qualia-framework 4.1.1 → 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/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/stop-session-log.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+// ~/.claude/hooks/stop-session-log.js — append a one-line session checkpoint
+// to ~/.claude/knowledge/daily-log/{YYYY-MM-DD}.md.
+//
+// Stop hook (fires when a Claude Code turn ends). This is the seed of the
+// memory layer (v4.2.0): every turn that produced something noteworthy gets a
+// line in today's daily log. Future versions will run an LLM "flush" job over
+// the daily log to promote durable knowledge into the wiki tier.
+//
+// Design constraints:
+//   • NEVER block — exit 0 always, even on internal failure.
+//   • Fast — under 100ms, no network, no LLM call. The log is mechanical.
+//   • Cheap to skip — if there's been no git activity since the last write,
+//     and we wrote a line within the last 5 minutes, we skip. Daily log
+//     stays scannable instead of becoming a turn-by-turn replay.
+//   • No PII / secrets — only project name, branch, phase, task counts,
+//     commit count. Never the contents of files or env vars.
+//
+// Format: append to today's file under a single H2 header per project:
+//
+//   ## qualia-framework
+//   - 14:32 · branch=feat/x · phase=2/4 · tasks=3/5 · commits=2 · touched=src/foo.ts,src/bar.ts
+//   - 16:08 · branch=feat/x · phase=2/4 · tasks=4/5 · commits=4
+//
+// Cross-platform (Windows/macOS/Linux). Zero shell dependencies.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { spawnSync } = require("child_process");
+
+const _traceStart = Date.now();
+
+const KNOWLEDGE_DIR = path.join(os.homedir(), ".claude", "knowledge");
+const DAILY_DIR = path.join(KNOWLEDGE_DIR, "daily-log");
+const LAST_WRITE_FILE = path.join(os.homedir(), ".claude", ".qualia-last-session-log");
+const MIN_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+
+function _trace(result, extra) {
+  try {
+    const traceDir = path.join(os.homedir(), ".claude", ".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: "stop-session-log",
+        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;
+  }
+}
+
+try {
+  // ── Skip if too soon since last write ────────────────────
+  const now = Date.now();
+  let lastWrite = 0;
+  try {
+    if (fs.existsSync(LAST_WRITE_FILE)) {
+      lastWrite = parseInt(fs.readFileSync(LAST_WRITE_FILE, "utf8").trim(), 10) || 0;
+    }
+  } catch {}
+  if (now - lastWrite < MIN_INTERVAL_MS) {
+    _trace("skip", { reason: "interval", since_last_ms: now - lastWrite });
+    process.exit(0);
+  }
+
+  // ── Resolve project context ──────────────────────────────
+  // Operate from the cwd; if not a git repo, fall back to basename.
+  const cwd = process.cwd();
+  const repoRoot = git(["rev-parse", "--show-toplevel"], { cwd }) || cwd;
+  const project = path.basename(repoRoot);
+  const branch = git(["rev-parse", "--abbrev-ref", "HEAD"], { cwd: repoRoot }) || "";
+
+  // Phase + task info from .planning/tracking.json (Qualia projects only).
+  let phase = "";
+  let tasks = "";
+  const tracking = readJson(path.join(repoRoot, ".planning", "tracking.json"));
+  if (tracking) {
+    const p = tracking.phase || 0;
+    const pt = tracking.phase_total || 0;
+    if (pt > 0) phase = `${p}/${pt}`;
+    const td = tracking.tasks_done || 0;
+    const tt = tracking.tasks_total || 0;
+    if (tt > 0) tasks = `${td}/${tt}`;
+  }
+
+  // Commits in this session window — heuristic: commits in last 8 hours by us.
+  // (Stop fires per turn, so a tighter window misses session boundaries.)
+  const commitCount = (() => {
+    const out = git(["log", "--since=8.hours", "--pretty=oneline"], { cwd: repoRoot });
+    if (!out) return 0;
+    return out.split("\n").filter(Boolean).length;
+  })();
+
+  // Top 3 touched files (uncommitted) — useful for resuming next session.
+  const touched = (() => {
+    const out = git(["diff", "--name-only", "HEAD"], { cwd: repoRoot });
+    if (!out) return [];
+    return out.split("\n").filter(Boolean).slice(0, 3);
+  })();
+
+  // Skip if literally nothing happened — no commits, no diff, no phase progress.
+  if (commitCount === 0 && touched.length === 0 && !phase) {
+    _trace("skip", { reason: "no-activity" });
+    process.exit(0);
+  }
+
+  // ── Compose the line ─────────────────────────────────────
+  const time = new Date().toTimeString().slice(0, 5); // HH:MM, local time
+  const parts = [`${time}`];
+  if (branch) parts.push(`branch=${branch}`);
+  if (phase) parts.push(`phase=${phase}`);
+  if (tasks) parts.push(`tasks=${tasks}`);
+  if (commitCount > 0) parts.push(`commits=${commitCount}`);
+  if (touched.length > 0) parts.push(`touched=${touched.join(",")}`);
+  const line = `- ${parts.join(" · ")}`;
+
+  // ── Append to today's file ───────────────────────────────
+  if (!fs.existsSync(DAILY_DIR)) fs.mkdirSync(DAILY_DIR, { recursive: true });
+  const today = new Date().toISOString().split("T")[0];
+  const file = path.join(DAILY_DIR, `${today}.md`);
+
+  let existing = "";
+  try {
+    if (fs.existsSync(file)) existing = fs.readFileSync(file, "utf8");
+  } catch {}
+
+  const projectHeader = `## ${project}`;
+  if (!existing) {
+    const header = `# Daily log — ${today}\n\n_Auto-generated by Qualia Framework. Each entry is one Stop-hook checkpoint per project per session._\n\n${projectHeader}\n${line}\n`;
+    fs.writeFileSync(file, header);
+  } else if (!existing.includes(projectHeader)) {
+    fs.appendFileSync(file, `\n${projectHeader}\n${line}\n`);
+  } else {
+    // Append the line under the existing project header. Insert after the last
+    // line that belongs to this project's section (next ## or EOF).
+    const headerIdx = existing.indexOf(projectHeader);
+    const afterHeader = headerIdx + projectHeader.length;
+    const nextHeaderIdx = existing.indexOf("\n## ", afterHeader);
+    const insertAt = nextHeaderIdx === -1 ? existing.length : nextHeaderIdx;
+    // Trim trailing newlines in the section so our append lands on a clean line.
+    const before = existing.slice(0, insertAt).replace(/\n+$/, "");
+    const after = existing.slice(insertAt);
+    fs.writeFileSync(file, `${before}\n${line}\n${after}`);
+  }
+
+  fs.writeFileSync(LAST_WRITE_FILE, String(now));
+  _trace("logged", { project, branch, phase, tasks, commits: commitCount });
+  process.exit(0);
+} catch (err) {
+  _trace("error", { error: err && err.message ? err.message : String(err) });
+  // Stop hooks must never block the user — exit 0 even on internal error.
+  process.exit(0);
+}

package/package.json

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

package/skills/qualia-debug/SKILL.md

@@ -40,7 +40,7 @@ node ~/.claude/bin/qualia-ui.js banner debug
 ### 2. Check Known Fixes First (cheap)
 
 ```bash
-cat ~/.claude/knowledge/common-fixes.md 2>/dev/null | grep -i "{symptom_keywords}"
+node ~/.claude/bin/knowledge.js search "{symptom_keywords}"
 ```
 
 If a known fix matches, apply it and jump to step 5 (verify). Known fixes are pre-verified patterns — no need to re-investigate.

package/skills/qualia-design/SKILL.md

@@ -59,6 +59,21 @@ Apply fixes to every HIGH and CRITICAL item. MEDIUM items fixed if cheap (same f
 
 Split target files into batches of 5. Spawn one Agent per batch IN THE SAME RESPONSE TURN (parallel execution). Each agent receives DESIGN.md inlined + its 5 files + the Design Quality Rubric from `rules/grounding.md`. Agents return their batch's critique table + the actual edits applied. The skill orchestrator fans in the results and runs the final verification (step 5).
 
+**Forked subagents (v4.2.0+):** if the current conversation already contains
+design taste discussion (font choices, palette discussion, motion preferences,
+or any color/typography critique threaded across multiple turns) AND
+`CLAUDE_AGENT_FORK_ENABLED=1` is set in `~/.claude/settings.json` (the v4.2.0
+default), prefer **forked subagents** over blank-context fan-out. Forks
+inherit the entire conversation history + share the prompt cache, so the
+batch agents see the 50k tokens of accumulated taste instead of a 2k-token
+compression. Anthropic shipped this in 2026-04 specifically to solve the
+"design subagent loses nuance" failure mode (NotebookLM 2026-04-25 source).
+Tell Claude explicitly: "spawn forked subagents to handle these batches in
+parallel." For variation-generation work (3 alternative homepage designs)
+forks are almost always the right call. For mechanical anti-pattern fixes
+(rip out `outline:none`, swap font tokens) blank context is fine — no
+nuance to inherit. When in doubt, fork — the cost is the same prompt cache.
+
 ```
 Agent(prompt="
 Read your role: builder for design transformation.