loop-engineering-harness 1.0.0

package/template/.claude/hooks/req_lib.py

@@ -0,0 +1,148 @@
+"""req_lib.py — the requirements/intention quality checker (the extended human gate).
+
+Wrong implementations are born at the requirements and decomposition stages, not
+at code. This module detects — mechanically, from disk, never by asking an agent
+to grade itself (design principle D-3) — the four conditions that must summon a
+human before automation proceeds:
+
+  R1  ambiguous / unorganized intention   — Intent & Scope present, no unresolved
+                                            markers (TBD / ??? / "clarify" / …)
+  R2  vague / unstructured requirements    — required sections present, and >= N
+                                            structured acceptance criteria (AC1, AC2…)
+  R3  wrong flow                           — phase artifacts exist in order
+                                            (discovery -> context-pack -> plan -> graph)
+  R4  diverted from user requirements      — every acceptance criterion is covered
+                                            by a task; no task cites an AC that is
+                                            not in discovery.md (scope creep / drift)
+
+Each check returns a list of human-readable problem strings; empty == clean.
+"""
+
+import os
+import re
+
+REQUIRED_SECTIONS = ("intent", "edge case", "non-functional", "acceptance criteria")
+
+# Markers that mean the intention is not actually resolved yet.
+UNCERTAINTY = (
+    r"\bTBD\b", r"\bTODO\b", r"\bXXX\b", r"\?\?\?",
+    "to be decided", "to be determined", "not sure", "unclear",
+    "figure out later", "clarify with", "decide later", "revisit later",
+)
+
+AC_RE = re.compile(r"\bAC\d+\b")
+TASK_BLOCK_RE = re.compile(r"```task\s*\n(.*?)```", re.S)
+
+
+def _read(path):
+    try:
+        with open(path, "r", encoding="utf-8", errors="ignore") as fh:
+            return fh.read()
+    except OSError:
+        return None
+
+
+def _headers(text):
+    return "\n".join(l.strip().lower() for l in text.splitlines() if l.lstrip().startswith("#"))
+
+
+def acceptance_ids(spec_dir):
+    text = _read(os.path.join(spec_dir, "discovery.md")) or ""
+    return set(AC_RE.findall(text))
+
+
+def _satisfies(block):
+    m = re.search(r"^\s*satisfies:\s*(.*)$", block, re.M)
+    ids = set()
+    if m:
+        ids |= set(AC_RE.findall(m.group(1)))
+    # also allow a dash-list under `satisfies:`
+    for line in block.splitlines():
+        if re.match(r"^\s*-\s*AC\d+", line):
+            ids |= set(AC_RE.findall(line))
+    return ids
+
+
+def plan_task_coverage(spec_dir):
+    """Union of AC ids referenced across all plan.md task blocks."""
+    text = _read(os.path.join(spec_dir, "plan.md")) or ""
+    covered = set()
+    for block in TASK_BLOCK_RE.findall(text):
+        covered |= _satisfies(block)
+    return covered
+
+
+def check_discovery(spec_dir, cfg=None):
+    cfg = cfg or {}
+    disc = os.path.join(spec_dir, "discovery.md")
+    text = _read(disc)
+    if text is None:
+        return ["R1: discovery.md is missing — run the interview before any pipeline work."]
+
+    problems = []
+    heads = _headers(text)
+    for sec in REQUIRED_SECTIONS:
+        if sec not in heads:
+            problems.append("R2: discovery.md has no '%s' section — requirements are unstructured." % sec)
+
+    min_ac = int(cfg.get("min_acceptance_criteria", 1))
+    n_ac = len(set(AC_RE.findall(text)))
+    if n_ac < min_ac:
+        problems.append(
+            "R2: fewer than %d structured acceptance criteria (label them AC1, AC2, …) "
+            "in discovery.md — vague success criteria produce ambiguity failures downstream." % min_ac)
+
+    for pat in UNCERTAINTY:
+        if re.search(pat, text, re.I):
+            problems.append(
+                "R1: unresolved marker matching '%s' in discovery.md — the intention is still "
+                "ambiguous. Resolve it with the user, don't let automation guess." % pat)
+            break
+    return problems
+
+
+def check_flow(spec_dir, is_specialist):
+    """R3 — phases must have run in order before an implementation dispatch."""
+    if not is_specialist:
+        return []
+    problems = []
+    for fname, phase in (("context-pack.md", "context research"),
+                         ("plan.md", "planning"),
+                         ("task-graph.json", "scheduling")):
+        if not os.path.exists(os.path.join(spec_dir, fname)):
+            problems.append(
+                "R3: wrong flow — dispatching implementation but %s (%s phase) is missing. "
+                "Phases run discovery -> context -> plan -> schedule -> implement, in order."
+                % (fname, phase))
+    return problems
+
+
+def check_coverage(spec_dir, cfg=None):
+    """R4 — plan must cover exactly the acceptance criteria: no gaps, no creep."""
+    cfg = cfg or {}
+    if not cfg.get("require_coverage", True):
+        return []
+    acs = acceptance_ids(spec_dir)
+    if not acs:
+        return []  # missing ACs already reported by check_discovery
+    covered = plan_task_coverage(spec_dir)
+    problems = []
+    uncovered = acs - covered
+    if uncovered:
+        problems.append(
+            "R4: acceptance criteria not covered by any task: %s. The plan under-delivers "
+            "or has diverged from what the user asked for." % ", ".join(sorted(uncovered)))
+    unknown = covered - acs
+    if unknown:
+        problems.append(
+            "R4: tasks claim acceptance criteria absent from discovery.md: %s. This is scope "
+            "creep / diversion — the plan is building something not requested." % ", ".join(sorted(unknown)))
+    return problems
+
+
+def check_all(spec_dir, is_specialist, cfg=None):
+    problems = check_discovery(spec_dir, cfg)
+    problems += check_flow(spec_dir, is_specialist)
+    if is_specialist or os.path.exists(os.path.join(spec_dir, "plan.md")):
+        problems += check_coverage(spec_dir, cfg)
+    return problems

