@rasensio/aidlc-content 1.50.0 → 1.52.0

package/docs/index.yaml

@@ -0,0 +1,115 @@
+# Manifest for the explanation pages in packages/content/docs/ — the single
+# declaration site. They ship inside @rasensio/aidlc-content and are read from the
+# installed package by `aidlc explain`; no project ever holds a copy
+# (docs-unreachable-from-installed-projects).
+#
+# Four claims live here as data rather than as prose, because a test can compare
+# data and cannot read prose: which pages exist, what code each one is about,
+# which CLI commands each one covers, and which broken-looking things are
+# deliberate. Guards are in packages/cli/test/docs-topics.test.ts.
+#
+# Schema (capability-docs/design.md, "Interfaces"):
+#   boundary          prose stating the pages-versus-knowledge-graph split
+#   entries[]         one per file in this directory
+#     id              short slug, unique
+#     kind            index | topic
+#     file            filename in this directory, must exist
+#     title           topic only
+#     source          topic only; the code this page is about, must exist on disk
+#     commands        topic only; top-level CLI commands this page covers
+#   undocumented[]    commands deliberately covered by no page, each with a reason
+#   historical_paths[] paths named on purpose that do not resolve, each with a reason
+
+boundary: >-
+  These pages and the knowledge graph are split by QUESTION, not by audience — both
+  serve agents as well as people. The knowledge graph (.aidlc/knowledge/, surfaced into
+  CLAUDE.md by `aidlc knowledge context`) answers where a thing is and what shape it
+  has: terse, indexed, loaded into every prompt. These pages (packages/content/docs/,
+  read with `aidlc explain`) answer why a thing
+  exists, what breaks without it, and how to use it: prose, read on demand. If a page
+  here restates a fact the knowledge graph already carries, that is the duplication this
+  split exists to prevent — link to the code instead. No page documents the contents of
+  the knowledge graph itself, which is why no topic's `source` points into
+  .aidlc/knowledge/.
+
+entries:
+  - id: readme
+    kind: index
+    file: README.md
+
+  - id: lifecycle
+    kind: topic
+    title: The lifecycle
+    file: lifecycle.md
+    source: packages/cli/src/core
+    commands: [init, start, continue, status, transition, gate, menu, amend, templates, spec, cross-check]
+
+  - id: state-and-concurrency
+    kind: topic
+    title: State, claims and concurrent work
+    file: state-and-concurrency.md
+    source: packages/cli/src/concurrency
+    commands: [claim, release]
+
+  - id: roadmap
+    kind: topic
+    title: The roadmap
+    file: roadmap.md
+    source: packages/content/skills/04-roadmap.md
+    commands: [roadmap, autopilot]
+
+  - id: reviews-and-guidance
+    kind: topic
+    title: Reviews, guidance and the constitution
+    file: reviews-and-guidance.md
+    source: packages/cli/src/review
+    commands: [review, constitution]
+
+  - id: cost-tracking
+    kind: topic
+    title: Cost tracking
+    file: cost-tracking.md
+    source: packages/cli/src/cost
+    commands: [cost]
+
+  - id: metrics
+    kind: topic
+    title: Metrics
+    file: metrics.md
+    source: packages/cli/src/metrics
+    commands: [metrics]
+
+  - id: knowledge-graph
+    kind: topic
+    title: The knowledge graph
+    file: knowledge-graph.md
+    source: packages/cli/src/knowledge
+    commands: [knowledge, discover]
+
+  - id: skills-and-platforms
+    kind: topic
+    title: Skills and platforms
+    file: skills-and-platforms.md
+    source: packages/cli/src/compile
+    commands: [add, update, docs, explain]
+
+  - id: hygiene-and-compliance
+    kind: topic
+    title: Repo hygiene and compliance
+    file: hygiene-and-compliance.md
+    source: packages/cli/src/doctor
+    commands: [doctor, compliance]
+
+# Empty on purpose: every top-level command is claimed by a page above. The
+# checker's allowlist branch is exercised on synthetic input in the test rather
+# than by leaving a real command undocumented to keep a code path warm.
+undocumented: []
+
+historical_paths:
+  - path: packages/web
+    reason: >-
+      Deleted at the website cutover (nextjs-website-revamp, T27). Named in
+      knowledge-graph.md and hygiene-and-compliance.md as the worked example behind the
+      `knowledge-stale-sources` check: 15 graph entities described it for 17 days, and
+      neither page can make that point without writing the path that no longer resolves.
+      The entries were removed by stale-graph-entries; the story is what stays.

