@metasession.co/devaudit-cli 0.3.17 → 0.3.19

package/sdlc/files/_common/scripts/derive-release-version.sh

@@ -24,13 +24,11 @@
 #                                                                    -> empty/skip
 #   5. Fallback:                      bare date                      -> v2026.05.17
 #
-# Step 4 (DevAudit-Installer#92) handles `chore:` / `docs:` / `ci:`
-# commits (e.g. a `devaudit update` sync) landing on the integration
-# branch between feature merge and release-PR open. Such a commit has
-# no REQ tag in its message → steps 1-3 fall through. The release
-# ticket on disk is a stronger explicit-operator-state signal than the
-# bare date — when exactly one ticket is open, attribute to it.
-# Multiple open tickets stays ambiguous → bare-date fallback.
+# A pending ticket or RTM row is not commit ownership. In particular, an
+# independent main hotfix must not become part of an active UAT REQ merely
+# because its mandatory back-merge lands while that REQ is the only pending
+# ticket. The optional fallback below is disabled by default and may be used
+# only for an explicitly reviewed integration exception.
 #
 # Note (DevAudit-Installer#220): `devaudit update` syncs now include
 # `[skip ci]` in their commit message, so they no longer trigger CI
@@ -91,7 +89,7 @@ fi
 # operator's explicit state says THIS is the in-flight release. Use it.
 # Zero or multiple → ambiguous, fall through to the bare date.
 # DevAudit-Installer#92.
