@metasession.co/devaudit-cli 0.3.11 → 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.11",
+  "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 |