qualia-framework 6.9.2 → 6.22.0

package/templates/requirements.md

@@ -75,17 +75,17 @@ Fixed scope for every project. Do not reassign these elsewhere.
 
 ## Post-Handoff (v2)
 
-Features acknowledged but deferred past initial handoff. Not in current journey.
+**Only** capabilities the client EXPLICITLY deferred in discovery §8 (Out of Scope) belong here. This is NOT an overflow bucket for a milestone cap — there is no cap; everything in the capability inventory (discovery §9) must be a REQ-ID mapped to a milestone above. If a capability is agreed but absent from the arc, that's a roadmap bug, not a v2 item.
 
 ### {Category}
 
-- **{CAT}-XX**: {capability}
+- **{CAT}-XX**: {capability} — deferred by client (discovery §8)
 
 ---
 
 ## Out of Scope
 
-Explicit exclusions with reasoning. Prevents scope creep.
+Explicit exclusions with reasoning, drawn from discovery §8. Prevents scope creep.
 
 | Feature | Reason |
 |---------|--------|
@@ -95,16 +95,16 @@ Explicit exclusions with reasoning. Prevents scope creep.
 
 ## Traceability
 
-Populated during roadmap creation. Every v1 requirement maps to exactly one milestone + phase.
+Populated during roadmap creation. Every capability from discovery §9 maps to exactly one milestone + phase. Coverage of the full inventory — not a v1 slice — is the gate.
 
 | Requirement | Milestone | Phase | Status |
 |-------------|-----------|-------|--------|
 | {CAT}-01 | M1: {name} | Phase {N} | Pending |
 
-**Coverage:**
-- v1 requirements (all feature milestones + Handoff): {X} total
+**Coverage (must be 100% of the §9 capability inventory):**
+- Agreed capabilities (discovery §9, whole project): {X} total
 - Mapped to milestones + phases: {Y}
-- Unmapped: {Z}
+- Unmapped: {Z}  ← MUST be 0 before the journey-approval gate passes
 
 ---
 

package/tests/agent-status.test.sh

