qualia-framework 6.2.9 → 6.3.0

package/tests/refs.test.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # Qualia Framework — surface-drift guard
 # Greps every active surface for backtick-quoted /qualia-{name} command references.
-# Asserts each name has a matching skills/qualia-{name}/SKILL.md.
+# Asserts each name is in bin/command-surface.js and has a matching SKILL.md.
 #
 # Why: v5.7 + v5.8 removed /qualia-quick, /qualia-task, /qualia-prd, /qualia-design,
 # /qualia-polish-loop. Three user-facing files (rules/speed.md, templates/help.html,
@@ -81,6 +81,11 @@ SCAN_FILES=$(
 # We capture name + file:line so we can show context per failure.
 declare -A SEEN_REFS
 declare -A REF_LOCATIONS
+declare -A ACTIVE_SKILL_MAP
+
+while IFS= read -r skill; do
+  [ -n "$skill" ] && ACTIVE_SKILL_MAP["/$skill"]=1
+done < <("$NODE" -e 'const {ACTIVE_SKILLS}=require(process.argv[1]); for (const s of ACTIVE_SKILLS) console.log(s)' "$FRAMEWORK_ROOT/bin/command-surface.js")
 
 while IFS= read -r file; do
   # Pattern A: backtick-quoted commands. Allow trailing flag/word but only capture base name.
@@ -124,11 +129,11 @@ for ref in $(printf '%s\n' "${!SEEN_REFS[@]}" | sort); do
   name="${ref#/}"
   skill_dir="$SKILLS_DIR/$name"
   locations="${REF_LOCATIONS[$ref]}"
-  if [ -d "$skill_dir" ] && [ -f "$skill_dir/SKILL.md" ]; then
-    pass "$ref → skills/$name/SKILL.md"
+  if [ "${ACTIVE_SKILL_MAP[$ref]:-}" = "1" ] && [ -d "$skill_dir" ] && [ -f "$skill_dir/SKILL.md" ]; then
+    pass "$ref → active skills/$name/SKILL.md"
     continue
   fi
-  fail_case "$ref" "no skills/$name/SKILL.md — referenced by: $locations"
+  fail_case "$ref" "not an active shipped command or missing skills/$name/SKILL.md — referenced by: $locations"
 done
 
 PACKAGE_VERSION="$("$NODE" -e 'console.log(require(process.argv[1]).version)' "$FRAMEWORK_ROOT/package.json" 2>/dev/null || echo "")"

package/tests/runner.js

@@ -212,7 +212,7 @@ describe("CLI", () => {
   it("team list works", () => {
     const r = run("cli.js", ["team", "list"]);
     assert.equal(r.status, 0);
-    assert.match(stripAnsi(r.stdout), /QS-FAWZI-01/);
+    assert.match(stripAnsi(r.stdout), /QS-FAWZI-11/);
   });
 
   it("traces handles missing traces dir", () => {
@@ -230,7 +230,7 @@ describe("CLI", () => {
     try {
       fs.mkdirSync(path.join(tmpHome, ".claude"), { recursive: true });
       fs.writeFileSync(path.join(tmpHome, ".claude", ".qualia-config.json"), JSON.stringify({
-        code: "QS-FAWZI-01",
+        code: "QS-FAWZI-11",
         installed_by: "Fawzi Goussous",
         role: "OWNER",
         version: "2.8.1",
@@ -1607,7 +1607,7 @@ describe("Hooks", () => {
     try {
       fs.mkdirSync(path.join(tmpHome, ".claude"), { recursive: true });
       fs.writeFileSync(path.join(tmpHome, ".claude", ".qualia-config.json"), JSON.stringify({
-        code: "QS-FAWZI-01", version: "99.99.99",
+        code: "QS-FAWZI-11", version: "99.99.99",
       }));
       const r = spawnSync(NODE, [path.join(HOOKS, "auto-update.js")], {
         encoding: "utf8", timeout: 5000,
@@ -2441,7 +2441,7 @@ describe("qualia-ui.js", () => {
     try {
       fs.mkdirSync(path.join(tmpHome, ".claude"), { recursive: true });
       fs.writeFileSync(path.join(tmpHome, ".claude", ".qualia-config.json"), JSON.stringify({
-        code: "QS-FAWZI-01",
+        code: "QS-FAWZI-11",
         installed_by: "Fawzi Goussous",
         role: "OWNER",
         version: "2.8.1",
@@ -2535,7 +2535,7 @@ describe("install.js", () => {
   it("valid code installs everything", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
-      const r = runInstall("QS-FAWZI-01", tmpHome);
+      const r = runInstall("QS-FAWZI-11", tmpHome);
       assert.equal(r.status, 0);
       assert.ok(fs.existsSync(path.join(tmpHome, ".claude", "skills", "qualia", "SKILL.md")));
       assert.ok(fs.existsSync(path.join(tmpHome, ".claude", "hooks", "session-start.js")));
@@ -2556,9 +2556,9 @@ describe("install.js", () => {
   it("config JSON has correct fields", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
-      runInstall("QS-FAWZI-01", tmpHome);
+      runInstall("QS-FAWZI-11", tmpHome);
       const config = JSON.parse(fs.readFileSync(path.join(tmpHome, ".claude", ".qualia-config.json"), "utf8"));
-      assert.equal(config.code, "QS-FAWZI-01");
+      assert.equal(config.code, "QS-FAWZI-11");
       assert.equal(config.installed_by, "Fawzi Goussous");
       assert.equal(config.role, "OWNER");
     } finally {
@@ -2569,7 +2569,7 @@ describe("install.js", () => {
   it("CLAUDE.md role placeholder replaced", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
-      runInstall("QS-FAWZI-01", tmpHome);
+      runInstall("QS-FAWZI-11", tmpHome);
       const claude = fs.readFileSync(path.join(tmpHome, ".claude", "CLAUDE.md"), "utf8");
       assert.match(claude, /Role: OWNER/);
       assert.doesNotMatch(claude, /\{\{ROLE\}\}/);
@@ -2578,12 +2578,13 @@ describe("install.js", () => {
     }
   });
 
-  it("11 hooks installed (v6.2.0: pre-compact removed; v5.0: vercel-account-guard, env-empty-guard, supabase-destructive-guard added)", () => {
+  it("12 hooks installed (v6.2.11: proxy approval guard added; v6.2.0: pre-compact removed)", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
-      runInstall("QS-FAWZI-01", tmpHome);
+      runInstall("QS-FAWZI-11", tmpHome);
       const hooks = fs.readdirSync(path.join(tmpHome, ".claude", "hooks")).filter(f => f.endsWith(".js"));
-      assert.equal(hooks.length, 11, `expected 11 hooks, got ${hooks.length}: ${hooks.join(", ")}`);
+      assert.equal(hooks.length, 12, `expected 12 hooks, got ${hooks.length}: ${hooks.join(", ")}`);
+      assert.ok(hooks.includes("fawzi-approval-guard.js"), "fawzi-approval-guard.js must be installed");
       assert.ok(!hooks.includes("pre-compact.js"), "pre-compact.js must NOT be installed (removed in v6.2.0)");
     } finally {
       fs.rmSync(tmpHome, { recursive: true, force: true });
@@ -2593,7 +2594,7 @@ describe("install.js", () => {
   it("settings.json has hooks and statusLine", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
-      runInstall("QS-FAWZI-01", tmpHome);
+      runInstall("QS-FAWZI-11", tmpHome);
       const settings = fs.readFileSync(path.join(tmpHome, ".claude", "settings.json"), "utf8");
       assert.match(settings, /SessionStart/);
       assert.match(settings, /PreToolUse/);
@@ -2606,10 +2607,10 @@ describe("install.js", () => {
   it("lowercase code is normalized", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
-      const r = runInstall("qs-fawzi-01", tmpHome);
+      const r = runInstall("qs-fawzi-11", tmpHome);
       assert.equal(r.status, 0);
       const config = JSON.parse(fs.readFileSync(path.join(tmpHome, ".claude", ".qualia-config.json"), "utf8"));
-      assert.equal(config.code, "QS-FAWZI-01");
+      assert.equal(config.code, "QS-FAWZI-11");
     } finally {
       fs.rmSync(tmpHome, { recursive: true, force: true });
     }
@@ -2618,10 +2619,10 @@ describe("install.js", () => {
   it("O/0 typo tolerance in code suffix", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
-      const r = runInstall("QS-FAWZI-O1", tmpHome);
+      const r = runInstall("QS-HASAN-O2", tmpHome);
       assert.equal(r.status, 0);
       const config = JSON.parse(fs.readFileSync(path.join(tmpHome, ".claude", ".qualia-config.json"), "utf8"));
-      assert.equal(config.code, "QS-FAWZI-01");
+      assert.equal(config.code, "QS-HASAN-02");
     } finally {
       fs.rmSync(tmpHome, { recursive: true, force: true });
     }
@@ -2672,10 +2673,10 @@ describe("install.js", () => {
   it("whitespace-padded code is accepted", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
-      const r = runInstall("  QS-FAWZI-01  ", tmpHome);
+      const r = runInstall("  QS-FAWZI-11  ", tmpHome);
       assert.equal(r.status, 0);
       const config = JSON.parse(fs.readFileSync(path.join(tmpHome, ".claude", ".qualia-config.json"), "utf8"));
-      assert.equal(config.code, "QS-FAWZI-01");
+      assert.equal(config.code, "QS-FAWZI-11");
     } finally {
       fs.rmSync(tmpHome, { recursive: true, force: true });
     }
@@ -2689,7 +2690,7 @@ describe("install.js", () => {
         customKey: "preserved",
         env: { MY_CUSTOM_VAR: "hello" },
       }));
-      const r = runInstall("QS-FAWZI-01", tmpHome);
+      const r = runInstall("QS-FAWZI-11", tmpHome);
       assert.equal(r.status, 0);
       const settings = JSON.parse(fs.readFileSync(path.join(tmpHome, ".claude", "settings.json"), "utf8"));
       assert.equal(settings.customKey, "preserved");
@@ -2704,7 +2705,7 @@ describe("install.js", () => {
   it("knowledge files created on first install", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
-      runInstall("QS-FAWZI-01", tmpHome);
+      runInstall("QS-FAWZI-11", tmpHome);
       assert.ok(fs.existsSync(path.join(tmpHome, ".claude", "knowledge", "learned-patterns.md")));
       assert.ok(fs.existsSync(path.join(tmpHome, ".claude", "knowledge", "common-fixes.md")));
       assert.ok(fs.existsSync(path.join(tmpHome, ".claude", "knowledge", "client-prefs.md")));
@@ -2716,10 +2717,10 @@ describe("install.js", () => {
   it("re-install preserves user edits in knowledge files", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
-      runInstall("QS-FAWZI-01", tmpHome);
+      runInstall("QS-FAWZI-11", tmpHome);
       fs.appendFileSync(path.join(tmpHome, ".claude", "knowledge", "learned-patterns.md"),
         "\n## CUSTOM LEARNING — DO NOT OVERWRITE\n");
-      runInstall("QS-FAWZI-01", tmpHome);
+      runInstall("QS-FAWZI-11", tmpHome);
       const content = fs.readFileSync(path.join(tmpHome, ".claude", "knowledge", "learned-patterns.md"), "utf8");
       assert.match(content, /CUSTOM LEARNING/);
     } finally {
@@ -2732,7 +2733,7 @@ describe("install.js", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
       // Fresh install first, then inject a user-owned hook, then reinstall.
-      runInstall("QS-FAWZI-01", tmpHome);
+      runInstall("QS-FAWZI-11", tmpHome);
       const settingsPath = path.join(tmpHome, ".claude", "settings.json");
       const before = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
 
@@ -2746,7 +2747,7 @@ describe("install.js", () => {
       before.hooks.PreToolUse = [userHook, ...(before.hooks.PreToolUse || [])];
       fs.writeFileSync(settingsPath, JSON.stringify(before, null, 2));
 
-      const r = runInstall("QS-FAWZI-01", tmpHome);
+      const r = runInstall("QS-FAWZI-11", tmpHome);
       assert.equal(r.status, 0);
       const after = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
       const allCmds = [];
@@ -2770,7 +2771,7 @@ describe("install.js", () => {
   it("templates copied to qualia-templates/", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
-      runInstall("QS-FAWZI-01", tmpHome);
+      runInstall("QS-FAWZI-11", tmpHome);
       const tmplDir = path.join(tmpHome, ".claude", "qualia-templates");
       assert.ok(fs.existsSync(tmplDir));
       const files = fs.readdirSync(tmplDir);
@@ -2783,7 +2784,7 @@ describe("install.js", () => {
   it("agents copied", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
-      runInstall("QS-FAWZI-01", tmpHome);
+      runInstall("QS-FAWZI-11", tmpHome);
       const agentDir = path.join(tmpHome, ".claude", "agents");
       assert.ok(fs.existsSync(agentDir));
       const files = fs.readdirSync(agentDir);
@@ -2796,11 +2797,14 @@ describe("install.js", () => {
   it("rules copied", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
-      runInstall("QS-FAWZI-01", tmpHome);
+      runInstall("QS-FAWZI-11", tmpHome);
       const rulesDir = path.join(tmpHome, ".claude", "rules");
       assert.ok(fs.existsSync(rulesDir));
       const files = fs.readdirSync(rulesDir);
       assert.ok(files.length > 0);
+      assert.ok(fs.existsSync(path.join(rulesDir, "command-output.md")));
+      assert.match(fs.readFileSync(path.join(rulesDir, "command-output.md"), "utf8"), /alwaysApply: true/);
+      assert.ok(fs.existsSync(path.join(tmpHome, ".claude", "qualia-design", "graphics.md")));
     } finally {
       fs.rmSync(tmpHome, { recursive: true, force: true });
     }
@@ -2809,7 +2813,7 @@ describe("install.js", () => {
   it("config version matches package.json", () => {
     const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "qualia-install-"));
     try {
-      runInstall("QS-FAWZI-01", tmpHome);
+      runInstall("QS-FAWZI-11", tmpHome);
       const config = JSON.parse(fs.readFileSync(path.join(tmpHome, ".claude", ".qualia-config.json"), "utf8"));
       assert.equal(config.version, PKG_VERSION);
     } finally {

package/tests/skills.test.sh

@@ -106,7 +106,7 @@ for skill_dir in "$SKILLS_DIR"/*/; do
 
   # Cache-aware spawn audit (per rules/grounding.md):
   # Every spawn to a CUSTOM (qualia-*) agent must anchor the prompt with
-  # `@~/.claude/agents/{name}.md` (either `Role: @...` or `Read your role:
+  # `@${QUALIA_AGENTS}/{name}.md` (either `Role: @...` or `Read your role:
   # @...` — both forms accepted). The role file is session-stable; placing
   # it first lets Anthropic's prompt cache reuse the prefix across spawns
   # (documented 81-90% cost reduction). If task-specific content lands
@@ -125,14 +125,14 @@ for skill_dir in "$SKILLS_DIR"/*/; do
     custom_spawn_count=$((custom_spawn_count + $(grep -c 'subagent_type="qualia-' "$ref_md")))
   fi
   if [ "${custom_spawn_count:-0}" -gt 0 ]; then
-    role_count=$(grep -cE '@~/\.claude/agents/' "$skill_md")
+    role_count=$(grep -cF '@${QUALIA_AGENTS}/' "$skill_md")
     if [ -f "$ref_md" ]; then
-      role_count=$((role_count + $(grep -cE '@~/\.claude/agents/' "$ref_md")))
+      role_count=$((role_count + $(grep -cF '@${QUALIA_AGENTS}/' "$ref_md")))
     fi
     if [ "${role_count:-0}" -ge "$custom_spawn_count" ]; then
       pass "$name: spawn audit ($custom_spawn_count custom spawn(s), all role-anchored for cache)"
     else
-      fail_case "$name: spawn audit" "$custom_spawn_count custom spawn(s) but only ${role_count:-0} '@~/.claude/agents/' anchors — prompt cache will miss"
+      fail_case "$name: spawn audit" "$custom_spawn_count custom spawn(s) but only ${role_count:-0} '@\${QUALIA_AGENTS}/' anchors — prompt cache will miss"
     fi
   fi
 done

package/tests/state.test.sh

@@ -6,6 +6,8 @@ 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"
+FRAMEWORK_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+STATE_LEDGER_JS="$FRAMEWORK_DIR/bin/state-ledger.js"
 NODE="${NODE:-node}"
 
 # Track tmp dirs we create so we can clean them up on exit
@@ -73,6 +75,47 @@ Goal: Test goal
 PLAN
 }
 
+make_valid_contract() {
+  local dir="$1"
+  local phase="${2:-1}"
+  cat > "$dir/.planning/phase-${phase}-contract.json" <<'JSON'
+{
+  "version": 1,
+  "phase": 1,
+  "goal": "Test goal",
+  "why": "Exercise machine evidence",
+  "generated_at": "2026-05-23T00:00:00.000Z",
+  "generated_by": "manual",
+  "source_plan_hash": "",
+  "success_criteria": ["Machine check passes"],
+  "tasks": [
+    {
+      "id": "T1",
+      "title": "Machine check",
+      "wave": 1,
+      "depends_on": [],
+      "persona": "none",
+      "files_modify": [],
+      "files_create": [],
+      "files_delete": [],
+      "acceptance_criteria": ["Node command exits 0"],
+      "action": "Run deterministic evidence check",
+      "context_files": [],
+      "verification": [
+        {
+          "type": "command-exit",
+          "command": "node",
+          "args": ["-e", "process.exit(0)"],
+          "expected_exit": 0,
+          "timeout_ms": 5000
+        }
+      ]
+    }
+  ]
+}
+JSON
+}
+
 echo "=== state.js Behavioral Tests ==="
 echo ""
 
@@ -98,11 +141,18 @@ INIT_EXIT=$?
 if [ "$INIT_EXIT" -eq 0 ] \
    && [ -f "$TMP/.planning/tracking.json" ] \
    && [ -f "$TMP/.planning/STATE.md" ] \
+   && [ -f "$TMP/.planning/qualia/state.jsonl" ] \
    && 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"
+  pass "cmdInit creates tracking.json + STATE.md + ledger"
 else
-  fail_case "cmdInit creates tracking.json + STATE.md" "exit=$INIT_EXIT"
+  fail_case "cmdInit creates tracking.json + STATE.md + ledger" "exit=$INIT_EXIT"
+fi
+
+if (cd "$TMP" && $NODE "$STATE_LEDGER_JS" validate 2>&1 | grep -q '"ok": true'); then
+  pass "cmdInit writes valid state ledger"
+else
+  fail_case "cmdInit state ledger validates"
 fi
 
 # tracking.json content sanity
@@ -175,13 +225,22 @@ EXIT=$?
 if [ "$EXIT" -eq 0 ] \
    && echo "$OUT" | grep -q '"ok": true' \
    && echo "$OUT" | grep -q '"status": "built"' \
+   && echo "$OUT" | grep -q '"ledger_event_id":' \
    && 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"
+  pass "planned → built records tasks_done/tasks_total + ledger id"
 else
   fail_case "planned → built" "exit=$EXIT"
 fi
 
+LEDGER_COUNT=$(wc -l < "$TMP/.planning/qualia/state.jsonl" | tr -d ' ')
+if [ "$LEDGER_COUNT" -ge 3 ] \
+   && (cd "$TMP" && $NODE "$STATE_LEDGER_JS" validate 2>&1 | grep -q '"ok": true'); then
+  pass "state ledger records init + transitions as valid chain"
+else
+  fail_case "state ledger transition chain" "count=$LEDGER_COUNT"
+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)
@@ -195,6 +254,33 @@ else
   fail_case "built → verified(pass) auto-advance" "exit=$EXIT out=$OUT"
 fi
 
+# 6b. verified(pass) refuses when a contract exists but machine evidence is missing
+TMP=$(make_project)
+make_valid_plan "$TMP" 1
+make_valid_contract "$TMP" 1
+(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)
+echo "result: PASS" > "$TMP/.planning/phase-1-verification.md"
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification pass 2>&1)
+EXIT=$?
+if [ "$EXIT" -ne 0 ] && echo "$OUT" | grep -q '"error": "MISSING_EVIDENCE"'; then
+  pass "verified(pass) refuses missing machine evidence when contract exists"
+else
+  fail_case "verified(pass) missing evidence guard" "exit=$EXIT out=$OUT"
+fi
+
+# 6c. verified(pass) succeeds after contract-runner writes passing evidence
+(cd "$TMP" && $NODE "$FRAMEWORK_DIR/bin/contract-runner.js" .planning/phase-1-contract.json >/dev/null 2>&1)
+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'; then
+  pass "verified(pass) accepts passing machine evidence"
+else
+  fail_case "verified(pass) with machine evidence" "exit=$EXIT out=$OUT"
+fi
+
 # 7. built → verified(fail) stays on phase 1, records verification=fail
 TMP=$(make_project)
 make_valid_plan "$TMP" 1
@@ -618,6 +704,50 @@ else
   fail_case "validate well-formed plan" "exit=$EXIT out=$OUT"
 fi
 
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" validate-plan --phase 1 --require-contract 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] \
+   && echo "$OUT" | grep -q 'JSON contract missing'; then
+  pass "validate-plan --require-contract fails when JSON contract is missing"
+else
+  fail_case "validate-plan --require-contract missing contract" "exit=$EXIT out=$OUT"
+fi
+
+HASH=$(cd "$TMP" && $NODE -e "const pc=require('$FRAMEWORK_DIR/bin/plan-contract.js'); const fs=require('fs'); process.stdout.write(pc.hashPlan(fs.readFileSync('.planning/phase-1-plan.md','utf8')))")
+cat > "$TMP/.planning/phase-1-contract.json" <<JSON
+{
+  "version": 1,
+  "phase": 1,
+  "goal": "test",
+  "why": "validate require-contract",
+  "generated_at": "2026-05-23T00:00:00Z",
+  "generated_by": "manual",
+  "source_plan_hash": "$HASH",
+  "success_criteria": ["ok"],
+  "tasks": [{
+    "id": "T1",
+    "title": "Task",
+    "wave": 1,
+    "depends_on": [],
+    "files_modify": [],
+    "files_create": [],
+    "files_delete": [],
+    "acceptance_criteria": ["ok"],
+    "action": "Do task",
+    "context_files": [],
+    "verification": [{ "type": "file-exists", "path": ".planning/phase-1-plan.md" }]
+  }]
+}
+JSON
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" validate-plan --phase 1 --require-contract 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"contract_status": "valid"'; then
+  pass "validate-plan --require-contract accepts valid JSON contract"
+else
+  fail_case "validate-plan --require-contract valid contract" "exit=$EXIT out=$OUT"
+fi
+
 # 33. validate-plan rejects empty plan
 TMP=$(make_project)
 echo "" > "$TMP/.planning/phase-1-plan.md"

package/skills/qualia-debug/SKILL.md

@@ -1,185 +0,0 @@
----
-name: qualia-debug
-description: "Investigative debugging — parses symptom from arguments, runs diagnostic scans, identifies root cause, applies minimal fix, writes DEBUG report. Trigger on 'debug', 'find bug', 'fix error', 'something is broken', 'not working', 'weird behavior', 'layout broken', 'CSS issue', 'slow page', 'performance'."
-allowed-tools:
-  - Bash
-  - Read
-  - Edit
-  - Write
-  - Grep
-  - Glob
-  - Agent
----
-
-# /qualia-debug — Investigative Debugging (one-shot)
-
-Parse the symptom. Run diagnostics. Find root cause. Apply minimal fix. Write report. **One-shot — no mandatory user questions.**
-
-## Usage
-
-- `/qualia-debug {symptom}` — investigate a specific symptom
-- `/qualia-debug` — no symptom given: investigate recently-changed files for obvious bugs
-- `/qualia-debug --frontend {symptom}` — layout/z-index/overflow bias
-- `/qualia-debug --perf {symptom}` — performance bias
-
-## Tool Budget
-
-Max 10 Read/Grep/Bash calls for investigation. If you haven't narrowed to root cause in 10, return `INSUFFICIENT EVIDENCE after 10 steps. Narrowed to: {files}. Recommend: {next diagnostic}.` Do not keep guessing.
-
-## Process
-
-```bash
-node ~/.claude/bin/qualia-ui.js banner debug
-```
-
-### 1. Parse Symptom from $ARGUMENTS
-
-- If arguments provided → that's the symptom. Extract: what's broken, where (file/page/feature), when (on click? on load? after change?).
-- If arguments empty → run `git diff HEAD~3 --stat` to find recently-touched files. Treat those as the suspect set. Symptom = "something in recent changes".
-
-### 2. Check Known Fixes First (cheap)
-
-```bash
-node ~/.claude/bin/knowledge.js search "{symptom_keywords}"
-```
-
-If a known fix matches, apply it and jump to step 5 (verify). Known fixes are pre-verified patterns — no need to re-investigate.
-
-### 3. Diagnostic Scan
-
-Run the scan matching the symptom type. All commands in a scan block run as parallel Bash calls in a single response turn.
-
-**General mode (default):**
-```bash
-# Compile errors
-npx tsc --noEmit 2>&1 | grep "error TS" | head -20
-
-# Empty catch / swallowed errors
-grep -rn "catch\s*{}\|catch\s*(.*)\s*{\s*}" --include="*.ts" --include="*.tsx" app/ components/ src/ lib/ 2>/dev/null | head -10
-
-# Recent console.error or thrown errors
-grep -rn "console\.error\|throw new" --include="*.ts" --include="*.tsx" app/ components/ src/ lib/ 2>/dev/null | head -10
-
-# Broken imports
-npx tsc --noEmit 2>&1 | grep -i "Cannot find module\|has no exported"
-```
-
-**Frontend mode (`--frontend`):**
-```bash
-# Stacking context audit (z-index issues)
-grep -rn "z-index\|z-\[" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null | head -20
-
-# Overflow candidates (horizontal scroll, clipping)
-grep -rn "100vw\|overflow.*hidden\|overflow-x\|position.*fixed" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null | head -15
-
-# Fixed dimensions breaking mobile
-grep -rn "width:.*[0-9]\+px\|height:.*[0-9]\+px\|w-\[[0-9]\+px\|h-\[[0-9]\+px" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null | grep -v "min-\|max-" | head -10
-
-# Flex/grid blowout candidates
-grep -rn "flex\|grid" --include="*.tsx" app/ components/ src/ 2>/dev/null | grep -v "min-w-0\|minmax(0" | wc -l
-```
-
-**Perf mode (`--perf`):**
-```bash
-# Sequential awaits that should be Promise.all
-grep -rn "const.*=.*await" --include="*.tsx" --include="*.ts" app/ src/ 2>/dev/null | grep -v "Promise.all\|Promise.allSettled" | head -15
-
-# Large files
-find app/ components/ src/ -name "*.tsx" -o -name "*.ts" 2>/dev/null | xargs wc -l 2>/dev/null | sort -rn | head -10
-
-# Missing next/image
-grep -rn "<img " --include="*.tsx" --include="*.jsx" app/ components/ src/ 2>/dev/null | grep -v "next/image" | wc -l
-
-# No dynamic imports (possible big bundles)
-grep -rn "import(\|next/dynamic" --include="*.tsx" --include="*.ts" app/ src/ 2>/dev/null | wc -l
-
-# Client-boundary usage
-grep -rln "'use client'" --include="*.tsx" app/ components/ src/ 2>/dev/null | wc -l
-```
-
-### 4. Form Hypothesis + Apply Minimal Fix
-
-From the diagnostic output, state the root cause in one sentence with `file:line` citation. No hedging — either you have evidence or you write `INSUFFICIENT EVIDENCE` and return (step 6).
-
-Apply the minimal fix:
-- Only edit files whose contents caused the symptom
-- One concept per commit — don't fold in cleanup
-- Don't refactor adjacent code
-- If the fix touches > 3 files, stop and ask the user first (major refactor disguised as a debug)
-
-### 5. Verify Fix
-
-```bash
-# TypeScript still compiles?
-npx tsc --noEmit 2>&1 | grep -c "error TS"   # Expect 0
-
-# Symptom reproduction — ideally a grep that would have matched the bug
-# and now returns empty:
-grep -rn "{pattern that represented the bug}" {scope} 2>/dev/null
-```
-
-If the verification fails, revert and return to step 3 with narrower hypothesis.
-
-### 6. Write DEBUG Report
-
-Write to `.planning/DEBUG-{YYYY-MM-DD-HHMM}.md`:
-
-```markdown
-# Debug Report — {YYYY-MM-DD HH:MM}
-
-**Symptom:** {user description or "recent changes" if no args}
-**Mode:** general | frontend | perf
-**Tool calls used:** {N}/10
-
-## Investigation
-- Diagnostic scans run: {list}
-- Files examined: {list}
-- Patterns searched: {list}
-
-## Root Cause
-{file:line} — "{quoted problematic code}" — {explanation of why it caused the symptom}
-
-## Fix Applied
-- Files: {list}
-- Diff summary: {one paragraph}
-- Verification: {commands run + results}
-
-## Related Observations
-- {any adjacent issues noticed but NOT fixed in this debug pass}
-```
-
-### 7. Commit
-
-```bash
-git add {specific files you changed}
-git commit -m "fix: {what was broken and why}"
-```
-
-## INSUFFICIENT EVIDENCE Return
-
-If you exhaust the 10-call budget without a confident root cause:
-
-```markdown
-# Debug Report — {YYYY-MM-DD HH:MM}
-
-**Symptom:** {description}
-**Outcome:** INSUFFICIENT EVIDENCE after 10 inspection steps
-
-## Narrowed To
-- Files examined: {list}
-- Ruled out: {list}
-- Remaining suspects: {list}
-
-## Recommended Next Diagnostic
-- {specific next step for the user — e.g., "run `npm run dev` and watch browser console for the specific error", or "add console.log at file:line and reproduce"}
-```
-
-Do NOT apply a speculative fix. Return the report and stop.
-
-## Rules
-
-- **No mandatory questions.** This is one-shot. If symptom args are missing, investigate recent changes.
-- **Root cause or INSUFFICIENT EVIDENCE** — no "probably" fixes.
-- **Minimal fix only.** One concept, one commit. No refactors dressed as debug.
-- **Tool budget is hard.** 10 calls, then stop.
-- **Every fix gets a DEBUG report in .planning/** — creates a searchable record.