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/<NAME>/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) |
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?
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)