@arbiterforge/ca-pi 0.15.12 → 0.16.0

package/plugins/ca-pi/routines/debug/references/handoff.md

@@ -0,0 +1,155 @@
+# Debug handoff field reference
+
+Generated from the finite `_debughandofflib.MODEL` definitions.
+The JSON Schema projects shape and scalar profiles. Cross-record SEM
+rules, strict byte decoding, causal truth, freshness, and authority remain
+separate obligations of the validator and its consumers.
+
+Protocol: `codearbiter.debug-handoff/1.0.0`.
+
+## blocker
+
+| Field | Profile |
+|---|---|
+| `blocker.kind` | `enum(access, evidence, authority, capability, safety, scope, budget, input)` |
+| `blocker.missing` | `text(1500)` |
+| `blocker.owner` | `nullable(text(300))` |
+| `blocker.resume_condition` | `text(1500)` |
+
+## check
+
+| Field | Profile |
+|---|---|
+| `check.authorization_basis` | `nullable(text(1000))` |
+| `check.cwd` | `nullable(text(512))` |
+| `check.evidence_ids` | `refs(evidence_id, 0..32, unique)` |
+| `check.exit_code` | `nullable(integer)` |
+| `check.expectation` | `text(1500)` |
+| `check.id` | `check_id` |
+| `check.observed` | `nullable(text(1500))` |
+| `check.operation` | `text(2000)` |
+| `check.side_effects` | `text(1500)` |
+| `check.status` | `enum(planned, completed, not_run, interrupted)` |
+
+## disposition
+
+| Field | Profile |
+|---|---|
+| `disposition.blockers` | `array(object(blocker), 0..8)` |
+| `disposition.cause_ids` | `refs(hypothesis_id, 0..16, unique)` |
+| `disposition.evidence_ids` | `refs(evidence_id, 0..32, unique)` |
+| `disposition.kind` | `enum(confirmed_code_defect, confirmed_noncode_cause, design_question, no_action, unresolved)` |
+| `disposition.rationale` | `text(2000)` |
+
+## evidence
+
+| Field | Profile |
+|---|---|
+| `evidence.check_id` | `nullable(check_id)` |
+| `evidence.coverage` | `enum(complete_for_claim, partial, unknown)` |
+| `evidence.id` | `evidence_id` |
+| `evidence.kind` | `enum(source, observation, user_report, command_result, contract)` |
+| `evidence.limitations` | `nullable(text(1500))` |
+| `evidence.locator` | `text(1000)` |
+| `evidence.observation` | `text(2000)` |
+| `evidence.observed_at` | `nullable(timestamp)` |
+| `evidence.snapshot_id` | `nullable(snapshot_id)` |
+
+## hypothesis
+
+| Field | Profile |
+|---|---|
+| `hypothesis.discriminator` | `text(1500)` |
+| `hypothesis.id` | `hypothesis_id` |
+| `hypothesis.limitations` | `nullable(text(1500))` |
+| `hypothesis.mechanism` | `text(2000)` |
+| `hypothesis.opposing_evidence_ids` | `refs(evidence_id, 0..32, unique)` |
+| `hypothesis.status` | `enum(supported, refuted, inconclusive)` |
+| `hypothesis.supporting_evidence_ids` | `refs(evidence_id, 0..32, unique)` |
+
+## next_step
+
+| Field | Profile |
+|---|---|
+| `next_step.action` | `nullable(text(1500))` |
+| `next_step.completion_evidence` | `nullable(text(1500))` |
+| `next_step.owner` | `nullable(text(300))` |
+| `next_step.target` | `enum(none, fix, adr, existing_owner, evidence)` |
+
+## packet
+
+| Field | Profile |
+|---|---|
+| `packet.case_id` | `case_id` |
+| `packet.checks` | `array(object(check), 0..24)` |
+| `packet.disposition` | `object(disposition)` |
+| `packet.evidence` | `array(object(evidence), 1..32)` |
+| `packet.hypotheses` | `array(object(hypothesis), 0..16)` |
+| `packet.next_step` | `object(next_step)` |
+| `packet.protocol` | `const(codearbiter.debug-handoff/1.0.0)` |
+| `packet.regression` | `nullable(object(regression))` |
+| `packet.reproduction` | `object(reproduction)` |
+| `packet.request` | `object(request)` |
+| `packet.snapshots` | `array(object(snapshot), 0..4)` |
+| `packet.symptom` | `object(symptom)` |
+
+## recipe
+
+| Field | Profile |
+|---|---|
+| `recipe.cwd` | `text(512)` |
+| `recipe.failure_signature` | `text(1000)` |
+| `recipe.preconditions` | `text(1000)` |
+| `recipe.steps` | `array(text(500), 1..8)` |
+
+## regression
+
+| Field | Profile |
+|---|---|
+| `regression.basis` | `enum(reproduction, causal_trace)` |
+| `regression.candidate_test_id` | `nullable(text(500))` |
+| `regression.evidence_ids` | `refs(evidence_id, 0..32, unique)` |
+| `regression.obligation` | `text(2000)` |
+| `regression.oracle` | `text(1500)` |
+| `regression.reuse_existing` | `boolean` |
+| `regression.snapshot_id` | `snapshot_id` |
+
+## reproduction
+
+| Field | Profile |
+|---|---|
+| `reproduction.evidence_ids` | `refs(evidence_id, 0..32, unique)` |
+| `reproduction.limitations` | `nullable(text(1500))` |
+| `reproduction.recipe` | `nullable(object(recipe))` |
+| `reproduction.status` | `enum(reproduced, intermittent, not_yet_reproduced, unsafe_to_replay, unavailable)` |
+
+## request
+
+| Field | Profile |
+|---|---|
+| `request.intent` | `enum(diagnosis_only, repair_requested)` |
+| `request.request_ref` | `text(512)` |
+| `request.restrictions` | `array(text(500), 0..12)` |
+| `request.scope` | `text(2000)` |
+
+## snapshot
+
+| Field | Profile |
+|---|---|
+| `snapshot.commit` | `nullable(git_oid)` |
+| `snapshot.dirty_state` | `enum(clean, dirty, unknown)` |
+| `snapshot.fingerprint` | `nullable(sha256)` |
+| `snapshot.fingerprint_recipe` | `nullable(recipe_name)` |
+| `snapshot.id` | `snapshot_id` |
+| `snapshot.limitations` | `nullable(text(1500))` |
+| `snapshot.repository` | `text(512)` |
+| `snapshot.runtime_identity` | `nullable(text(500))` |
+| `snapshot.worktree` | `text(512)` |
+
+## symptom
+
+| Field | Profile |
+|---|---|
+| `symptom.expected` | `nullable(text(1500))` |
+| `symptom.expected_evidence_ids` | `refs(evidence_id, 0..32, unique)` |
+| `symptom.observed` | `text(1500)` |

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

