loop-engineering-harness 1.0.0

package/src/loop.js

@@ -0,0 +1,181 @@
+'use strict';
+// L4 — the outer driver (DevelopmentUpdates.md §4).
+//
+// Pulls features off a queue and runs each in a FRESH headless session
+// (`claude -p`), one feature = one session (Rule 4). It never revives a context:
+// resuming a parked feature is a brand-new session rehydrated from specs/ by the
+// session-rehydrate hook — recover-from-compaction and resume-from-parking are
+// deliberately the same mechanism.
+//
+// Exactly three terminal states are read back from specs/<f>/state.json:
+//   committed  -> feature done, move on
+//   escalated  -> breaker tripped / task escalated: PARK (a question for the
+//                 human) and keep the queue moving — escalations do not stall it
+//   needs_approval -> plan drafted but not signed: PARK for the human gate
+//
+// The `runner` is injectable so the queue logic is unit-testable without
+// spawning a model. The default runner shells out to `claude -p`.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function readJSON(p, dflt) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return dflt; }
+}
+function writeJSON(p, obj) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(obj, null, 2) + '\n');
+}
+function slug(s) {
+  return String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'feature';
+}
+
+function queuePath(root) { return path.join(root, 'specs', '_queue.json'); }
+function answersPath(root) { return path.join(root, 'specs', '_answers.json'); }
+
+function loadQueue(root) {
+  return readJSON(queuePath(root), { features: [] });
+}
+function addToQueue(root, description, opts) {
+  opts = opts || {};
+  const q = loadQueue(root);
+  const id = opts.id || slug(description);
+  if (q.features.some((f) => f.id === id)) throw new Error(`feature '${id}' already queued`);
+  q.features.push({
+    id, description, status: 'pending',
+    auto_approve: !!opts.autoApprove, queuedAt: opts.now || null,
+  });
+  writeJSON(queuePath(root), q);
+  return id;
+}
+
+// ---- terminal-state detection (reads only disk) --------------------------
+function classify(root, id) {
+  const spec = path.join(root, 'specs', id);
+  const state = readJSON(path.join(spec, 'state.json'), null);
+  const plan = fs.existsSync(path.join(spec, 'plan.md'));
+  const approved = fs.existsSync(path.join(spec, 'approvals.json'));
+
+  if (state && state.phase === 'committed') return { terminal: 'committed' };
+  if (state && (state.health === 'tripped' ||
+      Object.values(state.tasks || {}).some((t) => t.status === 'escalate'))) {
+    return { terminal: 'escalated', reasons: state.health_reasons || ['task escalated'] };
+  }
+  if (plan && !approved) return { terminal: 'needs_approval', reasons: ['awaiting human plan approval'] };
+  return { terminal: 'incomplete', reasons: ['session ended without a terminal state'] };
+}
+
+function park(root, feature, cls) {
+  const ans = readJSON(answersPath(root), { parked: [] });
+  ans.parked = ans.parked.filter((p) => p.id !== feature.id);
+  ans.parked.push({
+    id: feature.id, terminal: cls.terminal,
+    reasons: cls.reasons || [], description: feature.description,
+    question: `Resolve '${feature.id}' (${cls.terminal}): ${(cls.reasons || []).join('; ')}. ` +
+      `Append the answer to specs/${feature.id}/discovery.md, then re-queue.`,
+  });
+  writeJSON(answersPath(root), ans);
+}
+
+// ---- token burndown producer (L3) ----------------------------------------
+// The driver is the one place with a real token count (from `claude -p` usage),
+// so it is where burndown is fed. recompute_health reads divergence.json.tokens_spent.
+function recordTokens(root, id, usage) {
+  if (!usage) return;
+  const spec = path.join(root, 'specs', id);
+  const dp = path.join(spec, 'divergence.json');
+  const div = readJSON(dp, {});
+  const spent = (usage.input_tokens || 0) + (usage.output_tokens || 0);
+  div.tokens_spent = (div.tokens_spent || 0) + spent;
+  writeJSON(dp, div);
+  return div.tokens_spent;
+}
+
+// ---- the default (real) runner: a fresh `claude -p` session --------------
+function claudeRunner(feature, ctx) {
+  const resume = fs.existsSync(path.join(ctx.root, 'specs', feature.id, 'plan.md'));
+  const prompt = resume
+    ? `Resume feature '${feature.id}'. A session is being rehydrated from ` +
+      `specs/${feature.id}/. Read state.json, then continue the pipeline per ` +
+      `task-graph.json to a terminal state.`
+    : `/feature ${feature.description}`;
+  const auto = ctx.autoApprove || feature.auto_approve;
+  const bin = ctx.claudeBin || 'claude';
+  const args = ['-p', prompt, '--output-format', 'json'];
+  if (ctx.permissionMode) args.push('--permission-mode', ctx.permissionMode);
+  const r = spawnSync(bin, args, {
+    cwd: ctx.root, encoding: 'utf8', timeout: ctx.timeoutMs || 1800000,
+    env: Object.assign({}, process.env, auto ? { HARNESS_AUTO_APPROVE: '1' } : {}),
+  });
+  if (r.error) throw new Error(`failed to spawn '${bin}': ${r.error.message}. Is Claude Code installed and on PATH?`);
+  let usage = null;
+  try { usage = (JSON.parse(r.stdout) || {}).usage || null; } catch (_) { /* non-JSON tail */ }
+  return { usage, raw: r.stdout };
+}
+
+// ---- the loop -------------------------------------------------------------
+async function processQueue(root, opts) {
+  opts = opts || {};
+  root = path.resolve(root);
+  const runner = opts.runner || claudeRunner;
+  const ctx = {
+    root, autoApprove: !!opts.autoApprove, claudeBin: opts.claudeBin,
+    permissionMode: opts.permissionMode, timeoutMs: opts.timeoutMs,
+  };
+  const summary = { committed: [], escalated: [], needs_approval: [], incomplete: [] };
+
+  while (true) {
+    const q = loadQueue(root);
+    const feature = q.features.find((f) => f.status === 'pending');
+    if (!feature) break;
+
+    if (opts.log) opts.log(`▶ ${feature.id}: starting fresh session`);
+    let usage = null;
+    try {
+      const res = await runner(feature, ctx);
+      usage = res && res.usage;
+    } catch (err) {
+      feature.status = 'parked';
+      feature.error = err.message;
+      writeJSON(queuePath(root), q);
+      park(root, feature, { terminal: 'incomplete', reasons: [err.message] });
+      summary.incomplete.push(feature.id);
+      if (opts.once) break; else continue;
+    }
+    const total = recordTokens(root, feature.id, usage);
+
+    const cls = classify(root, feature.id);
+    if (cls.terminal === 'committed') {
+      feature.status = 'done';
+      summary.committed.push(feature.id);
+    } else {
+      feature.status = 'parked';
+      park(root, feature, cls);
+      summary[cls.terminal].push(feature.id);
+    }
+    feature.lastTokens = total || undefined;
+    writeJSON(queuePath(root), q); // persist after each feature (crash-safe)
+    if (opts.log) opts.log(`  ${feature.id} -> ${cls.terminal}${total ? ` (${total} tok)` : ''}`);
+    if (opts.once) break;
+  }
+  return summary;
+}
+
+// Re-queue a parked feature (after a human appended the answer to discovery.md).
+function requeue(root, id, now) {
+  const q = loadQueue(root);
+  const f = q.features.find((x) => x.id === id);
+  if (!f) throw new Error(`no queued feature '${id}'`);
+  f.status = 'pending';
+  f.requeuedAt = now || null;
+  writeJSON(queuePath(root), q);
+  const ans = readJSON(answersPath(root), { parked: [] });
+  ans.parked = ans.parked.filter((p) => p.id !== id);
+  writeJSON(answersPath(root), ans);
+}
+
+module.exports = {
+  processQueue, addToQueue, loadQueue, requeue, classify, claudeRunner,
+  queuePath, answersPath, slug,
+};

