@metasession.co/devaudit-cli 0.3.17 → 0.3.19

package/sdlc/files/_common/scripts/report-test-execution.test.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+# report-test-execution.test.sh - Focused regression tests for the test execution lifecycle helper.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HELPER="$SCRIPT_DIR/report-test-execution.sh"
+[ -x "$HELPER" ] || chmod +x "$HELPER"
+
+PASS=0
+FAIL=0
+
+ok() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
+no() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
+
+make_fixture() {
+  local dir="$1"
+  rm -rf "$dir"
+  mkdir -p "$dir/bin"
+  cat > "$dir/bin/curl" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+LOG_FILE="${EXECUTION_TEST_LOG:?}"
+URL=""
+OUT_FILE=""
+WRITE_OUT=""
+BODY=""
+ARGS=("$@")
+for ((i=0; i<${#ARGS[@]}; i++)); do
+  arg="${ARGS[$i]}"
+  case "$arg" in
+    -o) OUT_FILE="${ARGS[$((i+1))]}" ;;
+    -w) WRITE_OUT="${ARGS[$((i+1))]}" ;;
+    -d) BODY="${ARGS[$((i+1))]}" ;;
+    http://*|https://*) URL="$arg" ;;
+  esac
+done
+printf 'URL:%s\n' "$URL" >> "$LOG_FILE"
+if [ -n "$BODY" ]; then
+  printf 'BODY:%s\n' "$BODY" >> "$LOG_FILE"
+fi
+
+status=500
+payload='{"error":"unhandled"}'
+case "$URL" in
+  *"/api/ci/releases/resolve"*)
+    status="${RESOLVE_STATUS:-200}"
+    payload="${RESOLVE_BODY:-{}}"
+    ;;
+  *"/cycles/start")
+    status="${START_STATUS:-201}"
+    payload="${START_BODY:-{}}"
+    ;;
+  *"/cycles/complete")
+    status="${COMPLETE_STATUS:-200}"
+    payload="${COMPLETE_BODY:-{}}"
+    ;;
+  *"/cycles/reconcile")
+    status="${RECONCILE_STATUS:-200}"
+    payload="${RECONCILE_BODY:-{}}"
+    ;;
+esac
+
+if [ -n "$OUT_FILE" ]; then
+  printf '%s' "$payload" > "$OUT_FILE"
+fi
+if [ -n "$WRITE_OUT" ]; then
+  printf '%s' "$status"
+fi
+EOF
+  chmod +x "$dir/bin/curl"
+}
+
+run_helper() {
+  PATH="$1/bin:$PATH" \
+  EXECUTION_TEST_LOG="$1/curl.log" \
+  DEVAUDIT_BASE_URL="https://devaudit.example.test" \
+  DEVAUDIT_API_KEY="mc_test_dummy" \
+  "$HELPER" "${@:2}"
+}
+
+assert_contains() {
+  local label="$1" needle="$2" file="$3"
+  if grep -Fq -- "$needle" "$file"; then ok "$label"; else no "$label"; fi
+}
+
+echo "=== report-test-execution.sh tests ==="
+
+case_start_success() {
+  echo "case: start resolves exact release and records execution"
+  local dir out exit_code
+  dir=$(mktemp -d)
+  make_fixture "$dir"
+  out="$dir/out.env"
+  RESOLVE_STATUS=200 \
+  RESOLVE_BODY='{"latest":{"id":"release-1","version":"REQ-100"}}' \
+  START_STATUS=201 \
+  START_BODY='{"id":"execution-1"}' \
+  run_helper "$dir" start \
+    --project-slug fixture-app \
+    --release REQ-100 \
+    --sdlc-stage 2 \
+    --environment uat \
+    --suite-kind e2e \
+    --iteration-key rework-1 \
+    --iteration-ordinal 1 \
+    --idempotency-key github:fixture/repo:feature-e2e.e2e:12345:1:2:REQ-100 \
+    --output-file "$out" >"$dir/stdout.log" 2>"$dir/stderr.log" && exit_code=0 || exit_code=$?
+  if [ "$exit_code" -eq 0 ]; then ok "exit code 0"; else no "expected exit 0"; fi
+  assert_contains "outputs supported=true" "execution_supported=true" "$out"
+  assert_contains "outputs execution_record_id" "execution_record_id=execution-1" "$out"
+  assert_contains "called start endpoint" "/cycles/start" "$dir/curl.log"
+  assert_contains "payload has suite kind" '"suiteKind": "e2e"' "$dir/curl.log"
+  assert_contains "payload carries portal transport kind" '"cycleKind": "e2e"' "$dir/curl.log"
+  assert_contains "payload has iteration key" '"iterationKey": "rework-1"' "$dir/curl.log"
+  rm -rf "$dir"
+}
+
+case_complete_reconciles_terminal_conflict() {
+  echo "case: complete falls back to reconcile on terminal-outcome conflict"
+  local dir out exit_code
+  dir=$(mktemp -d)
+  make_fixture "$dir"
+  out="$dir/out.env"
+  RESOLVE_STATUS=200 \
+  RESOLVE_BODY='{"latest":{"id":"release-1","version":"REQ-100"}}' \
+  COMPLETE_STATUS=400 \
+  COMPLETE_BODY='{"error":"Test execution already has a different terminal outcome; use reconcile"}' \
+  RECONCILE_STATUS=200 \
+  RECONCILE_BODY='{"id":"execution-1"}' \
+  run_helper "$dir" complete \
+    --project-slug fixture-app \
+    --release REQ-100 \
+    --sdlc-stage 2 \
+    --environment uat \
+    --suite-kind e2e \
+    --idempotency-key github:fixture/repo:feature-e2e.e2e:12345:1:2:REQ-100 \
+    --started-at 2026-07-16T10:00:00Z \
+    --outcome failed \
+    --output-file "$out" >"$dir/stdout.log" 2>"$dir/stderr.log" && exit_code=0 || exit_code=$?
+  if [ "$exit_code" -eq 0 ]; then ok "exit code 0"; else no "expected exit 0"; fi
+  assert_contains "called complete endpoint" "/cycles/complete" "$dir/curl.log"
+  assert_contains "called reconcile endpoint" "/cycles/reconcile" "$dir/curl.log"
+  assert_contains "outputs reconcile endpoint" "execution_endpoint=reconcile" "$out"
+  rm -rf "$dir"
+}
+
+case_missing_release_fails() {
+  echo "case: release resolve failure is not treated as successful fallback"
+  local dir out exit_code
+  dir=$(mktemp -d)
+  make_fixture "$dir"
+  out="$dir/out.env"
+  RESOLVE_STATUS=404 \
+  RESOLVE_BODY='{"error":"missing"}' \
+  run_helper "$dir" start \
+    --project-slug fixture-app \
+    --release REQ-100 \
+    --sdlc-stage 2 \
+    --environment uat \
+    --suite-kind e2e \
+    --idempotency-key key \
+    --output-file "$out" >"$dir/stdout.log" 2>"$dir/stderr.log" && exit_code=0 || exit_code=$?
+  if [ "$exit_code" -ne 0 ]; then ok "exit code non-zero"; else no "expected non-zero"; fi
+  if grep -q '/cycles/start' "$dir/curl.log"; then no "unexpected start endpoint call"; else ok "no start endpoint call"; fi
+  rm -rf "$dir"
+}
+
+case_start_success
+case_complete_reconciles_terminal_conflict
+case_missing_release_fails
+
+echo ""
+echo "=== report-test-execution.test.sh: $PASS passed, $FAIL failed ==="
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi

package/sdlc/files/_common/scripts/submit-for-uat-review.sh

@@ -27,6 +27,8 @@
 #      If status is uat_review   → idempotent no-op (exit 0, "already submitted").
 #      If status is uat_approved → idempotent no-op (exit 0, "already approved").
 #      Any other status          → refuse with an explanatory message.
+#   6. Print the explicit Stage 4 UAT execution command to run after the
+#      reviewer has completed UAT. Submission is not UAT execution.
 
 set -euo pipefail
 
@@ -50,6 +52,23 @@ note() { printf '  - %s\n' "$*"; }
 fail() { printf '  ✗ %s\n' "$*"; FAILED=$((FAILED + 1)); }
 ok()   { printf '  ✓ %s\n' "$*"; }
 
+print_uat_execution_next_step() {
+  local tested_sha="${1:-}"
+  [ -n "$tested_sha" ] || tested_sha="$(git rev-parse HEAD 2>/dev/null || true)"
+  echo ""
+  echo "Next required control: after the reviewer performs UAT, record the Stage 4 execution explicitly."
+  echo "Submission only moves the release into review; it does not claim UAT passed."
+  echo ""
+  echo "  ./scripts/record-uat-execution.sh \\"
+  echo "    --project-slug ${PROJECT_SLUG} \\"
+  echo "    --release ${RELEASE_VERSION:-$VERSION_PREFIX} \\"
+  echo "    --outcome passed \\"
+  echo "    --executor \"<reviewer identity>\" \\"
+  echo "    --tested-sha ${tested_sha:-<tested sha>} \\"
+  echo "    --checklist-ref \"<UAT checklist or portal note>\" \\"
+  echo "    --evidence-ref \"<supporting evidence path or URL>\""
+}
+
 echo "Readiness checks for ${PROJECT_SLUG} ${VERSION_PREFIX}"
 
 # 1. Working tree clean
