@metasession.co/devaudit-cli 0.1.39 → 0.1.40

package/package.json

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

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,