@metasession.co/devaudit-cli 0.2.0 → 0.3.1

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.

package/sdlc/files/_common/skills/sdlc-implementer/SKILL.md

@@ -265,7 +265,7 @@ Runs **first**, before any `REQ-XXX` is assigned. It decides which of the six ch
 3. **Announce a "Workflow Decision" block** (template below): change-type, commit-type, whether a `REQ-XXX` is needed, risk class, which stages/gates run, which approvals the **operator** must perform (UAT four-eyes, Production approval), and what is **skipped**.
 4. **Pause policy — pause-when-it-matters.** Pause for explicit confirmation on **tracked / heavier** paths, or when classification is **ambiguous**; **announce-and-auto-proceed** on trivial / housekeeping. The operator can always reclassify ("treat this as housekeeping" / "this is HIGH risk").
 5. **Route — and stay on to completion.** A route is a choice of _which workflow to drive_, never a hand-off that abandons the operator. Whatever the path, the skill keeps guiding step by step until no further action is required (typically: merged).
-   - **tracked** (feature / bug fix / refactor / perf) → continue into Phase 1 below (full Stages 1–5). **Write the skill-invocation sentinel** (devaudit-installer#226): `npx devaudit-sdlc --phase=issue`. This invokes the v0.2.0 CLI engine, which appends a JSON phase record to `.sdlc-implementer-invoked` (a gitignored, local-only file). The pre-push hook checks for this file's existence before allowing `feat`/`fix`/`refactor`/`perf` commits to be pushed. Without this sentinel, the pre-push hook will refuse the push and `validate-commits.sh` in CI will flag missing RTM provenance. Each subsequent phase transition (Phase 1, 2, 3, 4, 5) must also invoke `npx devaudit-sdlc --phase=<N>` to append its phase record to the sentinel.
+   - **tracked** (feature / bug fix / refactor / perf) → continue into Phase 1 below (full Stages 1–5). **Write the skill-invocation sentinel** (devaudit-installer#226): `node SDLC/bin/devaudit-sdlc.js --phase=issue` (or `node SDLC/bin/devaudit-sdlc.js --phase=issue` if the npm package is installed). This invokes the CLI engine, which appends a JSON phase record to `.sdlc-implementer-invoked` (a gitignored, local-only file). The pre-push hook checks for this file's existence before allowing `feat`/`fix`/`refactor`/`perf` commits to be pushed. Without this sentinel, the pre-push hook will refuse the push and `validate-commits.sh` in CI will flag missing RTM provenance. Each subsequent phase transition (Phase 1, 2, 3, 4, 5) must also invoke `node SDLC/bin/devaudit-sdlc.js --phase=<N>` to append its phase record to the sentinel.
    - **housekeeping / trivial** → drive the **Lightweight path** below to completion. No `REQ-XXX`, no RTM row, no evidence pack, no portal release approvals — but the skill still branches, runs the gates, opens the PR, and walks the operator through review → merge.
    - **compliance-doc-only** → drive the same Lightweight path as a docs push (or PR, per the project's flow) referencing the **existing** `REQ-XXX`: no new requirement and no quality-gate ceremony, but driven through to merge.
 6. **Write labels back.** Apply the inferred `type:*` / `risk:*` labels so the issue ends up labelled — `gh label create <label> --force` to ensure the label exists (idempotent; no failure if a label-seeding step never ran), then `gh issue edit <N> --add-label <label>`. Future triage is then a glance.
@@ -409,6 +409,15 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
    - **Requirements deviation** (an AC is wrong, incomplete, or missing) — trigger the [requirements gap flow](#requirements-gap-flow-devaudit-installer212). Do NOT just note it as a plan deviation. The AC table must be updated, `requirements-aligner` must be re-invoked to re-check SRS alignment, and the RTM must be updated.
    
    The classification question: "Did the implementation deviate from the plan's approach (how to build it), or did the plan's requirements deviate from reality (what to build)?" If the former, note and continue. If the latter, trigger the requirements gap flow.
+
+4b. **Reconcile test-plan.md file paths with actual files (devaudit-installer#241).** After writing/updating tests (both unit and E2E), diff the actual test file paths against `compliance/evidence/REQ-XXX/test-plan.md`. The test plan was authored during Stage 1 with predicted file paths — during implementation, tests are often added to existing files instead of creating new ones. This is a natural drift, but it must be reconciled before committing so `validate-compliance-artifacts.sh` doesn't fail at PR time.
+
+   For each file path referenced in `test-plan.md`:
+   - If the file exists on disk → OK, no action needed.
+   - If the file does not exist → check whether a test covering the same AC was added to a different file. If so, update `test-plan.md` to reference the actual file path.
+   - If the file does not exist and no equivalent test was found → **HALT**: "test-plan.md references <file> but no test file exists and no equivalent test covering the same AC was found. Either create the test file, update test-plan.md to point to the actual test file, or remove the entry if the AC is no longer relevant."
+
+   Commit the updated `test-plan.md` alongside the test code. This is a file-path reconciliation — it does not change the AC table (that's the step 5b plan ↔ test-scope AC consistency check, which is separate and checks AC drift, not file-path drift).
 5. **Run gates locally, cheap-first.** The gates are not equivalent-cost — `npm run lint` is seconds, `npx playwright test` is 30–60 minutes. Iterate on the fast gates; spend the e2e cost once.
 
    **Fast gates** (run on every change, ideally pre-commit):
@@ -428,7 +437,9 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
    git diff --name-only "$INTEGRATION_BRANCH"...HEAD -- 'app/**/*.tsx' 'src/**/*.tsx' 'pages/**/*.tsx' 'app/**/*.jsx' 'src/**/*.jsx' 'pages/**/*.jsx'
    ```
 
-   - **If UI-facing files are present:** check for `.e2e-gate-passed` sentinel file (written by `e2e-test-engineer` after a successful run) or `playwright-report/` directory with recent content. If neither exists, **HALT**: "E2E gate was not run. The change touches UI-facing files. Run `npx playwright test` (or invoke `e2e-test-engineer`) before committing. The pre-push hook will also block this push."
+   - **If UI-facing files are present:** check for `.e2e-gate-passed` sentinel file (written by `e2e-test-engineer` after a successful run) or `playwright-report/` directory with recent content. If neither exists, **HALT**: "E2E gate was not run. The change touches UI-facing files. Run `npx playwright test` (or invoke `e2e-test-engineer`) before committing. Do not defer to CI — install Playwright browsers with `npx playwright install` if needed. The pre-push hook will also block this push."
+
+     **Also check for `.e2e-evidence-wired` sentinel (devaudit-installer#226).** If `e2e/**/*.spec.ts` files were authored or modified, verify the `.e2e-evidence-wired` sentinel exists (written by `e2e-test-engineer` Phase 5½ after validating `tagTest()` and `evidenceShot()` calls). If missing, **HALT**: "Evidence wiring validation (Phase 5½) was not run. The change includes E2E spec files but no evidence wiring sentinel. Invoke `e2e-test-engineer` to validate `tagTest()` and `evidenceShot()` calls before committing. The pre-push hook will also block this push."
    - **If no UI-facing files (API-only, config, docs):** skip the check. Note the exemption in the commit body: "E2E gate skipped — no UI-facing files in this change."
    - **If `e2e-test-engineer` was invoked and determined e2e is not needed** (e.g. schema-only change): the skill writes `.e2e-gate-passed` with a `NOT_NEEDED` reason. The sentinel check passes. Note the exemption in the commit body: "E2E gate not needed — e2e-test-engineer assessed no UI surface (turn N)."
 
@@ -491,6 +502,14 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
    - The nil report uploads as `incident_report` evidence via `compliance-evidence.yml`'s `upload_incident_report` function, flipping `ISO29119.3.5.4` to COVERED for clean releases.
    - If incidents WERE closed, skip nil report generation — the populated incident report(s) from `incident-export.yml` serve as the evidence.
 
+5b. **Validate test-execution-summary.md gate states (devaudit-installer#240).** Before uploading evidence, verify that `compliance/evidence/REQ-XXX/test-execution-summary.md` does not contain invalid gate states. Run:
+
+   ```bash
+   bash scripts/validate-test-summary.sh origin/main
+   ```
+
+   If the validator fails, fix the summary before proceeding. 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. "Deferred to CI" and "Playwright browsers not installed locally" are environment issues, not gate states. The CI validator (`validate-test-summary.sh`) will reject any summary containing "deferred" or "browsers not installed" on PRs to main.
+
 6. **Organise artefacts** under `compliance/evidence/REQ-XXX/` with date-prefixed naming:
 
    ```

package/sdlc/files/ci/ci.yml.template

@@ -793,10 +793,35 @@ jobs:
                 # specs exist on disk. If specs are found but weren't run in
                 # this tier, emit a non-blocking warning instead of an error.
                 SPECS_ON_DISK=$(grep -rl --include='*.spec.ts' -e "@requirement ${REQ}" -e "tagTest.*${REQ}" -e "'${REQ}'" e2e/ 2>/dev/null | wc -l)
+
+                # devaudit-installer#237 — also scan unit test files for
+                # @requirement REQ-XXX annotations. A REQ with thorough unit
+                # test coverage but no E2E specs (legitimate for API-only or
+                # backend-only changes) should not be hard-blocked.
+                UNIT_TESTS_ON_DISK=$(grep -rl --include='*.test.ts' --include='*.test.tsx' -e "@requirement ${REQ}" -e "'${REQ}'" e2e/ __tests__/ tests/ src/ 2>/dev/null | wc -l)
+
+                # devaudit-installer#237 — check for test-execution-summary.md
+                # as a secondary signal. This is a human-authored document and
+                # weaker than machine-generated evidence, so it only converts
+                # a hard error to a warning when combined with unit test files
+                # on disk — never alone.
+                HAS_SUMMARY=false
+                if [ -f "compliance/evidence/${REQ}/test-execution-summary.md" ]; then
+                  HAS_SUMMARY=true
+                fi
+
                 if [ "$SPECS_ON_DISK" -gt 0 ]; then
+                  # Scenario B: E2E specs exist on disk but outside the smoke tier
                   echo "::warning::Evidence completeness gate: ${REQ} has zero tagged tests in this smoke run and zero per-AC screenshots, but ${SPECS_ON_DISK} spec file(s) on disk reference it (outside the smoke project). Evidence exists but was not executed in this CI tier. Consider running --project=critical or --grep \"${REQ}\" to capture evidence."
+                elif [ "$UNIT_TESTS_ON_DISK" -gt 0 ] && [ "$HAS_SUMMARY" = "true" ]; then
+                  # Scenario C: unit test files exist with @requirement annotations
+                  # and a test-execution-summary.md documents coverage
+                  echo "::warning::Evidence completeness gate: ${REQ} has zero E2E tagged tests and zero screenshots, but ${UNIT_TESTS_ON_DISK} unit test file(s) on disk reference it and a test-execution-summary.md exists. Unit test evidence found but execution was not verified in this run. If this is an API-only or backend-only change, this is expected."
                 else
-                  echo "::error::Evidence completeness gate: ${REQ} has zero tagged tests AND zero per-AC screenshots. The release cannot proceed to UAT with no traceable evidence. Ensure specs carry @requirement ${REQ} annotations and evidenceShot() calls (skill Phase 5½, issue #170)."
+                  # Scenario A: genuinely no evidence — no E2E specs, no unit tests,
+                  # no test-execution-summary. Hard error preserved (#237 Constraint 3).
+                  echo "::error::Evidence completeness gate: ${REQ} has zero traceable evidence — no tagged E2E tests, no per-AC screenshots, no unit test files with @requirement annotations, and no test-execution-summary.md. The release cannot proceed to UAT with no traceable per-REQ evidence."
+                  echo "::error::If E2E specs exist for this REQ, ensure they carry @requirement ${REQ} JSDoc annotations and tagTest() calls (e2e-test-engineer Phase 5½, issue #170). If unit tests exist, add @requirement ${REQ} annotations to the .test.ts files. If this is a pure config/docs change with no testable surface, document it in test-execution-summary.md."
                   EVIDENCE_GAPS=$((EVIDENCE_GAPS + 1))
                 fi
               else

package/sdlc/files/ci/compliance-validation.yml.template

@@ -30,5 +30,8 @@ jobs:
       - name: Validate compliance artifacts
         run: bash scripts/validate-compliance-artifacts.sh origin/main
 
+      - name: Validate test execution summaries
+        run: bash scripts/validate-test-summary.sh origin/main
+
       - name: Validate commit conventions
         run: bash scripts/validate-commits.sh origin/main

package/sdlc/files/stacks/node/hooks/pre-commit

@@ -1,6 +1,8 @@
 #!/usr/bin/env bash
-# Husky pre-commit hook — runs lint-staged on staged files.
-# Catches linting issues before they enter the commit history.
+# Husky pre-commit hook — SDLC guard + lint-staged on staged files.
+#
+# 1. SDLC guard — blocks manual execution on tracked branches (#231)
+# 2. lint-staged — catches linting issues before they enter the commit history
 #
 # Install: cp this file to .husky/pre-commit && chmod +x .husky/pre-commit
 #
@@ -10,4 +12,10 @@
 #     "*.{ts,tsx,js,jsx,json,md}": ["prettier --write"]
 #   }
 
+# ── 1. SDLC guard (devaudit-installer#231) ──────────────────────────
+if [ -f scripts/sdlc-guard.sh ]; then
+  bash scripts/sdlc-guard.sh
+fi
+
+# ── 2. lint-staged ──────────────────────────────────────────────────
 npx lint-staged

package/sdlc/files/stacks/node/hooks/pre-push

@@ -1,7 +1,8 @@
 #!/bin/sh
-# Husky pre-push hook — fast gates + E2E evidence + skill-invocation sentinel + compliance validator.
+# Husky pre-push hook — SDLC guard + fast gates + E2E evidence + skill-invocation sentinel + compliance validator.
 #
-# Runs four checks before allowing a push:
+# Runs five checks before allowing a push:
+# 0. SDLC guard — branch-name check for manual execution detection (#231)
 # 1. TypeScript check (fast gate)
 # 2. E2E evidence check — if UI-facing files changed, verify Playwright ran
 # 3. Skill-invocation sentinel — if feat/fix/refactor/perf commits present,
@@ -15,6 +16,13 @@
 
 set -eu
 
+# ── 0. SDLC guard (devaudit-installer#231) ──────────────────────────
+# Fast-fail: if on a tracked branch (feat/fix/refactor/perf) and the
+# sentinel is missing, bail before running expensive test suites.
+if [ -f scripts/sdlc-guard.sh ]; then
+  bash scripts/sdlc-guard.sh
+fi
+
 # ── 1. TypeScript check ──────────────────────────────────────────────
 echo "Pre-push: running TypeScript check..."
 npx tsc --noEmit
@@ -30,6 +38,8 @@ echo "Pre-push: TypeScript check passed."
 # Only fires if UI-facing files are in the push. Checks for either
 # playwright-report/ directory or .e2e-gate-passed sentinel (written by
 # e2e-test-engineer after a successful run).
+# Also checks .e2e-evidence-wired sentinel if e2e spec files changed
+# (written by e2e-test-engineer Phase 5½ after validating tagTest/evidenceShot).
 INTEGRATION_BRANCH=$(jq -r '.integration_branch // "develop"' sdlc-config.json 2>/dev/null || echo "develop")
 
 # Read stdin to get the pushed refs (husky pre-push protocol)
@@ -70,6 +80,23 @@ while read -r local_ref local_sha remote_ref remote_sha; do
     fi
     echo "Pre-push: E2E evidence check passed."
   fi
+
+  # Check for E2E spec file changes — require .e2e-evidence-wired sentinel
+  SPEC_FILES=$(git diff --name-only "$RANGE" -- 'e2e/**/*.spec.ts' 2>/dev/null || true)
+
+  if [ -n "$SPEC_FILES" ]; then
+    if [ ! -f .e2e-evidence-wired ]; then
+      echo ""
+      echo "ERROR: Evidence wiring validation (Phase 5½) was not run."
+      echo "       E2E spec files changed in this push:"
+      echo "$SPEC_FILES" | sed 's/^/         /'
+      echo ""
+      echo "       Invoke e2e-test-engineer to validate tagTest() and evidenceShot() calls."
+      echo "       Bypass with --no-verify (last resort, not a habit)."
+      exit 1
+    fi
+    echo "Pre-push: E2E evidence wiring check passed."
+  fi
 done
 
 # ── 3. Skill-invocation sentinel (devaudit-installer#226) ────────────

package/sdlc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devaudit-sdlc",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "DevAudit SDLC CLI Engine — cross-agent terminal-driven SDLC orchestrator.",
   "bin": {
     "devaudit-sdlc": "./src/bin/devaudit-sdlc.js"

package/sdlc/src/blueprints/1-plan-requirement.raw.md

@@ -10,7 +10,7 @@ If you are an AI agent reading this file, you are strictly prohibited from manua
 - **OTHER AGENTS (Cursor, Windsurf, Gemini, etc.):** Halt manual execution and output this exact message to the user: 
   "I am pausing to request authorization for the SDLC workflow on this issue. Please confirm if I should proceed."
   
-  CRITICAL WORKFLOW REQUIRED AFTER AUTHORIZATION: Once the operator grants permission to proceed, you MUST immediately execute 'npx devaudit-sdlc --phase=1' to generate the required commit sentinel file in the root directory BEFORE making any file modifications or code changes. Failure to create this file will result in your local git commits being automatically blocked by our pre-commit hooks.
+  CRITICAL WORKFLOW REQUIRED AFTER AUTHORIZATION: Once the operator grants permission to proceed, you MUST immediately execute 'node SDLC/bin/devaudit-sdlc.js --phase=1' to generate the required commit sentinel file in the root directory BEFORE making any file modifications or code changes. Failure to create this file will result in your local git commits being automatically blocked by our pre-commit hooks.
 
 ---
 

package/sdlc/src/blueprints/2-implement-and-test.raw.md

@@ -10,7 +10,7 @@ If you are an AI agent reading this file, you are strictly prohibited from manua
 - **OTHER AGENTS (Cursor, Windsurf, Gemini, etc.):** Halt manual execution and output this exact message to the user: 
   "I am pausing to request authorization for the SDLC workflow on this issue. Please confirm if I should proceed."
   
-  CRITICAL WORKFLOW REQUIRED AFTER AUTHORIZATION: Once the operator grants permission to proceed, you MUST immediately execute 'npx devaudit-sdlc --phase=2' to generate the required commit sentinel file in the root directory BEFORE making any file modifications or code changes. Failure to create this file will result in your local git commits being automatically blocked by our pre-commit hooks.
+  CRITICAL WORKFLOW REQUIRED AFTER AUTHORIZATION: Once the operator grants permission to proceed, you MUST immediately execute 'node SDLC/bin/devaudit-sdlc.js --phase=2' to generate the required commit sentinel file in the root directory BEFORE making any file modifications or code changes. Failure to create this file will result in your local git commits being automatically blocked by our pre-commit hooks.
 
 ---
 
@@ -174,6 +174,18 @@ If prerequisites are missing, do **not** start the full local suite. Run the tar
 
 **Do NOT proceed** until the scoped E2E/test-plan checks are complete and any local limitations are called out.
 
+### Step 4b: Reconcile Test Plan (devaudit-installer#241)
+
+After writing/updating tests (both unit and E2E), verify that `test-plan.md` file paths still match reality. The test plan was authored during Stage 1 with predicted file paths — during implementation, tests are often added to existing files instead of creating new ones. This natural drift must be reconciled before committing so `validate-compliance-artifacts.sh` doesn't fail at PR time.
+
+For each file path referenced in `test-plan.md`:
+
+- If the file exists on disk → OK, no action needed.
+- If the file does not exist → check whether a test covering the same AC was added to a different file. If so, update `test-plan.md` to reference the actual file path.
+- If the file does not exist and no equivalent test was found → **STOP**: "test-plan.md references `<file>` but no test file exists and no equivalent test covering the same AC was found. Either create the test file, update test-plan.md to point to the actual test file, or remove the entry if the AC is no longer relevant."
+
+Commit the updated `test-plan.md` alongside the test code. This is a file-path reconciliation — it does not change the AC table (the plan ↔ test-scope AC consistency check in the skill handles AC drift separately).
+
 ### Step 5: Stage Selectively
 
 ```bash

package/sdlc/src/blueprints/3-compile-evidence.raw.md

@@ -10,7 +10,7 @@ If you are an AI agent reading this file, you are strictly prohibited from manua
 - **OTHER AGENTS (Cursor, Windsurf, Gemini, etc.):** Halt manual execution and output this exact message to the user: 
   "I am pausing to request authorization for the SDLC workflow on this issue. Please confirm if I should proceed."
   
-  CRITICAL WORKFLOW REQUIRED AFTER AUTHORIZATION: Once the operator grants permission to proceed, you MUST immediately execute 'npx devaudit-sdlc --phase=3' to generate the required commit sentinel file in the root directory BEFORE making any file modifications or code changes. Failure to create this file will result in your local git commits being automatically blocked by our pre-commit hooks.
+  CRITICAL WORKFLOW REQUIRED AFTER AUTHORIZATION: Once the operator grants permission to proceed, you MUST immediately execute 'node SDLC/bin/devaudit-sdlc.js --phase=3' to generate the required commit sentinel file in the root directory BEFORE making any file modifications or code changes. Failure to create this file will result in your local git commits being automatically blocked by our pre-commit hooks.
 
 ---
 

package/sdlc/src/blueprints/4-submit-for-review.raw.md

@@ -10,7 +10,7 @@ If you are an AI agent reading this file, you are strictly prohibited from manua
 - **OTHER AGENTS (Cursor, Windsurf, Gemini, etc.):** Halt manual execution and output this exact message to the user: 
   "I am pausing to request authorization for the SDLC workflow on this issue. Please confirm if I should proceed."
   
-  CRITICAL WORKFLOW REQUIRED AFTER AUTHORIZATION: Once the operator grants permission to proceed, you MUST immediately execute 'npx devaudit-sdlc --phase=4' to generate the required commit sentinel file in the root directory BEFORE making any file modifications or code changes. Failure to create this file will result in your local git commits being automatically blocked by our pre-commit hooks.
+  CRITICAL WORKFLOW REQUIRED AFTER AUTHORIZATION: Once the operator grants permission to proceed, you MUST immediately execute 'node SDLC/bin/devaudit-sdlc.js --phase=4' to generate the required commit sentinel file in the root directory BEFORE making any file modifications or code changes. Failure to create this file will result in your local git commits being automatically blocked by our pre-commit hooks.
 
 ---
 

package/sdlc/src/blueprints/5-deploy-main.raw.md

@@ -10,7 +10,7 @@ If you are an AI agent reading this file, you are strictly prohibited from manua
 - **OTHER AGENTS (Cursor, Windsurf, Gemini, etc.):** Halt manual execution and output this exact message to the user: 
   "I am pausing to request authorization for the SDLC workflow on this issue. Please confirm if I should proceed."
   
-  CRITICAL WORKFLOW REQUIRED AFTER AUTHORIZATION: Once the operator grants permission to proceed, you MUST immediately execute 'npx devaudit-sdlc --phase=5' to generate the required commit sentinel file in the root directory BEFORE making any file modifications or code changes. Failure to create this file will result in your local git commits being automatically blocked by our pre-commit hooks.
+  CRITICAL WORKFLOW REQUIRED AFTER AUTHORIZATION: Once the operator grants permission to proceed, you MUST immediately execute 'node SDLC/bin/devaudit-sdlc.js --phase=5' to generate the required commit sentinel file in the root directory BEFORE making any file modifications or code changes. Failure to create this file will result in your local git commits being automatically blocked by our pre-commit hooks.
 
 ---
 

package/sdlc/src/blueprints/implementing-an-sdlc-issue.raw.md

@@ -8,7 +8,7 @@ If you are an AI agent reading this file, you are strictly prohibited from manua
 - **OTHER AGENTS (Cursor, Windsurf, Gemini, etc.):** Halt manual execution and output this exact message to the user: 
   "I am pausing to request authorization for the SDLC workflow on this issue. Please confirm if I should proceed."
   
-  CRITICAL WORKFLOW REQUIRED AFTER AUTHORIZATION: Once the operator grants permission to proceed, you MUST immediately execute 'npx devaudit-sdlc --phase=issue' to generate the required commit sentinel file in the root directory BEFORE making any file modifications or code changes. Failure to create this file will result in your local git commits being automatically blocked by our pre-commit hooks.
+  CRITICAL WORKFLOW REQUIRED AFTER AUTHORIZATION: Once the operator grants permission to proceed, you MUST immediately execute 'node SDLC/bin/devaudit-sdlc.js --phase=issue' to generate the required commit sentinel file in the root directory BEFORE making any file modifications or code changes. Failure to create this file will result in your local git commits being automatically blocked by our pre-commit hooks.
 
 End-to-end walkthrough for taking a GitHub issue from triage to merged-and-deployed under the Metasession SDLC. Audience: this project's developers and AI coding agents.
 

package/sdlc/.claude/settings.local.json

@@ -1,11 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(git init:*)",
-      "Bash(git add:*)",
-      "Bash(git branch:*)",
-      "Bash(git commit:*)",
-      "Bash(gh repo:*)"
-    ]
-  }
-}