# 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](#page3).

**Maintenance:** Update when new canonical trees are established or tree ownership changes. Drift detection daemon (see [Drift Detection Design](#page4)) monitors compliance weekly.

---

## Tree Ownership Table

One row per major tree. These are the **canonical locations** — creating parallel structures elsewhere violates the registry.

<table id="bkmrk-tree-purpose-owner-m"><thead><tr><th>Tree</th><th>Purpose</th><th>Owner</th><th>Migration target if violated</th></tr></thead><tbody><tr><td>`~/system/`</td><td>Orchestration runtime, daemons, tools, agents, specs, rules, hooks (git), schemas</td><td>John (orchestrator)</td><td>—</td></tr><tr><td>`~/ALAI/`</td><td>Company state — clients, brand, products, sales, legal, org, processes, pipelines, web-worktrees</td><td>ALAI (CEO)</td><td>—</td></tr><tr><td>`~/projects/`</td><td>Code repositories (libraries, internal tools, experiments)</td><td>Per repo (see BUILD-BLUEPRINT.md in each)</td><td>—</td></tr><tr><td>`~/companies/`</td><td>Per-company state (BasicConsulting AS, SnowIT, future entities)</td><td>Per company entity</td><td>—</td></tr><tr><td>`~/.claude/`</td><td>Claude Code harness (settings.json, hooks, agents, projects, memory, skills)</td><td>Anthropic Claude Code</td><td>DO NOT TOUCH (vendor-managed)</td></tr><tr><td>`~/Library/`</td><td>macOS system and vendor-managed application state</td><td>OS / app vendors</td><td>DO NOT TOUCH (OS-managed)</td></tr><tr><td>`~/aisystem/`</td><td>Canonical infra deploy workspace (Cloudflare Pages/DNS, BookStack, Vault, fleet configs)</td><td>John, Mehanik gate reads this path</td><td>—</td></tr><tr><td>`~/backups/`</td><td>Tar archives + offsite backup source (7-day + 30-day retention)</td><td>John</td><td>—</td></tr></tbody></table>

**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.**

<table id="bkmrk-dir-name-location-pu"><thead><tr><th>Dir Name</th><th>Location</th><th>Purpose</th><th>What NOT to do</th></tr></thead><tbody><tr><td>`infrastructure`</td><td>`~/ALAI/infrastructure/`</td><td>Cloud resources, VMs, network topology</td><td>Do NOT recreate `~/system/infrastructure/`</td></tr><tr><td>`internal`</td><td>`~/ALAI/internal/`</td><td>Internal company operations docs</td><td>Do NOT recreate `~/system/internal/`</td></tr><tr><td>`legal`</td><td>`~/ALAI/legal/`</td><td>Contracts, DPAs, corporate documents</td><td>Do NOT recreate `~/system/legal/`</td></tr><tr><td>`org`</td><td>`~/ALAI/org/`</td><td>Organizational structure, roles, policies</td><td>Do NOT recreate `~/system/org/`</td></tr><tr><td>`pipeline`</td><td>`~/ALAI/pipeline/`</td><td>Sales pipeline, lead tracking</td><td>Do NOT recreate `~/system/pipeline/`</td></tr><tr><td>`processes`</td><td>`~/ALAI/processes/`</td><td>Business processes, SOPs, operations</td><td>Do NOT recreate `~/system/processes/`</td></tr><tr><td>`products`</td><td>`~/ALAI/products/`</td><td>Product specifications, roadmaps</td><td>Do NOT recreate `~/system/products/`</td></tr><tr><td>`sales`</td><td>`~/ALAI/sales/`</td><td>Sales materials, proposals, decks</td><td>Do NOT recreate `~/system/sales/`</td></tr><tr><td>`web`</td><td>`~/ALAI/web-worktrees/`</td><td>Website repositories for ALAI brand properties</td><td>Do NOT recreate `~/system/web/`</td></tr></tbody></table>

**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.

<table id="bkmrk-pair-name-winner-oth"><thead><tr><th>Pair Name</th><th>Winner</th><th>Other Side Outcome</th><th>Tar Archive Path</th></tr></thead><tbody><tr><td>`agents`</td><td>`~/system/agents/` canonical</td><td>`~/ALAI/agents/` merged into system, then archived</td><td>`~/backups/anvil-fs-sweep-2026-05-07/alai-agents-merged.tar.gz`</td></tr><tr><td>`architecture`</td><td>**BOTH canonical, distinct purpose**</td><td>`~/ALAI/architecture/` renamed to `product-architecture/` (product specs, user-facing architecture)</td><td>N/A (rename, no archive)</td></tr><tr><td>`clients`</td><td>`~/ALAI/clients/` canonical</td><td>`~/system/clients/*` migrated to `~/ALAI/clients/<NAME>/overview.md`, then archived</td><td>`~/backups/anvil-fs-sweep-2026-05-07/system-clients-migrated.tar.gz`</td></tr><tr><td>`docs`</td><td>`~/system/docs/` canonical</td><td>`~/ALAI/docs/operations/` moved to `~/ALAI/processes/operations/`, then archived</td><td>`~/backups/anvil-fs-sweep-2026-05-07/alai-docs-operations-moved.tar.gz`</td></tr><tr><td>`services`</td><td>**BOTH canonical, distinct purpose**</td><td>`~/ALAI/services/` renamed to `service-catalog/` (client-facing service offerings vs system runtime services)</td><td>N/A (rename, no archive)</td></tr><tr><td>`templates`</td><td>`~/system/templates/` canonical</td><td>`~/ALAI/templates/` renamed to `doc-templates/` (business document templates, not code templates)</td><td>N/A (rename, no archive)</td></tr></tbody></table>

**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.

<table id="bkmrk-path-why-canonical-r"><thead><tr><th>Path</th><th>Why Canonical</th><th>Referenced By</th></tr></thead><tbody><tr><td>`~/aisystem/`</td><td>Mehanik infra gate workspace. CF Pages deployments, DNS configs, BookStack migrations read from here.</td><td>Mehanik Phase T, FlowForge deploy scripts</td></tr><tr><td>`~/system/security/`</td><td>Password-share tooling, client vault access scripts</td><td>`password-share.js`, `client-vault.js`</td></tr><tr><td>`~/system/schemas/`</td><td>JSON schemas for task markers, agent definitions</td><td>`mehanik-commit.js` reads `mehanik-marker.v1.json`</td></tr><tr><td>`~/system/hooks/`</td><td>**Git pre-commit/pre-publish hooks** (NOT Claude Code hooks — those live under `~/.claude/hooks/`)</td><td>Git repositories using ALAI pre-commit enforcement</td></tr></tbody></table>

**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.

<table id="bkmrk-file-scope-loads-whe"><thead><tr><th>File</th><th>Scope</th><th>Loads When</th><th>Purpose</th></tr></thead><tbody><tr><td>`~/.claude/CLAUDE.md`</td><td>User-global</td><td>**Always loaded** (all Claude Code sessions)</td><td>John's identity, ZAKONs, specialist routing, hard constraints</td></tr><tr><td>`~/CLAUDE.md`</td><td>Home directory project</td><td>CWD = `/Users/makinja`</td><td>Orchestration mode guardrails, session boot protocol, routing one-liners</td></tr><tr><td>`~/system/CLAUDE.md`</td><td>System tree project</td><td>CWD inside `~/system/`</td><td>System-specific build/deploy rules, tool usage</td></tr><tr><td>`~/ALAI/CLAUDE.md`</td><td>ALAI tree project</td><td>CWD inside `~/ALAI/`</td><td>ALAI brand guidelines, client-facing constraints</td></tr></tbody></table>

**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](#page4)) 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:**

1. `~/ALAI/web-worktrees/ucenje-v2` — Is this personal scholarly project misplaced under commercial brand tree?
2. `~/projects/` vs `~/companies/` boundary — What criteria determine if a repo goes in projects/ vs companies/?
3. `~/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](#page3) Consequences section.

---

## Drift Detection

**Automated Monitoring:** Weekly daemon (see [Drift Detection Design](#page4))

**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](#page3)
- **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](#page4)
- **ALAI Filesystem Handbook:** `~/system/HANDBOOK.md` (on-demand tool grammar)