-if [ -d compliance/pending-releases ]; then
+if [ "${DEVAUDIT_ALLOW_PENDING_TICKET_FALLBACK:-0}" = "1" ] && [ -d compliance/pending-releases ]; then
   # NUL-delimited count so filenames with spaces don't trip us up.
   TICKET_COUNT=$(find compliance/pending-releases -maxdepth 1 -type f \
     -name 'RELEASE-TICKET-REQ-*.md' -print0 2>/dev/null \
@@ -113,7 +111,7 @@ fi
 # multiple IN PROGRESS rows → ambiguous, fall through.
 # DevAudit-Installer#95.
 RTM_PATH="${RTM_PATH:-compliance/RTM.md}"
-if [ -f "$RTM_PATH" ]; then
+if [ "${DEVAUDIT_ALLOW_PENDING_TICKET_FALLBACK:-0}" = "1" ] && [ -f "$RTM_PATH" ]; then
   # Match REQ rows whose status column starts with `IN PROGRESS`.
   # `\|[[:space:]]+IN PROGRESS` requires a pipe followed by whitespace,
   # so legend rows (`| \`IN PROGRESS\``) and prose mentions don't match.

package/sdlc/files/_common/scripts/derive-release-version.test.sh

@@ -111,12 +111,9 @@ make_fixture "$WORK/c8" "Merge pull request #7 from metasession-dev/feat/req-002
 chore(deps): [REQ-002] dependency hardening — close R-001"
 assert_eq "merge-commit body [REQ-002] -> REQ-002" "REQ-002" "$(run_helper)"
 
-# Case 9 (DevAudit-Installer#92): a chore: sync commit has no REQ tag in
-# its message but a pending release ticket exists on disk. Must attribute
-# to the REQ from that ticket instead of falling through to the bare date.
-# Regression for REQ-051 / REQ-052 gate evidence landing on phantom date
-# releases when a `chore: devaudit update to 0.1.x` commit landed between
-# the feature merge and the release-PR open on wawagardenbar-app.
+# Case 9: a pending ticket is not ownership of an unrelated commit. The
+# default is a historical bare-date record; explicit operator exceptions may
+# opt in with DEVAUDIT_ALLOW_PENDING_TICKET_FALLBACK=1.
 make_fixture "$WORK/c9" "chore: devaudit update to 0.1.27"
 mkdir -p compliance/pending-releases
 cat > compliance/pending-releases/RELEASE-TICKET-REQ-051.md <<'TICKET'
@@ -124,7 +121,9 @@ cat > compliance/pending-releases/RELEASE-TICKET-REQ-051.md <<'TICKET'
 
 **Status:** TESTED - PENDING SIGN-OFF
 TICKET
-assert_eq "chore: sync + single pending ticket REQ-051 -> REQ-051" "REQ-051" "$(run_helper)"
+assert_eq "chore: sync + single pending ticket -> bare date $TODAY" "$TODAY" "$(run_helper)"
+GOT=$(DEVAUDIT_ALLOW_PENDING_TICKET_FALLBACK=1 run_helper)
+assert_eq "explicit pending-ticket exception -> REQ-051" "REQ-051" "$GOT"
 
 # Case 10: a chore: sync commit with MULTIPLE pending tickets — ambiguous,
 # stays at the bare-date fallback (don't guess between them).
@@ -154,11 +153,7 @@ cat > compliance/pending-releases/RELEASE-TICKET-REQ-051.md <<'TICKET'
 TICKET
 assert_eq "subject [REQ-099] beats pending REQ-051 -> REQ-099" "REQ-099" "$(run_helper)"
 
-# Case 13 (DevAudit-Installer#95): step-4-bis. No subject/body tag,
-# no pending ticket, but RTM.md has exactly one IN PROGRESS row.
-# Attribute to that REQ. Tests the zero-ceremony fallback that
-# survives chore/docs/ci sync commits when no operator state file
-# has been dropped.
+# Case 13: an RTM IN PROGRESS row is likewise not automatic commit ownership.
 make_fixture "$WORK/c13" "chore: devaudit update to 0.1.29"
 mkdir -p compliance
 cat > compliance/RTM.md <<'RTM'
@@ -168,7 +163,9 @@ cat > compliance/RTM.md <<'RTM'
 | REQ-100 | #10   | LOW  | compliance/evidence/REQ-100/ | APPROVED - DEPLOYED | dev      | 2026-05-30 |
 | REQ-101 | #11   | MED  | compliance/evidence/REQ-101/ | IN PROGRESS         | dev      | 2026-06-01 |
 RTM
-assert_eq "RTM single IN PROGRESS row -> REQ-101" "REQ-101" "$(run_helper)"
+assert_eq "RTM single IN PROGRESS row -> bare date $TODAY" "$TODAY" "$(run_helper)"
+GOT=$(DEVAUDIT_ALLOW_PENDING_TICKET_FALLBACK=1 run_helper)
+assert_eq "explicit RTM fallback exception -> REQ-101" "REQ-101" "$GOT"
 
 # Case 14: step-4-bis ambiguity guard. Two IN PROGRESS rows → falls
 # through to the bare date rather than guessing.
@@ -210,7 +207,8 @@ cat > compliance/RTM.md <<'RTM'
 | ------- | ----- | ----------- | ---------------------------- | --------------------------------------------------------------------- | ---------- | ---------- |
 | REQ-056 | #117  | MEDIUM-HIGH | compliance/evidence/REQ-056/ | IN PROGRESS (WhatsApp inbound-message router; many details follow...) | ostendo-io | 2026-06-01 |
 RTM
-assert_eq "RTM long parenthetical status -> REQ-056" "REQ-056" "$(run_helper)"
+GOT=$(DEVAUDIT_ALLOW_PENDING_TICKET_FALLBACK=1 run_helper)
+assert_eq "explicit RTM long-status fallback -> REQ-056" "REQ-056" "$GOT"
 
 # Case 17: step-4-bis must NOT win over a pending ticket on disk.
 # Step 4 returns first.
@@ -224,7 +222,8 @@ cat > compliance/RTM.md <<'RTM'
 | ------- | ----------- |
 | REQ-302 | IN PROGRESS |
 RTM
-assert_eq "pending ticket REQ-301 beats RTM IN PROGRESS REQ-302" "REQ-301" "$(run_helper)"
+GOT=$(DEVAUDIT_ALLOW_PENDING_TICKET_FALLBACK=1 run_helper)
+assert_eq "explicit pending ticket beats RTM fallback" "REQ-301" "$GOT"
 
 # Case 18: step-4-bis respects RTM_PATH env override.
 make_fixture "$WORK/c18" "chore: devaudit update to 0.1.29"
@@ -234,8 +233,8 @@ cat > docs/custom-RTM.md <<'RTM'
 | ------- | ----------- |
 | REQ-400 | IN PROGRESS |
 RTM
-GOT=$(RTM_PATH=docs/custom-RTM.md run_helper)
-assert_eq "RTM_PATH=docs/custom-RTM.md -> REQ-400" "REQ-400" "$GOT"
+GOT=$(RTM_PATH=docs/custom-RTM.md DEVAUDIT_ALLOW_PENDING_TICKET_FALLBACK=1 run_helper)
+assert_eq "explicit RTM_PATH fallback exception -> REQ-400" "REQ-400" "$GOT"
 
 # Case 19: step-4-bis with escaped pipes (\|) in the Status column.
 # The Status cell contains literal pipe characters escaped as \| (markdown
@@ -251,7 +250,8 @@ cat > compliance/RTM.md <<'RTM'
 | REQ-056 | #117  | MEDIUM-HIGH | compliance/evidence/REQ-056/ | IN PROGRESS (regex: /^\s*(stop\|unsubscribe\|opt[-\s]?out)\s*$/i)    | ostendo-io | 2026-06-01 |
 | REQ-064 | #121  | MEDIUM      | compliance/evidence/REQ-064/ | RELEASED (enum: open\|in_progress\|awaiting_customer\|resolved\|closed) | dev | 2026-06-02 |
 RTM
-assert_eq "RTM escaped pipes -> REQ-056 (single IN PROGRESS)" "REQ-056" "$(run_helper)"
+GOT=$(DEVAUDIT_ALLOW_PENDING_TICKET_FALLBACK=1 run_helper)
+assert_eq "explicit RTM escaped-pipe fallback -> REQ-056" "REQ-056" "$GOT"
 
 # Case 20: step-4-bis with escaped pipes — ambiguity guard still works.
 # Two IN PROGRESS rows, both with escaped pipes in status → falls through

package/sdlc/files/_common/scripts/generate-bundled-changes.sh

@@ -250,8 +250,29 @@ for version in "${EXPLICIT_PREDECESSORS[@]}"; do
   PREDECESSOR_LINES+=("- \`${version}\` (${role}/${relationship}) — ${title:-Untitled release ticket}")
 done
 
-COMMITS="$(git log "$SINCE_REF"..HEAD --format='%h%x09%s' 2>/dev/null || true)"
-BUNDLED="$(printf '%s\n' "$COMMITS" | grep -E "$HOUSEKEEPING_TYPES" || true)"
+# A tracked release only absorbs genuinely REQ-free housekeeping performed
+# during its own implementation window. Do not recast earlier history, or a
+# conventional commit explicitly owned by any REQ, as generic bundle work.
+SCAN_FROM="$SINCE_REF"
+if [[ "$VERSION" =~ ^REQ-[0-9]+$ ]]; then
+  FIRST_REQ_SHA="$(git log --reverse --format='%H' --grep="\\[${VERSION}\\]\\|Ref: ${VERSION}" 2>/dev/null | head -1 || true)"
+  if [ -n "$FIRST_REQ_SHA" ] && git rev-parse --verify "${FIRST_REQ_SHA}^" >/dev/null 2>&1; then
+    SCAN_FROM="${FIRST_REQ_SHA}^"
+  fi
+fi
+COMMITS="$(git log "$SCAN_FROM"..HEAD --format='%h%x09%s' 2>/dev/null || true)"
+BUNDLED=""
+while IFS=$'\t' read -r sha subject; do
+  [ -n "$sha" ] || continue
+  if ! printf '%s\t%s\n' "$sha" "$subject" | grep -Eq "$HOUSEKEEPING_TYPES"; then
+    continue
+  fi
+  if git log -1 --format='%s%n%b' "$sha" | grep -Eq '\[REQ-[0-9]+\]|Ref:[[:space:]]*REQ-[0-9]+'; then
+    continue
+  fi
+  BUNDLED+="${sha}"$'\t'"${subject}"$'\n'
+done <<<"$COMMITS"
+BUNDLED="${BUNDLED%$'\n'}"
 NON_RELEASE_ITEMS='[]'
 NON_RELEASE_LINES=()
 if [ -n "$BUNDLED" ]; then
@@ -324,7 +345,7 @@ echo "- **Why bundled here:** Explicit predecessor release tickets and non-relea
 echo "- **Evidence impact:** Evidence ownership remains on the source releases; the bundle manifest provides lineage and inherited visibility only."
 echo "- **Reviewer impact:** Approval scope includes the core tracked release plus the explicit predecessor releases and non-release work listed below."
 echo "- **Security / risk impact:** No additional security/risk impact identified automatically; reviewer must confirm in the canonical release artifacts."
-echo "- **Reference:** commit range \`${SINCE_REF}..HEAD\`"
+echo "- **Reference:** commit range \`${SCAN_FROM}..HEAD\`"
 echo ""
 
 echo "### Explicit Constituent Releases"

package/sdlc/files/_common/scripts/generate-bundled-changes.test.sh

@@ -109,25 +109,29 @@ assert_file_exists() {
   fi
 }
 
-# Test 1: housekeeping commits appear in markdown + JSON.
-echo "Test 1: housekeeping commits render as non-release work"
+# Test 1: only REQ-free housekeeping inside the tracked REQ window is bundled.
+echo "Test 1: release ownership excludes tagged and historical work"
 DIR1="$TMPDIR_BASE/test1"
 make_fixture "$DIR1"
 add_commit "chore: sync DevAudit templates from v0.1.69 to v0.1.70 [skip ci]"
 add_commit "docs: update API reference for /bookings endpoint"
 add_commit "feat: add booking widget [REQ-042]"
+add_commit "test: verify booking widget [REQ-042]"
 add_commit "chore(deps): bump eslint 9.0.5 to 9.0.6"
+add_commit "docs: document booking widget\n\nRef: REQ-042"
 add_commit "fix: resolve null pointer in booking service [REQ-042]"
 SINCE=$(git rev-list --max-parents=0 HEAD)
 JSON_OUT="$DIR1/bundle.json"
 OUTPUT=$(bash "$HELPER" "$SINCE" "REQ-042" --json-out "$JSON_OUT" 2>&1)
-assert_contains "markdown includes chore commit" "chore: sync DevAudit templates" "$OUTPUT"
-assert_contains "markdown includes docs commit" "docs: update API reference" "$OUTPUT"
 assert_contains "markdown includes scoped chore commit" "chore(deps): bump eslint" "$OUTPUT"
+assert_not_contains "markdown excludes historical chore commit" "chore: sync DevAudit templates" "$OUTPUT"
+assert_not_contains "markdown excludes historical docs commit" "docs: update API reference" "$OUTPUT"
+assert_not_contains "markdown excludes tagged test commit" "test: verify booking widget" "$OUTPUT"
+assert_not_contains "markdown excludes Ref-tagged docs commit" "docs: document booking widget" "$OUTPUT"
 assert_not_contains "markdown excludes feat commit" "feat: add booking widget" "$OUTPUT"
 assert_not_contains "markdown excludes fix commit" "fix: resolve null pointer" "$OUTPUT"
 assert_file_exists "json manifest emitted" "$JSON_OUT"
-assert_eq "non-release work count" "3" "$(jq -r '.nonReleaseWorkItems | length' "$JSON_OUT")"
+assert_eq "non-release work count" "1" "$(jq -r '.nonReleaseWorkItems | length' "$JSON_OUT")"
 assert_eq "member count with no tickets" "0" "$(jq -r '.members | length' "$JSON_OUT")"
 assert_eq "first housekeeping kind" "housekeeping_commit" "$(jq -r '.nonReleaseWorkItems[0].kind' "$JSON_OUT")"
 echo

package/sdlc/files/_common/scripts/reconcile-railway-deployment.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Reconcile a verified Railway recovery deployment to its GitHub deployment.
+set -euo pipefail
+
+REPO=""; SHA=""; GITHUB_DEPLOYMENT_ID=""; RAILWAY_DEPLOYMENT_ID=""
+RAILWAY_PROJECT=""; RAILWAY_ENVIRONMENT="production"; RAILWAY_SERVICE=""; HEALTH_URL=""
+for arg in "$@"; do
+  case "$arg" in
+    --repo=*) REPO="${arg#*=}" ;; --sha=*) SHA="${arg#*=}" ;;
+    --github-deployment-id=*) GITHUB_DEPLOYMENT_ID="${arg#*=}" ;;
+    --railway-deployment-id=*) RAILWAY_DEPLOYMENT_ID="${arg#*=}" ;;
+    --railway-project=*) RAILWAY_PROJECT="${arg#*=}" ;;
+    --railway-environment=*) RAILWAY_ENVIRONMENT="${arg#*=}" ;;
+    --railway-service=*) RAILWAY_SERVICE="${arg#*=}" ;;
+    --health-url=*) HEALTH_URL="${arg#*=}" ;;
+    *) echo "Unknown argument: $arg" >&2; exit 2 ;;
+  esac
+done
+[ -n "$REPO" ] && [ -n "$SHA" ] && [ -n "$GITHUB_DEPLOYMENT_ID" ] && [ -n "$RAILWAY_DEPLOYMENT_ID" ] && [ -n "$RAILWAY_PROJECT" ] && [ -n "$RAILWAY_SERVICE" ] && [ -n "$HEALTH_URL" ] || { echo "Missing required reconciliation arguments" >&2; exit 2; }
+
+DEPLOYMENTS=$(railway deployment list --json --project "$RAILWAY_PROJECT" --environment "$RAILWAY_ENVIRONMENT" --service "$RAILWAY_SERVICE" --limit 100)
+MATCH=$(jq -cer --arg id "$RAILWAY_DEPLOYMENT_ID" '.[] | select(.id == $id)' <<<"$DEPLOYMENTS") || { echo "::error::Railway deployment ${RAILWAY_DEPLOYMENT_ID} was not found."; exit 1; }
+STATUS=$(jq -r '.status // empty' <<<"$MATCH")
+PROVIDER_SHA=$(jq -r '.meta.commitHash // empty' <<<"$MATCH")
+BRANCH=$(jq -r '.meta.branch // empty' <<<"$MATCH")
+PROVIDER_REPO=$(jq -r '.meta.repo // empty' <<<"$MATCH")
+[ "$STATUS" = "SUCCESS" ] || { echo "::error::Railway deployment is not terminal-successful: ${STATUS:-missing}"; exit 1; }
+[ "$PROVIDER_SHA" = "$SHA" ] && [ "$BRANCH" = "main" ] && [ "$PROVIDER_REPO" = "$REPO" ] || { echo "::error::Railway provenance mismatch: repo=$PROVIDER_REPO branch=$BRANCH sha=$PROVIDER_SHA"; exit 1; }
+HTTP=$(curl -sS -o /dev/null -w '%{http_code}' --connect-timeout 5 --max-time 15 "$HEALTH_URL" || echo 000)
+[[ "$HTTP" =~ ^[23][0-9][0-9]$ ]] || { echo "::error::Health probe failed for ${HEALTH_URL}: HTTP ${HTTP}"; exit 1; }
+DESCRIPTION="manual_reconciliation; railway_deployment=${RAILWAY_DEPLOYMENT_ID}; sha=${SHA}; health_http=${HTTP}; verified_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+EXISTING=$(gh api "/repos/${REPO}/deployments/${GITHUB_DEPLOYMENT_ID}/statuses?per_page=20" --jq '[.[] | select(.state == "success" and (.description // "" | contains("railway_deployment='"$RAILWAY_DEPLOYMENT_ID"'")))] | length')
+if [ "$EXISTING" = "0" ]; then
+  gh api --method POST "/repos/${REPO}/deployments/${GITHUB_DEPLOYMENT_ID}/statuses" -f state=success -f environment=production -f description="$DESCRIPTION" -f environment_url="$HEALTH_URL" >/dev/null
+fi
+jq -n --arg provenance manual_reconciliation --arg provider railway --arg providerDeploymentId "$RAILWAY_DEPLOYMENT_ID" --arg sha "$SHA" --arg healthUrl "$HEALTH_URL" --arg healthHttp "$HTTP" --arg actor "${GITHUB_ACTOR:-operator}" --arg verifiedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '{provenance:$provenance,provider:$provider,providerDeploymentId:$providerDeploymentId,sha:$sha,healthUrl:$healthUrl,healthHttp:($healthHttp|tonumber),actor:$actor,verifiedAt:$verifiedAt}' > deployment-reconciliation.json
+echo "Verified Railway deployment ${RAILWAY_DEPLOYMENT_ID}; GitHub deployment ${GITHUB_DEPLOYMENT_ID} reconciled."

