@arbiterforge/ca-pi 0.17.6 → 0.17.8

package/README.md

@@ -10,7 +10,7 @@ and durable project context. You decide. codeArbiter enforces.
 <img alt="Claude Code plugin" src="https://img.shields.io/badge/Claude_Code-plugin-d97757">
 <img alt="Codex plugin" src="https://img.shields.io/badge/OpenAI_Codex-plugin-10a37f">
 <img alt="Pi Feature Forge preview" src="https://img.shields.io/badge/ca--pi-Feature_Forge_preview-d97757">
-<img alt="version 2.25.5" src="https://img.shields.io/badge/version-2.25.5-2b7489">
+<img alt="version 2.25.7" src="https://img.shields.io/badge/version-2.25.7-2b7489">
 <img alt="core lanes" src="https://img.shields.io/badge/core_lanes-18-555">
 <img alt="skills" src="https://img.shields.io/badge/skills-22-555">
 <img alt="agents" src="https://img.shields.io/badge/agents-20-555">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbiterforge/ca-pi",
-  "version": "0.17.6",
+  "version": "0.17.8",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",

package/plugins/ca-pi/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to `ca-pi` are documented in this file.
 
 ## [Unreleased]
 
+## [0.17.8] - 2026-10-12
+
+### Fixed
+
+- Restore reviewed legacy code-map metadata updates and explicit per-block Git
+  conflict resolution with bounded helpers, preserving native ownership,
+  stale-input checks, unselected text and the Git index (#967).
+- Explain debug packet shapes and link the trusted schema and a synthetic
+  unresolved example before one-shot validation (#951).
+- Document brownfield host prerequisites before scaffolding, preserving
+  containment, native approval and partial-state recovery gates (#950).
+
+## [0.17.7] - 2026-10-10
+
+### Fixed
+
+- Carry the shared bounded verification projection and approval preflight checks,
+  retaining complete command definitions, source snapshot ordering and full plan
+  identity freshness. Pi verification and review authority remain unsupported.
+
 ## [0.17.6] - 2026-10-10
 
 ### Fixed

package/plugins/ca-pi/helpers/artifacts/release.json

@@ -6,43 +6,43 @@
   "binaries": {
     "darwin/amd64": {
       "file": "ca-artifact-darwin-amd64",
-      "sha256": "7b9e95dba78bda2962d1b879c373a835466fe59aa082a3afb6efbc1fb3de454d",
+      "sha256": "5214e1062e49aa39cd73868cd9792e7e296a865bb6e86230b17c19dda1ba3b71",
       "native_tested": true
     },
     "darwin/arm64": {
       "file": "ca-artifact-darwin-arm64",
-      "sha256": "2469bd38df4e241f19bb443c4388283aaadc0638951a77331b25be81929d4f4c",
+      "sha256": "dde6deb178a0e725f8a88b1b30fa6980622b8af3b13fb73261aaaea47eb75a38",
       "native_tested": true
     },
     "linux/amd64": {
       "file": "ca-artifact-linux-amd64",
-      "sha256": "cf4116c08afa66426c3b9d78853dfc09b608e05412054b6fe18817a65db96a76",
+      "sha256": "ca2d5e0fecac0c99c45dc7576fff7d56af63dbd85decb4cfc54f81621ac90901",
       "native_tested": true
     },
     "linux/arm64": {
       "file": "ca-artifact-linux-arm64",
-      "sha256": "b1e92f0d279fe04b61dd287a4b20fc1db4abc3722c0325f5294a55bb1a972895",
+      "sha256": "de18df4c499814f6ccfc69efa6bfb6f4bbcd37c2af5dd091727233f1aaf91a39",
       "native_tested": true
     },
     "windows/amd64": {
       "file": "ca-artifact-windows-amd64.exe",
-      "sha256": "d8fa783dc8d30c5d48a8c336bca8ee5fd85be4c72629d7ac7246842b89c5135c",
+      "sha256": "ddab696f02b946400feac527f747a020b76dbb9e5dd444b0b7d464acbcd3888e",
       "native_tested": true
     },
     "windows/arm64": {
       "file": "ca-artifact-windows-arm64.exe",
-      "sha256": "2df30c81eb58d502aa9a146563b9dd725176cac9f907ebf36b73c157e5de2124",
+      "sha256": "23689eaa4df71f95bde58b18bc32fab8d4ae709495250ddfd13192fc0427a813",
       "native_tested": true
     }
   },
   "context_qualification": {
     "darwin/amd64": {
-      "source_commit": "7ef1feead876e08e9ad63d5e507a01650488719f",
+      "source_commit": "4c2529e2f3804d38855094e1c11d36178067c826",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38042731230",
-      "binary_sha256": "7b9e95dba78bda2962d1b879c373a835466fe59aa082a3afb6efbc1fb3de454d",
-      "observation_sha256": "c359781d36118baf2ebe6b73bb0ecefb59f4ca500b31a6f7e5baf52474e1127c",
-      "module_sha256": "fb635481a9bf9a88dbe052c2d738c28c1e3d2a6d741514fc28ac51b6fc8a47b4",
+      "run_id": "38219547942",
+      "binary_sha256": "5214e1062e49aa39cd73868cd9792e7e296a865bb6e86230b17c19dda1ba3b71",
+      "observation_sha256": "fdd1d120d5ad0e4aed101efad7c32aeac561035faf075b70abf3ba5f82a4bc3b",
+      "module_sha256": "1aea76bc4dc8b54b368dccc80c3a1133b403b5915018fdcb6018f1a3913fe66c",
       "native_cases": [
         "TestContextBoundedRender",
         "TestContextDocumentContract",
@@ -53,12 +53,12 @@
       ]
     },
     "darwin/arm64": {
-      "source_commit": "7ef1feead876e08e9ad63d5e507a01650488719f",
+      "source_commit": "4c2529e2f3804d38855094e1c11d36178067c826",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38042731230",
-      "binary_sha256": "2469bd38df4e241f19bb443c4388283aaadc0638951a77331b25be81929d4f4c",
-      "observation_sha256": "2d4c75ec50210c0bbf4b8c9a754a0fd89ee81dc60c9607066cf17c4e1af2050a",
-      "module_sha256": "fb635481a9bf9a88dbe052c2d738c28c1e3d2a6d741514fc28ac51b6fc8a47b4",
+      "run_id": "38219547942",
+      "binary_sha256": "dde6deb178a0e725f8a88b1b30fa6980622b8af3b13fb73261aaaea47eb75a38",
+      "observation_sha256": "18294ead6b8a48804464f06f1bcc8254e0176c0ac0c48486a121aa1a018a309a",
+      "module_sha256": "1aea76bc4dc8b54b368dccc80c3a1133b403b5915018fdcb6018f1a3913fe66c",
       "native_cases": [
         "TestContextBoundedRender",
         "TestContextDocumentContract",
@@ -69,12 +69,12 @@
       ]
     },
     "linux/amd64": {
-      "source_commit": "7ef1feead876e08e9ad63d5e507a01650488719f",
+      "source_commit": "4c2529e2f3804d38855094e1c11d36178067c826",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38042731230",
-      "binary_sha256": "cf4116c08afa66426c3b9d78853dfc09b608e05412054b6fe18817a65db96a76",
-      "observation_sha256": "0a57cde8e4f251ee5faf2cd2dc256638622464030cda79988c11295dec6dfec9",
-      "module_sha256": "fb635481a9bf9a88dbe052c2d738c28c1e3d2a6d741514fc28ac51b6fc8a47b4",
+      "run_id": "38219547942",
+      "binary_sha256": "ca2d5e0fecac0c99c45dc7576fff7d56af63dbd85decb4cfc54f81621ac90901",
+      "observation_sha256": "e4717e28c2ca9a27fc278196310a00a3adff09766d307951ba93de57b262f6ab",
+      "module_sha256": "1aea76bc4dc8b54b368dccc80c3a1133b403b5915018fdcb6018f1a3913fe66c",
       "native_cases": [
         "TestContextBoundedRender",
         "TestContextDocumentContract",
@@ -85,12 +85,12 @@
       ]
     },
     "linux/arm64": {
-      "source_commit": "7ef1feead876e08e9ad63d5e507a01650488719f",
+      "source_commit": "4c2529e2f3804d38855094e1c11d36178067c826",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38042731230",
-      "binary_sha256": "b1e92f0d279fe04b61dd287a4b20fc1db4abc3722c0325f5294a55bb1a972895",
-      "observation_sha256": "926d97ef85d2cd9caa658db620c7f135ea5a07873a188f289181a37ae636921d",
-      "module_sha256": "fb635481a9bf9a88dbe052c2d738c28c1e3d2a6d741514fc28ac51b6fc8a47b4",
+      "run_id": "38219547942",
+      "binary_sha256": "de18df4c499814f6ccfc69efa6bfb6f4bbcd37c2af5dd091727233f1aaf91a39",
+      "observation_sha256": "03064179c8e677c66c0c90a2d109b139e5b3bb057fa296d5a9da4946ae26c37c",
+      "module_sha256": "1aea76bc4dc8b54b368dccc80c3a1133b403b5915018fdcb6018f1a3913fe66c",
       "native_cases": [
         "TestContextBoundedRender",
         "TestContextDocumentContract",
@@ -101,12 +101,12 @@
       ]
     },
     "windows/amd64": {
-      "source_commit": "7ef1feead876e08e9ad63d5e507a01650488719f",
+      "source_commit": "4c2529e2f3804d38855094e1c11d36178067c826",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38042731230",
-      "binary_sha256": "d8fa783dc8d30c5d48a8c336bca8ee5fd85be4c72629d7ac7246842b89c5135c",
-      "observation_sha256": "70827706a7d231df640f9d4b27b4250f81311bfd89bee11b65ff48b985c1085c",
-      "module_sha256": "fb635481a9bf9a88dbe052c2d738c28c1e3d2a6d741514fc28ac51b6fc8a47b4",
+      "run_id": "38219547942",
+      "binary_sha256": "ddab696f02b946400feac527f747a020b76dbb9e5dd444b0b7d464acbcd3888e",
+      "observation_sha256": "e31ae79bc15c37dbb157c11e5a3775dd0d314350bbf761a968999ba4ffde2d9c",
+      "module_sha256": "1aea76bc4dc8b54b368dccc80c3a1133b403b5915018fdcb6018f1a3913fe66c",
       "native_cases": [
         "TestContextBoundedRender",
         "TestContextDocumentContract",
@@ -117,12 +117,12 @@
       ]
     },
     "windows/arm64": {
-      "source_commit": "7ef1feead876e08e9ad63d5e507a01650488719f",
+      "source_commit": "4c2529e2f3804d38855094e1c11d36178067c826",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38042731230",
-      "binary_sha256": "2df30c81eb58d502aa9a146563b9dd725176cac9f907ebf36b73c157e5de2124",
-      "observation_sha256": "f15d9d9894d0ae845e14c3bfba1cf1528f1debe166850e9fb0b46aee27d99dbd",
-      "module_sha256": "fb635481a9bf9a88dbe052c2d738c28c1e3d2a6d741514fc28ac51b6fc8a47b4",
+      "run_id": "38219547942",
+      "binary_sha256": "23689eaa4df71f95bde58b18bc32fab8d4ae709495250ddfd13192fc0427a813",
+      "observation_sha256": "e04cb8b45299950247c82557e7aa4c60c4c7b6b9718775b8c3ecaedc1d7bb6fe",
+      "module_sha256": "1aea76bc4dc8b54b368dccc80c3a1133b403b5915018fdcb6018f1a3913fe66c",
       "native_cases": [
         "TestContextBoundedRender",
         "TestContextDocumentContract",

package/plugins/ca-pi/hooks/_approvallib.py

@@ -93,70 +93,44 @@ def _preflight_plan_verification(client: Any, identity: dict[str, Any]) -> dict[
     artifact_id = identity["artifact_id"]
 
     def same_identity(value: dict[str, Any]) -> None:
-        if not isinstance(value, dict) or any(value.get(key) != identity.get(key) for key in keys):
+        if not isinstance(value, dict) or type(value.get("revision")) is not int:
+            raise _artifactlib.ArtifactError("INVALID_RESPONSE", "plan verification identity is malformed")
+        if any(value.get(key) != identity.get(key) for key in keys):
             raise _artifactlib.ArtifactError("STALE_PLAN_PREFLIGHT", "plan identity changed during verification preflight; reread the complete current plan")
 
-    def task_records(ids: list[str]):
-        for start in range(0, len(ids), 128):
-            selected = ids[start:start + 128]
-            offset = 0
-            for _ in range(len(selected)):
-                page = client.call("read-batch", {
-                    "artifact_id": artifact_id, "symbols": selected,
-                    "model_sha256": identity["model_sha256"], "offset": offset, "budget": 16384,
-                })
-                same_identity(page)
-                _artifactlib.ArtifactClient._check_page(page, offset, "records")
-                records = page["records"]
-                end = offset + len(records)
-                if (page.get("mode") != "exact" or page.get("context_complete") is not False
-                        or type(page.get("offset")) is not int or page["offset"] != offset
-                        or type(page.get("total")) is not int or page["total"] != len(selected)
-                        or not records or end > len(selected)
-                        or page["next_offset"] != (end if end < len(selected) else None)):
-                    raise _artifactlib.ArtifactError("INVALID_RESPONSE", "plan task batch count, offset or completeness changed")
-                for expected_id, row in zip(selected[offset:end], records):
-                    if (not isinstance(row, dict) or row.get("id") != expected_id
-                            or row.get("kind") != "tasks" or row.get("retired") is not False
-                            or not isinstance(row.get("record"), dict) or row["record"].get("id") != expected_id):
-                        raise _artifactlib.ArtifactError("INVALID_RESPONSE", "plan task batch contains an invalid or unexpected record")
-                    yield row["record"]
-                if page["next_offset"] is None:
-                    break
-                offset = end
-            else:
-                raise _artifactlib.ArtifactError("INVALID_RESPONSE", "plan task batch did not terminate")
-
-    same_identity(client.call("identity", {"artifact_id": artifact_id}))
     root = _artifactlib._trusted_directory(client.root, "UNSAFE_ROOT")
     diagnostics: list[str] = []
-    seen: set[str] = set()
+    last_task_id = ""
     command_count = 0
     offset, total = 0, None
     for _ in range(8193):
-        request = {"artifact_id": artifact_id, "offset": offset, "budget": 16384}
-        if offset:
-            request["model_sha256"] = identity["model_sha256"]
-        page = client.call("outline", request)
+        try:
+            page = client.call("plan-verification", {
+                "artifact_id": artifact_id, "expected": {key: identity[key] for key in keys},
+                "offset": offset, "budget": 16384,
+            })
+        except _artifactlib.ArtifactError as exc:
+            if exc.code == "STALE_CURSOR":
+                raise _artifactlib.ArtifactError("STALE_PLAN_PREFLIGHT", "plan identity changed during verification preflight; reread the complete current plan") from exc
+            raise
         same_identity(page)
-        _artifactlib.ArtifactClient._check_page(page, offset, "records")
-        if (page.get("offset") != offset or type(page.get("total")) is not int
-                or page["total"] < offset + len(page["records"])
-                or total is not None and page["total"] != total):
-            raise _artifactlib.ArtifactError("INVALID_RESPONSE", "plan outline count or offset changed")
+        _artifactlib.ArtifactClient._check_page(page, offset, "tasks")
+        tasks = page["tasks"]
+        end = offset + len(tasks)
+        if (page.get("context_complete") is not False
+                or type(page.get("offset")) is not int or page["offset"] != offset
+                or type(page.get("total")) is not int or page["total"] < end
+                or total is not None and page["total"] != total
+                or not tasks and page["total"] != 0
+                or page["next_offset"] != (end if end < page["total"] else None)):
+            raise _artifactlib.ArtifactError("INVALID_RESPONSE", "plan verification count, offset or completeness changed")
         total = page["total"]
-        tasks = []
-        for row in page["records"]:
-            if (not isinstance(row, dict) or not isinstance(row.get("id"), str)
-                    or row["id"] in seen or type(row.get("retired")) is not bool):
-                raise _artifactlib.ArtifactError("INVALID_RESPONSE", "plan outline contains an invalid or duplicate record")
-            seen.add(row["id"])
-            if row.get("kind") != "tasks" or row["retired"]:
-                continue
-            tasks.append(row["id"])
-        for task in task_records(tasks):
-            if not isinstance(task.get("verification"), list) or not task["verification"]:
-                raise _artifactlib.ArtifactError("INVALID_RESPONSE", "plan task lacks complete verification definitions")
+        for task in tasks:
+            if (not isinstance(task, dict) or set(task) != {"id", "verification"}
+                    or not isinstance(task.get("id"), str) or task["id"] <= last_task_id
+                    or not isinstance(task.get("verification"), list) or not task["verification"]):
+                raise _artifactlib.ArtifactError("INVALID_RESPONSE", "plan verification contains an invalid, unordered or incomplete task")
+            last_task_id = task["id"]
             for number, definition in enumerate(task["verification"], 1):
                 command_count += 1
                 try:
@@ -177,17 +151,11 @@ def _preflight_plan_verification(client: Any, identity: dict[str, Any]) -> dict[
                 except (_artifactlib.ArtifactError, _artifactauthoritylib.AuthorityError) as exc:
                     argv = definition.get("argv") if isinstance(definition, dict) else None
                     diagnostics.append(f"{task['id']} verification[{number}] {json.dumps(argv, ensure_ascii=True)}: {exc}")
-        next_offset = page["next_offset"]
-        expected = offset + len(page["records"])
-        if next_offset is None:
-            if expected != total:
-                raise _artifactlib.ArtifactError("INVALID_RESPONSE", "plan outline ended before every record was inspected")
+        if page["next_offset"] is None:
             break
-        if next_offset != expected:
-            raise _artifactlib.ArtifactError("INVALID_RESPONSE", "plan outline skipped records")
-        offset = next_offset
+        offset = end
     else:
-        raise _artifactlib.ArtifactError("INVALID_RESPONSE", "plan outline did not terminate")
+        raise _artifactlib.ArtifactError("INVALID_RESPONSE", "plan verification did not terminate")
     try:
         snapshot = client.call("snapshot", {"artifact_id": artifact_id})
     except _artifactlib.ArtifactError as exc:

package/plugins/ca-pi/hooks/_contextmergelib.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-# codeArbiter — restore the committed current side of a legacy code-map conflict.
+# codeArbiter — bounded legacy code-map recovery and metadata claim refresh.
 #
 # Fixed target and source only. Inspection binds the real merge, all index bytes,
 # conflict rendering and legacy provenance. Application rechecks that identity,
@@ -9,9 +9,14 @@
 # Public API:
 #   inspect(root) -> dict                   read-only recovery binding
 #   restore_head(root, expected) -> dict    restore exact HEAD blob, never stage
+#   inspect_claims(root) -> dict            bind existing metadata and sources
+#   refresh_claims(root, expected, claims) -> dict  selected metadata only
+#   inspect_blocks(root) -> dict            bind genuine Git conflict blocks
+#   resolve_blocks(root, expected, choices) -> dict  finite ours/theirs choices
 #   main(argv=None) -> int                  bounded JSON CLI
 
 import argparse
+import datetime
 import hashlib
 import json
 import os
@@ -20,6 +25,7 @@ import re
 import stat
 import subprocess
 import sys
+import tempfile
 
 from _appendonlyconflictlib import ResolutionError, _validate_conflicted_worktree, _write_bytes_atomic
 from _artifactlib import ArtifactError, _decode, _open_pinned_regular, _trusted_directory
@@ -32,6 +38,18 @@ TARGET = ".codearbiter/code-map.md"
 PROVENANCE = ".codearbiter/.provenance/code-map.json"
 MAX_BYTES = 8 << 20
 OID = r"[0-9a-f]{40}(?:[0-9a-f]{24})?"
+VERSION = r"(?:0|[1-9][0-9]{0,8})\.(?:0|[1-9][0-9]{0,8})\.(?:0|[1-9][0-9]{0,8})"
+MANIFESTS = {
+    "ca_version": "plugins/ca/.claude-plugin/plugin.json",
+    "codex_version": "plugins/ca-codex/.codex-plugin/plugin.json",
+    "pi_version": "plugins/ca-pi/package.json",
+}
+CLAIM_PATTERNS = {
+    "ca_version": rb"^- `plugins/ca/` \(v(" + VERSION.encode() + rb")(?=\))",
+    "codex_version": rb"^- `plugins/ca-codex/` \(v(" + VERSION.encode() + rb")(?=\))",
+    "pi_version": rb"^- `plugins/ca-pi/` \(v(" + VERSION.encode() + rb")(?=[,)])",
+    "metadata_date": rb"metadata refreshed on ([0-9]{4}-[0-9]{2}-[0-9]{2})(?=\.)",
+}
 
 
 def _require(condition, reason):
@@ -54,13 +72,14 @@ def _git(root, *args):
     return result.stdout
 
 
-def _read(path):
+def _read(path, *, single_link=False):
     _trusted_directory(path.parent, "UNSAFE_CONTEXT_PATH")
     descriptor = _open_pinned_regular(path)
     try:
         info = os.fstat(descriptor)
         _require(stat.S_ISREG(info.st_mode) and not getattr(info, "st_file_attributes", 0) & 0x400
                  and info.st_size <= MAX_BYTES, "context evidence must be a bounded regular file")
+        _require(not single_link or info.st_nlink == 1, "linked claim evidence is not supported")
         with os.fdopen(descriptor, "rb", closefd=False) as handle:
             raw = handle.read(MAX_BYTES + 1)
         _require(len(raw) <= MAX_BYTES, "context evidence is oversized")
@@ -75,7 +94,7 @@ def _legacy(raw):
              and record["doc"] == "code-map", "legacy code-map provenance required; native ownership is not recoverable here")
 
 
-def _snapshot(requested_root):
+def _snapshot(requested_root, *, blocks=False):
     root = _trusted_directory(requested_root, "UNSAFE_CONTEXT_ROOT")
     actual = Path(_git(root, "rev-parse", "--show-toplevel").decode().strip()).resolve(strict=True)
     _require(actual == root, "explicit repository root required")
@@ -103,7 +122,13 @@ def _snapshot(requested_root):
     theirs = _git(root, "cat-file", "blob", stages[2][1])
     # Reuse the existing single-conflict renderer check. Unsupported renderings
     # (including a non-empty diff3 base) refuse rather than discarding human text.
-    _validate_conflicted_worktree(current, b"", ours, theirs)
+    payload = ours
+    rendered = None
+    if blocks:
+        payload, rendered = _git_conflict_blocks(root, current,
+                                               _git(root, "cat-file", "blob", stages[0][1]), ours, theirs)
+    else:
+        _validate_conflicted_worktree(current, b"", ours, theirs)
     provenance = _read(root / PROVENANCE)
     _legacy(provenance)
     for revision in (base, head, incoming):
@@ -116,9 +141,17 @@ def _snapshot(requested_root):
     binding = {"root": str(root), "git_dir": str(git_dir), "head": head, "merge_head": incoming,
                "stages": stages, "index_sha256": _hash(_read(index)),
                "worktree_sha256": _hash(current), "provenance_sha256": _hash(provenance)}
+    if blocks:
+        binding["resolution"] = {"operation": "resolve-blocks", "rendering": rendered,
+                                 "blocks": len(payload[0])}
     digest = _hash(json.dumps(binding, sort_keys=True, separators=(",", ":")).encode())
-    return root, index, current, ours, {"target": TARGET, "head": head, "merge_head": incoming,
-                                        "head_sha256": _hash(ours), "binding": digest}
+    result = {"target": TARGET, "head": head, "merge_head": incoming,
+              "head_sha256": _hash(ours), "binding": digest}
+    if blocks:
+        result.update(blocks=len(payload[0]), rendering=rendered,
+                      sides=[{"ours_sha256": _hash(part["ours"]),
+                              "theirs_sha256": _hash(part["theirs"])} for part in payload[0]])
+    return root, index, current, payload, result
 
 
 def inspect(root):
@@ -143,16 +176,270 @@ def restore_head(root, expected):
     return {**fresh, "status": "restored", "staged": False}
 
 
+def _claim_matches(raw):
+    text = raw.decode("utf-8", "strict")
+    _require(re.match(r"^# Code map(?:[ \t][^\r\n]*)?\r?\n", text) is not None
+             and "\0" not in text and re.search(r"^(?:<{7,}|={7,}|>{7,}|\|{7,})", text, re.M) is None,
+             "a resolved UTF-8 code map is required")
+    fields = {}
+    for field, pattern in CLAIM_PATTERNS.items():
+        matches = list(re.finditer(pattern, raw, re.M))
+        _require(len(matches) <= 1, "ambiguous metadata claim")
+        if matches:
+            fields[field] = matches[0]
+    return fields
+
+
+def _claim_snapshot(requested_root):
+    root = _trusted_directory(requested_root, "UNSAFE_CONTEXT_ROOT")
+    actual = Path(_git(root, "rev-parse", "--show-toplevel").decode().strip()).resolve(strict=True)
+    _require(actual == root, "explicit repository root required")
+    git_dir = _trusted_directory(
+        _git(root, "rev-parse", "--absolute-git-dir").decode().strip(), "UNSAFE_GIT_DIRECTORY")
+    index = Path(_git(root, "rev-parse", "--path-format=absolute", "--git-path", "index").decode().strip())
+    head = _git(root, "rev-parse", "--verify", "HEAD^{commit}").decode().strip()
+    _require(re.fullmatch(OID, head), "current Git head required")
+    _require(not _git(root, "ls-files", "--unmerged", "--", TARGET, PROVENANCE),
+             "resolve context and provenance conflicts before claim refresh")
+    tracked = _git(root, "ls-files", "--stage", "-z", "--", TARGET, PROVENANCE).split(b"\0")
+    indexed = {}
+    for raw in tracked:
+        if raw:
+            matched = re.fullmatch(r"100644 (" + OID + r") 0\t(.+)", raw.decode())
+            _require(matched is not None and matched[2] in {TARGET, PROVENANCE},
+                     "regular tracked legacy context required")
+            indexed[matched[2]] = matched[1]
+    _require(set(indexed) == {TARGET, PROVENANCE}, "tracked document and provenance required")
+    current = _read(root / TARGET, single_link=True)
+    fields = _claim_matches(current)
+    provenance = _read(root / PROVENANCE, single_link=True)
+    _legacy(provenance)
+    _legacy(_git(root, "cat-file", "blob", head + ":" + PROVENANCE))
+    _legacy(_git(root, "cat-file", "blob", indexed[PROVENANCE]))
+    merge = None
+    if os.path.lexists(git_dir / "MERGE_HEAD"):
+        merge = _read(git_dir / "MERGE_HEAD").decode().strip()
+        _require(re.fullmatch(OID, merge), "one current merge head required")
+        _legacy(_git(root, "cat-file", "blob", merge + ":" + PROVENANCE))
+    for relative in (".codearbiter/.artifacts", ".codearbiter/.artifacts/transactions"):
+        if os.path.lexists(root / relative):
+            _trusted_directory(root / relative, "UNSAFE_CONTEXT_JOURNAL")
+    _require(_committed_context_journal(root, "code-map", TARGET) is False,
+             "native or uncertain context ownership requires its writer")
+    sources = {}
+    for field, relative in MANIFESTS.items():
+        raw = _read(root / relative, single_link=True)
+        manifest = _decode(raw)
+        version = manifest.get("version") if isinstance(manifest, dict) else None
+        _require(isinstance(version, str) and re.fullmatch(VERSION, version),
+                 "literal current source manifest version required")
+        sources[field] = {"version": version, "sha256": _hash(raw)}
+    binding = {"root": str(root), "git_dir": str(git_dir), "head": head, "merge_head": merge,
+               "index_sha256": _hash(_read(index)), "target_sha256": _hash(current),
+               "provenance_sha256": _hash(provenance), "sources": sources,
+               "claims": {field: matched[1].decode("ascii") for field, matched in fields.items()},
+               "inspection_date": datetime.date.today().isoformat()}
+    digest = _hash(json.dumps(binding, sort_keys=True, separators=(",", ":")).encode())
+    return root, index, current, sources, {**binding, "target": TARGET, "binding": digest}
+
+
+def inspect_claims(root):
+    return _claim_snapshot(root)[-1]
+
+
+def _selected_claim_bytes(current, sources, inspection_date, claims):
+    _require(type(claims) is list and 1 <= len(claims) <= 4, "select one to four existing metadata claims")
+    matches = _claim_matches(current)
+    edits = []
+    seen = set()
+    for claim in claims:
+        _require(type(claim) is dict and set(claim) == {"field", "before", "after"}, "typed metadata claims required")
+        field, before, after = claim["field"], claim["before"], claim["after"]
+        _require(type(field) is str and field in matches and field not in seen
+                 and type(before) is str and type(after) is str and before != after,
+                 "select each existing metadata claim once")
+        seen.add(field)
+        matched = matches[field]
+        _require(matched[1].decode() == before, "exact claim preimage required")
+        if field == "metadata_date":
+            datetime.date.fromisoformat(before)
+            _require(after == inspection_date, "refresh date must be the actual inspection date")
+        else:
+            _require(re.fullmatch(VERSION, after) and after == sources[field]["version"],
+                     "claim must match the current source manifest")
+        edits.append((*matched.span(1), after.encode("ascii")))
+    for start, end, replacement in sorted(edits, reverse=True):
+        current = current[:start] + replacement + current[end:]
+    return current
+
+
+def refresh_claims(root, expected, claims):
+    _require(isinstance(expected, str) and re.fullmatch(r"[0-9a-f]{64}", expected), "exact inspection binding required")
+    root, index, current, sources, initial = _claim_snapshot(root)
+    _require(initial["binding"] == expected, "stale claim binding; inspect again")
+    _selected_claim_bytes(current, sources, initial["inspection_date"], claims)
+    lock_path = Path(str(index) + ".lock")
+    descriptor = os.open(lock_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    try:
+        root, _index, before, sources, fresh = _claim_snapshot(root)
+        _require(fresh["binding"] == expected, "stale claim binding; inspect again")
+        proposed = _selected_claim_bytes(before, sources, fresh["inspection_date"], claims)
+        _write_bytes_atomic(root / TARGET, proposed, expected=before)
+    finally:
+        os.close(descriptor)
+        lock_path.unlink()
+    return {**fresh, "status": "refreshed", "staged": False, "after_sha256": _hash(proposed)}
+
+
+def _marker(line):
+    matched = re.fullmatch(rb"([<|=>]{7,32})(?: ([^\r\n]{1,256}))?\r?\n", line)
+    if matched is None or len(set(matched[1])) != 1:
+        return None
+    return matched[1][:1], len(matched[1]), matched[2] or b""
+
+
+def _parse_conflict_blocks(raw):
+    text = raw.decode("utf-8", "strict")
+    _require("\0" not in text, "UTF-8 text conflict required")
+    lines = raw.splitlines(keepends=True)
+    pieces, labels, marker_size = [], None, None
+    cursor = 0
+    prefix = []
+    while cursor < len(lines):
+        marker = _marker(lines[cursor])
+        if marker is None:
+            prefix.append(lines[cursor])
+            cursor += 1
+            continue
+        _require(marker[0] == b"<" and marker[2] == b"HEAD", "recognized Git HEAD conflict required")
+        size = marker[1]
+        side_labels = [marker[2], b"base", None]
+        part = {"prefix": b"".join(prefix), "ours": b"", "base": None, "theirs": b""}
+        prefix = []
+        cursor += 1
+        side, content = "ours", []
+        while cursor < len(lines):
+            marker = _marker(lines[cursor])
+            if marker is None:
+                content.append(lines[cursor])
+                cursor += 1
+                continue
+            _require(marker[1] == size, "consistent conflict marker size required")
+            if marker[0] == b"|" and side == "ours":
+                _require(marker[2], "Git base label required")
+                part[side] = b"".join(content)
+                side_labels[1] = marker[2]
+                side, content = "base", []
+            elif marker[0] == b"=" and side in {"ours", "base"}:
+                _require(not marker[2], "plain Git separator required")
+                part[side] = b"".join(content)
+                side, content = "theirs", []
+            elif marker[0] == b">" and side == "theirs":
+                _require(marker[2], "Git incoming label required")
+                part[side] = b"".join(content)
+                side_labels[2] = marker[2]
+                cursor += 1
+                break
+            else:
+                raise ResolutionError("ambiguous or nested conflict markers")
+            cursor += 1
+        _require(side_labels[2] is not None, "complete conflict block required")
+        if labels is None:
+            labels, marker_size = side_labels, size
+        _require(side_labels == labels and size == marker_size, "one consistent Git rendering required")
+        pieces.append(part)
+        _require(len(pieces) <= 32, "at most 32 conflict blocks supported")
+    _require(pieces, "Git conflict blocks required")
+    return (pieces, b"".join(prefix)), labels, marker_size
+
+
+def _git_conflict_blocks(root, current, base, ours, theirs):
+    payload, labels, size = _parse_conflict_blocks(current)
+    modes = (("diff3", "--diff3"), ("zdiff3", "--zdiff3")) if payload[0][0]["base"] is not None else (("merge", None),)
+    env = root_bound_git_env()
+    env.update(GIT_OPTIONAL_LOCKS="0", GIT_TERMINAL_PROMPT="0", GIT_NO_REPLACE_OBJECTS="1")
+    # Git itself must reproduce all hunk bodies and all unconflicted text from
+    # the real three stages. Labels are only the current bounded marker labels;
+    # no caller content, custom merge driver or arbitrary revision is executed.
+    with tempfile.TemporaryDirectory(prefix="codearbiter-context-merge-") as temporary:
+        paths = [Path(temporary) / name for name in ("ours", "base", "theirs")]
+        for path, raw in zip(paths, (ours, base, theirs)):
+            path.write_bytes(raw)
+        for name, flag in modes:
+            args = [git_executable(), "--no-pager", "--no-lazy-fetch", "-c", "core.fsmonitor=false",
+                    "-c", "core.untrackedCache=false", "-c", "merge.conflictStyle=merge",
+                    "merge-file", "--stdout", "--marker-size=" + str(size)]
+            if flag:
+                args.append(flag)
+            for label in labels:
+                args.extend(("-L", label.decode("utf-8", "strict")))
+            result = subprocess.run([*args, *(str(path) for path in paths)], cwd=root, env=env,
+                                    capture_output=True, shell=False, timeout=30)
+            _require(len(result.stdout) <= MAX_BYTES, "Git conflict rendering is oversized")
+            if 1 <= result.returncode <= 127 and result.stdout.replace(b"\r\n", b"\n") == current.replace(b"\r\n", b"\n"):
+                return payload, name
+    raise ResolutionError("worktree is not Git's current three-stage rendering")
+
+
+def inspect_blocks(root):
+    return _snapshot(root, blocks=True)[-1]
+
+
+def _choose_blocks(payload, choices):
+    parts, suffix = payload
+    _require(type(choices) is list and len(choices) == len(parts)
+             and all(type(choice) is str and choice in {"ours", "theirs"} for choice in choices),
+             "one explicit ours/theirs choice per conflict block required")
+    return b"".join(part["prefix"] + part[choice] for part, choice in zip(parts, choices)) + suffix
+
+
+def resolve_blocks(root, expected, choices):
+    _require(isinstance(expected, str) and re.fullmatch(r"[0-9a-f]{64}", expected), "exact inspection binding required")
+    root, index, _before, payload, initial = _snapshot(root, blocks=True)
+    _require(initial["binding"] == expected, "stale conflict binding; inspect again")
+    _choose_blocks(payload, choices)
+    lock_path = Path(str(index) + ".lock")
+    descriptor = os.open(lock_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    try:
+        root, _index, before, payload, fresh = _snapshot(root, blocks=True)
+        _require(fresh["binding"] == expected, "stale conflict binding; inspect again")
+        proposed = _choose_blocks(payload, choices)
+        _write_bytes_atomic(root / TARGET, proposed, expected=before)
+    finally:
+        os.close(descriptor)
+        lock_path.unlink()
+    return {**fresh, "status": "resolved", "staged": False, "after_sha256": _hash(proposed)}
+
+
 def main(argv=None):
-    parser = argparse.ArgumentParser(description="Recover only the exact HEAD-side legacy code-map in a current Git conflict.")
+    parser = argparse.ArgumentParser(description="Bounded fixed-target legacy code-map recovery and metadata refresh.")
     parser.add_argument("--root", required=True)
     operations = parser.add_subparsers(dest="operation", required=True)
     operations.add_parser("inspect")
     restore = operations.add_parser("restore-head")
     restore.add_argument("--expected", required=True)
+    operations.add_parser("inspect-claims")
+    refresh = operations.add_parser("refresh-claims")
+    refresh.add_argument("--expected", required=True)
+    refresh.add_argument("--claims", required=True)
+    operations.add_parser("inspect-blocks")
+    resolve = operations.add_parser("resolve-blocks")
+    resolve.add_argument("--expected", required=True)
+    resolve.add_argument("--choices", required=True)
     args = parser.parse_args(argv)
     try:
-        result = inspect(args.root) if args.operation == "inspect" else restore_head(args.root, args.expected)
+        if args.operation == "inspect":
+            result = inspect(args.root)
+        elif args.operation == "restore-head":
+            result = restore_head(args.root, args.expected)
+        elif args.operation == "inspect-claims":
+            result = inspect_claims(args.root)
+        elif args.operation == "refresh-claims":
+            result = refresh_claims(args.root, args.expected, _decode(args.claims.encode("utf-8")))
+        elif args.operation == "inspect-blocks":
+            result = inspect_blocks(args.root)
+        else:
+            result = resolve_blocks(args.root, args.expected, _decode(args.choices.encode("utf-8")))
     except (OSError, ValueError, RuntimeError, ArtifactError, subprocess.SubprocessError):
         print("context conflict recovery refused: absent, changed, unsafe or unsupported conflict evidence", file=sys.stderr)
         return 1

package/plugins/ca-pi/hooks/_host.py

@@ -11,7 +11,7 @@ import hostapi  # noqa: E402
 class PiHost(hostapi.Host):
     name = "pi"
     adapter_name = "@arbiterforge/ca-pi"
-    adapter_version = "0.17.6"
+    adapter_version = "0.17.8"
     update_target = "ca-pi"
     update_tag_prefix = "ca-pi-v"
     update_command = "pi update npm:@arbiterforge/ca-pi"

package/plugins/ca-pi/hooks/hostapi.py

@@ -313,7 +313,7 @@ class Host:
 
     name = "claude"
     adapter_name = "ca"
-    adapter_version = "2.25.5"
+    adapter_version = "2.25.7"
 
     # Update-notifier descriptor. Each independently versioned host overrides
     # these three values in its per-plugin _host.py. Keeping the target,

package/plugins/ca-pi/hooks/resolve-context-conflict.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-# codeArbiter — sanctioned fixed-target legacy context conflict recovery.
+# codeArbiter — sanctioned fixed-target legacy recovery and metadata refresh.
 
 from _contextmergelib import main
 

package/plugins/ca-pi/package.json

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

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

@@ -114,6 +114,31 @@ Run an **incremental re-scout for each affected document**, scoped to its select
 - **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.
 
+For reviewed legacy code-map metadata, use the shipped fixed-target helper at
+`<plugin-root>/hooks/resolve-context-conflict.py`. Run `--root "<project-root>"
+inspect-claims`, then `--root "<project-root>" refresh-claims --expected <binding>
+--claims <json-array>` with one to four reviewed records containing exactly
+`field`, `before`, and `after`. The supported existing fields are `ca_version`,
+`codex_version`, `pi_version`, and `metadata_date`. Use the inspection's exact
+current claim as `before`; a version's `after` must match its fixed source
+manifest, and the date must match `inspection_date`. Select the interpreter once
+by presence and use it for both calls; never retry a failed operation under
+another interpreter.
+
+This operation requires resolved, tracked legacy schema-1 document/provenance
+and no native or uncertain journal ownership. It binds document, provenance,
+Git/index, source manifest bytes and date, preserves all unselected bytes, and
+does not stage, rebaseline, adopt, enroll or create a native receipt. Inspect the
+worktree diff for `.codearbiter/code-map.md`, selectively stage that explicit
+path, and re-run the normal secrets scan over the newly staged Markdown before
+Phase 6. Treat it as a heal-proposed doc/code-map edit in Phase 6 review, never as
+a silent rebaseline, and retain its explicit inclusion in Phase 7. Provenance
+rebaseline remains separately scoped by Phase 5.5. Unsupported
+claims or refused preimages stop the edit; do not substitute a direct write or
+native adoption. A codeArbiter contributor may exercise the tested and
+independently reviewed canonical helper under `core/pysrc/` with live enforcement
+intact, never a copied script, installed-cache edit or hook/trust change.
+
 ## Phase 6 — Diff review · gate: BLOCK
 
 Read the complete staged diff (`git diff --cached`). Flag as blocking:

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

@@ -241,6 +241,17 @@ resume condition when applicable. Distinguish an executed check from a proposed
 command and a recommended handoff from a completed operation. Keep the actual
 diagnosis-only or repair-requested caller scope visible throughout.
 
+Before assembling a handoff or invoking its validator, read the installed
+packet preparation guide at `<plugin-root>/routines/debug/references/preparation.md`,
+field reference at `<plugin-root>/routines/debug/references/handoff.md`, and
+JSON Schema at `<plugin-root>/routines/debug/references/debug-handoff.schema.json`.
+Use the linked minimal unresolved example to learn the closed field shapes;
+its synthetic observations are never evidence for the current case. In
+particular, `case_id` must match `DBG-[A-Za-z0-9][A-Za-z0-9_-]{2,63}`.
+Resolve these references from the loaded trusted package. If they are absent,
+stop validated transfer and report the missing resource; do not guess a shape
+or use the one-shot validator to discover fields by trial and error.
+
 For a handoff, assemble the transient `codearbiter.debug-handoff/1.0.0` packet
 from the observations actually in hand. Preserve symptom, expectation and its
 citations, reproduction state and limitations, evidence observations and

package/plugins/ca-pi/routines/debug/references/minimal-unresolved.json

@@ -0,0 +1,58 @@
+{
+  "protocol": "codearbiter.debug-handoff/1.0.0",
+  "case_id": "DBG-example-unresolved",
+  "request": {
+    "intent": "diagnosis_only",
+    "request_ref": "example:synthetic-request",
+    "scope": "Synthetic documentation example only.",
+    "restrictions": ["No repair or external operations."]
+  },
+  "snapshots": [],
+  "symptom": {
+    "observed": "An example operator reports a timeout without an accessible trace.",
+    "expected": null,
+    "expected_evidence_ids": []
+  },
+  "reproduction": {
+    "status": "not_yet_reproduced",
+    "recipe": null,
+    "evidence_ids": [],
+    "limitations": "No runtime was exercised; this is a synthetic example."
+  },
+  "hypotheses": [],
+  "checks": [],
+  "evidence": [
+    {
+      "id": "E-01",
+      "kind": "user_report",
+      "snapshot_id": null,
+      "locator": "example:synthetic-request",
+      "observation": "The example operator reports a timeout.",
+      "observed_at": null,
+      "check_id": null,
+      "coverage": "unknown",
+      "limitations": "Synthetic report; no independent execution evidence."
+    }
+  ],
+  "disposition": {
+    "kind": "unresolved",
+    "rationale": "The failure trace is unavailable; no cause is established.",
+    "evidence_ids": ["E-01"],
+    "cause_ids": [],
+    "blockers": [
+      {
+        "kind": "evidence",
+        "missing": "The trace from the reported failing attempt.",
+        "owner": null,
+        "resume_condition": "A sanitized trace bound to that attempt is available."
+      }
+    ]
+  },
+  "regression": null,
+  "next_step": {
+    "target": "evidence",
+    "owner": null,
+    "action": "Identify the trace owner and obtain the missing observation.",
+    "completion_evidence": "A sanitized trace bound to the reported failing attempt."
+  }
+}

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

@@ -0,0 +1,41 @@
+# Prepare a debug handoff before validation
+
+Read the installed field reference at `<plugin-root>/routines/debug/references/handoff.md`
+and JSON Schema at `<plugin-root>/routines/debug/references/debug-handoff.schema.json`
+before assembling the packet. Both are generated from the validator's finite
+model. Every declared field is required, including nullable fields; objects
+reject extra fields. Use `null` for an unknown nullable value and the declared
+empty array where allowed. Do not use an empty string in place of unknown text.
+
+The minimal unresolved example at `<plugin-root>/routines/debug/references/minimal-unresolved.json`
+is a synthetic shape example with no runtime proof or repair authority. Read it
+as data. Build the current case from actual observations and their limitations;
+do not submit the example as a real diagnosis or copy its evidence claims.
+
+These scalar shapes often cause preventable rejection:
+
+| Field | Required shape |
+|---|---|
+| `case_id` | `DBG-[A-Za-z0-9][A-Za-z0-9_-]{2,63}`, matched in full |
+| Snapshot, evidence, hypothesis, check IDs | `S-`, `E-`, `H-`, `C-` followed by 2–4 ASCII digits |
+| `snapshot.commit` | `null` or 40/64 lowercase hexadecimal digits |
+| `snapshot.fingerprint` | `null` or `sha256:` followed by 64 lowercase hexadecimal digits |
+| `snapshot.fingerprint_recipe` | `null` or `[a-z][a-z0-9-]{0,63}/[1-9][0-9]{0,3}` |
+| `recipe.preconditions` | One nonblank string, at most 1,000 characters |
+| `check.exit_code` | `null` or a JSON integer, never a boolean |
+
+Choose enums from the reference exactly. For example, hypothesis status is
+`supported`, `refuted`, or `inconclusive`; reproduction status is `reproduced`,
+`intermittent`, `not_yet_reproduced`, `unsafe_to_replay`, or `unavailable`.
+Cross-record IDs must resolve to records in this packet. A shape-valid packet
+can still fail the validator's semantic rules. Schema inspection proves
+neither the diagnosis nor the caller's authority.
+
+Measure the finished candidate's UTF-8 byte count before the first invocation.
+The limit is 65,536 bytes. Prepare and, if needed, compact the candidate before
+validation, retaining all evidence required by its claims. Then invoke the
+installed helper once as the debug owner directs. A rejected packet stays
+rejected. Keep the bounded error code and field path; do not rewrite and
+resubmit it, retry through another interpreter, or use an alternate validator
+as an acceptance path. Existing logs and observations remain evidence inputs;
+rejection does not authorize an unvalidated repair handoff.

package/plugins/ca-pi/routines/finishing-a-development-branch/SKILL.md

@@ -168,6 +168,23 @@ cache edit or hook/trust change is permitted. Native context writer/adoption
 qualification remains unchanged. Re-run the current-head review and CI
 requirements after integration; previous green evidence does not bind new code.
 
+For an explicitly selected per-block resolution, use the same shipped helper
+with `--root "<project-root>" inspect-blocks`, then `--root "<project-root>"
+resolve-blocks --expected <binding> --choices <json-array>`. Review each block
+and supply exactly one `"ours"` or `"theirs"` choice in its displayed order. The
+inspection returns the block count and side hashes; read the conflict document
+to review the actual text. This is a separate operation: `restore-head` keeps
+its original single-block exact-HEAD contract.
+
+The explicit resolver binds the actual current merge and all three index
+stages, and requires Git to reproduce the complete worktree rendering in merge,
+diff3 or zdiff3 form. It supports at most 32 blocks and preserves every
+unconflicted byte, including incoming rows. Changed or foreign worktree text,
+native/uncertain ownership, malformed choices and unsupported renderings refuse
+without staging or changing other files. It leaves every index entry untouched;
+review the result and stage through the existing lane. The same interpreter,
+contributor-source, native-qualification and no-bypass requirements above apply.
+
 ### Open-PR procedure
 
 Run this procedure only for the selected open-PR or merge-via-PR action, after the

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

@@ -114,6 +114,31 @@ Run an **incremental re-scout for each affected document**, scoped to its select
 - **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.
 
+For reviewed legacy code-map metadata, use the shipped fixed-target helper at
+`<plugin-root>/hooks/resolve-context-conflict.py`. Run `--root "<project-root>"
+inspect-claims`, then `--root "<project-root>" refresh-claims --expected <binding>
+--claims <json-array>` with one to four reviewed records containing exactly
+`field`, `before`, and `after`. The supported existing fields are `ca_version`,
+`codex_version`, `pi_version`, and `metadata_date`. Use the inspection's exact
+current claim as `before`; a version's `after` must match its fixed source
+manifest, and the date must match `inspection_date`. Select the interpreter once
+by presence and use it for both calls; never retry a failed operation under
+another interpreter.
+
+This operation requires resolved, tracked legacy schema-1 document/provenance
+and no native or uncertain journal ownership. It binds document, provenance,
+Git/index, source manifest bytes and date, preserves all unselected bytes, and
+does not stage, rebaseline, adopt, enroll or create a native receipt. Inspect the
+worktree diff for `.codearbiter/code-map.md`, selectively stage that explicit
+path, and re-run the normal secrets scan over the newly staged Markdown before
+Phase 6. Treat it as a heal-proposed doc/code-map edit in Phase 6 review, never as
+a silent rebaseline, and retain its explicit inclusion in Phase 7. Provenance
+rebaseline remains separately scoped by Phase 5.5. Unsupported
+claims or refused preimages stop the edit; do not substitute a direct write or
+native adoption. A codeArbiter contributor may exercise the tested and
+independently reviewed canonical helper under `core/pysrc/` with live enforcement
+intact, never a copied script, installed-cache edit or hook/trust change.
+
 ## Phase 6 — Diff review · gate: BLOCK
 
 Read the complete staged diff (`git diff --cached`). Flag as blocking:

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

@@ -241,6 +241,17 @@ resume condition when applicable. Distinguish an executed check from a proposed
 command and a recommended handoff from a completed operation. Keep the actual
 diagnosis-only or repair-requested caller scope visible throughout.
 
+Before assembling a handoff or invoking its validator, read the installed
+packet preparation guide at `<plugin-root>/routines/debug/references/preparation.md`,
+field reference at `<plugin-root>/routines/debug/references/handoff.md`, and
+JSON Schema at `<plugin-root>/routines/debug/references/debug-handoff.schema.json`.
+Use the linked minimal unresolved example to learn the closed field shapes;
+its synthetic observations are never evidence for the current case. In
+particular, `case_id` must match `DBG-[A-Za-z0-9][A-Za-z0-9_-]{2,63}`.
+Resolve these references from the loaded trusted package. If they are absent,
+stop validated transfer and report the missing resource; do not guess a shape
+or use the one-shot validator to discover fields by trial and error.
+
 For a handoff, assemble the transient `codearbiter.debug-handoff/1.0.0` packet
 from the observations actually in hand. Preserve symptom, expectation and its
 citations, reproduction state and limitations, evidence observations and

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

@@ -27,12 +27,50 @@ An initialized refresh is routed through `/ca-status drift` and the existing
 `context-check` owner after an explicit scoped or full selection; `--brownfield`
 keeps its initial-population lock.
 
+### Brownfield host prerequisites
+
+For repositories with existing source, every scaffold and populator step in
+the Procedure below is conditional on observing these prerequisites first.
+This applies to both `--brownfield` and the default auto-detection route.
+When qualification is unavailable or unknown, stop here and issue the handoff
+described below. Do not execute the later Procedure steps or enter brownfield
+population through the When NOT to use section.
+
+Scaffolding enables governance and may install Git hooks before population.
+It does not qualify the host for context extraction. Before selecting
+`--brownfield` or automatically routing existing source to brownfield
+population, inspect the installed
+context-creation containment profile in
+`<plugin-root>/routines/context-creation/SKILL.md`, under that exact heading.
+The active host needs an observed context-specific child profile with enforced
+read-only containment and report delivery, plus the existing native context
+writer and approval support. Ordinary unrestricted collaboration agents on
+Codex desktop/Windows do not satisfy that requirement. The repository-only
+Claude preparation fixture is neither a shipped consumer route nor proof of
+a qualified host.
+
+When these prerequisites are unavailable or unknown, report the missing
+capability before invoking the scaffolder. Keep a fresh repository unactivated
+and retain every byte of any existing partial state. Name the loaded package,
+actual host limitation, selected population route and next missing prerequisite
+in the handoff; leave unobserved qualification and prior operation identities
+unknown. Resume on a host only after fresh containment and writer qualification,
+using the existing interrupted-population recovery procedure. No supported
+destination is implied by this guidance.
+
+This is a workflow preflight. The low-level scaffolder has no native scout
+capability attestation input and does not enforce or prove this assessment.
+Its successful exit, `--check` inventory or enabled stub never establishes
+population readiness. Do not fabricate a profile, receipt, context document
+or initialization sentinel to pass the later gates.
+
 The two flags are mutually exclusive and neither may combine with `--check`. `--stage N` may
-accompany one only while `.codearbiter/CONTEXT.md` is absent: scaffold at that stage, then enter the
+accompany one only while `.codearbiter/CONTEXT.md` is absent: after any required brownfield preflight,
+scaffold at that stage, then enter the
 selected workflow. When an uninitialized stub already exists, skip the refusing scaffolder and enter
 the selected workflow directly. An initialized marker or source-shape mismatch retains the selected
 legacy workflow's BLOCK. Without an explicit strategy, continue with the unchanged auto-detection
-procedure below.
+procedure below only after any required brownfield preflight.
 <!-- catalog-command-modes:end -->
 
 ## Procedure

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

@@ -168,6 +168,23 @@ cache edit or hook/trust change is permitted. Native context writer/adoption
 qualification remains unchanged. Re-run the current-head review and CI
 requirements after integration; previous green evidence does not bind new code.
 
+For an explicitly selected per-block resolution, use the same shipped helper
+with `--root "<project-root>" inspect-blocks`, then `--root "<project-root>"
+resolve-blocks --expected <binding> --choices <json-array>`. Review each block
+and supply exactly one `"ours"` or `"theirs"` choice in its displayed order. The
+inspection returns the block count and side hashes; read the conflict document
+to review the actual text. This is a separate operation: `restore-head` keeps
+its original single-block exact-HEAD contract.
+
+The explicit resolver binds the actual current merge and all three index
+stages, and requires Git to reproduce the complete worktree rendering in merge,
+diff3 or zdiff3 form. It supports at most 32 blocks and preserves every
+unconflicted byte, including incoming rows. Changed or foreign worktree text,
+native/uncertain ownership, malformed choices and unsupported renderings refuse
+without staging or changing other files. It leaves every index entry untouched;
+review the result and stage through the existing lane. The same interpreter,
+contributor-source, native-qualification and no-bypass requirements above apply.
+
 ### Open-PR procedure
 
 Run this procedure only for the selected open-PR or merge-via-PR action, after the