package/src/merge.js

@@ -0,0 +1,173 @@
+'use strict';
+// Low-level merge primitives shared by install/uninstall/detect.
+// Zero runtime dependencies — Node stdlib only.
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const BEGIN = '<!-- harness:begin v1.0 -->';
+const END = '<!-- harness:end -->';
+
+function read(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch (_) { return null; }
+}
+function readJSON(p) {
+  const raw = read(p);
+  if (raw === null) return undefined;
+  return JSON.parse(raw); // caller decides how to handle a throw (we abort)
+}
+function writeJSON(p, obj) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(obj, null, 2) + '\n');
+}
+
+// Detect a Python interpreter for the hook commands. Preference order lets the
+// same payload work on Windows (python / py) and unix (python3).
+function detectPython(explicit) {
+  const candidates = explicit ? [explicit] : ['python3', 'python', 'py -3'];
+  for (const c of candidates) {
+    try {
+      execSync(`${c} --version`, { stdio: 'ignore' });
+      return c;
+    } catch (_) { /* try next */ }
+  }
+  // Fall back to python3; the hooks fail-open, and the adopter can edit config.
+  return 'python3';
+}
+
+// ---- CLAUDE.md ------------------------------------------------------------
+// Append a delimited block; upgrades replace only the block; never touch the
+// adopter's own content.
+function mergeClaudeMd(targetPath, blockWithMarkers) {
+  const existing = read(targetPath);
+  if (existing === null) {
+    fs.writeFileSync(targetPath, blockWithMarkers.trimEnd() + '\n');
+    return { action: 'created' };
+  }
+  const b = existing.indexOf(BEGIN);
+  const e = existing.indexOf(END);
+  if (b !== -1 && e !== -1 && e > b) {
+    const before = existing.slice(0, b);
+    const after = existing.slice(e + END.length);
+    const next = before + blockWithMarkers.trim() + after;
+    fs.writeFileSync(targetPath, next);
+    return { action: 'upgraded' };
+  }
+  const sep = existing.endsWith('\n') ? '\n' : '\n\n';
+  fs.writeFileSync(targetPath, existing + sep + blockWithMarkers.trimEnd() + '\n');
+  return { action: 'appended' };
+}
+
+function stripClaudeMd(targetPath) {
+  const existing = read(targetPath);
+  if (existing === null) return { action: 'absent' };
+  const b = existing.indexOf(BEGIN);
+  const e = existing.indexOf(END);
+  if (b === -1 || e === -1 || e < b) return { action: 'no-block' };
+  let before = existing.slice(0, b);
+  let after = existing.slice(e + END.length);
+  let next = (before.replace(/\s+$/, '') + '\n' + after.replace(/^\s+/, '')).trim();
+  // If nothing but the block remained, remove the file entirely (byte-identity).
+  if (next === '') { fs.rmSync(targetPath, { force: true }); return { action: 'removed-file' }; }
+  fs.writeFileSync(targetPath, next + '\n');
+  return { action: 'stripped' };
+}
+
+// ---- settings.json --------------------------------------------------------
+// Deep-merge hook arrays. Existing entries are preserved and never reordered;
+// harness entries are appended, each already carrying "_harness": true.
+// A parse failure ABORTS — we never write a best-guess settings file.
+function mergeSettings(targetPath, payloadHooks, python) {
+  let settings = {};
+  const raw = read(targetPath);
+  if (raw !== null && raw.trim() !== '') {
+    try { settings = JSON.parse(raw); }
+    catch (err) {
+      throw new Error(
+        `Refusing to merge: ${targetPath} is not valid JSON (${err.message}). ` +
+        `Fix or remove it, then re-run.`);
+    }
+  }
+  settings.hooks = settings.hooks || {};
+  const appended = [];
+  for (const event of Object.keys(payloadHooks)) {
+    settings.hooks[event] = settings.hooks[event] || [];
+    for (const group of payloadHooks[event]) {
+      const g = JSON.parse(JSON.stringify(group));
+      for (const h of g.hooks) {
+        if (typeof h.command === 'string') h.command = h.command.replace(/__PYTHON__/g, python);
+      }
+      settings.hooks[event].push(g);
+      appended.push(event);
+    }
+  }
+  writeJSON(targetPath, settings);
+  return { appended };
+}
+
+// Remove every hook entry marked _harness; drop empty event arrays; if the whole
+// file reduces to {} remove it so the tree is byte-identical to pre-install.
+function stripSettings(targetPath) {
+  const raw = read(targetPath);
+  if (raw === null) return { action: 'absent' };
+  let settings;
+  try { settings = JSON.parse(raw); } catch (_) { return { action: 'unparseable-skip' }; }
+  if (!settings.hooks) return { action: 'no-hooks' };
+  for (const event of Object.keys(settings.hooks)) {
+    const groups = settings.hooks[event];
+    if (!Array.isArray(groups)) continue;
+    const kept = [];
+    for (const group of groups) {
+      const hooks = (group.hooks || []).filter((h) => h._harness !== true &&
+        !(typeof h.command === 'string' && /\.claude[\\/]hooks[\\/]/.test(h.command) &&
+          /(retrieval-nudge|commit-gate|dispatch-gate|requirements-gate|state-updater|trace-emitter|divergence-monitor|precompact-guard|session-rehydrate|artifact-size|version-tracker|version-gate)\.py/.test(h.command)));
+      if (hooks.length) kept.push(Object.assign({}, group, { hooks }));
+    }
+    if (kept.length) settings.hooks[event] = kept;
+    else delete settings.hooks[event];
+  }
+  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  if (Object.keys(settings).length === 0) {
+    fs.rmSync(targetPath, { force: true });
+    return { action: 'removed-file' };
+  }
+  writeJSON(targetPath, settings);
+  return { action: 'stripped' };
+}
+
+// ---- collision-safe file copy --------------------------------------------
+// Returns { dest, status: 'added'|'identical'|'renamed', renamedTo? }
+function copyFileSafe(src, dest) {
+  const content = fs.readFileSync(src);
+  if (fs.existsSync(dest)) {
+    const cur = fs.readFileSync(dest);
+    if (cur.equals(content)) return { dest, status: 'identical' };
+    const ext = path.extname(dest);
+    const renamed = dest.slice(0, -ext.length || undefined) + '.harness' + ext;
+    fs.mkdirSync(path.dirname(renamed), { recursive: true });
+    fs.writeFileSync(renamed, content);
+    return { dest, status: 'renamed', renamedTo: renamed };
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, content);
+  return { dest, status: 'added' };
+}
+
+const SKIP = new Set(['__pycache__', '.pytest_cache', '.DS_Store']);
+function walk(dir) {
+  const out = [];
+  for (const name of fs.readdirSync(dir)) {
+    if (SKIP.has(name) || name.endsWith('.pyc')) continue; // never ship build caches
+    const p = path.join(dir, name);
+    if (fs.statSync(p).isDirectory()) out.push(...walk(p));
+    else out.push(p);
+  }
+  return out;
+}
+
+module.exports = {
+  BEGIN, END, read, readJSON, writeJSON, detectPython,
+  mergeClaudeMd, stripClaudeMd, mergeSettings, stripSettings,
+  copyFileSafe, walk,
+};

