arbiterForge
diff --git a/‎.github/scripts/test_release_lib.py‎
Lines changed: 227 additions & 25 deletions b/‎.github/scripts/test_release_lib.py‎
Lines changed: 227 additions & 25 deletions
diff --git a/‎CHANGELOG.md‎
Lines changed: 33 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 33 additions & 0 deletions
diff --git a/‎core/pysrc/_githooks.py‎
Lines changed: 196 additions & 9 deletions b/‎core/pysrc/_githooks.py‎
Lines changed: 196 additions & 9 deletions
diff --git a/‎core/pysrc/doctor.py‎
Lines changed: 41 additions & 3 deletions b/‎core/pysrc/doctor.py‎
Lines changed: 41 additions & 3 deletions
diff --git a/‎plugins/ca-codex/CHANGELOG.md‎
Lines changed: 6 additions & 0 deletions b/‎plugins/ca-codex/CHANGELOG.md‎
Lines changed: 6 additions & 0 deletions
@@ -36,6 +36,39 @@ predate the plugin rewrite and are grouped by date.
   question ("if every criterion passed, what would still be broken?")
   that a bijective check cannot mechanize (#566).
 
+## [2.11.13] — 2026-08-05
+
+### Fixed
+
+- Six `.github/scripts/test_release_lib.py` governance rules that pin
+  load-bearing sentences in the release skill — the footer BLOCK /
+  never-auto-fill rule, the publish read-back rule, the immutable-tag hard
+  rule, the pre-tag BLOCK-on-nonzero rule, and two re-run HIGH rules
+  (`tag_sha` peeling, back-fill's `latest-eligible` declaration) — had every
+  anchor token also occurring elsewhere in the skill, so the sentence each
+  one names could be deleted while the rule stayed green. Each is now
+  re-anchored on a span unique to its own guarded sentence, verified against
+  the source and all three rendered payloads (`ca`, `ca-codex`, `ca-pi`),
+  with a pinned RED/GREEN mutation proof against the real skill text (#571).
+
+## [2.11.12] — 2026-08-05
+
+### Fixed
+
+- The git-level hook backstop (#161) could run from an arbitrarily stale
+  host plugin cache — a Codex install that predated the #279 sensitive-scan
+  exemption resurrected that exact false positive, blocking a commit whose
+  only "sensitive" lines were the crypto/secret gate's own machine-written
+  audit rows, with no in-session exit but an override. Each live host's
+  session now records a content-addressed freshness heartbeat
+  (`.git/codearbiter-hooksd/<plugin>.seen`) alongside its registered
+  enforcer entry; the generated shim skips a registered entry whose
+  heartbeat is missing or stale relative to a fresher registered sibling,
+  deferring the verdict to whichever entry a live session most recently
+  confirmed, rather than letting an unrefreshed cache author a block.
+  `/ca:doctor` now surfaces a stale drop-in entry before it can produce a
+  false block (#556).
+
 ## [2.11.11] — 2026-08-05
 
 ### Fixed
 
@@ -116,7 +116,12 @@
 from _durabilitylib import is_ephemeral_path
 from _gitexec import git_executable, trusted_git_executable, trusted_python_executable
 
-SENTINEL = "# codeArbiter-managed git hook (#161) — refreshed each session; edits are overwritten."
+SENTINEL = (
+    "# codeArbiter-managed git hook (#161) — 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."
+)
 PHASES = ("pre-commit", "pre-push")
 # The hooks_dir() resolution cache lives INSIDE .git/ itself (never under
 # .codearbiter/): a linked worktree's `.git` is a FILE (not a directory)
@@ -315,6 +320,141 @@ def _write_path_entry(dropin_dir, plugin, enforcer):
         return False
 
 
+def _seen_marker_file(dropin_dir, plugin):
+    return os.path.join(dropin_dir, f"{plugin}.seen")
+
+
+def _touch_seen_marker(dropin_dir, plugin, enforcer):
+    """Best-effort (never fatal) freshness heartbeat for `plugin` (#556).
+
+    Records the SAME enforcer value `_write_path_entry` just confirmed in
+    `<plugin>.path` — content-addressed on purpose. The freshness guard below
+    only trusts this heartbeat's mtime when its recorded content still
+    matches `<plugin>.path`'s CURRENT content; a raw mtime-only heartbeat
+    (compared only against `.path`'s own mtime) is a sub-millisecond race on
+    some filesystems whenever a `.path` entry is rewritten by something other
+    than `install()` shortly after a real install (exactly what several
+    existing drop-in tests simulate to probe unrelated behavior) — content
+    equality has no such timing dependency.
+
+    Unlike `<plugin>.path` (which `_write_path_entry` deliberately leaves
+    untouched when its content hasn't changed, to avoid churn), THIS file is
+    rewritten every live session regardless of whether the `.path` entry
+    itself changed — it is the signal a sibling plugin's cache has gone
+    stale. A plugin whose host never runs a session again simply stops
+    updating its `.seen` file, which is exactly the staleness #556 needs
+    surfaced.
+
+    Callers must skip this for an ephemeral enforcer (mirroring
+    `_write_path_entry`'s own refusal) — an ephemeral session confirming
+    freshness would be exactly the wrong direction: it would make a
+    sibling's genuinely durable, still-correct entry look stale by
+    comparison."""
+    try:
+        os.makedirs(dropin_dir, exist_ok=True)
+        _hooklib.write_text_atomic(
+            _seen_marker_file(dropin_dir, plugin), _shell_path(enforcer) + "\n", newline="\n")
+    except Exception:  # noqa: BLE001
+        pass
+
+
+# The freshness probe embedded VERBATIM into every generated shim (via a
+# stdin heredoc, see `_shim()`) AND run identically by `stale_registered_plugins`
+# below for `/ca:doctor` (#556, AC-3). Deliberately a single string constant
+# run in BOTH places rather than two hand-kept implementations: the shim
+# cannot import any plugin's `_githooks.py` to get this logic (whichever
+# plugin's copy it picked could itself be the stale one this guard exists to
+# distrust — the exact #556 failure, one level up), so it must be entirely
+# self-contained text that the CURRENTLY installing (never stale — the shim
+# file itself is regenerated by whatever live host runs `install()`, see
+# SENTINEL) session bakes in. `/ca:doctor` runs the SAME text as a real
+# subprocess instead of a parallel port, so the two can never drift.
+#
+# Algorithm: a plugin's registered entry is "stale" — printed to stdout, one
+# per line — iff (a) at least one OTHER registered entry in the same
+# drop-in dir has recorded a `.seen` heartbeat, AND (b) this plugin's own
+# heartbeat is either absent or strictly older than the freshest one seen.
+# When NOBODY has ever recorded a heartbeat (a repo that predates #556, or
+# every registered plugin genuinely dormant), nothing is printed — the
+# caller then treats every entry as before this fix (the original, safe
+# fail-closed "run everything" default), never silently disabling
+# enforcement outright.
+_FRESHNESS_PY = (
+    "import os, re, sys\n"
+    "d = sys.argv[1] if len(sys.argv) > 1 else ''\n"
+    "try:\n"
+    "    names = os.listdir(d)\n"
+    "except OSError:\n"
+    "    names = []\n"
+    "legacy = re.compile(r'^[0-9]+\\.[0-9]+\\.[0-9]+$')\n"
+    "def _rd(p):\n"
+    "    try:\n"
+    "        with open(p, encoding='utf-8', errors='replace') as f:\n"
+    "            return f.read().strip()\n"
+    "    except OSError:\n"
+    "        return None\n"
+    "entries = []\n"
+    "for n in sorted(names):\n"
+    "    if not n.endswith('.path'):\n"
+    "        continue\n"
+    "    plugin = n[:-len('.path')]\n"
+    "    if legacy.fullmatch(plugin):\n"
+    "        continue\n"
+    "    path_val = _rd(os.path.join(d, n))\n"
+    "    if path_val is None:\n"
+    "        continue\n"
+    "    seen_file = os.path.join(d, plugin + '.seen')\n"
+    # `.seen` only counts as a confirmation of what's registered RIGHT NOW when
+    # its recorded value still matches `.path`'s CURRENT content -- content
+    # equality, never a raw mtime-ordering guess. A `.path` entry rewritten by
+    # something other than install() (a version bump landing between two
+    # sessions, or -- in this suite's own drop-in fixtures -- a direct
+    # overwrite that never re-confirms) leaves a `.seen` file whose value no
+    # longer matches, which must NOT count as evidence for the new content: a
+    # sub-millisecond mtime race between two nearly-simultaneous writes is not
+    # a reliable ordering signal on every filesystem, but string equality has
+    # no timing dependency at all.
+    "    confirmed = None\n"
+    "    if _rd(seen_file) == path_val:\n"
+    "        try:\n"
+    "            confirmed = os.stat(seen_file).st_mtime\n"
+    "        except OSError:\n"
+    "            confirmed = None\n"
+    "    entries.append((plugin, confirmed))\n"
+    "known = [m for _, m in entries if m is not None]\n"
+    "if known:\n"
+    "    mx = max(known)\n"
+    "    for plugin, m in entries:\n"
+    "        if m is None or m < mx:\n"
+    "            print(plugin)\n"
+)
+
+
+def stale_registered_plugins(dropin_dir):
+    """Plugin names whose drop-in `.path` entry the generated shim's
+    freshness guard (#556) will SKIP at the next commit/push, because a
+    fresher registered sibling exists. Runs `_FRESHNESS_PY` as a real
+    subprocess of THIS interpreter — never a hand-kept parallel
+    implementation — so `/ca:doctor` (AC-3) and the shim can never disagree.
+
+    Returns [] when `dropin_dir` doesn't exist, nothing is registered, or
+    the probe fails for any reason — a diagnostic must never be able to
+    raise into its caller."""
+    if not dropin_dir or not os.path.isdir(dropin_dir):
+        return []
+    try:
+        r = subprocess.run(
+            [sys.executable, "-", dropin_dir], input=_FRESHNESS_PY,
+            capture_output=True, text=True, encoding="utf-8", errors="replace",
+            timeout=5,
+        )
+    except Exception:  # noqa: BLE001
+        return []
+    if r.returncode != 0:
+        return []
+    return [ln for ln in r.stdout.splitlines() if ln.strip()]
+
+
 _TRUSTED_IDENTITY_FILE = "trusted-executables.identity"
 
 
@@ -368,10 +508,10 @@ def _shim(dropin_dir, phase):
     # Single-interpreter selection preserves stdin (pre-push) and the BLOCK
     # exit code. The shim is HOST-NEUTRAL (ADR-0014): it embeds no plugin-
     # specific enforcer path, only the shared drop-in directory. It iterates
-    # every "*.path" entry there and runs EVERY enforcer that resolves. Any
-    # non-zero verdict blocks, so an older live sibling can never mask a newer
-    # guard. A dead entry from an uninstalled plugin is skipped. An unmatched
-    # glob (dir absent or
+    # every "*.path" entry there and runs every enforcer that resolves AND is
+    # not recognized as stale (#556, below) — any non-zero verdict from one of
+    # those blocks. A dead entry from an uninstalled plugin is skipped. An
+    # unmatched glob (dir absent or
     # empty) leaves `c` as the literal, un-expanded "$D/*.path" string in
     # POSIX `sh` — `[ -f "$c" ]` on that literal correctly fails too, so the
     # loop falls straight through to the same fail-closed tail with no special
@@ -381,6 +521,23 @@ def _shim(dropin_dir, phase):
     # provides trusted executable identities, install() persists them beside
     # the registry. Identity-less hosts preserve that set, so a later Claude or
     # Codex session cannot downgrade Pi's absolute executable boundary.
+    #
+    # #556 (AC-1): "any non-zero verdict blocks" used to mean an entry that
+    # nobody has refreshed in months — a host cache that predates a fix THIS
+    # checkout already carries, e.g. the #279 sensitive-scan exemption — could
+    # resurrect an already-closed false positive with no in-session exit but
+    # an override. Before running the loop, `$SKIP` is populated (via
+    # `_FRESHNESS_PY`, run once here from a heredoc so this is never delegated
+    # to any specific plugin's own — possibly stale — `_githooks.py`) with the
+    # plugin names whose `.seen` heartbeat (written every live session,
+    # unconditionally, by `install()`) is missing or older than a sibling's.
+    # Those entries are skipped WITHOUT running their python at all, deferring
+    # to whichever registered sibling a live session confirmed more recently.
+    # When NO entry anywhere has ever recorded a heartbeat (a repo that
+    # predates this fix, or a wholly dormant install), `$SKIP` is empty and
+    # every entry runs exactly as before — this can only ever narrow which
+    # entries run, never widen it, so a genuine `SEEN=0` fail-closed case is
+    # unaffected.
     def quote(value):
         return "'" + value.replace("'", "'\"'\"'") + "'"
 
@@ -414,10 +571,24 @@ def quote(value):
         '  if python3 -c "" 2>/dev/null; then PY=python3; else PY=python; fi\n'
         "fi\n"
         f"{capture}"
+        # #556: computed once per hook firing, from a literal heredoc (never
+        # an `import` of any plugin's own `_githooks.py`) so this stays
+        # correct even when every REGISTERED enforcer is stale — only the
+        # currently-installing session's freshly generated shim needs to be
+        # current for this to work. A crash/empty result here just leaves
+        # $SKIP empty (see `[ "$RC" -eq 0 ] || exit "$RC"` below — command
+        # substitution failure doesn't abort `sh`), the original run-everything
+        # behavior.
+        "SKIP=$(\"$PY\" - \"$D\" <<'CODEARBITER_556_FRESHNESS'\n"
+        f"{_FRESHNESS_PY}"
+        "CODEARBITER_556_FRESHNESS\n"
+        ")\n"
         "SEEN=0\n"
         'for c in "$D"/*.path; do\n'
         '  [ -f "$c" ] || continue\n'
-        '  case "${c##*/}" in [0-9]*.[0-9]*.[0-9]*.path) continue ;; esac\n'
+        '  N=${c##*/}\n'
+        '  case "$N" in [0-9]*.[0-9]*.[0-9]*.path) continue ;; esac\n'
+        '  case " $SKIP " in *" ${N%.path} "*) continue ;; esac\n'
         '  IFS= read -r E < "$c" || continue\n'
         '  [ -f "$E" ] || continue\n'
         '  SEEN=1\n'
@@ -645,7 +816,8 @@ def install(root):
         if (cached_norm == default_hd
                 and _confirmed_no_local_hooks_path(root)
                 and _hooks_current(cached_hd, dropin_dir)):
-            _write_path_entry(dropin_dir, plugin, enforcer)
+            if _write_path_entry(dropin_dir, plugin, enforcer):
+                _touch_seen_marker(dropin_dir, plugin, enforcer)  # #556 freshness heartbeat
             return []
     hd = hooks_dir(root)
     if not hd:
@@ -686,9 +858,12 @@ def install(root):
     # rev-parse re-probe entirely (performance-002) — best-effort, never fatal.
     _write_hooks_dir_cache(root, hd)
     # ADR-0014: refresh THIS plugin's own drop-in entry every call, whether or
-    # not the shim files above needed a rewrite.
+    # not the shim files above needed a rewrite. #556: the `.seen` heartbeat
+    # is touched on every successful confirmation too (never skipped for
+    # "no churn" the way the `.path` entry itself is) — it is the freshness
+    # guard's only signal that a LIVE session confirmed this entry today.
     if _write_path_entry(dropin_dir, plugin, enforcer):
-        pass
+        _touch_seen_marker(dropin_dir, plugin, enforcer)
     return actions
 
 
@@ -714,6 +889,18 @@ def uninstall(root):
             actions.append(f"{plugin}.path: removed")
         except Exception as e:  # noqa: BLE001
             _warn(f"could not remove {entry}: {e}")
+    # #556: drop this plugin's OWN freshness heartbeat alongside its `.path`
+    # entry — a genuinely uninstalled plugin must not keep looking "live" to
+    # the freshness guard above (it would otherwise sit there, forever
+    # confirmed-fresh at its last mtime, potentially outranking a sibling
+    # that IS still being maintained).
+    seen = _seen_marker_file(dropin_dir, plugin)
+    if os.path.isfile(seen):
+        try:
+            os.remove(seen)
+            actions.append(f"{plugin}.seen: removed")
+        except Exception as e:  # noqa: BLE001
+            _warn(f"could not remove {seen}: {e}")
     identity = _read_trusted_identity(dropin_dir)
     if identity is not None and identity[2] == plugin:
         path = _identity_file(dropin_dir)
 
@@ -22,6 +22,7 @@
 from _gitexec import git_executable  # noqa: E402
 import hostapi  # noqa: E402 — host seam (ADR-0011): plugin-root resolution
 import _entrylib  # noqa: E402 — shared run() dispatch (jscpd dedup)
+import _githooks  # noqa: E402 — #556: git-hook drop-in registry freshness
 from _hooklib import frontmatter_enabled, get_host, set_host, utf8_stdio  # noqa: E402
 
 HOOK_SCRIPTS = ("session-start.py", "pre-bash.py", "pre-write.py",
@@ -169,16 +170,18 @@ def check_payload(root, host=None):
 
 
 def check_repo():
+    """Returns the resolved repo root (for check_git_hook_freshness below), or
+    None when this process isn't inside a git repository at all."""
     r = _run_cmd([git_executable(), "rev-parse", "--show-toplevel"])
     if r.returncode != 0:
         warn("not inside a git repository — repo-level checks skipped")
-        return
+        return None
     root = r.stdout.strip()
     ctx = os.path.join(root, ".codearbiter", "CONTEXT.md")
     if not os.path.isfile(ctx):
         ok(f"no .codearbiter/CONTEXT.md in {root} — codeArbiter is dormant here "
            f"by design (run {get_host().cmd_ref('init')} to opt in)")
-        return
+        return root
     enabled, malformed = frontmatter_enabled(ctx)
     if malformed:
         fail("CONTEXT.md frontmatter opens with --- but never closes — the "
@@ -201,6 +204,40 @@ def check_repo():
         else:
             warn("git user.email is unset — overrides/ADRs cannot be attributed; "
                  "set it before gated work")
+    return root
+
+
+def check_git_hook_freshness(root):
+    """#556 (AC-3): the git-level hook backstop (#161) can be running from a
+    host's plugin cache that nobody has refreshed in a long time — a cache
+    that predates a fix THIS checkout already carries (the #279
+    sensitive-scan exemption, in the issue that motivated this check) is
+    still wired into `.git/hooks` and can still block on stale logic. Before
+    this check existed, nothing surfaced that until it produced a false
+    block. Runs the SAME freshness probe the generated shim itself runs at
+    commit/push time (`_githooks.stale_registered_plugins`), so this can
+    never disagree with what actually happens at commit time.
+
+    A no-op (nothing printed) when `root` is None (not inside a git repo —
+    already reported by check_repo) or the drop-in registry doesn't exist
+    yet (nothing installed, or a host that predates ADR-0014)."""
+    if root is None:
+        return
+    dropin_dir = _githooks._dropin_dir(root)
+    if dropin_dir is None or not os.path.isdir(dropin_dir):
+        return
+    stale = _githooks.stale_registered_plugins(dropin_dir)
+    if stale:
+        names = ", ".join(sorted(stale))
+        plural = "entries" if len(stale) != 1 else "entry"
+        warn(f"the git-hook backstop's drop-in registry (#161/#556) has a stale "
+             f"enforcer {plural} for: {names} — a fresher registered sibling "
+             f"exists (.git/codearbiter-hooksd), and the shim already skips the "
+             f"stale {plural} rather than let it false-block. Start a session for "
+             f"that host, or reinstall it, to refresh {names}.")
+    else:
+        ok("git-hook backstop registry (.git/codearbiter-hooksd) has no stale "
+           "enforcer entries")
 
 
 def check_host(host):
@@ -336,7 +373,8 @@ def main():
     check_host(host)
     check_interpreters()
     check_payload(root, host)
-    check_repo()
+    repo_root = check_repo()
+    check_git_hook_freshness(repo_root)
     check_mcp(host)
     if getattr(host, "has_statusline", True):
         # A host with no statusline surface (Codex) must not read
 
@@ -6,6 +6,12 @@ All notable changes to the **ca-codex** plugin are recorded here. Format follows
 
 ## [Unreleased]
 
+## [0.4.11] — 2026-08-05
+
+### Fixed
+
+- The git-level hook backstop (#161) could run from an arbitrarily stale host plugin cache — this plugin's own `0.3.0` cache predating the #279 sensitive-scan exemption resurrected that exact false positive, blocking a commit whose only "sensitive" lines were the crypto/secret gate's own machine-written audit rows. Each live host's session now records a content-addressed freshness heartbeat (`.git/codearbiter-hooksd/<plugin>.seen`) alongside its registered enforcer entry; the generated shim skips a registered entry whose heartbeat is missing or stale relative to a fresher registered sibling. `/ca:doctor` now surfaces a stale drop-in entry before it can produce a false block (#556).
+
 ## [0.4.10] — 2026-08-05
 
 ### Fixed