@@ -0,0 +1,153 @@
+#!/bin/bash
+# agent-status.test.sh — bin/agent-status.js (per-task status + fan-in barrier)
+# Run: bash tests/agent-status.test.sh
+
+PASS=0
+FAIL=0
+BIN_DIR="$(cd "$(dirname "$0")/../bin" && pwd)"
+NODE="${NODE:-node}"
+AS="$BIN_DIR/agent-status.js"
+
+assert_exit() {
+  local name="$1" expected="$2" actual="$3"
+  if [ "$expected" = "$actual" ]; then
+    echo "  ✓ $name"; PASS=$((PASS + 1))
+  else
+    echo "  ✗ $name (expected exit $expected, got $actual)"; FAIL=$((FAIL + 1))
+  fi
+}
+
+assert_contains() {
+  local name="$1" haystack="$2" needle="$3"
+  if echo "$haystack" | grep -q "$needle"; then
+    echo "  ✓ $name"; PASS=$((PASS + 1))
+  else
+    echo "  ✗ $name (missing '$needle' in: $haystack)"; FAIL=$((FAIL + 1))
+  fi
+}
+
+# A minimal contract with two tasks in wave 1, one in wave 2.
+write_contract() {
+  cat > "$1" <<'EOF'
+{
+  "version": 1,
+  "tasks": [
+    { "id": "T1", "wave": 1 },
+    { "id": "T2", "wave": 1 },
+    { "id": "T3", "wave": 2 }
+  ]
+}
+EOF
+}
+
+echo "agent-status.test.sh — bin/agent-status.js"
+echo ""
+
+# syntax
+$NODE -c "$AS" 2>/dev/null && { echo "  ✓ syntax valid"; PASS=$((PASS+1)); } || { echo "  ✗ syntax invalid"; FAIL=$((FAIL+1)); }
+
+# --- write / read round-trip ---
+TMP=$(mktemp -d)
+$NODE "$AS" write T1 RUNNING --phase 3 --wave 1 --cwd "$TMP" >/dev/null 2>&1
+assert_exit "write RUNNING → exit 0" 0 $?
+[ -f "$TMP/.agent-status/T1.json" ] && { echo "  ✓ status file created"; PASS=$((PASS+1)); } || { echo "  ✗ status file missing"; FAIL=$((FAIL+1)); }
+OUT=$($NODE "$AS" read T1 --cwd "$TMP" --json 2>&1)
+assert_contains "read shows RUNNING" "$OUT" '"status":"RUNNING"'
+$NODE "$AS" write T1 DONE --commit abc1234 --cwd "$TMP" >/dev/null 2>&1
+OUT=$($NODE "$AS" read T1 --cwd "$TMP" --json 2>&1)
+assert_contains "overwrite to DONE" "$OUT" '"status":"DONE"'
+assert_contains "records commit hash" "$OUT" 'abc1234'
+rm -rf "$TMP"
+
+# --- validation: bad task id and bad status are rejected (exit 2) ---
+TMP=$(mktemp -d)
+$NODE "$AS" write nope DONE --cwd "$TMP" >/dev/null 2>&1
+assert_exit "invalid task id → exit 2" 2 $?
+$NODE "$AS" write T1 FINISHED --cwd "$TMP" >/dev/null 2>&1
+assert_exit "invalid status → exit 2" 2 $?
+# traversal attempt in task id is rejected (no file written outside dir)
+$NODE "$AS" write ../evil DONE --cwd "$TMP" >/dev/null 2>&1
+assert_exit "path-traversal task id → exit 2" 2 $?
+rm -rf "$TMP"
+
+# --- barrier: holds until all expected tasks in the wave are DONE ---
+TMP=$(mktemp -d)
+write_contract "$TMP/contract.json"
+
+# Nothing written yet → wave 1 barrier HOLDS (exit 1), T1+T2 MISSING
+OUT=$($NODE "$AS" barrier "$TMP/contract.json" --wave 1 --cwd "$TMP" 2>&1)
+RC=$?
+assert_exit "empty wave-1 barrier holds" 1 $RC
+assert_contains "barrier reports HOLD" "$OUT" "BARRIER HOLD"
+
+# One DONE, one RUNNING → still holds
+$NODE "$AS" write T1 DONE --commit aaa --cwd "$TMP" >/dev/null 2>&1
+$NODE "$AS" write T2 RUNNING --cwd "$TMP" >/dev/null 2>&1
+$NODE "$AS" barrier "$TMP/contract.json" --wave 1 --cwd "$TMP" >/dev/null 2>&1
+assert_exit "partial wave-1 barrier holds" 1 $?
+
+# Both DONE → wave 1 barrier PASSES (exit 0)
+$NODE "$AS" write T2 DONE --commit bbb --cwd "$TMP" >/dev/null 2>&1
+OUT=$($NODE "$AS" barrier "$TMP/contract.json" --wave 1 --cwd "$TMP" 2>&1)
+RC=$?
+assert_exit "complete wave-1 barrier passes" 0 $RC
+assert_contains "barrier reports PASS" "$OUT" "BARRIER PASS"
+
+# Wave 2 still has T3 MISSING → holds independently
+$NODE "$AS" barrier "$TMP/contract.json" --wave 2 --cwd "$TMP" >/dev/null 2>&1
+assert_exit "wave-2 barrier still holds (T3 missing)" 1 $?
+
+# Whole-phase barrier (no --wave) holds because T3 not done
+$NODE "$AS" barrier "$TMP/contract.json" --cwd "$TMP" >/dev/null 2>&1
+assert_exit "phase barrier holds while T3 open" 1 $?
+
+# Finish T3 → phase barrier passes
+$NODE "$AS" write T3 DONE --commit ccc --cwd "$TMP" >/dev/null 2>&1
+$NODE "$AS" barrier "$TMP/contract.json" --cwd "$TMP" >/dev/null 2>&1
+assert_exit "phase barrier passes when all done" 0 $?
+
+# A BLOCKED task holds the barrier (BLOCKED != DONE)
+$NODE "$AS" write T3 BLOCKED --note "missing dep" --cwd "$TMP" >/dev/null 2>&1
+OUT=$($NODE "$AS" barrier "$TMP/contract.json" --cwd "$TMP" --json 2>&1)
+RC=$?
+assert_exit "BLOCKED task holds barrier" 1 $RC
+assert_contains "barrier json counts blocked" "$OUT" '"blocked": 1'
+rm -rf "$TMP"
+
+# --- barrier --tasks (explicit batch gate, no contract needed; R16 wave-plan) ---
+TMP=$(mktemp -d)
+$NODE "$AS" write T1 DONE --commit a --cwd "$TMP" >/dev/null 2>&1
+$NODE "$AS" write T2 RUNNING --cwd "$TMP" >/dev/null 2>&1
+$NODE "$AS" write T5 DONE --commit b --cwd "$TMP" >/dev/null 2>&1
+# batch {T1,T5} both DONE → pass, with no contract file present
+$NODE "$AS" barrier --tasks T1,T5 --cwd "$TMP" >/dev/null 2>&1
+assert_exit "barrier --tasks all DONE → pass (no contract)" 0 $?
+# batch {T1,T2} → T2 RUNNING → hold
+$NODE "$AS" barrier --tasks T1,T2 --cwd "$TMP" >/dev/null 2>&1
+assert_exit "barrier --tasks with a RUNNING member → hold" 1 $?
+OUT=$($NODE "$AS" barrier --tasks T1,T2 --cwd "$TMP" 2>&1)
+assert_contains "barrier --tasks scope label" "$OUT" "batch T1,T2"
+rm -rf "$TMP"
+
+# --- list + clear ---
+TMP=$(mktemp -d)
+$NODE "$AS" write T1 DONE --cwd "$TMP" >/dev/null 2>&1
+$NODE "$AS" write T2 RUNNING --cwd "$TMP" >/dev/null 2>&1
+OUT=$($NODE "$AS" list --cwd "$TMP" 2>&1)
+assert_contains "list shows T1" "$OUT" "T1"
+assert_contains "list shows T2" "$OUT" "T2"
+$NODE "$AS" clear --cwd "$TMP" >/dev/null 2>&1
+[ ! -d "$TMP/.agent-status" ] && { echo "  ✓ clear removes status dir"; PASS=$((PASS+1)); } || { echo "  ✗ clear left status dir"; FAIL=$((FAIL+1)); }
+rm -rf "$TMP"
+
+# --- buildActive library signal (used by R1's pre-write guard) ---
+TMP=$(mktemp -d)
+ACTIVE=$($NODE -e "const a=require('$AS'); a.writeStatus('$TMP',{task:'T1',status:'RUNNING'}); console.log(a.buildActive('$TMP'))" 2>&1)
+assert_contains "buildActive true while RUNNING" "$ACTIVE" "true"
+IDLE=$($NODE -e "const a=require('$AS'); a.writeStatus('$TMP',{task:'T1',status:'DONE'}); console.log(a.buildActive('$TMP'))" 2>&1)
+assert_contains "buildActive false when none RUNNING" "$IDLE" "false"
+rm -rf "$TMP"
+
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1

