qualia-framework 4.4.0 → 5.1.0

package/skills/qualia-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-build
-description: "Execute the current phase — spawns builder subagents per task with wave-based parallelization. Fresh context per task."
+description: "Executes a planned phase by spawning fresh builder subagents per task with wave-based parallelization. Each task gets isolated context, commits atomically, and runs its own validation. Use when the user says 'build this phase', 'execute the plan', 'start building', 'run the build', 'qualia-build', or after /qualia-plan approves a phase plan."
 allowed-tools:
   - Bash
   - Read
@@ -15,12 +15,12 @@ allowed-tools:
 
 # /qualia-build — Build a Phase
 
-Execute the phase plan. Each task runs in a fresh subagent context. Independent tasks run in parallel.
+Execute phase plan. Each task = fresh subagent. Independent tasks run parallel.
 
 ## Usage
-`/qualia-build` — build the current planned phase
+`/qualia-build` — build current planned phase
 `/qualia-build {N}` — build specific phase
-`/qualia-build {N} --auto` — build + chain into `/qualia-verify {N} --auto` when done (no human gate between build and verify)
+`/qualia-build {N} --auto` — build + chain into `/qualia-verify {N} --auto` (no human gate)
 
 ## Process
 
@@ -30,11 +30,11 @@ Execute the phase plan. Each task runs in a fresh subagent context. Independent
 cat .planning/phase-{N}-plan.md
 ```
 
-Parse: tasks, waves, file references.
+Parse tasks, waves, file refs.
 
-### 1b. Create Recovery Reference
+### 1b. Recovery Reference
 
-Before executing any tasks, record current HEAD for diagnosis. This is a reference, not an automatic rollback instruction.
+Tag HEAD before executing. Reference only, no auto-rollback.
 
 ```bash
 git tag -f "pre-build-phase-{N}" HEAD 2>/dev/null
@@ -44,7 +44,7 @@ git tag -f "pre-build-phase-{N}" HEAD 2>/dev/null
 node ~/.claude/bin/qualia-ui.js info "Recovery point: pre-build-phase-{N}"
 ```
 
-If a wave fails, stop and inspect `git status` plus the failed task output. Do not run destructive rollback commands automatically. Preserve user work, then either fix forward or ask before reverting specific files.
+Wave fail → stop, inspect status + output. Preserve work; fix forward or ask before reverting.
 ```bash
 git status --short
 git diff --stat
