qualia-framework 6.7.1 → 6.8.1

package/bin/install.js

@@ -210,13 +210,22 @@ function ensureCodexStatusLineConfig(existing) {
   return `${next.slice(0, tuiMatch.index)}${tuiBlock}${next.slice(tuiMatch.index + tuiMatch[0].length)}`;
 }
 
+// v6.8.1: .bak files go into a backups/ subdir next to the target instead of
+// littering the target's directory (a dozen settings.json.bak.* files were
+// accumulating in ~/.claude root across reinstalls).
+function bakPath(dest) {
+  const dir = path.join(path.dirname(dest), "backups");
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  return path.join(dir, `${path.basename(dest)}.bak.${ts}`);
+}
+
 function backupIfDifferent(dest, nextContent, label) {
   if (!fs.existsSync(dest)) return false;
   try {
     const existing = fs.readFileSync(dest, "utf8");
     if (existing === nextContent) return false;
-    const ts = new Date().toISOString().replace(/[:.]/g, "-");
-    const bak = `${dest}.bak.${ts}`;
+    const bak = bakPath(dest);
     fs.copyFileSync(dest, bak);
     ok(`Backed up existing ${label} -> ${path.basename(bak)}`);
     return true;
@@ -343,7 +352,10 @@ function cleanupLegacyV26() {
 // ─── Branded Header ─────────────────────────────────────
 const BOLD = "\x1b[1m";
 const TEAL_GLOW = "\x1b[38;2;0;170;175m";
-const PKG_VERSION = require("../package.json").version;
+// Defensive: the installed copy may lack a root package.json (Wave 1.2 writes one
+// post-install, but a partially-stripped install must not MODULE_NOT_FOUND here).
+let PKG_VERSION = "0.0.0";
+try { PKG_VERSION = require("../package.json").version; } catch {}
 const RULE = "━".repeat(48);
 
 function printHeader() {
@@ -672,7 +684,17 @@ async function main() {
   // doctor remains, but only strips the OLD legacy command (which our v2
   // hook does not match — different content, same filename is fine because
   // install always overwrites).
-  const DEPRECATED_HOOKS = ["block-env-edit.js"];
+  const DEPRECATED_HOOKS = [
+    "block-env-edit.js",
+    // Retired "brain" hooks from an abandoned experiment — never shipped in
+    // hooksSource, so the orphan-purge below also catches them; listed here as
+    // belt-and-suspenders for installs predating the orphan pass.
+    "brain-pre-compact.js",
+    "brain-session-end.js",
+    "brain-session-start.js",
+    // v6.8.1: the UserPromptSubmit half of the brain experiment was missed.
+    "brain-inject.js",
+  ];
   for (const f of DEPRECATED_HOOKS) {
     const p = path.join(hooksDest, f);
     try { if (fs.existsSync(p)) fs.unlinkSync(p); } catch {}
@@ -688,6 +710,16 @@ async function main() {
       warn(`${file} — ${e.message}`);
     }
   }
+  // Orphan purge (idempotency): remove any .js hook in the dest that the
+  // framework no longer ships, so retired hooks don't keep firing after upgrade.
+  try {
+    const srcHooks = new Set(fs.readdirSync(hooksSource).filter((f) => f.endsWith(".js")));
+    for (const f of fs.readdirSync(hooksDest).filter((f) => f.endsWith(".js"))) {
+      if (!srcHooks.has(f)) {
+        try { fs.unlinkSync(path.join(hooksDest, f)); warn(`pruned orphan hook ${f}`); } catch {}
+      }
+    }
+  } catch {}
 
   // ─── Templates (recursive — supports nested projects/ and research-project/) ─
   printSection("Templates");
@@ -761,6 +793,16 @@ async function main() {
         warn(`${file} — ${e.message}`);
       }
     }
+    // Canonical copy: qualia-scope + constitution read references/archetypes/*.md
+    // from CLAUDE_DIR/references (not qualia-references). Copy the whole tree
+    // recursively so nested dirs like archetypes/ land at the canonical path.
+    try {
+      const refDestCanonical = path.join(CLAUDE_DIR, "references");
+      copyTreeTransform(refDir, refDestCanonical, claudeText);
+      ok("references/ (canonical tree incl. archetypes/)");
+    } catch (e) {
+      warn(`references/ canonical — ${e.message}`);
+    }
   } else {
     log(`${DIM}(no references/ in framework — skipping)${RESET}`);
   }
@@ -789,9 +831,8 @@ async function main() {
     if (fs.existsSync(claudeDest)) {
       const existing = fs.readFileSync(claudeDest, "utf8");
       if (existing !== claudeMd) {
-        const ts = new Date().toISOString().replace(/[:.]/g, "-");
-        const bak = `${claudeDest}.bak.${ts}`;
-        try { fs.copyFileSync(claudeDest, bak); ok(`Backed up existing CLAUDE.md → ${path.basename(bak)}`); } catch {}
+        const bak = bakPath(claudeDest);
+        try { fs.copyFileSync(claudeDest, bak); ok(`Backed up existing CLAUDE.md → backups/${path.basename(bak)}`); } catch {}
       }
     }
     fs.writeFileSync(claudeDest, claudeText(claudeMd), "utf8");
@@ -811,6 +852,21 @@ async function main() {
       try { fs.chmodSync(out, 0o755); } catch {}
       ok(script.label);
     }
+    // v6.8.1: purge retired bin scripts (same belt-and-suspenders as
+    // DEPRECATED_HOOKS — bin/ never had an orphan pass, so the brain
+    // experiment's indexer survived reinstalls).
+    const DEPRECATED_BIN = ["build-brain-index.js"];
+    for (const f of DEPRECATED_BIN) {
+      const p = path.join(binDest, f);
+      try { if (fs.existsSync(p)) fs.unlinkSync(p); } catch {}
+    }
+    // Write a minimal root package.json so the installed CLI's `require("../package.json")`
+    // resolves post-install (bin/ lives at CLAUDE_DIR/bin, so the parent is CLAUDE_DIR).
+    fs.writeFileSync(
+      path.join(CLAUDE_DIR, "package.json"),
+      JSON.stringify({ name: "qualia-framework-install", version: PKG_VERSION, private: true }, null, 2) + "\n",
+    );
+    ok("package.json (root version marker)");
   } catch (e) {
     warn(`scripts — ${e.message}`);
   }
@@ -827,6 +883,16 @@ async function main() {
     warn(`guide.md — ${e.message}`);
   }
 
+  // ─── Companion docs (read by skills/agents + linked from guide.md) ─────
+  for (const doc of ["SOUL.md", "FLAGS.md", "TROUBLESHOOTING.md", "CHANGELOG.md"]) {
+    try {
+      copyTextTransform(path.join(FRAMEWORK_DIR, doc), path.join(CLAUDE_DIR, doc), claudeText);
+      ok(doc);
+    } catch (e) {
+      warn(`${doc} — ${e.message}`);
+    }
+  }
+
   // ─── Knowledge directory ─────────────────────────────────
   printSection("Knowledge Base");
   const knowledgeDir = path.join(CLAUDE_DIR, "knowledge");
@@ -993,6 +1059,9 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     } catch {}
   }
 
+  // Schema marker for editor validation / autocomplete of settings.json.
+  settings["$schema"] = "https://json.schemastore.org/claude-code-settings.json";
+
   // Env
   if (!settings.env) settings.env = {};
   Object.assign(settings.env, {
@@ -1008,7 +1077,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     // context exists in the current session; verifier and plan-checker still
     // use blank-context spawns to avoid the "kid grading their own homework"
     // failure mode.
-    CLAUDE_AGENT_FORK_ENABLED: "1",
+    CLAUDE_CODE_FORK_SUBAGENT: "1",
   });
 
   // Status line
@@ -1091,7 +1160,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
           { type: "command", command: nodeCmd("fawzi-approval-guard.js"), timeout: 5 },
           { type: "command", if: "Bash(git push*)", command: nodeCmd("branch-guard.js"), timeout: 5, statusMessage: "⬢ Checking branch permissions..." },
           { type: "command", if: "Bash(git push*)", command: nodeCmd("pre-push.js"), timeout: 15, statusMessage: "⬢ Syncing tracking..." },
-          { type: "command", if: "Bash(vercel --prod*)", command: nodeCmd("pre-deploy-gate.js"), timeout: 180, statusMessage: "⬢ Running quality gates..." },
+          { type: "command", if: "Bash(vercel --prod*)", command: nodeCmd("pre-deploy-gate.js"), timeout: 600, statusMessage: "⬢ Running quality gates..." },
           // v5.0 hooks — insights-driven friction prevention
           { type: "command", if: "Bash(vercel --prod*)|Bash(vercel deploy*)", command: nodeCmd("vercel-account-guard.js"), timeout: 8, statusMessage: "⬢ Verifying Vercel account..." },
           { type: "command", if: "Bash(vercel env*)", command: nodeCmd("env-empty-guard.js"), timeout: 5, statusMessage: "⬢ Checking env value..." },
@@ -1153,10 +1222,50 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     }
   }
 
