@pilotspace/add 1.5.0 → 1.7.0

package/docs/09-the-loop.md

@@ -47,6 +47,8 @@ A spec delta feeds the *next feature*. But a loop also teaches the **method itse
 
 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 ship review.** Before the consolidation, once a milestone's goal is met, the AI fills the milestone's `## Close — ship review` — the whole-milestone, cross-task evidence a person reads *before* checking the exit-criteria boxes (it is evidence, **not a new gate**). It has three parts: **ship by domain** — what changed in each bounded context (`tooling` · `skill` · `book`); **cross-task evidence** — one row per task (its gate, its tests, any residue); and a **goal-met map** — each exit criterion tied to the evidence that satisfies it. The AI then defines the milestone's **release steps**: the ordered, tool-agnostic hints to ship the milestone, of which `merge` is one small step (a pull request, an exported hand-off document, a tag or a publish are others). Those steps **feed** the release scope, not a second flow. The ritual itself lives in the `add` skill's `loop.md`; this chapter only names it.
+
 **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, newest-first (the newest record prepended at the top) — 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 prepends one row at the top of `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 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.

package/docs/16-releasing.md

@@ -0,0 +1,182 @@
+# 16 · Releasing
+
+[← 15 Foundations & Lineage](./15-foundations-and-lineage.md) · [Contents](./README.md) · Next: [Appendix A Templates →](./appendix-a-templates.md)
+
+---
+
+The flow chapters ([03](./03-step-1-specify.md)–[08](./08-step-6-verify.md)) take one feature from
+spec to verified. The loop chapter ([09](./09-the-loop.md)) keeps a milestone going until its goal
+is met. The stages chapter ([10](./10-setup-and-stages.md)) graduates the project's rigor. None of
+them *ship*. This chapter names the act every project eventually performs and that the method, until
+now, never formalized: bundling closed milestones into a versioned, user-facing release whose notes
+are evidence-backed, whose risk is disclosed, and whose behaviour is then watched.
+
+Releasing is the **fifth scope level** — after the task, the milestone, the foundation/setup level,
+and stage graduation. Like every scope level it runs the same shape: **gather → propose → the human
+confirms → the engine records and enforces a floor.** And like graduation, it ends with an outward
+act the human owns. The operational recipe lives in the `release.md` skill guide; this chapter is the
+*why* behind it.
+
+## 16.1 · Why release is its own scope level
+
+A number bump is not a release. A release is the moment one or more **closed milestones** become a
+versioned cut that real users can run. Three distinctions make it its own scope level:
+
+- **Milestone ≠ release.** A milestone is *feature-complete and consolidated* — its goal is met and
+  its lessons are gathered into the foundation (see [14 · The foundation](./14-foundation.md) and the
+  `fold.md` retrospective consolidation). A release is *shipped and watched*. The first is an internal
+  state; the second faces outward.
+- **Graduation ≠ release.** Stage graduation moves the project's *rigor* (mvp → production); a release
+  ships a *version*. The two axes are orthogonal: you cut a prototype preview, an mvp beta, and a
+  production GA, each at its own stage. You release at every stage, not only at the end.
+- **A release bundles; it does not equal.** One version may attribute several milestones — "we shipped
+  after a couple of milestones closed" is the normal case, not the exception. Forcing one release per
+  milestone is the anti-pattern; the decoupling is the whole point.
+
+So release sits beside the other scope levels rather than inside any of them. The granularity ladder
+is now complete: intake → milestone → task, with stage graduation and release as the two cross-cutting
+levels that change *rigor* and ship *versions* respectively (see the **Scope level** entry in
+[Appendix C](./appendix-c-glossary.md)).
+
+## 16.2 · The cue and the inventory — gather, never judge
+
+The trigger is a status line. When at least one milestone is `done`, archived, and not yet attributed
+to any release, `add.py status` prints:
+
+```
+  → releasable: N milestone(s) closed since last release
+```
+
+That line is a **tally**, never a verdict. It counts archived-but-unreleased milestones; it is silent
+for a project that has never released or has already shipped everything (grandfathered — zero change).
+It says *there is something to consider*, not *you are ready*.
+
+To gather the cut's evidence, run `add.py release-report`. It clusters five labeled record-sets: the
+closed milestones since the last release · their **consolidated deltas** (the "what changed" record) ·
+the open `RISK-ACCEPTED` waivers riding into the release · any open security `HARD-STOP` (a blocker) ·
+the §2 scenarios to take live as monitors. The report **gathers; it does not judge** — there is no
+readiness score to read off, because a tally that pretended to be a verdict would invite reading the
+number instead of the evidence.
+
+The reuse claim, stated plainly: **the consolidated deltas are the changelog source.** You do not write
+release notes from memory. The foundation already recorded what changed when each milestone was
+consolidated (`fold.md`); the release surfaces it. This is why release runs *after* consolidation, not
+before. The lifecycle order is one line:
+`milestone-done → fold → compact → archive → (repeat ≥1×) → release → watch`.
+
+## 16.3 · Drafting the notes and the version — the proposal
+
+From those record-sets you draft a [Keep a Changelog](https://keepachangelog.com/) entry: group the
+changes under Added / Changed / Fixed and name the headline capabilities concretely, in the user's
+language, not the commit's. Each bundled milestone's goal anchors one or more entries.
+
+Then propose the version. Semver is a decision the evidence informs but does not make for you: a
+breaking change is a MAJOR, a new capability a MINOR, a fix-only cut a PATCH. You propose the bump; the
+**human confirms it** — the version is a judgement, not a default the tool fills in.
+
+Both the notes and the version are *shown before they are asked about*. Present the drafted entry, the
+proposed version, and the waivers shipping in this cut via the report template — opening with the ARC
+(goal · done · plan) — and let the human approve once. The question is a summary to decide on; the
+artifact itself is rendered first, never pre-stamped.
+
+## 16.4 · The floor — what the engine enforces
+
+`add.py release <version>` is **guarded**. Before it records anything it enforces a readiness floor,
+refusing with a non-zero exit and leaving every file byte-unchanged on any of four conditions:
+
+- `release_security_open` — an open security `HARD-STOP` exists. This is the non-negotiable one: a
+  security finding is never shipped. Resolve it first, as a change request back to Specify.
+- `release_tests_red` — the suite is not green. A release ships on evidence, not on a plausible diff.
+- `release_no_closed_milestone` — nothing new since the last release. The cut would be a no-op; do not
+  bump a version to mark time.
+- `release_undisclosed_waiver` — a `RISK-ACCEPTED` waiver rides into the release but is missing from the
+  notes. Disclosure *is* the floor: a shipped risk the user cannot read about is a hidden risk.
+
+The security stop is **un-forceable.** `--force` exists for grandfathered and brownfield first-cuts —
+the same authority valve as `stage --force` ([10 · Setup and stages](./10-setup-and-stages.md)) — and
+it can override the other three rejects, but it can never override `release_security_open`. This mirrors
+the verify gate exactly ([08 · Verify](./08-step-6-verify.md)) and the governance ceiling that no
+autonomy level may lift ([11 · Governance](./11-governance.md)): a security `HARD-STOP` is the one
+outcome the method refuses to auto-pass, at verify and again at the cut.
+
+## 16.5 · The cut versus the ship — the engine records, the human ships
+
+Only after the human confirms do you run the cut. And here is the line that keeps releasing honest:
+**the engine records; the human ships.**
+
+`add.py release <version>` **records** the marker. It prepends the entry to `CHANGELOG.md`, stamps one
+append-only row (newest-first, like the §Key Decisions log) into `RELEASES.md` — date · version ·
+milestones · waivers shipped · evidence — and attributes the bundled milestones to this version, so the
+cue stops firing for them. The ledger is the attribution source: a milestone is "released" because a
+`RELEASES.md` row says so, never because a file was edited to claim it.
+
+What the engine does **not** do is act outward. It **never tags, publishes, or deploys.** The outward
+act — `git tag`, `npm publish`, the deploy pipeline — is the human's, tool-agnostic, exactly as the
+method tool "never renders" in design and "never spawns" a subagent. Design-for-failure — timeouts,
+retries, rollback, a tested revert path — belongs in the pipeline the human owns, not in a method tool
+that has no business holding deploy credentials. The tag is the human-gated trigger; the record is the
+engine's receipt that the floor was met.
+
+> **A caveat worth one paragraph.** `add.py release` writes `CHANGELOG.md` at the **project root**. That
+> is the right default for most repositories. But a repo with a different changelog convention — for
+> instance a **nested-package** layout whose root `CHANGELOG.md` is a deliberate pointer to a package's
+> own changelog — will get release blocks *prepended above* its existing content rather than replacing
+> it (the writer preserves what is there; it does not clobber). Reconcile per repo: either let the root
+> file carry the canonical log, or point the human's publish step at the package changelog the team
+> treats as the source of truth.
+
+## 16.6 · Watch and the hotfix path — re-entering observe
+
+A release is not the finish line; it is where the most reliable information finally appears. The §2
+scenarios that were pass/fail cases at build time become **live monitors** for the released version, and
+error-budget burn feeds the next loop. Live-registry and deploy confirmation are post-cut *evidence*,
+gathered after the tag — not unit tests pretending to be one.
+
+The unhappy path is first-class. A regression found in the wild re-enters at Specify as a **change
+request**, which narrows to a **hotfix release** — the same seven-step flow, scoped to the fix, cut as a
+PATCH. Releasing does not have a separate emergency mode; it has the ordinary flow at a tighter scope.
+
+Depth follows the stage, as everywhere in the method:
+
+- **prototype / poc** — a one-line preview note and a tag; no deploy ceremony. The point is feedback.
+- **mvp** — full notes, a tag, a guarded publish; watch the headline scenarios.
+- **production** — every step at full rigor: notes, tag, a deploy behind a rollback-tested pipeline,
+  live scenario monitors, and error-budget watch. The hotfix path is a routine capability here, not a
+  fire drill.
+
+## 16.7 · The flow, in one arc
+
+One arc, seven steps:
+
+**cue → gather → draft notes → readiness floor → human confirms → cut → watch**
+
+1. **cue** — `add.py status` prints `→ releasable: N` when an archived milestone is unreleased.
+2. **gather** — `add.py release-report` clusters the five record-sets (gather, never judge).
+3. **draft notes** — a Keep-a-Changelog entry drawn from the consolidated deltas; propose the version.
+4. **readiness floor** — the four guarded rejects; the security stop is un-forceable.
+5. **human confirms** — the notes, version, and waivers are shown, then approved once.
+6. **cut** — `add.py release <version>` records the CHANGELOG block + the `RELEASES.md` row + attribution.
+7. **watch** — the scenarios become monitors; a wild regression becomes a PATCH hotfix release.
+
+The recipe for each step — flags, the report's `--json` shape, the exact ledger row — lives in the
+`release.md` skill guide. This chapter is the reasoning; the guide is the procedure.
+
+## 16.8 · Worked example — this method's own 1.5.0
+
+The repository already runs this by hand, which is the best evidence the flow is real. The
+`udd-design-loop` milestone closed (4/4) and consolidated into `foundation-version 33`. From those
+deltas the human drafted the `## [1.5.0]` changelog entry, bumped the three version sources in
+lockstep, and a forward-pinned `test_release_1_5_0.py` asserted in-repo readiness: the versions agree,
+the changelog lineage survives, the feature anchors are named, and the engine is untouched by the
+release. The cut itself — the `git tag` that triggers the npm and PyPI publish — stayed human-gated,
+and the live-registry confirmation was gathered *after* the tag as verify evidence, never as a unit
+test.
+
+That ritual is what this chapter formalizes. `release-report` gathers the inventory, the floor enforces
+the security stop and the disclosures, `add.py release` records the cut, and the human still owns the
+tag. The method releases itself the way it asks every project to release: gather the evidence, disclose
+the risk, record the marker, and let a person make the outward call.
+
+---
+
+[← 15 Foundations & Lineage](./15-foundations-and-lineage.md) · [Contents](./README.md) · Next: [Appendix A Templates →](./appendix-a-templates.md)

