@graypark/loophaus 3.8.0 → 3.9.0

package/dist/README.md

@@ -10,10 +10,10 @@
   <a href="https://github.com/vcz-Gray/loophaus/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license" /></a>
   <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg?style=flat-square" alt="node version" />
   <img src="https://img.shields.io/badge/platform-Claude%20Code%20%7C%20Codex%20CLI%20%7C%20Kiro%20CLI-purple.svg?style=flat-square" alt="platform" />
-  <img src="https://img.shields.io/badge/tests-296%20passing-brightgreen.svg?style=flat-square" alt="tests" />
+  <img src="https://img.shields.io/badge/tests-359%20passing-brightgreen.svg?style=flat-square" alt="tests" />
 </p>
 
-<h3 align="center">Control plane for coding agents — iterative dev loops across Claude Code, Codex CLI, and Kiro CLI.</h3>
+<h3 align="center">Run AI coding agents in autonomous loops — fresh context each iteration, PRD-tracked progress, automatic quality gates.</h3>
 
 <p align="center">
   <sub>Based on <a href="https://ghuntley.com/ralph/">Geoffrey Huntley's Ralph Wiggum technique</a></sub>
@@ -21,26 +21,55 @@
 
 ---
 
-## Why loophaus?
+## The Problem
 
-AI coding agents struggle with fundamental problems that get worse over long sessions:
+AI coding agents struggle with long tasks:
 
-| Problem | What happens |
-|---------|-------------|
-| **Context rot** | Long conversations accumulate noise, the agent gets confused |
-| **No checkpoints** | All-or-nothing execution — can't resume after interruption |
-| **Lost learnings** | Previous iterations' insights overwritten by new context |
-| **Completion ambiguity** | Agent says "done" but tests still fail |
-| **Platform lock-in** | Techniques that work in one agent don't transfer to others |
-
-loophaus solves this:
-
-- **Fresh context per iteration** — Each cycle reads PRD + progress from disk, zero degradation
-- **Git-enforced safety** — Atomic commits per story, rollback at any point
-- **Append-only learnings** — `progress.txt` accumulates knowledge across iterations
-- **Test-verified completion** — Agent can only exit when `<promise>COMPLETE</promise>` is genuinely true
+- **Context rot** — agent gets confused after 10+ iterations
+- **Goal drift** — agent forgets the spec and solves the wrong problem
+- **No quality signal** — agent says "done" but tests still fail
+- **Token waste** — you re-explain the same context every time
+
+## The Solution
+
+- **Fresh context per iteration** — Each cycle reads PRD + progress from disk, zero degradation even after 20+ iterations
+- **PRD-linked progress tracking** — Stories are tracked in `prd.json` with pass/fail state, not "I think I'm done"
+- **Quality scoring with keep/discard** — Autoresearch-inspired refinement loop measures quality (0-100) and reverts regressions
 - **Universal stop hook** — One Node.js hook works across Claude Code, Codex CLI, and Kiro CLI
 
+## Quick Start
+
+```bash
+npm install -g @graypark/loophaus
+loophaus install
+```
+
+> **Note:** `npx @graypark/loophaus install` may fail on some npm versions due to a bin resolution cache bug. Use the global install above for reliable setup.
+
+The installer auto-detects your host (Claude Code, Codex CLI, or Kiro CLI) and sets up everything — stop hook, commands, and skills.
+
+Then in your AI coding session:
+
+```
+/loop-plan Add user authentication with JWT, bcrypt, and login UI
+```
+
+That's it. The interview generates a PRD, activates the loop, and starts implementing story by story.
+
+## Safety
+
+- Every iteration creates a **git checkpoint** — atomic revert anytime
+- **Max iterations limit** (default 20, configurable)
+- **Quality threshold = circuit breaker** — score < 80 triggers refine or stop
+- **Cost tracking** with policy enforcement (max $5, max 30 min)
+- `loophaus clean` for data lifecycle management
+
+## Why not just script this?
+
+1. **Fresh context isolation** — no degradation after 20 iterations; each cycle starts from disk, not from a decaying conversation
+2. **PRD-linked progress tracking** — structured `prd.json` with pass/fail per story, not "I think I'm done"
+3. **Quality scoring with keep/discard** — autoresearch pattern: measure, keep improvements, revert regressions
+
 ## How it works
 
 An AI agent works on a task in a continuous loop. Each iteration starts with fresh context — reading the PRD and progress files to decide what to do next. The agent implements one story, commits, updates progress, and exits. The stop hook intercepts the exit and re-injects the prompt. Repeat until all stories pass.
