Canonical Registry Canonical Path Registry Purpose: Industry-standard ITIL CMDB / Spotify Backstage pattern. Catalog of canonical paths, their owners, scope, and anti-drift rules. This is the authoritative source for "where does X belong" questions in ALAI's filesystem hierarchy. Last Updated: 2026-05-07 (ANVIL FS Sweep Phase 3 Wave 2) Source of Truth: This page. Also mirrored at ~/system/specs/canonical-registry.md . Cross-referenced by ADR-022 . Maintenance: Update when new canonical trees are established or tree ownership changes. Drift detection daemon (see Drift Detection Design ) monitors compliance weekly. Tree Ownership Table One row per major tree. These are the canonical locations — creating parallel structures elsewhere violates the registry. Tree Purpose Owner Migration target if violated ~/system/ Orchestration runtime, daemons, tools, agents, specs, rules, hooks (git), schemas John (orchestrator) — ~/ALAI/ Company state — clients, brand, products, sales, legal, org, processes, pipelines, web-worktrees ALAI (CEO) — ~/projects/ Code repositories (libraries, internal tools, experiments) Per repo (see BUILD-BLUEPRINT.md in each) — ~/companies/ Per-company state (BasicConsulting AS, SnowIT, future entities) Per company entity — ~/.claude/ Claude Code harness (settings.json, hooks, agents, projects, memory, skills) Anthropic Claude Code DO NOT TOUCH (vendor-managed) ~/Library/ macOS system and vendor-managed application state OS / app vendors DO NOT TOUCH (OS-managed) ~/aisystem/ Canonical infra deploy workspace (Cloudflare Pages/DNS, BookStack, Vault, fleet configs) John, Mehanik gate reads this path — ~/backups/ Tar archives + offsite backup source (7-day + 30-day retention) John — Anti-Pattern: Creating ~/system/clients/ when ~/ALAI/clients/ is canonical = split-brain. See "9 Already-Resolved Split-Brain Dirs" below. 9 Already-Resolved Split-Brain Dirs (ALAI-only, no system mirror needed) These directories existed under both ~/system/ and ~/ALAI/ . During ANVIL FS Sweep Phase 1, all were resolved: ALAI wins, system side archived. Dir Name Location Purpose What NOT to do infrastructure ~/ALAI/infrastructure/ Cloud resources, VMs, network topology Do NOT recreate ~/system/infrastructure/ internal ~/ALAI/internal/ Internal company operations docs Do NOT recreate ~/system/internal/ legal ~/ALAI/legal/ Contracts, DPAs, corporate documents Do NOT recreate ~/system/legal/ org ~/ALAI/org/ Organizational structure, roles, policies Do NOT recreate ~/system/org/ pipeline ~/ALAI/pipeline/ Sales pipeline, lead tracking Do NOT recreate ~/system/pipeline/ processes ~/ALAI/processes/ Business processes, SOPs, operations Do NOT recreate ~/system/processes/ products ~/ALAI/products/ Product specifications, roadmaps Do NOT recreate ~/system/products/ sales ~/ALAI/sales/ Sales materials, proposals, decks Do NOT recreate ~/system/sales/ web ~/ALAI/web-worktrees/ Website repositories for ALAI brand properties Do NOT recreate ~/system/web/ Rationale: These are business/company concerns, not orchestration runtime. They belong under ALAI tree. Archive Location: Archived content from system side moved to ~/backups/anvil-fs-sweep-2026-05-07/system-mirror-archived/ 6 Active Split-Brain — RESOLVED 2026-05-07 These dir names existed under both trees. Each required CEO/architect decision on which side wins or if both are legitimate. Pair Name Winner Other Side Outcome Tar Archive Path agents ~/system/agents/ canonical ~/ALAI/agents/ merged into system, then archived ~/backups/anvil-fs-sweep-2026-05-07/alai-agents-merged.tar.gz architecture BOTH canonical, distinct purpose ~/ALAI/architecture/ renamed to product-architecture/ (product specs, user-facing architecture) N/A (rename, no archive) clients ~/ALAI/clients/ canonical ~/system/clients/* migrated to ~/ALAI/clients//overview.md , then archived ~/backups/anvil-fs-sweep-2026-05-07/system-clients-migrated.tar.gz docs ~/system/docs/ canonical ~/ALAI/docs/operations/ moved to ~/ALAI/processes/operations/ , then archived ~/backups/anvil-fs-sweep-2026-05-07/alai-docs-operations-moved.tar.gz services BOTH canonical, distinct purpose ~/ALAI/services/ renamed to service-catalog/ (client-facing service offerings vs system runtime services) N/A (rename, no archive) templates ~/system/templates/ canonical ~/ALAI/templates/ renamed to doc-templates/ (business document templates, not code templates) N/A (rename, no archive) Decision Authority: CEO via Phase 2 gap report Decision #3. Rationale Notes: architecture : System side holds ADRs (Michael Nygard format), technical decisions. ALAI side holds product/business architecture (C4 models for clients). services : System side holds daemon/service definitions. ALAI side holds service catalog (AI Services, DevOps retainer offerings). templates : System side holds code scaffolding, agent prompt templates. ALAI side holds business docs (proposal templates, contract templates). 4 Surprise-Canonical Paths Discovered during Phase 1.6 content-peek. These paths were not initially mapped as canonical, but live code/scripts read from them . Upgrading to canonical status prevents accidental deletion. Path Why Canonical Referenced By ~/aisystem/ Mehanik infra gate workspace. CF Pages deployments, DNS configs, BookStack migrations read from here. Mehanik Phase T, FlowForge deploy scripts ~/system/security/ Password-share tooling, client vault access scripts password-share.js , client-vault.js ~/system/schemas/ JSON schemas for task markers, agent definitions mehanik-commit.js reads mehanik-marker.v1.json ~/system/hooks/ Git pre-commit/pre-publish hooks (NOT Claude Code hooks — those live under ~/.claude/hooks/ ) Git repositories using ALAI pre-commit enforcement Critical Distinction: ~/system/hooks/ ≠ ~/.claude/hooks/ ~/system/hooks/ = Git hooks (pre-commit, pre-publish) for repos ~/.claude/hooks/ = Claude Code lifecycle hooks (PreToolUse, PostToolUse, etc.) Status: These 4 paths are now protected. Do NOT archive or delete. 4-Way CLAUDE.md Scope Rules CLAUDE.md files exist at 4 different scope levels . Each loads based on current working directory (CWD). Understanding this prevents accidental override or scope pollution. File Scope Loads When Purpose ~/.claude/CLAUDE.md User-global Always loaded (all Claude Code sessions) John's identity, ZAKONs, specialist routing, hard constraints ~/CLAUDE.md Home directory project CWD = /Users/makinja Orchestration mode guardrails, session boot protocol, routing one-liners ~/system/CLAUDE.md System tree project CWD inside ~/system/ System-specific build/deploy rules, tool usage ~/ALAI/CLAUDE.md ALAI tree project CWD inside ~/ALAI/ ALAI brand guidelines, client-facing constraints Load Order: Global → CWD-specific. If CWD = ~/system/tools/ , both ~/.claude/CLAUDE.md and ~/system/CLAUDE.md are loaded. Anti-Pattern: Writing orchestration rules into ~/system/CLAUDE.md when they should be in ~/.claude/CLAUDE.md (global) or ~/CLAUDE.md (home project). Maintenance: Each file MUST have a scope-comment header matching its load context. Drift detection daemon checks this weekly. What MUST NOT Recreate These paths were archived during ANVIL FS Sweep . Recreating them silently reintroduces filesystem chaos and split-brain drift. Archived from ~/system/ (now under ~/backups/anvil-fs-sweep-2026-05-07/): ~/system/archive/ (meta-archive — already an archive of archives, moved to backup) ~/system/deprecated/ (old scripts, superseded tools) ~/system/deployments/ (stale deployment configs, superseded by aisystem/) ~/system/plans/ (old project plans, superseded by specs/) ~/system/clients/ (migrated to ~/ALAI/clients/) ~/system/infrastructure/ (migrated to ~/ALAI/infrastructure/) ~/system/internal/ (migrated to ~/ALAI/internal/) ~/system/legal/ (migrated to ~/ALAI/legal/) ~/system/org/ (migrated to ~/ALAI/org/) ~/system/pipeline/ (migrated to ~/ALAI/pipeline/) ~/system/processes/ (migrated to ~/ALAI/processes/) ~/system/products/ (migrated to ~/ALAI/products/) ~/system/sales/ (migrated to ~/ALAI/sales/) ~/system/web/ (migrated to ~/ALAI/web-worktrees/) Why This Matters: An agent seeing "no ~/system/clients/" might auto-create it without checking this registry. That recreates the split-brain. Enforcement: Drift detection daemon (see design spec ) checks weekly that none of these paths exist. Pending Organizational Audit This registry is mechanical — it documents "what is where NOW" after cleanup. It does NOT answer "does this BELONG here semantically?" Open Questions for Future Workstream: ~/ALAI/web-worktrees/ucenje-v2 — Is this personal scholarly project misplaced under commercial brand tree? ~/projects/ vs ~/companies/ boundary — What criteria determine if a repo goes in projects/ vs companies/? ~/aisystem/ vs ~/system/ — Should infra workspace eventually merge into system tree? Decision Authority: CEO (Alem Basic) Status: Deferred to separate workstream. Flagged in ADR-022 Consequences section. Drift Detection Automated Monitoring: Weekly daemon (see Drift Detection Design ) Manual Checks: Before creating new top-level ~/ directory → consult this registry Before moving large directory trees → update this registry, create ADR When agent reports "path not found" → check if it's in "What MUST NOT Recreate" list Enforcement Owner: John (orchestrator) Escalation: If canonical path violation detected → create H-priority MC, tag with canonical-violation References Decision Record: ADR-022 Sweep Plan: MC #99637 (parent), child MCs #99644, #99639, #99642, #99646, #99648, #99662, #99655, #99669, #99672, #99695, #99699, #99701, #99703 Drift Detection Design: Drift Detection Design ALAI Filesystem Handbook: ~/system/HANDBOOK.md (on-demand tool grammar)