@pilotspace/add 1.16.1 → 2.0.0

package/skill/add/{report-template.md → gate-udd.md}

@@ -1,8 +1,8 @@
-# Chat reports — the decision-point template (for the AI, not for add.py)
+# Gate reports — the text-mode UDD gate surface (for the AI, not add.py)
 
-The engine renders artifacts (`report`, `report --decide`, `status`); this file governs the CHAT MESSAGE you wrap around them.
+The engine renders artifacts (`report`, `report --decide`, `status`); this file governs the CHAT MESSAGE you wrap around them. Use it at every human gate; its UDD-family design home is `design.md`.
 
-Use it every time you report at or near a human gate.
+**The fitting persona owns the gate report** — these are PRINCIPLES, not a fixed template: CONVEY the content below, but the persona owns structure, order, and cadence per project. The layout shown is a sensible DEFAULT; the four floors (below) it may never drop.
 
 ## The decision banner — rendered first, above everything
 
@@ -11,11 +11,11 @@ Every report at a human gate opens with a banner line, so a human scanning a lon
 ```
 ════════════════════════════════════════════════════════════════
  PLAN · <task/milestone title, bold> · <gate name> → APPROVE?
- 📄 <task's TASK.md path>  ·  <milestone's MILESTONE.md path>
+ 📄 <task's PLAN.md path>  ·  <milestone's MILESTONE.md path>
 ════════════════════════════════════════════════════════════════
 ```
 
-- The title is the real H1 from TASK.md/MILESTONE.md, **bolded** — not the bare slug.
+- The title is the real H1 from PLAN.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.
 
@@ -29,7 +29,7 @@ ARC  goal: <the milestone / project goal this decision serves>
      plan: <this gate → the next step → the goal>
 ```
 
-- **goal** — read from `m-goal` in `add.py status`; never re-typed from memory.
+- **goal** — read from `m-goal` in `add.py status --all`; never from memory.
 - **done** — proven progress only: exit-criteria met/total, tasks done, what this gate proves. An honest fact, never a hope.
 - **plan** — this gate → the next step → the goal, mirroring the rollup's `DECIDE NEXT` line.
 
@@ -37,11 +37,6 @@ The arc is required at every human gate: **baseline-lock · contract-freeze · v
 
 Its facts are engine-sourced (goal = `m-goal` · done = exit-criteria + tasks done · plan = `DECIDE NEXT`); if your arc and `add.py` disagree, the engine wins.
 
-### Per-gate examples
-
-- **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:
@@ -62,16 +57,15 @@ SHAPE   <task title, bold> — v<N>  (DRAFT — not yet frozen)
   <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.
+- **Collapse done to a count** (never enumerate finished); **cap live items ~5–7**, dependency-ordered, footer `+N more queued`; one line each — never restate the PLAN.md.
+- **Glyphs fixed** — ✅ done · 🔄 active · ⬜ pending · ⚠ blocked/flagged; never invent new ones.
+- **Sourced from `add.py status`, summarized by you** — never pasted raw into chat.
+- **SHAPE is freeze-only** — the concrete shape being locked, so the human reviews it, not commentary.
+- **BUILD PLAN is the HOW** — at a freeze `report --decide` also renders the §3 Build-strategy (Scope · batches · Persona · Spawn) as a `BUILD PLAN (§3 …)` block, so the human approves how the build runs, not only the SHAPE; placeholders skipped.
 
-## The report blocks, in order
+## The report blocks — what to convey (you own the order)
 
-Render every block (write "none" rather than dropping one); add MORE when needed.
+A gate report CONVEYS these; the persona owns the order and may merge, reorder, or trim to fit the project — conveying each (write "none" rather than silently dropping one), never dropping a floor. A sensible default order follows, not a mandate; add MORE when needed.
 
 ```
 SUMMARY   one line: intent + target + where we are + what we done