package/template/.claude/hooks/requirements-gate.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""requirements-gate.py — PreToolUse hook on Task (the EXTENDED human gate).
+
+Runs alongside dispatch-gate. Where dispatch-gate enforces the *schedule*
+(approval hash, order, caps, breaker), this gate enforces *intention and
+requirement quality* — it refuses to let automation proceed on ambiguous
+intentions, vague/unstructured requirements, a wrong flow, or a plan that has
+diverted from what the user asked for. On a block, the only legal move is to
+re-enter interview mode with the user: these conditions route to a human by
+design, because retrying them just manufactures confident wrong guesses.
+
+Gated when the dispatch prompt carries `FEATURE: <slug>`:
+  * any pipeline dispatch     -> R1 (intent), R2 (structured requirements)
+  * a specialist (TASK-ID set) -> also R3 (flow order), R4 (requirement coverage)
+
+Non-pipeline Task use (no FEATURE header) passes through untouched.
+"""
+import os
+import re
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import harness_lib as lib  # noqa: E402
+import req_lib as req  # noqa: E402
+
+
+def main():
+    event = lib.read_hook_input()
+    if event.get("tool_name") != "Task":
+        lib.allow()
+
+    prompt = (event.get("tool_input", {}) or {}).get("prompt", "") or ""
+    m_feat = re.search(r"^FEATURE:\s*(\S+)", prompt, re.MULTILINE)
+    if not m_feat:
+        lib.allow()  # not a governed pipeline dispatch
+
+    root = lib.project_dir(event)
+    cfg = lib.load_config(root).get("requirements", {})
+    if cfg.get("enabled", True) is False:
+        lib.allow()
+
+    feature = m_feat.group(1)
+    spec_dir = os.path.join(root, "specs", feature)
+    is_specialist = bool(re.search(r"^TASK-ID:\s*\S+", prompt, re.MULTILINE))
+
+    problems = req.check_all(spec_dir, is_specialist, cfg)
+    if not problems:
+        lib.allow()
+
+    lib.deny(
+        "Human gate — requirements/intention not ready (Loop Engineering):\n"
+        "  - " + "\n  - ".join(problems) + "\n\n"
+        "These route to the USER, not a retry. Re-enter interview mode "
+        "(discovery-interview skill): resolve the ambiguity, structure the "
+        "acceptance criteria (AC1, AC2, …), and make the plan cover exactly what "
+        "was asked. Update discovery.md / plan.md, then re-approve. Do not dispatch "
+        "around this — a wrong requirement built perfectly is still wrong."
+    )
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/hooks/retrieval-nudge.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python
+"""retrieval-nudge.py  —  PreToolUse hook (matcher: Grep|Glob)
+
+Encodes the harness retrieval order: **Graphify -> skills -> memory**
+(Architecture.md §6). A broad, exploratory file scan is redirected to a
+dependency-aware `graphify query` first. Narrow, file-scoped searches pass
+straight through — the nudge steers discovery, it does not police every grep.
+
+Graphify-availability routing (the "search for context with graphify, and if it
+isn't available, auto-init then use the graphify skill" flow):
+
+  * graph built            -> steer to `graphify query "<derived question>"`
+  * installed, no graph    -> instruct: run `/graphify .` to build the graph,
+                              then query it   (auto-init / setup)
+  * not installed          -> instruct: run `/graphify .` — the skill self-installs
+                              via uv/pip on first run, then builds the graph
+
+Loop-safety: the hook blocks a given session at most once. It drops a marker on
+first fire; any subsequent broad search in the same session passes through. So
+the worst case is a single steering message — a subagent can never get wedged.
+"""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import harness_lib as lib  # noqa: E402
+
+
+def _abs(root, p):
+    return p if os.path.isabs(p) else os.path.join(root, p)
+
+
+def is_satisfied_or_already_nudged(root, hook_input):
+    """Graph-first retrieval is satisfied if the session already ran a graphify
+    query, OR we already nudged this session (one-shot — never trap a loop)."""
+    if lib.graphify_used_this_session(hook_input.get("transcript_path")):
+        return True
+    return _nudge_marker(root, hook_input, write=False)
+
+
+def _nudge_marker(root, hook_input, write):
+    session = hook_input.get("session_id") or "default"
+    safe = "".join(c if c.isalnum() or c in "-_" else "_" for c in str(session))
+    marker = os.path.join(root, ".claude", ".harness", "nudged-" + safe + ".flag")
+    if write:
+        try:
+            os.makedirs(os.path.dirname(marker), exist_ok=True)
+            with open(marker, "w", encoding="utf-8") as fh:
+                fh.write("1")
+        except Exception:
+            pass
+        return True
+    return os.path.exists(marker)
+
+
+def is_broad_search(root, tool_name, ti):
+    """True when the search is repo-wide exploration rather than a localized look.
+
+    Deterministic and scope-based (not pattern-guessing): a search is *narrow*
+    (passes through) when it is confined to a specific file, a specific
+    subdirectory, or a literal filename glob. Everything else is broad.
+    """
+    path = ti.get("path") or ""
+    # file-scoped -> always narrow
+    if path and os.path.isfile(_abs(root, path)):
+        return False
+    # explicit subdirectory (anything but repo root / cwd) -> narrow
+    if path and path not in (".", "./", "") and os.path.abspath(_abs(root, path)) != os.path.abspath(root):
+        return False
+
+    if tool_name == "Grep":
+        glob = ti.get("glob") or ""
+        # a literal filename glob (no wildcard) is a targeted lookup
+        if glob and "*" not in glob:
+            return False
+        return True
+
+    if tool_name == "Glob":
+        pattern = ti.get("pattern") or ""
+        # concrete directory prefix before the first wildcard -> targeted
+        head = pattern.split("*", 1)[0]
+        prefix = os.path.dirname(head)
+        if prefix and os.path.isdir(_abs(root, prefix)):
+            return False
+        return True
+
+    return False
+
+
+def derived_question(ti):
+    term = (ti.get("pattern") or ti.get("glob") or "").strip()
+    if not term or term in ("**", "**/*", "*"):
+        return "what are the main modules here and how do they depend on each other"
+    return 'where is `%s` defined and used, and what depends on it' % term
+
+
+def compose(root, tool_name, ti, gstate, auto_init):
+    q = derived_question(ti)
+    tail = ("\nThis is a one-time nudge for this session — if the graph can't answer, "
+            "just re-run your %s and it will pass through." % tool_name)
+
+    if gstate["graph_built"]:
+        return ("Graph-first retrieval (Loop Engineering).\n"
+                "A knowledge graph already exists at %s. Query it before a raw %s — "
+                "it returns dependency-aware context (importers, shared dependents) "
+                "that a text scan cannot:\n\n"
+                '    graphify query "%s"\n' % (gstate["graph_json"], tool_name, q)) + tail
+
+    if gstate["installed"]:
+        return ("Graph-first retrieval (Loop Engineering).\n"
+                "Graphify is installed but no graph has been built for this repo yet. "
+                "Initialize it before broad file scanning:\n\n"
+                "    /graphify .            # build the knowledge graph (one-time setup)\n"
+                '    graphify query "%s"\n' % q) + tail
+
+    # not installed -> route to the self-installing skill
+    if auto_init:
+        return ("Graph-first retrieval (Loop Engineering).\n"
+                "Graphify is not available in this project. Auto-initialize it before "
+                "broad file scanning — the /graphify skill self-installs (uv/pip) on "
+                "first run, then builds the graph:\n\n"
+                "    /graphify .            # install + build the knowledge graph\n"
+                '    graphify query "%s"\n' % q) + tail
+    return ("Graph-first retrieval (Loop Engineering): graphify is not installed. "
+            "Consider `/graphify .` to enable dependency-aware context.") + tail
+
+
+def main():
+    hook_input = lib.read_hook_input()
+    tool_name = hook_input.get("tool_name", "")
+    if tool_name not in ("Grep", "Glob"):
+        lib.allow()
+
+    root = lib.project_dir(hook_input)
+    config = lib.load_config(root)
+    nudge_cfg = config.get("retrieval_nudge", {})
+    mode = nudge_cfg.get("mode", "block")
+    if mode == "off":
+        lib.allow()
+
+    ti = hook_input.get("tool_input", {}) or {}
+    if not is_broad_search(root, tool_name, ti):
+        lib.allow()
+    if is_satisfied_or_already_nudged(root, hook_input):
+        lib.allow()
+
+    gstate = lib.graphify_state(root, config)
+    message = compose(root, tool_name, ti, gstate, nudge_cfg.get("auto_init", True))
+
+    # Record the one-shot marker BEFORE emitting, so a retry always progresses.
+    _nudge_marker(root, hook_input, write=True)
+
+    if mode == "warn":
+        lib.warn(message)
+    lib.deny(message)
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/hooks/session-rehydrate.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""
+session-rehydrate.py — SessionStart hook (matchers: "compact", "resume").
+
+The second half of the compaction-indifference design. precompact-guard.py
+snapshots the load-bearing minimum to disk; this hook injects it back into
+the fresh/compacted context. Stdout from a SessionStart hook is added to
+Claude's context, which is exactly the channel we want.
+
+Also serves the loop layer (DevelopmentUpdates.md §4): when the outer driver
+resumes a parked feature in a brand-new session, this same hook rehydrates
+it from artifacts — resume-from-artifacts and recover-from-compaction are
+deliberately the same mechanism.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+REPO = Path.cwd()
+ACTIVE_POINTER = REPO / "specs" / "_active.json"
+
+
+def main() -> None:
+    # Snapshot content may contain non-ASCII; force UTF-8 stdout so injection
+    # never dies on a Windows cp1252 console.
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+
+    try:
+        event = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    if event.get("source") not in ("compact", "resume"):
+        sys.exit(0)  # fresh interactive sessions start clean on purpose
+
+    if not ACTIVE_POINTER.exists():
+        sys.exit(0)
+
+    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)
+
+    snap = REPO / "specs" / feature / "pipeline-context.md"
+    if snap.exists():
+        # stdout -> injected into context
+        print(snap.read_text(encoding="utf-8"))
+    else:
+        print(
+            f"# PIPELINE REHYDRATION\n"
+            f"Active feature: {feature}. No snapshot found — rehydrate manually by "
+            f"reading specs/{feature}/state.json, plan.md, and task-graph.json, "
+            f"then continue per task-graph order."
+        )
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/hooks/state-updater.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python
+"""state-updater.py  —  SubagentStop + PostToolUse(Task) hook
+
+The single writer of specs/<f>/state.json (Architecture.md §6). Agents never
+edit state; this hook reconciles it from the review verdicts on disk each time a
+subagent finishes. Reconciler pattern — it does not need to know which subagent
+just ran; it re-derives the whole state from the review.*.json files + the task
+graph. Idempotent, and always exits 0 (it updates, it never gates).
+
+Per-task status:  pending -> needs_retry -> done  (or -> escalate)
+Counters live here, on disk, so context compaction can never turn a finite retry
+loop into an infinite one.
+"""
+
+import glob
+import os
+import re
+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
+
+REVIEW_RE = re.compile(r"review\.(?P<task>.+)\.(?P<n>\d+)\.json$")
+
+
+def reviews_by_task(feature_dir):
+    out = {}
+    for path in glob.glob(os.path.join(feature_dir, "review.*.json")):
+        m = REVIEW_RE.search(os.path.basename(path))
+        if not m:
+            continue
+        out.setdefault(m.group("task"), []).append((int(m.group("n")), path))
+    for task in out:
+        out[task].sort(key=lambda x: x[0])
+    return out
+
+
+def finding_keys(review):
+    keys = set()
+    for f in review.get("findings", []) or []:
+        keys.add((f.get("file", ""), f.get("detail", "") or f.get("id", "")))
+    return keys
+
+
+def main():
+    hook_input = lib.read_hook_input()
+    root = lib.project_dir(hook_input)
+    feature_dir = lib.current_feature_dir(root)
+    if not feature_dir:
+        lib.allow()
+
+    state_path = os.path.join(feature_dir, "state.json")
+    state = lib.read_json(state_path, default={}) or {}
+    state.setdefault("feature", os.path.basename(feature_dir))
+    state.setdefault("tasks", {})
+
+    graph = lib.read_json(os.path.join(feature_dir, "task-graph.json"), default={}) or {}
+    for t in graph.get("tasks", []):
+        state["tasks"].setdefault(t["id"], {"status": "pending", "attempts": 0})
+
+    by_task = reviews_by_task(feature_dir)
+    for task, entries in by_task.items():
+        latest_n, latest_path = entries[-1]
+        latest = lib.read_json(latest_path, default={}) or {}
+        ts = state["tasks"].setdefault(task, {"status": "pending", "attempts": 0})
+        ts["attempts"] = latest_n
+        ts["last_review"] = os.path.basename(latest_path)
+
+        if latest.get("status") == "pass":
+            ts["status"] = "done"
+            ts.pop("pending_failure_class", None)
+            continue
+
+        ts["status"] = "needs_retry"
+        ts["pending_failure_class"] = latest.get("failure_class", "mechanical")
+
+        # Repeated-finding early stop: reviewer flag, or identical findings twice.
+        repeat = bool(latest.get("repeat_finding"))
+        if not repeat and len(entries) >= 2:
+            prev = lib.read_json(entries[-2][1], default={}) or {}
+            repeat = bool(finding_keys(latest) & finding_keys(prev))
+        if repeat:
+            ts["status"] = "escalate"
+            ts["repeat_finding"] = True
+
+    # Mirror the in-flight task (set by dispatch-gate's .current.json) into state
+    # so the PreCompact snapshot captures it as part of the load-bearing minimum.
+    cur = loop.read_current(feature_dir)
+    if cur and cur.get("task_id"):
+        state["current_task"] = cur["task_id"]
+
+    # Derive the pipeline phase (part of Rule 4's load-bearing minimum). Purely a
+    # function of which artifacts exist — the snapshot must never guess.
+    tvals = state["tasks"].values()
+    if not graph.get("tasks"):
+        state["phase"] = "planning"
+    elif (not state["tasks"]) or any(t.get("status") != "done" for t in tvals):
+        state["phase"] = "execution"
+    else:
+        integ = glob.glob(os.path.join(feature_dir, "review.integration.*.json"))
+        passed = any((lib.read_json(p, default={}) or {}).get("status") == "pass" for p in integ)
+        state["phase"] = "committed" if passed else "integration"
+
+    # Derive circuit-breaker health from the disk signals just reconciled
+    # (retry caps, repeat findings, escalation count, footprint violations).
+    loop.recompute_health(state, feature_dir, lib.load_config(root))
+
+    lib.write_json(state_path, state)
+
+    # Maintain specs/_active.json — the pointer precompact-guard.py and
+    # session-rehydrate.py read to find the feature to snapshot / rehydrate.
+    lib.write_json(os.path.join(lib.specs_root(root), "_active.json"),
+                   {"feature": os.path.basename(feature_dir)})
+    lib.allow()
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/hooks/trace-emitter.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python
+"""trace-emitter.py  —  registered on ALL lifecycle events
+
+Maps hook events to observability spans/scores (Architecture.md §8):
+  session_id                     -> Langfuse trace id
+  PreToolUse(Task)/SubagentStop  -> subagent span open/close (no SubagentStart
+                                    exists, so open is approximated from dispatch)
+  tool calls                     -> child events
+  review verdicts                -> Langfuse scores; failed reviews -> dataset flag
+
+Fail-open, always. Observability must never become an availability dependency:
+every event is appended to .claude/traces/<session>.jsonl locally, and Langfuse
+delivery is a best-effort urllib POST wrapped in try/except with a short timeout.
+If Langfuse is unreachable, the local trace is the source of truth. Exit 0 no
+matter what — a telemetry failure must never block the pipeline.
+"""
+
+import base64
+import glob
+import json
+import os
+import sys
+import urllib.request
+from datetime import datetime, timezone
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import harness_lib as lib  # noqa: E402
+
+
+def now_iso():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def local_log(root, session, record):
+    try:
+        d = os.path.join(root, ".claude", "traces")
+        os.makedirs(d, exist_ok=True)
+        with open(os.path.join(d, (session or "session") + ".jsonl"), "a", encoding="utf-8") as fh:
+            fh.write(json.dumps(record, ensure_ascii=False) + "\n")
+    except Exception:
+        pass
+
+
+def latest_review(feature_dir):
+    files = glob.glob(os.path.join(feature_dir, "review.*.json")) if feature_dir else []
+    if not files:
+        return None
+    files.sort(key=os.path.getmtime)
+    return lib.read_json(files[-1])
+
+
+def langfuse_post(host, public, secret, batch):
+    body = json.dumps({"batch": batch}).encode("utf-8")
+    auth = base64.b64encode(("%s:%s" % (public, secret)).encode()).decode()
+    req = urllib.request.Request(
+        host.rstrip("/") + "/api/public/ingestion",
+        data=body,
+        headers={"Content-Type": "application/json", "Authorization": "Basic " + auth},
+        method="POST",
+    )
+    urllib.request.urlopen(req, timeout=3).read()
+
+
+def env_ref(value):
+    """Config values may be `env:VAR` references (never literal secrets on disk)."""
+    if isinstance(value, str) and value.startswith("env:"):
+        return os.environ.get(value[4:], "")
+    return value or ""
+
+
+def main():
+    hook_input = lib.read_hook_input()
+    root = lib.project_dir(hook_input)
+    session = hook_input.get("session_id") or "session"
+    event = hook_input.get("hook_event_name", "unknown")
+    tool = hook_input.get("tool_name", "")
+
+    record = {"ts": now_iso(), "event": event, "tool": tool, "session": session}
+    feature_dir = lib.current_feature_dir(root)
+    if feature_dir:
+        record["feature"] = os.path.basename(feature_dir)
+
+    review = latest_review(feature_dir) if event == "SubagentStop" else None
+    if review:
+        record["review"] = {
+            "task": review.get("task"),
+            "status": review.get("status"),
+            "failure_class": review.get("failure_class"),
+        }
+
+    local_log(root, session, record)
+
+    config = lib.load_config(root)
+    obs = config.get("observability", {})
+    if not obs.get("enabled", True) or obs.get("provider") != "langfuse":
+        lib.allow()
+
+    host = env_ref(obs.get("host")) or os.environ.get("LANGFUSE_HOST", "")
+    public = env_ref(obs.get("public_key")) or os.environ.get("LANGFUSE_PUBLIC_KEY", "")
+    secret = env_ref(obs.get("secret_key")) or os.environ.get("LANGFUSE_SECRET_KEY", "")
+    if not (host and public and secret):
+        lib.allow()  # unconfigured -> local trace only, silently
+
+    batch = [
+        {"type": "trace-create", "id": session, "timestamp": record["ts"],
+         "body": {"id": session, "name": record.get("feature", "loop-engineering")}},
+        {"type": "event-create", "id": session + ":" + record["ts"], "timestamp": record["ts"],
+         "body": {"traceId": session, "name": event, "metadata": record}},
+    ]
+    if review and review.get("status"):
+        batch.append({
+            "type": "score-create", "id": session + ":score:" + record["ts"],
+            "timestamp": record["ts"],
+            "body": {"traceId": session, "name": "review",
+                     "value": 1 if review.get("status") == "pass" else 0,
+                     "comment": review.get("failure_class") or ""},
+        })
+
+    try:
+        langfuse_post(host, public, secret, batch)
+    except Exception:
+        pass  # fail-open: local trace already written
+
+    lib.allow()
+
+
+if __name__ == "__main__":
+    main()