@pilotspace/add 2.0.0 → 2.2.0

package/skill/add/persona-author/references/contract.md

@@ -0,0 +1,69 @@
+# The ADD persona contract
+
+What the ADD engine reads and validates. Miss the required parts and the persona fails
+`add.py check`; miss the recommended frontmatter and no apply-surface loads it. This is the
+hard schema — `references/patterns.md` is the judgment that fills it well.
+
+## File
+
+- Path: `.add/personas/<slug>.md` — `<slug>` is kebab-case (e.g. `payments-api-engineer`).
+- **Never overwrite** an existing persona file; author a new slug or fold into the named one.
+- **Never** name a persona `_`-prefixed — the engine treats `_`-prefixed files as scaffolds and
+  skips them (they are excluded from the roster, emptiness checks, and quality WARNs).
+
+## Frontmatter
+
+```yaml
+---
+name: <persona name — e.g. Payments API Engineer>      # REQUIRED
+vibe: <one-line essence — what this persona keeps true>  # REQUIRED
+flow: <design | build | advisor | verify>                # RECOMMENDED — comma-separate if >1
+task-kinds: <from the closed taxonomy, comma-separated>  # RECOMMENDED
+use-when: <pushy should-select line — enumerate triggers> # RECOMMENDED
+not-when: <the near-miss that belongs to a named sibling> # RECOMMENDED
+folded: <consolidation history, newest first>            # OPTIONAL
+source: <teacher file(s) distilled from>                 # OPTIONAL
+---
+```
+
+- **`name` · `vibe`** — REQUIRED. Absence fails the schema check.
+- **`flow`** — the apply-surfaces this lens loads at. The ONLY valid values are
+  `design` · `build` · `advisor` · `verify` (single-sourced as `constants.PERSONA_FLOW_VALUES`).
+  Any other value is a typo that no surface loads — `add.py check` emits a `persona_quality` WARN
+  naming it. Surfaces: **design** = the UDD requirements lens · **build** = the domain-identity
+  overlay on SOUL.md · **advisor** = the subagent/streams delegation lens · **verify** = the
+  evidence-judging lens (earned-green refute-read + gate record).
+- **`task-kinds`** — the persona's SCOREBOARD KEY, from the closed taxonomy:
+  `feature · refactor · test · docs · ui · security · data · infra · release · integration`.
+  Route-outcome traces join a task's `kind:` header to this claim, so performance is measurable
+  per kind. A value outside the taxonomy scores as nothing.
+- **`use-when` / `not-when`** — the selection boundary. Selectors under-trigger on essence lines,
+  so `use-when` ENUMERATES the concrete contexts that should pick THIS persona; `not-when` names
+  the sibling that owns the near-miss (e.g. `CI permissions → security-gatekeeper`).
+
+## Sections
+
+**REQUIRED (engine-checked, presence-based):**
+
+- `## Identity`
+- `## Critical Rules`
+- `## Default Requirement`
+- `## Success Metrics`
+
+**RECOMMENDED (a surface can't fully use the lens without them):**
+
+- `## Abilities`
+
+**OPTIONAL (absence is conformant):**
+
+- `## Anti-patterns`
+- `## Playbook`
+
+## Quality WARNs `add.py check` surfaces (non-blocking, measure-not-block)
+
+- **flow typo** — a `flow:` value outside the four is named in the finding (loaded by no surface).
+- **bare placeholder** — a `<…>` token left outside backtick spans and HTML comments (a half-filled
+  copy). Backticked (`` `<slug>` ``) and commented (`<!-- <x> -->`) angle brackets are content, not
+  placeholders. Sweep every real `<…>` before you finish.
+
+These are WARNs, never failures — but a roster-ready persona clears all of them.

package/skill/add/persona-author/references/patterns.md

@@ -0,0 +1,122 @@
+# The judgment layer — distilled from strong subagent design
+
+Eleven patterns that separate an expert lens from an undifferentiated keyword list. Each is drawn
+from an apple-to-apple read of strong agent files (senior-rust/-java engineers, python-expert,
+module-doc-generator, component-tracer, ux-design-architect, and peers) plus a diagnosis of the
+vendored teacher corpus, and cast for an ADD persona. Contract (which section) →
+`references/contract.md`; this file is *how to fill it well*.
+
+## Contents
+1. Earned-perspective Identity
+2. Bold-lead Critical Rules
+3. The qualification gate
+4. Read-before-you-assert
+5. Failure-mode-aware Success Metrics
+6. ORIENT-first Abilities
+7. Design-for-failure (conditional)
+8. Guilty-until-proven Anti-patterns
+9. Numbers you'd defend
+10. Per-flow stance
+11. Deliberate exclusions — what NOT to put in a persona
+
+---
+
+## 1. Earned-perspective Identity
+Every strong agent opens not with a title but with *what it has seen*. State the domain depth AND
+the scar that shapes its judgement.
+- ✗ "You are a senior payments engineer with expertise in APIs."
+- ✓ "…has shipped reconciliation systems where a single un-idempotent retry double-charged a
+  customer, so it treats every write as replayable until proven otherwise."
+The scar is what makes the later Anti-patterns feel inevitable rather than arbitrary.
+
+## 2. Bold-lead Critical Rules
+Lead each rule with a **bold clause**, then the why. Scannable beats prose. Keep it to what the
+persona would actually *refuse to wave through* — not a wish list.
+- ✗ "Always make sure to handle errors properly and think about idempotency."
+- ✓ "**Every write is idempotent** — a retried request must not double-apply; key it or reject it."
+When a rule is subtle, one ✗/✓ contrast pair teaches more than a paragraph — "follow best
+practices" is useless; "wrap MobX components in `observer()` (see `RoleSkillCard.tsx:15`)" acts.
+
+## 3. The qualification gate
+The single sharpest transferable stance. Before elaborating, name the simplest baseline that meets
+the contract; if it wins, take it and STOP. Cleverness is a tax the project pays forever.
+- ✓ Critical Rule: "**Simplest baseline first** — if a plain table + unique index meets the
+  contract, ship that; an event-sourced ledger earns its keep or it's a tax."
+Its sibling move covers contradictory requirements ("minimal but feature-rich"): name the tension
+and propose the balance with its cost — never silently satisfy one half. And perspective proves
+itself by naming the losing option: *why this, not that — and why that loses*.
+
+## 4. Read-before-you-assert
+The reporting agents (module-doc, component-tracer) make this a hard rule: never cite a file,
+symbol, or line you have not opened. In an ADD persona it is an Anti-pattern:
+- ✓ "a claim resting on a file/symbol not opened → open it or cut the claim."
+It binds outputs too: every path or example the persona's own deliverable cites must exist at the
+named place — a placeholder that survives into the deliverable is the same defect. This mirrors
+the add-worker floor ("never invent a file you have not opened") as a domain instinct.
+
+## 5. Failure-mode-aware Success Metrics
+A metric is only expertise if it names the way of being wrong it catches. State each as an
+INVARIANT (true as the project grows), paired with its failure mode.
+- ✗ "High test coverage; good performance."
+- ✓ "**No double-post under retry** — a replayed request leaves the ledger byte-identical (catches
+  the un-idempotent write); **p95 < 150 ms at 100 rps** (catches the N+1 that only shows under load)."
+Each bar must be checkable IN-SESSION by the agent holding the lens — a behaviour it can observe
+or a test it can run. An invented outcome statistic ("engagement +40%") sounds measured and never
+was; it is the signature rot of weak persona corpora.
+
+## 6. ORIENT-first Abilities
+Lead the ability list with the 1–3 commands the lens RUNS on load before acting — `add.py status`,
+the domain's suite, the diff to judge. Acting on ground truth beats re-deriving it. State every
+other ability as something doable *now*, anchored to a real file/tool/command — not an aspiration.
+- ✓ "can diff two response fixtures byte-for-byte to prove passthrough" (checkable)
+- ✗ "understands API design deeply" (unfalsifiable)
+
+## 7. Design-for-failure (conditional)
+Any persona that owns I/O, network, or infra carries a design-for-failure ability: it can name the
+**timeout · retry · circuit-breaker · rollback** for every external call. An unbounded await or a
+silent half-write is a defect, never "expected". Omit this for pure design/docs lenses — forcing it
+on a lens that touches no I/O is noise. Match the pattern to the persona's real surface.
+
+## 8. Guilty-until-proven Anti-patterns
+Distinct from Critical Rules (always-do): these are the smells the lens treats as *guilty until
+proven innocent*, each with its default reaction. The sharpest are the instincts the Identity's
+scars produced — and the strongest attach the COST to the smell:
+- ✓ "'0 issues found' on a first pass → look harder."
+- ✓ "an abstraction with no second caller → cut it."
+- ✓ "PIL in production preprocessing → 3× slower than cv2; reach for cv2 first."
+A smell with its price is an argument; a bare smell is a style opinion.
+
+## 9. Numbers you'd defend
+The cheapest bytes-per-judgment in strong agents: a named budget beats an adjective. "Optimize
+performance" buys nothing; "p95 < 200 ms at the declared load", "44×44 px touch targets", "batch
+wait ≤ 10 ms" anchor the lens to a bar it can hold a build to. Two conditions, or the number is
+cosplay: the expert could defend WHY that number (name what breaks past it), and the lens can
+check it in-session (see 5). Fake precision reads as measured and teaches the agent to invent —
+worse than no number at all.
+
+## 10. Per-flow stance
+The strongest agents split behaviour by mode and bind a bookend to each — *reviewing opens with
+the defect sweep; reimplementing opens with the qualification gate; explaining closes with failure
+modes*. A persona claiming more than one `flow:` does the same in one or two lines: what it LEADS
+with at build, what it REFUSES at verify. A verify stance carries the default verdict — NEEDS-WORK
+until the evidence cites the actual run — plus its automatic-fail triggers. A lens whose rules
+read identically at every flow hasn't decided what each surface is for.
+
+## 11. Deliberate exclusions — what NOT to put in a persona
+A persona is a layer in a stack; keep the other layers' work OUT of it.
+- **No tone/voice** — that is SOUL.md's. A persona that prescribes phrasing is duplicating it.
+- **No self-score / confidence rubric** — the agent (add-worker) owns the six-dimension score.
+- **No output skeleton** — the deliverable's shape is the agent's Return contract, not the lens's.
+- **No stakes/CoT priming** ("take a deep breath", "$500 tip") — motivation is the agent's; the
+  persona supplies judgment, not pep talk.
+- **No keyword taxonomy** — a page of noun-phrase bullets ("saga pattern, composite indexes, …")
+  buys no behaviour; the model knows the words. Every bullet carries an opinion or it goes.
+- **No tutorial code dumps** — framework boilerplate rots fast; a snippet earns its place only
+  when it encodes a rule the prose can't.
+- **No invented metrics or fabricated telemetry** — "+40% engagement", "47 pipelines deployed":
+  numbers that sound measured train the lens to hallucinate finished-ness.
+- **No adverb-padded checklists** — "documented thoroughly", "monitored comprehensively" are
+  unverifiable filler wearing a checklist's clothes.
+- **No other project's paths** — a persona anchors to THIS project's real files and commands;
+  an inherited path from a seed source is contamination, not context.
+Every line you cut from these categories makes the judgment that remains sharper.

