Skip to content

NAS-Archivist design

Recovered from workstation Scratch on 2026-08-27. Catalog status in catalog/tools.md is Operating. This document is the design the tool was registered from. Logs do not live in Scratch; operator workstation logs stay off-tree.

NAS-Archivist Design & Implementation Plan

Status: Design Phase (Blocked by Bead requirement)
Author: NAS-Archivist persona
Date: 2026-08-10
Authority: Bluefly Engineering Standard, AGENTS.md

Executive Summary

NAS-Archivist is a governed agent and CLI tool that stewards the Synology NAS as the authoritative repository store. It audits Git estate health, verifies backups independently, enables safe repository reconciliation, and prevents destructive mutations through explicit governance gates.

Core mission: NAS = authoritative storage. Never hide, discard, or destroy work.

Problem Statement

Current state: - NAS stores canonical project repositories but lacks stewardship - No systematic audit of Git estate (clean/dirty/ahead/behind/diverged states) - No verification of Hyper Backup snapshots or BTRFS recovery integrity - Manual Git operations risk losing uncommitted work - No audit trail for repository mutations

Required capabilities: 1. Inventory NAS shares without exposing private contents 2. Classify Git repositories by state (CLEAN, BEHIND, AHEAD, DIRTY, DETACHED, DIVERGED) 3. Safely fetch without auto-merge 4. Fast-forward BEHIND repos only with explicit approval 5. Verify snapshots/backups independently of Git 6. Create worktrees in canonical location for isolated work 7. Generate eight-field execution receipts for all operations 8. Block destructive operations and report blockers

Architecture

Components

1. CLI Commands (extend blu-cli)

Path: /Volumes/AgentPlatform/Applications/__BLU/blu-cli/src/commands/nas.ts

Commands: - blu nas shares list — enumerate shares - blu nas repos audit [--detail] — classify all repositories - blu nas repos fetch [--all] — fetch all remotes - blu nas repos reconcile <path> [--approve-ff] — fast-forward single repo - blu nas worktree create <path> <branch> — create isolated worktree - blu nas backup verify [--snapshot <date>] — verify backup integrity - blu nas receipt show <id> — emit execution receipt

2. Agent Definition (OSSA v0.4)

Path: Canonical agent source (TBD: BluTown or platform-agents)

apiVersion: ossa/v0.4
kind: Agent
metadata:
  name: nas-archivist
  version: "1.0.0"
  description: NAS repository steward and backup verifier
spec:
  role: NAS repository maintenance and governance authority
  capabilities:
    - name: share_inventory
      description: List NAS shares without exposing private contents
    - name: git_estate_audit
      description: Classify repositories by state (CLEAN/BEHIND/AHEAD/DIRTY/DETACHED/DIVERGED)
    - name: safe_fetch
      description: Fetch remotes without auto-merge or push
    - name: reconciliation
      description: Fast-forward BEHIND repositories with explicit approval
    - name: backup_verification
      description: Verify Hyper Backup snapshots and BTRFS recovery
    - name: worktree_management
      description: Create isolated worktrees in canonical location
    - name: governance_receipts
      description: Emit eight-field execution receipts

3. Skill Definition

Path: Engineering-Standard/tools/nas-archivist/skill.md

Teaches agent to: - Use blu nas commands - Interpret state classifications - Apply Bluefly governance model - Generate execution receipts - Stop on blockers

4. Automation (workstation scheduler)

Path: ~/.config/launchd/com.bluefly.nas-archivist.plist

Runs daily NAS audit + backup verification: - 0200 UTC: full Git estate audit - 0400 UTC: backup snapshot verification - Never auto-pushes or auto-merges - Logs off-tree on the operator workstation (not Scratch, not the Git tree)

5. Documentation

Locations: - Engineering-Standard/catalog/tools.md — register NAS-Archivist as a tool - Engineering-Standard/reference/NAS-Operations.md — operational procedures - Engineering-Standard/infrastructure/NAS-Governance.md — governance model

NAS Share Inventory

Current Mounts (verified 2026-08-10)

Share Mount Authority Type Status
AgentPlatform /Volumes/AgentPlatform Engineering Platform Docs, runtime, config ACTIVE
web /Volumes/web Web Authority Published web apps ACTIVE
web_packages /Volumes/web_packages Package Registry npm, packages ACTIVE
docker /Volumes/docker Docker Authority Services, volumes ACTIVE
chat /Volumes/chat Chat Authority Chat services ACTIVE
home /Volumes/home User Authority User homes ACTIVE
homes /Volumes/homes User Authority User homes ACTIVE
MinimServer /Volumes/MinimServer Media Authority DLNA media ACTIVE
PlexMediaServer /Volumes/PlexMediaServer Media Authority Plex media ACTIVE
TimeMachine /Volumes/TimeMachine Backup Authority Time Machine ACTIVE

AgentPlatform Directory Boundaries

Directory Authority Type Git Repos?
Applications/ Git Source Code YES
BluTown/ Gas Town Runtime YES (monitoring)
BluCity-Docs/ Docs Repo Documentation YES
Evidence/ Evidence Engine Generated NO
Config/ IaC Configuration NO
Knowledge/ Knowledge Base Curated Docs YES (wiki)
Scratch/ None Disposable NO
.agents/ Agent Runtime Runtime State YES (OSSA)
.beads/ Beads Runtime State NO
.openclaw/ OpenClaw Runtime State YES (skills)
.codegraph/ CodeGraph Runtime State NO

