@arbiterforge/ca-pi 0.18.4 → 0.19.0

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

@@ -1,181 +1,111 @@
 ---
 name: writing-plans
-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.
+description: Turn the selected specification into a maintained implementation plan with clear outcomes, useful tasks, dependencies, and verification steps. Drafting uses the existing authorization and does not require artifact approval codes, reviewer receipts, or a frozen implementation script.
 disable-model-invocation: true
 ---
 
 # writing-plans
 
-## Authoritative format boundary
-
-For a new full-lane HTML spec, load `<plugin-root>/includes/artifacts.md` and
-use the installed structured-artifact engine for every spec and plan read or
-write. The resulting pair is `.codearbiter/specs/<slug>.html` and
-`.codearbiter/plans/<slug>.html`. Missing or invalid HTML capability is a STOP
-before writing and must not fall back to Markdown. An existing authoritative
-Markdown spec continues through the legacy Markdown path without conversion.
-HTML `--farm` dispatch remains blocked.
-
-
-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. 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 → 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.
-
-**If `--farm` was requested:** check that `FARM_API_KEY` is set in the environment of the Pi parent process. If absent, BLOCK immediately — cite `<plugin-root>/includes/farm.md` for setup instructions. Do not proceed; the farm dispatcher cannot run without an API key. Model selection happens later (at dispatch time in `subagent-driven-development`), so no model research is needed here.
-
-## Phase 1 — Criterion extraction · gate: BLOCK
-
-Lift every acceptance criterion from the spec and retain its stable ID (`AC-01`,
-`AC-02`, …). For HTML, obtain criterion records through typed engine reads and
-retain their typed IDs; rendered document text is not an authority source. This
-list is the coverage ledger for the whole plan — Phase 4 checks the task set
-against it.
-
-A criterion the spec leaves ambiguous is a `[CONFIRM-NN]` against
-`<project-root>/.codearbiter/open-questions.md` — surface it, do not invent the intent.
-
-**Backstop the ledger against the spec's own stated intent, mechanically, before trusting it — this
-runs even when `brainstorming` already ran the same check, because a hole that survived Phase 3
-survives Phase 4's bijection too, silently** (#566): run `"$PY" "<plugin-root>/hooks/_intentlib.py"
-uncovered-intent <spec-path> [--issue-body <scratch-file>]`, where `<spec-path>`
-is the authoritative `.html` or legacy `.md` spec selected above —
-`<scratch-file>` holds the linked issue's body when one exists (`gh issue view <N> --json body -q
-.body > <scratch-file>`, written outside the working tree), omitted when none does. A non-empty
-result names an in-scope bullet or an acceptance checkbox the criteria never cited — BLOCK and route
-back to `brainstorming` (`<plugin-root>/routines/brainstorming/SKILL.md`) to add the missing criterion or record a `[CONFIRM-NN]`; never paper over a
-missing criterion by authoring a task for it here instead. This is the LAST point before a hole gets
-laundered through Phase 4's bijection, which only checks the ledger against itself and cannot see
-past it.
-
-Then ask the half this tool cannot mechanize: **if every `AC-NN` passed and nothing else changed,
-what would still be broken?** A real answer names a criterion the ledger is missing even though
-every scope bullet and checkbox is technically cited — judgment, not mechanizable, and not satisfied
-by a rhetorical "nothing." Finding nothing broken is a reportable result, stated in one line, never a
-silent skip.
-
-Gate: every acceptance criterion in the spec captured as a numbered `AC-NN`; the `uncovered_intent`
-backstop above returns empty or every finding is resolved; and the negative question has been asked
-and answered. A partial ledger does not pass.
-
-## Phase 2 — Task decomposition · gate: BLOCK
-
-Break the work into the smallest honest units. Each **task** is ~2–5 minutes of work and carries:
-
-- **id** — `T-01`, `T-02`, … stable.
-- **path(s)** — the exact file(s) the task touches, resolved against `coding-standards.md`. "Some files" is not a path.
-- **verification** — one concrete command or observable that proves the task done (e.g., `<test cmd> -k test_token_expiry passes`, `endpoint returns 401 on missing header`). It cites a real `tech-stack.md` invocation or a directly observable behavior — never "looks right".
-- **maps-to** — the `tdd` obligation this verification corresponds to. The verification *maps to* a tdd obligation; it does NOT replace tdd's own gates. `tdd` Phase 1 still derives and Phase 4 still verifies obligations against passing tests.
-- **covers** — the `AC-NN`(s) this task advances.
-
-Split anything that won't fit ~5 minutes or touches unrelated paths. Reject the trap of one
-monolithic "implement the feature" task — that defeats the plan.
-
-Gate: every task has at least one path AND a verification AND a `maps-to`. A task missing any of the
-three blocks the plan.
-
-## Phase 3 — Order & MVP slice · gate: BLOCK
-
-Order tasks so each runs only after what it depends on. Flag every dependency explicitly
-(`T-07 depends on T-03`). A cycle is a decomposition error — return to Phase 2 and split.
-
-Group the ordered tasks so the **MVP slice** is identifiable: the minimal contiguous task set that
-satisfies the spec's core acceptance criteria and is shippable on its own. Everything past the slice
-is incremental.
-
-Gate: a complete dependency order with no cycle, and an explicitly marked MVP slice.
-
-## Phase 4 — Bijection proof & write · gate: BLOCK
-
-Cross the ledger against the task set, both directions. **This proves the plan and the ledger AGREE
-with each other — it does not prove the ledger itself is COMPLETE relative to the spec's stated
-intent.** A criterion missing from the ledger entirely was never a candidate for either check below;
-that completeness gap is caught earlier, by Phase 1's `uncovered_intent` backstop (and by
-`brainstorming` Phase 3 before that) — never re-derived here, and never implied by this phase's name
-(#566: a prior version of this gate read "coverage proof", which a bijective check does not earn).
-
-- Every `AC-NN` is covered by at least one task's `covers`. An uncovered criterion blocks — author the missing task.
-- 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`. 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 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. Before presenting either ordinary or combined review, call
-the private `_approvallib._preflight_plan_verification(client, identity)` with the current engine identity.
-It reads every task through bounded engine pages, checks each declared runner's supported
-named-outcome format, snapshots current inputs, and rejects identity drift. Resolve the complete
-reported set of command/input diagnostics before asking for approval. It does not run commands,
-discover or import tests, or require proposed test files and test names to exist. Input roots must
-already exist: choose an existing containing directory for files the plan will create. Roots and
-excluded directories are exact repository-relative paths, not basenames, globs, or paths relative
-to each root; for root `site`, use `site/node_modules`, `site/dist`, and other reviewed output paths.
-The ordinary and paired approval adapters repeat this preflight before arming their user reply.
-This admission check is not verification evidence; execution still binds actual commands and
-requires current named outcomes. 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
-`<project-root>/.codearbiter/plans/<slug>.md` — `<slug>` matching the spec —
-with the `AC-NN` ledger, the ordered task table (id · path(s) · verification ·
-maps-to · covers · depends-on · **status**, initialized `PENDING`), the marked
-MVP slice, and any out-of-scope item tagged inline `[NEEDS-TRIAGE]`.
-
-The status column is the pipeline's resume ledger: `subagent-driven-development` flips a task to
-`ACCEPTED` the moment it accepts it, so an interrupted run (crash, compaction, closed session) is
-re-entered by `/feature` at the first non-`ACCEPTED` task instead of restarted from brainstorming.
-
-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. 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.
-
-### Phase 4-farm extension (only when `--farm` was requested)
-
-When `--farm` was requested for a legacy Markdown workflow, after the bijective coverage gate passes and the `.md` plan is written,
-produce the farm artifact (`plan.json`) — **one MVP slice at a time** — per
-`<plugin-root>/routines/writing-plans/references/farm-plan.md`. Load that leaf and follow it;
-it owns the per-task failing-test + schema-valid `plan.json` procedure.
-
-Gate: all failing tests written and confirmed failing; `plan.json` written and schema-valid. Both
-artifacts exist before handing off to `subagent-driven-development` (`<plugin-root>/routines/subagent-driven-development/SKILL.md`).
-
-## Hard rules
-
-- 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.
-- MUST NOT let a task's verification stand in for a `tdd` gate — it maps to a tdd obligation, it does not replace one.
-- MUST NOT write the plan while any acceptance criterion is uncovered or any task covers nothing.
-- MUST NOT guess a verification command — cite `tech-stack.md` or STOP.
-- MUST NOT resolve an ambiguous criterion by guessing — raise a `[CONFIRM-NN]`.
-- MUST run the `uncovered_intent` backstop and ask the negative-judgment question in Phase 1, and MUST NOT treat Phase 4's bijection proof as a substitute — bijection proves the plan and the ledger agree with each other, never that the ledger is complete (#566).
-- MUST NOT emit `plan.json` in `--farm` mode without writing and confirming each failing test first.
-- MUST NOT set `meta.model` or `meta.apiBaseUrl` in `plan.json` — these belong to the dispatch step.
-- MUST NOT proceed with `--farm` if `FARM_API_KEY` is absent — cite `<plugin-root>/includes/farm.md` and BLOCK.
-- MUST, at exit, run the follow-up harvest (`<plugin-root>/includes/harvest.md`) over any `[NEEDS-TRIAGE]` out-of-scope items — batch-confirm promoting them to `open-tasks.md` (work) or `open-questions.md` (decisions) so they don't die in the plan file.
+Produce the plan for the active feature or sprint, then return it to that caller.
+Do not execute implementation from this skill. Use the user's existing direction;
+ask only about a consequential unresolved outcome, not permission to maintain the
+plan. An explicitly requested human checkpoint still belongs to the caller.
+
+## Select the source and representation
+
+Load `<plugin-root>/includes/artifacts.md` for artifact I/O. Read the selected
+specification's criterion records and retain its artifact ID and normative digest.
+For HTML, `_preflight_plan_authoring` checks that identity, structural validity,
+and the same-slug target. Create the matching plan as `draft_preview`; use
+`plan-bind` when selecting or refreshing its specification binding. Preserve human
+edits and stable references in the selected representation.
+
+Read relevant project context and the build/test commands in
+`<project-root>/.codearbiter/tech-stack.md`; use
+`<project-root>/.codearbiter/coding-standards.md` for applicable conventions.
+Missing optional orientation is not a new permission gate. Identify a genuinely
+missing requirement or command contract instead of guessing it.
+
+## Build useful tasks
+
+Start with the specification's intended outcome and criterion IDs. Check coverage
+in both directions: each required criterion has planned work, and each task serves
+the agreed outcome. Agreement between a plan and its criterion list does not
+prove that either captures every part of the user's intent. Inspect relevant
+source and ask what would still be wrong if all listed criteria passed. Record
+actual gaps; do not repeat an interview the caller has already resolved.
+
+Each task should describe a coherent unit of work: stable ID, intended result,
+relevant paths, referenced criteria, an implementation approach, dependencies,
+and the appropriate check or observable completion condition. Choose task size
+for useful implementation and review, not a compulsory two-to-five-minute limit.
+A small related change does not need its own author/reviewer lifecycle. Split
+work when it has separate outcomes, dependencies, or independently useful progress.
+
+Use real repository commands or an explicitly described observable check. A test
+file or case that this task will create may not exist yet. An unsupported named
+result parser is not a reason to reject the plan or invent test outcomes; a
+command-level result must not be claimed as proof of individual named tests.
+Read relevant command definitions without executing anything merely to author a
+plan. Runner support and actual execution are checked when that check is needed.
+
+Separate prerequisites that can be observed from choices only the user can make.
+For typed prerequisites, use `kind: fact` or `kind: decision` and explicit
+`task_refs` for affected tasks. Do not guess that an old unscoped prerequisite
+applies to every task, or narrow a real shared dependency to hide it. Observable
+facts use ordinary authorized tools and the engine's reported-observation path.
+A consequential unresolved choice gets a clear normal-language question, not an
+approval digest or a certification code.
+
+For source impact without a repository-wide dependency analysis, record
+`shared_inputs` only where the task genuinely depends on a common source
+interface, fixture, schema or unusual build configuration. These must be
+portable repository-relative paths to actual source, not generated artifact
+state; a directory path includes its bounded descendants. A known shared
+input change should refresh the affected check, not every unrelated review.
+Do not invent references or claim an exhaustive dependency graph; missing
+or unbounded inputs remain honestly `unassessed` in task context.
+
+Order tasks by their actual dependencies. Remove cycles by fixing the plan, not
+by pretending a required predecessor is complete. Group meaningful batches with
+clear outcomes; checkpoints organize implementation and do not independently
+create user approval requests. Keep genuinely blocked work visible while allowing
+independent work to proceed. Identify the smallest useful delivery outcome without
+splitting a promised atomic migration or compatibility change across releases.
+
+## Save, inspect, and maintain
+
+For HTML, use typed `create` and `apply` operations with current identity and CAS.
+Preserve the specification's criterion IDs, task references, reasons, and history.
+Drafts may be incomplete. Use `validate` with `gate: ready` to discover omissions;
+its diagnostics describe the plan, not whether an already-authorized agent may
+continue useful work. Structural errors or a conflicting write remain actual
+operation failures. Do not fill missing fields with fabricated evidence to make
+validation green.
+
+Maintain the plan under existing authorization without extra artifact approvals
+or freezing each method or check as another decision. Update in-scope steps,
+tasks, checks and valid dependencies with a reason; material outcome changes
+go to their actual decision owner.
+
+Read back the saved identity and affected symbols. Return the plan location,
+useful next work, actual unresolved choices, and outstanding checks to the active
+caller. Distinguish implemented progress from verified behavior; a plan or a
+`DONE` label is not test, review, or release evidence. Keep unrelated progress
+when correcting the plan, and do not restart brainstorming after an interruption.
+
+Existing Markdown retains one ledger and its original representation.
+Never infer a passing check from an old status or duplicate approval prompts.
+
+## Explicit farm requests only
+
+For a user-selected Markdown `--farm` workflow, use
+`<plugin-root>/includes/farm.md` and
+`<plugin-root>/routines/writing-plans/references/farm-plan.md`. Preserve the
+requested provider/budget and actual credential boundaries. Do not read
+credential contents or trigger model spending during ordinary authoring.
+HTML farm is disabled; never silently change backends.
+
+Retain real out-of-scope follow-ups using `<plugin-root>/includes/harvest.md`
+when relevant. Do not turn routine drafting into an additional audit program,
+mandatory reviewer chain, or repeated approval interview.

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

