@arbiterforge/ca-pi 0.6.0

package/plugins/ca-pi/routines/skill-author/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: skill-author
+description: The authoring gate for new skills. Routed to when the user invokes /new-skill "<gap>". Five gated phases — gap evidence, scope, authoring, self-review against the v2 house style, routing integration. A new skill is not written until an existing one is proven not to cover the gap, and not shipped until it carries gated phases, hard rules, and a routing entry. Every authored skill matches the v2 format (frontmatter name+description, # name, Pre-flight, Phase N · gate, Hard rules).
+---
+
+# skill-author
+
+Author a new skill, the right way. Routed to when the user invokes `/new-skill "<gap>"`.
+
+## Pre-flight
+
+Read these, or STOP and surface the gap — never author on assumption:
+
+- The `<gap>` argument. Absent → STOP and ask: "Describe the gap this skill would fill. What situation does no existing skill cover today?"
+- `<plugin-root>/routines/INDEX.md` — the surface scan of every existing skill. This is the gap-overlap check in Phase 1 and the integration target in Phase 5. Never bulk-read the skill bodies.
+- `<plugin-root>/routines/commit-gate/SKILL.md` and `<plugin-root>/routines/tdd/SKILL.md` — the canonical v2 format the authored skill must mirror. Read them before Phase 3.
+- `<project-root>/.codearbiter/CONTEXT.md` — project context, only if the gap is project-specific. A generic skill needs no project state.
+
+## Phase 1 — Gap evidence · gate: BLOCK
+
+A new skill is permanent surface area. It is not written until the gap is proven real and proven uncovered.
+
+Restate the gap in one sentence. Then scan `INDEX.md` for overlap: if an existing skill's "Owns" column already covers this, STOP and name it — "The `<name>` skill already owns this; review it before requesting a new one."
+
+If no skill covers it, demand evidence — one of:
+
+- **A** — three specific cases where the gap blocked work: what was attempted, what happened with no skill, what it cost.
+- **B** — one high-impact case with traceable evidence: a blocked PR, an introduced defect, a compliance finding, a repeated failure pattern.
+
+Hypothetical cases do not count. Fewer than three (Option A) or no traceable evidence (Option B) → STOP and decline: "Insufficient evidence of a real, recurring gap. A skill adds permanent maintenance cost. Return with evidence and I'll author it."
+
+Gate: the gap is restated, proven uncovered against `INDEX.md`, and backed by Option-A or Option-B evidence. Speculation does not pass.
+
+## Phase 2 — Scope · gate: BLOCK
+
+Settle scope with the user before any prose is written. Ask, and wait for an explicit answer:
+
+- **Routed or dispatched?** A *skill* is routed to (gated phases, lives at `<plugin-root>/routines/<name>/SKILL.md`). An *agent* is dispatched by a skill (a reviewer/author, lives at `<plugin-root>/agents/<name>.md`). If the gap is really a reviewer, this is the wrong skill — redirect to agent authoring.
+- **Command-invoked or internal?** Does a user type `/<name>` to reach it, or does another skill route to it mid-workflow? A command needs a routing-table entry; an internal skill needs a named parent that routes to it.
+- **Single responsibility.** State the one thing the skill owns in a sentence. If it needs "and" to describe its job, it is two skills — split it or pick one.
+
+Confirm back: "I will write a [command-invoked / internal] skill at `<plugin-root>/routines/<name>/SKILL.md`, owning <one responsibility>. [A `/<name>` command will be added to the routing table. / The `<parent>` skill will route to it.]"
+
+Gate: explicit user agreement on routed-vs-dispatched, command-vs-internal, and a one-sentence single responsibility. Assumed answers do not pass.
+
+## Phase 3 — Authoring · gate: BLOCK
+
+Write `SKILL.md` to the v2 house style — mirror `commit-gate` and `tdd` exactly. Start from `<plugin-root>/routines/skill-author/references/skill-template.md`. Required shape:
+
+- **Frontmatter** — `name:` and `description:` only. Description is terse: what routes to it, the phase count, the gate. No cut doc refs, no trigger disclaimer.
+- **`# <name>`** H1, then a one-line intro naming what routes to it (`/<command>` or the parent skill).
+- **`## Pre-flight`** — the docs to read or STOP on. Project state cites `<project-root>/.codearbiter/<doc>`; other skills cite `<plugin-root>/routines/<name>`; agents cite `<plugin-root>/agents/<name>.md`. Never guess a command — read it or STOP.
+- **`## Phase N — <title> · gate: BLOCK|STOP`** — sequential, each ending in a one-line `Gate:`. A phase with output that could be wrong has a gate; only a purely declarative phase may omit one.
+- **`## Hard rules`** — `MUST NOT` lines, one per rule, no duplication.
+
+Authoring rules:
+
+- Imperative, terse, no hedging. No "should", no "if it looks wrong". A gate is a concrete, checkable condition.
+- Surviving project docs only: `CONTEXT.md`, `tech-stack.md`, `coding-standards.md`, `specs/`, `plans/`, `security-controls.md`, `decisions/`, `overrides.log`. Do not reference cut docs or cut skills.
+- Terminology lock: a skill is *routed to*; an agent is *dispatched*. Never "trigger", "fires", or "runs".
+- An out-of-scope finding gets one line with an inline `[NEEDS-TRIAGE]` marker.
+
+## Phase 4 — Self-review · gate: BLOCK
+
+Re-read the authored skill against the v2 quality bar. Each line below is a checkable defect, not a vibe:
+
+- **Single responsibility** — the skill owns one thing. If a phase belongs to a different job, it is the wrong skill; cut it.
+- **Concrete gates** — every non-declarative phase ends in a `Gate:` line stating a checkable condition. "Looks good" / "seems right" is not a gate; rewrite it.
+- **House-style prose** — terse, imperative, matches `commit-gate`/`tdd`. Strip hedging and filler.
+- **No duplicated rules** — a rule stated in a phase is not restated in Hard rules, and Hard rules carry no duplicates. State each rule once.
+- **Format conformance** — frontmatter is `name`+`description`, plus `disable-model-invocation: true` ONLY on a chain-internal skill (never user-typed, reached solely via routing-table path loads — see ADR-0028); H1 matches `name`; phases are numbered with `· gate:`; paths use `<plugin-root>` / `<project-root>` correctly; no cut docs/skills, no legacy `${FRAMEWORK_ROOT}`/`${PROJECT_ROOT}`/`.agents/` paths.
+- **Frontmatter scalar quoting** — any frontmatter scalar that starts with `[` or `{`, or contains `": "` or `" | "`, MUST be JSON-quoted (the `_yaml_safe_scalar` predicate the surface generator applies to codex/pi wrappers; the claude surface ships frontmatter verbatim, so the author quotes it at the source).
+- **No trigger language** — "routed to" / "dispatched" only, and no `## Trigger` disclaimer block.
+- **Evidence lenses** (issue #612) — each checked where the skill's shape triggers it, skipped where it does not:
+  - A gate an agent is tempted to skip carries a rationalization guard AT the decision point — the known excuses paired with rebuttals. The best rebuttal carries its own instrument: a check the agent can run that falsifies the excuse either way. A tempting gate with no guard is a defect.
+  - An acceptance or verification step names what is READ, never what is claimed — "the subagent reports green" is a defect; "the runner's output shows green" is not.
+  - A user-facing ask leads with a recommendation AND its strongest counter-consideration.
+  - A rule a tested helper could enforce is mechanized rather than accreted as prose — the helper enforces, the prose explains.
+  - A rule whose literal reading has an exploitable edge names what it protects.
+- **Behavior-changing gate revisions are validated, not assumed** — an A/B pass (fixed scenarios, rubrics written before any output exists, both versions run under identical conditions) scaled to the change's blast radius, with results recorded in the PR (issue #612's method).
+
+Compile the findings, fix each, and re-read once. Present the corrected skill and the findings list to the user.
+
+Gate: zero open self-review defects, and the user has seen the corrected skill. An unaddressed defect blocks Phase 5.
+
+## Phase 5 — Routing integration · gate: BLOCK
+
+A skill no one routes to is dead code. Wire it in.
+
+- Add a row to `<plugin-root>/routines/INDEX.md`: skill name (linked), "Routed to by", and "Owns" (the one-sentence responsibility from Phase 2).
+- Add the skill to the routing table — the invocation cue (the `/<command>` or condition), the primary route, any dispatched agents, the hard gate. For a command-invoked skill, also register the `/<command>` in the command reference.
+- For an internal skill, update the named parent so it routes to the new skill explicitly.
+
+Verify no broken references: every path the skill cites resolves. `INDEX.md` row parity and routing-table dangling-route freedom are no longer a hand-check here — `.github/scripts/check_routing_index_parity.py` enforces both mechanically in CI (issue #592); a missing row, an orphan row, or a route to a name that does not exist fails the build.
+
+Hand off to `commit-gate` — never `git commit` directly. The skill change ships only through the commit gate.
+
+Gate: `INDEX.md` and the routing table updated, no broken references, and the change handed to `commit-gate`. CI's routing-parity check is the authority on row/route correctness, not a self-report.
+
+## Hard rules
+
+- MUST NOT author a skill before the gap is proven uncovered against `INDEX.md` and backed by Option-A or Option-B evidence.
+- MUST NOT begin authoring without explicit user agreement on scope (routed-vs-dispatched, command-vs-internal, single responsibility).
+- MUST NOT emit a skill whose phases lack concrete `Gate:` lines, or whose Hard rules duplicate phase rules.
+- MUST NOT use trigger language ("trigger", "fires", "runs") or a `## Trigger` disclaimer — a skill is routed to, an agent dispatched.
+- MUST NOT reference a cut doc, cut skill, or a legacy `.agents/` / `${FRAMEWORK_ROOT}` / `${PROJECT_ROOT}` path in an authored skill.
+- MUST NOT ship a skill without an `INDEX.md` row and a routing entry.
+- MUST NOT commit the new skill directly — hand off to `commit-gate`.

package/plugins/ca-pi/routines/skill-author/references/skill-template.md

@@ -0,0 +1,58 @@
+---
+name: <skill-name>
+description: <One terse sentence: what routes to this skill, the phase count, and the hard gate. No doc refs, no trigger disclaimer. JSON-quote the whole scalar if it starts with `[`/`{` or contains `": "` or `" | "`. Example: "The only path to X. Routed to when the user invokes /foo. Three gated phases — A, B, C. Nothing ships until every gate clears.">
+---
+<!-- Chain-internal skill (never user-typed, reached only via routing-table path loads)?
+     Add `disable-model-invocation: true` as a third frontmatter line — ADR-0028. -->
+
+# <skill-name>
+
+<One-line intro naming what routes to it: `/<command>` (user-invoked) or the parent skill (internal).>
+
+## Pre-flight
+
+Read these, or STOP and surface the gap — never guess a command:
+
+- `<project-root>/.codearbiter/<doc>.md` — <what it provides>. Stop if missing; do not guess.
+- `<plugin-root>/routines/<other-skill>/SKILL.md` — <only if a sibling skill must clear first>.
+- `<plugin-root>/agents/<agent>.md` — <only if this skill dispatches an agent>.
+
+## Phase 1 — <title> · gate: BLOCK
+
+<Imperative description of what this phase does. Terse, no hedging.>
+
+Gate: <a concrete, checkable exit condition>. A partial result does not pass.
+
+## Phase 2 — <title> · gate: BLOCK
+
+<...>
+
+Gate: <...>.
+
+## Phase N — <title> · gate: BLOCK
+
+<Final phase. If the skill ends by persisting, hand off to `commit-gate` — never `git commit` directly.>
+
+Gate: <...>.
+
+## Hard rules
+
+- MUST NOT <invariant, stated once — not duplicated from a phase>.
+- MUST NOT <invariant>.
+- MUST NOT guess a command — read the cited `.codearbiter/` doc or STOP.
+
+<!--
+House-style reminders (delete before shipping):
+- Frontmatter is `name:` + `description:` only.
+- H1 matches `name`. One-line intro names what routes to it.
+- Each non-declarative phase ends in a one-line `Gate:`.
+- Paths: project state -> `<project-root>/.codearbiter/<doc>`;
+  skills -> `<plugin-root>/routines/<name>`;
+  agents -> `<plugin-root>/agents/<name>.md`.
+- Surviving project docs only: CONTEXT.md, tech-stack.md, coding-standards.md,
+  specs/, plans/, security-controls.md, decisions/, overrides.log.
+- Terminology lock: a skill is *routed to*; an agent is *dispatched*.
+  Never "trigger", "fires", "runs". No `## Trigger` block.
+- Out-of-scope finding -> one line with inline `[NEEDS-TRIAGE]`.
+- Terse, imperative. No "should", no "if it looks wrong".
+-->

package/plugins/ca-pi/routines/subagent-driven-development/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: subagent-driven-development
+description: The implementation engine. Routed to by /sprint (full plan, autonomous) and by executing-plans (scoped batch, checkpoint-gated). One fresh subagent per task — test-first via tdd — followed by spec-compliance review, quality review, and fresh-run verification. No single context accumulates drift, and nothing is accepted on a subagent's word.
+disable-model-invocation: true
+---
+
+# subagent-driven-development
+
+One task, one fresh subagent, two reviews, proof on a fresh run. Routed to by `/sprint` (full plan,
+autonomous) and by `executing-plans` (one batch at a time, with human checkpoints between batches).
+The loop processes tasks in dependency order and never trusts a self-report.
+
+## Pre-flight
+
+Read these, or STOP and surface the gap — never guess scope, command, or obligation:
+
+- `<project-root>/.codearbiter/CONTEXT.md` — the `stage:` frontmatter (the maturity value) and project context.
+- `<project-root>/.codearbiter/plans/<slug>.md` — the approved plan. Each task carries an exact path set and a verification command. This is the task source.
+- `<project-root>/.codearbiter/specs/<slug>.md` — the approved spec. Each task's obligation traces to it. The spec-compliance review measures against it.
+- `<project-root>/.codearbiter/tech-stack.md` — build, test, and verification invocations; file layout; the scope-to-author mapping.
+- `<project-root>/.codearbiter/security-controls.md` — only when a task touches a security boundary (auth, crypto, secrets, a trust boundary).
+
+**Optional `scope` parameter:** when invoked by `executing-plans`, a list of task IDs is passed. The
+loop processes only those tasks (in their internal dependency order). When `scope` is absent (the
+`/sprint` path), the loop processes the full plan from first unblocked task to last.
+
+## Phase 1 — Task selection · gate: BLOCK
+
+Pull the next unblocked task from the plan in dependency order. When a `scope` was passed, restrict
+selection to tasks in that list. A task is one verifiable unit of work with a path set, a spec
+obligation, and a verification command.
+
+- Confirm every dependency task is `ACCEPTED` before selecting.
+- Confirm no unresolved `[CONFIRM-NN]` blocks the task. One that does halts the loop — see Hard rules.
+
+Gate: exactly one task selected, dependency-clean, with its spec obligation and verification command in hand.
+
+## Phase 2 — Implementation dispatch · gate: BLOCK
+
+**Farm path (when `<slug>.plan.json` exists alongside the `.md` plan):** skip the subagent dispatch
+loop below and follow `<plugin-root>/routines/subagent-driven-development/references/farm-dispatch.md`.
+The farm path replaces only the *authoring* step for the plan's tasks (cheap Zen workers under hard
+gates instead of premium subagents); it does **not** replace review — every task the farm reports green
+is still routed through Phases 3–5 before acceptance. The cost arbitrage is in who *writes* the code,
+never in whether it is *reviewed*. In brief: select a model (canary-probe with a cache→websearch
+fallback ladder), invoke the trusted `codearbiter_farm_preview` tool with the project-relative
+plan path, honor a circuit-breaker abort as a hard-gate STOP, then for
+each result either accept-after-Phases-3–5 (green) or re-dispatch via premium Phase 2 (escalate).
+Results stream to `.farm/farm-results.jsonl` and are consumed in completion order — Phase 3 + Phase 5
+per green task as it lands, Phase 4 still the once-per-scope barrier (reconcile against `farm-report.json`
+on abort). The reference has the full step-by-step.
+
+---
+
+**Normal path (no `plan.json`):** dispatch ONE fresh subagent for the selected task — `backend-author`, `frontend-author`, or
+`infra-author` by the scope mapping in `tech-stack.md`
+(`<plugin-root>/agents/<name>.md`). A fresh context per task is the whole point: no carried-over
+assumptions, no accumulated drift.
+
+The subagent works test-first by routing through the `tdd` skill (`<plugin-root>/routines/tdd/SKILL.md`) — no implementation code before
+`tdd` Phase 1. Brief it with the task's path set, its spec obligation, and its verification command.
+Nothing else from prior tasks leaks in.
+
+Gate: the subagent reports `tdd` complete — all six phases green. A `tdd` BLOCK halts the loop; do not
+re-dispatch around it.
+
+## Phase 3 — Spec-compliance review · gate: BLOCK
+
+Did the change satisfy the task's obligation? Measure the result against the spec line the task
+traces to — not against whether tests merely pass.
+
+- Every acceptance claim in the task's obligation is met by the change.
+- Scope is clean: nothing implemented beyond the task; nothing required by it omitted.
+- Out-of-scope work the subagent noticed is recorded with an inline `[NEEDS-TRIAGE]` marker — never
+  acted on inside this task.
+
+Gate: the obligation is fully satisfied and scope is clean. A shortfall returns the task to Phase 2
+with a corrective brief.
+
+## Phase 4 — Quality review (once per scope) · gate: BLOCK
+
+Runs ONCE per scope — after every task in the current scope has cleared Phase 3 and Phase 5 — over
+the **combined diff** of the scope, not per 2–5-minute task. Per-task review at that granularity
+costs more context than the work and catches nothing the batch diff doesn't; the batch boundary is
+where review pays. (A scope of one task reviews that task's diff — same rule, degenerate case.)
+
+Dispatch the reviewers applicable to what the combined diff touches, then `finding-triage`
+(`<plugin-root>/agents/finding-triage.md`) to classify every finding by severity. Select
+reviewers by the diff, not blanket — dispatching an irrelevant reviewer wastes a context:
+
+- `security-reviewer` (`<plugin-root>/agents/security-reviewer.md`) — any security-relevant path (authn/authz, deploy, CI, trust boundary).
+- `auth-crypto-reviewer` (`<plugin-root>/agents/auth-crypto-reviewer.md`) — auth, crypto, key, or secret changes.
+- `dependency-reviewer` (`<plugin-root>/agents/dependency-reviewer.md`) — `package.json` / lockfile / base-image changes.
+- `migration-reviewer` (`<plugin-root>/agents/migration-reviewer.md`) — DB migration add/modify.
+
+(Do NOT dispatch `grader` or `scout` — they are INTERNAL to `decision-variance` and must never be
+dispatched here.) If the change touches none of the above domains, the quality bar is `tdd`'s own gates
+plus `coverage-auditor` (already run in `tdd` Phase 4) — record that and proceed.
+
+- A security CRITICAL finding halts the loop — see Hard rules.
+- A HIGH finding returns the offending task(s) — attributed by file — to Phase 2; the scope's
+  quality review re-runs over the corrected combined diff.
+- MEDIUM and LOW findings are recorded; the user decides whether they block.
+
+Gate: no CRITICAL, no HIGH across the scope's combined diff. Nothing in the scope is `ACCEPTED`
+until this passes.
+
+## Phase 5 — Verification · gate: BLOCK
+
+Verification-before-completion: apply the shared fresh-run discipline in
+`<plugin-root>/includes/fresh-verification.md`, with **the task's verification command from the
+plan** as the target. Run it yourself in a clean invocation; do not accept a logged result from Phase 2.
+A non-zero exit, or output that does not demonstrate the obligation, returns the task to Phase 2.
+
+Gate: the verification command exits clean and its output demonstrates the obligation. Only then.
+
+## Phase 6 — Accept and advance · gate: BLOCK
+
+Mark the task `ACCEPTED` only when its spec-compliance review and fresh verification passed AND the
+scope's Phase 4 quality review passed.
+Record acceptance **in the plan file itself** — set the task's `status` cell in
+`.codearbiter/plans/<slug>.md` to `ACCEPTED` the moment it is accepted, plus any `[NEEDS-TRIAGE]`
+markers and the `.codearbiter/` audit trail. The plan's status column is the pipeline's resume
+ledger: an interrupted run is re-entered at the first non-`ACCEPTED` task, and an acceptance that
+lives only in conversation context is lost to the interruption.
+
+- Tasks remain in the current scope → return to Phase 1.
+- **Scoped invocation** (`scope` was passed by `executing-plans`): all scoped tasks `ACCEPTED` → signal
+  batch complete and return to `executing-plans`. Do NOT hand to `commit-gate`; the caller owns that decision.
+- **Full-plan invocation** (no `scope`, i.e. `/sprint`): plan complete → hand the branch to
+  `commit-gate`, then to the caller's finishing step. The loop does not commit on its own authority.
+
+Gate: every task in the current scope `ACCEPTED`, the suite green, ready for the caller's next step.
+
+## Hard rules
+
+- MUST dispatch a fresh subagent per task — never reuse one context across tasks.
+- MUST NOT write implementation code before the task's `tdd` Phase 1 completes.
+- MUST accept a task only when both reviews pass AND verification passes on a fresh run.
+- MUST NOT accept a task on a subagent's self-report — run the verification command and read its exit code.
+- MUST halt and surface to the user on a `tdd` BLOCK, a security CRITICAL finding, or an unresolved `[CONFIRM-NN]` inside the loop — and on a `commit-gate` failure at the finish handoff — even under `/sprint`. These never auto-proceed.
+- MUST NOT commit — hand the accepted branch to `commit-gate`.
+- MUST mark out-of-scope findings with an inline `[NEEDS-TRIAGE]` marker and never act on them inside the task.
+- MUST NOT invoke `farm.js` before writing `meta.model` into `plan.json` (or setting `FARM_MODEL`) — the dispatcher fails loudly otherwise.
+- MUST NOT skip model selection (Step 1) when `FARM_MODEL` is not set — exhaust the canary→cache→websearch fallback ladder before BLOCKing; never blind-invoke with an unknown model id.
+- MUST route every green farm task through Phases 3–5 before acceptance — the farm replaces authoring, never review. A cheap model gets the same scrutiny as a premium subagent, not less.
+- MUST treat a single task's drift/gaming/tampered-test escalation as model incapacity (re-dispatch via premium Phase 2); raise `[CONFIRM-NN]` and HALT only when multiple tasks drift onto the same out-of-scope path (a real spec gap).
+- MUST treat a `farm.js` circuit-breaker abort (`aborted: true`) as a hard-gate STOP — surface to the user; do not silently re-dispatch the whole slice to premium.
+- MUST NOT dispatch `grader` or `scout` in Phase 4 — they are INTERNAL to `decision-variance`.

package/plugins/ca-pi/routines/subagent-driven-development/references/farm-dispatch.md

@@ -0,0 +1,145 @@
+# Farm dispatch — reference for subagent-driven-development's farm path
+
+Loaded from `subagent-driven-development` Phase 2 when `<slug>.plan.json` exists alongside the `.md`
+plan. The farm is a pluggable execution backend — its value is deterministic, gated, parallel, isolated
+execution. The farm path replaces only the *authoring* step for the plan's tasks — a worker implements
+under hard gates instead of a premium subagent. The `Worker` seam admits cheap, premium, and agentic
+implementations; only the cheap HTTP-chat worker ships today (premium and agentic are what the seam is
+designed for — roadmap, not built). It does **not** replace review: every task the farm reports green is
+still routed through Phases 3, 4, and 5 before acceptance. Swapping the worker only changes who *writes*
+the code, never whether it is *reviewed*. See `<plugin-root>/includes/farm.md` for setup.
+
+## Step 1 — Model selection
+
+If `FARM_MODEL` env var is set, use it directly and skip selection. Otherwise, prefer a **measured**
+choice over web hearsay:
+
+1. Read `.farm/model-cache.json` if present. If it records a model chosen within the last 7 days whose
+   last canary pass-rate was acceptable, reuse it (skip to Step 2). Re-research only on a stale or
+   missing cache.
+2. Websearch `"OpenCode Zen free models <current month year>"` + the OpenCode model catalog to enumerate
+   the *candidate* free model ids (codenames included). This step is candidate **discovery**, not a
+   quality judgment.
+3. Run a canary probe to judge quality objectively: set `FARM_CANDIDATE_MODELS=<comma-separated ids>`
+   and call `codearbiter_farm_preview` with the project-relative plan plus
+   `canary: true`. It runs the plan's
+   smallest task against each candidate and writes `.farm/canary-report.json` ranked by measured
+   pass-rate / attempts / latency. Pick the top passing model.
+4. Surface the choice with its measured basis: "Selected `<model-id>` — canary passed in `<n>` attempts,
+   `<ms>`ms (vs. `<alternatives>`). Proceed, or set `FARM_MODEL` to override." For any opaque codename,
+   add one line of websearched identity context (e.g. "community reports GLM4-based") for the audit log.
+5. Fallback ladder if the canary can't run or none pass: (a) the cached model from Step 1; (b) a
+   websearch-selected model with a clear warning that the choice is unmeasured; (c) only if all fail,
+   BLOCK and ask the user to set `FARM_MODEL`. Halting the whole feature on a noisy websearch is wrong —
+   exhaust the ladder first.
+6. Write the chosen `meta.model` + `meta.apiBaseUrl` into `plan.json`, and update `.farm/model-cache.json`
+   (model + timestamp + canary pass-rate) before dispatching.
+
+## Step 2 — Farm dispatch
+
+Invoke the farm dispatcher:
+
+Call the trusted `codearbiter_farm_preview` tool with:
+
+```json
+{ "plan": ".codearbiter/plans/<slug>.plan.json" }
+```
+
+For the measured canary step, add `"canary": true`. The tool resolves the one shared built backend;
+if it reports `terminal: degraded`, surface that preview degradation and rebuild the sibling bundle.
+Do not shell out to a Pi-local farm dispatcher — this host ships none, so any path you construct for one resolves to nothing — and do not fall back silently.
+
+
+Run it with cwd set to `<project-root>` (the dispatcher resolves `.farm/` and git worktrees
+against the current directory). It runs tasks concurrently (up to `FARM_CONCURRENCY`, default 4),
+enforces gates and a zero-token anti-gaming guard, and writes to `<project-root>/.farm/`:
+- `farm-report.json` / `farm-report.md` — per-task status, attempts, files, worker token spend, warnings
+- `farm-results.jsonl` — the incremental stream: one `Result` JSON object per line, appended the moment
+  each task settles (drives completion-order consumption — see Step 2.6)
+- `diffs/<task-id>.patch` — the actual change per task, for audit
+
+Each of those is published twice: once under the run's own artifact directory
+`<project-root>/.farm/runs/<run-id>/` (the durable, attributable receipt — concurrent runs never
+overwrite each other's artifacts) and once at the top-level `.farm/` path above as a **latest**
+convenience pointer. The final summary line prints both. When two runs may share a repository, reconcile
+against the run directory; the pointer is last-writer-wins (always complete, never truncated).
+
+Isolated receipts are not a licence to run two farms on one repository unattended: the git state is
+still shared. Concurrent runs each need a distinct `FARM_INTEGRATION_BRANCH` and `FARM_WORKTREE_ROOT`,
+and non-overlapping task ids (each task branch is `farm/<task-id>`). At defaults the second run fails at
+startup on `cannot lock ref 'refs/heads/farm/integration'`.
+
+Exit code 0 = all green; exit code 2 = some tasks escalated, blocked, or the run was aborted;
+**exit code 3 = the run's authoritative, run-scoped report could not be published in full.** Exit 3 is a
+RECEIPT failure, not a task failure — the tasks may all have been green — and it means this run's
+durable record is missing or incomplete. Treat the run as unverified and re-dispatch; do not accept
+tasks off a run that exited 3. Inspect `.farm/runs/<run-id>/` for whatever did land before discarding.
+
+A failure to refresh the top-level **latest** pointer is *not* exit 3 — that pointer is explicitly
+non-authoritative. The run settles on its task outcome and prints a `WARNING:` naming what could not be
+refreshed; when you see it, `.farm/farm-report.json` describes some *other* run, so read the run
+directory.
+
+`farm-report.json` also carries an `artifacts` block: `artifacts.stream.complete` is `false` when a
+streaming-rail write failed (so a short `.jsonl` is not mistaken for a short run), and
+`artifacts.diffs.unavailable[]` names tasks whose patch could not be written, with the reason. That
+list is capped — `artifacts.diffs.unavailable_total` is the true count. Never assume a
+`diffs/<task-id>.patch` exists for a task listed there.
+
+## Step 2.5 — Circuit-breaker abort
+
+If `farm-report.json` has `aborted: true`, the dispatcher tripped its escalation-rate breaker — the
+chosen model is likely not capable of this slice. This is a hard-gate surface: STOP and tell the user,
+recommending the premium path or a different `FARM_MODEL`. Do not silently re-dispatch every task to
+premium Phase 2 (that defeats the backend's purpose and hides a bad signal).
+
+## Step 2.6 — Streaming consumption contract
+
+The dispatcher writes two artifacts (D7): the incremental `farm-results.jsonl` stream and the final
+`farm-report.json` summary. The escalation/acceptance handler (Step 3) MUST consume the stream in
+**completion order** — read `farm-results.jsonl` line by line (one `Result` JSON object per line) and
+process each task the moment it settles, rather than waiting to parse only the final report. Each
+`green` task is routed through **Phase 3 (spec-compliance) + Phase 5 (verification)** as it lands.
+
+- **Per-green-task = Phase 3 + Phase 5 only.** Only the spec-compliance and fresh-verification reviews
+  run per green task as it streams in.
+- **Phase 4 stays a once-per-scope barrier.** The quality review (Phase 4) MUST NOT be pipelined per
+  task — it still runs ONCE over the combined diff of the whole scope, after every task has cleared
+  Phase 3 and Phase 5. The streaming rail moves Phase 3 + Phase 5 earlier; it does NOT move Phase 4.
+- **`farm-report.json` is authority on abort (D7).** `farm-report.json` is always written in the
+  dispatcher's `finally` — even on a circuit-breaker abort or crash — and remains the AUTHORITATIVE
+  final summary. On an abort or crash, reconcile settled-task state against `farm-report.json`, NOT the
+  partial `.jsonl` stream. The stream is an append-only progress feed; the report is the source of truth.
+- **Temporal overlap is roadmap, not today.** `farm.js` runs in the foreground, so the consumer
+  processes the stream in completion order *after* the run returns — true *temporal* overlap (running
+  review WHILE the farm is still executing) requires backgrounding `farm.js` and is explicitly a
+  future/roadmap item. The streaming rail is the enabling primitive, not the full overlap yet.
+
+## Step 3 — Escalation handler (Phase 2.5)
+
+Consume `farm-results.jsonl` in completion order (Step 2.6); `farm-report.json` is the authoritative
+reconciliation source on abort. For each result:
+
+- **status `green`** — the test gate + anti-gaming guard passed, but it is NOT yet accepted. Route the
+  task through **Phase 3 (spec-compliance), Phase 4 (quality review), and Phase 5 (fresh verification)**
+  exactly as a premium subagent's output would be, measuring the merged change against the spec line the
+  task traces to. A green result carrying a `warning` (gaming-risk) gets extra attention in Phase 3.
+  Only after Phases 3–5 pass does the task reach Phase 6.
+- **status `escalate`, note starts with `"drift:"`** — the cheap model wrote outside `filesInScope`
+  even after a hardened-prompt retry. First occurrence on a task → treat as model incapacity, not a spec
+  gap: re-dispatch via premium Phase 2 (the worktree at `result.worktree` shows the attempt). Only when
+  **multiple tasks drift onto the same out-of-scope path** does it signal a genuine decomposition/spec
+  gap — then raise `[CONFIRM-NN]` and halt.
+- **status `escalate`, note starts with `"gaming:"`** — the model hard-coded the test's asserted value.
+  Re-dispatch via premium Phase 2; do not accept the farm output.
+- **status `escalate`, note starts with `"tampered test:"`** — the model altered the failing test.
+  Re-dispatch via premium Phase 2; the test is the gate's integrity anchor.
+- **status `escalate`, gate-failure note** — the model couldn't pass the test after retries. Re-dispatch
+  via premium Phase 2, seeding the brief with `result.worktree`, the gate note, and `test.path`.
+- **status `escalate`, note starts with `"merge failed"`** — re-order after the conflicting sibling and
+  re-dispatch via Phase 2.
+- **blocked** tasks (`farm-report.json` `blocked[]` array, each with a `reason`) — resolve the upstream
+  escalation first, then re-queue.
+
+Gate: every task is green AND passed Phases 3–5, or was re-dispatched via premium Phase 2 and accepted.
+No task advances to commit-gate while any sibling is unresolved.

package/plugins/ca-pi/routines/tdd/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: tdd
+description: The test-first gate. Routed to by /feature (after the spec is approved), /fix, and /refactor before any implementation code is written. Six gated phases — obligation scan, red, green, obligation verify, coverage, lint. No feature code exists before Phase 1 clears; nothing reaches commit-gate until all six are green.
+disable-model-invocation: true
+---
+
+# tdd
+
+Test-first, or it does not ship. Routed to by `/feature` (after spec approval), `/fix`, and `/refactor`.
+
+## Pre-flight
+
+Read these, or STOP and surface the gap — never guess a command or a threshold:
+
+- `<project-root>/.codearbiter/CONTEXT.md` — the `stage:` frontmatter (the maturity value) and project context.
+- `<project-root>/.codearbiter/tech-stack.md` — test, coverage, and lint invocations; file layout; mock patterns.
+- `<project-root>/.codearbiter/coding-standards.md` — style, structure, naming. Required for Phase 3.
+- `<project-root>/.codearbiter/specs/<slug>.md` — the approved spec, when `/feature` produced one. It is the primary obligation source.
+- `<project-root>/.codearbiter/security-controls.md` — only when the change touches a security boundary (auth, crypto, secrets, a trust boundary). Optional; absent on most changes.
+- `<project-root>/.codearbiter/code-map.md` — if present, a coarse concern→path→role map to orient before writing tests and code. Absent is fine — it is read-on-demand, populated by context-creation or commit-gate heal.
+
+## Phase 1 — Obligation scan · gate: BLOCK
+
+An **obligation** is one verifiable claim about the change: (a) a unique ID, (b) a source citation,
+(c) a status. Status moves `OPEN → MAPPED → COVERED`; an obligation Phase 4 cannot tie to a passing
+test is `MISSING`. "We should test X" is not an obligation.
+
+Derive every obligation before any code is written, and record each as `ID · source · OPEN`:
+
+- **Spec** — one obligation per acceptance criterion in the approved spec.
+- **Contract** — API and input-validation invariants, error responses, boundary conditions.
+- **Security** — only when `security-controls.md` applies: the assertion that the security-relevant boundary holds.
+
+Gate: the obligation list is complete. **Auto-pass** when every obligation maps one-to-one onto the
+acceptance criteria of an already-approved spec (full-lane spec or small-lane mini-spec) — the user
+approved that list once; do not re-ask. **User review is required** only for obligations derived
+BEYOND the spec (Contract and Security rows): surface just those additions, not the whole list.
+Under `/sprint`, spec-derived obligations auto-pass the same way and beyond-spec additions are
+SMARTS-decided and logged like any other auto-decision. A partial list never passes either way.
+
+## Phase 2 — Red · gate: BLOCK
+
+Write one or more failing tests per obligation. Bind each test ID to its obligation ID and move that
+obligation `OPEN → MAPPED`. Run the test command from `tech-stack.md`.
+
+- Every new test MUST fail, and fail **for the right reason** — the assertion, not an import error or a typo. A new test that passes with no implementation is wrong; fix it before continuing.
+- Every pre-existing test MUST stay green. One that breaks here is a conflict — stop and surface it.
+
+Reject the standard traps: asserting on a mock instead of behavior; a test that can never fail; a
+snapshot so broad it asserts nothing; coupling to an implementation detail instead of observable
+behavior; asserting on the framework's behavior rather than your own.
+
+The reasons to skip red are known. Hearing one is the tell that this gate is about to be waived —
+never the license to waive it:
+
+| excuse | reality |
+|---|---|
+| "Too simple to fail first." | Simple changes have the cheapest red tests — and "too simple to test" and "too simple to break" have never been the same claim. |
+| "I'll write the test right after." | A test written after green has never been seen red: it is authored against the implementation it was meant to constrain, and its power to catch the bug is never demonstrated. |
+| "The test would just restate the implementation." | Then it is aimed at the wrong seam — assert the observable behavior, not the wiring. A change with no observable behavior to assert is a design finding, not an exemption. |
+| "The existing suite already covers this." | Then the failing test is impossible to write — try it. If it genuinely cannot go red, the obligation is already COVERED and Phase 4 records exactly that; if it goes red, the claim was wrong and you are holding the proof. |
+
+Gate: the runner confirms new tests red (for the right reason) and existing tests green, with every
+obligation `MAPPED` to a failing test. No implementation code is written until this gate clears.
+
+## Phase 3 — Green · gate: BLOCK
+
+Write the **minimum** implementation that satisfies the Phase 2 tests — no speculative logic, no
+gold-plating — to the conventions in `coding-standards.md`. Run the full suite. A broken pre-existing
+test is a regression: fix it.
+
+Gate: full suite green, reached by satisfying the Phase 2 tests — not by weakening them. A test's
+assertions MUST be unchanged between red and green; only fixtures and setup may move. A relaxed
+assertion is a gate violation.
+
+## Phase 4 — Obligation verify · gate: BLOCK
+
+Walk the Phase 1 list item by item. Each `MAPPED` obligation moves to `COVERED` (a real passing test
+that exercises the claim) or `MISSING` (no test truly covers it). For security-relevant or
+contract-critical logic, dispatch the `coverage-auditor` agent
+(`<plugin-root>/agents/coverage-auditor.md`) to confirm the tests exercise the claim.
+
+A `MISSING` obligation returns the workflow to Phase 2 — author a correct failing test, then re-run
+Phase 3 — and loops until it is `COVERED`.
+
+**Stakes:** when you block on a `MISSING` obligation, state what the untested seam leaves exposed, not
+just that it is `MISSING` — one line naming the consequence: "this error path is untested; a 500 here
+would reach users silently." The block is the rule; the stakes are why it is worth the friction.
+
+Gate: every obligation `COVERED`, each backed by a passing test. Any `MISSING` blocks Phase 5.
+
+## Phase 5 — Coverage · gate: BLOCK
+
+Coverage scales with the maturity value (`stage:` in `CONTEXT.md`) — a rigor knob, not a promotion
+gate. The threshold table is the shared `<plugin-root>/includes/maturity-coverage.md` (the
+single source of truth, also used by `refactor` Phase 2).
+
+Run the coverage command from `tech-stack.md`. **Lines and branches must both clear the threshold**
+— a report satisfying one and not the other does not pass (issue #507). Below it on either → add
+tests until both are met.
+
+**Name the host you measured on**, and for a tree `tech-stack.md` marks as platform-forked, the
+figure is the UNION across its supported hosts — a single-host report scores the other platform's
+arm as permanently uncovered (issue #521, conditions in `<plugin-root>/includes/maturity-coverage.md`).
+Where only one host is available, say so and name what is missing rather than quoting it as the
+whole.
+
+Where the surface has no coverage tooling at all, take the no-tooling exemption in
+`<plugin-root>/includes/maturity-coverage.md` — which requires QUOTING the `tech-stack.md`
+Coverage section that omits a command for this surface — and pass the phase on the Phase 4
+obligation verify alone. Without that citation the phase STOPs: "I could not find the command" and
+"this surface has none" look identical from here and demand opposite responses. Do NOT invent a
+command, and do NOT silently skip the phase as though it had been run — a gate that cannot execute
+still reads as satisfied, which is worse than an absent one.
+
+**Stakes:** when coverage blocks below threshold, name the class of code left dark — the paths a later
+regression could rot unnoticed — not just "below threshold." The number is the rule; the untested paths
+are why it matters.
+
+Gate: threshold met on BOTH lines and branches for the current maturity value, or the no-tooling
+exemption taken WITH its citation. A test added only to move the percentage fails this gate in
+spirit — it converts an honest red into a green that asserts nothing.
+
+## Phase 6 — Lint · gate: BLOCK
+
+Run lint, and the type-check if the project is statically typed, from `tech-stack.md`. Resolve every
+error.
+
+Gate: clean lint and type-check, zero errors — this is what clears the path to `commit-gate`.
+"Mostly passes" is not passing.
+
+## Hard rules
+
+- MUST NOT skip, suppress, or comment out a test to clear any gate.
+- MUST NOT mark an obligation `COVERED` without a passing test that exercises the claim.
+- MUST NOT lower a coverage threshold without a decision recorded in `CONTEXT.md`.
+- MUST NOT inline-suppress a lint rule without a written reason, and never to bypass a security-relevant rule.
+- MUST NOT guess the test, coverage, or lint command — read `tech-stack.md` or STOP.
+- MUST, at exit, run the follow-up harvest (`<plugin-root>/includes/harvest.md`) over any `[NEEDS-TRIAGE]` raised this run — batch-confirm promoting work to `open-tasks.md` and decisions to `open-questions.md` so nothing languishes; nothing auto-promotes interactively.