qualia-framework 3.6.0 → 4.0.3

package/skills/qualia-plan/SKILL.md

@@ -1,6 +1,16 @@
 ---
 name: qualia-plan
 description: "Plan the current phase — spawns planner, validates with plan-checker in a revision loop (max 3), optionally runs discuss/research first. Use when ready to plan a phase."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
+  - TaskCreate
+  - TaskUpdate
 ---
 
 # /qualia-plan — Plan a Phase
@@ -13,6 +23,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 +164,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 +182,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}"
@@ -191,7 +206,7 @@ When invoked as `/qualia-plan {N} --gaps`, the planner is in gap-closure mode:
 2. For each FAIL item, create a targeted fix task:
    - **Files:** specific files that failed verification
    - **Action:** specific fix (not "fix auth" — "add session persistence check in src/lib/auth.ts signIn function")
-   - **Done when:** the exact verification criterion that previously failed, restated
+   - **Acceptance Criteria:** the exact verification criterion that previously failed, restated as an observable behavior
 3. Do NOT re-plan passing items. Do NOT add new features. Gap plans are surgical.
 4. Write to `.planning/phase-{N}-gaps-plan.md` (separate from original plan)
 5. All gap tasks are Wave 1 (parallel) unless they share files

package/skills/qualia-polish/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: qualia-polish
 description: "Design and UX pass — anti-AI-slop, genuine craft, responsive, accessible. Run after all phases are verified."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-polish — Design Pass

package/skills/qualia-quick/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: qualia-quick
 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'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
 ---
 
 # /qualia-quick — Quick Task

package/skills/qualia-report/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: qualia-report
 description: "Generate session report and commit to repo. Mandatory before clock-out."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
 ---
 
 # /qualia-report — Session Report
@@ -92,6 +97,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 +112,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 +127,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-research/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: qualia-research
 description: "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."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Agent
+  - WebFetch
+  - WebSearch
 ---
 
 # /qualia-research — Per-Phase Deep Research

package/skills/qualia-resume/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: qualia-resume
 description: "Restore context from a previous session. Reads .continue-here.md or STATE.md, summarizes where you left off, routes to next action. Trigger on 'resume', 'continue', 'pick up where I left off', 'what was I doing'."
+allowed-tools:
+  - Bash
+  - Read
 ---
 
 # /qualia-resume — Resume Work

package/skills/qualia-review/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: qualia-review
 description: "Production audit with scored diagnostics. Runs real commands, scores findings by severity. Trigger on 'review', 'audit', 'code review', 'security check', 'production check'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-review — Production Audit

package/skills/qualia-ship/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: qualia-ship
 description: "Deploy to production — quality gates, commit, push, deploy, verify. Use when ready to go live."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
 ---
 
 # /qualia-ship — Deploy

package/skills/qualia-skill-new/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: qualia-skill-new
 description: "Author a new Qualia skill or agent. Use when the user says 'create a new skill', 'add a skill', 'I want to build a skill', 'make this a reusable command', 'turn this into a skill'. Generates the SKILL.md, registers it in the right location, and optionally ships to the framework repo."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - AskUserQuestion
 ---
 
 # /qualia-skill-new — Author a New Skill

package/skills/qualia-task/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: qualia-task
 description: "Build a single task — more structured than /qualia-quick, lighter than /qualia-build. Spawns a fresh builder agent for one focused task."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Agent
+  - AskUserQuestion
 ---
 
 # /qualia-task — Single Task Builder
@@ -61,7 +68,7 @@ Agent(subagent_type: "qualia-builder")
 
 Task: {task description}
 Files: {files to create/modify}
-Done when: {completion criteria}
+Acceptance Criteria: {observable completion criteria, 1-3 bullet points}
 
 Context: Read PROJECT.md if it exists. Follow all rules (security, frontend, deployment).
 ```

package/skills/qualia-test/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: qualia-test
 description: "Generate or run tests for client projects. Trigger on 'write tests', 'add tests', 'test this', 'run tests', 'test coverage', 'need tests for'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
 ---
 
 # /qualia-test — Test Generator

package/skills/qualia-verify/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: qualia-verify
 description: "Goal-backward verification — checks if the phase ACTUALLY works, not just if tasks completed. Spawns verifier agent."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-verify — Verify a Phase
@@ -10,6 +18,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 +108,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

@@ -291,13 +291,13 @@
 </head>
 <body>
 
-<div class="version-pill">v3.6.0</div>
+<div class="version-pill">{{VERSION}}</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">v3.6.0 &middot; 26 skills</div>
+    <div class="version">{{VERSION}} &middot; 26 skills</div>
   </div>
 </div>
 
@@ -430,7 +430,7 @@
         <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>
         <div class="cmd"><span class="cmd-name">qualia-framework version</span><span class="cmd-desc">Show installed version + check for updates.</span></div>
-        <div class="cmd"><span class="cmd-name">qualia-framework migrate</span><span class="cmd-desc">Upgrade v2 settings to v3.</span></div>
+        <div class="cmd"><span class="cmd-name">qualia-framework migrate</span><span class="cmd-desc">Upgrade legacy settings.json to the current hook layout.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework analytics</span><span class="cmd-desc">Hook telemetry, verification pass rates, gap cycles.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework team</span><span class="cmd-desc">List, add, or remove team members.</span></div>
         <div class="cmd"><span class="cmd-name">qualia-framework traces</span><span class="cmd-desc">View recent hook activity.</span></div>
@@ -536,7 +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>
+  <span class="footer-version">qualia-framework {{VERSION}} &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}