@pilotspace/add 1.13.0 → 1.15.0

package/skill/add/advisor.md

@@ -1,30 +1,29 @@
 # Advisor — spawning one subagent to follow your plan
 
-The **advisor** strategy is for the orchestrating agent: spawn a *single* subagent to execute
-one piece of your plan, then merge its verdict back in. It is the single-subagent companion to
-`streams.md` — streams pipelines *many* independent tasks in parallel worktrees; the advisor
-delegates *one* well-scoped piece (a sweep, a review, a batch) while you stay in the loop. The
-engine never spawns; this is your judgment to make per step.
+The **advisor** strategy: spawn a *single* subagent to execute one piece of your plan, then merge
+its verdict back. It is the single-subagent companion to `streams.md` (which pipelines *many* tasks
+in parallel worktrees) — you delegate *one* well-scoped piece and stay in the loop. The engine never
+spawns; this is your call per step.
 
 ## When to spawn — and when not
 
-Spawn a subagent when the piece is **separable and worth the round-trip**:
+Spawn when the piece is **separable and worth the round-trip**: a broad sweep; an independent adversarial review (the `6-verify` refute-read — fresh context, not graded by the author); a well-scoped batch; or context-offload to a small verdict.
 
-- **Broad / expensive sweep** — gather a wide map cheaply, return a compact result.
-- **Independent adversarial review** — a fresh context argues *against* your result (the
-  `6-verify` earned-green refute-read), so the check is not graded by the author.
-- **A well-scoped delegable batch** — a self-contained slice with a clear contract and return shape.
-- **Context offload** — work that would bloat your context but compresses to a small verdict.
+Do **not** spawn for narrow, cheap work — pay the round-trip only when the piece is big or independent enough. When in doubt, do it in-context.
 
-Do **not** spawn when the work is narrow and cheap enough to do in-context: a small sweep, a
-two-file read, a quick edit. A spawn costs a round-trip — pay it only when the piece is big or
-independent enough to earn it. When in doubt, do it in-context.
+## The 3-lens sequential checklist at verify
+
+At Verify, sweep security → concurrency → architecture in order. **Security HARD-STOP ends the checklist** (leave the rest blank). Each lens returns: **CLEAR** · **HARD-STOP** (security only) · **RESIDUE** (concurrency/architecture).
+
+Record it in §6 `### Advisor 3-lens verdict`: **Verdict** (PASS/HARD-STOP) · **Residue** (none or brief) · **Binding** (`yes` for `sensitivity: mechanical` — the engine reads it for `advisor-gate-relax`; `advisory` otherwise).
+
+**Persona for the refute-read.** When the piece is the earned-green refute-read, select a **Code-Reviewer** persona; its findings carry severity markers — 🔴 blocker · 🟡 concern · 💭 note. A persona is advisory: it never lowers a gate (a security finding still HARD-STOPs).
 
 ## The plan-following prompt template
 
-Give the subagent the *piece of your plan it owns* and a fixed return shape. This reuses
-`streams.md`'s worker-contract tags for a single advisory subagent — the contract is identical
-on any runner; only the spawn adapter (see `streams.md`) changes. The `<strategy>` block mirrors the task's §5 (Strategy + Known-problem fixes) as the subagent's PREFERRED path — it self-improves on that plan and reports the strategy it actually used.
+Give the subagent the *piece it owns* and a fixed return shape. This reuses `streams.md`'s
+worker-contract tags — identical on any runner; only the spawn adapter (see `streams.md`) changes.
+The `<strategy>` block mirrors the task's §5 as the subagent's PREFERRED path — it self-improves on that plan and reports the strategy it actually used.
 
 ```xml
 <objective>
@@ -33,9 +32,11 @@ surrounding decisions. Return a verdict; do not record state.
 </objective>
 
 <persona>
-You are a {{DOMAIN}} engineer. Correctness over speed; a wrong-but-plausible result is expensive.
+SELECT the best-fit project persona for this piece and load `.add/personas/{{PERSONA_SLUG}}.md` —
+Identity→your stance · Critical Rules→constraints · Success Metrics→done-bar (streams.md's worker
+contract). No match → a {{DOMAIN}} engineer, correctness over speed; never blocks.
 Work step by step, following the plan:
-1. Load the context files; confirm you understand the piece you own.
+1. Load the context files + the persona; confirm you understand the piece you own.
 2. Do the work in small steps, honoring the orchestrator's plan and constraints.
 3. Self-score your result with confidence.md; if any dimension < 0.9, refine before returning.
 </persona>
@@ -53,29 +54,25 @@ the plan / task files the piece needs (read-only unless the piece says otherwise
 
 <return>
 End with a structured verdict the orchestrator parses and RECORDS:
-{ piece, result, evidence, confidence: {per-dimension 0–1}, open_questions }.
+{ piece, persona, result, evidence, confidence: {per-dimension 0–1}, open_questions }.
+`persona` names the slug you adopted (or `generic`) — the orchestrator records which persona did the work.
 Do NOT run add.py or write any shared state — you propose, the orchestrator records.
 </return>
 ```
 
 ## Choosing the model — vendor-neutral tiers
 
