@arbiterforge/ca-pi 0.6.0

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

@@ -0,0 +1,105 @@
+---
+name: ca-feature
+description: "Start a feature: brainstorm a spec, get it approved, then drive it test-first through the pipeline. The one entry to implementation."
+argument-hint: "<what you want to build>"
+---
+
+# /ca-feature — spec-driven feature
+
+The single permitted entry to implementation work. No feature code is written before a spec is approved and `tdd` Phase 1 clears. A one-line idea is not a spec — `brainstorming` makes it one.
+
+**Orientation:** if `.codearbiter/code-map.md` is present, read it first — a coarse concern→path→role map that orients task authoring. Absent is fine; it is read-on-demand, populated by context-creation or commit-gate heal.
+
+## Resume — an interrupted pipeline is re-entered, never restarted
+
+Before triage, scan `<project-root>/.codearbiter/specs/` and `plans/` for an existing slug
+matching `$ARGUMENTS` (invoked bare, list every resumable pipeline and ask which). A crash,
+compaction, or closed session mid-pipeline loses nothing — the spec, the plan, and each task's
+`status` cell are on disk. On a match, confirm the resume with the user in one line
+("resume `<slug>` at <point>?") and re-enter at the furthest checkpoint reached:
+
+1. **Plan exists with non-`ACCEPTED` tasks** → `executing-plans` (its Phase 1 batches only the
+   remaining tasks).
+2. **Plan exists, every task `ACCEPTED`** → `commit-gate` (the work is done and verified; it was the
+   commit that never happened).
+3. **Spec approved, no plan** → `writing-plans` (`<plugin-root>/routines/writing-plans/SKILL.md`).
+4. **Spec exists but never approved** → `brainstorming` (`<plugin-root>/routines/brainstorming/SKILL.md`), at its approval gate — not from scratch.
+
+Re-running `brainstorming` against an already-approved spec is the failure mode this section exists
+to prevent: it discards approved decisions and re-asks answered questions. Only an explicit user
+request ("start over") restarts an existing slug — and that is logged to `triage.log` like any
+classification.
+
+## Step 0 — change-class triage (logged)
+
+Before routing, classify the request. The **small lane** applies only when ALL of these hold —
+judged against `$ARGUMENTS` and a quick look at the code, never assumed:
+
+- the change touches ≤ 2 implementation files (plus their tests);
+- no §4 reference-map scope-touch: auth/crypto/secrets, dependencies, migrations/schema, telemetry,
+  public API surface, domain vocabulary;
+- no new dependency, endpoint, command, or configuration surface;
+- the behavior change is expressible as 1–3 concrete, individually testable acceptance criteria.
+
+**Small lane:** state the mini-spec inline (the 1–3 criteria) and STOP for the user's one-reply
+confirmation. On confirmation, append one line to `<project-root>/.codearbiter/triage.log`
+(append-only, `>>`):
+
+```
+[ISO-8601 timestamp] | BY: <git user.email> | LANE: small | SCOPE: <one-line> | BASIS: <criteria met>
+```
+
+Then route directly to `tdd` (`<plugin-root>/routines/tdd/SKILL.md`) — the confirmed criteria are its Phase 1 obligations; Phases 2–6 run
+unchanged — and exit through the full `commit-gate` and `finishing-a-development-branch` exactly as
+the full lane does. The lane trims ceremony, never gates.
+
+Any criterion violated, or uncertain → **full lane** (below). Uncertainty is full-lane; the triage
+never guesses.
+
+## Flow — full lane
+
+Route through the pipeline in order; each step gates the next:
+
+1. **`brainstorming`** (`<plugin-root>/routines/brainstorming/SKILL.md`) — refine `$ARGUMENTS` into a concrete spec by Socratic questioning: challenge
+   vague language, surface hidden complexity, force trade-offs. Writes the spec to
+   `<project-root>/.codearbiter/specs/<slug>.md`. **Hard gate: no plan and no code until the
+   user approves the spec.** Genuinely-unresolved unknowns become `[CONFIRM-NN]` in
+   `open-questions.md`, never guesses.
+2. **`writing-plans`** (`<plugin-root>/routines/writing-plans/SKILL.md`) — decompose the approved spec into small tasks, each with an exact path and a
+   verification that maps to a `tdd` obligation (it does not replace one). Writes
+   `<project-root>/.codearbiter/plans/<slug>.md` with bijective criterion↔task coverage.
+3. **`executing-plans`** (`<plugin-root>/routines/executing-plans/SKILL.md`) — coordinates the plan in small batches with human checkpoints. Each batch is
+   delegated to `subagent-driven-development` (`<plugin-root>/routines/subagent-driven-development/SKILL.md` — fresh author agent per task, spec-compliance review,
+   quality review, fresh verification). The user acknowledges between batches; nothing advances until
+   they do.
+4. **`commit-gate`** — the only path to a commit; nine gates, including behavioral proof.
+5. **`finishing-a-development-branch`** — terminal step: open-PR / merge-via-PR / discard. Every
+   change lands through a PR; never a direct write to the default branch.
+
+The autonomous counterpart (`/ca-sprint`) runs the same spec→plan but passes the full plan to
+`subagent-driven-development` directly, without per-batch checkpoints. That path is its own entry,
+not `/feature`.
+
+## Scope routing
+
+Scope determines which author agent `subagent-driven-development` dispatches per task:
+`backend-author`, `frontend-author`, or `infra-author` — per the mapping in `tech-stack.md`. A
+multi-area feature runs the appropriate agent per task; the full suite must be green before
+transitioning between scope areas.
+
+## When NOT to use
+
+- A known defect with a reproduction → `/fix`.
+- A behavior-preserving restructure → `/refactor`.
+- A question or quick discussion → `/btw`.
+- Persisting work already written → `/commit`.
+
+## Hard gate
+
+MUST NOT write feature code before a spec is approved AND `tdd` Phase 1 clears — the brainstormed
+spec in the full lane, the user-confirmed mini-spec in the small lane. MUST NOT take the small lane
+unless every Step 0 criterion holds, and MUST log the classification to
+`.codearbiter/triage.log` before `tdd` begins. MUST NOT skip `writing-plans` in the full lane.
+MUST NOT resolve a `[CONFIRM-NN]` in the spec by guessing — surface it.
+MUST NOT restart an interrupted pipeline whose artifacts exist on disk — resume at the furthest
+checkpoint per the Resume ladder, unless the user explicitly asks to start over.

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

