@pilotspace/add 1.0.0 → 1.1.0

package/skill/add/SKILL.md

@@ -31,7 +31,10 @@ Run the tool to find the resume point instead of re-reading the repo:
 python3 .add/tooling/add.py status
 ```
 
-- **No `.add/` yet** → go to **phase 0 (setup)**: read `phases/0-setup.md`.
+- **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 —
+  `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 lock-down.
 - **A task is active** → open `.add/tasks/<active>/TASK.md`, look at its `phase:`
   marker, and read the matching `phases/<n>-<phase>.md`. Work *only* that phase.
 - **No active task** → first SIZE the request (see Intake below), then create the
@@ -56,28 +59,51 @@ Load the phase guide **only for the phase you are in** (progressive disclosure):
 
 | Phase | Guide | Produces (TASK.md section) | Who leads |
 |-------|-------|----------------------------|-----------|
-| setup | `phases/0-setup.md` | `.add/` + survivor files | human |
-| specify | `phases/1-specify.md` | §1 rules + ranked least-sure flag | human + AI (co-specify) |
-| scenarios | `phases/2-scenarios.md` | §2 Given/When/Then | human |
-| contract | `phases/3-contract.md` | §3 frozen shape | human + AI |
-| tests | `phases/4-tests.md` | §4 + red suite in `tests/` | human sets, AI writes |
+| setup | `phases/0-setup.md` | `.add/` + survivors + first §1–§3 + `SETUP-REVIEW.md` | AI drafts → **human locks** (the lock-down) |
+| specify | `phases/1-specify.md` | §1 rules + ranked least-sure flag | AI drafts (co-specify)† |
+| scenarios | `phases/2-scenarios.md` | §2 Given/When/Then | AI drafts† |
+| contract | `phases/3-contract.md` | §3 frozen shape | AI drafts → **human approves once** (the seam)† |
+| tests | `phases/4-tests.md` | §4 + red suite in `tests/` | AI drafts† |
 | build | `phases/5-build.md` | code in `src/`, tests green | **AI** |
-| verify | `phases/6-verify.md` | §6 checks + gate record | **human** |
+| verify | `phases/6-verify.md` | §6 checks + gate record | **AI auto-gates on evidence**; human on residue/security‡ |
 | observe | `phases/7-observe.md` | §7 spec delta | human + AI |
 
+† **One-approval front (v7).** §1–§4 are drafted by the AI as a single bundle and frozen
+together; the human gives **one approval, at the contract freeze** (the autonomy seam) — not
+three separate sign-offs. The AI presents the bundle least-sure-first. See `run.md`.
+‡ **Verify auto-gate (v6–v7).** Under `autonomy: auto` (the default) a run may auto-PASS once
+the evidence is complete (all tests green · loops dry · no residue) — recorded as *auto-resolved*,
+an explicit PASS, not a skip. **Security always escalates** (HARD-STOP), as do concurrency /
+architecture residue and `conservative` autonomy. See `run.md`.
+
+Whenever you present a seam to the human in chat (intake · front approval · gate ·
+milestone close), follow `report-template.md` — SUMMARY → DECISION → ⚠ FLAGS →
+EVIDENCE → NEXT, engine-sourced facts, show-before-ask, never pre-stamp a seam.
+
 In **observe**, also emit **competency deltas** — learnings tagged by which of the five
 (`DDD · SDD · UDD · TDD · ADD`) they improve — so the foundation self-improves across loops.
 You write them as `open`; the human folds them into `PROJECT.md`. Read `deltas.md` for the
 grammar and the status lifecycle. At milestone close (or on demand), run the fold ritual that
 gathers confirmed deltas into a versioned foundation — read `fold.md`.
 
-## The dynamic run (v6)
+## The dynamic run (v6–v7)
+
+Once **§3 CONTRACT is FROZEN**, the build→verify half runs as a dynamic, auto-gated run —
+fan-out + in-run convergence — instead of a manual build (`autonomy: auto` is the default; lower
+to `conservative` to keep a human at the gate). Read `run.md` for the trigger, the touch-boundary,
+the evidence auto-gate, and the autonomy dial. The human-led front still owns *direction*, but v7
+compresses it to a **single approval at the contract seam**; the run never edits a frozen contract
+and never auto-passes a security finding.
+
+## Parallel streams — pipelining independent tasks (opt-in)
 
