@arbiterforge/ca-pi 0.18.4 → 0.19.0

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.

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

@@ -1,20 +1,19 @@
 ---
 name: context-check
-description: "Audit stale provenance-tracked docs on request. Report first; re-scout or re-baseline only for selected docs."
+description: "Inspect context drift and refresh selected source-backed documents under existing authorization."
 argument-hint: "(none)"
 ---
 
 # context-check
 
-An optional, on-demand drift audit for bypass cases: a merge or an external
-edit drifted a tracked source file you are not about to commit, so commit-gate's
-Phase 5.5 auto-heal did not fire. This skill reports stale docs and lets you
-act on each one individually.
+Inspect context drift or refresh selected source-backed documents. This includes
+drift from a merge or external edit that commit-gate's Phase 5.5 auto-heal did
+not cover, and an explicitly requested full refresh of initialized context.
 
 This skill is NOT in the daily loop. Commit-gate auto-heal (Phase 5.5,
-`heal_worklist`) owns the routine maintenance path. Invoke this only when drift
-was introduced outside a commit (e.g. a direct push, a merge you did not
-author, a manual file edit).
+`heal_worklist` for v1 and `v2_heal_worklist` for managed pairs) owns routine
+maintenance. Reuse existing selection and
+authorization for requested refresh; an audit-only request remains read-only.
 
 <!-- catalog-compatibility-notice:start -->
 > Compatibility route. Prefer `/ca-status drift` for new explicit usage. The retained entry
@@ -27,9 +26,11 @@ author, a manual file edit).
 Use this owner for a requested provenance drift audit, `/ca-status drift`, or
 the explicit `/ca-context-check` compatibility entry. Explanation-only questions
 and ordinary status snapshots remain read-only answers, not repair requests.
-Report first. Write only after the user selects re-scout or re-baseline for that
-document; never change an unselected derived document. This owner neither stages
-nor commits. Routine commit-gate auto-heal is unchanged.
+Report first for an audit-only request. A direct request to refresh selected
+documents or the full project context supplies that selection; reuse the
+existing authorization instead of asking again per document. Never change an
+unselected derived document. This owner neither stages nor commits. Routine
+commit-gate auto-heal is unchanged.
 
 An **initialized refresh** belongs to this existing owner after an explicit
 selection. It is separate from initial population: do not call the initialized
@@ -73,7 +74,7 @@ is unknown coverage, even when a neighboring v1 or v2 record is usable. Report
 the usable records and the unknowns separately; never turn an empty legacy
 drift report into a fresh verdict for v2. `v2_current` acknowledges matching
 identities only. `semantic: unverified` and `verified_fresh: false` remain in
-force until the owning semantic review and writer receipt establish otherwise;
+force: only actual evidence can support a narrower semantic claim;
 changing hashes or choosing re-baseline does not perform that review.
 
 Only if the relevant legacy drift report is empty and v2 coverage/identities
@@ -103,8 +104,7 @@ stale path. Do not offer an automatic write for an unbounded scope.
 ### Unsupported human content and owner reconciliation
 
 An unsupported human Markdown layout, ambiguous duplicate anchor, unparseable
-custom section, oversized document or absent managed ownership record is a
-write refusal for that document, not a reason to erase it or abandon safe
+custom section or oversized document is a write refusal for that document, not a reason to erase it or abandon safe
 task-time reading. An unrelated unknown section in an otherwise supported
 document remains unowned and byte-identical during a supported field update.
 Preserve exact bytes and report the specific unsupported or unowned span.
@@ -116,36 +116,38 @@ project. Surface a real conflict without silently displacing either source.
 
 If the requested change would adopt or replace normative instructions, route
 the proposal to its actual owner and obtain that owner's actual approval before
-any supported bounded update. An unsupported template needs explicit
-reconciliation or a qualified per-kind transition through the existing context
-writer. Its refusal never authorizes raw Write/Edit fallback or a regex rewrite.
+any supported bounded update. Missing or legacy v1 provenance may use explicit native `adopt` with current
+evidence and selected supported spans, preserving the old provenance preimage.
+An unsupported template still needs reconciliation through its actual owner or
+a supported writer transition. Its refusal never authorizes raw Write/Edit fallback or a regex rewrite.
 Task, question, audit, release and ADR files remain with their existing writers;
 do not normalize, recreate or edit their history during context refresh.
 
 ### Step 3 — Selected initialized refresh
 