@@ -134,6 +153,7 @@ case "$RELEASE_STATUS" in
       NEW_STATUS=$(echo "$BODY" | jq -r '.status')
       echo "  Status: draft → ${NEW_STATUS}"
       echo "  Review page: ${BASE_URL}/projects/${PROJECT_SLUG}/releases/${RELEASE_ID}?env=uat"
+      print_uat_execution_next_step "$REMOTE_SHA"
     else
       echo "  Submission failed (HTTP ${HTTP_CODE}): $(echo "$BODY" | jq -r '.error // .')" >&2
       exit 1
@@ -143,6 +163,7 @@ case "$RELEASE_STATUS" in
     echo ""
     echo "Release already submitted for UAT review (status: uat_review). No action taken."
     echo "Review page: ${BASE_URL}/projects/${PROJECT_SLUG}/releases/${RELEASE_ID}?env=uat"
+    print_uat_execution_next_step "$REMOTE_SHA"
     ;;
   uat_approved | prod_review | prod_approved | released)
     echo ""

package/sdlc/files/_common/scripts/upload-evidence.sh

@@ -42,19 +42,19 @@
 #                               4 submit-for-review, 5 deploy. Forwarded as
 #                               `sdlcStage`; unknown to older portals (ignored
 #                               server-side, no error).
-#   --test-cycle <id>           Test cycle identifier (typically the CI run
-#                               ID). Forwarded as `testCycleId`; lets the
-#                               portal group evidence by test cycle per
-#                               ISO/IEC/IEEE 29119-3. Optional — older
-#                               portals ignore the field (no error).
+#   --test-execution <id>       Test execution identifier (typically the CI run
+#                               ID). Forwarded to the portal transport as
+#                               `testCycleId` until the upload API field is
+#                               renamed.
 #   --evidence-scope <scope>    Evidence ownership scope: release | stage |
-#                               cycle | approval. Forwarded as
-#                               `evidenceScope`; optional and ignored by
-#                               older portals.
-#   --test-cycle-record-id <id> First-class portal cycle UUID. Requires
-#                               `--evidence-scope cycle`. Forwarded as
-#                               `testCycleRecordId`; preserved alongside
-#                               legacy `--test-cycle` during dual-write.
+#                               execution | approval. `execution` is mapped
+#                               to the portal transport value `cycle` until
+#                               the upload API field is renamed.
+#   --test-execution-record-id <id>
+#                               First-class portal test execution UUID.
+#                               Requires `--evidence-scope execution`.
+#                               Forwarded to the portal transport as
+#                               `testCycleRecordId`.
 #
 # Required environment variables:
 #   DEVAUDIT_BASE_URL  e.g. https://meta-comply-production.up.railway.app
