@metasession.co/devaudit-cli 0.1.33 → 0.1.34

package/package.json

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

package/scripts/upload-evidence.sh

@@ -72,6 +72,11 @@ EVIDENCE_CATEGORY=""
 RELEASE_TITLE=""
 CHANGE_TYPE=""
 GATE_STATUS=""
+# Repeatable `--meta-key key=value` accumulator. Each pair gets merged
+# into the metadata JSON sent to the portal. Used by the screenshot
+# upload loop to pass `origin=feature|regression` from the per-PNG
+# sidecar JSON written by the evidenceShot helper.
+META_KEYS=()
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
@@ -91,6 +96,17 @@ while [ "$#" -gt 0 ]; do
     # ran-and-failed != never-ran. Unknown values dropped server-side.
     # DevAudit-Installer#96.
     --gate-status) GATE_STATUS="$2"; shift 2 ;;
+    # --meta-key key=value (repeatable). Merged into the metadata JSON
+    # before posting. Validates the `key=value` shape; rejects bare
+    # keys without `=`.
+    --meta-key)
+      if [[ "$2" != *=* ]]; then
+        echo "Error: --meta-key requires key=value (got: $2)"
+        exit 1
+      fi
+      META_KEYS+=("$2")
+      shift 2
+      ;;
     *) echo "Unknown option: $1"; exit 1 ;;
   esac
 done
@@ -118,24 +134,27 @@ fi
 DEVAUDIT_BASE_URL="${DEVAUDIT_BASE_URL%/}"
 
 # --- Build metadata JSON ---
-METADATA="{}"
-if [ -n "$GIT_SHA" ] || [ -n "$CI_RUN_ID" ] || [ -n "$BRANCH" ]; then
-  METADATA="{"
-  FIRST=true
-  if [ -n "$GIT_SHA" ]; then
-    METADATA="${METADATA}\"gitSha\":\"${GIT_SHA}\""
-    FIRST=false
-  fi
-  if [ -n "$CI_RUN_ID" ]; then
-    [ "$FIRST" = false ] && METADATA="${METADATA},"
-    METADATA="${METADATA}\"ciRunId\":\"${CI_RUN_ID}\""
-    FIRST=false
-  fi
-  if [ -n "$BRANCH" ]; then
-    [ "$FIRST" = false ] && METADATA="${METADATA},"
-    METADATA="${METADATA}\"branch\":\"${BRANCH}\""
-  fi
-  METADATA="${METADATA}}"
+# Assemble entries first; only emit `{ ... }` if at least one field is
+# set. Each entry is a `"key":"value"` JSON pair with the value
+# json-escaped (quotes + backslashes).
+json_escape() {
+  printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g'
+}
+META_ENTRIES=()
+[ -n "$GIT_SHA" ] && META_ENTRIES+=("\"gitSha\":\"$(json_escape "$GIT_SHA")\"")
+[ -n "$CI_RUN_ID" ] && META_ENTRIES+=("\"ciRunId\":\"$(json_escape "$CI_RUN_ID")\"")
+[ -n "$BRANCH" ] && META_ENTRIES+=("\"branch\":\"$(json_escape "$BRANCH")\"")
+for KV in "${META_KEYS[@]}"; do
+  KEY="${KV%%=*}"
+  VAL="${KV#*=}"
+  META_ENTRIES+=("\"$(json_escape "$KEY")\":\"$(json_escape "$VAL")\"")
+done
+if [ "${#META_ENTRIES[@]}" -gt 0 ]; then
+  IFS=','
+  METADATA="{${META_ENTRIES[*]}}"
+  unset IFS
+else
+  METADATA="{}"
 fi
 
 # --- Collect files ---

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

@@ -193,6 +193,20 @@ Then bucket each failure:
 
 **Then check for missed requirements.** For each numbered acceptance criterion from Phase 2, confirm at least one *passing* test covers it. An AC with no passing test — because no test was written, or because the test fails — is a missed requirement. File it.
 
