qualia-framework 5.4.0 → 5.8.0

package/tests/bin.test.sh

@@ -1131,52 +1131,59 @@ fi
 echo ""
 echo "--- v5.0.0 (visual-polish loop addendum) ---"
 
-# 99. qualia-polish-loop SKILL.md installs
+# 99. qualia-polish SKILL.md installs (v5.8: polish-loop consolidated into --loop flag)
 TMP=$(mktmp)
 echo "QS-FAWZI-01" | HOME="$TMP" $NODE "$INSTALL_JS" >/dev/null 2>&1
-if [ -f "$TMP/.claude/skills/qualia-polish-loop/SKILL.md" ]; then
-  pass "qualia-polish-loop SKILL.md installs"
+if [ -f "$TMP/.claude/skills/qualia-polish/SKILL.md" ]; then
+  pass "qualia-polish SKILL.md installs"
 else
-  fail_case "qualia-polish-loop SKILL.md missing after install"
+  fail_case "qualia-polish SKILL.md missing after install"
 fi
 
-# 100. qualia-polish-loop REFERENCE.md installs
-if [ -f "$TMP/.claude/skills/qualia-polish-loop/REFERENCE.md" ]; then
-  pass "qualia-polish-loop REFERENCE.md installs"
+# 100. qualia-polish REFERENCE.md installs (carries the loop spec)
+if [ -f "$TMP/.claude/skills/qualia-polish/REFERENCE.md" ]; then
+  pass "qualia-polish REFERENCE.md installs"
 else
-  fail_case "qualia-polish-loop REFERENCE.md missing after install"
+  fail_case "qualia-polish REFERENCE.md missing after install"
 fi
 
-# 101. qualia-polish-loop SKILL.md references the design rubric
-if grep -q "design-rubric.md" "$TMP/.claude/skills/qualia-polish-loop/SKILL.md"; then
-  pass "qualia-polish-loop references design-rubric.md"
+# 101. qualia-polish SKILL.md references the design rubric
+if grep -q "design-rubric.md" "$TMP/.claude/skills/qualia-polish/SKILL.md"; then
+  pass "qualia-polish references design-rubric.md"
 else
-  fail_case "qualia-polish-loop missing rubric reference"
+  fail_case "qualia-polish missing rubric reference"
 fi
 
-# 102. qualia-polish-loop REFERENCE.md has the anchored vision eval prompt
-if grep -q "DEFAULT TO 3" "$TMP/.claude/skills/qualia-polish-loop/REFERENCE.md"; then
-  pass "qualia-polish-loop REFERENCE.md has anchored rubric prompt"
+# 102. qualia-polish REFERENCE.md has the anchored vision eval prompt
+if grep -q "DEFAULT TO 3" "$TMP/.claude/skills/qualia-polish/REFERENCE.md"; then
+  pass "qualia-polish REFERENCE.md has anchored rubric prompt"
 else
-  fail_case "qualia-polish-loop REFERENCE.md missing anchored rubric"
+  fail_case "qualia-polish REFERENCE.md missing anchored rubric"
 fi
 
-# 103. qualia-polish-loop SKILL.md has regression detection (LOOP_REGRESSION_DETECTED)
-if grep -q "LOOP_REGRESSION_DETECTED" "$TMP/.claude/skills/qualia-polish-loop/SKILL.md"; then
-  pass "qualia-polish-loop has regression kill-switch"
+# 103. qualia-polish REFERENCE.md has regression detection (LOOP_REGRESSION_DETECTED)
+if grep -q "LOOP_REGRESSION_DETECTED" "$TMP/.claude/skills/qualia-polish/REFERENCE.md"; then
+  pass "qualia-polish has regression kill-switch"
 else
-  fail_case "qualia-polish-loop missing regression kill-switch"
+  fail_case "qualia-polish missing regression kill-switch"
+fi
+
+# 103b. qualia-polish SKILL.md documents the --loop flag
+if grep -q -- "--loop" "$TMP/.claude/skills/qualia-polish/SKILL.md"; then
+  pass "qualia-polish SKILL.md documents --loop flag"
+else
+  fail_case "qualia-polish SKILL.md missing --loop documentation"
 fi
 
 # 104. score.mjs exists in the framework skill scripts
-if [ -f "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/score.mjs" ]; then
+if [ -f "$FRAMEWORK_DIR/skills/qualia-polish/scripts/score.mjs" ]; then
   pass "score.mjs exists in skill scripts"
 else
   fail_case "score.mjs missing from skill scripts"
 fi
 
 # 105. score.mjs computes pass correctly (all dims >= 3)
