loop-engineering-harness 1.0.0

package/template/.claude/hooks/divergence-monitor.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""divergence-monitor.py — PostToolUse hook on Edit|Write (DevelopmentUpdates.md §5).
+
+The footprint-violation detector: the approved plan *declared* which files each
+task may touch, so any write outside that set is, by definition, implementation
+wandering from the approved plan — divergence made measurable. It is the sharpest
+goal-diversion signal precisely because footprints already live on disk in
+task-graph.json; no agent judgment is involved (design principle D-3).
+
+Thresholds (harness.config.json → circuit_breaker.footprint_violations):
+  warn (default 1)  -> record + warn on stderr, let the run continue
+  halt (default 2)  -> record + trip the breaker in state.json; exit 2 so the
+                       subagent sees it immediately. dispatch-gate G3 then refuses
+                       every further dispatch until a human resolves it.
+
+Always safe: if there is no task in flight (.current.json absent) the edit is not
+a pipeline edit and passes untouched. Harness/runtime paths are never policed.
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import harness_lib as lib  # noqa: E402
+import loop_lib as loop  # noqa: E402
+
+IGNORE_PREFIXES = ("specs/", ".claude/", "graphify-out/", ".git/")
+
+
+def rel_to_repo(root, file_path):
+    if not file_path:
+        return None
+    ap = file_path if os.path.isabs(file_path) else os.path.join(root, file_path)
+    rel = os.path.relpath(os.path.abspath(ap), os.path.abspath(root))
+    return rel.replace("\\", "/")
+
+
+def main():
+    event = lib.read_hook_input()
+    if event.get("tool_name") not in ("Edit", "Write", "MultiEdit"):
+        lib.allow()
+
+    root = lib.project_dir(event)
+    ti = event.get("tool_input", {}) or {}
+    rel = rel_to_repo(root, ti.get("file_path"))
+    if not rel:
+        lib.allow()
+
+    feature_dir = lib.current_feature_dir(root)
+    if not feature_dir:
+        lib.allow()
+    cur = loop.read_current(feature_dir)
+    if not cur or not cur.get("task_id"):
+        lib.allow()  # no task in flight -> not a policed pipeline edit
+
+    # never police harness/runtime artifacts
+    if any(rel == p.rstrip("/") or rel.startswith(p) for p in IGNORE_PREFIXES):
+        lib.allow()
+
+    task_id = cur["task_id"]
+    graph = lib.read_json(os.path.join(feature_dir, "task-graph.json"), default={}) or {}
+    task = next((t for t in graph.get("tasks", []) if t.get("id") == task_id), None)
+    if task is None:
+        lib.allow()  # unknown task -> don't invent a violation
+
+    footprint = task.get("footprint", [])
+    if loop.in_footprint(rel, footprint):
+        lib.allow()  # inside the declared footprint — all good
+
+    # ---- violation ----------------------------------------------------
+    config = lib.load_config(root)
+    cb = (config.get("circuit_breaker", {}) or {}).get("footprint_violations", {}) or {}
+    warn_at, halt_at = int(cb.get("warn", 1)), int(cb.get("halt", 2))
+
+    div = lib.read_json(loop.divergence_path(feature_dir), default={}) or {}
+    fpv = div.setdefault("footprint_violations", {})
+    fpv[task_id] = int(fpv.get(task_id, 0)) + 1
+    div.setdefault("events", []).append({"task": task_id, "file": rel})
+    lib.write_json(loop.divergence_path(feature_dir), div)
+
+    # recompute health from disk and persist (health is derived; writers converge)
+    state = lib.read_json(os.path.join(feature_dir, "state.json"), default={}) or {}
+    state.setdefault("tasks", {})
+    loop.recompute_health(state, feature_dir, config)
+    lib.write_json(os.path.join(feature_dir, "state.json"), state)
+
+    total = sum(fpv.values())
+    msg = ("Footprint violation: task '%s' wrote '%s', outside its declared "
+           "footprint %s. Violations this feature: %d." % (task_id, rel, footprint, total))
+    if total >= halt_at:
+        lib.deny(msg + " Circuit breaker TRIPPED — all further dispatch is refused. "
+                       "Escalate to the user with the evidence in state.json / divergence.json.")
+    if total >= warn_at:
+        lib.warn(msg + " (warning; breaker trips at %d)" % halt_at)
+    lib.allow()
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/hooks/harness_lib.py

