@metasession.co/devaudit-cli 0.3.9 → 0.3.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "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.9",
+    "@metasession.co/devaudit-plugin-sdk": "^0.3.10",
     "ajv": "^8.20.0",
     "commander": "^12.1.0",
     "consola": "^3.2.3",

package/sdlc/files/_common/joining-an-existing-project.md

@@ -152,9 +152,10 @@ Two distinct credentials exist; conflating them is what causes the silent-CI-tok
 |---|---|---|---|---|
 | **Personal PAT** | `mctok_…` | `~/.config/devaudit/auth.json` (per developer) | You (the user) | Your local CLI commands |
 | **Project API key** | `dak_…` | Repo secret `DEVAUDIT_API_KEY` | The project | CI's `devaudit push` calls |
-| **Operator's PAT** | `mctok_…` | Repo secret `DEVAUDIT_USER_TOKEN` | The operator (singular) | CI's mutation calls (release register, approval submit) |
+| **Operator's PAT** | `mctok_…` | Repo secret `DEVAUDIT_USER_TOKEN` | The operator (singular) | CI's DevAudit portal calls that need human attribution (release submit / approval flows) |
+| **GitHub workflow token** | `${{ github.token }}` | Issued automatically per workflow run | The GitHub Actions workflow | CI's GitHub repo mutations (checkout, branch push, PR, issue, comment, label, check-run updates) |
 
-**Never paste your personal PAT into a repo secret.** Repo `DEVAUDIT_USER_TOKEN` is operator-owned. CI portal mutations are attributed to whoever's PAT is there — if it's yours, your name shows up against every release the team ships, and the moment your PAT expires CI breaks. Rotation belongs to the operator: `devaudit install --force-team-config` on their machine.
+**Never paste your personal PAT into a repo secret.** Repo `DEVAUDIT_USER_TOKEN` is operator-owned and is not the default GitHub auth path for workflow repo mutations. CI portal mutations are attributed to whoever's PAT is there — if it's yours, your name shows up against every release the team ships, and the moment your PAT expires CI portal actions break. Rotation belongs to the operator: `devaudit install --force-team-config` on their machine.
 
 If `devaudit auth status` shows the wrong user, run `devaudit auth logout && devaudit auth login` and paste the right PAT.
 
@@ -181,10 +182,10 @@ The synced CI gates expect a specific environment. Here's what you need locally
 
 | Surface | CI | Local (your machine) |
 |---|---|---|