+  // v6.8.1: sweep ALL hook events for retired Qualia hooks and dead node
+  // paths. The merge above only visits events present in qualiaHooks, so
+  // entries under other events (e.g. the retired brain-inject.js under
+  // UserPromptSubmit) survived every reinstall — firing a failing node
+  // process on each user prompt. Runs after the hooks/ install, so an
+  // existsSync miss means the file is truly gone, not not-yet-copied.
+  const DEPRECATED_HOOK_CMDS = [
+    "brain-inject.js", "build-brain-index.js", "block-env-edit.js",
+    "brain-pre-compact.js", "brain-session-end.js", "brain-session-start.js",
+  ];
+  const isDeadHookCmd = (cmd) => {
+    if (typeof cmd !== "string") return false;
+    if (DEPRECATED_HOOK_CMDS.some((f) => cmd.includes(f))) return true;
+    const m = cmd.match(/^node "([^"]+)"$/);
+    if (m && m[1].startsWith(CLAUDE_DIR + path.sep) && !fs.existsSync(m[1])) return true;
+    return false;
+  };
+  for (const event of Object.keys(settings.hooks)) {
+    const blocks = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+    const cleaned = [];
+    for (const block of blocks) {
+      if (!block || !Array.isArray(block.hooks)) continue;
+      const kept = block.hooks.filter((h) => !isDeadHookCmd(h && h.command));
+      if (kept.length > 0) cleaned.push({ ...block, hooks: kept });
+    }
+    if (cleaned.length > 0) settings.hooks[event] = cleaned;
+    else delete settings.hooks[event];
+  }
+
   // Permissions stay permissive; Qualia policy enforcement happens in hooks so
