@pilotspace/add 1.8.0 → 1.9.0

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

@@ -12,23 +12,15 @@ the work — gathering them IS the job, not a detour.
 ## Gather (in TASK.md §0)
 
 - **Touches** — the real files · symbols · signatures the task will read or change,
-  named from the actual code (use your code-navigation tools — grep / symbol search,
-  never memory). Each as `path:symbol — what it is / how it is keyed`.
-- **Context (working folder)** — beyond code, the NON-code artifacts the task touches:
-  docs/textbase (README · `*.md` · design notes) · TODOs (`TODO.md` · `FIXME`/`TODO`/`HACK`
-  comments · task lists) · config/manifests (configs · `.env.example` · `pyproject`/`package`
-  · CI) · data/fixtures (samples · fixtures · schemas). Gather only the TASK-SPECIFIC
-  delta — never index the whole repo.
-- **Honors** — the patterns and conventions the work must respect, cited from
-  `PROJECT.md` / `CONVENTIONS.md`. Gather only the TASK-SPECIFIC delta — never
-  re-derive the architecture or re-run the setup brownfield scan.
-- **Anchors the contract cites** — the specific symbols §3 CONTRACT will name. The
-  contract may cite only anchors that appear here.
+  named from the actual code (use code-navigation tools — grep / symbol search, never memory).
+  Each as `path:symbol — what it is / how it is keyed`.
+- **Context (working folder)** — NON-code artifacts the task touches: docs/textbase (README · `*.md` · design notes) · TODOs (`TODO.md` · `FIXME`/`TODO`/`HACK` comments) · config/manifests (configs · `.env.example` · `pyproject`/`package` · CI) · data/fixtures. Task-specific delta only — never index the whole repo.
+- **Honors** — the patterns and conventions the work must respect, cited from `PROJECT.md` / `CONVENTIONS.md`. Task-specific delta only — never re-derive the architecture.
+- **Anchors the contract cites** — the specific symbols §3 CONTRACT will name. The contract may cite only anchors that appear here.
 
 **How — gather efficiently:** for the BROAD sweep, prefer a small-model subagent / fast
 index / skim (offload to a cheap context, return a compact map); then DEEPEN on what THIS
-task specifically needs — never lock a shallow first pass. A recommendation: the engine
-never spawns a subagent (tool-agnostic), so the orchestrating agent chooses.
+task specifically needs — never lock a shallow first pass.
 
 ## Greenfield / first task
 

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

@@ -1,9 +1,6 @@
 # Phase 0 — Setup (autonomous draft → one human baseline approval)
 
-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.
+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 one decision: the **baseline approval**. Brownfield is silent; greenfield keeps a short interview. Either way, the human's only gate is `add.py lock`.
 
 ## 1 · Zero-touch entry — you run init yourself
 
@@ -14,29 +11,21 @@ project name and stage from the repo, and **arm the baseline-approval gate** wit
 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`.
+- `--await-lock` seeds an *unlocked* setup — the engine refuses crossing into build or calling `gate` until you `lock`. A plain `init` is grandfathered-locked; its closing `lock` would error `already_locked`.
+- name + stage are **your judgment** (read from the dir name, README, manifests): throwaway → `prototype`, 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**).
+- `brownfield:` → existing code (go to **2a**);
+- no `brownfield:` → 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.
+The code answers the questions a greenfield interview would ask — **read it instead of asking**. Open `adopt.md` and follow it: fill each living-doc file from the code, never clobber an existing one, tag every decision `evidence-grounded` 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):
+level** move — diverge → converge → validate, as a task's §1 uses (`phases/1-specify.md`), lifted to the foundation. Ask the one load-bearing question per lens, draft, then rank lowest-confidence-first and show the top flag:
 
 | Lens | The one question that unblocks the section |
 |------|--------------------------------------------|
@@ -45,98 +34,59 @@ lifted to the foundation. Ask the one load-bearing question per lens (diverge),
 | 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`.