@@ -82,16 +76,11 @@ APPROVE   what you need from the human (or "none — FYI") — exactly one — s
 NEXT      the recommended next actions, ranked (top ▶ highlighted, bolded) + what each unlocks
 ```
 
-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**.
+- **SUMMARY** never optional — one line even when PLAN/SHAPE carries the context. **FLAGS** lowest-confidence-first (why + cost-if-wrong; quote PLAN.md `⚠` / `- [~]` / `- [ ]` verbatim). **DECIDED** highest-confidence-first ("none" when none; never a security / residue / lowered-autonomy call). **EVIDENCE** engine-sourced, never re-typed. **APPROVE** the guided ask, last, after show-before-ask. **NEXT** ranked recommendations, not a second gate. **The ask itself** is a summary, never the artifact.
 
 ### 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 APPROVE. 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) AFTER EVIDENCE and BEFORE APPROVE. Add only when it carries what the core blocks don't; never pad; never drop a core block.
 
 ### The APPROVE block as a guided choice
 
@@ -104,26 +93,28 @@ APPROVE  <the question>
       <one-line description>
 ```
 
-- **Exactly one** option carries `▶ … (recommended)`. `confidence.md` self-score informs which; the human overrides freely.
-- **1–3 real alternatives** only — no strawmen; if there is genuinely one path, show one — never invent filler to reach three.
-- **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.
+- **Exactly one** `▶ … (recommended)` (per the confidence self-score, `phases/direction.md`; human overrides) + **1–3 real alternatives**, each described — no strawmen. **Human gates only** (`[human gate]`, not `[you drive]`). As an `AskUserQuestion` picker: recommended first with `(Recommended)`; else a numbered/`▶` menu. The question is a summary, never the artifact — intent + what "yes" means + flag count.
+
+## The four floors — the persona owns the form, never these
 
-**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.
+Whatever shape the persona renders per project, it MUST hold all four:
+- **show-before-ask** · **one-approval-at-the-freeze** · **never-pre-stamp** a human decision point
+- **security = HARD-STOP** — the one **un-persona-negotiable** floor: a security finding is never persona-softened (the human alone may strike this carve-out). The "## Hard rules" below detail how they play out.
 
 ## 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. PLAN/SHAPE counts as the artifact here too.
+- **Show before ask.** Render the artifact (digest · diff · report) before any approval question; PLAN/SHAPE counts 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.
+- **Reconcile the count.** FLAGS must reconcile with `add.py report --decide`'s open-item count before the ask. Engine wins on disagreement — 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.
+- **Never dump raw engine output as the plan.** Summarize `add.py status`/`report` through PLAN/SHAPE (or prose) — the engine's verbosity is for `add.py`, not the chat wrapped around it.
 - **One report per decision point.** After an approval, point at the frozen artifact — do not re-render the bundle.
+- **Batch, don't serialize.** N same-gate decisions ready together (intake items · ready-to-freeze contracts) render as ONE report: PLAN lists each with its own lowest-confidence flag; APPROVE covers the batch in one ask, any item held back by name.
 - **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 · 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.
+- **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 + the flag count — pointing at the report above.
+- **NEXT is not a second gate.** The decision stays in APPROVE; NEXT is ranked recommendations only.
 - **DECIDED never holds a gate-class call.** Security / residue / lowered-autonomy calls escalate in APPROVE.
-- **Recorded, not just performed.** Rendering this template at a gate is recorded, not assumed — TASK.md's `Reported: yes` (§3/§6) is the mechanical trace; `add.py audit` surfaces an unrecorded one (`contract_report_unrecorded` / `verify_report_unrecorded`), a spot-audit the backstop.
+- **Recorded, not just performed.** A gate render is recorded, not assumed — PLAN.md `Reported: yes` (§3/§6) is the trace; a human spot-audit is the backstop for a missed render.
 </constraints>

package/skill/add/intake.md

@@ -4,14 +4,52 @@ Before a task exists, ADD turns a raw request into correctly-sized, versioned sc
 **intake level** (the per-task flow is phases 0–7; intake is the step *before* a task). You
 (the AI) **propose**; the human **confirms**. Never create scope without a confirmed proposal.
 
