@pilotspace/add 1.6.0 → 1.7.1

package/docs/02-the-flow.md

@@ -83,7 +83,7 @@ The flow runs in two directions under two rules that never conflict. **Backward
 | 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; 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 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. Within that report the AI also presents the **DECISION** itself as a **guided choice** — one highlighted **recommended pick** (`▶ … (recommended)`) plus its real, described alternatives — so the human chooses with the recommendation and each option's consequence in view rather than a bare next-step line. Both are presentation only — they never add a gate or change an outcome, and the guided choice fires at human gates only. See [Appendix C](./appendix-c-glossary.md) and the `add` skill's `report-template.md` for the convention itself.
 
 ## What survives, and what is disposable
 

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

@@ -58,6 +58,10 @@ Scenario: not my account
 
 The `And no balance changes` line is doing real work: it specifies that a rejected transfer must leave the world untouched — a property the AI could easily violate by deducting before checking.
 
+## Cover the edge cases
+
+The transfer above is one domain; the same gaps recur in every domain — an HR leave request, a marketing campaign send, a checkout. Beyond the spec's "Reject" rules, sweep the recurring gaps and add a scenario for each that applies (or rule it out on purpose): boundary, duplicate/idempotent, ownership, stale/out-of-order, partial failure, concurrency, malformed input, limits/volume.
+
 ## The AI's role here
 
 Hand the AI the spec and have it draft a scenario for each rule, including the rejection rules. Then read them as the person who owns the requirement: do they describe what you actually meant? Correct any that drift. See `playbook/2_scenarios.md` in [Appendix B](./appendix-b-prompts.md).
@@ -65,6 +69,7 @@ Hand the AI the spec and have it draft a scenario for each rule, including the r
 ## Common mistakes
 
 - **Only happy-path scenarios.** Every "Reject" rule in the spec needs its own scenario, or that rule will never be verified.
+- **Edge cases left to the build.** A boundary, a duplicate, or a partial failure with no scenario becomes whatever the AI happens to code. Sweep the categories above against the task's domain.
 - **Vague results.** "Then it works" is not checkable. The result must be a specific, observable fact ("A has 70").
 - **Forgetting the unchanged state.** For any rejection, assert that nothing changed; otherwise a partial, corrupting failure can pass.
 
@@ -72,6 +77,7 @@ Hand the AI the spec and have it draft a scenario for each rule, including the r
 
 - [ ] Every "Must" rule has at least one scenario.
 - [ ] Every "Reject" rule has at least one scenario.
+- [ ] The edge-case categories that apply to this task's domain have a scenario (or are ruled out on purpose).
 - [ ] Each scenario's result is a specific, observable fact.
 - [ ] Rejections assert what must stay unchanged.
 

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