+### Phase 7 — Regression-pack handoff
+
+After Phase 6 succeeds — green run, all ACs proved, defects filed for anything missing — the new spec(s) you authored move into the project's regression pack. There is **no separate graduation step**. The pack is defined as:
+
+> **Every `*.spec.ts` (and `*.spec.tsx`) under `tests/e2e/` or `e2e/`.**
+
+There is no `regression/` sub-directory, no `@regression` tag, no manifest file. Being committed and merged to `develop` *is* the graduation step. Once that happens:
+
+1. The next CI run (on this branch's PR, or on `develop` after merge) executes the new spec alongside every existing one.
+2. The evidenceShot helper sees `process.env.E2E_NEW_SPECS` (computed by CI as `git diff --diff-filter=A <merge-base>...HEAD`) and tags this branch's captures as `origin: 'feature'`.
+3. Post-merge, develop runs see an empty `E2E_NEW_SPECS` and tag every capture as `origin: 'regression'`. The original feature-branch captures stay tagged `feature` as the historical proof of original landing; subsequent develop runs accumulate `regression` captures alongside.
+
+You don't need to do anything explicit for this step — it's a property of the pipeline, not an action. Surface it in the final report so the reviewer knows the new tests are now load-bearing for every future release.
+
 ### Filing defects
 
 Use whatever tracker integration you found in Phase 1: `gh issue create`, `glab issue create`, a Jira or Linear MCP tool, `az boards work-item create`. If nothing is available, produce a markdown report with each defect formatted ready to paste.
@@ -234,7 +248,7 @@ import { evidenceShot } from './helpers/evidence';
 test('AC1: edit dialog opens with fields pre-filled', async ({ page }) => {
   await openEditDialog(page, item.id);
   await expect(dialog.locator('#name')).toHaveValue(item.name);
-  await evidenceShot(page, 'REQ-037', 'AC1-edit-dialog-prefilled');
+  await evidenceShot(page, 'REQ-037', 1, 'edit-dialog-prefilled');
   // ...rest of test
 });
 ```
@@ -242,11 +256,14 @@ test('AC1: edit dialog opens with fields pre-filled', async ({ page }) => {
 **Discipline:**
 
 - Call `evidenceShot` **immediately after** the AC-proving assertion, before navigating, closing dialogs, or any further interaction.
-- Slug as `AC<n>-<what-this-proves>` — the filename documents the claim.
+- 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.
 - 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/<slug>.png` — commit these PNGs as part of the evidence pack so reviewers can corroborate the test-plan AC mapping.
+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.
+
+The helper also writes a sidecar `<filename>.meta.json` containing the AC mapping + the screenshot's **origin** — `feature` if the spec was added on the current branch, `regression` if the spec already existed. The consumer's CI passes `origin` through to the DevAudit portal as evidence metadata so the release-detail page can render feature vs regression captures distinctly. Auto-detected from `process.env.E2E_NEW_SPECS` — no manual tagging required.
 
 The canonical helper source lives at `references/evidence.ts` in this skill.
 

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

@@ -0,0 +1,62 @@
+/**
+ * Pure helpers backing `evidenceShot`. Kept Playwright-free so they
+ * can be unit-tested without pulling `@playwright/test` into the
+ * installer repo. The thin wrapper in `evidence.ts` does the Page
+ * screenshot + fs writes around these.
+ */
+
+export type EvidenceShotOrigin = 'feature' | 'regression';
+
+export interface EvidenceShotSidecar {
+  readonly origin: EvidenceShotOrigin;
+  readonly reqId: string;
+  readonly ac: number;
+  readonly slug: string;
+  readonly specFile: string;
+  readonly capturedAt: string;
+}
+
+const REQ_ID_RE = /^REQ-[A-Z0-9-]+$/;
+const SLUG_RE = /^[a-z0-9-]+$/;
+
+export function validateEvidenceShotInputs(reqId: string, ac: number, slug: string): void {
+  if (!REQ_ID_RE.test(reqId)) {
+    throw new Error(`evidenceShot: invalid reqId "${reqId}" (must match ${REQ_ID_RE})`);
+  }
+  if (!Number.isInteger(ac) || ac <= 0) {
+    throw new Error(`evidenceShot: invalid ac "${ac}" (must be a positive integer)`);
+  }
+  if (!SLUG_RE.test(slug)) {
+    throw new Error(
+      `evidenceShot: invalid slug "${slug}" (must match ${SLUG_RE} — kebab-case, no AC prefix)`,
+    );
+  }
+}
+
+export function composeScreenshotFilename(reqId: string, ac: number, slug: string): string {
+  return `${reqId}-AC${ac}-${slug}.png`;
+}
+
+/**
+ * Auto-detect origin from `process.env.E2E_NEW_SPECS` — the consumer
+ * globalSetup writes the newline-delimited list of spec files added
+ * on the current branch (`git diff --diff-filter=A`). If the calling
+ * spec appears in that list, it's `feature`; otherwise `regression`.
+ *
+ * Empty / missing env (typical for post-merge develop runs) → every
+ * capture is `regression`, which is the correct semantic outcome.
+ */
+export function autoDetectEvidenceShotOrigin(
+  specFile: string,
+  newSpecsEnv: string | undefined,
+): EvidenceShotOrigin {
+  const list = (newSpecsEnv ?? '').trim();
+  if (list.length === 0) return 'regression';
+  const newSpecs = new Set(
+    list
+      .split(/\r?\n/)
+      .map((s) => s.trim())
+      .filter(Boolean),
+  );
+  return newSpecs.has(specFile) ? 'feature' : 'regression';
+}

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

@@ -1,40 +1,94 @@
+import fs from 'fs';
 import path from 'path';
-import { type Page } from '@playwright/test';
+import { test, type Page } from '@playwright/test';
+import {
+  autoDetectEvidenceShotOrigin,
+  composeScreenshotFilename,
+  validateEvidenceShotInputs,
+  type EvidenceShotOrigin,
+  type EvidenceShotSidecar,
+} from './evidence-shot-core';
 
-const SLUG_RE = /^[A-Za-z0-9_-]+$/;
+export type { EvidenceShotOrigin };
+
+export interface EvidenceShotOptions {
+  /** Capture the full page rather than the viewport. Default: true. */
+  readonly fullPage?: boolean;
+  /**
+   * Override the auto-detected origin. By default the helper consults
+   * `process.env.E2E_NEW_SPECS` — set by the consumer's Playwright
+   * `globalSetup` step in CI — and tags the screenshot `feature` if
+   * the calling spec's file appears in that list, else `regression`.
+   */
+  readonly origin?: EvidenceShotOrigin;
+}
 
 /**
- * Write a per-assertion screenshot into the requirement's evidence pack.
+ * Write a per-AC behavioural-proof screenshot into the requirement's
+ * evidence pack.
  *
  * Call this AT the assertion that proves the AC, before any further
  * interaction or navigation. The PNG is committed as part of the
  * evidence pack and used by reviewers to corroborate the test-plan
  * AC mapping.
  *
- * Output path: `compliance/evidence/<reqId>/screenshots/<slug>.png`
+ * Filename: `REQ-XXX-AC<n>-<slug>.png`
+ * Output path: `compliance/evidence/<reqId>/screenshots/<filename>`
+ *
+ * The helper also writes a sidecar `<filename>.meta.json` containing
+ * `{ origin, reqId, ac, slug, specFile, capturedAt }`. The consumer's
+ * CI upload step reads the sidecar and passes `origin` as evidence
+ * metadata to the portal so the release-detail page can tell feature
+ * captures apart from regression-pack reruns.
  *
  * @example
  *   await expect(dialog.locator('#name')).toHaveValue(item.name);
- *   await evidenceShot(page, 'REQ-037', 'AC1-edit-dialog-prefilled');
+ *   await evidenceShot(page, 'REQ-037', 1, 'edit-dialog-prefilled');
+ *
+ * @param page Playwright Page
+ * @param reqId `REQ-` prefixed requirement id (e.g. `REQ-037`)
+ * @param ac AC number — mandatory; every screenshot proves one AC
+ * @param slug kebab-case descriptive slug (no `AC<n>-` prefix; the
+ *             helper composes it from `ac`)
  */
 export async function evidenceShot(
   page: Page,
   reqId: string,
+  ac: number,
   slug: string,
-  opts: { fullPage?: boolean } = {},
+  opts: EvidenceShotOptions = {},
 ): Promise<void> {
-  if (!SLUG_RE.test(reqId)) {
-    throw new Error(`evidenceShot: invalid reqId "${reqId}" (must match ${SLUG_RE})`);
-  }
-  if (!SLUG_RE.test(slug)) {
-    throw new Error(`evidenceShot: invalid slug "${slug}" (must match ${SLUG_RE})`);
-  }
-  const out = path.join(
-    process.cwd(),
-    'compliance/evidence',
+  validateEvidenceShotInputs(reqId, ac, slug);
+  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,
-    'screenshots',
-    `${slug}.png`,
-  );
-  await page.screenshot({ path: out, fullPage: opts.fullPage ?? true });
+    ac,
+    slug,
+    specFile,
+    capturedAt: new Date().toISOString(),
+  };
+  await fs.promises.writeFile(sidecarPath, `${JSON.stringify(sidecar, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * Test-info gives us the absolute spec path. Make it repo-relative so
+ * it survives serialisation into the sidecar JSON + the CI's git diff
+ * comparison list.
+ */
+function resolveSpecFile(): string {
+  try {
+    const info = test.info();
+    return path.relative(process.cwd(), info.file);
+  } catch {
+    return 'unknown';
+  }
 }

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

@@ -42,6 +42,12 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          # Full history so the "new specs on this branch" calculation
+          # (E2E_NEW_SPECS, below) can do a real diff against the merge
+          # base — Playwright's evidenceShot helper reads that env var to
+          # tag each captured screenshot as feature vs regression.
+          fetch-depth: 0
 
       # ── Cached installs (skip if already present on self-hosted runner) ──
 
@@ -142,6 +148,32 @@ jobs:
       - name: Wait for dev server
         run: npx wait-on http://localhost:3000 --timeout 120000
 
+      # Compute the set of e2e spec files added on this branch (relative
+      # to the merge base). The evidenceShot helper in the consumer's
+      # tests reads E2E_NEW_SPECS at capture time and tags each screenshot
+      # `origin=feature` when its spec appears in the list, else
+      # `origin=regression`. On main / develop (post-merge) the diff is
+      # empty and every capture is `regression`, which is the intended
+      # behaviour. Newline-delimited; relative paths.
+      - name: Compute new-spec list for E2E origin tagging
+        run: |
+          BASE_REF="${{ github.base_ref || github.event.repository.default_branch || 'main' }}"
+          BASE_SHA=$(git merge-base "origin/${BASE_REF}" HEAD 2>/dev/null || git rev-parse HEAD)
+          NEW_SPECS=$(git diff --name-only --diff-filter=A "${BASE_SHA}...HEAD" \
+            -- 'tests/e2e/**/*.spec.ts' 'tests/e2e/**/*.spec.tsx' \
+               'e2e/**/*.spec.ts' 'e2e/**/*.spec.tsx' 2>/dev/null || true)
+          {
+            echo "E2E_NEW_SPECS<<EOF"
+            echo "$NEW_SPECS"
+            echo "EOF"
+          } >> "$GITHUB_ENV"
+          if [ -n "$NEW_SPECS" ]; then
+            echo "New e2e specs on this branch (origin=feature for captures):"
+            echo "$NEW_SPECS" | sed 's/^/  /'
+          else
+            echo "No new e2e specs detected — all captures will tag origin=regression."
+          fi
+
 {{E2E_TEST_STEP}}
 {{E2E_AUTHENTICATED_STEP}}
       # ── Gate 5: Build ──
@@ -191,6 +223,7 @@ jobs:
             coverage/coverage-summary.json
             gate-outcomes.json
             compliance/evidence/*/screenshots/*.png
+            compliance/evidence/*/screenshots/*.png.meta.json
           retention-days: 90
 
   # ──────────────────────────────────────────────
@@ -486,16 +519,39 @@ jobs:
               [ -n "$REQ_TITLE" ] && REQ_META+=(--release-title "$REQ_TITLE")
               [ -n "$REQ_CT" ] && REQ_META+=(--change-type "$REQ_CT")
               for PNG in "${SHOTS[@]}"; do
-                # The folder is the (SRS) requirement id, the basename is the AC
-                # slug (ACn-…). Upload as <srs-req>-<slug>.png so the reviewer can
-                # see which requirement/AC each image proves and names don't collide.
-                SRS_REQ="$(basename "$(dirname "$(dirname "$PNG")")")"
-                NAMED="${SHOT_TMP}/${SRS_REQ}-$(basename "$PNG")"
+                # The basename is the canonical evidenceShot filename
+                # `REQ-XXX-AC<n>-<slug>.png`. The portal validates this
+                # shape on upload — anything else is rejected with 400.
+                BASE="$(basename "$PNG")"
+                NAMED="${SHOT_TMP}/${BASE}"
                 cp "$PNG" "$NAMED" 2>/dev/null || continue
+
+                # Read the sidecar JSON (`<png>.meta.json`) written by the
+                # evidenceShot helper. Pull `origin` out so the portal
+                # render can tell feature vs regression captures apart.
+                # Sidecar missing → upload with no origin metadata; the
+                # portal renders those as "unknown" until consumers re-
+                # onboard via `devaudit update`.
+                ORIGIN_META=()
+                if [ -f "${PNG}.meta.json" ]; then
+                  ORIGIN=$(python3 -c "
+import json, sys
+try:
+  with open('${PNG}.meta.json') as f:
+    print(json.load(f).get('origin', ''))
+except Exception:
+  pass
+" 2>/dev/null || true)
+                  if [ "$ORIGIN" = "feature" ] || [ "$ORIGIN" = "regression" ]; then
+                    ORIGIN_META+=(--meta-key "origin=${ORIGIN}")
+                  fi
+                fi
+
                 bash scripts/upload-evidence.sh \
                   {{PROJECT_SLUG}} "$REQ" screenshot "$NAMED" \
                   --category test_report ${FLAGS} --release "$REQ" \
                   "${REQ_META[@]}" \
+                  "${ORIGIN_META[@]}" \
                   || echo "::warning::evidence screenshot upload failed: ${PNG} -> ${REQ}"
               done
             done