-Once **§3 CONTRACT is FROZEN**, the build→verify half MAY run as a dynamic, auto-gated run —
-fan-out + in-run convergence — instead of a manual build. Read `run.md` for the trigger, the
-touch-boundary, the evidence auto-gate, and the autonomy dial. The human-led front
-(specify·scenarios·contract) is unchanged; the run never edits a frozen contract and never
-auto-passes a security finding.
+The default is one task at a time. When a milestone has several tasks whose `deps=` are
+already `PASS` and a human is ready to review, you MAY run them concurrently: read
+`streams.md`. It changes no `add.py` code — you compute a READY-QUEUE from `status`,
+spawn one worker per ready task (each in a worktree, building behind its own frozen
+contract), and keep the human seams (front approval · escalated Verify) on one serial
+REVIEW-QUEUE. The honest gain is pipelining (the reviewer never waits on a build), not
+N× speed; the autonomy dial sets how much actually overlaps.
 
 ## Non-negotiable rules (from the method)
 
@@ -100,6 +126,7 @@ inside TASK.md):
 ```bash
 python3 .add/tooling/add.py advance            # next phase of the active task
 python3 .add/tooling/add.py gate PASS          # at verify: records PASS, marks done
+python3 .add/tooling/add.py use <slug>         # switch the active task (e.g. across parallel streams)
 ```
 
 ## Depth by stage

package/skill/add/adopt.md

@@ -0,0 +1,65 @@
+# Adopt — map an existing repo into the foundation (silent)
+
+When ADD is pointed at a repo that already has code, onboarding is **silent**: the code
+answers the questions a greenfield interview would ask, so you read it rather than ask.
+This is the **brownfield path** of setup (the greenfield path keeps the 4-lens interview —
+see `phases/0-setup.md`). You fill the survivor files from evidence, then stop at the one
+human gate: the **lock-down** (`add.py lock`).
+
+## The signal — and arming the gate
+
+Enter a brownfield repo with `--await-lock`:
+
+```bash
+python3 .add/tooling/add.py init --await-lock
+```
+
+`--await-lock` does two things. It seeds an **unlocked** setup, which *arms the lock-down gate*
+— the engine then refuses a second task, crossing into build, and recording a gate until you
+`lock`. And init, being brownfield-aware, prints a line that begins:
+
+```
+brownfield: existing code detected — the `add` skill maps it into your foundation …
+```
+
+That line is your cue to run this guide. **Always use `--await-lock` for brownfield onboarding**:
+a plain `init` writes no setup and is grandfathered-locked, so its gate never arms *and* the
+closing `lock` below would refuse with `already_locked`. The engine only *detects* the existing
+code (a mechanical fact); it never reads or fills it — interpreting it is your job.
+
+## The silent mapping
+
+Fill each survivor file in `.add/` from what the code actually shows — **ask nothing**:
+
+| Survivor | Read it from |
+|----------|--------------|
+| `PROJECT.md` (foundation) | the domain nouns, entry points, the README, the first milestone the code implies |
+| `CONVENTIONS.md` | the languages, folder layout, naming, lint config, error style already in the tree |
+| `GLOSSARY.md` | the recurring names in modules, models, and public APIs (one name per concept) |
+| `MODEL_REGISTRY.md` | leave the active model record; note any AI-authored code you can detect |
+| `dependencies.allowlist` | the manifests already in the repo (package.json, pyproject, go.mod, …) |
+
+Two rules that never bend:
+
+1. **Never clobber a survivor.** `init` already skips any survivor that exists; if a human
+   already wrote `PROJECT.md`, you READ it, you do not overwrite it. Add, never replace.
+2. **Tag every drafted decision `evidence-grounded` vs `guessed`.** A line you read from the
+   code is *evidence-grounded* (cite the file). A line you inferred because the code was silent
+   is *guessed*. The human's single lock-down is only honest if they can see which is which —
+   the guesses are what they actually need to check. (The tags feed `SETUP-REVIEW.md`.)
+
+## Where it ends — the lock-down
+
+Brownfield onboarding draws no per-step approvals. You map the foundation, then draft the
+first milestone's scope and the first task's candidate front exactly as greenfield does, and
+present it all at **one** human gate. The human reviews the decisions (least-sure / `guessed`
+first) and signs:
+
+```bash
+python3 .add/tooling/add.py lock --by "<name>"
+```
+
+`lock` freezes the foundation + scope + first contract in one atomic write and opens the build.
+Until it is run, the engine refuses a second task, crossing into build, and recording a gate —
+so nothing is built on an unreviewed map. That gate is the only thing brownfield onboarding asks
+of a human; everything before it, you did from the code.

