@metasession.co/devaudit-cli 0.3.7 → 0.3.8

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

@@ -179,6 +179,12 @@ make_fixture "$D6" "REQ-006" << 'EOF'
 | ---------------- | ------------ | ------------------------------------------ |
 | E2E Tests        | SKIPPED      | API-only change, no UI surface (operator-approved) |
 
+## Accepted skips
+
+| Spec | Test | REQ/AC | Classification | Resolution attempted | Approved by | Rationale |
+|------|------|--------|---------------|---------------------|-------------|----------|
+| e2e/foo.spec.ts | "AC1: bar dialog" | REQ-006/AC1 | intentional_non_applicability | N/A — API-only change | operator | API-only change, no UI surface |
+
 **Final assessment:** All gates passed. E2E skipped — API-only change.
 EOF
 EXIT6=$(run_validator "$D6")
@@ -259,6 +265,87 @@ EOF
 EXIT11=$(run_validator "$D11")
 assert_exit "summary with NOT_NEEDED but no rationale — should fail" 1 "$EXIT11"
 
+# --- Case 12: SKIPPED with ## Accepted skips section and valid rows — should pass (devaudit-installer#279) ---
+D12="$WORK/case12"
+make_fixture "$D12" "REQ-012" << 'EOF'
+# Test Execution Summary — REQ-012
+
+## Gate Results
+
+| Gate             | Result       | Details                                    |
+| ---------------- | ------------ | ------------------------------------------ |
+| E2E Tests        | SKIPPED      | API-only change, no UI surface (operator-approved) |
+
+## Accepted skips
+
+| Spec | Test | REQ/AC | Classification | Resolution attempted | Approved by | Rationale |
+|------|------|--------|---------------|---------------------|-------------|----------|
+| e2e/foo.spec.ts | "AC3: bar dialog" | REQ-012/AC3 | intentional_non_applicability | N/A — API-only change | operator | API-only change, no UI surface |
+
+**Final assessment:** All gates passed. E2E skipped — API-only change.
+EOF
+EXIT12=$(run_validator "$D12")
+assert_exit "SKIPPED with ## Accepted skips section and valid rows — should pass" 0 "$EXIT12"
+
+# --- Case 13: SKIPPED without ## Accepted skips section — should fail (devaudit-installer#279) ---
+D13="$WORK/case13"
+make_fixture "$D13" "REQ-013" << 'EOF'
+# Test Execution Summary — REQ-013
+
+## Gate Results
+
+| Gate             | Result       | Details                                    |
+| ---------------- | ------------ | ------------------------------------------ |
+| E2E Tests        | SKIPPED      | API-only change, no UI surface (operator-approved) |
+
+**Final assessment:** All gates passed. E2E skipped — API-only change.
+EOF
+EXIT13=$(run_validator "$D13")
+assert_exit "SKIPPED without ## Accepted skips section — should fail" 1 "$EXIT13"
+
+# --- Case 14: SKIPPED with ## Accepted skips but no table rows — should fail (devaudit-installer#279) ---
+D14="$WORK/case14"
+make_fixture "$D14" "REQ-014" << 'EOF'
+# Test Execution Summary — REQ-014
+
+## Gate Results
+
+| Gate             | Result       | Details                                    |
+| ---------------- | ------------ | ------------------------------------------ |
+| E2E Tests        | SKIPPED      | API-only change, no UI surface (operator-approved) |
+
+## Accepted skips
+
+| Spec | Test | REQ/AC | Classification | Resolution attempted | Approved by | Rationale |
+|------|------|--------|---------------|---------------------|-------------|----------|
+
+**Final assessment:** All gates passed. E2E skipped — API-only change.
+EOF
+EXIT14=$(run_validator "$D14")
+assert_exit "SKIPPED with ## Accepted skips but no table rows — should fail" 1 "$EXIT14"
+
+# --- Case 15: SKIPPED with accepted-skip rows missing Approved by — should fail (devaudit-installer#279) ---
+D15="$WORK/case15"
+make_fixture "$D15" "REQ-015" << 'EOF'
+# Test Execution Summary — REQ-015
+
+## Gate Results
+
+| Gate             | Result       | Details                                    |
+| ---------------- | ------------ | ------------------------------------------ |
+| E2E Tests        | SKIPPED      | API-only change, no UI surface (operator-approved) |
+
+## Accepted skips
+
+| Spec | Test | REQ/AC | Classification | Resolution attempted | Approved by | Rationale |
+|------|------|--------|---------------|---------------------|-------------|----------|
+| e2e/foo.spec.ts | "AC3: bar dialog" | REQ-015/AC3 | intentional_non_applicability | N/A — API-only change |  | API-only change, no UI surface |
+
+**Final assessment:** All gates passed. E2E skipped — API-only change.
+EOF
+EXIT15=$(run_validator "$D15")
+assert_exit "SKIPPED with accepted-skip rows missing Approved by — should fail" 1 "$EXIT15"
+
 echo ""
 echo "=== Summary: $PASS pass / $FAIL fail ==="
 

