@pilotspace/add 1.2.0 → 1.4.0

package/skill/add/SKILL.md

@@ -20,7 +20,7 @@ You are the orchestrator. ADD keeps the AI fast *and* safe by fixing direction
 the result through passing evidence rather than a plausible-looking diff.
 
 **One file = one task.** Each feature lives in a single `.add/tasks/<slug>/TASK.md`
-with seven sections. You fill them top to bottom; the Python tool tracks where
+with a §0 ground preamble and seven step sections. You fill them top to bottom; the Python tool tracks where
 you are so context never rots across sessions.
 
 ## Always start here (orient — do not skip)
@@ -31,6 +31,11 @@ Run the tool to find the resume point instead of re-reading the repo:
 python3 .add/tooling/add.py status
 ```
 
+`status` points at two things to read when orienting: `.add/PROJECT.md` (the foundation) and
+`.add/SOUL.md` (your **voice** — tone, communication style, what keeps the human's trust). Read
+`.add/SOUL.md` each session and let it shape how you speak; it is human-owned and self-improving
+(the `soul-self-improve` path proposes voice deltas the human confirms).
+
 - **No `.add/state.json` yet** (a fresh install drops tooling + docs but does *not* init — so `status` says
   `no .add/ project found`) → enter **autonomous setup**: YOU run init yourself —
   `add.py init --name "<inferred>" --stage <picked> --await-lock` (don't tell the human to) — then read
@@ -61,6 +66,7 @@ Load the phase guide **only for the phase you are in** (progressive disclosure):
 | Phase | Guide | Produces (TASK.md section) | Who leads |
 |-------|-------|----------------------------|-----------|
 | setup | `phases/0-setup.md` | `.add/` + living docs + first §1–§3 + `SETUP-REVIEW.md` | AI drafts → **human locks** (the baseline approval) |
+| ground | `phases/0-ground.md` | §0 GROUND map (real files · symbols · the anchors §3 cites) | **AI** (the §0 preamble — no new gate) |
 | specify | `phases/1-specify.md` | §1 rules + ranked lowest-confidence flag | AI drafts (co-specify)† |
 | scenarios | `phases/2-scenarios.md` | §2 Given/When/Then | AI drafts† |
 | contract | `phases/3-contract.md` | §3 frozen shape | AI drafts → **human approves once** (the decision point)† |
@@ -73,7 +79,7 @@ Load the phase guide **only for the phase you are in** (progressive disclosure):
 contract freeze** (the decision point), presented lowest-confidence-first. See `run.md`.
 ‡ **Verify auto-gate (v6–v7).** Under `autonomy: auto` (the default) a run may auto-PASS on
 complete evidence — recorded as *auto-resolved*, an explicit PASS, not a skip. **Security always
-escalates** (HARD-STOP); so do concurrency / architecture residue and `conservative` autonomy.
+escalates** (HARD-STOP); so do concurrency / architecture residue and a lowered autonomy level (`conservative` / `manual`).
 See `run.md`.
 
 Whenever you present a decision point to the human in chat (intake · bundle approval · gate ·
@@ -85,13 +91,20 @@ In **observe**, also emit **lessons learned** — learnings tagged by which of t
 (`DDD · SDD · UDD · TDD · ADD`) they improve — so the foundation self-improves across loops.
 You write them as `open`; the human consolidates them into `PROJECT.md`. Read `deltas.md` for the
 grammar and the status lifecycle. At milestone close (or on demand), run the retrospective consolidation that
-gathers confirmed deltas into a versioned foundation — read `fold.md`.
+gathers confirmed deltas into a versioned foundation — read `fold.md`. Then (or on demand) compact the stable tail of each foundation spec into a rolled-up settled line — read `compact-foundation.md` (a SEPARATE step, run after `fold.md`).
+
+Observe also tunes your **voice**: propose a confirmable **voice delta** from the human's wordings +
+flow that, once they confirm, rewrites `SOUL.md` (the human is the only writer) — read `soul.md`.
 
 ## Beyond the bundle — load on demand
 
 Once **§3 CONTRACT is FROZEN**, the build→verify half is a dynamic, auto-gated run
-(`autonomy: auto` default, lowered to `conservative` for a human gate) — read `run.md`. To
-pipeline several ready tasks behind their own frozen contracts, read `streams.md`.
+(`autonomy: auto` default, lowered to `conservative` or `manual` for a human gate) — read `run.md`. To
+pipeline several ready tasks behind their own frozen contracts, read `streams.md`. To delegate
+one piece of your plan to a subagent that follows it — when to spawn, the plan-following prompt
+template, the tier pick — read `advisor.md`; and at any decision point self-score your draft
+(0–1 across six dimensions, refine if any < 0.9) with `confidence.md`. Both are advisory: the
+engine never spawns, and the self-score is never a gate.
 
 When a milestone's tasks are all done but its **goal** (the `MILESTONE.md` exit criteria) is not
 yet met, `milestone-done` holds the milestone open — read `loop.md` for the dynamic loop that turns

package/skill/add/advisor.md

@@ -0,0 +1,75 @@
+# Advisor — spawning one subagent to follow your plan
+
+The **advisor** strategy is for the orchestrating agent: spawn a *single* subagent to execute
+one piece of your plan, then merge its verdict back in. It is the single-subagent companion to
+`streams.md` — streams pipelines *many* independent tasks in parallel worktrees; the advisor
+delegates *one* well-scoped piece (a sweep, a review, a batch) while you stay in the loop. The
+engine never spawns; this is your judgment to make per step.
+
+## When to spawn — and when not
+
+Spawn a subagent when the piece is **separable and worth the round-trip**:
+
+- **Broad / expensive sweep** — gather a wide map cheaply, return a compact result (the `0-ground`
+  broad sweep is the canonical case).
+- **Independent adversarial review** — a fresh context argues *against* your result (the `6-verify`
+  earned-green refute-read), so the check is not graded by the author.
+- **A well-scoped delegable batch** — a self-contained slice with a clear contract and return shape.
+- **Context offload** — work that would bloat your context but compresses to a small verdict.
+
+Do **not** spawn when the work is narrow and cheap enough to do in-context: a small sweep, a
+two-file read, a quick edit. A spawn costs a round-trip and a fresh context — pay it only when
+the piece is big or independent enough to earn it. When in doubt, do it in-context.
+
+## The plan-following prompt template
+
+Give the subagent the *piece of your plan it owns* and a fixed return shape. This reuses
+`streams.md`'s worker-contract tags for a single advisory subagent — the contract is identical
+on any runner; only the spawn adapter (see `streams.md`) changes.
+
+```xml
+<objective>
+Execute THIS piece of the orchestrator's plan: {{PIECE}}. You own only this piece — not the
+surrounding decisions. Return a verdict; do not record state.
+</objective>
+
+<persona>
+You are a {{DOMAIN}} engineer. Correctness over speed; a wrong-but-plausible result is expensive.
+Work step by step, following the plan:
+1. Load the context files; confirm you understand the piece you own.
+2. Do the work in small steps, honoring the orchestrator's plan and constraints.
+3. Self-score your result with confidence.md; if any dimension < 0.9, refine before returning.
+</persona>
+
+<context_files>
+the plan / task files the piece needs (read-only unless the piece says otherwise)
+</context_files>
+
+<return>
+End with a structured verdict the orchestrator parses and RECORDS:
+{ piece, result, evidence, confidence: {per-dimension 0–1}, open_questions }.
+Do NOT run add.py or write any shared state — you propose, the orchestrator records.
+</return>
+```
+
+## Choosing the model — vendor-neutral tiers
+
+Reuse `streams.md`'s tiers, never a new vocabulary: **mid** (Claude Code: `sonnet`) for ordinary,
+well-scoped pieces with a clear contract; **top** (Claude Code: `opus`) for complex, ambiguous, or
+cross-cutting pieces. The tier maps to the runner's model id through the same adapter `streams.md`
+defines. A stronger model never buys back a human gate: high-risk scope still escalates.
+
+## The hard rule — you delegate, you do not abdicate
+
+<constraints>
+The engine never spawns — spawning is the orchestrating agent's choice (tool-agnostic). And:
+- the subagent PROPOSES; the orchestrator RECORDS — a worker never runs add.py or writes shared
+  state (state.json, MILESTONE.md, a sibling's files): you read its verdict and record the outcome;
+- delegation never lowers a gate — a SECURITY finding still HARD-STOPs, and high-risk scope still
+  escalates to the human, whoever (or whatever tier) did the work;
+- the spawned subagent returns its confidence.md self-score; a low score is a signal to refine or
+  re-spawn, never a pass.
+</constraints>
+
+> Used per step: each phase guide's Advisor hook points here, so an agent spawns in the idiom of
+> the phase it is in (see the per-step hooks).

package/skill/add/compact-foundation.md

@@ -0,0 +1,53 @@
+# Foundation compaction — collapse the stable tail
+
+This is the **retrospective shrink**. `fold.md` PREPENDS new learnings (newest-first); foundation
+compaction later COLLAPSES the stable tail of each foundation spec into a rolled-up settled line — so
+PROJECT.md, CONVENTIONS.md, GLOSSARY.md, and MODEL_REGISTRY.md keep to one screen as the project grows.
+
+You (the AI) **gather and propose**; the **human confirms**; you then write the settled line. This is a
+**convention**, not a command — there is no `add.py compact-foundation` (the engine stays judgment-free).
+It is DISTINCT from the engine `add.py compact <slug>` (the archive recovery-bundle move).
+
+## When
+
+At **milestone close** (after `fold.md`) or **on demand** when a spec has grown past one screen.
+Compaction is a SEPARATE step from `fold.md` — never merged into the retrospective consolidation.
+
+## Eligibility (one shared test)
+
+An entry is compaction-eligible **IFF** its milestone is **shipped** (done/archived) **AND** it carries
+**zero open residues**/deltas. An unshipped or open-residue entry is NOT eligible — leave it live
+(`open-residue-version`).
+
+## The ritual
+
+1. **Gather** — collect the stable, shipped, zero-residue tail of the target spec (its oldest entries).
+2. **Propose** — draft the per-spec rolled-up settled line (see the shapes below) and show the human.
+3. **Confirm** — the human accepts or declines. No write happens without confirmation.
+4. **Write** — replace the collapsed tail with ONE settled line at the BOTTOM (newest-first: live records
+   stay on top, the settled line anchors at the tail), carrying a git/archive pointer.
+
+## Per-spec rolled-line shapes (from the frozen compaction-contract)
+
+- **PROJECT.md §Spec** — a run of stable `[folded fv N..M]` bullets → `settled fvN–fvM — <theme> (see git)`.
+- **PROJECT.md §Key-Decisions** — matching shipped rows → one `| settled <dateA>–<dateB> | <N> decisions rolled | … | see git |` row at the tail.
+- **CONVENTIONS.md** — a run of stable `(TAG)` learnings → `- settled conventions <range> — <N> rules (see git)`.
+- **GLOSSARY.md** — a verbose, stable definition → its terse canonical line + `(rationale: see git)`. *(forward-looking — small today.)*
+- **MODEL_REGISTRY.md** — superseded model rows → `Prior models: <list> (see git)`. *(forward-looking — nothing to compact yet.)*
+
+## Preservation (every collapse)
+
+- **Never delete** — summarize and point; a settled line is lossy on prose, lossless on traceability.
+- A surviving **git**/archive pointer is mandatory (`trail-loss` if dropped).
+- **OPEN residues stay** live; the audit trail is summarized-not-deleted.
+
+## Reject codes (judgment-checked — the AI proposes, the human confirms)
+
+- `open-residue-version` — the entry is unshipped or has ≥1 open delta/residue; leave it live.
+- `trail-loss` — the collapse would drop the git/archive pointer or the audit summary.
+- `wrong-order` — a record is not newest-first, or the settled line is not at the tail.
+
+## Distinct from `add.py compact`
+
+Foundation compaction ≠ engine `add.py compact <slug>`. It mirrors `fold.md`'s "AI proposes, human
+confirms" voice and stays convention-guided — no engine command, no `add.py check` enforcement.

package/skill/add/confidence.md

@@ -0,0 +1,48 @@
+# Confidence — the self-score that aims attention
+
+The **confidence self-score** is an *advisory* check an agent runs on its own drafted artifact
+— a spec, a contract, a build, or a verdict returned by a spawned subagent — *before* it
+presents it. It sharpens the draft and aims the reader's eye at the soft spots; it is never a
+gate. Score it privately, refine while it is cheap, then surface what stayed uncertain.
+
+## The six dimensions
+
+Score each from 0 to 1 (0–1), honestly, on the artifact you are about to hand over:
+
+- **Completeness** — did it cover every rule, scenario, and rejection the task asked for?
+- **Clarity** — would the next reader understand it without you in the room?
+- **Practicality** — is it feasible and implementable as written, against the real code?
+- **Optimization** — does it balance correctness, simplicity, and cost — no gold-plating, no corner cut?
+- **Edge cases** — did it name the failure modes, the concurrency, the empty/oversized inputs?
+- **Self-evaluation** — does it carry its own refine step — a way to catch its own mistakes?
+
+If **any** dimension scores **< 0.9**, refine the artifact before you present it (or before you
+return from a spawned subagent), then re-score. The point is to spend the cheap iteration now,
+not after a human has read past the weak spot.
+
+## Where it plugs in
+
+- It **feeds the lowest-confidence flag** (run.md · phases/1-specify.md): the lowest-scoring
+  dimension or point is what you surface ⚠-first at the contract freeze. The self-score is the
+  private computation; the lowest-confidence flag is the public surfacing of its weakest point —
+  this rubric only *aims* that flag, it does not redefine it.
+- A persistently low score on a risky scope is a signal to **recommend lowering the autonomy
+  level** (auto → conservative / manual; run.md). Recommend it — never force it; choosing the
+  autonomy level stays the human's call.
+
+## The hard rule — advisory, never a gate
+
+<constraints>
+The confidence self-score is advisory only — it is never a gate. It never:
+- auto-PASSes a verify or blocks a run — the verify outcome rests on evidence (passing tests,
+  the non-functional review), not on a number the agent assigned itself;
+- substitutes for evidence or for the human decision point;
+- is recorded as a score the human "agreed to" — a self-asserted score that gated would only
+  move an unread approval one level up (run.md).
+
+What it MAY do: aim the lowest-confidence flag, trigger a refine pass, and recommend lowering
+the autonomy level. The gate itself stays evidence-based and human-owned.
+</constraints>
+
+> Used per step: each phase guide's Confidence hook points here, so an agent self-scores in the
+> idiom of the phase it is in (see the per-step hooks).

package/skill/add/fold.md

@@ -19,7 +19,7 @@ lives here so the engine stays judgment-free.
 2. **Group** — bucket them by competency (`DDD · SDD · UDD · TDD · ADD`).
 3. **Propose** — for each, draft the exact foundation edit (see routing) and show the human.
 4. **Confirm** — the human accepts or declines each delta. No write happens without this.
-5. **Write** — append the accepted edits, flip each delta's status, and bump the version.
+5. **Write** — prepend the accepted edits at the top (newest-first), flip each delta's status, and bump the version.
 
 ## Consolidation routing (every competency has a home)
 
@@ -31,15 +31,15 @@ lives here so the engine stays judgment-free.
 | `TDD` | `CONVENTIONS.md` | append a testing convention (no PROJECT.md section — it is the engine) |
 | `ADD` | `CONVENTIONS.md` | append a build/harness convention (likewise the engine) |
 
-**Every** consolidation — whatever the competency — ALSO appends one row to `PROJECT.md` **§Key Decisions**
+**Every** consolidation — whatever the competency — ALSO prepends one row at the TOP of `PROJECT.md` **§Key Decisions** (newest-first)
 (date · decision · why · outcome): the universal, auditable trail of what the foundation learned.
 
 ## Status transitions & version
 
-- on **confirm**: the delta moves `open` → `folded` (and its edit is appended to the routed target).
+- on **confirm**: the delta moves `open` → `folded` (and its edit is prepended at the top of the routed target, newest-first).
 - on **decline**: the delta moves `open` → `rejected` and is **left in place** — never deleted —
   so "we considered this and chose not to act" stays auditable.
-- a consolidation is **append-only**: it adds bullets/rows; it never silently rewrites existing foundation text.
+- a consolidation is **append-only (newest-first)**: it PREPENDS new bullets/rows at the top and never silently rewrites existing foundation text — EXCEPT via the recorded **compaction door** (`compact-foundation.md`): eligible (shipped + zero open residues) stable entries collapse upward into a rolled-up settled line at the tail. Reject: `open-residue-version` · `trail-loss` · `wrong-order`.
 - each consolidation session **bumps** the `foundation-version:` marker in `PROJECT.md` by one (monotonic int).
 
 ## Reject codes (the AI is first check, the human the backstop)

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

@@ -0,0 +1,68 @@
+# Phase 0 — Ground (the real codebase)
+
+Goal: before you specify anything, gather the REAL current working folder the task will
+touch — the actual files, symbols, signatures, docs, todos, config, data, patterns, and conventions — so the
+contract, tests, and build are grounded in what exists, not in what you assume.
+Fill **§0 GROUND** in TASK.md. Ground is a per-task preamble to the seven steps;
+it is **AI-owned** — no human gate here (the one approval stays at the §3 freeze).
+
+If you cannot name the files and symbols the task touches, you do not yet understand
+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.
+
+**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.
+
+## Greenfield / first task
+
+The first task of a project runs ground too. When there is little or no code yet
+(greenfield), or you are mid-setup, your grounding IS the foundation docs / brownfield
+scan you just produced — point at them; do not re-scan. An honest "new module, no
+existing code; honors CONVENTIONS.md §X" is a complete grounding.
+
+## AI prompt
+
+<prompt>
+Role: an engineer who reads the real code before designing against it.
+Read first: PROJECT.md · CONVENTIONS.md · the actual files the task touches.
+Objective: fill §0 GROUND with the real files/symbols/signatures + the conventions to
+honor + the anchor points the contract will cite — gathered from the codebase, never assumed.
+Steps:
+  0. Sweep broad cheaply first — prefer a small-model subagent / fast index / skim — then deepen task-specifically.
+  1. Locate the files and symbols the task reads or changes (code tools, not memory).
+  2. Record their signatures / how they are keyed; cite the conventions to honor (task delta only).
+  3. Name the anchors §3 will cite.
+Never: invent a file, symbol, or signature you have not opened.
+</prompt>
+
+## Exit gate
+
+<exit_gate>
+- [ ] The real files/symbols the task touches are named (from the code, not assumed).
+- [ ] The conventions to honor are cited (task-delta only; no architecture re-scan).
+- [ ] The anchors §3 will cite are listed — §3 names only anchors that exist here.
+</exit_gate>
+
+> **Advisor · Confidence** — a broad sweep is the canonical spawn case (advisor.md); self-score your grounding before you specify against it (confidence.md).
+
+## Next
+
+`python3 .add/tooling/add.py advance` → read `phases/1-specify.md`.
+Book: `docs/02-the-flow.md` (the flow; ground is the §0 preamble to the seven steps).

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

@@ -49,13 +49,40 @@ Ask only the live ones; skip what the request already answers. Rank your drafts
 one notation every scope level shares — `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>` — and
 tag thin or inferred 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 |
+
+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*).
+
+**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.
+
 ## 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.
+   `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).
+   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.
 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>"
