@arbiterforge/ca-pi 0.6.0

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

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+# codeArbiter - ACTIVATION: which Host this process is running under, where the
+# project root is, and whether the arbiter is switched on for it.
+#
+# Extracted from _hooklib (issue #321, architecture-002) as slice 4, the last and
+# the one with real teeth. Measured like the others: this cluster references
+# NOTHING from the rest of _hooklib. The edge runs the other way for the first
+# time - _log_gate_event (which stays behind) calls get_host() and
+# project_root() - so _hooklib imports from here and never the reverse. Still
+# one-way, still no cycle.
+#
+# WHY THESE BELONG TOGETHER: they are the three answers every hook needs before
+# it can decide anything, and they share two process-lifetime caches. `_HOST` and
+# `_ROOT_CACHE` exist because a hook is a single-shot process whose host identity
+# and project root cannot change mid-run; arbiter_active reads the root to find
+# CONTEXT.md, and project_root reads the host. Splitting them would put a cache
+# in one module and its only writer in another.
+#
+# ON THE MUTABLE GLOBALS, because this is the trap in this slice:
+# `_HOST` is deliberately NOT re-exported by _hooklib. `from _activationlib
+# import _HOST` binds the VALUE at import time, so a later set_host() would
+# rebind the name HERE and leave _hooklib holding a stale None forever - the
+# exact silent-divergence bug the partition exists to prevent. The three
+# accessors ARE re-exported, and they all read and write this module's global,
+# so every caller sees one cache no matter which module it imported them from.
+# That is the opposite of slice 3's lesson (re-export the privates) and for a
+# precise reason: a FUNCTION binding stays live, a VALUE binding does not.
+# Verified: nothing in the repo reads _hooklib._HOST directly.
+
+from __future__ import annotations
+
+import os
+import re
+
+import hostapi
+
+
+# The loaded Host is process-cached: hooks are single-shot processes, and the
+# host's identity cannot change mid-process (its methods read env/payload state
+# live at call time, so caching the OBJECT changes no verdict).
+_HOST = None
+
+def get_host():
+    """The process's Host instance (hostapi.load_host(), cached)."""
+    global _HOST
+    if _HOST is None:
+        _HOST = hostapi.load_host()
+    return _HOST
+
+
+def set_host(host):
+    """Dependency-injection seam (#257 architecture-001/performance-002).
+
+    Primes the module-cached `_HOST` that `get_host()` reads. Every entry
+    script's `run(host, argv=None)` calls this BEFORE `main()`, so the Host
+    instance the `__main__` guard already resolved via `hostapi.load_host()`
+    is the SAME object `get_host()` serves inside `main()` — closing two
+    defects at once: (1) `main()` no longer triggers its own redundant
+    `hostapi.load_host()` (a second `_host.py` load per invocation), and
+    (2) `run(host)` stops silently ignoring its `host` argument — a test that
+    calls `run(fake_host)` now genuinely exercises `fake_host`, not whatever
+    `load_host()` resolves from disk. In production the injected host IS the
+    `load_host()` result the guard already computed, so this changes no
+    behavior — it only removes the redundant second load and makes the
+    existing `run(host)` parameter live."""
+    global _HOST
+    _HOST = host
+
+
+def reset_host():
+    """Test-only: clear the injected/cached `_HOST` so the next `get_host()`
+    lazy-loads afresh. Production hook processes are single-shot and never need
+    this; but `set_host()` makes `_HOST` a process-lifetime singleton, so a test
+    that calls `run(fake_host)` must reset it in tearDown — otherwise the fake
+    leaks into any later in-process test that calls `get_host()` without its own
+    patch, silently running against the wrong host and masking a gate
+    regression (security review #257, LOW)."""
+    global _HOST
+    _HOST = None
+
+# project_root() memoization (performance-001/003, #260). A hook is a
+# single-shot process, so CLAUDE_PROJECT_DIR and the process cwd cannot
+# change mid-process — but the resolved VALUE is cached keyed on those two
+# inputs (not unconditionally) rather than as one bare value, so an env/cwd
+# change is a cache MISS, never a stale hit. This keeps the production
+# single-shot contract (the same hook process always sees an unchanging
+# env/cwd, so it resolves at most once) while staying correct for the
+# in-process integration-test harnesses that legitimately re-target
+# project_root() across many fixtures/envs within one Python process
+# (`python -m unittest discover` runs the whole suite in ONE interpreter —
+# an unconditional single-value cache would leak the FIRST test's resolved
+# root into every later test that calls project_root() or warn()/block()/
+# remind() in-process). A payload's `cwd` is deliberately NOT part of the
+# cache key: within one real hook process the payload is parsed at most once
+# and never changes, so a payload-bearing call and a later no-payload call in
+# the SAME (env, cwd) context are the SAME logical resolution and must return
+# the SAME value — exactly the "payload-bearing first call, later no-arg
+# calls stay consistent" contract. (A payload-only scenario — Codex, no
+# CLAUDE_PROJECT_DIR — still resolves once: the first call's payload wins and
+# is cached against the current (env, cwd); env/cwd don't change either.)
+_ROOT_CACHE = {}
+
+
+def _root_cache_key():
+    return (os.environ.get("CLAUDE_PROJECT_DIR"), os.getcwd())
+
+
+def _reset_root_cache():
+    """Test-only: drop every memoized project_root() resolution. Production
+    hook processes never need this (each is single-shot); integration tests
+    that simulate MANY logical hook invocations in one Python process and
+    need a resolution to be genuinely re-computed (rather than served from an
+    still-valid (env, cwd) cache entry) call this between scenarios."""
+    _ROOT_CACHE.clear()
+
+
+def marker_root(payload=None):
+    """The root `.codearbiter/.markers/` gate passes (security-pass.py,
+    migration-pass.py, and the H-09b/H-10b/H-14 guards) are written to and
+    read from (#604) — see `hostapi.Host.marker_root`'s docstring for why
+    this is NOT the same thing as `project_root()` in a linked worktree.
+
+    Not memoized like `project_root()` above: called at most once or twice
+    per hook process (the marker checks, or a single `security-pass.py` /
+    `migration-pass.py` run), so the extra git spawn a linked-worktree
+    escalation occasionally costs is not worth a second cache to avoid."""
+    return get_host().marker_root(payload)
+
+ARBITER_RE = re.compile(r"^\s*arbiter:\s*enabled\s*$", re.I)
+
+def frontmatter_enabled_text(text):
+    """(enabled, malformed) for CONTEXT.md *content* (see frontmatter_enabled).
+    Split out so the #159 Write/Edit guard can vet the RESULTING content of an
+    edit — 'does this edit keep the repo arbiter-enabled?' — without going to
+    disk, sharing one parser with the on-disk activation check so the two never
+    disagree on what 'enabled' means."""
+    lines = (text or "").split("\n")
+    if not lines:
+        return (False, False)
+    first = lines[0].lstrip("")  # tolerate a leading UTF-8 BOM
+    if first.strip() != "---":
+        return (False, False)  # no opening delimiter — dormant, not malformed
+    found = False
+    for ln in lines[1:]:
+        if ln.strip() == "---":
+            return (found, False)  # closing delimiter — decision is final
+        if ARBITER_RE.match(ln):
+            found = True
+    return (False, True)  # opened but never closed — malformed
+
+
+def frontmatter_enabled(ctx_path):
+    """Return (enabled, malformed) for CONTEXT.md ON DISK. `enabled` iff
+    `arbiter: enabled` appears in a properly-closed leading YAML frontmatter
+    block. `malformed` iff a block opens (`---` on line 1) but never closes — the
+    fail-loud case. A file with no frontmatter at all is simply dormant (not
+    malformed). Unreadable file -> (False, False)."""
+    try:
+        with open(ctx_path, encoding="utf-8", errors="replace") as f:
+            text = f.read()
+    except Exception:  # noqa: BLE001
+        return (False, False)
+    return frontmatter_enabled_text(text)
+
+
+def arbiter_active(root):
+    """True iff this repo opted in (`arbiter: enabled` in CONTEXT.md frontmatter).
+    Every enforcement hook gates on this so the plugin is genuinely dormant in
+    repos that never opted in — the plugin.json activation contract."""
+    enabled, _ = frontmatter_enabled(os.path.join(root, ".codearbiter", "CONTEXT.md"))
+    return enabled
+
+def project_root(payload=None):
+    """The project root. `CLAUDE_PROJECT_DIR` is the harness's own authoritative
+    signal and is trusted first: a hook subprocess is not guaranteed to start
+    with the project directory as its cwd, and a `git rev-parse` from elsewhere
+    can resolve to a different repo entirely (e.g. the plugin's own marketplace
+    clone). The env-first read also saves one git spawn per hook invocation.
+    Test harnesses that spawn hooks into fixture repos must pin the variable to
+    the fixture, as the production harness pins it to the project.
+
+    The resolution itself lives on the Host seam (hostapi.Host.project_root,
+    ADR-0011) — this function keeps its public signature (now accepting an
+    optional `payload`, architecture-006/#260, so a caller that already has
+    the parsed hook payload can hand it through to the payload-cwd leg) and
+    delegates, so every existing no-arg caller/import keeps working unchanged.
+
+    Memoized per (CLAUDE_PROJECT_DIR, process cwd) — see _ROOT_CACHE above for
+    the full contract (performance-001/003, #260): at most one resolution
+    (and at most one git spawn) per that key, so the repeated project_root()
+    reads inside block()/remind()/warn()'s gate-event logging don't each pay
+    a fresh subprocess."""
+    key = _root_cache_key()
+    if key not in _ROOT_CACHE:
+        _ROOT_CACHE[key] = get_host().project_root(payload)
+    return _ROOT_CACHE[key]

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

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+# codeArbiter — statusline arbiter-state parsing (extracted from statusline.py,
+# architecture-004).
+#
+# Owns reading the .codearbiter/ project-state directory into the compact dict the
+# arbiter segment renders: frontmatter parsing, override/question counting, the
+# mtime-keyed cache (a StopHook-driven statusline re-renders on every tool-call
+# completion, so re-parsing 5 small files on every render would be wasteful), and
+# the dev-mode marker check.
+#
+# The task-in-flight count and the arbiter-enabled gate are OWNED elsewhere
+# (_taskboardlib.count_in_flight / _hooklib.frontmatter_enabled) so the box and the
+# enforcement hooks agree on both contracts. This module never imports them
+# directly — the caller (statusline.py) passes its own guarded-imported references
+# through, so a test that monkeypatches statusline's fallback (e.g.
+# `mod._count_in_flight = None`) is observed correctly on the next call.
+#
+# Design principles (mirroring _ledgerlib.py):
+#   - Stdlib only; no third-party imports ever.
+#   - Zero side effects at import time.
+#   - Never raise on malformed user input — degrade to a safe default.
+#
+# Public API:
+#   frontmatter(path) -> dict                       parsed leading YAML frontmatter block
+#   frontmatter_text(text) -> dict                   same parse, given already-read text (performance-003)
+#   count_matches(path, pattern) -> int              regex match count in a file (0 on any I/O error)
+#   count_matches_text(text, pattern) -> int          same count, given already-read text (performance-003)
+#   arbiter_state(root, count_in_flight=None, read_board=None, frontmatter_enabled=None,
+#                 ctx_text=None, ot_text=None, oq_text=None) -> dict|None
+#   dev_active(root) -> bool                        True when the /dev marker is present
+#
+# performance-003 (#194): SessionStart's main() already reads CONTEXT.md,
+# open-tasks.md, and open-questions.md before the display-only governance line
+# is ever rendered. The optional ctx_text/ot_text/oq_text kwargs on
+# arbiter_state let a caller that already holds that content thread it through
+# instead of paying for a second disk read of the same file in the same
+# process. None (the default) means "not supplied" -> falls back to the
+# original read-from-disk behavior, so every existing caller (the standalone
+# statusline.py render, direct arbiter_state(root) calls in tests) is
+# unaffected.
+
+import os
+import re
+
+# mtime-keyed memo: statusline.py is a short-lived subprocess, but a single render
+# can resolve arbiter_state more than once (safe() probes), and the StopHook fires
+# the whole script on every tool-call completion. Caching on max(input mtime) makes
+# the 5 .codearbiter/ reads happen at most once per (root, change), re-reading only
+# when one of the inputs actually changes between renders.
+_ARBITER_CACHE = {}        # root -> (mtime_key, result)
+_ARBITER_FILES = ("CONTEXT.md", "overrides.log", "last-checkpoint",
+                  "open-tasks.md", "open-questions.md", "sprint-active")
+
+
+def frontmatter_text(text):
+    """Parse a properly-closed leading YAML frontmatter block out of already-read
+    `text` into a key map (see frontmatter() for the on-disk counterpart — this is
+    the pure text half, extracted for performance-003 so a caller holding the
+    content already can skip a second disk read). Tolerates a leading UTF-8 BOM
+    character (\\ufeff) on the first line the same way frontmatter()'s utf-8-sig
+    decode does, regardless of how the caller's text was originally decoded."""
+    fm = {}
+    lines = (text or "").splitlines()
+    if not lines:
+        return fm
+    first = lines[0].lstrip("")
+    if first.strip() != "---":
+        return fm
+    closed = False
+    for ln in lines[1:]:
+        if ln.strip() == "---":
+            closed = True
+            break
+        m = re.match(r"^([A-Za-z0-9_-]+):\s*(.*)$", ln)
+        if m:
+            fm[m.group(1)] = m.group(2).strip()
+    # A valid YAML frontmatter block is bounded by BOTH delimiters; an unterminated
+    # block (no closing "---") is malformed — don't honor keys parsed to EOF.
+    return fm if closed else {}
+
+
+def frontmatter(path):
+    """Parse a properly-closed leading YAML frontmatter block into a key map. The
+    *arbiter-enabled* decision is NOT made here — that activation contract is owned
+    by _hooklib.frontmatter_enabled (see arbiter_state) so the box and the
+    enforcement hooks read it one way. This reader exists only to surface the
+    remaining display keys (e.g. `stage`) the boolean gate doesn't carry."""
+    try:
+        # utf-8-sig transparently strips a leading BOM (Windows editors / PowerShell
+        # Out-File default to UTF-8-with-BOM); plain utf-8 would leave it on line 1
+        # and break the "---" frontmatter check.
+        with open(path, encoding="utf-8-sig", errors="replace") as f:
+            text = f.read()
+    except OSError:
+        return {}
+    return frontmatter_text(text)
+
+
+def count_matches_text(text, pattern):
+    """Regex match count against already-read `text` (see count_matches() for the
+    on-disk counterpart — the pure text half, extracted for performance-003)."""
+    return len(re.findall(pattern, text or "", re.MULTILINE))
+
+
+def count_matches(path, pattern):
+    try:
+        with open(path, encoding="utf-8", errors="replace") as f:
+            text = f.read()
+    except OSError:
+        return 0
+    return count_matches_text(text, pattern)
+
+
+def _arbiter_mtime_key(cad):
+    """Max mtime across the arbiter input files (missing files stat as -1.0). Two
+    renders with the same key saw identical inputs, so the cached state is valid."""
+    latest = -1.0
+    for nm in _ARBITER_FILES:
+        try:
+            latest = max(latest, os.stat(os.path.join(cad, nm)).st_mtime)
+        except OSError:
+            pass
+    return latest
+
+
+def _arbiter_enabled(ctx_path, frontmatter_enabled=None, ctx_text=None):
+    """The arbiter-enabled gate, owned by _hooklib.frontmatter_enabled when the lib
+    is importable (so the box and the enforcement hooks agree on the activation
+    contract). Falls back to the local frontmatter() parser only if the import
+    failed — the defensive degrade path, never a hard dependency.
+
+    When `ctx_text` is supplied (performance-003: the caller already read
+    CONTEXT.md), the decision is made from that text — no re-read of ctx_path."""
+    if ctx_text is not None:
+        return frontmatter_text(ctx_text).get("arbiter", "").lower() == "enabled"
+    if frontmatter_enabled is not None:
+        try:
+            enabled, _malformed = frontmatter_enabled(ctx_path)
+            return enabled
+        except Exception:  # noqa: BLE001 — degrade to the local parser, never crash
+            pass
+    return frontmatter(ctx_path).get("arbiter", "").lower() == "enabled"
+
+
+def arbiter_state(root, count_in_flight=None, read_board=None, frontmatter_enabled=None,
+                   ctx_text=None, ot_text=None, oq_text=None):
+    cad = os.path.join(root, ".codearbiter")
+    mkey = _arbiter_mtime_key(cad)
+    cached = _ARBITER_CACHE.get(root)
+    if cached is not None and cached[0] == mkey:
+        return cached[1]
+    result = _arbiter_state_uncached(cad, count_in_flight, read_board, frontmatter_enabled,
+                                      ctx_text=ctx_text, ot_text=ot_text, oq_text=oq_text)
+    _ARBITER_CACHE[root] = (mkey, result)
+    return result
+
+
+def _arbiter_state_uncached(cad, count_in_flight=None, read_board=None, frontmatter_enabled=None,
+                             ctx_text=None, ot_text=None, oq_text=None):
+    ctx_path = os.path.join(cad, "CONTEXT.md")
+    if not _arbiter_enabled(ctx_path, frontmatter_enabled, ctx_text=ctx_text):
+        return None
+    # performance-003: reuse the caller's already-read CONTEXT.md/open-tasks.md/
+    # open-questions.md text when supplied, instead of a second disk read. `None`
+    # (the default) preserves the exact original read-from-disk behavior.
+    fm = frontmatter_text(ctx_text) if ctx_text is not None else frontmatter(ctx_path)
+    total_over = count_matches(os.path.join(cad, "overrides.log"), r"^(?!\s*#)(?!\s*$).+")
+    # last-checkpoint holds the override COUNT at the last /ca:checkpoint. A value
+    # outside [0, total] is not a valid count (e.g. a timestamp from a stale writer)
+    # -> fail safe to 0 so overrides are surfaced, never silently hidden.
+    try:
+        with open(os.path.join(cad, "last-checkpoint"), encoding="utf-8") as f:
+            base = int(f.read().strip() or "0")
+    except (OSError, ValueError):
+        base = 0
+    if base < 0 or base > total_over:
+        base = 0
+    ot_path = os.path.join(cad, "open-tasks.md")
+    if count_in_flight is not None:
+        board_text = ot_text if ot_text is not None else (read_board(ot_path) or "")
+        tasks = count_in_flight(board_text)
+    else:
+        # Degraded fallback (only if _taskboardlib failed to import): mirror
+        # count_in_flight's done-exclusion inline so the segment never silently
+        # re-inflates to the pre-schema count. Never crashes the box.
+        tasks = (count_matches_text(ot_text, r"^- (?!\[[xX]\])") if ot_text is not None
+                 else count_matches(ot_path, r"^- (?!\[[xX]\])"))
+    q = (count_matches_text(oq_text, r"CONFIRM-[0-9]+") if oq_text is not None
+         else count_matches(os.path.join(cad, "open-questions.md"), r"CONFIRM-[0-9]+"))
+    return {
+        "stage": fm.get("stage", "-"),
+        "tasks": tasks,
+        "q": q,
+        "over": max(0, total_over - base),
+        "sprint": os.path.exists(os.path.join(cad, "sprint-active")),
+    }
+
+
+def dev_active(root):
+    """True when /dev developer-override mode is on — signalled by a transient marker
+    the orchestrator drops on /dev and clears on /arbiter (a local UI flag, not a log).
+
+    Presence-only by design, unaffected by #271 C-5's session-scoped clearing:
+    the marker still means "dev mode is on for SOMEONE" regardless of which
+    session owns it. Session-scoping only changes WHEN SessionStart is willing
+    to clear a live marker (never a different, possibly still-live session's
+    own marker) — it does not change what "present" means to this reader."""
+    return os.path.exists(os.path.join(root, ".codearbiter", ".markers", "dev-active"))

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