+## Analyze the request before you size it
+
+A raw request is rarely a task yet — it is intent wrapped in prose. ADD's first job is not to
+route it but to *read it into a task shape*. Do this BEFORE any bucket or interview:
+
+1. **Restate the intent** in one line — the outcome the human wants, in their world, not the
+   mechanism. If you cannot state it, it is underspecified → `ask_human` (never guess it).
+2. **Extract the latent requirements** — the acceptance signals hiding in the ask ("fast",
+   "secure", "works like X") are the measurable Targets in disguise; name each one explicitly.
+3. **Name the unstated** — the assumptions, defaults, and edge behavior the prose skips. These
+   become the interview agenda below; surface them, never silently fill them.
+4. **Surface the hidden work** — the migrations, new contract surface, and risks a naive read
+   misses. This is what separates a real task from a wish, and what escalates sensitivity.
+
+This analysis IS the task's raw material: the restated intent seeds §1 grounding, the latent
+requirements seed the §3 Target, the unstated becomes what the interview settles. Sizing (below)
+only decides *where* the task lives — the analysis decides *what it is*. Skipping it is how a
+vague prompt becomes a mis-sized, under-specified task.
+
 ## Interview before you size
 
-Run `add.py search <keyword> [<keyword> ...]` first — it surfaces overlapping/prior work in one
-command instead of a full manual re-read. When the request arrives as a question, or its intent is
-not sharp enough to place in one bucket: explore it WITH the user before classifying. Reflect the intent you heard, name what seems in and
-out of scope, and offer 2–3 sized options with your own recommendation. Only then emit
-`{ bucket, rationale, command }`. `ask_human` stays the floor: when interviewing cannot sharpen the
-request, reject — never guess a bucket.
+Run `add.py search <keyword> ...` first — it surfaces overlapping/prior work in one command. When
+the request is a question or won't place in one bucket, explore it WITH the user first: reflect
+the intent, name in/out of scope, offer 2–3 sized options with a recommendation. Only then emit
+`{ bucket, rationale, command }`. `ask_human` stays the floor: if interviewing can't sharpen it,
+reject — never guess a bucket.
+
+## The inline lane — below the bucket floor
+
+Buckets create versioned scope; some changes are too small to deserve any. After the
+interview sharpens the request, judge the lane FIRST — you (the AI) route it, silently:
+
+**Inline fits when ALL hold**: one file or a few adjacent ones · behavior the current specs
+already cover (a typo, a wording fix, a config value, a mechanical rename) · no new contract
+surface anyone else consumes · sensitivity mechanical. Then: **no task, no milestone** — make
+the edit directly, and leave the receipt:
+
+1. the **git diff** is the change record (commit it as usual);
+2. `add.py delta-append <dd> "<lesson>"` files what was learned into the living 5-DD spec —
+   the spec diff IS the approval artifact; a lane run that teaches nothing appends nothing.
+
+**The floor is closed**: a change touching **security · data · architecture** ALWAYS escalates
+to a real task — never inline, no matter how small (security stays HARD-STOP everywhere).
+New behavior, a new/changed contract, or anything you would want a frozen §3 for → bucket it.
+The route is yours, the veto is not: the human saying "make it a task" overrides the lane,
+always. When in doubt, bucket — the lane is for changes whose whole story fits in a diff.
 
 ## The four buckets
 
@@ -29,16 +67,23 @@ already-frozen scope?" → if yes it is a `change-request` (never re-size frozen
 Only if no, apply the size test: a new theme → `new-major`; a slice of a live theme → `sub-milestone`;
 fits the active milestone → `task`.
 
