@arbiterforge/ca-pi 0.6.0

package/plugins/ca-pi/includes/reference-map.md

@@ -0,0 +1,22 @@
+# Reference map
+
+Loaded on a scope-touch: before acting on code in one of these rows, read the governing doc first,
+then route to the owning skill or agent. This map answers *what to read before touching a scope*; for
+*what to invoke or route given a trigger*, use `routing-table.md`. "Read first" paths are under
+`<project-root>/.codearbiter/` unless the row gives a `<plugin-root>/` path.
+
+| If the change touches… | Read first | Route to |
+|---|---|---|
+| Any code change | `coding-standards.md` | `tdd` skill |
+| Stack / dependencies | `tech-stack.md`, `security-controls.md` | `dependency-reviewer` agent |
+| Auth, crypto, secrets | `security-controls.md` | `crypto-compliance` / `secret-handling` skill (`<plugin-root>/routines/<name>/SKILL.md`); `auth-crypto-reviewer` agent |
+| Data model / migrations | `tech-stack.md` | `migration-reviewer` agent |
+| Networking / deployment / attack surface | `security-controls.md` | `security-reviewer` agent (H-16 advisory); `security-architecture` skill (`/threat-model`, optional) |
+| New domain concept or component | `CONTEXT.md` | update the vocabulary in `CONTEXT.md` |
+| Failure / retry, CI/CD, branch settings | `tech-stack.md`, `security-controls.md` | `security-reviewer` agent (CI/CD: H-15 advisory) |
+| Risks / ADRs | `open-questions.md`, `decisions/` | `decision-lifecycle` skill (`/adr`) |
+| Architectural reconciliation | `plans/` (the three artifacts), `decisions/decision-log.md` | `decision-variance` skill (`/reconcile`) |
+| Out-of-scope finding | — | inline `[NEEDS-TRIAGE]` marker (never an ADR); promoted to `open-tasks.md` by the harvest at the workflow's terminal step |
+| Following up on workflow residue / a backlog task | `open-tasks.md` (schema), `<plugin-root>/includes/harvest.md` | `/ca-task` writer; harvest (`extract_*` → `promote`) at a terminal step |
+| Generating a user-facing deliverable (UI, report, PR/CHANGELOG prose, slide, chart) | `<plugin-root>/includes/anti-slop-design/INDEX.md` (then `core` + the medium leaf) | `design-quality-reviewer` agent |
+| Provenance drift surfaced outside a commit (merge, external edit, SessionStart drift line) | `.codearbiter/.provenance/` + `.codearbiter/code-map.md` | `context-check` skill (`/ca-context-check`) |

package/plugins/ca-pi/includes/review-matrix.md

@@ -0,0 +1,14 @@
+# Reviewer-to-path matrix
+
+The single source of truth for which reviewer is dispatched when the scope touches a given path.
+Cited by `review.md`, `pr.md`, `checkpoint.md`, and `preview.md`: edit the matrix here, not in those
+commands. Each matched reviewer is one read-only unit.
+
+| Reviewer | Dispatched when scope touches |
+|---|---|
+| `security-reviewer` | auth, middleware, secrets, deploy/CI, any security-sensitive path |
+| `auth-crypto-reviewer` | authn, crypto, key handling, secrets |
+| `dependency-reviewer` | `package.json`, lockfiles, base images, dependency manifests |
+| `migration-reviewer` | DB migration file add/modify |
+| `coverage-auditor` | any source change (test coverage vs. obligations) |
+| `architecture-drift-reviewer` | code that may diverge from accepted ADRs in `.codearbiter/decisions/` |

package/plugins/ca-pi/includes/reviewer-contract.md

@@ -0,0 +1,53 @@
+# Reviewer contract — findings format, output template, out-of-scope rule
+
+Canonical for every gate reviewer agent (`security-reviewer`, `auth-crypto-reviewer`,
+`dependency-reviewer`, `migration-reviewer`, `coverage-auditor`). Loaded via each agent's
+Required Reading; the agent bodies do not restate these blocks. An agent body MAY narrow the
+subject field or add fields and heading qualifiers — additions extend this contract, never
+replace it.
+
+## Findings format
+
+```
+**Severity:** CRITICAL | HIGH | MEDIUM | LOW
+**File:** <path>:<line>
+**Description:** <specific problem — no vague claims>
+**Remediation:** <concrete fix>
+```
+
+Agent-specific deltas declared in the agent body (examples): `security-reviewer` and
+`auth-crypto-reviewer` add a `**Control:**` line citing
+`<project-root>/.codearbiter/security-controls.md`; `dependency-reviewer` uses
+`**Package:** <name@version>` as the subject field; `coverage-auditor` uses
+`**File:** <source path> / <test path, if exists>`.
+
+## Review output template
+
+```
+## <Role> Review — <date>
+
+### CRITICAL findings (N)
+[findings or "none"]
+
+### HIGH findings (N)
+[findings or "none"]
+
+### MEDIUM findings (N)
+[findings or "none"]
+
+### LOW findings (N)
+[findings or "none"]
+
+### Gate status
+PASS (no CRITICAL or HIGH) | BLOCK (N CRITICAL, N HIGH must resolve before merge)
+```
+
+`<Role>` is the reviewer's own review name (Security, Auth/Crypto, Dependency, Migration,
+Coverage); an agent body may qualify the heading (e.g. the dependency review includes
+`<package@version>`).
+
+## Out-of-scope findings
+
+**Out-of-scope finding:** do not act on it and do not author an ADR for it (ADRs are
+user-attributed, via `/adr` only). Mark it inline with a `[NEEDS-TRIAGE]` marker; never
+silently drop it.

package/plugins/ca-pi/includes/routing-table.md

