@graypark/loophaus 3.1.0 → 3.3.0

package/bin/loophaus.mjs

@@ -44,6 +44,10 @@ Usage:
   npx @graypark/loophaus replay <trace-file> [--speed 2]
   npx @graypark/loophaus compare <trace1> <trace2>
   npx @graypark/loophaus loops
+  npx @graypark/loophaus worktree <create|remove|list>
+  npx @graypark/loophaus parallel <prd.json> [--count N] [--base branch]
+  npx @graypark/loophaus sessions
+  npx @graypark/loophaus resume <session-id>
   npx @graypark/loophaus --version
 
 Hosts:
@@ -371,6 +375,79 @@ async function runCompare() {
   console.log("");
 }
 
+async function runWorktree() {
+  const sub = args[1];
+  const { createWorktree, removeWorktree, listWorktrees } = await import("../core/worktree.mjs");
+
+  switch (sub) {
+    case "create": {
+      const name = args[2];
+      const base = args[3] || "HEAD";
+      if (!name) { console.log("Usage: loophaus worktree create <name> [base-branch]"); return; }
+      const wt = await createWorktree(name, base);
+      console.log(`Created worktree: ${wt.name} at ${wt.path} (branch: ${wt.branch})`);
+      break;
+    }
+    case "remove": {
+      const name = args[2];
+      if (!name) { console.log("Usage: loophaus worktree remove <name>"); return; }
+      await removeWorktree(name);
+      console.log(`Removed worktree: ${name}`);
+      break;
+    }
+    case "list": {
+      const wts = await listWorktrees();
+      if (wts.length === 0) { console.log("No loophaus worktrees."); return; }
+      console.log("Worktrees");
+      console.log("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+      for (const wt of wts) {
+        console.log(`  ${wt.name}  ${wt.branch}  ${wt.path}`);
+      }
+      break;
+    }
+    default:
+      console.log("Usage: loophaus worktree <create|remove|list>");
+  }
+}
+
+async function runSessions() {
+  const { listSessions } = await import("../core/session.mjs");
+  const sessions = await listSessions();
+  if (sessions.length === 0) { console.log("No saved sessions."); return; }
+  console.log("Sessions");
+  console.log("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  for (const s of sessions) {
+    const age = Math.round((Date.now() - new Date(s.savedAt).getTime()) / 60000);
+    console.log(`  ${s.sessionId}  iter=${s.currentIteration || 0}  ${age}m ago`);
+  }
+}
+
+async function runResume() {
+  const id = args[1];
+  if (!id) { console.log("Usage: loophaus resume <session-id>"); return; }
+  const { resumeSession } = await import("../core/session.mjs");
+  const state = await resumeSession(id);
+  if (!state) { console.log(`Session not found: ${id}`); return; }
+  console.log(`Resumed session ${id} at iteration ${state.currentIteration}`);
+  console.log(`Loop is now active. The stop hook will continue from here.`);
+}
+
+async function runParallelCmd() {
+  const prdPath = args[1] || "prd.json";
+  const count = parseInt(getFlag("--count") || "2", 10);
+  const base = getFlag("--base") || "HEAD";
+
+  const { runParallel } = await import("../core/parallel-runner.mjs");
+  const result = await runParallel({ prdPath, count, baseBranch: base });
+  console.log(result.message);
+  if (result.worktrees) {
+    console.log("\nWorktrees:");
+    for (const wt of result.worktrees) {
+      console.log(`  ${wt.name}  branch:${wt.branch}  stories:[${wt.stories.join(",")}]`);
+    }
+  }
+}
+
 try {
   switch (command) {
     case "install": await runInstall(); break;
@@ -381,6 +458,10 @@ try {
     case "watch": await runWatch(); break;
     case "replay": await runReplay(); break;
     case "compare": await runCompare(); break;
+    case "worktree": await runWorktree(); break;
+    case "parallel": await runParallelCmd(); break;
+    case "sessions": await runSessions(); break;
+    case "resume": await runResume(); break;
     default:
       if (command.startsWith("-")) {
         await runInstall();

package/commands/loop-plan.md

@@ -1,44 +1,166 @@
 ---
-description: "Plan and start loop via interactive interview"
+description: "Plan and start loop via interactive interview — auto-parallelizes across worktrees"
 argument-hint: "TASK_DESCRIPTION"
 allowed-tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "Agent", "Skill"]
 ---
 
-# /loop-plan — Interactive Planning & Loop
+# /loop-plan — Plan, Parallelize, Execute, Merge
+
+End-to-end workflow: interview → PRD → parallel distribution → loop execution → merge.
+The user runs `/loop-plan` once and gets a single merged branch with all work done.
+
+---
 
 ## Phase 1: Discovery Interview
 
-Ask the user 3-5 focused questions about $ARGUMENTS to understand:
-- What exactly needs to be built
-- Acceptance criteria
-- Technical constraints
-- Dependencies
+Ask 3-5 focused questions about $ARGUMENTS:
+
+| Category | What to confirm |
+|----------|----------------|
+| Scope | Single feature? Multi-file? Full refactor? |
+| Success criteria | What counts as "done"? |
+| Verification | `npm test`, `npx tsc`, lint commands? |
+| References | Existing code, patterns to follow? |
+| Parallelism | Multiple services? Independent file groups? |
+| Constraints | Must not break existing tests? Library restrictions? |
+
+One round of questions only. Skip questions already answered in $ARGUMENTS.
 
 ## Phase 2: PRD Generation
 
-Generate `prd.json` with user stories:
+Generate `prd.json`:
 
 ```json
 {
   "title": "<project title>",
+  "description": "<1-2 sentence summary>",
   "userStories": [
-    { "id": "US-001", "title": "<story>", "acceptance": "<criteria>", "passes": false },
-    ...
+    {
+      "id": "US-001",
+      "title": "<story title>",
+      "description": "<what to implement>",
+      "acceptanceCriteria": ["<criterion 1>", "<criterion 2>"],
+      "priority": 1,
+      "passes": false,
+      "group": "<ownership group — e.g., frontend, backend, auth, database>",
+      "testCommand": "<optional: npm test -- US-001>"
+    }
   ]
 }
 ```
 
-Right-size stories: each should be completable in 1-2 loop iterations.
+Rules:
+- Right-size stories: each completable in 1-2 iterations
+- Assign `group` to each story for parallel distribution
+- Order by `priority` (dependencies first)
+- Include `testCommand` when verification is possible
+
+Present PRD to user for approval before proceeding.
+
+## Phase 3: Parallelism Assessment
+
+Score the task for parallel execution:
+
+| Factor | Score |
+|--------|-------|
+| Stories span 3+ directories | +2 |
+| Stories are independent (no shared state) | +2 |
+| Multiple services (frontend/backend/auth) | +3 |
+| 6+ stories total | +1 |
+| Stories need full codebase context | -2 |
+| Strict ordering required | -3 |
+| Cross-file understanding needed | -1 |
+
+**Decision:**
+- Score >= 3 → **Parallel mode** (distribute across worktrees by `group`)
+- Score < 3 → **Sequential mode** (single loop, stories in order)
+
+Display the score and recommendation to the user. Proceed with the recommended mode unless the user overrides.
+
+## Phase 4A: Parallel Execution (score >= 3)
+
+### Step 1: Distribute stories by group
+
+Group stories by their `group` field. Each group becomes a worktree.
+
+```bash
+# Create the current branch as base for worktrees
+BASE_BRANCH=$(git branch --show-current)
+```
+
+### Step 2: Create worktrees and distribute PRDs
+
+For each group, use the Agent tool to spawn a subagent in an isolated worktree:
+
+```
+Agent(
+  prompt: "Implement the following stories from prd.json in this worktree.
+           Work on one story at a time. For each story:
+           1. Read prd.json and pick the next story where passes=false
+           2. Implement the story
+           3. Verify with the test command if provided
+           4. Set passes=true in prd.json
+           5. Commit: git add -A && git commit -m 'feat: <story-id> <title>'
+
+           When ALL stories pass, output <promise>TASK COMPLETE</promise>.
+
+           Stories assigned to you:
+           <filtered stories for this group>",
+  isolation: "worktree",
+  run_in_background: true,
+  name: "<group-name>"
+)
+```
+
+Launch ALL group agents in a single message (parallel execution).
+
+### Step 3: Wait and collect results
+
+Monitor agent completion. When all agents finish:
+
+1. List completed worktrees and their branches
+2. For each worktree branch, check if all assigned stories passed
+
+### Step 4: Merge results
+
+Merge all worktree branches back to the base branch using squash strategy:
+
+```bash
+git checkout $BASE_BRANCH
+
+# For each completed worktree branch:
+git merge --squash loophaus/<group-name>
+git commit -m "feat: merge <group-name> stories"
+```
+
+If merge conflicts occur:
+1. Report the conflict to the user
+2. Suggest manual resolution
+3. Do NOT force-resolve
+
+### Step 5: Cleanup
 
-## Phase 3: Loop Activation
+```bash
+# Remove worktrees
+git worktree list | grep .loophaus/worktrees | awk '{print $1}' | xargs -I {} git worktree remove {} --force
+# Remove branches
+git branch | grep loophaus/ | xargs git branch -D
+```
 
-After PRD approval, initialize the loop:
+### Step 6: Final verification
+
+Run the full test/verification command on the merged result.
+Update the main `prd.json` with all stories marked as `passes: true`.
+
+## Phase 4B: Sequential Execution (score < 3)
+
+Single loop, no worktrees:
 
 1. Create `.loophaus/state.json`:
 ```json
 {
   "active": true,
-  "prompt": "<implementation prompt based on PRD>",
+  "prompt": "Read prd.json. Pick next story where passes=false. Implement, verify, commit. Update progress.txt.",
   "completionPromise": "TASK COMPLETE",
   "maxIterations": <stories * 2 + 3>,
   "currentIteration": 0,
@@ -47,9 +169,37 @@ After PRD approval, initialize the loop:
 ```
 
 2. Start working on US-001 immediately.
+3. Each iteration: implement one story, verify, commit, update prd.json.
+4. Output `<promise>TASK COMPLETE</promise>` when ALL stories pass.
+
+## Phase 5: Summary Report
+
+After completion (parallel or sequential), output:
+
+```
+Loop Plan Complete
+══════════════════
+
+Mode:       parallel (3 worktrees) | sequential
+Stories:    7/7 done
+Duration:   ~15 minutes
+Iterations: 12 total (across all workers)
+
+Stories:
+  ✓ US-001  Add login API          (backend, 2 iterations)
+  ✓ US-002  Add auth middleware     (backend, 1 iteration)
+  ✓ US-003  Add login UI           (frontend, 3 iterations)
+  ...
+
+Branch:     feature/auth-system (all work merged)
+Verify:     npm test ✓
+```
 
 ## Rules
 
-- Each iteration: pick next pending story, implement, verify, mark passes=true if done
-- Update `progress.txt` with status after each story
-- Use `<promise>TASK COMPLETE</promise>` ONLY when ALL stories pass
+- ALWAYS present PRD for user approval before execution
+- ALWAYS show parallelism score and recommendation
+- If parallel: launch ALL agents simultaneously (single message with multiple Agent calls)
+- If merge conflict: STOP and report. Do not auto-resolve.
+- Use `<promise>TASK COMPLETE</promise>` ONLY when genuinely complete
+- Update `progress.txt` with learnings after each story

package/core/engine.mjs

@@ -27,6 +27,19 @@ export function evaluateStopHook(input, state) {
     };
   }
 
+  if (input.policy_result && input.policy_result.shouldStop) {
+    nextState.active = false;
+    events.push({ event: "stop", reason: "policy_violation", violations: input.policy_result.violations });
+    const reasons = input.policy_result.violations.map(v => `${v.type}: ${v.current}/${v.limit}`).join(", ");
+    return {
+      decision: "allow",
+      nextState,
+      events,
+      output: null,
+      message: `Loop: policy violation (${reasons}).`,
+    };
+  }
+
   if (nextState.completionPromise && input.last_assistant_text) {
     if (extractPromise(input.last_assistant_text, nextState.completionPromise)) {
       nextState.active = false;
@@ -57,6 +70,16 @@ export function evaluateStopHook(input, state) {
     events.push({ event: "verify_failed", script: nextState.verifyScript, output: input.verify_result.output || "" });
   }
 
+  if (input.test_results && input.test_results.length > 0) {
+    const allPassed = input.test_results.every(r => r.passed);
+    if (allPassed) {
+      events.push({ event: "test_result", status: "all_passed", results: input.test_results });
+    } else {
+      const failed = input.test_results.filter(r => !r.passed);
+      events.push({ event: "test_result", status: "some_failed", failed: failed.map(f => f.storyId) });
+    }
+  }
+
   if (input.stop_hook_active === true) {
     if (!input.has_pending_stories) {
       nextState.active = false;

package/core/merge-strategy.mjs

@@ -0,0 +1,72 @@
+// core/merge-strategy.mjs
+// Strategies for merging parallel worktree results back
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export const STRATEGIES = {
+  sequential: "Merge branches one by one in order",
+  "cherry-pick": "Cherry-pick specific commits from each branch",
+  squash: "Squash each branch into a single commit before merging",
+};
+
+export async function mergeSequential(branches, targetBranch = "main") {
+  const results = [];
+  for (const branch of branches) {
+    try {
+      await execFileAsync("git", ["merge", branch, "--no-edit"]);
+      results.push({ branch, status: "merged" });
+    } catch (err) {
+      results.push({ branch, status: "conflict", error: err.message });
+      try { await execFileAsync("git", ["merge", "--abort"]); } catch {}
+      break;
+    }
+  }
+  return results;
+}
+
+export async function mergeSquash(branches) {
+  const results = [];
+  for (const branch of branches) {
+    try {
+      await execFileAsync("git", ["merge", "--squash", branch]);
+      await execFileAsync("git", ["commit", "-m", `squash: merge ${branch}`]);
+      results.push({ branch, status: "squashed" });
+    } catch (err) {
+      results.push({ branch, status: "conflict", error: err.message });
+      try { await execFileAsync("git", ["merge", "--abort"]); } catch {}
+      break;
+    }
+  }
+  return results;
+}
+
+export async function mergeCherryPick(branches) {
+  const results = [];
+  for (const branch of branches) {
+    try {
+      const { stdout } = await execFileAsync("git", ["log", `main..${branch}`, "--format=%H", "--reverse"]);
+      const commits = stdout.trim().split("\n").filter(Boolean);
+      for (const commit of commits) {
+        await execFileAsync("git", ["cherry-pick", commit]);
+      }
+      results.push({ branch, status: "cherry-picked", commits: commits.length });
+    } catch (err) {
+      results.push({ branch, status: "conflict", error: err.message });
+      try { await execFileAsync("git", ["cherry-pick", "--abort"]); } catch {}
+      break;
+    }
+  }
+  return results;
+}
+
+export async function merge(strategy, branches, targetBranch) {
+  switch (strategy) {
+    case "sequential": return mergeSequential(branches, targetBranch);
+    case "squash": return mergeSquash(branches);
+    case "cherry-pick": return mergeCherryPick(branches);
+    default: throw new Error(`Unknown merge strategy: ${strategy}`);
+  }
+}

package/core/parallel-runner.mjs

@@ -0,0 +1,94 @@
+// core/parallel-runner.mjs
+// Parallel loop execution across worktrees
+
+import { fork } from "node:child_process";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createWorktree, removeWorktree, listWorktrees } from "./worktree.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const HOOKS_DIR = resolve(dirname(__filename), "..", "hooks");
+
+export function distributeStories(stories, n) {
+  const sorted = [...stories].sort((a, b) => (a.priority || 999) - (b.priority || 999));
+  const buckets = Array.from({ length: n }, () => []);
+  sorted.forEach((story, i) => buckets[i % n].push(story));
+  return buckets;
+}
+
+export async function runParallel({ prdPath, count = 2, baseBranch = "HEAD", cwd }) {
+  const raw = await readFile(prdPath, "utf-8");
+  const prd = JSON.parse(raw);
+  const pending = (prd.userStories || []).filter(s => !s.passes);
+
+  if (pending.length === 0) {
+    return { success: true, message: "No pending stories.", results: [] };
+  }
+
+  const effectiveCount = Math.min(count, pending.length);
+  const buckets = distributeStories(pending, effectiveCount);
+
+  const worktrees = [];
+  for (let i = 0; i < effectiveCount; i++) {
+    const name = `parallel-${i}`;
+    try {
+      const wt = await createWorktree(name, baseBranch);
+      worktrees.push({ ...wt, stories: buckets[i] });
+    } catch (err) {
+      for (const prev of worktrees) {
+        try { await removeWorktree(prev.name); } catch {}
+      }
+      throw new Error(`Failed to create worktree ${name}: ${err.message}`);
+    }
+  }
+
+  for (const wt of worktrees) {
+    const wtPrd = {
+      ...prd,
+      userStories: wt.stories,
+    };
+    const wtPrdPath = join(wt.path, "prd.json");
+    await writeFile(wtPrdPath, JSON.stringify(wtPrd, null, 2), "utf-8");
+
+    const stateDir = join(wt.path, ".loophaus");
+    await mkdir(stateDir, { recursive: true });
+    await writeFile(join(stateDir, "state.json"), JSON.stringify({
+      active: true,
+      prompt: `Implement stories from prd.json. Work on one story at a time.`,
+      completionPromise: "TASK COMPLETE",
+      maxIterations: wt.stories.length * 2 + 3,
+      currentIteration: 0,
+      sessionId: "",
+      name: wt.name,
+      startedAt: new Date().toISOString(),
+    }, null, 2), "utf-8");
+  }
+
+  return {
+    success: true,
+    worktrees: worktrees.map(wt => ({
+      name: wt.name,
+      path: wt.path,
+      branch: wt.branch,
+      stories: wt.stories.map(s => s.id),
+    })),
+    message: `Created ${effectiveCount} parallel worktrees with ${pending.length} stories distributed.`,
+  };
+}
+
+export async function cleanupParallel() {
+  const worktrees = await listWorktrees();
+  const results = [];
+  for (const wt of worktrees) {
+    if (wt.name.startsWith("parallel-")) {
+      try {
+        await removeWorktree(wt.name);
+        results.push({ name: wt.name, removed: true });
+      } catch (err) {
+        results.push({ name: wt.name, removed: false, error: err.message });
+      }
+    }
+  }
+  return results;
+}

package/core/policy.mjs

@@ -0,0 +1,58 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const DEFAULT_POLICY = {
+  id: "default",
+  conditions: [
+    { type: "max_iterations", value: 20 },
+  ],
+};
+
+export async function loadPolicy(cwd) {
+  const policyPath = join(cwd || process.cwd(), ".loophaus", "policy.json");
+  try {
+    const raw = await readFile(policyPath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return DEFAULT_POLICY;
+  }
+}
+
+export function evaluatePolicy(policy, state, context = {}) {
+  const violations = [];
+
+  for (const condition of policy.conditions || []) {
+    switch (condition.type) {
+      case "max_iterations":
+        if (state.currentIteration > condition.value) {
+          violations.push({ type: "max_iterations", limit: condition.value, current: state.currentIteration });
+        }
+        break;
+      case "max_cost":
+        if (context.totalCost && context.totalCost > condition.value) {
+          violations.push({ type: "max_cost", limit: condition.value, current: context.totalCost });
+        }
+        break;
+      case "max_time_minutes":
+        if (state.startedAt) {
+          const elapsed = (Date.now() - new Date(state.startedAt).getTime()) / 60000;
+          if (elapsed > condition.value) {
+            violations.push({ type: "max_time_minutes", limit: condition.value, current: Math.round(elapsed) });
+          }
+        }
+        break;
+      case "max_errors":
+        if (context.errorCount && context.errorCount > condition.value) {
+          violations.push({ type: "max_errors", limit: condition.value, current: context.errorCount });
+        }
+        break;
+    }
+  }
+
+  return {
+    shouldStop: violations.length > 0,
+    violations,
+  };
+}
+
+export { DEFAULT_POLICY };

package/core/session.mjs

@@ -0,0 +1,66 @@
+import { readFile, writeFile, readdir, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+function getSessionsDir(cwd) {
+  return join(cwd || process.cwd(), ".loophaus", "sessions");
+}
+
+export async function saveCheckpoint(sessionId, data, cwd) {
+  const dir = getSessionsDir(cwd);
+  await mkdir(dir, { recursive: true });
+  const checkpoint = {
+    sessionId,
+    savedAt: new Date().toISOString(),
+    ...data,
+  };
+  await writeFile(join(dir, `${sessionId}.json`), JSON.stringify(checkpoint, null, 2), "utf-8");
+  return checkpoint;
+}
+
+export async function loadCheckpoint(sessionId, cwd) {
+  const dir = getSessionsDir(cwd);
+  try {
+    const raw = await readFile(join(dir, `${sessionId}.json`), "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export async function listSessions(cwd) {
+  const dir = getSessionsDir(cwd);
+  try {
+    const files = await readdir(dir);
+    const sessions = [];
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+      try {
+        const raw = await readFile(join(dir, file), "utf-8");
+        const data = JSON.parse(raw);
+        sessions.push(data);
+      } catch { /* skip malformed */ }
+    }
+    return sessions.sort((a, b) => new Date(b.savedAt).getTime() - new Date(a.savedAt).getTime());
+  } catch {
+    return [];
+  }
+}
+
+export async function resumeSession(sessionId, cwd) {
+  const checkpoint = await loadCheckpoint(sessionId, cwd);
+  if (!checkpoint) return null;
+
+  const { write } = await import("../store/state-store.mjs");
+  const state = {
+    active: true,
+    prompt: checkpoint.prompt || "",
+    completionPromise: checkpoint.completionPromise || "TADA",
+    maxIterations: checkpoint.maxIterations || 20,
+    currentIteration: checkpoint.currentIteration || 0,
+    sessionId: checkpoint.sessionId,
+    name: checkpoint.name || "",
+    startedAt: checkpoint.startedAt || new Date().toISOString(),
+  };
+  await write(state, cwd, checkpoint.name);
+  return state;
+}

package/core/worktree.mjs

@@ -0,0 +1,97 @@
+// core/worktree.mjs
+// Git worktree lifecycle management
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdir, rm, access } from "node:fs/promises";
+import { join } from "node:path";
+
+const execFileAsync = promisify(execFile);
+
+async function fileExists(p) {
+  try { await access(p); return true; } catch { return false; }
+}
+
+export async function getRepoRoot() {
+  try {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "--show-toplevel"]);
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+export async function createWorktree(name, baseBranch = "HEAD") {
+  const root = await getRepoRoot();
+  if (!root) throw new Error("Not in a git repository");
+
+  const worktreePath = join(root, ".loophaus", "worktrees", name);
+  const branchName = `loophaus/${name}`;
+
+  if (await fileExists(worktreePath)) {
+    throw new Error(`Worktree already exists: ${name}`);
+  }
+
+  await mkdir(join(root, ".loophaus", "worktrees"), { recursive: true });
+
+  await execFileAsync("git", ["worktree", "add", "-b", branchName, worktreePath, baseBranch]);
+
+  return { name, path: worktreePath, branch: branchName };
+}
+
+export async function removeWorktree(name) {
+  const root = await getRepoRoot();
+  if (!root) throw new Error("Not in a git repository");
+
+  const worktreePath = join(root, ".loophaus", "worktrees", name);
+
+  if (!(await fileExists(worktreePath))) {
+    throw new Error(`Worktree not found: ${name}`);
+  }
+
+  await execFileAsync("git", ["worktree", "remove", worktreePath, "--force"]);
+
+  const branchName = `loophaus/${name}`;
+  try {
+    await execFileAsync("git", ["branch", "-D", branchName]);
+  } catch { /* branch may not exist */ }
+
+  return { name, removed: true };
+}
+
+export async function listWorktrees() {
+  const root = await getRepoRoot();
+  if (!root) return [];
+
+  try {
+    const { stdout } = await execFileAsync("git", ["worktree", "list", "--porcelain"]);
+    const entries = [];
+    let current = {};
+
+    for (const line of stdout.split("\n")) {
+      if (line.startsWith("worktree ")) {
+        if (current.path) entries.push(current);
+        current = { path: line.slice(9) };
+      } else if (line.startsWith("HEAD ")) {
+        current.head = line.slice(5);
+      } else if (line.startsWith("branch ")) {
+        current.branch = line.slice(7);
+      } else if (line === "bare") {
+        current.bare = true;
+      } else if (line === "") {
+        if (current.path) entries.push(current);
+        current = {};
+      }
+    }
+
+    const loophausDir = join(root, ".loophaus", "worktrees");
+    return entries.filter(e => e.path && e.path.startsWith(loophausDir)).map(e => ({
+      name: e.path.split("/").pop(),
+      path: e.path,
+      branch: e.branch || "",
+      head: e.head || "",
+    }));
+  } catch {
+    return [];
+  }
+}

package/hooks/stop-hook.mjs

@@ -4,6 +4,32 @@ import { evaluateStopHook } from "../core/engine.mjs";
 import { getLastAssistantText, hasPendingStories } from "../core/io-helpers.mjs";
 import { read as readState, write as writeState } from "../store/state-store.mjs";
 import { logEvents } from "../core/event-logger.mjs";
+import { join } from "node:path";
+
+async function runStoryTests(cwd) {
+  const { readFile } = await import("node:fs/promises");
+  const { execFile } = await import("node:child_process");
+  const { promisify } = await import("node:util");
+  const execFileAsync = promisify(execFile);
+  const prdPath = join(cwd, "prd.json");
+
+  try {
+    const prd = JSON.parse(await readFile(prdPath, "utf-8"));
+    if (!Array.isArray(prd.userStories)) return [];
+
+    const results = [];
+    for (const story of prd.userStories) {
+      if (!story.testCommand || story.passes) continue;
+      try {
+        await execFileAsync("sh", ["-c", story.testCommand], { cwd, timeout: 60_000 });
+        results.push({ storyId: story.id, passed: true });
+      } catch (err) {
+        results.push({ storyId: story.id, passed: false, error: err.message });
+      }
+    }
+    return results;
+  } catch { return []; }
+}
 
 async function readStdin() {
   const chunks = [];
@@ -39,11 +65,21 @@ async function main() {
     }
   }
 
+  // Run story tests if prd.json has testCommand fields
+  const testResults = await runStoryTests(cwd);
+
+  // Evaluate loop policy
+  const { loadPolicy, evaluatePolicy } = await import("../core/policy.mjs");
+  const policy = await loadPolicy(cwd);
+  const policyResult = evaluatePolicy(policy, state, { totalCost: 0, errorCount: 0 });
+
   const input = {
     ...hookInput,
     last_assistant_text: lastText,
     has_pending_stories: pending,
     verify_result: verifyResult,
+    test_results: testResults,
+    policy_result: policyResult,
   };
 
   const result = evaluateStopHook(input, state);
@@ -51,6 +87,19 @@ async function main() {
   await writeState(result.nextState, cwd);
   await logEvents(result.events, { adapter: "auto", loop_id: state.sessionId || "unknown" }, cwd);
 
+  // Save session checkpoint (best-effort)
+  try {
+    const { saveCheckpoint } = await import("../core/session.mjs");
+    await saveCheckpoint(result.nextState.sessionId || `auto-${Date.now()}`, {
+      prompt: result.nextState.prompt,
+      completionPromise: result.nextState.completionPromise,
+      maxIterations: result.nextState.maxIterations,
+      currentIteration: result.nextState.currentIteration,
+      name: result.nextState.name,
+      startedAt: result.nextState.startedAt,
+    }, cwd);
+  } catch { /* best-effort */ }
+
   if (result.message) process.stderr.write(result.message + "\n");
   if (result.output) process.stdout.write(JSON.stringify(result.output));
   process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graypark/loophaus",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "type": "module",
   "description": "loophaus — Control plane for coding agents. Iterative dev loops with multi-agent orchestration.",
   "license": "MIT",

package/platforms/codex-cli/installer.mjs

@@ -86,22 +86,37 @@ description: "Stop active loop"
   "loop-plan": {
     content: `---
 name: loop-plan
-description: "Plan and start loop via interactive interview"
+description: "Plan and start loop via interactive interview — auto-parallelizes across worktrees"
 argument-hint: "TASK_DESCRIPTION"
 ---
 
-# /loop-plan — Interactive Planning & Loop
+# /loop-plan — Plan, Parallelize, Execute, Merge
 
 ## Phase 1: Discovery Interview
-Ask 3-5 focused questions about the task to understand scope, acceptance criteria, constraints.
+Ask 3-5 focused questions about scope, success criteria, verification commands, parallelism potential.
 
 ## Phase 2: PRD Generation
-Generate \`prd.json\` with right-sized user stories.
-
-## Phase 3: Loop Activation
-Create \`.loophaus/state.json\` and start working on US-001 immediately.
-
-Use \`<promise>TASK COMPLETE</promise>\` ONLY when ALL stories pass.
+Generate \`prd.json\` with user stories. Each story has: id, title, description, acceptanceCriteria, priority, passes, group (for parallel distribution), testCommand.
+
+## Phase 3: Parallelism Assessment
+Score the task: stories span 3+ dirs (+2), independent (+2), multiple services (+3), 6+ stories (+1), need full context (-2), strict ordering (-3).
+Score >= 3: parallel mode (worktrees by group). Score < 3: sequential mode.
+
+## Phase 4A: Parallel Execution (score >= 3)
+1. Group stories by \`group\` field
+2. For each group, create an isolated worktree and assign stories
+3. Run all groups simultaneously
+4. When all complete, merge branches back (squash strategy)
+5. Run full verification on merged result
+
+## Phase 4B: Sequential Execution (score < 3)
+Create \`.loophaus/state.json\` and work through stories one at a time.
+
+## Rules
+- Present PRD for user approval before execution
+- Show parallelism score and recommendation
+- If merge conflict: STOP and report
+- Use \`<promise>TASK COMPLETE</promise>\` ONLY when ALL stories pass
 `,
   },
   "loop-pulse": {

package/platforms/kiro-cli/installer.mjs

@@ -64,22 +64,27 @@ description: "Stop active loop — use when user says 'stop loop', 'cancel loop'
   "loop-plan": {
     content: `---
 name: loop-plan
-description: "Plan and start loop via interactive interview — use when user says 'plan loop', 'interview', 'create PRD', 'plan task'"
+description: "Plan and start loop via interactive interview with auto-parallelization — use when user says 'plan loop', 'interview', 'create PRD', 'plan task', 'parallelize'"
 argument-hint: "TASK_DESCRIPTION"
 ---
 
-# Interactive Planning & Loop
+# Plan, Parallelize, Execute, Merge
 
 ## Phase 1: Discovery Interview
-Ask 3-5 focused questions about the task.
+Ask 3-5 focused questions about scope, success criteria, verification, parallelism.
 
 ## Phase 2: PRD Generation
-Generate prd.json with right-sized user stories.
+Generate prd.json. Each story has: id, title, group (for parallel distribution), testCommand, passes.
 
-## Phase 3: Loop Activation
-Create .loophaus/state.json and start working on US-001 immediately.
+## Phase 3: Parallelism Assessment
+Score: independent stories (+2), multiple services (+3), 6+ stories (+1), strict ordering (-3).
+Score >= 3: parallel (worktrees). Score < 3: sequential.
 
-Use \`<promise>TASK COMPLETE</promise>\` ONLY when ALL stories pass.
+## Phase 4: Execution
+Parallel: create worktrees per group, distribute stories, run simultaneously, merge back.
+Sequential: single loop through stories in order.
+
+Rules: present PRD for approval, show parallelism score, stop on merge conflicts.
 `,
   },
   "loop-pulse": {

package/skills/ralph-claude-interview/SKILL.md

@@ -50,7 +50,9 @@ Ask **concise questions** for missing items. Max 3-5 per round, one round only.
 | Cross-file understanding needed | -1    |
 | Multiple services               | +3    |
 
-Score >= 3: Use parallel Agent tool subagents in the prompt.
+Score >= 3: **Auto-parallel mode.** Group stories by `group` field, create isolated worktrees per group using Agent tool with `isolation: "worktree"`, launch ALL groups simultaneously in a single message. After all agents complete, merge branches back with squash strategy.
+
+Score < 3: Sequential mode. Single loop, stories in order.
 
 ### max-iterations
 
@@ -80,6 +82,8 @@ ralph-skills compatible format:
       "acceptanceCriteria": ["Criterion 1", "Typecheck passes"],
       "priority": 1,
       "passes": false,
+      "group": "backend",
+      "testCommand": "npm test -- US-001",
       "notes": ""
     }
   ]