-  // OWNER overrides and EMPLOYEE blocks can share one source of truth.
+  // OWNER overrides and EMPLOYEE blocks can share one source of truth. We still
+  // seed a scoped baseline allow-list (union-merged, never clobbering user
+  // entries) so common safe tooling has an explicit allow surface rather than
+  // an empty array that matches nothing.
   if (!settings.permissions) settings.permissions = {};
-  if (!settings.permissions.allow) settings.permissions.allow = [];
+  const QUALIA_DEFAULT_ALLOW = [
+    "Bash(git *)", "Bash(gh *)", "Bash(npx supabase *)",
+    "Bash(vercel *)", "Bash(npx tsc*)", "Bash(npm run *)",
+    "Read(*)", "Grep(*)", "Glob(*)",
+  ];
+  if (!Array.isArray(settings.permissions.allow)) settings.permissions.allow = [];
+  for (const a of QUALIA_DEFAULT_ALLOW) {
+    if (!settings.permissions.allow.includes(a)) settings.permissions.allow.push(a);
+  }
   if (!settings.permissions.deny) settings.permissions.deny = [];
 
   // ─── Optional: next-devtools MCP ─────────────────────────
@@ -1176,9 +1285,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
   // configs / custom permissions. Atomic write (tmp + rename) avoids partial
   // writes; the .bak file is the recovery point if the merger ever misbehaves.
   if (fs.existsSync(settingsPath)) {
-    const ts = new Date().toISOString().replace(/[:.]/g, "-");
-    const bak = `${settingsPath}.bak.${ts}`;
-    try { fs.copyFileSync(settingsPath, bak); } catch {}
+    try { fs.copyFileSync(settingsPath, bakPath(settingsPath)); } catch {}
   }
   const settingsTmp = `${settingsPath}.tmp.${process.pid}`;
   fs.writeFileSync(settingsTmp, JSON.stringify(settings, null, 2));