@@ -147,6 +147,19 @@ Then write the surviving project-state docs. Every file holds actual content der
 
 **Provenance stubs and code-map stub:** once the project-state docs above are on disk, write a provenance stub per derived doc to `.codearbiter/.provenance/<doc>.json` via `_provenancelib.write_stub` (`interview_derived: true`, empty `entries`) — one stub for each scout/source-derived doc (`CONTEXT`, `tech-stack`, `coding-standards`, `security-controls`). Also write a `.codearbiter/code-map.md` stub — a placeholder empty coarse map. WHY: greenfield has no source code yet, so real provenance entries and code-map contents populate on the first commit-gate auto-heal (or `/ca-context-check`) once code exists.
 
+After initialization, the first real package manifest is acquired through the
+normal `/ca-context-check` route, not another decomposition interview. An
+empty interview-derived `tech-stack` stub is intended context only. At task
+time, use a source/target snapshot with root `manifests` membership and call
+`_provenancelib.assess_context_provenance` for the selected document. Its
+`first_input_pending` state names the newly observed manifest paths and only
+`tech-stack` as a bounded refresh candidate. Inspect those real files through
+the selected refresh, reconcile facts with the intended architecture, and use
+the existing owner preview and receipt before any update. An empty membership
+or an uninspected boundary supplies no package command, dependency, database
+claim, or nested guidance. Preserve the initialized marker and interview
+history; the first input is not authority to rewrite them.
+
 Gate: every project-state doc written with real content; no `status: draft` ADRs remain in `decisions/`; `[CONFIRM-NN]` items are acceptable in `open-questions.md` for genuinely unresolved items; provenance stubs and code-map stub written.
 
 ## Phase 6 — Initialization lock & cleanup · gate: BLOCK

