qualia-framework 5.3.0 → 5.5.0

package/bin/plan-contract.js

@@ -21,6 +21,28 @@ const CHECK_TYPES = new Set([
   "file-exists", "grep-match", "command-exit", "behavioral",
 ]);
 
+// Scope-reduction detection — phrases that signal an LLM has watered down the
+// spec. The plan-checker agent does the same scan on the markdown plan; this
+// function does it on the JSON contract's free-text fields (action +
+// acceptance_criteria) so both paths catch the same failure mode.
+const SCOPE_REDUCTION_PHRASES = [
+  /\bv1\b/i, /\bv2\b/i, /simplified version/i, /static for now/i,
+  /hardcoded for now/i, /\bplaceholder\b/i, /basic version/i,
+  /minimal implementation/i, /will be wired later/i,
+  /dynamic in future phase/i, /skip for now/i, /\bstub\b/i,
+  /mock for now/i, /we can improve this later/i, /quick win for now/i,
+];
+
+function findScopeReductionPhrases(text) {
+  if (typeof text !== "string") return [];
+  const hits = [];
+  for (const re of SCOPE_REDUCTION_PHRASES) {
+    const m = text.match(re);
+    if (m) hits.push(m[0]);
+  }
+  return hits;
+}
+
 function isStringArray(v) {
   return Array.isArray(v) && v.every((x) => typeof x === "string");
 }
@@ -98,7 +120,15 @@ function validateTask(task, idx, allIds) {
     errs.push(`${where}.acceptance_criteria: must be a non-empty string[]`);
   }
   if (typeof task.action !== "string") errs.push(`${where}.action: required string`);
-  else if (task.action.length > 500) errs.push(`${where}.action: must be ≤ 500 characters (got ${task.action.length})`);
+  else {
+    if (task.action.length > 500) errs.push(`${where}.action: must be ≤ 500 characters (got ${task.action.length})`);
+    const actionHits = findScopeReductionPhrases(task.action);
+    if (actionHits.length) errs.push(`${where}.action: scope-reduction phrase(s) detected: ${actionHits.join(", ")} — rewrite to deliver the actual spec, or split via locked-decision channel`);
+  }
+  for (let i = 0; i < (task.acceptance_criteria || []).length; i++) {
+    const acHits = findScopeReductionPhrases(task.acceptance_criteria[i]);
+    if (acHits.length) errs.push(`${where}.acceptance_criteria[${i}]: scope-reduction phrase(s) detected: ${acHits.join(", ")}`);
+  }
   if (!isStringArray(task.context_files || [])) errs.push(`${where}.context_files: must be string[]`);
   if (!Array.isArray(task.verification) || task.verification.length === 0) {
     errs.push(`${where}.verification: must be a non-empty array`);
@@ -217,4 +247,5 @@ module.exports = {
   parseSafely,
   hashPlan,
   checkDrift,
+  findScopeReductionPhrases,
 };

package/bin/state.js

@@ -537,6 +537,139 @@ function cmdCheck(opts) {
   });
 }
 
