@metasession.co/devaudit-cli 0.1.53 → 0.1.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.1.53",
+  "version": "0.1.54",
   "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": "^0.1.53",
+    "@metasession.co/devaudit-plugin-sdk": "^0.1.54",
     "commander": "^12.1.0",
     "consola": "^3.2.3",
     "env-paths": "^3.0.0",

package/scripts/upload-evidence.sh

@@ -133,6 +133,42 @@ fi
 # Strip any trailing slash so we don't double-up later.
 DEVAUDIT_BASE_URL="${DEVAUDIT_BASE_URL%/}"
 
+# --- Base-URL drift check (devaudit-installer#143) ---
+# When the portal moves host (e.g. devaudit.metasession.co → devaudit.ai)
+# Cloudflare / the origin replies 301/302 with a Location header pointing
+# at the new host. Every consumer's CI that still uses the old base URL
+# fails every upload until DEVAUDIT_BASE_URL is rotated. We don't want
+# the failure mode to be a silent "evidence didn't upload" — surface the
+# drift loudly at the top of the run so the operator knows to rotate the
+# secret. (We still upload via `curl -L` so the run itself succeeds; the
+# warning is the nudge to fix the secret, not a hard stop.)
+probe_base_url_drift() {
+  # `${var:-}` so `set -u` doesn't trip if curl isn't installed or the
+  # network is offline. Probe with -I (HEAD); fall back to GET if HEAD
+  # is rejected by the upstream proxy. 5s connect + 10s overall is
+  # plenty for a redirect-only probe — we never read a body.
+  local probe_url="${DEVAUDIT_BASE_URL}/api/health"
+  local resp
+  resp=$(curl -sI -o /dev/null --max-time 10 --connect-timeout 5 \
+    -w "%{http_code} %{redirect_url}" "$probe_url" 2>/dev/null || true)
+  local code="${resp%% *}"
+  local redirect_url="${resp#* }"
+  if [[ "$code" =~ ^30[1278]$ ]] && [ -n "$redirect_url" ] && [ "$redirect_url" != " " ]; then
+    local old_host new_host
+    old_host=$(printf '%s' "$DEVAUDIT_BASE_URL" | sed -E 's|^https?://([^/]+).*|\1|')
+    new_host=$(printf '%s' "$redirect_url"      | sed -E 's|^https?://([^/]+).*|\1|')
+    if [ -n "$new_host" ] && [ "$old_host" != "$new_host" ]; then
+      echo "WARNING: DEVAUDIT_BASE_URL host '${old_host}' redirects to '${new_host}'."
+      echo "         Rotate the DEVAUDIT_BASE_URL secret in your CI environment to"
+      echo "         the new host to avoid silent breakage. (Uploads will still"
+      echo "         succeed this run — curl follows the redirect — but the"
+      echo "         underlying secret should be updated.)"
+      echo "         Ref: https://github.com/metasession-dev/DevAudit-Installer/issues/143"
+    fi
+  fi
+}
+probe_base_url_drift
+
 # --- Build metadata JSON ---
 # Assemble entries first; only emit `{ ... }` if at least one field is
 # set. Each entry is a `"key":"value"` JSON pair with the value
@@ -213,8 +249,12 @@ for FILE in "${FILES[@]}"; do
   fi
   FILE_SIZE=$(stat -c%s "$FILE" 2>/dev/null || stat -f%z "$FILE")
   echo -n "Uploading ${FILENAME}... "