@@ -136,9 +136,9 @@ while [ "$#" -gt 0 ]; do
     # DevAudit-Installer#96.
     --gate-status) GATE_STATUS="$2"; shift 2 ;;
     --sdlc-stage) SDLC_STAGE="$2"; shift 2 ;;
-    --test-cycle) TEST_CYCLE="$2"; shift 2 ;;
+    --test-execution) TEST_CYCLE="$2"; shift 2 ;;
     --evidence-scope) EVIDENCE_SCOPE="$2"; shift 2 ;;
-    --test-cycle-record-id) TEST_CYCLE_RECORD_ID="$2"; shift 2 ;;
+    --test-execution-record-id) TEST_CYCLE_RECORD_ID="$2"; shift 2 ;;
     # --meta-key key=value (repeatable). Merged into the metadata JSON
     # before posting. Validates the `key=value` shape; rejects bare
     # keys without `=`.
@@ -166,14 +166,18 @@ if [ -n "$SDLC_STAGE" ] && ! [[ "$SDLC_STAGE" =~ ^[1-5]$ ]]; then
   echo "Error: --sdlc-stage must be an integer 1-5 (got: $SDLC_STAGE)"
   exit 1
 fi
-if [ -n "$EVIDENCE_SCOPE" ] && ! [[ "$EVIDENCE_SCOPE" =~ ^(release|stage|cycle|approval)$ ]]; then
-  echo "Error: --evidence-scope must be one of: release, stage, cycle, approval"
+if [ -n "$EVIDENCE_SCOPE" ] && ! [[ "$EVIDENCE_SCOPE" =~ ^(release|stage|execution|approval)$ ]]; then
+  echo "Error: --evidence-scope must be one of: release, stage, execution, approval"
   exit 1
 fi
-if [ -n "$TEST_CYCLE_RECORD_ID" ] && [ "$EVIDENCE_SCOPE" != "cycle" ]; then
-  echo "Error: --test-cycle-record-id requires --evidence-scope cycle"
+if [ -n "$TEST_CYCLE_RECORD_ID" ] && [ "$EVIDENCE_SCOPE" != "execution" ]; then
+  echo "Error: --test-execution-record-id requires --evidence-scope execution"
   exit 1
 fi
+TRANSPORT_EVIDENCE_SCOPE="$EVIDENCE_SCOPE"
+if [ "$TRANSPORT_EVIDENCE_SCOPE" = "execution" ]; then
+  TRANSPORT_EVIDENCE_SCOPE="cycle"
+fi
 
 if [ -z "${DEVAUDIT_BASE_URL:-}" ]; then
   echo "Error: DEVAUDIT_BASE_URL environment variable is required"
@@ -553,7 +557,7 @@ for FILE in "${FILES[@]}"; do
   [ -n "$GATE_STATUS" ] && CURL_ARGS+=(-F "gateStatus=${GATE_STATUS}")
   [ -n "$SDLC_STAGE" ] && CURL_ARGS+=(-F "sdlcStage=${SDLC_STAGE}")
   [ -n "$TEST_CYCLE" ] && CURL_ARGS+=(-F "testCycleId=${TEST_CYCLE}")
-  [ -n "$EVIDENCE_SCOPE" ] && CURL_ARGS+=(-F "evidenceScope=${EVIDENCE_SCOPE}")
+  [ -n "$TRANSPORT_EVIDENCE_SCOPE" ] && CURL_ARGS+=(-F "evidenceScope=${TRANSPORT_EVIDENCE_SCOPE}")
   [ -n "$TEST_CYCLE_RECORD_ID" ] && CURL_ARGS+=(-F "testCycleRecordId=${TEST_CYCLE_RECORD_ID}")
   [ -n "$SENTINEL_CONTENT" ] && CURL_ARGS+=(-F "sentinelContent=${SENTINEL_CONTENT}")
   [ -n "$COMMIT_TIMESTAMP" ] && CURL_ARGS+=(-F "commitTimestamp=${COMMIT_TIMESTAMP}")

package/sdlc/files/_common/scripts/validate-commits.sh

