qualia-framework 6.14.0 → 7.0.0

package/bin/last-report.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+// last-report.js — surface "where work was left off last time" at session start.
+//
+// WHY: the /qualia router classifies state from state.js, .continue-here.md, and
+// git log — but it ignores .planning/reports/, which is the richest "where we
+// left off" signal a team has. A teammate (or future-you) picking the project
+// back up should instantly see the last session's outcome and next step without
+// opening a file. This extracts a compact digest from the newest report so the
+// router can print it at the TOP of its output when a project is loaded.
+//
+// Reports are written by /qualia-report at .planning/reports/report-{YYYY-MM-DD}.md
+// (the date filename may carry a suffix, e.g. report-2026-05-31-session3.md). The
+// markdown has a "# Session Report — {date}" title, a "**Date:**" line, a
+// "## What Was Done" section (the summary), and a "## Next Steps" section.
+//
+// Read-only. Zero npm dependencies.
+// Exit 0 = a report was found, 1 = none found, 2 = bad input.
+
+const fs = require("fs");
+const path = require("path");
+
+// Pull a YYYY-MM-DD from a report filename. Returns null when absent so a
+// misnamed file falls back to mtime ordering rather than poisoning the sort.
+function dateFromName(name) {
+  const m = name.match(/(\d{4}-\d{2}-\d{2})/);
+  return m ? m[1] : null;
+}
+
+// Whole-day difference between two ISO-ish dates (report date vs --now). Floors
+// to a non-negative integer; a future report date (clock skew) reads as 0.
+function ageDays(dateStr, nowIso) {
+  if (!dateStr) return null;
+  const then = Date.parse(dateStr + "T00:00:00Z");
+  const now = nowIso ? Date.parse(nowIso) : Date.now();
+  if (Number.isNaN(then) || Number.isNaN(now)) return null;
+  return Math.max(0, Math.floor((now - then) / 86400000));
+}
+
+// Collapse markdown bullets/bold/whitespace into one tight prose line.
+function flatten(s) {
+  return s
+    .replace(/^\s+/, "")         // leading indentation, so list-marker anchors match
+    .replace(/\*\*/g, "")
+    .replace(/^[-*]\s+/, "")     // unordered bullet
+    .replace(/^\d+[.)]\s+/, "")  // ordered list marker (1. / 1))
+    .replace(/`/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+// Lines that carry no signal for a digest (metadata, blank, headings).
+function isNoise(line) {
+  const t = line.trim();
+  if (!t) return true;
+  if (t.startsWith("#")) return true;
+  if (/^\*\*[A-Za-z ]+:\*\*/.test(t)) return true; // **Project:** / **Date:** etc.
+  return false;
+}
+
+// Find the body under a "## {heading}" until the next "## " heading or EOF.
+function sectionBody(lines, headingRe) {
+  let i = lines.findIndex((l) => headingRe.test(l.trim()));
+  if (i === -1) return [];
+  const out = [];
+  for (let j = i + 1; j < lines.length; j++) {
+    if (/^##\s/.test(lines[j].trim())) break;
+    out.push(lines[j]);
+  }
+  return out;
+}
+
+// First meaningful sentence/clause of a section, capped to keep the digest tight.
+function firstMeaningful(bodyLines, cap = 160) {
+  for (const raw of bodyLines) {
+    if (isNoise(raw)) continue;
+    const flat = flatten(raw);
+    if (!flat) continue;
+    return flat.length > cap ? flat.slice(0, cap - 1).trimEnd() + "…" : flat;
+  }
+  return "";
+}
+
+// Extract the digest from a single report's markdown text.
+function digest(text) {
+  const lines = text.split(/\r?\n/);
+
+  // Date: prefer the explicit **Date:** line, else the title's trailing date.
+  let date = null;
+  const dateLine = lines.find((l) => /^\*\*Date:\*\*/.test(l.trim()));
+  if (dateLine) date = (dateFromName(dateLine) || null);
+  if (!date) {
+    const title = lines.find((l) => /^#\s+Session Report/.test(l.trim()));
+    if (title) date = dateFromName(title);
+  }
+
+  // Summary: first meaningful line of "## What Was Done", else first meaningful
+  // line of the whole body (so malformed reports still yield something).
+  let summary = firstMeaningful(sectionBody(lines, /^##\s+What Was Done/i));
+  if (!summary) summary = firstMeaningful(lines);
+
+  // Next: first meaningful line of "## Next Steps" / "## Next Step".
+  let next = firstMeaningful(sectionBody(lines, /^##\s+Next Steps?/i));
+
+  return { date, summary, next };
+}
+
+// Library: find the newest report under root and return its digest object.
+//   { found, file, date, summary, next, age_days }
+function latestReport(root, opts = {}) {
+  const dir = path.join(path.resolve(root || process.cwd()), ".planning", "reports");
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return { found: false, file: null, date: null, summary: "", next: "", age_days: null };
+  }
+
+  const reports = entries
+    .filter((f) => /^report-.*\.md$/.test(f))
+    .map((f) => {
+      const full = path.join(dir, f);
+      let mtime = 0;
+      try { mtime = fs.statSync(full).mtimeMs; } catch {}
+      return { file: f, full, date: dateFromName(f), mtime };
+    });
+
+  if (reports.length === 0) {
+    return { found: false, file: null, date: null, summary: "", next: "", age_days: null };
+  }
+
+  // Newest by filename date desc; tiebreak (same/absent date) by mtime desc.
+  reports.sort((a, b) => {
+    const ad = a.date || "";
+    const bd = b.date || "";
+    if (ad !== bd) return bd.localeCompare(ad);
+    return b.mtime - a.mtime;
+  });
+
+  const top = reports[0];
+  let text = "";
+  try { text = fs.readFileSync(top.full, "utf8"); } catch {}
+  const d = digest(text);
+  const date = d.date || top.date || null;
+
+  return {
+    found: true,
+    file: top.file,
+    date,
+    summary: d.summary,
+    next: d.next,
+    age_days: ageDays(date, opts.now),
+  };
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") args.json = true;
+    else if (a === "--cwd") args.cwd = argv[++i];
+    else if (a.startsWith("--cwd=")) args.cwd = a.slice(6);
+    else if (a === "--now") args.now = argv[++i]; // ISO; tests inject determinism
+    else if (a.startsWith("--now=")) args.now = a.slice(6);
+    else { args._bad = a; }
+  }
+  return args;
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  if (args._bad) {
+    console.error(`last-report: unknown argument '${args._bad}'`);
+    return 2;
+  }
+
+  let result;
+  try {
+    result = latestReport(args.cwd, { now: args.now });
+  } catch (e) {
+    console.error(`last-report: ${e.message || e}`);
+    return 2;
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return result.found ? 0 : 1;
+  }
+
+  if (!result.found) {
+    console.log("No session reports yet — nothing to surface.");
+    return 1;
+  }
+
+  const age = result.age_days == null ? "?" : result.age_days;
+  const summary = result.summary || "(no summary in report)";
+  let line = `Last session (${result.date || "undated"}, ${age}d ago): ${summary}`;
+  if (result.next) line += ` → next: ${result.next}`;
+  console.log(line);
+  return 0;
+}
+
+module.exports = { latestReport };
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}

package/bin/project-sync.js

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+// project-sync.js — the single Framework→ERP project-sync snapshot.
+//
+// WHY: the ERP already ingests per-session reports (report-payload.js →
+// /api/v1/reports) and a lean progress rollup (project-snapshot.js →
+// /api/v1/project-snapshots). What was missing is ONE complete payload the ERP
+// can use to RECONCILE a project's milestones, phases, tasks, and reports in a
+// single read — including REQ-ID completion per milestone and the trunk/merge
+// model so the ERP understands how feature branches become deployed main.
+//
+// This composes (never duplicates) the existing snapshot:
+//   - bin/project-snapshot.js   → identity, current position, journey, lifetime,
+//                                  quality (harness_eval), progress_percent
+//   - bin/state.js              → readMilestoneRequirements (REQ-ID completion),
+//                                  parseStateMd (roadmap phase rows)
+// and ADDS the B2-specific reconciliation surface on top:
+//   - milestones[] enriched with REQ-ID completion (total/complete/incomplete),
+//     phases count, tasks_completed, deployed_url, status (closed/current/future)
+//   - task_rollup (lifetime tasks/build/deploy + current-phase gap_cycles)
+//   - accountability { offroad_count, offroad[] } — off-milestone work tally
+//   - integration { model: "trunk", ... } — the PR/merge model the ERP must grok
+//   - schema_version so the ERP can evolve the contract safely
+//
+// Read-only. Zero npm dependencies. `--json` (or no flag) prints the object;
+// library buildProjectSync() returns it. Exit 0 = built, 2 = no .planning/.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const snapshotLib = require("./project-snapshot.js");
+
+// project-sync's contract version. Bump when the SHAPE changes so the ERP can
+// branch on it. (Distinct from project-snapshot's snapshot_version.)
+const SCHEMA_VERSION = 1;
+
+function readJson(file, fallback = {}) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function readText(file, fallback = "") {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return fallback;
+  }
+}
+
+// REQ-ID completion for one milestone, read from .planning/REQUIREMENTS.md.
+// Mirrors state.js readMilestoneRequirements() exactly (rows like
+// `| CORE-01 | M2: Name | Phase 3 | Complete |`) but is parameterized on the
+// planning dir so tests can point it at a temp fixture. tracked=false when
+// REQUIREMENTS.md is absent or has no rows for the milestone (→ ERP skips the
+// REQ gate for that milestone, can't reconcile what wasn't declared).
+function milestoneRequirements(planningDir, milestoneNum) {
+  const md = readText(path.join(planningDir, "REQUIREMENTS.md"), null);
+  if (md == null) return { tracked: false, total: 0, complete: 0, incomplete: [] };
+  const num = parseInt(milestoneNum, 10);
+  const rows = [];
+  for (const line of md.split(/\r?\n/)) {
+    if (!/^\s*\|/.test(line)) continue;
+    const cells = line
+      .split("|")
+      .map((c) => c.trim())
+      .filter((c, i, a) => !(i === 0 && c === "") && !(i === a.length - 1 && c === ""));
+    if (cells.length < 4) continue;
+    const [id, milestone, , status] = cells;
+    if (!/^[A-Z]+-\d+$/.test(id)) continue; // skip header + non-REQ rows
+    const m = milestone.match(/M(\d+)\b/);
+    if (!m || parseInt(m[1], 10) !== num) continue;
+    rows.push({ id, status: status || "" });
+  }
+  const incomplete = rows
+    .filter((r) => r.status.trim().toLowerCase() !== "complete")
+    .map((r) => ({ id: r.id, status: r.status }));
+  return {
+    tracked: rows.length > 0,
+    total: rows.length,
+    complete: rows.length - incomplete.length,
+    incomplete,
+  };
+}
+
+// Count phase rows declared for the project from STATE.md's roadmap table.
+// Used only as a fallback when a closed milestone summary carries no phase
+// count of its own. Best-effort: returns 0 when STATE.md is absent/malformed.
+function roadmapPhaseCount(planningDir) {
+  const md = readText(path.join(planningDir, "STATE.md"), "");
+  const m = md.match(/\| # \| Phase \| Goal \| Status \|\n\|[-|]+\|\n([\s\S]*?)(?=\n##|\n$|$)/);
+  if (!m) return 0;
+  return m[1]
+    .trim()
+    .split("\n")
+    .filter((row) => row.split("|").map((c) => c.trim()).filter(Boolean).length >= 4).length;
+}
+
+// Build the unified milestones[] for reconciliation. Source of truth ordering:
+//   1. JOURNEY.md milestones (the full planned arc) — gives num + name + total.
+//   2. tracking.milestones[] (closed summaries) — gives closed_at + per-milestone
+//      phases_completed/tasks_completed + deployed_url.
+//   3. tracking.milestone (current) — marks the active one.
+//   4. REQUIREMENTS.md — REQ-ID completion per milestone.
+// Each entry's `status` is closed | current | future so the ERP can reconcile
+// which milestones to mark done, in-progress, or pending.
+function buildMilestones(options) {
+  const { journey, closed, currentNum, planningDir } = options;
+  const closedByNum = new Map();
+  for (const m of closed) {
+    const n = Number(m && m.num);
+    if (Number.isFinite(n)) closedByNum.set(n, m);
+  }
+
+  // The full set of milestone numbers we know about: journey ∪ closed ∪ current.
+  const nums = new Set();
+  for (const m of journey) nums.add(Number(m.num));
+  for (const n of closedByNum.keys()) nums.add(n);
+  if (Number.isFinite(currentNum)) nums.add(currentNum);
+  const ordered = [...nums].filter((n) => Number.isFinite(n)).sort((a, b) => a - b);
+
+  const nameByNum = new Map(journey.map((m) => [Number(m.num), m.name]));
+
+  return ordered.map((num) => {
+    const closedSummary = closedByNum.get(num) || null;
+    const status = closedSummary
+      ? "closed"
+      : num === currentNum
+        ? "current"
+        : "future";
+    const req = milestoneRequirements(planningDir, num);
+    const entry = {
+      num,
+      name:
+        (closedSummary && closedSummary.name) ||
+        nameByNum.get(num) ||
+        `Milestone ${num}`,
+      status,
+      phases: Number(
+        (closedSummary && (closedSummary.phases_completed != null
+          ? closedSummary.phases_completed
+          : closedSummary.phases)) || 0
+      ),
+      tasks_completed: Number(
+        (closedSummary && closedSummary.tasks_completed) || 0
+      ),
+      requirements: {
+        tracked: req.tracked,
+        total: req.total,
+        complete: req.complete,
+        incomplete: req.incomplete,
+      },
+    };
+    if (closedSummary && closedSummary.closed_at) entry.closed_at = closedSummary.closed_at;
+    const deployedUrl = (closedSummary && closedSummary.deployed_url) || "";
+    if (deployedUrl) entry.deployed_url = deployedUrl;
+    return entry;
+  });
+}
+
+function buildProjectSync(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const home = options.home || os.homedir();
+  const planning = options.planningDir || path.join(cwd, ".planning");
+  const now = options.now || new Date().toISOString();
+
+  // Compose the lean dashboard snapshot — reuse its identity/current/journey/
+  // lifetime/quality blocks verbatim instead of re-deriving them here.
+  const snapshot = snapshotLib.buildSnapshot({
+    cwd,
+    home,
+    planningDir: planning,
+    qualiaHome: options.qualiaHome,
+    now,
+  });
+
+  const tracking = readJson(path.join(planning, "tracking.json"), {});
+  const journeyText = readText(path.join(planning, "JOURNEY.md"), "");
+  const journey = snapshotLib.parseJourneyMilestones(journeyText);
+  const closed = Array.isArray(tracking.milestones) ? tracking.milestones : [];
+  const currentNum = Number(tracking.milestone || snapshot.current.milestone || 1);
+  const lifetime = snapshot.lifetime;
+
+  const milestones = buildMilestones({ journey, closed, currentNum, planningDir: planning });
+  // Fill a current/future milestone's phase count from the roadmap when it has
+  // none of its own (closed summaries already carry phases_completed).
+  const roadmapPhases = roadmapPhaseCount(planning) || Number(tracking.total_phases || 0);
+  for (const m of milestones) {
+    if (m.status === "current" && !m.phases) m.phases = roadmapPhases;
+  }
+
+  const offroad = Array.isArray(tracking.offroad) ? tracking.offroad : [];
+  const offroadCount = Number(
+    (tracking.lifetime && tracking.lifetime.offroad_count) || offroad.length || 0
+  );
+
+  return {
+    schema_version: SCHEMA_VERSION,
+    generated_at: now,
+    source: "qualia-framework",
+    payload: "project-sync",
+    framework_version: snapshot.framework_version,
+    identifiers: snapshot.identifiers,
+    project: {
+      ...snapshot.project,
+      lifecycle: tracking.lifecycle || "build",
+      ...(tracking.launched_at ? { launched_at: tracking.launched_at } : {}),
+      ...(tracking.launch_source ? { launch_source: tracking.launch_source } : {}),
+    },
+    current: snapshot.current,
+    quality: snapshot.quality,
+    // Full milestone arc enriched with REQ-ID completion — the spine of ERP
+    // reconciliation. journey.total_milestones rides along for the denominator.
+    total_milestones: snapshot.journey.total_milestones,
+    milestones,
+    // Cumulative + current task accounting so the ERP can roll tasks up without
+    // replaying every report.
+    task_rollup: {
+      tasks_completed: lifetime.tasks_completed,
+      phases_completed: lifetime.phases_completed,
+      milestones_completed: lifetime.milestones_completed,
+      total_phases_all_milestones: lifetime.total_phases,
+      build_count: lifetime.build_count,
+      deploy_count: lifetime.deploy_count,
+      current_phase_gap_cycles: snapshot.current.gap_cycles,
+    },
+    // Accountability: off-milestone work the OWNER + ERP should see (mirrors the
+    // branch-guard main-push tally — drift is counted, not hidden).
+    accountability: {
+      offroad_count: offroadCount,
+      offroad: offroad.slice(-10),
+    },
+    // The PR/merge model the ERP must understand to map branch→main→deploy:
+    // feature branches integrate to main at /qualia-ship (trunk model); pushes
+    // to a protected branch are recorded for accountability via branch-guard's
+    // employee_main_push events (POST /api/v1/policy-events; the local journal
+    // lives in the install home, referenced not read here).
+    integration: {
+      model: "trunk",
+      integrates_at: "/qualia-ship",
+      protected_branches: ["main", "master"],
+      main_push_event_type: "employee_main_push",
+      main_push_events_path: "~/.claude/.main-push-events.json",
+      note:
+        "Feature branches integrate to main at /qualia-ship (then deploy). " +
+        "Direct pushes to a protected branch are allowed but recorded as " +
+        "employee_main_push policy events for per-employee accountability.",
+    },
+    timestamps: snapshot.timestamps,
+  };
+}
+
+function writeProjectSync(sync, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const planning = options.planningDir || path.join(cwd, ".planning");
+  const outDir = options.outDir || path.join(planning, "snapshots");
+  fs.mkdirSync(outDir, { recursive: true });
+  const stamp = sync.generated_at.replace(/[:.]/g, "-");
+  const file = path.join(outDir, `project-sync-${stamp}.json`);
+  fs.writeFileSync(file, `${JSON.stringify(sync, null, 2)}\n`);
+  return file;
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const args = { cwd: null };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") args.json = true;
+    else if (a === "--write") args.write = true;
+    else if (a === "--pretty") args.pretty = true;
+    else if (a === "--cwd") args.cwd = argv[++i];
+    else if (a.startsWith("--cwd=")) args.cwd = a.slice(6);
+    else if (a === "--now") args.now = argv[++i];
+    else if (a.startsWith("--now=")) args.now = a.slice(6);
+  }
+  return args;
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  const cwd = args.cwd || process.cwd();
+  const planning = path.join(cwd, ".planning");
+  if (!fs.existsSync(planning)) {
+    console.error("project-sync: no .planning/ found — run /qualia-new to start.");
+    return 2;
+  }
+  const sync = buildProjectSync({ cwd, now: args.now });
+  if (args.write) {
+    const file = writeProjectSync(sync, { cwd });
+    process.stdout.write(`${file}\n`);
+    return 0;
+  }
+  process.stdout.write(`${JSON.stringify(sync, null, args.pretty || args.json ? 2 : 0)}\n`);
+  return 0;
+}
+
+module.exports = {
+  buildProjectSync,
+  buildMilestones,
+  milestoneRequirements,
+  writeProjectSync,
+  SCHEMA_VERSION,
+};
+
+if (require.main === module) {
+  try {
+    process.exit(main(process.argv));
+  } catch (error) {
+    console.error(`project-sync failed: ${error.message}`);
+    process.exit(1);
+  }
+}

package/bin/recall.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+// recall.js — the read side of Qualia memory. Unified recall across the two
+// memory stores so an agent (or /qualia-recall) gets ONE answer, not two:
+//
+//   1. knowledge layer  — ~/.claude/knowledge/ (via knowledge.js, the canonical
+//                          loader; we delegate so new files stay discoverable)
+//   2. qualia-memory     — QUALIA_MEMORY_ROOT/wiki, the Obsidian LLM Wiki, the
+//                          team's curated cross-project lessons
+//
+// Symmetric counterpart to /qualia-learn (write). Zero deps — shells out to
+// knowledge.js and grep, same posture as state.js / memory-mcp/server.js.
+//
+// Usage:
+//   recall.js <query...>                 # human digest across both stores
+//   recall.js <query> --json             # machine output
+//   recall.js <query> --scope knowledge  # one store only (knowledge | vault | all)
+//   recall.js <query> --max 20           # cap hits per store (default 50)
+//
+// Exit: 0 = ran (even with zero hits), 2 = bad invocation.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const { resolveRole, loadDenyMatchers, isDenied } = require("./vault-access.js");
+
+// ─── Store resolution ───────────────────────────────────────────────────────
+// Mirror knowledge.js's home resolution so a temp QUALIA_HOME (tests) lines up.
+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");
+}
+const KNOWLEDGE_JS = path.join(__dirname, "knowledge.js");
+const VAULT_ROOT = process.env.QUALIA_MEMORY_ROOT || path.join(os.homedir(), "qualia-memory");
+const WIKI = path.join(VAULT_ROOT, "wiki");
+
+// Vault access control lives in vault-access.js (shared with the memory MCP) so
+// the OWNER_ONLY / CONDITIONAL rule has exactly one implementation.
+
+// ─── Knowledge layer (delegate to knowledge.js — single source of truth) ─────
+// knowledge.js prints `relpath:line: text` per hit, or a `(no matches…)` /
+// `(knowledge layer not initialized)` sentinel line. We parse the hit shape and
+// drop the sentinels.
+function searchKnowledge(query, max) {
+  const r = spawnSync(process.env.NODE || "node", [KNOWLEDGE_JS, "search", query], {
+    encoding: "utf8",
+    timeout: 10000,
+  });
+  if (r.status !== 0 && !r.stdout) return [];
+  const hits = [];
+  for (const line of (r.stdout || "").split("\n")) {
+    const m = line.match(/^(.+?):(\d+):\s?(.*)$/);
+    if (!m) continue; // sentinel or blank
+    hits.push({ store: "knowledge", file: m[1], line: Number(m[2]), snippet: m[3].trim() });
+    if (hits.length >= max) break;
+  }
+  return hits;
+}
+
+// ─── Vault (grep over wiki — mirrors mcp/memory-mcp/server.js) ───────────────
+function searchVault(query, max, role) {
+  if (!fs.existsSync(WIKI)) return [];
+  const r = spawnSync(
+    "grep",
+    ["-rniF", "--include=*.md", "--include=*.txt", "--include=*.canvas", "--include=*.base", "--", query, WIKI],
+    { encoding: "utf8", timeout: 10000 }
+  );
+  // grep exit 1 = no matches (not an error); >1 = real error.
+  if (r.status !== 0 && r.status !== 1) return [];
+  // Non-OWNER roles get OWNER_ONLY / CONDITIONAL vault paths filtered out.
+  const matchers = role === "OWNER" ? null : loadDenyMatchers(WIKI);
+  const hits = [];
+  for (const line of (r.stdout || "").split("\n")) {
+    if (!line) continue;
+    const m = line.match(/^(.+?):(\d+):(.*)$/);
+    if (!m) continue;
+    const rel = path.relative(WIKI, m[1]) || path.basename(m[1]);
+    // Compare against VAULT-ROOT-relative path, the manifest's frame of reference.
+    if (matchers && isDenied(path.join("wiki", rel).split(path.sep).join("/"), matchers)) continue;
+    hits.push({ store: "vault", file: rel, line: Number(m[2]), snippet: m[3].trim() });
+    if (hits.length >= max) break;
+  }
+  return hits;
+}
+
+// ─── Rank: group by file, busiest file first, lines in order within a file ───
+function rankByFile(hits) {
+  const byFile = new Map();
+  for (const h of hits) {
+    if (!byFile.has(h.file)) byFile.set(h.file, []);
+    byFile.get(h.file).push(h);
+  }
+  return [...byFile.entries()]
+    .map(([file, hs]) => ({ file, count: hs.length, hits: hs.sort((a, b) => a.line - b.line) }))
+    .sort((a, b) => b.count - a.count);
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const opts = { json: false, scope: "all", max: 50, terms: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") opts.json = true;
+    else if (a === "--scope") opts.scope = (argv[++i] || "").toLowerCase();
+    else if (a === "--max") opts.max = Math.max(1, parseInt(argv[++i], 10) || 50);
+    else if (a === "-h" || a === "--help") opts.help = true;
+    else opts.terms.push(a);
+  }
+  return opts;
+}
+
+function usage() {
+  process.stderr.write(
+    "recall.js — unified recall across the knowledge layer + qualia-memory vault\n\n" +
+      "  recall.js <query...> [--scope all|knowledge|vault] [--json] [--max N]\n"
+  );
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    usage();
+    process.exit(0);
+  }
+  const query = opts.terms.join(" ").trim();
+  if (!query) {
+    usage();
+    process.exit(2);
+  }
+  if (!["all", "knowledge", "vault"].includes(opts.scope)) {
+    process.stderr.write(`recall.js: invalid --scope '${opts.scope}' (use all|knowledge|vault)\n`);
+    process.exit(2);
+  }
+
+  const role = resolveRole(qualiaHome());
+  const knowledge = opts.scope === "vault" ? [] : searchKnowledge(query, opts.max);
+  const vault = opts.scope === "knowledge" ? [] : searchVault(query, opts.max, role);
+  const total = knowledge.length + vault.length;
+
+  if (opts.json) {
+    console.log(
+      JSON.stringify(
+        { query, scope: opts.scope, role, total, knowledge: rankByFile(knowledge), vault: rankByFile(vault) },
+        null,
+        2
+      )
+    );
+    process.exit(0);
+  }
+
+  // Human digest.
+  console.log(`recall "${query}" — ${total} hit${total === 1 ? "" : "s"} (knowledge: ${knowledge.length}, vault: ${vault.length})${role !== "OWNER" ? ` · role ${role}: OWNER-only vault paths hidden` : ""}`);
+  const section = (label, hits) => {
+    if (!hits.length) return;
+    console.log(`\n${label}`);
+    for (const grp of rankByFile(hits)) {
+      console.log(`  ${grp.file} (${grp.count})`);
+      for (const h of grp.hits.slice(0, 5)) {
+        const snip = h.snippet.length > 120 ? h.snippet.slice(0, 117) + "…" : h.snippet;
+        console.log(`    L${h.line}: ${snip}`);
+      }
+    }
+  };
+  section("Knowledge layer (~/.claude/knowledge/)", knowledge);
+  section("Vault (qualia-memory/wiki/)", vault);
+  if (total === 0) console.log("\n(no matches — try a broader term, or check the vault/knowledge layer exists)");
+  process.exit(0);
+}
+
+main();