qualia-framework 5.3.0 → 5.5.0

package/docs/erp-contract.md

@@ -2,6 +2,17 @@
 
 The Qualia Framework optionally uploads session reports to the company ERP at `https://portal.qualiasolutions.net`. This document specifies the API shape.
 
+## Operating Model
+
+The ERP treats `/qualia-report` as an employee shift submission, not proof that an assigned task was finished. Employees clock out after their fixed daily hours and submit what happened during the shift: shipped work, partial progress, blockers, investigation, meetings, or no-code work.
+
+Primary ERP planning dates are:
+- Project deadline
+- Milestone deadline
+- Employee submission date from the uploaded report
+
+Phase and task counters remain framework telemetry. They help agents plan/build/verify, but they should not become the ERP's primary navigation, deadline model, or employee-performance label.
+
 ## Configuration
 
 Stored in `~/.claude/.qualia-config.json`:

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 |
@@ -102,7 +109,7 @@ If neither helps, paste the error and ask Claude directly. If Claude can't fix i
 ## Session Start / End
 
 **Start:** Claude loads your project context automatically. The router banner shows your journey position ("M2 of 4 · P2 of 3").
-**End:** Run `/qualia-report` — this is mandatory before clock-out. The report is committed to git and (if ERP is enabled) uploaded to https://portal.qualiasolutions.net.
+**End:** Run `/qualia-report` — this is the mandatory clock-out submission. It reports what happened during the work shift, even if the work is unfinished. The report is committed to git and (if ERP is enabled) uploaded to https://portal.qualiasolutions.net.
 
 ## How It Works (you don't need to know this, but if curious)
 
@@ -113,7 +120,7 @@ If neither helps, paste the error and ask Claude directly. If Claude can't fix i
 - **Story-file plans:** Every task has Why / Acceptance Criteria / Depends on / Validation inline — the plan IS the brief.
 - **Wave execution:** Independent tasks run in parallel. Dependent tasks wait.
 - **Milestone-boundary pauses:** In `--auto` mode, the framework pauses only at real decision points. Everything else runs on rails.
-- **tracking.json:** Updated on every push. The ERP reads it automatically. Includes `milestone_name` + `milestones[]` so the ERP renders a proper tree instead of a flat list.
+- **tracking.json:** Updated on every push. The ERP reads it automatically. Includes `milestone_name` + `milestones[]` so the ERP can show project and milestone progress without exposing framework tasks as the main employee workflow.
 
 ## Quick Reference
 
@@ -127,4 +134,4 @@ If neither helps, paste the error and ask Claude directly. If Claude can't fix i
 | Finished the last phase of a milestone | `/qualia-milestone` |
 | About to ship | `/qualia-ship` |
 | Client is ready to take over | `/qualia-handoff` |
-| End of workday | `/qualia-report` (mandatory) |
+| End of workday / clock-out | `/qualia-report` (mandatory shift submission) |

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.5.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

package/rules/speed.md

