@pilotspace/add 1.0.0 → 1.2.0

package/skill/add/report-template.md

@@ -0,0 +1,106 @@
+# Chat reports — the decision-point template (for the AI, not for add.py)
+
+The engine renders artifacts (`report`, `report --decide`, `status`); this file
+governs the CHAT MESSAGE you wrap around them. The digest is the artifact BEHIND
+your presentation, never a replacement for it — and your prose is never a
+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
+
+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:
+
+```
+ARC  goal: <the milestone / project goal this decision serves>
+     done: <proven progress — tasks done · exit-criteria met · what this gate proves>
+     plan: <this gate → the next step → the goal>
+```
+
+- **goal** — the milestone or project goal the decision serves, read from the
+  `m-goal` line in `add.py status`; never re-typed from memory.
+- **done** — proven progress only: exit-criteria met/total and tasks done from
+  the rollup, plus what this gate proves. An honest fact, never a hope.
+- **plan** — this gate → the next step → the goal, mirroring the rollup's
+  `DECIDE NEXT` line.
+
+The arc is required at every human gate: **baseline-lock · contract-freeze ·
+verify · intake · scope · milestone-close · graduation**. The three labels stay
+constant; their content adapts to the gate. The arc is presentation only — it
+adds no gate and changes no PASS / RISK-ACCEPTED / HARD-STOP / freeze outcome.
+
+Its facts are engine-sourced, exactly like EVIDENCE below: goal = `m-goal` ·
+done = exit-criteria met/total + tasks done · plan = `DECIDE NEXT`. If your arc
+and `add.py` output disagree, the engine wins — fix the arc, not the engine.
+
+### Per-gate examples — one shape, gate-specific content
+
+- **verify** — `goal:` ship the decision arc · `done:` report-arc tests 6/6
+  green, gate ready · `plan:` PASS this gate → wire the arc into every gate → goal.
+- **contract-freeze** — `goal:` … · `done:` bundle drafted, lowest-confidence
+  flag surfaced · `plan:` freeze §3 → build → goal.
+- **milestone-close** — `goal:` … · `done:` exit-criteria 3/3 met, all tasks
+  done · `plan:` close → archive → the next milestone.
+- **intake** — `goal:` the sized request · `done:` classified new-major,
+  rationale stated · `plan:` create the milestone → first contract → goal.
+
+## The five blocks, in order
+
+```
+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
+EVIDENCE  small table: tests · gates · parity · check — engine-sourced
+NEXT      the single next action + what it 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
+   *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
+   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
+   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.
+
+## Hard rules
+
+<constraints>
+- **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
+  `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
+  count disagrees with the engine is the un-transparent gate the ARC exists to close.
+- **Never pre-stamp a human decision point.** Freeze / gate / lock fields stay DRAFT or
+  blank until the answer returns: show → ask → stamp → advance. An artifact
+  must never claim an approval that has not happened.
+- **One report per decision point.** After an approval, point at the frozen artifact —
+  do not re-render the whole bundle.
+- **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
+  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.
+</constraints>

package/skill/add/run.md

@@ -1,25 +1,24 @@
 # 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 seam — below it code is disposable; above it nothing breaks. This rubric
-covers what runs on the far side of the seam: the **build->verify half, executed as a dynamic,
-self-improving run** instead of a manual, sequential build. The human-led FRONT (Specify · Scenarios
-· Contract) still owns *direction*, but v7 compresses it to a **single human approval at the seam**
-(see "The one-approval front" below) — the AI drafts the whole front, a human approves it once.
+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
-> fold loop (`deltas.md` · `fold.md`). The engine stays judgment-free: this is a rubric, not `add.py`.
+> consolidation loop (`deltas.md` · `fold.md`). The engine stays judgment-free: this is a rubric, not `add.py`.
 
-## The one-approval front (v7)
+## The specification bundle (v7)
 
-The human-led front 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 front as a single
-bundle** — the Spec, the Scenarios, the Contract, and the failing Tests — and presents it together. The
-human gives **one approval, at the frozen contract** (the seam). That single approval is the green light
+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 seam, and the seam **stays human**.
+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
@@ -28,10 +27,11 @@ then builds against and self-gate the result — the circular trust v6's dogfood
 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.
+Approve, and the run begins. The decision-point guide (`phases/3-contract.md`) carries the
+**freeze review checklist** — six lines that walk the human through exactly this, ⚠-first.
 
