@pilotspace/add 1.17.0 → 2.1.0

package/skill/add/beyond.md

@@ -0,0 +1,37 @@
+# Beyond the bundle — the full routing prose
+
+SKILL.md's compact index names each trigger; this guide carries the full routing
+prose. Load it (or the one guide you need) only when a trigger fires.
+
+- **§3 CONTRACT FROZEN** → build→verify is a dynamic, auto-gated run (`autonomy: auto` default; lower to
+  `conservative`/`manual` for a human gate) — `run.md`. Pipeline ready tasks behind frozen
+  contracts — the stream-orchestrator persona owns the playbook. Delegate one piece of your plan to a subagent — the named roster
+  (`add-worker` runs the beat — mode: direction/build/verify/persona; `add-advisor` is the second
+  mind it spawns to propose a plan, pressure-test a draft, or decide a delegable ambiguity) is
+  agent-call-preferred, the default over an ad-hoc spawn; when to spawn, the prompt template, the
+  tier — the advisor spawn (`phases/verify.md`). Self-score a draft (0–1 across six dimensions,
+  refine if any < 0.9) — the confidence self-score (`phases/direction.md`). Both advisory; the engine never spawns.
+- **Small, low-risk task**, less ceremony → the ONE atomic template already IS the lean render:
+  `new-task` scaffolds only the interface (contract · red suite · scope · verdict), bundle approved
+  in one freeze. Floor held (frozen contract · red test · verify gate; freeze-gated under any
+  milestone). Collapse, never skip — there is no separate lane to opt into.
+- **UI feature** at specify → the **design-definition loop** (UDD): intake the design axes → review the
+  domain → research and reuse components → wireframe → a captured screen the human confirms **before** build — `design.md`.
+  Tool-agnostic; the engine never renders.
+- Tasks all done but the milestone **goal** unmet → `milestone-done` holds it open; the loop turns open
+  deltas + extras into the next tasks until the goal is met — `loop.md`.
+- **Graduating mvp → production** — co-specify interview → draft ≥1 production milestone →
+  human confirm → then `stage production`. Guarded (`stage_no_roadmap`); the FINAL step, never a
+  bare flip. The quality-auditor persona carries the readiness playbook.
+- **Cutting a release** — draft notes from the closed milestones' deltas → meet the readiness
+  floor (security HARD-STOP is un-forceable) → the human confirms and runs the tag/publish/deploy.
+  The release-manager persona carries the cut playbook; the engine records nothing.
+- **Monorepo / multi-repo** — a milestone spans more than one green bar (a BE + its FE) → the
+  platform-engineer seed persona carries the components playbook (declare the parts, gate each
+  task on its part's green bar, hold a consumer until its producer's contract freezes). Opt-in.
+- **Project-fit personas** — the **persona loop** seeds `.add/personas/<slug>.md`, grows them via
+  observe→delta→consolidate, applies them in design/orchestration/advisor/build (advisory; never lowers a gate) — `docs/18-personas.md`.
+- **Risk-class of a task** — declare `sensitivity:` in the TASK header (base `security|data|architecture|
+  mechanical`, always valid). EXTEND it with your project's domain classes in `GLOSSARY.md`'s `## Sensitivity
+  classes` section; freeze/status/check read base ∪ project. The AI keeps the domain vocabulary current —
+  the Sensitivity section (`phases/verify.md`). Security is a human floor in every tier; only `mechanical` is advisor-gatable — see `advisor-gate-relax` in `run.md`.

package/skill/add/deltas.md

@@ -1,9 +1,11 @@
 # Lessons learned — how each loop sharpens the foundation
 
-A **lesson learned** is a single learning a task produces, tagged by which of ADD's five competencies it improves. Write deltas in **OBSERVE**; later `fold.md` consolidates confirmed ones into a versioned `PROJECT.md` — how `DDD · SDD · UDD · TDD · ADD` stop being write-once and converge.
+A **lesson learned** is a single learning a task produces, tagged by which of ADD's five competencies it improves. Write deltas in **OBSERVE** and file each into its living spec (`add.py delta-append`) — how `DDD · SDD · UDD · TDD · ADD` stop being write-once and converge.
 
 You **emit** deltas as `open`; only the **human** moves one to `folded` or `rejected`. You never self-approve a consolidation.
 
