@metasession.co/devaudit-cli 0.1.0 → 0.1.2

package/sdlc/files/_common/scripts/submit-for-uat-review.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# submit-for-uat-review.sh — Run readiness checks, then submit a release for UAT review.
+#
+# Usage:
+#   ./scripts/submit-for-uat-review.sh <project-slug> <version-prefix>
+#
+# Example:
+#   ./scripts/submit-for-uat-review.sh wawagardenbar-app v2026.05.14
+#
+# Required environment:
+#   DEVAUDIT_USER_TOKEN — Personal Access Token (mctok_…) issued from
+#                            /settings/tokens. Attributes the submission
+#                            to the issuing user so the four-eyes approval
+#                            control is preserved (the submitter cannot
+#                            approve their own release).
+#   DEVAUDIT_API_KEY    — project-scoped API key (existing) used to
+#                            resolve the release id and read its current
+#                            status. Distinct from the PAT.
+#   DEVAUDIT_BASE_URL   — DevAudit base URL (e.g. https://devaudit.metasession.co).
+#
+# What it does:
+#   1. Verify working tree is clean and develop is up-to-date with origin.
+#   2. Verify the release ticket exists in compliance/pending-releases/.
+#   3. Verify CI gates green on the current develop HEAD via gh CLI.
+#   4. Resolve the release id from (projectSlug, versionPrefix) via /api/ci/releases/resolve.
+#   5. If status is draft        → POST /api/releases/<id>/submit-review with the PAT.
+#      If status is uat_review   → idempotent no-op (exit 0, "already submitted").
+#      If status is uat_approved → idempotent no-op (exit 0, "already approved").
+#      Any other status          → refuse with an explanatory message.
+
+set -euo pipefail
+
+PROJECT_SLUG="${1:-}"
+VERSION_PREFIX="${2:-}"
+
+if [ -z "$PROJECT_SLUG" ] || [ -z "$VERSION_PREFIX" ]; then
+  echo "Usage: $0 <project-slug> <version-prefix>" >&2
+  echo "Example: $0 wawagardenbar-app v2026.05.14" >&2
+  exit 1
+fi
+
+: "${DEVAUDIT_USER_TOKEN:?DEVAUDIT_USER_TOKEN must be set (issue from /settings/tokens)}"
+: "${DEVAUDIT_API_KEY:?DEVAUDIT_API_KEY must be set (project API key)}"
+: "${DEVAUDIT_BASE_URL:?DEVAUDIT_BASE_URL must be set (e.g. https://devaudit.metasession.co)}"
+
+BASE_URL="${DEVAUDIT_BASE_URL%/}"
+
+FAILED=0
+note() { printf '  - %s\n' "$*"; }
+fail() { printf '  ✗ %s\n' "$*"; FAILED=$((FAILED + 1)); }
+ok()   { printf '  ✓ %s\n' "$*"; }
+
+echo "Readiness checks for ${PROJECT_SLUG} ${VERSION_PREFIX}"
+
+# 1. Working tree clean
+if [ -n "$(git status --porcelain)" ]; then
+  fail "Working tree has uncommitted changes — commit or stash before submitting."
+else
+  ok "Working tree clean."
+fi
+
+# 2. develop up-to-date with origin
+git fetch origin develop --quiet
+LOCAL_SHA="$(git rev-parse develop 2>/dev/null || echo '')"
+REMOTE_SHA="$(git rev-parse origin/develop 2>/dev/null || echo '')"
+if [ -z "$LOCAL_SHA" ] || [ -z "$REMOTE_SHA" ]; then
+  fail "Cannot resolve develop SHA — is the develop branch present?"
+elif [ "$LOCAL_SHA" != "$REMOTE_SHA" ]; then
+  fail "Local develop (${LOCAL_SHA:0:7}) does not match origin/develop (${REMOTE_SHA:0:7}) — push first."
+else
+  ok "develop is up-to-date with origin (${LOCAL_SHA:0:7})."
+fi
+
+# 3. Release ticket exists somewhere under compliance/pending-releases/
+TICKETS=$(find compliance/pending-releases -maxdepth 1 -name 'RELEASE-TICKET-*.md' 2>/dev/null | head -5 || true)
+if [ -z "$TICKETS" ]; then
+  fail "No RELEASE-TICKET-*.md found in compliance/pending-releases/."
+else
+  ok "Release ticket present:$(echo "$TICKETS" | sed 's|.*/| |g' | tr '\n' ' ')"
+fi
+
+# 4. CI gates green on current develop HEAD (if gh CLI available)
+if command -v gh >/dev/null 2>&1; then
+  CI_CONCLUSIONS=$(gh run list --branch develop --commit "$REMOTE_SHA" --limit 10 --json conclusion,status,name 2>/dev/null || echo '[]')
+  if [ "$CI_CONCLUSIONS" = '[]' ]; then
+    fail "No CI runs found for ${REMOTE_SHA:0:7} — has the push reached GitHub Actions yet?"
+  else
+    INCOMPLETE=$(echo "$CI_CONCLUSIONS" | jq -r '[.[] | select(.status != "completed")] | length')
+    FAILED_RUNS=$(echo "$CI_CONCLUSIONS" | jq -r '[.[] | select(.conclusion == "failure" or .conclusion == "cancelled")] | length')
+    if [ "$INCOMPLETE" -gt 0 ]; then
+      fail "CI still running on ${REMOTE_SHA:0:7} (${INCOMPLETE} in-flight)."
+    elif [ "$FAILED_RUNS" -gt 0 ]; then
+      fail "CI failed on ${REMOTE_SHA:0:7} (${FAILED_RUNS} runs failed)."
+    else
+      ok "CI gates green on ${REMOTE_SHA:0:7}."
+    fi
+  fi
+else
+  note "gh CLI not available — skipping CI-green check. Verify in GitHub UI."
+fi
+
+# 5. Resolve release id from (projectSlug, versionPrefix)
+RESOLVE_URL="${BASE_URL}/api/ci/releases/resolve?projectSlug=${PROJECT_SLUG}&versionPrefix=${VERSION_PREFIX}"
+RESOLVE=$(curl -s -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" "$RESOLVE_URL")
+RELEASE_ID=$(echo "$RESOLVE" | jq -r '.latest.id // empty')
+RELEASE_STATUS=$(echo "$RESOLVE" | jq -r '.latest.status // empty')
+RELEASE_VERSION=$(echo "$RESOLVE" | jq -r '.latest.version // empty')
+
+if [ -z "$RELEASE_ID" ]; then
+  fail "No release found in DevAudit for ${PROJECT_SLUG} ${VERSION_PREFIX} (has CI uploaded evidence yet?)."
+else
+  ok "Release found: ${RELEASE_VERSION} (id ${RELEASE_ID:0:8}…, status ${RELEASE_STATUS})."
+fi
+
+if [ "$FAILED" -gt 0 ]; then
+  echo ""
+  echo "Refusing to submit — ${FAILED} readiness check(s) failed."
+  exit 1
+fi
+
+# 6. Idempotent dispatch on release status
+case "$RELEASE_STATUS" in
+  draft)
+    echo ""
+    echo "Submitting ${RELEASE_VERSION} for UAT review…"
+    SUBMIT_URL="${BASE_URL}/api/releases/${RELEASE_ID}/submit-review"
+    RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
+      -H "X-DevAudit-Token: ${DEVAUDIT_USER_TOKEN}" \
+      -H "Content-Type: application/json" \
+      "$SUBMIT_URL")
+    HTTP_CODE=$(echo "$RESPONSE" | tail -1)
+    BODY=$(echo "$RESPONSE" | sed '$d')
+    if [ "$HTTP_CODE" = "200" ]; then
+      NEW_STATUS=$(echo "$BODY" | jq -r '.status')
+      echo "  Status: draft → ${NEW_STATUS}"
+      echo "  Review page: ${BASE_URL}/projects/${PROJECT_SLUG}/releases/${RELEASE_ID}?env=uat"
+    else
+      echo "  Submission failed (HTTP ${HTTP_CODE}): $(echo "$BODY" | jq -r '.error // .')" >&2
+      exit 1
+    fi
+    ;;
+  uat_review)
+    echo ""
+    echo "Release already submitted for UAT review (status: uat_review). No action taken."
+    echo "Review page: ${BASE_URL}/projects/${PROJECT_SLUG}/releases/${RELEASE_ID}?env=uat"
+    ;;
+  uat_approved | prod_review | prod_approved | released)
+    echo ""
+    echo "Release has progressed past UAT review (status: ${RELEASE_STATUS}). No action taken."
+    echo "Release page: ${BASE_URL}/projects/${PROJECT_SLUG}/releases/${RELEASE_ID}"
+    ;;
+  uat_rejected | prod_rejected)
+    echo ""
+    echo "Release is in a rejected state (status: ${RELEASE_STATUS}). Address review comments and push a fix before resubmitting." >&2
+    exit 2
+    ;;
+  *)
+    echo ""
+    echo "Release in unexpected status: ${RELEASE_STATUS}. Refusing to submit." >&2
+    exit 2
+    ;;
+esac

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

