@metasession.co/devaudit-cli 0.3.12 → 0.3.13

package/sdlc/files/_common/skills/sdlc-implementer/references/compliance-constraints.md

@@ -8,8 +8,7 @@ The constraints are enforced in `SKILL.md` and in the smoke pass. Where applicab
 
 ### 1. Never skip the UAT review gate
 
-| | |
-|---|---|
+|  |  |  | --- | --- |
 | **What** | The skill must not attempt to merge a PR while the `DevAudit Release Approval` check is red. |
 | **Why (framework)** | ISO 27001 A.8.32 (Change management); SOC 2 CC8 (Change management); EU AI Act Art. 14 (Human oversight). The UAT gate is the load-bearing human-oversight checkpoint. |
 | **Enforcement** | Portal-side via `check-release-approval.yml` workflow status check + branch protection. Skill-side: never call `gh pr merge` until the check is green. |
@@ -17,8 +16,7 @@ The constraints are enforced in `SKILL.md` and in the smoke pass. Where applicab
 
 ### 2. For HIGH/CRITICAL, never act as the UAT approver
 
-| | |
-|---|---|
+|  |  |  | --- | --- |
 | **What** | The skill must verify at Phase 4 that the configured UAT reviewer (in `compliance/plans/REQ-XXX/implementation-plan.md` §Four-eyes attestation slot) differs from the skill-trigger user. If they match, halt. |
 | **Why (framework)** | SOC 2 CC8.1 — segregation of duties; ISO 27001 A.5.15 (Access control — duty segregation). The change-author cannot also be the change-approver for higher-risk work. |
 | **Enforcement** | Portal-side: the release-approval API rejects self-approval for MEDIUM/HIGH/CRITICAL risk classes. Skill-side: refuses to open the PR if the configured reviewer matches the trigger user. |
@@ -26,8 +24,7 @@ The constraints are enforced in `SKILL.md` and in the smoke pass. Where applicab
 
 ### 3. Plan checkpoint mandatory for HIGH/CRITICAL
 
-| | |
-|---|---|
+|  |  |  | --- | --- |
 | **What** | At Phase 1 step 8, the skill pauses for human approval of the plan **iff** risk class is HIGH or CRITICAL. LOW/MEDIUM pass through automatically. Can be forced on for all classes via `--require-plan-approval` flag or `DEVAUDIT_REQUIRE_PLAN_APPROVAL=1` env var. |
 | **Why (framework)** | EU AI Act Art. 14 (Human oversight for high-risk AI systems); SOC 2 CC3 (Risk assessment requires human judgement); ISO 29119 §6 (Test management — planning is a documented human step). For HIGH/CRITICAL work the plan IS the design — human review must precede code. |
 | **Enforcement** | Skill-side. Phase 1 explicitly halts and waits for the human's "go" before Phase 2. |
@@ -35,8 +32,7 @@ The constraints are enforced in `SKILL.md` and in the smoke pass. Where applicab
 
 ### 4. Change-request loop triggers full UAT re-review
 
-| | |
-|---|---|
+|  |  |  | --- | --- |
 | **What** | When new commits land on a PR after a UAT change-request, the portal's release-approval state resets. The skill respects the reset, surfaces a "UAT re-review needed" comment, and never assumes the prior approval still covers the new changes. |
 | **Why (framework)** | ISO 27001 A.14.2.4 (Restrictions on changes to software packages — each change goes through controls); SOC 2 CC8.1 (Each change requires approval). Treating "approval given once, all subsequent commits inherit it" would make UAT a one-shot rubber-stamp. |
 | **Enforcement** | Portal-side: the release-approval state machine resets on new commits to the linked branch. Skill-side: re-requests review explicitly via the portal API after each change-request iteration. |
@@ -44,8 +40,7 @@ The constraints are enforced in `SKILL.md` and in the smoke pass. Where applicab
 
 ### 5. AI involvement disclosed on every commit
 
