qualia-framework 4.1.1 → 4.3.0

package/agents/builder.md

@@ -42,6 +42,34 @@ Parse every field in your task block:
 For every file you're about to modify — read it first. No exceptions.
 For every `@file` reference in Context — read it now.
 
+### 2b. Load Relevant Knowledge
+
+Before writing code, check the memory layer for prior decisions and known
+fixes that apply to this task. Hardcoded `cat ~/.claude/knowledge/X.md` is
+forbidden — always go through the loader so newly-added knowledge files
+become reachable automatically:
+
+```bash
+# Always — read the index to discover what's available
+node ~/.claude/bin/knowledge.js
+
+# If your task touches Supabase/auth/RLS:
+node ~/.claude/bin/knowledge.js load supabase-patterns
+node ~/.claude/bin/knowledge.js load patterns
+
+# If you're fixing a bug or hitting a familiar error, check known fixes:
+node ~/.claude/bin/knowledge.js load fixes
+node ~/.claude/bin/knowledge.js search "{error keyword}"
+
+# For client-specific work (project name appears in PROJECT.md):
+node ~/.claude/bin/knowledge.js load client
+```
+
+If a relevant entry exists, follow it (or note in your DONE message that
+you deviated and why). If nothing matches, proceed normally — the loader
+prints `(no entries in X — use /qualia-learn to add one)` for missing files,
+which is fine and means there is nothing to apply yet.
+
 ### 3. Build It
 - Follow the Action exactly as specified
 - Keep every Acceptance Criterion in mind — you are building toward observable user behaviors, not just files

package/agents/research-synthesizer.md

@@ -2,8 +2,15 @@
 name: qualia-research-synthesizer
 description: Merges 4 parallel research outputs (STACK, FEATURES, ARCHITECTURE, PITFALLS) into SUMMARY.md with roadmap implications. Spawned by qualia-new after researchers complete.
 tools: Read, Write
+model: haiku
 ---
 
+<!-- model: haiku — pure synthesis of already-gathered markdown. No new
+     reasoning beyond merging well-structured research files. Cole Medin's
+     "model-per-node" pattern: switch to haiku only where the work is
+     mechanical, not where it's high-stakes. -->
+
+
 # Research Synthesizer
 
 You merge 4 dimensional research files into one executive SUMMARY.md that informs roadmap creation. You don't do new research — you synthesize what's already gathered.

package/bin/cli.js