@@ -0,0 +1,76 @@
+"""pr-babysitter config resolution (Feature 2).
+
+A pure config-resolution unit for the pr-babysitter command. This module holds
+NO command behavior — only the env-driven resolver that decides whether the
+babysitter is enabled and how it reacts to a red gate. The command behavior is
+authored as prose in a later task.
+
+Environment variables
+---------------------
+CODEARBITER_BABYSIT
+    Master switch. Accepted "on" spellings (case-insensitive): ``on``, ``true``,
+    ``1``. Anything else — including absent, empty, or an unknown value —
+    resolves to OFF. Default: OFF (PB-8). Even when set on, the babysitter is
+    two-layer gated on arbiter dormancy: it stays OFF unless ``arbiter_active``
+    reports the repo opted in (PB-10). It is NEVER auto-enabled.
+
+CODEARBITER_BABYSIT_ONRED
+    What to do when the gate goes red. Normalized lowercase; one of ``propose``
+    or ``branch``. Any unknown, empty, or absent value resolves to ``propose``.
+    Default: ``propose`` (PB-5).
+"""
+
+_ON_VALUES = ("on", "true", "1")
+_ONRED_VALUES = ("propose", "branch")
+_ONRED_DEFAULT = "propose"
+
+
+def babysit_config(env, root, arbiter_active=None):
+    """Resolve the pr-babysitter config from ``env`` (a dict) for ``root``.
+
+    ``env`` and ``root`` are explicit parameters — this resolver never reads or
+    mutates ``os.environ``. ``arbiter_active`` is injected (defaulting to
+    ``_hooklib.arbiter_active``) so tests can pass a stub for the dormancy gate.
+
+    Returns a dict with at least ``enabled`` (bool) and ``on_red`` (str).
+    """
+    if arbiter_active is None:
+        import _hooklib
+        arbiter_active = _hooklib.arbiter_active
+
+    raw = (env.get("CODEARBITER_BABYSIT", "off") or "off").lower()
+    switched_on = raw in _ON_VALUES
+    # PB-10: two-layer gate — the env switch never overrides arbiter dormancy.
+    enabled = switched_on and bool(arbiter_active(root))
+
+    on_red = (env.get("CODEARBITER_BABYSIT_ONRED", "") or "").lower()
+    if on_red not in _ONRED_VALUES:
+        on_red = _ONRED_DEFAULT  # PB-5
+
+    return {"enabled": enabled, "on_red": on_red}
+
+
+def main(argv=None):
+    """CLI shim: resolve the babysitter config against the live environment and
+    print it as one JSON line, so /ca:pr and /ca:watch invoke this single
+    resolver instead of re-implementing the flag check in prose (no drift from
+    the accepted on|true|1 spellings or the PB-10 dormancy gate). Fail-safe:
+    any error degrades to the OFF default and still exits 0 — a broken resolver
+    must never become a reason to auto-attach a watcher.
+
+    Import-only module (no `__main__` entry point, per the thin-entry-hook
+    convention): the thin entry hook `babysit.py` imports and calls this
+    function; this underscore module is never run as a script directly."""
+    import argparse
+    import json
+    import os
+
+    parser = argparse.ArgumentParser(add_help=True)
+    parser.add_argument("--root", default=os.getcwd())
+    args = parser.parse_args(argv)
+    try:
+        cfg = babysit_config(os.environ, args.root)
+    except Exception:  # noqa: BLE001
+        cfg = {"enabled": False, "on_red": _ONRED_DEFAULT}
+    print(json.dumps(cfg))
+    return 0