@metasession.co/devaudit-cli 0.1.40 → 0.1.42

package/sdlc/files/_common/skills/sdlc-implementer/SKILL.md

@@ -160,9 +160,10 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
    For HIGH/CRITICAL also include: threat model (against STRIDE categories applicable to the touched surfaces), four-eyes attestation slot, rollback plan — the template has slots for all of these.
 
    **Don't delete sections** — mark with `N/A — <reason>` if a clause genuinely doesn't apply (e.g. UI-only change with no personal-data scope). Empty stubs commit-then-upload as placeholder evidence and break the audit trail.
-6. **Update `compliance/RTM.md`** with the new entry: REQ-XXX, title, risk class, linked issue, linked test cases (placeholder).
-7. **Post plan summary as an issue comment.** Format: TL;DR; Risk class + signals; Acceptance criteria; Technical approach (one paragraph); Dependencies; Test scope.
-8. **Checkpoint** — pause for human approval **iff** risk class is HIGH or CRITICAL. LOW and MEDIUM pass through to Phase 2 automatically. The checkpoint can be forced on for all classes via the `--require-plan-approval` flag (or `DEVAUDIT_REQUIRE_PLAN_APPROVAL=1` env var) for orgs that want it always-on.
+6. **Invoke `requirements-aligner` to populate the SRS-ID column on the AC table.** The plan's "Acceptance criteria" table carries an SRS-ID column per AC; `requirements-aligner` fuzzy-matches each AC against `docs/SRS.md` and proposes new `REQ-AREA-NNN` stubs, flags stale items, or annotates `@srs-deferred`. Don't author the SRS-ID column inline — call via the standard Claude Code Skill mechanism (`Skill(name: "requirements-aligner", …)`). Block plan APPROVAL until every AC has a resolved SRS-ID per the skill's Phase 1 contract (configurable via `sdlc-config.json:requirements_aligner.block_on_stage_1`; ramp-up mode default-on for legacy projects).
+7. **Update `compliance/RTM.md`** with the new entry: REQ-XXX, title, risk class, linked issue, linked test cases (placeholder).
+8. **Post plan summary as an issue comment.** Format: TL;DR; Risk class + signals; Acceptance criteria (with SRS-IDs); Technical approach (one paragraph); Dependencies; Test scope.
+9. **Checkpoint** — pause for human approval **iff** risk class is HIGH or CRITICAL. LOW and MEDIUM pass through to Phase 2 automatically. The checkpoint can be forced on for all classes via the `--require-plan-approval` flag (or `DEVAUDIT_REQUIRE_PLAN_APPROVAL=1` env var) for orgs that want it always-on.
 
 ### Phase 2 — Implement and test (SDLC stage 2)
 
@@ -193,12 +194,14 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
 
 ### Phase 3 — Compile evidence (SDLC stage 3)
 
-1. **Re-run the full test pack** with artefact capture:
+1. **Invoke `requirements-aligner` to drop the per-REQ SRS-alignment artefact.** The skill's Phase 2 produces `compliance/evidence/REQ-XXX/srs-alignment.md` — the per-REQ trace from each AC to its SRS item, with an operator sign-off block. The artefact uploads with `evidence_type=srs_alignment` and closes `ISO29119.3.4` + `SOC2.CC2.1` for the REQ. Call via the standard Skill mechanism; don't inline the alignment logic.
+2. **Re-run the full test pack** with artefact capture:
    - `npm run test:e2e -- --reporter=html` (produces `playwright-report/`)
    - `npx vitest run --coverage` (produces `coverage/`)
-2. **Organise artefacts** under `compliance/evidence/REQ-XXX/` with date-prefixed naming:
+3. **Organise artefacts** under `compliance/evidence/REQ-XXX/` with date-prefixed naming:
    ```
    compliance/evidence/REQ-XXX/
+   ├── srs-alignment.md                  ← produced in step 1 by requirements-aligner
    ├── YYYY-MM-DD_e2e-results.json
    ├── YYYY-MM-DD_playwright-report/
    ├── YYYY-MM-DD_traces/                ← per-test trace.zip + error-context.md
@@ -207,7 +210,7 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
    ```
 
    Copy Playwright's `test-results/` folder verbatim into `YYYY-MM-DD_traces/` so trace-by-test-name is available for audit without walking the HTML report's hash-name index. For HIGH/CRITICAL releases the traces are part of the audit trail — *"what state was the page in when test X failed and was overridden?"* answers in one `ls` instead of an HTML-report walk.
