@pilotspace/add 1.8.0 → 1.9.0

package/skill/add/run.md

@@ -1,57 +1,39 @@
 # The dynamic run — executing a locked scope
 
-Once a task's CONTRACT is frozen (phase 3), the scope is *locked*: the external shape will not move.
-That lock is ADD's autonomy decision point — below it code is disposable; above it nothing breaks. This rubric
-covers what runs on the far side of the decision point: the **build->verify half, executed as a dynamic,
-self-improving run** instead of a manual, sequential build. The human-led **specification bundle** (Specify · Scenarios
-· Contract) still owns *direction*, but v7 compresses it to a **single human approval at the decision point**
-(see "The specification bundle" below) — the AI drafts the whole bundle, a human approves it once.
-
-> **Self-improving = within-run convergence + emit v5 deltas** — same definition as v5: tracked,
-> evidence-backed, never autonomous training. The run converges in-turn AND feeds the human-gated
-> consolidation loop (`deltas.md` · `fold.md`). The engine stays judgment-free: this is a rubric, not `add.py`.
+Once a task's CONTRACT is frozen (phase 3), the scope is *locked*. That lock is ADD's autonomy
+decision point — below it code is disposable; above it nothing breaks. This rubric covers the
+**build->verify half, executed as a dynamic, self-improving run**. The human-led **specification
+bundle** (Specify · Scenarios · Contract) still owns *direction*, but v7 compresses it to a
+**single human approval at the decision point** — the AI drafts the whole bundle, a human approves
+it once. The engine stays judgment-free: this is a rubric, not `add.py`.
 
 ## The specification bundle (v7)
 
-The specification bundle used to be three separate approvals — Specify, then Scenarios, then the Contract
-freeze. v7 compresses it to **one**. From the user's input the AI **drafts the whole specification bundle in one pass** — the Spec, the Scenarios, the Contract, and the failing Tests — and presents it together. The
-human gives **one approval, at the frozen contract** (the decision point). That single approval is the green light
-for the self-driving run.
-
-Why one approval and not zero: the contract freeze is the autonomy decision point, and the decision point **stays human**.
-The AI *drafts* the contract but never *freezes its own* — a person approves the frozen shape before any
-auto-run touches code. This is exactly what keeps "never self-gate a human-led gate" true under an auto
-default: the one gate that remains is human. Drop it to zero and the AI would freeze the interface it
-then builds against and self-gate the result — the circular trust v6's dogfood warned against.
-
-What the human is actually approving in that one gate: that the drafted Spec captures the real intent,
-that the Scenarios cover the cases that matter, and that the Contract shape is the one to freeze. Reject
-any part and the bundle goes back to draft — that is backward-correction (principle 4), not failure.
-Approve, and the run begins. The decision-point guide (`phases/3-contract.md`) carries the
-**freeze review checklist** — seven lines that walk the human through exactly this, ⚠-first.
-
-**The lowest-confidence flag — aiming the one approval.** A single approval over a whole bundle is easy to
-grant without reading. So the AI presents the bundle **lowest-confidence first**: of everything it is asking the human
-to freeze, it names the **1–2 points most likely to be wrong**, tagged by part
-(`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`), each with *why* it is uncertain and
-*what it costs if wrong*. The §1 assumptions feed it, but a flag may equally point at an uncovered
-scenario or the contract shape. If nothing is materially uncertain, the AI still names the single
-biggest risk, however small — never a blank "none". Honest about its limit: the flag records that the
-human approved with the soft spots **in front of them**, eyes open; it makes a real review cheap and a
-lazy one visibly negligent, but it cannot *force* engagement — and the AI never asserts that the human
-engaged when it cannot know (a self-asserted gate would just move the unread approval one level up). Closing
-that enforcement gap is the job of a CI checker, not of prose.
+v7 compresses the old three-approval flow to **one**. The AI **drafts the whole specification
+bundle in one pass** — Spec, Scenarios, Contract, and failing Tests — and presents it together.
+The human gives **one approval, at the frozen contract** (the decision point).
+
+Why one and not zero: the decision point **stays human**. The AI *drafts* the contract but never
+*freezes its own* — a person approves the frozen shape before any auto-run touches code. What the
+human approves: that the Spec captures real intent, the Scenarios cover the cases that matter, and
+the Contract shape is the one to freeze. Reject any part and the bundle goes back to draft —
+backward-correction (principle 4), not failure. The decision-point guide (`phases/3-contract.md`) carries the **freeze review checklist** —
+seven lines that walk the human through exactly this, ⚠-first.
+
+**The lowest-confidence flag.** The AI presents the bundle **lowest-confidence first**: the
+**1–2 points most likely to be wrong**, tagged by part
+(`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`). The `because` names the §1
+assumption that makes it uncertain; the `if wrong` names what it costs if that assumption is off.
+If nothing is materially uncertain, the AI still names the single biggest risk — never a blank "none".
+Raising this flag is honor-system: the lint cannot force the AI to engage with it — closing that
+gap is a CI checker's job, not prose.
 
 ## When the run begins — the scope-lock trigger
 
