loop-engineering 1.0.0

package/skill/reference/ide-natives.md

@@ -0,0 +1,14 @@
+# IDE-native loop primitives
+
+Use this once a spec passes `verify` — to decide whether to run the loop via this skill's `run` command, or hand off to the IDE's own native autonomous-loop mechanism, if it has one.
+
+| Tool | Native loop primitive | Notes |
+|---|---|---|
+| **Codex CLI / IDE ext** | `/goal` (enable via `features.goals` in config.toml if not listed) | Paste this spec's Goal + Verification straight in. Codex treats goal text as both prompt and completion criteria, with its own progress UI (pause/resume/edit). If available, prefer it over this skill's `run` — it's native and has better UI for it. |
+| **Claude Code** | No single built-in `/goal`. This skill's `run` command (backed by `<skill-dir>/scripts/run_loop.mjs`) is the recommended mechanism — it persists state across turns the way a bare conversation loop can't. | Keep `LOOP_SPEC.md` and `.loop/state.json` in the repo; reference the spec each turn rather than re-describing the goal. |
+| **Cursor** | No first-class autonomous-until-done primitive as of mid-2026. Multi-task agent runs exist but aren't goal-gated. | Use `/loop` (the Cursor command in `integrations/cursor/`) to author/harden the spec; run iterations by re-invoking manually or scripting `run_loop.mjs` externally. |
+| **Windsurf (Cascade)** | Workflows (`.windsurf/workflows/*.md`, `/workflow-name`) run once per invocation, not autonomously until a goal is met. | Chain workflow steps and use this spec's Verification command as the explicit gate between them. |
+| **Antigravity** | Skill-triggered, single-shot per invocation like Windsurf, as of mid-2026. | Same approach — the spec governs each invocation; verify current docs before assuming an autonomous mode exists. |
+| **Generic / scripted (any CLI agent)** | Plain wrapper: call the agent CLI non-interactively, then `run_loop.mjs check`, branch on `status`, repeat. | Most portable. Works with any CLI-capable agent regardless of native support. |
+
+This table reflects mid-2026 product behavior and changes fast. If a native `/goal`-style mode exists and works well, prefer it — this skill's job is producing the spec either way, not insisting on its own runner.

package/skill/reference/init.md

@@ -0,0 +1,51 @@
+# /loop init — Capture project conventions into LOOP_CONTEXT.md
+
+Interviews the user for standing project conventions and writes them to `LOOP_CONTEXT.md`. Future `/loop new` and `/loop harden` invocations read this file so they don't re-ask for things that never change (test command, build command, forbidden paths).
+
+## When to use
+
+- First time using `/loop` in a project that has an established test/build setup.
+- After significant project restructuring (changed test runner, new forbidden paths, etc.).
+- When the user says "remember that we always use X" or "never touch Y."
+
+## Flow
+
+1. **Check for existing file.** If `LOOP_CONTEXT.md` already exists, read it and ask: "I found an existing LOOP_CONTEXT.md. Do you want to update it or start fresh?" If updating, show the current values and let the user amend only what changed.
+
+2. **Interview.** Ask the following, one at a time. Accept "none" or "skip" for any item.
+
+   - **Test command**: "What command runs your test suite?" (e.g. `npm test`, `pytest`, `go test ./...`)
+   - **Build command**: "What command builds the project, if any?" (e.g. `npm run build`, `make`, "none")
+   - **Lint/format command**: "What command runs lint or formatting?" (e.g. `npm run lint`, `ruff check .`, "none")
+   - **Forbidden always**: "Are there files, directories, or actions that loop specs in this project should never touch? List them." (e.g. `migrations/`, force-push, editing test files to make them pass)
+   - **Other standing notes**: "Anything else a loop spec author should know about this project by default?" (optional — the user can skip)
+
+3. **Write `LOOP_CONTEXT.md`** with this structure:
+
+```markdown
+# Loop Context
+
+Project conventions for loop spec authoring. Generated by `/loop init`.
+Update by running `/loop init` again.
+
+## Commands
+- **Test**: `<test command or "none">`
+- **Build**: `<build command or "none">`
+- **Lint**: `<lint command or "none">`
+
+## Forbidden always
+<bullet list of forbidden paths/actions, or "none specified">
+
+## Notes
+<standing notes, or omit section if none>
+```
+
+4. **Confirm before writing.** Show the user the draft and ask "Write this to LOOP_CONTEXT.md?" before creating or overwriting the file.
+
+5. **Remind how it's used.** After writing, say: "When you run `/loop new` or `/loop harden`, I'll read LOOP_CONTEXT.md and pre-fill the test/build commands and forbidden actions — you won't need to re-state them each time."
+
+## How downstream commands use LOOP_CONTEXT.md
+
+- `/loop new`: If `LOOP_CONTEXT.md` exists, pre-fill the Verification section with the test command and the Scope's Forbidden list with the standing forbidden actions. Still ask the user to confirm or override them for this specific spec.
+- `/loop harden`: Same — use the standing commands as defaults when proposing fixes to a weak spec.
+- The file is never required. If it doesn't exist, the downstream commands ask for this information as usual.

