qualia-framework 7.2.1 → 7.3.0

package/tests/plugin-manifest.test.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# plugin-manifest.test.sh — validates the experimental Claude Code plugin manifests.
+# Asserts .claude-plugin/plugin.json and .claude-plugin/marketplace.json are valid
+# JSON, declare their required fields, pin the same version as package.json, and that
+# every component path they reference exists in the repo. This is additive: it does
+# NOT touch the npx installer flow (bin/install.js + settings.json wiring), which is
+# covered by install-smoke.test.sh.
+
+set -u
+
+PASS=0
+FAIL=0
+
+pass() {
+  echo "  ✓ $1"
+  PASS=$((PASS + 1))
+}
+
+fail_case() {
+  echo "  ✗ $1"
+  [ -n "${2:-}" ] && echo "    $2"
+  FAIL=$((FAIL + 1))
+}
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+NODE="${NODE:-node}"
+PLUGIN="$ROOT/.claude-plugin/plugin.json"
+MARKET="$ROOT/.claude-plugin/marketplace.json"
+HOOKSJSON="$ROOT/hooks/hooks.json"
+
+echo "plugin-manifest.test.sh — plugin + marketplace manifests"
+echo ""
+
+# 1. plugin.json is valid JSON
+if [ -f "$PLUGIN" ] && "$NODE" -e "JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))" "$PLUGIN" 2>/dev/null; then
+  pass "plugin.json exists and is valid JSON"
+else
+  fail_case "plugin.json missing or invalid JSON" "$PLUGIN"
+fi
+
+# 2. marketplace.json is valid JSON
+if [ -f "$MARKET" ] && "$NODE" -e "JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))" "$MARKET" 2>/dev/null; then
+  pass "marketplace.json exists and is valid JSON"
+else
+  fail_case "marketplace.json missing or invalid JSON" "$MARKET"
+fi
+
+# 3. hooks/hooks.json is valid JSON
+if [ -f "$HOOKSJSON" ] && "$NODE" -e "JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))" "$HOOKSJSON" 2>/dev/null; then
+  pass "hooks/hooks.json exists and is valid JSON"
+else
+  fail_case "hooks/hooks.json missing or invalid JSON" "$HOOKSJSON"
+fi
+
+# 4. plugin.json required field: name (and the expected identity)
+PLUGIN_NAME=$("$NODE" -e "console.log(require(process.argv[1]).name || '')" "$PLUGIN" 2>/dev/null)
+if [ "$PLUGIN_NAME" = "qualia-framework" ]; then
+  pass "plugin.json declares name=qualia-framework"
+else
+  fail_case "plugin.json name field wrong" "got='$PLUGIN_NAME'"
+fi
+
+# 5. plugin.json version pinned to package.json version
+PKG_VERSION=$("$NODE" -e "console.log(require(process.argv[1]).version)" "$ROOT/package.json")
+PLUGIN_VERSION=$("$NODE" -e "console.log(require(process.argv[1]).version || '')" "$PLUGIN" 2>/dev/null)
+if [ "$PLUGIN_VERSION" = "$PKG_VERSION" ]; then
+  pass "plugin.json version matches package.json ($PKG_VERSION)"
+else
+  fail_case "plugin.json version drift" "package=$PKG_VERSION plugin=$PLUGIN_VERSION"
+fi
+
+# 6. plugin.json hooks path resolves to an existing file
+PLUGIN_HOOKS_REL=$("$NODE" -e "console.log(require(process.argv[1]).hooks || '')" "$PLUGIN" 2>/dev/null)
+PLUGIN_HOOKS_ABS="$ROOT/${PLUGIN_HOOKS_REL#./}"
+if [ -n "$PLUGIN_HOOKS_REL" ] && [ -f "$PLUGIN_HOOKS_ABS" ]; then
+  pass "plugin.json hooks path ($PLUGIN_HOOKS_REL) exists"
+else
+  fail_case "plugin.json hooks path missing" "ref='$PLUGIN_HOOKS_REL' abs='$PLUGIN_HOOKS_ABS'"
+fi
+
+# 7. Every hook file referenced in hooks/hooks.json exists at hooks/<file>.js
+MISSING_HOOKS=$("$NODE" - "$HOOKSJSON" "$ROOT" <<'NODE'
+const fs = require('fs');
+const path = require('path');
+const [, , hooksJson, root] = process.argv;
+const data = JSON.parse(fs.readFileSync(hooksJson, 'utf8'));
+const missing = [];
+const seen = new Set();
+for (const event of Object.keys(data)) {
+  for (const block of data[event]) {
+    for (const h of (block.hooks || [])) {
+      const cmd = h.command || '';
+      const m = cmd.match(/\$\{CLAUDE_PLUGIN_ROOT\}\/hooks\/([A-Za-z0-9._-]+\.js)/);
+      if (!m) { missing.push('UNPARSEABLE: ' + cmd); continue; }
+      const file = m[1];
+      if (seen.has(file)) continue;
+      seen.add(file);
+      if (!fs.existsSync(path.join(root, 'hooks', file))) missing.push(file);
+    }
+  }
+}
+process.stdout.write(missing.join(','));
+NODE
+)
+if [ -z "$MISSING_HOOKS" ]; then
+  pass "every hook referenced in hooks/hooks.json exists in hooks/"
+else
+  fail_case "hooks/hooks.json references missing/unparseable hook files" "$MISSING_HOOKS"
+fi
+
+# 8. All hooks/hooks.json commands use the ${CLAUDE_PLUGIN_ROOT} substitution (no absolute ~/.claude paths leaked)
+if ! grep -q "\.claude/hooks" "$HOOKSJSON" && grep -q "CLAUDE_PLUGIN_ROOT" "$HOOKSJSON"; then
+  pass "hooks/hooks.json uses \${CLAUDE_PLUGIN_ROOT}, no leaked ~/.claude paths"
+else
+  fail_case "hooks/hooks.json has leaked absolute paths or missing CLAUDE_PLUGIN_ROOT"
+fi
+
+# 9. marketplace.json required fields: name, owner.name, plugins[]
+MKT_OK=$("$NODE" - "$MARKET" <<'NODE'
+const fs = require('fs');
+const m = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+const ok = !!m.name && m.owner && !!m.owner.name && Array.isArray(m.plugins) && m.plugins.length > 0;
+process.stdout.write(ok ? 'ok' : 'bad');
+NODE
+)
+if [ "$MKT_OK" = "ok" ]; then
+  pass "marketplace.json has required name + owner.name + plugins[]"
+else
+  fail_case "marketplace.json missing required fields"
+fi
+
+# 10. marketplace plugin entry: required name + source, version matches, source path resolves
+MKT_PLUGIN=$("$NODE" - "$MARKET" "$ROOT" "$PKG_VERSION" <<'NODE'
+const fs = require('fs');
+const path = require('path');
+const [, , market, root, pkgVersion] = process.argv;
+const m = JSON.parse(fs.readFileSync(market, 'utf8'));
+const p = (m.plugins || []).find(x => x.name === 'qualia-framework');
+if (!p) { process.stdout.write('no-entry'); process.exit(0); }
+if (!p.source) { process.stdout.write('no-source'); process.exit(0); }
+// source './' resolves against the marketplace root (repo root); must be a dir containing .claude-plugin/
+const srcAbs = path.resolve(root, p.source);
+if (!fs.existsSync(path.join(srcAbs, '.claude-plugin', 'plugin.json'))) { process.stdout.write('source-unresolved'); process.exit(0); }
+if (p.version && p.version !== pkgVersion) { process.stdout.write('version-drift:' + p.version); process.exit(0); }
+process.stdout.write('ok');
+NODE
+)
+if [ "$MKT_PLUGIN" = "ok" ]; then
+  pass "marketplace plugin entry has name+source, source resolves, version matches"
+else
+  fail_case "marketplace plugin entry invalid" "$MKT_PLUGIN"
+fi
+
+# 11. .claude-plugin/ is in the npm package files list (ships in the tarball)
+if "$NODE" -e "process.exit((require(process.argv[1]).files||[]).includes('.claude-plugin/')?0:1)" "$ROOT/package.json"; then
+  pass "package.json files[] includes .claude-plugin/ (ships in tarball)"
+else
+  fail_case "package.json files[] missing .claude-plugin/"
+fi
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi
+
+exit 0

