@metasession.co/devaudit-cli 0.1.0 → 0.1.2

package/sdlc/files/ci/check-release-approval.yml.template

@@ -0,0 +1,201 @@
+# Release Approval Gate — blocks PR merge until release is approved in DevAudit.
+#
+# Four-eyes release-approval gate (always required). When UAT-environment
+# verification is configured for the project (sdlc-config.json `uat.enabled`),
+# the human approver factors that into their review, but the gate itself is
+# about the approval click — not the UAT-env exercise. Renamed from
+# "UAT Approval Gate" in sdlc-v1.22.0; backend release status enum
+# `uat_approved` is preserved for backwards-compat (renamed in v1.23.0).
+#
+# Generated by `devaudit install` / `devaudit update` from sdlc-config.json.
+# Do not edit manually — re-run the CLI (`devaudit update`) to regenerate.
+#
+# Auth: project-scoped API key. Issue from DevAudit → Project
+# Settings → API Keys (uploader role). Set as repo Secret
+# DEVAUDIT_API_KEY. Base URL is read from sdlc-config.json
+# devaudit.base_url; falls back to repo Variable DEVAUDIT_BASE_URL
+# (deprecated, removed in v1.23.0).
+
+name: Release Approval Gate
+
+on:
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  check-approval:
+    name: DevAudit Release Approval
+    runs-on: {{RUNNER}}
+    env:
+      DEVAUDIT_BASE_URL_VAR: ${{ vars.DEVAUDIT_BASE_URL }}
+      DEVAUDIT_API_KEY: ${{ secrets.DEVAUDIT_API_KEY }}
+      PROJECT_SLUG: {{PROJECT_SLUG}}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Resolve DevAudit base URL
+        run: |
+          # Prefer sdlc-config.json (visible in PR review) over repo Variable.
+          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"
+            echo "Using devaudit.base_url from sdlc-config.json: $BASE"
+          elif [ -n "$DEVAUDIT_BASE_URL_VAR" ]; then
+            BASE="$DEVAUDIT_BASE_URL_VAR"
+            echo "::warning::Using repo Variable DEVAUDIT_BASE_URL (deprecated in v1.23.0). Move base_url to sdlc-config.json devaudit.base_url for PR-visible config."
+          else
+            echo "::error::No DevAudit base URL configured. Set devaudit.base_url in sdlc-config.json."
+            exit 1
+          fi
+          # Bootstrap mode (#301): the first PR introducing the SDLC framework
+          # can't pass the gate that the framework introduces. If the API key
+          # secret isn't set yet, fall through with a notice — gate passes,
+          # enforcement kicks in once the secret is configured AND the project
+          # is auto-created by the first compliance-evidence.yml run.
+          if [ -z "${DEVAUDIT_API_KEY}" ]; then
+            echo "::notice::DEVAUDIT_API_KEY not set — bootstrap mode. Gate passes. Configure the secret after the first compliance-evidence.yml run initialises ${PROJECT_SLUG} in DevAudit; enforcement starts on the next PR after that."
+            echo "BOOTSTRAP_MODE=true" >> "$GITHUB_ENV"
+            exit 0
+          fi
+          # Pre-flight: confirm destination is reachable. Catches dead aliases / wrong hosts early.
+          CODE=$(curl -s -o /dev/null -w "%{http_code}" -m 10 -I "${BASE%/}/" || echo "000")
+          case "$CODE" in
+            2*|3*) echo "DevAudit reachable at ${BASE} (HTTP ${CODE})" ;;
+            *) echo "::error::DevAudit base URL ${BASE} returned HTTP ${CODE}. Likely a stale alias or wrong host. Check sdlc-config.json devaudit.base_url."; exit 1 ;;
+          esac
+          # Bootstrap probe (#301): project may not exist in DevAudit yet —
+          # the first compliance-evidence.yml run auto-creates it. A 404 here
+          # means we're on the introducing PR; pass with a notice. 401/403
+          # means the API key is invalid → fail (not bootstrap).
+          PROJ_CODE=$(curl -s -o /dev/null -w "%{http_code}" -m 10 \
+            -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+            "${BASE%/}/api/ci/projects/${PROJECT_SLUG}" || echo "000")
+          case "$PROJ_CODE" in
+            2*)
+              echo "DevAudit project '${PROJECT_SLUG}' confirmed (HTTP ${PROJ_CODE})"
+              ;;
+            404)
+              echo "::notice::DevAudit project '${PROJECT_SLUG}' does not exist yet (HTTP 404) — bootstrap mode. Gate passes. The project will be auto-created by the first compliance-evidence.yml run; enforcement kicks in on the next PR after that."
+              echo "BOOTSTRAP_MODE=true" >> "$GITHUB_ENV"
+              exit 0
+              ;;
+            401|403)
+              echo "::error::DevAudit returned HTTP ${PROJ_CODE} for project '${PROJECT_SLUG}' — API key is invalid or lacks access. Verify DEVAUDIT_API_KEY belongs to the right project."
+              exit 1
+              ;;
+            *)
+              echo "::error::Unexpected HTTP ${PROJ_CODE} when probing DevAudit project '${PROJECT_SLUG}'. Investigate before retrying."
+              exit 1
+              ;;
+          esac
+          echo "BOOTSTRAP_MODE=false" >> "$GITHUB_ENV"
+          # Strip trailing slash so we don't double-up later.
+          echo "BASE=${BASE%/}" >> "$GITHUB_ENV"
+          # Export for upload-evidence.sh / any other tool that reads $DEVAUDIT_BASE_URL directly.
+          echo "DEVAUDIT_BASE_URL=${BASE%/}" >> "$GITHUB_ENV"
+
+      - name: Resolve current release
+        id: release
+        if: env.BOOTSTRAP_MODE != 'true'
+        run: |
+          DATE_PREFIX="v$(date +%Y.%m.%d)"
+          RESOLVE_URL="${BASE}/api/ci/releases/resolve?projectSlug=${PROJECT_SLUG}&versionPrefix=${DATE_PREFIX}"
+          # Retry: register-release in ci.yml may still be racing with us.
+          MAX_ATTEMPTS=6
+          WAIT_SECONDS=10
+          RESP=""
+          for ATTEMPT in $(seq 1 $MAX_ATTEMPTS); do
+            RESP=$(curl -s -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" "${RESOLVE_URL}")
+            VERSION=$(echo "$RESP" | jq -r '.latest.version // empty')
+            if [ -n "$VERSION" ]; then
+              break
+            fi
+            if [ "$ATTEMPT" -lt "$MAX_ATTEMPTS" ]; then
+              echo "Attempt ${ATTEMPT}/${MAX_ATTEMPTS}: no release for ${DATE_PREFIX} yet — waiting ${WAIT_SECONDS}s..."
+              sleep $WAIT_SECONDS
+            fi
+          done
+          VERSION=$(echo "$RESP" | jq -r '.latest.version // empty')
+          if [ -z "$VERSION" ]; then
+            echo "::error::No release found for ${DATE_PREFIX} after ${MAX_ATTEMPTS} attempts. Push to develop first to create the release."
+            exit 1
+          fi
+          RELEASE_ID=$(echo "$RESP" | jq -r '.latest.id')
+          STATUS=$(echo "$RESP" | jq -r '.latest.status')
+          APPROVED_SHA=$(echo "$RESP" | jq -r '.latestApprovedSha // empty')
+          echo "release_id=${RELEASE_ID}" >> "$GITHUB_OUTPUT"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "status=${STATUS}" >> "$GITHUB_OUTPUT"
+          echo "approved_sha=${APPROVED_SHA}" >> "$GITHUB_OUTPUT"
+          echo "Release ${VERSION} status: ${STATUS}"
+          case "$STATUS" in
+            uat_approved|prod_review|prod_approved|released)
+              echo "Release approval confirmed (status: ${STATUS})"
+              ;;
+            *)
+              echo "::error::Release ${VERSION} is '${STATUS}' — release approval required (have an authorised reviewer approve in DevAudit; in v1.22.x the backend status enum remains 'uat_approved')."
+              exit 1
+              ;;
+          esac
+
+      - name: Link PR to release
+        if: env.BOOTSTRAP_MODE != 'true' && github.event_name == 'pull_request'
+        run: |
+          RELEASE_ID="${{ steps.release.outputs.release_id }}"
+          PR_URL="${{ github.event.pull_request.html_url }}"
+          PR_NUMBER="${{ github.event.pull_request.number }}"
+          curl -s -o /dev/null -w "PR link: HTTP %{http_code}\n" \
+            -X PATCH "${BASE}/api/ci/releases/${RELEASE_ID}" \
+            -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+            -H "Content-Type: application/json" \
+            -d "{\"prInfo\":{\"url\":\"${PR_URL}\",\"number\":${PR_NUMBER}}}"
+          echo "Linked PR #${PR_NUMBER} to release ${RELEASE_ID}"
+
+      - name: Post release link on PR
+        if: env.BOOTSTRAP_MODE != 'true' && github.event_name == 'pull_request'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          VERSION="${{ steps.release.outputs.version }}"
+          RELEASE_ID="${{ steps.release.outputs.release_id }}"
+          COMPLY_URL="${BASE}/projects/${PROJECT_SLUG}/releases/${RELEASE_ID}"
+          BODY="**DevAudit Release:** [${VERSION}](${COMPLY_URL})"
+          EXISTING=$(gh pr view ${{ github.event.pull_request.number }} --json comments --jq '.comments[] | select(.body | startswith("**DevAudit Release:**")) | .id' | head -1)
+          if [ -n "$EXISTING" ]; then
+            gh api repos/${{ github.repository }}/issues/comments/${EXISTING} -X PATCH -f body="${BODY}" || true
+          else
+            gh pr comment ${{ github.event.pull_request.number }} --body "${BODY}" || true
+          fi
+
+      - name: SHA comparison
+        if: env.BOOTSTRAP_MODE != 'true' && github.event_name == 'pull_request'
+        run: |
+          PR_HEAD_SHA="${{ github.event.pull_request.head.sha }}"
+          APPROVED_SHA="${{ steps.release.outputs.approved_sha }}"
+          if [ -n "$APPROVED_SHA" ] && [ "$APPROVED_SHA" != "$PR_HEAD_SHA" ]; then
+            echo "::warning::Approved SHA (${APPROVED_SHA:0:8}) differs from PR HEAD (${PR_HEAD_SHA:0:8}). Code may have changed after approval."
+          fi
+
+      - name: Update PR status (workflow_dispatch re-trigger)
+        if: env.BOOTSTRAP_MODE != 'true' && github.event_name == 'workflow_dispatch'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          PR_DATA=$(gh pr list --base main --head develop --json headRefOid --limit 1 2>/dev/null || echo '[]')
+          PR_SHA=$(echo "$PR_DATA" | jq -r '.[0].headRefOid // empty' 2>/dev/null || true)
+          if [ -n "$PR_SHA" ]; then
+            gh api "repos/${{ github.repository }}/statuses/${PR_SHA}" \
+              -X POST \
+              -f state=success \
+              -f context="Release Approval Gate" \
+              -f description="DevAudit release approval confirmed" \
+              -f target_url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
+              || echo "Warning: Failed to post commit status"
+          else
+            echo "No open PR from develop to main found — skipping status update"
+          fi