@@ -0,0 +1,260 @@
+"""harness_lib.py — tiny shared IO layer for the Loop Engineering hooks.
+
+Design rule (Architecture.md §1): agents do judgment, scripts do computation.
+This module is pure computation + IO. It never blocks; callers decide policy
+via exit codes. Everything here fails *open* — a missing config, an unparseable
+state file, or an absent graphify install must never crash a hook and wedge the
+user's session. A crashed hook is worse than an un-enforced one.
+"""
+
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+
+# ---------------------------------------------------------------------------
+# Config defaults. harness.config.json (repo root) overrides these shallowly.
+# ---------------------------------------------------------------------------
+DEFAULT_CONFIG = {
+    "graphify": {"binary": "graphify", "index_path": "graphify-out/"},
+    "retries": {"mechanical": 2, "contract": 1, "ambiguity": 0, "security": 0},
+    "dependency_depth": 1,
+    "retrieval_nudge": {
+        # "block" -> exit 2 (deny + steer). "warn" -> exit 0 with a note. "off".
+        "mode": "block",
+        # broad searches over more than this many chars of pattern still pass if
+        # they are scoped to a single existing file (see is_broad_search).
+        "auto_init": True,
+    },
+    "observability": {"provider": "langfuse", "enabled": True},
+    "gates": {"commit_requires_integration_review": True, "commit_requires_version": True},
+    "versioning": {
+        "enabled": True,
+        "manifests": ["package.json", "requirements.txt", "pyproject.toml", "go.mod", "Cargo.toml"],
+        "require_major_dep_ack": True,
+        "require_code_bump": True,
+        "require_dev_history": True,
+    },
+    # ---- V1.0 loop layer (DevelopmentUpdates.md) -------------------------
+    "budgets": {
+        "context_pack": 2000,
+        "task_entry": 300,
+        "review_findings": 500,
+        "per_task_default": 15000,
+        "dispatch_prompt_max": 8000,
+    },
+    "circuit_breaker": {
+        "footprint_violations": {"warn": 1, "halt": 2},
+        "max_escalations_per_feature": 2,
+        "burndown": {"warn_pct": 80, "halt_pct": 100},
+    },
+    "requirements": {
+        "enabled": True,
+        "min_acceptance_criteria": 1,
+        "require_coverage": True,
+    },
+    "loop": {
+        "queue": "specs/_queue.json",
+        "answer_queue": "specs/_answers.json",
+        "headless": True,
+        "auto_approve": False,
+    },
+}
+
+
+def read_hook_input():
+    """Parse the JSON object Claude Code writes to a hook's stdin.
+
+    Returns {} on any error so a malformed payload degrades to pass-through
+    rather than a stack trace in the user's terminal.
+    """
+    try:
+        raw = sys.stdin.read()
+        return json.loads(raw) if raw.strip() else {}
+    except Exception:
+        return {}
+
+
+def project_dir(hook_input=None):
+    """Resolve the adopter repo root.
+
+    CLAUDE_PROJECT_DIR is set by Claude Code for every hook; fall back to the
+    hook payload's cwd, then the process cwd.
+    """
+    env = os.environ.get("CLAUDE_PROJECT_DIR")
+    if env:
+        return os.path.abspath(env)
+    if hook_input and hook_input.get("cwd"):
+        return os.path.abspath(hook_input["cwd"])
+    return os.path.abspath(os.getcwd())
+
+
+def _deep_merge(base, override):
+    out = dict(base)
+    for k, v in (override or {}).items():
+        if isinstance(v, dict) and isinstance(out.get(k), dict):
+            out[k] = _deep_merge(out[k], v)
+        else:
+            out[k] = v
+    return out
+
+
+def load_config(root):
+    """Read harness.config.json merged over DEFAULT_CONFIG. Fail-open to defaults."""
+    path = os.path.join(root, "harness.config.json")
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            return _deep_merge(DEFAULT_CONFIG, json.load(fh))
+    except Exception:
+        return dict(DEFAULT_CONFIG)
+
+
+# ---------------------------------------------------------------------------
+# Feature / spec artifact chain
+# ---------------------------------------------------------------------------
+def specs_root(root):
+    return os.path.join(root, "specs")
+
+
+def current_feature_dir(root):
+    """The active feature = the specs/<f>/ dir with the most recently touched
+    state.json (falling back to directory mtime). Returns None if no features.
+
+    The orchestrator only works one feature at a time; recency is a good-enough
+    and fully deterministic-per-filesystem selector without extra bookkeeping.
+    """
+    sroot = specs_root(root)
+    if not os.path.isdir(sroot):
+        return None
+    best, best_mtime = None, -1.0
+    for name in os.listdir(sroot):
+        d = os.path.join(sroot, name)
+        if not os.path.isdir(d):
+            continue
+        marker = os.path.join(d, "state.json")
+        try:
+            mtime = os.path.getmtime(marker if os.path.exists(marker) else d)
+        except OSError:
+            continue
+        if mtime > best_mtime:
+            best, best_mtime = d, mtime
+    return best
+
+
+def read_json(path, default=None):
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            return json.load(fh)
+    except Exception:
+        return default
+
+
+def write_json(path, obj):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as fh:
+        json.dump(obj, fh, indent=2, ensure_ascii=False)
+    os.replace(tmp, path)
+
+
+# ---------------------------------------------------------------------------
+# Graphify state — the heart of the retrieval nudge
+# ---------------------------------------------------------------------------
+def graphify_state(root, config=None):
+    """Return the graphify readiness of this repo.
+
+    {
+      "installed":   bool,  # binary on PATH or a saved interpreter recorded
+      "graph_built": bool,  # graphify-out/graph.json exists (queryable now)
+      "index_path":  str,   # resolved absolute index dir
+      "graph_json":  str,   # resolved absolute graph.json path
+    }
+    Cheap by design: only shutil.which + os.path.exists. No subprocess, so it is
+    safe to call on every Grep/Glob PreToolUse without adding latency.
+    """
+    config = config or load_config(root)
+    binary = config.get("graphify", {}).get("binary", "graphify")
+    index_rel = config.get("graphify", {}).get("index_path", "graphify-out/")
+    index_path = os.path.join(root, index_rel)
+    graph_json = os.path.join(index_path, "graph.json")
+
+    saved_interp = os.path.join(index_path, ".graphify_python")
+    installed = bool(shutil.which(binary)) or os.path.exists(saved_interp)
+
+    return {
+        "installed": installed,
+        "graph_built": os.path.exists(graph_json),
+        "index_path": index_path,
+        "graph_json": graph_json,
+    }
+
+
+def graphify_used_this_session(transcript_path):
+    """Best-effort scan of the session transcript for prior graph-first retrieval.
+
+    True if any earlier tool call ran `graphify query|path|explain` or read from
+    graphify-out/. Used so the nudge fires once and then gets out of the way —
+    it steers the *first* broad search of a task, not every subsequent one.
+
+    Reads at most the tail of the transcript to bound cost.
+    """
+    if not transcript_path or not os.path.exists(transcript_path):
+        return False
+    needles = ("graphify query", "graphify path", "graphify explain", "graphify-out")
+    try:
+        # Transcripts are JSONL and can be large; read the last ~512 KB only.
+        size = os.path.getsize(transcript_path)
+        with open(transcript_path, "r", encoding="utf-8", errors="ignore") as fh:
+            if size > 512 * 1024:
+                fh.seek(size - 512 * 1024)
+                fh.readline()  # discard partial line
+            blob = fh.read()
+        return any(n in blob for n in needles)
+    except Exception:
+        return False
+
+
+def git_changeset(root):
+    """A stable fingerprint of the current pending diff (staged + unstaged vs HEAD).
+
+    The commit gate compares this to the `changeset` recorded in the integration
+    review verdict — a review only opens the gate for the diff it actually saw.
+    The reviewer agent records its changeset with this same helper (see
+    scripts/changeset.py) so the two always agree. Returns None outside a repo.
+    """
+    try:
+        inside = subprocess.run(
+            ["git", "rev-parse", "--is-inside-work-tree"],
+            cwd=root, capture_output=True, text=True, timeout=15)
+        if inside.returncode != 0 or inside.stdout.strip() != "true":
+            return None  # not a git repo -> no diff to fingerprint
+        parts = []
+        for args in (["git", "diff", "HEAD"], ["git", "diff", "--cached"]):
+            r = subprocess.run(args, cwd=root, capture_output=True, text=True, timeout=15)
+            parts.append(r.stdout or "")
+        blob = "\n".join(parts)
+        return "sha1:" + hashlib.sha1(blob.encode("utf-8", "ignore")).hexdigest()[:16]
+    except Exception:
+        return None
+
+
+def deny(message):
+    """Emit a PreToolUse block: stderr message + exit code 2.
+
+    Exit 2 is the Claude Code contract for "deny this tool call and feed stderr
+    back to the model" — the message becomes steering, not a user-facing error.
+    """
+    sys.stderr.write(message.rstrip() + "\n")
+    sys.exit(2)
+
+
+def warn(message):
+    """Non-blocking note: surfaced to the model, tool still runs (exit 0)."""
+    sys.stderr.write(message.rstrip() + "\n")
+    sys.exit(0)
+
+
+def allow():
+    sys.exit(0)

