qualia-framework 6.3.0 → 6.4.0

package/bin/status-snapshot.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+// bin/status-snapshot.js — operator status snapshot. Mirrors ECC's
+// `ecc status --markdown --write status.md`, but stays vertical to Qualia:
+// install health + active project + work in flight + ERP queue + memory state.
+//
+// Usage:
+//   qualia-framework status                       # print markdown to stdout
+//   qualia-framework status --write [path]        # write to file (default: ./STATUS.md)
+//   qualia-framework status --json                # machine-readable JSON
+//   qualia-framework status --exit-code           # exit 1 if readiness warnings exist
+//
+// Designed for cross-session paste — every line is fully qualified, no
+// runtime variables, no secrets. Safe to paste into a Slack / GitHub
+// comment / handoff doc.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawnSync } = require("child_process");
+
+const _start = 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(os.homedir(), ".claude");
+}
+
+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) return "never";
+  const diff = Date.now() - ms;
+  if (diff < 0) return "future";
+  if (diff < 60_000) return `${Math.round(diff / 1000)}s ago`;
+  if (diff < 3600_000) return `${Math.round(diff / 60_000)}m ago`;
+  if (diff < 86_400_000) return `${Math.round(diff / 3600_000)}h ago`;
+  return `${Math.round(diff / 86_400_000)}d ago`;
+}
+
+function parseArgs(argv) {
+  const args = { write: false, writePath: "", json: false, exitCode: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--write") {
+      args.write = true;
+      if (argv[i + 1] && !argv[i + 1].startsWith("--")) args.writePath = argv[++i];
+    } else if (a.startsWith("--write=")) {
+      args.write = true;
+      args.writePath = a.slice("--write=".length);
+    } else if (a === "--json") {
+      args.json = true;
+    } else if (a === "--exit-code") {
+      args.exitCode = true;
+    }
+  }
+  return args;
+}
+
+function collectInstallHealth() {
+  const qhome = qualiaHome();
+  const cfgPath = path.join(qhome, ".qualia-config.json");
+  const cfg = readJson(cfgPath) || {};
+  const pkgPath = path.join(__dirname, "..", "package.json");
+  const pkg = readJson(pkgPath) || {};
+
+  const homes = [path.join(os.homedir(), ".claude"), path.join(os.homedir(), ".codex")].filter((h) => fs.existsSync(h));
+  const installedTargets = homes.map((h) => path.basename(h) === ".codex" ? "Codex" : "Claude");
+
+  // Sanity: required core scripts exist?
+  const required = [
+    "bin/state.js",
+    "bin/command-surface.js",
+    "bin/prune-deprecated.js",
+    "hooks/pre-compact.js",
+    "hooks/stop-session-log.js",
+  ];
+  const missing = [];
+  for (const home of homes) {
+    for (const rel of required) {
+      if (!fs.existsSync(path.join(home, rel))) missing.push(`${path.basename(home)}:${rel}`);
+    }
+  }
+
+  return {
+    package_version: pkg.version || "?",
+    installed_version: cfg.version || "?",
+    installed_by: cfg.installed_by || "?",
+    role: cfg.role || "?",
+    installed_at: cfg.installed_at || "?",
+    targets: installedTargets,
+    missing_files: missing,
+    healthy: missing.length === 0 && !!cfg.version,
+  };
+}
+
+function collectActiveProject() {
+  const cwd = process.cwd();
+  const repoRoot = git(["rev-parse", "--show-toplevel"], { cwd }) || cwd;
+  const planningDir = path.join(repoRoot, ".planning");
+  if (!fs.existsSync(planningDir)) {
+    return { is_project: false, repo: path.basename(repoRoot) };
+  }
+
+  const tracking = readJson(path.join(planningDir, "tracking.json")) || {};
+  const stateText = (() => {
+    try { return fs.readFileSync(path.join(planningDir, "STATE.md"), "utf8"); } catch { return ""; }
+  })();
+  const phaseLine = stateText.split("\n").find((l) => /^Phase:/i.test(l)) || "";
+  const statusLine = stateText.split("\n").find((l) => /^Status:/i.test(l)) || "";
+
+  // Verification status of current phase.
+  const phase = tracking.phase || 0;
+  const vPath = phase ? path.join(planningDir, `phase-${phase}-verification.md`) : "";
+  let verifyState = "unverified";
+  let failCount = 0;
+  if (vPath && fs.existsSync(vPath)) {
+    try {
+      const v = fs.readFileSync(vPath, "utf8");
+      failCount = (v.match(/\bFAIL\b/g) || []).length + (v.match(/INSUFFICIENT EVIDENCE/g) || []).length;
+      verifyState = failCount > 0 ? "FAILED" : "passed";
+    } catch {}
+  }
+
+  return {
+    is_project: true,
+    repo: path.basename(repoRoot),
+    branch: git(["rev-parse", "--abbrev-ref", "HEAD"], { cwd: repoRoot }) || "?",
+    phase_line: phaseLine.trim() || `Phase: ${tracking.phase || "?"} of ${tracking.total_phases || tracking.phase_total || "?"}`,
+    status_line: statusLine.trim() || `Status: ${tracking.status || "?"}`,
+    verify_state: verifyState,
+    verify_fail_count: failCount,
+    gap_cycles_used: (tracking.gap_cycles || {})[String(phase)] || 0,
+    gap_cycle_limit: tracking.gap_cycle_limit || 2,
+  };
+}
+
+function collectWorkInFlight() {
+  const cwd = process.cwd();
+  const modified = git(["diff", "--name-only", "HEAD"], { cwd }).split("\n").filter(Boolean);
+  const staged = git(["diff", "--name-only", "--cached"], { cwd }).split("\n").filter(Boolean);
+  const untracked = git(["ls-files", "--others", "--exclude-standard"], { cwd }).split("\n").filter(Boolean);
+  const commitsAhead = (() => {
+    const head = git(["rev-parse", "HEAD"], { cwd });
+    const upstream = git(["rev-parse", "@{u}"], { cwd });
+    if (!head || !upstream) return 0;
+    const out = git(["rev-list", "--count", `${upstream}..HEAD`], { cwd });
+    return parseInt(out, 10) || 0;
+  })();
+  return {
+    modified: modified.slice(0, 20),
+    staged: staged.slice(0, 20),
+    untracked: untracked.slice(0, 20),
+    commits_ahead: commitsAhead,
+  };
+}
+
+function collectErpQueue() {
+  const qhome = qualiaHome();
+  const queueDir = path.join(qhome, ".erp-retry-queue");
+  if (!fs.existsSync(queueDir)) return { pending: 0, last_attempt: 0 };
+  try {
+    const entries = fs.readdirSync(queueDir).filter((f) => f.endsWith(".json"));
+    let lastMtime = 0;
+    for (const f of entries) lastMtime = Math.max(lastMtime, safeStatM(path.join(queueDir, f)));
+    return { pending: entries.length, last_attempt: lastMtime };
+  } catch {
+    return { pending: 0, last_attempt: 0 };
+  }
+}
+
+function collectMemoryState() {
+  const qhome = qualiaHome();
+  const dailyDir = path.join(qhome, "knowledge", "daily-log");
+  const lastFlushStamp = path.join(qhome, ".qualia-last-flush");
+  const lastLearnScanStamp = path.join(qhome, ".qualia-last-learning-scan");
+
+  let entriesThisWeek = 0;
+  if (fs.existsSync(dailyDir)) {
+    const sevenDaysAgo = Date.now() - 7 * 86_400_000;
+    for (const f of fs.readdirSync(dailyDir)) {
+      if (!f.endsWith(".md")) continue;
+      const m = f.match(/^(\d{4}-\d{2}-\d{2})\.md$/);
+      if (!m) continue;
+      const date = new Date(m[1] + "T00:00:00Z").getTime();
+      if (date >= sevenDaysAgo) entriesThisWeek++;
+    }
+  }
+
+  return {
+    last_flush_mtime: safeStatM(lastFlushStamp),
+    last_learn_scan_mtime: safeStatM(lastLearnScanStamp),
+    daily_log_days_this_week: entriesThisWeek,
+  };
+}
+
+function readinessWarnings(snap) {
+  const warnings = [];
+  if (!snap.install.healthy) warnings.push(`install: ${snap.install.missing_files.length} missing file(s) — run \`qualia-framework doctor\``);
+  if (snap.project.is_project) {
+    if (snap.project.verify_state === "FAILED") warnings.push(`phase ${snap.project.phase_line} has ${snap.project.verify_fail_count} FAIL marker(s)`);
+    if (snap.project.gap_cycles_used >= snap.project.gap_cycle_limit) warnings.push(`gap-cycle limit reached (${snap.project.gap_cycles_used}/${snap.project.gap_cycle_limit})`);
+  }
+  if (snap.erp.pending > 0) warnings.push(`ERP retry queue: ${snap.erp.pending} pending`);
+  if (snap.memory.last_flush_mtime === 0) warnings.push("knowledge has never been flushed — run `qualia-framework flush`");
+  return warnings;
+}
+
+function renderMarkdown(snap, warnings) {
+  const lines = [];
+  lines.push(`# Qualia status — ${new Date().toISOString()}`);
+  lines.push("");
+  lines.push(`Snapshot of installed framework + active project. Generated by \`qualia-framework status\`. Safe to paste into a handoff.`);
+  lines.push("");
+
+  // ── Install ──────────────────────────────────────
+  lines.push("## Install");
+  lines.push("| Field | Value |");
+  lines.push("|---|---|");
+  lines.push(`| Package version | \`${snap.install.package_version}\` |`);
+  lines.push(`| Installed version | \`${snap.install.installed_version}\` |`);
+  lines.push(`| Owner / role | ${snap.install.installed_by} / ${snap.install.role} |`);
+  lines.push(`| Targets | ${snap.install.targets.join(", ") || "(none)"} |`);
+  lines.push(`| Health | ${snap.install.healthy ? "✅ healthy" : `⚠ ${snap.install.missing_files.length} missing file(s)`} |`);
+  if (snap.install.missing_files.length > 0) {
+    lines.push("");
+    lines.push("Missing:");
+    for (const m of snap.install.missing_files.slice(0, 10)) lines.push(`- ${m}`);
+  }
+  lines.push("");
+
+  // ── Active project ───────────────────────────────
+  lines.push("## Active project");
+  if (!snap.project.is_project) {
+    lines.push(`Repo: \`${snap.project.repo}\` — not a Qualia project (no \`.planning/\` directory).`);
+  } else {
+    lines.push("| Field | Value |");
+    lines.push("|---|---|");
+    lines.push(`| Repo | \`${snap.project.repo}\` |`);
+    lines.push(`| Branch | \`${snap.project.branch}\` |`);
+    lines.push(`| ${snap.project.phase_line.replace(/\|/g, "\\|")} | |`);
+    lines.push(`| ${snap.project.status_line.replace(/\|/g, "\\|")} | |`);
+    lines.push(`| Verification | ${snap.project.verify_state === "FAILED" ? `⚠ FAILED (${snap.project.verify_fail_count} marker(s))` : snap.project.verify_state} |`);
+    lines.push(`| Gap cycles | ${snap.project.gap_cycles_used} / ${snap.project.gap_cycle_limit} |`);
+  }
+  lines.push("");
+
+  // ── Work in flight ───────────────────────────────
+  lines.push("## Work in flight");
+  const total = snap.work.modified.length + snap.work.staged.length + snap.work.untracked.length;
+  if (total === 0 && snap.work.commits_ahead === 0) {
+    lines.push("Clean.");
+  } else {
+    if (snap.work.commits_ahead > 0) lines.push(`- ${snap.work.commits_ahead} commit(s) ahead of upstream`);
+    if (snap.work.staged.length > 0) {
+      lines.push("");
+      lines.push(`### Staged (${snap.work.staged.length})`);
+      for (const f of snap.work.staged) lines.push(`- ${f}`);
+    }
+    if (snap.work.modified.length > 0) {
+      lines.push("");
+      lines.push(`### Modified (${snap.work.modified.length})`);
+      for (const f of snap.work.modified) lines.push(`- ${f}`);
+    }
+    if (snap.work.untracked.length > 0) {
+      lines.push("");
+      lines.push(`### Untracked (${snap.work.untracked.length})`);
+      for (const f of snap.work.untracked) lines.push(`- ${f}`);
+    }
+  }
+  lines.push("");
+
+  // ── ERP queue ────────────────────────────────────
+  lines.push("## ERP queue");
+  if (snap.erp.pending === 0) {
+    lines.push("No pending reports.");
+  } else {
+    lines.push(`${snap.erp.pending} pending. Last attempt ${humanAge(snap.erp.last_attempt)}.`);
+    lines.push("");
+    lines.push("Drain: `qualia-framework erp-flush`");
+  }
+  lines.push("");
+
+  // ── Memory ───────────────────────────────────────
+  lines.push("## Memory");
+  lines.push("| Field | Value |");
+  lines.push("|---|---|");
+  lines.push(`| Last flush | ${humanAge(snap.memory.last_flush_mtime)} |`);
+  lines.push(`| Last learning scan | ${humanAge(snap.memory.last_learn_scan_mtime)} |`);
+  lines.push(`| Daily-log days (last 7) | ${snap.memory.daily_log_days_this_week} |`);
+  lines.push("");
+
+  // ── Readiness warnings ───────────────────────────
+  if (warnings.length === 0) {
+    lines.push("## Readiness");
+    lines.push("✅ All green.");
+  } else {
+    lines.push("## Readiness warnings");
+    for (const w of warnings) lines.push(`- ⚠ ${w}`);
+  }
+  lines.push("");
+
+  lines.push("---");
+  lines.push(`_Generated in ${Date.now() - _start}ms by \`qualia-framework status\`._`);
+  return lines.join("\n") + "\n";
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const snap = {
+    install: collectInstallHealth(),
+    project: collectActiveProject(),
+    work: collectWorkInFlight(),
+    erp: collectErpQueue(),
+    memory: collectMemoryState(),
+    generated_at: new Date().toISOString(),
+  };
+  const warnings = readinessWarnings(snap);
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify({ ...snap, warnings }, null, 2) + "\n");
+  } else {
+    const md = renderMarkdown(snap, warnings);
+    if (args.write) {
+      const out = args.writePath || path.join(process.cwd(), "STATUS.md");
+      fs.writeFileSync(out, md);
+      console.log(`Wrote ${out}`);
+    } else {
+      process.stdout.write(md);
+    }
+  }
+
+  if (args.exitCode && warnings.length > 0) {
+    process.exit(1);
+  }
+}
+
+module.exports = { main, collectInstallHealth, collectActiveProject, collectWorkInFlight, collectErpQueue, collectMemoryState, readinessWarnings };
+
+if (require.main === module) {
+  try { main(); }
+  catch (e) {
+    console.error(`status failed: ${e.message}`);
+    process.exit(1);
+  }
+}

package/guide.md

@@ -1,33 +1,11 @@
-# Qualia Developer Guide (v6.3.0)
+# 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.3.0 is the harness hardening patch.** The default command surface is 23 active skills, retired helper sources are removed and pruned from older installs, `/qualia-polish --vibe` absorbs the old vibe command, `qualia-framework eval --run --write` produces scored eval artifacts, and PASS transitions now require clean machine evidence when a phase contract exists.
+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.7 carries forward.** 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`.
-
-**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-polish --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 23 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-polish --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
 
@@ -93,8 +71,8 @@ Append `--auto` to `/qualia-new` and the framework chains every step:
 | 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 |
 | Road view | `/qualia-road` | View and navigate journey/milestone/phase status |
-| Lost? | `/qualia` | Mechanical next-command router |
-| Confused? | `/qualia` | 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
 
@@ -118,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` 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   ← "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.
@@ -153,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` |
+| 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/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);
+}