Drift Detection Design ANVIL Filesystem Drift Detection Daemon — Design Specification Purpose: Automated weekly detection of canonical path registry violations, CLAUDE.md scope drift, and filesystem chaos re-introduction. Prevents split-brain recurrence after ANVIL FS Sweep ( ADR-022 ). Status: Design complete, build phase deferred to separate MC Owner: John (orchestrator) Last Updated: 2026-05-07 (ANVIL FS Sweep Phase 3 Wave 2) 1. Problem Statement ANVIL FS Sweep (MC #99637, ADR-022 ) resolved 15 split-brain dir names, archived deprecated content, and established a canonical path registry . However, without automated monitoring , agents can unknowingly recreate chaos: Example Drift Scenarios: Agent sees "no ~/system/clients/ " → creates it, not knowing ~/ALAI/clients/ is canonical Scope-tied CLAUDE.md files edited without updating scope-comment headers → 4-way load context breaks Surprise-canonical paths ( ~/aisystem/ , ~/system/security/ ) accidentally deleted → live code breaks Organizational drift (personal project reappears under ~/ALAI/web-worktrees/ ) goes unnoticed Root Cause: No feedback loop. One-time cleanup is insufficient without ongoing compliance checks. 2. Design Goals Primary Goals Detect split-brain re-introduction — Weekly check that archived paths stay deleted Enforce CLAUDE.md scope hygiene — Each file's header matches its load context Protect surprise-canonical paths — Detect if live-referenced dirs disappear Monitor specialist mapping integrity — specialist-mapping.json refs match actual dirs Flag org-fit violations — Warn (not error) on semantic-fit issues like personal projects under commercial trees Non-Goals Not a fixer — Daemon detects, does not auto-fix. Alerts HiveMind, creates MC, escalates to John. Not a full FS audit — Does not scan all 62,838 paths weekly. Targets known drift patterns only. Not real-time — Runs weekly, not on every file change (too expensive). 3. Architecture Trigger Mechanism LaunchAgent: com.john.anvil-fs-drift-detection.plist Schedule: Every 7 days (Sunday 03:00 local time) Run Condition: ANVIL host only (not on remote VMs) Timeout: 10 minutes max (if check hangs, daemon aborts and alerts) Script Location Path: ~/system/daemons/scripts/anvil-fs-drift-detection.sh Language: Bash (for filesystem ops, jq for JSON parsing) Dependencies: jq, grep, curl, node Output: Success (no drift): Log to ~/system/logs/anvil-fs-drift-detection.log , no alert Drift detected: HiveMind alert + create H-priority MC + log 4. Drift Detection Checks Each check runs sequentially. If ANY check fails, daemon immediately alerts and continues to remaining checks (fail-fast on alerting, but complete all checks for full report). Check 1: CLAUDE.md Scope Headers Purpose: Each of 4 CLAUDE.md files MUST have a scope-comment header matching its load context. Expected Outcome: All 4 files have scope headers. If missing/wrong, flag as drift. Rationale: Without scope headers, editors may accidentally write global rules into project-specific files (or vice versa). Check 2: Specialist Mapping Integrity Purpose: ~/system/agents/specialist-mapping.json references to agent definition files MUST point to actual existing dirs/files. Expected Outcome: All referenced agent files exist. If any ref is broken, flag as drift. Rationale: Broken refs cause agent routing failures (John tries to dispatch to non-existent agent). Check 3: MUST NOT Recreate List Purpose: Paths archived during ANVIL FS Sweep MUST NOT reappear on disk. If they do, split-brain is re-introduced. List of paths: ~/system/archive ~/system/deprecated ~/system/deployments ~/system/plans ~/system/clients ~/system/infrastructure ~/system/internal ~/system/legal ~/system/org ~/system/pipeline ~/system/processes ~/system/products ~/system/sales ~/system/web Expected Outcome: None of these paths exist. If any exists, flag as split-brain re-introduction. Rationale: Prevents silent chaos. If agent recreates ~/system/clients/ , future agents may write to it instead of canonical ~/ALAI/clients/ . Check 4: Surprise-Canonical Paths Still Exist Purpose: 4 paths upgraded to canonical during Phase 1.6 content-peek MUST still exist (live code reads from them). Paths: ~/aisystem ~/system/security ~/system/schemas ~/system/hooks Expected Outcome: All 4 dirs exist. If any missing, flag as regression (live scripts will fail). Rationale: These paths were not initially canonical but are read by live tools (Mehanik, password-share.js, etc.). Deletion breaks runtime. Check 5: Tree Ownership Violations (Warning-Level) Purpose: Detect semantic-fit issues like personal projects under commercial brand tree. This is organizational audit territory (deferred in ADR-022 Consequences), so flag as WARNING not ERROR. Expected Outcome: Logs warnings (not errors). Does NOT block or alert HiveMind. Just logs for human review. Rationale: Org-fit is subjective (requires CEO judgment). Daemon flags suspicious patterns but doesn't escalate as hard failure. 5. Alerting & Escalation Success Case (No Drift) Log Entry: [2026-05-14 03:00:01] ANVIL FS Drift Detection: All checks PASS. No drift detected. No HiveMind alert, no MC creation. Drift Detected (Any Check Fails) Immediate Actions: Log detailed findings to ~/system/logs/anvil-fs-drift-detection.log POST HiveMind alert (category: filesystem-drift , priority: high ) Create MC via node ~/system/tools/mc.js add with title: [DRIFT] ANVIL FS canonical violation detected — see drift log YYYY-MM-DD Set MC priority H , owner: john , category: system Warning Case (Org-Fit Issues) Log Entry (not alert): [2026-05-14 03:00:10] [WARNING] Personal project ~/ALAI/web-worktrees/ucenje-v2 under commercial tree (org audit pending) No HiveMind alert, no MC. Human reviews log weekly. 6. LaunchAgent Configuration File Path: ~/Library/LaunchAgents/com.john.anvil-fs-drift-detection.plist Key Configuration: NOT KeepAlive (learned from mlx-router BLOCKER in ADR-022 ) Runs once weekly, not on every boot 10-minute timeout prevents infinite hangs 7. Success Criteria Daemon is considered successful if: Runs weekly without hang (10-minute timeout not hit) Logs output to stdout/stderr paths Detects known drift patterns (unit test: temporarily create ~/system/clients/ , verify alert) Creates MC on drift (verify mc.js call succeeds) Does not false-positive (clean system → no alert) Warnings logged, not alerted (org-fit issues don't create MCs) 8. Testing Plan (Pre-Build) Before building the daemon, validate design assumptions with 6 unit tests: Scope Header Detection: Remove scope header from ~/.claude/CLAUDE.md , verify drift flagged MUST NOT Recreate Detection: Create ~/system/clients/ , verify drift flagged Surprise-Canonical Regression: Rename ~/system/security/ , verify drift flagged Specialist Mapping Broken Ref: Add fake ref to specialist-mapping.json , verify drift flagged Full Run (No Drift): Clean system, verify log shows "All checks PASS", no MC created Full Run (With Drift): Introduce 2 drift scenarios, verify log shows both, MC created with H priority 9. Dependencies System Requirements OS: macOS (LaunchAgent-based) Shell: Bash 4.0+ (for arrays, set -euo pipefail ) Tools: jq, grep, curl, node ALAI Infrastructure mc.js: Mission Control CLI ( node ~/system/tools/mc.js ) HiveMind API: (endpoint TBD — currently TODO in script) Canonical Registry: Canonical Registry page (authoritative MUST NOT recreate list) Related Systems ZAKON #28 Max Depth Boundary: Drift detection MC creation does NOT count toward emergent-spawn depth (it's a daemon, not agent-spawned) Daemon Fleet Watchdog: Monitors drift daemon's exit code (if non-zero, flags as silent failure) 10. Future Enhancements (Out of Scope for Initial Build) Real-Time inotify Monitoring: Use fswatch or inotify for instant detection (higher CPU cost) Auto-Fix Mode: Add --fix flag to auto-delete violated paths (risky, requires CEO approval) Trend Analysis: Store drift events in SQLite DB, generate weekly trend report Integration with Archive-First Scan: Merge into single weekly "filesystem health" daemon 11. Build Phase MC Stub Title: [DAEMON] Build ANVIL FS drift detection daemon (weekly canonical registry enforcement) Deliverables: Bash script: ~/system/daemons/scripts/anvil-fs-drift-detection.sh (5 checks + alerting) LaunchAgent plist: ~/Library/LaunchAgents/com.john.anvil-fs-drift-detection.plist (weekly Sunday 03:00) Unit tests: All 6 test cases PASS Integration: mc.js call verified, HiveMind POST stubbed (TODO endpoint) Daemon fleet watchdog: Add drift daemon to monitored list Acceptance Criteria: All 5 checks implemented LaunchAgent loaded: launchctl load ~/Library/LaunchAgents/com.john.anvil-fs-drift-detection.plist Manual run PASS on clean system Manual run ALERT on intentional drift (create ~/system/clients/ , verify MC created) Logs to ~/system/logs/anvil-fs-drift-detection.log Proveo validation: Unit tests 1-6 PASS Dependencies: ADR-022 (canonical registry established), mc.js (Mission Control CLI working) Effort: ~2 hours (script + plist + tests) Priority: M (not H — BLOCKER resolved, this is preventive maintenance) Owner: FlowForge (or John if simple Bash task) 12. References Authoritative Documents Canonical Registry: Canonical Registry page ADR-022: ADR-022 page Related Systems Daemon Fleet Watchdog: ~/system/daemons/scripts/daemon-fleet-watchdog.sh (monitors drift daemon health) Archive-First Scan: com.alai.archive-first-scan LaunchAgent (overlapping concern — candidate for merge) Prior Art MC #10043: Reform Execution Backlog (drift detection was surfaced here)