@pilotspace/add 1.15.0 → 1.16.1

package/docs/08-step-6-verify.md

@@ -31,9 +31,15 @@ Before the build, the task pre-declares its **build expectations** — the obser
 - [ ] Coverage did not decrease.
 - [ ] No test or contract was altered during the build.
 - [ ] Every pre-declared build expectation is confirmed by real evidence (not merely a green test).
+- [ ] Every §1 Must/Reject rule still traces to a §2 scenario tag or a §4 `covers:` line.
+- [ ] Every symbol §3's contract cites still resolves in the *current* tree, not just at Ground SHA.
 
 If any of these is false, stop here and return to the build; there is nothing to verify yet.
 
+A green suite proves the tests you wrote pass — it says nothing about a rule you never wired a scenario or test to at all. That is a different failure than the ones Part four covers: not a cheated pass, but a rule with no trace of ever being checked. `add.py check` scans every task project-wide for exactly this — a §1 Must or Reject with no §2 scenario tag and no §4 `covers:` line — but that sweep is easy to forget to run. `add.py audit`'s `rule_coverage_gap` notice surfaces the SAME check for the task actually at this gate, the moment it reaches Verify (a task that never adopted the tag convention at all is silently grandfathered, never retro-flagged). Neither blocks the gate; both make an already-real gap impossible to miss.
+
+The second check guards against a quieter kind of drift. §0's Ground SHA anchors the symbols §3's contract cites to the commit they were read at — but code moves *during* the build that follows. Before this gate, re-resolve every one of those symbols against the tree as it stands now, not the Ground SHA snapshot, and record it in §6's **Live-verify evidence** block. A moved or renamed anchor caught here is a one-line note; the same drift left silent is a future reader chasing a line number that no longer means what it did at Ground.
+
 ## Part two — check what tests miss
 
 Automated tests are excellent at behavior on defined inputs and poor at a few specific things. Check those by hand, every time:
@@ -77,6 +83,7 @@ A security finding is always a `HARD-STOP`; it is never waved through with a wai
 
 - [ ] All tests pass (the evidence).
 - [ ] Every pre-declared build expectation is confirmed by observable evidence.
+- [ ] Every §1 rule traces to §2/§4; every §3-cited symbol still resolves in the current tree.
 - [ ] Concurrency/timing of the risky operation is safe.
 - [ ] No exposed secrets, injection openings, or unexpected dependencies.
 - [ ] Layering and dependencies follow `CONVENTIONS.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.15.0",
+  "version": "1.16.1",
   "description": "ADD (AI-Driven Development). One skill. Eight steps. Five disciplines. Every feature ships through the loop — a minimal, state-tracked Claude Code skill that ships the AIDD book as its trust layer.",
   "bin": {
     "add": "bin/cli.js"
@@ -18,6 +18,7 @@
   "files": [
     "bin/",
     "skill/",
+    "agents/",
     "tooling/add.py",
     "tooling/add_engine/",
     "!tooling/add_engine/__pycache__",

package/skill/add/SKILL.md

@@ -120,8 +120,9 @@ once the human confirms, rewrites `SOUL.md` (the human is the only writer) — `
 
 - **§3 CONTRACT FROZEN** → build→verify is a dynamic, auto-gated run (`autonomy: auto` default; lower to
   `conservative`/`manual` for a human gate) — `run.md`. Pipeline ready tasks behind frozen
