@pilotspace/add 1.13.0 → 1.15.0

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

@@ -1,46 +1,43 @@
 # 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).
+Goal: before you specify, gather the REAL working folder the task touches — files, symbols,
+signatures, docs, config, data, conventions — so the contract/tests/build are grounded in what
+exists, not assumed. Fill **§0 GROUND** in TASK.md: a per-task preamble to the seven steps,
+**AI-owned** — no human gate (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.
+If you cannot name the files and symbols the task touches, you do not yet understand it —
+gathering them IS the job.
 
 ## Gather (in TASK.md §0)
 
-- **Touches** — the real files · symbols · signatures the task will read or change,
-  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.
+- **Touches** — the real files · symbols · signatures the task reads or changes, named from the
+  actual code (code-navigation tools — grep / symbol search, never memory). Each as `path:symbol — what it is / how keyed`; cite the **symbol**, not a bare line number (`l.NNN` rots at build; symbols survive).
+- **Context (working folder)** — NON-code artifacts touched: docs/textbase (`*.md`) · TODOs (`TODO`/`FIXME`) · config/manifests (`pyproject`/`package`/CI) · data/fixtures. Task-delta only.
+- **Honors** — patterns/conventions the work must respect, cited from `PROJECT.md`/`CONVENTIONS.md`. Task-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.
+- **Issues/Risks (→ feed §1)** — concrete problems · traps · untestable risks you find in the real code while grounding; §1 SPECIFY builds on these, not on assumptions. Task-delta only.
+- **Related intent** — the WHY: `PROJECT.md §` · `GLOSSARY` term(s) · the originating request/milestone rationale (intent, not Honors' conventions). Task-delta.
+- **Ground SHA** — the commit you grounded against (`git rev-parse --short HEAD`); any line ref is "as of" it. `check` warns on a §0 that cites line numbers with no SHA.
 
-**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.
+**How:** sweep BROAD cheaply (small-model subagent / fast index / skim → compact map), then DEEPEN on what THIS task needs — don't lock a shallow pass.
 
 ## 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.
+The first task runs ground too. With little/no code (greenfield) or mid-setup, your grounding IS
+the foundation docs / brownfield scan you produced — point at them, don't re-scan. An honest
+"new module, no code; honors CONVENTIONS.md §X" is complete.
 
 ## 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.
+Read first: PROJECT.md · CONVENTIONS.md · the files the task touches.
+Objective: fill §0 GROUND from the codebase — files/symbols/signatures + conventions + the
+anchors §3 cites + issues/risks found; 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.
+  0. Sweep broad cheaply (small-model subagent / fast index / skim), then deepen task-specifically.
+  1. Locate the files/symbols the task reads or changes (code tools, not memory).
+  2. Record signatures/keying; cite conventions (task-delta); note risks for §1; name §3's anchors.
 Never: invent a file, symbol, or signature you have not opened.
 </prompt>
 
@@ -48,17 +45,18 @@ Never: invent a file, symbol, or signature you have not opened.
 
 <exit_gate>
 - [ ] **Touches** — the real files/symbols the task touches are named (from the code, not assumed).
-- [ ] **Context** (working folder) — the non-code artifacts the task touches (docs · todos · config · data) are named, task-delta only.
-- [ ] **Honors** — the patterns/conventions to honor are cited (task-delta only; no architecture re-scan).
-- [ ] **Anchors** — the anchors §3 will cite are listed — §3 names only anchors that exist here.
+- [ ] **Context** (working folder) — the non-code artifacts touched (docs · config · data) are named, task-delta only.
+- [ ] **Honors** — the patterns/conventions to honor are cited (task-delta; no architecture re-scan).
+- [ ] **Anchors** — the anchors §3 will cite are listed (§3 names only anchors here).
+- [ ] **Issues/Risks** — the problems/risks found are recorded for §1 (or an honest none).
+- [ ] **Related intent** — the PROJECT/GLOSSARY/origin intent is linked (or an honest none).
+- [ ] **Ground SHA** — the commit grounded against is recorded (line refs read "as of" it).
 </exit_gate>
 
-**Grounding is complete when** all four fields are filled from real assets: a STRONG grounding cites
-actual files/symbols/docs/conventions you opened; a WEAK one leaves a `<…>` placeholder or names what you
-assume. All four are non-optional — skipping **Context** (the working folder beyond code) is the usual
-silent gap. §3 may cite only anchors that appear here.
+**Grounding is complete when** every field is filled from real assets (a `<…>` placeholder = weak;
+all non-optional). Skipping **Context** (beyond code) is the usual silent gap. §3 cites only anchors here.
 
-> **Advisor · Confidence** — a broad sweep is the canonical spawn case (advisor.md); self-score your grounding before you specify against it (confidence.md).
+> **Advisor · Confidence** — a broad sweep is the canonical spawn (advisor.md); self-score before you specify (confidence.md).
 
 ## Next
 

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

@@ -1,18 +1,18 @@
 # 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 one decision: the **baseline approval**. Brownfield is silent; greenfield keeps a short interview. Either way, the human's only gate is `add.py lock`.
+Goal: point ADD at a repo and **you** draft the whole foundation — domain, first-milestone scope, first task's contract — then hand the human one decision: the **baseline approval**. Brownfield silent; greenfield keeps a short interview; either way the only gate is `add.py lock`.
 
 ## 1 · Zero-touch entry — you run init yourself
 
-When there is no `.add/state.json`, do **not** tell the human to initialise — run it yourself. Infer the
-project name and stage from the repo, and **arm the baseline-approval gate** with `--await-lock`:
+No `.add/state.json`? Don't tell the human to initialise — run it yourself. Infer name + stage
+from the repo and **arm the baseline-approval gate** with `--await-lock`:
 
 ```bash
 python3 .add/tooling/add.py init --name "<inferred from repo/dir>" --stage <prototype|poc|mvp|production> --await-lock
 ```
 
-- `--await-lock` 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`.
+- `--await-lock` seeds an *unlocked* setup — the engine refuses build or `gate` until you `lock`. A plain `init` is grandfathered-locked (`already_locked` on a later `lock`).
+- name + stage are **your judgment**: throwaway → `prototype`, risky slice → `poc`, narrow → `mvp`, full rigor → `production`.
 
 `init` prints one of two things — **that is your branch**:
 - `brownfield:` → existing code (go to **2a**);
@@ -20,12 +20,12 @@ python3 .add/tooling/add.py init --name "<inferred from repo/dir>" --stage <prot
 
 ## 2a · Brownfield — map it silently
 
-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.
+The code answers what a greenfield interview would ask — **read it instead of asking**. Open `adopt.md`: fill each living-doc from code, never clobber, tag every decision `evidence-grounded` or `guessed`. Ask the human **nothing** here.
 
 ## 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 — 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:
+An empty repo has no code, so run the short interview — the **co-specify at foundation level** move
+(diverge → converge → validate, as §1 does in `phases/1-specify.md`), lifted to the foundation. Ask one load-bearing question per lens, draft, rank lowest-confidence-first, show the top flag:
 
 | Lens | The one question that unblocks the section |
 |------|--------------------------------------------|
@@ -45,47 +45,48 @@ Ask only the live ones. Rank: `⚠ <assumption> — lowest confidence because <w
 | **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** into `PROJECT.md` **Key Decisions** as it lands.
+Capture each surfaced decision as an **ADR** in `PROJECT.md` **Key Decisions** as it lands.
 
-**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.
+**Under `autonomy: auto`, auto-complete all four drives in one pass** — lowest-confidence-first. This deepens **drafting**, never the gate: it NEVER skips the human baseline approval — `lock` stays the one decision.
 
 ## 3 · Draft to the lock (both paths)
 
-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`).
+1. **Fill the living documentation**: `.add/PROJECT.md` (Domain · Spec · 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.md`). Brownfield: from code. Greenfield: from interview, gaps flagged `guessed`.
+   - **Seed personas** (`.add/personas/`): `init` scaffolds `_template.md` (the schema). Author one per role from PROJECT.md + the vendored teacher library `.add/personas-teacher/` (read off-build; engine never fetches), recording the teacher in `source:` and carrying its top `## Playbook` (both optional). Covered by the **baseline approval**; `add.py check` validates; never clobber.
+2. **Propose, then size it.** Float a **kickoff suggestion** for the first milestone: a **goal** (one sentence), a **flow** (task order), **scenarios** (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 the full bundle **§1–§4** — incl. the **§4 red suite** (`phases/4-tests.md`); the lock approves it whole. **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 (§1–§4, tests RED) → lock → build** — the red suite must FAIL **before build** (never start Build until §1–§4 exist and tests are red).
+   Draft the full bundle **§1–§4** incl. the **§4 red suite** (`phases/4-tests.md`); the lock approves it whole. **Leave §3 `Status: DRAFT`** — the lock is its approval. You MAY `advance` pre-lock, but the engine **refuses build** until you `lock` (`setup_unlocked`). Sequence: **bundle (§1–§4, tests RED) → lock → build** — the red suite must FAIL before 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 the **run mode** — **autonomy** (`add.py autonomy`, run.md) and **streams** (`add.py waves` + `streams.md`):
+Before the lock, surface the **run mode** — autonomy + streams (`run.md` · `streams.md`):
 
 | 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 |
+| **sequential · manual/conservative** | contract freeze **and** every Verify | one task; safest |
+| **parallel · auto** *(default)* | contract freeze **only** — Verify auto-PASSes on evidence | `add.py waves` overlaps independent builds behind frozen contracts |
 
-**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**.
+**Propose `parallel + auto`; confirm-to-keep** (or downgrade: `add.py autonomy set conservative --project` + `add.py streams set sequential --project`). Record in **`PROJECT.md` Key Decisions**.
 
-The irreducible floor: **one human approval per contract** fires no matter the mode.
+Floor: **one human approval per contract**.
 
 ## 4 · The one human gate — the baseline approval
 
-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:
+Open the report with the ARC per `report-template.md`, render SHAPE then APPROVE as a guided choice, then present `SETUP-REVIEW.md` lowest-confidence-first. They confirm **once** — an explicit yes to the baseline approval; 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 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.
+Typing it themselves stays the **escape hatch** — the decision is the human's; you execute. `lock` writes the lock layers atomically and opens the build.
 
 ## 5 · After the lock
 
-- The lock **is** the first task's contract approval — do **not** ask for a separate contract-freeze sign-off.
+- The lock **is** the first task's contract approval — no separate contract-freeze sign-off.
 - Stamp the first task's §3 `Status: FROZEN @ v1`, then read `phases/5-build.md`.
 
 ## Exit gate

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

@@ -3,12 +3,12 @@
 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 validate. If you cannot write the spec, you do not yet understand the feature — stop and ask.
+Specify is **co-specification**: brainstorm the shape WITH the user, draft, then validate. If you cannot write the spec, you don't yet understand the feature — stop and ask.
 
 ## Co-specify in three moves
 
-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).
+1. **Diverge** — surface the decision space: the 2–3 genuine framings + the open questions you'd otherwise guess. Invite the user to add, kill, redirect. (Conversational — no new file; at prototype/poc, one sentence.)
+2. **Converge** — draft §1 answering the §0 GROUND **Issues/Risks**, 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).** 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`.
@@ -25,13 +25,13 @@ Specify is **co-specification**: brainstorm the shape WITH the user, draft it, t
 
 ## The lowest-confidence flag is bundle-wide
 
-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."*
+The single approval is at the contract freeze, over the whole bundle — so your §1 ranking feeds the bundle-level flag the user reads there (`run.md`): *"of all I'm asking you to freeze, these 1–2 are most likely wrong."*
 
 ## AI prompt
 
 <prompt>
 Role: a domain analyst who brainstorms, then asks rather than assumes.
-Read first: CONVENTIONS · GLOSSARY · the user's raw input.
+Read first: CONVENTIONS · GLOSSARY · §0 GROUND Issues/Risks · the user's raw input.
 Objective: fill §1 SPECIFY with zero ambiguity left for the AI to resolve by guessing.
 Steps:
   1. Surface 2–3 framings + the open questions; let the user react before you draft.
@@ -50,10 +50,12 @@ Never: resolve an ambiguity by guessing.
       "none material" that still names the single biggest risk (never a blank "none").
 </exit_gate>
 
+> **Persona** — load the fit `.add/personas/<slug>.md`; its `## Critical Rules` shape §1 (advisory; never lowers a 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`.
 Book: `docs/03-step-1-specify.md`. (UI feature? also sketch flows + every screen
-state: loading/empty/error/success.)
+state: loading/empty/error/success; name it in the parent MILESTONE.md's Scope-hint
+vocabulary, not generic prose.)

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