package/docs/README.md

@@ -54,6 +54,9 @@ For every feature, before AI writes any code, you write four short artifacts in
 **Lineage**
 - [15 · Foundations & Lineage](./15-foundations-and-lineage.md)
 
+**Releasing**
+- [16 · Releasing](./16-releasing.md)
+
 **Part IV — Reference**
 - [Appendix A · Templates](./appendix-a-templates.md)
 - [Appendix B · Prompt library](./appendix-b-prompts.md)

package/docs/appendix-c-glossary.md

@@ -42,6 +42,10 @@
 
 **The decision arc** — the three engine-sourced lines a gate report opens with at every **decision point**: `goal:` the milestone goal the work serves · `done:` the achievement, the proven progress toward it (the gate reports render this line as `done`) · `plan:` what comes next. What `done` reports adapts per gate (verify: tests + evidence · milestone close: exit-criteria met · intake: the request sized) while the three-part shape stays constant. Rendered first, above the report's summary, so the human confirms with sight of the whole trajectory, not a local snapshot. Engine-sourced like all evidence — goal · done · plan are pulled from `add.py` output, never re-typed. Presentation only: it never adds a gate or changes a `PASS` / `RISK-ACCEPTED` / `HARD-STOP` / freeze outcome. The report it opens is the chat report a person reads at a decision point — distinct from the three Test/Quality/Risk reports a verify gate produces ([11 Governance](./11-governance.md)). See the `add` skill's `report-template.md`.
 