-The trigger is the **frozen contract**, nothing else. A run may start only when:
-
-- §3 CONTRACT is marked `FROZEN @ vN` (the shape is fixed), AND
-- §4 TESTS exist and are RED for the right reason (the target the run drives to green).
+The trigger is the **frozen contract**, nothing else. A run may start only when §3 CONTRACT is
+marked `FROZEN @ vN` AND §4 TESTS exist and are RED for the right reason.
 
-No frozen contract -> no run: you are still inside the specification bundle, and starting early is the
-forward-skip the flow forbids. The lock is what makes autonomous execution *safe* — the AI cannot
-drift the interface, because the interface is frozen above it.
+No frozen contract -> no run: starting early is the forward-skip the flow forbids.
 
 ## The change scope — what the run may and may not touch
 
@@ -59,156 +41,104 @@ drift the interface, because the interface is frozen above it.
 A locked run has a hard boundary. It MAY:
 
 - write and rewrite **code** (`src/`) — code is disposable below the decision point;
-- drive the **tests** to green WITHOUT weakening them (a weakened test is a method violation);
+- drive the **tests** to green WITHOUT weakening them;
 - gather **evidence** for the verify gate (test output, non-functional review).
 
 It MUST NOT:
 
 - change the **frozen contract** or the **locked scope** — a discovered gap is backward-correction:
-  the run STOPS and hands back to a human to reopen Specify (principle 4). The run never re-locks
-  scope on its own.
-- weaken, delete, or skip a **test** to make the build pass (that inverts the method).
+  the run STOPS and hands back to a human to reopen Specify (principle 4).
+- weaken, delete, or skip a **test** to make the build pass.
 - touch the **specification-bundle artifacts** (§1–§3) except to halt and escalate.
 </constraints>
 
-Crossing the boundary is not a fast run; it is an unverified one. When the run hits something only the
-specification bundle can resolve, it stops — and that stop is the loop working, not failing.
-
 ## The dynamic run — fan-out and in-run convergence
 
-Once it starts, the run does not crawl the build in one linear pass. It **fans out** the independent
-work — several build attempts, several test-fix loops, several checks at once — and then **converges**
-on a trustworthy result with three loops:
+The run **fans out** independent work and **converges** with three loops:
 
-- **loop-until-dry** — keep hunting failures and gaps until N consecutive passes find nothing new.
-  Stopping at the first green is how defects survive; the run stops only when the well runs dry.
-- **adversarial verify** — for every "done" claim, an independent skeptic tries to REFUTE it. The
-  claim survives only if it withstands refutation, not because one pass looked plausible.
-- **completeness-critic** — a final pass that asks "what did we NOT cover — a scenario, a non-functional risk,
-  an unstated assumption?" Whatever it finds re-enters the run.
+- **loop-until-dry** — keep hunting failures until N consecutive passes find nothing new.
+- **adversarial verify** — an independent skeptic tries to REFUTE every "done" claim.
+- **completeness-critic** — a final pass asking "what did we NOT cover?" Whatever it finds re-enters.
 
-The run ends only when the loops go dry AND the auto-gate's evidence is satisfied. This is the run
-**self-improving within the turn** — the same convergence the foundation loop runs across milestones,
-compressed into one task.
+The run ends only when the loops go dry AND the auto-gate's evidence is satisfied.
 
 ## The automated quality gate
 
 <constraints>
-The verify gate may be resolved by **evidence** rather than by a person — when the evidence is
-sufficient and the result is recorded (principle 7, reframed: an automated, recorded pass is an
-explicit pass, not a skip).
+The verify gate may be resolved by **evidence** rather than by a person (principle 7: an automated,
+recorded pass is an explicit pass, not a skip).
 
 - **Auto-PASS requires ALL of:** every test green; coverage not decreased; no test weakened and no
