@pilotspace/add 1.14.0 → 1.16.0

package/skill/add/advisor.md

@@ -1,30 +1,31 @@
 # 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.
+**Prefer the named roster.** Check first whether the piece fits one of ADD's five phase specialists — `add-design` (setup–contract) · `add-build` (tests·build) · `add-verify` (verify·observe) · `add-persona` (fit-persona selection) · `add-advisor` (a consultative second opinion) — before an ad-hoc spawn; each already carries the worker contract below.
+
+## 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 +34,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 +56,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/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

@@ -50,15 +50,14 @@ When every task is done but the goal is not, `add.py status` shows
    - **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) and
-   render as a guided choice (recommended next move + described alternatives).
+   Present the close via `report-template.md` — open with the ARC (goal · done · plan),
+   render as a guided choice — **before `milestone-done`/`archive-milestone` run, not after.**
 
 ## Reopen is the verb; this loop is the trigger
 
 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)
 

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

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