@metasession.co/devaudit-cli 0.1.39 → 0.1.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "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.39",
+    "@metasession.co/devaudit-plugin-sdk": "^0.1.41",
     "commander": "^12.1.0",
     "consola": "^3.2.3",
     "env-paths": "^3.0.0",

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

@@ -58,6 +58,38 @@ Both `ci.yml` and `compliance-evidence.yml` call the same helper, so a feature s
 
 If you need a separate release container for a sub-piece of work — e.g. carving REQ-038 out of an in-flight feature — give it its own REQ-ID and tag the commits accordingly.
 
+## Two release shapes
+
+A release is classified by its version pattern. **Most of this doc walks the tracked path** (a REQ-XXX-tagged release for a single requirement). For develop pushes that don't carry a REQ tag — typically `docs:`, `chore:`, `ci:`, `build:`, `test:`, `compliance:`, `revert:` — the version-deriver falls back to a bare date and the release is **housekeeping**.
+
+| Shape | Version pattern | Triggered by | Per-REQ ceremony |
+|---|---|---|---|
+| **Tracked** | `REQ-037`, `REQ-046-FIX`, etc. | A `feat`/`fix`/`refactor`/`perf` commit (REQ tag required by commitlint) | Yes — full Steps 1-9 |
+| **Housekeeping** | `v2026.06.04` (bare date, optionally `.N`) | A push containing only REQ-exempt commit types | **No** per-REQ artefacts; the portal auto-skips test-scope, test-plan, implementation-plan, and test-execution-summary completeness checks |
+
+### Housekeeping releases — what's required
+
+Housekeeping releases **skip** the per-requirement evidence (no REQ → no `compliance/evidence/REQ-XXX/` folder) but **still produce two release-scoped artefacts**:
+
+| Artefact | Tracked path | Housekeeping path | Auto-generated by CI? |
+|---|---|---|---|
+| Release ticket | `compliance/pending-releases/RELEASE-TICKET-REQ-XXX.md` (Step 8) | `compliance/pending-releases/RELEASE-TICKET-<version>.md` (e.g. `RELEASE-TICKET-v2026.06.04.md`) | **Yes** — `generate-housekeeping-release-ticket.sh` runs after `derive-release-version.sh` and emits a stub the operator reviews + signs off |
+| Security summary | `compliance/evidence/REQ-XXX/security-summary.md` (Step 4) | `compliance/security-summary-<version>.md` at the compliance root (release-scoped, not REQ-scoped) | **Yes** — `generate-security-summary.sh` scrapes the SAST + dep-audit gate JSON and emits a stub with an operator sign-off block |
+
+**The portal evidence check is lenient on filename.** Any file whose name (case-insensitive) starts with `release-ticket` satisfies the release-ticket check, and any file named exactly `security-summary.md` satisfies the security-summary check. The version-suffixed conventions above are recommended for **searchability + audit trail** when a project has many housekeeping releases stacked up — they keep the artefacts distinct per release without needing folder scoping.
+
+**What housekeeping operators do, end to end:**
+
+1. Push the `docs:` / `chore:` / `ci:` commits to develop. CI runs the four gates as usual.
+2. CI's `compliance-evidence.yml` workflow auto-opens a PR (`chore/housekeeping-release-<version>`) containing the two stubs.
+3. Review the stubs — confirm the commit-summary list in the release ticket is sensible, confirm the SAST + dep-audit summary reads correctly, fill in the operator sign-off block on each.
+4. Merge that PR. The next CI run picks up the artefacts and the portal's release-completeness checklist flips both items to ✓.
+5. Submit for UAT review on the portal. The approval flow is identical to the tracked path — same four-eyes rules (per project risk tier), same `draft → uat_review → uat_approved → prod_review → prod_approved → released` state machine.
+
+**No auto-approval.** Housekeeping releases still require operator action to advance through the gates. The CI-generated stubs replace the operator's authoring effort, not the operator's review.
+
+> **Versions of the framework before 2026-06 produced housekeeping stubs by hand.** Older release records may have `security-summary.md` under a REQ-XXX-shaped folder or no release ticket at all — leave those in DRAFT for the audit trail; backfilling isn't required.
+
 ## Steps
 
 ### Step 0: Confirm CI Is Green

package/sdlc/files/_common/implementing-an-sdlc-issue.md

