@pilotspace/add 1.1.0 → 1.3.0

package/bin/cli.js

@@ -29,12 +29,21 @@ function warn(msg) { process.stderr.write("warn: " + msg + "\n"); }
 function fail(msg) { process.stderr.write("error: " + msg + "\n"); process.exit(1); }
 
 function parseArgs(argv) {
-  const args = { _: [], force: false, stage: "prototype", name: null };
+  // stage/name stay null unless EXPLICITLY passed — the engine's own `init`
+  // defaults the stage and infers the name from the folder, so the manual-init
+  // hint only echoes flags the user actually chose (shortest true command).
+  const args = { _: [], force: false, check: false, stage: null, name: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--force") args.force = true;
-    else if (a === "--stage") args.stage = argv[++i];
-    else if (a === "--name") args.name = argv[++i];
+    else if (a === "--check") args.check = true;
+    else if (a === "--stage" || a === "--name") {
+      const v = argv[++i];
+      // fail loudly on a trailing/abutting flag — never silently drop a value
+      // the user tried to pass (parity with the pip twin's argparse error)
+      if (v == null || v.startsWith("--")) fail(a + " requires a value");
+      if (a === "--stage") args.stage = v; else args.name = v;
+    }
     else if (a.startsWith("--")) warn("ignoring unknown flag " + a);
     else args._.push(a);
   }
@@ -99,10 +108,87 @@ function cmdInit(args) {
   log("");
   log("Prefer the CLI / not using Claude Code? Initialise it yourself (this arms the lock-down):");
   const launcher = process.platform === "win32" ? "py" : "python3";
-  log(`  ${launcher} .add/tooling/add.py init --await-lock --stage ${args.stage}` +
+  log(`  ${launcher} .add/tooling/add.py init --await-lock` +
+      (args.stage ? ` --stage ${args.stage}` : "") +
       (args.name ? ` --name "${args.name}"` : ""));
 }
 
+// --- update: re-materialize the managed layer without a re-install -----------
+// The managed trees (ship-controlled). `update` clean-replaces each, so a file removed
+// upstream leaves no orphan — and never touches .add/state.json, PROJECT.md, milestones,
+// tasks, or archive (user data). Pure file-copy (npm <-> pip parity with _installer.py).
+const MANAGED = [
+  ["skill/add", [".claude", "skills", "add"], false],
+  ["tooling", [".add", "tooling"], true],
+  ["docs", [".add", "docs"], false],
+];
+const STAMP_FILE = ".add-version";
+
+function pkgVersion() {
+  try { return require(path.join(PKG_ROOT, "package.json")).version; }
+  catch (_e) { return "0.0.0"; }
+}
+
+function readStamp(addDir) {
+  const p = path.join(addDir, STAMP_FILE);
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch (_e) { return null; }
+}
+
+function writeStamp(addDir, version) {
+  fs.mkdirSync(addDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(addDir, STAMP_FILE),
+    JSON.stringify({ version: version, channel: "npm", installed_at: new Date().toISOString() }, null, 2) + "\n"
+  );
+}
+
+function cleanReplaceTree(src, dest, stripTests) {
+  if (!fs.existsSync(src)) fail("missing packaged source: " + src);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  if (fs.existsSync(dest)) fs.rmSync(dest, { recursive: true, force: true });
+  fs.cpSync(src, dest, { recursive: true });
+  if (stripTests) {
+    fs.rmSync(path.join(dest, "__pycache__"), { recursive: true, force: true });
+    for (const entry of fs.readdirSync(dest)) {
+      if (/^test_.*\.py$/.test(entry)) fs.rmSync(path.join(dest, entry), { force: true });
+    }
+  }
+}
+
+function cmdUpdate(args) {
+  const target = path.resolve(args._[0] || ".");
+  const addDir = path.join(target, ".add");
+  if (!fs.existsSync(path.join(addDir, "tooling")) && !fs.existsSync(path.join(addDir, "state.json"))) {
+    fail("no ADD project at " + target + " (.add/ not found) — run `init` first");
+  }
+  const version = pkgVersion();
+  const stamp = readStamp(addDir);
+  const cur = stamp && stamp.version ? stamp.version : null;
+
+  if (args.check) {
+    if (cur === version) log("ADD is current: project and package both at " + version + ".");
+    else if (cur === null) log("ADD project is unstamped; installed package is " + version + ". Run `update`.");
+    else log("ADD update available: project on " + cur + ", package is " + version + ". Run `update`.");
+    return;
+  }
+  if (cur === version && !args.force) {
+    log("ADD already at " + version + " — nothing to update (use --force to re-materialize).");
+    return;
+  }
+  // design-for-failure: back up state BEFORE touching anything.
+  const stateFile = path.join(addDir, "state.json");
+  if (fs.existsSync(stateFile)) {
+    fs.copyFileSync(stateFile, path.join(addDir, "pre-update-state.bak.json"));
+  }
+  for (const [sub, destParts, stripTests] of MANAGED) {
+    cleanReplaceTree(path.join(PKG_ROOT, sub), path.join(target, ...destParts), stripTests);
+  }
+  writeStamp(addDir, version);
+  log("ADD updated " + (cur || "(unstamped)") + " -> " + version +
+      " · skill · tooling · docs refreshed · your project state untouched.");
+}
+
 function main() {
   const argv = process.argv.slice(2);
   const cmd = argv[0] && !argv[0].startsWith("--") ? argv.shift() : "init";
@@ -111,9 +197,14 @@ function main() {
     case "init":
       cmdInit(args);
       break;
+    case "update":
+      cmdUpdate(args);
+      break;
     case "help":
     case "--help":
-      log("usage: npx @pilotspace/add init [targetDir] [--force] [--stage <s>] [--name <n>]");
+      log("usage: npx @pilotspace/add <init|update> [targetDir] [--force] [--check]");
+      log("  init    install the ADD skill + tooling + book into a project");
+      log("  update  re-materialize skill/tooling/docs to this package version (preserves your state)");
       break;
     default:
       fail("unknown command '" + cmd + "'. Try: npx @pilotspace/add init");

package/docs/01-principles.md

@@ -34,7 +34,7 @@ The flow has an order, but it is not a one-way march. Any step may reveal a gap
 
 How much you let the AI do is not a single switch. It is a setting that lives *per scope*, and it can differ from one part of the system to another. A well-tested, low-risk area may run at full autonomy while a new, high-risk one is held back.
 
-The *default starting point* is a deliberate choice. A team that has built up evidence and tooling may **start a scope at auto** — the AI drafts the front, a human approves the frozen contract once, and the build runs and auto-gates on evidence — and *lower to conservative* wherever risk is high. (An earlier formulation started every scope conservative and made autonomy the earned exception; it is the same dial either way — what differs is which end you default to.) Two things never move with the default, whichever way it points: the contract-freeze seam stays human (the AI never freezes the interface it then builds against), and a high-risk scope is always lowered, never auto-run.
+The *default starting point* is a deliberate choice. A team that has built up evidence and tooling may **start a scope at auto** — the AI drafts the specification bundle, a human approves the frozen contract once, and the build runs and auto-gates on evidence — and *lower to conservative* wherever risk is high. (An earlier formulation started every scope conservative and made autonomy the earned exception; it is the same control either way — what differs is which end you default to.) Two things never move with the default, whichever way it points: the contract-freeze decision point stays human (the AI never freezes the interface it then builds against), and a high-risk scope is always lowered, never auto-run.
 
 **Consequence:** autonomy is a per-scope setting you choose deliberately and can lower at any time; high-risk scope is held to a human gate regardless of the default (see [11 Governance](./11-governance.md)).
 
@@ -60,9 +60,9 @@ The instructions you give the AI are plain text that reference files in the repo
 
 **Consequence:** the same project works whether the team uses one AI coding tool or another, and switching tools changes nothing structural.
 
-## 9. Two surfaces: the State you load, the Story you reference
+## 9. Two layers: the working state you load, the audit trail you reference
 
-A method that fills the context window with its own documentation defeats itself — the agent rots before it reaches the work. So ADD keeps two doc surfaces and never loads both. The **State surface** is everything an agent loads to do the work each session: the `add` skill itself (its router `SKILL.md` and the one phase currently in play) together with the lean, current operational docs — `PROJECT.md` (the foundation), the active `MILESTONE.md`, the active `TASK.md`, and `state.json`. The **Story surface** is this book: the whole method, read once by a person to understand and trust ADD, and thereafter **never auto-loaded** into agent context — only referenced by a pointer. Depth lives on the Story surface; leanness is enforced on the State surface; they never compete for the same tokens.
+A method that fills the context window with its own documentation defeats itself — the agent rots before it reaches the work. So ADD keeps two documentation layers and never loads both. The **working state** is everything an agent loads to do the work each session: the `add` skill itself (its router `SKILL.md` and the one phase currently in play) together with the lean, current operational docs — `PROJECT.md` (the foundation), the active `MILESTONE.md`, the active `TASK.md`, and `state.json`. The **audit trail** is this book plus the records behind it: the whole method, read once by a person to understand and trust ADD, and thereafter **never auto-loaded** into agent context — only referenced by a pointer. Depth lives in the audit trail; leanness is enforced on the working state; they never compete for the same tokens.
 
 **Consequence:** the book can be as rich as trust requires without costing a single runtime token, while the loaded surface stays small enough never to rot. It is why the guideline block in `CLAUDE.md`/`AGENTS.md` *points* to `add.py status` and `PROJECT.md` rather than copying them.
 

package/docs/02-the-flow.md

@@ -6,15 +6,18 @@
 
 ## The flow
 
-AIDD is one repeatable flow of **seven steps**: six build the feature — Specify → Scenarios → Contract → Tests → Build → Verify — and the seventh, **Observe**, feeds what production teaches back into the next Specify. In the default flow the AI drafts the front (steps 1–4) and a person approves it **once**, at the contract freeze; the AI performs the Build; and Verify is resolved on evidence under `autonomy: auto`, with a person owning any residue. (See [11 Governance](./11-governance.md) for the autonomy dial and the one-approval seam.)
+AIDD is one repeatable flow of **seven steps**: six build the feature — Specify → Scenarios → Contract → Tests → Build → Verify — and the seventh, **Observe**, feeds what production teaches back into the next Specify. In the default flow the AI drafts the specification bundle (steps 1–4) and a person approves it **once**, at the contract freeze; the AI performs the Build; and Verify is resolved on evidence under `autonomy: auto`, with a person owning any residue. (See [11 Governance](./11-governance.md) for the autonomy level and the one-approval decision point.)
 
-![The ADD flow — a solid forward spine Specify→Scenarios→Contract→Tests→Build→Verify→Observe, with dashed backward-correction arrows (any phase may return to an earlier one), a Tests⇄Build red/green engine, and Observe looping back to the next Specify](./add-flow.png)
+**Before those seven steps comes a phase-0 preamble: `ground`.** Before it specifies anything, the AI gathers the real current codebase the task touches — the actual files, symbols, signatures, patterns, and conventions — into a lean §0 *grounding map*, surfacing the **anchors** the frozen contract will later cite. Ground is AI-owned and adds no new approval (the one approval stays at the contract freeze); it aims the specification bundle at reality instead of assumption, so the contract, tests, and build are grounded in the code as it actually is. The seven steps keep their numbering and brand — ground precedes them as step 0 (it is drawn as node 0 in the diagram below).
+
+![The ADD flow — a solid primary flow Specify→Scenarios→Contract→Tests→Build→Verify→Observe, with dashed backward-correction arrows (any phase may return to an earlier one), a Tests⇄Build red/green engine, and Observe looping back to the next Specify](./add-flow.png)
 
 ```mermaid
 flowchart LR
+  S0["0 Ground<br/>the real codebase"] --> S1["1 Specify<br/>the rules"]
   S1["1 Specify<br/>the rules"] --> S2["2 Scenarios<br/>pass/fail cases"]
   S2 --> S3["3 Contract<br/>freeze the shape"]
-  S3 --> S4["4 Tests<br/>safety net (red)"]
+  S3 --> S4["4 Tests<br/>failing-first (red)"]
   S4 --> S5["5 Build<br/>AI writes code"]
   S5 --> S6["6 Verify<br/>evidence + checks"]
   S6 --> OBS["Observe<br/>in production"]
@@ -23,14 +26,14 @@ flowchart LR
   S5 -. "a missing rule → back to Specify" .-> S1
   OBS -. "what you learn becomes the next spec" .-> S1
   classDef human fill:#FAEEDA,stroke:#BA7517,color:#633806;
-  classDef seam fill:#E1F5EE,stroke:#0F6E56,color:#04342C;
+  classDef decision fill:#E1F5EE,stroke:#0F6E56,color:#04342C;
   classDef machine fill:#E6F1FB,stroke:#185FA5,color:#042C53;
   class S1,S2 human;
-  class S3,S4 seam;
-  class S5,S6 machine;
+  class S3,S4 decision;
+  class S0,S5,S6 machine;
 ```
 
-> **Solid arrows are the forward spine** — you never start a phase before its input exists (forward-skip forbidden). **Dashed arrows are backward correction** — any phase may return to an earlier one to repair its artifact (the long loop, Observe → Specify, is the same rule at milestone scale). The tight Tests ⇄ Build cycle is the per-feature red/green engine.
+> **Solid arrows are the primary flow** — you never start a phase before its input exists (forward-skip forbidden). **Dashed arrows are backward correction** — any phase may return to an earlier one to repair its artifact (the long loop, Observe → Specify, is the same rule at milestone scale). The tight Tests ⇄ Build cycle is the per-feature red/green engine.
 
 ```text
   human-led ─────────────────►│◄─────────── machine-led ──► human verify
@@ -45,9 +48,9 @@ flowchart LR
        └─────────────────────────┘  becomes the next Specify
 ```
 
-The shape is deliberate: the human-led steps establish direction, a frozen contract forms the seam in the middle, and the AI-led build runs fast and safely on the far side because everything it needs is already fixed.
+The shape is deliberate: the human-led steps establish direction, a frozen contract forms the decision point in the middle, and the AI-led build runs fast and safely on the far side because everything it needs is already fixed.
 
-> **What changed in v7 (the diagrams above show the structural spine, which is unchanged).** The *steps* and their order are exactly as drawn — only **who resolves them** moved. The AI now drafts the whole front (steps 1–4) and a person approves it **once**, at the contract freeze (not a sign-off at each step); and **Verify is auto-gated on evidence** under `autonomy: auto` (the default), escalating security — always a `HARD-STOP` — and other residue to a person. Lower the dial to `conservative` to keep a human at the Verify gate. See [11 Governance](./11-governance.md).
+> **What changed in v7 (the diagrams above show the structural flow, which is unchanged).** The *steps* and their order are exactly as drawn — only **who resolves them** moved. The AI now drafts the whole specification bundle (steps 1–4) and a person approves it **once**, at the contract freeze (not a sign-off at each step); and **Verify is auto-gated on evidence** under `autonomy: auto` (the default), escalating security — always a `HARD-STOP` — and other residue to a person. Lower the autonomy level to `conservative` to keep a human at the Verify gate. See [11 Governance](./11-governance.md).
 
 ## Why the order is the order
 
@@ -58,7 +61,7 @@ Each step produces exactly one artifact, and each artifact is the input to the n
 | 1 Specify | the rules | scenarios, and everything after |
 | 2 Scenarios | pass/fail cases | the tests |
 | 3 Contract | the fixed shape | the tests and the build |
-| 4 Tests | the failing safety net | the build and the verification |
+| 4 Tests | the failing-first suite | the build and the verification |
 | 5 Build | the code | the verification |
 | 6 Verify | a trusted, releasable change | the release and the next loop |
 
@@ -66,17 +69,21 @@ The single rule of discipline follows directly: **do not begin a step until the
 
 The flow runs in two directions under two rules that never conflict. **Backward correction is always allowed:** any phase may send you back to an earlier one to repair its artifact — a failing Build that exposes a missing rule sends you back to Specify, and that is the loop working ([principle 4](./01-principles.md)), not a failure. **Forward-skipping is forbidden:** you never start a phase before its input artifact exists. Correct backward freely; never skip forward.
 
+**`done` is terminal — except via the recorded reopen.** Backward correction moves a *live* task; a task at `done` has already passed its gate. The one way back from `done` is the recorded `reopen` action (`add.py reopen <task> --to <phase> --reason "..."`): it returns the task to an earlier phase, resets the gate, and writes down *why* — so a done verdict is never quietly un-done. This is the same backward-correction rule, made explicit at the one state where it would otherwise be bypassed silently.
+
 ## Who does what
 
 | Step | Person's job | AI's job |
 |------|--------------|----------|
 | 1 Specify | confirm the rules (part of the one approval) | draft; list assumptions to confirm |
 | 2 Scenarios | confirm what "correct" looks like (part of the one approval) | draft scenarios |
-| 3 Contract | **approve & freeze the whole bundle (§1–§4) once — the seam** | draft the contract and mocks |
+| 3 Contract | **approve & freeze the whole bundle (§1–§4) once — the decision point** | draft the contract and mocks |
 | 4 Tests | confirm the targets (part of the one approval) | draft the failing tests |
 | 5 Build | direct in small batches | implement until tests pass |
 | 6 Verify | own the residue (security · concurrency · architecture); approve when `conservative` | gather evidence; **auto-PASS on complete evidence** under `autonomy: auto` |
-| 7 Observe | read the signal; fold confirmed deltas into PROJECT.md | run behind a flag; emit competency deltas |
+| 7 Observe | read the signal; consolidate confirmed deltas into PROJECT.md | run behind a flag; emit lessons learned |
+
+**What the human sees when it is their turn — the decision arc.** Whenever the flow stops for the human — the baseline approval that ends setup, the contract-freeze decision point and an escalated verify gate within each task, and the wider decision points of the loop (intake · scope · milestone close · stage graduation) — the AI opens its report with the **decision arc**: three engine-sourced lines — `goal:` the milestone goal the work serves · `done:` the proven progress toward it · `plan:` what comes next. The arc renders first, above the report's summary, so the human confirms with sight of the whole trajectory rather than a local snapshot. It is presentation only — it never adds a gate or changes an outcome. See [Appendix C](./appendix-c-glossary.md).
 
 ## What survives, and what is disposable
 

package/docs/03-step-1-specify.md

@@ -4,7 +4,7 @@
 
 > **Purpose:** state, in plain language, what the feature must do and what it must reject, with no ambiguity left for the AI to resolve by guessing.
 > **Produces:** `SPEC.md` for the feature.
-> **How it works — co-specification:** AI and human **brainstorm the shape together**; the AI drafts; the **human validates, with the AI's advice.** The decisive advice is a *least-sure flag* — the AI names the one or two things most likely to be wrong, so the human's attention lands where it matters. The human owns the decision; the AI owns surfacing what it does not yet know.
+> **How it works — co-specification:** AI and human **brainstorm the shape together**; the AI drafts; the **human validates, with the AI's advice.** The decisive advice is a *lowest-confidence flag* — the AI names the one or two things most likely to be wrong, so the human's attention lands where it matters. The human owns the decision; the AI owns surfacing what it does not yet know.
 
 ---
 
@@ -19,10 +19,10 @@ There is also a diagnostic value: **if you cannot write the spec, you do not yet
 A specification is not dictated by one side. It is made in three moves:
 
 1. **Diverge — brainstorm by both.** Before drafting, the AI surfaces the *decision space*: the two or three genuine ways to frame the feature, and the open questions it would otherwise resolve by guessing. You react — add, kill, redirect. This is the brainstorm, and it lives in the conversation, not in a new document.
-2. **Converge — the AI drafts, and ranks its own uncertainty.** The AI writes the spec below, then ranks what it is least sure about. It does not hand you a flat wall of equal-looking assumptions to nod through; it tells you *where it is most likely wrong, and what that would cost.*
+2. **Converge — the AI drafts, and ranks its own uncertainty.** The AI writes the spec below, then ranks where its confidence is lowest. It does not hand you a flat list of equal-looking assumptions to nod through; it tells you *where it is most likely wrong, and what that would cost.*
 3. **Validate — you decide, with the AI's advice.** You read the ranked uncertainty first, then confirm, correct, or send it back. Your approval is real because your attention was aimed.
 
-The brainstorm leaves a *light trace, not a document.* What you chose becomes a rule; what you weighed and dropped becomes a one-line **`Framings weighed:`** note; what stayed genuinely uncertain becomes a **least-sure flag**. Nothing new to maintain — the residue lands in the spec you were writing anyway.
+The brainstorm leaves a *light trace, not a document.* What you chose becomes a rule; what you weighed and dropped becomes a one-line **`Framings weighed:`** note; what stayed genuinely uncertain becomes a **lowest-confidence flag**. Nothing new to maintain — the residue lands in the spec you were writing anyway.
 
 ## What a good specification contains
 
@@ -31,7 +31,7 @@ Four parts, kept short:
 1. **Must** — the behaviors the feature is required to perform.
 2. **Reject** — the inputs or situations it must refuse, each paired with a named error.
 3. **After** — the state that is true once it succeeds (what changed).
-4. **Assumptions — least-sure first** — the things you are taking for granted, **ranked so the most-likely-wrong come first.** The top one or two carry a `⚠` flag with *why it is uncertain* and *what it costs if wrong*; the rest are the low-stakes tail. A spec with genuinely nothing uncertain still names its single biggest risk, however small — the AI never claims a blank mind.
+4. **Assumptions — lowest-confidence first** — the things you are taking for granted, **ranked so the most-likely-wrong come first.** The top one or two carry a `⚠` flag with *why it is uncertain* and *what it costs if wrong*; the rest are the low-stakes tail. A spec with genuinely nothing uncertain still names its single biggest risk, however small — the AI never claims a blank mind.
 
 Naming the errors matters. "Reject bad amounts" is an instruction to guess; `amount <= 0 -> "amount_invalid"` is a rule that produces a testable scenario and a defined contract response.
 
@@ -47,8 +47,8 @@ Reject:
   - <bad input / situation> -> "<error_code>"
 After:
   - <what is true once it succeeds>
-Assumptions — least-sure first:
-  ⚠ <most-likely-wrong assumption> — least sure because <why>; if wrong: <cost>
+Assumptions — lowest-confidence first:
+  ⚠ <most-likely-wrong assumption> — lowest confidence because <why>; if wrong: <cost>
   - [x] <confirmed / low-stakes assumption> — <one line>
 ```
 
@@ -69,8 +69,8 @@ Reject:
   - source == destination -> "same_account"
   - balance < amount      -> "insufficient_funds"
   - account not mine      -> "forbidden"
-Assumptions — least-sure first:
-  ⚠ same currency only (no FX) in v1 — least sure because the ticket never said; if wrong: the whole amount/rounding model changes and this contract is wrong
+Assumptions — lowest-confidence first:
+  ⚠ same currency only (no FX) in v1 — lowest confidence because the ticket never said; if wrong: the whole amount/rounding model changes and this contract is wrong
   - [x] no daily limit in v1 — confirmed: out of scope for v1
 ```
 
@@ -78,16 +78,18 @@ The `Framings weighed:` line shows what was considered and dropped, so the chose
 
 ## The AI's role here
 
-Use the AI to **open the space and then narrow it honestly.** First it brainstorms the genuine framings with you (diverge). Then it drafts the spec from whatever raw material you have — a ticket, an interview, a contract document — listing every assumption it had to make, **ranked least-sure first**, and flagging the one or two it is least confident in with *why* and *what it costs if wrong*. Its instinct is to fill gaps silently and present a confident wall; the method forces those gaps into the open, and forces the confident wall to declare its own soft spots. See `playbook/1_specify.md` in [Appendix B](./appendix-b-prompts.md).
+Use the AI to **open the space and then narrow it honestly.** First it brainstorms the genuine framings with you (diverge). Then it drafts the spec from whatever raw material you have — a ticket, an interview, a contract document — listing every assumption it had to make, **ranked lowest-confidence first**, and flagging the one or two it is least confident in with *why* and *what it costs if wrong*. Its instinct is to fill gaps silently and present a confident wall; the method forces those gaps into the open, and forces the confident wall to declare its own soft spots. See `playbook/1_specify.md` in [Appendix B](./appendix-b-prompts.md).
 
-The defining instruction: *if a requirement is unclear, ask — do not resolve it by guessing — and of the things you must assume, say plainly which you are least sure about.*
+The defining instruction: *if a requirement is unclear, ask — do not resolve it by guessing — and of the things you must assume, say plainly where your confidence is lowest.*
 
 ## Common mistakes
 
 - **Stating only the happy path.** The "Reject" list is where most real complexity lives; an empty one usually means it has not been thought through.
 - **Free-text errors.** Errors must be named codes, not sentences, so they can become scenarios and contract responses.
 - **Hidden assumptions.** If an assumption is not written down, it is not confirmed — it is a future bug with a delay timer.
-- **A flat wall of "confirmed" assumptions.** Eight equal-looking ticks invite a reflex approval. Rank them; flag the one or two that are load-bearing. An unranked list hides the risk inside the noise.
+- **A flat list of "confirmed" assumptions.** Eight equal-looking ticks invite a reflex approval. Rank them; flag the one or two that are load-bearing. An unranked list hides the risk inside the noise.
+- **"Existing behavior" claims without a citation.** An assumption row that asserts "this is how X works today" is describing intent, not code. Any wiring claim or assumption that depends on the current state of an existing path must carry a grep/line citation (e.g. `file.rs:203`) — otherwise it is a future bug in disguise.
+- **Wiring claims that name a symbol, not a caller chain.** Verifying that a function exists is not the same as verifying it is reachable. A wiring claim is only valid when it names the production caller chain from an actual entry point — not just the symbol's location in a file. A function that nothing calls is dead, not wired.
 
 ## Exit check
 
@@ -96,7 +98,7 @@ A spec is done when:
 - [ ] Every required behavior is stated explicitly.
 - [ ] Every rejection has a named error code.
 - [ ] The success state-change is described.
-- [ ] The assumptions are ordered least-sure first, and the one or two `⚠` flags carry *why* + *cost* — or, for genuinely trivial scope, an honest "none material" that still names the single biggest risk.
+- [ ] The assumptions are ordered lowest-confidence first, and the one or two `⚠` flags carry *why* + *cost* — or, for genuinely trivial scope, an honest "none material" that still names the single biggest risk.
 
 The shift from older practice: you no longer pre-confirm every assumption to advance. You confirm that the AI has *ranked* its uncertainty and that you have *engaged the top of the rank.* Stated honestly: the flag makes a genuine review cheap and a lazy one visibly negligent — it cannot force the read. That is the most a lightweight check can buy.
 
@@ -108,7 +110,7 @@ If you cannot state a rule clearly, the feature is not ready to build. Stop, tak
 
 ## The one approval, and where the flag really lands
 
-In the one-approval front, you do not approve the spec alone — you approve the whole frozen bundle (spec, scenarios, contract, tests) once, at the contract freeze. So the least-sure flag is **bundle-wide**: at that single seam the AI leads with *"of everything I'm asking you to freeze, these one or two points are most likely wrong"* — and a flag may point at an uncovered scenario or the contract shape, not only a spec assumption. The ranking you do here in Specify is the first feeder into that one gate. See [05 Contract](./05-step-3-contract.md) and the `add` skill's `run.md`.
+In the one-approval flow, you do not approve the spec alone — you approve the whole frozen bundle (spec, scenarios, contract, tests) once, at the contract freeze. So the lowest-confidence flag is **bundle-wide**: at that single decision point the AI leads with *"of everything I'm asking you to freeze, these one or two points are most likely wrong"* — and a flag may point at an uncovered scenario or the contract shape, not only a spec assumption. The ranking you do here in Specify is the first input into that one gate. See [05 Contract](./05-step-3-contract.md) and the `add` skill's `run.md`.
 
 ---
 

package/docs/04-step-2-scenarios.md

@@ -6,7 +6,7 @@
 > **Produces:** `features/<name>.feature`.
 > **Person's job:** decide what "correct" looks like in concrete situations. **AI's job:** draft the scenarios.
 
-> **Part of the one-approval front (v7).** In the default flow these scenarios are drafted by the AI alongside the spec, contract, and failing tests as **one bundle**, approved by a person **once**, at the contract freeze — not signed off step by step. This chapter is how to get the scenarios *right*; [05 Contract](./05-step-3-contract.md) is where the bundle is frozen. See [11 Governance](./11-governance.md).
+> **Part of the specification bundle (v7).** In the default flow these scenarios are drafted by the AI alongside the spec, contract, and failing tests as **one bundle**, approved by a person **once** (the one approval), at the contract freeze — not signed off step by step. This chapter is how to get the scenarios *right*; [05 Contract](./05-step-3-contract.md) is where the bundle is frozen. See [11 Governance](./11-governance.md).
 
 ---
 
@@ -14,7 +14,7 @@
 
 A plain rule is still open to interpretation. "Source must have enough balance" leaves open: enough for what, exactly? What happens to the balances when it is *not* enough? A scenario removes the interpretation by pinning a specific situation to a specific expected result.
 
-Scenarios occupy a unique position: they are **readable by people and checkable by machines at the same time.** A product owner can confirm a scenario is what they meant; a test can be generated directly from it. This makes them the bridge between the human-led front of the flow and the machine-led back. They are the single most leverage-bearing artifact in the method, because everything downstream — the tests, and through them the build's definition of success — is generated from them.
+Scenarios occupy a unique position: they are **readable by people and checkable by machines at the same time.** A product owner can confirm a scenario is what they meant; a test can be generated directly from it. This makes them the bridge between the human-led half of the flow and the machine-led back. They are the single most leverage-bearing artifact in the method, because everything downstream — the tests, and through them the build's definition of success — is generated from them.
 
 ## The form
 

package/docs/05-step-3-contract.md

@@ -6,13 +6,13 @@
 > **Produces:** `contracts/<name>.md` (plus a mock and contract tests).
 > **Person's job:** approve and freeze the shape. **AI's job:** generate the first draft, the mock, and the contract tests.
 
-> **The one approval lands here (v7).** In the default flow the AI drafts the whole front — spec, scenarios, this contract, and the failing tests — as **one bundle**, and a person gives a **single approval at this freeze**. Freezing the contract is the one human gate of the front, not the third of three sign-offs; reject any part and the whole bundle returns to draft (backward correction, not failure). See [11 Governance](./11-governance.md).
+> **The one approval lands here (v7).** In the default flow the AI drafts spec, scenarios, this contract, and the failing tests as **one specification bundle**, and a person gives a **single approval at this freeze**. Freezing the contract is the one human gate of the bundle, not the third of three sign-offs; reject any part and the whole bundle returns to draft (backward correction, not failure). See [11 Governance](./11-governance.md).
 
 ---
 
-## The seam of the whole method
+## The decision point of the whole method
 
-This step is the seam between the human-led and machine-led halves of the flow, and it is what makes everything after it safe.
+This step is the decision point between the human-led and machine-led halves of the flow, and it is what makes everything after it safe.
 
 The reasoning is simple. The AI is allowed to write and rewrite code quickly. That is only safe if there is a stable surface that the rest of the system depends on and that the AI is not allowed to disturb. The frozen contract is that surface. Below it, the code is disposable and can be regenerated freely; above it, nothing breaks, because the shape it depends on does not move.
 

package/docs/06-step-4-tests.md

@@ -6,7 +6,7 @@
 > **Produces:** a failing (red) automated test suite.
 > **Person's job:** set the targets and coverage. **AI's job:** generate the tests.
 
-> **Part of the one-approval front (v7).** In the default flow these tests are drafted by the AI as part of the front **bundle** (spec · scenarios · contract · tests) and approved by a person **once**, at the contract freeze — the tests are part of what that single approval covers. They still must be **red before the build**. See [11 Governance](./11-governance.md).
+> **Part of the specification bundle (v7).** In the default flow these tests are drafted by the AI as part of the specification **bundle** (spec · scenarios · contract · tests) and approved by a person **once**, at the contract freeze — the tests are part of what that one approval covers. They still must be **red before the build**. See [11 Governance](./11-governance.md).
 
 ---
 
@@ -18,7 +18,7 @@ The reason is mechanical. If code is written first and tests after, the tests ar
 
 ## The must-fail principle
 
-After generating the tests, you run them — and they must **fail**, because no implementation exists yet. This sounds trivial and is not. A test that passes before any code is written is testing nothing; it is a false reassurance that will later wave bad code through. Confirming the suite is "red for the right reason" (a missing implementation, not a broken test) is what makes it a genuine safety net.
+After generating the tests, you run them — and they must **fail**, because no implementation exists yet. This sounds trivial and is not. A test that passes before any code is written is testing nothing; it is a false reassurance that will later wave bad code through. Confirming the suite is "red for the right reason" (a missing implementation, not a broken test) is what makes it genuinely protective.
 
 ## What to test
 
@@ -60,6 +60,11 @@ The AI generates the test suite from the scenarios and contract. Your job is to
 - **A green suite before the build.** Means the tests are not actually exercising the missing feature — fix them now.
 - **Skipping the side-effect assertions.** Without `assert a.balance == 20` on the rejection path, a corrupting partial failure passes silently.
 - **No coverage target.** Without a recorded target, coverage can quietly erode during the build.
+- **`should_panic` as a red test.** Marking a test `#[should_panic(expected = "implement in green wave")]` (or the equivalent in any language) passes immediately and stays green while red — it is a lying red. Declare unimplemented paths with `todo!()` (or `unimplemented!()`) so the test actually fails. If a test is intentionally designed to flip from red to green during the build, say so with a comment: `// flip authorized at green wave`.
+- **Collateral tests named by category, not by exact name.** When a spec adds a slash command, a new CLI subcommand, or any other globally-enumerated thing, there is a fixed collateral set of tests that count or enumerate it (e.g. a command-registry count test, a help-text snapshot, an autocomplete positional assert). Pre-list these tests by their **exact test names** in §4 — not categories — so the build agent's edits to those "pre-existing" tests are expected and the count is right. Naming only the category means the agent finds the wrong test or misses one.
+- **Arithmetic not checked against frozen constants.** Before freezing, check that the red suite can reach green: a fixture with N bytes fails a hard-coded M-byte budget if N > M — the suite can never pass. Run the numbers before freeze, and add an additive override (e.g. `set_budget`) when the scenario implies a limit the production constant cannot satisfy in test.
+- **Non-hermetic tests that read real user state.** Tests that call a loader with `None` (defaulting to `~/.helios/settings.json` or the real home dir) become torn-read flakes under a parallel suite and assert nothing useful. Red tests that create or read production paths must redirect them to a temp dir; grep new tests for `home_dir`, `~/.config`, real-path defaults before freeze.
+- **Tests that share a per-machine singleton without isolation.** Background services (embedded servers, filesystem watchers) bind to fixed ports or paths. Tests that start such a service must tear it down, or they collide with a parallel run or an already-running dev instance. If the singleton cannot be isolated, gate those tests as serial (one thread, no parallel execution) and document it.
 
 ## Exit check
 
@@ -67,6 +72,9 @@ The AI generates the test suite from the scenarios and contract. Your job is to
 - [ ] The suite runs in the pipeline and is **red for the right reason**.
 - [ ] Tests assert observable behavior, not internals.
 - [ ] A coverage target is recorded.
+- [ ] No `should_panic` lying reds — unimplemented paths use `todo!()` or equivalent so they actually fail.
+- [ ] Collateral tests for globally-enumerated things (command counts, help snapshots) are listed by exact name.
+- [ ] Arithmetic checked: the red fixtures can reach green against the frozen constants.
 
 ## If the check fails
 

package/docs/07-step-5-build.md

@@ -63,7 +63,7 @@ The autonomy granted in this step should match the evidence and your review capa
 
 ## Common mistakes
 
-- **Batches too large to review.** Shrinks verification to rubber-stamping.
+- **Batches too large to review.** Shrinks verification to approving without reading.
 - **Letting the AI add unknown dependencies.** The allow-list check in the pipeline should block this automatically; if it does not, the supply-chain risk is real (an AI may invent a plausible package name that an attacker has registered).
 - **Accepting "all tests pass" without reading the change.** Passing tests are necessary, not sufficient — the next step exists for exactly this reason.
 
@@ -78,3 +78,5 @@ The autonomy granted in this step should match the evidence and your review capa
 ## If the check fails
 
 If the AI weakened a test, reject and re-prompt. If it added an out-of-allow-list package, the pipeline blocks it; have the AI find an approved alternative or raise the package for human approval. If the batch is too large to review, ask the AI to split the work and resubmit. Only once the exit check passes does the change proceed to verification.
+
+And in the other direction: if the *verify* gate later finds a confirmed cheat — a tamper, or a build that gamed the green (overfit to the fixtures, vacuous asserts, stubbed-away logic) — the task returns *here* for an honest redo. That return is the **bounded self-heal loop** (see the run chapter): revert the tampered file or de-overfit the code, then advance again. It is capped — after the cap a confirmed cheat HARD-STOPs to the human rather than looping forever, and a gamed green is never auto-passed.

package/docs/08-step-6-verify.md

@@ -12,16 +12,16 @@
 
 The build produced passing tests. That is necessary but not sufficient. Verification is where a person establishes trust — and the principle governing it is *trust through evidence, not inspection.*
 
-This needs care, because it is easy to misread. "Not by inspection" does not mean "do not look at the code." It means the *basis* of trust is the passing evidence plus a deliberate check of the specific things tests cannot easily catch — not a general impression that the code reads plausibly. Plausibility is exactly the trap: AI code is frequently plausible and wrong. So verification has two parts: confirm the evidence, then check the known blind spots.
+This needs care, because it is easy to misread. "Not by inspection" does not mean "do not look at the code." It means the *basis* of trust is the passing evidence plus a deliberate check of the specific things tests cannot easily catch — not a general impression that the code reads plausibly. Plausibility is exactly the trap: AI code is frequently plausible and wrong. So verification has two parts: confirm the evidence, then check the known non-functional risks.
 
-## Who resolves Verify — the evidence auto-gate
+## Who resolves Verify — the automated quality gate
 
-Verify can be resolved two ways, set per task by the `autonomy:` header (see [governance](./11-governance.md) and the autonomy dial):
+Verify can be resolved two ways, set per task by the `autonomy:` header (see [governance](./11-governance.md) and the autonomy level):
 
 - **Auto (the default).** When `autonomy: auto`, the run resolves the gate on **evidence** rather than waiting for a person — but only when *all* of these hold: every test green, coverage not decreased, no test weakened and no contract edited, the convergence loops dry, and **no residue** (security, concurrency, or architecture). It records `PASS` as *auto-resolved*, naming the run as the accountable owner — an explicit pass, not a skip. This is principle 7: a gate may be resolved by evidence when that evidence is sufficient and the result is logged.
 - **Human.** When `autonomy: conservative`, or whenever the run finds residue it cannot judge, the gate stops for a person; the two parts below are theirs.
 
-**Security is always a `HARD-STOP` and is never auto-passed, at any autonomy level.** The two parts that follow — confirm the evidence, then check the blind spots — are what *either* resolver works through; the only question is whether a person or the recorded run signs the outcome.
+**Security is always a `HARD-STOP` and is never auto-passed, at any autonomy level.** The two parts that follow — confirm the evidence, then check the non-functional risks — are what *either* resolver works through; the only question is whether a person or the recorded run signs the outcome.
 
 ## Part one — confirm the evidence
 
@@ -40,6 +40,22 @@ Automated tests are excellent at behavior on defined inputs and poor at a few sp
 - **Security.** Are there exposed secrets, injection openings, or unexpected dependencies? AI-generated code is known to hardcode secrets and to pull in packages by plausible-but-wrong names.
 - **Architecture conformance.** Does the change respect the layering and dependency rules in `CONVENTIONS.md`? Speed with no architectural check produces a fast-growing tangle that becomes unmaintainable within months.
 
+## Part three — the deep check (do not skim)
+
+Two failures slip straight past green tests. The first is code that is never *wired in* — a new function that nothing calls, an endpoint no route reaches: the tests for it pass in isolation while the feature is, in practice, absent. The second is the opposite — code left *dead* behind a path nothing exercises, quietly rotting. And for a change that produced prose rather than code, the equivalent failure is signing off on a claim you never actually read in full. Plausibility hides all three. So verification carries one explicit requirement beyond the non-functional review:
+
+> Deep check — do not skim. If the task produced code, record that every new symbol is referenced (wiring) and that no new dead/unused code was introduced. If it produced prose or non-code, record a semantic read — what you read in full and what it confirmed. Which path applies is the resolver's judgement; the engine never classifies.
+
+This is *evidence*, not impression: a reference search showing where each new symbol is called, a scan confirming nothing new is orphaned, or — for prose — a note of exactly what was read and what it confirmed. An unfilled deep check is a **shallow verify**, not a pass. The engine cannot judge wiring, dead code, or whether prose was truly read; the resolver records the evidence, and a person (under `conservative`) or the recorded run (under `auto`) signs it.
+
+**The wiring trace is a named step, not a free-form note.** For every new hook, closure, or middleware registered in this task: trace from the process entry point to the call site and record it explicitly — symbol, file, line. A symbol that is only reachable via a test helper or `make_config` but not via the production entry point (e.g. `build_harness_with_dispatcher`, `interactive_mode`) is not wired. This is the third repeated class in production: "runtime-activation-order/silent-noop" — the code exists and the unit tests pass, but the feature is absent in the running program. The wiring trace is how you catch it before a user does.
+
+## Part four — was the green earned?
+
+Passing tests say the code satisfies the cases you wrote down. They do not say it earned that pass honestly — and the mechanical tamper tripwire (Step 6's floor) only catches an *edited* test or contract, not a build that gamed the *unchanged* suite. The same rubric the phase guide carries names what the tripwire cannot see:
+
+A green suite proves the tests pass — not that the build EARNED them. Three judgment cheats pass the unchanged suite without earning it: src overfit to the test fixtures (special-cased to the literal inputs, not the general behavior §1 asked for), vacuous asserts (tautological — green even against an empty implementation), and real logic stubbed away (the function returns a constant the tests happen to accept). These cheats are invisible to the mechanical tamper tripwire, which only sees edited files. Score them with an adversarial refute-read: an independent reviewer — a subagent under `autonomy: auto` is recommended, the engine never spawns one — prompted to argue the green was NOT earned from outside the build context. This is the verify-gate, whole-suite specialization of run.md's adversarial verify (see run.md), not a new discipline. A confirmed earned-green failure is HARD-STOP-class: never auto-passed, never RISK-ACCEPTED — but a first cheat is a chance to redo: a confirmed cheat (mechanical tamper or a reported earned-green failure) enters the bounded self-heal loop — it returns to build for an honest redo, and only after the loop's cap does it HARD-STOP to the human (the loop lives in run.md).
+
 ## Recording the outcome
 
 Every verification ends with exactly one recorded outcome, with an accountable owner — never a silent pass:
@@ -58,14 +74,18 @@ A security finding is always a `HARD-STOP`; it is never waved through with a wai
 - [ ] Concurrency/timing of the risky operation is safe.
 - [ ] No exposed secrets, injection openings, or unexpected dependencies.
 - [ ] Layering and dependencies follow `CONVENTIONS.md`.
+- [ ] Deep check (do not skim): for code, every new symbol is referenced (wiring) and no new dead/unused code was introduced; for prose/non-code, a semantic read is recorded.
 - [ ] The change is approved — by a person, **or** (under `autonomy: auto`, no residue) auto-resolved by the run as the recorded accountable owner.
 - [ ] An outcome is recorded (`PASS` / `RISK-ACCEPTED` / `HARD-STOP`).
 
 ## Common mistakes
 
-- **Shipping on plausibility.** Reading the diff, finding it reasonable, and approving — without the evidence and the blind-spot checks — is the precise failure the method exists to prevent.
+- **Shipping on plausibility.** Reading the diff, finding it reasonable, and approving — without the evidence and the non-functional review — is the precise failure the method exists to prevent.
 - **Treating a security gap as acceptable risk.** It is a `HARD-STOP`, not a waiver.
 - **Skipping the concurrency check** because the tests are green. Tests rarely exercise simultaneity; this is a manual check by design.
+- **Trusting the green agent's self-reported test count.** A build agent running a filtered suite (e.g. `-E 'test(theme)'`) only sees tests inside the filter. Collateral failures outside the filter — a stale count in `all_commands_in_registry`, an e2e snapshot the agent did not touch — are invisible. The orchestrator's **full-suite rerun is load-bearing**; never skip it on the grounds that the scoped run was green.
+- **User-observable-only failures escalate to the human before exhausting discriminating probes.** When a symptom is only observable by a person (a TCC dialog, a visual flicker, an OS-level prompt), do not respond by running the suite again. Instead, design two or three targeted probes that let the user distinguish cause A from cause B in one interaction each. Three AskUser probes resolve what three blind reruns cannot.
+- **Background-process hangs misdiagnosed as test failures.** A test that never exits is not a failure in the test logic — it is a hang. The diagnosis recipe: background the test process, run `pgrep` to find it, use the platform profiler (`sample <pid>` on macOS, `perf` on Linux) to sample the stack, then `lsof -p <pid>` to see open files. Run an isolation experiment (suspect line on/off, 3×3) before reading any code. Entry-count caps do not bound wall time — a single huge directory or a blocking syscall inside a `spawn_blocking` call can hang indefinitely even when the entry cap is satisfied.
 
 ## If the check fails
 

package/docs/09-the-loop.md

@@ -15,7 +15,7 @@ That information is the input to the next cycle. What you learn in production be
 
 ## Release deliberately
 
-Release behind a mechanism that limits the blast radius of a mistake — a feature flag, a gradual rollout, or both. The verification step established that the feature is correct against everything you anticipated; a controlled release is your protection against what you did not anticipate. If something is wrong, you want to affect a few users and roll back, not affect everyone and scramble.
+Release behind a mechanism that limits the scope of impact of a mistake — a feature flag, a gradual rollout, or both. The verification step established that the feature is correct against everything you anticipated; a controlled release is your protection against what you did not anticipate. If something is wrong, you want to affect a few users and roll back, not affect everyone and scramble.
 
 ## Reuse the scenarios as monitors
 
@@ -33,9 +33,9 @@ Every defect, surprise, or new need is written up as a change to the specificati
 
 This is also where the AI returns to a useful role: summarizing telemetry, clustering errors into themes, and drafting the proposed spec delta for a person to review. But the production decisions — what to roll back, what to prioritize — remain human.
 
-## Competency deltas and the foundation fold
+## Lessons learned and the retrospective consolidation
 
-A spec delta feeds the *next feature*. But a loop also teaches the **method itself** — that the domain model missed a boundary, that a whole class of scenario was never tested, that a build convention helped or hurt. AIDD captures those as **competency deltas**: a single tagged learning, written in the Observe step, marking which of the five competencies it sharpens.
+A spec delta feeds the *next feature*. But a loop also teaches the **method itself** — that the domain model missed a boundary, that a whole class of scenario was never tested, that a build convention helped or hurt. AIDD captures those as **lessons learned**: a single tagged learning, written in the Observe step, marking which of the five competencies it sharpens.
 
 | tag | competency | a delta here means you learned something about… |
 |-----|------------|--------------------------------------------------|
@@ -45,11 +45,11 @@ A spec delta feeds the *next feature*. But a loop also teaches the **method itse
 | `TDD` | Test | how we prove correctness — a missing scenario, a flaky or hollow test |
 | `ADD` | AI/build | how the AI builds — a harness, prompt, or convention that helped or hurt |
 
-Each delta is one tagged entry — `- [COMPETENCY · status] the learning (evidence: a pointer)` — and the evidence is **required**: a failing scenario, a production signal, a review note. No evidence means it is an opinion, not a delta. The AI **emits** deltas as `open`; it never folds its own. Folding is judgment, and judgment is the human's — the same verify/observe seam that keeps the AI from grading its own work.
+Each delta is one tagged entry — `- [COMPETENCY · status] the learning (evidence: a pointer)` — and the evidence is **required**: a failing scenario, a production signal, a review note. No evidence means it is an opinion, not a delta. The AI **emits** deltas as `open`; it never consolidates its own. Consolidation is judgment, and judgment is the human's — the same verify/observe decision point that keeps the AI from grading its own work.
 
-**The fold.** At milestone close (or on demand, when open deltas pile up), a person runs the fold ritual: **gather** every `open` delta across the milestone's tasks, **group** them by competency, **propose** the exact foundation edit for each, **confirm** with the human one by one, then **write** — append-only — flipping each delta to `folded` (merged) or `rejected` (considered and deliberately not merged, left in place so the trail survives), and bumping the `foundation-version:` marker. `DDD`/`SDD`/`UDD` deltas fold into the matching section of `PROJECT.md`; `TDD`/`ADD` fold into `CONVENTIONS.md` (they sharpen the engine, not the product); and **every** fold also appends one row to `PROJECT.md` §Key Decisions — the universal, auditable record of what the foundation learned.
+**The consolidation.** At milestone close (or on demand, when open deltas pile up), a person runs the retrospective consolidation: **gather** every `open` delta across the milestone's tasks, **group** them by competency, **propose** the exact foundation edit for each, **confirm** with the human one by one, then **write** — append-only — flipping each delta to `folded` (merged) or `rejected` (considered and deliberately not merged, left in place so the trail survives), and bumping the `foundation-version:` marker. `DDD`/`SDD`/`UDD` deltas consolidate into the matching section of `PROJECT.md`; `TDD`/`ADD` consolidate into `CONVENTIONS.md` (they sharpen the engine, not the product); and **every** consolidation also appends one row to `PROJECT.md` §Key Decisions — the universal, auditable record of what the foundation learned.
 
-**Tooling.** `add.py deltas` lists every open delta across the project (so nothing waiting to be folded is invisible); `add.py check` lints each delta's well-formedness — known competency tag, valid status, non-empty evidence. There is deliberately **no `add.py fold`**: the engine stays judgment-free, and the ritual lives with the human who owns it.
+**Tooling.** `add.py deltas` lists every open delta across the project (so nothing waiting to be consolidated is invisible); `add.py check` lints each delta's well-formedness — known competency tag, valid status, non-empty evidence. There is deliberately **no `add.py fold`**: the engine stays judgment-free, and the ritual lives with the human who owns it.
 
 ## Re-entrancy: the loop is the whole point
 
@@ -57,5 +57,11 @@ Two principles converge here. *The flow is re-entrant* — any step can send you
 
 A team operating this way does not experience requirements changing as a failure of planning. It experiences it as the system working: reality is teaching the specification, and the specification is teaching the next build.
 
+## The milestone holds until its goal is met
+
+A single feature loops through Observe back to Specify; a **milestone** has the same shape at a larger scale, and a gate to match. A milestone is not finished when its tasks are done — it is finished when its **goal** is met, expressed as the exit criteria in `MILESTONE.md`. So `add.py milestone-done` is **goal-gated**: it refuses to close a milestone while any exit criterion is still unchecked, and **holds until** every box is checked. Those checkboxes are the human's affirmation that the goal is genuinely met — the engine reads the tally, it never judges the goal itself. (A milestone with no exit criteria closes as before; `milestone-done` is the only path to `done`, and archiving refuses anything not yet done — so the one gate cannot be slipped.)
+
+While the milestone is held open, the work each task leaves behind — open lessons, and items discovered but out of scope — becomes its next tasks: the AI proposes them, the human confirms, and the loop continues until the goal is reached. The milestone is the loop made concrete; the exit criteria are its finish line.
+
 > **Do:** release small, watch the scenarios, and feed every learning back into the spec.
 > **Don't:** treat shipping as the end. The most valuable information about a feature arrives *after* it ships.