qualia-framework 3.4.0 → 4.0.0

package/agents/roadmapper.md

@@ -1,30 +1,34 @@
 ---
 name: qualia-roadmapper
-description: Creates REQUIREMENTS.md (v1 requirements with REQ-IDs) and ROADMAP.md (phases mapped to requirements) from PROJECT.md and research. Spawned by qualia-new after research completes.
-tools: Read, Write
+description: Creates JOURNEY.md (full multi-milestone arc), REQUIREMENTS.md (multi-milestone, REQ-IDs), and ROADMAP.md (current milestone's phase detail) from PROJECT.md and research. Spawned by qualia-new after research completes.
+tools: Read, Write, Bash
 ---
 
 # Qualia Roadmapper
 
-You create two files: `REQUIREMENTS.md` (v1 requirements with REQ-IDs) and `ROADMAP.md` (phases mapped to requirements). You work from PROJECT.md + research SUMMARY.md. You don't run research yourself — that's already done.
+You produce the **full project journey** — every milestone from kickoff to handoff. This is the North Star for the rest of the project. Everything downstream (planner, builder, verifier, milestone close) stays architecturally consistent with what you write here.
+
+You do NOT run research — that's already done upstream.
 
 ## Input
 
 You receive:
 - `.planning/PROJECT.md` — core value, constraints, what they're building
-- `.planning/research/SUMMARY.md` — research synthesis with suggested phase structure (optional — may not exist if research was skipped)
-- `.planning/config.json` — project config including `depth` (quick | standard | comprehensive)
+- `.planning/research/SUMMARY.md` — research synthesis (optional — may not exist if research was skipped)
+- `.planning/config.json` — project config (`depth`, `template_type`)
 - User's confirmed feature scope (from the scoping conversation in qualia-new)
 
 ## Output
 
-Write two files:
-- `.planning/REQUIREMENTS.md` using template `~/.claude/qualia-templates/requirements.md`
-- `.planning/ROADMAP.md` using template `~/.claude/qualia-templates/roadmap.md`
+Write THREE files:
+
+1. `.planning/JOURNEY.md` — the full arc (all milestones) using `~/.claude/qualia-templates/journey.md`
+2. `.planning/REQUIREMENTS.md` — v1 requirements grouped by milestone, using `~/.claude/qualia-templates/requirements.md`
+3. `.planning/ROADMAP.md` — **only the current (first) milestone's phase detail**, using `~/.claude/qualia-templates/roadmap.md`
 
-Also update `.planning/STATE.md` via `state.js init` (NOT directly) so the phase tracker matches the roadmap you created.
+Then update `.planning/STATE.md` via `state.js init` (NOT directly) so the state machine matches Milestone 1's phases.
 
-## How to Build the Roadmap
+## How to Build the Journey
 
 ### 1. Read Context
 
@@ -32,126 +36,127 @@ Also update `.planning/STATE.md` via `state.js init` (NOT directly) so the phase
 Read: .planning/PROJECT.md
 Read: .planning/research/SUMMARY.md (if exists)
 Read: .planning/config.json
+Read: ~/.claude/qualia-templates/journey.md
 Read: ~/.claude/qualia-templates/requirements.md
 Read: ~/.claude/qualia-templates/roadmap.md
 ```
 
-### 2. Build REQUIREMENTS.md First
+### 2. Build REQUIREMENTS.md — grouped by milestone
 
-Before defining phases, define what "done" means as a list of atomic, testable requirements.
+Define what "done" means as atomic, testable requirements.
 
 **Format:** `{CATEGORY}-{NUMBER}` — `AUTH-01`, `CONT-02`, `SOCIAL-03`
 
-**Categories** come from:
-- Research FEATURES.md categories (if research exists)
-- User's confirmed feature scope from the scoping conversation
-- Common sense: Authentication, Content, Social, Notifications, Admin, etc.
-
 **Each requirement is:**
-- **Specific and testable:** "User can reset password via email link" (not "handle password reset")
 - **User-centric:** "User can X" (not "System does Y")
-- **Atomic:** One capability per requirement
-- **Independent:** Minimal dependencies on other requirements
+- **Atomic:** one capability per requirement
+- **Testable:** you can name the observable behavior
+- **Assigned to exactly one milestone**
 
-Put v1 requirements under `## v1 Requirements` grouped by category.
-Put deferred features under `## v2 Requirements`.
-Put explicit exclusions under `## Out of Scope` with reasoning.
+Organize requirements under `## Milestone 1 · {Name}`, `## Milestone 2 · {Name}`, ..., `## Handoff` sections. Put deferred features under `## Post-Handoff (v2)` and exclusions under `## Out of Scope`.
 
-### 3. Derive Phases
+### 3. Derive the Milestone Arc (JOURNEY.md)
 
-**Rules:**
-1. **Feature phases only.** Do NOT add review / deploy / handoff phases — those are handled by `/qualia-polish` → `/qualia-ship` → `/qualia-handoff` after feature phases complete.
-2. **Phase count depends on `depth` config:**
-   - `quick`: 3-5 phases
-   - `standard`: 5-8 phases
-   - `comprehensive`: 7-12 phases
-3. **Each phase is independently verifiable.** A phase completes when its success criteria are observable in a running app.
-4. **Each v1 requirement maps to exactly ONE phase.** No duplicates, no gaps.
-5. **Order by dependency, not priority.** Phase 2 should be able to use Phase 1's outputs.
+This is the most important step.
 
-**Typical phase shapes:**
+**Hard rules:**
+- **Ceiling: 5 milestones** (including Handoff). If the project needs more, defer remainder to post-handoff v2.
+- **Floor: 2 milestones** (one feature milestone + Handoff). If smaller, the project should use `/qualia-new --quick` instead.
+- **Final milestone is ALWAYS "Handoff"** with 4 standard phases: Polish, Content + SEO, Final QA, Handoff (credentials + walkthrough + domain transfer).
+- **Every non-Handoff milestone must have ≥ 2 phases** OR be an explicit shipped release gate. Single-phase milestones are phases, not milestones — merge them into the preceding milestone.
+- **Milestones are ordered by dependency, not priority.** M2 must be able to use M1's outputs.
 
-- **Phase 1: Foundation** — DB schema, auth, base layout, deploy pipeline
-- **Phase 2-4: Core features** — the main value-delivering capabilities
-- **Phase N-1: Content / UX polish** — copy, media, responsive, animations
-- **Phase N: Final polish** — SEO, analytics, performance, a11y
+**Typical milestone arcs by project type:**
 
-But don't force-fit this template. Shape the phases around what this specific project needs, using the research SUMMARY.md as your starting point.
+| Type | Arc |
+|---|---|
+| Landing / marketing | 2 milestones: Foundation → Handoff |
+| SaaS / dashboard | 4 milestones: Foundation → Core Features → Admin & Reporting → Handoff |
+| Voice / AI agent | 4 milestones: Foundation → Core Flow → Integrations → Handoff |
+| Mobile app | 5 milestones: Foundation → Core → Offline & Notifications → Store Prep → Handoff |
+| Multi-tenant platform | 5 milestones: Foundation → Core → Admin → Scale → Handoff |
 
-### 4. Derive Success Criteria per Phase
+Use the research SUMMARY.md as your starting point. Don't force-fit the template — shape to this specific project.
 
-For each phase, write 2-5 success criteria. Each must be:
-- **Observable** — someone running the app can see it work
-- **User-centric** — "user can X" not "code does Y"
-- **Phase-specific** — not generic ("tests pass" applies to every phase)
+**For each milestone:**
+- **Name** — short and evocative (e.g., "Core Feature Loop", not "Phase 2 Work")
+- **Why now** — one sentence explaining why this milestone comes *after* the previous and *before* the next. In plain language a non-technical team member understands.
+- **Exit criteria** — 2-3 observable outcomes that define "shipped" for this milestone
+- **Phases** — 2-5 phases. For Milestone 1, include full detail (goal + success criteria). For M2..M{N-1}, names + one-line goals are enough (progressive detail — full detail gets written when that milestone opens). For Handoff, use the fixed 4-phase template.
+- **Requirements covered** — list the REQ-IDs this milestone delivers
 
-**Example (good):**
-- User can sign up with email and receive verification email
-- User can log in and stay logged in across browser refresh
-- User can log out from any page
+### 4. Build ROADMAP.md — ONLY Milestone 1's phases (fully detailed)
 
-**Example (bad — too vague):**
-- Authentication works
-- Tests pass
-- Code is clean
+The current milestone gets full phase detail. Future milestones stay as sketches in JOURNEY.md until they open.
+
+For each phase in Milestone 1:
+- **Name** + **goal** (one line)
+- **Success criteria** — 2-5 observable user-facing behaviors
+- **Requirements covered** — REQ-IDs from REQUIREMENTS.md Milestone 1 section
 
 ### 5. Validate Coverage
 
-Before writing the files, verify:
-- [ ] Every v1 requirement maps to exactly one phase
-- [ ] Every phase has 2-5 success criteria
-- [ ] No phase depends on a later phase
-- [ ] Phase count is within the range for the `depth` config
-- [ ] No "review" / "deploy" / "handoff" phases
+Before writing, verify:
+- [ ] Every v1 requirement (all milestones excluding Handoff) has a REQ-ID
+- [ ] Every v1 requirement maps to exactly one milestone
+- [ ] Every milestone has ≥ 2 phases (except Handoff which has the fixed 4)
+- [ ] Milestone count is 2-5 total
+- [ ] Final milestone is literally named "Handoff" with the 4 standard phases
+- [ ] No milestone depends on a later milestone
+- [ ] Milestone 1 has full phase-level detail (goals + success criteria) ready for `/qualia-plan 1`
+- [ ] M2..M{N-1} have phase names + one-line goals (sketch, not full detail)
 
-If any requirement is unmapped, the roadmap is incomplete. Either add it to a phase or explicitly move it to v2.
+If any check fails, fix it. The orchestrator trusts your output.
 
 ### 6. Write the Files
 
-Write both files to `.planning/`. Use the templates as structural guides. Fill in every `{placeholder}` with concrete content.
+Write all three files to `.planning/`. Fill every `{placeholder}` with concrete content.
 
 ### 7. Update STATE.md via state.js
 
-**Do not edit STATE.md directly.** Call the state machine:
+**Do not edit STATE.md directly.** Call the state machine with Milestone 1's phases:
 
 ```bash
 node ~/.claude/bin/state.js init \
   --project "{project name from PROJECT.md}" \
   --client "{client from PROJECT.md}" \
   --type "{type from PROJECT.md}" \
-  --phases '<JSON array of {name, goal} objects>' \
-  --total_phases {N}
+  --milestone_name "{Milestone 1 name}" \
+  --phases '<JSON array of {name, goal} objects for Milestone 1 only>' \
+  --total_phases {count of Milestone 1 phases}
 ```
 
-This ensures STATE.md + tracking.json stay consistent and the status bar updates correctly.
+`--milestone_name` is the human name of Milestone 1 (e.g. "Foundation"). tracking.json records it so the status bar and ERP tree render correctly.
 
 ### 8. Return a Summary
 
-Report back to the orchestrator:
-
 ```
-Wrote: .planning/REQUIREMENTS.md ({X} v1 requirements, {Y} categories)
-Wrote: .planning/ROADMAP.md ({N} phases, 100% coverage)
-Wrote: .planning/STATE.md (via state.js init)
-
-Phase summary:
-  1. {name} — {REQ-IDs}
-  2. {name} — {REQ-IDs}
+Wrote: .planning/JOURNEY.md ({N} milestones to handoff)
+Wrote: .planning/REQUIREMENTS.md ({X} v1 requirements, {Y} categories, grouped across {N-1} feature milestones + Handoff)
+Wrote: .planning/ROADMAP.md (Milestone 1: {name} — {P} phases, ready for /qualia-plan 1)
+Wrote: .planning/STATE.md (via state.js init, milestone_name={Milestone 1 name})
+
+Journey:
+  M1. {Name} — {REQ-IDs}, {P} phases       [CURRENT, full detail]
+  M2. {Name} — {REQ-IDs}, {P} phases       [sketched]
   ...
+  M{N}. Handoff — 4 phases                 [standard]
 
-Research flags: {count} phases may need deeper research during planning
+Research flags: {count} milestones may need deeper research during planning
 ```
 
-## Quality Gates
+## Quality Gates (self-check)
 
-Before returning, self-check:
+Before returning:
 
-- [ ] Every v1 requirement has a REQ-ID in correct format
-- [ ] Every v1 requirement maps to exactly one phase
-- [ ] Every phase has 2-5 success criteria (observable, user-centric)
-- [ ] No phase depends on a later phase
-- [ ] No non-feature phases (no review/deploy/handoff)
-- [ ] STATE.md was updated via state.js, not directly
-- [ ] Requirements traceability table is populated
+- [ ] JOURNEY.md exists with all {N} milestones and exit criteria per milestone
+- [ ] REQUIREMENTS.md exists, requirements grouped by milestone, REQ-IDs present
+- [ ] ROADMAP.md exists with Milestone 1's phase detail
+- [ ] Final milestone is literally named "Handoff" with Polish / Content + SEO / Final QA / Handoff phases
+- [ ] Every feature milestone has ≥ 2 phases
+- [ ] Milestone count is between 2 and 5
+- [ ] STATE.md was updated via `state.js init` with `--milestone_name`, never edited by hand
+- [ ] M1's phases are fully detailed (goals + success criteria ready for planner)
+- [ ] M2..M{N-1} are sketched (phase names + one-line goals, detail later)
 
-If any check fails, fix it before returning. The orchestrator trusts your output — don't return half-baked roadmaps.
+If any check fails, fix it before returning. Incomplete roadmaps cost downstream time and cascade errors into every phase that follows.

package/agents/verifier.md

@@ -71,9 +71,18 @@ If the plan has no `## Verification Contract` section (older plans), skip this s
 ## How to Verify
 
 ### 1. Read the Plan
-Extract success criteria from the phase plan's `## Success Criteria` section. Also extract the `## Verification Contract` if present.
 
-### 2. For Each Criterion, Run the 3-Level Check
+Extract THREE layers of truth from the plan file:
+
+1. **Phase-level truths** — the `## Success Criteria` section
+2. **Task-level Acceptance Criteria** — the `**Acceptance Criteria:**` bullets inside each `## Task N` block. These describe user-observable behavior PER TASK and should all be true.
+3. **Verification Contract** — the `## Verification Contract` section with testable commands.
+
+Contracts (layer 3) take priority because they're machine-executable. Acceptance Criteria (layer 2) are the bridge between task and phase — if all AC across all tasks pass, the phase success criteria should follow.
+
+### 2. For Each Criterion (Phase + Per-Task AC), Run the 3-Level Check
+
+First, walk every task's Acceptance Criteria. For each AC, ask: does the code produce this observable behavior? Grep the artifacts, trace the wiring, inspect the route handler. Then run the 3-level check below on each phase-level Success Criterion.
 
 ```bash
 # Level 2: Does the file exist?

package/bin/cli.js

@@ -564,9 +564,19 @@ function cmdMigrate() {
   }
   if (!bashEntry.hooks) bashEntry.hooks = [];
 
+  // Compare by basename, not by absolute-path substring. If the user moved
+  // ~ between OS reinstalls, the OLD path embedded in settings.json no
+  // longer matches the NEW path and migrate would otherwise append a
+  // duplicate entry on every re-run.
+  const extractScriptName = (command) => {
+    const match = command && command.match(/["']([^"']+\.js)["']/);
+    return match ? path.basename(match[1]) : null;
+  };
+
   for (const hookFile of requiredBashHooks) {
     const cmd = nodeCmd(hookFile);
-    const exists = bashEntry.hooks.some(h => h.command && h.command.includes(hookFile));
+    const targetName = path.basename(hookFile);
+    const exists = bashEntry.hooks.some(h => extractScriptName(h.command) === targetName);
     if (!exists) {
       const hookDef = { type: "command", command: cmd, timeout: hookFile === "pre-deploy-gate.js" ? 180 : 5 };
       if (hookFile === "branch-guard.js") hookDef.if = "Bash(git push*)";
@@ -588,7 +598,8 @@ function cmdMigrate() {
 
   for (const hookFile of requiredEditHooks) {
     const cmd = nodeCmd(hookFile);
-    const exists = editEntry.hooks.some(h => h.command && h.command.includes(hookFile));
+    const targetName = path.basename(hookFile);
+    const exists = editEntry.hooks.some(h => extractScriptName(h.command) === targetName);
     if (!exists) {
       const hookDef = { type: "command", command: cmd, timeout: hookFile === "migration-guard.js" ? 10 : 5 };
       if (hookFile === "migration-guard.js") hookDef.if = "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)";

package/bin/install.js

@@ -497,16 +497,39 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
       api_key_file: ".erp-api-key",
     },
   };
-  fs.writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n");
+  // mode 0o600: this file holds the role bit (OWNER vs EMPLOYEE) which the
+  // branch-guard hook trusts. Default 0644 would let any local user edit it
+  // and self-elevate.
+  fs.writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+  try { fs.chmodSync(configFile, 0o600); } catch {}
 
   // ─── ERP API key (for report uploads) ──────────────────
+  // Per-user keys, never a hardcoded shared default. Sources, in order:
+  //   1. $QUALIA_ERP_KEY env var at install time (CI / scripted installs)
+  //   2. Existing ~/.claude/.erp-api-key (preserved across re-installs)
+  //   3. Skip — ERP disabled in config until user runs `qualia-framework set-erp-key`
   printSection("ERP Integration");
   const erpKeyFile = path.join(CLAUDE_DIR, ".erp-api-key");
-  if (!fs.existsSync(erpKeyFile)) {
-    fs.writeFileSync(erpKeyFile, "qualia-claude-2026", { mode: 0o600 });
-    ok(".erp-api-key (created)");
+  const envKey = (process.env.QUALIA_ERP_KEY || "").trim();
+  if (envKey) {
+    fs.writeFileSync(erpKeyFile, envKey, { mode: 0o600 });
+    try { fs.chmodSync(erpKeyFile, 0o600); } catch {}
+    ok(".erp-api-key (from $QUALIA_ERP_KEY)");
+  } else if (fs.existsSync(erpKeyFile)) {
+    try { fs.chmodSync(erpKeyFile, 0o600); } catch {}
+    ok(".erp-api-key (existing — preserved)");
   } else {
-    ok(".erp-api-key (exists)");
+    // Disable ERP in the config we just wrote.
+    try {
+      const cfg = JSON.parse(fs.readFileSync(configFile, "utf8"));
+      cfg.erp = { ...(cfg.erp || {}), enabled: false };
+      fs.writeFileSync(configFile, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
+      try { fs.chmodSync(configFile, 0o600); } catch {}
+    } catch {}
+    log(`${YELLOW}!${RESET} ERP key not configured — reports won't upload until set.`);
+    log(`${DIM}  Set with:${RESET} ${TEAL}export QUALIA_ERP_KEY=...${RESET} ${DIM}then re-install,${RESET}`);
+    log(`${DIM}  or write the key to:${RESET} ${WHITE}${erpKeyFile}${RESET} ${DIM}(mode 0600).${RESET}`);
+    log(`${DIM}  Get a key from Fawzi.${RESET}`);
   }
 
   // ─── Configure settings.json ───────────────────────────