package/tests/analyze-gate.test.sh

@@ -0,0 +1,170 @@
+#!/bin/bash
+# analyze-gate.test.sh — bin/analyze-gate.js (cross-artifact scope↔plan gate)
+# Run: bash tests/analyze-gate.test.sh
+
+PASS=0
+FAIL=0
+BIN_DIR="$(cd "$(dirname "$0")/../bin" && pwd)"
+NODE="${NODE:-node}"
+AG="$BIN_DIR/analyze-gate.js"
+
+assert_exit() {
+  local name="$1" expected="$2" actual="$3"
+  if [ "$expected" = "$actual" ]; then echo "  ✓ $name"; PASS=$((PASS+1));
+  else echo "  ✗ $name (expected exit $expected, got $actual)"; FAIL=$((FAIL+1)); fi
+}
+assert_contains() {
+  local name="$1" hay="$2" needle="$3"
+  if echo "$hay" | grep -q "$needle"; then echo "  ✓ $name"; PASS=$((PASS+1));
+  else echo "  ✗ $name (missing '$needle' in: $hay)"; FAIL=$((FAIL+1)); fi
+}
+
+# A contract whose tasks cover "checkout" + "stripe webhook" + "email receipt".
+write_good_contract() {
+  cat > "$1" <<'EOF'
+{
+  "version": 1,
+  "phase": 2,
+  "goal": "Customers can pay for an order and receive a receipt",
+  "why": "revenue",
+  "success_criteria": ["Checkout charges the card via Stripe", "Customer receives an email receipt"],
+  "tasks": [
+    { "id": "T1", "title": "Stripe checkout charge", "action": "Implement the checkout endpoint that charges the card through the Stripe webhook handler", "acceptance_criteria": ["Checkout charges card via Stripe successfully"] },
+    { "id": "T2", "title": "Email receipt", "action": "Send an email receipt to the customer after a successful charge", "acceptance_criteria": ["Customer receives an email receipt after payment"] }
+  ]
+}
+EOF
+}
+
+write_scope() {
+  cat > "$1" <<'EOF'
+---
+phase: 2
+---
+# Phase 2 Context: Payments
+
+## Acceptance Criteria (testable)
+- AC1 — Checkout charges the card through Stripe
+- AC2 — Customer receives an email receipt
+- AC3 — Failed payments display a retry banner with a refund option
+
+## DoD closure
+- Security: resolved
+EOF
+}
+
+echo "analyze-gate.test.sh — bin/analyze-gate.js"
+echo ""
+
+# syntax
+$NODE -c "$AG" 2>/dev/null && { echo "  ✓ syntax valid"; PASS=$((PASS+1)); } || { echo "  ✗ syntax invalid"; FAIL=$((FAIL+1)); }
+
+# --- clean: every scope AC covered, every success criterion has a task ---
+TMP=$(mktemp -d); mkdir -p "$TMP/.planning"
+write_good_contract "$TMP/.planning/phase-2-contract.json"
+# scope with only the two covered ACs
+cat > "$TMP/.planning/phase-2-context.md" <<'EOF'
+## Acceptance Criteria (testable)
+- AC1 — Checkout charges the card through Stripe
+- AC2 — Customer receives an email receipt
+EOF
+$NODE "$AG" 2 --cwd "$TMP" >/dev/null 2>&1
+assert_exit "all covered → ANALYZE PASS (exit 0)" 0 $?
+OUT=$($NODE "$AG" 2 --cwd "$TMP" 2>&1)
+assert_contains "reports PASS" "$OUT" "ANALYZE PASS"
+rm -rf "$TMP"
+
+# --- under-covered scope AC (the retry/refund banner is in scope, not in plan) ---
+TMP=$(mktemp -d); mkdir -p "$TMP/.planning"
+write_good_contract "$TMP/.planning/phase-2-contract.json"
+write_scope "$TMP/.planning/phase-2-context.md"
+OUT=$($NODE "$AG" 2 --cwd "$TMP" 2>&1)
+RC=$?
+assert_exit "uncovered scope AC → findings (exit 1)" 1 $RC
+assert_contains "flags the uncovered AC" "$OUT" "under-covered"
+assert_contains "names the refund/retry requirement" "$OUT" "retry banner"
+# JSON shape carries the finding type
+OUT=$($NODE "$AG" 2 --cwd "$TMP" --json 2>&1)
+assert_contains "json finding type" "$OUT" '"uncovered-scope-ac"'
+assert_contains "json severity HIGH" "$OUT" '"severity": "HIGH"'
+rm -rf "$TMP"
+
+# --- orphan success criterion (no task covers it) ---
+TMP=$(mktemp -d); mkdir -p "$TMP/.planning"
+cat > "$TMP/.planning/phase-3-contract.json" <<'EOF'
+{
+  "version": 1,
+  "phase": 3,
+  "goal": "g",
+  "why": "w",
+  "success_criteria": ["Dashboard exports analytics to CSV"],
+  "tasks": [
+    { "id": "T1", "title": "Login form", "action": "Build the login form with password reset", "acceptance_criteria": ["User can log in"] }
+  ]
+}
+EOF
+OUT=$($NODE "$AG" 3 --cwd "$TMP" --json 2>&1)
+RC=$?
+assert_exit "orphan success criterion → exit 1" 1 $RC
+assert_contains "flags orphan success criterion" "$OUT" '"uncovered-success-criterion"'
+rm -rf "$TMP"
+
+# --- glossary violation: plan uses a banned alias ---
+TMP=$(mktemp -d); mkdir -p "$TMP/.planning"
+cat > "$TMP/.planning/phase-1-contract.json" <<'EOF'
+{
+  "version": 1,
+  "phase": 1,
+  "goal": "Manage the AuthUser session lifecycle",
+  "why": "w",
+  "success_criteria": ["Sessions expire after 24h"],
+  "tasks": [
+    { "id": "T1", "title": "Session expiry", "action": "Expire AuthUser sessions after twentyfour hours of inactivity", "acceptance_criteria": ["Sessions expire after the configured window"] }
+  ]
+}
+EOF
+cat > "$TMP/.planning/CONTEXT.md" <<'EOF'
+# Glossary
+## Language
+### Customer
+The paying account holder.
+**Avoid:** AuthUser vs Customer (unless disambiguated)
+EOF
+OUT=$($NODE "$AG" 1 --cwd "$TMP" --json 2>&1)
+RC=$?
+assert_exit "banned glossary alias → exit 1" 1 $RC
+assert_contains "flags glossary violation" "$OUT" '"glossary-violation"'
+assert_contains "names the banned term" "$OUT" "AuthUser"
+rm -rf "$TMP"
+
+# --- no scope file → scope-coverage skipped, not a failure ---
+TMP=$(mktemp -d); mkdir -p "$TMP/.planning"
+write_good_contract "$TMP/.planning/phase-2-contract.json"
+# no phase-2-context.md, no CONTEXT.md
+OUT=$($NODE "$AG" 2 --cwd "$TMP" 2>&1)
+RC=$?
+assert_exit "no scope file → exit 0 (skipped)" 0 $RC
+assert_contains "notes the skip" "$OUT" "scope-coverage check skipped"
+rm -rf "$TMP"
+
+# --- missing contract → invocation error (exit 2) ---
+TMP=$(mktemp -d); mkdir -p "$TMP/.planning"
+$NODE "$AG" 9 --cwd "$TMP" >/dev/null 2>&1
+assert_exit "missing contract → exit 2" 2 $?
+rm -rf "$TMP"
+
+# --- library: coverage() unit behavior ---
+COV=$($NODE -e "const a=require('$AG'); const t=a.tokenize('Checkout charges the card via Stripe'); const set=new Set(t); console.log(a.coverage('Checkout charges card Stripe', set).covered)" 2>&1)
+assert_contains "coverage true when terms overlap" "$COV" "true"
+COV=$($NODE -e "const a=require('$AG'); console.log(a.coverage('Quantum teleportation export pipeline', new Set(['login','password'])).covered)" 2>&1)
+assert_contains "coverage false when disjoint" "$COV" "false"
+
+# --- library: scope AC parser strips the AC label ---
+ACS=$($NODE -e "const a=require('$AG'); console.log(JSON.stringify(a.parseScopeAcceptanceCriteria('## Acceptance Criteria (testable)\n- AC1 — Checkout works\n- AC2 — Receipt sent\n## Next\n- ignored')))" 2>&1)
+assert_contains "parses AC1 without label" "$ACS" "Checkout works"
+assert_contains "stops at next heading" "$ACS" "Receipt sent"
+if echo "$ACS" | grep -q "ignored"; then echo "  ✗ parser leaked past section"; FAIL=$((FAIL+1)); else echo "  ✓ parser stops at next ## heading"; PASS=$((PASS+1)); fi
+
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1