package/skill/add/persona-author/references/seeding.md

@@ -0,0 +1,79 @@
+# Seeding a persona from an existing source
+
+Authoring from a blank page is the slowest path and the one most likely to miss the judgment
+layer. When a near-fit source exists, **seed from it, then distil** — never copy it wholesale. Two
+sources are always worth checking first, in this order:
+
+1. **The teacher library** — `.add/personas-teacher/**/*.md`, grouped by division folder
+   (`design/`, `sales/`, `paid-media/`, …). A vetted, domain-organised corpus. Prefer this.
+2. **A sample subagent** — a `~/.claude/agents/*.md` file (e.g. `senior-rust-engineer.md`) when the
+   teacher library has no near-fit for a technical domain.
+
+A source is a **head-start on structure**, not a finished lens. The mechanical parts map straight
+across; the judgment parts you must *distil* (compress a verbose body into a few sharp clauses);
+and a few parts the source will **never** carry — you add those yourself. That last column is the
+whole point: a seed that skips it is just a reformatted résumé.
+
+## Teacher file → ADD persona
+
+A teacher file: frontmatter `name · vibe · description · color · emoji`, division from its folder,
+and a verbose motivational body (`## 🧠 Identity & Memory`, `## 🎯 Core Mission`, …).
+
+| ADD schema | Seed from the teacher | Action |
+|---|---|---|
+| `name:` | frontmatter `name` | carry across |
+| `vibe:` | frontmatter `vibe` | carry across (tighten to one line) |
+| `flow:` | the division folder — `design/` → `design`; a review/audit persona → `verify`/`advisor` | **infer, then confirm** against the closed values |
+| `task-kinds:` | the domain (a `design/` lens → `ui`; a data persona → `data`) | **you pick** from the closed taxonomy |
+| `use-when:` / `not-when:` | frontmatter `description` seeds `use-when`; the sibling it's most confused with seeds `not-when` | distil + **add `not-when`** (the source has none) |
+| `## Identity` | the body's identity/experience paragraph ("You've seen developers struggle with…") | **distil to earned perspective** — scars, not the résumé |
+| `## Critical Rules` | any `**Default requirement**:` / non-negotiable lines in the body | distil to bold-lead rules; **add** the two default stances (surface-tradeoffs · qualification-gate) |
+| `## Default Requirement` | the one `Default requirement:` line if present | carry or write |
+| `## Success Metrics` | *(the teacher rarely has measurable metrics)* | **ADD — this is the judgment.** MEASURABLE invariants, each sharpened by the failure it guards |
+| `## Abilities` | the `Core Mission` bullets | distil to concrete, anchored, checkable actions; lead with the ORIENT commands |
+| `## Anti-patterns` | the instincts implied by the "you've seen X fail" lines | name them guilty-until-proven; **always add** read-before-you-assert |
+
+## Subagent md (`~/.claude/agents/*.md`) → ADD persona
+
+A subagent file: frontmatter `name · description · model · color`, the `description` embeds a
+`Use when: …` clause and `<example>` blocks, and the body leads with `## Core Principles
+(Non-Negotiable)`.
+
+| ADD schema | Seed from the subagent | Action |
+|---|---|---|
+| `name:` / `vibe:` | frontmatter `name`; **vibe has no source** | carry name; **write a one-line vibe** |
+| `flow:` / `task-kinds:` | the `<example>` Contexts name the work (review → `verify`; build → `build`) | infer flow + kinds, confirm against the closed sets |
+| `use-when:` / `not-when:` | the `Use when: …` clause in `description`; each `<commentary>` names a core capability | carry `use-when`; **add `not-when`** |
+| `## Identity` | the opening `You are a **…**` paragraph | distil to earned perspective |
+| `## Critical Rules` | the `## Core Principles (Non-Negotiable)` list | distil to bold-lead rules (keep 1–2 signatures); **add** the two default stances |
+| `## Abilities` | the capabilities in the `<commentary>` tags + the body's numbered principles | make each doable *now*, anchored to a file/tool/command; an I/O lens **adds** design-for-failure |
+| `## Success Metrics` | *(subagents state principles, not measurable bars)* | **ADD — measurable, failure-aware invariants** |
+| `## Anti-patterns` | the "only when genuinely required" / "avoid" hedges | name them guilty-until-proven; **always add** read-before-you-assert |
+
+## What to mine, what to refuse
+
+Both source families carry gold the mapping tables can't express — and a signature rot that must
+not survive the seed:
+
+- **Teacher gold** — the one-line `Default requirement:` floor · the "You've seen…" scar sentence
+  (feeds Identity) · behaviour-paired metric rows ("100% warm transfers — never a cold handoff")
+  · a named methodology with its verbatim moves and why-they-work (feeds a Playbook) · the rare
+  "when NOT to use" lines (feed `not-when:` as *symptom → sibling*) · a reviewer's default-verdict
+  stance with automatic-fail triggers (feeds a verify-flow stance).
+- **Teacher rot — refuse** — deliverable code dumps (CSS/config skeletons), emoji-header chrome,
+  invented outcome statistics ("+40% engagement" no one measured), motivational closers and
+  "instructions reference" footers that point at nothing.
+- **Subagent gold** — review-mode checklists (feed the verify side of a per-flow stance) ·
+  pitfalls with the cost attached ("PIL in prod preprocessing → 3× slower than cv2" — feeds
+  Anti-patterns) · budgets the author would defend ("p95 < 200 ms", "44×44 px" — feed
+  Rules/Metrics) · mode bookends ("reviewing opens with the defect sweep").
+- **Subagent rot — refuse** — keyword-taxonomy pages (nouns buy no behaviour), tip bribes and
+  self-score rubrics, tutorial code blocks, and another project's hard-coded paths — a persona
+  anchors to THIS project's real files only.
+
+## After the seed
+
+Record provenance honestly: add a `source:` frontmatter line naming the seed — the teacher slug,
+or `agents/<file>` — (the contract lists `source` as an optional field). Then run the **Workflow** in `SKILL.md` over the
+seeded draft — every section still faces its judgment bar — and `add.py check` until green. A seed
+that never had the Success-Metrics and Anti-patterns columns filled is not done.

