qualia-framework 3.2.0 → 3.2.1

package/bin/install.js

@@ -13,8 +13,11 @@ const YELLOW = "\x1b[38;2;234;179;8m";
 const RED = "\x1b[38;2;239;68;68m";
 const RESET = "\x1b[0m";
 
+const CLAUDE_DIR = path.join(require("os").homedir(), ".claude");
+const FRAMEWORK_DIR = path.resolve(__dirname, "..");
+
 // ─── Team codes ──────────────────────────────────────────
-const TEAM = {
+const DEFAULT_TEAM = {
   "QS-FAWZI-01": {
     name: "Fawzi Goussous",
     role: "OWNER",
@@ -23,27 +26,40 @@ const TEAM = {
   "QS-HASAN-02": {
     name: "Hasan",
     role: "EMPLOYEE",
-    description: "Developer. Feature branches only. Cannot push to main or edit .env files.",
+    description: "Developer. Feature branches only. Cannot push to main.",
   },
   "QS-MOAYAD-03": {
     name: "Moayad",
     role: "EMPLOYEE",
-    description: "Developer. Feature branches only. Cannot push to main or edit .env files.",
+    description: "Developer. Feature branches only. Cannot push to main.",
   },
   "QS-RAMA-04": {
     name: "Rama",
     role: "EMPLOYEE",
-    description: "Developer. Feature branches only. Cannot push to main or edit .env files.",
+    description: "Developer. Feature branches only. Cannot push to main.",
   },
   "QS-SALLY-05": {
     name: "Sally",
     role: "EMPLOYEE",
-    description: "Developer. Feature branches only. Cannot push to main or edit .env files.",
+    description: "Developer. Feature branches only. Cannot push to main.",
   },
 };
 
-const CLAUDE_DIR = path.join(require("os").homedir(), ".claude");
-const FRAMEWORK_DIR = path.resolve(__dirname, "..");
+// Load team from external file, fall back to embedded defaults.
+function loadTeam() {
+  const teamFile = path.join(CLAUDE_DIR, ".qualia-team.json");
+  try {
+    if (fs.existsSync(teamFile)) {
+      const external = JSON.parse(fs.readFileSync(teamFile, "utf8"));
+      if (external && typeof external === "object" && Object.keys(external).length > 0) {
+        return external;
+      }
+    }
+  } catch {}
+  return DEFAULT_TEAM;
+}
+
+const TEAM = loadTeam();
 
 let installed = 0;
 let errors = 0;
@@ -65,14 +81,34 @@ function copy(src, dest) {
   fs.copyFileSync(src, dest);
 }
 
+// ─── Branded Header ─────────────────────────────────────
+const BOLD = "\x1b[1m";
+const TEAL_GLOW = "\x1b[38;2;0;170;175m";
+const PKG_VERSION = require("../package.json").version;
+const RULE = "━".repeat(48);
+
+function printHeader() {
+  console.log("");
+  console.log("");
+  console.log(`  ${TEAL}${BOLD}⬢  Q U A L I A${RESET}`);
+  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log(`  ${WHITE}Framework v${PKG_VERSION}${RESET}  ${DIM}·${RESET}  ${TEAL_GLOW}Qualia Solutions${RESET}`);
+  console.log(`  ${DIM}Plan → Build → Verify → Ship${RESET}`);
+  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log("");
+}
+
+function printSection(title) {
+  console.log("");
+  console.log(`  ${TEAL}▸${RESET} ${WHITE}${BOLD}${title}${RESET}`);
+  console.log(`  ${DIM}${"─".repeat(40)}${RESET}`);
+}
+
 // ─── Prompt for code ─────────────────────────────────────
 function askCode() {
   return new Promise((resolve) => {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
-    console.log("");
-    console.log(`${TEAL}  ⬢ Qualia Framework v2${RESET}`);
-    console.log(`${DIM}  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
-    console.log("");
+    printHeader();
     rl.question(`  ${WHITE}Enter install code:${RESET} `, (answer) => {
       rl.close();
       resolve(answer.trim());
@@ -111,10 +147,9 @@ async function main() {
   }
 
   console.log("");
-  log(`${GREEN}✓${RESET} ${WHITE}${member.name}${RESET} ${DIM}(${member.role})${RESET}`);
-  console.log("");
-  log(`Installing to ${WHITE}${CLAUDE_DIR}${RESET}`);
-  console.log("");
+  const roleColor = member.role === "OWNER" ? TEAL : GREEN;
+  console.log(`  ${GREEN}✓${RESET} ${WHITE}${BOLD}Welcome, ${member.name}${RESET}`);
+  console.log(`  ${DIM}  Role:${RESET} ${roleColor}${member.role}${RESET}  ${DIM}·${RESET}  ${DIM}Target:${RESET} ${WHITE}${CLAUDE_DIR}${RESET}`);
 
   // ─── Skills ──────────────────────────────────────────
   const skillsDir = path.join(FRAMEWORK_DIR, "skills");
@@ -122,7 +157,7 @@ async function main() {
     .readdirSync(skillsDir)
     .filter((d) => fs.statSync(path.join(skillsDir, d)).isDirectory());
 
-  log(`${WHITE}Skills${RESET}`);
+  printSection("Skills");
   for (const skill of skills) {
     try {
       copy(
@@ -136,7 +171,7 @@ async function main() {
   }
 
   // ─── Agents ────────────────────────────────────────────
-  log(`${WHITE}Agents${RESET}`);
+  printSection("Agents");
   const agentsDir = path.join(FRAMEWORK_DIR, "agents");
   for (const file of fs.readdirSync(agentsDir)) {
     try {
@@ -148,7 +183,7 @@ async function main() {
   }
 
   // ─── Rules ─────────────────────────────────────────────
-  log(`${WHITE}Rules${RESET}`);
+  printSection("Rules");
   const rulesDir = path.join(FRAMEWORK_DIR, "rules");
   for (const file of fs.readdirSync(rulesDir)) {
     try {
@@ -160,24 +195,26 @@ async function main() {
   }
 
   // ─── Hooks ─────────────────────────────────────────────
-  log(`${WHITE}Hooks${RESET}`);
+  printSection("Hooks");
   const hooksSource = path.join(FRAMEWORK_DIR, "hooks");
   const hooksDest = path.join(CLAUDE_DIR, "hooks");
   if (!fs.existsSync(hooksDest)) fs.mkdirSync(hooksDest, { recursive: true });
-  // Clean up legacy .sh hooks from previous installs so no orphans
-  // remain on disk after upgrading to the pure-Node hooks.
-  // Also purge explicitly-deprecated hooks by name (these are no longer
-  // shipped in framework/hooks/ but may linger on existing installs).
-  const DEPRECATED_HOOKS = [
-    "block-env-edit.js",  // v3.2.0: team decision to unblock .env read/write
-  ];
+  // Clean up legacy .sh hooks from previous v2.5/v2.6 installs so no orphans
+  // remain on disk after upgrading to the pure-Node v2.7+ hooks.
   try {
     for (const f of fs.readdirSync(hooksDest)) {
-      if (f.endsWith(".sh") || DEPRECATED_HOOKS.includes(f)) {
+      if (f.endsWith(".sh")) {
         try { fs.unlinkSync(path.join(hooksDest, f)); } catch {}
       }
     }
   } catch {}
+  // v3.2.0: purge deprecated hooks from existing installs on upgrade.
+  // block-env-edit.js was retired — team now has full read/write on .env*.
+  const DEPRECATED_HOOKS = ["block-env-edit.js"];
+  for (const f of DEPRECATED_HOOKS) {
+    const p = path.join(hooksDest, f);
+    try { if (fs.existsSync(p)) fs.unlinkSync(p); } catch {}
+  }
   for (const file of fs.readdirSync(hooksSource)) {
     try {
       const dest = path.join(hooksDest, file);
@@ -190,18 +227,8 @@ async function main() {
     }
   }
 
-  // ─── Status line ───────────────────────────────────────
-  log(`${WHITE}Status line${RESET}`);
-  try {
-    const slDest = path.join(CLAUDE_DIR, "bin", "statusline.js");
-    copy(path.join(FRAMEWORK_DIR, "bin", "statusline.js"), slDest);
-    ok("statusline.js");
-  } catch (e) {
-    warn(`statusline.js — ${e.message}`);
-  }
-
   // ─── Templates ─────────────────────────────────────────
-  log(`${WHITE}Templates${RESET}`);
+  printSection("Templates");
   const tmplDir = path.join(FRAMEWORK_DIR, "templates");
   const tmplDest = path.join(CLAUDE_DIR, "qualia-templates");
   if (!fs.existsSync(tmplDest)) fs.mkdirSync(tmplDest, { recursive: true });
@@ -215,7 +242,7 @@ async function main() {
   }
 
   // ─── CLAUDE.md with role ───────────────────────────────
-  log(`${WHITE}CLAUDE.md${RESET}`);
+  printSection("Configuration");
   try {
     let claudeMd = fs.readFileSync(
       path.join(FRAMEWORK_DIR, "CLAUDE.md"),
@@ -231,7 +258,7 @@ async function main() {
   }
 
   // ─── Scripts ─────────────────────────────────────────────
-  log(`${WHITE}Scripts${RESET}`);
+  printSection("Scripts");
   try {
     const binDest = path.join(CLAUDE_DIR, "bin");
     if (!fs.existsSync(binDest)) fs.mkdirSync(binDest, { recursive: true });
@@ -267,7 +294,7 @@ async function main() {
   }
 
   // ─── Knowledge directory ─────────────────────────────────
-  log(`${WHITE}Knowledge${RESET}`);
+  printSection("Knowledge Base");
   const knowledgeDir = path.join(CLAUDE_DIR, "knowledge");
   if (!fs.existsSync(knowledgeDir)) fs.mkdirSync(knowledgeDir, { recursive: true });
   const knowledgeFiles = {
@@ -333,7 +360,7 @@ Recurring issues and their solutions.
 **Symptom:** \`/qualia-ship\` is blocked with "service_role found in client code" for a file that's actually a Server Component (runs server-side only).
 **Cause:** pre-deploy-gate.js skips files matching \`.server.\` filename pattern OR \`server/\` directory path. If the Server Component is at \`app/admin/page.tsx\` (no .server. marker, not in a server/ dir), the scan flags it.
 **Workaround:** Rename to \`.server.tsx\` OR move to a \`server/\` subdirectory OR extract the service_role usage into a helper in \`lib/server/\`.
-**Framework version:** Known issue; better heuristic planned for a future release.
+**Framework version:** Known issue as of v2.8.1; better heuristic planned for v3.0.
 `,
     "client-prefs.md": `# Client Preferences
 
@@ -368,11 +395,16 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     role: member.role,
     version: require("../package.json").version,
     installed_at: new Date().toISOString().split("T")[0],
+    erp: {
+      enabled: true,
+      url: "https://portal.qualiasolutions.net",
+      api_key_file: ".erp-api-key",
+    },
   };
   fs.writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n");
 
   // ─── ERP API key (for report uploads) ──────────────────
-  log(`${WHITE}ERP integration${RESET}`);
+  printSection("ERP Integration");
   const erpKeyFile = path.join(CLAUDE_DIR, ".erp-api-key");
   if (!fs.existsSync(erpKeyFile)) {
     fs.writeFileSync(erpKeyFile, "qualia-claude-2026", { mode: 0o600 });
@@ -474,7 +506,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
             type: "command",
             if: "Bash(git push*)",
             command: nodeCmd("branch-guard.js"),
-            timeout: 10,
+            timeout: 5,
             statusMessage: "⬢ Checking branch permissions...",
           },
           {
@@ -521,38 +553,44 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     ],
   };
 
-  // Permissions
+  // Permissions — no restrictions on env files or branches.
+  // Everyone can read/write .env, push to main.
   if (!settings.permissions) settings.permissions = {};
   if (!settings.permissions.allow) settings.permissions.allow = [];
-  if (!settings.permissions.deny) {
-    settings.permissions.deny = [
-      "Read(./.env)",
-      "Read(./.env.*)",
-      "Read(./secrets/**)",
-    ];
+  if (!settings.permissions.deny) settings.permissions.deny = [];
+
+  // ─── Optional: next-devtools MCP ─────────────────────────
+  // Wire next-devtools-mcp for runtime error visibility in Next.js projects
+  if (!settings.mcpServers) settings.mcpServers = {};
+  if (!settings.mcpServers["next-devtools"]) {
+    settings.mcpServers["next-devtools"] = {
+      command: "npx",
+      args: ["next-devtools-mcp@0.3.10"],
+      disabled: false,
+    };
+    ok("MCP: next-devtools (runtime error visibility for Next.js projects)");
   }
 
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 
-  ok("Hooks: session-start, auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact");
+  ok("Hooks: session-start, auto-update, branch-guard, pre-push, migration-guard, deploy-gate, pre-compact");
   ok("Status line + spinner configured");
   ok("Environment variables + permissions");
 
   // ─── Summary ───────────────────────────────────────────
   console.log("");
-  console.log(`${TEAL}  ⬢ Installed ✓${RESET}`);
-  console.log(`${DIM}  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
-  console.log(`  ${WHITE}${member.name}${RESET} ${DIM}(${member.role})${RESET}`);
-  console.log(`  Skills:       ${WHITE}${skills.length}${RESET}`);
+  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log(`  ${TEAL}${BOLD}⬢  INSTALLED${RESET}`);
+  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log("");
+  console.log(`  ${WHITE}${BOLD}${member.name}${RESET}  ${DIM}·${RESET}  ${roleColor}${member.role}${RESET}  ${DIM}·${RESET}  ${DIM}v${PKG_VERSION}${RESET}`);
+  console.log("");
   const agentCount = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md')).length;
-  console.log(`  Agents:       ${WHITE}${agentCount}${RESET} ${DIM}(planner, builder, verifier, qa-browser)${RESET}`);
-  console.log(`  Hooks:        ${WHITE}8${RESET} ${DIM}(session-start, auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact)${RESET}`);
-  console.log(`  Rules:        ${WHITE}${fs.readdirSync(rulesDir).length}${RESET} ${DIM}(security, frontend, design-reference, deployment)${RESET}`);
-  console.log(`  Scripts:      ${WHITE}3${RESET} ${DIM}(state.js, qualia-ui.js, statusline.js)${RESET}`);
-  console.log(`  Knowledge:    ${WHITE}3${RESET} ${DIM}(patterns, fixes, client prefs)${RESET}`);
-  console.log(`  Templates:    ${WHITE}${fs.readdirSync(tmplDir).length}${RESET}`);
-  console.log(`  Status line:  ${GREEN}✓${RESET}`);
-  console.log(`  CLAUDE.md:    ${GREEN}✓${RESET} ${DIM}(${member.role})${RESET}`);
+  const hookCount = fs.readdirSync(hooksSource).length;
+  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}`);
 
   if (errors > 0) {
     console.log("");
@@ -560,7 +598,22 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
   }
 
   console.log("");
-  console.log(`  Restart Claude Code, then type ${TEAL}/qualia${RESET} in any project.`);
+  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log(`  ${WHITE}${BOLD}Quick Start${RESET}`);
+  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log("");
+  console.log(`  ${TEAL}1.${RESET} ${WHITE}Restart Claude Code${RESET} ${DIM}(loads new settings)${RESET}`);
+  console.log(`  ${TEAL}2.${RESET} ${WHITE}cd into any project${RESET} ${DIM}and run${RESET} ${TEAL}claude${RESET}`);
+  console.log(`  ${TEAL}3.${RESET} ${WHITE}Type${RESET} ${TEAL}${BOLD}/qualia${RESET} ${DIM}— it tells you what to do next${RESET}`);
+  console.log("");
+  console.log(`  ${DIM}New project?${RESET}    ${TEAL}/qualia-new${RESET}`);
+  console.log(`  ${DIM}Quick fix?${RESET}      ${TEAL}/qualia-quick${RESET}`);
+  console.log(`  ${DIM}End of day?${RESET}     ${TEAL}/qualia-report${RESET} ${DIM}(mandatory)${RESET}`);
+  console.log(`  ${DIM}Stuck?${RESET}          ${TEAL}/qualia${RESET}`);
+  console.log("");
+  console.log(`  ${DIM}${RULE}${RESET}`);
+  console.log(`  ${TEAL}${BOLD}Welcome to the future with Qualia.${RESET}`);
+  console.log(`  ${DIM}${RULE}${RESET}`);
   console.log("");
 }
 

package/bin/qualia-ui.js

@@ -249,6 +249,16 @@ function cmdNext(cmd) {
   console.log("");
 }
 
+function cmdEnd(status, nextCmd) {
+  console.log("");
+  console.log(`  ${TEAL}${BOLD}⬢${RESET} ${WHITE}${BOLD}${status || "DONE"}${RESET}`);
+  console.log(`  ${RULE_DIM}`);
+  if (nextCmd) {
+    console.log(`  ${TEAL}⟶${RESET} ${WHITE}Next:${RESET}  ${TEAL}${BOLD}${nextCmd}${RESET}`);
+  }
+  console.log("");
+}
+
 function cmdUpdate(current, latest) {
   if (!current || !latest) return;
   console.log("");
@@ -262,16 +272,6 @@ function cmdUpdate(current, latest) {
   console.log("");
 }
 
-function cmdEnd(status, nextCmd) {
-  console.log("");
-  console.log(`  ${TEAL}${BOLD}⬢${RESET} ${WHITE}${BOLD}${status || "DONE"}${RESET}`);
-  console.log(`  ${RULE_DIM}`);
-  if (nextCmd) {
-    console.log(`  ${TEAL}⟶${RESET} ${WHITE}Next:${RESET}  ${TEAL}${BOLD}${nextCmd}${RESET}`);
-  }
-  console.log("");
-}
-
 // ─── Main ────────────────────────────────────────────────
 const [cmd, ...rest] = process.argv.slice(2);
 switch (cmd) {
@@ -293,7 +293,7 @@ switch (cmd) {
   case "update":   cmdUpdate(rest[0], rest[1]); break;
   default:
     console.error(
-      `Usage: qualia-ui.js <banner|context|divider|ok|fail|warn|info|spawn|wave|task|done|next|end> [args]`
+      `Usage: qualia-ui.js <banner|context|divider|ok|fail|warn|info|spawn|wave|task|done|next|end|update> [args]`
     );
     process.exit(1);
 }

package/bin/state.js

@@ -9,6 +9,17 @@ const PLANNING = ".planning";
 const STATE_FILE = path.join(PLANNING, "STATE.md");
 const TRACKING_FILE = path.join(PLANNING, "tracking.json");
 
+// ─── Trace ──────────────────────────────────────────────
+function _trace(event, data) {
+  try {
+    const traceDir = path.join(require("os").homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = { hook: event, timestamp: new Date().toISOString(), ...data };
+    const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch { /* trace failures must not disrupt state machine */ }
+}
+
 // ─── Arg Parsing ─────────────────────────────────────────
 function parseArgs(argv) {
   const args = {};
@@ -186,6 +197,25 @@ const VALID_FROM = {
   done: ["handed_off"],
 };
 
+// ─── Configurable Gap Cycle Limit ────────────────────────
+function getGapCycleLimit() {
+  // Priority: tracking.json.gap_cycle_limit > PROJECT.md > default (2)
+  try {
+    const t = readTracking();
+    if (t && typeof t.gap_cycle_limit === "number" && t.gap_cycle_limit > 0) {
+      return t.gap_cycle_limit;
+    }
+  } catch {}
+
+  try {
+    const projectMd = fs.readFileSync(path.join(PLANNING, "PROJECT.md"), "utf8");
+    const match = projectMd.match(/^gap_cycle_limit:\s*(\d+)/m);
+    if (match) return parseInt(match[1]);
+  } catch {}
+
+  return 2; // default
+}
+
 function checkPreconditions(current, target, opts) {
   const phase = parseInt(opts.phase) || current.phase;
 
@@ -207,6 +237,14 @@ function checkPreconditions(current, target, opts) {
     const planFile = path.join(PLANNING, `phase-${phase}-plan.md`);
     if (!fs.existsSync(planFile))
       return fail("MISSING_FILE", `Plan file not found: ${planFile}`);
+    // Validate plan content (not just existence)
+    const planContent = fs.readFileSync(planFile, "utf8");
+    const taskHeaders = planContent.match(/^## Task \d+/gm);
+    if (!taskHeaders || taskHeaders.length === 0)
+      return fail("INVALID_PLAN", "Plan file has no task headers (expected '## Task N')");
+    const doneWhenCount = (planContent.match(/\*\*Done when:\*\*/g) || []).length;
+    if (doneWhenCount < taskHeaders.length)
+      return fail("INVALID_PLAN", `${taskHeaders.length} tasks but only ${doneWhenCount} 'Done when:' entries`);
   }
 
   if (target === "verified") {
@@ -228,14 +266,15 @@ function checkPreconditions(current, target, opts) {
       return fail("MISSING_FILE", `Handoff file not found: ${hFile}`);
   }
 
-  // Gap-closure circuit breaker
+  // Gap-closure circuit breaker (configurable limit)
   if (target === "planned" && current.status === "verified") {
     const t = readTracking() || {};
     const cycles = (t.gap_cycles || {})[String(phase)] || 0;
-    if (cycles >= 2) {
+    const limit = getGapCycleLimit();
+    if (cycles >= limit) {
       return fail(
         "GAP_CYCLE_LIMIT",
-        `Phase ${phase} has failed verification ${cycles} times. Escalate to Fawzi or re-plan from scratch.`
+        `Phase ${phase} has failed verification ${cycles} times (limit: ${limit}). Escalate to Fawzi or re-plan from scratch.`
       );
     }
   }
@@ -294,6 +333,7 @@ function cmdCheck(opts) {
     assigned_to: s.assigned_to,
     verification: t.verification || "pending",
     gap_cycles: (t.gap_cycles || {})[String(s.phase)] || 0,
+    gap_cycle_limit: getGapCycleLimit(),
     tasks_done: t.tasks_done || 0,
     tasks_total: t.tasks_total || 0,
     deployed_url: t.deployed_url || "",
@@ -331,7 +371,6 @@ function cmdTransition(opts) {
 
   // Special: note/activity (no status change)
   if (target === "note" || target === "activity") {
-    const now = new Date().toISOString().split("T")[0];
     if (opts.notes) t.notes = opts.notes;
     t.last_updated = new Date().toISOString();
     writeTracking(t);
@@ -353,7 +392,16 @@ function cmdTransition(opts) {
     target,
     { ...opts, phase }
   );
-  if (!check.ok) return output(check);
+  if (!check.ok) {
+    // Force only bypasses status-ordering errors (PRECONDITION_FAILED, GAP_CYCLE_LIMIT).
+    // Never bypass MISSING_FILE, MISSING_ARG, INVALID_PLAN — those cause broken state.
+    const forceableErrors = ["PRECONDITION_FAILED", "GAP_CYCLE_LIMIT"];
+    if (opts.force && forceableErrors.includes(check.error)) {
+      console.error(`WARNING: Forcing transition despite: ${check.message}`);
+    } else {
+      return output(check);
+    }
+  }
 
   const prevStatus = s.status;
 
@@ -432,6 +480,18 @@ function cmdTransition(opts) {
     return output(fail("WRITE_ERROR", e.message));
   }
 
+  // Skill outcome scoring — log transition for analytics
+  _trace("state-transition", {
+    result: "allow",
+    phase: s.phase,
+    status: s.status,
+    previous_status: prevStatus,
+    verification: t.verification,
+    gap_closure: prevStatus === "verified" && target === "planned",
+    duration_ms: 0,
+    extra: { verification: t.verification, gap_closure: prevStatus === "verified" && target === "planned" }
+  });
+
   output({
     ok: true,
     phase: s.phase,
@@ -597,6 +657,137 @@ function cmdFix(opts) {
   });
 }
 
+function cmdValidatePlan(opts) {
+  const phase = parseInt(opts.phase) || 1;
+  const planFile = path.join(PLANNING, `phase-${phase}-plan.md`);
+
+  if (!fs.existsSync(planFile)) {
+    return output(fail("MISSING_FILE", `Plan file not found: ${planFile}`));
+  }
+
+  const content = fs.readFileSync(planFile, "utf8");
+  const errors = [];
+
+  // Check frontmatter exists
+  if (!/^---\n/.test(content)) {
+    errors.push("Missing frontmatter (---) at start of file");
+  }
+
+  // Check task count > 0
+  const taskHeaders = content.match(/^## Task \d+/gm);
+  if (!taskHeaders || taskHeaders.length === 0) {
+    errors.push("No task headers found (expected '## Task N — title')");
+  }
+
+  // Check "Done when" exists for each task
+  const taskCount = taskHeaders ? taskHeaders.length : 0;
+  const doneWhenCount = (content.match(/\*\*Done when:\*\*/g) || []).length;
+  if (doneWhenCount < taskCount) {
+    errors.push(
+      `${taskCount} tasks but only ${doneWhenCount} 'Done when:' entries`
+    );
+  }
+
+  // Check Success Criteria section exists
+  if (!/## Success Criteria/m.test(content)) {
+    errors.push("Missing '## Success Criteria' section");
+  }
+
+  // Check goal in frontmatter
+  if (!/^goal:/m.test(content)) {
+    errors.push("Missing 'goal:' in frontmatter");
+  }
+
+  // ─── Verification Contract Validation (non-blocking) ────
+  const warnings = [];
+  const VALID_CHECK_TYPES = ["file-exists", "grep-match", "command-exit", "behavioral"];
+  let contractCount = 0;
+
+  if (/^## Verification Contract/m.test(content)) {
+    // Extract the contract section (from header to next ## or end of file)
+    const contractSectionMatch = content.match(
+      /^## Verification Contract\s*\n([\s\S]+)/m
+    );
+    if (contractSectionMatch) {
+      // Trim at the next ## heading that isn't ### (i.e., a new top-level section)
+      let contractSection = contractSectionMatch[1];
+      const nextH2 = contractSection.search(/\n## (?!#)/);
+      if (nextH2 !== -1) contractSection = contractSection.substring(0, nextH2);
+      // Each contract starts with ### Contract for Task N
+      const contractBlocks = contractSection.match(/^### Contract for Task \d+/gm);
+      contractCount = contractBlocks ? contractBlocks.length : 0;
+
+      if (contractCount === 0) {
+        warnings.push("Verification Contract section exists but contains no contract blocks (expected '### Contract for Task N')");
+      } else {
+        // Split into individual contract blocks for validation
+        const blockSplits = contractSection.split(/^(?=### Contract for Task \d+)/m).filter(Boolean);
+        for (const block of blockSplits) {
+          const taskNumMatch = block.match(/^### Contract for Task (\d+)/);
+          if (!taskNumMatch) continue;
+          const taskNum = taskNumMatch[1];
+
+          const checkTypeMatch = block.match(/\*\*Check type:\*\*\s*(.+)/);
+          const hasCommand = /\*\*Command:\*\*/.test(block);
+          const hasExpected = /\*\*Expected:\*\*/.test(block);
+          const hasFailIf = /\*\*Fail if:\*\*/.test(block);
+
+          if (!checkTypeMatch) {
+            warnings.push(`Contract for Task ${taskNum}: missing 'Check type'`);
+          } else {
+            const checkType = checkTypeMatch[1].trim().toLowerCase();
+            if (!VALID_CHECK_TYPES.includes(checkType)) {
+              warnings.push(
+                `Contract for Task ${taskNum}: invalid check type '${checkType}' (valid: ${VALID_CHECK_TYPES.join(", ")})`
+              );
+            }
+            // behavioral type doesn't require Command or Expected
+            const isBehavioral = checkType === "behavioral";
+            if (!isBehavioral && !hasCommand) {
+              warnings.push(`Contract for Task ${taskNum}: missing 'Command' (required for ${checkType})`);
+            }
+            if (!isBehavioral && !hasExpected) {
+              warnings.push(`Contract for Task ${taskNum}: missing 'Expected' (required for ${checkType})`);
+            }
+          }
+
+          if (!hasFailIf) {
+            warnings.push(`Contract for Task ${taskNum}: missing 'Fail if'`);
+          }
+        }
+      }
+
+      // Warn if contract count < task count
+      if (taskCount > 0 && contractCount > 0 && contractCount < taskCount) {
+        warnings.push(
+          `Only ${contractCount} contract(s) for ${taskCount} task(s) — not all tasks have verification contracts`
+        );
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return output({
+      ok: false,
+      error: "PLAN_VALIDATION_FAILED",
+      phase,
+      errors,
+      warnings: warnings.length > 0 ? warnings : undefined,
+      message: `Plan file has ${errors.length} issue(s)`,
+    });
+  }
+
+  output({
+    ok: true,
+    action: "validate-plan",
+    phase,
+    task_count: taskCount,
+    done_when_count: doneWhenCount,
+    contract_count: contractCount,
+    warnings: warnings.length > 0 ? warnings : undefined,
+  });
+}
+
 // ─── Output ──────────────────────────────────────────────
 function output(obj) {
   console.log(JSON.stringify(obj, null, 2));
@@ -620,11 +811,14 @@ switch (cmd) {
   case "fix":
     cmdFix(opts);
     break;
+  case "validate-plan":
+    cmdValidatePlan(opts);
+    break;
   default:
     output(
       fail(
         "UNKNOWN_COMMAND",
-        `Usage: state.js <check|transition|init|fix> [--options]`
+        `Usage: state.js <check|transition|init|fix|validate-plan> [--options]`
       )
     );
 }