+**Guided decision** — a **decision point** presented not as a bare next-step line but as one highlighted **recommended pick** plus its real, described alternatives (each with its one-line consequence), so the human chooses with the recommendation and what each option costs already in view. It refines the report's DECISION block — composing with **the decision arc**, never adding a gate — and fires at human gates only (never at an autonomous `[you drive]` step). The sibling of the decision arc: both are what the human sees when it is their turn. See the `add` skill's `report-template.md` for the convention itself.
+
+**Recommended pick** — the one option a **guided decision** highlights with the `▶ … (recommended)` marker: exactly one, never zero and never two. The AI's confidence self-score informs the pick; the human overrides it freely. See **Guided decision**.
+
 **Specification bundle** (formerly "the one-approval front") — §1–§4 of a task (spec · scenarios · contract · failing tests) drafted by the AI as one piece and approved by a person **once**, at the contract freeze. Rejecting any part returns the whole bundle to draft. The single approval it carries is the bundle approval.
 
 **Retrospective consolidation** (formerly "the fold / fold ritual") — the milestone-close (or on-demand) step where a person gathers `open` lessons learned, confirms each, and the AI writes them append-only into the versioned foundation, bumping `foundation-version:`. The AI never self-approves a consolidation. The machine names keep their names: `fold.md`, the `folded` delta status, and `add.py deltas`.