@@ -14,7 +14,7 @@ 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.** 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 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 SHAPE then the freeze APPROVE 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
 

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

@@ -19,16 +19,14 @@ before code exists is testing nothing and will wave bad code through later.
 
 ## Declaring where tests live
 
-§4's `Tests live in:` line is machine-read: when a task has no local `tests/`,
-`add.py report` counts test functions at the declared path(s) instead. The FIRST
-line matching `Tests live in:` is read; paths are its backticked tokens.
-Resolution: `./…` → this task's dir · a token containing `/` → the project root
-(the parent of `.add/`) · a bare name → a sibling of the previous token's
-directory (else the task dir). A directory token counts the `*.py` files directly
-inside it (non-recursive); a `.py` file token counts itself; anything else is
-ignored. Resolved files are deduped; 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.
+§4's `Tests live in:` line is machine-read: with no local `tests/`, `add.py report`
+counts test functions at the declared backticked paths instead (FIRST `Tests live in:`
+line only). Resolution: `./…` → this task's dir · a token with `/` → the project root
+(parent of `.add/`) · a bare name → a sibling of the previous token's dir (else the
+task dir). A directory token counts the `*.py` files directly inside it (non-recursive); a `.py`
+file counts itself; else ignored. Resolved files dedupe; declared counts marked `†`. Paths
+are confined: anything resolving outside the project root counts 0 — `..` traversal, absolute
+paths, and symlink escapes are never read.
 
 ## AI prompt
 
