qualia-framework 7.2.1 → 7.3.0

package/bin/verify-panel.js

@@ -26,6 +26,7 @@
 
 const fs = require("fs");
 const path = require("path");
+const { spawnSync } = require("child_process");
 
 const SEVERITY_WEIGHT = { CRITICAL: 8, HIGH: 4, MEDIUM: 2, LOW: 1 };
 const SEVERITY_RANK = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1 };
@@ -133,6 +134,115 @@ function aggregate(panel) {
   };
 }
 
+// ── gate recorder + verdict aggregator (machine-JSON gate fold) ─────────────
+// WHY: the verdict was an LLM reading prose ("phase is PASS only if ALL of these
+// agree…") and ANDing exit codes by hand — non-deterministic, and a dropped exit
+// code silently flips a CRITICAL. This makes the COMBINE deterministic without
+// changing what blocks: each gate's EXISTING block condition (the exit code it
+// already returns) is captured MECHANICALLY into one normalized artifact, and a
+// single `verdict {N}` call folds those gates + the panel into one PASS/FAIL with
+// the SAME severity weighting aggregate() already uses. No new blocking — the
+// aggregator only makes the existing AND deterministic.
+
+// Normalized gate-result artifact, sibling to phase-{N}-panel-{lens}.json:
+//   .planning/phase-{N}-gate-{name}.json
+//   = { gate, severity, blocking, findings: [{file,line,severity,title}] }
+// blocking=true means a surviving finding from this gate flips the verdict; the
+// findings array reuses the exact {file,line,severity,title} shape assemble()
+// consumes, so the gate folds into the panel with zero special-casing.
+
+// Each gate's EXISTING block condition → the severity the recorder stamps when
+// the gate signals a fault. This map is the LOCKED, ratifiable default (ADR-0002):
+//   - dep-verify    : exit 1 = a hallucinated/slopsquatted import → CRITICAL,
+//                     blocking. Auto-survives (no skeptic — a hallucinated import
+//                     is not refutable), so this gate ships NO votes.
+//   - slop-detect   : run as --severity=critical, so exit 1 = CRITICAL slop only
+//                     → CRITICAL, blocking. (HIGH/MEDIUM slop never reaches here.)
+//   - harness-eval  : a hard FAIL → CRITICAL, blocking. A soft/advisory sub-check
+//                     is recorded MEDIUM, NON-blocking (use --severity MEDIUM).
+//   - qualia-eval   : a suite FAIL → one CRITICAL per failing SUITE (the caller
+//                     records one gate artifact per failing suite, name=eval-<suite>).
+// A gate not in the map records as CRITICAL/blocking on non-zero (conservative).
+const GATE_DEFAULTS = {
+  "dep-verify":  { severity: "CRITICAL", blocking: true,  skeptic: false },
+  "slop-detect": { severity: "CRITICAL", blocking: true,  skeptic: false },
+  "harness-eval":{ severity: "CRITICAL", blocking: true,  skeptic: false },
+  "qualia-eval": { severity: "CRITICAL", blocking: true,  skeptic: false },
+};
+
+function gatePath(root, phase, name) {
+  return path.join(root, ".planning", `phase-${phase}-gate-${name}.json`);
+}
+
+// Record one gate's result from its REAL exit code. Non-zero exit = the gate's
+// block condition fired → one finding at the mapped (or overridden) severity.
+// Exit 0 = clean → empty findings (recorded, visible, non-blocking). The artifact
+// is written from the exit code mechanically — never an LLM hand-writing JSON.
+function recordGate(root, phase, name, exitCode, opts = {}) {
+  const def = GATE_DEFAULTS[name] || { severity: "CRITICAL", blocking: true };
+  const code = Number(exitCode);
+  const failed = !(Number.isFinite(code) && code === 0);
+  // --severity overrides the default (e.g. harness-eval soft sub-check → MEDIUM,
+  // which a non-blocking gate records but does not let flip the verdict).
+  const severity = normSeverity(opts.severity || def.severity);
+  // A non-CRITICAL/HIGH override is inherently non-blocking — a MEDIUM/LOW gate
+  // finding never flips the C/H verdict the aggregator gates on. Keep blocking
+  // true only when the severity can actually block, so the artifact is honest.
+  const canBlock = severity === "CRITICAL" || severity === "HIGH";
+  const blocking = (opts.blocking != null ? opts.blocking : def.blocking) && canBlock;
+  const title = opts.title ||
+    `${name} gate failed (exit ${Number.isFinite(code) ? code : "?"})`;
+  const findings = failed
+    ? [{ file: opts.file || `gate:${name}`, line: opts.line != null ? opts.line : null, severity, title }]
+    : [];
+  const artifact = { gate: name, severity, blocking, findings };
+  const out = gatePath(root, phase, name);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, JSON.stringify(artifact, null, 2) + "\n");
+  return { out: path.relative(root, out), artifact, failed };
+}
+
+// Glob the normalized gate artifacts for a phase. Each becomes a pseudo-lens
+// ("gate:<name>") whose findings carry the gate's severity. Non-blocking gates
+// still surface their findings (visible) but their findings are recorded at a
+// severity that cannot flip the verdict — honesty without regression.
+function assembleGates(root, phase) {
+  const dir = path.join(root, ".planning");
+  const re = new RegExp(`^phase-${phase}-gate-([a-z0-9-]+)\\.json$`);
+  const lenses = [];
+  const findings = [];
+  let files = [];
+  try { files = fs.readdirSync(dir); } catch { files = []; }
+  for (const f of files.sort()) {
+    const m = f.match(re);
+    if (!m) continue;
+    const name = m[1];
+    let g;
+    try { g = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8")); } catch { continue; }
+    if (!g || !Array.isArray(g.findings)) continue;
+    const lens = `gate:${name}`;
+    lenses.push(lens);
+    const blocking = g.blocking !== false;
+    for (const item of g.findings) {
+      // A non-blocking gate's findings are demoted to MEDIUM so the deterministic
+      // aggregate() (which fails only on surviving CRITICAL/HIGH) records them
+      // without ever flipping the verdict — the no-regression guarantee in code.
+      const sev = blocking ? normSeverity(item.severity || g.severity) : "MEDIUM";
+      findings.push({
+        lens,
+        file: item.file || `gate:${name}`,
+        line: item.line != null ? item.line : null,
+        severity: sev,
+        title: item.title || `${name} gate finding`,
+        // dep-verify/slop-detect gates auto-survive (no skeptic). Stamp a single
+        // real vote so a surviving CRITICAL is never mistaken for "unverified".
+        votes: { real: 1, notReal: 0 },
+      });
+    }
+  }
+  return { lenses, findings };
+}
+
 // ── CLI ───────────────────────────────────────────────────────────────────
 function parseArgs(argv) {
   const args = { _: [] };
@@ -142,6 +252,14 @@ function parseArgs(argv) {
     else if (a === "--write") args.write = true;
     else if (a === "--cwd") args.cwd = argv[++i];
     else if (a.startsWith("--cwd=")) args.cwd = a.slice(6);
+    else if (a === "--exit") args.exit = argv[++i];
+    else if (a.startsWith("--exit=")) args.exit = a.slice(7);
+    else if (a === "--severity") args.severity = argv[++i];
+    else if (a.startsWith("--severity=")) args.severity = a.slice(11);
+    else if (a === "--title") args.title = argv[++i];
+    else if (a.startsWith("--title=")) args.title = a.slice(8);
+    else if (a === "--blocking") args.blocking = argv[++i];
+    else if (a.startsWith("--blocking=")) args.blocking = a.slice(11);
     else args._.push(a);
   }
   return args;
@@ -219,7 +337,289 @@ function assemble(root, phase) {
   return { phase: Number(phase), lenses, findings };
 }
 
+// ── execution lens ──────────────────────────────────────────────────────────
+// EXECUTION-GROUNDED verify: a grep proves a symbol EXISTS; it does not prove the
+// feature RUNS. A builder can satisfy a grep pattern (exported name, string
+// match) while the project doesn't compile or its tests fail — the dominant
+// reward-hacking failure mode. This lens runs the project's OWN checks and writes
+// findings in the same {file,line,severity,title} shape assemble() consumes, so a
+// red build folds into the verdict as a CRITICAL the panel cannot grep around.
+//
+// Fail-soft vs fail-closed: a check whose tool is ABSENT (no tsconfig, no test
+// script) is SKIPPED — its absence is not evidence of breakage. A check that is
+// PRESENT but exits non-zero is a CRITICAL finding — present-and-red is real,
+// hard evidence the goal isn't achieved. Same discipline as the constitution's
+// gates: absent ⇒ inert, present-and-failing ⇒ block.
+
+// One project check: a label, whether it applies to this repo, and the argv to
+// run. `applies` keeps an absent tool from ever becoming a FAIL.
+function executionChecks(root) {
+  const has = (p) => fs.existsSync(path.join(root, p));
+  let pkg = {};
+  try { pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")); } catch { pkg = {}; }
+  const scripts = (pkg && pkg.scripts) || {};
+  return [
+    {
+      name: "typecheck",
+      title: "npx tsc --noEmit failed — project does not type-check",
+      applies: has("tsconfig.json"),
+      cmd: "npx",
+      args: ["tsc", "--noEmit"],
+    },
+    {
+      name: "test",
+      title: "npm test failed — the project's own test suite is red",
+      applies: typeof scripts.test === "string" && scripts.test.trim() !== "" &&
+        !/no test specified/i.test(scripts.test),
+      cmd: "npm",
+      args: ["test", "--silent"],
+    },
+    {
+      name: "build",
+      title: "npm run build failed — the project does not build",
+      applies: typeof scripts.build === "string" && scripts.build.trim() !== "",
+      cmd: "npm",
+      args: ["run", "build", "--silent"],
+    },
+  ];
+}
+
+// Run the applicable checks and return panel findings (CRITICAL per non-zero
+// check) plus a per-check status report. Absent tool ⇒ SKIPPED (no finding);
+// present + exit 0 ⇒ PASS (no finding); present + non-zero ⇒ CRITICAL finding.
+// Spawn errors (tool missing on PATH, e.g. no npx) are treated as SKIPPED, not
+// FAIL — fail-soft: we only fail-closed on a check we could actually run.
+function runExecution(root, opts = {}) {
+  const timeout = opts.timeout_ms || 300_000;
+  const findings = [];
+  const report = [];
+  for (const c of executionChecks(root)) {
+    if (!c.applies) { report.push({ name: c.name, status: "SKIPPED" }); continue; }
+    const r = spawnSync(c.cmd, c.args, {
+      cwd: root,
+      encoding: "utf8",
+      timeout,
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: false,
+    });
+    if (r.error) {
+      // Could not even launch the tool (ENOENT, etc.) — absent, not broken.
+      report.push({ name: c.name, status: "SKIPPED", detail: r.error.message });
+      continue;
+    }
+    const status = typeof r.status === "number" ? r.status : 1;
+    if (status === 0) { report.push({ name: c.name, status: "PASS" }); continue; }
+    const tail = (r.stderr || r.stdout || "").trim().split(/\r?\n/).slice(-3).join(" / ").slice(-300);
+    report.push({ name: c.name, status: "FAIL", exit: status, tail });
+    findings.push({
+      file: "package.json",
+      line: null,
+      severity: "CRITICAL",
+      title: `${c.title}${tail ? ` (exit ${status}: ${tail})` : ` (exit ${status})`}`,
+    });
+  }
+  return { findings, report };
+}
+
+// Write the execution lens's findings to phase-{N}-panel-execution.json — the
+// SAME path+shape assemble() globs, so the execution lens folds into the panel
+// with zero special-casing. Empty array when every check passed or was skipped.
+function writeExecutionPanel(root, phase, opts = {}) {
+  const { findings, report } = runExecution(root, opts);
+  const dir = path.join(root, ".planning");
+  const out = path.join(dir, `phase-${phase}-panel-execution.json`);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(out, JSON.stringify(findings, null, 2) + "\n");
+  return { out: path.relative(root, out), findings, report };
+}
+
+// Tally skeptic reply lines into vote counts. One verdict per line: a line is
+// a REAL vote if it starts with "REAL", a NOT_REAL vote if it starts with
+// "NOT_REAL" (checked first so "NOT_REAL" isn't read as "REAL"). Blank lines
+// and anything that isn't a verdict are ignored — the orchestrator pipes the
+// skeptics' one-line replies straight in, so stray prose never miscounts.
+// Pure function of its input ⇒ same lines → same counts (the determinism the
+// panel exists to provide; no LLM hand-tally between the votes and the verdict).
+function tallySkepticVotes(text) {
+  const votes = { real: 0, notReal: 0 };
+  for (const raw of String(text || "").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (/^NOT[_\s]?REAL\b/i.test(line)) votes.notReal++;
+    else if (/^REAL\b/i.test(line)) votes.real++;
+  }
+  return votes;
+}
+
+// Write the tallied votes onto the finding whose findingKey() matches `key`
+// in the assembled panel.json. Reuses the same read/write + key conventions as
+// dedupeFindings/assemble so the count the verdict sees is mechanical, not a
+// hand-edit the orchestrator could miscount.
+function writeSkepticVotes(root, phase, key, text) {
+  const panelPath = path.join(root, ".planning", `phase-${phase}-panel.json`);
+  let panel;
+  try {
+    panel = JSON.parse(fs.readFileSync(panelPath, "utf8"));
+  } catch (e) {
+    return { ok: false, error: `cannot read ${panelPath}: ${e.message}` };
+  }
+  const findings = Array.isArray(panel.findings) ? panel.findings : [];
+  const match = findings.find((f) => findingKey(f) === key);
+  if (!match) {
+    return { ok: false, error: `no finding matches key "${key}" in ${panelPath}`, keys: findings.map(findingKey) };
+  }
+  const votes = tallySkepticVotes(text);
+  match.votes = votes;
+  try {
+    fs.writeFileSync(panelPath, JSON.stringify(panel, null, 2) + "\n");
+  } catch (e) {
+    return { ok: false, error: `cannot write ${panelPath}: ${e.message}` };
+  }
+  return { ok: true, key, votes, path: panelPath };
+}
+
 function main(argv) {
+  // skeptic subcommand: verify-panel.js skeptic <phase> <finding-key> [replies-file] [--cwd DIR]
+  // Reads skeptic reply lines (one REAL/NOT_REAL per line) from the file arg or
+  // stdin, tallies them deterministically, and writes votes.real/votes.notReal
+  // onto the matching finding in .planning/phase-{N}-panel.json.
+  if (argv[2] === "skeptic") {
+    const sub = parseArgs(["", "", ...argv.slice(3)]);
+    const phase = sub._[0];
+    const key = sub._[1];
+    const repliesFile = sub._[2];
+    if (phase == null || key == null) { usage(); return 2; }
+    const root = path.resolve(sub.cwd || process.cwd());
+    let text;
+    try {
+      text = repliesFile ? fs.readFileSync(repliesFile, "utf8") : fs.readFileSync(0, "utf8");
+    } catch (e) {
+      console.error(`ERROR: cannot read skeptic replies: ${e.message}`);
+      return 2;
+    }
+    const res = writeSkepticVotes(root, phase, key, text);
+    if (!res.ok) {
+      console.error(`ERROR: ${res.error}`);
+      if (res.keys) console.error(`  available keys: ${res.keys.join(", ") || "(none)"}`);
+      return 2;
+    }
+    console.log(`tallied ${res.votes.real}✓/${res.votes.notReal}✗ → ${key} in ${path.relative(root, res.path)}`);
+    return 0;
+  }
+
+  // execution subcommand: verify-panel.js execution <phase> [--cwd DIR]
+  // Runs the project's own checks (tsc / test / build) and writes
+  // .planning/phase-{N}-panel-execution.json in assemble()'s shape. Exit code
+  // mirrors the result for shell callers: 1 if any present check failed (a
+  // CRITICAL was recorded), 0 otherwise (all passed or skipped). The written
+  // panel file is the authoritative artifact; the exit code is a convenience.
+  if (argv[2] === "execution") {
+    const sub = parseArgs(["", "", ...argv.slice(3)]);
+    const phase = sub._[0];
+    if (phase == null) { usage(); return 2; }
+    const root = path.resolve(sub.cwd || process.cwd());
+    let res;
+    try {
+      res = writeExecutionPanel(root, phase, {});
+    } catch (e) {
+      console.error(`ERROR: execution lens failed: ${e.message}`);
+      return 2;
+    }
+    const summary = res.report.map((r) => `${r.name}:${r.status}`).join(" · ") || "(no checks)";
+    console.log(`execution lens → ${res.out} — ${summary}` +
+      (res.findings.length ? ` — ${res.findings.length} CRITICAL` : ""));
+    return res.findings.length ? 1 : 0;
+  }
+
+  // gate subcommand: verify-panel.js gate <phase> <name> --exit <code> [--severity S] [--title T] [--cwd DIR]
+  // Deterministic recorder: writes phase-{N}-gate-{name}.json from a gate's REAL
+  // exit code, never an LLM hand-writing JSON. Non-zero exit → one finding at the
+  // mapped (or --severity-overridden) severity; exit 0 → clean (empty findings).
+  // This is how exit-code-only gates (slop-detect, dep-verify) get captured
+  // MECHANICALLY into the same artifact verdict folds in.
+  if (argv[2] === "gate") {
+    const sub = parseArgs(["", "", ...argv.slice(3)]);
+    const phase = sub._[0];
+    const name = sub._[1];
+    if (phase == null || name == null || sub.exit == null) {
+      console.error("Usage: verify-panel.js gate <phase> <name> --exit <code> [--severity S] [--title T]");
+      return 2;
+    }
+    const root = path.resolve(sub.cwd || process.cwd());
+    let res;
+    try {
+      res = recordGate(root, phase, name, sub.exit, {
+        severity: sub.severity,
+        title: sub.title,
+        blocking: sub.blocking != null ? sub.blocking !== "false" : null,
+      });
+    } catch (e) {
+      console.error(`ERROR: cannot record gate: ${e.message}`);
+      return 2;
+    }
+    console.log(`gate ${name} → ${res.out} — ${res.failed ? `${res.artifact.severity} (exit ${sub.exit})` : "clean"}`);
+    return 0;
+  }
+
+  // verdict subcommand: verify-panel.js verdict <phase> [--json] [--write] [--cwd DIR]
+  // THE single deterministic fold. Globs phase-{N}-panel-{lens}.json (existing
+  // panel + skeptic survival via assemble/survives) AND phase-{N}-gate-{name}.json
+  // (the recorded machine gates) into ONE panel, then runs the SAME aggregate()
+  // severity weighting → one PASS/FAIL. Replaces the orchestrator-LLM prose AND.
+  // Exit 0 = PASS, 1 = FAIL. Same artifacts → same verdict.
+  if (argv[2] === "verdict") {
+    const sub = parseArgs(["", "", ...argv.slice(3)]);
+    const phase = sub._[0];
+    if (phase == null) { usage(); return 2; }
+    const root = path.resolve(sub.cwd || process.cwd());
+
+    // Prefer the skeptic-voted panel.json if the skill already assembled+voted it;
+    // otherwise assemble fresh from the per-lens files. Either way the votes the
+    // skeptics wrote (writeSkepticVotes) are honored — verdict never re-runs them.
+    const panelPath = path.join(root, ".planning", `phase-${phase}-panel.json`);
+    let panel;
+    try {
+      panel = JSON.parse(fs.readFileSync(panelPath, "utf8"));
+    } catch {
+      panel = assemble(root, phase);
+    }
+    if (!panel || !Array.isArray(panel.findings)) panel = { phase: Number(phase), lenses: [], findings: [] };
+
+    const gates = assembleGates(root, phase);
+    const merged = {
+      phase: panel.phase != null ? panel.phase : Number(phase),
+      lenses: [...(panel.lenses || []), ...gates.lenses],
+      findings: [...(panel.findings || []), ...gates.findings],
+    };
+    const result = aggregate(merged);
+
+    if (sub.write && result.phase != null) {
+      const dir = path.join(root, ".planning");
+      try {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, `phase-${result.phase}-verdict.json`), JSON.stringify(result, null, 2) + "\n");
+        fs.writeFileSync(path.join(dir, `phase-${result.phase}-verdict.md`), toMarkdown(result));
+      } catch (e) {
+        console.error(`WARN: could not write verdict artifacts: ${e.message}`);
+      }
+    }
+
+    if (sub.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`VERDICT ${result.verdict} phase ${result.phase}: ` +
+        `${result.totals.surviving} surviving (${result.counts.CRITICAL}C/${result.counts.HIGH}H/${result.counts.MEDIUM}M/${result.counts.LOW}L), ` +
+        `${result.totals.killed} killed, score ${result.score}/5 ` +
+        `[${merged.lenses.length} lens/gate inputs]`);
+      if (!result.ok) for (const f of result.surviving) {
+        if (f.severity === "CRITICAL" || f.severity === "HIGH") {
+          console.log(`  [${f.severity}] ${f.title} — ${f.file || "?"}${f.line != null ? `:${f.line}` : ""} (${f.lenses.join(", ") || "?"})`);
+        }
+      }
+    }
+    return result.ok ? 0 : 1;
+  }
+
   // assemble subcommand: verify-panel.js assemble <phase> [--cwd DIR]
   if (argv[2] === "assemble") {
     const sub = parseArgs(["", "", ...argv.slice(3)]);
@@ -286,6 +686,15 @@ module.exports = {
   scoreFromCounts,
   aggregate,
   assemble,
+  executionChecks,
+  runExecution,
+  writeExecutionPanel,
+  tallySkepticVotes,
+  writeSkepticVotes,
+  recordGate,
+  assembleGates,
+  findingKey,
+  GATE_DEFAULTS,
   SEVERITY_WEIGHT,
 };
 

package/docs/onboarding.html

@@ -602,7 +602,7 @@
   </section>
 
   <footer>
-    <span>Qualia Framework v6.2.7 · Plan, build, verify, ship.</span>
+    <span>Qualia Framework v7.3.0 · Plan, build, verify, ship.</span>
     <span><a href="https://github.com/Qualiasolutions/qualia-framework">github.com/Qualiasolutions/qualia-framework</a></span>
   </footer>
 

package/hooks/branch-guard.js

@@ -130,16 +130,30 @@ function notify(event, branch) {
 }
 
 // ── role ────────────────────────────────────────────────────────────────────
+// Role-resolution failures are FAIL-LOUD but non-blocking: a missing config or
+// an unknown role means accountability silently degrades, so we emit a one-line
+// STDERR diagnostic to make it visible — but we never block (this hook must not
+// crash a session on its own error). KNOWN_ROLES is the set we can classify.
+const KNOWN_ROLES = ["OWNER", "EMPLOYEE"];
+function roleUnresolved(reason) {
+  console.error(`branch-guard: role unresolved (${reason}) — proceeding unenforced`);
+  _trace("allow", { reason: `role unresolved: ${reason}` });
+  process.exit(0);
+}
+
 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);
+  // Can't classify without config — visible, but the hook no longer blocks.
+  roleUnresolved("config missing/unreadable");
 }
 const role = (config.role || "").toUpperCase();
