qualia-framework 6.2.7 → 6.2.10

package/bin/install.js

@@ -4,6 +4,8 @@ const { createInterface } = require("readline");
 const path = require("path");
 const fs = require("fs");
 const ui = require("./qualia-ui.js");
+const { RUNTIME_BIN_SCRIPTS, binFiles } = require("./runtime-manifest.js");
+const { renderText } = require("./host-adapters.js");
 
 // ─── Colors (kept for legacy log lines; new sections route through qualia-ui) ─
 const TEAL = "\x1b[38;2;0;206;209m";
@@ -24,6 +26,24 @@ const TARGET_CLAUDE_ONLY = "1";
 const TARGET_CODEX_ONLY = "2";
 const TARGET_BOTH = "3";
 
+const CODEX_STATUS_LINE = [
+  "model-with-reasoning",
+  "task-progress",
+  "current-dir",
+  "git-branch",
+  "context-used",
+  "five-hour-limit",
+  "weekly-limit",
+];
+
+const CODEX_STATUS_LINE_BLOCK = [
+  "# Added by qualia-framework — Codex native bottom status line.",
+  "[tui]",
+  `status_line = ${JSON.stringify(CODEX_STATUS_LINE)}`,
+  "status_line_use_colors = true",
+  "",
+].join("\n");
+
 // Total install timer — set in main(), read by the final summary card.
 const installStart = Date.now();
 
@@ -125,14 +145,8 @@ function copyTree(src, dest) {
   }
 }
 
-function codexText(content) {
-  return String(content)
-    .replaceAll("~/.claude/", "~/.codex/")
-    .replaceAll("$HOME/.claude/", "$HOME/.codex/")
-    .replaceAll("${HOME}/.claude/", "${HOME}/.codex/")
-    .replaceAll("@~/.claude/", "@~/.codex/")
-    .replaceAll(".claude/", ".codex/");
-}
+const claudeText = (content) => renderText(content, "claude");
+const codexText = (content) => renderText(content, "codex");
 
 function copyTextTransform(src, dest, transform) {
   const destDir = path.dirname(dest);
@@ -156,6 +170,45 @@ function copyTreeTransform(src, dest, transform) {
   }
 }
 