package/plugins/ca-pi/routines/subagent-driven-development/SKILL.md

@@ -98,6 +98,27 @@ The subagent works test-first by routing through the `tdd` skill (`<plugin-root>
 `tdd` Phase 1. Brief it with the task's path set, its spec obligation, and its verification command.
 Nothing else from prior tasks leaks in.
 
+Before dispatch, obtain current bounded inputs for the selected task paths:
+existing code-map text if available, assessed provenance, scoped command
+records and collector observations, applicable constraint references, and
+host-effective native instructions in precedence order. Call the private
+`_artifactpromptlib.compose_feature_actor_input` with the chosen author name,
+brief, exact approved spec and plan IDs, task ID, task paths, and those inputs.
+Send its returned `input` as the fresh child's actual input. The returned
+packet never grants task start, source-snapshot admission, or permission to
+mutate or execute a discovered command. Resolve an applicable critical
+unresolved constraint before that material action. An unavailable optional
+map permits bounded read-only orientation, not an invented complete map.
+For each author or reviewer dispatch, call `_contextselectlib.prepare_actor_delivery`
+on that actor's freshly selected packet with the actual actor/task, absolute
+worktree, current source identity, and host epoch when observable. Send its
+bounded `delivery_text` to that child on `deliver` and retain the counted
+attempt. Treat `observed` only as caller-reported load/input evidence; do not
+use a shared session or persona/read marker as a receipt. On `blocked`, stop
+the material action and report the delivery gap. Re-select after resume,
+compaction, scope expansion, or worktree switch; missing epochs get at most
+two counted deliveries for the same binding.
+
 Gate: all six `tdd` phases must be green before acceptance. Never redispatch merely to evade a failing gate.
 Under an approved `/sprint`, an ordinary implementation/test failure routes to **Recovery within the approved sprint** in `<plugin-root>/SPRINT.md`; rerun the original gate after an evidence-led correction.
 An attended invocation returns the blocked prerequisite to its caller. A real authority or security block
@@ -108,6 +129,12 @@ halts the affected work and is surfaced under the hard rules, in either mode.
 Did the change satisfy the task's obligation? Measure the result against the spec line the task
 traces to — not against whether tests merely pass.
 
+For an independent spec reviewer, freshly compose the same task-scoped input
+with actor `spec-reviewer` and the exact artifact/task IDs, then send the
+returned `input` to that reviewer before its substantive verdict. Do not
+substitute the author's packet or the coordinator's summary for reviewer
+delivery; the reviewer independently checks source identity and constraints.
+
 - Every acceptance claim in the task's obligation is met by the change.
 - Scope is clean: nothing implemented beyond the task; nothing required by it omitted.
 - Out-of-scope work the subagent noticed is recorded with an inline `[NEEDS-TRIAGE]` marker — never
@@ -132,6 +159,13 @@ Dispatch the reviewers applicable to what the combined diff touches, then `findi
 (`<plugin-root>/agents/finding-triage.md`) to classify every finding by severity. Select
 reviewers by the diff, not blanket — dispatching an irrelevant reviewer wastes a context:
 
+For each dispatched reviewer, compose and send a fresh actor input with the
+union of paths in the combined scope, the current bounded context inputs,
+exact approved spec/plan IDs, and the scope task binding. Preserve independent
+review judgment and all existing review gates. A packet read only by the
+coordinator is not reviewer delivery; unresolved critical constraints block a
+substantive verdict while bounded source inspection remains possible.
+
 - `security-reviewer` (`<plugin-root>/agents/security-reviewer.md`) — any security-relevant path (authn/authz, deploy, CI, trust boundary).
 - `auth-crypto-reviewer` (`<plugin-root>/agents/auth-crypto-reviewer.md`) — auth, crypto, key, or secret changes.
 - `dependency-reviewer` (`<plugin-root>/agents/dependency-reviewer.md`) — `package.json` / lockfile / base-image changes.

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

@@ -20,6 +20,43 @@ dispatch remains blocked.
 
 Test-first, or it does not ship. Routed to by `/feature` (after spec approval), `/fix`, and `/refactor`.
 
+For a feature author, including a confirmed small-lane feature, the owning
+coordinator selects task paths and obtains the current bounded map, provenance,
+scoped command records and collector observations, applicable constraint
+references, and host-effective instructions in native precedence order. Before
+the author mutates or executes a discovered command, compose the fresh child
+input with `_artifactpromptlib.compose_feature_actor_input` and send its
+returned `input` to that child. Bind the actual approved spec and plan IDs
+for full-lane work. For a confirmed small-lane feature, pass its mini-spec
+text as `confirmed_mini_spec` and leave both artifact IDs absent; do not invent
+a plan or bypass its existing gate. The packet
+is an orientation aid with `requires_actor_check`, not admission. Recheck
+worktree/source identity and resolve applicable critical constraints before a
+material action. Missing optional map detail permits bounded read-only source
+inspection, with full schema or document body read only when needed.
+Apply `_contextselectlib.prepare_actor_delivery` to that selected packet for
+the actual child, task, worktree and current source/host epochs. Send its
+`delivery_text` when requested and count the attempt before the material
+action; an unknown receipt or surviving session marker never proves delivery.
+Re-select on resume, compaction, scope or worktree change, and report a blocked
+delivery gap rather than assuming the child retained prior context.
+
+For a fix or targeted test-only change, use the caller that already owns the
+task. Before the author mutates or executes a discovered command, call
+`_contextselectlib.compose_fix_or_test_actor_input` with the current scoped
+sources, exact command cwd and collector evidence, then send its returned
+`input` to that actor. Use `route='fix'`, `caller='fix'`, and the confirmed
+bug-origin evidence and named regression for a fix. Use `route='test_change'`
+with the existing `fix`, `feature`, or `refactor` caller for a test-only change;
+do not create a feature spec pair merely to deliver context. The selected
+caller retains its own approval and TDD gates. Reuse an actual bug-origin RED
+when it already proves the named regression; for a targeted test change,
+validate the test against the real defect or an honest fault fixture. Never
+change production behavior merely to manufacture a failing test. If this
+conflicts with a required TDD gate, surface the conflict to that gate's owner;
+context delivery does not waive it. The packet remains reported evidence, not
+task admission.
+
 ## Pre-flight
 
 Read these, or STOP and surface the gap — never guess a command or a threshold:
@@ -28,11 +65,19 @@ Read these, or STOP and surface the gap — never guess a command or a threshold
 - `<project-root>/.codearbiter/tech-stack.md` — test, coverage, and lint invocations; file layout; mock patterns.
 - `<plugin-root>/includes/verification-boundary.md` — the required split between focused local proof and exhaustive exact-head hosted CI.
 - `<project-root>/.codearbiter/coding-standards.md` — style, structure, naming. Required for Phase 3.
-- The authoritative approved spec selected by `/feature`. For HTML, read its
-  typed criterion records through the installed engine and confirm the paired
-  plan's exact binding; for legacy Markdown, read
-  `<project-root>/.codearbiter/specs/<slug>.md`. It is the primary obligation
+- For `/feature`, the authoritative approved spec. For HTML, read its typed
+  criterion records through the installed engine and confirm the paired plan's
+  exact binding; for legacy Markdown, read
+  `<project-root>/.codearbiter/specs/<slug>.md`. It is the feature obligation
   source.
+- For `/fix`, the bug-origin evidence: observed and expected behavior, the
+  current expectation and its citations, supported cause, and the regression
+  oracle with its cited evidence. If a validated debug handoff supplies these,
+  recheck its source binding and freshness in the actual worktree and the
+  original caller authority through the fix owner. A packet or its intent field
+  does not authorize repair. Do not create a feature artifact to enter TDD.
+- For `/refactor` backfill, the user-approved surface table and pre-existing
+  parity evidence owned by `/refactor`. It does not require a feature spec.
 - `<project-root>/.codearbiter/security-controls.md` — only when the change touches a security boundary (auth, crypto, secrets, a trust boundary). Optional; absent on most changes.
 - `<project-root>/.codearbiter/code-map.md` — if present, a coarse concern→path→role map to orient before writing tests and code. Absent is fine — it is read-on-demand, populated by context-creation or commit-gate heal.
 
@@ -44,27 +89,53 @@ test is `MISSING`. "We should test X" is not an obligation.
 
 Derive every obligation before any code is written, and record each as `ID · source · OPEN`:
 
-- **Spec** — one obligation per acceptance criterion in the approved spec. For
+- **Spec (`/feature`)** — one obligation per acceptance criterion in the approved spec. For
   HTML, cite the exact artifact ID and criterion ID returned by the engine;
   caller-supplied labels cannot manufacture obligations or widen the approved
   criterion set.
+- **Bug-origin regression (`/fix`)** — one obligation for each scoped wrong
+  behavior to repair. Cite the current expectation, observed defect and supported
+  cause, regression oracle and evidence, and relevant source binding. A validated
+  debug handoff supplies cited facts, not authority; derive these rows in the
+  existing ledger. Do not invent a feature artifact such as a spec, plan, or
+  mini-spec. The target regression must go red for the right reason before the
+  minimum implementation. If the expectation is unresolved or the proposed
+  behavior is new, stop and use the feature or decision owner.
+- **Refactor parity (`/refactor` backfill)** — cite the approved surface table
+  and the uncovered symbol or seam with its pre-existing behavior and parity
+  evidence. Do not turn a refactor into a feature or a bug fix.
 - **Contract** — API and input-validation invariants, error responses, boundary conditions.
 - **Security** — only when `security-controls.md` applies: the assertion that the security-relevant boundary holds.
 
-Gate: the obligation list is complete. **Auto-pass** when every obligation maps one-to-one onto the
-acceptance criteria of an already-approved spec (full-lane spec or small-lane mini-spec) — the user
-approved that list once; do not re-ask. **User review is required** only for obligations derived
-BEYOND the spec (Contract and Security rows): surface just those additions, not the whole list.
+Gate: the obligation list is complete. For `/feature`, **auto-pass** when every obligation maps
+one-to-one onto the acceptance criteria of an already-approved spec (full-lane spec or small-lane
+mini-spec) — the user approved that list once; do not re-ask. **User review is required** only for
+obligations derived BEYOND that spec (Contract and Security rows): surface just those additions.
+For `/fix`, the scoped bug-origin regression follows the original caller's repair authority and
+current evidence; the absence of a feature spec is not a block or permission to expand scope.
+Review any proposed obligation beyond that supported correction under its actual owner. An ADR
+remains a user-attributed decision through `/adr`; neither a handoff nor this ledger creates one.
+For `/refactor`, retain its user-approved surface table and parity gates; backfill only the named
+uncovered behavior or seam. The TDD checklist does not amend that table.
 Under `/sprint`, spec-derived obligations auto-pass the same way and beyond-spec additions are
 SMARTS-decided and logged like any other auto-decision. A partial list never passes either way.
 
 ## Phase 2 — Red · gate: BLOCK
 
-Write one or more failing tests per obligation. Bind each test ID to its obligation ID and move that
-obligation `OPEN → MAPPED`. Run the test command from `tech-stack.md`.
+Bind a failing test ID to each obligation and move that obligation `OPEN → MAPPED`.
+Run the test command from `tech-stack.md`. For `/fix`, first assess an existing failing
+test against target red: compare its assertion and regression oracle with the current
+target failure and evidence. Name the existing test ID in the obligation ledger and
+reuse that named existing target-red test when its oracle is adequate and it fails for
+the target reason. Do not duplicate a test solely because of its age or because it
+predates repair. Add tests only for uncovered obligations. Do not make a named target
+failure green before observing and recording its red result.
+
+- Every newly written test MUST fail, and fail **for the right reason** — the assertion, not an import error or a typo. A new test that passes with no implementation is wrong; fix it before continuing.
+- Record unrelated existing failures in the baseline and report them; an unrelated failure is not target red. An import or setup error is not target red. Preserve each failure's identity and output. A newly broken pre-existing test is a conflict — stop and surface it.
+- Required commit gates remain blocked while required checks fail. Do not skip tests, suppress failures, or waive gates to proceed.
 
-- Every new test MUST fail, and fail **for the right reason** — the assertion, not an import error or a typo. A new test that passes with no implementation is wrong; fix it before continuing.
-- Every pre-existing test MUST stay green. One that breaks here is a conflict — stop and surface it.
+Observe the target regression red on the broken source before repair or implementation. If a material fixture or setup change occurs after that observation, the earlier red no longer qualifies: repeat target red on the broken implementation with the changed fixture or setup before the minimum repair. For an intermittent or timing defect, prefer a faithful deterministic seam. If only repeated trials can exercise the mechanism, predeclare a finite trial bound and failure oracle; record the stochastic sample limit. Do not claim deterministic proof from a passing sample or retry until green. A failing trial must match the target mechanism, not merely fail intermittently.
 
 Reject the standard traps: asserting on a mock instead of behavior; a test that can never fail; a
 snapshot so broad it asserts nothing; coupling to an implementation detail instead of observable
@@ -80,8 +151,11 @@ never the license to waive it:
 | "The test would just restate the implementation." | Then it is aimed at the wrong seam — assert the observable behavior, not the wiring. A change with no observable behavior to assert is a design finding, not an exemption. |
 | "The existing suite already covers this." | Then the failing test is impossible to write — try it. If it genuinely cannot go red, the obligation is already COVERED and Phase 4 records exactly that; if it goes red, the claim was wrong and you are holding the proof. |
 
-Gate: the runner confirms new tests red (for the right reason) and existing tests green, with every
-obligation `MAPPED` to a failing test. No implementation code is written until this gate clears.
+Gate: the runner confirms each newly written test red for the right reason, or an
+adequate named existing target-red test red for that reason, with every obligation
+`MAPPED` to a failing test. Record unrelated existing failures separately; they
+cannot count as target red or clear later required checks. No implementation code
+is written until this gate clears.
 
 ## Phase 3 — Green · gate: BLOCK
 
@@ -91,8 +165,8 @@ gold-plating — to the conventions in `coding-standards.md`. Run the impact-bou
 pre-existing test is a regression: fix it. Exhaustive and cross-platform suites run on exact-head
 hosted CI before merge.
 
-Gate: the applicable local suite is green, reached by satisfying the Phase 2 tests — not by weakening them. A test's
-assertions MUST be unchanged between red and green; only fixtures and setup may move. A relaxed
+Gate: rerun the same named target test for fresh green on the repaired source, then rerun fresh affected-contract tests on that source. Record these results with the applicable coverage, lint, and type-check results; an old-head green is not repair proof. The applicable local suite is green, reached by satisfying the Phase 2 tests — not by weakening them. A test's
+assertions MUST be unchanged between red and green; only fixtures and setup may move, and a material change to either requires renewed target red on the broken implementation before this green. A relaxed
 assertion is a gate violation.
 
 ## Phase 4 — Obligation verify · gate: BLOCK

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

@@ -107,10 +107,12 @@ Gate: the change is proven to do what it claimed by fresh evidence — command o
 
 Compute the heal worklist from the staged set via `_provenancelib.heal_worklist(staged_paths, provenance, current_hashes)` — the subset of staged paths that are `drift_trigger:true` provenance entries whose recorded hash has diverged or is absent. **Empty worklist → skip this phase entirely; most commits pay nothing** (cost guarantee: ordinary commits touching no provenance source do zero re-scout work).
 
-Non-empty worklist → run an **incremental re-scout scoped to those paths only** (not the full repo). For each path, re-examine whether the claims in the backing doc still hold:
+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.
 
-- **Claim still holds → silently re-baseline.** Call `_provenancelib.rebaseline` to update the stored hash in `.codearbiter/.provenance/<doc>.json` and stage that file by explicit path so the re-baselined record rides THIS commit (ADR-0008 ride-along pattern — nothing is surfaced to the user). After staging, re-run the secrets scan from `tech-stack.md` over the newly-staged path(s) — any file staged after Phase 4 must still pass the automated secrets scan before the commit proceeds.
-- **Claim changed → route to the existing Phase 6 diff-review.** The doc or code-map edit required to reflect the changed claim is proposed in diff review — the user reviews it as part of the normal diff; nothing is silently rewritten.
+Run an **incremental re-scout for each affected document**, scoped to its selected staged paths only (not the full repo). A fresh first document does not discharge a stale second document's claims for the same source. Resolve each selected document/path dependency independently:
+
+- **Claim still holds → silently re-baseline only that document's provenance record.** Call `_provenancelib.rebaseline(doc_provenance, selected_current_hashes)` where `selected_current_hashes` contains current hashes only for the selected staged paths whose claims in that document were inspected and still hold. Do not re-baseline a path whose claim changed or was not inspected. Stage only `.codearbiter/.provenance/<doc>.json` by explicit path so the re-baselined record rides THIS commit (ADR-0008 ride-along pattern — nothing is surfaced to the user). After staging, re-run the secrets scan from `tech-stack.md` over the newly-staged path(s) — any file staged after Phase 4 must still pass the automated secrets scan before the commit proceeds. A missing current hash (deletion or rename) cannot be silently re-baselined; surface it in Phase 6 for review.
+- **Claim changed → route to the existing Phase 6 diff-review.** Propose only the affected doc or code-map edit required to reflect its changed claim. The user reviews that edit in the normal diff, and Phase 7 stages approved paths explicitly; do not silently rewrite or add unrelated documentation.
 
 ## Phase 6 — Diff review · gate: BLOCK
 

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

@@ -31,6 +31,13 @@ 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.
 
+An **initialized refresh** belongs to this existing owner after an explicit
+selection. It is separate from initial population: do not call the initialized
+`/ca-create-context`/`/ca-init --brownfield` path, rerun the scaffolder,
+clear `<!--INITIALIZED-->`, or repeat context finalization. An ordinary status
+snapshot and the initial `/ca-status drift` report are read-only. A declined
+refresh leaves every file unchanged.
+
 ## Pre-flight
 
 Read these before computing drift:
@@ -57,8 +64,23 @@ Use `_provenancelib` helpers in this order:
 Alternatively reuse the same logic as `startup_drift_line` by calling it for
 a human-readable summary, then inspecting `compute_drift` directly for detail.
 
-If the drift report is empty: report "no stale docs — provenance is fresh"
-and exit. No further action required.
+The `entries`/Git-hash comparison above covers legacy v1 records only. For
+every enrolled v2 document, call `assess_context_provenance` with the bounded
+current source/target snapshot and an action-boundary snapshot probe. Inspect
+its per-document states as well as aggregate coverage. A missing, corrupt or
+unsupported record, incomplete acquisition, partial hash or unchecked identity
+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;
+changing hashes or choosing re-baseline does not perform that review.
+
+Only if the relevant legacy drift report is empty and v2 coverage/identities
+have been checked without unknowns may this audit report no stale identities.
+That is not a claim that instruction-bearing facts are semantically verified.
+Only a separately explicit full initialized refresh selection may proceed
+without a stale-document list.
 
 ### Step 2 — Report stale docs
 
@@ -71,28 +93,92 @@ Stale docs (N):
   ...
 ```
 
-### Step 3 — Per-doc action loop
-
-For each stale doc, present three choices and wait for the user to select one:
+Also present every enrolled v2 document's `v2_current`, `v2_stale` or unknown
+state from Step 1. For `v2_stale`, derive a proposed affected scope from that
+document's bounded evidence references and recheck the exact paths before
+selection; the legacy `changed_scope` list cannot discover v2 drift. An
+unknown state needs a bounded recovery/inspection, not an inferred fresh or
+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
+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.
+Use the existing applicable instructions under their actual precedence for the
+current task; referencing those instructions unchanged does not create a new
+normative rule or require a new approval. Keep observed upstream conventions
+and accepted ADR references source-scoped when they do not already govern this
+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.
+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 (like commit-gate Phase 5.5 heal but manually
-invoked). The scout re-reads the changed paths and reports whether claims still
-hold. If claims still hold: silently re-baseline the hashes via `rebaseline`.
-If claims changed: surface the proposed doc edits for the user to accept before
-re-baselining.
-
-**re-baseline** — acknowledge the drift without re-scouting: call
-`rebaseline(provenance, current_hashes)` to update the stored hashes silently.
-Use this when the source change is cosmetic (formatting, comments, whitespace)
-and the derived doc claims are still accurate.
+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.
+
+**re-baseline** — the legacy v1 provenance choice may acknowledge a verified
+cosmetic change through its existing owner, where applicable. For an enrolled
+v2 content document, use only a selected owned field and the native bounded
+update with new, validated source evidence and changed proposed provenance.
+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.
+
+For each selected document, submit its finite typed `update` 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.
 
 **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
 wait for a later commit.
 
-After processing all stale docs, summarize which docs were re-scouted,
-re-baselined, or deferred.
+After processing selections, summarize changed documents, deferred selections,
+the declared coverage, and whether the run was full or incremental. Keep
+unselected content, initialized state and prior history intact.
 
 ## Hard rule