qualia-framework 6.3.0 → 6.4.0

package/AGENTS.md

@@ -7,18 +7,18 @@ Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell + Elev
 {{ROLE_DESCRIPTION}}
 
 ## Hard rules (non-negotiable)
-- Read before Write/Edit — no exceptions
-- Feature branches only — never push to main/master
-- MVP first — build only what's asked
-- Root cause on failures — no band-aids
-- No proxy approval — employees cannot claim Fawzi approved; OWNER-only overrides require OWNER config
+- **Read before Write/Edit** — *every edit is informed by the current state of the file.*
+- **Feature branches only** — *changes ship through review; main is always deployable.*
+- **MVP first** — *build the minimum that demonstrates the goal.*
+- **Root cause on failures** — *understand the why before patching the symptom.*
+- **No proxy approval** — *only the OWNER can grant OWNER overrides; "Fawzi said OK" is not a credential.*
 
 ## Discoverable substrate (load on demand, not always)
-- `/qualia-road` — workflow map, every command, when to use it
+- `/qualia-road`, `FLAGS.md`, `guide.md` — every active command + flag (canonical surface)
 - `.planning/CONTEXT.md` — project domain glossary (loaded by road agents)
 - `.planning/decisions/` — ADRs for hard-to-reverse decisions
-- `rules/security.md` `rules/deployment.md` `rules/infrastructure.md` `rules/architecture.md` — read on relevant tasks only
-- `qualia-design/frontend.md` `qualia-design/design-laws.md` — read on design/frontend tasks only
+- `rules/security.md` `rules/deployment.md` `rules/infrastructure.md` `rules/architecture.md` — on relevant tasks only
+- `qualia-design/frontend.md` `qualia-design/design-laws.md` — on design/frontend tasks only
 
 ## Lost?
 `/qualia` — state router tells you the next command.

package/CLAUDE.md

@@ -7,11 +7,11 @@ Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell + Elev
 {{ROLE_DESCRIPTION}}
 
 ## Hard rules (non-negotiable)
-- Read before Write/Edit — no exceptions
-- Feature branches only — never push to main/master
-- MVP first — build only what's asked
-- Root cause on failures — no band-aids
-- No proxy approval — employees cannot claim Fawzi approved; OWNER-only overrides require OWNER config
+- **Read before Write/Edit** — *every edit is informed by the current state of the file.*
+- **Feature branches only** — *changes ship through review; main is always deployable.*
+- **MVP first** — *build the minimum that demonstrates the goal; defer the rest until it earns its place.*
+- **Root cause on failures** — *understand the why before patching the symptom.*
+- **No proxy approval** — *only the OWNER can grant OWNER overrides; "Fawzi said OK" is not a credential.*
 
 ## Discoverable substrate (load on demand, not always)
 - `/qualia-road` — workflow map, every command, when to use it

package/README.md