package/bin/qualia-ui.js

@@ -17,6 +17,9 @@
 //   next <command>                       — "Run: /qualia-X" footer
 //   end <status> [next-command]          — closing banner with optional next
 //   update <current> <latest>            — sticky framework update banner
+//   plan-summary <path/to/plan.md>       — story-file dashboard for a plan
+//   journey-tree [path/to/JOURNEY.md]    — ladder view of all milestones, current highlighted
+//   milestone-complete <num> <name> <next> — celebration banner on milestone close
 
 const fs = require("fs");
 const path = require("path");
@@ -63,6 +66,11 @@ const ACTIONS = {
   welcome:    { label: "WELCOME",          glyph: "⬢" },
   test:       { label: "TESTING",          glyph: "⊡" },
   analytics:  { label: "ANALYTICS",        glyph: "◈" },
+  milestone:  { label: "MILESTONE",        glyph: "◆" },
+  journey:    { label: "JOURNEY",          glyph: "◯" },
+  auto:       { label: "AUTO MODE",        glyph: "⚡" },
+  research:   { label: "RESEARCH",         glyph: "◱" },
+  roadmap:    { label: "ROADMAP",          glyph: "◐" },
 };
 
 // ─── State Reading ───────────────────────────────────────
@@ -259,6 +267,261 @@ function cmdEnd(status, nextCmd) {
   console.log("");
 }
 