@@ -66,6 +93,28 @@ tag thin or inferred answers `guessed`.
 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`.
 
+## 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:
+
+| 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 |
+
+**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.
+
+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).
+
 ## 4 · The one human gate — the baseline approval
 
 Open the report with the ARC (goal · done · plan) per `report-template.md`, then present

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

@@ -15,6 +15,11 @@ understand the feature — that is information, not an obstacle. Stop and ask.
 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`).
+
 ## Produce (in TASK.md §1)
 
 <output_format>
@@ -58,6 +63,8 @@ Never: resolve an ambiguity by guessing.
       "none material" that still names the single biggest risk (never a blank "none").
 </exit_gate>
 
+> **Advisor · Confidence** — for an unfamiliar domain, spawn a researcher (advisor.md); self-score the spec and let the lowest dimension aim your ⚠ flag (confidence.md).
+
 ## Next
 
 `python3 .add/tooling/add.py advance` → read `phases/2-scenarios.md`.

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

@@ -40,6 +40,8 @@ Never: settle for a vague result ("then it works") — results must be specific
 - [ ] Every rejection asserts what stays unchanged.
 </exit_gate>
 
+> **Advisor · Confidence** — delegate a wide scenario sweep when the surface is large (advisor.md); score Edge cases honestly — a missing case surfaces there first (confidence.md).
+
 ## Next
 
 `python3 .add/tooling/add.py advance` → read `phases/3-contract.md`.

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

