@metasession.co/devaudit-cli 0.1.49 → 0.1.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.1.49",
+  "version": "0.1.52",
   "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.52",
     "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/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.
@@ -303,6 +305,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 +384,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