@arbiterforge/ca-pi 0.6.0

package/plugins/ca-pi/hooks/post-write-edit.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+# codeArbiter v2 — PostToolUse(Write|Edit) reminders. Scope-touch nudges.
+# Python port of post-write-edit.sh (#25): no jq, fails loud.
+#
+# These are advisory (non-blocking) nudges fired right after a write. The
+# load-bearing crypto/secret ENFORCEMENT is the blocking pre-commit gate in
+# pre-bash.py (H-09b/H-10b); these reminders surface the touch early so the gate
+# isn't a surprise at commit time. Kept: H-07 (dependency review), H-09 (crypto),
+# H-10 (secret). Added: H-12 (file governed by an ADR with a `governs:` field).
+
+import fnmatch
+import json
+import os
+import re
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import hostapi  # noqa: E402 — host seam (ADR-0011)
+import _entrylib  # noqa: E402 — shared run() dispatch (jscpd dedup)
+from _hooklib import (  # noqa: E402
+    CRYPTO_RE, SECRET_RE, arbiter_active, get_host, is_ci_path, is_deploy_path,
+    project_root, read_input, remind, repo_rel, set_host, utf8_stdio,
+)
+from _sloplib import find_prose_separator_dashes, in_antislop_doc_scope  # noqa: E402
+
+DEP_MANIFEST_RE = re.compile(
+    r"(package\.json|package-lock\.json|yarn\.lock|pnpm-lock\.yaml|requirements\.txt"
+    r"|pyproject\.toml|go\.mod|Cargo\.toml)$"
+)
+
+# Narrow, high-signal auth patterns for the H-17 advisory (#73). Deliberately
+# tight — auth has no clean deterministic trigger, so this nudges on the
+# unmistakable markers (passport, jwt verify/sign, framework guards/decorators,
+# common auth middleware names) rather than every mention of "login"/"session",
+# which would be noise. Advisory only: there is no auth commit gate.
+AUTH_RE = re.compile(
+    r"(passport\.(?:authenticate|use)"
+    r"|\bjsonwebtoken\b|jwt\.(?:verify|sign)"
+    r"|@(?:UseGuards|CanActivate|Authorize|RequireAuth)\b"
+    r"|\b(?:AuthGuard|requireAuth|isAuthenticated|authenticateUser|withAuth)\b"
+    r"|@login_required\b)",
+    re.I,
+)
+
+GOVERNS_RE = re.compile(r"^governs:\s*(.+)$", re.I)
+TITLE_RE = re.compile(r"^title:\s*(.+)$", re.I)
+STATUS_RE = re.compile(r"^status:\s*(.+)$", re.I)
+
+
+def adr_identifier(filename):
+    """The ADR identifier for `filename` — its filename STEM, not its number.
+
+    `0014-githook-shim-dropin-fail-closed.md` → `0014-githook-shim-dropin-fail-closed`.
+
+    #416: two ADRs in this repo share the number 0014, so the old
+    `filename.split("-")[0]` derivation collapsed two distinct decisions onto one
+    id and nudged "governed by ADR-0014" without saying which. The stem is unique
+    by construction, so keying on it makes the collision unrepresentable.
+
+    Deliberately mirrored in _readinjectlib.py — the two indexers are separate
+    payload files that cannot import each other's private helpers; the shared
+    contract test (.github/scripts/test_adr_identity.py) pins them to the same
+    answer so the derivation cannot drift apart again.
+    """
+    return os.path.splitext(str(filename))[0]
+
+
+# Bumped whenever the SHAPE or the derivation of a cached index entry changes.
+# The mtime stamp alone only invalidates on an ADR edit, so without this a
+# payload upgrade would keep serving pre-#416 numeric ids out of an already-
+# written cache until someone happened to touch a decisions/ file.
+GOVERNS_CACHE_SCHEMA = 2
+
+
+def governs_index(root):
+    """path-glob → ADR map from decisions/ frontmatter, cached against the
+    directory's latest mtime so the scan doesn't repeat on every write."""
+    ddir = os.path.join(root, ".codearbiter", "decisions")
+    if not os.path.isdir(ddir):
+        return []
+    files = [f for f in os.listdir(ddir) if re.match(r"[0-9]+-.+\.md$", f)]
+    if not files:
+        return []
+    stamp = max(os.path.getmtime(os.path.join(ddir, f)) for f in files)
+    cache_path = os.path.join(root, ".codearbiter", ".markers", "governs-cache.json")
+    try:
+        with open(cache_path, encoding="utf-8") as f:
+            cache = json.load(f)
+        if (cache.get("stamp") == stamp
+                and cache.get("schema") == GOVERNS_CACHE_SCHEMA):
+            return cache.get("index", [])
+    except Exception:  # noqa: BLE001 — absent/corrupt cache just rebuilds
+        pass
+
+    index = []
+    for fn in files:
+        title, status, globs = fn, "", []
+        try:
+            with open(os.path.join(ddir, fn), encoding="utf-8", errors="replace") as f:
+                for i, ln in enumerate(f):
+                    if i > 25:
+                        break
+                    if m := GOVERNS_RE.match(ln.strip()):
+                        globs = [g.strip() for g in m.group(1).split(",") if g.strip()]
+                    elif m := TITLE_RE.match(ln.strip()):
+                        title = m.group(1).strip()
+                    elif m := STATUS_RE.match(ln.strip()):
+                        status = m.group(1).strip().lower()
+        except Exception:  # noqa: BLE001
+            continue
+        if globs and status not in ("superseded", "rejected"):
+            adr = adr_identifier(fn)
+            index.append({"adr": adr, "title": title, "globs": globs})
+    try:
+        os.makedirs(os.path.dirname(cache_path), exist_ok=True)
+        with open(cache_path, "w", encoding="utf-8") as f:
+            json.dump({"stamp": stamp, "schema": GOVERNS_CACHE_SCHEMA,
+                       "index": index}, f)
+    except Exception:  # noqa: BLE001 — cache is an optimization, never required
+        pass
+    return index
+
+
+def _remind_op(root, op):
+    """Run every advisory nudge against ONE canonical file op
+    (hostapi.Host.iter_file_ops, ADR-0011 M2). Under Claude Code this receives
+    exactly the one op its Write/Edit payload maps to — op["added_text"] is
+    content-or-new_string, precisely the pre-seam `ti.get("content") or
+    ti.get("new_string")` read — so the Claude reminder path is unchanged. A
+    Codex apply_patch envelope fans out to one op per touched file, each
+    getting the same per-file nudges over its added lines."""
+    fpath = op.get("file_path", "") or ""
+    content = op.get("added_text") or ""
+
+    # H-12: the touched file is governed by an accepted ADR — surface it so the
+    # recorded decision pushes back at edit time, not at the next checkpoint.
+    rel = repo_rel(fpath, root)
+    if rel:
+        for entry in governs_index(root):
+            if any(fnmatch.fnmatch(rel, g) for g in entry["globs"]):
+                remind("H-12", f"{rel} is governed by ADR-{entry['adr']} ({entry['title']}). "
+                               f"If this change contradicts it, route to "
+                               f"{get_host().cmd_ref('reconcile')} or "
+                               f"{get_host().cmd_ref('adr')} — do not drift silently.")
+                break
+
+    # H-07: dependency manifest changed — review before committing.
+    if DEP_MANIFEST_RE.search(fpath):
+        remind("H-07", "Dependency manifest changed. Dispatch dependency-reviewer before "
+                       "committing (ORCHESTRATOR §5).")
+
+    # H-15: CI/CD workflow touched — advisory (#73). A bad workflow only runs
+    # once merged, so this is a nudge, not a commit gate; dispatch security-reviewer
+    # before the PR merges.
+    if rel and is_ci_path(rel, root):
+        remind("H-15", "CI/CD workflow changed. Dispatch security-reviewer before merging "
+                       "(it reviews workflow/secrets/permissions exposure). Advisory — "
+                       "not a commit block.")
+
+    # H-16: deployment / IaC manifest touched — advisory (#73). IaC bites only on
+    # apply, so this nudges; security-reviewer is the enforcement point at PR.
+    if rel and is_deploy_path(rel, root):
+        remind("H-16", "Deployment/IaC manifest changed. Dispatch security-reviewer before "
+                       "merging (it reviews exposed ports, public ACLs, disabled "
+                       "encryption, privilege). Advisory — not a commit block.")
+
+    # H-17: authentication/authorization logic touched — advisory (#73). Narrow,
+    # high-signal patterns only; the dangerous crypto/secret primitives are still
+    # hard-blocked by H-09b/H-10b at commit time.
+    if AUTH_RE.search(content):
+        remind("H-17", "Auth/authorization logic detected. Dispatch security-reviewer "
+                       "before merging (authn on every protected route; authz at the "
+                       "right layer). Advisory — not a commit block.")
+
+    # H-09: crypto/TLS pattern — the pre-commit gate will BLOCK until the
+    # crypto-compliance gate records a pass; run it now to avoid a commit-time stop.
+    if CRYPTO_RE.search(content):
+        remind("H-09", "Crypto/TLS pattern detected. Run the crypto-compliance check + dispatch "
+                       "auth-crypto-reviewer (no MD5/SHA1/DES/3DES/RC2/RC4/Blowfish; do not disable "
+                       "TLS verification). The commit will block until the gate records a pass.")
+
+    # H-10: possible hardcoded secret.
+    if SECRET_RE.search(content):
+        remind("H-10", "Possible hardcoded secret. Run the secret-handling check before "
+                       "committing. The commit will block until the gate records a pass.")
+
+    # H-13: a user-facing doc was written with an em/en dash used as a prose
+    # separator (anti-slop-design core §3.A, the single highest-signal AI tell).
+    # Advisory nudge to run the copy self-audit before it ships. Scope is community
+    # docs + docs/**, never codeArbiter's own framework bodies (see _sloplib).
+    if rel and in_antislop_doc_scope(rel):
+        hits = find_prose_separator_dashes(content)
+        if hits:
+            shown = ", ".join(str(h["line"]) for h in hits[:5])
+            more = "" if len(hits) <= 5 else f" (+{len(hits) - 5} more)"
+            remind("H-13", f"{rel}: em/en dash used as a prose separator on line(s) "
+                           f"{shown}{more} (anti-slop-design §3.A). Restructure the prose "
+                           f"and run the §3.A/§3.B copy self-audit before committing.")
+
+
+def main():
+    utf8_stdio()
+    root = project_root()
+    if not arbiter_active(root):
+        sys.exit(0)
+    # Host seam (ADR-0011, M2): one canonical op per touched file — exactly one
+    # under Claude Code (verdict-identical to the pre-seam single-payload body),
+    # one per patched file under Codex.
+    for op in get_host().iter_file_ops(read_input()):
+        _remind_op(root, op)
+    sys.exit(0)
+
+
+def run(host, argv=None):
+    """Host-seam entry point (ADR-0011): the __main__ guard calls this with the
+    plugin's loaded Host. Wraps main() unchanged — main() still communicates
+    via sys.exit/stdout/stderr, and its return value stays discarded exactly
+    as the old bare `main()` guard discarded it (so the process still exits 0
+    on a normal fall-through).
+
+    Wires `host` live (#257): primes `_hooklib`'s process-cached Host via
+    `set_host()` BEFORE main() runs, so main()'s `get_host()` call resolves
+    to the SAME instance the caller passed here — no second
+    `hostapi.load_host()`, and `run(fake_host)` genuinely exercises
+    `fake_host`."""
+    return _entrylib.dispatch(host, argv, main, set_host,
+                               pass_argv=False, propagate_result=False)
+
+
+if __name__ == "__main__":
+    sys.exit(run(hostapi.load_host()) or 0)

