qualia-framework 6.9.2 → 6.14.0

package/docs/erp-contract.md

@@ -54,6 +54,29 @@ employee's active session, such as proxy owner-approval claims ("Fawzi said OK")
 The ERP should increment or store by `(type, actor_code)` so Fawzi can see how
 many times each employee attempted to use proxy approval.
 
+**Event types posted to this endpoint:**
+
+| `type` | Posted by | Meaning |
+|---|---|---|
+| `proxy_owner_approval_claim` | `fawzi-approval-guard` | An EMPLOYEE used "Fawzi said OK"-style proxy approval. Has a `sample` field. |
+| `employee_main_push` | `branch-guard` (v6.10+) | An EMPLOYEE pushed to a protected branch (`main`/`master`). Pushing is **allowed**, not blocked — this event is the accountability record. Has a `branch` field instead of `sample`. |
+
+`employee_main_push` body (same envelope, `branch` replaces `sample`):
+```json
+{
+  "type": "employee_main_push",
+  "actor_code": "QS-HASAN-02",
+  "actor_name": "Hasan",
+  "actor_role": "EMPLOYEE",
+  "count": 4,
+  "branch": "main",
+  "project": "client-project",
+  "cwd": "/path/to/client-project",
+  "recorded_at": "2026-06-20T10:00:00.000Z"
+}
+```
+Store by `(type, actor_code)` the same way so Fawzi sees a per-employee main-push tally. `client_report_id` is `QS-MAINPUSH-<actor_code>-<count>` and each post carries an idempotency key.
+
 ### POST /api/v1/reports
 
 Upload a session report.

package/docs/qualia-manual.html