@@ -0,0 +1,47 @@
+# Routing table
+
+Loaded on a scope-touch or `/command`, not every turn. This table is the authoritative trigger→route
+surface: it answers *what to invoke or route given a trigger*; for *what doc to read before touching a
+scope*, use `reference-map.md`. Follow the primary route; the gate is a hard stop, not a suggestion. A
+command is **invoked**; the orchestrator **routes** to a skill; a skill **dispatches** an agent.
+Routing to a skill means loading its body from `<plugin-root>/routines/<name>/SKILL.md` — a route
+cell names the skill; this path convention locates it. That resolution never depends on the host's
+skill registry: a chain-internal skill hidden from the registry (`disable-model-invocation`) is
+reached the same way.
+
+| Invocation cue | Primary route | Also dispatch | Hard gate |
+|---|---|---|---|
+| New feature | `/feature` Step 0 triage → full lane `brainstorming` → `writing-plans` → `executing-plans` → `tdd`, or logged small lane straight to `tdd` | `backend-`/`frontend-`/`infra-author` | No spec, no code; no code before `tdd` Phase 1; small lane only on all triage criteria, logged to `triage.log` |
+| Autonomous sprint | `/sprint` → `SPRINT.md` (brainstorm → plan → `subagent-driven-development`) | per-task impl authors + reviewers | One interactive spec gate; hard gates never auto-decided; every auto-decision logged |
+| Bug fix | `/fix` → `tdd` (bug variant) | impl author | Failing regression test before any fix code |
+| Docs edit / dep bump / revert | `/chore` (type-scaled gates) | `dependency-reviewer` for deps | No behavioral code; suite green for deps/revert; exits via `commit-gate` |
+| Exploratory throwaway spike | `/spike` (self-contained command) → `spike/<slug>` branch | — | Never merges or PRs; `commit-gate`-exempt (nothing on the branch can land); exits to a findings note or `/feature` |
+| Behavior-preserving restructure | `/refactor` → `refactor` skill | `tdd` Phase 1 (new seams only) | No refactor without parity-coverage proof |
+| Unknown defect / investigation | `/debug` → `debug` skill | — | No code change in the skill; one named exit |
+| Commit | `/commit` → `commit-gate` | — | No commit without all nine gates green |
+| Open a PR / finish a branch | `/pr` → `finishing-a-development-branch` | reviewer fleet per path; PR-body prose applies `anti-slop-design` (`core` + `medium-documents` §7.A.1) | PR only; no direct-to-default, no force-push |
+| Watch a PR's CI / babysit checks | `/watch` → detached `gh pr checks --watch` | on-red diagnose (propose\|branch) | Never auto-merges; green → notify + offer; merge-to-default routes through the hard gate; no poll loop |
+| Code review of the diff | `/review` → `dispatching-parallel-agents` | reviewer fleet → `finding-triage` → `checkpoint-aggregator` | BLOCK on any CRITICAL/HIGH |
+| Periodic sweep | `/checkpoint` → `dispatching-parallel-agents` | reviewer fleet → triage → aggregator | Surfaces a triaged report; not a promotion gate |
+| Governance record for a window | `/audit` | — | Read-only; never overwrites a packet; audit lines quoted verbatim |
+| Release / version tag | `/release` → `release` skill | `commit-gate` (release commit); CHANGELOG prose applies `anti-slop-design` (`core` §3.A/§3.B) | No tag on a red suite; tag not pushed unbidden |
+| Code uses crypto / hashing / signing / TLS / random | `crypto-compliance` skill | `auth-crypto-reviewer` | BLOCK on any banned primitive |
+| Code reads / writes / passes a secret | `secret-handling` skill | `auth-crypto-reviewer` | BLOCK on a secret outside the approved store |
+| Auth / crypto / key change | `auth-crypto-reviewer` | `security-reviewer` | BLOCK on banned primitive, exposed secret, shell injection |
+| Migration file added or changed | `migration-reviewer` | — | BLOCK on missing classification or irreversible destructive op |
+| `package.json` / lockfile / base image changed | `/add-dep` → `dependency-reviewer` | — | BLOCK on denied license or supply-chain concern |
+| Run a pinned third-party tool ONCE, adopting nothing (`npx jscpd@4.0.5 .`) | `/ca-add-dep` → its *Ephemeral tool run* section (no `dependency-reviewer` dispatch) | — | Exact pinned version + approved registry + one confirmation; MUST NOT touch a manifest or lockfile, verified after the run, or it is adoption and takes the full review |
+| Sensitive feature / attack-surface change | `/threat-model` → `security-architecture` (optional) | `security-reviewer`, `auth-crypto-reviewer` | STOP only on a critical unmitigated threat |
+| Arbitration / variance / ADR reconciliation | `/reconcile` → `decision-variance` | `scout`, `grader`, `decision-challenger` | No decision recorded without user attribution |
+| New / aged ADR, unresolved `[CONFIRM-NN]` | `/adr`, `/adr-status` → `decision-lifecycle` | `decision-challenger` (optional) | No `[CONFIRM-NN]` resolved by guessing |
+| Rule conflict (persona vs docs vs code) | `/conflict` | — | STOP all other work immediately |
+| Unsure `/reconcile` vs `/conflict`? | rules contradict and work cannot safely continue → `/conflict`; artifacts drifted, work continues → `/reconcile` | — | When genuinely ambiguous, `/conflict` wins — stopping is recoverable, drifting past a rule conflict is not |
+| New skill needed | `/new-skill` → `skill-author` | — | No skill until the gap is proven uncovered |
+| Subagent raises an out-of-scope finding | inline `[NEEDS-TRIAGE]` marker | — | Never an ADR disposition; never silently dropped |
+| Sitting down to code / repo hygiene cleanup | `/ca-standup` → orchestrator git actions | — | ff-only pull on a clean tree; each branch/worktree delete confirmed individually; stash/dirty/un-pushed report-only; never touch the default branch |
+| Finish an already-merged branch (post-merge cleanup) | `/ca-cleanup` → `post-merge-cleanup` | — | Ancestry of the FETCHED default proven before any delete; unique/unclassifiable artifacts never discarded without a per-item confirmation; `--ff-only` and `branch -d` only; remote branch untouched; never routes to `/ca-override` |
+| Add / start / done a backlog task | `/ca-task` → `hooks/taskwrite.py` (the pure `_taskboardlib` transforms) | — | Board written only through the writer; `start` always stamps a date; `done` requires in-progress; never delete to complete |
+| Promote a workflow's un-actioned follow-ups | `includes/harvest.md` (run at a terminal step) → `/ca-task` (work) / `open-questions.md` (decision) | — | Batch-confirm interactive; SMARTS-logged auto under `/sprint`; dedup by `(from <origin>)`; a blocking decision escalates, never demoted |
+| Zero-onboarding dry-run of the reviewer fleet | `/ca-preview` (no skill; reuses `includes/review-matrix.md` to predict reviewers) | — | Read-only; writes nothing, stages nothing, `git status` unchanged; no `/ca-init` or `.codearbiter/` required; empty diff exits clean |
+| Manual drift audit of provenance-tracked docs (bypass / merge / external edit case) | `/ca-context-check` → `context-check` skill | — | Read-only unless user selects re-scout or re-baseline; MUST NOT commit on its own; not the daily loop — commit-gate auto-heal is the routine path |
+| Deep on-demand codebase audit | `/ca-tribunal` → `tribunal` skill | `tribunal-lens-reviewer` per active lens (+ optional `map-structure`/`map-deps` on large repos) | Read-only until the filing gate; runs only after the user acknowledges the token estimate; never blocks a merge/commit; nothing filed or sent without explicit authorization |