package/skill/reference/new.md

@@ -0,0 +1,55 @@
+# `new` — author a fresh loop spec
+
+Triggered by: `/loop new <goal description>`, or any goal description with no existing `LOOP_SPEC.md` in the working directory.
+
+## Flow
+
+1. **Read what's given.** If the user's goal description already implies an answer for one of the 5 components, don't ask about it again — extract it.
+
+2. **Interview for the 2 components that are usually actually missing** — Goal precision and Verification. Don't interrogate all 5 one by one; most users can state scope/escalation defaults fine once asked once, but goal vagueness and verification are where real gaps live.
+
+   - If the goal is a vague adjective ("better," "cleaner," "more polished," "looks good"): ask what observable, checkable thing would prove it's done. Push past the first vague answer if needed — "looks good" → "what would make it look good?" → "consistent spacing" → "is there a lint rule or visual diff that catches inconsistent spacing, or do we need a human eyeball each time?"
+   - If no verification method is stated: ask what command (test, build, lint, type-check) would return pass/fail. If genuinely nothing mechanical exists, say so and propose an LLM-judge rubric explicitly, flagged as the weakest link — never silently assume one exists.
+
+3. **Default the other 3 unless the user has opinions:**
+   - Termination: max iterations default 8–10 for a build task, lower (3–5) for anything touching production data or external services. No-progress default: 2 consecutive identical results. State these defaults explicitly so the user can override, don't just silently pick them.
+   - Scope: ask "anything definitely off-limits?" if not stated — at minimum forbid editing test files to force a pass.
+   - Escalation: default to "stop, summarize attempts, wait for human" unless the user wants something else (e.g. auto-revert on cap).
+
+4. **Write `LOOP_SPEC.md`** in the working directory using this exact shape:
+
+```markdown
+# Loop: <short name>
+
+## Goal
+<concrete, observable end state — not an adjective>
+
+## Verification
+```
+<exact command, e.g. npm run test && npm run build>
+```
+(or, if no deterministic check exists: state the LLM-judge rubric explicitly here, and say so)
+
+## Termination
+- Success: verification exits 0
+- Max iterations: <N>
+- No-progress: stop if 2 consecutive iterations produce identical result + unchanged working tree
+- Budget: <optional>
+
+## Scope
+- Allowed: <paths/stack>
+- Forbidden: <at least one explicit thing>
+
+## Escalation
+On cap or no-progress: stop, summarize attempts + last error, wait for human review.
+```
+
+5. **Run the linter immediately after writing the file.** Do not skip this because you just wrote it carefully:
+
+```bash
+node <skill-dir>/scripts/lint_spec.mjs LOOP_SPEC.md
+```
+
+If it fails, fix exactly what it reports and re-run — do not guess at what else might be wrong.
+
+6. Once it passes, tell the user the spec is ready and ask whether they want to `run` it now, hand it to their IDE's native loop primitive (see `reference/ide-natives.md`), or just keep the spec for later.

package/skill/reference/run.md