+  # `-L` follows 3xx redirects (devaudit-installer#143). The portal host
+  # has moved before (devaudit.metasession.co → devaudit.ai); without -L
+  # every consumer's CI silently fails on a stale base URL. `--max-redirs 3`
+  # bounds the follow so a misconfigured redirect loop can't hang CI.
   CURL_ARGS=(
-    -X POST "$UPLOAD_URL"
+    -X POST -L --max-redirs 3 "$UPLOAD_URL"
     -H "Authorization: Bearer ${DEVAUDIT_API_KEY}"
     -F "file=@${FILE}"
     -F "projectSlug=${PROJECT_SLUG}"

package/sdlc/files/_common/skills/adr-author/SKILL.md

@@ -206,7 +206,7 @@ I have reviewed the ADR-worthiness verdict above and confirm:
 
 **Step 2 — Tag for upload.** The CI's `compliance-evidence.yml` uploads this file as `evidence_type=architecture_decision` (added to META-COMPLY's `EVIDENCE_TYPE_REGISTRY` in the paired sub-PR). The framework-coverage matrix maps this to clauses per `framework-registry-auditor`'s review — see the META-COMPLY-side PR for the final clause attributions (v1 may ship orphan-by-design if the auditor rejects proposed mappings; see [`requirements-aligner`](../requirements-aligner/SKILL.md) for the precedent).
 
-**Step 3 — Hand-off back to `sdlc-implementer`.** The skill's job ends at the artefact + the operator sign-off. The parent orchestrator continues with the rest of Stage 3.
+**Step 3 — Return to the running `sdlc-implementer` context.** The skill's job ends at the artefact + the operator sign-off. The orchestrator immediately continues with the rest of Stage 3 inline — no pause, no operator nudge needed. (Skills run in the same invocation context; control returns synchronously when this skill exits. See `sdlc-implementer/SKILL.md` § *Sub-skill return semantics*.)
 
 ### Phase 3 — Per-REQ ad-hoc audit
 

package/sdlc/files/_common/skills/requirements-aligner/SKILL.md

@@ -132,7 +132,7 @@ I have reviewed the AC-to-SRS-item traces above and confirm:
 
 **Step 2 — Tag for upload.** The CI's `compliance-evidence.yml` uploads this file as `evidence_type=srs_alignment` (added to META-COMPLY's `EVIDENCE_TYPE_REGISTRY` in the paired sub-PR). The framework-coverage matrix then closes `ISO29119.3.4` (Test Plan — requirements traceability) and `SOC2.CC2.1` (Communication of policies — when paired with INSTRUCTIONS.md) for this REQ.
 
-**Step 3 — Hand-off back to `sdlc-implementer`.** The skill's job ends at the artefact + the operator sign-off. The parent orchestrator continues with the rest of Stage 3 (security summary, evidence upload, release ticket).
+**Step 3 — Return to the running `sdlc-implementer` context.** The skill's job ends at the artefact + the operator sign-off. The orchestrator immediately continues with the rest of Stage 3 (security summary, evidence upload, release ticket) inline — no pause, no operator nudge needed. (Skills run in the same invocation context; control returns synchronously when this skill exits. See `sdlc-implementer/SKILL.md` § *Sub-skill return semantics*.)
 
 ### Phase 3 — Per-REQ ad-hoc audit
 

package/sdlc/files/_common/skills/risk-register-keeper/SKILL.md

@@ -163,7 +163,7 @@ I have reviewed the risk register entries above and confirm:
 
 **Step 2 — Tag for upload.** The CI's `compliance-evidence.yml` uploads this file as `evidence_type=risk_assessment` (added to META-COMPLY's `EVIDENCE_TYPE_REGISTRY` in the paired sub-PR). The framework-coverage matrix attribution depends on `framework-registry-auditor`'s review — see the META-COMPLY-side PR for final clause closures.
 
-**Step 3 — Hand-off back to `sdlc-implementer`.** The skill's job ends at the artefact + operator sign-off.
+**Step 3 — Return to the running `sdlc-implementer` context.** The skill's job ends at the artefact + the operator sign-off. The orchestrator immediately continues with the rest of Stage 3 inline — no pause, no operator nudge needed. (Skills run in the same invocation context; control returns synchronously when this skill exits. See `sdlc-implementer/SKILL.md` § *Sub-skill return semantics*.)
 
 ### Phase 4 — `solo_with_gap` approval check
 

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

@@ -45,6 +45,20 @@ The orchestrator MUST invoke `e2e-test-engineer` for end-to-end and visual-regre
 
 Unit-test and integration-test work stays with this skill until a counterpart unit-test skill ships. The full sub-skill call graph lives at [`references/call-graph.md`](./references/call-graph.md).
 
