qualia-framework 6.2.10 → 6.4.0

package/docs/erp-contract.md

@@ -31,6 +31,29 @@ The API key is read from `.erp-api-key` in the same install home (file mode 0600
 
 ## Endpoints
 
+### POST /api/v1/policy-events
+
+Silently record framework policy violations that should not interrupt the
+employee's active session, such as proxy owner-approval claims ("Fawzi said OK").
+
+**Request Body:**
+```json
+{
+  "type": "proxy_owner_approval_claim",
+  "actor_code": "QS-HASAN-02",
+  "actor_name": "Hasan",
+  "actor_role": "EMPLOYEE",
+  "count": 3,
+  "sample": "Fawzi said ok",
+  "project": "client-project",
+  "cwd": "/path/to/client-project",
+  "recorded_at": "2026-05-23T10:00:00.000Z"
+}
+```
+
+The ERP should increment or store by `(type, actor_code)` so Fawzi can see how
+many times each employee attempted to use proxy approval.
+
 ### POST /api/v1/reports
 
 Upload a session report.
@@ -59,6 +82,9 @@ below).
   "team_id": "qualia-solutions",
   "workspace_id": "2af02a2d-6f1f-4d43-a6cb-6a1e7e09ac43",
   "git_remote": "github.com/QualiasolutionsCY/acme-portal",
+  "work_packet_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+  "assignment_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
+  "assignment_deadline": "2026-06-01",
   "client": "Client Name",
   "client_report_id": "QS-REPORT-03",
   "milestone": 2,
@@ -90,6 +116,13 @@ below).
     "total_phases": 8,
     "last_closed_milestone": 1
   },
+  "harness_eval": {
+    "status": "PASS",
+    "score": 92,
+    "phase": 2,
+    "generated_at": "2026-05-23T10:15:00.000Z",
+    "artifact": ".planning/evals/harness-eval-2026-05-23T10-15-00-000Z.json"
+  },
   "session_started_at": "2026-04-12T13:45:00Z",
   "session_duration_minutes": 45,
   "last_pushed_at": "2026-04-12T14:25:00Z",