package/skill/add/deltas.md

@@ -10,7 +10,7 @@ You (the AI) **emit** deltas as `open`. Only the **human** moves a delta to `fol
 
 ## The grammar (frozen)
 
-Each delta is ONE line, exactly:
+Each delta begins on its own **tag line**; the learning may wrap onto continuation lines:
 
 ```
 - [<COMPETENCY> · <status>] <learning> (evidence: <pointer>)
@@ -18,10 +18,20 @@ Each delta is ONE line, exactly:
 
 - `<COMPETENCY>` — exactly one of the five (below).
 - `<status>` — `open` | `folded` | `rejected`. A **newly emitted delta is `open`**.
-- `<learning>` — the insight, in one phrase ("the domain model missed multi-tenancy").
+- `<learning>` — the insight ("the domain model missed multi-tenancy"). It may run past one line;
+  the `- [COMPETENCY · status]` tag line must come **first**, and the `(evidence: …)` clause must
+  **close** the delta (on its last line).
 - `(evidence: …)` — **required**, non-empty: a failing scenario, a production signal, a review
   note. No evidence → it is an opinion, not a delta.
 
+A long learning may wrap — the lint (`add.py check`) joins continuation lines, so this is **one**
+delta, not two:
+
+```
+- [SDD · open] the export endpoint must reject a tenant-scoped token used cross-tenant,
+  returning `forbidden` (not `not_found`) (evidence: scenario_cross_tenant_export failed)
+```
+
 ## The five competencies (pick exactly one per delta)
 
 | tag | competency | a delta here means you learned something about… |

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

@@ -1,35 +1,98 @@
-# Phase 0 — Setup (once per project)
+# Phase 0 — Setup (autonomous draft → one human lock-down)
 
-Goal: make every later gate enforceable automatically. Do this once.
+Goal: point ADD at a repo and **you** draft the whole foundation — domain, first-milestone scope,
+and the first task's contract — then hand the human exactly one decision: the **lock-down**. Brownfield
+is silent (the code answers the questions); greenfield keeps a short interview. Either way, the human's
+only gate is `add.py lock`. This is the setup-altitude analog of a task's one-approval contract freeze.
 
-## Do
+## 1 · Zero-touch entry — you run init yourself
 
