qualia-framework 4.1.0 → 4.3.0

package/docs/reviews/v4.1.0-audit.md

@@ -0,0 +1,263 @@
+# Qualia Framework v4.1.0 — Production Review
+
+**Date:** 2026-04-22
+**Scope:** 26 skills, 8 agents, 7 hooks, 4 bin scripts, 6 rules, templates, docs, HTML surfaces
+**Method:** 4 parallel specialist audits (commands/skills, hooks/state, memory/knowledge, design/UX)
+**Findings:** 142 total across 4 dimensions
+
+---
+
+## Summary
+
+| Dimension | Critical | High | Medium | Low | Score |
+|-----------|----------|------|--------|-----|-------|
+| Commands & Skills | 5 | 14 | 17 | 9 | **2/5** |
+| Hooks & State | 0 | 3 | 16 | 13 | **3/5** |
+| Memory & Knowledge | 3 | 5 | 6 | 6 | **2/5** |
+| Design & UX | 0 | 11 | 15 | 11 | **2/5** |
+| **Total** | **8** | **33** | **54** | **47** | **2.25/5** |
+
+**Verdict: FAIL** — 8 critical blockers, 33 high findings. Framework is functional for OWNER daily use but structurally unsound for multi-employee scale. Ship v4.2.0 with the critical-fix batch before onboarding new team members.
+
+---
+
+## Top 10 Critical & High Issues (fix first)
+
+### 1. `grounding.md` is a phantom for existing installs [CRITICAL]
+**Where:** `skills/qualia-{build,plan,verify,design}/SKILL.md`, `agents/{builder,planner,plan-checker,verifier}.md` — all `@~/.claude/rules/grounding.md` references.
+**Reality:** File exists in repo `rules/grounding.md` but **not in installed** `~/.claude/rules/` for users who upgraded from v4.0.x (current local install is missing it). install.js copies it on fresh install only; no self-healing check on version bump.
+**Impact:** Every planner, builder, plan-checker, verifier spawn silently gets no Grounding Protocol and no Severity Rubric. All 1–5 scores by verifier are improvised. Affects every Road phase, every project, silently.
+**Fix:** Add a hook or install.js post-upgrade routine that compares `rules/` contents and copies missing files. Emit a warning if critical files missing.
+
+### 2. Builder agent never reads knowledge base [CRITICAL]
+**Where:** `agents/builder.md` — zero references to `~/.claude/knowledge/`.
+**Impact:** Patterns in `learned-patterns.md`, `supabase-patterns.md`, `common-fixes.md` reach the planner but not the agent that writes code. "Always use `lib/supabase/server.ts` for mutations" never reaches the coder.
+**Fix:** Add a "load relevant patterns" step to builder.md's preamble; pipe through `@~/.claude/knowledge/learned-patterns.md` like grounding.md.
+
+### 3. 11 of 14 knowledge files are invisible to every skill [CRITICAL]
+**Where:** `~/.claude/knowledge/` has `qualia-context.md`, `deployment-map.md`, `supabase-patterns.md`, `voice-agent-patterns.md`, `employees.md`, `claudecode-bible.md`, `optimization-research-2026.md`, `session-digest.md`, `email-signature.html`, etc. — grepping the framework for these filenames returns zero results.
+**Impact:** Every skill hardcodes filenames (`cat ~/.claude/knowledge/common-fixes.md`). New knowledge files are dead weight. `session-digest.md` hasn't updated since Apr 12 — the hook that wrote it no longer exists.
+**Fix:** Replace hardcoded cats with `node ~/.claude/bin/knowledge.js load --type <X>` — a discovery utility that indexes and merges tiers. See Memory Architecture proposal §B below.
+
+### 4. No per-employee memory scoping [CRITICAL]
+**Where:** All memory is in `~/.claude/knowledge/` with no user scope. Hasan, Fawzi, Moayad all share the same global knowledge files.
+**Impact:** Personal preferences mix with universal patterns. `employees.md` is a flat roster, not a scoping mechanism.
+**Fix:** 3-tier memory architecture — see §B.
+
+### 5. `qualia-report` ERP upload: silent injection & auth failures [CRITICAL]
+**Where:** `skills/qualia-report/SKILL.md:84-87, 114-163`.
+- Empty `API_KEY` → sends `Authorization: Bearer ` (blank); 401 handler says "Ask Fawzi" without diagnosing.
+- `SUBMITTED_BY` shell-interpolated into `node -e` string → single quote in git user.name breaks silently.
+- `CLIENT_REPORT_ID` fallback to empty string on state.js failure → commit message loses the ID; ERP payload corrupted.
+**Fix:** Add `[ -z "$API_KEY" ] && fail "No ERP key"` guard. Pipe SUBMITTED_BY via env var, not string interp. Validate report_id non-empty before proceeding.
+
+### 6. Triple overlap: `qualia-optimize` vs `qualia-review` vs `qualia-polish` [HIGH]
+**Where:** All three run the same grep patterns (fonts, max-width, gradients, service_role, empty catches, sequential awaits, `<img>` without next/image). Different output files (OPTIMIZE.md / REVIEW.md / inline fix). Different severity scales. User gets three reports about the same issues.
+**Fix:** Pick one. Recommend: `qualia-review` = detect-only (grep + score), `qualia-polish` = fix-only (applies known transforms), delete `qualia-optimize` or repurpose it as a parallel-agent wrapper around review+polish.
+
+### 7. 4 skills are orphans — never invoked by the Road [HIGH]
+**Where:** `qualia-test`, `qualia-debug`, `qualia-task`, `qualia-quick` are never auto-triggered by any Road step. The Road has no automated test gate between build and verify. If verification fails, the Road goes to `/qualia-plan --gaps`, not `/qualia-debug`.
+**Fix:** Add `/qualia-test` as a hard gate inside `/qualia-build` post-wave. Route verify-fail → `/qualia-debug` → `/qualia-plan --gaps` chain. Kill `qualia-task` (absorbed into `/qualia-quick`).
+
+### 8. Color palette drift across surfaces [HIGH]
+**Where:** `TEAL_DIM` differs `rgb(0,130,135)` (statusline.js:19) vs `rgb(0,140,145)` (qualia-ui.js:31). `DIM` differs `rgb(80,90,100)` vs `rgb(100,110,120)` across 3 files. Brand teal in demo.html `#00ced9` vs help.html `#00ced1`. Display fonts split: Fraunces (demo) vs Outfit (help).
+**Fix:** Create `bin/colors.js` as single source of truth; import in all 5 surfaces. Unify brand token vocabulary between demo.html and help.html.
+
+### 9. Statusline shows installer name, not operator [HIGH]
+**Where:** `bin/statusline.js:292` — reads `.qualia-config.json` which is set at install time.
+**Impact:** On a shared machine, all operators see the installer's name. `Qualia member: Hasan` even when Fawzi is driving.
+**Fix:** Read from a session-scoped identity (env var, git user.name) or add `/qualia-whoami` switch.
+
+### 10. `/qualia-ship` has no state guard and no security depth [HIGH]
+**Where:** `skills/qualia-ship/SKILL.md`.
+- No `state.js check` at start; can invoke from any state.
+- Security check only greps `service_role` — misses hardcoded keys, tracked `.env`, `dangerouslySetInnerHTML`.
+- Post-deploy verification uses literal `{domain}` placeholder — expects LLM to hallucinate URL.
+**Fix:** Add state-preconditions block (must be `polished` or final-phase verified). Inline the full qualia-review CRITICAL checks. Read `deployed_url` from tracking.json like `/qualia-handoff` does.
+
+---
+
+## Dimension Deep-Dives
+
+### A. Silent Fails (selected — 15 most dangerous)
+
+| # | File:line | Severity | Silent behavior |
+|---|-----------|----------|-----------------|
+| A1 | `state.js:179,229` | MED | `readTracking/readState` swallow corrupt JSON as "missing" → user told "No .planning/" when file is corrupt |
+| A2 | `state.js:59` | MED | Corrupt journal silently cleared, no log |
+| A3 | `state.js:107` | HIGH | Lock timeout falls through silently — concurrent writes possible |
+| A4 | `pre-push.js:22,47` | HIGH | No lock coordination with state.js; assumes cwd is repo root |
+| A5 | `pre-deploy-gate.js:51` | MED | `package.json` missing → ALL gates silently skipped |
+| A6 | `pre-deploy-gate.js:146` | MED | File read failure → security scan silently skips that file |
+| A7 | `session-start.js:128` | LOW | Top-level catch; crash inside try → no banner, no error, trace records "allow" anyway |
+| A8 | `qualia-report/SKILL.md:84` | CRIT | Empty pipe chain → report_id becomes `""`, commit loses ID |
+| A9 | `qualia-report/SKILL.md:114` | CRIT | Empty API key → blank Bearer token sent to ERP |
+| A10 | `qualia-handoff/SKILL.md:39` | CRIT | Malformed tracking.json → empty URL; verification curl hits blank target |
+| A11 | `qualia-help/SKILL.md:44` | HIGH | Missing template → sed writes empty file → blank help page opens; "ok" message still printed |
+| A12 | `qualia-verify/SKILL.md:65` | HIGH | `FRONTEND=true` never set — frontend detection broken; browser QA never spawns |
+| A13 | `migration-guard.js:96` | MED | DROP TABLE check is file-global, not per-statement — one `IF EXISTS` masks another unguarded DROP |
+| A14 | `state.js:329` | MED | Progress bar: phase 1/5 shows 0%, phase 5/5 shows 80% — never 100% |
+| A15 | `cli.js:827` | HIGH | ERP ping uses `curl` — unavailable on older Windows |
+
+### B. Memory Architecture — 3-Tier Proposal
+
+Current state is flat, untiered, and half-invisible. Proposed structure:
+
+```
+Tier 1 — FRAMEWORK (universal, ships with framework)
+  ~/.claude/knowledge/framework/
+  ├─ stack-patterns.md       ← Next.js, Supabase, Vercel
+  ├─ voice-patterns.md       ← Retell, ElevenLabs, Telnyx
+  ├─ security-patterns.md    ← RLS, service_role, env
+  ├─ common-fixes.md         ← cross-project fixes
+  └─ KNOWLEDGE-INDEX.md      ← auto-generated manifest
+
+Tier 2 — EMPLOYEE (per-user, ~/.claude/ scoped by team code)
+  ~/.claude/knowledge/employee/
+  ├─ preferences.md          ← my coding style, timezone, tools
+  ├─ my-patterns.md          ← things I've learned
+  ├─ my-fixes.md             ← errors I've solved
+  └─ KNOWLEDGE-INDEX.md
+
+Tier 3 — PROJECT (per-repo, version-controlled with project)
+  .planning/knowledge/
+  ├─ client-prefs.md         ← this client's brand/stack
+  ├─ project-patterns.md     ← project-specific gotchas
+  ├─ deployment.md           ← this project's deploy notes
+  └─ KNOWLEDGE-INDEX.md
+```
+
+**Discovery utility:** `bin/knowledge.js` — single CLI for all skills.
+```
+knowledge.js load --type patterns     # merges all 3 tiers, project overrides employee overrides framework
+knowledge.js search "supabase RLS"    # searches all tiers, labels source
+knowledge.js index                    # regenerates INDEX files
+knowledge.js promote --from employee --to framework  # for /qualia-learn
+```
+
+**Staleness:** INDEX tracks `last_verified` per file. Entries >30 days get `[STALE]` tag in merge output.
+
+**Integration with Claude native memory:** Keep `CLAUDE_CODE_DISABLE_AUTO_MEMORY=0`. Native memory captures conversational context; Qualia knowledge captures structured reusable patterns. Add `/qualia-learn --promote` to migrate native → structured. Statusline shows both counts: `K:14 M:4`.
+
+**Migration (one-off script):**
+1. Move universal bits of `learned-patterns.md` → `framework/stack-patterns.md`
+2. Move project-specific section → each project's `.planning/knowledge/`
+3. Move `email-signature.html` out of knowledge/ (not knowledge — asset)
+4. Delete `session-digest.md` (dead)
+5. Update 5 reader skills to use `knowledge.js load`
+
+### C. Commands That Don't Fit the Road
+
+| Skill | Status | Recommendation |
+|-------|--------|----------------|
+| `qualia-task` | Orphan, overlaps `qualia-quick` | **Delete** — fold into `/qualia-quick --proper` flag |
+| `qualia-quick` | Orphan | Keep, add `--proper` flag for atomic-commit behavior of task |
+| `qualia-test` | Orphan | Integrate into `/qualia-build` post-wave as hard gate |
+| `qualia-debug` | Orphan, only suggested | Auto-invoke after verify-fail before `/qualia-plan --gaps` |
+| `qualia-design` | Duplicates polish ~90% | **Merge into** `/qualia-polish`; delete standalone |
+| `qualia-optimize` | Overlaps review+polish | Repurpose as parallel-agent wrapper; specialists run review+polish in fan-out |
+| `qualia-review` | Orphan, no state guard | Integrate as mandatory step between build and verify (code review before goal check) |
+| `qualia-map` | Optional brownfield | Keep, but add auto-trigger on `/qualia-new` if `package.json` exists |
+| `qualia-research` | Optional | Keep as phase-depth option |
+| `qualia-discuss` | Optional | Keep |
+| `qualia-idk` | Alternate router | Keep — genuine diagnostic, not alias (fix help.html:410 description) |
+| `qualia-learn` | Meta | Keep, extend with tier promotion (see §B) |
+| `qualia-help` | Reference | Keep |
+| `qualia-skill-new` | Authoring | Keep |
+
+### D. Missing from the Road (gaps)
+
+1. **Automated test gate** — no skill runs tests after build, before verify. Add to `/qualia-build`.
+2. **Inter-phase code review** — goal-backward verify doesn't check code quality. Add `/qualia-review` between build and verify.
+3. **Adversarial/red-team build loop** — per harness-engineering research (Anthropic GAN pattern, Archon adversarial-dev). Generator ↔ evaluator with pre-negotiated sprint contract. Add `/qualia-adversarial` or fold into `/qualia-build --adversarial`.
+4. **Continuous reviewer agents** — no background persona reviewers (security, reliability, frontend-architect) on each commit. Stripe Minion pattern; Lopopolo "every push" pattern.
+5. **Component freshness** — no skill pulls latest shadcn/Radix versions or checks for staleness. Proposal below.
+
+### E. Component Fetching (user's explicit ask)
+
+No current mechanism. Framework has no `shadcn`, `radix`, or `component` references.
+
+**Proposal: `/qualia-components` skill**
+```
+/qualia-components add button card dialog   # pulls latest shadcn via `npx shadcn@latest add`
+/qualia-components update                    # bumps versions; writes .planning/component-changelog.md
+/qualia-components check                     # reports N components > X days stale
+```
+- Integrates with existing `vercel-plugin:shadcn` skill for shadcn ops
+- Uses WebFetch from researcher agent to pull latest docs (`https://ui.shadcn.com/docs/components/{name}`)
+- Writes a diff summary so planner knows what changed
+- Add a mandatory check inside `/qualia-verify`: flag components > 1 major version behind
+
+**Do not auto-update during builds.** Component breaks should be explicit, versioned, verified.
+
+### F. Design Polish Roadmap (5 phases)
+
+**Phase 1 — Color unification (1 day)**
+Create `bin/colors.js`; delete inline palettes in statusline, qualia-ui, session-start, install, cli. Fix TEAL_DIM, DIM, brand teal mismatches. DIM must pass WCAG AA (4.5:1) on dark terminals — currently fails at ~3.2:1.
+
+**Phase 2 — Statusline ergonomics (1 day)**
+Terminal-width guard on Line 1 (progressive truncation: identity → memory → worktree → agent). Add milestone indicator `M2 P3/5 T2/4`. Add last-error from `tracking.json.last_error`. Format duration as `Xh Ym` over 60min. Add burn rate `$/min`.
+
+**Phase 3 — HTML modernization (1 day)**
+help.html: replace `@import` with `<link rel="preconnect"><link rel="stylesheet">`. Unify design tokens with demo.html. Adopt `@container` queries for card grids. Add `color-scheme: dark`. Fix **demo.html:506 `</span>` → `</div>`** (broken DOM). Fix help.html:410 `/qualia-idk` description (currently says "Alias for /qualia" — wrong).
+
+**Phase 4 — Skill description cleanup (half day)**
+Trim 10 skills over 30-word descriptions. Add trigger phrases to 4 that have none (report, ship, verify, build). Cap at 20 words + triggers for autocomplete readability.
+
+**Phase 5 — Component fetching (1-2 days)** — see §E.
+
+### G. Team Ergonomics — What's Missing
+
+For a 5-person team operating from a shared fleet:
+- **Per-operator identity** on statusline (not installer)
+- **Active agent name/count** — which subagent is running right now
+- **Milestone progress** alongside phase progress (`M2/4 P3/5`)
+- **Shared-state indicator** — is someone else editing this project?
+- **Last verification score** from tracking.json
+- **Blocker summary** beyond the pill (currently only shows count, no first-line)
+
+---
+
+## Action Roadmap (priority-ordered)
+
+### v4.1.1 Hotfix (ship this week)
+1. Auto-copy missing rules on version bump (fixes grounding.md phantom)
+2. Guard empty API_KEY in qualia-report
+3. Fix broken `</span>` in demo.html:506
+4. Fix help.html:410 `/qualia-idk` description
+5. Add state guard to `/qualia-ship`
+
+### v4.2.0 — Structural (2 weeks)
+1. 3-tier memory architecture + `bin/knowledge.js`
+2. Merge `qualia-design` into `qualia-polish`, delete orphan `qualia-task`
+3. Unified `bin/colors.js`
+4. Builder agent loads knowledge
+5. Integrate `/qualia-test` as build gate, `/qualia-debug` on verify-fail
+6. cwd → git root resolution for state.js, pre-push, pre-compact (fixes 3 MED findings at once)
+
+### v4.3.0 — Harness patterns (4 weeks)
+1. Adversarial build mode (generator↔evaluator GAN-style)
+2. Continuous reviewer agents (security/reliability/frontend personas on every push)
+3. Source-code structural tests (file<350 lines, schema dedup, no-unknown)
+4. `/qualia-components` skill
+
+### v4.4.0 — Team-scale (ongoing)
+1. Per-operator identity on statusline
+2. Shared-state coordination lock
+3. Token burn rate + milestone progress indicators
+4. Knowledge staleness tracking + auto-prune
+
+---
+
+## Verdict
+
+**Strengths** — The Road skeleton is sound. Context isolation, goal-backward verification, story-file plans, wave-based parallelization, and the state machine are all genuinely good harness patterns (confirmed by comparison to Anthropic/OpenAI/Archon research).
+
+**Structural debt** — Three clusters compound risk:
+1. **Invisible dependencies** — grounding.md, 11 knowledge files, builder↔knowledge disconnect. The framework believes things are loaded that aren't.
+2. **Silent failures** — 15 high-impact silent-fail paths where users get "ok" messages while the underlying operation produced garbage.
+3. **Orphan skills** — 4 commands never touch the Road; 3 triple-overlap. Mental overhead for the team is real.
+
+**Shipping bar** — This review would FAIL `/qualia-ship` on a client project. The framework needs v4.1.1 hotfix before onboarding the next employee and v4.2.0 before the next major client delivery.
+
+Raw audit transcripts (142 findings in full) are available via the 4 background agent outputs if deeper context is needed on any specific finding.