package/plugins/ca-pi/hooks/pre-bash.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+# codeArbiter v2 — PreToolUse(Bash|PowerShell) guard. Thin entry point (#320):
+# reads stdin, dispatches to _bashguardlib.run_guards() for the actual
+# command-parsing / H-NN gate logic, exit code. Python port of pre-bash.sh
+# (issues #24, #25): no jq, fails loud, blocks via exit 2.
+#
+# All guards run only in arbiter-enabled repos (the plugin.json activation
+# contract); elsewhere this exits 0 immediately.
+
+import os
+import sys
+import traceback
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import hostapi  # noqa: E402 — host seam (ADR-0011)
+import _entrylib  # noqa: E402 — shared run() dispatch (jscpd dedup)
+from _hooklib import (  # noqa: E402
+    arbiter_active, block, get_host, project_root, read_input, set_host,
+    tool_input, utf8_stdio,
+)
+import _bashguardlib  # noqa: E402 — guard logic lives here (#320)
+
+# Backward-compat re-exports: pre-existing tests load this module directly
+# (importlib) and reach into it by name — kept resolving exactly as they did
+# before the #320 extraction, rather than editing those tests.
+#   .github/scripts/test_hook_guards.py: pre_bash._strip_heredoc_bodies,
+#     pre_bash.commit_pathspecs (now _bashguardlib's implementations)
+#   plugins/ca/hooks/tests/test_repo_resolution.py: pre_bash.git_cwd
+_strip_heredoc_bodies = _bashguardlib._strip_heredoc_bodies
+commit_pathspecs = _bashguardlib.commit_pathspecs
+git_cwd = _bashguardlib.git_cwd
+
+
+def _run(root):
+    # tool_input()/get_host() are resolved HERE (module-level names on this
+    # entry file), not inside _bashguardlib, so that
+    # test_guard_crash_failclosed.py's `self.mod.tool_input = <raiser>`
+    # monkeypatch — which replaces the attribute on THIS module object —
+    # still reaches the call (module-level rebinding is invisible to a name
+    # already imported into a different module's namespace).
+    payload = read_input()
+    ti = get_host().normalize_tool_input(payload.get("tool_name", "") or "",
+                                         tool_input(payload))
+    _bashguardlib.run_guards(payload, root, ti)
+
+
+def main():
+    utf8_stdio()
+    root = project_root()
+    if not arbiter_active(root):
+        sys.exit(0)
+    # reliability-002 (#189): everything past this point runs only in an
+    # arbiter-enabled repo, so a dormant/non-codeArbiter repo can never be
+    # bricked by a crash here. An uncaught exception in the scan path below
+    # (H-01/H-03/H-05/H-09b/H-10b/H-11/H-14/H-18/H-19/H-20) must fail CLOSED (exit 2,
+    # a BLOCK) rather than exit 1 — a non-2 exit is a NON-blocking error under
+    # the Claude Code hook contract (_hooklib.py:11-15), which would silently
+    # ALLOW the very tool call this guard exists to scan. read_input()'s
+    # documented fail-OPEN behavior on malformed stdin is unaffected: it catches
+    # its own parse errors internally and returns {} before this wrapper is
+    # ever reached.
+    try:
+        _run(root)
+    except SystemExit:
+        raise
+    except Exception:  # noqa: BLE001 — the fail-closed backstop of last resort
+        traceback.print_exc(file=sys.stderr)
+        block("H-00", "pre-bash guard crashed while scanning this command — failing "
+                      "closed (ORCHESTRATOR §2) rather than silently allowing an "
+                      "unscanned command. See the traceback above; retry, or report it.")
+
+
+def run(host, argv=None):
+    """Host-seam entry point (ADR-0011): the __main__ guard calls this with the
+    plugin's loaded Host. Wraps main() unchanged — main() still communicates
+    via sys.exit/stdout/stderr, and its return value stays discarded exactly
+    as the old bare `main()` guard discarded it (so the process still exits 0
+    on a normal fall-through).
+
+    Wires `host` live (#257): primes `_hooklib`'s process-cached Host via
+    `set_host()` BEFORE main() runs, so main()'s `get_host()` call resolves
+    to the SAME instance the caller passed here — no second
+    `hostapi.load_host()`, and `run(fake_host)` genuinely exercises
+    `fake_host`."""
+    return _entrylib.dispatch(host, argv, main, set_host,
+                               pass_argv=False, propagate_result=False)
+
+
+if __name__ == "__main__":
+    sys.exit(run(hostapi.load_host()) or 0)