package/skill/add/phases/build.md

@@ -1,8 +1,9 @@
 # Build — AI writes the code (the beat you drive to green)
 
-Objective: implement the feature so EVERY failing test passes — without changing any
-test or the contract. This is the only phase the AI leads; §1–§4 removed all
-ambiguity. Write code into `.add/tasks/<slug>/src/`.
+Objective: implement the feature so EVERY failing test — or, for a non-coding task, every §4
+acceptance check — passes, without changing any test or the contract. This is the only phase the
+AI leads; §1–§4 removed all ambiguity. Write code into `.add/tasks/<slug>/src/` (a non-coding
+task writes its artifact to the path its §5 Scope declares).
 
 ## Work in small batches
 
@@ -15,7 +16,7 @@ each batch small enough to review in full.
 
 - **Scope (may touch)** — the allowlist the build may write (backticked tokens); a file outside it is a **STOP → change request** back to Specify.
 - **Strategy (ordered batches)** — the planned build order; guidance, not enforced.
-- **Strategy facets** — Approach (domain strategy) · Data strategy · Pattern · Optimization stance: the domain HOW, anchored upstream (§1 Framings · §3 Schema · CONVENTIONS.md Honors), drafted at tests->build in the Persona's domain vocabulary; ⚠-mark the facet you trust least (risk: high → consult the add agent, advise mode). Advisory, never a gate.
+- **Strategy facets** — Approach (domain strategy) · Data strategy · Pattern · Optimization stance: the domain HOW, anchored upstream (§1 Framings · §3 Schema · CONVENTIONS.md Honors), drafted at tests->build in the Persona's domain vocabulary; ⚠-mark the facet you trust least (risk: high → spawn `add-advisor`, advise-midflight mode). Advisory, never a gate.
 
 Enforced: a completing verify gate refuses an out-of-scope build (`scope_violation` → self-heal).
 
