@pilotspace/add 2.0.0 → 2.1.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.

package/skill/add/phases/direction.md

@@ -81,7 +81,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>
 
@@ -236,6 +236,13 @@ 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
@@ -254,7 +261,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

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.
@@ -50,7 +50,7 @@ tasks use the compact form — banner → SUMMARY → EVIDENCE → APPROVE; `sec
 |---------|------|
 | `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

package/tooling/add.py

@@ -593,6 +593,11 @@ def cmd_init(args: argparse.Namespace) -> None:
             continue
         _atomic_write(dest, rendered)
 
+    # persona-skill: personas are AUTHORED via the persona-author skill (not seeded from a
+    # template) — but the location must exist so the first authored persona has a home and the
+    # unseeded nudge has a directory to check. Create it empty; the skill fills it.
+    (root / "personas").mkdir(parents=True, exist_ok=True)
+
     # specs-5dd (ADD 2.0 M3): the five living 5-DD specs — same survivor idiom as
     # SETUP_FILES (never clobber, never write blank), ONE template rendered five ways.
     for dd in SPEC_DDS:
@@ -779,6 +784,8 @@ def cmd_new_task(args: argparse.Namespace) -> None:
     # was HARD-STOP escalated) could launder the cap (HEAL_CAP) to zero by re-creating itself —
     # a zero-human cap bypass (the same invariant _heal_or_escalate guards: "never auto-resets").
     prior_heal = state["tasks"].get(slug, {}).get("heal") if args.force else None
+    # round-visible-runs: the round record is monotonic the same way — survives a --force re-create.
+    prior_rounds = state["tasks"].get(slug, {}).get("rounds") if args.force else None
     state["tasks"][slug] = {
         "title": title,
         "phase": "direction",
@@ -796,6 +803,8 @@ def cmd_new_task(args: argparse.Namespace) -> None:
         state["tasks"][slug]["relates_to"] = relates_to
     if prior_heal is not None:
         state["tasks"][slug]["heal"] = prior_heal   # monotonic — survives the --force re-create
+    if prior_rounds is not None:
+        state["tasks"][slug]["rounds"] = prior_rounds   # same monotonic contract as heal
     if from_delta:
         state["tasks"][slug]["from_delta"] = from_delta     # lineage: seeded from <prior>
     if sensitivity:
@@ -1686,8 +1695,21 @@ def cmd_phase(args: argparse.Namespace) -> None:
     # scope snapshot), so verify's _tamper_guard is armed and a freeze-gated DRAFT §3 is refused.
     # validate-then-write: a refusal raises BEFORE the phase is set, so nothing moves. The heal
     # loop sets phase=build directly (never via cmd_phase) and so stays exempt.
+    # round-visible-runs: --note annotates a verify->build ROUND — refuse it anywhere else,
+    # BEFORE any write (validate-then-write; a refused entry leaves state byte-unchanged).
+    # The refusal keys on the FLAG being passed (whitespace included) and the note is stored
+    # VERBATIM (§1 Boundary); the contract's refusal exit code is 2.
+    note = getattr(args, "note", None)
+    if note is not None and args.phase != "build":
+        _die("phase_note_build_only: --note annotates the verify->build round this return "
+             "records — it is only valid with target build", code=2)
+    prior = state["tasks"][slug].get("phase")
     if args.phase == "build":
         _build_entry(root, state, slug, skip_freeze=getattr(args, "skip_freeze", False))
+    # round-visible-runs: a verify->build return trip IS a round — record it in the SAME
+    # save as the phase write (atomic; no round without the return, no return without it).
+    if args.phase == "build" and prior == "verify":
+        _record_round(state["tasks"][slug], source="phase", note=note)
     state["tasks"][slug]["phase"] = args.phase
     state["tasks"][slug]["updated"] = _now()
     save_state(root, state)                    # F12: durable state FIRST (source of truth) — may _die
@@ -2293,6 +2315,7 @@ def _append_route_trace(root: Path, state: dict, slug: str, outcome: str) -> Non
             "kind": kind, "lane": lane, "routed_by": by,
             "persona": m.group(1) if m else None, "outcome": outcome,
             "heals": (t.get("heal") or {}).get("attempts", 0),
+            "rounds": (t.get("rounds") or {}).get("count", 0),   # visible verify->build return trips
             "recross": bool(t.get("recross")), "age_hours": age,
             "target_hit": t.get("target_hit"),          # the §3 Target judgment (plan-core)
             "actor": (t.get("gate_actor") or {}).get("name"),
@@ -2925,7 +2948,10 @@ def cmd_status(args: argparse.Namespace) -> None:
     _now_active = _active_task(state)
     if _now_active and _now_active in (state.get("tasks") or {}):
         _now_ph = (state["tasks"][_now_active] or {}).get("phase", "?")
-        print(f"now     : '{_now_active}' · phase={_now_ph} · {_next_footer(root, state)}")
+        # round-visible-runs: a bounced task names its return-trip count; silent at 0.
+        _now_r = ((state["tasks"][_now_active] or {}).get("rounds") or {}).get("count", 0)
+        _now_rr = f" · round {_now_r}" if _now_r else ""
+        print(f"now     : '{_now_active}' · phase={_now_ph}{_now_rr} · {_next_footer(root, state)}")
         print(f"          PLAN.md: .add/tasks/{_now_active}/PLAN.md   ·   re-orient: add.py status --brief")
     print(f"project : {state.get('project', '(unknown)')}")
     # project autonomy default (task init-auto-default): the posture new tasks INHERIT,
@@ -3957,7 +3983,7 @@ def cmd_check(args: argparse.Namespace) -> None:
                 infos.append((f"persona '{slug}'", "schema-conformant"))
                 # persona-schema-hardening: quality findings the presence check can't see
                 # (typo'd flow: value · bare <…> placeholder) — WARN-only (measure-not-block),
-                # REAL personas only: the seeded `_template.md` is all placeholders by design.
+                # REAL personas only: any `_`-prefixed scaffold is placeholders by design.
                 if not slug.startswith("_"):
                     try:
                         text = pf.read_text(encoding="utf-8")
@@ -4914,6 +4940,18 @@ def _scope_guard(root: Path, state: dict, slug: str) -> None:
                                   f"declared §5 Scope — {shown} ({len(out)} total)"))
 
 