-Pick the tier from `streams.md`'s vocabulary: **mid** for an ordinary, well-scoped piece; **top**
-for a complex, ambiguous, or cross-cutting one. The tier→model-id mapping and the spawn adapter
-live there — one home, not repeated here. A stronger model never buys back a human gate: high-risk
-scope still escalates.
+Pick the tier from `streams.md`: **mid** for an ordinary piece; **top** for a complex/ambiguous/
+cross-cutting one. The tier→model-id mapping + spawn adapter live there. A stronger model never buys
+back a gate: high-risk scope still escalates.
 
-## The hard rule — you delegate, you do not abdicate
+## The hard rule — delegate, don't abdicate
 
 <constraints>
-The engine never spawns — spawning is the orchestrating agent's choice (tool-agnostic). And:
-- the subagent PROPOSES; the orchestrator RECORDS — a worker never runs add.py or writes shared
-  state (state.json, MILESTONE.md, a sibling's files): you read its verdict and record the outcome;
-- delegation never lowers a gate — a SECURITY finding still HARD-STOPs, and high-risk scope still
-  escalates to the human, whoever (or whatever tier) did the work;
-- the spawned subagent returns its confidence.md self-score; a low score is a signal to refine or
-  re-spawn, never a pass.
+The engine never spawns — it's the orchestrating agent's choice. And:
+- the subagent PROPOSES; the orchestrator RECORDS — a worker never runs add.py or writes shared state;
+- delegation never lowers a gate — a SECURITY finding still HARD-STOPs and high-risk scope still escalates, whoever did the work;
+- the subagent returns its confidence.md self-score; a low score means refine or re-spawn, never a pass.
 </constraints>
 
-> Used per step: each phase guide's Advisor hook points here, so an agent spawns in the idiom of
-> the phase it is in (see the per-step hooks).
+> Used per step: each phase guide's Advisor hook points here (the per-step hooks).

package/skill/add/components.md

@@ -1,10 +1,8 @@
 # Components — monorepo and multi-repo slices
 
-Opt-in pillar for a milestone that spans **more than one green bar** — a backend
-and its frontend, a shared lib and two apps, services across repos. A project
-that declares no components is byte-identical to a single-codebase project. Reach
-for this only when one milestone genuinely crosses components. Full narrative:
-book chapter `17-components.md`.
+Opt-in pillar for a milestone spanning **more than one green bar** — a BE + its
+FE, a shared lib + two apps, services across repos. No components declared =
+byte-identical to a single-codebase project. Full narrative: `17-components.md`.
 
 ## Declare (never inferred)
 
@@ -13,21 +11,21 @@ book chapter `17-components.md`.
 ```toml
 [component.gateway]
 root      = "apps/gateway"
-green-bar = "pytest + pyright"
+green_bar = "pytest + pyright"
 [component.dashboard]
 root      = "apps/web"
-green-bar = "vitest + a11y"
+green_bar = "vitest + a11y"
 ```
 
-A task binds with a `component: <name>` header line → that root joins its §5
-Scope, and verify holds it to that component's green-bar.
+A task binds with a `component: <name>` header → that root joins its §5 Scope,
+and verify holds it to that component's green-bar.
 
 ## The loop
 
-1. **Per-component verify.** A bound task must CITE its component's green-bar in
-   the §6 Build-expectations evidence, or the gate refuses
-   `component_green_bar_uncited`. The engine never runs the suite — you run the
-   right one; the gate checks the right bar was cited.
+1. **Per-component verify.** A bound task must CITE its green-bar in §6 evidence
+   or the gate refuses `component_green_bar_uncited`. The engine never runs the
+   suite — it **surfaces** the component's `verify` command (and records it in §6);
+   you run it (NO-EXEC). The fast lane carries the same `component:` affordance.
 2. **Freeze a cross-component contract.** Declare `[contract.<id>]`
    (producer + consumers). A task names its role `produces: <id>` / `consumes: <id>`.
    The producer's freeze (contract→tests) writes the immutable snapshot
@@ -35,20 +33,20 @@ Scope, and verify holds it to that component's green-bar.
    flags consumers `contract_consumer_stale`; a missing/malformed snapshot
    HARD-STOPS — never build against an unfrozen shape.
 3. **One milestone, full slice.** A `consumes:` task is HELD from advancing
-   scenarios→contract (`producer_contract_unfrozen`) until the producer's
-   snapshot exists. The FE stays downstream of the frozen BE endpoint, in one
-   milestone.
+   scenarios→contract (`producer_contract_unfrozen`) until the producer's snapshot
+   exists — and `producer_contract_stale` if a live producer re-opened/drifted its
+   §3 (freeze-recency). The FE stays downstream of the frozen BE, in one milestone.
 4. **Across repos — federate.** A consumer repo declares `[federation.<id>]`
    (`source` + optional `pin`); `add.py federate pull <id>` validates and lands a
-   byte-for-byte copy of the producer repo's published snapshot locally, where it
-   behaves as in a monorepo. Fail-loud: unknown id / unreadable source / invalid
+   byte-for-byte copy of the producer's snapshot locally. Fail-loud:
+   unknown id / unreadable source / a `source` escaping the repo's allowlist
+   (`federation_source_escapes`, confined to a repo-root sibling) / invalid
    snapshot / version mismatch each HARD-STOPS and lands nothing.
 
 ## Hold the line
 
 - **Declared, not inferred** — no scanning `apps/*`.
-- **No central server / no shared mutable state** — federation copies an
-  immutable snapshot; each repo keeps its own git-native `state.json`.
-- **No new approval** — these are engine-enforced gates on the existing six-step
-  flow, not extra human checkpoints. Ownership/autonomy per component is the
-  identity story (`streams.md`, governance), layered on this graph.
+- **No central server / no shared mutable state** — federation copies an immutable
+  snapshot; each repo keeps its own `state.json`.
+- **No new approval** — engine-enforced gates on the six-step flow, not extra human
+  checkpoints. Per-component ownership/autonomy is the identity story (`streams.md`).

package/skill/add/confidence.md

@@ -18,7 +18,7 @@ If **any** dimension scores **< 0.9**, refine the artifact before presenting, th
 ## Where it plugs in
 
 - It **feeds the lowest-confidence flag** (run.md · 1-specify.md): the lowest-scoring dimension is what you surface ⚠-first at the contract freeze.
-- A persistently low score on a risky scope is a signal to **recommend** lowering the autonomy level (auto → conservative / manual; run.md). Recommend it — the autonomy level stays the human's call.
+- A persistently low score on a risky scope is a signal to **recommend** lowering the autonomy level (auto → conservative / manual; run.md) — the level stays the human's call.
 
 ## The hard rule — advisory, never a gate
 

package/skill/add/deltas.md

@@ -1,8 +1,8 @@
 # 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 a task's **OBSERVE** phase; later, `fold.md` gathers confirmed ones and consolidates them into a versioned `PROJECT.md`. This is how `DDD · SDD · UDD · TDD · ADD` stop being write-once and start converging.
+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.
 
-You **emit** deltas as `open`. Only the **human** moves a delta to `folded` or `rejected`. You never self-approve a consolidation.
+You **emit** deltas as `open`; only the **human** moves one to `folded` or `rejected`. You never self-approve a consolidation.
 
 ## The grammar (frozen)
 
@@ -14,10 +14,11 @@ Each delta begins on its own **tag line**; the learning may wrap:
 
 - `<COMPETENCY>` — exactly one of the five (below).
 - `<status>` — `open` | `folded` | `rejected`. A **newly emitted delta is `open`**.
-- `<learning>` — the insight. The `- [COMPETENCY · status]` tag line comes **first**; `(evidence: …)` **closes** the delta.
+- `<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>` 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`).
 
-A long learning may wrap — `add.py check` joins continuation lines, so this is **one** delta:
+A long learning may wrap — `add.py check` joins continuation lines into **one** delta:
 
 ```
 - [SDD · open] the export endpoint must reject a tenant-scoped token used cross-tenant,
@@ -34,18 +35,16 @@ A long learning may wrap — `add.py check` joins continuation lines, so this is
 | `TDD` | Test | how we prove correctness — a missing scenario, a flaky or hollow test |
 | `ADD` | AI/build | how the AI builds — a harness, prompt, or convention that helped or hurt |
 
-If a learning touches two, ask "which competency, once updated, would have PREVENTED this?" — that is its home. Split separate learnings into separate deltas; never tag one twice.
+If a learning touches two, ask "which competency, once updated, would have PREVENTED this?" — that is its home. Split separate learnings; never tag one twice.
 
 ## Status lifecycle
 
 ```
-emit (OBSERVE)        human review (foundation-update-loop)
-   open  ───────────▶  folded     (learning merged into PROJECT.md; version bumps)
-         └──────────▶  rejected   (considered and deliberately NOT consolidated — trail kept)
+emit (OBSERVE)        human review
+   open  ───────────▶  folded     (merged into PROJECT.md; version bumps)
+         └──────────▶  rejected   (deliberately NOT consolidated — trail kept)
 ```
 
-A `rejected` delta is left in place (not deleted) so "we saw this and chose not to act" stays auditable.
-
 ## Reject codes
 
 <reject_codes>
@@ -58,8 +57,8 @@ A `rejected` delta is left in place (not deleted) so "we saw this and chose not
 
 ```
 - [DDD · open] the account model conflated org and workspace (evidence: scenario_cross_tenant_read failed)
-- [TDD · open] no scenario covered a deleted tenant's dangling sessions (evidence: review note, PR thread)
-- [ADD · open] the scaffold's allow-list missed the tenancy lib, slowing build (evidence: build log retry)
+- [TDD · open] no scenario covered a deleted tenant's dangling sessions (evidence: review note)
+- [ADD · open] the scaffold's allow-list missed the tenancy lib, slowing build (evidence: build log)
 ```
 
-At the next foundation update the human consolidated the DDD and TDD deltas (→ `folded`) and rejected the ADD one (→ `rejected`). The foundation got sharper; nothing was silently lost.
+At the next update the human consolidated DDD+TDD (→ `folded`) and rejected ADD. Sharper foundation; nothing lost.

package/skill/add/design.md

@@ -2,13 +2,11 @@
 
 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. It is loaded on demand (like `advisor.md` / `confidence.md`);
-the engine never runs it for you.
+image — *before* any implementation. Loaded on demand; the engine never runs it for you.
 
-Design before code is the UDD half of the method. The token + component foundation a UI project
-draws from already exists — `tokens.json` (the compact-DTCG dialect, `udd-tokens.md`),
-`catalog.json` + `prototypes/<name>.json` (`udd-catalog.md`). This loop fills that foundation
-for a feature and earns the human's sign-off on the look before build.
+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.
 
 ## The loop — five beats
 
@@ -16,71 +14,73 @@ for a feature and earns the human's sign-off on the look before build.
 design-intake  →  review-domain  →  research-components  →  wireframe  →  render-capture-confirm
 ```
 
-Run the beats in order. Each feeds the next; the last ends at a human design-confirm.
+Run the beats in order; the last ends at a human design-confirm.
 
 ### 0 · design-intake
-Before you read the domain, interview the human on **four design axes** — so the look is
-*directed*, not guessed. Ask each, show the options, record the pick:
+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:
 
-- **FIDELITY** — how far this design goes: *lo-fi wireframe* · *hi-fi mockup* · *production*.
-  Recorded **intent** that **informs** how far the later beats render (it is not an engine gate).
+- **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.
-- **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`).
+- **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`).
 
-Record the answers **before** review-domain, at both levels: project **defaults** in DESIGN.md's
-`## Design intake` section; per-screen **overrides** (only the deltas) in the per-feature design
-note (the `prototypes/<name>.json` companion). Show-before-ask — confirm the picks, never assume.
+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.
 
 ### 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 and the **regions** each screen holds. Map each domain entity to a *presentational*
