qualia-framework 6.14.0 → 7.0.0

package/bin/branch-hygiene.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// branch-hygiene.js — the clock-out safety net for trunk integration.
+//
+// WHY: /qualia-ship integrates feature→main on every successful deploy, so the
+// normal path leaves nothing open. But work that was BUILT and never SHIPPED
+// strands on a local branch ahead of main, and the occasional review PR can
+// linger. This surfaces both at /qualia-report so nothing rots silently.
+//
+// Detects:
+//   - local branches with commits ahead of main that aren't merged (stranded work)
+//   - open PRs (best-effort via `gh`; skipped silently when gh is absent/unauth)
+//
+// Read-only. Never blocks (report never blocks) — exit 0 = clean,
+// 1 = stranded branches and/or stale PRs found, 2 = not a git repo.
+// Zero npm dependencies.
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+
+function git(args, cwd) {
+  const r = spawnSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  return { ok: r.status === 0, out: (r.stdout || "").trim(), err: (r.stderr || "").trim() };
+}
+
+function mainBranch(cwd) {
+  // Prefer an existing local main, else master, else the remote HEAD target.
+  for (const b of ["main", "master"]) {
+    if (git(["rev-parse", "--verify", "--quiet", b], cwd).ok) return b;
+  }
+  const head = git(["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"], cwd);
+  if (head.ok && head.out) return head.out.replace(/^origin\//, "");
+  return "main";
+}
+
+function strandedBranches(cwd, base) {
+  const heads = git(["for-each-ref", "--format=%(refname:short)", "refs/heads/"], cwd);
+  if (!heads.ok) return [];
+  const out = [];
+  for (const b of heads.out.split(/\r?\n/).filter(Boolean)) {
+    if (b === base) continue;
+    // commits on b not in base — unmerged work.
+    const count = git(["rev-list", "--count", `${base}..${b}`], cwd);
+    const ahead = count.ok ? Number(count.out) : 0;
+    if (ahead > 0) {
+      const last = git(["log", "-1", "--format=%cI", b], cwd);
+      out.push({ branch: b, ahead, last_commit: last.ok ? last.out : null });
+    }
+  }
+  return out.sort((a, b) => b.ahead - a.ahead);
+}
+
+// Best-effort open-PR list via gh. Absent/unauth/non-GitHub → [] (never an error).
+function openPRs(cwd, staleDays, nowIso) {
+  const r = spawnSync("gh", ["pr", "list", "--state", "open", "--json", "number,title,headRefName,createdAt", "--limit", "100"],
+    { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  if (r.status !== 0 || !r.stdout) return [];
+  let prs;
+  try { prs = JSON.parse(r.stdout); } catch { return []; }
+  const now = nowIso ? Date.parse(nowIso) : null;
+  return prs.map((p) => {
+    let ageDays = null;
+    if (now != null && p.createdAt) ageDays = Math.floor((now - Date.parse(p.createdAt)) / 86400000);
+    return { number: p.number, title: p.title, branch: p.headRefName, age_days: ageDays, stale: ageDays != null && ageDays >= staleDays };
+  });
+}
+
+function analyze(cwd, opts = {}) {
+  const root = path.resolve(cwd || process.cwd());
+  if (!git(["rev-parse", "--is-inside-work-tree"], root).ok) {
+    return { ok: false, error: "NOT_A_GIT_REPO" };
+  }
+  const base = mainBranch(root);
+  const stranded = strandedBranches(root, base);
+  const prs = openPRs(root, opts.staleDays || 7, opts.now);
+  const stalePrs = prs.filter((p) => p.stale);
+  return {
+    ok: stranded.length === 0 && stalePrs.length === 0,
+    base,
+    stranded,
+    open_prs: prs,
+    stale_prs: stalePrs,
+  };
+}
+
+// ── 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 === "--stale-days") args.staleDays = Number(argv[++i]);
+    else if (a.startsWith("--stale-days=")) args.staleDays = Number(a.slice(13));
+    else if (a === "--now") args.now = argv[++i]; // ISO; tests inject determinism
+    else if (a.startsWith("--now=")) args.now = a.slice(6);
+  }
+  return args;
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  const result = analyze(args.cwd, { staleDays: args.staleDays, now: args.now });
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return result.ok ? 0 : (result.error ? 2 : 1);
+  }
+
+  if (result.error === "NOT_A_GIT_REPO") {
+    console.error("branch-hygiene: not a git repository");
+    return 2;
+  }
+  if (result.ok) {
+    console.log(`Branch hygiene clean — no work stranded off ${result.base}, no stale PRs.`);
+    return 0;
+  }
+  if (result.stranded.length) {
+    console.log(`⚠ ${result.stranded.length} branch(es) with unshipped commits ahead of ${result.base}:`);
+    for (const s of result.stranded) {
+      console.log(`  - ${s.branch} (+${s.ahead} commit${s.ahead === 1 ? "" : "s"}) — /qualia-ship it or merge, or delete if abandoned`);
+    }
+  }
+  if (result.stale_prs.length) {
+    console.log(`⚠ ${result.stale_prs.length} stale open PR(s):`);
+    for (const p of result.stale_prs) console.log(`  - #${p.number} ${p.title} (${p.age_days}d, ${p.branch})`);
+  }
+  return 1;
+}
+
+module.exports = { analyze, strandedBranches, mainBranch };
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}

