qualia-framework-v2 2.8.0 → 2.9.0

package/README.md

@@ -16,6 +16,7 @@ Enter your team code when prompted. Get your code from Fawzi.
 ```bash
 npx qualia-framework-v2 version    # Check installed version + updates
 npx qualia-framework-v2 update     # Update to latest (remembers your code)
+npx qualia-framework-v2 uninstall  # Clean removal from ~/.claude/
 ```
 
 ## Usage
@@ -115,4 +116,8 @@ npx qualia-framework-v2 install
 
 Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel.
 
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for the full version history.
+
 Built by [Qualia Solutions](https://qualiasolutions.net) — Nicosia, Cyprus.

package/bin/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
-const { execSync } = require("child_process");
+const { spawnSync } = require("child_process");
 const path = require("path");
 const fs = require("fs");
+const readline = require("readline");
 
 const TEAL = "\x1b[38;2;0;206;209m";
 const TG = "\x1b[38;2;0;170;175m";
@@ -57,10 +58,17 @@ function cmdVersion() {
 
   // Check for updates
   try {
-    const latest = execSync("npm view qualia-framework-v2 version 2>/dev/null", {
-      encoding: "utf8",
+    // spawnSync with argv — no bash-only `2>/dev/null` redirect, no shell
+    // interpolation. stdio: "ignore" on stderr silences any npm warnings
+    // (offline, proxy, etc.) without a shell redirect. shell: true on
+    // Windows because `npm` is a .cmd shim that only resolves through cmd.
+    const r = spawnSync("npm", ["view", "qualia-framework-v2", "version"], {
+      stdio: ["ignore", "pipe", "ignore"],
+      shell: process.platform === "win32",
       timeout: 5000,
-    }).trim();
+      encoding: "utf8",
+    });
+    const latest = (r.stdout || "").trim();
     const semverGt = (a, b) => {
       const pa = a.split(".").map(Number), pb = b.split(".").map(Number);
       for (let i = 0; i < 3; i++) { if (pa[i] > pb[i]) return true; if (pa[i] < pb[i]) return false; }
@@ -94,7 +102,6 @@ function cmdUpdate() {
   console.log("");
 
   try {
-    const { spawnSync } = require("child_process");
     const r = spawnSync("npx", ["qualia-framework-v2@latest", "install"], {
       input: cfg.code + "\n",
       stdio: ["pipe", "inherit", "inherit"],
@@ -113,6 +120,253 @@ function cmdUpdate() {
   }
 }
 
+// ─── Uninstall ───────────────────────────────────────────
+// Surgical removal of the Qualia Framework from ~/.claude/.
+// Preserves CLAUDE.md (user may have customized it) and preserves any
+// non-Qualia entries in settings.json (other hooks, user env vars, etc.).
+// --yes / -y skips the confirmation prompt for scripted use.
+
+// 8 Qualia hook filenames — only these are removed from ~/.claude/hooks/,
+// any other hooks the user dropped in there are left alone.
+const QUALIA_HOOK_FILES = [
+  "session-start.js",
+  "auto-update.js",
+  "branch-guard.js",
+  "pre-push.js",
+  "block-env-edit.js",
+  "migration-guard.js",
+  "pre-deploy-gate.js",
+  "pre-compact.js",
+];
+
+// 4 Qualia agents — only these are removed.
+const QUALIA_AGENT_FILES = ["planner.md", "builder.md", "verifier.md", "qa-browser.md"];
+
+// 3 Qualia bin scripts.
+const QUALIA_BIN_FILES = ["state.js", "qualia-ui.js", "statusline.js"];
+
+// 4 Qualia rules.
+const QUALIA_RULE_FILES = ["security.md", "frontend.md", "design-reference.md", "deployment.md"];
+
+function promptYesNo(question, defaultYes) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const suffix = defaultYes ? " (Y/n)" : " (y/N)";
+    rl.question(`  ${WHITE}${question}${RESET}${suffix} `, (answer) => {
+      rl.close();
+      const a = String(answer || "").trim().toLowerCase();
+      if (!a) return resolve(defaultYes);
+      resolve(a === "y" || a === "yes");
+    });
+  });
+}
+
+function safeUnlink(p, counters) {
+  try {
+    if (fs.existsSync(p)) {
+      fs.unlinkSync(p);
+      counters.filesRemoved++;
+    }
+  } catch (e) {
+    counters.errors.push(`${p}: ${e.message}`);
+  }
+}
+
+function safeRmDir(p, counters) {
+  try {
+    if (fs.existsSync(p)) {
+      fs.rmSync(p, { recursive: true, force: true });
+      counters.dirsRemoved++;
+    }
+  } catch (e) {
+    counters.errors.push(`${p}: ${e.message}`);
+  }
+}
+
+function cleanSettingsJson(counters) {
+  const settingsPath = path.join(CLAUDE_DIR, "settings.json");
+  if (!fs.existsSync(settingsPath)) return;
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+  } catch (e) {
+    counters.errors.push(`settings.json: ${e.message}`);
+    return;
+  }
+
+  // Only remove entries that point at qualia paths. Leave everything else.
+  const isQualiaCommand = (cmd) =>
+    typeof cmd === "string" && (cmd.includes("qualia") || cmd.includes(".claude/hooks/") || cmd.includes(".claude/bin/"));
+
+  const filterHookArray = (arr) => {
+    if (!Array.isArray(arr)) return arr;
+    return arr
+      .map((entry) => {
+        if (!entry || !Array.isArray(entry.hooks)) return entry;
+        const hooks = entry.hooks.filter((h) => !isQualiaCommand(h && h.command));
+        return { ...entry, hooks };
+      })
+      .filter((entry) => Array.isArray(entry.hooks) && entry.hooks.length > 0);
+  };
+
+  if (settings.hooks && typeof settings.hooks === "object") {
+    for (const key of ["SessionStart", "PreToolUse", "PreCompact"]) {
+      if (settings.hooks[key]) {
+        const cleaned = filterHookArray(settings.hooks[key]);
+        if (cleaned && cleaned.length > 0) {
+          settings.hooks[key] = cleaned;
+        } else {
+          delete settings.hooks[key];
+        }
+      }
+    }
+    // If hooks is now empty, remove it entirely.
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  }
+
+  // Status line — only drop it if it points at our renderer.
+  if (settings.statusLine && typeof settings.statusLine === "object") {
+    const cmd = settings.statusLine.command || "";
+    if (isQualiaCommand(cmd) || cmd.includes("statusline.js") || cmd.includes("qualia-ui")) {
+      delete settings.statusLine;
+    }
+  }
+
+  // Qualia-specific spinner overrides.
+  if (settings.spinnerVerbs) delete settings.spinnerVerbs;
+  if (settings.spinnerTipsOverride) delete settings.spinnerTipsOverride;
+
+  // Leave settings.env alone — the user may have other env vars in there.
+
+  try {
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    counters.settingsCleaned = true;
+  } catch (e) {
+    counters.errors.push(`settings.json write: ${e.message}`);
+  }
+}
+
+async function cmdUninstall() {
+  banner();
+
+  const args = process.argv.slice(3);
+  const skipConfirm = args.includes("-y") || args.includes("--yes");
+
+  const cfg = readConfig();
+  console.log("");
+  if (cfg.installed_by) {
+    console.log(`  ${DIM}User:${RESET} ${WHITE}${cfg.installed_by}${RESET} ${DIM}(${cfg.role || "?"})${RESET}`);
+  } else {
+    console.log(`  ${DIM}No Qualia config found at${RESET} ${WHITE}${CONFIG_FILE}${RESET}`);
+  }
+  console.log("");
+
+  if (!skipConfirm) {
+    const confirm = await promptYesNo("Are you sure you want to uninstall the Qualia Framework?", false);
+    if (!confirm) {
+      console.log("");
+      console.log(`  ${DIM}Aborted.${RESET}`);
+      console.log("");
+      return;
+    }
+  }
+
+  // Preserve knowledge base by default.
+  let preserveKnowledge = true;
+  if (!skipConfirm) {
+    preserveKnowledge = await promptYesNo(
+      "Preserve knowledge base? (your learned patterns, fixes, client prefs)",
+      true
+    );
+  }
+
+  console.log("");
+  console.log(`  ${DIM}Removing framework files...${RESET}`);
+  console.log("");
+
+  const counters = { filesRemoved: 0, dirsRemoved: 0, settingsCleaned: false, errors: [] };
+
+  // Skills — any directory starting with "qualia" under ~/.claude/skills/.
+  const skillsDir = path.join(CLAUDE_DIR, "skills");
+  try {
+    if (fs.existsSync(skillsDir)) {
+      for (const name of fs.readdirSync(skillsDir)) {
+        if (name === "qualia" || name.startsWith("qualia-")) {
+          safeRmDir(path.join(skillsDir, name), counters);
+        }
+      }
+    }
+  } catch (e) {
+    counters.errors.push(`skills scan: ${e.message}`);
+  }
+
+  // Agents — only the 4 Qualia ones.
+  for (const f of QUALIA_AGENT_FILES) {
+    safeUnlink(path.join(CLAUDE_DIR, "agents", f), counters);
+  }
+
+  // Hooks — only the 8 Qualia ones.
+  for (const f of QUALIA_HOOK_FILES) {
+    safeUnlink(path.join(CLAUDE_DIR, "hooks", f), counters);
+  }
+
+  // Bin scripts — only the 3 Qualia ones.
+  for (const f of QUALIA_BIN_FILES) {
+    safeUnlink(path.join(CLAUDE_DIR, "bin", f), counters);
+  }
+
+  // Rules — all 4.
+  for (const f of QUALIA_RULE_FILES) {
+    safeUnlink(path.join(CLAUDE_DIR, "rules", f), counters);
+  }
+
+  // Templates directory (entire).
+  safeRmDir(path.join(CLAUDE_DIR, "qualia-templates"), counters);
+
+  // Knowledge directory (optional preservation).
+  if (!preserveKnowledge) {
+    safeRmDir(path.join(CLAUDE_DIR, "knowledge"), counters);
+  }
+
+  // Config + state files.
+  safeUnlink(path.join(CLAUDE_DIR, ".qualia-config.json"), counters);
+  safeUnlink(path.join(CLAUDE_DIR, ".qualia-last-update-check"), counters);
+  safeUnlink(path.join(CLAUDE_DIR, ".erp-api-key"), counters);
+  safeUnlink(path.join(CLAUDE_DIR, "qualia-guide.md"), counters);
+
+  // Clean settings.json surgically.
+  cleanSettingsJson(counters);
+
+  // Summary.
+  console.log("");
+  console.log(`${TEAL}  ◆ Uninstall complete${RESET}`);
+  console.log(`${DIM}  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
+  console.log(`  ${DIM}Files removed:${RESET}       ${WHITE}${counters.filesRemoved}${RESET}`);
+  console.log(`  ${DIM}Directories removed:${RESET} ${WHITE}${counters.dirsRemoved}${RESET}`);
+  console.log(
+    `  ${DIM}settings.json:${RESET}       ${counters.settingsCleaned ? `${GREEN}cleaned ✓${RESET}` : `${DIM}not present${RESET}`}`
+  );
+  if (preserveKnowledge) {
+    console.log(`  ${DIM}Knowledge base:${RESET}      ${GREEN}preserved ✓${RESET}`);
+  } else {
+    console.log(`  ${DIM}Knowledge base:${RESET}      ${YELLOW}removed${RESET}`);
+  }
+
+  if (counters.errors.length > 0) {
+    console.log("");
+    console.log(`  ${YELLOW}${counters.errors.length} warning(s):${RESET}`);
+    for (const err of counters.errors.slice(0, 5)) {
+      console.log(`    ${DIM}${err}${RESET}`);
+    }
+  }
+
+  console.log("");
+  console.log(
+    `  ${YELLOW}Manual step:${RESET} edit ${WHITE}~/.claude/CLAUDE.md${RESET} to remove the Qualia Framework section if desired.`
+  );
+  console.log("");
+}
+
 function cmdHelp() {
   banner();
   console.log("");
@@ -120,6 +374,7 @@ function cmdHelp() {
   console.log(`    npx qualia-framework-v2 ${TEAL}install${RESET}     Install or reinstall the framework`);
   console.log(`    npx qualia-framework-v2 ${TEAL}update${RESET}      Update to the latest version`);
   console.log(`    npx qualia-framework-v2 ${TEAL}version${RESET}     Show installed version + check for updates`);
+  console.log(`    npx qualia-framework-v2 ${TEAL}uninstall${RESET}   Clean removal from ~/.claude/ (${DIM}-y to skip prompts${RESET})`);
   console.log("");
   console.log(`  ${WHITE}After install:${RESET}`);
   console.log(`    ${TG}/qualia${RESET}          What should I do next?`);
@@ -151,6 +406,13 @@ switch (cmd) {
   case "upgrade":
     cmdUpdate();
     break;
+  case "uninstall":
+  case "remove":
+    cmdUninstall().catch((e) => {
+      console.error(`${RED}  ✗ Uninstall failed: ${e.message}${RESET}`);
+      process.exit(1);
+    });
+    break;
   default:
     cmdHelp();
 }

package/bin/install.js

@@ -80,14 +80,32 @@ function askCode() {
   });
 }
 
+// ─── Resolve team code (tolerates case + O/0 typo in suffix) ─
+// Accepts "qs-fawzi-01", "QS-FAWZI-01", "QS-FAWZI-O1" (letter O in the
+// numeric suffix), and returns the canonical key if found, else null.
+// Only normalizes O→0 in the segment AFTER the last dash — "QS-MOAYAD-03"
+// contains a real "O" in the name and must not be mangled.
+function resolveTeamCode(input) {
+  const normalized = String(input || "").trim().toUpperCase();
+  if (TEAM[normalized]) return normalized;
+  const fuzzy = normalized.replace(
+    /-([^-]*)$/,
+    (_, suffix) => `-${suffix.replace(/O/g, "0")}`
+  );
+  if (TEAM[fuzzy]) return fuzzy;
+  return null;
+}
+
 // ─── Main ────────────────────────────────────────────────
 async function main() {
-  const code = await askCode();
-  const member = TEAM[code];
+  const rawCode = await askCode();
+  const code = resolveTeamCode(rawCode);
+  const member = code ? TEAM[code] : null;
 
   if (!member) {
     console.log("");
-    log(`${RED}✗${RESET} Invalid code. Get your install code from Fawzi.`);
+    log(`${RED}✗${RESET} Invalid code: "${rawCode}". Get your install code from Fawzi.`);
+    log(`${DIM}  Tip: codes use digit zero, not letter O. Format: QS-NAME-01${RESET}`);
     console.log("");
     process.exit(1);
   }
@@ -248,9 +266,84 @@ async function main() {
   const knowledgeDir = path.join(CLAUDE_DIR, "knowledge");
   if (!fs.existsSync(knowledgeDir)) fs.mkdirSync(knowledgeDir, { recursive: true });
   const knowledgeFiles = {
-    "learned-patterns.md": "# Learned Patterns\n\nPatterns discovered across projects. Updated by `/qualia-learn` and manual notes.\n",
-    "common-fixes.md": "# Common Fixes\n\nRecurring issues and their solutions.\n",
-    "client-prefs.md": "# Client Preferences\n\nClient-specific preferences, design choices, and requirements.\n",
+    "learned-patterns.md": `# Learned Patterns
+
+Patterns discovered across projects. Updated by \`/qualia-learn\` and manual notes.
+
+---
+
+## Cross-platform Node: always spawnSync with argv, never execSync with shell strings
+**Why:** \`execSync(\\\`node \${path}/state.js check 2>/dev/null\\\`)\` breaks on Windows when the path contains spaces (common: \`C:\\\\Users\\\\John Doe\`) and the \`2>/dev/null\` redirect is bash-only. Windows cmd.exe tries to create \`\\\\dev\\\\null\` at drive root.
+**How:** Use \`spawnSync(process.execPath, [path, "check"], { stdio: ["ignore","pipe","ignore"] })\`. Argv array is immune to path splitting; \`stdio: "ignore"\` silences stderr without shell redirection.
+
+---
+
+## Cross-platform stdin piping: spawnSync with input:, not bash <<< here-strings
+**Why:** The \`<<<\` bash here-string works on bash + zsh but fails silently on Windows cmd.exe AND on Debian/Ubuntu where \`/bin/sh\` is dash (no \`<<<\` support).
+**How:** \`spawnSync("npx", ["cmd"], { input: "data\\\\n", stdio: ["pipe","inherit","inherit"], shell: process.platform === "win32" })\`. The \`input:\` option pipes stdin directly. \`shell: process.platform === "win32"\` is required because npm/npx are \`.cmd\` shims on Windows that only resolve through a shell.
+
+---
+
+## Fresh-context isolation beats shared-context compression
+**Why:** Claude's output quality degrades as context fills. A single massive context doing plan + build + verify hits the degradation curve on the later tasks.
+**How:** Spawn separate subagents for planner / builder (per task) / verifier. Each gets fresh context. Task 50 gets the same quality as task 1. Cost: PROJECT.md + STATE.md get re-loaded into each subagent context, but the quality win dominates.
+
+---
+
+## Goal-backward verification beats task-completion tracking
+**Why:** A task "create chat component" can be marked complete with a placeholder file. The task ran; the goal didn't.
+**How:** For each phase success criterion, do a 3-level check: (1) what must be TRUE, (2) what files/functions must EXIST and be substantive (not stubs), (3) what must be CONNECTED (imported and called). Grep the codebase. Never trust summaries.
+`,
+    "common-fixes.md": `# Common Fixes
+
+Recurring issues and their solutions.
+
+---
+
+## Install code "Invalid" — user typed letter O instead of digit 0
+**Symptom:** \`npx qualia-framework-v2 install\` rejects \`QS-NAME-O1\` (letter O in suffix).
+**Cause:** Team codes use digit zero (\`-01\`, \`-02\`, etc.), not letter O.
+**Fix:** Since v2.8.1, install.js auto-normalizes: \`QS-FAWZI-O1\` → \`QS-FAWZI-01\`. The normalization only touches the segment after the last dash, so \`QS-MOAYAD-03\` (real O in name) is preserved.
+**Framework version:** Fixed in v2.8.1.
+
+---
+
+## Windows banner shows "No project detected" inside a real project
+**Symptom:** The session-start banner from qualia-ui.js displays the router panel but without phase/status, even in a project with \`.planning/\`.
+**Cause:** Before v2.8.0, \`qualia-ui.js\` called state.js via \`execSync(\\\`node \${path} check 2>/dev/null\\\`)\`. Windows cmd.exe couldn't parse the \`2>/dev/null\` redirect and/or split the path on spaces in the username.
+**Fix:** v2.8.0 switched to \`spawnSync(process.execPath, [statePath, "check"], { stdio: ["ignore","pipe","ignore"] })\`. Argv array + silent stdio = cross-platform safe.
+**Framework version:** Fixed in v2.8.0.
+
+---
+
+## \`npx qualia-framework-v2 update\` fails on Windows or Ubuntu
+**Symptom:** Manual update command fails silently or with a shell parse error on Windows and Debian/Ubuntu.
+**Cause:** Before v2.8.0, cli.js cmdUpdate used \`execSync(\\\`npx ... install <<< "\${code}"\\\`, { shell: true })\`. The \`<<<\` here-string is bash-only; cmd.exe doesn't understand it, and \`/bin/sh\` on Debian/Ubuntu is \`dash\` which also lacks it.
+**Fix:** v2.8.0 replaced with \`spawnSync("npx", [...], { input: code + "\\\\n", shell: process.platform === "win32" })\`. Uses stdin pipe instead of here-string.
+**Framework version:** Fixed in v2.8.0.
+
+---
+
+## Pre-deploy gate false-positive on Next.js Server Components using service_role
+**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 as of v2.8.1; better heuristic planned for v3.0.
+`,
+    "client-prefs.md": `# Client Preferences
+
+Client-specific preferences, design choices, and requirements. Loaded by \`/qualia-new\` when starting a project for a known client.
+
+---
+
+## Example Client (template)
+**Industry:** {e.g., fintech, healthcare, SaaS}
+**Contact:** {email}
+**Design:** {dark-bold | clean-minimal | colorful-playful | corporate-professional}
+**Stack preferences:** {anything non-default}
+**Hard constraints:** {things they've explicitly said no to}
+**Source of notes:** {date or conversation reference}
+`,
   };
   for (const [name, defaultContent] of Object.entries(knowledgeFiles)) {
     const dest = path.join(knowledgeDir, name);

package/bin/state.js

@@ -51,19 +51,54 @@ function readState() {
 // ─── STATE.md Parser ─────────────────────────────────────
 function parseStateMd(content) {
   if (!content) return null;
+  const schema_errors = [];
   const get = (prefix) => {
     const m = content.match(new RegExp(`^${prefix}:\\s*(.+)$`, "m"));
     return m ? m[1].trim() : "";
   };
+  const hasField = (prefix) =>
+    new RegExp(`^${prefix}:\\s*`, "m").test(content);
+
   const phaseMatch = content.match(
     /^Phase:\s*(\d+)\s+of\s+(\d+)\s*[—-]\s*(.+)$/m
   );
+  if (!phaseMatch) {
+    schema_errors.push({
+      field: "phase_header",
+      message: 'Missing or malformed "Phase: N of M — Name" header',
+      severity: "error",
+    });
+  }
+
+  // Status field presence (independent of value)
+  if (!hasField("Status")) {
+    schema_errors.push({
+      field: "status_field",
+      message: "Missing Status: field",
+      severity: "warning",
+    });
+  }
+
   // Parse roadmap table
   const phases = [];
+  const tableHeaderRe = /\| # \| Phase \| Goal \| Status \|/;
   const tableMatch = content.match(
     /\| # \| Phase \| Goal \| Status \|\n\|[-|]+\|\n([\s\S]*?)(?=\n##|\n$|$)/
   );
-  if (tableMatch) {
+  if (!tableHeaderRe.test(content)) {
+    schema_errors.push({
+      field: "roadmap_table",
+      message: "Roadmap table header not found",
+      severity: "error",
+    });
+  } else if (!tableMatch) {
+    // Header is there but the separator row or body is malformed
+    schema_errors.push({
+      field: "roadmap_table",
+      message: "Roadmap table is malformed (missing separator row or body)",
+      severity: "error",
+    });
+  } else {
     for (const row of tableMatch[1].trim().split("\n")) {
       const cols = row.split("|").map((c) => c.trim()).filter(Boolean);
       if (cols.length >= 4) {
@@ -76,6 +111,19 @@ function parseStateMd(content) {
       }
     }
   }
+
+  // Row count vs header "of M"
+  if (phaseMatch) {
+    const declaredTotal = parseInt(phaseMatch[2]);
+    if (phases.length && phases.length !== declaredTotal) {
+      schema_errors.push({
+        field: "roadmap_rows",
+        message: `Expected ${declaredTotal} phases in roadmap, found ${phases.length}`,
+        severity: "warning",
+      });
+    }
+  }
+
   return {
     phase: phaseMatch ? parseInt(phaseMatch[1]) : 1,
     total_phases: phaseMatch ? parseInt(phaseMatch[2]) : phases.length || 1,
@@ -83,6 +131,7 @@ function parseStateMd(content) {
     status: get("Status").toLowerCase().replace(/\s+/g, "_") || "setup",
     assigned_to: get("Assigned to") || "",
     phases,
+    schema_errors,
   };
 }
 
@@ -254,6 +303,7 @@ function cmdCheck(opts) {
       s.total_phases,
       t.verification
     ),
+    schema_errors: s.schema_errors && s.schema_errors.length ? s.schema_errors : undefined,
   });
 }
 
@@ -269,6 +319,16 @@ function cmdTransition(opts) {
     );
   }
 
+  // Refuse transitions if STATE.md has schema errors (severity=error)
+  if (s.schema_errors && s.schema_errors.some((e) => e.severity === "error")) {
+    return output(
+      fail(
+        "STATE_SCHEMA_ERROR",
+        "STATE.md is malformed. Run `node state.js check` to see errors. Consider `state.js fix` to rewrite canonically."
+      )
+    );
+  }
+
   // Special: note/activity (no status change)
   if (target === "note" || target === "activity") {
     const now = new Date().toISOString().split("T")[0];
@@ -466,6 +526,77 @@ function cmdInit(opts) {
   });
 }
 
+function cmdFix(opts) {
+  const raw = readState();
+  const t = readTracking();
+  if (!raw && !t) {
+    return output(
+      fail("NO_PROJECT", "No .planning/ found. Run /qualia-new.")
+    );
+  }
+  const parsed = parseStateMd(raw) || {
+    phase: 1,
+    total_phases: 1,
+    phase_name: "",
+    status: "setup",
+    assigned_to: "",
+    phases: [],
+    schema_errors: [
+      { field: "content", message: "STATE.md missing or empty", severity: "error" },
+    ],
+  };
+  const previousErrors = (parsed.schema_errors || []).length;
+
+  // Prefer tracking.json values when parsed fields are defaulted/missing
+  const tr = t || {};
+  const totalPhases =
+    parseInt(tr.total_phases) || parsed.total_phases || parsed.phases.length || 1;
+  const phaseNum = parseInt(tr.phase) || parsed.phase || 1;
+  const phaseName =
+    (parsed.phase_name && parsed.phase_name.trim()) ||
+    tr.phase_name ||
+    `Phase ${phaseNum}`;
+  const status = parsed.status || tr.status || "setup";
+  const assignedTo = parsed.assigned_to || tr.assigned_to || "";
+
+  // Build a phases array of the right length
+  const phases = [];
+  for (let i = 0; i < totalPhases; i++) {
+    const existing = parsed.phases[i];
+    phases.push({
+      num: i + 1,
+      name: existing?.name || `Phase ${i + 1}`,
+      goal: existing?.goal || "TBD",
+      status: existing?.status || (i === 0 ? "ready" : "—"),
+    });
+  }
+
+  const s = {
+    phase: phaseNum,
+    total_phases: totalPhases,
+    phase_name: phaseName,
+    status,
+    assigned_to: assignedTo,
+    last_activity: "STATE.md repaired by state.js fix",
+    phases,
+    blockers: "None.",
+    resume: "—",
+  };
+
+  try {
+    writeStateMd(s);
+  } catch (e) {
+    return output(fail("WRITE_ERROR", e.message));
+  }
+
+  output({
+    ok: true,
+    action: "fix",
+    previous_errors: previousErrors,
+    fixed: true,
+  });
+}
+
 // ─── Output ──────────────────────────────────────────────
 function output(obj) {
   console.log(JSON.stringify(obj, null, 2));
@@ -486,11 +617,14 @@ switch (cmd) {
   case "init":
     cmdInit(opts);
     break;
+  case "fix":
+    cmdFix(opts);
+    break;
   default:
     output(
       fail(
         "UNKNOWN_COMMAND",
-        `Usage: state.js <check|transition|init> [--options]`
+        `Usage: state.js <check|transition|init|fix> [--options]`
       )
     );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework-v2",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework-v2": "./bin/cli.js"
@@ -19,11 +19,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/qualia-solutions/qualia-framework-v2"
+    "url": "git+https://github.com/Qualiasolutions/qualia-framework-v2.git"
   },
-  "homepage": "https://github.com/qualia-solutions/qualia-framework-v2#readme",
+  "homepage": "https://github.com/Qualiasolutions/qualia-framework-v2#readme",
   "scripts": {
-    "test": "bash tests/hooks.test.sh && bash tests/state.test.sh"
+    "test": "bash tests/hooks.test.sh && bash tests/state.test.sh && bash tests/bin.test.sh && bash tests/statusline.test.sh"
   },
   "files": [
     "bin/",