@@ -0,0 +1,55 @@
+---
+alwaysApply: true
+---
+
+# Speed Rules (MANDATORY)
+
+## Direct tools over subagents
+
+**NEVER use Task(Explore) or Task(general-purpose) for simple file lookups or code searches.** Use direct tools instead:
+- **Glob** for finding files by name/pattern
+- **Grep** for searching code content
+- **Read** for reading specific files
+- Only use Task(Explore) when you genuinely need 5+ rounds of deep codebase archaeology.
+
+**NEVER spawn subagents when direct tools work.** Subagents are slow — a direct Glob or Grep returns in seconds, a fresh agent burns 5-10 seconds of spawn overhead plus its own context budget.
+
+**Bias toward action, not exploration.** If the user asks you to fix something and you know the project structure, just do it.
+
+## CLI-first, MCP only when CLI can't
+
+MCP servers impose a **token tax**: their tool definitions consume context-window space on every turn, even when unused. CLIs that the model already knows from training data (git, gh, supabase, vercel, railway, npx, curl) impose zero token tax — the model recalls them from weights, not from the prompt.
+
+**Default to CLI.** Reach for MCP only when:
+- The CLI doesn't exist or doesn't expose the operation you need.
+- The CLI requires interactive auth that MCP has already brokered (e.g., Stripe Dashboard).
+- The MCP returns structured JSON that would be expensive to parse from CLI text output.
+- The MCP enforces governance (RLS-aware queries, scoped DB credentials) that the CLI doesn't.
+
+If a `/skill-name` exists that wraps a CLI, prefer the skill — it's been hardened. Canonical example: `/supabase` skill replaces 32 supabase MCP tools with `supabase` CLI calls and saves substantial token budget.
+
+### MCP tier-list (when each is justified)
+
+| Server | Always-on? | Justification |
+|---|---|---|
+| `claude-in-chrome` | On-demand | Browser automation has no CLI equivalent; use for QA flows only |
+| `supabase` MCP | **Off** in favor of `/supabase` skill | CLI covers 95% of operations; MCP only if you need branch management interactively |
+| `context7` | On-demand | Library docs at runtime — no CLI alternative for Context7 itself |
+| `notebooklm-mcp` | On-demand | NotebookLM has no CLI; only loaded when researching against existing notebooks |
+| `firecrawl-mcp` | On-demand | Web scraping; only loaded when feature requires it |
+| `next-devtools` | Always-on (dev) | Next.js 16 runtime errors not visible elsewhere |
+| `mux`, `stitch`, `higgsfield` | On-demand | Specialized API surfaces; load only on relevant client work |
+| `ZohoMCP`, `qualia-erp` | On-demand | Business ops only, not engineering-path |
+
+The pattern: **on-demand by default; always-on only when the data is irreducibly remote AND there's no CLI.**
+
+## Use shortcuts (Qualia commands)
+
+When a Qualia command exists for the situation, use it — don't reinvent:
+- `/qualia` — what's my next step?
+- `/qualia-quick` — small inline fix, no plan, no spawn
+- `/qualia-task` — single focused task, fresh builder spawn, atomic commit
+- `/qualia-ship` — full deploy pipeline (quality gates → commit → deploy → verify)
+- `/qualia-review` — production audit
+- `/qualia-pause` — save context before clearing the conversation
+- `/qualia-learn` — save a lesson from a mistake

package/skills/qualia-discuss/SKILL.md

@@ -67,10 +67,24 @@ Wait for response. Then:
 - Write an ADR in `.planning/decisions/ADR-{NNNN}-{slug}.md` ONLY when the decision is hard-to-reverse, surprising-without-context, AND involves real trade-offs (use the template — keep it scarce)
 - Drill deeper if the answer opens new branches
 
-### 4. Build the locked-decisions list
+### 4. Build the locked-decisions list (with IDs — machine-parseable downstream)
 
-For each resolved decision, capture: choice (what) / rationale (why) / source (who/when).
-Also track: **Discretion items** (planner decides) / **Deferred ideas** (NOT this phase) / **Risk flags** (watch during build) / **Open questions** (still unresolved).
+For each resolved decision, capture as a row with a stable ID `D-NN` (zero-padded, sequential within the phase). The planner's Decision Coverage Audit checks every `D-NN` is implemented; the plan-checker BLOCKS if any is missing.
+
+**Locked Decision row format:**
+
+| ID | Decision | Rationale | Source |
+|----|----------|-----------|--------|
+| D-01 | Use Supabase RLS for authorization, not middleware | Compliance requires database-level checks | discuss session 2026-05-09 |
+| D-02 | Store session tokens server-side, not in JWT | OWASP guidance + revocation requirement | ADR-0007 |
+
+Also track:
+- **Discretion items** — planner decides based on best practice (no IDs needed).
+- **Deferred ideas** — explicitly NOT this phase. The plan-checker will REVISE if any of these appears in a task.
+- **Risk flags** — watch during build (no IDs).
+- **Open questions** — still unresolved. Cannot lock until resolved.
+
+When you reference a decision later (in commit messages, task Why fields, ADRs), use its ID — `D-03` is shorter than the full decision text and cross-checkable.
 
 ### 5. Decision gate
 

