qualia-framework 7.1.0 → 7.2.0

package/CHANGELOG.md

@@ -8,6 +8,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > Note: git tags for historical versions were not retained; commit references are approximate
 > and dates reflect commit history rather than npm publish timestamps.
 
+## [7.2.0] - 2026-06-25 (journey spine — lifecycle UX for employees)
+
+A cosmetic/UX layer that gives an employee a continuous sense of place and
+momentum across the whole lifecycle — install → start → work → finish — reusing
+the existing teal palette and glyph set. No new commands to learn; the framework
+just shows "where am I, what's my forward motion, what's the one next move" at
+every touchpoint.
+
+### Added
+- **`qualia-ui.js spine`** — compact horizontal milestone ladder
+  (`M1 ●──M2 ◆──M3 ○`) with a caret aligned exactly beneath the current
+  milestone. Rendered by the session-start banner so the journey map is the
+  first thing an employee sees. Self-skips on single-milestone projects.
+- **`qualia-ui.js onboard <name>`** — first-run mental-model card (Plan → Build
+  → Verify → Ship + the one first move). Shown after install for non-OWNER
+  roles only.
+- **`qualia-ui.js phase-complete <n> <name> [k=v…]`** — per-phase celebration
+  with a milestone progress bar and optional streak; wired into `/qualia-ship`.
+- **`qualia-ui.js clockout <name> [k=v…]`** — end-of-day report card (shipped
+  counts, milestone %, streak); wired into `/qualia-report`. Every metric
+  self-omits when its data is unavailable — never fabricates.
+- **`barTicks(done,total,width)`** — reusable `▰▱` micro-bar helper.
+- **Always-visible progress in the statusline** — the phase pill now carries a
+  `▰▰▰▱▱` bar (`P3/5 ▰▰▰▱▱`) so forward motion is ambient while working.
+
+### Tests
+- New suite `journey-spine.test.sh` (33 cases): barTicks scaling/clamping, all
+  four cards, spine caret-alignment (exact column match), self-skip paths, and
+  the statusline bar. Full suite green: **28 shell suites + 179 node tests**.
+
 ## [7.1.0] - 2026-06-25 (harness gates — hallucinated deps, secrets, model routing)
 
 Hardening pass: reviewed Google's "The New SDLC With Vibe Coding" whitepaper

package/bin/install.js

