@pilotspace/add 1.16.1 → 2.0.0

package/skill/add/SKILL.md

@@ -1,16 +1,13 @@
 ---
 name: add
 description: >-
-  ADD (AI-Driven Development) — a minimal, state-tracked workflow for building
-  software where the AI writes the code and the human owns direction and
-  verification. Drives every feature through one lean TASK.md: Specify →
-  Scenarios → Contract → Tests → Build → Verify → Observe, with red/green TDD
-  built in. Use this skill whenever working in a repo that has a `.add/`
-  directory, when the user says "add", "start a task", "next phase", "specify
-  this feature", "ADD method", or "AI-driven development", or when scaffolding a
-  new feature and you want spec/tests-first discipline instead of vague-prompt
-  coding. Also use it to resume work across sessions (it reads `.add/state.json`
-  so you never re-read the whole repo).
+  ADD (AI-Driven Development) — a minimal, state-tracked workflow: the AI writes
+  the code, the human owns direction and verification. Drives every feature through
+  one lean PLAN.md: Specify → Scenarios → Plan → Tests → Build → Verify → Observe,
+  red/green TDD built in. Use whenever a repo has `.add/`, or the user says "add",
+  "start a task", "next phase", "specify this feature", "ADD method", "AI-driven
+  development", or wants spec/tests-first discipline over vague-prompt coding. Also
+  resumes work across sessions via `.add/state.json` (never re-read the whole repo).
 user-invocable: true
 category: workflows
 keywords: [add, aidd, ai-driven-development, spec-first, tdd, contract, scenarios, verify, milestone, task-orchestration]
@@ -18,138 +15,111 @@ argument-hint: "status | init | continue | --todo <text> | [describe new short g
 license: MIT
 metadata:
   author: add
-  version: "1.8.0"
+  version: "2.0.0"
 ---
 
-# ADD — the orchestration engine
+# ADD — memory · judgment · conscience (the agent is the hands)
 
-You are the orchestrator. ADD keeps the AI fast *and* safe by fixing direction
+You turn intent into the right task, then drive it. ADD keeps the AI fast *and* safe by fixing direction
 (spec, scenarios, contract, failing tests) **before** the build, and trusting the
-result through passing evidence rather than a plausible-looking diff.
+result through passing evidence, not a plausible diff.
 
-**One file = one task.** Each feature is one `.add/tasks/<slug>/TASK.md` — a §0 ground
-preamble plus seven step sections, filled top to bottom. The Python tool tracks where you
-are so context never rots across sessions.
+**One task = one atomic node.** Each feature is one `.add/tasks/<slug>/PLAN.md`; its frozen §3
+(contract · scope · Target) is the interface neighbor nodes depend on — edges compile from the
+milestone, `graph` renders the DAG, `locate` walks a failure to its node. Shard context beside it.
 
-**The `--todo` fast-path.** When the skill ARGUMENTS begin with `--todo`, skip orienting: route to
-`add.py todo` and print its output — `--todo <text>` captures · `--todo` lists open todos ·
-`--todo --done <id>` closes (engine errors surfaced verbatim) — then STOP.
+**The `--todo` fast-path.** ARGUMENTS begin with `--todo`? Skip orienting: run `add.py todo`, print
+it — `--todo <text>` captures · `--todo` lists · `--todo --done <id>` closes — then STOP.
 
 ## Always start here (orient — do not skip)
 
-Engine: `.add/tooling/add.py` · book: `.add/docs/`. Ensure the engine is in the project first:
+Engine: `.add/tooling/add.py`. Ensure it is in the project:
 
-- It exists → go straight to `status` below.
-- It does NOT (ADD installed as a Claude Code plugin — engine + book ride in the plugin) →
-  materialize once: `node "${CLAUDE_PLUGIN_ROOT}/bin/cli.js" init --no-skill`. That drops
-  `.add/tooling/` (engine) + `.add/docs/` (book) + the agent-agnostic `CLAUDE.md` block — like an
-  npm/pip install; the skill stays in the plugin, nothing duplicated.
+- It exists → go to `status` below.
+- It does NOT (a plugin install) → materialize once:
+  `node "${CLAUDE_PLUGIN_ROOT}/bin/cli.js" init --no-skill` — drops `.add/tooling/` (engine)
+  + the agent-agnostic `CLAUDE.md` block; the skill stays in the plugin.
 
-Find the resume point from the tool, not by re-reading the repo:
+Resume from the tool, never re-read the repo — mid-flow, trust each verb's
+`next:` footer:
 
 ```bash
-python3 .add/tooling/add.py status
+python3 .add/tooling/add.py status --brief
 ```
 
