qualia-framework 4.4.0 → 5.1.0

package/templates/PRODUCT.md

@@ -0,0 +1,95 @@
+# PRODUCT — {Project Name}
+
+> **Required.** The "who and why" every Qualia agent reads before designing or building anything.
+> `/qualia-new` generates this from 5 questions. Update as the product clarifies.
+
+## Register
+
+**One of:** `brand` · `product`
+
+- **brand** — design IS the product (marketing, landing, campaign, portfolio). Distinctiveness is the bar.
+- **product** — design SERVES the product (app, admin, dashboard, tool). Earned familiarity is the bar.
+
+A project may have BOTH (e.g., marketing site + app). When that's true, list both, and note which surfaces fall under each.
+
+```
+register: product
+secondary: brand (only for /marketing/* routes)
+```
+
+## Users (specific, not personas)
+
+Real humans with real jobs who will use this. Not "small business owners" — Sarah, who runs a 3-person bookkeeping practice in Limassol and pays for QuickBooks because she trusts it. Three users, named, with the workflow in mind.
+
+```
+1. {Name} — {role + scenario}. {What they're trying to do when they open this}.
+2. ...
+3. ...
+```
+
+## Brand voice
+
+How the product sounds in writing. UI strings, error messages, marketing copy. Three adjectives, then one sentence of "voice in motion."
+
+```
+Voice: {three adjectives — e.g., "direct, confident, dry"}
+
+Voice in motion: {one paragraph showing the voice in actual sentences. What an
+error message sounds like. What a confirmation sounds like. What the empty state
+sounds like. Concrete, not adjectives.}
+```
+
+## Anti-references (mandatory, 3-5)
+
+Sites the project should NOT look like. Anti-references pin down what the design is reacting against — more useful than positive references.
+
+```
+- {URL or descriptor} — {what it gets wrong for our use case}
+- {URL or descriptor} — ...
+- {URL or descriptor} — ...
+```
+
+For Brand register, these are usually saturated aesthetic lanes (see `rules/design-brand.md`).
+For Product register, these are usually patterns we don't want to inherit (e.g., "Salesforce Lightning — too dense, too many panels").
+
+## Positive references (optional, ≤3)
+
+Sites that demonstrate qualities we want to inherit. Less important than anti-references.
+
+```
+- {URL or app name} — {specific quality, e.g., "Linear's keyboard fluency", "Stripe's empty state copy", "Vercel's color restraint"}
+```
+
+## Strategic principles
+
+3-5 statements that resolve future arguments. Not feature ideas — design/UX principles that compound.
+
+```
+- {Principle}. {One-line rationale.}
+- {Principle}. {One-line rationale.}
+- {Principle}. {One-line rationale.}
+```
+
+Examples:
+- **Density before delight.** Users live in this app 6+ hours/day. Density wins over flourish.
+- **Power users are the primary persona.** Beginners get onboarding. The app optimizes for power.
+- **Speed of glance, not depth of click.** Information visible without interaction beats information one click away.
+
+## Constraints
+
+```
+Framework:        {Next.js 16 / React 19 / Vite / Astro / etc}
+Component library: {shadcn-ui · custom · radix · arco · ...}
+Performance budget: {LCP < 2.5s, INP < 200ms, CLS < 0.1, etc}
+Accessibility:    WCAG 2.2 AA minimum
+Browsers:         {evergreen / IE11 / mobile-first / ...}
+i18n:             {languages supported, RTL needed?}
+```
+
+## Differentiation (one sentence)
+
+What someone will remember about this product 24 hours after using it for the first time. If you can't write this in one sentence, the product hasn't decided what it is yet.
+
+```
+{One sentence. What's the memory hook?}
+```

package/templates/decisions/ADR-template.md