package/bin/command-surface.js

@@ -14,6 +14,7 @@ const ACTIVE_SKILLS = [
   "qualia-plan",
   "qualia-build",
   "qualia-verify",
+  "qualia-eval",
   "qualia-fix",
   "qualia-feature",
   "qualia-review",
@@ -28,6 +29,7 @@ const ACTIVE_SKILLS = [
   "qualia-doctor",
   "qualia-road",
   "qualia-learn",
+  "qualia-recall",
   "qualia-postmortem",
   "qualia-idk",
   "qualia-secure",

package/bin/compile-instructions.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// compile-instructions.js — single-source the agent-instruction files.
+//
+// CLAUDE.md and AGENTS.md used to be hand-maintained twins, which guarantees
+// drift (and they HAD drifted — the MVP-first line and the substrate list
+// differed). Now both are compiled from one canonical source,
+// templates/instructions.md, via the host adapter. Editors touch the canonical;
+// the per-host files are generated artifacts (committed, like a lockfile).
+//
+//   node bin/compile-instructions.js          # regenerate CLAUDE.md + AGENTS.md
+//   node bin/compile-instructions.js --check  # fail (exit 1) if either is stale
+//
+// The --check mode is the drift guard the test suite runs: it makes "edited one
+// twin, forgot the other" impossible to merge.
+
+const fs = require("fs");
+const path = require("path");
+const { adapter, compileInstructions } = require("./host-adapters.js");
+
+const FRAMEWORK_DIR = path.resolve(__dirname, "..");
+const CANONICAL = path.join(FRAMEWORK_DIR, "templates", "instructions.md");
+
+const HEADER =
+  "<!-- GENERATED from templates/instructions.md by bin/compile-instructions.js — do not edit directly; edit the canonical source and recompile. -->";
+
+// host → output filename, declared by the adapter (single source of per-host facts).
+const TARGETS = ["claude", "codex"];
+
+function expectedFor(canonical, host) {
+  return `${HEADER}\n\n${compileInstructions(canonical, host)}`;
+}
+
+function targets() {
+  return TARGETS.map((host) => ({
+    host,
+    file: adapter(host).instructionFile,
+    pathAbs: path.join(FRAMEWORK_DIR, adapter(host).instructionFile),
+  }));
+}
+
+function main(argv) {
+  const check = argv.includes("--check");
+  let canonical;
+  try {
+    canonical = fs.readFileSync(CANONICAL, "utf8");
+  } catch (e) {
+    console.error(`ERROR: cannot read canonical source ${CANONICAL}: ${e.message}`);
+    return 2;
+  }
+
+  const drift = [];
+  for (const t of targets()) {
+    const expected = expectedFor(canonical, t.host);
+    if (check) {
+      let actual = null;
+      try { actual = fs.readFileSync(t.pathAbs, "utf8"); } catch {}
+      if (actual !== expected) {
+        drift.push(t.file);
+        console.error(`DRIFT: ${t.file} is out of sync with templates/instructions.md`);
+      }
+    } else {
+      fs.writeFileSync(t.pathAbs, expected, "utf8");
+      console.log(`wrote ${t.file} (from templates/instructions.md, host=${t.host})`);
+    }
+  }
+
+  if (check) {
+    if (drift.length) {
+      console.error(`\n${drift.length} file(s) stale. Run: node bin/compile-instructions.js`);
+      return 1;
+    }
+    console.log("CLAUDE.md + AGENTS.md are in sync with templates/instructions.md");
+    return 0;
+  }
+  return 0;
+}
+
+module.exports = { expectedFor, targets, HEADER, CANONICAL };
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}

package/bin/design-tokens.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// design-tokens.js — the per-client design-token registry (R10).
+//
+// First-party brand data is the proven escape from AI design monoculture: ground
+// every builder in a real design system (CSS custom properties) instead of
+// letting each invent its own palette. This compiles a client's brand spec
+// (design-tokens.json) into a tokens.css registry that the scaffold imports and
+// every builder references via var(--…) — never a hardcoded hex (the
+// ABS-HEX-IN-JSX slop ban). The shadcn-registry pattern, zero-dep.
+//
+// Usage:
+//   design-tokens.js init [--out FILE]            # write a starter registry JSON
+//   design-tokens.js compile <tokens.json> [--out FILE]   # JSON → tokens.css
+//   design-tokens.js compile <tokens.json> --json # emit the flat var map as JSON
+//
+// Exit: 0 ok, 2 bad invocation / unreadable / invalid JSON. Zero deps.
+
+const fs = require("fs");
+
+const STARTER = {
+  $schema: "qualia-design-tokens/1",
+  color: {
+    bg: "oklch(0.99 0.005 95)",
+    fg: "oklch(0.22 0.02 265)",
+    accent: "oklch(0.62 0.18 250)",
+    muted: "oklch(0.55 0.02 265)",
+    border: "oklch(0.9 0.01 265)",
+  },
+  font: {
+    sans: "Geist, ui-sans-serif, system-ui, sans-serif",
+    serif: "Fraunces, ui-serif, Georgia, serif",
+    mono: "Geist Mono, ui-monospace, monospace",
+  },
+  radius: { sm: "0.25rem", md: "0.5rem", lg: "1rem" },
+  space: { unit: "0.25rem" },
+};
+
+// Flatten { group: { key: val } } → { "group-key": val }. One level of nesting;
+// scalar top-level keys (e.g. radius: "0.5rem") become bare vars.
+function flatten(spec) {
+  const out = {};
+  for (const [group, val] of Object.entries(spec)) {
+    if (group.startsWith("$")) continue; // skip $schema etc.
+    if (val && typeof val === "object" && !Array.isArray(val)) {
+      for (const [key, v] of Object.entries(val)) {
+        out[`${group}-${key}`] = String(v);
+      }
+    } else {
+      out[group] = String(val);
+    }
+  }
+  return out;
+}
+
+function toCss(spec) {
+  const vars = flatten(spec);
+  const lines = Object.entries(vars).map(([k, v]) => `  --${k}: ${v};`);
+  return [
+    "/* GENERATED by design-tokens.js from design-tokens.json — the client brand registry.",
+    "   Builders reference var(--…); never hardcode a hex (slop ban ABS-HEX-IN-JSX). */",
+    ":root {",
+    ...lines,
+    "}",
+    "",
+  ].join("\n");
+}
+
+function readJson(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch {
+    process.stderr.write(`design-tokens.js: cannot read ${file}\n`);
+    process.exit(2);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    process.stderr.write(`design-tokens.js: invalid JSON in ${file}: ${e.message}\n`);
+    process.exit(2);
+  }
+}
+
+function parseOut(argv) {
+  const i = argv.indexOf("--out");
+  return i >= 0 ? argv[i + 1] : null;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+
+  if (cmd === "init") {
+    const out = parseOut(argv);
+    const json = JSON.stringify(STARTER, null, 2) + "\n";
+    if (out) {
+      fs.writeFileSync(out, json);
+      console.log(`wrote starter registry → ${out}`);
+    } else {
+      process.stdout.write(json);
+    }
+    process.exit(0);
+  }
+
+  if (cmd === "compile") {
+    const file = argv[1];
+    if (!file || file.startsWith("--")) {
+      process.stderr.write("design-tokens.js compile <tokens.json> [--out FILE] [--json]\n");
+      process.exit(2);
+    }
+    const spec = readJson(file);
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(flatten(spec), null, 2));
+      process.exit(0);
+    }
+    const css = toCss(spec);
+    const out = parseOut(argv);
+    if (out) {
+      fs.writeFileSync(out, css);
+      console.log(`wrote token registry → ${out}`);
+    } else {
+      process.stdout.write(css);
+    }
+    process.exit(0);
+  }
+
+  process.stderr.write("design-tokens.js — per-client design-token registry\n\n  init [--out FILE]\n  compile <tokens.json> [--out FILE] [--json]\n");
+  process.exit(2);
+}
+
+main();