package/sdlc/files/ci/ci-status-fallback.yml.template

@@ -0,0 +1,41 @@
+# CI Status Fallback — emits the 'Quality Gates' status on docs/compliance-only commits
+#
+# Generated by `devaudit install` / `devaudit update` from sdlc-config.json.
+# Do not edit manually — re-run the CLI (`devaudit update`) to regenerate.
+#
+# Why this exists:
+#   ci.yml uses `paths-ignore` to skip the heavy quality-gates job on docs/compliance-only
+#   commits. When such a commit is the HEAD of a develop→main PR, branch protection on
+#   main still requires the `Quality Gates` status check, so the PR sits in
+#   "Expected — Waiting for status to be reported" indefinitely.
+#
+#   This workflow fires on EXACTLY the paths ci.yml ignores, and emits a passing
+#   `Quality Gates` status. Branch protection is satisfied without running the heavy gates
+#   on a commit that has no code in it.
+#
+#   Mixed commits (some docs + some code) trigger BOTH workflows. Same status name, both
+#   green = branch protection happy.
+
+name: CI Status Fallback
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [develop]
+    paths:
+{{PATHS_IGNORE}}      - 'sdlc-config.json'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality-gates:
+    name: Quality Gates
+    runs-on: ubuntu-latest
+    steps:
+      - name: Acknowledge docs/compliance-only commit
+        run: |
+          echo "Commit ${{ github.sha }} only touches docs/compliance paths."
+          echo "Heavy quality-gates workflow (ci.yml) was correctly skipped."
+          echo "This fallback emits the 'Quality Gates' status so branch protection is satisfied."

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