+Ask only the live ones. Rank: `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>` — tag thin answers `guessed`.
 
 ## 2c · Domain deep-dive — per-drive, across multiple turns (deepens §2b)
 
-§2b gets a foundation from one question per lens; this step DEEPENS it across **multiple
-turns**, one deep-dive per **drive** — naming all four, including the one §2b's lens list omitted:
-
 | Drive | Deepen |
 |-------|--------|
-| **DDD** (domain) | core nouns → model: the entities, the invariants, the bounded edges |
-| **SDD** (spec) | the milestone outcome → the behaviors and the explicit non-goals |
-| **UDD** (users) | the primary user → the jobs, the surface, the one flow that must feel right |
-| **TDD** (trust) | what "done & trusted" means: the risks to prove, the evidence that closes them |
+| **DDD** (domain) | core nouns → model: entities, invariants, bounded edges |
+| **SDD** (spec) | milestone outcome → behaviors and explicit non-goals |
+| **UDD** (users) | primary user → jobs, surface, the one flow that must feel right |
+| **TDD** (trust) | what "done & trusted" means: risks to prove, evidence that closes them |
 
-Capture each surfaced decision as an **ADR** (architecture decision record) into `PROJECT.md`
-**Key Decisions** as it lands — the Decisions lens becomes explicit ADR capture (the *why*, not just the *what*).
+Capture each surfaced decision as an **ADR** into `PROJECT.md` **Key Decisions** as it lands.
 
-**Under `autonomy: auto` with full context, auto-complete all four drives in one pass** — draft
-each without stopping to interview, still lowest-confidence-first, surfacing the top **flag**. Ask
-only the live drives; skip what the request already answered. This deepens **drafting**, never the
-gate: auto-complete NEVER skips the human baseline approval — the `lock` (§4) stays the one decision.
+**Under `autonomy: auto` with full context, auto-complete all four drives in one pass** — lowest-confidence-first, surfacing the top flag. This deepens **drafting**, never the gate: auto-complete NEVER skips the human baseline approval — the `lock` stays the one decision.
 
 ## 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`, and — for a UI project — `DESIGN.md` (the design source of truth: identity ·
-   principles · screens · the named-set foundation pointers + render recipe; delete it if there's no UI;
-   the design-definition loop that fills it — domain → components → wireframe → a captured screen confirmed before build — is `design.md`).
-   Brownfield: from the code. Greenfield: from the interview, gaps flagged `guessed`.
-2. **Propose, then size it.** You just read the codebase (brownfield) or interviewed (greenfield) — so
-   don't silently draft. First float a **kickoff suggestion** for the first milestone the human reacts to:
-   a **goal** (one outcome sentence), a **flow** (the breadth-first task order that gets there), and
-   **scenarios** (concrete examples of what the user can DO once it ships). Keep it a lightweight react-to
-   sketch — a few bullets, NOT the frozen `MILESTONE.md` or per-task §2 suites. This is show-before-ask:
-   the human reacts (confirm / adjust / redirect); you do not auto-create. On their reaction, draft its
-   `MILESTONE.md` (read `scope.md`) — goal · scope · exit criteria · breadth-first tasks.
+1. **Fill the living documentation**: `.add/PROJECT.md` (Domain · Spec/active milestone · UI/UX · Key Decisions), `CONVENTIONS.md`, `GLOSSARY.md`, `MODEL_REGISTRY.md`, `dependencies.allowlist`, and — for a UI project — `DESIGN.md` (delete if no UI; design loop: `design.md`). Brownfield: from code. Greenfield: from interview, gaps flagged `guessed`.
+2. **Propose, then size it.** Float a **kickoff suggestion** for the first milestone: a **goal** (one outcome sentence), a **flow** (task order), and **scenarios** (concrete examples of what ships). Not the frozen `MILESTONE.md`. On their reaction, draft `MILESTONE.md` (read `scope.md`).
 3. **Create the first task and draft its candidate specification bundle.** `new-task` is allowed pre-lock:
    ```bash
    python3 .add/tooling/add.py new-task <slug> --title "<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`.