-| | |
-|---|---|
+|  |  |  | --- | --- |
 | **What** | Every commit the skill creates carries a `Co-Authored-By: Claude <noreply@anthropic.com>` trailer (or equivalent for the specific Claude model in use). |
 | **Why (framework)** | ISO 27001 — transparency norms; EU AI Act Art. 13 (Transparency and provision of information to deployers); GDPR Art. 22 (data subjects' right to know about automated decisions, where applicable). When an auditor traces a commit, the AI involvement must be visible. |
 | **Enforcement** | Skill-side. Every `git commit` call includes the trailer. CI's `compliance-validation.yml` workflow can be configured to grep for `Co-Authored-By` on PRs labelled with the AI-touched marker; this is optional but recommended. |
@@ -53,8 +48,7 @@ The constraints are enforced in `SKILL.md` and in the smoke pass. Where applicab
 
 ### 6. All portal mutations through audit-logged APIs
 
-| | |
-|---|---|
+|  |  |  | --- | --- |
 | **What** | The skill calls `devaudit push` and the standard portal HTTP APIs — never a database back-channel, never a service-role-key-equivalent that bypasses the audit log. |
 | **Why (framework)** | ISO 27001 A.12.4 (Logging and monitoring); SOC 2 CC4 + CC7 (Monitoring activities + system operations). Every action that affects compliance state must produce an audit-log entry attributable to a human identity (the user whose PAT is in `DEVAUDIT_USER_TOKEN`). |
 | **Enforcement** | Skill-side. All portal interaction goes through `devaudit push` or `curl`/`gh api` against the documented REST endpoints. |
@@ -64,8 +58,7 @@ The constraints are enforced in `SKILL.md` and in the smoke pass. Where applicab
 
 ### 7. Rubber-stamping at UAT
 
-| | |
-|---|---|
+|  |  |  | --- | --- |
 | **What** | If the UAT reviewer approves without actually reading the change, the controls are formally satisfied but substantively hollow. |
 | **Why (framework)** | SOC 2 CC4.1 (Monitoring activities — the entity should detect this via its own QA sampling). Not enforced by any control mechanism; relies on human discipline. |
 | **Enforcement** | Not architectural. Mitigations: the SKILL.md's Principles section names the UAT reviewer as "the load-bearing human"; the portal's UAT-review UI intentionally adds friction (no one-click approve from email); org policy should random-sample approvals for QA. |

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

@@ -6,8 +6,9 @@
 # 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 are verified
-# by quality-gates-provenance.yml (same-SHA provenance check, not heavy CI rerun).
+# 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
@@ -15,9 +16,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'
 
@@ -31,6 +32,7 @@ jobs:
   # ──────────────────────────────────────────────
   quality-gates:
     name: Quality Gates
+    if: ${{ github.event_name != 'pull_request' || !startsWith(github.head_ref, 'chore/close-out-') }}
     runs-on: {{RUNNER}}
 
     services:
@@ -238,7 +240,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:
@@ -295,18 +297,16 @@ jobs:
           echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
           echo "Release version: ${VERSION}"
 
-      - name: Check release exists (no creation — deferred to upload-evidence)
+      - name: Ensure release exists for gate-cycle lineage
         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
-          # a push where gates weren't verified (devaudit-installer#226).
-          # This step only checks whether the release already exists (e.g.
-          # created earlier by sdlc-implementer Phase 1 step 3).
+          # First-class cycle APIs need an exact release row before the
+          # stage-2 cycle can start. This keeps failed gate runs visible even
+          # when later evidence generation fails.
           chmod +x scripts/upload-evidence.sh 2>/dev/null || true
           bash scripts/upload-evidence.sh \
             {{PROJECT_SLUG}} _compliance-docs release_registration README.md \
-            --release ${{ steps.version.outputs.version }} \
+            --release ${{ steps.version.outputs.version }} --create-release-if-missing \
             --environment uat --category planning \
             --git-sha ${{ github.sha }} --branch ${{ github.ref_name }} || true
 
@@ -338,8 +338,19 @@ jobs:
           fi
           echo "Scanning bundled changes since ${SINCE_REF} for ${VERSION}"
           BUNDLED_FILE="compliance/pending-releases/BUNDLED-CHANGES-${VERSION}.md"
+          BUNDLED_MANIFEST="compliance/pending-releases/BUNDLED-CHANGES-${VERSION}.json"
           mkdir -p compliance/pending-releases
-          bash scripts/generate-bundled-changes.sh "$SINCE_REF" "$VERSION" > "$BUNDLED_FILE"
+          chmod +x scripts/submit-bundle-manifest.sh 2>/dev/null || true
+          bash scripts/generate-bundled-changes.sh \
+            "$SINCE_REF" "$VERSION" --json-out "$BUNDLED_MANIFEST" > "$BUNDLED_FILE"
+          MEMBER_COUNT=$(jq -r '(.members // []) | length' "$BUNDLED_MANIFEST" 2>/dev/null || echo 0)
+          WORK_ITEM_COUNT=$(jq -r '(.nonReleaseWorkItems // []) | length' "$BUNDLED_MANIFEST" 2>/dev/null || echo 0)
+          if [ "$MEMBER_COUNT" = "0" ] && [ "$WORK_ITEM_COUNT" = "0" ]; then
+            echo "No bundled predecessor releases or non-release work detected for ${VERSION}."
+            rm -f "$BUNDLED_FILE" "$BUNDLED_MANIFEST"
+            exit 0
+          fi
+          bash scripts/submit-bundle-manifest.sh {{PROJECT_SLUG}} "$VERSION" "$BUNDLED_MANIFEST"
           # Upload as bundled_changes evidence against the REQ release.
           bash scripts/upload-evidence.sh \
             {{PROJECT_SLUG}} _compliance-docs bundled_changes "$BUNDLED_FILE" \
@@ -407,7 +418,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 }}
@@ -444,17 +455,33 @@ jobs:
       - name: Generate and upload gate evidence
         if: env.DEVAUDIT_BASE_URL != ''
         run: |