package/docs/knowledge-graph.md

@@ -0,0 +1,121 @@
+# The knowledge graph
+
+## Why this exists
+
+An agent starting a session knows nothing about your codebase. Left to itself it will re-explore —
+grepping, opening files, reconstructing the same picture the last session built and discarded. That is
+slow, and it is charged per token.
+
+The knowledge graph is persistent memory for that problem. Entities (modules, decisions, conventions,
+dependencies, debt, endpoints) with relationships between them, stored as YAML and indexed for
+full-text search. `aidlc knowledge context` compiles a summary of it into `CLAUDE.md`, so the facts
+arrive in the prompt without anyone querying for them.
+
+It is deliberately **terse**. Each entry is a compressed paragraph, because it competes for prompt
+space with the actual task. That compression is also its limit, and the reason the pages in this folder
+exist alongside it — see the boundary below.
+
+**What breaks without it:** every session pays the discovery cost again, and two sessions reach
+different conclusions about the same code.
+
+## How to use it
+
+```
+aidlc discover
+aidlc knowledge query cost
+aidlc knowledge get <id>
+aidlc knowledge graph <id>
+aidlc knowledge add --type decision --id <slug> --name "<title>" --description "<why>"
+aidlc knowledge relate <from> <to> --type <kind>
+aidlc knowledge context --scope phase --phase design
+```
+
+`discover` scans a codebase and seeds the graph — that is how a brownfield project starts. After that,
+record findings as you make them rather than at the end.
+
+To add several entities at once, pipe YAML documents (separated by `---`) to
+`aidlc knowledge add --stdin`. A `tags:` string there means what `--tags` means: comma-separated.
+**Every document is checked before any is written**, and a run that fails writes nothing. That rule
+exists because, before 1.40.1, the YAML was written before the index looked at it. A `tags: a,b,c`
+string was saved, then the command crashed with `entity.tags.join is not a function`. The natural
+retry merged into the saved record and turned the string into one tag per character. Four entities in
+this repo's own graph carried 11 to 17 single-letter tags each before anyone noticed.
+
+**Query before exploring.** That is the whole point: `aidlc knowledge query <term>` costs one command,
+and re-deriving the same fact costs a session.
+
+**Then check what it told you against the source.** This is the rule that matters most on this page.
+The graph is an index into the code, not an authority over it. An entry naming a component, a function
+or a registry is a pointer to open, and an entry written by an earlier instance may name something a
+later one renamed or deleted. A design built on a symbol that is not there produces code against an API
+nobody has, and nothing downstream catches it until implementation.
+
+`aidlc knowledge verify <id>` records that you checked. `aidlc knowledge update <id>` corrects an entry
+that no longer matches.
+
+That rule is not hypothetical here. For 17 days this graph carried **15 entities describing
+`@rasensio/aidlc-web`, a package deleted at the website cutover** — eight module entries plus seven
+dependencies sourced to its manifest. Its directory, `packages/web`, does not exist; the repo has
+`packages/cli`, `packages/content` and `packages/website`. `aidlc knowledge query "web"` answered
+with the deleted package before it answered with the real one. Nothing reported it, because a stale
+entry and a correct one are the same shape.
+
+They are no longer the same shape to `aidlc doctor`. The `knowledge-stale-sources` check resolves
+every entity's `source` against the disk and every relationship endpoint against the entity set, and
+names what does not resolve. It is **report tier**: it applies nothing, under any tier or flag. Of
+those 15 entities, 12 wanted deleting and 3 wanted their path corrected to a different manifest —
+indistinguishable from the data alone, so the remedy is a decision and `doctor` may not make it. See
+[Repo hygiene and compliance](hygiene-and-compliance.md).
+
+Two things that episode is worth remembering for. First, the two staleness signals that existed
+could not see it: `lastVerified` age flags most of a real graph, correct entries included, and the
+git-diff change signal goes quiet exactly when a directory is deleted, because a path that no longer
+exists stops appearing in diffs. Second, the entries were **auto-discovered at confidence 0.6**, so
+they lost the `CLAUDE.md` context budget to the hand-written 0.9 entries and never reached a prompt.
+That is the confidence ranking working — and it is also why nobody noticed for 17 days. A low-value
+fact that is wrong is still wrong; it just costs less per day.
+
+## The boundary against these pages
+
+Both surfaces are read by agents, so the split is by **question**, not audience:
+
+| | Answers | Shape | When it is read |
+|---|---|---|---|
+| Knowledge graph | Where is it? What shape is it? | Terse, indexed | Every prompt |
+| These pages | Why does it exist? What breaks without it? How do I use it? | Prose | On demand |
+
+A worked example of the difference. The graph records that `resolveSource` returns a `ResolveResult` of
+`ok` or `reason` rather than `null`. True, and useful for finding it. What it cannot afford to carry is
+*why*: a null could not distinguish "no transcript on disk" from "transcript found but no matching
+turns", and the bugfix instance `cost-claim-attribution` bought that distinction. An agent holding only
+the fact will simplify the type back to `null` and re-introduce the bug. An agent that read
+[cost-tracking.md](cost-tracking.md) will not.
+
+So: if something belongs in one line and answers *where*, it goes in the graph. If it needs a paragraph
+and answers *why*, it goes here. A page that restates a graph fact is the duplication the split exists
+to prevent — which is why no page here documents the graph's contents, and no topic's `source`
+points into `.aidlc/knowledge/`.
+
+## Where the code lives
+
+- `packages/cli/src/knowledge` — the engine. YAML files are the source of truth; a SQLite full-text
+  index sits behind a `KnowledgeIndex` interface for search. The index is derived and can be rebuilt.
+- `.aidlc/knowledge` — this project's own graph: `modules.yaml`, `decisions.yaml`,
+  `conventions.yaml`, `dependencies.yaml`, `debt.yaml`, `endpoints.yaml`, `relationships.yaml`, plus
+  the index database. Newer records sit one per file in a directory named for the type —
+  `decisions/<id>.yaml`, `relationships/<from>-<type>-<to>-<hash>.yaml` — and both layouts are read.
+
+Why one file per record: every instance used to append its decision to the end of `decisions.yaml`.
+Two branches that both append at the end conflict, so once one pull request merged, every other open
+one conflicted — and GitHub never runs the custom merge driver, so none of them could merge. On
+2026-10-02 that stalled a three-item autopilot run for two hours. Separate files make the conflict
+impossible rather than recoverable. The existing records were left where they are on purpose: moving
+them in one commit would itself conflict with every open branch. `aidlc knowledge compact` folds the
+record files back into the per-type files when one file is wanted.
+- `packages/cli/src/operational/knowledge.ts` — the operational hooks around it.
+- `packages/cli/src/discover` — the codebase scan behind `aidlc discover`.
+
+One implementation lesson worth carrying: a "preserve this unchanged" path that round-trips through a
+serializer does not preserve anything. Rebuilding the index must copy bytes, not re-emit parsed
+structures, or comment formatting and key order drift on every rebuild — 829 lines of diff versus 108
+on real data.

