qualia-framework-v2 2.7.0 → 2.8.0

package/README.md

@@ -50,12 +50,16 @@ See `guide.md` for the full developer guide.
 - **19 skills** — slash commands from setup to handoff, plus debugging, design, review, knowledge, session management, and skill authoring
 - **4 agents** — planner, builder, verifier, qa-browser (each in fresh context)
 - **8 hooks** — session start, branch guard, pre-push tracking sync, env protection, migration guard, deploy gate, pre-compact state save, auto-update (all Node.js — cross-platform)
-- **3 rules** — security, frontend, deployment
+- **4 rules** — security, frontend, design-reference, deployment
 - **5 templates** — tracking.json, state.md, project.md, plan.md, DESIGN.md
 
 ## Supported Platforms
 
-Works on **Windows 10/11, macOS, and Linux** (all distros). The only requirement is Node.js 18+. No Git Bash, no WSL, no bash dependency — every hook is pure Node.js.
+Works on **Windows 10/11, macOS, and Linux**. Requires Node.js 18+ and Claude Code.
+
+- Every hook and the status line are pure Node.js — no external bash, jq, or GNU coreutils required.
+- Skills are executed by Claude Code's own Bash tool (which Claude Code provides on all platforms, including Windows).
+- Tested on Fedora, EndeavourOS, macOS, and Windows 10/11.
 
 ## Why It Works
 
@@ -69,7 +73,7 @@ Splitting planner, builder, and verifier into separate agents with separate cont
 
 ### Production-Grade Hooks
 
-The `settings.json` hooks are real ops engineering, not theoretical:
+All 8 hooks are real ops engineering, not theoretical. Highlights:
 
 - **Pre-deploy gate** — TypeScript, lint, tests, build, and `service_role` leak scan before `vercel --prod`
 - **Branch guard** — Role-aware: owner can push to main, employees can't
@@ -100,7 +104,7 @@ npx qualia-framework-v2 install
   ├── agents/          planner.md, builder.md, verifier.md, qa-browser.md
   ├── hooks/           8 Node.js hooks — cross-platform (no bash dependency)
   ├── bin/             state.js (state machine) + qualia-ui.js (cosmetics library)
-  ├── knowledge/       learned-patterns.md, common-fixes.md, client-prefs.md (auto-loaded by skills)
+  ├── knowledge/       learned-patterns.md, common-fixes.md, client-prefs.md (loaded by plan/debug/new)
   ├── rules/           security.md, frontend.md, deployment.md
   ├── qualia-templates/ tracking.json, state.md, project.md, plan.md, DESIGN.md
   ├── CLAUDE.md        global instructions (role-configured per team member)

package/bin/cli.js

@@ -94,13 +94,21 @@ function cmdUpdate() {
   console.log("");
 
   try {
-    // Pull latest and reinstall with saved code
-    execSync(
-      `npx qualia-framework-v2@latest install <<< "${cfg.code}"`,
-      { stdio: "inherit", shell: true, timeout: 60000 }
-    );
+    const { spawnSync } = require("child_process");
+    const r = spawnSync("npx", ["qualia-framework-v2@latest", "install"], {
+      input: cfg.code + "\n",
+      stdio: ["pipe", "inherit", "inherit"],
+      shell: process.platform === "win32",  // npx is a .cmd shim on Windows — must go through shell
+      timeout: 120000,
+      encoding: "utf8",
+    });
+    if (r.status !== 0) {
+      console.log(`  ${RED}✗${RESET} Update failed. Run manually: npx qualia-framework-v2@latest install`);
+      process.exit(1);
+    }
   } catch (e) {
-    console.log(`  ${RED}✗${RESET} Update failed. Run manually: npx qualia-framework-v2@latest install`);
+    console.log(`  ${RED}✗${RESET} Update failed: ${e.message}`);
+    console.log(`  ${DIM}Run manually:${RESET} npx qualia-framework-v2@latest install`);
     process.exit(1);
   }
 }

package/bin/install.js

@@ -170,12 +170,11 @@ async function main() {
   // ─── Status line ───────────────────────────────────────
   log(`${WHITE}Status line${RESET}`);
   try {
-    const slDest = path.join(CLAUDE_DIR, "statusline.sh");
-    copy(path.join(FRAMEWORK_DIR, "statusline.sh"), slDest);
-    fs.chmodSync(slDest, 0o755);
-    ok("statusline.sh");
+    const slDest = path.join(CLAUDE_DIR, "bin", "statusline.js");
+    copy(path.join(FRAMEWORK_DIR, "bin", "statusline.js"), slDest);
+    ok("statusline.js");
   } catch (e) {
-    warn(`statusline.sh — ${e.message}`);
+    warn(`statusline.js — ${e.message}`);
   }
 
   // ─── Templates ─────────────────────────────────────────
@@ -224,6 +223,11 @@ async function main() {
     );
     fs.chmodSync(path.join(binDest, "qualia-ui.js"), 0o755);
     ok("qualia-ui.js (cosmetics library)");
+    copy(
+      path.join(FRAMEWORK_DIR, "bin", "statusline.js"),
+      path.join(binDest, "statusline.js")
+    );
+    ok("statusline.js (status bar renderer)");
   } catch (e) {
     warn(`scripts — ${e.message}`);
   }