-SCORE_OUT=$(echo '{"typography":3,"color":3,"spatial":3,"layout":3,"shadow":3,"motion":3,"microcopy":3,"container":3}' | $NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/score.mjs" 2>&1)
+SCORE_OUT=$(echo '{"typography":3,"color":3,"spatial":3,"layout":3,"shadow":3,"motion":3,"microcopy":3,"container":3}' | $NODE "$FRAMEWORK_DIR/skills/qualia-polish/scripts/score.mjs" 2>&1)
 EXIT=$?
 if [ "$EXIT" -eq 0 ] && echo "$SCORE_OUT" | grep -q '"pass": true'; then
   pass "score.mjs pass on all-3 scores"
@@ -1185,7 +1192,7 @@ else
 fi
 
 # 106. score.mjs computes fail correctly (one dim < 3)
-SCORE_OUT=$(echo '{"typography":2,"color":3,"spatial":3,"layout":3,"shadow":3,"motion":3,"microcopy":3,"container":3}' | $NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/score.mjs" 2>&1)
+SCORE_OUT=$(echo '{"typography":2,"color":3,"spatial":3,"layout":3,"shadow":3,"motion":3,"microcopy":3,"container":3}' | $NODE "$FRAMEWORK_DIR/skills/qualia-polish/scripts/score.mjs" 2>&1)
 EXIT=$?
 if [ "$EXIT" -eq 1 ] && echo "$SCORE_OUT" | grep -q '"pass": false'; then
   pass "score.mjs fail on dim < 3"
@@ -1193,38 +1200,38 @@ else
   fail_case "score.mjs fail computation" "exit=$EXIT"
 fi
 
-# 107. qualia-road references qualia-polish-loop
-if grep -q "qualia-polish-loop" "$TMP/.claude/skills/qualia-road/SKILL.md"; then
-  pass "qualia-road references qualia-polish-loop"
+# 107. qualia-road references the polish loop (now via --loop flag)
+if grep -qE "qualia-polish --loop|/qualia-polish --loop" "$TMP/.claude/skills/qualia-road/SKILL.md"; then
+  pass "qualia-road references /qualia-polish --loop"
 else
-  fail_case "qualia-road missing qualia-polish-loop reference"
+  fail_case "qualia-road missing /qualia-polish --loop reference"
 fi
 
 # 108. package.json version is 5.x (5.1+ accepted; v5.1 / v5.2 share the v5 line)
-if grep -qE '"5\.[1234]\.' "$FRAMEWORK_DIR/package.json"; then
+if grep -qE '"5\.([1-9]|[1-9][0-9])\.' "$FRAMEWORK_DIR/package.json"; then
   pass "package.json version is 5.x"
 else
   fail_case "package.json version not 5.x"
 fi
 
 # 109. loop.mjs installs (orchestrator)
-if [ -f "$TMP/.claude/skills/qualia-polish-loop/scripts/loop.mjs" ]; then
-  pass "qualia-polish-loop scripts/loop.mjs installs"
+if [ -f "$TMP/.claude/skills/qualia-polish/scripts/loop.mjs" ]; then
+  pass "qualia-polish scripts/loop.mjs installs"
 else
   fail_case "scripts/loop.mjs missing — install.js scripts/ subfolder copy broken"
 fi
 
 # 110. playwright-capture.mjs installs (capture helper)
-if [ -f "$TMP/.claude/skills/qualia-polish-loop/scripts/playwright-capture.mjs" ]; then
-  pass "qualia-polish-loop scripts/playwright-capture.mjs installs"
+if [ -f "$TMP/.claude/skills/qualia-polish/scripts/playwright-capture.mjs" ]; then
+  pass "qualia-polish scripts/playwright-capture.mjs installs"
 else
   fail_case "scripts/playwright-capture.mjs missing"
 fi
 
 # 111. fixtures/ subfolder installs (self-test pages)
-if [ -f "$TMP/.claude/skills/qualia-polish-loop/fixtures/clean.html" ] && \
-   [ -f "$TMP/.claude/skills/qualia-polish-loop/fixtures/broken.html" ]; then
-  pass "qualia-polish-loop fixtures/ installs (clean.html + broken.html)"
+if [ -f "$TMP/.claude/skills/qualia-polish/fixtures/clean.html" ] && \
+   [ -f "$TMP/.claude/skills/qualia-polish/fixtures/broken.html" ]; then
+  pass "qualia-polish fixtures/ installs (clean.html + broken.html)"
 else
   fail_case "fixtures/ subfolder not copied by install.js"
 fi
@@ -1237,7 +1244,7 @@ else
 fi
 
 # 113. loop.mjs parses as valid Node ESM
-EXIT=0; $NODE --check "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" 2>/dev/null || EXIT=$?
+EXIT=0; $NODE --check "$FRAMEWORK_DIR/skills/qualia-polish/scripts/loop.mjs" 2>/dev/null || EXIT=$?
 if [ "$EXIT" -eq 0 ]; then
   pass "loop.mjs parses as valid Node ESM"
 else
@@ -1245,7 +1252,7 @@ else
 fi
 
 # 114. playwright-capture.mjs parses as valid Node ESM
-EXIT=0; $NODE --check "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/playwright-capture.mjs" 2>/dev/null || EXIT=$?
+EXIT=0; $NODE --check "$FRAMEWORK_DIR/skills/qualia-polish/scripts/playwright-capture.mjs" 2>/dev/null || EXIT=$?
 if [ "$EXIT" -eq 0 ]; then
   pass "playwright-capture.mjs parses as valid Node ESM"
 else
@@ -1255,7 +1262,7 @@ fi
 # 115. loop.mjs init creates a valid state file
 TMP_STATE=$(mktmp)/qpl-state.json
 mkdir -p "$(dirname "$TMP_STATE")"
-EXIT=0; $NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" init \
+EXIT=0; $NODE "$FRAMEWORK_DIR/skills/qualia-polish/scripts/loop.mjs" init \
   --state "$TMP_STATE" --url "http://localhost:3000" --max 4 --budget 50000 >/dev/null 2>&1 || EXIT=$?
 if [ "$EXIT" -eq 0 ] && [ -f "$TMP_STATE" ] && grep -q '"verdict": "pending"' "$TMP_STATE"; then
   pass "loop.mjs init creates valid state.json"
@@ -1267,7 +1274,7 @@ fi
 TMP_STATE2=$(mktmp)/qpl-kill.json
 TMP_EVAL=$(mktmp)/qpl-eval.json
 mkdir -p "$(dirname "$TMP_STATE2")" "$(dirname "$TMP_EVAL")"
-$NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" init \
+$NODE "$FRAMEWORK_DIR/skills/qualia-polish/scripts/loop.mjs" init \
   --state "$TMP_STATE2" --url "http://localhost:3000" --max 8 >/dev/null 2>&1
 # write 3 identical evals
 KILL_OK=true
@@ -1282,7 +1289,7 @@ for ITER in 1 2 3; do
   "pass": false
 }
 EOF
-  EXIT=0; $NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" record \
+  EXIT=0; $NODE "$FRAMEWORK_DIR/skills/qualia-polish/scripts/loop.mjs" record \
     --state "$TMP_STATE2" --eval "$TMP_EVAL" >/dev/null 2>&1 || EXIT=$?
   if [ "$ITER" -lt 3 ] && [ "$EXIT" -ne 1 ]; then KILL_OK=false; fi
   if [ "$ITER" -eq 3 ] && [ "$EXIT" -ne 3 ]; then KILL_OK=false; fi
@@ -1430,7 +1437,7 @@ fi
 
 # 128. package.json bumped to 5.x (5.1+ accepted; 5.2 is the v5.2 release)
 PKG_V=$($NODE -e 'console.log(require("'"$FRAMEWORK_DIR"'/package.json").version)')
-if echo "$PKG_V" | grep -qE "^5\.[1234]\."; then
+if echo "$PKG_V" | grep -qE "^5\.([1-9]|[1-9][0-9])\."; then
   pass "package.json version bumped to 5.x ($PKG_V)"
 else
   fail_case "package.json version not 5.x" "got=$PKG_V"
@@ -1442,7 +1449,7 @@ echo "--- v5.2.0 (polish-loop reliability) ---"
 # 129. loop.mjs init accepts --routes and stores the URL list
 TMP_S=$(mktmp)/qpl-routes.json
 mkdir -p "$(dirname "$TMP_S")"
-EXIT=0; $NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" init \
+EXIT=0; $NODE "$FRAMEWORK_DIR/skills/qualia-polish/scripts/loop.mjs" init \
   --state "$TMP_S" \
   --routes "http://x.test/a,http://x.test/b,http://x.test/c" \
   --max 4 >/dev/null 2>&1 || EXIT=$?
@@ -1466,7 +1473,7 @@ fi
 # 131. loop.mjs init accepts --reduced-motion and records it in state
 TMP_S2=$(mktmp)/qpl-rm.json
 mkdir -p "$(dirname "$TMP_S2")"
-EXIT=0; $NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" init \
+EXIT=0; $NODE "$FRAMEWORK_DIR/skills/qualia-polish/scripts/loop.mjs" init \
   --state "$TMP_S2" --url "http://x.test/" --reduced-motion >/dev/null 2>&1 || EXIT=$?
 if [ "$EXIT" -eq 0 ] && grep -q '"reduced_motion": true' "$TMP_S2"; then
   pass "loop.mjs init --reduced-motion records state.reduced_motion=true"
@@ -1475,7 +1482,7 @@ else
 fi
 
 # 132. playwright-capture.mjs accepts --reduced-motion (parses without error)
-EXIT=0; OUT=$($NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/playwright-capture.mjs" --help 2>&1) || EXIT=$?
+EXIT=0; OUT=$($NODE "$FRAMEWORK_DIR/skills/qualia-polish/scripts/playwright-capture.mjs" --help 2>&1) || EXIT=$?
 if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q -- "--reduced-motion"; then
   pass "playwright-capture.mjs --help documents --reduced-motion"
 else
@@ -1485,7 +1492,7 @@ fi
 # 133. loop.mjs init rejects when neither --url nor --routes given
 TMP_S3=$(mktmp)/qpl-nourl.json
 mkdir -p "$(dirname "$TMP_S3")"
-EXIT=0; $NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" init \
+EXIT=0; $NODE "$FRAMEWORK_DIR/skills/qualia-polish/scripts/loop.mjs" init \
   --state "$TMP_S3" --max 4 >/dev/null 2>&1 || EXIT=$?
 if [ "$EXIT" -eq 2 ]; then
   pass "loop.mjs init rejects missing --url/--routes (exit 2)"
@@ -1496,9 +1503,9 @@ fi
 # 134. loop.mjs report mentions multi-route when state.urls > 1
 TMP_S4=$(mktmp)/qpl-rep.json
 mkdir -p "$(dirname "$TMP_S4")"
-$NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" init \
+$NODE "$FRAMEWORK_DIR/skills/qualia-polish/scripts/loop.mjs" init \
   --state "$TMP_S4" --routes "http://a/,http://b/" >/dev/null 2>&1
-REP=$($NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" report --state "$TMP_S4" 2>&1)
+REP=$($NODE "$FRAMEWORK_DIR/skills/qualia-polish/scripts/loop.mjs" report --state "$TMP_S4" 2>&1)
 if echo "$REP" | grep -q "URLs (2)"; then
   pass "loop.mjs report renders multi-route header"
 else
@@ -1512,27 +1519,32 @@ echo "--- v5.3.0 (Matt Pocock gaps: prd, hook-gen, parallel-interface) ---"
 TMP=$(mktmp)
 echo "QS-FAWZI-01" | HOME="$TMP" $NODE "$INSTALL_JS" >/dev/null 2>&1
 
-# 135. qualia-prd skill installs
-if [ -f "$TMP/.claude/skills/qualia-prd/SKILL.md" ]; then
-  pass "qualia-prd skill installs"
+# 135-137. /qualia-prd removed in v5.8.0 (was deprecated, overlapped /qualia-discuss).
+# Assert non-existence so the framework cannot accidentally re-ship it.
+if [ ! -f "$TMP/.claude/skills/qualia-prd/SKILL.md" ]; then
+  pass "qualia-prd removed (v5.8.0 cleanup)"
 else
-  fail_case "qualia-prd SKILL.md missing after install"
+  fail_case "qualia-prd unexpectedly present after v5.8.0 removal"
 fi
 
-# 136. qualia-prd description mentions PRD synthesis from conversation
-if grep -q "synthesize\|Synthesize" "$TMP/.claude/skills/qualia-prd/SKILL.md" \
-   && grep -q "/qualia-issues" "$TMP/.claude/skills/qualia-prd/SKILL.md"; then
-  pass "qualia-prd describes synthesis flow + pairs with /qualia-issues"
+# v5.8.0: assert /qualia-quick + /qualia-task also removed (were deprecated in v5.7).
+if [ ! -f "$TMP/.claude/skills/qualia-quick/SKILL.md" ]; then
+  pass "qualia-quick removed (v5.8.0 cleanup)"
 else
-  fail_case "qualia-prd missing synthesis or /qualia-issues link"
+  fail_case "qualia-quick unexpectedly present after v5.8.0 removal"
 fi
 
-# 137. qualia-prd documents fork-based token discipline
-if grep -qE "[Ff]orked subagent|fork.*subagent" "$TMP/.claude/skills/qualia-prd/SKILL.md" \
-   && grep -q "Token discipline" "$TMP/.claude/skills/qualia-prd/SKILL.md"; then
-  pass "qualia-prd documents fork-based synthesis (token discipline)"
+if [ ! -f "$TMP/.claude/skills/qualia-task/SKILL.md" ]; then
+  pass "qualia-task removed (v5.8.0 cleanup)"
 else
-  fail_case "qualia-prd missing fork/token-discipline section"
+  fail_case "qualia-task unexpectedly present after v5.8.0 removal"
+fi
+
+# v5.8.0: assert /qualia-feature is the canonical single-feature surface.
+if [ -f "$TMP/.claude/skills/qualia-feature/SKILL.md" ]; then
+  pass "qualia-feature installed (canonical single-feature surface)"
+else
+  fail_case "qualia-feature missing after install"
 fi
 
 # 138. qualia-hook-gen skill installs
@@ -1577,12 +1589,42 @@ fi
 
 # 143. package.json version is 5.x (5.1+ accepted; v5.3 is the v5.3 release)
 PKG_V=$($NODE -e 'console.log(require("'"$FRAMEWORK_DIR"'/package.json").version)')
-if echo "$PKG_V" | grep -qE "^5\.[1234]\."; then
+if echo "$PKG_V" | grep -qE "^5\.([1-9]|[1-9][0-9])\."; then
   pass "package.json version is 5.x ($PKG_V) — v5.3 accepted"
 else
   fail_case "package.json version not 5.x" "got=$PKG_V"
 fi
 
+echo ""
+echo "--- ERP shift-report contract ---"
+
+# 144. qualia-report describes clock-out as truthful shift submission, not task completion
+if grep -qi "daily shift report" "$TMP/.claude/skills/qualia-report/SKILL.md" \
+   && grep -qi "not a task-completion ceremony" "$TMP/.claude/skills/qualia-report/SKILL.md" \
+   && grep -qi "What happened during your shift" "$TMP/.claude/skills/qualia-report/SKILL.md"; then
+  pass "qualia-report frames clock-out as shift submission, not task completion"
+else
+  fail_case "qualia-report missing shift-submission contract"
+fi
+
+# 145. ERP contract documents the date model: project, milestone, employee submission
+if grep -q "Project deadline" "$FRAMEWORK_DIR/docs/erp-contract.md" \
+   && grep -q "Milestone deadline" "$FRAMEWORK_DIR/docs/erp-contract.md" \
+   && grep -q "Employee submission date" "$FRAMEWORK_DIR/docs/erp-contract.md" \
+   && grep -q "Phase and task counters remain framework telemetry" "$FRAMEWORK_DIR/docs/erp-contract.md"; then
+  pass "ERP contract documents project/milestone/submission date model"
+else
+  fail_case "ERP contract missing date-model clarification"
+fi
+
+# 146. Project glossary keeps framework tasks internal to agent execution
+if grep -q "framework-internal execution unit" "$FRAMEWORK_DIR/templates/CONTEXT.md" \
+   && grep -q "ERP tracks project deadlines, milestone deadlines, and employee shift submissions" "$FRAMEWORK_DIR/templates/CONTEXT.md"; then
+  pass "CONTEXT template distinguishes internal tasks from ERP workflow"
+else
+  fail_case "CONTEXT template missing framework-task vs ERP-workflow distinction"
+fi
+
 echo ""
 echo "=== Results: $PASS passed, $FAIL failed ==="
 [ "$FAIL" -eq 0 ] && exit 0 || exit 1

package/tests/lib.test.sh

@@ -57,6 +57,27 @@ console.log(errs.length > 0 ? "REJECTED" : "ACCEPTED");
 ')
 [ "$OUT" = "REJECTED" ] && ok "rejects malformed contract" || fail "malformed accepted"
 
+OUT=$($NODE -e '
+const pc = require("'"$PC"'");
+const slop = {
+  version: 1, phase: 1, goal: "x", why: "y",
+  generated_at: "t", generated_by: "planner", source_plan_hash: "h",
+  success_criteria: ["sc"],
+  tasks: [{
+    id: "T1", title: "t", wave: 1, depends_on: [],
+    files_modify: [], files_create: [], files_delete: [],
+    acceptance_criteria: ["minimal implementation of login"],
+    action: "Add hardcoded for now placeholder, will be wired later",
+    context_files: [],
+    verification: [{ type: "file-exists", path: "a.ts" }]
+  }]
+};
+const errs = pc.validate(slop);
+const hits = errs.filter(e => /scope-reduction/.test(e));
+console.log(hits.length >= 2 ? "DETECTED" : "MISSED:" + errs.join(";"));
+')
+[ "$OUT" = "DETECTED" ] && ok "detects scope-reduction phrases in action + acceptance_criteria" || fail "scope-reduction missed: $OUT"
+
 OUT=$($NODE -e '
 const pc = require("'"$PC"'");
 const c = {

package/tests/slop-detect.test.sh

@@ -121,8 +121,8 @@ else
   fail_case "gradient detection" "expected exit 1, got $EXIT_CODE"
 fi
 
-# ── Existing fixture: skills/qualia-polish-loop/fixtures/broken.html ──
-FIXTURE="$(cd "$(dirname "$0")/.." && pwd)/skills/qualia-polish-loop/fixtures/broken.html"
+# ── Existing fixture: skills/qualia-polish/fixtures/broken.html ──
+FIXTURE="$(cd "$(dirname "$0")/.." && pwd)/skills/qualia-polish/fixtures/broken.html"
 if [ -f "$FIXTURE" ]; then
   EXIT_CODE=0
   $NODE "$SLOP_DETECT" "$FIXTURE" >/dev/null 2>&1 || EXIT_CODE=$?

package/docs/archive/session-report-2026-04-18.md

@@ -1,199 +0,0 @@
-# Session Report — 2026-04-18
-
-**Project:** qualia-framework
-**Branch:** feature/full-journey (local, not pushed)
-**Released:** v3.7.0 (staged on feature/story-file-plans) and **v4.0.0** (staged on feature/full-journey)
-**Owner:** Fawzi Goussous
-**Duration:** ~4 hours
-
-## What this session shipped
-
-Two releases staged on separate feature branches, ready for push + merge + `npm publish`.
-
-| Tag | Branch | Commits | Theme |
-|---|---|---|---|
-| **v3.7.0** | feature/story-file-plans | 1 commit (8ae5b0e) | Story-file plan format — every phase plan task carries inline Why, Acceptance Criteria, Validation, explicit Depends on |
-| **v4.0.0** | feature/full-journey | 8 commits total (includes v3.7.0) | Full Journey release — /qualia-new maps the entire arc to handoff, --auto chains the Road end-to-end, milestone hierarchy locked, /qualia-idk rebuilt as diagnostician |
-
-**Test suite:** 150 → 156 green (+6 v4 coverage, 0 regressions).
-**Package:** version bumped 3.6.0 → 4.0.0.
-**Release candidate:** v4.0.0 commit is `f790554` on feature/full-journey.
-
-## Background & trigger
-
-Fawzi came in with three pain points from Sakani's ERP view:
-1. "Unphased Tasks" and "Phase 0: Central Bank Demo" rendering at the same tree level as "Milestone 1", "Milestone 2", etc. — milestones collapsed into single phases, numbering skipped (missing M5).
-2. `/qualia-new` stops at v1 — team improvises subsequent milestones, no clear path to handoff.
-3. Team members don't understand the framework's dev cycle. Need something a non-technical person can follow without getting lost.
-
-Plus: "make it sexier," personalize the Qualia experience, enhance every command for best practices, ship a stable v4.0.
-
-## The approach
-
-Split the work into labeled phases on a feature branch so commits tell the story:
-
-### v3.7.0 prerequisite — story-file plans
-- `templates/plan.md` rewritten to 7-field story-file format (Wave, Files, Depends on, Why, Acceptance Criteria, Action, Validation, Context + optional Persona)
-- `agents/planner.md` generates the new format
-- `agents/plan-checker.md` validates the 7 fields and cross-checks wave↔deps consistency
-- `agents/builder.md` reads rationale, respects Depends on, runs Validation before commit
-- `agents/verifier.md` adds 3-layer check (phase Success Criteria + per-task AC + Verification Contract)
-- `bin/qualia-ui.js` adds `plan-summary` command — terminal dashboard with colored persona chips, dependency arrows, AC/check counts per task
-- `bin/state.js` accepts both legacy `Done when:` and new `Acceptance Criteria:` anchors (backward-compatible)
-
-Committed on `feature/story-file-plans` as v3.7.0 (`8ae5b0e`). Standalone useful release; branched v4 off of it.
-
-### v4.0.0 — Full Journey, phased
-
-**Phase A — Model foundation** (`2e371c2`)
-- `templates/journey.md` — new JOURNEY.md schema (hard ceiling 5 milestones, hard floor 2, final milestone always Handoff with 4 fixed phases)
-- `tracking.json` gains `milestone_name`, `milestones[]` (array of closed milestone summaries)
-- `state.js close-milestone` readiness guards: MILESTONE_NOT_READY, MILESTONE_TOO_SMALL (both bypassable with --force)
-- `state.js init` accepts `--milestone_name` and preserves milestones[] across re-init
-- Tests: +4
-
-**Phase B — Roadmapper + /qualia-new full-journey output** (`87af253`)
-- `agents/roadmapper.md` rewritten: now produces JOURNEY.md (all milestones) + REQUIREMENTS.md (grouped by milestone) + ROADMAP.md (Milestone 1's phase detail only)
-- **Dropped** the old "no review/deploy/handoff phases" rule. **Replaced** with: final milestone is always literally named "Handoff" with fixed 4 phases.
-- `skills/qualia-new/SKILL.md` rewritten: always runs research (no more `workflow.research` gate), single approval on the whole journey, new `--auto` flag
-- `agents/research-synthesizer.md` thinks across all milestones
-- `skills/qualia-milestone/SKILL.md` reads next milestone from JOURNEY.md (no longer asks user)
-- `templates/requirements.md` multi-milestone format with standard Handoff section (HAND-01..HAND-15)
-- `templates/roadmap.md` scoped to current milestone only
-
-**Phase C — Auto-chain wiring** (`400cd17`)
-- `--auto` flag added to `/qualia-plan`, `/qualia-build`, `/qualia-verify`, `/qualia-milestone`
-- Auto-chain decision table in `/qualia-verify`: PASS → next phase OR milestone close OR ship+handoff; FAIL → gap closure OR halt at limit
-- Two human gates total per project: journey approval + each milestone boundary
-
-**Phase D+E — Builder pre-inline + journey visualization** (`74dd26e`)
-- Builder pre-inlines PROJECT.md + DESIGN.md + Context files into agent prompt BEFORE spawning (GSD-pattern borrowing, saves 3-5 Read calls per task)
-- `qualia-ui.js journey-tree` renders JOURNEY.md as ASCII ladder (green shipped, teal current, dim future, [FINAL] tag for Handoff)
-- `qualia-ui.js milestone-complete` celebration banner
-- 5 new banner actions: milestone ◆, journey ◯, auto ⚡, research ◱, roadmap ◐
-- `/qualia` router renders journey-tree for "you are here" orientation
-- `/qualia-milestone` renders journey-tree + milestone-complete
-
-**Phase F — Ship-side fields + handoff deliverables** (`b41a52d`)
-- `state.js` bumps `build_count` on each 'built' transition, `deploy_count` on each 'shipped' (previously never incremented)
-- `qualia-report` ERP payload now includes all v4 fields (project_id, team_id, git_remote, milestone_name, milestones[], build_count, deploy_count, session_started_at, last_pushed_at)
-- `/qualia-handoff` rewritten: explicit 4 mandatory deliverables — production URL verified (HTTP + latency + auth), docs updated, `.planning/archive/` check, final ERP report
-
-**Phase G — Smoke test fix + coverage** (`f62e753`)
-- Bug fix: close-milestone summary was recording current phase's tasks, not cumulative milestone total. Fixed via `lifetime.tasks_completed − sum(prior milestones[].tasks_completed)`
-- Tests: +2 (cumulative task count, build_count bump)
-
-**Release (`f790554`)**
-- Single unified v4.0.0 release commit
-- Package bumped 3.7.0 → 4.0.0
-- CHANGELOG.md v4.0.0 entry with full feature list + migration notes
-- `/qualia-idk` rebuilt as real diagnostician (was briefly v4.0.1 in the branch history, folded into v4.0.0 per owner request)
-
-### The `/qualia-idk` rebuild (folded into v4.0.0)
-
-Before: thin one-line alias to `/qualia`.
-
-Now: interpretive diagnostic. When user says "I don't know what's going on" / "something feels off":
-1. Spawns **Plan view** Explore subagent — reads only `.planning/*`, reports what plan says
-2. Spawns **Code view** Explore subagent in parallel — reads only source code, reports what's actually built, cites file:line
-3. Synthesizes: structured "What I see / The mismatch / What I think is happening / What to do next" in plain language
-4. Maps recommendations to existing commands where applicable
-
-`/qualia` description scoped back to mechanical state routing — no longer claims "idk/stuck/lost/confused" triggers (those route to `/qualia-idk` now).
-
-## Competitive research completed
-
-During the session, ran deep research on competing Claude Code frameworks:
-- **Superpowers** (Jesse Vincent) — 93K stars — rigid 5-phase gates, Visual Companion, cross-agent portability
-- **BMAD-METHOD** — 43K stars — 12-19 named role agents, story files, expansion packs
-- **gstack** (Garry Tan) — 74K stars — 23-role team, persistent browser daemon, /codex cross-model review
-- **GSD** (Get Shit Done, v1+v2) — 54K + 6K stars — state-machine auto-advance, pre-inlined dispatch, adaptive replanning
-- **SuperClaude, Agent OS, Context Engineering/PRP, Claude-Flow, Cursor 2.0, Windsurf** — broader landscape
-
-Patterns borrowed in v4.0.0:
-- **Story-file plan format** (BMAD) — inline rationale + acceptance criteria
-- **State-machine auto-advance** (GSD v2) — the --auto chain
-- **Pre-inline context at dispatch** (GSD v2) — builder's <pre-loaded-context> block
-- **Journey-as-first-class-artifact** (NotebookLM synthesis of Qualia's own docs)
-
-Patterns deferred to v4.1+:
-- Visual/mockup generation (gstack design-shotgun, Superpowers Visual Companion)
-- Cross-model review (gstack /codex)
-- Cross-project vector memory (claude-mem, Claude-Flow)
-- IDE integration
-- Token-budget compression
-
-## Verification at checkpoint
-
-```
-✅ Git            8 commits clean on feature/full-journey
-✅ Tests          156/156 pass
-✅ Smoke          state transitions + close-milestone + milestones[] summary verified on scratch project
-✅ UI             journey-tree + milestone-complete render correctly with real fixtures
-✅ Backward compat  older tracking.json without milestones[]/milestone_name still passes state.js check
-✅ No regressions Vs v3.6 baseline — all 150 existing tests still pass
-✅ Package        version 4.0.0, ready for `npm publish`
-✅ Handoff        V4_REVIEW.md written for next agent
-```
-
-## Pending (not done by this session)
-
-- **Git push** — both branches are local only
-- **Merge to main** — owner decides merge strategy (recommend v3.7.0 tag then v4.0.0 tag)
-- **`npm publish`** — requires owner auth
-- **Tag creation** — after merge
-- **Live auto-chain verification** — smoke tests covered state machine; the --auto chain (which spawns planner→builder→verifier subagents in sequence) wasn't exercised end-to-end. Recommended first real test is on a throwaway project post-publish.
-- **ERP-side updates** — v4 tracking.json fields are additive; ERP should accept them via its existing Zod strip-unknowns pattern, but worth verifying on deploy.
-
-## Files the next reviewer should eyeball
-
-Priority order (highest leverage first):
-
-1. `V4_REVIEW.md` — this file lives in repo root, written as the handoff doc
-2. `CHANGELOG.md` [4.0.0] section — full feature list
-3. `templates/journey.md` — new artifact schema
-4. `agents/roadmapper.md` — biggest agent rewrite
-5. `skills/qualia-new/SKILL.md` — core flow, 14 steps
-6. `skills/qualia-idk/SKILL.md` — new diagnostic
-7. `skills/qualia-verify/SKILL.md` — auto-chain decision table
-8. `skills/qualia-handoff/SKILL.md` — 4 deliverables enforcement
-9. `bin/state.js` close-milestone (~975-1050) — readiness guards + summary append
-10. `bin/qualia-ui.js` journey-tree + milestone-complete functions
-
-## Recommended publish sequence
-
-```bash
-# Push both branches
-git push -u origin feature/story-file-plans
-git push -u origin feature/full-journey
-
-# Merge v3.7.0 to main, tag, push
-git checkout main
-git merge --ff-only feature/story-file-plans
-git tag v3.7.0
-git push origin main --tags
-
-# Merge v4.0.0 to main, tag, push
-git merge --ff-only feature/full-journey
-git tag v4.0.0
-git push origin main --tags
-
-# Publish
-npm publish
-npm view qualia-framework version   # should return 4.0.0
-```
-
-## Known limitations / open questions
-
-1. **Auto-chain not live-tested.** Unit tests cover state transitions; subagent chaining is covered by the skill prompt text but not exercised. First real project run will reveal edge cases.
-2. **Milestone-summary `tasks_completed` accuracy** depends on lifetime counter deltas. Works if close-milestone is the only consumer — verified in test suite.
-3. **/qualia-idk two-pass isolation** depends on Explore subagent respecting the "do not read .planning/" and "do not read source code" instructions. Prompt-level enforcement, not hard boundary.
-4. **Builder pre-inline** inflates prompt size for monorepos with large DESIGN.md + multiple context files. Acceptable for most projects; could be optimized in v4.1.
-
-## For questions
-
-Contact: Fawzi Goussous — fawzi@qualiasolutions.net
-
----
-
-*Written 2026-04-18 at release-candidate time. Supersedes the 2026-04-17 session report covering v3.4.2 / v3.5.0 / v3.6.0.*