@graypark/loophaus 2.0.0

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@graypark/loophaus",
+  "version": "2.0.0",
+  "type": "module",
+  "description": "loophaus — Control plane for coding agents. Iterative dev loops with multi-agent orchestration.",
+  "license": "MIT",
+  "author": "graypark",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vcz-Gray/loophaus"
+  },
+  "homepage": "https://github.com/vcz-Gray/loophaus#readme",
+  "bugs": {
+    "url": "https://github.com/vcz-Gray/loophaus/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "loophaus": "./bin/loophaus.mjs"
+  },
+  "files": [
+    "bin/",
+    "hooks/",
+    "commands/",
+    "codex/",
+    "core/",
+    "store/",
+    "platforms/",
+    "scripts/",
+    "lib/",
+    "skills/",
+    ".claude-plugin/",
+    "README.md",
+    "README.ko.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "postinstall": "echo 'Run: npx loophaus --help'"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "loophaus",
+    "loop",
+    "ai-agent",
+    "iterative-development",
+    "stop-hook",
+    "control-plane",
+    "coding-agents"
+  ],
+  "devDependencies": {
+    "vitest": "^4.1.0"
+  }
+}

package/platforms/claude-code/adapter.mjs

@@ -0,0 +1,20 @@
+// platforms/claude-code/adapter.mjs
+
+export const name = "claude-code";
+export const platform = "claude-code";
+
+export function parseInput(raw) {
+  const input = typeof raw === "string" ? JSON.parse(raw) : raw;
+  return {
+    session_id: input.session_id || "",
+    transcript_path: input.transcript_path || null,
+    cwd: input.cwd || process.cwd(),
+    stop_hook_active: input.stop_hook_active || false,
+    last_assistant_message: input.last_assistant_message || "",
+  };
+}
+
+export function renderOutput(result) {
+  if (result.output) return JSON.stringify(result.output);
+  return "";
+}

package/platforms/claude-code/installer.mjs