-component (it shows state; it does not own a domain decision). The screen list + per-screen
-regions are this beat's output, grounded in the domain you just read.
+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.
 
 ### 2 · research-components (reuse before you invent)
-Check `catalog.json` **first** and **reuse** the components already there — that keeps screens
-consistent. Research a reference UI only to fill a **genuine gap**, and propose a **new** catalog
-component for that gap with a **cited** reference. Reuse before invention; a new component is the
-exception, not the default.
+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.
 
 ### 3 · wireframe
-Draw a **low-fi**, **structural** layout for each screen — regions and component slots, no
-styling, no color. This is the cheapest artifact that shows the *expected layout*, so the human
-can correct structure before a pixel is styled. Confirm the wireframe, then move on.
+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.
 
 ### 4 · render-capture-confirm
-Render the screen as a **self-contained HTML mock** — the project's component library via CDN,
-bound to `tokens.json` (resolved to CSS variables), composed from the **reusable per-component
-kit** (one token-bound partial per catalog component), populated with realistic **mock** data.
-**Capture** a real image (a headless screenshot) and present that image to the human for
-**design-confirm** — show-before-ask, **before build**. On confirm, record the layout back to
-`prototypes/<name>.json` + `catalog.json`, save the captured image to
-`.add/design/captures/<name>.<ext>`, and **attach or mention it in the feature's `TASK.md`** —
-so the screen the human approved is traceable from the task that builds it. The HTML mock is the
+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, match the screen to the seeded UI personas
+(`.add/personas/*` covering visual design and UX research) 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.
+
 ## Tool-agnostic capture
 
