@metasession.co/devaudit-cli 0.1.30 → 0.1.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "description": "DevAudit CLI — installs, syncs, and operates the Metasession SDLC across consumer projects.",
   "type": "module",
   "bin": {
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.8.2",
-    "@metasession.co/devaudit-plugin-sdk": "^0.1.30",
+    "@metasession.co/devaudit-plugin-sdk": "^0.1.32",
     "commander": "^12.1.0",
     "consola": "^3.2.3",
     "env-paths": "^3.0.0",

package/sdlc/files/_common/3-compile-evidence.md

@@ -29,7 +29,7 @@ description: Compile test, security, and AI evidence, update RTM, create release
 | `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 |
 | `compliance/evidence/REQ-XXX/test-plan.md` | Git | Test strategy — tests to add/update/remove, mapped to criteria |
-| `compliance/evidence/REQ-XXX/test-execution-summary.md` | Git | Gate results, test changes, coverage against test plan |
+| `compliance/evidence/REQ-XXX/test-execution-summary.md` | Git | Gate results, test changes, coverage against test plan. **ISO 29119-3 §3.5.6 Test Completion Report for THIS release** — uploaded as `evidence_type=test_report` since v0.1.32, satisfying the portal's Test Reports gate with fresh per-release evidence. |
 | `compliance/evidence/REQ-XXX/ai-use-note.md` | Git | Small markdown, needs PR review |
 | `compliance/evidence/REQ-XXX/ai-prompts.md` | Git | Small markdown, needs PR review |
 | `compliance/evidence/REQ-XXX/security-summary.md` | Git | Small markdown, needs PR review |

package/sdlc/files/_common/governance/periodic-review.md.template

@@ -9,10 +9,12 @@ review_cadence_days: 90
 
 > ⚠️ **STARTER TEMPLATE — REPLACE BEFORE GOING TO PRODUCTION.**
 > This file was auto-installed by `devaudit install` as a starting point.
-> Once Workstream 3 ships (`.github/workflows/periodic-review.yml`), this file will be
-> auto-regenerated quarterly with portal metrics. Until then — and to add the human
-> attestation the auto-generator can't produce — edit this file yourself. Auditors
-> will reject unedited stubs. See `docs/governance-templates.md` for guidance.
+> The Periodic Review workflow (`.github/workflows/periodic-review.yml`, shipped in
+> v0.1.31) auto-regenerates this file quarterly with locally-derived metrics and
+> opens a PR. The human attestation sections (Review notes, control-effectiveness
+> judgement, dual-actor sign-off) still need to be filled in before each PR can
+> merge — the auto-generator can't produce defensible attestation on its own.
+> Auditors will reject unedited stubs. See `docs/governance-templates.md` for guidance.
 
 # Periodic Review of Internal Controls
 

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

@@ -430,17 +430,18 @@ jobs:
               --category test_report ${FLAGS}
           fi
 
-          # Upload test summary report — precise evidence_type=test_report
-          # (was compliance_document). The portal's Compliance Gates panel
-          # filters by evidence_type, so the markdown summary belongs in the
-          # Test Reports gate alongside playwright-report.zip + coverage
-          # summary. Markdown renders inline (MarkdownRenderer); auditor
-          # reads pass/fail counts + narrative without downloading the zip.
-          # devaudit#370 follow-up.
+          # Upload project-level Test Summary Report as a baseline
+          # `compliance_document`. As of v0.1.32 this is NOT a per-release
+          # gate artefact — the Test Reports gate is satisfied by the
+          # per-REQ `test-execution-summary.md` uploaded by
+          # compliance-evidence.yml (carries fresh release-specific data).
+          # The project-level TSR remains useful as Documents-tab baseline
+          # describing the project's testing posture but no longer poses
+          # as per-release test evidence. See DevAudit-Installer#101.
           if [ -f "compliance/test-summary-report.md" ]; then
             upload test-summary-report.md \
-              {{PROJECT_SLUG}} _compliance-docs test_report compliance/test-summary-report.md \
-              --category test_report ${FLAGS}
+              {{PROJECT_SLUG}} _compliance-docs compliance_document compliance/test-summary-report.md \
+              --category planning ${FLAGS}
           fi
 
           # Upload per-AC e2e evidence screenshots, scoped to each in-scope

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

@@ -138,15 +138,20 @@ jobs:
             fi
           done
 
-          # Test summary report — precise evidence_type=test_report so it
-          # lands in the portal's Test Reports gate (rendered inline by the
-          # MarkdownRenderer). devaudit#370 follow-up; same change applied
-          # in ci.yml's gate-evidence upload step.
+          # Project-level Test Summary Report — a hand-authored baseline
+          # describing the project's testing posture. As of v0.1.32 this is
+          # uploaded as `compliance_document` (NOT `test_report`) — the
+          # per-release Test Reports gate is now satisfied by the per-REQ
+          # `test-execution-summary.md` uploaded in the in-scope-requirements
+          # loop below, which carries fresh release-specific data. The
+          # project-level TSR continues to ship as a Documents-tab baseline
+          # but no longer poses as per-release test evidence.
+          # See DevAudit-Installer#101.
           if [ -f "compliance/test-summary-report.md" ]; then
-            echo "Uploading: test-summary-report.md (test_report type)"
+            echo "Uploading: test-summary-report.md (compliance_document — baseline)"
             bash scripts/upload-evidence.sh \
-              {{PROJECT_SLUG}} _compliance-docs test_report compliance/test-summary-report.md \
-              --category test_report ${FLAGS} --release "${DERIVED_RELEASE}" \
+              {{PROJECT_SLUG}} _compliance-docs compliance_document compliance/test-summary-report.md \
+              --category planning ${FLAGS} --release "${DERIVED_RELEASE}" \
               "${DERIVED_META[@]}" \
               || echo "Warning: Failed to upload test-summary-report.md"
           fi
@@ -257,12 +262,28 @@ jobs:
               REQ_META_ARGS=$(req_meta_args "$REQ_ID")
               for ARTIFACT in "$REQ_DIR"*.md; do
                 [ -f "$ARTIFACT" ] || continue
-                echo "Uploading: ${REQ_ID}/$(basename "$ARTIFACT")"
+                # Per-REQ test-execution-summary.md is the ISO 29119-3 §3.5.6
+                # Test Completion Report for THIS release cycle (populated by
+                # the e2e-test-engineer skill in Stage 3 — scope, results, AC
+                # mapping, defects). Upload as `test_report` so it satisfies
+                # the portal's Test Reports gate with per-release evidence
+                # instead of the project-level evergreen TSR (which from
+                # v0.1.32 downgrades to `compliance_document`). See
+                # DevAudit-Installer#101.
+                BASENAME=$(basename "$ARTIFACT")
+                if [ "$BASENAME" = "test-execution-summary.md" ] || [ "$BASENAME" = "test-summary-report.md" ]; then
+                  EVTYPE=test_report
+                  EVCAT=test_report
+                else
+                  EVTYPE=compliance_document
+                  EVCAT=planning
+                fi
+                echo "Uploading: ${REQ_ID}/${BASENAME} (${EVTYPE})"
                 eval "bash scripts/upload-evidence.sh \
-                  {{PROJECT_SLUG}} \"${REQ_ID}\" compliance_document \"$ARTIFACT\" \
-                  --category planning ${FLAGS} --release \"${REQ_ID}\" \
+                  {{PROJECT_SLUG}} \"${REQ_ID}\" ${EVTYPE} \"$ARTIFACT\" \
+                  --category ${EVCAT} ${FLAGS} --release \"${REQ_ID}\" \
                   ${REQ_META_ARGS}" \
-                  || echo "Warning: Failed to upload $(basename "$ARTIFACT")"
+                  || echo "Warning: Failed to upload ${BASENAME}"
               done
             done
           fi

package/sdlc/files/ci/incident-export.yml.template

@@ -0,0 +1,173 @@
+# Incident Export — auto-export a closed `label:incident` issue to compliance/governance/incident-report-<n>.md
+#
+# Generated by `devaudit install` / `devaudit update` from sdlc-config.json.
+# Do not edit manually — re-run the CLI (`devaudit update`) to regenerate.
+#
+# Why this exists:
+# - ISO 29119 3.5.4 (Test incident report), SOC 2 CC7.2 (System monitoring
+#   and incident response), and GDPR Art. 33 + 34 (breach notification)
+#   all want incident records as portal-resident evidence — not lost in
+#   GitHub issue threads.
+# - When an issue labelled `incident` is closed, this workflow exports its
+#   title + body + comments + timeline into a structured markdown report,
+#   opens a PR adding it to compliance/governance/, and lets the next
+#   push to develop pick it up via compliance-evidence.yml's
+#   upload_governance helper (uploads as `incident_report`).
+#
+# Operator setup (one-time):
+#   gh label create incident --color 'B60205' --description 'Operational or test incident; close to auto-archive as portal evidence'
+#
+# DevAudit-Installer#98 WS4.
+
+name: Incident Export
+
+on:
+  issues:
+    types: [closed]
+
+permissions:
+  contents: write
+  issues: read
+  pull-requests: write
+
+jobs:
+  export:
+    name: Export closed incident issue to compliance/governance/
+    runs-on: ubuntu-latest
+    # Only fire when the issue carries the `incident` label. Cheap predicate;
+    # skips this job entirely on unlabelled issue closes.
+    if: contains(github.event.issue.labels.*.name, 'incident')
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.DEVAUDIT_USER_TOKEN || github.token }}
+
+      - name: Compute paths
+        id: paths
+        env:
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+        run: |
+          OUT="compliance/governance/incident-report-${ISSUE_NUMBER}.md"
+          BRANCH="chore/incident-export-${ISSUE_NUMBER}"
+          echo "out=${OUT}" >> "$GITHUB_OUTPUT"
+          echo "branch=${BRANCH}" >> "$GITHUB_OUTPUT"
+
+      - name: Export issue to markdown
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          OUT: ${{ steps.paths.outputs.out }}
+        run: |
+          mkdir -p compliance/governance
+          ISSUE_JSON=$(gh issue view "$ISSUE_NUMBER" \
+            --json title,body,labels,author,createdAt,closedAt,comments,url,assignees,number,state)
+          {
+            echo "$ISSUE_JSON" | jq -r '
+              "---",
+              ("title: " + (.title | @json)),
+              ("incident_id: \"INC-" + (.createdAt[:10] | gsub("-";"")) + "-" + (.number|tostring) + "\""),
+              ("severity: \"REPLACE — low | medium | high | critical\""),
+              ("detected_at: " + (.createdAt | @json)),
+              ("resolved_at: " + (.closedAt | @json)),
+              ("involves_personal_data: \"REPLACE — true | false\""),
+              ("reported_to_supervisory_authority: \"REPLACE — true | false | n/a\""),
+              ("notification_window_72h: \"REPLACE — within | outside | n/a\""),
+              ("last_reviewed_at: " + (.closedAt[:10] | @json)),
+              ("source_issue: " + (.url | @json)),
+              ("source_issue_number: " + (.number|tostring)),
+              "---",
+              "",
+              "> ℹ️ Auto-exported by Incident Export workflow on issue close.",
+              "> The narrative below is the original issue body + comments.",
+              "> **Operator must replace the REPLACE markers in the frontmatter and",
+              "> in the GDPR triage / sign-off sections before this PR merges** —",
+              "> a personal-data triage decision is load-bearing; an auto-generated",
+              "> answer is not defensible. Auditors will reject auto-generated",
+              "> stubs without human attestation.",
+              "",
+              "# Incident Report — " + .title,
+              "",
+              "**Framework coverage:**",
+              "",
+              "- `ISO29119.3.5.4` (Test incident report)",
+              "- `SOC2.CC7.2` (System monitoring and incident response)",
+              "- `GDPR.Art-33` (Notification of a personal data breach to the supervisory authority — 72h)",
+              "- `GDPR.Art-34` (Communication of a personal data breach to the data subject)",
+              "",
+              "**Source:** [#" + (.number|tostring) + "](" + .url + ")  ",
+              "**Detected:** " + .createdAt + "  ",
+              "**Closed:** " + .closedAt + "  ",
+              "**Reporter:** @" + .author.login + "  ",
+              "**Assignees:** " + (if .assignees == [] then "_unassigned_" else (.assignees | map("@" + .login) | join(", ")) end) + "  ",
+              "**Labels:** " + (.labels | map("`" + .name + "`") | join(", ")),
+              "",
+              "## 1. Personal data scope (GDPR triage) — REPLACE",
+              "",
+              "| Question | Answer |",
+              "| --- | --- |",
+              "| Did the incident involve personal data? | REPLACE — Y / N |",
+              "| If Y: estimated number of data subjects affected | REPLACE |",
+              "| If Y: categories of personal data involved | REPLACE |",
+              "| If Y: likely consequences for data subjects | REPLACE |",
+              "| Notify supervisory authority (Art. 33)? | REPLACE — required if Y and risk to rights/freedoms |",
+              "| Notify data subjects (Art. 34)? | REPLACE — required if high risk to rights/freedoms |",
+              "| 72-hour notification window | REPLACE — within / outside / n/a |",
+              "",
+              "## 2. Narrative (from the GitHub issue)",
+              "",
+              .body,
+              "",
+              "## 3. Timeline (from issue comments)"
+            '
+            echo ""
+            # Comments — one section each, ordered by createdAt.
+            echo "$ISSUE_JSON" | jq -r '
+              .comments | sort_by(.createdAt) | .[] |
+              "### " + .createdAt + " — @" + .author.login + "\n\n" + .body + "\n"
+            '
+            cat <<'TAIL'
+
+          ## 4. Sign-off — REPLACE
+
+          | Role                                | Name    | Date    |
+          | ----------------------------------- | ------- | ------- |
+          | Incident Commander                  | REPLACE | REPLACE |
+          | Engineering lead                    | REPLACE | REPLACE |
+          | DPO (if personal data involved)     | REPLACE | REPLACE |
+          | Security lead                       | REPLACE | REPLACE |
+
+          ---
+
+          _Source: auto-exported by `.github/workflows/incident-export.yml` when the originating issue was closed._
+          TAIL
+          } > "$OUT"
+          echo "Wrote $OUT"
+
+      - name: Open export PR
+        env:
+          GH_TOKEN: ${{ secrets.DEVAUDIT_USER_TOKEN || github.token }}
+          BRANCH: ${{ steps.paths.outputs.branch }}
+          OUT: ${{ steps.paths.outputs.out }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          ISSUE_URL: ${{ github.event.issue.html_url }}
+        run: |
+          git config user.name 'devaudit-bot'
+          git config user.email 'devaudit-bot@users.noreply.github.com'
+          git fetch origin develop
+          git checkout -B "${BRANCH}" origin/develop
+          git add "$OUT"
+          if git diff --cached --quiet; then
+            echo "No change — already exported."
+            exit 0
+          fi
+          git commit -m "chore(compliance): export incident #${ISSUE_NUMBER}" -m "Auto-exported by Incident Export workflow." -m "" -m "Source: ${ISSUE_URL}" -m "" -m "REPLACE markers in the GDPR triage + Sign-off sections require human attestation before this PR can merge."
+          git push --force-with-lease origin "${BRANCH}"
+          EXISTING=$(gh pr list --head "${BRANCH}" --json number --jq '.[0].number' || true)
+          if [ -z "$EXISTING" ]; then
+            gh pr create --base develop --head "${BRANCH}" \
+              --title "chore(compliance): export incident #${ISSUE_NUMBER}" \
+              --body "Auto-exported by the \`Incident Export\` workflow when issue [#${ISSUE_NUMBER}](${ISSUE_URL}) was closed with label \`incident\`.\n\n**Required before merge:**\n- [ ] Replace \`REPLACE — …\` markers in the **GDPR triage** section (personal-data Y/N decision is load-bearing)\n- [ ] Fill in **severity** in the frontmatter\n- [ ] Add reviewer sign-off (IC, Eng lead, DPO if PII, Security lead)\n- [ ] If 72h window applies and we're outside it, document the delay explicitly\n\nSee [\`compliance/governance/incident-report.md\`](compliance/governance/incident-report.md) (the v0.1.30 starter) and [\`DevAudit-Installer/docs/governance-templates.md\`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/docs/governance-templates.md#gdpr--eu-general-data-protection-regulation-2016679) for guidance.\n\nCloses (for this incident) \`ISO29119.3.5.4\` + \`SOC2.CC7.2\`; \`GDPR.Art-33\` + \`Art-34\` close once the triage section is filled in."
+          else
+            echo "PR #${EXISTING} already open for this incident — branch updated in place."
+          fi

package/sdlc/files/ci/periodic-review.yml.template

@@ -0,0 +1,218 @@
+# Periodic Review — quarterly auto-generation of compliance/governance/periodic-review.md
+#
+# Generated by `devaudit install` / `devaudit update` from sdlc-config.json.
+# Do not edit manually — re-run the CLI (`devaudit update`) to regenerate.
+#
+# Why this exists:
+# - SOC 2 CC4.1 (Monitoring of internal controls) and ISO 27001 A.12.1
+#   (Operational procedures and responsibilities) require periodic
+#   review of controls + procedures. The portal flags `periodic_review`
+#   evidence as `expired` after 365 days.
+# - The v0.1.30 starter at compliance/governance/periodic-review.md
+#   covers the operator's first attestation. This workflow auto-
+#   regenerates it quarterly with locally-derived metrics + a clearly-
+#   marked "Review notes (operator fills in)" section, opens a PR so
+#   a human reviews + approves before it lands on develop, then
+#   compliance-evidence.yml uploads it as `periodic_review` evidence.
+#
+# DevAudit-Installer#98 WS3.
+
+name: Periodic Review
+
+on:
+  schedule:
+    # Quarterly: 1st of Jan / Apr / Jul / Oct at 09:00 UTC.
+    - cron: '0 9 1 */3 *'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  generate:
+    name: Generate quarterly periodic-review.md
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          # Need write access for the chore branch.
+          token: ${{ secrets.DEVAUDIT_USER_TOKEN || github.token }}
+
+      - name: Compute review period
+        id: period
+        run: |
+          # End of period = today. Start = ~90 days back (rough quarter).
+          PERIOD_END=$(date -u +%Y-%m-%d)
+          PERIOD_START=$(date -u -d '90 days ago' +%Y-%m-%d)
+          REVIEW_ID=$(date -u +%Y-Q%q 2>/dev/null || date -u +%Y-%m)
+          BRANCH="chore/periodic-review-${REVIEW_ID//[^A-Za-z0-9-]/-}"
+          echo "period_start=${PERIOD_START}" >> "$GITHUB_OUTPUT"
+          echo "period_end=${PERIOD_END}" >> "$GITHUB_OUTPUT"
+          echo "review_id=${REVIEW_ID}" >> "$GITHUB_OUTPUT"
+          echo "branch=${BRANCH}" >> "$GITHUB_OUTPUT"
+
+      - name: Derive metrics from repo state
+        id: metrics
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PERIOD_START: ${{ steps.period.outputs.period_start }}
+        run: |
+          # Counts come from local state — no portal API call needed.
+          # The portal can render against its own data; this summary is
+          # for the operator's review-and-attest moment.
+          RTM_REQS=0
+          PENDING_RELEASES=0
+          APPROVED_RELEASES=0
+          INCIDENT_REPORTS=0
+          if [ -f compliance/RTM.md ]; then
+            RTM_REQS=$(grep -oE '^\| REQ-[0-9]+ ' compliance/RTM.md | wc -l | tr -d ' ')
+          fi
+          if [ -d compliance/pending-releases ]; then
+            PENDING_RELEASES=$(find compliance/pending-releases -maxdepth 1 -name 'RELEASE-TICKET-REQ-*.md' -type f 2>/dev/null | wc -l | tr -d ' ')
+          fi
+          if [ -d compliance/approved-releases ]; then
+            APPROVED_RELEASES=$(find compliance/approved-releases -maxdepth 1 -name 'RELEASE-TICKET-REQ-*.md' -type f 2>/dev/null | wc -l | tr -d ' ')
+          fi
+          if [ -d compliance/governance ]; then
+            INCIDENT_REPORTS=$(find compliance/governance -maxdepth 1 -name 'incident-report*.md' -type f 2>/dev/null | wc -l | tr -d ' ')
+          fi
+          # CI pass-rate over the period — best-effort via gh.
+          CI_RUNS=$(gh run list --branch develop --limit 100 --json conclusion,createdAt 2>/dev/null || echo '[]')
+          TOTAL_RUNS=$(echo "$CI_RUNS" | jq --arg since "${PERIOD_START}T00:00:00Z" '[.[] | select(.createdAt >= $since)] | length' 2>/dev/null || echo 0)
+          PASSED_RUNS=$(echo "$CI_RUNS" | jq --arg since "${PERIOD_START}T00:00:00Z" '[.[] | select(.createdAt >= $since and .conclusion == "success")] | length' 2>/dev/null || echo 0)
+          PASS_RATE="n/a"
+          if [ "$TOTAL_RUNS" -gt 0 ]; then
+            PASS_RATE="$((100 * PASSED_RUNS / TOTAL_RUNS))%"
+          fi
+          {
+            echo "rtm_reqs=${RTM_REQS}"
+            echo "pending_releases=${PENDING_RELEASES}"
+            echo "approved_releases=${APPROVED_RELEASES}"
+            echo "incident_reports=${INCIDENT_REPORTS}"
+            echo "ci_total=${TOTAL_RUNS}"
+            echo "ci_passed=${PASSED_RUNS}"
+            echo "ci_pass_rate=${PASS_RATE}"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Render periodic-review.md
+        env:
+          PERIOD_START: ${{ steps.period.outputs.period_start }}
+          PERIOD_END: ${{ steps.period.outputs.period_end }}
+          REVIEW_ID: ${{ steps.period.outputs.review_id }}
+          RTM_REQS: ${{ steps.metrics.outputs.rtm_reqs }}
+          PENDING_RELEASES: ${{ steps.metrics.outputs.pending_releases }}
+          APPROVED_RELEASES: ${{ steps.metrics.outputs.approved_releases }}
+          INCIDENT_REPORTS: ${{ steps.metrics.outputs.incident_reports }}
+          CI_TOTAL: ${{ steps.metrics.outputs.ci_total }}
+          CI_PASSED: ${{ steps.metrics.outputs.ci_passed }}
+          CI_PASS_RATE: ${{ steps.metrics.outputs.ci_pass_rate }}
+        run: |
+          mkdir -p compliance/governance
+          cat > compliance/governance/periodic-review.md <<EOF
+          ---
+          title: "Periodic Review of Internal Controls (${REVIEW_ID})"
+          period_start: "${PERIOD_START}"
+          period_end: "${PERIOD_END}"
+          reviewer: "REPLACE — name + role"
+          last_reviewed_at: "${PERIOD_END}"
+          review_cadence_days: 90
+          ---
+
+          > ℹ️ Auto-generated by Periodic Review workflow on ${PERIOD_END}.
+          > The CI-derived metrics below are filled in automatically. The
+          > **Review notes** and **Sign-off** sections still require the
+          > human attestation — replace the REPLACE markers before merging
+          > this PR. Auditors will reject auto-generated stubs with no
+          > human attestation.
+
+          # Periodic Review of Internal Controls
+
+          **Framework coverage:** \`SOC2.CC4.1\` (Monitoring of internal controls), \`ISO27001.A.12.1\` (Operational procedures and responsibilities)
+
+          **Evidence type:** \`periodic_review\` · **Cadence:** every 90 days. The portal flags this evidence as \`expired\` after 365 days.
+
+          ## 1. Review period
+
+          - **From:** ${PERIOD_START}
+          - **To:** ${PERIOD_END}
+          - **Reviewer:** REPLACE — name + role
+          - **Approver (different person, dual-actor):** REPLACE
+
+          ## 2. Activity summary (auto-derived from repo state)
+
+          | Metric                                    | Value                     |
+          | ----------------------------------------- | ------------------------- |
+          | Total tracked REQs in RTM                 | ${RTM_REQS}               |
+          | Pending releases at period end            | ${PENDING_RELEASES}       |
+          | Approved releases (cumulative)            | ${APPROVED_RELEASES}      |
+          | Incident reports on disk                  | ${INCIDENT_REPORTS}       |
+          | CI runs on \`develop\` (this period)       | ${CI_TOTAL}               |
+          | CI runs passing                           | ${CI_PASSED}              |
+          | CI pass rate                              | ${CI_PASS_RATE}           |
+
+          ## 3. Review notes (operator fills in)
+
+          REPLACE — qualitative observations about the period. What worked? What didn't? What follow-ups are required? Reference incident reports under \`compliance/governance/incident-report-*.md\` if any.
+
+          ## 4. Control-effectiveness judgement
+
+          REPLACE — for each material control area, document evidence + reviewer judgement:
+
+          - **Access control (ISO 27001 A.5.15):** REPLACE — effective / partially / not
+          - **Change management (ISO 27001 A.8.32 / SOC 2 CC8.1):** REPLACE
+          - **Security testing (ISO 27001 A.8.29):** REPLACE
+          - **Logging and monitoring (ISO 27001 A.8.16 / EUAIA Art. 12):** REPLACE
+          - **Operational procedures (ISO 27001 A.12.1):** REPLACE
+
+          ## 5. Follow-up actions
+
+          | # | Finding | Severity | Owner | Due | Issue |
+          | - | ------- | -------- | ----- | --- | ----- |
+          | 1 | REPLACE | REPLACE  | REPLACE | REPLACE | REPLACE |
+
+          ## 6. Sign-off
+
+          | Role                       | Name    | Date    |
+          | -------------------------- | ------- | ------- |
+          | Reviewer                   | REPLACE | REPLACE |
+          | Approver (dual-actor)      | REPLACE | REPLACE |
+          | Decision                   | REPLACE — controls effective / partially effective / not effective |
+
+          ---
+
+          _Source data: \`compliance/RTM.md\`, \`compliance/pending-releases/\`, \`compliance/approved-releases/\`, \`compliance/governance/incident-report-*.md\`, GitHub Actions runs on \`develop\` since ${PERIOD_START}._
+          EOF
+          echo "Generated compliance/governance/periodic-review.md"
+
+      - name: Open / update review PR
+        env:
+          GH_TOKEN: ${{ secrets.DEVAUDIT_USER_TOKEN || github.token }}
+          BRANCH: ${{ steps.period.outputs.branch }}
+          REVIEW_ID: ${{ steps.period.outputs.review_id }}
+        run: |
+          # Configure git for the bot commit.
+          git config user.name 'devaudit-bot'
+          git config user.email 'devaudit-bot@users.noreply.github.com'
+          # Branch from develop. If a branch from a prior failed run exists,
+          # blow it away and start fresh; we always regenerate from the latest
+          # repo state.
+          git fetch origin develop
+          git checkout -B "${BRANCH}" origin/develop
+          git add compliance/governance/periodic-review.md
+          if git diff --cached --quiet; then
+            echo "No change to periodic-review.md — nothing to do."
+            exit 0
+          fi
+          git commit -m "chore(compliance): periodic review ${REVIEW_ID} (auto-generated)" -m "Quarterly periodic-review.md regenerated by Periodic Review workflow." -m "" -m "REPLACE markers in the Review notes / Control-effectiveness / Sign-off sections require human attestation before this PR can merge."
+          git push --force-with-lease origin "${BRANCH}"
+          # Open PR (or update existing).
+          EXISTING=$(gh pr list --head "${BRANCH}" --json number --jq '.[0].number' || true)
+          if [ -z "$EXISTING" ]; then
+            gh pr create --base develop --head "${BRANCH}" \
+              --title "chore(compliance): periodic review ${REVIEW_ID}" \
+              --body "Auto-generated quarterly periodic-review for **${REVIEW_ID}** by the \`Periodic Review\` workflow.\n\n**Required before merge:**\n- [ ] Replace \`REPLACE — …\` markers in the **Review notes** section\n- [ ] Fill in control-effectiveness judgement for each control area\n- [ ] Add reviewer + approver names (dual-actor)\n- [ ] List follow-up actions with owners + dates\n\nSee [\`docs/governance-templates.md\`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/docs/governance-templates.md#soc-2--trust-services-criteria) (SDLC repo) for guidance.\n\nCloses \`SOC2.CC4.1\` + \`ISO27001.A.12.1\` for the period once the PR lands on develop."
+          else
+            echo "PR #${EXISTING} already open for this period — branch updated in place."
+          fi