qualia-framework 6.14.0 → 7.0.0

package/tests/batch-plan.test.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# batch-plan.test.sh — bin/batch-plan.js (/qualia-build --batch split, R20)
+# Run: bash tests/batch-plan.test.sh
+
+PASS=0
+FAIL=0
+BIN_DIR="$(cd "$(dirname "$0")/../bin" && pwd)"
+NODE="${NODE:-node}"
+BP="$BIN_DIR/batch-plan.js"
+
+assert_exit()     { if [ "$2" = "$3" ]; then echo "  ✓ $1"; PASS=$((PASS+1)); else echo "  ✗ $1 (expected exit $2, got $3)"; FAIL=$((FAIL+1)); fi; }
+assert_contains() { if echo "$2" | grep -qF -- "$3"; then echo "  ✓ $1"; PASS=$((PASS+1)); else echo "  ✗ $1 (missing '$3')"; FAIL=$((FAIL+1)); fi; }
+jcheck() { echo "$1" | $NODE -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{const p=JSON.parse(s);process.exit(($2)?0:1)})"; }
+
+echo "batch-plan.test.sh — bin/batch-plan.js"
+echo ""
+
+$NODE -c "$BP" 2>/dev/null && { echo "  ✓ syntax valid"; PASS=$((PASS+1)); } || { echo "  ✗ syntax invalid"; FAIL=$((FAIL+1)); }
+
+FILES=$(seq -f "src/f%g.ts" 1 23)
+
+# ── split math ──
+JSON=$($NODE "$BP" $FILES --batch-size 10 --max-workers 3 --json 2>&1); assert_exit "valid run → exit 0" 0 $?
+jcheck "$JSON" "p.total_files===23"   && { echo "  ✓ counts all files"; PASS=$((PASS+1)); } || { echo "  ✗ total_files"; FAIL=$((FAIL+1)); }
+jcheck "$JSON" "p.batch_count===3"    && { echo "  ✓ ceil(23/10)=3 batches"; PASS=$((PASS+1)); } || { echo "  ✗ batch_count"; FAIL=$((FAIL+1)); }
+jcheck "$JSON" "p.batches.every(b=>b.files.length<=10)" && { echo "  ✓ every batch ≤ batch-size"; PASS=$((PASS+1)); } || { echo "  ✗ batch size cap"; FAIL=$((FAIL+1)); }
+
+# ── disjoint + complete: every file in exactly one batch ──
+jcheck "$JSON" "(()=>{const a=p.batches.flatMap(b=>b.files);return a.length===23&&new Set(a).size===23})()" \
+  && { echo "  ✓ file-disjoint + complete (each file exactly once)"; PASS=$((PASS+1)); } || { echo "  ✗ disjointness"; FAIL=$((FAIL+1)); }
+
+# ── waves cap at max-workers ──
+jcheck "$JSON" "p.waves.every(w=>w.length<=3)" && { echo "  ✓ waves capped at max-workers"; PASS=$((PASS+1)); } || { echo "  ✗ wave cap"; FAIL=$((FAIL+1)); }
+jcheck "$JSON" "typeof p.staging_branch==='string'&&Array.isArray(p.waves)&&Array.isArray(p.batches)" \
+  && { echo "  ✓ --json shape (staging_branch/waves/batches)"; PASS=$((PASS+1)); } || { echo "  ✗ json shape"; FAIL=$((FAIL+1)); }
+
+# ── dedup ──
+jcheck "$($NODE "$BP" a a b --json 2>&1)" "p.total_files===2" && { echo "  ✓ de-dups repeated files"; PASS=$((PASS+1)); } || { echo "  ✗ dedup"; FAIL=$((FAIL+1)); }
+
+# ── --from FILE + stdin ──
+TMP=$(mktemp -d); printf 'x.ts\ny.ts\nz.ts\n' > "$TMP/list.txt"
+jcheck "$($NODE "$BP" --from "$TMP/list.txt" --json 2>&1)" "p.total_files===3" && { echo "  ✓ reads --from FILE"; PASS=$((PASS+1)); } || { echo "  ✗ --from file"; FAIL=$((FAIL+1)); }
+jcheck "$(printf 'a\nb\n' | $NODE "$BP" --from - --json 2>&1)" "p.total_files===2" && { echo "  ✓ reads --from - (stdin)"; PASS=$((PASS+1)); } || { echo "  ✗ --from stdin"; FAIL=$((FAIL+1)); }
+
+# ── human output mentions staging branch ──
+assert_contains "human output names staging branch" "$($NODE "$BP" a b --staging mig/x 2>&1)" "mig/x"
+
+# ── edge cases ──
+$NODE "$BP" --from /no/such/list.txt >/dev/null 2>&1; assert_exit "missing --from file → exit 2" 2 $?
+EOUT=$($NODE "$BP" 2>&1); assert_exit "no files → exit 0" 0 $?
+assert_contains "no files → friendly message" "$EOUT" "nothing to migrate"
+
+rm -rf "$TMP"
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

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/design-tokens.test.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# design-tokens.test.sh — bin/design-tokens.js (per-client token registry, R10)
+# Run: bash tests/design-tokens.test.sh
+
+PASS=0
+FAIL=0
+BIN_DIR="$(cd "$(dirname "$0")/../bin" && pwd)"
+NODE="${NODE:-node}"
+DT="$BIN_DIR/design-tokens.js"
+
+assert_exit()     { if [ "$2" = "$3" ]; then echo "  ✓ $1"; PASS=$((PASS+1)); else echo "  ✗ $1 (expected exit $2, got $3)"; FAIL=$((FAIL+1)); fi; }
+assert_contains() { if echo "$2" | grep -qF -- "$3"; then echo "  ✓ $1"; PASS=$((PASS+1)); else echo "  ✗ $1 (missing '$3')"; FAIL=$((FAIL+1)); fi; }
+
+echo "design-tokens.test.sh — bin/design-tokens.js"
+echo ""
+
+$NODE -c "$DT" 2>/dev/null && { echo "  ✓ syntax valid"; PASS=$((PASS+1)); } || { echo "  ✗ syntax invalid"; FAIL=$((FAIL+1)); }
+
+TMP=$(mktemp -d)
+
+# ── init ──
+$NODE "$DT" init --out "$TMP/tokens.json" >/dev/null 2>&1; assert_exit "init → exit 0" 0 $?
+INITJSON=$(cat "$TMP/tokens.json")
+echo "$INITJSON" | $NODE -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{const j=JSON.parse(s);process.exit(j.color&&j.font?0:1)})" \
+  && { echo "  ✓ init writes valid registry JSON (color+font)"; PASS=$((PASS+1)); } || { echo "  ✗ init JSON shape"; FAIL=$((FAIL+1)); }
+
+# ── compile → CSS ──
+CSS=$($NODE "$DT" compile "$TMP/tokens.json" 2>&1); assert_exit "compile → exit 0" 0 $?
+assert_contains "emits :root block"            "$CSS" ":root {"
+assert_contains "flattens nested color → var"  "$CSS" "--color-accent:"
+assert_contains "flattens nested font → var"   "$CSS" "--font-sans:"
+assert_contains "flattens nested radius → var" "$CSS" "--radius-md:"
+assert_contains "carries the hardcoded-hex ban reminder" "$CSS" "ABS-HEX-IN-JSX"
+
+# ── compile --json (flat map) ──
+FLAT=$($NODE "$DT" compile "$TMP/tokens.json" --json 2>&1)
+echo "$FLAT" | $NODE -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{const j=JSON.parse(s);process.exit(j['color-bg']?0:1)})" \
+  && { echo "  ✓ --json flat var map valid"; PASS=$((PASS+1)); } || { echo "  ✗ --json flat map"; FAIL=$((FAIL+1)); }
+
+# ── compile --out writes file ──
+$NODE "$DT" compile "$TMP/tokens.json" --out "$TMP/tokens.css" >/dev/null 2>&1
+[ -f "$TMP/tokens.css" ] && grep -q "^:root" "$TMP/tokens.css" && { echo "  ✓ compile --out writes tokens.css"; PASS=$((PASS+1)); } || { echo "  ✗ compile --out"; FAIL=$((FAIL+1)); }
+
+# ── error paths ──
+$NODE "$DT" compile /no/such/file.json >/dev/null 2>&1; assert_exit "missing file → exit 2" 2 $?
+echo '{ broken' > "$TMP/bad.json"
+$NODE "$DT" compile "$TMP/bad.json" >/dev/null 2>&1; assert_exit "invalid JSON → exit 2" 2 $?
+$NODE "$DT" bogus-cmd >/dev/null 2>&1; assert_exit "unknown command → exit 2" 2 $?
+
+rm -rf "$TMP"
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

