qualia-framework 6.14.0 → 7.0.0

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,18 +10,30 @@ 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)" },
   { file: "agent-status.js", label: "agent-status.js (per-task build status + wave fan-in barrier)" },
   { file: "analyze-gate.js", label: "analyze-gate.js (cross-artifact scope↔plan coverage gate)" },
+  { file: "verify-panel.js", label: "verify-panel.js (verifier panel + skeptic majority-survives aggregator)" },
+  { file: "wave-plan.js", label: "wave-plan.js (dependency-derived, concurrency-capped build schedule)" },
+  { file: "eval-runner.js", label: "eval-runner.js (layered assertion runner for AI-feature eval suites)" },
+  { file: "branch-hygiene.js", label: "branch-hygiene.js (clock-out sweep — stranded branches + stale PRs)" },
+  { file: "last-report.js", label: "last-report.js (router surfacing — newest session-report digest at session start)" },
   { 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)" },
   { file: "project-snapshot.js", label: "project-snapshot.js (ERP/admin project progress snapshot)" },
+  { file: "project-sync.js", label: "project-sync.js (Framework -> ERP full project-sync reconciliation payload)" },
   { file: "trust-score.js", label: "trust-score.js (harness health scoring)" },
   { 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)" },

package/bin/state.js

@@ -607,9 +607,28 @@ function cmdTransitionIncrement(opts, target) {
       const c = parseInt(opts.tasks_done) || 0;
       if (c > 0) t.lifetime.tasks_completed += c;
     }
+    // Scope tagging (anti-drift): /qualia-feature + /qualia-fix declare whether
+    // the work served the active milestone (--scope in --ref CORE-03) or was
+    // off-road (--scope off). Off-road work is COUNTED + ledgered so it can't
+    // drift invisibly — the OWNER + ERP see the tally, mirroring branch-guard.
+    const scope = String(opts.scope || "").toLowerCase();
+    if (scope === "off" || scope === "in") {
+      if (typeof t.lifetime.offroad_count !== "number") t.lifetime.offroad_count = 0;
+      if (scope === "off") {
+        t.lifetime.offroad_count += 1;
+        if (!Array.isArray(t.offroad)) t.offroad = [];
+        t.offroad.push({
+          at: new Date().toISOString(),
+          milestone: parseInt(t.milestone, 10) || null,
+          ref: opts.ref || null,
+          note: opts.notes || null,
+        });
+        if (t.offroad.length > 50) t.offroad = t.offroad.slice(-50); // keep recent
+      }
+    }
     writeTracking(t);
     regenerateViews(opts.notes || "Activity logged");
-    return output({ ok: true, action: target, layout: "increments" });
+    return output({ ok: true, action: target, layout: "increments", scope: scope || undefined, offroad_count: t.lifetime.offroad_count });
   }
 
   // Resolve the target increment: explicit --id, else --phase N (back-compat
@@ -759,6 +778,31 @@ function normalizeMilestoneName(name) {
   return String(name == null ? "" : name).trim().toLowerCase();
 }
 