-**The least-sure flag — aiming the one approval.** A single approval over a whole bundle invites a
-rubber stamp. So the AI presents the bundle **least-sure first**: of everything it is asking the human
+**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
@@ -39,7 +39,7 @@ scenario or the contract shape. If nothing is materially uncertain, the AI still
 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 be the rubber stamp one level up). Closing
+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.
 
 ## When the run begins — the scope-lock trigger
@@ -49,17 +49,18 @@ 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).
 
-No frozen contract -> no run: you are still on the human-led front, and starting early is the
+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.
 
-## The touch-boundary — what the run may and may not touch
+## The change scope — what the run may and may not touch
 
+<constraints>
 A locked run has a hard boundary. It MAY:
 
-- write and rewrite **code** (`src/`) — code is disposable below the seam;
+- 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);
-- gather **evidence** for the verify gate (test output, blind-spot checks).
+- gather **evidence** for the verify gate (test output, non-functional review).
 
 It MUST NOT:
 
@@ -67,10 +68,11 @@ It MUST NOT:
   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).
-- touch the **human-led front artifacts** (§1–§3) except to halt and escalate.
+- 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
-front can resolve, it stops — and that stop is the loop working, not failing.
+specification bundle can resolve, it stops — and that stop is the loop working, not failing.
 
 ## The dynamic run — fan-out and in-run convergence
 
@@ -82,21 +84,28 @@ on a trustworthy result with three loops:
   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 blind-spot,
+- **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.
 
 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 evidence auto-gate
+## 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).
 
 - **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.
+  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.
 - **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.
@@ -106,22 +115,24 @@ explicit pass, not a skip).
 
 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.
+</constraints>
 
 ## 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` competency delta** in the task's OBSERVE block, in the `deltas.md` grammar,
+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 fold (`fold.md`) at milestone close: the run emits `open`;
-the human folds. That is the loop closing — **v6 run -> v5 foundation** — so a dynamic run sharpens the
+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.
 
-## The autonomy dial
+## 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:
 
@@ -137,16 +148,24 @@ autonomy: auto | conservative
 
 > **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 dial is still **per-scope**, the level still lives in the
+> 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 dial is not a blank cheque. On a
+**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 `conservative`; leaving it at `auto` there is the reject code **`unguarded_high_risk_auto`**. This
-closes the v6 dogfood blind-spot, where the whole milestone ran at `auto` on the riskiest possible
+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.
 
-The dial is a **rubric convention** read by the human and the run — it is **not an `add.py` flag** (the
-engine stays judgment-free); the level lives in the `TASK.md` header where the run already reads.
+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 `autonomy: conservative` (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.
+</constraints>

package/skill/add/scope.md

@@ -20,6 +20,26 @@ scope drafting honors intake's classification — it never re-sizes a request:
 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.
 
+## 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.
+
+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.
+
 ## Drafting a good MILESTONE.md (section by section)
 
 - **goal** — ONE sentence, an outcome not an output ("a user can size any request", not "write
@@ -27,8 +47,8 @@ whole batch — until the human confirms. You propose; you wait.
 - **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 survivor layer stays honest).
-- **Shared / risky contracts to freeze first** — the seams between tasks; name the owning task.
+  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**
@@ -36,6 +56,7 @@ whole batch — until the human confirms. You propose; you wait.
 
 ## Reject codes (emit `{ reject, rationale }`, create nothing)
 
+<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
@@ -43,6 +64,7 @@ whole batch — until the human confirms. You propose; you wait.
   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.
+</reject_codes>
 
 ## Worked example (from this repo's own history)
 

package/skill/add/setup-review.md

@@ -0,0 +1,65 @@
+# 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.
+
+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.
+
+## 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.
+
+## The template
+
+```markdown
+# SETUP REVIEW — <project>
+
+<stage> · <brownfield | greenfield> · drafted by <model> @ <date>
+
+| # | Decision | Lands in | Tag | Why / Evidence |
+|---|----------|----------|-----|----------------|
+| 1 | <the drafted decision> | PROJECT.md \| scope \| first-contract | `guessed` | <the inference + why you had to guess> |
+| 2 | <…> | <…> | `evidence-grounded` | <cite the source file/line you read it from> |
+
+Sign: confirm in chat → the agent runs `add.py lock --by "<name>"` (typing it yourself works too)
+```
+
+Rows are numbered for reference at the gate ("row 1 is where my confidence is lowest").
+
+## 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.
+
+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.
+</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:
+
+```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.