@@ -1,42 +1,20 @@
-# Qualia Framework v6.3.0
-
-A harness engineering framework for Claude Code and OpenAI Codex. It installs into `~/.claude/` and/or `~/.codex/` and wraps your AI-assisted development workflow with structured planning, execution, verification, and deployment gates.
-
-It is not an application framework like Rails or Next.js. It doesn't generate code, run servers, or process data. It's an opinionated workflow layer that tells Claude how to plan, build, and verify your projects end-to-end, from "tell me what you want to make" to "here's the handoff doc for your client."
-
-**v6.3.0** — Harness hardening pass. Default install surface drops to 23 active skills, retired helper command sources are removed and pruned from older installs, `/qualia-polish --vibe` absorbs the separate vibe command, `harness-eval.js` writes scored eval artifacts, ERP reports/snapshots carry the latest eval score, and `state.js` refuses PASS when machine contract evidence is missing/failing or the verification report contains `INSUFFICIENT EVIDENCE`.
-**v6.2.11** — Owner approval integrity. Fawzi's install code is now `QS-FAWZI-11`; employees cannot use `QUALIA_SHIP_FORCE=1`; deploy refusals say why and what to run next; and employee "Fawzi said OK" proxy-approval claims are silently counted for ERP policy review.
-**v6.2.10** — Codex status line is now a publish-blocking install contract. Installer guarantees `[tui].status_line` in `~/.codex/config.toml`, `/qualia-doctor` verifies the native bottom line, and package smoke tests assert the Codex TUI segments are present.
-**v6.2.9** — Codex hook noise + status line. Conditional PreToolUse hooks no longer status-message on every Bash call (Codex was printing 8 "Running hook…" lines on every command). Self-filtering added to `pre-deploy-gate.js` and `pre-push.js` so they never trip on unrelated commands (Claude's substring matcher was firing them on for-loop arguments). Installer now writes `[tui] status_line = [...]` to Codex's `config.toml` for the rich native bottom status line.
-
-**v6.2.8** — Codex `/goal` integration + install hardening. Phase-start skills now set the Codex thread goal (with token budget) via `bin/codex-goal.js` and `rules/codex-goal.md`. Installer fixes: agent TOMLs now emit `name = "..."` (Codex 0.133 was rejecting all 9), ERP API key is mirrored from `~/.claude/` → `~/.codex/`, and deprecated skills (`qualia-task`, `qualia-quick`, `qualia-polish-loop`, `qualia-design`, `qualia-prd`) are pruned on upgrade.
-
-**v6.2.7** — Codex runtime compatibility. The installer now writes Codex-native hooks, TOML agents, bin scripts, rules, skills, templates, knowledge, guide, and role config under `~/.codex/`, not just `AGENTS.md`.
-
-**The v5 line (preserved):**
-- **v5.0**, alignment discipline. CONTEXT.md domain glossary, decisions/ ADRs, zoom/queue helper experiments, slim CLAUDE.md per Matt Pocock's instruction-budget rule, insights-driven hooks.
-- **v5.1**, autonomous visual-polish loop. Screenshots a URL at three viewports, scores design dimensions with vision, fixes top issues, loops until pass or kill-switch. Multi-target installer (Claude Code + Codex AGENTS.md + Both).
-- **v5.2**, polish-loop reliability. `--reduced-motion` capture flag, `--routes URL1,URL2` multi-route mode, first supervised end-to-end run.
-- **v5.3**, Matt Pocock gaps closed. hook-generation utility experiment, `/qualia-optimize --deepen` Step 5b parallel-interface design (3 fan-out agents producing radically different interfaces).
-- **v5.4-5.5**, token-discipline and plan-discipline. Cache-aware spawn ordering, scope-reduction prohibition, decision-coverage audit, requirement-coverage check.
-- **v5.6**, Demo vs Full Project gate at kickoff. Mandatory discovery interview via `/qualia-discuss` in PROJECT MODE (8 questions for demos, 14 for full projects). Demo-extension branch in `/qualia-milestone` for client-signs-after-demo conversion.
-- **v5.7**, `/qualia-feature` consolidates `/qualia-quick` + `/qualia-task` into one auto-scoped command.
-- **v5.8**, surface cleanup. `/qualia-polish --loop` replaces `/qualia-polish-loop`. `/qualia-quick`, `/qualia-task`, and `/qualia-prd` removed (deprecated in v5.7).
-- **v5.9**, deep-research fixes. Surface-drift test (`tests/refs.test.sh`) catches dead command references on every release. ERP report retry queue (`bin/erp-retry.js`) replaces the v5.8 lying retry message with a real persistent queue. Four structured agents (verifier, plan-checker, roadmapper, qa-browser) move to Sonnet for ~40% per-phase cost cut. Verifier downgrades to FAIL on any `INSUFFICIENT EVIDENCE` line, closing the false-pass vector.
-- **v5.9.1**, kickoff UX fix. `/qualia-new` now opens with the Demo/Full/Quick gate as Step 1 (`AskUserQuestion`), then exactly one free-text pitch question, then mandatory hand-off to `/qualia-discuss` — no ad-hoc clarification questioning between them. The shape gate drives the whole downstream interview, so it must come first.
-- **v5.9.2**, hook ordering + ERP payload fixes. `pre-push.js` self-gates against `branch-guard.js` so a blocked-push no longer leaves an orphan bot commit in local history. `qualia-report` ERP payload omits empty ISO datetime fields (`session_started_at`, `last_pushed_at`) instead of sending `''`, which the ERP validator rejected as 422.
-- **v6.0.0**, audit + cleanup pass. See CHANGELOG for the full list. Highlights: uninstall/migrate manifests fixed, silent hook `catch{}` blocks now traced, phantom `rules/frontend.md` references replaced, `/qualia-learn` and `/qualia-map` declare their actually-used tools, `/qualia-plan` revision-cycle contradiction reconciled (max 2), `agents/planner.md` and `agents/qa-browser.md` MCP tools declared in frontmatter, `rules/trust-boundary.md` extracted, hardcoded `/tmp` paths replaced with `mktemp`, fail-collect test runner, pre-v4 CHANGELOG archived.
-- **v6.1.0**, `/qualia-polish --vibe` adds a fast layout-preserving design pivot path and strengthens design-surface guards.
-- **v6.2.0**, removes hook-created bot commits. The ERP/report contract is `/qualia-report` POSTs, not passive git scraping of `tracking.json`.
-- **v6.2.1**, active-surface drift guard. README, guide, onboarding, ERP contract, road, milestone, polish, verify, and roadmapper wording now align with v6.2 behavior; refs tests fail on the stale claims.
-- **v6.2.2**, Framework/Memory/ERP clarity. ERP can hand a work packet into Framework sessions, reports can carry ERP-native IDs, and public npm install proof is a first-class release smoke.
-- **v6.2.3**, ERP ID guard. ERP-native IDs are UUID-only in report payloads; slugs remain in `project_id`/`team_id`.
-- **v6.2.4**, report payload contract. The ERP payload builder is now a shipped, tested script instead of shell-embedded inline code.
-- **v6.2.5**, project snapshot export. Framework can write `.planning/snapshots/project-snapshot-*.json` for explicit ERP/admin import.
-- **v6.2.6**, project snapshot upload. Framework can POST that project snapshot directly to ERP's project snapshot intake.
-- **v6.2.7**, Codex runtime compatibility. Codex installs now get native `hooks.json`, `agents/*.toml`, runtime scripts, rules, skills, templates, knowledge, guide, and config under `~/.codex/`.
-
-The Full Journey architecture carries forward: `/qualia-new` maps the entire project arc from kickoff to client handoff upfront, and the Road chains end-to-end in `--auto` mode with only two human gates per project.
+# Qualia Framework
+
+A vertical, two-harness, owner-first workflow framework for **Claude Code** and **OpenAI Codex**, opinionated for a Cyprus-based **Next.js · Supabase · Vercel · OpenRouter · Retell** stack.
+
+Qualia tells the agent how to plan, build, verify, and ship — end-to-end, from kickoff to client handoff. It is not an application framework. It is the harness that makes the agent productive on *your* stack.
+
+Read [`SOUL.md`](./SOUL.md) for the identity statement (17 lines).
+
+## First commands
+
+```text
+/qualia-new      Set up a new project (kickoff interview → research → roadmap)
+/qualia          Smart router — "what's my next command?"
+/qualia-feature  Add a single feature (auto-scoped, inline or fresh spawn)
+```
+
+The full road and command reference live in [`guide.md`](./guide.md). Every skill flag is in [`FLAGS.md`](./FLAGS.md). When something breaks, see [`TROUBLESHOOTING.md`](./TROUBLESHOOTING.md). Release history is in [`CHANGELOG.md`](./CHANGELOG.md).
 
 ## Don't run Claude's `/init` in a Qualia project
 

package/bin/cli.js

@@ -212,7 +212,9 @@ const QUALIA_HOOK_FILES = [
 ];
 const QUALIA_LEGACY_HOOK_FILES = [
   "block-env-edit.js", // removed in v3.2.0
-  "pre-compact.js", // removed in v6.2.0 — state.js journal makes bot-commits redundant
+  // pre-compact.js was removed in v6.2.0 and REINSTATED in v6.3.2 with a
+  // different mechanism (sidecar snapshot, no git commits). It's an active
+  // hook now — not in the legacy list.
 ];
 
 // Qualia agents — only these are removed.
@@ -767,22 +769,24 @@ function cmdMigrate() {
     }
   }
 
