@metasession.co/devaudit-cli 0.1.29 → 0.1.31

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