-1. Initialise the runtime (creates `.add/` + survivor-layer files):
+When there is no `.add/state.json`, do **not** tell the human to initialise — run it yourself. Infer the
+project name and stage from the repo, and **arm the lock-down gate** with `--await-lock`:
+
+```bash
+python3 .add/tooling/add.py init --name "<inferred from repo/dir>" --stage <prototype|poc|mvp|production> --await-lock
+```
+
+- `--await-lock` is **required** here: it seeds an *unlocked* setup, which arms the gate so the engine
+  refuses a second task / crossing into build / a `gate` until you `lock`. A plain `init` is
+  grandfathered-locked — its gate never arms, and the closing `lock` would error `already_locked`.
+- name + stage are **your judgment** (read them from the dir name, README, manifests); the engine stays
+  mechanical. Pick the stage from the ambition you hear: throwaway → `prototype`, one risky slice → `poc`,
+  narrow-but-real → `mvp`, full rigor → `production`.
+
+`init` prints one of two things — **that is your branch**:
+- a line starting `brownfield:` → there is existing code (go to **2a**);
+- the greenfield closing (no `brownfield:`) → an empty repo (go to **2b**).
+
+## 2a · Brownfield — map it silently
+
+The code answers the questions a greenfield interview would ask, so **read it, don't ask**. Open
+`adopt.md` and follow it: fill each survivor file from the code, never clobber an existing one, and tag
+every decision `evidence-grounded` (cite the file) or `guessed`. Ask the human **nothing** at this step.
+
+## 2b · Greenfield — the 4-lens interview (kept): co-specify at foundation altitude
+
+An empty repo has no code to read, so run the short interview. This is the **co-specify at foundation
+altitude** move — the same diverge → converge → validate brainstorm a task's §1 uses (`phases/1-specify.md`),
+lifted to the foundation. Ask the one load-bearing question per lens (diverge), draft the foundation
+(converge), then rank what you're least sure of and show the top flag first (validate):
+
+| Lens | The one question that unblocks the section |
+|------|--------------------------------------------|
+| Domain (DDD) | The 3–5 core nouns, and the one invariant that must NEVER break? |
+| Spec (SDD) | The first milestone's outcome — and what's explicitly NOT in v1? |
+| Users (UDD) | The primary user and the one job they hire this for? (or "no UI — surface is X") |
+| Decisions | What's already decided that you'd regret re-litigating? (first Key Decision row) |
+
+Ask only the live ones; skip what the request already answers. Rank your drafts least-sure-first using the
+one notation every altitude shares — `⚠ <assumption> — least sure because <why>; if wrong: <cost>` — and
+tag thin or inferred answers `guessed`.
+
+## 3 · Draft to the lock (both paths)
+
+1. **Fill the survivors** (they outlive all code): `.add/PROJECT.md` (the foundation — Domain · Spec/active
+   milestone · UI/UX · Key Decisions, one screen), `CONVENTIONS.md`, `GLOSSARY.md`, `MODEL_REGISTRY.md`,
+   `dependencies.allowlist`. Brownfield: from the code. Greenfield: from the interview, gaps flagged `guessed`.
+2. **Size the first milestone** (read `scope.md`) and draft its `MILESTONE.md` — goal · scope · exit criteria
+   · breadth-first tasks.
+3. **Create the first task and draft its candidate front.** `new-task` is allowed pre-lock:
    ```bash
-   python3 .add/tooling/add.py init --name "<project>" --stage prototype
+   python3 .add/tooling/add.py new-task <slug> --title "<first feature>"
    ```
-   If the tool isn't there yet, the installer (`npx @pilotspace/add init`) placed it at
-   `.add/tooling/add.py`.
-2. Fill the survivor-layer files (they outlive all code):
-   - `.add/PROJECT.md` — **the foundation**: Domain (DDD) · Spec/Living-Document (SDD,
-     → active milestone) · UI/UX (UDD) · Key Decisions. Cross-milestone context the
-     engine reads first. Keep it to one screen. Book: `docs/14-foundation.md`.
-   - `.add/CONVENTIONS.md` — language, folders, naming, lint, error-code style, architecture.
-   - `.add/GLOSSARY.md` — one name per concept; used in specs, contracts, and code.
-   - `.add/MODEL_REGISTRY.md` — which AI model/version writes this project.
-   - `.add/dependencies.allowlist` — packages the AI may use; CI rejects others.
-3. Confirm CI runs green on the empty skeleton before the first feature.
+   Draft §1 (specify) · §2 (scenarios) · §3 (contract). **Leave §3 `Status: DRAFT`** — the lock is its
+   approval (see §5). You MAY `advance` through specify → scenarios → contract → tests pre-lock, but the
+   engine **refuses crossing into build** until you `lock` (`setup_unlocked`). Sequence: front → lock → build.
+4. **Write `.add/SETUP-REVIEW.md`** per `setup-review.md`: every decision you drafted (foundation, scope,
+   first contract), **least-sure-first**, each tagged `guessed` | `evidence-grounded`.
+
+## 4 · The one human gate — the lock-down
+
+Present `SETUP-REVIEW.md` least-sure-first (the `guessed` rows are what the human must actually check). They
+sign **once**:
+
+```bash
+python3 .add/tooling/add.py lock --by "<name>"
+```
+
+`lock` records the lock layers (foundation · scope · contract) in one atomic write and opens the build. It is
+judgment-free — it does **not** parse `SETUP-REVIEW.md`; the human *reading* it is the review.
+
+## 5 · After the lock
+
+- The lock **is** the first task's contract approval — the v7 one-approval-front and the lock-down collapse
+  into this single signature. Do **not** ask for a separate contract-freeze sign-off (that double-gates).
+- Stamp the first task's §3 `Status: FROZEN @ v1` (lock-authorized), then read `phases/5-build.md` — build is
+  now open. Everything before this signature, you drafted.
 
 ## Exit gate
 