package/src/metrics.js

@@ -0,0 +1,70 @@
+'use strict';
+// L5 — flywheel metrics (DevelopmentUpdates.md §5-6, Rule 5).
+//
+// The derived metric that matters is **tokens-per-passing-task**: when it creeps
+// up, a compression stage is leaking. This computes it per feature from disk
+// (state.json + divergence.json + approvals.json) so it works with or without
+// Langfuse. Langfuse dashboards (docs/langfuse-dashboards.md) chart the same
+// numbers over time; this is the local, always-available view.
+
+const fs = require('fs');
+const path = require('path');
+
+function readJSON(p, dflt) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return dflt; }
+}
+
+function computeMetrics(root) {
+  root = path.resolve(root);
+  const specs = path.join(root, 'specs');
+  const out = [];
+  if (!fs.existsSync(specs)) return out;
+
+  for (const name of fs.readdirSync(specs).sort()) {
+    if (name.startsWith('_')) continue; // queue/answer files
+    const dir = path.join(specs, name);
+    if (!fs.statSync(dir).isDirectory()) continue;
+
+    const state = readJSON(path.join(dir, 'state.json'), { tasks: {} });
+    const div = readJSON(path.join(dir, 'divergence.json'), {});
+    const approvals = readJSON(path.join(dir, 'approvals.json'), {});
+
+    const tasks = Object.values(state.tasks || {});
+    const passing = tasks.filter((t) => t.status === 'done').length;
+    const spent = div.tokens_spent || 0;
+    const budget = approvals.budget || 0;
+
+    out.push({
+      feature: name,
+      phase: state.phase || 'unknown',
+      health: state.health || 'ok',
+      tasks_total: tasks.length,
+      tasks_passing: passing,
+      tokens_spent: spent,
+      budget: budget || null,
+      burndown_pct: budget ? Math.round((100 * spent) / budget) : null,
+      tokens_per_passing_task: passing ? Math.round(spent / passing) : null,
+      footprint_violations: Object.values(div.footprint_violations || {}).reduce((a, b) => a + b, 0),
+    });
+  }
+  return out;
+}
+
+function formatMetrics(rows) {
+  if (!rows.length) return 'No features found under specs/.';
+  const L = ['Loop Engineering — flywheel metrics', ''];
+  for (const r of rows) {
+    L.push(`• ${r.feature}  [${r.phase}${r.health === 'tripped' ? ', BREAKER TRIPPED' : ''}]`);
+    L.push(`    tasks: ${r.tasks_passing}/${r.tasks_total} passing` +
+      (r.footprint_violations ? `   footprint-violations: ${r.footprint_violations}` : ''));
+    L.push(`    tokens: ${r.tokens_spent}` +
+      (r.budget ? ` / ${r.budget} budget  (${r.burndown_pct}% burndown)` : ' (no budget set)'));
+    if (r.tokens_per_passing_task != null) {
+      L.push(`    tokens-per-passing-task: ${r.tokens_per_passing_task}  ← leak detector`);
+    }
+    L.push('');
+  }
+  return L.join('\n');
+}
+
+module.exports = { computeMetrics, formatMetrics };