-  contract edited; the convergence loops dry; the completeness-critic found nothing open; and the
-  deep check below recorded.
-- **The deep check (every gate, no skim).** 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. An unfilled deep check is
-  a **shallow verify**, not an auto-PASS — evidence the work is wired, not merely plausible.
+  contract edited; loops dry; completeness-critic clean; and the deep check below.
+- **The deep check (every gate, 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. An unfilled deep check is a **shallow verify**, not an auto-PASS.
 - **Always escalates to a human (never auto-passed):** any **security** finding (HARD-STOP, always);
-  a **concurrency**/timing risk the tests cannot exercise; an **architecture**/layering violation; and
-  any failing test. These are the residue principle 2 names — automation cannot judge them.
-- **Records exactly one outcome** (no silent skip): `PASS` (evidence + the named run as accountable
-  owner) · `RISK-ACCEPTED` (non-security, signed) · `HARD-STOP`. The record states it was
-  auto-resolved, names the run, and lists the residue checks performed.
-
-The auto-gate NEVER writes a human signature it did not get. An auto-PASS is logged as *auto-resolved*,
-honestly — the line between a pass and a skip is the recorded outcome, not a forged name.
+  a **concurrency**/timing risk the tests cannot exercise; an **architecture**/layering violation;
+  any failing test.
+- **Records exactly one outcome** (no silent skip): `PASS` · `RISK-ACCEPTED` · `HARD-STOP`. The
+  record states it was auto-resolved, names the run, and lists the residue checks performed.
+
+The auto-gate NEVER writes a human signature it did not get.
 </constraints>
 
-## The bounded self-heal loop — a confirmed cheat returns to build
+## The bounded self-heal loop
 
-The auto-gate trusts evidence; but evidence can be **gamed**. A build can make the unchanged red suite
-pass without EARNING it — a test or the frozen contract edited after the red run, src **overfit** to the
-fixtures, **vacuous** asserts, or real logic **stubbed away**. That is a **confirmed cheat**, and a cheat
-is **HARD-STOP-class**: never auto-passed, never RISK-ACCEPTED-waived (like a security finding). But a
-first cheat is not yet a stop — it is a chance to redo honestly.
+Evidence can be **gamed** — test or contract edited after the red run, src overfit to fixtures,
+vacuous asserts, or real logic stubbed away. That is a **confirmed cheat**: HARD-STOP-class, never
+auto-passed, never RISK-ACCEPTED-waived.
 
-So a confirmed cheat enters a **bounded self-heal loop**: the engine returns the task to **build** for an
-honest redo, **counts** the attempt, and **caps** it. After **3** honest re-build attempts a fourth
-confirmed cheat forces a **HARD-STOP that escalates to the human** — never an auto-PASS, never an unbounded
-loop. The engine COUNTS, CAPS, and ESCALATES; the **agent** does the honest re-build (the engine never
-auto-fixes). The counter is **monotonic** — it never auto-resets, so the cap cannot be cleared by
-re-crossing a phase; only an honest build (no cheat) escapes the loop, and an honest build PASSes even at
-the third attempt (the cap bites a *continued* cheat, never a recovery).
+A first cheat enters a **bounded self-heal loop**: the engine returns the task to **build** for an
+honest redo, counts the attempt, and caps it. After **3 honest** re-build attempts a fourth confirmed
+cheat forces a **HARD-STOP** that escalates to the human. The counter is **monotonic** — only an
+honest build escapes.
 
 Two findings enter the loop:
-- **mechanical** (enforced) — the tamper tripwire (`tamper-tripwire`): at the gate the engine re-hashes the
-  red test files + the frozen §3 against the `tests→build` snapshot; any divergence is a cheat, routed to
-  the loop before any completing outcome is recorded.
-- **semantic** (honor-system, necessary-not-sufficient) — the **adversarial refute-read** (`6-verify.md`):
-  an independent reviewer argues "the green was NOT earned" and, on a confirmed overfit/vacuous/stub, the
-  agent reports it with `add.py heal <slug> --reason "<finding>"`. The engine cannot SEE a judgment cheat,
-  so this entry is the agent's honest report — the human verify gate stays the real backstop.
+- **mechanical** (enforced) — the tamper tripwire: at the gate the engine re-hashes the red test
+  files + frozen §3 against the `tests→build` snapshot; any divergence routes to the loop.
+- **semantic** (honor-system) — the **adversarial refute-read** (`6-verify.md`): on a confirmed
+  overfit/vacuous/stub the agent reports it with `add.py heal <slug> --reason "<finding>"`.
+  The engine cannot see a judgment cheat, so this entry is the agent's honest report — the human
+  verify gate stays the real backstop.
 
-The mechanical entry returns-to-build automatically at the gate; the `heal` verb is how a *reported* cheat
-enters the same bounded loop. Either way: ≤3 honest redos, then escalate. A gamed green never ships.
+Either way: ≤3 honest redos, then escalate. A gamed green never ships.
 
 ## Emitting deltas — feeding the foundation back
 
-The completeness-critic does not discard what it finds. Every gap, surprise, or convention that helped
-or hurt becomes an **`open` lesson learned** in the task's OBSERVE block, in the `deltas.md` grammar,
-tagged by competency:
-
-- a finding the run FIXED but that taught the foundation something (a missing scenario -> `TDD`);
-- a finding the run could NOT fix — a residue escalation -> a delta AND the escalation to a human.
-
-These `open` deltas feed v5's human-gated consolidation (`fold.md`) at milestone close: the run emits `open`;
-the human consolidates. That is the loop closing — **v6 run -> v5 foundation** — so a dynamic run sharpens the
-five competencies instead of letting its findings evaporate at end-of-run.
+Every gap the completeness-critic finds becomes an **`open` lesson learned** in the task's OBSERVE
+block (`deltas.md` grammar). These `open` deltas feed v5's human-gated consolidation (`fold.md`)
+at milestone close — the loop closing: **v6 run -> v5 foundation**.
 
 ## The autonomy level
 
 <constraints>
-How much a run may auto-gate is a **per-scope setting**, not a global switch (principle 5: trust is
-earned per scope). A task declares its level in its `TASK.md` header:
+How much a run may auto-gate is a **per-scope setting** (principle 5). A task declares it in its
+`TASK.md` header — this is not an add.py flag; it is a rubric convention:
 
 ```
 autonomy: manual | conservative | auto
 ```
 
-An ordered ladder — `manual < conservative < auto` — declared once in the header and reviewed at the freeze:
-
-- **auto (the seeded default)** — the run may auto-PASS when the evidence + residue checks above are
-  satisfied. Security still always escalates. This is the default starting point: a frozen contract
-  flips the task into a self-driving run that converges and auto-gates on evidence.
-- **conservative** — the deliberate *lowering*: the run does all the work and converges, but STOPS at
-  the verify gate for a human. Auto-PASS is disabled. Choose it wherever evidence is thin or risk is high.
-- **manual** — the strict floor: the human owns the verify gate and the engine never auto-resolves
-  (behaviourally the conservative floor with the explicit "I drive this decision; the AI proposes only"
-  name). Choose it for the highest-stakes scope; like `conservative`, it satisfies the high-risk guard.
-
-> **v7 reversal (recorded, not hidden).** Earlier the default was `conservative` and `auto` was the
-> earned exception; v7 flips this — `auto` is the default, `conservative` is the deliberate lowering.
-> What did **not** change is principle 5: the autonomy level is still **per-scope**, and it still lives in the
-> `TASK.md` header, and you still lower it anywhere risk demands. Only the starting point moved.
-
-**The high-risk guard — `auto` is refused where it matters most.** The autonomy level is not a blank cheque. On a
-**high-risk or method-defining scope** — anything where a wrong-but-plausible result is expensive or
-hard to reverse (auth, money, data-loss paths, the method/trust-layer itself) — `auto` must be lowered
-to a stricter rung — `conservative` or `manual`; leaving it at `auto` there is the reject code
-**`unguarded_high_risk_auto`**. This
-closes the v6 dogfood gap, where the whole milestone ran at `auto` on the riskiest possible
-scope (defining the method) with no friction. The default is `auto` *for ordinary, well-tested scope*;
-high risk still earns a human gate.
-
-Judging *what* is high-risk stays human — the scope declares **`risk: high`** in the same `TASK.md`
-header where the autonomy level lives, reviewed at the freeze like every header line (the engine never
-classifies scope). **Since v14 the guard is mechanical for the declared case:**
-the engine refuses the declared combination — `add.py gate` will not complete (`PASS`/`RISK-ACCEPTED`) a task whose header
-carries `risk: high` without a lowered level — `conservative` or `manual` (error `unguarded_high_risk_auto`; `HARD-STOP`
-always records — stopping is never blocked), and `add.py audit` flags the same code on a finished
-record whose header was tampered or whose GATE RECORD reviewer is the auto-gate — which CI enforces
-(audit-ci). The honest limit mirrors the audit's: an **undeclared** high-risk scope passes; declaring
-is the human decision point, the engine enforces what was declared.
-
-**Autonomy is earned by goal-clarity — the auto-ready goal.** The level decides *who* resolves Verify;
-an **auto-ready goal** decides whether a self-verifying run is even *meaningful*. A milestone goal is
-auto-ready when **every exit criterion cites a verifier** — `(verify: <test | command | metric>)` — so the
-run can check its own result against the goal without human judgment. `add.py check` raises a
-`goal_not_auto_ready` WARN (never red, the active milestone only) while criteria are uncited, and `status`
-prints a `goal-ready:` line every session. It **measures, never blocks** — it changes neither the freeze
-gate nor the autonomy level. The lint forces a citation slot per criterion (raising the floor) but cannot
-prove the citation is honest (`(verify: it works)` passes) — that judgment stays the human's.
+- **auto (the default)** — the run may auto-PASS when evidence + residue checks are satisfied.
+  Security still always escalates.
+- **conservative** — the deliberate *lowering*: the run converges but STOPS at the verify gate.
+- **manual** — the strict floor: the human owns the verify gate; the engine never auto-resolves.
+
+> **v7 reversal (recorded).** Earlier the default was `conservative`; v7 flips it — `auto` is the
+> default, `conservative` is the deliberate lowering. The level is still **per-scope** and is
+> lowered wherever risk demands.
+
+**The high-risk guard.** On a **high-risk or method-defining scope** `auto` must be lowered to
+`conservative` or `manual`; leaving it at `auto` is the reject code **`unguarded_high_risk_auto`**.
+The scope declares **`risk: high`** in the `TASK.md` header (the engine never classifies scope).
+Since v14 the guard is mechanical for the declared case:
+the engine refuses the declared combination — `add.py gate` will not complete (`PASS`/`RISK-ACCEPTED`)
+a task whose header carries `risk: high` without a lowered level (`HARD-STOP` always records);
+`add.py audit` flags finished records whose header was tampered or whose GATE RECORD reviewer is
+the auto-gate (CI enforces). An undeclared high-risk scope passes — a scope without `risk: high`
+in its header is not blocked by the v14 mechanical guard.
+
+**Autonomy is earned by goal-clarity — the auto-ready goal.** A milestone goal is auto-ready
+when **every exit criterion cites a verifier** — `(verify: <test | command | metric>)`.
+`add.py check` raises a `goal_not_auto_ready` WARN while criteria are uncited, and `status`
+prints a `goal-ready:` line every session. It **measures, never blocks**. The lint cannot prove
+the citation is honest — `(verify: it works)` passes the check — that judgment stays the human's.
 </constraints>

package/skill/add/scope.md

@@ -1,121 +1,72 @@
 # Scope drafting — turn a classified request into a versioned MILESTONE.md
 
-This is the **second half of intake**. `intake.md` CLASSIFIES a request into a bucket; scope
-drafting turns that classified request into a confirmed, well-formed, versioned `MILESTONE.md`
-through discussion. The MILESTONE.md template is the SHAPE; this rubric is HOW to fill it well.
-You (the AI) **propose**; the human **confirms before anything is created**.
+`intake.md` CLASSIFIES a request into a bucket; scope drafting turns that into a confirmed, well-formed, versioned `MILESTONE.md` through discussion. The MILESTONE.md template is the SHAPE; this rubric is HOW to fill it well.
 
 ## What to do per intake outcome
 
-scope drafting honors intake's classification — it never re-sizes a request:
-
 | intake outcome | scope-loop action | creates (after confirm) |
 |----------------|-------------------|-------------------------|
 | `new-major` / `sub-milestone` | draft ONE MILESTONE.md (fill the template via discussion) | 1 milestone |
-| `task` | route to `add.py new-task <slug>` (it fits the active milestone) | 0 milestones |
+| `task` | route to `add.py new-task <slug>` (fits the active milestone) | 0 milestones |
 | `change-request` | route to SPECIFY/CONTRACT of the affected task | 0 milestones |
 | `split_required` | draft ALL N items as a batch in ONE pass | N milestones/tasks |
 
-**Confirm before create is the invariant.** It holds in the one-pass split case too: "one pass"
-means one drafting pass, NOT auto-creation. Nothing is written to disk — single draft or the
-whole batch — until the human confirms. You propose; you wait.
+**Confirm before create is the invariant.** "One pass" means one drafting pass, NOT auto-creation — nothing is written until the human confirms.
 
-## Position the goal — ground in assets, relate to the milestone map   (do this FIRST)
+**Confirm the milestone before detailing tasks.** `new-milestone <slug> --await-confirm` seeds it *unconfirmed* — `new-task` is HELD (`milestone_unconfirmed`) until you show the filled `MILESTONE.md`, get the human's go, and run `milestone-confirm <slug>`. Keeps you from digging into task §0–§5 before the parent is agreed. (Omit the flag: no gate.)
 
-Before you draft the goal sentence — before Diverge below — position the request in what
-already exists. You cannot write a correct goal without knowing where it sits.
+## Position the goal — ground in assets, relate to the milestone map   (do this FIRST)
 
-1. **Ground in current assets.** Read the goal input against `PROJECT.md` (domain · spec ·
-   UI/UX), the code it touches, and the existing docs — so the goal is grounded in what the
-   project already is, not in what you assume.
-2. **Relate to the milestone map.** Read every existing goal — `.add/milestones/*/MILESTONE.md`
-   and `.add/archive/*` — and name THIS request's relationship to them: *extends* theme X ·
-   *depends-on* Y · *overlaps* Z. Record that relationship in the `rationale` line you will write.
-3. **If the goal is already delivered** by an existing milestone, do NOT fork it — reject
-   `duplicate_goal` and route the request as a `task` or `change-request` (create nothing).
+Before drafting the goal sentence, position the request in what already exists — distinct from intake's classification, not redundant with it.
 
-This COMPLEMENTS `intake.md`'s bucket test (which weighs only whether a live milestone's goal
-covers the request); positioning also grounds the goal in current assets and relates it to the
-prior milestone map (`.add/milestones/*` + `.add/archive/*`) — which classification does not do.
-Point at intake for the bucket; do not restate it here.
+1. **Ground in current assets.** Read the goal against `PROJECT.md` (domain · spec · UI/UX), the code it touches, and existing docs — the goal must reflect what the project already is.
+2. **Relate to the milestone map.** Read every existing goal — `.add/milestones/*/MILESTONE.md` and `.add/archive/*` — and name THIS request's relationship: *extends* X · *depends-on* Y · *overlaps* Z. Record in the `rationale` line.
+3. **If the goal is already delivered** by an existing milestone, reject `duplicate_goal` and route as `task` or `change-request`.
 
 ## Brainstorm before you draft — co-specify at milestone level
 