+def _record_round(task: dict, *, source: str, note: str | None = None) -> None:
+    """Record ONE verify->build return trip — a visible 'round' (round-visible-runs).
+
+    Uncapped and OBSERVATIONAL: rounds never gate, never cap, never move a phase — they
+    make a dynamic verify->fix workflow legible in status and the route traces. Distinct
+    from the heal counter (the CHEAT-classed, capped subset); a heal return records BOTH.
+    Caller owns the save — the increment rides the same atomic write as the phase move."""
+    r = task.setdefault("rounds", {"count": 0, "history": []})
+    r["count"] = r.get("count", 0) + 1
+    r.setdefault("history", []).append({"at": _now(), "source": source, "note": note})
+
+
 def _heal_or_escalate(root: Path, state: dict, slug: str, *, reason: str, source: str) -> None:
     """The bounded self-heal router (verify-integrity, heal-then-escalate). Called ONLY when
     a cheat is CONFIRMED at this point — mechanical (tripwire divergence, source "tamper") or
@@ -4941,6 +4979,7 @@ def _heal_or_escalate(root: Path, state: dict, slug: str, *, reason: str, source
              "spec (change-request -> re-freeze) or abandon. A gamed green is never auto-passed.")
     heal["attempts"] = heal.get("attempts", 0) + 1
     heal.setdefault("history", []).append(entry)
+    _record_round(t, source=source)           # a heal return is ALSO a visible round (uncapped view)
     t["phase"] = "build"                      # DIRECT — never via advance (no re-snapshot)
     t["updated"] = _now()
     _sync_task_marker(root, slug, "build")
@@ -6682,6 +6721,8 @@ def build_parser() -> argparse.ArgumentParser:
     # cmd_phase) so pre-collapse scripts keep working; the stored value is always canonical.
     pp.add_argument("phase", choices=PHASES + tuple(LEGACY_PHASES))
     pp.add_argument("slug", nargs="?", default=None)
+    pp.add_argument("--note", default=None,
+                    help="annotate the verify->build round this return records (build target only)")
     pp.add_argument("--skip-freeze", action="store_true",
                     help="cross direction->build on a DRAFT §3, recording an auditable freeze_skipped "
                          "marker (the universal freeze gate's only bypass; never auto-freezes §3)")

package/tooling/add_engine/constants.py

@@ -115,18 +115,18 @@ PHASE_GROUPS = {
     "VERIFY": ("verify",),
 }
 # phase-bundles: the roster agent PREFERRED for each phase (per-PHASE, not per-bundle —
-# roster-distill (ADD 2.0 M1): ONE execution shell — the `add` agent — serves every
-# phase; the spawn prompt names the mode (direction·build·verify·advise·persona) and
-# the agent loads that beat's guide + the fitting persona (personas carry the
-# expertise, the agent carries the discipline). A phase missing here is a bug (PHASE_GROUPS'
-# own union covers every key); `_phase_bundle` is the fail-closed resolver for an
-# unmapped/corrupted phase token, not this map directly.
+# advisor-split: `add-worker` is the execution shell for every phase; the spawn prompt names
+# the mode (direction·build·verify·persona) and the agent loads that beat's guide + the fitting
+# persona (personas carry the expertise, the agent carries the discipline). `add-advisor` is
+# spawned on demand to propose/pressure-test/decide — it is not a per-phase default, so it is
+# absent here. A phase missing here is a bug (PHASE_GROUPS' own union covers every key);
+# `_phase_bundle` is the fail-closed resolver for an unmapped/corrupted phase token, not this map.
 PHASE_AGENT = {
-    "direction": "add",
-    "build": "add",
-    "verify": "add",
+    "direction": "add-worker",
+    "build": "add-worker",
+    "verify": "add-worker",
 }
-SETUP_FILES = ("PROJECT.md", "CONVENTIONS.md", "GLOSSARY.md", "MODEL_REGISTRY.md", "dependencies.allowlist", "DESIGN.md", "SOUL.md", "personas/_template.md")
+SETUP_FILES = ("PROJECT.md", "CONVENTIONS.md", "GLOSSARY.md", "MODEL_REGISTRY.md", "dependencies.allowlist", "DESIGN.md", "SOUL.md")
 
 # persona-setup: a PERSONA living doc (`.add/personas/<slug>.md`) is a frozen-schema file
 # distilled from the vendored teacher library to its critical-rules + default-requirement +
@@ -168,18 +168,19 @@ SPEC_DDS = {
 # THIS constant (not their own copy) so the wording can never drift across the three surfaces.
 # Project-scoped (not "this milestone's domain") per the confirmed v2 amendment: the AI should
 # catch up ALL of a project's missing personas, not draft a single milestone-fit one.
-PERSONA_HINT = ("no project-fit persona seeded yet under .add/personas/ — spawn the add agent "
-                "in persona mode (or read docs/18-personas.md) to seed the project's persona(s) "
-                "from PROJECT.md's domain + the seed templates (tooling/templates/personas/)")
+PERSONA_HINT = ("no project-fit persona seeded yet under .add/personas/ — use the persona-author "
+                "skill (or read docs/18-personas.md) to author the project's persona(s) "
+                "from PROJECT.md's domain")
 
 # persona-fit-nudge: the OPPOSITE-branch, mutually-exclusive sibling of PERSONA_HINT — fires only
 # when ≥1 real persona ALREADY exists, so a brand-new milestone doesn't silently assume one of
 # them fits its domain. Existence-only (names the persona slugs already seeded); the AI still
-# owns the actual fit judgment (the add agent's persona mode) — the engine never scores content
-# similarity. {slugs} is filled at call time from `.add/personas/*.md` (excluding `_template`).
+# owns the actual fit judgment (add-worker's persona mode, guided by the persona-author skill) —
+# the engine never scores content similarity. {slugs} is filled at call time from
+# `.add/personas/*.md` (excluding any `_`-prefixed scaffold).
 PERSONA_FIT_HINT_TEMPLATE = (
-    "existing persona(s) seeded — {slugs} — confirm one fits this milestone's domain, or spawn "
-    "the add agent in persona mode (or read docs/18-personas.md) to draft a better-fit one"
+    "existing persona(s) seeded — {slugs} — confirm one fits this milestone's domain, or use the "
+    "persona-author skill (or read docs/18-personas.md) to author a better-fit one"
 )
 
 # Scaffolded into .add/.gitignore at init so the engine's transient LOCAL artifacts

package/tooling/add_engine/guidelines.py

@@ -46,10 +46,11 @@ def _guideline_block() -> str:
         "PROJECT.md `invariants:` (run/entry contracts) bind EVERY task: the artifact must hold under\n"
         "the BARE declared runtime — a dependency that breaks it is a defect, never \"expected\".\n"
         "\n"
-        "Roster (from `add-method/agents/add.md`): ONE `add` agent — the spawn names the mode\n"
-        "(direction · build · verify · advise · persona); the agent loads that beat's phase guide\n"
-        "plus the best-fit `.add/personas/` persona (personas carry the expertise, the agent\n"
-        "carries the discipline; the floor above binds every mode).\n"
+        "Roster (from `add-method/agents/*.md`): TWO agents — `add-worker` runs each EXECUTION beat\n"
+        "(the spawn names it: direction · build · verify · persona), and `add-advisor` is the second\n"
+        "mind it spawns to propose a plan, pressure-test a draft, or decide a delegable ambiguity so\n"
+        "the beat never stalls. Each loads that beat's phase guide plus the best-fit `.add/personas/`\n"
+        "persona (personas carry the expertise, the agent carries the discipline; the floor binds both).\n"
         "\n"
         "On Claude Code the `add` skill drives this loop; other agents follow the three steps. Book: https://pilotspace.github.io/ADD/. This block is generated by `add.py sync-guidelines` — edit outside the markers.\n"
         f"{_GUIDE_END}"

package/tooling/add_engine/io_state.py

@@ -270,9 +270,9 @@ def _md5_file(p: Path) -> str | None:
 
 def _personas_unseeded(root: Path) -> bool:
     """True when `.add/personas/` has no REAL (non-template) authored persona: the