package/bin/erp-event.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// erp-event.js — the framework EMIT side of the unified event log (R14).
+//
+// Builds a signed FrameworkEvent envelope and queues it for the ERP's
+// POST /api/v1/events. The HMAC is keyed by the install's API token (the same
+// qlt_ key used for reports), so the ERP — which holds only the token's hash but
+// sees the plaintext Bearer per request — can verify body integrity + replay.
+// Standard-Webhooks shape: id/timestamp/signature ride in headers, the event in
+// the body. Non-blocking and graceful: ERP disabled or no key ⇒ a silent no-op.
+//
+// Mirrors lib/framework-events.ts on the ERP side — signingContent and the
+// HMAC-SHA256/base64 must stay byte-identical or signatures won't verify.
+//
+// Usage:
+//   erp-event.js emit <action> [--target type:ref]... [--project <uuid>]
+//                 [--meta k=v]... [--ctx k=v]... [--json] [--dry-run]
+//   # e.g. erp-event.js emit verify_pass --target project:acme --project <uuid>
+//
+// Exit: 0 = queued or skipped (never blocks a session), 2 = bad invocation.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const crypto = require("crypto");
+
+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 QUALIA_HOME = qualiaHome();
+const CONFIG_FILE = path.join(QUALIA_HOME, ".qualia-config.json");
+const API_KEY_FILE = path.join(QUALIA_HOME, ".erp-api-key");
+
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function readApiKey() {
+  try {
+    return fs.readFileSync(API_KEY_FILE, "utf8").trim();
+  } catch {
+    return "";
+  }
+}
+
+// The exact bytes the ERP re-signs: `${id}.${timestamp}.${rawBody}`. rawBody is
+// the EXACT payload string we queue — erp-retry posts it verbatim.
+function signingContent(id, timestamp, rawBody) {
+  return `${id}.${timestamp}.${rawBody}`;
+}
+function computeSignature(content, secret) {
+  return crypto.createHmac("sha256", secret).update(content).digest("base64");
+}
+
+// Build (and optionally sign) the envelope. Pure; injectable id/now for tests.
+function buildSignedEvent(action, opts = {}) {
+  const cfg = opts.config || readConfig();
+  const apiKey = opts.apiKey != null ? opts.apiKey : readApiKey();
+  const id = opts.id || (crypto.randomUUID ? crypto.randomUUID() : String(Math.random()).slice(2));
+  const ts = String(opts.now != null ? opts.now : Math.floor(Date.now() / 1000));
+
+  const event = {
+    action,
+    actor: opts.actor || {
+      code: cfg.code,
+      name: cfg.installed_by,
+      role: cfg.role,
+    },
+    ...(opts.targets && opts.targets.length ? { targets: opts.targets } : {}),
+    ...(opts.context ? { context: opts.context } : {}),
+    ...(opts.metadata ? { metadata: opts.metadata } : {}),
+    occurred_at: opts.occurredAt || new Date(Number(ts) * 1000).toISOString(),
+    ...(opts.erpProjectId ? { erp_project_id: opts.erpProjectId } : {}),
+    ...(opts.workspaceId ? { workspace_id: opts.workspaceId } : {}),
+  };
+
+  const payload = JSON.stringify(event);
+  const headers = { "Qualia-Event-Id": id, "Qualia-Event-Timestamp": ts };
+  // Sign only when we have a key — unsigned posts still authenticate via Bearer
+  // and the ERP records them signature_valid=false.
+  if (apiKey) headers["Qualia-Signature"] = computeSignature(signingContent(id, ts, payload), apiKey);
+
+  return { id, ts, event, payload, headers };
+}
+
+// In-process emit (hooks/skills can require this). Returns a result object;
+// never throws on ERP/network conditions.
+function emitEvent(action, opts = {}) {
+  const cfg = opts.config || readConfig();
+  if (cfg.erp && cfg.erp.enabled === false) return { ok: true, skipped: "erp-disabled" };
+  const erpUrl = (cfg.erp && cfg.erp.url) || "https://portal.qualiasolutions.net";
+  const built = buildSignedEvent(action, { ...opts, config: cfg });
+  if (opts.dryRun) return { ok: true, dryRun: true, ...built };
+
+  try {
+    const retryPath = path.join(QUALIA_HOME, "bin", "erp-retry.js");
+    const enqueue = fs.existsSync(retryPath)
+      ? require(retryPath).enqueue
+      : require("./erp-retry.js").enqueue;
+    enqueue({
+      client_report_id: built.id, // event_id is unique → no false dedupe
+      idempotency_key: built.id,
+      url: `${erpUrl.replace(/\/$/, "")}/api/v1/events`,
+      payload: built.payload,
+      headers: built.headers,
+    });
+    return { ok: true, queued: true, ...built };
+  } catch (e) {
+    return { ok: false, error: e && e.message ? e.message : String(e), ...built };
+  }
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+function parseKv(list) {
+  const out = {};
+  for (const item of list) {
+    const i = item.indexOf("=");
+    if (i > 0) out[item.slice(0, i)] = item.slice(i + 1);
+  }
+  return out;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv[0] !== "emit") {
+    process.stderr.write("erp-event.js emit <action> [--target type:ref] [--project uuid] [--meta k=v] [--ctx k=v] [--json] [--dry-run]\n");
+    process.exit(2);
+  }
+  const action = argv[1];
+  if (!action || action.startsWith("--")) {
+    process.stderr.write("erp-event.js: <action> is required (e.g. verify_pass)\n");
+    process.exit(2);
+  }
+  const targets = [];
+  const metaKv = [];
+  const ctxKv = [];
+  const opts = { json: false, dryRun: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--target") {
+      const t = argv[++i] || "";
+      const c = t.indexOf(":");
+      targets.push(c > 0 ? { type: t.slice(0, c), ref: t.slice(c + 1) } : { ref: t });
+    } else if (a === "--project") opts.erpProjectId = argv[++i];
+    else if (a === "--workspace") opts.workspaceId = argv[++i];
+    else if (a === "--meta") metaKv.push(argv[++i] || "");
+    else if (a === "--ctx") ctxKv.push(argv[++i] || "");
+    else if (a === "--json") opts.json = true;
+    else if (a === "--dry-run") opts.dryRun = true;
+  }
+  if (targets.length) opts.targets = targets;
+  if (metaKv.length) opts.metadata = parseKv(metaKv);
+  if (ctxKv.length) opts.context = parseKv(ctxKv);
+
+  const result = emitEvent(action, opts);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.skipped) {
+    console.log(`erp-event: skipped (${result.skipped})`);
+  } else if (result.dryRun) {
+    console.log(`erp-event: [dry-run] ${action} id=${result.id} signed=${!!result.headers["Qualia-Signature"]}`);
+  } else if (result.queued) {
+    console.log(`⬢ event queued: ${action} (${result.id})`);
+  } else if (!result.ok) {
+    console.error(`erp-event: ${result.error}`);
+  }
+  process.exit(0);
+}
+
+module.exports = { emitEvent, buildSignedEvent, signingContent, computeSignature };
+
+if (require.main === module) main();

