@metasession.co/devaudit-cli 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "DevAudit CLI — installs, syncs, and operates the Metasession SDLC across consumer projects.",
   "type": "module",
   "bin": {
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.8.2",
-    "@metasession.co/devaudit-plugin-sdk": "file:../plugin-sdk",
+    "@metasession.co/devaudit-plugin-sdk": "^0.3.0",
     "ajv": "^8.20.0",
     "commander": "^12.1.0",
     "consola": "^3.2.3",

package/sdlc/files/_common/scripts/close-out-release.sh

@@ -131,6 +131,12 @@ if [ -f "$RTM" ] && grep -qE "^\| ${REQ_ID} " "$RTM"; then
   # (`|---|---|…`) are left intact and don't affect `statuscol`.
   awk -v req="$REQ_ID" '
     BEGIN { FS="|"; OFS="|"; statuscol=0 }
+    # Protect escaped pipes (\|) from being treated as column delimiters.
+    # Replacing \| with \001 in $0 forces awk to re-split on only unescaped
+    # pipes, so literal pipes inside cell content (e.g. regex patterns like
+    # stop\|unsubscribe, enum values open\|in_progress\|closed) do not create
+    # phantom extra columns. Placeholders are restored to \| before output.
+    /\\\|/ { gsub(/\\\|/, "\001", $0) }
     # Header detection: scan every row; require both a "Status" header cell
     # AND an ID-like header cell in the same row before locking statuscol to
     # this row''s column index.
@@ -149,9 +155,10 @@ if [ -f "$RTM" ] && grep -qE "^\| ${REQ_ID} " "$RTM"; then
       if (match(cell, /\(/)) note=substr(cell, RSTART)   # preserve any " (requirement note)"
       gsub(/^[[:space:]]+|[[:space:]]+$/, "", note)
       $statuscol = (note != "" ? " RELEASED " note " " : " RELEASED ")
+      gsub(/\001/, "\\|", $0)
       print; next
     }
-    { print }
+    { gsub(/\001/, "\\|", $0); print }
   ' "$RTM" > "$TMP" && mv "$TMP" "$RTM"
   git add "$RTM" 2>/dev/null || true
   echo "RTM row ${REQ_ID} -> RELEASED."

package/sdlc/files/_common/scripts/close-out-release.test.sh

@@ -136,6 +136,65 @@ EOF
   rm -rf "$(dirname "$dir")"
 }
 