@@ -22,10 +22,11 @@ whole bundle (§1–§4). Before asking for it, present the bundle **lowest-conf
 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` 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 review checklist
 
-The human's one minute, aimed. Walk these six before saying yes:
+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
@@ -34,6 +35,7 @@ The human's one minute, aimed. Walk these six before saying yes:
 - **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?
+- **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.
 - **Tests** — will §4 go red for the right reason, asserting behavior rather than internals?
@@ -64,6 +66,8 @@ Never: change a frozen contract — a change reopens Specify.
 - [ ] Every spec rejection has a contracted response.
 </exit_gate>
 
+> **Advisor · Confidence** — a second opinion on a risky shape is worth a spawn (advisor.md); a low self-score is your cue to lower autonomy before you freeze (confidence.md).
+
 ## Next
 
 `python3 .add/tooling/add.py advance` → read `phases/4-tests.md`.

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

@@ -55,6 +55,8 @@ Never: implement the feature, or assert on internals.
 - [ ] Coverage target recorded.
 </exit_gate>
 
+> **Advisor · Confidence** — spawn a test-author for a broad red suite (advisor.md); score Completeness — one test per scenario, every rejection covered (confidence.md).
+
 ## Next
 
 `python3 .add/tooling/add.py advance` → read `phases/5-build.md`.

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

@@ -10,6 +10,21 @@ 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.
 
+## 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:
+
+- **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.
+
+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
@@ -36,9 +51,12 @@ Never: change a test or the contract; use a package off the allow-list; or push
 - [ ] Coverage did not decrease.
 - [ ] No test and no contract modified by the AI.
 - [ ] No dependency outside the allow-list.
+- [ ] No file outside the declared §5 Scope was touched.
 - [ ] Change small enough to review in full.
 </exit_gate>
 
+> **Advisor · Confidence** — delegate an independent, well-scoped batch (advisor.md); self-score before you present green, and refine while it is cheap (confidence.md).
+
 ## Next
 
 `python3 .add/tooling/add.py advance` → read `phases/6-verify.md`.
@@ -46,3 +64,9 @@ 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`.
+>
+> **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.

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