@@ -173,6 +206,37 @@ Authorization: Bearer <api-key>
 }
 ```
 
+## Work Packet Pull
+
+`qualia-framework work-packet pull --project <erp_project_id>` reads the active
+ERP mission packet and writes it to:
+
+```text
+.planning/work-packet.json
+```
+
+The Framework treats this as session context, not as a new source of business
+truth. ERP owns the employee, deadline, assignment, review state, and owner
+approval. Framework owns build, verification, snapshot, and report proof.
+
+Local packet shape:
+
+```json
+{
+  "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+  "project_id": "7b5d3b4e-2b8a-4de4-91a1-9b2f3182f5ef",
+  "assignment_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
+  "deadline_date": "2026-06-01",
+  "next_command": "/qualia-verify",
+  "mission_url": "https://portal.qualiasolutions.net/projects/7b5d3b4e-2b8a-4de4-91a1-9b2f3182f5ef/mission"
+}
+```
+
+Session start reads this file and shows the ERP deadline + next Framework
+command. `/qualia-report` sends `work_packet_id`, `assignment_id`, and
+`assignment_deadline`; project snapshots include the same fields under
+`identifiers`.
+
 ## Project Snapshot Export
 
 `qualia-framework project-snapshot --write` creates a local project-level rollup at:
@@ -206,7 +270,10 @@ Snapshot shape:
     "team_id": "qualia-solutions",
     "git_remote": "github.com/QualiasolutionsCY/acme-portal",
     "erp_project_id": "7b5d3b4e-2b8a-4de4-91a1-9b2f3182f5ef",
-    "client_id": "5f5a8d8e-8c58-4c30-9b76-13a08f0d0d8a"
+    "client_id": "5f5a8d8e-8c58-4c30-9b76-13a08f0d0d8a",
+    "work_packet_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+    "assignment_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
+    "assignment_deadline": "2026-06-01"
   },
   "project": {
     "name": "acme-portal",
@@ -226,6 +293,15 @@ Snapshot shape:
     "verification": "pending",
     "gap_cycles": 1
   },
+  "quality": {
+    "harness_eval": {
+      "status": "PASS",
+      "score": 92,
+      "phase": 2,
+      "generated_at": "2026-05-23T10:15:00.000Z",
+      "artifact": ".planning/evals/harness-eval-2026-05-23T10-15-00-000Z.json"
+    }
+  },
   "journey": {
     "total_milestones": 3,
     "milestones": [
@@ -287,11 +363,15 @@ Snapshot shape:
 | milestone_name | string | recommended (v4+) | Human name of the current milestone — from JOURNEY.md / tracking.json |
 | milestones | array | recommended (v4+) | Array of closed milestone summaries: `{num, name, closed_at, phases_completed, tasks_completed}`. Renders the journey tree on the ERP. |
 | lifetime | object | recommended | Cumulative counters — tasks_completed, phases_completed, milestones_completed, total_phases, last_closed_milestone |
+| harness_eval | object | recommended (v6.3+) | Latest deterministic harness eval summary: status, score, phase, generated_at, and local artifact path. |
 | project_id | string | recommended (v3.6+) | Stable per-project identifier — preferred dedupe key over `project` slug. Survives directory renames. |
 | team_id | string | recommended (v3.6+) | Installation's team identifier. Composite `(team_id, project_id)` is the canonical project key. |
 | erp_project_id | UUID string | optional | ERP's canonical project UUID when known. Strongest direct link for admin dashboards; `/qualia-report` only sends UUID-shaped values. |
 | client_id | UUID string | optional | ERP/client canonical UUID when known. Lets reports attach to the client without guessing from a display name; slug-like values are omitted to avoid ERP validation failures. |
 | workspace_id | UUID string | optional | Workspace/tenant scope for multi-company or multi-team installs; only UUID-shaped values are sent. |
+| work_packet_id | UUID string | optional (v6.3+) | ERP `project_work_packets.id` read from `.planning/work-packet.json`. Links the report to the exact employee mission packet. |
+| assignment_id | UUID string | optional (v6.3+) | ERP `project_assignments.id` read from `.planning/work-packet.json`. Links the report to the assignment/deadline owner. |
+| assignment_deadline | date string | optional (v6.3+) | ERP-owned assignment deadline (`YYYY-MM-DD`) active when the report was submitted. |
 | git_remote | string | optional (v3.6+) | e.g. `github.com/QualiasolutionsCY/foo`. Lets the ERP correlate tracking with the source repo. |
 | session_started_at | string | optional (v3.6+) | ISO 8601 — when the current Claude Code session began. |
 | last_pushed_at | string | optional (v3.6+) | ISO 8601 — distinct from `last_updated` (which fires on local writes too). |

package/docs/onboarding.html

@@ -497,7 +497,6 @@
         <h4>Diagnose &amp; fix</h4>
         <dl>
           <dt>/qualia-fix</dt><dd>Repair lane. Finds root cause, applies a minimal fix, verifies it, writes a fix report.</dd>
-          <dt>/qualia-debug</dt><dd>Investigative debugging. Use when the failure is unclear and you need evidence before repair.</dd>
           <dt>/qualia-review</dt><dd>Read-only production audit with severity-scored findings. Run before a big deploy.</dd>
           <dt>/qualia-optimize</dt><dd>Deep improvement map for performance, design, alignment, and architecture. Spawns parallel specialists.</dd>
           <dt>/qualia-postmortem</dt><dd>Self-healing layer. After a failed verify, identifies which agent or rule should have caught it and proposes a delta.</dd>
@@ -529,11 +528,7 @@
         <h4>Navigate the session</h4>
         <dl>
           <dt>/qualia</dt><dd>State router. Tells you the exact next command.</dd>
-          <dt>/qualia-idk</dt><dd>"Something feels off." Diagnoses confusion across .planning + codebase.</dd>
-          <dt>/qualia-pause</dt><dd>Save context for handoff to a future session.</dd>
-          <dt>/qualia-resume</dt><dd>Restore context and routing from a paused session.</dd>
           <dt>/qualia-road</dt><dd>Terminal map of the workflow. Headless-friendly.</dd>
-          <dt>/qualia-help</dt><dd>Open this kind of reference in the browser.</dd>
         </dl>
       </div>
     </div>
@@ -559,7 +554,6 @@
         <h4>Code archaeology</h4>
         <dl>
           <dt>/qualia-map</dt><dd>Brownfield onboarding. Map an existing codebase before adding to it.</dd>
-          <dt>/qualia-zoom</dt><dd>Map a small, unfamiliar code area in domain-glossary terms.</dd>
         </dl>
       </div>
     </div>
@@ -574,21 +568,16 @@
         <h4>Knowledge</h4>
         <dl>
           <dt>/qualia-learn</dt><dd>Save a learning, pattern, fix, or client preference. Persists across projects and sessions.</dd>
-          <dt>/qualia-flush</dt><dd>Promote daily-log raw entries to the curated knowledge tier.</dd>
         </dl>
       </div>
       <div class="kit-group">
         <h4>Issue queue</h4>
         <dl>
-          <dt>/qualia-issues</dt><dd>Break a phase plan into independent vertical-slice GitHub issues.</dd>
-          <dt>/qualia-triage</dt><dd>Route open issues into needs-info, ready-for-agent, ready-for-human.</dd>
         </dl>
       </div>
       <div class="kit-group">
         <h4>Extend the framework</h4>
         <dl>
-          <dt>/qualia-skill-new</dt><dd>Author a new Qualia skill or agent.</dd>
-          <dt>/qualia-hook-gen</dt><dd>Convert an instruction into a deterministic Claude Code hook.</dd>
         </dl>
       </div>
       <div class="kit-group">

package/guide.md

@@ -1,31 +1,11 @@
-# Qualia Developer Guide (v6.2.7)
+# Qualia Developer Guide
 
 > Follow the road. Type the commands. The framework handles the rest.
 > `--auto` chains the whole road end-to-end with only two human checkpoints per project.
 
-**v6.2.7 is the Codex runtime compatibility patch.** Codex installs now get native `~/.codex/hooks.json`, TOML agents, bin scripts, rules, skills, templates, knowledge, guide, and role config in addition to `AGENTS.md`.
+Surface: **23 active skills**. Use `/qualia-fix` for broken behavior, `/qualia-feature` for new single-feature work, `/qualia-discuss` in PROJECT MODE for kickoff capture, `/qualia-polish --loop` for the autonomous visual loop, and `/qualia-polish --vibe` for fast layout-preserving aesthetic pivots.
 
-**v6.2.5 carries forward.** `qualia-framework project-snapshot --write` creates a single `.planning/snapshots/project-snapshot-*.json` artifact with project identifiers, current milestone/phase, closed milestones, lifetime counters, and a project progress percentage for explicit ERP/admin import.
-
-**v6.2.4 carries forward.** The Framework -> ERP report payload now comes from the shipped and tested `report-payload.js` builder, so admin-visible report linking fields are covered by executable tests instead of only prompt prose.
-
-**v6.2.3 carries forward.** Framework slugs stay in `project_id`/`team_id`; ERP foreign-key identifiers (`erp_project_id`, `client_id`, `workspace_id`) are sent only when UUID-shaped, so reports do not fail validation because a local slug leaked into an ERP UUID field.
-
-**v6.2.2 carries forward.** Framework builds, Memory remembers, ERP operates. ERP work packets can seed Claude/Codex sessions, `/qualia-report` can carry ERP-native IDs, and release verification now has a public `@latest` install smoke.
-
-**v6.2.1 carries forward.** Active docs match the v6.2 no-bot-commit model, the explicit `/qualia-report` ERP contract, the current skill surface, and fail-closed `INSUFFICIENT EVIDENCE` behavior. `tests/refs.test.sh` guards those claims.
-
-**v6.1.0 ships the design-pivot path you were missing.** New `/qualia-vibe` is fast aesthetic pivot (~3 min): swap design tokens, keep layout. Default proposes ONE direction per `rules/one-opinion.md` (the EventMaster discipline — never give the user a menu). Sub-modes: `--variants N` for the opt-in menu, `--extract URL` reverse-engineers DESIGN.md from a reference site, `--sync` shows code↔DESIGN.md drift and can patch DESIGN.md from code. Slop-detect grew banned fonts (Montserrat/Poppins/Lato/Open Sans) and a `--watch` flag for proactive single-file mode. Several design-surface bugs from v6.0 audit are fixed too (viewport mismatch, slop-detect path resolution in the polish loop, dead `/qualia-design` references, the bounce-easing token that contradicted design-laws).
-
-**v6.2.0 removes hook-created bot commits.** `pre-push.js` stamps local `tracking.json` telemetry but no longer commits it. `pre-compact.js` is gone because `state.js` already gives stronger crash safety with atomic writes plus a journal. ERP sync remains explicit through `/qualia-report` POSTs, not passive git scraping.
-
-**v5.9.2 carries forward.** `pre-push.js` self-gates against `branch-guard.js` so a blocked push no longer leaves an orphan bot commit. `qualia-report` ERP payload omits empty ISO datetime fields (avoids 422 from the ERP validator).
-
-**v5.9.1 carries forward.** `/qualia-new` opens with the Demo/Full/Quick project-shape gate via `AskUserQuestion`, then exactly one free-text pitch question, then a hard hand-off to `/qualia-discuss` for the structured interview (8 questions for demos, 14 for full projects).
-
-**v5.9.0 carries forward.** `tests/refs.test.sh` catches dead command references in user-facing surfaces on every release. `bin/erp-retry.js` is a real persistent retry queue for ERP report uploads. Four structured agents (verifier, plan-checker, roadmapper, qa-browser) run on Sonnet for ~40% per-phase cost cut, while builder/planner/researcher/visual-evaluator stay on Opus where the architectural and vision reasoning lives. The verifier downgrades to FAIL on any `INSUFFICIENT EVIDENCE` line.
-
-**Surface is 35 installed skills.** Use `/qualia-fix` for broken existing behavior, `/qualia-feature` for new single-feature work, and `/qualia-discuss` in PROJECT MODE for kickoff capture; `/qualia-polish --loop` for the autonomous visual loop; `/qualia-vibe` for fast layout-preserving aesthetic pivots.
+For the identity statement see [`SOUL.md`](./SOUL.md). For every skill flag see [`FLAGS.md`](./FLAGS.md). When something breaks see [`TROUBLESHOOTING.md`](./TROUBLESHOOTING.md). For release history see [`CHANGELOG.md`](./CHANGELOG.md).
 
 ## The Road
 
@@ -81,21 +61,18 @@ Append `--auto` to `/qualia-new` and the framework chains every step:
 | Single feature | `/qualia-feature` | Auto-scoped: inline for trivia, fresh spawn for 1-5 files |
 | Finishing | `/qualia-polish` | Design and UX pass (scope-adaptive: component / route / app / redesign / critique / quick / loop) |
 | | `/qualia-polish --loop` | Autonomous visual-polish loop: screenshot, vision-eval, fix, repeat |
-| Pivot the vibe | `/qualia-vibe` | Fast aesthetic pivot (~3 min): swap tokens, keep layout. Propose ONE direction. |
-| | `/qualia-vibe --extract <URL>` | Reverse-engineer DESIGN.md from a reference site |
-| | `/qualia-vibe --sync` | Show / patch drift between code (CSS vars + Tailwind) and DESIGN.md |
+| Pivot the vibe | `/qualia-polish --vibe` | Fast aesthetic pivot (~3 min): swap tokens, keep layout. Propose ONE direction. |
+| | `/qualia-polish --vibe --extract <URL>` | Reverse-engineer DESIGN.md from a reference site |
+| | `/qualia-polish --vibe --sync` | Show / patch drift between code (CSS vars + Tailwind) and DESIGN.md |
 | | `/qualia-ship` | Deploy to production |
 | | `/qualia-handoff` | Deliver to client (4 mandatory deliverables) |
 | Reporting | `/qualia-report` | Log what you did (mandatory before clock-out) |
-| Zooming in | `/qualia-zoom` | Focus on a single file or function with full context |
-| Issues | `/qualia-issues` | Break a phase plan into vertical-slice GitHub issues |
-| Triage | `/qualia-triage` | Triage open issues through the ready-for-agent state machine |
 | Optimize | `/qualia-optimize --deepen` | Find shallow modules; v5.3+ spawns 3 parallel interface-design variants per candidate |
+| Harness eval | `qualia-framework eval --run --write` | Run machine contract checks and write scored eval artifacts for ERP/reporting |
 | Planning hygiene | `qualia-framework planning-hygiene scan` | Detect loose `.planning/` reports/assets before they turn into folder bloat |
-| Hook gen | `/qualia-hook-gen` | Convert a CLAUDE.md/rules instruction into a deterministic hook (v5.3+) |
 | Road view | `/qualia-road` | View and navigate journey/milestone/phase status |
-| Lost? | `/qualia` | Mechanical next-command router |
-| Confused? | `/qualia-idk` | Diagnostic — scans planning + code, explains what's going on |
+| Lost — need next command | `/qualia` | Mechanical state-driven router |
+| Confused — need to understand the situation | `/qualia-idk` | Three-scan diagnostic + paste-ready command sequence |
 
 ## Full Journey Hierarchy
 
@@ -119,14 +96,14 @@ Hard rules (enforced by `state.js` and the roadmapper):
 2. **Read before write** — don't edit files you haven't read
 3. **MVP first** — build what's asked, nothing extra
 4. **Every task has a `Why`** (story-file format) — if you can't explain why a task matters in one sentence, it probably shouldn't exist
-5. **`/qualia` is your friend** — lost? type it
-6. **`/qualia-idk` is your deeper friend** — not lost on "what command", but confused about the *situation*? Type `idk`.
+5. **`/qualia` is your friend** — lost on "what's my next command?" The router reads state and returns the next move.
+6. **`/qualia-idk` is your deeper friend** — confused about *the situation itself*. Reads conversation + planning + code, then returns guidance plus a paste-ready Qualia command sequence.
 
 ## When You're Stuck
 
 ```
