qualia-framework 5.4.0 → 5.8.0

package/skills/{qualia-polish-loop → qualia-polish}/REFERENCE.md

@@ -1,4 +1,4 @@
-# REFERENCE — /qualia-polish-loop
+# REFERENCE — /qualia-polish --loop
 
 Verbatim agent prompts and operational details. Loaded on demand by SKILL.md, not carried in the system prompt. Per progressive-disclosure discipline (Matt Pocock): the agent reads SKILL.md first, then this file when it needs the spawn templates.
 
@@ -104,7 +104,7 @@ Agent({
 Role: @~/.claude/agents/builder.md
 
 <phase_context>
-You are inside /qualia-polish-loop iteration {N}. The vision evaluator scored
+You are inside /qualia-polish --loop iteration {N}. The vision evaluator scored
 the {dim} dimension at {score}. Your single task: fix that one dimension.
 
 <design>
@@ -133,7 +133,7 @@ the {dim} dimension at {score}. Your single task: fix that one dimension.
 2. Make the MINIMUM edit to fix this one dimension. Do not refactor. Do not change logic. Do not touch state management. Do not change copy unless this is a microcopy issue.
 3. Use design tokens from DESIGN.md. Do not invent new color values, font names, or spacing.
 4. After the edit, commit via the orchestrator (slop-detect-gated):
-     node ~/.claude/skills/qualia-polish-loop/scripts/loop.mjs commit-fix --state {STATE} --file {file} --slug {dim}-{short-keyword}
+     node ~/.claude/skills/qualia-polish/scripts/loop.mjs commit-fix --state {STATE} --file {file} --slug {dim}-{short-keyword}
    If slop-detect blocks (exit 2), READ the slop output and re-edit. If you cannot fix without violating slop-detect, return BLOCKED with the conflict.
 5. Return DONE with: file modified, lines changed, slop-detect: pass, commit: {sha}.
 </task>
@@ -260,6 +260,6 @@ This is intentional. Most visual regressions Fawzi has documented in `/insights`
 
 - Cross-browser rendering checks (Firefox / WebKit) — Chromium-only, per `qualia-polish` Stage 4 precedent
 - Accessibility audits beyond what the rubric scores — use `/qualia-polish` Stage 3 (Lighthouse + axe) for that
-- Performance regressions — use `/qualia-polish-loop` only after Lighthouse score passes
+- Performance regressions — use `/qualia-polish --loop` only after Lighthouse score passes
 - Reference-image-only mode (compare to a target screenshot without a brief) — currently the brief is required; reference is supplemental
-- Multi-page sweeps — one URL per invocation; chain `/qualia-polish-loop` per route for site-wide passes
+- Multi-page sweeps — one URL per invocation; chain `/qualia-polish --loop` per route for site-wide passes

package/skills/qualia-polish/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-polish
-description: "Scope-adaptive design pass — works on a single component, a route, the whole app, or a ground-up redesign. Trigger on 'polish', 'design pass', 'fix the design', 'redesign', 'critique', 'audit design', 'looks ugly', 'make it look better'. Replaces both /qualia-polish and /qualia-design from earlier versions."
+description: "Scope-adaptive design pass. Works on a single component, a route, the whole app, a ground-up redesign, or an autonomous visual loop. Trigger on 'polish', 'design pass', 'fix the design', 'redesign', 'critique', 'audit design', 'looks ugly', 'make it look better', 'polish loop', 'visual loop', 'fix what I see', 'iterate on the design until it's correct'. Replaces /qualia-polish-loop (now /qualia-polish --loop) and /qualia-design from earlier versions."
 allowed-tools:
   - Bash
   - Read
@@ -9,12 +9,12 @@ allowed-tools:
   - Grep
   - Glob
   - Agent
-argument-hint: "[file|route|--redesign|--critique|--quick] [--register=brand|product]"
+argument-hint: "[file|route|--redesign|--critique|--quick|--loop] [--register=brand|product] [--brief PATH] [--max 8] [--viewports 375,768,1440]"
 ---
 
 # /qualia-polish — Scope-Adaptive Design Pass
 
-One command. Six scopes. Use it whenever you need design work — from a 30-second component touch-up to a 30-minute ground-up redesign.
+One command. Seven scopes. Use it whenever you need design work, from a 30-second component touch-up to a 30-minute ground-up redesign to a fully autonomous see-fix-verify loop.
 
 ## Scopes
 
@@ -28,8 +28,17 @@ The first argument selects the scope. Stage selection follows from scope.
 | `/qualia-polish --redesign` | **Redesign** | ~30m | all + Stage 1 mandatory + 2 vision iterations |
 | `/qualia-polish --critique` | **Critique** | read-only | 0, 4, 5 (no edits) |
 | `/qualia-polish --quick` | **Quick** | ~1m | 0, 2, 7 (gates only, no vision loop) |
+| `/qualia-polish --loop {url}` | **Loop** | ~5-15m | autonomous see/fix/verify, max 8 iterations |
 
-Other flags: `--register=brand|product` to override register inference.
+Other flags: `--register=brand|product` overrides register inference. Loop-specific flags: `--brief PATH`, `--max N`, `--viewports 375,768,1440`, `--ref PATH`, `--budget 100000`.
+
+## --loop mode (autonomous visual loop)
+
+When `--loop` is the first flag, the polish run is fully autonomous: screenshot a live URL at three viewports, score 8 design dimensions of `qualia-design/design-rubric.md` against the brief using vision, fix top issues in the codebase, re-screenshot, repeat until every dimension scores ≥ 3 or the kill-switch fires (regression, budget cap, max iterations).
+
+This is the surface formerly known as `/qualia-polish-loop` (consolidated into a flag in v5.8.0). The scripts ship at `skills/qualia-polish/scripts/{loop,playwright-capture,score}.mjs`; vision evaluator is `agents/visual-evaluator.md`; full loop spec lives in this skill's `REFERENCE.md`.
+
+When `--loop` is detected on entry, route to the loop process documented in `REFERENCE.md` and stop executing the standard stages below. The two paths share Stage 0 substrate gates and the rubric, but diverge from Stage 1 onward.
 
 ## Setup gates (non-optional, every scope)
 

package/skills/{qualia-polish-loop → qualia-polish}/scripts/loop.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * loop.mjs — orchestrator state-machine for /qualia-polish-loop.
+ * loop.mjs — orchestrator state-machine for /qualia-polish --loop.
  *
  * Claude (the parent session) drives the loop by issuing CLI commands. This
  * script keeps the deterministic state — iteration counter, regression
@@ -294,7 +294,7 @@ switch (cmd) {
   case "--help":
   case "-h":
   case undefined:
-    console.log(`loop.mjs — orchestrator for /qualia-polish-loop
+    console.log(`loop.mjs — orchestrator for /qualia-polish --loop
 
 Commands:
   init       --state PATH (--url URL | --routes URL1,URL2,...) [--brief PATH] [--ref PATH] [--max 8] [--budget 100000] [--reduced-motion]

package/skills/{qualia-polish-loop → qualia-polish}/scripts/playwright-capture.mjs

@@ -36,7 +36,7 @@ function parseArgs() {
     } else if (a === "--wait" && argv[i + 1]) args.wait = parseInt(argv[++i], 10);
     else if (a === "--reduced-motion") args.reducedMotion = true;
     else if (a === "--help" || a === "-h") {
-      console.log(`playwright-capture.mjs — Screenshot capture for /qualia-polish-loop
+      console.log(`playwright-capture.mjs — Screenshot capture for /qualia-polish --loop
 
 Usage:
   node playwright-capture.mjs --url <url> --out <dir> [--viewports 375,768,1440] [--wait 1500] [--reduced-motion]

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-road/SKILL.md

@@ -45,23 +45,22 @@ Every road agent loads `PRODUCT.md + DESIGN.md + design-laws.md` substrate. Buil
 /qualia-polish --quick                       ~1m  gates only
 ```
 
-## /qualia-polish-loop -- autonomous visual QA (v5.1+, hardened in v5.2)
+## /qualia-polish --loop -- autonomous visual QA (v5.1+, consolidated into /qualia-polish in v5.8)
 ```
-/qualia-polish-loop http://localhost:3000                screenshot + eval + fix loop
-/qualia-polish-loop {url} --max 4                       cap iterations
-/qualia-polish-loop {url} --ref design.png              anchor to reference image
-/qualia-polish-loop {url} --reduced-motion              force prefers-reduced-motion (v5.2+)
-/qualia-polish-loop --routes /a,/b,/c                   multi-route sweep (v5.2+)
+/qualia-polish --loop http://localhost:3000               screenshot + eval + fix loop
+/qualia-polish --loop {url} --max 4                       cap iterations
+/qualia-polish --loop {url} --ref design.png              anchor to reference image
+/qualia-polish --loop {url} --reduced-motion              force prefers-reduced-motion
+/qualia-polish --loop --routes /a,/b,/c                   multi-route sweep
 ```
 Screenshots at 3 viewports (375/768/1440), scores 8 design dimensions using vision, fixes issues, re-screenshots, loops until all dims >= 3 or kill-switch triggers. Per-iteration git commits for clean revert.
 
-## v5.3+ skills (Matt Pocock gaps closed)
+## v5.3+ skills
 ```
-/qualia-prd            synthesize current conversation → .planning/PRD-{slug}.md (durable feature spec)
 /qualia-hook-gen       convert a CLAUDE.md/rules instruction into a deterministic pre-tool-use hook
-/qualia-optimize --deepen   now spawns 3 parallel interface-design variants per candidate (Step 5b)
+/qualia-optimize --deepen   spawns 3 parallel interface-design variants per candidate (Step 5b)
 ```
-`/qualia-prd` pairs with `/qualia-issues` to form the PRD → vertical-slice → execute loop. `/qualia-hook-gen` reduces lifetime token cost (each migrated rule frees ~50-200 tokens per request). `/qualia-optimize --deepen` produces dramatically better refactor RFCs because 3 radically-different interfaces are surfaced and the human picks/hybridizes.
+`/qualia-hook-gen` reduces lifetime token cost (each migrated rule frees ~50-200 tokens per request). `/qualia-optimize --deepen` produces dramatically better refactor RFCs because 3 radically-different interfaces are surfaced and the human picks/hybridizes.
 
 ## Alignment substrate (v5.0+)
 Before high-stakes phases, run alignment skills against `.planning/CONTEXT.md` (domain glossary) and `.planning/decisions/` (ADRs):
@@ -80,7 +79,7 @@ Before high-stakes phases, run alignment skills against `.planning/CONTEXT.md` (
 ```
 Lost?        → /qualia        (state router — tells you the next command)
 Stuck/weird? → /qualia-idk    (diagnostic — spawns plan-view + code-view agents in parallel)
-Quick fix?   → /qualia-quick  (skip planning for small tasks)
+Single feature? → /qualia-feature (auto-scoped: inline for trivia, fresh spawn for 1-5 files)
 Paused?      → /qualia-resume (restore from .continue-here.md or STATE.md)
 End of day?  → /qualia-report (mandatory before clock-out; writes ERP payload)
 Debug bug?   → /qualia-debug  (feedback-loop-first investigation)

package/templates/CONTEXT.md

@@ -18,14 +18,15 @@ A unit of work inside a milestone. 2–5 tasks. Ends in a verification gate.
 **Avoid:** epic, story, ticket, sprint.
 
 ### Task
-A single commit-sized unit with one verification contract.
-**Avoid:** subtask, chore, todo.
+A framework-internal execution unit: one commit-sized work item with one verification contract.
+**Avoid:** using "task" as an ERP assignment or employee performance label unless the product domain explicitly needs it.
 
 ## Relationships
 - Project holds many Milestones
 - Milestone holds many Phases
 - Phase holds many Tasks
 - Task carries one Verification Contract
+- ERP tracks project deadlines, milestone deadlines, and employee shift submissions; framework tasks stay internal.
 - {{add domain-specific relationships, e.g. "Customer holds many Orders"}}
 
 ## Flagged ambiguities

package/templates/help.html

@@ -479,7 +479,7 @@
       <li><span class="rule-icon">1</span> Feature branches by default &mdash; OWNER overrides must be explicit</li>
       <li><span class="rule-icon">2</span> Read before write &mdash; understand files before editing</li>
       <li><span class="rule-icon">3</span> MVP first &mdash; build what's asked, nothing extra</li>
-      <li><span class="rule-icon">4</span> /qualia-report before clock-out &mdash; mandatory, enforced by ERP</li>
+      <li><span class="rule-icon">4</span> /qualia-report before clock-out &mdash; mandatory shift submission in ERP</li>
       <li><span class="rule-icon">5</span> Secrets through approved flows &mdash; use set-erp-key or ask Fawzi</li>
       <li><span class="rule-icon">6</span> Stuck 30+ minutes? Ask Fawzi</li>
     </ul>

package/templates/phase-context.md

@@ -13,11 +13,12 @@ Captured during `/qualia-discuss {N}` — decisions, trade-offs, and constraints
 
 ## Locked Decisions
 
-Non-negotiable choices. Planner must honor these exactly.
+Non-negotiable choices. Planner must honor these exactly. Every row has a stable ID (`D-NN`) — the planner's Decision Coverage Audit checks each is implemented; the plan-checker BLOCKS if any is missing.
 
-| Decision | Rationale | Source |
-|----------|-----------|--------|
-| {e.g., "Use Supabase RLS for authorization, not middleware"} | {e.g., "Client compliance requires database-level checks"} | {who/when} |
+| ID | Decision | Rationale | Source |
+|----|----------|-----------|--------|
+| D-01 | {e.g., "Use Supabase RLS for authorization, not middleware"} | {e.g., "Client compliance requires database-level checks"} | {who/when} |
+| D-02 | {next decision} | {rationale} | {source} |
 
 ## Discretion (Planner Chooses)
 

package/templates/project-discovery.md

@@ -0,0 +1,83 @@
+---
+project_type: {demo or full}
+discovered_at: {YYYY-MM-DD}
+discovery_mode: project
+---
+
+# Project Discovery, {Project Name}
+
+The non-technical kickoff interview output. `/qualia-discuss` writes this in PROJECT MODE before `/qualia-new` generates JOURNEY.md. Captures intent, audience, brand, and constraints in the user's own words.
+
+Demo path: 8 questions. Full-project path: 14 questions.
+
+## 1. The one-line pitch
+
+> {What is this thing, in one sentence a stranger would understand?}
+
+## 2. Who is it for
+
+> {Name three real humans who will use this. Not personas, real names plus their scenario.}
+
+## 3. The "remember 24 hours later" sentence
+
+> {What does someone remember 24 hours after first using this?}
+
+## 4. Three anti-references
+
+> {Three sites or apps this should NOT look like, with one-line reasons each.}
+
+## 5. Brand voice
+
+> {Three adjectives, then one paragraph of voice in motion — an error message, a confirmation, an empty state.}
+
+## 6. Success criterion
+
+> {How does the client know this worked? One observable outcome.}
+
+## 7. Hard constraints
+
+> {Anything that is non-negotiable: stack, deadline, compliance, integrations, budget.}
+
+## 8. Out of scope
+
+> {What is intentionally NOT in this project, even if it would be obvious to add.}
+
+---
+
+The remaining six questions only run for `project_type: full`. Demo mode stops here.
+
+## 9. Milestone arc, in the client's words
+
+> {After the demo, what's the next chapter? After that, what's the chapter after? Stop at three to five chapters total. The last chapter is always Handoff.}
+
+## 10. Compliance and legal
+
+> {Anything regulated: payments, medical, legal, finance, accessibility commitments, data residency.}
+
+## 11. Integrations
+
+> {Third-party systems this must talk to, in priority order.}
+
+## 12. Content and copy
+
+> {Who writes the copy and where does it live, today and after handoff?}
+
+## 13. Team and roles after handoff
+
+> {Who maintains this after we ship? What can they do, what can't they do?}
+
+## 14. Budget and timeline shape
+
+> {Fixed deadline, fixed scope, or fixed budget? Pick one — the other two flex.}
+
+---
+
+## How this feeds `/qualia-new`
+
+- §1-§5 seed PROJECT.md (one-line pitch, what we're building) and PRODUCT.md (users, register, voice, anti-references).
+- §6 becomes the first row of the success-criteria table in ROADMAP.md.
+- §7-§8 populate PROJECT.md's "Out of Scope" and the constraints section.
+- §9 (full only) seeds JOURNEY.md milestone names + "why now" lines.
+- §10-§14 (full only) feed research scoping and the Handoff milestone checklist.
+
+Demo projects skip §9-§14 because they ARE one milestone — the journey is just that milestone plus an implicit "client signs, we extend" branch handled by `/qualia-milestone`.

package/templates/project.md

@@ -1,8 +1,15 @@
+---
+project_type: full
+---
+
 # {Project Name}
 
 ## Client
 {client name}
 
+## Project Type
+{demo or full — demo is a single shippable milestone for a sales conversation; full is the multi-milestone arc to Handoff}
+
 ## What We're Building
 {description}