-| Personal identity | `secrets.DEVAUDIT_USER_TOKEN` (operator's) | `~/.config/devaudit/auth.json` (yours) — `devaudit auth login` |
+| Personal identity | `secrets.DEVAUDIT_USER_TOKEN` (operator's, portal-only) | `~/.config/devaudit/auth.json` (yours) — `devaudit auth login` |
 | Project API key | `secrets.DEVAUDIT_API_KEY` | Usually unset locally — only needed if you're testing `devaudit push` against the live portal; ask the operator if you need to debug it |
 | Portal URL | `vars.DEVAUDIT_BASE_URL` | `~/.config/devaudit/auth.json` (set by `auth login`) or `$DEVAUDIT_BASE_URL` env |
-| GitHub auth | `${{ github.token }}` (auto) | `gh auth login` |
+| GitHub auth | `${{ github.token }}` (auto, repo mutations) | `gh auth login` |
 | Node | matrix-pinned to project's `node_version` | nvm / volta / whatever — `devaudit doctor` checks ≥ 22 |
 | `jq` / `curl` | always present on GH runners | install via package manager — `devaudit doctor` flags absence |
 

package/sdlc/files/_common/scripts/close-out-contract.test.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# close-out-contract.test.sh — Tests for the close-out marker helper.
+#
+# Usage:
+#   ./scripts/close-out-contract.test.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/close-out-contract.sh"
+
+PASS=0
+FAIL=0
+
+assert_eq() {
+  local desc="$1" want="$2" got="$3"
+  if [ "$got" = "$want" ]; then
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $desc"
+    echo "        want: $want"
+    echo "        got:  $got"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+assert_true() {
+  local desc="$1"
+  shift
+  if "$@"; then
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $desc"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+assert_false() {
+  local desc="$1"
+  shift
+  if "$@"; then
+    echo "  FAIL: $desc"
+    FAIL=$((FAIL + 1))
+  else
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  fi
+}
+
+echo "=== close-out-contract.sh tests ==="
+
+assert_eq "branch prefix constant" "chore/close-out-" "$CLOSEOUT_BRANCH_PREFIX"
+assert_eq "marker prefix constant" "Release-Closeout:" "$CLOSEOUT_MARKER_PREFIX"
+assert_eq "closeout_marker emits structured line" "Release-Closeout: REQ-090" "$(closeout_marker REQ-090)"
+
+assert_true "is_closeout_marker accepts canonical marker" is_closeout_marker "Release-Closeout: REQ-090"
+assert_true "is_closeout_marker accepts extra whitespace" is_closeout_marker "Release-Closeout:    REQ-123"
+assert_false "is_closeout_marker rejects wrong prefix" is_closeout_marker "Closeout: REQ-090"
+assert_false "is_closeout_marker rejects short req ids" is_closeout_marker "Release-Closeout: REQ-9"
+assert_false "is_closeout_marker rejects bare prose mention" is_closeout_marker "This closes REQ-090 after release."
+
+assert_eq "closeout_marker_req extracts req id" "REQ-090" "$(closeout_marker_req "Release-Closeout: REQ-090")"
+assert_eq "closeout_marker_req extracts first req id from mixed text" "REQ-111" "$(closeout_marker_req $'x\nRelease-Closeout: REQ-111\nmore')"
+assert_eq "closeout_marker_req returns empty when marker absent" "" "$(closeout_marker_req "no marker here" || true)"
+
+echo
+echo "Result: $PASS passed, $FAIL failed"
+[ "$FAIL" = "0" ]

package/sdlc/files/_common/scripts/prepare-release-pr.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# prepare-release-pr.sh — ensure there is one truthful release PR.
+#
+# Usage:
+#   ./scripts/prepare-release-pr.sh [--apply] [--mode=update|recreate]
+#
+# Default mode is dry-run + update. Dry-run prints the action it would take.
+# With --apply:
+#   - no existing PR: creates one
+#   - current PR: updates title/body only when needed
+#   - stale PR + mode=update: rewrites title/body and comments
+#   - stale PR + mode=recreate: closes old PR and opens a fresh one
+
+set -euo pipefail
+
+APPLY=false
+MODE="update"
+for arg in "$@"; do
+  case "$arg" in
+    --apply) APPLY=true ;;
+    --mode=update) MODE="update" ;;
+    --mode=recreate) MODE="recreate" ;;
+    *) echo "Unknown argument: $arg" >&2; exit 2 ;;
+  esac
+done
+
+INTEGRATION_BRANCH=$(jq -r '.integration_branch // "develop"' sdlc-config.json 2>/dev/null || echo "develop")
+RELEASE_BRANCH=$(jq -r '.release_branch // "main"' sdlc-config.json 2>/dev/null || echo "main")
+
+if [ ! -x scripts/derive-release-version.sh ]; then
+  chmod +x scripts/derive-release-version.sh 2>/dev/null || true
+fi
+CURRENT_RELEASE=$(./scripts/derive-release-version.sh)
+if [ -z "$CURRENT_RELEASE" ]; then
+  echo "No active release version derived; close-out reconciliation appears in progress." >&2
+  exit 1
+fi
+
+TITLE="Release: ${CURRENT_RELEASE}"
+BODY=$(cat <<EOF
+## Release
+
+- Release: ${CURRENT_RELEASE}
+- Base: ${RELEASE_BRANCH}
+- Head: ${INTEGRATION_BRANCH}
+
+## DevAudit
+
+- Release context is derived from the current ${INTEGRATION_BRANCH} head.
+- If this PR replaced an older release PR, the older PR was superseded because it no longer matched the governing release context.
+EOF
+)
+
+OPEN_PRS=$(gh pr list --base "$RELEASE_BRANCH" --head "$INTEGRATION_BRANCH" --state open --json number,title,body,url --limit 10)
+COUNT=$(echo "$OPEN_PRS" | jq 'length')
+
+if [ "$COUNT" -eq 0 ]; then
+  echo "No open ${INTEGRATION_BRANCH}->${RELEASE_BRANCH} PR found."
+  if [ "$APPLY" = "true" ]; then
+    gh pr create --base "$RELEASE_BRANCH" --head "$INTEGRATION_BRANCH" --title "$TITLE" --body "$BODY"
+  else
+    echo "Dry run: would create release PR titled '$TITLE'."
+  fi
+  exit 0
+fi
+
+if [ "$COUNT" -gt 1 ]; then
+  echo "ERROR: ${COUNT} open ${INTEGRATION_BRANCH}->${RELEASE_BRANCH} PRs found. Resolve duplicates manually." >&2
+  echo "$OPEN_PRS" | jq -r '.[] | "  #\(.number) \(.title) \(.url)"' >&2
+  exit 1
+fi
+
+PR_NUMBER=$(echo "$OPEN_PRS" | jq -r '.[0].number')
+PR_TITLE=$(echo "$OPEN_PRS" | jq -r '.[0].title // ""')
+PR_BODY=$(echo "$OPEN_PRS" | jq -r '.[0].body // ""')
+PR_URL=$(echo "$OPEN_PRS" | jq -r '.[0].url')
+
+if printf '%s\n%s\n' "$PR_TITLE" "$PR_BODY" | grep -q "$CURRENT_RELEASE"; then
+  echo "Open release PR #${PR_NUMBER} already matches ${CURRENT_RELEASE}: ${PR_URL}"
+  exit 0
+fi
+
+echo "Open release PR #${PR_NUMBER} is stale for current release ${CURRENT_RELEASE}: ${PR_URL}"
+echo "Current title: ${PR_TITLE}"
+
+if [ "$APPLY" != "true" ]; then
+  echo "Dry run: would ${MODE} stale PR #${PR_NUMBER} for ${CURRENT_RELEASE}."
+  exit 0
+fi
+
+if [ "$MODE" = "recreate" ]; then
+  gh pr comment "$PR_NUMBER" --body "Superseded: current ${INTEGRATION_BRANCH} head now derives ${CURRENT_RELEASE}; this PR no longer matches the governing release context."
+  gh pr close "$PR_NUMBER" --comment "Closed as superseded by ${CURRENT_RELEASE} release context."
+  gh pr create --base "$RELEASE_BRANCH" --head "$INTEGRATION_BRANCH" --title "$TITLE" --body "$BODY"
+else
+  gh pr edit "$PR_NUMBER" --title "$TITLE" --body "$BODY"
+  gh pr comment "$PR_NUMBER" --body "Release PR context refreshed: current ${INTEGRATION_BRANCH} head derives ${CURRENT_RELEASE}."
+  echo "Updated PR #${PR_NUMBER} to ${CURRENT_RELEASE}: ${PR_URL}"
+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

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

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# validate-commits.test.sh — Fixture-based tests for validate-commits.sh.
+#
+# Covers the relaxed "exactly one active tracked release" behavior:
+# implementation commits without REQ tags downgrade to warnings only when
+# release context is unambiguous; otherwise they remain hard errors.
+#
+# Usage:
+#   ./scripts/validate-commits.test.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+VALIDATOR="$SCRIPT_DIR/validate-commits.sh"
+[ -x "$VALIDATOR" ] || chmod +x "$VALIDATOR"
+
+PASS=0
+FAIL=0
+
+make_fixture() {
+  local dir="$1" subject="$2" body="${3:-}"
+  rm -rf "$dir"
+  mkdir -p "$dir"
+  cd "$dir"
+  git init -q --initial-branch=main
+  git config user.email "test@example.com"
+  git config user.name "test"
+  echo "base" > base.txt
+  git add base.txt
+  git commit -q -m "chore: base"
+
+  git checkout -q -b feature
+  echo "feature" > app.ts
+  git add app.ts
+  if [ -n "$body" ]; then
+    git commit -q -m "$subject" -m "$body"
+  else
+    git commit -q -m "$subject"
+  fi
+}
+
+run_validator() {
+  set +e
+  OUT_FILE=$(mktemp)
+  bash "$VALIDATOR" main > "$OUT_FILE" 2>&1
+  LAST_EXIT=$?
+  set -e
+}
+
+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)"
+    sed 's/^/    /' "$OUT_FILE"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+assert_grep() {
+  local desc="$1" pattern="$2" want_match="$3"
+  local found=0
+  if grep -qE "$pattern" "$OUT_FILE"; then
+    found=1
+  fi
+  if [ "$found" = "$want_match" ]; then
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $desc (want match=$want_match, got=$found, pattern=$pattern)"
+    sed 's/^/    /' "$OUT_FILE"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+WORKDIR=$(mktemp -d -t validate-commits-test-XXXX)
+trap 'rm -rf "$WORKDIR"' EXIT
+
+echo "=== validate-commits.sh tests ==="
+
+# Case 1: one active pending ticket makes a missing-REQ implementation
+# commit a warning, not a hard failure.
+echo "Case 1: single active pending release downgrades missing REQ to warning"
+make_fixture "$WORKDIR/case1" "feat: implement kitchen workflow" "Co-Authored-By: Test <test@example.com>"
+mkdir -p compliance/pending-releases
+cat > compliance/pending-releases/RELEASE-TICKET-REQ-123.md <<'EOF'
+# Release Ticket: REQ-123
+EOF
+git add compliance/pending-releases
+git commit -q --amend --no-edit
+run_validator
+assert_exit "single active pending release exits 0" 0
+assert_grep "warning emitted for missing REQ with one active release" 'WARNING .*one active tracked release \(REQ-123\)' 1
+assert_grep "no hard error for missing requirement" "ERROR .*implementation commit but cites no requirement" 0
+
+# Case 2: ambiguous pending release context keeps the missing-REQ path as
+# a hard error.
+echo "Case 2: two active pending releases keep missing REQ as hard error"
+make_fixture "$WORKDIR/case2" "feat: implement kitchen workflow" "Co-Authored-By: Test <test@example.com>"
+mkdir -p compliance/pending-releases
+cat > compliance/pending-releases/RELEASE-TICKET-REQ-123.md <<'EOF'
+# Release Ticket: REQ-123
+EOF
+cat > compliance/pending-releases/RELEASE-TICKET-REQ-124.md <<'EOF'
+# Release Ticket: REQ-124
+EOF
+git add compliance/pending-releases
+git commit -q --amend --no-edit
+run_validator
+assert_exit "ambiguous pending releases exits 1" 1
+assert_grep "hard error emitted when active context is ambiguous" "ERROR .*implementation commit but cites no requirement" 1
+
+# Case 3: no pending ticket, but exactly one active RTM row in the
+# accepted statuses also downgrades to a warning.
+echo "Case 3: RTM fallback with one active row downgrades missing REQ to warning"
+make_fixture "$WORKDIR/case3" "fix: recover already-merged history" "Co-Authored-By: Test <test@example.com>"
+mkdir -p compliance
+cat > compliance/RTM.md <<'EOF'
+# RTM
+| REQ-ID  | Title | Status                    |
+| ------- | ----- | ------------------------- |
+| REQ-200 | Done  | APPROVED - DEPLOYED       |
+| REQ-201 | Live  | TESTED - PENDING SIGN-OFF |
+EOF
+git add compliance/RTM.md
+git commit -q --amend --no-edit
+run_validator
+assert_exit "single active RTM row exits 0" 0
+assert_grep "warning emitted for RTM fallback context" 'WARNING .*one active tracked release \(REQ-201\)' 1
+assert_grep "no hard error under single RTM fallback context" "ERROR .*implementation commit but cites no requirement" 0
+
+# Case 4: zero active context remains a hard error.
+echo "Case 4: no active release context keeps missing REQ as hard error"
+make_fixture "$WORKDIR/case4" "perf: tune kitchen workflow" "Co-Authored-By: Test <test@example.com>"
+run_validator
+assert_exit "no active context exits 1" 1
+assert_grep "hard error emitted without any active release context" "ERROR .*implementation commit but cites no requirement" 1
+
+echo
+echo "Result: $PASS passed, $FAIL failed"
+[ "$FAIL" = "0" ]

package/sdlc/files/_common/skills/sdlc-implementer/SKILL.md

@@ -553,7 +553,17 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
 
 ### Phase 4 — Submit for UAT review (SDLC stage 4)
 
-1. **Open the release PR** — the PR that carries the UAT four-eyes approval gate (`check-release-approval.yml`), always into `$RELEASE_BRANCH`: `gh pr create --base "$RELEASE_BRANCH" --head "$INTEGRATION_BRANCH"` (e.g. `develop → main`). The implementation already landed on `$INTEGRATION_BRANCH` in Phase 2; this promotes it. (Note: if other work is also waiting on `$INTEGRATION_BRANCH`, this is a bundled release — every in-scope REQ keeps its own release record and Production approval.)
+1. **Prepare the truthful release PR** — the PR that carries the UAT four-eyes approval gate (`check-release-approval.yml`), always into `$RELEASE_BRANCH` from `$INTEGRATION_BRANCH` (e.g. `develop → main`). The implementation already landed on `$INTEGRATION_BRANCH` in Phase 2; this promotes it. (Note: if other work is also waiting on `$INTEGRATION_BRANCH`, this is a bundled release — every in-scope REQ keeps its own release record and Production approval.)
+
+   Before creating a PR manually, run the synced helper:
+
+   ```bash
+   ./scripts/prepare-release-pr.sh --apply --mode=update
+   ```
+
+   This is mandatory for devaudit-installer#312. It detects an existing open `$INTEGRATION_BRANCH → $RELEASE_BRANCH` PR, derives the current governing release from the current head, and ensures there is exactly one truthful release PR. If the existing PR is stale, the default `update` mode rewrites the title/body and comments with the refresh. Use `--mode=recreate` only when the operator explicitly wants the older PR closed and a new PR opened.
+
+   If the helper reports multiple open release PRs, halt with: "Multiple open release PRs for `$INTEGRATION_BRANCH → $RELEASE_BRANCH`; operator action — close duplicates or choose the authoritative PR, then resume REQ-XXX." Do not open another PR.
 
    PR body per the SDLC PR template (see [`.github/pull_request_template.md`](../../../../../.github/pull_request_template.md)):
    - Closes #N
@@ -571,8 +581,30 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
 
 3. **Apply labels** — `awaiting-uat-review`, `risk:<class>`.
 4. **Comment on the issue**: "Implementation complete. PR #M opened. Evidence on portal: <link>. UAT review requested. Resume with `resume REQ-XXX` once UAT approval is granted on the portal."
-5. **Hard stop.** Phase 4 ends here. Do not proceed to merge; the human's next action is reviewing on the portal.
-6. **Update SDLC status sticky** before halting: `bash scripts/update-sdlc-status.sh "$ISSUE_NUM" "Phase 4 — release PR #<N> opened against $RELEASE_BRANCH; CI running" "Operator action — review PR #<N> + approve UAT release on the portal; sdlc-implementer halts until you ping resume REQ-XXX"`. This is a critical handoff — the sticky must reflect that the agent has stopped + the operator is on the hook.
+5. **Inspect PR blockers before handoff (devaudit-installer#304).** Run `gh pr view <N> --json mergeStateStatus,reviewDecision,statusCheckRollup,url` and categorize the state:
+   - `reviewDecision` not approved → human approval blocker; hand off to the reviewer.
+   - Release Approval Gate failing while portal state is not `uat_approved` → portal approval blocker; hand off to portal UAT reviewer.
+   - Release Approval Gate failing while portal state is `uat_approved` → retry path below.
+   - Compliance validation / evidence completeness failing → real workflow or evidence defect; fix or create a follow-up PR before handoff.
+   - Checks pending → wait/poll until terminal before declaring the PR ready.
+   - Stale PR context detected by `prepare-release-pr.sh` → rerun the helper in `--apply` mode and repeat this blocker inspection.
+
+   **Executable loop (devaudit-installer#304).** Use the bundled watcher rather than a one-shot `gh` read when the PR is blocked or waiting:
+
+   ```bash
+   node SDLC/bin/devaudit-sdlc.js \
+     --watch-pr=<N> \
+     --repo <owner/name> \
+     --req XXX \
+     --release REQ-XXX \
+     --project-slug <project-slug> \
+     --base-url <devaudit-base-url>
+   ```
+
+   The watcher persists retry state in `.sdlc-pr-watch.json`, polls `gh pr view` + `gh pr checks`, re-runs likely flaky workflows automatically, and re-runs the Release Approval Gate when the portal is already approved but GitHub has not converged yet. Use `--once` when you only need a single classification pass.
+
+6. **Hard stop only after blocker classification.** Phase 4 ends here. Do not proceed to merge; the human's next action is reviewing on the portal or clearing the categorized blocker above.
+7. **Update SDLC status sticky** before halting: `bash scripts/update-sdlc-status.sh "$ISSUE_NUM" "Phase 4 — truthful release PR #<N> prepared against $RELEASE_BRANCH; blockers classified" "Operator action — review PR #<N> + approve UAT release on the portal; sdlc-implementer halts until you ping resume REQ-XXX"`. This is a critical handoff — the sticky must reflect that the agent has stopped + the operator is on the hook.
 
 **When an external gate hangs or fails for unrelated reasons.** A required gate may fail for reasons outside the change's scope — flaky infra, an unrelated regression test that hangs at hour-plus runtime with no log activity, a known-failing suite. When this happens:
 
@@ -685,6 +717,10 @@ The native agent must NOT continue to the next phase (Phase 3 → Phase 4, Phase
 
 **PR merged to main ≠ done.** After the release PR is merged to `main`, the native agent must re-invoke the skill for Phase 5 close-out (see Phase 5 step 0 below). The merge is not the end of the workflow — post-merge compliance steps are mandatory.
 
+### Commit-history hygiene recovery (devaudit-installer#315)
+
+Commit-level `[REQ-XXX]` hygiene is preventive, not the strongest source of release truth after history has already merged to a protected integration branch. If CI reports a missing commit-level REQ after the branch has exactly one active tracked release ticket or one matching RTM row, treat the release ticket / RTM context as authoritative and add a follow-up compliance note instead of rewriting protected history. The generated `validate-commits.sh` implements this as a warning in the exactly-one-active-release case. If there are zero or multiple active tracked releases, the validation remains a hard error because the release context is ambiguous.
+
 ### Commit-scoping rule for SRS updates (devaudit-installer#226)
 
 When a commit is authored as part of REQ-XXX's SDLC flow, the commit subject must cite `[REQ-XXX]` — the **active REQ** driving the current SDLC flow — regardless of which other REQs the content touches. Other REQs may appear in the body for traceability, but never in the subject.

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

@@ -783,13 +783,13 @@ jobs:
                 # "zero traceable evidence" even though well-written, REQ-tagged
                 # specs exist on disk. If specs are found but weren't run in
                 # this tier, emit a non-blocking warning instead of an error.
-                SPECS_ON_DISK=$(grep -rl --include='*.spec.ts' -e "@requirement ${REQ}" -e "tagTest.*${REQ}" -e "'${REQ}'" e2e/ 2>/dev/null | wc -l)
+                SPECS_ON_DISK=$( { grep -rl --include='*.spec.ts' -e "@requirement ${REQ}" -e "tagTest.*${REQ}" -e "'${REQ}'" e2e/ 2>/dev/null || true; } | wc -l | tr -d ' ')
 
                 # devaudit-installer#237 — also scan unit test files for
                 # @requirement REQ-XXX annotations. A REQ with thorough unit
                 # test coverage but no E2E specs (legitimate for API-only or
                 # backend-only changes) should not be hard-blocked.
-                UNIT_TESTS_ON_DISK=$(grep -rl --include='*.test.ts' --include='*.test.tsx' -e "@requirement ${REQ}" -e "'${REQ}'" e2e/ __tests__/ tests/ src/ 2>/dev/null | wc -l)
+                UNIT_TESTS_ON_DISK=$( { grep -rl --include='*.test.ts' --include='*.test.tsx' -e "@requirement ${REQ}" -e "'${REQ}'" e2e/ __tests__/ tests/ src/ 2>/dev/null || true; } | wc -l | tr -d ' ')
 
                 # devaudit-installer#237 — check for test-execution-summary.md
                 # as a secondary signal. This is a human-authored document and

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

@@ -638,6 +638,7 @@ jobs:
     permissions:
       contents: read
       actions: read
+      issues: write
     env:
       DEVAUDIT_BASE_URL_VAR: ${{ vars.DEVAUDIT_BASE_URL }}
       DEVAUDIT_API_KEY: ${{ secrets.DEVAUDIT_API_KEY }}
@@ -682,7 +683,7 @@ jobs:
           name: e2e-regression-report
           path: e2e-artifacts/
           run-id: ${{ github.event.workflow_run.id }}
-          github-token: ${{ secrets.GITHUB_TOKEN }}
+          github-token: ${{ github.token }}
         continue-on-error: true
 
       - name: Derive release version
@@ -726,8 +727,9 @@ jobs:
           FLAGS="${FLAGS} --test-cycle ${{ github.event.workflow_run.id }}"
 
           # In-scope REQs from pending release tickets at the triggering
-          # SHA. Fall back to `_compliance-docs` if no tickets present so
-          # the artefact at least lands somewhere visible.
+          # SHA. If the ticket was created after the triggering E2E run,
+          # recover REQs from the Playwright JSON artifact before falling
+          # back to `_compliance-docs` (DevAudit-Installer#311).
           REQS=()
           if [ -d compliance/pending-releases ]; then
             for TICKET in compliance/pending-releases/RELEASE-TICKET-REQ-*.md; do
@@ -742,6 +744,47 @@ jobs:
               REQS+=("$REQ_ID")
             done
           fi
+
+          if [ "${#REQS[@]}" -eq 0 ] && [ -f e2e-artifacts/e2e-regression-results.json ]; then
+            while IFS= read -r REQ_ID; do
+              [ -n "$REQ_ID" ] || continue
+              REQS+=("$REQ_ID")
+            done < <(python3 - <<'PY'
+            import json
+            import re
+            import sys
+
+            try:
+                with open('e2e-artifacts/e2e-regression-results.json', 'r', encoding='utf-8') as handle:
+                    data = json.load(handle)
+            except Exception:
+                sys.exit(0)
+
+            seen = set()
+
+            def walk(value):
+                if isinstance(value, str):
+                    for req in re.findall(r'REQ-[0-9]+', value):
+                        seen.add(req)
+                elif isinstance(value, dict):
+                    for item in value.values():
+                        walk(item)
+                elif isinstance(value, list):
+                    for item in value:
+                        walk(item)
+
+            walk(data)
+            for req in sorted(seen):
+                print(req)
+            PY
+            )
+          fi
+
+          if [ "${#REQS[@]}" -eq 1 ] && echo "$DERIVED_RELEASE" | grep -qE '^v[0-9]{4}\.[0-9]{2}\.[0-9]{2}([.][0-9]+)?$'; then
+            echo "E2E upload recovered tracked release ${REQS[0]} from artifact metadata; overriding bare-date release ${DERIVED_RELEASE}."
+            DERIVED_RELEASE="${REQS[0]}"
+          fi
+
           if [ "${#REQS[@]}" -eq 0 ]; then
             REQS=(_compliance-docs)
           fi
@@ -812,7 +855,9 @@ jobs:
       - name: Triage and file incidents on E2E Regression failure
         if: steps.resolve.outputs.skip != 'true' && github.event.workflow_run.conclusion == 'failure'
         env:
-          GH_TOKEN: ${{ secrets.DEVAUDIT_USER_TOKEN || github.token }}
+          # GitHub issue/label mutations use the workflow token. DevAudit
+          # user tokens are portal PATs, not guaranteed GitHub PATs (#305).
+          GH_TOKEN: ${{ github.token }}
           CI_RUN_ID: ${{ github.event.workflow_run.id }}
           WORKFLOW_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }}
           GIT_SHA: ${{ github.event.workflow_run.head_sha }}

package/sdlc/files/ci/incident-export.yml.template

@@ -49,7 +49,9 @@ jobs:
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-          token: ${{ secrets.DEVAUDIT_USER_TOKEN || github.token }}
+          # GitHub repo mutations use the workflow token. The DevAudit
+          # user token is for portal attribution, not GitHub checkout/push.
+          token: ${{ github.token }}
 
       - name: Classify routing (Path A vs Path B)
         id: route
@@ -436,7 +438,8 @@ jobs:
       - name: Direct commit to develop (Path A)
         if: steps.route.outputs.path == 'A'
         env:
-          GH_TOKEN: ${{ secrets.DEVAUDIT_USER_TOKEN || github.token }}
+          # GitHub push uses the workflow token plus job permissions.
+          GH_TOKEN: ${{ github.token }}
           OUT: ${{ steps.paths.outputs.out }}
           ISSUE_NUMBER: ${{ github.event.issue.number }}
           ISSUE_URL: ${{ github.event.issue.html_url }}
@@ -454,7 +457,8 @@ jobs:
       - name: Open export PR (Path B)
         if: steps.route.outputs.path == 'B'
         env:
-          GH_TOKEN: ${{ secrets.DEVAUDIT_USER_TOKEN || github.token }}
+          # GitHub branch push + PR creation use the workflow token.
+          GH_TOKEN: ${{ github.token }}
           BRANCH: ${{ steps.paths.outputs.branch }}
           OUT: ${{ steps.paths.outputs.out }}
           ISSUE_NUMBER: ${{ github.event.issue.number }}

package/sdlc/files/ci/label-retention.yml.template

@@ -56,7 +56,9 @@ jobs:
       - name: Enforce label retention
         if: steps.opt.outputs.enabled == 'true'
         env:
-          GH_TOKEN: ${{ secrets.DEVAUDIT_USER_TOKEN || github.token }}
+          # GitHub issue/comment mutations use the workflow token. The
+          # DevAudit user token is reserved for portal attribution flows.
+          GH_TOKEN: ${{ github.token }}
           EVENT_NAME: ${{ github.event_name }}
           EVENT_ACTION: ${{ github.event.action }}
           ISSUE_NUMBER: ${{ github.event.issue.number }}

package/sdlc/files/ci/periodic-review.yml.template

@@ -37,8 +37,9 @@ jobs:
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-          # Need write access for the chore branch.
-          token: ${{ secrets.DEVAUDIT_USER_TOKEN || github.token }}
+          # Need write access for the chore branch. GitHub repo mutations
+          # use the workflow token; the DevAudit user token is portal auth.
+          token: ${{ github.token }}
 
       - name: Compute review period
         id: period
@@ -188,7 +189,8 @@ jobs:
 
       - name: Open / update review PR
         env:
-          GH_TOKEN: ${{ secrets.DEVAUDIT_USER_TOKEN || github.token }}
+          # GitHub branch push + PR creation use the workflow token.
+          GH_TOKEN: ${{ github.token }}
           BRANCH: ${{ steps.period.outputs.branch }}
           REVIEW_ID: ${{ steps.period.outputs.review_id }}
         run: |