Skip to content

ADR-0006: Mac Laptop Purge and NAS-Centric Engineering Layout

Engineering contract (binding for this ADR)

# Contract Tag
1 Owner: Bluefly (BluCity-Docs — planning and evidence only; no execution in this ADR) INFERRED
2 Upstream owns tools; Bluefly owns config + migration procedure — no forks INFERRED
3 Docs/procedure replace custom scripts for v1 (Execution Constitution: evidence collection must not produce software v1) INFERRED
4 Improves reproducibility: Mac → stateless dev client; NAS → durable mirrors + sandbox INFERRED
5 Must NOT strand work on one laptop — migration phases define what moves when INFERRED
6 Reduces long-term ownership by centralizing mirrors and sandbox runtime on NAS INFERRED

Status

Accepted by operator directive on 2026-07-22 — the repository and workspace locations below are authoritative for dev-client / NAS custodian layout. Destructive purge or migration remains gated by RX-MIG-001 and RX-MIG-002.

Evolution (2026-08-27): Gas City production execution converged on Oracle-only runtime with Tailscale operator access. Rig paths are /opt/bluefly/blucity and /opt/bluefly/rigs/<rig>. This ADR's Mac/NAS phases remain valid for dev-client demotion; Oracle binding is governed by oracle-canonical-architecture and blucity CI (gc-site-bind).

Problem