-  contracts — `streams.md`. Delegate one piece of your plan to a subagent (when to spawn, the prompt
-  template, the tier) — `advisor.md`. Self-score a draft (0–1 across six dimensions, refine if any < 0.9)
+  contracts — `streams.md`. Delegate one piece of your plan to a subagent — prefer the named roster
+  (`add-design`/`add-build`/`add-verify`/`add-persona`/`add-advisor`) over an ad-hoc spawn; when to
+  spawn, the prompt template, the tier — `advisor.md`. Self-score a draft (0–1 across six dimensions, refine if any < 0.9)
   — `confidence.md`. Both advisory; the engine never spawns.
 - **Small, low-risk task**, less ceremony → the **fast lane**: `new-task --fast` scaffolds the minimal
   `TASK.fast.md`, bundle approved in one freeze — `phases/fast-lane.md`. Floor held (frozen contract ·

package/skill/add/advisor.md

@@ -11,6 +11,8 @@ Spawn when the piece is **separable and worth the round-trip**: a broad sweep; a
 
 Do **not** spawn for narrow, cheap work — pay the round-trip only when the piece is big or independent enough. When in doubt, do it in-context.
 
+**Prefer the named roster.** Check first whether the piece fits one of ADD's five phase specialists — `add-design` (setup–contract) · `add-build` (tests·build) · `add-verify` (verify·observe) · `add-persona` (fit-persona selection) · `add-advisor` (a consultative second opinion) — before an ad-hoc spawn; each already carries the worker contract below.
+
 ## The 3-lens sequential checklist at verify
 
 At Verify, sweep security → concurrency → architecture in order. **Security HARD-STOP ends the checklist** (leave the rest blank). Each lens returns: **CLEAR** · **HARD-STOP** (security only) · **RESIDUE** (concurrency/architecture).

package/skill/add/loop.md

@@ -50,8 +50,8 @@ When every task is done but the goal is not, `add.py status` shows
    - **Define the release steps** — write the milestone's `## Release steps` (merge is one small
      step among them; PR, asset export, tag/publish are others). These **feed** the release scope —
      read `release.md` for the cut; loop.md never re-specifies it.
-   Present the close via `report-template.md` — open with the ARC (goal · done · plan) and
-   render as a guided choice (recommended next move + described alternatives).
+   Present the close via `report-template.md` — open with the ARC (goal · done · plan),
+   render as a guided choice — **before `milestone-done`/`archive-milestone` run, not after.**
 
 ## Reopen is the verb; this loop is the trigger
 

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

@@ -47,12 +47,12 @@ Ask only the live ones. Rank: `⚠ <assumption> — lowest confidence because <w
 
 Capture each surfaced decision as an **ADR** in `PROJECT.md` **Key Decisions** as it lands.
 
-**Under `autonomy: auto`, auto-complete all four drives in one pass** — lowest-confidence-first. This deepens **drafting**, never the gate: it NEVER skips the human baseline approval — `lock` stays the one decision.
+**Under `autonomy: auto`, auto-complete all four drives in one pass** — lowest-confidence-first. This deepens **drafting**, never the gate — `lock` stays the one decision.
 
 ## 3 · Draft to the lock (both paths)
 
 1. **Fill the living documentation**: `.add/PROJECT.md` (Domain · Spec · UI/UX · Key Decisions), `CONVENTIONS.md`, `GLOSSARY.md`, `MODEL_REGISTRY.md`, `dependencies.allowlist`, and — for a UI project — `DESIGN.md` (delete if no UI; `design.md`). Brownfield: from code. Greenfield: from interview, gaps flagged `guessed`.
-   - **Seed personas** (`.add/personas/`): `init` scaffolds `_template.md` (the schema). Author one per role from PROJECT.md + the vendored teacher library `.add/personas-teacher/` (read off-build; engine never fetches), recording the teacher in `source:` and carrying its top `## Playbook` (both optional). Covered by the **baseline approval**; `add.py check` validates; never clobber.
+   - **Seed personas** (`.add/personas/`): `init` scaffolds `_template.md` (the schema). **Author one per role** from PROJECT.md + the vendored teacher library `.add/personas-teacher/` (read off-build; engine never fetches) — citing the teacher in `source:` and carrying its top `## Playbook` are the two optional parts, not the authoring. Covered by the **baseline approval**; `add.py check` validates; never clobber. Still unseeded later? `status`/`check`/`new-milestone`'s hint means: return here, draft every missing project persona — not just one.
 2. **Propose, then size it.** Float a **kickoff suggestion** for the first milestone: a **goal** (one sentence), a **flow** (task order), **scenarios** (examples of what ships). Not the frozen `MILESTONE.md`. On their reaction, draft `MILESTONE.md` (read `scope.md`).
 3. **Create the first task and draft its candidate specification bundle.** `new-task` is allowed pre-lock:
    ```bash
@@ -76,7 +76,7 @@ Floor: **one human approval per contract**.
 
 ## 4 · The one human gate — the baseline approval
 
-Open the report with the ARC per `report-template.md`, render SHAPE then APPROVE as a guided choice, then present `SETUP-REVIEW.md` lowest-confidence-first. They confirm **once** — an explicit yes to the baseline approval; ambient mid-stream agreement is not a confirmation. On that recorded confirmation, you run the lock:
+Open the report with the ARC per `report-template.md`, render SHAPE then APPROVE as a guided choice, 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 the lock:
 
 ```bash
 python3 .add/tooling/add.py lock --by "<name>"