@@ -80,33 +109,53 @@ An AI agent works on a task in a continuous loop. Each iteration starts with fre
               └─────────────────────────────────┘
 ```
 
-## Quick Start
+## Commands
 
-```bash
-npm install -g @graypark/loophaus
-loophaus install
-```
+| Command | Description |
+|---------|-------------|
+| `/loop-plan` | Interactive interview — asks targeted questions, generates PRD, activates loop |
+| `/loop` | Start iterative dev loop directly (when you already have a PRD or custom prompt) |
+| `/loop-stop` | Stop the active loop immediately |
+| `/loop-pulse` | Check current loop status, iteration count, and progress |
 
-> **Note:** `npx @graypark/loophaus install` may fail on some npm versions due to a bin resolution cache bug. Use the global install above for reliable setup.
+## Quality Loop (v3.4.0+)
 
-The installer auto-detects your host (Claude Code, Codex CLI, or Kiro CLI) and sets up everything — stop hook, commands, and skills.
+loophaus v3.4.0 introduces the **Quality Loop** — inspired by [karpathy/autoresearch](https://github.com/karpathy/autoresearch)'s experiment-measure-keep/discard pattern.
 
-Then in your AI coding session:
+Instead of simply marking a story as "done" when tests pass, `/loop-plan` now **measures quality** (0-100) and **iteratively refines** until the score meets the threshold.
 
 ```
-/loop-plan Add user authentication with JWT, bcrypt, and login UI
+Phase 4: Implement
+     ↓
+Phase 5: Evaluate (score 0-100)
+     ↓           ↑
+Phase 6: Refine Loop
+  score improved? → keep (commit)
+  score declined? → discard (git reset)
+  max attempts reached? → move on
+     ↓
+Phase 7: Report (with quality scores)
 ```
 
-That's it. The interview generates a PRD, activates the loop, and starts implementing story by story.
+| autoresearch | loophaus |
+|-------------|----------|
+| `val_bpb` | quality score (weighted: tests, typecheck, lint, verify, diff, custom) |
+| `results.tsv` | `.loophaus/results.tsv` |
+| keep → advance | score improved → commit |
+| discard → revert | score declined → `git reset --hard` |
+| NEVER STOP | max 3 attempts per story (configurable) |
 
-## Commands
+### Configuration
 
-| Command | Description |
-|---------|-------------|
-| `/loop-plan` | Interactive interview — asks targeted questions, generates PRD, activates loop |
-| `/loop` | Start iterative dev loop directly (when you already have a PRD or custom prompt) |
-| `/loop-stop` | Stop the active loop immediately |
-| `/loop-pulse` | Check current loop status, iteration count, and progress |
+```json
+{
+  "qualityThreshold": 80,
+  "maxRefineAttempts": 3,
+  "qualityConfig": {
+    "weights": { "tests": 30, "typecheck": 25, "lint": 15, "verify": 15, "diff": 10, "custom": 5 }
+  }
+}
+```
 
 ## Platform Support
 
@@ -165,55 +214,13 @@ loophaus install          # Install to detected host
 loophaus status           # Show current loop state and active host
 loophaus stats            # Iteration history and completion metrics
 loophaus quality          # Run quality scoring on current stories
+loophaus demo             # Run interactive demo
+loophaus config           # Show/edit configuration
+loophaus update-check     # Check for new versions
+loophaus upgrade          # Upgrade to latest version
 loophaus uninstall        # Clean removal from all hosts
 ```
 
