qualia-framework 3.6.0 → 4.0.3

package/templates/requirements.md

@@ -3,29 +3,85 @@
 **Defined:** {date}
 **Core Value:** {from PROJECT.md — the one thing that must work}
 
-## v1 Requirements
+Requirements are grouped by the milestone that delivers them. Each requirement
+has a stable REQ-ID and is atomic, testable, and user-centric.
 
-Initial release scope. Each maps to one roadmap phase.
+---
+
+## Milestone 1 · {Name}
 
-### {Category 1}
+Short description of what this milestone delivers for the user.
+
+### {Category}
 
 - [ ] **{CAT}-01**: {user-centric, testable, atomic capability}
 - [ ] **{CAT}-02**: {capability}
-- [ ] **{CAT}-03**: {capability}
 
-### {Category 2}
+### {Category}
 
 - [ ] **{CAT}-01**: {capability}
-- [ ] **{CAT}-02**: {capability}
 
-## v2 Requirements
+---
+
+## Milestone 2 · {Name}
+
+### {Category}
+
+- [ ] **{CAT}-03**: {capability}
+- [ ] **{CAT}-04**: {capability}
+
+---
 
-Acknowledged but deferred to a future release. Not in current roadmap.
+## Milestone 3 · {Name}
 
 ### {Category}
 
-- **{CAT}-01**: {capability}
-- **{CAT}-02**: {capability}
+- [ ] **{CAT}-05**: {capability}
+
+---
+
+## Handoff
+
+Fixed scope for every project. Do not reassign these elsewhere.
+
+### Polish
+
+- [ ] **HAND-01**: Every user-facing page has all interactive states (hover, focus, loading, error, empty)
+- [ ] **HAND-02**: Responsive verified at 375 / 768 / 1440 / 1920px
+- [ ] **HAND-03**: WCAG AA contrast + keyboard navigation verified
+
+### Content + SEO
+
+- [ ] **HAND-04**: Real copy replaces all placeholder text
+- [ ] **HAND-05**: Meta tags, OG images, sitemap.xml, robots.txt present
+- [ ] **HAND-06**: Analytics wired (Plausible / PostHog / GA)
+
+### Final QA
+
+- [ ] **HAND-07**: Full-flow test of every primary user journey
+- [ ] **HAND-08**: Cross-browser verified (Chrome + Safari + Firefox)
+- [ ] **HAND-09**: `/qualia-review` scored diagnostics reviewed, blockers resolved
+
+### Handoff
+
+- [ ] **HAND-10**: Production URL verified (HTTP 200, auth flow works, latency < 500ms)
+- [ ] **HAND-11**: README updated with architecture, setup, API documentation
+- [ ] **HAND-12**: Credentials document delivered to client (deploy tokens, admin accounts, third-party keys)
+- [ ] **HAND-13**: Recorded walkthrough (Loom or equivalent) delivered
+- [ ] **HAND-14**: `.planning/archive/` contains every milestone's verification reports
+- [ ] **HAND-15**: Final `/qualia-report` submitted, `lifetime.milestones_completed` incremented
+
+---
+
+## Post-Handoff (v2)
+
+Features acknowledged but deferred past initial handoff. Not in current journey.
+
+### {Category}
+
+- **{CAT}-XX**: {capability}
+
+---
 
 ## Out of Scope
 
@@ -35,35 +91,39 @@ Explicit exclusions with reasoning. Prevents scope creep.
 |---------|--------|
 | {feature} | {why excluded} |
 
+---
+
 ## Traceability
 
-Which phases cover which requirements. Populated during roadmap creation.
+Populated during roadmap creation. Every v1 requirement maps to exactly one milestone + phase.
 
-| Requirement | Phase | Status |
-|-------------|-------|--------|
-| {CAT}-01 | Phase {N} | Pending |
+| Requirement | Milestone | Phase | Status |
+|-------------|-----------|-------|--------|
+| {CAT}-01 | M1: {name} | Phase {N} | Pending |
 
 **Coverage:**
-- v1 requirements: {X} total
-- Mapped to phases: {Y}
+- v1 requirements (all feature milestones + Handoff): {X} total
+- Mapped to milestones + phases: {Y}
 - Unmapped: {Z}
 
 ---
 
 ## Requirement Quality Rules
 
-1. **ID format:** `{CATEGORY}-{NUMBER}` — `AUTH-01`, `CONT-02`, `SOCIAL-03`
+1. **ID format:** `{CATEGORY}-{NUMBER}` — stable across the project's life
 2. **User-centric:** "User can X" — not "System does Y"
-3. **Atomic:** One capability per requirement — not "User can login and manage profile"
-4. **Testable:** "User can reset password via email link" — not "handle password reset"
-5. **Independent:** Minimal dependencies on other requirements
+3. **Atomic:** one capability per requirement
+4. **Testable:** the observable behavior is nameable
+5. **Independent:** minimal dependencies on other requirements
+6. **Assigned to exactly one milestone:** no duplicates, no gaps
 
 ## Status Values
 
 - **Pending** — not started