package/skills/qualia-help/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-help
-description: "Open the Qualia Framework reference guide in the browser. A beautiful themed HTML page with all commands, rules, services, and the road. Trigger on 'help', 'how does this work', 'show me the commands', 'qualia help', 'reference'."
+description: "Open the BROWSER HTML reference for the Qualia Framework — themed page with all commands, rules, services, and the road. The default when a browser is available. For terminal-only output (SSH, headless), use /qualia-road. Triggers: 'help', 'how does this work', 'show me the commands', 'qualia help', 'reference', 'open the docs'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-map/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-map
-description: "Map an existing codebase to infer architecture, stack, conventions, what's already built, AND adapt Qualia to the repo's existing tracker/labels/glossary conventions (onboarding). For brownfield projects — run BEFORE /qualia-new so Validated requirements get inferred from existing code and Qualia commands respect the repo's existing process."
+description: "Map an existing codebase to infer architecture, stack, conventions, what's already built, AND adapt Qualia to the repo's existing tracker/labels/glossary conventions (onboarding). For brownfield projects — run BEFORE /qualia-new so Validated requirements get inferred from existing code and Qualia commands respect the repo's existing process. Triggers: 'map this codebase', 'onboard to existing project', 'brownfield setup', 'what's already built here', 'scan the repo', 'inherited a codebase', 'audit this project before planning'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-milestone/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-milestone
-description: "Close the current milestone and open the next one — loads the next milestone's scope from JOURNEY.md (no ad-hoc naming). Archives artifacts, marks requirements Complete, regenerates ROADMAP.md for the next milestone."
+description: "Close the current milestone and open the next one — loads the next milestone's scope from JOURNEY.md (no ad-hoc naming). Archives artifacts, marks requirements Complete, regenerates ROADMAP.md for the next milestone. Triggers: 'close milestone', 'next milestone', 'milestone done', 'wrap up milestone', 'M1 done open M2', 'I want to advance to the next milestone', 'finish this milestone'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-new/SKILL.md

@@ -183,7 +183,7 @@ git commit -m "docs: PRODUCT.md — register, users, voice, anti-references"
 If frontend work is involved, generate `.planning/DESIGN.md` from `templates/DESIGN.md`. The generation MUST commit to four things upfront (these go in §1 of DESIGN.md):
 
 1. **Aesthetic direction** — pick ONE: `editorial · brutalist · luxury · maximalist · retro-futuristic · organic · terminal-native · sci-fi · pastoral · industrial · ...`. Don't hedge ("modern minimal" is hedging — pick one extreme).
-2. **Color strategy** — pick ONE: `Restrained · Committed · Full palette · Drenched`. See `rules/design-laws.md` §2.
+2. **Color strategy** — pick ONE: `Restrained · Committed · Full palette · Drenched`. See `qualia-design/design-laws.md` §2.
 3. **Scene sentence** — one concrete sentence: who uses this, where, ambient light, mood. NOT "observability dashboard" — "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room." Run the sentence, not the category.
 4. **Differentiation** — one sentence: what someone remembers 24 hours later.
 
@@ -198,7 +198,7 @@ Then fill the rest of DESIGN.md:
 - §9 Responsive: mobile-first
 - §10 Anti-pattern checklist (the auto-runnable one)
 
-Cross-check the result against `rules/design-laws.md` §8 absolute bans BEFORE writing — the design must not propose any banned pattern.
+Cross-check the result against `qualia-design/design-laws.md` §8 absolute bans BEFORE writing — the design must not propose any banned pattern.
 
 ```bash
 git add .planning/DESIGN.md .planning/config.json

package/skills/qualia-optimize/REFERENCE.md

@@ -15,7 +15,7 @@ Agent(
 </planning>
 
 <rules>
-{rules/frontend.md content}
+{qualia-design/frontend.md content}
 </rules>
 
 <task>
@@ -30,7 +30,7 @@ Analyze frontend:
 
 2. **Design Alignment**
    - Components vs DESIGN.md (colors, typography, spacing)
-   - rules/frontend.md compliance: distinctive fonts? sharp accents? transitions? No card grids / gradients?
+   - qualia-design/frontend.md compliance: distinctive fonts? sharp accents? transitions? No card grids / gradients?
    - Consistency across app (buttons, spacing, colors)
 
 3. **Frontend Perf**

package/skills/qualia-optimize/SKILL.md

@@ -73,7 +73,7 @@ ls .planning/decisions/ 2>/dev/null && cat .planning/decisions/*.md 2>/dev/null
 
 Also read rules:
 ```bash
