qualia-framework 3.6.0 → 4.0.3

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

@@ -126,18 +126,23 @@ function cmdUpdate() {
 // non-Qualia entries in settings.json (other hooks, user env vars, etc.).
 // --yes / -y skips the confirmation prompt for scripted use.
 
-// 8 Qualia hook filenames — only these are removed from ~/.claude/hooks/,
-// any other hooks the user dropped in there are left alone.
+// Current Qualia hook filenames — only these are removed from ~/.claude/hooks/,
+// any other hooks the user dropped in there are left alone. The LEGACY set
+// lists hooks that were shipped by older framework versions but have since
+// been removed; uninstall still tries to clean them so old installs get a
+// clean removal.
 const QUALIA_HOOK_FILES = [
   "session-start.js",
   "auto-update.js",
   "branch-guard.js",
   "pre-push.js",
-  "block-env-edit.js",
   "migration-guard.js",
   "pre-deploy-gate.js",
   "pre-compact.js",
 ];
+const QUALIA_LEGACY_HOOK_FILES = [
+  "block-env-edit.js", // removed in v3.2.0
+];
 
 // 4 Qualia agents — only these are removed.
 const QUALIA_AGENT_FILES = ["planner.md", "builder.md", "verifier.md", "qa-browser.md"];
@@ -210,14 +215,14 @@ function cleanSettingsJson(counters) {
   };
 
   if (settings.hooks && typeof settings.hooks === "object") {
-    for (const key of ["SessionStart", "PreToolUse", "PreCompact"]) {
-      if (settings.hooks[key]) {
-        const cleaned = filterHookArray(settings.hooks[key]);
-        if (cleaned && cleaned.length > 0) {
-          settings.hooks[key] = cleaned;
-        } else {
-          delete settings.hooks[key];
-        }
+    // Iterate every hook event key, not a hardcoded subset — future hook
+    // events added by Claude Code or the framework get cleaned automatically.
+    for (const key of Object.keys(settings.hooks)) {
+      const cleaned = filterHookArray(settings.hooks[key]);
+      if (cleaned && cleaned.length > 0) {
+        settings.hooks[key] = cleaned;
+      } else {
+        delete settings.hooks[key];
       }
     }
     // If hooks is now empty, remove it entirely.
@@ -305,8 +310,8 @@ async function cmdUninstall() {
     safeUnlink(path.join(CLAUDE_DIR, "agents", f), counters);
   }
 
-  // Hooks — only the 8 Qualia ones.
-  for (const f of QUALIA_HOOK_FILES) {
+  // Hooks — current set plus any legacy hook filenames from older versions.
+  for (const f of [...QUALIA_HOOK_FILES, ...QUALIA_LEGACY_HOOK_FILES]) {
     safeUnlink(path.join(CLAUDE_DIR, "hooks", f), counters);
   }
 

package/bin/install.js

@@ -599,16 +599,23 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
   // bash/Git Bash requirement on Windows.
   const hd = path.join(CLAUDE_DIR, "hooks");
   const nodeCmd = (hookFile) => `node "${path.join(hd, hookFile)}"`;
-  settings.hooks = {
+  const QUALIA_HOOK_SET = new Set([
+    "session-start.js", "auto-update.js", "branch-guard.js", "pre-push.js",
+    "pre-deploy-gate.js", "migration-guard.js", "pre-compact.js",
+  ]);
+  const isQualiaHookCmd = (cmd) => {
+    if (typeof cmd !== "string") return false;
+    for (const h of QUALIA_HOOK_SET) if (cmd.includes(h)) return true;
+    return false;
+  };
+
+  // Our canonical hook definitions, grouped per event/matcher.
+  const qualiaHooks = {
     SessionStart: [
       {
         matcher: ".*",
         hooks: [
-          {
-            type: "command",
-            command: nodeCmd("session-start.js"),
-            timeout: 5,
-          },
+          { type: "command", command: nodeCmd("session-start.js"), timeout: 5 },
         ],
       },
     ],
@@ -616,44 +623,16 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
       {
         matcher: "Bash",
         hooks: [
-          {
-            type: "command",
-            command: nodeCmd("auto-update.js"),
-            timeout: 5,
-          },
-          {
-            type: "command",
-            if: "Bash(git push*)",
-            command: nodeCmd("branch-guard.js"),
-            timeout: 5,
-            statusMessage: "⬢ Checking branch permissions...",
-          },
-          {
-            type: "command",
-            if: "Bash(git push*)",
-            command: nodeCmd("pre-push.js"),
-            timeout: 15,
-            statusMessage: "⬢ Syncing tracking...",
-          },
-          {
-            type: "command",
-            if: "Bash(vercel --prod*)",
-            command: nodeCmd("pre-deploy-gate.js"),
-            timeout: 180,
-            statusMessage: "⬢ Running quality gates...",
-          },
+          { type: "command", command: nodeCmd("auto-update.js"), timeout: 5 },
+          { type: "command", if: "Bash(git push*)", command: nodeCmd("branch-guard.js"), timeout: 5, statusMessage: "⬢ Checking branch permissions..." },
+          { type: "command", if: "Bash(git push*)", command: nodeCmd("pre-push.js"), timeout: 15, statusMessage: "⬢ Syncing tracking..." },
+          { type: "command", if: "Bash(vercel --prod*)", command: nodeCmd("pre-deploy-gate.js"), timeout: 180, statusMessage: "⬢ Running quality gates..." },
         ],
       },
       {
         matcher: "Edit|Write",
         hooks: [
-          {
-            type: "command",
-            if: "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)",
-            command: nodeCmd("migration-guard.js"),
-            timeout: 10,
-            statusMessage: "⬢ Checking migration safety...",
-          },
+          { type: "command", if: "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)", command: nodeCmd("migration-guard.js"), timeout: 10, statusMessage: "⬢ Checking migration safety..." },
         ],
       },
     ],
@@ -661,17 +640,27 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
       {
         matcher: "compact",
         hooks: [
-          {
-            type: "command",
-            command: nodeCmd("pre-compact.js"),
-            timeout: 15,
-            statusMessage: "⬢ Saving state...",
-          },
+          { type: "command", command: nodeCmd("pre-compact.js"), timeout: 15, statusMessage: "⬢ Saving state..." },
         ],
       },
     ],
   };
 
+  // Merge user hooks: strip Qualia-owned commands, preserve everything else.
+  if (!settings.hooks || typeof settings.hooks !== "object") settings.hooks = {};
+  for (const event of Object.keys(qualiaHooks)) {
+    const existing = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+    // Remove Qualia-owned command entries from each matcher block, drop empty blocks.
+    const cleaned = [];
+    for (const block of existing) {
+      if (!block || !Array.isArray(block.hooks)) continue;
+      const kept = block.hooks.filter((h) => !isQualiaHookCmd(h && h.command));
+      if (kept.length > 0) cleaned.push({ ...block, hooks: kept });
+    }
+    // Append our canonical blocks after the preserved user ones.
+    settings.hooks[event] = [...cleaned, ...qualiaHooks[event]];
+  }
+
   // Permissions — no restrictions on env files or branches.
   // Everyone can read/write .env, push to main.
   if (!settings.permissions) settings.permissions = {};