qualia-framework 4.3.0 → 4.4.0

package/README.md

@@ -115,13 +115,13 @@ Project
 
 **Why it matters:** non-technical team members can follow the ladder from any entry point. `/qualia` and `/qualia-milestone` render JOURNEY.md as a visual ladder with current position highlighted.
 
-## What's Inside (v4.0.0)
+## What's Inside (v4.3.0)
 
-- **26 skills** — from setup to handoff, plus debug, design, review, optimize, diagnostic (`qualia-idk`), session management, skill authoring, per-phase depth (discuss, research, map), and full-journey additions (`--auto` chaining, milestone closure)
+- **28 skills** — from setup to handoff, plus debug, design, review, optimize, diagnostic (`qualia-idk`), memory flush, postmortem, session management, skill authoring, per-phase depth (discuss, research, map), and full-journey additions (`--auto` chaining, milestone closure)
 - **8 agents** (each runs in fresh context): planner, builder, verifier, qa-browser, researcher, research-synthesizer, roadmapper, plan-checker
-- **7 hooks** (pure Node.js, cross-platform): session-start, branch-guard, pre-push tracking sync, migration-guard, pre-deploy-gate, pre-compact state save, auto-update
-- **5 rules**: security, frontend, design-reference, deployment, infrastructure
-- **19 template files**: project.md, **journey.md** (new in v4), plan.md (story-file format), state.md, DESIGN.md, tracking.json (now with `milestone_name` + `milestones[]`), requirements.md (multi-milestone), roadmap.md (current milestone only), phase-context.md, 4 project-type templates (website, ai-agent, voice-agent, mobile-app), 5 research-project templates (STACK, FEATURES, ARCHITECTURE, PITFALLS, SUMMARY), help.html
+- **9 hooks** (pure Node.js, cross-platform): session-start, auto-update, git-guardrails, branch-guard, pre-push tracking sync, migration-guard, pre-deploy-gate, pre-compact state save, stop-session-log
+- **6 rules**: security, frontend, design-reference, deployment, infrastructure, grounding
+- **21 template files**: project.md, **journey.md** (new in v4), plan.md (story-file format), state.md, DESIGN.md, tracking.json (now with `milestone_name` + `milestones[]`), requirements.md (multi-milestone), roadmap.md (current milestone only), phase-context.md, 4 project-type templates (website, ai-agent, voice-agent, mobile-app), 5 research-project templates (STACK, FEATURES, ARCHITECTURE, PITFALLS, SUMMARY), knowledge templates, help.html
 - **1 reference** — questioning.md methodology for deep project initialization
 
 ## Supported Platforms
@@ -156,13 +156,17 @@ Splitting planner, builder, and verifier into separate agents with separate cont
 
 ### Production-Grade Hooks
 
-All 7 hooks are real ops engineering, not theoretical:
+All 9 hooks are real ops engineering, not theoretical:
 
 - **Pre-deploy gate** — TypeScript, lint, tests, build, and `service_role` leak scan before `vercel --prod`
+- **Session start** — Shows project state, next command, update notices, and health warnings at session start
+- **Auto-update** — Daily update check with cached failures so offline/npm issues do not slow every command
+- **Git guardrails** — Blocks destructive git operations like force-push to main/master, `git clean -fd`, and `rm -rf .git`
 - **Branch guard** — Role-aware: owner can push to main, employees can't (parses refspec so `feature/x:main` bypass is blocked)
 - **Migration guard** — Catches `DROP TABLE` without `IF EXISTS`, `DELETE`/`UPDATE` without `WHERE`, `CREATE TABLE` without RLS, `GRANT ... TO PUBLIC`, `ALTER TABLE ... DROP COLUMN`
 - **Pre-push** — Stamps tracking.json via a bot commit so the ERP always sees fresh data
 - **Pre-compact** — Saves state before context compression
+- **Stop-session log** — Writes lightweight daily session checkpoints into the knowledge layer
 
 ### Enforced State Machine
 
@@ -183,12 +187,12 @@ npx qualia-framework@latest install
      |
      v
 ~/.claude/
-  ├── skills/             26 slash commands
+  ├── skills/             28 slash commands
   ├── agents/             8 agent definitions (planner, builder, verifier, qa-browser, roadmapper, research-synthesizer, researcher, plan-checker)
-  ├── hooks/              7 Node.js hooks — cross-platform (no bash dependency)
-  ├── bin/                state.js (state machine) + qualia-ui.js (cosmetics, banners, journey-tree) + statusline.js
+  ├── hooks/              9 Node.js hooks — cross-platform (no bash dependency)
+  ├── bin/                state.js + qualia-ui.js + statusline.js + knowledge.js + knowledge-flush.js
   ├── knowledge/          learned-patterns.md, common-fixes.md, client-prefs.md
