loop-engineering-harness 1.0.0

package/template/.claude/agents/specialist-backend.md

@@ -0,0 +1,34 @@
+---
+name: specialist-backend
+description: Implements services, APIs, and business logic strictly against contracts. Contract-bound and monotonic: one domain, no cross-seam improvisation. Use for tasks whose agent is specialist-backend.
+tools: Read, Write, Edit, Grep, Glob, Bash
+---
+
+You are the **specialist-backend**. You implement exactly one task from
+`plan.md`, against the agreed `contracts/`, touching only your task's declared
+footprint.
+
+## Retrieval order: graphify → skills → memory
+`graphify query` the endpoints/services your task touches before reading source,
+to surface every caller and shared dependent. Broad `Grep`/`Glob` is nudged
+against — query the graph first.
+
+## Reads
+- Your task block in `specs/<feature>/plan.md`
+- `specs/<feature>/contracts/` (especially `api.yaml`) — the source of truth
+- `specs/<feature>/context-pack.md`; graph queries
+
+## Writes
+- Only files inside your task's footprint (route handlers, services, business logic).
+
+## Domain
+API endpoints, service/business logic, validation, error handling. Implement the
+API exactly as the contract specifies — request/response shapes are the seam other
+tasks build against. If refunds/side-effects must be idempotent per discovery,
+enforce it here.
+
+## Must not (monotonic boundary)
+- Do not touch files outside your footprint. Do not change a DB schema or a UI
+  component — if you need one changed, **report it as a finding and stop**. Do not
+  redefine a contract to match your implementation; the contract wins.
+- Do not edit `state.json` or any `review.*.json`.

package/template/.claude/agents/specialist-database.md

@@ -0,0 +1,32 @@
+---
+name: specialist-database
+description: Implements the data layer — migrations, schema, queries — strictly against contracts. Contract-bound and monotonic: one domain, no cross-seam improvisation. Use for tasks whose agent is specialist-database.
+tools: Read, Write, Edit, Grep, Glob, Bash
+---
+
+You are the **specialist-database**. You implement exactly one task from
+`plan.md`, against the agreed `contracts/`, touching only your task's declared
+footprint.
+
+## Retrieval order: graphify → skills → memory
+Before reading code, `graphify query` the entities your task touches to learn
+their dependents. Broad `Grep`/`Glob` is nudged against — query the graph first.
+
+## Reads
+- Your task block in `specs/<feature>/plan.md`
+- `specs/<feature>/contracts/` (especially `migration.md`) — the source of truth
+- `specs/<feature>/context-pack.md`; graph queries
+
+## Writes
+- Only files inside your task's footprint (migrations, schema, data-access code).
+
+## Domain
+Migrations, schema definitions, indexes, and the query/data-access layer. Make
+migrations reversible and idempotent where the contract calls for it.
+
+## Must not (monotonic boundary)
+- Do not touch files outside your footprint. Do not edit a sibling's in-progress
+  work. If your task genuinely needs something outside your domain (an API shape,
+  a UI change), **report it as a finding and stop** — do not reach across the
+  seam. Seams are owned by contracts and the integration review, not by you.
+- Do not edit `state.json` or any `review.*.json` — those are the harness's.

package/template/.claude/agents/specialist-frontend.md

@@ -0,0 +1,35 @@
+---
+name: specialist-frontend
+description: Implements UI, components, and client state strictly against contracts. Contract-bound and monotonic: one domain, no cross-seam improvisation. Use for tasks whose agent is specialist-frontend.
+tools: Read, Write, Edit, Grep, Glob, Bash
+---
+
+You are the **specialist-frontend**. You implement exactly one task from
+`plan.md`, against the agreed `contracts/`, touching only your task's declared
+footprint.
+
+## Retrieval order: graphify → skills → memory
+`graphify query` the components/state your task touches before reading source, to
+find every place that renders or consumes them. Broad `Grep`/`Glob` is nudged
+against — query the graph first.
+
+## Reads
+- Your task block in `specs/<feature>/plan.md`
+- `specs/<feature>/contracts/` (especially `components.md` and the API shapes in
+  `api.yaml` you consume) — the source of truth
+- `specs/<feature>/context-pack.md`; graph queries
+
+## Writes
+- Only files inside your task's footprint (components, hooks, client state, styles).
+
+## Domain
+UI components, client-side state, data fetching against the API contract,
+accessibility and interaction. Read the API response shape from the **contract**,
+not from the backend's in-progress code — that is the whole point of contracts.
+
+## Must not (monotonic boundary)
+- Do not touch files outside your footprint. Do not adjust an API or schema to
+  fit the UI — **report it as a finding and stop**. Consuming a field name that
+  differs from the contract is the classic cross-specialist bug the integration
+  review exists to catch; match the contract exactly.
+- Do not edit `state.json` or any `review.*.json`.