@@ -0,0 +1,165 @@
+// platforms/claude-code/installer.mjs
+import { readFile, writeFile, mkdir, cp, access, chmod } from "node:fs/promises";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  getClaudeHome,
+  getClaudePluginsDir,
+  getClaudePluginCacheDir,
+  getClaudeSettingsPath,
+  getClaudeInstalledPluginsPath,
+  getPackageVersion,
+} from "../../lib/paths.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const PROJECT_ROOT = resolve(dirname(__filename), "../..");
+
+async function fileExists(p) {
+  try { await access(p); return true; } catch { return false; }
+}
+
+export async function detect() {
+  return fileExists(join(getClaudeHome(), "settings.json")) || fileExists(getClaudeHome());
+}
+
+export async function install({ dryRun = false, force = false } = {}) {
+  const MARKETPLACE_NAME = "loophaus-marketplace";
+  const PLUGIN_KEY = `loophaus@${MARKETPLACE_NAME}`;
+  const GITHUB_REPO = "vcz-Gray/loophaus";
+  const version = getPackageVersion();
+  const cacheDir = getClaudePluginCacheDir();
+  const pluginsDir = getClaudePluginsDir();
+  const marketplaceDir = join(pluginsDir, "marketplaces", MARKETPLACE_NAME);
+
+  console.log("");
+  console.log(`loophaus installer — Claude Code${dryRun ? " (DRY RUN)" : ""}`);
+  console.log(`Version: ${version}`);
+  console.log(`Target: ${cacheDir}`);
+  console.log("");
+
+  if (!force && await fileExists(cacheDir)) {
+    if (dryRun) {
+      console.log("  ! Existing installation found (would prompt for --force)");
+    } else {
+      console.log("  ! Existing installation found. Use --force to overwrite.");
+      return false;
+    }
+  }
+
+  // Step 1: Copy plugin files
+  console.log("[1/4] Copying plugin files...");
+  const dirs = [".claude-plugin", "commands", "hooks", "scripts", "skills", "lib", "core", "store"];
+  for (const dir of dirs) {
+    const src = join(PROJECT_ROOT, dir);
+    if (!(await fileExists(src))) continue;
+    const dest = join(cacheDir, dir);
+    console.log(`  > Copy ${dir}/ -> ${dest}`);
+    if (!dryRun) {
+      await mkdir(dest, { recursive: true });
+      await cp(src, dest, { recursive: true });
+    }
+  }
+
+  for (const file of ["package.json", "LICENSE", "README.md"]) {
+    const src = join(PROJECT_ROOT, file);
+    if (await fileExists(src)) {
+      console.log(`  > Copy ${file}`);
+      if (!dryRun) await cp(src, join(cacheDir, file));
+    }
+  }
+
+  if (!dryRun) {
+    const sh = join(cacheDir, "scripts", "setup-ralph-loop.sh");
+    if (await fileExists(sh)) await chmod(sh, 0o755);
+  }
+
+  // Step 2: Register marketplace
+  console.log("[2/4] Registering marketplace...");
+  const knownPath = join(pluginsDir, "known_marketplaces.json");
+  let known = {};
+  if (await fileExists(knownPath)) {
+    try { known = JSON.parse(await readFile(knownPath, "utf-8")); } catch {}
+  }
+  known[MARKETPLACE_NAME] = {
+    source: { source: "github", repo: GITHUB_REPO },
+    installLocation: marketplaceDir,
+    lastUpdated: new Date().toISOString(),
+  };
+  if (!dryRun) await writeFile(knownPath, JSON.stringify(known, null, 2), "utf-8");
+
+  const mpDir = join(marketplaceDir, ".claude-plugin");
+  if (!dryRun) {
+    await mkdir(mpDir, { recursive: true });
+    await writeFile(join(mpDir, "marketplace.json"), JSON.stringify({
+      name: MARKETPLACE_NAME,
+      owner: { name: "graypark" },
+      metadata: { description: "loophaus — Control plane for coding agents", version },
+      plugins: [{
+        name: "loophaus",
+        source: "./",
+        description: "Iterative dev loops with stop hooks",
+        version,
+        keywords: ["loophaus", "loop", "control-plane"],
+        category: "productivity",
+        skills: "./skills/",
+      }],
+    }, null, 2), "utf-8");
+    await cp(
+      join(PROJECT_ROOT, ".claude-plugin", "plugin.json"),
+      join(mpDir, "plugin.json"),
+    );
+  }
+
+  // Step 3: installed_plugins.json
+  console.log("[3/4] Registering plugin...");
+  const ipPath = getClaudeInstalledPluginsPath();
+  let ip = { version: 2, plugins: {} };
+  if (await fileExists(ipPath)) {
+    try { ip = JSON.parse(await readFile(ipPath, "utf-8")); } catch {}
+  }
+  delete ip.plugins["ralph-codex@ralph-codex"];
+  delete ip.plugins["ralph-codex@ralph-codex-marketplace"];
+  ip.plugins[PLUGIN_KEY] = [{
+    scope: "user",
+    installPath: cacheDir,
+    version,
+    installedAt: new Date().toISOString(),
+    lastUpdated: new Date().toISOString(),
+  }];
+  if (!dryRun) await writeFile(ipPath, JSON.stringify(ip, null, 2), "utf-8");
+
+  // Step 4: settings.json
+  console.log("[4/4] Enabling plugin...");
+  const settingsPath = getClaudeSettingsPath();
+  let settings = {};
+  if (await fileExists(settingsPath)) {
+    try { settings = JSON.parse(await readFile(settingsPath, "utf-8")); } catch {}
+  }
+  if (!settings.enabledPlugins) settings.enabledPlugins = {};
+  delete settings.enabledPlugins["ralph-codex@ralph-codex"];
+  delete settings.enabledPlugins["ralph-codex@ralph-codex-marketplace"];
+  settings.enabledPlugins[PLUGIN_KEY] = true;
+  if (!settings.extraKnownMarketplaces) settings.extraKnownMarketplaces = {};
+  settings.extraKnownMarketplaces[MARKETPLACE_NAME] = {
+    source: { source: "github", repo: GITHUB_REPO },
+  };
+  if (!dryRun) await writeFile(settingsPath, JSON.stringify(settings, null, 2), "utf-8");
+
+  console.log("");
+  if (dryRun) {
+    console.log("  \u2714 Dry run complete.");
+  } else {
+    console.log("  \u2714 loophaus installed for Claude Code!");
+    console.log("");
+    console.log("  Run /reload-plugins in Claude Code to activate.");
+    console.log("  Commands: /loop, /loop-plan, /loop-stop, /loop-pulse");
+    console.log("  To uninstall: npx @graypark/loophaus uninstall --claude");
+  }
+  console.log("");
+  return true;
+}
+
+export async function uninstall({ dryRun = false } = {}) {
+  const { uninstall: doUninstall } = await import("../../bin/uninstall.mjs");
+  return doUninstall({ dryRun, claude: true });
+}

