@arbiterforge/ca-pi 0.6.0

package/plugins/ca-pi/routines/tribunal/references/schemas.md

@@ -0,0 +1,58 @@
+# Orchestrator schemas & artifact layout
+
+The finding record (what agents emit) is in `finding-record.md`. This file holds the orchestrator-only logs and the run layout. Source of truth = the per-finding files (`findings/<lens>/<finding-id>.json`) plus the two append-only logs (`triage.jsonl`, `run.jsonl`); everything else is a projection regenerable from them. Write each record as it is produced — never batch.
+
+## Artifact tree
+
+```
+.codearbiter/reports/<run-id>/        # run-id = <UTC-date>-<scope-slug>
+  run.jsonl              # APPEND-ONLY run-state events; resume source of truth
+  manifest.yaml          # projection of run.jsonl (regenerable snapshot)
+  inventory.md           # map + risk/boundary/marker overlay
+  findings/<lens>/<finding-id>.json  # one finding per file, written on discovery
+                         # (crash-durable: a kill risks only the in-flight file;
+                         # per-lens dirs, so no write contention)
+  triage.jsonl           # APPEND-ONLY, one decision/line
+  bodies/<finding-id>.md # issue body, lazy, approved-only
+  plans/phase-<n>.md     # per-wave path plan (projection)
+  report.md              # final human-readable (projection)
+  issue-commands.sh      # ready-to-run gh issue create commands
+  telemetry.json         # KPI payload, opt-in
+```
+
+## triage/v1 — one object per line in `triage.jsonl`
+
+```json
+{"schema":"triage/v1","id":"<finding-id>","decision":"keep|combine|duplicate|false-positive|defer|accept-risk|decision-required|investigate","final_severity":"critical|high|medium|low","final_confidence":0.0,"counter_argument":"<steelman; required for critical+high>","rationale":"<why>","group_id":"<when combine>","duplicate_of":"<finding-id, when duplicate>","issue_ref":"<filled after filing>","decided_at":"<iso8601>"}
+```
+
+`final_*` override the provisional self-scores everywhere downstream. `issue_ref` closes the finding→issue loop and makes re-runs idempotent.
+
+## run/v1 — one state event per line in `run.jsonl`
+
+```json
+{"schema":"run/v1","event":"run-started|lens-launched|lens-skipped|lens-completed|wave-flushed|wave-triaged|report-written|issues-filed|telemetry-sent|run-aborted","wave":1,"lens":"<lens>","detail":"<optional>","surface_seen":0,"findings":0,"model":"<model>","tokens":0,"at":"<iso8601>"}
+```
+
+`run-aborted` records a deliberate abandon (optional `detail` = reason) and marks the run terminal.
+
+A `lens-completed` event carries `surface_seen` (int — the lens's Exposure denominator), `findings` (int — count the lens emitted), and `model` (the model the lens ran on, as dispatched); `model` also appears on `lens-launched`. `tokens` (int, optional) records the lens's observed token spend when the orchestrator can see it; null/omitted when unobserved.
+
+The `run-started` event's `detail` carries the chosen wave partition — the lens list per wave (default or repartitioned-for-cause, per `cost-and-models.md`). This is the single record of the partition; nothing else derives or re-derives it.
+
+## Resume — read the cursor, never the finding bodies
+
+`run.jsonl` is the coarse state log — one line per wave/lens transition, tens of lines even across retries, not the per-finding logs. Resume reads the cursor, not the whole run, and never re-hydrates completed work:
+
+0. **No `run-started`.** A run dir present but with no `run-started` event in `run.jsonl` is a Phase-0/1 death — restart Phase 0/1 fresh (`inventory.md` and lens selection are cheap to rebuild); any finding files already on disk stand and are deduped at triage as normal.
+1. **Position.** The resume point is fixed by the last triaged wave: `grep '"event":"wave-triaged"' run.jsonl | tail -1` returns it while reading only matching lines. If none, resume at wave 1.
+2. **Plan.** Read the wave partition from the `run-started` event's `detail` — the recorded partition, never re-derived — via `manifest.yaml` (a small projection) or, if it is missing or stale, `run.jsonl` directly. Both are bounded reads — never a full-file scan for the plan.
+3. **Re-enter** Phase 2/3 for waves after the last triaged one only.
+4. **Do not load** already-triaged waves' `findings/<lens>/` files or `triage.jsonl` into context — they are authoritative on disk. A later wave's dedup that needs a specific prior id fetches it by targeted `grep` across `findings/`, never a full read.
+5. **Ordering.** `plans/phase-<n>.md` is written before the `wave-triaged` event for that wave is emitted — the event asserts the plan exists.
+
+`manifest.yaml` is a convenience snapshot regenerated from `run.jsonl`; it accelerates the plan read but is never authoritative — a corrupt or stale manifest falls back to the append-only log.
+
+## dedup_key & ids
+
+`id`: `<lens>-NNN`, sequential per lens. `dedup_key`: `<lens>:<path-normalized-to-repo-root>:<short-slug-of-title>`. Dedup matches on `dedup_key` and overlapping `locations`.

package/plugins/ca-pi/routines/tribunal/references/telemetry.md

@@ -0,0 +1,28 @@
+# Telemetry (opt-in, KPI-only)
+
+Optional feedback that refines the skill and calibrates the estimator, pooled across contributors. The target is the public codeArbiter repo, so a shared corpus needs a shared destination — which is safe only because the payload is boring by construction: aggregates and per-lens exposure counts, never anything that identifies a codebase or exposes a weakness. Off by default; sent only on explicit per-run authorization.
+
+## Hard scrubbing
+
+The payload carries integers and enums only. It MUST NOT contain code, file paths, finding titles or text, commit hashes, or remote URLs. Repo identity is omitted by default; a contributor who wants to self-tag their submission for their own cross-run tracking may add `--tag <label>`, and only then does `tag` appear. `run_id` is a fresh random value, not derived from the repo.
+
+## Why exposure counts, not raw findings
+
+A raw finding count is uninterpretable alone: it is base-rate x detector-sensitivity x exposure, and you cannot invert the product from one number. "0 SQL-injection findings" reads as both "nobody concatenates SQL" and "our appsec lens is blind" — and those resolve oppositely. The per-lens `surface_seen` denominator disambiguates: 0 against a large surface is a blind-spot alarm; 0 against no surface is correctly uninformative. `false_positives` (from the decision log) separates a silent lens from a noisy one. These fields let the corpus *flag* blind-vs-rare; they cannot *confirm* it — that needs ground truth (a seeded-vulnerability canary or a semgrep/CodeQL cross-check), which is a separate self-test, not a payload field.
+
+Reading the corpus is the maintainer's judgment, not skill behavior — and a suspicious zero in a security lens defaults to suspecting the detector, never to dialing the lens back, because those costs are asymmetric.
+
+## Payload — `telemetry.json`
+
+```json
+{"schema":"telemetry/v1","skill_version":"<x.y.z>","run_id":"<random>","at":"<iso8601>","tag":"<omitted unless --tag>","loc_total":0,"loc_by_language":{"<lang>":0},"files_scanned":0,"primary_language":"<lang>","lenses_run":0,"lenses_skipped":0,"model_orchestrator":"<api-string>","models_by_tier":{"opus":0,"sonnet":0,"haiku":0},"tokens_estimated":0,"tokens_actual":null,"lens_exposure":{"<lens>":{"ran":true,"surface_seen":0,"findings":0,"false_positives":0}},"issues_found":0,"severity_breakdown":{"critical":0,"high":0,"medium":0,"low":0},"decision_breakdown":{"keep":0,"combine":0,"duplicate":0,"false_positive":0,"defer":0,"accept_risk":0,"decision_required":0,"investigate":0},"issues_filed":0,"run_duration_sec":0}
+```
+
+`lens_exposure` is the field that makes the corpus interpretable; `surface_seen` and `model_orchestrator`/`models_by_tier` are sourced from `run.jsonl` `lens-launched`/`lens-completed` events, not hand-tallied. `tokens_estimated` vs `tokens_actual` calibrates the cost estimate (a guardrail, not a measure of review quality); `tokens_actual` sums `run.jsonl` `lens-completed` `tokens` when present, and is otherwise optional/best-effort — null when the orchestrator could not observe subagent spend. `issues_found` is the post-triage kept count (the `keep` + `combine` decision groups), distinct from the per-lens raw `findings` counts in `lens_exposure`. `skill_version` is read from `plugin.json`, not hand-set.
+
+## Send procedure
+
+- Write `telemetry.json`; show it in full.
+- State plainly, in one line: these aggregates post publicly to the codeArbiter repo; they carry no code, paths, or finding text, and no repo identity unless you added `--tag`.
+- **Default:** print `gh issue create --repo arbiterForge/codeArbiter --label telemetry --title "run-metrics <at>" --body-file telemetry.json`. Stop.
+- **On explicit approval:** run it; record a `telemetry-sent` event in `run.jsonl`.

package/plugins/ca-pi/routines/tribunal/references/triage.md

@@ -0,0 +1,53 @@
+# Triage & calibration
+
+Triage per wave from disk. The orchestrator's calibrated values are final and override every provisional self-score downstream.
+
+## Dedup
+
+Before calibrating, dedup each new finding against all findings already on disk — match by `dedup_key` and by overlapping locations. A match decides as `duplicate` (`duplicate_of` set), distinct from `combine`.
+
+## Severity rubric (impact x likelihood)
+
+- **critical** — exploitable security hole, data loss/corruption, or an outage path reachable with realistic input.
+- **high** — serious correctness/security weakness, latent but plausible; or a systemic architectural defect amplifying other risk.
+- **medium** — real defect/debt, limited blast radius or lower likelihood.
+- **low** — minor quality, polish, or DX improvement.
+
+## Calibration
+
+For each finding, set `final_severity`/`final_confidence` from the evidence directly — the lens's values are provisional input. For every critical/high, record a `counter_argument` — the strongest case it is lower or a false positive; if compelling, downgrade or reclassify. Calibration is bidirectional: promote under-rated findings too. Optional for criticals: dispatch a fresh-context adversary that sees only the finding + code and tries to refute it, to defeat anchoring.
+
+## Severity priors
+
+Apply as priors on findings that already cleared evidence-or-drop, never to manufacture one: resource-level authz / IDOR → high or critical; injection with reachable user input → high or critical; literal secret → high or critical; async operation with no handler on a critical path → high. A high-marker/high-iteration location (per `ai-markers.md`) nudges one level at most.
+
+## Confidence gate
+
+The bar a finding's `final_confidence` must clear to file, tiered by severity — an uncertain critical is too costly to bury silently, so it gets a lower bar and a softer landing than a low:
+
+| `final_severity` | gate | below the gate |
+| --- | --- | --- |
+| critical / high | ≥0.5 | → `decision-required`, framed as a question, never dropped silently |
+| medium | ≥0.7 | → `investigate` |
+| low | ≥0.75 | → `investigate` |
+
+## Low-severity discipline
+
+A `low` is kept only above the confidence gate (≥0.75, see above) with a concrete, actionable remediation. Beyond ~5 lows per lens, aggregate the remainder into a single rollup finding that still lists each `path:line`.
+
+## Decision vocabulary (into `triage.jsonl`)
+
+- **keep** — actionable fix; files as its own issue.
+- **combine** — real, merged with siblings under a shared `group_id`; one issue.
+- **duplicate** — identical to a recorded finding (`duplicate_of`); distinct from combine.
+- **false-positive** — not real; `rationale` required (this tunes future-run noise down — keep it).
+- **defer** — real, out of scope/priority now; preserved, not filed this run.
+- **accept-risk** — real, consciously not fixing; the risk-acceptance trail.
+- **decision-required** — real and significant, but the response is an ADR-grade design choice, not a clear fix; files as a discussion, not a fix ticket.
+- **investigate** — undecided, or a medium/low below the confidence gate after calibration; never filed.
+
+Below the confidence gate after calibration: medium/low → `investigate`; critical/high → `decision-required` (see Confidence gate above — never dropped silently). ADR-grade questions also → `decision-required`.
+
+## Per-wave plan
+
+`plans/phase-<n>.md` covers only `keep`/`combine`, grouped by type (lens/category/`group_id`): shared remediation approach, ordered sequence, cross-group `depends_on`, rolled-up acceptance criteria. Roadmap level only — no per-finding code steps. A `decision-required` item gets a one-line "ADR-candidate — resolve via `/ca-adr`" pointer, never an authored ADR.

package/plugins/ca-pi/routines/using-git-worktrees/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: using-git-worktrees
+description: OPTIONAL per-task isolation for autonomous parallel work. Routed to only on explicit opt-in by subagent-driven-development or dispatching-parallel-agents, so parallel units mutate files without colliding. Stands up one worktree per unit, works it in isolation, then integrates each unit back onto the caller's working branch for the caller's single commit-gate + finishing-a-development-branch exit. Never on the default path; it does not bypass a gate or finish per unit.
+disable-model-invocation: true
+---
+
+# using-git-worktrees
+
+OPTIONAL. Per-task filesystem isolation for parallel agent work — opt-in only, never the default path.
+Routed to by `subagent-driven-development` and `dispatching-parallel-agents` when, and only when, the
+caller requests isolation. If no isolation is requested, this skill does not run; parallel units share
+the working tree under their own discipline.
+
+Isolation is convenience, not soul. It lets concurrent units edit files without collision. It changes
+nothing about the gates — the consolidated work still clears `commit-gate` and the single
+`finishing-a-development-branch` terminal step, run by the caller. What it MUST NOT do is multiply
+that terminal step into one PR per unit.
+
+## Pre-flight
+
+Read these, or STOP and surface the gap — never guess:
+
+- `<project-root>/.codearbiter/CONTEXT.md` — confirm the repo is a git repo and the base/working branch.
+
+Confirm the caller passed an explicit isolation opt-in AND the parallel unit list (from `plans/<slug>.md`). Absent either, do not stand up worktrees.
+
+## Phase 1 — Provision · gate: BLOCK
+
+Stand up one worktree per parallel unit. For each unit, create a worktree on a fresh branch off the
+current base, under a dedicated parent directory outside the main working tree
+(e.g. `../.codearbiter-worktrees/<slug>`):
+
+- One worktree, one branch, one unit. Never share a worktree across units.
+- Branch name MUST be unique and traceable to its unit's task ID.
+- Record each worktree path and branch in a dedicated manifest `<project-root>/.codearbiter/.worktrees.json` (gitignored scratch — NOT the `open-tasks.md` backlog) so a crash leaves no untracked isolation.
+
+Gate: every unit has a distinct worktree on a distinct branch, all rooted at the same clean base, all
+recorded. A reused branch or a missing record does not pass.
+
+## Phase 2 — Isolated work · gate: BLOCK
+
+Each parallel unit works entirely inside its own worktree. Dispatch is unchanged — the caller still
+dispatches its author and reviewer agents; they simply operate on the isolated path.
+
+- A unit MUST NOT read or write outside its assigned worktree.
+- A unit MUST NOT touch `main` or any other unit's branch.
+- All implementation inside a worktree still flows through `tdd` — isolation is not a TDD bypass.
+
+Gate: each unit's work is contained to its own worktree, with no cross-worktree or base-branch writes.
+
+## Phase 3 — Fold back · gate: BLOCK
+
+Integrate each isolated unit's work back onto the caller's single working branch — do NOT finish each
+unit on its own. Per unit, in order:
+
+1. Confirm the unit was accepted by the caller (its per-task review and verification passed in
+   `subagent-driven-development`, or its result cleared the funnel in `dispatching-parallel-agents`).
+   An unaccepted unit does not fold back.
+2. Integrate its branch onto the caller's working branch (merge or rebase), resolving any conflict
+   here, in the open. Never integrate onto `main` or the default branch.
+
+The consolidated working branch then takes the caller's normal single exit — ONE `commit-gate` pass
+and ONE `finishing-a-development-branch` decision, run by the caller, not per unit. This skill
+integrates; it never opens N PRs or finishes N branches. A unit that cannot integrate cleanly is
+surfaced as a conflict for resolution — never force-merged, never dropped silently.
+
+Gate: every accepted unit integrated onto the caller's working branch with conflicts resolved; no
+per-unit PR or finish was opened.
+
+## Phase 4 — Teardown · gate: BLOCK
+
+Remove every worktree this skill created, prune its administrative metadata, and clear the manifest at
+`<project-root>/.codearbiter/.worktrees.json`. A unit whose branch was integrated onto the
+working branch (Phase 3) has its worktree torn down; an unaccepted or abandoned unit's worktree and
+branch are removed together.
+
+Gate: zero worktrees created by this skill remain, and the manifest is empty. An orphaned worktree is a failure.
+
+## Hard rules
+
+- MUST NOT run on the default path — isolation requires an explicit caller opt-in.
+- MUST NOT share a worktree or a branch across parallel units.
+- MUST NOT let a unit read or write outside its assigned worktree, or touch `main`.
+- MUST NOT open a per-unit PR or run `finishing-a-development-branch` per unit — integrate accepted units onto the caller's working branch, which takes the single `commit-gate` + finishing exit.
+- MUST NOT leave an orphaned worktree behind — every worktree this skill creates is torn down before the skill returns.

package/plugins/ca-pi/routines/writing-plans/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: writing-plans
+description: The spec-to-plan bridge. Routed to by /feature once the brainstormed spec is approved, and by /sprint before execution. Decomposes the spec into 2–5 minute tasks, each carrying its exact file path(s) and a concrete verification step that maps to a tdd obligation. Writes the plan to .codearbiter/plans/<slug>.md, ordered with dependencies flagged and an MVP slice identifiable. Nothing executes until every task has a path and a verification and the task set covers every acceptance criterion.
+disable-model-invocation: true
+---
+
+# writing-plans
+
+Turn an approved spec into an executable plan. Routed to by `/feature` (after spec approval) and `/sprint`.
+
+## Pre-flight
+
+Read these, or STOP and surface the gap — never plan against an unapproved or missing spec:
+
+- `<project-root>/.codearbiter/specs/<slug>.md` — the approved brainstorming spec. The single source of acceptance criteria. Absent or unapproved → STOP and route back to `/feature`.
+- `<project-root>/.codearbiter/CONTEXT.md` — the `stage:` frontmatter (the maturity value) and project context.
+- `<project-root>/.codearbiter/tech-stack.md` — file layout, build/test/lint invocations. A verification step cites a real command from here, never a guess.
+- `<project-root>/.codearbiter/coding-standards.md` — structure and naming, so a task names the right path.
+
+**If `--farm` was requested:** check that `FARM_API_KEY` is set in the environment of the Pi parent process. If absent, BLOCK immediately — cite `<plugin-root>/includes/farm.md` for setup instructions. Do not proceed; the farm dispatcher cannot run without an API key. Model selection happens later (at dispatch time in `subagent-driven-development`), so no model research is needed here.
+
+## Phase 1 — Criterion extraction · gate: BLOCK
+
+Lift every acceptance criterion from the spec verbatim and assign each a stable ID (`AC-01`,
+`AC-02`, …). This list is the coverage ledger for the whole plan — Phase 4 checks the task set
+against it.
+
+A criterion the spec leaves ambiguous is a `[CONFIRM-NN]` against
+`<project-root>/.codearbiter/open-questions.md` — surface it, do not invent the intent.
+
+**Backstop the ledger against the spec's own stated intent, mechanically, before trusting it — this
+runs even when `brainstorming` already ran the same check, because a hole that survived Phase 3
+survives Phase 4's bijection too, silently** (#566): run `"$PY" "<plugin-root>/hooks/_intentlib.py"
+uncovered-intent <project-root>/.codearbiter/specs/<slug>.md [--issue-body <scratch-file>]` —
+`<scratch-file>` holds the linked issue's body when one exists (`gh issue view <N> --json body -q
+.body > <scratch-file>`, written outside the working tree), omitted when none does. A non-empty
+result names an in-scope bullet or an acceptance checkbox the criteria never cited — BLOCK and route
+back to `brainstorming` (`<plugin-root>/routines/brainstorming/SKILL.md`) to add the missing criterion or record a `[CONFIRM-NN]`; never paper over a
+missing criterion by authoring a task for it here instead. This is the LAST point before a hole gets
+laundered through Phase 4's bijection, which only checks the ledger against itself and cannot see
+past it.
+
+Then ask the half this tool cannot mechanize: **if every `AC-NN` passed and nothing else changed,
+what would still be broken?** A real answer names a criterion the ledger is missing even though
+every scope bullet and checkbox is technically cited — judgment, not mechanizable, and not satisfied
+by a rhetorical "nothing." Finding nothing broken is a reportable result, stated in one line, never a
+silent skip.
+
+Gate: every acceptance criterion in the spec captured as a numbered `AC-NN`; the `uncovered_intent`
+backstop above returns empty or every finding is resolved; and the negative question has been asked
+and answered. A partial ledger does not pass.
+
+## Phase 2 — Task decomposition · gate: BLOCK
+
+Break the work into the smallest honest units. Each **task** is ~2–5 minutes of work and carries:
+
+- **id** — `T-01`, `T-02`, … stable.
+- **path(s)** — the exact file(s) the task touches, resolved against `coding-standards.md`. "Some files" is not a path.
+- **verification** — one concrete command or observable that proves the task done (e.g., `<test cmd> -k test_token_expiry passes`, `endpoint returns 401 on missing header`). It cites a real `tech-stack.md` invocation or a directly observable behavior — never "looks right".
+- **maps-to** — the `tdd` obligation this verification corresponds to. The verification *maps to* a tdd obligation; it does NOT replace tdd's own gates. `tdd` Phase 1 still derives and Phase 4 still verifies obligations against passing tests.
+- **covers** — the `AC-NN`(s) this task advances.
+
+Split anything that won't fit ~5 minutes or touches unrelated paths. Reject the trap of one
+monolithic "implement the feature" task — that defeats the plan.
+
+Gate: every task has at least one path AND a verification AND a `maps-to`. A task missing any of the
+three blocks the plan.
+
+## Phase 3 — Order & MVP slice · gate: BLOCK
+
+Order tasks so each runs only after what it depends on. Flag every dependency explicitly
+(`T-07 depends on T-03`). A cycle is a decomposition error — return to Phase 2 and split.
+
+Group the ordered tasks so the **MVP slice** is identifiable: the minimal contiguous task set that
+satisfies the spec's core acceptance criteria and is shippable on its own. Everything past the slice
+is incremental.
+
+Gate: a complete dependency order with no cycle, and an explicitly marked MVP slice.
+
+## Phase 4 — Bijection proof & write · gate: BLOCK
+
+Cross the ledger against the task set, both directions. **This proves the plan and the ledger AGREE
+with each other — it does not prove the ledger itself is COMPLETE relative to the spec's stated
+intent.** A criterion missing from the ledger entirely was never a candidate for either check below;
+that completeness gap is caught earlier, by Phase 1's `uncovered_intent` backstop (and by
+`brainstorming` Phase 3 before that) — never re-derived here, and never implied by this phase's name
+(#566: a prior version of this gate read "coverage proof", which a bijective check does not earn).
+
+- Every `AC-NN` is covered by at least one task's `covers`. An uncovered criterion blocks — author the missing task.
+- Every task advances at least one `AC-NN`. A task that covers nothing is scope creep — cut it or surface it.
+
+Then write the plan to `<project-root>/.codearbiter/plans/<slug>.md` — `<slug>` matching the
+spec — with the `AC-NN` ledger, the ordered task table (id · path(s) · verification · maps-to ·
+covers · depends-on · **status**, initialized `PENDING`), the marked MVP slice, and any out-of-scope
+item tagged inline `[NEEDS-TRIAGE]`.
+
+The status column is the pipeline's resume ledger: `subagent-driven-development` flips a task to
+`ACCEPTED` the moment it accepts it, so an interrupted run (crash, compaction, closed session) is
+re-entered by `/feature` at the first non-`ACCEPTED` task instead of restarted from brainstorming.
+
+Gate: bijection proven between the plan and the ledger — no criterion without a task, no task without
+a criterion — and the plan written to disk. This proves the two are mutually consistent, nothing more;
+completeness of the ledger itself was Phase 1's gate, not this one. This clears the path to execution:
+`executing-plans` (checkpointed, via `/feature`) or `subagent-driven-development` (autonomous, via
+`/sprint`) — each routes every task through `tdd`. The plan never hands off to `tdd` directly.
+
+### Phase 4-farm extension (only when `--farm` was requested)
+
+When `--farm` was requested, after the bijective coverage gate passes and the `.md` plan is written,
+produce the farm artifact (`plan.json`) — **one MVP slice at a time** — per
+`<plugin-root>/routines/writing-plans/references/farm-plan.md`. Load that leaf and follow it;
+it owns the per-task failing-test + schema-valid `plan.json` procedure.
+
+Gate: all failing tests written and confirmed failing; `plan.json` written and schema-valid. Both
+artifacts exist before handing off to `subagent-driven-development` (`<plugin-root>/routines/subagent-driven-development/SKILL.md`).
+
+## Hard rules
+
+- MUST NOT plan against an absent or unapproved spec — STOP and route back to `/feature`.
+- MUST NOT emit a task without an exact path AND a concrete verification step.
+- MUST NOT let a task's verification stand in for a `tdd` gate — it maps to a tdd obligation, it does not replace one.
+- MUST NOT write the plan while any acceptance criterion is uncovered or any task covers nothing.
+- MUST NOT guess a verification command — cite `tech-stack.md` or STOP.
+- MUST NOT resolve an ambiguous criterion by guessing — raise a `[CONFIRM-NN]`.
+- MUST run the `uncovered_intent` backstop and ask the negative-judgment question in Phase 1, and MUST NOT treat Phase 4's bijection proof as a substitute — bijection proves the plan and the ledger agree with each other, never that the ledger is complete (#566).
+- MUST NOT emit `plan.json` in `--farm` mode without writing and confirming each failing test first.
+- MUST NOT set `meta.model` or `meta.apiBaseUrl` in `plan.json` — these belong to the dispatch step.
+- MUST NOT proceed with `--farm` if `FARM_API_KEY` is absent — cite `<plugin-root>/includes/farm.md` and BLOCK.
+- MUST, at exit, run the follow-up harvest (`<plugin-root>/includes/harvest.md`) over any `[NEEDS-TRIAGE]` out-of-scope items — batch-confirm promoting them to `open-tasks.md` (work) or `open-questions.md` (decisions) so they don't die in the plan file.

package/plugins/ca-pi/routines/writing-plans/references/farm-plan.md

@@ -0,0 +1,50 @@
+# writing-plans — `--farm` plan.json extension
+
+Loaded by `writing-plans` Phase 4 only when `--farm` was requested. The base plan (Phases 1–4) is
+unchanged; this leaf adds the machine artifact the farm dispatcher needs.
+
+After the bijective coverage gate passes and the `.md` plan is written, produce the farm artifact —
+**one MVP slice at a time, not the whole plan up front.** Front-loading every failing test for the
+entire plan would be the waterfall this skill otherwise rejects (Phase 3), and it maximizes the cost
+of a mid-flight spec change. So the farm artifact is scoped to the **current slice** (the MVP slice on
+the first pass; the next contiguous group on later passes). For each task in the current slice, in
+dependency order:
+
+1. Route through `tdd` Phase 1 (derive obligations) + Phase 2 (write the failing test). The test file
+   must exist on disk and fail before continuing. Record the test file path for this task.
+2. Confirm the test is actually failing (run the gate command from `tech-stack.md`; it must exit
+   non-zero). A test that passes before implementation means the obligation is wrong — STOP and revisit
+   Phase 2.
+
+Then write `<project-root>/.codearbiter/plans/<slug>.plan.json` (the current slice's tasks only)
+conforming to `<plugin-root>/tools/plan.schema.json`:
+
+- `meta.name` ← slug
+- `meta.repo` ← project name from CONTEXT.md
+- `meta.model` and `meta.apiBaseUrl` — **leave unset**. These are written by
+  `subagent-driven-development`'s model research step at dispatch time. Writing them here would bake in
+  a potentially stale selection.
+- Per task: `id` ← T-NN (normalized to kebab-case), `description` ← task description,
+  `filesInScope` ← path(s) from the task table, `test.path` ← the failing test written above,
+  `gate.commands` ← verification command from task table plus full-suite and lint/typecheck from
+  `tech-stack.md`, `deps` ← dependency ids (empty array if none), `context` ← a minimal slice of
+  relevant types/interfaces (omit if the test file plus task description is self-contained),
+  `maxRetries` ← omit to use the farm default.
+- **`gate.commands[0]` MUST be the task's narrow behavioral test** (the command that runs just
+  `test.path`), with the full suite and lint/typecheck following. The farm's mutation guard re-runs
+  `gate.commands[0]` per mutant; if the first command were the full suite, mutation testing would be
+  prohibitively slow.
+
+Validate the JSON against the schema before writing (load the schema from
+`<plugin-root>/tools/plan.schema.json` and check). A schema-invalid plan BLOCKS.
+
+`plan.schema.json` is the **authoring** contract. The dispatcher enforces its own **runtime** contract
+(`PLAN_SHAPE` / `parsePlan()` in `farm.ts`) on the parsed JSON before it touches a single field, and
+that one is authoritative: a plan that fails it exits before any worktree, branch, report, or network
+call. The two are kept identical key-for-key and type-for-type by a parity test, so a plan that
+satisfies the schema is accepted at runtime — with one deliberate exception, the kebab-case `id`
+pattern, which is stricter here than the runtime path-safety rule. Both objects are closed: an
+undeclared property is an error, not an ignored extra.
+
+Gate: all failing tests written and confirmed failing; `plan.json` written and schema-valid. Both
+artifacts exist before handing off to `subagent-driven-development`.

package/plugins/ca-pi/skills/ca-add-dep/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: ca-add-dep
+description: Vet a new or changed third-party dependency for license, provenance, and supply-chain risk before any install runs.
+argument-hint: "<package[@version]>"
+---
+
+# /ca-add-dep — dependency review
+
+Gate a new or changed third-party dependency through review before it lands. When you route through
+this command, the orchestrator runs no install until the `dependency-reviewer` agent clears the
+package. Specify the exact version if you have one; without one, the reviewer evaluates the latest
+available version.
+
+## Routes to
+
+The `dependency-reviewer` agent (`<plugin-root>/agents/dependency-reviewer.md`). The agent
+reads `<project-root>/.codearbiter/security-controls.md` (allowed/denied licenses, provenance
+and supply-chain policy) and `<project-root>/.codearbiter/tech-stack.md` (stack fit, dependency
+manager) to judge the package.
+
+After the agent clears it, the orchestrator surfaces the install command for confirmation. The lock
+file change is committed alongside the manifest change — never one without the other.
+
+## When NOT to use
+
+- Removing a dependency → `/ca-fix` or `/ca-feature` with the change described.
+- Updating an existing dependency as part of a code change → `/ca-feature` / `/ca-fix`; manifest
+  changes route to review at `/ca-pr`.
+- Asking about a package without installing it → `/ca-btw`.
+
+## Ephemeral tool run — one invocation, nothing adopted
+
+A one-time developer tool is not a dependency, and reviewing it as one is what
+issue #346 records going wrong: a duplicate-code investigation was interrupted
+and pushed toward project-dependency review for `jscpd`, which the operator had
+explicitly said must never be listed as a dependency. The redirect loop then
+reached for `/ca-override`, a bypass invented to cover missing coverage. This
+section is that coverage.
+
+**The distinction is the dependency GRAPH, not the download.** Adopting or
+changing anything that enters `package.json`, a lockfile, or a base image is the
+review above, unchanged. Running a pinned tool once, against the repository,
+adopting nothing, is this.
+
+Route here when ALL of these hold. If any is unclear, it is a dependency and
+takes the full review:
+
+1. The operator asked for this specific tool, by name, in this session.
+2. It runs ONCE, for inspection or analysis. It is not wired into a script, a
+   hook, or CI.
+3. Nothing it does may change a manifest, a lockfile, or a committed artifact.
+
+Then:
+
+- **Pin the exact version.** `npx jscpd@4.0.5 .`, never bare `npx jscpd` — an
+  unpinned invocation resolves to whatever was published this morning, which is
+  the supply-chain exposure the review exists for and the one part of it that
+  still applies at full strength.
+- **Use the approved registry.** `https://registry.npmjs.org` is the only one
+  (`security-controls.md`); no `git+`, no `file:`, no non-TLS source.
+- **Confirm before running**, naming the exact command. One approval, not a
+  review — the operator has already made the adoption decision, which is "no".
+- **Isolate what you can.** Prefer a cache directory under the system temp dir
+  over the project tree, and write any report there too, so the run leaves no
+  residue a later commit could pick up.
+- **Report what ran** — the pinned command and where its output went.
+
+**Hard gate: MUST NOT modify a manifest or a lockfile.** If the tool writes one,
+that is adoption, and it stops here and routes to the review above. Verify
+rather than trust: `git status --porcelain` over the manifest and lockfile paths
+must be unchanged after the run. A tool that requires adoption to run at all is
+a dependency, and saying so is the correct answer.
+
+This is a bounded carve-out inside this command, not a command of its own
+(ADR-0023). A new command would add a public surface — the catalog, the Pi
+command catalog, the README counts, the site sidebar — to govern an action whose
+whole definition is that it changes nothing.
+
+## Hard gate
+
+MUST NOT install before `dependency-reviewer` clears the package. BLOCK on a denied license or any
+unresolved supply-chain or provenance concern.
+
+This gate is **orchestrator-enforced, not hook-enforced**: unlike the crypto/secret gate
+(`pre-bash.py` H-09b/H-10b), there is no pre-bash rule that blocks a bare `npm`/`pip`/`yarn`/`pnpm
+install` typed outside this command. The discipline depends on routing installs through `/ca-add-dep`.
+A hook-level install block (parallel to the security-gate marker) would be a stronger posture, but is a
+deliberate behavior change — a possible future enhancement, not the current contract.

package/plugins/ca-pi/skills/ca-adr/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: ca-adr
+description: Author a numbered, dated, user-attributed Architecture Decision Record under .codearbiter/decisions/.
+argument-hint: "<decision title>"
+---
+
+# /ca-adr — author an ADR
+
+Record an architectural decision as a numbered, dated ADR. Title the decision clearly — name what was
+decided, not what was considered (`"Use PostgreSQL as the primary database"`, not
+`"Database selection"`). This is the only sanctioned path to author an ADR.
+
+## Routes to
+
+The `decision-lifecycle` skill (`<plugin-root>/routines/decision-lifecycle/SKILL.md`). The skill
+owns numbering, the file template, the `proposed → accepted → superseded | rejected` status lifecycle,
+and writes the file to `<project-root>/.codearbiter/decisions/`. Status transitions require
+explicit user instruction; the orchestrator never advances an ADR on its own.
+
+## When NOT to use
+
+- Check the health of existing ADRs → `/ca-adr-status`.
+- Reconcile or challenge a suspect ADR → `/ca-reconcile`.
+- Ask about a decision without recording it → `/ca-btw`.
+
+## Hard gate
+
+An ADR is authored ONLY via `/ca-adr` with explicit user attribution. MUST NOT author an ADR as the
+disposition of a routine finding — decision-worthy findings surface to the user or to
+`open-questions.md` as a `[CONFIRM-NN]`. MUST NOT resolve a `[CONFIRM-NN]` in the ADR by guessing.

package/plugins/ca-pi/skills/ca-adr-status/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: ca-adr-status
+description: Report the health of Architecture Decision Records — aged, unchallenged, supersession candidates, unresolved CONFIRM-NN. Read-only.
+argument-hint: "(none) | --adr N"
+---
+
+# /ca-adr-status — ADR health scan
+
+Survey the health of recorded ADRs. Read-only — no file is modified. With `--adr N` the scan focuses
+on a single ADR; with no argument it scans every ADR under
+`<project-root>/.codearbiter/decisions/`.
+
+## Routes to
+
+The `decision-lifecycle` skill (`<plugin-root>/routines/decision-lifecycle/SKILL.md`) in its
+health-scan mode. For each ADR it flags: aged decisions, `proposed` ADRs never challenged,
+supersession candidates (a newer ADR or code pattern contradicts the decision), and unresolved
+`[CONFIRM-NN]` placeholders. Findings aggregate into a structured report; nothing is changed.
+
+## When NOT to use
+
+- Author a new ADR → `/ca-adr`.
+- Challenge or reconcile a specific ADR in depth → `/ca-reconcile`.
+- Ask what a specific ADR says → `/ca-btw`.
+
+## Hard gate
+
+Read-only — MUST NOT modify any file. MUST NOT resolve a `[CONFIRM-NN]` found during the scan —
+surface it and stop. A supersession candidate that contradicts an accepted ADR is flagged for
+`/ca-conflict`.

package/plugins/ca-pi/skills/ca-arbiter/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: ca-arbiter
+description: Exit maintainer dev mode — restore orchestration, remove the dev marker, log the exit.
+argument-hint: (none)
+---
+
+# /ca-arbiter — restore orchestration
+
+The exit door for `/ca-dev`. No-op if dev mode is not active.
+
+## Flow
+
+1. **Log exit** — append to `<project-root>/.codearbiter/overrides.log` (append-only, `>>`):
+
+   ```
+   [ISO-8601 timestamp] | BY: <email> | DEV: exit
+   ```
+
+2. **Marker** — remove `<project-root>/.codearbiter/.markers/dev-active`.
+3. **Resume** — re-present the startup state (stage, blocking `CONFIRM-NN`, in-flight tasks) and
+   await a slash command. Orchestration, routing, and all gates are back in force.
+
+## Hard gate
+
+MUST write the `DEV: exit` line to `overrides.log` and remove the `dev-active` marker before resuming
+orchestration — the exit is on the audit trail like the entry. MUST NOT rewrite or truncate
+`overrides.log` — the append-only rule has no dev exception, on entry or exit. If a prior session
+ended mid-dev, SessionStart has already appended the synthetic `BY: session-cleanup | DEV: exit` close
+line and cleared the marker (`session-start.py`, observability-001). In that case MUST NOT write a
+second `DEV: exit` for that orphaned entry — the close is already on the trail.
+
+Session-scoped clearing (#271): SessionStart's synthetic close is now conditional on the marker
+plausibly being abandoned rather than owned by a different, still-live session — it will NOT clobber
+another concurrently-running session's live `/dev` marker or write a false `DEV: exit` for it.
+`/ca-arbiter` remains the ONLY way to cleanly close your OWN `/dev` session's audit pair; do not
+rely on a future SessionStart to do it for you.