@@ -45,7 +45,7 @@ A worked end-to-end example for a zero-risk change (a typo, a dependency bump, a
 3. **Commit with a housekeeping type.** `docs:` / `chore:` / `ci:` / `build:` / `test:` / `revert:` are **exempt** from the `[REQ-XXX]` rule — e.g. `git commit -m "docs: fix typo in README"`. A `feat` / `fix` / `refactor` / `perf` subject without a `[REQ-XXX]` or `Ref: REQ-XXX` is **rejected** by commitlint and `validate-commits.sh` — if that fires, you picked the wrong type and the change isn't trivial.
 4. **Run the gates locally — not optional.** `npx tsc --noEmit`, lint, and the test suite must pass before you push. Trivial ≠ unverified.
 5. **Push and open a PR.** CI runs the same quality gates. `compliance-validation.yml` finds no `REQ-XXX` and **skips** artifact validation; no release ticket, no RTM row, no evidence pack is required.
-6. **Merge once CI is green** and a reviewer approves the PR. There's **no** portal release record to approve, no UAT/Production gate, and no close-out — a housekeeping push produces at most a bare-date release (`vYYYY.MM.DD`), which carries no approval gate. (Contrast the tracked-change flow below, which produces a `REQ-XXX` release that goes through four-eyes.)
+6. **Merge once CI is green** and a reviewer approves the PR. A housekeeping push **does** produce a portal release record — a bare-date release (`vYYYY.MM.DD`) — and it **does** go through the same UAT → production four-eyes flow as a tracked release. What the portal **auto-skips for housekeeping** is the four per-REQ completeness items (test-scope / test-plan / implementation-plan / test-execution-summary) — those have nothing to evaluate without a `REQ-XXX`. What's still required: all four CI gates green, a release ticket (`compliance/pending-releases/RELEASE-TICKET-<version>.md`), and a security summary (`compliance/security-summary-<version>.md`). **CI auto-generates both stubs as an operator-sign-off PR** (DevAudit-Installer v0.1.41+, scripts `generate-housekeeping-release-ticket.sh` + `generate-security-summary.sh`). Review the stubs + replace the `REPLACE — …` markers + merge → next CI run uploads them → matrix flips both items to ✓ → submit for UAT review on the portal. See [stage-3 housekeeping section](./3-compile-evidence.md) for the full walkthrough.
 
 If at any step it stops feeling trivial — it changes behaviour, touches auth/payments/data, or an auditor would ask about it — switch to a tracked change and run `sdlc-implementer`. When unsure, it's not trivial.
 

package/sdlc/files/_common/scripts/generate-housekeeping-release-ticket.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# generate-housekeeping-release-ticket.sh
+#
+# Writes a housekeeping release-ticket stub for a bare-date release
+# (`v2026.06.04` etc.). Synced into the consumer's `scripts/` by
+# `devaudit update`; invoked from `compliance-evidence.yml` after
+# `derive-release-version.sh` when the version pattern is bare-date AND
+# no ticket file already exists.
+#
+# Usage:
+#   bash scripts/generate-housekeeping-release-ticket.sh <version> > <out>
+#
+# Where <version> is the bare-date version (e.g. `v2026.06.04`) and
+# <out> is the target path (typically `compliance/pending-releases/
+# RELEASE-TICKET-<version>.md`).
+#
+# The stub carries:
+# - Frontmatter with version + generated_at + last_reviewed_at (defaults
+#   to today; operator updates on sign-off)
+# - Commit summaries since the previous release tag (or last 20 commits
+#   if no prior tag exists)
+# - An operator sign-off block with `REPLACE — …` markers the operator
+#   must fill in before merging the auto-PR
+#
+# Companion to `generate-security-summary.sh`. Both are invoked together
+# by the CI workflow.
+#
+# DevAudit-Installer#116 WS3.
+
+set -euo pipefail
+
+VERSION="${1:-}"
+if [ -z "$VERSION" ]; then
+  echo "usage: $(basename "$0") <version>" >&2
+  exit 2
+fi
+
+# Validate bare-date pattern (matches `classifyReleaseShape` in META-COMPLY).
+if ! [[ "$VERSION" =~ ^v[0-9]{4}\.[0-9]{2}\.[0-9]{2}(\.[0-9]+)?$ ]]; then
+  echo "error: '$VERSION' is not a bare-date version (expected vYYYY.MM.DD[.N])" >&2
+  exit 2
+fi
+
+TODAY=$(date -u +%Y-%m-%d)
+
+# Last 20 commits with subject lines. Skip the version-deriver fallback
+# from itself (avoid recursion if this script is re-run on a branch
+# that already includes its own auto-commit).
+COMMIT_LINES=$(git log -20 --pretty=format:'- `%h` %s' 2>/dev/null \
+  | grep -v 'chore: housekeeping release-ticket stub' \
+  | head -15)
+if [ -z "$COMMIT_LINES" ]; then
+  COMMIT_LINES="- _(no commits found in `git log` — this stub was generated outside a git context)_"
+fi
+
+cat <<EOF
+---
+version: "$VERSION"
+release_shape: housekeeping
+generated_at: "$TODAY"
+last_reviewed_at: "$TODAY"
+generated_by: "generate-housekeeping-release-ticket.sh (DevAudit-Installer#116)"
+---
+
+> ⚠️ **AUTO-GENERATED STUB — REPLACE BEFORE MERGE**
+>
+> This release ticket was auto-generated by CI when develop received a
+> housekeeping push (no \`REQ-XXX\` in commit subjects, version derived
+> as bare-date \`$VERSION\`).
+>
+> **The operator must:**
+> 1. Confirm the **Summary** below describes the actual intent of these
+>    commits — replace the placeholder if the auto-summary is generic.
+> 2. Fill in the **Sign-off** block with the operator's name + date +
+>    risk assessment.
+> 3. Merge this PR. The next \`compliance-evidence.yml\` run will upload
+>    this file as \`release_artifact\` evidence, satisfying the
+>    portal's release-ticket completeness check.
+
+# Release Ticket: $VERSION (housekeeping)
+
+**Status:** TESTED - PENDING SIGN-OFF
+**Date:** $TODAY
+**Release Shape:** Housekeeping (bare-date, no REQ tag)
+**Version:** $VERSION
+
+---
+
+## Summary
+
+REPLACE — one or two sentences describing what these housekeeping commits delivered. Examples: *"Documentation refresh for the v0.1.39 governance changes; no code paths touched."* / *"Dependency bumps (vitest 4.0.5 → 4.0.6, prettier 4.3.0 → 4.3.1) caught by Dependabot; no behavioural change."* / *"CI workflow housekeeping: retry-on-flake threshold raised, runner image pinned."*
+
+## Commits in this release
+
+$COMMIT_LINES
+
+## Risk Assessment
+
+REPLACE — confirm risk class for this release (typically LOW for housekeeping):
+
+- [ ] **LOW** — documentation, dependency bumps, CI tweaks, internal refactors. No user-visible behaviour change.
+- [ ] **MEDIUM** — touches code paths an end-user reaches; user-visible change is small and well-contained.
+- [ ] **HIGH** — should not be a housekeeping release. If this is checked, **stop and re-tag the commits with \`REQ-XXX\`** so the release is tracked properly.
+
+## Test Evidence
+
+| Test Type | Status | Source |
+|---|---|---|
+| TypeScript | $(test -f gate-outcomes.json && echo "see gate-outcomes.json" || echo "REPLACE — green / N/A") | CI \`typecheck\` gate |
+| SAST | $(test -f gate-outcomes.json && echo "see gate-outcomes.json" || echo "REPLACE — green / N/A") | CI \`SAST\` gate |
+| Dependency audit | $(test -f gate-outcomes.json && echo "see gate-outcomes.json" || echo "REPLACE — green / N/A") | CI \`dependency_audit\` gate |
+| E2E | $(test -f gate-outcomes.json && echo "see gate-outcomes.json" || echo "REPLACE — green / N/A") | CI \`e2e\` gate |
+| Test reports | $(test -f gate-outcomes.json && echo "see gate-outcomes.json" || echo "REPLACE — green / N/A") | CI \`test_report\` gate |
+
+> Companion artefact: \`compliance/security-summary-$VERSION.md\` (auto-generated by \`generate-security-summary.sh\` in the same workflow run; contains the SAST + dep-audit findings detail).
+
+## Acceptance Criteria
+
+- [x] All four compliance gates green on the CI run that produced this stub
+- [x] No \`REQ-XXX\`-tagged commits in this release (housekeeping by definition)
+- [ ] Operator-reviewed and signed off — see Sign-off block below
+
+## Post-Deploy Actions
+
+| Type | Script / Command | Target | Required | Notes |
+|------|-----------------|--------|----------|-------|
+| — | None | — | — | Housekeeping releases typically have no post-deploy actions |
+
+<!-- Replace the "None" row above if this release requires post-deploy work. -->
+
+---
+
+## Sign-off
+
+| Role | Name | Date | Notes |
+|---|---|---|---|
+| Submitter | REPLACE | $TODAY | Auto-generated by CI; reviewed + edited |
+| Reviewer (independent if project risk_tier ≠ low) | REPLACE | REPLACE | REPLACE |
+
+## Audit Trail
+
+| Date | Action | Actor | Notes |
+|------|--------|-------|-------|
+| $TODAY | Stub auto-generated | devaudit-bot | Bare-date version $VERSION |
+| REPLACE | Operator sign-off | REPLACE | REPLACE |
+| REPLACE | Submitted for UAT review | REPLACE | Via portal |
+EOF

package/sdlc/files/_common/scripts/generate-security-summary.sh

@@ -0,0 +1,170 @@
+#!/usr/bin/env bash
+# generate-security-summary.sh
+#
+# Writes a security-summary stub for a release. Resolves the dangling
+# reference in META-COMPLY's release-checklist (the UI hint mentioned a
+# generator script that didn't exist).
+#
+# Usage:
+#   bash scripts/generate-security-summary.sh <version> > <out>
+#
+# - For housekeeping releases (bare-date version), the canonical
+#   <out> is `compliance/security-summary-<version>.md` at the
+#   compliance root.
+# - For tracked releases (REQ-XXX version), the canonical <out> is
+#   `compliance/evidence/REQ-XXX/security-summary.md`. The script
+#   outputs the same body shape; only the caller decides the path.
+#
+# Scrapes:
+# - `sast-results.json` (Semgrep) — high/critical findings count
+# - `dependency-audit.json` (npm audit / pip-audit) — high/critical
+#   vulnerability count
+# - `gate-outcomes.json` (DevAudit-Installer v0.1.29) — per-gate
+#   pass/fail/skip status
+#
+# Each source is optional — the stub gracefully reports "not found"
+# rather than erroring out. The operator fills in any missing detail
+# in the sign-off block before merging the auto-PR.
+#
+# DevAudit-Installer#116 WS4.
+
+set -euo pipefail
+
+VERSION="${1:-}"
+if [ -z "$VERSION" ]; then
+  echo "usage: $(basename "$0") <version>" >&2
+  exit 2
+fi
+
+TODAY=$(date -u +%Y-%m-%d)
+
+# Detect release shape from the version.
+SHAPE="unknown"
+if [[ "$VERSION" =~ ^v[0-9]{4}\.[0-9]{2}\.[0-9]{2}(\.[0-9]+)?$ ]]; then
+  SHAPE="housekeeping"
+elif [[ "$VERSION" =~ ^REQ- ]]; then
+  SHAPE="tracked"
+fi
+
+# Helper: scrape Semgrep JSON for high/critical counts. Soft-fails when
+# the file is absent or jq isn't available.
+sast_summary() {
+  if [ ! -f sast-results.json ]; then
+    echo "REPLACE — \`sast-results.json\` not present at CWD; check that the SAST gate ran on this commit"
+    return
+  fi
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "REPLACE — \`jq\` not available; manually inspect \`sast-results.json\`"
+    return
+  fi
+  local HIGH CRITICAL TOTAL
+  HIGH=$(jq -r '[.results[]? | select(.extra.severity == "WARNING" or .extra.severity == "ERROR")] | length' sast-results.json 2>/dev/null || echo "?")
+  CRITICAL=$(jq -r '[.results[]? | select(.extra.severity == "ERROR")] | length' sast-results.json 2>/dev/null || echo "?")
+  TOTAL=$(jq -r '[.results[]?] | length' sast-results.json 2>/dev/null || echo "?")
+  echo "$TOTAL total finding(s) · $HIGH high/warning · $CRITICAL critical/error"
+}
+
+# Helper: scrape npm audit JSON. Tolerant of both `npm audit --json`
+# shape (vulnerabilities object) and pip-audit shape (vulnerabilities
+# array).
+dep_audit_summary() {
+  if [ ! -f dependency-audit.json ]; then
+    echo "REPLACE — \`dependency-audit.json\` not present at CWD; check that the dependency-audit gate ran on this commit"
+    return
+  fi
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "REPLACE — \`jq\` not available; manually inspect \`dependency-audit.json\`"
+    return
+  fi
+  # npm audit shape: .vulnerabilities is an object keyed by package
+  # name with .severity per row.
+  local HIGH CRITICAL TOTAL
+  HIGH=$(jq -r '[.vulnerabilities | (if type == "object" then to_entries[] | .value else .[]? end) | select(.severity == "high")] | length' dependency-audit.json 2>/dev/null || echo "?")
+  CRITICAL=$(jq -r '[.vulnerabilities | (if type == "object" then to_entries[] | .value else .[]? end) | select(.severity == "critical")] | length' dependency-audit.json 2>/dev/null || echo "?")
+  TOTAL=$(jq -r '[.vulnerabilities | (if type == "object" then to_entries[] | .value else .[]? end)] | length' dependency-audit.json 2>/dev/null || echo "?")
+  echo "$TOTAL total vulnerability/ies · $HIGH high · $CRITICAL critical"
+}
+
+# Helper: gate-outcomes.json (DevAudit-Installer v0.1.29 onwards).
+gate_outcomes_summary() {
+  if [ ! -f gate-outcomes.json ]; then
+    echo "REPLACE — \`gate-outcomes.json\` not present at CWD"
+    return
+  fi
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "REPLACE — \`jq\` not available; manually inspect \`gate-outcomes.json\`"
+    return
+  fi
+  jq -r 'to_entries[] | "- **\(.key)** — \(.value // "?")"' gate-outcomes.json 2>/dev/null \
+    || echo "REPLACE — could not parse gate-outcomes.json"
+}
+
+SAST_SUMMARY=$(sast_summary)
+DEP_SUMMARY=$(dep_audit_summary)
+GATES=$(gate_outcomes_summary)
+
+cat <<EOF
+---
+version: "$VERSION"
+release_shape: $SHAPE
+generated_at: "$TODAY"
+last_reviewed_at: "$TODAY"
+generated_by: "generate-security-summary.sh (DevAudit-Installer#116)"
+---
+
+> ⚠️ **AUTO-GENERATED STUB — REVIEW BEFORE MERGE**
+>
+> This security summary was auto-generated by CI from the SAST and
+> dependency-audit gate JSON. The operator should:
+>
+> 1. Confirm the **findings summary** matches what they saw on the
+>    gate panel for this release.
+> 2. Replace any \`REPLACE — …\` markers below (typically the access-
+>    control + audit-log assessment, which the gates can't infer).
+> 3. Sign off in the **Sign-off** block before this PR merges.
+
+# Security Summary — $VERSION
+
+**Release shape:** $SHAPE
+**Generated:** $TODAY
+**Source data:** \`sast-results.json\` + \`dependency-audit.json\` + \`gate-outcomes.json\` (this CI run)
+
+## SAST findings (Semgrep)
+
+$SAST_SUMMARY
+
+> **Policy:** the SAST gate fails the build at \`high\` or \`critical\` severity. If this release shipped, both are zero.
+
+## Dependency vulnerabilities
+
+$DEP_SUMMARY
+
+> **Policy:** the dependency-audit gate fails the build at \`high\` or \`critical\` severity. If this release shipped, both are zero.
+
+## Gate outcomes (per CI run)
+
+$GATES
+
+## Access control + audit log
+
+| Check | Result | Notes |
+|---|---|---|
+| Access control unchanged | REPLACE — yes/no | If yes, no further work. If no, document the auth/RBAC delta and confirm it landed an audit event. |
+| Audit log append-only invariant preserved | REPLACE — yes/no | If yes, no further work. If no, document why and confirm the change has independent review. |
+| Sensitive data exposure | REPLACE — yes/no | If yes, escalate to the GDPR triage in \`compliance/governance/dpia.md\` before merging. |
+
+## Risk Assessment
+
+REPLACE — one paragraph summarising the security posture of this release. For housekeeping releases the typical wording is *"No code paths touched; security posture unchanged from the previous release."* For tracked releases name the touched modules + threat model assessment.
+
+---
+
+## Sign-off
+
+| Role | Name | Date | Notes |
+|---|---|---|---|
+| Author | devaudit-bot (auto-generated) | $TODAY | Stub generated from CI gate JSON |
+| Reviewer | REPLACE | REPLACE | REPLACE |
+
+Once reviewed + signed off, this file is uploaded as evidence by the next \`compliance-evidence.yml\` run; the portal's release-completeness checklist flips the security-summary item to ✓.
+EOF

package/sdlc/files/_common/skills/e2e-test-engineer/SKILL.md

@@ -327,7 +327,7 @@ test('AC1: edit dialog opens with fields pre-filled', async ({ page }) => {
 - Call `evidenceShot` **immediately after** the AC-proving assertion, before navigating, closing dialogs, or any further interaction.
 - AC number is a separate argument (`ac: number`) — the helper composes the filename `REQ-XXX-AC<n>-<slug>.png`. The slug describes what the screenshot proves (`edit-dialog-prefilled`), NOT the AC number.
 - Slug is kebab-case lowercase (`[a-z0-9-]+`). Capitalised slugs, underscores, or spaces throw.
-- One screenshot per AC, not per test.
+- One **canonical** screenshot per AC; additional stage screenshots are tier-gated — see *Screenshot density per spec role* below.
 - Failure forensics stays untouched (`screenshot: 'only-on-failure'` + `trace: 'on-first-retry'`).
 
 The helper is shipped automatically into `e2e/helpers/evidence.ts` by the SDLC sync (node-stack consumers). Output lands at `compliance/evidence/<REQ-ID>/screenshots/REQ-XXX-AC<n>-<slug>.png` — commit these PNGs as part of the evidence pack so reviewers can corroborate the test-plan AC mapping.
@@ -336,6 +336,43 @@ The helper also writes a sidecar `<filename>.meta.json` containing the AC mappin
 
 The canonical helper source lives at `references/evidence.ts` in this skill.
 
+### Screenshot density per spec role
+
+The number of `evidenceShot` calls per spec should scale to the spec's role:
+
+- **While the spec is a feature artefact** (newly authored on the branch, before merge to develop): capture multiple stages — every meaningful transition or state the AC documents. The dense evidence is what reviewers use to verify the AC was met end-to-end during the feature cycle.
+- **Once the spec joins the regression pack** (post-merge, `git diff --diff-filter=A` no longer matches it): capture only the canonical "this still works" anchor per AC. Re-running the dense journey on every regression cycle is noise and inflates CI artefact storage with little signal.
+
+The `EvidenceShotOrigin` signal (`'feature' | 'regression'`) auto-detects from `E2E_NEW_SPECS`. Mark stage screenshots with `{ tier: 'feature' }`; the helper auto-suppresses them on regression runs. The canonical anchor uses the default tier (`'always'`).
+
+```ts
+test('AC7: stock dial completes the transition', async ({ page }) => {
+  // Stage screenshots — fire while the spec is a feature artefact;
+  // auto-suppress once it graduates into the regression pack.
+  await openStockDial(page, item.id);
+  await evidenceShot(page, 'REQ-066', 7, 'dial-open',  { tier: 'feature' });
+  await advanceDial(page);
+  await evidenceShot(page, 'REQ-066', 7, 'in-progress', { tier: 'feature' });
+
+  // Canonical anchor — always fires (default tier: 'always').
+  // This is the artefact every future regression run re-captures as
+  // proof the AC still holds.
+  await expect(dial.getByRole('status')).toHaveText('Completed');
+  await evidenceShot(page, 'REQ-066', 7, 'completed');
+});
+```
+
+A reasonable default per AC:
+
+- 1× canonical "completed / final state" shot (tier `'always'`).
+- 1–3× stage shots covering the meaningful intermediate transitions (tier `'feature'`).
+
+When to deviate:
+
+- **Single-shot ACs** (one assertion that's its own proof — e.g. *"the form submits and returns to the list"*) need only the canonical anchor. Don't manufacture stages just to hit the 1–3 band.
+- **Long flows** (>3 meaningful transitions) keep all stages tier `'feature'`. The post-merge regression run still has the canonical anchor to corroborate the AC; the dense journey is on the feature PR for reviewers and in the audit-pack download for that release forever.
+- **Reviewer pushback that evidence feels thin** (single-shot per AC across a HIGH-risk REQ) almost always means tier `'feature'` stages are missing — add them on the feature branch where they actually fire, not after.
+
 ---
 
 ## Principles

package/sdlc/files/_common/skills/e2e-test-engineer/references/evidence-shot-core.ts

@@ -7,6 +7,23 @@
 
 export type EvidenceShotOrigin = 'feature' | 'regression';
 
+/**
+ * Capture density tier. Lets spec authors mark intermediate-state
+ * screenshots that only matter while the spec is being authored on a
+ * feature branch — once the spec joins the regression pack, those
+ * become noise and inflate CI artefact storage.
+ *
+ * - `'always'` (default) — capture on every run. Use for the canonical
+ *   "this still works" anchor per AC; the artefact reviewers rely on
+ *   to corroborate the test-plan mapping across every release.
+ * - `'feature'` — capture only when the spec's origin is `feature`
+ *   (i.e. the spec was added on the current branch per
+ *   `E2E_NEW_SPECS`). Auto-suppressed once the spec graduates into
+ *   the regression pack. Use for stage screenshots covering meaningful
+ *   intermediate transitions reviewers want during the feature cycle.
+ */
+export type EvidenceShotTier = 'always' | 'feature';
+
 export interface EvidenceShotSidecar {
   readonly origin: EvidenceShotOrigin;
   readonly reqId: string;
@@ -16,6 +33,20 @@ export interface EvidenceShotSidecar {
   readonly capturedAt: string;
 }
 
+/**
+ * Pure decision: should the capture be suppressed?
+ *
+ * The only suppression case is `tier='feature'` × `origin='regression'`
+ * — a stage screenshot whose spec has graduated into the regression
+ * pack. Every other (tier, origin) combination captures.
+ */
+export function shouldSuppressEvidenceShot(
+  tier: EvidenceShotTier,
+  origin: EvidenceShotOrigin,
+): boolean {
+  return tier === 'feature' && origin === 'regression';
+}
+
 const REQ_ID_RE = /^REQ-[A-Z0-9-]+$/;
 const SLUG_RE = /^[a-z0-9-]+$/;
 

package/sdlc/files/_common/skills/e2e-test-engineer/references/evidence.ts

@@ -4,12 +4,14 @@ import { test, type Page } from '@playwright/test';
 import {
   autoDetectEvidenceShotOrigin,
   composeScreenshotFilename,
+  shouldSuppressEvidenceShot,
   validateEvidenceShotInputs,
   type EvidenceShotOrigin,
   type EvidenceShotSidecar,
+  type EvidenceShotTier,
 } from './evidence-shot-core';
 
-export type { EvidenceShotOrigin };
+export type { EvidenceShotOrigin, EvidenceShotTier };
 
 export interface EvidenceShotOptions {
   /** Capture the full page rather than the viewport. Default: true. */
@@ -21,6 +23,14 @@ export interface EvidenceShotOptions {
    * the calling spec's file appears in that list, else `regression`.
    */
   readonly origin?: EvidenceShotOrigin;
+  /**
+   * Capture density tier. Default: `'always'`. Set to `'feature'` for
+   * intermediate-state screenshots that should only fire while the
+   * spec is on a feature branch — they auto-suppress once the spec
+   * graduates into the regression pack. See the SKILL.md "Screenshot
+   * density per spec role" section for the density policy.
+   */
+  readonly tier?: EvidenceShotTier;
 }
 
 /**
@@ -59,15 +69,15 @@ export async function evidenceShot(
   opts: EvidenceShotOptions = {},
 ): Promise<void> {
   validateEvidenceShotInputs(reqId, ac, slug);
+  const tier: EvidenceShotTier = opts.tier ?? 'always';
+  const specFile = resolveSpecFile();
+  const origin = opts.origin ?? autoDetectEvidenceShotOrigin(specFile, process.env.E2E_NEW_SPECS);
+  if (shouldSuppressEvidenceShot(tier, origin)) return;
   const fileName = composeScreenshotFilename(reqId, ac, slug);
   const dir = path.join(process.cwd(), 'compliance/evidence', reqId, 'screenshots');
   const pngPath = path.join(dir, fileName);
   const sidecarPath = `${pngPath}.meta.json`;
-
   await page.screenshot({ path: pngPath, fullPage: opts.fullPage ?? true });
-
-  const specFile = resolveSpecFile();
-  const origin = opts.origin ?? autoDetectEvidenceShotOrigin(specFile, process.env.E2E_NEW_SPECS);
   const sidecar: EvidenceShotSidecar = {
     origin,
     reqId,

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: |