qualia-framework 6.22.0 → 7.0.0

package/bin/host-adapters.js

@@ -27,6 +27,8 @@ const HOSTS = {
     configFile: "settings.json",
     agentDir: "agents",
     agentExt: ".md",
+    agentCli: "claude", // the CLI that runs a non-interactive turn for this host
+    agentExecPrefix: ["-p"], // `claude -p "<prompt>"`
     naming: {}, // Claude is the canonical voice — no swaps.
   },
   codex: {
@@ -36,11 +38,18 @@ const HOSTS = {
     configFile: "config.toml",
     agentDir: "agents",
     agentExt: ".toml",
-    // Canonical source speaks "Claude Code"; Codex artifacts speak "Codex".
+    agentCli: "codex",
+    agentExecPrefix: ["exec"], // `codex exec "<prompt>"`
     naming: { "Claude Code": "Codex", "Claude's": "Codex's" },
   },
 };
 
+// Which host owns this install home? (".codex" → codex, else claude.) The one
+// place that maps a home dir back to a host name — callers ask, never re-derive.
+function hostForHome(home) {
+  return path.basename(home) === ".codex" ? "codex" : "claude";
+}
+
 function adapter(name) {
   const host = HOSTS[name];
   if (!host) throw new Error(`Unknown Qualia host adapter: ${name}`);
@@ -50,6 +59,8 @@ function adapter(name) {
     instructionPath: path.join(home, host.instructionFile),
     configPath: path.join(home, host.configFile),
     agentPath: path.join(home, host.agentDir),
+    // Full argv (minus the binary) to run one non-interactive turn on this host.
+    agentExec: (prompt) => [...host.agentExecPrefix, prompt],
     tokens: {
       QUALIA_HOME: home,
       QUALIA_BIN: `${home}/bin`,
@@ -118,6 +129,7 @@ function compileInstructions(canonical, hostName) {
 module.exports = {
   HOSTS,
   adapter,
+  hostForHome,
   applyNaming,
   applyPaths,
   renderText,

package/bin/install.js

@@ -1442,6 +1442,29 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     ok("MCP: next-devtools (runtime error visibility for Next.js projects)");
   }
 
+  // ─── qualia-memory MCP ──────────────────────────────────
+  // Read-only access to the Karpathy LLM Wiki at ~/qualia-memory/. Three tools:
+  // memory.search, memory.read, memory.list. Zero deps — see docs/MEMORY-MCP.md.
+  // Registered globally so every Claude Code session has it without per-project
+  // .mcp.json. Users override the vault path via QUALIA_MEMORY_ROOT.
+  const memoryServerPath = path.join(FRAMEWORK_DIR, "mcp", "memory-mcp", "server.js");
+  if (!settings.mcpServers["qualia-memory"]) {
+    settings.mcpServers["qualia-memory"] = {
+      command: "node",
+      args: [memoryServerPath],
+      env: {
+        QUALIA_MEMORY_ROOT: path.join(require("os").homedir(), "qualia-memory"),
+      },
+      disabled: false,
+    };
+    ok("MCP: qualia-memory (read-only wiki at ~/qualia-memory/)");
+  } else {
+    // Always refresh the args path — the framework may have moved (npm i -g
+    // location, dev checkout vs published install). Env stays user-controlled.
+    settings.mcpServers["qualia-memory"].command = "node";
+    settings.mcpServers["qualia-memory"].args = [memoryServerPath];
+  }
+
   // v5.0: backup existing settings.json before overwrite. The merge logic above
   // preserves user fields, but a partial-write or merger bug could destroy MCP
   // configs / custom permissions. Atomic write (tmp + rename) avoids partial

package/bin/knowledge-flush.js

@@ -110,8 +110,11 @@ function dailyLogHasRecentEntries(windowDays) {
 }
 
 // ── Preflight ────────────────────────────────────────────
-const IS_CODEX_INSTALL = path.basename(QUALIA_HOME) === ".codex";
-const agentCli = IS_CODEX_INSTALL ? "codex" : "claude";
+// Per-host facts (which CLI, how to invoke it) come from the adapter — the one
+// place runtime differences live. See bin/host-adapters.js.
+const { adapter, hostForHome } = require("./host-adapters.js");
+const host = adapter(hostForHome(QUALIA_HOME));
+const agentCli = host.agentCli;
 const agentBin = which(agentCli);
 if (!agentBin) {
   logEvent({ event: "skipped", reason: `${agentCli}-cli-not-on-path` });
@@ -143,7 +146,7 @@ const prompt = [
   "Finish with one line starting exactly: ⬢ Flushed daily-log",
 ].join("\n");
 
-const cliArgs = IS_CODEX_INSTALL ? ["exec", prompt] : ["-p", prompt];
+const cliArgs = host.agentExec(prompt);
 const result = spawnSync(agentBin, cliArgs, {
   encoding: "utf8",
   timeout: 5 * 60 * 1000, // 5 min hard cap — flush should never take this long

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();

package/bin/repo-map.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// repo-map.js — a cheap, deterministic symbol map of a codebase. The zero-dep
+// answer to Aider's tree-sitter repo-map (R18): give /qualia-map (and any agent
+// onboarding to a brownfield repo) the STRUCTURE — every file's top-level
+// symbols — without reading whole files. Grounds the scan; cuts token cost.
+//
+// Not a parser: language-aware regexes over top-level (column-0) declarations.
+// Good enough to answer "what's in this repo and where" — exports, functions,
+// classes, types — ranked by symbol density so the busiest files surface first.
+//
+// Usage:
+//   repo-map.js [dir]                 # human tree (default cwd)
+//   repo-map.js [dir] --json          # machine output
+//   repo-map.js [dir] --max-files N   # cap files shown (default 60)
+//
+// Exit: 0 = ran, 2 = bad invocation / dir missing. Zero deps.
+
+const fs = require("fs");
+const path = require("path");
+
+const IGNORE_DIRS = new Set([
+  ".git", "node_modules", "dist", "build", ".next", "out", "coverage", "vendor",
+  ".venv", "venv", "__pycache__", ".turbo", ".cache", "target", "bin/obj",
+  ".pytest_cache", ".mypy_cache", ".gradle", "Pods", ".terraform",
+]);
+
+// Per-extension symbol extractors. Each regex captures the symbol name in a
+// named-or-numbered group; `kind` labels it. Anchored to line start (top-level).
+const EXTRACTORS = {
+  js: jsLike, jsx: jsLike, ts: jsLike, tsx: jsLike, mjs: jsLike, cjs: jsLike,
+  py: py, go: go, rs: rs, rb: rb, java: java, php: php,
+};
+
+function scanLines(content, rules) {
+  const out = [];
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const { re, kind } of rules) {
+      const m = line.match(re);
+      if (m) {
+        out.push({ kind, name: m[m.length - 1], line: i + 1 });
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+function jsLike(c) {
+  return scanLines(c, [
+    { re: /^export\s+(?:default\s+)?(?:async\s+)?function\s+(\w+)/, kind: "fn" },
+    { re: /^export\s+(?:default\s+)?class\s+(\w+)/, kind: "class" },
+    { re: /^export\s+(?:abstract\s+)?(?:interface|type|enum)\s+(\w+)/, kind: "type" },
+    { re: /^export\s+(?:const|let|var)\s+(\w+)/, kind: "const" },
+    { re: /^(?:async\s+)?function\s+(\w+)/, kind: "fn" },
+    { re: /^class\s+(\w+)/, kind: "class" },
+    { re: /^(?:export\s+)?default\s+class\s+(\w+)/, kind: "class" },
+  ]);
+}
+function py(c) {
+  return scanLines(c, [
+    { re: /^(?:async\s+)?def\s+(\w+)/, kind: "fn" },
+    { re: /^class\s+(\w+)/, kind: "class" },
+  ]);
+}
+function go(c) {
+  return scanLines(c, [
+    { re: /^func\s+\([^)]*\)\s+(\w+)/, kind: "method" },
+    { re: /^func\s+(\w+)/, kind: "fn" },
+    { re: /^type\s+(\w+)/, kind: "type" },
+  ]);
+}
+function rs(c) {
+  return scanLines(c, [
+    { re: /^(?:pub\s+)?(?:async\s+)?fn\s+(\w+)/, kind: "fn" },
+    { re: /^(?:pub\s+)?struct\s+(\w+)/, kind: "struct" },
+    { re: /^(?:pub\s+)?enum\s+(\w+)/, kind: "enum" },
+    { re: /^(?:pub\s+)?trait\s+(\w+)/, kind: "trait" },
+  ]);
+}
+function rb(c) {
+  return scanLines(c, [
+    { re: /^\s*def\s+([\w.?!]+)/, kind: "fn" },
+    { re: /^\s*class\s+(\w+)/, kind: "class" },
+    { re: /^\s*module\s+(\w+)/, kind: "module" },
+  ]);
+}
+function java(c) {
+  return scanLines(c, [
+    { re: /^\s*(?:public|private|protected)?\s*(?:abstract\s+)?class\s+(\w+)/, kind: "class" },
+    { re: /^\s*(?:public|private|protected)\s+(?:static\s+)?(?:interface|enum)\s+(\w+)/, kind: "type" },
+  ]);
+}
+function php(c) {
+  return scanLines(c, [
+    { re: /^\s*(?:abstract\s+)?class\s+(\w+)/, kind: "class" },
+    { re: /^\s*function\s+(\w+)/, kind: "fn" },
+    { re: /^\s*(?:interface|trait)\s+(\w+)/, kind: "type" },
+  ]);
+}
+
+function walk(root, max) {
+  const results = [];
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith(".") && e.name !== ".") {
+        if (e.isDirectory() && IGNORE_DIRS.has(e.name)) continue;
+      }
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (IGNORE_DIRS.has(e.name)) continue;
+        stack.push(full);
+      } else if (e.isFile()) {
+        const ext = path.extname(e.name).slice(1).toLowerCase();
+        const extract = EXTRACTORS[ext];
+        if (!extract) continue;
+        let content;
+        try {
+          content = fs.readFileSync(full, "utf8");
+        } catch {
+          continue;
+        }
+        if (content.length > 2 * 1024 * 1024) continue; // skip huge/minified
+        const symbols = extract(content);
+        if (symbols.length) results.push({ file: path.relative(root, full), symbols });
+      }
+    }
+    if (results.length > 5000) break; // hard backstop
+  }
+  // Busiest files first — the structural backbone surfaces at the top.
+  results.sort((a, b) => b.symbols.length - a.symbols.length || a.file.localeCompare(b.file));
+  void max;
+  return results;
+}
+
+function parseArgs(argv) {
+  const opts = { dir: ".", json: false, maxFiles: 60 };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") opts.json = true;
+    else if (a === "--max-files") opts.maxFiles = Math.max(1, parseInt(argv[++i], 10) || 60);
+    else if (a === "-h" || a === "--help") opts.help = true;
+    else opts.dir = a;
+  }
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    process.stdout.write("repo-map.js [dir] [--json] [--max-files N]\n");
+    process.exit(0);
+  }
+  const root = path.resolve(opts.dir);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    process.stderr.write(`repo-map.js: not a directory: ${opts.dir}\n`);
+    process.exit(2);
+  }
+  const files = walk(root, opts.maxFiles);
+  const totalSymbols = files.reduce((n, f) => n + f.symbols.length, 0);
+
+  if (opts.json) {
+    console.log(JSON.stringify({ root, total_files: files.length, total_symbols: totalSymbols, files: files.slice(0, opts.maxFiles) }, null, 2));
+    process.exit(0);
+  }
+
+  console.log(`repo-map: ${files.length} source file${files.length === 1 ? "" : "s"}, ${totalSymbols} top-level symbols`);
+  if (files.length > opts.maxFiles) console.log(`(showing the ${opts.maxFiles} densest; pass --max-files to widen)`);
+  for (const f of files.slice(0, opts.maxFiles)) {
+    console.log(`\n${f.file}  (${f.symbols.length})`);
+    for (const s of f.symbols.slice(0, 24)) {
+      console.log(`  ${s.kind.padEnd(6)} ${s.name}  :${s.line}`);
+    }
+    if (f.symbols.length > 24) console.log(`  … +${f.symbols.length - 24} more`);
+  }
+  process.exit(0);
+}
+
+main();

package/bin/runtime-manifest.js

@@ -10,6 +10,11 @@ const RUNTIME_BIN_SCRIPTS = [
   { file: "statusline.js", label: "statusline.js (status bar renderer)" },
   { file: "knowledge.js", label: "knowledge.js (memory-layer loader)" },
   { file: "knowledge-flush.js", label: "knowledge-flush.js (cron-runnable flush)" },
+  { file: "recall.js", label: "recall.js (read-side memory recall — knowledge layer + role-filtered vault)" },
+  { file: "vault-access.js", label: "vault-access.js (shared vault access-control — honors wiki/_meta/access.md)" },
+  { file: "repo-map.js", label: "repo-map.js (zero-dep symbol map for brownfield onboarding — /qualia-map)" },
+  { file: "design-tokens.js", label: "design-tokens.js (per-client CSS-variable token registry — R10)" },
+  { file: "batch-plan.js", label: "batch-plan.js (file-disjoint batch split for /qualia-build --batch — R20)" },
   { file: "state-ledger.js", label: "state-ledger.js (hash-chained state event ledger)" },
   { file: "plan-contract.js", label: "plan-contract.js (plan JSON validator)" },
   { file: "contract-runner.js", label: "contract-runner.js (contract evidence runner)" },
@@ -23,6 +28,7 @@ const RUNTIME_BIN_SCRIPTS = [
   { file: "agent-runs.js", label: "agent-runs.js (agent telemetry writer)" },
   { file: "slop-detect.mjs", label: "slop-detect.mjs (anti-pattern scanner — runs pre-commit on frontend builds)" },
   { file: "erp-retry.js", label: "erp-retry.js (ERP report retry queue — drained by session-start hook and erp-flush CLI)" },
+  { file: "erp-event.js", label: "erp-event.js (signed lifecycle-event emitter → ERP /api/v1/events, R14 client)" },
   { file: "work-packet.js", label: "work-packet.js (ERP mission/work packet pull + local reader)" },
   { file: "report-payload.js", label: "report-payload.js (Framework -> ERP report payload builder)" },
   { file: "auto-report.js", label: "auto-report.js (B1 ship-time auto-report)" },

package/bin/vault-access.js

@@ -0,0 +1,82 @@
+// vault-access.js — the SINGLE source for qualia-memory vault access control.
+//
+// The vault carries an access manifest at wiki/_meta/access.md naming OWNER_ONLY
+// and CONDITIONAL paths. Every deterministic reader of the vault (recall.js, the
+// memory MCP server) enforces it THROUGH THIS MODULE so the security rule has one
+// implementation that can't drift between callers. Fail-closed: an unknown role
+// is treated as non-OWNER (restricted). See rules/access.md.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+// Resolve the caller's role. QUALIA_ROLE env wins (tests / overrides); else read
+// `role` from <home>/.qualia-config.json; else RESTRICTED (fail-closed).
+function resolveRole(home) {
+  if (process.env.QUALIA_ROLE) return process.env.QUALIA_ROLE.toUpperCase();
+  const h = home || process.env.QUALIA_HOME || path.join(os.homedir(), ".claude");
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(h, ".qualia-config.json"), "utf8"));
+    if (cfg && typeof cfg.role === "string") return cfg.role.toUpperCase();
+  } catch {}
+  return "RESTRICTED";
+}
+
+// Parse the OWNER_ONLY + CONDITIONAL path tokens from wiki/_meta/access.md into
+// matchers over VAULT-ROOT-relative paths (e.g. "wiki/_meta/access.md").
+// Returns null when no manifest exists (caller decides; wiki is curated-by-design).
+function loadDenyMatchers(wikiDir) {
+  let text;
+  try {
+    text = fs.readFileSync(path.join(wikiDir, "_meta", "access.md"), "utf8");
+  } catch {
+    return null;
+  }
+  const matchers = [];
+  for (const section of ["## OWNER_ONLY", "## CONDITIONAL"]) {
+    const start = text.indexOf(section);
+    if (start === -1) continue;
+    const rest = text.slice(start + section.length);
+    const end = rest.indexOf("\n## ");
+    const body = end === -1 ? rest : rest.slice(0, end);
+    for (const m of body.matchAll(/`([^`]+)`/g)) {
+      const tok = m[1].trim();
+      if (!tok.includes("/") && !tok.includes("*")) continue; // skip non-path backticks
+      matchers.push(tok);
+    }
+  }
+  return matchers;
+}
+
+// Does a VAULT-ROOT-relative path match any deny pattern?
+//   "dir/"     → prefix match    "dir/*.md" → prefix + extension
+//   "a/*/b"    → glob → regex    bare       → exact or prefix
+function isDenied(vaultRelPath, matchers) {
+  for (const tok of matchers) {
+    if (tok.endsWith("/*.md")) {
+      const dir = tok.slice(0, -5);
+      if (vaultRelPath.startsWith(dir + "/") && vaultRelPath.endsWith(".md")) return true;
+    } else if (tok.endsWith("/")) {
+      if (vaultRelPath.startsWith(tok)) return true;
+    } else if (tok.includes("*")) {
+      const re = new RegExp("^" + tok.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*") + "$");
+      if (re.test(vaultRelPath)) return true;
+    } else if (vaultRelPath === tok || vaultRelPath.startsWith(tok + "/")) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// Convenience for callers that work in WIKI-relative paths (recall, memory-mcp).
+// OWNER sees everything; non-OWNER is denied OWNER_ONLY/CONDITIONAL wiki paths.
+// Unknown manifest → allow (wiki is curated; sensitive stores live outside wiki/).
+function isWikiPathAllowed(wikiRelPath, role, wikiDir) {
+  if (role === "OWNER") return true;
+  const matchers = loadDenyMatchers(wikiDir);
+  if (!matchers) return true;
+  const vaultRel = path.join("wiki", wikiRelPath).split(path.sep).join("/");
+  return !isDenied(vaultRel, matchers);
+}
+
+module.exports = { resolveRole, loadDenyMatchers, isDenied, isWikiPathAllowed };

package/docs/erp-contract.md

@@ -77,6 +77,41 @@ many times each employee attempted to use proxy approval.
 ```
 Store by `(type, actor_code)` the same way so Fawzi sees a per-employee main-push tally. `client_report_id` is `QS-MAINPUSH-<actor_code>-<count>` and each post carries an idempotency key.
 
+### POST /api/v1/events (R14 — unified signed event log)
+
+The single endpoint for ALL CLI→ERP events: lifecycle/run events
+(`session_started`, `phase_planned`, `build_wave_started`, `verify_pass`,
+`verify_fail`, …) and, going forward, the policy events above. Emitted by
+`bin/erp-event.js` and queued through `erp-retry.js`.
+
+**Headers (Standard-Webhooks style):**
+```
+Authorization: Bearer <api-key>
+Content-Type: application/json
+Qualia-Event-Id:        <unique id — also the idempotency key>
+Qualia-Event-Timestamp: <unix seconds or ISO 8601>
+Qualia-Signature:       <base64 HMAC-SHA256 of `${id}.${timestamp}.${rawBody}`, keyed by the api-key; omit for unsigned>
+```
+
+**Body (the `FrameworkEvent`):**
+```json
+{
+  "action": "verify_pass",
+  "actor": { "code": "QS-FAWZI-11", "name": "Fawzi", "role": "OWNER" },
+  "targets": [{ "type": "project", "ref": "acme-portal" }],
+  "context": {},
+  "metadata": {},
+  "occurred_at": "2026-06-22T10:00:00.000Z",
+  "erp_project_id": "7b5d3b4e-…"
+}
+```
+
+The HMAC is keyed by the caller's `qlt_` token (the ERP holds only its hash but
+sees the plaintext Bearer per request), so body integrity + replay are verified
+with no extra secret. Server stores to an append-only `framework_events` table,
+idempotent on `Qualia-Event-Id`; unsigned posts are accepted but recorded
+`signature_valid=false`. Accepts `reports:write` or `events:write` scope.
+
 ### POST /api/v1/reports
 
 Upload a session report.