-How you render and capture is **your** choice: a headless browser (Playwright / Puppeteer), an
-`html2image`-style renderer, a browser-automation skill, a design tool, or a hosted screenshot
-service. The recommended default is the self-contained HTML mock above, captured headless,
-because it needs no app build yet still wears the project's real tokens and component vocabulary.
-For a project that renders json-render, the recommended default is **`@json-render/image`**
-(Satori → PNG/SVG, no browser). The captured image is **design-confirm evidence** the human
-approves; the engine never renders. This keeps the loop tool-agnostic and the method renderer-free.
+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>`** and are attached/mentioned in the
-feature's `TASK.md`. `add.py check` raises a never-red `missing_capture` WARN for any prototype
-under `.add/design/prototypes/` that still lacks a capture — a nudge to render + confirm it.
+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.
 
-The loop **binds** the existing UDD contracts **read-only**: `tokens.json`, `catalog.json`, and
-`prototypes/<name>.json` are read and composed, never reshaped — the `prototypes/<name>.json`
-data contract stays **unchanged** (a change to it is a change request, not a design step). And
-**identity** values — brand color, palette, typeface — stay **human-owned**: surface them for the
-human to decide, never auto-pick a brand value (`udd-tokens.md`).
+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
 
@@ -96,6 +96,9 @@ human to decide, never auto-pick a brand value (`udd-tokens.md`).
   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

package/skill/add/fold.md

@@ -1,24 +1,24 @@
 # Consolidating lessons — how the foundation self-improves
 
-This **closes the loop**. `deltas.md` lets a task EMIT lessons (`open` lessons learned in OBSERVE); retrospective consolidation gathers the confirmed ones and writes them into a **versioned foundation**, so `DDD · SDD · UDD · TDD · ADD` sharpen across milestones.
+This **closes the loop**. `deltas.md` lets a task EMIT `open` lessons in OBSERVE; consolidation gathers the confirmed ones into a **versioned foundation**, so `DDD · SDD · UDD · TDD · ADD` sharpen across milestones.
 
-`add.py fold` is **judgment-free**: it only TRANSCRIBES each lesson's own captured text into its routed home and bumps the version. It NEVER composes or merges prose, and it **never self-approves** a consolidation — running the command records the human's confirmation. Deciding WHICH lessons to keep, and polishing raw transcribed bullets into lean one-screen prose, remain the human's work — the latter via the **compaction door** (`compact-foundation.md`).
+`add.py fold` is **judgment-free**: it only TRANSCRIBES each lesson's captured text into its routed home and bumps the version — it never composes prose and **never self-approves** (running the command records the human's confirmation). Choosing which lessons to keep, and polishing raw bullets into lean prose (the **compaction door**, `compact-foundation.md`), stay the human's work.
 
 ## When to consolidate
 
-At **milestone close** (the natural version bump), or **on demand** when open lessons pile up. One run of `add.py fold` = ONE consolidation session: bumps `foundation-version` exactly once and stamps every resolved lesson with that version.
+At **milestone close**, or **on demand** when open lessons pile up. One `add.py fold` = ONE session: one `foundation-version` bump, every resolved lesson stamped with it.
 
 ## The ritual
 
 1. **Gather** — `add.py deltas` reads every task's OBSERVE block for lessons still `open`.
-2. **Confirm** — decide which to keep; a lesson you do NOT want is marked `rejected` and left in place. Running `add.py fold` over the rest IS your confirmation.
+2. **Confirm** — mark any lesson you do NOT want `rejected` (left in place); running `add.py fold` over the rest IS your confirmation.
 3. **Write** — `add.py fold [--task <slug>] [--comp <TAG>]` performs the mechanical write atomically:
    - flips each selected `open` lesson to `folded` and stamps it `[folded foundation-version N]`;
-   - transcribes each lesson VERBATIM as one bullet at the TOP (newest-first) of its routed section;
-   - prepends one row to §Key Decisions (date · what · why · outcome);
+   - transcribes each VERBATIM as one bullet at the TOP (newest-first) of its routed section;
+   - prepends one §Key Decisions row (date · what · why · outcome);
    - bumps `foundation-version` by one.
    Validate-all-then-write: if any precondition fails the command writes NOTHING.
-4. **Propose & polish** — transcribed bullets are RAW; afterward consolidate/merge into lean prose (append-only, newest-first) via the compaction door.
+4. **Propose & polish** — raw bullets later merge into lean prose (append-only, newest-first) via the compaction door.
 
 ## Consolidation routing
 
@@ -29,15 +29,14 @@ At **milestone close** (the natural version bump), or **on demand** when open le
 | `UDD` | `PROJECT.md` §Users | transcribed bullet at the top |
 | `TDD` | `CONVENTIONS.md` §Method learnings | transcribed bullet |
 | `ADD` | `CONVENTIONS.md` §Method learnings | transcribed bullet |
+| `persona:<slug>` | `.add/personas/<slug>.md` §Critical Rules / §Success Metrics | dated bullet at top; schema stays conformant |
 
-Every consolidation ALSO prepends one row at the TOP of `PROJECT.md` §Key Decisions: date · decision · why · outcome.
+A `persona:<slug> · <hint>` lesson routes into that persona doc, not a foundation file; it is still flipped `folded` and still bumps the version once (`deltas.md`).
 
 ## Status transitions & version
 
-- **confirm**: `open` → `folded` (text transcribed at top of routed target, newest-first).
-- **decline**: `open` → `rejected`, left in place — "we considered and chose not to act" stays auditable.
-- Consolidation is **append-only (newest-first)**: PREPENDS new bullets/rows, never silently rewrites — EXCEPT via the recorded compaction door.
-- Each `add.py fold` run **bumps** `foundation-version:` in `PROJECT.md` by one (monotonic int).
+- **confirm** `open` → `folded`; **decline** `open` → `rejected` (left in place — auditable trail).
+- Consolidation is **append-only (newest-first)** — PREPENDS, never silently rewrites, EXCEPT via the recorded compaction door.
 
 ## Reject codes
 
@@ -45,17 +44,20 @@ Every consolidation ALSO prepends one row at the TOP of `PROJECT.md` §Key Decis
 - `no_open_deltas` — nothing is `open` in the selected scope. Version is NOT bumped.
 - `missing_route_section` — a lesson routes to a foundation section that does not exist. Add the section header, then re-run. Nothing is written.
 - `no_foundation_version` — `PROJECT.md` carries no parseable `foundation-version:` marker to bump.
+- `missing_persona_target` — a `persona:<slug>` lesson with no `.add/personas/<slug>.md`. Fail-closed: nothing written, no bump. Seed the persona first.
+- `persona_section_unroutable` — the section hint is not `critical-rule` or `success-metric`. Nothing is written.
+- `persona_clobber_forbidden` — INVARIANT: a persona consolidation prepends only; it never drops existing content or breaks the schema.
 </reject_codes>
 
-Convention-era codes `unconfirmed_fold` and `unroutable_delta` are **retired**: invoking `add.py fold` IS the confirmation; a missing destination surfaces as `missing_route_section`.
+Retired: `unconfirmed_fold` · `unroutable_delta` — running `add.py fold` IS the confirmation; a missing destination is `missing_route_section`.
 
 ## Worked example
 
 The `competency-deltas` task closed its OBSERVE with two lessons:
 
 ```