+// Parse the REQUIREMENTS.md traceability table for one milestone's REQ-IDs and
+// their status. Rows look like: `| CORE-01 | M2: Name | Phase 3 | Complete |`.
+// Returns { tracked: bool, total, incomplete: [{id, status}] }. tracked=false
+// when REQUIREMENTS.md is absent or has no rows for this milestone (→ gate
+// skips, like analyze-gate's no-scope-file: can't enforce what isn't declared).
+function readMilestoneRequirements(milestoneNum) {
+  let md;
+  try { md = fs.readFileSync(path.join(PLANNING, "REQUIREMENTS.md"), "utf8"); }
+  catch { return { tracked: false, total: 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");
+  return { tracked: rows.length > 0, total: rows.length, incomplete };
+}
+
 function readState() {
   try {
     return fs.readFileSync(STATE_FILE, "utf8");
@@ -1275,6 +1319,28 @@ function applyNoteOrActivity(target, s, t, opts) {
       t.lifetime.tasks_completed += count;
     }
   }
+  // Scope tagging (anti-drift): /qualia-feature + /qualia-fix declare whether the
+  // work served the active milestone (--scope in --ref CORE-03) or was off-road
+  // (--scope off). Off-road work is COUNTED + ledgered so it can't drift
+  // invisibly — the OWNER + ERP see the tally, mirroring branch-guard.
+  const scope = String(opts.scope || "").toLowerCase();
+  let offroadCount;
+  if (scope === "in" || scope === "off") {
+    ensureLifetime(t);
+    if (typeof t.lifetime.offroad_count !== "number") t.lifetime.offroad_count = 0;
+    if (scope === "off") {
+      t.lifetime.offroad_count += 1;
+      if (!Array.isArray(t.offroad)) t.offroad = [];
+      t.offroad.push({
+        at: new Date().toISOString(),
+        milestone: parseInt(t.milestone, 10) || null,
+        ref: opts.ref || null,
+        note: opts.notes || null,
+      });
+      if (t.offroad.length > 50) t.offroad = t.offroad.slice(-50);
+    }
+    offroadCount = t.lifetime.offroad_count;
+  }
   t.last_updated = new Date().toISOString();
   writeTracking(t);
   s.last_activity = opts.notes || "Activity logged";
@@ -1284,6 +1350,8 @@ function applyNoteOrActivity(target, s, t, opts) {
     phase: s.phase,
     status: s.status,
     action: target,
+    scope: scope || undefined,
+    offroad_count: offroadCount,
   };
 }
 
@@ -2314,6 +2382,27 @@ function cmdValidatePlan(opts) {
 // recently closed milestone so re-running close-milestone (e.g., after a
 // hiccup) does NOT double-count. To re-close a milestone deliberately, pass
 // --force.
+// Report REQ-ID completion for a milestone (defaults to the current one). The
+// same check close-milestone gates on — exposed so /qualia-milestone can show
+// coverage before closing, and so it's directly testable. Exit 0 = all complete
+// (or untracked), 1 = incomplete requirements remain.
+function cmdReqsCheck(opts) {
+  const t = readTracking();
+  const milestone = opts.milestone != null ? parseInt(opts.milestone, 10) : (t ? parseInt(t.milestone, 10) || 1 : 1);
+  const reqs = readMilestoneRequirements(milestone);
+  const ok = !reqs.tracked || reqs.incomplete.length === 0;
+  output({
+    ok,
+    action: "reqs-check",
+    milestone,
+    tracked: reqs.tracked,
+    total: reqs.total,
+    complete: reqs.total - reqs.incomplete.length,
+    incomplete: reqs.incomplete,
+  });
+  process.exitCode = ok ? 0 : 1;
+}
+
 function cmdCloseMilestone(opts) {
   const beforeStateRaw = readState();
   const beforeTrackingRaw = readTrackingRaw();
@@ -2323,6 +2412,7 @@ function cmdCloseMilestone(opts) {
     return output(fail("NO_PROJECT", "No .planning/ found."));
   }
   ensureLifetime(t);
+  const closeWarnings = [];
 
   // parseInt — legacy tracking.json files carry milestone as a string ("9"),
   // which would corrupt `closedMilestone + 1` ("91") and break num dedupe.
@@ -2367,6 +2457,23 @@ function cmdCloseMilestone(opts) {
         )
       );
     }
+    // REQ-ID coverage gate: a milestone isn't "done" just because its phases
+    // verified — its agreed requirements must actually be Complete. Stops
+    // "finishing a milestone with scope left open". strict blocks; standard warns.
+    const reqs = readMilestoneRequirements(closedMilestone);
+    if (reqs.tracked && reqs.incomplete.length > 0) {
+      const profile = resolveProfile(s, t);
+      const list = reqs.incomplete.map((r) => `${r.id}:${r.status || "Pending"}`).join(", ");
+      if (profile === "strict") {
+        return output(
+          fail(
+            "MILESTONE_REQS_INCOMPLETE",
+            `Milestone ${closedMilestone} has ${reqs.incomplete.length}/${reqs.total} requirement(s) not Complete in REQUIREMENTS.md: ${list}. Finish or explicitly defer them (move to Out of Scope), or use --force.`
+          )
+        );
+      }
+      closeWarnings.push(`${reqs.incomplete.length}/${reqs.total} requirement(s) not Complete: ${list} (standard profile — proceeding; record why in the report).`);
+    }
   }
 
   // ─── Append a summary to milestones[] so the ERP can render the tree ──
@@ -2485,6 +2592,7 @@ function cmdCloseMilestone(opts) {
   } else {
     result.ledger_error = ledger.error;
   }
+  if (closeWarnings.length) result.warnings = closeWarnings;
   output(result);
 }
 
@@ -2921,6 +3029,9 @@ try {
     case "close-milestone":
       cmdCloseMilestone(opts);
       break;
+    case "reqs-check":
+      cmdReqsCheck(opts);
+      break;
     case "backfill-lifetime":
       cmdBackfillLifetime(opts);
       break;

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 };