-3. **Upload each artefact to the portal**:
+4. **Upload each artefact to the portal**:
    ```bash
    devaudit push <project-slug> REQ-XXX <evidence-type> <file> \
      --release "v$(date +%Y.%m.%d)" --create-release-if-missing \
@@ -215,9 +218,9 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
      --git-sha "$(git rev-parse HEAD)" \
      --branch "$(git rev-parse --abbrev-ref HEAD)"
    ```
-   Evidence types: `screenshot`, `e2e_result`, `test_report`, `audit_log`, `compliance_document`, `manual_upload`.
-4. **Verify uploads landed.** `gh api` or `curl` against `https://devaudit.metasession.co/projects/<slug>/requirements/REQ-XXX/evidence` should show every artefact.
-5. **Update `compliance/RTM.md`** with portal links for each evidence row.
+   Evidence types: `screenshot`, `e2e_result`, `test_report`, `audit_log`, `compliance_document`, `manual_upload`, `srs_alignment` (from step 1).
+5. **Verify uploads landed.** `gh api` or `curl` against `https://devaudit.metasession.co/projects/<slug>/requirements/REQ-XXX/evidence` should show every artefact.
+6. **Update `compliance/RTM.md`** with portal links for each evidence row.
 
 ### Phase 4 — Submit for UAT review (SDLC stage 4)
 

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

@@ -101,6 +101,87 @@ jobs:
           echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
           echo "Release version: ${VERSION}"
 