package/plugins/ca-pi/includes/security-gate-record.md

@@ -0,0 +1,22 @@
+# Recording the security-gate pass
+
+The shared mechanism by which `crypto-compliance` and `secret-handling` unblock a commit. Referenced
+by both skills' "On pass" step; the only difference between them is which commit hook the marker
+satisfies (H-09b for crypto/TLS, H-10b for secrets).
+
+**On a genuine PASS only**, resolve the interpreter once by presence — `PY=python3; { command -v python3 >/dev/null 2>&1 && python3 --version >/dev/null 2>&1; } || PY=python`
+— never `python3 X || python X`, which reruns X on any nonzero exit and reports the second run's
+code instead of the first's (#577) — then run:
+
+```bash
+"$PY" "<plugin-root>/hooks/security-pass.py"
+```
+
+It writes `<project-root>/.codearbiter/.markers/security-gate-passed` containing a digest of
+every sensitive added line it approved. The PreToolUse commit hook (**H-09b** for crypto/TLS, **H-10b**
+for secrets) blocks any commit whose staged diff touches a guarded pattern until this marker is fresh
+(< 30 min) AND covers every sensitive line being committed — a pass recorded for one diff cannot
+launder a later, different change through the freshness window.
+
+On any BLOCK, do **not** record the pass — the commit stays blocked until the finding is resolved and
+the gate genuinely passes. A premature or unconditional recording defeats the gate.

package/plugins/ca-pi/includes/smarts/core.md