@@ -0,0 +1,83 @@
+#!/bin/bash
+# validate-commits.sh — Validates commit conventions on PRs.
+#
+# Usage:
+#   ./scripts/validate-commits.sh [base-branch]
+#
+# Checks all commits in the PR for:
+# - Conventional Commits format (type: description or type(scope): description)
+# - Co-Authored-By tag on commits touching code files (warning)
+# - Ref: REQ-XXX on commits related to tracked requirements (warning)
+#
+# Install: cp this file to your project's scripts/ directory && chmod +x scripts/validate-commits.sh
+
+set -euo pipefail
+
+BASE_BRANCH="${1:-origin/main}"
+EXIT_CODE=0
+WARN_COUNT=0
+
+echo "=== Commit Convention Validation ==="
+echo "Comparing: $BASE_BRANCH...HEAD"
+echo ""
+
+# Conventional Commit regex: type(optional-scope): description
+CC_REGEX='^(feat|fix|docs|test|refactor|chore|compliance|security|perf|ci|build|revert)(\([a-zA-Z0-9_-]+\))?!?: .+'
+
+COMMITS=$(git log "$BASE_BRANCH"..HEAD --format='%H' || true)
+
+if [ -z "$COMMITS" ]; then
+  echo "No commits found between $BASE_BRANCH and HEAD."
+  exit 0
+fi
+
+TOTAL=0
+FAILED=0
+
+while IFS= read -r sha; do
+  TOTAL=$((TOTAL + 1))
+  SUBJECT=$(git log -1 --format='%s' "$sha")
+  BODY=$(git log -1 --format='%B' "$sha")
+  SHORT=$(git log -1 --format='%h' "$sha")
+
+  # Check Conventional Commits format
+  if ! echo "$SUBJECT" | grep -qE "$CC_REGEX"; then
+    # Allow merge commits
+    if echo "$SUBJECT" | grep -q '^Merge '; then
+      continue
+    fi
+    echo "ERROR [$SHORT]: Not Conventional Commits format: \"$SUBJECT\""
+    FAILED=$((FAILED + 1))
+    EXIT_CODE=1
+    continue
+  fi
+
+  # Check Co-Authored-By on commits that touch code files
+  CODE_FILES=$(git diff-tree --no-commit-id --name-only -r "$sha" -- '*.ts' '*.tsx' '*.js' '*.jsx' '*.py' 2>/dev/null || true)
+  if [ -n "$CODE_FILES" ]; then
+    if ! echo "$BODY" | grep -qi 'Co-Authored-By:'; then
+      echo "WARNING [$SHORT]: Touches code files but missing Co-Authored-By tag"
+      WARN_COUNT=$((WARN_COUNT + 1))
+    fi
+  fi
+
+  # Check Ref: REQ-XXX on requirement-related commits
+  if echo "$BODY" | grep -qi 'compliance\|requirement\|REQ-'; then
+    if ! echo "$BODY" | grep -qP 'Ref:\s*REQ-\d+'; then
+      echo "WARNING [$SHORT]: Appears requirement-related but missing Ref: REQ-XXX"
+      WARN_COUNT=$((WARN_COUNT + 1))
+    fi
+  fi
+
+done <<< "$COMMITS"
+
+echo ""
+echo "Checked $TOTAL commits: $FAILED errors, $WARN_COUNT warnings."
+
+if [ $EXIT_CODE -eq 0 ]; then
+  echo "=== Commit convention check passed ==="
+else
+  echo "=== FAILED: $FAILED commits do not follow Conventional Commits format ==="
+fi
+
+exit $EXIT_CODE

