@metasession.co/devaudit-cli 0.3.16 → 0.3.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "description": "DevAudit CLI — installs, syncs, and operates the Metasession SDLC across consumer projects.",
   "type": "module",
   "bin": {
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.8.2",
-    "@metasession.co/devaudit-plugin-sdk": "^0.3.16",
+    "@metasession.co/devaudit-plugin-sdk": "^0.3.18",
     "ajv": "^8.20.0",
     "commander": "^12.1.0",
     "consola": "^3.2.3",

package/sdlc/files/_common/scripts/check-host-deployment.sh

@@ -8,6 +8,7 @@ REPO=""
 SHA=""
 MAX_ATTEMPTS=30
 POLL_SECONDS=10
+OUTPUT_FILE=""
 
 for arg in "$@"; do
   case "$arg" in
@@ -15,6 +16,7 @@ for arg in "$@"; do
     --sha=*) SHA="${arg#*=}" ;;
     --max-attempts=*) MAX_ATTEMPTS="${arg#*=}" ;;
     --poll-seconds=*) POLL_SECONDS="${arg#*=}" ;;
+    --output-file=*) OUTPUT_FILE="${arg#*=}" ;;
     *)
       echo "Unknown argument: $arg" >&2
       exit 2
@@ -23,7 +25,7 @@ for arg in "$@"; do
 done
 
 if [ -z "$REPO" ] || [ -z "$SHA" ]; then
-  echo "Usage: check-host-deployment.sh --repo=<owner/name> --sha=<sha> [--max-attempts=N] [--poll-seconds=N]" >&2
+  echo "Usage: check-host-deployment.sh --repo=<owner/name> --sha=<sha> [--max-attempts=N] [--poll-seconds=N] [--output-file=path]" >&2
   exit 2
 fi
 
@@ -64,43 +66,91 @@ if statuses:
 PY
 }
 
+extract_status_details() {
+  python3 - <<'PY'
+import json
+import os
+
+statuses = json.loads(os.environ.get("STATUSES_JSON", "[]"))
+latest = statuses[0] if statuses else {}
+print(json.dumps({
+    "state": str(latest.get("state") or "").lower(),
+    "description": str(latest.get("description") or ""),
+    "target_url": str(latest.get("target_url") or latest.get("environment_url") or ""),
+    "environment": str(latest.get("environment") or ""),
+}, separators=(",", ":")))
+PY
+}
+
+json_field() {
+  STATUS_DETAILS="$1" FIELD="$2" python3 - <<'PY'
+import json
+import os
+print(json.loads(os.environ["STATUS_DETAILS"]).get(os.environ["FIELD"], ""))
+PY
+}
+
+write_result() {
+  local verification="$1" deployment_id="$2" deployment_state="$3" description="$4" target_url="$5" environment="$6" attempt="$7"
+  [ -n "$OUTPUT_FILE" ] || return 0
+  cat > "$OUTPUT_FILE" <<EOF
+verification=${verification}
+deployment_id=${deployment_id}
+deployment_state=${deployment_state}
+description=${description}
+target_url=${target_url}
+environment=${environment}
+attempt=${attempt}
+elapsed_seconds=$(( (ATTEMPT - 1) * POLL_SECONDS ))
+EOF
+}
+
 for ATTEMPT in $(seq 1 "$MAX_ATTEMPTS"); do
   DEPLOYMENTS_JSON=$(gh api "/repos/${REPO}/deployments?sha=${SHA}&per_page=20")
   DEPLOYMENT_ID=$(DEPLOYMENTS_JSON="$DEPLOYMENTS_JSON" select_deployment_id)
 
   if [ -z "$DEPLOYMENT_ID" ]; then
-    echo "Attempt ${ATTEMPT}/${MAX_ATTEMPTS}: no GitHub deployment found yet for ${SHA}."
+    echo "::notice::deployment verification attempt=${ATTEMPT}/${MAX_ATTEMPTS} sha=${SHA} deployment_id=none state=missing"
     if [ "$ATTEMPT" -lt "$MAX_ATTEMPTS" ]; then
       sleep "$POLL_SECONDS"
       continue
     fi
-    echo "::error::No GitHub deployment was published for ${SHA} after ${MAX_ATTEMPTS} attempts."
+    write_result "deployment_status_missing" "" "" "No GitHub deployment was published for the SHA" "" "" "$ATTEMPT"
+    echo "::error::deployment_status_missing: no GitHub deployment was published for ${SHA} after ${MAX_ATTEMPTS} attempts."
     exit 1
   fi
 
   STATUSES_JSON=$(gh api "/repos/${REPO}/deployments/${DEPLOYMENT_ID}/statuses?per_page=20")