@@ -72,10 +76,24 @@
 
 **Baseline approval** (formerly "the lock-down") — the single human gate ending autonomous setup: an explicit yes that freezes the foundation, first scope, and first contract together; runs as `add.py lock --by <name>`.
 
-**Scope level** (formerly "altitude") — the granularity a decision lives at: intake level (request → versioned scope) · milestone level · setup/foundation level · task level. (A cross-stage decision lives one level out, at the **stage-graduation** loop — which `graduate.md` also numbers as a scope level; see **Stage graduation**.) One ⚠-assumption notation is shared across every scope level.
+**Scope level** (formerly "altitude") — the granularity a decision lives at: intake level (request → versioned scope) · milestone level · setup/foundation level · task level · release level (≥1 closed milestone → a versioned, watched cut; see **Release scope level**). (A cross-stage decision lives one level out, at the **stage-graduation** loop — which `graduate.md` also numbers as a scope level; see **Stage graduation**.) One ⚠-assumption notation is shared across every scope level.
 
 **Autonomy level** (formerly "autonomy dial") — the explicit per-task setting (`autonomy: manual | conservative | auto`, an ordered ladder manual < conservative < auto) choosing who resolves Verify: `auto` auto-PASSes on complete evidence, `conservative` keeps a human at the gate, `manual` is the strict floor (the human owns the gate; nothing auto-resolves). A high-risk scope refuses an unguarded `auto` — it must be lowered to `manual` or `conservative`. New tasks seed a visible, overridable `autonomy: auto`; a live task with no level warns (`implicit_autonomy`), a token outside the set is rejected (`unknown_autonomy_level`).
 