+# ── Case 3: RTM row with escaped pipes (\|) in Status column ─────────────────
+# The Status cell contains literal pipe characters escaped as \| (markdown
+# table convention). Without the fix, awk's FS="|" splits on these escaped
+# pipes too, creating phantom extra columns and mangling the row on close-out.
+{
+  dir="$(mktemp -d)/cli-close-out-fixture-3"
+  mkdir -p "$dir/compliance/pending-releases" "$dir/compliance/approved-releases"
+  cd "$dir"
+  git init -q --initial-branch=main >/dev/null
+  git config user.email "test@example.com"
+  git config user.name "test"
+  cat > compliance/RTM.md <<'EOF'
+# Requirements Traceability Matrix
+
+| REQ-ID  | Issue | Risk        | Evidence                     | Status                                                                | Approver   | Date       |
+| ------- | ----- | ----------- | ---------------------------- | --------------------------------------------------------------------- | ---------- | ---------- |
+| REQ-056 | #117  | MEDIUM-HIGH | compliance/evidence/REQ-056/ | IN PROGRESS (regex: /^\s*(stop\|unsubscribe\|opt[-\s]?out)\s*$/i)    | ostendo-io | 2026-06-01 |
+| REQ-064 | #121  | MEDIUM      | compliance/evidence/REQ-064/ | IN PROGRESS (enum: open\|in_progress\|awaiting_customer\|resolved\|closed) | dev | 2026-06-02 |
+| REQ-075 | #135  | LOW         | compliance/evidence/REQ-075/ | TESTED - PENDING SIGN-OFF (union: 'food'\|'drinks')                  | dev        | 2026-06-03 |
+EOF
+  cat > compliance/pending-releases/RELEASE-TICKET-REQ-056.md <<'EOF'
+# Release Ticket: REQ-056
+
+**Status:** TESTED - PENDING SIGN-OFF
+**DevAudit Release:** REQ-056
+EOF
+  git add -A
+  git commit -q -m "fixture: escaped pipes in status"
+  unset DEVAUDIT_API_KEY DEVAUDIT_BASE_URL || true
+  bash "$HELPER" REQ-056 >/dev/null 2>&1 || true
+  # Assert: REQ-056 col-1 stays REQ-056, col-5 flips to RELEASED with note preserved
+  # Use sed to neutralize \| before awk field splitting (same technique as the
+  # production fix in derive-release-version.sh).
+  row=$(grep -m1 -E "^\| REQ-056 " compliance/RTM.md || true)
+  col1=$(echo "$row" | sed 's/\\|/  /g' | awk -F '|' '{gsub(/^[[:space:]]+|[[:space:]]+$/,"",$2); print $2}')
+  col5=$(echo "$row" | sed 's/\\|/  /g' | awk -F '|' '{gsub(/^[[:space:]]+|[[:space:]]+$/,"",$6); print $6}')
+  assert_eq "escaped-pipe: REQ-056 col-1 unchanged" "REQ-056" "$col1"
+  # col5 starts with RELEASED (the parenthetical note is preserved by close-out)
+  case "$col5" in RELEASED*) assert_eq "escaped-pipe: REQ-056 col-5 flipped" "RELEASED" "RELEASED" ;; *) assert_eq "escaped-pipe: REQ-056 col-5 flipped" "RELEASED" "$col5" ;; esac
+  # Assert: the parenthetical note with escaped pipes is preserved
+  echo "$row" | grep -qF 'stop\|unsubscribe\|opt' \
+    && assert_eq "escaped-pipe: note preserved" "yes" "yes" \
+    || assert_eq "escaped-pipe: note preserved" "yes" "no"
+  # Assert: REQ-064 row untouched (still has escaped pipes in status)
+  row64=$(grep -m1 -E "^\| REQ-064 " compliance/RTM.md || true)
+  echo "$row64" | grep -qF 'open\|in_progress' \
+    && assert_eq "escaped-pipe: REQ-064 untouched" "yes" "yes" \
+    || assert_eq "escaped-pipe: REQ-064 untouched" "yes" "no"
+  # Assert: REQ-075 row untouched (text has 'food'\|'drinks' with quotes)
+  row75=$(grep -m1 -E "^\| REQ-075 " compliance/RTM.md || true)
+  echo "$row75" | grep -qF "food" && echo "$row75" | grep -qF "drinks" \
+    && assert_eq "escaped-pipe: REQ-075 untouched" "yes" "yes" \
+    || assert_eq "escaped-pipe: REQ-075 untouched" "yes" "no"
+  # Assert: row still has exactly 7 columns (9 fields with leading/trailing empty)
+  nfields=$(echo "$row" | sed 's/\\|/  /g' | awk -F '|' '{print NF}')
+  assert_eq "escaped-pipe: REQ-056 still 7 columns" "9" "$nfields"
+  rm -rf "$(dirname "$dir")"
+}
+
 echo
 echo "Result: $PASS passed, $FAIL failed"
 [ "$FAIL" = "0" ]

package/sdlc/files/_common/scripts/derive-release-version.sh

@@ -114,7 +114,8 @@ if [ -f "$RTM_PATH" ]; then
   # Variable padding between REQ-ID and Status (Issue/Risk/Evidence
   # columns) is fine — only the leading REQ-XXX and the status-cell
   # marker matter.
