@metasession.co/devaudit-cli 0.3.12 → 0.3.13

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

@@ -5,8 +5,9 @@
 #
 # Single consolidated job. Order: install → ruff → mypy → semgrep → pip-audit → pytest → build.
 #
-# PRs to develop run Quality Gates before integration. PRs to main inherit
-# commit status via branch protection.
+# PRs to {{INTEGRATION_BRANCH}} run Quality Gates before integration. PRs to
+# {{RELEASE_BRANCH}} are handled by quality-gates-provenance.yml: provenance-only
+# for release PRs, full CI rerouted for hotfix/* PRs.
 # Compliance validation runs separately on PRs (compliance-validation.yml).
 
 name: CI Pipeline
@@ -14,9 +15,9 @@ name: CI Pipeline
 on:
   workflow_dispatch:
   pull_request:
-    branches: [develop]
+    branches: [{{INTEGRATION_BRANCH}}]
   push:
-    branches: [develop]
+    branches: [{{INTEGRATION_BRANCH}}]
     paths-ignore:
 {{PATHS_IGNORE}}      - 'sdlc-config.json'
 
@@ -190,7 +191,7 @@ jobs:
     # PRs to develop should report Quality Gates without mutating DevAudit
     # releases or evidence. Release registration remains a develop-push /
     # manual-dispatch side effect.
-    if: ${{ github.event_name != 'pull_request' }}
+    if: ${{ github.event_name != 'pull_request' && github.ref_name == '{{INTEGRATION_BRANCH}}' }}
     outputs:
       version: ${{ steps.version.outputs.version }}
     env:
@@ -314,7 +315,7 @@ jobs:
     # evidence — `status=failed` is itself the audit trail. `!cancelled()`
     # still guards against partial state on operator-cancel.
     # DevAudit-Installer#96.
-    if: ${{ always() && !cancelled() && needs.register-release.result == 'success' }}
+    if: ${{ always() && !cancelled() && github.ref_name == '{{INTEGRATION_BRANCH}}' && needs.register-release.result == 'success' }}
     env:
       DEVAUDIT_BASE_URL_VAR: ${{ vars.DEVAUDIT_BASE_URL }}
       DEVAUDIT_API_KEY: ${{ secrets.DEVAUDIT_API_KEY }}
@@ -356,11 +357,33 @@ jobs:
       - name: Generate and upload gate evidence
         if: env.DEVAUDIT_BASE_URL != ''
         run: |
-          chmod +x scripts/upload-evidence.sh 2>/dev/null || true
+          chmod +x scripts/upload-evidence.sh scripts/report-test-cycle.sh 2>/dev/null || true
           FLAGS="--git-sha ${{ github.sha }} --ci-run-id ${{ github.run_id }} --branch ${{ github.ref_name }}"
           FLAGS="${FLAGS} --release ${{ needs.register-release.outputs.version }} --create-release-if-missing"
           FLAGS="${FLAGS} --environment uat"