+## Sub-skill return semantics (devaudit-installer#144)
+
+**Sub-skills return findings synchronously; do not wait for operator confirmation between sub-skill returns.** Invoking a Skill loads its instructions into this same invocation context — there is no separate agent, no separate process. When a sub-skill emits its final summary and stops, this orchestrator's next step runs immediately, in the same turn if possible.
+
+The literal phrasing _"Returns to the running `sdlc-implementer` context"_ at the tail of each sub-skill (`requirements-aligner`, `adr-author`, `risk-register-keeper`, and any future siblings) does **not** mean "pause and wait for the operator to nudge you" — it means "you have control again; keep going with the parent workflow." A chain of three sub-skill calls in Phase 1 (steps 6 → 7 → 8) or Phase 3 (steps 1 → 2 → 3) is a single flowing sequence; do not stop between them.
+
+The only pauses in the whole workflow are the explicitly-named checkpoints:
+
+- **Phase 1 step 11** — pause for human approval **iff** risk class is HIGH or CRITICAL (or `--require-plan-approval` is set).
+- **Phase 4 step 5** — hard stop, release PR opened, awaiting UAT review on the portal.
+- **Phase 5** — invoked separately by the user (`resume REQ-XXX`).
+
+Everything else is silent continuation. The rule is **opt-in-to-pause, not opt-out-of-pause**. If you find yourself stopping after a sub-skill's "Return to the running `sdlc-implementer` context" line and waiting for the operator to ask _"is anything happening?"_ — that is the bug this section exists to prevent. Keep going.
+
 ## SDLC navigability — LAST/NEXT status sticky (devaudit#131)
 
 Long-running SDLC issues accumulate dozens of comments across multiple Claude Code sessions. The operator returning to the thread should be able to answer two questions in under five seconds:
@@ -204,13 +218,19 @@ _Workflow tweak (CI artifact upload, gate timeout bump, etc.)_
 
 Reached from Phase 0 for non-tracked change-types. The skill drives this end-to-end; the only difference from the tracked cycle is the absence of _ceremony_, not the absence of _guidance_. It pauses only where a human is genuinely required (PR review, merge).
 
+**CI trigger shape — read once before step 7.** The DevAudit-Installer-generated `ci.yml.template` defaults to **post-merge-only** triggers (`push: branches: [<integration>]`, no `pull_request:` trigger). On these projects there will be **no PR-time checks** to wait for — review + merge is the gate, and the post-merge CI run on the integration branch is the actual quality gate. A consumer who has explicitly added a `pull_request:` trigger has PR-time CI in addition. The skill must adapt step 7's wording to whichever shape the project uses; never poll a PR for checks that the template doesn't trigger.
+
 1. **Branch off `$INTEGRATION_BRANCH`** with a housekeeping prefix — `chore/…`, `docs/…`, `ci/…`, `build/…`, `test/…`, or `compliance/…` for a doc-only change against an existing REQ.
 2. **Make the change**, single-purpose. If it turns out to touch runtime behaviour in `app/` / `lib/`, stop and reclassify as tracked — the commit-type rule is the backstop.
 3. **Run all gates locally** (`npm run lint`, `npx tsc --noEmit`, the test suite, `semgrep`, `npm audit` — or the stack-adapter equivalents). Trivial ≠ unverified; never `--no-verify`.
 4. **Commit** with a housekeeping type and **no** `REQ-XXX` — `docs:` / `chore:` / `ci:` / `build:` / `test:` / `revert:` are exempt from the `[REQ-XXX]` rule; a `compliance:` doc-only change references the existing REQ. `Co-Authored-By: Claude` if AI-assisted.
 5. **Push and open the PR** into `$INTEGRATION_BRANCH` (`gh pr create --base "$INTEGRATION_BRANCH" --head <branch>`). CI runs the same quality gates; `compliance-validation.yml` finds no `REQ-XXX` and skips artifact validation.
 6. **For `ci:` changes, verify-via-dispatch before merging.** `gh workflow run <workflow.yml> --ref <branch>` fires the modified workflow against the PR branch. If the change broke a step, the dispatch run fails loudly and you fix-forward _before_ the merge ships the broken gate to `$INTEGRATION_BRANCH`. This is the cheapest insurance against silent CI regressions — a `ci:` change that breaks a gate is most damaging _after_ it lands.