@@ -52,6 +50,7 @@ Never: implement the feature, or assert on internals.
 - [ ] Coverage target recorded.
 </exit_gate>
 
+> **Persona** — let the fit persona's `## Success Metrics` shape the red suite (advisory).
 > **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

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

@@ -1,27 +1,31 @@
 # Phase 5 — Build (AI writes the code)
 
 Goal: implement the feature so EVERY failing test passes — without changing any
-test or the contract. This is the only phase the AI leads. It works because §1–§4
-removed all ambiguity. Write code into `.add/tasks/<slug>/src/`.
+test or the contract. This is the only phase the AI leads; §1–§4 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.
+Pick ONE task-sized slice, restate its tests, implement, 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 §3 approval — never invented mid-build:
+§5 opens with two declarations, drafted with the 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). 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.
+- **Scope (may touch)** — the allowlist of files the build may write (backticked tokens). A file outside it is a **STOP → change request** back to Specify, never improvisation.
+- **Strategy (ordered batches)** — the planned build order; guidance, not enforced.
 
-Enforced: a completing verify gate refuses an out-of-scope build (`scope_violation` → self-heal); `add.py check` surfaces it.
+Enforced: a completing verify gate refuses an out-of-scope build (`scope_violation` → self-heal).
+
+## Persona overlay (optional)
+
+You may load the active `.add/personas/<slug>.md` as a domain **overlay** atop `SOUL.md` (SOUL = voice/trust; persona = domain **stance**) — name it in §5. SOUL.md is **human-owned**: the overlay never rewrites it (`soul.md`). Advisory — it never lowers a gate; security still **HARD-STOPs**.
 
 ## The cardinal rule
 
 **Never weaken or delete a test to make it pass, and never edit the frozen
