qualia-framework 6.9.0 → 6.14.0

package/hooks/branch-guard.js

@@ -1,13 +1,19 @@
 #!/usr/bin/env node
-// ~/.claude/hooks/branch-guard.js — block non-OWNER push to main/master.
-// PreToolUse hook on `git push*` commands. Reads role from
-// ~/.claude/.qualia-config.json (single source of truth).
-// Exits 2 to BLOCK (Claude Code hook protocol). Exits 0 to allow.
+// ~/.claude/hooks/branch-guard.js — ACCOUNTABILITY for non-OWNER pushes to
+// main/master. Policy changed in v6.10: pushing to main is no longer BLOCKED.
+// Instead every employee push to a protected branch is COUNTED — recorded
+// locally (per-employee total) and reported to the ERP as a policy-event the
+// OWNER can see — and the employee gets a visible notice. OWNER pushes are
+// unaffected and silent. This hook never blocks (always exits 0).
+//
+// PreToolUse hook on `git push*`. Reads role from ~/.claude/.qualia-config.json.
+// Mirrors the allow-and-record model of fawzi-approval-guard.js.
 // Cross-platform (Windows/macOS/Linux).
 
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
+const crypto = require("crypto");
 const { spawnSync } = require("child_process");
 
 const _traceStart = Date.now();