-Don't draft a MILESTONE.md from thin input. Run the same three-move co-specify as a
-task's §1 (`phases/1-specify.md`) — Diverge (framings + open questions) → Converge
-(draft + rank) → Validate (show flags first) — raised to milestone scope. Ask only
-what moves the goal, the In/Out line, or the task list; skip what PROJECT.md settles.
-Draft the WHOLE milestone before showing; nothing hits disk until the human confirms.
+Don't draft from thin input. Run the three-move co-specify (`phases/1-specify.md`) — Diverge → Converge → Validate — raised to milestone scope. Ask only what moves the goal, the In/Out line, or the task list.
 
 Diverge seeds (pick the live ones):
-- **Outcome** — done means a user can do *what* they can't today? (goal sentence)
-- **Edge of scope** — nearest thing assumed IN that you want OUT? (Out list)
-- **Riskiest decision point** — which contract, if wrong, costs the most rework? (freeze-first)
-- **Done-looks-like** — how do we SEE each outcome without reading code? (exit criteria)
-- **First slice** — which task unblocks the rest? (breadth-first order)
-
-Rank assumptions lowest-confidence first; the top 1–2 get the flag the human reads at confirm:
-`⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>`. Present the draft via
-`report-template.md` — open with the ARC (goal · done · plan): the goal this milestone serves,
-what is already covered, and the plan its task list lays out.
-Render the draft as a guided choice — the recommended scope + its described alternatives (per `report-template.md`).
+- **Outcome** — done means a user can do *what* they can't today?
+- **Edge of scope** — nearest thing assumed IN that you want OUT?
+- **Riskiest decision point** — which contract, if wrong, costs the most rework?
+- **Done-looks-like** — how do we SEE each outcome without reading code?
+- **First slice** — which task unblocks the rest?
+
+Rank assumptions lowest-confidence first; top 1–2 get the flag: `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>`. Present via `report-template.md` — open with the ARC (goal · done · plan), render as a guided choice.
 
 ## Drafting a good MILESTONE.md (section by section)
 