-## Quality Loop (v3.4.0+)
-
-loophaus v3.4.0 introduces the **Quality Loop** — inspired by [karpathy/autoresearch](https://github.com/karpathy/autoresearch)'s experiment→measure→keep/discard pattern.
-
-Instead of simply marking a story as "done" when tests pass, `/loop-plan` now **measures quality** (0-100) and **iteratively refines** until the score meets the threshold.
-
-```
-Phase 4: Implement
-     ↓
-Phase 5: Evaluate (score 0-100)
-     ↓           ↑
-Phase 6: Refine Loop
-  score improved? → keep (commit)
-  score declined? → discard (git reset)
-  max attempts reached? → move on
-     ↓
-Phase 7: Report (with quality scores)
-```
-
-| autoresearch | loophaus |
-|-------------|----------|
-| `val_bpb` | quality score (weighted: tests, typecheck, lint, verify, diff, custom) |
-| `results.tsv` | `.loophaus/results.tsv` |
-| keep → advance | score improved → commit |
-| discard → revert | score declined → `git reset --hard` |
-| NEVER STOP | max 3 attempts per story (configurable) |
-
-### Configuration
-
-```json
-{
-  "qualityThreshold": 80,
-  "maxRefineAttempts": 3,
-  "qualityConfig": {
-    "weights": { "tests": 30, "typecheck": 25, "lint": 15, "verify": 15, "diff": 10, "custom": 5 }
-  }
-}
-```
-
-### CLI
-
-```bash
-loophaus quality               # Score all stories
-loophaus quality --story US-001 # Score a specific story
-```
-
 ## Architecture
 
 ```
@@ -253,7 +260,7 @@ loophaus/
 ├── .claude-plugin/
 │   └── plugin.json               # Claude Code marketplace manifest
 ├── dist/                         # Compiled output (tsc)
-└── tests/                        # 296 test cases (vitest)
+└── tests/                        # 359 test cases (vitest)
 ```
 
 ## PRD Format
@@ -311,10 +318,10 @@ npm uninstall -g @graypark/loophaus
 git clone https://github.com/vcz-Gray/loophaus.git
 cd loophaus
 npm install
-npm test
-npm run typecheck  # TypeScript strict mode
-npm run build      # Compile to dist/
-npx vitest        # watch mode
+npm test               # 359 tests
+npm run typecheck      # TypeScript strict mode
+npm run build          # Compile to dist/
+npx vitest             # watch mode
 ```
 
 ## License

package/dist/bin/loophaus.js

@@ -24,7 +24,7 @@ const VALID_COMMANDS = [
     "install", "uninstall", "status", "stats", "loops", "watch",
     "replay", "compare", "worktree", "parallel", "quality",
     "sessions", "resume", "benchmark", "clean", "config",
-    "update-check", "upgrade", "help",
+    "update-check", "upgrade", "demo", "help",
 ];
 function validateFlags() {
     for (const arg of args) {
@@ -122,6 +122,7 @@ Usage:
   npx @graypark/loophaus upgrade
   npx @graypark/loophaus sessions
   npx @graypark/loophaus resume <session-id>
+  npx @graypark/loophaus demo
   npx @graypark/loophaus --version
 
 Hosts:
@@ -878,6 +879,94 @@ function setNestedValue(obj, path, value) {
     }
     current[parts[parts.length - 1]] = value;
 }
+async function runDemo() {
+    const { mkdtemp, writeFile, rm, mkdir } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join: pathJoin } = await import("node:path");
+    const { execSync } = await import("node:child_process");
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    console.log(`loophaus demo`);
+    console.log(`\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550`);
+    console.log();
+    const demoDir = await mkdtemp(pathJoin(tmpdir(), "loophaus-demo-"));
+    try {
+        // Initialize git repo
+        execSync("git init -q", { cwd: demoDir, stdio: "ignore" });
+        execSync("git config user.email 'demo@loophaus.dev'", { cwd: demoDir, stdio: "ignore" });
+        execSync("git config user.name 'loophaus-demo'", { cwd: demoDir, stdio: "ignore" });
+        // Write broken index.mjs
+        const indexContent = `// index.mjs — broken sum function
+export function sum(a, b) {
+  return a - b; // BUG: should be a + b
+}
+`;
+        await writeFile(pathJoin(demoDir, "index.mjs"), indexContent, "utf-8");
+        // Write prd.json with 2 stories
+        const prd = {
+            title: "Fix sum module",
+            userStories: [
+                { id: "US-001", title: "Fix sum function", acceptance: "sum(2, 3) returns 5", passes: false },
+                { id: "US-002", title: "Add tests", acceptance: "test file verifies sum works", passes: false },
+            ],
+        };
+        await writeFile(pathJoin(demoDir, "prd.json"), JSON.stringify(prd, null, 2), "utf-8");
+        // Write state.json
+        await mkdir(pathJoin(demoDir, ".loophaus"), { recursive: true });
+        const state = { active: true, currentIteration: 0, maxIterations: 4, completionPromise: "Fix sum module" };
+        await writeFile(pathJoin(demoDir, ".loophaus", "state.json"), JSON.stringify(state, null, 2), "utf-8");
+        // Initial commit
+        execSync("git add -A && git commit -q -m 'init: broken sum'", { cwd: demoDir, stdio: "ignore" });
+        // Show project tree
+        console.log(`Creating demo project...`);
+        console.log();
+        await sleep(400);
+        console.log(`\uD83D\uDCC1 ${demoDir}/`);
+        console.log(`\u251C\u2500\u2500 index.mjs        (broken sum function)`);
+        console.log(`\u251C\u2500\u2500 prd.json          (2 stories)`);
+        console.log(`\u2514\u2500\u2500 .loophaus/state.json`);
+        console.log();
+        await sleep(600);
+        // Simulate iteration 1
+        console.log(`Simulating loop iteration 1/4...`);
+        await sleep(300);
+        console.log(`  \u2192 Reading prd.json: 2 stories, 0 done`);
+        await sleep(400);
+        console.log(`  \u2192 Working on US-001: Fix sum function`);
+        await sleep(600);
+        console.log(`  \u2192 Verified: sum(2, 3) = 5 \u2713`);
+        await sleep(300);
+        console.log(`  \u2192 Committed: feat: US-001 Fix sum function`);
+        console.log();
+        await sleep(500);
+        // Simulate iteration 2
+        console.log(`Simulating loop iteration 2/4...`);
+        await sleep(300);
+        console.log(`  \u2192 Reading prd.json: 2 stories, 1 done`);
+        await sleep(400);
+        console.log(`  \u2192 Working on US-002: Add tests`);
+        await sleep(600);
+        console.log(`  \u2192 Verified: 2 tests passing \u2713`);
+        await sleep(300);
+        console.log(`  \u2192 Committed: feat: US-002 Add tests`);
+        console.log();
+        await sleep(500);
+        console.log(`Quality Score: 95/100 (A+)`);
+        console.log();
+        console.log(`All stories complete! \uD83C\uDF89`);
+        console.log();
+        console.log(`This is what /loop-plan does autonomously in your real projects.`);
+        console.log();
+        console.log(`Try it:`);
+        console.log(`  cd your-project`);
+        console.log(`  /loop-plan "describe your task here"`);
+        console.log();
+        console.log(`Cleaning up demo...`);
+    }
+    finally {
+        // Clean up temp directory
+        await rm(demoDir, { recursive: true, force: true });
+    }
+}
 try {
     switch (command) {
         case "install":
@@ -934,6 +1023,9 @@ try {
         case "resume":
             await runResume();
             break;
+        case "demo":
+            await runDemo();
+            break;
         default:
             if (command.startsWith("-")) {
                 await runInstall();

package/dist/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@graypark/loophaus",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "type": "module",
-  "description": "loophaus — Control plane for coding agents. Iterative dev loops with multi-agent orchestration.",
+  "description": "Autonomous dev loops for AI coding agents — fresh context each iteration, PRD-tracked progress, automatic quality gates.",
   "license": "MIT",
   "author": "graypark",
   "repository": {
     "type": "git",
-    "url": "https://github.com/vcz-Gray/loophaus"
+    "url": "git+https://github.com/vcz-Gray/loophaus.git"
   },
   "homepage": "https://github.com/vcz-Gray/loophaus#readme",
   "bugs": {
@@ -17,7 +17,7 @@
     "access": "public"
   },
   "bin": {
-    "loophaus": "./dist/bin/loophaus.js"
+    "loophaus": "dist/bin/loophaus.js"
   },
   "files": [
     "dist/",
@@ -43,16 +43,23 @@
     "prepare": "npm run build"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.0.0",
+    "npm": ">=9.0.0"
   },
   "keywords": [
     "loophaus",
-    "loop",
+    "autonomous",
     "ai-agent",
-    "iterative-development",
+    "coding-agents",
+    "fresh-context",
+    "prd",
+    "quality-scoring",
+    "autoresearch",
+    "claude-code",
+    "codex-cli",
+    "kiro-cli",
     "stop-hook",
-    "control-plane",
-    "coding-agents"
+    "iterative-development"
   ],
   "devDependencies": {
     "@types/node": "^25.5.0",

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@graypark/loophaus",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "type": "module",
-  "description": "loophaus — Control plane for coding agents. Iterative dev loops with multi-agent orchestration.",
+  "description": "Autonomous dev loops for AI coding agents — fresh context each iteration, PRD-tracked progress, automatic quality gates.",
   "license": "MIT",
   "author": "graypark",
   "repository": {
     "type": "git",
-    "url": "https://github.com/vcz-Gray/loophaus"
+    "url": "git+https://github.com/vcz-Gray/loophaus.git"
   },
   "homepage": "https://github.com/vcz-Gray/loophaus#readme",
   "bugs": {
@@ -17,7 +17,7 @@
     "access": "public"
   },
   "bin": {
-    "loophaus": "./dist/bin/loophaus.js"
+    "loophaus": "dist/bin/loophaus.js"
   },
   "files": [
     "dist/",
@@ -43,16 +43,23 @@
     "prepare": "npm run build"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.0.0",
+    "npm": ">=9.0.0"
   },
   "keywords": [
     "loophaus",
-    "loop",
+    "autonomous",
     "ai-agent",
-    "iterative-development",
+    "coding-agents",
+    "fresh-context",
+    "prd",
+    "quality-scoring",
+    "autoresearch",
+    "claude-code",
+    "codex-cli",
+    "kiro-cli",
     "stop-hook",
-    "control-plane",
-    "coding-agents"
+    "iterative-development"
   ],
   "devDependencies": {
     "@types/node": "^25.5.0",