package/sdlc/files/_common/scripts/validate-compliance-artifacts.sh

@@ -0,0 +1,202 @@
+#!/bin/bash
+# validate-compliance-artifacts.sh — Validates compliance artifacts exist on PRs to main.
+#
+# Usage:
+#   ./scripts/validate-compliance-artifacts.sh [base-branch]
+#
+# Checks that PRs containing tracked requirement commits have the required
+# compliance artifacts (test-scope, RTM entry, release ticket, etc.).
+# Designed to run as a CI job on PRs to main.
+#
+# Install: cp this file to your project's scripts/ directory && chmod +x scripts/validate-compliance-artifacts.sh
+
+set -euo pipefail
+
+BASE_BRANCH="${1:-origin/main}"
+EXIT_CODE=0
+
+echo "=== Compliance Artifact Validation ==="
+echo "Comparing: $BASE_BRANCH...HEAD"
+echo ""
+
+# Extract REQ-XXX references from commits in this PR.
+#
+# Requires ≥3 digits so placeholder patterns like `REQ-0XX` (used in
+# commit-body templates referring to a batch of sub-REQs) don't create
+# phantom IDs that block CI — the loose `\d+` would match `REQ-0` from
+# `REQ-0XX` and then ERROR on a missing evidence dir for the phantom
+# `REQ-0`. The project's stable id format is REQ-001 onwards (#232).
+REQUIREMENTS=$(git log "$BASE_BRANCH"..HEAD --format='%B' | grep -oP 'REQ-\d{3,}' | sort -u || true)
+
+if [ -z "$REQUIREMENTS" ]; then
+  echo "No REQ-XXX references found in PR commits — skipping artifact validation."
+  echo "If this PR contains tracked requirements, ensure commits include 'Ref: REQ-XXX'."
+  exit 0
+fi
+
+echo "Requirements found in PR commits: $REQUIREMENTS"
+echo ""
+
+for REQ in $REQUIREMENTS; do
+  echo "--- Checking $REQ ---"
+
+  # Skip REQs that have no RTM row — they're forward-references or
+  # design-discussion mentions in commit bodies, not tracked
+  # requirements for this release. Two practical cases (#232):
+  #   - "REQ-033 is a prereq for REQ-034" — REQ-034 hasn't started.
+  #   - REQ scaffolded then descoped — RTM row removed but old
+  #     `Ref: REQ-XXX` commits still grep-match.
+  # The `| $REQ ` pattern (leading pipe + trailing space) matches the
+  # markdown table row used in RTM, so a substring elsewhere doesn't
+  # accidentally satisfy it.
+  if ! grep -q "| $REQ " compliance/RTM.md 2>/dev/null; then
+    echo "  INFO: $REQ is referenced in commits but has no RTM row — skipping (forward-reference, not a tracked requirement for this release)"
+    continue
+  fi
+
+  # Check evidence directory exists
+  if [ ! -d "compliance/evidence/$REQ" ]; then
+    echo "  ERROR: Evidence directory missing: compliance/evidence/$REQ/"
+    EXIT_CODE=1
+    continue
+  fi
+  echo "  OK: Evidence directory exists"
+
+  # Check test-scope.md exists
+  if [ ! -f "compliance/evidence/$REQ/test-scope.md" ]; then
+    echo "  ERROR: Test scope missing: compliance/evidence/$REQ/test-scope.md"
+    EXIT_CODE=1
+  else
+    echo "  OK: test-scope.md exists"
+  fi
+
+  # Check test-plan.md exists
+  if [ ! -f "compliance/evidence/$REQ/test-plan.md" ]; then
+    echo "  ERROR: Test plan missing: compliance/evidence/$REQ/test-plan.md"
+    EXIT_CODE=1
+  else
+    echo "  OK: test-plan.md exists"
+
+    # Verify test files referenced in test-plan.md exist in the tree.
+    # Two alternatives: directory-prefixed paths (captured whole), and bare
+    # filenames containing .test. / .spec. (captured from the stem, not the
+    # dot — without the leading [\w./-]+ the match would start at `.test.`
+    # and drop the filename entirely). See DevAudit #133.
+    #
+    # mapfile + quoted expansion: without this, tokens like `__tests__/**`
+    # get pathname-expanded by the for-loop and produce phantom "missing"
+    # errors for every real subdirectory. See DevAudit #137.
+    mapfile -t TEST_FILES < <(
+      grep -oP '(?:__tests__/|tests?/|e2e/|spec/)\S+|[\w./-]+\.(?:test|spec)\.\S+' \
+        "compliance/evidence/$REQ/test-plan.md" 2>/dev/null \
+        | sed 's/[`),.;:]*$//' | grep -v '/$' | sort -u || true
+    )
+    if [ "${#TEST_FILES[@]}" -gt 0 ]; then
+      MISSING_TESTS=0
+      for TF in "${TEST_FILES[@]}"; do
+        # Prose glob references like `__tests__/**` describe a directory
+        # set, not a specific file — skip instead of treating as missing.
+        if [[ "$TF" == *[*?]* ]]; then
+          echo "  INFO: Skipping glob reference (not a file path): $TF"
+          continue
+        fi
+        # Try exact path; otherwise search the repo by basename, skipping
+        # node_modules and build/coverage outputs. The previous
+        # `compgen -G "**/X"` form relied on bash globstar to recurse,
+        # but globstar is OFF by default — `**` collapsed to a single
+        # `*` (depth-1 wildcard), so any bare-filename reference whose
+        # actual file lived at depth ≥2 was falsely reported as missing.
+        if [ ! -f "$TF" ] && ! find . \
+             -type d \( -name node_modules -o -name .next -o -name .git \
+                        -o -name playwright-report -o -name coverage \
+                        -o -name dist -o -name build -o -name 'test-results' \) -prune \
+             -o -type f -name "$(basename "$TF")" -print 2>/dev/null \
+             | grep -q .; then
+          echo "  ERROR: Test file referenced in test-plan.md not found: $TF"
+          MISSING_TESTS=$((MISSING_TESTS + 1))
+        fi
+      done
+      if [ "$MISSING_TESTS" -gt 0 ]; then
+        echo "  ERROR: $MISSING_TESTS test file(s) from test-plan.md missing — tests must be written before merge"
+        EXIT_CODE=1
+      else
+        echo "  OK: All test files referenced in test-plan.md exist"
+      fi
+    fi
+  fi
+
+  # Check test-execution-summary.md exists
+  if [ ! -f "compliance/evidence/$REQ/test-execution-summary.md" ]; then
+    echo "  WARNING: Test execution summary missing: compliance/evidence/$REQ/test-execution-summary.md"
+  else
+    echo "  OK: test-execution-summary.md exists"
+  fi
+
+  # Check RTM entry exists and has an accepted terminal status. Accepts
+  # SUPERSEDED as a valid terminal state — used when a REQ is replaced
+  # by a successor (e.g. REQ-030 superseded by REQ-031). Without this
+  # branch every PR with a commit referencing a SUPERSEDED REQ blocks
+  # CI (#232).
+  if grep -q "$REQ" compliance/RTM.md 2>/dev/null; then
+    if grep "$REQ" compliance/RTM.md | grep -q "TESTED - PENDING SIGN-OFF"; then
+      echo "  OK: RTM status is TESTED - PENDING SIGN-OFF"
+    elif grep "$REQ" compliance/RTM.md | grep -q "APPROVED"; then
+      echo "  OK: RTM status is APPROVED"
+    elif grep "$REQ" compliance/RTM.md | grep -q "SUPERSEDED"; then
+      echo "  OK: RTM status is SUPERSEDED"
+    else
+      echo "  WARNING: RTM entry exists but status is not TESTED - PENDING SIGN-OFF"
+    fi
+  else
+    echo "  ERROR: No RTM entry found for $REQ in compliance/RTM.md"
+    EXIT_CODE=1
+  fi
+
+  # Check release ticket exists. Accepts the superseded-releases/
+  # location as a valid terminal home (mirrors pending- and
+  # approved-releases/) so SUPERSEDED REQs don't block CI (#232).
+  TICKET_PATTERN="compliance/pending-releases/RELEASE-TICKET-${REQ}*"
+  APPROVED_PATTERN="compliance/approved-releases/RELEASE-TICKET-${REQ}*"
+  SUPERSEDED_PATTERN="compliance/superseded-releases/RELEASE-TICKET-${REQ}*"
+  if compgen -G "$TICKET_PATTERN" > /dev/null 2>&1 \
+     || compgen -G "$APPROVED_PATTERN" > /dev/null 2>&1 \
+     || compgen -G "$SUPERSEDED_PATTERN" > /dev/null 2>&1; then
+    echo "  OK: Release ticket exists"
+  else
+    echo "  ERROR: Release ticket missing: compliance/pending-releases/RELEASE-TICKET-${REQ}.md"
+    EXIT_CODE=1
+  fi
+
+  # Check implementation-plan.md for MEDIUM/HIGH risk (check RTM for risk level)
+  if grep "$REQ" compliance/RTM.md 2>/dev/null | grep -qiE 'MEDIUM|HIGH'; then
+    if [ ! -f "compliance/evidence/$REQ/implementation-plan.md" ]; then
+      echo "  ERROR: Implementation plan missing for MEDIUM/HIGH risk: compliance/evidence/$REQ/implementation-plan.md"
+      EXIT_CODE=1
+    else
+      echo "  OK: implementation-plan.md exists (MEDIUM/HIGH risk)"
+    fi
+
+    # Check AI prompt log for MEDIUM/HIGH with AI involvement
+    if [ -f "compliance/evidence/$REQ/ai-use-note.md" ] && [ ! -f "compliance/evidence/$REQ/ai-prompts.md" ]; then
+      echo "  WARNING: AI use noted but ai-prompts.md missing for MEDIUM/HIGH risk"
+    fi
+  fi
+
+  echo ""
+done
+
+# Check that RTM was updated in this PR
+if git diff --name-only "$BASE_BRANCH"...HEAD | grep -q 'compliance/RTM.md'; then
+  echo "OK: compliance/RTM.md was updated in this PR"
+else
+  echo "WARNING: compliance/RTM.md was not modified in this PR"
+fi
+
+echo ""
+if [ $EXIT_CODE -eq 0 ]; then
+  echo "=== All compliance artifact checks passed ==="
+else
+  echo "=== FAILED: Missing required compliance artifacts ==="
+fi
+
+exit $EXIT_CODE