@@ -0,0 +1,42 @@
+---
+name: ca-fix
+description: "Fix a confirmed bug: a failing regression test first, then a minimal fix, then the rest of the tdd gates."
+argument-hint: "<what's happening vs. what should happen>"
+---
+
+# /ca-fix — regression-first bug fix
+
+The only permitted entry to bug-fix work. No fix code is written before a regression test reproduces the defect and goes red for the right reason. Give the observed behavior and the expected behavior, plus a stack trace or reproduction when you have one.
+
+**Orientation:** if `.codearbiter/code-map.md` is present, read it before diagnosing — a coarse concern→path→role map that helps locate the defect. Absent is fine; it is read-on-demand.
+
+## Flow
+
+Routes to the `tdd` skill, bug variant — Phase 1 is framed around confirming the defect, not building
+new behavior:
+
+1. **Reproduce** the bug consistently.
+2. **Locate the root cause** — the exact code path producing the wrong behavior.
+3. **Write a regression test** that fails in the current state for the precise reason the bug causes
+   (not an unrelated error).
+4. **Confirm it's red for the right reason** — the failure message matches the described defect.
+
+Only then does `tdd` proceed: minimal fix to green, then the remaining `tdd` gates. The implementation
+agent (`backend-author`, `frontend-author`, or `infra-author`) is selected by where the bug lives. If
+the defect cannot be pinned by a failing test, STOP and surface the question.
+
+## Routes to
+
+`tdd` (`<plugin-root>/routines/tdd/SKILL.md`) — all phases, Phase 1 framed for bug confirmation.
+
+## When NOT to use
+
+- New behavior → `/ca-feature`.
+- A behavior-preserving restructure → `/ca-refactor`.
+- "Why does it do this?" → `/ca-btw`.
+- Persisting fix code already written → `/ca-commit` (the gates still apply).
+
+## Hard gate
+
+MUST NOT write fix code before the regression test is red for the right reason. MUST NOT accept a test
+that passes against the broken state as proof of the defect.

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

