@pilotspace/add 1.16.1 → 2.0.0

package/skill/add/phases/direction.md

@@ -0,0 +1,280 @@
+# Direction — the whole specification bundle (setup · rules · plan · red suite) to the ONE freeze
+
+Every task drafts §1–§4 top-to-bottom, then ONE human approval crosses it into build:
+`add.py freeze --by <name> --cross`. This file is the reference depth for that span —
+SKILL.md carries the loop; read the section you're stuck in, not the file.
+
+---
+
+## Setup — first session only (autonomous draft → one baseline lock)
+
+## 1 · Zero-touch entry — you run init yourself
+
+No `.add/state.json`? Run init yourself — never tell the human to. Infer name + stage from the
+repo and **arm the baseline-approval gate** with `--await-lock`:
+
+```bash
+python3 .add/tooling/add.py init --name "<inferred from repo/dir>" --stage <prototype|poc|mvp|production> --await-lock
+```
+
+- `--await-lock` seeds an *unlocked* setup — the engine refuses build/`gate` until you `lock`; a plain `init` is grandfathered-locked (re-lock: `already_locked`).
+- name + stage are **your judgment**: throwaway → `prototype`, risky slice → `poc`, narrow → `mvp`, full rigor → `production`.
+- `init` prints your branch: `brownfield:` → existing code, map it SILENTLY (open `adopt.md`: fill each living documentation file from code, never clobber, tag `evidence-grounded` | `guessed`; ask the human nothing). No `brownfield:` → greenfield, run the 4-lens interview below.
+
+## 2 · Greenfield — the 4-lens interview: co-specify at foundation level
+
+Ask one load-bearing question per lens (only the live ones), draft, rank lowest-confidence-first:
+
+| Lens | The one question that unblocks the section |
+|------|--------------------------------------------|
+| Domain (DDD) | The 3–5 core nouns, and the one invariant that must NEVER break? |
+| Spec (SDD) | The first milestone's outcome — and what's explicitly NOT in v1? |
+| Users (UDD) | The primary user and the one job they hire this for? (or "no UI — surface is X") |
+| Decisions | What's already decided that you'd regret re-litigating? (first Key Decision row) |
+
+Rank: `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>` — tag thin answers
+`guessed`. Under `autonomy: auto`, deepen all four drives in one pass (deepens drafting, never the
+gate); capture each surfaced decision as an ADR in `PROJECT.md` **Key Decisions**.
+
+## 3 · Draft to the lock (both paths)
+
+1. **Pin invariants first — never defer.** The "never breaks" invariant + any imposed
+   run/entry contract (interpreter · port · packaging · protocol) land in PROJECT.md `invariants:`
+   NOW; every task's §3 Grounding re-states the ones it touches.
+2. **Seed, don't draft.** Fill ONLY the `goal:` line, the 4-lens seed answers, and the sections the
+   FIRST milestone touches (UI project: seed `DESIGN.md` per `design.md`; delete if no UI). Every
+   other section keeps its `<!-- living: fill on first touch -->` marker. One `generic` persona is
+   enough at setup; author per-role personas from the local teacher library
+   (`.add/personas-teacher/`) when a task first embodies the role.
+3. **Propose, then size it.** Float a kickoff suggestion (goal · flow · scenarios) for the first
+   milestone; on the human's reaction draft `MILESTONE.md` (Milestone scope drafting, below).
+4. **Create the first task and draft its bundle §1–§4** (`new-task` is allowed pre-lock; the red
+   suite must FAIL before build). Leave §3 `Status: DRAFT` — the lock is its approval; the engine
+   refuses build until you `lock` (`setup_unlocked`).
+5. **Write `.add/SETUP-REVIEW.md`** per `adopt.md`'s Setup review section: every drafted
+   decision, **lowest-confidence-first**, tagged `guessed` | `evidence-grounded`.
+
+**Run mode** — propose before the lock, confirm-to-keep, record in PROJECT.md Key Decisions:
+
+| Autonomy | Human gates |
+|----------|-------------|
+| **sequential · auto** *(default)* | contract freeze **only** — Verify auto-PASSes on evidence |
+| **sequential · manual/conservative** | contract freeze **and** every Verify — safest |
+
+One task at a time; raise the gate via `add.py autonomy set conservative --project` (or
+`init --run-mode conservative`). Need concurrency? Spawn a subagent per task to run in parallel, its
+model picked by task complexity (mid ordinary · top complex) — floor stays **one human approval per contract**.
+
+## 4 · The one human gate — the baseline approval
+
+Open the report with the ARC per `gate-udd.md`, then present `SETUP-REVIEW.md`
+lowest-confidence-first. They confirm **once** — an explicit yes; ambient agreement is not a
+confirmation. **Never self-stamp a timeout — hold, or re-ask.** On that recorded confirmation, you run:
+
+```bash
+python3 .add/tooling/add.py lock --by "<name>"
+```
+
+Typing it themselves stays the escape hatch. The lock IS the first task's contract approval —
+stamp its §3 `Status: FROZEN @ v1`, build is open.
+
+<exit_gate>
+- [ ] `.add/state.json` exists; setup seeded unlocked (`--await-lock`) then locked.
+- [ ] Seed lines filled; untouched sections carry the living marker (brownfield: evidence-grounded from code).
+- [ ] First task created; §1–§4 drafted — the red suite runs RED before build opens; `.add/SETUP-REVIEW.md` written lowest-confidence-first.
+- [ ] Human confirmed the baseline approval and `add.py lock --by` ran with their name.
+</exit_gate>
+
+---
+
+## Milestone scope drafting — a classified request into a versioned MILESTONE.md
+
+Intake CLASSIFIES (`intake.md`); this rubric fills the confirmed `MILESTONE.md` (the
+template is the SHAPE).
+`new-major`/`sub-milestone` → draft ONE MILESTONE.md · `split_required` → draft ALL N as one
+batch pass · `task`/`change-request` → no milestone (route per intake).
+**Confirm before create is the convention** — one drafting pass, nothing written until the human confirms; enforced only
+by the opt-in gate: `new-milestone <slug> --await-confirm` seeds it unconfirmed and HOLDS
+`new-task` (`milestone_unconfirmed`) until you show the filled draft and run
+`milestone-confirm <slug>`.
+
+## Position the goal FIRST — ground in assets, relate to the map
+
+1. **Ground in current assets** — the four §3 Grounding fields at milestone scope: **Touches**
+   (subsystems/files) · **Context** (docs · config · data) · **Honors** (`PROJECT.md`/
+   `CONVENTIONS.md` invariants) · **Anchors** (contracts/symbols tasks cite) — each from real
+   assets, never assumed. Record it as the milestone's `## Ground` — gathered ONCE; each task's
+   specify PROJECTS its §1 from it. Touches >1 app root (BE+FE)? weigh `.add/components.toml` now.
+2. **Relate to the map** — `add.py search <keyword>` first, then read every live + archived goal
+   (`.add/milestones/*` · `.add/archive/*`); name the relationship — *extends* X · *depends-on* Y ·
+   *overlaps* Z — in the `rationale` line.
+3. **Already delivered** by an existing milestone → reject `duplicate_goal`; route as `task` or
+   `change-request`.
+
+**Draft the sections well**: goal = ONE outcome sentence (no "and" — that is two milestones) ·
+rationale = bucket + WHY + the relationship (never in state.json) · Scope In/Out = an explicit
+deferral list (an empty Out means scope is not thought through) · shared decisions/contracts
+name the owning task · tasks breadth-first (`slug · depends-on · one line`, each one-file-sized) ·
+exit criteria observable, EVERY criterion maps to a declared task slug · `Close — ship review` +
+`Release steps` stay drafted-blank (filled at `milestone-done`/release). Brainstorm via the
+three-move co-specify (below) at milestone scope; rank assumptions lowest-confidence first (top
+1–2 get the ⚠ flag); present per `gate-udd.md` as a guided choice — fix any unmet box first.
+Rejects: `not_classified` · `dangling_criterion` · `no_milestone` · `duplicate_goal`.
+
+---
+
+## Rules (§1) + scenarios (§2) — co-specification
+
+State what the feature MUST do and MUST REJECT — zero ambiguity left to guessing. Co-specify in three moves: **Diverge** (surface the 2–3 genuine framings +
+open questions; let the user react), **Converge** (draft §1 by PROJECTING from the milestone
+`## Ground` + the request), **Validate** (present the ranked uncertainty first). If you cannot
+write the spec, you don't yet understand the feature — stop and ask. **Identity is direction, not
+default (UDD)**: brand/palette/typeface are human-owned — surface, never assume; a UI screen runs
+the design-definition loop (`design.md`).
+
+<output_format>
+- **Framings weighed** — one-line trace: `X (chosen) · Y · Z`.
+- **Must** — each required behavior. **Reject** — each refused input/situation with a **named error
+  code** (`amount <= 0 -> "amount_invalid"`). **After** — the state true once it succeeds.
+- **Boundary** — one format-variant per external input shape the tests must speak (or an explicit "none").
+- **Assumptions — lowest-confidence first** — ranked most-likely-wrong → least; the top 1–2 carry
+  `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>`.
+</output_format>
+
+§2 makes every rule checkable — one scenario per Must and per Reject:
+
+```gherkin
+Scenario: <short name>
+  Given <starting situation>
+  When <action>
+  Then <observable result>
+  And <what must remain unchanged>   # REQUIRED for every rejection
+```
+
+Then sweep the edge cases — boundary · duplicate · partial failure · concurrency · malformed input —
+one per applicable case, or rule it out on purpose. Every Then is specific and observable, never
+"then it works". Your §1 ranking feeds the bundle-level flag the human reads at the freeze.
+
+<exit_gate>
+- [ ] Framings weighed noted; every required behavior stated; every rejection has a named error code.
+- [ ] Assumptions ordered lowest-confidence first; the 1–2 `⚠` flags carry why + cost — or an honest
+      "none material" that still names the single biggest risk (never a blank "none").
+- [ ] §2: one scenario per Must and per Reject; every rejection asserts what stays unchanged; edge
+      cases covered or ruled out on purpose.
+</exit_gate>
+
+---
+
+## Plan (§3) — ground · freeze the shape · build-strategy
+
+Turn the rules + scenarios into ONE change plan and FREEZE it. Below the freeze code is disposable;
+above it the Contract does not move.
+
+### Grounding — reason it in-context (don't write an essay — `PLAN.md.tmpl`: persist the interface, not prose)
+Project from the milestone `## Ground`, then deepen only where THIS task lands. Never invent a
+file/symbol you have not opened; cite the **symbol**, not a bare line number (`l.NNN` rots; symbols
+survive), via code-navigation tools, not memory. **Persist only what the contract needs**: the
+**Anchors** it may cite (the specific symbols §3 names — it may cite ONLY these) and, optionally, a
+**Ground SHA** (the commit grounded against — the engine stamps it when the line is present).
+Everything else — what it **Touches**, the **Honors**/seams consulted, the **Issues/Risks**, the
+**Related intent** (the WHY) — you REASON now and let the frozen Contract encode; don't transcribe it
+into the file. Sweep BROAD cheaply (skim an index/map; a subagent sweep for unfamiliar ground), then
+DEEPEN on what THIS task needs. *Greenfield / first task:* grounding IS the foundation docs — an
+honest "new module, no code; honors CONVENTIONS.md §X" is complete.
+
+### Contract — freeze the external shape (HARD, tamper-guarded)
+Interfaces with inputs/outputs; shapes + persistent schema (note transactional needs). Names drawn
+from `GLOSSARY.md`; a response for **every** Reject code from §1; cites only Grounding anchors.
+Declare the measurable **Target** — the success bar the verify evidence must hit (numbers, not
+adjectives; judged at the gate with `--target-hit`). Generate a mock + contract tests so
+dependent work can start.
+
+### Build-strategy — the intended approach (SOFT: preferred; the builder self-improves, records actual at verify)
+**Scope (may touch)** — backticked path tokens; the freeze locks this. **Strategy** — ordered
+batches. **Approach / Data strategy / Pattern / Optimization stance** — the domain plan + the
+trust-least facet. **Persona** · **Spawn isolation** · **Known-problem fixes** (`SEAMS.md` traps).
+
+### The freeze — the one approval
+Present the bundle **lowest-confidence first**. Render from the card: banner → ARC → SHAPE →
+SUMMARY → FLAGS → DECIDED → EVIDENCE → APPROVE → NEXT (`gate-udd.md` = template + examples, read at
+most once per session) — **render before `FROZEN`, then record `Reported: yes`; never on a
+timeout** (`run.md`). The freeze always renders the full card. The approval freezes the Contract
+(HARD) + the Build-strategy Scope; then `Status: FROZEN @ v1 — approved by <name>`. Lane modes are
+retired — ONE atomic template serves every task; if the header still carries an optional `route:`
+line the freeze records it (audit-only — `route_unrecorded` is measured, never a refusal).
+
+<exit_gate>
+- [ ] **Grounding** — reasoned in-context; the Contract's **Anchors** resolve in the code; an optional **Ground SHA** recorded (the essay bullets are not persisted — the interface is).
+- [ ] **Contract** — versioned, `FROZEN`; contract tests pass against the mock; every name matches the glossary; every §1 rejection has a contracted response.
+- [ ] **Build-strategy** — Scope declared; batches + persona + spawn isolation named; a measurable Target set.
+- [ ] The Contract cites only Grounding anchors; the ⚠ lowest-confidence flag is surfaced.
+</exit_gate>
+
+## The freeze review checklist
+
+The human's one minute, aimed. Walk these seven before saying yes:
+
+- **⚠ flags first** — read the lowest-confidence flags; accept each knowing its cost if wrong. The engine refuses an unflagged freeze before build (`unflagged_freeze`).
+- **Intent** — does §1 say what you actually want built?
+- **Cases** — does every Must and Reject have an observable §2 scenario?
+- **Shape** — glossary names, error codes, additive vs breaking: is THIS the shape to freeze?
+- **Grounded** — does the Contract cite anchors that exist in the Grounding map? `status`/`check` surface this.
+- **Risk** — high-risk or method-defining? Require `risk: high · autonomy: conservative` in the PLAN.md header.
+- **Tests** — will §4 go red for the right reason, asserting behavior rather than internals?
+
+Reject any line → the bundle goes back to draft; the freeze stays the only gate.
+
+---
+
+## Tests (§4) — failing-first suite
+
+Run the suite now, with no implementation — **red for the right reason** (missing implementation,
+not a broken harness). A test green before code exists is testing nothing. **A test is any
+machine-checkable assertion**, not only xUnit code — a metric threshold (ML/data), a reconciliation
+query, a plan-diff (infra), a rendered-screen diff (UI). Produce: one executable test per §2
+scenario asserting **behavior, not internals** · contract-conformance tests (shapes + error
+responses) · side-effect assertions on rejection paths (`assert balance unchanged`) · a recorded
+coverage target.
+
+## Declaring where tests live
+
+§4's `Tests live in:` line is machine-read — declare paths as backticked tokens on that line: with
+no local `tests/`, `add.py report` counts test functions at the declared paths (FIRST such line only).
+`./…` → this task dir · a token with `/` → the project root · a bare name → a
+sibling of the previous token's dir. A directory counts its `*.py` files
+(non-recursive); a `.py` file counts itself. Resolved files dedupe; declared counts
+marked `†`. Paths are confined: outside the project root counts 0 — `..` traversal,
+absolute paths, and symlink escapes are never read.
+
+**Clause map + edges.** Fill each `<test_plan>` bullet's `covers:` tail — frozen with the
+bundle; `add.py locate path::test_x` walks a failure → owning node → that frozen §3 clause.
+Declare edges at creation (`--depends-on`, later `relate`; milestone-confirm compiles `## Tasks`
+rows into inherited edges) — `locate <slug>` names who re-verifies when a settled contract
+moves. Ground §3 on each parent edge's frozen §3 — the PLAN.md itself, never a summary or
+built code.
+
+<exit_gate>
+- [ ] One test per scenario, red for the right reason, asserting observable behavior; coverage target recorded.
+</exit_gate>
+
+> **Persona / Advisor / Confidence** — load the domain-fit `.add/personas/<slug>.md` (its Critical
+> Rules shape §1, its Success Metrics shape the red suite; advisory, never lowers a gate). If none
+> fits, spawn the add agent in persona mode to seed one (PROJECT.md + `.add/personas-teacher/`),
+> then load it — seed per DOMAIN, REUSE across tasks, never one per task. Canonical spawns:
+> researcher (unfamiliar domain) · risky-shape second opinion · test-author for a wide suite (the
+> advisor spawn — `phases/verify.md`); self-score the bundle below — the lowest dimension aims ⚠.
+
+## The confidence self-score
+
+Before presenting ANY drafted artifact (spec · contract · bundle · subagent verdict), self-score
+it 0–1 on six dimensions: **Completeness** (every rule/scenario/rejection covered?) · **Clarity**
+(understood without you in the room?) · **Practicality** (implementable against the real code?) ·
+**Optimization** (correctness/simplicity/cost balanced — no gold-plating, no corner cut?) ·
+**Edge cases** (failure modes, concurrency, empty/oversized inputs named?) · **Self-evaluation**
+(does it carry its own refine step?). Any dimension **< 0.9** → refine, then re-score. The lowest
+dimension is what you surface ⚠-first at the freeze; persistently low on risky scope →
+*recommend* lowering autonomy (the level stays the human's call).
+The hard rule: **advisory, never a gate** — it never auto-passes a verify, never substitutes for evidence or the
+human decision, and a self-asserted score is never recorded as something the human "agreed to".
+
+Book: `docs/03-step-1-specify.md` · `docs/05-step-3-plan.md` · `docs/06-step-4-tests.md` · `docs/10-setup-and-stages.md`.

package/skill/add/phases/verify.md

@@ -0,0 +1,160 @@
+# Verify — evidence + non-functional review (gate + the observe tail)
+
+Goal: establish trust and record an outcome. Passing tests are necessary, not
+sufficient. Fill **§6** in PLAN.md including the GATE RECORD.
+
+> **Who resolves this gate depends on the `autonomy:` header.** Under `autonomy: auto` (the default)
+> a run auto-PASSes on complete evidence with **no residue** (security · concurrency · architecture),
+> recorded *auto-resolved* with the named run as owner;
+> **security is always a HARD-STOP and is never auto-passed**. Under `conservative`, or whenever
+> residue is found, this phase is **human-led** (auto-PASS conditions: `run.md`).
+
+## Part one — confirm the evidence
+
+- [ ] All tests pass.
+- [ ] Coverage did not decrease.
+- [ ] No test or contract was altered during build.
+- [ ] The §3 Target (measurable) is hit — including any declared outcome tests can't show, confirmed by real evidence.
+- [ ] §1 rules trace to §2/§4 — an untraced rule is a coverage gap (`add.py check` warns on it).
+- [ ] every §3-cited symbol still resolves in the CURRENT tree.
+
+If any is false, stop and return to Build.
+
+## Part two — check what tests miss
+
+- **Concurrency/timing** — correct when two run at once? (Tests run serially and miss races.)
+- **Security** — exposed secrets, injection openings, unexpected dependencies. A security finding is always `HARD-STOP`, never a waiver. ANY note here escalates to the human — start it with `NOTE` or `⚠` so a reviewer can see it. A finding you never marked is **invisible** — escalated to no one. Under `auto`, a human **spot-audit** (reading the diff) is the only backstop for a *missed* security finding.
+- **Architecture** — respects layering/dependency rules in CONVENTIONS.md?
+
+Run the three lenses in order — a Security `HARD-STOP` ends the checklist (leave the rest blank). Record in §6 `### Advisor 3-lens verdict` (Verdict · Residue · Binding): `sensitivity: mechanical` → Binding `yes` (engine reads it for `advisor-gate-relax`), every other class → Binding `advisory`. An unfilled block is an unrecorded verdict, not a PASS.
+
+## Part three — the deep check (do not skim)
+
+Code: record every new symbol referenced (wiring) and no new dead/unused code introduced. Prose or non-code: record a semantic read — what you read in full and what it confirmed. The resolver judges which path; the engine never classifies.
+
+Record in the §6 **Deep checks** block — an unfilled one is a **shallow verify**, not a PASS.
+
+## Part four — was the green earned?
+
+A green suite proves tests pass — not that the build EARNED them. Three judgment cheats pass the unchanged suite: src overfit to the test fixtures (special-cased to literal inputs), vacuous asserts (green against an empty implementation), and real logic stubbed away — all invisible to the mechanical tamper tripwire. Score them with an adversarial refute-read: an independent reviewer — the engine never spawns one — prompted to argue the green was NOT earned. A confirmed earned-green failure is HARD-STOP-class: never auto-passed, never RISK-ACCEPTED — a first cheat enters the bounded self-heal loop (run.md). Under `auto`, **record the verdict** in §6's `### Refute-read verdict` block — an unrecorded verdict leaves the auto-PASS untraceable (the human spot-audit is the backstop).
+
+## Record exactly one outcome (no silent pass)
+
+Render this gate from the card: banner → ARC → SUMMARY → FLAGS → EVIDENCE → APPROVE → NEXT
+(`gate-udd.md` = the full template + examples, read at most once per session), and reconcile FLAGS
+with `add.py report --decide`'s open-item count. Right-size the render to the risk: `sensitivity: mechanical`
+tasks use the compact form — banner → SUMMARY → EVIDENCE → APPROVE; `security` / `data` /
+`architecture` always get the full card. **Human-led: render before `gate` and record `Reported: yes` in §6, never self-stamp.**
+
+| Outcome | When |
+|---------|------|
+| `PASS` | all checks met |
+| `RISK-ACCEPTED` | a **non-security** gap, with signed owner + ticket + expiry |
+| `HARD-STOP` | any failing test or any security finding |
+
+## Exit gate / Next
+
+<exit_gate>
+- [ ] Evidence confirmed, non-functional risks checked, outcome recorded — a person approved, or
+  (under `autonomy: auto`, no residue) the run auto-resolved as accountable owner.
+</exit_gate>
+
+> **Persona** — refute-read under the fit `flow: verify` persona / Code-Reviewer lens (advisory; security still HARD-STOPs).
+> **Advisor · Confidence** — the earned-green refute-read is the canonical adversarial spawn (the
+> advisor spawn, below); score it with the confidence self-score (`phases/direction.md`) before recording the gate.
+
+```bash
+python3 .add/tooling/add.py gate PASS          # marks the task done
+# or: add.py gate RISK-ACCEPTED   |   add.py gate HARD-STOP (return to Build)
+```
+
+## Observe (post-gate, §7) — feed the next loop
+
+Verify owns the loop's tail since the six-phase merge. After the gate, fill §7:
+
+1. **Release behind a scope-of-impact limit** — a flag and/or gradual rollout.
+2. **Reuse scenarios as monitors** — the §2 scenarios that defined "correct" define
+   what you alert on: overall error rate, each rejection's rate, latency of the risky op.
+3. **Draft the next spec delta** — every defect, surprise, or new need becomes a change
+   that re-enters the flow at Specify (a new task). Emit lessons tagged by the
+   competency they improve (`deltas.md`); file each into its living spec (`delta-append`).
+4. **Propose a voice delta** — where your voice diverged from the human's, propose a
+   confirmable voice delta tuning `SOUL.md`, emitted `open` (grammar + routing: `deltas.md` —
+   the human is the only writer). Never auto-roll-back — recommend; a human owns production.
+
+> **Decisions (ADR)** — the gate already harvested §7's ADR block into the milestone record.
+> **Persona** — tag `· persona:<slug> · critical-rule|success-metric|anti-pattern|ability`;
+> a HOW-an-agent-behaves lesson belongs in that persona file, not the shared pile.
+
+Loop — the artifacts are living docs the next cycle refines. Map: the self-improving map
+(`phases/build.md`) · book: `docs/08-step-6-verify.md` · `docs/09-the-loop.md`.
+
+## The advisor spawn — delegate one piece, never the loop
+
+Spawn a *single* subagent for one well-scoped piece of your plan (many-task pipelines: the
+stream-orchestrator persona); the engine never spawns — your call per step. Spawn when the piece
+is separable and worth the round-trip: a broad sweep, an independent adversarial review (the
+refute-read — fresh context, never author-graded), a batch, a context-offload; not for narrow
+cheap work — in doubt, do it in-context. **Prefer the named roster**: the ONE `add` agent — the
+spawn names the mode (direction · build · verify · persona · advise) — over an ad-hoc spawn; it
+carries the worker contract and loads the beat guide + best-fit persona itself. Tier: **mid**
+ordinary, **top** complex/cross-cutting (the roster contract in `agents/add.md` maps tiers to
+models); a stronger model never buys back a gate. **Refute-read persona** — a **Code-Reviewer**;
+findings carry severity: 🔴 blocker · 🟡 concern · 💭 note. A persona is advisory: it never
+lowers a gate (a security finding still HARD-STOPs).
+
+The plan-following prompt (the worker-contract tags — canonical here):
+
+```xml
+<objective>
+Execute THIS piece of the orchestrator's plan: {{PIECE}}. You own only this piece — not the
+surrounding decisions. Return a verdict; do not record state.
+</objective>
+
+<persona>
+SELECT the persona by frontmatter — flow: match first, then domain; read ONE body —
+and load `.add/personas/{{PERSONA_SLUG}}.md` —
+Identity→your stance · Critical Rules→constraints · Success Metrics→done-bar.
+No match → a {{DOMAIN}} engineer, correctness over speed; never blocks.
+Work step by step: load the context files + the persona; do the work in small steps honoring
+the orchestrator's plan; self-score on the confidence six dimensions — any < 0.9 → refine
+before returning.
+</persona>
+
+<strategy>
+The task's §5 plan — the Strategy (ordered batches) order and the Known-problem fixes — is
+your PREFERRED starting path, not a hard rule. Improve on it when a better strategy emerges
+as you build; on done, report the strategy you ACTUALLY used so the orchestrator can update
+§5 for the audit trail.
+</strategy>
+
+<context_files>
+the plan / task files the piece needs (read-only unless the piece says otherwise)
+</context_files>
+
+<return>
+End with a structured verdict the orchestrator parses and RECORDS:
+{ piece, persona, result, evidence, confidence: {per-dimension 0–1}, open_questions }.
+`persona` names the slug you adopted (or `generic`). Do NOT run add.py or write any shared
+state — you propose, the orchestrator records.
+</return>
+```
+
+**Delegate, don't abdicate**: 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; a low returned self-score
+means refine or re-spawn, never a pass.
+
+## Sensitivity — the risk-class vocabulary
+
+A `sensitivity:` header line declares the risk-CLASS (*what kind*, distinct from `risk:` = *how
+much*); the engine validates + surfaces it (freeze/status/check), never classifies. Base four:
+**security** (authn/authz, secrets, crypto, attack surface — HARD-STOP, human in EVERY tier) ·
+**data** (persistence, migrations, privacy, loss — Datetime, money, or timezone arithmetic also ⇒
+`data`, value formats are the risk surface, bench wm2's naive-timestamp green) · **architecture**
+(module boundaries, contracts, cross-cutting structure) · **mechanical** (rote, low-impact — the
+only class a recorded advisor verdict can gate for auto-completion, `advisor-gate-relax`). EXTEND
+per project in `GLOSSARY.md`'s `## Sensitivity classes` (`- <token>: <definition>`); freeze accepts
+base ∪ domain else `sensitivity_invalid`. Declared never inferred · base four never replaced · a
+comment is never a declaration · a new KIND of risk → propose a class, human confirms (map domain →
+base behavior in the definition, e.g. "pii … escalates to human review" = human-floor).

package/skill/add/run.md

@@ -7,23 +7,10 @@ Scenarios · Contract) still owns *direction*. The engine stays judgment-free: t
 
 ## The specification bundle (v7)
 
-v7 compresses the old three-approval flow to **one**. The AI **drafts the whole specification
-bundle in one pass** — Spec, Scenarios, Contract, and failing Tests — and presents it together.
-The human gives **one approval, at the frozen contract** (the decision point).
-
-Why one and not zero: the decision point **stays human**. The AI *drafts* the contract but never
-*freezes its own* — a person approves the frozen shape before any auto-run touches code: that the
-Spec captures real intent, the Scenarios cover the cases that matter, and the Contract shape is the
-one to freeze. Reject any part → back to draft (backward-correction, principle 4, not failure). The
-decision-point guide (`phases/3-contract.md`) carries the **freeze review checklist** — seven lines,
-⚠-first.
-
-**The lowest-confidence flag.** The AI presents the bundle **lowest-confidence first**: the
-**1–2 points most likely to be wrong**, tagged by part
-(`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`) — `because` names the §1
-assumption behind the doubt, `if wrong` its cost. If nothing is materially uncertain, the AI still
-names the single biggest risk — never a blank "none". This flag is honor-system: the lint cannot
-force engagement — closing that gap is a CI checker's job, not prose.
+v7 compresses the old three-approval flow to **one**: the AI drafts Spec · Scenarios ·
+Contract · failing Tests in one pass; the human gives **one approval, at the frozen
+contract** (a rejected part goes back to draft — backward-correction, not failure). The
+freeze presentation lives in `phases/direction.md`, its one home; this rubric owns AFTER the freeze.
 
 ## When the run begins — the scope-lock trigger
 
@@ -68,9 +55,9 @@ recorded pass is an explicit pass, not a skip).
 - **Auto-PASS requires ALL of:** every test green; coverage not decreased; no test weakened and no
   contract edited; loops dry; completeness-critic clean; and the deep check below.
 - **The deep check (every gate, do not skim).** If the task produced code, record that every new symbol is referenced (wiring) and that no new dead/unused code was introduced. If it produced prose or non-code, record a semantic read. An unfilled deep check is a **shallow verify**, not an auto-PASS.