package/src/uninstall.js

@@ -0,0 +1,63 @@
+'use strict';
+// Reverses an install. With a manifest it is exact (byte-identical repo, minus
+// specs/). Without one it falls back to a conservative heuristic. specs/ is the
+// adopter's work product and is ALWAYS left in place.
+
+const fs = require('fs');
+const path = require('path');
+const m = require('./merge');
+const { MANIFEST_REL } = require('./install');
+
+function tryRmEmptyDirsUp(startDir, stopDir) {
+  let dir = startDir;
+  while (dir.startsWith(stopDir) && dir !== stopDir) {
+    try { fs.rmdirSync(dir); } catch (_) { break; } // non-empty -> stop
+    dir = path.dirname(dir);
+  }
+}
+
+function uninstall(target) {
+  target = path.resolve(target);
+  const manifestPath = path.join(target, MANIFEST_REL);
+  const manifest = m.readJSON(manifestPath);
+  const removed = [];
+
+  // settings + CLAUDE.md first (independent of manifest presence)
+  const setRes = m.stripSettings(path.join(target, '.claude', 'settings.json'));
+  const claudeRes = m.stripClaudeMd(path.join(target, 'CLAUDE.md'));
+
+  const toDelete = [];
+  if (manifest) {
+    for (const rel of manifest.filesAdded.concat(manifest.filesRenamed)) {
+      if (rel === 'harness.config.json' && !manifest.configWritten) continue;
+      toDelete.push(rel);
+    }
+  } else {
+    // Heuristic: delete the files this template is known to ship.
+    const { planClaudeFiles } = require('./detect');
+    for (const f of planClaudeFiles(target)) {
+      toDelete.push(path.relative(target, f.dest).replace(/\\/g, '/'));
+    }
+  }
+
+  for (const rel of toDelete) {
+    const abs = path.join(target, rel);
+    if (fs.existsSync(abs)) {
+      fs.rmSync(abs, { force: true });
+      removed.push(rel);
+      tryRmEmptyDirsUp(path.dirname(abs), target);
+    }
+  }
+
+  // remove the harness state dir (markers, manifest) and clean empties
+  fs.rmSync(path.join(target, '.claude', '.harness'), { recursive: true, force: true });
+  tryRmEmptyDirsUp(path.join(target, '.claude', 'agents'), target);
+  for (const d of ['agents', 'skills', 'commands', 'hooks', 'scripts']) {
+    tryRmEmptyDirsUp(path.join(target, '.claude', d), target);
+  }
+  tryRmEmptyDirsUp(path.join(target, '.claude'), path.dirname(target));
+
+  return { removed, settings: setRes.action, claudeMd: claudeRes.action, usedManifest: !!manifest };
+}
+
+module.exports = { uninstall };