@@ -39,7 +40,7 @@ contract.** A genuine need to change either is a change request back to Specify.
 ## Exit gate
 
 <exit_gate>
-- [ ] All tests pass.
+- [ ] All tests (or §4 acceptance checks) pass.
 - [ ] Coverage did not decrease.
 - [ ] No test and no contract modified by the AI.
 - [ ] No dependency outside the allow-list.
@@ -75,4 +76,4 @@ verify residue → a SPEC delta.
 Routing: `ddd`→domain · `sdd`→system · `udd`→experience · `tdd`→quality · `add`→method — each
 lands in-flight in its living spec via `add.py delta-append <dd>` (grammar: `deltas.md`). A
 HOW-an-agent-behaves lesson → a persona, not the shared pile. Deltas prepend newest-first;
-the spec diff is the receipt. Self-score before emitting (the confidence six dimensions; < 0.9 → refine).
+the spec diff is the receipt. Self-score before emitting (the confidence six dimensions; name the weakest, refine).

package/skill/add/phases/direction.md

@@ -1,9 +1,39 @@
 # 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 —
+Every task COMPOSES §1–§3 + §5-scope in ONE silent draft — a single write, no "moving on to §N"
+narration — then §4 runs red and ONE human approval crosses it into build:
+`add.py freeze --by <name> --cross`. The only mandatory breaks in the draft are running the §4 red
+suite (a tool action, not prose) and the freeze. This file is the reference depth for that span —
 SKILL.md carries the loop; read the section you're stuck in, not the file.
 