@@ -0,0 +1,56 @@
+---
+name: ca-init
+description: Opt this repo into codeArbiter — scaffold the root-level .codearbiter/ state store.
+argument-hint: "(none) | --stage N | --check"
+---
+
+# /ca-init — first-run scaffold
+
+Stand up the root-level `.codearbiter/` project-state store that opts a repo into arbiter
+management. This is the v2 replacement for vendoring/`init-vendor`: no symlinks, no shims, no dual
+root. It writes the activation flag and the empty state files, then hands off to the populator.
+
+`.codearbiter/CONTEXT.md` frontmatter `arbiter: enabled` is the single activation flag — it gates
+the SessionStart persona injection. The scaffolded
+`CONTEXT.md` is a **stub** (no initialization sentinel), so after scaffolding the project still needs
+populating before normal operation.
+
+## Procedure
+
+1. Run the scaffolder against the repo's git toplevel (resolved by the script):
+
+   ```
+   python "<plugin-root>/hooks/init-codearbiter.py"
+   ```
+
+   It is idempotent and refuses if `.codearbiter/CONTEXT.md` already exists — it never overwrites
+   state. Pass `--stage N` to set the initial maturity value (default `1`). Use `--check` to report
+   state without creating anything.
+
+2. It creates `.codearbiter/` with: `CONTEXT.md` (`arbiter: enabled`, `stage: N`, stub body),
+   `open-tasks.md`, `open-questions.md`, `overrides.log` (audit header), and `last-checkpoint` (`0`).
+
+3. **Then route to the populator** — the stub is not yet usable:
+   - **Source code already exists** in the repo → route to `/ca-create-context` (brownfield: scouts
+     read the codebase and synthesize the full context, writing the initialization sentinel).
+   - **Greenfield** (no meaningful source) → route to `/ca-decompose` (layered interview).
+
+   The populator is **mandatory, not optional**: it authors `tech-stack.md`, `coding-standards.md`,
+   and `security-controls.md` (and writes the initialization sentinel). The pipeline gates BLOCK on
+   reading those files — `writing-plans` and `tdd` need `tech-stack.md`, the security gates need
+   `security-controls.md` — so `/ca-feature` run on a freshly-scaffolded stub will STOP at pre-flight
+   until the populator has run. `session-start` surfaces this as `NOT INITIALIZED` every session.
+
+4. Report what was created and which populator you are routing to.
+
+## When NOT to use
+
+- `.codearbiter/` already scaffolded → the scaffolder refuses; run `/ca-create-context` or
+  `/ca-decompose` to populate, or `/ca-status` to see state.
+- You only want to re-check detection state → run the scaffolder with `--check`.
+
+## Hard gate
+
+MUST NOT hand-author `.codearbiter/CONTEXT.md` frontmatter — the scaffolder is the sanctioned path so
+the activation flag and state-file shapes match what the hook parses. MUST NOT mark a
+stub initialized; only the populator writes the initialization sentinel.

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