+   Draft §1 · §2 · §3. **Leave §3 `Status: DRAFT`** — the lock is its approval. You MAY `advance` 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 drafted decision, **lowest-confidence-first**, tagged `guessed` | `evidence-grounded`.
 
 ## Run mode — how the build will be driven (propose parallel + auto; confirm to keep)
 
-Before the lock, surface ONE more choice so the human is aware of how ADD will drive the build:
-the **run mode**. Two settings compose it — the **autonomy** level (`add.py autonomy`, run.md: who owns
-the verify gate) and **streams** (`add.py waves` + `streams.md`: whether independent tasks pipeline).
-Show this table so the human sees the flow behavior of each, then PROPOSE the default:
+Before the lock, surface the **run mode** — **autonomy** (`add.py autonomy`, run.md) and **streams** (`add.py waves` + `streams.md`):
 
-| Run mode | Human gates that fire | Concurrency / flow behavior |
-|----------|-----------------------|-----------------------------|
-| **sequential · manual/conservative** | the contract freeze **and** every Verify, one task at a time | one task start-to-finish before the next; safest, slowest; the reviewer waits on each build |
-| **parallel · auto** *(proposed default)* | the contract freeze **only** — Verify auto-PASSes on complete evidence (security/residue still escalate) | `add.py waves` schedules independent tasks into waves; builds overlap behind their frozen contracts while you review one bundle; the reviewer is never blocked on a build |
+| Run mode | Human gates | Concurrency |
+|----------|-------------|-------------|
+| **sequential · manual/conservative** | contract freeze **and** every Verify | one task at a time; safest, slowest |
+| **parallel · auto** *(proposed default)* | contract freeze **only** — Verify auto-PASSes on complete evidence | `add.py waves` schedules independent tasks; builds overlap behind frozen contracts |
 
