@metasession.co/devaudit-cli 0.1.49 → 0.1.53

package/package.json

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

package/sdlc/files/_common/1-plan-requirement.md

@@ -131,6 +131,8 @@ Create `compliance/evidence/REQ-XXX/implementation-plan.md`:
 - Files to create/modify
 - Architecture decisions
 - Risks and dependencies
+- **Surface inventory completeness** (MEDIUM/HIGH risk) — every user-touchable surface listed in Section 2's surface-inventory table is either `In scope`, `Already works`, or explicitly `Out of scope (waived)` with a follow-up issue. No surface is silently absent. _(devaudit#152)_
+- **AC form** — the test-scope ACs (drafted in Step 7) can each be phrased in Given/When/Then against the surfaces in scope. If any AC reduces to _"the schema accepts X"_ or _"the resolver returns Y"_, the plan is incomplete — return to Section 2 and expand the surface inventory until every AC has a UI surface that delivers it. _(devaudit#152)_
 
 **Do NOT proceed** until the developer explicitly approves the plan. If the developer requests changes, update `implementation-plan.md` and re-present. For HIGH risk, this review is especially important — it's cheaper to change the plan than to refactor the code.
 
@@ -177,9 +179,22 @@ Standard gates apply. No additional testing beyond universal exit criteria.
 - CI independent verification: all PR checks pass
 - Human code review via PR
 
+### How to write acceptance criteria (devaudit#152)
+
+Phrase each AC as a **user-observable journey**, not a technical-layer assertion. Use the Given/When/Then form:
+
+> **Given** [pre-state + which UI surface the user is on], **When** [named user action with a named control], **Then** [observable change in a named UI surface].
+
+If you can't phrase an AC in Given/When/Then because no UI surface delivers the change to a user, the scope is incomplete — return to the implementation plan's surface inventory (Section 2). LOW risk REQs may keep ACs shorter when the change is genuinely surface-free (refactor / dep bump / infra-only), but the journey form is still preferred when a user surface exists.
+
+Examples:
+
+- ✅ "Given the dependency is updated, When CI runs the universal gates, Then 0 high/critical findings."
+- ❌ "Schema accepts optional `inventoryId` field" — internal mechanic, belongs in `test-plan.md` (this matters even for LOW when the change is user-facing).
+
 ## Acceptance Criteria
 
-- [x] [Criterion 1 — what "done" looks like]
+- [x] [Criterion 1 — what "done" looks like, phrased Given/When/Then where applicable]
 - [x] [Criterion 2]
 EOF
 ```
@@ -218,10 +233,24 @@ How we confirm this meets the business requirement:
 - [e.g., "Verify public page displays new content correctly"]
 - [e.g., "Confirm edits are visible to users within expected time"]
 
+### How to write acceptance criteria (devaudit#152)
+
+Phrase each AC as a **user-observable journey**, not a technical-layer assertion. Use the Given/When/Then form:
+
+> **Given** [pre-state + which UI surface the user is on], **When** [named user action with a named control], **Then** [observable change in a named UI surface] _(plus any audit / downstream UI changes)_.
+
+If you can't phrase an AC in Given/When/Then because no UI surface delivers the change to a user, the scope is incomplete — return to the implementation plan's surface inventory (Section 2).
+
+Examples:
+
+- ✅ "Given Poundo has Ogbono linked, When a staff member opens `/dashboard/orders/express/create-order`, picks Ogbono from the Soup group, and marks the order Complete, Then `/dashboard/inventory/{ogbono}` shows stock decreased by 1 and a new Sale movement row tied to the order ID."
+- ❌ "Schema accepts optional `inventoryId` field (persistence round-trip)" — unit-test contract, belongs in `test-plan.md`, not here.
+- ❌ "Resolver maps selected pairs to inventory link" — internal mechanic, not user value.
+
 ## Acceptance Criteria
 
-- [ ] [Criterion 1]
-- [ ] [Criterion 2]
+- [ ] [Criterion 1 — Given/When/Then]
+- [ ] [Criterion 2 — Given/When/Then]
 - [ ] All additional testing items above pass
 EOF
 ```
@@ -274,10 +303,24 @@ How we confirm this meets the business requirement:
 - Elevated review required for: [security-sensitive files]
 - Regeneration protocol: [will any components be regenerated?]
 
+### How to write acceptance criteria (devaudit#152)
+
+Phrase each AC as a **user-observable journey**, not a technical-layer assertion. Use the Given/When/Then form:
+
+> **Given** [pre-state + which UI surface the user is on], **When** [named user action with a named control], **Then** [observable change in a named UI surface] _(plus any audit / downstream UI changes)_.
+
+HIGH risk especially: every AC must pin to a named UI surface from the implementation plan's surface inventory (Section 2). If you can't phrase an AC in Given/When/Then because no UI surface delivers the change to a user, the scope is incomplete — expand the surface inventory before approving the plan. This is the gap that produced REQ-030 on a consumer project (feature shipped through every gate green, but no order-creation surface let a user select a customisation at order time).
+
+Examples:
+
+- ✅ "Given an admin has linked Poundo to Ogbono in `/dashboard/inventory/links`, When a staff member opens `/dashboard/orders/express/create-order`, picks Ogbono from the Soup group, and marks the order Complete, Then `/dashboard/inventory/{ogbono}` shows stock decreased by 1, a new Sale movement row appears tied to the order ID, and the activity timeline records the link-driven deduction."
+- ❌ "Schema accepts optional `inventoryId` field (persistence round-trip)" — unit-test contract, belongs in `test-plan.md`, not here.
+- ❌ "Resolver maps selected pairs to inventory link" — internal mechanic, not user value.
+
 ## Acceptance Criteria
 
-- [ ] [Criterion 1]
-- [ ] [Criterion 2]
+- [ ] [Criterion 1 — Given/When/Then against a named UI surface]
+- [ ] [Criterion 2 — Given/When/Then against a named UI surface]
 - [ ] All security testing items pass
 - [ ] All validation items confirmed
 - [ ] Independent review completed (if required)

package/sdlc/files/_common/2-implement-and-test.md

@@ -126,7 +126,9 @@ Write or update E2E tests **after** implementation. E2E tests need working UI/AP
 
 > **Skill available:** invoke the **`e2e-test-engineer`** skill for this step (at `.claude/skills/e2e-test-engineer/SKILL.md`). It derives scenarios from the requirement's acceptance criteria, reconciles with the existing test pack (flags obsoletes — but never deletes without confirmation), runs the suite, and files defects for failures or missed ACs. Framework-agnostic (Playwright, Cypress, pytest-playwright, etc.) and tracker-agnostic (GitHub, Linear, Jira, etc.). For projects with no e2e suite yet, the skill also covers bootstrapping one. See [`sdlc/SKILLS.md`](../sdlc/SKILLS.md) for the full list of available skills.
 
-> **Run authenticated flows in CI.** Tests that need a logged-in session (admin forms, role-gated flows) belong in their own Playwright project that depends on `auth-setup`. Register that project name in `sdlc-config.json` `e2e_projects` and set `e2e_seed_command` / `e2e_env` so CI seeds fixtures and runs it as a **report-only** gate (continue-on-error — it surfaces failures as evidence without blocking the merge until proven stable). Prove each AC with an `evidenceShot(page, 'REQ-XXX', 'ACn-…')` so the PNG lands in `compliance/evidence/REQ-XXX/screenshots/`. This is what lets Stage 3 Step 10 reduce manual UAT to a light smoke instead of a full re-click.
+> **Run authenticated flows in CI.** Tests that need a logged-in session (admin forms, role-gated flows) belong in their own Playwright project that depends on `auth-setup`. Register that project name in `sdlc-config.json` `e2e_projects` and set `e2e_seed_command` / `e2e_env` so CI seeds fixtures and runs it as a **report-only** gate (continue-on-error — it surfaces failures as evidence without blocking the merge until proven stable). Prove each UI-driven AC with an `evidenceShot(page, 'REQ-XXX', acN, 'slug')` so the PNG lands in `compliance/evidence/REQ-XXX/screenshots/`. This is what lets Stage 3 Step 10 reduce manual UAT to a light smoke instead of a full re-click.
+
+> **Transport-layer specs have no page** (devaudit#127). Specs that exercise the system at the transport boundary — Node `fetch` against webhooks, `MongoClient` queries, `socket.io-client` assertions — cannot call `evidenceShot`. Their evidence form is the per-spec row in `test-execution-summary.md` describing the asserted behaviour in operator terms. The portal's release-detail "screenshots" panel will show zero entries for purely-transport REQs; that's correct. Reviewers cross-reference `test-execution-summary.md` instead. See `e2e-test-engineer/SKILL.md` § *Specs with no page object*.
 
 **4a. Review the test plan for E2E items:**
 ```bash

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

@@ -135,6 +135,24 @@ cat > compliance/evidence/REQ-XXX/test-execution-summary.md << 'EOF'
 **Git SHA:** [short SHA]
 **CI Run:** [run ID or "local"]
 
+## Test design (devaudit#50)
+
+Records the design-time decisions before listing run results — what was tested, what was deliberately deferred, who/what decided. Auditors (and future maintainers) can see the scope decision was *made*, not implicit.
+
+**Layers planned:** [unit | integration | e2e | visual | manual — pick the ones that apply to this REQ]
+
+**Layers covered:** [same list, marked ✓ for shipped layers / `deferred` for skipped ones]
+
+**Deferrals (if any):**
+
+- [e.g. "e2e N/A — schema-only change, no UI surface reads the new fields yet; deferred to REQ-NNN when the admin form lands"]
+- [e.g. "visual regression N/A — backend service change, no UI affected"]
+- A deferral without a stated rationale is a gap, not a deferral. Either name *why* it was skipped or do the work.
+
+**Skill invocation:** [`e2e-test-engineer` invoked on turn N during Phase 2 — verifiable from the chat transcript] / [`manual scope decision` — operator chose layers directly because <reason>]
+
+**Surface inventory (MEDIUM/HIGH risk REQs):** see `implementation-plan.md` Section 2. Each `In scope` surface here should map to at least one passing test below; each `Already works` surface should map to a regression-pack spec; each `Out of scope (waived)` surface should have a follow-up issue referenced.
+
 ## Gate Results
 
 | Gate | Result | Details |

package/sdlc/files/_common/Implementation_Plan_TEMPLATE.md

@@ -35,11 +35,29 @@ Each section below maps to one (or more) of these clauses. Don't delete sections
 > _Closes ISO 29119 §3.4 — test plan_
 
 - **Goal:** REPLACE — one sentence describing what this REQ delivers, no jargon.
+
+### How to write acceptance criteria (devaudit#152)
+
+Phrase each AC as a **user-observable journey**, not a technical-layer assertion. Use the Given/When/Then form:
+
+> **Given** [the relevant pre-state, including which UI surface the user is on],
+> **When** [the user takes a specific, named action with a specific, named control],
+> **Then** [the user can observe a specific, named change in a specific, named UI surface]
+> _(And any additional observable changes — audit rows, downstream UI updates, etc.)_
+
+Concrete examples:
+
+- ✅ "Given Poundo has Ogbono linked, When a staff member opens `/dashboard/orders/express/create-order` and picks Ogbono from the Soup group and marks the order Complete, Then `/dashboard/inventory/{ogbono}` shows stock decreased by 1 and one new Sale movement row tied to the order ID."
+- ❌ "Schema accepts optional `inventoryId` field (persistence round-trip)" — this is a unit-test contract, not a user-observable AC. It belongs in `test-plan.md`, not here.
+- ❌ "Resolver maps selected pairs to inventory link" — same problem. Internal mechanics, not user value.
+
+If you can't phrase an AC in Given/When/Then because no UI surface delivers the change to a user, the scope is incomplete — expand the **Surface inventory** (Section 2) until every AC has a UI surface that delivers it.
+
 - **Acceptance criteria:**
 
 | AC  | Description                                | SRS item it traces to                                                                   |
 | --- | ------------------------------------------ | --------------------------------------------------------------------------------------- |
-| AC1 | REPLACE — one-line behavioural description | REQ-AREA-NNN (existing) / REQ-AREA-NNN (new — propose stub) / `@srs-deferred: <reason>` |
+| AC1 | REPLACE — one-line Given/When/Then journey | REQ-AREA-NNN (existing) / REQ-AREA-NNN (new — propose stub) / `@srs-deferred: <reason>` |
 | AC2 | REPLACE                                    | REPLACE                                                                                 |
 | …   |                                            |                                                                                         |
 
@@ -50,6 +68,24 @@ Each section below maps to one (or more) of these clauses. Don't delete sections
 - **In scope:** REPLACE — list every file / module / surface the change touches.
 - **Out of scope:** REPLACE — adjacent areas the change deliberately leaves alone.
 
+### Surface inventory (MEDIUM/HIGH risk — required) (devaudit#152)
+
+List every UI, API, background job, and report **that a real user touches** in the journey this REQ enables. For each surface, mark one of:
+
+- **In scope** — this REQ adds or modifies it
+- **Already works** — existing code already handles it correctly (link the file / route as evidence)
+- **Out of scope (waived)** — explicitly deferred, with one-sentence justification and a follow-up issue link
+
+| Surface                 | URL / file                                            | Status                                                                       |
+| ----------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------- |
+| [e.g. Customer cart]    | `/menu` modal — `components/features/menu/…`          | In scope                                                                     |
+| [e.g. Staff POS]        | `/dashboard/orders/express/…`                         | Out of scope (waived) — front-of-house flow not used yet, follow-up #NN      |
+| [e.g. Admin Edit Order] | `/dashboard/orders/[id]/edit` — `app/admin/orders/…`  | Already works — existing customisation picker handles the new fields as-is   |
+
+**Rule of thumb:** if the AC list reads _"the schema accepts X"_ or _"the resolver returns Y"_ but never _"the user can do Z in the UI and see the result in the UI"_, the surface inventory is incomplete and the plan is not ready for approval. The matching test-scope ACs in Step 7 must each pin to a surface listed here.
+
+LOW risk REQs may skip the table when the change is genuinely surface-free (refactor, dependency bump, infra-only). State `Surface inventory: N/A — <reason>` instead.
+
 ## 3. Architecture decisions
 
 > _Populated by the [`adr-author` skill](../skills/adr-author/SKILL.md) at Stage 1 plan APPROVAL._

package/sdlc/files/_common/Test_Architecture.md

@@ -39,7 +39,7 @@ These standards apply to all Metasession products, client engagements, and inter
 ### Speed over Exhaustiveness
 - Fast feedback prioritized (unit tests < 30 seconds)
 - Parallelization and sharding for E2E suites
-- Strategic test selection based on code changes
+- Strategic test selection based on code changes — first concrete implementation is the three-tier E2E gating model (smoke / critical / regression), see Test_Strategy.md § *E2E gating model* (v0.1.53+)
 - Regression suites optimized for execution time
 
 ### Traceability

package/sdlc/files/_common/Test_Policy.md

@@ -150,6 +150,18 @@ Testing effort is prioritized by risk level, determined at planning time:
 
 AI involvement in Medium or High categories raises risk by one level. The Test Strategy defines specific testing depth requirements per level.
 
+### E2E gate enforcement (v0.1.53+)
+
+The MoSCoW prioritisation of acceptance criteria maps onto three E2E gates, each enforced at a different point in the workflow:
+
+- **Must-tier ACs in the smoke subset** must pass on every push to the integration branch. Blocking — a red smoke gate stops the integration hop.
+- **Must-tier ACs in the critical subset** must pass on every PR to the release branch. Blocking — a red critical gate stops the release.
+- **Should/Could-tier ACs (full regression)** must pass on the next post-merge run to the release branch OR a hotfix issue is auto-filed. Not pre-merge blocking — the safety net is post-hoc triage by the operator within working hours.
+
+Operator override on a hotfix issue (accept-with-rationale) is logged on the issue itself + carried in the next release's `test-execution-summary.md` design record (devaudit#50). The framework does not permit silently shipping a failing test — every red regression spec ends as either fixed, reverted, or accepted-with-recorded-rationale.
+
+See Test_Strategy.md § *System Testing (E2E)* — *E2E gating model* for the tier definitions + cost philosophy.
+
 ---
 
 ## Roles & Responsibilities

package/sdlc/files/_common/Test_Strategy.md

@@ -38,6 +38,24 @@ Validates interactions between system components — API contracts, service inte
 
 End-to-end validation of complete user workflows from UI to database. Primary responsibility of the QA team. Automated using BDD frameworks that map acceptance criteria to executable specifications. Covers 100% of critical user paths.
 
+#### E2E gating model — three tiers (devaudit#152 follow-up, v0.1.53)
+
+Full E2E regression on every PR is expensive — a 30+ minute wait per release-PR blocks velocity for diminishing marginal safety once smoke covers the headline flows. The framework's gating model maps the existing MoSCoW prioritisation onto three tiers, each gated at a different point in the workflow:
+
+| Tier | Location | When it runs | Wall-clock target | Audit role |
+|---|---|---|---|---|
+| **smoke** | `e2e/smoke/*.spec.ts` | every push to `$INTEGRATION_BRANCH` (via `ci.yml`) | ~3–5 min | fast feedback on every change |
+| **critical** | `e2e/smoke/` + `e2e/critical/*.spec.ts` | PR-to-`$RELEASE_BRANCH` (via `e2e-regression.yml`) | ~10–15 min | release-readiness Must gate |
+| **regression** | all `e2e/**/*.spec.ts` | nightly + push-to-`$RELEASE_BRANCH` + `workflow_dispatch` | ~35 min (or your project's full pack) | full audit trail + drift catch |
+
+The mapping to MoSCoW: **Must-priority SRS items live in `e2e/smoke/` (fast feedback) and `e2e/critical/` (release gate); Should/Could items live in `e2e/` and are covered by the regression tier.** The classifier is the developer authoring the spec — see `skills/e2e-test-engineer/SKILL.md` Phase 3 for the decision tree.
+
+**Cost philosophy.** Smoke protects every push from breaking the headline flow. Critical protects every release from a Must-tier regression. Full regression protects the audit trail + catches drift overnight. We accept that a Should/Could-tier regression *can* slip past the PR gate; we catch it on the next post-merge run + auto-file a hotfix issue. The framework prefers this over a 35-min wait on every release because operator velocity matters and the safety net stays intact.
+
+**Post-merge safety net.** Every push to `$RELEASE_BRANCH` re-runs the full regression. On failure, `e2e-regression.yml` auto-files a `bug, priority:high` issue tagging the merge commit + the failing specs. The operator triages within working hours — hotfix forward, revert the commit, or accept-with-rationale if the failure is environmental. No automated revert (false positives + flakes + UAT-data drift are real classes; an operator triages each individually).
+
+**Reference workflow.** A copy-pasteable `e2e-regression.yml` shape lives at `skills/e2e-test-engineer/references/e2e-regression-3-tier.yml`. Adoption is opt-in per consumer (the framework doesn't currently sync this workflow; consumers own their own `e2e-regression.yml`).
+
 ### Acceptance Testing
 
 Validates that requirements and acceptance criteria are met from a business perspective. Conducted in staging environments mirroring production. Requires sign-off from Product Managers. May include formal UAT with stakeholders for regulated features.

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

@@ -19,6 +19,8 @@ Maintain or bootstrap a project's e2e and visual regression test suite. Given an
 - Unit, component, or API-only tests.
 - Performance, load, or accessibility audits, unless the project's e2e pack already includes them — in which case follow its lead.
 
+**Transport-layer specs that live in `e2e/`** (Node `fetch` against webhooks, `MongoClient` queries, `socket.io-client` assertions) ARE in scope — they exercise the deployed system end-to-end, just at the transport boundary rather than the UI. Their evidence form is `test-execution-summary.md`, not `evidenceShot` (see *Specs with no page object* below). The "API-only tests" exclusion above means **unit-level** API contract tests that exercise a route handler in isolation, not transport-boundary integration tests against the running system.
+
 ## The workflow
 
 Six phases. Don't skip them and don't reorder — each one feeds the next. Communicate progress as you go; long silent phases feel like the skill has stalled.
@@ -129,6 +131,26 @@ Resist padding. A new endpoint doesn't need a test that re-verifies login if log
 
 For each scenario, write a one-line description. Present the full grouped list to the user before writing any code: *"Here's the coverage I'd propose — anything to add or drop?"*
 
+#### Classify each spec into a tier (devaudit#152 follow-up, v0.1.53)
+
+When designing each scenario, also pick the tier it'll live in. Three tiers map to MoSCoW priority + gating point (see `Test_Strategy.md` § *E2E gating model*):
+
+| Tier | File location | Picks this when… |
+|---|---|---|
+| **smoke** | `e2e/smoke/*.spec.ts` | Cross-cutting sanity that proves the app is up: login, basic nav, one canonical CRUD per main domain. Runs on every push to the integration branch. Keep small — total smoke wall-clock target is ~3–5 min. |
+| **critical** | `e2e/critical/*.spec.ts` | Must-priority SRS item that breaks a headline flow if it regresses. Examples: payment authorisation, order completion, admin permission editing, RBAC enforcement on financial surfaces. Runs on PR-to-release-branch. Total critical wall-clock target ~10–15 min (includes smoke). |
+| **regression** | `e2e/<area>/*.spec.ts` | Should/Could-priority SRS item, edge cases, less-load-bearing flows. Runs nightly + post-merge + dispatch. Total full pack can be 30+ min; that's the point of the tier. |
+
+Decision tree, applied per scenario:
+
+1. **Does the spec prove a Must-priority SRS AC (or a baseline "app is up" sanity check)?** → smoke or critical.
+2. **Within Must: would a regression here break a headline business flow visible to a paying customer or stop a release from shipping?** → critical. Otherwise → smoke.
+3. **Should/Could priority, edge case, advanced flow?** → regression (file under `e2e/<area>/`, not under `e2e/smoke/` or `e2e/critical/`).
+
+When you can't decide between critical and regression, default to **regression** — promoting a spec from regression → critical later is cheap (move the file); demoting in the other direction is rarely needed but equally cheap. The cost of putting a Should spec in critical is everyone waiting longer on every PR-to-main for a low-value signal.
+
+Record the tier choice in the eventual `test-execution-summary.md` § *Test design* (devaudit#50) — Layers covered should name which tier each new spec landed in. Reviewers verify the tier choice is defensible during the WAIT CHECKPOINT.
+
 ### Phase 4 — Reconcile with existing tests
 
 For the area touched by the change, look at what's already there.
@@ -303,6 +325,15 @@ Wrap up with a summary the user can drop into the PR or ticket:
 - Defects filed — count, with links.
 - Missed requirements — count, with links.
 
+**Then feed the test-design record (devaudit#50).** The Stage 3 `test-execution-summary.md` (generated per `3-compile-evidence.md` Step 1a) carries a `## Test design` section at the top. Before Stage 3 finalises the file, populate that section with the design-time decisions this skill made, so the SDLC has a recorded trace that scope was *decided*, not implicit:
+
+- **Layers planned** — which of `unit | integration | e2e | visual | manual` applied to this REQ
+- **Layers covered** — same list with ✓ or `deferred`
+- **Deferrals** — explicit one-line rationale per deferred layer (`e2e N/A — schema-only, no UI yet` rather than silent absence)
+- **Skill invocation** — _"`e2e-test-engineer` invoked on turn N during Phase 2"_, with a turn pointer the reviewer can verify against the chat transcript
+
+If you authored or modified `e2e/**/*.spec.ts` directly without invoking this skill, that's a delegation gap — the `sdlc-implementer` Phase 2 audit (devaudit#132) will catch it before Phase 3. The honest record is: the skill ran (or didn't), the layers were chosen for stated reasons, and the test-execution-summary attribution points back at the chat turn where the decision happened.
+
 ---
 
 ## Evidence vs failure forensics
@@ -373,6 +404,27 @@ When to deviate:
 - **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.
 
+### Specs with no page object — transport-layer evidence (devaudit#127)
+
+`evidenceShot` requires a Playwright `page` object. Specs that exercise behaviour at the transport layer — Node `fetch` against HTTP / webhook endpoints, `socket.io-client` connections, direct `MongoClient` queries, gRPC clients — have no `page` and **cannot call `evidenceShot`**. Examples from the wawagardenbar-app regression pack:
+
+- `e2e/payments/webhook-signature-rejection.spec.ts` — HMAC-SHA512 verification via Node `fetch`
+- `e2e/realtime/order-status-broadcast.spec.ts` — `socket.io-client` event assertion
+- `e2e/admin/menu-item-delete.spec.ts` — direct `MongoClient` + service-layer call
+
+These specs are still E2E (they exercise the deployed system end-to-end at the transport boundary), they belong in `e2e/`, and they run alongside UI specs. **Their evidence form is the per-spec entry in `test-execution-summary.md`** — the table of spec → pass/fail → asserted behaviour (signature rejected with HTTP 401, idempotent replay suppressed, broadcast received within Nms, soft-delete cascaded) is the load-bearing proof. The screenshot check is **N/A** for them; the release-completeness "behavioural proof" check is satisfied by the test-execution-summary upload alone.
+
+Discipline for transport specs:
+
+- Name the asserted behaviour in the test title using the same `[REQ-XXX][ACn]` bracket convention UI specs use. Reviewers grep on that.
+- The `test-execution-summary.md` table row should describe what the spec verified in operator-facing terms ("signature mismatch returns 401; payment row unchanged"), not in TypeScript-spec terms ("`expect(response.status).toBe(401)`").
+- If a transport spec *can* be paired with a thin UI shim that screenshots the user-visible outcome (e.g. an admin dashboard surface that shows the rejected payment as "Failed — signature mismatch"), pair them — that buys back the screenshot evidence at the surface level. Otherwise: transport spec stands alone.
+- The portal's release-detail "screenshots" panel will show zero entries for purely-transport REQs; that's correct. Reviewers cross-reference `test-execution-summary.md` instead.
+
+This is **observation**, not gate-relaxation — these specs satisfy the SDLC evidence requirement; the screenshot mechanism doesn't apply.
+
+A `evidenceTrace(reqId, ac, slug, payload)` helper that writes a JSON sidecar (request/response/ledger shape) was considered as a Phase B; deferred until the portal grows a non-PNG evidence type. Today the test-execution-summary already carries the equivalent information at the table level.
+
 ---
 
 ## Principles

package/sdlc/files/_common/skills/e2e-test-engineer/references/e2e-regression-3-tier.yml

@@ -0,0 +1,178 @@
+# Reference: three-tier E2E gating workflow (devaudit#152 follow-up, v0.1.53)
+#
+# Copy this into your consumer-owned .github/workflows/e2e-regression.yml
+# to adopt the 3-tier model: smoke (every develop push, fast) / critical
+# (PR-to-main, ~10-15 min target) / regression (nightly + push-to-main +
+# dispatch, full audit trail with auto-issue on failure).
+#
+# The framework does NOT sync this file automatically — your consumer
+# owns its e2e-regression.yml. Apply the patterns below to your own
+# file; keep any consumer-specific env / matrix / runner customisations.
+#
+# Tier definitions:
+#   - smoke   — runs on develop push via ci.yml (no change here)
+#   - critical — Playwright project that selects e2e/smoke/ + e2e/critical/
+#   - regression — Playwright project that selects all e2e/**/*.spec.ts
+#
+# playwright.config.ts must define the `critical` project for this to
+# fire; if it doesn't, the gate falls back to the existing `smoke`
+# project so PR-to-main stays green during migration.
+
+name: E2E Regression
+
+on:
+  pull_request:
+    branches: [main] # critical-tier gate before merge
+  push:
+    branches: [main] # full regression after merge; auto-issues on failure
+  schedule:
+    - cron: '0 2 * * *' # nightly full regression
+  workflow_dispatch:
+    inputs:
+      specs:
+        description: 'Optional: space-separated spec paths or --grep pattern for a scoped run. Empty = full regression.'
+        required: false
+
+permissions:
+  contents: read
+  issues: write # post-merge auto-issue on regression failure
+
+concurrency:
+  group: e2e-regression-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  e2e:
+    name: E2E Regression Tests
+    runs-on: ubuntu-latest # adapt to your runner; e.g. self-hosted, ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # for E2E_NEW_SPECS computation
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22' # match your project
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      # Decide which Playwright project to run based on the trigger.
+      # PR-to-main uses critical with smoke fall-back; push-to-main and
+      # schedule run the full regression project; workflow_dispatch
+      # accepts an optional spec filter.
+      - name: Determine E2E project + spec selector
+        id: select
+        run: |
+          set -euo pipefail
+          EVENT="${{ github.event_name }}"
+          case "$EVENT" in
+            pull_request)
+              if grep -qE "name:\s*['\"]critical['\"]" playwright.config.ts 2>/dev/null; then
+                echo "project=critical" >> "$GITHUB_OUTPUT"
+                echo "Using critical-tier project (smoke + e2e/critical/)"
+              else
+                echo "project=smoke" >> "$GITHUB_OUTPUT"
+                echo "::warning::No 'critical' Playwright project defined; falling back to smoke. See e2e-test-engineer/references/e2e-regression-3-tier.yml + the Phase 3 tier-classification guide."
+              fi
+              echo "specs=" >> "$GITHUB_OUTPUT"
+              ;;
+            push|schedule)
+              echo "project=regression" >> "$GITHUB_OUTPUT"
+              echo "specs=" >> "$GITHUB_OUTPUT"
+              echo "Running full regression project"
+              ;;
+            workflow_dispatch)
+              echo "project=regression" >> "$GITHUB_OUTPUT"
+              echo "specs=${{ github.event.inputs.specs }}" >> "$GITHUB_OUTPUT"
+              if [ -n "${{ github.event.inputs.specs }}" ]; then
+                echo "Scoped dispatch: ${{ github.event.inputs.specs }}"
+              fi
+              ;;
+          esac
+
+      - name: Run E2E suite
+        id: run
+        env:
+          PLAYWRIGHT_HTML_REPORTER_OPEN: never
+          PLAYWRIGHT_JSON_OUTPUT_NAME: e2e-regression-results.json
+          # Add your e2e_env values here as needed (DEVAUDIT_BASE_URL etc.)
+        run: |
+          set -euo pipefail
+          PROJECT="${{ steps.select.outputs.project }}"
+          SPECS="${{ steps.select.outputs.specs }}"
+          if [ -n "$SPECS" ]; then
+            npx playwright test --project="$PROJECT" --reporter=json,html $SPECS
+          else
+            npx playwright test --project="$PROJECT" --reporter=json,html
+          fi
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: e2e-regression-report
+          path: |
+            e2e-regression-results.json
+            playwright-report/
+            test-results/
+
+      # ─────────────────────────────────────────────────────────────
+      # Post-merge auto-issue on regression failure (push:branches:[main])
+      #
+      # Catches regressions that slipped past the critical-tier PR gate.
+      # Opens a high-priority issue tagging the merge commit + the
+      # failing specs so the operator can triage within working hours.
+      # No auto-revert — that's intentionally an operator decision.
+      # ─────────────────────────────────────────────────────────────
+      - name: Open hotfix issue on post-merge regression
+        if: failure() && github.event_name == 'push' && github.ref == 'refs/heads/main'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          MERGE_SHA="${{ github.sha }}"
+          MERGE_SHA_SHORT=$(echo "$MERGE_SHA" | cut -c1-7)
+          RUN_URL="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+
+          # Extract failing spec names from the JSON reporter output if available.
+          FAILING=""
+          if [ -f e2e-regression-results.json ]; then
+            FAILING=$(jq -r '
+              [.. | objects | select(.status == "failed" or .status == "timedOut") | .title // empty]
+              | unique | .[]
+            ' e2e-regression-results.json 2>/dev/null | head -20 || true)
+          fi
+          if [ -z "$FAILING" ]; then
+            FAILING="(see the failing run logs — could not parse spec titles from reporter output)"
+          fi
+
+          BODY=$(cat <<EOF
+          ## Post-merge regression caught on \`main\`
+
+          The full regression suite failed on the post-merge run for commit \`${MERGE_SHA_SHORT}\`. The critical-tier PR gate let this slip through.
+
+          **Failing specs (best-effort extracted from the JSON reporter):**
+
+          \`\`\`
+          ${FAILING}
+          \`\`\`
+
+          **Triage actions:**
+
+          - [ ] Read the run log: ${RUN_URL}
+          - [ ] Pull \`e2e-regression-report\` artifact from the run; inspect \`test-results/<spec>/error-context.md\` for page state at failure
+          - [ ] Decide: hotfix on \`main\`, revert \`${MERGE_SHA_SHORT}\`, or accept-with-rationale if the failure is environmental
+          - [ ] If the failing spec is a Must-tier candidate that should have caught this pre-merge, move it from \`e2e/\` to \`e2e/critical/\` so the next PR-to-main runs it
+
+          **Auto-filed by:** \`e2e-regression.yml\` (devaudit#152 3-tier gating, v0.1.53+)
+          EOF
+          )
+
+          gh issue create \
+            --title "[hotfix] Post-merge regression on \`${MERGE_SHA_SHORT}\` — full E2E failed" \
+            --body "$BODY" \
+            --label "bug,priority:high"