package/sdlc/files/_common/scripts/reconcile-railway-deployment.test.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")" && pwd)"; HELPER="$ROOT/reconcile-railway-deployment.sh"
+WORK="$(mktemp -d)"; trap 'rm -rf "$WORK"' EXIT; PASS=0; FAIL=0
+ok(){ echo "  ok $1"; PASS=$((PASS+1)); }; no(){ echo "  FAIL $1"; FAIL=$((FAIL+1)); }
+mock() { mkdir -p "$1/bin"; cat >"$1/bin/railway" <<'EOF'
+#!/usr/bin/env bash
+printf '%s' "$MOCK_RAILWAY_JSON"
+EOF
+cat >"$1/bin/curl" <<'EOF'
+#!/usr/bin/env bash
+printf '%s' "${MOCK_HTTP:-200}"
+EOF
+cat >"$1/bin/gh" <<'EOF'
+#!/usr/bin/env bash
+if [[ "$*" == *"--jq"* ]]; then printf '%s' "${MOCK_EXISTING:-[]}"; else echo "$*" >> "$MOCK_GH_LOG"; fi
+EOF
+chmod +x "$1/bin/"*; }
+run(){ local d="$1"; shift; (cd "$d"; PATH="$d/bin:$PATH" MOCK_GH_LOG="$d/gh.log" "$@" bash "$HELPER" --repo=org/app --sha=abc --github-deployment-id=42 --railway-deployment-id=r1 --railway-project=p --railway-service=s --health-url=https://health.test); }
+mock "$WORK"
+GOOD='[{"id":"r1","status":"SUCCESS","meta":{"repo":"org/app","branch":"main","commitHash":"abc"}}]'
+if run "$WORK" env MOCK_RAILWAY_JSON="$GOOD"; then ok valid; else no valid; fi
+grep -q '"provenance": "manual_reconciliation"' "$WORK/deployment-reconciliation.json" && ok provenance_evidence || no provenance_evidence
+if run "$WORK" env MOCK_RAILWAY_JSON='[{"id":"r1","status":"SUCCESS","meta":{"repo":"org/app","branch":"main","commitHash":"wrong"}}]'; then no sha_mismatch; else ok sha_mismatch; fi
+if run "$WORK" env MOCK_RAILWAY_JSON='[{"id":"r1","status":"FAILED","meta":{"repo":"org/app","branch":"main","commitHash":"abc"}}]'; then no provider_failure; else ok provider_failure; fi
+if run "$WORK" env MOCK_RAILWAY_JSON="$GOOD" MOCK_HTTP=500; then no health_failure; else ok health_failure; fi
+rm -f "$WORK/gh.log"
+if run "$WORK" env MOCK_RAILWAY_JSON="$GOOD" MOCK_EXISTING='[{"state":"success","description":"railway_deployment=r1"}]'; then ok idempotent; else no idempotent; fi
+[ ! -f "$WORK/gh.log" ] && ok no_duplicate_post || no no_duplicate_post
+echo "$PASS passed, $FAIL failed"; [ "$FAIL" -eq 0 ]

package/sdlc/files/_common/scripts/record-uat-execution.sh

@@ -0,0 +1,195 @@
+#!/usr/bin/env bash
+# record-uat-execution.sh - Record an explicit Stage 4 UAT execution.
+#
+# This script does not submit, approve, or release anything. It records the
+# manual UAT execution that happened while the release was under UAT review.
+#
+# Usage:
+#   ./scripts/record-uat-execution.sh \
+#     --project-slug <slug> \
+#     --release <REQ-XXX|version> \
+#     --outcome <passed|failed|cancelled|skipped|timed_out|action_required> \
+#     --executor <identity> \
+#     [--tested-sha <sha>] \
+#     [--build-version <version>] \
+#     [--checklist-ref <path-or-url>] \
+#     [--evidence-ref <path-or-url>] \
+#     [--remediation-ref <issue-or-url>] \
+#     [--executed-at <iso8601>] \
+#     [--execution-id <stable-id>] \
+#     [--output-file <path>]
+#
+# Required environment:
+#   DEVAUDIT_BASE_URL
+#   DEVAUDIT_API_KEY
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPORT_TEST_EXECUTION="${REPORT_TEST_EXECUTION_HELPER:-${SCRIPT_DIR}/report-test-execution.sh}"
+
+usage() {
+  sed -n '1,38p' "$0" >&2
+  exit 1
+}
+
+PROJECT_SLUG=""
+RELEASE_VERSION=""
+OUTCOME=""
+EXECUTOR=""
+TESTED_SHA="${GITHUB_SHA:-}"
+BUILD_VERSION=""
+CHECKLIST_REF=""
+EVIDENCE_REF=""
+REMEDIATION_REF=""
+EXECUTED_AT=""
+EXECUTION_ID=""
+OUTPUT_FILE=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --project-slug) PROJECT_SLUG="${2:-}"; shift 2 ;;
+    --release) RELEASE_VERSION="${2:-}"; shift 2 ;;
+    --outcome) OUTCOME="${2:-}"; shift 2 ;;
+    --executor) EXECUTOR="${2:-}"; shift 2 ;;
+    --tested-sha) TESTED_SHA="${2:-}"; shift 2 ;;
+    --build-version) BUILD_VERSION="${2:-}"; shift 2 ;;
+    --checklist-ref) CHECKLIST_REF="${2:-}"; shift 2 ;;
+    --evidence-ref) EVIDENCE_REF="${2:-}"; shift 2 ;;
+    --remediation-ref) REMEDIATION_REF="${2:-}"; shift 2 ;;
+    --executed-at) EXECUTED_AT="${2:-}"; shift 2 ;;
+    --execution-id) EXECUTION_ID="${2:-}"; shift 2 ;;
+    --output-file) OUTPUT_FILE="${2:-}"; shift 2 ;;
+    -h|--help) usage ;;
+    *) echo "Unknown option: $1" >&2; usage ;;
+  esac
+done
+
+require_arg() {
+  local value="$1" name="$2"
+  if [ -z "$value" ]; then
+    echo "Error: ${name} is required" >&2
+    exit 1
+  fi
+}
+
+require_arg "$PROJECT_SLUG" "--project-slug"
+require_arg "$RELEASE_VERSION" "--release"
+require_arg "$OUTCOME" "--outcome"
+require_arg "$EXECUTOR" "--executor"
+
+case "$OUTCOME" in
+  passed|failed|cancelled|skipped|timed_out|action_required) ;;
+  *)
+    echo "Error: --outcome must be passed, failed, cancelled, skipped, timed_out, or action_required" >&2
+    exit 1
+    ;;
+esac
+if [ "$OUTCOME" = "failed" ] && [ -z "$REMEDIATION_REF" ]; then
+  echo "Error: --remediation-ref is required when --outcome failed" >&2
+  exit 1
+fi
+
+if [ -z "${DEVAUDIT_BASE_URL:-}" ]; then
+  echo "Error: DEVAUDIT_BASE_URL environment variable is required" >&2
+  exit 1
+fi
+if [ -z "${DEVAUDIT_API_KEY:-}" ]; then
+  echo "Error: DEVAUDIT_API_KEY environment variable is required" >&2
+  exit 1
+fi
+if [ ! -x "$REPORT_TEST_EXECUTION" ]; then
+  echo "Error: report-test-execution helper not found or not executable: $REPORT_TEST_EXECUTION" >&2
+  exit 1
+fi
+
+if [ -z "$TESTED_SHA" ] && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  TESTED_SHA="$(git rev-parse HEAD)"
+fi
+if [ -z "$TESTED_SHA" ]; then
+  echo "Error: --tested-sha is required when GITHUB_SHA is unset and git HEAD cannot be resolved" >&2
+  exit 1
+fi
+
+iso_now() {
+  date -u +"%Y-%m-%dT%H:%M:%SZ"
+}
+
+hash_value() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    printf '%s' "$1" | sha256sum | awk '{print $1}'
+  else
+    printf '%s' "$1" | shasum -a 256 | awk '{print $1}'
+  fi
+}
+
+sanitize_id_part() {
+  printf '%s' "$1" | tr -cs 'A-Za-z0-9._:-' '-'
+}
+
+[ -n "$EXECUTED_AT" ] || EXECUTED_AT="$(iso_now)"
+
+if [ -z "$EXECUTION_ID" ]; then
+  KEY_SOURCE="${PROJECT_SLUG}|${RELEASE_VERSION}|${TESTED_SHA}|${BUILD_VERSION}|${EXECUTOR}|${OUTCOME}|${CHECKLIST_REF}|${EVIDENCE_REF}|${REMEDIATION_REF}"
+  KEY_HASH="$(hash_value "$KEY_SOURCE" | cut -c1-16)"
+  EXECUTION_ID="manual-uat:$(sanitize_id_part "$RELEASE_VERSION"):$(sanitize_id_part "$TESTED_SHA" | cut -c1-12):${KEY_HASH}"
+fi
+
+IDEMPOTENCY_KEY="manual-uat:${PROJECT_SLUG}:${RELEASE_VERSION}:${EXECUTION_ID}"
+OUTCOME_REASON="executor=${EXECUTOR}; tested_sha=${TESTED_SHA}"
+[ -z "$BUILD_VERSION" ] || OUTCOME_REASON="${OUTCOME_REASON}; build=${BUILD_VERSION}"
+[ -z "$CHECKLIST_REF" ] || OUTCOME_REASON="${OUTCOME_REASON}; checklist=${CHECKLIST_REF}"
+[ -z "$EVIDENCE_REF" ] || OUTCOME_REASON="${OUTCOME_REASON}; evidence=${EVIDENCE_REF}"
+[ -z "$REMEDIATION_REF" ] || OUTCOME_REASON="${OUTCOME_REASON}; remediation=${REMEDIATION_REF}"
+
+START_OUTPUT="$(mktemp)"
+COMPLETE_OUTPUT="$(mktemp)"
+cleanup() {
+  rm -f "$START_OUTPUT" "$COMPLETE_OUTPUT"
+}
+trap cleanup EXIT
+
+COMMON_ARGS=(
+  --project-slug "$PROJECT_SLUG"
+  --release "$RELEASE_VERSION"
+  --sdlc-stage 4
+  --environment uat
+  --suite-kind uat
+  --iteration-key "uat:${RELEASE_VERSION}:${TESTED_SHA}"
+  --provider manual_uat
+  --external-run-id "$EXECUTION_ID"
+  --external-job-id "manual-uat-execution"
+  --commit-sha "$TESTED_SHA"
+  --branch "uat"
+  --workflow-name "Manual UAT execution"
+  --workflow-url "${DEVAUDIT_BASE_URL%/}/projects/${PROJECT_SLUG}/requirements/${RELEASE_VERSION}"
+  --idempotency-key "$IDEMPOTENCY_KEY"
+  --started-at "$EXECUTED_AT"
+)
+COMPLETE_ARGS=(
+  "${COMMON_ARGS[@]}"
+  --completed-at "$EXECUTED_AT"
+  --outcome "$OUTCOME"
+  --outcome-reason "$OUTCOME_REASON"
+)
+if [ -n "$REMEDIATION_REF" ]; then
+  COMPLETE_ARGS+=(--incident-reference "$REMEDIATION_REF")
+fi
+
+"$REPORT_TEST_EXECUTION" start "${COMMON_ARGS[@]}" --output-file "$START_OUTPUT"
+"$REPORT_TEST_EXECUTION" complete "${COMPLETE_ARGS[@]}" --output-file "$COMPLETE_OUTPUT"
+
+if [ -n "$OUTPUT_FILE" ]; then
+  {
+    printf 'uat_execution_id=%s\n' "$EXECUTION_ID"
+    printf 'uat_idempotency_key=%s\n' "$IDEMPOTENCY_KEY"
+    printf 'uat_outcome=%s\n' "$OUTCOME"
+    printf 'uat_executed_at=%s\n' "$EXECUTED_AT"
+    grep '^execution_' "$COMPLETE_OUTPUT" || true
+  } >> "$OUTPUT_FILE"
+fi
+
+echo "Recorded Stage 4 UAT execution for ${RELEASE_VERSION}: ${OUTCOME}"
+echo "  Execution ID: ${EXECUTION_ID}"
+echo "  Tested SHA: ${TESTED_SHA}"
+echo "  Executor: ${EXECUTOR}"