+**Emit in-flight, not batched**: the moment a lesson is learned — any phase, any task — file it with `add.py delta-append <dd> "<lesson>"` (`ddd|sdd|udd|tdd|add`). The verb prepends one `[open · <date>]` line (newest first, active task stamped) into the lesson's **living spec** under `.add/specs/` — `domain.md · system.md · experience.md · quality.md · method.md`, seeded at init and on demand for pre-2.0 projects. The task's §7 Competency-deltas block stays the per-task record; the living spec is where the lessons accumulate across tasks.
+
 ## The grammar (frozen)
 
 Each delta begins on its own **tag line**; the learning may wrap:
@@ -16,7 +18,7 @@ Each delta begins on its own **tag line**; the learning may wrap:
 - `<status>` — `open` | `folded` | `rejected`. A **newly emitted delta is `open`**.
 - `<learning>` — the insight; the tag line comes **first**, `(evidence: …)` **closes** the delta.
 - `(evidence: …)` — **required**, non-empty: a failing scenario, a production signal, a review note. No evidence → it is an opinion, not a delta.
-- **persona target (optional)** — a competency lesson MAY add `· persona:<slug> · <critical-rule|success-metric|anti-pattern|ability>` in brackets, e.g. `- [UDD · open · persona:ui-designer · success-metric] 4.5:1 contrast (evidence: audit)`. At `add.py fold` it lands in `.add/personas/<slug>.md` under that section (newest-first, never clobbering) instead of `PROJECT.md` (`fold.md`).
+- **persona target (optional)** — a competency lesson MAY add `· persona:<slug> · <critical-rule|success-metric|anti-pattern|ability>` in brackets, e.g. `- [UDD · open · persona:ui-designer · success-metric] 4.5:1 contrast (evidence: audit)`. The persona loop lands it in `.add/personas/<slug>.md` under that section (newest-first, never clobbering) instead of the shared specs.
 
 A long learning may wrap — `add.py check` joins continuation lines into **one** delta:
 
@@ -62,3 +64,24 @@ emit (OBSERVE)        human review
 ```
 
 At the next update the human consolidated DDD+TDD (→ `folded`) and rejected ADD. Sharper foundation; nothing lost.
+
+## Voice deltas — SOUL.md converges to the human
+
+`SOUL.md` (Tone · Communication style · Trust) is the AI's voice — a proposed starter,
+**human-owned**. Emit voice deltas beside the lessons learned in observe, grounded ONLY in the
+working session — their wordings, their corrections, their flow — never their private files:
+
+```
+- [VOICE · <status>] <observation about the voice> (evidence: <in-session pointer>)
+```
+
+`<status>` = `open` | `confirmed` | `declined`; evidence is required (a correction, a re-ask, a
+visible preference) — none → drop it. The loop: **emit** `open` (show-before-ask) → the human
+**confirms or declines** each → on a confirm, rewrite the routed SOUL.md section surgically
+(how I *sound* → `## Tone` · how I *structure* → `## Communication style` · what keeps *trust* →
+`## Trust`) and record the line `confirmed` at the top of `## Voice deltas` (newest-first,
+append-only; declined stays in place). **The human's confirm is the only writer.** Rejects:
+`unconfirmed_voice_rewrite` (a SOUL.md write without a recorded confirm — stop, get the confirm) ·
+`no_open_voice_deltas` (nothing open — a no-op, touch nothing) · `unroutable_voice_delta` (maps
+to no section — fix the delta or widen the routing before writing). No `add.py` command writes
+the voice.

package/skill/add/design.md

@@ -1,12 +1,11 @@
 # Design — the design-definition loop (UDD)
 