-cat ~/.claude/rules/frontend.md 2>/dev/null
+cat ~/.claude/qualia-design/frontend.md 2>/dev/null
 cat ~/.claude/rules/security.md 2>/dev/null
 ```
 

package/skills/qualia-polish/SKILL.md

@@ -37,7 +37,7 @@ Before any work — design or otherwise — pass these gates. Skipping them prod
 
 | Gate | Required check | If fail |
 |---|---|---|
-| Substrate | `rules/design-laws.md`, `design-brand.md`, `design-product.md`, `design-rubric.md` exist and have been read | Read them. |
+| Substrate | `qualia-design/design-laws.md`, `design-brand.md`, `design-product.md`, `design-rubric.md` exist and have been read | Read them. |
 | PRODUCT | `PRODUCT.md` exists at project root, has `register:` field, and is not placeholder (`[TODO]` markers, < 200 chars) | Run setup: ask 5 questions and generate it. Never synthesize from prompt alone. |
 | DESIGN | `DESIGN.md` exists. If missing on App / Redesign scope, BLOCK and run setup. If missing on Component / Section / Critique / Quick scope, NUDGE and proceed. | Generate from PRODUCT.md + 3 questions. |
 | Slop-detect | `bin/slop-detect.mjs` is callable | Install or pull from framework. |
@@ -100,7 +100,7 @@ For App / Redesign / Section scope on multi-file work:
 - If the conversation already contains design-taste discussion (font/color/motion preferences threaded across multiple turns), prefer **forked subagents** (`--fork-session`) so they inherit the taste context. Otherwise, blank-context fan-out is fine for mechanical fixes.
 
 Each agent receives:
-- `rules/design-laws.md` + the matching register file
+- `qualia-design/design-laws.md` + the matching register file
 - `PRODUCT.md` + `DESIGN.md` (inlined)
 - Its 5 files (paths + contents)
 - Instruction: apply the Design Quality Rubric per file. Fix every dimension scoring < 3. Make literal edits. Do NOT change logic — only styling.
@@ -158,7 +158,7 @@ viewports: [
 For each iteration:
 
 1. Capture all 3 viewports
-2. Pass to a vision-model agent with `rules/design-rubric.md` as the prompt anchor + DESIGN.md as the spec
+2. Pass to a vision-model agent with `qualia-design/design-rubric.md` as the prompt anchor + DESIGN.md as the spec
 3. The agent scores 8 dimensions, anchored 1-5, with evidence per dimension
 4. Apply fixes ONLY to dimensions scored 1 or 2 (don't nitpick 3s; prevents oscillation)
 5. STOP if: all dimensions ≥ 3 (success), OR any dimension regressed from previous iteration (regression-stop), OR 2 iterations reached (hard cap)

package/skills/qualia-polish-loop/REFERENCE.md

@@ -58,7 +58,7 @@ Agent({
 Role: @~/.claude/agents/visual-evaluator.md
 
 <rubric>
-{INLINE rules/design-rubric.md §"The 8 dimensions" through §"Aggregate score"}
+{INLINE qualia-design/design-rubric.md §"The 8 dimensions" through §"Aggregate score"}
 </rubric>
 
 <brief>

package/skills/qualia-polish-loop/SKILL.md

@@ -18,7 +18,7 @@ See its own work. Fix its own work. Stop only when correct.
 
 ## What it does
 
-Takes a URL + design brief. Screenshots at 3 viewports (mobile / tablet / desktop). Spawns a vision evaluator that scores 8 dimensions of `rules/design-rubric.md` against the brief with cited evidence. Spawns up to 3 fix-builders in parallel for the top issues. Re-screenshots. Loops until all dimensions ≥ 3 or the kill-switch trips (regression, budget, or max iterations).
+Takes a URL + design brief. Screenshots at 3 viewports (mobile / tablet / desktop). Spawns a vision evaluator that scores 8 dimensions of `qualia-design/design-rubric.md` against the brief with cited evidence. Spawns up to 3 fix-builders in parallel for the top issues. Re-screenshots. Loops until all dimensions ≥ 3 or the kill-switch trips (regression, budget, or max iterations).
 
 Different from `/qualia-polish`: that one is read+edit+slop-detect, single pass. This one is **see+edit+verify+repeat** with a real loop and real screenshots.
 
@@ -39,7 +39,7 @@ Run these in order. Halt on the first failure.
 
 | Gate | Check | If fail |
 |---|---|---|
-| Substrate | `rules/design-rubric.md`, `rules/design-laws.md` exist | Run `npx qualia install` |
+| Substrate | `qualia-design/design-rubric.md`, `qualia-design/design-laws.md` exist | Run `npx qualia install` |
 | Brief | `--brief` PATH if provided, else `.planning/DESIGN.md`, else PRODUCT.md | If none, HALT: "No design brief found. Pass --brief or run /qualia-new." |
 | Browser | `node ~/.claude/skills/qualia-polish-loop/scripts/playwright-capture.mjs --url about:blank --out /tmp/qpl-preflight` exits 0 | HALT with the script's setup hint |
 | URL reachable | `curl -fsS -o /dev/null -w '%{http_code}' "$URL"` returns 2xx/3xx | HALT — start the dev server first |
@@ -91,7 +91,7 @@ node ~/.claude/skills/qualia-polish-loop/scripts/loop.mjs record \
 
 Exit codes: `0` = SUCCESS (all dims ≥ 3), `1` = CONTINUE (more iterations), `3` = KILLED (regression / budget / max).
 
-The orchestrator computes the verdict per `rules/design-rubric.md`:
+The orchestrator computes the verdict per `qualia-design/design-rubric.md`:
 
 - **all aggregate scores ≥ 3 AND no critical issues remain** → SUCCESS, exit loop
 - **same issue fingerprint recurred 3 consecutive iterations** → KILL, `LOOP_REGRESSION_DETECTED`

package/skills/qualia-polish-loop/fixtures/broken.html

@@ -1,8 +1,8 @@
 <!doctype html>
 <!--
   Deliberately broken page used by /qualia-polish-loop self-test Scenario 2.
-  Hits multiple absolute-ban patterns from rules/design-laws.md and
-  rules/design-brand.md so the vision evaluator has to identify them all.
+  Hits multiple absolute-ban patterns from qualia-design/design-laws.md and
+  qualia-design/design-brand.md so the vision evaluator has to identify them all.
   Banned font (Inter), pure white + pure black, blue-purple gradient,
   gradient text, identical 3-column card grid, "Get Started" / "Learn More"
   generic CTAs, side-stripe border-left:4px decorative, max-width:1280

package/skills/qualia-polish-loop/scripts/score.mjs

@@ -3,7 +3,7 @@
  * score.mjs -- Qualia visual-polish loop scoring utility.
  *
  * Takes a JSON object with 8 dimension scores and computes pass/fail
- * per the design rubric formula from rules/design-rubric.md.
+ * per the design rubric formula from qualia-design/design-rubric.md.
  *
  * Usage:
  *   echo '{"typography":3,"color":2,"spatial":3,"layout":3,"shadow":3,"motion":3,"microcopy":3,"container":3}' | node score.mjs

package/skills/qualia-postmortem/SKILL.md

@@ -95,7 +95,7 @@ matches the failure. Use this lookup:
 | Wave 2 task ran before wave 1 committed | `agents/planner.md` (dependency graph) |
 | Build passed locally, broke in CI | `rules/deployment.md` or a missing pre-deploy-gate scan |
 | RLS missing on new table | `rules/security.md` + `agents/builder.md` (security persona handling) |
-| Design regression — fonts off, contrast fail | `rules/frontend.md` + `skills/qualia-design/SKILL.md` |
+| Design regression — fonts off, contrast fail | `qualia-design/frontend.md` + `skills/qualia-design/SKILL.md` |
 | Migration unsafe (DROP without IF EXISTS, etc.) | `hooks/migration-guard.js` |
 | Verifier missed it | `agents/verifier.md` — most embarrassing case, address with extra care |
 

package/skills/qualia-quick/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-quick
-description: "Fast path for small tasks — bug fixes, tweaks, hot fixes. Skips full phase planning. Trigger on 'quick fix', 'small change', 'tweak', 'hot fix', 'one-line fix', 'quick edit', 'small bug'."
+description: "Fast inline path for trivial fixes — ≤1 hour, typically 1 file, no plan, NO subagent spawn. The current Claude does the work directly. For a 1-5 file change that justifies a fresh builder context, use /qualia-task instead. Trigger on 'quick fix', 'small change', 'tweak', 'hot fix', 'one-line fix', 'typo', 'config tweak'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-report/SKILL.md

@@ -9,9 +9,11 @@ allowed-tools:
   - AskUserQuestion
 ---
 
-# /qualia-report — Daily Clock-Out Report
+# /qualia-report — Daily Shift Report
 
-The end-of-day flow. Generates a report, commits it, pushes, uploads to the ERP, and tells the employee they can stop. Designed so Hasan and Moayad never get stuck on it.
+The end-of-day clock-out flow. Generates a shift report, commits it, pushes, uploads to the ERP, and tells the employee they can stop. Designed so Hasan and Moayad never get stuck on it.
+
+This is not a task-completion ceremony. The report records what happened during the employee's fixed work shift: shipped work, partial progress, blockers, investigation, meetings, or no-code work. A valid report can say "not finished yet" as long as it clearly explains the shift outcome and next step.
 
 ## Flags
 - `/qualia-report` — normal flow (generate, commit, push, upload to ERP)
@@ -60,18 +62,18 @@ None.   ← or list 1–N actual blockers (NOT "had to read docs" — that's nor
 2. ...
 ```
 