@@ -139,6 +139,8 @@ const QUALIA_HOOK_FILES = [
   "migration-guard.js",
   "pre-deploy-gate.js",
   "pre-compact.js",
+  "git-guardrails.js",
+  "stop-session-log.js",
 ];
 const QUALIA_LEGACY_HOOK_FILES = [
   "block-env-edit.js", // removed in v3.2.0
@@ -157,7 +159,7 @@ const QUALIA_AGENT_FILES = [
 ];
 
 // 3 Qualia bin scripts.
-const QUALIA_BIN_FILES = ["state.js", "qualia-ui.js", "statusline.js"];
+const QUALIA_BIN_FILES = ["state.js", "qualia-ui.js", "statusline.js", "knowledge.js", "knowledge-flush.js"];
 
 // 5 Qualia rules.
 const QUALIA_RULE_FILES = ["security.md", "frontend.md", "design-reference.md", "deployment.md", "infrastructure.md"];
@@ -872,6 +874,133 @@ function cmdErpPing() {
   process.exit(1);
 }
 
+// ─── Doctor: post-install health check ───────────────────
+// Mirrors the spot-check that session-start.js runs once per 24h. Surfaces
+// missing files, mis-wired hooks, stale settings.json, and version drift.
+// Use whenever something feels off, before opening an issue, or after a
+// version upgrade. Exits 0 if healthy, 1 if any issue is found.
+// ─── Flush: convenience wrapper around knowledge-flush.js ───────
+// Exposes the cron-runnable script as a top-level CLI command so users can
+// run `qualia-framework flush` ad-hoc. All args after the command pass through.
+function cmdFlush() {
+  const flushScript = path.join(CLAUDE_DIR, "bin", "knowledge-flush.js");
+  if (!fs.existsSync(flushScript)) {
+    console.log(`  ${RED}✗${RESET} knowledge-flush.js not installed at ${flushScript}`);
+    console.log(`  ${DIM}Run: npx qualia-framework@latest install${RESET}`);
+    process.exit(1);
+  }
+  const args = process.argv.slice(3);
+  const r = spawnSync(process.execPath, [flushScript, ...args], {
+    stdio: "inherit",
+    shell: false,
+  });
+  process.exit(typeof r.status === "number" ? r.status : 1);
+}
+
+function cmdDoctor() {
+  banner();
+  console.log("");
+
+  const issues = [];
+  const checks = [];
+
+  function check(label, ok, hint) {
+    checks.push({ label, ok, hint });
+    if (!ok) issues.push({ label, hint });
+  }
+
+  // ── Critical files (the same set session-start.js validates) ──
+  const criticalFiles = [
+    path.join(CLAUDE_DIR, "rules", "grounding.md"),
+    path.join(CLAUDE_DIR, "rules", "security.md"),
+    path.join(CLAUDE_DIR, "rules", "frontend.md"),
+    path.join(CLAUDE_DIR, "rules", "deployment.md"),
+    path.join(CLAUDE_DIR, "bin", "state.js"),
+    path.join(CLAUDE_DIR, "bin", "qualia-ui.js"),
+    path.join(CLAUDE_DIR, "bin", "statusline.js"),
+    path.join(CLAUDE_DIR, "bin", "knowledge.js"),
+    path.join(CLAUDE_DIR, "bin", "knowledge-flush.js"),
+    path.join(CLAUDE_DIR, "CLAUDE.md"),
+    CONFIG_FILE,
+  ];
+  for (const f of criticalFiles) {
+    check(
+      `${path.relative(CLAUDE_DIR, f) || f}`,
+      fs.existsSync(f),
+      "run: npx qualia-framework@latest install",
+    );
+  }
+
+  // ── Hooks ─────────────────────────────────────────────
+  for (const h of QUALIA_HOOK_FILES) {
+    check(
+      `hooks/${h}`,
+      fs.existsSync(path.join(CLAUDE_DIR, "hooks", h)),
+      "reinstall: npx qualia-framework@latest install",
+    );
+  }
+
+  // ── Knowledge layer ────────────────────────────────────
+  const knowledgeFiles = [
+    path.join(CLAUDE_DIR, "knowledge", "agents.md"),
+    path.join(CLAUDE_DIR, "knowledge", "index.md"),
+    path.join(CLAUDE_DIR, "knowledge", "daily-log"),
+  ];
+  for (const f of knowledgeFiles) {
+    check(
+      `knowledge/${path.basename(f)}${fs.existsSync(f) && fs.statSync(f).isDirectory() ? "/" : ""}`,
+      fs.existsSync(f),
+      "reinstall to initialize the memory layer: npx qualia-framework@latest install",
+    );
+  }
+
+  // ── settings.json hook wiring ──────────────────────────
+  const settingsPath = path.join(CLAUDE_DIR, "settings.json");
+  if (fs.existsSync(settingsPath)) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+      const wantEvents = ["SessionStart", "PreToolUse", "PreCompact", "Stop"];
+      for (const ev of wantEvents) {
+        const blocks = (settings.hooks || {})[ev] || [];
+        const hasQualia = blocks.some((b) =>
+          (b.hooks || []).some((h) => typeof h.command === "string" && h.command.includes(".claude")),
+        );
+        check(`settings.json hooks.${ev}`, hasQualia, "reinstall to wire hooks");
+      }
+    } catch (e) {
+      check("settings.json parseable", false, e.message);
+    }
+  } else {
+    check("settings.json", false, "Claude Code never ran here? Open Claude once first");
+  }
+
+  // ── Version vs. installed ──────────────────────────────
+  const cfg = readConfig();
+  if (cfg.installed_at) {
+    check(`config installed_by=${cfg.installed_by || "?"} role=${cfg.role || "?"}`, true);
+  } else {
+    check("config has install metadata", false, "reinstall to record");
+  }
+
+  // ── Render ────────────────────────────────────────────
+  for (const c of checks) {
+    const mark = c.ok ? `${GREEN}✓${RESET}` : `${RED}✗${RESET}`;
+    console.log(`  ${mark} ${c.label}`);
+  }
+  console.log("");
+  if (issues.length === 0) {
+    console.log(`  ${GREEN}All checks passed. Framework is healthy.${RESET}`);
+    console.log("");
+    process.exit(0);
+  }
+  console.log(`  ${RED}${issues.length} issue${issues.length === 1 ? "" : "s"} found:${RESET}`);
+  for (const i of issues) {
+    console.log(`  ${DIM}•${RESET} ${i.label}${i.hint ? ` ${DIM}— ${i.hint}${RESET}` : ""}`);
+  }
+  console.log("");
+  process.exit(1);
+}
+
 function cmdHelp() {
   banner();
   console.log("");
@@ -884,7 +1013,9 @@ function cmdHelp() {
   console.log(`    qualia-framework ${TEAL}team${RESET}         Manage team members (${DIM}list|add|remove${RESET})`);
   console.log(`    qualia-framework ${TEAL}traces${RESET}       View recent hook telemetry`);
   console.log(`    qualia-framework ${TEAL}analytics${RESET}    Show outcome scoring & gap cycle stats`);
-  console.log(`    qualia-framework ${TEAL}erp-ping${RESET}     Verify ERP connectivity + API key`);
+  console.log(`    qualia-framework ${TEAL}erp-ping${RESET}     Verify ERP connectivity + API key
+    qualia-framework ${TEAL}doctor${RESET}       Health-check the install (files, hooks, settings)
+    qualia-framework ${TEAL}flush${RESET}        Promote daily-log → curated knowledge (memory layer)`);
   console.log("");
   console.log(`  ${WHITE}After install:${RESET}`);
   console.log(`    ${TG}/qualia${RESET}          What should I do next?`);
@@ -941,6 +1072,15 @@ switch (cmd) {
   case "ping":
     cmdErpPing();
     break;
+  case "doctor":
+  case "health":
+  case "health-check":
+    cmdDoctor();
+    break;
+  case "flush":
+  case "knowledge-flush":
+    cmdFlush();
+    break;
   default:
     cmdHelp();
 }

package/bin/install.js

@@ -294,8 +294,12 @@ async function main() {
   const tmplDir = path.join(FRAMEWORK_DIR, "templates");
   const tmplDest = path.join(CLAUDE_DIR, "qualia-templates");
   if (!fs.existsSync(tmplDest)) fs.mkdirSync(tmplDest, { recursive: true });
+  // `knowledge/` is a sibling templates directory but installs to a different
+  // destination (~/.claude/knowledge/, not ~/.claude/qualia-templates/), so we
+  // skip it here and handle it in the dedicated "Knowledge layer" section below.
   for (const entry of fs.readdirSync(tmplDir, { withFileTypes: true })) {
     if (entry.name.startsWith(".")) continue;
+    if (entry.name === "knowledge") continue;
     const srcPath = path.join(tmplDir, entry.name);
     const destPath = path.join(tmplDest, entry.name);
     try {
@@ -311,6 +315,38 @@ async function main() {
     }
   }
 
+  // ─── Knowledge layer (Karpathy-style raw → wiki memory tier) ──────
+  // Initializes ~/.claude/knowledge/ on first install. Never overwrites
+  // existing files — re-running the installer is safe for users who have
+  // already accumulated learnings.
+  printSection("Knowledge layer");
+  const knowledgeSrc = path.join(FRAMEWORK_DIR, "templates", "knowledge");
+  const knowledgeDest = path.join(CLAUDE_DIR, "knowledge");
+  if (!fs.existsSync(knowledgeDest)) fs.mkdirSync(knowledgeDest, { recursive: true });
+  const dailyLogDir = path.join(knowledgeDest, "daily-log");
+  if (!fs.existsSync(dailyLogDir)) {
+    fs.mkdirSync(dailyLogDir, { recursive: true });
+    ok("daily-log/ (created)");
+  } else {
+    log(`${DIM}daily-log/ (kept)${RESET}`);
+  }
+  if (fs.existsSync(knowledgeSrc)) {
+    for (const file of fs.readdirSync(knowledgeSrc)) {
+      const src = path.join(knowledgeSrc, file);
+      const dest = path.join(knowledgeDest, file);
+      try {
+        if (fs.existsSync(dest)) {
+          log(`${DIM}${file} (kept — user has customized)${RESET}`);
+        } else {
+          copy(src, dest);
+          ok(`${file} (initialized)`);
+        }
+      } catch (e) {
+        warn(`${file} — ${e.message}`);
+      }
+    }
+  }
+
   // ─── References (methodology docs loaded by skills at runtime) ────
   printSection("References");
   const refDir = path.join(FRAMEWORK_DIR, "references");
@@ -374,6 +410,18 @@ async function main() {
       path.join(binDest, "statusline.js")
     );
     ok("statusline.js (status bar renderer)");
+    copy(
+      path.join(FRAMEWORK_DIR, "bin", "knowledge.js"),
+      path.join(binDest, "knowledge.js")
+    );
+    fs.chmodSync(path.join(binDest, "knowledge.js"), 0o755);
+    ok("knowledge.js (memory-layer loader)");
+    copy(
+      path.join(FRAMEWORK_DIR, "bin", "knowledge-flush.js"),
+      path.join(binDest, "knowledge-flush.js")
+    );
+    fs.chmodSync(path.join(binDest, "knowledge-flush.js"), 0o755);
+    ok("knowledge-flush.js (cron-runnable flush)");
   } catch (e) {
     warn(`scripts — ${e.message}`);
   }
@@ -562,6 +610,15 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     CLAUDE_CODE_DISABLE_AUTO_MEMORY: "0",
     MAX_MCP_OUTPUT_TOKENS: "25000",
     CLAUDE_CODE_NO_FLICKER: "1",
+    // v4.2.0 phase 3 — enable forked subagents (Anthropic, 2026-04).
+    // Forks inherit the full conversation history + share the prompt cache,
+    // so design fan-outs and discuss-context handoffs preserve nuance instead
+    // of compressing 50k tokens of taste discussion into a 2k subagent prompt.
+    // /qualia-design and the builder agent reach for /fork when discuss
+    // 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",
   });
 
   // Status line
@@ -613,6 +670,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
   const QUALIA_HOOK_SET = new Set([
     "session-start.js", "auto-update.js", "branch-guard.js", "pre-push.js",
     "pre-deploy-gate.js", "migration-guard.js", "pre-compact.js",
+    "git-guardrails.js", "stop-session-log.js",
   ]);
   const isQualiaHookCmd = (cmd) => {
     if (typeof cmd !== "string") return false;
@@ -635,6 +693,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
         matcher: "Bash",
         hooks: [
           { type: "command", command: nodeCmd("auto-update.js"), timeout: 5 },
+          { type: "command", command: nodeCmd("git-guardrails.js"), timeout: 5, statusMessage: "⬢ Checking git safety..." },
           { 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..." },
@@ -655,6 +714,14 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
         ],
       },
     ],
+    Stop: [
+      {
+        matcher: ".*",
+        hooks: [
+          { type: "command", command: nodeCmd("stop-session-log.js"), timeout: 5 },
+        ],
+      },
+    ],
   };
 
   // Merge user hooks: strip Qualia-owned commands, preserve everything else.