-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).
+contract.** A genuine need to change either is a change request back to Specify. Honor the §5 safety rule (e.g. atomic balance update).
 
 ## AI prompt
 
@@ -30,9 +34,9 @@ Role: implement the feature so EVERY failing test passes — the build phase.
 Read first: §1 · §3 · §4 · CONVENTIONS.
 Objective: every §4 test green, one small batch at a time.
 Steps:
-  1. Make EVERY failing test pass, one small batch at a time, honoring the §5 safety rule.
+  1. Make EVERY failing test pass, honoring the §5 safety rule.
   2. Report which tests pass and exactly what changed.
-Never: change a test or the contract; use a package off the allow-list; or push past something unclear instead of asking.
+Never: change a test or the contract; use a package off the allow-list; or push past unclear instead of asking.
 </prompt>
 
 ## Exit gate
@@ -46,7 +50,7 @@ Never: change a test or the contract; use a package off the allow-list; or push
 - [ ] 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).
+> **Advisor · Confidence** — delegate a well-scoped batch (advisor.md); self-score before presenting green, refine while cheap (confidence.md).
 
 ## Next
 
@@ -55,4 +59,4 @@ Book: `docs/07-step-5-build.md`.
 
 > Under `autonomy: auto` Build and Verify run together as one evidence-auto-gated run. See `run.md`.
 >
