qualia-framework 4.1.1 → 4.4.0

package/bin/cli.js

@@ -29,7 +29,8 @@ function readConfig() {
 
 function writeConfig(cfg) {
   if (!fs.existsSync(CLAUDE_DIR)) fs.mkdirSync(CLAUDE_DIR, { recursive: true });
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2) + "\n");
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
+  try { fs.chmodSync(CONFIG_FILE, 0o600); } catch {}
 }
 
 function banner() {
@@ -139,6 +140,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,10 +160,10 @@ 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", "plan-contract.js", "agent-runs.js"];
 
-// 5 Qualia rules.
-const QUALIA_RULE_FILES = ["security.md", "frontend.md", "design-reference.md", "deployment.md", "infrastructure.md"];
+// 6 Qualia rules.
+const QUALIA_RULE_FILES = ["security.md", "frontend.md", "design-reference.md", "deployment.md", "infrastructure.md", "grounding.md"];
 
 function promptYesNo(question, defaultYes) {
   return new Promise((resolve) => {
@@ -551,7 +554,7 @@ function cmdMigrate() {
   console.log(`  ${DIM}Target version:${RESET}  ${WHITE}${PKG.version}${RESET}`);
   console.log("");
 
-  // 1. Ensure all 8 hooks are wired (v2 missed block-env-edit and branch-guard)
+  // 1. Ensure the full v4.3 hook set is wired.
   const hd = path.join(CLAUDE_DIR, "hooks");
   const nodeCmd = (hookFile) => `node "${path.join(hd, hookFile)}"`;
 
@@ -562,10 +565,19 @@ function cmdMigrate() {
     settings.hooks.SessionStart = [{ matcher: ".*", hooks: [{ type: "command", command: nodeCmd("session-start.js"), timeout: 5 }] }];
     changes++;
     console.log(`  ${GREEN}+${RESET} Added SessionStart hook`);
+  } else {
+    const hasSessionStart = settings.hooks.SessionStart.some(e =>
+      Array.isArray(e.hooks) && e.hooks.some(h => typeof h.command === "string" && h.command.includes("session-start.js"))
+    );
+    if (!hasSessionStart) {
+      settings.hooks.SessionStart.push({ matcher: ".*", hooks: [{ type: "command", command: nodeCmd("session-start.js"), timeout: 5 }] });
+      changes++;
+      console.log(`  ${GREEN}+${RESET} Wired session-start.js into SessionStart`);
+    }
   }
 
   // Check PreToolUse hooks — ensure all critical hooks are present
-  const requiredBashHooks = ["auto-update.js", "branch-guard.js", "pre-push.js", "pre-deploy-gate.js"];
+  const requiredBashHooks = ["auto-update.js", "git-guardrails.js", "branch-guard.js", "pre-push.js", "pre-deploy-gate.js"];
   const requiredEditHooks = ["migration-guard.js"];
 
   if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
@@ -593,9 +605,10 @@ function cmdMigrate() {
     const exists = bashEntry.hooks.some(h => extractScriptName(h.command) === targetName);
     if (!exists) {
       const hookDef = { type: "command", command: cmd, timeout: hookFile === "pre-deploy-gate.js" ? 180 : 5 };
-      if (hookFile === "branch-guard.js") hookDef.if = "Bash(git push*)";
+      if (hookFile === "git-guardrails.js") hookDef.statusMessage = "⬢ Checking git safety...";
+      if (hookFile === "branch-guard.js") { hookDef.if = "Bash(git push*)"; hookDef.statusMessage = "⬢ Checking branch permissions..."; }
       if (hookFile === "pre-push.js") { hookDef.if = "Bash(git push*)"; hookDef.timeout = 15; }
-      if (hookFile === "pre-deploy-gate.js") hookDef.if = "Bash(vercel --prod*)";
+      if (hookFile === "pre-deploy-gate.js") { hookDef.if = "Bash(vercel --prod*)"; hookDef.timeout = 180; hookDef.statusMessage = "⬢ Running quality gates..."; }
       bashEntry.hooks.push(hookDef);
       changes++;
       console.log(`  ${GREEN}+${RESET} Wired ${hookFile} into PreToolUse/Bash`);
@@ -616,7 +629,7 @@ function cmdMigrate() {
     const exists = editEntry.hooks.some(h => extractScriptName(h.command) === targetName);
     if (!exists) {
       const hookDef = { type: "command", command: cmd, timeout: hookFile === "migration-guard.js" ? 10 : 5 };
-      if (hookFile === "migration-guard.js") hookDef.if = "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)";
+      if (hookFile === "migration-guard.js") { hookDef.if = "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)"; hookDef.statusMessage = "⬢ Checking migration safety..."; }
       editEntry.hooks.push(hookDef);
       changes++;
       console.log(`  ${GREEN}+${RESET} Wired ${hookFile} into PreToolUse/Edit|Write`);
@@ -624,10 +637,42 @@ function cmdMigrate() {
   }
 
   // Check PreCompact hook
-  if (!settings.hooks.PreCompact) {
+  if (!settings.hooks.PreCompact || !Array.isArray(settings.hooks.PreCompact)) {
     settings.hooks.PreCompact = [{ matcher: "compact", hooks: [{ type: "command", command: nodeCmd("pre-compact.js"), timeout: 15 }] }];
     changes++;
     console.log(`  ${GREEN}+${RESET} Added PreCompact hook`);
+  } else {
+    let compactEntry = settings.hooks.PreCompact.find(e => e.matcher === "compact");
+    if (!compactEntry) {
+      compactEntry = { matcher: "compact", hooks: [] };
+      settings.hooks.PreCompact.push(compactEntry);
+    }
+    if (!compactEntry.hooks) compactEntry.hooks = [];
+    const exists = compactEntry.hooks.some(h => extractScriptName(h.command) === "pre-compact.js");
+    if (!exists) {
+      compactEntry.hooks.push({ type: "command", command: nodeCmd("pre-compact.js"), timeout: 15, statusMessage: "⬢ Saving state..." });
+      changes++;
+      console.log(`  ${GREEN}+${RESET} Wired pre-compact.js into PreCompact`);
+    }
+  }
+
+  if (!settings.hooks.Stop || !Array.isArray(settings.hooks.Stop)) {
+    settings.hooks.Stop = [{ matcher: ".*", hooks: [{ type: "command", command: nodeCmd("stop-session-log.js"), timeout: 5 }] }];
+    changes++;
+    console.log(`  ${GREEN}+${RESET} Added Stop hook`);
+  } else {
+    let stopEntry = settings.hooks.Stop.find(e => e.matcher === ".*");
+    if (!stopEntry) {
+      stopEntry = { matcher: ".*", hooks: [] };
+      settings.hooks.Stop.push(stopEntry);
+    }
+    if (!stopEntry.hooks) stopEntry.hooks = [];
+    const exists = stopEntry.hooks.some(h => extractScriptName(h.command) === "stop-session-log.js");
+    if (!exists) {
+      stopEntry.hooks.push({ type: "command", command: nodeCmd("stop-session-log.js"), timeout: 5 });
+      changes++;
+      console.log(`  ${GREEN}+${RESET} Wired stop-session-log.js into Stop`);
+    }
   }
 
   // 2. Ensure env vars are up to date
@@ -728,12 +773,12 @@ function cmdAnalytics() {
   }
 
   // Verification outcomes (from traces that include verification data)
-  const verifications = traces.filter(t => t.hook === "state-transition" && t.extra && t.extra.verification);
-  const passes = verifications.filter(t => t.extra.verification === "pass").length;
-  const fails = verifications.filter(t => t.extra.verification === "fail").length;
+  const verifications = traces.filter(t => t.hook === "state-transition" && t.verification);
+  const passes = verifications.filter(t => t.verification === "pass").length;
+  const fails = verifications.filter(t => t.verification === "fail").length;
 
   // Gap cycle data
-  const gapTraces = traces.filter(t => t.hook === "state-transition" && t.extra && t.extra.gap_closure);
+  const gapTraces = traces.filter(t => t.hook === "state-transition" && t.gap_closure);
   const totalGapCycles = gapTraces.length;
 
   // Display
@@ -779,8 +824,9 @@ function cmdErpPing() {
   console.log("");
 
   const cfg = readConfig();
+  const args = new Set(process.argv.slice(3));
   const erpUrl = (cfg.erp && cfg.erp.url) || "https://portal.qualiasolutions.net";
-  const erpEnabled = !(cfg.erp && cfg.erp.enabled === false);
+  let erpEnabled = !(cfg.erp && cfg.erp.enabled === false);
   const keyFile = path.join(CLAUDE_DIR, ".erp-api-key");
 
   console.log(`  ${DIM}URL:${RESET}       ${WHITE}${erpUrl}${RESET}`);
@@ -800,6 +846,19 @@ function cmdErpPing() {
   console.log(`  ${DIM}Key:${RESET}       ${GREEN}present${RESET} ${DIM}(${apiKey.length} bytes)${RESET}`);
   console.log("");
 
+  if (!erpEnabled && args.has("--enable")) {
+    cfg.erp = {
+      ...(cfg.erp || {}),
+      enabled: true,
+      url: erpUrl,
+      api_key_file: ".erp-api-key",
+    };
+    writeConfig(cfg);
+    erpEnabled = true;
+    console.log(`  ${GREEN}✓ ERP enabled in config.${RESET}`);
+    console.log("");
+  }
+
   if (!erpEnabled) {
     console.log(`  ${YELLOW}ERP is disabled in config. Enable with:${RESET}`);
     console.log(`  ${DIM}  qualia-framework erp-ping --enable${RESET}`);
@@ -872,6 +931,266 @@ function cmdErpPing() {
   process.exit(1);
 }
 
+function cmdSetErpKey() {
+  banner();
+  console.log("");
+
+  const keyFile = path.join(CLAUDE_DIR, ".erp-api-key");
+  const rawArgs = process.argv.slice(3);
+  const clear = rawArgs.includes("--clear");
+
+  if (!fs.existsSync(CLAUDE_DIR)) fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+
+  if (clear) {
+    try { fs.unlinkSync(keyFile); } catch {}
+    const cfg = readConfig();
+    cfg.erp = { ...(cfg.erp || {}), enabled: false, url: (cfg.erp && cfg.erp.url) || "https://portal.qualiasolutions.net", api_key_file: ".erp-api-key" };
+    writeConfig(cfg);
+    console.log(`  ${GREEN}✓${RESET} ERP key removed and ERP disabled.`);
+    console.log("");
+    return;
+  }
+
+  let key = rawArgs.find((a) => a && !a.startsWith("--")) || "";
+  if (!key && !process.stdin.isTTY) {
+    try { key = fs.readFileSync(0, "utf8").trim(); } catch {}
+  }
+
+  key = String(key || "").trim();
+  if (!key) {
+    console.log(`  ${RED}✗${RESET} Missing ERP API key.`);
+    console.log(`  ${DIM}Usage:${RESET} qualia-framework set-erp-key <key>`);
+    console.log(`  ${DIM}Safe shell history option:${RESET} printf '%s' "$QUALIA_ERP_KEY" | qualia-framework set-erp-key`);
+    console.log("");
+    process.exit(1);
+  }
+
+  if (key.length < 10) {
+    console.log(`  ${YELLOW}!${RESET} Key looks short (${key.length} bytes). Saving anyway.`);
+  }
+
+  fs.writeFileSync(keyFile, key, { mode: 0o600 });
+  try { fs.chmodSync(keyFile, 0o600); } catch {}
+
+  const cfg = readConfig();
+  cfg.erp = {
+    ...(cfg.erp || {}),
+    enabled: true,
+    url: (cfg.erp && cfg.erp.url) || "https://portal.qualiasolutions.net",
+    api_key_file: ".erp-api-key",
+  };
+  writeConfig(cfg);
+
+  console.log(`  ${GREEN}✓${RESET} ERP key saved to ${WHITE}${keyFile}${RESET}`);
+  console.log(`  ${DIM}Verify with:${RESET} ${TEAL}qualia-framework erp-ping${RESET}`);
+  console.log("");
+}
+
+// ─── 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);
+}
+
+// ─── Agents: per-spawn telemetry (see docs/agent-runs.md) ─────────
+function cmdAgents() {
+  banner();
+  console.log("");
+
+  // Lazy require so the CLI works even if the lib is missing during dev.
+  let lib;
+  try { lib = require("./agent-runs.js"); }
+  catch (e) {
+    console.log(`  ${RED}✗${RESET} agent-runs.js not available: ${e.message}`);
+    console.log("");
+    process.exit(1);
+  }
+
+  const args = process.argv.slice(3);
+  const flags = new Set(args.filter((a) => a.startsWith("--")));
+  const sub = args.find((a) => !a.startsWith("--"));
+
+  const cwd = process.cwd();
+
+  if (sub === "prune") {
+    const idx = args.indexOf("--before");
+    const before = idx >= 0 ? args[idx + 1] : null;
+    if (!before) {
+      console.log(`  ${RED}✗${RESET} usage: qualia-framework agents prune --before YYYY-MM-DD`);
+      console.log("");
+      process.exit(1);
+    }
+    try {
+      const r = lib.prune(cwd, before);
+      console.log(`  ${GREEN}✓${RESET} Pruned ${r.removed} run record(s), ${r.logs_removed} log file(s).`);
+      console.log("");
+      return;
+    } catch (e) {
+      console.log(`  ${RED}✗${RESET} ${e.message}`);
+      console.log("");
+      process.exit(1);
+    }
+  }
+
+  const opts = { limit: 50 };
+  if (flags.has("--failed")) opts.failed = true;
+  const taskIdx = args.indexOf("--task");
+  if (taskIdx >= 0) opts.task_id = args[taskIdx + 1];
+  const phaseIdx = args.indexOf("--phase");
+  if (phaseIdx >= 0) opts.phase = Number(args[phaseIdx + 1]);
+
+  const records = lib.read(cwd, opts);
+  if (records.length === 0) {
+    console.log(`  ${DIM}No agent runs recorded yet${RESET} ${DIM}(or run from a project with .planning/)${RESET}`);
+    console.log("");
+    return;
+  }
+
+  console.log(`  ${WHITE}Agent runs${RESET} ${DIM}(showing ${records.length}, newest last)${RESET}`);
+  console.log(`  ${DIM}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
+  console.log(`  ${DIM}TIME   AGENT       PHASE TASK STATUS    DURATION  NOTE${RESET}`);
+  for (const r of records) {
+    const t = (r.finished_at || r.started_at || "").slice(11, 16);
+    const agent = (r.agent_type || "").padEnd(11);
+    const phase = String(r.phase ?? "-").padEnd(5);
+    const task = (r.task_id || "-").padEnd(4);
+    const stColor = r.status === "success" ? GREEN : r.status === "partial" ? YELLOW : RED;
+    const status = `${stColor}${(r.status || "?").padEnd(9)}${RESET}`;
+    const dur = r.duration_ms != null ? `${Math.round(r.duration_ms / 1000)}s`.padStart(7) : "      —";
+    const note = r.failure_reason
+      ? `${DIM}${r.failure_reason}${RESET}`
+      : (r.commit_sha ? `${DIM}${r.commit_sha.slice(0, 7)}${RESET}` : "");
+    console.log(`  ${t}  ${agent} ${phase} ${task} ${status} ${dur}  ${note}`);
+  }
+  console.log("");
+  const failed = records.filter((r) => r.status !== "success").length;
+  if (failed > 0) {
+    console.log(`  ${YELLOW}${failed} non-success run(s).${RESET} ${DIM}qualia-framework agents --failed for details${RESET}`);
+    console.log("");
+  }
+}
+
 function cmdHelp() {
   banner();
   console.log("");
@@ -880,11 +1199,15 @@ function cmdHelp() {
   console.log(`    qualia-framework ${TEAL}update${RESET}       Update to the latest version`);
   console.log(`    qualia-framework ${TEAL}version${RESET}      Show installed version + check for updates`);
   console.log(`    qualia-framework ${TEAL}uninstall${RESET}    Clean removal from ~/.claude/ (${DIM}-y to skip prompts${RESET})`);
-  console.log(`    qualia-framework ${TEAL}migrate${RESET}      Migrate settings from v2 to v3`);
+  console.log(`    qualia-framework ${TEAL}migrate${RESET}      Wire current hook + env layout into ~/.claude/settings.json`);
   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}agents${RESET}       Show per-agent run history (${DIM}--failed|--task ID|--phase N|prune --before${RESET})`);
+  console.log(`    qualia-framework ${TEAL}set-erp-key${RESET}  Save/enable the ERP API key`);
   console.log(`    qualia-framework ${TEAL}erp-ping${RESET}     Verify ERP connectivity + API key`);
+  console.log(`    qualia-framework ${TEAL}doctor${RESET}       Health-check the install (files, hooks, settings)`);
+  console.log(`    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?`);
@@ -933,14 +1256,30 @@ switch (cmd) {
   case "migrate":
     cmdMigrate();
     break;
+  case "agents":
+    cmdAgents();
+    break;
   case "analytics":
   case "stats":
     cmdAnalytics();
     break;
+  case "set-erp-key":
+  case "erp-key":
+    cmdSetErpKey();
+    break;
   case "erp-ping":
   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,28 @@ 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)");
+    copy(
+      path.join(FRAMEWORK_DIR, "bin", "plan-contract.js"),
+      path.join(binDest, "plan-contract.js")
+    );
+    ok("plan-contract.js (plan JSON validator)");
+    copy(
+      path.join(FRAMEWORK_DIR, "bin", "agent-runs.js"),
+      path.join(binDest, "agent-runs.js")
+    );
+    ok("agent-runs.js (agent telemetry writer)");
   } catch (e) {
     warn(`scripts — ${e.message}`);
   }
@@ -538,8 +596,8 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
       try { fs.chmodSync(configFile, 0o600); } catch {}
     } catch {}
     log(`${YELLOW}!${RESET} ERP key not configured — reports won't upload until set.`);
-    log(`${DIM}  Set with:${RESET} ${TEAL}export QUALIA_ERP_KEY=...${RESET} ${DIM}then re-install,${RESET}`);
-    log(`${DIM}  or write the key to:${RESET} ${WHITE}${erpKeyFile}${RESET} ${DIM}(mode 0600).${RESET}`);
+    log(`${DIM}  Set with:${RESET} ${TEAL}qualia-framework set-erp-key <key>${RESET}`);
+    log(`${DIM}  or:${RESET} ${TEAL}export QUALIA_ERP_KEY=...${RESET} ${DIM}then re-install.${RESET}`);
     log(`${DIM}  Get a key from Fawzi.${RESET}`);
   }
 
@@ -562,6 +620,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 +680,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 +703,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 +724,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.
@@ -672,8 +749,8 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     settings.hooks[event] = [...cleaned, ...qualiaHooks[event]];
   }
 
-  // Permissions — no restrictions on env files or branches.
-  // Everyone can read/write .env, push to main.
+  // Permissions stay permissive; Qualia policy enforcement happens in hooks so
+  // OWNER overrides and EMPLOYEE blocks can share one source of truth.
   if (!settings.permissions) settings.permissions = {};
   if (!settings.permissions.allow) settings.permissions.allow = [];
   if (!settings.permissions.deny) settings.permissions.deny = [];
@@ -692,7 +769,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");
 
@@ -709,7 +786,11 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
   const ruleCount = fs.readdirSync(rulesDir).length;
   const tmplCount = fs.readdirSync(tmplDir).length;
   console.log(`  ${DIM}Skills${RESET}    ${TEAL}${skills.length}${RESET}     ${DIM}Agents${RESET}  ${TEAL}${agentCount}${RESET}     ${DIM}Hooks${RESET}   ${TEAL}${hookCount}${RESET}`);
-  console.log(`  ${DIM}Rules${RESET}     ${TEAL}${ruleCount}${RESET}     ${DIM}Scripts${RESET} ${TEAL}3${RESET}     ${DIM}Templates${RESET} ${TEAL}${tmplCount}${RESET}`);
+  const installedBinDir = path.join(CLAUDE_DIR, "bin");
+  const scriptCount = fs.existsSync(installedBinDir)
+    ? fs.readdirSync(installedBinDir).filter(f => f.endsWith('.js')).length
+    : 0;
+  console.log(`  ${DIM}Rules${RESET}     ${TEAL}${ruleCount}${RESET}     ${DIM}Scripts${RESET} ${TEAL}${scriptCount}${RESET}     ${DIM}Templates${RESET} ${TEAL}${tmplCount}${RESET}`);
 
   if (errors > 0) {
     console.log("");