package/template/.claude/agents/context-researcher.md

@@ -0,0 +1,47 @@
+---
+name: context-researcher
+description: Expands graphify queries and targeted source reading into a compact codebase brief. Use after discovery.md exists and before planning. Burns tokens freely in its own window; returns only context-pack.md.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the **context-researcher**. You run in an isolated window: you may read
+40k+ tokens of graph output and source, but the orchestrator will only ever see
+the one file you write. Spend context lavishly here so the orchestrator doesn't
+have to.
+
+## Retrieval order (mandatory): graphify → skills → memory
+1. **graphify first.** Start every investigation with the knowledge graph, not a
+   grep. If `graphify-out/graph.json` exists, run `graphify query "<question>"`
+   for each subsystem the feature touches. If it does **not** exist, the repo is
+   not initialized — stop and tell the orchestrator to run `/graphify .` (it
+   self-installs and builds the graph); do not fall back to blind scanning.
+2. **Then** read the specific files the graph surfaced as god nodes, shared
+   dependents, or seam points.
+3. Broad `Grep`/`Glob` is a last resort and is nudged against by a hook — if you
+   reach for it, you probably skipped step 1.
+
+## Reads
+- `specs/<feature>/discovery.md` (your assignment)
+- `graphify query` output; source files it points to
+
+## Writes — exactly one file
+- `specs/<feature>/context-pack.md`, **≤ ~2000 tokens**. Start with these
+  feature-wide sections:
+  - **What exists** — the modules/entities relevant to this feature
+  - **Dependency map** — what depends on what (name the shared dependents; these
+    become sequential edges later)
+  - **Conventions** — house patterns to match (error handling, naming, test style)
+  - **Risk notes** — shared code, cross-cutting callers, anything that will bite
+    a specialist (e.g. "refund logic is also called from the admin panel")
+- **Then, per-area sections keyed to the anticipated work areas (Context Rule 2).**
+  Structure the pack so each future specialist can be handed ONLY its slice — a
+  `## Area: database`, `## Area: backend`, `## Area: frontend` (name the areas the
+  feature actually spans). The orchestrator lifts one area into each task-scoped
+  dispatch prompt; feature-wide context inside a single task's window is itself a
+  distractor. If you cannot cleanly separate an area, say so in Risk notes rather
+  than dumping everything into one blob.
+
+## Must not
+- Do not write code, plans, or contracts. Do not edit anything but your one file.
+- Do not use Bash for anything other than `graphify` and read-only inspection.
+- Do not exceed the token budget — a bloated pack defeats the whole design.