-- [ ] `.add/state.json` exists (`add.py status` works).
-- [ ] `.add/PROJECT.md` foundation filled (domain · spec · UI/UX).
-- [ ] CONVENTIONS, GLOSSARY, MODEL_REGISTRY, allowlist filled.
-- [ ] Pipeline green on the skeleton.
+- [ ] `.add/state.json` exists; setup was seeded unlocked (`--await-lock`) then locked.
+- [ ] Survivors filled (brownfield: from code, tagged evidence-grounded; greenfield: from the interview).
+- [ ] First task created; §1–§3 drafted; `.add/SETUP-REVIEW.md` written least-sure-first.
+- [ ] Human signed `add.py lock`; first task §3 `FROZEN @ v1`; build open.
 
 ## Next
 
-```bash
-python3 .add/tooling/add.py new-task <slug> --title "<feature>"
-```
-Then read `phases/1-specify.md`. · Book: `docs/10-setup-and-stages.md`.
+After the lock, read `phases/5-build.md` (build is open). · Book: `docs/10-setup-and-stages.md`
+*(note: book chapters 10 / 13 / 14 still describe the older human-led setup until `book-align` lands).*

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

@@ -20,6 +20,22 @@ whole bundle (§1–§4). Before asking for it, present the bundle **least-sure
 most likely wrong (`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`) — aim the human's
 eye before they freeze. See `run.md`.
 
+## The freeze review checklist
+
+The human's one minute, aimed. Walk these six before saying yes:
+
+- **⚠ flags first** — read the least-sure flags; accept each knowing its cost if wrong.
+- **Intent** — does §1 say what you actually want built (and is anything you expected missing)?
+- **Cases** — does every Must and Reject have an observable §2 scenario you care about?
+- **Shape** — glossary names, error codes, additive vs breaking: is THIS the shape to freeze?
+- **Risk** — is this scope high-risk or method-defining? Then require
+  `risk: high · autonomy: conservative` in the TASK.md header — the engine refuses an unguarded completion.
+- **Tests** — will §4 go red for the right reason, asserting behavior rather than internals?
+
+This checklist AIMS the one approval — never a second gate, no sign-off forms, no
+extra documents. Reject any line and the bundle goes back to draft; that is
+backward-correction, not failure.
+
 ## AI prompt
 
 > Role: an interface architect; frozen contracts are immutable. Read §1, §2,

package/skill/add/phases/4-tests.md

@@ -17,6 +17,20 @@ before code exists is testing nothing and will wave bad code through later.
 - Side-effect assertions on rejection paths (`assert balance unchanged`).
 - A recorded coverage target in §4.
 
+## Declaring where tests live
+
+§4's `Tests live in:` line is machine-read: when a task has no local `tests/`,
+`add.py report` counts test functions at the declared path(s) instead. The FIRST
+line matching `Tests live in:` is read; paths are its backticked tokens.
+Resolution: `./…` → this task's dir · a token containing `/` → the project root
+(the parent of `.add/`) · a bare name → a sibling of the previous token's
+directory (else the task dir). A directory token counts the `*.py` files directly
+inside it (non-recursive); a `.py` file token counts itself; anything else is
+ignored. Resolved files are deduped, and reports mark declared counts with `†`.
+Paths are confined: anything resolving (symlinks followed)
+outside the project root counts 0 — `..` traversal, absolute paths, and
+symlink escapes are never read.
+
 ## AI prompt
 
 > Role: a test author who writes tests before code. Read §2 and §3. Turn each

package/skill/add/phases/5-build.md

@@ -36,3 +36,6 @@ change request back to Specify. Honor the feature-specific safety rule named in
 
 `python3 .add/tooling/add.py advance` → read `phases/6-verify.md`.
 Book: `docs/07-step-5-build.md`.
+
+> Under `autonomy: auto` (the default) Build and Verify run together as one dynamic,
+> evidence-auto-gated run — not two manual stops. See `run.md`.

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