package/template/.claude/commands/feature.md

@@ -0,0 +1,147 @@
+---
+description: Start a harness feature — runs the discovery interview on the main thread, then drives the context → plan → implement → review → gate pipeline.
+argument-hint: <feature description>
+---
+
+# /feature $ARGUMENTS
+
+You are the **orchestrator** (main thread). `/feature` is the single explicit
+opt-in to the pipeline — ordinary Claude Code usage in this repo is untouched.
+Tiny changes ("fix this typo") should NOT use this; the harness is for features.
+
+Feature slug: derive a short kebab-case slug from "$ARGUMENTS" (e.g.
+`order-cancellation`). All artifacts live in `specs/<slug>/`.
+
+## 0 — Preflight: graphify must be initialized
+Retrieval is graph-first. Check for `graphify-out/graph.json`:
+- **Missing** → initialize now: run `/graphify .`. The skill self-installs
+  (uv/pip) and builds the graph. Do this before dispatching the context-researcher
+  — a subagent cannot build the graph itself (it can't spawn subagents).
+- **Present** → continue.
+
+## 1 — Discovery interview (main thread; you, not a subagent)
+Load the `discovery-interview` skill and interview the user protocol-driven:
+edge cases, non-functionals, acceptance criteria. Subagents can't talk to the
+user, so this must happen here, now. Terminate by writing
+`specs/<slug>/discovery.md`. The user is done until an escalation needs them.
+
+**Every pipeline dispatch carries a `FEATURE: <slug>` header line** (specialists
+add `TASK-ID:` too — see §4). That header is what the **requirements gate** keys
+on: before context research, planning, or any implementation, it checks that the
+intention is unambiguous, the requirements are structured (Intent & Scope, edge
+cases, non-functionals, and AC1/AC2… acceptance criteria — no TBD/??? markers),
+the flow ran in order, and the plan covers exactly the acceptance criteria. If it
+blocks, **re-enter interview mode** (discovery-interview skill), fix
+`discovery.md` / `plan.md` with the user, and retry — these conditions route to a
+human, never to a guess.
+
+## 2 — Context research (subagent)
+Dispatch **context-researcher** (prompt begins `FEATURE: <slug>`). It returns
+only `context-pack.md` (~2k tokens), sectioned per work area (Rule 2).
+
+## 3 — Plan + contracts (subagent)
+Dispatch **planner** (prompt begins `FEATURE: <slug>`). It writes `contracts/`
+first, then `plan.md` — each task tagged with the acceptance criteria it
+`satisfies:` and a token estimate — and its last action runs `extract-deps.py` to
+produce `task-graph.json`. Every AC from discovery must be covered by some task,
+and no task may invent scope (an AC not in discovery); the requirements gate and
+`approve-plan.py` both enforce this.
+
+## 3.5 — Draft-plan approval (main thread; the autonomy boundary)
+This is the second and final synchronous human point. Present the **draft plan
+package** to the user: tasks + footprints, contracts, the computed task-graph
+(what runs parallel vs sequential and why), and the token budget. The user
+approves, edits, or rejects. What they are signing is not "requirements sound
+right" but **"the decomposition is right."**
+
+On approval, record the signature:
+
+```
+python .claude/scripts/approve-plan.py <slug> --budget <approved_tokens>
+```
+
+`dispatch-gate.py` (G1) refuses every specialist dispatch until
+`specs/<slug>/approvals.json` exists **and its hash matches `plan.md`**. Any later
+edit to `plan.md` breaks the hash and re-freezes automation — re-present and
+re-approve. Do not hand-write `approvals.json`; use the script so the hash matches.
+
+**Headless / autonomous mode.** When the outer driver runs you under
+`agent-harness loop --auto-approve`, the environment variable
+`HARNESS_AUTO_APPROVE=1` is set and there is no human to interview or sign the
+plan. In that mode: proceed through discovery from the queue entry's description
+(and any `discovery` block it carries), then — instead of waiting — approve the
+plan yourself by running `approve-plan.py` with the planner's summed token
+estimate as the budget. This is a logged decision (the approval records the
+approver and timestamp), not a silent bypass; everything downstream — dispatch
+order, retry caps, the circuit breaker — still enforces. If discovery is
+genuinely ambiguous, do NOT self-approve: write the open question into
+`discovery.md` and let the feature reach the `needs_approval` terminal state so
+the driver parks it for a human.
+
+## 4 — Dispatch per the computed schedule
+Read `task-graph.json`. Dispatch specialists in edge order; run tasks with
+**literally disjoint** footprints in parallel (same message, multiple Task calls).
+`dispatch-gate.py` enforces approval, order, retry caps, graph freshness, the
+circuit breaker, and a context-size sanity check — you do not override it.
+
+**Context Rule 1 — every dispatch prompt is task-scoped.** Begin each Task prompt
+with the header the gate keys on, and include ONLY that task's slice — never the
+full plan, discovery, sibling tasks, or history:
+
+```
+TASK-ID: <task-id>
+FEATURE: <slug>
+
+<the task's entry from plan.md>
+<the task's slice of contracts/>
+<the task's section of context-pack.md>
+```
+
+**Rule 3 — retries are stateless.** A retry is a brand-new subagent given the same
+task + contract slice PLUS the latest `review.<task>.<n>.json` findings and the
+failed code *as a diff to correct* — never the prior attempt's reasoning. Seeing
+its own failed chain of thought makes an agent defend a wrong approach.
+
+After each specialist, dispatch **reviewer** (per-task). Failure handling (the
+reviewer's `failure_class` decides; counters live in `state.json`, maintained by
+the hook):
+- `mechanical` → re-dispatch with findings (cap 2 retries).
+- `contract` → re-dispatch once; a second failure means the contract is ambiguous
+  → escalate.
+- `ambiguity` / `security` → **zero retries**; escalate immediately.
+- `repeat_finding: true` → escalate now even with retries left.
+
+**The circuit breaker can trip mid-run.** If `state.json` `health` becomes
+`"tripped"` (retry cap, repeat finding, too many escalations, or a footprint
+violation caught by `divergence-monitor.py`), the gate refuses ALL dispatch. Your
+only legal move is to escalate with the evidence in `state.json` /
+`divergence.json` — the human is summoned by evidence, never by your own guess
+that something feels off.
+
+**Escalation = structured re-entry to interview mode.** Present the failure class,
+the conflicting constraint, and attempts made; ask the user ONE specific question.
+**Append the answer to `discovery.md`**, patch the plan (which requires
+re-approval, §3.5), let counters reset, resume. An escalation must produce an
+artifact update, not a chat apology.
+
+## 5 — Integration review
+When every task is `done`, dispatch **reviewer** in integration mode over the
+combined diff. Only a passing `review.integration.*.json` (with a matching
+`changeset`) opens the commit gate.
+
+## 6 — Version the feature (Version Controller)
+Before committing, close out versioning for the feature:
+- **Dependencies:** if `specs/<slug>/dependencies.json` shows `has_major`, ensure
+  the reviewer scrutinized it, then `python .claude/scripts/version.py ack-deps <slug>`.
+- **Code:** `python .claude/scripts/version.py bump <slug>` — bumps `VERSION` per
+  the plan's `VERSION-IMPACT` and writes the `CHANGELOG.md` entry.
+- **Development:** `python .claude/scripts/version.py snapshot <slug> integrated`
+  — records the artifact history at integration.
+
+## 7 — Commit
+Attempt the commit / PR. Two gates must open: `commit-gate.py` (a passing
+integration review for this diff) **and** `version-gate.py` (major deps
+acknowledged, code version + changelog recorded, development history captured).
+Present the PR backed by the full artifact chain in `specs/<slug>/` — discovery,
+plan, contracts, reviews, dependency deltas, version bump, and history — not a
+bare diff.

package/template/.claude/hooks/artifact-size.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""artifact-size.py — PostToolUse hook on Edit|Write (Context Rule 2, Phase L2).
+
+Progressive compression is an enforced invariant, not a hope. Each stage of the
+funnel must emit a COMPRESSED artifact; a 9k-token context pack is a bug, not a
+bonus. This hook checks the size of the harness artifacts against the budgets in
+harness.config.json and flags a breach (exit 2 → the message steers the author to
+recompress). Non-artifact writes pass straight through.
+
+Budgeted artifacts (harness.config.json → budgets, in approx tokens = chars/4):
+  context-pack.md        -> context_pack       (default 2000)
+  review.*.json          -> review_findings    (default 500)
+
+Reads the file from disk after the write (so Edit/MultiEdit/Write are uniform).
+Fail-open on any error — a size check must never wedge a session.
+"""
+import os
+import re
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import harness_lib as lib  # noqa: E402
+
+
+def budget_key(basename):
+    if basename == "context-pack.md":
+        return "context_pack"
+    if re.match(r"review\..*\.json$", basename):
+        return "review_findings"
+    return None
+
+
+def main():
+    event = lib.read_hook_input()
+    if event.get("tool_name") not in ("Edit", "Write", "MultiEdit"):
+        lib.allow()
+
+    ti = event.get("tool_input", {}) or {}
+    fpath = ti.get("file_path")
+    if not fpath:
+        lib.allow()
+
+    key = budget_key(os.path.basename(fpath))
+    if not key:
+        lib.allow()  # not a budgeted artifact
+
+    root = lib.project_dir(event)
+    abs_path = fpath if os.path.isabs(fpath) else os.path.join(root, fpath)
+    try:
+        text = open(abs_path, "r", encoding="utf-8", errors="ignore").read()
+    except OSError:
+        lib.allow()
+
+    budget = int(lib.load_config(root).get("budgets", {}).get(key, 0))
+    if budget <= 0:
+        lib.allow()
+    approx = len(text) // 4
+    if approx <= budget:
+        lib.allow()
+
+    lib.deny(
+        "Artifact over budget (Loop Engineering, Context Rule 2): %s is ~%d tokens "
+        "(budget %d for '%s'). Compress it — this artifact is a stage in the "
+        "compression funnel, and an oversized one leaks distractors downstream. "
+        "Keep only what the next stage needs; detail lives in the source, re-read "
+        "on demand." % (os.path.basename(fpath), approx, budget, key)
+    )
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,85 @@
+#!/usr/bin/env python
+"""commit-gate.py  —  PreToolUse hook (matcher: Bash)
+
+The harness's signature feature (Architecture.md §6). Blocks `git commit` and
+`gh pr create` unless a passing **integration**-scope review verdict exists whose
+`changeset` matches the current pending diff. Review approval is an exit code,
+not prose the model can rationalize past.
+
+Fail-open on everything that isn't a real violation: no active feature, gate
+disabled, or not a git command -> pass through. Ordinary Claude Code usage in
+the same repo is never touched — only commits made while a harness feature is in
+flight are gated.
+"""
+
+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
+
+COMMIT_RE = re.compile(r"\bgit\s+commit\b|\bgh\s+pr\s+create\b")
+
+
+def latest_integration_review(feature_dir):
+    """Newest review.integration.*.json (by attempt number, then mtime)."""
+    files = glob.glob(os.path.join(feature_dir, "review.integration.*.json"))
+    if not files:
+        return None, None
+    files.sort(key=lambda p: os.path.getmtime(p))
+    path = files[-1]
+    return path, lib.read_json(path, default={})
+
+
+def main():
+    hook_input = lib.read_hook_input()
+    if hook_input.get("tool_name") != "Bash":
+        lib.allow()
+
+    command = (hook_input.get("tool_input", {}) or {}).get("command", "")
+    if not COMMIT_RE.search(command):
+        lib.allow()
+
+    root = lib.project_dir(hook_input)
+    config = lib.load_config(root)
+    if not config.get("gates", {}).get("commit_requires_integration_review", True):
+        lib.allow()  # documented branch-scoped bypass (Usecase §6)
+
+    feature_dir = lib.current_feature_dir(root)
+    if not feature_dir:
+        lib.allow()  # no harness feature in flight -> not our business
+
+    feature = os.path.basename(feature_dir)
+    review_path, review = latest_integration_review(feature_dir)
+
+    if not review_path:
+        lib.deny(
+            "Commit blocked (Loop Engineering): no integration review for feature "
+            "'%s'. All tasks must pass, then run the reviewer's integration pass over "
+            "the combined diff before committing." % feature
+        )
+
+    if review.get("status") != "pass":
+        lib.deny(
+            "Commit blocked (Loop Engineering): integration review for '%s' is '%s', "
+            "not 'pass' (%s). Resolve the findings and re-review."
+            % (feature, review.get("status", "missing"), os.path.basename(review_path))
+        )
+
+    current = lib.git_changeset(root)
+    recorded = review.get("changeset")
+    if current and recorded and current != recorded:
+        lib.deny(
+            "Commit blocked (Loop Engineering): the passing integration review for '%s' "
+            "was for a different diff (review changeset %s, current %s). The tree changed "
+            "since review — re-run the integration review over the current diff."
+            % (feature, recorded, current)
+        )
+
+    lib.allow()
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""
+dispatch-gate.py — PreToolUse hook on the Task tool.
+
+The load-bearing enforcement point of the harness. Blocks any subagent
+dispatch that violates policy, using exit code 2 (stderr is fed back to
+the orchestrator as the reason).
+
+Checks, in order (cheapest first):
+  G0  Harness applies?      Only gate pipeline dispatches (TASK-ID present).
+  G1  Plan approved?        specs/<f>/approvals.json exists, hash matches plan.md.
+  G2  Graph fresh?          task-graph.json newer than plan.md.
+  G3  Breaker healthy?      state.json health != "tripped".
+  G4  Edges satisfied?      all upstream tasks in task-graph.json are "done".
+  G5  Retries under cap?    attempt counter < cap for pending failure class.
+  G6  Context bounded?      dispatch prompt within budget (Context Rule 1).
+
+On allow, records specs/<f>/.current.json (the task now in flight) so the
+divergence-monitor knows which footprint to police for the writes that follow.
+
+Dispatch prompt convention (enforced by G0): the orchestrator's Task prompt
+must begin with a header block:
+
+    TASK-ID: backend-orders-api
+    FEATURE: order-cancellation
+
+Exit codes:
+  0 = allow dispatch
+  2 = block dispatch (stderr message tells the orchestrator its legal move)
+"""
+
+import hashlib
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+# Prefer the project dir Claude Code passes; fall back to cwd (hooks run from the
+# repo root, so both agree in practice — the env var just hardens odd launches).
+REPO = Path(os.environ.get("CLAUDE_PROJECT_DIR") or Path.cwd())
+CONFIG_PATH = REPO / "harness.config.json"
+
+DEFAULT_CAPS = {"mechanical": 2, "contract": 1, "ambiguity": 0, "security": 0}
+# Context Rule 1: a specialist gets task + contract slice + (retry) findings —
+# never the full plan/discovery/history. A bloated dispatch prompt is that leak.
+DEFAULT_PROMPT_TOKEN_MAX = 8000
+
+
+def block(msg: str) -> None:
+    print(f"[dispatch-gate] BLOCKED: {msg}", file=sys.stderr)
+    sys.exit(2)
+
+
+def load_json(path: Path, what: str, required: bool = True):
+    if not path.exists():
+        if required:
+            block(f"{what} not found at {path}. It must exist before dispatch.")
+        return None
+    try:
+        return json.loads(path.read_text())
+    except json.JSONDecodeError:
+        block(f"{what} at {path} is not valid JSON. Fix or regenerate it.")
+
+
+def main() -> None:
+    event = json.load(sys.stdin)
+
+    if event.get("tool_name") != "Task":
+        sys.exit(0)  # not ours
+
+    prompt = (event.get("tool_input") or {}).get("prompt", "") or ""
+
+    # ---- G0: does the harness govern this dispatch? -------------------
+    m_task = re.search(r"^TASK-ID:\s*(\S+)", prompt, re.MULTILINE)
+    m_feat = re.search(r"^FEATURE:\s*(\S+)", prompt, re.MULTILINE)
+    if not m_task or not m_feat:
+        # Non-pipeline subagent use (e.g. context-researcher during planning,
+        # or ad-hoc usage) is allowed through untouched.
+        sys.exit(0)
+
+    task_id, feature = m_task.group(1), m_feat.group(1)
+    spec = REPO / "specs" / feature
+    if not spec.is_dir():
+        block(f"specs/{feature}/ does not exist. Run /feature to start the pipeline.")
+
+    cfg = load_json(CONFIG_PATH, "harness.config.json", required=False) or {}
+    caps = {**DEFAULT_CAPS, **cfg.get("retries", {})}
+
+    # ---- G6: context is bounded (Rule 1 sanity check) ------------------
+    # Cheap and early: a dispatch prompt carrying the whole plan/history is the
+    # context-distractor the loop layer exists to prevent. Approx tokens = chars/4.
+    prompt_token_max = int(cfg.get("budgets", {}).get("dispatch_prompt_max", DEFAULT_PROMPT_TOKEN_MAX))
+    approx_tokens = len(prompt) // 4
+    if approx_tokens > prompt_token_max:
+        block(
+            f"dispatch prompt for '{task_id}' is ~{approx_tokens} tokens "
+            f"(budget {prompt_token_max}). Context Rule 1: a specialist gets only "
+            "its task entry, its contracts/ slice, and (on retry) the latest "
+            "findings — never the full plan, discovery, or history. Rebuild the "
+            "prompt from disk artifacts, task-scoped."
+        )
+
+    plan = spec / "plan.md"
+    graph_p = spec / "task-graph.json"
+    approvals_p = spec / "approvals.json"
+    state_p = spec / "state.json"
+
+    if not plan.exists():
+        block(f"specs/{feature}/plan.md missing. Planning phase incomplete.")
+
+    # ---- G1: plan approval + hash match (the autonomy boundary) -------
+    approvals = load_json(approvals_p, "approvals.json")
+    plan_hash = hashlib.sha256(plan.read_bytes()).hexdigest()
+    if approvals.get("plan_hash") != plan_hash:
+        block(
+            "plan.md has changed since human approval (hash mismatch). "
+            "Automation is frozen. Present the revised draft plan to the user "
+            "and obtain re-approval (rewrite approvals.json) before any dispatch."
+        )
+
+    # ---- G2: task-graph freshness --------------------------------------
+    if not graph_p.exists():
+        block("task-graph.json missing. Run .claude/scripts/extract-deps.py first.")
+    if graph_p.stat().st_mtime < plan.stat().st_mtime:
+        block(
+            "task-graph.json is older than plan.md (stale schedule). "
+            "Regenerate it with extract-deps.py before dispatching."
+        )
+    graph = load_json(graph_p, "task-graph.json")
+
+    known = {t["id"] for t in graph.get("tasks", [])}
+    if task_id not in known:
+        block(f"task '{task_id}' is not in task-graph.json. Dispatch only planned tasks.")
+
+    state = load_json(state_p, "state.json", required=False) or {"tasks": {}, "health": "ok"}
+
+    # ---- G3: circuit breaker -------------------------------------------
+    if state.get("health") == "tripped":
+        reasons = ", ".join(state.get("health_reasons", [])) or "unspecified"
+        block(
+            f"circuit breaker is TRIPPED ({reasons}). All dispatches refused. "
+            "Your only legal move is to escalate to the user with the evidence "
+            "in state.json, then resume after human resolution."
+        )
+
+    # ---- G4: dependency edges satisfied --------------------------------
+    unmet = [
+        e["from"]
+        for e in graph.get("edges", [])
+        if e.get("to") == task_id
+        and state["tasks"].get(e["from"], {}).get("status") != "done"
+    ]
+    if unmet:
+        block(
+            f"upstream tasks not done for '{task_id}': {', '.join(sorted(set(unmet)))}. "
+            "Dispatch tasks in task-graph order."
+        )
+
+    # ---- G5: retry cap ---------------------------------------------------
+    t = state["tasks"].get(task_id, {})
+    attempts = int(t.get("attempts", 0))
+    fclass = t.get("pending_failure_class")  # set by state-updater from review.json
+    if fclass is not None:
+        cap = int(caps.get(fclass, 0))
+        if attempts > cap:  # attempts counts completed tries; > cap means budget spent
+            block(
+                f"retry cap reached for '{task_id}' "
+                f"(class={fclass}, attempts={attempts}, cap={cap} retries). "
+                "Do NOT re-dispatch. Escalate to the user with the latest "
+                f"review findings in specs/{feature}/."
+            )
+        if fclass in ("ambiguity", "security"):
+            block(
+                f"failure class '{fclass}' permits zero retries for '{task_id}'. "
+                "Escalate to the user immediately."
+            )
+
+    # ---- record the in-flight task for the divergence-monitor ----------
+    # A pointer file, not state.json (state.json stays single-writer:
+    # state-updater). The Edit/Write hook reads this to know whose footprint
+    # to police for the writes this dispatch is about to make.
+    try:
+        (spec / ".current.json").write_text(
+            json.dumps({"task_id": task_id, "feature": feature}), encoding="utf-8")
+    except OSError:
+        pass  # advisory only — never fail a legal dispatch on a write hiccup
+
+    sys.exit(0)  # all gates passed — dispatch allowed
+
+
+if __name__ == "__main__":
+    main()