package/hooks/auto-update.js

@@ -110,6 +110,11 @@ try {
         detected_at: new Date().toISOString(),
       }, null, 2));
     } catch {}
+    // Invalidate the session-start health cache so the next session re-checks
+    // whether new critical files shipped in the latest version are installed.
+    try {
+      fs.unlinkSync(path.join(CLAUDE_DIR, ".qualia-install-health.json"));
+    } catch {}
     _trace("auto-update", "allow", { reason: "notification-written", current: cfg.version, latest });
   } else {
     // Already up to date — clear any stale notification file.

package/hooks/git-guardrails.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/git-guardrails.js — block destructive git commands.
+//
+// PreToolUse hook on `Bash`. Reads the proposed command from the Claude Code
+// hook payload (stdin JSON: tool_input.command) and exits 2 to BLOCK, 0 to
+// allow. Cross-platform (Windows/macOS/Linux), zero shell dependencies.
+//
+// Patterns blocked unconditionally:
+//   • git push --force / -f to main or master (use --force-with-lease instead)
+//   • git push --force / -f from current branch when current branch is main
+//   • git reset --hard <anything> when on main/master (would discard uncommitted)
+//   • git clean -fd / -fdx (no recovery — irreversible)
+//   • git branch -D main / master (destroys the branch)
+//   • rm -rf .git (nukes repo history)
+//
+// Escape hatch:
+//   QUALIA_ALLOW_DESTRUCTIVE=1 in env → all checks pass through (use sparingly,
+//   document the reason in your commit message).
+//
+// This hook complements branch-guard.js, which blocks NORMAL pushes by EMPLOYEE
+// to main. git-guardrails.js applies to EVERYONE (OWNER too) for irreversible
+// operations — guardrails, not permissions.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawnSync } = require("child_process");
+
+const _traceStart = Date.now();
+
+function _trace(result, extra) {
+  try {
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const entry = {
+      hook: "git-guardrails",
+      result,
+      timestamp: new Date().toISOString(),
+      duration_ms: Date.now() - _traceStart,
+      ...extra,
+    };
+    const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {}
+}
+
+function block(reason, suggestion) {
+  const lines = [
+    `BLOCKED: ${reason}`,
+    suggestion ? `Suggestion: ${suggestion}` : null,
+    `Override (use sparingly): QUALIA_ALLOW_DESTRUCTIVE=1`,
+  ].filter(Boolean);
+  for (const l of lines) {
+    console.error(l);
+    console.log(l);
+  }
+  _trace("block", { reason });
+  process.exit(2);
+}
+
+// Honor escape hatch first — keeps tests and emergency overrides cheap.
+if (process.env.QUALIA_ALLOW_DESTRUCTIVE === "1") {
+  _trace("allow", { reason: "QUALIA_ALLOW_DESTRUCTIVE=1" });
+  process.exit(0);
+}
+
+// Read hook payload from stdin (Claude Code passes JSON; if no stdin, allow).
+let payload = "";
+try {
+  if (!process.stdin.isTTY) payload = fs.readFileSync(0, "utf8");
+} catch {}
+
+let command = "";
+try {
+  if (payload) command = (JSON.parse(payload).tool_input || {}).command || "";
+} catch {}
+
+if (!command) {
+  _trace("allow", { reason: "no-command" });
+  process.exit(0);
+}
+
+// Normalize for matching: collapse whitespace, lowercase the flags.
+// We deliberately match on substrings — chained commands (`x && y`) and
+// quoted arguments still get scanned for the dangerous primitive.
+const cmd = command.replace(/\s+/g, " ").trim();
+
+// Helper: detect current git branch (silent on failure).
+function currentBranch() {
+  try {
+    const r = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+      encoding: "utf8",
+      timeout: 2000,
+      shell: process.platform === "win32",
+    });
+    return (r.stdout || "").trim();
+  } catch {
+    return "";
+  }
+}
+
+// ── Rule 1: nuking .git ───────────────────────────────────
+if (/\brm\s+(-[a-z]*r[a-z]*f|-[a-z]*f[a-z]*r)\b[^|;&]*\.git(\b|$|\/)/.test(cmd)) {
+  block(
+    "rm -rf .git would destroy all repository history",
+    "If you really need to reinitialize, do it deliberately — back up first",
+  );
+}
+
+// ── Rule 2: git clean -fd / -fdx ──────────────────────────
+// `git clean -fd` deletes untracked files and directories with no recovery.
+// We block this because the recovery cost is high and the agent rarely needs
+// it — `git stash` or moving the file is almost always the right answer.
+if (/\bgit\s+clean\s+(-[a-zA-Z]*f[a-zA-Z]*d|-[a-zA-Z]*d[a-zA-Z]*f)/.test(cmd)) {
+  block(
+    "git clean -fd permanently deletes untracked files",
+    "Use `git stash --include-untracked` if you need a clean tree but might want the files later",
+  );
+}
+
+// ── Rule 3: git branch -D main / master ───────────────────
+if (/\bgit\s+branch\s+-D\s+(main|master)\b/.test(cmd)) {
+  block(
+    "deleting main/master branch is destructive",
+    "If this is intentional, run it manually outside Claude with QUALIA_ALLOW_DESTRUCTIVE=1",
+  );
+}
+
+// ── Rule 4: git push --force to main / master ─────────────
+// Match `git push ... --force ... main` or `git push ... -f ... main` (and
+// master). Excludes --force-with-lease which is the safe variant.
+const isPush = /\bgit\s+push\b/.test(cmd);
+const hasForce =
+  /\s(--force|-f)(\s|$)/.test(" " + cmd + " ") &&
+  !/--force-with-lease/.test(cmd);
+
+if (isPush && hasForce) {
+  // Targets main/master explicitly: `git push origin main`, `git push --force origin main`
+  if (/\b(main|master)\b/.test(cmd)) {
+    block(
+      "force-pushing to main/master rewrites shared history",
+      "Use `git push --force-with-lease origin <branch>` on a feature branch instead",
+    );
+  }
+  // Or pushing the current branch when on main
+  const branch = currentBranch();
+  if (branch === "main" || branch === "master") {
+    block(
+      `force-pushing while on ${branch} (rewrites shared history)`,
+      "Switch to a feature branch first: `git checkout -b feat/<name>`",
+    );
+  }
+}
+
+// ── Rule 5: git reset --hard while on main / master ───────
+if (/\bgit\s+reset\s+--hard\b/.test(cmd)) {
+  const branch = currentBranch();
+  if (branch === "main" || branch === "master") {
+    block(
+      `git reset --hard while on ${branch} discards uncommitted work and rewrites local history`,
+      "Switch to a feature branch first, or use `git stash` to preserve work",
+    );
+  }
+}
+
+_trace("allow", {});
+process.exit(0);

