qualia-framework 3.4.0 → 4.0.0

package/skills/qualia-plan/SKILL.md

@@ -13,6 +13,7 @@ Spawn a planner agent to break the current phase into executable tasks, then val
 `/qualia-plan {N}` — plan specific phase N
 `/qualia-plan {N} --gaps` — plan fixes for verification failures
 `/qualia-plan {N} --skip-check` — skip the plan-checker validation loop (not recommended)
+`/qualia-plan {N} --auto` — plan + auto-chain into `/qualia-build {N} --auto` when done (no human approval between plan and build)
 
 ## Process
 
@@ -153,16 +154,10 @@ Show the remaining issues. Ask:
 
 ### 5. Present Final Plan
 
-```bash
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js ok "Plan ready: {count} tasks across {count} waves"
-```
+Render the story-file dashboard — this is a single command that parses the plan and shows the phase goal, waves, tasks, personas, dependencies, acceptance-criteria counts, and validation counts:
 
-For each wave:
 ```bash
-node ~/.claude/bin/qualia-ui.js wave {wave_num} {wave_total} {task_count}
-node ~/.claude/bin/qualia-ui.js task 1 "{task title}"
-node ~/.claude/bin/qualia-ui.js task 2 "{task title}"
+node ~/.claude/bin/qualia-ui.js plan-summary .planning/phase-{N}-plan.md
 ```
 
 End with plain text: *"Approve? (yes / adjust)"*
@@ -177,7 +172,17 @@ node ~/.claude/bin/state.js transition --to planned --phase {N}
 
 If state.js returns an error, show it and stop. Do NOT manually edit STATE.md or tracking.json.
 
-### 7. Route
+### 7. Route (auto-chain aware)
+
+**If invoked with `--auto`:** immediately invoke `/qualia-build {N} --auto` inline. The user already approved the whole journey at `/qualia-new` time — no additional approval needed per phase plan.
+
+```bash
+node ~/.claude/bin/qualia-ui.js info "Auto mode — chaining into /qualia-build {N}"
+```
+
+Then invoke the `qualia-build` skill inline with `--auto`.
+
+**Otherwise (guided mode):** stop and show the next step:
 
 ```bash
 node ~/.claude/bin/qualia-ui.js end "PHASE {N} PLANNED" "/qualia-build {N}"

package/skills/qualia-quick/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-quick
-description: "Fast path for small tasks — bug fixes, tweaks, hot fixes. Skips full phase planning."
+description: "Fast path for small tasks — bug fixes, tweaks, hot fixes. Skips full phase planning. Trigger on 'quick fix', 'small change', 'tweak', 'hot fix', 'one-line fix', 'quick edit', 'small bug'."
 ---
 
 # /qualia-quick — Quick Task

package/skills/qualia-report/SKILL.md

@@ -92,6 +92,9 @@ SUBMITTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 # Only upload if ERP is enabled
 if [ "$ERP_ENABLED" = "true" ]; then
   # Build structured JSON payload from tracking.json (matches ERP contract /api/v1/reports)
+  # v4: include milestone_name, milestones[], team_id, project_id, git_remote,
+  # session_started_at, last_pushed_at, build_count, deploy_count — the ERP
+  # uses these to render the project tree (milestone → phases → unphased) correctly.
   PAYLOAD=$(node -e "
     const fs = require('fs');
     const t = JSON.parse(fs.readFileSync('.planning/tracking.json', 'utf8'));
@@ -104,8 +107,13 @@ if [ "$ERP_ENABLED" = "true" ]; then
     } catch {}
     console.log(JSON.stringify({
       project: t.project || require('path').basename(process.cwd()),
+      project_id: t.project_id || '',
+      team_id: t.team_id || '',
+      git_remote: t.git_remote || '',
       client: t.client || '',
       milestone: t.milestone || 1,
+      milestone_name: t.milestone_name || '',
+      milestones: Array.isArray(t.milestones) ? t.milestones : [],
       phase: t.phase,
       phase_name: t.phase_name,
       total_phases: t.total_phases,
@@ -114,7 +122,11 @@ if [ "$ERP_ENABLED" = "true" ]; then
       tasks_total: t.tasks_total || 0,
       verification: t.verification || 'pending',
       gap_cycles: (t.gap_cycles || {})[String(t.phase)] || 0,
+      build_count: t.build_count || 0,
+      deploy_count: t.deploy_count || 0,
       deployed_url: t.deployed_url || '',
+      session_started_at: t.session_started_at || '',
+      last_pushed_at: t.last_pushed_at || '',
       lifetime: t.lifetime || {},
       commits: commits,
       notes: notes,

package/skills/qualia-verify/SKILL.md

@@ -10,6 +10,7 @@ Spawn a verifier agent to check if the phase goal was achieved. Does NOT trust b
 ## Usage
 `/qualia-verify` — verify the 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
 
 ## Process
 
@@ -31,7 +32,7 @@ node ~/.claude/bin/qualia-ui.js spawn verifier "Goal-backward check..."
 
 ```
 Agent(prompt="
-Read your role: @agents/verifier.md
+Read your role: @~/.claude/agents/verifier.md
 
 Phase plan with success criteria AND verification contracts:
 @.planning/phase-{N}-plan.md
@@ -56,7 +57,7 @@ If frontend:
 
 ```
 Agent(prompt="
-Read your role: @agents/qa-browser.md
+Read your role: @~/.claude/agents/qa-browser.md
 
 Phase plan: @.planning/phase-{N}-plan.md
 Existing verification: @.planning/phase-{N}-verification.md
@@ -99,11 +100,64 @@ 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: state.js auto-advances to the next phase.
-If FAIL and gap_cycles >= 2: state.js returns GAP_CYCLE_LIMIT — tell the employee to escalate.
-If FAIL and gap_cycles < 2: proceed to `/qualia-plan {N} --gaps`.
+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.
 
+After state transition, capture the 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
+```
+
+### 4b. Route (auto-chain aware)
+
+**In `--auto` mode**, the router decides the next step based on verify 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 |
+
+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
+```
+
+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:
+
+```bash
+node ~/.claude/bin/qualia-ui.js fail "Phase {N} has 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)"
+```
+
+**Default (guided mode)** behavior is unchanged — show the next command and stop:
+
+```bash
+# PASS
+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:

package/templates/help.html

@@ -37,6 +37,22 @@
     -webkit-font-smoothing: antialiased;
   }
 
+  /* ─── Version Pill (top-right) ───────────── */
+  .version-pill {
+    position: fixed;
+    top: 1rem;
+    right: 1rem;
+    z-index: 10;
+    padding: 0.3rem 0.75rem;
+    background: var(--bg-card);
+    border: 1px solid var(--border);
+    border-radius: 999px;
+    font-family: var(--font-mono);
+    font-size: 0.7rem;
+    color: var(--teal);
+    letter-spacing: 0.04em;
+  }
+
   /* ─── Header ─────────────────────────────── */
   .header {
     padding: clamp(2rem, 6vw, 4rem) clamp(1.5rem, 5vw, 4rem);
@@ -134,6 +150,12 @@
     color: var(--text-subtle);
     margin-bottom: 0.75rem;
   }
+  .cmd-group-note {
+    font-size: 0.78rem;
+    color: var(--text-subtle);
+    margin: -0.5rem 0 0.75rem 0;
+    font-style: italic;
+  }
   .cmd {
     display: flex;
     gap: 1rem;
@@ -150,7 +172,7 @@
     font-size: 0.85rem;
     color: var(--teal);
     white-space: nowrap;
-    min-width: 160px;
+    min-width: 200px;
   }
   .cmd-desc {
     font-size: 0.85rem;
@@ -244,6 +266,14 @@
     color: var(--text-subtle);
   }
   .footer strong { color: var(--teal); font-weight: 500; }
+  .footer-version {
+    display: block;
+    margin-top: 0.5rem;
+    font-family: var(--font-mono);
+    font-size: 0.7rem;
+    color: var(--text-subtle);
+    letter-spacing: 0.04em;
+  }
 
   /* ─── Responsive ─────────────────────────── */
   @media (max-width: 640px) {
@@ -251,6 +281,7 @@
     .cmd-name { min-width: unset; }
     .road { flex-direction: column; align-items: flex-start; }
     .road-arrow { display: none; }
+    .version-pill { top: 0.5rem; right: 0.5rem; font-size: 0.65rem; }
   }
 
   @media (prefers-reduced-motion: reduce) {
@@ -260,11 +291,13 @@
 </head>
 <body>
 
+<div class="version-pill">v3.6.0</div>
+
 <div class="header">
   <div class="header-content">
     <h1><span>Qualia</span> Framework</h1>
     <p>Plan, build, verify, ship. The AI-powered workflow for Qualia Solutions.</p>
-    <div class="version">v{{VERSION}}</div>
+    <div class="version">v3.6.0 &middot; 26 skills</div>
   </div>
 </div>
 
@@ -293,73 +326,106 @@
     </div>
   </section>
 
-  <!-- Commands -->
+  <!-- Skills -->
   <section>
-    <h2>Commands</h2>
+    <h2>Skills (26)</h2>
 
+    <!-- Road (core flow) -->
     <div class="cmd-group">
-      <h3>Navigation</h3>
+      <h3>Road &mdash; Core Flow</h3>
+      <p class="cmd-group-note">The seven steps every project walks through.</p>
+      <div class="commands">
+        <div class="cmd"><span class="cmd-name">/qualia-new</span><span class="cmd-desc">Set up a new project from scratch &mdash; deep questioning, parallel research, REQUIREMENTS.md, ROADMAP.md, approval gate. Use when starting any new client project.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-plan</span><span class="cmd-desc">Plan the current phase &mdash; spawns planner, validates with plan-checker in a revision loop (max 3), optionally runs discuss/research first. Use when ready to plan a phase.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-build</span><span class="cmd-desc">Execute the current phase &mdash; spawns builder subagents per task with wave-based parallelization. Fresh context per task.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-verify</span><span class="cmd-desc">Goal-backward verification &mdash; checks if the phase ACTUALLY works, not just if tasks completed. Spawns verifier agent.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-polish</span><span class="cmd-desc">Design and UX pass &mdash; anti-AI-slop, genuine craft, responsive, accessible. Run after all phases are verified.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-ship</span><span class="cmd-desc">Deploy to production &mdash; quality gates, commit, push, deploy, verify. Use when ready to go live.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-handoff</span><span class="cmd-desc">Client delivery &mdash; credentials, handover doc, final update. Use after shipping.</span></div>
+      </div>
+    </div>
+
+    <!-- Phase Depth (optional) -->
+    <div class="cmd-group">
+      <h3>Phase Depth &mdash; Optional</h3>
+      <p class="cmd-group-note">Used before / around /qualia-plan when a phase needs deeper context.</p>
       <div class="commands">
-        <div class="cmd"><span class="cmd-name">/qualia</span><span class="cmd-desc">What should I do next? Reads project state, tells you the exact command.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-idk</span><span class="cmd-desc">Same as /qualia. For when you're stuck.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-resume</span><span class="cmd-desc">Pick up where you left off from a previous session.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-pause</span><span class="cmd-desc">Save progress. Creates .continue-here.md for next session.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-discuss</span><span class="cmd-desc">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.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-research</span><span class="cmd-desc">Deep-research a niche domain or library BEFORE planning a specific phase. Spawns the researcher agent with Context7/WebFetch access. Writes to .planning/phase-{N}-research.md.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-map</span><span class="cmd-desc">Map an existing codebase to infer architecture, stack, conventions, and what's already built. For brownfield projects &mdash; run BEFORE /qualia-new so Validated requirements get inferred from existing code.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-milestone</span><span class="cmd-desc">Close out a completed milestone and prep the next one. Archives the current milestone's artifacts, updates REQUIREMENTS.md to mark v1 requirements Complete, and creates the next milestone roadmap.</span></div>
       </div>
     </div>
 
+    <!-- Quality -->
     <div class="cmd-group">
-      <h3>Project Setup</h3>
+      <h3>Quality</h3>
+      <p class="cmd-group-note">Diagnose, audit, optimize, polish, test.</p>
       <div class="commands">
-        <div class="cmd"><span class="cmd-name">/qualia-new</span><span class="cmd-desc">Interactive wizard. Asks about client, scope, design, stack. Creates everything.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-debug</span><span class="cmd-desc">Structured debugging &mdash; symptom gathering, diagnosis confirmation, root cause analysis. Trigger on 'debug', 'find bug', 'fix error', 'something is broken'.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-review</span><span class="cmd-desc">Production audit with scored diagnostics. Runs real commands, scores findings by severity. Trigger on 'review', 'audit', 'code review', 'security check'.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-optimize</span><span class="cmd-desc">Deep optimization pass &mdash; reads .planning/ AND codebase to find performance, design, UI, backend, and frontend issues. Spawns parallel specialist agents. Supports --perf, --ui, --backend, --alignment, --fix flags.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-polish</span><span class="cmd-desc">Design and UX pass &mdash; anti-AI-slop, genuine craft, responsive, accessible. Run after all phases are verified.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-test</span><span class="cmd-desc">Generate or run tests for client projects. Trigger on 'write tests', 'add tests', 'test this', 'test coverage'.</span></div>
       </div>
     </div>
 
+    <!-- Quick Paths -->
     <div class="cmd-group">
-      <h3>Build Loop</h3>
+      <h3>Quick Paths</h3>
+      <p class="cmd-group-note">Lightweight alternatives when the full road is overkill.</p>
       <div class="commands">
-        <div class="cmd"><span class="cmd-name">/qualia-plan</span><span class="cmd-desc">Plan the current phase. AI generates tasks with success criteria.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-build</span><span class="cmd-desc">Build it. Fresh AI agent per task, parallel waves.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-verify</span><span class="cmd-desc">Verify it actually works. Greps code, scores on 4 dimensions.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-quick</span><span class="cmd-desc">Fast path for small tasks &mdash; bug fixes, tweaks, hot fixes. Skips full phase planning.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-task</span><span class="cmd-desc">Build a single task &mdash; more structured than /qualia-quick, lighter than /qualia-build. Spawns a fresh builder agent for one focused task.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-design</span><span class="cmd-desc">One-shot design transformation &mdash; critiques, fixes, polishes, hardens, makes responsive. No reports, no choices, just makes it professional.</span></div>
       </div>
     </div>
 
+    <!-- Knowledge -->
     <div class="cmd-group">
-      <h3>Quick Work</h3>
+      <h3>Knowledge</h3>
+      <p class="cmd-group-note">Persist learnings and log work.</p>
       <div class="commands">
-        <div class="cmd"><span class="cmd-name">/qualia-quick</span><span class="cmd-desc">Skip planning. For bug fixes, tweaks, hot fixes under 1 hour.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-task</span><span class="cmd-desc">One focused task. More structured than quick, lighter than build.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-learn</span><span class="cmd-desc">Save a learning, pattern, fix, or client preference to the knowledge base. Persists across projects and sessions.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-report</span><span class="cmd-desc">Generate session report and commit to repo. Mandatory before clock-out.</span></div>
       </div>
     </div>
 
+    <!-- Session -->
     <div class="cmd-group">
-      <h3>Design & Quality</h3>
+      <h3>Session</h3>
+      <p class="cmd-group-note">Hand off and resume context cleanly.</p>
       <div class="commands">
-        <div class="cmd"><span class="cmd-name">/qualia-design</span><span class="cmd-desc">One-shot design fix. Reads DESIGN.md, kills AI slop, makes it professional.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-polish</span><span class="cmd-desc">Full design pass. Typography, color, states, motion, a11y, responsive, hardening.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-review</span><span class="cmd-desc">Production audit. Security, performance, reliability. Scored diagnostics.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-pause</span><span class="cmd-desc">Save session context for seamless handoff. Creates .continue-here.md so the next session picks up exactly where you left off.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-resume</span><span class="cmd-desc">Restore context from a previous session. Reads .continue-here.md or STATE.md, summarizes where you left off, routes to next action.</span></div>
       </div>
     </div>
 
+    <!-- Navigation -->
     <div class="cmd-group">
-      <h3>Ship & Deliver</h3>
+      <h3>Navigation</h3>
+      <p class="cmd-group-note">When you don't know what to do next.</p>
       <div class="commands">
-        <div class="cmd"><span class="cmd-name">/qualia-ship</span><span class="cmd-desc">Quality gates, commit, push, deploy to Vercel, post-deploy verification.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-handoff</span><span class="cmd-desc">Client delivery. Credentials, docs, handover package.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-report</span><span class="cmd-desc">Log your session. Mandatory before clock-out. Uploads to ERP.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia</span><span class="cmd-desc">Smart router &mdash; reads project state, classifies your situation, tells you the exact next command. Use whenever you're unsure about your next step.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-idk</span><span class="cmd-desc">Alias for /qualia. The smart router handles all 'idk', 'what now', 'I'm stuck' situations.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-help</span><span class="cmd-desc">Open the Qualia Framework reference guide in the browser. A beautiful themed HTML page with all commands, rules, services, and the road.</span></div>
       </div>
     </div>
 
+    <!-- Meta -->
     <div class="cmd-group">
-      <h3>Debugging & Learning</h3>
+      <h3>Meta</h3>
+      <p class="cmd-group-note">Extend the framework itself.</p>
       <div class="commands">
-        <div class="cmd"><span class="cmd-name">/qualia-debug</span><span class="cmd-desc">Structured debugging. Symptom &rarr; diagnosis &rarr; root cause &rarr; fix.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-learn</span><span class="cmd-desc">Save a pattern, fix, or client preference to the knowledge base.</span></div>
-        <div class="cmd"><span class="cmd-name">/qualia-test</span><span class="cmd-desc">Generate or run tests. Auto-detects framework.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-skill-new</span><span class="cmd-desc">Author a new Qualia skill or agent. Generates the SKILL.md, registers it in the right location, and optionally ships to the framework repo.</span></div>
       </div>
     </div>
+  </section>
 
+  <!-- CLI -->
+  <section>
+    <h2>CLI (Terminal)</h2>
     <div class="cmd-group">
-      <h3>CLI (Terminal)</h3>
       <div class="commands">
         <div class="cmd"><span class="cmd-name">qualia-framework install</span><span class="cmd-desc">Install or reinstall the framework.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework update</span><span class="cmd-desc">Update to the latest version.</span></div>
@@ -470,6 +536,7 @@
 <div class="footer">
   <strong>Welcome to the future with Qualia.</strong><br>
   Qualia Solutions &mdash; Nicosia, Cyprus
+  <span class="footer-version">qualia-framework v3.6.0 &middot; 26 skills</span>
 </div>
 
 </body>

package/templates/journey.md

@@ -0,0 +1,113 @@
+---
+project: "{Project Name}"
+total_milestones: {N}
+current_milestone: 1
+created: {date}
+---
+
+# {Project Name} — Journey
+
+The full arc from kickoff to client handoff. Every milestone. Every exit criterion.
+This file is the **North Star** — all planning downstream must stay architecturally
+consistent with it.
+
+## Mission
+
+{one-paragraph description of what this project delivers and for whom}
+
+## The Path ({N} milestones to handoff)
+
+```
+M1 ─── M2 ─── M3 ─── ... ─── M{N} (Handoff)
+│
+└── [CURRENT]
+```
+
+---
+
+## Milestone 1 · {Name}     [CURRENT]
+
+**Why now:** {one-sentence reason this is the first release — what foundation it lays}
+
+**Exit criteria** (what "shipped" means for M1):
+- {observable outcome 1}
+- {observable outcome 2}
+- {observable outcome 3}
+
+**Phases:**
+1. **{Phase Name}** — {one-line goal}
+2. **{Phase Name}** — {one-line goal}
+3. **{Phase Name}** — {one-line goal}
+
+**Requirements covered:** {REQ-IDs — e.g. AUTH-01, AUTH-02, CORE-01}
+
+**Research flags:** {any phases that may need deeper research during planning}
+
+---
+
+## Milestone 2 · {Name}
+
+**Why now:** {plain-language reason this follows M1}
+
+**Exit criteria:**
+- {observable outcome 1}
+- {observable outcome 2}
+
+**Phases:**
+1. **{Phase Name}** — {one-line goal}
+2. **{Phase Name}** — {one-line goal}
+3. **{Phase Name}** — {one-line goal}
+
+**Requirements covered:** {REQ-IDs}
+
+---
+
+## Milestone 3 · {Name}
+
+**Why now:** {reason}
+
+**Exit criteria:**
+- {outcome}
+- {outcome}
+
+**Phases:**
+1. **{Phase Name}** — {one-line goal}
+2. **{Phase Name}** — {one-line goal}
+
+**Requirements covered:** {REQ-IDs}
+
+---
+
+## Milestone {N} · Handoff     [FINAL]
+
+**Why now:** Production-ready for real users and client takeover.
+
+**Exit criteria:**
+- Deployed on production domain with HTTP 200 + auth flow verified
+- Client has credentials, runbook, and recorded walkthrough
+- `.planning/archive/` contains every milestone's verification reports
+- ERP `lifetime.milestones_completed` reflects this milestone
+
+**Phases (standard for every project):**
+1. **Polish** — design pass, responsive, accessibility, empty/error states
+2. **Content + SEO** — real copy, metadata, sitemap, robots, analytics
+3. **Final QA** — full-flow test, cross-browser, edge cases, `/qualia-review`
+4. **Handoff** — credentials doc, client walkthrough, domain transfer, support clause
+
+**Requirements covered:** {REQ-IDs — typically ops/quality/handoff categories}
+
+---
+
+## Rules for This Journey
+
+1. **Hard ceiling: 5 milestones.** If the project needs more, defer to a v2 release after handoff.
+2. **Hard floor: 2 milestones.** Anything smaller should use `/qualia-new --quick` instead.
+3. **The final milestone is always Handoff.** Same 4 phases every project. Never negotiable.
+4. **Milestones ≥ 2 phases OR are a shipped release gate.** A 1-phase milestone is a phase, not a milestone.
+5. **Numbering is contiguous.** No skipped milestone numbers.
+6. **Progressive detail is OK.** M1 is fully detailed (ready for `/qualia-plan`). M2..M{N-1} have phase names + one-line goals. Full phase detail gets written by roadmapper when the milestone opens.
+7. **Exit criteria are observable.** "User can do X" not "Feature Y works."
+
+---
+
+*Last updated: {date}*

package/templates/plan.md

@@ -7,36 +7,81 @@ waves: {count}
 
 # Phase {N}: {Name}
 
-Goal: {what must be true when done}
+**Goal:** {what must be TRUE when this phase is done}
+
+**Why this phase:** {one sentence — what this unlocks for the user or the product}
+
+---
 
 ## Task 1 — {title}
+
 **Wave:** 1
-**Files:** {files to create or modify}
-**Action:** {exactly what to build}
+**Persona:** {optional: security | architect | ux | frontend | backend | performance | none}
+**Files:** {specific absolute paths — e.g. `src/lib/auth.ts`, `src/app/login/page.tsx`}
+**Depends on:** {task numbers (e.g. "Task 0"), or "none"}
+
+**Why:**
+{one-sentence rationale — what problem this solves, what would break without it. Not "implement auth" but "Session persistence is the #1 abandonment trigger in onboarding — verification emails are wasted without it."}
+
+**Acceptance Criteria:**
+- {observable user-facing behavior 1}
+- {observable user-facing behavior 2}
+- {observable user-facing behavior 3}
+
+**Action:**
+{concrete steps the builder follows — specific function names, imports, patterns. Not "add auth" but "Add `signInWithPassword()` call in `handleSubmit`, validate email with Zod schema, redirect to `/dashboard` on success."}
+
+**Validation:** (builder self-check before commit)
+- `{exact command 1}` → expected output
+- `{exact command 2}` → expected output
+
 **Context:** Read @{file references}
-**Done when:** {observable, testable criterion}
+
+---
 
 ## Task 2 — {title}
+
 **Wave:** 1
+**Persona:** {optional}
 **Files:** {files}
-**Action:** {what to build}
-**Done when:** {criterion}
+**Depends on:** {none | Task N}
+
+**Why:**
+{one-sentence rationale}
+
+**Acceptance Criteria:**
+- {user-facing behavior}
+
+**Action:**
+{steps}
+
+**Validation:**
+- `{command}` → expected
+
+**Context:** Read @{files}
+
+---
 
 ## Success Criteria
+
+Phase-level truths — what must be observable when this phase is done.
+
 - [ ] {truth 1 — what the user can do}
 - [ ] {truth 2}
 - [ ] {truth 3}
 
 ## Verification Contract
 
+Machine-executable checks the verifier runs verbatim. One per task minimum.
+
 ### Contract for Task 1 — {title}
 **Check type:** {file-exists | grep-match | command-exit | behavioral}
-**Command:** `{exact command the verifier will run}`
-**Expected:** {what the output should be}
-**Fail if:** {what constitutes failure}
+**Command:** `{exact command}`
+**Expected:** {output}
+**Fail if:** {failure condition}
 
 ### Contract for Task 2 — {title}
-**Check type:** {file-exists | grep-match | command-exit | behavioral}
+**Check type:** {type}
 **Command:** `{exact command}`
-**Expected:** {expected output}
+**Expected:** {output}
 **Fail if:** {failure condition}