-    directory is absent, empty, or holds only the seeded `_template.md` scaffold
-    (persona-seed-nudge). Fail-soft: an unreadable directory counts as unseeded
-    rather than raising — this feeds a `note:`/INFO hint, never a gate."""
+    directory is absent, empty, or holds only a `_template.md` scaffold (personas are
+    authored via the persona-author skill, not seeded). Fail-soft: an unreadable directory
+    counts as unseeded rather than raising — this feeds a `note:`/INFO hint, never a gate."""
     d = root / "personas"
     if not d.is_dir():
         return True

package/tooling/templates/PLAN.md.tmpl

@@ -71,7 +71,7 @@ Verified by: <agent-id> · at: <ISO-8601 UTC timestamp>
 
 ---
 
-## 4 · TESTS — failing-first suite (red) ▸ docs/06-step-4-tests.md
+## 4 · TESTS — failing-first suite or acceptance checks (red) ▸ docs/06-step-4-tests.md
 
 <test_plan>
   - test_<name>: arrange / act / assert behavior not internals · covers: <M#, R:code>
@@ -79,6 +79,7 @@ Verified by: <agent-id> · at: <ISO-8601 UTC timestamp>
 
 Tests live in: `./tests/` · MUST run red (missing implementation) before Build.
 <!-- declare paths as backticked tokens on this line: `./…` = 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) · declared counts marked † · outside the project root counts 0. The test_plan bullets' `covers:` tails are machine-read too: `add.py locate path::test_name` resolves a failing test to the frozen §3 clause it proves -->
