@arbiterforge/ca-pi 0.15.12 → 0.16.0

package/plugins/ca-pi/hooks/session-start.py

@@ -34,7 +34,7 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 import hostapi  # noqa: E402 — host seam (ADR-0011): plugin root + capability flags
 from _durabilitylib import is_ephemeral_path  # noqa: E402
 from _hooklib import (  # noqa: E402
-    frontmatter_enabled, get_host, marker_root, project_root, set_host,
+    frontmatter_enabled, get_host, initialized_body_text, marker_root, project_root, set_host,
     utf8_stdio, write_text_atomic,
 )
 from _standuplib import (  # noqa: E402
@@ -59,7 +59,6 @@ import _updatelib  # noqa: E402 — update-available notifier (cache read + noti
 from _modelib import _DEV_PENDING_CLOSE_MAX, _settle_dev_close  # noqa: E402,F401
 import _modelib  # noqa: E402
 
-INITIALIZED_RE = re.compile(r"<!--\s*INITIALIZED\s*-->")
 STAGE_RE = re.compile(r"^stage:\s*([0-9]+)", re.I | re.M)
 CONFIRM_RE = re.compile(r"CONFIRM-[0-9]+")
 
@@ -853,7 +852,7 @@ def clear_mode_marker(root, host_name=None, session_id=None, now=None):
     _settle_dev_close(root, marker=marker, new_line=line, host_name=host_name)
 
 
-def provenance_drift_line(root, runner=None):
+def provenance_drift_line(root, runner=None, report_unknown=False):
     """One-line SessionStart drift notice, or "" when clean/degraded.
 
     Wraps _provenancelib.startup_drift_line; any failure degrades to "" so the
@@ -861,12 +860,26 @@ def provenance_drift_line(root, runner=None):
     injectable so tests are deterministic/offline; production passes None which
     lets the lib bind its default `git -C root hash-object` runner. (T-16)"""
     try:
-        return _provenancelib.startup_drift_line(
-            root, runner=runner, cmd_ref=get_host().cmd_ref)
+        unknown = [] if report_unknown else None
+        line = _provenancelib.startup_drift_line(
+            root, runner=runner, cmd_ref=get_host().cmd_ref, unknown=unknown)
+        if report_unknown and unknown:
+            return "context coverage: unknown ({}) -- run {}".format(
+                unknown[0], get_host().cmd_ref("context-check"))
+        return line
     except Exception:  # noqa: BLE001 — never crash session startup
         return ""
 
 
+def context_coverage_line(root):
+    """Bounded provenance coverage notice; no source hash or authority claim."""
+    try:
+        return _provenancelib.startup_context_coverage_line(
+            root, cmd_ref=get_host().cmd_ref)
+    except Exception:  # noqa: BLE001 — never crash session startup
+        return "context coverage: unknown -- run /ca:context-check"
+
+
 # --- Update-available notifier (spec: update-available-notifier.md) ---------
 # codeArbiter ships via a third-party marketplace, which Claude Code does NOT
 # auto-update by default. This surfaces a single line when the cached "latest"
@@ -1110,6 +1123,11 @@ def emit_daily_briefing(root, summary, date_iso, marker_present, ctx_text=None,
 
 
 def main():
+    # This is the ACTIVE host startup path. It may settle mode state, heal a
+    # host-owned statusline pin, install Git enforcement, and spawn fetch/update
+    # children. An unfamiliar repository must be inspected by the explicit-root
+    # init --check --passive route BEFORE entering a host session; a later skill
+    # cannot retroactively prevent SessionStart effects.
     utf8_stdio()
     # get_host() (#257): resolves the SAME Host run(host) already primed via
     # set_host(), instead of a second hostapi.load_host() disk/probe.
@@ -1231,7 +1249,7 @@ def main():
     emit_banner(getattr(host, "name", "unknown"), mode)
 
     ctx_text = read_text(ctx) or ""
-    if not INITIALIZED_RE.search(ctx_text):
+    if not initialized_body_text(ctx_text):
         emit_not_initialized(root, host, mode)
         sys.exit(0)
 
@@ -1246,8 +1264,9 @@ def main():
     emit_task_summary(ot_text)
 
     # --- Passive provenance drift notice (T-16, spec pillar 4) ---
-    _drift = provenance_drift_line(root)
+    _drift = provenance_drift_line(root, report_unknown=True)
     emit_provenance_drift(_drift)
+    emit_provenance_drift(context_coverage_line(root))
 
     # --- Update-available notice (AC-1/AC-2/AC-3) --------------------------
     _update = update_notice_line(plugin)

package/plugins/ca-pi/includes/author-tdd-workflow.md

@@ -1,15 +1,27 @@
 # Author TDD workflow — non-negotiable, fixed order
 
-Canonical for the author agents (`backend-author`, `frontend-author`). Loaded via each agent's
+Canonical for the author agents (`backend-author`, `frontend-author`, `infra-author`). Loaded via each agent's
 Required Reading; the agent bodies do not restate it. This is the worker's execution order for
 one task — the tdd skill's phase gates govern the lane above it.
 Apply `<plugin-root>/includes/verification-boundary.md` throughout.
 
+Use the Phase 1 checklist for the owning route. For a bug-origin `/fix`, carry the
+current expectation, cited evidence, supported cause, and regression oracle into
+the existing obligation ledger; confirm the original caller's repair authority and
+source freshness through the fix owner. Do not fabricate a feature artifact. For
+`/feature`, keep the approved spec and its criteria; for `/refactor`, keep its
+approved surface and parity contract. An ADR remains a user-attributed decision
+through `/adr`, never an author shortcut.
+
 Fixed order. Do not skip or reorder.
 
-1. **Write failing tests** — one test per obligation in the Phase 1 checklist
-2. **Confirm tests fail for the right reason** — run the test command from `tech-stack.md`; the failure must match the obligation, not an unrelated error
+1. **Map failing tests** — bind each Phase 1 obligation to a test ID. For `/fix`, assess an existing failing test against target red using the current regression oracle and evidence. Name the existing test ID in the ledger and reuse that named existing target-red test when its oracle is adequate and the assertion matches the defect. Do not duplicate a test because of its age or because it predates repair. Add tests only for uncovered obligations.
+2. **Confirm tests are red for the right reason** — run the test command from `tech-stack.md`; the target failure must match the obligation. Record unrelated existing failures in the baseline; an unrelated failure is not target red. An import or setup error is not target red. Preserve and report their identities and outputs. Required commit gates remain blocked while required checks fail. Do not skip tests, suppress failures, or waive gates to proceed.
 3. **Write minimum implementation** — only enough code to make the failing tests pass; no extra scope
-4. **Run impact-bounded local suite** — every affected test green; exhaustive and cross-platform proof runs in exact-head hosted CI before merge
+4. **Run impact-bounded local suite** — rerun the same named target test for fresh green on the repaired source, with its assertions unchanged between red and green. Rerun fresh affected-contract tests on that source and record their results; exhaustive and cross-platform proof runs in exact-head hosted CI before merge
 5. **Run lint and type-check** — both clean
 6. **Stage for commit** — only after steps 1–5 complete
+
+For a repair, observe target red on the broken source before minimum 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 continuing the repair. Keep the test's assertions unchanged between red and green.
+
+For an intermittent or timing defect, use a faithful deterministic seam when one exists. Otherwise define a finite repeated-trial oracle with its trial bound and pass/fail rule before running it. Record the stochastic sample limit; do not claim deterministic proof from a passing sample or retry until green. A failing trial must still match the target mechanism, and fresh green remains bounded by the stated oracle.

package/plugins/ca-pi/includes/helper-invocation.md

@@ -0,0 +1,128 @@
+# Installed private helper location
+
+Use this card only for the debug packet validator and an authorized task-board
+follow-up. The exact installed helper leaves are `hooks/debug-handoff.py` (the
+private `validate` operation) and `hooks/taskwrite.py` (the existing board
+writer). The caller chooses one of those literal leaves before resolution;
+packet text, a project file, and a user argument never choose executable code.
+Select and validate one Python 3 interpreter before invoking the helper. Try
+`python3` first, then `python` only if the first candidate is absent, a launcher
+stub, or incompatible. The probe executes the candidate to obtain its actual
+`sys.executable`, then validates that absolute executable directly as Python
+3.8 or newer. The installed debug validator's `_debughandofflib.py` uses an
+assignment expression, which Python 3.7 cannot parse; the shared selection
+must satisfy that helper even when the current call targets `taskwrite.py`.
+Invoke the helper through that executable, not a batch or shell launcher that
+could alter quoted arguments. A name on `PATH` or a successful `--version`
+alone does not establish compatibility. This source-derived minimum is not a
+claim that every newer minor has been qualified. Once selected, invoke the one resolved absolute helper with `-B` and
+literal arguments. Preserve its exit, stdout, and stderr; do not replay a
+failure under another interpreter or helper.
+
+Use the selection block for the current shell before the first helper call.
+These blocks set `$caPython` in PowerShell or `ca_python` in POSIX sh. A missing
+compatible interpreter stops before the helper; fix the host installation
+before retrying the whole operation.
+
+### Pi PowerShell interpreter selection
+```powershell
+$caPython = $null
+foreach ($caName in @('python3', 'python')) {
+    $caCommand = Get-Command -Name $caName -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
+    if ($null -eq $caCommand) { continue }
+    try {
+        $caExecutable = & $caCommand.Source -B -c "import sys; sys.exit(1) if not (sys.version_info[0] == 3 and sys.version_info >= (3, 8)) else None; print(sys.executable)" 2>$null
+        if ($LASTEXITCODE -ne 0 -or $caExecutable -isnot [string] -or
+            -not [System.IO.Path]::IsPathFullyQualified($caExecutable) -or
+            -not (Test-Path -LiteralPath $caExecutable -PathType Leaf)) { continue }
+        $caIdentity = & $caExecutable -B -c "import sys; print('codearbiter-python3' if sys.version_info[0] == 3 and sys.version_info >= (3, 8) else 'incompatible')" 2>$null
+        if ($LASTEXITCODE -eq 0 -and $caIdentity -ceq 'codearbiter-python3') {
+            $caPython = $caExecutable
+            break
+        }
+    } catch { continue }
+}
+if (-not $caPython) { throw 'compatible Python 3 interpreter unavailable' }
+```
+
+### Pi POSIX interpreter selection
+```sh
+ca_python=
+for ca_candidate in python3 python; do
+  ca_path=$(command -v "$ca_candidate" 2>/dev/null) || continue
+  case "$ca_path" in /*) ;; *) continue;; esac
+  [ -f "$ca_path" ] || continue
+  ca_executable=$("$ca_path" -B -c 'import sys; sys.exit(1) if not (sys.version_info[0] == 3 and sys.version_info >= (3, 8)) else None; print(sys.executable)' 2>/dev/null) || continue
+  case "$ca_executable" in
+    /*) ;;
+    [A-Za-z]:'\'*)
+      command -v cygpath >/dev/null 2>&1 || continue
+      ca_executable=$(cygpath -u "$ca_executable") || continue ;;
+    *) continue ;;
+  esac
+  [ -f "$ca_executable" ] && [ -x "$ca_executable" ] || continue
+  ca_identity=$("$ca_executable" -B -c 'import sys; print("codearbiter-python3" if sys.version_info[0] == 3 and sys.version_info >= (3, 8) else "incompatible")' 2>/dev/null) || continue
+  if [ "$ca_identity" = codearbiter-python3 ]; then ca_python=$ca_executable; break; fi
+done
+if [ -z "$ca_python" ]; then printf '%s\n' 'compatible Python 3 interpreter unavailable' >&2; exit 2; fi
+```
+
+Start from the absolute path of the **loaded installed entry resource** that
+the host actually supplied: `commands/task.md` or `commands/debug.md` on
+Claude, `skills/ca-task/SKILL.md` or `skills/ca-debug/SKILL.md` on Codex and
+Pi. The Codex and Pi skill directories are two levels below the package root;
+Claude's command directory is one level below it. Do not use the current directory, a project checkout,
+an unset `PLUGIN_ROOT`/`CLAUDE_PLUGIN_ROOT` token from a hook runner, `/hooks`,
+a source clone, or a recursive cache search. If the loaded resource, package
+identity, or exact helper is absent, report that failure and stop. Keep the
+current working directory at the intended project when invoking `taskwrite.py`.
+
+
+Pi's loaded `skills/ca-task/SKILL.md` or `skills/ca-debug/SKILL.md` is the
+anchor. `package.json` is the installed package identity marker; a written
+`<plugin-root>` string is not an executable path. Bind the selected resource
+and one literal helper leaf as above.
+
+### Pi PowerShell resolution
+```powershell
+$caResolvedResource = (Resolve-Path -LiteralPath $caLoadedResource -ErrorAction Stop).ProviderPath
+$caResourceDirectory = Split-Path -Parent $caResolvedResource
+$caInstalledRoot = (Resolve-Path -LiteralPath (Join-Path $caResourceDirectory '..\..') -ErrorAction Stop).ProviderPath
+$caManifest = Join-Path $caInstalledRoot 'package.json'
+if (-not (Test-Path -LiteralPath $caManifest -PathType Leaf)) { throw "installed ca-pi package identity missing" }
+$caHelper = Join-Path $caInstalledRoot $caHelperRelative
+if (-not (Test-Path -LiteralPath $caHelper -PathType Leaf)) { throw "installed helper missing: $caHelper" }
+```
+
+### Pi POSIX resolution
+```sh
+case "$ca_loaded_resource" in /*) ;; *) printf '%s\n' 'loaded installed resource must be absolute' >&2; exit 2;; esac
+if [ ! -f "$ca_loaded_resource" ]; then printf '%s\n' 'loaded installed resource missing' >&2; exit 2; fi
+ca_installed_root=$(CDPATH= cd -P "$(dirname "$ca_loaded_resource")/../.." && pwd -P) || exit 2
+if [ ! -f "$ca_installed_root/package.json" ]; then printf '%s\n' 'installed ca-pi package identity missing' >&2; exit 2; fi
+ca_helper=$ca_installed_root/$ca_helper_relative
+if [ ! -f "$ca_helper" ]; then printf '%s\n' 'installed helper missing' >&2; exit 2; fi
+```
+
+
+Never repair a missing installed helper by selecting a similarly named file
+from a checkout or cache. A missing or partial package blocks the operation.
+
+For private debug validation, select the literal leaf
+`hooks/debug-handoff.py` with the resolution block above. Supply one finite
+packet of at most 65,536 bytes through the host execution tool's stdin and
+retain that tool's timeout and output controls. The helper owns rejection of
+oversize input; never build a shell pipeline, command string, path argument,
+or unbounded read to transport the packet. Invoke only once with the literal
+`validate` operation and retain its original exit, stdout, and stderr.
+
+### Pi PowerShell validate invocation
+```powershell
+& $caPython -B $caHelper validate
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+```
+
+### Pi POSIX validate invocation
+```sh
+"$ca_python" -B "$ca_helper" validate
+```

package/plugins/ca-pi/includes/pi-host-notes.md

@@ -22,6 +22,19 @@ file maps those actions to Pi's extension API.
   silently allows classified reads. Plan mode is read-only except for the
   current canonical spec, plan, and plan-ledger files; source, configuration,
   unrelated project-state, and external mutations deny.
+- For an authorized debug validator or task-board writer call, load
+  [helper-invocation.md](helper-invocation.md) relative to this installed host
+  note. Derive the installed package
+  from the absolute path of the currently loaded `ca-debug` or `ca-task`
+  `SKILL.md`, then check the exact helper and run the card's PowerShell or POSIX
+  Python 3 selection block before invoking it. Select once by an executed
+  identity probe; preserve a failed helper's original output and exit status
+  without a second-interpreter attempt. Put task options before `--` and pass
+  user text as one literal argument. Feed validation one finite packet of at
+  most 65,536 bytes through the host tool's stdin using the card's direct
+  `validate` call. The literal `<plugin-root>` spelling
+  is not a shell path. A missing helper blocks the call; preserve the current
+  project working directory for board writes.
 - `codearbiter_background_bash` and `/ca-jobs list|tail|cancel` are bounded,
   session-only parent capabilities. Jobs and their metadata terminate at
   shutdown and are never restored from Pi session entries.

package/plugins/ca-pi/includes/routing-table.md

@@ -27,7 +27,7 @@ reached the same way.
 | Docs edit / dep bump / revert | `/chore` (type-scaled gates) | `dependency-reviewer` for deps | No behavioral code; suite green for deps/revert; exits via `commit-gate` |
 | Exploratory throwaway spike | `/spike` (self-contained command) → `spike/<slug>` branch | — | Never merges or PRs; `commit-gate`-exempt (nothing on the branch can land); exits to a findings note or `/feature` |
 | Behavior-preserving restructure | `refactor` skill at `<plugin-root>/routines/refactor/SKILL.md` (explicit `/refactor` uses the same owner) | `tdd` Phase 1 (coverage backfill or new seams) | No refactor without parity-coverage proof |
-| Unknown defect / investigation | `debug` skill at `<plugin-root>/routines/debug/SKILL.md` (explicit `/debug` uses the same owner) | — | No code change in the skill; one named exit |
+| Unknown defect / investigation | `debug` skill at `<plugin-root>/routines/debug/SKILL.md` (explicit `/debug` uses the same owner) | — | No code change in the skill; one of confirmed_code_defect, confirmed_noncode_cause, design_question, no_action, or unresolved with evidence; continuation retains caller authority |
 | Commit | `commit-gate` skill at `<plugin-root>/routines/commit-gate/SKILL.md` (explicit `/commit` uses the same owner) | — | No commit without all nine gates green |
 | Open a PR / finish a branch | `finishing-a-development-branch` at `<plugin-root>/routines/finishing-a-development-branch/SKILL.md`; select direct-open or caller mode first | reviewer fleet per path; PR-body prose applies `anti-slop-design` (`core` + `medium-documents` §7.A.1) | PR only; no direct-to-default, no force-push |
 | Watch a PR's CI / babysit checks | `/watch` → detached `gh pr checks --watch` | on-red diagnose (propose\|branch) | Never auto-merges; green → notify + offer; merge-to-default routes through the hard gate; no poll loop |

package/plugins/ca-pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbiterforge/ca-pi",
-  "version": "0.15.12",
+  "version": "0.16.0",
   "private": true,
   "license": "AGPL-3.0-only",
   "type": "module",

package/plugins/ca-pi/routines/INDEX.md

@@ -15,7 +15,7 @@ not both merely to repeat the same procedure. This index lists what each skill O
 | [tdd](tdd/SKILL.md) | `/feature` (after spec approval), `/fix`, `/refactor` | The test-first gate: six phases — obligation scan → red → green → obligation verify → coverage → lint. No implementation before Phase 1; no path to `commit-gate` until all six gates are green. |
 | [commit-gate](commit-gate/SKILL.md) | `/commit` | The commit gate: nine phases — permission, branch, classification, impact-bounded local verification under the shared [verification boundary](../includes/verification-boundary.md), behavioral proof, diff review, selective stage, message, commit. No commit while an applicable check is red, the behavior unproven, or secrets/cruft present; exhaustive exact-head proof remains a hosted-CI merge gate. |
 | [decision-variance](decision-variance/SKILL.md) | Architectural reconciliation or variance report; explicit `/reconcile` retained | One SMARTS arbitration owner; report-only is non-mutating. Analysis card loads on demand; only explicit user choices enter the append-only log. |
-| [debug](debug/SKILL.md) | Diagnosis intent or `/debug` | Investigate-then-decide root-cause analysis: five phases. Investigation only, no code change here; forces one named exit — `/fix`, `/adr`, or a no-action close. |
+| [debug](debug/SKILL.md) | Diagnosis intent or `/debug` | Investigate-then-decide root-cause analysis: five phases. Investigation only, no code change here; returns one evidence-backed result: confirmed_code_defect, confirmed_noncode_cause, design_question, no_action, or unresolved. Follow-up action retains caller authority; no default task or ADR write. |
 | [refactor](refactor/SKILL.md) | Behavior-preserving restructure intent or `/refactor` | Behavior-preserving change behind a parity-coverage proof gate; routes to `tdd` Phase 1 for coverage backfill or new test seams. |
 | [context-creation](context-creation/SKILL.md) | `/create-context` (brownfield) | Back-fills `.codearbiter/` from existing source via parallel scouts; writes `CONTEXT.md` (`arbiter: enabled` + `stage:`) and locks it `<!--INITIALIZED-->`. |
 | [decompose](decompose/SKILL.md) | greenfield startup, `/decompose` | Six-layer senior-architect interview, compaction-resilient via per-layer disk drafts + DRAFT ADRs; populates `.codearbiter/` and locks it initialized. |

package/plugins/ca-pi/routines/commit-gate/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/routines/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