-**If `COUNT == 0`** — ask the employee gracefully (don't force a fake report):
+**If `COUNT == 0`** — ask the employee gracefully (don't force a fake report or fake completed task):
 
 Use `AskUserQuestion`:
 - header: "Empty day?"
-- question: "No commits in the last 8 hours. What did you do today?"
+- question: "No commits in the last 8 hours. What happened during your shift?"
 - options:
   - "Investigation / research only"
   - "Meetings / calls (no code)"
   - "Blocked — tell me on what"
   - "Time off / partial day"
 
-Capture the answer as the report body. Empty days are still valid clock-outs — the ERP needs to see them.
+Capture the answer as the report body. Empty days and unfinished work are still valid clock-outs — the ERP needs a truthful employee submission date and shift summary.
 
 ### Step 3 — Write report file
 
@@ -139,7 +141,7 @@ fi
 
 node ~/.claude/bin/qualia-ui.js divider
 node ~/.claude/bin/qualia-ui.js ok "Report $CLIENT_REPORT_ID complete."
-node ~/.claude/bin/qualia-ui.js info "You can clock out now. See you tomorrow."
+node ~/.claude/bin/qualia-ui.js info "Shift report submitted. You can clock out now."
 ```
 
 ## Common errors (read this when something goes wrong)

package/skills/qualia-research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-research
-description: "Deep-research a niche domain or library BEFORE planning a specific phase. Spawns the researcher agent with Context7/WebFetch access. Writes to .planning/phase-{N}-research.md."
+description: "Deep-research a niche domain or library BEFORE planning a specific phase. Spawns the researcher agent with Context7/WebFetch access. Writes to .planning/phase-{N}-research.md. Triggers: 'research X library', 'research the domain before planning', 'study Stripe webhooks', 'how do others do RAG', 'best practices for X', 'compare libraries', 'I need depth before planning phase N'. Distinct from /qualia-recall (which queries the local Obsidian vault) and /qualia-discuss (which interviews the user)."
 allowed-tools:
   - Bash
   - Read
@@ -75,7 +75,8 @@ Reqs: {REQ-IDs for this phase}
 
 <output_path>.planning/phase-{N}-research.md</output_path>
 
-Priority: Context7 → WebFetch → WebSearch.
+Priority: NotebookLM (cross-notebook query) → local knowledge layer (knowledge.js search + qualia-recall) → Context7 → WebFetch → WebSearch.
+Skip web round when local sources cover the question with confidence ≥ MEDIUM (per agents/researcher.md §1b).
 Include: recommendation, rationale, versions, code examples, alternatives, pitfalls, sources.
 ", subagent_type="qualia-researcher", description="Phase {N} research")
 ```
@@ -123,4 +124,5 @@ node ~/.claude/bin/qualia-ui.js end "PHASE {N} RESEARCH DONE" "/qualia-plan {N}"
 1. **One session per run.** Don't research phases 1-5 in one call.
 2. **Must produce a file.** Research in conversation only is worthless.
 3. **Honor locked decisions.** Don't research alternatives to locked choices.
-4. **Context7 first.** Try Context7 MCP before WebFetch.
+4. **Local-first.** Drain NotebookLM and `~/qualia-memory` before any external call. The team has already researched most domains we touch — querying existing notebooks is near-zero token cost AND higher-quality than fresh WebSearch.
+5. **Context7 before WebFetch.** When you do go external, Context7 first for libraries; only WebFetch for non-library content (blog posts, case studies, post-mortems).