-> **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.
+> **Honest redo.** A confirmed cheat returns the task HERE — revert the tampered file or de-overfit src, then advance again (the bounded self-heal loop, `run.md`; capped, then HARD-STOPs to the human). Never weaken a test or edit the frozen contract to pass.

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

@@ -11,7 +11,7 @@ sufficient. Fill **§6** in TASK.md including the GATE RECORD.
 
 ## Before you build — declare the build expectations
 
-Fill the §6 **Build expectations** block BEFORE Build: OBSERVABLE outcomes derived from §2 + §3. At this gate, confirm each against real evidence (the `confirmed by` column) — one with no evidence is not yet verified.
+Fill the §6 **Build expectations** block BEFORE Build: OBSERVABLE outcomes derived from §2 + §3. At this gate, confirm each against real evidence (the `confirmed by` column) — one with no evidence isn't yet verified.
 
 ## Part one — confirm the evidence
 
@@ -25,14 +25,16 @@ If any is false, stop and return to Build.
 ## Part two — check what tests miss
 
 - **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`). **But that check sees only what you wrote down:** it fires on a *marked* note that slipped through as an auto-gate PASS — a finding you never marked is **invisible** to the engine, escalated to no one. Honest disclosure, not false cover: under `auto`, a human **spot-audit** (reading the diff) is the only backstop for a *missed* security finding.
+- **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`). **But that check sees only what you wrote down:** it fires on a *marked* note auto-gated to PASS — a finding you never marked is **invisible**, escalated to no one. Under `auto`, a human **spot-audit** (reading the diff) is the only backstop for a *missed* security finding.
 - **Architecture** — respects layering/dependency rules in CONVENTIONS.md?
 
+Run the three lenses in order — a Security `HARD-STOP` ends the checklist (leave the rest blank). Record in §6 `### Advisor 3-lens verdict` (Verdict · Residue · Binding): `sensitivity: mechanical` → Binding `yes` (engine reads it for `advisor-gate-relax`), every other class → Binding `advisory`. `add.py audit` flags an unfilled block `advisor_verdict_unrecorded`, a companion to `refute_unrecorded`.
+
 ## Part three — the 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. The resolver judges which path; the engine never classifies.
 
-Record it in the §6 **Deep checks** block — an unfilled one is a **shallow verify**, not a PASS.
+Record in the §6 **Deep checks** block — an unfilled one is a **shallow verify**, not a PASS.
 
 ## Part four — was the green earned?
 
@@ -40,7 +42,7 @@ A green suite proves tests pass — not that the build EARNED them. Three judgme
 
 ## Record exactly one outcome (no silent pass)
 
-Present this gate via `report-template.md`'s ARC, render DECISION as a guided choice, and reconcile FLAGS with `add.py report --decide`'s open-item count first.
+Present this gate via `report-template.md`'s ARC, render APPROVE as a guided choice, and reconcile FLAGS with `add.py report --decide`'s open-item count.
 
 | Outcome | When |
 |---------|------|
@@ -55,6 +57,7 @@ Present this gate via `report-template.md`'s ARC, render DECISION as a guided ch
   (under `autonomy: auto`, no residue) the run auto-resolved as accountable owner.
 </exit_gate>
 