package/skill/add/phases/3-contract.md

@@ -14,7 +14,7 @@ Then mark `Status: FROZEN @ v1`. Generate a mock + contract tests so dependent
 work can start before the real code exists.
 </output_format>
 
-**The freeze is the one approval.** Present the bundle **lowest-confidence first**: the 1–2 points most likely wrong (`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`). Open with the ARC per `report-template.md`, rendering SHAPE then the freeze APPROVE as a guided choice (recommended pick + described alternatives). See `run.md`. The approval also freezes the §5 **Scope (may touch)** allowlist + Strategy declarations.
+**The freeze is the one approval.** Present the bundle **lowest-confidence first**: the 1–2 points most likely wrong (`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`). Open with the ARC per `report-template.md`, rendering SHAPE then the freeze APPROVE as a guided choice (recommended pick + alternatives) — **render before `FROZEN`, then record `Reported: yes` in §3; never on a timeout.** See `run.md`. The approval also freezes §5 **Scope (may touch)** + Strategy.
 
 ## The freeze review checklist
 

package/skill/add/phases/6-verify.md

@@ -19,6 +19,8 @@ Fill the §6 **Build expectations** block BEFORE Build: OBSERVABLE outcomes deri
 - [ ] Coverage did not decrease.
 - [ ] No test or contract was altered during build.
 - [ ] Every §6 Build expectation is confirmed by real evidence (not just a green test).