@@ -1542,7 +1649,7 @@ async function installCodex(member, target) {
               { type: "command", command: nodeCmd("fawzi-approval-guard.js"), timeout: 5 },
               { 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("pre-deploy-gate.js"), timeout: 600 },
               { 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 },

package/bin/runtime-manifest.js

@@ -18,6 +18,7 @@ const RUNTIME_BIN_SCRIPTS = [
   { file: "erp-retry.js", label: "erp-retry.js (ERP report retry queue — drained by session-start hook and erp-flush CLI)" },
   { file: "work-packet.js", label: "work-packet.js (ERP mission/work packet pull + local reader)" },
   { file: "report-payload.js", label: "report-payload.js (Framework -> ERP report payload builder)" },
+  { file: "auto-report.js", label: "auto-report.js (B1 ship-time auto-report)" },
   { file: "project-snapshot.js", label: "project-snapshot.js (ERP/admin project progress snapshot)" },
   { file: "trust-score.js", label: "trust-score.js (harness health scoring)" },
   { file: "harness-eval.js", label: "harness-eval.js (project eval scoring + evidence artifact)" },

package/bin/security-scan.js

@@ -192,7 +192,7 @@ function categoryScore(findings) {
   return { weighted_sum: ws, score: Math.max(1, 5 - Math.floor(ws / 8)), counts };
 }
 
-function renderMarkdown({ findings, paths, score }) {
+function renderMarkdown({ findings, paths, score, skipped = [] }) {
   const lines = [];
   lines.push(`# Qualia security scan — ${new Date().toISOString()}`);
   lines.push("");
@@ -202,10 +202,16 @@ function renderMarkdown({ findings, paths, score }) {
   lines.push(`**Score:** ${score.score} / 5 (weighted_sum=${score.weighted_sum})`);
   lines.push("");
 
-  if (findings.length === 0) {
+  if (skipped.length > 0) {
+    lines.push(`⚠️ **${skipped.length} file(s) could not be scanned** — result is NOT clean (score degraded, non-zero exit):`);
+    for (const s of skipped) lines.push(`- \`${s.file}\` — ${s.error}`);
+    lines.push("");
+  }
+
+  if (findings.length === 0 && skipped.length === 0) {
     lines.push("✅ Clean.");
     lines.push("");
-  } else {
+  } else if (findings.length > 0) {
     findings.sort((a, b) => severityOrder(a.severity) - severityOrder(b.severity));
     for (const f of findings) {
       lines.push(`### [${f.severity}] ${f.name}`);
@@ -346,6 +352,7 @@ function main() {
   const paths = args.paths || defaultPaths();
   const findings = [];
   const scanned = [];
+  const skipped = [];
 
   for (const p of paths) {
     try {
@@ -356,14 +363,21 @@ function main() {
       const content = fs.readFileSync(p, "utf8");
       scanned.push(p);
       findings.push(...scanContent(p, content));
-    } catch {}
+    } catch (e) { skipped.push({ file: p, error: e.message }); }
   }
 
   const score = categoryScore(findings);
+  // An unreadable file must not silently pass as clean. Degrade the score
+  // (min 1) and force a non-clean exit when any target could not be scanned.
+  if (skipped.length > 0) score.score = Math.max(1, score.score - 1);
+
+  // A scan that couldn't read every target must not exit clean — surface at
+  // least HIGH (1) so an unreadable file can't slip through a CI gate as 0.
+  const exitCode = skipped.length > 0 ? Math.max(1, exitCodeFor(findings)) : exitCodeFor(findings);
 
   if (args.json) {
-    process.stdout.write(JSON.stringify({ findings, scanned, score }, null, 2) + "\n");
-    process.exit(exitCodeFor(findings));
+    process.stdout.write(JSON.stringify({ findings, scanned, skipped, score }, null, 2) + "\n");
+    process.exit(exitCode);
   }
 
   // --deep emits a prompt pack for the /qualia-secure skill to spawn agents.
@@ -373,17 +387,17 @@ function main() {
     try { fs.mkdirSync(planningDir, { recursive: true }); } catch {}
     const staticPath = path.join(planningDir, "security-scan.md");
     const promptPath = path.join(planningDir, "security-deep-prompt.md");
-    fs.writeFileSync(staticPath, renderMarkdown({ findings, paths: scanned, score }));
+    fs.writeFileSync(staticPath, renderMarkdown({ findings, paths: scanned, score, skipped }));
     fs.writeFileSync(promptPath, renderDeepPromptPack({ findings, scanned, score }));
     console.log(`Wrote ${staticPath}`);
     console.log(`Wrote ${promptPath}`);
     console.log("");
     console.log("Now run `/qualia-secure` in a Claude session — it will read the prompt pack");
     console.log("and spawn the red/blue/auditor agents in parallel.");
-    process.exit(exitCodeFor(findings));
+    process.exit(exitCode);
   }
 
-  const md = renderMarkdown({ findings, paths: scanned, score });
+  const md = renderMarkdown({ findings, paths: scanned, score, skipped });
   if (args.write) {
     const outDefault = path.join(process.cwd(), ".planning", "security-scan.md");
     const out = args.writePath || outDefault;
@@ -395,7 +409,7 @@ function main() {
     process.stdout.write(md);
   }
 
-  process.exit(exitCodeFor(findings));
+  process.exit(exitCode);
 }
 
 module.exports = { main, scanContent, defaultPaths, categoryScore, renderDeepPromptPack, SECRET_PATTERNS, CONFIG_SMELLS };

package/bin/trust-score.js

@@ -4,6 +4,7 @@
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
+const { spawnSync } = require("child_process");
 const pc = require("./plan-contract.js");
 const ledger = require("./state-ledger.js");
 const { binFiles } = require("./runtime-manifest.js");
@@ -16,6 +17,12 @@ const HOMES = [
 
 const REQUIRED_BIN = binFiles();
 
+// Spine scripts: the load-bearing executables that, if they fail to even parse,
+// render the install dead. binFiles() does not include these, so probe them
+// explicitly — existence AND Node loadability (`--check`). A syntax-broken
+// cli.js (the C1 regression) must force overall status off PASS.
+const SPINE_SCRIPTS = ["cli.js", "install.js", "state.js"];
+
 const REQUIRED_HOOKS = [
   "session-start.js", "auto-update.js", "branch-guard.js", "pre-push.js",
   "pre-deploy-gate.js", "migration-guard.js", "git-guardrails.js",
@@ -54,10 +61,27 @@ function inspectInstall(homes) {
     return { status: "fail", score: 0, issues: ["no Qualia install config found"], targets: [] };
   }
   const issues = [];
+  let spineBroken = false;
   for (const home of homes) {
     for (const f of REQUIRED_BIN) {
       if (!exists(path.join(home.dir, "bin", f))) issues.push(`${home.name}: missing bin/${f}`);
     }
+    // Spine probe: Node loadability of spine scripts that ARE installed.
+    // cli.js / install.js run via npx / the installer and are not part of the
+    // runtime manifest, so their ABSENCE is not a failure (state.js absence is
+    // already reported via REQUIRED_BIN). But any spine script that IS present
+    // must pass `--check` — a syntax-broken installed spine forces status off
+    // PASS (this is the check that catches a dead cli.js).
+    for (const f of SPINE_SCRIPTS) {
+      const fp = path.join(home.dir, "bin", f);
+      if (!exists(fp)) continue;
+      const r = spawnSync(process.execPath, ["--check", fp], { encoding: "utf8" });
+      if (r.status !== 0) {
+        const detail = (r.stderr || r.error?.message || "").split("\n")[0].trim();
+        issues.push(`${home.name}: spine bin/${f} fails --check${detail ? ` (${detail})` : ""}`);
+        spineBroken = true;
+      }
+    }
     if (home.name === "Claude") {
       if (!exists(path.join(home.dir, "CLAUDE.md"))) issues.push("Claude: missing CLAUDE.md");
       if (!exists(path.join(home.dir, "settings.json"))) issues.push("Claude: missing settings.json");
@@ -67,6 +91,16 @@ function inspectInstall(homes) {
       if (!exists(path.join(home.dir, "config.toml"))) issues.push("Codex: missing config.toml");
     }
   }
+  // A broken spine is a hard failure: the install cannot run. Force fail status
+  // (drives overall status to FAIL) and zero the score regardless of other issues.
+  if (spineBroken) {
+    return {
+      status: "fail",
+      score: 0,
+      issues,
+      targets: homes.map((h) => h.name),
+    };
+  }
   return {
     status: issues.length ? "degraded" : "pass",
     score: issues.length ? Math.max(6, 20 - issues.length * 2) : 20,

package/hooks/migration-guard.js

@@ -161,12 +161,12 @@ if (realCreateTables.length > 0 && !/ENABLE\s+ROW\s+LEVEL\s+SECURITY/i.test(scan
 }
 
 if (errors.length > 0) {
-  console.log("⬢ Migration guard — dangerous patterns found:");
+  console.error("⬢ Migration guard — dangerous patterns found:");
   for (const e of errors) {
-    console.log(`  ✗ ${e}`);
+    console.error(`  ✗ ${e}`);
   }
-  console.log("");
-  console.log("Fix these before proceeding. If intentional, ask Fawzi to approve.");
+  console.error("");
+  console.error("Fix these before proceeding. If intentional, ask Fawzi to approve.");
   _trace("migration-guard", "block", { errors });
   process.exit(2);
 }

package/hooks/pre-deploy-gate.js

@@ -73,7 +73,7 @@ function runGate(label, cmd, args, { required = true } = {}) {
   const r = spawnSync(cmd, args, {
     stdio: ["ignore", "pipe", "pipe"],
     encoding: "utf8",
-    timeout: 180000,
+    timeout: 120000,
     shell: process.platform === "win32",
   });
   if (r.status === 0) {
@@ -170,7 +170,10 @@ function enforceShipPolicy() {
 
   // If this is not a Qualia-managed project, keep the legacy behavior: run the
   // quality/security gates but do not invent state.
-  if (!state || !status) return;
+  if (!state || !status) {
+    console.error("⬢ pre-deploy-gate: no ship-state (brownfield) — skipping ship-policy gate, quality gates still run");
+    return;
+  }
 
   const shippable = status === "polished" || (status === "verified" && verification === "pass");
   if (!shippable && !force) {
@@ -281,9 +284,16 @@ if (fs.existsSync("tsconfig.json")) {
 }
 
 // Lint (with QUALIA_SKIP_LINT=1 escape — for the documented "lint blocks
-// ship" friction when the lint failures are pre-existing or auto-fixer-broken)
+// ship" friction when the lint failures are pre-existing or auto-fixer-broken).
+// The skip is OWNER-only, mirroring the QUALIA_SHIP_FORCE role-gate above.
 if (hasScript("lint")) {
-  if (process.env.QUALIA_SKIP_LINT === "1") {
+  const skipLint = process.env.QUALIA_SKIP_LINT === "1";
+  const lintRole = String(readConfig().role || "").toUpperCase();
+  if (skipLint && lintRole !== "OWNER") {
+    const lintState = readState();
+    blockDeploy("QUALIA_SKIP_LINT is OWNER-only.", (lintState && lintState.next_command) || "/qualia");
+  }
+  if (skipLint) {
     console.log("  ⚠ Lint skipped (QUALIA_SKIP_LINT=1)");
     _trace("pre-deploy-gate", "skip-lint", { reason: "QUALIA_SKIP_LINT=1" });
   } else {

package/hooks/stop-session-log.js

@@ -91,13 +91,16 @@ try {
   // dedupe marker, so it's a cheap no-op on every turn except the one right
   // after a ship. Wrapped + unref'd so it never blocks or breaks the session.
   try {
-    const { spawn } = require("child_process");
-    const child = spawn(
-      process.execPath,
-      [path.join(__dirname, "..", "bin", "auto-report.js")],
-      { cwd: process.cwd(), detached: true, stdio: "ignore" },
-    );
-    child.unref();
+    const autoReportPath = path.join(__dirname, "..", "bin", "auto-report.js");
+    if (fs.existsSync(autoReportPath)) {
+      const { spawn } = require("child_process");
+      const child = spawn(
+        process.execPath,
+        [autoReportPath],
+        { cwd: process.cwd(), detached: true, stdio: "ignore" },
+      );
+      child.unref();
+    }
   } catch {}
 
   // ── Skip if too soon since last write ────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "6.7.1",
+  "version": "6.8.1",
   "description": "Claude Code and Codex workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -54,7 +54,11 @@
     "docs/onboarding.html",
     "CLAUDE.md",
     "AGENTS.md",
-    "guide.md"
+    "guide.md",
+    "SOUL.md",
+    "FLAGS.md",
+    "TROUBLESHOOTING.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18"

package/qualia-design/design-rubric.md

@@ -33,7 +33,7 @@ A whole-app `/qualia-polish` scores all 9 dimensions across multiple representat
 
 | Score | Criteria |
 |---|---|
-| 1 | Inter / Roboto / Arial / system-ui / Space Grotesk as primary. Or single weight throughout. |
+| 1 | Banned font as primary — Inter / Roboto / Arial / Helvetica / system-ui / Space Grotesk / Montserrat / Poppins / Lato / Open Sans. Or single weight throughout. |
 | 2 | Project font loaded but only one weight, no scale, no letter-spacing variation. |
 | 3 | Project font with 2-3 weights, basic scale (h1/h2/body), readable. |
 | 4 | Distinctive display + refined body pair. Letter-spacing varied semantically (tight headlines, open labels). Tabular numerals on numeric data. |
@@ -41,6 +41,8 @@ A whole-app `/qualia-polish` scores all 9 dimensions across multiple representat
 
 Evidence format: `font-family: "<name>" used at line N, scale 14/16/24/40 visible, weights 400/500/700`
 
+The banned-font list above is the machine-enforced counterpart of `bin/slop-detect.mjs` (the static anti-pattern scanner) and `agents/visual-evaluator.md` (the vision evaluator). All three are kept in lockstep — Inter, Roboto, Arial, Helvetica, system-ui, Space Grotesk, Montserrat, Poppins, Lato, Open Sans.
+
 ### 2. Color cohesion
 
 | Score | Criteria |

package/rules/architecture.md

@@ -119,7 +119,7 @@ Read this file (auto-load via skill or `@rules/architecture.md`) when:
 
 - Planning a new module or feature with multiple components.
 - The user requests `/qualia-optimize --deepen` or `--alignment`.
-- A verifier is scoring "Container depth & nesting" (per `rules/design-rubric.md` dimension 8).
+- A verifier is scoring "Container depth & nesting" (per `qualia-design/design-rubric.md` dimension 8).
 - An ADR is being drafted for an architectural fork.
 
 Do **not** auto-load this on quick fixes, copy edits, single-component touch-ups — that wastes instruction budget. Use judgment.

package/rules/grounding.md

@@ -102,7 +102,9 @@ Every skill that spawns an agent must order the prompt from most-stable to most-
 - Per-task content goes LAST. Mixing task-specific files into `<phase_context>` breaks cache on every spawn within the same wave.
 - Reference files via `@path` when the harness auto-expands, OR inline the content — but pick one and stick with it per section (switching styles breaks prefix match).
 
-## Design Quality Rubric (any dimension < 3 = mandatory fix before commit)
+## Design Quality Rubric (pre-commit SUBSET — any dimension < 3 = mandatory fix before commit)
+
+> This 6-dimension table (Typography, Color, Spacing, States, Responsiveness, Accessibility) is the fast pre-commit gate every agent runs inline. It is a **deliberate SUBSET** of the authoritative 9-dimension rubric at `@qualia-design/design-rubric.md` (Typography, Color cohesion, Spatial rhythm, Layout originality, Shadow & depth, Motion intent, Microcopy specificity, Container depth & nesting, Visual system & graphics). For verifier scoring and `/qualia-polish --critique`, the 9-dimension rubric is authoritative — read it, don't score from this subset.
 
 | Dimension       | 1 (Fail)                                | 3 (Acceptable)                           | 5 (Excellent)                              |
 |-----------------|-----------------------------------------|------------------------------------------|--------------------------------------------|

package/rules/speed.md

@@ -26,14 +26,14 @@ MCP servers impose a **token tax**: their tool definitions consume context-windo
 - The MCP returns structured JSON that would be expensive to parse from CLI text output.
 - The MCP enforces governance (RLS-aware queries, scoped DB credentials) that the CLI doesn't.
 
-If a `/skill-name` exists that wraps a CLI, prefer the skill — it's been hardened. Canonical example: `/supabase` skill replaces 32 supabase MCP tools with `supabase` CLI calls and saves substantial token budget.
+If a `/skill-name` exists that wraps a CLI, prefer the skill — it's been hardened. Canonical example: drive Supabase through `npx supabase` (migrations, type generation, local dev, SQL) instead of the Supabase MCP — the CLI hits the same API at zero token cost and replaces the bulk of the MCP tool surface (see `infrastructure.md`).
 
 ### MCP tier-list (when each is justified)
 
 | Server | Always-on? | Justification |
 |---|---|---|
 | `claude-in-chrome` | On-demand | Browser automation has no CLI equivalent; use for QA flows only |
-| `supabase` MCP | **Off** in favor of `/supabase` skill | CLI covers 95% of operations; MCP only if you need branch management interactively |
+| `supabase` MCP | **Off** in favor of `npx supabase` CLI | CLI covers 95% of operations; MCP only if you need branch management interactively |
 | `context7` | On-demand | Library docs at runtime — no CLI alternative for Context7 itself |
 | `notebooklm-mcp` | On-demand | NotebookLM has no CLI; only loaded when researching against existing notebooks |
 | `firecrawl-mcp` | On-demand | Web scraping; only loaded when feature requires it |

package/skills/qualia-idk/SKILL.md

@@ -207,13 +207,13 @@ With all three reports + `<user_confusion>` + `<session_context>` in hand, produ
 |---|---|
 | Plan says built but code has stubs | `/qualia-plan {N} --gaps` → `/qualia-build` → `/qualia-verify` |
 | Verify FAILed and no postmortem ran | `/qualia-postmortem` → `/qualia-plan {N} --gaps` → `/qualia-build` |
-| Stale `.continue-here.md`, ongoing context | `/qualia-resume` → `/qualia` |
+| Stale `.continue-here.md`, ongoing context | `/qualia` (restores from `.continue-here.md` / STATE.md) |
 | Brownfield drift (plan and code diverged hard) | `/qualia-map` → `/qualia-plan {N} --gaps` |
 | Phase context missing (no `/qualia-scope` ran) | `/qualia-scope {N}` → `/qualia-plan {N}` |
 | Specific error, scope clear | `/qualia-fix '<symptom>'` |
 | Performance feels off, no profile | `/qualia-fix --perf '<route>'` or `/qualia-optimize --perf` |
 | Design feels off | `/qualia-polish --critique` then `/qualia-polish` |
-| User is overwhelmed | `/qualia-pause` (save handoff), come back later |
+| User is overwhelmed | `/qualia-handoff` (save handoff), come back later |
 | Truly nothing actionable found | Ask one specific question; don't invent a sequence |
 
 Pick the sequence that fits the actual evidence. Substitute real `{N}` from the Plan-view scan.
@@ -240,6 +240,6 @@ node ${QUALIA_BIN}/qualia-ui.js end "DIAGNOSED" "{first command in the sequence,
 - User knows what they're doing and just wants the next command → `/qualia`
 - User has a specific error message they want fixed → `/qualia-fix '<symptom>'`
 - User wants to review code quality → `/qualia-review`
-- User wants to pause and come back → `/qualia-pause`
+- User wants to pause and come back → `/qualia-handoff`
 
 `/qualia-idk` is specifically for **"I'm not sure what I'm even looking at"** situations. Route to sharper tools when the question is sharper.