-7. **Report honest status** — wait for CI, name any failing check, fix and re-push. Never announce "ready" while a required check is red.
+7. **Report honest status — adapt to the project's CI trigger shape (devaudit-installer#145).** Check whether `.github/workflows/ci.yml` has a `pull_request:` trigger.
+   - **PR-time CI present** — wait for CI to settle, name any failing check, fix and re-push. Never announce "ready" while a required check is red.
+   - **Post-merge-only CI (the DevAudit-Installer default — `push: branches: [<integration>]` with no `pull_request:` trigger)** — say so explicitly in the LAST/NEXT sticky: _"no PR-time checks will fire; review + merge is the gate; CI runs post-merge on `$INTEGRATION_BRANCH`."_ Don't poll the PR for checks that won't arrive. The post-merge run (CI Pipeline + Compliance Evidence Upload on the integration branch) is the actual gate; address it via fix-forward if it fails.
+
+   Either way, never bypass a gate (no `--no-verify`, no `--admin` merge of a red required check); the only difference is **where** you wait for the gate to fire — before merge vs. after merge.
 8. **Guide review → merge.** A human still reviews the PR (separation of duties). There is **no** portal release approval, no UAT four-eyes, no Production gate, and no close-out. Merge once CI is green and the reviewer approves.
 9. **Done.** A housekeeping push produces at most a bare-date release (`vYYYY.MM.DD`) with no approval gate; a doc-only push attaches its docs to the existing `REQ-XXX` release. No further action required — report completion and stop.
 

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

@@ -484,8 +484,21 @@ jobs:
           # moment each acceptance criterion is demonstrated, NOT the Playwright
           # report's trailing/failure capture. evidenceType `screenshot` →
           # image/png renders inline. Only when a pending release ticket defines
-          # the in-scope REQ(s); skipped on ordinary dev pushes. Best-effort: a
-          # screenshot upload failure warns but never blocks the gate.
+          # the in-scope REQ(s); skipped on ordinary dev pushes.
+          #
+          # devaudit-installer#147 — per-REQ glob scoping + UPLOAD_FAILURES
+          # accounting. Previously the SHOTS glob was project-wide
+          # (`ci-evidence/compliance/evidence/*/screenshots/*.png`) and the
+          # for-REQ loop uploaded that cross-product against every in-scope
+          # REQ. Out-of-scope REQs' legacy PNGs whose filenames don't match
+          # `REQ-XXX-AC<n>-<slug>.png` then 400'd at the portal — and the
+          # `|| echo "::warning::..."` swallowed the failure so the step
+          # reported SUCCESS while screenshots were quietly missing. Now each
+          # in-scope REQ globs its OWN screenshots/ directory; out-of-scope
+          # legacy folders are intentionally ignored. To re-upload an older
+          # REQ's screenshots, add its release ticket back under
+          # compliance/pending-releases/. Failures now bump UPLOAD_FAILURES
+          # so the step exits non-zero and the release PR turns red.
           SHOT_REQS=()
           if [ -d compliance/pending-releases ]; then
             for TICKET in compliance/pending-releases/RELEASE-TICKET-REQ-*.md; do
@@ -494,14 +507,8 @@ jobs:
             done
           fi
           shopt -s nullglob
