Skip to main content

ADR-022: Architectural Decision

ADR-022: ANVIL Filesystem Canonical Map and Cleanup

Status: Accepted (2026-05-07)

Deciders: Alem Basic (CEO) via Phase 2 gap report

Consulted: Petter Graff (architect), FlowForge (devops), Proveo (validator)

Date: 2026-05-07

Context

ALAI's ANVIL (Mac Studio orchestration host) filesystem had accumulated significant structural drift since late 2025.

Phase 1 Findings (Read-Only Audit)

Scope: 5 read-only audit tasks (MCs #99644, #99639, #99642, #99646, #99648)

Inventory:

  • 62,838 total paths under /Users/makinja/
  • 158 LaunchAgent daemons (managed via ~/Library/LaunchAgents/)
  • 91 child directories under ~/system/
  • 31 child directories under ~/ALAI/

Split-Brain Detection:

  • 15 directory names existed under both ~/system/ and ~/ALAI/ simultaneously
  • Examples: agents/, architecture/, clients/, docs/, services/, templates/, infrastructure/, legal/, products/, sales/, web/, org/, pipeline/, processes/, internal/

Broken References:

  • 137 cited-but-missing documentation references (BookStack pages, specs, runbooks referenced in code/configs but not found on disk or in BookStack)
  • 30 broken daemon references (LaunchAgents pointing to non-existent scripts or logs)

PHANTOM Daemons:

  • 3 daemons marked KeepAlive=true but failing on every restart cycle:
    • mlx-router (boot failure — IP binding issue)
    • 2 others flagged in Phase 1

Phase 1.6 Content-Peek

Extended audit (MC #99662) to read file contents in suspicious dirs, revealing:

  • 4 surprise-canonical paths (~/aisystem/, ~/system/security/, ~/system/schemas/, ~/system/hooks/) — live code reads from these, cannot delete
  • Merge conflict detection in split-brain pairs

Phase 2 Gap Report

Analysis (MC #99655) synthesized 10 CEO decision items:

  1. BLOCKER: com.john.mlx-router.plist KeepAlive=true causing boot hang every reboot
  2. Tree ownership table (which tree is canonical for what purpose)
  3. Split-brain resolution strategy (6 pairs required case-by-case decision)
  4. Archive strategy (7-day hot backup vs 30-day cold archive)
  5. Broken reference cleanup (delete stale daemon plists, update docs)
  6. Surprise-canonical upgrade (protect 4 paths from deletion)
  7. Storage reclamation estimate (~9GB after cleanup)
  8. CLAUDE.md scope-comment enforcement (4-way scope: global, home, system, ALAI)
  9. Documentation deliverables (canonical registry, ADR, drift detection design)
  10. Drift detection daemon (weekly monitoring to prevent re-introduction)

Root Causes:

  • No central canonical path registry → agents recreated dirs arbitrarily
  • No tree ownership model → business docs under ~/system/, runtime configs under ~/ALAI/
  • No drift detection → split-brain accumulated over 4+ months undetected

Decision

Execute ANVIL Filesystem Sweep in 3 phases, with 10 sub-decisions consolidated under this ADR.

Sub-Decision 1: Resolve BLOCKER

Unload com.john.mlx-router.plist (KeepAlive=true causing boot hang). Defer router fix to separate MC. Boot must succeed before bulk cleanup.

Implementation: MC #99669 + 3 technical debt MCs (#99665 router fix, #99666 IP binding root cause, #99667 KeepAlive policy review)

Sub-Decision 2: Establish Tree Ownership Model

Define canonical trees with clear ownership (see Canonical Registry for full table).

Sub-Decision 3: Split-Brain Resolution (6 Pairs)

Both canonical, distinct purpose (rename non-conflicting):

  • architecture → System: ADRs, technical decisions. ALAI: renamed to product-architecture/ (product specs)
  • services → System: daemon definitions. ALAI: renamed to service-catalog/ (client-facing offerings)
  • templates → System: code scaffolding. ALAI: renamed to doc-templates/ (business docs)

One canonical, migrate other (9 ALAI-wins + 3 system-wins):

  • ALAI canonical: clients/, infrastructure/, internal/, legal/, org/, pipeline/, processes/, products/, sales/, web/
  • System canonical: agents/, docs/

Implementation: MCs #99672 (bulk cleanup), #99695 + #99699 (split-brain merges/renames)

Sub-Decision 4: Archive Strategy

  • Hot backup: 7-day retention at ~/backups/anvil-fs-sweep-2026-05-07/
  • Cold archive: 30-day tar.gz offsite (B2 bucket via existing daemon)
  • What to archive: All deleted paths, all split-brain losing sides, all deprecated tools

Sub-Decision 5: Broken Reference Cleanup

  • Delete 30 broken daemon plists (scripts no longer exist)
  • Mark 137 missing doc refs as TODO in code comments (BookStack publish or delete comment)
  • Update specialist-mapping.json if any agent dirs deleted

Implementation: Part of MC #99672 bulk cleanup

Sub-Decision 6: Upgrade 4 Surprise-Canonical Paths

Discovered via content-peek (MC #99662). See Canonical Registry for details on:

  • ~/aisystem/ — Mehanik infra gate, CF deployments
  • ~/system/security/ — password-share.js, client-vault.js
  • ~/system/schemas/ — mehanik-commit.js reads JSON schemas
  • ~/system/hooks/ — Git pre-commit/pre-publish (NOT Claude Code hooks)

Status: Protected from deletion. Added to canonical registry.

Sub-Decision 7: Storage Reclamation

Estimate: ~9GB freed after archiving:

  • Deprecated tools: ~2GB
  • Duplicate split-brain content: ~4GB
  • Stale logs/caches: ~3GB

Sub-Decision 8: CLAUDE.md Scope Enforcement

4-way scope model (see Canonical Registry for full table).

Sub-Decision 9: Documentation Deliverables

Create 3 artifacts (this ADR is one of them):

  1. Canonical Registry (see page) — ITIL CMDB / Backstage-style catalog
  2. This ADR — Architectural decision record
  3. Drift Detection Design (see page) — spec for future daemon build

Sub-Decision 10: Drift Detection Daemon (Future Build)

Design deliverable: See Drift Detection Design

Purpose: Weekly check to prevent split-brain re-introduction

Status: Design done, build deferred to separate MC (not part of this sweep)

Consequences

Positive

  1. BLOCKER resolved — ANVIL boots without hang (mlx-router unloaded)
  2. ~9GB storage reclaimed — Deprecated/duplicate content archived
  3. Canonical registry established — Future agents have authoritative "where does X belong" source
  4. Tree ownership clarified — Orchestration runtime (system) vs company state (ALAI) now explicit
  5. Split-brain eliminated — 15 dir name conflicts resolved via merge/rename/migrate
  6. Broken references cleaned — 30 phantom daemons deleted, 137 missing docs flagged
  7. 4 surprise-canonical paths protected — Prevents accidental deletion of live-referenced dirs
  8. CLAUDE.md scope model documented — 4-way load context now explicit
  9. ADR record created — Future context for "why is the tree structured this way"
  10. Drift detection designed — Automated prevention of chaos re-introduction

Negative

  1. Some content judgment deferred — 3 split-brain pairs (architecture, services, templates) required CEO call for "both canonical" edge case
  2. Organizational audit deferred — This sweep is mechanical (what/where), not semantic (should it be there). Example: ~/ALAI/web-worktrees/ucenje-v2 (personal scholarly project under commercial brand tree?) — deferred to separate workstream
  3. 3 TD MCs created — mlx-router fix, IP binding root cause, KeepAlive policy review — technical debt carried forward
  4. 137 missing doc refs — Flagged as TODOs, not resolved (requires BookStack authoring or code comment deletion)
  5. Daemon fleet audit incomplete — 158 daemons inventoried, 30 broken refs deleted, but full health audit (success rate, error patterns) deferred

Neutral

  1. 4 surprise-canonical paths upgraded — Content-peek revealed live references; upgraded to protected status (good outcome, but unplanned scope expansion)
  2. 5 scope-creep items excluded — ~/system/drafts/, company-prompts/, exo-env/, hook-native/, minions.db — flagged in gap report but NOT touched in this sweep. Pending separate org audit (semantic-fit review)

Implementation

Phase 1: Read-Only Audit (5 Tasks)

Completed MCs:

  • #99644: Inventory ~/system/ children (91 dirs)
  • #99639: Inventory ~/ALAI/ children (31 dirs)
  • #99642: Detect split-brain dir names (15 pairs)
  • #99646: Audit daemon fleet (158 LaunchAgents, 30 broken refs)
  • #99648: Catalog cited-but-missing docs (137 refs)

Phase 1.6: Content-Peek (Extension)

Completed MC: #99662

Phase 2: Gap Report

Completed MC: #99655 — Synthesize findings into 10 CEO decision items

Phase 3 Wave 1-A: BLOCKER Unload

Completed MC: #99669 — Unload com.john.mlx-router.plist KeepAlive=true

Technical Debt MCs Created: #99665, #99666, #99667

Phase 3 Wave 1-B: Bulk Cleanup

Completed MC: #99672 — Archive deprecated tools, delete broken daemon plists, reclaim ~9GB

Phase 3 Wave 1-C: Split-Brain Resolution

Completed MCs: #99695, #99699 — Merge/rename/migrate 6 split-brain pairs

Phase 3 Wave 2: Documentation

This Deliverable (MC #99637 child):

Phase 3 Wave 3: Validation & Publication

MC #99703: E2E validation (Proveo) — see evidence

Current: BookStack publication (MC TBD)

References

Authoritative Documents

Mission Control Tasks

Parent: MC #99637 (ANVIL-FS Sweep — PARENT)

Phase 1-3 MCs: See Implementation section above for complete list of 16 MCs.

  • ADR-012: AWS App Runner canonical for Drop (anti-phantom drift reference)
  • ADR-021: Bilko blueprint-aligned cleanup (parallel effort, same timeframe)

Context Documents

  • ~/.claude/CLAUDE.md — John's identity, ZAKONs
  • ~/CLAUDE.md — Home orchestration guardrails
  • ~/system/CLAUDE.md — System-specific rules
  • ~/ALAI/CLAUDE.md — Brand guidelines

No comments to display

Back to top