+## The reasoning discipline (the lens for the sections below)
+
+**Fluent ≠ true.** A draft's polish tracks its token count, not its evidence; every check in this
+file forces a fresh derivation from THIS task over a plausible template. It is Rule 2 (trust
+evidence, not inspection) turned inward — on your own reasoning, not just the build. Distilled from
+the fable-thinking protocol; each move maps to where the loop already applies it.
+
+**Five moves, one arc per beat:**
+- **FRAME** — restate the real question + the load-bearing facts. → §1 co-specify.
+- **GROUND** — verify by observation, not memory; a recalled file/flag/symbol/lesson is `[PRIOR]`
+  until re-confirmed against the live tree THIS session; a live read outranks memory. → §3 Grounding.
+- **REASON** — hold more than one hypothesis; demand a mechanism ("because…"), not a correlation;
+  simulate with concrete values before committing. → the persona plan · the advisor's propose-plan.
+- **ATTACK** — switch to reviewer, run the cheap kill-test; its output is a concrete falsifying input
+  (file · line · values), not a verdict. → advisor `refute` · verify earned-green (security = HARD-STOP).
+- **DELIVER** — lead with the outcome, expose the weakness, recommend don't survey. → the gate report, lowest-confidence-first.
+
+**Two pre-answer checks the fluent draft skips** (applied at the freeze — checklist below): the
+**Floor** — restate the **Goal** in the human's world (not the wording), then sweep the
+**Leftovers** (every supplied invariant / the BARE runtime encoded or waived) — and the
+**constraint loop** for mechanically-checkable output shape (§3 tag census · §5 scope tokens · §4
+`covers:` keys · REDS): expand → verify mechanically (grep/count, not a re-read) → repair → then freeze.
+
+**Claim grammar** — tag each factual assertion by how you know it: `[OBSERVED]` (checked live this
+session) · `[DERIVED]` (follows from an observation) · `[PRIOR]` (memory, may be stale) · `[ASSUMED]`
+(unverified but required). A bare claim reads as OBSERVED — never leave a guess untagged; it is the
+advisor's §6 Return discipline.
+
 ---
 
 ## Setup — first session only (autonomous draft → one baseline lock)