-For each stale or bounded affected document, present supported re-scout,
-re-baseline and defer choices; wait for the user's selection. A user may instead
-explicitly select full refresh. Do not interpret
-`status drift`, the drift report itself or an ordinary status request as that
-selection. Record the selected documents and declared affected source paths
-before any scout or write. An incremental refresh re-scouts only the selected
-drifted paths and affected logical assignments. A full refresh declares all six
-logical assignments and all five content documents. Retain prior coverage as
-prior evidence; a scoped `join_scout_reports` result has `full_coverage: false`
-and must never be described as a newly completed full scan.
-
-**re-scout** — dispatch an incremental re-scout of the drifted paths for this
-doc, scoped to those paths only. Use the context-creation containment profile,
-run budget, `admit_scout_attempt` and `join_scout_reports` contract for exactly
-the declared affected assignments. A missing/failed report, changed snapshot,
-contradiction or unresolved task-dependent decision blocks the selected write.
-If the claims still hold, a valid selected owned-field metadata refresh may
-keep document bytes identical only when proposed v2 provenance actually
-changes. Missing selection and unchanged proposed provenance refuse; retain
-the stale pair and do not claim freshness in those cases. Any update still
-requires current source evidence, exact preview approval and receipt-only
-apply. Surface the proposed content and provenance pair for exact review.
+Use the user's selected documents and affected scope. If only an audit was
+requested, offer reinspection, re-baseline and defer choices before writing.
+A request for full refresh already selects all five content documents and all
+six logical categories; do not repeat that question. Record the selection and
+source paths, then inspect only what those claims need. Keep the initialized
+marker and prior history. Full inspection accounts for all six categories;
+incremental inspection does not claim a new full scan.
+
+**re-scout / reinspect** — use direct bounded inspection or optional scoped
+agents for the selected claims. The context-creation evidence and gap rules
+apply. When structured reports help, `join_scout_reports` tracks their declared
+coverage; a scoped result has `full_coverage: false`. The helper is not a
+permission or containment check. A missing report can be replaced by direct
+inspection, but failed or uninspected work never becomes evidence of absence.
+Recheck changed source snapshots and resolve contradictions before their
+claims are written. Unrelated gaps do not hold independent selected work.
+
+If claims still hold, a selected owned-field metadata refresh may keep document
+bytes identical when current evidence changes the v2 provenance. Missing
+selection and unchanged proposed provenance refuse rather than claim a refresh.
+Surface the proposed content and provenance pair, inspect its source bindings,
+and apply within the selected authorization. Review consequential or disputed
+claims independently when useful; a matching digest does not verify semantics.
 
 **re-baseline** — the legacy v1 provenance choice may acknowledge a verified
 cosmetic change through its existing owner, where applicable. For an enrolled
@@ -155,22 +157,56 @@ If no field is selected or the proposed pair is a true no-op, retain the stale
 pair and defer that selection. Never directly write the v2 provenance or use
 the legacy `rebaseline` helper as a fallback for it.
 
-**full refresh** — only after explicit selection, use the same qualified
-containment and bounded join with `mode: full` and six complete logical reports.
-Synthesize all five content documents from the new evidence and reconcile gaps
-under the context-creation Phase 3–4 rules. Do not enter its Phase 6 lock.
+**full refresh** — use bounded inspection across all six categories and
+synthesize all five content documents from current evidence. Preserve unknowns
+and reconcile material user decisions under context-creation Phase 3–4. Do not
+enter its Phase 6 lock for an already initialized repository.
 
-For each selected document, submit its finite typed `update` preview through
+For a selected whole-document refresh, prepare a UTF-8 draft inside the workspace
+that retains user-owned content outside the requested change. The installed CLI
+collects bounded source hashes and chooses create/adopt/update from the current
+pair. Substitute the actual inspected repository-relative source paths; repeat
+`--source` for each supporting file. For example:
+
+```text
+python "<plugin-root>/hooks/init-codearbiter.py" --root "<project-root>" --context-draft "context-code-map-draft.md" --document code-map --source "src/main.py"
+```
+
+This retains an internal preview but does not change the content document or
+provenance. Inspect the returned diff, then apply the exact returned reference
+and digest:
+
+```text
+python "<plugin-root>/hooks/init-codearbiter.py" --root "<project-root>" --context-apply "<preview_ref>" --preview-sha256 "<preview_sha256>"
+```
+
+The source list must support the draft; it is not an automatic semantic review.
+The convenience path records `semantic_review: unreviewed`. Use typed field
+previews below when only specific managed fields are selected.
+
+For each selected document, send the typed preview through
 `python "<plugin-root>/hooks/init-codearbiter.py" --root <exact-root> --context-request <request-file>`.
-The installed qualified context writer checks the existing document/provenance
-pair, current source evidence, field ownership and protected target set. Review
-the exact proposed pair and obtain its own native `approve-context` reply; apply
-only its receipt through the same `--context-request` bridge. Read back the
-committed pair and confirm the standalone `<!--INITIALIZED-->` marker remains
-for `CONTEXT.md`. The writer's five content targets exclude task, question and
-audit history. Never edit those owners as a side effect, hand-write a provenance
-record, bypass a refusal, stage or commit here. If the installed writer or
-qualified scout profile is unavailable, report that boundary and retain state.
+The request uses `operation: preview` and a `preview` object. Native
+`context-preview` supports `create` for a genuinely absent document, explicit
+`adopt` for supported missing/v1 provenance, and `update` for a managed v2 pair.
+Supply the exact expected document/provenance hashes, selected fields, typed
+content and source evidence. Keep request files inside the workspace.
+
+Inspect the returned diff and preserved content. Apply with `operation: apply`,
+`preview_ref` and `preview_sha256` through the same bridge;
+native `context-apply` rechecks the preview and current identities under its
+lock and writes the selected document/provenance pair together. No approval
+receipt, actor ticket or qualified scout profile is a prerequisite for ordinary
+already-authorized refresh. This is compare-and-swap protection, not a second
+permission system. A stale preview requires reinspection, never an overwrite.
+After a lost response, inspect the transaction and retry its identical request
+and operation ID or use native recovery; do not start a duplicate write.
+
+Read back the committed pair and confirm `<!--INITIALIZED-->` remains for
+`CONTEXT.md`. Keep unowned spans byte-identical and retain legacy provenance
+history. Task, question, audit, release and ADR history stay with their actual
+writers. Never hand-write a provenance record or bypass a refused unsupported
+shape. A missing safe writer stops that write, not authorized task-time reads.
 
 **defer** — do nothing for this doc now. The drift line will reappear at the
 next SessionStart. Use when the change is in-progress and the doc update should