-- [ADD · open] dogfood .add/tooling template can silently diverge from canonical (evidence: md5 mismatch this build)
-- [TDD · open] structural tests guard canonical artifacts but not their dogfood twins (evidence: scope-loop note + this build)
+- [ADD · open] dogfood .add/tooling can silently diverge from canonical (evidence: md5 mismatch)
+- [TDD · open] structural tests guard canonical artifacts but not their dogfood twins (evidence: this build)
 ```
 
-The human keeps both and runs `add.py fold`. Routing transcribes each into `CONVENTIONS.md` §Method learnings, prepends a §Key Decisions row, flips them to `folded` with `[folded foundation-version N]`, and bumps `foundation-version` 1 → 2 — all in one atomic write.
+The human runs `add.py fold`: both transcribe into `CONVENTIONS.md` §Method learnings, a §Key Decisions row is prepended, both flip to `folded`, and `foundation-version` bumps 1 → 2 — one atomic write.

package/skill/add/intake.md

@@ -6,8 +6,9 @@ Before a task exists, ADD turns a raw request into correctly-sized, versioned sc
 
 ## Interview before you size
 
-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
+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.
@@ -61,7 +62,7 @@ goal/body, the new TASK.md, or a note in the affected TASK.md — never in state
 Some requests decompose into **N>1 milestones of the same line** — a roadmap, not one milestone.
 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. (AI proposes.)
+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.
 3. **Create** all N on confirm — the first with `add.py new-milestone <slug>` (active), the rest

package/skill/add/loop.md

@@ -57,8 +57,7 @@ When every task is done but the goal is not, `add.py status` shows
 
 When a deepened verify finds a criterion unmet on a task already marked done,
 `add.py reopen <task> --to <phase> --reason "..."` returns it to the flow with a recorded
-reason and a reset gate. Deciding WHEN to fire it — because a goal criterion is unmet — is this
-loop's job.
+reason and a reset gate — fired by this loop's judgment, not the engine's.
 
 ## The reactivation residual (deferred)