@@ -692,7 +759,7 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
 
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 
-  ok("Hooks: session-start, auto-update, branch-guard, pre-push, migration-guard, deploy-gate, pre-compact");
+  ok("Hooks: session-start, auto-update, branch-guard, pre-push, migration-guard, deploy-gate, pre-compact, git-guardrails, stop-session-log");
   ok("Status line + spinner configured");
   ok("Environment variables + permissions");
 

package/bin/knowledge-flush.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+// ~/.claude/bin/knowledge-flush.js — non-interactive memory-layer flush.
+//
+// Wraps `/qualia-flush` so it can run from cron (or systemd timer, or any
+// CI/scheduled job) without an interactive Claude Code session. Closes the
+// memory loop end-to-end:
+//
+//   Stop hook (auto, every turn) → ~/.claude/knowledge/daily-log/{date}.md
+//   THIS SCRIPT (weekly cron)    → spawns `claude -p "/qualia-flush --days 7"`
+//   /qualia-flush                 → promotes raw → curated tier
+//   bin/knowledge.js (every spawn) → reads index.md → reaches the right file
+//
+// Usage:
+//   node ~/.claude/bin/knowledge-flush.js               # 7-day flush
+//   node ~/.claude/bin/knowledge-flush.js --days 14     # custom window
+//   node ~/.claude/bin/knowledge-flush.js --dry-run     # preview only
+//   node ~/.claude/bin/knowledge-flush.js --project X   # scope to one project
+//
+// Recommended cron entry (weekly Sunday 3 AM local):
+//   0 3 * * 0 node ~/.claude/bin/knowledge-flush.js >> ~/.claude/.qualia-flush.log 2>&1
+//
+// Behavior:
+//   • If `claude` CLI isn't on PATH, exits 0 with a logged warning. Cron
+//     spam is worse than a missed flush — a real failure surfaces in the
+//     log file the user is presumably watching.
+//   • If the daily-log dir is empty (nothing to flush), exits 0 silently.
+//   • If `claude -p` returns non-zero, exits 1 with the error captured in
+//     the log so cron can be configured to alert on it.
+//   • Writes one structured JSONL line per run to ~/.claude/.qualia-flush.log
+//     so the user can audit "when did the last 5 flushes run, what did they
+//     produce?" without parsing free text.
+//
+// Cross-platform (Windows/macOS/Linux). Honors the same args as the skill.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawnSync } = require("child_process");
+
+const HOME = os.homedir();
+const KNOWLEDGE_DIR = path.join(HOME, ".claude", "knowledge");
+const DAILY_DIR = path.join(KNOWLEDGE_DIR, "daily-log");
+const LOG_FILE = path.join(HOME, ".claude", ".qualia-flush.log");
+
+const _start = Date.now();
+
+function logEvent(event) {
+  try {
+    const dir = path.dirname(LOG_FILE);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const line = JSON.stringify({
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - _start,
+      ...event,
+    });
+    fs.appendFileSync(LOG_FILE, line + "\n");
+  } catch {}
+}
+
+function which(cmd) {
+  // Cross-platform `which`. Returns the first PATH match or null.
+  // We don't shell out to `which` itself because it doesn't exist on Windows
+  // (it's `where` there, with different semantics).
+  const sep = process.platform === "win32" ? ";" : ":";
+  const exts = process.platform === "win32"
+    ? (process.env.PATHEXT || ".EXE;.CMD;.BAT").split(";")
+    : [""];
+  const dirs = (process.env.PATH || "").split(sep);
+  for (const dir of dirs) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const candidate = path.join(dir, cmd + ext);
+      try {
+        if (fs.existsSync(candidate)) return candidate;
+      } catch {}
+    }
+  }
+  return null;
+}
+
+// Pass-through args (so `--days 14`, `--dry-run`, `--project X` all reach the
+// skill). We don't parse them ourselves — the skill is the source of truth
+// for argument semantics. We only use `--days` locally to short-circuit when
+// the daily-log is genuinely empty.
+const argv = process.argv.slice(2);
+const flagIdx = argv.indexOf("--days");
+const days = flagIdx >= 0 ? parseInt(argv[flagIdx + 1], 10) || 7 : 7;
+
+function dailyLogHasRecentEntries(windowDays) {
+  if (!fs.existsSync(DAILY_DIR)) return false;
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - windowDays);
+  const cutoffStr = cutoff.toISOString().split("T")[0];
+  try {
+    const entries = fs.readdirSync(DAILY_DIR);
+    for (const f of entries) {
+      if (!f.endsWith(".md")) continue;
+      const base = f.replace(/\.md$/, "");
+      if (base >= cutoffStr) return true;
+    }
+  } catch {}
+  return false;
+}
+
+// ── Preflight ────────────────────────────────────────────
+const claudeBin = which("claude");
+if (!claudeBin) {
+  logEvent({ event: "skipped", reason: "claude-cli-not-on-path" });
+  // Exit 0 — a missing CLI on the host running cron is a config issue, not
+  // a flush failure. Don't spam alerts.
+  process.exit(0);
+}
+
+if (!dailyLogHasRecentEntries(days)) {
+  logEvent({ event: "skipped", reason: "no-recent-daily-log", window_days: days });
+  process.exit(0);
+}
+
+// ── Run ──────────────────────────────────────────────────
+// `claude -p "<prompt>"` runs a single non-interactive turn. The skill body
+// invocation matches what the user would type at the prompt.
+const prompt = `/qualia-flush ${argv.join(" ")}`.trim();
+
+const result = spawnSync(claudeBin, ["-p", prompt], {
+  encoding: "utf8",
+  timeout: 5 * 60 * 1000, // 5 min hard cap — flush should never take this long
+  shell: process.platform === "win32",
+  stdio: ["ignore", "pipe", "pipe"],
+});
+
+const stdout = (result.stdout || "").trim();
+const stderr = (result.stderr || "").trim();
+const status = typeof result.status === "number" ? result.status : -1;
+
+if (status !== 0) {
+  logEvent({
+    event: "failed",
+    status,
+    prompt,
+    stderr_tail: stderr.slice(-1000),
+  });
+  // Surface to stderr so cron's MAILTO sends an alert.
+  console.error(`knowledge-flush: claude -p exited ${status}`);
+  if (stderr) console.error(stderr.slice(-2000));
+  process.exit(1);
+}
+
+// Success: parse stdout for the skill's summary line if present, else log
+// the full output tail.
+const summaryMatch = stdout.match(/⬢ Flushed daily-log .+/);
+logEvent({
+  event: "ok",
+  prompt,
+  summary: summaryMatch ? summaryMatch[0] : stdout.split("\n").slice(-3).join(" | "),
+});
+
+// Echo the user-facing summary to stdout so cron logs / interactive runs
+// both surface what happened.
+if (summaryMatch) {
+  console.log(summaryMatch[0]);
+} else {
+  console.log(stdout.split("\n").slice(-5).join("\n"));
+}
+process.exit(0);