@@ -25,9 +25,12 @@ Verify can be resolved two ways, set per task by the `autonomy:` header (see [go
 
 ## Part one — confirm the evidence
 
+Before the build, the task pre-declares its **build expectations** — the observable outcomes a correct build must produce, read off §2's scenarios and §3's contract. Confirm each one here against evidence you can see, not a restated test name: this is what makes the gate check the build is *right*, not merely that the suite is green.
+
 - [ ] All tests pass.
 - [ ] Coverage did not decrease.
 - [ ] No test or contract was altered during the build.
+- [ ] Every pre-declared build expectation is confirmed by real evidence (not merely a green test).
 
 If any of these is false, stop here and return to the build; there is nothing to verify yet.
 
@@ -71,6 +74,7 @@ A security finding is always a `HARD-STOP`; it is never waved through with a wai
 ## The verification checklist
 
 - [ ] All tests pass (the evidence).
+- [ ] Every pre-declared build expectation is confirmed by observable evidence.
 - [ ] Concurrency/timing of the risky operation is safe.
 - [ ] No exposed secrets, injection openings, or unexpected dependencies.
 - [ ] Layering and dependencies follow `CONVENTIONS.md`.

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/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`.
@@ -80,6 +84,10 @@
 
 **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "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
@@ -37,7 +63,9 @@ python3 .add/tooling/add.py status
 (the `soul-self-improve` path proposes voice deltas the human confirms).
 
 - **No `.add/state.json` yet** (a fresh install drops tooling + docs but does *not* init — so `status` says
-  `no .add/ project found`) → enter **autonomous setup**: YOU run init yourself —
+  `no .add/ project found`) → enter **autonomous setup**: first, if `.add/.intent` exists, read it — the
+  one-line first-build intent the user gave the installer (a NOTE, never an init trigger) — and let it seed
+  your kickoff suggestion (`phases/0-setup.md`); then YOU run init yourself —
   `add.py init --name "<inferred>" --stage <picked> --await-lock` (don't tell the human to) — then read
   `phases/0-setup.md` and draft the foundation + first scope + first contract through to the human baseline approval.
 - **A task is active** → open `.add/tasks/<active>/TASK.md`, look at its `phase:`
@@ -84,7 +112,7 @@ See `run.md`.
 
 Whenever you present a decision point to the human in chat (intake · bundle approval · gate ·
 milestone close), follow `report-template.md` — open with the ARC (goal · done · plan,
-engine-sourced), then SUMMARY → DECISION → ⚠ FLAGS → EVIDENCE → NEXT, show-before-ask, never
+engine-sourced), then SUMMARY → DECISION → FLAGS → DECIDED → EVIDENCE → NEXT, show-before-ask, never
 pre-stamp a decision point — and the question is a summary, never the artifact.
 
 In **observe**, also emit **lessons learned** — learnings tagged by which of the five

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

@@ -31,10 +31,16 @@ First ask "does this change already-frozen scope?" → if yes, it is a `change-r
 → `new-major`; a slice of a live theme → `sub-milestone`; fits the active milestone
 → `task`.
 
+**One-task gap rule.** If the request is ONE task but does NOT fit the active milestone's
+stated scope, do NOT force it into `sub-milestone` (which requires "too big for one task").
+Instead: create a new micro-milestone to house it (`new-milestone` + `new-task`). The
+micro-milestone gives the task ledger attribution and clear exit criteria without inflating scope.
+
 ## What you emit (the proposal)
 
 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

@@ -12,11 +12,20 @@ sufficient. Fill **§6** in TASK.md including the GATE RECORD.
 > or whenever residue is found, this phase is **human-led** and the checks below
 > are the human's.
 
+## Before you build — declare the build expectations
+
+Fill the §6 **Build expectations** block BEFORE you start Build: the OBSERVABLE outcomes a
+correct build must produce, derived from §2 SCENARIOS + §3 CONTRACT. At this gate, confirm each
+one against real evidence (the `confirmed by` column) — so verify proves the build is *correct*,
+not merely that the suite is green. An expectation with no evidence is not yet verified; passing
+tests on inputs you thought of never substitute for the outcome you promised.
+
 ## Part one — confirm the evidence
 
 - [ ] All tests pass.
 - [ ] Coverage did not decrease.
 - [ ] No test or contract was altered during build.
+- [ ] Every §6 Build expectation is confirmed by real evidence (not just a green test).
 
 If any is false, stop and return to Build — there is nothing to verify yet.
 
@@ -66,7 +75,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 |

package/skill/add/release.md

@@ -47,7 +47,8 @@ One arc, seven steps: **cue → gather → draft notes → readiness floor → h
    never auto-passed, never shipped silent.
 4. **Human confirms the cut** — present via `report-template.md`, opening with the ARC (goal · done · plan):
    the version you are shipping, the milestones + evidence that earn it, and the rollout + watch plan that
-   follows. Show the drafted notes, the version, and the waivers being shipped. The human approves once
+   follows. Render the cut as a guided choice — the recommended version + its described alternatives
+   (per `report-template.md`). Show the drafted notes, the version, and the waivers being shipped. The human approves once
    (the decision point) — never pre-stamped; you surface a summary to decide on, not the artifact itself.
 5. **Cut — record the marker** — only now run `add.py release <version> --notes <file>`. The engine
    **records**: it prepends the CHANGELOG entry, stamps one append-only row (newest-first) in

package/skill/add/report-template.md

@@ -8,12 +8,12 @@ replacement for the digest.
 Use it every time you report at or near a decision point: an intake proposal, a
 bundle approval, a verify gate, a task completion, a milestone close.
 
-## The decision arc — rendered first, above the five blocks
+## The decision arc — rendered first, above the report blocks
 
 Every report at a human gate opens with the **ARC** — three labelled lines that
 place the decision in the work's whole arc, so the human confirms with sight of
 where this is going, not just the step in front of them. Render it first, then a
-separator, then the unchanged five blocks below:
+separator, then the report blocks below:
 
 ```
 ARC  goal: <the milestone / project goal this decision serves>
@@ -48,35 +48,91 @@ and `add.py` output disagree, the engine wins — fix the arc, not the engine.
 - **intake** — `goal:` the sized request · `done:` classified new-major,
   rationale stated · `plan:` create the milestone → first contract → goal.
 
-## The five blocks, in order
+## The report blocks, in order
+
+The blocks below are the CORE set, rendered in order at every decision-point
+report. Render every one (write "none" rather than dropping a block); add MORE
+blocks when a specific report needs them (see "Beyond the core blocks" below).
 
 ```
-SUMMARY   one line: intent + target + where we are
-DECISION  what you need from the human (or "none — FYI")
-⚠ FLAGS   lowest-confidence first, why + cost-if-wrong
+SUMMARY   one line: intent + target + where we are + what we done
+DECISION  what you need from the human (or "none — FYI") — exactly one
+FLAGS     lowest-confidence first: why + cost-if-wrong
+DECIDED   highest-confidence first: the autonomous calls you made + why each was safe
 EVIDENCE  small table: tests · gates · parity · check — engine-sourced
-NEXT      the single next action + what it unlocks
+NEXT      the recommended next actions, ranked (top ▶ highlighted, bolded) + what each unlocks
 ```
 
 1. **SUMMARY** — one line carrying intent + target + position, e.g.
    "v13 task 2/3 — tests-declared-fallback is green, gate PASS." The reader
    knows where they are before they read anything else.
-2. **DECISION** — the question the human must answer, stated plainly; exactly
-   one decision per report, or an explicit "none — FYI". If a decision exists,
-   ask it AFTER everything below has been shown (show-before-ask).
-3. **⚠ FLAGS** — lowest-confidence first, each with *why* confidence is lowest and the
+2. **DECISION** — the question the human must answer, presented as a **guided
+   decision**: lead with the one **recommended pick** marked `▶ … (recommended)`,
+   then its **1–3** described alternatives, every option carrying a one-line
+   description (see "guided choice" below). Exactly one decision per report, or an
+   explicit "none — FYI". If a decision exists, ask it after everything below has
+   been shown (show-before-ask).
+3. **FLAGS** — lowest-confidence first, each with *why* confidence is lowest and the
    *cost if wrong*. Where TASK.md markers exist (`⚠` / `- [~]` / `- [ ]`),
    quote them verbatim and keep their document order — extraction ≠ judgment.
-4. **EVIDENCE** — engine-sourced facts pasted from `add.py` output, never
+4. **DECIDED** — the counterpart to FLAGS: the high-confidence calls you settled
+   autonomously WITHOUT a gate, highest-confidence first, each with *why* it was
+   safe (the change-type or evidence that earned the autonomy). FLAGS surfaces the
+   lowest-confidence calls so the human can challenge them; DECIDED surfaces the
+   highest-confidence ones so the human can see what you closed without asking. "none" when you made no
+   autonomous calls. NEVER list a security / residue / lowered-autonomy call here —
+   those always escalate in DECISION (see the Hard rules), never auto-decided.
+5. **EVIDENCE** — engine-sourced facts pasted from `add.py` output, never
    re-typed from memory. If your prose and the engine disagree, the engine
    wins: fix the engine or the data, not the sentence.
-5. **NEXT** — one action and what it unlocks. Mirror the rollup's DECIDE NEXT
-   line when it is right; overrule it only with a stated reason (e.g. planned
+6. **NEXT** — the recommended next actions as a ranked list, the top one marked
+   `▶` and each with what it unlocks. NEXT is **informational, not a second gate**:
+   it shows the menu of what's next and never adds a decision — the one decision
+   stays the DECISION block. Mirror the rollup's DECIDE NEXT line for the top
+   action when it is right; overrule it only with a stated reason (e.g. planned
    tasks the state file cannot see yet).
 
-**The ask itself** — when block 2's decision becomes a literal question component
-(option picker, numbered menu), compose it as a summary: the detail stays in the
-report above, the question carries intent + what "yes" means + the flag count.
+### Beyond the core blocks — add more when the decision needs it
+
+The six blocks above are the CORE set. When a specific report needs more than they
+carry — a `RISK` ledger, a `DIFF`, a `SCOPE` map, a `COST` estimate — add an extra
+block in the same shape (SCREAMING-CASE label · one-line intent · engine-sourced
+where it can be), placed AFTER EVIDENCE and BEFORE NEXT so NEXT always closes the
+report. Add a block only when it carries what the core six don't; never pad to look
+thorough — and never drop a core block; render "none" instead.
+
+### The DECISION block as a guided choice
+
+When the human must choose, render block 2 as a **guided decision** — never a bare next step:
+
+```
+DECISION  <the question>
+
+  ▶ <recommended option>  (recommended)
+      <one-line description — what it means · what it unlocks or costs>
+    <alternative option>
+      <one-line description>
+    <alternative option>
+      <one-line description>
+```
+
+- **Recommended pick** — exactly one option carries the `▶ … (recommended)` marker; never zero,
+  never two. Your `confidence.md` self-score informs which to recommend; the human overrides freely
+  (a recommendation, not a default that auto-proceeds).
+- **1–3 described alternatives** — only real, takeable options (no strawmen). If there is genuinely
+  one path, show the single recommended step + its description — never invent filler to reach three.
+- **Every option is described** — the pick and each alternative carry a one-line description (what
+  it means + what it unlocks or costs); ≤1 line, no bare labels.
+- **Human gates only** — render the guided choice at `[human gate]` decision points; at a
+  `[you drive]` autonomous step there is no human to choose, so render none. Show-before-ask still
+  holds — the described choice is the ASK, rendered after EVIDENCE.
+
+**The ask itself** — when block 2's decision becomes a literal question component (an
+`AskUserQuestion` picker or a numbered menu), compose it as the guided choice above: the
+**recommended option goes first, with a `(Recommended)` suffix**, and each option's `description`
+carries its one-line description. On a tool without `AskUserQuestion`, render the same shape as a
+numbered/`▶` menu in chat — the convention is tool-agnostic. The question text stays a summary —
+intent + what "yes" means + the flag count — pointing at the report above.
 
 ## Hard rules
 
@@ -84,7 +140,11 @@ report above, the question carries intent + what "yes" means + the flag count.
 - **Summary-first.** Never bury the decision under a task list or a diff.
 - **Show before ask.** Render the artifact (digest · diff · report) before any
   approval question; the human decides on what they can see.
-- **Reconcile the count.** Before the ask, your ⚠ FLAGS must reconcile with
+- **Guided decision.** At a `[human gate]`, present block 2 as a guided choice — one highlighted
+  **recommended pick** (`▶ … (recommended)`, exactly one) + its 1–3 described alternatives, every
+  option carrying a one-line description; never a bare next step. `confidence.md` informs the pick;
+  the human overrides freely. Not at `[you drive]` autonomous steps.
+- **Reconcile the count.** Before the ask, your FLAGS must reconcile with
   `add.py report --decide`'s open-item count. If your prose calls an item
   resolved while the digest still counts it open, the engine wins — fix the data
   (the TASK.md markers the digest reads), not the sentence. A report whose flag
@@ -97,10 +157,14 @@ report above, the question carries intent + what "yes" means + the flag count.
 - **Honest scope.** "Done" means the request, not the last task: report
   "task 2/3", never "done" while approved scope remains.
 - **The question is a summary, never the artifact.** Every approval ask carries
-  two layers: a compact SUMMARY · DECISION · ⚠ FLAGS block sits in chat
+  two layers: a compact SUMMARY · DECISION · FLAGS block sits in chat
   immediately before the ask (positional), and the question text itself is a
   summary of two lines at most — intent + what "yes" means + the flag count —
   pointing at the report above (compositional). The full bundle, diff, or
   artifact lives only in the chat report; a question that re-carries it buries
   the decision.
+- **NEXT is not a second gate.** NEXT lists recommended next actions (ranked, top
+  `▶`); the single decision stays the DECISION block — NEXT never carries an approval ask.
+- **DECIDED never holds a gate-class call.** A security / residue / lowered-autonomy
+  call is escalated in DECISION, never reported as already auto-decided in DECIDED.
 </constraints>