-  // PreCompact: pre-compact.js was removed in v6.2.0 (state.js already provides
-  // crash-safe atomic writes with a write-ahead journal — the bot commit added
-  // no durability). Strip any legacy entry; drop the event key if it's empty.
-  if (Array.isArray(settings.hooks.PreCompact)) {
-    const beforeLen = settings.hooks.PreCompact.length;
-    settings.hooks.PreCompact = settings.hooks.PreCompact
-      .map(block => {
-        if (!block || !Array.isArray(block.hooks)) return block;
-        return { ...block, hooks: block.hooks.filter(h => extractScriptName(h && h.command) !== "pre-compact.js") };
-      })
-      .filter(block => Array.isArray(block.hooks) && block.hooks.length > 0);
-    const removed = beforeLen !== settings.hooks.PreCompact.length || settings.hooks.PreCompact.length === 0;
-    if (settings.hooks.PreCompact.length === 0) delete settings.hooks.PreCompact;
-    if (removed) {
+  // PreCompact: wire pre-compact.js (v6.3.2 — sidecar snapshot, no git).
+  // If a PreCompact array exists, ensure our hook is in it; otherwise create it.
+  if (!Array.isArray(settings.hooks.PreCompact)) {
+    settings.hooks.PreCompact = [{ matcher: ".*", hooks: [{ type: "command", command: nodeCmd("pre-compact.js"), timeout: 10 }] }];
+    changes++;
+    console.log(`  ${GREEN}+${RESET} Added PreCompact hook (pre-compact.js)`);
+  } else {
+    let preCompactEntry = settings.hooks.PreCompact.find(e => e.matcher === ".*");
+    if (!preCompactEntry) {
+      preCompactEntry = { matcher: ".*", hooks: [] };
+      settings.hooks.PreCompact.push(preCompactEntry);
+    }
+    if (!Array.isArray(preCompactEntry.hooks)) preCompactEntry.hooks = [];
+    const exists = preCompactEntry.hooks.some(h => extractScriptName(h && h.command) === "pre-compact.js");
+    if (!exists) {
+      preCompactEntry.hooks.push({ type: "command", command: nodeCmd("pre-compact.js"), timeout: 10 });
       changes++;
-      console.log(`  ${GREEN}-${RESET} Removed legacy pre-compact.js from PreCompact`);
+      console.log(`  ${GREEN}+${RESET} Wired pre-compact.js into PreCompact`);
     }
   }
 
@@ -1329,6 +1333,10 @@ function cmdDoctor() {
       "bin/report-payload.js",
       "bin/project-snapshot.js",
       "bin/planning-hygiene.js",
+      "bin/prune-deprecated.js",
+      "bin/learning-candidates.js",
+      "bin/status-snapshot.js",
+      "bin/security-scan.js",
       "knowledge/agents.md",
       "knowledge/index.md",
       "knowledge/daily-log",
@@ -1392,6 +1400,31 @@ function cmdDoctor() {
         check("Codex config.toml status_line parseable", false, e.message);
       }
     }
+
+    // Ghost-skill detection: retired skills must NOT remain in skills/ or the harness
+    // will keep advertising them as live invocable commands ("trap skills").
+    try {
+      const { findGhostSkills, pruneGhostSkills } = require("./prune-deprecated.js");
+      const ghosts = findGhostSkills(home);
+      if (ghosts.length === 0) {
+        check(`${label} no retired ghost skills`, true);
+      } else {
+        // Auto-prune. Doctor is the right place — users run it often, and the action
+        // is safe (RETIRED_SKILLS is a static, hand-curated list).
+        const { removed, errors } = pruneGhostSkills(home);
+        if (errors.length > 0) {
+          // Don't silently swallow filesystem errors — surface them so the user
+          // can fix the underlying permission/mount issue. Trap skills will keep
+          // appearing until the prune actually succeeds.
+          const hint = errors.map((e) => `${e.name}: ${e.error}`).join("; ");
+          check(`${label} ghost-skill prune (${removed.length} ok, ${errors.length} failed)`, false, hint);
+        } else {
+          check(`${label} pruned ${removed.length} ghost skill(s): ${removed.join(", ")}`, true);
+        }
+      }
+    } catch (e) {
+      check(`${label} ghost-skill prune`, false, e.message);
+    }
   }
 
   // ── Version vs. installed ──────────────────────────────
@@ -1562,6 +1595,9 @@ function cmdHelp() {
   console.log(`    qualia-framework ${TEAL}trust${RESET}        Score install, state, contracts, memory, ERP (${DIM}--json${RESET})`);
   console.log(`    qualia-framework ${TEAL}eval${RESET}         Write/run project harness eval scoring (${DIM}--run --write --json${RESET})`);
   console.log(`    qualia-framework ${TEAL}flush${RESET}        Promote daily-log → curated knowledge (memory layer)`);
+  console.log(`    qualia-framework ${TEAL}learn-scan${RESET}   Scan recent commits + daily-log for repeated patterns worth promoting (${DIM}--since=N --print${RESET})`);
+  console.log(`    qualia-framework ${TEAL}status${RESET}       Portable operator snapshot — install + project + work + ERP + memory (${DIM}--write --json --exit-code${RESET})`);
+  console.log(`    qualia-framework ${TEAL}secure${RESET}       Security scan of agent config — secrets/permissions/hook hygiene (${DIM}--json --write --paths${RESET})`);
   console.log("");
   console.log(`  ${WHITE}After install:${RESET}`);
   console.log(`    ${TG}/qualia${RESET}          What should I do next?`);
@@ -1659,6 +1695,18 @@ switch (cmd) {
   case "knowledge-flush":
     cmdFlush();
     break;
+  case "learn-scan":
+  case "learning-candidates":
+    require("./learning-candidates.js").main();
+    break;
+  case "status":
+  case "operator-status":
+    require("./status-snapshot.js").main();
+    break;
+  case "secure":
+  case "security-scan":
+    require("./security-scan.js").main();
+    break;
   default:
     cmdHelp();
 }

package/bin/command-surface.js

@@ -28,6 +28,8 @@ const ACTIVE_SKILLS = [
   "qualia-road",
   "qualia-learn",
   "qualia-postmortem",
+  "qualia-idk",
+  "qualia-secure",
   "zoho-workflow",
 ];
 
@@ -43,7 +45,9 @@ const RETIRED_SKILLS = [
   "qualia-debug",      // folded into qualia-fix for actionable repairs
   "qualia-vibe",       // folded into qualia-polish modes/documentation
   "qualia-help",       // guide/help files remain installed; no slash command
-  "qualia-idk",        // folded into qualia router diagnostic branch
+  // qualia-idk RESTORED in v6.3.1 — owner pivot: keep the deep diagnostic
+  // separate from the cheap router. /qualia stays mechanical, /qualia-idk
+  // does the heavy three-scan synthesis with paste-ready command sequence.
   "qualia-pause",      // folded into qualia router handoff branch
   "qualia-resume",     // folded into qualia router handoff branch
   "qualia-zoom",       // folded into qualia-map/qualia-review as an analysis mode

package/bin/install.js

@@ -661,12 +661,18 @@ async function main() {
   } catch {}
   // Purge deprecated hooks from existing installs on upgrade.
   // - block-env-edit.js (v3.2.0): team now has full read/write on .env*.
-  // - pre-compact.js (v6.2.0): bot-committed STATE.md + tracking.json on
-  //   context compaction for ERP visibility. ERP never read tracking.json
-  //   from git, and state.js already provides crash-safe atomic writes with
-  //   a write-ahead journal (state.js:36-64) — the bot commit added no
-  //   durability, just history noise.
-  const DEPRECATED_HOOKS = ["block-env-edit.js", "pre-compact.js"];
+  //
+  // Note: pre-compact.js was removed in v6.2.0 (it bot-committed STATE.md +
+  // tracking.json, which added no durability over state.js's atomic writes
+  // + journal). v6.3.2 reintroduces pre-compact.js but with a fundamentally
+  // different mechanism — it writes a markdown SIDECAR to
+  // .planning/.compaction-snapshot.md (no git, no state.js writes) so the
+  // next session can see what was in flight when compaction wiped context.
+  // Safe to ship as a fresh install; the v6.2.0 stripping logic in cli.js
+  // doctor remains, but only strips the OLD legacy command (which our v2
+  // hook does not match — different content, same filename is fine because
+  // install always overwrites).
+  const DEPRECATED_HOOKS = ["block-env-edit.js"];
   for (const f of DEPRECATED_HOOKS) {
     const p = path.join(hooksDest, f);
     try { if (fs.existsSync(p)) fs.unlinkSync(p); } catch {}
@@ -1100,11 +1106,20 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
         ],
       },
     ],
-    // v6.2.0: PreCompact intentionally empty. The qualiaHooks loop in the
-    // settings.json merge below still iterates over this key, so legacy
-    // Qualia-owned pre-compact.js entries get stripped from existing user
-    // settings on upgrade. Nothing new is wired in.
-    PreCompact: [],
+    // v6.3.2: PreCompact reintroduced with a NEW mechanism. The old hook
+    // (removed in v6.2.0) bot-committed STATE.md + tracking.json. This v2
+    // hook writes a markdown SIDECAR to .planning/.compaction-snapshot.md
+    // (no git, no state.js writes). The qualiaHooks loop below still
+    // iterates over this key, so any leftover legacy pre-compact.js wiring
+    // is replaced by the new one cleanly.
+    PreCompact: [
+      {
+        matcher: ".*",
+        hooks: [
+          { type: "command", command: nodeCmd("pre-compact.js"), timeout: 10 },
+        ],
+      },
+    ],
     Stop: [
       {
         matcher: ".*",

package/bin/learning-candidates.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// bin/learning-candidates.js — scan recent git history + daily-log for
+// repeated patterns and emit a list of skill-creation candidates.
+//
+// Run via:
+//   qualia-framework learn-scan           # writes ~/.claude/knowledge/learning-candidates.md
+//   qualia-framework learn-scan --print    # also prints to stdout
+//   qualia-framework learn-scan --since=7  # look at last 7 days (default: 14)
+//
+// What it detects:
+//   1. Repeated fix-scope patterns — "fix(auth):" appearing 3+ times in 14 days
+//      → suggest a skill or hook that prevents/diagnoses that class of bug.
+//   2. Repeated touched-file patterns — same file appearing in 4+ session
+//      checkpoints → suggest factoring or codifying the workflow around it.
+//   3. Repeated phrases in daily-log entries — heuristic, low-signal v1.
+//
+// What it does NOT do:
+//   - Auto-create skills. That's /qualia-skill-new's job (with human review).
+//   - Touch the wiki tier (knowledge/concepts/). That's /qualia-flush's job.
+//   - Run continuously in background. ECC's Haiku observer is over-engineered
+//     for Qualia's weekly cadence. Run this manually or via /qualia-flush.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawnSync } = require("child_process");
+
+function qualiaHome() {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(os.homedir(), ".claude");
+}
+
+function git(args, opts = {}) {
+  try {
+    const r = spawnSync("git", args, { encoding: "utf8", timeout: 3000, shell: process.platform === "win32", ...opts });
+    if (r.status !== 0) return "";
+    return (r.stdout || "").trim();
+  } catch {
+    return "";
+  }
+}
+
+function parseArgs(argv) {
+  const args = { print: false, sinceDays: 14 };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--print") args.print = true;
+    else if (a.startsWith("--since=")) {
+      const n = parseInt(a.split("=")[1], 10);
+      if (n > 0) args.sinceDays = n;
+    } else if (a === "--since" && argv[i + 1]) {
+      const n = parseInt(argv[++i], 10);
+      if (n > 0) args.sinceDays = n;
+    }
+  }
+  return args;
+}
+
+// Conventional Commits subject parser. Returns {type, scope} or null.
+function parseCommitSubject(subject) {
+  const m = subject.match(/^([a-z]+)(?:\(([^)]+)\))?(!)?:\s*(.+)$/i);
+  if (!m) return null;
+  return { type: m[1].toLowerCase(), scope: m[2] || "", description: m[4] };
+}
+
+function scanRepoCommits(repoRoot, sinceDays) {
+  const out = git(["log", `--since=${sinceDays}.days`, "--pretty=%H%x09%s"], { cwd: repoRoot });
+  if (!out) return [];
+  const commits = [];
+  for (const line of out.split("\n")) {
+    const [sha, subject] = line.split("\t");
+    if (!sha || !subject) continue;
+    const parsed = parseCommitSubject(subject);
+    if (parsed) commits.push({ sha, subject, ...parsed });
+  }
+  return commits;
+}
+
+function aggregateFixPatterns(commits) {
+  // Group fix-type commits by scope (or by first-word of description if no scope).
+  const groups = new Map();
+  for (const c of commits) {
+    if (c.type !== "fix") continue;
+    const key = c.scope || c.description.split(" ")[0].toLowerCase().replace(/[^a-z0-9-]/g, "");
+    if (!key) continue;
+    const arr = groups.get(key) || [];
+    arr.push(c);
+    groups.set(key, arr);
+  }
+  return [...groups.entries()]
+    .filter(([, arr]) => arr.length >= 3)
+    .sort((a, b) => b[1].length - a[1].length)
+    .map(([scope, arr]) => ({ scope, count: arr.length, samples: arr.slice(0, 3).map((c) => `${c.sha.slice(0, 7)} ${c.subject}`) }));
+}
+
+function readDailyLogs(qhome, sinceDays) {
+  const dir = path.join(qhome, "knowledge", "daily-log");
+  if (!fs.existsSync(dir)) return [];
+  const cutoff = Date.now() - sinceDays * 86_400_000;
+  const out = [];
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith(".md")) continue;
+    const m = f.match(/^(\d{4}-\d{2}-\d{2})\.md$/);
+    if (!m) continue;
+    const date = new Date(m[1] + "T00:00:00Z").getTime();
+    if (date < cutoff) continue;
+    try {
+      out.push({ date: m[1], content: fs.readFileSync(path.join(dir, f), "utf8") });
+    } catch {}
+  }
+  return out;
+}
+
+function aggregateTouchedFiles(dailyLogs) {
+  // Look for "touched=a,b,c" across entries. Count occurrences per file.
+  const counts = new Map();
+  for (const log of dailyLogs) {
+    const matches = log.content.matchAll(/touched=([^\s·]+)/g);
+    for (const m of matches) {
+      for (const f of m[1].split(",")) {
+        const k = f.trim();
+        if (!k) continue;
+        counts.set(k, (counts.get(k) || 0) + 1);
+      }
+    }
+  }
+  return [...counts.entries()]
+    .filter(([, n]) => n >= 4)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10)
+    .map(([file, count]) => ({ file, count }));
+}
+
+function render({ sinceDays, fixPatterns, touchedFiles, repoRoot }) {
+  const lines = [];
+  lines.push(`# Learning candidates — generated ${new Date().toISOString()}`);
+  lines.push("");
+  lines.push(`Scope: last ${sinceDays} days.`);
+  if (repoRoot) lines.push(`Repo: ${repoRoot}`);
+  lines.push("");
+  lines.push("Each candidate below is a pattern that recurred enough times to be worth promoting into a skill, agent, or hook. Review and act:");
+  lines.push("- `/qualia-skill-new` — create a Qualia skill for the workflow");
+  lines.push("- `/qualia-hook-gen` — convert a CLAUDE.md instruction into a deterministic hook");
+  lines.push("- `/qualia-learn` — save a one-off learning to the knowledge wiki");
+  lines.push("- Ignore — patterns that aren't worth automating");
+  lines.push("");
+
+  lines.push("## Repeated fix-scopes (Conventional Commits)");
+  if (fixPatterns.length === 0) {
+    lines.push("(none — no scope has 3+ fixes in the window)");
+  } else {
+    for (const fp of fixPatterns) {
+      lines.push(`### \`fix(${fp.scope})\` — ${fp.count} commits`);
+      lines.push("Recent samples:");
+      for (const s of fp.samples) lines.push(`- ${s}`);
+      lines.push("");
+      lines.push(`> **Suggested action:** if this keeps recurring, add a guard hook or a /qualia-skill-new dedicated to debugging \`${fp.scope}\`.`);
+      lines.push("");
+    }
+  }
+
+  lines.push("## Repeatedly-touched files");
+  if (touchedFiles.length === 0) {
+    lines.push("(none — no file appeared in 4+ session checkpoints)");
+  } else {
+    lines.push("File | Touched count");
+    lines.push("---|---:");
+    for (const t of touchedFiles) lines.push(`\`${t.file}\` | ${t.count}`);
+    lines.push("");
+    lines.push("> **Suggested action:** files touched this often may be a hotspot (deserves more tests) or a friction point (deserves a skill that automates the recurring edit).");
+  }
+  lines.push("");
+  lines.push("---");
+  lines.push("_Generated by `bin/learning-candidates.js`. Re-run with `qualia-framework learn-scan` or `qualia-framework learn-scan --since=30`._");
+
+  return lines.join("\n") + "\n";
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const qhome = qualiaHome();
+  const cwd = process.cwd();
+  const repoRoot = git(["rev-parse", "--show-toplevel"], { cwd }) || "";
+
+  const commits = repoRoot ? scanRepoCommits(repoRoot, args.sinceDays) : [];
+  const fixPatterns = aggregateFixPatterns(commits);
+  const dailyLogs = readDailyLogs(qhome, args.sinceDays);
+  const touchedFiles = aggregateTouchedFiles(dailyLogs);
+
+  const doc = render({ sinceDays: args.sinceDays, fixPatterns, touchedFiles, repoRoot });
+
+  const outDir = path.join(qhome, "knowledge");
+  if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
+  const outPath = path.join(outDir, "learning-candidates.md");
+  fs.writeFileSync(outPath, doc);
+
+  // Stamp last-scan time.
+  fs.writeFileSync(path.join(qhome, ".qualia-last-learning-scan"), String(Date.now()));
+
+  if (args.print) {
+    process.stdout.write(doc);
+  } else {
+    console.log(`Wrote ${fixPatterns.length} fix-pattern candidate(s) + ${touchedFiles.length} hot file(s) to ${outPath}`);
+  }
+}
+
+module.exports = { main, aggregateFixPatterns, aggregateTouchedFiles, parseCommitSubject };
+
+if (require.main === module) {
+  try { main(); }
+  catch (e) {
+    console.error(`learn-scan failed: ${e.message}`);
+    process.exit(1);
+  }
+}

