qualia-framework 4.3.0 → 4.5.0

package/bin/cli.js

@@ -29,7 +29,8 @@ function readConfig() {
 
 function writeConfig(cfg) {
   if (!fs.existsSync(CLAUDE_DIR)) fs.mkdirSync(CLAUDE_DIR, { recursive: true });
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2) + "\n");
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
+  try { fs.chmodSync(CONFIG_FILE, 0o600); } catch {}
 }
 
 function banner() {
@@ -159,10 +160,15 @@ const QUALIA_AGENT_FILES = [
 ];
 
 // 3 Qualia bin scripts.
-const QUALIA_BIN_FILES = ["state.js", "qualia-ui.js", "statusline.js", "knowledge.js", "knowledge-flush.js"];
-
-// 5 Qualia rules.
-const QUALIA_RULE_FILES = ["security.md", "frontend.md", "design-reference.md", "deployment.md", "infrastructure.md"];
+const QUALIA_BIN_FILES = ["state.js", "qualia-ui.js", "statusline.js", "knowledge.js", "knowledge-flush.js", "plan-contract.js", "agent-runs.js", "slop-detect.mjs"];
+
+// Qualia rules — security, deployment, infra, grounding, plus the v4.5.0 design substrate.
+// frontend.md and design-reference.md are kept for backward compat; new projects use design-laws/brand/product/rubric.
+const QUALIA_RULE_FILES = [
+  "security.md", "deployment.md", "infrastructure.md", "grounding.md",
+  "frontend.md", "design-reference.md",
+  "design-laws.md", "design-brand.md", "design-product.md", "design-rubric.md",
+];
 
 function promptYesNo(question, defaultYes) {
   return new Promise((resolve) => {
@@ -553,7 +559,7 @@ function cmdMigrate() {
   console.log(`  ${DIM}Target version:${RESET}  ${WHITE}${PKG.version}${RESET}`);
   console.log("");
 
-  // 1. Ensure all 8 hooks are wired (v2 missed block-env-edit and branch-guard)
+  // 1. Ensure the full v4.3 hook set is wired.
   const hd = path.join(CLAUDE_DIR, "hooks");
   const nodeCmd = (hookFile) => `node "${path.join(hd, hookFile)}"`;
 
@@ -564,10 +570,19 @@ function cmdMigrate() {
     settings.hooks.SessionStart = [{ matcher: ".*", hooks: [{ type: "command", command: nodeCmd("session-start.js"), timeout: 5 }] }];
     changes++;
     console.log(`  ${GREEN}+${RESET} Added SessionStart hook`);
+  } else {
+    const hasSessionStart = settings.hooks.SessionStart.some(e =>
+      Array.isArray(e.hooks) && e.hooks.some(h => typeof h.command === "string" && h.command.includes("session-start.js"))
+    );
+    if (!hasSessionStart) {
+      settings.hooks.SessionStart.push({ matcher: ".*", hooks: [{ type: "command", command: nodeCmd("session-start.js"), timeout: 5 }] });
+      changes++;
+      console.log(`  ${GREEN}+${RESET} Wired session-start.js into SessionStart`);
+    }
   }
 
   // Check PreToolUse hooks — ensure all critical hooks are present
-  const requiredBashHooks = ["auto-update.js", "branch-guard.js", "pre-push.js", "pre-deploy-gate.js"];
+  const requiredBashHooks = ["auto-update.js", "git-guardrails.js", "branch-guard.js", "pre-push.js", "pre-deploy-gate.js"];
   const requiredEditHooks = ["migration-guard.js"];
 
   if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
@@ -595,9 +610,10 @@ function cmdMigrate() {
     const exists = bashEntry.hooks.some(h => extractScriptName(h.command) === targetName);
     if (!exists) {
       const hookDef = { type: "command", command: cmd, timeout: hookFile === "pre-deploy-gate.js" ? 180 : 5 };
-      if (hookFile === "branch-guard.js") hookDef.if = "Bash(git push*)";
+      if (hookFile === "git-guardrails.js") hookDef.statusMessage = "⬢ Checking git safety...";
+      if (hookFile === "branch-guard.js") { hookDef.if = "Bash(git push*)"; hookDef.statusMessage = "⬢ Checking branch permissions..."; }
       if (hookFile === "pre-push.js") { hookDef.if = "Bash(git push*)"; hookDef.timeout = 15; }
-      if (hookFile === "pre-deploy-gate.js") hookDef.if = "Bash(vercel --prod*)";
+      if (hookFile === "pre-deploy-gate.js") { hookDef.if = "Bash(vercel --prod*)"; hookDef.timeout = 180; hookDef.statusMessage = "⬢ Running quality gates..."; }
       bashEntry.hooks.push(hookDef);
       changes++;
       console.log(`  ${GREEN}+${RESET} Wired ${hookFile} into PreToolUse/Bash`);
@@ -618,7 +634,7 @@ function cmdMigrate() {
     const exists = editEntry.hooks.some(h => extractScriptName(h.command) === targetName);
     if (!exists) {
       const hookDef = { type: "command", command: cmd, timeout: hookFile === "migration-guard.js" ? 10 : 5 };
-      if (hookFile === "migration-guard.js") hookDef.if = "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)";
+      if (hookFile === "migration-guard.js") { hookDef.if = "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)"; hookDef.statusMessage = "⬢ Checking migration safety..."; }
       editEntry.hooks.push(hookDef);
       changes++;
       console.log(`  ${GREEN}+${RESET} Wired ${hookFile} into PreToolUse/Edit|Write`);
@@ -626,10 +642,42 @@ function cmdMigrate() {
   }
 
   // Check PreCompact hook
-  if (!settings.hooks.PreCompact) {
+  if (!settings.hooks.PreCompact || !Array.isArray(settings.hooks.PreCompact)) {
     settings.hooks.PreCompact = [{ matcher: "compact", hooks: [{ type: "command", command: nodeCmd("pre-compact.js"), timeout: 15 }] }];
     changes++;
     console.log(`  ${GREEN}+${RESET} Added PreCompact hook`);
+  } else {
+    let compactEntry = settings.hooks.PreCompact.find(e => e.matcher === "compact");
+    if (!compactEntry) {
+      compactEntry = { matcher: "compact", hooks: [] };
+      settings.hooks.PreCompact.push(compactEntry);
+    }
+    if (!compactEntry.hooks) compactEntry.hooks = [];
+    const exists = compactEntry.hooks.some(h => extractScriptName(h.command) === "pre-compact.js");
+    if (!exists) {
+      compactEntry.hooks.push({ type: "command", command: nodeCmd("pre-compact.js"), timeout: 15, statusMessage: "⬢ Saving state..." });
+      changes++;
+      console.log(`  ${GREEN}+${RESET} Wired pre-compact.js into PreCompact`);
+    }
+  }
+
+  if (!settings.hooks.Stop || !Array.isArray(settings.hooks.Stop)) {
+    settings.hooks.Stop = [{ matcher: ".*", hooks: [{ type: "command", command: nodeCmd("stop-session-log.js"), timeout: 5 }] }];
+    changes++;
+    console.log(`  ${GREEN}+${RESET} Added Stop hook`);
+  } else {
+    let stopEntry = settings.hooks.Stop.find(e => e.matcher === ".*");
+    if (!stopEntry) {
+      stopEntry = { matcher: ".*", hooks: [] };
+      settings.hooks.Stop.push(stopEntry);
+    }
+    if (!stopEntry.hooks) stopEntry.hooks = [];
+    const exists = stopEntry.hooks.some(h => extractScriptName(h.command) === "stop-session-log.js");
+    if (!exists) {
+      stopEntry.hooks.push({ type: "command", command: nodeCmd("stop-session-log.js"), timeout: 5 });
+      changes++;
+      console.log(`  ${GREEN}+${RESET} Wired stop-session-log.js into Stop`);
+    }
   }
 
   // 2. Ensure env vars are up to date
@@ -730,12 +778,12 @@ function cmdAnalytics() {
   }
 
   // Verification outcomes (from traces that include verification data)
-  const verifications = traces.filter(t => t.hook === "state-transition" && t.extra && t.extra.verification);
-  const passes = verifications.filter(t => t.extra.verification === "pass").length;
-  const fails = verifications.filter(t => t.extra.verification === "fail").length;
+  const verifications = traces.filter(t => t.hook === "state-transition" && t.verification);
+  const passes = verifications.filter(t => t.verification === "pass").length;
+  const fails = verifications.filter(t => t.verification === "fail").length;
 
   // Gap cycle data
-  const gapTraces = traces.filter(t => t.hook === "state-transition" && t.extra && t.extra.gap_closure);
+  const gapTraces = traces.filter(t => t.hook === "state-transition" && t.gap_closure);
   const totalGapCycles = gapTraces.length;
 
   // Display
@@ -781,8 +829,9 @@ function cmdErpPing() {
   console.log("");
 
   const cfg = readConfig();
+  const args = new Set(process.argv.slice(3));
   const erpUrl = (cfg.erp && cfg.erp.url) || "https://portal.qualiasolutions.net";
-  const erpEnabled = !(cfg.erp && cfg.erp.enabled === false);
+  let erpEnabled = !(cfg.erp && cfg.erp.enabled === false);
   const keyFile = path.join(CLAUDE_DIR, ".erp-api-key");
 
   console.log(`  ${DIM}URL:${RESET}       ${WHITE}${erpUrl}${RESET}`);
@@ -802,6 +851,19 @@ function cmdErpPing() {
   console.log(`  ${DIM}Key:${RESET}       ${GREEN}present${RESET} ${DIM}(${apiKey.length} bytes)${RESET}`);
   console.log("");
 
+  if (!erpEnabled && args.has("--enable")) {
+    cfg.erp = {
+      ...(cfg.erp || {}),
+      enabled: true,
+      url: erpUrl,
+      api_key_file: ".erp-api-key",
+    };
+    writeConfig(cfg);
+    erpEnabled = true;
+    console.log(`  ${GREEN}✓ ERP enabled in config.${RESET}`);
+    console.log("");
+  }
+
   if (!erpEnabled) {
     console.log(`  ${YELLOW}ERP is disabled in config. Enable with:${RESET}`);
     console.log(`  ${DIM}  qualia-framework erp-ping --enable${RESET}`);
@@ -874,6 +936,61 @@ function cmdErpPing() {
   process.exit(1);
 }
 
+function cmdSetErpKey() {
+  banner();
+  console.log("");
+
+  const keyFile = path.join(CLAUDE_DIR, ".erp-api-key");
+  const rawArgs = process.argv.slice(3);
+  const clear = rawArgs.includes("--clear");
+
+  if (!fs.existsSync(CLAUDE_DIR)) fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+
+  if (clear) {
+    try { fs.unlinkSync(keyFile); } catch {}
+    const cfg = readConfig();
+    cfg.erp = { ...(cfg.erp || {}), enabled: false, url: (cfg.erp && cfg.erp.url) || "https://portal.qualiasolutions.net", api_key_file: ".erp-api-key" };
+    writeConfig(cfg);
+    console.log(`  ${GREEN}✓${RESET} ERP key removed and ERP disabled.`);
+    console.log("");
+    return;
+  }
+
+  let key = rawArgs.find((a) => a && !a.startsWith("--")) || "";
+  if (!key && !process.stdin.isTTY) {
+    try { key = fs.readFileSync(0, "utf8").trim(); } catch {}
+  }
+
+  key = String(key || "").trim();
+  if (!key) {
+    console.log(`  ${RED}✗${RESET} Missing ERP API key.`);
+    console.log(`  ${DIM}Usage:${RESET} qualia-framework set-erp-key <key>`);
+    console.log(`  ${DIM}Safe shell history option:${RESET} printf '%s' "$QUALIA_ERP_KEY" | qualia-framework set-erp-key`);
+    console.log("");
+    process.exit(1);
+  }
+
+  if (key.length < 10) {
+    console.log(`  ${YELLOW}!${RESET} Key looks short (${key.length} bytes). Saving anyway.`);
+  }
+
+  fs.writeFileSync(keyFile, key, { mode: 0o600 });
+  try { fs.chmodSync(keyFile, 0o600); } catch {}
+
+  const cfg = readConfig();
+  cfg.erp = {
+    ...(cfg.erp || {}),
+    enabled: true,
+    url: (cfg.erp && cfg.erp.url) || "https://portal.qualiasolutions.net",
+    api_key_file: ".erp-api-key",
+  };
+  writeConfig(cfg);
+
+  console.log(`  ${GREEN}✓${RESET} ERP key saved to ${WHITE}${keyFile}${RESET}`);
+  console.log(`  ${DIM}Verify with:${RESET} ${TEAL}qualia-framework erp-ping${RESET}`);
+  console.log("");
+}
+
 // ─── Doctor: post-install health check ───────────────────
 // Mirrors the spot-check that session-start.js runs once per 24h. Surfaces
 // missing files, mis-wired hooks, stale settings.json, and version drift.
@@ -1001,6 +1118,84 @@ function cmdDoctor() {
   process.exit(1);
 }
 
+// ─── Agents: per-spawn telemetry (see docs/agent-runs.md) ─────────
+function cmdAgents() {
+  banner();
+  console.log("");
+
+  // Lazy require so the CLI works even if the lib is missing during dev.
+  let lib;
+  try { lib = require("./agent-runs.js"); }
+  catch (e) {
+    console.log(`  ${RED}✗${RESET} agent-runs.js not available: ${e.message}`);
+    console.log("");
+    process.exit(1);
+  }
+
+  const args = process.argv.slice(3);
+  const flags = new Set(args.filter((a) => a.startsWith("--")));
+  const sub = args.find((a) => !a.startsWith("--"));
+
+  const cwd = process.cwd();
+
+  if (sub === "prune") {
+    const idx = args.indexOf("--before");
+    const before = idx >= 0 ? args[idx + 1] : null;
+    if (!before) {
+      console.log(`  ${RED}✗${RESET} usage: qualia-framework agents prune --before YYYY-MM-DD`);
+      console.log("");
+      process.exit(1);
+    }
+    try {
+      const r = lib.prune(cwd, before);
+      console.log(`  ${GREEN}✓${RESET} Pruned ${r.removed} run record(s), ${r.logs_removed} log file(s).`);
+      console.log("");
+      return;
+    } catch (e) {
+      console.log(`  ${RED}✗${RESET} ${e.message}`);
+      console.log("");
+      process.exit(1);
+    }
+  }
+
+  const opts = { limit: 50 };
+  if (flags.has("--failed")) opts.failed = true;
+  const taskIdx = args.indexOf("--task");
+  if (taskIdx >= 0) opts.task_id = args[taskIdx + 1];
+  const phaseIdx = args.indexOf("--phase");
+  if (phaseIdx >= 0) opts.phase = Number(args[phaseIdx + 1]);
+
+  const records = lib.read(cwd, opts);
+  if (records.length === 0) {
+    console.log(`  ${DIM}No agent runs recorded yet${RESET} ${DIM}(or run from a project with .planning/)${RESET}`);
+    console.log("");
+    return;
+  }
+
+  console.log(`  ${WHITE}Agent runs${RESET} ${DIM}(showing ${records.length}, newest last)${RESET}`);
+  console.log(`  ${DIM}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
+  console.log(`  ${DIM}TIME   AGENT       PHASE TASK STATUS    DURATION  NOTE${RESET}`);
+  for (const r of records) {
+    const t = (r.finished_at || r.started_at || "").slice(11, 16);
+    const agent = (r.agent_type || "").padEnd(11);
+    const phase = String(r.phase ?? "-").padEnd(5);
+    const task = (r.task_id || "-").padEnd(4);
+    const stColor = r.status === "success" ? GREEN : r.status === "partial" ? YELLOW : RED;
+    const status = `${stColor}${(r.status || "?").padEnd(9)}${RESET}`;
+    const dur = r.duration_ms != null ? `${Math.round(r.duration_ms / 1000)}s`.padStart(7) : "      —";
+    const note = r.failure_reason
+      ? `${DIM}${r.failure_reason}${RESET}`
+      : (r.commit_sha ? `${DIM}${r.commit_sha.slice(0, 7)}${RESET}` : "");
+    console.log(`  ${t}  ${agent} ${phase} ${task} ${status} ${dur}  ${note}`);
+  }
+  console.log("");
+  const failed = records.filter((r) => r.status !== "success").length;
+  if (failed > 0) {
+    console.log(`  ${YELLOW}${failed} non-success run(s).${RESET} ${DIM}qualia-framework agents --failed for details${RESET}`);
+    console.log("");
+  }
+}
+
 function cmdHelp() {
   banner();
   console.log("");
@@ -1009,13 +1204,15 @@ function cmdHelp() {
   console.log(`    qualia-framework ${TEAL}update${RESET}       Update to the latest version`);
   console.log(`    qualia-framework ${TEAL}version${RESET}      Show installed version + check for updates`);
   console.log(`    qualia-framework ${TEAL}uninstall${RESET}    Clean removal from ~/.claude/ (${DIM}-y to skip prompts${RESET})`);
-  console.log(`    qualia-framework ${TEAL}migrate${RESET}      Migrate settings from v2 to v3`);
+  console.log(`    qualia-framework ${TEAL}migrate${RESET}      Wire current hook + env layout into ~/.claude/settings.json`);
   console.log(`    qualia-framework ${TEAL}team${RESET}         Manage team members (${DIM}list|add|remove${RESET})`);
   console.log(`    qualia-framework ${TEAL}traces${RESET}       View recent hook telemetry`);
   console.log(`    qualia-framework ${TEAL}analytics${RESET}    Show outcome scoring & gap cycle stats`);
-  console.log(`    qualia-framework ${TEAL}erp-ping${RESET}     Verify ERP connectivity + API key
-    qualia-framework ${TEAL}doctor${RESET}       Health-check the install (files, hooks, settings)
-    qualia-framework ${TEAL}flush${RESET}        Promote daily-log → curated knowledge (memory layer)`);
+  console.log(`    qualia-framework ${TEAL}agents${RESET}       Show per-agent run history (${DIM}--failed|--task ID|--phase N|prune --before${RESET})`);
+  console.log(`    qualia-framework ${TEAL}set-erp-key${RESET}  Save/enable the ERP API key`);
+  console.log(`    qualia-framework ${TEAL}erp-ping${RESET}     Verify ERP connectivity + API key`);
+  console.log(`    qualia-framework ${TEAL}doctor${RESET}       Health-check the install (files, hooks, settings)`);
+  console.log(`    qualia-framework ${TEAL}flush${RESET}        Promote daily-log → curated knowledge (memory layer)`);
   console.log("");
   console.log(`  ${WHITE}After install:${RESET}`);
   console.log(`    ${TG}/qualia${RESET}          What should I do next?`);
@@ -1023,7 +1220,7 @@ function cmdHelp() {
   console.log(`    ${TG}/qualia-plan${RESET}     Plan a phase`);
   console.log(`    ${TG}/qualia-build${RESET}    Build it (parallel tasks)`);
   console.log(`    ${TG}/qualia-verify${RESET}   Verify it works`);
-  console.log(`    ${TG}/qualia-design${RESET}   One-shot design fix`);
+  console.log(`    ${TG}/qualia-polish${RESET}   Design pass — any scope (component, route, app, redesign)`);
   console.log(`    ${TG}/qualia-debug${RESET}    Structured debugging`);
   console.log(`    ${TG}/qualia-review${RESET}   Production audit`);
   console.log(`    ${TG}/qualia-ship${RESET}     Deploy to production`);
@@ -1064,10 +1261,17 @@ switch (cmd) {
   case "migrate":
     cmdMigrate();
     break;
+  case "agents":
+    cmdAgents();
+    break;
   case "analytics":
   case "stats":
     cmdAnalytics();
     break;
+  case "set-erp-key":
+  case "erp-key":
+    cmdSetErpKey();
+    break;
   case "erp-ping":
   case "ping":
     cmdErpPing();

package/bin/install.js

@@ -422,6 +422,22 @@ async function main() {
     );
     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)");
   } catch (e) {
     warn(`scripts — ${e.message}`);
   }
@@ -586,8 +602,8 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
       try { fs.chmodSync(configFile, 0o600); } catch {}
     } catch {}
     log(`${YELLOW}!${RESET} ERP key not configured — reports won't upload until set.`);
-    log(`${DIM}  Set with:${RESET} ${TEAL}export QUALIA_ERP_KEY=...${RESET} ${DIM}then re-install,${RESET}`);
-    log(`${DIM}  or write the key to:${RESET} ${WHITE}${erpKeyFile}${RESET} ${DIM}(mode 0600).${RESET}`);
+    log(`${DIM}  Set with:${RESET} ${TEAL}qualia-framework set-erp-key <key>${RESET}`);
+    log(`${DIM}  or:${RESET} ${TEAL}export QUALIA_ERP_KEY=...${RESET} ${DIM}then re-install.${RESET}`);
     log(`${DIM}  Get a key from Fawzi.${RESET}`);
   }
 
@@ -739,8 +755,8 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     settings.hooks[event] = [...cleaned, ...qualiaHooks[event]];
   }
 
-  // Permissions — no restrictions on env files or branches.
-  // Everyone can read/write .env, push to main.
+  // Permissions stay permissive; Qualia policy enforcement happens in hooks so
+  // OWNER overrides and EMPLOYEE blocks can share one source of truth.
   if (!settings.permissions) settings.permissions = {};
   if (!settings.permissions.allow) settings.permissions.allow = [];
   if (!settings.permissions.deny) settings.permissions.deny = [];
@@ -776,7 +792,11 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
   const ruleCount = fs.readdirSync(rulesDir).length;
   const tmplCount = fs.readdirSync(tmplDir).length;
   console.log(`  ${DIM}Skills${RESET}    ${TEAL}${skills.length}${RESET}     ${DIM}Agents${RESET}  ${TEAL}${agentCount}${RESET}     ${DIM}Hooks${RESET}   ${TEAL}${hookCount}${RESET}`);
-  console.log(`  ${DIM}Rules${RESET}     ${TEAL}${ruleCount}${RESET}     ${DIM}Scripts${RESET} ${TEAL}3${RESET}     ${DIM}Templates${RESET} ${TEAL}${tmplCount}${RESET}`);
+  const installedBinDir = path.join(CLAUDE_DIR, "bin");
+  const scriptCount = fs.existsSync(installedBinDir)
+    ? fs.readdirSync(installedBinDir).filter(f => f.endsWith('.js')).length
+    : 0;
+  console.log(`  ${DIM}Rules${RESET}     ${TEAL}${ruleCount}${RESET}     ${DIM}Scripts${RESET} ${TEAL}${scriptCount}${RESET}     ${DIM}Templates${RESET} ${TEAL}${tmplCount}${RESET}`);
 
   if (errors > 0) {
     console.log("");

package/bin/plan-contract.js

@@ -0,0 +1,220 @@
+#!/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`.
+//
+// Zero npm dependencies. Hand-rolled validator, ~100 LOC.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const SCHEMA_VERSION = 1;
+
+const PERSONAS = new Set([
+  "security", "architect", "ux", "frontend",
+  "backend", "data", "performance", "none",
+]);
+
+const CHECK_TYPES = new Set([
+  "file-exists", "grep-match", "command-exit", "behavioral",
+]);
+
+function isStringArray(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+
+function isPlainObject(v) {
+  return v && typeof v === "object" && !Array.isArray(v);
+}
+
+function validateCheck(check, taskId, idx) {
+  const errs = [];
+  const where = `tasks[id=${taskId}].verification[${idx}]`;
+  if (!isPlainObject(check)) return [`${where}: not an object`];
+  if (!CHECK_TYPES.has(check.type)) {
+    errs.push(`${where}.type: must be one of ${[...CHECK_TYPES].join("|")}`);
+    return errs;
+  }
+  switch (check.type) {
+    case "file-exists":
+      if (typeof check.path !== "string" || !check.path) errs.push(`${where}.path: required string`);
+      if (check.must_contain != null && typeof check.must_contain !== "string") errs.push(`${where}.must_contain: must be string`);
+      break;
+    case "grep-match":
+      if (typeof check.path !== "string" || !check.path) errs.push(`${where}.path: required string`);
+      if (typeof check.pattern !== "string" || !check.pattern) errs.push(`${where}.pattern: required string`);
+      else { try { new RegExp(check.pattern); } catch { errs.push(`${where}.pattern: invalid regex`); } }
+      if (check.expect !== "present" && check.expect !== "absent") errs.push(`${where}.expect: must be "present" or "absent"`);
+      break;
+    case "command-exit":
+      if (typeof check.command !== "string" || !check.command) errs.push(`${where}.command: required string`);
+      else if (/[;&|`$<>(){}\\]/.test(check.command)) errs.push(`${where}.command: shell metacharacters not allowed (use args[])`);
+      if (!isStringArray(check.args || [])) errs.push(`${where}.args: must be string[]`);
+      if (typeof check.expected_exit !== "number") errs.push(`${where}.expected_exit: required number`);
+      if (check.timeout_ms != null && (typeof check.timeout_ms !== "number" || check.timeout_ms <= 0)) {
+        errs.push(`${where}.timeout_ms: must be positive number`);
+      }
+      if (check.expect_stdout_match != null) {
+        if (typeof check.expect_stdout_match !== "string") errs.push(`${where}.expect_stdout_match: must be string`);
+        else { try { new RegExp(check.expect_stdout_match); } catch { errs.push(`${where}.expect_stdout_match: invalid regex`); } }
+      }
+      break;
+    case "behavioral":
+      if (typeof check.description !== "string" || !check.description) errs.push(`${where}.description: required string`);
+      if (!Array.isArray(check.evidence_required) || check.evidence_required.length === 0) {
+        errs.push(`${where}.evidence_required: must be a non-empty array`);
+      } else {
+        check.evidence_required.forEach((ev, i) => {
+          const w = `${where}.evidence_required[${i}]`;
+          if (!isPlainObject(ev)) { errs.push(`${w}: not an object`); return; }
+          if (typeof ev.path !== "string" || !ev.path) errs.push(`${w}.path: required string`);
+          if (typeof ev.description !== "string" || !ev.description) errs.push(`${w}.description: required string`);
+          if (ev.matcher != null) {
+            if (typeof ev.matcher !== "string") errs.push(`${w}.matcher: must be string`);
+            else { try { new RegExp(ev.matcher); } catch { errs.push(`${w}.matcher: invalid regex`); } }
+          }
+        });
+      }
+      break;
+  }
+  return errs;
+}
+
+function validateTask(task, idx, allIds) {
+  const errs = [];
+  const where = `tasks[${idx}]`;
+  if (!isPlainObject(task)) return [`${where}: not an object`];
+  if (typeof task.id !== "string" || !/^T\d+$/.test(task.id)) errs.push(`${where}.id: must match ^T\\d+$`);
+  if (typeof task.title !== "string" || !task.title) errs.push(`${where}.title: required string`);
+  if (typeof task.wave !== "number" || task.wave < 1) errs.push(`${where}.wave: must be positive number`);
+  if (!isStringArray(task.depends_on || [])) errs.push(`${where}.depends_on: must be string[]`);
+  if (task.persona != null && !PERSONAS.has(task.persona)) errs.push(`${where}.persona: invalid value`);
+  if (!isStringArray(task.files_modify || [])) errs.push(`${where}.files_modify: must be string[]`);
+  if (!isStringArray(task.files_create || [])) errs.push(`${where}.files_create: must be string[]`);
+  if (!isStringArray(task.files_delete || [])) errs.push(`${where}.files_delete: must be string[]`);
+  if (!isStringArray(task.acceptance_criteria || []) || (task.acceptance_criteria || []).length === 0) {
+    errs.push(`${where}.acceptance_criteria: must be a non-empty string[]`);
+  }
+  if (typeof task.action !== "string") errs.push(`${where}.action: required string`);
+  else if (task.action.length > 500) errs.push(`${where}.action: must be ≤ 500 characters (got ${task.action.length})`);
+  if (!isStringArray(task.context_files || [])) errs.push(`${where}.context_files: must be string[]`);
+  if (!Array.isArray(task.verification) || task.verification.length === 0) {
+    errs.push(`${where}.verification: must be a non-empty array`);
+  } else {
+    task.verification.forEach((c, i) => errs.push(...validateCheck(c, task.id, i)));
+  }
+
+  // disjointness across files_modify/create/delete
+  const m = new Set(task.files_modify || []);
+  const c = new Set(task.files_create || []);
+  const d = new Set(task.files_delete || []);
+  for (const p of m) if (c.has(p) || d.has(p)) errs.push(`${where}: ${p} appears in multiple file lists`);
+  for (const p of c) if (d.has(p)) errs.push(`${where}: ${p} appears in multiple file lists`);
+
+  // depends_on references must exist
+  for (const dep of task.depends_on || []) {
+    if (!allIds.has(dep)) errs.push(`${where}.depends_on: references unknown id "${dep}"`);
+  }
+  return errs;
+}
+
+function detectCycles(tasks) {
+  const graph = new Map(tasks.map((t) => [t.id, t.depends_on || []]));
+  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const color = new Map([...graph.keys()].map((k) => [k, WHITE]));
+  const cycles = [];
+  function dfs(u, stack) {
+    color.set(u, GRAY);
+    stack.push(u);
+    for (const v of graph.get(u) || []) {
+      if (!graph.has(v)) continue;
+      const cv = color.get(v);
+      if (cv === GRAY) { cycles.push([...stack, v].join(" → ")); return; }
+      if (cv === WHITE) dfs(v, stack);
+    }
+    color.set(u, BLACK);
+    stack.pop();
+  }
+  for (const k of graph.keys()) if (color.get(k) === WHITE) dfs(k, []);
+  return cycles;
+}
+
+function validate(contract) {
+  const errs = [];
+  if (!isPlainObject(contract)) return ["contract: not an object"];
+  if (contract.version !== SCHEMA_VERSION) errs.push(`version: must be ${SCHEMA_VERSION}, got ${contract.version}`);
+  if (typeof contract.phase !== "number" || contract.phase < 1) errs.push("phase: must be positive number");
+  if (typeof contract.goal !== "string" || !contract.goal) errs.push("goal: required string");
+  if (typeof contract.why !== "string" || !contract.why) errs.push("why: required string");
+  if (typeof contract.generated_at !== "string") errs.push("generated_at: required ISO 8601 string");
+  if (!["planner", "compile-plan", "manual"].includes(contract.generated_by)) {
+    errs.push('generated_by: must be "planner" | "compile-plan" | "manual"');
+  }
+  if (typeof contract.source_plan_hash !== "string") errs.push("source_plan_hash: required string (empty for manual)");
+  if (!isStringArray(contract.success_criteria || []) || (contract.success_criteria || []).length === 0) {
+    errs.push("success_criteria: must be a non-empty string[]");
+  }
+  if (!Array.isArray(contract.tasks) || contract.tasks.length === 0) {
+    errs.push("tasks: must be a non-empty array");
+    return errs;
+  }
+
+  const ids = new Set();
+  for (const t of contract.tasks) {
+    if (t && typeof t.id === "string") {
+      if (ids.has(t.id)) errs.push(`tasks: duplicate id "${t.id}"`);
+      ids.add(t.id);
+    }
+  }
+
+  contract.tasks.forEach((t, i) => errs.push(...validateTask(t, i, ids)));
+
+  const cycles = detectCycles(contract.tasks);
+  if (cycles.length) errs.push(`tasks: cycle detected: ${cycles[0]}`);
+
+  // wave > max(deps wave)
+  const byId = new Map(contract.tasks.map((t) => [t.id, t]));
+  for (const t of contract.tasks) {
+    const deps = (t.depends_on || []).map((id) => byId.get(id)).filter(Boolean);
+    if (deps.length === 0) continue;
+    const maxDepWave = Math.max(...deps.map((d) => d.wave || 0));
+    if ((t.wave || 0) <= maxDepWave) {
+      errs.push(`tasks[id=${t.id}].wave: must be > ${maxDepWave} (max wave of its dependencies)`);
+    }
+  }
+
+  return errs;
+}
+
+function parseSafely(text) {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+function hashPlan(text) {
+  return "sha256:" + crypto.createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+function checkDrift(contractPath, planMdPath) {
+  if (!fs.existsSync(contractPath)) return { ok: false, reason: "contract-missing" };
+  if (!fs.existsSync(planMdPath)) return { ok: false, reason: "plan-md-missing" };
+  const parsed = parseSafely(fs.readFileSync(contractPath, "utf8"));
+  if (!parsed.ok) return { ok: false, reason: "contract-unparseable", detail: parsed.error };
+  const stored = parsed.value.source_plan_hash;
+  if (!stored) return { ok: true, drift: false, reason: "no-hash-stored" };
+  const current = hashPlan(fs.readFileSync(planMdPath, "utf8"));
+  return { ok: true, drift: stored !== current, stored, current };
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  validate,
+  parseSafely,
+  hashPlan,
+  checkDrift,
+};