@metasession.co/devaudit-cli 0.3.9 → 0.3.11

package/package.json

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

package/sdlc/HOST_ADAPTER.md

@@ -76,6 +76,17 @@ Sync may warn if these are absent; it's a soft check (the CI workflow is the har
 | `config_keys.optional` | string[] | Keys consumers may define (e.g. an optional database service). |
 | `config_keys.defaults` | object   | Fallback values when a key is absent.                          |
 
+### Runtime contract
+
+| Field                                     | Type    | Purpose                                                                                                  |
+| ----------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
+| `runtime_contract.preferred_web_runtime`  | string  | Operator-facing guidance for the expected production web runtime shape on this host.                     |
+| `runtime_contract.forbid_typescript_runtime` | boolean | Whether long-lived production web processes on this host should forbid `tsx`/`ts-node` style execution. |
+| `runtime_contract.prefer_standalone_output` | boolean | Whether frameworks with a standalone/minimal runtime output should prefer it on this host.              |
+| `runtime_contract.scheduler_placement`    | string  | Operator-facing guidance for where scheduled/background jobs should run on this host.                    |
+
+This field is not consumed by templates yet. It exists so host-level runtime-efficiency rules are versioned and schema-validated instead of living as tribal knowledge in issues and comments.
+
 ### Notes
 
 | Field   | Type     | Purpose                                                                                                                         |
@@ -103,6 +114,12 @@ See the step-by-step walkthrough: **[docs/adding-a-host.md](../docs/adding-a-hos
   "wait_for_deploy": "for i in $(seq 1 30); do flyctl status --app \"${APP_NAME}\" --json | jq -e '.Deployment.Status == \"successful\"' && break; sleep 10; done",
   "required_secrets": ["FLY_API_TOKEN", "DEVAUDIT_API_KEY"],
   "required_env": ["APP_NAME"],
+  "runtime_contract": {
+    "preferred_web_runtime": "compiled JavaScript or framework standalone output",
+    "forbid_typescript_runtime": true,
+    "prefer_standalone_output": true,
+    "scheduler_placement": "scheduled jobs should run in a separate worker or platform cron, not in the web process"
+  },
   "notes": [
     "Production URL is resolved at deploy time by flyctl — no GitHub Secret to maintain.",
     "Deploy step runs `flyctl deploy --remote-only` in the post-deploy workflow; FLY_API_TOKEN is the auth."

package/sdlc/SKILLS.md

@@ -112,6 +112,14 @@ node scripts/validate-adapter.cjs sdlc/files/_common/skills/<name>/SKILL.md
 
 These delegations are hard contracts — the orchestrator's SKILL.md fails review if it inlines a specialist skill's procedure. The invocation pattern is documented in [docs/adding-a-skill.md §Orchestrator skills](../docs/adding-a-skill.md#orchestrator-skills-calling-other-skills).
 
+Phase 4 is now more than a one-shot handoff note. When a release PR is blocked or waiting, `sdlc-implementer` can hand execution to the bundled watcher:
+
+```bash
+node SDLC/bin/devaudit-sdlc.js --watch-pr=<number> --repo <owner/name> --once
+```
+
+or, without `--once`, a bounded poll loop that persists retry state in `.sdlc-pr-watch.json`, re-runs likely flaky workflows, and re-runs the Release Approval Gate when the portal is already approved but GitHub has not yet converged. That makes "blocked PR handling" an executable part of the orchestration contract rather than a prose-only reminder.
+
 `sdlc-implementer` is **not** used for trivial / housekeeping changes (docs, formatting, dependency bumps, CI tweaks) — those skip the requirement and the ceremony. See [the change-type matrix](../docs/change-workflows.md) and the [trivial-change walkthrough](./files/_common/implementing-an-sdlc-issue.md#trivial-change-walkthrough).
 
 ### The SoT-alignment skill family

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-status-fallback.yml.template

@@ -32,6 +32,10 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+  statuses: write
+
 jobs:
   quality-gates:
     name: Quality Gates

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 }}