qualia-framework 7.0.1 → 7.2.0

package/CHANGELOG.md

@@ -8,6 +8,82 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > Note: git tags for historical versions were not retained; commit references are approximate
 > and dates reflect commit history rather than npm publish timestamps.
 
+## [7.2.0] - 2026-06-25 (journey spine — lifecycle UX for employees)
+
+A cosmetic/UX layer that gives an employee a continuous sense of place and
+momentum across the whole lifecycle — install → start → work → finish — reusing
+the existing teal palette and glyph set. No new commands to learn; the framework
+just shows "where am I, what's my forward motion, what's the one next move" at
+every touchpoint.
+
+### Added
+- **`qualia-ui.js spine`** — compact horizontal milestone ladder
+  (`M1 ●──M2 ◆──M3 ○`) with a caret aligned exactly beneath the current
+  milestone. Rendered by the session-start banner so the journey map is the
+  first thing an employee sees. Self-skips on single-milestone projects.
+- **`qualia-ui.js onboard <name>`** — first-run mental-model card (Plan → Build
+  → Verify → Ship + the one first move). Shown after install for non-OWNER
+  roles only.
+- **`qualia-ui.js phase-complete <n> <name> [k=v…]`** — per-phase celebration
+  with a milestone progress bar and optional streak; wired into `/qualia-ship`.
+- **`qualia-ui.js clockout <name> [k=v…]`** — end-of-day report card (shipped
+  counts, milestone %, streak); wired into `/qualia-report`. Every metric
+  self-omits when its data is unavailable — never fabricates.
+- **`barTicks(done,total,width)`** — reusable `▰▱` micro-bar helper.
+- **Always-visible progress in the statusline** — the phase pill now carries a
+  `▰▰▰▱▱` bar (`P3/5 ▰▰▰▱▱`) so forward motion is ambient while working.
+
+### Tests
+- New suite `journey-spine.test.sh` (33 cases): barTicks scaling/clamping, all
+  four cards, spine caret-alignment (exact column match), self-skip paths, and
+  the statusline bar. Full suite green: **28 shell suites + 179 node tests**.
+
+## [7.1.0] - 2026-06-25 (harness gates — hallucinated deps, secrets, model routing)
+
+Hardening pass: reviewed Google's "The New SDLC With Vibe Coding" whitepaper
+against the framework, then ran a deep multi-agent audit of the result and fixed
+what it surfaced. Theme: move enforcement out of model-read prose and into
+deterministic gates.
+
+### Added
+- **`bin/dep-verify.mjs` — hallucinated/slopsquatted dependency gate.** Flags an
+  import only when its package is BOTH undeclared in `package.json` AND absent
+  from `node_modules` — the paper's #1 named AI-generated-code security failure
+  mode. A string/regex/comment-aware parser with statement-anchored matching
+  keeps false positives near zero. Wired into `/qualia-verify`, `/qualia-ship`,
+  and the `pre-deploy-gate` hook (OWNER-only `QUALIA_SKIP_DEPCHECK` escape).
+- **`hooks/secret-guard.js` — commit-time secret gate.** Fail-closed PreToolUse
+  hook on `git commit*` that scans staged content for service_role keys, private
+  keys, AWS/OpenAI/GitHub tokens, and staged `.env` files; blocks (exit 2),
+  never prints the matched value, OWNER-only `QUALIA_SECRET_SKIP` escape.
+  Enforces two constitution non-negotiables that were prose-only. Registered on
+  both runtimes; added to `trust-score` REQUIRED_HOOKS.
+- **Intelligent model routing.** `/qualia-build` builders default to `sonnet`
+  (escalate to frontier for architect / high-complexity / auth-payment-migration;
+  `haiku` for mechanical sweeps); `/qualia-verify` panel verifiers run on
+  `sonnet`, skeptic adjudication on frontier. The token-economy OpEx lever.
+- **`tests/runtime-parity.test.sh`.** Asserts the Codex blocking-gate set is a
+  superset of the critical gates so Claude/Codex hook drift can't recur.
+
+### Fixed
+- **Deploy gates now fail CLOSED.** `pre-deploy-gate` blocked only on exit 1, so a
+  scanner crash or timeout printed "✓" and deployed anyway; both the anti-slop and
+  dep-verify blocks now block on any non-clean outcome.
+- **Codex gate parity.** `task-write-guard.js` (the off-contract-write gate) was
+  registered on Claude but omitted from the Codex hooks — so on Codex a builder
+  could write fabricated/out-of-scope files unblocked. Now registered on both.
+- **A5 failed-status gap closure (`state.js`).** The A5 increment path sets status
+  `"failed"` on a failed verify (legacy keeps `"verified"`+fail); the gap-cycle
+  circuit breaker, the re-plan transition (`VALID_FROM`), the gap-cycle counter,
+  and `next_command` all only recognized `"verified"` — so the breaker never fired
+  (unbounded gap cycles), re-plan was rejected, and routing dead-ended at
+  `/qualia`. All four spots now recognize `"failed"`.
+
+### Tests
+- New suites: dep-verify, secret-guard, runtime-parity; A5 regression cases in
+  `state.test.sh`; pre-deploy-gate fail-closed + dep cases in `hooks.test.sh`.
+- Full suite green: **27 shell suites + 179 node tests**.
+
 ## [7.0.1] - 2026-06-22 (/qualia-recall is OWNER-only)
 
 ### Changed — `/qualia-recall` restricted to OWNER