-  DEPLOY_STATE=$(STATUSES_JSON="$STATUSES_JSON" extract_status_state)
+  STATUS_DETAILS=$(STATUSES_JSON="$STATUSES_JSON" extract_status_details)
+  DEPLOY_STATE=$(json_field "$STATUS_DETAILS" state)
+  DESCRIPTION=$(json_field "$STATUS_DETAILS" description)
+  TARGET_URL=$(json_field "$STATUS_DETAILS" target_url)
+  ENVIRONMENT=$(json_field "$STATUS_DETAILS" environment)
+  echo "::notice::deployment verification attempt=${ATTEMPT}/${MAX_ATTEMPTS} sha=${SHA} deployment_id=${DEPLOYMENT_ID} environment=${ENVIRONMENT:-unknown} state=${DEPLOY_STATE:-missing} target_url=${TARGET_URL:-none} elapsed_seconds=$(( (ATTEMPT - 1) * POLL_SECONDS ))"
 
   case "$DEPLOY_STATE" in
     success)
+      write_result "success" "$DEPLOYMENT_ID" "$DEPLOY_STATE" "$DESCRIPTION" "$TARGET_URL" "$ENVIRONMENT" "$ATTEMPT"
       echo "GitHub deployment ${DEPLOYMENT_ID} for ${SHA} reached terminal success."
       exit 0
       ;;
     failure|error)
-      echo "::error::GitHub deployment ${DEPLOYMENT_ID} for ${SHA} reached terminal failure (${DEPLOY_STATE})."
+      write_result "deployment_terminal_failure" "$DEPLOYMENT_ID" "$DEPLOY_STATE" "$DESCRIPTION" "$TARGET_URL" "$ENVIRONMENT" "$ATTEMPT"
+      echo "::error::deployment_terminal_failure: GitHub deployment ${DEPLOYMENT_ID} for ${SHA} reached ${DEPLOY_STATE}. ${DESCRIPTION} ${TARGET_URL}"
       exit 1
       ;;
     queued|in_progress|pending|"")
-      echo "Attempt ${ATTEMPT}/${MAX_ATTEMPTS}: deployment ${DEPLOYMENT_ID} for ${SHA} is ${DEPLOY_STATE:-pending}."
       if [ "$ATTEMPT" -lt "$MAX_ATTEMPTS" ]; then
         sleep "$POLL_SECONDS"
         continue
       fi
-      echo "::error::GitHub deployment ${DEPLOYMENT_ID} for ${SHA} did not reach a terminal success state after ${MAX_ATTEMPTS} attempts."
+      write_result "deployment_status_timeout" "$DEPLOYMENT_ID" "${DEPLOY_STATE:-missing}" "$DESCRIPTION" "$TARGET_URL" "$ENVIRONMENT" "$ATTEMPT"
+      echo "::error::deployment_status_timeout: GitHub deployment ${DEPLOYMENT_ID} for ${SHA} remained ${DEPLOY_STATE:-missing} after ${MAX_ATTEMPTS} attempts. Last target URL: ${TARGET_URL:-none}."
       exit 1
       ;;
     *)
-      echo "::error::Deployment ${DEPLOYMENT_ID} for ${SHA} returned unexpected state '${DEPLOY_STATE}'."
+      write_result "deployment_status_unknown" "$DEPLOYMENT_ID" "$DEPLOY_STATE" "$DESCRIPTION" "$TARGET_URL" "$ENVIRONMENT" "$ATTEMPT"
+      echo "::error::deployment_status_unknown: deployment ${DEPLOYMENT_ID} for ${SHA} returned unexpected state '${DEPLOY_STATE}'. ${DESCRIPTION} ${TARGET_URL}"
       exit 1
       ;;
   esac

package/sdlc/files/_common/scripts/check-host-deployment.test.sh

@@ -67,7 +67,7 @@ run_check() {
   shift 2
   (
     cd "$dir"
-    PATH="$dir/mock-bin:$PATH" "$@" bash "$HELPER" --repo=metasession-dev/example --sha=abc123 --max-attempts=1 --poll-seconds=0
+    PATH="$dir/mock-bin:$PATH" "$@" bash "$HELPER" --repo=metasession-dev/example --sha=abc123 --max-attempts=1 --poll-seconds=0 --output-file="$out.result"
   ) >"$out" 2>&1
 }
 
@@ -87,6 +87,7 @@ else
 fi
 assert_exit "success deployment passes" 0 "$CODE"
 assert_grep "success message emitted" 'terminal success' "$OUT"
+assert_grep "success result is structured" '^verification=success$' "$OUT.result"
 echo ""
 
 echo "--- Test 2: failure status fails ---"
@@ -99,7 +100,8 @@ else
   CODE=$?
 fi
 assert_exit "failed deployment exits 1" 1 "$CODE"
-assert_grep "failure message emitted" 'terminal failure' "$OUT"
+assert_grep "failure message emitted" 'deployment_terminal_failure' "$OUT"
+assert_grep "terminal failure result is structured" '^verification=deployment_terminal_failure$' "$OUT.result"
 echo ""
 
 echo "--- Test 3: missing deployment fails closed ---"