@@ -0,0 +1,44 @@
+# `run` — execute the loop end-to-end
+
+Triggered by: `/loop run [path]`, "start the loop," "iterate until this passes."
+
+## Precondition
+
+**Never run a spec that hasn't passed the linter.** Run `node <skill-dir>/scripts/lint_spec.mjs <path>` first if it hasn't been checked in this conversation already. If it fails, stop and go to `reference/harden.md` — do not run a loop against an incomplete spec; the no-progress and cap logic only mean something if Goal/Verification/Termination are real.
+
+## The loop
+
+This is the actual cycle. The script (`run_loop.mjs`) only runs the verifier and tracks state — it does not write code. That's the agent's job, every iteration, between script calls:
+
+1. **Check current state** (skip on the very first iteration of a fresh run):
+   ```bash
+   node <skill-dir>/scripts/run_loop.mjs check LOOP_SPEC.md
+   ```
+   Read the JSON output's `status` field. Three possible values:
+   - `"success"` → stop. Report success to the user with the iteration count. Done.
+   - `"continue"` → an attempt was made and failed, but under cap and making progress. Proceed to step 2.
+   - `"stop-escalate"` → stop immediately. Do not run the verifier again, do not make another edit "just to see." Report the `reason` field to the user verbatim, along with the iteration history (`node <skill-dir>/scripts/run_loop.mjs status LOOP_SPEC.md`), and wait for human input per the spec's Escalation section.
+
+2. **If `continue` (or this is iteration 1): make a real change.** Read the spec's Goal and the last failure's `stderr` (included in the JSON). Make a genuine attempt to close the gap — actually edit files, don't just re-run the check hoping for a different result. This is the step the script cannot do for you.
+
+3. **Loop back to step 1.** Re-run `check`. The script re-evaluates from the new state.
+
+## Critical: don't fight the script's verdict
+
+If `run_loop.mjs` reports `stop-escalate` for no-progress, that means the verifier output AND the working tree were identical to the previous attempt — i.e., either nothing was actually changed, or a change was made and then reverted to the same state. Do not:
+- Re-run the check again manually outside the loop hoping it now reads differently — it won't, the inputs haven't changed.
+- Argue that "this time it'll work" and bypass the script by running the verification command directly instead of through `run_loop.mjs check` — that's circumventing the cap, not satisfying it.
+
+If you genuinely believe the no-progress detection is wrong (e.g. the change was real but doesn't show in git status because it touched a file outside the repo), say so to the user explicitly and let them decide whether to `reset` and continue — don't silently route around the script.
+
+## Reporting
+
+After every iteration, give the user a one-line status: iteration N/cap, pass/fail, what changed. Don't go silent for multiple iterations and then dump a wall of history — that's how a stuck loop goes unnoticed.
+
+## On success
+
+Report the final iteration count and what changed across the run. Don't immediately suggest more changes unless asked — the loop's job was to hit the stated goal, not to keep improving indefinitely.
+
+## On escalation
+
+Don't soften it. State plainly: cap reached / no-progress detected, here's the last error, here's what was tried, your call on next steps. Offer concrete next steps (raise the cap and retry, change the verification method, manually intervene) rather than just reporting failure and stopping.

package/skill/reference/status.md

@@ -0,0 +1,15 @@
+# `status` — report iteration history, read-only
+
+Triggered by: `/loop status [path]`, "how's the loop going," "what happened last run."
+
+## Flow
+
+```bash
+node <skill-dir>/scripts/run_loop.mjs status <path, default LOOP_SPEC.md>
+```
+
+Report:
+- `"no-history"` → no run has happened yet for this spec. Suggest `run` if they want to start one.
+- Otherwise → completed iterations vs max, and a short read of the history: did it trend toward passing, or stall? Look at consecutive hashes in `history` — if the last two `hash` values match, the loop is (or was) one `check` away from no-progress escalation.
+
+This command never executes the verifier or modifies state — it only reads `.loop/state.json`. If the user wants to clear history and start fresh, that's `node <skill-dir>/scripts/run_loop.mjs reset <path>`, not part of `status` — confirm with them before running `reset`, since it discards the record of what was already tried.

package/skill/reference/verify.md

@@ -0,0 +1,23 @@
+# `verify` — lint-only check, no execution
+
+Triggered by: `/loop verify [path]`, "is this spec ready?", "check my loop spec."
+
+## Flow
+
+1. Run:
+
+```bash
+node <skill-dir>/scripts/lint_spec.mjs <path, default LOOP_SPEC.md>
+```
+
+2. Report the result verbatim-ish to the user:
+   - **Exit 0**: spec is loop-ready. Tell the user plainly, and ask if they want to `run` it now.
+   - **Exit 1**: relay the itemized issue list exactly as the script reported it — don't summarize it into something vaguer. If the user wants it fixed now, switch to `reference/harden.md`; if they just wanted the check, stop here.
+
+## What this command does NOT do
+
+- Does not execute the verification command from the spec (that's `run`).
+- Does not modify the spec file (that's `harden`).
+- Does not touch `.loop/state.json`.
+
+This is a read-only check. If the user wanted execution, they'll say so — don't assume `verify` implies `run`.

package/skill/scripts/lint_spec.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// lint_spec.mjs — validates a LOOP_SPEC.md against the 5 required loop-engineering components.
+// Exit 0 = spec is loop-ready. Exit 1 = spec is missing or incomplete, with specific errors.
+//
+// Usage: node lint_spec.mjs [path/to/LOOP_SPEC.md]
+// Default path: ./LOOP_SPEC.md
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+const target = resolve(process.argv[2] || "LOOP_SPEC.md");
+
+const REQUIRED_SECTIONS = [
+  { key: "Goal", header: /^##\s+Goal\s*$/m },
+  { key: "Verification", header: /^##\s+Verification\s*$/m },
+  { key: "Termination", header: /^##\s+Termination\s*$/m },
+  { key: "Scope", header: /^##\s+Scope\s*$/m },
+  { key: "Escalation", header: /^##\s+Escalation\s*$/m },
+];
+
+// Phrases that indicate the section is a template placeholder, not real content.
+// These match only when the ENTIRE trimmed section is the placeholder — a substring match
+// would false-positive on legitimate commands containing <args>, e.g. `playwright test <file>`.
+const PLACEHOLDER_WHOLE_SECTION_PATTERNS = [
+  /^\.\.\.$/,
+  /^<[^>]{2,80}>$/, // section is nothing but a single unfilled template slot like "<concrete, observable end state>"
+  /^TBD$/i,
+  /^TODO$/i,
+  /^N\/A$/i,
+];
+
+function isPlaceholder(text) {
+  if (!text || text.length === 0) return true;
+  const trimmed = text.trim();
+  return PLACEHOLDER_WHOLE_SECTION_PATTERNS.some((p) => p.test(trimmed));
+}
+
+function extractSection(content, key) {
+  // Grab everything between "## Key" and the next "## " heading or end of file.
+  // Anchored on "\n##" (not "^##" with the m flag) to avoid $ matching end-of-line
+  // instead of end-of-string, which previously truncated every multi-line section
+  // at its first line break.
+  const re = new RegExp(`(?:^|\\n)##\\s+${key}\\s*\\n([\\s\\S]*?)(?=\\n##\\s+|$)`);
+  const m = content.match(re);
+  return m ? m[1].trim() : null;
+}
+
+function checkVerification(text) {
+  // Verification section needs either a runnable-looking command (backticks / code fence)
+  // or an explicit acknowledgement that it's LLM-judge based (flagged as weakest link).
+  const hasCodeFence = /```[\s\S]*?```/.test(text) || /`[^`]+`/.test(text);
+  const flagsLLMJudge = /llm[\s-]?judge|llm[\s-]?as[\s-]?judge|rubric/i.test(text);
+  if (!hasCodeFence && !flagsLLMJudge) {
+    return "Verification section has no command (in backticks/code fence) and does not explicitly name an LLM-judge rubric as fallback. A verifier must be either a runnable check or an explicitly-flagged LLM-judge.";
+  }
+  return null;
+}
+
+function checkTermination(text) {
+  const hasSuccess = /success/i.test(text);
+  const hasMaxIter = /max\s+iterations?|iteration\s+cap/i.test(text);
+  const hasNoProgress = /no-?progress/i.test(text);
+  const missing = [];
+  if (!hasSuccess) missing.push("success condition");
+  if (!hasMaxIter) missing.push("max iterations / iteration cap");
+  if (!hasNoProgress) missing.push("no-progress exit");
+  if (missing.length > 0) {
+    return `Termination section is missing: ${missing.join(", ")}. All three are required — a loop without a no-progress exit can burn its entire budget repeating the same failure.`;
+  }
+  return null;
+}
+
+function checkScope(text) {
+  const hasForbidden = /forbidden|not\s+allowed|never|do\s+not/i.test(text);
+  if (!hasForbidden) {
+    return "Scope section names no forbidden actions. Every loop spec must explicitly forbid at least one destructive shortcut (e.g. editing tests to force a pass, touching migrations, force-pushing).";
+  }
+  return null;
+}
+
+function checkEscalation(text) {
+  const hasStop = /stop|halt|wait|escalat|human|review/i.test(text);
+  if (!hasStop) {
+    return "Escalation section does not describe what happens when the cap is hit. Must explicitly state the loop stops and waits for a human rather than retrying indefinitely.";
+  }
+  return null;
+}
+
+function main() {
+  if (!existsSync(target)) {
+    console.error(`FAIL: ${target} not found.`);
+    console.error("No loop spec exists yet. Run the 'new' command to author one before verifying or running a loop.");
+    process.exit(1);
+  }
+
+  const content = readFileSync(target, "utf-8");
+  const errors = [];
+  const sections = {};
+
+  for (const { key, header } of REQUIRED_SECTIONS) {
+    if (!header.test(content)) {
+      errors.push(`Missing required section: "## ${key}"`);
+      continue;
+    }
+    const text = extractSection(content, key);
+    sections[key] = text;
+    if (isPlaceholder(text)) {
+      errors.push(`Section "## ${key}" is empty or still contains placeholder/template text: ${JSON.stringify((text || "").slice(0, 80))}`);
+    }
+  }
+
+  // Section-specific deep checks only run if the section exists and isn't a placeholder.
+  if (sections.Verification && !isPlaceholder(sections.Verification)) {
+    const err = checkVerification(sections.Verification);
+    if (err) errors.push(`[Verification] ${err}`);
+  }
+  if (sections.Termination && !isPlaceholder(sections.Termination)) {
+    const err = checkTermination(sections.Termination);
+    if (err) errors.push(`[Termination] ${err}`);
+  }
+  if (sections.Scope && !isPlaceholder(sections.Scope)) {
+    const err = checkScope(sections.Scope);
+    if (err) errors.push(`[Scope] ${err}`);
+  }
+  if (sections.Escalation && !isPlaceholder(sections.Escalation)) {
+    const err = checkEscalation(sections.Escalation);
+    if (err) errors.push(`[Escalation] ${err}`);
+  }
+
+  if (errors.length > 0) {
+    console.error(`FAIL: ${target} is not loop-ready (${errors.length} issue${errors.length > 1 ? "s" : ""}):`);
+    for (const e of errors) console.error(`  - ${e}`);
+    process.exit(1);
+  }
+
+  console.log(`PASS: ${target} is loop-ready. All 5 sections present and substantive.`);
+  process.exit(0);
+}
+
+main();

package/skill/scripts/run_loop.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+// run_loop.mjs — runs one iteration of a loop spec's verification command, updates state,
+// and reports whether the loop should continue, stop-success, or stop-escalate.
+//
+// This script enforces caps itself rather than trusting the calling agent to count correctly.
+// It does NOT make code changes — that's the agent's job between iterations. This script's
+// only responsibilities: run the verifier, hash the result, compare to history, decide status.
+//
+// Usage:
+//   node run_loop.mjs check [path/to/LOOP_SPEC.md]   — run one verification pass, report status
+//   node run_loop.mjs reset [path/to/LOOP_SPEC.md]   — clear iteration history for a fresh run
+//   node run_loop.mjs status [path/to/LOOP_SPEC.md]  — print current state without running anything
+//
+// State file: .loop/state.json (relative to cwd), one entry per spec path.
+
+import { readFileSync, readdirSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { execSync } from "node:child_process";
+import { createHash } from "node:crypto";
+
+const STATE_DIR = resolve(".loop");
+const STATE_FILE = resolve(STATE_DIR, "state.json");
+
+const DEFAULT_MAX_ITERATIONS = 10;
+const DEFAULT_NO_PROGRESS_LIMIT = 2; // consecutive identical results before stopping
+
+function loadState() {
+  if (!existsSync(STATE_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(STATE_FILE, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+function saveState(state) {
+  if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true });
+  writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
+}
+
+function extractVerificationCommand(specContent) {
+  const re = /(?:^|\n)##\s+Verification\s*\n([\s\S]*?)(?=\n##\s+|$)/;
+  const m = specContent.match(re);
+  if (!m) return null;
+  const fenceMatch = m[1].match(/```(?:[a-z]*\n)?([\s\S]*?)```/);
+  if (fenceMatch) return fenceMatch[1].trim();
+  const inlineMatch = m[1].match(/`([^`]+)`/);
+  if (inlineMatch) return inlineMatch[1].trim();
+  return null;
+}
+
+function extractMaxIterations(specContent) {
+  const re = /(?:^|\n)##\s+Termination\s*\n([\s\S]*?)(?=\n##\s+|$)/;
+  const m = specContent.match(re);
+  if (!m) return DEFAULT_MAX_ITERATIONS;
+  const numMatch = m[1].match(/max\s+iterations?\s*:?\s*(\d+)/i);
+  return numMatch ? parseInt(numMatch[1], 10) : DEFAULT_MAX_ITERATIONS;
+}
+
+function hashResult(stdout, stderr, exitCode) {
+  return createHash("sha256").update(`${exitCode}:${stdout}:${stderr}`).digest("hex").slice(0, 16);
+}
+
+function hashWorkingTree() {
+  // Prefer git: a diff of tracked+untracked changes against HEAD. Falls back to a
+  // content hash of the cwd if not in a git repo. This exists because many verification
+  // commands (assert/test-style) print identical generic failure text regardless of *why*
+  // they failed — without this, two genuinely different failed attempts would hash identically
+  // and falsely trigger no-progress.
+  try {
+    const diff = execSync("git diff HEAD --stat && git status --porcelain", {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (diff && diff.trim().length > 0) {
+      return createHash("sha256").update(diff).digest("hex").slice(0, 16);
+    }
+    // Empty diff in a real git repo is meaningful (truly unchanged) — keep it, don't fall through.
+    return createHash("sha256").update("git-clean").digest("hex").slice(0, 16);
+  } catch {
+    // Not a git repo (or git unavailable) — walk the directory tree with Node.js fs APIs.
+    // Cross-platform; no shell commands needed. Skips .git, node_modules, .loop (state files).
+    try {
+      const hash = createHash("sha256");
+      const SKIP = new Set([".git", "node_modules", ".loop"]);
+      function walk(dir) {
+        let entries;
+        try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const e of entries) {
+          if (SKIP.has(e.name)) continue;
+          const full = join(dir, e.name);
+          if (e.isDirectory()) walk(full);
+          else { try { hash.update(e.name + ":"); hash.update(readFileSync(full)); } catch {} }
+        }
+      }
+      walk(process.cwd());
+      return hash.digest("hex").slice(0, 16);
+    } catch {
+      return "no-tree-signal";
+    }
+  }
+}
+
+function runVerification(command) {
+  try {
+    const stdout = execSync(command, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+    return { exitCode: 0, stdout, stderr: "" };
+  } catch (err) {
+    return {
+      exitCode: err.status ?? 1,
+      stdout: err.stdout ? err.stdout.toString() : "",
+      stderr: err.stderr ? err.stderr.toString() : String(err.message || err),
+    };
+  }
+}
+
+function cmdCheck(specPath) {
+  if (!existsSync(specPath)) {
+    console.error(`FAIL: ${specPath} not found. Author a spec first (run the 'new' command).`);
+    process.exit(1);
+  }
+  const specContent = readFileSync(specPath, "utf-8");
+  const command = extractVerificationCommand(specContent);
+  if (!command) {
+    console.error(`FAIL: could not extract a runnable command from the Verification section of ${specPath}.`);
+    console.error("Either add a fenced/backtick command, or this spec is LLM-judge-based and must be checked manually, not via run_loop.mjs.");
+    process.exit(1);
+  }
+  const maxIterations = extractMaxIterations(specContent);
+
+  const state = loadState();
+  const key = resolve(specPath);
+  const entry = state[key] || { iterations: [], maxIterations };
+  entry.maxIterations = maxIterations; // always refresh from current spec in case it changed
+
+  const completedCount = entry.iterations.length;
+  if (completedCount >= maxIterations) {
+    console.log(JSON.stringify({
+      status: "stop-escalate",
+      reason: `Iteration cap reached (${completedCount}/${maxIterations}) without success.`,
+      iterations: completedCount,
+    }, null, 2));
+    process.exit(2);
+  }
+
+  console.error(`Running verification (iteration ${completedCount + 1}/${maxIterations}): ${command}`);
+  const result = runVerification(command);
+  const resultHash = hashResult(result.stdout, result.stderr, result.exitCode);
+  const treeHash = hashWorkingTree();
+  const compositeHash = `${resultHash}:${treeHash}`;
+  const iterationRecord = {
+    n: completedCount + 1,
+    exitCode: result.exitCode,
+    hash: compositeHash,
+    timestamp: new Date().toISOString(),
+  };
+  entry.iterations.push(iterationRecord);
+  state[key] = entry;
+  saveState(state);
+
+  if (result.exitCode === 0) {
+    console.log(JSON.stringify({
+      status: "success",
+      reason: "Verification command exited 0.",
+      iterations: entry.iterations.length,
+      stdout: result.stdout.slice(-2000),
+    }, null, 2));
+    process.exit(0);
+  }
+
+  // No-progress check: look at the last N hashes (including this one).
+  const recentHashes = entry.iterations.slice(-DEFAULT_NO_PROGRESS_LIMIT).map((it) => it.hash);
+  const allSame = recentHashes.length === DEFAULT_NO_PROGRESS_LIMIT && recentHashes.every((h) => h === recentHashes[0]);
+  if (allSame) {
+    console.log(JSON.stringify({
+      status: "stop-escalate",
+      reason: `No-progress: last ${DEFAULT_NO_PROGRESS_LIMIT} iterations produced an identical result AND an unchanged working tree (no files were modified, or the change reverted to the same state). Stopping to avoid burning budget on a repeated failure.`,
+      iterations: entry.iterations.length,
+      stderr: result.stderr.slice(-2000),
+    }, null, 2));
+    process.exit(2);
+  }
+
+  if (entry.iterations.length >= maxIterations) {
+    console.log(JSON.stringify({
+      status: "stop-escalate",
+      reason: `Iteration cap reached (${entry.iterations.length}/${maxIterations}) without success.`,
+      iterations: entry.iterations.length,
+      stderr: result.stderr.slice(-2000),
+    }, null, 2));
+    process.exit(2);
+  }
+
+  console.log(JSON.stringify({
+    status: "continue",
+    reason: "Verification failed but under cap and making progress (result differs from immediately preceding attempt). Make a change and check again.",
+    iterations: entry.iterations.length,
+    maxIterations,
+    stderr: result.stderr.slice(-2000),
+  }, null, 2));
+  process.exit(1);
+}
+
+function cmdReset(specPath) {
+  const state = loadState();
+  const key = resolve(specPath);
+  delete state[key];
+  saveState(state);
+  console.log(`Reset iteration history for ${specPath}.`);
+}
+
+function cmdStatus(specPath) {
+  const state = loadState();
+  const key = resolve(specPath);
+  const entry = state[key];
+  if (!entry) {
+    console.log(JSON.stringify({ status: "no-history", specPath }, null, 2));
+    return;
+  }
+  console.log(JSON.stringify({
+    specPath,
+    maxIterations: entry.maxIterations,
+    completed: entry.iterations.length,
+    history: entry.iterations,
+  }, null, 2));
+}
+
+function main() {
+  const [, , subcommand, specPathArg] = process.argv;
+  const specPath = resolve(specPathArg || "LOOP_SPEC.md");
+
+  switch (subcommand) {
+    case "check":
+      cmdCheck(specPath);
+      break;
+    case "reset":
+      cmdReset(specPath);
+      break;
+    case "status":
+      cmdStatus(specPath);
+      break;
+    default:
+      console.error("Usage: node run_loop.mjs <check|reset|status> [path/to/LOOP_SPEC.md]");
+      process.exit(1);
+  }
+}
+
+main();