package/bin/cli.js

@@ -214,6 +214,7 @@ const QUALIA_HOOK_FILES = [
   "env-empty-guard.js",
   "supabase-destructive-guard.js",
   "vercel-account-guard.js",
+  "secret-guard.js",
 ];
 const QUALIA_LEGACY_HOOK_FILES = [
   "block-env-edit.js", // removed in v3.2.0
@@ -712,6 +713,7 @@ function cmdMigrate() {
     "vercel-account-guard.js",
     "env-empty-guard.js",
     "supabase-destructive-guard.js",
+    "secret-guard.js",
   ];
   const requiredEditHooks = ["migration-guard.js"];
 
@@ -747,6 +749,7 @@ function cmdMigrate() {
       if (hookFile === "vercel-account-guard.js") { hookDef.if = "Bash(vercel --prod*)|Bash(vercel deploy*)"; hookDef.timeout = 8; hookDef.statusMessage = "⬢ Verifying Vercel account..."; }
       if (hookFile === "env-empty-guard.js") { hookDef.if = "Bash(vercel env*)"; hookDef.statusMessage = "⬢ Checking env value..."; }
       if (hookFile === "supabase-destructive-guard.js") { hookDef.if = "Bash(supabase*)|Bash(npx supabase*)"; hookDef.statusMessage = "⬢ Checking Supabase safety..."; }
+      if (hookFile === "secret-guard.js") { hookDef.if = "Bash(git commit*)"; hookDef.timeout = 10; hookDef.statusMessage = "⬢ Scanning staged content for secrets..."; }
       bashEntry.hooks.push(hookDef);
       changes++;
       console.log(`  ${GREEN}+${RESET} Wired ${hookFile} into PreToolUse/Bash`);
@@ -1011,7 +1014,9 @@ async function cmdErpPing() {
     project: "qualia-framework-erp-ping",
     project_id: "ping",
     team_id: "qualia-solutions",
-    client_report_id: "QS-PING-00",
+    // client_report_id intentionally omitted: ERP only accepts a QS-REPORT-NN
+    // form or an absent field. A synthetic "QS-PING-NN" is rejected (422). With
+    // it absent the server assigns a throwaway UUID — exactly what a dry-run ping wants.
     phase: 0,
     phase_name: "ping",
     status: "setup",

package/bin/dep-verify.mjs

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+/**
+ * dep-verify — Hallucinated / slopsquatted dependency scanner for Qualia projects.
+ *
+ * The harness gate that AI-generated code most often trips: importing a package
+ * that does not exist. The model invents a plausible name (`react-use-toast`),
+ * or typosquats a real one (`lodahs`), and the import only fails at install or
+ * runtime — long after the agent reported success. This scanner catches it at
+ * the verify/ship gate, deterministically and with zero network calls.
+ *
+ * The signal is precise: a bare import is flagged ONLY when its package is
+ * BOTH undeclared in package.json AND absent from node_modules. That is the
+ * exact signature of a hallucinated or slopsquatted dependency — and it keeps
+ * false positives near zero (phantom/hoisted deps that are actually installed
+ * are left alone).
+ *
+ * Usage:
+ *   node bin/dep-verify.mjs                       # scan repo from cwd
+ *   node bin/dep-verify.mjs src/app/page.tsx      # scan one file
+ *   node bin/dep-verify.mjs src/                   # scan a directory
+ *   node bin/dep-verify.mjs --json                 # machine-readable output
+ *   node bin/dep-verify.mjs --severity=critical    # parity flag (all findings are critical)
+ *
+ * Exit codes:
+ *   0  no undeclared/uninstalled imports
+ *   1  one or more hallucinated/slopsquatted imports found
+ *   2  invocation error
+ *
+ * Builder agents and the /qualia-verify + /qualia-ship gates call this BEFORE
+ * commit/deploy. A non-zero exit blocks. Pairs with slop-detect.mjs (design
+ * tells) — this is the correctness/security half of the same gate.
+ */
+
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join, extname, relative, resolve, dirname } from "node:path";
+import { argv, exit, cwd } from "node:process";
+import { builtinModules } from "node:module";
+
+// ── Config ────────────────────────────────────────────────────────────
+const SOURCE_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"]);
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", ".next", "out",
+  "coverage", ".turbo", ".vercel", "vendor", ".cache",
+]);
+// Node builtins, with and without the `node:` prefix.
+const BUILTINS = new Set([...builtinModules, ...builtinModules.map((m) => `node:${m}`)]);
+
+// ── Import extraction ─────────────────────────────────────────────────
+// A context-free comment regex is unsafe here: a `//` inside a string or
+// regex literal would erase the rest of the line (dropping a real import → a
+// silent miss), and import-looking text *inside* a string would be matched as
+// a live import (a false block). So we strip comments with a small scanner
+// that tracks string, template, and regex-literal state, then match imports
+// only at statement boundaries so syntax embedded in a string never counts.
+
+// Heuristic for whether a `/` begins a regex literal: it does when the last
+// significant code character is an operator/opener (not a value/identifier).
+function isRegexStart(prev) {
+  return prev === "" || "(,=:[!&|?{};+-*%^~<>".includes(prev);
+}
+
+// Remove // and /* */ comments while preserving strings, template literals,
+// and regex literals (and preserving newlines so line numbers are stable).
+function stripComments(src) {
+  let out = "";
+  let i = 0;
+  const n = src.length;
+  let state = "code"; // code | line | block | regex | sq | dq | tpl
+  let prevSig = "";   // last significant (non-whitespace) code char emitted
+  while (i < n) {
+    const c = src[i];
+    const c2 = src[i + 1];
+    if (state === "code") {
+      if (c === "/" && c2 === "/") { state = "line"; i += 2; continue; }
+      if (c === "/" && c2 === "*") { state = "block"; i += 2; continue; }
+      if (c === "/" && isRegexStart(prevSig)) { state = "regex"; out += c; i++; continue; }
+      if (c === "'") { state = "sq"; out += c; prevSig = c; i++; continue; }
+      if (c === '"') { state = "dq"; out += c; prevSig = c; i++; continue; }
+      if (c === "`") { state = "tpl"; out += c; prevSig = c; i++; continue; }
+      out += c;
+      if (!/\s/.test(c)) prevSig = c;
+      i++;
+      continue;
+    }
+    if (state === "line") {
+      if (c === "\n") { state = "code"; out += c; }
+      i++;
+      continue;
+    }
+    if (state === "block") {
+      if (c === "*" && c2 === "/") { state = "code"; i += 2; continue; }
+      if (c === "\n") out += c;
+      i++;
+      continue;
+    }
+    // regex literal or string: copy verbatim, honoring escapes.
+    out += c;
+    if (c === "\\") {
+      if (i + 1 < n) { out += src[i + 1]; i += 2; continue; }
+      i++;
+      continue;
+    }
+    if (state === "regex" && c === "/") { state = "code"; prevSig = "/"; }
+    else if (state === "sq" && c === "'") { state = "code"; prevSig = c; }
+    else if (state === "dq" && c === '"') { state = "code"; prevSig = c; }
+    else if (state === "tpl" && c === "`") { state = "code"; prevSig = c; }
+    i++;
+  }
+  return out;
+}
+
+// Statement-anchored so import/export keywords inside a string literal don't
+// match (they are preceded by a quote, not a statement boundary). `m` flag so
+// `^` anchors each line; the negated class spans multi-line import bodies.
+const ES_FROM_RE = /(?:^|[;{}])\s*(?:import|export)\b[^'";]*?from\s*['"]([^'"]+)['"]/gm;
+const BARE_IMPORT_RE = /(?:^|[;{}])\s*import\s*['"]([^'"]+)['"]/gm;
+// require()/import() can be inline; exclude member/identifier prefixes
+// (myRequire(, foo.import() ) via lookbehind.
+const CALL_RE = /(?<![\w$.])(?:require|import)\s*\(\s*['"]([^'"]+)['"]/g;
+
+function extractSpecifiers(source) {
+  const cleaned = stripComments(source);
+  const out = new Set();
+  for (const re of [ES_FROM_RE, BARE_IMPORT_RE, CALL_RE]) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(cleaned)) !== null) {
+      if (m[1]) out.add(m[1]);
+    }
+  }
+  return [...out];
+}
+
+// Resolve a raw specifier to its installable package name, or null if it is
+// not an external package (relative, absolute, alias, or subpath import).
+function packageName(spec) {
+  if (!spec) return null;
+  if (spec.startsWith(".") || spec.startsWith("/")) return null; // relative / absolute
+  if (spec.includes(":")) return null; // protocol specifiers: node:, virtual:, https:, data:, blob:
+  if (spec.startsWith("@/") || spec.startsWith("~/") || spec.startsWith("#")) return null; // common aliases / subpath imports
+  if (spec.startsWith("@")) {
+    const parts = spec.split("/");
+    return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : null; // @scope/name
+  }
+  return spec.split("/")[0]; // name (drop subpath)
+}
+
+// ── package.json + tsconfig discovery (walk up, cached) ───────────────
+const declaredCache = new Map();
+const aliasCache = new Map();
+
+function readJSONSafe(p) {
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// Union of declared deps from the nearest package.json walking up, plus the
+// top-most (repo-root) package.json to tolerate monorepo hoisting.
+function declaredDepsFor(fileDir) {
+  if (declaredCache.has(fileDir)) return declaredCache.get(fileDir);
+  const names = new Set();
+  let dir = fileDir;
+  let last = null;
+  while (true) {
+    const pj = join(dir, "package.json");
+    if (existsSync(pj)) {
+      const json = readJSONSafe(pj);
+      if (json) {
+        for (const field of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+          for (const k of Object.keys(json[field] || {})) names.add(k);
+        }
+      }
+      last = dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  declaredCache.set(fileDir, names);
+  return names;
+}
+
+// tsconfig/jsconfig path-alias prefixes (e.g. "@app/*" → "@app/").
+function aliasPrefixesFor(fileDir) {
+  if (aliasCache.has(fileDir)) return aliasCache.get(fileDir);
+  const prefixes = [];
+  let dir = fileDir;
+  while (true) {
+    for (const name of ["tsconfig.json", "jsconfig.json"]) {
+      const cfg = readJSONSafe(join(dir, name));
+      const paths = cfg?.compilerOptions?.paths;
+      if (paths) {
+        for (const key of Object.keys(paths)) {
+          // A wildcard alias ("@app/*") suppresses its subtree; a non-wildcard
+          // alias ("@env") suppresses only the exact specifier. Without this
+          // distinction a bare "@utils" would wrongly swallow "@utils-extended/server".
+          if (key.endsWith("*")) {
+            const p = key.replace(/\*$/, "");
+            prefixes.push({ wild: true, value: p.endsWith("/") ? p : `${p}/` });
+          } else {
+            prefixes.push({ wild: false, value: key });
+          }
+        }
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  aliasCache.set(fileDir, prefixes);
+  return prefixes;
+}
+
+// Is the package physically installed in any node_modules up the tree?
+function isInstalled(fileDir, pkg) {
+  let dir = fileDir;
+  while (true) {
+    if (existsSync(join(dir, "node_modules", pkg))) return true;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return false;
+}
+
+// ── File walking ──────────────────────────────────────────────────────
+function collectFiles(target) {
+  let st;
+  try {
+    st = statSync(target);
+  } catch {
+    return null; // signal: path does not exist
+  }
+  if (st.isFile()) return SOURCE_EXT.has(extname(target)) ? [target] : [];
+  const files = [];
+  const walk = (d) => {
+    let entries;
+    try {
+      entries = readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name)) walk(join(d, e.name));
+      } else if (e.isFile() && SOURCE_EXT.has(extname(e.name))) {
+        files.push(join(d, e.name));
+      }
+    }
+  };
+  walk(target);
+  return files;
+}
+
+// ── Scan ──────────────────────────────────────────────────────────────
+function scanFile(file) {
+  const findings = [];
+  let source;
+  try {
+    source = readFileSync(file, "utf8");
+  } catch {
+    return findings;
+  }
+  const fileDir = dirname(resolve(file));
+  const declared = declaredDepsFor(fileDir);
+  const aliases = aliasPrefixesFor(fileDir);
+  const seen = new Set();
+  for (const spec of extractSpecifiers(source)) {
+    if (aliases.some((a) => (a.wild ? spec.startsWith(a.value) : spec === a.value))) continue;
+    const pkg = packageName(spec);
+    if (!pkg) continue;
+    if (BUILTINS.has(pkg) || BUILTINS.has(spec)) continue;
+    if (declared.has(pkg)) continue;
+    if (isInstalled(fileDir, pkg)) continue;
+    if (seen.has(pkg)) continue; // one finding per package per file
+    seen.add(pkg);
+    findings.push({ file: relative(cwd(), file), package: pkg, specifier: spec });
+  }
+  return findings;
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────
+function main() {
+  const args = argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("dep-verify — flags imports that are neither declared in package.json nor installed.");
+    console.log("Usage: node bin/dep-verify.mjs [paths...] [--json] [--severity=critical]");
+    exit(0);
+  }
+  const json = args.includes("--json");
+  const paths = args.filter((a) => !a.startsWith("--") && !a.startsWith("-"));
+  const targets = paths.length ? paths : [cwd()];
+
+  const allFiles = [];
+  for (const t of targets) {
+    const files = collectFiles(t);
+    if (files === null) {
+      if (json) console.log(JSON.stringify({ ok: false, error: "ENOENT", path: t }, null, 2));
+      else console.error(`dep-verify: path not found: ${t}`);
+      exit(2);
+    }
+    allFiles.push(...files);
+  }
+
+  const findings = [];
+  for (const f of allFiles) findings.push(...scanFile(f));
+
+  if (json) {
+    console.log(JSON.stringify({ ok: findings.length === 0, scanned: allFiles.length, findings }, null, 2));
+  } else if (findings.length === 0) {
+    console.log(`dep-verify: ${allFiles.length} file(s) scanned — no hallucinated dependencies.`);
+  } else {
+    console.error(`dep-verify: ${findings.length} hallucinated/slopsquatted import(s) — undeclared AND not installed:\n`);
+    for (const f of findings) {
+      console.error(`  ✗ ${f.file}`);
+      console.error(`      imports "${f.specifier}" → package "${f.package}" is not in package.json and not in node_modules`);
+    }
+    console.error(`\n  Fix: confirm the package name is real, then add it to package.json (npm/pnpm/yarn add),`);
+    console.error(`       or correct the import. AI commonly invents or typosquats package names.`);
+  }
+
+  exit(findings.length === 0 ? 0 : 1);
+}
+
+main();

package/bin/install.js

@@ -1283,6 +1283,8 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     "fawzi-approval-guard.js", "task-write-guard.js",
     // v5.0 — insights-driven destructive-op + wrong-account guards
     "vercel-account-guard.js", "env-empty-guard.js", "supabase-destructive-guard.js",
+    // commit-time secret gate (constitution: never commit service_role / .env)
+    "secret-guard.js",
     // performance-audit telemetry capture (UserPromptSubmit)
     "usage-capture.js",
   ]);
@@ -1316,6 +1318,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
           { 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..." },
           { type: "command", if: "Bash(supabase*)|Bash(npx supabase*)", command: nodeCmd("supabase-destructive-guard.js"), timeout: 5, statusMessage: "⬢ Checking Supabase safety..." },
+          { type: "command", if: "Bash(git commit*)", command: nodeCmd("secret-guard.js"), timeout: 10, statusMessage: "⬢ Scanning staged content for secrets..." },
         ],
       },
       {
@@ -1569,6 +1572,12 @@ function printSummary({ member, target, claudeInstalled }) {
   console.log(
     `  ${DIM}              performance audit. Opt out:${RESET} ${TEAL}erp.capturePrompts=false${RESET} ${DIM}in ~/.claude/.qualia-config.json${RESET}`
   );
+  // New employees get the milestone mental model up front — OWNERs already
+  // know how the flow works, so we skip the card for them to avoid noise.
+  if (member.role !== "OWNER") {
+    try { ui.onboard(member.name); } catch {}
+  }
+
   console.log("");
   console.log(`  ${DIM2}${RULE}${RESET}`);
   console.log(`  ${TEAL}${BOLD}Welcome to the future with Qualia.${RESET}`);
@@ -1861,6 +1870,7 @@ async function installCodex(member, target, employeeMode = false) {
               { 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 },
+              { type: "command", command: nodeCmd("secret-guard.js"), timeout: 10, statusMessage: "⬢ Scanning staged content for secrets..." },
             ],
           },
           {
@@ -1868,6 +1878,11 @@ async function installCodex(member, target, employeeMode = false) {
             hooks: [
               { type: "command", command: nodeCmd("fawzi-approval-guard.js"), timeout: 5 },
               { type: "command", command: nodeCmd("migration-guard.js"), timeout: 10 },
+              // Runtime parity with Claude (install.js Edit|Write group): the
+              // off-contract-write gate must run on Codex too, else a Codex
+              // builder can write fabricated/out-of-scope files unblocked.
+              // Enforced by tests/runtime-parity.test.sh.
+              { type: "command", command: nodeCmd("task-write-guard.js"), timeout: 5, statusMessage: "⬢ Checking plan-contract file scope..." },
             ],
           },
         ],