@arbiterforge/ca-pi 0.17.7 → 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.6" src="https://img.shields.io/badge/version-2.25.6-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.7",
+  "version": "0.17.8",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",

package/plugins/ca-pi/CHANGELOG.md

@@ -4,6 +4,18 @@ 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

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

@@ -37,11 +37,11 @@
   },
   "context_qualification": {
     "darwin/amd64": {
-      "source_commit": "91b2cbba46d29d69ea052019acfabf52dc8e3897",
+      "source_commit": "4c2529e2f3804d38855094e1c11d36178067c826",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38199172149",
+      "run_id": "38219547942",
       "binary_sha256": "5214e1062e49aa39cd73868cd9792e7e296a865bb6e86230b17c19dda1ba3b71",
-      "observation_sha256": "1c6f01fc33af2fabbd15633dbd1f5313208dd6eb754d00a1a17d80287f656a37",
+      "observation_sha256": "fdd1d120d5ad0e4aed101efad7c32aeac561035faf075b70abf3ba5f82a4bc3b",
       "module_sha256": "1aea76bc4dc8b54b368dccc80c3a1133b403b5915018fdcb6018f1a3913fe66c",
       "native_cases": [
         "TestContextBoundedRender",
@@ -53,11 +53,11 @@
       ]
     },
     "darwin/arm64": {
-      "source_commit": "91b2cbba46d29d69ea052019acfabf52dc8e3897",
+      "source_commit": "4c2529e2f3804d38855094e1c11d36178067c826",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38199172149",
+      "run_id": "38219547942",
       "binary_sha256": "dde6deb178a0e725f8a88b1b30fa6980622b8af3b13fb73261aaaea47eb75a38",
-      "observation_sha256": "94f984c74dd5a906bd5ea8ad03c2efe2e561c1e19e3574bb2825e353531c138d",
+      "observation_sha256": "18294ead6b8a48804464f06f1bcc8254e0176c0ac0c48486a121aa1a018a309a",
       "module_sha256": "1aea76bc4dc8b54b368dccc80c3a1133b403b5915018fdcb6018f1a3913fe66c",
       "native_cases": [
         "TestContextBoundedRender",
@@ -69,11 +69,11 @@
       ]
     },
     "linux/amd64": {
-      "source_commit": "91b2cbba46d29d69ea052019acfabf52dc8e3897",
+      "source_commit": "4c2529e2f3804d38855094e1c11d36178067c826",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38199172149",
+      "run_id": "38219547942",
       "binary_sha256": "ca2d5e0fecac0c99c45dc7576fff7d56af63dbd85decb4cfc54f81621ac90901",
-      "observation_sha256": "ba2155d373bbfd6e4469aa4e240cb1f06a6ac93823d9b6958ae8c0053a4d4a61",
+      "observation_sha256": "e4717e28c2ca9a27fc278196310a00a3adff09766d307951ba93de57b262f6ab",
       "module_sha256": "1aea76bc4dc8b54b368dccc80c3a1133b403b5915018fdcb6018f1a3913fe66c",
       "native_cases": [
         "TestContextBoundedRender",
@@ -85,11 +85,11 @@
       ]
     },
     "linux/arm64": {
-      "source_commit": "91b2cbba46d29d69ea052019acfabf52dc8e3897",
+      "source_commit": "4c2529e2f3804d38855094e1c11d36178067c826",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38199172149",
+      "run_id": "38219547942",
       "binary_sha256": "de18df4c499814f6ccfc69efa6bfb6f4bbcd37c2af5dd091727233f1aaf91a39",
-      "observation_sha256": "fd52f870338809a6dca3a0f1367130af716fbe463c1f7715e775bed2307508f3",
+      "observation_sha256": "03064179c8e677c66c0c90a2d109b139e5b3bb057fa296d5a9da4946ae26c37c",
       "module_sha256": "1aea76bc4dc8b54b368dccc80c3a1133b403b5915018fdcb6018f1a3913fe66c",
       "native_cases": [
         "TestContextBoundedRender",
@@ -101,11 +101,11 @@
       ]
     },
     "windows/amd64": {
-      "source_commit": "91b2cbba46d29d69ea052019acfabf52dc8e3897",
+      "source_commit": "4c2529e2f3804d38855094e1c11d36178067c826",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38199172149",
+      "run_id": "38219547942",
       "binary_sha256": "ddab696f02b946400feac527f747a020b76dbb9e5dd444b0b7d464acbcd3888e",
-      "observation_sha256": "fcfedfe79d6b914347674538c432dad334da8d06794d138ec295c1568e3ef158",
+      "observation_sha256": "e31ae79bc15c37dbb157c11e5a3775dd0d314350bbf761a968999ba4ffde2d9c",
       "module_sha256": "1aea76bc4dc8b54b368dccc80c3a1133b403b5915018fdcb6018f1a3913fe66c",
       "native_cases": [
         "TestContextBoundedRender",
@@ -117,11 +117,11 @@
       ]
     },
     "windows/arm64": {
-      "source_commit": "91b2cbba46d29d69ea052019acfabf52dc8e3897",
+      "source_commit": "4c2529e2f3804d38855094e1c11d36178067c826",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38199172149",
+      "run_id": "38219547942",
       "binary_sha256": "23689eaa4df71f95bde58b18bc32fab8d4ae709495250ddfd13192fc0427a813",
-      "observation_sha256": "3ea32af39b84aaf1ccfbda2063c2c2c3031f205f838b52e3fc2b03ae00f3e392",
+      "observation_sha256": "e04cb8b45299950247c82557e7aa4c60c4c7b6b9718775b8c3ecaedc1d7bb6fe",
       "module_sha256": "1aea76bc4dc8b54b368dccc80c3a1133b403b5915018fdcb6018f1a3913fe66c",
       "native_cases": [
         "TestContextBoundedRender",

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.7"
+    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.6"
+    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.7",
+  "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