-          chmod +x scripts/upload-evidence.sh 2>/dev/null || true
-          # --create-release-if-missing is intentionally here (post-gate) rather
-          # than in register-release. This ensures the portal release record only
-          # appears after gates have run — even if gates failed, the release
-          # record is created here so failure evidence attaches to it.
-          # (devaudit-installer#226)
+          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} --sdlc-stage 2"
-          FLAGS="${FLAGS} --test-cycle ${{ github.run_id }}"
+          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.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
 
           # Track failures across all uploads so we can fail the job at the
           # end with the full picture. Previously each upload used
@@ -494,7 +521,7 @@ jobs:
             STATUS_BUILD=$(gate_status "$(jq -r '.build // "skipped"' ci-evidence/gate-outcomes.json)")
             upload gate-outcomes.json \
               {{PROJECT_SLUG}} _compliance-docs gate_outcome ci-evidence/gate-outcomes.json \
-              --category ci_pipeline ${FLAGS}
+              --category ci_pipeline ${FLAGS} "${PRIMARY_LINEAGE_FLAGS[@]}"
           fi
 
           # Re-generate gate evidence as fallback if artifact download failed
@@ -519,7 +546,7 @@ jobs:
           if [ -f ci-evidence/sast-results.json ]; then
             upload sast-results.json \
               {{PROJECT_SLUG}} _compliance-docs sast_report 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
 
           # Upload dependency audit — precise evidence_type=dependency_audit
@@ -527,14 +554,14 @@ jobs:
           if [ -f ci-evidence/dependency-audit.json ]; then
             upload dependency-audit.json \
               {{PROJECT_SLUG}} _compliance-docs dependency_audit 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
 
           # Upload E2E test results (e2e_result category)
           if [ -f ci-evidence/e2e-results.json ]; then
             upload e2e-results.json \
               {{PROJECT_SLUG}} _compliance-docs e2e_result ci-evidence/e2e-results.json \
-              --category e2e_result ${FLAGS}
+              --category e2e_result ${FLAGS} "${PRIMARY_LINEAGE_FLAGS[@]}"
           fi
 
           # Upload Playwright HTML report (e2e_report — run context, NOT
@@ -546,7 +573,7 @@ jobs:
             if [ -f ci-evidence/playwright-report.zip ]; then
               upload playwright-report.zip \
                 {{PROJECT_SLUG}} _compliance-docs e2e_report ci-evidence/playwright-report.zip \
-                --category e2e_report ${FLAGS}
+                --category e2e_report ${FLAGS} "${PRIMARY_LINEAGE_FLAGS[@]}"
             fi
           fi
 
@@ -557,7 +584,7 @@ jobs:
           if [ -f ci-evidence/coverage/coverage-summary.json ]; then
             upload coverage-summary.json \
               {{PROJECT_SLUG}} _compliance-docs coverage_report ci-evidence/coverage/coverage-summary.json \
-              --category coverage_report ${FLAGS}
+              --category coverage_report ${FLAGS} "${PRIMARY_LINEAGE_FLAGS[@]}"
           fi
 
           # Upload project-level Test Summary Report as a baseline
@@ -571,7 +598,9 @@ jobs:
           if [ -f "compliance/test-summary-report.md" ]; then
             upload test-summary-report.md \
               {{PROJECT_SLUG}} _compliance-docs compliance_document compliance/test-summary-report.md \
-              --category planning ${FLAGS}
+              --category planning --git-sha ${{ github.sha }} --ci-run-id ${{ github.run_id }} --branch ${{ github.ref_name }} \
+              --release ${{ needs.register-release.outputs.version }} --create-release-if-missing \
+              --environment uat --sdlc-stage 2
           fi
 
           # devaudit-installer#200 Fix 4 — Per-REQ gate evidence fan-out.
@@ -850,5 +879,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.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/close-out-release.yml.template

@@ -11,10 +11,11 @@
 #   - workflow_dispatch — manual catch-up for an already-released requirement.
 #
 # 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.
+# scripts/close-out-release.sh for the requirement (flip the governing ticket +
+# RTM, move the governing ticket to approved-releases/, and move any absorbed
+# predecessor tickets to superseded-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
 
@@ -133,6 +134,7 @@ jobs:
           - release ticket moved to approved-releases/
           - release ticket status → RELEASED
           - RTM row → RELEASED
+          - absorbed predecessor tickets → superseded-releases/ (if the bundle manifest listed any)
 
           Ref: ${REQ}"
           git push -u origin "$BRANCH" --force-with-lease
@@ -144,6 +146,7 @@ jobs:
           - **main → develop reconciliation** — merges released code back into develop
           - **release ticket** moved to \`approved-releases/\`, status \`RELEASED\`
           - **RTM row** flipped to \`RELEASED\`
+          - **absorbed predecessor tickets** moved to \`superseded-releases/\` when the release bundle lists them
 
           Review + merge to develop."
           gh pr create --base develop --head "$BRANCH" \