@pilotspace/add 1.7.3 → 1.9.0

package/skill/add/loop.md

@@ -1,11 +1,11 @@
 # 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.
+This guide 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`
+You **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)
@@ -13,19 +13,19 @@ creates each one. The engine never decides what the next task is — that is jud
 `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.
+`- [x]`/`- [ ]` tally, it never judges whether the goal is met. 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.
+both refuse a milestone that is not done. 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:
+`goal not met (m/n exit criteria)`. That is the cue:
 
 1. **Gather** the carried inventory:
    - open lessons — `add.py deltas` (the §7 OBSERVE deltas still `open`);
@@ -38,36 +38,32 @@ When every task is done but the goal is not, `add.py status` shows
    the normal flow (specify → … → verify).
 5. **Repeat** until the work the goal needs is done.
 6. **Close** — when the goal is genuinely met, run the **ship review** before you close:
-   - **Fill the ship review first** — write the milestone's `## Close — ship review` section (the
-     scaffold ships in `MILESTONE.md`): **Ship by domain** — what changed per bounded context
-     (`tooling` · `skill` · `book`, or "untouched"); **Cross-task evidence** — one row per task
-     (`gate` · `tests` · `residue`); and the **Goal met?** map — each exit criterion tied to the
-     evidence that satisfies it. This is the whole-milestone, cross-task evidence the human READS;
-     it is evidence, **not a new gate**.
+   - **Fill the ship review first** — write the milestone's `## Close — ship review` section:
+     **Ship by domain** — what changed per bounded context (`tooling` · `skill` · `book`, or
+     "untouched"); **Cross-task evidence** — one row per task (`gate` · `tests` · `residue`);
+     and the **Goal met?** map — each exit criterion tied to the evidence that satisfies it.
+     This is the whole-milestone cross-task evidence the human READS; it is evidence, not a gate.
    - **Check the boxes** — read that evidence, then check the exit-criteria boxes in `MILESTONE.md`
-     (the single affirmation — the same gate as ever), and `add.py milestone-done <slug>` succeeds
-     (then consolidate the open deltas and archive — the `milestone-done → fold → compact → archive`
-     lifecycle, per `fold.md` · `compact-foundation.md`).
-   - **Define the release steps** — write the milestone's `## Release steps` (merge is one small step
-     among them; PR, asset export, tag/publish are others — tool-agnostic hints the human runs).
-     These **feed** the release scope — read `release.md` for the cut; loop.md never re-specifies it.
-   Present the close via `report-template.md` — open with the ARC (goal · done · plan): the milestone
-   goal, the exit-criteria met (with the ship-review evidence) that prove it, and the plan beyond the
-   close. Render the close as a guided choice — the recommended next move + its described alternatives
-   (per `report-template.md`).
+     (the single affirmation), and `add.py milestone-done <slug>` succeeds (then consolidate open
+     deltas and archive — the `milestone-done → fold → compact → archive` lifecycle, per
+     `fold.md` · `compact-foundation.md`).
+   - **Define the release steps** — write the milestone's `## Release steps` (merge is one small
+     step among them; PR, asset export, tag/publish are others). These **feed** the release scope —
+     read `release.md` for the cut; loop.md never re-specifies it.
+   Present the close via `report-template.md` — open with the ARC (goal · done · plan) and
+   render as a guided choice (recommended next move + described alternatives).
 
 ## 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.
+When a deepened verify 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. 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.
+A reopen fired inside the loop happens while the milestone is still **active** — the goal-gate
+held it open, so it never reached done. 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,
+until a later task makes milestone reactivation first-class.

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 |
 |---------|------|