+<!-- NON-CODING task (kind: docs · release · infra, or a non-coding project)? §4 is a failing-first ACCEPTANCE CHECK, not a script — verifiable pass/fail evidence (mkdocs build succeeds · §X covers A/B/C · every internal link resolves), red before the artifact exists and green after. Set `Tests live in: evidence` (no `./tests/`). The red→green discipline holds; only the must-be-executable-code requirement is lifted. -->
 
 ---
 
@@ -86,14 +87,14 @@ Tests live in: `./tests/` · MUST run red (missing implementation) before Build.
 
 Strategy actually used: <fill at VERIFY — what you ACTUALLY did (or "as planned"); harvested into §7 Decisions (ADR)>
 Code lives in: `./src/`
-Spawn (multi-agent): build/verify subagent spawns default `isolation: worktree`; cross-agent advisor — spawn the `add` agent in **advise mode** (an agent OTHER than the builder) for the freeze `--cross` and the §6 refute-read; `self` only when solo.
+Spawn (multi-agent): build/verify subagent spawns default `isolation: worktree`; cross-agent advisor — spawn `add-advisor` (an agent OTHER than the builder) for the freeze `--cross` and the §6 refute-read; `self` only when solo.
 Constraints: do NOT change any test or the frozen §3 contract; stay inside §3 Scope (an out-of-scope build fails the gate: scope_violation); keep the §3 Regression floor green; allow-list packages only; ask if unclear.
 
 ---
 
 ## 6 · VERIFY — evidence + non-functional review ▸ docs/08-step-6-verify.md
 
-- [ ] all tests pass — including the §3 Regression floor (host suite)
+- [ ] all tests (or §4 acceptance checks) pass — including the §3 Regression floor (host suite)
 - [ ] coverage did not decrease
 - [ ] no test or contract was altered during build
 - [ ] the green was EARNED, not gamed — no overfit to fixtures, vacuous asserts, or stubbed-away logic (a confirmed cheat is HARD-STOP)