-- **goal** — ONE sentence, an outcome not an output ("a user can size any request", not "write
-  intake.md"). If it needs an "and", it is probably two milestones.
-- **rationale** — the confirmed intake bucket + WHY (the theme · slice · fit), AND the milestone
-  relationship you captured in "Position the goal" above. One or two header lines; never in state.json.
-- **Scope In/Out** — the explicit anti-creep deferral list. Naming what is OUT is as important
-  as what is IN; an empty Out list usually means the scope is not yet thought through.
-- **Shared decisions & glossary deltas** — cross-cutting rules every task must honor, named from
-  the glossary. New terms get a glossary entry (the living documentation stays honest).
-- **Shared / risky contracts to freeze first** — the decision points between tasks; name the owning task.
-- **Tasks (breadth-first)** — `slug · depends-on · one line` each. Decompose by deliverable, not
-  by phase; keep each task one-file-sized. Order by dependency, not by guesswork.
-- **Exit criteria** — observable, and **every exit criterion maps to a declared task slug**
-  (no dangling criterion). Each line answers "which task delivers this, and how would we see it?"
-- **Close — ship review** + **Release steps** — leave these as the template at draft time: they are
-  **drafted-blank** here and filled LATER (Close at `milestone-done`, the close flow; Release steps when
-  the ship path is known, owned by `release.md`) — not scope drafting. Named here so you know the full
-  9-section shape and neither fill them early nor read a fresh draft as "incomplete".
-
-## Draft well-formedness gate   (a draft passes ALL of these before you propose it)
-
-A scope draft is well-formed — ready to show the human — only when:
-- [ ] the goal is ONE outcome sentence (no "and" — that is two milestones)
+- **goal** — ONE outcome sentence (no "and" — that is two milestones).
+- **rationale** — intake bucket + WHY, AND the milestone relationship from "Position the goal". Never in state.json.
+- **Scope In/Out** — explicit anti-creep deferral list. An empty Out list means scope is not yet thought through.
+- **Shared decisions & glossary deltas** — cross-cutting rules every task must honor. New terms get a glossary entry.
+- **Shared / risky contracts to freeze first** — decision points between tasks; name the owning task.
+- **Tasks (breadth-first)** — `slug · depends-on · one line` each. Decompose by deliverable; keep each task one-file-sized.
+- **Exit criteria** — observable; **every exit criterion maps to a declared task slug** (no dangling criterion).
+- **Close — ship review** + **Release steps** — **drafted-blank** here; filled LATER (`milestone-done` and `release.md`). Named so you know the full 9-section shape.
+
+## Draft well-formedness gate
+
+A scope draft is well-formed only when:
+- [ ] goal is ONE outcome sentence (no "and")
 - [ ] every exit criterion maps to a declared task slug (no dangling criterion)
-- [ ] `rationale` records the bucket + the milestone relationship from "Position the goal"
+- [ ] `rationale` records the bucket + milestone relationship from "Position the goal"
 - [ ] `Close — ship review` and `Release steps` are left as the template (drafted-blank)
-- [ ] the In/Out list names what is deferred (an empty Out list is unfinished thinking)
+- [ ] the In/Out list names what is deferred
 
-Propose only a well-formed draft — an incomplete one is the gap that lets a milestone reach
-task breakdown half-formed.
+Propose only a well-formed draft — an incomplete one lets a milestone reach task breakdown half-formed.
 
-## Reject codes (emit `{ reject, rationale }`, create nothing)
+## Reject codes
 
 <reject_codes>
-- `not_classified` — the request has not been through intake yet. Classify it first; you cannot
-  draft scope for an unclassified request.
-- `dangling_criterion` — a drafted MILESTONE.md has an exit criterion that maps to no declared
-  task slug. FIX the draft (add the task or drop the criterion) before proposing — never propose
-  a malformed milestone. With no engine lint, you are the first check and the human is the backstop.
-- `no_milestone` — intake routed the request to `task` or `change-request`; scope drafting
-  creates NO milestone. Honor the classification; do not invent milestone-sized scope.
-- `duplicate_goal` — the goal is already delivered by an existing milestone (live or in
-  `.add/archive/`). Do NOT fork it into a parallel milestone; route the request as a `task` or
-  `change-request` and create nothing. (Raised by the "Position the goal" step.)
+- `not_classified` — the request has not been through intake. Classify it first.
+- `dangling_criterion` — a drafted MILESTONE.md has an exit criterion that maps to no declared task slug. FIX the draft before proposing.
+- `no_milestone` — intake routed to `task` or `change-request`; create NO milestone.
+- `duplicate_goal` — the goal is already delivered by an existing milestone (live or in `.add/archive/`). Route as `task` or `change-request`, create nothing.
 </reject_codes>
 
-## Worked example (from this repo's own history)
-
-Request: *"open the Interface & Intake milestone"* → intake classified it `sub-milestone` of the
-live v4 self-driving theme → scope drafting produced **`.add/milestones/v4-1/MILESTONE.md`**:
+## Worked example
 
-- **goal**: make ADD harness-drivable and self-scoping — machine-readable state plus an
-  AI-facilitated request→versioned-milestone intake loop (the real v4-1 goal, one outcome sentence).
-- **tasks** (breadth-first): `machine-state-json` · `versioning-policy` · `scope-loop`.
-- **exit criteria** — each maps to its task slug: `--json` emits owner+stop (← machine-state-json),
-  the AI proposes a bucket with rationale (← versioning-policy), the AI drafts a versioned
-  MILESTONE.md via discussion (← scope-loop). Every criterion names the task that delivers it —
-  which is exactly the well-formedness rule above, checkable against the real file.
+Request: *"open the Interface & Intake milestone"* → intake classified it `sub-milestone` of v4 → scope drafting produced **`.add/milestones/v4-1/MILESTONE.md`**: goal *make ADD harness-drivable and self-scoping*; tasks (breadth-first) `machine-state-json` · `versioning-policy` · `scope-loop`; each exit criterion maps to its slug.

package/skill/add/setup-review.md

@@ -1,19 +1,12 @@
 # Setup review — the one page the human signs
 
-Autonomous setup ends at a single human gate: the **baseline approval** (`add.py lock`). Before that
-signature is honest, the human needs to see *what you drafted and how sure you were* — not re-derive
-it. `SETUP-REVIEW.md` is that page: every decision you made while drafting the foundation, first-scope,
-and the first contract, **ordered lowest-confidence-first** so the riskiest guesses meet their eye first.
+Autonomous setup ends at a single human gate: the **baseline approval** (`add.py lock`). `SETUP-REVIEW.md` is that page: every decision you made while drafting the foundation, first-scope, and the first contract, **ordered lowest-confidence-first** so the riskiest guesses meet the human's eye first.
 
-This is the setup-level analog of presenting a task's specification bundle lowest-confidence-first at the contract freeze.
-The engine never reads this file — `add.py lock` is judgment-free, the signature *is* the gate (see
-`setup-lock-state`). The human **reading** this page is the review; your job is to make the reading honest.
+The engine never reads this file — `add.py lock` is judgment-free, the signature *is* the gate. The human **reading** this page is the review.
 
 ## Where it lives
 
-Write **one** artifact at `.add/SETUP-REVIEW.md`. **Never clobber a human-edited one** — if it already
-exists with hand edits, append/update, don't overwrite (the same non-clobber rule `init` applies to
-living docs). It is a per-onboarding, setup-level artifact; it sits beside `PROJECT.md`, not under a task.
+Write **one** artifact at `.add/SETUP-REVIEW.md`. **Never clobber a human-edited one** — if it already exists with hand edits, append/update, don't overwrite. It sits beside `PROJECT.md`, not under a task.
 
 ## The template
 
