@pilotspace/add 1.0.0 → 1.2.0

package/skill/add/loop.md

@@ -0,0 +1,59 @@
+# The dynamic loop — open deltas and extras become the next tasks
+
+A milestone is not done when its tasks are done — it is done when its **GOAL** is met.
+This guide is the loop that drives a milestone toward that goal: turn what each task
+leaves behind (open lessons, and work discovered but out of scope) into the next tasks,
+and keep going until the exit criteria are all met.
+
+You (the AI) **gather and propose**; the **human confirms**; the existing `add.py new-task`
+creates each one. The engine never decides what the next task is — that is judgment.
+
+## The goal-gate (what holds the loop open)
+
+`add.py milestone-done <slug>` REFUSES to close a milestone while its exit criteria are not
+all met — it stops with `milestone_goal_unmet` and the milestone stays active. The exit-criteria
+checkboxes in `MILESTONE.md` ARE the human's goal-met affirmation: the engine reads the
+`- [x]`/`- [ ]` tally, it never judges whether the goal is met (the same trust model as reading a
+recorded `PASS`). Checking the last box is the deliberate act that releases the gate.
+
+The gate fires only when criteria exist. A milestone with no exit-criteria checkboxes closes as
+before — write criteria into `MILESTONE.md` if you want the goal-gate to hold the milestone open.
+
+`milestone-done` is the only way a milestone reaches `done`; `archive-milestone` and `compact`
+both refuse a milestone that is not done. So the one gate is enough — there is no quiet way around it.
+
+## The loop
+
+When every task is done but the goal is not, `add.py status` shows
+`goal not met (m/n exit criteria)` where it would otherwise prompt to archive. That is the cue:
+
+1. **Gather** the carried inventory:
+   - open lessons — `add.py deltas` (the §7 OBSERVE deltas still `open`);
+   - the planned-but-unscaffolded tasks — the plan-vs-state line in `add.py status`;
+   - any reopened task — one a deepened verify returned to the flow (see below).
+2. **Propose** the next tasks: for each carried item worth doing now, draft a one-line task
+   (slug + title + why) and show the human. Group the trivial ones; do not propose noise.
+3. **Confirm** — the human accepts, edits, or declines each. No task is created without this.
+4. **Create** each accepted task — `add.py new-task <slug> --title "..."` — and run it through
+   the normal flow (specify → … → verify).
+5. **Repeat** until the work the goal needs is done.
+6. **Close** — when the goal is genuinely met, check the exit-criteria boxes in `MILESTONE.md`,
+   then `add.py milestone-done <slug>` succeeds (then consolidate the open deltas and archive).
+   Present the close via `report-template.md` — open with the ARC (goal · done · plan): the
+   milestone goal, the exit-criteria met that prove it, and the plan beyond the close.
+
+## Reopen is the verb; this loop is the trigger
+
+When a deepened verify (the no-skim wiring / dead-code / semantic check) finds a criterion unmet
+on a task already marked done, `add.py reopen <task> --to <phase> --reason "..."` returns it to the
+flow with a recorded reason and a reset gate. `reopen` is the recorded action; deciding WHEN to
+fire it — because a goal criterion is unmet — is this loop's job.
+
+## The reactivation residual (deferred)
+
+A reopen fired inside the loop happens while the milestone is still **active** — the goal-gate held
+it open, so it never reached done, and no reactivation is needed. The one residual — reopening a
+task inside a milestone that was already closed — is surfaced by `add.py check` (a done milestone
+with a live task reads as incoherent). Re-activating a closed milestone is **deferred**: resolve it
+by hand for now (the loop's own design keeps in-flight milestones open), until a later task makes
+milestone reactivation first-class.

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

@@ -1,35 +1,103 @@
-# Phase 0 — Setup (once per project)
+# Phase 0 — Setup (autonomous draft → one human baseline approval)
 
-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 **baseline approval**. 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-level 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 baseline-approval 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 instead of asking**. Open
+`adopt.md` and follow it: fill each living-doc 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 level
+
+An empty repo has no code to read, so run the short interview. This is the **co-specify at foundation
+level** 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 where your confidence is lowest 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 lowest-confidence-first using the
+one notation every scope level shares — `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>` — and
+tag thin or inferred answers `guessed`.
+
+## 3 · Draft to the lock (both paths)
+
+1. **Fill the living documentation** (it outlives 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 specification bundle.** `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: bundle → lock → build.
+4. **Write `.add/SETUP-REVIEW.md`** per `setup-review.md`: every decision you drafted (foundation, scope,
+   first contract), **lowest-confidence-first**, each tagged `guessed` | `evidence-grounded`.
+
+## 4 · The one human gate — the baseline approval
+
+Open the report with the ARC (goal · done · plan) per `report-template.md`, then present
+`SETUP-REVIEW.md` lowest-confidence-first (the `guessed` rows are what the human must actually check). They
+confirm **once** — an explicit yes to the baseline approval itself, in conversation; ambient agreement mid-stream is
+not a confirmation. On that recorded confirmation, you run the lock with their name:
+
+```bash
+python3 .add/tooling/add.py lock --by "<name>"
+```
+
+Typing the command themselves stays the **escape hatch** — the decision is always the human's; you just
+execute it. `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 specification-bundle approval and the baseline approval 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.
+<exit_gate>
+- [ ] `.add/state.json` exists; setup was seeded unlocked (`--await-lock`) then locked.
+- [ ] Living docs filled (brownfield: from code, tagged evidence-grounded; greenfield: from the interview).
+- [ ] First task created; §1–§3 drafted; `.add/SETUP-REVIEW.md` written lowest-confidence-first.
+- [ ] Human confirmed the baseline approval and `add.py lock --by` ran with their name; first task §3 `FROZEN @ v1`; build open.
+</exit_gate>
 
 ## 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/1-specify.md

@@ -11,42 +11,52 @@ understand the feature — that is information, not an obstacle. Stop and ask.
 
 1. **Diverge** — before drafting, surface the decision space: the 2–3 genuine framings of the
    feature + the open questions you would otherwise guess. Invite the user to add, kill,
-   redirect. (Conversational — no new file. At prototype/poc this collapses to one sentence.)
-2. **Converge** — draft §1, then RANK what you are least sure about (below).
+   redirect. (Conversational — no new file. At prototype/poc this shortens to one sentence.)
+2. **Converge** — draft §1, then RANK where your confidence is lowest (below).
 3. **Validate** — present the ranked uncertainty first; the user confirms, corrects, or sends back.
 
 ## Produce (in TASK.md §1)
 
+<output_format>
 - **Framings weighed** — a one-line trace of what you considered: `X (chosen) · Y · Z`.
 - **Must** — each required behavior.
 - **Reject** — each refused input/situation, paired with a **named error code**
   (`amount <= 0 -> "amount_invalid"`, never "handle bad input").
 - **After** — the state that is true once it succeeds.
-- **Assumptions — least-sure first** — ranked most-likely-wrong → least. The top 1–2 carry a
-  `⚠` flag: `⚠ <assumption> — least sure because <why>; if wrong: <cost>`. The rest are the
-  low-stakes `[x]` tail. Never a flat wall of equal `[x]` ticks — that is what gets rubber-stamped.
+- **Assumptions — lowest-confidence first** — ranked most-likely-wrong → least. The top 1–2 carry a
+  `⚠` flag: `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>`. The rest are the
+  low-stakes `[x]` tail. Keep the ranking visible — a flat list of equal `[x]` ticks gets approved without reading.
+</output_format>
 
-## The least-sure flag is bundle-wide
+## The lowest-confidence flag is bundle-wide
 
 The single human approval happens once, at the contract freeze, over the whole bundle. So your
-§1 ranking is the FIRST FEEDER into a bundle-level flag the user reads at the seam (`run.md`):
+§1 ranking is the first input into a bundle-level flag the user reads at the decision point (`run.md`):
 *"of everything I'm asking you to freeze, these 1–2 are most likely wrong."* A flag may point at
 a §1 assumption, an uncovered scenario, or the contract shape.
 
 ## AI prompt
 
-> Role: a domain analyst who brainstorms, then asks rather than assumes. Read CONVENTIONS,
-> GLOSSARY, and the user's raw input. First surface 2–3 framings + open questions and let me
-> react. Then produce §1: Framings weighed, every Must, every Reject with a named error code,
-> the After state, and the Assumptions RANKED least-sure first — flag the 1–2 you are least
-> sure about with why + cost. Never resolve an ambiguity by guessing.
+<prompt>
+Role: a domain analyst who brainstorms, then asks rather than assumes.
+Read first: CONVENTIONS · GLOSSARY · the user's raw input.
+Objective: fill §1 SPECIFY with zero ambiguity left for the AI to resolve by guessing.
+Steps:
+  1. Surface 2–3 framings + the open questions; let the user react before you draft.
+  2. Produce §1 — Framings weighed, every Must, every Reject with a named error code, the
+     After state, and the Assumptions RANKED lowest-confidence first.
+  3. Flag the 1–2 where your confidence is lowest, each with why + cost.
+Never: resolve an ambiguity by guessing.
+</prompt>
 
 ## Exit gate
 
+<exit_gate>
 - [ ] Framings weighed noted; every required behavior stated.
 - [ ] Every rejection has a named error code; success state-change described.
-- [ ] Assumptions ordered least-sure first; the 1–2 `⚠` flags carry why + cost — or an honest
+- [ ] Assumptions ordered lowest-confidence first; the 1–2 `⚠` flags carry why + cost — or an honest
       "none material" that still names the single biggest risk (never a blank "none").
+</exit_gate>
 
 ## Next
 

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

@@ -6,6 +6,7 @@ generated from it. Fill **§2 SCENARIOS** in TASK.md.
 
 ## Produce (in TASK.md §2)
 
+<output_format>
 ```gherkin
 Scenario: <short name>
   Given <starting situation>
@@ -15,20 +16,29 @@ Scenario: <short name>
 ```
 
 The `And ... unchanged` clause catches corrupting partial failures (e.g. a balance
-deducted before a check fails). Never omit it on a rejection.
+deducted before a check fails). Include it on every rejection.
+</output_format>
 
 ## AI prompt
 
-> Role: a specification tester. Read §1 and GLOSSARY. Write one scenario per Must
-> and per Reject rule. For every rejection add an And-clause asserting what must NOT
-> change. Results must be specific and observable — never "then it works".
+<prompt>
+Role: a specification tester.
+Read first: §1 · GLOSSARY.
+Objective: one scenario per Must and per Reject rule, each result specific and observable.
+Steps:
+  1. Write one scenario per Must rule and one per Reject rule.
+  2. For every rejection add an And-clause asserting what must NOT change.
+Never: settle for a vague result ("then it works") — results must be specific and observable.
+</prompt>
 
 ## Exit gate
 
+<exit_gate>
 - [ ] One scenario per Must rule.
 - [ ] One scenario per Reject rule.
 - [ ] Each result is a specific, observable fact.
 - [ ] Every rejection asserts what stays unchanged.
+</exit_gate>
 
 ## Next
 

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

@@ -1,12 +1,13 @@
 # Phase 3 — Contract (freeze the shape)
 
 Goal: fix the external shape — interfaces, data, names, error cases — and FREEZE
-it. This is the seam that makes the AI-led build safe: below it code is
+it. This is the decision point that makes the AI-led build safe: below it code is
 disposable; above it nothing breaks because the shape does not move. Fill
 **§3 CONTRACT** in TASK.md.
 
 ## Produce (in TASK.md §3)
 
+<output_format>
 - Interfaces (endpoints/functions/messages) with inputs/outputs.
 - Request/response shapes + persistent schema (note transactional needs).
 - Names drawn from `GLOSSARY.md` (same concept = same name everywhere).
@@ -14,26 +15,54 @@ disposable; above it nothing breaks because the shape does not move. Fill
 
 Then mark `Status: FROZEN @ v1`. Generate a mock + contract tests so dependent
 work can start before the real code exists.
+</output_format>
 
-**The freeze is the one approval.** This seam is where the single human approval lands, over the
-whole bundle (§1–§4). Before asking for it, present the bundle **least-sure first**: the 1–2 points
+**The freeze is the one approval.** This decision point is where the single human approval lands, over the
+whole bundle (§1–§4). Before asking for it, present the bundle **lowest-confidence first**: the 1–2 points
 most likely wrong (`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`) — aim the human's
-eye before they freeze. See `run.md`.
+eye before they freeze. Open that report with the ARC (goal · done · plan) per `report-template.md` so the
+human sees the goal this freeze serves and the plan beyond it, not just the bundle. See `run.md`.
+
+## The freeze review checklist
+
+The human's one minute, aimed. Walk these six before saying yes:
+
+- **⚠ flags first** — read the lowest-confidence flags; accept each knowing its cost if wrong.
+  The engine refuses an unflagged freeze before build: a frozen §3 with no well-formed
+  lowest-confidence flag is rejected (`unflagged_freeze`), and `audit` re-checks it on every
+  record that crossed.
+- **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 — the freeze stays the only 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,
-> GLOSSARY. Produce §3: interfaces, shapes, schema named from the glossary; a
-> response for every Reject code; a mock returning the contracted shapes and
-> contract tests pinning them. Mark FROZEN. No business logic. Never change a
-> frozen contract — a change reopens Specify.
+<prompt>
+Role: an interface architect; frozen contracts are immutable.
+Read first: §1 · §2 · GLOSSARY.
+Objective: produce §3 — the frozen external shape, nothing more.
+Steps:
+  1. Define interfaces, shapes, and schema named from the glossary, with a response for every Reject code.
+  2. Generate a mock returning the contracted shapes and contract tests pinning them.
+  3. Mark FROZEN. No business logic.
+Never: change a frozen contract — a change reopens Specify.
+</prompt>
 
 ## Exit gate
 
+<exit_gate>
 - [ ] Versioned and marked `FROZEN`.
 - [ ] Contract tests pass against the mock.
 - [ ] Every name matches the glossary.
 - [ ] Every spec rejection has a contracted response.
+</exit_gate>
 
 ## Next
 

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

@@ -1,4 +1,4 @@
-# Phase 4 — Tests (red safety net)
+# Phase 4 — Tests (failing-first suite)
 
 Goal: turn scenarios + contract into automated tests and confirm they FAIL before
 any code exists. This operationalizes red/green TDD: red now, green only after
@@ -12,24 +12,48 @@ before code exists is testing nothing and will wave bad code through later.
 
 ## Produce
 
+<output_format>
 - One executable test per scenario (§2), asserting **behavior, not internals**.
 - Contract-conformance tests (shapes + error responses from §3).
 - Side-effect assertions on rejection paths (`assert balance unchanged`).
 - A recorded coverage target in §4.
+</output_format>
+
+## 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
-> scenario into an executable test; add contract-conformance and edge-case tests;
-> run the suite and confirm it fails for the right reason. Record a coverage
-> target. Do NOT implement the feature. Never assert on internals.
+<prompt>
+Role: a test author who writes tests before code.
+Read first: §2 · §3.
+Objective: a red suite that fails for the right reason — behavior, not internals.
+Steps:
+  1. Turn each scenario into an executable test.
+  2. Add contract-conformance and edge-case tests.
+  3. Run the suite and confirm it fails for the right reason; record a coverage target.
+Never: implement the feature, or assert on internals.
+</prompt>
 
 ## Exit gate
 
+<exit_gate>
 - [ ] One test per scenario.
 - [ ] Suite runs and is **red for the right reason**.
 - [ ] Tests assert observable behavior.
 - [ ] Coverage target recorded.
+</exit_gate>
 
 ## Next
 

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

@@ -19,20 +19,30 @@ change request back to Specify. Honor the feature-specific safety rule named in
 
 ## AI prompt
 
-> Read §1, §3, §4, and CONVENTIONS. Make EVERY failing test pass, one small batch
-> at a time. Constraints: do NOT change any test; do NOT change the contract; honor
-> the §5 safety rule; use only allow-listed packages; stop and ask if unclear.
-> Report which tests pass and exactly what changed.
+<prompt>
+Role: implement the feature so EVERY failing test passes — the build phase.
+Read first: §1 · §3 · §4 · CONVENTIONS.
+Objective: every §4 test green, one small batch at a time.
+Steps:
+  1. Make EVERY failing test pass, one small batch at a time, honoring the §5 safety rule.
+  2. Report which tests pass and exactly what changed.
+Never: change a test or the contract; use a package off the allow-list; or push past something unclear instead of asking.
+</prompt>
 
 ## Exit gate
 
+<exit_gate>
 - [ ] All tests pass.
 - [ ] Coverage did not decrease.
 - [ ] No test and no contract modified by the AI.
 - [ ] No dependency outside the allow-list.
 - [ ] Change small enough to review in full.
+</exit_gate>
 
 ## Next
 
 `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)
+# Phase 6 — Verify (evidence + non-functional review)
 
 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,10 +26,33 @@ 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?
 
+## Part three — the deep check (do not skim)
+
+Green tests prove behavior on the inputs you thought of. They do not prove the change
+is *wired in*, nor that you did not leave a dead end behind — and for a non-coding change
+they prove nothing about whether you actually *read* the thing you signed off. So one more
+requirement, every gate:
+
+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.
+
+Record it in the §6 **Deep checks** block — where each new symbol is called (a reference
+search), the dead-code scan result, or the prose you read in full and what it confirmed.
+An unfilled Deep checks block is a **shallow verify**, not a PASS.
+
 ## Record exactly one outcome (no silent pass)
 
+When you present this gate to the human, open with the ARC (goal · done · plan) per
+`report-template.md`, and reconcile its FLAGS with `add.py report --decide`'s open-item count
+before the ask — per that file's reconcile rule (verify is where a flag-vs-digest mismatch bites).
+
 | Outcome | When |
 |---------|------|
 | `PASS` | all checks met |
@@ -30,7 +61,10 @@ 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.
+<exit_gate>
+- [ ] Evidence confirmed, non-functional risks checked, outcome recorded — a person approved, or
+  (under `autonomy: auto` with no residue) the run auto-resolved as the accountable owner.
+</exit_gate>
 
 ```bash
 python3 .add/tooling/add.py gate PASS          # marks the task done

package/skill/add/phases/7-observe.md

@@ -6,7 +6,7 @@ about the feature finally appears. Fill **§7** in TASK.md.
 
 ## Do
 
-1. **Release behind a blast-radius limit** — feature flag and/or gradual rollout.
+1. **Release behind a scope-of-impact limit** — feature flag and/or gradual rollout.
 2. **Reuse scenarios as monitors** — the §2 scenarios that defined "correct" now
    define what you alert on: overall error rate, each rejection's rate (a spike in
    one is a signal), latency of the risky operation under load.
@@ -15,16 +15,24 @@ about the feature finally appears. Fill **§7** in TASK.md.
 
 ## AI prompt
 
-> Role: a reliability analyst feeding the next cycle. Read telemetry, objectives,
-> incidents. Report error-budget burn; cluster errors and surface the top
-> real-world failures; draft a SPEC delta with evidence links. Never auto-roll-back
-> — recommend; a human owns the production decision.
+<prompt>
+Role: a reliability analyst feeding the next cycle.
+Read first: telemetry · objectives · incidents.
+Objective: turn what production shows into the next SPEC delta.
+Steps:
+  1. Report error-budget burn.
+  2. Cluster errors and surface the top real-world failures.
+  3. Draft a SPEC delta with evidence links.
+Never: auto-roll-back — recommend; a human owns the production decision.
+</prompt>
 
 ## Exit gate
 
+<exit_gate>
 - [ ] Released behind a flag/rollout.
 - [ ] Scenario-based monitors live.
 - [ ] A reviewed spec delta captured (becomes the next `new-task`).
+</exit_gate>
 
 ## Next