package/docs/lifecycle.md

@@ -0,0 +1,198 @@
+# The lifecycle
+
+## Why this exists
+
+Working with an AI agent on real software has a specific failure mode: the agent writes code
+immediately, the code is plausible, and nobody can tell afterwards what it was supposed to do. There
+is no record of the decision, so the next session re-decides it, differently.
+
+The lifecycle exists to put a paper trail in front of the code. An **instance** is one unit of work
+with its own folder under `.aidlc/state/`. It moves through **phases**, and each phase must produce a
+named document before the next one starts. Requirements before design, design before code, tests
+before release. That ordering is not ceremony — it is the only thing that makes a later question
+like "why is it built this way?" answerable at all.
+
+**What breaks without it:** the work still gets done, but each session starts from scratch. This
+project's own numbers make the case: every instance has left a folder of requirements, designs and
+retrospectives — 47 of them at the time of writing — and the reason anything in this repo can be
+traced back to a decision is that the document existed before the code did. Where the trail is missing — the knowledge graph's stale
+entries, for instance — nobody can tell whether a thing is wrong or merely old.
+
+The second reason is subtler. Phases give an agent a place to *stop*. Without a phase boundary, an
+agent asked to fix a typo will refactor the module, because there is no structural moment at which
+"that is enough" is the correct answer.
+
+## How to use it
+
+Set up a project once:
+
+```
+aidlc init
+```
+
+Then, per piece of work:
+
+```
+aidlc start quick-feature --name my-thing
+aidlc status
+aidlc continue
+aidlc transition my-thing
+```
+
+`start` creates the folder and a branch. `continue` resumes from the next incomplete step, loading
+only the context that step needs. `transition` evaluates the gates and advances the phase — it
+refuses if the phase's documents are not done, which is the point.
+
+**Templates** decide which phases apply. There are five, in `packages/content/templates`:
+
+| Template | Phases | Use it for |
+|---|---|---|
+| `micro-task` | implementation, testing | a typo, a version bump |
+| `bugfix` | reproduction first, then the usual | something is broken |
+| `quick-feature` | requirements → deployment | most features |
+| `full-feature` | adds ideation | you do not yet know what you are building |
+| `spike` | research question, no release | finding out whether something is possible |
+
+`aidlc templates` lists them; `aidlc templates show <name> --scope <scope>` prints each phase with
+the artifacts it requires. Use it before creating an instance by hand — an instance seeded with
+artifacts its template never asked for fails its gates on files nobody needs, and until this command
+existed the artifact names lived only inside `node_modules`.
+
+**Scope** is the other dial, and it is the one people get wrong. Scope is not how big or ambitious
+the work is — it is which phases run. `micro` starts at implementation, `standard` starts at
+requirements, `full` starts at ideation. A large change with a settled design is `standard`; a small
+change nobody has thought about is `full`.
+
+**Gates** are the checks between phases. `aidlc gate <instance> <phase>` runs one without advancing,
+which is what CI calls. It fails on any phase not yet marked complete, and `aidlc transition` is the
+step that marks it — so a gate run before the transition fails by design. When either command fails,
+its output ends with a numbered **Next steps** block: one action per kind of failure, with the real
+instance, phase and artifact names filled in. When the `CI` environment variable is set, `aidlc gate`
+words that block for a pipeline and names no command that changes lifecycle state. `--json` output
+carries no such block.
+
+Two gates are worth knowing because they block real work:
+
+- The **traceability gate** requires every active acceptance criterion in `requirements.md` to be
+  referenced by some test. Criteria are written `- AC-1: <text>`, and tests refer to them as
+  `<instance>/AC-1`. It has no override flag, deliberately — the one time a gate here had no bypass,
+  it forced the discovery that five "criteria" were release process steps rather than properties of
+  the software. The requirements skill asks for behaviours in one of four shapes —
+  `WHEN …, THE SYSTEM SHALL …`, `WHILE …`, `IF …, THEN …`, `WHERE …` — because each one names its
+  own test. The gate does not check the shape, on purpose: a performance budget or a docs change is
+  not a behaviour, and a check would force it into one. A bugfix's `requirements.md` also lists
+  *unchanged* behaviour as criteria, so the fix cannot quietly break its neighbour.
+- The **ownership gate** checks that the session transitioning a phase is the one that claimed it.
+  This one has an override, and the honest observation from the retrospectives is that having the
+  override meant it got waved through by reflex on every phase.
+
+`aidlc menu`, or bare `aidlc`, opens a picker of the common commands if you would rather not
+remember them.
+
+**When requirements move after their phase closed**, `aidlc amend <instance>` is the way back. The
+gates check that artifacts exist, not that they still agree with each other, so editing
+`requirements.md` after its phase completed leaves the phase `complete`, the design describing the old
+criterion, and every gate passing — silent drift.
+
+The protocol is: retire the criterion in place, issue its replacement with a fresh ID, then append an
+amendment section naming what changed and which phases it invalidated.
+
+```markdown
+## Amendment 1 — 2026-09-07, after the design review
+- **Retires:** AC-4, AC-9
+- **Issues:** AC-31
+- **Reopens:** design
+- **Reason:** the customer integration needs JSON as well as CSV
+```
+
+`aidlc amend <instance> --impact` is read-only and lists every task, test and artifact that still cites
+the retired criteria. It is deliberately advisory: it *suggests* phases and never chooses them, because
+the first design derived the reopen set from that walk and the result was degenerate —
+`requirements.md` always cites every retired criterion, so every amendment reopened the requirements
+phase. A destructive state write should not depend on a prose-scanning heuristic.
+
+Running `aidlc amend <instance>` reopens the phase named in `Reopens:` and every phase between it and
+the current one, setting each back to `in-progress`. That re-arms the gates that already exist — this
+added no new gate — and appends a `type: reopen` record so churn is visible in history rather than
+reading as a normal forward pass. It needs a live claim, prints every change before making it, requires
+`--confirm` from testing onwards, applies amendments in order, and is a stated no-op on a second run.
+A completed instance is refused outright: its change is new work.
+
+A correction confined to the current phase does not have to reopen anything. Write `Reopens: none`, or
+name the current phase: the amendment is recorded and no phase moves. That is checked, not taken on
+trust. The walk is the one input a refusal may read: `aidlc amend` refuses any reopen — `none` included —
+that would leave a completed phase still citing a retired criterion, names each such phase, and prints the
+`Reopens:` it would accept. `--impact` ends with the same verdict in one line. The walk still never
+chooses what is reopened; it can only stop a write, never cause one.
+
+**What the system does today** lives in `.aidlc/specs/`, one file per capability. Each instance's
+`requirements.md` describes a change; after enough of them, nobody can say what the system does without
+replaying all of them. The corpus is that replay, done once per instance instead of by every reader.
+
+A requirements author writes the change as a `## Spec delta` section — `ADDED`, `MODIFIED` and `REMOVED`
+blocks against named capabilities. A `MODIFIED` or `REMOVED` block carries `Base: <revision>`, the
+8-character hash `aidlc spec show <capability>` prints for the requirement it was written against.
+
+```markdown
+## Spec delta
+
+### MODIFIED cost-tracking: Phase windows
+Base: 3f2a9c1e
+The system attributes each usage record to the phase and turn open at its timestamp.
+```
+
+At the completion moment `aidlc transition` folds the delta in, stamps each requirement with the
+instance and date, and files the delta under `.aidlc/specs/archive/<date>-<instance>.md`. If another
+instance changed the same requirement first, its revision no longer matches the base: the fold stops,
+completion is not recorded, and nothing is written. That is the whole conflict rule — a requirement is
+never silently overwritten. `aidlc spec fold <instance> --dry-run` runs the same check any time before.
+An instance with no delta completes exactly as before; nothing was back-filled, so the corpus starts
+empty and grows.
+
+**Before code is written**, `aidlc cross-check <instance>` reads `requirements.md`, `design.md` and
+`tasks.md` side by side. `aidlc review` reads one artifact at a time, so a criterion design forgot, or a
+task nobody asked for, passes every review and turns up in the code. The check prints one line per gap,
+naming both artifacts and the criterion or task:
+
+```
+requirements.md AC-4 → tasks.md: no open or done task cites it
+tasks.md T7 → requirements.md: cites no criterion
+requirements.md AC-2 → design.md: not mentioned
+```
+
+It reads criteria and tasks with the parsers the gates use, so the two can never disagree about what a
+file says, and it prints the lines those parsers could not read. It writes nothing, changes no phase,
+exits 0 whatever it finds, and no gate runs it — the implementation skill offers it before the first
+task, and acting on a gap is a person's call: fix the open artifact, or amend a completed one.
+
+**One agent per task** is the other way to run implementation, where the platform has sub-agents
+(Claude Code today). Each task goes to an agent that starts fresh, so task 8 does not inherit tasks 1–7;
+a second agent that edits nothing reviews it, and the box is ticked only after that review passes. The
+reviewer is handed one fixed `git diff` listing every test or spec file that existed before the task
+and was modified, deleted or renamed — and fails each one the task did not ask to change. The listing
+is mechanical on purpose: the agent that wrote the code also used to be the one deciding the tests that
+define done were fine, and a loosened assertion looks like a pass from inside. It is asked once per
+instance and off by default, because it roughly doubles the agents. Tasks that may run at the same time
+carry `(wave: <n>)` in `tasks.md`; a wave must be a run of consecutive tasks, and a bad marker keeps
+the task and warns rather than dropping it from gate coverage. The whole loop is one rule file,
+`.aidlc/resources/rules/task-agents.md`, so a session that runs its tasks itself never reads it.
+
+## Where the code lives
+
+- `packages/cli/src/core` — templates, scope resolution, and the gate engine.
+  `template-resolver.ts` handles `extends:`; `gate.ts` evaluates phase criteria.
+- `packages/cli/src/state` — reading and writing the instance folders and `transitions.log`.
+- `packages/cli/src/traceability` — the acceptance-criteria parser and the test scanner behind the
+  traceability gate. The AC grammar is closed on purpose; near-misses warn rather than vanish.
+- `packages/cli/src/tasks` — the `tasks.md` breakdown parser, including the `(wave: <n>)` marker.
+- `packages/cli/src/change` — the amendment grammar, the read-only impact walk, and the `reopen`
+  transition. `parser.ts` is fence-aware and treats a wrapped bullet as one bullet, because the first
+  version truncated a wrapped `Retires:` list to half its ids and dropped three fields silently.
+- `packages/cli/src/spec` — the spec corpus: the capability-file parser, the delta parser, and the
+  fold. `planFold` computes every file before `applyFold` writes any, which is what makes a conflict
+  leave the corpus untouched.
+- `packages/cli/src/crosscheck` — `aidlc cross-check`, a pure comparison of one instance's three
+  planning artifacts. Nothing but its own command imports it, and a test keeps it that way.
+- `packages/cli/src/menu` — the interactive picker. It reads no lifecycle state by design, because
+  "what should I do next?" belongs to the skill, not the menu.
+- `packages/content/templates` — the five templates, as data.

