qualia-framework 6.9.2 → 6.22.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.
@@ -323,6 +346,151 @@ Snapshot shape:
 }
 ```
 
+## Project Sync Payload (reconciliation)
+
+`qualia-framework project-sync` builds the **single complete project-sync snapshot** — the one payload the ERP reads to RECONCILE a project's milestones, phases, tasks, and reports in one pass, and to understand the PR/merge model that maps a feature branch to deployed `main`.
+
+It is distinct from the two existing emitters:
+- `POST /api/v1/reports` (report-payload.js) = ONE work session.
+- `POST /api/v1/project-snapshots` (project-snapshot.js) = lean progress rollup for dashboards (`progress_percent`).
+- **project-sync** = the FULL reconciliation surface: every milestone with REQ-ID completion, current position, task rollup, accountability counters, and the trunk/merge model. project-sync **composes** project-snapshot's identity/current/journey/lifetime/quality blocks (no duplication) and enriches them.
+
+```text
+qualia-framework project-sync            # print JSON (compact) to stdout
+qualia-framework project-sync --json     # print JSON (pretty)
+qualia-framework project-sync --write    # persist .planning/snapshots/project-sync-<ts>.json
+```
+
+Exit 0 = built; exit 2 = no `.planning/` (run `/qualia-new`). Read-only, zero dependencies. Graceful when JOURNEY.md / REQUIREMENTS.md / fields are absent (milestones still emit, REQ blocks report `tracked: false`).
+
+### Payload shape
+
+```json
+{
+  "schema_version": 1,
+  "generated_at": "2026-06-21T00:00:00.000Z",
+  "source": "qualia-framework",
+  "payload": "project-sync",
+  "framework_version": "6.14.0",
+  "identifiers": {
+    "project_id": "qs-acme-portal",
+    "team_id": "qualia-solutions",
+    "git_remote": "github.com/QualiasolutionsCY/acme-portal",
+    "erp_project_id": "7b5d3b4e-2b8a-4de4-91a1-9b2f3182f5ef"
+  },
+  "project": {
+    "name": "acme-portal",
+    "client": "Acme",
+    "status": "built",
+    "deployed_url": "https://client.vercel.app",
+    "progress_percent": 42,
+    "lifecycle": "build",
+    "launched_at": "2026-05-01T00:00:00Z"
+  },
+  "current": {
+    "milestone": 2, "milestone_name": "Product",
+    "phase": 2, "phase_name": "Dashboard", "total_phases": 4,
+    "tasks_done": 3, "tasks_total": 5,
+    "verification": "pending", "gap_cycles": 1
+  },
+  "quality": { "harness_eval": { "status": "PASS", "score": 92, "phase": 2, "generated_at": "…", "artifact": "…" } },
+  "total_milestones": 3,
+  "milestones": [
+    {
+      "num": 1, "name": "Foundation", "status": "closed",
+      "phases": 3, "tasks_completed": 12,
+      "requirements": { "tracked": true, "total": 4, "complete": 4, "incomplete": [] },
+      "closed_at": "2026-04-10T18:00:00Z",
+      "deployed_url": "https://m1.vercel.app"
+    },
+    {
+      "num": 2, "name": "Product", "status": "current",
+      "phases": 4, "tasks_completed": 0,
+      "requirements": { "tracked": true, "total": 5, "complete": 3,
+        "incomplete": [ { "id": "CORE-03", "status": "Incomplete" } ] }
+    },
+    {
+      "num": 3, "name": "Handoff", "status": "future",
+      "phases": 0, "tasks_completed": 0,
+      "requirements": { "tracked": false, "total": 0, "complete": 0, "incomplete": [] }
+    }
+  ],
+  "task_rollup": {
+    "tasks_completed": 15, "phases_completed": 4, "milestones_completed": 1,
+    "total_phases_all_milestones": 7, "build_count": 4, "deploy_count": 1,
+    "current_phase_gap_cycles": 1
+  },
+  "accountability": {
+    "offroad_count": 2,
+    "offroad": [ { "at": "2026-06-01T10:00:00Z", "milestone": 2, "ref": "BUG-7", "note": "hotfix login" } ]
+  },
+  "integration": {
+    "model": "trunk",
+    "integrates_at": "/qualia-ship",
+    "protected_branches": ["main", "master"],
+    "main_push_event_type": "employee_main_push",
+    "main_push_events_path": "~/.claude/.main-push-events.json",
+    "note": "Feature branches integrate to main at /qualia-ship (then deploy). Direct pushes to a protected branch are allowed but recorded as employee_main_push policy events for per-employee accountability."
+  },
+  "timestamps": { "session_started_at": "", "last_pushed_at": "", "last_updated": "" }
+}
+```
+
+### Field meanings
+
+| Field | Meaning |
+|-------|---------|
+| `schema_version` | project-sync contract version. The ERP branches on this to evolve the shape safely. **Distinct** from `snapshot_version` (project-snapshot). |
+| `payload` | Always `"project-sync"` — discriminates this from the report / snapshot payloads when they share an endpoint or queue. |
+| `identifiers` | Same resolution block as project-snapshot — `erp_project_id` is the strongest link, then `git_remote`, then `(team_id, project_id)`. |
+| `project.lifecycle` | `build` (milestone journey) or `operate` (post-launch update stream). The ERP stops expecting a handoff for an `operate` project. |
+| `project.launched_at` / `launch_source` | Present once launched; lets the ERP date the build→operate transition. |
+| `current.*` | The active milestone/phase position + verification + flattened `gap_cycles` (number, current phase). |
+| `total_milestones` | Denominator for milestone-completion (from JOURNEY.md, else max known). |
+| `milestones[]` | The reconciliation spine — every known milestone (journey ∪ closed ∪ current), ordered by num. |
+| `milestones[].status` | `closed` \| `current` \| `future`. The ERP marks done / in-progress / pending from this. |
+| `milestones[].phases` | Phase count: `phases_completed` for closed milestones; the current roadmap phase count for the active one; 0 for future. |
+| `milestones[].tasks_completed` | Tasks completed within that milestone (closed summaries carry this; 0 for current/future — use `task_rollup` for cumulative). |
+| `milestones[].requirements` | REQ-ID completion from REQUIREMENTS.md: `tracked` (false ⇒ no REQ rows declared for this milestone, ERP skips the REQ gate), `total`, `complete`, `incomplete[]` (`{id, status}`). |
+| `milestones[].closed_at` / `deployed_url` | Present when the closed-milestone summary carries them. |
+| `task_rollup` | Cumulative counters so the ERP rolls tasks up without replaying every report: lifetime tasks/phases/milestones, `total_phases_all_milestones`, build/deploy counts, current-phase gap cycles. |
+| `accountability.offroad_count` | Count of off-milestone work units (mirrors the branch-guard main-push tally — drift is counted, not hidden). |
+| `accountability.offroad[]` | Last 10 off-road entries: `{at, milestone, ref, note}`. |
+| `integration` | The PR/merge model (see below). |
+
+### How the ERP reconciles from this payload
+
+1. **Resolve the project** via `identifiers` (same precedence as reports/snapshots).
+2. **Milestones** — upsert each `milestones[]` entry by `num`. Set the ERP milestone state from `status` (`closed`→done, `current`→in-progress, `future`→pending). When `requirements.tracked` is true, the milestone is **complete only if** `complete === total`; surface `incomplete[]` REQ-IDs as the remaining work. When `tracked` is false, fall back to `status` alone (no REQ table was declared).
+3. **Phases** — `milestones[].phases` + `current.total_phases` give per-milestone phase counts; `task_rollup.total_phases_all_milestones` is the grand total across the whole journey.
+4. **Tasks** — use `task_rollup.tasks_completed` for the cumulative figure and `milestones[].tasks_completed` for per-closed-milestone attribution. Do **not** sum reports to get this — the rollup is authoritative.
+5. **Reports** — project-sync does not carry session notes; it reconciles *state*, while `/api/v1/reports` carries each *session*. Reconcile both against the same resolved project: reports for the activity feed, project-sync for the milestone/phase/task tree.
+6. **Accountability** — store `offroad_count` per project so off-milestone drift is visible alongside the per-employee `employee_main_push` tally from `/api/v1/policy-events`.
+
+### PR / merge model (what the ERP must understand)
+
+The framework uses **trunk integration**, surfaced in `integration`:
+
+- Work happens on a **feature branch** (`branch-guard` enforces feature-branch-only; `main`/`master` are protected).
+- `/qualia-ship` **integrates the feature branch into `main`** and then deploys (`integrates_at: "/qualia-ship"`). There is no long-lived release branch; `main` is always the deployable trunk.
+- A direct push to a protected branch is **allowed, not blocked** — but `branch-guard` records an `employee_main_push` policy event (`POST /api/v1/policy-events`, keyed by `(type, actor_code)`) for per-employee accountability. The local journal lives at `main_push_events_path` (`~/.claude/.main-push-events.json`) in the install home; project-sync **references** it, it does not read across the home boundary.
+
+So the branch→main→deploy mapping the ERP should encode: **a milestone's `deployed_url` + `status: closed` means its feature work was integrated to `main` and shipped via `/qualia-ship`.** Main-push events are the exception trail, not the normal integration path.
+
+---
+
+## Framework emits (this repo) vs ERP ingests (backend — out of scope here)
+
+**Framework emits (delivered in this repo):**
+- `qualia-framework project-sync [--json|--write]` builds and (optionally) persists the payload above.
+- Deterministic, read-only, zero-dependency; composes project-snapshot; graceful on missing fields.
+- The payload SHAPE and field semantics documented in this section are the contract.
+
+**ERP ingests (backend work — NOT in this repo):**
+- A `POST /api/v1/project-sync` endpoint (or extend project-snapshots to accept `payload: "project-sync"`) that authenticates the Bearer key and validates `schema_version`.
+- Project resolution + the reconciliation logic in "How the ERP reconciles" above — upserting milestones/phases/tasks, marking completion from REQ counts, and storing `offroad_count`.
+- Wiring an upload path (the framework's `project-snapshot.js` already has `uploadSnapshot()`/retry plumbing the ERP team can mirror for project-sync once the endpoint exists). project-sync itself ships **emit + document** only; the HTTP upload + server-side ingest are the backend's to build.
+
 ## Behavior
 
 - When `erp.enabled` is `false`, `/qualia-report` skips the upload and prints an info line so the employee knows the report stayed local.

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");