uni-harness 0.1.0

package/bin/cli.js

@@ -0,0 +1,371 @@
+#!/usr/bin/env node
+/**
+ * uni-harness — installer for the Claude Code agent harness kit
+ *
+ * Usage:
+ *   npx uni-harness init      [dir] [--force]   install the harness
+ *   npx uni-harness update    [dir] [--force]   update machinery files
+ *   npx uni-harness doctor    [dir]             diagnose the installation
+ *   npx uni-harness uninstall [dir] --yes       remove machinery files
+ *
+ * File boundary (the core contract of this installer):
+ *   machinery (managed)  — .claude/hooks/, .claude/skills/, .claude/agents/,
+ *                          harness/  → init installs them, update refreshes
+ *                          them. Hashes are recorded in
+ *                          .harness/kit-manifest.json so files the user has
+ *                          modified are NEVER overwritten (unless --force).
+ *   project-owned        — CLAUDE.md, .harness/commands.env,
+ *                          .claude/settings.json  → created by init when
+ *                          absent; update/uninstall never touch them.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+const MACHINERY_DIRS = ['.claude/hooks', '.claude/skills', '.claude/agents', 'harness'];
+const MANIFEST = '.harness/kit-manifest.json';
+const KIT_VERSION = require(path.join(PKG_ROOT, 'package.json')).version;
+
+// ── helpers ──────────────────────────────────────────────────────
+const sha256 = (file) =>
+  crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
+function walk(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (e.name === '__pycache__' || e.name === 'node_modules') continue;
+      out.push(...walk(p));
+    } else if (e.isFile() && e.name !== '.DS_Store' && !e.name.endsWith('.pyc')) {
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+function machineryFiles() {
+  const files = [];
+  for (const d of MACHINERY_DIRS) {
+    for (const f of walk(path.join(PKG_ROOT, d))) {
+      files.push(path.relative(PKG_ROOT, f));
+    }
+  }
+  return files.sort();
+}
+
+function copyInto(target, rel) {
+  const dst = path.join(target, rel);
+  fs.mkdirSync(path.dirname(dst), { recursive: true });
+  fs.copyFileSync(path.join(PKG_ROOT, rel), dst);
+  if (rel.endsWith('.sh')) {
+    try { fs.chmodSync(dst, 0o755); } catch { /* e.g. Windows */ }
+  }
+}
+
+function readManifest(target) {
+  const p = path.join(target, MANIFEST);
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+function writeManifest(target, files) {
+  const entries = {};
+  for (const rel of files) {
+    const p = path.join(target, rel);
+    if (fs.existsSync(p)) entries[rel] = sha256(p);
+  }
+  const p = path.join(target, MANIFEST);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(
+    { kitVersion: KIT_VERSION, installedAt: new Date().toISOString(), files: entries },
+    null, 2) + '\n');
+}
+
+function runHookTests(target) {
+  const t = path.join(target, 'harness/tests/test_hooks.sh');
+  if (!fs.existsSync(t)) return null;
+  const r = spawnSync('bash', [t], { cwd: target, encoding: 'utf8' });
+  if (r.error) return null; // no bash (e.g. Windows) — skip
+  return { ok: r.status === 0, out: (r.stdout || '') + (r.stderr || '') };
+}
+
+const log = (s) => process.stdout.write(s + '\n');
+
+// ── settings.json merge (init only) ──────────────────────────────
+// Hooks: append only the entries whose hook script is not yet registered
+// for that event. Everything the user already has is left untouched.
+// If the template ships a permissions block, it is used only when the
+// target has none at all — we never silently widen an existing one; missing
+// entries are printed as suggestions instead.
+function mergeSettings(target) {
+  const tplPath = path.join(PKG_ROOT, '.claude/settings.json');
+  const dstPath = path.join(target, '.claude/settings.json');
+  const tpl = JSON.parse(fs.readFileSync(tplPath, 'utf8'));
+
+  if (!fs.existsSync(dstPath)) {
+    fs.mkdirSync(path.dirname(dstPath), { recursive: true });
+    fs.copyFileSync(tplPath, dstPath);
+    log('  + .claude/settings.json (new)');
+    return;
+  }
+
+  let cur;
+  try { cur = JSON.parse(fs.readFileSync(dstPath, 'utf8')); } catch {
+    log('  ! .claude/settings.json failed to parse — skipping merge. Register the hooks manually.');
+    return;
+  }
+
+  let changed = false;
+  cur.hooks = cur.hooks || {};
+  for (const [event, entries] of Object.entries(tpl.hooks || {})) {
+    cur.hooks[event] = cur.hooks[event] || [];
+    for (const entry of entries) {
+      const cmd = entry.hooks && entry.hooks[0] && entry.hooks[0].command;
+      const present = JSON.stringify(cur.hooks[event]).includes(path.basename(cmd || ''));
+      if (!present) { cur.hooks[event].push(entry); changed = true; }
+    }
+  }
+
+  const missing = [];
+  if (tpl.permissions) {
+    if (!cur.permissions) {
+      cur.permissions = tpl.permissions;
+      changed = true;
+    } else {
+      for (const key of ['allow', 'ask', 'deny']) {
+        for (const rule of (tpl.permissions[key] || [])) {
+          if (!(cur.permissions[key] || []).includes(rule)) missing.push(`${key}: ${rule}`);
+        }
+      }
+    }
+  }
+
+  if (changed) {
+    fs.writeFileSync(dstPath, JSON.stringify(cur, null, 2) + '\n');
+    log('  ~ .claude/settings.json (hooks merged; existing settings preserved)');
+  }
+  if (missing.length) {
+    log('  ! settings.json permissions is missing kit-recommended entries (NOT added automatically):');
+    for (const m of missing) log(`      ${m}`);
+  }
+}
+
+// ── init ─────────────────────────────────────────────────────────
+function init(target, force) {
+  const files = machineryFiles();
+  const manifest = readManifest(target);
+  const skipped = [];
+
+  for (const rel of files) {
+    const dst = path.join(target, rel);
+    if (fs.existsSync(dst)) {
+      const dstHash = sha256(dst);
+      if (dstHash === sha256(path.join(PKG_ROOT, rel))) continue; // already identical
+      const recorded = manifest && manifest.files && manifest.files[rel];
+      if (!force && dstHash !== recorded) { skipped.push(rel); continue; }
+    }
+    copyInto(target, rel);
+    log('  + ' + rel);
+  }
+
+  let claudeMdExisted = false;
+  for (const rel of ['CLAUDE.md', '.harness/commands.env']) {
+    const dst = path.join(target, rel);
+    if (fs.existsSync(dst)) {
+      log('  = ' + rel + ' (existing file kept)');
+      if (rel === 'CLAUDE.md') claudeMdExisted = true;
+      continue;
+    }
+    copyInto(target, rel);
+    log('  + ' + rel);
+  }
+  mergeSettings(target);
+
+  fs.mkdirSync(path.join(target, '.harness/logs'), { recursive: true });
+  const gi = path.join(target, '.gitignore');
+  const giBody = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
+  if (!giBody.split('\n').some((l) => l.trim().replace(/\/$/, '') === '.harness/logs')) {
+    fs.writeFileSync(gi, giBody + (giBody && !giBody.endsWith('\n') ? '\n' : '') + '.harness/logs/\n');
+    log('  ~ .gitignore (+.harness/logs/)');
+  }
+
+  writeManifest(target, files);
+
+  if (skipped.length) {
+    log('\nSkipped files with local modifications (use --force to overwrite):');
+    for (const s of skipped) log('  ! ' + s);
+  }
+
+  const t = runHookTests(target);
+  if (t) log(t.ok ? '\nHook tests passed.' : '\nHook tests FAILED:\n' + t.out);
+  else log('\nbash not found — skipped hook tests.');
+
+  log('\nNext step: open Claude Code in the project and run /harness-init');
+  log('to fill in the BUILD/TEST/LINT commands — the verification sensors');
+  log('stay inactive until then.');
+  if (claudeMdExisted) {
+    log('Your existing CLAUDE.md was kept as-is. /harness-init will propose');
+    log('adding the harness sections (PROJECT / RULES / Work Loop /');
+    log('Checkpoints) to it — nothing is changed without your approval.');
+  }
+  return t && !t.ok ? 1 : 0;
+}
+
+// ── update ───────────────────────────────────────────────────────
+function update(target, force) {
+  const manifest = readManifest(target);
+  if (!manifest) {
+    log('No kit-manifest.json found. Run `uni-harness init` first.');
+    return 1;
+  }
+  const files = machineryFiles();
+  const skipped = [];
+  let changed = 0;
+
+  for (const rel of files) {
+    const src = path.join(PKG_ROOT, rel);
+    const dst = path.join(target, rel);
+    const recorded = manifest.files[rel];
+    if (!fs.existsSync(dst)) { copyInto(target, rel); log('  + ' + rel); changed++; continue; }
+    const dstHash = sha256(dst);
+    if (dstHash === sha256(src)) continue; // up to date
+    if (!force && recorded && dstHash !== recorded) { skipped.push(rel); continue; }
+    copyInto(target, rel);
+    log('  ~ ' + rel);
+    changed++;
+  }
+
+  // Files removed from the kit: clean up unmodified copies only
+  for (const rel of Object.keys(manifest.files)) {
+    if (files.includes(rel)) continue;
+    const dst = path.join(target, rel);
+    if (fs.existsSync(dst) && sha256(dst) === manifest.files[rel]) {
+      fs.unlinkSync(dst);
+      log('  - ' + rel + ' (removed from kit)');
+      changed++;
+    }
+  }
+
+  writeManifest(target, files);
+  log(`\n${changed} file(s) updated (v${manifest.kitVersion} -> v${KIT_VERSION}). ` +
+      'CLAUDE.md / commands.env / settings.json were not touched.');
+  if (skipped.length) {
+    log('Skipped files with local modifications (use --force to overwrite):');
+    for (const s of skipped) log('  ! ' + s);
+  }
+
+  const t = runHookTests(target);
+  if (t) log(t.ok ? 'Hook tests passed.' : 'Hook tests FAILED:\n' + t.out);
+  return t && !t.ok ? 1 : 0;
+}
+
+// ── doctor ───────────────────────────────────────────────────────
+function doctor(target) {
+  let hard = 0;
+  const check = (ok, name, hint) => {
+    log(`  ${ok ? 'ok  ' : 'FAIL'} ${name}${!ok && hint ? ' — ' + hint : ''}`);
+    if (!ok) hard++;
+  };
+  const warn = (name) => log(`  warn ${name}`);
+
+  const has = (cmd) => !spawnSync(cmd, ['--version'], { encoding: 'utf8' }).error;
+  check(has('bash'), 'bash');
+  check(has('python3'), 'python3', 'the hooks use python3 for JSON parsing');
+
+  const manifest = readManifest(target);
+  check(!!manifest, MANIFEST, 'run `uni-harness init` first');
+  if (manifest) log(`       kit version: ${manifest.kitVersion} (package: ${KIT_VERSION})`);
+
+  for (const rel of machineryFiles()) {
+    const p = path.join(target, rel);
+    if (!fs.existsSync(p)) { check(false, rel, 'missing — run `uni-harness update`'); continue; }
+    if (rel.endsWith('.sh')) {
+      try { fs.accessSync(p, fs.constants.X_OK); } catch { check(false, rel, 'not executable'); }
+    }
+  }
+
+  const sp = path.join(target, '.claude/settings.json');
+  try {
+    const body = fs.readFileSync(sp, 'utf8');
+    JSON.parse(body);
+    check(true, '.claude/settings.json parses');
+    for (const h of ['guard-pre-bash.sh', 'sensor-post-edit.sh', 'stop-gate.sh', 'observe-log.sh', 'session-start.sh']) {
+      if (!body.includes(h)) check(false, `hook registered: ${h}`, 'not in settings.json');
+    }
+  } catch { check(false, '.claude/settings.json', 'missing or failed to parse'); }
+
+  const envp = path.join(target, '.harness/commands.env');
+  if (fs.existsSync(envp)) {
+    const env = fs.readFileSync(envp, 'utf8');
+    if (/^(LINT_CMD|TEST_CMD)=".+"/m.test(env)) check(true, 'commands.env sensor commands');
+    else warn('commands.env is empty — sensors inactive. Run /harness-init in Claude Code');
+  } else check(false, '.harness/commands.env', 'missing');
+
+  const cm = path.join(target, 'CLAUDE.md');
+  if (fs.existsSync(cm) && fs.readFileSync(cm, 'utf8').includes('[project name]')) {
+    warn('CLAUDE.md PROJECT section is still a placeholder — run /harness-init');
+  }
+
+  const t = runHookTests(target);
+  if (t) check(t.ok, 'hook tests (harness/tests/test_hooks.sh)');
+
+  log(hard === 0 ? '\nDiagnosis passed.' : `\n${hard} failure(s).`);
+  return hard === 0 ? 0 : 1;
+}
+
+// ── uninstall ────────────────────────────────────────────────────
+function uninstall(target, yes) {
+  const manifest = readManifest(target);
+  if (!manifest) { log('No kit-manifest.json — nothing installed here.'); return 1; }
+  if (!yes) { log('This removes the machinery files. Add --yes to confirm.'); return 1; }
+
+  for (const [rel, hash] of Object.entries(manifest.files)) {
+    const p = path.join(target, rel);
+    if (!fs.existsSync(p)) continue;
+    if (sha256(p) === hash) { fs.unlinkSync(p); log('  - ' + rel); }
+    else log('  ! ' + rel + ' (locally modified — kept)');
+  }
+  fs.unlinkSync(path.join(target, MANIFEST));
+  for (const d of ['.claude/hooks', '.claude/skills', '.claude/agents', 'harness/tests', 'harness']) {
+    try { fs.rmdirSync(path.join(target, d)); } catch { /* keep if not empty */ }
+  }
+  log('Uninstalled. CLAUDE.md / commands.env / settings.json / logs were kept.');
+  log('Remove the hook registrations from settings.json manually (missing');
+  log('hook files are ignored silently, but the entries are now dead).');
+  return 0;
+}
+
+// ── main ─────────────────────────────────────────────────────────
+function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+  const flags = new Set(args.filter((a) => a.startsWith('--')));
+  const dirArg = args.slice(1).find((a) => !a.startsWith('--'));
+  const target = path.resolve(dirArg || process.cwd());
+
+  if (!cmd || flags.has('--help')) {
+    log('Usage: uni-harness <init|update|doctor|uninstall> [dir] [--force|--yes]');
+    return 0;
+  }
+  if (path.resolve(target) === PKG_ROOT) {
+    log('Refusing to install into the kit repository itself. Pass a target project path.');
+    return 1;
+  }
+  if (!fs.existsSync(target)) { log(`Target path does not exist: ${target}`); return 1; }
+
+  switch (cmd) {
+    case 'init': return init(target, flags.has('--force'));
+    case 'update': return update(target, flags.has('--force'));
+    case 'doctor': return doctor(target);
+    case 'uninstall': return uninstall(target, flags.has('--yes'));
+    default: log(`Unknown command: ${cmd}`); return 1;
+  }
+}
+
+process.exit(main());