@@ -14,14 +14,14 @@ authorized it, and what is still open.* Read-only over every source; its only wr
 ## Window
 
 - `<from-ref> <to-ref>` — two tags/SHAs (e.g. `v1.2.0 v1.3.0`).
-- `--since-checkpoint` — from the `last-checkpoint` record to HEAD.
+- `--since-checkpoint` — use `source_commit` and `recorded_at` from the latest checkpoint report under `.codearbiter/checkpoints/` as the commit and UTC time anchors.
 - `--since <date>` — ISO date to HEAD.
 - No argument → from the most recent tag to HEAD (no tags → last checkpoint; neither → BLOCK and
   ask for an explicit window).
 
 ## Flow
 
-1. Resolve the window to a commit range and a time range; both appear in the packet header.
+1. Resolve the window to a commit range and a time range; both appear in the packet header. For a checkpoint window, select the report with the latest valid `recorded_at`, verify its `source_commit` resolves to a commit and is an ancestor of HEAD, and cite the report. Include its `worktree_dirty` value as a review-scope limitation. Missing or invalid anchors require an explicit ref/date window; never infer one from the report filename or the integer override counter in `last-checkpoint`.
 2. Gather, citing each source file:
    - **Commits** — `git log` over the range, grouped by Conventional-Commit type; merge commits
      listed with their PR reference.

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

@@ -24,7 +24,7 @@ Periodic sweep of the entire codebase with the reviewer fleet, funneled to a sin
 
 2. Route to `dispatching-parallel-agents` (`<plugin-root>/routines/dispatching-parallel-agents/SKILL.md`) with that unit list (read-only batch). It dedupes, then
    funnels through `finding-triage` → `verdict-aggregator` and returns the single read-only verdict.
-3. After the verdict returns, separately dispatch `checkpoint-aggregator` with that verdict. It writes the dated report to
+3. After the verdict returns, separately dispatch `checkpoint-aggregator` with that verdict and the reviewed commit from `git rev-parse HEAD`, the UTC review-start time, and whether the reviewed worktree was dirty. Retain these observed values from before the sweep. It writes the dated report to
    `<project-root>/.codearbiter/checkpoints/YYYY-MM-DD.md`: findings by severity with
    file:line, and out-of-scope items marked inline `[NEEDS-TRIAGE]`.
 4. Write the current override **count** to `<project-root>/.codearbiter/last-checkpoint` — the

package/plugins/ca-pi/skills/ca-commit/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.