-**One-task gap rule.** If the request is ONE task but does NOT fit the active milestone's stated
-scope, do not force it into `sub-milestone` (which requires "too big for one task"): create a new
-micro-milestone to house it (`new-milestone` + `new-task`) — that gives the task ledger attribution
-and clear exit criteria without inflating scope.
+**Size the freeze, not the template (task bucket only).** ONE atomic template serves every task;
+single behavior · no new contract surface others consume · sensitivity mechanical → propose drafting
+the whole Direction bundle in one pass to a single freeze. Any doubt → draft §1–§4 beat by beat.
+
+**One-task gap rule.** ONE task that does NOT fit the active milestone's scope: never force it
+into `sub-milestone` — create a micro-milestone to house it (`new-milestone` + `new-task`) for
+ledger attribution + clear exit criteria without inflating scope.
+
+**Batched intake.** N same-bucket items arriving together classify as ONE proposal: one report,
+one human confirm covering the batch — never N sequential asks. Mixed buckets stay
+`split_required`.
 
 ## What you emit (the proposal)
 
-Present the proposal via `report-template.md` — open with the ARC (goal · done · plan): the goal this
+Present the proposal via `gate-udd.md` — open with the ARC (goal · done · plan): the goal this
 request serves, what is already covered, and the plan the chosen bucket sets up. Render it as a guided
