@arbiterforge/ca-pi 0.6.0

package/plugins/ca-pi/routines/commit-gate/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: commit-gate
+description: The only path to a commit. Routed to when the user invokes /commit or otherwise instructs codeArbiter to persist staged changes. Nine gated phases — permission, branch, classification, verification (test/lint/secrets), behavioral proof, diff review, selective stage, message, commit. Nothing reaches version control without clearing every gate; "it looks good" is not authorization.
+---
+
+# commit-gate
+
+The only permitted path to a commit. Bypassing it is a hard-rule violation. Routed to when the user invokes `/commit` or any equivalent instruction to persist staged changes.
+
+## Pre-flight
+
+Read these, or STOP and surface the gap — never guess a command:
+
+- `<project-root>/.codearbiter/tech-stack.md` — test, lint, and secrets-scan invocations. Stop if missing; do not guess.
+- A git repository must be present and `git status` available.
+- The `tdd` skill must have cleared all six phases for any new or modified feature code in the staged set. If `tdd` is incomplete, STOP and surface the gap.
+
+## Phase 1 — Permission · gate: BLOCK
+
+Confirm the user explicitly authorized this commit. Speculative commits are prohibited.
+
+Explicit instructions: "commit", "commit this", "go ahead and commit", "create the commit". Ambiguous signals — "looks good", "that should work" — are NOT authorization. Record the instruction text for the report.
+
+Gate: explicit user authorization is on record. Inferred or assumed permission does not pass.
+
+## Phase 2 — Branch · gate: BLOCK
+
+Run `git branch --show-current`. If the branch is `main`, `master`, or any protected branch, STOP and instruct the user to create a feature branch. Record the branch name for the report.
+
+Gate: the working branch is not protected.
+
+## Phase 3 — Classification · gate: BLOCK
+
+Read the staged set (`git diff --cached --name-only` and `--stat`). Classify the change into a commit type:
+
+- `feat` — new capability or behavior
+- `fix` — corrects a defect
+- `test` — tests only
+- `refactor` — restructures without behavior change
+- `docs` — documentation only
+- `chore` — build, tooling, dependency updates
+- `ci` — pipeline changes
+
+Derive the scope from the staged paths. If the staged set spans more than one type, split it — stage and commit each type separately.
+
+Flag any staged **database migration** (per `_hooklib.is_migration_path`) here — it carries a mandatory migration-review routing in Phase 4 (the H-14 gate), independent of the commit type.
+
+Gate: the staged set is type-homogeneous with a single type and scope.
+
+## Phase 4 — Verification · gate: BLOCK
+
+Read the test, lint, and secrets-scan commands from `tech-stack.md`. Then:
+
+- Run the test command. ALL tests green. Any failure blocks.
+- Run lint, and the type-check if the project is statically typed. Zero errors.
+- Run the secrets scan on ALL staged files, regardless of commit type. Any finding blocks.
+- **Security gates (mandatory routing):** if the staged diff touches crypto/TLS or secret patterns, route it through `crypto-compliance` (`<plugin-root>/routines/crypto-compliance/SKILL.md`) and/or `secret-handling` (`<plugin-root>/routines/secret-handling/SKILL.md`) — they scan against `security-controls.md` and, on pass, record the diff-bound marker `.codearbiter/.markers/security-gate-passed` (via `hooks/security-pass.py`). This is not optional: the PreToolUse commit hook **H-09b/H-10b blocks the commit** until that gate pass is recorded AND covers every sensitive line being committed.
+- **Migration gate (mandatory routing):** if the staged set contains a database migration (Phase 3 flags it; the detection rule is `_hooklib.is_migration_path` — default migration globs, extendable/narrowable via a `migration-paths` block in `security-controls.md`), dispatch the `migration-reviewer` agent (`<plugin-root>/agents/migration-reviewer.md`). **On a genuine PASS only**, record the content-bound marker `.codearbiter/.markers/migration-gate-passed` by resolving 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 (#577) — and running `"$PY" "<plugin-root>/hooks/migration-pass.py"`. This is not optional: the PreToolUse commit hook **H-14 blocks the commit** until the pass is recorded AND covers every migration file being committed (by content digest, no freshness window — an edit to a reviewed migration re-blocks). This closes the bare-`/commit` / small-lane gap from issue #77. On a BLOCK, do not record the pass.
+- **CI/deploy review (mandatory routing, no marker gate):** if the staged set touches a CI/CD workflow (`_hooklib.is_ci_path` — defaults extendable via a `ci-paths` block in `security-controls.md`) or a deployment/IaC manifest (`_hooklib.is_deploy_path` — `deploy-paths` block), dispatch the `security-reviewer` agent (`<plugin-root>/agents/security-reviewer.md`). This is the enforcement point the advisory `post-write-edit` reminders **H-15/H-16** point to, and it closes the bare-`/commit` / small-lane gap for CI/deploy (the `/review`, `/pr`, `/checkpoint`, and sprint lanes already dispatch it). Unlike crypto/secret/migration there is **no commit-block marker** — a CI workflow runs only once merged and IaC bites only on apply, so a BLOCK-level finding halts the commit via Phase 6 review, but routine CI/deploy edits are not gated per-commit. Act on the findings by severity; do not record a marker.
+
+Record each result (PASS / BLOCK) for the report.
+
+Gate: test, lint, secrets scan, and (when crypto/secret is touched) the security gate all PASS. Any failure halts the commit until fixed and re-run.
+
+## Phase 5 — Behavioral proof · gate: BLOCK
+
+Apply the shared fresh-run discipline in `<plugin-root>/includes/fresh-verification.md`, with
+**the spec's acceptance criterion** as the target — prove the behavior against the spec, not against a
+self-report.
+
+- Identify the proving command or observable: the acceptance criterion from `<project-root>/.codearbiter/specs/<slug>.md` (or the task's verification in the plan). If none exists, derive the smallest command that exercises the claimed behavior.
+- Run it fresh in this phase, read its output and exit code, and confirm the observed behavior matches the spec's acceptance criteria. A mismatch, or an unverifiable claim, blocks.
+
+**Stakes:** a behavioral-proof mismatch means the change does not do what the spec claims — state what would ship broken if this passed ("the retry path never fires; a transient error would hang the caller"), not just "proof mismatch." That gap is exactly what a green-looking suite hides.
+
+Gate: the change is proven to do what it claimed by fresh evidence — command output and exit code read in this phase. A self-reported "it works" does not pass.
+
+## Phase 5.5 — Provenance auto-heal (conditional)
+
+Compute the heal worklist from the staged set via `_provenancelib.heal_worklist(staged_paths, provenance, current_hashes)` — the subset of staged paths that are `drift_trigger:true` provenance entries whose recorded hash has diverged or is absent. **Empty worklist → skip this phase entirely; most commits pay nothing** (cost guarantee: ordinary commits touching no provenance source do zero re-scout work).
+
+Non-empty worklist → run an **incremental re-scout scoped to those paths only** (not the full repo). For each path, re-examine whether the claims in the backing doc still hold:
+
+- **Claim still holds → silently re-baseline.** Call `_provenancelib.rebaseline` to update the stored hash in `.codearbiter/.provenance/<doc>.json` and stage that file by explicit path so the re-baselined record rides THIS commit (ADR-0008 ride-along pattern — nothing is surfaced to the user). After staging, re-run the secrets scan from `tech-stack.md` over the newly-staged path(s) — any file staged after Phase 4 must still pass the automated secrets scan before the commit proceeds.
+- **Claim changed → route to the existing Phase 6 diff-review.** The doc or code-map edit required to reflect the changed claim is proposed in diff review — the user reviews it as part of the normal diff; nothing is silently rewritten.
+
+## Phase 6 — Diff review · gate: BLOCK
+
+Read the complete staged diff (`git diff --cached`). Flag as blocking:
+
+- Unexpected files — not discussed in the session.
+- Credentials, tokens, API keys, or any secret — belt-and-suspenders to Phase 4.
+- Incomplete changes — TODO markers, placeholder values, dead commented-out code, partial stubs.
+- Tests disabled or skipped that were not intentionally disabled.
+- Scope creep — changes outside the agreed feature or fix boundary.
+
+**Board-edit exemption (ADR-0008):** an edit to `open-tasks.md` where `_taskboardlib.classify_board_diff(old, new)` returns a clean transition (done-flip `[~]`→`[x]`, start-flip `[ ]`→`[~]` with its optional minted dotted ID, or a single queued-add `[ ]`) is **expected and RETAINED** — it is not scope creep and MUST NOT be unstaged. Any other `open-tasks.md` change — a reworded or deleted entry, or an arbitrary content edit — does not classify as a transition and still flags as scope creep.
+
+**Provenance re-baseline exemption (ADR-0008):** a `.codearbiter/.provenance/<doc>.json` file written by the Phase 5.5 auto-heal re-baseline is likewise **expected and RETAINED** — it is not scope creep and MUST NOT be unstaged. A heal-proposed doc or code-map edit (the claim-changed path from Phase 5.5) appears in the diff for normal review; treat it as any other finding. This exemption waives the scope-creep flag only; the secrets check is not waived — the automated re-scan in Phase 5.5 covers the provenance file.
+
+On any blocking finding, unstage the affected files, surface the finding, and STOP. An out-of-scope change that should not be lost gets an inline `[NEEDS-TRIAGE]` marker before it is set aside.
+
+**Stakes:** name what the finding would have cost if committed — a leaked credential is live the moment it lands and must be rotated; a scope-creep file ships untested behavior the review waved through. State that consequence on a credential or scope finding, not just "out of scope."
+
+Gate: the diff is clean — zero blocking findings.
+
+## Phase 7 — Selective stage · gate: BLOCK
+
+**First, run the follow-up harvest — before staging anything.** Run the follow-up harvest (`<plugin-root>/includes/harvest.md`) over any Phase 6 `[NEEDS-TRIAGE]` set-asides — promote discovered follow-ups to `open-tasks.md` (work) or `open-questions.md` (decision) via the existing harvest procedure. Running this before the commit means raised board tasks are staged and ride the work commit in the same payload.
+
+**Atomicity rule:** a raised task riding the work commit is a **contingent default** — if the PR/branch is abandoned, the board additions are abandoned with it (self-correcting, ADR-0008). A follow-up that **must survive** PR abandonment is filed as a **GitHub issue**, not the board.
+
+Then selectively stage: if files were unstaged in Phase 6, re-stage only the clean files by explicit path: `git add path/to/file`. When a clean task-board transition was retained by the Phase 6 board-edit exemption, include `open-tasks.md` in the selective stage by explicit path (`git add open-tasks.md`) alongside the work files, so the flip rides the same commit. Include any `open-tasks.md` additions produced by the harvest step in the same explicit-path stage. When Phase 5.5 produced a re-baselined provenance record, include the affected `.codearbiter/.provenance/<doc>.json` file(s) by explicit path in the same selective stage so the re-baselined record rides the work commit. Re-run `git diff --cached --name-only` and confirm the staged list matches the intended set exactly — no extra files. Unstage any extra and report the discrepancy.
+
+Gate: the staged set contains exactly the intended files. MUST NOT use `git add -A`, `git add .`, or any wildcard.
+
+## Phase 8 — Message · gate: BLOCK
+
+Compose a Conventional Commits message:
+
+- Subject: `<type>(<scope>): <imperative summary>`, MUST NOT exceed 72 characters.
+- Blank line, then a body explaining WHY — not a restatement of what changed.
+- For `feat` and `fix`, add a `CHANGELOG:` footer summarizing the user-visible impact.
+- If the commit closes an issue or references a decision, add the footer (`Closes #NN`, `Ref: ADR-NNNN`).
+- No content-free subjects — "fix bug", "update code", "changes" do not pass.
+
+Gate: subject ≤ 72 chars, a body is present, and any `feat`/`fix` carries a `CHANGELOG:` footer.
+
+## Phase 9 — Commit · gate: BLOCK
+
+Commit with the approved message via `-m` or heredoc with proper quoting — never an interactive editor. Capture the resulting SHA.
+
+If a pre-commit hook fails: read its output in full, fix the issue, re-stage by explicit path (Phase 7 rules apply), and create a NEW commit. MUST NOT `--amend` after a hook failure.
+
+After a successful commit, run `git status` to confirm the tree is clean. Deliver the report: SHA, branch, explicit file list, gate results (test / lint / secrets), and the message used.
+
+Gate: the commit lands and `git status` is clean. Unexpected uncommitted changes after the commit block closure — report the discrepancy.
+
+## Hard rules
+
+- MUST NOT commit without explicit user authorization. "It looks good" is not permission.
+- MUST NOT commit to `main`, `master`, or any protected branch.
+- MUST NOT run `git add -A`, `git add .`, or any wildcard staging.
+- MUST NOT commit while any test is failing, any lint error stands, or any secret is present.
+- MUST NOT accept a self-reported "it works" — prove the behavior against the spec with a fresh command run (Phase 5) before committing.
+- MUST NOT skip, disable, or work around any automated gate.
+- MUST NOT commit a staged database migration without a recorded migration-review pass — the H-14 hook blocks it until `migration-reviewer` passes and `hooks/migration-pass.py` records the content-bound marker.
+- MUST NOT `--amend` after a pre-commit hook failure — create a new commit.
+- MUST NOT guess the test, lint, or secrets-scan command — read `tech-stack.md` or STOP.
+- MUST NOT silently rewrite a doc's claims — a claim-change edit proposed by Phase 5.5 goes through diff review (Phase 6), never through the silent re-baseline path. The re-baseline path is strictly for claims that still hold; the Phase 5.5 re-baseline MUST ride the work commit (staged by explicit path in Phase 7).
+- MUST, **at Phase 7 before staging**, run the follow-up harvest (`<plugin-root>/includes/harvest.md`) over any Phase 6 `[NEEDS-TRIAGE]` set-aside — promote to `open-tasks.md` (work) or `open-questions.md` (decision) so raised tasks ride the work commit. A follow-up that must survive PR abandonment is filed as a GitHub issue, not the board.

package/plugins/ca-pi/routines/context-check/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: context-check
+description: Optional manual drift audit — report stale provenance-tracked docs (via _provenancelib drift detection across .codearbiter/.provenance/), then per stale doc offer re-scout / re-baseline / defer. Not the daily loop; commit-gate auto-heal owns routine maintenance.
+---
+
+# context-check
+
+An optional, on-demand drift audit for bypass cases: a merge or an external
+edit drifted a tracked source file you are not about to commit, so commit-gate's
+Phase 5.5 auto-heal did not fire. This skill reports stale docs and lets you
+act on each one individually.
+
+This skill is NOT in the daily loop. Commit-gate auto-heal (Phase 5.5,
+`heal_worklist`) owns the routine maintenance path. Invoke this only when drift
+was introduced outside a commit (e.g. a direct push, a merge you did not
+author, a manual file edit).
+
+## Pre-flight
+
+Read these before computing drift:
+
+1. `.codearbiter/.provenance/` — the per-doc provenance records. Load all
+   records via `load_provenance_dir` from
+   `<plugin-root>/hooks/_provenancelib.py`.
+2. `.codearbiter/code-map.md` — coarse concern map; read to orient on which
+   modules the stale docs govern.
+
+## Flow
+
+### Step 1 — Compute drift
+
+Use `_provenancelib` helpers in this order:
+
+1. `load_provenance_dir(root + "/.codearbiter/.provenance/")` — returns the
+   provenance map `{doc: record}`.
+2. Collect all `drift_trigger: true` paths across all records.
+3. `batch_hash(paths, runner)` — hash every existing path in one git call.
+4. `compute_drift(provenance_map, current_hashes)` — returns a drift report
+   `{doc: [{path, kind}]}` for docs that have stale sources.
+
+Alternatively reuse the same logic as `startup_drift_line` by calling it for
+a human-readable summary, then inspecting `compute_drift` directly for detail.
+
+If the drift report is empty: report "no stale docs — provenance is fresh"
+and exit. No further action required.
+
+### Step 2 — Report stale docs
+
+For each doc in the drift report, call `changed_scope(doc_provenance, drift)`
+to list its drifted paths. Present a concise report before offering actions:
+
+```
+Stale docs (N):
+  <doc>: <path1>, <path2>  (changed | missing)
+  ...
+```
+
+### Step 3 — Per-doc action loop
+
+For each stale doc, present three choices and wait for the user to select one:
+
+**re-scout** — dispatch an incremental re-scout of the drifted paths for this
+doc, scoped to those paths only (like commit-gate Phase 5.5 heal but manually
+invoked). The scout re-reads the changed paths and reports whether claims still
+hold. If claims still hold: silently re-baseline the hashes via `rebaseline`.
+If claims changed: surface the proposed doc edits for the user to accept before
+re-baselining.
+
+**re-baseline** — acknowledge the drift without re-scouting: call
+`rebaseline(provenance, current_hashes)` to update the stored hashes silently.
+Use this when the source change is cosmetic (formatting, comments, whitespace)
+and the derived doc claims are still accurate.
+
+**defer** — do nothing for this doc now. The drift line will reappear at the
+next SessionStart. Use when the change is in-progress and the doc update should
+wait for a later commit.
+
+After processing all stale docs, summarize which docs were re-scouted,
+re-baselined, or deferred.
+
+## Hard rule
+
+This skill MUST NOT commit. If re-scout or re-baseline produces updated
+`.codearbiter/.provenance/` records, those file changes ride the next
+user-initiated commit through commit-gate normally. No staging, no commits here.

package/plugins/ca-pi/routines/context-creation/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: context-creation
+description: The brownfield back-fill. Routed to by /create-context, and by startup when .codearbiter/CONTEXT.md lacks the <!--INITIALIZED--> body marker but source code exists. Six gated phases — pre-flight, scout dispatch, synthesis, gap interview, write, lock. Reads the existing codebase through parallel scouts, drafts every surviving project-state doc, resolves gaps with the user, and locks the project as initialized.
+---
+
+# context-creation
+
+Wrap an existing codebase in project state, without guessing. Routed to by `/create-context`, and by startup when `.codearbiter/CONTEXT.md` exists but carries no `<!--INITIALIZED-->` body marker and meaningful source code is present. When no meaningful source exists, this is the wrong skill — route to `decompose` instead.
+
+This back-fills from existing source. It complements `/ca-init`, which scaffolds an empty `.codearbiter/` for a fresh project; here the docs are derived from what is already on disk.
+
+## Pre-flight
+
+Read these, or STOP and surface the gap — never guess project identity or a command:
+
+- `<project-root>/.codearbiter/CONTEXT.md` — if it already carries `<!--INITIALIZED-->`, context exists. Stop and route to normal operation.
+- The repository root listing (one level deep) — the source surface this skill extracts from.
+
+The excluded set (not "meaningful source"): `.git/`, `.codearbiter/`, `.claude/`, `AGENTS.md`, `CLAUDE.md`, `README.md`, `LICENSE`, `.gitignore`, `.gitmodules`, and standard tooling dotfiles (`.editorconfig`, `.prettierrc`, etc.). Meaningful source MUST exist beyond it.
+
+## Phase 1 — Pre-flight confirmation · gate: BLOCK
+
+Confirm the repository is a brownfield codebase safe for scout-based extraction:
+
+1. Confirm `<!--INITIALIZED-->` is absent from `CONTEXT.md`.
+2. Confirm meaningful source code is present beyond the excluded set.
+3. Identify the primary source directories (`src/`, `backend/`, `frontend/`, `lib/`, `app/`, or equivalent).
+
+State the finding to the user: existing source detected, beginning scout-based extraction.
+
+Gate: `<!--INITIALIZED-->` absent AND meaningful source present. If the marker is present, stop and route to normal operation. If no meaningful source exists, stop and route to `decompose`. Neither condition met → do not proceed.
+
+## Phase 2 — Scout dispatch · gate: BLOCK
+
+A **scout** is a restricted, read-only role, not an unconstrained
+`general-purpose` agent. A scout reads one targeted slice of the codebase and
+returns a structured findings report — file paths, line numbers, and named
+values only, never raw code excerpts. Scouts are internal to this skill; they
+are never invoked from a command.
+
+Dispatch six isolated `scout` subagents simultaneously. If the active host
+cannot provide isolated subagents, BLOCK context creation and report the host
+capability gap. The general inline-role fallback does not apply here: this
+skill's report-only synthesis contract depends on the orchestrator never
+loading the scouts' raw source into its own context.
+Each reads only its assigned slice:
+
+- **Scout A — Tech stack.** Read `package.json`, lockfiles, `pyproject.toml`, `requirements.txt`, `go.mod`, `Cargo.toml`, `*.gemspec`, `Gemfile`. Report languages, runtime versions, frameworks, key dependencies, the dependency manager, license fields. Additionally report, at the repository root only: which of `package.json` / `pyproject.toml` / `Cargo.toml` / `composer.json` carry a version field (candidate release manifests), which of `CHANGELOG.md` / `CHANGES.md` / `HISTORY.md` are present (candidate changelogs), and any existing tag naming convention visible in the repo (e.g. a `v*` tag) — the inputs Phase 3/5 use to draft `.codearbiter/release-targets.md`.
+- **Scout B — Infrastructure.** Read CI/CD config (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `.circleci/config.yml`), `Dockerfile*`, `docker-compose*.yml`, `Makefile`, `*.tf`, IaC. Report CI/CD platform, build/test/lint commands, deployment targets, environment names, containerization, IaC tool.
+- **Scout C — Architecture.** Read the source tree (names and structure only), entry points (`main.ts`, `index.ts`, `app.py`, `server.go`), and imports in entry points only. Report component list, entry points, module boundaries, architectural pattern, public interfaces.
+- **Scout D — Security posture.** Read auth files (`auth*`, `middleware*`, `guard*`, `jwt*`, `session*`, `oauth*`), crypto import lines, secret-loading sites (`process.env`, `os.environ`, vault/KMS call sites — paths and line numbers only, never values), `.env.example` (never `.env`). Report auth mechanism, crypto libraries, secret-loading patterns (paths + lines, no values), vault/KMS integration, hardcoded-secret risk files (paths only).
+- **Scout E — Testing.** Read test files and test config (`vitest.config.*`, `jest.config.*`, `pytest.ini`, Makefile test flags), coverage config. Report test framework, runner command, coverage tool, coverage thresholds in config, naming convention, approximate test count by type, fixtures.
+- **Scout F — Data model.** Read migration files (`migrations/`, `drizzle/`, `alembic/`, `db/migrate/`), schema definitions (`schema.ts`, `*.prisma`, `*.sql`, `models/`), ORM config, DB connection config (keys only, never credentials). Report database type, ORM/query builder, entity names, migration tool, approximate entity count, multi-tenancy patterns.
+
+The orchestrator reads only the scout reports in later phases — never the raw source — to preserve working context. A scout that finds nothing returns an explicit "not found" report, never silence.
+
+**Content hashes:** Scouts additionally emit a `git hash-object <path>` content oid per cited file in the hash field of their evidence entry. The scout already Read those files — no additional pass is needed, and no raw content is forwarded to the orchestrator.
+
+Gate: all six scout reports returned. A missing report is a blocking gap — do not proceed with an incomplete picture. Re-dispatch a failing scout before Phase 3.
+
+## Phase 3 — Synthesis · gate: BLOCK
+
+Draft every surviving project-state doc from the six reports, working only from the reports. Map source to destination:
+
+| Scout source | Destination |
+|---|---|
+| A (tech stack), B (build/test/lint commands), E (test runner) | `tech-stack.md` |
+| C (architecture), E (structure) | `coding-standards.md` |
+| D (security) | `security-controls.md` (thin) |
+| A (candidate manifest, candidate changelog, tag convention) | `.codearbiter/release-targets.md` |
+| All scouts | `CONTEXT.md` (project identity, purpose, scope, NOT-building) |
+
+Classify every finding by confidence:
+
+- **HIGH** — directly and unambiguously in a report (e.g., `"jest"` in `package.json`). Write it as fact.
+- **MEDIUM** — inferred from an indirect signal (directory layout implies layered architecture, no explicit config). Write it with a note: inferred from [signal], verify before relying on it.
+- **LOW** — no signal, or conflicting signals. Write a `[CONFIRM-NN]` placeholder.
+
+Every `[CONFIRM-NN]` carries: a sequential ID, one sentence on what is unknown, why it matters, and what would resolve it. IDs are sequential with `open-questions.md`.
+
+**`.codearbiter/release-targets.md` is HIGH-confidence only when Scout A found exactly one candidate manifest and exactly one candidate changelog at the repository root.** Draft the row then, in the grammar `<plugin-root>/hooks/_releaselib.py`'s module docstring declares — a single-target project needs only `prefix`, `manifest`, `changelog`, `payload`:
+
+```text
+<!-- release-targets -->
+[app]
+prefix: v
+manifest: package.json
+changelog: CHANGELOG.md
+payload: .
+latest-eligible: true
+<!-- /release-targets -->
+```
+
+(`prefix` defaults to `v` unless Scout A found a different existing tag convention; `payload` is `.` for a single-package repository.) Zero, or more than one, candidate manifest or changelog is LOW confidence — the same "no signal, or conflicting signals" rule above — and gets a `[CONFIRM-NN]` instead of a guessed row; this doc is never scaffolded from an ambiguous scan, and the file is simply not written until the gap is resolved in Phase 4.
+
+**`latest-eligible: true` is not cosmetic.** `/release`'s own back-fill detector (`detect_candidate_target`) emits it for this exact single-target shape, so a project drafted here and one back-filled through `/release` must agree — omitting it here would default the row's Phase-3 publish to `--latest=false`, and the same project would get different release behavior depending on which lane happened to declare it first.
+
+Gate: every surviving doc drafted; every low-confidence inference carries a `[CONFIRM-NN]`. No silent omission. A domain with no scout signal gets a doc with a `[CONFIRM-NN]` for the whole section — never an empty file.
+
+## Phase 4 — Gap interview · gate: BLOCK
+
+Resolve `[CONFIRM-NN]` items with the user. Ask only what the scouts could not answer with HIGH confidence.
+
+1. Present the `[CONFIRM-NN]` list grouped by category — gaps the scan could not resolve.
+2. Ask ONE targeted question per item. No compound questions. Do not re-ask anything scouts answered with HIGH confidence.
+3. Per answer: if it resolves the gap, replace the placeholder with content; if the user explicitly defers, keep the placeholder, mark it deferred with the date, and record it in `open-questions.md`; if the answer is vague, challenge it and demand a concrete answer before recording anything.
+
+Gate: every `[CONFIRM-NN]` has exactly one outcome — resolved (replaced with content) or explicitly deferred (marked and recorded in `open-questions.md`). No item is silently dropped. Do not proceed with unacknowledged gaps.
+
+## Phase 5 — Project-state write · gate: BLOCK
+
+Write the surviving docs to `<project-root>/.codearbiter/`. Every doc carries actual content — no unresolved placeholder may remain where a value was determined:
+
+| File | Content |
+|---|---|
+| `CONTEXT.md` | Project identity, purpose, scope, primary users, NOT-building. Frontmatter MUST include `arbiter: enabled` (the activation flag the SessionStart hook keys on) and `stage:` set to a single maturity number (default `1`; the user may raise it if the project is further along). |
+| `tech-stack.md` | Languages, frameworks, test runner, lint command, build command, coverage command, issue-tracker command (e.g. `gh issue create`). |
+| `coding-standards.md` | Structural patterns, naming conventions, style rules. |
+| `security-controls.md` | Thin: auth mechanism, banned crypto primitives, secret-loading stance. Only what a security boundary actually requires. |
+| `open-questions.md` | Every deferred `[CONFIRM-NN]` in `CONFIRM-NN: <description>` form. |
+| `open-tasks.md` | Create the file with its heading only. **Every task goes in through the board helper, one call per item — `python3 "<plugin-root>/hooks/taskwrite.py" add "<task>"` — never by writing entries into the file directly** (B-18). The helper owns the board schema the SessionStart hook and the statusline parse, so a backlog seeded this way cannot drift from it; and once `open-tasks.md` is enrolled in the protected-state registry, a direct write is refused outright, which would leave a Write-tool instruction here unfollowable. If scouts found no backlog, the heading-only file stands as the stub. |
+| `overrides.log` | Empty append-only audit log, created so `/override` has a sink. |
+| `release-targets.md` | Conditional, unlike every other row above: written ONLY when Phase 3 drafted it at HIGH confidence (exactly one candidate manifest, exactly one candidate changelog) or Phase 4 resolved its `[CONFIRM-NN]` to a concrete row. Left unwritten otherwise — `/release`'s own back-fill lane (or a later `context-creation` run, once the ambiguity resolves) is the sanctioned way to create it, never a guess made here. **This file is marker-gated protected state; it needs the authoring marker below, unlike every other row in this table.** |
+
+**Authoring marker — required for `release-targets.md` only.** That path is enrolled in the protected-state registry as `marker-gated` (hook `H-22`), so a Write against it is refused unless a fresh authoring marker exists. This lane is a sanctioned author of it, so it mints one immediately before the write and removes it immediately after — the same one-pass shape `/release`'s back-fill lane uses:
+
+```bash
+mkdir -p "$(git rev-parse --show-toplevel)/.codearbiter/.markers"
+touch "$(git rev-parse --show-toplevel)/.codearbiter/.markers/release-targets-authoring"
+```
+
+Write the file, then:
+
+```bash
+rm -f "$(git rev-parse --show-toplevel)/.codearbiter/.markers/release-targets-authoring"
+```
+
+Skip both commands entirely when this run is not writing `release-targets.md` — a marker minted for a write that never happens is a 30-minute window nothing needed. No other file in the table above is enrolled, so none of them take a marker.
+
+If scouts found existing decision records (`docs/decisions/`, `adr/`), summarize them as entries under `.codearbiter/decisions/` in the standard ADR format. If a record cannot be fully parsed, summarize what is known, flag the uncertainty, and note the source path for review.
+
+**Provenance and code-map (small addition, not a Phase 5 rebuild):**
+
+- Write ONE provenance file per derived doc to `.codearbiter/.provenance/<doc>.json` via `_provenancelib.write_provenance` and `new_record`. Each entry carries: `path` (repo-relative), `hash` (the scout's `git hash-object` oid), `drift_trigger` (from `_provenancelib.classify_source(path)`), and the `claims` array with `lines`, `claim`, and `confidence` drawn from the scout evidence.
+- Synthesize `.codearbiter/code-map.md` (concern → path → ≤1-line role) from Scout C (architecture) evidence. Use concern headings (`## <concern>`) and column-0 bullets (`- \`path\` — role`). Keep it coarse — module/concern granularity only, no full file listing.
+
+Do NOT scaffold any cut doc — see `<plugin-root>/includes/cut-docs.md` for the canonical never-scaffold list. Maturity lives in the `stage:` frontmatter of `CONTEXT.md`, not a separate file.
+
+Gate: every surviving doc written; `CONTEXT.md` frontmatter carries `arbiter: enabled` and `stage:`; no resolved value left as a placeholder. Deferred `[CONFIRM-NN]` items are acceptable only in `open-questions.md`.
+
+## Phase 6 — Initialization lock · gate: BLOCK
+
+Lock the project state as initialized and return to normal orchestration:
+
+1. Write the `<!--INITIALIZED-->` marker into the body of `CONTEXT.md`.
+2. List `.codearbiter/` and display the populated tree.
+3. Confirm each required file is present and non-empty: `CONTEXT.md` (with `arbiter: enabled` frontmatter and the `<!--INITIALIZED-->` body marker), `tech-stack.md`, `coding-standards.md`, `security-controls.md`, `open-questions.md`, `open-tasks.md`, `overrides.log`.
+4. State the return to normal operation: extraction complete, project state initialized and locked, `/ca-feature` available to begin work. Deferred questions live in `open-questions.md`.
+
+Gate: `arbiter: enabled` set and `<!--INITIALIZED-->` present in `CONTEXT.md`; every required file present and non-empty. Do not close this skill without confirming both markers are written.
+
+## Hard rules
+
+- MUST NOT write `<!--INITIALIZED-->` while any `[CONFIRM-NN]` is unaddressed — every gap must be resolved or explicitly deferred to `open-questions.md` first.
+- MUST NOT resolve a `[CONFIRM-NN]` by guessing — surface the question to the user or defer it.
+- MUST NOT proceed past Phase 2 with fewer than six scout reports.
+- MUST NOT run Phase 2 inline — isolated scout subagents are required for the report-only synthesis boundary.
+- MUST NOT load raw source into the orchestrator context after Phase 1 — synthesize from scout reports only.
+- MUST NOT record a scout finding that exposes a secret value — paths and line numbers only.
+- MUST NOT scaffold a cut doc — see `<plugin-root>/includes/cut-docs.md` for the canonical never-scaffold list. Maturity is the `stage:` frontmatter number in `CONTEXT.md`.
+- MUST NOT run when `CONTEXT.md` already carries `<!--INITIALIZED-->` — stop and route to normal operation.

package/plugins/ca-pi/routines/crypto-compliance/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: crypto-compliance
+description: The banned-primitive gate. Routed to when changed code hashes, signs, encrypts, derives keys, generates security-relevant randomness, configures TLS, or imports a crypto library. Rejects broken primitives, disabled TLS verification, and home-rolled crypto; the approved-primitive list lives in security-controls.md. The auth-crypto-reviewer agent is dispatched as the reviewer.
+disable-model-invocation: true
+---
+
+# crypto-compliance
+
+The banned-primitive gate. Routed to when changed code uses cryptography, hashing, signing, key derivation, security-relevant random generation, or TLS configuration.
+
+## Pre-flight
+
+Read these, or STOP and surface the gap — never guess the policy:
+
+- `<project-root>/.codearbiter/security-controls.md` — the project's approved and forbidden primitives, key requirements, and TLS minimum. If this file is unreadable, BLOCK; do not infer the policy.
+
+## Phase 1 — Banned-primitive scan · gate: BLOCK
+
+Scan every crypto operation in the changed code against `security-controls.md`. Apply the project's forbidden list; where it is silent, the following BLOCK unconditionally:
+
+- **Broken primitives** — `md5`, `sha1`/`sha-1` (including in HMAC or "just for IDs"), `des`, `3des`, `rc4`, and RSA keys below 2048 bits.
+- **Disabled TLS verification** — `rejectUnauthorized: false`, `verify: false`, or any disabling of certificate peer verification, on any connection.
+- **Home-rolled crypto** — a hand-built cipher, AEAD, KDF, signature scheme, or any reimplementation of a primitive in userland instead of a vetted, approved one.
+- **Unapproved primitive or library** — any algorithm, mode, key size, or crypto library not on the approved list in `security-controls.md`.
+
+Dispatch the `auth-crypto-reviewer` agent (`<plugin-root>/agents/auth-crypto-reviewer.md`) to confirm these findings against `security-controls.md`.
+
+Gate: no banned or unapproved primitive, no disabled TLS verification, and no home-rolled crypto in the changed code.
+
+**On pass — record the gate:** follow `<plugin-root>/includes/security-gate-record.md` (the shared record mechanism). For this gate the relevant commit hook is **H-09b** (crypto/TLS). On any BLOCK, do NOT record the pass.
+
+**Out-of-scope finding:** do not act on it and do not author an ADR (ADRs are user-attributed, via `/adr` only). Mark it inline with `[NEEDS-TRIAGE]`; never silently drop it.
+
+## Hard rules
+
+- MUST read `security-controls.md` before scanning — BLOCK if it cannot be read.
+- MUST NOT use MD5, SHA1, DES, 3DES, RC4, or RSA below 2048 bits — even for non-security checksums or IDs.
+- MUST NOT set `verify: false` or `rejectUnauthorized: false`, or otherwise disable certificate verification, on any TLS connection.
+- MUST NOT use a home-rolled or userland-reimplemented cryptographic primitive.
+- MUST NOT use any primitive, key size, or crypto library not on the approved list in `security-controls.md`.
+- MUST record the `security-gate-passed` marker (via `hooks/security-pass.py`) ONLY when the gate genuinely passes — the marker is what unblocks the commit (hook H-09b), so a premature or unconditional recording defeats the gate.

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

@@ -0,0 +1,99 @@
+---
+name: debug
+description: "Investigate-then-decide root-cause analysis for a defect whose cause is unknown (distinct from /fix, which assumes a known bug). Five gated phases: capture, hypothesize, gather, decide, hand off. Investigation only, no code changes; exits to /fix, /adr, or a no-action close."
+---
+
+# debug
+
+Find the cause first, fix it never. `debug` investigates and routes; it does not touch code. It drives one closed loop — **reproduce** (Phase 1) → confirm by cited evidence (Phases 2–3) → hand `/fix` a regression test that re-runs the repro and must pass (**verify**). The minimal repro is the anchor that closes the loop; code changes belong to `/fix`.
+
+## Pre-flight
+
+Read these, or STOP and surface the gap — never guess a log path, trace tool, or test runner:
+
+- `<project-root>/.codearbiter/tech-stack.md` — log paths, trace tooling, test runner conventions. The evidence sources.
+- `<project-root>/.codearbiter/CONTEXT.md` — domain vocabulary, system structure, and the `stage:` frontmatter (the maturity value; higher demands more rigorous evidence before exit).
+- `<project-root>/.codearbiter/security-controls.md` — only when the symptom touches a security boundary (auth, crypto, secrets). Optional; absent on most defects.
+
+The user MUST supply at least a one-sentence symptom. If absent, ask for one — do not guess the symptom.
+
+## Phase 1 — Symptom capture · gate: BLOCK
+
+Record the symptom with enough fidelity that another operator reproduces it without further questions:
+
+- **Observed** — one sentence: what the system did. Not the suspected cause; causes belong to Phase 2.
+- **Expected** — one sentence. If the user cannot state expected behavior, that itself may be a design/behavior ambiguity — flag it for Phase 4.
+- **Minimal repro** — exact command/request/action, required input and state, environment (local/staging/prod/test) and maturity value, frequency (every time / intermittent / one-time).
+- **Evidence in hand** — error messages, stack traces, log excerpts; cite the source of each (log path + timestamp, request ID).
+
+If no minimal repro exists, derive one with the user before continuing. An intermittent issue still has a trigger condition (an input pattern, a load condition, a timing window) — capture that.
+
+Gate: a minimal repro, or a documented intermittent-trigger profile. A symptom without one cannot be debugged, only speculated about. Every piece of evidence MUST cite its source.
+
+## Phase 2 — Hypothesis generation · gate: BLOCK
+
+Produce at least three distinct candidate causes, ranked by likelihood, before gathering any evidence against them. Distinct means different subsystems, mechanisms, or failure modes — not three rewordings of one suspicion.
+
+For each candidate write: a one-sentence hypothesis, the subsystem/boundary involved, and the mechanism by which it produces the observed symptom. Number them H1, H2, H3… for Phase 3.
+
+Rank by recency of relevant changes (recent commits to the suspect subsystem raise rank), symptom specificity (a symptom pointing narrowly at one mechanism raises it), and historical pattern.
+
+Include at least one **boring** hypothesis — environmental drift, dependency version change, config mismatch, stale cache, operator error. List it even if ranked last. Confirmation bias toward exotic causes is the recurring debug failure mode.
+
+Gate: three or more distinct hypotheses, one of them boring. Single-hypothesis lock-in is the single most common cause of misdiagnosis — the gate forces breadth before depth.
+
+## Phase 3 — Evidence gathering · gate: BLOCK
+
+For each hypothesis, identify what would confirm or refute it, then gather that evidence by reading existing artifacts only. No code is modified in this phase.
+
+For each H1…HN write the CONFIRM signal, the REFUTE signal, and the source where each lives (log file, trace tool, commit range, metric dashboard). Then read:
+
+- Application logs and traces at the paths/tools in `tech-stack.md`.
+- Recent commits (`git log`, `git diff`) on suspect paths.
+- Configuration, environment variables, feature flags (read-only).
+
+Annotate each hypothesis CONFIRMED, REFUTED, or INCONCLUSIVE, with a cited source. Do not collapse INCONCLUSIVE to CONFIRMED or REFUTED by inference — state what additional evidence is needed and where it lives. New hypotheses that emerge are added and gathered against; Phase 2 is a floor, not a ceiling.
+
+Gate: no code change of any kind — no edit, no refactor, no "try a fix." A hypothesis testable only by changing code becomes a Phase 4 finding (exit (a), with a regression test obligation), not a change here. No INCONCLUSIVE evidence promoted to CONFIRMED without a cited source.
+
+## Phase 4 — Root-cause decision · gate: BLOCK
+
+Walk the evidence ledger and pick exactly one exit. "We'll figure it out later" is not an exit.
+
+- **(a) Confirmed bug → `/fix`.** One hypothesis is CONFIRMED by cited evidence and the disposition is a code change. Carry: the hypothesis ID and statement, the cited confirming evidence, and a named **regression test obligation** — a one-sentence description of the test `/fix` MUST write (and watch fail) before any fix code. It MUST encode the Phase 1 minimal repro, so the exact condition that reproduced the defect becomes the test that proves it fixed — this is what closes the reproduce→fix→verify loop. `/fix` refuses to proceed without it.
+- **(b) Behavior/design ambiguity → `/adr`.** The system behaves as currently specified, but the specification itself is in question. Carry: the hypothesis ID and statement, a one-sentence statement of the ambiguity, and the symptom record plus evidence ledger as context. An ADR is authored only via `/adr` with explicit user attribution — surface the question to the user and obtain attribution; never author the ADR autonomously as the disposition of a debug session.
+- **(c) No-action close.** The symptom is non-reproducible, was a one-time environmental event, or was already resolved by an unrelated commit. Carry: a one-sentence rationale, the cited evidence supporting "no action," and a note appended to the symptom record.
+
+If a finding is real but out of scope for any of the three exits, mark it inline with `[NEEDS-TRIAGE]` and continue — do not stall on it.
+
+If no exit can be chosen — all hypotheses INCONCLUSIVE — loop back to Phase 3 for more evidence, or take exit (b) and surface the open question. "No decision" is not a valid exit.
+
+Gate: exactly one of (a) / (b) / (c) is named. Exit (a) carries a regression test obligation. Exit (b) carries the ambiguity statement and user attribution before any `/adr`. No exit closes on "more investigation needed" without either looping to Phase 3 or selecting (b).
+
+## Phase 5 — Handoff · gate: BLOCK
+
+Emit a summary downstream skills can consume without re-reading the session, then route:
+
+- **Summary block:** symptom (one sentence), reproduction profile, hypotheses considered (count + one-line list), evidence ledger summary (CONFIRMED / REFUTED / INCONCLUSIVE per hypothesis), the Phase 4 exit and rationale, and the handoff target.
+- **Exit (a):** route to `/fix` with the confirmed bug statement, cited evidence, and named regression test obligation. The orchestrator routes `/fix` to the `tdd` skill in bug-fix variant, where that test becomes the Phase 1 obligation that must fail before fix code. `debug` does not pre-write the test.
+- **Exit (b):** surface the chosen `/adr` with the ambiguity statement, symptom record, and evidence ledger attached as context, with user attribution.
+- **Exit (c):** record a queued entry **through the board helper, never by appending to the file** — `python3 "<plugin-root>/hooks/taskwrite.py" add "<symptom>" --desc "<no-action rationale>"` (add `--id debug.note` to mint a dotted ID; optional for a debug note). The helper owns the schema the SessionStart hook parses, so a note recorded this way cannot drift from it, and it is the only writer that `.codearbiter/open-tasks.md`'s protected-state class admits. This keeps the note in the in-flight count as an open item to revisit rather than a bare bullet. No further handoff.
+
+Surface the summary and the handoff to the user before the skill exits.
+
+Gate: the handoff is routed. Exit (a) carries an explicit regression test obligation. Exit (c) is recorded before close.
+
+## Hard rules
+
+- MUST NOT modify, refactor, or "try a fix" on any code during Phases 1–5. Code changes belong to `/fix`.
+- MUST NOT proceed past Phase 1 without a minimal repro or a documented intermittent-trigger profile.
+- MUST NOT proceed past Phase 2 with fewer than three distinct hypotheses, or with three rewordings of one suspicion.
+- MUST include at least one boring environmental / configuration / dependency hypothesis in Phase 2.
+- MUST NOT promote INCONCLUSIVE evidence to CONFIRMED or REFUTED without a cited source.
+- MUST cite the source of every piece of evidence — log path + timestamp, commit SHA, trace ID.
+- MUST exit Phase 4 with exactly one of (a) confirmed bug → `/fix`, (b) ambiguity → `/adr`, or (c) no-action close.
+- MUST NOT route to `/fix` for a bug not yet confirmed by cited evidence — `/fix` is for known bugs.
+- MUST NOT exit (a) without a named regression test obligation for `/fix` to carry into its TDD Phase 1.
+- MUST tie the exit-(a) regression test obligation to the Phase 1 minimal repro — the repro is the test that closes the loop.
+- MUST NOT author an ADR autonomously as the disposition of a debug session — exit (b) obtains user attribution and routes through `/adr`.
+- MUST NOT guess a log path, trace tool, or test command — read `tech-stack.md` or STOP.