@arbiterforge/ca-pi 0.6.0

package/plugins/ca-pi/hooks/init-codearbiter.py

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+# codeArbiter — first-run scaffolder. Creates the root-level .codearbiter/ project
+# state directory that opts a repo into arbiter management. Idempotent: it never
+# overwrites a file that already exists, so it is safe to re-run.
+#
+# The `arbiter: enabled` frontmatter in CONTEXT.md is the single activation flag —
+# it gates both the SessionStart persona injection and the arbiter statusline
+# segments. CONTEXT.md is scaffolded WITHOUT the <!--INITIALIZED--> body sentinel,
+# so the next session routes to /ca:create-context (source exists) or /ca:decompose
+# (greenfield) to populate it.
+#
+# Usage:
+#   python init-codearbiter.py [--root PATH] [--stage N]
+#   python init-codearbiter.py --check        # report state, create nothing
+
+import argparse
+import subprocess
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from _gitexec import git_executable  # noqa: E402
+import hostapi  # noqa: E402 — host seam (ADR-0011)
+import _hooklib  # noqa: E402 — set_host DI seam (#257)
+import _entrylib  # noqa: E402 — shared run() dispatch (jscpd dedup)
+
+# NOTE: this stub deliberately does NOT contain the initialization sentinel
+# (an HTML comment wrapping the word INITIALIZED). The SessionStart hook greps
+# for that exact token to decide whether the project is populated, so emitting it
+# here — even inside a comment — would falsely mark an empty stub as initialized.
+# The populator flow (/ca:create-context or /ca:decompose) adds it on its own line.
+CONTEXT = """\
+---
+arbiter: enabled
+stage: {stage}
+---
+
+# Project: {name}
+
+<!-- This .codearbiter/ directory is the root-level project-state store. It lives
+outside .claude/ so it survives even if the codeArbiter plugin is uninstalled.
+The `arbiter: enabled` frontmatter above is the activation flag.
+
+This CONTEXT.md is a stub: it carries no initialization sentinel yet, so the
+orchestrator routes you to {create_context} (if source already exists) or
+{decompose} (greenfield) to populate the real project context. That flow writes
+the sentinel and normal operation begins. -->
+
+_Not yet initialized. Run {create_context} or {decompose} to populate._
+"""
+
+OPEN_TASKS = """\
+# Open tasks
+
+In-flight and queued work. One top-level `- ` bullet per task; the statusline and
+SessionStart hook count these, EXCLUDING done (`- [x]`).
+
+Schema (one task = a lifecycle line + indented content sub-bullets):
+
+```
+- [~] poc.auth.0001 - Validate session tokens  (started 2026-06-18)
+  - Desc: reject expired/forged tokens at the auth middleware
+  - Done when: an expired token returns 401; a valid one passes
+  - Boundaries: auth, secrets
+```
+
+- Marker: `[ ]` queued | `[~]` in-progress | `[x]` done. In-progress and done
+  carry a dated `(started YYYY-MM-DD)` / `(done YYYY-MM-DD)` parenthetical; a
+  stale `[~]` is surfaced at SessionStart.
+- ID `<group>.<type>.<seq>`: `group` = build phase (poc/mvp1/v1...), `type` =
+  domain (auth/api/ui/infra...), `seq` = >=4-digit, numbered within each
+  `group.type`. ID + title + marker are required.
+- `Desc` / `Done when` / `Boundaries` are filled when known (`TBD` until then).
+  Keep `Done when` to one coarse sentence — per-step verification belongs to a
+  plan, not here. `Boundaries` names the security/trust boundary the task is
+  expected to touch (auth, crypto, secrets, ...).
+"""
+
+OPEN_QUESTIONS = """\
+# Open questions
+
+Unresolved `[CONFIRM-NN]` items. Each blocks dependent work until resolved.
+The SessionStart hook and statusline count `CONFIRM-NN` occurrences here.
+
+_None open._
+"""
+
+OVERRIDES = """\
+# codeArbiter override log - append-only audit artifact. Never edit or delete prior lines.
+# Format: [ISO-8601] | BY: <name> <<email>> | GATE: <gate bypassed> | REASON: <reason>
+# Written only by /override. The statusline counts non-comment lines after the
+# last-checkpoint marker as "overrides since last checkpoint."
+"""
+
+DONE_TASKS = """\
+# Done tasks
+
+Completed work swept off the board by `taskwrite archive`, newest last.
+APPEND-ONLY: entries are added here and never edited or removed, so a
+finished task has exactly one permanent record.
+
+Each line is the task's original lifecycle line, moved verbatim from
+`open-tasks.md` with its `(done YYYY-MM-DD)` stamp intact — the stamp is
+what makes an entry ageable, and what `archive` refuses to invent.
+
+Written only by `taskwrite archive`. `/ca:standup` proposes the sweep with
+per-item confirmation; nothing sweeps automatically.
+"""
+
+FILES = {
+    "open-tasks.md": OPEN_TASKS,
+    # B-23: scaffolded at init rather than created on first archive. An
+    # append-only file that springs into existence mid-sweep has no
+    # reviewed initial content and no header explaining what it is — and
+    # `archive`'s first write would be the thing that defines the format.
+    "done-tasks.md": DONE_TASKS,
+    "open-questions.md": OPEN_QUESTIONS,
+    "overrides.log": OVERRIDES,
+    "last-checkpoint": "0\n",
+}
+
+
+def project_root(opt):
+    if opt:
+        return os.path.abspath(opt)
+    # prefer git toplevel; fall back to cwd
+    try:
+        out = subprocess.run([git_executable(), "rev-parse", "--show-toplevel"],
+                             capture_output=True, text=True, timeout=2)
+        top = out.stdout.strip()
+        if out.returncode == 0 and top:
+            return os.path.abspath(top)
+    except Exception:
+        pass
+    return os.path.abspath(os.getcwd())
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(add_help=True)
+    ap.add_argument("--root")
+    ap.add_argument("--stage", type=int, default=1)
+    ap.add_argument("--check", action="store_true")
+    args = ap.parse_args(argv)
+
+    root = project_root(args.root)
+    cad = os.path.join(root, ".codearbiter")
+    ctx = os.path.join(cad, "CONTEXT.md")
+    # Host-native command spellings for every populate pointer this scaffold
+    # emits or writes into the stub (codex-support M3): the same text must
+    # read /ca:create-context under Claude Code and $ca-create-context under
+    # Codex, or the very first thing a Codex-only user sees is a dead pointer.
+    _host = _hooklib.get_host()
+    _cc = _host.cmd_ref("create-context")
+    _dc = _host.cmd_ref("decompose")
+    name = os.path.basename(root.rstrip("/\\")) or "project"
+
+    if args.check:
+        if os.path.exists(ctx):
+            print(f"ALREADY SCAFFOLDED: {ctx} exists.")
+            with open(ctx, encoding="utf-8", errors="replace") as f:
+                text = f.read()
+            import re
+            initd = bool(re.search(r"(?m)^\s*<!--\s*INITIALIZED\s*-->\s*$", text))
+            print("arbiter: " + ("enabled" if re.search(r"(?m)^arbiter:\s*enabled\s*$", text) else "not enabled"))
+            print("initialized body: " + ("yes" if initd else
+                  "no (run " + _cc + " or " + _dc + ")"))
+        else:
+            print(f"NOT SCAFFOLDED: {cad} would be created. Run without --check to scaffold.")
+        return
+
+    if os.path.exists(ctx):
+        raise SystemExit(
+            f"REFUSING: {ctx} already exists. .codearbiter/ is already scaffolded here. "
+            f"To populate it, run {_cc} or {_dc}; to repair, edit by hand.")
+
+    os.makedirs(cad, exist_ok=True)
+    created = []
+    if not os.path.exists(ctx):
+        with open(ctx, "w", encoding="utf-8") as f:
+            f.write(CONTEXT.format(stage=args.stage, name=name,
+                                   create_context=_cc, decompose=_dc))
+        created.append("CONTEXT.md")
+    for fname, content in FILES.items():
+        fp = os.path.join(cad, fname)
+        if not os.path.exists(fp):
+            with open(fp, "w", encoding="utf-8") as f:
+                f.write(content)
+            created.append(fname)
+
+    # #161: install the git-level enforcement backstop (pre-commit/pre-push) so
+    # git mutations are gated at the operation itself, not only at the literal
+    # Bash command string. Best-effort — a repo without a git dir, or a foreign
+    # existing hook, is reported by install(), never fatal to scaffolding.
+    try:
+        sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+        from _githooks import install as _install_git_hooks
+        gh = _install_git_hooks(root)
+        if gh:
+            print("git hooks: " + ", ".join(gh))
+    except Exception as e:  # noqa: BLE001
+        print(f"git hooks: install skipped ({e})", file=sys.stderr)
+
+    print(f"SCAFFOLDED .codearbiter/ at {cad}")
+    print("created: " + ", ".join(created))
+    print(f"arbiter: enabled (stage {args.stage}); CONTEXT.md is a stub (no <!--INITIALIZED--> sentinel).")
+    print(f"Next: run {_cc} (source exists) or {_dc} (greenfield) to populate.")
+
+
+def run(host, argv=None):
+    """Host-seam entry point (ADR-0011): the __main__ guard calls this with the
+    plugin's loaded Host. Wraps main(argv) unchanged — main()'s 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 any `get_host()` call downstream
+    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, _hooklib.set_host,
+                               pass_argv=True, propagate_result=False)
+
+
+if __name__ == "__main__":
+    sys.exit(run(hostapi.load_host()) or 0)

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

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+# codeArbiter — thin entry point for /ca:metrics (architecture-006/#179).
+#
+# Wraps _metricslib.compute and prints its JSON-serialized result, so the
+# field-access/serialization step /ca:metrics needs is import-covered
+# (py_compile + unit tests) instead of living as an inline `python -c`
+# multi-statement block in command prose. Mirrors doctor.py / taskwrite.py:
+# entry point stays thin, all computation lives in _metricslib.
+#
+# Invoked by commands/metrics.md as (interpreter resolved once by presence,
+# never a `python3 X || python X` fold -- #577):
+#   "$PY" "<plugin>/hooks/metrics.py" --root "<dir>" [--window N]
+#
+# Read-only: _metricslib.compute() never writes; this wrapper only prints its
+# return value. json.dumps is called with its default ensure_ascii=True so the
+# arrow glyphs (up/down/right arrows) are ASCII-escaped on the way out — this
+# avoids a UnicodeEncodeError on Windows cp1252 consoles. Do NOT pass
+# ensure_ascii=False here; the command prose renders the real glyphs itself
+# from the parsed JSON, not from this process's raw stdout.
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import hostapi  # noqa: E402 — host seam (ADR-0011)
+import _hooklib  # noqa: E402 — set_host DI seam (#257)
+import _entrylib  # noqa: E402 — shared run() dispatch (jscpd dedup)
+import _metricslib  # noqa: E402
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="metrics", add_help=True)
+    parser.add_argument("--root", default=os.getcwd())
+    parser.add_argument("--window", type=int, default=None)
+    args = parser.parse_args(argv)
+
+    if args.window is not None:
+        result = _metricslib.compute(args.root, window_size=args.window)
+    else:
+        result = _metricslib.compute(args.root)
+    print(json.dumps(result))
+    return 0
+
+
+def run(host, argv=None):
+    """Host-seam entry point (ADR-0011): the __main__ guard calls this with the
+    plugin's loaded Host. Delegates to main(argv) and returns its exit code,
+    exactly as the old `sys.exit(main())` guard propagated it.
+
+    Wires `host` live (#257): primes `_hooklib`'s process-cached Host via
+    `set_host()` BEFORE main() runs, so any `get_host()` call downstream
+    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, _hooklib.set_host,
+                               pass_argv=True, propagate_result=True)
+
+
+if __name__ == "__main__":
+    sys.exit(run(hostapi.load_host()) or 0)