package/plugins/ca-pi/hooks/pre-edit.py

@@ -0,0 +1,284 @@
+#!/usr/bin/env python3
+# codeArbiter v2 — PreToolUse(Edit|MultiEdit|NotebookEdit) guard. Activation +
+# audit-log + marker + ADR integrity. Python port of pre-edit.sh (#25): no jq,
+# fails loud, blocks via exit 2.
+#
+# Guards (arbiter-enabled repo only), symlink-resolved via classify_protected
+# (#162 — raw path AND realpath-resolved repo-relative form):
+#   H-18  CONTEXT.md may not be edited to drop `arbiter: enabled` (#159).
+#   H-19  .codearbiter/.markers/* are never edited via the Edit tools (#160).
+#   H-05  audit-log Edits must be pure, tail-anchored appends: old_string must
+#         be the file's REAL current trailing content, new_string must extend
+#         it, and replace_all is rejected outright (reliability-003, #172).
+#   H-11  ADRs under decisions/ are edited only via /adr.
+#   H-22  the protected-state registry (B1/#564): the SAME generic branch as
+#         pre-write.py — marker-gated admits only under a fresh authoring
+#         marker; helper-only and append-only are hard-blocked, no marker
+#         path at all.
+#
+# NotebookEdit is guarded too (a notebook has no append/frontmatter semantics, so
+# a protected target is refused outright) — defense in depth; none of the
+# protected files is a .ipynb, but the tool must not be a hole.
+#
+# Host seam (ADR-0011, #261): this file reasons entirely over the canonical
+# per-file ops from hostapi.Host.iter_file_ops (the same seam pre-write.py
+# already routes through) — it never branches on a native tool name
+# ("MultiEdit", "NotebookEdit"). The properties that used to be read off the
+# raw tool_input (old_string, replace_all, "this is a MultiEdit batch entry",
+# "this is a notebook with no content semantics") are host-neutral op fields
+# (old_string, replace_all, batched, notebook) instead — a future host whose
+# edit tool shares those same shapes gets the same guard semantics without
+# pre-edit.py knowing its tool names.
+
+import os
+import sys
+import traceback
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import hostapi  # noqa: E402 — host seam (ADR-0011)
+import _entrylib  # noqa: E402 — shared run() dispatch (jscpd dedup)
+from _hooklib import (  # noqa: E402
+    MARKER_FRESHNESS_MINUTES, arbiter_active, block, classify_protected,
+    frontmatter_enabled_text, get_host, is_tail_append, marker_fresh,
+    project_root, read_input, set_host, utf8_stdio,
+)
+from _protectedstatelib import (  # noqa: E402
+    ProtectedPolicy, marker_gated_write_admitted, resolve_registered_path,
+)
+
+
+def _read_real_text(root, fpath):
+    """Best-effort current on-disk content of `fpath` (symlink-resolved), or
+    "" if unreadable. Shared by the #159 CONTEXT.md replay and the H-05
+    tail-anchor check (reliability-003, #172) — both need the file's REAL
+    current content, not just an edit op's own old_string, to verify what the
+    edit actually does to the file."""
+    path = fpath if os.path.isabs(fpath) else os.path.join(root, fpath)
+    try:
+        with open(os.path.realpath(path), encoding="utf-8", errors="replace") as f:
+            return f.read()
+    except Exception:  # noqa: BLE001
+        return ""
+
+
+def _resulting_context(root, fpath, ops):
+    """Best-effort resulting content of CONTEXT.md after ALL of `ops` (one or
+    more canonical edit ops targeting the same file — a MultiEdit call fans
+    out to several, applied as one atomic batch) are replayed in order, so
+    the #159 guard can vet whether the FULL call keeps the repo
+    arbiter-enabled. Reads the real (symlink-resolved) file and replays each
+    op's old_string/added_text/replace_all against the running text, exactly
+    as the pre-seam per-tool replay did — driven off op fields instead of a
+    native tool_input shape. An old_string that isn't present leaves the text
+    unchanged (the tool would error anyway) — harmless for the check."""
+    text = _read_real_text(root, fpath)
+    for op in ops:
+        old = op.get("old_string", "") or ""
+        new = op.get("added_text", "") or ""
+        if op.get("replace_all"):
+            text = text.replace(old, new)
+        else:
+            text = text.replace(old, new, 1)
+    return text
+
+
+def _run(root):
+    payload = read_input()
+    # Host seam (ADR-0011, M2/#261): iter_file_ops maps this host's native
+    # payload to canonical per-file ops. Under Claude Code, Edit/NotebookEdit
+    # map to exactly one op and MultiEdit fans to one op per edits[] entry —
+    # all sharing the SAME file_path, since each of these tools targets one
+    # file per call. Codex does not register this entry at all — its edits
+    # arrive as apply_patch and are guarded per-op by pre-write.py
+    # (docs/parity.md).
+    ops = list(get_host().iter_file_ops(payload))
+    if not ops:
+        sys.exit(0)
+
+    fpath = ops[0].get("file_path", "") or ""
+    classes = classify_protected(fpath, root)
+
+    # The tag that names each protected class, in message priority order.
+    _CLASS_TAG = (("marker", "H-19"), ("context", "H-18"),
+                  ("audit", "H-05"), ("decisions", "H-11"),
+                  ("state", "H-22"))
+
+    # H-21: an "opaque" op is a host's signal that it could not map this
+    # payload to a known per-file shape at all (e.g. a FailClosedHost, or a
+    # future host's unparseable envelope) — ambiguity resolves CLOSED
+    # (ORCHESTRATOR §2), mirroring pre-write.py's opaque handling.
+    if any(op.get("kind") == "opaque" for op in ops):
+        block("H-21", "This edit could not be decomposed into per-file operations, so its "
+                      "targets cannot be guarded. Failing closed. Retry, or report it.")
+
+    # A "notebook" op (NotebookEdit): its target has no append/frontmatter
+    # semantics to reason about — refuse any protected target outright with a
+    # class-appropriate tag (defense in depth). A notebook call always fans to
+    # exactly one op, so checking ops[0] speaks for the whole call.
+    if ops[0].get("notebook"):
+        for cls, tag in _CLASS_TAG:
+            if cls in classes:
+                block(tag, "NotebookEdit may not target a protected .codearbiter artifact "
+                           "(CONTEXT.md, audit logs, ADRs, or markers) — use the sanctioned "
+                           "skill path.")
+        sys.exit(0)
+
+    # H-19: markers are never edited via the Edit tools (#160) — the sanctioned
+    # producers write them; an Edit is tampering. Block outright.
+    if "marker" in classes:
+        block("H-19", "The .codearbiter/.markers/ gate tokens are not editable via the Edit "
+                      "tools (#160) — editing one forges or tampers with a security/migration/ADR "
+                      "gate pass. Markers are recorded only by the sanctioned gate producers.")
+
+    # H-18: an edit to CONTEXT.md may not drop `arbiter: enabled` or corrupt the
+    # frontmatter (#159) — replay every op against the file in order (a
+    # MultiEdit's edits apply as one atomic batch; the resulting text after
+    # ALL of them is what matters, not any single intermediate op) and
+    # require the FINAL result stays enabled.
+    if "context" in classes:
+        enabled, malformed = frontmatter_enabled_text(_resulting_context(root, fpath, ops))
+        if malformed or not enabled:
+            block("H-18", "This Edit would remove or alter the `arbiter: enabled` frontmatter in "
+                          ".codearbiter/CONTEXT.md (#159) — the activation switch every enforcement "
+                          "hook reads. Disabling it from inside the repo would make every gate "
+                          "dormant. Keep `arbiter: enabled` in a well-formed frontmatter block.")
+
+    # H-05: the audit logs (and the /sprint decision record) are append-only — an
+    # Edit must be a verifiable TAIL-ANCHORED append: old_string must be the
+    # file's REAL current trailing content, and new_string must extend it.
+    # (path set: _hooklib.is_audit_log)
+    if "audit" in classes:
+        # A batched op (MultiEdit's edits[] fan) applies as part of a batch and
+        # no single entry's old_string/new_string can express a verifiable
+        # pure append to an append-only file — the sanctioned append path is a
+        # single Edit (or '>>'). Block it outright rather than reason about
+        # the batch.
+        if any(op.get("batched") for op in ops):
+            block("H-05", "MultiEdit cannot guarantee a pure append to an append-only "
+                          ".codearbiter audit log (overrides.log, triage.log, sprint-log.md, decisions/decision-log.md) "
+                          "(ORCHESTRATOR §7). Append with a single Edit or '>>'.")
+        # Exactly one non-batched op reaches this point (Edit).
+        op = ops[0]
+        # reliability-003 (#172): replace_all can never be a verifiable append —
+        # it rewrites EVERY occurrence of old_string, not just the tail (a
+        # single-occurrence replace_all is indistinguishable from a targeted
+        # rewrite, and a multi-occurrence one alters interior lines outright).
+        # Reject it outright before even looking at old_string/new_string.
+        if op.get("replace_all"):
+            block("H-05", "An Edit with replace_all=true on an append-only .codearbiter "
+                          "audit log (overrides.log, triage.log, sprint-log.md, decisions/decision-log.md) cannot be a "
+                          "verifiable pure append (ORCHESTRATOR §7) — replace_all rewrites "
+                          "every matching occurrence, not just the file's tail. Append with "
+                          "'>>', or a single non-replace_all Edit whose old_string is the "
+                          "file's current trailing content.")
+        old = op.get("old_string", "") or ""
+        new = op.get("added_text", "") or ""
+        # migration-003: `new.startswith("")` is ALWAYS True, so an empty
+        # old_string defeats the append check entirely — it could prepend or
+        # replace arbitrary content with the guard never firing. An empty
+        # old_string can never be a verifiable append (there is no existing tail
+        # to extend); block it outright.
+        if not old:
+            block("H-05", "An Edit with an empty old_string on an append-only .codearbiter "
+                          "audit log (overrides.log, triage.log, sprint-log.md, decisions/decision-log.md) cannot be a "
+                          "verifiable pure append (ORCHESTRATOR §7) — every string starts with "
+                          "the empty string. Append with '>>', or a single Edit whose old_string "
+                          "is the file's current trailing content.")
+        if not new.startswith(old):
+            block("H-05", "The .codearbiter audit logs (overrides.log, triage.log, "
+                          "sprint-log.md) are append-only (ORCHESTRATOR §7). This Edit alters "
+                          "existing audit lines; only pure appends are permitted (new text "
+                          "must extend the old text).")
+        # reliability-003 (#172): new.startswith(old) alone is not enough — an
+        # old_string that matches an INTERIOR line (not the file's actual
+        # trailing content) still satisfies startswith, but inserts content
+        # BETWEEN existing lines rather than truly appending at the end.
+        # Tail-anchor against the REAL on-disk content: old_string must be
+        # exactly what the file currently ends with.
+        current = _read_real_text(root, fpath)
+        if not is_tail_append(current, old, new):
+            block("H-05", "The .codearbiter audit logs (overrides.log, triage.log, "
+                          "sprint-log.md) are append-only (ORCHESTRATOR §7). This Edit's "
+                          "old_string is not the file's current TRAILING content — a mid-file "
+                          "insertion reorders the audit record even though new_string extends "
+                          "old_string. Append with '>>', or a single Edit whose old_string is "
+                          "exactly the file's current tail.")
+
+    # H-11: ADRs may only be edited via /adr — any .md anywhere under decisions/
+    # (a non-numbered draft or a nested path is still an immutable decision).
+    # (path set: _hooklib.is_decisions_path)
+    if "decisions" in classes:
+        marker = os.path.join(root, ".codearbiter", ".markers", "adr-authoring-active")
+        if not os.path.isfile(marker):
+            block("H-11", "ADR files are edited only via /adr (ORCHESTRATOR §3) — user "
+                          "attribution required.")
+        if not marker_fresh(marker, MARKER_FRESHNESS_MINUTES):
+            block("H-11", f"ADR authoring marker is stale (>{MARKER_FRESHNESS_MINUTES} min). Re-run /adr.")
+
+    # H-22: the protected-state registry (B1/#564) — the SAME generic branch
+    # pre-write.py carries (T-06/T-07 design ruling: one branch, not a
+    # per-tool special case). classify_protected already decided "state" is
+    # a hit; resolve_registered_path only resolves WHICH registered path and
+    # WHICH policy — never a second, independent membership check.
+    # marker-gated admits only under a fresh authoring marker; helper-only
+    # and append-only are flank-IDENTICAL here — both hard-block
+    # unconditionally, with NO marker path and no tail-anchored-append
+    # admission (unlike H-05's audit logs, an append-only registry entry's
+    # append verb lives in the sanctioned HELPER, not in this Edit flank).
+    if "state" in classes:
+        rel, policy = resolve_registered_path(fpath, root)
+        if policy == ProtectedPolicy.MARKER_GATED:
+            if not marker_gated_write_admitted(rel, root):
+                block("H-22", f"'{rel}' is marker-gated protected project state (#564) — an "
+                              f"Edit is admitted only under a fresh authoring marker. Run the "
+                              f"sanctioned authoring lane, or "
+                              + get_host().cmd_ref("override") + ".")
+        else:
+            block("H-22", f"'{rel}' is protected project state (#564) — the Edit tools may "
+                          f"never target it; there is no marker path for this policy. Use "
+                          f"the sanctioned helper.")
+
+    sys.exit(0)
+
+
+def main():
+    utf8_stdio()
+    root = project_root()
+    if not arbiter_active(root):
+        sys.exit(0)
+    # reliability-002 (#189): scoped to arbiter-enabled repos only (above), so a
+    # dormant/non-codeArbiter repo can never be bricked by a crash here. An
+    # uncaught exception in the scan below must fail CLOSED (exit 2 = BLOCK),
+    # not exit 1 — a non-2 exit is a NON-blocking error under the Claude Code
+    # hook contract (_hooklib.py:11-15) and would silently ALLOW the Edit.
+    # read_input()'s documented fail-OPEN parse behavior is unaffected: it
+    # catches its own errors and returns {} before this wrapper is reached.
+    try:
+        _run(root)
+    except SystemExit:
+        raise
+    except Exception:  # noqa: BLE001 — the fail-closed backstop of last resort
+        traceback.print_exc(file=sys.stderr)
+        block("H-00", "pre-edit guard crashed while scanning this Edit — failing "
+                      "closed (ORCHESTRATOR §2) rather than silently allowing an "
+                      "unscanned edit. See the traceback above; retry, or report it.")
+
+
+def run(host, argv=None):
+    """Host-seam entry point (ADR-0011): the __main__ guard calls this with the
+    plugin's loaded Host. Wraps main() unchanged — main() still communicates
+    via sys.exit/stdout/stderr, and its return value stays discarded exactly
+    as the old bare `main()` guard discarded it (so the process still exits 0
+    on a normal fall-through).
+
+    Wires `host` live (#257): primes `_hooklib`'s process-cached Host via
+    `set_host()` BEFORE main() runs, so main()'s `get_host()` call resolves
+    to the SAME instance the caller passed here — no second
+    `hostapi.load_host()`, and `run(fake_host)` genuinely exercises
+    `fake_host`."""
+    return _entrylib.dispatch(host, argv, main, set_host,
+                               pass_argv=False, propagate_result=False)
+
+
+if __name__ == "__main__":
+    sys.exit(run(hostapi.load_host()) or 0)