-choice — the recommended bucket + its described alternatives (per `report-template.md`). For every
+choice — the recommended bucket + its described alternatives (per `gate-udd.md`). For every
 request, emit ONE of:
 
 - **a classification** — `{ bucket, rationale, command }` — `rationale` names WHY (the theme, the
@@ -55,29 +100,20 @@ request, emit ONE of:
 </reject_codes>
 
 When confirmed, record the `rationale` in the artifact you create or affect — the new MILESTONE.md
-goal/body, the new TASK.md, or a note in the affected TASK.md — never in state.json.
+goal/body, the new PLAN.md, or a note in the affected PLAN.md — never in state.json.
 
 ## Roadmap — a request that is several milestones
 
-Some requests decompose into **N>1 milestones of the same line** — a roadmap, not one milestone.
+Some requests decompose into **N>1 milestones of the same line** — a roadmap.
 Don't create only the first and lose the rest. Instead:
 
 1. **Propose** the roadmap — the ordered milestone list, each with a one-line goal.
-2. **Confirm** — the human confirms the roadmap before anything is created. Never auto-create N
-   milestones unprompted — the intake floor (`ask_human`) still holds.
+2. **Confirm** — the human confirms before anything is created; never auto-create N
+   milestones unprompted (the `ask_human` floor holds).
 3. **Create** all N on confirm — the first with `add.py new-milestone <slug>` (active), the rest
    with `add.py new-milestone --queued <slug>` (status `queued`, not focused).
-4. **Promote** one at a time — as each is started, `add.py activate <slug>` flips it queued→active.
-   You work one active milestone at a time; the queue is the agreed backlog, surfaced at resume.
-
-This is NOT `split_required`: that code is for a request spanning **different buckets** (propose the
-smallest correctly-sized set). A roadmap is several milestones of the **same line**, created queued.
-
-## Worked examples (from this project's own history)
+4. **Promote** — `add.py activate <slug>` flips each queued→active as started; one active
+   milestone at a time, the queue is the agreed backlog surfaced at resume.
 
-| request | bucket | rationale |
-|---------|--------|-----------|
-| give ADD a hosted web dashboard | new-major | a new product theme no active milestone's goal covers → a fresh major line (v5) |
-| add the build corridor + tests-red-before-build | sub-milestone | a slice of the live v4 "self-driving" theme, too big for one task → v4-2 |
-| expose owner/stop as --json | task | fits the active v4-1 (intake interface) scope → one task |
-| guide --json phase/gate should be nullable | change-request | changes the FROZEN machine-state-json contract → reopen its CONTRACT, do not make a new milestone |
+NOT `split_required` (that is for a request spanning **different buckets**); a roadmap is
+several milestones of the **same line**, created queued.

package/skill/add/loop.md

@@ -1,38 +1,37 @@
 # 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 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.
+A milestone is done when its **GOAL** is met, not when its tasks are.
+This guide drives toward that goal: turn what each task leaves behind (open lessons,
+work discovered out of scope) into the next tasks until the exit criteria are all met.
 
 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.
+creates each one. The engine never decides the next task — that's judgment.
 
 ## The goal-gate (what holds the loop open)
 
-`add.py milestone-done <slug>` REFUSES to close a milestone while its exit criteria are not
-all met — it stops with `milestone_goal_unmet` and the milestone stays active. The exit-criteria
+`add.py milestone-done <slug>` REFUSES to close a milestone while its exit criteria aren't
+all met — it stops with `milestone_goal_unmet`, 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. Checking the last box is the
+`- [x]`/`- [ ]` tally, never judging 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.
+before — write criteria into `MILESTONE.md` 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. The one gate is enough — there is no quiet way around it.
+`milestone-done` is the only way a milestone reaches `done`; `archive-milestone`
+refuses a milestone not done. The one gate is enough — 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)`. That is the cue:
+Every task done but not the goal? `add.py status` shows
+`goal not met (m/n exit criteria)`. That's the cue:
 
 1. **Gather** the carried inventory:
-   - open lessons — `add.py deltas` (the §7 OBSERVE deltas still `open`);
+   - open lessons — `add.py deltas` (§7 deltas still `open`);
    - the planned-but-unscaffolded tasks — the plan-vs-state line in `add.py status`;
    - any reopened task — one a deepened verify returned to the flow (see below).
 2. **Propose** the next tasks: for each carried item worth doing now, draft a one-line task
-   (slug + title + why) and show the human. Group the trivial ones; do not propose noise.
+   (slug + title + why) and show the human. Group trivial ones; no noise.
 3. **Confirm** — the human accepts, edits, or declines each. No task is created without this.
 4. **Create** each accepted task — `add.py new-task <slug> --title "..."` — and run it through
    the normal flow (specify → … → verify).
@@ -41,18 +40,31 @@ When every task is done but the goal is not, `add.py status` shows
    - **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.
+     and the **Goal met?** map — each exit criterion tied to its evidence.
+     This is the whole-milestone cross-task evidence the human READS — evidence, not a gate.
    - **Check the boxes** — read that evidence, then check the exit-criteria boxes in `MILESTONE.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`).
+     (the single affirmation), and `add.py milestone-done <slug>` succeeds (then file the open
+     deltas into their living specs — `add.py delta-append` — and archive).
    - **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),
+     step among them; PR, asset export, tag/publish are others). The human owns the cut;
+     loop.md never re-specifies it.
+   Present the close via `gate-udd.md` — open with the ARC (goal · done · plan),
    render as a guided choice — **before `milestone-done`/`archive-milestone` run, not after.**
 
+## Route reflection (GEPA) — the routes learn at close
+
+`add.py deltas` ends with the **route scoreboard**: per-lane evidence (gated · outcome mix ·
+heals · median age) rolled up from `.add/traces/route-outcomes.jsonl` — one line the engine
+appends at every recorded gate. At close, reflect on it GEPA-style under the PM persona:
+
+- **keep** a route rule whose lane cut heals/age with no gate regressions;
+- **prune** a rule no trace ever took (it never fired);
+- **propose** each change as `add.py delta-append add "<route-rule delta>"`, evidence cited.
+
+The **human folds** ratified rules into `.add/personas/<slug>.md` — the only mutation path
+(never-clobber). Personas never touch frozen contracts, tests, the SKILL core, or the
+security HARD-STOP.
+
 ## Reopen is the verb; this loop is the trigger
 
 When a deepened verify finds a criterion unmet on a task already marked done,

package/skill/add/phases/build.md

@@ -0,0 +1,78 @@
+# Build — AI writes the code (the beat you drive to green)
+
+Objective: implement the feature so EVERY failing test passes — without changing any
+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 its tests, implement, iterate to green —
+each batch small enough to review in full.
+
+## Declaring the scope of impact (Scope + Strategy)
+
+§5's declarations are drafted with the bundle and frozen by the §3 approval — never invented mid-build:
+
+- **Scope (may touch)** — the allowlist the build may write (backticked tokens); a file outside it is a **STOP → change request** back to Specify.
+- **Strategy (ordered batches)** — the planned build order; guidance, not enforced.
+- **Strategy facets** — Approach (domain strategy) · Data strategy · Pattern · Optimization stance: the domain HOW, anchored upstream (§1 Framings · §3 Schema · CONVENTIONS.md Honors), drafted at tests->build in the Persona's domain vocabulary; ⚠-mark the facet you trust least (risk: high → consult the add agent, advise mode). Advisory, never a gate.
+
+Enforced: a completing verify gate refuses an out-of-scope build (`scope_violation` → self-heal).
+
+## Persona overlay (optional)
+
+Load the active `.add/personas/<slug>.md` as a domain **overlay** atop `SOUL.md` (SOUL = voice/trust; persona = domain **stance**) — name it in §5; its domain supplies the facet vocabulary. SOUL.md is **human-owned**: the overlay never rewrites it (voice deltas: `deltas.md`). Advisory — it never lowers a gate; security still **HARD-STOPs**.
+
+## A red outside your suite — locate first
+
+`add.py locate path::test_name`, never a blind fix. **in-node** — a live task owns it;
+coordinate. **interface-regression** — you broke a DONE task's contract: fix the breaker; a
+contract change is a change request, the printed closure names who re-verifies. **unowned** —
+host/foreign surface = your §3 Regression floor; keep it green. A §4 `covers:` map quotes the
+frozen §3 clause — repair the clause, not the symptom.
+
+## 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 §5 safety rule (e.g. atomic balance update).
+
+## Exit gate
+
+<exit_gate>
+- [ ] All tests pass.
+- [ ] Coverage did not decrease.
+- [ ] No test and no contract modified by the AI.
+- [ ] No dependency outside the allow-list.
+- [ ] No file outside the declared §5 Scope was touched.
+- [ ] Change small enough to review in full.
+</exit_gate>
+
+> **Advisor · Confidence** — delegate a well-scoped batch (the advisor spawn, `phases/verify.md`); self-score before presenting green, refine while cheap (the confidence self-score, `phases/direction.md`).
+
+## Next
+
+`python3 .add/tooling/add.py gate PASS` (from build — compound-crosses to verify in one call) → `phases/verify.md` on demand.
+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 (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.
+
+## The self-improving map — every loop feeds four artifacts
+
+You emit `open`; the human confirms; the engine transcribes — **nothing self-approves**. Emission
+lives in observe (§7); every earlier step feeds it: ground surprises → §1 · the freeze's ⚠ flag →
+the next spec · a red-suite gap → a TDD lesson · build's strategy-actually-used → the ADR block ·
+verify residue → a SPEC delta.
+
+| what improves | grammar (closes `(evidence: …)`) | consolidator |
+|---|---|---|
+| the living specs — `.add/specs/` | `[DDD\|SDD\|UDD\|TDD\|ADD · open] lesson` | `add.py delta-append <dd>` |
+| personas — the agents' stances | `… · persona:<slug> · critical-rule\|success-metric\|anti-pattern\|ability` | the persona loop |
+| `SOUL.md` — your voice | a voice delta, `open` | human rewrite (`deltas.md`) |
+| the next scope | `[SPEC · open]` → seeded · dropped · carried | `loop.md` → `new-task` |
+
+Routing: `ddd`→domain · `sdd`→system · `udd`→experience · `tdd`→quality · `add`→method — each
+lands in-flight in its living spec via `add.py delta-append <dd>` (grammar: `deltas.md`). A
+HOW-an-agent-behaves lesson → a persona, not the shared pile. Deltas prepend newest-first;
+the spec diff is the receipt. Self-score before emitting (the confidence six dimensions; < 0.9 → refine).