package/plugins/ca-pi/hooks/migration-pass.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+# codeArbiter — record a migration-review pass BOUND to the migration files it
+# approved (H-14, issue #77).
+#
+# There was no commit-time migration gate before #77: a migration committed via
+# bare /commit or the /feature small lane never reached migration-reviewer (the
+# /review, /pr, /checkpoint, and sprint lanes did dispatch it). commit-gate now
+# dispatches migration-reviewer when it classifies a staged migration and runs
+# THIS script on PASS. It mirrors security-pass.py: it hashes the content of
+# every staged/worktree/untracked migration file (detected by is_migration_path)
+# and writes the digests to .codearbiter/.markers/migration-gate-passed;
+# pre-bash.py's H-14 then admits a commit only when every migration file being
+# committed is in the recorded set.
+#
+# Binding is by content digest with no freshness window: a migration is
+# immutable, so a recorded pass stays valid while the content is unchanged, and
+# any edit changes the digest -> the backstop re-blocks (closing TOCTOU and
+# enforcing immutability at commit time).
+#
+# Invoked by skill prose as (interpreter resolved once by presence, never a
+# `python3 X || python X` fold -- #577):
+#   "$PY" "<plugin>/hooks/migration-pass.py"
+
+import os
+import subprocess
+
+from _gitexec import git_executable
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from _hooklib import (  # noqa: E402
+    content_digest, is_migration_path, marker_root, project_root, set_host,
+    utf8_stdio, warn, write_text_atomic,
+)
+
+MAX_FILE_BYTES = 1_000_000  # a blob bigger than this is not a reviewable migration
+
+
+def run_git(args, cwd):
+    return subprocess.run(
+        [git_executable()] + args, cwd=cwd, capture_output=True, text=True,
+        encoding="utf-8", errors="replace", timeout=30,
+    )
+
+
+def candidate_paths(root):
+    """Every path the next commit could introduce a migration through: tracked
+    changes vs HEAD (staged and unstaged), plus untracked files. On an unborn
+    branch (no HEAD) every tracked file is new content."""
+    paths = set()
+    for args in (["diff", "--cached", "--name-only"], ["diff", "--name-only"]):
+        r = run_git(args, root)
+        if r.returncode == 0:
+            paths.update(p for p in r.stdout.splitlines() if p.strip())
+    if not paths:
+        r = run_git(["ls-files"], root)
+        if r.returncode == 0:
+            paths.update(p for p in r.stdout.splitlines() if p.strip())
+    u = run_git(["ls-files", "--others", "--exclude-standard"], root)
+    if u.returncode == 0:
+        paths.update(p for p in u.stdout.splitlines() if p.strip())
+    return paths
+
+
+def read_text(root, rel):
+    p = os.path.join(root, rel)
+    try:
+        if os.path.getsize(p) > MAX_FILE_BYTES:
+            return None
+        with open(p, encoding="utf-8", errors="replace") as f:
+            return f.read()
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def main():
+    utf8_stdio()
+    root = project_root()
+    if not os.path.isdir(os.path.join(root, ".codearbiter")):
+        warn("no .codearbiter/ here — migration-pass.py records nothing outside "
+             "an initialized repo")
+        sys.exit(1)
+    migs = sorted(rel for rel in candidate_paths(root) if is_migration_path(rel, root))
+    digests = set()
+    for rel in migs:
+        text = read_text(root, rel)
+        if text is not None:
+            digests.add(content_digest(text))
+    # #604: same split as security-pass.py — candidate_paths(root)/read_text(root, …)
+    # above must stay bound to wherever this process is actually running (a
+    # linked worktree's own tree), but the MARKER write goes through
+    # marker_root(), which agrees with the H-14 guard's main-checkout-anchored
+    # read (D-2) even when this process has no CLAUDE_PROJECT_DIR set.
+    write_root = marker_root()
+    marker_dir = os.path.join(write_root, ".codearbiter", ".markers")
+    os.makedirs(marker_dir, exist_ok=True)
+    marker = os.path.join(marker_dir, "migration-gate-passed")
+    digests = sorted(digests)
+    # Atomic write (migration-002): a crash mid-write never leaves a half-written
+    # marker, which the backstop would read as an unrecognized digest and force a
+    # spurious gate re-run.
+    write_text_atomic(marker, "\n".join(digests) + ("\n" if digests else ""))
+    print(f"migration-gate pass recorded: {len(digests)} migration file(s) "
+          f"bound to {os.path.relpath(marker, write_root)}")
+
+
+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 any `get_host()` call downstream
+    resolves to the SAME instance the caller passed here — no second
+    `hostapi.load_host()`, and `run(fake_host)` genuinely exercises
+    `fake_host`."""
+    set_host(host)
+    main()
+    return 0
+
+
+if __name__ == "__main__":
+    # hostapi is imported here (not at module top) so OB-S1's stdlib-import
+    # scan of this producer keeps its exact allowlist; hostapi is the same-dir
+    # host seam (ADR-0011), stdlib-only like _hooklib.
+    import hostapi  # noqa: PLC0415
+    sys.exit(run(hostapi.load_host()) or 0)