@@ -187,7 +187,7 @@ footer{margin-top:80px;padding-top:24px;border-top:1px solid var(--border);color
     <p class="sec-sub">Qualia is an opinionated workflow that lives inside Claude Code (and Codex). It ships a lifecycle of <code>/qualia-*</code> slash commands, plus the guardrails (hooks, rules, and a shared brain) that keep every project consistent and safe.</p>
     <div class="grid g3">
       <div class="panel"><h3>🧭 It routes you</h3><p class="dim">Never wonder what's next. <code>/qualia</code> reads your project's state and hands you the exact next command. The framework keeps the map; you keep moving.</p></div>
-      <div class="panel"><h3>🛟 It guards you</h3><p class="dim">Deterministic hooks block the dangerous stuff (pushing to <code>main</code>, leaking secrets, destructive DB ops) before it happens. Rules aren't suggestions; they're enforced.</p></div>
+      <div class="panel"><h3>🛟 It guards you</h3><p class="dim">Deterministic hooks block the dangerous stuff (leaking secrets, destructive DB ops, force-pushing) before it happens, and record the risky-but-allowed stuff (pushing to <code>main</code>) for the owner. Rules aren't suggestions; they're enforced.</p></div>
       <div class="panel"><h3>🧠 It remembers</h3><p class="dim">Lessons from every project flow into a shared knowledge base. A fix one person discovered shows up in everyone's install, so the team gets smarter over time.</p></div>
     </div>
     <div class="note teal"><b>The one-line mental model:</b> you describe <em>what</em> you want; the framework owns <em>how</em> Qualia builds it: the stack, the phases, the quality bar, the deploy steps.</div>
@@ -216,7 +216,7 @@ footer{margin-top:80px;padding-top:24px;border-top:1px solid var(--border);color
   <!-- INSTALL -->
   <section id="install" class="reveal">
     <h2><span class="bar"></span> Install in employee mode</h2>
-    <p class="sec-sub">You can install and do real work <b>today</b>, with no credentials. Employee mode gives you the full framework at the safest privilege level: feature branches only, no pushes to <code>main</code>.</p>
+    <p class="sec-sub">You can install and do real work <b>today</b>, with no credentials. Employee mode gives you the full framework at the safest privilege level. Feature branches are the norm; pushing to <code>main</code> is allowed but recorded for the owner.</p>
     <pre><span class="c"># one command, works on a fresh machine</span>
 npx qualia-framework@latest install</pre>
     <p>At the prompt <code>Install code or "EMPLOYEE":</code></p>
@@ -225,7 +225,7 @@ npx qualia-framework@latest install</pre>
       <tr><td>Have a team code</td><td><code>QS-NAME-##</code></td><td>Install as that team member (ERP reporting on, with the key)</td></tr>
       <tr><td>Have no code yet</td><td><code>EMPLOYEE</code></td><td>Full framework, EMPLOYEE role, ERP reporting off until a code is set</td></tr>
     </table>
-    <div class="note"><b>Nothing is missing in employee mode.</b> Skills, agents, hooks, and knowledge are installed identically. The only differences: you can't push to <code>main</code> (the <code>branch-guard</code> hook blocks it), and <code>/qualia-report</code> saves a <em>local</em> report instead of uploading to the ERP. Ask Fawzi for a <code>QS-NAME-##</code> code when you're ready to upgrade.</div>
+    <div class="note"><b>Nothing is missing in employee mode.</b> Skills, agents, hooks, and knowledge are installed identically. The only differences: pushing to <code>main</code> is recorded for the owner (the <code>branch-guard</code> hook counts each one to the ERP) rather than free, and <code>/qualia-report</code> saves a <em>local</em> report instead of uploading to the ERP. Ask Fawzi for a <code>QS-NAME-##</code> code when you're ready to upgrade.</div>
     <h3>Then confirm it's healthy</h3>
     <p>Run the doctor before real work. It checks the install, hooks, project state, and the ERP queue, and prints PASS/FAIL with the exact fix for anything wrong.</p>
     <p><span class="cmd" data-copy="/qualia-doctor">/qualia-doctor<span class="ico">copy</span></span> <span class="dim">in employee mode it reports ERP as disabled; that's expected, not an error.</span></p>
@@ -294,7 +294,7 @@ npx qualia-framework@latest install</pre>
       </div></div>
       <div class="w"><span class="wn"></span><div class="wbody">
         <h4>Ship it</h4>
-        <p class="dim"><span class="cmd" data-copy="/qualia-ship">/qualia-ship<span class="ico">copy</span></span>: gates, commit, deploy to Vercel, verify live. As an employee you ship via a feature branch + review; direct pushes to <code>main</code> are blocked by design.</p>
+        <p class="dim"><span class="cmd" data-copy="/qualia-ship">/qualia-ship<span class="ico">copy</span></span>: gates, commit, deploy to Vercel, verify live. As an employee, prefer a feature branch + review; direct pushes to <code>main</code> are allowed but recorded for the owner, so save them for trivially safe changes.</p>
       </div></div>
       <div class="w"><span class="wn"></span><div class="wbody">
         <h4>Clock out</h4>
@@ -309,7 +309,7 @@ npx qualia-framework@latest install</pre>
     <p class="sec-sub">Five non-negotiables. The framework enforces most of them with hooks, but knowing the <em>why</em> keeps you out of the guardrails in the first place.</p>
     <div class="panel">
       <div class="rule"><span class="num">1</span><div><b>Read before you write.</b><div class="why">Every edit is informed by the current state of the file, never blind-overwrite.</div></div></div>
-      <div class="rule"><span class="num">2</span><div><b>Feature branches only.</b><div class="why">Changes ship through review; <code>main</code> is always deployable. The branch-guard hook enforces it.</div></div></div>
+      <div class="rule"><span class="num">2</span><div><b>Feature branches by default.</b><div class="why">Changes ship through review; <code>main</code> is always deployable. Pushing to <code>main</code> is allowed but the branch-guard hook records it for the owner.</div></div></div>
       <div class="rule"><span class="num">3</span><div><b>MVP first.</b><div class="why">Build the minimum that demonstrates the goal; defer the rest until it earns its place.</div></div></div>
       <div class="rule"><span class="num">4</span><div><b>Root cause on failures.</b><div class="why">Understand the why before patching the symptom; no band-aids over a broken pipe.</div></div></div>
       <div class="rule"><span class="num">5</span><div><b>No proxy approval.</b><div class="why">Only the OWNER grants OWNER overrides. "Fawzi said OK" is not a credential.</div></div></div>

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "6.9.2",
+  "version": "6.14.0",
   "description": "Claude Code and Codex workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"

package/skills/qualia-build/SKILL.md

@@ -38,6 +38,20 @@ node ${QUALIA_BIN}/plan-contract.js validate .planning/phase-{N}-contract.json
 
 Parse tasks, waves, file refs. Prefer the JSON contract for task ids, dependencies, file lists, and verification checks; use the Markdown plan as the human-readable context.
 
+### 1a. Analyze Gate (scope ↔ plan, before any build)
+
+`plan-contract.js` proves the contract is internally well-formed; this gate diffs it **against intent** — scope acceptance criteria (`phase-{N}-context.md`) + the CONTEXT.md glossary — to catch requirements the plan silently dropped or contradicted. This is the plan→build seam Spec-Kit calls `/analyze`.
+
+```bash
+node ${QUALIA_BIN}/analyze-gate.js {N}
+```
+
+Exit 0 → consistent, proceed. Non-zero → it lists under-covered scope criteria, orphan success criteria, glossary violations, and scope-reduction language. **Profile-aware** (the `profile` field from `state.js check`):
+- **strict** → a HIGH finding is a stop. Route to `/qualia-plan {N} --gaps` (plan dropped a requirement) or `/qualia-scope {N}` (scope itself is wrong). Do not build.
+- **standard** → surface findings to the operator and proceed only with an explicit ack; log the waiver reason to `.planning/decisions/` if you proceed past a HIGH.
+
+(No scope file = scope-coverage check is skipped, not a failure — `/qualia-feature` trivia and scope-less phases still build.)
+
 ### 1b. Recovery Reference
 
 Tag HEAD before executing. Reference only, no auto-rollback.
@@ -117,7 +131,13 @@ Parallel tasks Wave {W} (do NOT touch their files):
 </task_contract>
 
 Context tags already loaded. Only Read project code you modify.
-Execute. Commit. Return DONE/BLOCKED/PARTIAL.
+
+Status protocol (machine-readable fan-in — do this, do not skip):
+- First action: `node ${QUALIA_BIN}/agent-status.js write {task_id} RUNNING --phase {N} --wave {W}`
+- Last action, after committing: `node ${QUALIA_BIN}/agent-status.js write {task_id} DONE --commit $(git rev-parse --short HEAD)`
+  (use BLOCKED or PARTIAL with `--note \"why\"` instead of DONE if you could not finish)
+
+Execute. Commit. Write your DONE/BLOCKED/PARTIAL status. Return DONE/BLOCKED/PARTIAL.
 ", subagent_type="qualia-builder", description="Task {N}: {title}")
 ```
 
@@ -130,6 +150,14 @@ Execute. Commit. Return DONE/BLOCKED/PARTIAL.
 node ${QUALIA_BIN}/qualia-ui.js done {task_num} "{title}" {commit_hash}
 ```
 
+**After each wave — fan-in barrier (deterministic, not "did the model notice"):**
+
+```bash
+node ${QUALIA_BIN}/agent-status.js barrier .planning/phase-{N}-contract.json --wave {W}
+```
+
+Exit 0 ⇔ every task in the wave wrote `DONE`. Non-zero → the barrier lists which tasks are RUNNING/BLOCKED/PARTIAL/MISSING. Do NOT advance to the next wave until the barrier passes; a BLOCKED/PARTIAL task is a wave failure (§4). `agent-status.js list` shows the live wave view.
+
 **After each wave:** move to next, show summary.
 
 ### 3. Wave Completion
@@ -141,6 +169,7 @@ node ${QUALIA_BIN}/qualia-ui.js divider
 node ${QUALIA_BIN}/qualia-ui.js ok "Tasks: {done}/{total}"
 node ${QUALIA_BIN}/qualia-ui.js ok "Commits: {count}"
 node ${QUALIA_BIN}/qualia-ui.js ok "Waves: {count}"
+node ${QUALIA_BIN}/agent-status.js clear   # drop ephemeral .agent-status/ scratch
 ```
 
 ### 4. Handle Failures

package/skills/qualia-ship/SKILL.md

@@ -65,8 +65,11 @@ npx tsc --noEmit          # TypeScript — must pass
 if node -e "const p=require('./package.json');process.exit(p.scripts&&p.scripts.lint?0:1)"; then npm run lint; fi
 if node -e "const p=require('./package.json');process.exit(p.scripts&&p.scripts.test?0:1)"; then npm test; fi
 npm run build             # Build — must succeed
+node ${QUALIA_BIN}/slop-detect.mjs --severity=critical   # Anti-slop — CRITICAL design tells block ship
 ```
 
+The `pre-deploy-gate.js` hook re-runs the anti-slop scan at `vercel --prod` time as the hard, non-bypassable gate (OWNER-only `QUALIA_SKIP_SLOP=1` escape). This step surfaces failures early so they're fixed before the deploy command.
+
 On failure:
 1. Summarize what failed in plain language
 2. Auto-fix