@graypark/loophaus 2.0.0

package/commands/loop-pulse.md

@@ -0,0 +1,38 @@
+---
+description: "Check loop status"
+allowed-tools:
+  [
+    "Read(.loophaus/state.json)",
+    "Read(.claude/ralph-loop.local.md)",
+    "Read(prd.json)",
+    "Read(progress.txt)",
+  ]
+---
+
+# /loop-pulse — Check Loop Status
+
+1. Read `.loophaus/state.json` (or legacy `.claude/ralph-loop.local.md`)
+   - If neither exists: "No active loop."
+
+2. If active, display:
+   ```
+   Loop Status
+   ───────────
+   Active:     yes
+   Iteration:  5/20
+   Promise:    TASK COMPLETE
+   ```
+
+3. If `prd.json` exists, also show:
+   ```
+   Stories
+   ───────
+   ✓ US-001  Add login API
+   ✓ US-002  Add auth middleware
+   → US-003  Add JWT refresh (in progress)
+     US-004  Add logout endpoint
+
+   Progress: 2/4 done
+   ```
+
+4. If `progress.txt` exists, show last 5 lines.

package/commands/loop-stop.md

@@ -0,0 +1,29 @@
+---
+description: "Stop active loop"
+allowed-tools:
+  [
+    "Bash(test -f .loophaus/state.json:*)",
+    "Bash(rm .loophaus/state.json)",
+    "Read(.loophaus/state.json)",
+    "Bash(test -f .claude/ralph-loop.local.md:*)",
+    "Bash(rm .claude/ralph-loop.local.md)",
+    "Read(.claude/ralph-loop.local.md)",
+  ]
+---
+
+# /loop-stop — Stop Active Loop
+
+1. Check if `.loophaus/state.json` exists: `test -f .loophaus/state.json && echo "EXISTS" || echo "NOT_FOUND"`
+   - If not found, also check legacy path: `test -f .claude/ralph-loop.local.md && echo "LEGACY" || echo "NOT_FOUND"`
+
+2. **If NOT_FOUND** on both: Say "No active loop found."
+
+3. **If EXISTS** (.loophaus/state.json):
+   - Read the file to get `currentIteration`
+   - Remove it: `rm .loophaus/state.json`
+   - Report: "Stopped loop at iteration N."
+
+4. **If LEGACY** (.claude/ralph-loop.local.md):
+   - Read it to get the iteration field
+   - Remove it: `rm .claude/ralph-loop.local.md`
+   - Report: "Stopped loop at iteration N. (migrated from legacy path)"

package/commands/loop.md

@@ -0,0 +1,17 @@
+---
+description: "Start iterative dev loop"
+argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT]"
+allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh:*)"]
+---
+
+# /loop — Start Iterative Dev Loop
+
+Execute the setup script to initialize the loop:
+
+```!
+"${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
+```
+
+Work on the task. When you try to exit, the stop hook feeds the SAME PROMPT back for the next iteration. Your previous work persists in files and git history.
+
+CRITICAL: If a completion promise is set, ONLY output it when genuinely complete. Do not output false promises to escape the loop.

package/commands/ralph-loop.md

@@ -0,0 +1,18 @@
+---
+description: "Start Ralph Loop in current session"
+argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT]"
+allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh:*)"]
+hide-from-slash-command-tool: "true"
+---
+
+# Ralph Loop Command
+
+Execute the setup script to initialize the Ralph loop:
+
+```!
+"${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
+```
+
+Please work on the task. When you try to exit, the Ralph loop will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.
+
+CRITICAL RULE: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop, even if you think you're stuck or should exit for other reasons. The loop is designed to continue until genuine completion.

package/core/engine.mjs