@@ -21,11 +21,12 @@ echo "=== Commit Convention Validation ==="
 echo "Comparing: $BASE_BRANCH...HEAD"
 echo ""
 
-# Conventional Commit regex: type(optional-scope): description
+# Conventional Commit regex: optional [REQ-XXX] prefix, then
+# type(optional-scope): description.
 # Scope accepts anything except `)` so multi-scope subjects like
 # `feat(auth,profile):` and `fix(rewards/expiry):` validate. The closing-paren
-# guard prevents pathological inputs. DevAudit-Installer#93.
-CC_REGEX='^(feat|fix|docs|test|refactor|chore|compliance|security|perf|ci|build|revert)(\([^)]+\))?!?: .+'
+# guard prevents pathological inputs. DevAudit-Installer#93/#440.
+CC_REGEX='^(\[REQ-[0-9]{3,}\][[:space:]]+)?(feat|fix|docs|test|refactor|chore|compliance|security|perf|ci|build|revert)(\([^)]+\))?!?: .+'
 
 COMMITS=$(git log "$BASE_BRANCH"..HEAD --format='%H' || true)
 
@@ -78,7 +79,8 @@ while IFS= read -r sha; do
   # are exempt. Mirrors the commitlint rule; this is the PR-CI half that
   # `--no-verify` can't skip. Work starts from a requirement (which starts
   # from an issue) — use the sdlc-implementer skill to assign one.
-  TYPE=$(echo "$SUBJECT" | grep -oE '^[a-z]+' || true)
+  SUBJECT_FOR_TYPE=$(echo "$SUBJECT" | sed -E 's/^\[REQ-[0-9]{3,}\][[:space:]]+//')
+  TYPE=$(echo "$SUBJECT_FOR_TYPE" | grep -oE '^[a-z]+' || true)
   case "$TYPE" in
     feat|fix|refactor|perf)
       if ! echo "$SUBJECT" | grep -qP '\[REQ-\d{3,}\]' \

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

@@ -138,6 +138,21 @@ run_validator
 assert_exit "no active context exits 1" 1
 assert_grep "hard error emitted without any active release context" "ERROR .*implementation commit but cites no requirement" 1
 
+# Case 5: leading REQ prefix is accepted before the Conventional Commit type.
+echo "Case 5: leading REQ prefix before type is accepted"
+make_fixture "$WORKDIR/case5" "[REQ-123] fix(reports): map dynamic category reports" "Co-Authored-By: Test <test@example.com>"
+run_validator
+assert_exit "leading REQ prefix exits 0" 0
+assert_grep "no conventional-commit error for leading REQ prefix" "Not Conventional Commits format" 0
+assert_grep "no missing-requirement error for leading REQ prefix" "implementation commit but cites no requirement" 0
+
+# Case 6: malformed leading REQ prefixes remain invalid.
+echo "Case 6: malformed leading REQ prefix is rejected"
+make_fixture "$WORKDIR/case6" "[REQ-12] fix: invalid short req prefix" "Co-Authored-By: Test <test@example.com>"
+run_validator
+assert_exit "malformed leading REQ prefix exits 1" 1
+assert_grep "malformed prefix is not treated as conventional" "Not Conventional Commits format" 1
+
 echo
 echo "Result: $PASS passed, $FAIL failed"
 [ "$FAIL" = "0" ]

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