package/platforms/codex-cli/adapter.mjs

@@ -0,0 +1,20 @@
+// platforms/codex-cli/adapter.mjs
+
+export const name = "codex-cli";
+export const platform = "codex-cli";
+
+export function parseInput(raw) {
+  const input = typeof raw === "string" ? JSON.parse(raw) : raw;
+  return {
+    session_id: input.session_id || "",
+    transcript_path: input.transcript_path || null,
+    cwd: input.cwd || process.cwd(),
+    stop_hook_active: input.stop_hook_active || false,
+    last_assistant_message: input.last_assistant_message || "",
+  };
+}
+
+export function renderOutput(result) {
+  if (result.output) return JSON.stringify(result.output);
+  return "";
+}

package/platforms/codex-cli/installer.mjs

@@ -0,0 +1,131 @@
+// platforms/codex-cli/installer.mjs
+import { readFile, writeFile, mkdir, cp, access } from "node:fs/promises";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  getCodexHome,
+  getHooksJsonPath,
+  getPluginInstallDir,
+  getSkillsDir,
+} from "../../lib/paths.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const PROJECT_ROOT = resolve(dirname(__filename), "../..");
+
+async function fileExists(p) {
+  try { await access(p); return true; } catch { return false; }
+}
+
+export async function detect() {
+  return fileExists(getCodexHome());
+}
+
+export async function install({ dryRun = false, force = false, local = false } = {}) {
+  const pluginDir = local
+    ? join(process.cwd(), ".codex", "plugins", "loophaus")
+    : getPluginInstallDir();
+  const hooksJsonPath = local
+    ? join(process.cwd(), ".codex", "hooks.json")
+    : getHooksJsonPath();
+  const skillsDir = local
+    ? join(process.cwd(), ".codex", "skills")
+    : getSkillsDir();
+
+  console.log("");
+  console.log(`loophaus installer — Codex CLI${dryRun ? " (DRY RUN)" : ""}`);
+  console.log(`Mode: ${local ? "local (.codex/)" : "global (~/.codex/)"}`);
+  console.log(`Target: ${pluginDir}`);
+  console.log("");
+
+  if (!force && await fileExists(pluginDir)) {
+    if (dryRun) {
+      console.log("  ! Existing installation found (would prompt for --force)");
+    } else {
+      console.log("  ! Existing installation found. Use --force to overwrite.");
+      return false;
+    }
+  }
+
+  // Step 1: Copy files
+  console.log("[1/3] Copying plugin files...");
+  for (const dir of ["hooks", "codex/commands", "lib", "core", "store"]) {
+    const src = join(PROJECT_ROOT, dir);
+    if (!(await fileExists(src))) continue;
+    const destDir = dir === "codex/commands" ? "commands" : dir;
+    const dest = join(pluginDir, destDir);
+    console.log(`  > Copy ${dir}/ -> ${dest}`);
+    if (!dryRun) {
+      await mkdir(dest, { recursive: true });
+      await cp(src, dest, { recursive: true });
+    }
+  }
+  if (!dryRun) await cp(join(PROJECT_ROOT, "package.json"), join(pluginDir, "package.json"));
+
+  // Step 2: Hooks
+  console.log("[2/3] Configuring Stop hook...");
+  const stopCmd = `node "${join(pluginDir, "hooks", "stop-hook.mjs")}"`;
+  let existing = { hooks: {} };
+  if (await fileExists(hooksJsonPath)) {
+    try { existing = JSON.parse(await readFile(hooksJsonPath, "utf-8")); } catch { existing = { hooks: {} }; }
+  }
+  if (!existing.hooks) existing.hooks = {};
+  if (!Array.isArray(existing.hooks.Stop)) existing.hooks.Stop = [];
+  existing.hooks.Stop = existing.hooks.Stop.filter(e =>
+    !(e.hooks || []).some(h => h.command && h.command.includes("loophaus"))
+  );
+  existing.hooks.Stop.push({ hooks: [{ type: "command", command: stopCmd, timeout: 30 }] });
+  if (!dryRun) {
+    await mkdir(dirname(hooksJsonPath), { recursive: true });
+    await writeFile(hooksJsonPath, JSON.stringify(existing, null, 2), "utf-8");
+  }
+
+  // Step 3: Skills
+  console.log("[3/3] Installing skills...");
+  for (const name of ["ralph-loop", "cancel-ralph"]) {
+    const skillDir = join(skillsDir, name);
+    const src = name === "ralph-loop" ? "codex/commands/ralph-loop.md" : "codex/commands/cancel-ralph.md";
+    console.log(`  > Install skill: ${name}`);
+    if (!dryRun) {
+      await mkdir(skillDir, { recursive: true });
+      const srcPath = join(PROJECT_ROOT, src);
+      if (await fileExists(srcPath)) {
+        const content = await readFile(srcPath, "utf-8");
+        await writeFile(
+          join(skillDir, "SKILL.md"),
+          content.replaceAll("${RALPH_CODEX_ROOT}", pluginDir).replaceAll("${LOOPHAUS_ROOT}", pluginDir),
+          "utf-8",
+        );
+      }
+    }
+  }
+
+  const standaloneSkills = [
+    "ralph-interview",
+    "ralph-orchestrator",
+    "ralph-claude-interview",
+    "ralph-claude-loop",
+    "ralph-claude-cancel",
+    "ralph-claude-orchestrator",
+  ];
+  for (const sk of standaloneSkills) {
+    const srcDir = join(PROJECT_ROOT, "skills", sk);
+    if (await fileExists(srcDir)) {
+      console.log(`  > Install skill: ${sk}`);
+      if (!dryRun) {
+        await mkdir(join(skillsDir, sk), { recursive: true });
+        await cp(srcDir, join(skillsDir, sk), { recursive: true });
+      }
+    }
+  }
+
+  console.log("");
+  if (dryRun) {
+    console.log("  \u2714 Dry run complete. No files were modified.");
+  } else {
+    console.log("  \u2714 loophaus installed for Codex CLI!");
+    console.log("  Commands: /loop, /loop-plan, /loop-stop, /loop-pulse");
+    console.log(`  To uninstall: npx @graypark/loophaus uninstall${local ? " --local" : ""}`);
+  }
+  console.log("");
+  return true;
+}

