qualia-framework 3.6.0 → 4.0.3

package/guide.md

@@ -1,63 +1,126 @@
-# Qualia Developer Guide
+# Qualia Developer Guide (v4)
 
 > Follow the road. Type the commands. The framework handles the rest.
+> v4 adds a `--auto` flag that chains the whole road end-to-end with only two human checkpoints per project.
 
 ## The Road
 
 ```
-/qualia-new          ← Set up project (once)
+/qualia-new                ← Set up project (once). Produces JOURNEY.md — all milestones to handoff.
      ↓
-For each phase:
-  /qualia-plan       ← Plan it (planner agent)
-  /qualia-build      ← Build it (builder subagents)
-  /qualia-verify     ← Verify it works (verifier agent)
+For each phase of the current milestone:
+  /qualia-plan             ← Plan it (planner + plan-checker, story-file format)
+  /qualia-build            ← Build it (builder subagents with pre-inlined context)
+  /qualia-verify           ← Check it actually works (goal-backward + per-task AC)
      ↓
-/qualia-polish       ← Design pass
-/qualia-ship         ← Deploy to production
-/qualia-handoff      ← Deliver to client
+/qualia-milestone          ← Close milestone, open next from JOURNEY.md
+     ↓
+...repeat per milestone until the Handoff milestone...
+     ↓
+/qualia-polish             ← Design pass (part of Handoff milestone)
+/qualia-ship               ← Deploy to production
+/qualia-handoff            ← Enforce the 4 handoff deliverables
      ↓
 Done.
 ```
 
-## The 10 Commands
+## Auto Mode (v4)
+
+Append `--auto` to `/qualia-new` and the framework chains every step:
+
+```
+/qualia-new --auto
+  → research runs → JOURNEY.md written → approve the whole journey ONCE
+  → auto: plan 1 → build 1 → verify 1 → plan 2 → build 2 → verify 2 → ...
+  → pause at each milestone boundary: "Continue to M{N+1}?"
+  → resume: plan 1 → build 1 → ... of new milestone
+  → eventually reaches Handoff milestone's last phase → ship → handoff → report → done
+```
+
+**Human gates in auto mode (total: 2 per project):**
+1. Journey approval after `/qualia-new` research
+2. Each milestone boundary
+
+**Plus one halt case:** if a phase fails verification beyond the gap-cycle limit (default 2), the chain stops and asks for human intervention.
+
+## The Road Commands
 
 | When | Command | What it does |
 |------|---------|-------------|
-| Starting | `/qualia-new` | Set up project from scratch |
+| Starting | `/qualia-new` | Set up project with full journey (all milestones → Handoff) |
+| Starting (auto) | `/qualia-new --auto` | Same + chain through building automatically |
 | Building | `/qualia-plan` | Plan the current phase |
 | | `/qualia-build` | Build it (parallel tasks) |
 | | `/qualia-verify` | Check it actually works |
+| Milestone | `/qualia-milestone` | Close current, open next from JOURNEY.md |
 | Quick fix | `/qualia-quick` | Skip planning, just do it |
 | Finishing | `/qualia-polish` | Design and UX pass |
 | | `/qualia-ship` | Deploy to production |