@@ -35,31 +28,21 @@ Rows are numbered for reference at the gate ("row 1 is where my confidence is lo
 ## The two rules that make it honest
 
 <constraints>
-1. **Lowest-confidence-first.** Order rows by confidence **ascending**. A `guessed` row always floats above an
-   `evidence-grounded` one. The point is not completeness theatre — it is to spend the human's attention
-   where it changes outcomes: the top of the table is the part they actually need to challenge.
+1. **Lowest-confidence-first.** Order rows by confidence **ascending**. A `guessed` row always floats above an `evidence-grounded` one. The top of the table is the part the human actually needs to challenge.
 
 2. **Every row is tagged — `guessed` or `evidence-grounded`.**
-   - `evidence-grounded` — you read it from the code/repo. **Cite the file** (e.g. `pyproject.toml`,
-     `src/orders/models.py`). Brownfield onboarding (see `adopt.md`) is mostly these.
-   - `guessed` — the repo was silent, so you inferred it. **State the inference and why.** Thin-greenfield
-     onboarding (a near-empty repo, only the 4-lens answers) produces these. These are what the human
-     must check; that is why they sit on top.
-
-   The tag vocabulary is shared with `adopt.md` — the brownfield map tags each filled living-doc decision
-   `guessed`/`evidence-grounded`, and those tags flow straight into this table.
+   - `evidence-grounded` — you read it from the code/repo. **Cite the file** (e.g. `pyproject.toml`). Brownfield onboarding (see `adopt.md`) is mostly these.
+   - `guessed` — the repo was silent, so you inferred it. **State the inference and why.** Thin-greenfield onboarding produces these. These are what the human must check; that is why they sit on top.
+
+   The tag vocabulary is shared with `adopt.md` — brownfield map tags flow straight into this table.
 </constraints>
 
 ## Where it ends
 
-`SETUP-REVIEW.md` is **read-only context** for the baseline approval. You do not ask the human to approve it
-field-by-field; you present it, lowest-confidence-first; they confirm in conversation, and you run the lock
-with their name:
+`SETUP-REVIEW.md` is read-only context for the baseline approval — present it lowest-confidence-first, not field-by-field; the human confirms in conversation; you run the lock:
 
 ```bash
 python3 .add/tooling/add.py lock --by "<name>"
 ```
 
-`lock` records the lock layers and opens the build — it does **not** parse or validate this file (the
-engine stays judgment-free). The review lives in the human's reading of the page, not in the tool. Make
-the top of the table the truth they most need, and the one signature is informed.
+`lock` records the lock layers and opens the build — it does **not** parse or validate this file. Make the top of the table the truth they most need.