Context
Operator-directed (@tobiu) — the first concrete artifact of the v13.2 architecture program (#14304), and its cheapest high-leverage piece. The Brain's structure is a stale 2/10 snapshot (per #14304); the cheapest first heal is a generated current-map: always-accurate (vs rotted hand-docs — DreamPipeline.md cites ai/daemons/DreamService.mjs, a path that does not exist), standalone-useful for onboarding (the "where's the code?" reaction), and the baseline both the migration (Lane 1) and the immune-system lint (Lane 2) consume.
The operator's bar: we will not get the architecture 100% right; 80–90% + continuous iteration is the win — which is why this tooling matters. It makes the iteration cheap and visible: generate → enforce → iterate.
Precedent (V-B-A'd): #12247 (CLOSED) already lints learn/tree.json against the learn/ folder tree — the same generate-vs-declared shape, proven. This applies it to ai/.
The Problem
The folder structure is invisible — no one scans it before placing files (the V-B-A'd root cause of the rot: diagnostics/recovery/Dream all misplaced because no one looked). Hand-maintained structure docs rot. There is no always-accurate, machine-readable map of "what's where."
The Architectural Reality
- The map is generated from the live tree (always accurate), never hand-written.
- It is a pure generator — emit the current structure; the intended-vs-actual comparison is a downstream consumer (the Lane-2 lint + the enforcement).
- Placement: it is operator/CI tooling about
ai/, so buildScripts/ai/ (next to the other build tools) — NOT inside ai/ (the inspector must not live inside the inspected).
- CLI convention V-B-A'd:
commander is already a package.json dep + the buildScripts/ standard (build/all, create/addConfig) — use it; no new dep.
- Dual-use: Lane 1 (migration before/after baseline) + Lane 2 (immune-system generator-half).
The Fix
A commander CLI under buildScripts/ai/ that walks a configurable root (default ai/) and emits deterministic, sorted JSON of the folder structure:
- Default: per-folder
{ path, fileCount }.
--files: include file names.--loc: include lines-per-file — prefer code-LOC (excluding comments) per the cohesion-budget principle (counts catch folder-bloat > 7; LOC catches file-bloat like the 2,476-line services/graph "helper"; together = the cohesion/size budget).- Output sorted/stable → committable + cleanly diffable (the diff is the drift signal on a PR).
Designed-for-enforcement (the trajectory — not this ticket's deliverable)
This tool is built to be enforced downstream (operator's vision): a "what-belongs-where" sanity-check at ticket-work time + a placement check at PR-review time, both consuming this JSON + the forthcoming intended-SSOT (Lane 0 / #14304). Those enforcement integrations are follow-on tickets (they require the intended-SSOT to exist); this ticket delivers the standalone generator they will consume.
Acceptance Criteria
Out of Scope
- The intended-SSOT / declared placement map (Lane 0 / #14304).
- The enforcement integrations (ticket-work sanity-check, PR-review placement-check) — follow-on; they need the intended-SSOT.
- The actual migration (Lane 1) — this is its baseline tool, not the migration.
Avoided Traps
- Hand-written map: rejected — it rots (
DreamPipeline.md proves it). Generate it.
- Non-deterministic output: rejected — kills the diff-as-drift-signal; sort everything.
- Baking in the intended-comparison: rejected — keep it a pure generator (one job, composable); the lint is a separate consumer.
- Placing it in
ai/: rejected — it is tooling about ai/, so buildScripts/ai/.
Related
#14304 (v13.2 architecture epic — parent) · #14305 (Lane-2 immune-system sandbox — the consumer) · #14302 (Lane-1 structure sandbox — the migration baseline) · #12247 (the learn/tree.json lint precedent) · learn/agentos/DreamPipeline.md (the rotted-doc anchor).
Live latest-open sweep: checked at creation; no equivalent structure-tooling ticket exists (#12247 precedent is CLOSED + scoped to learn/).
Origin Session ID: f4454a29-afc5-4897-a66c-a8c2c9460d55
Handoff Retrieval Hints: "folder-structure map generator committable JSON buildScripts/ai"; "architecture current-map counts loc deterministic diff drift-signal".
Authored by Grace (@neo-opus-grace, Claude Opus 4.8). Operator-directed; Euclid-buildable.
Context
Operator-directed (@tobiu) — the first concrete artifact of the v13.2 architecture program (#14304), and its cheapest high-leverage piece. The Brain's structure is a stale 2/10 snapshot (per #14304); the cheapest first heal is a generated current-map: always-accurate (vs rotted hand-docs —
DreamPipeline.mdcitesai/daemons/DreamService.mjs, a path that does not exist), standalone-useful for onboarding (the "where's the code?" reaction), and the baseline both the migration (Lane 1) and the immune-system lint (Lane 2) consume.The operator's bar: we will not get the architecture 100% right; 80–90% + continuous iteration is the win — which is why this tooling matters. It makes the iteration cheap and visible: generate → enforce → iterate.
Precedent (V-B-A'd): #12247 (CLOSED) already lints
learn/tree.jsonagainst thelearn/folder tree — the same generate-vs-declared shape, proven. This applies it toai/.The Problem
The folder structure is invisible — no one scans it before placing files (the V-B-A'd root cause of the rot: diagnostics/recovery/Dream all misplaced because no one looked). Hand-maintained structure docs rot. There is no always-accurate, machine-readable map of "what's where."
The Architectural Reality
ai/, sobuildScripts/ai/(next to the other build tools) — NOT insideai/(the inspector must not live inside the inspected).commanderis already apackage.jsondep + thebuildScripts/standard (build/all, create/addConfig) — use it; no new dep.The Fix
A
commanderCLI underbuildScripts/ai/that walks a configurable root (defaultai/) and emits deterministic, sorted JSON of the folder structure:{ path, fileCount }.--files: include file names.--loc: include lines-per-file — prefer code-LOC (excluding comments) per the cohesion-budget principle (counts catch folder-bloat > 7; LOC catches file-bloat like the 2,476-lineservices/graph"helper"; together = the cohesion/size budget).Designed-for-enforcement (the trajectory — not this ticket's deliverable)
This tool is built to be enforced downstream (operator's vision): a "what-belongs-where" sanity-check at ticket-work time + a placement check at PR-review time, both consuming this JSON + the forthcoming intended-SSOT (Lane 0 / #14304). Those enforcement integrations are follow-on tickets (they require the intended-SSOT to exist); this ticket delivers the standalone generator they will consume.
Acceptance Criteria
commanderCLI underbuildScripts/ai/(per the existingbuildScripts/convention) emits deterministic, sorted JSON of the folder structure (per-folder{path, fileCount}) for a configurable root (defaultai/).--filesincludes file names;--locincludes LOC per file (prefer code-LOC excluding comments).ai:structure-mapnpm script + a one-line usage doc.Out of Scope
Avoided Traps
DreamPipeline.mdproves it). Generate it.ai/: rejected — it is tooling aboutai/, sobuildScripts/ai/.Related
#14304 (v13.2 architecture epic — parent) · #14305 (Lane-2 immune-system sandbox — the consumer) · #14302 (Lane-1 structure sandbox — the migration baseline) · #12247 (the
learn/tree.jsonlint precedent) ·learn/agentos/DreamPipeline.md(the rotted-doc anchor).Live latest-open sweep: checked at creation; no equivalent structure-tooling ticket exists (#12247 precedent is CLOSED + scoped to
learn/).Origin Session ID: f4454a29-afc5-4897-a66c-a8c2c9460d55
Handoff Retrieval Hints: "folder-structure map generator committable JSON buildScripts/ai"; "architecture current-map counts loc deterministic diff drift-signal".
Authored by Grace (@neo-opus-grace, Claude Opus 4.8). Operator-directed; Euclid-buildable.