package/sdlc/files/_common/scripts/record-uat-execution.test.sh

@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+# record-uat-execution.test.sh - Regression tests for the manual UAT execution helper.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HELPER="$SCRIPT_DIR/record-uat-execution.sh"
+[ -x "$HELPER" ] || chmod +x "$HELPER"
+
+PASS=0
+FAIL=0
+
+ok() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
+no() { echo "  FAIL: $1"; FAIL=$((FAIL + 1)); }
+
+make_fixture() {
+  local dir="$1"
+  rm -rf "$dir"
+  mkdir -p "$dir/bin"
+  cat > "$dir/bin/report-test-execution.sh" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+LOG_FILE="${UAT_TEST_LOG:?}"
+printf 'CALL:%s\n' "$*" >> "$LOG_FILE"
+mode="$1"
+shift
+out=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --output-file) out="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+if [ -n "$out" ]; then
+  {
+    printf 'execution_supported=true\n'
+    printf 'execution_record_id=execution-%s\n' "$mode"
+    printf 'execution_idempotency_key=stub\n'
+  } >> "$out"
+fi
+EOF
+  chmod +x "$dir/bin/report-test-execution.sh"
+}
+
+run_helper() {
+  UAT_TEST_LOG="$1/uat.log" \
+  DEVAUDIT_BASE_URL="https://devaudit.example.test" \
+  DEVAUDIT_API_KEY="mc_test_dummy" \
+  REPORT_TEST_EXECUTION_HELPER="$1/bin/report-test-execution.sh" \
+  "$HELPER" "${@:2}"
+}
+
+assert_contains() {
+  local label="$1" needle="$2" file="$3"
+  if grep -Fq -- "$needle" "$file"; then ok "$label"; else no "$label"; fi
+}
+
+echo "=== record-uat-execution.sh tests ==="
+
+case_passed_records_stage_four_pair() {
+  echo "case: passed UAT records Stage 4 start and complete"
+  local dir out exit_code
+  dir=$(mktemp -d)
+  make_fixture "$dir"
+  out="$dir/out.env"
+  run_helper "$dir" \
+    --project-slug fixture-app \
+    --release REQ-100 \
+    --outcome passed \
+    --executor "Jane Reviewer" \
+    --tested-sha abc123def456 \
+    --build-version build-42 \
+    --checklist-ref compliance/evidence/REQ-100/uat-checklist.md \
+    --evidence-ref https://devaudit.example.test/projects/fixture-app/releases/release-1 \
+    --executed-at 2026-07-20T12:00:00Z \
+    --output-file "$out" >"$dir/stdout.log" 2>"$dir/stderr.log" && exit_code=0 || exit_code=$?
+  if [ "$exit_code" -eq 0 ]; then ok "exit code 0"; else no "expected exit 0"; fi
+  assert_contains "called start" "CALL:start" "$dir/uat.log"
+  assert_contains "called complete" "CALL:complete" "$dir/uat.log"
+  assert_contains "stage 4" "--sdlc-stage 4" "$dir/uat.log"
+  assert_contains "uat environment" "--environment uat" "$dir/uat.log"
+  assert_contains "uat kind" "--suite-kind uat" "$dir/uat.log"
+  assert_contains "manual provider" "--provider manual_uat" "$dir/uat.log"
+  assert_contains "tested sha" "--commit-sha abc123def456" "$dir/uat.log"
+  assert_contains "passed outcome" "--outcome passed" "$dir/uat.log"
+  assert_contains "executor provenance" "executor=Jane Reviewer" "$dir/uat.log"
+  if grep -q '^uat_execution_id=' "$out"; then ok "output execution id"; else no "missing output execution id"; fi
+  rm -rf "$dir"
+}
+
+case_idempotency_is_stable() {
+  echo "case: derived execution id is stable for repeat command"
+  local dir out1 out2 id1 id2
+  dir=$(mktemp -d)
+  make_fixture "$dir"
+  out1="$dir/out1.env"
+  out2="$dir/out2.env"
+  run_helper "$dir" --project-slug fixture-app --release REQ-100 --outcome passed --executor "Jane Reviewer" --tested-sha abc123def456 --executed-at 2026-07-20T12:00:00Z --output-file "$out1" >/dev/null
+  run_helper "$dir" --project-slug fixture-app --release REQ-100 --outcome passed --executor "Jane Reviewer" --tested-sha abc123def456 --executed-at 2026-07-20T13:00:00Z --output-file "$out2" >/dev/null
+  id1=$(grep '^uat_idempotency_key=' "$out1")
+  id2=$(grep '^uat_idempotency_key=' "$out2")
+  if [ "$id1" = "$id2" ]; then ok "stable idempotency key"; else no "idempotency key changed"; fi
+  rm -rf "$dir"
+}
+
+case_failed_records_remediation() {
+  echo "case: failed UAT includes remediation reference"
+  local dir
+  dir=$(mktemp -d)
+  make_fixture "$dir"
+  run_helper "$dir" \
+    --project-slug fixture-app \
+    --release REQ-100 \
+    --outcome failed \
+    --executor "Jane Reviewer" \
+    --tested-sha abc123def456 \
+    --remediation-ref https://github.com/example/repo/issues/10 \
+    >/dev/null
+  assert_contains "failed outcome" "--outcome failed" "$dir/uat.log"
+  assert_contains "incident reference" "--incident-reference https://github.com/example/repo/issues/10" "$dir/uat.log"
+  rm -rf "$dir"
+}
+
+case_invalid_outcome_fails_before_calls() {
+  echo "case: invalid outcome fails before lifecycle calls"
+  local dir exit_code
+  dir=$(mktemp -d)
+  make_fixture "$dir"
+  run_helper "$dir" --project-slug fixture-app --release REQ-100 --outcome green --executor Jane --tested-sha abc123 >/dev/null 2>"$dir/stderr.log" && exit_code=0 || exit_code=$?
+  if [ "$exit_code" -ne 0 ]; then ok "exit code non-zero"; else no "expected non-zero"; fi
+  if [ ! -f "$dir/uat.log" ]; then ok "no lifecycle call"; else no "unexpected lifecycle call"; fi
+  rm -rf "$dir"
+}
+
+case_passed_records_stage_four_pair
+case_idempotency_is_stable
+case_failed_records_remediation
+case_invalid_outcome_fails_before_calls
+
+echo ""
+echo "=== record-uat-execution.test.sh: $PASS passed, $FAIL failed ==="
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi