qualia-framework-v2 2.9.0 → 3.0.0

package/skills/qualia-test/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: qualia-test
+description: "Generate or run tests for client projects. Trigger on 'write tests', 'add tests', 'test this', 'run tests', 'test coverage', 'need tests for'."
+---
+
+# /qualia-test — Test Generator
+
+Generate tests for client project code. Detect framework, classify targets, write tests, run them.
+
+## Usage
+
+- `/qualia-test` — Generate tests for recently changed files
+- `/qualia-test {file}` — Generate tests for a specific file
+- `/qualia-test --run` — Run existing tests and report
+- `/qualia-test --coverage` — Run with coverage report
+
+## Process
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner test
+```
+
+### 1. Detect Test Framework
+
+```bash
+node -e "
+const p=JSON.parse(require('fs').readFileSync('package.json','utf8'));
+const d={...p.dependencies,...p.devDependencies};
+console.log(JSON.stringify({
+  vitest: !!d.vitest,
+  jest: !!d.jest,
+  playwright: !!d['@playwright/test'],
+  testing_library: !!d['@testing-library/react']
+}))
+"
+```
+
+If no test framework found, install vitest (lighter than jest for Next.js/Vite):
+
+```bash
+npm install -D vitest @testing-library/react @testing-library/jest-dom jsdom
+```
+
+Add to `vitest.config.ts` if it doesn't exist:
+```typescript
+import { defineConfig } from 'vitest/config'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: 'jsdom',
+    setupFiles: ['./vitest.setup.ts'],
+  },
+})
+```
+
+### 2. Find Targets
+
+If specific file given → use that.
+If `--run` → skip to step 4.
+Otherwise find recently changed untested files:
+
+```bash
+# Files changed in last 5 commits that don't have tests
+git diff --name-only HEAD~5 --diff-filter=AM -- '*.ts' '*.tsx' 2>/dev/null | grep -v "test\|spec\|__test__\|\.d\.ts" | head -10
+```
+
+### 3. Generate Tests
+
+For each target file, classify it and generate the appropriate test:
+
+**API route** (`app/api/**/route.ts`):
+- Test each exported handler (GET, POST, PUT, DELETE)
+- Test with valid input → expected response
+- Test with invalid input → 400 error
+- Test without auth → 401 (if auth is required)
+
+**Server action** (has `"use server"`):
+- Test each exported function
+- Test with valid args → expected result
+- Test with invalid args → error handling
+
+**React component** (`*.tsx` with JSX):
+- Test rendering without crashing
+- Test interactive elements (clicks, form submissions)
+- Test loading, error, and empty states if they exist
+- Test accessibility (role, aria-label presence)
+
+**Utility function** (`lib/*.ts`, `utils/*.ts`):
+- Test each exported function with normal input
+- Test edge cases: empty, null, undefined, boundary values
+- Test error cases: invalid input, missing data
+
+Write test file next to the source: `{file}.test.ts` or `{file}.test.tsx`.
+
+### 4. Run Tests
+
+```bash
+# Vitest
+npx vitest run --reporter=verbose 2>&1 | tail -30
+
+# Or Jest
+npx jest --verbose 2>&1 | tail -30
+
+# Coverage (if --coverage flag)
+npx vitest run --coverage 2>&1 | tail -30
+```
+
+### 5. Report
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js info "Files tested: {N}"
+node ~/.claude/bin/qualia-ui.js ok "Passing: {pass}/{total}"
+node ~/.claude/bin/qualia-ui.js end "TESTS DONE"
+```
+
+If any tests fail, show the failures and offer to fix them.
+
+### 6. Commit
+
+```bash
+git add {test files}
+git commit -m "test: add tests for {files}"
+```
+
+## Rules
+
+1. **Test behavior, not implementation.** Don't test internal state — test what the user/caller sees.
+2. **No snapshot tests.** They're brittle and meaningless.
+3. **No mocking unless necessary.** Test real behavior. Mock only external services (APIs, databases).
+4. **Each test file is self-contained.** No shared mutable state between tests.
+5. **Name tests as sentences.** `it("returns 401 when user is not authenticated")` not `it("test auth")`.

package/skills/qualia-verify/SKILL.md

@@ -33,7 +33,7 @@ node ~/.claude/bin/qualia-ui.js spawn verifier "Goal-backward check..."
 Agent(prompt="
 Read your role: @agents/verifier.md
 
-Phase plan with success criteria:
+Phase plan with success criteria AND verification contracts:
 @.planning/phase-{N}-plan.md
 
 {If re-verification: Previous verification with gaps:}

package/templates/plan.md

@@ -26,3 +26,17 @@ Goal: {what must be true when done}
 - [ ] {truth 1 — what the user can do}
 - [ ] {truth 2}
 - [ ] {truth 3}
+
+## Verification Contract
+
+### Contract for Task 1 — {title}
+**Check type:** {file-exists | grep-match | command-exit | behavioral}
+**Command:** `{exact command the verifier will run}`
+**Expected:** {what the output should be}
+**Fail if:** {what constitutes failure}
+
+### Contract for Task 2 — {title}
+**Check type:** {file-exists | grep-match | command-exit | behavioral}
+**Command:** `{exact command}`
+**Expected:** {expected output}
+**Fail if:** {failure condition}

package/tests/bin.test.sh

@@ -494,7 +494,21 @@ else
   fail_case "settings.json contents"
 fi
 
-# 33. Lowercase code works (resolveTeamCode normalizes)
+# 33. settings.json contains all 8 hooks wired correctly
+if grep -q 'block-env-edit.js' "$TMP/.claude/settings.json" \
+   && grep -q 'branch-guard.js' "$TMP/.claude/settings.json" \
+   && grep -q 'migration-guard.js' "$TMP/.claude/settings.json" \
+   && grep -q 'pre-push.js' "$TMP/.claude/settings.json" \
+   && grep -q 'pre-deploy-gate.js' "$TMP/.claude/settings.json" \
+   && grep -q 'auto-update.js' "$TMP/.claude/settings.json" \
+   && grep -q 'session-start.js' "$TMP/.claude/settings.json" \
+   && grep -q 'pre-compact.js' "$TMP/.claude/settings.json"; then
+  pass "settings.json has all 8 hooks wired"
+else
+  fail_case "settings.json missing hooks"
+fi
+
+# 34. Lowercase code works (resolveTeamCode normalizes)
 TMP=$(mktmp)
 echo "qs-fawzi-01" | HOME="$TMP" $NODE "$INSTALL_JS" > "$TMP/out.log" 2>&1
 EXIT=$?

package/tests/hooks.test.sh

@@ -107,11 +107,11 @@ TMP=$(setup_guard_repo main OWNER)
 assert_exit "OWNER on main → allowed" 0 $?
 rm -rf "$TMP"
 
-# EMPLOYEE on main → blocked (exit 1)
+# EMPLOYEE on main → blocked (exit 2)
 TMP=$(setup_guard_repo main EMPLOYEE)
 OUT=$(cd "$TMP/proj" && HOME="$TMP" $NODE "$HOOKS_DIR/branch-guard.js" 2>&1)
 RC=$?
-if [ "$RC" -eq 1 ] && echo "$OUT" | grep -q "BLOCKED" && echo "$OUT" | grep -q "main"; then
+if [ "$RC" -eq 2 ] && echo "$OUT" | grep -q "BLOCKED" && echo "$OUT" | grep -q "main"; then
   echo "  ✓ EMPLOYEE on main → blocked (BLOCKED in stdout)"
   PASS=$((PASS + 1))
 else
@@ -123,7 +123,7 @@ rm -rf "$TMP"
 # EMPLOYEE on master → blocked
 TMP=$(setup_guard_repo master EMPLOYEE)
 (cd "$TMP/proj" && HOME="$TMP" $NODE "$HOOKS_DIR/branch-guard.js" >/dev/null 2>&1)
-assert_exit "EMPLOYEE on master → blocked" 1 $?
+assert_exit "EMPLOYEE on master → blocked" 2 $?
 rm -rf "$TMP"
 
 # EMPLOYEE on feature branch → allowed
@@ -138,13 +138,13 @@ TMP=$(setup_guard_repo feature/xyz OWNER)
 assert_exit "OWNER on feature/xyz → allowed" 0 $?
 rm -rf "$TMP"
 
-# Missing config → fails closed (block, exit 1)
+# Missing config → fails closed (block, exit 2)
 TMP=$(mktemp -d)
 mkdir -p "$TMP/proj"
 (cd "$TMP/proj" && git init -q && git checkout -b feature/x -q 2>/dev/null)
 # NO .claude/.qualia-config.json
 (cd "$TMP/proj" && HOME="$TMP" $NODE "$HOOKS_DIR/branch-guard.js" >/dev/null 2>&1)
-assert_exit "missing config → blocked (fails closed)" 1 $?
+assert_exit "missing config → blocked (fails closed)" 2 $?
 rm -rf "$TMP"
 
 # Malformed config JSON → fails closed
@@ -153,7 +153,7 @@ mkdir -p "$TMP/proj" "$TMP/.claude"
 (cd "$TMP/proj" && git init -q && git checkout -b feature/x -q 2>/dev/null)
 echo 'not json{' > "$TMP/.claude/.qualia-config.json"
 (cd "$TMP/proj" && HOME="$TMP" $NODE "$HOOKS_DIR/branch-guard.js" >/dev/null 2>&1)
-assert_exit "malformed config JSON → blocked" 1 $?
+assert_exit "malformed config JSON → blocked" 2 $?
 rm -rf "$TMP"
 
 # Empty role field → fails closed
@@ -162,7 +162,7 @@ mkdir -p "$TMP/proj" "$TMP/.claude"
 (cd "$TMP/proj" && git init -q && git checkout -b feature/x -q 2>/dev/null)
 echo '{"role":""}' > "$TMP/.claude/.qualia-config.json"
 (cd "$TMP/proj" && HOME="$TMP" $NODE "$HOOKS_DIR/branch-guard.js" >/dev/null 2>&1)
-assert_exit "empty role field → blocked" 1 $?
+assert_exit "empty role field → blocked" 2 $?
 rm -rf "$TMP"
 
 # --- pre-push.js ---
@@ -286,6 +286,52 @@ else
 fi
 rm -rf "$TMP"
 
+# --- pre-deploy-gate: Server Component / route handler exemptions ---
+
+# route.ts with service_role → exempt (always server-side)
+TMP=$(mktemp -d)
+mkdir -p "$TMP/app/api/auth"
+echo 'const key = process.env.SUPABASE_SERVICE_ROLE_KEY; export async function POST() {}' > "$TMP/app/api/auth/route.ts"
+OUT=$( (cd "$TMP" && $NODE "$HOOKS_DIR/pre-deploy-gate.js") 2>&1 )
+RC=$?
+assert_exit "route.ts with service_role → exempt (exit 0)" 0 $RC
+rm -rf "$TMP"
+
+# middleware.ts with service_role → exempt (always server-side)
+TMP=$(mktemp -d)
+echo 'import { service_role } from "./config"; export function middleware() {}' > "$TMP/middleware.ts"
+OUT=$( (cd "$TMP" && $NODE "$HOOKS_DIR/pre-deploy-gate.js") 2>&1 )
+RC=$?
+assert_exit "middleware.ts with service_role → exempt (exit 0)" 0 $RC
+rm -rf "$TMP"
+
+# File in app/api/ with service_role → exempt
+TMP=$(mktemp -d)
+mkdir -p "$TMP/app/api/webhook"
+echo 'const sr = "service_role"; export async function GET() { return new Response(sr); }' > "$TMP/app/api/webhook/route.js"
+OUT=$( (cd "$TMP" && $NODE "$HOOKS_DIR/pre-deploy-gate.js") 2>&1 )
+RC=$?
+assert_exit "app/api/ file with service_role → exempt (exit 0)" 0 $RC
+rm -rf "$TMP"
+
+# File with "use server" directive + service_role → exempt
+TMP=$(mktemp -d)
+mkdir -p "$TMP/app/admin"
+printf '"use server"\nconst key = process.env.SUPABASE_SERVICE_ROLE_KEY;\nexport async function deleteUser() {}\n' > "$TMP/app/admin/actions.ts"
+OUT=$( (cd "$TMP" && $NODE "$HOOKS_DIR/pre-deploy-gate.js") 2>&1 )
+RC=$?
+assert_exit "\"use server\" file with service_role → exempt (exit 0)" 0 $RC
+rm -rf "$TMP"
+
+# Regular app/page.tsx WITHOUT directive + service_role → still blocks
+TMP=$(mktemp -d)
+mkdir -p "$TMP/app/admin"
+echo 'const key = "service_role"; export default function Page() { return <div>{key}</div>; }' > "$TMP/app/admin/page.tsx"
+OUT=$( (cd "$TMP" && $NODE "$HOOKS_DIR/pre-deploy-gate.js") 2>&1 )
+RC=$?
+assert_exit "regular page.tsx with service_role → blocked (exit 1)" 1 $RC
+rm -rf "$TMP"
+
 # --- session-start.js — must exit 0 always ---
 echo ""
 echo "session-start:"

package/tests/state.test.sh

@@ -45,6 +45,34 @@ fail_case() {
   FAIL=$((FAIL + 1))
 }
 
+# Write a minimal valid plan file (passes content validation).
+# Usage: make_valid_plan "$TMP" 1
+make_valid_plan() {
+  local dir="$1"
+  local phase="${2:-1}"
+  cat > "$dir/.planning/phase-${phase}-plan.md" <<'PLAN'
+---
+phase: 1
+goal: "Test goal"
+tasks: 1
+waves: 1
+---
+
+# Phase 1: Test
+
+Goal: Test goal
+
+## Task 1 — Test task
+**Wave:** 1
+**Files:** src/test.ts
+**Action:** Create test file
+**Done when:** File exists
+
+## Success Criteria
+- [ ] Test passes
+PLAN
+}
+
 echo "=== state.js Behavioral Tests ==="
 echo ""
 
@@ -126,7 +154,7 @@ echo "happy path transitions:"
 
 # 4. setup → planned (with plan file)
 TMP=$(make_project)
-touch "$TMP/.planning/phase-1-plan.md"
+make_valid_plan "$TMP" 1
 OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to planned 2>&1)
 EXIT=$?
 if [ "$EXIT" -eq 0 ] \
@@ -166,7 +194,7 @@ fi
 
 # 7. built → verified(fail) stays on phase 1, records verification=fail
 TMP=$(make_project)
-touch "$TMP/.planning/phase-1-plan.md"
+make_valid_plan "$TMP" 1
 (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"
@@ -201,7 +229,7 @@ fi
 
 # 9. planned → verified fails (requires status=built)
 TMP=$(make_project)
-touch "$TMP/.planning/phase-1-plan.md"
+make_valid_plan "$TMP" 1
 (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)
@@ -229,7 +257,7 @@ fi
 
 # 11. built → verified with missing verification file → MISSING_FILE
 TMP=$(make_project)
-touch "$TMP/.planning/phase-1-plan.md"
+make_valid_plan "$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)
 # NO verification file
@@ -245,7 +273,7 @@ fi
 
 # 12. built → verified without --verification → MISSING_ARG
 TMP=$(make_project)
-touch "$TMP/.planning/phase-1-plan.md"
+make_valid_plan "$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)
 touch "$TMP/.planning/phase-1-verification.md"
@@ -262,13 +290,13 @@ 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"
+make_valid_plan "$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)
 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"
+make_valid_plan "$TMP" 2
 (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"
@@ -303,7 +331,7 @@ 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"
+make_valid_plan "$TMP" 1
 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)
@@ -346,7 +374,7 @@ 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"
+make_valid_plan "$TMP" 1
 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)
@@ -465,7 +493,7 @@ fi
 
 # 26. Transition refuses on severity=error (missing Phase: header)
 TMP=$(make_project)
-touch "$TMP/.planning/phase-1-plan.md"
+make_valid_plan "$TMP" 1
 sed -i.bak '/^Phase:/d' "$TMP/.planning/STATE.md"
 OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to planned 2>&1)
 EXIT=$?
@@ -513,7 +541,7 @@ fi
 
 # 29. After fix, transition that was previously blocked now works
 TMP=$(make_project)
-touch "$TMP/.planning/phase-1-plan.md"
+make_valid_plan "$TMP" 1
 sed -i.bak '/^Phase:/d' "$TMP/.planning/STATE.md"
 # Blocked before fix
 (cd "$TMP" && $NODE "$STATE_JS" transition --to planned 2>&1 | grep -q STATE_SCHEMA_ERROR) || \
@@ -529,6 +557,156 @@ else
   fail_case "after fix transition" "exit=$EXIT out=$OUT"
 fi
 
+# ─── Configurable gap cycle limit ────────────────────────
+echo ""
+echo "configurable gap cycle limit:"
+
+# 30. gap_cycle_limit=5 allows 3rd gap closure (would fail at default 2)
+TMP=$(make_project)
+make_valid_plan "$TMP" 1
+touch "$TMP/.planning/phase-1-verification.md"
+# Set custom limit in tracking.json
+TRACKING=$(cat "$TMP/.planning/tracking.json")
+echo "$TRACKING" | $NODE -e "
+  const t = JSON.parse(require('fs').readFileSync(0,'utf8'));
+  t.gap_cycle_limit = 5;
+  process.stdout.write(JSON.stringify(t, null, 2));
+" > "$TMP/.planning/tracking.json"
+# Do 3 gap closure cycles
+(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)
+(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)
+# 3rd closure should succeed (limit is 5, we're at 2)
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to planned 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"ok": true'; then
+  pass "gap_cycle_limit=5 allows 3rd closure (default would block)"
+else
+  fail_case "custom gap limit" "exit=$EXIT out=$OUT"
+fi
+
+# 31. cmdCheck includes gap_cycle_limit in output
+TMP=$(make_project)
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" check 2>&1)
+if echo "$OUT" | grep -q '"gap_cycle_limit":'; then
+  pass "cmdCheck includes gap_cycle_limit in output"
+else
+  fail_case "gap_cycle_limit in check" "out=$OUT"
+fi
+
+# ─── Plan content validation ────────────────────────────
+echo ""
+echo "plan content validation:"
+
+# 32. validate-plan accepts well-formed plan
+TMP=$(make_project)
+make_valid_plan "$TMP" 1
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" validate-plan --phase 1 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"action": "validate-plan"' \
+   && echo "$OUT" | grep -q '"task_count": 1'; then
+  pass "validate-plan accepts well-formed plan"
+else
+  fail_case "validate well-formed plan" "exit=$EXIT out=$OUT"
+fi
+
+# 33. validate-plan rejects empty plan
+TMP=$(make_project)
+echo "" > "$TMP/.planning/phase-1-plan.md"
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" validate-plan --phase 1 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] \
+   && echo "$OUT" | grep -q '"error": "PLAN_VALIDATION_FAILED"'; then
+  pass "validate-plan rejects empty plan"
+else
+  fail_case "validate empty plan" "exit=$EXIT out=$OUT"
+fi
+
+# 34. validate-plan rejects plan missing Done when
+TMP=$(make_project)
+cat > "$TMP/.planning/phase-1-plan.md" <<'EOF'
+---
+phase: 1
+goal: "Test"
+tasks: 1
+waves: 1
+---
+## Task 1 — Incomplete
+**Wave:** 1
+**Files:** test.ts
+**Action:** Do something
+
+## Success Criteria
+- [ ] Works
+EOF
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" validate-plan --phase 1 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] \
+   && echo "$OUT" | grep -q "PLAN_VALIDATION_FAILED" \
+   && echo "$OUT" | grep -q "Done when"; then
+  pass "validate-plan rejects plan missing 'Done when'"
+else
+  fail_case "validate missing done-when" "exit=$EXIT out=$OUT"
+fi
+
+# 35. Transition to planned with invalid plan content → INVALID_PLAN
+TMP=$(make_project)
+echo "# Empty plan with no tasks" > "$TMP/.planning/phase-1-plan.md"
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to planned 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] \
+   && echo "$OUT" | grep -q '"error": "INVALID_PLAN"'; then
+  pass "transition → planned with invalid plan → INVALID_PLAN"
+else
+  fail_case "transition invalid plan" "exit=$EXIT out=$OUT"
+fi
+
+# ─── Force flag ──────────────────────────────────────────
+echo ""
+echo "force flag:"
+
+# 36. --force bypasses precondition failure
+TMP=$(make_project)
+# setup → built should fail (requires planned first)
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to built --force 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"ok": true' \
+   && echo "$OUT" | grep -q '"status": "built"'; then
+  pass "--force bypasses precondition (setup → built)"
+else
+  fail_case "force flag" "exit=$EXIT out=$OUT"
+fi
+
+# 37. --force does NOT bypass MISSING_FILE (planned without plan file)
+TMP=$(make_project)
+# No plan file exists — force should NOT help
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to planned --force 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] \
+   && echo "$OUT" | grep -q '"error": "MISSING_FILE"'; then
+  pass "--force does NOT bypass MISSING_FILE"
+else
+  fail_case "force vs MISSING_FILE" "exit=$EXIT out=$OUT"
+fi
+
+# 38. --force does NOT bypass INVALID_PLAN
+TMP=$(make_project)
+echo "# No tasks here" > "$TMP/.planning/phase-1-plan.md"
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to planned --force 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] \
+   && echo "$OUT" | grep -q '"error": "INVALID_PLAN"'; then
+  pass "--force does NOT bypass INVALID_PLAN"
+else
+  fail_case "force vs INVALID_PLAN" "exit=$EXIT out=$OUT"
+fi
+
 # ─── Summary ─────────────────────────────────────────────
 echo ""
 echo "=== Results: $PASS passed, $FAIL failed ==="