package/tests/bin.test.sh

@@ -487,15 +487,16 @@ else
   fail_case "CLAUDE.md role substitution"
 fi
 
-# 31. All 14 hooks installed (block-env-edit removed in v3.2.0;
+# 31. All 15 hooks installed (block-env-edit removed in v3.2.0;
 # git-guardrails + stop-session-log added in v4.2.0;
 # vercel-account-guard + env-empty-guard + supabase-destructive-guard added in v5.0.0;
 # fawzi-approval-guard added in v6.2.11; pre-compact removed in v6.2.0 and
 # REINTRODUCED in v6.3.2 with sidecar-snapshot mechanism;
-# usage-capture added in v6.9.1 — UserPromptSubmit telemetry capture)
+# usage-capture added in v6.9.1 — UserPromptSubmit telemetry capture;
+# task-write-guard added in v6.13 — R1 runtime plan-contract file-scope guard)
 HOOK_COUNT=$(ls "$TMP/.claude/hooks/"*.js 2>/dev/null | wc -l)
-if [ "$HOOK_COUNT" -eq 14 ]; then
-  pass "14 hooks installed in hooks/ (incl. usage-capture v6.9.1)"
+if [ "$HOOK_COUNT" -eq 15 ]; then
+  pass "15 hooks installed in hooks/ (incl. task-write-guard v6.13)"
 else
   fail_case "hook count" "got $HOOK_COUNT"
 fi

