loop-engineering-harness 1.0.0

package/template/.claude/scripts/extract-deps.py

@@ -0,0 +1,288 @@
+#!/usr/bin/env python
+"""extract-deps.py — deterministic task-dependency extractor (Architecture.md §5).
+
+Turns the planner's per-task file footprints into a scheduling DAG. This is the
+one component with real unit tests, because it is pure computation: given the
+same plan.md and the same codebase graph it MUST emit a byte-identical
+task-graph.json. Nothing here calls an LLM — that is the whole point of taking
+dependency math away from the agents.
+
+Usage
+    extract-deps.py --plan specs/<f>/plan.md --out specs/<f>/task-graph.json
+    extract-deps.py --files src/auth/ src/db/schema.prisma   # standalone "what does this touch?"
+
+Options
+    --graphify-out graphify-out/     structural graph directory (default)
+    --depth 1                        hops to expand each footprint (default 1)
+
+Footprint source of truth — plan.md declares each task in a fenced ```task block:
+
+    ```task
+    id: db-orders-migration
+    agent: specialist-database
+    footprint:
+      - db/migrations/
+      - db/schema.prisma
+    produces: [migration]     # optional interface(s) this task defines
+    consumes: []              # optional interface(s) this task depends on
+    ```
+
+Edges (a sequential dependency = the two tasks may NOT run concurrently):
+  * overlap            — a footprint file is literally in both tasks
+  * shared_dependent   — the graph expands both onto a common third file
+  * contract           — one task consumes an interface another produces
+Fully disjoint expanded footprints and no contract link => parallel-safe (no edge).
+Direction: contract producer->consumer; otherwise earlier-in-plan -> later (a
+total order, so the graph is always a DAG).
+"""
+
+import argparse
+import fnmatch
+import hashlib
+import json
+import os
+import re
+import sys
+
+
+# --------------------------------------------------------------------------- #
+# plan.md parsing — a tiny, dependency-free subset parser for ```task blocks
+# --------------------------------------------------------------------------- #
+TASK_BLOCK_RE = re.compile(r"```task\s*\n(.*?)```", re.S)
+
+
+def _parse_list(inline):
+    inline = inline.strip()
+    if inline.startswith("[") and inline.endswith("]"):
+        inner = inline[1:-1].strip()
+        return [x.strip().strip("'\"") for x in inner.split(",") if x.strip()]
+    return []
+
+
+def parse_plan(text):
+    """Return an ordered list of task dicts: id, agent, footprint, produces, consumes."""
+    tasks = []
+    for block in TASK_BLOCK_RE.findall(text):
+        task = {"id": None, "agent": None, "footprint": [], "produces": [], "consumes": []}
+        key = None
+        for raw in block.splitlines():
+            line = raw.rstrip()
+            if not line.strip():
+                continue
+            m = re.match(r"^(\w+):\s*(.*)$", line)
+            if m and not line.startswith((" ", "\t", "-")):
+                key, val = m.group(1), m.group(2).strip()
+                if key in ("footprint", "produces", "consumes"):
+                    task[key] = _parse_list(val) if val else []
+                elif key in ("id", "agent"):
+                    task[key] = val.strip("'\"")
+                continue
+            item = re.match(r"^\s*-\s*(.+)$", line)
+            if item and key in ("footprint", "produces", "consumes"):
+                task[key].append(item.group(1).strip().strip("'\""))
+        if task["id"]:
+            task["footprint"] = [norm(p) for p in task["footprint"]]
+            tasks.append(task)
+    return tasks
+
+
+def norm(p):
+    return p.replace("\\", "/").strip()
+
+
+# --------------------------------------------------------------------------- #
+# graphify structural graph — defensive loader + undirected BFS expansion
+# --------------------------------------------------------------------------- #
+def load_graph(graphify_out):
+    path = os.path.join(graphify_out, "graph.json")
+    if not os.path.exists(path):
+        return None
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            return json.load(fh)
+    except Exception:
+        return None
+
+
+def node_file(node):
+    for k in ("file", "path", "source_location", "location", "filepath"):
+        v = node.get(k) if isinstance(node, dict) else None
+        if isinstance(v, str) and v:
+            return norm(v.split(":", 1)[0])
+    return None
+
+
+def build_index(graph):
+    """Return (node_file_map, adjacency) from a best-effort read of graph.json."""
+    nodes = graph.get("nodes", []) if isinstance(graph, dict) else []
+    files, adj = {}, {}
+    for n in nodes:
+        nid = n.get("id") if isinstance(n, dict) else None
+        if nid is None:
+            continue
+        files[nid] = node_file(n)
+        adj.setdefault(nid, set())
+    for e in graph.get("edges", []) if isinstance(graph, dict) else []:
+        if isinstance(e, dict):
+            a, b = e.get("source", e.get("from")), e.get("target", e.get("to"))
+        elif isinstance(e, (list, tuple)) and len(e) >= 2:
+            a, b = e[0], e[1]
+        else:
+            continue
+        if a in adj and b in adj:
+            adj[a].add(b)
+            adj[b].add(a)
+    return files, adj
+
+
+def matches(fpath, entry):
+    if fpath is None:
+        return False
+    entry = norm(entry)
+    if entry.endswith("/"):
+        return fpath.startswith(entry)
+    if any(c in entry for c in "*?["):
+        return fnmatch.fnmatch(fpath, entry)
+    return fpath == entry or fpath.startswith(entry + "/")
+
+
+def expand(footprint, files, adj, depth):
+    """Expand a footprint to a sorted file set via <=depth undirected hops."""
+    if not files:
+        return sorted(set(footprint))
+    seeds = {nid for nid, f in files.items() if any(matches(f, e) for e in footprint)}
+    frontier, seen = set(seeds), set(seeds)
+    for _ in range(max(0, depth)):
+        nxt = set()
+        for nid in frontier:
+            nxt |= adj.get(nid, set())
+        nxt -= seen
+        seen |= nxt
+        frontier = nxt
+    expanded = {files[nid] for nid in seen if files.get(nid)}
+    return sorted(expanded | set(footprint))
+
+
+# --------------------------------------------------------------------------- #
+# edge computation
+# --------------------------------------------------------------------------- #
+def common_key(a_expanded, b_expanded):
+    """First shared file/dir between two expanded sets, deterministically."""
+    for x in sorted(a_expanded):
+        for y in sorted(b_expanded):
+            if x == y or x.startswith(y.rstrip("/") + "/") or y.startswith(x.rstrip("/") + "/"):
+                return x if len(x) <= len(y) else y
+    return None
+
+
+def compute_edges(tasks):
+    order = {t["id"]: i for i, t in enumerate(tasks)}
+    raw = {t["id"]: set(t["footprint"]) for t in tasks}
+    exp = {t["id"]: set(t["_expanded"]) for t in tasks}
+    edges = {}
+
+    # contract edges: producer -> consumer
+    for p in tasks:
+        for c in tasks:
+            if p["id"] == c["id"]:
+                continue
+            shared = set(p.get("produces", [])) & set(c.get("consumes", []))
+            for iface in sorted(shared):
+                edges[(p["id"], c["id"])] = "contract: %s" % iface
+
+    # footprint edges: overlap / shared_dependent, directed by plan order
+    ids = [t["id"] for t in tasks]
+    for i in range(len(ids)):
+        for j in range(i + 1, len(ids)):
+            a, b = ids[i], ids[j]
+            key = common_key(exp[a], exp[b])
+            if key is None:
+                continue
+            frm, to = (a, b) if order[a] <= order[b] else (b, a)
+            if (frm, to) in edges or (to, frm) in edges:
+                continue  # a contract edge already orders this pair
+            in_raw = any(matches(f, key) or matches(key, f) for f in raw[a]) and \
+                     any(matches(f, key) or matches(key, f) for f in raw[b])
+            reason = ("overlap: %s" if in_raw else "shared_dependent: %s") % key
+            edges[(frm, to)] = reason
+
+    return [{"from": f, "to": t, "reason": r} for (f, t), r in
+            sorted(edges.items(), key=lambda kv: kv[0])]
+
+
+# --------------------------------------------------------------------------- #
+# entry points
+# --------------------------------------------------------------------------- #
+def build_task_graph(plan_path, graphify_out, depth):
+    text = open(plan_path, "r", encoding="utf-8").read()
+    tasks = parse_plan(text)
+    graph = load_graph(graphify_out)
+    files, adj = build_index(graph) if graph else ({}, {})
+
+    for t in sorted(tasks, key=lambda x: x["id"]):
+        t["_expanded"] = expand(t["footprint"], files, adj, depth)
+
+    tasks_sorted = sorted(tasks, key=lambda x: x["id"])
+    out_tasks = [{
+        "id": t["id"], "agent": t.get("agent"),
+        "footprint": sorted(t["footprint"]),
+        "expanded_footprint": t["_expanded"],
+        "produces": sorted(t.get("produces", [])),
+        "consumes": sorted(t.get("consumes", [])),
+    } for t in tasks_sorted]
+
+    gv = "none"
+    if isinstance(graph, dict):
+        gv = str(graph.get("graphify_version") or graph.get("version") or "unknown")
+
+    return {
+        "generated_from": {
+            "plan_sha256": hashlib.sha256(text.encode("utf-8")).hexdigest(),
+            "graphify_version": gv,
+            "dependency_depth": depth,
+        },
+        "tasks": out_tasks,
+        "edges": compute_edges(tasks_sorted),
+    }
+
+
+def dumps_stable(obj):
+    return json.dumps(obj, indent=2, ensure_ascii=False, sort_keys=False) + "\n"
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="Deterministic task-dependency extractor")
+    ap.add_argument("--plan")
+    ap.add_argument("--out")
+    ap.add_argument("--files", nargs="+")
+    ap.add_argument("--graphify-out", default="graphify-out")
+    ap.add_argument("--depth", type=int, default=None)
+    args = ap.parse_args(argv)
+
+    depth = args.depth if args.depth is not None else 1
+
+    if args.files:
+        graph = load_graph(args.graphify_out)
+        files, adj = build_index(graph) if graph else ({}, {})
+        touched = expand([norm(f) for f in args.files], files, adj, depth)
+        report = {"input": [norm(f) for f in args.files],
+                  "depth": depth,
+                  "graph": "present" if graph else "absent",
+                  "touched": touched}
+        sys.stdout.write(dumps_stable(report))
+        return 0
+
+    if not (args.plan and args.out):
+        ap.error("provide either --files, or both --plan and --out")
+
+    result = build_task_graph(args.plan, args.graphify_out, depth)
+    os.makedirs(os.path.dirname(os.path.abspath(args.out)), exist_ok=True)
+    with open(args.out, "w", encoding="utf-8") as fh:
+        fh.write(dumps_stable(result))
+    sys.stderr.write("task-graph.json: %d tasks, %d edges\n"
+                     % (len(result["tasks"]), len(result["edges"])))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/template/.claude/scripts/version.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""version.py — the Version Controller CLI.
+
+    python .claude/scripts/version.py baseline  <feature>            # capture pre-feature deps
+    python .claude/scripts/version.py deps       <feature>            # recompute + show dep changes
+    python .claude/scripts/version.py ack-deps   <feature> [--who X]  # acknowledge major bumps
+    python .claude/scripts/version.py bump       <feature> [--level major|minor|patch] [--now TS]
+    python .claude/scripts/version.py snapshot   <feature> <milestone> [--now TS]
+    python .claude/scripts/version.py status     <feature>
+
+Dependency baseline is captured at approval (approve-plan.py calls `baseline`);
+the tracker hook diffs against it; `bump` writes VERSION + CHANGELOG; `snapshot`
+records development history. Keep sha256/semver logic in version_lib so the hook
+and this CLI never disagree.
+"""
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "hooks"))
+import harness_lib as lib  # noqa: E402
+import version_lib as ver  # noqa: E402
+
+REPO = str(Path(os.environ.get("CLAUDE_PROJECT_DIR") or Path.cwd()))
+
+
+def spec_of(feature):
+    return os.path.join(REPO, "specs", feature)
+
+
+def _cfg():
+    return lib.load_config(REPO).get("versioning", {})
+
+
+def cmd_baseline(a):
+    spec = spec_of(a.feature)
+    os.makedirs(spec, exist_ok=True)
+    deps = ver.snapshot_deps(REPO, _cfg().get("manifests"))
+    lib.write_json(os.path.join(spec, "dependencies.baseline.json"), deps)
+    sys.stderr.write("baseline: %d dependencies captured for '%s'\n" % (len(deps), a.feature))
+    return 0
+
+
+def cmd_deps(a):
+    spec = spec_of(a.feature)
+    baseline = lib.read_json(os.path.join(spec, "dependencies.baseline.json"))
+    if baseline is None:
+        sys.stderr.write("no baseline — run: version.py baseline %s (at approval)\n" % a.feature)
+        return 1
+    changes = ver.diff_deps(baseline, ver.snapshot_deps(REPO, _cfg().get("manifests")))
+    prev = lib.read_json(os.path.join(spec, "dependencies.json"), default={}) or {}
+    lib.write_json(os.path.join(spec, "dependencies.json"), {
+        "changes": changes, "has_major": ver.has_major(changes),
+        "acknowledged": bool(prev.get("acknowledged")) and not ver.has_major(changes),
+    })
+    print(json.dumps(changes, indent=2))
+    return 0
+
+
+def cmd_ack_deps(a):
+    spec = spec_of(a.feature)
+    dp = os.path.join(spec, "dependencies.json")
+    deps = lib.read_json(dp, default={}) or {}
+    deps["acknowledged"] = True
+    deps["acknowledged_by"] = a.who
+    deps["acknowledged_at"] = a.now or datetime.now(timezone.utc).isoformat()
+    lib.write_json(dp, deps)
+    sys.stderr.write("acknowledged major dependency changes for '%s'\n" % a.feature)
+    return 0
+
+
+def cmd_bump(a):
+    spec = spec_of(a.feature)
+    level = a.level or ver.plan_version_impact(spec) or "minor"
+    current = ver.read_root_version(REPO)
+    new = ver.next_version(current, level)
+    now = a.now or datetime.now(timezone.utc).isoformat()
+
+    with open(os.path.join(REPO, "VERSION"), "w", encoding="utf-8") as fh:
+        fh.write(new + "\n")
+
+    deps = lib.read_json(os.path.join(spec, "dependencies.json"), default={}) or {}
+    dep_line = "none"
+    if deps.get("changes"):
+        dep_line = ", ".join("%s %s->%s (%s)" % (c["name"], c["from"], c["to"], c["severity"])
+                             for c in deps["changes"])
+    entry = ("## %s — %s\n\n- Release level: **%s**\n- Feature: `%s`\n- Dependency changes: %s\n\n"
+             % (new, now[:10] if now else "", level, a.feature, dep_line))
+    clog = os.path.join(REPO, "CHANGELOG.md")
+    existing = ""
+    if os.path.exists(clog):
+        with open(clog, "r", encoding="utf-8", errors="ignore") as fh:
+            existing = fh.read()
+    header = "# Changelog\n\n"
+    body = existing[len(header):] if existing.startswith(header) else existing
+    with open(clog, "w", encoding="utf-8") as fh:
+        fh.write(header + entry + body)
+
+    lib.write_json(os.path.join(spec, "version.json"),
+                   {"code_version": new, "level": level, "previous": current, "at": now})
+    sys.stderr.write("bumped %s -> %s (%s) and wrote CHANGELOG for '%s'\n" % (current, new, level, a.feature))
+    return 0
+
+
+def cmd_snapshot(a):
+    dev = ver.record_snapshot(spec_of(a.feature), a.milestone,
+                              now=a.now or datetime.now(timezone.utc).isoformat())
+    sys.stderr.write("dev-version %d snapshot '%s' for '%s'\n" % (dev, a.milestone, a.feature))
+    return 0
+
+
+def cmd_status(a):
+    spec = spec_of(a.feature)
+    deps = lib.read_json(os.path.join(spec, "dependencies.json"), default={}) or {}
+    vj = lib.read_json(os.path.join(spec, "version.json"), default={}) or {}
+    hist = lib.read_json(os.path.join(spec, "history.json"), default={}) or {}
+    print("Version status — %s" % a.feature)
+    print("  code_version: %s (%s)" % (vj.get("code_version", "—"), vj.get("level", "—")))
+    print("  dependency changes: %d (major=%s, acknowledged=%s)"
+          % (len(deps.get("changes", [])), deps.get("has_major", False), deps.get("acknowledged", False)))
+    print("  dev_version: %s (%d milestones)" % (hist.get("dev_version", "—"), len(hist.get("entries", []))))
+    return 0
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    for name in ("baseline", "deps", "status"):
+        s = sub.add_parser(name); s.add_argument("feature")
+    s = sub.add_parser("ack-deps"); s.add_argument("feature"); s.add_argument("--who", default="human"); s.add_argument("--now")
+    s = sub.add_parser("bump"); s.add_argument("feature"); s.add_argument("--level", choices=["major", "minor", "patch"]); s.add_argument("--now")
+    s = sub.add_parser("snapshot"); s.add_argument("feature"); s.add_argument("milestone"); s.add_argument("--now")
+    a = ap.parse_args(argv)
+    return {
+        "baseline": cmd_baseline, "deps": cmd_deps, "ack-deps": cmd_ack_deps,
+        "bump": cmd_bump, "snapshot": cmd_snapshot, "status": cmd_status,
+    }[a.cmd](a)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/template/.claude/skills/contract-writing/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: contract-writing
+description: How to write the interface contracts that let specialists work in parallel without colliding. Use in the planner, before finalizing the task list — contracts are written before any implementation.
+---
+
+# contract-writing
+
+Contracts are the harness's answer to the cross-specialist seam problem. They fix
+every interface **before** implementation, so a frontend task builds against the
+agreed API shape rather than the backend's half-finished code. A contract is a
+promise a reviewer can check a diff against.
+
+## Principle
+Write the contract for a seam **only where two tasks meet**. Internal
+implementation detail is not a contract. If exactly one task touches something,
+it needs no contract — footprint ownership is enough.
+
+## The three usual contracts (write what the feature needs, name each interface)
+
+`contracts/api.yaml` — endpoint shapes the backend *produces* and the frontend
+*consumes*. Method, path, request body, response body, error responses. Field
+names here are law: the classic seam bug is a frontend reading `refundId` when the
+contract (and backend) say `refund_id`.
+
+```yaml
+cancel-api:            # <- the interface name tasks reference in produces/consumes
+  POST /orders/{id}/cancel:
+    request:  { reason: string }
+    response: { status: "cancelled", refund_id: string, refunded_amount: number }
+    errors:   { 409: "already cancelled", 422: "not cancellable" }
+```
+
+`contracts/migration.md` — the DB shape the data task *produces*: tables/columns
+added or changed, nullability, indexes, reversibility. Downstream API tasks
+`consume` it.
+
+`contracts/components.md` — component props / client-state contracts the frontend
+owns and any shared UI seam.
+
+## Naming interfaces
+Give each seam a short id (`cancel-api`, `migration`) and use it in the plan's
+`produces:` / `consumes:` lists. `extract-deps.py` turns a produce→consume pair
+into a sequential edge even when the two tasks share no files — that is how the
+schedule knows the frontend waits on the backend.
+
+## Checklist before finalizing the plan
+- Every cross-task seam has a named contract entry.
+- Every task that depends on a seam lists it in `consumes:`.
+- No contract describes a purely internal detail (over-specifying creates false
+  edges and needless serialization).

package/template/.claude/skills/discovery-interview/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: discovery-interview
+description: Protocol-driven feature discovery. Use on the main thread at the start of /feature (and on every escalation re-entry) to interview the user for edge cases, non-functionals, and acceptance criteria, then write discovery.md.
+---
+
+# discovery-interview
+
+Discovery is a **phase on the main thread**, not a subagent — subagents cannot
+talk to the user. Your job is to extract the requirements a plan can be built on
+and the acceptance criteria a review can be judged against. Interview
+protocol-driven, not generically.
+
+## Protocol — cover all four, in order
+
+1. **Intent & scope.** One sentence: what changes for the user? What is explicitly
+   out of scope? Name the modules you expect to touch (confirm against graphify).
+
+2. **Edge cases.** Push hard here — this is where ambiguity that later stalls the
+   pipeline is cheapest to resolve. Ask the awkward ones concretely:
+   - boundary states ("an already-refunded order?", "a partial shipment?")
+   - concurrency ("two cancels race?"), empty/limit cases, failure/rollback paths.
+
+3. **Non-functionals.** Idempotency, performance budgets, security/authz
+   constraints, observability/audit requirements, backward compatibility.
+
+4. **Acceptance criteria.** Concrete, checkable statements, each labelled with a
+   stable id — **AC1, AC2, AC3, …** — one per line:
+   ```
+   - AC1: cancelling a shipped order refunds only the unshipped portion
+   - AC2: refunds are idempotent (a repeated cancel does not double-refund)
+   ```
+   These ids are load-bearing: the planner tags each task with the ACs it
+   `satisfies:`, and the requirements gate refuses to proceed unless every AC is
+   covered by a task and no task invents an AC that isn't here (scope creep). They
+   are also the reviewer's rubric — vague criteria produce `ambiguity` failures.
+
+## Rules
+- Ask, don't assume. One unresolved ambiguity here is worth ten confident wrong
+  guesses later. If the user says "you decide", record the decision explicitly as
+  a chosen default so the reviewer can check it.
+- **Leave no unresolved markers.** `TBD`, `TODO`, `???`, "clarify with…", "not
+  sure", "decide later" in discovery.md will freeze the pipeline at the
+  requirements gate — resolve them with the user now, or record an explicit
+  chosen default. An unresolved marker is an unfinished interview.
+- Keep it tight — a handful of high-leverage questions, not an interrogation.
+
+## Output — `specs/<feature>/discovery.md`
+Sections (all four are required; the requirements gate checks for them):
+**Intent & Scope** (explicit in-scope AND out-of-scope), **Edge Cases** (Q→A),
+**Non-functionals**, **Acceptance Criteria** (AC1, AC2, … — checkable, one per line).
+
+## On escalation re-entry
+When the orchestrator escalates, you are re-entered with a specific question and
+the conflicting constraint. Get the answer, then **append** a dated
+`## Escalation: <topic>` section to `discovery.md` — never rewrite prior content.
+The append is the new requirements information the plan is patched from.

package/template/.claude/skills/review-taxonomy/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: review-taxonomy
+description: The failure classification the reviewer must apply. Use in the reviewer to assign a failure_class, which sets the retry policy the dispatch gate enforces. Also defines the repeat-finding early-stop rule.
+---
+
+# review-taxonomy
+
+Your `failure_class` is not a label — it selects the retry policy the dispatch
+gate enforces by exit code. Classify precisely; the wrong class either wastes
+retries on an unretryable problem or hard-stops a fixable one.
+
+## Decision tree (apply top to bottom; first match wins)
+
+1. **security** — a vulnerability (injection, authz bypass, secret exposure,
+   unsafe deserialization). → `fail`, **0 retries**, hard stop for human review.
+   Rationale is policy, not capability: you do not let an agent iterate until the
+   scanner goes quiet. Never downgrade a real security finding to unblock a run.
+
+2. **ambiguity** — you cannot determine the *intended* behavior from discovery +
+   contracts (e.g. "should cancelling a partially-shipped order refund the shipped
+   portion?"). → `fail`, **0 retries**. Retrying ambiguity only manufactures
+   confident guesses; it must go back to the human. Name the exact undecided
+   question in a finding — the orchestrator will ask the user verbatim.
+
+3. **contract** — the implementation does not match `contracts/` (wrong field
+   name, wrong status code, missing endpoint). → `fail`, **1 retry**. A *second*
+   contract failure means the contract itself is ambiguous → escalate as ambiguity.
+
+4. **mechanical** — tests fail, type/lint errors, a missing migration; the fix is
+   derivable from the error output. → `fail`, **2 retries** (3 attempts total).
+
+If none apply and the work meets the acceptance criteria and stays in footprint:
+→ `status: "pass"`, `failure_class: null`.
+
+## Findings
+Each finding: `{ id, severity, file, detail }`. `detail` must be specific enough
+that the specialist can act without guessing (name the file, the symbol, the
+expected vs actual). Severity `error` blocks a pass; `warn` does not.
+
+## Repeat-finding early stop (mandatory)
+Before writing your verdict, read the previous attempt's `review.<task>.*.json`.
+If any finding is essentially identical to one you filed last attempt, set
+`"repeat_finding": true`. Two identical failures predict a third — the harness
+escalates immediately rather than spending the remaining retry budget confirming
+the specialist doesn't understand the fix.
+
+## Integration mode
+Same taxonomy, but over the combined diff plus the graphify pass on touched files.
+The seam bug you are hunting (a parallel task still reading a renamed field)
+usually classes as `contract`. Record `changeset` on a pass — the commit gate
+checks it.

package/template/CLAUDE.harness.md

@@ -0,0 +1,68 @@
+<!-- harness:begin v1.0 -->
+## Loop Engineering — Agent Harness
+
+This repo runs the Loop Engineering harness. **Policy lives in exit codes and
+on-disk artifacts, not in prose** — hooks and scripts enforce the rules below; you
+exercise judgment within them. Files in `specs/<feature>/` are the pipeline;
+`harness.config.json` holds every knob. Any gate that blocks tells you the legal
+next move — do that, don't route around it.
+
+### Retrieval order — always graphify → skills → memory
+Before broad file exploration, query the knowledge graph: `graphify query "<q>"`.
+If `graphify-out/graph.json` is missing, initialize with `/graphify .` (it
+self-installs and builds it). A hook nudges broad `Grep`/`Glob` toward the graph
+once per session; narrow, file-scoped reads pass through.
+
+### Features run through `/feature` — everything else is untouched
+Small edits do not use the pipeline. `/feature` opens a discovery interview, then
+drives: context → plan + contracts → **plan approval** → dispatch → review →
+integration review → **version** → commit. Humans are needed at exactly two
+points: the interview/approval and escalations.
+
+### The enforced gates (you cannot talk past these)
+- **Requirements gate** — refuses to proceed on an ambiguous intention, vague or
+  unstructured requirements (need Intent & Scope, edge cases, non-functionals, and
+  `AC1, AC2…` acceptance criteria — no TBD/??? markers), a wrong flow, or a plan
+  that has diverged from the acceptance criteria (an AC covered by no task, or a
+  task inventing scope). On block, **re-enter interview mode** — these go to the
+  user, never to a guess.
+- **Plan-approval boundary** — `dispatch-gate.py` refuses every dispatch until
+  `specs/<f>/approvals.json` matches `plan.md`'s hash. Sign with
+  `python .claude/scripts/approve-plan.py <feature> --budget <tokens>`. Editing the
+  plan after approval re-freezes automation. In headless mode (`HARNESS_AUTO_APPROVE=1`)
+  self-approve after drafting — a logged decision — unless discovery is ambiguous.
+- **Dispatch gate** — enforces approval, task-graph freshness, dependency order,
+  retry caps, the circuit breaker, and a context-size limit (Rule 1: a dispatch
+  prompt carries only the task's slice — never the full plan, discovery, or history).
+- **Circuit breaker** — `state.json` `health` becomes `tripped` on retry caps,
+  repeat findings, too many escalations, footprint violations, or token-burndown
+  breach. Then all dispatch is refused and your only move is to escalate with the
+  evidence in `state.json` / `divergence.json`.
+- **Commit gate** — `git commit` / `gh pr create` is blocked until a passing
+  **integration review** exists for the current diff.
+- **Version gate** — commit is also blocked until the feature is versioned:
+  major dependency bumps acknowledged (`version.py ack-deps`), a code semver bump +
+  `CHANGELOG.md` entry (`version.py bump`), and a development snapshot
+  (`version.py snapshot <feature> integrated`).
+
+### Rules you must follow
+- **State is hook-owned.** Never hand-edit `state.json`, `review.*.json`,
+  `approvals.json`, or the version/dependency/history files.
+- **Task-scoped dispatch (Rule 1).** Begin each pipeline Task prompt with
+  `FEATURE: <slug>` (specialists add `TASK-ID: <id>`), and include only that task's
+  entry, its contracts slice, and — on retry — the latest findings.
+- **Stateless retries (Rule 3).** A retry is a fresh subagent given the findings and
+  the failed code as a diff to correct — never its own prior reasoning.
+- **Contracts before code.** Specialists implement against `contracts/`, stay inside
+  their declared footprint, and report anything cross-seam as a finding.
+- **Escalation is structured re-entry.** Present the failure/condition and one
+  specific question; append the answer to `discovery.md`; re-approve if the plan
+  changed. An escalation produces an artifact update, not a chat apology.
+- **Compaction is fine.** After a compact, trust `specs/<feature>/` and the injected
+  snapshot — re-read from disk rather than compacted memory.
+
+Artifacts per feature live in `specs/<feature>/` (discovery, context-pack, plan,
+contracts, task-graph, approvals, state, reviews, dependencies, version, history).
+The autonomous driver processes `specs/_queue.json`; parked features await a human
+in `specs/_answers.json`.
+<!-- harness:end -->