-| | `/qualia-handoff` | Deliver to client |
-| Reporting | `/qualia-report` | Log what you did (mandatory) |
-| **Lost?** | **`/qualia`** | **Tells you the exact next command** |
+| | `/qualia-handoff` | Deliver to client (4 mandatory deliverables) |
+| Reporting | `/qualia-report` | Log what you did (mandatory before clock-out) |
+| Lost? | `/qualia` | Mechanical next-command router |
+| Confused? | `/qualia-idk` | Diagnostic — scans planning + code, explains what's going on |
+
+## Full Journey Hierarchy (v4)
+
+```
+Project
+└─ Journey           (the whole arc — mapped upfront by /qualia-new, lives in .planning/JOURNEY.md)
+   └─ Milestone      (a release — 2-5 total, Handoff is always last)
+      └─ Phase       (a feature-sized deliverable, 2-5 tasks)
+         └─ Task     (atomic unit, one commit, one verification contract)
+```
+
+Hard rules (enforced by `state.js` and the roadmapper):
+- **Milestone count: 2 to 5.** Final milestone is always literally named "Handoff".
+- **≥ 2 phases per non-Handoff milestone** (single-phase "milestones" are phases, not milestones).
+- **Milestone numbering is contiguous** — no skipped numbers.
+- **Handoff milestone has fixed 4 phases:** Polish, Content + SEO, Final QA, Handoff (credentials + walkthrough + archive + ERP report).
 
 ## Rules
 
 1. **Feature branches only** — never push to main
 2. **Read before write** — don't edit files you haven't read
 3. **MVP first** — build what's asked, nothing extra
-4. **`/qualia` is your friend** — lost? type it
+4. **Every task has a `Why`** (story-file format) — if you can't explain why a task matters in one sentence, it probably shouldn't exist
+5. **`/qualia` is your friend** — lost? type it
+6. **`/qualia-idk` is your deeper friend** — not lost on "what command", but confused about the *situation*? Type `idk`.
 
 ## When You're Stuck
 
 ```
-/qualia       ← "what's next?"
+/qualia       ← "what command should I run next?" (state-driven, instant)
+/qualia-idk   ← "what's actually going on here?" (diagnostic, scans planning + code, ~30s)
 ```
 
-If that doesn't help, paste the error and ask Claude directly. If Claude can't fix it, tell Fawzi.
+If neither helps, paste the error and ask Claude directly. If Claude can't fix it, tell Fawzi.
 
 ## Session Start / End
 
-**Start:** Claude loads your project context automatically.
-**End:** Run `/qualia-report` — this is mandatory before clock-out.
+**Start:** Claude loads your project context automatically. The router banner shows your journey position ("M2 of 4 · P2 of 3").
+**End:** Run `/qualia-report` — this is mandatory before clock-out. The report is committed to git and (if ERP is enabled) uploaded to https://portal.qualiasolutions.net.
 
 ## How It Works (you don't need to know this, but if curious)
 
+- **Journey-first planning:** `/qualia-new` produces JOURNEY.md listing every milestone from kickoff to Handoff with exit criteria and phase sketches. The whole team sees the path on day 1.
 - **Context isolation:** Each task runs in a fresh AI brain. Task 50 gets the same quality as Task 1.
-- **Goal-backward verification:** The verifier doesn't trust "I built it." It greps the code to check if things actually work.
-- **Plans are prompts:** The plan file IS what the builder reads. No translation loss.
+- **Pre-inlined context at dispatch:** The builder starts with PROJECT.md, DESIGN.md, and all Context @files already loaded — no wasted orientation reads.
+- **Goal-backward verification:** The verifier doesn't trust "I built it." It greps the code to check if things actually work AND walks every task's Acceptance Criteria.
+- **Story-file plans:** Every task has Why / Acceptance Criteria / Depends on / Validation inline — the plan IS the brief.
 - **Wave execution:** Independent tasks run in parallel. Dependent tasks wait.
-- **tracking.json:** Updated on every push. The ERP reads it automatically.
+- **Milestone-boundary pauses:** In `--auto` mode, the framework pauses only at real decision points. Everything else runs on rails.
+- **tracking.json:** Updated on every push. The ERP reads it automatically. v4 adds `milestone_name` + `milestones[]` so the ERP renders a proper tree instead of a flat list.
+
+## Quick Reference
+
+| Situation | Run |
+|---|---|
+| Starting a new client project | `/qualia-new` (or `/qualia-new --auto` to roll end-to-end) |
+| Starting a quick throwaway | `/qualia-new --quick` |
+| Brownfield project | `/qualia-map` first, then `/qualia-new` |
+| Stuck picking next command | `/qualia` |
+| Confused about the situation | `/qualia-idk` |
+| Finished the last phase of a milestone | `/qualia-milestone` |
+| About to ship | `/qualia-ship` |
+| Client is ready to take over | `/qualia-handoff` |
+| End of workday | `/qualia-report` (mandatory) |