package/template/.claude/hooks/loop_lib.py

@@ -0,0 +1,108 @@
+"""loop_lib.py — shared helpers for the V1.0 loop layer (DevelopmentUpdates.md).
+
+Two things live here so the divergence-monitor and the state-updater agree
+byte-for-byte on what "healthy" means:
+
+  * footprint matching (is this file inside a task's declared footprint?)
+  * recompute_health() — derive state.json's `health` from disk signals ONLY.
+
+Design principle D-3: divergence is detected mechanically from disk, never by an
+agent's self-assessment. `health` is therefore a pure function of on-disk
+artifacts (review verdicts in state.json + footprint counts in divergence.json +
+the approved budget). Any hook can recompute it and land on the same answer, so
+it does not matter who writes it last — they converge.
+"""
+
+import fnmatch
+import os
+
+_here = os.path.dirname(os.path.abspath(__file__))
+import sys
+sys.path.insert(0, _here)
+import harness_lib as lib  # noqa: E402
+
+DEFAULT_CAPS = {"mechanical": 2, "contract": 1, "ambiguity": 0, "security": 0}
+
+
+def _norm(p):
+    return str(p).replace("\\", "/").strip()
+
+
+def in_footprint(rel_path, footprint):
+    """True if rel_path is covered by any footprint entry (dir/, file, or glob).
+    Mirrors extract-deps.py matching so the gate and the plan speak one language."""
+    rel = _norm(rel_path)
+    for entry in footprint or []:
+        e = _norm(entry)
+        if not e:
+            continue
+        if e.endswith("/") and rel.startswith(e):
+            return True
+        if any(c in e for c in "*?[") and fnmatch.fnmatch(rel, e):
+            return True
+        if rel == e or rel.startswith(e + "/"):
+            return True
+    return False
+
+
+def read_current(spec_dir):
+    """The task the dispatch-gate marked in flight (or None)."""
+    return lib.read_json(os.path.join(spec_dir, ".current.json"))
+
+
+def divergence_path(spec_dir):
+    return os.path.join(spec_dir, "divergence.json")
+
+
+def recompute_health(state, spec_dir, config):
+    """Derive and set state['health'] / state['health_reasons'] from disk signals.
+
+    Mutates and returns `state`; the CALLER writes state.json (so there is one
+    write per hook invocation). Every reason added is a HALT-level condition —
+    health flips to 'tripped' iff at least one is present, which is what
+    dispatch-gate G3 refuses on. Warn-level signals (e.g. a first footprint
+    violation) intentionally do not trip; they wait for the halt threshold.
+    """
+    caps = {**DEFAULT_CAPS, **config.get("retries", {})}
+    cb = config.get("circuit_breaker", {})
+    max_esc = int(cb.get("max_escalations_per_feature", 2))
+    halt_fp = int((cb.get("footprint_violations", {}) or {}).get("halt", 2))
+    halt_pct = int((cb.get("burndown", {}) or {}).get("halt_pct", 100))
+
+    reasons = []
+    tasks = state.get("tasks", {}) or {}
+
+    for tid, t in sorted(tasks.items()):
+        fc = t.get("pending_failure_class")
+        if fc:
+            cap = int(caps.get(fc, 0))
+            if int(t.get("attempts", 0)) > cap:
+                reasons.append("retry_cap:%s(class=%s,attempts=%s,cap=%s)"
+                               % (tid, fc, t.get("attempts", 0), cap))
+            if fc in ("ambiguity", "security"):
+                reasons.append("zero_retry_class:%s(%s)" % (tid, fc))
+        if t.get("status") == "escalate" or t.get("repeat_finding"):
+            reasons.append("repeat_finding:%s" % tid)
+
+    escalations = sum(1 for t in tasks.values() if t.get("status") == "escalate")
+    if escalations > max_esc:
+        reasons.append("too_many_escalations:%d>%d (feature likely over-scoped)"
+                       % (escalations, max_esc))
+
+    div = lib.read_json(divergence_path(spec_dir), default={}) or {}
+    fp_total = sum((div.get("footprint_violations", {}) or {}).values())
+    if fp_total >= halt_fp:
+        reasons.append("footprint_violations:%d>=halt %d" % (fp_total, halt_fp))
+
+    # Token burndown vs the approved budget, if both are on disk.
+    spent = div.get("tokens_spent")
+    approvals = lib.read_json(os.path.join(spec_dir, "approvals.json"), default={}) or {}
+    budget = approvals.get("budget")
+    if isinstance(spent, (int, float)) and isinstance(budget, (int, float)) and budget > 0:
+        pct = 100.0 * spent / budget
+        if pct >= halt_pct:
+            reasons.append("burndown:%d%%>=halt %d%%" % (int(pct), halt_pct))
+
+    state["health"] = "tripped" if reasons else "ok"
+    state["health_reasons"] = reasons
+    return state

