@arbiterforge/ca-pi 0.18.4 → 0.20.0

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

@@ -1,209 +1,78 @@
 ---
 name: brainstorming
-description: The Socratic spec-refinement front of /feature, and the planning front of /sprint. Routed to BEFORE any code — it turns a one-line idea into a concrete spec with testable criteria, ready for initial combined sprint review or explicit sequential approval. Five gated phases — frame, shape, refine, write, review-and-approve. No implementation before an approved spec; the caller retains required planning, execution and delivery ordering. Each acceptance criterion becomes one tdd Phase 1 obligation.
+description: Refine feature and sprint intent into a useful specification. Capture scope, observable criteria and material choices without repeated artifact approval ceremonies.
 disable-model-invocation: true
 ---
 
 # brainstorming
 
-## Structured-artifact boundary
-
-For new full-lane work or an existing HTML spec/plan, load
-`<plugin-root>/includes/artifacts.md` before artifact I/O. Before Phase 1, call
-`_select_authoring_route` with the trusted project root, slug, invoking workflow,
-and selected lane; use only its returned mode, format, and paths. For a selected
-HTML route it checks the
-installed capability before writing; missing or invalid HTML capability is a
-STOP and the workflow must not fall back to Markdown. Its typed
-ID, binding, readiness, receipt, contextual-read and scope-state rules replace
-legacy Markdown parsing and direct status-cell edits for that pipeline. Keep all
-other workflow gates, including human checkpoints, unchanged. Existing `.md`
-artifacts remain on their legacy path. New full-lane specs use the installed
-structured-artifact engine and default to canonical `.html`. HTML `--farm`
-dispatch remains blocked.
-
-
-Refine the idea before it touches code. Routed to by `/feature` and `/sprint` as their specification step.
-
-## Caller scope and authority
-
-Read the active caller's workflow, selected lane, scope and existing delegation before refining.
-Initial sprint planning is not an approved sprint: this skill does not grant its own delegation.
-A full-lane feature requires `writing-plans` after spec approval. Initial HTML sprint planning instead
-returns a ready draft identity for the combined spec/plan review before either is approved; a
-subordinate specification step returns its result to the existing caller. Preserve direct handoffs when they
-satisfy that caller's ordering, not an unconditional terminal route to implementation.
-
-A sprint may contain several related features under one coherent goal. Keep their boundaries and
-criteria explicit without converting the sprint into repeated feature interviews. Parameter and
-method choices follow safety-core; material product decisions and missing authority are not inferred.
-No new registered surface, runtime state or copied procedure is needed for this call contract.
-
-## Pre-flight
-
-Read these, or STOP and surface the gap — never guess scope or stack:
-
-- `<project-root>/.codearbiter/CONTEXT.md` — the `stage:` frontmatter (the maturity value), domain vocabulary, and what the project is NOT building.
-- `<project-root>/.codearbiter/tech-stack.md` — the stack the feature must fit; rule out incompatible designs early.
-- `<project-root>/.codearbiter/open-questions.md` — existing `[CONFIRM-NN]` items; new ones number sequentially from here.
-
-**Recorded intent — fail-soft, exempt from the read-or-STOP rule above (ADR-0025).** Also
-consult, when present: the `decisions/` index (titles via `decision-log.md` or the filename
-listing — load a full ADR body only when its subject touches this feature) and
-`plans/02-phased-build-plan.md`'s section headings (plus `plans/01-architecture-breakdown.md`
-when the feature touches component boundaries or integrations). Index-first, never a bulk read.
-A missing file or directory here is NOT a gap to surface and never a STOP: record
-`intent: silent — no decomposition record` in the running notes and proceed.
-
-Scope-sized and light. NOT decompose's whole-project six-layer interview — five phases for the
-caller's feature or coherent sprint. Depth scales with that scope, not the ceremony. The deliberately
-inline small-feature lane remains owned by `/feature`; do not manufacture an HTML pair for it.
-
-## Phase 1 — Frame the problem · gate: BLOCK
-
-Take the one-line idea and pin its boundaries before designing or asking anything:
-
-- State the problem in one sentence — the concrete pain, not the proposed solution.
-- Name the user or caller who feels it, and what "done" looks like to them.
-- Name what this feature explicitly does NOT do — the boundary that keeps scope honest.
-- Check the framing against `CONTEXT.md`: it never contradicts the NOT-building list or redefines domain vocabulary. A contradiction is a conflict — surface it, do not reconcile it silently.
-- Check the framing against the recorded intent (pre-flight, when present): an idea that resurrects a capability `plans/02` records as deferred, or that duplicates a backlog item, is a fork to ask — lead with the recorded deferral rationale and your recommendation; never proceed on it silently (ADR-0025).
-- **Respect the caller's unit of work.** For a feature, split unrelated independently shippable
-  concerns before refining them; record the selected piece and its exclusions. For a sprint, retain
-  related features within the stated sprint goal and identify their separable criteria and dependencies
-  for planning. Do not force one new user interview per feature or silently absorb unrelated work.
-  Ask only when the intended scope or necessary product decision remains unresolved.
-
-Gate: problem, caller, and out-of-scope boundary stated and consistent with `CONTEXT.md`; the unit is
-the caller's selected feature or coherent sprint, with unrelated scope explicitly excluded.
-
-## Phase 2 — Shape the approach · gate: BLOCK
-
-Before drilling into details, establish WHICH design the details belong to:
-
-- Propose the genuine candidate approaches — usually two or three — each with its real trade-off stated (`X gives you A but costs B`). Recommend exactly one, with the reasoning that picks it. The user rules on material product decisions during initial feature or sprint planning; within an already-approved sprint, its existing delegated decision rules apply and the choice is logged. A recommendation made before approval does not authorize execution.
-- **Never manufacture alternatives.** When only one sane approach exists, say so and say why — a padded list of straw options is noise wearing the costume of rigor, and it trains the reader to skim the one section that matters.
-- **Check each candidate against accepted ADRs** (the pre-flight index; ADR-0025). A contradicting candidate is surfaced WITH the ADR citation, never silently dropped — and it may not be recommended except paired with a supersession fork via `/adr`. When the contradicting candidate is the only sane approach, that IS the fork: present it (the user rules under `/feature`; under `/sprint` this surfaces at the interactive Phase 1 gate, where the user is present to rule).
-- Apply the isolation lens to the recommended shape while it is still soft: can each part be understood without reading its internals, and can its internals change without breaking its consumers? A design that fails this here fails it again in review, after the code exists.
-- Apply the YAGNI lens: strike anything the Phase 1 problem statement does not demand. A capability the caller never asked for is scope creep with a head start.
-
-Gate: one approach selected under the caller's existing authority and recorded with its trade-off;
-nothing in it exceeds the stated problem. Selection during initial planning is not execution authority.
-
-## Phase 3 — Socratic refinement loop · gate: BLOCK
-
-Turn the chosen approach concrete. The discipline is decide-or-ask, never drift:
-
-- **Choose methods; ask missing decisions.** Select reversible parameters and implementation methods
-  within safety-core's decision-authority limits; multiple reasonable methods alone do not require a
-  user choice. Record material decisions in the running notes and the spec's **Decided parameters**.
-  Use the existing delegated decision rules only where the approved sprint covers the choice. A
-  missing product decision, unresolved `[CONFIRM-NN]`, scope expansion or irreversible operation is
-  not a method choice: ask the actual question with its recommendation and counter-consideration.
-- **Batch what is independent.** Forks whose answers do not depend on each other are asked together, not serialized into rounds. One round of three real questions beats three rounds of one.
-- Run every answer through three lenses:
-  - **Vague language** — make the required outcome observable: "fast", "secure" and "scalable"
-    need acceptance boundaries. Only unresolved product requirements or missing user-owned decisions
-    become `[CONFIRM-NN]`; a reversible implementation detail deliberately left to planning within
-    the agreed constraints is not an unanswered user question. Do not invent unknowns to fill a template.
-  - **Hidden complexity** — name what the user assumes is easy but is hard: state, concurrency, edge cases, failure modes, validation, idempotency, migration of existing data. Surface it now or it surfaces in `tdd`.
-  - **Trade-off forcing** — identify the actual choice and its counter-consideration. Apply the caller's existing authority: ask material user-owned decisions, or choose and log an authorized delegated method. Never hide a choice or widen delegation.
-- **The loop has a breaker.** When refinement stops converging, stop repeating the same question or
-  hypothesis. Reuse an applicable recorded ruling; within delegation, diagnose and choose a different
-  evidence-supported method. A genuine unresolved user decision or rule conflict is surfaced once
-  through its owner, never guessed or treated as permission. Do not manufacture `[CONFIRM-NN]` for
-  the agent's internal choice of method.
-- **Closure is a checklist, not a feeling.** The reasons to stop asking that do not count, each with why:
-  - *"The feature is simple enough."* — Simplicity shortens the spec; it does not waive it. The five-sentence spec still names its criteria.
-  - *"I've asked enough questions."* — Question fatigue is not an exit condition. The exit is the Phase 5 review passing.
-  - *"The user seems eager to move on."* — Eagerness is a signal to compress the asking (decide more parameters, batch harder), never to skip an unresolved fork.
-  - *"We can settle it during implementation."* — Missing acceptance requirements cannot be deferred
-    as implementation freedom. Record genuine user-owned unknowns; retain method selection within
-    the existing planning and delegated-execution contract.
-
-Record every genuinely-unresolved user-owned requirement or decision as `[CONFIRM-NN]` in `<project-root>/.codearbiter/open-questions.md`, numbered sequentially. A finding that belongs to a different feature or a future scope gets an inline `[NEEDS-TRIAGE]` marker in the notes — never route it to a ticket.
-
-**Before closing this loop, check the criteria decided so far against their own stated intent, not merely against each other** (#566: `writing-plans` Phase 4 proves BIJECTION between a plan's tasks and the `AC-NN` ledger — every criterion has a task, every task has a criterion — and that proves the two AGREE, never that the ledger itself is COMPLETE. A criterion missed by both sides passes that check cleanly; catching the miss belongs here, at the source, before Phase 4 writes anything to freeze it in place.) Assemble a scratch file outside the working tree (`mktemp`) shaped like the spec sections Phase 4 is about to write — a `## Scope` heading over the Phase 1 framing, and an `## Acceptance criteria` heading over every criterion decided in this phase's running notes so far — and, when this feature traces to a GitHub issue, its body into a second scratch file (`gh issue view <N> --json body -q .body > <scratch-file>`; omitted when there is no linked issue). Run `"$PY" "<plugin-root>/hooks/_intentlib.py" uncovered-intent <scope-and-criteria-file> [--issue-body <scratch-file>]`. A non-empty result names an in-scope bullet or an issue acceptance checkbox no criterion's text cites — add the missing criterion now, or record it as a `[CONFIRM-NN]` if it is genuinely undecided, never carry it forward uncited. This mechanical pass is the CHEAP half; it catches only an uncited bullet or checkbox.
-
-Then ask the half it cannot mechanize, explicitly, as its own step: **if every criterion decided so far passed and nothing else changed, what would still be broken?** A real answer names a criterion the ledger is still missing even though every scope bullet and checkbox is technically cited — a bullet reading "fix all three contaminated skills" against criteria for two of the three passes the citation check above cleanly, and only this question catches it. Finding nothing broken is a reportable result, stated in one line, never a silent skip.
-
-Gate: every vague term made concrete; every material choice resolved under the caller's authority or recorded as a genuine `[CONFIRM-NN]`; every parameter decision recorded in the running notes that seed Phase 4's **Decided parameters** section; no unresolved user-owned acceptance requirement outside a `[CONFIRM-NN]`; the `uncovered_intent` backstop returns empty or every finding is resolved; and the negative question above has been asked and answered, not merely named. A blocking `[CONFIRM-NN]` that gates the spec's core stops the loop — surface it and STOP.
-
-## Phase 4 — Write the spec · gate: BLOCK
-
-Create or revise the agreed spec at the route-selected spec path, in its selected format.
-New full-lane work uses `<project-root>/.codearbiter/specs/<slug>.html` through the installed
-structured-artifact engine; do not write HTML or its embedded model directly. An existing `.md`
-spec stays on its exact legacy path; never create a counterpart or implicitly convert it.
-The spec holds:
-
-- **Problem** — the Phase 1 framing in final form.
-- **Approach** — the Phase 2 choice and the trade-off that picked it, in two or three sentences.
-- **Scope** — what is in, and the explicit out-of-scope boundary.
-- **Decided parameters** — the parameter-level choices made in Phase 3, each in one line, so the approval reads them instead of discovering them in code review.
-- **Acceptance criteria** — a numbered list, each criterion concrete and testable: a specific input, the observable output, the boundary or failure behavior. Each criterion is verifiable by one or more focused tests. "It works well" is not a criterion. These become `tdd` Phase 1 obligations — one obligation per criterion, so an untestable criterion is a defect to fix here, not in `tdd`.
-- **Open questions** — every `[CONFIRM-NN]` raised, cross-referenced to `open-questions.md`.
-- **Governs** *(optional)* — a spec-header line `**Governs:** <comma-separated globs>` that enrolls the approved spec in file-scoped just-in-time context injection: on a Read of any file matching one of the listed globs, a pointer to this spec is surfaced to the agent (tier 3 of the file→knowledge map). Adding the line is sufficient to enroll; no other change required.
-
-Gate: the spec file exists on disk under `specs/`, with at least one acceptance criterion and every criterion individually testable.
-
-## Phase 5 — Review, approval & handoff · gate: STOP
-
-The spec earns its approval; it is not waved through. Two passes over the FILE as written, then the stop:
-
-1. **Mechanical self-review** — one pass, correct through the selected format's owning writer, no re-review: no placeholder text (`TBD`, `???`, an unfilled section); no criterion that contradicts the scope; nothing that crosses the `CONTEXT.md` NOT-building boundary; no criterion that contradicts an accepted ADR or `plans/01`'s recorded component boundaries (ADR-0025); every criterion still testable by one or more focused tests after the edits; the vague-language lens applied to the spec's own prose.
-2. **Adversarial pass** — build the strongest case AGAINST the design before the user reads it: the failure mode most likely to be real, the criterion most likely to be wrong, the assumption that would invalidate the approach if false. Present what survives WITH the spec at approval — the user rules on a challenged design, not a defended one. Finding nothing is a reportable result, stated in one line, not a silent skip.
-3. **Approval:**
-   - **Under `/feature`** — present the spec and the adversarial findings, and request explicit user approval. Iterate on the file in place until the user approves. A blocking `[CONFIRM-NN]` must be resolved by the user before approval — never auto-resolve it.
-   - **Initial `/sprint` planning** — prepare the ready draft spec and adversarial findings for
-     explicit user approval with its complete draft plan at the caller's one initial review gate.
-     For HTML, return the current draft identity to `writing-plans` in `draft_for_pair` mode;
-     the combined `arm-sprint` / `sprint-approve` path in `<plugin-root>/includes/artifacts.md`
-     observes the exact returned reply and binds/approves both documents atomically. Do not separately approve
-     the spec, synthesize a SMARTS receipt, or execute draft tasks. Do not reinterpret one generic reply
-     as approval of either artifact or delegation. Autonomy begins only after the
-     caller's spec AND plan approval requirement is met. A legacy Markdown caller retains its
-     recorded approval mechanism; there is no implicit conversion.
-
-   - **Within an already-approved sprint** — use its existing delegation only for an in-scope choice.
-     For HTML, a supported policy-owned adapter must supply the actual event and engine receipt;
-     follow `<plugin-root>/includes/artifacts.md`. A SMARTS score or log entry is not an approval receipt.
-     The private `smarts-apply` producer covers only existing plan-method steps under an explicit
-     paired user grant; it cannot approve a specification amendment or widen its protected scope.
-     Use only a qualified production producer for the requested authority and host; do not invent a capture event
-     or reuse inspection-only evidence. A missing producer is not delegation: retain the pending state and use
-     only the existing supported authority path. The native engine's presence does not qualify a host adapter.
-     Blocking `[CONFIRM-NN]` decisions are never auto-approved in either phase.
-
-**Continuation follows the caller.** For a full-lane feature or sprint with approved spec authority,
-return the approved spec identity and review outcome to its planning step; for initial HTML sprint
-review, return the ready draft identity without execution authority. Either may forward directly to
-`writing-plans` (`<plugin-root>/routines/writing-plans/SKILL.md`) when that is the caller's declared
-next step. Do not skip required plan creation, binding or approval by jumping to `tdd`. A subordinate
-invocation returns to the named checkpoint in its caller instead of launching another full workflow.
-The inline small feature route belongs to `/feature` and can reach `tdd` without invoking this full-lane
-specification procedure. Neither path grants commit, PR, merge or publication authority.
-
-Gate: both review passes completed against the authoritative file, adversarial findings presented,
-and no unresolved blocking `[CONFIRM-NN]`. Require actual approval verified before execution.
-Only initial combined HTML review may return a ready unapproved draft to its constrained planner.
-The next operation obeys the active caller's sequence and authority.
-
-## Hard rules
-
-- MUST NOT write implementation code or route to `tdd` before the spec is on disk under `specs/` AND approved.
-- MUST preserve the caller's feature or coherent sprint boundary; unrelated scope is split or excluded, not silently absorbed.
-- MUST NOT manufacture alternatives in Phase 2 — when one sane approach exists, say so and why.
-- MUST NOT write an acceptance criterion that cannot be verified by one or more focused tests.
-- MUST record material parameter choices; ask genuine missing user decisions in full, not internal method-selection questions already covered by delegation.
-- MUST stop a non-converging refinement strategy; reuse recorded rulings or authorized diagnosis rather than repeat an answered question. Genuine conflicts still route to their owner.
-- MUST run the `uncovered_intent` mechanical backstop and ask the negative-judgment question ("if every criterion passed and nothing else changed, what would still be broken?") before closing Phase 3 — bijective coverage in `writing-plans` proves the plan and the ledger agree with each other, never that the ledger is complete (#566).
-- MUST run the Phase 5 mechanical self-review and adversarial pass against the file as written, and present the adversarial findings at approval.
-- MUST NOT resolve a `[CONFIRM-NN]` by guessing — surface it and record it in `open-questions.md`.
-- MUST NOT auto-approve a spec carrying a blocking `[CONFIRM-NN]`, even under `/sprint` — it escalates to the user.
-- MUST NOT contradict the NOT-building list or redefine domain vocabulary in `CONTEXT.md` — a contradiction is a conflict to surface, not reconcile.
-- MUST NOT run decompose's six-layer whole-project interview or force a coherent sprint through repeated one-feature interviews.
-- MUST NOT use SMARTS to approve the initial sprint; record delegated decisions in the existing audit trail and verify actual authority for the selected artifact format.
-- MUST, at exit, run the follow-up harvest (`<plugin-root>/includes/harvest.md`) in the active caller's mode:
-  batch-confirm interactive work; use autonomous promotion only under existing delegation. A blocking
-  decision is never promoted into authority or silently demoted to a follow-up.
+Refine the agreed outcome before implementation. This is intent clarification and specification authoring, not a second permission system. The feature or sprint request is the initial authorization; ask about consequential choices not already answered, not whether an artifact may exist.
+
+## Format and caller
+
+For artifact I/O, load `<plugin-root>/includes/artifacts.md` and select the source with `_select_authoring_route`. Retain that source identity through specification authoring.
+
+The calling feature or sprint owns scope and the next step. A sprint may include several related features under one coherent goal. A small inline feature remains the caller's mini-spec lane. Specification authoring itself does not grant commit, publication, override, provider spending, or irreversible-operation authority.
+
+Use relevant CONTEXT.md, tech-stack.md and security-controls.md when present. Read an existing open-questions document and relevant ADR/plan headings index-first. Missing optional historical indices are not blockers. Preserve real decisions while distinguishing an accepted decision from implemented or released behavior.
+
+## Recorded intent and consequential conflicts
+
+Use an index-first recorded-intent read to avoid asking about settled choices.
+This pre-flight is exempt from the read-or-STOP rule when optional project
+history is absent: **intent: silent — no decomposition record**. Do not
+manufacture a plan or an approval to fill that gap.
+
+If a proposed solution resurrects a capability `plans/02` records as deferred,
+identify the original reason and any stated re-evaluation trigger, then fork to ask
+only when the *outcome* would materially change. An explicit current owner steer
+can settle that fork; an ordinary implementation detail cannot silently reverse
+a recorded deferral.
+
+A candidate that contradicts an accepted ADR must be **surfaced WITH the ADR
+citation, never silently dropped**. A recommended outcome change is paired with
+a supersession fork via `/adr` instead of pretending the old decision never
+existed. If the contradiction is the only sane approach, that IS the fork:
+show the choice and consequence to the owner once, respecting an already
+recorded superseding instruction. A referenced ADR is not a new permission
+token for safe, in-scope investigation or implementation.
+
+## Phase 1 - Frame
+
+State the problem, observable result, intended scope and explicit exclusions. Respect what the user already requested. If a record conflicts with new intent, identify the material decision and which work it affects; do not automatically create another approval round for ordinary method choices.
+
+## Phase 2 - Select a viable approach
+
+Consider genuine trade-offs where they matter, recommend a suitable approach and explain why. Do not manufacture straw alternatives. Reversible implementation methods remain agent-owned within the agreed outcome. Ask for a user ruling on an unresolved, consequential product choice, not on every viable implementation detail.
+
+**Never manufacture alternatives.** When only one sane approach exists, say so in one line and say why; that path runs no SMARTS comparison and adds no SMARTS table.
+
+**SMARTS on a material choice.** Only when two or more materially plausible approaches exist, run a SMARTS comparison per `<plugin-root>/includes/smarts/core.md` inline before recommending one. Bound it to the context-envelope dimensions that could differentiate the approaches, mark missing evidence `Unknown` with its missing observation, and surface a decision-critical `Unknown` before selecting. If every candidate carries one, pause the selection until the missing observation is resolved or the user rules. The comparison dispatches no grader or scout, performs no bulk read of `plans/` or `decisions/`, and loads `<plugin-root>/includes/smarts/lenses.md` only when a verdict turns on a consideration the core summaries do not settle. Name cost, schedule, team-skill, vendor or stakeholder constraints alongside the result; they never become a seventh lens. Apply the core's priority order when lenses conflict; a tie without explicit priority evidence goes to the user. An explicit request for a full SMARTS read changes only the presentation depth — the full option-by-option table — with no new command and no change to decision authority.
+
+**Record the rationale.** When the comparison ran, write the decisive lenses, any `Unknown` with its missing observation, the non-SMARTS constraints and the selection reason into the spec's `SEC-SMARTS` section, or the `## SMARTS design rationale` section of a Markdown spec. A single-approach choice records only its one-line statement there.
+
+Review applicable ADRs and explicit exclusions. A real conflicting architecture decision goes to its owner. Mentioning a protected file does not by itself restart the entire feature interview.
+
+## Phase 3 - Make acceptance observable
+
+Turn intended scope into specific criteria: input or trigger, expected behavior, and relevant failure/boundary condition. Check integration risks and ask: **if every criterion passed, what would still be broken?** For meaningful behavior changes, plan one or more focused tests against the actual obligation; do not create tests solely to clear an artifact gate. For complex or issue-backed work, a bounded `_intentlib.py uncovered-intent` inspection can catch uncited requirements. It is not a mandatory permission gate for every small change.
+
+Choose sensible defaults and record material parameters. Do not create CONFIRM placeholders for normal method choices. A consequential unresolved requirement warrants one clear user question; independent work may proceed if that decision affects only part of the plan. Do not repeatedly ask the same question merely because an artifact was revised.
+
+## Phase 4 - Write the spec
+
+Create or update the route-selected spec with: problem, chosen approach and rationale, included/excluded scope, meaningful parameters, observable acceptance criteria, and actual open decisions. For HTML use typed `create` and `apply`, stable criterion IDs, current CAS, and symbol-scoped readback; never edit embedded HTML/JSON directly. Existing Markdown remains on the legacy path without automatic conversion. Do not invent a command, test, source, approval or result.
+
+Drafts may be incomplete. `validate` with `gate: ready` identifies missing coverage and structure. Diagnostics help complete the plan; they are not a reason to prohibit independent authorized investigation. A conflicting write or structural failure still prevents claiming the artifact was saved. A ready spec is not proof of implementation.
+
+## Phase 5 - Self-review and handoff
+
+Read back the saved specification. Check consistency, alignment with the user's request, exclusions, and ability to verify: no criterion that contradicts an accepted ADR without an explicitly resolved, source-visible owner decision. Identify a plausible failure mode or say none was found. Proportion the review to risk rather than mandating an adversarial committee.
+
+For full-lane feature or sprint work, return the selected spec identity, normative digest, criteria, and genuinely open decisions directly to `writing-plans` (`<plugin-root>/routines/writing-plans/SKILL.md`). The caller maintains its ordering; do not skip a useful plan to reach implementation. An existing spec should resume at its actual unfinished step, not restart an interview.
+
+**Do not demand separate spec approval or `arm-sprint`/`sprint-approve` merely to progress.** An explicitly requested human review pause and real user-owned decisions still apply. Historical paired approval, producer capture or SMARTS grant remains historical; do not fabricate a receipt. In-scope method updates during work are typed plan maintenance, not another permission interview.
+
+## Hard boundaries
+
+Never broaden the requested outcome, ignore a genuine host denial or user stop, manufacture verification evidence, silently change representation, or claim a saved/verified state without observing it. Preserve source integrity and independently applicable security controls. Avoid interviews for already-answered or agent-owned choices.

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

@@ -20,23 +20,22 @@ 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.
 - `<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.
-
-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.
+- Read the scoped obligations and observed evidence under `<plugin-root>/routines/tdd/SKILL.md`. Confirmed fixes require regression RED/GREEN; features require current criterion-focused checks; refactors require passing characterization/parity evidence. Apply the relevant coverage and lint requirements. Resolve missing evidence for the staged change using its selected verification approach.
+- The discovered authoritative spec/plan pair, when relevant to this commit. For HTML,
+  load `<plugin-root>/includes/artifacts.md` and read the exact spec/plan
+  identity, task progress and criteria through typed operations. `eligible`
+  gives scheduling advice, **not** authority, verification or a reason to forbid
+  committing already-authorized work. `REVIEW` and `DONE` describe work
+  progress, not independent checks.
+
+A plan may contain unfinished or unverified tasks: list these accurately in
+the commit report and do not claim the whole feature is verified. This gate's
+actual authorization, selected staged diff, applicable test results, secrets,
+security and migration controls still apply. Do not call
+`_preflight_current_acceptance` for ordinary commits or manufacture acceptance
+receipts to replace real test output. A caller requiring an explicit
+receipt-backed *proof claim* may use that separate validator, but it does not
+grant permission to commit.
 
 ## Phase 1 — Permission · gate: BLOCK
 
@@ -75,20 +74,24 @@ Gate: the staged set is type-homogeneous with a single type and scope.
 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.
+- Establish impact-bounded local test results that directly cover the staged paths and obligations. Reuse inspected results while their relevant source, inputs and command match; run missing or affected checks. Any unresolved failure blocks. Repository-wide and cross-platform suites belong to exact-head hosted CI before merge.
+- Establish current lint results, and type-check results if the project is statically typed. Reuse applicable observed results under the same source/input rule. 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.
+Required specialized review may reuse an existing review of the same source,
+requirements, findings and verification inputs. Dispatch only missing or affected
+review work. Required security and migration markers must still cover the actual
+staged content; a prior review does not waive their writers or hook checks.
+Record each result (PASS / BLOCK), its source and whether it was reused or run.
 
 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
+Apply the current-evidence rules 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.
 
@@ -97,15 +100,47 @@ self-report.
   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.
+- Inspect the applicable output and exit code and confirm the observed behavior matches the spec's acceptance criteria. Reuse the Phase 4 or implementation result when it already proves that criterion on unchanged relevant inputs. Run a separate proving command only when existing evidence is missing, affected or insufficient. A mismatch or 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.
+Gate: inspected current command output and exit code prove the claimed behavior. The phase change alone does not require another run. 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).
+Partition the loaded records by schema. Select only recorded content paths or
+membership scopes/predicates intersecting staged sources. Commits touching no
+recorded source do no re-scout work. An empty legacy worklist says nothing about v2.
+Include deleted paths and both sides of renames in `staged_paths`, for example
+with `git diff --cached --name-only --no-renames`.
+
+**Managed v2 pairs:** acquire one bounded snapshot covering the selected documents'
+recorded dependencies and target preimages. Call `assess_context_provenance` for
+those document IDs with its action-boundary snapshot probe, then reuse that
+snapshot and assessment in
+`_provenancelib.v2_heal_worklist(staged_paths, provenance, snapshot, assessment)`.
+Its `claims` identify the affected document, field, claim and staged source paths;
+they select inspection work, not permission to write. These paths are staged triggers;
+inspect the selected claims' complete recorded evidence before refreshing their fields,
+including any changed unstaged dependency. Preserve uninspected claims and bindings.
+Report `unknown` entries and defer that document's automatic
+update; do not label it fresh or block independent commit work.
+
+When inspected claims still hold, prepare an `update` of the selected owned fields
+with unchanged content and current source evidence. When a claim changed, propose
+the bounded content correction for Phase 6 review. Use the typed `context-preview`
+and `context-apply` procedure in
+`<plugin-root>/routines/context-check/SKILL.md`, retaining exact expected pair hashes,
+the returned preview reference/digest and all unselected bytes. Reuse the existing
+maintenance authorization; do not enter a second approval cycle. Native apply
+rechecks the source and pair identities and writes both files together. Read back
+the result. Never pass v2 records to `rebaseline` or write them directly. Stage the
+resulting pair by explicit paths and secrets-scan every newly staged file.
+
+**Legacy v1 records:** compute the heal worklist via
+`_provenancelib.heal_worklist(staged_paths, provenance, current_hashes)` — staged
+`drift_trigger:true` entries whose hash diverged or is absent. An empty v1 worklist
+skips only this legacy branch.
 
 Non-empty worklist → call `_provenancelib.compute_drift(provenance, current_hashes)` to retain the document/source mapping. For each stale document in that drift report, get its record as `doc_provenance` and call `_provenancelib.changed_scope(doc_provenance, drift)`. Intersect that document's drifted paths with the worklist; skip a document when the intersection is empty. The hash map can omit unstaged paths, so a missing entry outside the worklist must not broaden this commit's re-scout. Confirm that every selected worklist path maps to at least one stale document after this filtering; if a record is malformed or the mapping is incomplete, STOP and report the gap rather than treating the path as fresh.
 
@@ -217,7 +252,7 @@ Gate: the commit lands and `git status` is clean. Unexpected uncommitted changes
 - 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 prove the behavior against the spec with inspected current evidence (Phase 5); a self-reported "it works" is insufficient.
 - 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.