package/template/.claude/agents/planner.md

@@ -0,0 +1,71 @@
+---
+name: planner
+description: Decomposes a feature into tasks with explicit file footprints and writes interface contracts BEFORE any implementation. Its final action always invokes extract-deps.py. Use after context-pack.md exists.
+tools: Read, Write, Grep, Bash
+---
+
+You are the **planner**. You turn discovery + context into a decomposition and,
+critically, the **contracts** that let specialists work in parallel without
+colliding. Contract-first planning is the seam-integrity mechanism of the whole
+harness — interfaces are fixed here, before anyone implements.
+
+Load the `contract-writing` skill before writing contracts.
+
+## Reads
+- `specs/<feature>/discovery.md`, `specs/<feature>/context-pack.md`
+
+## Writes
+1. `specs/<feature>/contracts/` — the interface agreements, written FIRST:
+   `api.yaml` (endpoint schemas), `migration.md` (DB shape), `components.md`
+   (props / client contracts). Whatever the feature needs; name interfaces so
+   tasks can reference them.
+2. `specs/<feature>/plan.md` — one `` ```task `` block per task. Every task
+   carries an **explicit file footprint** (the files it is allowed to touch) and,
+   where relevant, which contract interfaces it `produces` / `consumes`:
+
+   ```task
+   id: backend-orders-api
+   agent: specialist-backend
+   footprint:
+     - api/orders.ts
+   produces: [cancel-api]
+   consumes: [migration]
+   satisfies: [AC1, AC2]
+   est_tokens: 12000
+   ```
+
+   **`satisfies:` is the anti-divergence contract.** Tag every task with the
+   acceptance-criteria ids (from `discovery.md`) it delivers. The requirements
+   gate refuses to proceed unless **every** AC is covered by some task and **no**
+   task cites an AC that isn't in discovery.md. So: cover all of what was asked
+   (no gaps) and build only what was asked (no scope creep). If you find you need
+   a task with no AC, the requirement is missing — stop and flag it, don't invent
+   scope.
+
+   Give every task an **`est_tokens`** estimate (implementation + review + a
+   retry's worth of headroom). These sum into the approval package's budget and
+   feed the estimate-vs-actual metric (Rule 5) — the burndown ceiling the circuit
+   breaker later enforces is only as honest as these numbers, so estimate
+   deliberately, not reflexively.
+
+   Footprint rules: be precise and minimal. A footprint that is too broad forces
+   false sequential edges; one that is too narrow risks a specialist needing a
+   file it can't touch (which it must then report, not grab). Prefer specific
+   files over directories unless the task genuinely owns the whole directory.
+
+3. **Declare the release impact.** Put a line `VERSION-IMPACT: major|minor|patch`
+   in `plan.md` — the Version Controller uses it to compute the semver bump.
+   Breaking API/contract changes → `major`; new capability → `minor`; fix-only →
+   `patch`. This is part of what the human signs at approval.
+
+4. **Last action, always:** invoke the extractor so the schedule matches the plan:
+
+   ```
+   python .claude/scripts/extract-deps.py --plan specs/<feature>/plan.md --out specs/<feature>/task-graph.json
+   ```
+
+## Must not
+- Do not implement anything. Do not assign two tasks overlapping footprints and
+  call them parallel — the extractor will serialize them; that's correct, don't
+  fight it. Do not finish without running extract-deps.py (a stale or missing
+  task-graph.json will block every dispatch).

package/template/.claude/agents/reviewer.md

@@ -0,0 +1,64 @@
+---
+name: reviewer
+description: Reviews specialist work in two modes — per-task (diff vs plan + contract) and integration (combined diff + contract conformance + graphify pass over touched files). Emits a valid review.json with a failure_class. The native evaluation producer of the flywheel.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the **reviewer**. You are the harness's evaluation producer: your verdict
+is an artifact, and the commit gate is an exit code that reads it. Load the
+`review-taxonomy` skill before judging.
+
+## Two modes
+**Per-task** — review one specialist's diff against `plan.md` (did it stay in
+footprint?) and against `contracts/` (does it match the agreed interface?).
+
+**Integration** (after every task is `done`) — review the **combined** feature
+diff. Check exactly three things:
+1. the combined diff itself,
+2. `contracts/` conformance across all tasks,
+3. a `graphify query` over every touched file — did anyone change something that
+   other, untouched code depends on? (This is where cross-specialist seam bugs
+   surface — a renamed field a parallel task still reads the old way.)
+4. `specs/<feature>/dependencies.json` — if `has_major` is true, treat the
+   dependency bump as a finding to scrutinize (breaking upgrade, security, license).
+   Once satisfied it's safe, the human/orchestrator acknowledges it
+   (`version.py ack-deps`); an unacknowledged major bump keeps the version gate shut.
+
+## Reads
+- `git diff` (per-task: the task's files; integration: `git diff main...HEAD`)
+- `specs/<feature>/plan.md`, `contracts/`, prior `review.<task>.*.json`
+- `graphify query` on touched files
+
+## Writes — exactly one verdict file per review
+- Per-task: `specs/<feature>/review.<task>.<attempt>.json`
+- Integration: `specs/<feature>/review.integration.<attempt>.json`
+
+Schema (must be valid JSON):
+```json
+{
+  "task": "backend-orders-api",
+  "attempt": 2,
+  "status": "pass | fail",
+  "failure_class": "mechanical | contract | ambiguity | security | null",
+  "repeat_finding": false,
+  "findings": [
+    { "id": "F1", "severity": "error", "file": "api/orders.ts", "detail": "..." }
+  ],
+  "changeset": "<output of: python .claude/scripts/changeset.py>"
+}
+```
+
+## Rules
+- Classify every failure. The class sets the retry policy the dispatch gate
+  enforces — get it right (see the `review-taxonomy` skill for the decision tree).
+- **Diff your own findings across attempts.** If a finding repeats verbatim from
+  the previous attempt, set `"repeat_finding": true` — two identical failures
+  predict a third; the harness escalates instead of burning another retry.
+- For an integration review you intend to pass, you MUST record `changeset` from
+  `python .claude/scripts/changeset.py` — the commit gate only opens for the exact
+  diff you reviewed.
+- `security` and `ambiguity` are always `status: "fail"` with zero retries. Never
+  soften a security finding to get a run unblocked.
+
+## Must not
+- Do not fix the code. Do not edit `state.json`. You judge; you do not implement.