@@ -0,0 +1,84 @@
+// Pure function: no I/O, no side effects. Returns decision + next state + events.
+
+export function evaluateStopHook(input, state) {
+  const events = [];
+  const nextState = { ...state };
+
+  if (!nextState.active) {
+    return { decision: "allow", nextState, events, output: null };
+  }
+
+  if (nextState.sessionId && input.session_id && nextState.sessionId !== input.session_id) {
+    return { decision: "allow", nextState, events, output: null };
+  }
+
+  nextState.currentIteration += 1;
+  events.push({ event: "iteration", iteration: nextState.currentIteration });
+
+  if (nextState.maxIterations > 0 && nextState.currentIteration > nextState.maxIterations) {
+    nextState.active = false;
+    events.push({ event: "stop", reason: "max_iterations" });
+    return {
+      decision: "allow",
+      nextState,
+      events,
+      output: null,
+      message: `Loop: max iterations (${nextState.maxIterations}) reached.`,
+    };
+  }
+
+  if (nextState.completionPromise && input.last_assistant_text) {
+    if (extractPromise(input.last_assistant_text, nextState.completionPromise)) {
+      nextState.active = false;
+      events.push({ event: "stop", reason: "completion_promise", promise: nextState.completionPromise });
+      return {
+        decision: "allow",
+        nextState,
+        events,
+        output: null,
+        message: `Loop: completion promise "${nextState.completionPromise}" detected.`,
+      };
+    }
+  }
+
+  if (input.stop_hook_active === true) {
+    if (!input.has_pending_stories) {
+      nextState.active = false;
+      events.push({ event: "stop", reason: "all_stories_done" });
+      return {
+        decision: "allow",
+        nextState,
+        events,
+        output: null,
+        message: "Loop: no pending stories. Allowing exit.",
+      };
+    }
+    events.push({ event: "continue", reason: "pending_stories" });
+  }
+
+  events.push({ event: "state_change", from: "running", to: "running" });
+
+  const iterInfo = nextState.maxIterations > 0
+    ? `${nextState.currentIteration}/${nextState.maxIterations}`
+    : `${nextState.currentIteration}`;
+
+  const reason = [nextState.prompt, "", "---", `Loop iteration ${iterInfo}. Continue working on the task above.`].join("\n");
+
+  const output = { decision: "block", reason };
+  if (nextState.completionPromise) {
+    output.systemMessage = `Loop iteration ${iterInfo} | To stop: output <promise>${nextState.completionPromise}</promise> (ONLY when TRUE)`;
+  } else {
+    output.systemMessage = `Loop iteration ${iterInfo} | No completion promise — loop runs until max iterations`;
+  }
+
+  return { decision: "block", nextState, events, output };
+}
+
+export function extractPromise(text, promisePhrase) {
+  const regex = new RegExp(`<promise>\\s*${escapeRegex(promisePhrase)}\\s*</promise>`, "s");
+  return regex.test(text);
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/core/event-logger.mjs

@@ -0,0 +1,37 @@
+// Best-effort trace logger. Failures never affect stop-hook decisions.
+
+import { appendFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+
+export function getTracePath(cwd) {
+  return join(cwd || process.cwd(), ".loophaus", "trace.jsonl");
+}
+
+export async function logEvents(events, metadata = {}, cwd) {
+  try {
+    const tracePath = getTracePath(cwd);
+    await mkdir(dirname(tracePath), { recursive: true });
+
+    const ts = new Date().toISOString();
+    const lines = events.map(e =>
+      JSON.stringify({ ts, ...metadata, ...e })
+    ).join("\n") + "\n";
+
+    await appendFile(tracePath, lines, "utf-8");
+  } catch {
+    // Best-effort: silently ignore failures
+  }
+}
+
+export async function readTrace(cwd) {
+  const tracePath = getTracePath(cwd);
+  try {
+    const { readFile } = await import("node:fs/promises");
+    const raw = await readFile(tracePath, "utf-8");
+    return raw.trim().split("\n").map(line => {
+      try { return JSON.parse(line); } catch { return null; }
+    }).filter(Boolean);
+  } catch {
+    return [];
+  }
+}

package/core/loop.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Loophaus Loop Protocol",
+  "type": "object",
+  "required": ["protocol_version", "states", "stop_conditions"],
+  "properties": {
+    "protocol_version": { "const": "1.0" },
+    "loop_id": { "type": "string" },
+    "states": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": { "enum": ["discovery", "plan", "implement", "verify", "commit", "done"] },
+          "transitions": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "stop_conditions": {
+      "type": "object",
+      "properties": {
+        "max_iterations": { "type": "integer", "minimum": 0 },
+        "completion_promise": { "type": "string" },
+        "all_stories_done": { "type": "boolean" }
+      }
+    }
+  }
+}

package/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "description": "loophaus stop hook for iterative coding loops",
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/stop-hook.mjs"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/stop-hook.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { evaluateStopHook } from "../core/engine.mjs";
+import { read as readState, write as writeState } from "../store/state-store.mjs";
+import { logEvents } from "../core/event-logger.mjs";
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+async function getLastAssistantText(transcriptPath) {
+  if (!transcriptPath) return "";
+  try {
+    const raw = await readFile(transcriptPath, "utf-8");
+    const lines = raw.trim().split("\n");
+    const recent = lines.filter((line) => {
+      try { return JSON.parse(line).role === "assistant"; } catch { return false; }
+    }).slice(-100);
+    for (let i = recent.length - 1; i >= 0; i--) {
+      try {
+        const obj = JSON.parse(recent[i]);
+        const contents = obj.message?.content || obj.content;
+        if (Array.isArray(contents)) {
+          for (let j = contents.length - 1; j >= 0; j--) {
+            if (contents[j].type === "text" && contents[j].text) return contents[j].text;
+          }
+        } else if (typeof contents === "string") return contents;
+      } catch { /* skip */ }
+    }
+  } catch { /* not found */ }
+  return "";
+}
+
+async function hasPendingStories(cwd) {
+  try {
+    const raw = await readFile(join(cwd || process.cwd(), "prd.json"), "utf-8");
+    const prd = JSON.parse(raw);
+    return Array.isArray(prd.userStories) && prd.userStories.some((s) => s.passes === false);
+  } catch { return false; }
+}
+
+async function main() {
+  let hookInput = {};
+  try {
+    const raw = await readStdin();
+    if (raw.trim()) hookInput = JSON.parse(raw);
+  } catch { /* empty input */ }
+
+  const cwd = hookInput.cwd || process.cwd();
+  const state = await readState(cwd);
+
+  const lastText = hookInput.last_assistant_message ||
+    await getLastAssistantText(hookInput.transcript_path || null);
+  const pending = await hasPendingStories(cwd);
+
+  const input = {
+    ...hookInput,
+    last_assistant_text: lastText,
+    has_pending_stories: pending,
+  };
+
+  const result = evaluateStopHook(input, state);
+
+  await writeState(result.nextState, cwd);
+  await logEvents(result.events, { adapter: "auto", loop_id: state.sessionId || "unknown" }, cwd);
+
+  if (result.message) process.stderr.write(result.message + "\n");
+  if (result.output) process.stdout.write(JSON.stringify(result.output));
+  process.exit(0);
+}
+
+main().catch((err) => {
+  process.stderr.write(`loophaus stop-hook error: ${err.message}\n`);
+  process.exit(0);
+});

package/lib/paths.mjs

@@ -0,0 +1,91 @@
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+let _cachedVersion = null;
+export function getPackageVersion() {
+  if (_cachedVersion) return _cachedVersion;
+  try {
+    const pkg = JSON.parse(
+      readFileSync(join(__dirname, "..", "package.json"), "utf-8"),
+    );
+    _cachedVersion = pkg.version;
+  } catch {
+    _cachedVersion = "0.0.0";
+  }
+  return _cachedVersion;
+}
+
+export function isWindows() {
+  return process.platform === "win32";
+}
+
+// --- Codex CLI paths ---
+
+export function getCodexHome() {
+  if (process.env.CODEX_HOME) {
+    return process.env.CODEX_HOME;
+  }
+  return join(homedir(), ".codex");
+}
+
+export function getHooksJsonPath() {
+  return join(getCodexHome(), "hooks.json");
+}
+
+export function getPluginInstallDir() {
+  return join(getCodexHome(), "plugins", "loophaus");
+}
+
+export function getSkillsDir() {
+  return join(getCodexHome(), "skills");
+}
+
+export function getLocalCodexDir() {
+  return join(process.cwd(), ".codex");
+}
+
+export function getLocalPluginDir() {
+  return join(getLocalCodexDir(), "plugins", "loophaus");
+}
+
+export function getLocalHooksJsonPath() {
+  return join(getLocalCodexDir(), "hooks.json");
+}
+
+export function getLocalSkillsDir() {
+  return join(getLocalCodexDir(), "skills");
+}
+
+// --- Claude Code paths ---
+
+export function getClaudeHome() {
+  return join(homedir(), ".claude");
+}
+
+export function getClaudePluginsDir() {
+  return join(getClaudeHome(), "plugins");
+}
+
+export function getClaudePluginCacheDir(version) {
+  const v = version || getPackageVersion();
+  return join(
+    getClaudePluginsDir(),
+    "cache",
+    "loophaus-marketplace",
+    "loophaus",
+    v,
+  );
+}
+
+export function getClaudeSettingsPath() {
+  return join(getClaudeHome(), "settings.json");
+}
+
+export function getClaudeInstalledPluginsPath() {
+  return join(getClaudePluginsDir(), "installed_plugins.json");
+}

package/lib/state.mjs

@@ -0,0 +1,46 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+
+const DEFAULT_STATE = {
+  active: false,
+  prompt: "",
+  completionPromise: "TADA",
+  maxIterations: 20,
+  currentIteration: 0,
+  sessionId: "",
+};
+
+export function getStatePath() {
+  return (
+    process.env.LOOPHAUS_STATE_FILE ||
+    process.env.RALPH_STATE_FILE ||
+    join(process.cwd(), ".loophaus", "state.json")
+  );
+}
+
+export async function readState() {
+  const statePath = getStatePath();
+  try {
+    const raw = await readFile(statePath, "utf-8");
+    return { ...DEFAULT_STATE, ...JSON.parse(raw) };
+  } catch {
+    return { ...DEFAULT_STATE };
+  }
+}
+
+export async function writeState(state) {
+  const statePath = getStatePath();
+  await mkdir(dirname(statePath), { recursive: true });
+  await writeFile(statePath, JSON.stringify(state, null, 2), "utf-8");
+}
+
+export async function resetState() {
+  await writeState({ ...DEFAULT_STATE });
+}
+
+export async function incrementIteration() {
+  const state = await readState();
+  state.currentIteration += 1;
+  await writeState(state);
+  return state;
+}

package/lib/stop-hook-core.mjs

@@ -0,0 +1,162 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export function extractPromise(text, promisePhrase) {
+  const regex = new RegExp(
+    `<promise>\\s*${escapeRegex(promisePhrase)}\\s*</promise>`,
+    "s",
+  );
+  return regex.test(text);
+}
+
+export function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export async function getLastAssistantText(transcriptPath) {
+  if (!transcriptPath) return "";
+  try {
+    const raw = await readFile(transcriptPath, "utf-8");
+    const lines = raw.trim().split("\n");
+    const assistantLines = lines.filter((line) => {
+      try {
+        const obj = JSON.parse(line);
+        return obj.role === "assistant";
+      } catch {
+        return false;
+      }
+    });
+    const recent = assistantLines.slice(-100);
+    for (let i = recent.length - 1; i >= 0; i--) {
+      try {
+        const obj = JSON.parse(recent[i]);
+        const contents = obj.message?.content || obj.content;
+        if (Array.isArray(contents)) {
+          for (let j = contents.length - 1; j >= 0; j--) {
+            if (contents[j].type === "text" && contents[j].text) {
+              return contents[j].text;
+            }
+          }
+        } else if (typeof contents === "string") {
+          return contents;
+        }
+      } catch {
+        // skip malformed lines
+      }
+    }
+  } catch {
+    // transcript not found or unreadable
+  }
+  return "";
+}
+
+export async function hasPendingStories(cwd) {
+  const prdPath = join(cwd || process.cwd(), "prd.json");
+  try {
+    const raw = await readFile(prdPath, "utf-8");
+    const prd = JSON.parse(raw);
+    if (!Array.isArray(prd.userStories)) return false;
+    return prd.userStories.some((s) => s.passes === false);
+  } catch {
+    return false;
+  }
+}
+
+export async function processStopHook(hookInput, readStateFn, writeStateFn) {
+  const stderr = [];
+  const state = await readStateFn();
+
+  // Not active — allow exit
+  if (!state.active) {
+    return { exitCode: 0, stdout: "", stderr: "" };
+  }
+
+  // Session isolation
+  if (
+    state.sessionId &&
+    hookInput.session_id &&
+    state.sessionId !== hookInput.session_id
+  ) {
+    return { exitCode: 0, stdout: "", stderr: "" };
+  }
+
+  // Increment iteration
+  state.currentIteration += 1;
+
+  // Check max iterations
+  if (state.maxIterations > 0 && state.currentIteration > state.maxIterations) {
+    stderr.push(
+      `Loop: max iterations (${state.maxIterations}) reached.\n`,
+    );
+    state.active = false;
+    await writeStateFn(state);
+    return { exitCode: 0, stdout: "", stderr: stderr.join("") };
+  }
+
+  // Check completion promise
+  if (state.completionPromise) {
+    const lastText =
+      hookInput.last_assistant_message ||
+      (await getLastAssistantText(hookInput.transcript_path || null));
+
+    if (lastText && extractPromise(lastText, state.completionPromise)) {
+      stderr.push(
+        `Loop: completion promise "${state.completionPromise}" detected.\n`,
+      );
+      state.active = false;
+      await writeStateFn(state);
+      return { exitCode: 0, stdout: "", stderr: stderr.join("") };
+    }
+  }
+
+  // Hybrid stop_hook_active handling:
+  // When true, the agent already continued from a previous block.
+  // Check prd.json for pending stories — only block if work remains.
+  if (hookInput.stop_hook_active === true) {
+    const cwd = hookInput.cwd || process.cwd();
+    const pending = await hasPendingStories(cwd);
+
+    if (!pending) {
+      stderr.push(
+        "Loop: stop_hook_active=true, no pending stories. Allowing exit.\n",
+      );
+      state.active = false;
+      await writeStateFn(state);
+      return { exitCode: 0, stdout: "", stderr: stderr.join("") };
+    }
+
+    stderr.push(
+      "Loop: stop_hook_active=true, pending stories found. Continuing.\n",
+    );
+  }
+
+  // Save updated iteration
+  await writeStateFn(state);
+
+  // Build continuation prompt
+  const iterInfo =
+    state.maxIterations > 0
+      ? `${state.currentIteration}/${state.maxIterations}`
+      : `${state.currentIteration}`;
+
+  const reason = [
+    state.prompt,
+    "",
+    "---",
+    `Loop iteration ${iterInfo}. Continue working on the task above.`,
+  ].join("\n");
+
+  const output = { decision: "block", reason };
+
+  if (state.completionPromise) {
+    output.systemMessage = `Loop iteration ${iterInfo} | To stop: output <promise>${state.completionPromise}</promise> (ONLY when TRUE)`;
+  } else {
+    output.systemMessage = `Loop iteration ${iterInfo} | No completion promise — loop runs until max iterations`;
+  }
+
+  return {
+    exitCode: 0,
+    stdout: JSON.stringify(output),
+    stderr: stderr.join(""),
+  };
+}