+**Release** — a versioned, user-facing cut that bundles one or more closed milestones into something real users can run; its notes are evidence-backed, its risk is disclosed, and its behaviour is then watched. Recorded with `add.py release <version>`, which writes the changelog block and the ledger row but never tags, publishes, or deploys — the outward act stays human-owned. See [16 · Releasing](./16-releasing.md).
+
+**Release scope level** — the fifth scope level: releasing as its own granularity, orthogonal to the stage. A release bundles ≥1 closed milestone (never forced one-per-milestone) and may be cut at any stage — prototype preview, mvp beta, production GA. Distinct from milestone-close (feature-complete + consolidated) and from stage graduation (which changes rigor, not version). See **Scope level** and [16 · Releasing](./16-releasing.md).
+
+**Ship review** — the whole-milestone, cross-task evidence the AI fills at milestone close in the `## Close — ship review` section: ship-by-domain (what changed per bounded context), cross-task evidence (one row per task: gate · tests · residue), and a goal-met map (each exit criterion tied to its evidence). A person reads it *before* checking the exit-criteria boxes — evidence, not a new gate. The ritual lives in the `add` skill's `loop.md`. See [09 · The Loop](./09-the-loop.md).
+
+**Release steps** — the AI-defined, per-milestone ordered hints to ship a closed milestone, of which `merge` is one small step (a pull request, an exported hand-off document, a tag or a publish are others). Defined at close and **fed** into the release scope (see **Release**), never a second flow.
+
+**Readiness floor** — the engine-enforced pre-cut gate `add.py release` applies before it records anything: a green suite, zero open security `HARD-STOP`, a closed-and-unreleased milestone to bundle, and every riding `RISK-ACCEPTED` waiver disclosed in the notes. Its four rejects are `release_security_open` (un-forceable) · `release_tests_red` · `release_no_closed_milestone` · `release_undisclosed_waiver`; `--force` may override every reject except the security stop.
+
+**RELEASES.md ledger** — the append-only, newest-first trail of release rows at the project root (date · version · milestones · waivers shipped · evidence). Like the §Key Decisions log it is never rewritten; a superseded or yanked version is recorded as a new row. The ledger is the attribution source — a milestone is "released" because a row says so — which is why the `→ releasable` cue never has to read a milestone file.
+
+**Hotfix release** — a narrowed PATCH cut that re-enters at Specify as a change request when a regression is found in a released version. It runs the same seven-step release flow scoped to the fix; releasing has no separate emergency mode, only the ordinary flow at a tighter scope.
+
 **Auto-ready goal** — a milestone goal whose every exit criterion **cites a verifier** (`(verify: <test|command|metric>)`), so the engine can self-verify the result against the goal without human judgment. It is the prerequisite by which **autonomy is earned by goal-clarity**: the **autonomy level** governs *who* resolves Verify, but a clarified, machine-checkable goal is what makes a self-verifying run meaningful. `add.py check` raises a `goal_not_auto_ready` **WARN** (never red) for the active milestone until it has an auto-ready goal (≥1 exit criterion and every one cited), and `status` surfaces it (`goal-ready: auto-ready ✓` / cited-of-total); a zero-criteria goal reads not-auto-ready and is milestone-shaping's nudge, not this warning's. The lint forces a citation *slot* per criterion — it raises the floor but **cannot prove the citation is real** (a human can write `(verify: it works)`): citation-theater is the accepted irreducible floor, and the freeze gate and autonomy behavior are unchanged by it.
 
 **Automated quality gate** (formerly "evidence auto-gate") — the Verify resolver under `autonomy: auto`: a run may auto-PASS on complete evidence, recorded as *auto-resolved*; a security finding always escalates (`HARD-STOP`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "ADD (AI-Driven Development) — a minimal, state-tracked Claude Code skill that drives every feature through Specify → Scenarios → Contract → Tests → Build → Verify → Observe. Ships the AIDD book as its trust layer.",
   "bin": {
     "add": "bin/cli.js"
@@ -8,6 +8,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@clack/prompts": "^1.5.1"
+  },
   "scripts": {
     "test": "python3 -m unittest discover -s tooling -p 'test_*.py'",
     "prepublishOnly": "python3 -m unittest discover -s tooling -p 'test_packaging.py'"

package/skill/add/SKILL.md

@@ -11,6 +11,15 @@ description: >-
   new feature and you want spec/tests-first discipline instead of vague-prompt
   coding. Also use it to resume work across sessions (it reads `.add/state.json`
   so you never re-read the whole repo).
+user-invocable: true
+when_to_use: "Invoke in any repo with a `.add/` directory, or when the user wants spec/tests-first feature work, resumes ADD work, or asks to start/advance a task."
+category: workflows
+keywords: [add, aidd, ai-driven-development, spec-first, tdd, contract, scenarios, verify, milestone, task-orchestration]
+argument-hint: "[describe your goals] OR [describe what is your expectation] (e.g., implement authentication flows for both server api and client side to handle email + Google OAuth login, session refresh, RBAC guards, and a profile page that survives page reloads)"
+license: MIT
+metadata:
+  author: add
+  version: "1.0.0"
 ---
 
 # ADD — the orchestration engine
@@ -25,6 +34,23 @@ you are so context never rots across sessions.
 
 ## Always start here (orient — do not skip)
 
+The engine lives at `.add/tooling/add.py` and the book at `.add/docs/`. Make sure the
+engine is in this project before anything else:
+
+- If `.add/tooling/add.py` exists, go straight to `status` below.
+- If it does NOT exist, ADD was installed as a Claude Code plugin — the engine and the
+  book ride in the plugin, not the project. Materialize them into the project once, before
+  any other step:
+
+  ```bash
+  node "${CLAUDE_PLUGIN_ROOT}/bin/cli.js" init --no-skill
+  ```
+
+  That drops `.add/tooling/` (the engine) and `.add/docs/` (the book) here, so the engine,
+  the book, and the agent-agnostic guideline block in `CLAUDE.md` all work for every agent
+  and for a human at the shell — exactly like an npm or pip install. The skill itself stays
+  in the plugin, so nothing is duplicated.
+
 Run the tool to find the resume point instead of re-reading the repo:
 
 ```bash
@@ -121,6 +147,13 @@ orchestration: gather `graduation-report` analytics → co-specify interview →
 milestone → human confirm → then (and only then) `stage production`. The flip is guarded
 (`stage_no_roadmap`) and is the FINAL step — never a bare label change.
 
+When one or more milestones have closed since the last release, `add.py status` prints
+**`→ releasable: N milestone(s) closed since last release`** — read `release.md` for the 5th scope
+level: gather `release-report` → draft notes from the consolidated deltas → meet the readiness floor
+(security HARD-STOP is un-forceable) → human confirms → `add.py release <version>` records the cut
+(CHANGELOG + `RELEASES.md` ledger + milestone attribution) → watch. The engine records; the human runs
+the tag / publish / deploy. A release bundles ≥1 milestone and is orthogonal to stage.
+
 ## Non-negotiable rules (from the method)
 
 <constraints>

package/skill/add/fold.md

@@ -1,60 +1,77 @@
-# Consolidating deltas — how the foundation self-improves
+# Consolidating lessons — how the foundation self-improves
 
-This **closes the loop**. `deltas.md` lets a task EMIT learnings (`open` lessons learned in its
-OBSERVE phase); the retrospective consolidation gathers the confirmed ones and writes them into a **versioned foundation**,
-so `DDD · SDD · UDD · TDD · ADD` sharpen across milestones instead of drifting.
+This **closes the loop**. `deltas.md` lets a task EMIT lessons (`open` lessons learned in its
+OBSERVE phase); the retrospective consolidation gathers the confirmed ones and writes them into a
+**versioned foundation**, so `DDD · SDD · UDD · TDD · ADD` sharpen across milestones instead of drifting.
 
-You (the AI) **gather and propose**; the **human confirms**; you then write the **append-only** consolidation.
-You never self-approve a consolidation — consolidating is judgment (see the verify/observe decision point).
+Since v3 this is mechanized by a command — `add.py fold` — but the command stays **judgment-free**:
+it only ever TRANSCRIBES each lesson's OWN captured text into its routed home and bumps the version.
+It NEVER composes or merges prose, and it never **self-approves** a consolidation — running the
+command records the human's confirmation, it does not replace their judgment. Deciding WHICH lessons
+to keep, and later polishing the raw transcribed bullets into lean one-screen prose, remain the
+human's work — the latter via the **compaction door** (`compact-foundation.md`).
 
 ## When to consolidate
 
 At **milestone close** (the natural "version bump to the foundation"), or **on demand** when open
-deltas have piled up. This is a convention, not a command — there is no `add.py fold`; the consolidation
-lives here so the engine stays judgment-free.
+lessons have piled up. One run of `add.py fold` is ONE consolidation session: it bumps
+`foundation-version` exactly once and stamps every lesson it resolves with that one new version.
 
 ## The ritual
 
-1. **Gather** — scan every task's §7 OBSERVE block for lesson-learned lines still `open` (`add.py deltas` reads them by the machine heading).
-2. **Group** — bucket them by competency (`DDD · SDD · UDD · TDD · ADD`).
-3. **Propose** — for each, draft the exact foundation edit (see routing) and show the human.
-4. **Confirm** — the human accepts or declines each delta. No write happens without this.
-5. **Write** — prepend the accepted edits at the top (newest-first), flip each delta's status, and bump the version.
+1. **Gather** — `add.py deltas` reads every task's OBSERVE block for lessons still `open` (by the machine heading).
+2. **Confirm** — decide which to keep; a lesson you do NOT want is marked `rejected` and left in place
+   (see below). Running `add.py fold` over the rest IS your confirmation — the command needs no separate flag.
+3. **Write** — `add.py fold [--task <slug>] [--comp <TAG>]` performs the mechanical write atomically:
+   - flips each selected `open` lesson to `folded` and stamps it `[folded foundation-version N]`;
+   - transcribes each lesson VERBATIM as one bullet at the TOP (newest-first) of its routed section (below);
+   - prepends one row to §Key Decisions (date · what · why · outcome);
+   - bumps `foundation-version` by one.
+   Validate-all-then-write: if any precondition fails the command writes NOTHING (the tree stays byte-identical).
+4. **Propose & polish** — the transcribed bullets are RAW; afterward you consolidate/merge them into
+   lean prose (append-only, newest-first) via the compaction door. The engine never does this editorial step.
 
 ## Consolidation routing (every competency has a home)
 
 | competency | consolidates into | how |
 |------------|-----------|-----|
-| `DDD` | `PROJECT.md` §Domain (DDD) | refine/append a model bullet |
-| `SDD` | `PROJECT.md` §Spec / Living Document (SDD) | refine/append a settled-vs-open line |
-| `UDD` | `PROJECT.md` §Users (UDD) | refine/append a UX line |
-| `TDD` | `CONVENTIONS.md` | append a testing convention (no PROJECT.md section — it is the engine) |
-| `ADD` | `CONVENTIONS.md` | append a build/harness convention (likewise the engine) |
+| `DDD` | `PROJECT.md` §Domain | a transcribed bullet at the top |
+| `SDD` | `PROJECT.md` §Spec | a transcribed bullet at the top |
+| `UDD` | `PROJECT.md` §Users | a transcribed bullet at the top |
+| `TDD` | `CONVENTIONS.md` §Method learnings | a transcribed bullet (no PROJECT.md section — it is the engine) |
+| `ADD` | `CONVENTIONS.md` §Method learnings | a transcribed bullet (likewise the engine) |
 
-**Every** consolidation — whatever the competency — ALSO prepends one row at the TOP of `PROJECT.md` **§Key Decisions** (newest-first)
-(date · decision · why · outcome): the universal, auditable trail of what the foundation learned.
+**Every** consolidation — whatever the competency — ALSO prepends one row at the TOP of `PROJECT.md`
+**§Key Decisions** (newest-first) (date · decision · why · outcome): the universal, auditable trail of
+what the foundation learned.
 
 ## Status transitions & version
 
-- on **confirm**: the delta moves `open` → `folded` (and its edit is prepended at the top of the routed target, newest-first).
-- on **decline**: the delta moves `open` → `rejected` and is **left in place** — never deleted —
+- on **confirm**: the lesson moves `open` → `folded` (its text transcribed at the top of the routed target, newest-first).
+- on **decline**: the lesson moves `open` → `rejected` and is **left in place** — never deleted —
   so "we considered this and chose not to act" stays auditable.
-- a consolidation is **append-only (newest-first)**: it PREPENDS new bullets/rows at the top and never silently rewrites existing foundation text — EXCEPT via the recorded **compaction door** (`compact-foundation.md`): eligible (shipped + zero open residues) stable entries collapse upward into a rolled-up settled line at the tail. Reject: `open-residue-version` · `trail-loss` · `wrong-order`.
-- each consolidation session **bumps** the `foundation-version:` marker in `PROJECT.md` by one (monotonic int).
+- a consolidation is **append-only (newest-first)**: it PREPENDS new bullets/rows at the top and never
+  silently rewrites existing foundation text — EXCEPT via the recorded **compaction door** (`compact-foundation.md`):
+  eligible (shipped + zero open residues) stable entries collapse upward into a rolled-up settled line at the tail.
+- each `add.py fold` run **bumps** the `foundation-version:` marker in `PROJECT.md` by one (monotonic int).
 
-## Reject codes (the AI is first check, the human the backstop)
+## Reject codes (the command is fail-closed; validate-all-then-write)
 
 <reject_codes>
-- `no_open_deltas` — nothing is `open` anywhere. The ritual is a no-op; do **not** bump the version.
-- `unconfirmed_fold` — a write was attempted without recorded human confirmation. The AI proposes;
-  it never self-approves one. Stop and get confirmation.
-- `unroutable_delta` — a delta's competency is not one of the five, so it has no consolidation target. Fix the
-  delta (it is malformed per `deltas.md`) before consolidating.
+- `no_open_deltas` — nothing is `open` in the selected scope. The session is a no-op; the version is NOT bumped.
+- `missing_route_section` — a lesson routes to a foundation section that does not exist (e.g. a `UDD`
+  lesson with no `## Users` section). Fail-closed: add the section header, then re-run. Nothing is written.
+- `no_foundation_version` — `PROJECT.md` carries no parseable `foundation-version:` marker to bump.
 </reject_codes>
 
+The convention-era codes `unconfirmed_fold` and `unroutable_delta` are **retired** (bridged here, not
+silently dropped): invoking `add.py fold` IS the confirmation, so `unconfirmed_fold` no longer applies;
+and routing is total over the five competencies, so a missing destination surfaces as the more precise
+`missing_route_section` rather than `unroutable_delta`.
+
 ## Worked example (from this repo's own history)
 
-The `competency-deltas` task closed its OBSERVE with two deltas — the homeless ones, `TDD`/`ADD`,
+The `competency-deltas` task closed its OBSERVE with two lessons — the homeless ones, `TDD`/`ADD`,
 which have no PROJECT.md section:
 
 ```
@@ -62,7 +79,8 @@ which have no PROJECT.md section:
 - [TDD · open] structural tests guard canonical artifacts but not their dogfood twins (evidence: scope-loop note + this build)
 ```
 
-At the next consolidation the human confirms both. Routing sends each to `CONVENTIONS.md` (a "sync the dogfood
-tree + assert md5 parity" convention), appends a §Key Decisions row for each, flips them to `folded`,
-and bumps `foundation-version` 1 → 2. The two competencies the foundation never tracked before now
-have a home — which is exactly why v5 routes TDD/ADD to `CONVENTIONS.md`.
+At the next consolidation the human keeps both and runs `add.py fold`. Routing transcribes each into
+`CONVENTIONS.md` §Method learnings, prepends a §Key Decisions row, flips them to `folded` with a
+`[folded foundation-version N]` stamp, and bumps `foundation-version` 1 → 2 — all in one atomic write.
+The two competencies the foundation never tracked before now have a home — which is exactly why v5
+routes `TDD`/`ADD` to `CONVENTIONS.md`.

package/skill/add/graduate.md

@@ -40,7 +40,8 @@ That line is the trigger. Before both tallies complete, status is silent and not
    is what these milestones *contain*; this guide proposes them, it does not do them.
 4. **Human confirms** — present the roadmap via `report-template.md`, opening with the ARC
    (goal · done · plan): the stage-graduation goal, the MVP coverage that earns the move, and the
-   plan the production milestones lay out. The human accepts, edits, or declines each drafted
+   plan the production milestones lay out. Render the roadmap as a guided choice — the recommended path
+   + its described alternatives (per `report-template.md`). The human accepts, edits, or declines each drafted
    milestone. No milestone is created without this; nothing advances on a draft the human has not confirmed.
 5. **Flip — the final step** — only now run `add.py stage production`. Because ≥1 production milestone
    now exists, the guard passes and the transition is recorded. This is the orchestration's last act.

package/skill/add/intake.md

@@ -35,6 +35,7 @@ First ask "does this change already-frozen scope?" → if yes, it is a `change-r
 
 Present the proposal to the human via `report-template.md` — open with the ARC (goal · done ·
 plan): the goal this request serves, what is already covered, and the plan the chosen bucket sets up.
+Render the proposal as a guided choice — the recommended bucket + its described alternatives (per `report-template.md`).
 
 For every request, emit ONE of:
 

package/skill/add/loop.md

@@ -37,10 +37,24 @@ When every task is done but the goal is not, `add.py status` shows
 4. **Create** each accepted task — `add.py new-task <slug> --title "..."` — and run it through
    the normal flow (specify → … → verify).
 5. **Repeat** until the work the goal needs is done.
-6. **Close** — when the goal is genuinely met, check the exit-criteria boxes in `MILESTONE.md`,
-   then `add.py milestone-done <slug>` succeeds (then consolidate the open deltas and archive).
-   Present the close via `report-template.md` — open with the ARC (goal · done · plan): the
-   milestone goal, the exit-criteria met that prove it, and the plan beyond the close.
+6. **Close** — when the goal is genuinely met, run the **ship review** before you close:
+   - **Fill the ship review first** — write the milestone's `## Close — ship review` section (the
+     scaffold ships in `MILESTONE.md`): **Ship by domain** — what changed per bounded context
+     (`tooling` · `skill` · `book`, or "untouched"); **Cross-task evidence** — one row per task
+     (`gate` · `tests` · `residue`); and the **Goal met?** map — each exit criterion tied to the
+     evidence that satisfies it. This is the whole-milestone, cross-task evidence the human READS;
+     it is evidence, **not a new gate**.
+   - **Check the boxes** — read that evidence, then check the exit-criteria boxes in `MILESTONE.md`
+     (the single affirmation — the same gate as ever), and `add.py milestone-done <slug>` succeeds
+     (then consolidate the open deltas and archive — the `milestone-done → fold → compact → archive`
+     lifecycle, per `fold.md` · `compact-foundation.md`).
+   - **Define the release steps** — write the milestone's `## Release steps` (merge is one small step
+     among them; PR, asset export, tag/publish are others — tool-agnostic hints the human runs).
+     These **feed** the release scope — read `release.md` for the cut; loop.md never re-specifies it.
+   Present the close via `report-template.md` — open with the ARC (goal · done · plan): the milestone
+   goal, the exit-criteria met (with the ship-review evidence) that prove it, and the plan beyond the
+   close. Render the close as a guided choice — the recommended next move + its described alternatives
+   (per `report-template.md`).
 
 ## Reopen is the verb; this loop is the trigger
 

package/skill/add/phases/0-setup.md

@@ -118,7 +118,7 @@ high-risk task still refuses `auto` and forces a lowered rung (run.md guard).
 
 ## 4 · The one human gate — the baseline approval
 
-Open the report with the ARC (goal · done · plan) per `report-template.md`, then present
+Open the report with the ARC (goal · done · plan) per `report-template.md`, render the baseline-lock DECISION as a guided choice (the recommended pick + described alternatives), then present
 `SETUP-REVIEW.md` lowest-confidence-first (the `guessed` rows are what the human must actually check). They
 confirm **once** — an explicit yes to the baseline approval itself, in conversation; ambient agreement mid-stream is
 not a confirmation. On that recorded confirmation, you run the lock with their name:

package/skill/add/phases/2-scenarios.md

@@ -28,6 +28,7 @@ Objective: one scenario per Must and per Reject rule, each result specific and o
 Steps:
   1. Write one scenario per Must rule and one per Reject rule.
   2. For every rejection add an And-clause asserting what must NOT change.
+  3. Sweep for the edge cases the spec omits — boundary, duplicate, partial failure, concurrency, malformed input — add one per case that applies, or rule it out on purpose.
 Never: settle for a vague result ("then it works") — results must be specific and observable.
 </prompt>
 
@@ -36,6 +37,7 @@ Never: settle for a vague result ("then it works") — results must be specific
 <exit_gate>
 - [ ] One scenario per Must rule.
 - [ ] One scenario per Reject rule.
+- [ ] Edge cases the spec omits are covered (boundary · duplicate · partial failure · …) or ruled out on purpose.
 - [ ] Each result is a specific, observable fact.
 - [ ] Every rejection asserts what stays unchanged.
 </exit_gate>

package/skill/add/phases/3-contract.md

@@ -20,7 +20,7 @@ work can start before the real code exists.
 **The freeze is the one approval.** This decision point is where the single human approval lands, over the
 whole bundle (§1–§4). Before asking for it, present the bundle **lowest-confidence first**: the 1–2 points
 most likely wrong (`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`) — aim the human's
-eye before they freeze. Open that report with the ARC (goal · done · plan) per `report-template.md` so the
+eye before they freeze. Open that report with the ARC (goal · done · plan) per `report-template.md`, rendering the freeze DECISION as a guided choice (the recommended pick + described alternatives), so the
 human sees the goal this freeze serves and the plan beyond it, not just the bundle. See `run.md`.
 The approval also freezes the §5 Scope (may touch) + Strategy declarations — the bundle covers them.
 

package/skill/add/phases/6-verify.md

@@ -66,7 +66,7 @@ redo, and only after the loop's cap does it HARD-STOP to the human (the loop liv
 ## Record exactly one outcome (no silent pass)
 
 When you present this gate to the human, open with the ARC (goal · done · plan) per
-`report-template.md`, and reconcile its FLAGS with `add.py report --decide`'s open-item count
+`report-template.md`, render the gate DECISION as a guided choice (the recommended pick + described alternatives), and reconcile its FLAGS with `add.py report --decide`'s open-item count
 before the ask — per that file's reconcile rule (verify is where a flag-vs-digest mismatch bites).
 
 | Outcome | When |