-          FLAGS="${FLAGS} --test-cycle ${{ github.run_id }}"
+          FLAGS="${FLAGS} --sdlc-stage 2"
+          PRIMARY_LINEAGE_FLAGS=(--test-cycle "${{ github.run_id }}")
+          CYCLE_OUT="$(mktemp)"
+          bash scripts/report-test-cycle.sh start \
+            --project-slug {{PROJECT_SLUG}} \
+            --release "${{ needs.register-release.outputs.version }}" \
+            --sdlc-stage 2 \
+            --environment uat \
+            --cycle-kind quality_gate \
+            --provider github_actions \
+            --external-run-id "${{ github.run_id }}" \
+            --external-run-attempt "${{ github.run_attempt }}" \
+            --idempotency-key "github:${{ github.repository }}:quality-gates-python.quality_gate:${{ github.run_id }}:${{ github.run_attempt }}:2:${{ needs.register-release.outputs.version }}" \
+            --commit-sha "${{ github.sha }}" \
+            --branch "${{ github.ref_name }}" \
+            --workflow-name "Quality Gates" \
+            --workflow-url "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
+            --output-file "$CYCLE_OUT"
+          . "$CYCLE_OUT"
+          rm -f "$CYCLE_OUT"
+          if [ "${cycle_supported:-false}" = "true" ] && [ -n "${cycle_record_id:-}" ]; then
+            PRIMARY_LINEAGE_FLAGS+=(--evidence-scope cycle --test-cycle-record-id "${cycle_record_id}")
+          fi
 
           UPLOAD_FAILURES=0
           upload() {
@@ -394,7 +417,7 @@ jobs:
             STATUS_TESTS=$(gate_status "$(jq -r '.tests // "skipped"' "$OUTCOMES_FILE")")
             upload gate-outcomes.json \
               {{PROJECT_SLUG}} _compliance-docs gate_outcome "$OUTCOMES_FILE" \
-              --category ci_pipeline ${FLAGS}
+              --category ci_pipeline ${FLAGS} "${PRIMARY_LINEAGE_FLAGS[@]}"
           fi
 
           mkdir -p {{WORKING_DIR_PREFIX}}ci-evidence
@@ -405,14 +428,14 @@ jobs:
           if [ -f {{WORKING_DIR_PREFIX}}ci-evidence/sast-results.json ]; then
             upload sast-results.json \
               {{PROJECT_SLUG}} _compliance-docs sast_report {{WORKING_DIR_PREFIX}}ci-evidence/sast-results.json \
-              --category security_scan --gate-status "$STATUS_SAST" ${FLAGS}
+              --category security_scan --gate-status "$STATUS_SAST" ${FLAGS} "${PRIMARY_LINEAGE_FLAGS[@]}"
           fi
 
           # Precise evidence_type=dependency_audit (matches the node template).
           if [ -f {{WORKING_DIR_PREFIX}}ci-evidence/dependency-audit.json ]; then
             upload dependency-audit.json \
               {{PROJECT_SLUG}} _compliance-docs dependency_audit {{WORKING_DIR_PREFIX}}ci-evidence/dependency-audit.json \
-              --category security_scan --gate-status "$STATUS_DEPAUDIT" ${FLAGS}
+              --category security_scan --gate-status "$STATUS_DEPAUDIT" ${FLAGS} "${PRIMARY_LINEAGE_FLAGS[@]}"
           fi
 
           # pytest junit.xml is the Python equivalent of e2e-results.json —
@@ -421,7 +444,7 @@ jobs:
           if [ -f {{WORKING_DIR_PREFIX}}ci-evidence/junit.xml ]; then
             upload junit.xml \
               {{PROJECT_SLUG}} _compliance-docs e2e_result {{WORKING_DIR_PREFIX}}ci-evidence/junit.xml \
-              --category e2e_result --gate-status "$STATUS_TESTS" ${FLAGS}
+              --category e2e_result --gate-status "$STATUS_TESTS" ${FLAGS} "${PRIMARY_LINEAGE_FLAGS[@]}"
           fi
 
           # Project-level Test Summary Report — intentional compliance_document
@@ -523,5 +546,30 @@ jobs:
             exit 1
           fi
 
+      - name: Complete primary quality-gate cycle
+        if: always() && env.DEVAUDIT_BASE_URL != ''
+        run: |
+          case "${{ job.status }}" in
+            success)   OUTCOME=passed ;;
+            cancelled) OUTCOME=cancelled ;;
+            *)         OUTCOME=failed ;;
+          esac
+          chmod +x scripts/report-test-cycle.sh 2>/dev/null || true
+          bash scripts/report-test-cycle.sh complete \
+            --project-slug {{PROJECT_SLUG}} \
+            --release "${{ needs.register-release.outputs.version }}" \
+            --sdlc-stage 2 \
+            --environment uat \
+            --cycle-kind quality_gate \
+            --provider github_actions \
+            --external-run-id "${{ github.run_id }}" \
+            --external-run-attempt "${{ github.run_attempt }}" \
+            --idempotency-key "github:${{ github.repository }}:quality-gates-python.quality_gate:${{ github.run_id }}:${{ github.run_attempt }}:2:${{ needs.register-release.outputs.version }}" \
+            --commit-sha "${{ github.sha }}" \
+            --branch "${{ github.ref_name }}" \
+            --workflow-name "Quality Gates" \
+            --workflow-url "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
+            --outcome "$OUTCOME"
+
       - name: Summary
         run: echo "Evidence uploaded for ${{ needs.register-release.outputs.version }} (UAT)"

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

@@ -1,4 +1,5 @@
-# Quality Gates Provenance — verifies prior Quality Gates success on PRs to main
+# Quality Gates Provenance — routes PRs to the release branch into the correct
+# Quality Gates path.
 #
 # Generated by `devaudit install` / `devaudit update` from sdlc-config.json.
 # Do not edit manually — re-run the CLI (`devaudit update`) to regenerate.
@@ -9,10 +10,11 @@
 #   Quality Gates result. When that happens, neither existing workflow fires on
 #   the PR to main, so the release PR sits with missing/ambiguous protection.
 #
