qualia-framework 4.5.0 → 5.3.0

package/skills/qualia-road/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: qualia-road
+description: "Show the Qualia workflow map in the terminal — Project → Journey → Milestones → Phases → Tasks. Lists every command, when to use it, and how phases chain. Use when user asks 'how does Qualia work', 'what's the workflow', 'show me the road', 'what command does X', 'how do projects flow', or is new to the framework. (For an interactive HTML reference instead, use /qualia-help.)"
+disable-model-invocation: true
+allowed-tools:
+  - Read
+---
+
+# The Qualia Road — Project Workflow Map
+
+**Hierarchy:** Project → Journey → Milestones (2–5, Handoff always last) → Phases (2–5 tasks each) → Tasks (one commit, one verification contract).
+
+```
+/qualia-new        → kickoff + parallel research + JOURNEY.md (all milestones upfront)
+                     add --auto to chain the whole road end-to-end
+     ↓
+For each milestone, for each phase:
+  /qualia-plan     → plan the phase (planner + plan-checker revision loop, fresh context)
+  /qualia-build    → build it (builder subagents per task, wave-based parallel)
+  /qualia-verify   → goal-backward check (verifier agent, fresh context)
+     ↓
+/qualia-milestone  → close milestone, archive artifacts, prep next (human gate)
+     ↓ (repeat for each milestone until Handoff)
+
+Final milestone = Handoff:
+  /qualia-polish   → final design pass (whole app)
+  (content + SEO)  → Phase 2
+  (final QA)       → Phase 3
+  /qualia-ship     → deploy to production (quality gates → deploy → verify)
+  /qualia-handoff  → 4 deliverables: credentials, doc, final update, report
+     ↓
+Done.
+```
+
+## Design as a thread (v4.5.0+)
+Every road agent loads `PRODUCT.md + DESIGN.md + design-laws.md` substrate. Builders run `slop-detect` on every frontend commit. Verifiers score 8 design dimensions per phase.
+
+## /qualia-polish is scope-adaptive
+```
+/qualia-polish src/components/Button.tsx     ~30s component touch-up
+/qualia-polish app/dashboard                 ~3m  section pass
+/qualia-polish                               ~12m whole app, fan-out
+/qualia-polish --redesign                    ~30m ground-up redesign
+/qualia-polish --critique                    read-only scored audit
+/qualia-polish --quick                       ~1m  gates only
+```
+
+## /qualia-polish-loop -- autonomous visual QA (v5.1+)
+```
+/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
+```
+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.
+
+## Alignment substrate (v5.0+)
+Before high-stakes phases, run alignment skills against `.planning/CONTEXT.md` (domain glossary) and `.planning/decisions/` (ADRs):
+
+```
+/qualia-discuss            → relentless one-question interview, updates CONTEXT.md inline
+/qualia-zoom               → map an unfamiliar code area using glossary terms
+/qualia-optimize --deepen  → find shallow modules, propose Ousterhout-style refactors
+/qualia-test --tdd         → vertical-slice red→green→refactor for one feature
+/qualia-issues             → break a phase plan into independent GH issues
+/qualia-triage             → label + route open issues (ready-for-agent vs human)
+/qualia-map                → adapt Qualia to an existing brownfield repo's conventions (5th onboarding agent)
+```
+
+## Auxiliary commands
+```
+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)
+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)
+Unsure plan? → /qualia-discuss (capture decisions before planning)
+```
+
+## Human gates
+Journey approval after `/qualia-new`, then one at each milestone boundary via `/qualia-milestone`. `--auto` runs everything between gates automatically.
+
+## Context isolation
+Every task runs in a fresh subagent context. Task 50 gets the same quality as Task 1.
+- Planner gets: PROJECT.md + CONTEXT.md + phase requirements
+- Builder gets: single task from plan + PROJECT.md + CONTEXT.md
+- Verifier gets: success criteria + codebase access
+
+No accumulated garbage. No context rot.
+
+## Quality gates (always active via hooks)
+- **Frontend guard** — Read `.planning/DESIGN.md` before any frontend changes
+- **Deploy guard** — tsc + lint + build + tests must pass before deploy
+- **Migration guard** — Catches dangerous SQL (DROP without IF EXISTS, DELETE without WHERE, CREATE TABLE without RLS)
+- **Slop-detect** — Em-dash and AI-tells check on every UI commit
+- **Intent verification** — Confirm before modifying 3+ files (OWNER role: just do it)
+
+## Tracking
+`.planning/tracking.json` is updated on every push. The ERP reads it via git.
+Never edit tracking.json manually — hooks update it from STATE.md.
+
+## Compaction — ALWAYS preserve
+Project path/name, branch, current phase, modified files, decisions, test results, in-progress work, errors, tracking.json state.