@@ -1572,6 +1572,12 @@ function printSummary({ member, target, claudeInstalled }) {
   console.log(
     `  ${DIM}              performance audit. Opt out:${RESET} ${TEAL}erp.capturePrompts=false${RESET} ${DIM}in ~/.claude/.qualia-config.json${RESET}`
   );
+  // New employees get the milestone mental model up front — OWNERs already
+  // know how the flow works, so we skip the card for them to avoid noise.
+  if (member.role !== "OWNER") {
+    try { ui.onboard(member.name); } catch {}
+  }
+
   console.log("");
   console.log(`  ${DIM2}${RULE}${RESET}`);
   console.log(`  ${TEAL}${BOLD}Welcome to the future with Qualia.${RESET}`);

package/bin/qualia-ui.js

@@ -20,6 +20,10 @@
 //   plan-summary <path/to/plan.md>       — story-file dashboard for a plan
 //   journey-tree [path/to/JOURNEY.md]    — ladder view of all milestones, current highlighted
 //   milestone-complete <num> <name> <next> — celebration banner on milestone close
+//   spine [path/to/JOURNEY.md]           — compact horizontal "you are here" journey map (start banner)
+//   onboard <name>                       — first-run milestone mental-model card (post-install, employees)
+//   phase-complete <num> <name> [k=v…]   — per-phase celebration (tasks, mdone, mtotal, streak, next, nextname)
+//   clockout <name> [k=v…]               — end-of-day report card (phases, tasks, commits, mdone, mtotal, streak, date, erp)
 
 const fs = require("fs");
 const path = require("path");
@@ -127,6 +131,17 @@ function progressBar(phase, total) {
   return `${bar} ${DIM}${pct}%${RESET}`;
 }
 
+// Compact filled/empty tick bar (▰▱) for inline use in cards and the journey
+// spine. Scales `done` of `total` onto `width` ticks. Returns "" when total<1.
+function barTicks(done, total, width) {
+  const w = width || 5;
+  const t = Number(total) || 0;
+  if (t < 1) return "";
+  const d = Math.max(0, Math.min(t, Number(done) || 0));
+  const filled = Math.max(0, Math.min(w, Math.round((d / t) * w)));
+  return `${TEAL}${"▰".repeat(filled)}${DIM2}${"▱".repeat(w - filled)}${RESET}`;
+}
+
 function colorForStatus(s) {
   const colors = {
     setup: DIM,
@@ -410,6 +425,166 @@ function cmdMilestoneComplete(num, name, nextName) {
   console.log("");
 }
 
+// ─── Journey Spine (compact horizontal "you are here") ───
+// One-line milestone ladder with the current milestone marked and a caret
+// beneath it. Rendered by the session-start banner so an employee sees where
+// they are in the arc the instant they open the terminal. Skips itself when
+// there is no real multi-milestone journey to map (nothing to orient against).
+function cmdSpine(journeyPath) {
+  const state = readState();
+  if (!state || !state.ok) return;
+  const current = state.milestone || 1;
+
+  // Milestone list: JOURNEY.md headers first, then state.milestones, else none.
+  let milestones = [];
+  const p = journeyPath || ".planning/JOURNEY.md";
+  try {
+    const content = fs.readFileSync(p, "utf8");
+    const re = /^## Milestone (\d+)\s*·\s*(.+?)\s*(?:\[[^\]]*\])?\r?$/gm;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      milestones.push({ num: parseInt(m[1]), name: m[2].trim() });
+    }
+  } catch {}
+  if (milestones.length === 0 && Array.isArray(state.milestones)) {
+    milestones = state.milestones
+      .map((x, i) => ({ num: x.num || i + 1, name: x.name || x.milestone_name || "" }));
+  }
+  // Nothing to orient against on a single-milestone (or unknown) project.
+  if (milestones.length < 2) return;
+  milestones.sort((a, b) => a.num - b.num);
+
+  // Build the colored spine while tracking the plain-text column of the current
+  // milestone's marker, so the caret lands exactly beneath it.
+  const SEP = "──";
+  const colored = [];
+  const plainSegs = [];
+  let caretCol = -1;
+  for (let i = 0; i < milestones.length; i++) {
+    const ms = milestones[i];
+    const isPast = ms.num < current;
+    const isCurrent = ms.num === current;
+    const marker = isPast ? `${GREEN}●${RESET}`
+      : isCurrent ? `${TEAL}${BOLD}◆${RESET}`
+      : `${DIM2}○${RESET}`;
+    const labelColor = isCurrent ? TEAL + BOLD : isPast ? DIM : WHITE;
+    const labelPlain = `M${ms.num} `;
+    if (isCurrent) {
+      const prefix = plainSegs.length ? plainSegs.join(SEP).length + SEP.length : 0;
+      caretCol = prefix + labelPlain.length; // column of the marker glyph
+    }
+    plainSegs.push(`${labelPlain}●`);
+    colored.push(`${labelColor}M${ms.num}${RESET} ${marker}`);
+  }
+
+  const LABEL_W = 10; // "Journey" label field width (2-space indent added below)
+  console.log("");
+  console.log(`  ${pad(DIM + "Journey" + RESET, LABEL_W)}${colored.join(`${DIM2}${SEP}${RESET}`)}`);
+  if (caretCol >= 0) {
+    console.log(`  ${" ".repeat(LABEL_W + caretCol)}${TEAL}↑${RESET} ${DIM}you are here${RESET}`);
+  }
+  const last = (state.last_activity || "").trim();
+  if (last && !/regenerated from increments/i.test(last)) {
+    const short = last.length > 56 ? last.slice(0, 55) + "…" : last;
+    console.log(`  ${pad(DIM + "Last" + RESET, LABEL_W)}${DIM}${short}${RESET}`);
+  }
+  console.log("");
+}
+
+// ─── Onboard (first-run mental model for a new employee) ─
+// Shown after install for non-OWNER roles: the milestone mental model + the one
+// first move. Keeps a new hire from staring at a prompt wondering what to type.
+function cmdOnboard(name) {
+  const who = name ? ` ${DIM}·${RESET} ${WHITE}welcome aboard, ${name}${RESET}` : ` ${DIM}·${RESET} ${WHITE}welcome aboard${RESET}`;
+  console.log("");
+  console.log(`  ${TEAL}${BOLD}⬢${RESET} ${WHITE}${BOLD}QUALIA${RESET}${who}`);
+  console.log(`  ${RULE_DIM}`);
+  console.log(`  ${WHITE}You build in milestones:${RESET}  ${TEAL}Plan ${DIM}→ ${TEAL}Build ${DIM}→ ${TEAL}Verify ${DIM}→ ${TEAL}Ship${RESET}`);
+  console.log(`  ${DIM}You never have to guess what's next — the statusline shows where you are,${RESET}`);
+  console.log(`  ${DIM}and ${RESET}${TEAL}/qualia${RESET}${DIM} always tells you the next command.${RESET}`);
+  console.log(`  ${RULE_DIM}`);
+  console.log(`  ${TEAL}⟶${RESET} ${WHITE}First move:${RESET}  ${TEAL}${BOLD}/qualia${RESET}`);
+  console.log("");
+}
+
+// ─── Phase Complete (per-phase celebration + next move) ──
+// Smaller sibling of milestone-complete, shown by /qualia-build (or /qualia-ship)
+// when a phase closes. Optional metrics passed as key=value (tasks, mdone,
+// mtotal, streak, next, nextname); any omitted metric is simply not rendered.
+function cmdPhaseComplete(num, name, kv) {
+  kv = kv || {};
+  console.log("");
+  const title = name ? ` ${DIM}·${RESET} ${TEAL}${name}${RESET}` : "";
+  console.log(`  ${GREEN}${BOLD}◆${RESET} ${WHITE}${BOLD}PHASE ${num} COMPLETE${RESET}${title}`);
+  console.log(`  ${RULE_DIM}`);
+  const checks = [];
+  if (kv.tasks) checks.push(`${GREEN}✓${RESET} ${WHITE}${kv.tasks} tasks${RESET}`);
+  checks.push(`${GREEN}✓${RESET} ${WHITE}verified${RESET}`);
+  checks.push(`${GREEN}✓${RESET} ${WHITE}shipped${RESET}`);
+  console.log(`  ${checks.join("   ")}`);
+  if (kv.mdone && kv.mtotal) {
+    const d = parseInt(kv.mdone, 10), t = parseInt(kv.mtotal, 10);
+    const remaining = t - d;
+    const tail = remaining <= 0 ? `${GREEN}milestone ready to close${RESET}`
+      : remaining === 1 ? `${DIM}one more to close the milestone${RESET}`
+      : `${DIM}${remaining} phases left in this milestone${RESET}`;
+    console.log(`  ${pad(DIM + "Milestone" + RESET, 11)}${barTicks(d, t)} ${DIM}${d}/${t} phases · ${RESET}${tail}`);
+  }
+  if (kv.streak && parseInt(kv.streak, 10) > 1) {
+    console.log(`  ${YELLOW}🔥 ${kv.streak} phases shipped today${RESET}`);
+  }
+  console.log(`  ${RULE_DIM}`);
+  if (kv.next) {
+    const nn = kv.nextname ? `   ${DIM}(${kv.nextname})${RESET}` : "";
+    console.log(`  ${TEAL}⟶${RESET} ${WHITE}Next:${RESET}  ${TEAL}${BOLD}${kv.next}${RESET}${nn}`);
+  }
+  console.log("");
+}
+
+// ─── Clock Out (end-of-day report card) ──────────────────
+// Rendered by /qualia-report at shift close. Metrics passed as key=value
+// (phases, tasks, commits, mdone, mtotal, streak, date, erp=ok|queued).
+function cmdClockout(name, kv) {
+  kv = kv || {};
+  console.log("");
+  const who = name ? ` ${DIM}·${RESET} ${WHITE}${name}${RESET}` : "";
+  const date = kv.date ? ` ${DIM}·${RESET} ${DIM}${kv.date}${RESET}` : "";
+  console.log(`  ${TEAL}${BOLD}▤${RESET} ${WHITE}${BOLD}CLOCK OUT${RESET}${who}${date}`);
+  console.log(`  ${RULE_DIM}`);
+  const shipped = [];
+  if (kv.phases) shipped.push(`${WHITE}${kv.phases} phases${RESET}`);
+  if (kv.tasks) shipped.push(`${WHITE}${kv.tasks} tasks${RESET}`);
+  if (kv.commits) shipped.push(`${WHITE}${kv.commits} commits${RESET}`);
+  if (shipped.length) {
+    console.log(`  ${pad(DIM + "Shipped" + RESET, 12)}${shipped.join(`  ${DIM}·${RESET}  `)}`);
+  }
+  if (kv.mdone && kv.mtotal) {
+    const d = parseInt(kv.mdone, 10), t = parseInt(kv.mtotal, 10);
+    const pct = t > 0 ? Math.round((d / t) * 100) : 0;
+    console.log(`  ${pad(DIM + "Milestone" + RESET, 12)}${barTicks(d, t)} ${DIM}${pct}%${RESET}`);
+  }
+  if (kv.streak && parseInt(kv.streak, 10) >= 1) {
+    console.log(`  ${pad(DIM + "Streak" + RESET, 12)}${YELLOW}${kv.streak} days${RESET}`);
+  }
+  console.log(`  ${RULE_DIM}`);
+  const tail = kv.erp === "ok" ? `${GREEN}Report uploaded to ERP ✓${RESET}`
+    : kv.erp === "queued" ? `${YELLOW}Report queued — uploads next session${RESET}`
+    : `${DIM}Session report saved${RESET}`;
+  console.log(`  ${tail}   ${DIM}See you tomorrow.${RESET}`);
+  console.log("");
+}
+
+// Parse trailing `key=value` CLI args into an object (used by the lifecycle
+// cards so optional metrics are positional-order-independent).
+function parseKV(args) {
+  const o = {};
+  for (const a of args || []) {
+    const i = a.indexOf("=");
+    if (i > 0) o[a.slice(0, i)] = a.slice(i + 1);
+  }
+  return o;
+}
+
 // ─── Plan Summary (story-file dashboard) ─────────────────
 // Renders a polished overview of a plan file: phase goal, tasks grouped by wave,
 // persona chips, dependency lines, AC count, validation count. Called by
@@ -733,6 +908,12 @@ module.exports = {
   divider,
   section,
   sectionClose,
+  // Lifecycle cards (called in-process by install.js / reused by skills)
+  onboard: cmdOnboard,
+  phaseComplete: cmdPhaseComplete,
+  clockout: cmdClockout,
+  spine: cmdSpine,
+  barTicks,
   // Existing helpers (kept exposed for reuse)
   pad,
   visibleLength,
@@ -776,9 +957,13 @@ switch (cmd) {
   case "plan-summary": cmdPlanSummary(rest[0]); break;
   case "journey-tree": cmdJourneyTree(rest[0]); break;
   case "milestone-complete": cmdMilestoneComplete(rest[0], rest[1], rest.slice(2).join(" ")); break;
+  case "spine":    cmdSpine(rest[0]); break;
+  case "onboard":  cmdOnboard(rest.join(" ")); break;
+  case "phase-complete": cmdPhaseComplete(rest[0], rest[1] || "", parseKV(rest.slice(2))); break;
+  case "clockout": cmdClockout(rest[0] || "", parseKV(rest.slice(1))); break;
   default:
     console.error(
-      `Usage: qualia-ui.js <banner|context|divider|ok|fail|warn|info|spawn|wave|task|done|next|end|update|plan-summary|journey-tree|milestone-complete> [args]`
+      `Usage: qualia-ui.js <banner|context|divider|ok|fail|warn|info|spawn|wave|task|done|next|end|update|plan-summary|journey-tree|milestone-complete|spine|onboard|phase-complete|clockout> [args]`
     );
     process.exit(1);
 }

package/bin/statusline.js

@@ -205,7 +205,13 @@ try {
       parts.push(mStr);
     }
 
-    if (total > 0) parts.push(`P${phase}/${total}`);
+    if (total > 0) {
+      // Always-visible forward-motion bar: phase of total, scaled to 5 ticks.
+      const w = 5;
+      const filled = Math.max(0, Math.min(w, Math.round((phase / total) * w)));
+      const ticks = "▰".repeat(filled) + "▱".repeat(w - filled);
+      parts.push(`P${phase}/${total} ${ticks}`);
+    }
     if (tasksTotal > 0) parts.push(`T${tasksDone}/${tasksTotal}`);
     if (status) parts.push(status);
 

package/hooks/session-start.js

@@ -225,6 +225,7 @@ try {
     fallbackText();
   } else if (fs.existsSync(STATE_FILE)) {
     runUi("banner", "router");
+    runUi("spine"); // horizontal "you are here" journey map (self-skips if <2 milestones)
     renderWorkPacketContext();
     const next = getNextCommand();
     if (next) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "description": "Claude Code and Codex workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"

package/skills/qualia-report/SKILL.md

@@ -155,6 +155,17 @@ fi
 node ${QUALIA_BIN}/qualia-ui.js divider
 node ${QUALIA_BIN}/qualia-ui.js ok "Report $CLIENT_REPORT_ID complete."
 node ${QUALIA_BIN}/qualia-ui.js info "Shift report submitted. You can clock out now."
+
+# End-of-day report card. Name from config; commits = $COUNT; milestone
+# progress from state. erp=ok when the upload confirmed, erp=queued when it was
+# enqueued for retry. Every metric self-omits if its variable is empty.
+EMP_NAME=$(node -pe 'try{JSON.parse(require("fs").readFileSync(process.env.HOME+"/.claude/.qualia-config.json","utf8")).installed_by||""}catch{""}' 2>/dev/null)
+MDONE=$(node ${QUALIA_BIN}/state.js check 2>/dev/null | node -pe 'try{JSON.parse(require("fs").readFileSync(0)).phase||""}catch{""}')
+MTOTAL=$(node ${QUALIA_BIN}/state.js check 2>/dev/null | node -pe 'try{JSON.parse(require("fs").readFileSync(0)).total_phases||""}catch{""}')
+node ${QUALIA_BIN}/qualia-ui.js clockout "$EMP_NAME" date="{YYYY-MM-DD}" \
+  ${COUNT:+commits=$COUNT} \
+  ${MDONE:+mdone=$MDONE} ${MTOTAL:+mtotal=$MTOTAL} \
+  ${ERP_RESULT:+erp=$ERP_RESULT}
 ```
 
 ## Common errors (read this when something goes wrong)

package/skills/qualia-ship/SKILL.md

@@ -222,6 +222,21 @@ fi
 ```
 Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
+```bash
+# Per-phase celebration card. Reads the freshly-updated state so the phase
+# number, name, and milestone progress bar are accurate. Streak = phases this
+# employee shipped today (from the trace log); omitted if unavailable. Every
+# metric self-omits when missing, so this never fabricates.
+PHASE_NUM=$(node ${QUALIA_BIN}/state.js check 2>/dev/null | node -pe 'try{JSON.parse(require("fs").readFileSync(0)).phase||""}catch{""}')
+PHASE_NAME=$(node ${QUALIA_BIN}/state.js check 2>/dev/null | node -pe 'try{JSON.parse(require("fs").readFileSync(0)).phase_name||""}catch{""}')
+TOTAL_PHASES=$(node ${QUALIA_BIN}/state.js check 2>/dev/null | node -pe 'try{JSON.parse(require("fs").readFileSync(0)).total_phases||""}catch{""}')
+node ${QUALIA_BIN}/qualia-ui.js phase-complete "${PHASE_NUM:-?}" "$PHASE_NAME" \
+  ${TASKS_DONE:+tasks=$TASKS_DONE} \
+  ${PHASE_NUM:+mdone=$PHASE_NUM} ${TOTAL_PHASES:+mtotal=$TOTAL_PHASES} \
+  ${STREAK:+streak=$STREAK} \
+  next=/qualia-handoff
+```
+
 ```bash
 node ${QUALIA_BIN}/qualia-ui.js end "SHIPPED" "/qualia-handoff"
 ```

package/tests/journey-spine.test.sh

@@ -0,0 +1,171 @@
+#!/bin/bash
+# journey-spine.test.sh — lifecycle cosmetic layer (bin/qualia-ui.js spine/onboard/
+# phase-complete/clockout + barTicks + statusline progress bar).
+# Run: bash tests/journey-spine.test.sh
+
+PASS=0
+FAIL=0
+BIN_DIR="$(cd "$(dirname "$0")/../bin" && pwd)"
+NODE="${NODE:-node}"
+UI="$BIN_DIR/qualia-ui.js"
+STATE="$BIN_DIR/state.js"
+STATUSLINE="$BIN_DIR/statusline.js"
+
+# strip ANSI for column-accurate assertions
+strip() { sed 's/\x1b\[[0-9;]*m//g'; }
+
+assert_contains()     { if echo "$2" | strip | grep -qF -- "$3"; then echo "  ✓ $1"; PASS=$((PASS+1)); else echo "  ✗ $1 (missing '$3')"; FAIL=$((FAIL+1)); fi; }
+assert_not_contains() { if echo "$2" | strip | grep -qF -- "$3"; then echo "  ✗ $1 (should not contain '$3')"; FAIL=$((FAIL+1)); else echo "  ✓ $1"; PASS=$((PASS+1)); fi; }
+
+echo "journey-spine.test.sh — lifecycle cosmetic layer"
+echo ""
+
+$NODE -c "$UI" 2>/dev/null && { echo "  ✓ qualia-ui syntax valid"; PASS=$((PASS+1)); } || { echo "  ✗ qualia-ui syntax invalid"; FAIL=$((FAIL+1)); }
+
+# ── barTicks: scaling + clamping ──
+TICKS=$($NODE -e 'const u=require(process.argv[1]); console.log(["a"+u.barTicks(4,5),"b"+u.barTicks(0,5),"c"+u.barTicks(5,5),"d"+u.barTicks(9,5),"e"+u.barTicks(2,0)].join("\n"))' "$UI" | strip)
+assert_contains "barTicks 4/5 → 4 filled"        "$TICKS" "a▰▰▰▰▱"
+assert_contains "barTicks 0/5 → all empty"        "$TICKS" "b▱▱▱▱▱"
+assert_contains "barTicks 5/5 → all filled"       "$TICKS" "c▰▰▰▰▰"
+assert_contains "barTicks clamps over-fill to 5"  "$TICKS" "d▰▰▰▰▰"
+assert_contains "barTicks total<1 → empty string" "$TICKS" "e"
+
+# ── onboard card ──
+ONB=$($NODE "$UI" onboard "Maria" 2>&1)
+assert_contains "onboard greets by name"          "$ONB" "welcome aboard, Maria"
+assert_contains "onboard shows milestone flow"    "$ONB" "Plan"
+assert_contains "onboard shows the first move"    "$ONB" "/qualia"
+
+# ── phase-complete card ──
+PC=$($NODE "$UI" phase-complete 3 "Checkout flow" tasks=6 mdone=4 mtotal=5 streak=3 next=/qualia-build nextname="Order confirmation" 2>&1)
+assert_contains "phase-complete shows phase + name"     "$PC" "PHASE 3 COMPLETE"
+assert_contains "phase-complete shows task count"       "$PC" "6 tasks"
+assert_contains "phase-complete shows milestone bar"    "$PC" "4/5 phases"
+assert_contains "phase-complete 'one more' at 4/5"      "$PC" "one more to close the milestone"
+assert_contains "phase-complete shows streak"           "$PC" "3 phases shipped today"
+assert_contains "phase-complete shows next command"     "$PC" "/qualia-build"
+# streak of 1 must NOT render (not a streak)
+PC1=$($NODE "$UI" phase-complete 1 "Cart" streak=1 2>&1)
+assert_not_contains "phase-complete hides streak=1"     "$PC1" "shipped today"
+# milestone complete wording at full
+PCFULL=$($NODE "$UI" phase-complete 5 "Polish" mdone=5 mtotal=5 2>&1)
+assert_contains "phase-complete 'ready to close' at 5/5" "$PCFULL" "milestone ready to close"
+
+# ── clockout card ──
+CO=$($NODE "$UI" clockout "Maria" date="Thu Jun 25" phases=3 tasks=14 commits=9 mdone=4 mtotal=5 streak=4 erp=ok 2>&1)
+assert_contains "clockout names the employee"     "$CO" "CLOCK OUT"
+assert_contains "clockout shows shipped phases"   "$CO" "3 phases"
+assert_contains "clockout shows commits"          "$CO" "9 commits"
+assert_contains "clockout shows milestone %"      "$CO" "80%"
+assert_contains "clockout shows streak"           "$CO" "4 days"
+assert_contains "clockout confirms ERP upload"    "$CO" "uploaded to ERP"
+CO_Q=$($NODE "$UI" clockout "Maria" erp=queued 2>&1)
+assert_contains "clockout queued state"           "$CO_Q" "queued"
+
+# ── spine: needs a multi-milestone project fixture ──
+TMP=$(mktemp -d)
+(
+  cd "$TMP"
+  $NODE "$STATE" init --project "acme-portal" \
+    --phases '[{"name":"Cart","goal":"x"},{"name":"Checkout","goal":"y"},{"name":"Receipts","goal":"z"}]' >/dev/null 2>&1
+  mkdir -p .planning
+  cat > .planning/JOURNEY.md <<'JEOF'
+---
+project: "acme-portal"
+---
+## Milestone 1 · Foundations
+1. **Auth**
+## Milestone 2 · Commerce
+1. **Cart**
+## Milestone 3 · Growth
+1. **Referrals**
+## Milestone 4 · Handoff
+1. **Docs**
+JEOF
+)
+SPINE=$(cd "$TMP" && $NODE "$UI" spine 2>&1)
+assert_contains "spine renders the Journey label"  "$SPINE" "Journey"
+assert_contains "spine renders all 4 milestones"   "$SPINE" "M4"
+assert_contains "spine shows current marker ◆"     "$SPINE" "◆"
+assert_contains "spine shows 'you are here'"       "$SPINE" "you are here"
+
+# caret column == current-marker column (exact alignment)
+ALIGN=$(cd "$TMP" && $NODE "$UI" spine 2>&1 | strip | $NODE -e '
+  let s=""; process.stdin.on("data",d=>s+=d).on("end",()=>{
+    const lines=s.split("\n").filter(l=>l.length);
+    const spine=lines.find(l=>l.includes("Journey"));
+    const caret=lines.find(l=>l.includes("you are here"));
+    if(!spine||!caret){console.log("NOLINES");return;}
+    const markerCol=spine.indexOf("◆");
+    const caretCol=caret.indexOf("↑");
+    console.log(markerCol===caretCol?"ALIGNED":("MISALIGNED "+markerCol+" vs "+caretCol));
+  });
+')
+assert_contains "spine caret aligns under current marker" "$ALIGN" "ALIGNED"
+
+# spine self-skips with <2 milestones (single-milestone project)
+TMP2=$(mktemp -d)
+( cd "$TMP2" && $NODE "$STATE" init --project "solo" --phases '[{"name":"A","goal":"x"}]' >/dev/null 2>&1 )
+SPINE2=$(cd "$TMP2" && $NODE "$UI" spine 2>&1)
+assert_not_contains "spine self-skips single-milestone project" "$SPINE2" "you are here"
+
+# spine outside any project → no crash, no output
+SPINE3=$(cd / && $NODE "$UI" spine 2>&1)
+assert_not_contains "spine no-ops outside a project" "$SPINE3" "Journey"
+
+# ── statusline: the always-visible progress bar ──
+TMP3=$(mktemp -d); mkdir -p "$TMP3/.planning"
+cat > "$TMP3/.planning/tracking.json" <<'TEOF'
+{"phase":3,"total_phases":5,"status":"building","milestone":2,"milestone_name":"Commerce","tasks_done":2,"tasks_total":6,"blockers":[]}
+TEOF
+SL=$(printf '{"workspace":{"current_dir":"%s"},"cost":{"total_cost_usd":0},"duration_ms":0}' "$TMP3" | $NODE "$STATUSLINE" 2>&1)
+assert_contains "statusline shows P3/5"            "$SL" "P3/5"
+assert_contains "statusline shows the tick bar"    "$SL" "▰▰▰▱▱"
+
+# ── skill-wiring smoke: run the ACTUAL ship/report closing bash ──
+# These mirror the exact variable plumbing in skills/qualia-ship/SKILL.md and
+# skills/qualia-report/SKILL.md (state.js parsing + ${VAR:+…} expansions), so a
+# regression in the wiring — not just the renderer — is caught.
+TMP4=$(mktemp -d)
+( cd "$TMP4" && $NODE "$STATE" init --project "wired" \
+    --phases '[{"name":"Cart","goal":"x"},{"name":"Checkout","goal":"y"},{"name":"Receipts","goal":"z"}]' >/dev/null 2>&1 )
+
+# ---- /qualia-ship closing block (verbatim plumbing) ----
+SHIP_OUT=$(cd "$TMP4" && {
+  PHASE_NUM=$($NODE "$STATE" check 2>/dev/null | $NODE -pe 'try{JSON.parse(require("fs").readFileSync(0)).phase||""}catch{""}')
+  PHASE_NAME=$($NODE "$STATE" check 2>/dev/null | $NODE -pe 'try{JSON.parse(require("fs").readFileSync(0)).phase_name||""}catch{""}')
+  TOTAL_PHASES=$($NODE "$STATE" check 2>/dev/null | $NODE -pe 'try{JSON.parse(require("fs").readFileSync(0)).total_phases||""}catch{""}')
+  TASKS_DONE=4
+  $NODE "$UI" phase-complete "${PHASE_NUM:-?}" "$PHASE_NAME" \
+    ${TASKS_DONE:+tasks=$TASKS_DONE} \
+    ${PHASE_NUM:+mdone=$PHASE_NUM} ${TOTAL_PHASES:+mtotal=$TOTAL_PHASES} \
+    next=/qualia-handoff
+} 2>&1)
+assert_contains "ship wiring → resolves phase number into card" "$SHIP_OUT" "PHASE 1 COMPLETE"
+assert_contains "ship wiring → tasks plumbed through"   "$SHIP_OUT" "4 tasks"
+assert_contains "ship wiring → milestone bar plumbed"   "$SHIP_OUT" "phases"
+assert_contains "ship wiring → next command set"        "$SHIP_OUT" "/qualia-handoff"
+assert_not_contains "ship wiring → no literal \${VAR"   "$SHIP_OUT" '${'
+
+# ---- /qualia-report closing block (verbatim plumbing) ----
+REPORT_OUT=$(cd "$TMP4" && {
+  EMP_NAME=$($NODE -pe 'try{JSON.parse(require("fs").readFileSync(process.env.HOME+"/.claude/.qualia-config.json","utf8")).installed_by||""}catch{""}' 2>/dev/null)
+  MDONE=$($NODE "$STATE" check 2>/dev/null | $NODE -pe 'try{JSON.parse(require("fs").readFileSync(0)).phase||""}catch{""}')
+  MTOTAL=$($NODE "$STATE" check 2>/dev/null | $NODE -pe 'try{JSON.parse(require("fs").readFileSync(0)).total_phases||""}catch{""}')
+  COUNT=9
+  ERP_RESULT=ok
+  $NODE "$UI" clockout "$EMP_NAME" date="2026-06-25" \
+    ${COUNT:+commits=$COUNT} \
+    ${MDONE:+mdone=$MDONE} ${MTOTAL:+mtotal=$MTOTAL} \
+    ${ERP_RESULT:+erp=$ERP_RESULT}
+} 2>&1)
+assert_contains "report wiring → renders CLOCK OUT"     "$REPORT_OUT" "CLOCK OUT"
+assert_contains "report wiring → commit count plumbed"  "$REPORT_OUT" "9 commits"
+assert_contains "report wiring → milestone % plumbed"   "$REPORT_OUT" "%"
+assert_contains "report wiring → erp result plumbed"    "$REPORT_OUT" "uploaded to ERP"
+assert_not_contains "report wiring → no literal \${VAR" "$REPORT_OUT" '${'
+
+rm -rf "$TMP" "$TMP2" "$TMP3" "$TMP4"
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

package/tests/run-all.sh

@@ -35,6 +35,7 @@ SUITES=(
   "repo-map"
   "design-tokens"
   "batch-plan"
+  "journey-spine"
 )
 
 FAILED=()