qualia-framework 5.5.0 → 5.9.0

package/skills/qualia-feature/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: qualia-feature
+description: "Auto-scoped single feature build. Picks inline (≤1 trivial file, no spawn) or fresh builder spawn (1-5 logic files, atomic commit) automatically from the task description. Refuses and routes to /qualia-plan for 5+ files or full phases. Replaces /qualia-quick and /qualia-task. Flags: --force-spawn forces a builder, --force-inline forces inline. Trigger phrases: 'build this one thing', 'add a component', 'implement this feature', 'quick fix', 'small change', 'tweak', 'hot fix', 'one-line fix', 'typo', 'config tweak', 'qualia-feature'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
+  - AskUserQuestion
+---
+
+# /qualia-feature — Auto-scoped Single Feature
+
+One command for everything between a typo and a phase. Auto-detects scope from the task description and picks the right execution path. No more guessing whether to use `/qualia-quick` or `/qualia-task`.
+
+## Usage
+
+`/qualia-feature` — describe interactively
+`/qualia-feature {description}` — run with description directly
+`/qualia-feature --force-spawn {description}` — force a fresh builder spawn (even if auto would inline)
+`/qualia-feature --force-inline {description}` — force inline path (even if auto would spawn)
+
+## When to use
+
+- One feature outside a planned phase
+- A bug fix, typo, config tweak, or one-line change
+- A 1-5 file feature, component, API route, or integration
+- A refactor of a single module
+
+## When NOT to use
+
+- 5+ files or multiple subsystems touched → `/qualia-plan`
+- Part of a planned phase → `/qualia-build`
+- Investigating a symptom you can't name yet → `/qualia-debug`
+- Optimization or polish pass → `/qualia-optimize` or `/qualia-polish`
+
+## Process
+
+### 1. Capture description
+
+If invoked without args, ask: **"What do you want to build?"**
+
+Wait for free-text answer. Don't paraphrase back. Capture the user's exact phrasing — it feeds both the auto-scope classifier and the eventual commit message.
+
+### 2. Auto-detect scope
+
+Classify the description into one of three buckets:
+
+| Bucket | Heuristic | Path |
+|--------|-----------|------|
+| **inline** | Typo, comment edit, 1-line config change, single-word rename, dead-code removal, copy edit, link fix, version bump, single emoji/icon swap | Direct work, no spawn |
+| **spawn** | Add a component, add an API route, add a small migration + UI, implement a single feature, fix a non-trivial bug, refactor a module under 5 files | Fresh builder spawn |
+| **refuse** | "Build the dashboard", "implement payments", "ship the auth system", "add a checkout flow", any description that names a multi-step workflow or 5+ subsystems | Refuse, route to `/qualia-plan` |
+
+**Inline signals** (any one is sufficient):
+- "fix typo", "fix the comment", "rename X to Y", "remove unused", "update copy", "change the link", "bump version"
+- Description fits in one short sentence and names one specific micro-change
+- The action is reversible by a single `git revert`
+
+**Spawn signals** (any one is sufficient):
+- "add a", "implement", "build", "create" + a single noun (component, route, page, table, form, modal, hook, util, migration)
+- Description names a single feature with multiple touch points (e.g. "add a feedback form" → migration + API + UI = 3-4 files, but still one cohesive thing)
+- The work needs a fresh context to avoid contaminating the current conversation
+
+**Refuse signals** (any one is sufficient):
+- "build the X system", "implement the entire Y", "add complete Z support"
+- Description names a multi-milestone capability (auth, payments, search, admin panel) without a tight slice
+- Estimated touch ≥ 5 files OR ≥ 1 day
+
+### 3. Announce the route + escape hatch
+
+Show the user what was detected. Always offer the escape hatch:
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner feature
+node ~/.claude/bin/qualia-ui.js info "Detected scope: {inline|spawn|refuse}"
+node ~/.claude/bin/qualia-ui.js info "Reason: {one-line rationale}"
+```
+
+Then:
+
+- header: "Scope detected"
+- question: "Auto-scope says {bucket}. Proceed, or override?"
+- options:
+  - "Proceed with {bucket}"
+  - "Force inline" (only shown if bucket != inline)
+  - "Force spawn" (only shown if bucket != spawn)
+  - "Route to /qualia-plan" (only shown if bucket != refuse)
+  - "Re-describe"
+
+If `--force-spawn` or `--force-inline` was passed on the command line, skip this gate entirely and execute the forced path.
+
+### 4. Execute the inline path
+
+For inline scope:
+
+1. Read the file(s) that need to change (one read per file, no spawning).
+2. Make the edit directly using Edit/Write.
+3. Run `npx tsc --noEmit` if TypeScript and the change touches typed code; skip otherwise.
+4. Atomic commit with a clear conventional-commit message:
+
+```bash
+git add {specific files}
+git commit -m "fix: {description}"
+```
+
+5. Record in state:
+
+```bash
+node ~/.claude/bin/state.js transition --to note --notes "{brief description}" --tasks-done 1
+```
+
+6. End with:
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "FEATURE SHIPPED (inline)"
+```
+
+### 5. Execute the spawn path
+
+For spawn scope:
+
+1. Build a quick task spec (don't write to a file, just confirm with user):
+
+```bash
+node ~/.claude/bin/qualia-ui.js info "What: {what to build}"
+node ~/.claude/bin/qualia-ui.js info "Files: {files to create/modify, comma list}"
+node ~/.claude/bin/qualia-ui.js info "Done: {observable acceptance criteria, 1-3 bullets}"
+```
+
+Ask: **"Good to build?"** Wait for confirmation.
+
+2. Spawn the builder:
+
+```
+Agent(subagent_type="qualia-builder", description="Feature: {short title}")
+  prompt: |
+    Read your role: @~/.claude/agents/builder.md
+
+    <task>
+    {task description verbatim from user}
+    </task>
+
+    <files>
+    {files to create/modify}
+    </files>
+
+    <acceptance_criteria>
+    {1-3 observable bullets}
+    </acceptance_criteria>
+
+    <context>
+    Read .planning/PROJECT.md if it exists.
+    Read .planning/CONTEXT.md if it exists (domain glossary).
+    Follow rules/security.md, rules/frontend.md, rules/deployment.md as applicable.
+    Atomic commit. Run npx tsc --noEmit before commit.
+    </context>
+```
+
+3. After the builder returns, verify:
+   - `npx tsc --noEmit` exits 0 (rerun the builder up to 2x if it failed self-verify, per the v5.5.0 auto-heal pattern).
+   - Quick smoke test if applicable.
+   - Confirm the commit was made: `git log --oneline -1` shows the feature.
+
+4. Report:
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "Feature: {description}"
+node ~/.claude/bin/qualia-ui.js ok "Files: {files changed}"
+node ~/.claude/bin/qualia-ui.js ok "Commit: {commit hash}"
+node ~/.claude/bin/qualia-ui.js end "FEATURE SHIPPED (spawn)"
+```
+
+5. Record in state:
+
+```bash
+node ~/.claude/bin/state.js transition --to note --notes "{description}" --tasks-done 1
+```
+
+### 6. Execute the refuse path
+
+For refuse scope, do NOT build. Explain why and route:
+
+```bash
+node ~/.claude/bin/qualia-ui.js warn "This is too big for /qualia-feature (5+ files or multi-step workflow)."
+node ~/.claude/bin/qualia-ui.js info "Reason: {one-line — e.g. 'description names the entire auth system, not a slice'}"
+node ~/.claude/bin/qualia-ui.js end "ROUTED" "/qualia-plan"
+```
+
+If the user is sure it's small and the classifier got it wrong, they can re-invoke with `--force-spawn`.
+
+## Auto-scope examples
+
+| Description | Detected | Why |
+|-------------|----------|-----|
+| "fix the typo in the hero copy" | inline | typo + 1 file |
+| "rename `userId` to `user_id` in auth.ts" | inline | rename in 1 file |
+| "bump next from 16.0.3 to 16.0.4" | inline | version bump, 1 file |
+| "add a Feedback button that opens a modal" | spawn | single feature, 2-4 files |
+| "add a GET /api/health route returning ok" | spawn | 1 route, but worth a fresh context for test pass |
+| "implement Stripe subscription checkout" | refuse | multi-file + webhooks + admin = phase |
+| "build the dashboard" | refuse | names a multi-page surface |
+| "add the admin user-management page" | refuse | usually 5+ files (table, modals, API, RLS, types) |
+
+## Rules
+
+1. **Auto-scope is confident by default, with two escape hatches.** Trust the classifier; use `--force-spawn` or `--force-inline` when it guesses wrong. Don't waste a question on "which path?" — propose and let the user override.
+2. **Inline is genuinely fresh-context-free.** No subagent spawn for inline work — the current Claude does it directly. That's the whole speed advantage over `/qualia-task`.
+3. **Spawn means atomic.** One feature, one commit, one acceptance criteria block. No grab-bag commits that touch four unrelated things.
+4. **Refuse means refuse.** When a description is phase-sized, route to `/qualia-plan`, don't try to fit it in. The auto-classifier is the gate that protects the work from sprawling.
+5. **STATE.md via state.js only.** Never edit STATE.md or tracking.json by hand. Both paths record through `state.js transition`.
+6. **Follow rules/* on every path.** Security, frontend, deployment rules apply equally to inline and spawn. Read-before-write is non-negotiable.

package/skills/qualia-milestone/SKILL.md

@@ -38,6 +38,77 @@ node ~/.claude/bin/state.js check
 
 If either fires (without `--force`), stop and show the error. The user must verify remaining phases first (or add `--force` for explicit bypass on a preview/demo milestone).
 
+### 1b. Demo-Extension Branch (v5.6)
+
+Detect if this is a demo project closing its only milestone:
+
+```bash
+PROJECT_TYPE=$(grep -E "^project_type:" .planning/PROJECT.md | head -1 | awk '{print $2}')
+MILESTONE_COUNT=$(grep -cE "^## Milestone " .planning/JOURNEY.md 2>/dev/null || echo 0)
+```
+
+If `PROJECT_TYPE=demo` AND `MILESTONE_COUNT=1`, the demo's one milestone is closing — there is no "next milestone" in the file. Ask the conversion question:
+
+- header: "Demo shipped — what next?"
+- question: "The demo milestone is done. Did the client sign? If yes, extend this into a full project (regenerate JOURNEY.md as a multi-milestone arc to Handoff). If no, this project closes here."
+- options:
+  - "Client signed — extend to full project"
+  - "Demo only — close here, project is done"
+  - "Pause" — don't close yet, decide later
+
+**If "Client signed — extend to full project":**
+
+1. Update `.planning/PROJECT.md` frontmatter: `project_type: full`.
+2. Run a brief discovery top-up — invoke `/qualia-discuss` in PROJECT MODE, but only ask §9-§14 (the full-project-only questions). This adds the milestone arc, compliance, integrations, content ownership, handoff team, and budget shape.
+3. Spawn the roadmapper in `extend-to-full` mode (see prompt below). It reads the existing single milestone (now M1), the updated discovery, and produces a full JOURNEY.md with M2..M{N-1} sketches plus the Handoff milestone.
+4. Then proceed with the standard close-milestone flow (Steps 2-9) — M1 closes, M2 opens, the user is asked to continue.
+
+Roadmapper prompt for the extension:
+
+```
+Agent(prompt="
+Read your role: @~/.claude/agents/roadmapper.md
+
+<mode>extend-demo-to-full</mode>
+<existing_journey>.planning/JOURNEY.md</existing_journey>
+<discovery>.planning/project-discovery.md</discovery>
+
+<task>
+The existing JOURNEY.md has 1 milestone (the demo, now M1 and shipped). Extend it
+into a 2-5 milestone arc to Handoff:
+
+- Keep M1 exactly as-is (it shipped).
+- Add M2..M{N-1} based on §9 of project-discovery.md (the milestone-arc question
+  the user answered when converting from demo).
+- Append a Handoff milestone (fixed 4 phases: Polish, Content + SEO, Final QA,
+  Handoff).
+- Update REQUIREMENTS.md to add REQ-IDs for the new milestones.
+- Do NOT regenerate ROADMAP.md here — that happens in Step 7 of /qualia-milestone
+  when M2 opens.
+
+Mark M2..M{N-1} as sketched, not fully detailed. The user gets full detail per
+milestone when /qualia-milestone opens each one.
+</task>
+", subagent_type=\"qualia-roadmapper\", description=\"Extend demo to full project\")
+```
+
+**If "Demo only — close here":** treat the demo as a shipped-and-done project. Skip Steps 2-9 of the normal flow. Just run:
+
+```bash
+node ~/.claude/bin/state.js close-milestone --force
+node ~/.claude/bin/qualia-ui.js end "DEMO SHIPPED" "/qualia-report"
+```
+
+In `--auto` mode, inline-invoke `/qualia-report` and stop.
+
+**If "Pause":** stop, show:
+
+```bash
+node ~/.claude/bin/qualia-ui.js info "Demo milestone left open. Run /qualia-milestone again when you decide."
+```
+
+If the demo branch did NOT fire (full project, or demo with multiple milestones already after extension), continue to Step 2.
+
 ### 2. Banner + Confirm
 
 ```bash
@@ -206,4 +277,5 @@ node ~/.claude/bin/qualia-ui.js end "M{N} CLOSED · M{N+1} OPEN" "/qualia-plan 1
 3. **Archive, don't delete.** Old phase work stays accessible via `.planning/archive/`.
 4. **New milestone = fresh phase numbering.** First phase of the new milestone is Phase 1, not Phase {N+1}.
 5. **ERP sync aware.** tracking.json milestones[] gets a summary entry on close — the ERP reads this to render the tree.
-6. **Handoff is the final milestone.** If the current milestone IS Handoff, there is no "next" — route to `/qualia-report` and the project is done.
+6. **Handoff is the final milestone (full projects).** If the current milestone IS Handoff, there is no "next" — route to `/qualia-report` and the project is done.
+7. **Demo closes via the demo-extension branch (Step 1b).** A demo's single milestone closing triggers the "client signed?" question. The framework never silently auto-extends a demo without asking — the conversion is a real business decision.

package/skills/qualia-new/SKILL.md

@@ -58,27 +58,41 @@ test -d .git && echo "HAS_GIT"
 test -f .planning/codebase/README.md && echo "ALREADY_MAPPED"
 ```
 
-If existing code is detected AND not already mapped, ask the user whether to run `/qualia-map` inline first. If yes, invoke the `qualia-map` skill inline, wait for completion, then continue to Step 1.
+If existing code is detected AND not already mapped, ask the user whether to run `/qualia-map` inline first. If yes, invoke the `qualia-map` skill inline, wait for completion, then continue to Step 0.6.
 
-### Step 1. Deep Questioning
+### Step 0.6. Project Type Gate (Demo vs Full)
 
-Load the questioning methodology:
+The single most important fork in the workflow. Demo and Full produce different journeys, different research depth, different milestone counts.
 
-```bash
-cat ~/.claude/qualia-references/questioning.md 2>/dev/null
-```
+- header: "Project shape"
+- question: "Is this a demo (single shippable milestone, sales conversation) or a full project (multi-milestone arc to Handoff)?"
+- options:
+  - "Demo" — one shippable milestone, real backend, no mocks. Built to win a client conversation, extensible via `/qualia-milestone` if they sign.
+  - "Full project" — the full multi-milestone arc to Handoff. 2-5 milestones planned upfront.
+
+Store the answer as `PROJECT_TYPE=demo` or `PROJECT_TYPE=full`. It drives Steps 1, 8, and 10.
 
-Follow the thread. Challenge vagueness. Make abstract concrete. Check the 4-item mental checklist (what, why, who, done).
+**Demo design philosophy is non-negotiable:** real backend always, DESIGN.md mandatory, slop-detect hard-block. Speed comes from skipping multi-milestone planning, NEVER from skipping design quality or mocking the backend.
 
-Use `AskUserQuestion` for forks with 2-4 concrete interpretations. Use free text when you want them to think freely.
+### Step 1. Mandatory Discovery Interview (PROJECT MODE)
 
-**Decision gate** — when you could write a clear PROJECT.md:
+Invoke `/qualia-discuss` inline in PROJECT MODE — non-technical kickoff interview. 8 questions for demo, 14 for full project. Pass `PROJECT_TYPE` so the discuss skill skips the type question.
+
+This step REPLACES the old free-form "deep questioning" loop. The discuss skill captures answers verbatim into `.planning/project-discovery.md`, which seeds PROJECT.md, PRODUCT.md, CONTEXT.md, and (for full projects) JOURNEY.md milestone names.
+
+```bash
+# Inline-invoke qualia-discuss in PROJECT MODE
+# (no phase number arg = PROJECT MODE; PROJECT_TYPE env tells it which question set)
+PROJECT_TYPE=$PROJECT_TYPE qualia-discuss
+```
+
+After the interview returns, `.planning/project-discovery.md` exists with the user's answers. Read it. Confirm understanding:
 
 - header: "Ready?"
-- question: "I understand what you're building. Create PROJECT.md and move forward?"
-- options: ["Create PROJECT.md", "Keep exploring"]
+- question: "I have what I need to write PROJECT.md and move forward. Continue?"
+- options: ["Continue", "More questions"]
 
-Loop until "Create PROJECT.md".
+If "More questions": re-invoke `/qualia-discuss` for additional rounds. Otherwise continue.
 
 ### Step 2. Detect Project Type
 
@@ -216,11 +230,16 @@ node ~/.claude/bin/qualia-ui.js banner research
 mkdir -p .planning/research
 ```
 
-Say: **"Running 4 parallel research agents (stack, features, architecture, pitfalls)..."**
+**Research scope branches on `PROJECT_TYPE`:**
+
+- **Demo** (`PROJECT_TYPE=demo`): pass `<scope>quick</scope>` to all 4 researchers AND the synthesizer. Each researcher gets a 3-call budget instead of 8. The synthesizer produces a single-milestone suggestion (no Handoff, no multi-milestone arc). Total research time drops roughly 3x with no loss of correctness on the demo path — the depth was wasted when there's only one milestone to ship.
+- **Full project** (`PROJECT_TYPE=full`): standard scope, 8-call budget per researcher, full milestone-arc synthesis.
 
-Spawn 4 researchers in parallel (single message, 4 Agent tool calls), with multi-milestone scope. See REFERENCE.md section "Researcher prompts (4 dimensions)" for the verbatim prompt templates.
+Say: **"Running 4 parallel research agents (stack, features, architecture, pitfalls)..."** (demo: append "— quick scope").
 
-**After all 4 complete, spawn synthesizer.** See REFERENCE.md section "Synthesizer prompt" for the verbatim prompt template.
+Spawn 4 researchers in parallel (single message, 4 Agent tool calls). See REFERENCE.md section "Researcher prompts (4 dimensions)" for the verbatim prompt templates. Include `<scope>quick</scope>` in each prompt when `PROJECT_TYPE=demo`.
+
+**After all 4 complete, spawn synthesizer.** See REFERENCE.md section "Synthesizer prompt" for the verbatim prompt template. Include `<scope>quick</scope>` when `PROJECT_TYPE=demo`.
 
 **Commit:**
 ```bash
@@ -258,7 +277,12 @@ Gather any additional requirements the user wants that research missed.
 node ~/.claude/bin/qualia-ui.js banner roadmap
 ```
 
-Spawn the roadmapper with full-journey mandate. If the user passed `--full-detail`, include `<full_detail>true</full_detail>` in the prompt so the roadmapper writes complete phase detail for ALL milestones. See REFERENCE.md section "Roadmapper prompt" for the verbatim prompt template.
+**Roadmapper output branches on `PROJECT_TYPE`:**
+
+- **Demo** (`PROJECT_TYPE=demo`): roadmapper produces a 1-milestone JOURNEY.md (the demo milestone, 2-4 phases) plus a matching REQUIREMENTS.md and a fully-detailed ROADMAP.md. No "Handoff" milestone is appended — the demo is its own complete artifact. The journey-tree at Step 11 shows a single rung; the "extend to full project" branch is handled later by `/qualia-milestone` if the client signs.
+- **Full project** (`PROJECT_TYPE=full`): roadmapper produces the standard 2-5 milestone arc ending in Handoff. Milestone 1 fully detailed, M2..M{N-1} sketched (unless `--full-detail`).
+
+Spawn the roadmapper with `<project_type>$PROJECT_TYPE</project_type>` in the prompt. If the user passed `--full-detail`, include `<full_detail>true</full_detail>` so the roadmapper writes complete phase detail for ALL milestones (full project only; demo always has full detail because there's only one milestone). See REFERENCE.md section "Roadmapper prompt" for the verbatim prompt template.
 
 ### Step 11. Present the Journey (single view)
 
@@ -366,12 +390,15 @@ Do NOT use `--quick` for: client projects, anything with compliance stakes, anyt
 
 ## Rules
 
-1. **Research runs automatically.** No permission ask. Only `--quick` skips it. This is a v4 invariant.
-2. **The journey includes Handoff.** Every project's final milestone is literally named "Handoff" with 4 standard phases. The roadmapper enforces this.
-3. **Single approval gate.** One gate for the whole journey. Not per-milestone, not per-phase.
-4. **Milestone count: 2-5.** Hard floor 2, hard ceiling 5. Bigger projects defer remainder to post-handoff v2.
-5. **Milestone 1 is fully detailed.** M2..M{N-1} are sketched. Detail fills in when each milestone opens.
-6. **STATE.md through state.js.** Never edit STATE.md or tracking.json by hand.
-7. **Inline skill invocation.** When Step 0.5 offers `/qualia-map`, invoke it inline — don't exit.
-8. **CONTEXT.md is mandatory (v5.0).** Every project gets a domain glossary at `.planning/CONTEXT.md`. Seeded from questioning answers. Loaded by every road agent. Kept terse.
-9. **ADRs are scarce.** `.planning/decisions/` exists from day one but only fills with hard-to-reverse, surprising-without-context, real-tradeoff decisions. Cargo-culting ADRs ruins the signal.
+1. **Project type is the first fork.** Step 0.6 asks Demo vs Full Project. Every downstream step branches on this. Don't skip it, don't infer it.
+2. **Discovery interview is mandatory (v5.6).** Step 1 always invokes `/qualia-discuss` in PROJECT MODE. No free-form questioning loop, no "I'll just sketch PROJECT.md from the user's first message." The interview is 8 questions for demo, 14 for full project.
+3. **Research runs automatically.** No permission ask. Only `--quick` skips it. Demo path uses `<scope>quick</scope>` (3-call budget per researcher); full project uses standard 8-call budget.
+4. **Demo design philosophy is non-negotiable.** Real backend always, DESIGN.md mandatory, slop-detect hard-block. Speed comes from skipping multi-milestone planning, never from skipping design quality or mocking the backend. A demo that uses mock data is not a Qualia demo.
+5. **Demos are 1 milestone, full projects are 2-5.** Demo journeys have no "Handoff" — the demo IS the artifact. Full projects always end in Handoff (fixed 4 phases). The journey-tree adapts to both shapes.
+6. **The full-project journey includes Handoff.** Every full project's final milestone is literally named "Handoff" with 4 standard phases. The roadmapper enforces this.
+7. **Single approval gate.** One gate for the whole journey. Not per-milestone, not per-phase.
+8. **Milestone 1 is fully detailed (full projects).** M2..M{N-1} are sketched. Detail fills in when each milestone opens. Demos are always fully detailed because they're 1 milestone.
+9. **STATE.md through state.js.** Never edit STATE.md or tracking.json by hand.
+10. **Inline skill invocation.** When Step 0.5 offers `/qualia-map` or Step 1 invokes `/qualia-discuss`, invoke it inline — don't exit.
+11. **CONTEXT.md is mandatory.** Every project gets a domain glossary at `.planning/CONTEXT.md`. Seeded from the discovery interview answers. Loaded by every road agent. Kept terse.
+12. **ADRs are scarce.** `.planning/decisions/` exists from day one but only fills with hard-to-reverse, surprising-without-context, real-tradeoff decisions. Cargo-culting ADRs ruins the signal.

package/skills/qualia-optimize/SKILL.md

@@ -146,7 +146,7 @@ Collect all 3 proposals. Present to the user as a side-by-side table:
 | 2 | ... | ... | ... | ... |
 | 3 | ... | ... | ... | ... |
 
-User picks `1`, `2`, `3`, or `hybrid` (with notes on which elements from which proposals to combine). The synthesizer then writes a "Refactor RFC" to `.planning/REFACTOR-{slug}.md` and optionally opens a GH issue (mirrors `/qualia-prd` flow).
+User picks `1`, `2`, `3`, or `hybrid` (with notes on which elements from which proposals to combine). The synthesizer then writes a "Refactor RFC" to `.planning/REFACTOR-{slug}.md` and optionally opens a GH issue.
 
 **Why parallel + radically different**: a single deepening proposal anchors on the first idea the LLM has. Three parallel proposals with diverse design constraints surface trade-offs the user can see at a glance — and the human's "taste" dominates the choice rather than the agent's first instinct. Empirically (Matt Pocock + Qualia internal testing) this produces dramatically better refactor RFCs than a single-pass proposal.
 

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

@@ -168,6 +168,17 @@ REPORT_FILE=".planning/reports/report-{date}.md"
 SUBMITTED_BY=$(git config user.name || echo "unknown")
 SUBMITTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 
+# Idempotency key — deterministic per (client_report_id, submitted_at). A retry
+# of the same shift report carries the same key, so the ERP can dedupe at the
+# header level in addition to the UPSERT on (project_id, client_report_id).
+IDEMPOTENCY_KEY=$(node -e "
+  const c=require('crypto');
+  const seed='$CLIENT_REPORT_ID|$SUBMITTED_AT|'+require('path').basename(process.cwd());
+  // RFC 4122 v5-style: deterministic UUID from sha1 of the seed
+  const h=c.createHash('sha1').update(seed).digest('hex');
+  console.log([h.slice(0,8),h.slice(8,12),'5'+h.slice(13,16),'8'+h.slice(17,20),h.slice(20,32)].join('-'));
+")
+
 # Guard: API key required for upload (otherwise curl posts an empty bearer)
 if [ "$ERP_ENABLED" = "true" ] && [ -z "$API_KEY" ] && [ "$DRY_RUN" != "true" ]; then
   node ~/.claude/bin/qualia-ui.js warn "ERP API key missing (~/.claude/.erp-api-key). Run: qualia-framework set-erp-key <key>"
@@ -189,6 +200,17 @@ PAYLOAD=$(
     const commits=[];try{const r=spawnSync('git',['log','--oneline','--since=8 hours ago','--format=%h'],{encoding:'utf8',timeout:3000});if(r.stdout)commits.push(...r.stdout.trim().split('\n').filter(Boolean));}catch{}
     const gitRemote=t.git_remote||git(['config','--get','remote.origin.url']);
     const projectKey=t.project_id||repoSlug(gitRemote)||require('path').basename(process.cwd());
+    // Session duration: minutes from session_started_at to submitted_at. The ERP's
+    // example payload (docs/erp-contract.md:93) includes this; without it the ERP
+    // can't compute shift-length analytics without parsing notes.
+    let sessionDurationMinutes=0;
+    if(t.session_started_at){
+      const startMs=Date.parse(t.session_started_at);
+      const endMs=Date.parse(process.env.SUBMITTED_AT)||Date.now();
+      if(!Number.isNaN(startMs)&&endMs>startMs){
+        sessionDurationMinutes=Math.round((endMs-startMs)/60000);
+      }
+    }
     console.log(JSON.stringify({
       project:t.project||require('path').basename(process.cwd()),
       project_id:projectKey,team_id:t.team_id||'qualia-solutions',git_remote:gitRemote,
@@ -200,6 +222,7 @@ PAYLOAD=$(
       gap_cycles:(t.gap_cycles||{})[String(t.phase)]||0,build_count:t.build_count||0,
       deploy_count:t.deploy_count||0,deployed_url:t.deployed_url||'',
       session_started_at:t.session_started_at||'',last_pushed_at:t.last_pushed_at||'',
+      session_duration_minutes:sessionDurationMinutes,
       lifetime:t.lifetime||{},commits:commits,notes:notes,
       submitted_by:process.env.SUBMITTED_BY||'unknown',submitted_at:process.env.SUBMITTED_AT
     }));
@@ -214,11 +237,15 @@ if [ "$DRY_RUN" = "true" ]; then
   exit 0
 fi
 
-# Upload — 3 attempts with 1s/3s/9s backoff
+# Upload — 3 attempts with 1s/3s/9s backoff.
+# Idempotency-Key header carries a deterministic UUID per (client_report_id, submitted_at)
+# so the ERP can dedupe at the request level in addition to the UPSERT key on the body.
+# Documented in docs/erp-contract.md:42-49 with a 24h replay window.
 if [ "$ERP_ENABLED" = "true" ]; then
   for ATTEMPT in 1 2 3; do
     RESPONSE=$(curl -sS -X POST "$ERP_URL/api/v1/reports" \
       -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
+      -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
       -d "$PAYLOAD" --max-time 10 -w "\n__HTTP__%{http_code}" 2>&1)
     HTTP_CODE=$(echo "$RESPONSE" | grep -o "__HTTP__[0-9]*" | sed 's/__HTTP__//')
     BODY=$(echo "$RESPONSE" | sed 's/__HTTP__[0-9]*//g')
@@ -235,7 +262,42 @@ if [ "$ERP_ENABLED" = "true" ]; then
     fi
     [ $ATTEMPT -lt 3 ] && { SLEEP=$((1 * 3 ** (ATTEMPT - 1))); node ~/.claude/bin/qualia-ui.js warn "Attempt $ATTEMPT failed (HTTP ${HTTP_CODE:-timeout}), retrying in ${SLEEP}s..."; sleep $SLEEP; }
   done
-  [ "$ATTEMPT" = "3" ] && [ "$HTTP_CODE" != "200" ] && node ~/.claude/bin/qualia-ui.js warn "ERP upload failed after 3 attempts. $CLIENT_REPORT_ID is committed locally; will appear in ERP after retry."
+
+  # If all 3 in-process attempts failed, enqueue the report into the persistent
+  # retry queue (~/.claude/.erp-retry-queue.json). session-start.js drains it on
+  # the next Claude Code launch; `qualia-framework erp-flush` drains it on demand.
+  # This replaces the prior "will appear after retry" message which was a lie —
+  # no retry mechanism existed before v5.9.
+  if [ "$ATTEMPT" = "3" ] && [ "$HTTP_CODE" != "200" ]; then
+    LAST_ERR="HTTP ${HTTP_CODE:-timeout}"
+    if [ -n "$BODY" ]; then LAST_ERR="$LAST_ERR: $(echo "$BODY" | head -c 200)"; fi
+    PAYLOAD="$PAYLOAD" \
+    CLIENT_REPORT_ID="$CLIENT_REPORT_ID" \
+    IDEMPOTENCY_KEY="$IDEMPOTENCY_KEY" \
+    ERP_URL="$ERP_URL" \
+    LAST_ERR="$LAST_ERR" \
+    node -e "
+      try {
+        const {enqueue} = require(require('os').homedir() + '/.claude/bin/erp-retry.js');
+        enqueue({
+          client_report_id: process.env.CLIENT_REPORT_ID,
+          idempotency_key: process.env.IDEMPOTENCY_KEY,
+          url: process.env.ERP_URL + '/api/v1/reports',
+          payload: process.env.PAYLOAD,
+          last_error: process.env.LAST_ERR,
+        });
+        process.stdout.write('enqueued');
+      } catch (e) {
+        process.stderr.write('enqueue failed: ' + (e.message || e));
+        process.exit(1);
+      }
+    " 2>/dev/null && {
+      node ~/.claude/bin/qualia-ui.js warn "ERP upload failed after 3 attempts — $CLIENT_REPORT_ID enqueued for auto-retry on next session"
+      node ~/.claude/bin/qualia-ui.js info "Drain manually with: qualia-framework erp-flush"
+    } || {
+      node ~/.claude/bin/qualia-ui.js warn "ERP upload failed after 3 attempts AND queue enqueue failed. $CLIENT_REPORT_ID is committed locally — re-run /qualia-report later to retry."
+    }
+  fi
 fi
 
 [ "$ERP_ENABLED" != "true" ] && node ~/.claude/bin/qualia-ui.js info "ERP upload skipped (disabled). $CLIENT_REPORT_ID committed locally."