package/sdlc/files/_common/skills/e2e-test-engineer/SKILL.md

@@ -300,6 +300,21 @@ Then bucket each failure:
 
 The classification is: "Is the AC correct but untested/buggy? → defect. Is the AC itself wrong/missing? → requirements gap."
 
+**Then triage skipped tests (devaudit-installer#279).** After failure triage and missed-requirements check, inspect all skipped tests from the machine-readable Playwright reporter output (JSON reporter). For each skipped test:
+
+1. **Extract the best available reason** from: `test.skipReason`, annotations, `test.skip(...)` / `testInfo.skip(...)` descriptions, setup-project failures, or helper/guard messages. Do not hard-code to one field — use the richest available source.
+2. **Classify each skip into one of:**
+   - `environment_gap` — browser not installed, database down, port conflict, missing system dependency
+   - `precondition_gap` — seed data missing, auth fixture expired, test account locked
+   - `intentional_non_applicability` — API-only change with no UI surface, feature flag disabled for this environment
+   - `obsolete_or_quarantined` — test references removed functionality, spec is stale
+3. **Fix `environment_gap` and `precondition_gap` first** — these are never acceptable skip reasons. Resolve the underlying issue, rerun the focused tests, then rerun the full suite.
+4. **Only remaining `intentional_non_applicability` or unresolved skips** may be surfaced to the operator for approval. Each accepted skip must have an operator-approved rationale.
+5. **A skipped test never proves an acceptance criterion.** If a skipped test is the only coverage for an in-scope AC, that AC is unverified until a passing test proves it.
+6. **Do not write a `PASSED` E2E sentinel while unresolved or unapproved skips remain.**
+
+Record all accepted skips in the `## Accepted skips` section of `test-execution-summary.md` (see Stage 3 blueprint).
+
 ### Phase 7 — Regression-pack handoff
 
 After Phase 6 succeeds — green run, all ACs proved, defects filed for anything missing — the new spec(s) you authored move into the project's regression pack. There is **no separate graduation step**. The pack is defined as:
@@ -422,6 +437,7 @@ Wrap up with a summary the user can drop into the PR or ticket:
 - Tests added — count, with a list.
 - Tests updated — count.
 - Tests deleted — count, with rationale.
+- Tests skipped — count, classification, resolution status, and operator-approved rationale for any accepted skip (devaudit-installer#279).
 - Suite result — passing, failing, flaky.
 - Defects filed — count, with links.
 - Requirements gap reports — count, with details (devaudit-installer#212 Gap 4). These are ACs classified as "impossible to test" or "missing AC" — returned to `sdlc-implementer` for the requirements gap flow, not filed as defects.

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

@@ -209,7 +209,7 @@ NEXT: Done — close issue + retire feature branch (sdlc-implementer halts)
 Lead every substantive turn with a driver tag on the **first line**, then the two-line LAST/NEXT shape so the operator can `Ctrl-F NEXT:` in the chat transcript to find the current pointer without re-reading:
 
 ```
-[Agent driving]   — or —   [Operator driving]   — or —   [Blocked]
+[Skill driving]   — or —   [Native agent driving]   — or —   [Operator driving]   — or —   [Blocked]
 
 **LAST:** <one sentence>
 **NEXT:** <one sentence with actor>
@@ -217,9 +217,10 @@ Lead every substantive turn with a driver tag on the **first line**, then the tw
 
 The driver tag is mandatory and comes **before** the LAST/NEXT lines:
 
-- **`[Agent driving]`** — the skill is auto-continuing; no human action needed right now. The operator can look away.
-- **`[Operator driving]`** — the skill has halted; the human must do something (review, approve, merge, answer a question). The NEXT line states the specific action needed.
-- **`[Blocked]`** — something failed and the skill cannot proceed. State the blocker and the operator action needed to unblock.
+- **`[Skill driving]`** — a skill (e.g. `sdlc-implementer`) is auto-continuing; no human action needed right now. The operator can look away.
+- **`[Native agent driving]`** — the native AI agent (Cursor, Windsurf, Claude Code, Gemini CLI, etc.) is executing steps without a skill invocation. The operator can look away but should monitor more closely since no skill protocol is governing phase transitions.
+- **`[Operator driving]`** — the skill/agent has halted; the human must do something (review, approve, merge, answer a question). The NEXT line states the specific action needed.
+- **`[Blocked]`** — something failed and the skill/agent cannot proceed. State the blocker and the operator action needed to unblock.
 
 The tag reflects the **final** state of the response — if the skill was driving but hits a halt mid-turn, the tag is `[Operator driving]` or `[Blocked]`.
 
@@ -587,6 +588,8 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
 
 **Release Approval Gate retry (devaudit-installer#211 Gap 17).** If the Release Approval Gate check fails on the PR and the portal approval was already given (API sync delay, stale cache), retry logic: re-run the Release Approval Gate workflow up to 3 times with 30-second intervals (`gh workflow run check-release-approval.yml` or trigger via `workflow_dispatch`). If it still fails after 3 retries: halt — "Release Approval Gate still failing after 3 retries. Portal may show approval but the gate can't verify it. Operator action — check the portal release status manually, verify the API key is valid, and re-run the workflow from GitHub Actions if needed."
 
+**Auto-refresh on UAT approval (devaudit#562, devaudit-installer#283).** When the portal's UAT approval is granted, the portal automatically sends a `repository_dispatch('release-approved')` event to the consuming project's repo. This triggers `check-release-approval.yml` to re-run without manual intervention. The retry logic above is still needed for edge cases (API sync delays, network issues), but the common path is now fully automated. If the auto-refresh doesn't fire (e.g. portal GitHub trigger misconfigured), the manual retry sequence above remains the fallback.
+
 ### Phase 5 — Finalise or change-request loop (SDLC stage 5)
 
 Invoked separately by the user after UAT activity on the portal. Trigger: "resume REQ-XXX", "REQ-XXX UAT done", or just re-firing the skill on the same issue.

package/sdlc/files/ci/check-release-approval.yml.template

@@ -22,6 +22,14 @@ on:
   pull_request:
     branches: [main]
   workflow_dispatch:
+  repository_dispatch:
+    types: [release-approved]
+
+permissions:
+  contents: read
+  checks: write
+  pull-requests: write
+  issues: write
 
 jobs:
   check-approval:
@@ -43,7 +51,11 @@ jobs:
           # produces the same release identity here (#81 — release-identity
           # coherence; was hardcoded to `v$(date +%Y.%m.%d)` which never
           # matched the `REQ-XXX` records the uploaders wrote).
-          ref: ${{ github.event.pull_request.head.sha }}
+          #
+          # devaudit#283 — repository_dispatch events don't have a
+          # pull_request payload. Fall back to the develop branch ref so
+          # the gate can resolve the release and post a status check.
+          ref: ${{ github.event.pull_request.head.sha || 'develop' }}
           fetch-depth: 0
 
       - name: Resolve DevAudit base URL
@@ -149,13 +161,22 @@ jobs:
         id: release
         if: env.BOOTSTRAP_MODE != 'true'
         run: |
-          # Derive the same release prefix the uploaders write to. The script
-          # priority is: subject `[REQ-XXX]` → body `Ref: REQ-XXX` → body
-          # `[REQ-XXX]` (merge-commit case) → bare-date fallback. Reusing it
-          # here makes the gate and the uploaders agree on release identity
-          # (#81). The 8 scenarios are covered by derive-release-version.test.sh.
-          chmod +x scripts/derive-release-version.sh 2>/dev/null || true
-          LOOKUP_PREFIX=$(bash scripts/derive-release-version.sh)
+          # devaudit#283 — repository_dispatch('release-approved') events
+          # carry the release version in client_payload. Use it directly
+          # when available to avoid re-deriving from git history.
+          if [ "${{ github.event_name }}" = "repository_dispatch" ] && [ -n "${{ github.event.client_payload.release }}" ]; then
+            LOOKUP_PREFIX="${{ github.event.client_payload.release }}"
+            echo "Using release version from repository_dispatch payload: ${LOOKUP_PREFIX}"
+          else
+            # Derive the same release prefix the uploaders write to. The script
+            # priority is: subject `[REQ-XXX]` → body `Ref: REQ-XXX` → body
+            # `[REQ-XXX]` (merge-commit case) → bare-date fallback. Reusing it
+            # here makes the gate and the uploaders agree on release identity
+            # (#81). The 8 scenarios are covered by derive-release-version.test.sh.
+            chmod +x scripts/derive-release-version.sh 2>/dev/null || true
+            LOOKUP_PREFIX=$(bash scripts/derive-release-version.sh)
+            echo "Derived release prefix from git history: ${LOOKUP_PREFIX}"
+          fi
           echo "Resolving release for prefix: ${LOOKUP_PREFIX}"
           RESOLVE_URL="${BASE}/api/ci/releases/resolve?projectSlug=${PROJECT_SLUG}&versionPrefix=${LOOKUP_PREFIX}"
           # Retry: register-release in ci.yml may still be racing with us.
@@ -234,21 +255,59 @@ jobs:
             echo "::warning::Approved SHA (${APPROVED_SHA:0:8}) differs from PR HEAD (${PR_HEAD_SHA:0:8}). Code may have changed after approval."
           fi
 
-      - name: Update PR status (workflow_dispatch re-trigger)
-        if: env.BOOTSTRAP_MODE != 'true' && github.event_name == 'workflow_dispatch'
+      - name: Update PR check run (workflow_dispatch / repository_dispatch re-trigger)
+        if: env.BOOTSTRAP_MODE != 'true' && (github.event_name == 'workflow_dispatch' || github.event_name == 'repository_dispatch')
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          PR_DATA=$(gh pr list --base main --head develop --json headRefOid --limit 1 2>/dev/null || echo '[]')
-          PR_SHA=$(echo "$PR_DATA" | jq -r '.[0].headRefOid // empty' 2>/dev/null || true)
-          if [ -n "$PR_SHA" ]; then
-            gh api "repos/${{ github.repository }}/statuses/${PR_SHA}" \
-              -X POST \
-              -f state=success \
-              -f context="Release Approval Gate" \
-              -f description="DevAudit release approval confirmed" \
-              -f target_url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
-              || echo "Warning: Failed to post commit status"
+          TARGET_SHA="${{ github.event.client_payload.approved_sha || '' }}"
+          if [ -z "$TARGET_SHA" ]; then
+            TARGET_SHA="${{ steps.release.outputs.approved_sha }}"
+          fi
+
+          RELEASE_PR="${{ github.event.client_payload.release_pr || '' }}"
+          if [ -z "$TARGET_SHA" ] && [ -n "$RELEASE_PR" ] && [ "$RELEASE_PR" != "null" ]; then
+            TARGET_SHA=$(gh pr view "$RELEASE_PR" --json headRefOid --jq '.headRefOid // empty' 2>/dev/null || true)
+          fi
+
+          if [ -z "$TARGET_SHA" ]; then
+            PR_DATA=$(gh pr list --base main --json number,headRefOid,updatedAt --limit 20 2>/dev/null || echo '[]')
+            TARGET_SHA=$(echo "$PR_DATA" | jq -r 'sort_by(.updatedAt) | reverse | .[0].headRefOid // empty' 2>/dev/null || true)
+          fi
+
+          if [ -z "$TARGET_SHA" ]; then
+            echo "::error::Unable to resolve PR head SHA for DevAudit Release Approval check refresh. Portal dispatch should include approved_sha."
+            exit 1
+          fi
+
+          CHECK_NAME="DevAudit Release Approval"
+          DETAILS_URL="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          COMPLETED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+          EXISTING_ID=$(gh api \
+            "/repos/${{ github.repository }}/commits/${TARGET_SHA}/check-runs?name=DevAudit%20Release%20Approval" \
+            --jq '.check_runs[] | select(.name == "DevAudit Release Approval") | .id' \
+            | head -1 || true)
+
+          if [ -n "$EXISTING_ID" ]; then
+            gh api "/repos/${{ github.repository }}/check-runs/${EXISTING_ID}" \
+              -X PATCH \
+              -f status=completed \
+              -f conclusion=success \
+              -f completed_at="$COMPLETED_AT" \
+              -f details_url="$DETAILS_URL" \
+              -f "output[title]=DevAudit release approval confirmed" \
+              -f "output[summary]=Release ${{ steps.release.outputs.version }} is approved in DevAudit."
+            echo "Updated ${CHECK_NAME} check run ${EXISTING_ID} on ${TARGET_SHA}."
           else
-            echo "No open PR from develop to main found — skipping status update"
+            gh api "/repos/${{ github.repository }}/check-runs" \
+              -X POST \
+              -f name="$CHECK_NAME" \
+              -f head_sha="$TARGET_SHA" \
+              -f status=completed \
+              -f conclusion=success \
+              -f completed_at="$COMPLETED_AT" \
+              -f details_url="$DETAILS_URL" \
+              -f "output[title]=DevAudit release approval confirmed" \
+              -f "output[summary]=Release ${{ steps.release.outputs.version }} is approved in DevAudit."
+            echo "Created ${CHECK_NAME} check run on ${TARGET_SHA}."
           fi

package/sdlc/files/ci/ci-status-fallback.yml.template

@@ -13,6 +13,9 @@
 #   `Quality Gates` status. Branch protection is satisfied without running the heavy gates
 #   on a commit that has no code in it.
 #
+#   PRs to main are actively verified by quality-gates-provenance.yml, which checks
+#   for prior develop-side Quality Gates success on the same head SHA.
+#
 #   Mixed commits (some docs + some code) trigger BOTH workflows. Same status name, both
 #   green = branch protection happy.
 

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

@@ -6,8 +6,8 @@
 # Single consolidated job — on a self-hosted runner, parallel jobs run
 # sequentially anyway. One checkout + one cached npm ci = fast.
 #
-# PRs to develop run Quality Gates before integration. PRs to main inherit
-# commit status via branch protection.
+# PRs to develop run Quality Gates before integration. PRs to main are verified
+# by quality-gates-provenance.yml (same-SHA provenance check, not heavy CI rerun).
 # Compliance validation runs separately on PRs (compliance-validation.yml).
 
 name: CI Pipeline
@@ -287,11 +287,16 @@ jobs:
           # feature converges on one release record. See DevAudit #310.
           chmod +x scripts/derive-release-version.sh 2>/dev/null || true
           VERSION=$(./scripts/derive-release-version.sh)
+          if [ -z "$VERSION" ]; then
+            echo "version=skip" >> "$GITHUB_OUTPUT"
+            echo "Release registration skipped: close-out reconciliation detected."
+            exit 0
+          fi
           echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
           echo "Release version: ${VERSION}"
 
       - name: Check release exists (no creation — deferred to upload-evidence)
-        if: env.DEVAUDIT_BASE_URL != ''
+        if: env.DEVAUDIT_BASE_URL != '' && steps.version.outputs.version != 'skip'
         run: |
           # Release creation is deferred to the upload-evidence job (which
           # runs after gates pass) so the portal never shows a release from
@@ -306,7 +311,7 @@ jobs:
             --git-sha ${{ github.sha }} --branch ${{ github.ref_name }} || true
 
       - name: Generate and upload bundled changes (REQ releases only)
-        if: env.DEVAUDIT_BASE_URL != ''
+        if: env.DEVAUDIT_BASE_URL != '' && steps.version.outputs.version != 'skip'
         run: |
           VERSION="${{ steps.version.outputs.version }}"
           # Only generate bundled changes for REQ-tagged releases —
@@ -349,32 +354,20 @@ jobs:
         run: |
           if [ ! -f "compliance/RTM.md" ]; then exit 0; fi
 
-          # Per REQ row in RTM we look up: title (release-ticket H1, else the
-          # linked issue's title via `gh`), and risk_class (the first LOW /
-          # MEDIUM / HIGH / CRITICAL token in the row). Both are optional —
-          # the portal renders gracefully with nulls. The portal endpoint
-          # accepts either a bare string[] (legacy) or rich rows.
+          # Per REQ row in RTM we look up: title (shared release metadata
+          # helper: **Requirement:** line, issue title, then H1 fallback), and
+          # risk_class (the first LOW / MEDIUM / HIGH / CRITICAL token in the
+          # row). Both are optional — the portal renders gracefully with nulls.
+          # The portal endpoint accepts either a bare string[] (legacy) or rich
+          # rows.
           REQS_JSON='[]'
           while IFS= read -r REQ; do
             [ -z "$REQ" ] && continue
             ROW=$(grep -m1 -E "^\| ${REQ} " compliance/RTM.md || true)
             TITLE=""
-            # Title: release-ticket H1 first (pending then approved)
-            for FILE in "compliance/pending-releases/RELEASE-TICKET-${REQ}.md" \
-                        "compliance/approved-releases/RELEASE-TICKET-${REQ}.md"; do
-              if [ -f "$FILE" ]; then
-                TITLE=$(grep -m1 '^# ' "$FILE" \
-                  | sed -E 's/^# *(REQ-[0-9]+)?[[:space:]]*[—:-]?[[:space:]]*//')
-                break
-              fi
-            done
-            # Title fallback: first issue # found anywhere in the row
-            if [ -z "$TITLE" ] && [ -n "$ROW" ]; then
-              ISSUE_NUM=$(echo "$ROW" | grep -oE '#[0-9]+' | head -1 | tr -d '#')
-              if [ -n "$ISSUE_NUM" ]; then
-                TITLE=$(gh issue view "$ISSUE_NUM" --json title --jq .title 2>/dev/null || true)
-              fi
-            fi
+            source scripts/extract-release-metadata.sh 2>/dev/null || true
+            extract_release_metadata "$REQ" 2>/dev/null || true
+            TITLE="$RELEASE_TITLE"
             # Risk: first LOW/MEDIUM/HIGH/CRITICAL token in the row
             RISK=""
             if [ -n "$ROW" ]; then
@@ -680,18 +673,16 @@ jobs:
             SHOT_TMP="$(mktemp -d)"
             for REQ in "${SHOT_REQS[@]}"; do
               # Per-REQ release metadata for the portal (no-clobbered on existing rows):
-              # release title from the pending ticket's H1; change type from the
-              # latest commit that references the REQ.
-              REQ_TITLE=""
-              if [ -f "compliance/pending-releases/RELEASE-TICKET-${REQ}.md" ]; then
-                REQ_TITLE=$(grep -m1 '^# ' "compliance/pending-releases/RELEASE-TICKET-${REQ}.md" \
-                  | sed -E 's/^# *(REQ-[0-9]+)?[[:space:]]*[—:-]?[[:space:]]*//')
-              fi
+              # Uses the shared extraction helper so both workflow paths produce
+              # the same title/summary for the same REQ. DevAudit-Installer#285.
+              source scripts/extract-release-metadata.sh 2>/dev/null || true
+              extract_release_metadata "$REQ" 2>/dev/null || true
               REQ_CT=$(git log --grep "\[${REQ}\]\|Ref: ${REQ}" --pretty=%s -1 2>/dev/null \
                 | grep -oE '^(feat|fix|refactor|perf|chore|docs|ci|build|test|compliance|revert)' \
                 | head -1 || true)
               REQ_META=()
-              [ -n "$REQ_TITLE" ] && REQ_META+=(--release-title "$REQ_TITLE")
+              [ -n "$RELEASE_TITLE" ] && REQ_META+=(--release-title "$RELEASE_TITLE")
+              [ -n "$RELEASE_SUMMARY" ] && REQ_META+=(--release-summary "$RELEASE_SUMMARY")
               [ -n "$REQ_CT" ] && REQ_META+=(--change-type "$REQ_CT")
               # devaudit-installer#147 — per-REQ scoped glob. ONLY this REQ's
               # own screenshots/ directory; legacy folders for REQs not in

package/sdlc/files/ci/close-out-release.yml.template

@@ -1,5 +1,5 @@
-# Release close-out — reconcile the local compliance tree after a release is
-# marked `released` on the DevAudit portal.
+# Release close-out — reconcile the local compliance tree and sync main back to
+# develop after a release is marked `released` on the DevAudit portal.
 #
 # Generated by `devaudit install` / `devaudit update` from sdlc-config.json.
 # Do not edit manually — re-run the CLI (`devaudit update`) to regenerate.
@@ -10,9 +10,11 @@
 #     release_pr }.
 #   - workflow_dispatch — manual catch-up for an already-released requirement.
 #
-# It runs scripts/close-out-release.sh for the requirement (flip ticket +
-# RTM, move ticket to approved-releases/), then opens a PR to develop. The
-# script is idempotent, so a no-op produces no PR.
+# It merges origin/main into a branch from develop (devaudit#281), runs
+# scripts/close-out-release.sh for the requirement (flip ticket + RTM, move
+# ticket to approved-releases/), then opens one PR to develop containing both
+# the main→develop sync and the compliance-tree close-out. The script is
+# idempotent, so a no-op produces no PR.
 
 name: Release Close-out
 
@@ -60,6 +62,25 @@ jobs:
           BASE=$(jq -r '.devaudit.base_url // empty' sdlc-config.json 2>/dev/null || true)
           echo "DEVAUDIT_BASE_URL=${BASE%/}" >> "$GITHUB_ENV"
 
+      - name: Merge main into develop branch
+        id: merge
+        run: |
+          # devaudit#281 — merge origin/main back into develop so the
+          # reconciliation PR carries both the released code and the
+          # compliance-tree close-out. Uses a non-interactive merge.
+          git config user.name "devaudit-bot"
+          git config user.email "devaudit-bot@users.noreply.github.com"
+          git fetch origin main
+          # Check if develop already contains main (nothing to merge)
+          if git merge-base --is-ancestor origin/main develop; then
+            echo "develop already contains origin/main — no merge needed."
+            echo "merged=false" >> "$GITHUB_OUTPUT"
+          else
+            git merge origin/main --no-edit --no-ff
+            echo "merged=true" >> "$GITHUB_OUTPUT"
+            echo "Merged origin/main into develop branch."
+          fi
+
       - name: Run close-out
         id: closeout
         run: |
@@ -74,23 +95,58 @@ jobs:
             echo "Nothing to close out (idempotent no-op) — no PR opened."
           fi
 
+      - name: Close existing sync PRs for same REQ
+        if: steps.closeout.outputs.changed == 'true' || steps.merge.outputs.merged == 'true'
+        run: |
+          # devaudit#281 — if an older same-REQ sync PR is already open,
+          # close it as superseded instead of leaving duplicate sync PRs.
+          REQ="${{ steps.in.outputs.req }}"
+          # Look for open PRs targeting develop that mention this REQ in the title
+          EXISTING_PRS=$(gh pr list --base develop --state open --json number,title --jq '.[] | select(.title | test("'"${REQ}"'")) | .number' 2>/dev/null || true)
+          for PR_NUM in $EXISTING_PRS; do
+            echo "Closing existing PR #${PR_NUM} as superseded by automated close-out for ${REQ}"
+            gh pr close ${PR_NUM} --comment "Superseded by automated release close-out for ${REQ}. This PR is no longer needed — the reconciliation is handled by the Release Close-out workflow." 2>/dev/null || true
+          done
+
       - name: Open close-out PR
-        if: steps.closeout.outputs.changed == 'true'
+        if: steps.closeout.outputs.changed == 'true' || steps.merge.outputs.merged == 'true'
         run: |
           REQ="${{ steps.in.outputs.req }}"
-          BRANCH="chore/close-out-${REQ}"
+          # Source the shared close-out contract for the branch prefix and marker
+          source scripts/close-out-contract.sh 2>/dev/null || true
+          BRANCH="${CLOSEOUT_BRANCH_PREFIX}${REQ}"
+          # Fallback if contract script not available
+          [ -z "$BRANCH" ] && BRANCH="chore/close-out-${REQ}"
           git config user.name "devaudit-bot"
           git config user.email "devaudit-bot@users.noreply.github.com"
           git checkout -b "$BRANCH"
           git add -A
-          git commit -m "docs(compliance): close out ${REQ} release ticket (RELEASED)
+          # Build the close-out marker
+          MARKER=$(closeout_marker "${REQ}" 2>/dev/null || echo "Release-Closeout: ${REQ}")
+          git commit -m "docs(compliance): close out ${REQ} release — sync main + reconcile (RELEASED)
+
+          ${MARKER}
 
           Automated reconciliation after the DevAudit portal marked ${REQ} released.
-          Ticket Status -> RELEASED + moved to approved-releases/; RTM row -> RELEASED.
+          Includes:
+          - main → develop sync
+          - release ticket moved to approved-releases/
+          - release ticket status → RELEASED
+          - RTM row → RELEASED
 
           Ref: ${REQ}"
           git push -u origin "$BRANCH" --force-with-lease
+          PR_BODY="Automated close-out — the DevAudit portal marked **${REQ}** \`released\`.
+
+          ${MARKER}
+
+          This PR includes:
+          - **main → develop reconciliation** — merges released code back into develop
+          - **release ticket** moved to \`approved-releases/\`, status \`RELEASED\`
+          - **RTM row** flipped to \`RELEASED\`
+
+          Review + merge to develop."
           gh pr create --base develop --head "$BRANCH" \
-            --title "docs(compliance): close out ${REQ} release ticket (RELEASED)" \
-            --body "Automated close-out — the DevAudit portal marked **${REQ}** \`released\`. This moves the ticket to \`approved-releases/\`, flips its Status and the RTM row to \`RELEASED\`. Review + merge to develop, then promote to main." \
+            --title "docs(compliance): close out ${REQ} — sync main + reconcile (RELEASED)" \
+            --body "$PR_BODY" \
             || echo "::warning::PR may already exist for ${BRANCH}."

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

@@ -129,6 +129,11 @@ jobs:
           # code or docs. See DevAudit #310.
           chmod +x scripts/derive-release-version.sh 2>/dev/null || true
           VERSION=$(./scripts/derive-release-version.sh)
+          if [ -z "$VERSION" ]; then
+            echo "version=skip" >> "$GITHUB_OUTPUT"
+            echo "Compliance evidence upload skipped: close-out reconciliation detected."
+            exit 0
+          fi
           echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
           echo "Release version: ${VERSION}"
 
@@ -143,10 +148,17 @@ jobs:
       # merged, the next compliance-evidence.yml run uploads them as
       # evidence and the matrix flips both items to ✓.
       #
+      # devaudit#284 — release reconciliation merges (from close-out-release.yml)
+      # carry a `Release-Closeout: REQ-XXX` marker in the commit body.
+      # derive-release-version.sh detects this marker and emits an empty
+      # version, which this workflow converts to the explicit `skip` sentinel.
+      # Reconciliation pushes therefore never create housekeeping stubs and
+      # never attach fresh evidence to an already released tracked record.
+      #
       # Mirrors the `incident-export.yml` pattern: auto-PR, operator fills
       # in sign-off, merge to land.
       - name: Auto-generate housekeeping stubs (if needed)
-        if: steps.resolve.outputs.skip != 'true'
+        if: steps.resolve.outputs.skip != 'true' && steps.version.outputs.version != 'skip'
         env:
           # Use the workflow's GITHUB_TOKEN directly. The `permissions:`
           # block on the job grants `contents: write` + `pull-requests:
@@ -226,7 +238,7 @@ jobs:
           fi
 
       - name: Upload compliance documents
-        if: steps.resolve.outputs.skip != 'true'
+        if: steps.resolve.outputs.skip != 'true' && steps.version.outputs.version != 'skip'
         run: |
           chmod +x scripts/upload-evidence.sh 2>/dev/null || true
           # Common flags WITHOUT --release. Each upload appends its OWN
@@ -428,19 +440,17 @@ jobs:
           fi
           rm -f "$AUDIT_LOG_FILE"
 
-          # Helper: emit a `--release-title …` `--change-type …` pair for a given
-          # REQ, derived from its pending release-ticket H1 and the most recent
-          # commit attributed to that REQ. Empty pair when neither is available.
+          # Helper: emit `--release-title …` `--release-summary …` `--change-type …`
+          # args for a given REQ, derived from its release-ticket metadata and
+          # the most recent commit attributed to that REQ. Empty pair when
+          # neither is available. Uses the shared extraction helper so both
+          # workflow paths produce the same title/summary for the same REQ.
+          # DevAudit-Installer#285.
           req_meta_args() {
-            local REQ="$1"; local TITLE=""; local CT=""
-            for FILE in "compliance/pending-releases/RELEASE-TICKET-${REQ}.md" \
-                        "compliance/approved-releases/RELEASE-TICKET-${REQ}.md"; do
-              if [ -f "$FILE" ]; then
-                TITLE=$(grep -m1 '^# ' "$FILE" \
-                  | sed -E 's/^# *(REQ-[0-9]+)?[[:space:]]*[—:-]?[[:space:]]*//')
-                break
-              fi
-            done
+            local REQ="$1"; local CT=""
+            # Source the shared helper and extract canonical title + summary
+            source scripts/extract-release-metadata.sh 2>/dev/null || true
+            extract_release_metadata "$REQ" 2>/dev/null || true
             CT=$(git log --grep "\[${REQ}\]\|Ref: ${REQ}" --pretty=%s -1 2>/dev/null \
               | grep -oE '^(feat|fix|refactor|perf|chore|docs|ci|build|test|compliance|revert)' \
               | head -1 || true)
@@ -448,7 +458,8 @@ jobs:
             # trailing `[ … ] && cmd` whose test fails returns 1, and the
             # function inherits that exit code; calling via $(req_meta_args …)
             # then aborts the step silently (DevAudit-Installer#77).
-            if [ -n "$TITLE" ]; then printf -- '--release-title %q ' "$TITLE"; fi
+            if [ -n "$RELEASE_TITLE" ]; then printf -- '--release-title %q ' "$RELEASE_TITLE"; fi
+            if [ -n "$RELEASE_SUMMARY" ]; then printf -- '--release-summary %q ' "$RELEASE_SUMMARY"; fi
             if [ -n "$CT" ]; then printf -- '--change-type %q ' "$CT"; fi
           }
 
@@ -680,11 +691,16 @@ jobs:
         run: |
           chmod +x scripts/derive-release-version.sh 2>/dev/null || true
           VERSION=$(./scripts/derive-release-version.sh)
+          if [ -z "$VERSION" ]; then
+            echo "version=skip" >> "$GITHUB_OUTPUT"
+            echo "E2E evidence upload skipped: close-out reconciliation detected."
+            exit 0
+          fi
           echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
           echo "Resolved release version: ${VERSION}"
 
       - name: Upload E2E Regression evidence to DevAudit
-        if: steps.resolve.outputs.skip != 'true'
+        if: steps.resolve.outputs.skip != 'true' && steps.version.outputs.version != 'skip'
         run: |
           set -euo pipefail
           DERIVED_RELEASE="${{ steps.version.outputs.version }}"