+      # Housekeeping artefact auto-generation (DevAudit-Installer#116 WS3+WS4)
+      #
+      # Housekeeping releases (bare-date version) need two operator-authored
+      # artefacts to clear the portal's release-completeness checklist:
+      # `RELEASE-TICKET-<version>.md` and `security-summary-<version>.md`.
+      # When the version resolves to a bare-date AND those artefacts don't
+      # already exist on develop, generate stubs from the CI gate JSON and
+      # open a PR that the operator reviews + signs off + merges. Once
+      # merged, the next compliance-evidence.yml run uploads them as
+      # evidence and the matrix flips both items to ✓.
+      #
+      # Mirrors the `incident-export.yml` pattern: auto-PR, operator fills
+      # in sign-off, merge to land.
+      - name: Auto-generate housekeeping stubs (if needed)
+        if: steps.resolve.outputs.skip != 'true'
+        env:
+          GH_TOKEN: ${{ secrets.DEVAUDIT_USER_TOKEN || github.token }}
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          # Guard: only fire for bare-date (housekeeping) versions.
+          if ! [[ "$VERSION" =~ ^v[0-9]{4}\.[0-9]{2}\.[0-9]{2}(\.[0-9]+)?$ ]]; then
+            echo "Version ${VERSION} is not housekeeping; skipping stub generation."
+            exit 0
+          fi
+          TICKET_PATH="compliance/pending-releases/RELEASE-TICKET-${VERSION}.md"
+          SECSUM_PATH="compliance/security-summary-${VERSION}.md"
+          # Skip when both stubs already exist (this branch already carries
+          # them, or a prior run already opened the PR and the artefacts
+          # have since merged).
+          if [ -f "$TICKET_PATH" ] && [ -f "$SECSUM_PATH" ]; then
+            echo "Housekeeping stubs already present for ${VERSION}; nothing to generate."
+            exit 0
+          fi
+          chmod +x scripts/generate-housekeeping-release-ticket.sh 2>/dev/null || true
+          chmod +x scripts/generate-security-summary.sh 2>/dev/null || true
+          mkdir -p compliance/pending-releases
+          # Generate any missing stubs. Each generator is independent so a
+          # partial-state branch (e.g. ticket already merged but security-
+          # summary still missing) only writes the missing half.
+          if [ ! -f "$TICKET_PATH" ]; then
+            bash scripts/generate-housekeeping-release-ticket.sh "$VERSION" > "$TICKET_PATH"
+            echo "Wrote $TICKET_PATH"
+          fi
+          if [ ! -f "$SECSUM_PATH" ]; then
+            bash scripts/generate-security-summary.sh "$VERSION" > "$SECSUM_PATH"
+            echo "Wrote $SECSUM_PATH"
+          fi
+          # Open the auto-PR. force-with-lease so re-runs on the same
+          # bare-date version update the same branch in place.
+          BRANCH="chore/housekeeping-release-${VERSION}"
+          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
+          # Re-write under the new branch (the checkout above resets the
+          # working tree — regenerate so the commit captures the stubs).
+          if [ ! -f "$TICKET_PATH" ]; then
+            bash scripts/generate-housekeeping-release-ticket.sh "$VERSION" > "$TICKET_PATH"
+          fi
+          if [ ! -f "$SECSUM_PATH" ]; then
+            bash scripts/generate-security-summary.sh "$VERSION" > "$SECSUM_PATH"
+          fi
+          git add "$TICKET_PATH" "$SECSUM_PATH"
+          if git diff --cached --quiet; then
+            echo "No change — stubs already on develop."
+            exit 0
+          fi
+          git commit -m "chore: housekeeping release-ticket stub + security-summary for ${VERSION}" \
+            -m "Auto-generated by compliance-evidence.yml (DevAudit-Installer#116)." \
+            -m "" \
+            -m "REPLACE markers in the Risk Assessment + Sign-off blocks require operator review before 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(housekeeping): release-ticket + security-summary stubs for ${VERSION}" \
+              --body "Auto-generated by the \`Compliance Evidence Upload\` workflow when develop received a housekeeping push (no \`REQ-XXX\` in commit subjects; version derived as bare-date \`${VERSION}\`).\n\n**Files added:**\n- \`${TICKET_PATH}\` — release ticket stub with commit summary + sign-off block\n- \`${SECSUM_PATH}\` — security summary stub scraping SAST + dep-audit gate JSON\n\n**Required before merge:**\n- [ ] Replace \`REPLACE — …\` markers in the **Summary**, **Risk Assessment**, and **Sign-off** blocks on both files\n- [ ] Confirm the auto-scraped SAST + dep-audit counts match what the gate panel shows\n- [ ] Add reviewer sign-off (operator name + date)\n\nOnce merged, the next \`compliance-evidence.yml\` run uploads both artefacts as evidence and the portal's release-completeness checklist flips the **Security summary present** + **Release ticket present** items to ✓.\n\nSee [stage-3 SDLC doc \"Housekeeping releases\" section](../SDLC/3-compile-evidence.md) for the full operator walkthrough."
+          else
+            echo "PR #${EXISTING} already open for ${VERSION} — branch updated in place."
+          fi
+
       - name: Upload compliance documents
         if: steps.resolve.outputs.skip != 'true'
         run: |

package/sdlc/files/sdlc-config.example.json

@@ -84,5 +84,14 @@
   "production_review": {
     "enabled": true,
     "terminal_status": "prod_review"
+  },
+
+  "_comment_requirements_aligner": "requirements-aligner skill toggles (DevAudit-Installer#119, v0.1.42+). Controls when the skill blocks vs advises. block_on_stage_1=false (default) means the skill advises on AC-to-SRS mapping at plan APPROVAL but doesn't block; flip to true once docs/SRS.md is populated enough for the check to be reliably surfacing real drift (not false-positives on sparse SoT). block_on_stage_3=true means the per-REQ srs-alignment.md artefact is required before Stage 3 completes — the per-REQ evidence is the hard gate. auto_file_followup_issue=false means the skill never opens GitHub issues automatically; if gaps are detected and operator defers, operator files follow-up manually. ramp_up_runs=5 means the first 5 invocations on a project are audit-only regardless of block_on_stage_1, so legacy projects with sparse SRS get time to populate before blocking enforces.",
+  "requirements_aligner": {
+    "enabled": true,
+    "block_on_stage_1": false,
+    "block_on_stage_3": true,
+    "auto_file_followup_issue": false,
+    "ramp_up_runs": 5
   }
 }