@arbiterforge/ca-pi 0.14.9 → 0.14.12

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

@@ -1,11 +1,17 @@
 ---
 name: skill-author
-description: The authoring gate for new skills. Routed to when the user invokes /new-skill "<gap>". Five gated phases — gap evidence, scope, authoring, self-review against the v2 house style, routing integration. A new skill is not written until an existing one is proven not to cover the gap, and not shipped until it carries gated phases, hard rules, and a routing entry. Every authored skill matches the v2 format (frontmatter name+description, # name, Pre-flight, Phase N · gate, Hard rules).
+description: Assess a request for a new reusable codeArbiter skill, prove the uncovered gap, agree scope, author and integrate it. Questions and one-off tasks do not authorize adding a skill.
+argument-hint: <gap or verb-noun skill name>
 ---
 
 # skill-author
 
-Author a new skill, the right way. Routed to when the user invokes `/new-skill "<gap>"`.
+Author a new skill, the right way. The public entry and natural-language requests route
+here; this complete owner is also available as a directly read internal resource.
+Use a verb-noun name (for example, `dependency-review`), not a descriptive sentence.
+A one-time action belongs to the applicable work procedure. A question about whether a
+skill is needed is answered without authoring; an almost-matching owner is reviewed and
+extended through the existing change workflow rather than duplicated.
 
 ## Pre-flight
 
@@ -13,7 +19,9 @@ Read these, or STOP and surface the gap — never author on assumption:
 
 - The `<gap>` argument. Absent → STOP and ask: "Describe the gap this skill would fill. What situation does no existing skill cover today?"
 - `<plugin-root>/routines/INDEX.md` — the surface scan of every existing skill. This is the gap-overlap check in Phase 1 and the integration target in Phase 5. Never bulk-read the skill bodies.
-- `<plugin-root>/routines/commit-gate/SKILL.md` and `<plugin-root>/routines/tdd/SKILL.md` — the canonical v2 format the authored skill must mirror. Read them before Phase 3.
+- `<plugin-root>/routines/commit-gate/SKILL.md` and `<plugin-root>/routines/tdd/SKILL.md` — the canonical v2 format the authored skill must mirror. Read them before Phase 3. The command-backed commit owner also demonstrates the
+  single-source entry convention. Keep its description and argument hint with the
+  owning skill; the generator supplies the compatible public spelling per host.
 - `<project-root>/.codearbiter/CONTEXT.md` — project context, only if the gap is project-specific. A generic skill needs no project state.
 
 ## Phase 1 — Gap evidence · gate: BLOCK
@@ -47,7 +55,7 @@ Gate: explicit user agreement on routed-vs-dispatched, command-vs-internal, and
 
 Write `SKILL.md` to the v2 house style — mirror `commit-gate` and `tdd` exactly. Start from `<plugin-root>/routines/skill-author/references/skill-template.md`. Required shape:
 
-- **Frontmatter** — `name:` and `description:` only. Description is terse: what routes to it, the phase count, the gate. No cut doc refs, no trigger disclaimer.
+- **Frontmatter** — `name:` and `description:` as the normal base. Description is terse: the requested outcome, when it applies, and important negative intent. A command-backed owner also records its argument hint and keeps its natural-language description on the owner. The generator suppresses only the redundant Claude command description. No cut doc refs, no trigger disclaimer.
 - **`# <name>`** H1, then a one-line intro naming what routes to it (`/<command>` or the parent skill).
 - **`## Pre-flight`** — the docs to read or STOP on. Project state cites `<project-root>/.codearbiter/<doc>`; other skills cite `<plugin-root>/routines/<name>`; agents cite `<plugin-root>/agents/<name>.md`. Never guess a command — read it or STOP.
 - **`## Phase N — <title> · gate: BLOCK|STOP`** — sequential, each ending in a one-line `Gate:`. A phase with output that could be wrong has a gate; only a purely declarative phase may omit one.
@@ -68,7 +76,11 @@ Re-read the authored skill against the v2 quality bar. Each line below is a chec
 - **Concrete gates** — every non-declarative phase ends in a `Gate:` line stating a checkable condition. "Looks good" / "seems right" is not a gate; rewrite it.
 - **House-style prose** — terse, imperative, matches `commit-gate`/`tdd`. Strip hedging and filler.
 - **No duplicated rules** — a rule stated in a phase is not restated in Hard rules, and Hard rules carry no duplicates. State each rule once.
-- **Format conformance** — frontmatter is `name`+`description`, plus `disable-model-invocation: true` ONLY on a chain-internal skill (never user-typed, reached solely via routing-table path loads — see ADR-0028); H1 matches `name`; phases are numbered with `· gate:`; paths use `<plugin-root>` / `<project-root>` correctly; no cut docs/skills, no legacy `${FRAMEWORK_ROOT}`/`${PROJECT_ROOT}`/`.agents/` paths.
+- **Format conformance** — frontmatter is `name`+`description`, plus `disable-model-invocation: true` on a chain-internal skill (ADR-0028);
+  a command-backed owner instead remains discoverable and also owns its
+  `argument-hint`. The generator suppresses the redundant command listing only on
+  command-native hosts; Codex/Pi entries remain discoverable. Other invocation/tool/model metadata
+  needs explicit generator support, never silent dropping; H1 matches `name`; phases are numbered with `· gate:`; paths use `<plugin-root>` / `<project-root>` correctly; no cut docs/skills, no legacy `${FRAMEWORK_ROOT}`/`${PROJECT_ROOT}`/`.agents/` paths.
 - **Frontmatter scalar quoting** — any frontmatter scalar that starts with `[` or `{`, or contains `": "` or `" | "`, MUST be JSON-quoted (the `_yaml_safe_scalar` predicate the surface generator applies to codex/pi wrappers; the claude surface ships frontmatter verbatim, so the author quotes it at the source).
 - **No trigger language** — "routed to" / "dispatched" only, and no `## Trigger` disclaimer block.
 - **Evidence lenses** (issue #612) — each checked where the skill's shape triggers it, skipped where it does not:
@@ -90,6 +102,15 @@ A skill no one routes to is dead code. Wire it in.
 - Add a row to `<plugin-root>/routines/INDEX.md`: skill name (linked), "Routed to by", and "Owns" (the one-sentence responsibility from Phase 2).
 - Add the skill to the routing table — the invocation cue (the `/<command>` or condition), the primary route, any dispatched agents, the hard gate. For a command-invoked skill, also register the `/<command>` in the command reference.
 - For an internal skill, update the named parent so it routes to the new skill explicitly.
+- Before adding a command wrapper, check whether it would only repeat the skill's
+  description and route back here. In codeArbiter source, use the existing generator's
+  whole-file SKILL_ENTRY declaration for a genuinely command-backed owner; keep its
+  argument hint and procedure in that one discoverable owner. On Claude the generated
+  command remains explicitly usable without a duplicate model listing; Codex/Pi use
+  their generated entry skill for discovery and keep the owner in private routines.
+  Do not register another public operation solely for an implementation step. A
+  directly referenced information card can remain outside discovery roots, owned by
+  its existing caller; it does not need fabricated skill frontmatter or an INDEX row.
 
 Verify no broken references: every path the skill cites resolves. `INDEX.md` row parity and routing-table dangling-route freedom are no longer a hand-check here — `.github/scripts/check_routing_index_parity.py` enforces both mechanically in CI (issue #592); a missing row, an orphan row, or a route to a name that does not exist fails the build.
 

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

@@ -1,6 +1,6 @@
 ---
 name: writing-plans
-description: The spec-to-plan bridge. Routed to by /feature once the brainstormed spec is approved, and by /sprint before execution. Decomposes the spec into 2–5 minute tasks, each carrying its exact file path(s) and a concrete verification step that maps to a tdd obligation. Writes the plan in the approved spec's authoritative format, ordered with dependencies flagged and an MVP slice identifiable. Nothing executes until every task has a path and a verification and the task set covers every acceptance criterion.
+description: The spec-to-plan bridge. /feature supplies an approved spec; initial full-lane HTML sprint review may supply a ready draft only through draft_for_pair. Creates the same-format plan with exact paths, tests, dependencies and complete criterion coverage. The initial paired review has no execution authority until one real user reply approves both artifacts. Ordinary sequential planning retains approved-source binding and plan approval.
 disable-model-invocation: true
 ---
 
@@ -17,16 +17,21 @@ Markdown spec continues through the legacy Markdown path without conversion.
 HTML `--farm` dispatch remains blocked.
 
 
-Turn an approved spec into an executable plan. Routed to by `/feature` (after spec approval) and `/sprint`.
+Turn an approved spec into an executable plan, or prepare a ready draft plan for initial combined
+HTML sprint review. Draft preparation is not execution authority. Routed to by `/feature` (after
+spec approval) and `/sprint` under its explicit call mode.
 
 ## Pre-flight
 
-Read these, or STOP and surface the gap — never plan against an unapproved or missing spec:
+Read these, or STOP and surface the gap. Missing specs always block. Ordinary planning requires
+approval; only initial full-lane HTML sprint-pair preparation accepts an exact ready draft:
 
 - The authoritative approved spec selected by `/feature`: for HTML, resolve it
   through the installed engine and verify its ready approval and exact identity;
   for legacy Markdown, read `<project-root>/.codearbiter/specs/<slug>.md`.
-  Absent or unapproved → STOP and route back to `/feature`.
+  Absent → STOP. Unapproved → STOP except the explicit initial sprint `draft_for_pair` mode,
+  which verifies ready/current draft identity through the private preflight and never grants execution.
+  Route a genuine missing prerequisite back to the active caller, not an unrelated feature interview.
 - `<project-root>/.codearbiter/CONTEXT.md` — the `stage:` frontmatter (the maturity value) and project context.
 - `<project-root>/.codearbiter/tech-stack.md` — file layout, build/test/lint invocations. A verification step cites a real command from here, never a guess.
 - `<project-root>/.codearbiter/coding-standards.md` — structure and naming, so a task names the right path.
@@ -107,12 +112,16 @@ that completeness gap is caught earlier, by Phase 1's `uncovered_intent` backsto
 - Every task advances at least one `AC-NN`. A task that covers nothing is scope creep — cut it or surface it.
 
 For an HTML source, pass the selected route, installed client, and the spec
-identity just read from the engine through `_preflight_plan_authoring`. Only its
+identity just read from the engine through `_preflight_plan_authoring`. Initial full-lane sprint
+pair preparation alone sets `draft_for_pair: true`; the ordinary default still requires approval. Only its
 returned same-slug `.codearbiter/plans/<slug>.html` target may be created. Create
 that plan through the installed structured-artifact engine as `draft_preview`,
-using the approved spec's exact artifact ID and normative digest. Populate it only with typed operations,
-validate it at the ready gate, then use `plan-bind` to bind it to that approved
-spec before plan approval. This path must not create `.codearbiter/plans/<slug>.md`;
+using the source spec's exact artifact ID and normative digest. For ordinary sequential planning,
+this must be the approved spec's exact artifact ID and normative digest. Populate it only with typed operations
+and validate it at the ready gate. For initial combined review, retain `draft_preview` and return
+both ready identities to the caller: `sprint-approve` owns the binding and both approvals after one
+actual host-observed reply. Do not separately `plan-bind` or approve that pair. On ordinary approved-spec
+planning, use `plan-bind` to bind it to the approved spec before plan approval. This path must not create `.codearbiter/plans/<slug>.md`;
 that would be a shadow authority.
 
 For an existing authoritative Markdown source, write
@@ -127,7 +136,8 @@ re-entered by `/feature` at the first non-`ACCEPTED` task instead of restarted f
 
 Gate: bijection proven between the plan and the ledger — no criterion without a task, no task without
 a criterion — and the plan written to disk. This proves the two are mutually consistent, nothing more;
-completeness of the ledger itself was Phase 1's gate, not this one. This clears the path to execution:
+completeness of the ledger itself was Phase 1's gate, not this one. Initial combined-review drafts
+return for `arm-sprint`, never execution. Only verified approved spec-and-plan authority clears execution:
 `executing-plans` (checkpointed, via `/feature`) or `subagent-driven-development` (autonomous, via
 `/sprint`) — each routes every task through `tdd`. The plan never hands off to `tdd` directly.
 
@@ -143,7 +153,9 @@ artifacts exist before handing off to `subagent-driven-development` (`<plugin-ro
 
 ## Hard rules
 
-- MUST NOT plan against an absent or unapproved spec — STOP and route back to `/feature`.
+- MUST NOT execute or approve work against an absent or unapproved spec. Only explicit initial
+  full-lane HTML `draft_for_pair` planning accepts a ready draft and must return for combined approval;
+  other unapproved inputs route back to their actual caller.
 - MUST NOT write or parse rendered HTML directly, create a Markdown shadow for
   an HTML spec, or bind a plan from a caller-supplied identity.
 - MUST NOT emit a task without an exact path AND a concrete verification step.

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

@@ -1,28 +1,182 @@
 ---
 name: ca-commit
-description: Run the full commit gate — the only sanctioned path to a git commit.
+description: Create a verified local Git commit when committing changes is requested. Not for explaining commit history, drafting a message only, or postponing a commit. Applies every commit gate and never implies a push or PR.
 argument-hint: (none)
 ---
 
-# /ca-commit — commit gate
+# commit-gate
 
-The only path to a commit. The orchestrator issues no `git commit` without the `commit-gate` skill
-clearing first. "It looks good" is not authorization. No arguments — the skill reads current git
-state (staged files, diff, test results) and decides whether every gate is green.
+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.
 
-## Routes to
+No command arguments are required; inspect current Git state. Test-only requests use the
+recorded invocation in `tech-stack.md` without entering this committing procedure. PR
+readiness belongs to the existing PR workflow; an informational or message-only request
+must not reach staging, commit, or this procedure's writing close.
 
-The `commit-gate` skill (`<plugin-root>/routines/commit-gate/SKILL.md`) — all phases. The skill
-is canonical for its phases, gates, and output format.
+## Pre-flight
 
-## When NOT to use
+Read these, or STOP and surface the gap — never guess a command:
 
-- Before writing code → `/ca-feature` or `/ca-fix` first.
-- To check PR readiness → `/ca-pr` (dispatches additional BLOCK-level reviewers).
-- To run tests without committing → run the test command from `tech-stack.md` directly.
+- `<project-root>/.codearbiter/tech-stack.md` — test, lint, and secrets-scan invocations. Stop if missing; do not guess.
+- `<plugin-root>/includes/verification-boundary.md` — the required split between focused local proof and exhaustive exact-head hosted CI.
+- 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.
+- The discovered authoritative spec/plan pair, when this commit belongs to a
+  `/feature` or `/sprint` pipeline. For HTML, load
+  `<plugin-root>/includes/artifacts.md`; use the engine `identity` and `eligible`
+  results, and treat the exact spec and plan identities plus the acceptance
+  receipts bound in engine state as the commit proof. Require
+  `all_accepted_and_current: true` before this gate can commit completed plan
+  work. The gate must not parse rendered HTML and must not consult a shadow
+  Markdown ledger. Displayed state, checkboxes, hashes, or caller-supplied
+  labels cannot substitute for current engine acceptance.
 
-## Hard gate
+For that HTML pair, invoke the installed bridge's
+`_preflight_current_acceptance` with the exact `_resolve_workflow_pair` result,
+the repository-bound client, and the spec/plan IDs returned by the engine. Use
+its returned identities and receipts as the proof for this gate. A refusal is a
+BLOCK before staging or committing; never construct an equivalent proof from
+caller metadata.
 
-MUST NOT commit without `commit-gate` clearing. The applicable impact-bounded local tests from
-`<plugin-root>/includes/verification-boundary.md` must be green; exhaustive repository and
-cross-platform suites are exact-head hosted-CI merge gates, not local commit prerequisites.
+## 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 apply
+`<plugin-root>/includes/verification-boundary.md`:
+
+- Run the impact-bounded local tests that directly cover the staged paths and obligations. Any failure blocks. Repository-wide and cross-platform suites belong to exact-head hosted CI before merge, not this commit gate.
+- 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: the applicable focused tests, lint/type-check, secrets scan, and specialized gates all PASS. Any failure halts the commit until fixed and re-run. This gate does not claim that exhaustive hosted CI has run; `finishing-a-development-branch` proves that separately before merge.
+
+## 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 from the selected authoritative
+  pair. For Markdown, use the existing criterion and task-verification text. For
+  HTML, use the exact criterion and task records returned by symbol-scoped
+  engine `read`; never scrape the rendered document. 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):** ADR-0008 governs three transitions riding a commit whose primary purpose is something else — a board edit inside such a commit is **expected and RETAINED** (not scope creep, MUST NOT be unstaged) only when `_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 `[ ]`). Any other `open-tasks.md` edit riding an unrelated commit does not classify as one of those transitions and still flags as scope creep — it does not belong to that commit's agreed boundary.
+
+This does not cover a commit whose own Phase 3 classification **is** the board change — e.g. a `docs` chore whose sole content is a `/ca-standup` archival sweep (open-tasks.md removals plus the matching `done-tasks.md` append). There, the boundary was already agreed at Phase 3, so those edits are in-scope by that classification directly; `classify_board_diff` is not consulted and does not need to recognize archival as a fourth transition.
+
+**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 turn exhaustive repository-wide or cross-platform CI into a local prerequisite when the shared `verification-boundary` assigns it to exact-head hosted CI.
+- 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/skills/ca-new-skill/SKILL.md

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