@@ -62,33 +62,32 @@ node ~/.claude/bin/qualia-ui.js banner build {N} "{phase name}"
 node ~/.claude/bin/qualia-ui.js wave {W} {total_waves} {tasks_in_wave}
 ```
 
-**For each task in the wave — spawn ALL tasks in this wave as separate `Agent()` calls in the SAME response turn so the harness executes them concurrently. Do NOT await one task before spawning the next. Sequential spawning defeats wave parallelism.**
+**Per task in wave: spawn ALL as separate `Agent()` calls in SAME turn (concurrent). Do NOT await one before spawning next.**
 
 ```bash
 node ~/.claude/bin/qualia-ui.js task {task_num} "{task title}"
 ```
 
-**Pre-inline context before spawning** (saves 3-5 Read calls inside each builder subagent — GSD-style dispatch):
+**Pre-inline context** (saves 3-5 Read calls per builder):
 
-1. Parse the task's `Context:` field to get `@file` references
+1. Parse task `Context:` → `@file` refs
 2. Read PROJECT.md
-3. Read DESIGN.md if any file in the task is `.tsx`, `.jsx`, `.css`, `.scss`
-4. Read each `@file` referenced in Context
-5. Inline all of the above into the agent prompt under `<pre-loaded-context>` so the builder starts with full context
+3. Read DESIGN.md if task touches `.tsx`/`.jsx`/`.css`/`.scss`
+4. Read each `@file` from Context
+5. Inline all into prompt under `<pre-loaded-context>`
 
-Spawn a fresh builder subagent:
+Spawn builder:
 
 ```
 Agent(prompt="
-Read your role: @~/.claude/agents/builder.md
-Grounding + rubrics: @~/.claude/rules/grounding.md
+Role: @~/.claude/agents/builder.md
 
 <phase_context>
 # PROJECT.md
-{inlined contents of .planning/PROJECT.md}
+{inlined .planning/PROJECT.md}
 
 # DESIGN.md (if frontend task)
-{inlined contents of .planning/DESIGN.md}
+{inlined .planning/DESIGN.md}
 </phase_context>
 
 <task_context>
@@ -97,40 +96,35 @@ Grounding + rubrics: @~/.claude/rules/grounding.md
 </task_context>
 
 <wave_context>
-Other tasks in Wave {W} (running in parallel, do NOT touch their files):
-- Task {N}: "{title}" — files: {comma-separated Files list}
-- Task {M}: "{title}" — files: {comma-separated Files list}
-(If you are the only task in this wave, omit this block.)
+Parallel tasks Wave {W} (do NOT touch their files):
+- Task {N}: {title} -- files: {files}
+- Task {M}: {title} -- files: {files}
+(Omit if sole task in wave.)
 </wave_context>
 
 <task>
-{paste the single task block from the plan — title, wave, persona, files, depends-on, why, acceptance-criteria, action, validation, context}
+{task block from plan: title, wave, persona, files, depends-on, why, AC, action, validation, context}
 </task>
 
-All files in <phase_context> and <task_context> are already in your working memory — do NOT re-Read them. Only Read files NOT inlined (project code you need to modify).
-
-Execute the task. Commit when done. Return DONE/BLOCKED/PARTIAL per your Output Contract.
+Context tags already loaded. Only Read project code you modify.
+Execute. Commit. Return DONE/BLOCKED/PARTIAL.
 ", subagent_type="qualia-builder", description="Task {N}: {title}")
 ```
 
-**Why this ordering (cache-aware):** The role + grounding.md (session-stable) comes FIRST, phase_context (stable across every task in the phase) comes SECOND, task_context (varies per task) comes LAST. This preserves prefix-cache hits across tasks in the same wave — Anthropic prompt caching matches byte-identical prefixes, and a stable prefix of ~2-5k tokens hits at 92% rate (Claude Code benchmark). Sequential pre-inline without this split breaks cache on every task.
-
-**Why pre-inline at all:** without it, the builder's first actions are 3-5 Read tool calls to orient itself. With pre-inline, the builder starts already oriented and spends its context budget on the actual task.
+**Cache ordering:** Role + grounding FIRST, phase_context SECOND, task_context LAST. Stable prefix ~2-5k tokens → 92% cache hit. Pre-inline eliminates 3-5 Read calls per builder.
 
-**After each task completes:**
-- Verify the commit exists: `git log --oneline -1`
-- Show result:
+**After each task:**
+- Verify commit: `git log --oneline -1`
+- Show:
 ```bash
 node ~/.claude/bin/qualia-ui.js done {task_num} "{title}" {commit_hash}
 ```
 
-**After each wave completes:**
-- Move to next wave
-- Show wave summary
+**After each wave:** move to next, show summary.
 
 ### 3. Wave Completion
 
-After all waves complete:
+All waves done:
 
 ```bash
 node ~/.claude/bin/qualia-ui.js divider
@@ -141,30 +135,30 @@ node ~/.claude/bin/qualia-ui.js ok "Waves: {count}"
 
 ### 4. Handle Failures
 
-If a builder subagent returns a deviation or blocker:
-- **Minor deviation:** Log it, continue
-- **Major deviation:** Show to employee, ask how to proceed
-- **Blocker:** Show the blocker, suggest fix or escalation
+Builder returns deviation/blocker:
+- **Minor:** Log, continue
+- **Major:** Show to employee, ask how to proceed
+- **Blocker:** Show, suggest fix or escalation
 
 ### 5. Update State
 
 ```bash
 node ~/.claude/bin/state.js transition --to built --phase {N} --tasks-done {done} --tasks-total {total} --wave {wave}
 ```
-If state.js returns an error, show it to the employee and stop.
-Do NOT manually edit STATE.md or tracking.json — state.js handles both.
+Error → show, stop.
+Do NOT edit STATE.md or tracking.json manually; state.js handles both.
 
 ### 6. Route (auto-chain aware)
 
-**If invoked with `--auto`:** immediately invoke `/qualia-verify {N} --auto` inline. No pause, no permission ask. Verify will either chain into the next phase (if PASS), into gap closure (if FAIL and gap cycles remain), or halt with clear escalation (if gap limit reached).
+**`--auto`:** invoke `/qualia-verify {N} --auto` inline. No pause.
 
 ```bash
 node ~/.claude/bin/qualia-ui.js info "Auto mode — chaining into /qualia-verify {N}"
 ```
 
-Then invoke the `qualia-verify` skill inline with the same `--auto` flag.
+Then invoke `qualia-verify` inline with `--auto`.
 
-**Otherwise (default guided mode):** stop and show the next step:
+**Guided mode:** stop, show next step:
 
 ```bash
 node ~/.claude/bin/qualia-ui.js end "PHASE {N} BUILT" "/qualia-verify {N}"

package/skills/qualia-discuss/SKILL.md

@@ -1,121 +1,104 @@
 ---
 name: qualia-discuss
-description: "Capture phase decisions, trade-offs, and constraints BEFORE planning. Use for complex phases with regulatory, compliance, or architectural stakes. Creates .planning/phase-{N}-context.md that planner honors as locked input."
+description: "Aggressive alignment interview before planning a phase — asks ONE question at a time, proposes a recommended answer with each, walks every branch of the decision tree until resolved. Updates .planning/CONTEXT.md inline as terms crystallize and writes ADRs for hard-to-reverse decisions. Output: .planning/phase-{N}-context.md (locked input the planner honors). Use BEFORE /qualia-plan for high-stakes phases (regulatory, auth, payments, multi-tenant, architectural forks), or when the user says 'discuss', 'grill me', 'stress test this plan', 'wait let's think about this one', 'I'm not sure how to approach this'."
 allowed-tools:
   - Bash
   - Read
   - Write
   - Edit
+  - Grep
+  - Glob
   - AskUserQuestion
 ---
 
-# /qualia-discuss — Phase Context Capture
+# /qualia-discuss — Alignment Interview Before Planning
 
-Before a complex phase gets planned, surface the decisions and trade-offs that must inform planning. Output: `.planning/phase-{N}-context.md` that the planner reads as locked input.
-
-## When to Use
+Surface and lock the decisions, trade-offs, and constraints that must inform a phase plan. Output: `.planning/phase-{N}-context.md` (locked input). Side effects: `.planning/CONTEXT.md` gains new terms; `.planning/decisions/` may gain ADRs.
 
+## When to use
 - Regulated domains (legal, medical, financial) where wrong choices have legal cost
-- Phases with architectural forks (e.g., "auth via middleware or RLS?")
+- Phases with architectural forks ("auth via middleware or RLS?")
 - Phases with external dependencies you want to lock first
-- Anytime the user says "wait, let's think about this one"
+- User says "wait, let's think about this one"
 
-## Process
+## The four grilling rules
 
-### 1. Determine Phase
+1. **One question at a time.** Wait for the answer before asking the next. Never batch.
+2. **Propose your recommended answer first.** Format every question as `Question / Recommendation / Trade-offs`. The user accepts, edits, or rejects — way faster than open interview.
+3. **If the codebase can answer, explore instead of asking.** Don't make the user say what `git grep` could tell you.
+4. **Walk every branch.** When the user picks A over B, the next question is the one that A makes load-bearing. Resolve dependencies one-by-one until the tree is fully traversed.
 
-```bash
-node ~/.claude/bin/state.js check 2>/dev/null
-```
-
-If a phase number was passed as argument, use it. Otherwise use the current phase from STATE.md.
+## Process
 
-### 2. Load Context
+### 1. Load substrate
 
 ```bash
-cat .planning/PROJECT.md 2>/dev/null
-cat .planning/ROADMAP.md 2>/dev/null
+node ~/.claude/bin/state.js check 2>/dev/null
+cat .planning/PROJECT.md .planning/ROADMAP.md .planning/CONTEXT.md 2>/dev/null
+ls .planning/decisions/ 2>/dev/null
 cat .planning/research/SUMMARY.md 2>/dev/null
 ```
 
-Identify:
-- Phase goal from ROADMAP.md
-- Requirements covered by this phase
-- Research flags for this phase (from SUMMARY.md)
+If `.planning/CONTEXT.md` is missing, copy `~/.claude/qualia-templates/CONTEXT.md` to `.planning/CONTEXT.md` first.
+If `.planning/decisions/` is missing, create it. Copy `~/.claude/qualia-templates/decisions/ADR-template.md` next to it for reference.
 
-### 3. Open the Conversation
+### 2. Open the conversation
 
-Print the banner:
 ```bash
 node ~/.claude/bin/qualia-ui.js banner discuss {N} "{phase name from ROADMAP.md}"
 ```
 
-Ask inline (free text, not AskUserQuestion):
-
-**"We're about to plan {phase name}. The goal is: {goal from ROADMAP.md}. Before I hand this to the planner, what decisions, trade-offs, or constraints should be locked in?"**
+Then state the goal in one sentence and the open questions you found in priority order (highest-stakes / hardest-to-reverse first).
 
-Wait for their response.
+### 3. Grill, one question at a time
 
-### 4. Follow the Thread
+Format:
 
-Based on their answer, dig into specifics:
+```
+**Question {N}/{total}:** {the question}
 
-- If they mention a technology → "Why that one specifically?"
-- If they mention a constraint → "What happens if we don't honor this?"
-- If they mention a trade-off → "Which side do you want to land on, and why?"
-- If they mention a concern → "What's the worst case?"
+**My recommendation:** {your proposed answer + 1-sentence why}
 
-Use `AskUserQuestion` when there are clear interpretation forks. Free text otherwise.
+**Trade-offs:** {what gets harder if we go this way}
+```
 
-### 5. Capture Locked Decisions
+Wait for response. Then:
+- Update `.planning/CONTEXT.md` inline if a term crystallized (add definition + `Avoid:` line for rejected synonyms)
+- 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
 
-Build up a list of **locked decisions** — things the planner MUST honor. Each decision has:
-- The choice (what)
-- The rationale (why)
-- The source (who/when)
+### 4. Build the locked-decisions list
 
-Also capture:
-- **Discretion items** — things the planner can decide freely
-- **Deferred ideas** — good ideas that are NOT in this phase
-- **Risk flags** — things to watch during building
-- **Open questions** — things that still need resolution
+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).
 
-### 6. Decision Gate
+### 5. Decision gate
 
-When you have enough context:
+When the tree is fully traversed:
 
 - header: "Ready to lock?"
-- question: "Ready to lock these decisions and move to /qualia-plan {N}?"
-- options:
-  - "Lock it in" — Write phase-{N}-context.md and done
-  - "Keep exploring" — I have more to say
+- question: "Lock these decisions and move to /qualia-plan {N}?"
+- options: "Lock it in" / "Keep exploring"
 
 Loop until "Lock it in".
 
-### 7. Write phase-{N}-context.md
-
-Use the template at `~/.claude/qualia-templates/phase-context.md`. Fill every section with concrete content.
+### 6. Write phase-{N}-context.md
 
-```bash
-# Write the file to .planning/phase-{N}-context.md
-```
-
-### 8. Commit
-
-```bash
-git add .planning/phase-{N}-context.md
-git commit -m "docs(phase-{N}): capture phase context before planning"
-```
+Fill `~/.claude/qualia-templates/phase-context.md` with concrete content. Reference any ADRs written, any CONTEXT.md terms added.
 
-### 9. Route to Next
+### 7. Commit and route
 
 ```bash
+git add .planning/phase-{N}-context.md .planning/CONTEXT.md .planning/decisions/
+git commit -m "docs(phase-{N}): lock context, glossary terms, ADRs"
 node ~/.claude/bin/qualia-ui.js end "PHASE {N} CONTEXT LOCKED" "/qualia-plan {N}"
 ```
 
 ## Rules
 
-1. **One session, one phase.** Don't try to discuss phases 1 and 2 in the same invocation.
-2. **Locked decisions are NON-NEGOTIABLE.** The planner will honor them exactly. If you lock something you're not sure about, that's a mistake.
-3. **Don't redo research.** If the user asks a research question you don't know, suggest `/qualia-research {N}` instead.
-4. **Short context files are fine.** If the phase is simple, a 30-line context.md is better than a forced 200-line one.
+1. **One session, one phase.** Don't discuss phases 1 and 2 in the same invocation.
+2. **Locked decisions are NON-NEGOTIABLE.** The planner honors them exactly. Don't lock what you're unsure of — defer it instead.
+3. **Don't redo research.** If a question requires research you don't have, suggest `/qualia-research {N}` and pause.
+4. **CONTEXT.md is precious — keep entries terse.** One sentence each. It's loaded into every spawn; bloat costs tokens.
+5. **ADRs are scarce on purpose.** Three criteria all required. If any is missing, put it in CONTEXT.md or the phase-context.md instead.
+6. **Short context files are fine.** A 30-line context for a simple phase beats a forced 200-line one.

package/skills/qualia-handoff/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: qualia-handoff
+disable-model-invocation: true
 description: "Client delivery — produces the 4 mandatory Handoff deliverables (production URL, documentation, client assets archive, ERP finalization). Triggered at the end of the Handoff milestone."
 allowed-tools:
   - Bash

package/skills/qualia-issues/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: qualia-issues
+description: "Break a phase plan into independent vertical-slice GitHub issues with needs-triage label. Each issue is demoable end-to-end (schema → API → UI → tests). Dependency-ordered. Externalizes Qualia work to the open queue so other agents, sessions, or human contributors can pull from it. Use when user says 'create issues from this plan', 'externalize the phase', 'turn this into GitHub issues', 'qualia-issues', 'split into tickets', or after /qualia-plan when the work should be parallelizable. Hard dependency: requires tracker config — run /qualia-map first if .planning/agents/tracker.md is missing."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# /qualia-issues — Phase Plan → Independent Vertical-Slice GH Issues
+
+Externalizes a phase plan to the GitHub issue queue. Each issue is a thin slice that delivers a complete demoable behavior end-to-end. Other Qualia sessions, autonomous agents, or human contributors can then pull from the queue.
+
+## Why vertical slices
+
+ANTI-PATTERN: chop the plan horizontally (issue 1 = "all schema work", issue 2 = "all API work", issue 3 = "all UI"). This creates dependencies that block parallelism, and no single issue is demoable on its own.
+
+CORRECT: each issue traverses every layer (schema → API → UI → tests) for one narrow user-facing behavior. Many thin slices > few thick ones.
+
+## Hard dependencies (per Matt Pocock's ADR-0001)
+
+This skill cannot work meaningfully without:
+- `.planning/agents/tracker.md` — tells it where to file issues (GH, GL, local)
+- `.planning/agents/labels.md` — tells it the canonical-role-to-existing-label mapping
+- `gh` CLI authenticated (if tracker is GitHub)
+
+**If any are missing, halt and tell the user:** "Run `/qualia-map` first — it scans your repo and writes the adapter config so Qualia honors your existing tracker conventions."
+
+## Process
+
+### 1. Determine phase
+
+Phase number from `$ARGUMENTS` if provided, else current from `node ~/.claude/bin/state.js check`.
+
+### 2. Load substrate
+
+```bash
+cat .planning/agents/tracker.md
+cat .planning/agents/labels.md
+cat .planning/phase-{N}-plan.md
+cat .planning/CONTEXT.md 2>/dev/null
+cat .planning/PROJECT.md
+```
+
+If `phase-{N}-plan.md` is missing, halt: "No plan exists for phase {N}. Run `/qualia-plan {N}` first."
+
+### 3. Decompose into vertical slices
+
+Read the phase plan tasks. Group/split into slices where each slice:
+- Delivers ONE user-facing behavior end-to-end
+- Touches every relevant layer (schema, server, client, tests) needed for that behavior
+- Is independently demoable or verifiable
+- Has explicit blocking-dependencies on other slices (kept minimal)
+
+Use **CONTEXT.md domain language** in titles and descriptions. Don't say "user table" if the glossary says "AuthUser" or "Customer."
+
+### 4. Show proposed slices to user
+
+```
+Proposed slices for phase {N}:
+
+Slice 1: {title in domain language}
+  Behavior: {one sentence}
+  Touches: schema, server-action, page route, test
+  Blocks: none
+
+Slice 2: ...
+  Blocks: Slice 1 (needs the schema migration)
+```
+
+Use `AskUserQuestion`:
+- header: "Approve slices?"
+- question: "File these {N} issues?"
+- options: "File them" / "Re-decompose" / "Cancel"
+
+### 5. File issues in dependency order
+
+For each approved slice (in dependency order so blocking slices exist when blockees are filed):
+
+```bash
+# Write the body to a temp file FIRST — never heredoc-interpolate user content into shell.
+# Plan content (titles, behaviors, criteria) is user-controlled; shell metacharacters or a
+# rogue 'EOF' line in the plan would break out of the heredoc. --body-file eliminates the risk.
+BODY_FILE=$(mktemp -t qualia-issue.XXXXXX.md)
+cat > "$BODY_FILE" <<EOF_TEMPLATE
+## End-to-end behavior
+{one paragraph}
+
+## Acceptance criteria
+- [ ] {criterion 1 — observable behavior, not implementation detail}
+- [ ] {criterion 2}
+- [ ] tests pass for the slice
+
+## Blocks
+- {issue # of any blocking slice, or "none"}
+
+## Domain terms touched
+{terms from CONTEXT.md this slice involves}
+
+## Phase context
+Part of phase {N} ({phase name}). Plan: .planning/phase-{N}-plan.md.
+EOF_TEMPLATE
+
+gh issue create \
+  --title "{title in domain language}" \
+  --body-file "$BODY_FILE" \
+  --label "needs-triage,enhancement"
+
+rm -f "$BODY_FILE"
+```
+
+Capture the returned issue number for use in subsequent slices' "Blocks" fields.
+
+**Why temp file, not heredoc:** plan files (`.planning/phase-{N}-plan.md`) and CONTEXT.md are project repo content — anyone with commit access can write them. A crafted plan with shell metacharacters or a literal `EOF` line in the content could break out of an inline heredoc and execute arbitrary shell. `--body-file` reads the body as raw bytes, no shell expansion. The `EOF_TEMPLATE` token (vs the standard `EOF`) is also more resistant to accidental collisions.
+
+### 6. Write summary
+
+`.planning/phase-{N}-issues.md`:
+
+```markdown
+# Phase {N} — Issue Queue
+
+Filed {date}. Status: open queue.
+
+| # | Slice | Issue | Blocks |
+|---|---|---|---|
+| 1 | {title} | #123 | none |
+| 2 | {title} | #124 | #123 |
+```
+
+### 7. Commit and route
+
+```bash
+git add .planning/phase-{N}-issues.md
+git commit -m "docs(phase-{N}): externalize {N_slices} slices to GH issue queue"
+
+node ~/.claude/bin/qualia-ui.js end "QUEUE FILED" "/qualia-triage"
+```
+
+## Rules
+
+1. **Each issue is demoable on its own.** If a "completed" issue can't be shown as working behavior, the slicing was wrong.
+2. **CONTEXT.md language is mandatory.** Issue titles use domain terms, not implementation jargon.
+3. **No file paths or line numbers in issue bodies.** Issues describe behavior. Implementation details live in the phase plan.
+4. **Acceptance criteria are observable behaviors.** "Form validates email format" not "regex.test() returns true".
+5. **Dependencies kept minimal.** If slice A blocks slice B blocks slice C blocks slice D, the slicing collapsed to horizontal — re-decompose.
+6. **`needs-triage` is the default label.** `/qualia-triage` will route from there.