-  ├── rules/              security, frontend, design-reference, deployment, infrastructure
+  ├── rules/              security, frontend, design-reference, deployment, infrastructure, grounding
   ├── qualia-templates/   project.md, journey.md, plan.md (story-file), state.md, DESIGN.md, tracking.json, requirements.md, roadmap.md, + projects/*.md + research-project/*.md + help.html
   ├── qualia-references/  questioning.md (deep project initialization methodology)
   ├── CLAUDE.md           global instructions (role-configured per team member)
@@ -201,6 +205,6 @@ Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell AI, El
 
 ## Changelog
 
-See [CHANGELOG.md](./CHANGELOG.md) for the full version history. v4.0.0 release notes are the most recent section.
+See [CHANGELOG.md](./CHANGELOG.md) for the full version history. v4.3.0 release notes are the most recent section.
 
 Built by [Qualia Solutions](https://qualiasolutions.net) — Nicosia, Cyprus.

package/bin/agent-runs.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+// Agent runs telemetry — JSONL writer + reader. See docs/agent-runs.md.
+//
+// Pure library. Atomic writes via fs.appendFileSync (single write() syscall
+// to an O_APPEND file descriptor; safe at our record sizes — see the spec).
+//
+// Zero npm dependencies.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const SCHEMA_VERSION = 1;
+
+const VALID_AGENT_TYPES = new Set([
+  "planner", "plan-checker", "builder", "verifier", "qa-browser",
+  "researcher", "research-synthesizer", "roadmapper", "team-orchestrator",
+  "custom",
+]);
+
+const VALID_STATUS = new Set([
+  "success", "partial", "blocked", "failure", "timeout", "interrupted",
+]);
+
+// One UUID per process — fallback when Claude Code doesn't expose a session id.
+let _processSessionId = null;
+function processSessionId() {
+  if (!_processSessionId) {
+    const buf = crypto.randomBytes(16);
+    // RFC 4122 v4
+    buf[6] = (buf[6] & 0x0f) | 0x40;
+    buf[8] = (buf[8] & 0x3f) | 0x80;
+    const h = buf.toString("hex");
+    _processSessionId = `${h.slice(0,8)}-${h.slice(8,12)}-${h.slice(12,16)}-${h.slice(16,20)}-${h.slice(20)}`;
+  }
+  return _processSessionId;
+}
+
+// ULID-ish: timestamp prefix + random suffix. Sortable by time.
+function newRunId() {
+  const ts = Date.now().toString(36).toUpperCase().padStart(10, "0");
+  const rand = crypto.randomBytes(10).toString("hex").toUpperCase();
+  return `${ts}${rand}`.slice(0, 26);
+}
+
+function planningDir(cwd) {
+  return path.join(cwd || process.cwd(), ".planning");
+}
+
+function jsonlPath(cwd) {
+  return path.join(planningDir(cwd), "agent-runs.jsonl");
+}
+
+function logDir(cwd) {
+  return path.join(planningDir(cwd), "agent-runs");
+}
+
+function telemetryEnabled() {
+  return (process.env.QUALIA_TELEMETRY || "").toLowerCase() !== "off";
+}
+
+function ensureDir(p) {
+  if (!fs.existsSync(p)) fs.mkdirSync(p, { recursive: true });
+}
+
+function truncTail(s, max) {
+  if (typeof s !== "string") return undefined;
+  if (s.length <= max) return s;
+  return s.slice(s.length - max);
+}
+
+// ─── Writer ────────────────────────────────────────────────────────────
+
+// start({ agent_type, model, ... }) → opaque token used by finish()
+function start(opts) {
+  const now = new Date().toISOString();
+  const token = {
+    started_at: now,
+    started_ms: Date.now(),
+    record: {
+      schema_version: SCHEMA_VERSION,
+      run_id: opts.run_id || newRunId(),
+      parent_run_id: opts.parent_run_id || undefined,
+      skill_invocation_id: opts.skill_invocation_id || processSessionId(),
+      session_id: opts.session_id || processSessionId(),
+      agent_type: opts.agent_type,
+      agent_name: opts.agent_name || undefined,
+      model: opts.model,
+      effort: opts.effort || undefined,
+      project: opts.project || undefined,
+      phase: opts.phase != null ? opts.phase : undefined,
+      milestone: opts.milestone != null ? opts.milestone : undefined,
+      task_id: opts.task_id || undefined,
+      wave: opts.wave != null ? opts.wave : undefined,
+      retry_of: opts.retry_of || undefined,
+      started_at: now,
+    },
+  };
+  return token;
+}
+
+// finish(token, { status, ... }) → writes the JSONL line + optional log file
+function finish(token, result) {
+  if (!token || !token.record) throw new Error("finish: invalid token");
+  if (!telemetryEnabled()) return { written: false, reason: "telemetry-off" };
+
+  const cwd = result.cwd || process.cwd();
+  if (!fs.existsSync(planningDir(cwd))) {
+    return { written: false, reason: "no-planning-dir" };
+  }
+
+  const finishedMs = Date.now();
+  const record = {
+    ...token.record,
+    status: result.status,
+    started_at: token.record.started_at,
+    finished_at: new Date(finishedMs).toISOString(),
+    duration_ms: finishedMs - token.started_ms,
+    input_tokens: result.input_tokens,
+    output_tokens: result.output_tokens,
+    cache_read_tokens: result.cache_read_tokens,
+    cache_creation_tokens: result.cache_creation_tokens,
+    tool_calls_count: result.tool_calls_count,
+    files_changed: Array.isArray(result.files_changed) ? [...new Set(result.files_changed)] : undefined,
+    commit_sha: result.commit_sha || undefined,
+    verifier_score: result.verifier_score,
+    verification_result: result.verification_result,
+    failure_reason: result.failure_reason,
+    failure_detail: truncTail(result.failure_detail, 500),
+  };
+
+  if (!VALID_AGENT_TYPES.has(record.agent_type)) {
+    record.failure_reason = record.failure_reason || "unknown";
+    // don't reject — we want the trace even if the caller misnamed itself
+  }
+  if (!VALID_STATUS.has(record.status)) {
+    record.status = "failure";
+    record.failure_reason = record.failure_reason || "unknown";
+  }
+
+  // Side log for non-success runs.
+  if (record.status !== "success" && typeof result.full_stderr === "string" && result.full_stderr.length) {
+    try {
+      ensureDir(logDir(cwd));
+      const logFile = path.join(logDir(cwd), `${record.run_id}.log`);
+      fs.writeFileSync(logFile, result.full_stderr);
+      record.log_file = path.relative(cwd, logFile).split(path.sep).join("/");
+    } catch {
+      // Side-log is best-effort — never block the JSONL write.
+    }
+  }
+
+  // Drop undefined keys for a compact line.
+  const clean = {};
+  for (const [k, v] of Object.entries(record)) if (v !== undefined) clean[k] = v;
+
+  const line = JSON.stringify(clean) + "\n";
+  ensureDir(planningDir(cwd));
+  fs.appendFileSync(jsonlPath(cwd), line);
+  return { written: true, run_id: record.run_id, log_file: record.log_file };
+}
+
+// ─── Reader ────────────────────────────────────────────────────────────
+
+function read(cwd, opts) {
+  const file = jsonlPath(cwd);
+  if (!fs.existsSync(file)) return [];
+  const lines = fs.readFileSync(file, "utf8").split(/\r?\n/).filter(Boolean);
+  const records = [];
+  for (const line of lines) {
+    try { records.push(JSON.parse(line)); }
+    catch { /* skip corrupt line; we never want a single bad record to mask the rest */ }
+  }
+  let out = records;
+  if (opts && opts.failed) {
+    out = out.filter((r) => r.status !== "success");
+  }
+  if (opts && opts.task_id) {
+    out = out.filter((r) => r.task_id === opts.task_id);
+  }
+  if (opts && opts.phase != null) {
+    out = out.filter((r) => r.phase === opts.phase);
+  }
+  if (opts && opts.limit) {
+    out = out.slice(-opts.limit);
+  }
+  return out;
+}
+
+function prune(cwd, beforeIso) {
+  const file = jsonlPath(cwd);
+  if (!fs.existsSync(file)) return { removed: 0, logs_removed: 0 };
+  const cutoff = Date.parse(beforeIso);
+  if (!Number.isFinite(cutoff)) throw new Error(`prune: invalid date "${beforeIso}"`);
+
+  const lines = fs.readFileSync(file, "utf8").split(/\r?\n/).filter(Boolean);
+  const kept = [];
+  const removedRunIds = [];
+  for (const line of lines) {
+    let rec;
+    try { rec = JSON.parse(line); }
+    catch { kept.push(line); continue; } // preserve unparseable; never destroy data we don't understand
+    const ts = Date.parse(rec.finished_at || rec.started_at || "");
+    if (Number.isFinite(ts) && ts < cutoff) {
+      removedRunIds.push(rec.run_id);
+    } else {
+      kept.push(line);
+    }
+  }
+  fs.writeFileSync(file, kept.join("\n") + (kept.length ? "\n" : ""));
+
+  let logsRemoved = 0;
+  if (fs.existsSync(logDir(cwd))) {
+    for (const id of removedRunIds) {
+      const lf = path.join(logDir(cwd), `${id}.log`);
+      try { fs.unlinkSync(lf); logsRemoved++; } catch {}
+    }
+  }
+  return { removed: removedRunIds.length, logs_removed: logsRemoved };
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  start,
+  finish,
+  read,
+  prune,
+  // exposed for tests / introspection
+  newRunId,
+  processSessionId,
+  jsonlPath,
+  logDir,
+};

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() {
@@ -159,10 +160,10 @@ const QUALIA_AGENT_FILES = [
 ];
 
 // 3 Qualia bin scripts.
-const QUALIA_BIN_FILES = ["state.js", "qualia-ui.js", "statusline.js", "knowledge.js", "knowledge-flush.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) => {
@@ -553,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)}"`;
 
@@ -564,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 = [];
@@ -595,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`);
@@ -618,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`);
@@ -626,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
@@ -730,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
@@ -781,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}`);
@@ -802,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}`);
@@ -874,6 +931,61 @@ 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.
@@ -1001,6 +1113,84 @@ function cmdDoctor() {
   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("");
@@ -1009,13 +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}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(`    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?`);
@@ -1064,10 +1256,17 @@ 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();