@@ -47,6 +47,22 @@ Record it in the §6 **Deep checks** block — where each new symbol is called (
 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.
 
+## 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).
+
 ## Record exactly one outcome (no silent pass)
 
 When you present this gate to the human, open with the ARC (goal · done · plan) per
@@ -66,6 +82,8 @@ before the ask — per that file's reconcile rule (verify is where a flag-vs-dig
   (under `autonomy: auto` with no residue) the run auto-resolved as the accountable owner.
 </exit_gate>
 
+> **Advisor · Confidence** — the earned-green refute-read is the canonical adversarial spawn (advisor.md); score the verdict before you record the gate (confidence.md).
+
 ```bash
 python3 .add/tooling/add.py gate PASS          # marks the task done
 # or: add.py gate RISK-ACCEPTED   |   add.py gate HARD-STOP (return to Build)

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

@@ -12,6 +12,11 @@ about the feature finally appears. Fill **§7** in TASK.md.
    one is a signal), latency of the risky operation under load.
 3. **Draft the next spec delta** — every defect, surprise, or new need becomes a
    concrete change that re-enters the flow at Specify (a new task).
+4. **Propose a voice delta** — you just worked a whole task alongside the human, so
+   notice where your voice diverged from theirs (their wordings + flow) and propose a
+   confirmable **voice delta** that tunes `SOUL.md`. Emit it `open`; the human confirms;
+   only then do you rewrite the routed SOUL.md section. Read `soul.md` for the grammar,
+   the routing, and the human-is-only-writer rule.
 
 ## AI prompt
 
@@ -34,6 +39,8 @@ Never: auto-roll-back — recommend; a human owns the production decision.
 - [ ] A reviewed spec delta captured (becomes the next `new-task`).
 </exit_gate>
 
+> **Advisor · Confidence** — spawn a reviewer to mine the run for lessons (advisor.md); score Self-evaluation — did this loop teach the foundation? (confidence.md).
+
 ## Next
 
 Loop. The artifacts you built are living documents the next cycle refines.