package/tests/erp-event.test.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+# erp-event.test.sh — bin/erp-event.js (framework EMIT side of the R14 event log)
+# Run: bash tests/erp-event.test.sh
+
+PASS=0
+FAIL=0
+BIN_DIR="$(cd "$(dirname "$0")/../bin" && pwd)"
+NODE="${NODE:-node}"
+EE="$BIN_DIR/erp-event.js"
+
+assert_exit()     { if [ "$2" = "$3" ]; then echo "  ✓ $1"; PASS=$((PASS+1)); else echo "  ✗ $1 (expected exit $2, got $3)"; FAIL=$((FAIL+1)); fi; }
+assert_contains() { if echo "$2" | grep -qF -- "$3"; then echo "  ✓ $1"; PASS=$((PASS+1)); else echo "  ✗ $1 (missing '$3')"; FAIL=$((FAIL+1)); fi; }
+assert_absent()   { if echo "$2" | grep -qF -- "$3"; then echo "  ✗ $1 (unexpected '$3')"; FAIL=$((FAIL+1)); else echo "  ✓ $1"; PASS=$((PASS+1)); fi; }
+
+echo "erp-event.test.sh — bin/erp-event.js"
+echo ""
+
+$NODE -c "$EE" 2>/dev/null && { echo "  ✓ syntax valid"; PASS=$((PASS+1)); } || { echo "  ✗ syntax invalid"; FAIL=$((FAIL+1)); }
+
+# ── unit: build + sign (the cross-repo contract) ──
+$NODE -e '
+const { buildSignedEvent, signingContent, computeSignature } = require("'"$EE"'");
+const cfg = { code: "QS-FAWZI-11", installed_by: "Fawzi", role: "OWNER" };
+const b = buildSignedEvent("verify_pass", { id: "evt1", now: 1750000000, apiKey: "qlt_k", config: cfg, targets: [{type:"project",ref:"acme"}] });
+const ok =
+  b.event.action === "verify_pass" &&
+  b.event.actor.code === "QS-FAWZI-11" && b.event.actor.role === "OWNER" &&
+  b.headers["Qualia-Event-Id"] === "evt1" &&
+  b.headers["Qualia-Event-Timestamp"] === "1750000000" &&
+  // signature must equal a fresh recompute over `${id}.${ts}.${payload}` (the ERP verify)
+  b.headers["Qualia-Signature"] === computeSignature(signingContent("evt1","1750000000",b.payload), "qlt_k") &&
+  // and must NOT match a wrong key
+  b.headers["Qualia-Signature"] !== computeSignature(signingContent("evt1","1750000000",b.payload), "qlt_other");
+process.exit(ok ? 0 : 1);
+' && { echo "  ✓ builds envelope + signature byte-matches the ERP verify algorithm"; PASS=$((PASS+1)); } || { echo "  ✗ build/sign contract"; FAIL=$((FAIL+1)); }
+
+# unsigned when no key: no Qualia-Signature header, still a valid envelope
+$NODE -e '
+const { buildSignedEvent } = require("'"$EE"'");
+const b = buildSignedEvent("session_started", { id:"e", now:1, apiKey:"", config:{} });
+process.exit(b.headers["Qualia-Signature"] === undefined && b.headers["Qualia-Event-Id"] === "e" ? 0 : 1);
+' && { echo "  ✓ no API key → unsigned envelope (Bearer still authenticates server-side)"; PASS=$((PASS+1)); } || { echo "  ✗ unsigned path"; FAIL=$((FAIL+1)); }
+
+# ── CLI behavior with a temp install home ──
+HOME_DIR=$(mktemp -d)
+mkdir -p "$HOME_DIR/bin"
+cp "$BIN_DIR/erp-retry.js" "$HOME_DIR/bin/erp-retry.js"
+printf '{"role":"OWNER","code":"QS-FAWZI-11","installed_by":"Fawzi","erp":{"enabled":true,"url":"https://example.test"}}' > "$HOME_DIR/.qualia-config.json"
+printf 'qlt_testkey' > "$HOME_DIR/.erp-api-key"
+RUN(){ QUALIA_HOME="$HOME_DIR" $NODE "$EE" "$@"; }
+
+# dry-run: does NOT enqueue
+OUT=$(RUN emit verify_pass --target project:x --dry-run --json 2>&1); assert_exit "dry-run → exit 0" 0 $?
+assert_contains "dry-run builds a signature" "$OUT" "Qualia-Signature"
+[ ! -f "$HOME_DIR/.erp-retry-queue.json" ] && { echo "  ✓ dry-run does not enqueue"; PASS=$((PASS+1)); } || { echo "  ✗ dry-run enqueued"; FAIL=$((FAIL+1)); }
+
+# real emit: enqueues an item carrying the signed headers + /events url
+RUN emit build_wave_started --target project:x --project 7b5d3b4e-2b8a-4de4-91a1-9b2f3182f5ef >/dev/null 2>&1
+Q=$(cat "$HOME_DIR/.erp-retry-queue.json" 2>/dev/null)
+assert_contains "emit enqueues to /api/v1/events"  "$Q" "/api/v1/events"
+assert_contains "queued item carries the signature header" "$Q" "Qualia-Signature"
+assert_contains "queued item carries the event action"     "$Q" "build_wave_started"
+
+# ERP disabled → skipped, no enqueue
+HOME2=$(mktemp -d)
+printf '{"role":"OWNER","erp":{"enabled":false}}' > "$HOME2/.qualia-config.json"
+OUT=$(QUALIA_HOME="$HOME2" $NODE "$EE" emit verify_fail 2>&1); assert_exit "erp disabled → exit 0" 0 $?
+assert_contains "erp disabled → skipped" "$OUT" "skipped"
+[ ! -f "$HOME2/.erp-retry-queue.json" ] && { echo "  ✓ erp disabled → no enqueue"; PASS=$((PASS+1)); } || { echo "  ✗ enqueued while disabled"; FAIL=$((FAIL+1)); }
+
+# bad invocation
+$NODE "$EE" >/dev/null 2>&1; assert_exit "no action → exit 2" 2 $?
+$NODE "$EE" emit >/dev/null 2>&1; assert_exit "emit without action → exit 2" 2 $?
+
+rm -rf "$HOME_DIR" "$HOME2"
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

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