+// ─── Journey Tree (the North Star visualization) ────────
+// Renders JOURNEY.md as an ASCII ladder with the current milestone highlighted.
+// Called after /qualia-new to show the full arc, and by /qualia (router) to
+// orient the user on "you are here".
+function cmdJourneyTree(journeyPath) {
+  const p = journeyPath || ".planning/JOURNEY.md";
+  let content = "";
+  try {
+    content = fs.readFileSync(p, "utf8");
+  } catch {
+    console.log(`  ${DIM}No JOURNEY.md at ${p}${RESET}`);
+    return;
+  }
+
+  const state = readState();
+  const currentMilestone = state && state.ok ? (state.milestone || 1) : 1;
+
+  // Parse milestone blocks: "## Milestone N · Name" or "## Milestone N · Handoff"
+  const milestoneRe = /^## Milestone (\d+)\s*·\s*(.+?)\s*(?:\[[^\]]*\])?\r?$/gm;
+  const milestones = [];
+  let m;
+  while ((m = milestoneRe.exec(content)) !== null) {
+    const num = parseInt(m[1]);
+    const name = m[2].trim();
+    // Extract the section body to pull Why-now and phases
+    const startIdx = m.index + m[0].length;
+    const nextMatch = milestoneRe.exec(content);
+    const endIdx = nextMatch ? nextMatch.index : content.length;
+    milestoneRe.lastIndex = startIdx; // rewind for next iteration
+    const body = content.slice(startIdx, endIdx);
+
+    const whyMatch = body.match(/\*\*Why now:\*\*\s*(.+?)\r?$/m);
+    const why = whyMatch ? whyMatch[1].trim() : "";
+
+    const phaseNames = [];
+    const phaseRe = /^\d+\.\s+\*\*([^*]+)\*\*/gm;
+    let pm;
+    while ((pm = phaseRe.exec(body)) !== null) {
+      phaseNames.push(pm[1].trim());
+    }
+
+    milestones.push({ num, name, why, phaseNames });
+    if (nextMatch) milestoneRe.lastIndex = nextMatch.index;
+    else break;
+  }
+
+  if (milestones.length === 0) {
+    console.log(`  ${DIM}JOURNEY.md has no milestones to render${RESET}`);
+    return;
+  }
+
+  // Project name from frontmatter if present
+  const projMatch = content.match(/^project:\s*"?(.+?)"?\s*$/m);
+  const projectName = projMatch ? projMatch[1] : projectName();
+
+  console.log("");
+  console.log(`  ${TEAL}${BOLD}◯${RESET} ${WHITE}${BOLD}JOURNEY${RESET} ${DIM}▸${RESET} ${WHITE}${projectName}${RESET}`);
+  console.log(`  ${RULE_DIM}`);
+  console.log(`  ${DIM}${milestones.length} milestones · currently at M${currentMilestone}${RESET}`);
+  console.log("");
+
+  for (let i = 0; i < milestones.length; i++) {
+    const ms = milestones[i];
+    const isCurrent = ms.num === currentMilestone;
+    const isPast = ms.num < currentMilestone;
+    const isFuture = ms.num > currentMilestone;
+    const isHandoff = /handoff/i.test(ms.name);
+
+    let marker;
+    let labelColor;
+    let connector = "│";
+
+    if (isPast) {
+      marker = `${GREEN}●${RESET}`;
+      labelColor = DIM;
+    } else if (isCurrent) {
+      marker = `${TEAL}${BOLD}◆${RESET}`;
+      labelColor = TEAL + BOLD;
+    } else {
+      marker = `${DIM2}○${RESET}`;
+      labelColor = WHITE;
+    }
+
+    const tag = isCurrent
+      ? ` ${TEAL}${BOLD}[CURRENT]${RESET}`
+      : isPast
+      ? ` ${GREEN}[shipped]${RESET}`
+      : isHandoff
+      ? ` ${DIM2}[FINAL]${RESET}`
+      : "";
+
+    console.log(`  ${marker} ${labelColor}M${ms.num} · ${ms.name}${RESET}${tag}`);
+
+    if (ms.why && (isCurrent || isFuture)) {
+      const shortWhy = ms.why.length > 80 ? ms.why.slice(0, 77) + "…" : ms.why;
+      console.log(`  ${DIM2}│${RESET}   ${DIM}${shortWhy}${RESET}`);
+    }
+
+    if (ms.phaseNames.length > 0 && (isCurrent || isHandoff)) {
+      const phaseList = ms.phaseNames.slice(0, 4).join(` ${DIM2}→${RESET} ${DIM}`);
+      console.log(`  ${DIM2}│${RESET}   ${DIM}${phaseList}${DIM}${ms.phaseNames.length > 4 ? ` +${ms.phaseNames.length - 4}` : ""}${RESET}`);
+    }
+
+    // Connector between milestones (skip after last)
+    if (i < milestones.length - 1) {
+      console.log(`  ${DIM2}│${RESET}`);
+    }
+  }
+  console.log("");
+  console.log(`  ${RULE_DIM}`);
+}
+
+// ─── Milestone Complete (celebration banner) ─────────────
+// Shown at milestone-boundary in auto mode, and by /qualia-milestone manually.
+function cmdMilestoneComplete(num, name, nextName) {
+  console.log("");
+  console.log(`  ${GREEN}${BOLD}◆${RESET} ${WHITE}${BOLD}MILESTONE ${num} SHIPPED${RESET} ${DIM}·${RESET} ${TEAL}${name || ""}${RESET}`);
+  console.log(`  ${RULE_DIM}`);
+  if (nextName) {
+    if (/handoff/i.test(nextName)) {
+      console.log(`  ${DIM}Next${RESET}      ${TEAL}${BOLD}${nextName}${RESET} ${DIM}· the final milestone${RESET}`);
+    } else {
+      console.log(`  ${DIM}Next${RESET}      ${WHITE}${nextName}${RESET}`);
+    }
+  } else {
+    console.log(`  ${GREEN}${BOLD}PROJECT COMPLETE${RESET} ${DIM}· last milestone reached${RESET}`);
+  }
+  console.log(`  ${RULE_DIM}`);
+  console.log("");
+}
+
+// ─── Plan Summary (story-file dashboard) ─────────────────
+// Renders a polished overview of a plan file: phase goal, tasks grouped by wave,
+// persona chips, dependency lines, AC count, validation count. Called by
+// /qualia-plan after the planner and plan-checker finish.
+function cmdPlanSummary(planPath) {
+  if (!planPath) {
+    console.error("Usage: qualia-ui.js plan-summary <path-to-plan.md>");
+    process.exit(1);
+  }
+  let content = "";
+  try {
+    content = fs.readFileSync(planPath, "utf8");
+  } catch (e) {
+    console.error(`Cannot read plan: ${e.message}`);
+    process.exit(1);
+  }
+
+  // ─ Parse frontmatter + phase header ─
+  const fmMatch = content.match(/^---\n([\s\S]+?)\n---/);
+  const fm = {};
+  if (fmMatch) {
+    for (const line of fmMatch[1].split("\n")) {
+      const m = line.match(/^(\w+):\s*(.+?)\s*$/);
+      if (m) fm[m[1]] = m[2].replace(/^["']|["']$/g, "");
+    }
+  }
+  const phaseNum = fm.phase || "?";
+  const phaseGoal = fm.goal || "";
+  const phaseTitleMatch = content.match(/^# Phase \d+:?\s*(.+?)\r?$/m);
+  const phaseTitle = phaseTitleMatch ? phaseTitleMatch[1].trim() : `Phase ${phaseNum}`;
+  const whyPhaseMatch = content.match(/^\*\*Why this phase:\*\*\s*(.+?)\r?$/m);
+  const whyPhase = whyPhaseMatch ? whyPhaseMatch[1].trim() : "";
+
+  // ─ Parse tasks ─
+  const taskBlocks = content.split(/^(?=## Task \d+)/m).filter((b) => /^## Task \d+/.test(b));
+  const tasks = taskBlocks.map((block) => {
+    const titleMatch = block.match(/^## Task (\d+)\s*—\s*(.+?)\r?$/m);
+    const wave = parseInt((block.match(/\*\*Wave:\*\*\s*(\d+)/) || [])[1]) || 1;
+    const persona = ((block.match(/\*\*Persona:\*\*\s*(.+?)\r?$/m) || [])[1] || "").trim();
+    const deps = ((block.match(/\*\*Depends on:\*\*\s*(.+?)\r?$/m) || [])[1] || "").trim();
+    const why = ((block.match(/\*\*Why:\*\*\s*([\s\S]+?)(?=\r?\n\*\*|\r?\n##|$)/) || [])[1] || "").trim().replace(/\s+/g, " ");
+    const acBlock = (block.match(/\*\*Acceptance Criteria:\*\*\s*([\s\S]+?)(?=\r?\n\*\*|\r?\n##|$)/) || [])[1] || "";
+    const acCount = (acBlock.match(/^[-*]\s+/gm) || []).length;
+    const validationBlock = (block.match(/\*\*Validation:\*\*[^\n]*\n([\s\S]+?)(?=\r?\n\*\*|\r?\n##|$)/) || [])[1] || "";
+    const validationCount = (validationBlock.match(/^[-*]\s+/gm) || []).length;
+    return {
+      num: titleMatch ? parseInt(titleMatch[1]) : 0,
+      title: titleMatch ? titleMatch[2].trim() : "",
+      wave,
+      persona: (() => {
+        // Strip placeholder syntax ({...}), then only accept the known set
+        const cleaned = persona.replace(/[{}]/g, "").trim().toLowerCase();
+        const valid = ["security", "architect", "ux", "frontend", "backend", "performance"];
+        return valid.includes(cleaned) ? cleaned : "";
+      })(),
+      deps,
+      why,
+      acCount,
+      validationCount,
+    };
+  });
+
+  const contractCount = (content.match(/^### Contract for Task \d+/gm) || []).length;
+  const totalWaves = tasks.length > 0 ? Math.max(...tasks.map((t) => t.wave)) : 0;
+
+  // ─ Render ─
+  console.log("");
+  console.log(`  ${TEAL}${BOLD}▣${RESET} ${WHITE}${BOLD}PLAN${RESET} ${DIM}▸${RESET} ${WHITE}Phase ${phaseNum} — ${phaseTitle}${RESET}`);
+  console.log(`  ${RULE_DIM}`);
+  if (phaseGoal) {
+    console.log(`  ${DIM}Goal${RESET}      ${WHITE}${phaseGoal}${RESET}`);
+  }
+  if (whyPhase) {
+    console.log(`  ${DIM}Why${RESET}       ${WHITE}${whyPhase}${RESET}`);
+  }
+  console.log(`  ${DIM}Shape${RESET}     ${TEAL}${tasks.length}${RESET} ${DIM}tasks${RESET} ${DIM}·${RESET} ${TEAL}${totalWaves}${RESET} ${DIM}waves${RESET} ${DIM}·${RESET} ${TEAL}${contractCount}${RESET} ${DIM}contracts${RESET}`);
+  console.log(`  ${RULE_DIM}`);
+
+  // Persona palette
+  const personaColors = {
+    security: RED,
+    architect: BLUE,
+    ux: "\x1b[38;2;255;182;193m",
+    frontend: TEAL,
+    backend: "\x1b[38;2;186;85;211m",
+    performance: YELLOW,
+  };
+
+  for (let w = 1; w <= totalWaves; w++) {
+    const waveTasks = tasks.filter((t) => t.wave === w);
+    if (!waveTasks.length) continue;
+    console.log("");
+    console.log(`  ${TEAL}»${RESET} ${WHITE}${BOLD}Wave ${w}${RESET} ${DIM}(${waveTasks.length} ${waveTasks.length === 1 ? "task" : "tasks"}, parallel)${RESET}`);
+    for (const t of waveTasks) {
+      const personaChip = t.persona
+        ? ` ${(personaColors[t.persona] || DIM)}[${t.persona}]${RESET}`
+        : "";
+      // Only show the dep chip if it names a real task reference.
+      // Suppress blanks, "none", and template placeholders like "{none | Task N}".
+      const depsClean = (t.deps || "").trim();
+      const depsIsReal =
+        depsClean &&
+        !/^none$/i.test(depsClean) &&
+        !/[{}]/.test(depsClean);
+      const depChip = depsIsReal ? ` ${DIM}← ${depsClean}${RESET}` : "";
+      console.log(`    ${DIM}${t.num}.${RESET} ${WHITE}${t.title}${RESET}${personaChip}${depChip}`);
+      // Suppress placeholder Why text (contains {} braces) to keep the
+      // dashboard clean when the planner hasn't filled it in yet.
+      if (t.why && !/[{}]/.test(t.why)) {
+        const shortWhy = t.why.length > 90 ? t.why.slice(0, 87) + "…" : t.why;
+        console.log(`       ${DIM}${shortWhy}${RESET}`);
+      }
+      const metrics = [];
+      if (t.acCount > 0) metrics.push(`${TEAL}${t.acCount}${RESET} ${DIM}AC${RESET}`);
+      if (t.validationCount > 0) metrics.push(`${TEAL}${t.validationCount}${RESET} ${DIM}checks${RESET}`);
+      if (metrics.length) {
+        console.log(`       ${metrics.join(` ${DIM}·${RESET} `)}`);
+      }
+    }
+  }
+  console.log("");
+  console.log(`  ${RULE_DIM}`);
+}
+
 function cmdUpdate(current, latest) {
   if (!current || !latest) return;
   console.log("");
@@ -291,9 +554,12 @@ switch (cmd) {
   case "next":     cmdNext(rest.join(" ")); break;
   case "end":      cmdEnd(rest[0], rest.slice(1).join(" ")); break;
   case "update":   cmdUpdate(rest[0], rest[1]); break;
+  case "plan-summary": cmdPlanSummary(rest[0]); break;
+  case "journey-tree": cmdJourneyTree(rest[0]); break;
+  case "milestone-complete": cmdMilestoneComplete(rest[0], rest[1], rest.slice(2).join(" ")); break;
   default:
     console.error(
-      `Usage: qualia-ui.js <banner|context|divider|ok|fail|warn|info|spawn|wave|task|done|next|end|update> [args]`
+      `Usage: qualia-ui.js <banner|context|divider|ok|fail|warn|info|spawn|wave|task|done|next|end|update|plan-summary|journey-tree|milestone-complete> [args]`
     );
     process.exit(1);
 }