-**Propose `parallel + auto` as the default, and ask the human to confirm-to-keep** (or downgrade in
-one step — `add.py autonomy set conservative --project`, or just run tasks one at a time). This is a
-confirm, never a silent flip. Record the chosen mode in **`PROJECT.md` Key Decisions** (e.g. "run mode:
-parallel + auto (opt-out), confirmed by <name>") so every later session inherits it.
+**Propose `parallel + auto`, ask the human to confirm-to-keep** (or downgrade: `add.py autonomy set conservative --project`). Record the chosen mode in **`PROJECT.md` Key Decisions**.
 
-What the default does **not** change: the irreducible floor still holds — **one human approval per
-contract** fires no matter the mode. `auto` + `parallel` change the *order and throttle* of the build
-(which tasks run when, and who gates Verify), never *whether* the contract decision point fires. A
-high-risk task still refuses `auto` and forces a lowered rung (run.md guard).
+The irreducible floor: **one human approval per contract** fires no matter the mode.
 
 ## 4 · The one human gate — the baseline approval
 
-Open the report with the ARC (goal · done · plan) per `report-template.md`, render the baseline-lock DECISION as a guided choice (the recommended pick + described alternatives), then present
-`SETUP-REVIEW.md` lowest-confidence-first (the `guessed` rows are what the human must actually check). They
-confirm **once** — an explicit yes to the baseline approval itself, in conversation; ambient agreement mid-stream is
-not a confirmation. On that recorded confirmation, you run the lock with their name:
+Open the report with the ARC per `report-template.md`, render the DECISION as a guided choice, then present `SETUP-REVIEW.md` lowest-confidence-first. They confirm **once** — an explicit yes to the baseline approval itself; ambient mid-stream agreement is not a confirmation. On that recorded confirmation, you run the lock:
 
 ```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.
+Typing it themselves stays the **escape hatch** — the decision is always the human's; you just execute it. `lock` records the lock layers in one atomic write and opens the build.
 
 ## 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.
+- The lock **is** the first task's contract approval — do **not** ask for a separate contract-freeze sign-off.
+- Stamp the first task's §3 `Status: FROZEN @ v1`, then read `phases/5-build.md`.
 
 ## Exit gate
 
@@ -149,5 +99,4 @@ build. It is judgment-free — it does **not** parse `SETUP-REVIEW.md`; the huma
 
 ## Next
 
-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).*
+After the lock, read `phases/5-build.md` (build is open). Book: `docs/10-setup-and-stages.md`.

package/skill/add/phases/1-specify.md

@@ -3,44 +3,29 @@
 Goal: state what the feature MUST do and what it must REJECT, with zero ambiguity
 for the AI to resolve by guessing. Fill **§1 SPECIFY** in TASK.md.
 
-Specify is **co-specification**: brainstorm the shape WITH the user, draft it, then let
-the user validate with your advice. If you cannot write the spec, you do not yet
-understand the feature — that is information, not an obstacle. Stop and ask.
+Specify is **co-specification**: brainstorm the shape WITH the user, draft it, then validate. If you cannot write the spec, you do not yet understand the feature — stop and ask.
 
 ## Co-specify in three moves
 
-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 shortens to one sentence.)
+1. **Diverge** — 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 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.
 
-**Identity is direction, not default (UDD).** For UI/design work, identity values — the brand
-color, the core palette, the typeface — are human-owned. Surface them for discussion during
-Diverge; never assume a brand value. The UDD token dialect checks a token's *shape*; its *value*
-is the user's call (`udd-tokens.md`). For a UI feature with a screen, run the design-definition
-loop in `design.md` — domain → research and reuse components → wireframe → a real captured screen
-the human confirms before build — and carry the confirmed layout into the contract.
+**Identity is direction, not default (UDD).** Brand color, palette, typeface are human-owned — surface them during Diverge, never assume. For a UI feature with a screen, run the design-definition loop in `design.md`.
 
 ## Produce (in TASK.md §1)
 
 <output_format>
-- **Framings weighed** — a one-line trace of what you considered: `X (chosen) · Y · Z`.
+- **Framings weighed** — one-line trace: `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").
+- **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 — 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.
+- **Assumptions — lowest-confidence first** — ranked most-likely-wrong → least. The top 1–2 carry a `⚠` flag: `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>`. Keep the ranking visible — a flat list of equal `[x]` ticks gets approved without reading.
 </output_format>
 
 ## 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 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.
+The single human approval happens at the contract freeze, over the whole bundle. So your §1 ranking feeds 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."*
 
 ## AI prompt
 

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

@@ -1,8 +1,6 @@
 # Phase 2 — Scenarios (pass/fail cases)
 
-Goal: rewrite each rule as a concrete Given/When/Then that is readable by people
-and checkable by machines. This is the highest-leverage artifact — the tests are
-generated from it. Fill **§2 SCENARIOS** in TASK.md.
+Goal: rewrite each rule as a concrete Given/When/Then that is readable by people and checkable by machines. Fill **§2 SCENARIOS** in TASK.md.
 
 ## Produce (in TASK.md §2)
 

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

@@ -1,9 +1,6 @@
 # Phase 3 — Contract (freeze the shape)
 
-Goal: fix the external shape — interfaces, data, names, error cases — and FREEZE
-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.
+Goal: fix the external shape — interfaces, data, names, error cases — and FREEZE it. The decision point that makes the AI-led build safe: below it code is disposable; above it the shape does not move. Fill **§3 CONTRACT** in TASK.md.
 
 ## Produce (in TASK.md §3)
 
@@ -17,32 +14,21 @@ 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 decision point is where the single human approval lands, over the
-whole bundle (§1–§4). Before asking for it, present the bundle **lowest-confidence first**: the 1–2 points
-most likely wrong (`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`) — aim the human's
-eye before they freeze. Open that report with the ARC (goal · done · plan) per `report-template.md`, rendering the freeze DECISION as a guided choice (the recommended pick + described alternatives), so the
-human sees the goal this freeze serves and the plan beyond it, not just the bundle. See `run.md`.
-The approval also freezes the §5 Scope (may touch) + Strategy declarations — the bundle covers them.
+**The freeze is the one approval.** Present the bundle **lowest-confidence first**: the 1–2 points most likely wrong (`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`). Open with the ARC per `report-template.md`, rendering the freeze DECISION as a guided choice (recommended pick + described alternatives). See `run.md`. The approval also freezes the §5 **Scope (may touch)** allowlist + Strategy declarations.
 
 ## The freeze review checklist
 
 The human's one minute, aimed. Walk these seven 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?
+- **⚠ flags first** — read the lowest-confidence flags; accept each knowing its cost if wrong. The engine refuses an unflagged freeze before build (`unflagged_freeze`); `audit` re-checks it on every record that crossed.
+- **Intent** — does §1 say what you actually want built?
+- **Cases** — does every Must and Reject have an observable §2 scenario?
 - **Shape** — glossary names, error codes, additive vs breaking: is THIS the shape to freeze?
-- **Grounded** — does §3 cite anchors that exist in the §0 GROUND map (real files/symbols), not invented ones? `status`/`check` surface this — measure, never block.
-- **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.
+- **Grounded** — does §3 cite anchors that exist in the §0 GROUND map? `status`/`check` surface this.
+- **Risk** — high-risk or method-defining? Require `risk: high · autonomy: conservative` in the TASK.md header.
 - **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.
+Reject any line and the bundle goes back to draft; the freeze stays the only gate.
 
 ## AI prompt
 

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

@@ -1,8 +1,6 @@
 # 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
-Build. Fill **§4 TESTS** and write the suite into `.add/tasks/<slug>/tests/`.
+Goal: turn scenarios + contract into automated tests and confirm they FAIL before any code exists — red now, green only after Build. Fill **§4 TESTS** and write the suite into `.add/tasks/<slug>/tests/`.
 
 ## The must-fail principle
 
@@ -28,9 +26,8 @@ Resolution: `./…` → this task's dir · a token containing `/` → the projec
 (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
+ignored. Resolved files are deduped; reports mark declared counts with `†`.
+Paths are confined: anything resolving outside the project root counts 0 — `..` traversal, absolute paths, and
 symlink escapes are never read.
 
 ## AI prompt

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

@@ -7,30 +7,21 @@ removed all ambiguity. Write code into `.add/tasks/<slug>/src/`.
 ## Work in small batches
 
 Pick ONE task-sized slice, restate the tests it must satisfy, implement, run
-tests, iterate to green. Keep each batch small enough to review in full — you
-cannot move faster than you can verify.
+tests, iterate to green. Keep each batch small enough to review in full.
 
 ## Declaring the scope of impact (Scope + Strategy)
 
-§5 of TASK.md opens with two declarations, drafted WITH the specification bundle
-and frozen by the one §3 approval — never invented mid-build:
+§5 of TASK.md opens with two declarations, drafted WITH the specification bundle and frozen by the §3 approval — never invented mid-build:
 
-- **Scope (may touch)** — the allowlist of every file the build may write
-  (backticked tokens; grammar in the template comment). During build, needing a
-  file outside the declared Scope is a **STOP → change request** back to Specify,
-  never improvisation.
-- **Strategy (ordered batches)** — the planned build order. Guidance, not
-  enforced: it aims the small-batches loop, it does not gate it.
+- **Scope (may touch)** — the allowlist of every file the build may write (backticked tokens). Needing a file outside the declared Scope is a **STOP → change request** back to Specify, never improvisation.
+- **Strategy (ordered batches)** — the planned build order. Guidance, not enforced.
 
-Deferral, named: the engine gate (touched ⊆ declared) lands in the
-`scope-gate-enforce` task — until it ships this section is prose discipline.
+Deferral, named: the engine gate (touched ⊆ declared) lands in the `scope-gate-enforce` task — until it ships this section is prose discipline.
 
 ## The cardinal rule
 
 **Never weaken or delete a test to make it pass, and never edit the frozen
-contract.** That makes the code judge itself. A genuine need to change either is a
-change request back to Specify. Honor the feature-specific safety rule named in §5
-(e.g. atomic balance update) — the one property tests alone may not force.
+contract.** A genuine need to change either is a change request back to Specify. Honor the feature-specific safety rule named in §5 (e.g. atomic balance update).
 
 ## AI prompt
 
@@ -62,11 +53,6 @@ Never: change a test or the contract; use a package off the allow-list; or push
 `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`.
+> Under `autonomy: auto` Build and Verify run together as one evidence-auto-gated run. See `run.md`.
 >
-> **Honest redo.** If the verify gate finds a confirmed cheat (a tamper, or a reported
-> earned-green failure), the task returns HERE for an honest redo — revert the tampered
-> file or de-overfit src, then advance again. This is the bounded self-heal loop (`run.md`),
-> capped: after the cap a confirmed cheat HARD-STOPs to the human. Never weaken a test or
-> edit the frozen contract to pass.
+> **Honest redo.** A confirmed cheat returns the task HERE — revert the tampered file or de-overfit src, then advance again. This is the bounded self-heal loop (`run.md`), capped: after the cap it HARD-STOPs to the human. Never weaken a test or edit the frozen contract to pass.

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

@@ -4,21 +4,15 @@ Goal: establish trust and record an outcome. Passing tests are necessary, not
 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.
+> Under `autonomy: auto` (the default) a run auto-PASSes once evidence is complete —
+> every test green, convergence loops dry, and **no residue** (security · concurrency · architecture) —
+> recorded as *auto-resolved* with the named run as accountable owner. **Security is
+> always a HARD-STOP and is never auto-passed.** Under `autonomy: conservative`, or
+> whenever residue is found, this phase is **human-led**.
 
 ## Before you build — declare the build expectations
 
-Fill the §6 **Build expectations** block BEFORE you start Build: the OBSERVABLE outcomes a
-correct build must produce, derived from §2 SCENARIOS + §3 CONTRACT. At this gate, confirm each
-one against real evidence (the `confirmed by` column) — so verify proves the build is *correct*,
-not merely that the suite is green. An expectation with no evidence is not yet verified; passing
-tests on inputs you thought of never substitute for the outcome you promised.
+Fill the §6 **Build expectations** block BEFORE Build: OBSERVABLE outcomes derived from §2 SCENARIOS + §3 CONTRACT. At this gate, confirm each against real evidence (the `confirmed by` column). An expectation with no evidence is not yet verified.
 
 ## Part one — confirm the evidence
 
@@ -27,56 +21,27 @@ tests on inputs you thought of never substitute for the outcome you promised.
 - [ ] No test or contract was altered during build.
 - [ ] Every §6 Build expectation is confirmed by real evidence (not just a green test).
 
-If any is false, stop and return to Build — there is nothing to verify yet.
+If any is false, stop and return to Build.
 
 ## Part two — check what tests miss
 
-- **Concurrency/timing** — is it correct when two run at once? (Tests run serially
-  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?
+- **Concurrency/timing** — correct when two run at once? (Tests run serially and miss races.)
+- **Security** — exposed secrets, injection openings, unexpected dependencies. A security finding is always `HARD-STOP`, never a waiver. ANY note here escalates to the human — start it with `NOTE` or `⚠` so `add.py audit` can see it (`unescalated_security_note`).
+- **Architecture** — respects 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.
 
-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 it in the §6 **Deep checks** block. An unfilled Deep checks block is a **shallow verify**, not a PASS.
 
 ## Part four — was the green earned?
 
-A green suite proves the tests pass — not that the build EARNED them. Three judgment cheats
-pass the unchanged suite without earning it: src overfit to the test fixtures (special-cased
-to the literal inputs, not the general behavior §1 asked for), vacuous asserts (tautological —
-green even against an empty implementation), and real logic stubbed away (the function returns
-a constant the tests happen to accept). These cheats are invisible to the mechanical tamper
-tripwire, which only sees edited files. Score them with an adversarial refute-read: an
-independent reviewer — a subagent under `autonomy: auto` is recommended, the engine never
-spawns one — prompted to argue the green was NOT earned from outside the build context. This
-is the verify-gate, whole-suite specialization of run.md's adversarial verify (see run.md), not
-a new discipline. A confirmed earned-green failure is HARD-STOP-class: never auto-passed, never
-RISK-ACCEPTED — but a first cheat is a chance to redo: a confirmed cheat (mechanical tamper or a
-reported earned-green failure) enters the bounded self-heal loop — it returns to build for an honest
-redo, and only after the loop's cap does it HARD-STOP to the human (the loop lives in run.md).
+A green suite proves tests pass — not that the build EARNED them. Three judgment cheats pass the unchanged suite: src overfit to the test fixtures (special-cased to literal inputs), vacuous asserts (tautological — green against an empty implementation), and real logic stubbed away. These are invisible to the mechanical tamper tripwire. Score them with an adversarial refute-read: an independent reviewer — the engine never spawns one — prompted to argue the green was NOT earned. A confirmed earned-green failure is HARD-STOP-class: never auto-passed, never RISK-ACCEPTED — a first cheat enters the bounded self-heal loop (run.md).
 
 ## 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`, render the gate DECISION as a guided choice (the recommended pick + described alternatives), and reconcile its FLAGS with `add.py report --decide`'s open-item count
-before the ask — per that file's reconcile rule (verify is where a flag-vs-digest mismatch bites).
+When you present this gate, open with the ARC per `report-template.md`, render the DECISION as a guided choice, and reconcile FLAGS with `add.py report --decide`'s open-item count before the ask.
 
 | Outcome | When |
 |---------|------|

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

@@ -1,8 +1,6 @@
 # Phase 7 — Observe (feed the next loop)
 
-Goal: release deliberately, watch reality, and turn what you learn into the next
-spec. Release is not the finish line — it is where the most reliable information
-about the feature finally appears. Fill **§7** in TASK.md.
+Goal: release deliberately, watch reality, and turn what you learn into the next spec. Fill **§7** in TASK.md.
 
 ## Do
 

package/skill/add/phases/fast-lane.md

@@ -0,0 +1,31 @@
+# Fast lane — less ceremony, same floor
+
+The fast lane is the **collapsed, opt-in task path for small work**. Same flow — ground → specify →
+contract → tests → build → verify — with fewer sections and the bundle approved in one pass. It
+**collapses** the ceremony; it never drops the floor. The human opts in (`--fast`); the engine never
+guesses that a task is small.
+
+## When
+
+Pick it for a **small, low-risk, roughly single-file change**. Stay on the full lane when the work
+wants its scenarios enumerated — a milestone or release, an architecture or security change, anything
+cross-cutting, or anything you are not yet sure is small. In doubt, run the full lane.
+
+## How
+
+1. `add.py new-task <slug> --fast` scaffolds the minimal `TASK.fast.md` (sections {0,1,3,4,5,6};
+   §2 SCENARIOS and §7 OBSERVE dropped — §1's Accept line carries the behavior a scenario would).
+2. Ground, draft §1 + §3, and **freeze the contract as one batched approval** — the single decision
+   point, led by the lowest-confidence flag.
+3. Write a **red** test (§4), run it failing for the right reason.
+4. Build (§5) to green, then record the **verify gate** (§6).
+
+## Floor kept, only collapsed
+
+Three things never move, on either lane: a **frozen** §3 before build · a **red** test before build ·
+a recorded **verify gate** at the end (a security finding is always HARD-STOP). A `--fast` task is
+freeze-gated under ANY milestone — `advance` refuses `contract_not_frozen` while §3 is a draft. Speed
+comes from **fewer sections + auto-gating**, not from cutting any of the three.
+
+Not a way around the contract, the red test, or the gate; not for milestones or releases; not
+engine-chosen — ceremony is human-owned.