@@ -1,8 +1,16 @@
 # Phase 6 — Verify (evidence + blind-spot checks)
 
 Goal: establish trust and record an outcome. Passing tests are necessary, not
-sufficient. This phase is **human-led** — there is no AI role. Fill **§6** in
-TASK.md including the GATE RECORD.
+sufficient. Fill **§6** in TASK.md including the GATE RECORD.
+
+> **Who resolves this gate depends on the `autonomy:` header (see `run.md`).**
+> Under `autonomy: auto` (the default) a run auto-PASSes once the evidence is
+> complete — every test green, the convergence loops dry, and **no residue**
+> (security · concurrency · architecture) — recording it as *auto-resolved* with
+> the named run as accountable owner: an explicit PASS, not a skip. **Security is
+> always a HARD-STOP and is never auto-passed.** Under `autonomy: conservative`,
+> or whenever residue is found, this phase is **human-led** and the checks below
+> are the human's.
 
 ## Part one — confirm the evidence
 
@@ -18,6 +26,9 @@ If any is false, stop and return to Build — there is nothing to verify yet.
   and miss races.) This is usually the single most important check.
 - **Security** — exposed secrets, injection openings, unexpected/invented
   dependencies. A security finding is always `HARD-STOP`, never a waiver.
+  Writing ANY note on this line means the gate escalates to the human — and
+  start it with `NOTE` or `⚠` so `add.py audit` can see it: a marked security
+  note reviewed by the auto-gate is an audit finding (`unescalated_security_note`).
 - **Architecture** — does it respect layering/dependency rules in CONVENTIONS.md?
 
 ## Record exactly one outcome (no silent pass)
@@ -30,7 +41,8 @@ If any is false, stop and return to Build — there is nothing to verify yet.
 
 ## Exit gate / Next
 
-- [ ] Evidence confirmed, blind-spots checked, a person approved, outcome recorded.
+- [ ] Evidence confirmed, blind-spots checked, outcome recorded — a person approved, or
+  (under `autonomy: auto` with no residue) the run auto-resolved as the accountable owner.
 
 ```bash
 python3 .add/tooling/add.py gate PASS          # marks the task done

package/skill/add/report-template.md

@@ -0,0 +1,48 @@
+# Chat reports — the seam 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 seam: an intake proposal, a
+bundle/front approval, a verify gate, a task completion, a milestone close.
+
+## The five blocks, in order
+
+```
+SUMMARY   one line: intent + target + where we are
+DECISION  what you need from the human (or "none — FYI")
+⚠ FLAGS   least-sure 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** — least-sure first, each with *why* it is least sure 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).
+
+## Hard rules
+
+- **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.
+- **Never pre-stamp a human seam.** 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 seam.** 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.

package/skill/add/run.md

@@ -28,7 +28,8 @@ 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 seam 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
@@ -148,5 +149,12 @@ closes the v6 dogfood blind-spot, where the whole milestone ran at `auto` on the
 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 dial 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 seam, the engine enforces what was declared.

package/skill/add/scope.md

@@ -20,6 +20,24 @@ 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 altitude
+
+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 seam** — 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 least-sure first; the top 1–2 get the flag the human reads at confirm:
+`⚠ <assumption> — least sure because <why>; if wrong: <cost>`.
+
 ## Drafting a good MILESTONE.md (section by section)
 
 - **goal** — ONE sentence, an outcome not an output ("a user can size any request", not "write

package/skill/add/setup-review.md

@@ -0,0 +1,62 @@
+# Setup review — the one page the human signs
+
+Autonomous setup ends at a single human gate: the **lock-down** (`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 least-sure-first** so the riskiest guesses meet their eye first.
+
+This is the setup-altitude analog of presenting a task's front least-sure-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
+survivors). It is a per-onboarding, setup-altitude 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: reviewed the above → `add.py lock --by "<name>"`
+```
+
+Rows are numbered for reference at the gate ("row 1 is the one I'm least sure about").
+
+## The two rules that make it honest
+
+1. **Least-sure-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 survivor decision
+   `guessed`/`evidence-grounded`, and those tags flow straight into this table.
+
+## Where it ends
+
+`SETUP-REVIEW.md` is **read-only context** for the lock-down. You do not ask the human to approve it
+field-by-field; you present it, least-sure-first, and they sign once:
+
+```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.