package/skills/qualia-ship/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: qualia-ship
+disable-model-invocation: true
 description: "Deploy to production — state-guard, full security scan, quality gates, commit, push, deploy, verify. Trigger on 'deploy', 'ship it', 'go live', 'push to prod', 'launch', 'release to production'."
 allowed-tools:
   - Bash

package/skills/qualia-task/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-task
-description: "Build a single task — more structured than /qualia-quick, lighter than /qualia-build. Spawns a fresh builder agent for one focused task."
+description: "Builds a single focused task in a fresh builder context with atomic commit and validation. More structured than /qualia-quick, lighter than /qualia-build (no phase plan needed). Use when the user says 'build this one thing', 'add a component', 'implement this feature', 'qualia-task', or for any 1-5 file change outside a full phase."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-test
-description: "Generate or run tests for client projects. Trigger on 'write tests', 'add tests', 'test this', 'run tests', 'test coverage', 'need tests for'."
+description: "Generate tests for existing code, run tests, OR drive a feature test-first via --tdd vertical-slice loop (red→green→refactor, one test→one impl→repeat). Trigger on 'write tests', 'add tests', 'test this', 'run tests', 'test coverage', 'need tests for', 'tdd this', 'test-driven', 'red green refactor'."
 allowed-tools:
   - Bash
   - Read
@@ -20,6 +20,7 @@ Generate tests for client project code. Detect framework, classify targets, writ
 - `/qualia-test {file}` — Generate tests for a specific file
 - `/qualia-test --run` — Run existing tests and report
 - `/qualia-test --coverage` — Run with coverage report
+- `/qualia-test --tdd "{feature description}"` — Drive the feature test-first via vertical-slice loop
 
 ## Process
 