-/qualia       ← "what command should I run next?" (state-driven, instant)
-/qualia-idk   ← "what's actually going on here?" (diagnostic, scans planning + code, ~30s)
+/qualia       ← "what's my next command?" (state-driven, instant)
+/qualia-idk   ← "what is actually going on here?" (three-scan diagnostic, ~30-45s)
 ```
 
 If neither helps, paste the error and ask Claude directly. If Claude can't fix it, tell Fawzi.
@@ -154,8 +131,8 @@ If neither helps, paste the error and ask Claude directly. If Claude can't fix i
 | Starting a new client project | `/qualia-new` (or `/qualia-new --auto` to roll end-to-end) |
 | Starting a quick throwaway | `/qualia-new --quick` |
 | Brownfield project | `/qualia-map` first, then `/qualia-new` |
-| Stuck picking next command | `/qualia` |
-| Confused about the situation | `/qualia-idk` |
+| Stuck — "what command should I run?" | `/qualia` |
+| Confused — "what's actually going on?" | `/qualia-idk` |
 | Finished the last phase of a milestone | `/qualia-milestone` |
 | About to ship | `/qualia-ship` |
 | Client is ready to take over | `/qualia-handoff` |

package/hooks/fawzi-approval-guard.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// Silently records EMPLOYEE attempts to use "Fawzi said OK" style proxy
+// approval. This hook never blocks and never prints: the policy text teaches
+// the agent not to do it; this hook records when it still appears in tool input.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const crypto = require("crypto");
+
+function qualiaHome() {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(os.homedir(), ".claude");
+}
+
+const QUALIA_HOME = qualiaHome();
+const CONFIG = path.join(QUALIA_HOME, ".qualia-config.json");
+const EVENT_FILE = path.join(QUALIA_HOME, ".approval-policy-events.json");
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+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 {}
+}
+
+function collectStrings(value, out = []) {
+  if (typeof value === "string") out.push(value);
+  else if (Array.isArray(value)) value.forEach((v) => collectStrings(v, out));
+  else if (value && typeof value === "object") {
+    for (const v of Object.values(value)) collectStrings(v, out);
+  }
+  return out;
+}
+
+function hookInputText() {
+  try {
+    if (process.stdin.isTTY) return "";
+    const raw = fs.readFileSync(0, "utf8");
+    if (!raw) return "";
+    try {
+      const parsed = JSON.parse(raw);
+      return collectStrings(parsed.tool_input || parsed).join("\n");
+    } catch {
+      return raw;
+    }
+  } catch {
+    return "";
+  }
+}
+
+function approvalClaim(text) {
+  const normalized = String(text || "").replace(/\s+/g, " ").trim();
+  if (!normalized) return "";
+  const patterns = [
+    /\bfawzi\b.{0,80}\b(said|says|told|approved|approves|okayed|ok'd|allowed|allows|authorized|authorizes|confirmed)\b.{0,80}\b(ok|okay|fine|yes|ship|deploy|go ahead|do it|allowed|approved)?/i,
+    /\bfawzi\s+is\s+(here|with\s+me|beside\s+me)\b.{0,80}\b(ok|okay|fine|yes|approved|approves|allow|allows|ship|deploy|go ahead|do it)\b/i,
+    /\b(owner|boss)\b.{0,40}\b(said|says|approved|approves|okayed|ok'd)\b.{0,60}\b(ok|okay|fine|yes|ship|deploy|go ahead|do it)\b/i,
+  ];
+  for (const re of patterns) {
+    const m = normalized.match(re);
+    if (m) return m[0].slice(0, 220);
+  }
+  return "";
+}
+
+function recordLocal(config, sample) {
+  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: "proxy_owner_approval_claim",
+    actor_code: config.code || "",
+    actor_name: config.installed_by || "",
+    actor_role: config.role || "",
+    count,
+    sample,
+    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;
+}
+
+function enqueueErp(config, event) {
+  try {
+    const retryPath = path.join(QUALIA_HOME, "bin", "erp-retry.js");
+    if (!fs.existsSync(retryPath)) return;
+    if (config.erp && config.erp.enabled === false) return;
+    const erpUrl = (config.erp && config.erp.url) || "https://portal.qualiasolutions.net";
+    const { enqueue } = require(retryPath);
+    enqueue({
+      client_report_id: `QS-POLICY-${(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 {}
+}
+
+try {
+  const config = readJson(CONFIG, {});
+  if ((config.role || "").toUpperCase() === "OWNER") process.exit(0);
+  if ((config.role || "").toUpperCase() !== "EMPLOYEE") process.exit(0);
+
+  const sample = approvalClaim(hookInputText());
+  if (!sample) process.exit(0);
+
+  const event = recordLocal(config, sample);
+  enqueueErp(config, event);
+} catch {}
+
+process.exit(0);

package/hooks/pre-compact.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/pre-compact.js — snapshot in-flight session context to
+// .planning/.compaction-snapshot.md so /qualia-resume (or the next session)
+// can surface what was active when compaction wiped the conversation.
+//
+// PreCompact hook (fires before Claude Code compacts the context window).
+//
+// Why this hook returned in v6.3.2:
+//   v6.2.0 removed the original pre-compact.js because it created BOT COMMITS
+//   to stamp STATE.md / tracking.json. That was the wrong mechanism —
+//   state.js's atomic write + journal already gives crash safety. This v2
+//   hook does NOT touch git, does NOT touch tracking.json, does NOT write
+//   through state.js. It only writes to a sidecar file that survives
+//   compaction and tells the next session "here's what was in flight".
+//
+// Design constraints (same shape as stop-session-log.js):
+//   • NEVER block — exit 0 always, even on internal failure.
+//   • Fast — under 200ms, no network, no LLM call.
+//   • No PII / secrets — file paths, commit subjects, phase numbers only.
+//   • Idempotent — overwrites the sidecar on every fire; we only care
+//     about the LATEST pre-compaction state.
+//   • No git commits, no state.js mutations.
+//
+// Sidecar format (.planning/.compaction-snapshot.md):
+//   # Pre-compaction snapshot — {ISO timestamp}
+//   ## State
+//   Phase: 2 of 4 — built
+//   ## Work in flight
+//   - 3 modified files (uncommitted)
+//   - foo.ts, bar.ts, baz.test.ts
+//   ## Recent commits (last 5)
+//   - abc1234 feat: implement signin
+//   - def5678 test: signin happy path
+//   ## Active planning artifacts
+//   - .planning/phase-2-plan.md (modified 14m ago)
+//   - .planning/phase-2-verification.md (modified 3h ago)
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const _traceStart = Date.now();
+
+function qualiaHome() {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(require("os").homedir(), ".claude");
+}
+
+function _trace(result, extra) {
+  try {
+    const traceDir = path.join(qualiaHome(), ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    fs.appendFileSync(
+      path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`),
+      JSON.stringify({
+        hook: "pre-compact",
+        result,
+        timestamp: new Date().toISOString(),
+        duration_ms: Date.now() - _traceStart,
+        ...extra,
+      }) + "\n",
+    );
+  } catch {}
+}
+
+function git(args, opts = {}) {
+  try {
+    const r = spawnSync("git", args, {
+      encoding: "utf8",
+      timeout: 2000,
+      shell: process.platform === "win32",
+      ...opts,
+    });
+    if (r.status !== 0) return "";
+    return (r.stdout || "").trim();
+  } catch {
+    return "";
+  }
+}
+
+function readJson(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function safeStatM(p) {
+  try { return fs.statSync(p).mtimeMs; } catch { return 0; }
+}
+
+function humanAge(ms) {
+  if (ms < 60_000) return `${Math.round(ms / 1000)}s ago`;
+  if (ms < 3600_000) return `${Math.round(ms / 60_000)}m ago`;
+  if (ms < 86_400_000) return `${Math.round(ms / 3600_000)}h ago`;
+  return `${Math.round(ms / 86_400_000)}d ago`;
+}
+
+try {
+  const cwd = process.cwd();
+  const repoRoot = git(["rev-parse", "--show-toplevel"], { cwd }) || cwd;
+  const planningDir = path.join(repoRoot, ".planning");
+
+  // Skip if not a Qualia project (no .planning/ dir) — nothing to snapshot.
+  if (!fs.existsSync(planningDir)) {
+    _trace("skip", { reason: "no-planning-dir" });
+    process.exit(0);
+  }
+
+  const now = Date.now();
+  const tracking = readJson(path.join(planningDir, "tracking.json")) || {};
+  const stateText = (() => {
+    try { return fs.readFileSync(path.join(planningDir, "STATE.md"), "utf8"); }
+    catch { return ""; }
+  })();
+
+  // State header line (one line from STATE.md, or fall back to tracking.json).
+  const stateLine = (() => {
+    const phaseLine = stateText.split("\n").find((l) => /^Phase:/i.test(l));
+    const statusLine = stateText.split("\n").find((l) => /^Status:/i.test(l));
+    if (phaseLine || statusLine) return [phaseLine, statusLine].filter(Boolean).join(" — ");
+    const p = tracking.phase || "?";
+    const total = tracking.total_phases || tracking.phase_total || "?";
+    const status = tracking.status || "?";
+    return `Phase: ${p} of ${total} — ${status}`;
+  })();
+
+  // Work in flight: uncommitted modified files.
+  const modified = (() => {
+    const out = git(["diff", "--name-only", "HEAD"], { cwd: repoRoot });
+    return out ? out.split("\n").filter(Boolean) : [];
+  })();
+  const staged = (() => {
+    const out = git(["diff", "--name-only", "--cached"], { cwd: repoRoot });
+    return out ? out.split("\n").filter(Boolean) : [];
+  })();
+  const inFlight = [...new Set([...modified, ...staged])].slice(0, 10);
+
+  // Recent commits — last 5, single-line.
+  const recentCommits = (() => {
+    const out = git(["log", "--pretty=%h %s", "-5"], { cwd: repoRoot });
+    return out ? out.split("\n").filter(Boolean) : [];
+  })();
+
+  // Active planning artifacts: phase-*-* files modified in last 24h.
+  const activePlanning = (() => {
+    try {
+      const files = fs.readdirSync(planningDir).filter((f) => /^phase-\d+/.test(f) && f.endsWith(".md"));
+      const day = 24 * 3600_000;
+      return files
+        .map((f) => ({ name: f, age: now - safeStatM(path.join(planningDir, f)) }))
+        .filter((x) => x.age < day)
+        .sort((a, b) => a.age - b.age)
+        .slice(0, 5);
+    } catch { return []; }
+  })();
+
+  // Open deviations / verification FAILs in current phase.
+  const phaseNum = tracking.phase || 0;
+  const verifyFails = (() => {
+    if (!phaseNum) return [];
+    const vPath = path.join(planningDir, `phase-${phaseNum}-verification.md`);
+    if (!fs.existsSync(vPath)) return [];
+    try {
+      const v = fs.readFileSync(vPath, "utf8");
+      const fails = (v.match(/^[^\n]*\bFAIL\b[^\n]*$/gm) || []).slice(0, 5);
+      const insufficient = (v.match(/^[^\n]*INSUFFICIENT EVIDENCE[^\n]*$/gm) || []).slice(0, 3);
+      return [...fails, ...insufficient];
+    } catch { return []; }
+  })();
+
+  // Compose snapshot. Markdown so the next session can render it as-is.
+  const ts = new Date().toISOString();
+  const lines = [
+    `# Pre-compaction snapshot — ${ts}`,
+    "",
+    "_Written by `hooks/pre-compact.js` immediately before Claude Code compacted the context window. `/qualia-resume` and session-start surface this so the next session sees what was active._",
+    "",
+    "## State",
+    stateLine || "(no state info)",
+    "",
+  ];
+
+  lines.push("## Work in flight");
+  if (inFlight.length === 0) {
+    lines.push("(no uncommitted changes)");
+  } else {
+    lines.push(`${inFlight.length} file(s):`);
+    for (const f of inFlight) lines.push(`- ${f}`);
+  }
+  lines.push("");
+
+  lines.push("## Recent commits");
+  if (recentCommits.length === 0) {
+    lines.push("(no commit history)");
+  } else {
+    for (const c of recentCommits) lines.push(`- ${c}`);
+  }
+  lines.push("");
+
+  lines.push("## Active planning artifacts (modified in last 24h)");
+  if (activePlanning.length === 0) {
+    lines.push("(none)");
+  } else {
+    for (const p of activePlanning) lines.push(`- ${p.name} — ${humanAge(p.age)}`);
+  }
+  lines.push("");
+
+  if (verifyFails.length > 0) {
+    lines.push("## Open verification issues");
+    for (const f of verifyFails) lines.push(`- ${f.trim()}`);
+    lines.push("");
+  }
+
+  lines.push("---");
+  lines.push("_Sidecar file. Not committed to git. Read by `/qualia-resume` and `session-start` to restore in-flight context after compaction._");
+
+  fs.writeFileSync(path.join(planningDir, ".compaction-snapshot.md"), lines.join("\n") + "\n");
+  _trace("snapshot", {
+    in_flight: inFlight.length,
+    commits: recentCommits.length,
+    active_planning: activePlanning.length,
+    verify_fails: verifyFails.length,
+  });
+  process.exit(0);
+} catch (err) {
+  _trace("error", { error: err && err.message ? err.message : String(err) });
+  process.exit(0);
+}