package/bin/prune-deprecated.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// Shared helper: prune retired skill folders from an install home (~/.claude or ~/.codex).
+//
+// Why a separate file: install.js already runs prune on install, but users often run
+// `qualia-framework doctor` more frequently than they re-install. When a skill is
+// retired (moved from ACTIVE_SKILLS → RETIRED_SKILLS in command-surface.js), the
+// folder must also be removed from the install home, or the harness will keep
+// advertising it as live and users will invoke "trap skills" that no longer route.
+//
+// Both install.js and cli.js (doctor) call this.
+
+const fs = require("fs");
+const path = require("path");
+const { RETIRED_SKILLS } = require("./command-surface.js");
+
+function findGhostSkills(baseDir) {
+  const skillsDir = path.join(baseDir, "skills");
+  if (!fs.existsSync(skillsDir)) return [];
+  return RETIRED_SKILLS.filter((name) => fs.existsSync(path.join(skillsDir, name)));
+}
+
+// Returns { removed: [names], errors: [{name, target, error}] }.
+// Callers can decide how to surface errors — the doctor flow logs them, the
+// install flow shows them as warnings. We do NOT silently swallow them (per
+// CodeRabbit review on PR #46): a permissions / mount-point failure during
+// prune leaves stale ghost skills installed and the user has no signal.
+function pruneGhostSkills(baseDir) {
+  const skillsDir = path.join(baseDir, "skills");
+  if (!fs.existsSync(skillsDir)) return { removed: [], errors: [] };
+  const removed = [];
+  const errors = [];
+  for (const name of RETIRED_SKILLS) {
+    const target = path.join(skillsDir, name);
+    try {
+      if (fs.existsSync(target)) {
+        fs.rmSync(target, { recursive: true, force: true });
+        removed.push(name);
+      }
+    } catch (err) {
+      errors.push({ name, target, error: err && err.message ? err.message : String(err) });
+    }
+  }
+  return { removed, errors };
+}
+
+module.exports = { findGhostSkills, pruneGhostSkills };
+
+if (require.main === module) {
+  // CLI: `node prune-deprecated.js <baseDir>` — useful for manual cleanup.
+  const baseDir = process.argv[2] || path.join(require("os").homedir(), ".claude");
+  const { removed, errors } = pruneGhostSkills(baseDir);
+  if (errors.length > 0) {
+    console.error(`Pruned ${removed.length} ghost skill(s); ${errors.length} failed:`);
+    for (const e of errors) console.error(`  ✗ ${e.name} (${e.target}): ${e.error}`);
+    if (removed.length > 0) for (const name of removed) console.log(`  - ${name}`);
+    process.exit(1);
+  }
+  if (removed.length === 0) {
+    console.log(`No ghost skills in ${baseDir}/skills/`);
+  } else {
+    console.log(`Pruned ${removed.length} ghost skill(s) from ${baseDir}/skills/:`);
+    for (const name of removed) console.log(`  - ${name}`);
+  }
+}

package/bin/runtime-manifest.js

@@ -23,6 +23,10 @@ const RUNTIME_BIN_SCRIPTS = [
   { file: "harness-eval.js", label: "harness-eval.js (project eval scoring + evidence artifact)" },
   { file: "codex-goal.js", label: "codex-goal.js (Codex /goal objective + token-budget suggester)" },
   { file: "planning-hygiene.js", label: "planning-hygiene.js (.planning organization scanner)" },
+  { file: "prune-deprecated.js", label: "prune-deprecated.js (ghost-skill cleanup for retired commands)" },
+  { file: "learning-candidates.js", label: "learning-candidates.js (scan recent commits + daily-log for patterns worth promoting)" },
+  { file: "status-snapshot.js", label: "status-snapshot.js (portable operator snapshot — install + project + work + ERP + memory)" },
+  { file: "security-scan.js", label: "security-scan.js (static security scanner for agent config — secrets, permissions, hook hygiene)" },
 ];
 
 function binFiles() {