qualia-framework 3.6.0 → 4.0.0

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
 
@@ -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/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}

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,