package/template/.claude/hooks/precompact-guard.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""
+precompact-guard.py — PreCompact hook.
+
+Design intent (Rule 4, DevelopmentUpdates.md): we do NOT fight compaction —
+we make the pipeline indifferent to it. This hook's job is to guarantee that
+the load-bearing minimum survives on DISK before the context window is
+compressed:
+
+    - current feature        (pointer to specs/<f>/)
+    - current task id
+    - current pipeline phase
+    - attempt counters / breaker health (already in state.json)
+
+It writes a tiny snapshot file, specs/<f>/pipeline-context.md, that the
+SessionStart(source=compact) rehydration hook injects back into context
+right after compaction. Everything else in the window is allowed to
+compact freely, because it can be re-read from specs/ on demand.
+
+PreCompact hooks cannot block compaction — and we don't want to. Exit 0 always.
+"""
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+REPO = Path.cwd()
+ACTIVE_POINTER = REPO / "specs" / "_active.json"  # {"feature": "...", maintained by state-updater}
+
+
+def main() -> None:
+    try:
+        event = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)  # never break compaction
+
+    if not ACTIVE_POINTER.exists():
+        sys.exit(0)  # no pipeline in flight — nothing to protect
+
+    try:
+        feature = json.loads(ACTIVE_POINTER.read_text(encoding="utf-8")).get("feature")
+    except (json.JSONDecodeError, OSError):
+        sys.exit(0)
+    if not feature:
+        sys.exit(0)
+
+    spec = REPO / "specs" / feature
+    state_p = spec / "state.json"
+    state = {}
+    if state_p.exists():
+        try:
+            state = json.loads(state_p.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            state = {}
+
+    current_task = state.get("current_task", "unknown")
+    phase = state.get("phase", "unknown")
+    health = state.get("health", "ok")
+
+    snapshot = f"""# PIPELINE CONTEXT SNAPSHOT (load-bearing minimum)
+_Written by precompact-guard at {datetime.now(timezone.utc).isoformat()} \
+(trigger: {event.get('trigger', 'unknown')})_
+
+- **FEATURE:** {feature}
+- **ARTIFACTS:** specs/{feature}/  <- re-read plan.md, task-graph.json,
+  state.json, contracts/ from here instead of relying on compacted memory.
+- **CURRENT TASK:** {current_task}
+- **PIPELINE PHASE:** {phase}
+- **BREAKER HEALTH:** {health}
+
+## Standing orders after compaction
+1. Treat this snapshot + specs/{feature}/ as the ONLY source of truth.
+   Do not trust compacted recollections of plan details or review findings.
+2. Resume by re-reading state.json, then continue dispatching per
+   task-graph.json. dispatch-gate.py will enforce order, approval hash,
+   retry caps, and breaker state regardless.
+3. Never read source code or raw diffs into this (orchestrator) context —
+   that work belongs to subagents (compression funnel, Rule 2).
+"""
+    try:
+        spec.mkdir(parents=True, exist_ok=True)
+        (spec / "pipeline-context.md").write_text(snapshot, encoding="utf-8")
+    except OSError as e:
+        print(f"[precompact-guard] snapshot write failed: {e}", file=sys.stderr)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()