Git Estate Audit Results (Preliminary)

Audit Date: 2026-08-10 22:03 UTC
Scope: /Volumes/AgentPlatform, max depth 6
Status: RUNNING (background task)

Key repositories found: - BluCity-Docs — Git ACTIVE - BluTown — Git ACTIVE - Knowledge (wiki) — Git ACTIVE - Applications/__BLU/* — Git ACTIVE (multiple) - .agents/gitlab-ossa-agent — Git ACTIVE (Kubernetes agent, NOT platform agent) - .openclaw/skills — Git ACTIVE

Full audit results: see NAS-AUDIT.md and nas-audit-2026-08-05.md.

Blockers & Authority

Governance Gate (gt-policy)

Local BluCity-Docs clone enforces: - Requirement: Active Bead for all mutations (Edit/Write/Bash) - Status: NO ACTIVE BEAD - Resolution: Create Bead via blu work create (requires Oracle connectivity) - Workaround: None available (gt-policy fails closed)

Infrastructure Gaps

  1. Cedar policy gate bootstrap — setGateBaseDir() not called
  2. Dolt server unreachable — Oracle Beads database not local
  3. buildkit not installed — migrating to blu-cli anyway

Impact: Cannot create Beads locally; must work through Oracle or disable gate.

Implementation Phases

Phase 1: Read-Only Audit & Design ✓

  • [x] NAS share inventory
  • [x] Git estate classification (audit in progress)
  • [x] Backup verification planning
  • [x] Governance model definition
  • [x] Skill definition
  • [x] Agent design

Status: COMPLETE (pending audit results)

Phase 2: Tool Registration & Documentation

  • [x] Register NAS-Archivist in Engineering-Standard/catalog/tools.md
  • [x] Land skill at Engineering-Standard/tools/nas-archivist/skill.md
  • [ ] Create operations documentation
  • [ ] Update catalog/capabilities if needed

Phase 3: CLI Implementation (BLOCKED)

  • [ ] Extend blu-cli with nas command group
  • [ ] Implement shares list, repos audit, repos fetch, repos reconcile
  • [ ] Implement worktree create, backup verify, receipt show
  • [ ] Add 1Password Connect auth (no .op-env, no token copies)
  • [ ] Add off-tree operator logging

Blocker: Requires Bead + git mutations + TypeScript build

Phase 4: Automation & Scheduling (BLOCKED)

  • [ ] Create launchd plist for workstation scheduler
  • [ ] Wire daily audit + backup verification
  • [ ] Configure log rotation
  • [ ] Test one complete cycle

Blocker: Requires phase 2 & 3 complete

Phase 5: Verification & Runtime Projection (BLOCKED)

  • [ ] Test read-only audit against real NAS
  • [ ] Test backup verification
  • [ ] Test worktree creation
  • [ ] Generate OSSA runtime projection
  • [ ] Register in OpenClaw

Blocker: Requires phase 2 & 3 complete

Governance Model

State Machine (Repositories)

CLEAN ↔ BEHIND (safe to FF)
  ↓
DIRTY ──→ BLOCKER (must resolve)
  ↓
DETACHED ──→ BLOCKER (must resolve)
  ↓
DIVERGED ──→ BLOCKER (must resolve)
  ↓
AHEAD ──→ BLOCKER (must approve push)
  ↓
NO_UPSTREAM ──→ BLOCKER (must configure)

Execution Boundary

NAS-Archivist CAN: - Observe and classify - Fetch remotes - Create worktrees - Verify backups - Stop on blockers - Generate receipts

NAS-Archivist CANNOT: - Commit or push - Merge conflicts - Delete branches - Discard work - Authorize mutations beyond scope

Next Steps (Requires Bead)

  1. Create Bead 

    blu work create "Platform: NAS-Archivist agent and governance tooling"

  2. Update Catalog

  3. Add to Engineering-Standard/catalog/tools.md

  4. Create agent registration in OSSA

  5. Implement CLI

  6. Extend blu-cli with nas commands

  7. TypeScript + Zod validation

  8. Create Skill

  9. This directory: Engineering-Standard/tools/nas-archivist/skill.md

  10. Test & Deploy

  11. Read-only audit on real NAS
  12. Backup verification
  13. Scheduler installation
  14. Runtime projection

Evidence & Verification

This directory is the design home. Historical workstation audit dumps from 2026-08-10 were Scratch session files and are not re-homed here. Live NAS evidence: Engineering-Standard/catalog/NAS-AUDIT.md, ledger/verification/nas-audit-2026-08-05.md.

Terminal State

Current: Design and skill landed in this directory. CLI (blu nas) and scheduler remain planned.

Do not treat Scratch as the home for this tool.

Verification Checklist

  • [ ] NAS shares enumerated without private content exposure
  • [ ] Git repositories classified by state (audit complete)
  • [ ] Backup snapshots verified independently
  • [ ] Skill definition validates
  • [ ] Agent definition in canonical source
  • [ ] CLI commands implemented and tested
  • [ ] Automation scheduled and ran once
  • [ ] Eight-field receipts generated for all operations
  • [ ] No destructive operations performed
  • [ ] All blockers recorded and escalated
  • [ ] MR merged and CI passed
  • [ ] Runtime projection generated