-When a **UI feature** reaches specify, design it before you build it. This loop takes the
-feature from the **domain** to a screen the human has **seen and confirmed** — a real captured
-image — *before* any implementation. Loaded on demand; the engine never runs it for you.
-
-Design before code is the UDD half of the method. It fills the existing token + component
-foundation — `tokens.json` (`udd-tokens.md`), `catalog.json` + `prototypes/<name>.json`
-(`udd-catalog.md`) — for a feature and earns the human's sign-off before build.
+When a **UI feature** — or any human-facing **experience surface** (screen · interactive flow ·
+**human gate**) — reaches specify, design it first. UDD is experience-driven, not UI-only: it takes
+the surface from the **domain** to a real captured image the human has **seen and confirmed** —
+*before* build. Loaded on demand; the engine never runs it. It fills the existing token + component
+foundation — `tokens.json` (schema: `templates/udd-tokens.md`), `catalog.json` +
+`prototypes/<name>.json` (schema: `templates/udd-catalog.md`).
 
 ## The loop — five beats
 
@@ -16,91 +15,74 @@ design-intake  →  review-domain  →  research-components  →  wireframe  →
 
 Run the beats in order; the last ends at a human design-confirm.
 
+## Personas carry the design — the loop carries the discipline
+
+Load the design-fit persona FIRST: it brings the **frontend-designer** performance, the loop keeps
+the rigor (personas carry the expertise, the loop the discipline). Two `flow: design` dimensions
+(`.add/personas/*` frontmatter, else description-match) — **UI-Designer** (visual systems · component
+libraries · pixel-craft · WCAG-AA **accessibility**) and **UX-Researcher** (evidence-validated,
+never assumed). None fits? Seed from `.add/personas-teacher/design/` (ui-designer · ux-researcher ·
+ux-architect) + `engineering-frontend-developer` via the add agent in persona mode, then load — seed
+per DOMAIN, reuse across screens. The persona's **Critical Rules** shape every beat; its **Success
+Metrics** become the beat-4 confirm checklist. Advisory: it sharpens the design, never lowers a gate.
+
 ### 0 · design-intake
-Before reading the domain, interview the human on **four design axes** so the look is *directed*,
-not guessed — ask each, show options, record the pick:
+Before reading the domain, interview the human on **five design axes** — ask each, show options,
+record the pick:
 
-- **FIDELITY** — how far this goes: *lo-fi wireframe* · *hi-fi mockup* · *production*. Recorded
-  **intent** informing the later beats, not an engine gate.
-- **CONCEPT** — the design *idea / mood / direction* in a line.
-- **LAYOUT** — the *structure / grid / hierarchy* the screens lean on.
+- **FIDELITY** — *lo-fi wireframe* · *hi-fi mockup* · *production*. Recorded intent, not a gate.
+- **CONCEPT** — the *idea / mood / direction* in a line.
+- **LAYOUT** — the *structure / grid / hierarchy*.
 - **VISUAL DESIGN** — *color · type · spacing · imagery*. **Surface** identity values for the human
-  to choose — never auto-pick a brand value (identity stays **human-owned**, `udd-tokens.md`).
+  to choose — never auto-pick (identity stays **human-owned**, `templates/udd-tokens.md`).
+- **INTERACTION** — *cadence · when/how to seek the human · turn-rhythm*; static screen → *none*.
 
-Record the answers **before** review-domain: project **defaults** in DESIGN.md's `## Design intake`;
-per-screen **overrides** (deltas only) in the per-feature design note (`prototypes/<name>.json`
-companion). Show-before-ask — confirm the picks.
+Record **before** review-domain: project **defaults** in DESIGN.md's `## Design intake`; per-screen
+**overrides** in the per-feature note (`prototypes/<name>.json` companion). Show-before-ask.
 
 ### 1 · review-domain
 Start from the **domain**, not a blank canvas. Read the domain model — entities, flows, the
-ubiquitous language in `PROJECT.md` / `GLOSSARY.md` — and derive **which screens** the feature
-needs + the **regions** each holds. Map each entity to a *presentational* component (shows state;
-owns no domain decision). The screen list + regions are this beat's output.
+ubiquitous language in `PROJECT.md` / `GLOSSARY.md` — and derive **which screens** the feature needs
++ each screen's **regions**. Map each entity to a *presentational* component (owns no domain
+decision). Output: the screen list + regions.
 
 ### 2 · research-components (reuse before you invent)