+function ensureCodexStatusLineConfig(existing) {
+  const statusLine = `status_line = ${JSON.stringify(CODEX_STATUS_LINE)}`;
+  const colors = "status_line_use_colors = true";
+  if (!existing || !existing.trim()) {
+    return [
+      "# Created by qualia-framework install.",
+      "# User settings can be added normally; Qualia runtime lives in AGENTS.md, hooks.json, agents/, and bin/.",
+      "",
+      "[features]",
+      "hooks = true",
+      "plugin_hooks = true",
+      "",
+      "# Codex's native status line is rendered at the bottom of the TUI.",
+      "# It supports a fixed list of built-in segment names. Custom command-backed",
+      "# status lines are not supported in Codex 0.133, so Qualia phase/project",
+      "# context is rendered by the SessionStart banner while the native bottom",
+      "# line keeps model, task, directory, git, context, and limit state visible.",
+      CODEX_STATUS_LINE_BLOCK,
+    ].join("\n");
+  }
+
+  let next = existing;
+  if (!/^\[tui\]\s*$/m.test(next)) {
+    return `${next.replace(/\s*$/, "\n\n")}${CODEX_STATUS_LINE_BLOCK}`;
+  }
+
+  const tuiMatch = next.match(/^\[tui\]\s*$(?:\n(?!\[)[^\n]*)*/m);
+  if (!tuiMatch) return `${next.replace(/\s*$/, "\n\n")}${CODEX_STATUS_LINE_BLOCK}`;
+
+  let tuiBlock = tuiMatch[0];
+  if (!/^\s*status_line\s*=/m.test(tuiBlock)) {
+    tuiBlock = tuiBlock.replace(/^\[tui\]\s*$/m, `[tui]\n${statusLine}`);
+  }
+  if (!/^\s*status_line_use_colors\s*=/m.test(tuiBlock)) {
+    tuiBlock = `${tuiBlock.replace(/\s*$/, "")}\n${colors}`;
+  }
+  return `${next.slice(0, tuiMatch.index)}${tuiBlock}${next.slice(tuiMatch.index + tuiMatch[0].length)}`;
+}
+
 function backupIfDifferent(dest, nextContent, label) {
   if (!fs.existsSync(dest)) return false;
   try {
@@ -205,19 +258,46 @@ function parseAgentMarkdown(content) {
   return result;
 }
 
-function renderCodexAgentToml(markdown) {
+function renderCodexAgentToml(markdown, filenameFallback) {
   const parsed = parseAgentMarkdown(markdown);
-  const body = parsed.body
-    .replaceAll("~/.claude/", "~/.codex/")
-    .replaceAll("@~/.claude/", "@~/.codex/");
+  const body = codexText(parsed.body);
+  const name = (parsed.name || filenameFallback || "").replace(/^qualia-/, "");
   const description = parsed.description || "Qualia Framework specialist agent.";
   return [
+    `name = ${tomlString(name)}`,
     `description = ${tomlString(description)}`,
     `developer_instructions = ${tomlString(body)}`,
     "",
   ].join("\n");
 }
 
+// Skills removed in past versions but still present in older installs.
+// Pruned from BOTH ~/.claude/skills/ and ~/.codex/skills/ on every install run
+// so the active surface matches what the framework currently ships.
+const DEPRECATED_SKILLS = [
+  "qualia-task",         // v5.7.0 — folded into qualia-feature
+  "qualia-quick",        // v5.7.0 — folded into qualia-feature
+  "qualia-polish-loop",  // v5.8.0 — folded into qualia-polish --loop
+  "qualia-design",       // v4 wave 2 — folded into scope-adaptive qualia-polish
+  "qualia-prd",          // v5.8.0 — surface cleanup
+];
+
+function pruneDeprecatedSkills(baseDir) {
+  const skillsDir = path.join(baseDir, "skills");
+  if (!fs.existsSync(skillsDir)) return [];
+  const removed = [];
+  for (const name of DEPRECATED_SKILLS) {
+    const target = path.join(skillsDir, name);
+    try {
+      if (fs.existsSync(target)) {
+        fs.rmSync(target, { recursive: true, force: true });
+        removed.push(name);
+      }
+    } catch {}
+  }
+  return removed;
+}
+
 // Surgically remove orphaned v2.6 install cruft from ~/.claude/ on upgrade.
 // v2.6 installed a separate ~/.claude/qualia-framework/ directory with workflows/,
 // references/, assets/, bin/qualia-tools.js. v3 doesn't use any of that — it was
@@ -474,16 +554,19 @@ async function main() {
     .filter((d) => fs.statSync(path.join(skillsDir, d)).isDirectory());
 
   printSection("Skills");
+  const claudePruned = pruneDeprecatedSkills(CLAUDE_DIR);
+  for (const name of claudePruned) ok(`pruned deprecated: ${name}`);
   for (const skill of skills) {
     try {
-      copy(
+      copyTextTransform(
         path.join(skillsDir, skill, "SKILL.md"),
-        path.join(CLAUDE_DIR, "skills", skill, "SKILL.md")
+        path.join(CLAUDE_DIR, "skills", skill, "SKILL.md"),
+        claudeText
       );
       // Copy REFERENCE.md if the skill has one (progressive-disclosure pattern)
       const refSrc = path.join(skillsDir, skill, "REFERENCE.md");
       if (fs.existsSync(refSrc)) {
-        copy(refSrc, path.join(CLAUDE_DIR, "skills", skill, "REFERENCE.md"));
+        copyTextTransform(refSrc, path.join(CLAUDE_DIR, "skills", skill, "REFERENCE.md"), claudeText);
       }
       // v5.1: Copy scripts/ subfolder if present (e.g. qualia-polish ships
       // playwright-capture.mjs, loop.mjs, score.mjs that the --loop mode
@@ -506,7 +589,7 @@ async function main() {
   const agentsDir = path.join(FRAMEWORK_DIR, "agents");
   for (const file of fs.readdirSync(agentsDir)) {
     try {
-      copy(path.join(agentsDir, file), path.join(CLAUDE_DIR, "agents", file));
+      copyTextTransform(path.join(agentsDir, file), path.join(CLAUDE_DIR, "agents", file), claudeText);
       ok(file);
     } catch (e) {
       warn(`${file} — ${e.message}`);
@@ -518,7 +601,7 @@ async function main() {
   const rulesDir = path.join(FRAMEWORK_DIR, "rules");
   for (const file of fs.readdirSync(rulesDir)) {
     try {
-      copy(path.join(rulesDir, file), path.join(CLAUDE_DIR, "rules", file));
+      copyTextTransform(path.join(rulesDir, file), path.join(CLAUDE_DIR, "rules", file), claudeText);
       ok(file);
     } catch (e) {
       warn(`${file} — ${e.message}`);
@@ -559,7 +642,7 @@ async function main() {
   if (fs.existsSync(designDir)) {
     for (const file of fs.readdirSync(designDir)) {
       try {
-        copy(path.join(designDir, file), path.join(designDest, file));
+        copyTextTransform(path.join(designDir, file), path.join(designDest, file), claudeText);
         ok(file);
       } catch (e) {
         warn(`${file} — ${e.message}`);
@@ -620,10 +703,10 @@ async function main() {
     const destPath = path.join(tmplDest, entry.name);
     try {
       if (entry.isDirectory()) {
-        copyTree(srcPath, destPath);
+        copyTreeTransform(srcPath, destPath, claudeText);
         ok(`${entry.name}/ (directory)`);
       } else {
-        copy(srcPath, destPath);
+        copyTextTransform(srcPath, destPath, claudeText);
         ok(entry.name);
       }
     } catch (e) {
@@ -654,7 +737,7 @@ async function main() {
         if (fs.existsSync(dest)) {
           log(`${DIM}${file} (kept — user has customized)${RESET}`);
         } else {
-          copy(src, dest);
+          copyTextTransform(src, dest, claudeText);
           ok(`${file} (initialized)`);
         }
       } catch (e) {
@@ -671,7 +754,7 @@ async function main() {
     if (!fs.existsSync(refDest)) fs.mkdirSync(refDest, { recursive: true });
     for (const file of fs.readdirSync(refDir)) {
       try {
-        copy(path.join(refDir, file), path.join(refDest, file));
+        copyTextTransform(path.join(refDir, file), path.join(refDest, file), claudeText);
         ok(file);
       } catch (e) {
         warn(`${file} — ${e.message}`);
@@ -710,7 +793,7 @@ async function main() {
         try { fs.copyFileSync(claudeDest, bak); ok(`Backed up existing CLAUDE.md → ${path.basename(bak)}`); } catch {}
       }
     }
-    fs.writeFileSync(claudeDest, claudeMd, "utf8");
+    fs.writeFileSync(claudeDest, claudeText(claudeMd), "utf8");
     ok(`Configured as ${member.role}`);
   } catch (e) {
     warn(`CLAUDE.md — ${e.message}`);
@@ -721,78 +804,23 @@ async function main() {
   try {
     const binDest = path.join(CLAUDE_DIR, "bin");
     if (!fs.existsSync(binDest)) fs.mkdirSync(binDest, { recursive: true });
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "state.js"),
-      path.join(binDest, "state.js")
-    );
-    ok("state.js (state machine)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "qualia-ui.js"),
-      path.join(binDest, "qualia-ui.js")
-    );
-    fs.chmodSync(path.join(binDest, "qualia-ui.js"), 0o755);
-    ok("qualia-ui.js (cosmetics library)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "statusline.js"),
-      path.join(binDest, "statusline.js")
-    );
-    ok("statusline.js (status bar renderer)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "knowledge.js"),
-      path.join(binDest, "knowledge.js")
-    );
-    fs.chmodSync(path.join(binDest, "knowledge.js"), 0o755);
-    ok("knowledge.js (memory-layer loader)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "knowledge-flush.js"),
-      path.join(binDest, "knowledge-flush.js")
-    );
-    fs.chmodSync(path.join(binDest, "knowledge-flush.js"), 0o755);
-    ok("knowledge-flush.js (cron-runnable flush)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "plan-contract.js"),
-      path.join(binDest, "plan-contract.js")
-    );
-    ok("plan-contract.js (plan JSON validator)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "agent-runs.js"),
-      path.join(binDest, "agent-runs.js")
-    );
-    ok("agent-runs.js (agent telemetry writer)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "slop-detect.mjs"),
-      path.join(binDest, "slop-detect.mjs")
-    );
-    fs.chmodSync(path.join(binDest, "slop-detect.mjs"), 0o755);
-    ok("slop-detect.mjs (anti-pattern scanner — runs pre-commit on frontend builds)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "erp-retry.js"),
-      path.join(binDest, "erp-retry.js")
-    );
-    fs.chmodSync(path.join(binDest, "erp-retry.js"), 0o755);
-    ok("erp-retry.js (ERP report retry queue — drained by session-start hook and erp-flush CLI)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "report-payload.js"),
-      path.join(binDest, "report-payload.js")
-    );
-    fs.chmodSync(path.join(binDest, "report-payload.js"), 0o755);
-    ok("report-payload.js (Framework -> ERP report payload builder)");
-    copy(
-      path.join(FRAMEWORK_DIR, "bin", "project-snapshot.js"),
-      path.join(binDest, "project-snapshot.js")
-    );
-    fs.chmodSync(path.join(binDest, "project-snapshot.js"), 0o755);
-    ok("project-snapshot.js (ERP/admin project progress snapshot)");
+    for (const script of RUNTIME_BIN_SCRIPTS) {
+      const out = path.join(binDest, script.file);
+      copy(path.join(FRAMEWORK_DIR, "bin", script.file), out);
+      try { fs.chmodSync(out, 0o755); } catch {}
+      ok(script.label);
+    }
   } catch (e) {
     warn(`scripts — ${e.message}`);
   }
 
   // ─── Guide ─────────────────────────────────────────────
   try {
-    copy(
-      path.join(FRAMEWORK_DIR, "guide.md"),
-      path.join(CLAUDE_DIR, "qualia-guide.md")
-    );
+      copyTextTransform(
+        path.join(FRAMEWORK_DIR, "guide.md"),
+        path.join(CLAUDE_DIR, "qualia-guide.md"),
+        claudeText
+      );
     ok("guide.md");
   } catch (e) {
     warn(`guide.md — ${e.message}`);
@@ -1011,6 +1039,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     excludeDefault: true,
     tips: [
       "⬢ Lost? Type /qualia for the next step",
+      "⬢ Broken behavior? Use /qualia-fix for root cause, patch, verify",
       "⬢ Single feature? Use /qualia-feature, it auto-scopes",
       "⬢ End of day? /qualia-report submits your shift before clock-out",
       "⬢ Context isolation: every task gets a fresh AI brain",
@@ -1227,6 +1256,7 @@ function printSummary({ member, target, claudeInstalled }) {
   }
   console.log("");
   console.log(`  ${DIM}New project?${RESET}    ${TEAL}/qualia-new${RESET}`);
+  console.log(`  ${DIM}Broken thing?${RESET}  ${TEAL}/qualia-fix${RESET}`);
   console.log(`  ${DIM}Single feature?${RESET} ${TEAL}/qualia-feature${RESET}`);
   console.log(`  ${DIM}End of day?${RESET}     ${TEAL}/qualia-report${RESET} ${DIM}(shift submission)${RESET}`);
   console.log(`  ${DIM}Stuck?${RESET}          ${TEAL}/qualia${RESET}`);
@@ -1304,23 +1334,20 @@ async function installCodex(member, target) {
   }
 
   // Codex treats config.toml as optional, but doctor reports a warning when it
-  // is absent. Create a minimal, parseable file on fresh Codex-only homes and
-  // leave existing user config untouched.
+  // is absent. Keep user settings intact while guaranteeing the native bottom
+  // status line is present.
   try {
     const configToml = path.join(CODEX_DIR, "config.toml");
+    const existing = fs.existsSync(configToml) ? fs.readFileSync(configToml, "utf8") : "";
+    const next = ensureCodexStatusLineConfig(existing);
     if (!fs.existsSync(configToml)) {
-      atomicWrite(configToml, [
-        "# Created by qualia-framework install.",
-        "# User settings can be added normally; Qualia runtime lives in AGENTS.md, hooks.json, agents/, and bin/.",
-        "",
-        "[features]",
-        "hooks = true",
-        "plugin_hooks = true",
-        "",
-      ].join("\n"));
+      atomicWrite(configToml, next);
       ok("config.toml (minimal Codex config)");
+    } else if (next !== existing) {
+      atomicWrite(configToml, next);
+      ok("config.toml (Codex bottom status line)");
     } else {
-      log(`${DIM}config.toml (kept — user has customized)${RESET}`);
+      log(`${DIM}config.toml (kept — Codex status line already wired)${RESET}`);
     }
   } catch (e) {
     warn(`Codex config.toml — ${e.message}`);
@@ -1347,23 +1374,29 @@ async function installCodex(member, target) {
     warn(`Codex config — ${e.message}`);
   }
 
+  // Mirror the ERP API key from Claude → Codex so erp-retry/report-payload can
+  // post from Codex sessions without a separate provisioning step. The key
+  // resolver at runtime looks in $CODEX_DIR/.erp-api-key only; without this
+  // copy, every Codex ERP write 401s and the queue grows silently.
+  try {
+    const claudeKey = path.join(CLAUDE_DIR, ".erp-api-key");
+    const codexKey = path.join(CODEX_DIR, ".erp-api-key");
+    if (fs.existsSync(claudeKey) && !fs.existsSync(codexKey)) {
+      const key = fs.readFileSync(claudeKey, "utf8");
+      atomicWrite(codexKey, key, 0o600);
+      ok(".erp-api-key (mirrored from ~/.claude/)");
+    } else if (fs.existsSync(codexKey)) {
+      log(`${DIM}.erp-api-key (existing — preserved)${RESET}`);
+    }
+  } catch (e) {
+    warn(`Codex .erp-api-key — ${e.message}`);
+  }
+
   // Scripts
   try {
     const binDest = path.join(CODEX_DIR, "bin");
     if (!fs.existsSync(binDest)) fs.mkdirSync(binDest, { recursive: true });
-    const scripts = [
-      "state.js",
-      "qualia-ui.js",
-      "statusline.js",
-      "knowledge.js",
-      "knowledge-flush.js",
-      "plan-contract.js",
-      "agent-runs.js",
-      "slop-detect.mjs",
-      "erp-retry.js",
-      "report-payload.js",
-      "project-snapshot.js",
-    ];
+    const scripts = binFiles();
     for (const script of scripts) {
       const src = path.join(FRAMEWORK_DIR, "bin", script);
       const out = path.join(binDest, script);
@@ -1386,7 +1419,7 @@ async function installCodex(member, target) {
       const parsed = parseAgentMarkdown(source);
       const base = parsed.name ? parsed.name.replace(/^qualia-/, "") : path.basename(file, ".md");
       const out = path.join(agentsDest, `${base}.toml`);
-      const toml = renderCodexAgentToml(source);
+      const toml = renderCodexAgentToml(source, base);
       backupIfDifferent(out, toml, `agents/${base}.toml`);
       atomicWrite(out, toml);
     }
@@ -1401,9 +1434,9 @@ async function installCodex(member, target) {
     const rulesDest = path.join(CODEX_DIR, "rules");
     if (!fs.existsSync(rulesDest)) fs.mkdirSync(rulesDest, { recursive: true });
     for (const file of fs.readdirSync(rulesDir)) {
-      copy(path.join(rulesDir, file), path.join(rulesDest, file));
+      copyTextTransform(path.join(rulesDir, file), path.join(rulesDest, file), codexText);
     }
-    copyTree(path.join(FRAMEWORK_DIR, "qualia-design"), path.join(CODEX_DIR, "qualia-design"));
+    copyTreeTransform(path.join(FRAMEWORK_DIR, "qualia-design"), path.join(CODEX_DIR, "qualia-design"), codexText);
     ok("rules/ + qualia-design/");
   } catch (e) {
     warn(`Codex rules/design — ${e.message}`);
@@ -1415,6 +1448,8 @@ async function installCodex(member, target) {
   try {
     const skillsSrc = path.join(FRAMEWORK_DIR, "skills");
     const skillsDest = path.join(CODEX_DIR, "skills");
+    const codexPruned = pruneDeprecatedSkills(CODEX_DIR);
+    for (const name of codexPruned) ok(`pruned deprecated: ${name}`);
     for (const skill of fs.readdirSync(skillsSrc)) {
       const src = path.join(skillsSrc, skill);
       if (!fs.statSync(src).isDirectory()) continue;
@@ -1471,6 +1506,18 @@ async function installCodex(member, target) {
       try { fs.chmodSync(out, 0o755); } catch {}
     }
     const nodeCmd = (hookFile) => `node "${path.join(hooksDest, hookFile)}"`;
+    // Codex's hook schema does NOT include an `if` field — only `command`,
+    // `commandWindows`, `timeout`, `async`, `statusMessage`. Filtering on
+    // tool_input.command happens inside each hook script (they read stdin
+    // JSON and `process.exit(0)` fast when the command doesn't match).
+    //
+    // Codex prints `statusMessage` for every entry in the matched group BEFORE
+    // running the hook. Including statusMessage on conditional hooks produced
+    // 8 lines of "Running PreToolUse hook: Qualia X..." on every Bash call
+    // even when 6 of the 8 immediately exited 0. We only set statusMessage on
+    // hooks that always do real work (auto-update + git-guardrails). The
+    // conditional hooks stay registered (so they still fire when applicable)
+    // but render silently.
     const qualiaHooks = {
       hooks: {
         SessionStart: [
@@ -1482,18 +1529,18 @@ async function installCodex(member, target) {
             hooks: [
               { type: "command", command: nodeCmd("auto-update.js"), timeout: 5, statusMessage: "Qualia update check..." },
               { type: "command", command: nodeCmd("git-guardrails.js"), timeout: 5, statusMessage: "Qualia git safety..." },
-              { type: "command", if: "Bash(git push*)", command: nodeCmd("branch-guard.js"), timeout: 5, statusMessage: "Qualia branch guard..." },
-              { type: "command", if: "Bash(git push*)", command: nodeCmd("pre-push.js"), timeout: 15, statusMessage: "Qualia tracking stamp..." },
-              { type: "command", if: "Bash(vercel --prod*)", command: nodeCmd("pre-deploy-gate.js"), timeout: 180, statusMessage: "Qualia deploy gate..." },
-              { type: "command", if: "Bash(vercel --prod*)|Bash(vercel deploy*)", command: nodeCmd("vercel-account-guard.js"), timeout: 8, statusMessage: "Qualia Vercel account..." },
-              { type: "command", if: "Bash(vercel env*)", command: nodeCmd("env-empty-guard.js"), timeout: 5, statusMessage: "Qualia env guard..." },
-              { type: "command", if: "Bash(supabase*)|Bash(npx supabase*)", command: nodeCmd("supabase-destructive-guard.js"), timeout: 5, statusMessage: "Qualia Supabase guard..." },
+              { type: "command", command: nodeCmd("branch-guard.js"), timeout: 5 },
+              { type: "command", command: nodeCmd("pre-push.js"), timeout: 15 },
+              { type: "command", command: nodeCmd("pre-deploy-gate.js"), timeout: 180 },
+              { type: "command", command: nodeCmd("vercel-account-guard.js"), timeout: 8 },
+              { type: "command", command: nodeCmd("env-empty-guard.js"), timeout: 5 },
+              { type: "command", command: nodeCmd("supabase-destructive-guard.js"), timeout: 5 },
             ],
           },
           {
             matcher: "Edit|Write",
             hooks: [
-              { type: "command", if: "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)", command: nodeCmd("migration-guard.js"), timeout: 10, statusMessage: "Qualia migration guard..." },
+              { type: "command", command: nodeCmd("migration-guard.js"), timeout: 10 },
             ],
           },
         ],

package/bin/plan-contract.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // Plan contract validator + helpers. See docs/plan-contract.md.
 //
-// Pure library — no CLI dispatch. Required by state.js and by skills that
-// emit/consume `.planning/phase-{N}-contract.json`.
+// Library + tiny CLI. Required by state.js and by skills that emit/consume
+// `.planning/phase-{N}-contract.json`.
 //
 // Zero npm dependencies. Hand-rolled validator, ~100 LOC.
 
@@ -241,11 +241,108 @@ function checkDrift(contractPath, planMdPath) {
   return { ok: true, drift: stored !== current, stored, current };
 }
 
+function readContractFile(contractPath) {
+  if (!fs.existsSync(contractPath)) {
+    return { ok: false, error: "CONTRACT_MISSING", message: `Contract file not found: ${contractPath}` };
+  }
+  const parsed = parseSafely(fs.readFileSync(contractPath, "utf8"));
+  if (!parsed.ok) {
+    return { ok: false, error: "CONTRACT_UNPARSEABLE", message: parsed.error };
+  }
+  return { ok: true, contract: parsed.value };
+}
+
+function cliUsage() {
+  console.error([
+    "Usage:",
+    "  plan-contract.js validate <contract.json> [--json]",
+    "  plan-contract.js drift <contract.json> <plan.md> [--json]",
+    "  plan-contract.js hash <plan.md>",
+  ].join("\n"));
+}
+
+function printResult(payload, asJson) {
+  if (asJson) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  if (payload.ok) {
+    if (payload.action === "validate") console.log(`VALID ${payload.path}`);
+    else if (payload.action === "drift") console.log(payload.drift ? "DRIFT" : "NO_DRIFT");
+    else if (payload.action === "hash") console.log(payload.hash);
+    else console.log("OK");
+    return;
+  }
+  console.error(`${payload.error || "ERROR"}: ${payload.message || (payload.errors || []).join("; ")}`);
+}
+
+function main(argv) {
+  const cmd = argv[2];
+  const asJson = argv.includes("--json");
+  if (!cmd || cmd === "--help" || cmd === "-h") {
+    cliUsage();
+    return 2;
+  }
+
+  if (cmd === "validate") {
+    const contractPath = argv[3];
+    if (!contractPath || contractPath.startsWith("--")) {
+      cliUsage();
+      return 2;
+    }
+    const loaded = readContractFile(contractPath);
+    if (!loaded.ok) {
+      printResult({ ok: false, action: "validate", path: contractPath, ...loaded }, asJson);
+      return 2;
+    }
+    const errors = validate(loaded.contract);
+    const payload = { ok: errors.length === 0, action: "validate", path: contractPath, errors };
+    printResult(payload, asJson);
+    return payload.ok ? 0 : 1;
+  }
+
+  if (cmd === "drift") {
+    const contractPath = argv[3];
+    const planPath = argv[4];
+    if (!contractPath || !planPath || contractPath.startsWith("--") || planPath.startsWith("--")) {
+      cliUsage();
+      return 2;
+    }
+    const result = checkDrift(contractPath, planPath);
+    const payload = { ok: !!result.ok && !result.drift, action: "drift", path: contractPath, plan: planPath, ...result };
+    printResult(payload, asJson);
+    return payload.ok ? 0 : 1;
+  }
+
+  if (cmd === "hash") {
+    const planPath = argv[3];
+    if (!planPath || planPath.startsWith("--")) {
+      cliUsage();
+      return 2;
+    }
+    if (!fs.existsSync(planPath)) {
+      printResult({ ok: false, action: "hash", error: "PLAN_MISSING", message: `Plan file not found: ${planPath}` }, asJson);
+      return 2;
+    }
+    const hash = hashPlan(fs.readFileSync(planPath, "utf8"));
+    printResult({ ok: true, action: "hash", path: planPath, hash }, asJson);
+    return 0;
+  }
+
+  cliUsage();
+  return 2;
+}
+
 module.exports = {
   SCHEMA_VERSION,
   validate,
   parseSafely,
   hashPlan,
   checkDrift,
+  readContractFile,
   findScopeReductionPhrases,
 };
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}