@@ -0,0 +1,390 @@
+# CI Pipeline — all gates on every code push to develop
+#
+# Generated by `devaudit install` / `devaudit update` from sdlc-config.json.
+# Do not edit manually — re-run the CLI (`devaudit update`) to regenerate.
+#
+# Single consolidated job — on a self-hosted runner, parallel jobs run
+# sequentially anyway. One checkout + one cached npm ci = fast.
+#
+# PRs to main inherit commit status via branch protection.
+# Compliance validation runs separately on PRs (compliance-validation.yml).
+
+name: CI Pipeline
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [develop]
+    paths-ignore:
+{{PATHS_IGNORE}}      - 'sdlc-config.json'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ──────────────────────────────────────────────
+  # All quality gates in a single job — one checkout, cached installs
+  # ──────────────────────────────────────────────
+  quality-gates:
+    name: Quality Gates
+    runs-on: {{RUNNER}}
+
+    services:
+      {{DATABASE_SERVICE}}:
+        image: {{DATABASE_IMAGE}}
+        ports:
+          - {{DATABASE_PORT}}
+
+    env:
+{{DATABASE_ENV}}
+{{APP_ENV}}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # ── Cached installs (skip if already present on self-hosted runner) ──
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: {{NODE_VERSION}}
+
+      - name: Install dependencies (skip if lockfile unchanged)
+        run: |
+          LOCK_HASH=$(sha256sum package-lock.json | cut -d' ' -f1)
+          if [ -f node_modules/.lock-hash ] && [ "$(cat node_modules/.lock-hash)" = "$LOCK_HASH" ]; then
+            echo "node_modules up to date — skipping npm ci"
+          else
+            npm ci
+            echo "$LOCK_HASH" > node_modules/.lock-hash
+          fi
+
+      - name: Install Semgrep (skip if already installed)
+        run: |
+          VENV="$HOME/.semgrep-venv"
+          if [ -x "$VENV/bin/semgrep" ]; then
+            echo "Semgrep already installed"
+          else
+            python3 -m venv "$VENV"
+            "$VENV/bin/pip" install semgrep
+          fi
+          echo "$VENV/bin" >> "$GITHUB_PATH"
+
+      - name: Install Playwright (skip if already cached)
+        run: npx playwright install --with-deps chromium 2>/dev/null || npx playwright install chromium
+
+      # ── Gate 1: TypeScript ──
+
+      - name: TypeScript Check
+        run: npx tsc --noEmit
+
+      # ── Gate 2: SAST (Semgrep) ──
+
+      - name: SAST Scan
+        run: |
+          semgrep scan --config auto {{SOURCE_DIRS}} \
+            --severity ERROR --severity WARNING \
+            --json > sast-results.json 2>&1 || true
+          FINDINGS=$(python3 -c "
+          import json
+          with open('sast-results.json') as f:
+            data = json.load(f)
+          results = data.get('results', [])
+          print(len(results))
+          " 2>/dev/null || echo "0")
+          echo "SAST findings: $FINDINGS"
+          BASELINE={{SAST_BASELINE}}
+          if [ "$FINDINGS" -gt "$BASELINE" ]; then
+            echo "::error::New SAST findings ($FINDINGS > baseline $BASELINE)."
+            exit 1
+          fi
+
+      # ── Gate 3: Dependency Audit ──
+
+      - name: Dependency Audit
+        run: |
+          npm audit --json > dependency-audit.json 2>&1 || true
+          ACCEPTED="{{ACCEPTED_DEP_RISKS}}"
+          UNACCEPTED=$(python3 -c "
+          import json
+          with open('dependency-audit.json') as f:
+            data = json.load(f)
+          accepted = set('${ACCEPTED}'.split()) if '${ACCEPTED}' else set()
+          vulns = data.get('vulnerabilities', {})
+          issues = [name for name, v in vulns.items()
+                    if v.get('severity') in ('high', 'critical')
+                    and name not in accepted]
+          print(len(issues))
+          " 2>/dev/null || echo "unknown")
+          echo "Unaccepted high/critical: $UNACCEPTED"
+          if [ "$UNACCEPTED" != "0" ] && [ "$UNACCEPTED" != "unknown" ]; then
+            echo "::error::$UNACCEPTED unaccepted high/critical vulnerability(ies)."
+            exit 1
+          fi
+
+      # ── Gate 4: E2E Tests (Playwright) ──
+
+{{DATABASE_URI_STEP}}
+
+      - name: Kill stale dev server
+        run: lsof -ti:3000 | xargs kill -9 2>/dev/null || true
+
+      - name: Start dev server
+        run: {{E2E_START_COMMAND}} &
+
+      - name: Wait for dev server
+        run: npx wait-on http://localhost:3000 --timeout 120000
+
+      - name: E2E Tests
+        run: |
+          PLAYWRIGHT_HTML_REPORTER_OPEN=never npx playwright test --project={{E2E_PROJECT}} --reporter=json,html > e2e-results.json 2>/dev/null \
+            || PLAYWRIGHT_HTML_REPORTER_OPEN=never npx playwright test --project={{E2E_PROJECT}} --reporter=html
+
+      # ── Gate 5: Build ──
+
+      - name: Build Check
+        run: npm run build
+        env:
+{{BUILD_ENV}}
+
+      # ── Upload artifacts ──
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        continue-on-error: true
+        with:
+          name: ci-results
+          path: |
+            sast-results.json
+            dependency-audit.json
+            e2e-results.json
+            playwright-report/
+            coverage/coverage-summary.json
+          retention-days: 90
+
+  # ──────────────────────────────────────────────
+  # Register release early (parallel with gates) so UAT gate can find it
+  # ──────────────────────────────────────────────
+  register-release:
+    name: Register Release
+    runs-on: {{RUNNER}}
+    if: ${{ vars.DEVAUDIT_BASE_URL != '' }}
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    env:
+      DEVAUDIT_BASE_URL: ${{ vars.DEVAUDIT_BASE_URL }}
+      DEVAUDIT_API_KEY: ${{ secrets.DEVAUDIT_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate DevAudit env
+        run: |
+          if [ -z "${DEVAUDIT_BASE_URL}" ] || [ -z "${DEVAUDIT_API_KEY}" ]; then
+            echo "::error::DEVAUDIT_BASE_URL (variable) and DEVAUDIT_API_KEY (secret) must both be set."
+            exit 1
+          fi
+          echo "BASE=${DEVAUDIT_BASE_URL%/}" >> "$GITHUB_ENV"
+
+      - name: Determine release version
+        id: version
+        run: |
+          # Release identity is the REQ tag on the latest commit
+          # ([REQ-XXX] in subject, Ref: REQ-XXX in body), with a bare-date
+          # fallback for housekeeping commits. Both this workflow and
+          # compliance-evidence.yml call the same helper so a single
+          # feature converges on one release record. See DevAudit #310.
+          chmod +x scripts/derive-release-version.sh 2>/dev/null || true
+          VERSION=$(./scripts/derive-release-version.sh)
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Release version: ${VERSION}"
+
+      - name: Ensure release exists
+        run: |
+          chmod +x scripts/upload-evidence.sh 2>/dev/null || true
+          # Create the release in DevAudit (no evidence yet — just registration)
+          bash scripts/upload-evidence.sh \
+            {{PROJECT_SLUG}} _compliance-docs compliance_document README.md \
+            --release ${{ steps.version.outputs.version }} --create-release-if-missing \
+            --environment uat --category planning \
+            --git-sha ${{ github.sha }} --branch ${{ github.ref_name }} || true
+
+      - name: Sync known requirements from RTM
+        run: |
+          if [ -f "compliance/RTM.md" ]; then
+            REQS=$(grep -oP 'REQ-\d+' compliance/RTM.md | sort -t- -k2 -n -u)
+            if [ -n "$REQS" ]; then
+              JSON_ARRAY=$(echo "$REQS" | jq -R -s -c 'split("\n") | map(select(length > 0))')
+              HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
+                -X PATCH "${BASE}/api/ci/projects/{{PROJECT_SLUG}}/known-requirements" \
+                -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+                -H "Content-Type: application/json" \
+                -d "{\"requirements\": ${JSON_ARRAY}}")
+              echo "known_requirements sync: HTTP ${HTTP_CODE}"
+              echo "Synced $(echo "$REQS" | wc -w) requirements from RTM.md"
+            fi
+          fi
+
+  # ──────────────────────────────────────────────
+  # Upload Evidence to DevAudit (after gates pass)
+  # ──────────────────────────────────────────────
+  upload-evidence:
+    name: Upload Evidence
+    runs-on: {{RUNNER}}
+    needs: [quality-gates, register-release]
+    if: ${{ !failure() && !cancelled() && vars.DEVAUDIT_BASE_URL != '' }}
+    env:
+      DEVAUDIT_BASE_URL: ${{ vars.DEVAUDIT_BASE_URL }}
+      DEVAUDIT_API_KEY: ${{ secrets.DEVAUDIT_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download CI gate artifacts
+        uses: actions/download-artifact@v4
+        continue-on-error: true
+        with:
+          name: ci-results
+          path: ci-evidence/
+
+      - name: Generate and upload gate evidence
+        if: env.DEVAUDIT_BASE_URL != ''
+        run: |
+          chmod +x scripts/upload-evidence.sh 2>/dev/null || true
+          FLAGS="--git-sha ${{ github.sha }} --ci-run-id ${{ github.run_id }} --branch ${{ github.ref_name }}"
+          FLAGS="${FLAGS} --release ${{ needs.register-release.outputs.version }} --create-release-if-missing"
+          FLAGS="${FLAGS} --environment uat"
+
+          # Track failures across all uploads so we can fail the job at the
+          # end with the full picture. Previously each upload used
+          # `|| echo "Warning: ..."` which masked every error as a benign
+          # warning, letting broken releases ship without gate evidence
+          # (DevAudit #132).
+          UPLOAD_FAILURES=0
+          upload() {
+            local label="$1"; shift
+            echo "Uploading: ${label}"
+            if ! bash scripts/upload-evidence.sh "$@"; then
+              echo "::error::Failed to upload ${label}"
+              UPLOAD_FAILURES=$((UPLOAD_FAILURES + 1))
+            fi
+          }
+
+          # Re-generate gate evidence as fallback if artifact download failed
+          mkdir -p ci-evidence
+          if [ ! -f ci-evidence/sast-results.json ]; then
+            VENV="$HOME/.semgrep-venv"
+            if [ -x "$VENV/bin/semgrep" ]; then
+              "$VENV/bin/semgrep" scan --config auto {{SOURCE_DIRS}} --json > ci-evidence/sast-results.json 2>/dev/null || echo '{"results":[]}' > ci-evidence/sast-results.json
+            else
+              echo '{"results":[]}' > ci-evidence/sast-results.json
+            fi
+          fi
+          if [ ! -f ci-evidence/dependency-audit.json ]; then
+            npm audit --json > ci-evidence/dependency-audit.json 2>/dev/null || echo '{"vulnerabilities":{}}' > ci-evidence/dependency-audit.json
+          fi
+
+          # Upload SAST results (security_scan category)
+          if [ -f ci-evidence/sast-results.json ]; then
+            upload sast-results.json \
+              {{PROJECT_SLUG}} _compliance-docs audit_log ci-evidence/sast-results.json \
+              --category security_scan ${FLAGS}
+          fi
+
+          # Upload dependency audit (security_scan category)
+          if [ -f ci-evidence/dependency-audit.json ]; then
+            upload dependency-audit.json \
+              {{PROJECT_SLUG}} _compliance-docs audit_log ci-evidence/dependency-audit.json \
+              --category security_scan ${FLAGS}
+          fi
+
+          # Upload E2E test results (ci_pipeline category)
+          if [ -f ci-evidence/e2e-results.json ]; then
+            upload e2e-results.json \
+              {{PROJECT_SLUG}} _compliance-docs e2e_result ci-evidence/e2e-results.json \
+              --category ci_pipeline ${FLAGS}
+          fi
+
+          # Upload Playwright HTML report (test_report category)
+          if [ -d ci-evidence/playwright-report ]; then
+            (cd ci-evidence && zip -qr playwright-report.zip playwright-report/) 2>/dev/null || true
+            if [ -f ci-evidence/playwright-report.zip ]; then
+              upload playwright-report.zip \
+                {{PROJECT_SLUG}} _compliance-docs test_report ci-evidence/playwright-report.zip \
+                --category test_report ${FLAGS}
+            fi
+          fi
+
+          # Upload Jest coverage summary (test_report category)
+          if [ -f ci-evidence/coverage/coverage-summary.json ]; then
+            upload coverage-summary.json \
+              {{PROJECT_SLUG}} _compliance-docs test_report ci-evidence/coverage/coverage-summary.json \
+              --category test_report ${FLAGS}
+          fi
+
+          # Upload test summary report (test_report category)
+          if [ -f "compliance/test-summary-report.md" ]; then
+            upload test-summary-report.md \
+              {{PROJECT_SLUG}} _compliance-docs compliance_document compliance/test-summary-report.md \
+              --category test_report ${FLAGS}
+          fi
+
+          # Upload compliance docs (planning category)
+          for DOC in compliance/RTM.md compliance/test-plan.md compliance/test-cases.md; do
+            if [ -f "$DOC" ]; then
+              upload "$(basename "$DOC")" \
+                {{PROJECT_SLUG}} _compliance-docs compliance_document "$DOC" \
+                --category planning ${FLAGS}
+            fi
+          done
+
+          # Upload release tickets (pending only — approved releases are historical)
+          for DIR in compliance/pending-releases; do
+            if [ -d "$DIR" ]; then
+              for TICKET in "$DIR"/*.md; do
+                [ -f "$TICKET" ] || continue
+                upload "$(basename "$TICKET")" \
+                  {{PROJECT_SLUG}} _compliance-docs compliance_document "$TICKET" \
+                  --category release_artifact ${FLAGS}
+              done
+            fi
+          done
+
+          # Upload per-requirement evidence — scoped to requirements with a
+          # pending release ticket. Without this scoping every historical
+          # compliance/evidence/REQ-*/ folder would be re-uploaded on every
+          # run, re-populating the release-requirement matrix with the full
+          # project catalogue (DevAudit #133).
+          IN_SCOPE_REQS=()
+          if [ -d compliance/pending-releases ]; then
+            for TICKET in compliance/pending-releases/RELEASE-TICKET-REQ-*.md; do
+              [ -f "$TICKET" ] || continue
+              REQ_ID=$(basename "$TICKET" .md | sed 's/^RELEASE-TICKET-//')
+              IN_SCOPE_REQS+=("$REQ_ID")
+            done
+          fi
+
+          if [ ${#IN_SCOPE_REQS[@]} -eq 0 ]; then
+            echo "No pending release tickets found — skipping per-requirement evidence upload"
+          else
+            echo "In-scope requirements for this release: ${IN_SCOPE_REQS[*]}"
+            for REQ_ID in "${IN_SCOPE_REQS[@]}"; do
+              REQ_DIR="compliance/evidence/${REQ_ID}/"
+              if [ ! -d "$REQ_DIR" ]; then
+                echo "Warning: pending ticket for ${REQ_ID} but no ${REQ_DIR} on disk"
+                continue
+              fi
+              for ARTIFACT in "$REQ_DIR"*.md; do
+                [ -f "$ARTIFACT" ] || continue
+                upload "${REQ_ID}/$(basename "$ARTIFACT")" \
+                  {{PROJECT_SLUG}} "${REQ_ID}" compliance_document "$ARTIFACT" \
+                  --category planning ${FLAGS}
+              done
+            done
+          fi
+
+          if [ "$UPLOAD_FAILURES" -gt 0 ]; then
+            echo "::error::${UPLOAD_FAILURES} evidence upload(s) failed — release is missing gate evidence and cannot pass UAT review"
+            exit 1
+          fi
+
+      - name: Summary
+        run: echo "Evidence uploaded for ${{ needs.register-release.outputs.version }} (UAT)"