@metasession.co/devaudit-cli 0.1.1 → 0.1.3

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

@@ -0,0 +1,161 @@
+# Compliance Evidence Upload — triggers on compliance-only changes
+#
+# Generated by `devaudit install` / `devaudit update` from sdlc-config.json.
+# Do not edit manually — re-run the CLI (`devaudit update`) to regenerate.
+#
+# Uploads compliance docs to DevAudit without running quality gates.
+# Complements ci.yml which skips compliance-only pushes via paths-ignore.
+# In sdlc-v1.22.0+ this workflow is the load-bearing path for Stage 3
+# Step 9 (push-early): every commit on develop that touches compliance/
+# fires this and uploads to DevAudit immediately so destination breakage
+# (dead alias, missing token, schema drift) surfaces in seconds, not at
+# the end of Stage 3.
+#
+# Auth: project-scoped API key (uploader role). Issue from
+# DevAudit → Project Settings → API Keys. 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: Compliance Evidence Upload
+
+on:
+  push:
+    branches: [develop]
+    paths:
+      - 'compliance/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  upload-compliance-evidence:
+    name: Upload Compliance Evidence
+    runs-on: {{RUNNER}}
+    env:
+      DEVAUDIT_BASE_URL_VAR: ${{ vars.DEVAUDIT_BASE_URL }}
+      DEVAUDIT_API_KEY: ${{ secrets.DEVAUDIT_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Resolve DevAudit base URL
+        id: resolve
+        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 "::warning::No DevAudit base URL configured — skipping evidence upload. Set devaudit.base_url in sdlc-config.json."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if [ -z "${DEVAUDIT_API_KEY}" ]; then
+            echo "::warning::DEVAUDIT_API_KEY not set — skipping evidence upload."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            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 "skip=false" >> "$GITHUB_OUTPUT"
+              echo "BASE=${BASE%/}" >> "$GITHUB_ENV"
+              # Export for upload-evidence.sh, which reads $DEVAUDIT_BASE_URL directly.
+              echo "DEVAUDIT_BASE_URL=${BASE%/}" >> "$GITHUB_ENV"
+              ;;
+            *)
+              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
+
+      - name: Determine release version
+        id: version
+        if: steps.resolve.outputs.skip != 'true'
+        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
+          # ci.yml call the same helper so a single feature converges on
+          # one release record regardless of whether the push touched
+          # code or docs. 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: Upload compliance documents
+        if: steps.resolve.outputs.skip != 'true'
+        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 ${{ steps.version.outputs.version }} --create-release-if-missing"
+          FLAGS="${FLAGS} --environment uat"
+
+          # Upload compliance docs (planning category)
+          for DOC in compliance/RTM.md compliance/test-plan.md compliance/test-cases.md compliance/test-summary-report.md; do
+            if [ -f "$DOC" ]; then
+              echo "Uploading: $(basename "$DOC")"
+              bash scripts/upload-evidence.sh \
+                {{PROJECT_SLUG}} _compliance-docs compliance_document "$DOC" \
+                --category planning ${FLAGS} || echo "Warning: Failed to upload $(basename "$DOC")"
+            fi
+          done
+
+          # Upload release tickets (pending only)
+          if [ -d "compliance/pending-releases" ]; then
+            for TICKET in compliance/pending-releases/*.md; do
+              [ -f "$TICKET" ] || continue
+              echo "Uploading: $(basename "$TICKET")"
+              bash scripts/upload-evidence.sh \
+                {{PROJECT_SLUG}} _compliance-docs compliance_document "$TICKET" \
+                --category release_artifact ${FLAGS} || echo "Warning: Failed to upload $(basename "$TICKET")"
+            done
+          fi
+
+          # 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 #135, sibling of #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
+                echo "Uploading: ${REQ_ID}/$(basename "$ARTIFACT")"
+                bash scripts/upload-evidence.sh \
+                  {{PROJECT_SLUG}} "${REQ_ID}" compliance_document "$ARTIFACT" \
+                  --category planning ${FLAGS} || echo "Warning: Failed to upload $(basename "$ARTIFACT")"
+              done
+            done
+          fi
+
+      - name: Summary
+        run: echo "Compliance evidence uploaded for ${{ steps.version.outputs.version }}"

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

@@ -0,0 +1,34 @@
+# Compliance Validation — runs on PRs to main only
+#
+# Generated by `devaudit install` / `devaudit update` from sdlc-config.json.
+# Do not edit manually — re-run the CLI (`devaudit update`) to regenerate.
+#
+# Validates that compliance artifacts (test-scope, test-plan, RTM entries,
+# release tickets) are complete before merging to main. These artifacts are
+# built up progressively during development, so this check only makes sense
+# when the work is ready to merge — not on every push to develop.
+
+name: Compliance Validation
+
+on:
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  compliance-validation:
+    name: Compliance Validation
+    runs-on: {{RUNNER}}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Validate compliance artifacts
+        run: bash scripts/validate-compliance-artifacts.sh origin/main
+
+      - name: Validate commit conventions
+        run: bash scripts/validate-commits.sh origin/main

package/sdlc/files/ci/post-deploy-prod.yml.template

@@ -0,0 +1,159 @@
+# Post-deploy production verification (read-only)
+#
+# Generated by `devaudit install` / `devaudit update` from sdlc-config.json.
+# Do not edit manually — re-run the CLI (`devaudit update`) to regenerate.
+#
+# Production verification is READ-ONLY.
+# No E2E tests, no database operations, no API mutations.
+#
+# In sdlc-v1.22.0+ the terminal release status is configurable via
+# sdlc-config.json `production_review.terminal_status`:
+#   - "prod_review" (default, Option A) — stop at prod_review; human in the
+#     portal clicks "Approve Production" then "Mark as Released" for an
+#     explicit audit trail. Closes #138.
+#   - "released" (Option B) — preserves v1.21.x auto-release behaviour.
+
+name: Post-Deploy Production Evidence
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  production-evidence:
+    name: Production Evidence
+    runs-on: {{RUNNER}}
+    env:
+      DEVAUDIT_BASE_URL_VAR: ${{ vars.DEVAUDIT_BASE_URL }}
+      DEVAUDIT_API_KEY: ${{ secrets.DEVAUDIT_API_KEY }}
+      PROD_URL: ${{ secrets.{{PRODUCTION_URL_SECRET}} }}
+      PROJECT_SLUG: {{PROJECT_SLUG}}
+      GIT_SHA: ${{ github.sha }}
+      CI_RUN: ${{ github.run_id }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Resolve DevAudit base URL and post-deploy terminal status
+        run: |
+          # Prefer sdlc-config.json (visible in PR review) over repo Variable.
+          CONFIG_URL=""
+          TERMINAL_STATUS="prod_review"
+          if [ -f sdlc-config.json ]; then
+            CONFIG_URL=$(jq -r '.devaudit.base_url // empty' sdlc-config.json 2>/dev/null || true)
+            CONFIG_TERMINAL=$(jq -r '.production_review.terminal_status // empty' sdlc-config.json 2>/dev/null || true)
+            if [ -n "$CONFIG_TERMINAL" ]; then
+              TERMINAL_STATUS="$CONFIG_TERMINAL"
+            fi
+          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."
+          else
+            echo "::error::No DevAudit base URL configured. Set devaudit.base_url in sdlc-config.json."
+            exit 1
+          fi
+          if [ -z "${DEVAUDIT_API_KEY}" ]; then
+            echo "::error::DEVAUDIT_API_KEY secret must be set."
+            exit 1
+          fi
+          case "$TERMINAL_STATUS" in
+            prod_review|released) ;;
+            *)
+              echo "::error::Invalid production_review.terminal_status '${TERMINAL_STATUS}'. Must be 'prod_review' or 'released'."
+              exit 1
+              ;;
+          esac
+          echo "Post-deploy terminal status: ${TERMINAL_STATUS}"
+          echo "BASE=${BASE%/}" >> "$GITHUB_ENV"
+          # Export for upload-evidence.sh, which reads $DEVAUDIT_BASE_URL directly.
+          echo "DEVAUDIT_BASE_URL=${BASE%/}" >> "$GITHUB_ENV"
+          echo "TERMINAL_STATUS=${TERMINAL_STATUS}" >> "$GITHUB_ENV"
+
+      - name: Resolve current release
+        id: release
+        run: |
+          DATE_PREFIX="v$(date +%Y.%m.%d)"
+          RESP=$(curl -s -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+            "${BASE}/api/ci/releases/resolve?projectSlug=${PROJECT_SLUG}&versionPrefix=${DATE_PREFIX}")
+          VERSION=$(echo "$RESP" | jq -r '.latest.version // empty')
+          if [ -z "$VERSION" ]; then
+            VERSION="${DATE_PREFIX}"
+          fi
+          RELEASE_ID=$(echo "$RESP" | jq -r '.latest.id // empty')
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "release_id=${RELEASE_ID}" >> "$GITHUB_OUTPUT"
+          echo "Release version: ${VERSION}"
+
+      - name: Wait for production deployment
+        run: |
+          for i in $(seq 1 30); do
+            HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" "${PROD_URL}/" || echo "000")
+            if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 400 ]; then
+              echo "Production is up (HTTP ${HTTP_CODE})"
+              break
+            fi
+            echo "Attempt ${i}/30: HTTP ${HTTP_CODE} — waiting 10s..."
+            sleep 10
+          done
+
+      - name: Production smoke tests (read-only)
+        run: |
+          echo "=== Production Smoke Tests ==="
+          HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" "${PROD_URL}/")
+          echo "Health check: HTTP ${HTTP_CODE}"
+          if [ "$HTTP_CODE" -lt 200 ] || [ "$HTTP_CODE" -ge 400 ]; then
+            echo "::error::Production health check failed"
+            exit 1
+          fi
+          curl -s -I "${PROD_URL}/" | grep -iE 'x-frame-options|x-content-type|strict-transport|content-security' || true
+          echo "=== Smoke Tests Passed ==="
+          cat > prod-smoke-results.json << RESULTS_EOF
+          {
+            "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+            "production_url": "${PROD_URL}",
+            "git_sha": "${GIT_SHA}",
+            "tests": [
+              {"name": "health_check", "status": "passed"},
+              {"name": "security_headers", "status": "checked"}
+            ]
+          }
+          RESULTS_EOF
+
+      - name: Upload production evidence
+        run: |
+          chmod +x scripts/upload-evidence.sh 2>/dev/null || true
+          VERSION="${{ steps.release.outputs.version }}"
+          FLAGS="--release ${VERSION} --create-release-if-missing --environment production --category test_report"
+          FLAGS="${FLAGS} --git-sha ${GIT_SHA} --ci-run-id ${CI_RUN} --branch main"
+          if [ -f prod-smoke-results.json ]; then
+            bash scripts/upload-evidence.sh \
+              "${PROJECT_SLUG}" "_compliance-docs" "test_report" prod-smoke-results.json \
+              ${FLAGS} || echo "Warning: Failed to upload smoke results"
+          fi
+
+      - name: Advance release status (post-deploy)
+        run: |
+          RELEASE_ID="${{ steps.release.outputs.release_id }}"
+          if [ -z "$RELEASE_ID" ]; then
+            echo "::warning::No release_id resolved — skipping status patch"
+            exit 0
+          fi
+          curl -s -o /dev/null -w "Release status patch: HTTP %{http_code}\n" \
+            -X PATCH "${BASE}/api/ci/releases/${RELEASE_ID}" \
+            -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+            -H "Content-Type: application/json" \
+            -d "{\"status\":\"${TERMINAL_STATUS}\"}"
+          case "$TERMINAL_STATUS" in
+            prod_review)
+              echo "Release ${{ steps.release.outputs.version }} → prod_review."
+              echo "Next: a human in the portal clicks 'Approve Production' (→ prod_approved), then 'Mark as Released' (→ released)."
+              echo "Audit trail captures both events with reviewer identity per compliance/risk-register.md."
+              ;;
+            released)
+              echo "Release ${{ steps.release.outputs.version }} → released (Option B: auto-release with no post-deploy human gate)."
+              ;;
+          esac

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

@@ -0,0 +1,335 @@
+# CI Pipeline — all gates on every code push to develop (Python stack)
+#
+# Generated by `devaudit install` / `devaudit update` from sdlc-config.json + stacks/python/adapter.json.
+# Do not edit manually — re-run the CLI (`devaudit update`) to regenerate.
+#
+# Single consolidated job. Order: install → ruff → mypy → semgrep → pip-audit → pytest → build.
+#
+# 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:
+  quality-gates:
+    name: Quality Gates
+    runs-on: {{RUNNER}}
+
+    # `working-directory` lets monorepo / subdir Python projects (e.g. META-AGENT
+    # with mission-control-api/pyproject.toml) run gates from the right place
+    # without prefixing every command. Defaults to '.' (repo root) when
+    # sdlc-config.json doesn't set working_directory.
+    defaults:
+      run:
+        working-directory: {{WORKING_DIRECTORY}}
+
+    services:
+      {{DATABASE_SERVICE}}:
+        image: {{DATABASE_IMAGE}}
+        ports:
+          - {{DATABASE_PORT}}
+
+    env:
+{{DATABASE_ENV}}
+{{APP_ENV}}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '{{PYTHON_VERSION}}'
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pip install semgrep pip-audit build
+
+      # ── Gate 1: Lint + format (ruff) ──
+
+      - name: Ruff lint
+        run: ruff check {{SOURCE_DIRS}}
+
+      - name: Ruff format check
+        run: ruff format --check {{SOURCE_DIRS}}
+
+      # ── Gate 2: Type check (mypy --strict) ──
+
+      - name: Type Check (mypy)
+        run: mypy {{SOURCE_DIRS}}
+
+      # ── Gate 3: SAST (Semgrep) ──
+
+      - name: SAST Scan
+        run: |
+          mkdir -p ci-evidence
+          semgrep scan --config auto {{SOURCE_DIRS}} \
+            --severity ERROR --severity WARNING \
+            --json > ci-evidence/sast-results.json 2>&1 || true
+          FINDINGS=$(python3 -c "
+          import json
+          with open('ci-evidence/sast-results.json') as f:
+            data = json.load(f)
+          print(len(data.get('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 4: Dependency Audit (pip-audit) ──
+
+      - name: Dependency Audit
+        run: |
+          mkdir -p ci-evidence
+          pip-audit --format=json > ci-evidence/dependency-audit.json 2>&1 || true
+          ACCEPTED="{{ACCEPTED_DEP_RISKS}}"
+          UNACCEPTED=$(python3 -c "
+          import json
+          with open('ci-evidence/dependency-audit.json') as f:
+            data = json.load(f)
+          accepted = set('${ACCEPTED}'.split()) if '${ACCEPTED}' else set()
+          deps = data.get('dependencies', []) if isinstance(data, dict) else data
+          issues = []
+          for dep in deps:
+            name = dep.get('name', '') if isinstance(dep, dict) else ''
+            vulns = dep.get('vulns', []) if isinstance(dep, dict) else []
+            if vulns and name and name not in accepted:
+              issues.append(name)
+          print(len(issues))
+          " 2>/dev/null || echo "unknown")
+          echo "Unaccepted vulnerable packages: $UNACCEPTED"
+          if [ "$UNACCEPTED" != "0" ] && [ "$UNACCEPTED" != "unknown" ]; then
+            echo "::error::$UNACCEPTED unaccepted vulnerable package(s)."
+            exit 1
+          fi
+
+      # ── Gate 5: Tests (pytest) ──
+
+{{DATABASE_URI_STEP}}
+
+      - name: Tests
+        run: |
+          mkdir -p ci-evidence
+          pytest --junit-xml=ci-evidence/junit.xml --tb=short
+
+      # ── Gate 6: Build ──
+
+      - name: Build Check
+        run: python -m build --sdist --wheel
+        env:
+{{BUILD_ENV}}
+
+      # ── Upload artifacts ──
+
+      # actions/upload-artifact@v4 doesn't honour the job's `working-directory`;
+      # paths are workspace-relative. Prefix with WORKING_DIR_PREFIX so artifacts
+      # uploaded from a subdir project (e.g. mission-control-api/) include the
+      # subdir in their stored path, matching where the gate steps wrote them.
+      - uses: actions/upload-artifact@v4
+        if: always()
+        continue-on-error: true
+        with:
+          name: ci-results
+          path: |
+            {{WORKING_DIR_PREFIX}}ci-evidence/sast-results.json
+            {{WORKING_DIR_PREFIX}}ci-evidence/dependency-audit.json
+            {{WORKING_DIR_PREFIX}}ci-evidence/junit.xml
+            {{WORKING_DIR_PREFIX}}dist/
+          retention-days: 90
+
+  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: |
+          DATE_PREFIX="v$(date +%Y.%m.%d)"
+          RESP=$(curl -s -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+            "${BASE}/api/ci/releases/resolve?projectSlug={{PROJECT_SLUG}}&versionPrefix=${DATE_PREFIX}")
+          VERSION=$(echo "$RESP" | jq -r '.nextSequenceVersion // empty')
+          if [ -z "$VERSION" ]; then
+            VERSION="${DATE_PREFIX}"
+          fi
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Release version: ${VERSION}"
+
+      - name: Ensure release exists
+        run: |
+          chmod +x scripts/upload-evidence.sh 2>/dev/null || true
+          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:
+    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
+
+      # Download to workspace root: upload-artifact@v4 preserves the file's
+      # workspace-relative path (e.g. mission-control-api/ci-evidence/sast.json
+      # for a subdir project). Downloading with path: '.' restores files to
+      # those exact paths so the upload-evidence.sh references below resolve
+      # without nesting.
+      - name: Download CI gate artifacts
+        uses: actions/download-artifact@v4
+        continue-on-error: true
+        with:
+          name: ci-results
+          path: .
+
+      - 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"
+
+          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
+          }
+
+          mkdir -p {{WORKING_DIR_PREFIX}}ci-evidence
+
+          if [ -f {{WORKING_DIR_PREFIX}}ci-evidence/sast-results.json ]; then
+            upload sast-results.json \
+              {{PROJECT_SLUG}} _compliance-docs audit_log {{WORKING_DIR_PREFIX}}ci-evidence/sast-results.json \
+              --category security_scan ${FLAGS}
+          fi
+
+          if [ -f {{WORKING_DIR_PREFIX}}ci-evidence/dependency-audit.json ]; then
+            upload dependency-audit.json \
+              {{PROJECT_SLUG}} _compliance-docs audit_log {{WORKING_DIR_PREFIX}}ci-evidence/dependency-audit.json \
+              --category security_scan ${FLAGS}
+          fi
+
+          # pytest junit.xml is the Python equivalent of e2e-results.json — same `e2e_result` evidence type
+          if [ -f {{WORKING_DIR_PREFIX}}ci-evidence/junit.xml ]; then
+            upload junit.xml \
+              {{PROJECT_SLUG}} _compliance-docs e2e_result {{WORKING_DIR_PREFIX}}ci-evidence/junit.xml \
+              --category ci_pipeline ${FLAGS}
+          fi
+
+          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
+
+          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
+
+          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
+
+          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)"