@@ -112,7 +114,37 @@ else
   CODE=$?
 fi
 assert_exit "missing deployment exits 1" 1 "$CODE"
-assert_grep "missing deployment message emitted" 'No GitHub deployment was published' "$OUT"
+assert_grep "missing deployment message emitted" 'deployment_status_missing' "$OUT"
+assert_grep "missing deployment result is structured" '^verification=deployment_status_missing$' "$OUT.result"
+echo ""
+
+echo "--- Test 4: prolonged in-progress status reports timeout ---"
+OUT="$WORK/test4.out"
+if run_check "$WORK" "$OUT" env \
+  MOCK_DEPLOYMENTS_JSON='[{"id":5453707224,"environment":"production"}]' \
+  MOCK_STATUSES_JSON='[{"state":"in_progress","description":"provider still building","environment_url":"https://example.test"}]'; then
+  CODE=0
+else
+  CODE=$?
+fi
+assert_exit "in-progress deployment fails closed" 1 "$CODE"
+assert_grep "timeout classification emitted" 'deployment_status_timeout' "$OUT"
+assert_grep "timeout result is structured" '^verification=deployment_status_timeout$' "$OUT.result"
+assert_grep "timeout retains target URL" '^target_url=https://example.test$' "$OUT.result"
+echo ""
+
+echo "--- Test 5: missing status reports timeout ---"
+OUT="$WORK/test5.out"
+if run_check "$WORK" "$OUT" env \
+  MOCK_DEPLOYMENTS_JSON='[{"id":5453707224,"environment":"production"}]' \
+  MOCK_STATUSES_JSON='[]'; then
+  CODE=0
+else
+  CODE=$?
+fi
+assert_exit "missing status fails closed" 1 "$CODE"
+assert_grep "missing status timeout classification emitted" 'deployment_status_timeout' "$OUT"
+assert_grep "missing status result is structured" '^deployment_state=missing$' "$OUT.result"
 echo ""
 
 echo "=== check-host-deployment.test.sh: $PASS passed, $FAIL failed ==="

package/sdlc/files/_common/scripts/check-release-pr-scope.test.sh

@@ -136,16 +136,17 @@ echo ""
 
 echo "--- Test 5: bare-date releases require an explicit standalone declaration ---"
 make_fixture "$WORK/test5" "chore: standalone housekeeping release"
-cat > "$WORK/test5/compliance/standalone-housekeeping/STANDALONE-HOUSEKEEPING-v2026.07.18.json" <<'EOF'
+BARE_DATE_VERSION="v$(date -u +%Y.%m.%d)"
+cat > "$WORK/test5/compliance/standalone-housekeeping/STANDALONE-HOUSEKEEPING-${BARE_DATE_VERSION}.json" <<EOF
 {
   "schemaVersion": 1,
-  "version": "v2026.07.18",
+  "version": "${BARE_DATE_VERSION}",
   "releaseMode": "standalone_housekeeping",
   "reason": "Urgent operational change cannot wait for the next tracked requirement release."
 }
 EOF
 OUT="$WORK/test5.out"
-if run_check "$WORK/test5" "$OUT" env PR_TITLE="Standalone housekeeping promotion: v2026.07.18" PR_BODY=$'## Release\n- Release: v2026.07.18\n'; then
+if run_check "$WORK/test5" "$OUT" env PR_TITLE="Standalone housekeeping promotion: ${BARE_DATE_VERSION}" PR_BODY=$"## Release\n- Release: ${BARE_DATE_VERSION}\n"; then
   CODE=0
 else
   CODE=$?
@@ -156,16 +157,16 @@ echo ""
 
 echo "--- Test 6: bare-date releases without the exception marker fail ---"
 make_fixture "$WORK/test6" "chore: standalone housekeeping release"
-cat > "$WORK/test6/compliance/standalone-housekeeping/STANDALONE-HOUSEKEEPING-v2026.07.18.json" <<'EOF'
+cat > "$WORK/test6/compliance/standalone-housekeeping/STANDALONE-HOUSEKEEPING-${BARE_DATE_VERSION}.json" <<EOF
 {
   "schemaVersion": 1,
-  "version": "v2026.07.18",
+  "version": "${BARE_DATE_VERSION}",
   "releaseMode": "standalone_housekeeping",
   "reason": "Urgent operational change cannot wait for the next tracked requirement release."
 }
 EOF
 OUT="$WORK/test6.out"
-if run_check "$WORK/test6" "$OUT" env PR_TITLE="Release: v2026.07.18" PR_BODY=$'## Release\n- Release: v2026.07.18\n'; then
+if run_check "$WORK/test6" "$OUT" env PR_TITLE="Release: ${BARE_DATE_VERSION}" PR_BODY=$"## Release\n- Release: ${BARE_DATE_VERSION}\n"; then
   CODE=0
 else
   CODE=$?

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 ]