@arbiterforge/ca-pi 0.10.2 → 0.10.5

package/README.md

@@ -10,7 +10,7 @@ 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.17.1" src="https://img.shields.io/badge/version-2.17.1-2b7489">
+<img alt="version 2.17.4" src="https://img.shields.io/badge/version-2.17.4-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-23-555">
 <img alt="agents" src="https://img.shields.io/badge/agents-19-555">
@@ -96,7 +96,9 @@ stability, command syntax, trust, and platform differences.
 | Codex CLI | `ca-codex` | `$ca-feature` | Stable |
 | Pi | `ca-pi` | `/ca-feature` | Feature Forge `preview` |
 
-**Prerequisites:** Python 3 on `PATH` and `git config user.email` set. Pi also requires Node.js
+**Prerequisites:** Python 3 on `PATH` and `git config user.email` set. ADR lifecycle proof requires
+Git 2.45.0+ with `--no-lazy-fetch` on all three governance hosts; unavailable flag support blocks
+verification with an upgrade prerequisite, never an implicit fetch fallback. Pi also requires Node.js
 22.19+. If Python is missing, Pi installs its final wrappers but blocks mutating calls and points to
 `/ca-doctor`; Claude Code and Codex surface an interpreter breadcrumb instead of silently claiming
 governance is active. The [compatibility matrix](https://arbiterforge.github.io/codeArbiter/getting-started/compatibility/)
@@ -115,7 +117,7 @@ Approve the normal plugin trust prompt, open the target repository, and continue
 
 ### Codex CLI
 
-The public GitHub-slug flow is **available now**. The repository currently ships `ca-codex 0.9.1`;
+The public GitHub-slug flow is **available now**. The repository currently ships `ca-codex 0.9.4`;
 the dated end-to-end public-install record discovered `ca-codex 0.2.4` from release `v2.8.13`.
 Current packaging and shared-core parity are continuously verified, while that dated live-install
 record stays labeled rather than being silently promoted to evidence for a newer adapter:

package/package.json

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

package/plugins/ca-pi/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `ca-pi` are documented in this file.
 
 ## [Unreleased]
 
+## [0.10.5] - 2026-09-05
+
+### Fixed
+
+- Upgrade earlier codeArbiter-managed Git hook shims after ownership-banner wording changes while preserving foreign hooks.
+
+## [0.10.4] - 2026-09-05
+
+### Fixed
+
+- Select a history-preserving PR merge when ADR lifecycle evidence binds source commits outside the base branch.
+
+## [0.10.3] - 2026-09-04
+
+### Changed
+
+- Synchronize the shared host kernel's adapter identity metadata with the Claude adapter version.
+
 ## [0.10.2] - 2026-09-03
 
 ### Fixed

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

@@ -0,0 +1,496 @@
+#!/usr/bin/env python3
+"""codeArbiter: pure lifecycle validation and verified-only export helpers.
+
+Shared API: parse_adr, validate_events, validate_source_blobs,
+validate_evidence_sources, append_only_error, and verified_export.
+"""
+
+import datetime as dt
+import hashlib
+import json
+import os
+import re
+
+ADR_RE = re.compile(r"^(\d{4}-.+)\.md$")
+HEX64 = re.compile(r"^[0-9a-f]{64}$")
+HEX40 = re.compile(r"^[0-9a-f]{40}$")
+FRONTMATTER_LINE_RE = re.compile(r"^([a-z][a-z0-9-]*):(?: (.*))?$")
+H1_RE = re.compile(r"^# ADR-\d{4} (?:—|-) .+$")
+H2_RE = re.compile(r"^## (.+)$", re.MULTILINE)
+STATUS_VALUES = {"draft", "proposed", "accepted", "superseded", "rejected"}
+
+
+def _sha(data):
+    return hashlib.sha256(data).hexdigest()
+
+
+def _normalized_text(blob):
+    return bytes(blob).decode("utf-8").replace("\r\n", "\n").replace("\r", "\n")
+
+
+def parse_adr(blob):
+    """Strictly parse one ADR and return status, sections, and bound bytes."""
+    text = _normalized_text(blob)
+    if not text.startswith("---\n"):
+        raise ValueError("ADR has no opening frontmatter delimiter")
+    end = text.find("\n---\n", 4)
+    if end < 0:
+        raise ValueError("ADR has no closing frontmatter delimiter")
+    front_text = text[4:end]
+    body = text[end + 5:]
+    fields = {}
+    retained_front = []
+    for line in front_text.split("\n"):
+        if not line:
+            raise ValueError("blank or malformed frontmatter line")
+        match = FRONTMATTER_LINE_RE.fullmatch(line)
+        if not match:
+            raise ValueError("malformed frontmatter line %r" % line)
+        key, value = match.groups()
+        if key in fields:
+            raise ValueError("duplicate frontmatter key %s" % key)
+        fields[key] = value or ""
+        if key == "status":
+            retained_front.append("status: <mutable-status>")
+        else:
+            retained_front.append(line)
+    for required in ("status", "date", "title", "decided-by", "supersedes"):
+        if not fields.get(required):
+            raise ValueError("missing frontmatter key %s" % required)
+    if fields["status"].lower() not in STATUS_VALUES:
+        raise ValueError("unsupported ADR status %r" % fields["status"])
+
+    # Both separators are present in accepted history. Bind the exact heading
+    # bytes, but fail closed unless there is exactly one recognized ADR H1.
+    h1_matches = re.findall(r"(?m)^# ADR-\d{4} (?:—|-) .+$", body)
+    if len(h1_matches) != 1 or not H1_RE.fullmatch(h1_matches[0]):
+        raise ValueError("ADR has malformed or missing H1 heading")
+    heading_matches = list(H2_RE.finditer(body))
+    headings = [match.group(1) for match in heading_matches]
+    duplicates = sorted({heading for heading in headings if headings.count(heading) > 1})
+    if duplicates:
+        raise ValueError("duplicate ADR section heading(s): %s" % ", ".join(duplicates))
+    for required in ("Status", "Context", "Decision"):
+        if required not in headings:
+            raise ValueError("ADR has no ## %s section" % required)
+
+    sections = {}
+    status_value_span = None
+    for index, match in enumerate(heading_matches):
+        content_start = match.end()
+        if content_start < len(body) and body[content_start] == "\n":
+            content_start += 1
+        content_end = heading_matches[index + 1].start() if index + 1 < len(heading_matches) else len(body)
+        sections[match.group(1)] = body[content_start:content_end].encode("utf-8")
+        if match.group(1) == "Status":
+            status_text = body[content_start:content_end]
+            status_match = re.match(r"\s*([A-Za-z]+)(?=$|[\s—-])", status_text)
+            if status_match is None or status_match.group(1).lower() not in STATUS_VALUES:
+                raise ValueError("ADR Status section has no recognized status value")
+            if status_match.group(1).lower() != fields["status"].lower():
+                raise ValueError("ADR Status section disagrees with frontmatter status")
+            status_value_span = (
+                content_start + status_match.start(1),
+                content_start + status_match.end(1),
+            )
+    if status_value_span is None or not sections["Status"].strip():
+        raise ValueError("ADR Status section is empty")
+
+    status_start, status_end = status_value_span
+    immutable_text = (
+        "---\n" + "\n".join(retained_front) + "\n---\n" +
+        body[:status_start] + "<mutable-status>" + body[status_end:]
+    )
+    return {"status": fields["status"].lower(), "fields": fields,
+            "sections": sections, "immutable": immutable_text.encode("utf-8")}
+
+
+def immutable_body(blob):
+    """Complete normalized ADR bytes excluding only its parsed status values."""
+    return parse_adr(blob)["immutable"]
+
+
+def obligation_set_digest(obligations):
+    encoded = json.dumps(obligations, sort_keys=True, separators=(",", ":"),
+                         ensure_ascii=False).encode("utf-8")
+    return _sha(encoded)
+
+
+def read_jsonl(path):
+    events = []
+    with open(path, encoding="utf-8") as handle:
+        for number, line in enumerate(handle, 1):
+            if not line.strip():
+                continue
+            try:
+                events.append(json.loads(line))
+            except (TypeError, ValueError) as exc:
+                events.append({"event": "invalid", "_error": "line %d: %s" % (number, exc)})
+    return events
+
+
+def read_adrs(root, errors=None):
+    directory = os.path.join(root, ".codearbiter", "decisions")
+    result = {}
+    for name in sorted(os.listdir(directory)):
+        match = ADR_RE.match(name)
+        if not match:
+            continue
+        path = os.path.join(directory, name)
+        with open(path, "rb") as handle:
+            blob = handle.read()
+        try:
+            parse_adr(blob)
+        except (UnicodeError, ValueError) as exc:
+            if errors is not None:
+                errors.append("%s: %s" % (match.group(1), exc))
+            continue
+        result[match.group(1)] = blob
+    return result
+
+
+def read_accepted_adrs(root, errors=None):
+    return {adr: blob for adr, blob in read_adrs(root, errors=errors).items()
+            if parse_adr(blob)["status"] == "accepted"}
+
+
+def append_only_error(base, current):
+    if bytes(current).startswith(bytes(base)):
+        return None
+    return "adr-lifecycle ledger rewrites or truncates base history"
+
+
+def _parse_time(value):
+    moment = dt.datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    if moment.tzinfo is None or moment.utcoffset() is None:
+        raise ValueError("timestamp has no timezone")
+    return moment
+
+
+def _binding_errors(event, blob):
+    errors = []
+    adr = event.get("adr", "<missing>")
+    try:
+        parsed = parse_adr(blob)
+        body = _sha(parsed["immutable"])
+    except (UnicodeError, ValueError) as exc:
+        errors.append("%s: immutable content unavailable: %s" % (adr, exc))
+        parsed = {"sections": {}}
+    else:
+        if body != event.get("body_sha256"):
+            errors.append("%s: immutable-body digest does not match" % adr)
+    try:
+        _parse_time(event.get("recorded_at"))
+    except (TypeError, ValueError):
+        errors.append("%s: binding has invalid recorded_at" % adr)
+    obligations = event.get("obligations")
+    if not isinstance(obligations, list):
+        errors.append("%s: obligations must be a list" % adr)
+        obligations = []
+    if obligation_set_digest(obligations) != event.get("obligations_sha256"):
+        errors.append("%s: obligation-set digest does not match sealed content" % adr)
+    seen = set()
+    for obligation in obligations:
+        oid = obligation.get("id") if isinstance(obligation, dict) else None
+        if not isinstance(oid, str) or not oid.startswith(adr + "."):
+            errors.append("%s: obligation id %r is not stem-scoped" % (adr, oid))
+            continue
+        if oid in seen:
+            errors.append("%s: duplicate obligation id %s" % (adr, oid))
+        seen.add(oid)
+        section = obligation.get("section")
+        section_bytes = parsed["sections"].get(section) if isinstance(section, str) else None
+        if section_bytes is None:
+            errors.append("%s: obligation %s section binding is absent" % (adr, oid))
+        text = obligation.get("text")
+        if not isinstance(text, str) or not text.strip():
+            errors.append("%s: obligation %s has no bound text" % (adr, oid))
+            continue
+        encoded = text.encode("utf-8")
+        if _sha(encoded) != obligation.get("text_sha256"):
+            errors.append("%s: obligation %s text digest does not match" % (adr, oid))
+        if section_bytes is not None and encoded not in section_bytes:
+            errors.append("%s: obligation %s text violates its section binding" % (adr, oid))
+    return errors
+
+
+def validate_source_blobs(events, source_blobs):
+    """Validate acceptance and migration bindings against committed Git bytes."""
+    errors = []
+    for event in events:
+        if not isinstance(event, dict) or event.get("event") not in ("acceptance", "baseline"):
+            continue
+        adr = event.get("adr")
+        kind = event.get("event")
+        label = "source-commit" if kind == "acceptance" else "migration-snapshot"
+        field = "source_commit" if kind == "acceptance" else "observed_commit"
+        commit = event.get(field)
+        if not isinstance(commit, str) or not isinstance(adr, str):
+            errors.append("%s: %s binding identity is malformed" % (adr, label))
+            continue
+        blob = source_blobs.get((commit, adr))
+        if blob is None:
+            errors.append("%s: %s ADR blob is unavailable" % (adr, label))
+            continue
+        if _sha(blob) != event.get("blob_sha256"):
+            errors.append("%s: %s blob digest does not match" % (adr, label))
+        try:
+            parsed = parse_adr(blob)
+            body_digest = _sha(parsed["immutable"])
+        except (UnicodeError, ValueError) as exc:
+            errors.append("%s: %s immutable content unavailable: %s" % (adr, label, exc))
+        else:
+            if body_digest != event.get("body_sha256"):
+                errors.append("%s: %s immutable-body digest does not match" % (adr, label))
+            if parsed["status"] != "accepted":
+                errors.append("%s: %s ADR status must be accepted" % (adr, label))
+    return errors
+
+
+def _evidence_errors(event, index):
+    errors = []
+    if not isinstance(event.get("event_id"), str) or not event["event_id"].strip():
+        errors.append("line %d: evidence has no event_id" % index)
+    if not HEX40.fullmatch(str(event.get("source_commit", ""))):
+        errors.append("line %d: evidence source_commit must be a 40-character Git id" % index)
+    digests = event.get("input_digests")
+    if not isinstance(digests, dict) or not digests:
+        errors.append("line %d: evidence has no input digests" % index)
+    elif any(not isinstance(path, str) or not path or not HEX64.fullmatch(str(digest))
+             for path, digest in digests.items()):
+        errors.append("line %d: evidence input digests must map paths to SHA-256 values" % index)
+    kind = event.get("event")
+    if kind == "implemented":
+        if not isinstance(event.get("evidence"), str) or not event["evidence"].strip():
+            errors.append("line %d: implementation evidence is missing" % index)
+    if kind == "verified":
+        for field in ("proof_contract", "producer", "command", "observed_at",
+                      "valid_until", "claim"):
+            if not isinstance(event.get(field), str) or not event[field].strip():
+                errors.append("line %d: verified evidence has no %s" % (index, field))
+        if event.get("claim_scope") != "repository":
+            errors.append("line %d: verified evidence claim_scope must be repository" % index)
+        try:
+            observed = _parse_time(event.get("observed_at"))
+            valid_until = _parse_time(event.get("valid_until"))
+            if observed > valid_until:
+                errors.append("line %d: observed_at is after valid_until" % index)
+        except (TypeError, ValueError) as exc:
+            errors.append("line %d: verified evidence timestamp/timezone is invalid: %s" %
+                          (index, exc))
+    return errors
+
+
+def validate_events(events, adr_blobs, require_all_accepted=False):
+    errors = []
+    bindings = {}
+    obligations = {}
+    event_ids = {}
+    implementations = {}
+    for index, event in enumerate(events, 1):
+        if not isinstance(event, dict):
+            errors.append("invalid lifecycle event at entry %d" % index)
+            continue
+        if event.get("_error"):
+            errors.append("invalid lifecycle event: %s" % event["_error"])
+            continue
+        if event.get("schema") != "adr-lifecycle/v1":
+            errors.append("line %d: unsupported schema" % index)
+        kind = event.get("event")
+        adr = event.get("adr")
+        if kind in ("acceptance", "baseline"):
+            if not isinstance(adr, str) or not adr:
+                errors.append("line %d: binding has malformed ADR identity" % index)
+                continue
+            if adr in bindings:
+                errors.append("%s: second acceptance/baseline binding is forbidden" % adr)
+                continue
+            blob = adr_blobs.get(adr)
+            if blob is None:
+                errors.append("%s: binding names no valid ADR" % adr)
+                continue
+            bindings[adr] = event
+            errors.extend(_binding_errors(event, blob))
+            sealed = event.get("obligations_sealed") is True
+            if kind == "acceptance":
+                if not sealed:
+                    errors.append("%s: acceptance obligation set is not sealed" % adr)
+                if sealed and not (isinstance(event.get("obligations"), list)
+                                   and event["obligations"]):
+                    errors.append("%s: sealed acceptance obligation set is empty" % adr)
+                if not HEX40.fullmatch(str(event.get("source_commit", ""))):
+                    errors.append("%s: acceptance source_commit must be a 40-character Git id" % adr)
+                if "observed_commit" in event:
+                    errors.append("%s: acceptance must not use observed_commit" % adr)
+            else:
+                if sealed:
+                    errors.append("%s: legacy baseline must remain unsealed" % adr)
+                if "source_commit" in event:
+                    errors.append("%s: legacy baseline must not fabricate an acceptance commit" % adr)
+                if not HEX40.fullmatch(str(event.get("observed_commit", ""))):
+                    errors.append("%s: baseline observed_commit must be a 40-character Git id" % adr)
+            raw_obligations = event.get("obligations")
+            for item in raw_obligations if isinstance(raw_obligations, list) else []:
+                if isinstance(item, dict) and isinstance(item.get("id"), str):
+                    oid = item["id"]
+                    if oid in obligations:
+                        errors.append("%s: duplicate obligation id %s" % (adr, oid))
+                    obligations[oid] = adr
+        elif kind in ("implemented", "verified"):
+            event_id = event.get("event_id")
+            if not isinstance(event_id, str) or not event_id:
+                errors.append("line %d: evidence has no event_id" % index)
+            elif event_id in event_ids:
+                errors.append("line %d: duplicate event_id %r" % (index, event_id))
+            else:
+                event_ids[event_id] = kind
+            oid = event.get("obligation")
+            if not isinstance(oid, str):
+                errors.append("line %d: evidence has malformed obligation identity" % index)
+                continue
+            if oid not in obligations:
+                errors.append("line %d: evidence names undeclared obligation %r" % (index, oid))
+            elif adr != obligations[oid]:
+                errors.append("line %d: evidence ADR does not own obligation %r" % (index, oid))
+            key = (adr, oid)
+            if kind == "implemented":
+                implementations.setdefault(key, []).append(event)
+            else:
+                prior = implementations.get(key, [])
+                if not prior:
+                    errors.append("line %d: verified evidence appears before implementation for %r" %
+                                  (index, oid))
+                elif event.get("input_digests") != prior[-1].get("input_digests"):
+                    errors.append("line %d: verification input set differs from implementation input digest boundary for %r" %
+                                  (index, oid))
+            errors.extend(_evidence_errors(event, index))
+        elif kind == "invalidated":
+            event_id = event.get("event_id")
+            if not isinstance(event_id, str) or not event_id:
+                errors.append("line %d: invalidation has no event_id" % index)
+            elif event_id in event_ids:
+                errors.append("line %d: duplicate event_id %r" % (index, event_id))
+            else:
+                event_ids[event_id] = kind
+            target = event.get("target_event_id")
+            if (not isinstance(target, str) or target not in event_ids or
+                    event_ids.get(target) not in ("implemented", "verified")):
+                errors.append("line %d: invalidation target is missing or not prior evidence" % index)
+            if not isinstance(event.get("reason"), str) or not event["reason"].strip():
+                errors.append("line %d: invalidation has no reason" % index)
+            try:
+                _parse_time(event.get("recorded_at"))
+            except (TypeError, ValueError):
+                errors.append("line %d: invalidation has invalid recorded_at" % index)
+        else:
+            errors.append("line %d: unknown event %r" % (index, kind))
+    if require_all_accepted:
+        for adr in sorted(set(adr_blobs) - set(bindings)):
+            errors.append("%s: accepted ADR has no lifecycle binding" % adr)
+    return errors
+
+
+def validate_evidence_sources(events, source_inputs):
+    """Recompute every evidence path digest from its committed Git bytes."""
+    errors = []
+    for event in events:
+        if not isinstance(event, dict) or event.get("event") not in ("implemented", "verified"):
+            continue
+        commit = event.get("source_commit")
+        event_id = event.get("event_id", "<missing>")
+        digests = event.get("input_digests")
+        if not isinstance(digests, dict):
+            continue
+        for path, expected in digests.items():
+            if not isinstance(path, str) or not isinstance(commit, str):
+                errors.append("%s: Git input binding is malformed" % event_id)
+                continue
+            blob = source_inputs.get((commit, path))
+            if blob is None:
+                errors.append("%s: Git input %s is unavailable at %s" % (event_id, path, commit))
+            elif _sha(blob) != expected:
+                errors.append("%s: Git input digest does not match for %s" % (event_id, path))
+    return errors
+
+
+def _inputs_current(event, current_blobs):
+    digests = event.get("input_digests")
+    if not isinstance(digests, dict) or not digests:
+        return False
+    return all(path in current_blobs and current_blobs[path] is not None and
+               _sha(current_blobs[path]) == digest
+               for path, digest in digests.items())
+
+
+def verified_export(events, adr_blobs, current_blobs, now):
+    errors = validate_events(events, adr_blobs)
+    if errors:
+        return [], errors
+    try:
+        moment = _parse_time(now)
+    except (TypeError, ValueError) as exc:
+        return [], ["export time/timezone is invalid: %s" % exc]
+    bindings = {event.get("adr"): event for event in events
+                if event.get("event") in ("acceptance", "baseline")}
+    invalidated = {event.get("target_event_id") for event in events
+                   if event.get("event") == "invalidated"}
+    exported = []
+    suppressed = set()
+    for adr, binding in sorted(bindings.items()):
+        if parse_adr(adr_blobs[adr])["status"] != "accepted":
+            errors.append("%s: current ADR status is not accepted; no Verified export" % adr)
+            suppressed.add(adr)
+            continue
+        if not binding.get("obligations_sealed"):
+            errors.append("%s: obligation set is unsealed; no Verified export" % adr)
+            suppressed.add(adr)
+            continue
+        for obligation in binding.get("obligations", []):
+            oid = obligation["id"]
+            impls = [event for event in events if event.get("event") == "implemented"
+                     and event.get("adr") == adr and event.get("obligation") == oid
+                     and event.get("event_id") not in invalidated]
+            proofs = [event for event in events if event.get("event") == "verified"
+                      and event.get("adr") == adr and event.get("obligation") == oid
+                      and event.get("event_id") not in invalidated]
+            implementation = next(
+                (event for event in reversed(impls) if _inputs_current(event, current_blobs)), None)
+            proof = next(
+                (event for event in reversed(proofs)
+                 if _inputs_current(event, current_blobs)
+                 and _parse_time(event["observed_at"]) <= moment <= _parse_time(event["valid_until"])),
+                None)
+            if implementation is None:
+                errors.append("%s: no current implementation evidence; implementation input digest is missing or stale" % oid)
+                suppressed.add(adr)
+                continue
+            if proof is None:
+                current_proofs = [event for event in proofs
+                                  if _inputs_current(event, current_blobs)]
+                if current_proofs and all(
+                        moment > _parse_time(event["valid_until"])
+                        for event in current_proofs):
+                    errors.append("%s: no current verification evidence; all current-input evidence expired or was invalidated" % oid)
+                elif current_proofs and all(
+                        moment < _parse_time(event["observed_at"])
+                        for event in current_proofs):
+                    errors.append("%s: verification evidence is not yet observable" % oid)
+                else:
+                    errors.append("%s: no current verification evidence; verification input digest is missing or stale" % oid)
+                suppressed.add(adr)
+                continue
+            if proof.get("input_digests") != implementation.get("input_digests"):
+                errors.append("%s: implementation/verification input boundary differs" % oid)
+                suppressed.add(adr)
+                continue
+            exported.append({
+                "adr": adr, "obligation": oid, "claim": proof["claim"],
+                "claim_scope": proof["claim_scope"], "source_commit": proof["source_commit"],
+                "input_digests": proof["input_digests"],
+                "proof_contract": proof["proof_contract"], "producer": proof["producer"],
+                "command": proof["command"], "observed_at": proof["observed_at"],
+                "valid_until": proof["valid_until"],
+            })
+    # A verified report is aggregate per ADR over that ADR's complete sealed set.
+    # Never leak a partial set for one ADR or let it hide another complete ADR.
+    return [row for row in exported if row["adr"] not in suppressed], errors

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

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""codeArbiter: root-bound, committed lifecycle proof shared by CI and installs.
+
+API: read_committed_evidence, validate_committed_sources, source_ancestry,
+merge_method. No working-tree fallback, pending-packet allowance, or network.
+"""
+
+import json
+import subprocess
+
+import _adrlifecycle as al
+from _gitexec import git_executable, root_bound_git_env
+
+LEDGER_REL = ".codearbiter/decisions/adr-lifecycle.jsonl"
+
+
+class GitPrerequisiteError(Exception):
+    """The selected Git cannot provide the required offline proof boundary."""
+
+
+def _git(root, *args):
+    prerequisite = ("ADR lifecycle proof requires Git 2.45.0+ with --no-lazy-fetch; "
+                    "upgrade the selected Git executable. Proof is never retried without that flag.")
+    try:
+        executable = git_executable()
+        env = root_bound_git_env()
+        result = subprocess.run(
+            [executable, "--no-replace-objects", "--no-lazy-fetch", "-C", root, *args],
+            capture_output=True, check=False, env=env)
+        if result.returncode:
+            # Diagnose the actual safety capability, not localized error text or
+            # a version string. This probe reads no repository and never retries
+            # the failed proof command with its network protection removed.
+            capability = subprocess.run(
+                [executable, "--no-lazy-fetch", "--version"],
+                capture_output=True, check=False, env=env)
+            if capability.returncode:
+                raise GitPrerequisiteError(prerequisite)
+    except (OSError, RuntimeError) as exc:
+        raise GitPrerequisiteError(prerequisite) from exc
+    return result
+
+
+def _git_blob(root, commit, path):
+    if not isinstance(commit, str):
+        return None
+    resolved = _git(root, "rev-parse", "--verify", "--end-of-options", "%s^{commit}" % commit)
+    if resolved.returncode != 0:
+        return None
+    result = _git(root, "show", "%s:%s" % (commit, path))
+    return result.stdout if result.returncode == 0 else None
+
+
+def _ledger_at(root, commit):
+    entry = _git(root, "ls-tree", "--name-only", commit, LEDGER_REL)
+    if entry.returncode != 0:
+        raise ValueError("could not inspect lifecycle ledger at %s" % commit)
+    if not entry.stdout.strip():
+        return None
+    blob = _git_blob(root, commit, LEDGER_REL)
+    if blob is None:
+        raise ValueError("could not read lifecycle ledger at %s" % commit)
+    return blob
+
+
+def source_ancestry(root, events, current_ref, base_ref=None):
+    """Require retained source identities; select a merge that preserves them."""
+    errors = []
+    refs = {}
+    for label, ref in (("current", current_ref), ("base", base_ref)):
+        if ref is None and label == "base":
+            continue
+        if not isinstance(ref, str) or not ref:
+            errors.append("%s ref is not a resolvable commit: %s" % (label, ref))
+            continue
+        resolved = _git(root, "rev-parse", "--verify", "--end-of-options",
+                        "%s^{commit}" % ref)
+        if resolved.returncode:
+            errors.append("%s ref is not a resolvable commit: %s" % (label, ref))
+        else:
+            refs[label] = resolved.stdout.decode("ascii").strip()
+    if errors:
+        return errors, None
+    method = "squash"
+    sources = set()
+    for event in events:
+        if not isinstance(event, dict):
+            continue
+        kind = event.get("event")
+        if kind in ("acceptance", "implemented", "verified"):
+            source = event.get("source_commit")
+        elif kind == "baseline":
+            source = event.get("observed_commit")
+        else:
+            continue
+        if not isinstance(source, str) or not al.HEX40.fullmatch(source):
+            errors.append("lifecycle source commit is malformed")
+            continue
+        sources.add(source)
+    for source in sorted(sources):
+        retained = _git(root, "merge-base", "--is-ancestor", source, refs["current"])
+        if retained.returncode == 1:
+            errors.append("%s: source commit is not an ancestor of current ref" % source)
+        elif retained.returncode:
+            errors.append("%s: could not verify source commit ancestry" % source)
+        if "base" in refs:
+            in_base = _git(root, "merge-base", "--is-ancestor", source, refs["base"])
+            if in_base.returncode == 1:
+                method = "merge"
+            elif in_base.returncode:
+                errors.append("%s: could not verify source commit base ancestry" % source)
+    return errors, None if errors else method
+
+
+
+def read_committed_evidence(root, current_ref):
+    """Read only direct, canonical ADR paths from an exact Git snapshot."""
+    committed = _ledger_at(root, current_ref)
+    if committed is None:
+        raise ValueError("current ref has no lifecycle ledger")
+    events = [json.loads(line) for line in committed.decode("utf-8").splitlines()
+              if line.strip()]
+    tree = _git(root, "ls-tree", "-r", "--name-only", "-z",
+                current_ref, ".codearbiter/decisions/")
+    if tree.returncode:
+        raise ValueError("could not inspect current ADR tree")
+    blobs = {}
+    for path in tree.stdout.decode("utf-8").split("\0"):
+        prefix = ".codearbiter/decisions/"
+        if not path.startswith(prefix):
+            continue
+        name = path[len(prefix):]
+        if "/" in name:
+            continue
+        match = al.ADR_RE.fullmatch(name)
+        if match:
+            blob = _git_blob(root, current_ref, path)
+            if blob is None:
+                raise ValueError("could not read current ADR blob: %s" % path)
+            al.parse_adr(blob)
+            blobs[match.group(1)] = blob
+    return events, blobs, committed
+
+
+def validate_committed_sources(root, events):
+    """Recompute existing source-blob and evidence digests from exact Git bytes."""
+    source_blobs = {}
+    source_inputs = {}
+    for event in events:
+        if not isinstance(event, dict):
+            continue
+        kind = event.get("event")
+        if kind in ("acceptance", "baseline"):
+            commit = event.get("source_commit" if kind == "acceptance" else "observed_commit")
+            adr = event.get("adr")
+            if isinstance(commit, str) and isinstance(adr, str):
+                source_blobs[(commit, adr)] = _git_blob(
+                    root, commit, ".codearbiter/decisions/%s.md" % adr)
+        elif kind in ("implemented", "verified"):
+            commit = event.get("source_commit")
+            digests = event.get("input_digests")
+            if isinstance(digests, dict) and isinstance(commit, str):
+                for path in digests:
+                    if isinstance(path, str):
+                        source_inputs[(commit, path)] = _git_blob(root, commit, path)
+    return (al.validate_source_blobs(events, source_blobs) +
+            al.validate_evidence_sources(events, source_inputs))
+
+
+def merge_method(root, base_ref, current_ref):
+    """Strict portable preflight; inherited baselines are not migration authority."""
+    errors = []
+    refs = []
+    for label, ref in (("base", base_ref), ("current", current_ref)):
+        if not isinstance(ref, str) or not ref:
+            return ["%s ref is not a resolvable commit" % label], None
+        result = _git(root, "rev-parse", "--verify", "--end-of-options", ref + "^{commit}")
+        if result.returncode:
+            return ["%s ref is not a resolvable commit: %s" % (label, ref)], None
+        refs.append(result.stdout.decode("ascii").strip())
+    base, head = refs
+    try:
+        events, blobs, committed = read_committed_evidence(root, head)
+        base_bytes = _ledger_at(root, base)
+        base_events = [json.loads(line) for line in (base_bytes or b"").decode("utf-8").splitlines()
+                       if line.strip()]
+        errors.extend(al.validate_events(events, blobs))
+        bindings = {event.get("adr") for event in events if isinstance(event, dict)
+                    and event.get("event") in ("acceptance", "baseline")
+                    and isinstance(event.get("adr"), str)}
+        errors.extend("%s: accepted ADR has no lifecycle binding" % adr
+                      for adr, blob in sorted(blobs.items())
+                      if al.parse_adr(blob)["status"] == "accepted" and adr not in bindings)
+        if base_bytes is not None:
+            prefix_error = al.append_only_error(base_bytes, committed)
+            if prefix_error:
+                errors.append(prefix_error)
+        # A consumer cannot import this repository's closed migration epoch.
+        # Only exact already-committed base events may carry baseline records.
+        for event in events:
+            if (isinstance(event, dict) and event.get("event") == "baseline"
+                    and event not in base_events):
+                errors.append("%s: new legacy baseline is not permitted by merge preflight"
+                              % event.get("adr"))
+        errors.extend(validate_committed_sources(root, events))
+        ancestry_errors, method = source_ancestry(root, events, head, base)
+        errors.extend(ancestry_errors)
+    except (OSError, RuntimeError, ValueError, UnicodeError) as exc:
+        return ["could not validate committed lifecycle evidence: %s" % exc], None
+    return errors, None if errors else method

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

@@ -117,8 +117,9 @@ from _durabilitylib import is_ephemeral_path
 from _gitexec import (git_executable, root_bound_git_env,
                       trusted_git_executable, trusted_python_executable)
 
-SENTINEL = (
-    "# codeArbiter-managed git hook (#161) — this SHIM is refreshed by any live "
+SENTINEL = "# codeArbiter-managed git hook (#161)"
+SHIM_NOTICE = (
+    "# This SHIM is refreshed by any live "
     "host's session (it is host-neutral, ADR-0014); the plugin-specific enforcer "
     "entries it dispatches to (.git/codearbiter-hooksd/*.path) each self-heal "
     "only on THAT plugin's own next session (#556) — edits here are overwritten."
@@ -581,6 +582,7 @@ def _shim(dropin_dir, phase):
     return (
         "#!/bin/sh\n"
         f"{SENTINEL}\n"
+        f"{SHIM_NOTICE}\n"
         f"D={quote(_shell_path(dropin_dir))}\n"
         f'if [ -e "$D/{_TRUSTED_IDENTITY_FILE}" ] || [ -L "$D/{_TRUSTED_IDENTITY_FILE}" ]; then\n'
         f'  [ -f "$D/{_TRUSTED_IDENTITY_FILE}" ] || exit 1\n'
@@ -860,7 +862,11 @@ def install(root):
         desired = _shim(dropin_dir, phase)
         if os.path.exists(dest):
             existing = _read(dest)
-            if existing is not None and SENTINEL not in existing:
+            lines = existing.splitlines() if existing is not None else []
+            managed = len(lines) >= 2 and lines[0] == "#!/bin/sh" and (
+                lines[1] == SENTINEL or lines[1].startswith(f"{SENTINEL} — ")
+            )
+            if existing is not None and not managed:
                 _warn(f"an existing {phase} hook is not codeArbiter-managed — leaving it "
                       f"untouched. For git-level enforcement, call "
                       f"'{os.path.basename(enforcer)} {phase}' from it (see includes docs).")

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.10.2"
+    adapter_version = "0.10.5"
     update_target = "ca-pi"
     update_tag_prefix = "ca-pi-v"
     update_command = "pi update npm:@arbiterforge/ca-pi"

package/plugins/ca-pi/hooks/adr-merge-method.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+"""codeArbiter: read-only lifecycle merge selector for an installed plugin.
+
+CLI: --root REPO --base-ref COMMIT --current-ref COMMIT --merge-method
+Success emits exactly merge or squash; every unavailable proof fails closed.
+"""
+
+import argparse
+import sys
+
+from _adrlifecyclegit import GitPrerequisiteError, merge_method
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", required=True)
+    parser.add_argument("--base-ref", required=True)
+    parser.add_argument("--current-ref", required=True)
+    parser.add_argument("--merge-method", required=True, action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        errors, method = merge_method(args.root, args.base_ref, args.current_ref)
+    except (GitPrerequisiteError, OSError, RuntimeError, ValueError) as exc:
+        errors, method = ["could not verify lifecycle refs: %s" % exc], None
+    if errors:
+        for error in errors:
+            print("::error::" + error, file=sys.stderr)
+        return 1
+    print(method)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

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

package/plugins/ca-pi/includes/safety-core.md

@@ -52,6 +52,13 @@ The irreversible-action set draws a confirmation even when intent is obvious, be
 confirmation is the gate, not friction: merge to the default branch, branch or worktree
 deletion, release and tag publication, and the logged bypass itself (`/ca-override`).
 
+**Merge-to-default hard gate: ADR source ancestry.** Before composing any merge offer (including
+`/ca-watch`) or performing an authorized merge, load Phase 1 of
+`<plugin-root>/routines/finishing-a-development-branch/SKILL.md` and apply its `--merge-method`
+preflight to the exact fetched base and PR head. Preserve a required true merge and use
+`--match-head-commit`; green CI cannot substitute for source ancestry. Missing evidence blocks the
+offer. This check never authorizes the merge itself.
+
 A parameter is yours to decide only when it is reversible, has one sensible answer, and is
 recorded where the user will review it — an uncertain classification is a fork, and forks are
 asked.

package/plugins/ca-pi/routines/decision-lifecycle/SKILL.md

@@ -81,6 +81,11 @@ that any obligation is Implemented or Verified. When the user explicitly authori
    `recorded_at`, `source_commit`, `blob_sha256`, `body_sha256`, `obligations`,
    `obligations_sha256`, and `obligations_sealed: true`. A second acceptance or baseline binding for
    the same stem is invalid.
+4. Preserve **ADR source ancestry** through delivery. Before opening the PR and again before
+   its merge offer, follow the finishing skill's `--merge-method` preflight on the exact base/head.
+   A source not already in base ancestry requires a true merge commit with `--match-head-commit`;
+   squash or rebase would orphan its identity. Missing source ancestry blocks delivery. Never
+   rewrite the acceptance binding or rely on deleted branch objects remaining remotely fetchable.
 
 The lifecycle ledger is append-only. A legacy accepted ADR receives a `baseline` with no fabricated
 acceptance commit, an `observed_commit` whose Git blob is rechecked as the migration snapshot, an

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

@@ -26,6 +26,27 @@ Assemble the facts the decision needs. Nothing is presented until all are in han
 - **Diff summary** — files changed, insertions/deletions, and the commit list since the base. Read it, do not paraphrase from memory.
 - **Gate results** — `commit-gate` outcome and the `last-checkpoint` record. Surface any open `[NEEDS-TRIAGE]` markers left in the diff as out-of-scope findings.
 - **Plan delta** — when a plan exists, state which plan items the branch satisfied and which remain open. Open items are surfaced, not hidden.
+- **ADR source ancestry** — when `.codearbiter/decisions/adr-lifecycle.jsonl` exists, select
+  the merge method from the exact fetched target commit and PR head commit. Run the installed verifier:
+  `python "<plugin-root>/hooks/adr-merge-method.py" --root "<project-root>" --base-ref <base-sha> --current-ref <head-sha> --merge-method`.
+  It validates committed lifecycle evidence and prints `merge` if any bound source is absent from
+  the base ancestry, otherwise `squash`. Every acceptance/evidence `source_commit` and baseline
+  `observed_commit` must resolve and be an ancestor of the head; each is checked against the base too.
+  The self-contained verifier reads committed ADR paths and source bytes, checks their digests and
+  status, and enforces the exact ledger prefix. It admits no baseline newly introduced after the base;
+  an inherited baseline is not authorization for another migration. No repository-local verifier,
+  dirty working-tree bytes, or network fallback can substitute for this proof.
+  ADR lifecycle proof requires Git 2.45.0+ with `--no-lazy-fetch`. The verifier enforces that flag
+  capability and reports an upgrade prerequisite when unavailable. Missing objects block verification;
+  neither failure triggers a retry that fetches proof implicitly.
+  An unavailable verifier, malformed record, missing object, or source outside head ancestry blocks
+  the offer. Never infer retention from local object availability or remote branch/PR refs.
+  A source absent from base requires a true merge commit; squash and rebase would lose its identity.
+  Record the exact base, head, and selected method in the PR body. If merge commits are unavailable,
+  STOP and surface the conflict; do not change repository settings or rewrite the ledger.
+  Revalidate immediately before a merge offer or authorized merge, and use
+  `gh pr merge <PR> --merge --match-head-commit <head-sha>` when `merge` is required.
+  If all sources are already in base ancestry, retain the project's usual merge convention.
 
 Gate: branch confirmed non-default, diff summary read, gate results and plan delta in hand.
 
@@ -49,7 +70,7 @@ Gate: a single terminal option is chosen — by the user under `/feature`, or au
 Carry out the chosen option, and only that one:
 
 - **Open a PR** — push the branch and open the PR against the default branch. The reviewer path-matrix, the anti-slop PR-body composition (description citing the plan items satisfied, the gate results, the §2 conflict level of any non-obvious tradeoff), and the babysitter attach are the steps documented in the `/ca-pr` command flow (`<plugin-root>/skills/ca-pr/SKILL.md`) — **execute those steps here; do not re-invoke `/ca-pr`** (under `/sprint` this skill is reached via `commit-gate`, without the `/pr` command ever running, so a route back would loop). Leave the PR open; the merge is not yours to take.
-- **Merge via PR** — open the PR as above, confirm its checks are green, then merge it through the PR (squash or merge per project convention) so the work lands. Never push to the default branch directly, never force-push.
+- **Merge via PR** — open the PR as above, confirm its checks are green, revalidate Phase 1's ADR source ancestry and exact base/head, then merge it through the PR with the selected method and `--match-head-commit`. Never push to the default branch directly, never force-push.
 - **Discard** — requires explicit user confirmation naming the branch. Before discarding, verify the branch is fully pushed; if any commit is un-pushed, STOP and report exactly what would be lost — never delete un-pushed work silently. Discard proceeds only after the user confirms with that loss in view.
 
 Gate: the chosen option completed — for open-PR a PR exists against the default branch; for merge the work landed through that PR; for discard the user confirmed against a stated loss summary.