@metasession.co/devaudit-cli 0.3.8 → 0.3.10

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

package/sdlc/files/ci/post-deploy-prod.yml.template

@@ -34,6 +34,9 @@ jobs:
   production-evidence:
     name: Production Evidence
     runs-on: {{RUNNER}}
+    permissions:
+      contents: read
+      issues: write
     env:
       DEVAUDIT_BASE_URL_VAR: ${{ vars.DEVAUDIT_BASE_URL }}
       DEVAUDIT_API_KEY: ${{ secrets.DEVAUDIT_API_KEY }}
@@ -151,7 +154,9 @@ jobs:
       - name: File incident on smoke failure
         if: 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 }}
           PROD_URL: ${{ secrets.{{PRODUCTION_URL_SECRET}} }}
           GIT_SHA: ${{ github.sha }}
           CI_RUN: ${{ github.run_id }}

package/sdlc/files/ci/quality-gates-provenance.yml.template

@@ -31,7 +31,7 @@ jobs:
     steps:
       - name: Verify prior Quality Gates success on head SHA
         env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ github.token }}
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
           CURRENT_RUN_ID: ${{ github.run_id }}
         run: |

package/sdlc/files/stacks/node/hooks/pre-push

@@ -38,6 +38,9 @@ echo "Pre-push: TypeScript check passed."
 # Previous code had two `while read` loops; the second consumed nothing
 # because stdin was already exhausted by the first (devaudit-installer#278).
 PUSH_REFS="$(cat)"
+PUSH_REFS_FILE=$(mktemp)
+trap 'rm -f "$PUSH_REFS_FILE"' EXIT HUP INT TERM
+printf '%s\n' "$PUSH_REFS" > "$PUSH_REFS_FILE"
 
 INTEGRATION_BRANCH=$(jq -r '.integration_branch // "develop"' sdlc-config.json 2>/dev/null || echo "develop")
 
@@ -49,7 +52,8 @@ INTEGRATION_BRANCH=$(jq -r '.integration_branch // "develop"' sdlc-config.json 2
 # (written by e2e-test-engineer Phase 5½ after validating tagTest/evidenceShot).
 # Scoped to integration-branch pushes (correct for the normal workflow).
 
-echo "$PUSH_REFS" | while read -r local_ref local_sha remote_ref remote_sha; do
+while read -r local_ref local_sha remote_ref remote_sha; do
+  [ -n "${local_ref:-}" ] || continue
   # Check if pushing to the integration branch
   case "$remote_ref" in
     *"refs/heads/$INTEGRATION_BRANCH") ;;
@@ -103,7 +107,7 @@ echo "$PUSH_REFS" | while read -r local_ref local_sha remote_ref remote_sha; do
     fi
     echo "Pre-push: E2E evidence wiring check passed."
   fi
-done
+done < "$PUSH_REFS_FILE"
 
 # ── 3. Skill-invocation sentinel (devaudit-installer#226) ────────────
 # If feat/fix/refactor/perf commits are in the push, verify the
@@ -115,11 +119,9 @@ done
 TRACKED_TYPES='^(feat|fix|refactor|perf)(\(.+\))?!?:'
 HAS_TRACKED=false
 
-# Parse stdin refs in the current shell (not a subshell) so HAS_TRACKED propagates.
-for ref_line in $PUSH_REFS; do
-  set -- $ref_line
-  local_sha="$2"
-  remote_sha="$4"
+# Parse captured refs in the current shell so HAS_TRACKED propagates.
+while read -r local_ref local_sha remote_ref remote_sha; do
+  [ -n "${local_ref:-}" ] || continue
   if [ "$remote_sha" = "0000000000000000000000000000000000000000" ]; then
     RANGE="$local_sha"
   else
@@ -129,7 +131,7 @@ for ref_line in $PUSH_REFS; do
   if echo "$COMMITS" | grep -qE "$TRACKED_TYPES"; then
     HAS_TRACKED=true
   fi
-done
+done < "$PUSH_REFS_FILE"
 
 if [ "$HAS_TRACKED" = "true" ]; then
   if [ ! -f .sdlc-implementer-invoked ]; then
@@ -147,10 +149,8 @@ if [ "$HAS_TRACKED" = "true" ]; then
   # If the commit touches Phase 3 artifacts (compliance/evidence/REQ-XXX/),
   # the sentinel must contain a phase "3" record. If it touches Phase 5
   # close-out (approved-releases/ or RTM RELEASED), sentinel must have phase "5".
-  for ref_line in $PUSH_REFS; do
-    set -- $ref_line
-    local_sha="$2"
-    remote_sha="$4"
+  while read -r local_ref local_sha remote_ref remote_sha; do
+    [ -n "${local_ref:-}" ] || continue
     if [ "$remote_sha" = "0000000000000000000000000000000000000000" ]; then
       RANGE="$local_sha"
     else
@@ -181,7 +181,7 @@ if [ "$HAS_TRACKED" = "true" ]; then
         exit 1
       fi
     fi
-  done
+  done < "$PUSH_REFS_FILE"
   echo "Pre-push: phase-progression check passed."
 fi
 

package/sdlc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-sdlc",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "description": "DevAudit SDLC CLI Engine — cross-agent terminal-driven SDLC orchestrator.",
   "bin": {
     "devaudit-sdlc": "./src/bin/devaudit-sdlc.js"