-  IN_PROGRESS_REQS=$(grep -E '\|[[:space:]]+IN PROGRESS' "$RTM_PATH" 2>/dev/null \
+  IN_PROGRESS_REQS=$(sed 's/\\|/  /g' "$RTM_PATH" 2>/dev/null \
+    | grep -E '\|[[:space:]]+IN PROGRESS' \
     | grep -oE '^\|[[:space:]]*REQ-[0-9]+' \
     | grep -oE 'REQ-[0-9]+' | sort -u || true)
   if [ -n "$IN_PROGRESS_REQS" ]; then

package/sdlc/files/_common/scripts/derive-release-version.test.sh

@@ -237,6 +237,35 @@ RTM
 GOT=$(RTM_PATH=docs/custom-RTM.md run_helper)
 assert_eq "RTM_PATH=docs/custom-RTM.md -> REQ-400" "REQ-400" "$GOT"
 
+# Case 19: step-4-bis with escaped pipes (\|) in the Status column.
+# The Status cell contains literal pipe characters escaped as \| (markdown
+# table convention). Without the sed pre-processing, the grep could match
+# a pipe inside the cell content followed by " IN PROGRESS", producing
+# false positives. With the fix, only unescaped pipe delimiters are matched.
+make_fixture "$WORK/c19" "chore: devaudit update to 0.1.29"
+mkdir -p compliance
+cat > compliance/RTM.md <<'RTM'
+# RTM
+| REQ-ID  | Issue | Risk        | Evidence                     | Status                                                                | Approver   | Date       |
+| ------- | ----- | ----------- | ---------------------------- | --------------------------------------------------------------------- | ---------- | ---------- |
+| REQ-056 | #117  | MEDIUM-HIGH | compliance/evidence/REQ-056/ | IN PROGRESS (regex: /^\s*(stop\|unsubscribe\|opt[-\s]?out)\s*$/i)    | ostendo-io | 2026-06-01 |
+| REQ-064 | #121  | MEDIUM      | compliance/evidence/REQ-064/ | RELEASED (enum: open\|in_progress\|awaiting_customer\|resolved\|closed) | dev | 2026-06-02 |
+RTM
+assert_eq "RTM escaped pipes -> REQ-056 (single IN PROGRESS)" "REQ-056" "$(run_helper)"
+
+# Case 20: step-4-bis with escaped pipes — ambiguity guard still works.
+# Two IN PROGRESS rows, both with escaped pipes in status → falls through
+# to bare date rather than guessing.
+make_fixture "$WORK/c20" "chore: devaudit update to 0.1.29"
+mkdir -p compliance
+cat > compliance/RTM.md <<'RTM'
+| REQ-ID  | Status                                                                |
+| ------- | -------------------------------------------------------------------- |
+| REQ-056 | IN PROGRESS (regex: stop\|unsubscribe\|opt[-\s]?out)                 |
+| REQ-064 | IN PROGRESS (enum: open\|in_progress\|awaiting_customer\|resolved)   |
+RTM
+assert_eq "RTM two IN PROGRESS w/ escaped pipes -> bare date $TODAY" "$TODAY" "$(run_helper)"
+
 echo ""
 echo "=== Summary: $PASS pass / $FAIL fail ==="
 

package/sdlc/files/_common/scripts/validate-test-summary.sh

@@ -0,0 +1,146 @@
+#!/bin/bash
+# validate-test-summary.sh — Validates test-execution-summary.md content.
+#
+# Usage:
+#   ./scripts/validate-test-summary.sh [base-branch]
+#
+# Checks that test-execution-summary.md files for in-scope REQs do not
+# contain invalid gate states like "deferred" or "Deferred to CI".
+# E2E gate results must be one of: PASS, FAIL, NOT_NEEDED (with reason),
+# or SKIPPED (with operator-approved rationale). "Deferred to CI" is not
+# a valid SDLC state (devaudit-installer#240).
+#
+# Designed to run as a CI job on PRs to main, alongside
+# validate-compliance-artifacts.sh.
+#
+# Install: cp this file to your project's scripts/ directory && chmod +x scripts/validate-test-summary.sh
+
+set -euo pipefail
+
+BASE_BRANCH="${1:-origin/main}"
+EXIT_CODE=0
+
+echo "=== Test Execution Summary Validation ==="
+echo "Comparing: $BASE_BRANCH...HEAD"
+echo ""
+
+# Extract the requirement(s) THIS PR implements — same logic as
+# validate-compliance-artifacts.sh
+PR_MSGS=$(git log "$BASE_BRANCH"..HEAD --format='%B' || true)
+REQUIREMENTS=$(
+  {
+    printf '%s\n' "$PR_MSGS" | grep -oP '\[\KREQ-\d{3,}(?=\])' || true
+    printf '%s\n' "$PR_MSGS" | grep -iP '^\s*Ref:' | grep -oP 'REQ-\d{3,}' || true
+  } | sort -u
+)
+
+if [ -z "$REQUIREMENTS" ]; then
+  echo "No REQ-XXX references found in PR commits — skipping test summary validation."
+  exit 0
+fi
+
+echo "Requirements found in PR commits: $REQUIREMENTS"
+echo ""
+
+for REQ in $REQUIREMENTS; do
+  echo "--- Checking $REQ ---"
+
+  SUMMARY="compliance/evidence/$REQ/test-execution-summary.md"
+
+  if [ ! -f "$SUMMARY" ]; then
+    echo "  INFO: $SUMMARY not found — skipping (validate-compliance-artifacts.sh checks existence)"
+    echo ""
+    continue
+  fi
+
+  echo "  OK: test-execution-summary.md exists"
+
+  # Check 1: Reject "deferred" (case-insensitive) anywhere in the file
+  if grep -qi 'deferred' "$SUMMARY"; then
+    echo "  ERROR: 'deferred' found in $SUMMARY — 'Deferred to CI' is not a valid gate state (devaudit-installer#238, #240)."
+    echo "         E2E gate results must be: PASS, FAIL, NOT_NEEDED (with reason), or SKIPPED (with operator-approved rationale)."
+    echo "         Offending lines:"
+    grep -in 'deferred' "$SUMMARY" | sed 's/^/           /'
+    EXIT_CODE=1
+  fi
+
+  # Check 2: Reject "browsers not installed" as a gate outcome
+  if grep -qi 'browsers not installed' "$SUMMARY"; then
+    echo "  ERROR: 'browsers not installed' found in $SUMMARY — this is an environment setup issue, not a gate state (devaudit-installer#238, #240)."
+    echo "         Install browsers with 'npx playwright install' and re-run the E2E suite."
+    echo "         Offending lines:"
+    grep -in 'browsers not installed' "$SUMMARY" | sed 's/^/           /'
+    EXIT_CODE=1
+  fi
+
+  # Check 3: Reject "Deferred to CI" explicitly (catches the exact pattern from #238)
+  if grep -qi 'deferred to ci' "$SUMMARY"; then
+    echo "  ERROR: 'Deferred to CI' found in $SUMMARY — CI is a safety net, not a replacement for local E2E execution (devaudit-installer#238, #240)."
+    echo "         Offending lines:"
+    grep -in 'deferred to ci' "$SUMMARY" | sed 's/^/           /'
+    EXIT_CODE=1
+  fi
+
+  # Check 4: Validate E2E gate result in the gate results table
+  # Look for lines matching "| E2E ... | <result> |" pattern
+  E2E_LINES=$(grep -i '| *e2e' "$SUMMARY" 2>/dev/null || true)
+  if [ -n "$E2E_LINES" ]; then
+    while IFS= read -r line; do
+      # Extract the result column (2nd | field after "E2E")
+      RESULT=$(echo "$line" | grep -oP '\|\s*\K[^|]+(?=\s*\|)' | head -2 | tail -1 | xargs || true)
+      if [ -n "$RESULT" ]; then
+        RESULT_LOWER=$(echo "$RESULT" | tr '[:upper:]' '[:lower:]')
+        # Skip empty or separator lines
+        if [ -z "$RESULT_LOWER" ] || echo "$RESULT_LOWER" | grep -q '^[|-]*$'; then
+          continue
+        fi
+        # Check for invalid "deferred" state
+        if echo "$RESULT_LOWER" | grep -qi 'defer'; then
+          echo "  ERROR: E2E gate result '$RESULT' is not valid — 'deferred' is not a gate state (devaudit-installer#240)"
+          EXIT_CODE=1
+        fi
+      fi
+    done <<< "$E2E_LINES"
+  fi
+
+  # Check 5: If E2E result is SKIPPED or NOT_NEEDED, require a rationale on the same line
+  if grep -qi '| *e2e.*| *skipped' "$SUMMARY" 2>/dev/null; then
+    SKIPPED_LINE=$(grep -i '| *e2e.*| *skipped' "$SUMMARY" | head -1)
+    # Rationale can be in the details column (after the result column) or inline with the state
+    if echo "$SKIPPED_LINE" | grep -qi 'skipped.*[—–-].*\|| *skipped.*|.*[a-z]'; then
+      echo "  OK: E2E gate result is SKIPPED with rationale"
+    else
+      echo "  ERROR: E2E gate result is SKIPPED but no rationale provided. Add a reason in the Details column (e.g. 'SKIPPED — API-only change, no UI surface (operator-approved)') (devaudit-installer#240)"
+      EXIT_CODE=1
+    fi
+  fi
+
+  if grep -qi '| *e2e.*| *not_needed' "$SUMMARY" 2>/dev/null; then
+    NN_LINE=$(grep -i '| *e2e.*| *not_needed' "$SUMMARY" | head -1)
+    if echo "$NN_LINE" | grep -qi 'not_needed.*[—–-].*\|| *not_needed.*|.*[a-z]'; then
+      echo "  OK: E2E gate result is NOT_NEEDED with rationale"
+    else
+      echo "  ERROR: E2E gate result is NOT_NEEDED but no rationale provided. Add a reason in the Details column (e.g. 'NOT_NEEDED — schema-only change, no UI surface') (devaudit-installer#240)"
+      EXIT_CODE=1
+    fi
+  fi
+
+  # Check 6: Reject "E2E deferred to CI" in final assessment lines
+  if grep -qi 'e2e deferred\|e2e.*deferred to ci' "$SUMMARY" 2>/dev/null; then
+    echo "  ERROR: 'E2E deferred' language found in final assessment — 'deferred' is not a valid gate state (devaudit-installer#240)"
+    echo "         Offending lines:"
+    grep -in 'e2e deferred\|e2e.*deferred to ci' "$SUMMARY" | sed 's/^/           /'
+    EXIT_CODE=1
+  fi
+
+  echo ""
+done
+
+echo ""
+if [ $EXIT_CODE -eq 0 ]; then
+  echo "=== All test execution summary checks passed ==="
+else
+  echo "=== FAILED: Invalid gate states found in test execution summary ==="
+fi
+
+exit $EXIT_CODE

package/sdlc/files/_common/scripts/validate-test-summary.test.sh

@@ -0,0 +1,268 @@
+#!/usr/bin/env bash
+# validate-test-summary.test.sh — Tests for validate-test-summary.sh.
+#
+# Builds a throwaway git repo per case, creates compliance evidence with
+# crafted test-execution-summary.md files, runs the validator, and asserts
+# on the exit code. Hermetic: runs inside mktemp'd directories that are
+# torn down at the end.
+#
+# Usage:
+#   ./scripts/validate-test-summary.test.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HELPER="$SCRIPT_DIR/validate-test-summary.sh"
+[ -x "$HELPER" ] || chmod +x "$HELPER"
+
+PASS=0
+FAIL=0
+
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT
+
+# Build a fresh git fixture with a commit referencing REQ-XXX.
+# Sets up compliance/evidence/REQ-XXX/ directory.
+# $1 = dir, $2 = REQ ID, $3 = summary file content (via stdin)
+make_fixture() {
+  local dir="$1" req="$2"
+  rm -rf "$dir"
+  mkdir -p "$dir"
+  cd "$dir"
+  git init -q --initial-branch=main
+  git config user.email "test@example.com"
+  git config user.name "test"
+
+  # Create a base branch and a feature branch with a REQ commit
+  echo "x" > f.txt
+  git add f.txt
+  git commit -q -m "initial"
+
+  git checkout -q -b feature
+  echo "y" > g.txt
+  git add g.txt
+  git commit -q -m "feat: [${req}] test change
+
+Ref: ${req}"
+
+  # Create evidence directory and RTM row
+  mkdir -p "compliance/evidence/${req}"
+  echo "| ${req} | #999 | HIGH | compliance/evidence/${req}/ | TESTED - PENDING SIGN-OFF | TBD | -- |" > compliance/RTM.md
+  git add compliance/RTM.md
+  git commit -q -m "docs: add RTM row for ${req}"
+
+  # Write the test-execution-summary.md from stdin
+  cat > "compliance/evidence/${req}/test-execution-summary.md"
+
+  # Stay on feature branch so the validator sees the diff from main
+}
+
+# Run the validator against the fixture, capture exit code.
+# $1 = fixture dir
+run_validator() {
+  local dir="$1"
+  cd "$dir"
+  local exit_code=0
+  bash "$HELPER" main > /tmp/validate-test-summary-output.txt 2>&1 || exit_code=$?
+  echo "$exit_code"
+}
+
+assert_exit() {
+  local desc="$1" want="$2" got="$3"
+  if [ "$got" = "$want" ]; then
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $desc"
+    echo "    want exit: $want"
+    echo "    got exit:  $got"
+    cat /tmp/validate-test-summary-output.txt | sed 's/^/    /'
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "=== validate-test-summary.sh tests ==="
+
+# --- Case 1: Clean summary with PASS — should pass ---
+D1="$WORK/case1"
+make_fixture "$D1" "REQ-001" << 'EOF'
+# Test Execution Summary — REQ-001
+
+## Test design
+
+**Layers planned:** unit, e2e
+**Layers covered:** unit ✓, e2e ✓
+
+## Gate Results
+
+| Gate             | Result   | Details              |
+| ---------------- | -------- | -------------------- |
+| TypeScript       | PASS     | 0 errors             |
+| E2E Tests        | PASS     | All specs green      |
+| Unit Tests       | PASS     | 42 passed            |
+
+**Final assessment:** All gates passed.
+EOF
+EXIT1=$(run_validator "$D1")
+assert_exit "clean summary with PASS — should pass" 0 "$EXIT1"
+
+# --- Case 2: Summary with 'deferred' — should fail ---
+D2="$WORK/case2"
+make_fixture "$D2" "REQ-002" << 'EOF'
+# Test Execution Summary — REQ-002
+
+## Test design
+
+**Layers covered:** unit ✓, e2e deferred
+
+## Gate Results
+
+| Gate             | Result   | Details                                  |
+| ---------------- | -------- | ---------------------------------------- |
+| E2E Tests        | DEFERRED | Playwright browsers not installed locally |
+
+**Final assessment:** All local gates passed. E2E deferred to CI.
+EOF
+EXIT2=$(run_validator "$D2")
+assert_exit "summary with 'deferred' — should fail" 1 "$EXIT2"
+
+# --- Case 3: Summary with 'Deferred to CI' — should fail ---
+D3="$WORK/case3"
+make_fixture "$D3" "REQ-003" << 'EOF'
+# Test Execution Summary — REQ-003
+
+**Final assessment:** All gates passed. E2E Deferred to CI.
+EOF
+EXIT3=$(run_validator "$D3")
+assert_exit "summary with 'Deferred to CI' — should fail" 1 "$EXIT3"
+
+# --- Case 4: Summary with 'browsers not installed' — should fail ---
+D4="$WORK/case4"
+make_fixture "$D4" "REQ-004" << 'EOF'
+# Test Execution Summary — REQ-004
+
+## Gate Results
+
+| Gate             | Result   | Details                                  |
+| ---------------- | -------- | ---------------------------------------- |
+| E2E Tests        | SKIPPED  | Playwright browsers not installed locally |
+
+**Final assessment:** E2E skipped — browsers not installed.
+EOF
+EXIT4=$(run_validator "$D4")
+assert_exit "summary with 'browsers not installed' — should fail" 1 "$EXIT4"
+
+# --- Case 5: Summary with NOT_NEEDED and rationale — should pass ---
+D5="$WORK/case5"
+make_fixture "$D5" "REQ-005" << 'EOF'
+# Test Execution Summary — REQ-005
+
+## Gate Results
+
+| Gate             | Result       | Details                                    |
+| ---------------- | ------------ | ------------------------------------------ |
+| E2E Tests        | NOT_NEEDED   | Schema-only change, no UI surface           |
+
+**Final assessment:** All gates passed. E2E not needed for this REQ.
+EOF
+EXIT5=$(run_validator "$D5")
+assert_exit "summary with NOT_NEEDED and rationale — should pass" 0 "$EXIT5"
+
+# --- Case 6: Summary with SKIPPED and rationale — should pass ---
+D6="$WORK/case6"
+make_fixture "$D6" "REQ-006" << 'EOF'
+# Test Execution Summary — REQ-006
+
+## Gate Results
+
+| Gate             | Result       | Details                                    |
+| ---------------- | ------------ | ------------------------------------------ |
+| E2E Tests        | SKIPPED      | API-only change, no UI surface (operator-approved) |
+
+**Final assessment:** All gates passed. E2E skipped — API-only change.
+EOF
+EXIT6=$(run_validator "$D6")
+assert_exit "summary with SKIPPED and rationale — should pass" 0 "$EXIT6"
+
+# --- Case 7: Summary with SKIPPED but no rationale — should fail ---
+D7="$WORK/case7"
+make_fixture "$D7" "REQ-007" << 'EOF'
+# Test Execution Summary — REQ-007
+
+## Gate Results
+
+| Gate             | Result       | Details    |
+| ---------------- | ------------ | ---------- |
+| E2E Tests        | SKIPPED      |            |
+
+**Final assessment:** All gates passed.
+EOF
+EXIT7=$(run_validator "$D7")
+assert_exit "summary with SKIPPED but no rationale — should fail" 1 "$EXIT7"
+
+# --- Case 8: No REQ references — should pass (skip) ---
+D8="$WORK/case8"
+rm -rf "$D8"
+mkdir -p "$D8"
+cd "$D8"
+git init -q --initial-branch=main
+git config user.email "test@example.com"
+git config user.name "test"
+echo "x" > f.txt
+git add f.txt
+git commit -q -m "initial"
+git checkout -q -b feature
+echo "y" > g.txt
+git add g.txt
+git commit -q -m "docs: update README"
+EXIT8=$(run_validator "$D8")
+assert_exit "no REQ references — should pass (skip)" 0 "$EXIT8"
+
+# --- Case 9: No test-execution-summary.md — should pass (skip) ---
+D9="$WORK/case9"
+make_fixture "$D9" "REQ-009" << 'EOF'
+# placeholder
+EOF
+rm "$D9/compliance/evidence/REQ-009/test-execution-summary.md"
+EXIT9=$(run_validator "$D9")
+assert_exit "no test-execution-summary.md — should pass (skip)" 0 "$EXIT9"
+
+# --- Case 10: Summary with 'e2e deferred' in final assessment — should fail ---
+D10="$WORK/case10"
+make_fixture "$D10" "REQ-010" << 'EOF'
+# Test Execution Summary — REQ-010
+
+## Gate Results
+
+| Gate             | Result   | Details         |
+| ---------------- | -------- | --------------- |
+| E2E Tests        | PASS     | All specs green |
+
+**Final assessment:** All gates passed. E2E deferred to CI for critical tier.
+EOF
+EXIT10=$(run_validator "$D10")
+assert_exit "summary with 'e2e deferred' in final assessment — should fail" 1 "$EXIT10"
+
+# --- Case 11: NOT_NEEDED without rationale — should fail ---
+D11="$WORK/case11"
+make_fixture "$D11" "REQ-011" << 'EOF'
+# Test Execution Summary — REQ-011
+
+## Gate Results
+
+| Gate             | Result       | Details    |
+| ---------------- | ------------ | ---------- |
+| E2E Tests        | NOT_NEEDED   |            |
+
+**Final assessment:** All gates passed.
+EOF
+EXIT11=$(run_validator "$D11")
+assert_exit "summary with NOT_NEEDED but no rationale — should fail" 1 "$EXIT11"
+
+echo ""
+echo "=== Summary: $PASS pass / $FAIL fail ==="
+
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi
+exit 0

package/sdlc/files/_common/skills/e2e-test-engineer/SKILL.md

@@ -241,8 +241,34 @@ Halt and report the gap to the user:
 
 Do **not** proceed to Phase 6 until all gaps are resolved. The user may choose to skip an AC (e.g. API-only, transport-only) — that's valid, but it must be an explicit decision recorded in the test-execution-summary, not an omission.
 
+**Write the evidence-wiring sentinel (devaudit-installer#226).** After all Phase 5½ checks pass (all `@requirement`, `evidenceShot()`, and `tagTest()` calls verified), write a `.e2e-evidence-wired` sentinel file in the repo root so the pre-push hook and `sdlc-implementer` Phase 2 step 5b can verify evidence wiring was validated:
+
+```bash
+echo "WIRED $(date -u +%Y-%m-%dT%H:%M:%SZ) REQ-XXX" > .e2e-evidence-wired
+```
+
+If the user explicitly skipped an AC (e.g. API-only), note it in the sentinel:
+
+```bash
+echo "WIRED $(date -u +%Y-%m-%dT%H:%M:%SZ) REQ-XXX (AC3 skipped — API-only)" > .e2e-evidence-wired
+```
+
+The file is gitignored and never committed — it's a local-only signal that evidence wiring was validated in this working directory.
+
 ### Phase 6 — Execute and report
 
+**Pre-flight: browser availability (devaudit-installer#238).** Before running the suite, verify Playwright browsers are installed:
+
+```bash
+npx playwright install --dry-run 2>&1 | grep -q "is already installed" || npx playwright install
+```
+
+If the install fails (e.g. missing system dependencies on Linux), run `npx playwright install --with-deps` (requires sudo on some systems — ask the operator). Do not defer E2E execution to CI because browsers are not installed. Installing browsers takes ~30 seconds; deferring breaks the evidence trail.
+
+**Do not defer E2E to CI (devaudit-installer#238).** If browsers are not installed, install them. If the dev server will not start, debug it. If the database is not running, start it. CI is a safety net, not a replacement for local E2E execution. The `.e2e-gate-passed` sentinel must be written by a local run — skipping it by deferring to CI breaks the evidence-completeness chain and causes the evidence-completeness gate (#237) to fire with false negatives.
+
+**Gate state vocabulary (devaudit-installer#240).** In `test-execution-summary.md`, E2E gate results must be one of: `PASS`, `FAIL`, `NOT_NEEDED` (with reason), or `SKIPPED` (with operator-approved rationale). The word "deferred" must never appear in `test-execution-summary.md` — not as a gate state, not in prose, not in final assessment. The CI validator (`validate-test-summary.sh`) rejects any file containing "deferred" anywhere. If E2E was not run locally, record it as `SKIPPED` with the reason and flag it as a gate failure for the reviewer. Do not write "E2E deferred to CI" or "Playwright browsers not installed locally" — these are environment issues, not gate states.
+
 Run the suite. Strategy:
 
 1. **Iterate focused.** During fix-and-verify, run only the failing specs (`--grep`, spec-path args, or a CI input that scopes to a subset). Cycle time is what makes the loop tractable — full regression for every iteration burns CI budget and operator patience. Expect to loop: fix → focused run → fix → focused run, many times.
@@ -404,8 +430,8 @@ Wrap up with a summary the user can drop into the PR or ticket:
 **Then feed the test-design record (devaudit#50).** The Stage 3 `test-execution-summary.md` (generated per `3-compile-evidence.md` Step 1a) carries a `## Test design` section at the top. Before Stage 3 finalises the file, populate that section with the design-time decisions this skill made, so the SDLC has a recorded trace that scope was *decided*, not implicit:
 
 - **Layers planned** — which of `unit | integration | e2e | visual | manual` applied to this REQ
-- **Layers covered** — same list with ✓ or `deferred`
-- **Deferrals** — explicit one-line rationale per deferred layer (`e2e N/A — schema-only, no UI yet` rather than silent absence)
+- **Layers covered** — same list with ✓ or `NOT_NEEDED` (with reason)
+- **Exemptions** — explicit one-line rationale per exempt layer (`e2e NOT_NEEDED — schema-only, no UI yet` rather than silent absence). Do not use "deferred" as a gate state — it is not a valid SDLC state (devaudit-installer#240). The CI validator (`validate-test-summary.sh`) will reject any summary containing "deferred".
 - **Skill invocation** — _"`e2e-test-engineer` invoked on turn N during Phase 2"_, with a turn pointer the reviewer can verify against the chat transcript
 
 If you authored or modified `e2e/**/*.spec.ts` directly without invoking this skill, that's a delegation gap — the `sdlc-implementer` Phase 2 audit (devaudit#132) will catch it before Phase 3. The honest record is: the skill ran (or didn't), the layers were chosen for stated reasons, and the test-execution-summary attribution points back at the chat turn where the decision happened.