@@ -0,0 +1,80 @@
+---
+name: ca-metrics
+description: Read-only 3-metric governance glance — override rate, small-lane rate, sprint low-confidence ratio — each with a trend arrow vs. the prior 20-commit window.
+argument-hint: "[--window N]"
+---
+
+# /ca-metrics — governance trend glance
+
+A bare-numbers summary of the three governance-health metrics that `_metricslib.py`
+tracks across commit windows. Each metric shows its value for the **current** 20-commit
+window and a direction arrow (↑/↓/→) relative to the immediately preceding window.
+
+This is NOT a second `/ca-audit` packet. It prints numbers and arrows only — no
+verbatim override lines, no commit list, no file write. Use it to spot a trend at a
+glance; reach for `/ca-audit` when you need the full evidentiary packet.
+
+## Flow
+
+1. **Invoke the helper.** Call the thin entry hook `metrics.py`, which wraps
+   `compute` from `_metricslib.py`. 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 … || python …`, which reruns the helper on any nonzero exit
+   and reports the second run's code instead of the first's (#577). Pass
+   `<project-root>` as `--root`. If `--window N` was
+   supplied, pass it through as `--window N`; otherwise omit it (the helper
+   applies the default of 20).
+
+   ```
+   "$PY" "<plugin-root>/hooks/metrics.py" --root "<project-root>"
+   ```
+
+   > **`ensure_ascii` note — do not remove this.** `metrics.py` calls `json.dumps`
+   > with its default `ensure_ascii=True`. This ASCII-escapes the arrow glyphs
+   > (↑↓→) in the subprocess stdout, which avoids a `UnicodeEncodeError` on Windows
+   > `cp1252` consoles that cannot encode those code-points raw. The rendered output
+   > you present to the user (step 2 below) uses the real glyphs — they are written
+   > by the assistant, not piped through the subprocess stdout. Do NOT add
+   > `ensure_ascii=False` here.
+
+   With a custom window size:
+   ```
+   "$PY" "<plugin-root>/hooks/metrics.py" --root "<project-root>" --window N
+   ```
+   Replace `N` with the integer the user supplied.
+
+2. **Render the glance.** Parse the returned JSON dict. Present exactly three lines,
+   one per metric, in this order:
+
+   ```
+   override rate:          <current>  <arrow>  (prior: <prior>)
+   small-lane rate:        <current>  <arrow>  (prior: <prior>)
+   sprint low-conf ratio:  <current>  <arrow>  (prior: <prior>)
+   ```
+
+   - Use the real glyphs ↑, ↓, → in your message (not the JSON-escaped forms).
+   - For `sprint_low_conf_ratio`, the `current` or `prior` value may be the string
+     `"n/a"` — render it literally (e.g. `n/a ↑`).
+   - ↑ on `override_rate` and `sprint_low_conf_ratio` is a worsening signal; state
+     this briefly below the table so the reader does not have to guess.
+
+3. **State the window.** Append one line naming the window size used, e.g.
+   `Window: 20 commits (default)` or `Window: N commits (--window N)`.
+
+## Hard gate
+
+- Read-only. MUST NOT write, create, or modify any file. MUST NOT stage or commit.
+  `git status` MUST be unchanged after a run.
+- Emits ONLY the fixed 3-metric glance: `override_rate`, `small_lane_rate`,
+  `sprint_low_conf_ratio`. MUST NOT emit verbatim override log lines, verbatim
+  triage entries, commit lists, or any other content from the governance logs.
+- MUST NOT require `/ca-init` to have been run. The helper degrades gracefully on
+  absent logs (counts return 0 / ratio returns `"n/a"`); surface the degraded
+  values as-is rather than blocking.
+- If the helper subprocess fails entirely (import error, Python not found), report
+  the error and stop — do not fabricate metric values.
+
+## When NOT to use
+
+- Full governance packet with verbatim overrides and audit trail → `/ca-audit`.
+- Live project state (active sprint, open confirms, hook health) → `/ca-status`.

package/plugins/ca-pi/skills/ca-new-skill/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: ca-new-skill
+description: "Author a new codeArbiter skill: prove the gap is real, get the spec approved, then write it."
+argument-hint: "<verb-noun skill name>"
+---
+
+# /ca-new-skill — author a skill
+
+The only permitted entry to creating a skill. Nothing is written until the gap is proven uncovered — skills are not created speculatively. Name the skill in verb-noun form (`"dependency-review"`), not as a description (`"the thing that checks packages"`).
+
+## Flow
+
+Routes to the `skill-author` skill, which owns the work end to end through its five gated phases — gap
+evidence, scope, authoring, self-review against the v2 house style, and routing integration (the
+`INDEX.md` + routing-table entry that makes the new skill reachable). The phase definitions live in the
+skill; this command does not restate them. Nothing is authored until an existing skill or agent is
+proven not to cover the need; nothing ships until the new skill carries gated phases, hard rules, and
+its routing entry.
+
+## Routes to
+
+`skill-author` (`<plugin-root>/routines/skill-author/SKILL.md`) — all five phases.
+
+## When NOT to use
+
+- A one-time action → `/ca-feature` or a command definition.
+- An existing skill nearly covers it → extend that skill via `/ca-feature`.
+- "Do we even need a skill here?" → `/ca-btw`.
+
+## Hard gate
+
+MUST prove the gap is real in Phase 1 before writing any skill content. MUST get user approval on the
+spec before authoring. MUST NOT create a skill that duplicates an existing skill's purpose — surface
+the overlap instead. Skill files live only under `<plugin-root>/routines/<name>/`.

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

@@ -0,0 +1,72 @@
+---
+name: ca-override
+description: Sanctioned, logged bypass of a gate or hard rule — one audit line, then proceed.
+argument-hint: "<reason>"
+---
+
+# /ca-override — logged bypass
+
+The sanctioned escape hatch. Bypass is permitted only with an audit log entry. Overrides are always
+logged, always visible, never silent. Single identity, single confirm.
+
+## Flow
+
+1. Validate `$ARGUMENTS` — the reason names the gate being bypassed and a justification. Reject a
+   vague reason ("just skip it") and ask for a specific one.
+2. Detect the operator identity from `git config user.email` only. If it is unset, ask the user once
+   to state their identity for the log. (No platform ladder, no second confirmation.)
+3. Append one line to `<project-root>/.codearbiter/overrides.log`:
+
+   ```
+   [ISO-8601 timestamp] | BY: <email> | GATE: <gate bypassed> | REASON: <reason>
+   ```
+
+   The log is append-only — never edited or deleted, committed as a permanent audit artifact.
+4. Proceed with the overridden action. Note in the response that the override is logged.
+
+## Security ceiling — heavier path for security-critical stops
+
+A routine gate (lint, a style rule, a non-security review finding) takes the single-confirm path above.
+But a **security-critical stop is NOT bypassable by a single confirm.** The following require the
+heavier path below, never the one-line flow:
+
+- a security **CRITICAL** finding;
+- the crypto/secret commit gate (hook **H-09b / H-10b** — staged crypto/TLS or secret without a gate pass);
+- an **irreversible** operation (data loss, a destructive migration, anything unrollbackable).
+
+Heavier path (all required, in order):
+1. **Surface the specific finding verbatim** — name the exact primitive/secret/operation and the
+   concrete risk. A generic "security override" is rejected.
+2. **Explicit per-finding acknowledgement** — the user must acknowledge *that specific finding* in
+   their own words (a bare "yes"/"go ahead"/"I trust you" is declined — this mirrors `decision-variance`).
+   Detect identity from `git config user.email`; if unset, ask once.
+3. **Heavier log entry** — append a line tagged `SECURITY-OVERRIDE` that records the specific finding,
+   not just the gate name:
+
+   ```
+   [ISO-8601] | BY: <email> | SECURITY-OVERRIDE | FINDING: <specific finding> | REASON: <reason>
+   ```
+4. **Only then** record the bypass. For the crypto/secret commit gate, that means 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/security-pass.py"`,
+   which writes `<project-root>/.codearbiter/.markers/security-gate-passed` bound to the
+   sensitive lines it approves, so hook H-09b/H-10b allows the commit — recorded **only** after
+   steps 1–3, never to skip the gate proper.
+
+Under `/ca-sprint`, a security-critical override is a hard-gate STOP: it surfaces to the user and is
+**never** auto-decided, even in autonomous mode (`SPRINT.md` hard gates).
+
+## Hard gate
+
+MUST write the log line before proceeding — it is not optional. MUST capture an operator identity —
+"codeArbiter" or "automated" are not valid. MUST include a justification. The override is scoped to
+the immediate action only; it creates no standing exception. MUST NOT edit or delete an existing
+`overrides.log` entry. MUST route a security-critical / crypto-secret / irreversible stop through the
+**Security ceiling** path — never the single-confirm flow — and MUST NOT auto-decide such an override
+under `/ca-sprint`.
+
+## When NOT to use
+
+- Routine work that passes all gates — never needed.
+- Reconciling two conflicting sources → `/ca-conflict`.

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

