qualia-framework 6.22.0 → 7.0.0

package/CHANGELOG.md

@@ -8,6 +8,192 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > Note: git tags for historical versions were not retained; commit references are approximate
 > and dates reflect commit history rather than npm publish timestamps.
 
+## [7.0.0] - 2026-06-22 (v7 — the restructure is complete)
+
+The v7 milestone release. The 6.12→6.29 line landed the whole v7 restructure
+brief; this marks it shipped. Highlights across the arc:
+
+- **v7.0 lifecycle** — build→operate, forced-handoff removed; the three missing
+  runtime primitives wired as deterministic gates: R1 file-disjointness pre-write
+  hook, R2 `.agent-status` fan-in barrier, R3 cross-artifact `/analyze` gate.
+- **v7.1 memory** — `/qualia-recall` (read side of `/qualia-learn`), a single
+  shared vault access-control module honoring `wiki/_meta/access.md` (enforced by
+  both recall and the read-only memory MCP), and `bin/repo-map.js` (R18).
+- **v7.2 verification** — the framework's OWN test surface is now gated in CI
+  (R6: `runner.js` joined `npm test`); R7 `/qualia-eval`, R8 verifier panel, R19
+  voice DoD confirmed.
+- **v7.3 codex-adapter** — CLAUDE.md + AGENTS.md from one source (R4); every
+  runtime-behavior branch routed through `host-adapters.js` (R5).
+- **Design + scale** — tunable design dials + ban→do-instead pre-flight (R9),
+  per-client token registry (R10), `/qualia-build --batch` migration lane (R20).
+- **ERP event integration (R14/R12)** — one signed, append-only `framework_events`
+  log: the framework signs and emits lifecycle events; the ERP verifies (HMAC
+  byte-matched across repos) and renders a live run-tree. Live in production.
+
+Test surface at release: 24 shell suites + 179 cross-platform node tests, both
+gated by `npm test`. No functional change in this bump — it tags the milestone.
+
+## [6.29.0] - 2026-06-22 (R14 client — the framework now emits signed events to the ERP)
+
+The ERP side of R14 (the `framework_events` table + `/api/v1/events` +
+`/api/v1/policy-events`) shipped in the `qualia-erp` repo and is live in
+production. This is the framework EMIT side that closes the loop.
+
+### Added — `bin/erp-event.js`: signed lifecycle-event emitter
+- Builds a `FrameworkEvent` envelope and queues it for `POST /api/v1/events`.
+  HMAC-SHA256 keyed by the install's `qlt_` token over `${id}.${timestamp}.${body}`
+  — **byte-identical** to the ERP's `lib/framework-events.ts` verifier (tested as
+  a cross-repo contract), so signatures verify with no extra secret. Headers
+  carry id/timestamp/signature (Standard-Webhooks shape); the event is the body.
+- Non-blocking + graceful: ERP disabled or no API key ⇒ silent no-op; unsigned
+  posts still authenticate via Bearer (recorded `signature_valid=false`).
+  `emit <action> [--target type:ref] [--project uuid] [--meta k=v] [--json]
+  [--dry-run]`, plus an `emitEvent()` export for in-process callers.
+
+### Changed
+- `bin/erp-retry.js`: the retry queue now carries optional per-item `headers`
+  (so the signed-event envelope rides the existing idempotent retry rails);
+  Auth/Content-* stay framework-owned and non-overridable.
+- `/qualia-verify`: emits `verify_pass` / `verify_fail` after the state
+  transition — the first live lifecycle signal into the ERP run-tree. Other
+  points (`session_started`, `phase_planned`, `build_wave_started`) documented.
+- `docs/erp-contract.md`: new "POST /api/v1/events" section (envelope, headers,
+  signing).
+- `tests/erp-event.test.sh` (14 cases incl. the cross-repo signature match);
+  run-all now **24 suites**, all green (+179 node).
+
+## [6.28.0] - 2026-06-22 (R20 — the migration lane for /qualia-build)
+
+### Added — `bin/batch-plan.js` + `/qualia-build --batch`
+- The wave model fits a phase; it doesn't fit a 50–500-file codemod. `--batch` is
+  a map-reduce over a flat file list: `batch-plan.js` splits it into
+  FILE-DISJOINT batches (each a worktree-isolated worker with tiny context that
+  opens its own commit) grouped into concurrency-capped waves, fanned in through
+  ONE staging branch. Deterministic split (dedup, complete, disjoint, waves ≤
+  max-workers); the orchestration lives in the skill.
+- `--from FILE`/stdin, `--batch-size`, `--max-workers`, `--staging`, `--json`.
+  Zero-dep. `/qualia-build --batch` documents the full orchestration (staging
+  branch → per-wave worktree workers → fan-in → test once → ship), including
+  "log any dropped batch — no silent partial migrations."
+- `tests/batch-plan.test.sh` (15); run-all now **23 suites**, all green (+179 node).
+
+## [6.27.0] - 2026-06-22 (R9 + R10 — design dials, ban→do-instead pre-flight, per-client token registry)
+
+Two framework-area design enhancements: steer generation away from slop upfront,
+and ground every builder in a real per-client design system.
+
+### Added — R9: tunable design dials + generation-time pre-flight
+- `qualia-design/design-dials.md`: DESIGN_VARIANCE / MOTION_INTENSITY /
+  VISUAL_DENSITY (LOW|MED|HIGH) with concrete mappings + register/project-type
+  gating, plus a ban→do-instead table mirroring slop-detect's rules WITH the
+  positive alternative (avoids the pink-elephant backfire). The generation-time
+  half of the anti-slop contract; slop-detect remains the post-hoc gate.
+- `templates/DESIGN.md` §0 declares the dials; `/qualia-polish` Stage 0 resolves
+  them and cites the bans before editing.
+
+### Added — R10: per-client design-token registry
+- `bin/design-tokens.js`: compiles a client brand spec (`design-tokens.json`)
+  into a CSS-variable registry (`tokens.css`). `/qualia-new` scaffolds it;
+  builders reference `var(--…)`, never a literal hex. The shadcn-registry
+  pattern — first-party brand data is the escape from design monoculture.
+- `tests/design-tokens.test.sh` (14) + the dials contract test in lib.test.sh;
+  run-all now **22 suites**, all green (+ 179 node).
+
+## [6.26.0] - 2026-06-22 (R18 — a cheap symbol map for brownfield onboarding)
+
+### Added — `bin/repo-map.js`, wired into `/qualia-map`
+- Aider's repo-map idea, in the framework's zero-dep idiom: a deterministic
+  symbol map of a codebase (top-level exports/functions/classes/types per file,
+  busiest files first) via language-aware regexes for JS/TS, Python, Go, Rust,
+  Ruby, Java, PHP. NO tree-sitter native dependency — the brief named tree-sitter
+  but that fights the framework's zero-dep posture; regex extraction gets the
+  "what's in this repo and where" signal at zero cost.
+- `/qualia-map` now runs it BEFORE the mapper agents (`repo-map.json`), so they
+  onboard from a structural index instead of reading the tree blind — cheaper,
+  better-grounded brownfield scans. `--json`, `--max-files`; skips
+  node_modules/dist/.git/etc.; exit 2 on bad dir. Registered in
+  runtime-manifest + lib install set; `tests/repo-map.test.sh` (14 cases).
+  run-all now **21 suites**.
+
+## [6.25.0] - 2026-06-21 (v7.3 codex-adapter — the last runtime branch moves into the seam)
+
+v7.3 is complete. R4 (emit AGENTS.md alongside CLAUDE.md from one canonical
+source) was already shipped via `bin/compile-instructions.js` — both files
+compile from `templates/instructions.md` through the host adapter, with a
+`--check` drift guard gated by the `instructions` suite. This release finishes R5.
+
+### Changed — R5: agent-CLI invocation is now an adapter fact (no more stray runtime branch)
+- `host-adapters.js` was already the real seam (declarative `HOSTS`, per-host
+  paths/naming/instruction-file). The one genuine `if (codex)` behavior branch
+  still living outside it was in `knowledge-flush.js`: it hardcoded
+  `codex`/`claude` as the CLI and `exec`/`-p` as the invocation. Those are
+  per-host FACTS — moved into the adapter: `agentCli` + `agentExecPrefix`
+  (declarative) → `adapter().agentExec(prompt)` (computed argv), plus
+  `hostForHome(home)` so the home→host mapping has one owner.
+- `knowledge-flush.js` now asks the adapter instead of branching. When a third
+  runtime arrives it's one `HOSTS` entry, not a grep-and-patch. lib.test.sh
+  covers the new facts.
+- Left intentionally: the `qualiaHome()` install-root idiom repeated across
+  bins/hooks treats both hosts IDENTICALLY (it's home resolution, not a behavior
+  branch) — sweeping 20 files for a no-op-difference helper is high-risk,
+  low-value, and would touch hot paths. Noted, not done.
+
+## [6.24.0] - 2026-06-21 (v7.2 verification — gate the framework's own test surface)
+
+v7.2 verification is complete. R7 (`/qualia-eval` lane), R8 (verify-panel +
+adversarial skeptics), and R19 (voice-agent archetype DoD) shipped earlier and
+are confirmed green. This release closes R6.
+
+### Fixed — R6: the framework's own checks can no longer silently regress
+- The cross-platform `tests/runner.js` harness (179 node:test cases, incl. the
+  memory-MCP suite) was **never run by `npm test`** — only the shell suite was.
+  That is exactly why it silently drifted to 21 failures: nothing ran it. Now
+  `npm test` runs BOTH (`test:shell && test:node`), so CI (`run: npm test`)
+  gates the full surface — 20 shell suites + 179 node tests. Added a `test:node`
+  script. Verified CI-safe (179/179 with an empty HOME, no install required).
+- This is R6's real intent for a deterministic/offline framework: a machine gate
+  on the framework's OWN checks. The LLM-prompt-level eval of skills is out of
+  scope for offline CI; `/qualia-eval` (R7) already provides that lane for the AI
+  artifacts projects build.
+
+## [6.23.0] - 2026-06-21 (v7.1 memory loop — recall, vault access control, harness health)
+
+Completes the v7.1 memory work: the read side now exists, the vault has real
+access control, and the cross-platform test harness is green again.
+
+### Added — `/qualia-recall` + `bin/recall.js`: the read side of memory
+- Kills the `/qualia-recall` ghost (referenced in `agents/researcher.md` and
+  `skills/qualia-research` but never built). `recall.js` unifies BOTH stores in
+  one ranked digest: the knowledge layer (delegates to `knowledge.js` so new
+  files stay discoverable) + the qualia-memory vault (grep over `wiki/`).
+  `--json`, `--scope all|knowledge|vault`, `--max`. Zero deps. Registered in
+  `command-surface` ACTIVE_SKILLS + `runtime-manifest`.
+
+### Added — vault access control (`bin/vault-access.js`, `rules/access.md`)
+- The vault's `wiki/_meta/access.md` manifest named `/qualia-recall` as an
+  enforcer, referenced an enforcing rule at `~/.claude/rules/access.md`, and
+  expected readers to honor OWNER_ONLY / CONDITIONAL paths — but **none of those
+  existed**. Now: `vault-access.js` is the single implementation (parse manifest,
+  resolve role, deny non-OWNER reads of OWNER_ONLY/CONDITIONAL paths,
+  fail-closed on unknown role); `rules/access.md` is the always-on enforcing
+  rule; **both** `recall.js` and the always-on memory MCP enforce it through that
+  one module so the security rule can't drift. No-manifest ⇒ no filtering (the
+  wiki is curated-by-design; sensitive stores live outside `wiki/`).
+
+### Fixed — test harness health
+- `tests/runner.js` (cross-platform node:test harness) had drifted to 154/21;
+  re-synced to current bin/hook contracts (MISSING_CONTRACT/evidence,
+  SUSPICIOUS_NAME, set-erp-key stdin, branch-guard v6.10 allowed+recorded) with
+  no assertions weakened. Now **179**, with the new memory-MCP access cases.
+- `tests/recall.test.sh` (18 cases) added; `run-all` now **20 suites**, all green.
+
+### Fixed — vault docs (qualia-memory repo)
+- `CLAUDE.md` named a non-existent `flush.py` for session capture (the real
+  mechanism is the claude-memory-compiler SessionEnd hook) and carried a stale
+  `/home/qualia-new/` path. Corrected. No framework write-back leg was built:
+  the vault's session loop is external and already exists; the framework's
+  knowledge tier is separate by design.
+
 ## [6.22.0] - 2026-06-21 (session continuity + ERP project-sync — built by two parallel worktree agents)
 
 Two independent continuity features, built concurrently in isolated git worktrees and integrated together.