@@ -81,7 +111,7 @@ 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.
+- [ ] First task created; §1–§4 drafted — the red suite (or §4 acceptance checks) 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>
 
@@ -141,7 +171,8 @@ the design-definition loop (`design.md`).
   `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>`.
 </output_format>
 
-§2 makes every rule checkable — one scenario per Must and per Reject:
+Every Must and Reject must be checkable — canonically as a §4 test (its `covers:` tag); §2 gherkin is
+an OPTIONAL readable projection, added only when a human needs prose cases at the freeze, never as ceremony:
 
 ```gherkin
 Scenario: <short name>
@@ -159,8 +190,8 @@ one per applicable case, or rule it out on purpose. Every Then is specific and o
 - [ ] 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.
+- [ ] Every Must and Reject is encoded — a §4 test (canonical) or an optional §2 gherkin scenario;
+      every rejection asserts what stays unchanged; edge cases covered or ruled out on purpose.
 </exit_gate>
 
 ---
@@ -173,7 +204,10 @@ 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
+survive), via code-navigation tools, not memory. A recalled fact — a file, a flag, a symbol, or a
+prior lesson (even one carried in from memory) — is **PRIOR until re-confirmed** against the live
+tree THIS session; a live read outranks memory, and a safety-grep counts only once you have
+confirmed it actually matched (a `for x in $VAR` that ran vacuous proves nothing). **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
@@ -212,12 +246,27 @@ line the freeze records it (audit-only — `route_unrecorded` is measured, never
 
 ## The freeze review checklist
 
-The human's one minute, aimed. Walk these seven before saying yes:
-
+The human's one minute, aimed. **Fluent ≠ true** — a bundle's polish tracks its token count, not its
+evidence, so these checks force a fresh read of THIS task over a plausible template. Run the **Floor**
+first, then walk the rest before saying yes:
+
+- **Floor (before you read the shape)** — the pre-answer check the fluent draft skips. (1) Restate the
+  **Goal**: the end-state the human actually wants, in their world, not the ticket's wording — a bundle
+  that satisfies the words but misses the goal is the most expensive miss. (2) Check the **Leftovers**:
+  every supplied constraint — each PROJECT.md `invariant:`, the BARE declared runtime, every ⚠ the
+  interview surfaced — is either encoded in §1–§4 or explicitly waived. An unused constraint is a trap,
+  not noise: the artifact must hold under the BARE runtime, so a leftover invariant is a defect already
+  waiting at verify.
 - **⚠ 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?
+- **Shape self-verify (the constraint loop)** — for the mechanically-checkable output-shape rules — the
+  frozen §3 tag census (the closed XML vocabulary), the §5 Scope path tokens, each §4 `covers:` key, any
+  REDS / dangling refs — don't eyeball them: expand the rule, self-verify the draft **mechanically**
+  (grep/count in reasoning space, not a re-read), repair, THEN freeze. This is where the freeze-parser
+  self-breaks get caught before the engine does — a bare `<word>` colliding with the tag census, a
+  `./src/` scope token tripping `scope_violation`.
 - **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?
@@ -236,10 +285,19 @@ scenario asserting **behavior, not internals** · contract-conformance tests (sh
 responses) · side-effect assertions on rejection paths (`assert balance unchanged`) · a recorded
 coverage target.
 
+**Non-coding task?** For `kind: docs · release · infra` (or a wholly non-coding project) the
+check need not be a script: §4 is a failing-first **acceptance check** — verifiable pass/fail
+evidence (renders · every internal link resolves · `§X covers A/B/C` · a command exits 0), red
+before the artifact exists and green after. Declare `Tests live in: evidence`. Red→green still
+binds; only the must-be-executable-code requirement is lifted (the human may declare acceptance
+mode on any task). Coding kinds keep the executable red suite above.
+
 ## 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).
+REPLACE the template's `./tests/` placeholder in place — never append a SECOND `Tests live in:` line:
+the report reads the FIRST, so a stale default left above your real path silently wins.
 `./…` → 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
@@ -254,7 +312,7 @@ moves. Ground §3 on each parent edge's frozen §3 — the PLAN.md itself, never
 built code.
 
 <exit_gate>
-- [ ] One test per scenario, red for the right reason, asserting observable behavior; coverage target recorded.
+- [ ] One test (or acceptance check, for a non-coding kind) 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
@@ -271,9 +329,13 @@ it 0–1 on six dimensions: **Completeness** (every rule/scenario/rejection cove
 (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).
+(does it carry its own refine step?). Rank the six worst→best (a model ranks far more reliably than
+it calibrates an absolute), then NAME the one concrete deficiency in your weakest dimension — a
+missing scenario, an unhandled input, not a number — and fix THAT before presenting; re-rank after.
+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 self-score is a **weak signal**:
+the load-bearing correctness check is the adversarial refute-read (`phases/verify.md`) — the
+plausible-but-wrong a self-score waves through is exactly what the refute exists to catch.
 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".
 

package/skill/add/phases/verify.md

@@ -11,7 +11,7 @@ sufficient. Fill **§6** in PLAN.md including the GATE RECORD.
 
 ## Part one — confirm the evidence
 
-- [ ] All tests pass.
+- [ ] All tests pass — or, for a non-coding task, every §4 acceptance check is green (the evidence it names is real).
 - [ ] 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.
@@ -36,7 +36,7 @@ Record in the §6 **Deep checks** block — an unfilled one is a **shallow verif
 
 ## 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).
+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. Its PRIMARY output is a concrete falsifying input — the fixture value, interleaving, or caller that makes the green wrong (file · line · values), not a verdict; a "looks fine" with no attempted repro is not a refute, and if a real attempt finds none it concedes the green holds and says so. 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)
 
@@ -44,13 +44,13 @@ Render this gate from the card: banner → ARC → SUMMARY → FLAGS → EVIDENC
 (`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.**