package/bin/erp-retry.js

@@ -101,7 +101,7 @@ function writeQueue(data) {
   fs.renameSync(tmp, QUEUE_FILE);
 }
 
-function enqueue({ client_report_id, idempotency_key, url, payload, last_error }) {
+function enqueue({ client_report_id, idempotency_key, url, payload, last_error, headers }) {
   if (!client_report_id || !url || !payload) {
     throw new Error("enqueue: client_report_id, url, payload are required");
   }
@@ -113,6 +113,7 @@ function enqueue({ client_report_id, idempotency_key, url, payload, last_error }
     existing.idempotency_key = idempotency_key || existing.idempotency_key;
     existing.url = url;
     existing.payload = payload;
+    if (headers) existing.headers = headers;
     existing.last_error = last_error || existing.last_error || "";
     existing.attempts = existing.attempts || 0;
     existing.give_up = false; // unblock a retry if user fixed the underlying issue
@@ -123,6 +124,7 @@ function enqueue({ client_report_id, idempotency_key, url, payload, last_error }
       idempotency_key: idempotency_key || "",
       url,
       payload,
+      ...(headers ? { headers } : {}),
       enqueued_at: new Date().toISOString(),
       attempts: 0,
       last_error: last_error || "",
@@ -146,6 +148,15 @@ function postOnce(item, apiKey) {
       "Content-Length": Buffer.byteLength(item.payload),
     };
     if (item.idempotency_key) headers["Idempotency-Key"] = item.idempotency_key;
+    // Per-item custom headers (e.g. the signed-event envelope:
+    // Qualia-Event-Id / Qualia-Event-Timestamp / Qualia-Signature). Auth +
+    // Content-* are framework-owned and not overridable.
+    if (item.headers && typeof item.headers === "object") {
+      for (const [k, v] of Object.entries(item.headers)) {
+        if (/^(authorization|content-type|content-length)$/i.test(k)) continue;
+        headers[k] = String(v);
+      }
+    }
     const req = lib.request({
       method: "POST",
       hostname: u.hostname,