package/tests/instructions.test.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+# instructions.test.sh — single-source instruction compile (R4) + host adapter
+# contract (R5). Run: bash tests/instructions.test.sh
+
+PASS=0
+FAIL=0
+FRAMEWORK_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+NODE="${NODE:-node}"
+HA="$FRAMEWORK_DIR/bin/host-adapters.js"
+CI="$FRAMEWORK_DIR/bin/compile-instructions.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_eq() {
+  local name="$1" expected="$2" actual="$3"
+  if [ "$expected" = "$actual" ]; then echo "  ✓ $name"; PASS=$((PASS+1));
+  else echo "  ✗ $name (expected '$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')"; FAIL=$((FAIL+1)); fi
+}
+refute_contains() {
+  local name="$1" hay="$2" needle="$3"
+  if echo "$hay" | grep -qF "$needle"; then echo "  ✗ $name (found '$needle')"; FAIL=$((FAIL+1));
+  else echo "  ✓ $name"; PASS=$((PASS+1)); fi
+}
+
+echo "instructions.test.sh — single-source compile (R4) + host contract (R5)"
+echo ""
+
+# syntax
+$NODE -c "$HA" 2>/dev/null && { echo "  ✓ host-adapters syntax valid"; PASS=$((PASS+1)); } || { echo "  ✗ host-adapters syntax"; FAIL=$((FAIL+1)); }
+$NODE -c "$CI" 2>/dev/null && { echo "  ✓ compile-instructions syntax valid"; PASS=$((PASS+1)); } || { echo "  ✗ compile-instructions syntax"; FAIL=$((FAIL+1)); }
+
+# --- R4: drift guard — committed files match the canonical ---
+$NODE "$CI" --check >/dev/null 2>&1
+assert_exit "compile-instructions --check passes (no drift)" 0 $?
+
+# A canonical edit not reflected in the artifacts is caught by --check.
+TMPCANON=$(mktemp)
+cp "$FRAMEWORK_DIR/templates/instructions.md" "$TMPCANON"
+printf '\nDRIFT-MARKER\n' >> "$FRAMEWORK_DIR/templates/instructions.md"
+$NODE "$CI" --check >/dev/null 2>&1
+RC=$?
+cp "$TMPCANON" "$FRAMEWORK_DIR/templates/instructions.md"   # restore immediately
+rm -f "$TMPCANON"
+assert_exit "drift guard fails (exit 1) when canonical edited but not recompiled" 1 $RC
+# confirm restore worked
+$NODE "$CI" --check >/dev/null 2>&1
+assert_exit "canonical restored, --check green again" 0 $?
+
+# --- R4: both artifacts share an identical body, differ only in footer ---
+CLAUDE_BODY=$(sed -n '/# Qualia Framework/,/state router tells you the next command/p' "$FRAMEWORK_DIR/CLAUDE.md")
+AGENTS_BODY=$(sed -n '/# Qualia Framework/,/state router tells you the next command/p' "$FRAMEWORK_DIR/AGENTS.md")
+if [ "$CLAUDE_BODY" = "$AGENTS_BODY" ]; then
+  echo "  ✓ CLAUDE.md and AGENTS.md bodies are identical (no drift)"; PASS=$((PASS+1));
+else
+  echo "  ✗ CLAUDE.md and AGENTS.md bodies diverge"; FAIL=$((FAIL+1));
+fi
+# host-specific footer survives
+assert_contains "CLAUDE.md keeps Claude footer" "$(cat "$FRAMEWORK_DIR/CLAUDE.md")" "this file stays under 25 lines"
+assert_contains "AGENTS.md keeps cross-vendor footer" "$(cat "$FRAMEWORK_DIR/AGENTS.md")" "cross-vendor compatibility"
+refute_contains "AGENTS.md does NOT carry the Claude-only footer" "$(cat "$FRAMEWORK_DIR/AGENTS.md")" "this file stays under 25 lines"
+# both carry the generated header + role placeholder for install to fill
+assert_contains "CLAUDE.md has generated header" "$(head -1 "$FRAMEWORK_DIR/CLAUDE.md")" "GENERATED from templates/instructions.md"
+assert_contains "AGENTS.md keeps {{ROLE}} for install" "$(cat "$FRAMEWORK_DIR/AGENTS.md")" "{{ROLE}}"
+
+# --- R5: adapter contract is the single source of per-host facts ---
+assert_eq "claude instructionFile" "CLAUDE.md" "$($NODE -e "console.log(require('$HA').adapter('claude').instructionFile)")"
+assert_eq "codex instructionFile" "AGENTS.md" "$($NODE -e "console.log(require('$HA').adapter('codex').instructionFile)")"
+assert_eq "claude configFile" "settings.json" "$($NODE -e "console.log(require('$HA').adapter('claude').configFile)")"
+assert_eq "codex configFile" "config.toml" "$($NODE -e "console.log(require('$HA').adapter('codex').configFile)")"
+assert_eq "codex agentExt" ".toml" "$($NODE -e "console.log(require('$HA').adapter('codex').agentExt)")"
+assert_eq "unknown host throws" "throws" "$($NODE -e "try{require('$HA').adapter('cursor');console.log('no')}catch(e){console.log('throws')}")"
+
+# --- R5: stripHostBlocks keeps only the matching host's block ---
+SRC='before
+<!--QUALIA-HOST claude-->
+CLAUDE_ONLY
+<!--/QUALIA-HOST-->
+<!--QUALIA-HOST codex-->
+CODEX_ONLY
+<!--/QUALIA-HOST-->
+after'
+CLAUDE_OUT=$($NODE -e "console.log(require('$HA').stripHostBlocks(process.argv[1],'claude'))" "$SRC")
+assert_contains "claude strip keeps CLAUDE_ONLY" "$CLAUDE_OUT" "CLAUDE_ONLY"
+refute_contains "claude strip drops CODEX_ONLY" "$CLAUDE_OUT" "CODEX_ONLY"
+CODEX_OUT=$($NODE -e "console.log(require('$HA').stripHostBlocks(process.argv[1],'codex'))" "$SRC")
+assert_contains "codex strip keeps CODEX_ONLY" "$CODEX_OUT" "CODEX_ONLY"
+refute_contains "codex strip drops CLAUDE_ONLY" "$CODEX_OUT" "CLAUDE_ONLY"
+
+# --- R5: compileInstructions applies naming but leaves tokens/role for install ---
+NAMED=$($NODE -e "console.log(require('$HA').compileInstructions('Use Claude Code now. Role: {{ROLE}} at \${QUALIA_BIN}','codex'))")
+assert_contains "codex compile swaps the product name" "$NAMED" "Use Codex now"
+assert_contains "codex compile leaves {{ROLE}} for install" "$NAMED" "{{ROLE}}"
+assert_contains "codex compile leaves \${QUALIA_BIN} token for install" "$NAMED" '${QUALIA_BIN}'
+
+# --- R5: renderText still resolves paths (regression) ---
+RENDERED=$($NODE -e "console.log(require('$HA').renderText('bin at \${QUALIA_BIN}','claude'))")
+assert_contains "renderText resolves QUALIA_BIN" "$RENDERED" "/.claude/bin"
+
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1