@@ -0,0 +1,90 @@
+# SMARTS — lenses, cell rules, strength
+
+The standardized evaluation for architectural variances. Apply the six lenses evenhandedly to every
+option. This is the project's framework; do not substitute another. This `core` file is everything the
+scoring path needs (decision-variance, the grader, the decision-challenger, and `/sprint` autonomous
+scoring). The append-only **decision-log entry format** lives separately in
+[`decision-log-format.md`](decision-log-format.md) — load it only when writing a log line.
+
+## Step 0 — recorded-intent check (before any lens is scored; ADR-0025)
+
+*Applies to `/sprint` autonomous scoring and `brainstorming` (spec shaping) ONLY. Exempt by name:
+`decision-variance`, the `grader`, and the `decision-challenger` — on arbitration surfaces the
+variance IS the recorded-intent check, and the decision-variance Phase 4 authority order, not this
+step, ranks the record.*
+
+Before scoring, check whether the project's record already answers or constrains the decision.
+Sources, ranked by the Phase 4 authority order: an explicit user decision this session (including
+the approved sprint spec) > a recorded, unsuperseded `decision-log.md` entry > an accepted ADR >
+the three `plans/` artifacts; `CONTEXT.md` and `open-questions.md` (including its
+Deferred-decisions sections) constrain at their recorded level. Load index-first: consult the ADR
+index (`decision-log.md` or the `decisions/` filename listing) and plan section headings only;
+load a body only after the index names it relevant; never bulk-read `plans/` or `decisions/`
+(ORCHESTRATOR §3's no-bulk-reads rule).
+
+Three outcomes:
+
+- **Answered** — a source already decides it. Conform to the highest-ranked source and cite it.
+  A wanted contradiction routes to `/reconcile` or ADR supersession in interactive lanes; under
+  `/sprint`, an answered-but-contradicting outcome IS the contradiction hard gate — stop and
+  surface, never a mid-sprint reconcile dispatch. A lower-ranked record answering against a
+  higher-ranked steer follows the steer and logs the divergence with both citations — never
+  silently conform downward.
+- **Constrains** — the record narrows but does not decide. Feed the citation into the affected
+  cells; it satisfies the evidence-specificity rule below.
+- **Silent** — no record speaks. Proceed to the lenses and state `intent: silent`.
+
+Fail-soft: an absent `plans/` or `decisions/` directory is not a gap to surface and never a STOP —
+record `intent: silent — no decomposition record` and proceed.
+
+## The six lenses
+
+- **Scalable** — supports growth in users, data, throughput, geography without an architectural rewrite. Trap: over-engineering for scale that never arrives, or under-engineering for scale that's on the roadmap.
+- **Maintainable** — can be understood, modified, and extended later (including by agents) without prohibitive effort. Standard patterns over bespoke abstractions; mind the refactoring blast radius and eventual hand-off.
+- **Available** — reachable and functional when needed, including under partial failure. Watch single points of failure, bundled-dependency failure, recovery time. Do not conflate availability with high availability.
+- **Reliable** — correct, predictable, durable outcomes. ACID where it matters (the decision log, audit events), idempotency, state consistency, recovery without corruption.
+- **Testable** — validated by deterministic, fast tests that cover real failure modes. Unit + integration + contract; mind mockability and test-data isolation. "Tests later" is a Weak verdict.
+- **Securable** — enables the project's security posture (per `<project-root>/.codearbiter/security-controls.md`) without retrofit. Authentication, authorization, audit, secret management, attack surface, default-deny stance, supply-chain integrity.
+
+## Cell rules (hard)
+
+Each SMARTS cell is a constraint, not a guideline. A non-conformant cell is rejected.
+
+1. **Length cap** — at most 25 words per cell.
+2. **Verdict-first** — every cell opens with one verdict word: `Strong` (performs well), `Adequate` (acceptable), `Weak` (poor), `Indifferent` (this lens does not differentiate the options at the current scale).
+3. **Justification follows** — at most 20 words after the verdict.
+4. **No hedging adverbs** — forbidden: potentially, might, arguably, perhaps, generally, tends to, could be, may. If genuinely uncertain, the verdict is `Indifferent`.
+5. **Evidence specificity** — "industry standard," "best practice," "widely adopted" are not evidence. Cite a specific property of the option, a specific project constraint, or a specific failure mode.
+
+## Strength of recommendation
+
+Every recommendation carries exactly one strength label:
+
+- **strong** — multiple dominant lenses align cleanly on one option; non-SMARTS factors confirm.
+- **moderate** — dominant lenses align with caveats, or a single lens dominates.
+- **tied** — no preferred option emerges. A legitimate output: "This is a coin flip under SMARTS — your call."
+
+There is no `weak` level — a slight edge is `moderate`. When lenses conflict with no winner, state it
+plainly, surface which lens the user has emphasized in prior decisions as input, and mark `tied`.
+The `Precedent:` line under each table (decision-variance Phase 3) is how that emphasis is surfaced
+systematically: 1–3 most-similar prior decisions by ID plus the observed lens pattern, or
+`Precedent: none on record` when history is thin — never an invented pattern.
+
+SMARTS does not cover cost, time-to-market, team-skill fit, vendor lock-in, or political
+acceptability. When these matter, surface them as **non-SMARTS considerations** alongside the table;
+they supplement, never replace, the analysis.
+
+## Worked example
+
+**Variance:** authorization engine bundled in the deployment package vs. customer-provided.
+
+| Lens | Bundled | External |
+|---|---|---|
+| Scalable | Adequate. Sub-ms decisions sufficient at 50-user scale. | Adequate. Same ceiling, adds a network hop. |
+| Maintainable | Strong. One package owns versioning and integration. | Weak. Two release cycles must coordinate. |
+| Available | Strong. Available whenever the system is. | Weak. Depends on customer infrastructure. |
+| Reliable | Strong. Failure contained in the deployment boundary. | Weak. Failure surface includes customer network. |
+| Testable | Strong. Local test env is one package install. | Weak. Requires standing up two services. |
+| Securable | Strong. Self-contained mandate satisfied. | Weak. Cross-service auditing is harder. |
+
+**Recommendation:** Bundle the engine. Strength: **strong** — Securable and Available dominate cleanly; no lens favors external enough to override.

package/plugins/ca-pi/includes/smarts/decision-log-format.md

@@ -0,0 +1,56 @@
+# SMARTS decision-log format
+
+The append-only decision-log entry schema. Loaded only by the skills/agents that WRITE a log line —
+`decision-variance`, `decision-lifecycle`, and the `grader`. The six lenses, cell rules, and strength
+labels live in [`core.md`](core.md); read that for the scoring itself.
+
+Path: `<project-root>/.codearbiter/decisions/decision-log.md`. **Strictly append-only** — no
+edits to a prior entry, ever (not typos, not formatting). Read prior entries; never rewrite them. To
+supersede, append a new entry whose `Supersedes:` references the prior one. Traversal is forward-only:
+to find whether an entry was superseded, scan forward for a later entry that references it. No
+backward `Superseded by:` field is maintained.
+
+Entries are numbered sequentially (`DECISION-0001`, …; no gaps) and separated by `---`:
+
+```markdown
+## DECISION-<NNNN> — <Decision ID> — <one-line summary>
+
+**Date:** YYYY-MM-DD
+**Status:** accepted | superseded | deferred
+**Supersedes:** DECISION-NNNN | none
+**Decided by:** <user identifier> | "user during arbitration session" | "User explicitly accepted recommendation as their decision"
+**Decision category:** <category>
+**Artifact-section-hash:** <SHA-256 of the cited artifact section, heading inclusive, HTML comments stripped — or "n/a">
+
+### Variance summary
+- **Artifact position:** [one sentence]
+- **Scaffold position:** [one sentence]
+- **Status type:** divergent | scaffold-silent | artifact-silent | same-level-conflict-resolution | open-decision-closure
+
+### Decision
+[The user's choice. 2–4 sentences. What was decided, not what was discussed.]
+
+### SMARTS rationale
+[Which lenses drove it. 2–6 sentences.]
+
+### Implementation implication
+[What changes — specific scaffold files, ADRs, or artifact sections to update.]
+
+### Re-evaluation trigger (deferred only)
+[The event that should reopen this. Omit unless status is deferred.]
+
+### Resolves same-level conflict between (when applicable)
+[Name both conflicting sources. Omit otherwise.]
+
+---
+```
+
+**Artifact-section-hash** — record the SHA-256 of the artifact section that defined the artifact's
+position at decision time (section heading inclusive to the next same-or-higher heading exclusive,
+HTML comments stripped, UTF-8, full 64-char hex). It is `n/a` for `artifact-silent` variances,
+open-decision closures, and process decisions with no artifact source. The Phase 1 stale check
+recomputes it on later sessions.
+
+**Never:** edit a prior entry; compress multiple variances into one entry; record "no decision
+needed"; omit the SMARTS rationale; omit the hash field (write `n/a`, do not drop it); write a
+decision the user did not explicitly make.

package/plugins/ca-pi/routines/INDEX.md

@@ -0,0 +1,32 @@
+# skills — catalog (surface scan)
+
+Skill bodies load on routing only. This index is the surface scan; never bulk-read
+`skills/*/SKILL.md`. Each skill is an orchestrator routine with gated phases, routed to, never
+"triggered." This index lists what each skill OWNS; to decide WHERE a trigger routes, load
+`<plugin-root>/includes/routing-table.md` (the authoritative trigger→route surface).
+
+| Skill | Routed to by | Owns |
+|---|---|---|
+| [tdd](tdd/SKILL.md) | `/feature` (after spec approval), `/fix`, `/refactor` | The test-first gate: six phases — obligation scan → red → green → obligation verify → coverage → lint. No implementation before Phase 1; no path to `commit-gate` until all six gates are green. |
+| [commit-gate](commit-gate/SKILL.md) | `/commit` | The commit gate: nine phases — permission, branch, classification, verification, behavioral proof, diff review, selective stage, message, commit. No commit while the suite is red, the behavior unproven, or secrets/cruft present. |
+| [decision-variance](decision-variance/SKILL.md) | `/reconcile` | SMARTS 6-lens arbitration of project/ADR conflicts; append-only, user-attributed decision log + audit trail. Never decides alone — every choice carries user attribution. |
+| [debug](debug/SKILL.md) | `/debug` | Investigate-then-decide root-cause analysis: five phases. Investigation only, no code change here; forces one named exit — `/fix`, `/adr`, or a no-action close. |
+| [refactor](refactor/SKILL.md) | `/refactor` | Behavior-preserving change behind a parity-coverage proof gate; routes to `tdd` Phase 1 only when new test seams are needed. |
+| [context-creation](context-creation/SKILL.md) | `/create-context` (brownfield) | Back-fills `.codearbiter/` from existing source via parallel scouts; writes `CONTEXT.md` (`arbiter: enabled` + `stage:`) and locks it `<!--INITIALIZED-->`. |
+| [decompose](decompose/SKILL.md) | greenfield startup, `/decompose` | Six-layer senior-architect interview, compaction-resilient via per-layer disk drafts + DRAFT ADRs; populates `.codearbiter/` and locks it initialized. |
+| [brainstorming](brainstorming/SKILL.md) | `/feature` (front), `/sprint` planning | Socratic idea→spec: split bundles, shape the approach, then decide parameters / ask forks in full; adversarial self-review before approval; writes `specs/<slug>.md` whose acceptance criteria become `tdd` obligations. Hard-gate: no code until the spec is approved. |
+| [writing-plans](writing-plans/SKILL.md) | `/feature`, `/sprint` (after the spec) | Decomposes an approved spec into small tasks, each with a path + a verification that maps to a `tdd` obligation; writes `plans/<slug>.md` with bijective criterion↔task coverage. |
+| [executing-plans](executing-plans/SKILL.md) | `/feature` | Checkpoint coordinator — groups tasks into batches, delegates each to `subagent-driven-development` (fresh author agent per task, full review chain), stops for user acknowledgement between batches. |
+| [subagent-driven-development](subagent-driven-development/SKILL.md) | `/sprint` (engine), `executing-plans` (batch scope) | Fresh subagent per task → spec-compliance then quality review → fresh-run verification; accepts only on proof. Hard-stops on `tdd` BLOCK, security CRITICAL, `[CONFIRM-NN]`. |
+| [dispatching-parallel-agents](dispatching-parallel-agents/SKILL.md) | `subagent-driven-development`, `/sprint`, parallel `/review` | Reusable fan-out primitive: bound concurrency, collect, dedupe, funnel through `finding-triage`→`checkpoint-aggregator`. Results unused until the funnel runs. |
+| [finishing-a-development-branch](finishing-a-development-branch/SKILL.md) | `/feature`, `/sprint` (terminal) | The terminal step after `commit-gate`: open-PR / merge-via-PR / discard. No direct-to-main, no force-push; `/sprint` auto-selects open-PR and never merges. |
+| [using-git-worktrees](using-git-worktrees/SKILL.md) | `subagent-driven-development`, `dispatching-parallel-agents` (opt-in) | OPTIONAL per-unit filesystem isolation for parallel work; integrates accepted units back onto the caller's working branch for its single `commit-gate` + finish. Never the default path. |
+| [secret-handling](secret-handling/SKILL.md) | changed code reads/writes/passes a secret | The secret-source gate: identify → source → sinks/persistence. Secrets only from the approved store in `security-controls.md`; never in source, log, error, telemetry, image, or LLM prompt. Dispatches `auth-crypto-reviewer`. |
+| [crypto-compliance](crypto-compliance/SKILL.md) | changed code uses crypto/hashing/signing/TLS/random | The banned-primitive gate: one scan. Rejects broken primitives, disabled TLS verification, home-rolled crypto; approved list lives in `security-controls.md`. Dispatches `auth-crypto-reviewer`. |
+| [skill-author](skill-author/SKILL.md) | `/new-skill "<gap>"` | The only path to a new skill: five phases — gap evidence, scope, authoring, self-review against the v2 house style, routing integration. No skill written until the gap is proven uncovered; none shipped without gated phases, hard rules, and an `INDEX.md` + routing entry. |
+| [decision-lifecycle](decision-lifecycle/SKILL.md) | `/adr`, `/adr-status` | Lean ADR author + status: author a numbered, dated, user-attributed ADR under `.codearbiter/decisions/`; list/status; forward-only supersede chains. Optional `decision-challenger`. Log-entry format lives in `includes/smarts/decision-log-format.md`. ADRs only via `/adr`, with user attribution. |
+| [release](release/SKILL.md) | `/release` | Lean SemVer release, three phases: derive the bump from Conventional-Commits since the last tag + roll `CHANGELOG.md`; cut the annotated tag + report; publish (push tag + `gh release create`) on explicit authorization. No tag on a red suite; no direct-to-main/force-push; nothing published unbidden; a release commit routes through `commit-gate`. |
+| [security-architecture](security-architecture/SKILL.md) | `/threat-model` (optional) | OPTIONAL lightweight STRIDE pass for sensitive features: attack surface → STRIDE → findings, governed by `security-controls.md`. MAY dispatch `security-reviewer` / `auth-crypto-reviewer`. Not a routine gate; hard-STOPs only on a critical unmitigated threat. |
+| [context-check](context-check/SKILL.md) | `/context-check` | OPTIONAL manual drift audit: load `.codearbiter/.provenance/` via `load_provenance_dir` + `compute_drift`, report stale docs, then per stale doc: re-scout / re-baseline (`rebaseline`) / defer. Not the daily loop — commit-gate auto-heal owns routine maintenance. |
+| [post-merge-cleanup](post-merge-cleanup/SKILL.md) | `/ca-cleanup` | The already-merged branch transition: fetch, prove `HEAD` is contained in the fetched default (SHA-ancestry, or a squash-merge proven by the merged PR record), classify every dirty/untracked artifact as unique/redundant/superseded, resolve each under its own confirmation, fast-forward the local default ref then `--ff-only` onto it, then `branch -d` the merged local branch. Unique or unclassifiable artifacts are never discarded unbidden; the remote branch is never touched; never routes to `/ca-override`. |
+| [tribunal](tribunal/SKILL.md) | `/ca-tribunal` | The deep, rarely-convened whole-codebase audit lane: seven gated phases across eleven specialist lenses, each finding persisted to its own file (plus append-only triage/run logs) under `.codearbiter/reports/<run-id>/`, resumable from disk, filing approved findings as GitHub issues; never a required gate. |

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

@@ -0,0 +1,122 @@
+---
+name: brainstorming
+description: The Socratic spec-refinement front of /feature, and the planning front of /sprint. Routed to BEFORE any code — it takes a one-line idea and drives it to an approved, concrete spec with testable acceptance criteria. Five gated phases — frame, shape, refine, write, review-and-approve. No implementation and no handoff to tdd until the spec is on disk and approved; each acceptance criterion becomes one tdd Phase 1 obligation.
+disable-model-invocation: true
+---
+
+# brainstorming
+
+Refine the idea before it touches code. Routed to by `/feature` (before `tdd`) and by `/sprint` (the planning front).
+
+## Pre-flight
+
+Read these, or STOP and surface the gap — never guess scope or stack:
+
+- `<project-root>/.codearbiter/CONTEXT.md` — the `stage:` frontmatter (the maturity value), domain vocabulary, and what the project is NOT building.
+- `<project-root>/.codearbiter/tech-stack.md` — the stack the feature must fit; rule out incompatible designs early.
+- `<project-root>/.codearbiter/open-questions.md` — existing `[CONFIRM-NN]` items; new ones number sequentially from here.
+
+**Recorded intent — fail-soft, exempt from the read-or-STOP rule above (ADR-0025).** Also
+consult, when present: the `decisions/` index (titles via `decision-log.md` or the filename
+listing — load a full ADR body only when its subject touches this feature) and
+`plans/02-phased-build-plan.md`'s section headings (plus `plans/01-architecture-breakdown.md`
+when the feature touches component boundaries or integrations). Index-first, never a bulk read.
+A missing file or directory here is NOT a gap to surface and never a STOP: record
+`intent: silent — no decomposition record` in the running notes and proceed.
+
+Per-feature and light. NOT decompose's whole-project six-layer interview — one feature, five phases. Depth scales with the feature, not the ceremony: a small feature earns a short pass through every phase, never a skipped one. A spec can be five sentences; it cannot be zero — smallness changes the spec's length, not its existence.
+
+## Phase 1 — Frame the problem · gate: BLOCK
+
+Take the one-line idea and pin its boundaries before designing or asking anything:
+
+- State the problem in one sentence — the concrete pain, not the proposed solution.
+- Name the user or caller who feels it, and what "done" looks like to them.
+- Name what this feature explicitly does NOT do — the boundary that keeps scope honest.
+- Check the framing against `CONTEXT.md`: it never contradicts the NOT-building list or redefines domain vocabulary. A contradiction is a conflict — surface it, do not reconcile it silently.
+- Check the framing against the recorded intent (pre-flight, when present): an idea that resurrects a capability `plans/02` records as deferred, or that duplicates a backlog item, is a fork to ask — lead with the recorded deferral rationale and your recommendation; never proceed on it silently (ADR-0025).
+- **Split before you spend.** If the idea bundles more than one independently shippable concern — distinct callers, acceptance criteria that would partition into disjoint sets, separable data or surfaces — say so NOW and negotiate the split with the user before any refinement effort is spent on one piece. Each surviving piece is its own spec and its own run of this skill. A bundle discovered in Phase 4 has already wasted every question asked about the piece that gets cut.
+
+Gate: problem, caller, and out-of-scope boundary stated and consistent with `CONTEXT.md`, and the idea is confirmed to be ONE feature — or the split is agreed and this run proceeds on exactly one piece.
+
+## Phase 2 — Shape the approach · gate: BLOCK
+
+Before drilling into details, establish WHICH design the details belong to:
+
+- Propose the genuine candidate approaches — usually two or three — each with its real trade-off stated (`X gives you A but costs B`). Recommend exactly one, with the reasoning that picks it. The user chooses under `/feature`; under `/sprint`, SMARTS chooses and the choice is logged with its scoring.
+- **Never manufacture alternatives.** When only one sane approach exists, say so and say why — a padded list of straw options is noise wearing the costume of rigor, and it trains the reader to skim the one section that matters.
+- **Check each candidate against accepted ADRs** (the pre-flight index; ADR-0025). A contradicting candidate is surfaced WITH the ADR citation, never silently dropped — and it may not be recommended except paired with a supersession fork via `/adr`. When the contradicting candidate is the only sane approach, that IS the fork: present it (the user rules under `/feature`; under `/sprint` this surfaces at the interactive Phase 1 gate, where the user is present to rule).
+- Apply the isolation lens to the recommended shape while it is still soft: can each part be understood without reading its internals, and can its internals change without breaking its consumers? A design that fails this here fails it again in review, after the code exists.
+- Apply the YAGNI lens: strike anything the Phase 1 problem statement does not demand. A capability the caller never asked for is scope creep with a head start.
+
+Gate: one approach chosen (user-chosen, or SMARTS-chosen and logged), its trade-off stated, and nothing in it the problem does not require.
+
+## Phase 3 — Socratic refinement loop · gate: BLOCK
+
+Turn the chosen approach concrete. The discipline is decide-or-ask, never drift:
+
+- **Decide the parameters; ask the forks.** A parameter-level choice — a naming, a default, a threshold, an ordering with one sensible answer — is yours to make: decide it and record it in this phase's running notes; every recorded decision lands in the spec's **Decided parameters** section when Phase 4 writes the file, which is where the user reads them at approval. A genuine fork — a real trade-off, a scope boundary, anything irreversible or user-visible — is the user's: ask it IN FULL the first time, leading with your recommendation and its reasoning. Never merely mention that an open decision exists; a named-but-unasked question is an omission wearing a disclaimer.
+- **Batch what is independent.** Forks whose answers do not depend on each other are asked together, not serialized into rounds. One round of three real questions beats three rounds of one.
+- Run every answer through three lenses:
+  - **Vague language** — force concrete nouns, numbers, and verbs. "Manage", "handle", "support" are not verbs. "Fast", "secure", "scalable" are not specifications. "We'll figure it out later" is not an answer — every "later" becomes a `[CONFIRM-NN]`.
+  - **Hidden complexity** — name what the user assumes is easy but is hard: state, concurrency, edge cases, failure modes, validation, idempotency, migration of existing data. Surface it now or it surfaces in `tdd`.
+  - **Trade-off forcing** — when a real decision exists, frame it with a recommendation and let the user rule. Do not pick for the user; do not hide that a pick exists.
+- **The loop has a breaker.** When refinement stops converging — an answer contradicts an earlier one, or the same fork resurfaces after being answered — STOP the loop: restate the contradiction plainly, force one adjudication (a user ruling, or a recorded `[CONFIRM-NN]`), and only then continue. A loop that circles is not being thorough; it is failing to close.
+- **Closure is a checklist, not a feeling.** The reasons to stop asking that do not count, each with why:
+  - *"The feature is simple enough."* — Simplicity shortens the spec; it does not waive it. The five-sentence spec still names its criteria.
+  - *"I've asked enough questions."* — Question fatigue is not an exit condition. The exit is the Phase 5 review passing.
+  - *"The user seems eager to move on."* — Eagerness is a signal to compress the asking (decide more parameters, batch harder), never to skip an unresolved fork.
+  - *"We can settle it during implementation."* — Every deferral is a `[CONFIRM-NN]` on record, or it is a guess that `tdd` will faithfully implement.
+
+Record every genuinely-unresolved unknown as `[CONFIRM-NN]` in `<project-root>/.codearbiter/open-questions.md`, numbered sequentially. A finding that belongs to a different feature or a future scope gets an inline `[NEEDS-TRIAGE]` marker in the notes — never route it to a ticket.
+
+**Before closing this loop, check the criteria decided so far against their own stated intent, not merely against each other** (#566: `writing-plans` Phase 4 proves BIJECTION between a plan's tasks and the `AC-NN` ledger — every criterion has a task, every task has a criterion — and that proves the two AGREE, never that the ledger itself is COMPLETE. A criterion missed by both sides passes that check cleanly; catching the miss belongs here, at the source, before Phase 4 writes anything to freeze it in place.) Assemble a scratch file outside the working tree (`mktemp`) shaped like the spec sections Phase 4 is about to write — a `## Scope` heading over the Phase 1 framing, and an `## Acceptance criteria` heading over every criterion decided in this phase's running notes so far — and, when this feature traces to a GitHub issue, its body into a second scratch file (`gh issue view <N> --json body -q .body > <scratch-file>`; omitted when there is no linked issue). Run `"$PY" "<plugin-root>/hooks/_intentlib.py" uncovered-intent <scope-and-criteria-file> [--issue-body <scratch-file>]`. A non-empty result names an in-scope bullet or an issue acceptance checkbox no criterion's text cites — add the missing criterion now, or record it as a `[CONFIRM-NN]` if it is genuinely undecided, never carry it forward uncited. This mechanical pass is the CHEAP half; it catches only an uncited bullet or checkbox.
+
+Then ask the half it cannot mechanize, explicitly, as its own step: **if every criterion decided so far passed and nothing else changed, what would still be broken?** A real answer names a criterion the ledger is still missing even though every scope bullet and checkbox is technically cited — a bullet reading "fix all three contaminated skills" against criteria for two of the three passes the citation check above cleanly, and only this question catches it. Finding nothing broken is a reportable result, stated in one line, never a silent skip.
+
+Gate: every vague term made concrete; every fork resolved by the user or recorded as `[CONFIRM-NN]`; every parameter decision recorded in the running notes that seed Phase 4's **Decided parameters** section; no unresolved "later" outside a `[CONFIRM-NN]`; the `uncovered_intent` backstop returns empty or every finding is resolved; and the negative question above has been asked and answered, not merely named. A blocking `[CONFIRM-NN]` that gates the spec's core stops the loop — surface it and STOP.
+
+## Phase 4 — Write the spec · gate: BLOCK
+
+Write the agreed spec to `<project-root>/.codearbiter/specs/<slug>.md`. The slug is derived from the feature. The spec holds:
+
+- **Problem** — the Phase 1 framing in final form.
+- **Approach** — the Phase 2 choice and the trade-off that picked it, in two or three sentences.
+- **Scope** — what is in, and the explicit out-of-scope boundary.
+- **Decided parameters** — the parameter-level choices made in Phase 3, each in one line, so the approval reads them instead of discovering them in code review.
+- **Acceptance criteria** — a numbered list, each criterion concrete and testable: a specific input, the observable output, the boundary or failure behavior. Each criterion is verifiable by a single test. "It works well" is not a criterion. These become `tdd` Phase 1 obligations — one obligation per criterion, so an untestable criterion is a defect to fix here, not in `tdd`.
+- **Open questions** — every `[CONFIRM-NN]` raised, cross-referenced to `open-questions.md`.
+- **Governs** *(optional)* — a spec-header line `**Governs:** <comma-separated globs>` that enrolls the approved spec in file-scoped just-in-time context injection: on a Read of any file matching one of the listed globs, a pointer to this spec is surfaced to the agent (tier 3 of the file→knowledge map). Adding the line is sufficient to enroll; no other change required.
+
+Gate: the spec file exists on disk under `specs/`, with at least one acceptance criterion and every criterion individually testable.
+
+## Phase 5 — Review, approval & handoff · gate: STOP
+
+The spec earns its approval; it is not waved through. Two passes over the FILE as written, then the stop:
+
+1. **Mechanical self-review** — one pass, fix inline, no re-review: no placeholder text (`TBD`, `???`, an unfilled section); no criterion that contradicts the scope; nothing that crosses the `CONTEXT.md` NOT-building boundary; no criterion that contradicts an accepted ADR or `plans/01`'s recorded component boundaries (ADR-0025); every criterion still testable by a single test after the edits; the vague-language lens applied to the spec's own prose.
+2. **Adversarial pass** — build the strongest case AGAINST the design before the user reads it: the failure mode most likely to be real, the criterion most likely to be wrong, the assumption that would invalidate the approach if false. Present what survives WITH the spec at approval — the user rules on a challenged design, not a defended one. Finding nothing is a reportable result, stated in one line, not a silent skip.
+3. **Approval:**
+   - **Under `/feature`** — present the spec and the adversarial findings, and request explicit user approval. Iterate on the file in place until the user approves. A blocking `[CONFIRM-NN]` must be resolved by the user before approval — never auto-resolve it.
+   - **Under `/sprint`** — approval may be granted automatically by SMARTS scoring, logged to the `.codearbiter/` audit trail. A blocking `[CONFIRM-NN]` is never auto-approvable; it escalates to the user and STOPs the sprint flow.
+
+On approval, hand off to the `tdd` skill (`<plugin-root>/routines/tdd/SKILL.md`), which enters Phase 1 against the approved spec — one obligation per acceptance criterion.
+
+Gate: both review passes run against the file on disk, adversarial findings presented, and the spec approved (by the user under `/feature`, or by logged SMARTS auto-approval under `/sprint`) with no unresolved blocking `[CONFIRM-NN]`. Only then does control pass to `tdd`.
+
+## Hard rules
+
+- MUST NOT write implementation code or route to `tdd` before the spec is on disk under `specs/` AND approved.
+- MUST NOT refine a bundle — an idea holding more than one independently shippable concern splits in Phase 1, before any question budget is spent.
+- MUST NOT manufacture alternatives in Phase 2 — when one sane approach exists, say so and why.
+- MUST NOT write an acceptance criterion that cannot be verified by a single test.
+- MUST decide parameter-level choices and record them in the spec; MUST ask genuine forks in full, with a recommendation, the first time — never name an open decision without asking it.
+- MUST stop a non-converging refinement loop and force one adjudication — a contradiction or a resurfacing fork is a breaker, not a prompt to circle.
+- MUST run the `uncovered_intent` mechanical backstop and ask the negative-judgment question ("if every criterion passed and nothing else changed, what would still be broken?") before closing Phase 3 — bijective coverage in `writing-plans` proves the plan and the ledger agree with each other, never that the ledger is complete (#566).
+- MUST run the Phase 5 mechanical self-review and adversarial pass against the file as written, and present the adversarial findings at approval.
+- MUST NOT resolve a `[CONFIRM-NN]` by guessing — surface it and record it in `open-questions.md`.
+- MUST NOT auto-approve a spec carrying a blocking `[CONFIRM-NN]`, even under `/sprint` — it escalates to the user.
+- MUST NOT contradict the NOT-building list or redefine domain vocabulary in `CONTEXT.md` — a contradiction is a conflict to surface, not reconcile.
+- MUST NOT run decompose's six-layer whole-project interview — this is one feature, five phases.
+- MUST log a `/sprint` auto-approval to the `.codearbiter/` audit trail.
+- MUST, at exit, run the follow-up harvest (`<plugin-root>/includes/harvest.md`) over any `[NEEDS-TRIAGE]` notes raised this run — batch-confirm promoting them to `open-tasks.md` (work) or `open-questions.md` (decisions) so out-of-scope ideas don't vanish.