package/docs/metrics.md

@@ -0,0 +1,67 @@
+# Metrics
+
+## Why this exists
+
+The lifecycle already records everything needed to answer whether the process is working: when each
+phase started and ended, which instances were bugfixes, which earlier instance each bugfix blames, and
+what each one cost. Metrics is the read-only roll-up over that, so nobody has to open 42 folders and
+count.
+
+The one number that justifies the module is **true cost**. A feature's own cost is what its sessions
+burned. Its true cost adds the bugfixes it caused. Read own cost and meta-features look cheap; read true
+cost and they do not. Cost tracking: $153.65 own, $219.78 true. The gap is a third, and it is exactly the
+gap that hides whether finishing work is generating more work than it retires.
+
+The second is **change failure rate** per template — the share of completed instances that some later
+bugfix names as its cause. It is computed from `caused_by` links that a human confirmed, never guessed,
+which is why the number means something.
+
+**What breaks without it:** you optimise the thing you can see. This project shipped eleven features in
+nine days and then spent five days on seven bugfixes, and the ratio flipped because most of what shipped
+were features that watch the lifecycle rather than serve a user. That pattern was invisible until it was
+counted.
+
+## How to use it
+
+```
+aidlc metrics
+aidlc metrics --json
+```
+
+Read-only and pure — it computes from existing state and writes nothing.
+
+Four families come out:
+
+**Completion moment.** Scope-aware, which is fiddlier than it sounds: for most templates an instance
+completes when its last applicable phase completes, but maintenance-terminal templates complete on
+maintenance *entry*, because maintenance is open-ended and would otherwise never finish.
+
+**Change failure rate per template.** Distinct completed instances named in some bugfix's `caused_by`,
+divided by completed instances.
+
+**Lead times**, per phase and per instance. Phase lead time pairs each `to: X` in `transitions.log`
+with the next `from: X`, summing re-entries, and falls back to the phase file when the log is
+incomplete. The fallback matters — a phase that was never transitioned through the CLI would otherwise
+read as zero, which is a bug this project shipped and then fixed.
+
+**True cost**, one level deep. Own cost plus the cost of bugfixes that blame this instance. One level,
+not transitive, because a bugfix caused by a bugfix is a chain whose attribution nobody can defend.
+Null when there is no ledger data — never zero-filled, for the reason given in
+[cost-tracking.md](cost-tracking.md).
+
+Two cautions when reading the output. The generated release posts snapshot these figures into their
+frontmatter at generation time, so a post's numbers are historical, not live. And `own_cost` is never
+written as `true_cost` — they are separate fields precisely because conflating them is the error the
+module exists to prevent.
+
+## Where the code lives
+
+- `packages/cli/src/metrics/report.ts` — `computeMetrics(projectRoot, config)`, the whole module. One
+  pure function, no writes, no network.
+- `packages/cli/src/commands/metrics.ts` — the command, including `--json`.
+- `packages/cli/src/state` — `transitions.log` and the phase files it reads.
+- `packages/cli/src/cost` — where the money half comes from.
+
+The inputs are the instance folders under `.aidlc/state/`, and `caused_by` in `instance.yaml` is the
+link that makes change failure rate and true cost possible. It is written only after a human confirms
+the candidate — an unconfirmed guess is left absent, and absent means unknown rather than none.