-- **The recorded refute-read (under `auto`).** The earned-green refute-read (`6-verify.md`) is not just run — its **verdict is recorded** in §6 (`EARNED | NOT-EARNED`); `add.py audit` surfaces an unrecorded one as `refute_unrecorded` — one of three shape lints it lists (with `shallow_deep_check` + `risk_unset`) — and a human spot-audit is the backstop. NOT-EARNED routes to `add.py heal`, never an auto-PASS.
-- **The recorded Advisor 3-lens verdict (under `auto`).** The Advisor 3-lens sweep (security → concurrency → architecture, `6-verify.md`) is recorded in §6 `### Advisor 3-lens verdict`; `add.py audit` surfaces an unfilled block as `advisor_verdict_unrecorded` — a shape lint alongside `refute_unrecorded`.
-- **The rendered gate report (§3/§6).** Report-template.md's ceremony is recorded, not just performed — a `Reported: yes` line in §3/§6; `add.py audit` surfaces an unrecorded one as `contract_report_unrecorded`/`verify_report_unrecorded`; a human spot-audit is the backstop.
+- **The recorded refute-read (under `auto`).** The earned-green refute-read (`6-verify.md`) is not just run — its **verdict is recorded** in §6 (`EARNED | NOT-EARNED`); an unrecorded verdict leaves the auto-PASS untraceable — a human spot-audit is the backstop. NOT-EARNED routes to `add.py heal`, never an auto-PASS.
+- **The recorded Advisor 3-lens verdict (under `auto`).** The Advisor 3-lens sweep (security → concurrency → architecture, `6-verify.md`) is recorded in §6 `### Advisor 3-lens verdict`; an unfilled block is an unrecorded verdict, not a PASS.
+- **The rendered gate report (§3/§6).** Report-template.md's ceremony is recorded, not just performed — a `Reported: yes` line in §3/§6 is the trace; a missed render surfaces only there — a human spot-audit is the backstop.
 - **The `advisor-gate-relax` pathway.** A `risk: high` + `sensitivity: mechanical` task whose §6 Advisor 3-lens verdict records Verdict `PASS` and Residue `none` may auto-complete via `add.py gate PASS` **without** a lowered autonomy level. Security and every non-mechanical sensitivity class are never relaxed by this pathway — the high-risk guard still applies.
 - **Always escalates to a human (never auto-passed):** any **security** finding (HARD-STOP, always);
   a **concurrency**/timing risk the tests cannot exercise; an **architecture**/layering violation;