+// ─── cmdTransition helpers ──────────────────────────────────────────────
+// cmdTransition was a 195-line orchestrator that mixed validation, the
+// note/activity short-circuit, per-status mutations, atomic write, and
+// trace+output into one block. Split into focused helpers below; the
+// orchestrator now reads top-to-bottom in ~50 lines. Behavior is
+// preserved exactly — verified by the 59 state.test.sh assertions.
+
+// Handles the note/activity short-circuit. Returns the success payload
+// when the target is note/activity (caller should `return output(...)`),
+// or null if not handled (caller proceeds with normal transition).
+function applyNoteOrActivity(target, s, t, opts) {
+  if (target !== "note" && target !== "activity") return null;
+  if (opts.notes) t.notes = opts.notes;
+  // Count tasks from quick/task work toward lifetime
+  if (opts.tasks_done) {
+    const count = parseInt(opts.tasks_done) || 0;
+    if (count > 0) {
+      ensureLifetime(t);
+      t.lifetime.tasks_completed += count;
+    }
+  }
+  t.last_updated = new Date().toISOString();
+  writeTracking(t);
+  s.last_activity = opts.notes || "Activity logged";
+  writeStateMd(s);
+  return {
+    ok: true,
+    phase: s.phase,
+    status: s.status,
+    action: target,
+  };
+}
+
+// Per-status mutations. Each helper mutates `s` and `t` in place (JS
+// objects are by-reference) and returns nothing. They DO NOT write to
+// disk — the orchestrator commits everything atomically at the end.
+
+function applyPlannedTransition(s, t, prevStatus, phase) {
+  // Gap closure: increment counter if coming from verified(fail).
+  if (prevStatus === "verified") {
+    if (!t.gap_cycles) t.gap_cycles = {};
+    t.gap_cycles[String(phase)] = (t.gap_cycles[String(phase)] || 0) + 1;
+    s.last_activity = `Gap closure #${t.gap_cycles[String(phase)]} planned (phase ${phase})`;
+  }
+  if (s.phases[phase - 1]) s.phases[phase - 1].status = "planned";
+}
+
+function applyBuiltTransition(s, t, opts, phase) {
+  t.tasks_done = parseInt(opts.tasks_done) || 0;
+  t.tasks_total = parseInt(opts.tasks_total) || 0;
+  t.wave = parseInt(opts.wave) || 0;
+  t.build_count = (parseInt(t.build_count) || 0) + 1;
+  s.last_activity = `Phase ${phase} built (${t.tasks_done}/${t.tasks_total} tasks)`;
+  if (s.phases[phase - 1]) s.phases[phase - 1].status = "built";
+}
+
+function applyVerifiedTransition(s, t, opts, phase) {
+  t.verification = opts.verification;
+  s.last_activity = `Phase ${phase} verified — ${opts.verification}`;
+  if (s.phases[phase - 1]) {
+    s.phases[phase - 1].status =
+      opts.verification === "pass" ? "verified" : "failed";
+  }
+
+  if (opts.verification !== "pass") return;
+
+  // Auto-advance on pass: accumulate into lifetime BEFORE resetting
+  // current counters so the totals are correct.
+  ensureLifetime(t);
+  t.lifetime.tasks_completed += (t.tasks_done || 0);
+  t.lifetime.phases_completed += 1;
+
+  if (phase < s.total_phases) {
+    s.phase = phase + 1;
+    s.phase_name = s.phases[phase]?.name || `Phase ${phase + 1}`;
+    s.status = "setup";
+    t.phase = s.phase;
+    t.phase_name = s.phase_name;
+    t.status = "setup";
+    t.verification = "pending";
+    t.tasks_done = 0;
+    t.tasks_total = 0;
+    s.last_activity = `Phase ${phase} passed — advancing to phase ${s.phase}`;
+  }
+  // Reset gap counter for the passed phase.
+  if (t.gap_cycles) t.gap_cycles[String(phase)] = 0;
+}
+
+function applyPolishedTransition(s) {
+  // Polish is a whole-project pass. Mark every already-passed phase as
+  // polished. (Previously only the last row was touched and was set to
+  // "verified" — wrong status string, lost current-phase context.)
+  for (const p of s.phases) {
+    const st = (p.status || "").toLowerCase();
+    if (st === "verified" || st === "polished" || st === "completed" || st === "complete") {
+      p.status = "polished";
+    }
+  }
+}
+
+function applyShippedTransition(t, opts) {
+  t.deployed_url = opts.deployed_url || "";
+  t.deploy_count = (parseInt(t.deploy_count) || 0) + 1;
+}
+
+// Atomically commit the new state + tracking. Writes a journal snapshot
+// of the pre-transition files first; if the process dies between the
+// two real writes, the next invocation restores both from the journal.
+// Each individual write is torn-write safe (tmp + rename); the journal
+// closes the gap between the two writes.
+//
+// Returns null on success, or a `fail(...)` object on write error
+// (caller should pass through to `output(...)`).
+function commitTransitionAtomic(s, t) {
+  const backupState = readState();
+  const backupTracking = (() => {
+    try { return fs.readFileSync(TRACKING_FILE, "utf8"); } catch { return null; }
+  })();
+  try {
+    writeJournal(backupState, backupTracking);
+    writeStateMd(s);
+    writeTracking(t);
+    clearJournal();
+    return null;
+  } catch (e) {
+    // Revert whichever file is out of sync with pre-transition state.
+    try { if (backupState) atomicWrite(STATE_FILE, backupState); } catch {}
+    try { if (backupTracking) atomicWrite(TRACKING_FILE, backupTracking); } catch {}
+    clearJournal();
+    return fail("WRITE_ERROR", e.message);
+  }
+}
+
 function cmdTransition(opts) {
   const target = opts.to;
   if (!target) return output(fail("MISSING_ARG", "--to is required"));
@@ -544,9 +677,7 @@ function cmdTransition(opts) {
   const t = readTracking();
   const s = parseStateMd(readState());
   if (!t || !s) {
-    return output(
-      fail("NO_PROJECT", "No .planning/ found. Run /qualia-new.")
-    );
+    return output(fail("NO_PROJECT", "No .planning/ found. Run /qualia-new."));
   }
 
   // Refuse transitions if STATE.md has schema errors (severity=error)
@@ -559,47 +690,21 @@ function cmdTransition(opts) {
     );
   }
 
-  // Special: note/activity (no status change)
-  if (target === "note" || target === "activity") {
-    if (opts.notes) t.notes = opts.notes;
-    // Count tasks from quick/task work toward lifetime
-    if (opts.tasks_done) {
-      const count = parseInt(opts.tasks_done) || 0;
-      if (count > 0) {
-        ensureLifetime(t);
-        t.lifetime.tasks_completed += count;
-      }
-    }
-    t.last_updated = new Date().toISOString();
-    writeTracking(t);
-    s.last_activity = opts.notes || "Activity logged";
-    writeStateMd(s);
-    return output({
-      ok: true,
-      phase: s.phase,
-      status: s.status,
-      action: target,
-    });
-  }
+  // Note/activity short-circuit (no status change, no precondition check)
+  const noteResult = applyNoteOrActivity(target, s, t, opts);
+  if (noteResult) return output(noteResult);
 
   const phase = parseInt(opts.phase) || s.phase;
 
   // Precondition check
-  const check = checkPreconditions(
-    { ...s, phase },
-    target,
-    { ...opts, phase }
-  );
+  const check = checkPreconditions({ ...s, phase }, target, { ...opts, phase });
   if (!check.ok) {
-    // Force bypasses status-ordering errors AND plan-content errors. The use case
-    // is retroactive bookkeeping: a phase was built without /qualia-plan and the
-    // user is catching STATE.md up to reality. `--force` never bypasses MISSING_FILE
-    // or MISSING_ARG — those would leave the state machine pointing at nothing.
-    const forceableErrors = [
-      "PRECONDITION_FAILED",
-      "GAP_CYCLE_LIMIT",
-      "INVALID_PLAN",
-    ];
+    // --force bypasses status-ordering and plan-content errors. The use case
+    // is retroactive bookkeeping: a phase was built without /qualia-plan and
+    // the user is catching STATE.md up to reality. --force never bypasses
+    // MISSING_FILE or MISSING_ARG — those would leave the state machine
+    // pointing at nothing.
+    const forceableErrors = ["PRECONDITION_FAILED", "GAP_CYCLE_LIMIT", "INVALID_PLAN"];
     if (opts.force && forceableErrors.includes(check.error)) {
       console.error(`WARNING: Forcing transition despite: ${check.message}`);
     } else {
@@ -609,109 +714,26 @@ function cmdTransition(opts) {
 
   const prevStatus = s.status;
 
-  // Apply transition
+  // Apply common transition fields
   s.status = target;
   s.last_activity = `${target} (phase ${phase})`;
-
-  // Update tracking fields
   t.status = target;
   t.phase = phase;
   t.phase_name = s.phases[phase - 1]?.name || s.phase_name;
   t.last_updated = new Date().toISOString();
 
-  if (target === "planned") {
-    // Gap closure: increment counter if coming from verified(fail)
-    if (prevStatus === "verified") {
-      if (!t.gap_cycles) t.gap_cycles = {};
-      t.gap_cycles[String(phase)] = (t.gap_cycles[String(phase)] || 0) + 1;
-      s.last_activity = `Gap closure #${t.gap_cycles[String(phase)]} planned (phase ${phase})`;
-    }
-    // Update roadmap
-    if (s.phases[phase - 1]) s.phases[phase - 1].status = "planned";
-  }
+  // Per-status mutations
+  if (target === "planned") applyPlannedTransition(s, t, prevStatus, phase);
+  if (target === "built") applyBuiltTransition(s, t, opts, phase);
+  if (target === "verified") applyVerifiedTransition(s, t, opts, phase);
+  if (target === "polished") applyPolishedTransition(s);
+  if (target === "shipped") applyShippedTransition(t, opts);
 
-  if (target === "built") {
-    t.tasks_done = parseInt(opts.tasks_done) || 0;
-    t.tasks_total = parseInt(opts.tasks_total) || 0;
-    t.wave = parseInt(opts.wave) || 0;
-    t.build_count = (parseInt(t.build_count) || 0) + 1;
-    s.last_activity = `Phase ${phase} built (${t.tasks_done}/${t.tasks_total} tasks)`;
-    if (s.phases[phase - 1]) s.phases[phase - 1].status = "built";
-  }
-
-  if (target === "verified") {
-    t.verification = opts.verification;
-    s.last_activity = `Phase ${phase} verified — ${opts.verification}`;
-    if (s.phases[phase - 1])
-      s.phases[phase - 1].status =
-        opts.verification === "pass" ? "verified" : "failed";
-
-    // Auto-advance on pass
-    if (opts.verification === "pass") {
-      // Accumulate into lifetime BEFORE resetting current counters
-      ensureLifetime(t);
-      t.lifetime.tasks_completed += (t.tasks_done || 0);
-      t.lifetime.phases_completed += 1;
-
-      if (phase < s.total_phases) {
-        s.phase = phase + 1;
-        s.phase_name = s.phases[phase]?.name || `Phase ${phase + 1}`;
-        s.status = "setup";
-        t.phase = s.phase;
-        t.phase_name = s.phase_name;
-        t.status = "setup";
-        t.verification = "pending";
-        t.tasks_done = 0;
-        t.tasks_total = 0;
-        s.last_activity = `Phase ${phase} passed — advancing to phase ${s.phase}`;
-      }
-      // Reset gap counter for the passed phase
-      if (t.gap_cycles) t.gap_cycles[String(phase)] = 0;
-    }
-  }
-
-  if (target === "polished") {
-    // Mark every passed phase as polished (polish is a whole-project pass).
-    // Previously only the last roadmap row was touched, and was set to
-    // "verified" — which both lost current-phase context and used the wrong
-    // status string. Now we use "polished" on every row that's already at
-    // verified or polished or completed.
-    for (const p of s.phases) {
-      const st = (p.status || "").toLowerCase();
-      if (st === "verified" || st === "polished" || st === "completed" || st === "complete") {
-        p.status = "polished";
-      }
-    }
-  }
-
-  if (target === "shipped") {
-    t.deployed_url = opts.deployed_url || "";
-    t.deploy_count = (parseInt(t.deploy_count) || 0) + 1;
-  }
-
-  // Write both files. We write a journal snapshot of the pre-transition
-  // STATE.md + tracking.json first; if the process dies between the two
-  // real writes, the next invocation will see the journal and restore both
-  // files to the pre-transition state. Each individual write is torn-write
-  // safe (tmp + rename); the journal closes the gap between the two.
-  const backupState = readState();
-  const backupTracking = (() => {
-    try { return fs.readFileSync(TRACKING_FILE, "utf8"); } catch { return null; }
-  })();
-  try {
-    writeJournal(backupState, backupTracking);
-    writeStateMd(s);
-    writeTracking(t);
-    clearJournal();
-  } catch (e) {
-    // Revert whichever file is out of sync with pre-transition state.
-    try { if (backupState) atomicWrite(STATE_FILE, backupState); } catch {}
-    try { if (backupTracking) atomicWrite(TRACKING_FILE, backupTracking); } catch {}
-    clearJournal();
-    return output(fail("WRITE_ERROR", e.message));
-  }
+  // Atomic commit
+  const writeError = commitTransitionAtomic(s, t);
+  if (writeError) return output(writeError);
 
-  // Skill outcome scoring — log transition for analytics
+  // Trace transition for analytics
   _trace("state-transition", "allow", {
     phase: s.phase,
     status: s.status,

package/docs/archive/v4.0.0-review.md

@@ -0,0 +1,288 @@
+# v4.0.0 — Review & Publish Handoff
+
+**Date:** 2026-04-18
+**Branch:** `feature/full-journey`
+**Release tag:** v4.0.0 (not yet tagged, not yet pushed)
+**Status:** Ready for review. Tests 156/156 green. Needs human eyeball before `git push` + `npm publish`.
+
+This document is the single source of truth for what shipped in v4.0.0 and what the next agent/reviewer needs to verify before the release goes public.
+
+---
+
+## TL;DR
+
+The Qualia Framework v4.0.0 makes `/qualia-new` produce the **entire project journey** (all milestones → Handoff) upfront, enables **end-to-end auto-chaining** of the Road with `--auto`, locks down the **milestone/phase/task hierarchy**, and **rebuilds `/qualia-idk` as a real diagnostician** instead of a router alias.
+
+10 commits on `feature/full-journey` (8 feature + 1 docs + 1 release-state fix). ~28 files touched. 156/156 tests green.
+
+Two local branches, neither pushed:
+
+| Branch | HEAD | Ships |
+|---|---|---|
+| `feature/story-file-plans` | `8ae5b0e` | v3.7.0 — story-file plan format (independent, useful on its own) |
+| `feature/full-journey` | `f790554` | v4.0.0 — full journey, auto-chain, diagnostic idk (includes v3.7.0) |
+
+---
+
+## The commits on `feature/full-journey`
+
+```
+94bc119 fix(v4): correct v4.0.0 — fold qualia-idk changelog entries into initial release
+ea9e7f3 docs(v4): README, guide.md, SESSION_REPORT updated for v4.0.0 + V4_REVIEW.md handoff
+f790554 release(v4.0.0): full journey — kickoff to handoff on rails
+f62e753 fix(v4/phase-g): milestone summary cumulative task count + smoke tests
+b41a52d feat(v4/phase-f): build_count + deploy_count bump, ERP v4 payload, handoff 4-deliverables
+74dd26e feat(v4/phase-d-e): builder pre-inline + journey visualization
+400cd17 feat(v4/phase-c): auto-chain wiring across Road skills
+87af253 feat(v4/phase-b): roadmapper + qualia-new full-journey output
+2e371c2 feat(v4/phase-a): model foundation — milestones[] + readiness guards
+8ae5b0e release(v3.7.0): story-file plan format (from feature/story-file-plans)
+```
+
+**Release-point:** `94bc119` is the canonical v4.0.0 HEAD (package.json = "4.0.0", CHANGELOG has a single [4.0.0] section with `/qualia-idk` folded in). Tag v4.0.0 at this commit.
+
+---
+
+## What v4.0.0 actually changes
+
+### Hierarchy (locked down)
+```
+Project
+└─ Journey (all milestones defined upfront)
+   └─ Milestone (a release — 2-5 total, Handoff is always last)
+      └─ Phase (2-5 tasks per phase)
+         └─ Task (one commit, one verification contract)
+```
+
+- 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** (guarded by `state.js close-milestone`).
+- Milestone numbering is **contiguous** — no skipped numbers.
+
+### New artifact: `.planning/JOURNEY.md`
+The North Star. Lists every milestone with why-now + exit criteria + phase sketches. Written once during `/qualia-new`, consulted at every milestone boundary.
+
+### Auto mode (`--auto` flag)
+```
+/qualia-new --auto
+  → research runs automatically
+  → JOURNEY.md written
+  → SINGLE human approval on the whole journey
+  → plan 1 → build 1 → verify 1 → plan 2 → build 2 → verify 2 → ...
+  → [milestone boundary — HUMAN GATE: "Continue to M{N+1}?"]
+  → ... repeat until Handoff last phase ...
+  → /qualia-ship → /qualia-handoff → /qualia-report → DONE
+```
+
+**Two human gates total per project** (journey approval + each milestone boundary). Plus one halt if gap-cycle limit exceeded on a failed phase.
+
+### `/qualia-idk` now diagnostic (not a router alias)
+Spawns two isolated `Explore` subagents in parallel:
+1. **Plan view** — reads only `.planning/*`, reports what plan says we are + what should be TRUE
+2. **Code view** — reads only source code, reports what's built + what compiles + what's stubbed, cites file:line
+
+Main skill synthesizes: "What I see / The mismatch / What I think is happening / What to do next."
+
+### `/qualia` description scoped back to state routing
+Previously claimed "idk / stuck / lost / confused" triggers. Those now route to `/qualia-idk`. `/qualia` keeps "what next / what now / next command."
+
+### Schema changes (all additive, backward compatible)
+`tracking.json` gains:
+- `milestone_name` — human name of current milestone
+- `milestones[]` — array of closed milestone summaries (for ERP tree render)
+- `build_count`, `deploy_count` — now actually incremented on transitions
+
+`state.js` check output gains `milestone_name` + `milestones`.
+
+`qualia-report` ERP payload now includes all v4 fields.
+
+---
+
+## How to verify before publishing
+
+### 1. Run the test suite
+```bash
+cd /home/qualiasolutions/qualia-framework
+node --test tests/runner.js
+```
+Expected: `# pass 156 / # fail 0`.
+
+### 2. Visual smoke test of new UI commands
+```bash
+# Make a fake project
+TMP=/tmp/qualia-v4-visual && rm -rf $TMP && mkdir -p $TMP/.planning
+cat > $TMP/.planning/JOURNEY.md <<'EOF'
+---
+project: "Demo"
+---
+## Milestone 1 · Foundation
+**Why now:** Base infra.
+**Phases:**
+1. **Setup**
+2. **Auth**
+## Milestone 2 · Core Features
+**Why now:** Value delivery.
+**Phases:**
+1. **Feature A**
+2. **Feature B**
+## Milestone 3 · Handoff
+**Phases:**
+1. **Polish**
+2. **Content + SEO**
+3. **Final QA**
+4. **Handoff**
+EOF
+cat > $TMP/.planning/tracking.json <<'EOF'
+{"milestone":2,"milestone_name":"Core Features","milestones":[],"phase":1,"total_phases":2,"status":"built","lifetime":{"tasks_completed":4,"phases_completed":2,"milestones_completed":1}}
+EOF
+cat > $TMP/.planning/STATE.md <<'EOF'
+## Current Position
+Phase: 1 of 2 — Feature A
+Status: built
+Assigned to: Reviewer
+
+## Roadmap
+| # | Phase | Goal | Status |
+|---|-------|------|--------|
+| 1 | Feature A | x | built |
+| 2 | Feature B | x | — |
+EOF
+(cd $TMP && node /home/qualiasolutions/qualia-framework/bin/qualia-ui.js journey-tree .planning/JOURNEY.md)
+node /home/qualiasolutions/qualia-framework/bin/qualia-ui.js milestone-complete 1 "Foundation" "Core Features"
+node /home/qualiasolutions/qualia-framework/bin/qualia-ui.js milestone-complete 3 "Handoff" ""
+rm -rf $TMP
+```
+Expected:
+- Journey tree shows green dot on M1, teal diamond on M2 (CURRENT), dim circle on M3 (FINAL).
+- First milestone-complete banner shows `Next: Core Features`.
+- Second shows `PROJECT COMPLETE · last milestone reached`.
+
+### 3. State-machine end-to-end smoke
+Covered by test case `tests/runner.js` "milestone summary captures cumulative tasks_completed" and "build_count bumps on each 'built' transition". Both pass.
+
+### 4. Manual eyeball of key files
+Review these for v4 correctness:
+
+| File | Why |
+|---|---|
+| `templates/journey.md` | New artifact schema — is the format clear and complete? |
+| `agents/roadmapper.md` | Biggest agent rewrite — does it correctly describe the 3-file output (JOURNEY + REQUIREMENTS + ROADMAP)? |
+| `skills/qualia-new/SKILL.md` | Core flow — is the 14-step process coherent? Is `--auto` wiring clear? |
+| `skills/qualia-idk/SKILL.md` | New diagnostic — does the 2-pass isolation make sense? Is the synthesis format useful? |
+| `skills/qualia-verify/SKILL.md` | Auto-chain decision table (PASS → next phase / last phase → milestone / last milestone → ship) |
+| `skills/qualia-milestone/SKILL.md` | Reads next milestone from JOURNEY.md now, not user prompt |
+| `skills/qualia-handoff/SKILL.md` | 4 mandatory deliverables enforced |
+| `bin/state.js` lines ~975-1050 | close-milestone readiness guards + milestones[] summary append |
+| `bin/qualia-ui.js` journey-tree + milestone-complete | New visualizations |
+| `CHANGELOG.md` [4.0.0] section | Full feature list + migration notes |
+
+### 5. Backward-compat verification
+The v4 changes are designed additive. Verify by:
+```bash
+# tracking.json from an older project (no milestones[], no milestone_name)
+# should still work with state.js check
+echo '{"milestone":1,"phase":1,"total_phases":3,"status":"setup","lifetime":{"tasks_completed":0,"phases_completed":0,"milestones_completed":0,"total_phases":0}}' > /tmp/old-tracking.json
+mkdir -p /tmp/old-project/.planning && mv /tmp/old-tracking.json /tmp/old-project/.planning/tracking.json
+cat > /tmp/old-project/.planning/STATE.md <<'EOF'
+Phase: 1 of 3 — Setup
+Status: setup
+
+## Roadmap
+| # | Phase | Goal | Status |
+|---|-------|------|--------|
+| 1 | Setup | x | ready |
+| 2 | Feature | x | — |
+| 3 | Ship | x | — |
+EOF
+(cd /tmp/old-project && node /home/qualiasolutions/qualia-framework/bin/state.js check | head -20)
+rm -rf /tmp/old-project
+```
+Expected: `check` succeeds, output includes `milestones: []` and `milestone_name: ""` (hydrated by `ensureLifetime`).
+
+---
+
+## Publish checklist
+
+Once review passes:
+
+```bash
+# 1. Push both branches
+git push -u origin feature/story-file-plans
+git push -u origin feature/full-journey
+
+# 2. Merge v3.7.0 first (recommended — gives it a distinct tag in history)
+git checkout main
+git merge --ff-only feature/story-file-plans
+git tag v3.7.0
+git push origin main --tags
+
+# 3. Merge v4.0.0
+git merge --ff-only feature/full-journey
+# If fast-forward fails (unlikely since v4 branched off story-file-plans HEAD):
+#   git merge feature/full-journey    # creates a merge commit — also fine
+git tag v4.0.0
+git push origin main --tags
+
+# 4. npm publish
+npm publish
+# Expected: qualia-framework@4.0.0 goes live. Auto-update hook notifies
+# every team member's installed client on next session.
+
+# 5. Verify
+npm view qualia-framework version    # should return 4.0.0
+```
+
+### Alternative: one combined release
+If the team would rather have a single v4.0.0 release tag (skip the v3.7.0 tag):
+
+```bash
+git checkout main
+git merge --ff-only feature/full-journey
+git tag v4.0.0
+git push origin main --tags
+npm publish
+```
+(v3.7.0 work is still in the history, just not tagged as its own release.)
+
+---
+
+## Risk areas (eyeball these)
+
+1. **Auto-chain logic in `/qualia-verify`** — the decision table (PASS → next phase / last phase of milestone / last phase of Handoff / FAIL gap / FAIL limit) is described in the SKILL.md but relies on Claude to parse JOURNEY.md at runtime to detect "last phase of milestone." Smoke test didn't actually run the auto-chain because that requires live subagent invocation. **Recommended first test on merge**: run `/qualia-new --auto` on a throwaway project and watch how it handles the milestone boundary.
+
+2. **Roadmapper's new three-file output** — the rewritten agent prompt is long and complex. The roadmapper must:
+   - Generate JOURNEY.md with all milestones
+   - Assign requirements to milestones
+   - Only detail Milestone 1 in ROADMAP.md
+   - Pass `--milestone_name` to `state.js init`
+   Smoke test didn't exercise the roadmapper directly — it's only triggered by `/qualia-new`.
+
+3. **`/qualia-idk`'s two-pass isolation** — depends on `Explore` subagent correctly NOT crossing its scope. If an Explore agent reads .planning/ when told "code only" or vice versa, the diagnosis degrades. The SKILL.md has explicit "DO NOT read..." instructions but this is prompt-level enforcement, not hard boundary.
+
+4. **Builder pre-inline context** — saves tool calls but inflates prompt size. On very large projects (PROJECT.md + DESIGN.md + 5 context files could easily be 10k+ tokens), the builder's prompt might balloon. Acceptable for most projects; watch for issues on monorepos.
+
+---
+
+## Known limitations / deferred
+
+- **No visual / mockup generation** (gstack's `/design-shotgun` or Superpowers' Visual Companion). Not in v4 — could be a v4.1 feature.
+- **No cross-model review** (gstack's `/codex`). Not in v4.
+- **No cross-project vector memory** (Claude-Flow's claude-mem pattern). Current `knowledge/` is still hand-authored markdown.
+- **No IDE integration** (VS Code extension, JetBrains plugin). Claude Code CLI only.
+- **No token-budget compression** (SuperClaude's ~70% compression claim). Qualia relies on fresh-context agents instead of compression.
+
+These are all discussed in the competitive gap analysis done earlier in the session — see the chat transcript or memory for details.
+
+---
+
+## Questions for Fawzi before publish
+
+1. **Single v4.0.0 release or v3.7.0 + v4.0.0?** Default: both tags (v3.7.0 as a step release). Cleaner history. Alternative: fold into single v4.0.0.
+2. **Alpha/beta tag on npm?** `npm publish` without `--tag` goes to `latest` and every installed client auto-updates on next session. If you want a slower rollout, publish with `--tag beta` and the team opts in manually with `npm install qualia-framework@beta install`.
+3. **Do you want to dogfood v4 on an existing project before publish?** Running `npx qualia-framework@4.0.0-alpha install` locally on Sakani or another project is the safest way to verify end-to-end — especially the auto-chain which isn't covered by the unit tests.
+
+Contact for questions: Fawzi Goussous — fawzi@qualiasolutions.net
+
+---
+
+*Generated 2026-04-18 by the v4 build session. Review this doc + CHANGELOG.md [4.0.0] before publishing.*