+> **Persona** — run the refute-read under the fit persona / Code-Reviewer lens (advisory; security still HARD-STOPs).
 > **Advisor · Confidence** — the earned-green refute-read is the canonical adversarial spawn (advisor.md); score it before recording the gate (confidence.md).
 
 ```bash

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

@@ -38,9 +38,10 @@ Never: auto-roll-back — recommend; a human owns the production decision.
 - [ ] A reviewed spec delta captured (becomes the next `new-task`).
 </exit_gate>
 
+> **Persona** — tag a lesson `· persona:<slug> ·` so `add.py fold` grows the persona.
 > **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.
+Loop. The artifacts you built are living docs the next cycle refines.
 Book: `docs/09-the-loop.md`.

package/skill/add/report-template.md

@@ -2,11 +2,26 @@
 
 The engine renders artifacts (`report`, `report --decide`, `status`); this file governs the CHAT MESSAGE you wrap around them.
 
-Use it every time you report at or near a decision point.
+Use it every time you report at or near a human gate.
 
-## The decision arc — rendered first, above the report blocks
+## The decision banner — rendered first, above everything
 
-Every report at a human gate opens with the **ARC** — three labelled lines placing the decision in the work's whole arc. Render it first, then a separator, then the report blocks:
+Every report at a human gate opens with a banner line, so a human scanning a long chat can spot "this needs my input" without reading prose:
+
+```
+════════════════════════════════════════════════════════════════
+ PLAN · <task/milestone title, bold> · <gate name> → APPROVE?
+ 📄 <task's TASK.md path>  ·  <milestone's MILESTONE.md path>
+════════════════════════════════════════════════════════════════
+```
+
+- The title is the real H1 from TASK.md/MILESTONE.md, **bolded** — not the bare slug.
+- The path line names the actual file(s) so the human can open them directly; omit the milestone half for a milestone-free/fast task.
+- Any `§`-numbered section named anywhere in the report (SHAPE, FLAGS, APPROVE, NEXT) is **bolded** — e.g. `**§3 CONTRACT**` — so a scanning eye finds exactly which part of the file is in play.
+
+## The decision arc — rendered next
+
+Every report at a human gate carries the **ARC** — three labelled lines placing the decision in the work's whole arc. Render it right after the banner, then a separator, then the report blocks:
 
 ```
 ARC  goal: <the milestone / project goal this decision serves>