@@ -0,0 +1,30 @@
+# ADR-{{NNNN}} — {{Decision title in present tense}}
+
+- **Date:** {{YYYY-MM-DD}}
+- **Phase:** {{N}} — {{phase name}}
+- **Status:** Proposed | Accepted | Superseded by ADR-XXXX
+- **Domain terms:** {{any new/affected terms — also update CONTEXT.md}}
+
+## Context
+What is the situation that requires a decision? Why are we deciding this now? What constraints apply (regulatory, performance, team skill, deadlines)?
+
+## Decision
+What we are doing. State it as a single declarative sentence first, then expand.
+
+## Consequences
+- **What becomes easier:** ...
+- **What becomes harder:** ...
+- **What is now load-bearing on this decision:** ...
+
+## Alternatives considered
+Why each alternative was rejected — keep this honest. Future-you will read it.
+
+- **Alt A** — {{rejected because…}}
+- **Alt B** — {{rejected because…}}
+
+## Notes
+Any non-obvious context, links to discussion threads, related issues. Optional.
+
+---
+
+**When to write an ADR (per Matt Pocock's rule):** only when the decision is hard-to-reverse, surprising-without-context, AND involves real trade-offs. If any of those three is missing, just put it in CONTEXT.md or a phase plan instead. ADRs are scarce on purpose.

package/tests/bin.test.sh

@@ -9,6 +9,7 @@ NODE="${NODE:-node}"
 CLI_JS="$FRAMEWORK_DIR/bin/cli.js"
 UI_JS="$FRAMEWORK_DIR/bin/qualia-ui.js"
 INSTALL_JS="$FRAMEWORK_DIR/bin/install.js"
+STATE_JS="$FRAMEWORK_DIR/bin/state.js"
 PKG_VERSION=$($NODE -e 'console.log(require("'"$FRAMEWORK_DIR"'/package.json").version)')
 
 # Track tmp dirs we create so we can clean them up on exit
@@ -476,11 +477,12 @@ else
   fail_case "CLAUDE.md role substitution"
 fi
 
-# 31. All 9 hooks installed (block-env-edit removed in v3.2.0;
-# git-guardrails + stop-session-log added in v4.2.0)
+# 31. All 12 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)
 HOOK_COUNT=$(ls "$TMP/.claude/hooks/"*.js 2>/dev/null | wc -l)
-if [ "$HOOK_COUNT" -eq 9 ]; then
-  pass "9 hooks installed in hooks/"
+if [ "$HOOK_COUNT" -eq 12 ]; then
+  pass "12 hooks installed in hooks/"
 else
   fail_case "hook count" "got $HOOK_COUNT"
 fi
@@ -496,7 +498,7 @@ else
   fail_case "settings.json contents"
 fi
 
-# 33. settings.json contains all 9 hooks wired correctly
+# 33. settings.json contains all 12 hooks wired correctly
 if 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" \
@@ -505,8 +507,11 @@ if grep -q 'branch-guard.js' "$TMP/.claude/settings.json" \
    && grep -q 'session-start.js' "$TMP/.claude/settings.json" \
    && grep -q 'pre-compact.js' "$TMP/.claude/settings.json" \
    && grep -q 'git-guardrails.js' "$TMP/.claude/settings.json" \
-   && grep -q 'stop-session-log.js' "$TMP/.claude/settings.json"; then
-  pass "settings.json has all 9 hooks wired"
+   && grep -q 'stop-session-log.js' "$TMP/.claude/settings.json" \
+   && grep -q 'vercel-account-guard.js' "$TMP/.claude/settings.json" \
+   && grep -q 'env-empty-guard.js' "$TMP/.claude/settings.json" \
+   && grep -q 'supabase-destructive-guard.js' "$TMP/.claude/settings.json"; then
+  pass "settings.json has all 12 hooks wired"
 else
   fail_case "settings.json missing hooks"
 fi
@@ -992,6 +997,445 @@ else
   fail_case "help missing flush" "exit=$EXIT"
 fi
 
+echo ""
+echo "--- v5.0.0 (alignment substrate + new skills) ---"
+
+# 79. CONTEXT.md template installs to qualia-templates/
+TMP=$(mktmp)
+echo "QS-FAWZI-01" | HOME="$TMP" $NODE "$INSTALL_JS" >/dev/null 2>&1
+if [ -f "$TMP/.claude/qualia-templates/CONTEXT.md" ]; then
+  pass "CONTEXT.md template installs to qualia-templates/"
+else
+  fail_case "CONTEXT.md template missing"
+fi
+
+# 80. decisions/ADR-template.md installs (validates nested template dir copy)
+if [ -f "$TMP/.claude/qualia-templates/decisions/ADR-template.md" ]; then
+  pass "decisions/ADR-template.md installs (nested template dir)"
+else
+  fail_case "decisions/ADR-template.md missing"
+fi
+
+# 81-84. The 4 new v5 skills install with their SKILL.md
+for SKILL in qualia-zoom qualia-road qualia-issues qualia-triage; do
+  if [ -f "$TMP/.claude/skills/$SKILL/SKILL.md" ]; then
+    pass "$SKILL skill installs"
+  else
+    fail_case "$SKILL skill missing after install"
+  fi
+done
+
+# 85. qualia-discuss SKILL.md mentions "grilling" (validates v5 fold of qualia-grill into discuss)
+if grep -qi "grilling" "$TMP/.claude/skills/qualia-discuss/SKILL.md"; then
+  pass "qualia-discuss documents grilling pattern (folded from qualia-grill)"
+else
+  fail_case "qualia-discuss missing grilling reference"
+fi
+
+# 86. qualia-discuss SKILL.md references CONTEXT.md (validates v5 substrate wiring)
+if grep -q "CONTEXT.md" "$TMP/.claude/skills/qualia-discuss/SKILL.md"; then
+  pass "qualia-discuss references CONTEXT.md"
+else
+  fail_case "qualia-discuss missing CONTEXT.md reference"
+fi
+
+# 87. qualia-road has disable-model-invocation: true (pure reference skill, user-only)
+if grep -q "disable-model-invocation: true" "$TMP/.claude/skills/qualia-road/SKILL.md"; then
+  pass "qualia-road has disable-model-invocation: true"
+else
+  fail_case "qualia-road missing disable-model-invocation"
+fi
+
+# 88. qualia-road has NO dead skill refs (qualia-grill, qualia-deepen, qualia-tdd, qualia-onboard
+# were folded; if they appear as bare /qualia-* commands the road documentation is broken)
+if grep -qE '/qualia-(grill|deepen|tdd|onboard)\b' "$TMP/.claude/skills/qualia-road/SKILL.md"; then
+  fail_case "qualia-road still references folded skills as commands"
+else
+  pass "qualia-road has no dead-skill references"
+fi
+
+# 89. CONTEXT.md template has NO /qualia-grill reference (was folded into /qualia-discuss)
+if grep -q '/qualia-grill\b' "$TMP/.claude/qualia-templates/CONTEXT.md"; then
+  fail_case "CONTEXT.md template still references /qualia-grill"
+else
+  pass "CONTEXT.md template has no /qualia-grill reference"
+fi
+
+# 90. Builder agent has trust-boundary block (defends against CONTEXT.md prompt injection)
+if grep -q "Trust boundary" "$TMP/.claude/agents/builder.md"; then
+  pass "builder.md has Trust boundary block (prompt-injection defense)"
+else
+  fail_case "builder.md missing Trust boundary block"
+fi
+
+# 91. qualia-issues uses --body-file (not vulnerable heredoc) for gh issue create
+if grep -q -- "--body-file" "$TMP/.claude/skills/qualia-issues/SKILL.md" \
+   && ! grep -q "gh issue create.*--body \"\$(cat <<" "$TMP/.claude/skills/qualia-issues/SKILL.md"; then
+  pass "qualia-issues uses --body-file (no heredoc shell injection)"
+else
+  fail_case "qualia-issues still uses heredoc for gh issue body"
+fi
+
+# 92-94. v5.0 insights-driven hooks parse as valid Node and install
+for HOOK in vercel-account-guard env-empty-guard supabase-destructive-guard; do
+  HOOK_FILE="$TMP/.claude/hooks/${HOOK}.js"
+  if [ -f "$HOOK_FILE" ]; then
+    EXIT=0; $NODE -c "$HOOK_FILE" 2>/dev/null || EXIT=$?
+    if [ "$EXIT" -eq 0 ]; then
+      pass "${HOOK}.js installs and parses as valid Node"
+    else
+      fail_case "${HOOK}.js parse error"
+    fi
+  else
+    fail_case "${HOOK}.js missing after install"
+  fi
+done
+
+# 95. cmdInit guards against suspicious project names (insights friction: throwaway projects)
+TMP_PROJ=$(mktemp -d)
+EXIT=0; OUT=$(cd "$TMP_PROJ" && $NODE "$STATE_JS" init --project "test" --phases '[{"name":"X","goal":"y"}]' 2>&1) || EXIT=$?
+if [ "$EXIT" -ne 0 ] && echo "$OUT" | grep -q "SUSPICIOUS_NAME"; then
+  pass "state.js init blocks suspicious project name 'test' without --force"
+else
+  fail_case "state.js init allowed 'test' as project name"
+fi
+rm -rf "$TMP_PROJ"
+
+# 96. cmdInit allows real client name
+TMP_PROJ=$(mktemp -d)
+EXIT=0; OUT=$(cd "$TMP_PROJ" && $NODE "$STATE_JS" init --project "RealClient" --phases '[{"name":"X","goal":"y"}]' 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$OUT" | grep -q '"action": "init"'; then
+  pass "state.js init allows real project name 'RealClient'"
+else
+  fail_case "state.js init rejected real name" "exit=$EXIT"
+fi
+rm -rf "$TMP_PROJ"
+
+# 97. cmdInit allows suspicious name with --force (escape hatch)
+TMP_PROJ=$(mktemp -d)
+EXIT=0; OUT=$(cd "$TMP_PROJ" && $NODE "$STATE_JS" init --project "test" --phases '[{"name":"X","goal":"y"}]' --force 2>&1) || EXIT=$?
+if [ "$EXIT" -eq 0 ]; then
+  pass "state.js init --force bypasses suspicious-name guard"
+else
+  fail_case "state.js init --force was blocked" "exit=$EXIT"
+fi
+rm -rf "$TMP_PROJ"
+
+# 98. pre-deploy-gate honors QUALIA_SKIP_LINT escape (insights friction: lint blocks ship)
+if grep -q "QUALIA_SKIP_LINT" "$TMP/.claude/hooks/pre-deploy-gate.js"; then
+  pass "pre-deploy-gate.js honors QUALIA_SKIP_LINT escape"
+else
+  fail_case "pre-deploy-gate missing QUALIA_SKIP_LINT escape"
+fi
+
+echo ""
+echo "--- v5.0.0 (visual-polish loop addendum) ---"
+
+# 99. qualia-polish-loop SKILL.md installs
+TMP=$(mktmp)
+echo "QS-FAWZI-01" | HOME="$TMP" $NODE "$INSTALL_JS" >/dev/null 2>&1
+if [ -f "$TMP/.claude/skills/qualia-polish-loop/SKILL.md" ]; then
+  pass "qualia-polish-loop SKILL.md installs"
+else
+  fail_case "qualia-polish-loop SKILL.md missing after install"
+fi
+
+# 100. qualia-polish-loop REFERENCE.md installs
+if [ -f "$TMP/.claude/skills/qualia-polish-loop/REFERENCE.md" ]; then
+  pass "qualia-polish-loop REFERENCE.md installs"
+else
+  fail_case "qualia-polish-loop REFERENCE.md missing after install"
+fi
+
+# 101. qualia-polish-loop SKILL.md references the design rubric
+if grep -q "design-rubric.md" "$TMP/.claude/skills/qualia-polish-loop/SKILL.md"; then
+  pass "qualia-polish-loop references design-rubric.md"
+else
+  fail_case "qualia-polish-loop missing rubric reference"
+fi
+
+# 102. qualia-polish-loop REFERENCE.md has the anchored vision eval prompt
+if grep -q "DEFAULT TO 3" "$TMP/.claude/skills/qualia-polish-loop/REFERENCE.md"; then
+  pass "qualia-polish-loop REFERENCE.md has anchored rubric prompt"
+else
+  fail_case "qualia-polish-loop REFERENCE.md missing anchored rubric"
+fi
+
+# 103. qualia-polish-loop SKILL.md has regression detection (LOOP_REGRESSION_DETECTED)
+if grep -q "LOOP_REGRESSION_DETECTED" "$TMP/.claude/skills/qualia-polish-loop/SKILL.md"; then
+  pass "qualia-polish-loop has regression kill-switch"
+else
+  fail_case "qualia-polish-loop missing regression kill-switch"
+fi
+
+# 104. score.mjs exists in the framework skill scripts
+if [ -f "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/score.mjs" ]; then
+  pass "score.mjs exists in skill scripts"
+else
+  fail_case "score.mjs missing from skill scripts"
+fi
+
+# 105. score.mjs computes pass correctly (all dims >= 3)
+SCORE_OUT=$(echo '{"typography":3,"color":3,"spatial":3,"layout":3,"shadow":3,"motion":3,"microcopy":3,"container":3}' | $NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/score.mjs" 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 0 ] && echo "$SCORE_OUT" | grep -q '"pass": true'; then
+  pass "score.mjs pass on all-3 scores"
+else
+  fail_case "score.mjs pass computation" "exit=$EXIT"
+fi
+
+# 106. score.mjs computes fail correctly (one dim < 3)
+SCORE_OUT=$(echo '{"typography":2,"color":3,"spatial":3,"layout":3,"shadow":3,"motion":3,"microcopy":3,"container":3}' | $NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/score.mjs" 2>&1)
+EXIT=$?
+if [ "$EXIT" -eq 1 ] && echo "$SCORE_OUT" | grep -q '"pass": false'; then
+  pass "score.mjs fail on dim < 3"
+else
+  fail_case "score.mjs fail computation" "exit=$EXIT"
+fi
+
+# 107. qualia-road references qualia-polish-loop
+if grep -q "qualia-polish-loop" "$TMP/.claude/skills/qualia-road/SKILL.md"; then
+  pass "qualia-road references qualia-polish-loop"
+else
+  fail_case "qualia-road missing qualia-polish-loop reference"
+fi
+
+# 108. package.json version is 5.1.x (multi-target install + polish-loop in v5.x line)
+if grep -qE '"5\.1\.' "$FRAMEWORK_DIR/package.json"; then
+  pass "package.json version is 5.1.x"
+else
+  fail_case "package.json version not 5.1.x"
+fi
+
+# 109. loop.mjs installs (orchestrator)
+if [ -f "$TMP/.claude/skills/qualia-polish-loop/scripts/loop.mjs" ]; then
+  pass "qualia-polish-loop scripts/loop.mjs installs"
+else
+  fail_case "scripts/loop.mjs missing — install.js scripts/ subfolder copy broken"
+fi
+
+# 110. playwright-capture.mjs installs (capture helper)
+if [ -f "$TMP/.claude/skills/qualia-polish-loop/scripts/playwright-capture.mjs" ]; then
+  pass "qualia-polish-loop scripts/playwright-capture.mjs installs"
+else
+  fail_case "scripts/playwright-capture.mjs missing"
+fi
+
+# 111. fixtures/ subfolder installs (self-test pages)
+if [ -f "$TMP/.claude/skills/qualia-polish-loop/fixtures/clean.html" ] && \
+   [ -f "$TMP/.claude/skills/qualia-polish-loop/fixtures/broken.html" ]; then
+  pass "qualia-polish-loop fixtures/ installs (clean.html + broken.html)"
+else
+  fail_case "fixtures/ subfolder not copied by install.js"
+fi
+
+# 112. visual-evaluator agent installs
+if [ -f "$TMP/.claude/agents/visual-evaluator.md" ]; then
+  pass "agents/visual-evaluator.md installs"
+else
+  fail_case "visual-evaluator agent missing after install"
+fi
+
+# 113. loop.mjs parses as valid Node ESM
+EXIT=0; $NODE --check "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" 2>/dev/null || EXIT=$?
+if [ "$EXIT" -eq 0 ]; then
+  pass "loop.mjs parses as valid Node ESM"
+else
+  fail_case "loop.mjs parse error"
+fi
+
+# 114. playwright-capture.mjs parses as valid Node ESM
+EXIT=0; $NODE --check "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/playwright-capture.mjs" 2>/dev/null || EXIT=$?
+if [ "$EXIT" -eq 0 ]; then
+  pass "playwright-capture.mjs parses as valid Node ESM"
+else
+  fail_case "playwright-capture.mjs parse error"
+fi
+
+# 115. loop.mjs init creates a valid state file
+TMP_STATE=$(mktmp)/qpl-state.json
+mkdir -p "$(dirname "$TMP_STATE")"
+EXIT=0; $NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" init \
+  --state "$TMP_STATE" --url "http://localhost:3000" --max 4 --budget 50000 >/dev/null 2>&1 || EXIT=$?
+if [ "$EXIT" -eq 0 ] && [ -f "$TMP_STATE" ] && grep -q '"verdict": "pending"' "$TMP_STATE"; then
+  pass "loop.mjs init creates valid state.json"
+else
+  fail_case "loop.mjs init failed (exit=$EXIT, state present? $([ -f "$TMP_STATE" ] && echo yes || echo no))"
+fi
+
+# 116. loop.mjs record kill-switch fires on 3 consecutive recurrences of same fingerprint
+TMP_STATE2=$(mktmp)/qpl-kill.json
+TMP_EVAL=$(mktmp)/qpl-eval.json
+mkdir -p "$(dirname "$TMP_STATE2")" "$(dirname "$TMP_EVAL")"
+$NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" init \
+  --state "$TMP_STATE2" --url "http://localhost:3000" --max 8 >/dev/null 2>&1
+# write 3 identical evals
+KILL_OK=true
+for ITER in 1 2 3; do
+  cat > "$TMP_EVAL" <<EOF
+{
+  "iteration": $ITER,
+  "tokens_used": 100,
+  "viewport_results": [],
+  "aggregate_scores": {"typography":1,"color":3,"spatial":3,"layout":3,"shadow":3,"motion":3,"microcopy":3,"container":3},
+  "top_issues": [{"dim":"typography","severity":"critical","description":"banned font Inter visible","likely_file":"src/styles.css","fix":"replace"}],
+  "pass": false
+}
+EOF
+  EXIT=0; $NODE "$FRAMEWORK_DIR/skills/qualia-polish-loop/scripts/loop.mjs" record \
+    --state "$TMP_STATE2" --eval "$TMP_EVAL" >/dev/null 2>&1 || EXIT=$?
+  if [ "$ITER" -lt 3 ] && [ "$EXIT" -ne 1 ]; then KILL_OK=false; fi
+  if [ "$ITER" -eq 3 ] && [ "$EXIT" -ne 3 ]; then KILL_OK=false; fi
+done
+if [ "$KILL_OK" = true ] && grep -q '"verdict": "killed_regression"' "$TMP_STATE2"; then
+  pass "loop.mjs kill-switch fires after 3 consecutive recurrences"
+else
+  fail_case "loop.mjs kill-switch did not fire correctly"
+fi
+
+# 117. visual-evaluator agent has trust-boundary block (security-critical)
+if grep -q "Trust boundary" "$TMP/.claude/agents/visual-evaluator.md"; then
+  pass "visual-evaluator has trust-boundary block (refuses inlined-file injection)"
+else
+  fail_case "visual-evaluator missing trust-boundary block"
+fi
+
+echo ""
+echo "--- v5.1.0 (multi-target install: Claude / Codex / Both) ---"
+
+# 118. Target=1 (Claude only) installs to ~/.claude/, not ~/.codex/
+TMP=$(mktmp)
+printf 'QS-FAWZI-01\n1\n' | HOME="$TMP" $NODE "$INSTALL_JS" > "$TMP/log.txt" 2>&1
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && [ -f "$TMP/.claude/.qualia-config.json" ] \
+   && [ ! -d "$TMP/.codex" ]; then
+  pass "target=1 → ~/.claude/ populated, ~/.codex/ untouched"
+else
+  fail_case "target=1 Claude-only" "exit=$EXIT codex_exists=$(test -d "$TMP/.codex" && echo yes || echo no)"
+fi
+
+# 119. Target=2 (Codex only) writes ~/.codex/AGENTS.md, skips ~/.claude/
+TMP=$(mktmp)
+printf 'QS-FAWZI-01\n2\n' | HOME="$TMP" $NODE "$INSTALL_JS" > "$TMP/log.txt" 2>&1
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && [ -f "$TMP/.codex/AGENTS.md" ] \
+   && [ ! -d "$TMP/.claude" ] \
+   && grep -q "Role: OWNER" "$TMP/.codex/AGENTS.md" \
+   && ! grep -q "{{ROLE}}" "$TMP/.codex/AGENTS.md"; then
+  pass "target=2 → ~/.codex/AGENTS.md with Role: OWNER, ~/.claude/ skipped"
+else
+  fail_case "target=2 Codex-only" "exit=$EXIT claude_exists=$(test -d "$TMP/.claude" && echo yes || echo no)"
+fi
+
+# 120. Target=3 (Both) populates both directories with the right artifacts
+TMP=$(mktmp)
+printf 'QS-FAWZI-01\n3\n' | HOME="$TMP" $NODE "$INSTALL_JS" > "$TMP/log.txt" 2>&1
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && [ -f "$TMP/.claude/.qualia-config.json" ] \
+   && [ -f "$TMP/.codex/AGENTS.md" ] \
+   && grep -q "Role: OWNER" "$TMP/.codex/AGENTS.md"; then
+  pass "target=3 → both ~/.claude/ and ~/.codex/AGENTS.md populated"
+else
+  fail_case "target=3 Both" "exit=$EXIT"
+fi
+
+# 121. Backward compat: legacy single-line piped install (no target line)
+# defaults to Claude only. Same exact invocation as pre-v5.1.
+TMP=$(mktmp)
+echo "QS-FAWZI-01" | HOME="$TMP" $NODE "$INSTALL_JS" > "$TMP/log.txt" 2>&1
+EXIT=$?
+if [ "$EXIT" -eq 0 ] \
+   && [ -f "$TMP/.claude/.qualia-config.json" ] \
+   && [ ! -d "$TMP/.codex" ]; then
+  pass "legacy single-line piped install → defaults to Claude only"
+else
+  fail_case "backward compat" "exit=$EXIT"
+fi
+
+# 122. Codex AGENTS.md is backed up before overwrite (matches v5.0 CLAUDE.md
+# / settings.json discipline — never silently destroy user-edited files).
+TMP=$(mktmp)
+mkdir -p "$TMP/.codex"
+echo "OLD USER CONTENT" > "$TMP/.codex/AGENTS.md"
+printf 'QS-FAWZI-01\n2\n' | HOME="$TMP" $NODE "$INSTALL_JS" > "$TMP/log.txt" 2>&1
+EXIT=$?
+BAK_COUNT=$(ls "$TMP/.codex/"AGENTS.md.bak.* 2>/dev/null | wc -l)
+if [ "$EXIT" -eq 0 ] \
+   && [ "$BAK_COUNT" -ge 1 ] \
+   && grep -q "OLD USER CONTENT" "$TMP/.codex/"AGENTS.md.bak.* \
+   && ! grep -q "OLD USER CONTENT" "$TMP/.codex/AGENTS.md"; then
+  pass "Codex AGENTS.md backup-before-overwrite preserves prior content"
+else
+  fail_case "Codex backup discipline" "exit=$EXIT bak_count=$BAK_COUNT"
+fi
+
+# 123. Codex install with same content does NOT create a redundant .bak
+# (the v5.0 CLAUDE.md backup discipline only backs up if content differs).
+TMP=$(mktmp)
+printf 'QS-FAWZI-01\n2\n' | HOME="$TMP" $NODE "$INSTALL_JS" > "$TMP/log.txt" 2>&1
+# Re-run with same input — content should be identical, no new backup.
+printf 'QS-FAWZI-01\n2\n' | HOME="$TMP" $NODE "$INSTALL_JS" > "$TMP/log2.txt" 2>&1
+BAK_COUNT=$(ls "$TMP/.codex/"AGENTS.md.bak.* 2>/dev/null | wc -l)
+if [ "$BAK_COUNT" -eq 0 ]; then
+  pass "Codex re-install with identical content → no redundant .bak"
+else
+  fail_case "Codex backup over-zealous" "bak_count=$BAK_COUNT"
+fi
+
+# 124. Non-TTY install log is free of cursor-control / line-clear escape
+# sequences (\r, \x1b[?25l/h hide-cursor, \x1b[2K clear-line). Spinner +
+# overwrite primitives must degrade cleanly when output is piped.
+TMP=$(mktmp)
+printf 'QS-FAWZI-01\n3\n' | HOME="$TMP" $NODE "$INSTALL_JS" > "$TMP/log.txt" 2>&1
+# Look for any of: bare CR, hide-cursor (?25), clear-line (\x1b[2K).
+if [ -s "$TMP/log.txt" ] \
+   && ! grep -q $'\r' "$TMP/log.txt" \
+   && ! grep -q '?25' "$TMP/log.txt" \
+   && ! grep -q '\[2K' "$TMP/log.txt"; then
+  pass "non-TTY install log degrades cleanly (no cursor-control escapes)"
+else
+  fail_case "non-TTY log has orphan escape sequences"
+fi
+
+# 125. Final summary card includes the new "Targets" + "Time" rows
+TMP=$(mktmp)
+printf 'QS-FAWZI-01\n3\n' | HOME="$TMP" $NODE "$INSTALL_JS" > "$TMP/log.txt" 2>&1
+CLEAN=$(strip_ansi < "$TMP/log.txt")
+if echo "$CLEAN" | grep -q "Targets" \
+   && echo "$CLEAN" | grep -q "Claude Code · Codex" \
+   && echo "$CLEAN" | grep -qE "Time +[0-9]+(\.[0-9]+s|ms|s)"; then
+  pass "summary card shows Targets + Time rows"
+else
+  fail_case "summary card missing v5.1 rows"
+fi
+
+# 126. qualia-ui.js exports the v5.1 live-progress primitives
+EXPORTED=$($NODE -e 'const u=require("'"$UI_JS"'"); console.log(["step","spinner","progress","box","kv","divider","section","sectionClose"].every(k=>typeof u[k]==="function") ? "ok" : "missing")')
+if [ "$EXPORTED" = "ok" ]; then
+  pass "qualia-ui.js exports step/spinner/progress/box/kv/divider/section/sectionClose"
+else
+  fail_case "qualia-ui exports missing" "got=$EXPORTED"
+fi
+
+# 127. qualia-ui.js still works as CLI when invoked directly (require-vs-CLI gate)
+OUT=$($NODE "$UI_JS" ok "test" 2>&1)
+if echo "$OUT" | grep -q "test"; then
+  pass "qualia-ui.js CLI dispatch still works after exports refactor"
+else
+  fail_case "qualia-ui CLI broke"
+fi
+
+# 128. package.json bumped to 5.1.x
+PKG_V=$($NODE -e 'console.log(require("'"$FRAMEWORK_DIR"'/package.json").version)')
+if echo "$PKG_V" | grep -qE "^5\.1\."; then
+  pass "package.json version bumped to 5.1.x ($PKG_V)"
+else
+  fail_case "package.json version not bumped to 5.1.x" "got=$PKG_V"
+fi
+
 echo ""
 echo "=== Results: $PASS passed, $FAIL failed ==="
 [ "$FAIL" -eq 0 ] && exit 0 || exit 1