+if (!KNOWN_ROLES.includes(role)) {
+  // Empty / unknown role — resolution failed. Surface it, then allow.
+  roleUnresolved(role ? `unknown role '${role}'` : "empty role");
+}
 
-// OWNER pushes to main are normal and unremarkable. Anything that isn't a known
-// EMPLOYEE is also left alone (nothing to attribute).
+// OWNER pushes to main are normal and unremarkable. A resolved non-EMPLOYEE
+// (OWNER) is left alone silently (nothing to attribute).
 if (role !== "EMPLOYEE") {
   _trace("allow", { role });
   process.exit(0);

package/hooks/fawzi-approval-guard.js

@@ -129,9 +129,22 @@ function enqueueErp(config, event) {
 }
 
 try {
-  const config = readJson(CONFIG, {});
-  if ((config.role || "").toUpperCase() === "OWNER") process.exit(0);
-  if ((config.role || "").toUpperCase() !== "EMPLOYEE") process.exit(0);
+  // Role-resolution failures are FAIL-LOUD but non-blocking: a missing config or
+  // an unknown role means this accountability hook silently goes dark, so emit a
+  // one-line STDERR diagnostic to make it visible — but never block (this hook
+  // must not crash a session on its own error).
+  const config = readJson(CONFIG, null);
+  if (!config) {
+    console.error("fawzi-approval-guard: role unresolved (config missing/unreadable) — proceeding unenforced");
+    process.exit(0);
+  }
+  const role = (config.role || "").toUpperCase();
+  if (role === "OWNER") process.exit(0);
+  if (role !== "EMPLOYEE") {
+    // Empty / unknown role — resolution failed. Surface it, then allow.
+    console.error(`fawzi-approval-guard: role unresolved (${role ? `unknown role '${role}'` : "empty role"}) — proceeding unenforced`);
+    process.exit(0);
+  }
 
   const sample = approvalClaim(hookInputText());
   if (!sample) process.exit(0);

package/hooks/hooks.json

@@ -0,0 +1,60 @@
+{
+  "SessionStart": [
+    {
+      "matcher": ".*",
+      "hooks": [
+        { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.js\"", "timeout": 5 }
+      ]
+    }
+  ],
+  "PreToolUse": [
+    {
+      "matcher": "Bash",
+      "hooks": [
+        { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/auto-update.js\"", "timeout": 5 },
+        { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/git-guardrails.js\"", "timeout": 5, "statusMessage": "⬢ Checking git safety..." },
+        { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/fawzi-approval-guard.js\"", "timeout": 5 },
+        { "type": "command", "if": "Bash(git push*)", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/branch-guard.js\"", "timeout": 5, "statusMessage": "⬢ Recording branch activity..." },
+        { "type": "command", "if": "Bash(git push*)", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/pre-push.js\"", "timeout": 15, "statusMessage": "⬢ Syncing tracking..." },
+        { "type": "command", "if": "Bash(vercel --prod*)", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/pre-deploy-gate.js\"", "timeout": 600, "statusMessage": "⬢ Running quality gates..." },
+        { "type": "command", "if": "Bash(vercel --prod*)|Bash(vercel deploy*)", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/vercel-account-guard.js\"", "timeout": 8, "statusMessage": "⬢ Verifying Vercel account..." },
+        { "type": "command", "if": "Bash(vercel env*)", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/env-empty-guard.js\"", "timeout": 5, "statusMessage": "⬢ Checking env value..." },
+        { "type": "command", "if": "Bash(supabase*)|Bash(npx supabase*)", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/supabase-destructive-guard.js\"", "timeout": 5, "statusMessage": "⬢ Checking Supabase safety..." },
+        { "type": "command", "if": "Bash(*psql*)|Bash(*.sql*)|Bash(supabase db execute*)|Bash(supabase db push*)|Bash(npx supabase db execute*)|Bash(npx supabase db push*)", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/migration-guard.js\"", "timeout": 10, "statusMessage": "⬢ Checking migration safety..." },
+        { "type": "command", "if": "Bash(git commit*)", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/secret-guard.js\"", "timeout": 10, "statusMessage": "⬢ Scanning staged content for secrets..." }
+      ]
+    },
+    {
+      "matcher": "Edit|Write",
+      "hooks": [
+        { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/fawzi-approval-guard.js\"", "timeout": 5 },
+        { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/task-write-guard.js\"", "timeout": 5, "statusMessage": "⬢ Checking plan-contract file scope..." },
+        { "type": "command", "if": "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/migration-guard.js\"", "timeout": 10, "statusMessage": "⬢ Checking migration safety..." }
+      ]
+    }
+  ],
+  "PreCompact": [
+    {
+      "matcher": ".*",
+      "hooks": [
+        { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/pre-compact.js\"", "timeout": 10 }
+      ]
+    }
+  ],
+  "Stop": [
+    {
+      "matcher": ".*",
+      "hooks": [
+        { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/stop-session-log.js\"", "timeout": 5 }
+      ]
+    }
+  ],
+  "UserPromptSubmit": [
+    {
+      "matcher": ".*",
+      "hooks": [
+        { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/usage-capture.js\"", "timeout": 5 }
+      ]
+    }
+  ]
+}