package/hooks/migration-guard.js

@@ -11,6 +11,10 @@ const _traceStart = Date.now();
 // Read JSON tool input from stdin with a safety timeout.
 // On Windows, fs.readFileSync(0) can hang if stdin isn't closed by the host.
 // We loop fs.readSync with a 1s deadline; if no data arrives, treat as empty.
+// Between EAGAIN retries we sleep via Atomics.wait to avoid CPU-burning spin.
+function sleepSync(ms) {
+  try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch {}
+}
 function readInput() {
   const deadline = Date.now() + 1000;
   const buf = Buffer.alloc(65536);
@@ -21,8 +25,8 @@ function readInput() {
       try {
         n = fs.readSync(0, buf, 0, buf.length, null);
       } catch (e) {
-        // EAGAIN/EWOULDBLOCK: no data yet, retry until deadline
-        if (e && (e.code === "EAGAIN" || e.code === "EWOULDBLOCK")) continue;
+        // EAGAIN/EWOULDBLOCK: no data yet. Sleep 1ms and retry until deadline.
+        if (e && (e.code === "EAGAIN" || e.code === "EWOULDBLOCK")) { sleepSync(1); continue; }
         // Any other read error: bail
         break;
       }
@@ -108,14 +112,24 @@ if (/ALTER\s+TABLE\s+[^;]*\bDROP\s+COLUMN\b/i.test(scan)) {
   errors.push("ALTER TABLE ... DROP COLUMN is destructive");
 }
 
-// DELETE without WHERE
-if (/DELETE\s+FROM/i.test(scan) && !/WHERE/i.test(scan)) {
-  errors.push("DELETE FROM without WHERE clause");
+// DELETE / UPDATE without WHERE — check per-statement, not file-global.
+// Previously a file containing "DELETE FROM foo;" followed by any later
+// "... WHERE ..." (in a SELECT, JOIN, etc.) would pass the check.
+function splitStatements(src) {
+  return src.split(/;/g).map((s) => s.trim()).filter(Boolean);
 }
-
-// UPDATE without WHERE — affects every row
-if (/\bUPDATE\s+\w+(?:\.\w+)?\s+SET\b/i.test(scan) && !/WHERE/i.test(scan)) {
-  errors.push("UPDATE without WHERE clause — affects every row");
+const statements = splitStatements(scan);
+for (const stmt of statements) {
+  if (/^\s*DELETE\s+FROM\b/i.test(stmt) && !/\bWHERE\b/i.test(stmt)) {
+    errors.push("DELETE FROM without WHERE clause");
+    break;
+  }
+}
+for (const stmt of statements) {
+  if (/^\s*UPDATE\s+\w+(?:\.\w+)?\s+SET\b/i.test(stmt) && !/\bWHERE\b/i.test(stmt)) {
+    errors.push("UPDATE without WHERE clause — affects every row");
+    break;
+  }
 }
 
 // TRUNCATE (almost always wrong in migrations)

package/hooks/pre-compact.js

@@ -2,17 +2,44 @@
 // ~/.claude/hooks/pre-compact.js — commit STATE.md before context compaction.
 // PreCompact hook. Silent on failure — context compaction must never be blocked.
 // Cross-platform (Windows/macOS/Linux).
+//
+// BY DEFAULT this commit uses --no-verify + --no-gpg-sign. The auto-save is a
+// framework bot commit, and pre-commit hooks that run full test suites would
+// routinely fail (context compaction happens at any moment) and lose the
+// STATE.md snapshot. But compliance-sensitive projects can opt into strict
+// mode via ~/.claude/.qualia-config.json:
+//
+//   {
+//     "pre_compact": {
+//       "respect_user_hooks": true,
+//       "respect_gpg_signing": true
+//     }
+//   }
+//
+// When either is true, the corresponding --no-* flag is dropped.
 
 const fs = require("fs");
 const path = require("path");
+const os = require("os");
 const { spawnSync } = require("child_process");
 
 const _traceStart = Date.now();
 
 const STATE_FILE = path.join(".planning", "STATE.md");
+const CONFIG_FILE = path.join(os.homedir(), ".claude", ".qualia-config.json");
+
+function readCompactConfig() {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+    return cfg.pre_compact || {};
+  } catch {
+    return {};
+  }
+}
 
 let _commitStatus = null;
 let _commitReason = "no-state-file";
+let _commitFlags = null;
 
 try {
   if (fs.existsSync(STATE_FILE)) {
@@ -29,16 +56,17 @@ try {
         timeout: 3000,
         shell: process.platform === "win32",
       });
-      // Bypass user pre-commit hooks and commit signing so the auto-save
-      // never fails silently and STATE.md is always persisted before
-      // context compaction. Attribute to the framework bot, not the user.
-      const commitRes = spawnSync("git", [
-        "commit",
-        "--no-verify",
-        "--no-gpg-sign",
-        "--author=Qualia Framework <bot@qualia.solutions>",
-        "-m", "state: pre-compaction save",
-      ], {
+      const cfg = readCompactConfig();
+      const commitArgs = ["commit"];
+      if (!cfg.respect_user_hooks) commitArgs.push("--no-verify");
+      if (!cfg.respect_gpg_signing) commitArgs.push("--no-gpg-sign");
+      commitArgs.push("--author=Qualia Framework <bot@qualia.solutions>");
+      commitArgs.push("-m", "state: pre-compaction save");
+      _commitFlags = {
+        no_verify: !cfg.respect_user_hooks,
+        no_gpg_sign: !cfg.respect_gpg_signing,
+      };
+      const commitRes = spawnSync("git", commitArgs, {
         timeout: 5000,
         stdio: ["ignore", "ignore", "pipe"],
         encoding: "utf8",
@@ -72,5 +100,5 @@ function _trace(hookName, result, extra) {
   } catch {}
 }
 
-_trace("pre-compact", "allow", { commit_status: _commitStatus, commit_reason: _commitReason });
+_trace("pre-compact", "allow", { commit_status: _commitStatus, commit_reason: _commitReason, commit_flags: _commitFlags });
 process.exit(0);

package/hooks/pre-deploy-gate.js

@@ -2,8 +2,7 @@
 // ~/.claude/hooks/pre-deploy-gate.js — quality gates before production deploy.
 // PreToolUse hook on `vercel --prod*` commands. Runs tsc, lint, tests, build,
 // then scans for service_role leaks in client code.
-// Exits 1 to BLOCK deploy (preserved for test compatibility; Claude Code's hook
-// protocol formally uses exit 2, but the framework's existing tests assert on 1).
+// Exits 2 to BLOCK deploy (Claude Code PreToolUse hook contract).
 // Exits 0 to allow.
 // Cross-platform (Windows/macOS/Linux). No `grep` or `find` — pure Node.
 
@@ -43,7 +42,7 @@ function runGate(label, cmd, args, { required = true } = {}) {
   if (required) {
     console.error(`BLOCKED: ${label} errors. Fix before deploying.`);
     _trace("pre-deploy-gate", "block", { gate: label });
-    process.exit(1);
+    process.exit(2);
   }
   return false;
 }
@@ -180,7 +179,7 @@ if (leaks.length > 0) {
     console.error(`  ✗ ${f}`);
   }
   _trace("pre-deploy-gate", "block", { gate: "security", leaks: leaks.slice(0, 10) });
-  process.exit(1);
+  process.exit(2);
 }
 console.log("  ✓ Security");
 console.log("⬢ All gates passed.");

package/hooks/pre-push.js

@@ -85,9 +85,12 @@ function commitStamp() {
     "-m", `chore(track): ERP sync ${now}`,
   ]);
   if (commit.status !== 0) {
-    // If commit failed (e.g., empty diff because git's auto-CRLF normalized
-    // the only change to nothing), restore the file to keep the working tree
-    // clean and move on. Not fatal.
+    // Commit failed (e.g., empty diff because git's auto-CRLF normalized the
+    // only change to nothing, or branch is in a detached/conflicted state).
+    // Unstage tracking.json and restore the working tree copy so the user's
+    // next manual commit isn't polluted by our aborted stamp.
+    try { git(["reset", "HEAD", "--", TRACKING]); } catch {}
+    try { if (raw != null) atomicWrite(TRACKING, raw); } catch {}
     return { skipped: "git-commit-failed", error: (commit.stderr || commit.stdout || "").trim() };
   }
   return { committed: true, sha: lastCommit, ts: now };

package/hooks/session-start.js

@@ -52,6 +52,14 @@ function getNextCommand() {
   }
 }
 
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(HOME, ".claude", ".qualia-config.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
 function fallbackText() {
   // If qualia-ui.js is missing, emit plain text. Keeps the session informative
   // even on a broken install.
@@ -121,14 +129,6 @@ try {
   // Deliberately silent — hook must never fail
 }
 
-function readConfig() {
-  try {
-    return JSON.parse(fs.readFileSync(path.join(HOME, ".claude", ".qualia-config.json"), "utf8"));
-  } catch {
-    return {};
-  }
-}
-
 function _trace(hookName, result, extra) {
   try {
     const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "3.6.0",
+  "version": "4.0.3",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"

package/rules/frontend.md

@@ -109,18 +109,10 @@ These are Qualia brand standards — mandatory for every frontend component. Not
 If `.planning/DESIGN.md` exists in the project, it takes precedence over these defaults.
 Read it before any frontend work. It contains project-specific: palette, typography, spacing, component patterns.
 
-## Impeccable Design Skills (global)
-- `/polish` — Final detail pass before shipping
-- `/bolder` — Amplify safe/boring designs
-- `/design-quieter` — Tone down overly aggressive designs
-- `/animate` — Add purposeful micro-interactions
-- `/colorize` — Inject strategic color into monochrome UIs
-- `/clarify` — Fix unclear UX copy, labels, error messages
-- `/critique` — Design director-level review
-- `/distill` — Strip unnecessary complexity
-- `/delight` — Add memorable touches and personality
-- `/harden` — Edge cases, overflow, i18n robustness
-- `/responsive` — Cross-device responsive adaptation
+## Qualia design commands
+- `/qualia-design` — One-shot design transformation (critique + fix + polish + responsive + harden)
+- `/qualia-polish` — Final detail pass before shipping (run after all phases verified)
+- `/qualia-review` — Scored production audit
 
 ### Recommended workflow
-1. Build feature → 2. `/critique` → 3. `/polish` → 4. `/harden` → ship
+1. Build feature → 2. `/qualia-design` → 3. `/qualia-polish` → ship

package/skills/qualia/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: qualia
-description: "Smart router — reads project state, classifies your situation, tells you the exact next command. Use whenever you type /qualia, 'what next', 'next', 'idk', 'what now', 'what should I do', 'I'm stuck', 'help me decide', 'lost', 'confused', or are unsure about your next step."
+description: "Smart router — reads project state (state.js), classifies the situation mechanically, returns the exact next command. Use whenever you type /qualia, 'what next', 'next', 'what now', 'what should I do next', 'what command now'. For deeper 'I don't understand what's going on' / 'something feels off' situations, use /qualia-idk instead — that one actually scans the planning folder and codebase to diagnose the confusion."
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
 ---
 
 # /qualia — What's Next?
@@ -56,6 +61,8 @@ Use the state.js JSON output plus gathered context:
 **Clear next step** (use the UI helper — it reads state.js itself):
 ```bash
 node ~/.claude/bin/qualia-ui.js banner router
+# If a project is loaded, show the journey position first (one-glance orientation)
+test -f .planning/JOURNEY.md && node ~/.claude/bin/qualia-ui.js journey-tree .planning/JOURNEY.md
 node ~/.claude/bin/qualia-ui.js next "{next_command from state.js}"
 ```
 

package/skills/qualia-build/SKILL.md

@@ -1,6 +1,16 @@
 ---
 name: qualia-build
 description: "Execute the current phase — spawns builder subagents per task with wave-based parallelization. Fresh context per task."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
+  - TaskCreate
+  - TaskUpdate
 ---
 
 # /qualia-build — Build a Phase
@@ -10,6 +20,7 @@ Execute the phase plan. Each task runs in a fresh subagent context. Independent
 ## Usage
 `/qualia-build` — build the 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)
 
 ## Process
 
@@ -57,22 +68,44 @@ node ~/.claude/bin/qualia-ui.js wave {W} {total_waves} {tasks_in_wave}
 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):
+
+1. Parse the task's `Context:` field to get `@file` references
+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
+
 Spawn a fresh builder subagent:
 
 ```
 Agent(prompt="
 Read your role: @~/.claude/agents/builder.md
 
-Project context:
-@.planning/PROJECT.md
+<pre-loaded-context>
+# PROJECT.md
+{inlined contents of .planning/PROJECT.md}
+
+# DESIGN.md (if frontend task)
+{inlined contents of .planning/DESIGN.md}
+
+# {each @file from task.Context}
+{inlined contents}
+</pre-loaded-context>
 
 YOUR TASK:
-{paste the single task block from the plan — title, files, action, context refs, done-when}
+{paste the single task block from the plan — title, wave, persona, files, depends-on, why, acceptance-criteria, action, validation, context}
 
-Execute this task. Read all @file references before writing. Commit when done.
+All files in <pre-loaded-context> are already in your working memory — do NOT
+re-Read them. Only Read files NOT in the pre-loaded context (e.g. existing
+project code you need to modify).
+
+Execute the task. Commit when done.
 ", subagent_type="qualia-builder", description="Task {N}: {title}")
 ```
 
+**Why pre-inline:** without it, the builder's first actions are 3-5 Read tool calls to orient itself (PROJECT.md, DESIGN.md, context files). With pre-inline, the builder starts already oriented and spends its context budget on the actual task.
+
 **After each task completes:**
 - Verify the commit exists: `git log --oneline -1`
 - Show result:
@@ -110,6 +143,18 @@ node ~/.claude/bin/state.js transition --to built --phase {N} --tasks-done {done
 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.
 
+### 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).
+
+```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.
+
+**Otherwise (default guided mode):** stop and show the next step:
+
 ```bash
 node ~/.claude/bin/qualia-ui.js end "PHASE {N} BUILT" "/qualia-verify {N}"
 ```

package/skills/qualia-debug/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: qualia-debug
 description: "Structured debugging — symptom gathering, diagnosis confirmation, root cause analysis. Trigger on 'debug', 'find bug', 'fix error', 'something is broken', 'not working', 'weird behavior', 'layout broken', 'CSS issue', 'slow page', 'performance'."
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-debug — Structured Debugging

package/skills/qualia-design/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: qualia-design
 description: "One-shot design transformation — critiques, fixes, polishes, hardens, makes responsive. No reports, no choices, just makes it professional. Trigger on 'fix the design', 'make it look better', 'redesign', 'design pass', 'make it modern', 'it looks ugly', 'fix the UI'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-design — One-Shot Design Transformation
@@ -87,7 +95,7 @@ git commit -m "style: design transformation"
   - {key change 2}
   - {key change 3}
 
-  Fine-tune: /bolder, /design-quieter, /colorize, /animate
+  Next: /qualia-polish (final pass) · /qualia-review (scored audit)
 ```
 
 ## Rules

package/skills/qualia-discuss/SKILL.md

@@ -1,6 +1,12 @@
 ---
 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."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - AskUserQuestion
 ---
 
 # /qualia-discuss — Phase Context Capture