package/harness/harness_report.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Harness health scorecard.
+
+Reads .harness/logs/tool_calls.jsonl and prints health metrics.
+
+Usage:
+    python3 harness/harness_report.py [--days 7]
+"""
+import argparse
+import datetime as dt
+import json
+import sys
+from collections import Counter, defaultdict
+from pathlib import Path
+
+
+def load(log_path: Path, since: dt.datetime):
+    rows = []
+    if not log_path.exists():
+        return rows
+    with log_path.open() as f:
+        for line in f:
+            try:
+                e = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            try:
+                ts = dt.datetime.fromisoformat(e.get("ts", ""))
+            except ValueError:
+                continue
+            if ts >= since:
+                e["_ts"] = ts
+                rows.append(e)
+    return rows
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--days", type=int, default=7)
+    args = ap.parse_args()
+
+    root = Path(__file__).resolve().parent.parent
+    log_path = root / ".harness" / "logs" / "tool_calls.jsonl"
+    since = dt.datetime.now() - dt.timedelta(days=args.days)
+    rows = load(log_path, since)
+
+    print(f"═══ Harness Health Scorecard (last {args.days} days) ═══")
+    if not rows:
+        print("No logs found. Check that the hooks are registered and a session has run.")
+        return 0
+
+    sessions = defaultdict(list)
+    for e in rows:
+        sessions[e.get("session_id", "?")].append(e)
+
+    total = len(rows)
+    failures = [e for e in rows if e.get("event") == "PostToolUseFailure"]
+    fail_rate = len(failures) / total * 100 if total else 0.0
+
+    print(f"Sessions:               {len(sessions)}")
+    print(f"Tool calls:             {total}")
+    print(f"Tool failures:          {len(failures)} ({fail_rate:.1f}%)")
+
+    per_session = sorted(len(v) for v in sessions.values())
+    mid = per_session[len(per_session) // 2]
+    print(f"Calls/session (median): {mid}  (max {per_session[-1]})")
+
+    print("\n─ Top tools by usage ─")
+    for tool, n in Counter(e.get("tool", "?") for e in rows).most_common(8):
+        f = sum(1 for e in failures if e.get("tool") == tool)
+        mark = f"  (failures {f})" if f else ""
+        print(f"  {tool:<28}{n:>5}{mark}")
+
+    if failures:
+        print("\n─ Top repeated failure signatures (ratchet candidates) ─")
+        sigs = Counter((e.get("tool", "?"), (e.get("error") or "")[:70]) for e in failures)
+        for (tool, err), n in sigs.most_common(5):
+            if n >= 2:
+                print(f"  [{n}x] {tool}: {err}")
+        print("\n  -> For failures repeated 2+ times, consider /ratchet to turn them into rules.")
+
+    print("\n─ How to read this ─")
+    print("  · Is the failure rate trending down week over week?")
+    print("  · The same failure signature next week means the ratchet isn't working")
+    print("  · The growth rate of CLAUDE.md rules should be declining (a maturity signal)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/harness/tests/test_hooks.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# ════════════════════════════════════════════════════════════════
+# Harness hook self-tests
+# Run: bash harness/tests/test_hooks.sh
+# Feeds sample JSON into each hook and asserts the expected behavior
+# (block / inject / silence). "Pass silently when unconfigured" is
+# part of the hook contract, so that path is tested too.
+# ════════════════════════════════════════════════════════════════
+set -u
+
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+HOOKS="$ROOT/.claude/hooks"
+PASS=0
+FAIL=0
+
+# check <name> <expected substring|EMPTY> <actual output>
+check() {
+  local name="$1" expect="$2" actual="$3"
+  if [ "$expect" = "EMPTY" ]; then
+    if [ -z "$actual" ]; then PASS=$((PASS+1)); echo "  ok: $name"
+    else FAIL=$((FAIL+1)); echo "  FAIL: $name — expected no output, got: ${actual:0:120}"; fi
+  else
+    if printf '%s' "$actual" | grep -qF "$expect"; then PASS=$((PASS+1)); echo "  ok: $name"
+    else FAIL=$((FAIL+1)); echo "  FAIL: $name — missing '$expect': ${actual:0:160}"; fi
+  fi
+}
+
+fresh_project() {
+  TMP=$(mktemp -d)
+  export CLAUDE_PROJECT_DIR="$TMP"
+  mkdir -p "$TMP/.harness/logs"
+}
+
+# ── guard-pre-bash.sh ────────────────────────────────────────────
+echo "guard-pre-bash.sh"
+fresh_project
+OUT=$(echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' | bash "$HOOKS/guard-pre-bash.sh")
+check "blocks recursive root delete" '"permissionDecision": "deny"' "$OUT"
+OUT=$(echo '{"tool_name":"Bash","tool_input":{"command":"git commit -m x --no-verify"}}' | bash "$HOOKS/guard-pre-bash.sh")
+check "blocks --no-verify" "no-verify" "$OUT"
+OUT=$(echo '{"tool_name":"Bash","tool_input":{"command":"git push --force origin main"}}' | bash "$HOOKS/guard-pre-bash.sh")
+check "blocks force push" '"permissionDecision": "deny"' "$OUT"
+OUT=$(echo '{"tool_name":"Bash","tool_input":{"command":"git push --force-with-lease origin main"}}' | bash "$HOOKS/guard-pre-bash.sh")
+check "allows force-with-lease" "EMPTY" "$OUT"
+OUT=$(echo '{"tool_name":"Bash","tool_input":{"command":"git status"}}' | bash "$HOOKS/guard-pre-bash.sh")
+check "passes safe commands" "EMPTY" "$OUT"
+
+# ── observe-log.sh ───────────────────────────────────────────────
+echo "observe-log.sh"
+fresh_project
+echo '{"hook_event_name":"PostToolUse","session_id":"s1","tool_name":"Bash","tool_input":{"command":"ls"}}' | bash "$HOOKS/observe-log.sh" > /dev/null
+LINES=$(wc -l < "$TMP/.harness/logs/tool_calls.jsonl" | tr -d ' ')
+check "logs one call" "1" "$LINES"
+echo '{"hook_event_name":"PostToolUse","session_id":"s1","tool_name":"Edit","tool_input":{"file_path":"a.py"},"agent_id":"x1","agent_type":"code-reviewer"}' | bash "$HOOKS/observe-log.sh" > /dev/null
+check "records subagent fields" "code-reviewer" "$(tail -1 "$TMP/.harness/logs/tool_calls.jsonl")"
+OUT=""
+for _ in 1 2 3; do
+  OUT=$(echo '{"hook_event_name":"PostToolUseFailure","session_id":"s1","tool_name":"Bash","tool_input":{"command":"pytest"},"tool_response":"E: same error"}' | bash "$HOOKS/observe-log.sh")
+done
+check "tripwire on 3 identical failures" "The same tool failed" "$OUT"
+
+# ── sensor-post-edit.sh ──────────────────────────────────────────
+echo "sensor-post-edit.sh"
+fresh_project
+OUT=$(echo '{"session_id":"s1","tool_input":{"file_path":"a.py"}}' | bash "$HOOKS/sensor-post-edit.sh")
+check "silent without commands.env" "EMPTY" "$OUT"
+printf 'LINT_CMD="false"\nTEST_CMD=""\n' > "$TMP/.harness/commands.env"
+OUT=$(echo '{"session_id":"s1","tool_input":{"file_path":"README.md"}}' | bash "$HOOKS/sensor-post-edit.sh")
+check "passes doc files" "EMPTY" "$OUT"
+OUT=$(echo '{"session_id":"s1","tool_input":{"file_path":"a.py"}}' | bash "$HOOKS/sensor-post-edit.sh")
+check "feeds back lint failure" "LINT FAILED" "$OUT"
+check "records pending_test marker" "a.py" "$(cat "$TMP/.harness/logs/pending_test.s1" 2>/dev/null)"
+printf 'LINT_CMD="true"\nTEST_CMD=""\n' > "$TMP/.harness/commands.env"
+OUT=$(echo '{"session_id":"s1","tool_input":{"file_path":"a.py"}}' | bash "$HOOKS/sensor-post-edit.sh")
+check "silent when lint passes" "EMPTY" "$OUT"
+
+# ── stop-gate.sh ─────────────────────────────────────────────────
+echo "stop-gate.sh"
+fresh_project
+printf 'LINT_CMD=""\nTEST_CMD="false"\n' > "$TMP/.harness/commands.env"
+OUT=$(echo '{"session_id":"s1"}' | bash "$HOOKS/stop-gate.sh")
+check "passes sessions with no edits" "EMPTY" "$OUT"
+echo "a.py" > "$TMP/.harness/logs/pending_test.s1"
+OUT=$(echo '{"session_id":"s1"}' | bash "$HOOKS/stop-gate.sh")
+check "blocks stop on failing tests" '"decision": "block"' "$OUT"
+check "shows block count" "1/3" "$OUT"
+OUT=$(echo '{"session_id":"s1"}' | bash "$HOOKS/stop-gate.sh")
+check "second block" "2/3" "$OUT"
+OUT=$(echo '{"session_id":"s1"}' | bash "$HOOKS/stop-gate.sh")
+check "third block demands escalation" "escalation packet" "$OUT"
+OUT=$(echo '{"session_id":"s1"}' | bash "$HOOKS/stop-gate.sh")
+check "passes after cap clears marker" "EMPTY" "$OUT"
+echo "a.py" > "$TMP/.harness/logs/pending_test.s1"
+printf 'LINT_CMD=""\nTEST_CMD="true"\n' > "$TMP/.harness/commands.env"
+OUT=$(echo '{"session_id":"s1"}' | bash "$HOOKS/stop-gate.sh")
+check "silent when tests pass" "EMPTY" "$OUT"
+[ -f "$TMP/.harness/logs/pending_test.s1" ] && MARKER_LEFT="yes" || MARKER_LEFT=""
+check "clears marker on pass" "EMPTY" "$MARKER_LEFT"
+
+# ── session-start.sh ─────────────────────────────────────────────
+echo "session-start.sh"
+fresh_project
+OUT=$(bash "$HOOKS/session-start.sh")
+check "silent without checkpoint" "EMPTY" "$OUT"
+echo '{"task_id":"t1","status":"in_progress","next_step":"do X"}' > "$TMP/progress.json"
+OUT=$(bash "$HOOKS/session-start.sh")
+check "injects in-progress checkpoint" "progress.json" "$OUT"
+echo '{"task_id":"t1","status":"completed"}' > "$TMP/progress.json"
+OUT=$(bash "$HOOKS/session-start.sh")
+check "skips completed checkpoint" "EMPTY" "$OUT"
+rm "$TMP/progress.json"
+NOW=$(python3 -c 'import datetime; print(datetime.datetime.now().isoformat(timespec="seconds"))')
+for _ in 1 2 3; do
+  echo "{\"ts\":\"$NOW\",\"session_id\":\"old\",\"event\":\"PostToolUseFailure\",\"tool\":\"Bash\",\"error\":\"x\"}" >> "$TMP/.harness/logs/tool_calls.jsonl"
+done
+OUT=$(bash "$HOOKS/session-start.sh")
+check "nudges /ratchet on accumulated failures" "/ratchet" "$OUT"
+fresh_project
+printf 'LINT_CMD=""\nTEST_CMD=""\n' > "$TMP/.harness/commands.env"
+OUT=$(bash "$HOOKS/session-start.sh")
+check "offers /harness-init when unconfigured" "/harness-init" "$OUT"
+printf 'LINT_CMD="true"\nTEST_CMD=""\n' > "$TMP/.harness/commands.env"
+OUT=$(bash "$HOOKS/session-start.sh")
+check "no setup nudge once configured" "EMPTY" "$OUT"
+
+# ── result ───────────────────────────────────────────────────────
+echo
+echo "passed: $PASS, failed: $FAIL"
+[ "$FAIL" -eq 0 ] || exit 1