OBSERVED: The M4 Mac accumulates operational drift that conflicts with a multi-node engineering layout:

  • Dirty git worktrees across Sites/blueflyio/ and WORKING_DEMOs/* (OBSERVED — BluCity-Docs git status 2026-07-07: 531 modified, 71 untracked, 2245 deleted in convergence branch)
  • Mac ~/gt empty or non-authoritative for hq-* fleet work (OBSERVED — workspace policy: Oracle ~/gt is execution SoR; Mac empty ~/gt is not canonical Gas Town)
  • Path sprawl: duplicate BluTown checkouts (BluTown, BluTownM4), flat clones under Sites/blueflyio/WORKING_DEMOs/, symlink-dependent Drupal module trees (OBSERVED — workspace AGENTS.md)
  • QMD breakage when corpus paths assume Mac-local layout (OBSERVED — operator report; UNKNOWN extent until RX-MIG-001)
  • Mac BluTown .beads quarantined read-only (OBSERVED — workspace policy: QUARANTINE_READ_ONLY; duplicate hq-* fleet is projection only)

INFERRED: Treating the Mac as long-term SoR for mirrors, sandbox runtime, or town-level beads creates single-laptop failure mode and onboarding friction (see ADR-0003 portability).

Principle (logical authorities — not paths)

Authority Role Host realization (2026-07-07) Tag
Dev client Stateless: Cursor, DDEV client, git, SSH, Tailscale M4 Mac (mac-m4.tailcf98b3.ts.net) RETRIEVED — domains.yaml; OBSERVED — workspace policy
Engineering appliance Git mirrors, sandbox compose, sandbox runtime state, docs clone Synology DS224+ NAS (blueflynas.tailcf98b3.ts.net) INFERRED — operator architecture; UNKNOWN — full NAS path inventory until RX-MIG-002
Production execution Gas Town / beads authority for hq-* convoys Oracle (bluefly-platform.tailcf98b3.ts.net, ~/gt) RETRIEVED — upstream-lawbooks.md; NOT concluded as sole beads SoR for all scopes — see Beads implication

RETRIEVED: Architecture names logical authorities; runtime resolves them (ADR-0003 portability).

Repository and workspace layout

ACCEPTED: GitLab is source authority. NAS application repositories back registered Mac worktrees:

GitLab                                              # source of truth
/Volumes/AgentPlatform/Applications                 # Mac-mounted NAS repository storage
worktrees            # registered Mac worktrees
Scratch              # temporary and scratch files

Documentation and work artifacts never belong in ~/.claude, ~/.codex, or another hidden home directory.

OBSERVED: NAS is not a Homebrew host — package management differs from Mac (OBSERVED — operator session; validate on NAS during RX-MIG-002).

Phases (procedure only — no execution)

Phase 0 — Inventory receipt

Goal: Read-only catalog of what exists on Mac vs NAS vs Oracle before any demotion or purge.

Step Action Output Gate
0.1 Run RX-MIG-001 on Mac Mac inventory receipt PASS required
0.2 Cross-reference Zero-Assumption Convergence Audit wave inventories Pointer to ZACA packets (C1–D4) INFERRED — no duplicate file audit
0.3 Record Oracle execution boundary Gas Town / OpenClaw receipts under Evidence/Capability/runtime/ UNKNOWN — stubs mostly placeholder

Explicit NOT in Phase 0: delete, git clean, move, or re-point symlinks.

Phase 1 — NAS parity

Goal: NAS holds substitutes for Mac-local SoR candidates before Mac demotion.

Step Action Output Gate
1.1 Verify repositories under /Volumes/AgentPlatform/Applications/ Repository manifest RX-MIG-002 row per repo
1.2 Verify the blucity-docs repository backs a registered Mac worktree Repository path + git rev-parse HEAD RX-MIG-002
1.3 Sandbox compose under sandbox/ + state under data/sandbox/ Sandbox receipt RX-BD-001 / RX-BD-002 on NAS sandbox only
1.4 Beads learn/validate RX-BD-001, RX-BD-002 PASS before shared Beads server claim

INFERRED: NAS = learn/validate sandbox only until RX-BD-001 and RX-BD-002 pass — NOT shared Beads server yet (UP-BD-021).

Phase 2 — Mac demotion

Goal: Stop treating Mac paths as SoR; quarantine without deleting.

Step Action Output Gate
2.1 Document Mac paths still referenced by docs, hooks, or CI Demotion manifest RX-MIG-001 delta
2.2 Quarantine Mac ~/gt — break-glass only, not daily SoR Quarantine receipt OBSERVED — policy already denies Mac mutators via gt-mac-guard
2.3 Quarantine Mac BluTown .beads — read-only projection Quarantine receipt OBSERVED — QUARANTINE_READ_ONLY
2.4 Re-point operator workflows to NAS mirrors + Oracle execution Procedure updates in Playbooks UNKNOWN — per-tool

Explicit NOT in Phase 2: purge, rm, git clean, force-checkout, stash.

Phase 3 — Purge candidates (gated)

Goal: Explicit list of Mac-local artifacts eligible for removal only after NAS/Oracle substitute passes RX-MIG-002.

Candidate class Example (Mac) Substitute authority Purge gate
Standalone Mac clones Repositories outside worktrees/ NAS Applications repository + registered Mac worktree RX-MIG-002 PASS + git rev-parse match
Stale worktree copies Extra BluTown checkout not in active use NAS repository + registered Mac worktree Checkpoint commit + RX-MIG-002
Local sandbox runtime state DDEV DBs, compose volumes used only for throwaway validate NAS data/sandbox/ RX-MIG-002 + operator sign-off
Hollow rig shells Mac ~/gt rig dirs recreated by mistake Oracle ~/gt NOT purge — quarantine only until Oracle verified
QMD corpus duplicates Mac-only index paths NAS or git-backed corpus RX-MIG-002 + QMD query PASS
OBSERVED drift artifacts .auto-memory/, stale node_modules in abandoned worktrees N/A — reproducible from git RX-MIG-001 documents + clean worktree policy

Purge gate (each item): RX-MIG-002 proves NAS (or Oracle) replacement exists and operator confirms no uncheckpointed work in that path.

Phase 4 — Thin client profile

Goal: Define what MUST remain on Mac after migration.

Must remain Rationale Tag
SSH keys / 1Password CLI session Auth to GitLab, Oracle, NAS, Tailscale INFERRED
Cursor + governed hooks Primary dev UI OBSERVED
DDEV client (validation substrate) ContextControl and Drupal proof — not production SoR RETRIEVED — workspace policy
git + worktrees for active lanes Thin checkout; mirrors on NAS INFERRED
Tailscale Reach NAS, Oracle, phone ops RETRIEVED — domains.yaml
op run / env inheritance pattern Single auth at session start RETRIEVED — AGENTS.md

INFERRED: Mac should not host town-level beads writes, production OpenClaw gateway, or authoritative Gas Town convoy state.

Explicit NOT purge yet

Item Reason Tag
Oracle execution (~/gt, OpenClaw, production stacks) Production SoR — separate IaC/deploy ADRs RETRIEVED
1Password secrets and .secrets/ op-env references Auth plane — never duplicated to NAS plaintext INFERRED
Active dirty worktrees without checkpoint commit Stranding risk — violates contract §5 INFERRED
Drupal custom module symlinks under ContextControl Binding rule — symlinks resolve only to registered repositories under worktrees/ RETRIEVED — workspace policy
NAS Applications/ until RX-MIG-002 proves repository freshness Premature purge loses only copy INFERRED

Beads implication

RETRIEVED: Developer-scoped repos use embedded Beads + Dolt remote on GitLab; Git holds config, Dolt holds operational work (ADR-0007 operational work SoR).

INFERRED: Town-level beads (hq-* on Oracle) stay on Oracle until:

  1. ADR-0007 operational work SoR reaches Accepted, and
  2. RX-BD-002 passes on NAS sandbox.

UNKNOWN: Whether NAS ever becomes shared Beads server vs remaining learn/validate only.

Decision

Accepted: GitLab is source authority; /Volumes/AgentPlatform/Applications holds NAS repositories that back worktrees under worktrees; temporary work belongs under Scratch.

No purge or destructive migration is authorized until the migration receipts pass. Oracle remains production execution for Gas Town hq-* until the operational-work ADR concludes otherwise.

Consequences

References