@@ -132,7 +133,54 @@ git add {test files}
 git commit -m "test: add tests for {files}"
 ```
 
-## Rules
+## --tdd mode (vertical-slice red→green→refactor)
+
+When `--tdd "{feature}"` is passed, run this loop instead of the after-the-fact generator. Stops the user from accumulating untested code.
+
+### The non-negotiable rules
+
+1. **Vertical slices only.** ANTI-PATTERN: write all tests first, then all implementation. Correct: one test → one minimal implementation → repeat.
+
+   ```
+   WRONG (horizontal):  RED test1-5 → GREEN impl1-5
+   RIGHT (vertical):    RED→GREEN test1→impl1, then test2→impl2, ...
+   ```
+
+2. **Test through the public interface only.** If the test reaches into private state, the test will die on the first refactor. Test what callers see.
+3. **Only enough code to pass the current test.** No speculative features. No "while we're here." Resist scope creep — the next test will demand it if it's needed.
+4. **Never refactor while red.** Green first. THEN refactor (with tests still green as the safety net).
+5. **Each cycle is a commit.** `test: {behavior}` for the red, `feat: {minimal impl}` for the green. Tiny commits = revertable units.
+
+### Loop
+
+#### Phase 1 — Plan the slices
+1. Read `.planning/CONTEXT.md` if it exists — use domain glossary terms in test names
+2. Decompose `"{feature}"` into the smallest vertical slices that each deliver an observable behavior
+3. Show the slice list to the user. Get approval before writing the first test.
+
+#### Phase 2 — Tracer bullet (slice 1)
+1. **RED**: write ONE test against the public interface that the feature would expose. Run it — it must fail (no implementation yet)
+2. **GREEN**: write the MINIMUM code to make it pass. Run all tests — green
+3. **COMMIT**: `git commit -m "test+feat({slug}): {slice 1 behavior}"`
+
+#### Phase 3 — Incremental loop
+For each remaining slice:
+1. **RED**: one test, one behavior, fails
+2. **GREEN**: minimal code, all tests pass
+3. **REFACTOR** (only if tests still green): extract duplication, apply SOLID where the code asks for it, run tests after each step
+4. **COMMIT**
+
+#### Phase 4 — Per-cycle checklist (run on every slice)
+- [ ] Test describes a behavior, not an implementation detail
+- [ ] Test uses only the public interface
+- [ ] Test would survive a reasonable internal refactor
+- [ ] Implementation is minimal — no speculative features
+- [ ] Test name reads as a sentence
+
+#### Phase 5 — Hand off
+When all slices are green, suggest: `/qualia-verify {N}` (if part of a phase) or `/qualia-optimize --deepen` (if the implementation accumulated shallow modules during the loop).
+
+## Rules (apply to all modes)
 
 1. **Test behavior, not implementation.** Don't test internal state — test what the user/caller sees.
 2. **No snapshot tests.** They're brittle and meaningless.

package/skills/qualia-triage/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: qualia-triage
+description: "State machine over open GH issues — labels each as needs-triage, needs-info, ready-for-agent, ready-for-human, or wontfix. Optionally routes ready-for-agent issues into an autonomous /qualia-build run. Pairs with /qualia-issues to enable the autonomous Ralph-Wiggum loop where agents pull work from the queue without human-in-loop. Use when user says 'triage', 'qualia-triage', 'route the queue', 'pull next from backlog', 'what's ready for the agent'. Hard dependency: requires .planning/agents/labels.md — run /qualia-map first if missing."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# /qualia-triage — Issue Queue State Machine
+
+Walks the open issue queue, applies state labels, optionally routes `ready-for-agent` issues into autonomous build runs.
+
+## The state machine
+
+Every issue carries exactly one **category** label and exactly one **state** label.
+
+**Category labels** (mutually exclusive):
+- `bug` — something is broken
+- `enhancement` — new feature or improvement
+
+**State labels** (exactly one per issue):
+- `needs-triage` — initial state, awaiting maintainer evaluation
+- `needs-info` — clarification needed from reporter
+- `ready-for-agent` — fully specified, autonomous build can pull this
+- `ready-for-human` — requires human implementation (judgment, sensitive area, scope unclear)
+- `wontfix` — rejected
+
+**Flow:**
+
+```
+unlabeled → needs-triage → ┬→ needs-info → (response) → needs-triage
+                           ├→ ready-for-agent → (autonomous build) → closed
+                           ├→ ready-for-human → (human picks up) → closed
+                           └→ wontfix → closed
+```
+
+## Hard dependencies
+
+This skill cannot work meaningfully without:
+- `.planning/agents/labels.md` — canonical-role-to-existing-label mapping
+- `.planning/agents/tracker.md` — tells it where the queue lives
+- `gh` CLI authenticated (if tracker is GitHub)
+
+If missing, halt: "Run `/qualia-map` first to scan your repo and write the adapter config."
+
+## Process
+
+### 1. Load substrate
+
+```bash
+cat .planning/agents/labels.md
+cat .planning/agents/tracker.md
+cat .planning/CONTEXT.md 2>/dev/null
+```
+
+If labels are missing in the tracker, create them per the canonical mapping.
+
+### 2. List the queue
+
+```bash
+gh issue list --state open --limit 50 --json number,title,body,labels --jq '.'
+```
+
+### 3. Classify each unlabeled / needs-triage issue
+
+For each issue:
+
+**Read the body. Then assign one state per these criteria:**
+
+| State | Criteria |
+|---|---|
+| `ready-for-agent` | Acceptance criteria are explicit + observable. Touches files Qualia knows. No business-judgment calls. No security-sensitive areas without explicit ADR backing. |
+| `ready-for-human` | Requires judgment Qualia shouldn't make. Touches security/auth/payments without ADR. Scope is fuzzy. Risk is high. |
+| `needs-info` | Reporter left out reproduction steps, expected behavior, or scope is too vague to act on. |
+| `wontfix` | Out of project scope per PROJECT.md. Already implemented. Duplicate of #N. Conflicts with locked ADR. |
+
+For each issue, also assign category (`bug` if behavior is broken vs spec, `enhancement` otherwise).
+
+### 4. Apply labels
+
+```bash
+gh issue edit {N} --add-label "{state},{category}" --remove-label "needs-triage"
+```
+
+For `needs-info`, also post a comment with the specific questions. Use `--body-file` (never heredoc-interpolate) — issue text is user-controlled and could contain shell metacharacters or a rogue `EOF`:
+
+```bash
+COMMENT_FILE=$(mktemp -t qualia-triage.XXXXXX.md)
+cat > "$COMMENT_FILE" <<EOF_TEMPLATE
+Need a few more details to triage this:
+
+1. {specific question 1}
+2. {specific question 2}
+
+Once these are answered I'll re-triage.
+EOF_TEMPLATE
+
+gh issue comment {N} --body-file "$COMMENT_FILE"
+rm -f "$COMMENT_FILE"
+```
+
+### 5. Show the queue snapshot
+
+```
+Triaged {N} issues:
+
+ready-for-agent:  {count} ─ #123, #124, #126
+ready-for-human:  {count} ─ #125, #127
+needs-info:       {count} ─ #128
+wontfix:          {count} ─ #129
+```
+
+### 6. Optional autonomous loop
+
+```
+{N} issues ready-for-agent. Pull the next one into autonomous build?
+```
+
+`AskUserQuestion`:
+- header: "Auto-pull?"
+- question: "Pull #{first ready-for-agent} into autonomous /qualia-build?"
+- options:
+  - "Pull it" — feed the issue into a fresh /qualia-build run, then re-triage when done
+  - "Pause" — stop here, user picks up manually
+
+If "Pull it":
+1. Read the issue body fully
+2. Spawn `/qualia-build` with the issue body as task input
+3. After build completes and verifies green, comment the closing PR/commit on the issue and `gh issue close {N}`
+4. Loop back to step 6 (next ready-for-agent issue)
+
+The loop continues until the queue empties or the user pauses.
+
+### 7. Final report
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "QUEUE TRIAGED" "/qualia or /qualia-build {next}"
+```
+
+## Rules
+
+1. **One category, one state — always.** No issue without both labels (after triage). No issue with two of either.
+2. **`ready-for-agent` is conservative.** When in doubt, `ready-for-human`. Wrong agent-pull is more expensive than a human picking it up.
+3. **`needs-info` posts a comment.** Don't just label and walk away — the reporter must know what's blocking.
+4. **`wontfix` cites a reason.** Body or comment must say WHY (out of scope per PROJECT.md, conflicts with ADR-NNNN, duplicate of #N).
+5. **Autonomous loop is opt-in per session.** Don't auto-loop without the user pressing "Pull it" each cycle (until they explicitly ask for a continuous run).
+6. **Re-triage on response.** When `needs-info` issues get a reply, they return to `needs-triage` for re-evaluation.

package/skills/qualia-verify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-verify
-description: "Goal-backward verification — checks if the phase ACTUALLY works, not just if tasks completed. Spawns verifier agent."
+description: "Goal-backward verification of a built phase. Spawns a fresh verifier agent that greps the actual codebase against acceptance criteria, scores the design rubric, and optionally runs an adversarial second pass. Use when the user says 'verify this phase', 'check if it works', 'run verification', 'did the build pass', 'qualia-verify', or after /qualia-build completes."
 allowed-tools:
   - Bash
   - Read
@@ -13,13 +13,13 @@ allowed-tools:
 
 # /qualia-verify — Verify a Phase
 
-Spawn a verifier agent to check if the phase goal was achieved. Does NOT trust build summaries — greps the actual codebase.
+Spawn verifier to check phase goal. Does NOT trust build summaries; greps codebase.
 
 ## Usage
-`/qualia-verify` — verify the current built phase
+`/qualia-verify` — verify current built phase
 `/qualia-verify {N}` — verify specific phase
-`/qualia-verify {N} --auto` — verify + auto-chain: PASS → next phase (or milestone close); FAIL → gap closure; gap limit → halt with escalation
-`/qualia-verify {N} --adversarial` — run a SECOND verifier in fresh context with an adversarial prompt ("find what's wrong, not what's right"). Union the findings. Recommended for high-stakes phases (Handoff milestone, payment/auth/migration code) where a biased single-pass review would silently approve a bad change. v4.3.0+.
+`/qualia-verify {N} --auto` — verify + auto-chain: PASS → next phase/milestone; FAIL → gap closure; gap limit → halt
+`/qualia-verify {N} --adversarial` — second verifier in fresh context with adversarial prompt. Union findings. Recommended for high-stakes phases (Handoff, payment/auth/migration). v4.3.0+.
 
 ## Process
 
@@ -41,25 +41,19 @@ node ~/.claude/bin/qualia-ui.js spawn verifier "Goal-backward check..."
 
 ```
 Agent(prompt="
-Read your role: @~/.claude/agents/verifier.md
-Grounding + rubrics: @~/.claude/rules/grounding.md
+Role: @~/.claude/agents/verifier.md
 
-Project conventions (MUST consult before scoring Quality):
-@.planning/PROJECT.md
+Project: @.planning/PROJECT.md
+Plan + AC + validation: @.planning/phase-{N}-plan.md
+{Re-verify → previous gaps: @.planning/phase-{N}-verification.md}
 
-Phase plan with success criteria AND verification contracts:
-@.planning/phase-{N}-plan.md
-
-{If re-verification: Previous verification with gaps:}
-{@.planning/phase-{N}-verification.md}
-
-Verify this phase. Apply the Grounding Protocol — every finding needs file:line evidence. Use the Severity Rubric for all severity labels. Write report to .planning/phase-{N}-verification.md
+Verify phase. Every finding needs file:line evidence. Severity Rubric for all labels. Output: .planning/phase-{N}-verification.md
 ", subagent_type="qualia-verifier", description="Verify phase {N}")
 ```
 
 ### 2b. Browser QA (if phase touched frontend)
 
-If the phase plan's Files section includes any `.tsx`, `.jsx`, `.css`, `.scss`, or `app/`/`pages/`/`components/` paths, ALSO spawn the browser QA agent in parallel:
+If plan Files include `.tsx`/`.jsx`/`.css`/`.scss` or `app/`/`pages/`/`components/` paths, spawn browser QA parallel:
 
 ```bash
 # Detect frontend touch
@@ -70,26 +64,20 @@ If frontend:
 
 ```
 Agent(prompt="
-Read your role: @~/.claude/agents/qa-browser.md
+Role: @~/.claude/agents/qa-browser.md
 
-Phase plan: @.planning/phase-{N}-plan.md
-Existing verification: @.planning/phase-{N}-verification.md
+Plan: @.planning/phase-{N}-plan.md
+Verification: @.planning/phase-{N}-verification.md
 
-Drive the running dev server and test the routes this phase touched. Append a '## Browser QA' section to the verification file.
+Drive dev server, test routes phase touched. Append '## Browser QA' to verification file.
 ", subagent_type="qualia-qa-browser", description="Browser QA phase {N}")
 ```
 
-Wait for both the main verifier and the QA browser agent before moving to step 3. If Playwright MCP is unavailable, the QA browser agent returns BLOCKED — that's not a phase failure, just a note in the report.
+Wait for both verifier + QA before step 3. Playwright MCP unavailable → QA returns BLOCKED (note, not phase failure).
 
 ### 2c. Adversarial Second Opinion (--adversarial flag, optional)
 
-When `--adversarial` is in the args, OR when the current milestone is
-`Handoff` OR the phase plan touches files matching `auth|payment|migration|rls|service_role`, spawn a SECOND verifier in fresh context with an
-adversarial prompt. This is the "kid-grading-their-own-homework"
-mitigation — a single verifier instance trained on the same rubric the
-planner+builder optimized against gets ~70% fewer real findings than a
-fresh-context adversarial pass (Cole Medin, NotebookLM 2026-04-25, citing
-PR-acceptance studies).
+`--adversarial` in args, OR milestone is `Handoff`, OR plan touches `auth|payment|migration|rls|service_role` → spawn SECOND verifier in fresh context. Mitigates self-grading bias (~70% fewer findings without adversarial pass).
 
 ```bash
 node ~/.claude/bin/qualia-ui.js spawn verifier "Adversarial pass — find what's wrong"
@@ -97,66 +85,48 @@ node ~/.claude/bin/qualia-ui.js spawn verifier "Adversarial pass — find what's
 
 ```
 Agent(prompt="
-Read your role: @~/.claude/agents/verifier.md
-Grounding + rubrics: @~/.claude/rules/grounding.md
-
-You are an ADVERSARIAL reviewer. Your job is to find what's WRONG with
-this phase, not to confirm it works. Assume the previous verifier missed
-something. Use the same Severity Rubric, the same evidence-citation
-requirement, but bias your search toward edge cases the cooperative
-verifier would skip:
-  • What untested error path exists?
-  • What input would crash this?
-  • What concurrent access pattern is unhandled?
-  • What downstream consumer breaks if this contract changes?
-  • Where is a security assumption (auth, RLS, secrets) implicit
-    instead of enforced?
-
-Project conventions: @.planning/PROJECT.md
-Phase plan: @.planning/phase-{N}-plan.md
-Cooperative verifier's report (do NOT re-find what they found, find
-what they MISSED): @.planning/phase-{N}-verification.md
-
-Append a '## Adversarial Findings' section to the verification file.
-Empty section is fine if you genuinely found nothing — better that than
-inventing findings to look productive.
+Role: @~/.claude/agents/verifier.md
+
+ADVERSARIAL reviewer. Find what's WRONG. Assume cooperative verifier missed something. Same Severity Rubric + evidence-citation req. Bias toward edge cases:
+  - Untested error paths?
+  - Crash-inducing input?
+  - Unhandled concurrent access?
+  - Downstream breaks if contract changes?
+  - Security assumption (auth, RLS, secrets) implicit not enforced?
+
+Project: @.planning/PROJECT.md
+Plan: @.planning/phase-{N}-plan.md
+Cooperative report (find what they MISSED): @.planning/phase-{N}-verification.md
+
+Append '## Adversarial Findings' to verification file. Empty section fine if nothing found.
 ", subagent_type="qualia-verifier", description="Adversarial verify phase {N}")
 ```
 
-Findings from the adversarial pass merge into the main verification
-report. The combined PASS/FAIL is the union: if either pass found a
-CRITICAL or HIGH gap, the phase is FAIL.
+Findings merge into main report. Union PASS/FAIL: either pass found CRITICAL/HIGH → phase FAIL.
 
 ### 3. Present Results
 
-Read the verification report. Present:
+Read verification report. Present:
 
-**If PASS:**
+**PASS:**
 ```bash
 node ~/.claude/bin/qualia-ui.js ok "All {count} criteria passed"
 node ~/.claude/bin/qualia-ui.js end "PHASE {N} VERIFIED" "/qualia-plan {N+1}"
 ```
-(If phase == total phases, use `/qualia-polish` as the next command.)
+(Last phase → `/qualia-polish` as next command.)
 
-**If FAIL:**
+**FAIL:**
 ```bash
 node ~/.claude/bin/qualia-ui.js ok "Passed: {pass_count}"
 node ~/.claude/bin/qualia-ui.js fail "Failed: {fail_count}"
 ```
 
-Then for each gap:
+Per gap:
 ```bash
 node ~/.claude/bin/qualia-ui.js fail "{gap description}"
 ```
 
-**Self-healing layer (v4.3.0+):** before re-planning the gaps, run a
-postmortem so the framework itself learns from the miss. This is Cole
-Medin's pillar 5: don't just fix the bug, fix the AI-layer file that
-should have caught it. The postmortem writes a report to
-`.planning/phase-{N}-postmortem.md` for review — it does NOT auto-apply
-deltas to agents/rules unless the user runs `/qualia-postmortem --apply`
-explicitly. Without this loop, the same class of bug ships in PR-3, PR-7,
-PR-11 of the next project.
+**Self-healing (v4.3.0+):** before re-planning gaps, run postmortem so framework learns from miss. Writes `.planning/phase-{N}-postmortem.md`. Does NOT auto-apply deltas unless user runs `/qualia-postmortem --apply`.
 
 ```
 /qualia-postmortem --phase {N}
@@ -172,68 +142,57 @@ node ~/.claude/bin/qualia-ui.js end "PHASE {N} GAPS FOUND" "/qualia-plan {N} --g
 ```bash
 node ~/.claude/bin/state.js transition --to verified --phase {N} --verification {pass|fail}
 ```
-If PASS and more phases in this milestone: state.js auto-advances to the next phase.
-If FAIL and gap_cycles >= limit: state.js returns GAP_CYCLE_LIMIT — escalate.
-If FAIL and gap_cycles < limit: proceed to `/qualia-plan {N} --gaps`.
-Do NOT manually edit STATE.md or tracking.json — state.js handles both.
+PASS + more phases → state.js auto-advances.
+FAIL + gap_cycles >= limit → GAP_CYCLE_LIMIT, escalate.
+FAIL + gap_cycles < limit → `/qualia-plan {N} --gaps`.
+Do NOT edit STATE.md or tracking.json manually; state.js handles both.
 
-After state transition, capture the new state for auto-chain routing:
+Capture new state for auto-chain routing:
 
 ```bash
 NEW_STATE=$(node ~/.claude/bin/state.js check)
-# Parse: .phase (new current phase), .total_phases, .status, .verification
-# Also read .planning/JOURNEY.md to know if this was the last phase of a milestone
+# Parse: .phase, .total_phases, .status, .verification
+# Read .planning/JOURNEY.md to check if last phase of milestone
 ```
 
 ### 4b. Route (auto-chain aware)
 
-**In `--auto` mode**, the router decides the next step based on verify result + journey position:
+**`--auto` mode** router decides next step based on result + journey position:
 
 | Result | Journey position | Action |
 |---|---|---|
-| PASS | More phases remain in current milestone | Inline invoke `/qualia-plan {N+1} --auto` |
-| PASS | Last phase of current milestone (not Handoff) | Inline invoke `/qualia-milestone --auto` |
-| PASS | Last phase of Handoff milestone | Inline invoke `/qualia-ship`, then `/qualia-handoff`, then `/qualia-report` |
-| FAIL | gap_cycles < limit | Inline invoke `/qualia-plan {N} --gaps --auto` |
-| FAIL | gap_cycles >= limit | **HALT** — show escalation message, require human intervention |
+| PASS | More phases in milestone | `/qualia-plan {N+1} --auto` |
+| PASS | Last phase of milestone (not Handoff) | `/qualia-milestone --auto` |
+| PASS | Last phase of Handoff | `/qualia-ship` → `/qualia-handoff` → `/qualia-report` |
+| FAIL | gap_cycles < limit | `/qualia-plan {N} --gaps --auto` |
+| FAIL | gap_cycles >= limit | **HALT** — escalation, require human |
 
-Detect "last phase of current milestone":
-```bash
-# tracking.json.milestone gives current milestone number
-# .planning/JOURNEY.md describes phases per milestone
-# If the just-verified phase's number == total phases of current milestone → last phase
-```
+Last phase: verified phase == total from JOURNEY.md.
+Handoff: milestone name == "Handoff" AND last phase.
 
-Detect "last phase of Handoff milestone":
-```bash
-# If the current milestone's name in JOURNEY.md is "Handoff" AND this was its last phase
-```
-
-**Halt case (gap cycle limit)** — stop auto-chain and show:
+**Halt (gap cycle limit):**
 
 ```bash
-node ~/.claude/bin/qualia-ui.js fail "Phase {N} has failed verification {cycles} times — gap limit reached"
+node ~/.claude/bin/qualia-ui.js fail "Phase {N} failed verification {cycles} times -- gap limit reached"
 node ~/.claude/bin/qualia-ui.js warn "Human intervention required. Options:"
-echo "  1. Re-plan this phase from scratch: /qualia-plan {N}"
-echo "  2. Adjust the roadmap — phase scope may be wrong"
-echo "  3. Escalate to Fawzi (for EMPLOYEE role)"
+echo "  1. Re-plan from scratch: /qualia-plan {N}"
+echo "  2. Adjust roadmap (scope wrong)"
+echo "  3. Escalate to Fawzi (EMPLOYEE role)"
 ```
 
-**Default (guided mode)** behavior is unchanged — show the next command and stop:
+**Guided mode:**
 
 ```bash
-# PASS
+# PASS (or "/qualia-milestone" if last phase, "/qualia-polish" if overall last)
 node ~/.claude/bin/qualia-ui.js end "PHASE {N} VERIFIED" "/qualia-plan {N+1}"
-# (or "/qualia-milestone" if last phase of milestone, "/qualia-polish" if overall last phase)
-
 # FAIL
 node ~/.claude/bin/qualia-ui.js end "PHASE {N} GAPS FOUND" "/qualia-plan {N} --gaps"
 ```
 
 ### 5. Passive Knowledge Capture (on FAIL)
 
-When verification fails, after showing the gaps, ask the user:
+On FAIL, after showing gaps:
 
-> *"Was any of this a recurring issue worth saving to common-fixes.md? (yes / no / which ones)"*
+> *"Any recurring issue worth saving to common-fixes.md? (yes / no / which ones)"*
 
-If yes, for each flagged gap spawn a brief `/qualia-learn` flow with type=`fix` — the gap title and fix direction from the verification report become the entry. Do NOT save every failure automatically — only the ones the user flags. The point is to build a real knowledge base, not a log of every mistake.
+Yes → spawn `/qualia-learn` with type=`fix` per flagged gap. Do NOT auto-save every failure; only user-flagged.