package/docs/reviews-and-guidance.md

@@ -0,0 +1,144 @@
+# Reviews, guidance and the constitution
+
+## Why this exists
+
+An agent that reviews its own work finds nothing. Not because it is dishonest — because the same
+reasoning that produced the artifact produces the review, so the blind spots are identical. Every
+mechanism on this page is a way of getting a second opinion into the process without a second human.
+
+Three of them, at three timescales:
+
+**Adversarial review** is per artifact. A separate session reads `requirements.md` or `design.md`
+cold and attacks it: ambiguities, contradictions, missing edge cases, untestable criteria, hidden
+assumptions, security gaps, scope creep. Findings land in `<artifact>.md.review.md` — the artifact's
+own extension, then the suffix — and a `critical` finding blocks the phase.
+
+The value is not theoretical. On one design here the review found that a guard intended to catch
+stale file paths would fail on the very page explaining stale file paths — the page has to name the
+deleted path in order to discuss it. That defect would have shipped and then been "fixed" by deleting
+the guard.
+
+**Guidance layers** are per project, and they accumulate. Each is a markdown file in
+`.aidlc/guidance/` registered in `index.yaml`. A layer added today applies to the next phase
+immediately — phases read the index at runtime rather than having guidance baked into them, so
+nothing needs recompiling.
+
+They split two ways, and the split is the answer to "they accumulate":
+
+- **Always-read** — every layer whose index entry does *not* say `on_demand: true`. A phase reads
+  these on entry, without being asked.
+- **On-demand** — a layer whose entry carries `on_demand: true`. Registered, active, current; read
+  only when a phase has a stated reason to.
+
+`lessons.md` is the on-demand one, and it is the reason the split exists. Appended at each
+retrospective, up to three entries per instance, it reached **88KB — 85% of every byte a session read
+before touching task work**, while the consolidation trigger sat at 25 sections and 90 days. At 23
+sections, 12 days after a consolidation, both triggers were still in the future and the file was
+already the largest thing resident. A third trigger now fires on **20KB**, which is the dimension that
+costs money.
+
+Its always-read counterpart is **`lessons-digest.md`**: a distillation, under 4KB, regenerated by the
+retrospective at consolidation, with what it *omits* confirmed edit by edit. The full corpus stays at
+`.aidlc/guidance/lessons.md` and the digest names that path, because distilling a safety mechanism is
+fine and silently dropping it is not.
+
+**The constitution** is per repo and rarely changes. It states what this repo is for and what it must
+never become, derived from a product vision document. Triage checks items against it, and an item
+that crosses a prohibition is the clearest `hold/` there is — naming the prohibition turns "not for
+us" into a reason the submitter can read.
+
+**What breaks without them:** work passes review because the reviewer was the author, the same defect
+recurs every few weeks with nobody noticing it is the same defect, and scope drifts one reasonable
+item at a time.
+
+## How to use it
+
+```
+aidlc review my-thing requirements.md
+aidlc constitution
+```
+
+`review` scaffolds the findings file with a placeholder; an agent then performs the actual review and
+overwrites it. Findings carry a severity (`critical`, `major`, `minor`), the section, the issue, a
+concrete suggestion, and a status. A finding without a suggestion is not actionable and should not be
+written.
+
+**The findings filename carries the artifact's extension twice, and that is deliberate.** The file
+for `requirements.md` is `requirements.md.review.md`. It looks like a typo. The gate looks artifacts
+up by the name the template declares, so `requirements.review.md` is a file the gate cannot see — and
+for three weeks that is exactly what happened: the command built its filename from the argument as
+typed, so typing `requirements` (the phase name, and what the review skill's own prose called the
+artifact) produced a file that was written, parsed, counted and summarised correctly and then reported
+as absent by the transition. Eleven findings files across six completed instances were sitting on disk
+having never counted toward the gate they were run for.
+
+Both spellings of the *argument* now work — `aidlc review my-thing requirements` and
+`aidlc review my-thing requirements.md` write the same file — because one module,
+`review/findings-naming.ts`, owns the mapping in both directions. Prefer the command over naming the
+file by hand. `aidlc doctor` renames any legacy file it finds.
+
+The reason both directions live in one module rather than the writer being "fixed": fixing only the
+writer leaves the already-written files dead, and fixing only the reader leaves two valid spellings
+forever. The reader resolves both because it strips the suffix and then canonicalizes, so the two
+spellings converge on one key and no call site has to know which it is looking at.
+
+Two further conventions worth copying:
+
+**Review `design.md` and `tasks.md` as separate findings files.** The skill can be read as folding
+task findings into the design's file, and doing that once blurred two real defects together — splitting
+by artifact forced findings about the breakdown apart from findings about the design.
+
+**State the dimensions you found nothing in.** A review that lists four findings and stops is
+indistinguishable from a review that only looked at four things. Writing "security: no issues, and
+here is why the section does not apply" is what makes the absence evidence.
+
+Guidance needs no command — drop a file in `.aidlc/guidance/` and add it to `index.yaml`. There is one
+rule that matters: **guidance is never inlined into a compiled skill.** Skills reference the layer;
+they do not copy it. A copy is a thing that drifts, and a drifted copy of a security rule is worse
+than no rule.
+
+That rule has a trap worth knowing before you register a small layer. A layer under 2KB *is* inlined
+when a skill names it in a `{{guidance:<name>}}` placeholder — the threshold exists so a multi-KB
+document becomes a pointer instead of bloating eighteen skill bodies. Set `always_pointer: true` on
+the entry to opt out whatever the size. `lessons-digest.md` does exactly that, and the flag is
+load-bearing rather than decorative: without it, the file the whole change exists to keep small would
+be copied into every emitted skill.
+
+`always_pointer` and `on_demand` answer different questions and are independent. `always_pointer` is
+about *rendering* — how a named layer is delivered into a skill body. `on_demand` is about *reading* —
+whether a phase opens the layer at all on entry. A layer may set either, both, or neither.
+
+The lessons file is capped at three new entries per retrospective, and follow-ups default to
+`dropped` — keeping one requires a stated reason. Both caps exist because finishing work reliably
+generates more work than it retires.
+
+## Where the code lives
+
+- `packages/cli/src/review` — `findings-parser.ts` parses the findings format that the phase gate
+  reads. The gate looks only at `*.review.md`, which is what lets compliance findings live in a
+  separate `*.compliance.md` file and stay advisory. `findings-naming.ts` is the single declaration
+  site for how an artifact name and a findings filename map to each other, in both directions; two
+  independent derivations of that key is the defect it exists to prevent, so its test asserts the
+  inverse property rather than a table of literals.
+- `packages/cli/src/commands/review.ts` — the scaffold generator, and the placeholder detection that
+  stops an unreviewed scaffold from counting as a review. Also the artifact allowlist: an argument the
+  instance's template does not declare is refused, because a typo used to scaffold a findings file no
+  gate would ever read.
+- `packages/cli/src/doctor/migrations/findings-filename.ts` — renames legacy findings files. Safe
+  tier, and it never opens the file. A collision (both spellings present for one artifact) is
+  *reported*, never resolved: renaming would clobber a real review to tidy a name.
+- `packages/content/guidance` — the layers shipped with the framework: `secure-defaults.md`,
+  `accessibility.md`, `api-conventions.md`, `lessons-digest.md`, `content-operations.md`, plus
+  `index.yaml`. The shipped digest is a **stub**, deliberately: lessons are project data, and a
+  framework package must not hand one project's observations to every consumer.
+- `packages/cli/src/compile/guidance-budget.ts` — `alwaysReadLayers` and the two 20KB constants. One
+  module so the skill prose, the `aidlc status` notice and the tests cite one declaration.
+- `packages/cli/src/doctor/migrations/lessons-digest-layer.ts` — moves an existing project onto the
+  digest. `confirm` tier, because it changes what every future session reads. Runs directly after
+  `install-guidance`, and that order is load-bearing: it registers the digest only when the body is
+  already on disk, and reversed it would leave `lessons` on-demand with nothing always-read in its
+  place.
+- `.aidlc/guidance/lessons.md` — this project's own lessons, now on-demand. Worth reading before
+  writing any guard: it already contains the failure modes of the guard you are about to write.
+- `packages/content/skills/80-review.md` and `05-constitution.md` — the review protocol and the
+  constitution protocol.