-          # Only this run's freshly-generated screenshots (from the ci-results
-          # artifact). The full pack regenerates them every run, so the committed
-          # copies under compliance/evidence/ are redundant here — globbing both
-          # uploaded every image twice (deduped on display, but wasteful + rate-limit
-          # pressure) and swept in legacy screenshots from unrelated past releases.
-          SHOTS=(ci-evidence/compliance/evidence/*/screenshots/*.png)
-          if [ "${#SHOT_REQS[@]}" -gt 0 ] && [ "${#SHOTS[@]}" -gt 0 ]; then
-            echo "Uploading ${#SHOTS[@]} evidence screenshot(s) for: ${SHOT_REQS[*]}"
+          if [ "${#SHOT_REQS[@]}" -gt 0 ]; then
+            echo "Uploading per-AC evidence screenshots for: ${SHOT_REQS[*]}"
             SHOT_TMP="$(mktemp -d)"
             for REQ in "${SHOT_REQS[@]}"; do
               # Per-REQ release metadata for the portal (no-clobbered on existing rows):
@@ -518,7 +525,16 @@ jobs:
               REQ_META=()
               [ -n "$REQ_TITLE" ] && REQ_META+=(--release-title "$REQ_TITLE")
               [ -n "$REQ_CT" ] && REQ_META+=(--change-type "$REQ_CT")
-              for PNG in "${SHOTS[@]}"; do
+              # devaudit-installer#147 — per-REQ scoped glob. ONLY this REQ's
+              # own screenshots/ directory; legacy folders for REQs not in
+              # SHOT_REQS are intentionally ignored.
+              REQ_SHOTS=(ci-evidence/compliance/evidence/"$REQ"/screenshots/*.png)
+              if [ "${#REQ_SHOTS[@]}" -eq 0 ]; then
+                echo "No per-AC screenshots for ${REQ} (none captured by evidenceShot this run)"
+                continue
+              fi
+              echo "Uploading ${#REQ_SHOTS[@]} screenshot(s) for ${REQ}"
+              for PNG in "${REQ_SHOTS[@]}"; do
                 # The basename is the canonical evidenceShot filename
                 # `REQ-XXX-AC<n>-<slug>.png`. The portal validates this
                 # shape on upload — anything else is rejected with 400.
@@ -540,12 +556,22 @@ jobs:
                   fi
                 fi
 
-                bash scripts/upload-evidence.sh \
+                if bash scripts/upload-evidence.sh \
                   {{PROJECT_SLUG}} "$REQ" screenshot "$NAMED" \
                   --category test_report ${FLAGS} --release "$REQ" \
                   "${REQ_META[@]}" \
-                  "${ORIGIN_META[@]}" \
-                  || echo "::warning::evidence screenshot upload failed: ${PNG} -> ${REQ}"
+                  "${ORIGIN_META[@]}"
+                then
+                  :
+                else
+                  # devaudit-installer#147 — feed the same UPLOAD_FAILURES
+                  # counter that gate uploads use, so a screenshot
+                  # rejected by the portal's filename validator (or any
+                  # other failure mode) turns the step RED instead of
+                  # silently warning.
+                  echo "::warning::evidence screenshot upload failed: ${PNG} -> ${REQ}"
+                  UPLOAD_FAILURES=$((UPLOAD_FAILURES + 1))
+                fi
               done
             done
           fi

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

@@ -25,14 +25,29 @@ on:
     branches: [develop]
     paths:
       - 'compliance/**'
+  # devaudit-installer#149 — listen for completion of the E2E Regression
+  # workflow so the critical-tier run on the release PR + the full
+  # regression on post-merge to main both upload their JSON results +
+  # HTML report to the portal under the right release. Without this hook
+  # the UAT four-eyes reviewer only sees smoke-tier evidence from the
+  # feature PR's develop merge — the broader sweep against the
+  # about-to-be-promoted integration code never reaches the portal.
+  workflow_run:
+    workflows: ['E2E Regression']
+    types: [completed]
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event.workflow_run.id || '' }}
   cancel-in-progress: true
 
 jobs:
   upload-compliance-evidence:
     name: Upload Compliance Evidence
+    # devaudit-installer#149 — only the push/dispatch paths run the
+    # compliance-doc upload. The workflow_run path is handled by the
+    # sibling job below; running both on a workflow_run event would
+    # double-upload every compliance doc.
+    if: github.event_name != 'workflow_run'
     runs-on: {{RUNNER}}
     # Permissions are needed because the "Auto-generate housekeeping stubs"
     # step pushes a new branch + opens a PR via `gh pr create` when the
@@ -412,22 +427,58 @@ jobs:
               REQ_META_ARGS=$(req_meta_args "$REQ_ID")
               for ARTIFACT in "$REQ_DIR"*.md; do
                 [ -f "$ARTIFACT" ] || continue
-                # Per-REQ test-execution-summary.md is the ISO 29119-3 §3.5.6
-                # Test Completion Report for THIS release cycle (populated by
-                # the e2e-test-engineer skill in Stage 3 — scope, results, AC
-                # mapping, defects). Upload as `test_report` so it satisfies
-                # the portal's Test Reports gate with per-release evidence
-                # instead of the project-level evergreen TSR (which from
-                # v0.1.32 downgrades to `compliance_document`). See
-                # DevAudit-Installer#101.
+                # Per-REQ basename → (evidence_type, evidence_category) routing.
+                # The bare default (compliance_document, planning) is the
+                # historical catch-all; the named cases route specific
+                # artefacts to their dedicated evidence types so the portal's
+                # framework-coverage matrix attributes them correctly:
+                #
+                #   - test-execution-summary.md / test-summary-report.md
+                #       → test_report : ISO 29119-3 §3.5.6 Test Completion
+                #         Report per release cycle. Satisfies the portal's
+                #         Test Reports gate with per-release evidence
+                #         instead of the project-level evergreen TSR (which
+                #         from v0.1.32 downgrades to compliance_document).
+                #         DevAudit-Installer#101.
+                #
+                #   - srs-alignment.md
+                #       → srs_alignment : output of the requirements-aligner
+                #         skill at Stage 3. Orphan-by-design at v1 per
+                #         META-COMPLY framework-registry-auditor review;
+                #         surfaces in Documents tab + audit-pack export.
+                #         DevAudit-Installer#119.
+                #
+                #   - architecture-decision.md
+                #       → architecture_decision : output of the adr-author
+                #         skill at Stage 3. Closes ISO 27001 A.8.25 (Secure
+                #         development life cycle) via the dedicated type
+                #         predicate. DevAudit-Installer#120.
+                #
+                #   - risk-assessment.md
+                #       → risk_assessment : output of the risk-register-keeper
+                #         skill at Stage 3. Closes SOC 2 CC3.2 (Risk
+                #         identification and assessment) via the dedicated
+                #         type predicate. DevAudit-Installer#121.
+                #
+                # Until this routing existed the new artefacts uploaded as
+                # compliance_document, which matches the project-baseline
+                # docs predicate but NOT the per-REQ Tier 3 clause
+                # predicates that expect the dedicated types — so the matrix
+                # reported MISSING / PARTIAL for SOC2.CC3.2 + ISO27001.A.8.25
+                # despite the files being present. DevAudit-Installer#146.
                 BASENAME=$(basename "$ARTIFACT")
-                if [ "$BASENAME" = "test-execution-summary.md" ] || [ "$BASENAME" = "test-summary-report.md" ]; then
-                  EVTYPE=test_report
-                  EVCAT=test_report
-                else
-                  EVTYPE=compliance_document
-                  EVCAT=planning
-                fi
+                case "$BASENAME" in
+                  test-execution-summary.md|test-summary-report.md)
+                    EVTYPE=test_report; EVCAT=test_report ;;
+                  srs-alignment.md)
+                    EVTYPE=srs_alignment; EVCAT=planning ;;
+                  architecture-decision.md)
+                    EVTYPE=architecture_decision; EVCAT=planning ;;
+                  risk-assessment.md)
+                    EVTYPE=risk_assessment; EVCAT=planning ;;
+                  *)
+                    EVTYPE=compliance_document; EVCAT=planning ;;
+                esac
                 echo "Uploading: ${REQ_ID}/${BASENAME} (${EVTYPE})"
                 eval "bash scripts/upload-evidence.sh \
                   {{PROJECT_SLUG}} \"${REQ_ID}\" ${EVTYPE} \"$ARTIFACT\" \
@@ -440,3 +491,174 @@ jobs:
 
       - name: Summary
         run: echo "Compliance evidence uploaded for ${{ steps.version.outputs.version }}"
+
+  # devaudit-installer#149 — upload the E2E Regression artefacts to the
+  # portal so the critical-tier run on the release PR + the full
+  # regression on post-merge to main both land as portal evidence (not
+  # just GitHub Actions artifacts).
+  #
+  # Fires only on `workflow_run` events. The triggering workflow is the
+  # consumer's `E2E Regression` (project-owned per the v0.1.53 3-tier
+  # gating model) which writes:
+  #   - e2e-regression-results.json (Playwright JSON reporter)
+  #   - playwright-report/          (HTML report)
+  #   - test-results/               (per-spec traces / videos / screenshots)
+  # to GitHub Actions artifact storage under the name `e2e-regression-report`.
+  # We download that artifact via the workflow_run.id, derive the release
+  # version against the triggering run's head_sha, then upload the
+  # canonical artefacts as `evidence_type=e2e_result` + `test_report`
+  # against each in-scope REQ.
+  upload-e2e-regression-evidence:
+    name: Upload E2E Regression Evidence
+    if: github.event_name == 'workflow_run'
+    runs-on: {{RUNNER}}
+    # actions: read is required so `actions/download-artifact@v4` with
+    # `run-id` can read another workflow's artifacts. Without it the
+    # download step fails with a 404 even when the artifact exists.
+    permissions:
+      contents: read
+      actions: read
+    env:
+      DEVAUDIT_BASE_URL_VAR: ${{ vars.DEVAUDIT_BASE_URL }}
+      DEVAUDIT_API_KEY: ${{ secrets.DEVAUDIT_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Check out the SHA the E2E Regression ran against — that
+          # determines the release version + the in-scope REQs via the
+          # pending release tickets at that snapshot, not whatever
+          # default branch currently points to.
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+
+      - name: Resolve DevAudit base URL
+        id: resolve
+        run: |
+          CONFIG_URL=""
+          if [ -f sdlc-config.json ]; then
+            CONFIG_URL=$(jq -r '.devaudit.base_url // empty' sdlc-config.json 2>/dev/null || true)
+          fi
+          if [ -n "$CONFIG_URL" ]; then
+            BASE="$CONFIG_URL"
+          elif [ -n "$DEVAUDIT_BASE_URL_VAR" ]; then
+            BASE="$DEVAUDIT_BASE_URL_VAR"
+          else
+            echo "::warning::No DevAudit base URL configured — skipping E2E evidence upload."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if [ -z "${DEVAUDIT_API_KEY}" ]; then
+            echo "::warning::DEVAUDIT_API_KEY not set — skipping E2E evidence upload."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "skip=false" >> "$GITHUB_OUTPUT"
+          echo "DEVAUDIT_BASE_URL=${BASE%/}" >> "$GITHUB_ENV"
+
+      - name: Download E2E Regression artifact
+        if: steps.resolve.outputs.skip != 'true'
+        uses: actions/download-artifact@v4
+        with:
+          name: e2e-regression-report
+          path: e2e-artifacts/
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+        continue-on-error: true
+
+      - name: Derive release version
+        if: steps.resolve.outputs.skip != 'true'
+        id: version
+        run: |
+          chmod +x scripts/derive-release-version.sh 2>/dev/null || true
+          VERSION=$(./scripts/derive-release-version.sh)
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Resolved release version: ${VERSION}"
+
+      - name: Upload E2E Regression evidence to DevAudit
+        if: steps.resolve.outputs.skip != 'true'
+        run: |
+          set -euo pipefail
+          DERIVED_RELEASE="${{ steps.version.outputs.version }}"
+
+          # Tier metadata for the portal (the operator filters/groups by
+          # this on the release detail). pull_request → critical;
+          # push to main → regression; otherwise dispatch/schedule.
+          PRIOR_EVENT="${{ github.event.workflow_run.event }}"
+          PRIOR_BRANCH="${{ github.event.workflow_run.head_branch }}"
+          case "$PRIOR_EVENT" in
+            pull_request) TIER=critical ;;
+            push)         TIER=regression ;;
+            *)            TIER="${PRIOR_EVENT}" ;;
+          esac
+
+          # Common flags for upload-evidence.sh. Branch + SHA come from
+          # the triggering run, not from this workflow_run dispatch.
+          FLAGS="--create-release-if-missing --environment uat \
+                 --git-sha ${{ github.event.workflow_run.head_sha }} \
+                 --ci-run-id ${{ github.event.workflow_run.id }} \
+                 --branch ${PRIOR_BRANCH}"
+
+          # In-scope REQs from pending release tickets at the triggering
+          # SHA. Fall back to `_compliance-docs` if no tickets present so
+          # the artefact at least lands somewhere visible.
+          REQS=()
+          if [ -d compliance/pending-releases ]; then
+            for TICKET in compliance/pending-releases/RELEASE-TICKET-REQ-*.md; do
+              [ -f "$TICKET" ] || continue
+              REQS+=("$(basename "$TICKET" .md | sed 's/^RELEASE-TICKET-//')")
+            done
+          fi
+          if [ "${#REQS[@]}" -eq 0 ]; then
+            REQS=(_compliance-docs)
+          fi
+          echo "Uploading E2E ${TIER}-tier evidence to: ${REQS[*]} (release: ${DERIVED_RELEASE})"
+
+          UPLOAD_FAILURES=0
+          for REQ in "${REQS[@]}"; do
+            # 1. JSON reporter output → e2e_result. The single canonical
+            # machine-readable artefact for the run.
+            if [ -f e2e-artifacts/e2e-regression-results.json ]; then
+              if bash scripts/upload-evidence.sh \
+                {{PROJECT_SLUG}} "$REQ" e2e_result \
+                e2e-artifacts/e2e-regression-results.json \
+                --category test_report ${FLAGS} --release "${DERIVED_RELEASE}" \
+                --meta-key "tier=${TIER}"
+              then
+                :
+              else
+                echo "::warning::e2e_result upload failed for ${REQ}"
+                UPLOAD_FAILURES=$((UPLOAD_FAILURES + 1))
+              fi
+            fi
+            # 2. Playwright HTML report index → test_report. Operator-
+            # facing artefact (the formatted run summary). Skipped if
+            # the report directory is missing (e.g. an upstream
+            # infrastructure failure aborted before reporting).
+            if [ -f e2e-artifacts/playwright-report/index.html ]; then
+              if bash scripts/upload-evidence.sh \
+                {{PROJECT_SLUG}} "$REQ" test_report \
+                e2e-artifacts/playwright-report/index.html \
+                --category test_report ${FLAGS} --release "${DERIVED_RELEASE}" \
+                --meta-key "tier=${TIER}"
+              then
+                :
+              else
+                echo "::warning::playwright HTML report upload failed for ${REQ}"
+                UPLOAD_FAILURES=$((UPLOAD_FAILURES + 1))
+              fi
+            fi
+          done
+
+          # Per-spec failure screenshots from test-results/ are NOT
+          # uploaded: Playwright names them `test-failed-1.png` /
+          # `test-finished-1.png`, which the portal's filename
+          # validator (REQ-XXX-AC<n>-<slug>.png) rejects. Use the
+          # evidenceShot(page, REQ, AC, slug) helper from the
+          # e2e-test-engineer skill for per-AC named captures; those
+          # upload via ci.yml's per-REQ screenshot loop.
+
+          if [ "$UPLOAD_FAILURES" -gt 0 ]; then
+            echo "::error::${UPLOAD_FAILURES} E2E evidence upload(s) failed — portal release matrix may be incomplete"
+            exit 1
+          fi
+          echo "E2E ${TIER}-tier evidence uploaded for ${#REQS[@]} requirement(s)"