-- **In Progress** — phase is active
-- **Complete** — requirement verified
+- **In Progress** — milestone is active, phase in progress
+- **Complete** — verified as passing
 - **Blocked** — waiting on external factor
 
 ---
+
 *Last updated: {date}*

package/templates/roadmap.md

@@ -1,8 +1,22 @@
-# Roadmap: {Project Name}
+# Roadmap · Milestone {N} · {Milestone Name}
 
+**Project:** {Project Name}
+**Milestone:** {N} of {Total} ({"CURRENT" / shipped})
 **Created:** {date}
-**Total phases:** {N}
-**v1 requirements:** {X} covered
+**Phases:** {P}
+**Requirements covered:** {REQ-IDs from this milestone's REQUIREMENTS.md section}
+
+See `JOURNEY.md` for the full project arc. This file is ONLY the current milestone's phases.
+
+## Exit Criteria
+
+What "shipped" means for this milestone:
+
+- {observable outcome 1}
+- {observable outcome 2}
+- {observable outcome 3}
+
+---
 
 ## Phases
 
@@ -25,9 +39,8 @@
 **Success criteria** (observable user behaviors):
 1. {user can do X}
 2. {user can do Y}
-3. {user can do Z}
 
-**Depends on:** none (or: Phase {N})
+**Depends on:** none
 
 ---
 
@@ -46,26 +59,40 @@
 
 ---
 
-{... continue for all phases ...}
+### Phase 3: {Name}
+
+**Goal:** {goal}
+
+**Requirements covered:**
+- {REQ-ID}: {description}
+
+**Success criteria:**
+1. {criterion}
+
+**Depends on:** Phase 2
+
+---
 
 ## Coverage Verification
 
-All v1 requirements must map to exactly one phase. Unmapped requirements = roadmap gap.
+Every requirement in this milestone must map to exactly one phase.
 
 | Requirement | Phase | Covered? |
 |-------------|-------|----------|
 | {REQ-ID} | Phase {N} | ✓ |
 
-**Coverage:** {X}/{Y} v1 requirements mapped ({100% expected})
-
 ---
 
-## Rules
+## When This Milestone Closes
 
-1. **Feature phases only.** No "review" / "deploy" / "handoff" phases — those are driven by `/qualia-polish` → `/qualia-ship` → `/qualia-handoff` after all feature phases verify.
-2. **Each requirement maps to exactly one phase.** If a requirement spans phases, it's too big — split it.
-3. **Phases are independently verifiable.** A phase completes when its success criteria are observable in a running app.
-4. **Order by dependency, not priority.** Phase 2 should depend on Phase 1's outputs.
+Triggered by `/qualia-milestone` after `/qualia-verify` passes on the last phase:
+
+1. All phase artifacts are archived to `.planning/archive/milestone-{N}-{slug}/`
+2. `tracking.json` `milestones[]` gets a summary entry (num, name, phases_completed, shipped_url, closed_at)
+3. REQUIREMENTS.md marks this milestone's requirements as **Complete**
+4. Next milestone from JOURNEY.md opens — roadmapper regenerates this ROADMAP.md for Milestone {N+1}
+5. `state.js init --force --milestone_name "{N+1 name}"` resets current-phase fields, preserves lifetime + milestones[] history
 
 ---
+
 *Last updated: {date}*

package/templates/tracking.json

@@ -7,6 +7,8 @@
   "project_id": "",
   "git_remote": "",
   "milestone": 1,
+  "milestone_name": "",
+  "milestones": [],
   "phase": 0,
   "phase_name": "",
   "total_phases": 0,

package/tests/hooks.test.sh

@@ -218,25 +218,25 @@ export default function P(){return null}
 EOF
 OUT=$(cd "$TMP" && $NODE "$HOOKS_DIR/pre-deploy-gate.js" 2>&1)
 RC=$?
-if [ "$RC" -eq 1 ] \
+if [ "$RC" -eq 2 ] \
    && echo "$OUT" | grep -q "BLOCKED" \
    && echo "$OUT" | grep -q "service_role"; then
-  echo "  ✓ service_role leak in app/ → blocked with diagnostic"
+  echo "  ✓ service_role leak in app/ → blocked with diagnostic (exit 2)"
   PASS=$((PASS + 1))
 else
-  echo "  ✗ service_role leak in app/ → blocked (exit=$RC)"
+  echo "  ✗ service_role leak in app/ → blocked (exit=$RC, expected 2)"
   FAIL=$((FAIL + 1))
 fi
 rm -rf "$TMP"
 
-# service_role leak in components/ → BLOCKED
+# service_role leak in components/ → BLOCKED (exit 2 per PreToolUse contract)
 TMP=$(mktemp -d)
 mkdir -p "$TMP/components"
 cat > "$TMP/components/Widget.tsx" <<'EOF'
 const key = "service_role_literal_leak";
 EOF
 (cd "$TMP" && $NODE "$HOOKS_DIR/pre-deploy-gate.js" >/dev/null 2>&1)
-assert_exit "service_role in components/ → blocked" 1 $?
+assert_exit "service_role in components/ → blocked (exit 2)" 2 $?
 rm -rf "$TMP"
 
 # service_role in a *.server.ts file → allowed (skip convention)