@@ -303,7 +307,7 @@ async function main() {
   // Status line
   settings.statusLine = {
     type: "command",
-    command: "~/.claude/statusline.sh",
+    command: `node "${path.join(CLAUDE_DIR, "bin", "statusline.js")}"`,
   };
 
   // Spinner
@@ -424,18 +428,6 @@ async function main() {
         ],
       },
     ],
-    SubagentStart: [
-      {
-        matcher: ".*",
-        hooks: [
-          {
-            type: "command",
-            command:
-              'echo \'{"additionalContext": "◆ Qualia agent spawned"}\'',
-          },
-        ],
-      },
-    ],
   };
 
   // Permissions
@@ -449,8 +441,6 @@ async function main() {
     ];
   }
 
-  settings.effortLevel = "high";
-
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 
   ok("Hooks: session-start, auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact");
@@ -467,7 +457,7 @@ async function main() {
   console.log(`  Agents:       ${WHITE}${agentCount}${RESET} ${DIM}(planner, builder, verifier, qa-browser)${RESET}`);
   console.log(`  Hooks:        ${WHITE}8${RESET} ${DIM}(session-start, auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact)${RESET}`);
   console.log(`  Rules:        ${WHITE}${fs.readdirSync(rulesDir).length}${RESET} ${DIM}(security, frontend, design-reference, deployment)${RESET}`);
-  console.log(`  Scripts:      ${WHITE}2${RESET} ${DIM}(state.js, qualia-ui.js)${RESET}`);
+  console.log(`  Scripts:      ${WHITE}3${RESET} ${DIM}(state.js, qualia-ui.js, statusline.js)${RESET}`);
   console.log(`  Knowledge:    ${WHITE}3${RESET} ${DIM}(patterns, fixes, client prefs)${RESET}`);
   console.log(`  Templates:    ${WHITE}${fs.readdirSync(tmplDir).length}${RESET}`);
   console.log(`  Status line:  ${GREEN}✓${RESET}`);

package/bin/qualia-ui.js

@@ -20,7 +20,7 @@
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
-const { execSync } = require("child_process");
+const { spawnSync } = require("child_process");
 
 // ─── Colors ──────────────────────────────────────────────
 const TEAL = "\x1b[38;2;0;206;209m";
@@ -64,11 +64,14 @@ const ACTIONS = {
 // ─── State Reading ───────────────────────────────────────
 function readState() {
   try {
-    const out = execSync(`node ${path.join(os.homedir(), ".claude", "bin", "state.js")} check 2>/dev/null`, {
+    const statePath = path.join(os.homedir(), ".claude", "bin", "state.js");
+    const r = spawnSync(process.execPath, [statePath, "check"], {
       encoding: "utf8",
       timeout: 3000,
+      stdio: ["ignore", "pipe", "ignore"],
     });
-    return JSON.parse(out);
+    if (r.status !== 0 || !r.stdout) return null;
+    return JSON.parse(r.stdout);
   } catch {
     return null;
   }

package/bin/statusline.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+// Qualia status line — teal branded, shows phase + context + git.
+// Pure Node.js port of the original statusline.sh. Cross-platform
+// (Windows/macOS/Linux). No jq, no GNU stat, no /tmp hardcoding.
+//
+// Reads JSON from stdin (Claude Code status line schema), prints
+// two ANSI-formatted lines to stdout. Never throws — every section
+// is wrapped so missing data degrades gracefully.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+// ─── Colors (matches bin/qualia-ui.js palette) ───────────
+const TEAL = "\x1b[38;2;0;206;209m";
+const TEAL_GLOW = "\x1b[38;2;0;170;175m";
+const TEAL_DIM = "\x1b[38;2;0;130;135m";
+const WHITE = "\x1b[38;2;220;225;230m";
+const DIM = "\x1b[38;2;80;90;100m";
+const GREEN = "\x1b[38;2;52;211;153m";
+const YELLOW = "\x1b[38;2;234;179;8m";
+const RED = "\x1b[38;2;239;68;68m";
+const RESET = "\x1b[0m";
+
+// ─── Read input ──────────────────────────────────────────
+function readInput() {
+  try {
+    const raw = fs.readFileSync(0, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+const input = readInput();
+
+function pick(obj, keypath, fallback) {
+  try {
+    let cur = obj;
+    for (const k of keypath.split(".")) {
+      if (cur == null) return fallback;
+      cur = cur[k];
+    }
+    return cur == null ? fallback : cur;
+  } catch {
+    return fallback;
+  }
+}
+
+const MODEL = String(pick(input, "model.display_name", ""));
+const DIR = String(pick(input, "workspace.current_dir", process.cwd()));
+const PCT_RAW = Number(pick(input, "context_window.used_percentage", 0)) || 0;
+const PCT = Math.floor(PCT_RAW);
+const COST = Number(pick(input, "cost.total_cost_usd", 0)) || 0;
+const DURATION_MS = Number(pick(input, "cost.total_duration_ms", 0)) || 0;
+const AGENT = String(pick(input, "agent.name", "") || "");
+const WORKTREE = String(pick(input, "worktree.name", "") || "");
+
+// ─── Context bar ─────────────────────────────────────────
+let BAR = "";
+let BAR_COLOR = TEAL;
+try {
+  if (PCT >= 80) BAR_COLOR = RED;
+  else if (PCT >= 50) BAR_COLOR = YELLOW;
+  else BAR_COLOR = TEAL;
+
+  const BAR_WIDTH = 10;
+  const filled = Math.max(0, Math.min(BAR_WIDTH, Math.floor((PCT * BAR_WIDTH) / 100)));
+  const empty = BAR_WIDTH - filled;
+  BAR = "━".repeat(filled) + "╌".repeat(empty);
+} catch {
+  BAR = "╌".repeat(10);
+}
+
+// ─── Git branch (cached, cross-platform) ─────────────────
+let BRANCH = "";
+let CHANGES = 0;
+try {
+  const username = (os.userInfo().username || "anon").replace(/[^a-zA-Z0-9_-]/g, "_");
+  const cacheFile = path.join(os.tmpdir(), `qualia-git-cache-${username}`);
+
+  let fresh = false;
+  try {
+    const st = fs.statSync(cacheFile);
+    if (Date.now() - st.mtimeMs <= 3000) fresh = true;
+  } catch {
+    fresh = false;
+  }
+
+  if (!fresh) {
+    let branch = "";
+    let changes = 0;
+    try {
+      const dirCheck = spawnSync("git", ["rev-parse", "--git-dir"], {
+        cwd: DIR,
+        encoding: "utf8",
+        timeout: 1000,
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      if (dirCheck.status === 0) {
+        const br = spawnSync("git", ["branch", "--show-current"], {
+          cwd: DIR,
+          encoding: "utf8",
+          timeout: 1000,
+          stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (br.status === 0) branch = (br.stdout || "").trim();
+
+        const st = spawnSync("git", ["status", "--porcelain"], {
+          cwd: DIR,
+          encoding: "utf8",
+          timeout: 1000,
+          stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (st.status === 0) {
+          const out = (st.stdout || "").trim();
+          changes = out ? out.split("\n").length : 0;
+        }
+      }
+    } catch {}
+    try {
+      fs.writeFileSync(cacheFile, `${branch}|${changes}`);
+    } catch {}
+  }
+
+  try {
+    const cached = fs.readFileSync(cacheFile, "utf8");
+    const [b, c] = cached.split("|");
+    BRANCH = b || "";
+    CHANGES = parseInt(c, 10) || 0;
+  } catch {}
+} catch {}
+
+// ─── Phase info from .planning/tracking.json ─────────────
+let PHASE_INFO = "";
+try {
+  const trackingPath = path.join(DIR, ".planning", "tracking.json");
+  if (fs.existsSync(trackingPath)) {
+    const tracking = JSON.parse(fs.readFileSync(trackingPath, "utf8"));
+    const phase = Number(tracking.phase || 0) || 0;
+    const total = Number(tracking.total_phases || 0) || 0;
+    const status = String(tracking.status || "");
+    if (total > 0) {
+      const pdone = Math.floor((phase * 100) / total);
+      const pfill = Math.max(0, Math.min(4, Math.floor(pdone / 25)));
+      const pempt = 4 - pfill;
+      const pbar = "●".repeat(pfill) + "○".repeat(pempt);
+      PHASE_INFO = `${TEAL}${pbar}${RESET} ${WHITE}P${phase}/${total}${RESET} ${TEAL_GLOW}${status}${RESET}`;
+    }
+  }
+} catch {}
+
+// ─── Duration ────────────────────────────────────────────
+let DUR = "0s";
+try {
+  if (DURATION_MS >= 60000) {
+    DUR = `${Math.floor(DURATION_MS / 60000)}m`;
+  } else {
+    DUR = `${Math.floor(DURATION_MS / 1000)}s`;
+  }
+} catch {}
+
+// ─── Cost ────────────────────────────────────────────────
+let COST_FMT = "$0.00";
+try {
+  COST_FMT = `$${COST.toFixed(2)}`;
+} catch {}
+
+// ─── Line 1: Project + Git + Agent + Worktree + Phase ────
+let LINE1 = "";
+try {
+  const dirBase = path.basename(DIR) || DIR;
+  LINE1 = `${TEAL}◆${RESET} ${WHITE}${dirBase}${RESET}`;
+  if (BRANCH) {
+    if (CHANGES > 0) {
+      LINE1 += ` ${DIM}on${RESET} ${TEAL_GLOW}${BRANCH}${RESET} ${YELLOW}~${CHANGES}${RESET}`;
+    } else {
+      LINE1 += ` ${DIM}on${RESET} ${TEAL_GLOW}${BRANCH}${RESET}`;
+    }
+  }
+  if (AGENT) LINE1 += ` ${DIM}│${RESET} ${TEAL}⚡${AGENT}${RESET}`;
+  if (WORKTREE) LINE1 += ` ${DIM}│${RESET} ${TEAL_DIM}⎇ ${WORKTREE}${RESET}`;
+  if (PHASE_INFO) LINE1 += ` ${DIM}│${RESET} ${PHASE_INFO}`;
+} catch {
+  LINE1 = `${TEAL}◆${RESET} ${WHITE}qualia${RESET}`;
+}
+
+// ─── Line 2: Context bar + Cost + Duration + Model ───────
+let LINE2 = "";
+try {
+  LINE2 =
+    `${BAR_COLOR}${BAR}${RESET} ${DIM}${PCT}%${RESET} ` +
+    `${DIM}│${RESET} ${DIM}${COST_FMT}${RESET} ` +
+    `${DIM}│${RESET} ${DIM}${DUR}${RESET} ` +
+    `${DIM}│${RESET} ${TEAL_DIM}${MODEL}${RESET}`;
+} catch {
+  LINE2 = `${DIM}${PCT}%${RESET}`;
+}
+
+process.stdout.write(LINE1 + "\n");
+process.stdout.write(LINE2 + "\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework-v2",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework-v2": "./bin/cli.js"
@@ -23,7 +23,7 @@
   },
   "homepage": "https://github.com/qualia-solutions/qualia-framework-v2#readme",
   "scripts": {
-    "test": "bash tests/hooks.test.sh"
+    "test": "bash tests/hooks.test.sh && bash tests/state.test.sh"
   },
   "files": [
     "bin/",
@@ -34,8 +34,7 @@
     "templates/",
     "tests/",
     "CLAUDE.md",
-    "guide.md",
-    "statusline.sh"
+    "guide.md"
   ],
   "engines": {
     "node": ">=18"

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

@@ -29,9 +29,27 @@ options:
     description: "This is a subagent role, not a slash command. Creates agents/{name}.md."
 ```
 
-**Framework** → target: `/home/qualia/Projects/qualia/qualia-framework-v2/skills/{name}/SKILL.md`
+### 1a. Resolve framework directory
+
+If the user chose **Framework skill** or a framework-scoped **Agent**, resolve `${FRAMEWORK_DIR}` — the checkout path of this user's qualia-framework-v2 repo — BEFORE computing any target paths. Never hardcode `/home/<user>/...`; different teammates and operating systems have different paths.
+
+```bash
+# Priority order: env var → git detection → ask user
+FRAMEWORK_DIR="${QUALIA_FRAMEWORK_DIR:-}"
+if [ -z "$FRAMEWORK_DIR" ] && git -C . rev-parse --show-toplevel >/dev/null 2>&1; then
+  ORIGIN=$(git -C . config --get remote.origin.url 2>/dev/null)
+  case "$ORIGIN" in
+    *qualia-framework-v2*) FRAMEWORK_DIR=$(git -C . rev-parse --show-toplevel) ;;
+  esac
+fi
+echo "${FRAMEWORK_DIR:-UNRESOLVED}"
+```
+
+If the command prints `UNRESOLVED`, ask the user: *"Where is your qualia-framework-v2 checkout? (absolute path, or type 'local' to save only to ~/.claude/)"*. If they type `local`, downgrade the scope to Local. Otherwise store the answer as `${FRAMEWORK_DIR}` for the rest of the session.
+
+**Framework** → target: `${FRAMEWORK_DIR}/skills/{name}/SKILL.md`
 **Local** → target: `~/.claude/skills/{name}/SKILL.md`
-**Agent** → target: `/home/qualia/Projects/qualia/qualia-framework-v2/agents/{name}.md` (framework) or `~/.claude/agents/{name}.md` (local)
+**Agent** → target: `${FRAMEWORK_DIR}/agents/{name}.md` (framework) or `~/.claude/agents/{name}.md` (local)
 
 ### 2. Gather Requirements
 
@@ -119,10 +137,11 @@ Fix any ambiguity the test agent found.
 
 ```bash
 # Framework skill — copy to local .claude for immediate testing
-cp /home/qualia/Projects/qualia/qualia-framework-v2/skills/{name}/SKILL.md ~/.claude/skills/{name}/SKILL.md
+mkdir -p ~/.claude/skills/{name}
+cp "${FRAMEWORK_DIR}/skills/{name}/SKILL.md" ~/.claude/skills/{name}/SKILL.md
 
 # Verify it parses
-node -e "const fs=require('fs');const c=fs.readFileSync('/home/qualia/.claude/skills/{name}/SKILL.md','utf8');if(!c.includes('---'))throw new Error('missing frontmatter');if(!c.match(/^name:\s*\S/m))throw new Error('missing name');if(!c.match(/^description:\s*\S/m))throw new Error('missing description');console.log('OK')"
+node -e "const fs=require('fs');const os=require('os');const path=require('path');const c=fs.readFileSync(path.join(os.homedir(),'.claude/skills/{name}/SKILL.md'),'utf8');if(!c.includes('---'))throw new Error('missing frontmatter');if(!c.match(/^name:\s*\S/m))throw new Error('missing name');if(!c.match(/^description:\s*\S/m))throw new Error('missing description');console.log('OK')"
 ```
 
 ### 7. Commit (framework skills only)
@@ -131,7 +150,7 @@ Do NOT commit unless the user explicitly says "commit" or "ship it".
 
 When they do:
 ```bash
-cd /home/qualia/Projects/qualia/qualia-framework-v2
+cd "${FRAMEWORK_DIR}"
 git add skills/{name}/
 git commit -m "feat: add /{name} skill"
 ```

package/tests/state.test.sh

@@ -0,0 +1,398 @@
+#!/bin/bash
+# Qualia Framework v2 — state.js behavioral tests
+# Run: bash tests/state.test.sh
+
+PASS=0
+FAIL=0
+# Resolve STATE_JS to an ABSOLUTE path so `cd` inside subshells doesn't break it.
+STATE_JS="$(cd "$(dirname "$0")/../bin" && pwd)/state.js"
+NODE="${NODE:-node}"
+
+# Track tmp dirs we create so we can clean them up on exit
+TMP_DIRS=()
+cleanup() {
+  for d in "${TMP_DIRS[@]}"; do
+    [ -d "$d" ] && rm -rf "$d"
+  done
+}
+trap cleanup EXIT
+
+# Make a fresh temp project with 2 phases, already initialized.
+# Prints the absolute path to the new tmp dir (does NOT cd).
+make_project() {
+  local TMP
+  TMP=$(mktemp -d)
+  TMP_DIRS+=("$TMP")
+  (
+    cd "$TMP" || exit 1
+    $NODE "$STATE_JS" init \
+      --project "TestProject" \
+      --phases '[{"name":"Foundation","goal":"Auth"},{"name":"Core","goal":"Features"}]' \
+      >/dev/null 2>&1
+  )
+  echo "$TMP"
+}
+
+# pass "name" — record a passing assertion
+pass() {
+  echo "  ✓ $1"
+  PASS=$((PASS + 1))
+}
+
+# fail "name" "detail"
+fail_case() {
+  echo "  ✗ $1${2:+ — $2}"
+  FAIL=$((FAIL + 1))
+}
+
+echo "=== state.js Behavioral Tests ==="
+echo ""
+
+# Sanity check
+if [ ! -f "$STATE_JS" ]; then
+  echo "FATAL: state.js not found at $STATE_JS"
+  exit 1
+fi
+
+# ─── Basic I/O ───────────────────────────────────────────
+echo "basic I/O:"
+
+# 1. cmdInit produces valid tracking.json + STATE.md
+TMP=$(mktemp -d); TMP_DIRS+=("$TMP")
+(
+  cd "$TMP" || exit 1
+  $NODE "$STATE_JS" init \
+    --project "TestProject" \
+    --phases '[{"name":"Foundation","goal":"Auth"},{"name":"Core","goal":"Features"}]' \
+    >/tmp/qualia-state-test.out 2>&1
+)
+INIT_EXIT=$?
+if [ "$INIT_EXIT" -eq 0 ] \
+   && [ -f "$TMP/.planning/tracking.json" ] \
+   && [ -f "$TMP/.planning/STATE.md" ] \
+   && grep -q '"ok": true' /tmp/qualia-state-test.out \
+   && grep -q '"action": "init"' /tmp/qualia-state-test.out; then
+  pass "cmdInit creates tracking.json + STATE.md"
+else
+  fail_case "cmdInit creates tracking.json + STATE.md" "exit=$INIT_EXIT"
+fi
+
+# tracking.json content sanity
+if grep -q '"project": "TestProject"' "$TMP/.planning/tracking.json" \
+   && grep -q '"total_phases": 2' "$TMP/.planning/tracking.json" \
+   && grep -q '"phase": 1' "$TMP/.planning/tracking.json" \
+   && grep -q '"status": "setup"' "$TMP/.planning/tracking.json"; then
+  pass "cmdInit tracking.json has correct fields"
+else
+  fail_case "cmdInit tracking.json fields"
+fi
+
+# STATE.md content sanity
+if grep -q 'Phase: 1 of 2 — Foundation' "$TMP/.planning/STATE.md" \
+   && grep -q 'Status: setup' "$TMP/.planning/STATE.md"; then
+  pass "cmdInit STATE.md has correct header"
+else
+  fail_case "cmdInit STATE.md header"
+fi
+
+# 2. cmdCheck reads back init state
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" check 2>&1)
+CHECK_EXIT=$?
+if [ "$CHECK_EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"ok": true' \
+   && echo "$OUT" | grep -q '"phase": 1' \
+   && echo "$OUT" | grep -q '"status": "setup"' \
+   && echo "$OUT" | grep -q '"total_phases": 2'; then
+  pass "cmdCheck returns phase=1 status=setup total_phases=2"
+else
+  fail_case "cmdCheck returns init state" "exit=$CHECK_EXIT"
+fi
+
+# 3. cmdCheck with no project → ok:false NO_PROJECT, exit 1
+TMP2=$(mktemp -d); TMP_DIRS+=("$TMP2")
+OUT=$(cd "$TMP2" && $NODE "$STATE_JS" check 2>&1)
+CHECK_EXIT=$?
+if [ "$CHECK_EXIT" -eq 1 ] \
+   && echo "$OUT" | grep -q '"ok": false' \
+   && echo "$OUT" | grep -q '"error": "NO_PROJECT"'; then
+  pass "cmdCheck without .planning → NO_PROJECT, exit 1"
+else
+  fail_case "cmdCheck NO_PROJECT" "exit=$CHECK_EXIT"
+fi
+
+# ─── Happy path transitions ──────────────────────────────
+echo ""
+echo "happy path transitions:"
+
+# 4. setup → planned (with plan file)
+TMP=$(make_project)
+touch "$TMP/.planning/phase-1-plan.md"
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to planned 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"ok": true' \
+   && echo "$OUT" | grep -q '"status": "planned"' \
+   && echo "$OUT" | grep -q '"previous_status": "setup"'; then
+  pass "setup → planned succeeds with plan file"
+else
+  fail_case "setup → planned" "exit=$EXIT out=$OUT"
+fi
+
+# 5. planned → built (records tasks_done/tasks_total)
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to built --tasks-done 5 --tasks-total 5 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"ok": true' \
+   && echo "$OUT" | grep -q '"status": "built"' \
+   && grep -q '"tasks_done": 5' "$TMP/.planning/tracking.json" \
+   && grep -q '"tasks_total": 5' "$TMP/.planning/tracking.json"; then
+  pass "planned → built records tasks_done/tasks_total"
+else
+  fail_case "planned → built" "exit=$EXIT"
+fi
+
+# 6. built → verified(pass) auto-advances to phase 2, resets status to setup
+touch "$TMP/.planning/phase-1-verification.md"
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification pass 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"ok": true' \
+   && echo "$OUT" | grep -q '"phase": 2' \
+   && echo "$OUT" | grep -q '"status": "setup"'; then
+  pass "built → verified(pass) auto-advances phase and resets to setup"
+else
+  fail_case "built → verified(pass) auto-advance" "exit=$EXIT out=$OUT"
+fi
+
+# 7. built → verified(fail) stays on phase 1, records verification=fail
+TMP=$(make_project)
+touch "$TMP/.planning/phase-1-plan.md"
+(cd "$TMP" && $NODE "$STATE_JS" transition --to planned >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to built --tasks-done 3 --tasks-total 5 >/dev/null 2>&1)
+touch "$TMP/.planning/phase-1-verification.md"
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification fail 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"ok": true' \
+   && echo "$OUT" | grep -q '"phase": 1' \
+   && echo "$OUT" | grep -q '"status": "verified"' \
+   && echo "$OUT" | grep -q '"verification": "fail"'; then
+  pass "built → verified(fail) stays on phase 1"
+else
+  fail_case "built → verified(fail)" "exit=$EXIT out=$OUT"
+fi
+
+# ─── Precondition failures ───────────────────────────────
+echo ""
+echo "precondition failures:"
+
+# 8. setup → built fails with PRECONDITION_FAILED
+TMP=$(make_project)
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to built 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] \
+   && echo "$OUT" | grep -q '"ok": false' \
+   && echo "$OUT" | grep -q '"error": "PRECONDITION_FAILED"' \
+   && echo "$OUT" | grep -q "Cannot go from 'setup' to 'built'"; then
+  pass "setup → built fails with PRECONDITION_FAILED"
+else
+  fail_case "setup → built precondition" "exit=$EXIT out=$OUT"
+fi
+
+# 9. planned → verified fails (requires status=built)
+TMP=$(make_project)
+touch "$TMP/.planning/phase-1-plan.md"
+(cd "$TMP" && $NODE "$STATE_JS" transition --to planned >/dev/null 2>&1)
+touch "$TMP/.planning/phase-1-verification.md"
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification pass 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] \
+   && echo "$OUT" | grep -q '"error": "PRECONDITION_FAILED"' \
+   && echo "$OUT" | grep -q "Cannot go from 'planned' to 'verified'"; then
+  pass "planned → verified fails (requires built)"
+else
+  fail_case "planned → verified precondition" "exit=$EXIT out=$OUT"
+fi
+
+# 10. planned with missing plan file → MISSING_FILE
+TMP=$(make_project)
+# no phase-1-plan.md created
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to planned 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] \
+   && echo "$OUT" | grep -q '"error": "MISSING_FILE"' \
+   && echo "$OUT" | grep -q "phase-1-plan.md"; then
+  pass "setup → planned fails without plan file (MISSING_FILE)"
+else
+  fail_case "setup → planned MISSING_FILE" "exit=$EXIT out=$OUT"
+fi
+
+# 11. built → verified with missing verification file → MISSING_FILE
+TMP=$(make_project)
+touch "$TMP/.planning/phase-1-plan.md"
+(cd "$TMP" && $NODE "$STATE_JS" transition --to planned >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to built --tasks-done 1 --tasks-total 1 >/dev/null 2>&1)
+# NO verification file
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification pass 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] \
+   && echo "$OUT" | grep -q '"error": "MISSING_FILE"' \
+   && echo "$OUT" | grep -q "phase-1-verification.md"; then
+  pass "built → verified fails without verification file (MISSING_FILE)"
+else
+  fail_case "built → verified MISSING_FILE" "exit=$EXIT out=$OUT"
+fi
+
+# 12. built → verified without --verification → MISSING_ARG
+TMP=$(make_project)
+touch "$TMP/.planning/phase-1-plan.md"
+(cd "$TMP" && $NODE "$STATE_JS" transition --to planned >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to built --tasks-done 1 --tasks-total 1 >/dev/null 2>&1)
+touch "$TMP/.planning/phase-1-verification.md"
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to verified 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] \
+   && echo "$OUT" | grep -q '"error": "MISSING_ARG"' \
+   && echo "$OUT" | grep -q "verification"; then
+  pass "built → verified without --verification → MISSING_ARG"
+else
+  fail_case "built → verified MISSING_ARG" "exit=$EXIT out=$OUT"
+fi
+
+# 13. → shipped without --deployed-url → MISSING_ARG
+# Must go through polished first, so fabricate state by transitioning through the full path.
+TMP=$(make_project)
+touch "$TMP/.planning/phase-1-plan.md"
+(cd "$TMP" && $NODE "$STATE_JS" transition --to planned >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to built --tasks-done 1 --tasks-total 1 >/dev/null 2>&1)
+touch "$TMP/.planning/phase-1-verification.md"
+(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification pass >/dev/null 2>&1)
+# Now on phase 2, status=setup. Run phase 2 to completion.
+touch "$TMP/.planning/phase-2-plan.md"
+(cd "$TMP" && $NODE "$STATE_JS" transition --to planned >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to built --tasks-done 1 --tasks-total 1 >/dev/null 2>&1)
+touch "$TMP/.planning/phase-2-verification.md"
+(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification pass >/dev/null 2>&1)
+# Status should now be "verified" on last phase (no auto-advance past last phase)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to polished >/dev/null 2>&1)
+# Now try ship without deployed-url
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to shipped 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] \
+   && echo "$OUT" | grep -q '"error": "MISSING_ARG"' \
+   && echo "$OUT" | grep -q "deployed-url"; then
+  pass "→ shipped without --deployed-url → MISSING_ARG"
+else
+  fail_case "→ shipped MISSING_ARG" "exit=$EXIT out=$OUT"
+fi
+
+# 14. Unknown target --to frobnicate → INVALID_STATUS
+TMP=$(make_project)
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to frobnicate 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] \
+   && echo "$OUT" | grep -q '"error": "INVALID_STATUS"'; then
+  pass "--to frobnicate → INVALID_STATUS"
+else
+  fail_case "invalid target" "exit=$EXIT out=$OUT"
+fi
+
+# ─── Gap cycle circuit breaker ───────────────────────────
+echo ""
+echo "gap cycle circuit breaker:"
+
+# 15. First gap closure: verified(fail) → planned, gap_cycles[1]=1
+TMP=$(make_project)
+touch "$TMP/.planning/phase-1-plan.md"
+touch "$TMP/.planning/phase-1-verification.md"
+(cd "$TMP" && $NODE "$STATE_JS" transition --to planned >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to built --tasks-done 1 --tasks-total 1 >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification fail >/dev/null 2>&1)
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to planned 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"ok": true' \
+   && echo "$OUT" | grep -q '"gap_cycles": 1'; then
+  pass "first gap closure: verified(fail) → planned, gap_cycles=1"
+else
+  fail_case "first gap closure" "exit=$EXIT out=$OUT"
+fi
+
+# 16. Second gap closure: gap_cycles[1]=2
+(cd "$TMP" && $NODE "$STATE_JS" transition --to built --tasks-done 1 --tasks-total 1 >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification fail >/dev/null 2>&1)
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to planned 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"ok": true' \
+   && echo "$OUT" | grep -q '"gap_cycles": 2'; then
+  pass "second gap closure: gap_cycles=2"
+else
+  fail_case "second gap closure" "exit=$EXIT out=$OUT"
+fi
+
+# 17. Third gap closure attempt → GAP_CYCLE_LIMIT
+(cd "$TMP" && $NODE "$STATE_JS" transition --to built --tasks-done 1 --tasks-total 1 >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification fail >/dev/null 2>&1)
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to planned 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] \
+   && echo "$OUT" | grep -q '"error": "GAP_CYCLE_LIMIT"'; then
+  pass "third gap closure attempt blocked (GAP_CYCLE_LIMIT)"
+else
+  fail_case "gap cycle limit" "exit=$EXIT out=$OUT"
+fi
+
+# 18. verified(pass) resets gap_cycles[1] to 0
+# Set up a fresh project, do ONE failed cycle, then pass on the next attempt.
+TMP=$(make_project)
+touch "$TMP/.planning/phase-1-plan.md"
+touch "$TMP/.planning/phase-1-verification.md"
+(cd "$TMP" && $NODE "$STATE_JS" transition --to planned >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to built --tasks-done 1 --tasks-total 1 >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification fail >/dev/null 2>&1)
+# gap_cycles[1] is now 0 before the gap closure; becomes 1 after
+(cd "$TMP" && $NODE "$STATE_JS" transition --to planned >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to built --tasks-done 1 --tasks-total 1 >/dev/null 2>&1)
+(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification pass >/dev/null 2>&1)
+# After pass, gap_cycles[1] should be reset to 0 in tracking.json
+if grep -q '"1": 0' "$TMP/.planning/tracking.json"; then
+  pass "verified(pass) resets gap_cycles[1] to 0"
+else
+  fail_case "gap cycle reset on pass"
+fi
+
+# ─── Special transitions ─────────────────────────────────
+echo ""
+echo "special transitions:"
+
+# 19. --to note --notes "foo" succeeds, records notes
+TMP=$(make_project)
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to note --notes "hello world" 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"ok": true' \
+   && echo "$OUT" | grep -q '"action": "note"' \
+   && echo "$OUT" | grep -q '"status": "setup"' \
+   && grep -q '"notes": "hello world"' "$TMP/.planning/tracking.json"; then
+  pass "--to note records notes, status unchanged"
+else
+  fail_case "--to note" "exit=$EXIT out=$OUT"
+fi
+
+# 20. --to activity succeeds without status change
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to activity 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"ok": true' \
+   && echo "$OUT" | grep -q '"action": "activity"' \
+   && echo "$OUT" | grep -q '"status": "setup"'; then
+  pass "--to activity succeeds without status change"
+else
+  fail_case "--to activity" "exit=$EXIT out=$OUT"
+fi
+
+# ─── Summary ─────────────────────────────────────────────
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1

package/statusline.sh

@@ -1,93 +0,0 @@
-#!/bin/bash
-# Qualia status line — teal branded, shows phase + context + git
-input=$(cat)
-
-MODEL=$(echo "$input" | jq -r '.model.display_name')
-DIR=$(echo "$input" | jq -r '.workspace.current_dir')
-PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
-COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
-DURATION_MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')
-AGENT=$(echo "$input" | jq -r '.agent.name // empty')
-WORKTREE=$(echo "$input" | jq -r '.worktree.name // empty')
-
-# Teal palette
-T='\033[38;2;0;206;209m'       # Primary teal
-TG='\033[38;2;0;170;175m'      # Teal glow (darker)
-TD='\033[38;2;0;130;135m'      # Teal dim
-W='\033[38;2;220;225;230m'     # White
-DIM='\033[38;2;80;90;100m'     # Dim gray
-GREEN='\033[38;2;52;211;153m'  # Success green
-YELLOW='\033[38;2;234;179;8m'  # Warning
-RED='\033[38;2;239;68;68m'     # Error
-RESET='\033[0m'
-
-# Context bar with teal gradient
-if [ "$PCT" -ge 80 ]; then BAR_COLOR="$RED"
-elif [ "$PCT" -ge 50 ]; then BAR_COLOR="$YELLOW"
-else BAR_COLOR="$T"; fi
-
-BAR_WIDTH=10
-FILLED=$((PCT * BAR_WIDTH / 100))
-EMPTY=$((BAR_WIDTH - FILLED))
-BAR=""
-[ "$FILLED" -gt 0 ] && printf -v FILL "%${FILLED}s" && BAR="${FILL// /━}"
-[ "$EMPTY" -gt 0 ] && printf -v PAD "%${EMPTY}s" && BAR="${BAR}${PAD// /╌}"
-
-# Git branch (cached for speed)
-CACHE="/tmp/qualia-git-cache"
-if [ ! -f "$CACHE" ] || [ $(($(date +%s) - $(stat -c %Y "$CACHE" 2>/dev/null || echo 0))) -gt 3 ]; then
-  BRANCH=""
-  CHANGES=0
-  if git rev-parse --git-dir > /dev/null 2>&1; then
-    BRANCH=$(git branch --show-current 2>/dev/null)
-    CHANGES=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
-  fi
-  echo "$BRANCH|$CHANGES" > "$CACHE"
-fi
-IFS='|' read -r BRANCH CHANGES < "$CACHE"
-
-# Qualia phase from tracking.json
-PHASE_INFO=""
-TRACKING=".planning/tracking.json"
-if [ -f "$TRACKING" ]; then
-  PHASE=$(jq -r '.phase // 0' "$TRACKING" 2>/dev/null)
-  TOTAL=$(jq -r '.total_phases // 0' "$TRACKING" 2>/dev/null)
-  STATUS=$(jq -r '.status // ""' "$TRACKING" 2>/dev/null)
-  if [ "$TOTAL" -gt 0 ]; then
-    # Phase progress mini-bar
-    PDONE=$((PHASE * 100 / TOTAL))
-    PFILL=$((PDONE / 25))
-    PEMPT=$((4 - PFILL))
-    PBAR=""
-    [ "$PFILL" -gt 0 ] && printf -v PF "%${PFILL}s" && PBAR="${PF// /●}"
-    [ "$PEMPT" -gt 0 ] && printf -v PE "%${PEMPT}s" && PBAR="${PBAR}${PE// /○}"
-    PHASE_INFO="${T}${PBAR}${RESET} ${W}P${PHASE}/${TOTAL}${RESET} ${TG}${STATUS}${RESET}"
-  fi
-fi
-
-# Duration
-MINS=$((DURATION_MS / 60000))
-SECS=$(((DURATION_MS % 60000) / 1000))
-[ "$MINS" -gt 0 ] && DUR="${MINS}m" || DUR="${SECS}s"
-
-# Cost
-COST_FMT=$(printf '$%.2f' "$COST")
-
-# Line 1: Project + Git + Phase
-LINE1="${T}◆${RESET} ${W}${DIR##*/}${RESET}"
-if [ -n "$BRANCH" ]; then
-  if [ "$CHANGES" -gt 0 ]; then
-    LINE1="${LINE1} ${DIM}on${RESET} ${TG}${BRANCH}${RESET} ${YELLOW}~${CHANGES}${RESET}"
-  else
-    LINE1="${LINE1} ${DIM}on${RESET} ${TG}${BRANCH}${RESET}"
-  fi
-fi
-[ -n "$AGENT" ] && LINE1="${LINE1} ${DIM}│${RESET} ${T}⚡${AGENT}${RESET}"
-[ -n "$WORKTREE" ] && LINE1="${LINE1} ${DIM}│${RESET} ${TD}⎇ ${WORKTREE}${RESET}"
-[ -n "$PHASE_INFO" ] && LINE1="${LINE1} ${DIM}│${RESET} ${PHASE_INFO}"
-
-# Line 2: Context bar + Cost + Duration + Model
-LINE2="${BAR_COLOR}${BAR}${RESET} ${DIM}${PCT}%${RESET} ${DIM}│${RESET} ${DIM}${COST_FMT}${RESET} ${DIM}│${RESET} ${DIM}${DUR}${RESET} ${DIM}│${RESET} ${TD}${MODEL}${RESET}"
-
-printf '%b\n' "$LINE1"
-printf '%b\n' "$LINE2"