qualia-framework 5.3.0 → 5.4.0

package/docs/archive/v4.0.0-review.md

@@ -0,0 +1,288 @@
+# v4.0.0 — Review & Publish Handoff
+
+**Date:** 2026-04-18
+**Branch:** `feature/full-journey`
+**Release tag:** v4.0.0 (not yet tagged, not yet pushed)
+**Status:** Ready for review. Tests 156/156 green. Needs human eyeball before `git push` + `npm publish`.
+
+This document is the single source of truth for what shipped in v4.0.0 and what the next agent/reviewer needs to verify before the release goes public.
+
+---
+
+## TL;DR
+
+The Qualia Framework v4.0.0 makes `/qualia-new` produce the **entire project journey** (all milestones → Handoff) upfront, enables **end-to-end auto-chaining** of the Road with `--auto`, locks down the **milestone/phase/task hierarchy**, and **rebuilds `/qualia-idk` as a real diagnostician** instead of a router alias.
+
+10 commits on `feature/full-journey` (8 feature + 1 docs + 1 release-state fix). ~28 files touched. 156/156 tests green.
+
+Two local branches, neither pushed:
+
+| Branch | HEAD | Ships |
+|---|---|---|
+| `feature/story-file-plans` | `8ae5b0e` | v3.7.0 — story-file plan format (independent, useful on its own) |
+| `feature/full-journey` | `f790554` | v4.0.0 — full journey, auto-chain, diagnostic idk (includes v3.7.0) |
+
+---
+
+## The commits on `feature/full-journey`
+
+```
+94bc119 fix(v4): correct v4.0.0 — fold qualia-idk changelog entries into initial release
+ea9e7f3 docs(v4): README, guide.md, SESSION_REPORT updated for v4.0.0 + V4_REVIEW.md handoff
+f790554 release(v4.0.0): full journey — kickoff to handoff on rails
+f62e753 fix(v4/phase-g): milestone summary cumulative task count + smoke tests
+b41a52d feat(v4/phase-f): build_count + deploy_count bump, ERP v4 payload, handoff 4-deliverables
+74dd26e feat(v4/phase-d-e): builder pre-inline + journey visualization
+400cd17 feat(v4/phase-c): auto-chain wiring across Road skills
+87af253 feat(v4/phase-b): roadmapper + qualia-new full-journey output
+2e371c2 feat(v4/phase-a): model foundation — milestones[] + readiness guards
+8ae5b0e release(v3.7.0): story-file plan format (from feature/story-file-plans)
+```
+
+**Release-point:** `94bc119` is the canonical v4.0.0 HEAD (package.json = "4.0.0", CHANGELOG has a single [4.0.0] section with `/qualia-idk` folded in). Tag v4.0.0 at this commit.
+
+---
+
+## What v4.0.0 actually changes
+
+### Hierarchy (locked down)
+```
+Project
+└─ Journey (all milestones defined upfront)
+   └─ Milestone (a release — 2-5 total, Handoff is always last)
+      └─ Phase (2-5 tasks per phase)
+         └─ Task (one commit, one verification contract)
+```
+
+- Hard floor: 2 milestones. Hard ceiling: 5.
+- Final milestone is **always literally named "Handoff"** with 4 fixed phases (Polish, Content + SEO, Final QA, Handoff).
+- Every non-Handoff milestone needs **≥ 2 phases** (guarded by `state.js close-milestone`).
+- Milestone numbering is **contiguous** — no skipped numbers.
+
+### New artifact: `.planning/JOURNEY.md`
+The North Star. Lists every milestone with why-now + exit criteria + phase sketches. Written once during `/qualia-new`, consulted at every milestone boundary.
+
+### Auto mode (`--auto` flag)
+```
+/qualia-new --auto
+  → research runs automatically
+  → JOURNEY.md written
+  → SINGLE human approval on the whole journey
+  → plan 1 → build 1 → verify 1 → plan 2 → build 2 → verify 2 → ...
+  → [milestone boundary — HUMAN GATE: "Continue to M{N+1}?"]
+  → ... repeat until Handoff last phase ...
+  → /qualia-ship → /qualia-handoff → /qualia-report → DONE
+```
+
+**Two human gates total per project** (journey approval + each milestone boundary). Plus one halt if gap-cycle limit exceeded on a failed phase.
+
+### `/qualia-idk` now diagnostic (not a router alias)
+Spawns two isolated `Explore` subagents in parallel:
+1. **Plan view** — reads only `.planning/*`, reports what plan says we are + what should be TRUE
+2. **Code view** — reads only source code, reports what's built + what compiles + what's stubbed, cites file:line
+
+Main skill synthesizes: "What I see / The mismatch / What I think is happening / What to do next."
+
+### `/qualia` description scoped back to state routing
+Previously claimed "idk / stuck / lost / confused" triggers. Those now route to `/qualia-idk`. `/qualia` keeps "what next / what now / next command."
+
+### Schema changes (all additive, backward compatible)
+`tracking.json` gains:
+- `milestone_name` — human name of current milestone
+- `milestones[]` — array of closed milestone summaries (for ERP tree render)
+- `build_count`, `deploy_count` — now actually incremented on transitions
+
+`state.js` check output gains `milestone_name` + `milestones`.
+
+`qualia-report` ERP payload now includes all v4 fields.
+
+---
+
+## How to verify before publishing
+
+### 1. Run the test suite
+```bash
+cd /home/qualiasolutions/qualia-framework
+node --test tests/runner.js
+```
+Expected: `# pass 156 / # fail 0`.
+
+### 2. Visual smoke test of new UI commands
+```bash
+# Make a fake project
+TMP=/tmp/qualia-v4-visual && rm -rf $TMP && mkdir -p $TMP/.planning
+cat > $TMP/.planning/JOURNEY.md <<'EOF'
+---
+project: "Demo"
+---
+## Milestone 1 · Foundation
+**Why now:** Base infra.
+**Phases:**
+1. **Setup**
+2. **Auth**
+## Milestone 2 · Core Features
+**Why now:** Value delivery.
+**Phases:**
+1. **Feature A**
+2. **Feature B**
+## Milestone 3 · Handoff
+**Phases:**
+1. **Polish**
+2. **Content + SEO**
+3. **Final QA**
+4. **Handoff**
+EOF
+cat > $TMP/.planning/tracking.json <<'EOF'
+{"milestone":2,"milestone_name":"Core Features","milestones":[],"phase":1,"total_phases":2,"status":"built","lifetime":{"tasks_completed":4,"phases_completed":2,"milestones_completed":1}}
+EOF
+cat > $TMP/.planning/STATE.md <<'EOF'
+## Current Position
+Phase: 1 of 2 — Feature A
+Status: built
+Assigned to: Reviewer
+
+## Roadmap
+| # | Phase | Goal | Status |
+|---|-------|------|--------|
+| 1 | Feature A | x | built |
+| 2 | Feature B | x | — |
+EOF
+(cd $TMP && node /home/qualiasolutions/qualia-framework/bin/qualia-ui.js journey-tree .planning/JOURNEY.md)
+node /home/qualiasolutions/qualia-framework/bin/qualia-ui.js milestone-complete 1 "Foundation" "Core Features"
+node /home/qualiasolutions/qualia-framework/bin/qualia-ui.js milestone-complete 3 "Handoff" ""
+rm -rf $TMP
+```
+Expected:
+- Journey tree shows green dot on M1, teal diamond on M2 (CURRENT), dim circle on M3 (FINAL).
+- First milestone-complete banner shows `Next: Core Features`.
+- Second shows `PROJECT COMPLETE · last milestone reached`.
+
+### 3. State-machine end-to-end smoke
+Covered by test case `tests/runner.js` "milestone summary captures cumulative tasks_completed" and "build_count bumps on each 'built' transition". Both pass.
+
+### 4. Manual eyeball of key files
+Review these for v4 correctness:
+
+| File | Why |
+|---|---|
+| `templates/journey.md` | New artifact schema — is the format clear and complete? |
+| `agents/roadmapper.md` | Biggest agent rewrite — does it correctly describe the 3-file output (JOURNEY + REQUIREMENTS + ROADMAP)? |
+| `skills/qualia-new/SKILL.md` | Core flow — is the 14-step process coherent? Is `--auto` wiring clear? |
+| `skills/qualia-idk/SKILL.md` | New diagnostic — does the 2-pass isolation make sense? Is the synthesis format useful? |
+| `skills/qualia-verify/SKILL.md` | Auto-chain decision table (PASS → next phase / last phase → milestone / last milestone → ship) |
+| `skills/qualia-milestone/SKILL.md` | Reads next milestone from JOURNEY.md now, not user prompt |
+| `skills/qualia-handoff/SKILL.md` | 4 mandatory deliverables enforced |
+| `bin/state.js` lines ~975-1050 | close-milestone readiness guards + milestones[] summary append |
+| `bin/qualia-ui.js` journey-tree + milestone-complete | New visualizations |
+| `CHANGELOG.md` [4.0.0] section | Full feature list + migration notes |
+
+### 5. Backward-compat verification
+The v4 changes are designed additive. Verify by:
+```bash
+# tracking.json from an older project (no milestones[], no milestone_name)
+# should still work with state.js check
+echo '{"milestone":1,"phase":1,"total_phases":3,"status":"setup","lifetime":{"tasks_completed":0,"phases_completed":0,"milestones_completed":0,"total_phases":0}}' > /tmp/old-tracking.json
+mkdir -p /tmp/old-project/.planning && mv /tmp/old-tracking.json /tmp/old-project/.planning/tracking.json
+cat > /tmp/old-project/.planning/STATE.md <<'EOF'
+Phase: 1 of 3 — Setup
+Status: setup
+
+## Roadmap
+| # | Phase | Goal | Status |
+|---|-------|------|--------|
+| 1 | Setup | x | ready |
+| 2 | Feature | x | — |
+| 3 | Ship | x | — |
+EOF
+(cd /tmp/old-project && node /home/qualiasolutions/qualia-framework/bin/state.js check | head -20)
+rm -rf /tmp/old-project
+```
+Expected: `check` succeeds, output includes `milestones: []` and `milestone_name: ""` (hydrated by `ensureLifetime`).
+
+---
+
+## Publish checklist
+
+Once review passes:
+
+```bash
+# 1. Push both branches
+git push -u origin feature/story-file-plans
+git push -u origin feature/full-journey
+
+# 2. Merge v3.7.0 first (recommended — gives it a distinct tag in history)
+git checkout main
+git merge --ff-only feature/story-file-plans
+git tag v3.7.0
+git push origin main --tags
+
+# 3. Merge v4.0.0
+git merge --ff-only feature/full-journey
+# If fast-forward fails (unlikely since v4 branched off story-file-plans HEAD):
+#   git merge feature/full-journey    # creates a merge commit — also fine
+git tag v4.0.0
+git push origin main --tags
+
+# 4. npm publish
+npm publish
+# Expected: qualia-framework@4.0.0 goes live. Auto-update hook notifies
+# every team member's installed client on next session.
+
+# 5. Verify
+npm view qualia-framework version    # should return 4.0.0
+```
+
+### Alternative: one combined release
+If the team would rather have a single v4.0.0 release tag (skip the v3.7.0 tag):
+
+```bash
+git checkout main
+git merge --ff-only feature/full-journey
+git tag v4.0.0
+git push origin main --tags
+npm publish
+```
+(v3.7.0 work is still in the history, just not tagged as its own release.)
+
+---
+
+## Risk areas (eyeball these)
+
+1. **Auto-chain logic in `/qualia-verify`** — the decision table (PASS → next phase / last phase of milestone / last phase of Handoff / FAIL gap / FAIL limit) is described in the SKILL.md but relies on Claude to parse JOURNEY.md at runtime to detect "last phase of milestone." Smoke test didn't actually run the auto-chain because that requires live subagent invocation. **Recommended first test on merge**: run `/qualia-new --auto` on a throwaway project and watch how it handles the milestone boundary.
+
+2. **Roadmapper's new three-file output** — the rewritten agent prompt is long and complex. The roadmapper must:
+   - Generate JOURNEY.md with all milestones
+   - Assign requirements to milestones
+   - Only detail Milestone 1 in ROADMAP.md
+   - Pass `--milestone_name` to `state.js init`
+   Smoke test didn't exercise the roadmapper directly — it's only triggered by `/qualia-new`.
+
+3. **`/qualia-idk`'s two-pass isolation** — depends on `Explore` subagent correctly NOT crossing its scope. If an Explore agent reads .planning/ when told "code only" or vice versa, the diagnosis degrades. The SKILL.md has explicit "DO NOT read..." instructions but this is prompt-level enforcement, not hard boundary.
+
+4. **Builder pre-inline context** — saves tool calls but inflates prompt size. On very large projects (PROJECT.md + DESIGN.md + 5 context files could easily be 10k+ tokens), the builder's prompt might balloon. Acceptable for most projects; watch for issues on monorepos.
+
+---
+
+## Known limitations / deferred
+
+- **No visual / mockup generation** (gstack's `/design-shotgun` or Superpowers' Visual Companion). Not in v4 — could be a v4.1 feature.
+- **No cross-model review** (gstack's `/codex`). Not in v4.
+- **No cross-project vector memory** (Claude-Flow's claude-mem pattern). Current `knowledge/` is still hand-authored markdown.
+- **No IDE integration** (VS Code extension, JetBrains plugin). Claude Code CLI only.
+- **No token-budget compression** (SuperClaude's ~70% compression claim). Qualia relies on fresh-context agents instead of compression.
+
+These are all discussed in the competitive gap analysis done earlier in the session — see the chat transcript or memory for details.
+
+---
+
+## Questions for Fawzi before publish
+
+1. **Single v4.0.0 release or v3.7.0 + v4.0.0?** Default: both tags (v3.7.0 as a step release). Cleaner history. Alternative: fold into single v4.0.0.
+2. **Alpha/beta tag on npm?** `npm publish` without `--tag` goes to `latest` and every installed client auto-updates on next session. If you want a slower rollout, publish with `--tag beta` and the team opts in manually with `npm install qualia-framework@beta install`.
+3. **Do you want to dogfood v4 on an existing project before publish?** Running `npx qualia-framework@4.0.0-alpha install` locally on Sakani or another project is the safest way to verify end-to-end — especially the auto-chain which isn't covered by the unit tests.
+
+Contact for questions: Fawzi Goussous — fawzi@qualiasolutions.net
+
+---
+
+*Generated 2026-04-18 by the v4 build session. Review this doc + CHANGELOG.md [4.0.0] before publishing.*

package/docs/instruction-budget-audit.md

@@ -0,0 +1,113 @@
+# Instruction-Budget Audit
+
+> **Date:** 2026-05-06
+> **Trigger:** Re-study of *Skills and Strategies for Real Engineering with Claude Code* (Matt Pocock) and *Context and Tools: Mastering the AI Engineering Lifecycle* (Patrick Debois, Karpathy, Pocock, Mario Zechner).
+> **Question:** Does Qualia Framework actually honor the "load on demand, not always" promise written in `CLAUDE.md`?
+
+## Finding 1 — `~/.claude/rules/*.md` is loaded eagerly by Claude Code
+
+Claude Code auto-discovers and injects every Markdown file under `~/.claude/rules/` into the system prompt of every session. This is **harness behavior**, not framework behavior — there is no `@-import` declaration in `~/.claude/CLAUDE.md`, yet the rules appear in the system reminder verbatim.
+
+**Measured cost (2026-05-06 install):**
+
+| File | Lines | Notes |
+|---|---|---|
+| `design-reference.md` | 179 | Motion specs, WCAG checklist, breakpoints |
+| `design-rubric.md` | 157 | 8-dimension verifier rubric |
+| `design-laws.md` | 148 | OKLCH, color strategy, typography |
+| `frontend.md` | 118 | Brand standards |
+| `design-brand.md` | 114 | Brand register |
+| `design-product.md` | 114 | Product register |
+| `grounding.md` | 114 | Severity rubric, citation format |
+| `infrastructure.md` | 87 | Stack, MCP servers, CLIs |
+| `deployment.md` | 30 | Post-deploy checklist |
+| `speed.md` | 23 | Speed rules |
+| `context7.md` | 14 | Context7 trigger rule |
+| `security.md` | 12 | RLS, auth, secrets |
+| **Total** | **1110** | |
+
+At ~4 chars/line average that is **~28 KB injected on every session**, regardless of whether the user is touching frontend, backend, infra, or nothing.
+
+The rule files themselves are written under the assumption that a skill or agent will read them on demand (e.g., `agents/builder.md` line 139 says *"Security, design, and performance rules auto-load from `rules/*.md` based on the files you touch"*) — which is correct **inside subagent fork prompts** but **wrong for the user's main session**, where the harness loads them all preemptively.
+
+## Finding 2 — `CLAUDE.md` template is already disciplined
+
+The framework `CLAUDE.md` template is 24 lines and ends with the right note:
+
+> *"this file stays under 25 lines. Steering rules go into discoverable skills, not into the global system prompt. CLI preferences go into hooks. Stack/architecture details are trivially discoverable in package.json/config."*
+
+This part is healthy. The leak is in `rules/`, not `CLAUDE.md`.
+
+## Finding 3 — Skill dedup hypothesis was wrong
+
+A first pass suggested deleting `qualia-quick`, `qualia-road`, `qualia-help`, `qualia-handoff` as duplicates. Cross-reference check showed:
+
+- `qualia-quick` is referenced from `bin/install.js`, `hooks/session-start.js`, `templates/help.html`, `README.md`, `guide.md`, `skills/qualia-prd/SKILL.md`, `skills/qualia-task/SKILL.md` — load-bearing.
+- `qualia-road` is referenced from `CLAUDE.md`, `AGENTS.md`, `README.md`, `guide.md`, `skills/qualia-help/SKILL.md` description — load-bearing.
+- `qualia-help` opens an HTML reference — distinct purpose from `qualia-road` (terminal map).
+- `qualia-handoff` is the final delivery skill, referenced from `bin/state.js:490`, ship/verify, journey-demo — load-bearing.
+
+**Each skill has a job.** No deletion is safe in this PR. The right fix is *boundary clarity in descriptions* (so the LLM picks correctly), not deletion.
+
+## Recommended follow-ups (deferred to separate PRs)
+
+### R1 — Move design rules to a lazy folder *(big, risky)*
+
+```
+~/.claude/rules/                           # always-loaded (HARNESS)
+  ├── grounding.md       (114)             # KEEP — universal
+  ├── security.md         (12)             # KEEP — universal
+  ├── speed.md            (23)             # KEEP — universal
+  ├── context7.md         (14)             # KEEP — universal
+  └── infrastructure.md   (87)             # KEEP — universal stack
+                                            #   total: ~250 lines
+
+~/.claude/qualia-design/                    # explicit-load only
+  ├── design-laws.md     (148)
+  ├── design-brand.md    (114)
+  ├── design-product.md  (114)
+  ├── design-reference.md (179)
+  ├── design-rubric.md   (157)
+  ├── frontend.md        (118)
+  └── deployment.md       (30)             # post-deploy checklist; loaded by /qualia-ship
+                                            #   total: 860 lines, NOT auto-loaded
+```
+
+Skills/agents that need design rules `Read` them on demand (already the pattern in `agents/builder.md` and `agents/verifier.md`). The save: **~28 KB → ~6 KB injected per session, ~22 KB recovered.**
+
+Required changes:
+1. `bin/install.js` — install design rules to `~/.claude/qualia-design/` instead of `~/.claude/rules/`.
+2. Every skill/agent reference path `rules/design-*.md` → `qualia-design/design-*.md` or use `~/.claude/qualia-design/design-*.md` absolute.
+3. Update `hooks/session-start.js` `CRITICAL_FILES` health check.
+4. Migration step in `bin/install.js` to clean up old `~/.claude/rules/design-*.md` for existing installs.
+
+**Effort:** M-L. **Impact:** ~80% reduction in always-loaded substrate.
+
+### R2 — Skill description sharpening *(small, safe)*
+
+`qualia-quick` and `qualia-task` overlap in description. Tighten:
+- `qualia-quick`: "≤1 hour, 1 file, no plan, no spawn — just do it."
+- `qualia-task`: "1–3 hours, 1–5 files, fresh builder spawn, atomic commit, no phase plan."
+
+`qualia-road` and `qualia-help` overlap. Clarify:
+- `qualia-road`: "Terminal-rendered workflow map. Use over SSH or when no browser."
+- `qualia-help`: "Browser-rendered HTML reference. Default."
+
+### R3 — Per-skill versioning + eval harness *(carry-over from notebook 1, source 6 — Debois)*
+
+Each skill carries its own `version:` in frontmatter and a `tests/skills/{skill-name}.spec.sh` fixture. CI runs the fixture against the skill spec. Catches silent skill rot when CC behavior changes underneath.
+
+### R4 — MCP tier-list rule in `rules/speed.md` *(carry-over from notebook 1, source 5 — CLI vs MCP)*
+
+Codify the "CLI-first" principle. Reference the existing `/supabase` skill replacing 32 supabase MCP tools as the canonical example.
+
+## What changed in *this* PR
+
+This PR ships the changes that don't require user-state migration:
+
+1. **Citation enforcement preamble** in `agents/builder.md` and `agents/verifier.md` — closes notebook 2, source #9 (*Never Trust an LLM*). Builders and verifiers must cite `file:line — "quoted"` or write `INSUFFICIENT EVIDENCE`. No hedging, no narration.
+2. **`rules/architecture.md`** — net-new, deep-modules + scout-for-shallow-code from notebook 2 sources #5 + #12 (Pocock de-slop, codebase-not-ready-for-AI). Skill `/qualia-optimize --deepen` already exists; this rule formalizes the architectural taste it scouts for.
+3. **README warning** — "Never run Claude's `/init`" — direct users to `/qualia-new` or `/qualia-map`. Per notebook 2 sources #3 + #8.
+4. **This audit document** — anchors the deferred follow-ups so they don't get lost.
+
+The relocation in R1 is the biggest single win available; it is intentionally deferred so this PR stays small and reversible.

package/guide.md

@@ -1,8 +1,10 @@
-# Qualia Developer Guide (v5)
+# Qualia Developer Guide (v5.3)
 
 > 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.
 
+**v5.3 ships three Matt-Pocock gap closures:** `/qualia-prd` (synthesize conversation → durable spec), `/qualia-hook-gen` (CLAUDE.md instruction → deterministic hook), `/qualia-optimize --deepen` Step 5b (3 parallel-interface design variants for refactor RFCs). Plus the visual-polish loop (`/qualia-polish-loop`) from v5.1 with reduced-motion + multi-route flags from v5.2.
+
 ## The Road
 
 ```
@@ -49,18 +51,23 @@ Append `--auto` to `/qualia-new` and the framework chains every step:
 |------|---------|-------------|
 | Starting | `/qualia-new` | Set up project with full journey (all milestones → Handoff) |
 | Starting (auto) | `/qualia-new --auto` | Same + chain through building automatically |
+| Brownfield | `/qualia-map` | Map an existing codebase BEFORE `/qualia-new` |
+| Mid-project spec | `/qualia-prd` | Synthesize the current conversation into a durable feature spec (v5.3+) |
 | Building | `/qualia-plan` | Plan the current phase |
 | | `/qualia-build` | Build it (parallel tasks) |
 | | `/qualia-verify` | Check it actually works |
 | Milestone | `/qualia-milestone` | Close current, open next from JOURNEY.md |
 | Quick fix | `/qualia-quick` | Skip planning, just do it |
-| Finishing | `/qualia-polish` | Design and UX pass |
+| Finishing | `/qualia-polish` | Design and UX pass (scope-adaptive: component / route / app / redesign / critique / quick) |
+| | `/qualia-polish-loop` | Autonomous visual-polish loop — screenshot → vision-eval → fix → repeat (v5.1+) |
 | | `/qualia-ship` | Deploy to production |
 | | `/qualia-handoff` | Deliver to client (4 mandatory deliverables) |
 | Reporting | `/qualia-report` | Log what you did (mandatory before clock-out) |
 | Zooming in | `/qualia-zoom` | Focus on a single file or function with full context |
-| Issues | `/qualia-issues` | Scan codebase for issues, tech debt, and improvement opportunities |
-| Triage | `/qualia-triage` | Prioritize and categorize a backlog of issues |
+| Issues | `/qualia-issues` | Break a phase plan into vertical-slice GitHub issues |
+| Triage | `/qualia-triage` | Triage open issues through the ready-for-agent state machine |
+| Optimize | `/qualia-optimize --deepen` | Find shallow modules; v5.3+ spawns 3 parallel interface-design variants per candidate |
+| Hook gen | `/qualia-hook-gen` | Convert a CLAUDE.md/rules instruction into a deterministic hook (v5.3+) |
 | Road view | `/qualia-road` | View and navigate journey/milestone/phase status |
 | Lost? | `/qualia` | Mechanical next-command router |
 | Confused? | `/qualia-idk` | Diagnostic — scans planning + code, explains what's going on |

package/hooks/session-start.js

@@ -34,8 +34,8 @@ const HEALTH_FILE = path.join(HOME, ".claude", ".qualia-install-health.json");
 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", "qualia-design", "frontend.md"),
   path.join(HOME, ".claude", "bin", "state.js"),
 ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "5.3.0",
+  "version": "5.4.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -28,14 +28,17 @@
     "test:hooks": "bash tests/hooks.test.sh",
     "test:bin": "bash tests/bin.test.sh",
     "test:lib": "bash tests/lib.test.sh",
+    "test:skills": "bash tests/skills.test.sh",
+    "test:slop-detect": "bash tests/slop-detect.test.sh",
     "test:statusline": "bash tests/statusline.test.sh",
-    "test:shell": "bash tests/statusline.test.sh && bash tests/state.test.sh && bash tests/hooks.test.sh && bash tests/bin.test.sh && bash tests/lib.test.sh"
+    "test:shell": "bash tests/statusline.test.sh && bash tests/state.test.sh && bash tests/hooks.test.sh && bash tests/bin.test.sh && bash tests/lib.test.sh && bash tests/skills.test.sh && bash tests/slop-detect.test.sh"
   },
   "files": [
     "bin/",
     "agents/",
     "hooks/",
     "rules/",
+    "qualia-design/",
     "skills/",
     "templates/",
     "references/",

package/rules/architecture.md

@@ -0,0 +1,125 @@
+# Architecture Rules
+
+How Qualia code stays navigable for future agents (human and AI). Read on architectural-judgment tasks: refactors, new module decisions, deep-module work, `/qualia-optimize --deepen`.
+
+## 1. Deep modules over shallow ones (Ousterhout)
+
+A **deep module** hides significant complexity behind a small, stable interface. A **shallow module** exposes most of its internals — every caller has to know how it works to use it.
+
+| | Deep | Shallow |
+|---|---|---|
+| Interface size (params, exports) | Small | Wide |
+| Internal logic | Substantial | Trivial |
+| Cost to change implementation | Low (callers don't notice) | High (every caller breaks) |
+| Cost to read a caller | Low | High (must know module internals) |
+
+Deep modules are the primary defense against AI-generated entropy. AI is excellent at generating implementation; humans (and AI under guidance) must defend the **interface**.
+
+### Smell — shallow code
+
+If you spot any of these, the module is shallow and is a refactor candidate:
+
+- A wrapper function that does only argument shuffling and a single inner call.
+- A type-only file that re-exports types from elsewhere.
+- A "service" that has 8 public methods and one private one.
+- A util module where every export is used in exactly one place.
+- A class whose every method is a one-liner pass-through.
+
+`/qualia-optimize --deepen` is the skill that scouts for these and proposes interface consolidations.
+
+## 2. Locality over cleverness
+
+Code that changes together should live together. The cost of a "DRY" abstraction is paid every time a future caller has to mentally fork to the abstraction's definition. Three similar lines beats a premature `extractCommon()` that everyone has to read twice.
+
+Apply DRY only when:
+- The duplication is exact (not just similar shape).
+- The thing duplicated is unlikely to diverge.
+- The caller doesn't need to know "the rule" to read the call site.
+
+If any of those three is uncertain, leave the duplication. Pocock's rule of thumb: **three is the threshold, but only if all three would change in lock-step.**
+
+## 3. Adapters at seams
+
+Wherever the system meets an external dependency (database, third-party API, AI provider, payment gateway), introduce an adapter. The adapter:
+
+- Owns the dependency's specific shape (auth headers, response envelopes, error formats).
+- Translates to a project-internal type that the rest of the code uses.
+- Is the only file that needs to change when the dependency is swapped or upgraded.
+
+This is the seam where tests inject fakes and where future migrations live. A codebase without adapters is a codebase that fights every dependency upgrade.
+
+**Example seams** in a typical Qualia project:
+- `lib/supabase/server.ts` — adapter over `@supabase/supabase-js`.
+- `lib/openrouter/client.ts` — adapter over OpenRouter REST API.
+- `lib/retell/agent.ts` — adapter over Retell AI SDK.
+- `lib/zoho/contacts.ts` — adapter over Zoho Books API.
+
+Direct calls to vendor SDKs from feature code are a smell. Move them through an adapter.
+
+## 4. Progressive disclosure of complexity
+
+A reader entering the codebase from a fresh clone should be able to follow this path:
+
+```
+README.md  →  app/ or src/index  →  one feature folder  →  one route  →  one component  →  one util
+```
+
+At each step the depth increases. The top is breadth (what does this app do?), the bottom is depth (how does this specific util compute X?). Skipping levels is a smell:
+
+- An entry point that imports 30 modules from across the tree → the tree is shallow.
+- A route handler that calls a database directly → no service layer; logic and IO are entangled.
+- A component that owns its own data fetching, mutation logic, error handling, and rendering → no hook abstraction; the component will be impossible to test or replace.
+
+The pattern that tells a fresh reader where to go next is **layered service boundaries**:
+1. **Routes / pages** — wiring only. No business logic.
+2. **Features / use cases** — business logic. Calls services.
+3. **Services** — orchestration. Calls adapters.
+4. **Adapters** — IO. The only layer that talks to vendors.
+5. **Domain types** — pure. No imports of the above.
+
+Inversions of this order (domain types importing adapters, services calling components) are bugs in shape.
+
+## 5. Interface stability beats internal elegance
+
+Once an interface has callers, changing it is expensive. Internal refactors are cheap. **Optimize for the cost of change.**
+
+When in doubt:
+- A new public function: write it conservatively. Defaults are a liability — every default is a future migration.
+- An internal function: write it expressively. Internal callers can be fixed in one sweep.
+
+Pocock's heuristic from de-slop: *the interface is the thing the AI shouldn't change without you. The implementation is the thing the AI can rewrite at will.*
+
+## 6. Test the seam, not the function
+
+Unit tests that pin internal function signatures rot fast — every refactor breaks them. Tests against the **adapter** or **service interface** survive refactors.
+
+Order of test value (high → low):
+1. **End-to-end / user-flow** — tests at the route level. Survive everything except feature changes.
+2. **Service-level** — tests at the use-case boundary. Survive most refactors.
+3. **Adapter-level** — tests with the vendor mocked. Survive vendor swaps.
+4. **Unit / function-level** — tests against a single internal function. Last resort. Only for genuinely tricky algorithms.
+
+The pyramid in older textbooks (lots of unit, few e2e) inverted in the AI era. AI generates internal functions cheaply; the seam tests are the ones that survive AI-driven refactors.
+
+## 7. The codebase IS the documentation
+
+Per Pocock's *"Never run /init"*: static documentation rots within weeks. The agents and humans should be able to **explore** to discover, not **memorize** to recall.
+
+Practical rules:
+- README.md: orientation only — what is this app, how do I run it, where is the source of truth for the rest. Not API docs, not architecture diagrams that will lie within a sprint.
+- `.planning/CONTEXT.md`: domain glossary, append-only as terms emerge. Discovered, not maintained.
+- ADRs in `.planning/decisions/`: hard-to-reverse calls, dated, immutable. Future archaeology, not current spec.
+- Anything else: it lives in code or it doesn't exist. If you need a diagram, generate it from the code at read-time.
+
+A skill or agent that needs context should `Read` the relevant code, not a synopsis of it written six months ago.
+
+## 8. When to apply this rule file
+
+Read this file (auto-load via skill or `@rules/architecture.md`) when:
+
+- Planning a new module or feature with multiple components.
+- The user requests `/qualia-optimize --deepen` or `--alignment`.
+- A verifier is scoring "Container depth & nesting" (per `rules/design-rubric.md` dimension 8).
+- An ADR is being drafted for an architectural fork.
+
+Do **not** auto-load this on quick fixes, copy edits, single-component touch-ups — that wastes instruction budget. Use judgment.

package/rules/infrastructure.md

@@ -8,8 +8,7 @@ Standard services across all Qualia projects. Use these unless the project expli
 
 ## Database: Supabase (every project)
 - Every project uses Supabase for auth, database, and storage
-- **CLI:** `npx supabase` — migrations, type generation, local dev
-- **MCP:** Supabase MCP server is available in Claude Code for direct database operations
+- **CLI-first** — prefer `npx supabase` (migrations, type generation, local dev, SQL) over the Supabase MCP server. The MCP imposes a token tax on every turn; the CLI hits the same API at zero token cost. Use the MCP only when you need a feature the CLI doesn't expose (e.g., interactive branch management).
 - Always enable RLS on every table (see `rules/security.md`)
 - Use `lib/supabase/server.ts` for server-side, `lib/supabase/client.ts` for client-side
 - Run `npx supabase gen types` after schema changes