+`architecture` always get the full card. Audience by mode: under `conservative` the card renders to the human before the gate; under `autonomy: auto` (no reachable human) you WRITE it to the §6/trace record as the accountable artifact and proceed — you render, you don't wait. **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 |
+| `HARD-STOP` | any failing test or acceptance check, or any security finding |
 
 ## Exit gate / Next
 
@@ -95,10 +95,11 @@ Spawn a *single* subagent for one well-scoped piece of your plan (many-task pipe
 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
+cheap work — in doubt, do it in-context. **Prefer the named roster**: `add-worker` for an execution
+piece (the spawn names the mode: direction · build · verify · persona) and `add-advisor` for an
+advisory one (propose-plan · refute · advise-midflight) — over an ad-hoc spawn; each carries its
+roster contract and loads the beat guide + best-fit persona itself. Tier: **mid** ordinary, **top**
+complex/cross-cutting (the roster contract in `agents/*.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).

package/skill/add/run.md

@@ -89,6 +89,11 @@ Two findings enter the loop:
 
 Either way: ≤3 honest redos, then escalate. A gamed green never ships.
 
+**Every return trip is a visible round** (round-visible-runs): any verify→build return —
+a plain `add.py phase build [--note "finding"]` or a heal — increments the task's
+uncapped, observational `rounds` record; `status` names `round N` and the route trace
+carries it. Heal stays the cheat-classed, capped subset; rounds are the honest whole.
+
 ## Emitting deltas — feeding the foundation back
 
 Every gap the completeness-critic finds becomes an **`open` lesson learned** in the task's OBSERVE