package/hooks/pre-push.js

@@ -74,10 +74,16 @@ function commitStamp() {
   // --no-verify: skip user pre-commit hooks (this is a bot commit).
   // --no-gpg-sign: don't pop a signing prompt for a chore commit.
   // --author: attribute to bot, not user.
-  const add = git(["add", TRACKING]);
+  // -c core.autocrlf=false: without this, Windows installs with autocrlf=true
+  // normalize the just-written LF-terminated JSON to CRLF in the index, so the
+  // diff against HEAD is empty, the commit fails, and we roll back the stamp.
+  // Forcing autocrlf=false for this one add/commit pair preserves the JSON as
+  // written and keeps the stamp consistent across platforms.
+  const add = git(["-c", "core.autocrlf=false", "add", TRACKING]);
   if (add.status !== 0) return { skipped: "git-add-failed", error: add.stderr };
 
   const commit = git([
+    "-c", "core.autocrlf=false",
     "commit",
     "--no-verify",
     "--no-gpg-sign",

package/hooks/session-start.js

@@ -25,6 +25,41 @@ const UI = path.join(HOME, ".claude", "bin", "qualia-ui.js");
 const STATE_FILE = path.join(".planning", "STATE.md");
 const CONTINUE_HERE = ".continue-here.md";
 const NOTIF_FILE = path.join(HOME, ".claude", ".qualia-update-available.json");
+const HEALTH_FILE = path.join(HOME, ".claude", ".qualia-install-health.json");
+
+// Critical files referenced by skills via @-import. If any are missing, skills
+// silently get empty context and produce ungrounded output. We spot-check these
+// on session-start and write a cached result (1-per-day) to HEALTH_FILE so we
+// don't stat on every session.
+const CRITICAL_FILES = [
+  path.join(HOME, ".claude", "rules", "grounding.md"),
+  path.join(HOME, ".claude", "rules", "security.md"),
+  path.join(HOME, ".claude", "rules", "frontend.md"),
+  path.join(HOME, ".claude", "rules", "deployment.md"),
+  path.join(HOME, ".claude", "bin", "state.js"),
+];
+
+function checkInstallHealth() {
+  // Returns null if healthy, or an array of missing files if damaged.
+  // Caches result in HEALTH_FILE for 24h to avoid repeated stat overhead.
+  try {
+    if (fs.existsSync(HEALTH_FILE)) {
+      const cached = JSON.parse(fs.readFileSync(HEALTH_FILE, "utf8"));
+      const age = Date.now() - (cached.checked_at || 0);
+      if (age < 24 * 60 * 60 * 1000) {
+        return cached.missing && cached.missing.length ? cached.missing : null;
+      }
+    }
+  } catch {}
+  const missing = CRITICAL_FILES.filter((f) => !fs.existsSync(f));
+  try {
+    fs.writeFileSync(
+      HEALTH_FILE,
+      JSON.stringify({ checked_at: Date.now(), missing }, null, 2),
+    );
+  } catch {}
+  return missing.length ? missing : null;
+}
 
 function runUi(...args) {
   if (!fs.existsSync(UI)) return;
@@ -94,9 +129,25 @@ function maybeRenderUpdateBanner() {
   } catch {}
 }
 
+function renderHealthWarning(missing) {
+  // Loud, non-blocking warning when critical install files are missing.
+  // Tells the user exactly what to run — never silent.
+  const label = missing.map((f) => path.basename(f)).join(", ");
+  if (fs.existsSync(UI)) {
+    runUi("warn", `Install incomplete — missing: ${label}`);
+    runUi("info", "Run: npx qualia-framework@latest install");
+  } else {
+    console.log(`QUALIA: Install incomplete — missing ${label}`);
+    console.log(`QUALIA: Run: npx qualia-framework@latest install`);
+  }
+}
+
 try {
   maybeRenderUpdateBanner();
 
+  const healthMissing = checkInstallHealth();
+  if (healthMissing) renderHealthWarning(healthMissing);
+
   if (!fs.existsSync(UI)) {
     fallbackText();
   } else if (fs.existsSync(STATE_FILE)) {
@@ -125,8 +176,23 @@ try {
     console.log(`    ${TEAL}/qualia-quick${RESET}  ${DIM}Quick fix (skip planning)${RESET}`);
     console.log("");
   }
-} catch {
-  // Deliberately silent — hook must never fail
+} catch (e) {
+  // Hook must never exit non-zero. Log to trace so silent crashes are visible
+  // in analytics, but do not print to stderr (would clutter the banner).
+  try {
+    const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");
+    if (!fs.existsSync(traceDir)) fs.mkdirSync(traceDir, { recursive: true });
+    const file = path.join(traceDir, `${new Date().toISOString().split("T")[0]}.jsonl`);
+    fs.appendFileSync(
+      file,
+      JSON.stringify({
+        hook: "session-start",
+        result: "error",
+        error: String(e && e.message ? e.message : e),
+        timestamp: new Date().toISOString(),
+      }) + "\n",
+    );
+  } catch {}
 }
 
 function _trace(hookName, result, extra) {