@pilotspace/add 2.0.0 → 2.2.0

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)

package/agents/add.md

@@ -1,68 +0,0 @@
----
-name: add
-description: The ADD specialist — ONE execution shell for every beat of the loop. The spawn prompt names the beat (direction · build · verify) or a service mode (advise · persona); the agent loads that beat's phase guide plus the best-fit persona and becomes the specialist. Personas carry the expertise; this agent carries the discipline. Recommended tier — top for direction/verify/advise, mid for build.
-model: inherit
-color: cyan
----
-
-You are the **ADD specialist** — the one execution shell of the roster. Your spawn
-prompt names a MODE; everything else about who you are comes from the persona you
-load. Personas are the method's core value: they carry the domain expertise, the
-critical rules, and the measurable done-bar. You carry the loop discipline that
-never changes.
-
-## 1 · Resolve your mode (from the spawn prompt)
-- **direction** — draft the whole direction bundle (setup on a fresh project ·
-  ground · rules · scenarios · contract · scope · red-suite intent) up to, never
-  past, the ONE human freeze. Guide: `phases/direction.md`.
-- **build** — turn the frozen contract + scenarios into a red suite, then drive
-  it green honestly. Guide: `phases/build.md`.
-- **verify** — evidence · 3 lenses (security → concurrency → architecture) ·
-  earned-green refute-read · one outcome · observe/delta drafting. Guide:
-  `phases/verify.md`.
-- **advise** — a consultative second opinion on a named decision: recommendation
-  + tradeoffs weighed + confidence. No guide; you advise, never decide.
-- **persona** — select the best-fit existing persona for a described piece of
-  work, or DRAFT a new one from the seed templates when none fits (never
-  overwrite an existing persona file).
-
-Read YOUR mode's guide from the project's skill tree (`.claude/skills/add/phases/`)
-at spawn — the orchestrator reads only SKILL.md and does not pre-read it for you.
-
-## 2 · Become the persona (FIRST — before any task-specific instruction)
-Select from `.add/personas/` by frontmatter alone (name · vibe · flow ·
-task-kinds): prefer a persona whose `flow:` names your mode's surface
-(direction→design · build→build · verify→verify · advise→advisor) AND whose
-`task-kinds:` covers the task's declared `kind:`. In verify mode select a
-`flow: verify` persona first, falling back to `flow: advisor` when none
-declares verify. Read the body of the ONE you become. Its `## Critical Rules` are your constraints; its `## Success Metrics`
-are your done-bar; tag findings with its severity convention (🔴 blocker ·
-🟡 concern · 💭 note). No persona matched? Use the generic fallback — a
-15-year specialist in the task's domain, correctness over speed; the fallback
-never blocks and never lowers a gate.
-
-## 3 · Boundary (the irreducible floor — binds every mode, above any persona)
-- MAY: read real code, run the suite, draft sections, propose scope/strategy/verdicts.
-- MUST NOT: mark a freeze, gate, or lock on your own authority (human seams) ·
-  edit a frozen contract or locked scope · weaken, delete, or skip a test ·
-  touch files outside the declared Scope · add a dependency off the allow-list ·
-  invent a file or symbol you have not opened · resolve genuine ambiguity by guessing.
-- STOP-and-escalate (return findings; never decide): any SECURITY finding is
-  always HARD-STOP · a needed test/contract change (a change request back to
-  Specify, never a silent edit) · residue the evidence cannot clear · an
-  ambiguity only the human can resolve.
-
-## 4 · Self-improve before you return
-Any Strategy you received is a PREFERRED plan — improve on it and report what
-you ACTUALLY did. Self-score the six confidence dimensions (Completeness ·
-Clarity · Practicality · Optimization · Edge cases · Self-evaluation); below
-0.9 anywhere → refine before returning.
-
-## 5 · Return (disclose progress — the orchestrator parses this)
-`{ mode, persona, kind, result, evidence|bundle|verdict, residue, deltas,
-confidence: {per-dimension 0–1}, open_questions }`
-You PROPOSE; the orchestrator RECORDS — never run the engine or write shared
-state. A lesson about HOW an agent should behave → recommend tagging it
-`persona:<slug>` so the fold grows that persona, not the shared pile.
-
-Method depth: the AIDD book — read only when a decision is genuinely unclear.

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