+- [ ] §1 rules trace to §2/§4 — an untraced rule is a coverage gap (`add.py audit`'s `rule_coverage_gap`; `check` has detail).
+- [ ] every §3-cited symbol still resolves in the CURRENT tree, not just Ground SHA (§6 Live-verify evidence catches a stale/moved anchor here, not later).
 
 If any is false, stop and return to Build.
 
@@ -42,7 +44,7 @@ A green suite proves tests pass — not that the build EARNED them. Three judgme
 
 ## Record exactly one outcome (no silent pass)
 
-Present this gate via `report-template.md`'s ARC, render APPROVE as a guided choice, and reconcile FLAGS with `add.py report --decide`'s open-item count.
+Present this gate via `report-template.md`'s ARC, render APPROVE, and reconcile FLAGS with `add.py report --decide`'s open-item count. **Human-led: render before `gate` and record `Reported: yes` in §6, never self-stamp.**
 
 | Outcome | When |
 |---------|------|

package/skill/add/report-template.md

@@ -125,4 +125,5 @@ APPROVE  <the question>
 - **The question is a summary, never the artifact.** A compact SUMMARY · FLAGS block sits in chat immediately before the ask; the question text itself is two lines at most — intent + what "yes" means + flag count — pointing at the report above.
 - **NEXT is not a second gate.** The single decision stays in APPROVE; NEXT is ranked recommendations only.
 - **DECIDED never holds a gate-class call.** Security / residue / lowered-autonomy calls escalate in APPROVE.
+- **Recorded, not just performed.** Rendering this template at a gate is recorded, not assumed — TASK.md's `Reported: yes` (§3/§6) is the mechanical trace; `add.py audit` surfaces an unrecorded one (`contract_report_unrecorded` / `verify_report_unrecorded`), a spot-audit the backstop.
 </constraints>

package/skill/add/run.md

@@ -70,6 +70,7 @@ recorded pass is an explicit pass, not a skip).
 - **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 `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;

package/skill/add/streams.md

@@ -55,6 +55,9 @@ tier hint: top → dag-scheduler, setup-run-mode; mid → the rest
 - **Spend your strongest model on the critical path.** Critical-path tasks gate the most
   downstream work; off-path tasks take **mid**. The tier hint is advisory — override when you
   know a task is harder than its position suggests.
+- **Prefer the named roster per worker** — `add-build` for a tests/build-phase worker, `add-design`
+  for design-phase, `add-verify` for verify-phase (full roster + when-to-spawn in advisor.md) — over
+  a generic ad-hoc spawn.
 - **`--json`** (`{ milestone, waves, critical_path, critical_path_len, tiers, blocked }`) feeds
   a runner that spawns programmatically. `blocked` lists tasks whose dep cannot be satisfied
   within this milestone; a `dependency_cycle` is refused with the offending members named.
@@ -95,6 +98,10 @@ floor never drops to zero (`run.md:22`). Do not engineer around it.
   gates this (`engine-merge-base-enforcement`): `add.py wave-verify` before the first merge-back
   refuses a mismatched/pending echo (`unverified_fork_base`) or off-template ledger
   (`wave_ledger_malformed`); `add.py check` is the standing monitor.
+- **Materialize gitignored engine content** — `git worktree add` checks out TRACKED files only;
+  `.add/tooling` (engine) and `.add/docs` (book) are gitignored and will be ABSENT even when the
+  worktree's HEAD matches — copy them in before the worker's first `add.py` call, or its
+  `phase`/`advance` commands have no engine to run at all (confirmed 3-for-3 this session).
 - **Lease + timeout** — record which worker holds which task (wave ledger); a dead worker releases
   its claim back to READY.
 - **Failure isolates** — a worker's STOP-and-escalate blocks only its own task; siblings run on, the

package/tooling/add.py

@@ -100,6 +100,7 @@ from add_engine.io_state import (  # re-exported as module globals: callers use
     _CONFLICT_MARKER_RE,                                            # conflict-marker re
     _load_state_for_json,                                          # --json state loader
     _md5_text, _md5_file,                                          # md5 hashing helpers
+    _personas_unseeded,                                            # persona-seed-nudge predicate
 )
 
 
@@ -1886,6 +1887,11 @@ def cmd_status(args: argparse.Namespace) -> None:
     # Existence-only: no open/parse, so the pointer adds no IO failure path (a non-file is no voice).
     if (root / "SOUL.md").exists():
         print("voice   : .add/SOUL.md  (how I sound & what keeps your trust — read each session)")
+    # persona pointer (persona-seed-nudge v2): project-wide, read every session like context/voice
+    # above — fires until >=1 REAL persona is seeded, self-clears once one lands. Advisory only;
+    # never gates, never touches the --json branch (human-readable orientation surface only).
+    if _personas_unseeded(root):
+        print(f"persona : {PERSONA_HINT}")
     # wave resume hint — a live ledger outranks memory (streams.md "Wave ledger").
     # Existence-only: no open/read/parse, so the hint adds no IO failure path; a
     # non-file at the path is not a ledger. One line PER live ledger — more than
@@ -2930,6 +2936,11 @@ def cmd_check(args: argparse.Namespace) -> None:
                                  "persona_schema_incomplete: missing " + ", ".join(missing)))
             else:
                 infos.append((f"persona '{slug}'", "schema-conformant"))
+    # persona-seed-nudge: surface the SAME "no real persona" gap `new-milestone` nudges on, so
+    # it is also visible on a plain `check`/`status` sweep — an INFO affirmation-of-absence,
+    # never a WARN (measure-not-block; a project with no personas behaves exactly as before).
+    if _personas_unseeded(root):
+        infos.append(("personas", f"unseeded — {PERSONA_HINT}"))
 
     # drift: a done milestone must have no unfinished tasks
     for mslug, m in milestones.items():
@@ -3055,6 +3066,30 @@ def cmd_check(args: argparse.Namespace) -> None:
                          f".add/design/captures/{_pname}.<png|svg|…> — render + confirm it "
                          "before build (design.md beat 4)"))
 
+    # roster-uninstalled (roster-install-drift): the ADD-managed guideline block cites the agent
+    # roster ("agents/*.md" tail — matches both the shipped `add-method/agents/*.md` attribution
+    # citation and any older phrasing) but the project may have no roster installed at all — never
+    # shipped in the package, synced before this fix, or from a build that regressed the agents/
+    # tree — a dead reference with no signal anywhere. WARN, never red (measure-not-block);
+    # presence-gated on the citation itself — a project whose guideline files don't cite a roster
+    # at all is silently exempt, never retro-flagged.
+    _project_root = root.parent
+    _cites_roster = False
+    for _gname in GUIDELINE_FILES:
+        try:
+            if "agents/*.md" in (_project_root / _gname).read_text(encoding="utf-8"):
+                _cites_roster = True
+                break
+        except OSError:
+            pass
+    if _cites_roster:
+        _agents_dir = _project_root / ".claude" / "agents"
+        if not (_agents_dir.is_dir() and any(_agents_dir.glob("add-*.md"))):
+            warnings.append(("roster_uninstalled",
+                             "guideline file(s) cite the agent roster but no `.claude/agents/"
+                             "add-*.md` files are installed — run `add.py update` (or re-run the "
+                             "CLI installer) to materialize them"))
+
     passed = sum(1 for ok, _, _ in checks if ok)
     failed = len(checks) - passed
     if as_json:
@@ -3407,6 +3442,12 @@ def cmd_new_milestone(args: argparse.Namespace) -> None:
     else:
         print("active milestone set." + ("" if not await_confirm else
               "  (unconfirmed — show the MILESTONE.md, then: add.py milestone-confirm " + slug + ")"))
+        # persona-seed-nudge: a non-blocking hint (never a gate) when this project has no
+        # REAL project-fit persona yet — points at the cross-cutting selection/drafting
+        # service rather than inventing a second mechanism. Fires only on the ACTIVE arm
+        # (a queued milestone isn't yet in flight, so the nudge would be premature there).
+        if _personas_unseeded(root):
+            print(f"note: {PERSONA_HINT}")
     print(_next_footer(root, state))   # converges the old "Decompose it into tasks: …" hint
 
 
@@ -6037,6 +6078,21 @@ def _freeze_skip_notices(state: dict) -> list[dict]:
 # region only (mirrors _RISK_HIGH_RE's anchoring so a title substring can never look like one).
 _RISK_ANY_RE = re.compile(r"(?:^|·)[ \t]*risk:[ \t]*\S", re.MULTILINE)
 
+# A single `Reported:` line (report-rendered-trace) — scoped to ONE phase body at a time by the
+# caller (bodies.get(3, "")/bodies.get(6, "")), so §3 and §6 never cross-contaminate each other.
+_REPORTED_LINE_RE = re.compile(r"(?m)^Reported:[ \t]*(.*)$")
+
+
+def _reported_unrecorded(body_text: str) -> bool:
+    """True iff a 'Reported:' line is PRESENT but still an unfilled `<...>` placeholder or blank.
+    ABSENT line -> False (grandfathered — a pre-existing task's TASK.md predates this template
+    field), mirroring _section_unfilled's absent-block convention."""
+    m = _REPORTED_LINE_RE.search(body_text)
+    if m is None:
+        return False
+    val = m.group(1).strip()
+    return (not val) or bool(re.fullmatch(r"<[^>\n]*>", val))
+
 
 def _guarantee_lint_notices(root: Path, state: dict) -> dict:
     """PRESENCE-ONLY, MEASURE-NOT-BLOCK lints SURFACED (never failed-on) by `add.py audit`
@@ -6049,16 +6105,31 @@ def _guarantee_lint_notices(root: Path, state: dict) -> dict:
                            refute-record, M4) — the earned-green verdict the AI must record under
                            `auto`; ABSENT block grandfathers exactly like shallow. MEASURE-NOT-BLOCK:
                            never auto-blocks a gate, only surfaced here for review + a human spot-audit.
-    Honest visibility for three verify guarantees; NEVER a finding (audit stays exit 0). PURE — reads
+      rule_coverage_gap[]= this task's OWN §1 Must/Reject IDs have >=1 rule with no §2 scenario tag
+                           and no §4 `covers:` line (_rule_coverage_gaps — same opt-in-by-tag-presence
+                           grandfather as `add.py check`'s whole-project sweep) — surfaced the moment
+                           THIS task reaches verify, not only via a separate `check` invocation someone
+                           has to remember to run; `check` still owns the per-rule detail.
+      contract_report_unrecorded[] = §3's `Reported:` line present-but-unfilled (report-rendered-
+                           trace) — the freeze report (banner/ARC/SHAPE) was cited by the guide but
+                           never recorded as rendered; ABSENT line grandfathers a pre-field task.
+      verify_report_unrecorded[]   = §6's `Reported:` line present-but-unfilled — the gate report
+                           (banner/ARC) was never recorded as rendered; same grandfather rule.
+    Honest visibility for six verify guarantees; NEVER a finding (audit stays exit 0). PURE — reads
     TASK.md + state only, writes nothing."""
     shallow, risk_unset, refute_unrecorded, sensitivity_unset = [], [], [], []
     advisor_verdict_unrecorded = []
     advisor_reviewer_is_author = []
     advisor_residue_on_mechanical_mis_tier = []
+    rule_coverage_gap = []
+    contract_report_unrecorded = []
+    verify_report_unrecorded = []
     for slug in sorted(state.get("tasks") or {}):
         if (state["tasks"][slug] or {}).get("phase") not in ("verify", "observe", "done"):
             continue
-        body6 = _raw_phase_bodies(root, slug).get(6, "")
+        bodies = _raw_phase_bodies(root, slug)
+        body3 = bodies.get(3, "")
+        body6 = bodies.get(6, "")
         hdr = _task_header(root, slug)
         if _section_unfilled(body6, "### Deep checks"):
             shallow.append(slug)
@@ -6066,12 +6137,21 @@ def _guarantee_lint_notices(root: Path, state: dict) -> dict:
             refute_unrecorded.append(slug)
         if _section_unfilled(body6, "### Advisor 3-lens verdict"):
             advisor_verdict_unrecorded.append(slug)
+        if _reported_unrecorded(body3):
+            contract_report_unrecorded.append(slug)
+        if _reported_unrecorded(body6):
+            verify_report_unrecorded.append(slug)
         if not _RISK_ANY_RE.search(hdr):
             risk_unset.append(slug)
         # sensitivity_unset (risk-sensitivity-taxonomy): a verify-reached task with no
         # human-declared sensitivity — MEASURE-NOT-BLOCK, same class as risk_unset.
         if _task_sensitivity(hdr) is None:
             sensitivity_unset.append(slug)
+        # rule_coverage_gap (verify-traceability-glint): this task's own §1 Must/Reject vs
+        # §2/§4 tags — the SAME predicate `check` uses project-wide, scoped to just this task
+        # and surfaced right at verify, not only via a separate whole-project sweep.
+        if _rule_coverage_gaps(bodies.get(1, ""), bodies.get(2, ""), bodies.get(4, "")):
+            rule_coverage_gap.append(slug)
         # advisor_reviewer_is_author / advisor_residue_on_mechanical_mis_tier
         # (advisor-verdict-audit): MEASURE-NOT-BLOCK lints on the filled advisor block.
         # Both require the block to be PRESENT AND FILLED (not just unfilled).
@@ -6105,7 +6185,10 @@ def _guarantee_lint_notices(root: Path, state: dict) -> dict:
             "sensitivity_unset": sensitivity_unset,
             "advisor_verdict_unrecorded": advisor_verdict_unrecorded,
             "advisor_reviewer_is_author": advisor_reviewer_is_author,
-            "advisor_residue_on_mechanical_mis_tier": advisor_residue_on_mechanical_mis_tier}
+            "advisor_residue_on_mechanical_mis_tier": advisor_residue_on_mechanical_mis_tier,
+            "rule_coverage_gap": rule_coverage_gap,
+            "contract_report_unrecorded": contract_report_unrecorded,
+            "verify_report_unrecorded": verify_report_unrecorded}
 
 
 def cmd_audit(args: argparse.Namespace) -> None:
@@ -6142,6 +6225,11 @@ def cmd_audit(args: argparse.Namespace) -> None:
             av = glints["advisor_verdict_unrecorded"]
             print(f"audit: advisor_verdict_unrecorded — {len(av)} task(s): {', '.join(av)} "
                   f"— record the 3-lens advisor verdict (§6); a spot-audit is the backstop")
+        if glints["rule_coverage_gap"]:
+            rc = glints["rule_coverage_gap"]
+            print(f"audit: rule_coverage_gap — {len(rc)} task(s): {', '.join(rc)} "
+                  f"— a §1 Must/Reject has no §2 scenario tag or §4 covers: line "
+                  f"(run `add.py check` for the per-rule detail)")
         if glints["sensitivity_unset"]:
             su = glints["sensitivity_unset"]
             print(f"audit: sensitivity_unset — {len(su)} task(s) reached verify with no "
@@ -6155,11 +6243,22 @@ def cmd_audit(args: argparse.Namespace) -> None:
             print(f"audit: advisor_residue_on_mechanical_mis_tier — {len(am)} task(s): "
                   f"{', '.join(am)} — mechanical tier with non-none residue and PASS verdict "
                   f"is incoherent; consider re-tiering")
+        if glints["contract_report_unrecorded"]:
+            cr = glints["contract_report_unrecorded"]
+            print(f"audit: contract_report_unrecorded — {len(cr)} task(s): {', '.join(cr)} "
+                  f"— record the rendered freeze report (§3 `Reported: yes`); a spot-audit is the backstop")
+        if glints["verify_report_unrecorded"]:
+            vr = glints["verify_report_unrecorded"]
+            print(f"audit: verify_report_unrecorded — {len(vr)} task(s): {', '.join(vr)} "
+                  f"— record the rendered gate report (§6 `Reported: yes`); a spot-audit is the backstop")
         if not findings and not skips and not glints["shallow"] and not glints["risk_unset"] \
                 and not glints["refute_unrecorded"] and not glints["advisor_verdict_unrecorded"] \
                 and not glints["sensitivity_unset"] \
                 and not glints["advisor_reviewer_is_author"] \
-                and not glints["advisor_residue_on_mechanical_mis_tier"]:
+                and not glints["advisor_residue_on_mechanical_mis_tier"] \
+                and not glints["rule_coverage_gap"] \
+                and not glints["contract_report_unrecorded"] \
+                and not glints["verify_report_unrecorded"]:
             print(f"audit: clean ({checked} tasks checked)")
     # MEASURE-NOT-BLOCK: only real findings raise the exit code; notices never do.
     if findings:

package/tooling/add_engine/constants.py

@@ -24,6 +24,7 @@ __all__ = [
     "SETUP_FILES",
     "PERSONA_FRONTMATTER_KEYS",
     "PERSONA_REQUIRED_SECTIONS",
+    "PERSONA_HINT",
     "GUIDELINE_FILES",
     "RULES_FILE_REL",
     "WORKFLOW_HEADINGS",
@@ -99,6 +100,14 @@ SETUP_FILES = ("PROJECT.md", "CONVENTIONS.md", "GLOSSARY.md", "MODEL_REGISTRY.md
 PERSONA_FRONTMATTER_KEYS = ("name", "vibe")
 PERSONA_REQUIRED_SECTIONS = ("## Identity", "## Critical Rules", "## Default Requirement", "## Success Metrics")
 
+# persona-seed-nudge v2: ONE hint, single-sourced — `new-milestone`/`check`/`status` all print
+# 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-persona "
+                "agent (or read docs/18-personas.md) to seed the project's persona(s) from "
+                "PROJECT.md's domain")
+
 # Scaffolded into .add/.gitignore at init so the engine's transient LOCAL artifacts
 # never reach git. Bare-filename patterns match at any depth under .add/ (tasks/,
 # milestones/, archive/). These are working state, not records: scope-snapshot.json

package/tooling/add_engine/io_state.py

@@ -199,3 +199,17 @@ def _md5_file(p: Path) -> str | None:
         return hashlib.md5(p.read_bytes()).hexdigest()
     except OSError:
         return 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."""
+    d = root / "personas"
+    if not d.is_dir():
+        return True
+    try:
+        return not any(p.stem != "_template" for p in d.glob("*.md"))
+    except OSError:
+        return True

package/tooling/templates/TASK.md.tmpl

@@ -82,6 +82,7 @@ Schema: <tables/fields touched, and access pattern>
 
 Glossary deltas: <new domain term(s) this task introduces, `Term: definition` — or "none">
 Status: DRAFT
+Reported: <yes — the freeze report (banner/ARC/SHAPE) rendered before this froze | no>
 <!-- The freeze IS the one approval — lead it with the bundle's lowest-confidence flag: the 1–2
      points most likely wrong across the whole bundle, tagged [spec|scenario|contract|test], each
      with why + cost (the §1 ⚠ assumptions feed it; a flag may point at a scenario or the contract
@@ -117,6 +118,7 @@ Scope (may touch): `./src/`   <fill before the §3 freeze — every file the bui
 Strategy (ordered batches): <1. … 2. … — the planned build order; guidance, not enforced; preferred architecture/pattern strategies; advise solution/method to resolve issues/implement features>
 
 Persona (optional): <name the persona file under `.add/personas/` this build embodies as a domain stance atop SOUL.md — advisory, never lowers a gate; absent = generic>
+Spawn isolation (default): <prefer isolation: "worktree" for any subagent build/verify spawn, not only explicit parallel mode; shared-tree needs a stated reason — see worktree-isolated-spawn-default>
 Known-problem fixes: <trap → planned fix — the failure modes this build must dodge; guidance, not enforced>
 Strategy actually used: <fill at VERIFY — the strategy you ACTUALLY used (or "as planned"); harvested into the §7 Decisions (ADR) block as the [AI] build decision>
 Safety rule (feature-specific): <e.g. debit+credit in one atomic transaction>
@@ -187,6 +189,7 @@ Residue: <none | summary>
 Binding: <yes — mechanical | advisory — <sensitivity>>
 
 ### GATE RECORD
+Reported: <yes — the gate report (banner/ARC) rendered before this outcome recorded | no>
 Outcome: <PASS | RISK-ACCEPTED | HARD-STOP>
 If RISK-ACCEPTED -> owner: <name> · ticket: <link> · expires: <date>   (never for a security gap)
 Reviewed by: <name> · date: <date>

package/tooling/templates/personas/_template.md.tmpl

@@ -1,6 +1,10 @@
 ---
 name: <persona name — e.g. Frontend Engineer, UX Researcher>
 vibe: <one-line essence — what this persona keeps true>
+flow: <RECOMMENDED — which of the three apply-surfaces this persona is loaded at (see
+ docs/18-personas.md "Apply — three surfaces"): design (the UDD requirements lens) | build
+ (the domain-identity overlay on SOUL.md) | advisor (subagent/streams delegation, incl. the
+ verify refute-read) — comma-separate if more than one, e.g. `build, advisor`>
 source: <OPTIONAL — the teacher file(s) this was distilled from, e.g. `.add/personas-teacher/engineering/engineering-software-architect.md` (provenance; omit if hand-authored)>
 ---
 <!-- A PERSONA is a project-fit requirements persona, distilled from the vendored teacher
@@ -9,8 +13,11 @@ source: <OPTIONAL — the teacher file(s) this was distilled from, e.g. `.add/pe
      the teacher; the engine only seeds + validates this schema (presence-based). This
      `_template.md` is the schema reference — copy it to `<slug>.md` and fill it.
 
-     REQUIRED: `name` + `vibe` frontmatter and the Identity / Critical Rules /
+     REQUIRED (engine-checked): `name` + `vibe` frontmatter and the Identity / Critical Rules /
      Default Requirement / Success Metrics sections.
+     RECOMMENDED (not engine-checked, but expected on every persona for consistency): `flow:`
+     frontmatter and the `## Abilities` section — a persona with no stated flow or abilities is
+     hard for the design/build/advisor surfaces to actually pick up and use.
      OPTIONAL (recommended for a faithful distillation): `source:` frontmatter, and the
      `## Anti-patterns` + `## Playbook` sections. The engine never requires the optional
      parts; absence is conformant.
@@ -23,12 +30,25 @@ source: <OPTIONAL — the teacher file(s) this was distilled from, e.g. `.add/pe
      3. TAG provenance honestly. In `## Playbook`, mark each item teacher-derived vs
         ADD-native. Never credit home-grown project scaffolding to the teacher.
      4. METRICS are rules, not snapshots. Prefer an invariant ("suite matches the last
-        green run") over a volatile literal ("2491/0") that rots as the project grows. -->
+        green run") over a volatile literal ("2491/0") that rots as the project grows.
+     5. NAME the flow. State which apply-surface(s) actually load this persona — a persona
+        that fits none of design/build/advisor is dead weight nobody will ever pick up.
+     6. ABILITIES are checkable skills, not aspirations. Anchor each to a real file, tool, or
+        command this project already has — the same anchoring discipline as Critical Rules
+        and Success Metrics, applied to "what this persona can concretely do." -->
 
 ## Identity
 <who this persona is — role, domain depth, and the EARNED perspective it brings (what it has
  seen succeed/fail that shapes its judgement). One short paragraph.>
 
+## Abilities
+<concrete, checkable things this persona can actually DO — a capability list, distinct from
+ Critical Rules (always-enforced constraints) and Playbook (optional step-by-step scaffolding).
+ State each as something the agent can perform right now, anchored to a real file/tool/command
+ where possible — not an aspiration.>
+- <a concrete capability — e.g. "can diff two response fixtures byte-for-byte to prove passthrough">
+- <another concrete capability>
+
 ## Critical Rules
 <non-negotiables this persona ALWAYS enforces. Lead with 1–2 carried from the teacher (its
  signature stance), then add project-specific ones.>