package/platforms/kiro-cli/adapter.mjs

@@ -0,0 +1,21 @@
+// platforms/kiro-cli/adapter.mjs
+
+export const name = "kiro-cli";
+export const platform = "kiro-cli";
+
+export function parseInput(raw) {
+  const input = typeof raw === "string" ? JSON.parse(raw) : raw;
+  return {
+    session_id: input.session_id || "",
+    transcript_path: input.transcript_path || null,
+    cwd: input.cwd || process.cwd(),
+    stop_hook_active: input.stop_hook_active || false,
+    last_assistant_message: input.last_assistant_message || "",
+    hook_event_name: input.hook_event_name || "stop",
+  };
+}
+
+export function renderOutput(result) {
+  if (result.output) return JSON.stringify(result.output);
+  return "";
+}

package/platforms/kiro-cli/installer.mjs

@@ -0,0 +1,115 @@
+// platforms/kiro-cli/installer.mjs
+import { readFile, writeFile, mkdir, cp, access, rm } from "node:fs/promises";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+
+const __filename = fileURLToPath(import.meta.url);
+const PROJECT_ROOT = resolve(dirname(__filename), "../..");
+
+function getKiroHome() {
+  return join(homedir(), ".kiro");
+}
+
+async function fileExists(p) {
+  try { await access(p); return true; } catch { return false; }
+}
+
+export async function detect() {
+  return fileExists(getKiroHome());
+}
+
+export async function install({ dryRun = false, force = false } = {}) {
+  const kiroHome = getKiroHome();
+  const agentsDir = join(kiroHome, "agents");
+  const steeringDir = join(kiroHome, "steering");
+
+  console.log("");
+  console.log(`loophaus installer — Kiro CLI${dryRun ? " (DRY RUN)" : ""}`);
+  console.log(`Target: ${kiroHome}`);
+  console.log("");
+
+  // Step 1: Create agent config with stop hook
+  console.log("[1/2] Configuring agent with stop hook...");
+  const agentConfig = {
+    name: "loophaus",
+    description: "loophaus — iterative dev loop agent",
+    hooks: {
+      stop: [{ command: `node "${join(PROJECT_ROOT, "hooks", "stop-hook.mjs")}"` }],
+    },
+  };
+
+  const agentPath = join(agentsDir, "loophaus.json");
+  if (!force && await fileExists(agentPath)) {
+    if (dryRun) {
+      console.log("  ! Existing agent config found (would prompt for --force)");
+    } else {
+      console.log("  ! Existing agent config found. Use --force to overwrite.");
+      return false;
+    }
+  }
+
+  console.log(`  > Write ${agentPath}`);
+  if (!dryRun) {
+    await mkdir(agentsDir, { recursive: true });
+    await writeFile(agentPath, JSON.stringify(agentConfig, null, 2), "utf-8");
+  }
+
+  // Step 2: Copy steering files
+  console.log("[2/2] Installing steering files...");
+  const commands = [
+    { src: "commands/loop.md", dest: "loop.md" },
+    { src: "commands/loop-plan.md", dest: "loop-plan.md" },
+    { src: "commands/loop-stop.md", dest: "loop-stop.md" },
+    { src: "commands/loop-pulse.md", dest: "loop-pulse.md" },
+  ];
+  for (const { src, dest } of commands) {
+    const srcPath = join(PROJECT_ROOT, src);
+    if (await fileExists(srcPath)) {
+      const destPath = join(steeringDir, dest);
+      console.log(`  > Copy ${src} -> ${destPath}`);
+      if (!dryRun) {
+        await mkdir(steeringDir, { recursive: true });
+        await cp(srcPath, destPath);
+      }
+    }
+  }
+
+  console.log("");
+  if (dryRun) {
+    console.log("  \u2714 Dry run complete. No files were modified.");
+  } else {
+    console.log("  \u2714 loophaus installed for Kiro CLI!");
+    console.log("  Commands: /loop, /loop-plan, /loop-stop, /loop-pulse");
+    console.log("  To uninstall: npx @graypark/loophaus uninstall --kiro");
+  }
+  console.log("");
+  return true;
+}
+
+export async function uninstall({ dryRun = false } = {}) {
+  const kiroHome = getKiroHome();
+
+  const targets = [
+    join(kiroHome, "agents", "loophaus.json"),
+    join(kiroHome, "steering", "loop.md"),
+    join(kiroHome, "steering", "loop-plan.md"),
+    join(kiroHome, "steering", "loop-stop.md"),
+    join(kiroHome, "steering", "loop-pulse.md"),
+  ];
+
+  console.log("");
+  console.log(`loophaus uninstaller — Kiro CLI${dryRun ? " (DRY RUN)" : ""}`);
+  console.log("");
+
+  for (const p of targets) {
+    if (await fileExists(p)) {
+      console.log(`  > Remove ${p}`);
+      if (!dryRun) await rm(p);
+    }
+  }
+
+  console.log("");
+  console.log("  \u2714 loophaus removed from Kiro CLI.");
+  console.log("");
+}

