@metasession.co/devaudit-cli 0.3.8 → 0.3.10

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

@@ -0,0 +1,593 @@
+#!/usr/bin/env bash
+# @requirement REQ-007 - CLI upload script for CI pipelines
+# @requirement REQ-020 - Extended with release/environment/category flags
+# @requirement REQ-XXX - #224: posts to META-COMPLY's API instead of Supabase
+#
+# Usage:
+#   ./scripts/upload-evidence.sh <project-slug> <requirement-id> <evidence-type> <file-or-directory>
+#
+# Optional flags:
+#   --git-sha <sha>             Git commit SHA
+#   --ci-run-id <id>            CI run identifier
+#   --branch <branch>           Git branch name
+#   --release <version>         Release version (e.g. v1.0.0). The route
+#                               resolves it to a release UUID server-side.
+#   --create-release-if-missing Auto-create the release as 'draft' if absent
+#   --environment <env>         Environment: uat or production
+#   --category <cat>            Evidence category: ci_pipeline, local_dev,
+#                               planning, test_report, security_scan,
+#                               release_artifact
+#   --release-title <text>      Human title for the release row (e.g. the
+#                               release-ticket H1). Forwarded as
+#                               `releaseTitle`; the portal no-clobbers
+#                               existing non-null values.
+#   --release-summary <text>    Reviewer-facing short description of what
+#                               the release covers. Forwarded as
+#                               `releaseSummary`; the portal no-clobbers
+#                               existing non-null values.
+#                               DevAudit-Installer#285.
+#   --change-type <type>        Conventional-commit prefix (feat / fix /
+#                               refactor / perf / chore / docs / ci /
+#                               build / test / compliance / revert) for
+#                               the release row. Unknown values are
+#                               silently dropped server-side.
+#   --gate-status <status>      `passed` / `failed` / `skipped`. Lets the
+#                               portal distinguish a gate that ran-and-
+#                               failed from one that never ran. Forwarded
+#                               as `gateStatus`; unknown values are
+#                               silently dropped server-side.
+#                               DevAudit-Installer#96.
+#   --sdlc-stage <1-5>          SDLC stage that produced this artefact:
+#                               1 plan, 2 implement/test, 3 compile-evidence,
+#                               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).
+#
+# Required environment variables:
+#   DEVAUDIT_BASE_URL  e.g. https://meta-comply-production.up.railway.app
+#   DEVAUDIT_API_KEY   project-scoped API key (uploader role); format `mc_…`.
+#                         Issue from: Project Settings → API Keys in
+#                         META-COMPLY's web UI.
+#
+# Large-file uploads (>=25MB):
+#   Files above 25MB use a presigned R2 upload flow (3-step: request URL →
+#   PUT to R2 → notify portal) instead of multipart POST. This requires
+#   the Portal to be configured with R2 evidence storage
+#   (R2_EVIDENCE_BUCKET and related env vars). If R2 is not configured,
+#   the Portal returns a clear error which is surfaced to the operator.
+#   #298 — the Portal response body is included in the error output.
+#
+# Examples:
+#   ./scripts/upload-evidence.sh meta-ats REQ-001 screenshot \
+#       compliance/evidence/REQ-001/screenshots/
+#   ./scripts/upload-evidence.sh meta-ats _compliance-docs compliance_document \
+#       compliance/RTM.md --git-sha abc123
+#   ./scripts/upload-evidence.sh meta-ats REQ-001 e2e_result \
+#       playwright-report/ --release v1.0.0 --environment uat \
+#       --category ci_pipeline --create-release-if-missing
+
+set -euo pipefail
+
+# --- Parse arguments ---
+if [ "$#" -lt 4 ]; then
+  echo "Usage: $0 <project-slug> <requirement-id> <evidence-type> <file-or-directory> [flags…]"
+  exit 1
+fi
+
+PROJECT_SLUG="$1"
+REQUIREMENT_ID="$2"
+EVIDENCE_TYPE="$3"
+FILE_PATH="$4"
+shift 4
+
+GIT_SHA=""
+CI_RUN_ID=""
+BRANCH=""
+RELEASE_VERSION=""
+CREATE_RELEASE_IF_MISSING=false
+ENVIRONMENT=""
+EVIDENCE_CATEGORY=""
+RELEASE_TITLE=""
+RELEASE_SUMMARY=""
+CHANGE_TYPE=""
+GATE_STATUS=""
+SDLC_STAGE=""
+TEST_CYCLE=""
+# Repeatable `--meta-key key=value` accumulator. Each pair gets merged
+# into the metadata JSON sent to the portal. Used by the screenshot
+# upload loop to pass `origin=feature|regression` from the per-PNG
+# sidecar JSON written by the evidenceShot helper.
+META_KEYS=()
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --git-sha) GIT_SHA="$2"; shift 2 ;;
+    --ci-run-id) CI_RUN_ID="$2"; shift 2 ;;
+    --branch) BRANCH="$2"; shift 2 ;;
+    --release) RELEASE_VERSION="$2"; shift 2 ;;
+    --create-release-if-missing) CREATE_RELEASE_IF_MISSING=true; shift ;;
+    --environment) ENVIRONMENT="$2"; shift 2 ;;
+    --category) EVIDENCE_CATEGORY="$2"; shift 2 ;;
+    # Descriptive title + conventional-commit change type passed through to
+    # the portal's findOrCreateRelease no-clobber backfill. Both optional;
+    # unknown change-type values are dropped server-side, not 400'd.
+    --release-title) RELEASE_TITLE="$2"; shift 2 ;;
+    --release-summary) RELEASE_SUMMARY="$2"; shift 2 ;;
+    --change-type) CHANGE_TYPE="$2"; shift 2 ;;
+    # passed/failed/skipped — surfaces failed gates on the portal so
+    # ran-and-failed != never-ran. Unknown values dropped server-side.
+    # DevAudit-Installer#96.
+    --gate-status) GATE_STATUS="$2"; shift 2 ;;
+    --sdlc-stage) SDLC_STAGE="$2"; shift 2 ;;
+    --test-cycle) TEST_CYCLE="$2"; shift 2 ;;
+    # --meta-key key=value (repeatable). Merged into the metadata JSON
+    # before posting. Validates the `key=value` shape; rejects bare
+    # keys without `=`.
+    --meta-key)
+      if [[ "$2" != *=* ]]; then
+        echo "Error: --meta-key requires key=value (got: $2)"
+        exit 1
+      fi
+      META_KEYS+=("$2")
+      shift 2
+      ;;
+    *) echo "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+if [ -n "$ENVIRONMENT" ] && [ -z "$RELEASE_VERSION" ]; then
+  echo "Error: --environment requires --release (evidence without a release is orphaned)"
+  exit 1
+fi
+if [ -n "$RELEASE_VERSION" ] && [ -z "$EVIDENCE_CATEGORY" ]; then
+  echo "Error: --category is required when --release is specified (gate validation)"
+  exit 1
+fi
+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 [ -z "${DEVAUDIT_BASE_URL:-}" ]; then
+  echo "Error: DEVAUDIT_BASE_URL environment variable is required"
+  exit 1
+fi
+if [ -z "${DEVAUDIT_API_KEY:-}" ]; then
+  echo "Error: DEVAUDIT_API_KEY environment variable is required (issue from"
+  echo "       Project Settings → API Keys in META-COMPLY)"
+  exit 1
+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
+# json-escaped (quotes + backslashes).
+json_escape() {
+  printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g'
+}
+META_ENTRIES=()
+[ -n "$GIT_SHA" ] && META_ENTRIES+=("\"gitSha\":\"$(json_escape "$GIT_SHA")\"")
+[ -n "$CI_RUN_ID" ] && META_ENTRIES+=("\"ciRunId\":\"$(json_escape "$CI_RUN_ID")\"")
+[ -n "$BRANCH" ] && META_ENTRIES+=("\"branch\":\"$(json_escape "$BRANCH")\"")
+for KV in "${META_KEYS[@]}"; do
+  KEY="${KV%%=*}"
+  VAL="${KV#*=}"
+  META_ENTRIES+=("\"$(json_escape "$KEY")\":\"$(json_escape "$VAL")\"")
+done
+if [ "${#META_ENTRIES[@]}" -gt 0 ]; then
+  IFS=','
+  METADATA="{${META_ENTRIES[*]}}"
+  unset IFS
+else
+  METADATA="{}"
+fi
+
+# --- Collect files ---
+FILES=()
+if [ -d "$FILE_PATH" ]; then
+  while IFS= read -r -d '' f; do
+    FILES+=("$f")
+  done < <(find "$FILE_PATH" -type f -print0)
+else
+  FILES=("$FILE_PATH")
+fi
+if [ ${#FILES[@]} -eq 0 ]; then
+  echo "Error: No files found at $FILE_PATH"
+  exit 1
+fi
+
+# --- Upload each file via /api/evidence/upload ---
+#
+# Retry-on-429 / 5xx: consumer CI workflows fire 8-12 sequential uploads per
+# requirement (test-scope, test-plan, implementation-plan, security-summary,
+# test-execution-summary, ai-prompts, ai-use-note, uat-checklist, gates/*.json).
+# That cadence trips DevAudit's per-IP rate limiter, marking otherwise-green
+# CI runs as failed. Retry transiently with exponential backoff (1s → 16s),
+# honouring Retry-After if the portal supplies it. Auth/validation errors
+# (4xx other than 429) still fail fast — they won't fix themselves.
+#
+# Issue: devaudit#263.
+SUCCEEDED=0
+FAILED=0
+# devaudit#133 — central stub guard. Any file still carrying the
+# DevAudit starter banner ("STARTER TEMPLATE — REPLACE BEFORE
+# COMMITTING" / "...BEFORE GOING TO PRODUCTION" — both phrasings)
+# is skipped before the upload attempt so unedited placeholders
+# can't flip a clause to COVERED off a stub. The check is binary-
+# safe (-a) so it doesn't choke on PNGs or other non-text files.
+SKIPPED=0
+TOTAL_SIZE=0
+UPLOAD_URL="${DEVAUDIT_BASE_URL}/api/evidence/upload"
+MAX_ATTEMPTS=${UPLOAD_MAX_ATTEMPTS:-5}
+INITIAL_BACKOFF_SECONDS=${UPLOAD_INITIAL_BACKOFF_SECONDS:-1}
+UPLOAD_CONNECT_TIMEOUT_SECONDS=${UPLOAD_CONNECT_TIMEOUT_SECONDS:-10}
+UPLOAD_MAX_TIME_SECONDS=${UPLOAD_MAX_TIME_SECONDS:-120}
+# DevAudit-Installer#189 — files above this size use the presigned R2 URL
+# upload flow (3-step: request URL → PUT to R2 → notify portal) instead of
+# the multipart POST. Avoids the portal's FormData body parser limit.
+# 25MB = 26214400 bytes.
+PRESIGNED_THRESHOLD_BYTES=${PRESIGNED_THRESHOLD:-26214400}
+PRESIGNED_MAX_ATTEMPTS=${PRESIGNED_MAX_ATTEMPTS:-3}
+PRESIGNED_UPLOAD_MAX_TIME_SECONDS=${PRESIGNED_UPLOAD_MAX_TIME_SECONDS:-300}
+
+is_unedited_starter_stub() {
+  # Match BOTH banner phrasings the SDLC has shipped (v0.1.36 changed
+  # the wording from "...GOING TO PRODUCTION" to "...COMMITTING").
+  # -a forces binary→text so we don't error on PNGs/PDFs; the regex
+  # won't match either of those formats by accident.
+  grep -aqE 'STARTER TEMPLATE.+REPLACE BEFORE' "$1"
+}
+
+# DevAudit-Installer#189 — Presigned R2 URL upload for large files (>25MB).
+# 3-step flow: (1) request presigned URL from portal, (2) PUT file to R2,
+# (3) notify portal that upload is complete. Each step retries on 429/5xx
+# and connection errors. Returns 0 on success, 1 on failure.
+upload_presigned() {
+  local file="$1"
+  local filename
+  filename=$(basename "$file")
+  local file_size
+  file_size=$(stat -c%s "$file" 2>/dev/null || stat -f%z "$file")
+
+  # Derive a MIME type from the extension (best-effort).
+  local mime_type="application/octet-stream"
+  case "$filename" in
+    *.zip)  mime_type="application/zip" ;;
+    *.json) mime_type="application/json" ;;
+    *.png)  mime_type="image/png" ;;
+    *.pdf)  mime_type="application/pdf" ;;
+    *.md)   mime_type="text/markdown" ;;
+    *.html) mime_type="text/html" ;;
+  esac
+
+  local presign_url="${DEVAUDIT_BASE_URL}/api/evidence/upload-url"
+  local complete_url="${DEVAUDIT_BASE_URL}/api/evidence/upload-complete"
+
+  # --- Step 1: Request presigned upload URL ---
+  local attempt backoff http_code curl_exit resp_body upload_url evidence_id
+  attempt=1
+  backoff=$INITIAL_BACKOFF_SECONDS
+  upload_url=""
+  evidence_id=""
+  while [ "$attempt" -le "$PRESIGNED_MAX_ATTEMPTS" ]; do
+    resp_body=$(mktemp)
+    http_code=$(curl -s -o "$resp_body" -w "%{http_code}" \
+      -X POST -L --max-redirs 3 \
+      --connect-timeout "$UPLOAD_CONNECT_TIMEOUT_SECONDS" \
+      --max-time "$UPLOAD_MAX_TIME_SECONDS" \
+      "$presign_url" \
+      -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+      -H "Content-Type: application/json" \
+      -d "{
+        \"projectSlug\": \"${PROJECT_SLUG}\",
+        \"requirementId\": \"${REQUIREMENT_ID}\",
+        \"evidenceType\": \"${EVIDENCE_TYPE}\",
+        \"fileName\": \"${filename}\",
+        \"fileSizeBytes\": ${file_size},
+        \"mimeType\": \"${mime_type}\",
+        \"metadata\": ${METADATA},
+        \"releaseVersion\": \"${RELEASE_VERSION}\",
+        \"createReleaseIfMissing\": \"${CREATE_RELEASE_IF_MISSING}\",
+        \"releaseBranch\": \"${BRANCH}\",
+        \"environment\": \"${ENVIRONMENT}\",
+        \"evidenceCategory\": \"${EVIDENCE_CATEGORY}\",
+        \"releaseTitle\": \"${RELEASE_TITLE}\",
+        \"releaseSummary\": \"${RELEASE_SUMMARY}\",
+        \"sdlcStage\": \"${SDLC_STAGE}\",
+        \"testCycleId\": \"${TEST_CYCLE}\"
+      }") || curl_exit=$?
+    curl_exit=${curl_exit:-0}
+    if [ "$curl_exit" -eq 0 ] && [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
+      upload_url=$(jq -r '.uploadUrl // empty' "$resp_body" 2>/dev/null || true)
+      evidence_id=$(jq -r '.evidenceId // empty' "$resp_body" 2>/dev/null || true)
+      rm -f "$resp_body"
+      if [ -n "$upload_url" ] && [ -n "$evidence_id" ] && [ "$upload_url" != "null" ] && [ "$evidence_id" != "null" ]; then
+        break
+      fi
+      # Portal responded 2xx but didn't return presigned URL fields —
+      # presigned URL flow not configured. Fall back to multipart.
+      echo -n "(portal did not return presigned URL, falling back to multipart) "
+      return 255
+    fi
+    if [ "$curl_exit" -ne 0 ] || [ "$http_code" = "429" ] || { [ "$http_code" -ge 500 ] && [ "$http_code" -lt 600 ]; }; then
+      if [ "$attempt" -lt "$PRESIGNED_MAX_ATTEMPTS" ]; then
+        rm -f "$resp_body"
+        echo -n "(step 1: HTTP ${http_code}, retry in ${backoff}s) "
+        sleep "$backoff"
+        attempt=$((attempt + 1))
+        backoff=$((backoff * 2))
+        continue
+      fi
+    fi
+    # Non-retriable error (4xx other than 429) or exhausted retries.
+    # #298 — Surface the Portal response body so operators see WHY it
+    # failed (e.g. "Presigned uploads require R2 storage configuration")
+    # instead of just "HTTP 501". Include up to 500 chars of the body.
+    local err_excerpt=""
+    if [ -s "$resp_body" ]; then
+      err_excerpt=$(head -c 500 "$resp_body")
+    fi
+    rm -f "$resp_body"
+    echo -n "(step 1 failed: HTTP ${http_code}"
+    if [ -n "$err_excerpt" ]; then
+      echo -n " — ${err_excerpt}"
+    fi
+    echo ") "
+    return 1
+  done
+
+  if [ -z "$upload_url" ] || [ -z "$evidence_id" ]; then
+    echo -n "(step 1: no presigned URL after ${attempt} attempts) "
+    return 1
+  fi
+
+  # --- Step 2: Upload directly to R2 via presigned URL ---
+  attempt=1
+  backoff=$INITIAL_BACKOFF_SECONDS
+  while [ "$attempt" -le "$PRESIGNED_MAX_ATTEMPTS" ]; do
+    http_code=$(curl -s -o /dev/null -w "%{http_code}" \
+      -X PUT \
+      -H "Content-Type: ${mime_type}" \
+      --connect-timeout "$UPLOAD_CONNECT_TIMEOUT_SECONDS" \
+      --max-time "$PRESIGNED_UPLOAD_MAX_TIME_SECONDS" \
+      --data-binary @"$file" \
+      "$upload_url") || curl_exit=$?
+    curl_exit=${curl_exit:-0}
+    if [ "$curl_exit" -eq 0 ] && [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
+      break
+    fi
+    if [ "$curl_exit" -ne 0 ] || [ "$http_code" = "429" ] || { [ "$http_code" -ge 500 ] && [ "$http_code" -lt 600 ]; }; then
+      if [ "$attempt" -lt "$PRESIGNED_MAX_ATTEMPTS" ]; then
+        echo -n "(step 2: HTTP ${http_code}, retry in ${backoff}s) "
+        sleep "$backoff"
+        attempt=$((attempt + 1))
+        backoff=$((backoff * 2))
+        continue
+      fi
+    fi
+    echo -n "(step 2 failed: HTTP ${http_code}) "
+    return 1
+  done
+
+  # --- Step 3: Notify portal that upload is complete ---
+  attempt=1
+  backoff=$INITIAL_BACKOFF_SECONDS
+  while [ "$attempt" -le "$PRESIGNED_MAX_ATTEMPTS" ]; do
+    http_code=$(curl -s -o /dev/null -w "%{http_code}" \
+      -X POST -L --max-redirs 3 \
+      --connect-timeout "$UPLOAD_CONNECT_TIMEOUT_SECONDS" \
+      --max-time "$UPLOAD_MAX_TIME_SECONDS" \
+      "$complete_url" \
+      -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+      -H "Content-Type: application/json" \
+      -d "{\"evidenceId\": \"${evidence_id}\"}") || curl_exit=$?
+    curl_exit=${curl_exit:-0}
+    if [ "$curl_exit" -eq 0 ] && [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
+      return 0
+    fi
+    if [ "$curl_exit" -ne 0 ] || [ "$http_code" = "429" ] || { [ "$http_code" -ge 500 ] && [ "$http_code" -lt 600 ]; }; then
+      if [ "$attempt" -lt "$PRESIGNED_MAX_ATTEMPTS" ]; then
+        echo -n "(step 3: HTTP ${http_code}, retry in ${backoff}s) "
+        sleep "$backoff"
+        attempt=$((attempt + 1))
+        backoff=$((backoff * 2))
+        continue
+      fi
+    fi
+    echo -n "(step 3 failed: HTTP ${http_code}) "
+    return 1
+  done
+  return 1
+}
+
+for FILE in "${FILES[@]}"; do
+  FILENAME=$(basename "$FILE")
+  if is_unedited_starter_stub "$FILE"; then
+    echo "SKIPPED ${FILENAME} — unedited starter stub (replace the STARTER TEMPLATE banner to upload)"
+    SKIPPED=$((SKIPPED + 1))
+    continue
+  fi
+  FILE_SIZE=$(stat -c%s "$FILE" 2>/dev/null || stat -f%z "$FILE")
+  echo -n "Uploading ${FILENAME}... "
+
+  # DevAudit-Installer#189 — large files use the presigned R2 URL flow
+  # to bypass the portal's multipart body parser limit. If the portal
+  # doesn't support presigned URLs (returns 255), fall back to multipart.
+  if [ "$FILE_SIZE" -ge "$PRESIGNED_THRESHOLD_BYTES" ]; then
+    PRESIGNED_RESULT=0
+    upload_presigned "$FILE" || PRESIGNED_RESULT=$?
+    if [ "$PRESIGNED_RESULT" -eq 0 ]; then
+      echo "OK (${FILE_SIZE} bytes, presigned R2 upload)"
+      SUCCEEDED=$((SUCCEEDED + 1))
+      TOTAL_SIZE=$((TOTAL_SIZE + FILE_SIZE))
+      continue
+    elif [ "$PRESIGNED_RESULT" -ne 255 ]; then
+      echo "FAILED (presigned upload after ${PRESIGNED_MAX_ATTEMPTS} attempts)"
+      FAILED=$((FAILED + 1))
+      continue
+    fi
+    # Result 255 — portal doesn't support presigned URLs, fall through
+    # to the existing multipart flow.
+  fi
+
+  # `-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 -L --max-redirs 3
+    --connect-timeout "$UPLOAD_CONNECT_TIMEOUT_SECONDS"
+    --max-time "$UPLOAD_MAX_TIME_SECONDS"
+    "$UPLOAD_URL"
+    -H "Authorization: Bearer ${DEVAUDIT_API_KEY}"
+    -F "file=@${FILE}"
+    -F "projectSlug=${PROJECT_SLUG}"
+    -F "requirementId=${REQUIREMENT_ID}"
+    -F "evidenceType=${EVIDENCE_TYPE}"
+    -F "metadata=${METADATA}"
+  )
+  [ -n "$RELEASE_VERSION" ] && CURL_ARGS+=(-F "releaseVersion=${RELEASE_VERSION}")
+  if [ "$CREATE_RELEASE_IF_MISSING" = true ]; then
+    CURL_ARGS+=(-F "createReleaseIfMissing=true")
+  fi
+  [ -n "$BRANCH" ] && CURL_ARGS+=(-F "releaseBranch=${BRANCH}")
+  [ -n "$ENVIRONMENT" ] && CURL_ARGS+=(-F "environment=${ENVIRONMENT}")
+  [ -n "$EVIDENCE_CATEGORY" ] && CURL_ARGS+=(-F "evidenceCategory=${EVIDENCE_CATEGORY}")
+  [ -n "$RELEASE_TITLE" ] && CURL_ARGS+=(-F "releaseTitle=${RELEASE_TITLE}")
+  [ -n "$RELEASE_SUMMARY" ] && CURL_ARGS+=(-F "releaseSummary=${RELEASE_SUMMARY}")
+  [ -n "$CHANGE_TYPE" ] && CURL_ARGS+=(-F "changeType=${CHANGE_TYPE}")
+  [ -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}")
+
+  ATTEMPT=1
+  BACKOFF=$INITIAL_BACKOFF_SECONDS
+  HTTP_CODE=0
+  RESP_BODY_FILE=""
+  RESP_HEADERS_FILE=""
+  LAST_CURL_ERROR=""
+  while [ "$ATTEMPT" -le "$MAX_ATTEMPTS" ]; do
+    [ -n "$RESP_BODY_FILE" ] && rm -f "$RESP_BODY_FILE"
+    RESP_BODY_FILE=$(mktemp)
+    RESP_HEADERS_FILE=$(mktemp)
+    CURL_EXIT=0
+    HTTP_CODE=$(curl -s -o "$RESP_BODY_FILE" -D "$RESP_HEADERS_FILE" -w "%{http_code}" "${CURL_ARGS[@]}") || CURL_EXIT=$?
+    if [ "$CURL_EXIT" -ne 0 ]; then
+      LAST_CURL_ERROR="curl exit ${CURL_EXIT}"
+      if [ "$CURL_EXIT" -eq 28 ]; then
+        LAST_CURL_ERROR="${LAST_CURL_ERROR} (timed out after ${UPLOAD_MAX_TIME_SECONDS}s)"
+      fi
+      if [ "$ATTEMPT" -lt "$MAX_ATTEMPTS" ]; then
+        WAIT_SECONDS=$BACKOFF
+        echo -n "(${LAST_CURL_ERROR}, retry in ${WAIT_SECONDS}s) "
+        rm -f "$RESP_HEADERS_FILE"
+        sleep "$WAIT_SECONDS"
+        ATTEMPT=$((ATTEMPT + 1))
+        BACKOFF=$((BACKOFF * 2))
+        continue
+      fi
+      rm -f "$RESP_HEADERS_FILE"
+      break
+    fi
+    if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
+      rm -f "$RESP_HEADERS_FILE"
+      break
+    fi
+    # Decide whether the failure is retriable (429 or 5xx).
+    if [ "$HTTP_CODE" = "429" ] || { [ "$HTTP_CODE" -ge 500 ] && [ "$HTTP_CODE" -lt 600 ]; }; then
+      if [ "$ATTEMPT" -lt "$MAX_ATTEMPTS" ]; then
+        # Honour Retry-After (seconds) if the portal supplied it; otherwise back off.
+        WAIT_SECONDS=$BACKOFF
+        RETRY_AFTER=$(grep -i '^retry-after:' "$RESP_HEADERS_FILE" 2>/dev/null | head -1 | sed 's/^[Rr]etry-[Aa]fter:[[:space:]]*//' | tr -d '\r')
+        if [[ "$RETRY_AFTER" =~ ^[0-9]+$ ]] && [ "$RETRY_AFTER" -gt 0 ]; then
+          WAIT_SECONDS=$RETRY_AFTER
+        fi
+        echo -n "(HTTP ${HTTP_CODE}, retry in ${WAIT_SECONDS}s) "
+        rm -f "$RESP_HEADERS_FILE"
+        sleep "$WAIT_SECONDS"
+        ATTEMPT=$((ATTEMPT + 1))
+        BACKOFF=$((BACKOFF * 2))
+        continue
+      fi
+    fi
+    rm -f "$RESP_HEADERS_FILE"
+    break
+  done
+
+  if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
+    rm -f "$RESP_BODY_FILE"
+    if [ "$ATTEMPT" -gt 1 ]; then
+      echo "OK (${FILE_SIZE} bytes, attempt ${ATTEMPT}/${MAX_ATTEMPTS})"
+    else
+      echo "OK (${FILE_SIZE} bytes)"
+    fi
+    SUCCEEDED=$((SUCCEEDED + 1))
+    TOTAL_SIZE=$((TOTAL_SIZE + FILE_SIZE))
+  else
+    if [ -n "$LAST_CURL_ERROR" ]; then
+      echo "FAILED (${LAST_CURL_ERROR} after ${ATTEMPT} attempt(s))"
+    else
+      echo "FAILED (HTTP ${HTTP_CODE} after ${ATTEMPT} attempt(s))"
+    fi
+    if [ -s "$RESP_BODY_FILE" ]; then
+      echo "  Response: $(head -c 500 "$RESP_BODY_FILE")"
+    fi
+    rm -f "$RESP_BODY_FILE"
+    FAILED=$((FAILED + 1))
+  fi
+done
+
+# --- Summary ---
+echo ""
+echo "=== Upload Summary ==="
+echo "Files: ${SUCCEEDED} succeeded, ${FAILED} failed, ${SKIPPED} skipped (${#FILES[@]} total)"
+echo "Total size: $((TOTAL_SIZE / 1024)) KB"
+# Skipped stubs are intentional (devaudit#133) — they don't fail the
+# run. Only true upload failures bump the exit code.
+if [ "$FAILED" -gt 0 ]; then
+  exit 1
+fi

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

@@ -37,6 +37,23 @@ fi
 TOTAL=0
 FAILED=0
 
+ACTIVE_RELEASE_REQS=""
+if [ -d compliance/pending-releases ]; then
+  ACTIVE_RELEASE_REQS=$(find compliance/pending-releases -maxdepth 1 -type f \
+    -name 'RELEASE-TICKET-REQ-*.md' -print 2>/dev/null \
+    | sed -E 's|.*/RELEASE-TICKET-(REQ-[0-9]+)\.md$|\1|' | sort -u || true)
+fi
+if [ -z "$ACTIVE_RELEASE_REQS" ] && [ -f compliance/RTM.md ]; then
+  ACTIVE_RELEASE_REQS=$(sed 's/\\|/  /g' compliance/RTM.md 2>/dev/null \
+    | grep -E '\|[[:space:]]+IN PROGRESS|\|[[:space:]]+TESTED - PENDING SIGN-OFF' \
+    | grep -oE '^\|[[:space:]]*REQ-[0-9]+' \
+    | grep -oE 'REQ-[0-9]+' | sort -u || true)
+fi
+ACTIVE_RELEASE_REQ_COUNT=0
+if [ -n "$ACTIVE_RELEASE_REQS" ]; then
+  ACTIVE_RELEASE_REQ_COUNT=$(printf '%s\n' "$ACTIVE_RELEASE_REQS" | grep -c . || true)
+fi
+
 while IFS= read -r sha; do
   TOTAL=$((TOTAL + 1))
   SUBJECT=$(git log -1 --format='%s' "$sha")
@@ -66,13 +83,21 @@ while IFS= read -r sha; do
     feat|fix|refactor|perf)
       if ! echo "$SUBJECT" | grep -qP '\[REQ-\d{3,}\]' \
         && ! echo "$BODY" | grep -qiP 'Ref:\s*REQ-\d{3,}'; then