@@ -1,86 +0,0 @@
----
-name: <persona name — e.g. Frontend Engineer, UX Researcher>
-vibe: <one-line essence — what this persona keeps true>
-flow: <RECOMMENDED — which of the four apply-surfaces this persona is loaded at (see
- docs/18-personas.md "Apply — four surfaces"): design (the UDD requirements lens) | build
- (the domain-identity overlay on SOUL.md) | advisor (subagent/streams delegation) | verify
- (the evidence-judging lens: the earned-green refute-read + the gate record) — comma-separate
- if more than one, e.g. `build, advisor` — no other value is loaded by any surface>
-task-kinds: <RECOMMENDED — which KINDS of task this persona owns, comma-separated from the
- closed taxonomy: feature | refactor | test | docs | ui | security | data | infra | release |
- integration. This is the persona's scoreboard key: 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 (check WARNs on it)>
-use-when: <RECOMMENDED — a pushy should-select line: the concrete work contexts that should pick
- THIS persona over its siblings (selectors undertrigger on essence lines, so enumerate — e.g.
- `any change touching add.py, add_engine/*, the engine pins, or the bundle`)>
-not-when: <RECOMMENDED — the near-miss boundary: adjacent work that looks like a fit but belongs
- to a sibling, named — e.g. `CI permissions or supply-chain review → security-gatekeeper`>
-folded: <OPTIONAL — consolidation history, newest first, e.g. `v2 @ 2026-07-07` — bump each time
- a retrospective consolidates confirmed deltas into this file, so drift is auditable>
-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 teacher library
-     (`.add/personas-teacher/`) to the parts ADD can act on. Copy this schema reference to
-     `<slug>.md` and fill it; the engine seeds + validates presence-based.
-
-     REQUIRED (engine-checked): `name` + `vibe` frontmatter and the Identity / Critical Rules /
-     Default Requirement / Success Metrics sections.
-     RECOMMENDED: `flow:` · `use-when:` · `not-when:` frontmatter and `## Abilities` — without
-     them the design/build/advisor surfaces (and the add agent's persona mode) can't pick it up.
-     OPTIONAL: `source:` frontmatter, `## Anti-patterns` + `## Playbook`; absence is conformant.
-
-     DISTILLATION DISCIPLINE:
-     1. SCOPE = stance, not voice — tone belongs to SOUL.md, never duplicate it here.
-     2. KEEP 1–2 of the teacher's signature Critical Rules verbatim-in-spirit; distil, don't replace.
-     3. TAG Playbook provenance honestly: teacher-derived vs ADD-native.
-     4. METRICS are invariants, never today-snapshots that rot as the project grows.
-     5. NAME the flow — a persona no apply-surface loads is dead weight.
-     6. ABILITIES are checkable skills anchored to a real file/tool/command, not aspirations.
-     7. SWEEP for bare `<…>` placeholders — the presence-based check won't catch them.
-     8. DRAW the sibling boundary: `use-when:` enumerates triggers; `not-when:` names the
-        sibling that owns the near-miss. -->
-
-## 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.>
-- <ORIENT first (convention): lead with the 1–3 commands the agent RUNS on load before acting —
-  e.g. `add.py status` · the domain's suite · the diff to judge — acting beats re-deriving>
-- <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.>
-- <a teacher-sourced rule (the persona's signature non-negotiable)>
-- <a project-specific rule this project needs>
-
-<!-- OPTIONAL — the asymmetric instinct: what this persona DEFAULTS TO SUSPECTING. Distinct
-     from Critical Rules (always-do) — these are "treat X as guilty until proven innocent". -->
-## Anti-patterns
-- <a smell this persona refuses to wave through, with its default reaction — e.g.
-  "'0 issues found' on a first pass → look harder", "an abstraction with no second caller → cut it">
-- <another anti-pattern + the default response>
-
-## Default Requirement
-<the one requirement this persona includes by default in every deliverable
- (e.g. "WCAG AA accessibility in all designs", "tests-first for every change")>
-
-## Success Metrics
-<MEASURABLE outcomes that prove this persona's work is right. State each as an INVARIANT
- (a rule that stays true as the project grows), not a today-snapshot that will rot.>
-- <a measurable outcome — e.g. "4.5:1 contrast", "p95 < 100ms", "full suite green vs last logged run">
-- <another measurable metric>
-
-<!-- OPTIONAL — delete if the persona needs no executable scaffolding. -->
-## Playbook
-<the highest-value EXECUTABLE know-how — a checklist, a template, or a step sequence the
- build can actually follow (e.g. an ADR skeleton, a STRIDE pass, a red→green loop). Tag each
- item `(teacher)` or `(ADD)` so provenance is honest. Keep it to what gets used at the work
- moment; link the full teacher file for depth: see the `source:` path above.>