package/scripts/setup-ralph-loop.sh

@@ -0,0 +1,145 @@
+#!/bin/bash
+
+# loophaus Setup Script
+# Creates state file for in-session loop
+
+set -euo pipefail
+
+# Parse arguments
+PROMPT_PARTS=()
+MAX_ITERATIONS=0
+COMPLETION_PROMISE="null"
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    -h|--help)
+      cat << 'HELP_EOF'
+loophaus — Iterative coding loop
+
+USAGE:
+  /loop [PROMPT...] [OPTIONS]
+
+ARGUMENTS:
+  PROMPT...    Initial prompt to start the loop (can be multiple words without quotes)
+
+OPTIONS:
+  --max-iterations <n>           Maximum iterations before auto-stop (default: unlimited)
+  --completion-promise '<text>'  Promise phrase (USE QUOTES for multi-word)
+  -h, --help                     Show this help message
+
+DESCRIPTION:
+  Starts a loop in your CURRENT session. The stop hook prevents
+  exit and feeds your output back as input until completion or iteration limit.
+
+  To signal completion, you must output: <promise>YOUR_PHRASE</promise>
+
+EXAMPLES:
+  /loop Build a todo API --completion-promise 'DONE' --max-iterations 20
+  /loop --max-iterations 10 Fix the auth bug
+  /loop Refactor cache layer  (runs forever)
+
+STOPPING:
+  Only by reaching --max-iterations or detecting --completion-promise
+  To cancel manually: /loop-stop
+
+MONITORING:
+  cat .loophaus/state.json
+HELP_EOF
+      exit 0
+      ;;
+    --max-iterations)
+      if [[ -z "${2:-}" ]]; then
+        echo "❌ Error: --max-iterations requires a number argument" >&2
+        exit 1
+      fi
+      if ! [[ "$2" =~ ^[0-9]+$ ]]; then
+        echo "❌ Error: --max-iterations must be a positive integer or 0, got: $2" >&2
+        exit 1
+      fi
+      MAX_ITERATIONS="$2"
+      shift 2
+      ;;
+    --completion-promise)
+      if [[ -z "${2:-}" ]]; then
+        echo "❌ Error: --completion-promise requires a text argument" >&2
+        exit 1
+      fi
+      COMPLETION_PROMISE="$2"
+      shift 2
+      ;;
+    *)
+      PROMPT_PARTS+=("$1")
+      shift
+      ;;
+  esac
+done
+
+PROMPT="${PROMPT_PARTS[*]:-}"
+
+if [[ -z "$PROMPT" ]]; then
+  echo "❌ Error: No prompt provided" >&2
+  echo "" >&2
+  echo "   Examples:" >&2
+  echo "     /loop Build a REST API for todos" >&2
+  echo "     /loop Fix the auth bug --max-iterations 20" >&2
+  echo "     /loop --completion-promise 'DONE' Refactor code" >&2
+  exit 1
+fi
+
+# Create state file
+mkdir -p .loophaus
+
+if [[ -n "$COMPLETION_PROMISE" ]] && [[ "$COMPLETION_PROMISE" != "null" ]]; then
+  COMPLETION_PROMISE_YAML="\"$COMPLETION_PROMISE\""
+else
+  COMPLETION_PROMISE_YAML="null"
+fi
+
+cat > .loophaus/loop.local.md <<EOF
+---
+active: true
+iteration: 1
+session_id: ${CLAUDE_CODE_SESSION_ID:-}
+max_iterations: $MAX_ITERATIONS
+completion_promise: $COMPLETION_PROMISE_YAML
+started_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+---
+
+$PROMPT
+EOF
+
+# Output setup message
+cat <<EOF
+🔄 Loop activated!
+
+Iteration: 1
+Max iterations: $(if [[ $MAX_ITERATIONS -gt 0 ]]; then echo $MAX_ITERATIONS; else echo "unlimited"; fi)
+Completion promise: $(if [[ "$COMPLETION_PROMISE" != "null" ]]; then echo "${COMPLETION_PROMISE//\"/} (ONLY output when TRUE)"; else echo "none (runs forever)"; fi)
+
+The stop hook is now active. When you try to exit, the SAME PROMPT will be
+fed back to you. Your previous work persists in files and git history.
+
+To cancel: /loop-stop
+To monitor: cat .loophaus/loop.local.md
+EOF
+
+if [[ -n "$PROMPT" ]]; then
+  echo ""
+  echo "$PROMPT"
+fi
+
+if [[ "$COMPLETION_PROMISE" != "null" ]]; then
+  echo ""
+  echo "═══════════════════════════════════════════════════════════"
+  echo "CRITICAL — Loop Completion Promise"
+  echo "═══════════════════════════════════════════════════════════"
+  echo ""
+  echo "To complete this loop, output this EXACT text:"
+  echo "  <promise>$COMPLETION_PROMISE</promise>"
+  echo ""
+  echo "STRICT REQUIREMENTS:"
+  echo "  ✓ Use <promise> XML tags EXACTLY as shown"
+  echo "  ✓ The statement MUST be completely TRUE"
+  echo "  ✓ Do NOT output false promises to exit the loop"
+  echo "═══════════════════════════════════════════════════════════"
+fi