@metasession.co/devaudit-cli 0.1.47 → 0.1.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.1.47",
+  "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.47",
+    "@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/scripts/update-sdlc-status.sh

@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+# update-sdlc-status.sh — Post or update the canonical SDLC status
+# sticky comment on a REQ tracking issue (devaudit#131).
+#
+# Purpose: long-running SDLC issues accumulate dozens of comments.
+# The operator scrolling the thread can't find "where are we right
+# now" without re-reading. This helper writes a marker-tagged comment
+# at a predictable shape; subsequent calls find + edit the existing
+# comment instead of stacking new ones, so the latest status always
+# lives in exactly one place on the issue.
+#
+# Idempotent — find-or-create. The marker is HTML-commented so it
+# doesn't show up in the rendered issue UI but is greppable via the
+# API. Subsequent invocations on the same issue replace the body
+# without dropping the marker.
+#
+# Usage:
+#   ./scripts/update-sdlc-status.sh <issue-number> "<last-step>" "<next-step>" [--repo owner/name] [--dry-run]
+#
+# Examples:
+#   ./scripts/update-sdlc-status.sh 322 \
+#     "Phase 2 complete — feat branch landed on develop" \
+#     "Phase 3 — sdlc-implementer auto-continuing"
+#
+#   ./scripts/update-sdlc-status.sh 322 \
+#     "Phase 4 — release PR #455 opened" \
+#     "Operator action — review + merge develop→main when ready" \
+#     --repo metasession-dev/wawagardenbar-app
+#
+# Required:
+#   - `gh` CLI authenticated (uses GITHUB_TOKEN or the current `gh auth` session)
+#   - The issue must exist
+#
+# Optional flags:
+#   --repo owner/name   Override repo (defaults to the cwd's git remote)
+#   --dry-run           Print the body + the gh command that would run,
+#                       without making any API calls. Used by the test
+#                       suite + safe for operator inspection.
+
+set -euo pipefail
+
+if [ "$#" -lt 3 ]; then
+  cat <<'USAGE' >&2
+Usage: update-sdlc-status.sh <issue-number> "<last-step>" "<next-step>" [--repo owner/name] [--dry-run]
+USAGE
+  exit 1
+fi
+
+ISSUE_NUM="$1"
+LAST_STEP="$2"
+NEXT_STEP="$3"
+shift 3
+
+REPO=""
+DRY_RUN=false
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --repo)
+      REPO="$2"
+      shift 2
+      ;;
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    *)
+      echo "Unknown flag: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Validate issue number is numeric early so we don't make bogus API
+# calls when the caller fat-fingers the arg order.
+if ! [[ "$ISSUE_NUM" =~ ^[1-9][0-9]*$ ]]; then
+  echo "Error: issue number must be a positive integer, got: $ISSUE_NUM" >&2
+  exit 1
+fi
+
+MARKER='<!-- sdlc-implementer:status -->'
+
+# Body shape — keep this compact and load-bearing. The marker MUST be
+# the first line so the find-existing pass can use startswith() in
+# the gh JSON filter without false positives.
+BODY=$(cat <<EOF
+$MARKER
+
+**🟢 LAST STEP** — $LAST_STEP
+
+**🔵 NEXT STEP** — $NEXT_STEP
+
+---
+
+_Updated by \`sdlc-implementer\` on every stage transition. The full SDLC trail lives in the comments below; this comment is the always-current pointer._
+EOF
+)
+
+REPO_FLAG=""
+if [ -n "$REPO" ]; then
+  REPO_FLAG="--repo $REPO"
+fi
+
+if [ "$DRY_RUN" = "true" ]; then
+  echo "[dry-run] would update sticky on issue #$ISSUE_NUM${REPO:+ in $REPO}"
+  echo "----- body -----"
+  echo "$BODY"
+  echo "----- end body -----"
+  exit 0
+fi
+
+# Find an existing status sticky on this issue. We grep through the
+# comments looking for the canonical marker; if found, edit it; if
+# not, create a fresh one.
+#
+# gh's --jq filter handles the lookup server-side so we don't drag
+# every comment back to local. `startswith` is the right matcher
+# because the marker is always the first line.
+EXISTING_ID=""
+# Build the api endpoint. Without --repo, gh resolves from the current
+# git remote — same as `gh issue …` does elsewhere in the framework.
+if [ -n "$REPO" ]; then
+  EXISTING_ID=$(gh api "repos/$REPO/issues/$ISSUE_NUM/comments" --paginate \
+    --jq '.[] | select(.body | startswith("'"$MARKER"'")) | .id' | head -1)
+else
+  EXISTING_ID=$(gh api "repos/{owner}/{repo}/issues/$ISSUE_NUM/comments" --paginate \
+    --jq '.[] | select(.body | startswith("'"$MARKER"'")) | .id' | head -1)
+fi
+
+if [ -n "$EXISTING_ID" ]; then
+  echo "Updating existing SDLC status sticky (comment id: $EXISTING_ID)"
+  if [ -n "$REPO" ]; then
+    gh api "repos/$REPO/issues/comments/$EXISTING_ID" -X PATCH \
+      --field "body=$BODY" >/dev/null
+  else
+    gh api "repos/{owner}/{repo}/issues/comments/$EXISTING_ID" -X PATCH \
+      --field "body=$BODY" >/dev/null
+  fi
+else
+  echo "Posting new SDLC status sticky on issue #$ISSUE_NUM"
+  # shellcheck disable=SC2086  # REPO_FLAG must split on space
+  gh issue comment "$ISSUE_NUM" $REPO_FLAG --body "$BODY" >/dev/null
+fi
+
+echo "SDLC status updated."

package/sdlc/files/_common/scripts/update-sdlc-status.test.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# update-sdlc-status.test.sh — Tests for the SDLC status sticky helper
+# (devaudit#131). Exercises --dry-run so no real API call is needed.
+#
+# Usage:
+#   ./scripts/update-sdlc-status.test.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HELPER="$SCRIPT_DIR/update-sdlc-status.sh"
+[ -x "$HELPER" ] || chmod +x "$HELPER"
+
+PASS=0
+FAIL=0
+ok() { echo "  ✓ $1"; PASS=$((PASS + 1)); }
+no() { echo "  ✗ $1"; FAIL=$((FAIL + 1)); }
+
+case_missing_args() {
+  echo "case: missing args exits non-zero with a usage line"
+  local out exit_code
+  out=$("$HELPER" 2>&1) && exit_code=0 || exit_code=$?
+  if [ "$exit_code" -ne 0 ]; then
+    ok "exit code non-zero ($exit_code)"
+  else
+    no "expected non-zero exit on missing args"
+  fi
+  if printf '%s\n' "$out" | grep -q "Usage:"; then
+    ok "stderr includes Usage line"
+  else
+    no "stderr missing Usage; got:\n$out"
+  fi
+}
+
+case_non_numeric_issue() {
+  echo "case: non-numeric issue number fails fast"
+  local out exit_code
+  out=$("$HELPER" "abc" "last" "next" --dry-run 2>&1) && exit_code=0 || exit_code=$?
+  if [ "$exit_code" -ne 0 ]; then
+    ok "exit code non-zero"
+  else
+    no "expected failure on non-numeric issue number"
+  fi
+  if printf '%s\n' "$out" | grep -q "must be a positive integer"; then
+    ok "error message names the problem"
+  else
+    no "wrong error message:\n$out"
+  fi
+}
+
+case_dry_run_emits_body() {
+  echo "case: --dry-run prints the body without invoking gh"
+  local out exit_code
+  out=$("$HELPER" 42 "Phase 1 complete — plan written" "Phase 2 — implement" --dry-run 2>&1) && exit_code=0 || exit_code=$?
+  if [ "$exit_code" -eq 0 ]; then
+    ok "exit code 0"
+  else
+    no "expected exit 0, got $exit_code"
+    return
+  fi
+  if printf '%s\n' "$out" | grep -q '<!-- sdlc-implementer:status -->'; then
+    ok "body includes marker comment"
+  else
+    no "body missing marker; got:\n$out"
+  fi
+  if printf '%s\n' "$out" | grep -qE '\*\*🟢 LAST STEP\*\* — Phase 1 complete'; then
+    ok "body includes LAST STEP line"
+  else
+    no "LAST STEP line missing or wrong format; got:\n$out"
+  fi
+  if printf '%s\n' "$out" | grep -qE '\*\*🔵 NEXT STEP\*\* — Phase 2 — implement'; then
+    ok "body includes NEXT STEP line"
+  else
+    no "NEXT STEP line missing or wrong format; got:\n$out"
+  fi
+  if printf '%s\n' "$out" | grep -q 'would update sticky on issue #42'; then
+    ok "dry-run header names the issue"
+  else
+    no "dry-run header missing issue number; got:\n$out"
+  fi
+}
+
+case_dry_run_repo_flag() {
+  echo "case: --repo flag is reflected in the dry-run header"
+  local out
+  out=$("$HELPER" 5 "a" "b" --repo metasession-dev/example --dry-run 2>&1)
+  if printf '%s\n' "$out" | grep -q 'in metasession-dev/example'; then
+    ok "dry-run header includes repo"
+  else
+    no "dry-run header missing repo; got:\n$out"
+  fi
+}
+
+case_unknown_flag_rejected() {
+  echo "case: unknown flag rejected"
+  local out exit_code
+  out=$("$HELPER" 1 "a" "b" --bogus 2>&1) && exit_code=0 || exit_code=$?
+  if [ "$exit_code" -ne 0 ] && printf '%s\n' "$out" | grep -q 'Unknown flag'; then
+    ok "unknown flag rejected with message"
+  else
+    no "expected unknown-flag rejection; got exit $exit_code, output:\n$out"
+  fi
+}
+
+case_marker_is_first_line() {
+  echo "case: marker is the FIRST line of the body (find-existing relies on startswith)"
+  local out
+  out=$("$HELPER" 1 "a" "b" --dry-run 2>&1)
+  # Extract just the body between the markers we print
+  local body
+  body=$(printf '%s\n' "$out" | awk '/^----- body -----$/,/^----- end body -----$/')
+  local first
+  first=$(printf '%s\n' "$body" | sed -n '2p') # line 1 is the "----- body -----" header; line 2 is the body's first line
+  if printf '%s\n' "$first" | grep -q '<!-- sdlc-implementer:status -->'; then
+    ok "marker is the body's first line"
+  else
+    no "marker not on first line; first line was: '$first'"
+  fi
+}
+
+case_missing_args
+case_non_numeric_issue
+case_dry_run_emits_body
+case_dry_run_repo_flag
+case_unknown_flag_rejected
+case_marker_is_first_line
+
+echo ""
+echo "=== update-sdlc-status.test.sh ==="
+echo "PASS: $PASS  FAIL: $FAIL"
+[ "$FAIL" -eq 0 ]

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