@@ -105,14 +92,14 @@ Either way: ≤3 honest redos, then escalate. A gamed green never ships.
 ## Emitting deltas — feeding the foundation back
 
 Every gap the completeness-critic finds becomes an **`open` lesson learned** in the task's OBSERVE
-block (`deltas.md` grammar). These `open` deltas feed v5's human-gated consolidation (`fold.md`)
-at milestone close — the loop closing: **v6 run -> v5 foundation**.
+block (`deltas.md` grammar). File each into its living spec (`add.py delta-append`) as it lands
+— the loop closing: **v6 run -> the living 5-DD specs**.
 
 ## The autonomy level
 
 <constraints>
 How much a run may auto-gate is a **per-scope setting** (principle 5). A task declares it in its
-`TASK.md` header — this is not an add.py flag; it is a rubric convention:
+`PLAN.md` header — this is not an add.py flag; it is a rubric convention:
 
 ```
 autonomy: manual | conservative | auto
@@ -125,17 +112,13 @@ autonomy: manual | conservative | auto
 - **conservative** — the deliberate *lowering*: the run converges but STOPS at the verify gate.
 - **manual** — the strict floor: the human owns the verify gate; the engine never auto-resolves.
 
-> **v7 reversal (recorded).** Earlier the default was `conservative`; v7 flips it to `auto` as
-> the default. The level is still **per-scope** and is lowered wherever risk demands.
-
 **The high-risk guard.** On a **high-risk or method-defining scope** `auto` must be lowered to
 `conservative` or `manual`; leaving it at `auto` is the reject code **`unguarded_high_risk_auto`**.
-The scope declares **`risk: high`** in the `TASK.md` header (the engine never classifies scope).
+The scope declares **`risk: high`** in the `PLAN.md` header (the engine never classifies scope).
 Since v14 the guard is mechanical for the declared case:
 the engine refuses the declared combination — `add.py gate` will not complete (`PASS`/`RISK-ACCEPTED`)
-a task whose header carries `risk: high` without a lowered level (`HARD-STOP` always records);
-`add.py audit` flags finished records whose header was tampered or whose GATE RECORD reviewer is
-the auto-gate (CI enforces). An undeclared high-risk scope passes — a scope without `risk: high`
+a task whose header carries `risk: high` without a lowered level (`HARD-STOP` always records).
+An undeclared high-risk scope passes — a scope without `risk: high`
 in its header is not blocked by the v14 mechanical guard.
 
 **Autonomy is earned by goal-clarity — the auto-ready goal.** A milestone goal is auto-ready

package/skill/add/terms.md

@@ -0,0 +1,18 @@
+# Terms — the method's coined vocabulary (decode, don't guess)
+
+The loop in `SKILL.md` uses a few compressed terms of art. This is their plain-language key —
+load it once if a phrase reads opaque; it teaches nothing new about the flow, only names it.
+
+| Term | Plain meaning |
+|------|---------------|
+| **the ARC** | the three-line frame every gate opens with — **A**im (the goal this serves) · **R**each (what is already covered) · **C**ourse (the plan the choice sets up). Engine-sourced, never invented. |
+| **co-specify** | write the ranked ⚠ risk-flag *inside* §1 as you draft it — the flag and the rule it guards are specified together, not bolted on after. |
+| **red for the right reason** | a §4 test fails because the behavior is genuinely absent, not because of a typo, bad import, or wrong fixture. Prove the failure message names the missing behavior before you build. |
+| **covers: clause** | each §4 test bullet carries a `covers:` key naming the frozen §3 clause it proves — the link that lets `locate` map a failing test back to its contract clause. |
+| **cross / re-cross** | *cross* = pass the one human approval that carries the task from direction into build (`freeze --cross`). *re-cross* = a post-freeze change reopened the contract, so the crossing must be earned again. |
+| **compound-cross** | at `gate PASS`, the engine folds every open sub-check (evidence · lenses · target-hit) into one recorded crossing — you don't stamp each; the gate compounds them. |
+| **earned-green refute-read** | before recording PASS, read the green suite *trying to disprove it* — is it green because the feature works, or because the test is weak? Green is earned, not assumed. |
+| **auto-resolved PASS** | under `autonomy: auto`, a verify with complete, no-residue evidence records an explicit PASS without a human tap — an *auto-resolved* crossing, never a skip. Residue or lowered autonomy → a human decides. |
+
+Everything else in `SKILL.md` is plain method language; when in doubt, the phase guide that owns the
+beat (`phases/direction.md` · `phases/build.md` · `phases/verify.md`) defines it in full.