-Check `catalog.json` **first** and **reuse** what's there — it keeps screens consistent. Research
-a reference UI only to fill a **genuine gap**; propose a **new** catalog component for it with a
-**cited** reference. Reuse before invention — a new component is the exception.
+Check `catalog.json` **first** and **reuse** it. Research a reference UI only for a **genuine gap**;
+propose a **new** catalog component with a **cited** reference — the exception, not the reflex.
 
 ### 3 · wireframe
 Draw a **low-fi**, **structural** layout per screen — regions and component slots, no styling, no
-color. The cheapest artifact that shows the *expected layout*, so the human corrects structure
-before a pixel is styled. Confirm, then move on.
+color. Confirm structure before a pixel is styled, then move on.
 
 ### 4 · render-capture-confirm
-Render the screen as a **self-contained HTML mock** — the component library via CDN, bound to
-`tokens.json` (CSS variables), composed from the **reusable per-component kit** (one token-bound
-partial per catalog component), with realistic **mock** data.
-**Capture** a real image (a headless screenshot) and present it to the human for **design-confirm**
-— show-before-ask, **before build**. On confirm, record the layout to `prototypes/<name>.json` +
-`catalog.json`, save the image to `.add/design/captures/<name>.<ext>`, and **mention it in the
-feature's `TASK.md`** — so the approved screen is traceable from the task. The HTML mock is the
-*visible evidence*; the json-render tree is the *machine-checkable* record.
-
-**Persona evidence checklist.** Before design-confirm, load the `flow: design` personas
-(`.add/personas/*` frontmatter, else description-match) and render their `## Success Metrics`
-as a confirmable **checklist** beside the captured image — **both dimensions**: **UI-Designer**
-(visual + WCAG-AA **accessibility**) and **UX-Researcher** (methodology-first,
-**validated by user evidence, not assumed**). Each item traces to a success-metric
-the human confirms; it is **evidence, never an auto-pass** — a persona **never lowers a gate**
-(ADD principle 2). **No UI personas**? A **generic design-confirm**, never blocked; UI-less skips it.
+Render the screen as a **self-contained HTML mock** (component library via CDN, bound to
+`tokens.json`, composed from the per-component kit, realistic **mock** data). **Capture** a real
+image (headless screenshot), present it for **design-confirm** — show-before-ask, **before build**.
+On confirm: record layout to `prototypes/<name>.json` + `catalog.json`, save image to
+`.add/design/captures/<name>.<ext>`, mention it in the feature's `PLAN.md`.
+
+**Persona evidence checklist.** Render the loaded personas' `## Success Metrics` as a confirmable
+**checklist** beside the image — both dimensions: **UI-Designer** (visual/**accessibility**) and
+**UX-Researcher** (evidence, not assumed). Each item traces to a metric the human confirms —
+**evidence, never an auto-pass**; a persona **never lowers a gate**. **No UI personas** → a
+generic design-confirm; UI-less skips it.
+
+### Text-mode gate variant
+A **human gate** runs the loop in **text mode** — intake the **INTERACTION** axis → design the
+report per `gate-udd.md` → **confirm**; no capture beat.
 
 ## Tool-agnostic capture
 
-How you render and capture is **your** choice (headless browser, `html2image`, a design tool, a
-screenshot service). The default is the self-contained HTML mock above, captured headless — no app
-build, yet wearing the project's real tokens and components. For a json-render project, the default
-is **`@json-render/image`** (Satori → PNG/SVG, no browser). The captured image is **design-confirm
-evidence** the human approves; the engine never renders — the loop stays tool-agnostic, the method
-renderer-free.
-
-Captures live at **`.add/design/captures/<name>.<ext>`**, mentioned in the feature's `TASK.md`.
-`add.py check` raises a never-red `missing_capture` WARN for any prototype lacking one — a nudge
-to render + confirm.
+Render/capture however you like (headless browser, `html2image`, a screenshot service); the default
+is the self-contained HTML mock above, captured headless. For a json-render project, the default is
+**`@json-render/image`** (Satori → PNG/SVG, no browser). The engine never renders — the loop stays
+tool-agnostic. Captures live at **`.add/design/captures/<name>.<ext>`**, mentioned in `PLAN.md`;
+`add.py check` raises a never-red `missing_capture` WARN for any prototype lacking one.
 
 The loop **binds** the UDD contracts **read-only** — `tokens.json` / `catalog.json` /
 `prototypes/<name>.json` are read, never reshaped (a reshape is a change request). **Identity**
-values stay **human-owned** (`udd-tokens.md`).
-
-## The hard rules
-
-<constraints>
-- **Intake before domain.** The four axes (FIDELITY · CONCEPT · LAYOUT · VISUAL DESIGN) are
-  interviewed and recorded — DESIGN.md defaults + per-screen overrides — before beat 1.
-- **Domain first.** A screen is derived from the domain (beat 1), never sketched blind.
-- **Reuse before invent.** Beat 2 checks the catalog first; a new component is a justified,
-  cited exception — never the reflex.
-- **Confirm before build.** The captured image is approved by the human *before* implementation;
-  a design-confirm placed at or after build defeats the loop.
-- **The engine never renders.** Capture is a recommended, tool-agnostic recipe run by the
-  agent's own tools; the image is evidence, not an engine artifact.
-- **Bind, don't break.** The loop reads `tokens.json` / `catalog.json` / `prototypes/<name>.json`
-  read-only; the data contract is unchanged, and identity values stay human-owned.
-- **Confirm against the personas.** With UI personas seeded, the checklist carries the UI-Designer
-  (visual/accessibility) + UX-Researcher (evidence-not-assumption) success-metrics — evidence,
-  never an auto-pass.
-</constraints>
-
-> Used at specify for a UI feature: `phases/0-setup.md` scaffolds `DESIGN.md`, and
-> `phases/1-specify.md` points here when the feature has a screen — run the four beats, then
+values stay **human-owned** (`templates/udd-tokens.md`).
+
+> Used at specify for a UI feature: `phases/direction.md`'s setup span scaffolds `DESIGN.md`, and
+> its Rules span points here when the feature has a screen — run the four beats, then
 > carry the confirmed layout into the contract.

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 arc · `done:` tests 6/6 green · `plan:` PASS → every gate → goal.
-- **contract-freeze** — `done:` bundle drafted, 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.
-- **Cap live items at ~5–7**, dependency-ordered; footer `+N more queued`.
-- **One line per item** — slug + what it does or blocks on; never restate the whole TASK.md.
-- **Glyphs are fixed** — ✅ done · 🔄 active · ⬜ pending · ⚠ blocked/flagged; never invent new ones.
-- **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,27 +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, no filler; one genuine path → show one.
-- **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 item with its own lowest-confidence flag; APPROVE covers the batch in one ask, and any item can be held back by name.
+- **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,21 +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`) — ledger attribution + 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.
 
-**Batched intake.** N same-bucket items arriving together (one directive; a drafted
-milestone's task list) classify as ONE proposal: one report listing every item, one
-human confirm covering the batch — never N sequential asks. Mixed buckets stay
+**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
@@ -60,7 +100,7 @@ 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
 
@@ -77,12 +117,3 @@ Don't create only the first and lose the rest. Instead:
 
 NOT `split_required` (that is for a request spanning **different buckets**); a roadmap is
 several milestones of the **same line**, created queued.
-
-## Worked examples (from this project's own history)
-
-| request | bucket | rationale |
-|---------|--------|-----------|
-| give ADD a hosted web dashboard | new-major | a new product theme → a fresh major line (v5) |
-| add the build corridor + tests-red-before-build | sub-milestone | a slice of the live v4 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 a FROZEN contract → reopen its CONTRACT, never a new milestone |

package/skill/add/loop.md

@@ -1,33 +1,33 @@
 # The dynamic loop — open deltas and extras become the next tasks
 
 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, and
-work discovered but out of scope) into the next tasks until the exit criteria are all met.
+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
 
 Every task done but not the goal? `add.py status` shows
-`goal not met (m/n exit criteria)`. That is the cue:
+`goal not met (m/n exit criteria)`. That's the cue:
 
 1. **Gather** the carried inventory:
-   - open lessons — `add.py deltas` (§7 deltas still `open`) + the deferred pile — `add.py deltas --carried`;
+   - 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
@@ -40,18 +40,31 @@ Every task done but not the goal? `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,