@@ -0,0 +1,61 @@
+---
+name: ca-pr
+description: Open a pull request the only sanctioned way — clear every BLOCK-level review finding, then stage the PR. Never a direct write to the default branch.
+argument-hint: (none)
+---
+
+# /ca-pr — open a pull request
+
+The only permitted path to a pull request. Every change lands through a PR — never a direct write or force-push to the default branch. No PR is drafted while any BLOCK-level review finding stands.
+
+## Flow
+
+Routes to the `finishing-a-development-branch` skill, open-PR path. The orchestrator reads the current
+branch, its diff against the base, and the commit log to determine what changed and which reviewers
+apply, then:
+
+1. **Confirm the commit gate cleared** this session (`commit-gate` green, or `/ca-commit` completed).
+2. **Path matrix** — inspect the diff and dispatch the reviewer agents the change demands:
+   - auth / crypto / middleware paths → `auth-crypto-reviewer` + `security-reviewer`
+   - migration files → `migration-reviewer`
+   - dependency manifests → `dependency-reviewer`
+   - all paths → `coverage-auditor`
+3. **Run reviewers** in parallel where there are no dependencies.
+4. **BLOCK check** — any CRITICAL or HIGH finding STOPs the flow; present it and do not draft the PR.
+   The user resolves, re-runs `/ca-commit`, then `/ca-pr`.
+5. **Stage the PR** once all BLOCK findings clear: concise title; summary of what changed and why; a
+   bulleted test plan; a conflict-hierarchy tradeoff citation for any non-obvious tradeoff; a link to
+   any ADR the change implements or contradicts. The PR body is a user-facing deliverable: before
+   composing it, load `<plugin-root>/includes/anti-slop-design/core.md` and the
+   `medium-documents` leaf, and apply at least the §3.A em-dash ban and the §3.B copy self-audit to the
+   prose. Then `gh pr create`; return the URL.
+6. **Auto-attach the babysitter** — resolve the flag with the canonical resolver, never by eyeballing
+   the env var (so the accepted `on|true|1` spellings and the dormancy gate can't drift). 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 (#577):
+   ```
+   "$PY" "<plugin-root>/hooks/babysit.py" --root "<project-root>"
+   ```
+   It prints one JSON line, e.g. `{"enabled": true, "on_red": "propose"}`. Only when `enabled` is
+   true (the global flag `CODEARBITER_BABYSIT` is on — default off, mirrors `CODEARBITER_PRUNE` — and
+   the repo is arbiter-active), attach a CI watcher to the PR just opened, equivalent to
+   `/ca-watch <new-PR>`. When `enabled` is false, do nothing here — the user can still run `/ca-watch`
+   ad-hoc. Never enable the flag on the user's behalf.
+
+## Routes to
+
+`finishing-a-development-branch` (`<plugin-root>/routines/finishing-a-development-branch/SKILL.md`),
+open-PR path.
+
+## When NOT to use
+
+- Staged changes not yet committed → `/ca-commit`.
+- Review a diff without opening a PR → `/ca-review`.
+- A pre-implementation security pass → `/ca-threat-model`.
+
+## Hard gate
+
+MUST NOT open a PR while any BLOCK-level (CRITICAL or HIGH) finding is unresolved. MUST NOT skip a
+reviewer the path matrix requires. MUST NOT open a PR before the commit gate ran this session. MUST
+NOT open a PR, write, or force-push directly to the default branch. MUST NOT auto-attach a CI watcher
+unless `CODEARBITER_BABYSIT` is on, and MUST NOT enable that flag on the user's behalf.

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

@@ -0,0 +1,86 @@
+---
+name: ca-preview
+description: Zero-onboarding, read-only dry-run of the reviewer fleet against the current uncommitted diff. Predicts reviewers, runs the state-free secret scan, writes nothing.
+argument-hint: (none)
+---
+
+# /ca-preview — reviewer-fleet dry-run
+
+See what codeArbiter would do to your real code before paying any onboarding cost. This is a
+read-only dry-run against the current uncommitted diff: it predicts which reviewers the change
+would dispatch, runs the checks that need no project rules, and reports. It never writes state.
+
+It requires no `/ca-init`, no `.codearbiter/` directory, and no decompose or create-context
+interview. It functions in a repo that never opted in, and it modifies nothing: not the worktree,
+not the index, not `.codearbiter/`. `git status` is unchanged by a run.
+
+## Flow
+
+1. **Collect the diff.** Call the thin entry hook `preview.py` in `diff` mode, which wraps
+   `collect_diff` from `<plugin-root>/hooks/_previewlib.py`. It unions HEAD-vs-worktree
+   changes, staged changes, and untracked files (forward-slash paths). Run it from the project
+   root so `_previewlib`/`_hooklib` resolve on the same `sys.path`. 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 (#577):
+   ```
+   "$PY" "<plugin-root>/hooks/preview.py" diff
+   ```
+   If the result is empty (clean tree, or not a git repo), print a friendly **"Nothing to
+   preview"** line and STOP. This is a clean exit, not an error: no stack trace, no failure.
+
+2. **Predict reviewers by path.** Read the reviewer-to-path matrix at
+   `<plugin-root>/includes/review-matrix.md`. That include is the single source of truth
+   for which reviewer is dispatched when scope touches a given path: do NOT restate, fork, or
+   inline a second copy of the table here. For each changed path, list the reviewers that WOULD
+   dispatch and name the triggering path for each. This is the same mapping `/ca-review` uses, so
+   the predicted set matches what a real review would dispatch.
+
+3. **Run the state-free secret scan.** Call the thin entry hook `preview.py` in `secrets` mode,
+   which wraps `scan_secrets` from `<plugin-root>/hooks/_previewlib.py`. It reads each
+   changed file's current content and returns `SecretFinding(path, line_no, snippet)` for every
+   credential line, with the secret VALUE already masked to `****` in `snippet`:
+   ```
+   "$PY" "<plugin-root>/hooks/preview.py" secrets
+   ```
+   Report each finding by `path:line_no` with its redacted snippet. The snippet arrives already
+   masked: never reconstruct or print a raw secret value.
+
+## Report
+
+Emit one clear report with these parts:
+
+- **Changed files** — the reviewed-file set from step 1, each with its change kind(s) (unstaged,
+  staged, untracked).
+- **Predicted reviewers** — per the matrix, which reviewers would dispatch and the triggering path
+  for each. These are predicted (would-dispatch), not run here.
+- **Secret findings** — the results of the real scan from step 3, by `path:line_no` with the
+  redacted snippet, marked as found (ran locally), at BLOCK severity. State "none found" when the
+  scan is clean.
+- **Onboarding nudge** — close with one line: the full gated review comes via `/ca-init` then
+  `/ca-review`.
+
+## Distinct from /ca-doctor
+
+This reports reviewer and gate behavior on the current diff. It makes NO hook-probe claims and says
+nothing about wrapper wiring or the active-dispatch coverage gap: that is `/ca-doctor`.
+ Do not blend the two.
+
+## When NOT to use
+
+- An onboarded repo wanting the full gated verdict → `/ca-init` then `/ca-review`.
+- Inspecting wrapper wiring and the active-dispatch coverage gap → `/ca-doctor`.
+
+- A question about the code → `/ca-btw`.
+
+## Hard gate
+
+- Read-only. MUST NOT write, create, or modify any file, including anything under `.codearbiter/`;
+  MUST NOT stage or commit. `git status` MUST be unchanged after a run.
+- MUST NOT require, trigger, or error on missing `/ca-init`, `.codearbiter/` state, or the
+  decompose / create-context interview.
+- MUST NOT print a raw secret value: the lib returns the snippet already redacted, and the report
+  carries only that masked form.
+- An empty diff or a non-git directory MUST yield the "Nothing to preview" message and a clean
+  exit, never a stack trace.
+- MUST treat the reviewer prediction as predicted (would-dispatch) and the secret scan as found
+  (ran locally): it MUST NOT attribute fabricated findings to any predicted reviewer.

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

@@ -0,0 +1,100 @@
+---
+name: ca-prune
+description: Trim transcript clutter to extend session lifetime — analyze, prune a copy, or toggle the after-each-turn service. Dry-run by default; gains land at resume/compaction, not the current turn.
+argument-hint: "status | dry | run <path> | audit <path> | on | off"
+---
+
+# /ca-prune — session transcript pruner
+
+Long sessions die when their semantic history fills the context window with bulk: oversized tool
+outputs, thinking blocks, MCP/shell noise, stale file reads, and host-specific sidecars. The shared
+policy trims that bulk at safe quiescence boundaries while each host codec preserves its native
+integrity model and the K most recent tool-bearing turns verbatim. Claude keeps byte-safe JSONL
+serialization; Pi uses semantic entries and returns a native custom-compaction result.
+Gains land at the host's next native resume/restart or compaction boundary, not by mutating the
+running session's active file. **Pi-native compaction** is event-driven and never rewrites an active
+Pi session file.
+
+## Argument
+
+`$ARGUMENTS` is one of:
+
+- `status` (default) — report cumulative reduction and service state for this session from
+  `~/.codearbiter/prune-state.json`, and whether `CODEARBITER_PRUNE` is `on`/`dry`/`off`. When
+  the service has run in `dry` mode, every would-be prune is also recorded — one JSONL row per
+  decision, across all sessions — to the shared data-collection log
+  `~/.codearbiter/metrics/prune-dry.jsonl` (override with `CODEARBITER_PRUNE_METRICS`). That log is
+  the evidence base for the `dry`→`on` decision: a clean record (every row `verdict: dry-run`,
+  `validation_errors: 0`) over a representative set of sessions is the signal that enabling is safe.
+  Read `context_bytes_freed` / `context_est_tokens_freed` for model-context benefit and
+  `file_bytes_freed` / `file_pct` for disk and resume-parse benefit. `sidecar-collapse` is explicitly
+  `file-only`; it must not count toward the context-benefit or cold-cache decision.
+  The legacy `freed_bytes`, `pct`, and `est_tokens_before` / `est_tokens_after` fields remain
+  whole-file compatibility aliases; do not use them as model-context evidence.
+- `dry` — create a read-only semantic plan (or analyze a scratch copy where the host exposes a
+  serialized transcript); present the per-strategy reduction table with every strategy labeled
+  `context` or `file-only`. Never writes the active session.
+- `run <path>` — prune the target with `--execute`. Targets a **copy or an old/inactive
+  transcript only** — the tool refuses an active or recently-modified target by construction.
+- `audit <path>` — read-only integrity report: line-parse, uuid chain, tool-pair coverage,
+  condensation markers.
+- `on` / `off` — guidance on enabling or disabling the after-each-turn service.
+
+## Flow
+
+1. **status / dry / audit** — run the backing tool and present its output verbatim. 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 (#577):
+   ```
+   "$PY" "<plugin-root>/hooks/prune-transcript.py" <subcommand> [<path>]
+   ```
+   For serialized hosts, `dry` analyzes `<path>.copy.jsonl`; Pi active sessions use the native
+   semantic planner and return a custom compaction result without session-file writes.
+
+2. **run** — confirm the path is a copy or an inactive session, then:
+   ```
+   "$PY" "<plugin-root>/hooks/prune-transcript.py" <path> --execute [--tier T]
+   ```
+   Present the per-strategy reduction report; follow with `audit` on the result.
+
+3. **on/off** — explain the after-each-turn service: `UserPromptSubmit` and `PreCompact` hooks
+   prune at safe quiescence points, always exit 0, and never block the prompt. Tiers: `gentle`
+   (sidecar + oversize clamp), `standard` (+ reasoning fold, aged/MCP/shell), `aggressive`
+   (+ stale-read, reminder dedup, image evict). Config via `CODEARBITER_PRUNE` (`off`|`dry`|`on`,
+   ships **off**), `CODEARBITER_PRUNE_TIER`, `CODEARBITER_PRUNE_KEEP_RECENT` (the K most recent
+   tool **turns** kept verbatim — each turn is an assistant tool_use plus its results),
+   `CODEARBITER_PRUNE_MAXBYTES`. Enabling is the user's explicit choice — never set it unbidden.
+   In `dry` mode the service writes no transcript but appends each would-be prune to
+   `~/.codearbiter/metrics/prune-dry.jsonl` (path override: `CODEARBITER_PRUNE_METRICS`) for
+   data collection; in `on` mode the executed prunes are recorded in `~/.codearbiter/prune.log`.
+   If a prior service-mode prune was killed mid-write, the next run self-heals the transcript
+   from the newest backup in `~/.codearbiter/prune-backups/` before doing anything else.
+
+   **Cold-miss nudge** [Feature Forge — `preview`]: when `CODEARBITER_PRUNE` is `on`, an
+   optional submit-time speed bump warns once before a cold cache re-cache lands on bloated
+   context. Enable with `CODEARBITER_PRUNE_NUDGE=on` (default `off`). When all arming conditions
+   hold (idle ≥ `CODEARBITER_PRUNE_NUDGE_IDLE_SECS`, default 240 s; estimated model-context
+   tokens freed ≥
+   `CODEARBITER_PRUNE_NUDGE_MIN_TOKENS`, default 80 000), the hook blocks the submit once with
+   an advisory on stderr and returns exit code 2. File-only sidecar reduction never arms it. The
+   advisory names the approximate avoidable context-token count and the host-native actions that
+   move the re-cache to pruned context:
+   native compaction or a normal exit + resume/restart. Resubmitting immediately proceeds. The block fires at most
+   once per cold window; a subsequent warm submit (idle < floor) resets the window so the next
+   genuine cold stretch re-arms. The gate is strictly opt-in, never fires in `dry`/`off` mode,
+   and fails open on any error — a pruner fault will never block the session.
+
+## When NOT to use
+
+- Context bar nowhere near compaction — the most recent turns are protected anyway.
+- Install health → `/ca-doctor`.
+- Project progress → `/ca-status`.
+
+## Hard gate
+
+- MUST NOT run `--execute` against the **live** session's transcript — the tool refuses a
+  recently-modified file by construction; manual `run` targets copies or old sessions only.
+- MUST surface the native-boundary-only gains limitation whenever a user expects an immediate
+  active-file context drop.
+- MUST NOT enable the service (`CODEARBITER_PRUNE=on`) on behalf of the user — explain and let
+  them decide.