-`status` names two files to read when orienting: `.add/PROJECT.md` (the foundation) and `.add/SOUL.md`
-(your **voice** — tone, style, what keeps the human's trust; read it each session — human-owned and
-self-improving via the `soul-self-improve` path). Then branch on state:
-
-- **No `.add/state.json` yet** (`status` says `no .add/ project found`) → **autonomous setup**: if
-  `.add/.intent` exists, read it — the installer's one-line first-build intent (a NOTE, never an init
-  trigger) — to seed your kickoff; then YOU run init — `add.py init --name "<inferred>" --stage <picked>
-  --await-lock` — and read `phases/0-setup.md` to draft the foundation + §1–§3 through to the human
-  baseline approval.
-- **A task is active** → open its `.add/tasks/<active>/TASK.md`, read the `phase:` marker, load the
-  matching `phases/<n>-<phase>.md`. Work *only* that phase.
+Then read the foundation map `add.py status --foundation` (`--all` full) + `.add/SOUL.md` (**voice**). Then branch on state:
+
+- **No `.add/state.json` yet** (`status` says `no .add/ project found`) → **autonomous setup**: read
+  `.add/.intent` if present (the installer's first-build intent — a NOTE, never an init trigger), then
+  YOU run `add.py init --name "<inferred>" --stage <picked> --await-lock` and drive setup via
+  `phases/direction.md` (brownfield repo → map it silently, `adopt.md`) — to the human baseline `lock`.
+- **A task is active** → open its `.add/tasks/<active>/PLAN.md`, read the `phase:` marker, work that
+  beat per the loop below.
 - **No active task** → first SIZE the request (Intake below), then `add.py new-task <slug> --title "..."`.
 
-**Quick ref** — `status` resume · `init` bootstrap · `advance` continue · `gate PASS` at verify.
-**Flag mode** — two human-owned settings (never auto-picked): **fast** (task) · **auto** (mode).
-- **fast** — `new-task --fast`: minimal template, freeze-gated; a milestone-free `--fast` task is a
-  blessed standalone low-ceremony lane. Jot ideas first with `add.py todo "<text>"` (then `todo` to
-  list · `todo --done <id>`).
-- **auto** — `autonomy: auto` (default) auto-gates verify on evidence; lower the autonomy level with
-  `add.py autonomy set conservative|manual` for a human gate · `new-milestone --await-confirm`
-  confirm-gates a milestone's tasks.
+**Quick ref** — `status --brief` resume · `advance --fill <draft>` writes · `status --section <n>` one §body · `gate PASS` at verify.
+**Flag mode** — ONE atomic template serves every task (no lanes); flags are header declarations.
+- **gate_mode** — headless/agent-crossed freeze: declare `gate_mode: ai-plan-verify` in the PLAN.md
+  header + fill the §3 AI-verify record; security|data|architecture stay human-frozen (unstrikeable).
+- **auto** — `autonomy: auto` (default) auto-gates verify on evidence; `add.py autonomy set
+  conservative|manual` restores a human gate · `new-milestone --await-confirm` confirm-gates its tasks.
 
 ## Intake — size a request before creating scope
 
-Classify a raw request BEFORE any milestone or task: read `intake.md`, place it in one bucket —
-`new-major` · `sub-milestone` · `task` · `change-request` — propose `{ bucket, rationale, command }`;
-the human confirms. A question or unsharp intent? **Interview before you size** (`intake.md`). Once
-`new-major`/`sub-milestone`, draft the `MILESTONE.md` (goal · scope · exit criteria · breadth-first
-tasks) — read `scope.md`. Create it `new-milestone --await-confirm`, then `milestone-confirm <slug>`
-gates `new-task` until the parent is agreed. For `task`/`change-request`: `add.py new-task` then the
-first phase guide.
-
-## The flow and which file to load
-
-Load the phase guide **only for the phase you are in** (progressive disclosure):
-
-| Phase | Guide | Produces (TASK.md section) | Who leads |
-|-------|-------|----------------------------|-----------|
-| setup | `phases/0-setup.md` | `.add/` + living docs + first §1–§3 + `SETUP-REVIEW.md` | AI drafts → **human locks** (the baseline approval) |
-| ground | `phases/0-ground.md` | §0 GROUND map (real files · symbols · the anchors §3 cites) | **AI** (the §0 preamble — no new gate) |
-| specify | `phases/1-specify.md` | §1 rules + ranked lowest-confidence flag | AI drafts (co-specify)† |
-| scenarios | `phases/2-scenarios.md` | §2 Given/When/Then | AI drafts† |
-| contract | `phases/3-contract.md` | §3 frozen shape | AI drafts → **human approves once** (the decision point)† |
-| tests | `phases/4-tests.md` | §4 + red suite in `tests/` | AI drafts† |
-| build | `phases/5-build.md` | code in `src/`, tests green | **AI** |
-| verify | `phases/6-verify.md` | §6 checks + gate record | **AI auto-gates on evidence**; human on residue/security‡ |
-| observe | `phases/7-observe.md` | §7 spec delta | human + AI |
-
-† **The specification bundle (v7).** §1–§4 are one bundle; the human gives **one approval at the
-contract freeze**, lowest-confidence-first — see `run.md`.
-‡ **Verify auto-gate (v6–v7).** Under `autonomy: auto` (default) a run may auto-PASS on complete
-evidence (*auto-resolved* — an explicit PASS, not a skip). **Security always escalates** (HARD-STOP);
-so do concurrency / architecture residue and a lowered autonomy level (`conservative` / `manual`) — `run.md`.
-
-At every human decision point (intake · bundle approval · gate · milestone close) follow
-`report-template.md`: open with the banner then the ARC (goal · done · plan, engine-sourced), then PLAN/SHAPE → SUMMARY →
-FLAGS → DECIDED → EVIDENCE → APPROVE → NEXT; show-before-ask; never pre-stamp; the question is a summary, never the artifact.
-
-In **observe**, emit **lessons learned** tagged by which of the five (`DDD · SDD · UDD · TDD · ADD`)
-they improve (write them `open`; the human consolidates into `PROJECT.md`) — grammar + lifecycle in
-`deltas.md`. At milestone close (or on demand) the retrospective consolidation gathers confirmed deltas
-into a versioned foundation — `fold.md`; then (separately, after) compact each foundation spec's stable
-tail — `compact-foundation.md`. Observe also tunes your voice: propose a confirmable voice delta that,
-once the human confirms, rewrites `SOUL.md` (the human is the only writer) — `soul.md`.
+Classify a raw request BEFORE any scope: read `intake.md`. Too small for scope → the
+**inline lane** (diff + `delta-append` receipt; security·data·architecture escalates). Else
+one bucket — `new-major` ·
+`sub-milestone` · `task` · `change-request` — propose `{ bucket, rationale, command }`; the human
+confirms. Unsharp intent? **Interview before you size** (`intake.md`). For a milestone bucket draft
+`MILESTONE.md` (goal · scope · exit criteria · breadth-first tasks — `phases/direction.md`), then
+`new-milestone --await-confirm` + `milestone-confirm <slug>` (gates `new-task`; confirm compiles Tasks to the DAG → new-task inherits each node's depends-on). For
+`task`/`change-request`: `add.py new-task`, then beat 1 above.
+
+## The 3-beat loop (inline — this file IS the loop; references load on demand)
+
+Every task is three beats (seven steps, folded), three engine calls, ONE human decision:
+
+1. **DIRECTION** — load the domain-fit persona (seed via add persona-mode if none), then draft
+   the whole bundle top-to-bottom in PLAN.md: §1 rules + ranked ⚠ flag (co-specify) ·
+   §2 scenarios · §3 PLAN (grounding → frozen contract shape → build-strategy + Scope + Target) · §4 red suite
+   (run it — red for the RIGHT reason; fill each bullet's `covers:` clause key). Then the ONE approval, presented
+   lowest-confidence-first: `add.py freeze --by "<name>" --cross` (a setup session's baseline `lock`
+   IS this approval).
+2. **BUILD** — code in `src/` until every red is green; change no test, no frozen contract; stay
+   inside the §3 Scope. A test OUTSIDE your suite failing? `add.py locate path::test` names the
+   owning node, the failure class, the frozen §3 clause it proves, and who re-verifies if a
+   settled contract must move.
+3. **VERIFY** — confirm evidence · 3 lenses (**security always HARD-STOP**) · earned-green
+   refute-read · then `add.py gate PASS --target-hit yes|partial|no` (from build it compound-crosses; under `autonomy: auto` a
+   run auto-PASSes on complete no-residue evidence — *auto-resolved*, an explicit PASS, never a
+   skip; residue or lowered autonomy → human — `run.md`).
+
+Stuck or deep? References, on demand — optional: `phases/direction.md` ·
+`phases/build.md` · `phases/verify.md` · opaque term? `terms.md`. Delegating? Spawn
+the roster agent; it loads its own references (you read ONLY this file).
+
+At each decision point (intake · bundle · gate · close) the fitting persona OWNS the gate report (banner then the ARC) —
+`gate-udd.md` holds the principles: CONVEY decision + ARC (engine-sourced) · shape · flags (lowest-first) ·
+evidence · a guided APPROVE; the persona owns the form, never the four floors (security stays HARD-STOP) — the question is a summary, never the artifact.
+Read once per session.
+
+Emit **lessons learned** tagged by which of the five (`DDD · SDD · UDD · TDD · ADD`)
+they improve — **in-flight**: `add.py delta-append <dd> "<lesson>"` → its living spec in
+`.add/specs/` (grammar: `deltas.md`).
+The living specs ARE the foundation; the close counts what §7 still holds open. Observe also
+tunes your voice: a confirmable delta the human confirms rewrites `SOUL.md` (the human is the only
+writer) — `deltas.md`.
 
 ## Beyond the bundle — load on demand
 
-- **§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 — `streams.md`. Delegate one piece of your plan to a subagent — prefer the named roster
-  (`add-design`/`add-build`/`add-verify`/`add-persona`/`add-advisor`) over an ad-hoc spawn; when to
-  spawn, the prompt template, the tier — `advisor.md`. Self-score a draft (0–1 across six dimensions, refine if any < 0.9)
-  — `confidence.md`. Both advisory; the engine never spawns.
-- **Small, low-risk task**, less ceremony → the **fast lane**: `new-task --fast` scaffolds the minimal
-  `TASK.fast.md`, bundle approved in one freeze — `phases/fast-lane.md`. Floor held (frozen contract ·
-  red test · verify gate; freeze-gated under any milestone). Collapse, never skip; opt-in.
-- **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`.
-- `status` prints **`MVP covered → propose graduation`** (every milestone done AND stage criteria all
-  `[x]`) → `graduate.md`: `graduation-report` → co-specify interview → draft ≥1 production milestone →
-  human confirm → then `stage production`. Guarded (`stage_no_roadmap`); the FINAL step, never a bare flip.
-- `status` prints **`→ releasable: N milestone(s) closed since last release`** → `release.md` (the 5th
-  scope level): `release-report` → draft notes from the consolidated deltas → meet the readiness floor
-  (security HARD-STOP is un-forceable) → human confirms → `add.py release <version>` records the cut
-  (CHANGELOG + `RELEASES.md` ledger + milestone attribution). The engine records; the human runs the
-  tag/publish/deploy. A release bundles ≥1 milestone, orthogonal to stage.
-- **Monorepo / multi-repo** — a milestone spans more than one green bar (a BE + its FE) → the
-  **component pillar**: declare components in `.add/components.toml`, gate each task on its component's
-  green-bar, freeze cross-component contracts (`produces:`/`consumes:`), hold the FE until the BE
-  freezes, `federate pull` across repos — `components.md`. Opt-in; no components = today.
-- **Project-fit personas** — the **persona loop** seeds `.add/personas/<slug>.md`, grows them via
-  observe→delta→consolidate, applies them in design/streams/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 —
-  `sensitivity.md`. Security is a human floor in every tier; only `mechanical` is advisor-gatable — see `advisor-gate-relax` in `run.md`.
+One trigger = one guide — full prose: `beyond.md`; load only when a trigger fires:
+
+- §3 FROZEN → auto-gated run `run.md` · subagent roster + pipelines (agent-call-preferred,
+  the default execution mode) → `phases/verify.md` · self-score → `phases/direction.md`
+- UI/experience surface → UDD loop `design.md`
+- milestone goal unmet at `milestone-done` → `loop.md`
+- graduation · release · monorepo green-bars → persona-owned playbooks, `beyond.md` ·
+  the persona loop (`.add/personas/`) → `docs/18-personas.md` · `sensitivity:` + `advisor-gate-relax` → `phases/verify.md`
 
 ## Non-negotiable rules (from the method)
 
@@ -162,31 +132,27 @@ once the human confirms, rewrites `SOUL.md` (the human is the only writer) — `
    A real change is a *change request* back to Specify.
 4. **No silent skips.** Every Verify ends in exactly one recorded outcome: `PASS`, `RISK-ACCEPTED`
    (signed, non-security only), or `HARD-STOP`. A security finding is always `HARD-STOP`.
-5. **Ask, don't guess.** If a requirement is unclear, stop and ask the user.
 </constraints>
 
-## Advancing
-
-After a phase's exit gate is met, advance the state (this also syncs the TASK.md marker):
+## Advancing — the 3-call walk
 
 ```bash
-python3 .add/tooling/add.py advance            # next phase of the active task
-python3 .add/tooling/add.py gate PASS          # at verify: records PASS, marks done
-python3 .add/tooling/add.py use <slug>         # switch the active task (e.g. across parallel streams)
+python3 .add/tooling/add.py new-task <slug> --title "..."   # born at direction
+python3 .add/tooling/add.py freeze --by "<name>" --cross    # the ONE approval -> build
+python3 .add/tooling/add.py gate PASS                       # verify recorded, task done
+# add.py advance = step-wise alternative · add.py use <slug> = switch tasks
 ```
 
 ## Depth by stage
 
-The steps never change; their depth does (read the stage from `add.py status`):
+The steps never change; their depth does (stage from `add.py status`):
 
-- **prototype** — run light; code is throwaway; design/experience is the point.
-- **poc** — run contract/tests/build deeply on the single riskiest slice only.
+- **prototype** — light; throwaway code; design/experience is the point.
+- **poc** — contract/tests/build deep on the single riskiest slice only.
 - **mvp** — full flow, narrow scope, light observation.
-- **production** — every step at full rigor + the observe loop. Reach it via the `graduate.md`
-  orchestration when status shows `MVP covered → propose graduation`, never a bare `stage production` flip.
+- **production** — full rigor + the observe loop; reached via the graduation playbook
+  (`beyond.md`), never a bare `stage production` flip.
 
 ## The method rationale
 
-The full method (the *why* behind every rule) is the AIDD book in `.add/docs/`. When a phase decision is
-genuinely unclear, read the linked chapter — each phase guide points to its chapter. Do not duplicate
-the book here; load it on demand.
+The *why* lives in the AIDD book — https://pilotspace.github.io/ADD/ (the `docs/…` chapters the guides cite). Read it when a decision is genuinely unclear; never duplicate it here.

package/skill/add/adopt.md

@@ -35,6 +35,34 @@ Fill each living-doc file in `.add/` from what the code shows — **ask nothing*
 2. **Tag every drafted decision `evidence-grounded` vs `guessed`.** A line you read from the code is *evidence-grounded* (cite the file). A line you inferred because the code was silent is *guessed*. The human's single baseline approval is only honest if they can see which is which — the guesses are what they actually need to check. (The tags feed `SETUP-REVIEW.md`.)
 </constraints>
 
+## Setup review — the one page the human signs
+
+Both setup paths (this brownfield map AND the greenfield draft, `phases/direction.md`) end at
+the same single human gate, and `SETUP-REVIEW.md` is that page: every decision you made while
+drafting the foundation, first-scope, and first contract, ordered **lowest-confidence-first** so
+the riskiest guesses meet the human's eye first. The engine never reads it — `add.py lock` is
+judgment-free; the human *reading* this page is the review. Write ONE artifact at
+`.add/SETUP-REVIEW.md`, beside `PROJECT.md` (never clobber a human-edited one — append/update):
+
+```markdown
+# SETUP REVIEW — <project>
+
+<stage> · <brownfield | greenfield> · drafted by <model> @ <date>
+
+| # | Decision | Lands in | Tag | Why / Evidence |
+|---|----------|----------|-----|----------------|
+| 1 | <the drafted decision> | PROJECT.md \| scope \| first-contract | `guessed` | <the inference + why you had to guess> |
+| 2 | <…> | <…> | `evidence-grounded` | <cite the source file/line you read it from> |
+
+Sign: confirm in chat → the agent runs `add.py lock --by "<name>"` (typing it yourself works too)
+```
+
+The two rules that make it honest: rows sort by confidence **ascending** — a `guessed` row
+always floats above an `evidence-grounded` one (the top of the table is what the human must
+actually challenge); and EVERY row is tagged with the shared vocabulary above (`guessed` = the
+repo was silent, state the inference; `evidence-grounded` = cite the file). Rows are numbered
+for reference at the gate. Present it lowest-confidence-first, not field-by-field.
+
 ## Where it ends — the baseline approval
 
 Brownfield onboarding draws no per-step approvals: map the foundation, draft the first milestone's scope and first task's candidate specification bundle, then present it all at **one** human gate. The human reviews decisions (`guessed` first) and confirms; you run the lock:

package/skill/add/beyond.md

@@ -0,0 +1,36 @@
+# 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
+  (the ONE `add` agent — mode: direction/build/verify/persona/advise) is agent-call-preferred, the
+  default execution mode 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>` 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, 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.
+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.