package/tests/refs.test.sh

@@ -217,6 +217,70 @@ assert_count "hooks"  "$HOOK_COUNT"  "$FRAMEWORK_ROOT/README.md" '[0-9]+ hooks'
 assert_count "rules"  "$RULE_COUNT"  "$FRAMEWORK_ROOT/README.md" '[0-9]+ (installed )?rules'
 assert_count "skills" "$SKILL_COUNT" "$FRAMEWORK_ROOT/guide.md"  '[0-9]+ active skills'
 
+# ── Doc/code coherence guard ──────────────────────────────────────────────────
+# A doc that promises a `qualia-framework <cmd>` CLI command or a `/qualia-*`
+# skill must point at one that actually exists. The authoritative check lives in
+# bin/qualia-doctor.js (gateDocCoherence) — it resolves the real surface from
+# cli.js dispatch + command-surface.js. We drive that gate here so the test and
+# the doctor never diverge, then pin the three specific contradictions the
+# v7.2.2 doc audit found so they can't silently come back.
+COHERENCE_STATUS=$("$NODE" -e '
+  const m = require(process.argv[1]);
+  const r = m.gateDocCoherence(m.repoRoot());
+  process.stdout.write(r.status + "\t" + r.detail);
+' "$FRAMEWORK_ROOT/bin/qualia-doctor.js" 2>/dev/null)
+COHERENCE_RESULT="${COHERENCE_STATUS%%$'\t'*}"
+COHERENCE_DETAIL="${COHERENCE_STATUS#*$'\t'}"
+if [ "$COHERENCE_RESULT" = "PASS" ]; then
+  pass "doctor doc/code coherence gate → $COHERENCE_DETAIL"
+else
+  fail_case "doctor doc/code coherence gate ($COHERENCE_RESULT)" "$COHERENCE_DETAIL"
+fi
+
+# Contradiction 1: TROUBLESHOOTING.md must not send anyone to `qualia-framework
+# erp-status` (no such dispatch case — the real one is `erp-flush show`).
+if grep -qE 'qualia-framework[[:space:]]+erp-status' "$FRAMEWORK_ROOT/TROUBLESHOOTING.md"; then
+  fail_case "TROUBLESHOOTING.md erp-status" "references nonexistent 'qualia-framework erp-status' — use 'erp-flush show'"
+else
+  pass "TROUBLESHOOTING.md no longer references nonexistent 'qualia-framework erp-status'"
+fi
+if grep -qE 'qualia-framework[[:space:]]+erp-flush[[:space:]]+show' "$FRAMEWORK_ROOT/TROUBLESHOOTING.md"; then
+  pass "TROUBLESHOOTING.md points queue-depth check at real 'erp-flush show'"
+else
+  fail_case "TROUBLESHOOTING.md erp-flush show" "queue-depth instruction should use 'qualia-framework erp-flush show'"
+fi
+
+# Contradiction 2: onboarding.html version stamp must match package.json, not
+# the stale v6.2.7 it carried.
+PKG_VERSION=$("$NODE" -e 'process.stdout.write(require(process.argv[1]).version)' "$FRAMEWORK_ROOT/package.json")
+if grep -qE "Qualia Framework v${PKG_VERSION//./\\.}" "$FRAMEWORK_ROOT/docs/onboarding.html"; then
+  pass "docs/onboarding.html version stamp = package v$PKG_VERSION"
+else
+  fail_case "docs/onboarding.html version stamp" "footer must read 'Qualia Framework v$PKG_VERSION' (package version)"
+fi
+if grep -qE 'Qualia Framework v6\.2\.7' "$FRAMEWORK_ROOT/docs/onboarding.html"; then
+  fail_case "docs/onboarding.html stale version" "still stamps the retired v6.2.7"
+else
+  pass "docs/onboarding.html no longer stamps stale v6.2.7"
+fi
+
+# Contradiction 3: AGENTS.md is GENERATED from templates/instructions.md and is
+# guarded against drift by tests/instructions.test.sh (compile --check). The
+# "under 25 lines" self-claim it carries is a known inaccuracy (the file is 29
+# lines), but it can only be corrected at the canonical source + recompile — not
+# by editing AGENTS.md directly, which would break the drift guard. Here we just
+# pin that the claim must be fixed in the TEMPLATE, not the generated file, so a
+# future fix lands in the right place. (Tracked, non-blocking.)
+TEMPLATE="$FRAMEWORK_ROOT/templates/instructions.md"
+AGENTS_LINES=$(wc -l < "$FRAMEWORK_ROOT/AGENTS.md" | tr -d ' ')
+if [ -f "$TEMPLATE" ] && grep -qE 'under 25 lines' "$TEMPLATE" && [ "$AGENTS_LINES" -ge 25 ]; then
+  echo "  ! AGENTS.md/template still claim 'under 25 lines' but generated file is $AGENTS_LINES lines"
+  echo "    fix at templates/instructions.md then 'node bin/compile-instructions.js' (out of this task's allowlist)"
+  pass "AGENTS.md line-budget claim flagged at its canonical source (templates/instructions.md)"
+else
+  pass "AGENTS.md line-budget self-claim is truthful ($AGENTS_LINES lines)"
+fi
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 

package/tests/run-all.sh

@@ -38,6 +38,7 @@ SUITES=(
   "r6-golden"
   "memory-loop"
   "journey-spine"
+  "plugin-manifest"
 )
 
 FAILED=()

package/tests/state.test.sh

@@ -1639,6 +1639,180 @@ else
   fail_case "A5 breaker" "rp2=$RP2 rp3=$RP3"
 fi
 
+# ─── FIX #1: nextCommand() threads lifecycle on the INCREMENT path ──────────
+echo ""
+echo "lifecycle threading on increment routing (FIX #1):"
+
+# 72. operate + increments: a launched project migrated to increments must keep
+#     operate routing. The increment transition call site previously dropped the
+#     lifecycle arg, so the LAST phase verified(pass) reverted to the build-mode
+#     /qualia-polish chain instead of /qualia-update. This is the regression.
+TMP=$(make_project)
+make_valid_plan "$TMP" 1
+make_valid_plan "$TMP" 2
+echo "result: PASS" > "$TMP/.planning/phase-1-verification.md"
+echo "result: PASS" > "$TMP/.planning/phase-2-verification.md"
+(cd "$TMP" && $NODE "$STATE_JS" launch >/dev/null 2>&1)   # lifecycle → operate (in tracking.json)
+(cd "$TMP" && $NODE "$STATE_JS" migrate >/dev/null 2>&1)  # legacy → increments (lifecycle persists)
+a5op() { (cd "$TMP" && $NODE "$STATE_JS" transition --to "$1" ${2:+--verification "$2"} ${3:+$3} --id "$4" 2>&1); }
+# Drive inc-0001 to verified(pass) — NOT the last increment, routes to next plan.
+a5op planned "" "" inc-0001-foundation >/dev/null 2>&1
+a5op built "" "--tasks-done 1 --tasks-total 1" inc-0001-foundation >/dev/null 2>&1
+a5op verified pass "" inc-0001-foundation >/dev/null 2>&1
+# Drive inc-0002 (the LAST increment) to verified(pass) — operate routes to update.
+a5op planned "" "" inc-0002-core >/dev/null 2>&1
+a5op built "" "--tasks-done 1 --tasks-total 1" inc-0002-core >/dev/null 2>&1
+VLAST=$(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification pass --id inc-0002-core 2>&1)
+if echo "$VLAST" | grep -q '"next_command": "/qualia-update"'; then
+  pass "operate increment: last-phase verified(pass) → /qualia-update (lifecycle threaded, not /qualia-polish)"
+else
+  fail_case "operate increment routing (FIX #1)" "out=$VLAST"
+fi
+
+# 73. operate + increments: `check` (cmdCheckIncrement) surfaces the operate
+#     next_command too — the read-side router must agree with the transition.
+CKOP=$(cd "$TMP" && $NODE "$STATE_JS" check 2>&1)
+if echo "$CKOP" | grep -q '"next_command": "/qualia-update"'; then
+  pass "operate increment: check surfaces /qualia-update (cmdCheckIncrement threads lifecycle)"
+else
+  fail_case "operate increment check routing (FIX #1)" "out=$CKOP"
+fi
+
+# 74. REGRESSION: a BUILD-mode increment project still routes to /qualia-polish
+#     on the last verified(pass) — undefined/build lifecycle must behave as today.
+TMP=$(make_project)
+make_valid_plan "$TMP" 1
+make_valid_plan "$TMP" 2
+echo "result: PASS" > "$TMP/.planning/phase-1-verification.md"
+echo "result: PASS" > "$TMP/.planning/phase-2-verification.md"
+(cd "$TMP" && $NODE "$STATE_JS" migrate >/dev/null 2>&1)   # no launch → lifecycle=build
+b5() { (cd "$TMP" && $NODE "$STATE_JS" transition --to "$1" ${2:+--verification "$2"} ${3:+$3} --id "$4" 2>&1); }
+b5 planned "" "" inc-0001-foundation >/dev/null 2>&1
+b5 built "" "--tasks-done 1 --tasks-total 1" inc-0001-foundation >/dev/null 2>&1
+b5 verified pass "" inc-0001-foundation >/dev/null 2>&1
+b5 planned "" "" inc-0002-core >/dev/null 2>&1
+b5 built "" "--tasks-done 1 --tasks-total 1" inc-0002-core >/dev/null 2>&1
+VBUILD=$(cd "$TMP" && $NODE "$STATE_JS" transition --to verified --verification pass --id inc-0002-core 2>&1)
+if echo "$VBUILD" | grep -q '"next_command": "/qualia-polish"'; then
+  pass "build increment: last-phase verified(pass) → /qualia-polish (no operate regression)"
+else
+  fail_case "build increment routing regression (FIX #1)" "out=$VBUILD"
+fi
+
+# 75. UNRECOGNIZED_STATUS: an unknown status must NOT self-recommend /qualia
+#     (no router loop) — nextCommand()'s default branch emits a diagnostic.
+#     Corrupt STATE.md to a bogus status so the public `check` routes via default.
+TMP=$(_mktemp_native); TMP_DIRS+=("$TMP")
+(cd "$TMP" && git init -q 2>/dev/null; $NODE "$STATE_JS" init --project delta --total-phases 1 --phases '[{"name":"Core","goal":"x"}]' --force >/dev/null 2>&1)
+# Corrupt the status to an unknown value in STATE.md so cmdCheck routes via the default branch.
+$NODE -e "
+  const fs=require('fs'), p='$TMP/.planning/STATE.md';
+  let md=fs.readFileSync(p,'utf8');
+  md=md.replace(/(\*\*Status\*\*:\s*)\w+/i,'\$1bogus_status').replace(/(^status:\s*)\w+/im,'\$1bogus_status');
+  fs.writeFileSync(p,md);
+" 2>/dev/null
+UNK=$(cd "$TMP" && $NODE "$STATE_JS" check 2>&1)
+if echo "$UNK" | grep -q 'UNRECOGNIZED_STATUS' && ! echo "$UNK" | grep -q '"next_command": "/qualia"'; then
+  pass "unknown status → UNRECOGNIZED_STATUS diagnostic (no /qualia self-recommend loop)"
+else
+  fail_case "unrecognized status handling (FIX #1)" "out=$UNK"
+fi
+
+# ─── Scope-drift gate (ITEM #5) ──────────────────────────
+# analyze-gate.js is now ENFORCED at the planned→built seam (was SKILL prose).
+# A strict-profile HIGH finding (a scope acceptance criterion the plan silently
+# dropped) refuses the advance and writes a trace; a clean plan advances; the
+# gate's own failure (unreadable contract) is fail-soft (does not block).
+echo ""
+echo "scope-drift gate (planned→built):"
+
+# Build a phase-1 plan + contract that DROPS one of two scope acceptance criteria.
+# AC2 ("export compliance reconciliation spreadsheet to PDF") shares NO tokens
+# with the contract, so analyze-gate flags it HIGH (uncovered-scope-ac).
+make_drift_plan() {
+  local dir="$1"
+  printf '# Phase 1\n## Task 1 — Login\n**Done when:** Login form renders\n' > "$dir/.planning/phase-1-plan.md"
+  cat > "$dir/.planning/phase-1-contract.json" <<'JSON'
+{"version":1,"phase":1,"goal":"Build login form","why":"auth","success_criteria":["Login form renders"],"tasks":[{"id":"T1","title":"Login form","wave":1,"depends_on":[],"persona":"none","files_modify":[],"files_create":[],"files_delete":[],"acceptance_criteria":["Login form renders"],"action":"Create login form","context_files":[],"verification":[]}]}
+JSON
+  cat > "$dir/.planning/phase-1-context.md" <<'MD'
+## Acceptance Criteria
+- AC1 — Login form renders
+- AC2 — Administrators can export quarterly compliance reconciliation spreadsheet to PDF
+MD
+  mkdir -p "$dir/.planning/evidence"
+  printf '{"ok":true,"checks":[]}\n' > "$dir/.planning/evidence/phase-1-contract-run.json"
+}
+
+# A1. strict profile + HIGH drift finding → planned→built is REFUSED (SCOPE_DRIFT).
+TMP=$(make_project)
+make_drift_plan "$TMP"
+(cd "$TMP" && $NODE "$STATE_JS" transition --to planned --phase 1 >/dev/null 2>&1)
+TRACE_DIR="${QUALIA_HOME:-$HOME/.claude}/.qualia-traces"
+TRACE_FILE="$TRACE_DIR/$(date +%Y-%m-%d).jsonl"
+TRACE_BEFORE=0
+[ -f "$TRACE_FILE" ] && TRACE_BEFORE=$(grep -c '"hook":"scope-drift"' "$TRACE_FILE" 2>/dev/null || echo 0)
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to built --phase 1 --tasks-done 1 --tasks-total 1 2>&1)
+EXIT=$?
+if [ "$EXIT" -ne 0 ] \
+   && echo "$OUT" | grep -q '"error": "SCOPE_DRIFT"' \
+   && echo "$OUT" | grep -q 'compliance reconciliation spreadsheet'; then
+  pass "strict + HIGH scope-drift → planned→built REFUSED (offending dropped AC named)"
+else
+  fail_case "strict scope-drift block" "exit=$EXIT out=$OUT"
+fi
+
+# A2. the refusal also wrote a scope-drift 'block' trace (gate left a trail).
+TRACE_AFTER=0
+[ -f "$TRACE_FILE" ] && TRACE_AFTER=$(grep -c '"hook":"scope-drift"' "$TRACE_FILE" 2>/dev/null || echo 0)
+if [ "$TRACE_AFTER" -gt "$TRACE_BEFORE" ] \
+   && grep -q '"hook":"scope-drift","result":"block"' "$TRACE_FILE" 2>/dev/null; then
+  pass "scope-drift block writes a .qualia-traces entry"
+else
+  fail_case "scope-drift trace written" "before=$TRACE_BEFORE after=$TRACE_AFTER"
+fi
+
+# A3. --force overrides the scope-drift block (senior waiver / standard profile).
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to built --phase 1 --tasks-done 1 --tasks-total 1 --force 2>&1)
+if echo "$OUT" | grep -q '"status": "built"'; then
+  pass "scope-drift is forceable: --force advances past the block"
+else
+  fail_case "scope-drift --force override" "out=$OUT"
+fi
+
+# A4. a CLEAN plan (no dropped AC) advances planned→built normally.
+TMP=$(make_project)
+printf '# Phase 1\n## Task 1 — Login\n**Done when:** Login form renders\n' > "$TMP/.planning/phase-1-plan.md"
+cat > "$TMP/.planning/phase-1-contract.json" <<'JSON'
+{"version":1,"phase":1,"goal":"Login form renders","why":"auth","success_criteria":["Login form renders"],"tasks":[{"id":"T1","title":"Login form renders","wave":1,"depends_on":[],"persona":"none","files_modify":[],"files_create":[],"files_delete":[],"acceptance_criteria":["Login form renders"],"action":"Create login form renders","context_files":[],"verification":[]}]}
+JSON
+printf '## Acceptance Criteria\n- AC1 — Login form renders\n' > "$TMP/.planning/phase-1-context.md"
+(cd "$TMP" && $NODE "$STATE_JS" transition --to planned --phase 1 >/dev/null 2>&1)
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to built --phase 1 --tasks-done 1 --tasks-total 1 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q '"status": "built"'; then
+  pass "clean plan (scope covered) advances planned→built"
+else
+  fail_case "clean plan advances" "exit=$EXIT out=$OUT"
+fi
+
+# A5. FAIL-SOFT: when analyze-gate's own input is broken (unreadable contract),
+#     the gate must NOT block the build — it fails soft and advances.
+TMP=$(make_project)
+make_drift_plan "$TMP"
+(cd "$TMP" && $NODE "$STATE_JS" transition --to planned --phase 1 >/dev/null 2>&1)
+# Corrupt the contract AFTER reaching planned so the drift gate can't parse it.
+echo 'NOT JSON {{{' > "$TMP/.planning/phase-1-contract.json"
+OUT=$(cd "$TMP" && $NODE "$STATE_JS" transition --to built --phase 1 --tasks-done 1 --tasks-total 1 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && echo "$OUT" | grep -q '"status": "built"' \
+   && ! echo "$OUT" | grep -q 'SCOPE_DRIFT'; then
+  pass "scope-drift gate is fail-soft: unreadable contract does NOT block the build"
+else
+  fail_case "scope-drift fail-soft" "exit=$EXIT out=$OUT"
+fi
+
 # ─── Summary ─────────────────────────────────────────────
 echo ""
 echo "=== Results: $PASS passed, $FAIL failed ==="