@@ -229,9 +229,9 @@ Before running the suite (Phase 6), verify that the evidence traceability wiring
 
    Also verify the import is present: `import { tagTest } from './helpers/test-tags'` (or the correct relative path from the spec's location to `e2e/helpers/test-tags.ts`).
 
-4. **Check release and cycle provenance.** Before handing the work back to `sdlc-implementer`, identify the tracked `REQ-XXX`, the source branch SHA, and the expected SDLC stage/cycle for the run. The CI evidence upload must retain those values so the portal can show the result in the correct numbered cycle for the release that produced it.
+4. **Check release and execution provenance.** Before handing the work back to `sdlc-implementer`, identify the tracked `REQ-XXX`, the source branch SHA, and the expected SDLC stage/test execution for the run. The CI evidence upload must retain those values so the portal can show the result in the correct numbered execution for the release that produced it.
    - A passing local run is not portal evidence by itself. Report it as local verification and let the configured CI workflow upload the resulting report and screenshots.
-   - For a bundled release, evidence remains attributed to its originating REQ and cycle. The absorbing release may reference that source release through bundle lineage, but must not relabel the source E2E run as newly produced by the absorbing REQ.
+   - For a bundled release, evidence remains attributed to its originating REQ and execution. The absorbing release may reference that source release through bundle lineage, but must not relabel the source E2E run as newly produced by the absorbing REQ.
    - Confirm the CI invocation has an unambiguous release context (`REQ-XXX` or the documented standalone-housekeeping declaration). A bare-date integration housekeeping run is historical CI only; it must not create an approval-ready E2E evidence set.
    - If the project workflow cannot provide this context, halt and report a workflow-contract gap. Do not claim that screenshots or E2E results will appear correctly on the portal.
 
@@ -247,7 +247,7 @@ 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()`, `tagTest()`, and release/cycle provenance checks 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:
+**Write the evidence-wiring sentinel (devaudit-installer#226).** After all Phase 5½ checks pass (all `@requirement`, `evidenceShot()`, `tagTest()`, and release/execution provenance checks 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
@@ -366,7 +366,7 @@ Each filed issue needs:
 
 #### Framework classification + the `incident` label
 
-Every defect filed from Phase 6 becomes `incident_report` evidence when (a) the issue is labelled `incident` and (b) the issue is closed. The flow: closed-with-label → `incident-export.yml` exports the body to `compliance/governance/incident-report-<N>.md` → `compliance-evidence.yml` uploads as `incident_report` evidence → portal flips the attributed clauses MISSING → COVERED.
+Every defect filed from Phase 6 becomes `incident_report` evidence when (a) the issue is labelled `incident` and (b) the issue is closed. The flow: closed-with-label → `incident-export.yml` exports the body to `compliance/governance/incident-report-<N>.md` with `incident_kind`, `source_release`, `source_issue`, and `semantic_id` frontmatter → `compliance-evidence.yml` uploads it as source-owned `incident_report` evidence → portal flips the attributed clauses MISSING → COVERED for that source release.
 
 Classify the defect against this table when filing — the canonical version lives at `governance-doc-author/references/incident-classification.md`, mirrored here for the e2e workflow:
 
@@ -411,6 +411,8 @@ Once closed, the `incident-export.yml` workflow exports this issue's body to `co
 - **Path B (any of SOC2/GDPR/EUAIA ticked):** auto-files a PR with the GDPR triage + sign-off sections to fill in. Merge that PR → `compliance-evidence.yml` uploads as `incident_report`.
 ```
 
+The issue body must identify the owning `REQ-XXX` or standalone housekeeping release so the exported report's `source_release` is correct. Do not let a later bundled release claim the incident as newly produced evidence; bundles inherit by explicit lineage.
+
 Pre-tick boxes you're confident about. Leave the operator-judgement ones (GDPR triage, AI-failure classification) for the operator to confirm in the export PR.
 
 #### Worked examples
@@ -448,7 +450,7 @@ Wrap up with a summary the user can drop into the PR or ticket:
 - Defects filed — count, with links.
 - Requirements gap reports — count, with details (devaudit-installer#212 Gap 4). These are ACs classified as "impossible to test" or "missing AC" — returned to `sdlc-implementer` for the requirements gap flow, not filed as defects.
 - Missed requirements — count, with links.
-- **Release provenance** — originating `REQ-XXX`, local run result, expected CI workflow/run, and expected portal stage/cycle. For bundled work, state the source REQ explicitly and that the absorbing release will reference it through lineage rather than overwrite its attribution.
+- **Release provenance** — originating `REQ-XXX`, local run result, expected CI workflow/run, and expected portal stage/execution. For bundled work, state the source REQ explicitly and that the absorbing release will reference it through lineage rather than overwrite its attribution.
 
 **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:
 
@@ -496,8 +498,8 @@ The canonical helper source lives at `references/evidence.ts` in this skill.
 
 The number of `evidenceShot` calls per spec should scale to the spec's role:
 
-- **While the spec is a feature artefact** (newly authored on the branch, before merge to develop): capture multiple stages — every meaningful transition or state the AC documents. The dense evidence is what reviewers use to verify the AC was met end-to-end during the feature cycle.
-- **Once the spec joins the regression pack** (post-merge, `git diff --diff-filter=A` no longer matches it): capture only the canonical "this still works" anchor per AC. Re-running the dense journey on every regression cycle is noise and inflates CI artefact storage with little signal.
+- **While the spec is a feature artefact** (newly authored on the branch, before merge to develop): capture multiple stages - every meaningful transition or state the AC documents. The dense evidence is what reviewers use to verify the AC was met end-to-end during the feature iteration.
+- **Once the spec joins the regression pack** (post-merge, `git diff --diff-filter=A` no longer matches it): capture only the canonical "this still works" anchor per AC. Re-running the dense journey on every regression execution is noise and inflates CI artefact storage with little signal.
 
 The `EvidenceShotOrigin` signal (`'feature' | 'regression'`) auto-detects from `E2E_NEW_SPECS`. Mark stage screenshots with `{ tier: 'feature' }`; the helper auto-suppresses them on regression runs. The canonical anchor uses the default tier (`'always'`).
 

package/sdlc/files/_common/skills/e2e-test-engineer/references/e2e-regression-3-tier.yml

@@ -2,8 +2,8 @@
 #
 # Copy this into your consumer-owned .github/workflows/e2e-regression.yml
 # to adopt the 3-tier model: smoke (every develop push, fast) / critical
-# (consumer-enabled release PR, ~10-15 min target) / regression (post-merge
-# or scheduled only when the consumer opts in, plus dispatch).
+# (consumer-enabled release PR, ~10-15 min target) / regression after a
+# successful production deployment status (or manual dispatch).
 #
 # The framework does NOT sync this file automatically — your consumer
 # owns its e2e-regression.yml. Apply the patterns below to your own
@@ -17,14 +17,18 @@
 # playwright.config.ts must define the `critical` project for this to
 # fire; if it doesn't, the gate falls back to the existing `smoke`
 # project so PR-to-main stays green during migration.
+#
+# A post-merge regression is release evidence, not a best-effort background
+# task. Keep its timeout below the job timeout so the workflow can retain
+# partial evidence and report a terminal timeout outcome to DevAudit.
 
 name: E2E Regression
 
 on:
   pull_request:
     branches: [main] # critical-tier gate before merge
-  push:
-    branches: [main] # full regression after merge; auto-issues on failure
+  deployment_status:
+    types: [created] # full regression only after successful production deploy
   workflow_dispatch:
     inputs:
       specs:
@@ -42,11 +46,22 @@ concurrency:
 jobs:
   e2e:
     name: E2E Regression Tests
+    if: >-
+      github.event_name != 'deployment_status' ||
+      (github.event.deployment_status.state == 'success' &&
+       (github.event.deployment.environment == 'production' ||
+        github.event.deployment.environment == 'prod' ||
+        endsWith(github.event.deployment.environment, '/ production') ||
+        endsWith(github.event.deployment.environment, '/production')))
     runs-on: ubuntu-latest # adapt to your runner; e.g. self-hosted, ubuntu-24.04
+    # The full regression target is about 35 minutes. Leave time to archive
+    # partial output before GitHub terminates the job.
+    timeout-minutes: 55
     steps:
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0 # for E2E_NEW_SPECS computation
+          ref: ${{ github.event.deployment.sha || github.sha }}
 
       - uses: actions/setup-node@v6
         with:
@@ -79,7 +94,7 @@ jobs:
               fi
               echo "specs=" >> "$GITHUB_OUTPUT"
               ;;
-            push|schedule)
+            deployment_status|schedule)
               echo "project=regression" >> "$GITHUB_OUTPUT"
               echo "specs=" >> "$GITHUB_OUTPUT"
               echo "Running full regression project"
@@ -93,6 +108,25 @@ jobs:
               ;;
           esac
 
+      - name: Record E2E execution context
+        id: context
+        env:
+          E2E_TARGET_URL: ${{ vars.E2E_TARGET_URL }}
+        run: |
+          set -euo pipefail
+          TARGET_URL="${E2E_TARGET_URL:-${PLAYWRIGHT_BASE_URL:-${BASE_URL:-http://localhost:3000}}}"
+          jq -n \
+            --arg targetUrl "$TARGET_URL" \
+            --arg project "${{ steps.select.outputs.project }}" \
+            --arg specs "${{ steps.select.outputs.specs }}" \
+            --arg serverStart "consumer-managed-or-external" \
+            --arg serverStop "consumer-managed-or-external" \
+            --arg startedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+            --argjson timeoutMinutes 40 \
+            '{target_url: $targetUrl, project: $project, selected_specs: $specs, test_server_start: $serverStart, test_server_stop: $serverStop, timeout_minutes: $timeoutMinutes, started_at: $startedAt, outcome: "running"}' \
+            > e2e-regression-metadata.json
+          echo "target_url=$TARGET_URL" >> "$GITHUB_OUTPUT"
+
       - name: Run E2E suite
         id: run
         env:
@@ -100,14 +134,28 @@ jobs:
           PLAYWRIGHT_JSON_OUTPUT_NAME: e2e-regression-results.json
           # Add your e2e_env values here as needed (DEVAUDIT_BASE_URL etc.)
         run: |
-          set -euo pipefail
+          set -uo pipefail
           PROJECT="${{ steps.select.outputs.project }}"
           SPECS="${{ steps.select.outputs.specs }}"
           if [ -n "$SPECS" ]; then
-            npx playwright test --project="$PROJECT" --reporter=json,html $SPECS
+            timeout --signal=TERM --kill-after=60s 40m npx playwright test --project="$PROJECT" --reporter=json,html $SPECS
+          else
+            timeout --signal=TERM --kill-after=60s 40m npx playwright test --project="$PROJECT" --reporter=json,html
+          fi
+          STATUS=$?
+          if [ "$STATUS" -eq 124 ]; then
+            OUTCOME="timed_out"
+            echo "::error::E2E regression exceeded its 40-minute execution budget. Partial evidence will be uploaded."
+          elif [ "$STATUS" -eq 0 ]; then
+            OUTCOME="passed"
           else
-            npx playwright test --project="$PROJECT" --reporter=json,html
+            OUTCOME="failed"
           fi
+          jq --arg outcome "$OUTCOME" --arg completedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --argjson exitCode "$STATUS" \
+            '. + {outcome: $outcome, completed_at: $completedAt, exit_code: $exitCode}' \
+            e2e-regression-metadata.json > e2e-regression-metadata.tmp
+          mv e2e-regression-metadata.tmp e2e-regression-metadata.json
+          exit "$STATUS"
 
       - uses: actions/upload-artifact@v7
         if: always()
@@ -115,11 +163,15 @@ jobs:
           name: e2e-regression-report
           path: |
             e2e-regression-results.json
+            e2e-regression-metadata.json
             playwright-report/
             test-results/
+            e2e-server.log
+            server.log
+          if-no-files-found: warn
 
       # ─────────────────────────────────────────────────────────────
-      # Post-merge auto-issue on regression failure (push:branches:[main])
+      # Post-deployment auto-issue on regression failure.
       #
       # Catches regressions that slipped past the critical-tier PR gate.
       # Opens a high-priority issue tagging the merge commit + the
@@ -127,7 +179,7 @@ jobs:
       # No auto-revert — that's intentionally an operator decision.
       # ─────────────────────────────────────────────────────────────
       - name: Open hotfix issue on post-merge regression
-        if: failure() && github.event_name == 'push' && github.ref == 'refs/heads/main'
+        if: failure() && github.event_name == 'deployment_status' && github.event.deployment_status.state == 'success'
         env:
           GH_TOKEN: ${{ github.token }}
         run: |