-#   This workflow fires on PRs to main, queries the GitHub API for prior
-#   successful `Quality Gates` check runs on the PR head SHA, and fails closed
-#   if none are found. It does NOT rerun heavy CI — it is a same-SHA provenance
-#   check only.
+#   This workflow fires on PRs to {{RELEASE_BRANCH}} and chooses between two modes:
+#   - release PR (`{{INTEGRATION_BRANCH}} -> {{RELEASE_BRANCH}}`): same-SHA provenance
+#     check only
+#   - hotfix PR (`hotfix/* -> {{RELEASE_BRANCH}}`): dispatch the real ci.yml gates on
+#     the hotfix branch and proxy that result back onto the PR
 #
 #   The job name is exactly `Quality Gates` to satisfy existing branch-protection
 #   rules without introducing a new required-check name.
@@ -22,14 +24,102 @@ name: CI Pipeline
 on:
   workflow_dispatch:
   pull_request:
-    branches: [main]
+    branches: [{{RELEASE_BRANCH}}]
 
 jobs:
+  release-scope-integrity:
+    name: Release Scope Integrity
+    if: ${{ !startsWith(github.event.pull_request.head.ref, 'hotfix/') && !startsWith(github.event.pull_request.head.ref, 'fix/hotfix-') }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+
+      - name: Check release PR metadata against derived scope
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_BODY: ${{ github.event.pull_request.body }}
+          HEAD_REF: ${{ github.event.pull_request.head.ref }}
+        run: |
+          chmod +x scripts/check-release-pr-scope.sh 2>/dev/null || true
+          bash scripts/check-release-pr-scope.sh
+
   quality-gates:
     name: Quality Gates
     runs-on: ubuntu-latest
     steps:
+      - name: Classify PR path
+        id: classify
+        env:
+          HEAD_REF: ${{ github.event.pull_request.head.ref }}
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+        run: |
+          case "$HEAD_REF" in
+            hotfix/*|fix/hotfix-*)
+              echo "kind=hotfix" >> "$GITHUB_OUTPUT"
+              ;;
+            *)
+              echo "kind=release" >> "$GITHUB_OUTPUT"
+              ;;
+          esac
+          echo "base_ref=${BASE_REF}" >> "$GITHUB_OUTPUT"
+          echo "head_ref=${HEAD_REF}" >> "$GITHUB_OUTPUT"
+
+      - name: Dispatch ci.yml Quality Gates for hotfix PR
+        if: steps.classify.outputs.kind == 'hotfix'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          HEAD_REF: ${{ steps.classify.outputs.head_ref }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          BEFORE_JSON=$(gh run list \
+            --workflow "CI Pipeline" \
+            --branch "$HEAD_REF" \
+            --event workflow_dispatch \
+            --limit 50 \
+            --json databaseId,headSha)
+
+          gh workflow run ci.yml --ref "$HEAD_REF"
+
+          RUN_ID=""
+          for ATTEMPT in $(seq 1 20); do
+            AFTER_JSON=$(gh run list \
+              --workflow "CI Pipeline" \
+              --branch "$HEAD_REF" \
+              --event workflow_dispatch \
+              --limit 50 \
+              --json databaseId,headSha)
+            RUN_ID=$(BEFORE_JSON="$BEFORE_JSON" AFTER_JSON="$AFTER_JSON" HEAD_SHA="$HEAD_SHA" python3 - <<'PY'
+            import json
+            import os
+
+            before = {str(item["databaseId"]) for item in json.loads(os.environ["BEFORE_JSON"])}
+            head_sha = os.environ["HEAD_SHA"]
+            for item in json.loads(os.environ["AFTER_JSON"]):
+                if item.get("headSha") == head_sha and str(item["databaseId"]) not in before:
+                    print(item["databaseId"])
+                    break
+            PY
+            )
+            if [ -n "$RUN_ID" ]; then
+              break
+            fi
+            echo "Waiting for dispatched ci.yml run to appear for ${HEAD_REF}..."
+            sleep 10
+          done
+
+          if [ -z "$RUN_ID" ]; then
+            echo "::error::Unable to locate the dispatched ci.yml run for hotfix branch ${HEAD_REF}."
+            exit 1
+          fi
+
+          echo "Watching dispatched ci.yml run ${RUN_ID} for hotfix branch ${HEAD_REF}..."
+          gh run watch "$RUN_ID" --exit-status
+
       - name: Verify prior Quality Gates success on head SHA
+        if: steps.classify.outputs.kind != 'hotfix'
         env:
           GH_TOKEN: ${{ github.token }}
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
@@ -37,26 +127,31 @@ jobs:
         run: |
           echo "Checking for prior successful 'Quality Gates' on SHA: $HEAD_SHA"
           echo "Excluding current workflow run: $CURRENT_RUN_ID"
-
-          # Query GitHub API for check runs on this SHA with name "Quality Gates"
           CURRENT_RUN_URL="/actions/runs/${CURRENT_RUN_ID}"
-          RESPONSE=$(gh api \
-            "/repos/${{ github.repository }}/commits/${HEAD_SHA}/check-runs?name=Quality%20Gates" \
-            --jq ".check_runs[]
-              | select(.status == \"completed\" and .conclusion == \"success\")
-              | select((.details_url // \"\") | contains(\"${CURRENT_RUN_URL}\") | not)")
-
-          if [ -n "$RESPONSE" ]; then
-            echo "Found prior successful Quality Gates result:"
-            echo "$RESPONSE" | head -5
-            echo ""
-            echo "Provenance verified — this SHA passed develop-side Quality Gates."
-            exit 0
-          else
-            echo "::error::This SHA did not pass develop-side Quality Gates."
-            echo "::error::Push this exact commit through the normal develop flow first."
-            echo ""
-            echo "No prior successful 'Quality Gates' check run found for SHA $HEAD_SHA"
-            echo "(excluding current workflow run $CURRENT_RUN_ID)."
-            exit 1
-          fi
+          MAX_ATTEMPTS=10
+          WAIT_SECONDS=30
+
+          for ATTEMPT in $(seq 1 $MAX_ATTEMPTS); do
+            RESPONSE=$(gh api \
+              "/repos/${{ github.repository }}/commits/${HEAD_SHA}/check-runs?name=Quality%20Gates" \
+              --jq ".check_runs[]
+                | select(.status == \"completed\" and .conclusion == \"success\")
+                | select((.details_url // \"\") | contains(\"${CURRENT_RUN_URL}\") | not)")
+
+            if [ -n "$RESPONSE" ]; then
+              echo "Found prior successful Quality Gates result:"
+              echo "$RESPONSE" | head -5
+              echo ""
+              echo "Provenance verified — this SHA passed develop-side Quality Gates."
+              exit 0
+            fi
+
+            if [ "$ATTEMPT" -lt "$MAX_ATTEMPTS" ]; then
+              echo "Develop-side Quality Gates for SHA ${HEAD_SHA} not successful yet. Waiting ${WAIT_SECONDS}s (${ATTEMPT}/${MAX_ATTEMPTS})..."
+              sleep "$WAIT_SECONDS"
+            fi
+          done
+
+          echo "::error::No successful develop-side Quality Gates result found for SHA ${HEAD_SHA} after waiting $((MAX_ATTEMPTS * WAIT_SECONDS / 60)) minutes."
+          echo "::error::Push this exact commit through the normal develop flow first, or wait for the in-flight develop pipeline to finish and rerun this check."
+          exit 1

package/sdlc/package.json

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

package/sdlc/src/bin/devaudit-sdlc.js

@@ -16,6 +16,15 @@ const DEFAULT_FLAKY_PATTERNS = [
     'flaky',
     'retry',
 ];
+const DEFAULT_INTEGRATION_BRANCH = 'develop';
+const DEFAULT_RELEASE_BRANCH = 'main';
+const REQUIRED_RELEASE_CHECKS = [
+    'Quality Gates',
+    'Release Scope Integrity',
+    'Compliance Validation',
+    'DevAudit Release Approval',
+    'E2E Regression Suite',
+];
 const RELEASE_APPROVAL_STATUSES = new Set([
     'uat_approved',
     'release_approved',
@@ -84,6 +93,11 @@ function isReleaseGateCheck(check) {
     return haystack.includes('release approval') || haystack.includes('uat approval');
 }
 
+function isReleasePromotionPr(pr, options) {
+    return normalizeState(pr.baseRefName) === normalizeState(options.releaseBranch || DEFAULT_RELEASE_BRANCH)
+        && normalizeState(pr.headRefName) === normalizeState(options.integrationBranch || DEFAULT_INTEGRATION_BRANCH);
+}
+
 function isFlakyCheck(check, patterns) {
     const haystack = `${check.name || ''} ${check.workflow || ''}`.toLowerCase();
     return patterns.some(pattern => haystack.includes(pattern));
@@ -313,6 +327,14 @@ function classifyPrStatus(pr, checks, portalStatus, watch, options) {
     const failingChecks = checks.filter(check => isFailingState(check.state || check.bucket));
     const pendingChecks = checks.filter(check => isPendingState(check.state || check.bucket));
     const releaseGate = checks.find(isReleaseGateCheck) || null;
+    const isReleasePr = isReleasePromotionPr(pr || {}, options);
+    const releaseChecks = isReleasePr
+        ? checks.filter(check => REQUIRED_RELEASE_CHECKS.includes(String(check.name || '')))
+        : [];
+    const missingReleaseChecks = isReleasePr
+        ? REQUIRED_RELEASE_CHECKS.filter(required => !releaseChecks.some(check => String(check.name || '') === required))
+        : [];
+    const pendingReleaseChecks = releaseChecks.filter(check => isPendingState(check.state || check.bucket));
 
     if (normalizeState(pr.state) !== 'open') {
         return {
@@ -362,6 +384,22 @@ function classifyPrStatus(pr, checks, portalStatus, watch, options) {
         };
     }
 
+    if (isReleasePr && missingReleaseChecks.length > 0) {
+        return {
+            kind: 'waiting',
+            exitCode: 2,
+            summary: `PR #${watch.prNumber} is still waiting for required release checks to report: ${missingReleaseChecks.join(', ')}.`,
+        };
+    }
+
+    if (isReleasePr && pendingReleaseChecks.length > 0) {
+        return {
+            kind: 'waiting',
+            exitCode: 2,
+            summary: `PR #${watch.prNumber} still has required release checks running: ${pendingReleaseChecks.map(formatCheckName).join(', ')}.`,
+        };
+    }
+
     for (const check of failingChecks) {
         if (!isReleaseGateCheck(check) && isFlakyCheck(check, options.flakyPatterns || DEFAULT_FLAKY_PATTERNS)) {
             const runId = extractRunId(check.link);
@@ -405,7 +443,9 @@ function classifyPrStatus(pr, checks, portalStatus, watch, options) {
     return {
         kind: 'ready',
         exitCode: 0,
-        summary: `PR #${watch.prNumber} is approved and all observed checks are green. Ready for merge.`,
+        summary: isReleasePr
+            ? `PR #${watch.prNumber} is approved and all required release checks reached terminal success. Ready for merge.`
+            : `PR #${watch.prNumber} is approved and all observed checks are green. Ready for merge.`,
     };
 }
 
@@ -454,6 +494,8 @@ async function watchPullRequest() {
 
     const options = {
         flakyPatterns: flakyPatterns.length > 0 ? flakyPatterns : DEFAULT_FLAKY_PATTERNS,
+        integrationBranch: getOption('integration-branch') || DEFAULT_INTEGRATION_BRANCH,
+        releaseBranch: getOption('release-branch') || DEFAULT_RELEASE_BRANCH,
     };
 
     let pollsRemaining = once ? 1 : maxPolls;
@@ -463,7 +505,7 @@ async function watchPullRequest() {
         let pr;
         let checks;
         try {
-            pr = runGhJson(['pr', 'view', String(prNumber), '--repo', repo, '--json', 'state,isDraft,reviewDecision']);
+            pr = runGhJson(['pr', 'view', String(prNumber), '--repo', repo, '--json', 'state,isDraft,reviewDecision,baseRefName,headRefName']);
             checks = runGhJson(['pr', 'checks', String(prNumber), '--repo', repo, '--json', 'name,state,link,workflow,bucket']) || [];
             if (!Array.isArray(checks)) checks = [];
         } catch (error) {

package/sdlc/src/blueprints/1-plan-requirement.raw.md

@@ -70,6 +70,11 @@ Open `compliance/RTM.md`, Part B. The issue provides full context; the RTM is a
 | REQ-XXX | #NNN | [LOW/MEDIUM/HIGH] | compliance/evidence/REQ-XXX/ | DRAFT | -- | -- |
 ```
 
+If any RTM cell content needs literal pipe characters, escape them as `\|`
+rather than writing bare `|`. This matters for regex or enum examples inside
+status/notes text because markdownlint otherwise misreads the row as having
+extra columns.
+
 The auditor reads one row and follows the links: Issue for context and rationale, evidence directory for test artifacts, PR for code changes.
 
 ### Step 5: Create Evidence Directory
@@ -379,7 +384,7 @@ cat > compliance/evidence/REQ-XXX/test-plan.md << 'EOF'
 
 ## Functional Test Mapping
 | Acceptance Criterion | Test File | Test Name |
-|---------------------|-----------|-----------|
+| --------------------- | ----------- | ----------- |
 | [From test-scope.md] | [spec file] | [test name] |
 
 ## Non-Functional Tests (MEDIUM/HIGH)

package/sdlc/src/blueprints/2-implement-and-test.raw.md

@@ -246,7 +246,7 @@ For LOW-risk docs/tooling/script-only changes or environments without the requir
 #### Exit Criteria
 
 | Gate | Threshold |
-|---|---|
+| --- | --- |
 | TypeScript | 0 errors |
 | SAST (high/critical) | 0 findings |
 | Dependencies (high/critical) | 0 vulnerabilities |

package/sdlc/src/blueprints/3-compile-evidence.raw.md

@@ -36,7 +36,7 @@ If you are an AI agent reading this file, you are strictly prohibited from manua
 **Markdown stays in git. Binary and JSON evidence goes to DevAudit.**
 
 | Artifact | Store in | Why |
-|----------|----------|-----|
+| ---------- | ---------- | ----- |
 | `compliance/RTM.md` | Git | Source of truth, version history, PR-reviewable |
 | `compliance/evidence/REQ-XXX/test-scope.md` | Git | Planning artifact, reviewed in PRs |
 | `compliance/evidence/REQ-XXX/implementation-plan.md` | Git | Design decisions artifact (MEDIUM/HIGH risk), reviewed in PRs |
@@ -60,7 +60,7 @@ CI uploads are scoped to a **release record** in DevAudit, keyed by `(project, v
 The templated workflows derive the release version from the **latest commit on the branch** via `scripts/derive-release-version.sh`:
 
 | Commit shape | Release version |
-|---|---|
+| --- | --- |
 | Subject `[REQ-037] feat(...)` | `REQ-037` |
 | Subject `feat(...)` + body `Ref: REQ-037` | `REQ-037` |
 | Subject contains multiple tags (e.g. `[REQ-037][REQ-038]`) | First match wins → `REQ-037` |
@@ -75,7 +75,7 @@ If you need a separate release container for a sub-piece of work — e.g. carvin
 A release is classified by its version pattern. **Most of this doc walks the tracked path** (a REQ-XXX-tagged release for a single requirement). For develop pushes that don't carry a REQ tag — typically `docs:`, `chore:`, `ci:`, `build:`, `test:`, `compliance:`, `revert:` — the version-deriver falls back to a bare date and the release is **housekeeping**.
 
 | Shape | Version pattern | Triggered by | Per-REQ ceremony |
-|---|---|---|---|
+| --- | --- | --- | --- |
 | **Tracked** | `REQ-037`, `REQ-046-FIX`, etc. | A `feat`/`fix`/`refactor`/`perf` commit (REQ tag required by commitlint) | Yes — full Steps 1-9 |
 | **Housekeeping** | `v2026.06.04` (bare date, optionally `.N`) | A push containing only REQ-exempt commit types | **No** per-REQ artefacts; the portal auto-skips test-scope, test-plan, implementation-plan, and test-execution-summary completeness checks |
 
@@ -84,7 +84,7 @@ A release is classified by its version pattern. **Most of this doc walks the tra
 Housekeeping releases **skip** the per-requirement evidence (no REQ → no `compliance/evidence/REQ-XXX/` folder) but **still produce two release-scoped artefacts**:
 
 | Artefact | Tracked path | Housekeeping path | Auto-generated by CI? |
-|---|---|---|---|
+| --- | --- | --- | --- |
 | Release ticket | `compliance/pending-releases/RELEASE-TICKET-REQ-XXX.md` (Step 8) | `compliance/pending-releases/RELEASE-TICKET-<version>.md` (e.g. `RELEASE-TICKET-v2026.06.04.md`) | **Yes** — `generate-housekeeping-release-ticket.sh` runs after `derive-release-version.sh` and emits a stub the operator reviews + signs off |
 | Security summary | `compliance/evidence/REQ-XXX/security-summary.md` (Step 4) | `compliance/security-summary-<version>.md` at the compliance root (release-scoped, not REQ-scoped) | **Yes** — `generate-security-summary.sh` scrapes the SAST + dep-audit gate JSON and emits a stub with an operator sign-off block |
 
@@ -168,7 +168,7 @@ Records the design-time decisions before listing run results — what was tested
 ## Gate Results
 
 | Gate | Result | Details |
-|------|--------|---------|
+| ------ | -------- | --------- |
 | TypeScript | PASS | 0 errors |
 | SAST | PASS | [N] findings ([N] baseline) |
 | Dependency Audit | PASS | [N] unaccepted high/critical |
@@ -180,7 +180,7 @@ Records the design-time decisions before listing run results — what was tested
 Required when E2E gate result is `SKIPPED`. Optional when no accepted skips exist.
 
 | Spec | Test | REQ/AC | Classification | Resolution attempted | Approved by | Rationale |
-|------|------|--------|---------------|---------------------|-------------|----------|
+| ------ | ------ | -------- | --------------- | --------------------- | ------------- | ---------- |
 | e2e/foo.spec.ts | "AC3: bar dialog" | REQ-XXX/AC3 | intentional_non_applicability | N/A — API-only change | [operator] | API-only change, no UI surface |
 
 Rules:
@@ -191,11 +191,25 @@ Rules:
 
 ## Test Cycles
 
-| Cycle | CI Run | Gate Status | E2E Result | Coverage | Date |
-|-------|--------|-------------|------------|----------|------|
-| #1    | [run_id] | [PASS/FAIL] | [N/N]   | [N%]     | [YYYY-MM-DD] |
+Prefer the first-class release-journey / cycle API when the portal exposes it. Generate the table from the API response rather than inferring cycles from uploaded files:
 
-**Final assessment:** [All cycles passed / N cycles failed — see incidents]
+```bash
+# Example:
+curl -s -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+  "${DEVAUDIT_BASE_URL%/}/api/projects/<slug>/releases/REQ-XXX/journey" \
+  > /tmp/release-journey.json
+bash scripts/render-test-cycles.sh /tmp/release-journey.json
+```
+
+The helper renders a first-class table when `.cycles[]` is present, and falls back to legacy `testCycleId` grouping when the portal has not yet rolled out cycle records.
+
+| Source Release | SDLC Stage | Cycle | Kind | Outcome | Workflow / Run | Related Evidence | Incident / Remediation | Date |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| REQ-XXX | 2 implement_test | #1 | quality_gate | passed | [Quality Gates](https://github.com/example/repo/actions/runs/123) (run 123, attempt 1) | quality-gates.json | None | 2026-07-16 11:03:00 |
+| REQ-XXX | 2 implement_test | #2 | e2e | passed | [E2E Regression](https://github.com/example/repo/actions/runs/124) (run 124, attempt 2) | e2e-results.json, screenshots.zip | Incident #501 fixed in PR #507 | 2026-07-16 11:19:00 |
+| REQ-089 | 4 uat_review | #1 | uat | passed | [UAT Review](https://devaudit.example/releases/REQ-089) | uat-checklist.md | None | 2026-07-16 12:02:00 |
+
+**Final assessment:** [First-class cycle records show all stage cycles passed / N cycles failed — see incidents]
 
 ## Bundled Release Context
 
@@ -224,13 +238,13 @@ Required when `compliance/pending-releases/BUNDLED-CHANGES-REQ-XXX.md` exists fo
 ## Test Plan Coverage
 
 | Acceptance Criterion | Status | Test |
-|---------------------|--------|------|
+| --------------------- | -------- | ------ |
 | [From test-plan.md] | PASS | `[spec-file]::[test-name]` |
 
 ## Evidence Locations
 
 | Evidence | Location |
-|----------|----------|
+| ---------- | ---------- |
 | E2E results | DevAudit: [project]/REQ-XXX/e2e-results.json |
 | SAST results | DevAudit: [project]/REQ-XXX/sast-results.json |
 | Dependency audit | DevAudit: [project]/REQ-XXX/dependency-audit.json |
@@ -359,7 +373,7 @@ No incidents or defects were discovered during the test cycle for release `<vers
 ## Sign-off
 
 | Role | Name | Date |
-|---|---|---|
+| --- | --- | --- |
 | Test lead | REPLACE — assign | REPLACE |
 | Engineering lead | REPLACE — assign | REPLACE |
 EOF
@@ -480,7 +494,7 @@ The test-scope artefact carries an **SRS-ID cross-reference table** so each test
 ## SRS coverage
 
 | Test (file) | AC | SRS item |
-|---|---|---|
+| --- | --- | --- |
 | e2e/admin-order-flow.spec.ts | AC1 | REQ-ORDER-005 |
 | services/order-service.test.ts | AC2 | REQ-INV-010 |
 | e2e/incident-dashboard.spec.ts | AC9 | REQ-OPS-001 |
@@ -538,7 +552,7 @@ Required when `compliance/pending-releases/BUNDLED-CHANGES-REQ-XXX.md` exists or
 ## AI Contributors
 
 | Tool | Version | Session | Commits | Date Range |
-|------|---------|---------|---------|------------|
+| ------ | --------- | --------- | --------- | ------------ |
 | [tool / none] | [version] | [session id] | [N] | [YYYY-MM-DD to YYYY-MM-DD] |
 
 **Handoffs:** [None / list — see `ai-agent-handoff.md` if applicable]
@@ -557,13 +571,13 @@ Required when `compliance/pending-releases/BUNDLED-CHANGES-REQ-XXX.md` exists or
 
 ## Test Evidence
 | Test Type | Count | Passed | Failed | Evidence Location |
-|-----------|-------|--------|--------|-------------------|
+| ----------- | ------- | -------- | -------- | ------------------- |
 | E2E (Playwright) | [N] | [N] | 0 | DevAudit portal: [PROJECT_SLUG]/REQ-XXX |
 | Unit | [N] | [N] | 0 | DevAudit portal: [PROJECT_SLUG]/REQ-XXX |
 
 ## Security Evidence
 | Check | Result | Evidence Location |
-|-------|--------|-------------------|
+| ------- | -------- | ------------------- |
 | SAST | 0 high/critical | DevAudit portal: [PROJECT_SLUG]/REQ-XXX |
 | Dependency Audit | 0 high/critical | DevAudit portal: [PROJECT_SLUG]/REQ-XXX |
 | Access Control | [PASS/N/A] | Git: `compliance/evidence/REQ-XXX/security-summary.md` |
@@ -584,7 +598,7 @@ Required when `compliance/pending-releases/BUNDLED-CHANGES-REQ-XXX.md` exists or
 ## Post-Deploy Actions
 
 | Type | Script / Command | Target | Required | Notes |
-|------|-----------------|--------|----------|-------|
+| ------ | ----------------- | -------- | ---------- | ------- |
 | — | None | — | — | No post-deploy actions required |
 
 <!-- Replace the "None" row above with actual actions if this release requires them:
@@ -612,7 +626,7 @@ Required when `compliance/pending-releases/BUNDLED-CHANGES-REQ-XXX.md` exists or
 
 ## Audit Trail
 | Date | Action | Actor | Notes |
-|------|--------|-------|-------|
+| ------ | -------- | ------- | ------- |
 | [date] | Requirement created | [who] | Risk: [level] |
 | [date] | Implementation completed | [who] | [details] |
 | [date] | AI code reviewed | [reviewer] | [files] |
@@ -794,7 +808,7 @@ The script:
 Required environment variables for the scripted path:
 
 | Var | What it is | Where to set |
-|---|---|---|
+| --- | --- | --- |
 | `DEVAUDIT_USER_TOKEN` | Personal Access Token (`mctok_…`) attributed to the running user | Issue at `/settings/tokens`; store as a repo secret for CI or `.env` for local |
 | `DEVAUDIT_API_KEY` | Project-scoped API key (existing) | Already set for evidence uploads |
 | `DEVAUDIT_BASE_URL` | DevAudit URL | Resolved by CI templates; locally read from `sdlc-config.json devaudit.base_url` |

package/sdlc/src/blueprints/4-submit-for-review.raw.md

@@ -121,7 +121,7 @@ gh pr create --base main --head develop --title "type: description" --body "$(ca
 ## Test Results (Local — Comprehensive)
 
 | Gate | Result | Details |
-|------|--------|---------|
+| ------ | -------- | --------- |
 | E2E Tests | [N]/[N] passed | Spec files: [list spec files that ran] |
 | TypeScript | 0 errors | `npx tsc --noEmit` |
 | SAST | 0 high/critical | [N] rules scanned, [N] files |
@@ -148,7 +148,7 @@ CI runs automatically on this PR. The following gates must pass before merge:
 
 ### Where to Find Test Results
 | Source | Location | What It Shows |
-|--------|----------|---------------|
+| -------- | ---------- | --------------- |
 | **CI status** | Green/red icons on PR commits | Pass/fail for each gate (independent, tamper-resistant) |
 | **CI E2E comment** | PR comments (automated) | E2E pass/fail with commit SHA |
 | **DevAudit evidence** | [View evidence on DevAudit](https://[DevAudit-URL]/projects/[PROJECT_SLUG]/requirements/REQ-XXX) | Playwright report, SAST results, dependency audit |