package/sdlc/files/_common/scripts/validate-compliance-artifacts.test.sh

@@ -0,0 +1,202 @@
+#!/usr/bin/env bash
+# validate-compliance-artifacts.test.sh — fixture-based tests for #232
+# hardenings (regex tightening, no-RTM-row skip, SUPERSEDED handling).
+#
+# Builds a throwaway git repo per case, populates compliance/ files,
+# runs validate-compliance-artifacts.sh against it, asserts on the exit
+# code and selected log lines.
+#
+# Usage:
+#   ./scripts/validate-compliance-artifacts.test.sh
+#
+# The script is hermetic: it does NOT touch the host repo; everything
+# runs inside a mktemp'd directory that's torn down at the end. Suitable
+# for CI invocation, no extra deps beyond bash + git + grep.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+VALIDATOR="$SCRIPT_DIR/validate-compliance-artifacts.sh"
+[ -x "$VALIDATOR" ] || chmod +x "$VALIDATOR"
+
+PASS=0
+FAIL=0
+
+# --- helpers ---
+
+# Build a fresh git fixture under $1 and cd into it. Initial commit on
+# a `base` branch, then a single feature commit on `feature` whose body
+# the caller seeds via the second argument.
+make_fixture() {
+  local dir="$1" feat_msg="$2"
+  rm -rf "$dir"
+  mkdir -p "$dir"
+  cd "$dir"
+  git init -q --initial-branch=base
+  git config user.email "test@example.com"
+  git config user.name "test"
+  mkdir -p compliance/pending-releases compliance/approved-releases compliance/superseded-releases compliance/evidence
+  printf '# RTM\n\n| ID | Description | Status |\n| --- | --- | --- |\n' > compliance/RTM.md
+  git add . && git commit -q -m "init"
+  git checkout -q -b feature
+  echo "feature change" > feature.txt
+  git add . && git commit -q -m "feat: feature commit
+
+$feat_msg"
+}
+
+# Run the validator against the current fixture's HEAD vs base. Captures
+# stdout to $OUT_FILE and exit code to $EXIT_CODE_VAR.
+run_validator() {
+  set +e
+  OUT_FILE=$(mktemp)
+  bash "$VALIDATOR" base > "$OUT_FILE" 2>&1
+  LAST_EXIT=$?
+  set -e
+}
+
+assert_grep() {
+  local desc="$1" pattern="$2" want_match="$3"
+  if grep -qE "$pattern" "$OUT_FILE"; then
+    found=1
+  else
+    found=0
+  fi
+  if [ "$found" = "$want_match" ]; then
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $desc (want match=$want_match, got=$found, pattern=$pattern)"
+    echo "  --- output ---"
+    sed 's/^/  /' "$OUT_FILE"
+    echo "  ---"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+assert_exit() {
+  local desc="$1" want="$2"
+  if [ "$LAST_EXIT" = "$want" ]; then
+    echo "  PASS: $desc (exit=$LAST_EXIT)"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $desc (want=$want, got=$LAST_EXIT)"
+    echo "  --- output ---"
+    sed 's/^/  /' "$OUT_FILE"
+    echo "  ---"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+WORKDIR=$(mktemp -d -t validate-compliance-test-XXXX)
+trap 'rm -rf "$WORKDIR"' EXIT
+
+# --- case 1: REQ-0XX placeholder is ignored (\d{3,} regex) ---
+
+echo "Case 1: REQ-0XX placeholder doesn't create phantom REQ-0"
+make_fixture "$WORKDIR/case1" "Ref: REQ-0XX/test-scope.md (placeholder for sub-REQs)"
+run_validator
+assert_grep "no phantom REQ-0 surfaced" '^Requirements found in PR commits: REQ-0\b' 0
+assert_grep "skip-validation message present" 'No REQ-XXX references found' 1
+assert_exit "validator exits 0 on placeholder-only commit body" 0
+cd "$WORKDIR"
+
+# --- case 2: REQ-099 mentioned but absent from RTM → INFO + skip ---
+
+echo "Case 2: forward-reference REQ skipped when RTM row absent"
+make_fixture "$WORKDIR/case2" "Ref: REQ-099 (this is a forward-reference, no RTM row)"
+run_validator
+assert_grep "INFO line emitted for forward-reference" 'INFO: REQ-099 is referenced.*no RTM row' 1
+assert_grep "no ERROR for missing evidence dir" 'ERROR: Evidence directory missing.*REQ-099' 0
+assert_exit "validator exits 0 when only forward-references present" 0
+cd "$WORKDIR"
+
+# --- case 3: SUPERSEDED RTM status is accepted ---
+
+echo "Case 3: SUPERSEDED RTM status passes"
+make_fixture "$WORKDIR/case3" "Ref: REQ-030"
+# RTM with SUPERSEDED status; full evidence + ticket present
+{
+  echo '# RTM'
+  echo
+  echo '| ID | Description | Status |'
+  echo '| --- | --- | --- |'
+  echo '| REQ-030 | Replaced by REQ-031 | SUPERSEDED by REQ-031 |'
+} > compliance/RTM.md
+mkdir -p compliance/evidence/REQ-030
+echo "scope" > compliance/evidence/REQ-030/test-scope.md
+echo "plan" > compliance/evidence/REQ-030/test-plan.md
+touch compliance/pending-releases/RELEASE-TICKET-REQ-030.md
+git add . && git commit -q --amend --no-edit
+run_validator
+assert_grep "RTM SUPERSEDED accepted" 'OK: RTM status is SUPERSEDED' 1
+assert_exit "validator exits 0 with SUPERSEDED RTM status" 0
+cd "$WORKDIR"
+
+# --- case 4: SUPERSEDED ticket location is accepted ---
+
+echo "Case 4: superseded-releases/ ticket location accepted"
+make_fixture "$WORKDIR/case4" "Ref: REQ-031"
+{
+  echo '# RTM'
+  echo
+  echo '| ID | Description | Status |'
+  echo '| --- | --- | --- |'
+  echo '| REQ-031 | Successor of REQ-030 | SUPERSEDED by REQ-032 |'
+} > compliance/RTM.md
+mkdir -p compliance/evidence/REQ-031
+echo "scope" > compliance/evidence/REQ-031/test-scope.md
+echo "plan" > compliance/evidence/REQ-031/test-plan.md
+# Only the superseded location — neither pending- nor approved-releases.
+touch compliance/superseded-releases/RELEASE-TICKET-REQ-031.md
+git add . && git commit -q --amend --no-edit
+run_validator
+assert_grep "ticket in superseded-releases/ accepted" 'OK: Release ticket exists' 1
+assert_grep "no missing-ticket ERROR" 'ERROR: Release ticket missing' 0
+assert_exit "validator exits 0 with SUPERSEDED ticket location" 0
+cd "$WORKDIR"
+
+# --- case 5: bare-filename reference resolves to file at depth ≥2 ---
+#
+# Regression for the broken `compgen -G "**/$TF"` search: bash globstar
+# is off by default, so `**` only matched depth-1 paths. A test plan
+# referencing a bare filename (e.g. `inventory-service.list-by-kind.test.ts`)
+# whose actual file lived at `__tests__/services/...` was reported as
+# missing even though it existed. Fix uses `find -name` instead.
+
+echo "Case 5: bare-filename reference resolves to depth-2 test file"
+make_fixture "$WORKDIR/case5" "Ref: REQ-200"
+{
+  echo '# RTM'
+  echo
+  echo '| ID | Description | Status |'
+  echo '| --- | --- | --- |'
+  echo '| REQ-200 | Bare-filename ref test | IN PROGRESS |'
+} > compliance/RTM.md
+mkdir -p compliance/evidence/REQ-200
+echo "scope" > compliance/evidence/REQ-200/test-scope.md
+# Plan references the file by BARE filename (no directory prefix).
+{
+  echo '# Test Plan — REQ-200'
+  echo
+  echo '| AC | Test | Notes |'
+  echo '| --- | --- | --- |'
+  echo '| AC1 | `foo-service.list-by-kind.test.ts` | unit test |'
+} > compliance/evidence/REQ-200/test-plan.md
+# Actual test file lives at depth 2.
+mkdir -p __tests__/services
+echo "// stub" > __tests__/services/foo-service.list-by-kind.test.ts
+echo "summary" > compliance/evidence/REQ-200/test-execution-summary.md
+touch compliance/pending-releases/RELEASE-TICKET-REQ-200.md
+git add . && git commit -q --amend --no-edit
+run_validator
+assert_grep "depth-2 bare filename resolved" 'OK: All test files referenced in test-plan.md exist' 1
+assert_grep "no missing-test ERROR" 'ERROR: Test file referenced in test-plan.md not found' 0
+assert_exit "validator exits 0 with depth-2 bare-filename reference" 0
+cd "$WORKDIR"
+
+# --- summary ---
+
+echo
+echo "=== validate-compliance-artifacts.test.sh: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]