qualia-framework 3.4.0 → 4.0.0

package/README.md

@@ -1,10 +1,10 @@
-# Qualia Framework v3
+# Qualia Framework v4
 
 A harness engineering framework for [Claude Code](https://claude.ai/code). It installs into `~/.claude/` and wraps your AI-assisted development workflow with structured planning, execution, verification, and deployment gates.
 
-It is not an application framework like Rails or Next.js. It doesn't generate code, run servers, or process data. It's an opinionated workflow layer that tells Claude how to plan, build, and verify your projects.
+It is not an application framework like Rails or Next.js. It doesn't generate code, run servers, or process data. It's an opinionated workflow layer that tells Claude how to plan, build, and verify your projects — end-to-end, from "tell me what you want to make" to "here's the handoff doc for your client."
 
-v3 applies lessons from Anthropic's ["Harness Design for Long-Running Apps"](https://www.anthropic.com/engineering/harness-design-long-running-apps) article: scored evaluator rubrics, verification contracts, smarter guards, hook telemetry, and dynamic team management.
+**v4 is the Full Journey release.** `/qualia-new` now maps the entire project arc from kickoff to client handoff upfront (all milestones, not just v1), and the Road can chain itself end-to-end in `--auto` mode with only two human gates per project. Story-file plan format, goal-backward verification, and the 4-dimension scoring rubric from v3 all carry forward.
 
 ## Install
 
@@ -26,68 +26,100 @@ npx qualia-framework traces     # View recent hook telemetry
 
 ## Usage
 
-Open Claude Code in any project directory:
+Open Claude Code in any project directory.
 
-### The Road (main flow)
+### The Road — guided mode (default)
 
 ```
-/qualia-new       # Set up a new project (deep questioning + research + roadmap)
-/qualia-plan N    # Plan phase N (with plan-checker validation loop)
-/qualia-build N   # Build phase N (wave-based parallel tasks)
-/qualia-verify N  # Verify phase N works (goal-backward + QA browser)
+/qualia-new         # Set up a project: questioning + research + JOURNEY.md with all milestones → Handoff
+/qualia-plan N      # Plan phase N of the current milestone (story-file format, plan-checker validation loop)
+/qualia-build N     # Build phase N (builder subagents with pre-inlined context, wave-based parallel tasks)
+/qualia-verify N    # Verify phase N works (goal-backward + per-task acceptance criteria + browser QA)
 ...repeat plan/build/verify per phase...
-/qualia-polish    # Design and UX pass
-/qualia-ship      # Deploy to production
-/qualia-handoff   # Deliver to client
+/qualia-milestone   # Close current milestone, open next (loads next scope from JOURNEY.md)
+...repeat per milestone until the final "Handoff" milestone...
+/qualia-polish      # Design and UX pass (first phase of the Handoff milestone)
+/qualia-ship        # Deploy to production
+/qualia-handoff     # Enforce the 4 mandatory handoff deliverables
+/qualia-report      # Mandatory end-of-session report + ERP upload
 ```
 
+### The Road — auto mode
+
+```
+/qualia-new --auto
+```
+
+Research runs automatically. User approves the full journey once. Framework chains plan → build → verify → (next phase) → ... → milestone boundary. User approves continuation per milestone. Framework resumes, eventually reaches the Handoff milestone's last phase → ship → handoff → report. Done.
+
+Two human gates per project. One halt case (gap-cycle limit exceeded on a failing phase).
+
 ### Phase-specific depth (optional)
 
 ```
-/qualia-discuss N   # Capture decisions before planning a complex phase
+/qualia-discuss N   # Capture decisions before planning a complex phase (locks constraints for the planner)
 /qualia-research N  # Deep-research a niche phase (Context7/WebFetch/WebSearch)
-/qualia-map         # Map existing codebase (brownfield projects)
-/qualia-milestone   # Close current milestone, open next
+/qualia-map         # Map existing codebase (brownfield projects — run before /qualia-new)
 ```
 
 ### Navigation & state
 
 ```
-/qualia           # What should I do next? (smart router)
-/qualia-idk       # I'm stuck — smart advisor
+/qualia           # Mechanical state router — "what's my next command?"
+/qualia-idk       # Diagnostic — "what's actually going on?" Two isolated scans (planning / codebase), then a plain-language explanation
 /qualia-pause     # Save session, continue later
 /qualia-resume    # Pick up where you left off
 ```
 
-### Quality & debug
+### Quality & shortcuts
 
 ```
 /qualia-debug     # Structured debugging
 /qualia-design    # One-shot design transformation
-/qualia-review    # Production audit
-/qualia-optimize  # Deep optimization pass
-/qualia-quick     # Skip planning, just do it
-/qualia-task      # Build one thing properly
+/qualia-review    # Production audit (scored diagnostics)
+/qualia-optimize  # Deep optimization pass (parallel specialist agents)
+/qualia-quick     # Fast path for trivial fixes (skips planning)
+/qualia-task      # Build one thing properly (fresh builder, atomic commit, no phase plan)
 /qualia-test      # Generate or run tests
 ```
 
-### Knowledge & reporting
+### Knowledge & meta
 
 ```
-/qualia-learn     # Save a pattern, fix, or client pref
-/qualia-report    # Log your work (mandatory end of day)
+/qualia-learn     # Save a pattern, fix, or client pref to ~/.claude/knowledge/
+/qualia-skill-new # Author a new Qualia skill or agent
 /qualia-help      # Open the framework reference in your browser
 ```
 
 See `guide.md` for the full developer guide.
 
-## What's Inside (v3.3.0)
+## The Full Journey (v4)
+
+Every v4 project has a `.planning/JOURNEY.md` — the North Star document that maps the entire arc from kickoff to client handoff.
+
+```
+Project
+└─ Journey (all milestones defined upfront)
+   └─ 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)
+```
 
-- **26 skills** — slash commands from setup to handoff, plus debugging, design, review, knowledge, session management, skill authoring, and the new deep-flow additions (discuss, research, map, milestone)
-- **8 agents** — planner, builder, verifier, qa-browser, researcher, research-synthesizer, roadmapper, plan-checker (each in fresh context)
-- **7 hooks** — session start, branch guard, pre-push tracking sync, migration guard, deploy gate, pre-compact state save, auto-update (all Node.js — cross-platform)
-- **5 rules** — security, frontend, design-reference, deployment, infrastructure
-- **12+ templates** — project.md, plan.md, state.md, DESIGN.md, tracking.json, requirements.md, roadmap.md, phase-context.md, 4× research-project templates, 4× project-type templates
+**Hard rules:**
+- Hard floor: 2 milestones. Hard ceiling: 5.
+- Final milestone is **always literally named "Handoff"** with 4 fixed phases (Polish, Content + SEO, Final QA, Handoff).
+- Every non-Handoff milestone needs **≥ 2 phases** (enforced by `state.js close-milestone`).
+- Milestone numbering is contiguous.
+
+**Why it matters:** non-technical team members can follow the ladder from any entry point. `/qualia` and `/qualia-milestone` render JOURNEY.md as a visual ladder with current position highlighted.
+
+## What's Inside (v4.0.0)
+
+- **26 skills** — from setup to handoff, plus debug, design, review, optimize, diagnostic (`qualia-idk`), session management, skill authoring, per-phase depth (discuss, research, map), and full-journey additions (`--auto` chaining, milestone closure)
+- **8 agents** (each runs in fresh context): planner, builder, verifier, qa-browser, researcher, research-synthesizer, roadmapper, plan-checker
+- **7 hooks** (pure Node.js, cross-platform): session-start, branch-guard, pre-push tracking sync, migration-guard, pre-deploy-gate, pre-compact state save, auto-update
+- **5 rules**: security, frontend, design-reference, deployment, infrastructure
+- **19 template files**: project.md, **journey.md** (new in v4), plan.md (story-file format), state.md, DESIGN.md, tracking.json (now with `milestone_name` + `milestones[]`), requirements.md (multi-milestone), roadmap.md (current milestone only), phase-context.md, 4 project-type templates (website, ai-agent, voice-agent, mobile-app), 5 research-project templates (STACK, FEATURES, ARCHITECTURE, PITFALLS, SUMMARY), help.html
 - **1 reference** — questioning.md methodology for deep project initialization
 
 ## Supported Platforms
@@ -100,35 +132,47 @@ Works on **Windows 10/11, macOS, and Linux**. Requires Node.js 18+ and Claude Co
 
 ## Why It Works
 
+### Full Journey (v4)
+
+`/qualia-new` maps every milestone from kickoff to handoff. Team members see the entire ladder before climbing. No improvising the next chunk after each ship. The final milestone is always "Handoff" with 4 mandatory deliverables (verified production URL, updated docs, archived client assets, final ERP report) — so the path to "shipped" is visible from day 1.
+
+### Auto-Chain End-to-End
+
+`--auto` mode chains `/qualia-plan → /qualia-build → /qualia-verify → …` without re-typing commands. The framework pauses only at real decisions: journey approval at kickoff, each milestone boundary, and one halt on gap-cycle-limit failures. Everything in between runs on rails.
+
 ### Goal-Backward Verification
 
-Most CI checks "did the task run." Qualia checks "does the outcome actually work." The verifier scores on 4 dimensions (Correctness, Completeness, Wiring, Quality), each 1-5, with a hard threshold at 3. It doesn't trust summaries — it greps the codebase for stubs, placeholders, unwired imports. The planner generates verification contracts (testable commands) that the verifier executes before ad-hoc checks.
+Most CI checks "did the task run." Qualia checks "does the outcome actually work." The verifier scores on 4 dimensions (Correctness, Completeness, Wiring, Quality), each 1–5, with a hard threshold at 3. It doesn't trust summaries — it greps the codebase for stubs, placeholders, unwired imports, and walks each task's observable Acceptance Criteria.
+
+### Story-File Plans (Plans Are Prompts)
+
+Plan files aren't documents that get translated into prompts — they ARE the prompts. Every task carries inline `Why` (rationale), `Acceptance Criteria` (observable user behaviors), `Depends on` (explicit ordering), and `Validation` (self-check commands) before the builder touches code. `@file` references tell the orchestrator what to pre-inline into the builder's prompt, saving 3-5 orientation Read calls per task.
 
 ### Agent Separation
 
-Splitting planner, builder, and verifier into separate agents with separate contexts prevents the "God prompt" problem where one massive context tries to plan AND code AND test. Each agent gets fresh context. This directly addresses Claude's quality degradation curve — task 50 gets the same quality as task 1.
+Splitting planner, builder, and verifier into separate agents with separate contexts prevents the "God prompt" problem. Each agent gets fresh context. Task 50 gets the same quality as task 1.
 
 ### Production-Grade Hooks
 
-All 8 hooks are real ops engineering, not theoretical. Highlights:
+All 7 hooks are real ops engineering, not theoretical:
 
 - **Pre-deploy gate** — TypeScript, lint, tests, build, and `service_role` leak scan before `vercel --prod`
-- **Branch guard** — Role-aware: owner can push to main, employees can't
-- **Migration guard** — Catches `DROP TABLE` without `IF EXISTS`, `DELETE` without `WHERE`, `CREATE TABLE` without RLS
-- **Env block** — Prevents Claude from touching `.env` files
+- **Branch guard** — Role-aware: owner can push to main, employees can't (parses refspec so `feature/x:main` bypass is blocked)
+- **Migration guard** — Catches `DROP TABLE` without `IF EXISTS`, `DELETE`/`UPDATE` without `WHERE`, `CREATE TABLE` without RLS, `GRANT ... TO PUBLIC`, `ALTER TABLE ... DROP COLUMN`
+- **Pre-push** — Stamps tracking.json via a bot commit so the ERP always sees fresh data
 - **Pre-compact** — Saves state before context compression
 
 ### Enforced State Machine
 
-Every workflow step calls `state.js` — a Node.js state machine that validates preconditions (including plan content), updates both STATE.md and tracking.json atomically, and tracks gap-closure cycles. The gap-closure limit is configurable per project (default: 2). A `--force` flag enables recovery after failed builds.
+Every workflow step calls `state.js` — a Node.js state machine that validates preconditions (including plan content), updates both STATE.md and tracking.json atomically, and tracks gap-closure cycles. v4 adds milestone readiness guards: `close-milestone` refuses to close a milestone with unverified phases or < 2 phases (unless `--force`), and appends a summary to `tracking.json.milestones[]` so the ERP renders a clean project tree.
 
 ### Wave-Based Parallelization
 
 Plans are grouped into waves for parallel execution. No fancy DAG solver — the planner assigns wave numbers, the orchestrator spawns agents per wave. Pragmatic over clever.
 
-### Plans Are Prompts
+### Diagnostic Intelligence
 
-Plan files aren't documents that get translated into prompts — they ARE the prompts. `@file` references, explicit task actions, and verification criteria baked in. This eliminates translation loss between "what we planned" and "what Claude actually reads."
+`/qualia-idk` is a real diagnostician (not a router alias). When the user's confusion is about *understanding the situation*, it spawns two isolated scans in parallel — one reads only `.planning/`, the other reads only source code — then synthesizes a plain-language "What I see / What I think is happening / What to do next" diagnosis. Catches plan↔code drift that a state-only router can't see.
 
 ## Architecture
 
@@ -137,23 +181,24 @@ npx qualia-framework install
      |
      v
 ~/.claude/
-  ├── skills/          19 slash commands
-  ├── agents/          planner.md, builder.md, verifier.md, qa-browser.md
-  ├── hooks/           8 Node.js hooks — cross-platform (no bash dependency)
-  ├── bin/             state.js (state machine) + qualia-ui.js (cosmetics library)
-  ├── knowledge/       learned-patterns.md, common-fixes.md, client-prefs.md (loaded by plan/debug/new)
-  ├── rules/           security.md, frontend.md, design-reference.md, deployment.md
-  ├── qualia-templates/ tracking.json, state.md, project.md, plan.md, DESIGN.md
-  ├── CLAUDE.md        global instructions (role-configured per team member)
-  └── statusline.js    teal-branded 2-line status bar
+  ├── skills/             26 slash commands
+  ├── agents/             8 agent definitions (planner, builder, verifier, qa-browser, roadmapper, research-synthesizer, researcher, plan-checker)
+  ├── hooks/              7 Node.js hooks — cross-platform (no bash dependency)
+  ├── bin/                state.js (state machine) + qualia-ui.js (cosmetics, banners, journey-tree) + statusline.js
+  ├── knowledge/          learned-patterns.md, common-fixes.md, client-prefs.md
+  ├── rules/              security, frontend, design-reference, deployment, infrastructure
+  ├── qualia-templates/   project.md, journey.md, plan.md (story-file), state.md, DESIGN.md, tracking.json, requirements.md, roadmap.md, + projects/*.md + research-project/*.md + help.html
+  ├── qualia-references/  questioning.md (deep project initialization methodology)
+  ├── CLAUDE.md           global instructions (role-configured per team member)
+  └── (settings.json wired for hooks, statusline, spinner verbs, etc.)
 ```
 
 ## For Qualia Solutions Team
 
-Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel.
+Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: Retell AI, ElevenLabs, Telnyx. AI: OpenRouter. Compute: Railway (agents/background jobs).
 
 ## Changelog
 
-See [CHANGELOG.md](./CHANGELOG.md) for the full version history.
+See [CHANGELOG.md](./CHANGELOG.md) for the full version history. v4.0.0 release notes are the most recent section.
 
 Built by [Qualia Solutions](https://qualiasolutions.net) — Nicosia, Cyprus.

package/agents/builder.md

@@ -16,29 +16,40 @@ Working code + atomic git commit.
 
 ## How to Execute
 
-### 1. Read Your Task
-Parse your task block:
-- **Files:** what to create or modify
-- **Action:** what to build
-- **Context:** read the `@file` references NOW before writing anything
-- **Done when:** the criterion you'll verify against
+### 1. Read Your Task (Story File)
+
+Parse every field in your task block:
+- **Wave / Depends on:** you should only be running when your dependencies are committed. If `Depends on: Task 1` and Task 1 isn't in git log, STOP and return `BLOCKED — waiting on Task N`.
+- **Persona (optional):** if set to `security`, weight security rules heavily. If `ux`, prioritize accessibility + states. If `frontend`, read `.planning/DESIGN.md`. Acts as a lens, not a separate brain.
+- **Files:** what to create or modify (scope boundary)
+- **Why:** internalize this. It's the rationale. If you can't explain why this task matters in one sentence after reading, re-read before coding.
+- **Acceptance Criteria:** the user-facing behaviors you must produce. You are done when these are true.
+- **Action:** the concrete steps. Follow them.
+- **Validation:** your self-check commands. Run these BEFORE `git commit`.
+- **Context:** read every `@file` reference NOW before writing anything.
 
 ### 2. Read Before Write
 For every file you're about to modify — read it first. No exceptions.
-For every `@file` reference in your context — read it now.
+For every `@file` reference in Context — read it now.
 
 ### 3. Build It
-- Follow the action exactly as specified
+- Follow the Action exactly as specified
+- Keep every Acceptance Criterion in mind — you are building toward observable user behaviors, not just files
 - MVP only — build what's asked, nothing extra
 - If the plan says "use library X" — use library X
 - If something in the plan seems wrong, flag it but still follow the plan
 
-### 4. Verify Your Work
-Before committing, check your "Done when" criterion:
-- Does the code actually do what the criterion says?
-- Run `npx tsc --noEmit` if you touched TypeScript files
-- No `// TODO`, no placeholder text, no stub functions
-- Imports are wired — not just declared but actually used
+### 4. Self-Verify Your Work
+
+Before committing:
+
+1. Run every command in **Validation:** — they must pass
+2. Mentally walk through each **Acceptance Criterion** — does the code actually produce that observable behavior?
+3. Run `npx tsc --noEmit` if you touched TypeScript files
+4. No `// TODO`, no placeholder text, no stub functions
+5. Imports are wired — not just declared but actually used
+
+If any Validation command fails or any AC is not met, fix before committing. Do not commit and hope the verifier catches it.
 
 ### 5. Commit
 One atomic commit per task:

package/agents/plan-checker.md

@@ -34,29 +34,42 @@ Plan must have YAML frontmatter with:
 
 **FAIL if:** frontmatter missing, incomplete, or `goal` differs from ROADMAP.md.
 
-### Rule 2: Every task has the 3 mandatory fields
+### Rule 2: Every task has the 6 mandatory story-file fields
 
-Each `## Task N — title` block must include:
-- **Files:** specific absolute paths (not "the auth files", not "relevant components")
-- **Action:** concrete instructions (not "implement auth", not "add the feature")
-- **Done when:** testable criterion (not "auth works", not "it's done")
+Each `## Task N — title` block must include ALL of these:
 
-**FAIL if:** any task missing any of the 3 fields, OR any field is vague.
+- **Wave:** integer (e.g. `**Wave:** 1`)
+- **Files:** specific absolute paths (not "the auth files", not "relevant components")
+- **Depends on:** explicit task numbers OR `none` (not blank)
+- **Why:** one-sentence rationale — what problem this solves (not "implement X")
+- **Acceptance Criteria:** 2-4 observable user-facing behaviors as bullet points
+- **Action:** concrete instructions with specific functions/imports/patterns
+- **Validation:** 1-3 grep/curl/tsc commands the builder runs before committing
 
-**How to detect vague:**
-- `Files: {filenames}` → pass
-- `Files: relevant files` → fail
-- `Action: Build the login page using Supabase auth with email/password, validate with Zod, redirect to /dashboard` → pass
-- `Action: Implement authentication` → fail
-- `Done when: grep -c "signInWithPassword" src/lib/auth.ts returns non-zero` → pass
-- `Done when: auth works` → fail
+`**Persona:**` is optional — warn if present but not one of {security, architect, ux, frontend, backend, performance, none}.
 
-### Rule 3: Wave assignments are correct
+**FAIL if:** any task missing any of the 7 required fields, OR any field is vague.
 
-Each task has a `**Wave:** {N}` field. Waves group tasks for parallel execution.
+**How to detect vague:**
+- `Files: relevant files` → FAIL
+- `Files: src/lib/auth.ts, src/app/login/page.tsx` → PASS
+- `Why: implement authentication` → FAIL (that's a what, not a why)
+- `Why: Session persistence is the #1 abandonment trigger in the onboarding funnel` → PASS
+- `Acceptance Criteria: - auth works` → FAIL (not observable)
+- `Acceptance Criteria: - User signs up with email, sees verification prompt, clicks link, lands on /dashboard with session` → PASS
+- `Action: Implement auth` → FAIL
+- `Action: Add signInWithPassword() call in handleSubmit, validate with Zod, redirect to /dashboard on success` → PASS
+- `Validation: it should work` → FAIL
+- `Validation: grep -c "signInWithPassword" src/lib/auth.ts → ≥ 1` → PASS
+- `Depends on:` (blank) → FAIL — must be explicit `none` or `Task N`
+
+### Rule 3: Wave assignments are correct and consistent with Depends on
+
+Each task has a `**Wave:** {N}` field. Waves group tasks for parallel execution. The wave number must be consistent with the task's `**Depends on:**` line.
 
 **FAIL if:**
-- Task in Wave 2 doesn't reference a Wave 1 task as a dependency
+- Task in Wave 2+ has `Depends on: none` (contradicts wave ordering — should be Wave 1)
+- Task in Wave N has a dependency on a task in Wave ≥N (impossible — dep must be in an earlier wave)
 - Tasks in same wave touch the same files (file conflict — can't run in parallel)
 - More than 3 waves (tasks too granular)
 

package/agents/planner.md

@@ -34,7 +34,11 @@ Each truth → one task. 2-5 tasks per phase. Each task must fit in one context
 - **Wave 2:** Tasks that depend on Wave 1 (run after Wave 1 completes)
 - Most phases need 1-2 waves. If you need 3+, your tasks are too granular.
 
-### 4. Write the Plan
+### 4. Write the Plan (Story-File Format)
+
+Plans are STORY FILES, not task lists. Every task is a self-contained package that embeds *why*, *what*, and *how to verify* — so the builder can execute without re-reading PRDs and the verifier has explicit acceptance targets.
+
+Use `~/.claude/qualia-templates/plan.md` as the structural reference. Every task block MUST include: **Wave, Files, Depends on, Why, Acceptance Criteria, Action, Validation, Context.** Persona is optional.
 
 ```markdown
 ---
@@ -46,40 +50,45 @@ 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}
 
 ## Task 1 — {title}
 **Wave:** 1
-**Files:** {files to create or modify}
-**Action:** {exactly what to build — specific enough for a junior dev to follow}
-**Context:** Read @{file references the builder needs}
-**Done when:** {observable, testable criterion}
+**Persona:** {optional: security | architect | ux | frontend | backend | performance | none}
+**Files:** {specific paths}
+**Depends on:** {none | Task N}
 
-## Task 2 — {title}
-**Wave:** 1
-**Files:** {files}
-**Action:** {what to build}
-**Done when:** {criterion}
+**Why:** {one-sentence rationale — what problem this solves}
+
+**Acceptance Criteria:**
+- {observable user-facing behavior 1}
+- {observable user-facing behavior 2}
 
-## Task 3 — {title}
-**Wave:** 2 (after Task 1, 2)
-**Files:** {files}
-**Action:** {what to build}
-**Done when:** {criterion}
+**Action:** {concrete steps with function names, imports, patterns}
+
+**Validation:** (builder self-check)
+- `{exact command}` → expected output
+
+**Context:** Read @{file references}
 
 ## Success Criteria
-- [ ] {truth 1 — what the user can do}
-- [ ] {truth 2}
-- [ ] {truth 3}
+- [ ] {phase-level truth 1}
+- [ ] {phase-level truth 2}
 ```
 
 ## Task Specificity (Mandatory)
 
-Every task MUST have these three fields with concrete content:
+Every task MUST have these fields with concrete content:
+
+- **Files:** Absolute paths from project root. Not "the auth files" or "relevant components". Specific: `src/app/auth/login/page.tsx`, `src/lib/auth.ts`. If creating, state what it exports. If modifying, state what changes.
+- **Depends on:** Explicit task numbers this task requires, OR `none`. This is what enables wave assignment and parallel-safe execution. Do not leave it blank.
+- **Why:** One sentence explaining the *motivation* — what problem this solves, what would break without it. Not "implement auth" but "Session persistence is the #1 abandonment trigger; verification emails are wasted without it."
+- **Acceptance Criteria:** 2-4 bullet points describing what the user can observe when this task is done. Not "auth works" but "User signs up, receives verification email, clicks link, lands on /dashboard with session persisted across refresh."
+- **Action:** At least one concrete instruction. Reference specific functions, components, patterns: "Add `signInWithPassword()` call in the `handleSubmit` handler, validate email with Zod schema, redirect to `/dashboard` on success."
+- **Validation:** 1-3 grep/curl/tsc commands the builder runs BEFORE committing. These are the builder's self-check — they prove the task actually produced running code, not just files.
 
-- **Files:** Absolute paths from project root. Not "the auth files" or "relevant components". Specific: `src/app/auth/login/page.tsx`, `src/lib/auth.ts`. If creating a file, state what it exports. If modifying, state what changes.
-- **Action:** At least one concrete instruction — not just "implement auth". Reference specific functions, components, or patterns. "Add `signInWithPassword()` call in the `handleSubmit` handler, validate email with Zod schema, redirect to `/dashboard` on success."
-- **Done when:** Testable, not fuzzy. Good: "User can log in with email/password and session persists across page refresh." Bad: "Auth works." Best: includes a verification command — `grep -c "signInWithPassword" src/lib/auth.ts` returns non-zero.
+**Persona (optional):** If a task has a clear specialist lens (security, architect, ux, frontend, backend, performance), set `**Persona:**` so the builder weights relevant rules. Leave blank or set `none` if generic.
 
 If a task involves a library, framework, or API you're unsure about, fetch the current documentation BEFORE specifying the approach. Don't guess at APIs.
 
@@ -89,7 +98,7 @@ Preferred order:
 
 Your training data is often stale. A two-second lookup is cheaper than a wrong task specification.
 
-**Self-check:** Before returning the plan, verify every task has specific file paths, concrete actions, and testable done-when criteria. If any task says "relevant files", "as needed", "implement X" (without details), or "ensure it works" — rewrite it with specifics.
+**Self-check:** Before returning the plan, verify every task has: specific file paths, an explicit Depends on line, a one-sentence Why, 2-4 Acceptance Criteria, concrete Action, and 1-3 Validation commands. If any field says "relevant files", "as needed", "implement X" (without details), or "ensure it works" — rewrite it with specifics. If you can't write a Why, the task is probably not needed.
 
 ## Verification Contracts
 

package/agents/research-synthesizer.md

@@ -44,17 +44,30 @@ Write for someone who will only read this section.
 
 Don't duplicate full documents. Summarize the 3-5 most important items from each dimension. Link back to the detail docs for readers who want more.
 
-### 4. Derive Roadmap Implications
+### 4. Derive Journey Implications (Multi-Milestone)
 
-This is the most important section. Based on:
-- FEATURES.md MVP definition → what v1 must have
-- ARCHITECTURE.md build order → what depends on what
-- PITFALLS.md phase mapping → what each phase must prevent
+This is the most important section. Suggest the **full milestone arc**, not just a v1 phase list.
 
-Suggest a phase structure. Be explicit about:
-- **What each phase delivers** (user-facing capability)
-- **Why this order** (dependencies or risk-first reasoning)
-- **Research flags** — phases likely needing deeper research during `/qualia-plan`
+Based on:
+- FEATURES.md split (table stakes = v1 across milestones, differentiators = later milestones or post-handoff)
+- ARCHITECTURE.md build order → what depends on what, which foundation must land in Milestone 1 to support final-milestone requirements
+- PITFALLS.md → which risks stall later milestones and need to be addressed in Milestone 1 foundations
+
+Suggest a **2-5 milestone arc ending in Handoff**:
+
+- **Milestone 1 · Foundation** — almost always. DB, auth, base layout, deploy pipeline.
+- **Milestone 2-{N-1} · Core + Expansion** — the value-delivering capabilities, ordered by dependency.
+- **Milestone {N} · Handoff** — ALWAYS the final milestone. Fixed 4 phases: Polish, Content + SEO, Final QA, Handoff.
+
+For each milestone, say:
+- **Name** — short, evocative
+- **Why now** — one plain-language sentence explaining why this follows the previous
+- **Exit criteria** — 2-3 observable outcomes
+- **Phases sketched** — 2-5 phase names with one-line goals (M1 full detail, M2..M{N-1} sketched)
+
+Also suggest:
+- **Research flags** — which milestones likely need deeper research during `/qualia-plan` (the roadmapper may schedule `/qualia-research {N}` for these)
+- **Handoff implications** — what the client needs to take over (credentials, docs, training) — informs the Handoff milestone's scope
 
 ### 5. Set Overall Confidence
 
@@ -79,8 +92,8 @@ Note gaps: areas where research was inconclusive. These will be addressed during
 ```
 Wrote: .planning/research/SUMMARY.md
 Overall confidence: {HIGH/MEDIUM/LOW}
-Suggested phases: {count}
-Research flags: {count} (phases needing deeper research during planning)
+Suggested milestones: {count including Handoff}
+Research flags: {count} (milestones needing deeper research during planning)
 ```
 
-The roadmapper agent reads your SUMMARY.md as context when producing REQUIREMENTS.md and ROADMAP.md.
+The roadmapper agent reads your SUMMARY.md as context when producing JOURNEY.md, REQUIREMENTS.md, and ROADMAP.md (Milestone 1 detail).