package/bin/batch-plan.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// batch-plan.js — the deterministic core of /qualia-build --batch (R20).
+//
+// The wave model fits feature builds (a handful of dependency-linked tasks); it
+// does NOT fit a 50–500-file mechanical migration (a codemod). This splits a
+// flat file list into worktree-isolated, FILE-DISJOINT batches — each a small
+// worker with tiny context that opens its own commit — then groups them into
+// concurrency-capped waves that fan in through one staging branch. Map-reduce
+// over files. Zero-dep; the orchestration (spawning workers, merging) lives in
+// the /qualia-build skill — this owns the split so it's deterministic + testable.
+//
+// Usage:
+//   batch-plan.js <file> [<file> …]        # files as args
+//   batch-plan.js --from LIST              # newline-delimited file (- = stdin)
+//   …  --batch-size N (default 20)  --max-workers K (default 5)
+//      --staging BRANCH (default batch/staging)  --json
+//
+// Exit: 0 ok (even 0 files), 2 bad invocation. Zero deps.
+
+const fs = require("fs");
+
+function parseArgs(argv) {
+  const o = { files: [], batchSize: 20, maxWorkers: 5, staging: "batch/staging", json: false, from: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--batch-size") o.batchSize = Math.max(1, parseInt(argv[++i], 10) || 20);
+    else if (a === "--max-workers") o.maxWorkers = Math.max(1, parseInt(argv[++i], 10) || 5);
+    else if (a === "--staging") o.staging = argv[++i] || o.staging;
+    else if (a === "--from") o.from = argv[++i];
+    else if (a === "--json") o.json = true;
+    else if (a === "-h" || a === "--help") o.help = true;
+    else o.files.push(a);
+  }
+  return o;
+}
+
+function chunk(arr, size) {
+  const out = [];
+  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
+  return out;
+}
+
+function readList(from) {
+  let raw;
+  if (from === "-") {
+    try { raw = fs.readFileSync(0, "utf8"); } catch { raw = ""; }
+  } else {
+    try { raw = fs.readFileSync(from, "utf8"); } catch {
+      process.stderr.write(`batch-plan.js: cannot read ${from}\n`);
+      process.exit(2);
+    }
+  }
+  return raw.split("\n").map((s) => s.trim()).filter(Boolean);
+}
+
+function buildPlan(files, opts) {
+  // De-dup while preserving order — a file must land in exactly one batch.
+  const seen = new Set();
+  const unique = [];
+  for (const f of files) {
+    if (!seen.has(f)) { seen.add(f); unique.push(f); }
+  }
+  const groups = chunk(unique, opts.batchSize);
+  const pad = String(groups.length).length;
+  const batches = groups.map((batchFiles, i) => {
+    const id = String(i + 1).padStart(pad, "0");
+    return { id, branch: `batch/${opts.staging.replace(/^batch\//, "")}-${id}`, file_count: batchFiles.length, files: batchFiles };
+  });
+  // Batches are file-disjoint → all parallelizable; cap concurrency into waves.
+  const waves = chunk(batches.map((b) => b.id), opts.maxWorkers);
+  return {
+    total_files: unique.length,
+    batch_size: opts.batchSize,
+    max_workers: opts.maxWorkers,
+    batch_count: batches.length,
+    wave_count: waves.length,
+    staging_branch: opts.staging,
+    waves,
+    batches,
+  };
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    process.stdout.write("batch-plan.js <file…> | --from LIST [--batch-size N] [--max-workers K] [--staging B] [--json]\n");
+    process.exit(0);
+  }
+  let files = opts.files;
+  if (opts.from) files = files.concat(readList(opts.from));
+  const plan = buildPlan(files, opts);
+
+  if (opts.json) {
+    console.log(JSON.stringify(plan, null, 2));
+    process.exit(0);
+  }
+
+  console.log(`batch-plan: ${plan.total_files} files → ${plan.batch_count} batches (≤${plan.batch_size} each) → ${plan.wave_count} waves (≤${plan.max_workers} workers)`);
+  console.log(`staging branch: ${plan.staging_branch}`);
+  for (let w = 0; w < plan.waves.length; w++) {
+    console.log(`\nwave ${w + 1}: ${plan.waves[w].join(", ")}`);
+    for (const id of plan.waves[w]) {
+      const b = plan.batches.find((x) => x.id === id);
+      console.log(`  batch ${id} → ${b.branch} (${b.file_count} files)`);
+    }
+  }
+  if (plan.batch_count === 0) console.log("(no files — nothing to migrate)");
+  process.exit(0);
+}
+
+main();

package/bin/command-surface.js

@@ -29,6 +29,7 @@ const ACTIVE_SKILLS = [
   "qualia-doctor",
   "qualia-road",
   "qualia-learn",
+  "qualia-recall",
   "qualia-postmortem",
   "qualia-idk",
   "qualia-secure",

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,