@@ -21,13 +27,14 @@ function qualiaHome() {
 
 const QUALIA_HOME = qualiaHome();
 const CONFIG = path.join(QUALIA_HOME, ".qualia-config.json");
+const EVENT_FILE = path.join(QUALIA_HOME, ".main-push-events.json");
 
-function _trace(hookName, result, extra) {
+function _trace(result, extra) {
   try {
     const traceDir = path.join(QUALIA_HOME, ".qualia-traces");
     if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
     const entry = {
-      hook: hookName,
+      hook: "branch-guard",
       result,
       timestamp: new Date().toISOString(),
       duration_ms: Date.now() - _traceStart,
@@ -38,64 +45,131 @@ function _trace(hookName, result, extra) {
   } catch {}
 }
 
-function fail(msg, extraLines) {
-  // Claude Code surfaces stderr in hook block reasons — write there primarily.
-  // Also mirror to stdout so downstream tooling that scrapes stdout still sees it.
-  console.error(msg);
-  console.log(msg);
-  if (Array.isArray(extraLines)) {
-    for (const line of extraLines) {
-      console.error(line);
-      console.log(line);
-    }
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return fallback;
   }
-  _trace("branch-guard", "block", { reason: msg });
-  process.exit(2);
 }
 
-let role = "";
-try {
-  const cfg = JSON.parse(fs.readFileSync(CONFIG, "utf8"));
-  role = cfg.role || "";
-} catch {
-  fail(`BLOCKED: ${CONFIG} missing or unreadable. Run: npx qualia-framework install`);
+function writeJson(file, data) {
+  try {
+    const dir = path.dirname(file);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${file}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+    try { fs.chmodSync(tmp, 0o600); } catch {}
+    fs.renameSync(tmp, file);
+  } catch {}
+}
+
+// Record the push locally and return the event (with the running per-actor count).
+function recordLocal(config, branch) {
+  const data = readJson(EVENT_FILE, { counts: {}, events: [] });
+  if (!data.counts || typeof data.counts !== "object") data.counts = {};
+  if (!Array.isArray(data.events)) data.events = [];
+
+  const key = config.code || config.installed_by || "unknown";
+  const prev = data.counts[key] || {};
+  const count = (prev.total || 0) + 1;
+  const event = {
+    type: "employee_main_push",
+    actor_code: config.code || "",
+    actor_name: config.installed_by || "",
+    actor_role: config.role || "",
+    count,
+    branch,
+    project: path.basename(process.cwd()),
+    cwd: process.cwd(),
+    recorded_at: new Date().toISOString(),
+  };
+
+  data.counts[key] = {
+    actor_code: event.actor_code,
+    actor_name: event.actor_name,
+    actor_role: event.actor_role,
+    total: count,
+    last_seen_at: event.recorded_at,
+  };
+  data.events.push(event);
+  data.events = data.events.slice(-200);
+  writeJson(EVENT_FILE, data);
+  return event;
+}
+
+// Queue the event for the ERP (idempotent, retried by erp-retry.js). Same
+// /api/v1/policy-events endpoint the proxy-approval guard uses — the ERP stores
+// by (type, actor_code) so the OWNER sees a per-employee main-push tally.
+function enqueueErp(config, event) {
+  try {
+    if (config.erp && config.erp.enabled === false) return;
+    const retryPath = path.join(QUALIA_HOME, "bin", "erp-retry.js");
+    if (!fs.existsSync(retryPath)) return;
+    const erpUrl = (config.erp && config.erp.url) || "https://portal.qualiasolutions.net";
+    const { enqueue } = require(retryPath);
+    enqueue({
+      client_report_id: `QS-MAINPUSH-${(event.actor_code || "UNKNOWN").replace(/[^A-Z0-9-]/gi, "")}-${event.count}`,
+      idempotency_key: crypto.randomUUID ? crypto.randomUUID() : "",
+      url: `${erpUrl.replace(/\/$/, "")}/api/v1/policy-events`,
+      payload: JSON.stringify(event),
+      last_error: "",
+    });
+  } catch {}
+}
+
+function notify(event, branch) {
+  // Visible, non-blocking notice. The push proceeds either way.
+  const who = event.actor_name || event.actor_code || "you";
+  const lines = [
+    `⬢ NOTICE: ${who} pushed to '${branch}'.`,
+    `  Recorded (framework + ERP) and visible to the OWNER — main-push #${event.count}.`,
+    `  Prefer a feature branch + review for changes that aren't trivially safe.`,
+  ];
+  for (const l of lines) console.error(l);
+}
+
+// ── role ────────────────────────────────────────────────────────────────────
+const config = readJson(CONFIG, null);
+if (!config) {
+  // Can't classify without config — but the hook no longer blocks anything.
+  _trace("allow", { reason: "config missing/unreadable" });
+  process.exit(0);
 }
+const role = (config.role || "").toUpperCase();
 
-if (!role) {
-  fail(`BLOCKED: Cannot determine role from ${CONFIG}. Defaulting to deny.`);
+// OWNER pushes to main are normal and unremarkable. Anything that isn't a known
+// EMPLOYEE is also left alone (nothing to attribute).
+if (role !== "EMPLOYEE") {
+  _trace("allow", { role });
+  process.exit(0);
 }
 
-// Read Claude Code hook payload from stdin (if any). Contains tool_input.command
-// with the actual `git push ...` invocation. Parsing this lets us catch refspec
-// bypasses like `git push origin feature/x:main` that --show-current would miss.
+// ── detect a push that targets a protected branch ───────────────────────────
 let pushCommand = "";
 try {
-  const raw = fs.readFileSync(0, "utf8");
-  if (raw && raw.trim()) {
-    const payload = JSON.parse(raw);
-    pushCommand = (payload && payload.tool_input && payload.tool_input.command) || "";
+  if (!process.stdin.isTTY) {
+    const raw = fs.readFileSync(0, "utf8");
+    if (raw && raw.trim()) {
+      const payload = JSON.parse(raw);
+      pushCommand = (payload && payload.tool_input && payload.tool_input.command) || "";
+    }
   }
 } catch {
-  // No stdin or non-JSON stdin — fall through to branch check.
+  // No stdin or non-JSON — fall through to the --show-current check.
 }
 
-// Tokenize the push command and detect refspecs targeting main/master.
-// Refspec forms: <src>:<dst>, :<dst> (delete), +<src>:<dst> (force).
-// We only flag explicit <src>:<dst> refspecs here; bare branch pushes
-// (e.g. `git push origin main` from a non-main branch) are uncommon and
-// handled by the --show-current fallback below when applicable.
+// Explicit refspec form: <src>:<dst>, :<dst>, +<src>:<dst> targeting main/master.
 function refspecTargetsProtected(cmd) {
   if (!cmd || typeof cmd !== "string") return null;
   const tokens = cmd.split(/\s+/).filter(Boolean);
   const pushIdx = tokens.indexOf("push");
   if (pushIdx === -1) return null;
-
   for (let i = pushIdx + 1; i < tokens.length; i++) {
     let tok = tokens[i];
     if (tok.startsWith("-")) continue;
     if (tok.startsWith("+")) tok = tok.slice(1);
     tok = tok.replace(/^['"]|['"]$/g, "");
-
     if (tok.includes(":")) {
       const parts = tok.split(":");
       const dst = parts[parts.length - 1].replace(/^refs\/heads\//, "");
@@ -105,30 +179,26 @@ function refspecTargetsProtected(cmd) {
   return null;
 }
 
-const refspecTarget = refspecTargetsProtected(pushCommand);
-if (refspecTarget && role !== "OWNER") {
-  fail(
-    `BLOCKED: Employees cannot push to ${refspecTarget}. Create a feature branch first.`,
-    ["Run: git checkout -b feature/your-feature-name"]
-  );
+let target = refspecTargetsProtected(pushCommand);
+if (!target) {
+  const r = spawnSync("git", ["branch", "--show-current"], {
+    encoding: "utf8",
+    timeout: 3000,
+    shell: process.platform === "win32",
+  });
+  const branch = ((r.stdout || "").trim());
+  if (branch === "main" || branch === "master") target = branch;
 }
 
-// Ask git for the current branch --show-current. Works identically on Windows/macOS/Linux.
-const r = spawnSync("git", ["branch", "--show-current"], {
-  encoding: "utf8",
-  timeout: 3000,
-  shell: process.platform === "win32",
-});
-const branch = ((r.stdout || "").trim());
-
-if (branch === "main" || branch === "master") {
-  if (role !== "OWNER") {
-    fail(
-      `BLOCKED: Employees cannot push to ${branch}. Create a feature branch first.`,
-      ["Run: git checkout -b feature/your-feature-name"]
-    );
-  }
+if (!target) {
+  // Not a protected-branch push — nothing to record.
+  _trace("allow", { role });
+  process.exit(0);
 }
 
-_trace("branch-guard", "allow");
+// ── count + notify, then ALLOW ──────────────────────────────────────────────
+const event = recordLocal(config, target);
+enqueueErp(config, event);
+notify(event, target);
+_trace("allow", { role, recorded: true, branch: target, count: event.count });
 process.exit(0);

package/hooks/pre-deploy-gate.js

@@ -322,6 +322,44 @@ if (leaks.length > 0) {
   process.exit(2);
 }
 console.log("  ✓ Security");
+
+// Anti-slop: zero-token deterministic scan for the AI-design tells the
+// constitution bans (banned fonts, purple-blue gradients, etc). slop-detect
+// exits 1 on CRITICAL findings; we translate that to a deploy block (exit 2).
+// Skipped silently when the scanner isn't installed (brownfield / older
+// installs) so it never breaks a project that predates it. OWNER-only escape
+// hatch mirrors QUALIA_SKIP_LINT.
+const slopScript = path.join(QUALIA_HOME, "bin", "slop-detect.mjs");
+if (fs.existsSync(slopScript)) {
+  const skipSlop = process.env.QUALIA_SKIP_SLOP === "1";
+  if (skipSlop) {
+    const slopRole = String(readConfig().role || "").toUpperCase();
+    if (slopRole !== "OWNER") {
+      const slopState = readState();
+      blockDeploy("QUALIA_SKIP_SLOP is OWNER-only.", (slopState && slopState.next_command) || "/qualia");
+    }
+    console.log("  ⚠ Anti-slop skipped (QUALIA_SKIP_SLOP=1)");
+    _trace("pre-deploy-gate", "skip-slop", { reason: "QUALIA_SKIP_SLOP=1" });
+  } else {
+    const r = spawnSync(process.execPath, [slopScript, "--severity=critical"], {
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf8",
+      timeout: 60000,
+    });
+    if (r.status === 1) {
+      console.error("BLOCKED: anti-slop scan found CRITICAL design tells. Fix before deploying.");
+      const output = `${r.stdout || ""}${r.stderr || ""}`.trim();
+      if (output) {
+        const lines = output.split(/\r?\n/).filter(Boolean).slice(-20);
+        for (const line of lines) console.error(`  ${line}`);
+      }
+      _trace("pre-deploy-gate", "block", { gate: "slop", status: r.status });
+      process.exit(2);
+    }
+    console.log("  ✓ Anti-slop");
+  }
+}
+
 console.log("⬢ All gates passed.");
 
 _trace("pre-deploy-gate", "allow");

package/hooks/session-start.js

@@ -167,17 +167,37 @@ function maybeDrainErpQueue() {
   } catch {}
 }
 
+function cmpVersions(a, b) {
+  // Returns >0 if a>b, <0 if a<b, 0 if equal. Tolerates missing/non-numeric
+  // segments by treating them as 0. Pure semver-major.minor.patch compare.
+  const pa = String(a || "0").split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b || "0").split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
 function maybeRenderUpdateBanner() {
   // EMPLOYEE-only sticky banner. auto-update.js writes NOTIF_FILE when a new
   // version is detected; we render it every session until the user actually
-  // runs `npx qualia-framework@latest install`. The file is cleared by
-  // auto-update.js once the install completes or the version catches up.
+  // runs `npx qualia-framework@latest install`. auto-update.js clears the file
+  // when it next runs and finds the version caught up — but it is throttled, so
+  // between an install and that next run the notif can be stale. We therefore
+  // self-validate here against the installed version (.qualia-config.json) and
+  // clear+skip a stale notice rather than show a false "update available".
   if (!fs.existsSync(NOTIF_FILE) || !fs.existsSync(UI)) return;
   try {
     const notif = JSON.parse(fs.readFileSync(NOTIF_FILE, "utf8"));
-    if (notif && notif.current && notif.latest) {
-      runUi("update", notif.current, notif.latest);
+    if (!notif || !notif.current || !notif.latest) return;
+    const installed = readConfig().version;
+    if (installed && cmpVersions(installed, notif.latest) >= 0) {
+      // Already at or past the advertised latest — the notice is stale.
+      try { fs.unlinkSync(NOTIF_FILE); } catch {}
+      return;
     }
+    runUi("update", notif.current, notif.latest);
   } catch {}
 }
 

package/hooks/task-write-guard.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/task-write-guard.js — runtime enforcement of the plan
+// contract's declared file sets. PreToolUse hook on Edit/Write.
+// Exits 2 to BLOCK. Exits 0 to allow. Cross-platform (Windows/macOS/Linux).
+//
+// WHY: plan-contract.js proves file-disjointness across parallel tasks at PLAN
+// time, but nothing stops a builder writing outside its declared set at RUN
+// time — the documented #1 cause of cross-wave merge conflicts and AI entropy
+// (files nobody planned). This turns the static check into a deterministic
+// guardrail ("a rule worth enforcing is worth a hook" — constitution).
+//
+// SCOPE & HONEST LIMITATION: Claude Code fires the same stateless hook for
+// every subagent and gives it no task identity, so this hook cannot attribute a
+// write to a *specific* task. What it CAN enforce — and does — is that, while a
+// build is in flight, every Edit/Write targets a path DECLARED by SOME task in
+// the active phase contract (files_modify ∪ files_create). Plan-time
+// disjointness already guarantees no two tasks share a path, and the builder's
+// <wave_context> prompt tells it which set is its own; so the residual gap
+// ("T3 edits T4's declared file") is prompt-guarded while the high-frequency
+// vector ("builder invents/edits a file nobody planned") is hard-blocked.
+//
+// The guard is SCOPED: it is a no-op unless a build is active (≥1 RUNNING entry
+// in .agent-status/). Outside a build it never fires, so it can't interfere with
+// the orchestrator, the verifier, or ordinary editing. Fails OPEN on any error.
+
+const fs = require("fs");
+const path = require("path");
+
+const _traceStart = Date.now();
+
+// ── stdin reader (same robust pattern as the other guards) ──────────────
+function sleepSync(ms) {
+  try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch {}
+}
+function readInput() {
+  const deadline = Date.now() + 1000;
+  const buf = Buffer.alloc(65536);
+  let data = "";
+  try {
+    while (Date.now() < deadline) {
+      let n = 0;
+      try {
+        n = fs.readSync(0, buf, 0, buf.length, null);
+      } catch (e) {
+        if (e && (e.code === "EAGAIN" || e.code === "EWOULDBLOCK")) { sleepSync(1); continue; }
+        break;
+      }
+      if (n === 0) break;
+      data += buf.slice(0, n).toString("utf8");
+    }
+    if (!data) return {};
+    return JSON.parse(data);
+  } catch {
+    return {};
+  }
+}
+
+function _trace(result, extra) {
+  try {
+    const os = require("os");
+    const parent = path.basename(path.dirname(__dirname));
+    const qualiaHome = process.env.QUALIA_HOME ||
+      (parent === ".codex" || parent === ".claude" ? path.dirname(__dirname) : path.join(os.homedir(), ".claude"));
+    const traceDir = path.join(qualiaHome, ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = { hook: "task-write-guard", result, timestamp: new Date().toISOString(), duration_ms: Date.now() - _traceStart, ...extra };
+    fs.appendFileSync(path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`), JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
+function allow(reason, extra) { _trace("allow", { reason, ...extra }); process.exit(0); }
+
+// OWNER / debugging escape hatch, mirroring git-guardrails' QUALIA_ALLOW_*.
+if (process.env.QUALIA_ALLOW_OUTSIDE_CONTRACT === "1") allow("escape-hatch");
+
+const input = readInput();
+const ti = input.tool_input || {};
+const rawPath = String(ti.file_path || "");
+if (!rawPath) allow("no file_path");
+
+const root = process.cwd();
+
+// Reuse the status + contract libraries that ship alongside this hook (bin/ is a
+// sibling of hooks/ in both the repo and the installed layout). If they're not
+// resolvable (older/partial install), fail open.
+let agentStatus, planContract;
+try {
+  agentStatus = require(path.join(__dirname, "..", "bin", "agent-status.js"));
+  planContract = require(path.join(__dirname, "..", "bin", "plan-contract.js"));
+} catch {
+  allow("libs unavailable");
+}
+
+// SCOPE: only enforce during an active build (≥1 RUNNING agent-status entry).
+let running;
+try {
+  running = agentStatus.listStatuses(root).filter((s) => s.status === "RUNNING");
+} catch {
+  allow("status unreadable");
+}
+if (!running || running.length === 0) allow("no active build");
+
+// Locate the active phase contract. Prefer the phase declared by a RUNNING
+// builder; fall back to the sole phase-*-contract.json if unambiguous.
+function findContractPath() {
+  const phases = [...new Set(running.map((s) => s.phase).filter((p) => p != null))];
+  for (const p of phases) {
+    const cp = path.join(root, ".planning", `phase-${p}-contract.json`);
+    if (fs.existsSync(cp)) return cp;
+  }
+  try {
+    const dir = path.join(root, ".planning");
+    const matches = fs.readdirSync(dir).filter((f) => /^phase-\d+-contract\.json$/.test(f));
+    if (matches.length === 1) return path.join(dir, matches[0]);
+  } catch {}
+  return null;
+}
+
+const contractPath = findContractPath();
+if (!contractPath) allow("no active contract");
+
+let contract;
+try {
+  const loaded = planContract.readContractFile(contractPath);
+  if (!loaded.ok) allow("contract unreadable");
+  contract = loaded.contract;
+} catch {
+  allow("contract parse error");
+}
+
+// Build the union of writable declared paths across all tasks.
+// Edit/Write create or modify; deletes are out of band for this tool family.
+function norm(p) {
+  return String(p).replace(/\\/g, "/").replace(/^\.\//, "");
+}
+const declared = new Set();
+for (const t of contract.tasks || []) {
+  for (const f of t.files_modify || []) declared.add(norm(f));
+  for (const f of t.files_create || []) declared.add(norm(f));
+}
+
+// Resolve the target to a path relative to the project root.
+const abs = path.isAbsolute(rawPath) ? rawPath : path.resolve(root, rawPath);
+const rel = norm(path.relative(root, abs));
+
+// Out of project root → not this guard's concern (other guards handle secrets).
+if (rel.startsWith("../") || rel === "" || path.isAbsolute(rel)) allow("outside project root", { rel });
+
+// Framework scratch / planning artifacts are always writable during a build:
+// the status protocol, evidence, deviations, plan and contract files.
+if (rel.startsWith(".agent-status/") || rel.startsWith(".planning/")) allow("framework path", { rel });
+
+if (declared.has(rel)) allow("declared", { rel });
+
+// Not declared by any task → block.
+console.error("⬢ task-write-guard — write outside the plan contract:");
+console.error(`  ✗ ${rel}`);
+console.error("");
+console.error(`  No task in ${path.relative(root, contractPath)} declares this file`);
+console.error("  (files_modify / files_create). Builders may only write files");
+console.error("  their task planned. If this file is genuinely needed, add it to");
+console.error("  the contract via the locked-decision channel, or re-plan the phase.");
+console.error("  OWNER override: QUALIA_ALLOW_OUTSIDE_CONTRACT=1");
+_trace("block", { rel, contract: path.relative(root, contractPath) });
+process.exit(2);

package/hooks/usage-capture.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * UserPromptSubmit hook — per-session framework-usage capture.
+ *
+ * Records, into `.planning/.session-usage.json` of the active project:
+ *   - command_usage : a histogram of qualia slash-commands the engineer fired
+ *   - prompt_samples: the engineer's real prompts (opt-in), for the ERP
+ *                     prompt-quality judge
+ *
+ * `report-payload.js` folds both into the /qualia-report clock-out payload, and
+ * `/qualia-report` clears the file after a successful upload. This is what feeds
+ * the ERP performance audit's "framework usage & prompting" pillar (command
+ * volume + diversity, and LLM-judged prompt quality).
+ *
+ * Privacy: prompt capture is opt-in via `erp.capturePrompts` in
+ * ~/.claude/.qualia-config.json (default ON for the internal team; set to false
+ * to record command counts only). The file is a .planning dotfile and is
+ * deleted at clock-out — it must never be committed.
+ *
+ * Never blocks: any error exits 0 with no stdout (adds no context to the prompt).
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const MAX_SAMPLES = 60;
+const MAX_SAMPLE_LEN = 8000;
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function capturePromptsEnabled(home) {
+  const cfg =
+    readJson(path.join(home, '.claude', '.qualia-config.json'), null) ||
+    readJson(path.join(home, '.codex', '.qualia-config.json'), {});
+  return !cfg || !cfg.erp || cfg.erp.capturePrompts !== false;
+}
+
+function main() {
+  let raw = '';
+  try {
+    raw = fs.readFileSync(0, 'utf8');
+  } catch {
+    process.exit(0);
+  }
+  let input = {};
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  const prompt = typeof input.prompt === 'string' ? input.prompt : '';
+  const cwd = input.cwd || input.cwd_path || process.cwd();
+  if (!prompt.trim()) process.exit(0);
+
+  // Only record inside a Qualia project (has .planning/).
+  const planningDir = path.join(cwd, '.planning');
+  if (!fs.existsSync(planningDir)) process.exit(0);
+
+  const usageFile = path.join(planningDir, '.session-usage.json');
+  const usage = readJson(usageFile, { command_usage: {}, prompt_samples: [] });
+  if (!usage.command_usage || typeof usage.command_usage !== 'object') usage.command_usage = {};
+  if (!Array.isArray(usage.prompt_samples)) usage.prompt_samples = [];
+
+  // Count a qualia slash-command if one appears as a token in the prompt.
+  const m = prompt.match(/(?:^|\s)\/(qualia[a-z0-9-]*)/i);
+  if (m) {
+    const cmd = m[1].toLowerCase();
+    usage.command_usage[cmd] = (usage.command_usage[cmd] || 0) + 1;
+  }
+
+  // Sample the real prompt for the prompt-quality judge (opt-in, disclosed).
+  if (capturePromptsEnabled(os.homedir())) {
+    // Transparency: tell the engineer once per shift that prompts are recorded
+    // and how to turn it off. stderr so it's seen but never enters model
+    // context. The flag rides in the usage file, which is cleared at clock-out,
+    // so the notice reappears each new shift. Best-effort — never blocks.
+    if (!usage.notice_shown) {
+      try {
+        process.stderr.write(
+          '\x1b[38;2;80;90;100m[qualia] This session records your /qualia command usage and ' +
+          'prompt samples for the team performance audit. Opt out anytime: set ' +
+          'erp.capturePrompts=false in ~/.claude/.qualia-config.json\x1b[0m\n'
+        );
+      } catch { /* never block the prompt */ }
+      usage.notice_shown = true;
+    }
+    usage.prompt_samples.push(prompt.trim().slice(0, MAX_SAMPLE_LEN));
+    if (usage.prompt_samples.length > MAX_SAMPLES) {
+      usage.prompt_samples = usage.prompt_samples.slice(-MAX_SAMPLES);
+    }
+  }
+
+  try {
+    fs.writeFileSync(usageFile, JSON.stringify(usage));
+  } catch {
+    /* best-effort; never block the prompt */
+  }
+  process.exit(0);
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "6.9.0",
+  "version": "6.14.0",
   "description": "Claude Code and Codex workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -52,6 +52,7 @@
     "docs/release.md",
     "docs/changelog-v6.html",
     "docs/onboarding.html",
+    "docs/qualia-manual.html",
     "docs/EMPLOYEE-QUICKSTART.md",
     "CLAUDE.md",
     "AGENTS.md",