package/tests/branch-hygiene.test.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# branch-hygiene.test.sh — bin/branch-hygiene.js (clock-out stranded-branch sweep)
+# Run: bash tests/branch-hygiene.test.sh
+
+PASS=0
+FAIL=0
+BIN_DIR="$(cd "$(dirname "$0")/../bin" && pwd)"
+NODE="${NODE:-node}"
+BH="$BIN_DIR/branch-hygiene.js"
+
+assert_exit() {
+  local name="$1" expected="$2" actual="$3"
+  if [ "$expected" = "$actual" ]; then echo "  ✓ $name"; PASS=$((PASS+1));
+  else echo "  ✗ $name (expected exit $expected, got $actual)"; FAIL=$((FAIL+1)); fi
+}
+assert_contains() {
+  local name="$1" hay="$2" needle="$3"
+  if echo "$hay" | grep -qF "$needle"; then echo "  ✓ $name"; PASS=$((PASS+1));
+  else echo "  ✗ $name (missing '$needle' in: $hay)"; FAIL=$((FAIL+1)); fi
+}
+
+# fresh repo on main with one commit; prints the dir (caller rm -rf)
+setup_repo() {
+  local tmp
+  tmp=$(mktemp -d)
+  (cd "$tmp" \
+    && git init -q \
+    && git checkout -q -b main 2>/dev/null \
+    && git config user.email t@t.com && git config user.name T \
+    && echo seed > seed.txt && git add seed.txt && git commit -q -m seed)
+  echo "$tmp"
+}
+
+echo "branch-hygiene.test.sh — bin/branch-hygiene.js"
+echo ""
+
+$NODE -c "$BH" 2>/dev/null && { echo "  ✓ syntax valid"; PASS=$((PASS+1)); } || { echo "  ✗ syntax invalid"; FAIL=$((FAIL+1)); }
+
+# --- not a git repo → exit 2 ---
+TMP=$(mktemp -d)
+(cd "$TMP" && $NODE "$BH" >/dev/null 2>&1)
+assert_exit "not a git repo → exit 2" 2 $?
+rm -rf "$TMP"
+
+# --- clean: only main → exit 0 ---
+TMP=$(setup_repo)
+(cd "$TMP" && $NODE "$BH" >/dev/null 2>&1)
+assert_exit "clean repo (main only) → exit 0" 0 $?
+OUT=$(cd "$TMP" && $NODE "$BH" 2>&1)
+assert_contains "reports clean" "$OUT" "clean"
+rm -rf "$TMP"
+
+# --- stranded feature branch ahead of main → exit 1, listed ---
+TMP=$(setup_repo)
+(cd "$TMP" && git checkout -q -b feat/stranded && echo work > w.txt && git add w.txt && git commit -q -m "wip work")
+(cd "$TMP" && $NODE "$BH" >/dev/null 2>&1)
+assert_exit "branch ahead of main → exit 1" 1 $?
+OUT=$(cd "$TMP" && $NODE "$BH" 2>&1)
+assert_contains "lists the stranded branch" "$OUT" "feat/stranded"
+assert_contains "shows commits ahead" "$OUT" "+1 commit"
+# json shape
+OUT=$(cd "$TMP" && $NODE "$BH" --json 2>&1)
+assert_contains "json stranded entry" "$OUT" '"branch": "feat/stranded"'
+assert_contains "json ahead count" "$OUT" '"ahead": 1'
+rm -rf "$TMP"
+
+# --- once integrated (ff-merged) into main → no longer stranded → exit 0 ---
+TMP=$(setup_repo)
+(cd "$TMP" && git checkout -q -b feat/done && echo x > x.txt && git add x.txt && git commit -q -m "done work")
+(cd "$TMP" && git checkout -q main && git merge -q --ff-only feat/done)
+(cd "$TMP" && $NODE "$BH" >/dev/null 2>&1)
+assert_exit "ff-merged branch no longer stranded → exit 0" 0 $?
+rm -rf "$TMP"
+
+# --- master as the base branch is detected ---
+TMP=$(mktemp -d)
+(cd "$TMP" && git init -q && git checkout -q -b master 2>/dev/null && git config user.email t@t.com && git config user.name T && echo s > s.txt && git add s.txt && git commit -q -m s)
+(cd "$TMP" && git checkout -q -b feature && echo y > y.txt && git add y.txt && git commit -q -m y)
+OUT=$(cd "$TMP" && $NODE "$BH" --json 2>&1)
+assert_contains "detects master as base" "$OUT" '"base": "master"'
+assert_contains "stranded vs master" "$OUT" '"branch": "feature"'
+rm -rf "$TMP"
+
+# --- library: analyze() returns structured result ---
+TMP=$(setup_repo)
+(cd "$TMP" && git checkout -q -b b1 && echo a>a && git add a && git commit -q -m a)
+RES=$($NODE -e "console.log(JSON.stringify(require('$BH').analyze('$TMP').stranded.length))" 2>&1)
+assert_contains "analyze() finds 1 stranded" "$RES" "1"
+rm -rf "$TMP"
+
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1

