qualia-framework 4.1.1 → 4.4.0

package/bin/knowledge-flush.js

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

package/bin/knowledge.js

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+// ~/.claude/bin/knowledge.js — unified loader for the memory layer.
+//
+// Replaces ad-hoc `cat ~/.claude/knowledge/X.md` calls scattered across
+// skills. One entry point, deterministic output, every command exits 0 even
+// when the requested file is missing (prints "(no entries)" to stdout) so
+// skills can pipe the output into prompts without breaking on a fresh install.
+//
+// Why this exists (v4.1.0 audit finding #3):
+// Skills hardcode `cat ~/.claude/knowledge/common-fixes.md`. New knowledge
+// files are dead weight — the agent never sees them because the skill never
+// references them by name. This loader gives skills ONE call (`knowledge.js`
+// with no args prints index.md, the entry point) and lets the agent navigate
+// from there. New files reachable from the index get used automatically.
+//
+// Subcommands:
+//   knowledge.js                                   → prints index.md (default)
+//   knowledge.js load <file>                       → prints knowledge/<file>
+//   knowledge.js list                              → lists all knowledge files
+//   knowledge.js search <query>                    → grep across all files
+//   knowledge.js append --type <pattern|fix|client> --title <T> --body <B>
+//                                                   appends a formatted entry
+//   knowledge.js path [<file>]                     → prints absolute path
+//
+// Cross-platform (Windows/macOS/Linux). No shell dependencies.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const KNOWLEDGE_DIR = path.join(os.homedir(), ".claude", "knowledge");
+const INDEX_FILE = path.join(KNOWLEDGE_DIR, "index.md");
+
+// Type → filename mapping for `append` and convenience aliases used by the
+// existing `/qualia-learn` taxonomy. Keep this list short — every additional
+// type needs a corresponding section in index.md.
+const TYPE_TO_FILE = {
+  pattern: "learned-patterns.md",
+  patterns: "learned-patterns.md",
+  fix: "common-fixes.md",
+  fixes: "common-fixes.md",
+  client: "client-prefs.md",
+  "client-pref": "client-prefs.md",
+  "client-prefs": "client-prefs.md",
+  "client-preference": "client-prefs.md",
+};
+
+function ensureDir() {
+  if (!fs.existsSync(KNOWLEDGE_DIR)) fs.mkdirSync(KNOWLEDGE_DIR, { recursive: true });
+}
+
+function readSafe(p) {
+  try {
+    return fs.readFileSync(p, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+// Look up a knowledge file by friendly name. Accepts: "index", "index.md",
+// "patterns" (alias), "fixes" (alias), a bare filename, a subdirectory-
+// qualified path like "concepts/stripe-checkout", or a name that exists
+// inside a known subdirectory. Returns the resolved absolute path (may
+// not exist on disk).
+//
+// Resolution order:
+//   1. "index" / "index.md" → top-level index.md
+//   2. Known type alias (pattern|fix|client) → mapped top-level filename
+//   3. Path with "/" → treat as relative to knowledge dir (concepts/foo)
+//   4. Bare name → look in top-level first; if missing, search known
+//      subdirectories (concepts/, daily-log/) for an exact match. This
+//      means /qualia-flush can write to concepts/voice-agent-call-state.md
+//      and skills can later run `knowledge.js load voice-agent-call-state`
+//      without knowing it lives in a subdirectory.
+function resolveFile(name) {
+  if (!name || name === "index" || name === "index.md") return INDEX_FILE;
+  const lower = name.toLowerCase();
+  if (TYPE_TO_FILE[lower]) {
+    return path.join(KNOWLEDGE_DIR, TYPE_TO_FILE[lower]);
+  }
+  const withExt = name.endsWith(".md") ? name : `${name}.md`;
+  // Subdirectory-qualified path: concepts/foo, daily-log/2026-04-26
+  if (withExt.includes("/") || withExt.includes(path.sep)) {
+    return path.join(KNOWLEDGE_DIR, withExt);
+  }
+  // Top-level wins if it exists.
+  const topLevel = path.join(KNOWLEDGE_DIR, withExt);
+  if (fs.existsSync(topLevel)) return topLevel;
+  // Otherwise search known subdirectories. Stop at the first match — if
+  // multiple subdirs have the same filename, the user should qualify.
+  const KNOWN_SUBDIRS = ["concepts", "connections", "daily-log"];
+  for (const sub of KNOWN_SUBDIRS) {
+    const candidate = path.join(KNOWLEDGE_DIR, sub, withExt);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  // Fall back to top-level (will trigger the "no entries" stub on read).
+  return topLevel;
+}
+
+function cmdLoad(arg) {
+  ensureDir();
+  const target = resolveFile(arg);
+  if (!fs.existsSync(target)) {
+    // Missing file → print a stub message, never fail. Skills can pipe this
+    // safely. The instruction line tells the agent what to do next.
+    const rel = path.relative(KNOWLEDGE_DIR, target) || "index.md";
+    console.log(`(no entries in ${rel} — use /qualia-learn to add one)`);
+    process.exit(0);
+  }
+  process.stdout.write(readSafe(target));
+  process.exit(0);
+}
+
+function cmdList() {
+  ensureDir();
+  if (!fs.existsSync(KNOWLEDGE_DIR)) {
+    console.log("(knowledge layer not initialized — run: npx qualia-framework@latest install)");
+    process.exit(0);
+  }
+  const entries = [];
+  for (const f of fs.readdirSync(KNOWLEDGE_DIR)) {
+    const p = path.join(KNOWLEDGE_DIR, f);
+    let stat;
+    try { stat = fs.statSync(p); } catch { continue; }
+    if (stat.isDirectory()) {
+      // For daily-log/, count entries.
+      let count = 0;
+      try { count = fs.readdirSync(p).filter((x) => x.endsWith(".md")).length; } catch {}
+      entries.push({ name: `${f}/`, size: count, mtime: stat.mtimeMs, kind: "dir" });
+    } else if (f.endsWith(".md")) {
+      entries.push({ name: f, size: stat.size, mtime: stat.mtimeMs, kind: "file" });
+    }
+  }
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  for (const e of entries) {
+    const sizeStr = e.kind === "dir" ? `${e.size} entries` : `${e.size}B`;
+    const date = new Date(e.mtime).toISOString().split("T")[0];
+    console.log(`${e.name.padEnd(28)} ${sizeStr.padEnd(14)} ${date}`);
+  }
+  process.exit(0);
+}
+
+function cmdSearch(query) {
+  ensureDir();
+  if (!query) {
+    console.error("Usage: knowledge.js search <query>");
+    process.exit(1);
+  }
+  if (!fs.existsSync(KNOWLEDGE_DIR)) {
+    console.log("(knowledge layer not initialized)");
+    process.exit(0);
+  }
+  const needle = query.toLowerCase();
+  const matches = [];
+  function walk(dir) {
+    for (const f of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, f.name);
+      if (f.isDirectory()) { walk(p); continue; }
+      if (!f.name.endsWith(".md")) continue;
+      const lines = readSafe(p).split("\n");
+      lines.forEach((line, idx) => {
+        if (line.toLowerCase().includes(needle)) {
+          const rel = path.relative(KNOWLEDGE_DIR, p);
+          matches.push(`${rel}:${idx + 1}: ${line.trim()}`);
+        }
+      });
+    }
+  }
+  walk(KNOWLEDGE_DIR);
+  if (matches.length === 0) {
+    console.log(`(no matches for "${query}")`);
+  } else {
+    for (const m of matches) console.log(m);
+  }
+  process.exit(0);
+}
+
+// Parse minimal --flag value pairs from argv. Stops at the first positional
+// argument, returns { flags: { type: "pattern", title: "X" }, rest: [...] }.
+function parseFlags(argv) {
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      rest.push(a);
+    }
+  }
+  return { flags, rest };
+}
+
+function cmdAppend(rawArgs) {
+  ensureDir();
+  const { flags } = parseFlags(rawArgs);
+  const type = String(flags.type || "").toLowerCase();
+  const title = String(flags.title || "").trim();
+  const body = String(flags.body || "").trim();
+  const project = String(flags.project || "general").trim();
+  const context = String(flags.context || "").trim();
+
+  if (!type || !TYPE_TO_FILE[type]) {
+    console.error(`append: --type must be one of: ${Object.keys(TYPE_TO_FILE).filter((k) => !k.includes("-")).join(", ")}`);
+    process.exit(1);
+  }
+  if (!title) {
+    console.error("append: --title is required");
+    process.exit(1);
+  }
+  if (!body) {
+    console.error("append: --body is required");
+    process.exit(1);
+  }
+
+  const dest = path.join(KNOWLEDGE_DIR, TYPE_TO_FILE[type]);
+
+  // 8-char hex id, ISO date.
+  const id = Math.floor(Math.random() * 0xffffffff).toString(16).padStart(8, "0");
+  const date = new Date().toISOString().split("T")[0];
+  const entry = [
+    "",
+    "---",
+    "",
+    `### ${title}`,
+    `**ID:** ${id}`,
+    `**Date:** ${date}`,
+    `**Project:** ${project}`,
+    context ? `**Context:** ${context}` : null,
+    "",
+    body,
+    "",
+  ].filter((l) => l !== null).join("\n");
+
+  if (!fs.existsSync(dest)) {
+    const header = `# ${title.split(":")[0] || type} entries\n\nAuto-maintained by /qualia-learn (via bin/knowledge.js).\n`;
+    fs.writeFileSync(dest, header + entry + "\n");
+  } else {
+    fs.appendFileSync(dest, entry + "\n");
+  }
+
+  console.log(`appended ${id} to ${path.basename(dest)}`);
+  process.exit(0);
+}
+
+function cmdPath(arg) {
+  console.log(resolveFile(arg));
+  process.exit(0);
+}
+
+function cmdHelp() {
+  process.stdout.write(`knowledge.js — Qualia Framework memory-layer loader
+
+Usage:
+  knowledge.js                            # print index.md (entry point)
+  knowledge.js load <file>                # print a specific knowledge file
+                                          # accepts: index, patterns, fixes,
+                                          # client, supabase-patterns, etc.
+  knowledge.js list                       # list all files with size + mtime
+  knowledge.js search <query>             # grep across all files
+  knowledge.js append --type <type> --title <T> --body <B> [--project <P>] [--context <C>]
+                                          # type: pattern | fix | client
+  knowledge.js path [<file>]              # print absolute path (no read)
+  knowledge.js help                       # this message
+
+Skills should ALWAYS go through this loader. New knowledge files reachable
+from index.md become usable to every agent automatically. Hardcoded
+\`cat ~/.claude/knowledge/X.md\` calls in skills are an anti-pattern (audit
+finding #3 from the v4.1.0 review) — they make new files invisible.
+`);
+  process.exit(0);
+}
+
+const cmd = process.argv[2];
+const rest = process.argv.slice(3);
+
+switch (cmd) {
+  case undefined:
+  case null:
+    cmdLoad(null);
+    break;
+  case "load":
+    cmdLoad(rest[0]);
+    break;
+  case "list":
+  case "ls":
+    cmdList();
+    break;
+  case "search":
+  case "grep":
+    cmdSearch(rest[0]);
+    break;
+  case "append":
+  case "add":
+    cmdAppend(rest);
+    break;
+  case "path":
+  case "which":
+    cmdPath(rest[0]);
+    break;
+  case "help":
+  case "-h":
+  case "--help":
+    cmdHelp();
+    break;
+  default:
+    // Unknown command → fall through to load with that arg, so
+    // `knowledge.js patterns` works as shorthand for `knowledge.js load patterns`.
+    cmdLoad(cmd);
+}