-        echo "ERROR [$SHORT]: '$TYPE' is an implementation commit but cites no requirement."
-        echo "       Add [REQ-XXX] to the subject or a 'Ref: REQ-XXX' trailer. Start work"
-        echo "       from a requirement via the sdlc-implementer skill (it assigns the REQ"
-        echo "       from the originating issue in Phase 1)."
-        FAILED=$((FAILED + 1))
-        EXIT_CODE=1
-        continue
+        if [ "$ACTIVE_RELEASE_REQ_COUNT" -eq 1 ]; then
+          ACTIVE_REQ=$(printf '%s\n' "$ACTIVE_RELEASE_REQS" | head -1)
+          echo "WARNING [$SHORT]: '$TYPE' cites no requirement, but the branch has one active tracked release (${ACTIVE_REQ})."
+          echo "       Treating the release ticket / RTM context as authoritative for this already-merged history."
+          echo "       Add a follow-up compliance note if this was not an intentional recovery path."
+          WARN_COUNT=$((WARN_COUNT + 1))
+        else
+          echo "ERROR [$SHORT]: '$TYPE' is an implementation commit but cites no requirement."
+          echo "       Add [REQ-XXX] to the subject or a 'Ref: REQ-XXX' trailer. Start work"
+          echo "       from a requirement via the sdlc-implementer skill (it assigns the REQ"
+          echo "       from the originating issue in Phase 1)."
+          FAILED=$((FAILED + 1))
+          EXIT_CODE=1
+          continue
+        fi
       fi
 
       # RTM provenance check (devaudit-installer#226): verify the REQ-XXX