package/tests/eval-runner.test.sh

@@ -0,0 +1,147 @@
+#!/bin/bash
+# eval-runner.test.sh — bin/eval-runner.js (layered AI-feature eval, R7)
+# Run: bash tests/eval-runner.test.sh
+
+PASS=0
+FAIL=0
+BIN_DIR="$(cd "$(dirname "$0")/../bin" && pwd)"
+NODE="${NODE:-node}"
+ER="$BIN_DIR/eval-runner.js"
+
+assert_exit() {
+  local name="$1" expected="$2" actual="$3"
+  if [ "$expected" = "$actual" ]; then echo "  ✓ $name"; PASS=$((PASS+1));
+  else echo "  ✗ $name (expected exit $expected, got $actual)"; FAIL=$((FAIL+1)); fi
+}
+assert_contains() {
+  local name="$1" hay="$2" needle="$3"
+  if echo "$hay" | grep -qF "$needle"; then echo "  ✓ $name"; PASS=$((PASS+1));
+  else echo "  ✗ $name (missing '$needle' in: $hay)"; FAIL=$((FAIL+1)); fi
+}
+
+echo "eval-runner.test.sh — bin/eval-runner.js"
+echo ""
+
+$NODE -c "$ER" 2>/dev/null && { echo "  ✓ syntax valid"; PASS=$((PASS+1)); } || { echo "  ✗ syntax invalid"; FAIL=$((FAIL+1)); }
+
+# --- all deterministic assertions pass → PASS ---
+TMP=$(mktemp -d)
+cat > "$TMP/s.json" <<'EOF'
+{ "feature":"support-chat", "cases":[
+  { "name":"refund", "output":"We refund within 30 days.", "latency_ms":1200, "cost_usd":0.008,
+    "assert":[
+      {"type":"contains","value":"30 days"},
+      {"type":"not_contains","value":"I cannot help"},
+      {"type":"regex","value":"\\b30\\b"},
+      {"type":"min_length","value":5},
+      {"type":"max_latency_ms","value":2000},
+      {"type":"max_cost_usd","value":0.02}
+    ] } ] }
+EOF
+$NODE "$ER" "$TMP/s.json" >/dev/null 2>&1
+assert_exit "all deterministic pass → exit 0" 0 $?
+OUT=$($NODE "$ER" "$TMP/s.json" 2>&1)
+assert_contains "reports EVAL PASS" "$OUT" "EVAL PASS"
+rm -rf "$TMP"
+
+# --- a failing contains → FAIL with the failing assertion shown ---
+TMP=$(mktemp -d)
+cat > "$TMP/s.json" <<'EOF'
+{ "feature":"chat", "cases":[
+  { "name":"refusal", "output":"I cannot help with that.",
+    "assert":[ {"type":"contains","value":"30 days"}, {"type":"not_contains","value":"I cannot help"} ] } ] }
+EOF
+$NODE "$ER" "$TMP/s.json" >/dev/null 2>&1
+assert_exit "failing assertion → exit 1" 1 $?
+OUT=$($NODE "$ER" "$TMP/s.json" 2>&1)
+assert_contains "shows failing case" "$OUT" "refusal"
+rm -rf "$TMP"
+
+# --- latency over budget → FAIL ---
+TMP=$(mktemp -d)
+cat > "$TMP/s.json" <<'EOF'
+{ "feature":"chat", "cases":[
+  { "name":"slow", "output":"ok", "latency_ms":5000, "assert":[ {"type":"max_latency_ms","value":2000} ] } ] }
+EOF
+$NODE "$ER" "$TMP/s.json" >/dev/null 2>&1
+assert_exit "latency over budget → exit 1" 1 $?
+# missing latency metric but asserted → fail (no silent pass)
+cat > "$TMP/s2.json" <<'EOF'
+{ "feature":"chat", "cases":[ { "name":"no-metric", "output":"ok", "assert":[ {"type":"max_latency_ms","value":2000} ] } ] }
+EOF
+$NODE "$ER" "$TMP/s2.json" >/dev/null 2>&1
+assert_exit "asserting latency with none recorded → exit 1" 1 $?
+rm -rf "$TMP"
+
+# --- json_path + json_valid ---
+TMP=$(mktemp -d)
+cat > "$TMP/s.json" <<'EOF'
+{ "feature":"rag", "cases":[
+  { "name":"structured", "output":"{\"answer\":\"yes\",\"sources\":[{\"id\":\"doc1\"}]}",
+    "assert":[
+      {"type":"json_valid"},
+      {"type":"json_path","path":"answer","equals":"yes"},
+      {"type":"json_path","path":"sources.0.id","contains":"doc"}
+    ] } ] }
+EOF
+$NODE "$ER" "$TMP/s.json" >/dev/null 2>&1
+assert_exit "json_path + json_valid pass → exit 0" 0 $?
+# invalid json under json_valid → fail
+cat > "$TMP/bad.json" <<'EOF'
+{ "feature":"rag", "cases":[ { "name":"notjson", "output":"not json", "assert":[ {"type":"json_valid"} ] } ] }
+EOF
+$NODE "$ER" "$TMP/bad.json" >/dev/null 2>&1
+assert_exit "json_valid on non-json → exit 1" 1 $?
+rm -rf "$TMP"
+
+# --- llm_rubric: verdict pass / fail / pending ---
+TMP=$(mktemp -d)
+cat > "$TMP/pass.json" <<'EOF'
+{ "feature":"chat", "cases":[ { "name":"r", "output":"grounded answer", "assert":[ {"type":"llm_rubric","rubric":"grounded","verdict":"pass"} ] } ] }
+EOF
+$NODE "$ER" "$TMP/pass.json" >/dev/null 2>&1
+assert_exit "llm_rubric verdict=pass → exit 0" 0 $?
+cat > "$TMP/fail.json" <<'EOF'
+{ "feature":"chat", "cases":[ { "name":"r", "output":"hallucination", "assert":[ {"type":"llm_rubric","rubric":"grounded","verdict":"fail"} ] } ] }
+EOF
+$NODE "$ER" "$TMP/fail.json" >/dev/null 2>&1
+assert_exit "llm_rubric verdict=fail → exit 1" 1 $?
+cat > "$TMP/pending.json" <<'EOF'
+{ "feature":"chat", "cases":[ { "name":"r", "output":"x", "assert":[ {"type":"llm_rubric","rubric":"grounded"} ] } ] }
+EOF
+$NODE "$ER" "$TMP/pending.json" >/dev/null 2>&1
+assert_exit "unjudged llm_rubric → PENDING → exit 1 (no silent pass)" 1 $?
+OUT=$($NODE "$ER" "$TMP/pending.json" 2>&1)
+assert_contains "reports unjudged rubric count" "$OUT" "unjudged"
+rm -rf "$TMP"
+
+# --- output_file resolution + --write artifact ---
+TMP=$(mktemp -d); mkdir -p "$TMP/.planning"
+echo -n "the answer is 42" > "$TMP/out.txt"
+cat > "$TMP/s.json" <<'EOF'
+{ "feature":"file-feature", "cases":[ { "name":"fromfile", "output_file":"out.txt", "assert":[ {"type":"contains","value":"42"} ] } ] }
+EOF
+(cd "$TMP" && $NODE "$ER" s.json --write >/dev/null 2>&1)
+assert_exit "output_file case passes → exit 0" 0 $?
+[ -f "$TMP/.planning/evals/eval-file-feature.json" ] && { echo "  ✓ --write emits eval artifact"; PASS=$((PASS+1)); } || { echo "  ✗ no eval artifact"; FAIL=$((FAIL+1)); }
+# missing output_file → fail, not crash
+cat > "$TMP/miss.json" <<'EOF'
+{ "feature":"x", "cases":[ { "name":"gone", "output_file":"nope.txt", "assert":[ {"type":"contains","value":"y"} ] } ] }
+EOF
+(cd "$TMP" && $NODE "$ER" miss.json >/dev/null 2>&1)
+assert_exit "missing output_file → exit 1 (graceful)" 1 $?
+rm -rf "$TMP"
+
+# --- library: runAssertion unit ---
+U=$($NODE -e "const e=require('$ER'); console.log(e.runAssertion({type:'contains',value:'hi'},{output:'oh hi there'}).ok)" 2>&1)
+assert_contains "runAssertion contains true" "$U" "true"
+U=$($NODE -e "const e=require('$ER'); console.log(e.getPath({a:{b:[{c:9}]}},'a.b.0.c'))" 2>&1)
+assert_contains "getPath nested+index" "$U" "9"
+
+# --- malformed suite → exit 2 ---
+$NODE "$ER" /nonexistent-suite.json >/dev/null 2>&1
+assert_exit "missing suite → exit 2" 2 $?
+
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1