@@ -27,34 +42,61 @@ Its facts are engine-sourced (goal = `m-goal` · done = exit-criteria + tasks do
 - **verify** — `goal:` ship the decision arc · `done:` report-arc tests 6/6 green · `plan:` PASS → wire the arc into every gate → goal.
 - **contract-freeze** — `goal:` … · `done:` bundle drafted, lowest-confidence flag surfaced · `plan:` freeze §3 → build → goal.
 
+## PLAN / SHAPE — when there's more than one step, or a shape to freeze
+
+Render one of these (never both) right after the ARC, whenever the message needs to show more than a single fact — a multi-task breakdown, a roadmap, mid-milestone orientation, or (at a contract freeze) the shape itself:
+
+```
+PLAN   <milestone or theme — one line>
+  ✅ done (N)          <collapsed — never enumerated by name>
+  🔄 <active-slug>      <one line: what it's doing right now>
+  ⬜ <next-slug>        <one line — "depends-on: <slug>" if it blocks>
+  ⬜ <next-slug>
+  ⚠ <flagged-slug>     <one line — why it's flagged>
+  … +N more queued     <only if the live list exceeds the cap>
+```
+
+```
+SHAPE   <task title, bold> — v<N>  (DRAFT — not yet frozen)
+  <endpoint/type/field>        <new | changed | unchanged>
+  <error case / reject token>  <what triggers it>
+```
+
+- **Collapse done to a count.** Never enumerate finished tasks by name — the human already trusts what's shipped; re-listing it is noise.
+- **Cap live items at ~5–7**, in dependency order; footer `+N more queued` rather than listing everything.
+- **One line per item** — slug + what it does or blocks on; never restate the whole TASK.md.
+- **Glyphs are fixed** — ✅ done · 🔄 active/in-progress · ⬜ pending · ⚠ blocked or flagged. Do not invent new glyphs.
+- **Sourced from the engine, summarized by you** — pull from `add.py status`'s `tasks:`/`streams:` output; never paste it verbatim into chat.
+- **SHAPE is freeze-only** — the concrete thing being locked, so the human reviews the actual shape, not just commentary about it.
+
 ## The report blocks, in order
 
 Render every block (write "none" rather than dropping one); add MORE when needed.
 
 ```
 SUMMARY   one line: intent + target + where we are + what we done
-DECISION  what you need from the human (or "none — FYI") — exactly one
 FLAGS     lowest-confidence first: why + cost-if-wrong
 DECIDED   highest-confidence first: the autonomous calls you made + why each was safe
 EVIDENCE  small table: tests · gates · parity · check — engine-sourced
+APPROVE   what you need from the human (or "none — FYI") — exactly one — sits last, right before the ask
 NEXT      the recommended next actions, ranked (top ▶ highlighted, bolded) + what each unlocks
 ```
 
-1. **SUMMARY** — one line: intent + target + position.
-2. **DECISION** — as a **guided decision**: one `▶ … (recommended)` + 1–3 described alternatives. Exactly one per report, or "none — FYI". Ask after everything below (show-before-ask).
-3. **FLAGS** — lowest-confidence first, each with *why* and *cost if wrong*. Where TASK.md markers exist (`⚠` / `- [~]` / `- [ ]`), quote verbatim and keep document order.
-4. **DECIDED** — high-confidence autonomous calls, highest-confidence first, each with *why* it was safe. "none" when none. NEVER list a security / residue / lowered-autonomy call here.
-5. **EVIDENCE** — engine-sourced facts from `add.py` output, never re-typed.
+1. **SUMMARY** — one line: intent + target + position. **Never optional** — even when PLAN/SHAPE already carries most of the context, SUMMARY still renders as its own line; it is never merged into or silently replaced by another block.
+2. **FLAGS** — lowest-confidence first, each with *why* and *cost if wrong*. Where TASK.md markers exist (`⚠` / `- [~]` / `- [ ]`), quote verbatim and keep document order.
+3. **DECIDED** — high-confidence autonomous calls, highest-confidence first, each with *why* it was safe. "none" when none. NEVER list a security / residue / lowered-autonomy call here.
+4. **EVIDENCE** — engine-sourced facts from `add.py` output, never re-typed.
+5. **APPROVE** — as a **guided decision**: one `▶ … (recommended)` + 1–3 described alternatives. Exactly one per report, or "none — FYI". Rendered last among the core blocks — the actual interactive ask fires only after everything above it (show-before-ask).
 6. **NEXT** — ranked next actions, top one marked `▶` with what it unlocks. Mirror the rollup's `DECIDE NEXT` for the top action; overrule it only with a stated reason. **Informational, not a second gate**.
 
 ### Beyond the core blocks
 
-When a report needs more — a `RISK` ledger, a `DIFF`, a `SCOPE` map — add an extra block (SCREAMING-CASE label · one-line intent · engine-sourced where possible) AFTER EVIDENCE and BEFORE NEXT. Add only when it carries what the core blocks don't; never pad; never drop a core block.
+When a report needs more — a `RISK` ledger, a `DIFF`, a `SCOPE` map — add an extra block (SCREAMING-CASE label · one-line intent · engine-sourced where possible) AFTER EVIDENCE and BEFORE APPROVE. Add only when it carries what the core blocks don't; never pad; never drop a core block.
 
-### The DECISION block as a guided choice
+### The APPROVE block as a guided choice
 
 ```
-DECISION  <the question>
+APPROVE  <the question>
 
   ▶ <recommended option>  (recommended)
       <one-line description — what it means · what it unlocks or costs>
@@ -67,19 +109,20 @@ DECISION  <the question>
 - **Every option is described** — pick and each alternative carry a one-line description.
 - **Human gates only** — render at `[human gate]` points; not at `[you drive]` steps.
 
-**The ask itself** — when block 2 becomes an `AskUserQuestion` picker: recommended option goes first with `(Recommended)` suffix. On tools without `AskUserQuestion`, render as a numbered/`▶` menu. The question is a summary, never the artifact — intent + what "yes" means + the flag count.
+**The ask itself** — when the APPROVE block becomes an `AskUserQuestion` picker: recommended option goes first with `(Recommended)` suffix. On tools without `AskUserQuestion`, render as a numbered/`▶` menu. The question is a summary, never the artifact — intent + what "yes" means + the flag count.
 
 ## Hard rules
 
 <constraints>
 - **Summary-first.** Never bury the decision under a task list or a diff.
-- **Show before ask.** Render the artifact (digest · diff · report) before any approval question.
-- **Guided decision.** At a `[human gate]`, block 2 is a guided choice — one `▶ … (recommended)` + 1–3 described alternatives; never a bare next step.
+- **Show before ask.** Render the artifact (digest · diff · report) before any approval question. PLAN/SHAPE counts as the artifact here too.
+- **Guided decision.** At a `[human gate]`, APPROVE is a guided choice — one `▶ … (recommended)` + 1–3 described alternatives; never a bare next step.
 - **Reconcile the count.** FLAGS must reconcile with `add.py report --decide`'s open-item count before the ask. Engine wins if prose disagrees — fix the data, not the sentence.
 - **Never pre-stamp a human decision point.** Freeze / gate / lock fields stay DRAFT or blank until the answer returns: show → ask → stamp → advance.
+- **Never dump raw engine output as the plan.** Summarize `add.py status`/`report` through PLAN/SHAPE (or prose) — the engine's full verbosity is for `add.py` itself, not the chat message wrapped around it.
 - **One report per decision point.** After an approval, point at the frozen artifact — do not re-render the bundle.
 - **Honest scope.** "Done" means the request, not the last task: report "task 2/3", never "done" while approved scope remains.
-- **The question is a summary, never the artifact.** A compact SUMMARY · DECISION · FLAGS block sits in chat immediately before the ask; the question text itself is two lines at most — intent + what "yes" means + flag count — pointing at the report above.
-- **NEXT is not a second gate.** The single decision stays in DECISION; NEXT is ranked recommendations only.
-- **DECIDED never holds a gate-class call.** Security / residue / lowered-autonomy calls escalate in DECISION.
+- **The question is a summary, never the artifact.** A compact SUMMARY · FLAGS block sits in chat immediately before the ask; the question text itself is two lines at most — intent + what "yes" means + flag count — pointing at the report above.
+- **NEXT is not a second gate.** The single decision stays in APPROVE; NEXT is ranked recommendations only.
+- **DECIDED never holds a gate-class call.** Security / residue / lowered-autonomy calls escalate in APPROVE.
 </constraints>

package/skill/add/run.md

@@ -69,6 +69,8 @@ recorded pass is an explicit pass, not a skip).
   contract edited; loops dry; completeness-critic clean; and the deep check below.
 - **The deep check (every gate, 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. An unfilled deep check is a **shallow verify**, not an auto-PASS.
 - **The recorded refute-read (under `auto`).** The earned-green refute-read (`6-verify.md`) is not just run — its **verdict is recorded** in §6 (`EARNED | NOT-EARNED`); `add.py audit` surfaces an unrecorded one as `refute_unrecorded` — one of three shape lints it lists (with `shallow_deep_check` + `risk_unset`) — and a human spot-audit is the backstop. NOT-EARNED routes to `add.py heal`, never an auto-PASS.
+- **The recorded Advisor 3-lens verdict (under `auto`).** The Advisor 3-lens sweep (security → concurrency → architecture, `6-verify.md`) is recorded in §6 `### Advisor 3-lens verdict`; `add.py audit` surfaces an unfilled block as `advisor_verdict_unrecorded` — a shape lint alongside `refute_unrecorded`.
+- **The `advisor-gate-relax` pathway.** A `risk: high` + `sensitivity: mechanical` task whose §6 Advisor 3-lens verdict records Verdict `PASS` and Residue `none` may auto-complete via `add.py gate PASS` **without** a lowered autonomy level. Security and every non-mechanical sensitivity class are never relaxed by this pathway — the high-risk guard still applies.
 - **Always escalates to a human (never auto-passed):** any **security** finding (HARD-STOP, always);
   a **concurrency**/timing risk the tests cannot exercise; an **architecture**/layering violation;
   any failing test.
@@ -122,9 +124,8 @@ autonomy: manual | conservative | auto
 - **conservative** — the deliberate *lowering*: the run converges but STOPS at the verify gate.
 - **manual** — the strict floor: the human owns the verify gate; the engine never auto-resolves.
 
-> **v7 reversal (recorded).** Earlier the default was `conservative`; v7 flips it — `auto` is the
-> default, `conservative` is the deliberate lowering. The level is still **per-scope** and is
-> lowered wherever risk demands.
+> **v7 reversal (recorded).** Earlier the default was `conservative`; v7 flips it to `auto` as
+> the default. The level is still **per-scope** and is lowered wherever risk demands.
 
 **The high-risk guard.** On a **high-risk or method-defining scope** `auto` must be lowered to
 `conservative` or `manual`; leaving it at `auto` is the reject code **`unguarded_high_risk_auto`**.