@metasession.co/devaudit-cli 0.1.70 → 0.1.72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.1.70",
+  "version": "0.1.72",
   "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.70",
+    "@metasession.co/devaudit-plugin-sdk": "^0.1.72",
     "ajv": "^8.20.0",
     "commander": "^12.1.0",
     "consola": "^3.2.3",
@@ -41,7 +41,9 @@
     "execa": "^9.5.1"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.9.0",
+    "js-yaml": "^5.1.0",
     "msw": "^2.7.0",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",

package/sdlc/files/_common/scripts/derive-release-version.sh

@@ -26,6 +26,13 @@
 # bare date — when exactly one ticket is open, attribute to it.
 # Multiple open tickets stays ambiguous → bare-date fallback.
 #
+# Note (DevAudit-Installer#220): `devaudit update` syncs now include
+# `[skip ci]` in their commit message, so they no longer trigger CI
+# at all. The bare-date fallback (step 5) is therefore reached only by
+# human-authored housekeeping commits — the intended use case. Skipped
+# housekeeping changes are bundled into the next REQ release via
+# `generate-bundled-changes.sh` (run by the register-release CI job).
+#
 # Step 4-bis (DevAudit-Installer#95) is the zero-ceremony equivalent:
 # RTM.md is the file the operator already maintains as the source of
 # truth for release state. When step 4 finds no ticket and exactly one

package/sdlc/files/_common/scripts/generate-bundled-changes.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# generate-bundled-changes.sh
+#
+# Scans commits since a given ref (tag, SHA, or branch) and filters for
+# housekeeping commit types (chore/docs/ci/build/test/revert) that were
+# skipped via [skip ci] or otherwise not individually released. Outputs
+# a markdown summary suitable for upload as `bundled_changes` evidence
+# against a REQ-tagged release.
+#
+# Synced into the consumer's `scripts/` by `devaudit update`; invoked
+# from `ci.yml` register-release job when the derived version is a
+# REQ-tagged release (not bare-date).
+#
+# Usage:
+#   bash scripts/generate-bundled-changes.sh <since-ref> [<version>]
+#
+# Where:
+#   <since-ref>  — git ref to scan from (tag, SHA, or branch name).
+#                   Typically the previous release tag or the merge-base
+#                   of the current branch and the previous release.
+#   <version>    — (optional) the release version for the header.
+#                   Defaults to "current release".
+#
+# Output (stdout): markdown document listing housekeeping commits
+# absorbed into this release.
+#
+# DevAudit-Installer#220.
+
+set -euo pipefail
+
+SINCE_REF="${1:-}"
+VERSION="${2:-current release}"
+
+if [ -z "$SINCE_REF" ]; then
+  echo "Usage: bash scripts/generate-bundled-changes.sh <since-ref> [<version>]" >&2
+  exit 1
+fi
+
+# Verify the ref exists before proceeding.
+if ! git rev-parse --verify "$SINCE_REF" >/dev/null 2>&1; then
+  echo "Error: ref '$SINCE_REF' not found in git history." >&2
+  exit 1
+fi
+
+# Housekeeping commit type prefixes (Conventional Commits).
+# feat/fix are tracked changes — excluded. Anything else is housekeeping.
+# The git log format is "<short-sha>\t<subject>", so the regex matches
+# the commit type after the tab character.
+HOUSEKEEPING_TYPES='^[0-9a-f]+	(chore|docs|ci|build|test|revert|style|perf|refactor)(\(.+\))?!?:'
+
+# Collect commits since the ref, filtering for housekeeping types.
+# Format: <short-sha>\t<subject>
+COMMITS=$(git log "$SINCE_REF"..HEAD --format='%h	%s' 2>/dev/null || true)
+
+if [ -z "$COMMITS" ]; then
+  # No commits since ref — output an empty summary.
+  echo "## Bundled Changes"
+  echo ""
+  echo "No housekeeping commits found since \`${SINCE_REF}\`."
+  echo ""
+  exit 0
+fi
+
+# Filter for housekeeping commit types.
+BUNDLED=$(echo "$COMMITS" | grep -E "$HOUSEKEEPING_TYPES" || true)
+
+if [ -z "$BUNDLED" ]; then
+  echo "## Bundled Changes"
+  echo ""
+  echo "No housekeeping commits found since \`${SINCE_REF}\`."
+  echo ""
+  exit 0
+fi
+
+# Count the bundled commits.
+COUNT=$(echo "$BUNDLED" | wc -l | tr -d ' ')
+
+# Generate the markdown summary.
+echo "## Bundled Changes"
+echo ""
+echo "The following ${COUNT} housekeeping commit(s) were absorbed into release \`${VERSION}\` since \`${SINCE_REF}\`:"
+echo ""
+echo "$BUNDLED" | while IFS=$'\t' read -r SHA SUBJECT; do
+  echo "- \`${SHA}\` ${SUBJECT}"
+done
+echo ""
+echo "These commits were not individually released (tooling syncs / housekeeping)."
+echo "Gate evidence above covers the full state of develop at CI time, including these changes."

package/sdlc/files/_common/scripts/generate-bundled-changes.test.sh

@@ -0,0 +1,183 @@
+#!/usr/bin/env bash
+# generate-bundled-changes.test.sh — Tests for generate-bundled-changes.sh.
+#
+# Builds a throwaway git repo per case, crafts commits with mixed types,
+# runs the helper against it, asserts on the stdout content. Hermetic:
+# runs inside mktemp'd directories that are torn down at the end.
+#
+# Usage:
+#   ./scripts/generate-bundled-changes.test.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HELPER="$SCRIPT_DIR/generate-bundled-changes.sh"
+[ -x "$HELPER" ] || chmod +x "$HELPER"
+
+PASS=0
+FAIL=0
+
+TMPDIR_BASE="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR_BASE"' EXIT
+
+# Build a fresh git fixture with an initial commit.
+make_fixture() {
+  local dir="$1"
+  rm -rf "$dir"
+  mkdir -p "$dir"
+  cd "$dir"
+  git init -q --initial-branch=main
+  git config user.email "test@example.com"
+  git config user.name "test"
+  echo "x" > f.txt
+  git add f.txt
+  git commit -q -m "feat: initial commit [REQ-001]"
+}
+
+# Add a commit with a given message.
+add_commit() {
+  local msg="$1"
+  echo "$(date +%s%N)" >> f.txt
+  git add f.txt
+  git commit -q -m "$msg"
+}
+
+assert_contains() {
+  local desc="$1" want="$2" got="$3"
+  if echo "$got" | grep -qF "$want"; then
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $desc"
+    echo "    want (substring): $want"
+    echo "    got:"
+    echo "$got" | sed 's/^/      /'
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+assert_not_contains() {
+  local desc="$1" want="$2" got="$3"
+  if echo "$got" | grep -qF "$want"; then
+    echo "  FAIL: $desc"
+    echo "    should not contain: $want"
+    echo "    got:"
+    echo "$got" | sed 's/^/      /'
+    FAIL=$((FAIL + 1))
+  else
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  fi
+}
+
+# ─── Test 1: Mixed commits — only housekeeping types in output ─────
+echo "Test 1: mixed commits filter to housekeeping only"
+DIR1="$TMPDIR_BASE/test1"
+make_fixture "$DIR1"
+add_commit "chore: sync DevAudit templates from v0.1.69 to v0.1.70 [skip ci]"
+add_commit "docs: update API reference for /bookings endpoint"
+add_commit "feat: add booking widget [REQ-042]"
+add_commit "chore: bump eslint 9.0.5 to 9.0.6"
+add_commit "fix: resolve null pointer in booking service [REQ-042]"
+# Tag the initial commit as the "since" ref
+SINCE=$(git rev-list --max-parents=0 HEAD)
+OUTPUT=$(bash "$HELPER" "$SINCE" "REQ-042" 2>&1 || true)
+assert_contains "housekeeping chore: sync in output" "chore: sync DevAudit templates" "$OUTPUT"
+assert_contains "housekeeping docs: update in output" "docs: update API reference" "$OUTPUT"
+assert_contains "housekeeping chore: bump eslint in output" "chore: bump eslint" "$OUTPUT"
+assert_not_contains "feat commit excluded" "feat: add booking widget" "$OUTPUT"
+assert_not_contains "fix commit excluded" "fix: resolve null pointer" "$OUTPUT"
+assert_contains "header present" "## Bundled Changes" "$OUTPUT"
+assert_contains "version in header" "REQ-042" "$OUTPUT"
+echo
+
+# ─── Test 2: No housekeeping commits ────────────────────────────────
+echo "Test 2: no housekeeping commits — empty summary"
+DIR2="$TMPDIR_BASE/test2"
+make_fixture "$DIR2"
+add_commit "feat: add feature A [REQ-010]"
+add_commit "fix: fix bug B [REQ-010]"
+SINCE=$(git rev-list --max-parents=0 HEAD)
+OUTPUT=$(bash "$HELPER" "$SINCE" "REQ-010" 2>&1 || true)
+assert_contains "no housekeeping message" "No housekeeping commits found" "$OUTPUT"
+echo
+
+# ─── Test 3: All housekeeping types captured ────────────────────────
+echo "Test 3: all housekeeping commit types captured"
+DIR3="$TMPDIR_BASE/test3"
+make_fixture "$DIR3"
+add_commit "ci: update workflow timeout"
+add_commit "build: bump node version to 22"
+add_commit "test: add unit test for booking"
+add_commit "revert: remove experimental feature"
+add_commit "style: fix formatting in utils"
+add_commit "perf: optimize query in booking"
+add_commit "refactor: extract validation logic"
+SINCE=$(git rev-list --max-parents=0 HEAD)
+OUTPUT=$(bash "$HELPER" "$SINCE" "REQ-030" 2>&1 || true)
+assert_contains "ci: type captured" "ci: update workflow timeout" "$OUTPUT"
+assert_contains "build: type captured" "build: bump node version" "$OUTPUT"
+assert_contains "test: type captured" "test: add unit test for booking" "$OUTPUT"
+assert_contains "revert: type captured" "revert: remove experimental feature" "$OUTPUT"
+assert_contains "style: type captured" "style: fix formatting" "$OUTPUT"
+assert_contains "perf: type captured" "perf: optimize query" "$OUTPUT"
+assert_contains "refactor: type captured" "refactor: extract validation" "$OUTPUT"
+echo
+
+# ─── Test 4: No commits since ref ───────────────────────────────────
+echo "Test 4: no commits since ref — empty summary"
+DIR4="$TMPDIR_BASE/test4"
+make_fixture "$DIR4"
+SINCE=$(git rev-parse HEAD)
+OUTPUT=$(bash "$HELPER" "$SINCE" "REQ-001" 2>&1 || true)
+assert_contains "no commits message" "No housekeeping commits found" "$OUTPUT"
+echo
+
+# ─── Test 5: Invalid ref ────────────────────────────────────────────
+echo "Test 5: invalid ref — error exit"
+DIR5="$TMPDIR_BASE/test5"
+make_fixture "$DIR5"
+set +e
+OUTPUT=$(bash "$HELPER" "nonexistent-ref" "REQ-001" 2>&1)
+RC=$?
+set -e
+if [ "$RC" -ne 0 ]; then
+  echo "  PASS: non-zero exit code for invalid ref"
+  PASS=$((PASS + 1))
+else
+  echo "  FAIL: expected non-zero exit code for invalid ref"
+  FAIL=$((FAIL + 1))
+fi
+echo
+
+# ─── Test 6: Scoped commit types (chore(deps)) ─────────────────────
+echo "Test 6: scoped housekeeping commits captured"
+DIR6="$TMPDIR_BASE/test6"
+make_fixture "$DIR6"
+add_commit "chore(deps): bump eslint from 9.0.5 to 9.0.6"
+add_commit "ci(workflow): update timeout to 30 minutes"
+SINCE=$(git rev-list --max-parents=0 HEAD)
+OUTPUT=$(bash "$HELPER" "$SINCE" "REQ-050" 2>&1 || true)
+assert_contains "scoped chore(deps) captured" "chore(deps): bump eslint" "$OUTPUT"
+assert_contains "scoped ci(workflow) captured" "ci(workflow): update timeout" "$OUTPUT"
+echo
+
+# ─── Test 7: Missing since-ref argument ────────────────────────────
+echo "Test 7: missing since-ref argument — error exit"
+DIR7="$TMPDIR_BASE/test7"
+make_fixture "$DIR7"
+set +e
+OUTPUT=$(bash "$HELPER" 2>&1)
+RC=$?
+set -e
+if [ "$RC" -ne 0 ]; then
+  echo "  PASS: non-zero exit code for missing argument"
+  PASS=$((PASS + 1))
+else
+  echo "  FAIL: expected non-zero exit code for missing argument"
+  FAIL=$((FAIL + 1))
+fi
+echo
+
+echo "=== Summary: ${PASS} pass / ${FAIL} fail ==="
+[ "$FAIL" -eq 0 ]

package/sdlc/files/_common/scripts/validate-commits.sh

@@ -74,6 +74,29 @@ while IFS= read -r sha; do
         EXIT_CODE=1
         continue
       fi
+
+      # RTM provenance check (devaudit-installer#226): verify the REQ-XXX
+      # cited in the commit has an sdlc-implementer@<version> provenance
+      # stamp in compliance/RTM.md. Without the stamp, the skill was not
+      # invoked and the RTM row was created manually.
+      REQ_ID=$(echo "$SUBJECT" | grep -oP '\[REQ-\d{3,}\]' | tr -d '[]' || true)
+      if [ -z "$REQ_ID" ]; then
+        REQ_ID=$(echo "$BODY" | grep -oiP 'Ref:\s*REQ-\d{3,}' | grep -oP 'REQ-\d{3,}' | tail -1 || true)
+      fi
+      if [ -n "$REQ_ID" ] && [ -f compliance/RTM.md ]; then
+        RTM_ROW=$(grep -m1 -E "^\| ${REQ_ID} " compliance/RTM.md || true)
+        if [ -n "$RTM_ROW" ]; then
+          if ! echo "$RTM_ROW" | grep -q 'sdlc-implementer@'; then
+            echo "ERROR [$SHORT]: $REQ_ID in commit message has no sdlc-implementer provenance in RTM.md."
+            echo "       The RTM row for $REQ_ID was not created by the sdlc-implementer skill."
+            echo "       Either invoke sdlc-implementer and re-run, or add the provenance marker"
+            echo "       'sdlc-implementer@<version>' to the RTM row manually with operator sign-off."
+            FAILED=$((FAILED + 1))
+            EXIT_CODE=1
+            continue
+          fi
+        fi
+      fi
       ;;
   esac
 

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

@@ -288,6 +288,20 @@ There is no `regression/` sub-directory, no `@regression` tag, no manifest file.
 
 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.
 
+**Write the E2E gate sentinel (devaudit-installer#226).** After a successful full regression run (Phase 6 step 2), write a `.e2e-gate-passed` sentinel file in the repo root so the pre-push hook and `sdlc-implementer` Phase 2 step 5b can verify the E2E gate ran:
+
+```bash
+echo "PASSED $(date -u +%Y-%m-%dT%H:%M:%SZ) ${{ github.run_id }}" > .e2e-gate-passed
+```
+
+If you determined e2e is not needed for this REQ (schema-only, API-only, no UI surface), write the sentinel with a `NOT_NEEDED` reason instead:
+
+```bash
+echo "NOT_NEEDED $(date -u +%Y-%m-%dT%H:%M:%SZ) <reason>" > .e2e-gate-passed
+```
+
+The file is gitignored and never committed — it's a local-only signal that the gate was run in this working directory.
+
 ### 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.

package/sdlc/files/_common/skills/sdlc-implementer/SKILL.md

@@ -96,7 +96,7 @@ When the user asks for a change that goes beyond the current REQ's acceptance cr
 
 4. **Wait for the user to confirm one of:**
    - **(a) File a separate issue** (new REQ) — ship the current REQ as-is. The agent continues with the original scope.
-   - **(b) Amend REQ-XXX's scope** — explicitly expand `test-scope.md` / `implementation-plan.md`, update the plan, invalidate existing evidence, and re-walk Stage 3. This option carries a warning: *"Amending scope after evidence is compiled (Stage 3+) invalidates the existing test-execution-summary, screenshots, and UAT verification. All Stage 3 evidence must be re-compiled."*
+   - **(b) Amend REQ-XXX's scope** — explicitly expand `test-scope.md` / `test-plan.md` / `implementation-plan.md`, update the plan, invalidate existing evidence, and re-walk Stage 3. Re-extract both `test-scope.md` and `test-plan.md` from the updated plan (Phase 1 step 5b drift management). This option carries a warning: *"Amending scope after evidence is compiled (Stage 3+) invalidates the existing test-execution-summary, screenshots, and UAT verification. All Stage 3 evidence must be re-compiled."*
    - **(c) Abandon the request** — do nothing, continue with the original scope.
 
 **Do not implement the out-of-scope change before the user picks (a), (b), or (c).** The inertia trap is real: the agent is mid-flow, the codebase is open, and the request sounds reasonable. The gate exists to interrupt that inertia — STOP, surface the scope gap, and let the user decide.
@@ -140,10 +140,11 @@ Amendment steps:
 2. Re-invoke `requirements-aligner` → propose new/updated SRS stubs
 3. Operator edits SRS stubs into canonical Given/When/Then prose in `docs/SRS.md`
 4. Update `compliance/RTM.md`
-5. Commit: `compliance: [REQ-XXX] amend ACs — requirements gap <description>`
-6. If Phase 2+: re-run affected tests (delegating to `e2e-test-engineer` if e2e)
-7. If Phase 3+: re-compile affected evidence
-8. Continue from current phase
+5. Re-extract `compliance/evidence/REQ-XXX/test-scope.md` and `compliance/evidence/REQ-XXX/test-plan.md` from the updated plan (Phase 1 step 5b drift management, devaudit-installer#226)
+6. Commit: `compliance: [REQ-XXX] amend ACs — requirements gap <description>`
+7. If Phase 2+: re-run affected tests (delegating to `e2e-test-engineer` if e2e)
+8. If Phase 3+: re-compile affected evidence
+9. Continue from current phase
 
 **(c) File a follow-up REQ** — ship the current REQ as-is, file a separate issue for the requirements gap. Appropriate when the gap is a genuine new behaviour that deserves its own cycle. Continue with the current REQ unchanged.
 
@@ -254,7 +255,7 @@ Runs **first**, before any `REQ-XXX` is assigned. It decides which of the six ch
 3. **Announce a "Workflow Decision" block** (template below): change-type, commit-type, whether a `REQ-XXX` is needed, risk class, which stages/gates run, which approvals the **operator** must perform (UAT four-eyes, Production approval), and what is **skipped**.
 4. **Pause policy — pause-when-it-matters.** Pause for explicit confirmation on **tracked / heavier** paths, or when classification is **ambiguous**; **announce-and-auto-proceed** on trivial / housekeeping. The operator can always reclassify ("treat this as housekeeping" / "this is HIGH risk").
 5. **Route — and stay on to completion.** A route is a choice of _which workflow to drive_, never a hand-off that abandons the operator. Whatever the path, the skill keeps guiding step by step until no further action is required (typically: merged).
-   - **tracked** (feature / bug fix / refactor / perf) → continue into Phase 1 below (full Stages 1–5).
+   - **tracked** (feature / bug fix / refactor / perf) → continue into Phase 1 below (full Stages 1–5). **Write the skill-invocation sentinel** (devaudit-installer#226): `echo "INVOKED $(date -u +%Y-%m-%dT%H:%M:%SZ)" > .sdlc-implementer-invoked`. This file is gitignored and never committed — it's a local-only signal that the pre-push hook checks before allowing `feat`/`fix`/`refactor`/`perf` commits to be pushed. Without this sentinel, the pre-push hook will refuse the push and `validate-commits.sh` in CI will flag missing RTM provenance.
    - **housekeeping / trivial** → drive the **Lightweight path** below to completion. No `REQ-XXX`, no RTM row, no evidence pack, no portal release approvals — but the skill still branches, runs the gates, opens the PR, and walks the operator through review → merge.
    - **compliance-doc-only** → drive the same Lightweight path as a docs push (or PR, per the project's flow) referencing the **existing** `REQ-XXX`: no new requirement and no quality-gate ceremony, but driven through to merge.
 6. **Write labels back.** Apply the inferred `type:*` / `risk:*` labels so the issue ends up labelled — `gh label create <label> --force` to ensure the label exists (idempotent; no failure if a label-seeding step never ran), then `gh issue edit <N> --add-label <label>`. Future triage is then a glance.
@@ -354,6 +355,15 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
 
    **Don't delete sections** — mark with `N/A — <reason>` if a clause genuinely doesn't apply (e.g. UI-only change with no personal-data scope). Empty stubs commit-then-upload as placeholder evidence and break the audit trail.
 
+5b. **Extract `test-scope.md` and `test-plan.md` from the implementation plan (devaudit-installer#226).** After step 5, extract two artefacts from the plan into `compliance/evidence/REQ-XXX/` so CI's `validate-compliance-artifacts.sh` finds them in the expected location:
+
+   - **`compliance/evidence/REQ-XXX/test-scope.md`** — the AC table with SRS-IDs, risk class, and verification method per AC. Extracted from the plan's "Acceptance criteria" table.
+   - **`compliance/evidence/REQ-XXX/test-plan.md`** — the test file listing with AC coverage mapping: which test file covers which AC, test type (unit/integration/e2e), and whether each AC has at least one test. Extracted from the plan's "Test scope" section.
+
+   These files are the CI validator's expected artefacts. Without them, `validate-compliance-artifacts.sh` fails and the pre-push hook blocks the push. The plan directory (`compliance/plans/REQ-XXX/`) retains the full plan; these are extracted subsets for CI validation.
+
+   **Drift management (devaudit-installer#226).** If the plan's AC table changes after step 5b (requirements gap flow option (b), scope-expansion halt gate option (b), or plan deviation), re-extract both `test-scope.md` and `test-plan.md` from the updated plan. The extracted files must always match the plan's current AC table. Phase 2 step 5b checks plan ↔ test-scope AC consistency before running E2E.
+
 6. **Invoke `requirements-aligner` to populate the SRS-ID column on the AC table.** The plan's "Acceptance criteria" table carries an SRS-ID column per AC; `requirements-aligner` fuzzy-matches each AC against `docs/SRS.md` and proposes new `REQ-AREA-NNN` stubs, flags stale items, or annotates `@srs-deferred`. Don't author the SRS-ID column inline — call via the standard Claude Code Skill mechanism (`Skill(name: "requirements-aligner", …)`). Block plan APPROVAL until every AC has a resolved SRS-ID per the skill's Phase 1 contract (configurable via `sdlc-config.json:requirements_aligner.block_on_stage_1`; ramp-up mode default-on for legacy projects).
 
    **SRS stub editing (devaudit-installer#212 Gap 5).** After `requirements-aligner` returns, the plan's SRS items proposed/touched section may contain N new stubs and M stale items. The operator must edit `docs/SRS.md` to flesh out the stubs into canonical Given/When/Then prose and update stale items. Do not proceed to Phase 2 until the SRS is updated. The skill enforces this by checking that no stub placeholders remain in `docs/SRS.md` for the proposed SRS-IDs before auto-continuing. A stub placeholder is any SRS entry containing `<TODO>` or the `@srs-stub` marker.
@@ -364,7 +374,7 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
 - **`requirements-aligner` fails** (e.g. no `docs/SRS.md`): If `block_on_stage_1` is true, halt — "requirements-aligner could not find SRS.md. Operator action — create `docs/SRS.md` or disable `requirements_aligner.block_on_stage_1` in `sdlc-config.json`." If false, warn and continue with `@srs-deferred` on all ACs.
 - **`adr-author` fails**: Warn and continue — ADR is advisory by default. Mark the plan's "Architecture decisions" section as "ADR assessment skipped — <error>".
 - **`risk-register-keeper` fails**: If `block_on_stage_1` is true, halt. If false, warn and continue — mark the plan's "Risk register entries" section as "Risk assessment skipped — <error>".
-9. **Update `compliance/RTM.md`** with the new entry: REQ-XXX, title, risk class, linked issue, linked test cases (placeholder).
+9. **Update `compliance/RTM.md`** with the new entry: REQ-XXX, title, risk class, linked issue, linked test cases (placeholder), and a provenance marker `sdlc-implementer@<version>` (devaudit-installer#226). The provenance column is the last column in the RTM row — `validate-commits.sh` in CI checks for its presence when `feat`/`fix`/`refactor`/`perf` commits cite a REQ-XXX. Without the stamp, CI fails with "no sdlc-implementer provenance in RTM.md." If the RTM table doesn't have a provenance column, add one with header `Provenance`.
 10. **Post plan summary as an issue comment.** Format: TL;DR; Risk class + signals; Acceptance criteria (with SRS-IDs); Architectural decisions (ADR-NNN reference or no-ADR rationale); Risk register entries (RISK-NNN list); Technical approach (one paragraph); Dependencies; Test scope.
 11. **Checkpoint** — pause for human approval **iff** risk class is HIGH or CRITICAL. LOW and MEDIUM pass through to Phase 2 automatically. The checkpoint can be forced on for all classes via the `--require-plan-approval` flag (or `DEVAUDIT_REQUIRE_PLAN_APPROVAL=1` env var) for orgs that want it always-on.
 12. **Update SDLC status sticky** before exiting Phase 1: `bash scripts/update-sdlc-status.sh "$ISSUE_NUM" "Phase 1 complete — plan written to compliance/plans/REQ-XXX/implementation-plan.md (risk class <CLASS>)" "Phase 2 — sdlc-implementer auto-continuing"` (or "Operator action — review plan + ping resume" if the HIGH/CRITICAL checkpoint paused).
@@ -401,6 +411,19 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
    **E2E gate** — run _once_, after the fast gates are clean:
    - `npx playwright test` (delegated to `e2e-test-engineer`, which has its own focused-iteration discipline for within-e2e fix-and-verify loops)
 
+5b. **E2E gate verification — mandatory before commit (devaudit-installer#226).** After running gates in step 5, verify the E2E gate actually ran before proceeding to step 7 (commit). This is the skill-level enforcement that backs the pre-push hook.
+
+   Check whether the change touches UI-facing files:
+   ```bash
+   git diff --name-only "$INTEGRATION_BRANCH"...HEAD -- 'app/**/*.tsx' 'src/**/*.tsx' 'pages/**/*.tsx' 'app/**/*.jsx' 'src/**/*.jsx' 'pages/**/*.jsx'
+   ```
+
+   - **If UI-facing files are present:** check for `.e2e-gate-passed` sentinel file (written by `e2e-test-engineer` after a successful run) or `playwright-report/` directory with recent content. If neither exists, **HALT**: "E2E gate was not run. The change touches UI-facing files. Run `npx playwright test` (or invoke `e2e-test-engineer`) before committing. The pre-push hook will also block this push."
+   - **If no UI-facing files (API-only, config, docs):** skip the check. Note the exemption in the commit body: "E2E gate skipped — no UI-facing files in this change."
+   - **If `e2e-test-engineer` was invoked and determined e2e is not needed** (e.g. schema-only change): the skill writes `.e2e-gate-passed` with a `NOT_NEEDED` reason. The sentinel check passes. Note the exemption in the commit body: "E2E gate not needed — e2e-test-engineer assessed no UI surface (turn N)."
+
+   **Plan ↔ test-scope AC consistency check (devaudit-installer#226 drift management).** Before running E2E, verify the AC table in `compliance/plans/REQ-XXX/implementation-plan.md` matches `compliance/evidence/REQ-XXX/test-scope.md`. Compare the AC IDs in both files — if they diverge (new AC added to plan but not re-extracted, or AC removed from plan but still in test-scope), **HALT**: "test-scope.md is out of sync with implementation-plan.md. AC IDs differ: <diff>. Re-extract test-scope.md and test-plan.md from the updated plan (Phase 1 step 5b) before running E2E."
+
 6. **On gate failure**, iterate up to N=3 attempts. Each iteration: read the failure output, propose a fix, apply, re-run. On exhausted attempts, halt with the full failure output and explicit resume instructions: "Gate <name> failed after N=3 attempts. Last failure: <output>. Operator action — fix the failure, commit to the feature branch, push, then ping `resume REQ-XXX`. The skill will re-run the gate from where it left off." Update the sticky with the same. Never use `--no-verify`, `eslint-disable`, `@ts-expect-error`, `xfail`, or any other bypass.
 7. **Commit** using Conventional Commits with `Ref: REQ-XXX` trailer and `Co-Authored-By: Claude` trailer. One commit per logical step; never amend a commit that's already been pushed.
 8. **Land the work on `$INTEGRATION_BRANCH`.** Push the feature branch, then open a PR `feat/REQ-XXX-<slug> → $INTEGRATION_BRANCH` and merge it once CI is green. This is the **integration hop** — there is no UAT four-eyes gate here (that's the release PR in Phase 4); for MEDIUM+ risk get a peer review on this PR per the project's norms. The push to `$INTEGRATION_BRANCH` is what triggers `ci.yml` to register the release and upload gate evidence. **Merge conflict resolution:** if the PR has merge conflicts (another feature branch merged first), pull the latest `$INTEGRATION_BRANCH` into the feature branch (`git merge "$INTEGRATION_BRANCH" --no-edit`), resolve conflicts (preferring the feature branch's changes for files this REQ touches), push, wait for CI. If conflicts are in files this REQ doesn't touch, halt — "Merge conflict in <files> from another feature. Operator action — review the conflict, these files are outside REQ-XXX's scope."
@@ -462,6 +485,9 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
 
    ```
    compliance/evidence/REQ-XXX/
+   ├── test-scope.md                     ← extracted in Phase 1 step 5b
+   ├── test-plan.md                      ← extracted in Phase 1 step 5b
+   ├── implementation-plan.md            ← copied from compliance/plans/ in step 6b
    ├── srs-alignment.md                  ← produced in step 1 by requirements-aligner
    ├── architecture-decision.md          ← produced in step 2 by adr-author
    ├── risk-assessment.md                ← produced in step 3 by risk-register-keeper
@@ -474,6 +500,14 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
 
    Copy Playwright's `test-results/` folder verbatim into `YYYY-MM-DD_traces/` so trace-by-test-name is available for audit without walking the HTML report's hash-name index. For HIGH/CRITICAL releases the traces are part of the audit trail — _"what state was the page in when test X failed and was overridden?"_ answers in one `ls` instead of an HTML-report walk.
 
+6b. **Copy `implementation-plan.md` from `compliance/plans/` to `compliance/evidence/` (devaudit-installer#226).** The CI validator (`validate-compliance-artifacts.sh`) expects `implementation-plan.md` in `compliance/evidence/REQ-XXX/`, not in `compliance/plans/REQ-XXX/`. Copy (not move) the file so the plan directory retains the original:
+
+   ```bash
+   cp compliance/plans/REQ-XXX/implementation-plan.md compliance/evidence/REQ-XXX/implementation-plan.md
+   ```
+
+   This ensures the pre-push hook's compliance validator check passes. The plan directory retains the original for in-flight reference; the evidence directory has the copy for CI validation and audit.
+
 6. **Upload each artefact to the portal** — retry each upload up to 3 times with backoff (5s, 15s, 45s). If an upload still fails after 3 retries, mark it in the RTM as `UPLOAD_FAILED` and surface a warning. Do not mark the RTM as verified for failed uploads. On `resume REQ-XXX`, re-attempt failed uploads before proceeding to Phase 4.
    ```bash
    devaudit push <project-slug> REQ-XXX <evidence-type> <file> \
@@ -528,6 +562,12 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
 
 Invoked separately by the user after UAT activity on the portal. Trigger: "resume REQ-XXX", "REQ-XXX UAT done", or just re-firing the skill on the same issue.
 
+0. **Re-read state (devaudit-installer#226).** On resume, reconstruct state from the filesystem before acting:
+   - Re-read `compliance/RTM.md` to check the REQ-XXX row's current status.
+   - Check whether `compliance/pending-releases/RELEASE-TICKET-REQ-XXX.md` still exists (not yet moved to `approved-releases/`).
+   - Check `git log` for the merge commit on `$RELEASE_BRANCH`.
+   - If resuming after an environment detour (not a UAT approval), re-read `compliance/evidence/REQ-XXX/` to see which artefacts already exist and resume at the appropriate phase.
+
 1. **Read portal state.** `curl` `https://devaudit.metasession.co/api/projects/<slug>/releases/<version>` and inspect the approval status. Retry up to 3 times with exponential backoff (5s, 15s, 45s) on 5xx responses. If all retries fail, halt — "Portal unreachable at <URL>. Cannot determine UAT approval state. Operator action — verify portal availability + API key, then ping `resume REQ-XXX`." If the API returns 401/403, halt — "Portal API key rejected (HTTP 401/403). The `DEVAUDIT_API_KEY` secret may be expired or revoked. Operator action — rotate the API key, then ping `resume REQ-XXX`." Never guess the portal state.
 
 2. **Branch on state:**
@@ -541,14 +581,23 @@ Invoked separately by the user after UAT activity on the portal. Trigger: "resum
        - If `released` (Option B): PATCH directly to `released` — `PATCH /releases/<version>` with `{"status": "released"}`.
        - If `prod_review` (Option A, default): after `post-deploy-prod.yml` completes, the release is at `prod_review`. Update the sticky to "Phase 5 — production deployed; awaiting prod approval on portal" and halt. The operator clicks "Approve Production" (`prod_review` → `prod_approved`) then "Mark as Released" (`prod_approved` → `released`) in the portal. On next `resume REQ-XXX`, the skill reads the portal state — if `released`, finalise (close issue, update sticky to terminal). If `prod_approved`, prompt the operator to click "Mark as Released". If still `prod_review`, report "awaiting production approval" and stop.
      - Comment on the issue: "Released. Production smoke evidence: <link>." (only after release status is `released`)
-     - **Update SDLC status sticky** to the terminal state: `bash scripts/update-sdlc-status.sh "$ISSUE_NUM" "Phase 5 complete — release marked Released; production smoke evidence uploaded" "Done — close issue + retire feature branch (sdlc-implementer halts)"`.
+     - **Phase 5 close-out — mandatory post-merge compliance steps (devaudit-installer#226).** After the release is marked `released` on the portal, perform the close-out:
+       1. **Update RTM status** — change the REQ-XXX row from `TESTED - PENDING SIGN-OFF` to `APPROVED - DEPLOYED` in `compliance/RTM.md`.
+       2. **Move release ticket** — move `compliance/pending-releases/RELEASE-TICKET-REQ-XXX.md` to `compliance/approved-releases/`. This prevents CI's `upload-evidence` job from treating the REQ as in-scope for subsequent releases.
+       3. **Verify portal approval** — confirm the DevAudit portal release record is in `released` status.
+       4. **Commit the close-out** — `git add compliance/RTM.md compliance/pending-releases/ compliance/approved-releases/ && git commit -m "compliance: [REQ-XXX] close out release — RTM updated to APPROVED - DEPLOYED, ticket moved to approved-releases/"`.
+       5. **Push the close-out commit** to `$INTEGRATION_BRANCH`.
+
+       These steps are mandatory — the native agent must not treat "PR merged" or "release marked Released" as completion without performing the close-out. Without moving the release ticket to `approved-releases/`, CI continues uploading evidence for the REQ on every subsequent release, polluting the portal's audit trail.
+     - **Update SDLC status sticky** to the terminal state: `bash scripts/update-sdlc-status.sh "$ISSUE_NUM" "Phase 5 complete — release marked Released; production smoke evidence uploaded; close-out committed (RTM → APPROVED - DEPLOYED, ticket → approved-releases/)" "Done — close issue + retire feature branch (sdlc-implementer halts)"`.
      - Close the issue.
      - If production smoke fails: do NOT mark as Released. **Delegate incident filing to `governance-doc-author` (devaudit-installer#210 §6c)** — invoke `Skill(name: "governance-doc-author", args: "Production smoke failure for REQ-XXX. File an incident issue with the `incident` label + `### Framework attribution` section (ISO29119.3.5.4 + SOC2.CC7.2), severity `blocker`. Include the production URL, git SHA, testCycleId (CI run ID), and smoke results in the issue body.")`. Page the on-call per the project's incident playbook, follow the rollback plan from the implementation plan. If the rollback also fails: update the sticky to "Phase 5 CRITICAL — production smoke failed AND rollback failed. Production is in a broken state. Operator action — page on-call immediately, engage hosting platform support, declare incident per the project's incident playbook. This is beyond the skill's scope." Do NOT attempt further automated remediation. **Update the sticky** to reflect the incident state: `… "Phase 5 BLOCKED — production smoke failed; INCIDENT issue #N filed" "Operator action — read INCIDENT #N + execute rollback per plan"`.
 
    - **Changes requested** → run change-request loop:
      - Fetch change-request comments from the PR (`gh pr view <M> --comments`) and from the portal release page.
-     - **Classify the change request (devaudit-installer#210 §6b):** Assess whether the change request is a **defect** (the implementation doesn't match the AC — the reviewer found a bug) or a **scope change** (the AC itself needs amendment — the reviewer wants new behaviour the AC didn't specify).
+     - **Classify the change request (devaudit-installer#210 §6b, devaudit-installer#212 Gap 6):** Assess whether the change request is a **defect** (the implementation doesn't match the AC — the reviewer found a bug), a **requirements gap** (the reviewer identified behaviour that should have been an AC but wasn't — the plan was incomplete, not the implementation), or a **scope change** (the reviewer wants new behaviour this REQ genuinely shouldn't deliver).
        - **If it's a defect:** Delegate to `e2e-test-engineer` to file the incident with the `incident` label + `### Framework attribution` section before fixing. Invoke `Skill(name: "e2e-test-engineer", args: "Phase 6 triage — UAT reviewer found defect in REQ-XXX. Change-request comment: <summary>. Triage and file application defects with the `incident` label + `### Framework attribution` section per the standard convention.")`. `e2e-test-engineer` returns with a summary of filed incidents. Then fix the defect in the same Phase 2 re-run. This ensures UAT-discovered defects produce `incident_report` evidence, closing `ISO29119.3.5.4` for the defect — not just silently fixing it.
+       - **If it's a requirements gap:** Trigger the [requirements gap flow](#requirements-gap-flow-devaudit-installer212) with the reviewer's feedback as the gap report. The operator decides: accept the gap (ship without the edge case), amend the ACs (add the edge case as a new AC, update plan + SRS, re-walk Phase 2-3), or file a follow-up REQ. If "amend" is chosen, the change-request iteration includes the new AC in the delta-plan section, `requirements-aligner` is re-invoked for the new AC, and the SRS is updated. Do NOT file an incident — the plan was incomplete, not the implementation buggy. Do NOT use the scope-expansion halt gate — this is a plan quality issue, not a scope creep request.
        - **If it's a scope change:** Use the existing scope-expansion halt gate (REQ-SKILL-IMPLEMENTER-019) — file a separate issue or amend the REQ scope. Do NOT file an incident — the AC itself needs amendment, not a defect fix.
      - Add a new `## Change-request iteration N` section to `compliance/plans/REQ-XXX/implementation-plan.md` describing what changed and why.
      - **Update the release ticket status** (`compliance/pending-releases/RELEASE-TICKET-REQ-XXX.md`): set `**Status:**` to `CHANGES REQUESTED — ITERATION N` when entering the iteration. Commit the ticket update alongside the delta-plan section in the same iteration commit.
@@ -569,6 +618,59 @@ Invoked separately by the user after UAT activity on the portal. Trigger: "resum
 
    - **UAT rejected** → halt. Post on the issue: "UAT rejected this release. Options: (a) close PR and re-plan from scratch, (b) escalate to a different reviewer, (c) appeal the rejection with new context." See [`references/change-request-loop.md`](./references/change-request-loop.md) §"If the change-request is a rejection" for details. Do not attempt to address — the reviewer has marked the release fundamentally broken. Wait for the user to decide.
 
+## Native agent responsibilities and re-invocation protocol (devaudit-installer#226)
+
+The `skill` tool is a **stateless instruction injection** — not a persistent sub-agent. When invoked, the skill's markdown is loaded into the native agent's context. The native agent executes the steps. But the skill has no persistent state, no execution monitoring, and no re-invoke triggers. The following protocol bridges this gap.
+
+### Native agent responsibilities
+
+The native agent (the AI coding assistant executing this skill) is responsible for:
+
+- **Command execution** — running `npx playwright test`, `npm run dev`, `mongod`, etc.
+- **Environment debugging** — port conflicts, stale locks, missing binaries, Playwright browser installs
+- **Browser inspection** — reading page snapshots, DOM state, error dialogs during E2E debugging
+- **External service interaction** — Railway deploy status, UAT health checks, DevAudit portal (human-only)
+- **Git operations** — merge conflicts, push retries, branch management
+
+The skill is responsible for workflow decisions, compliance checklists, and phase transitions. The native agent executes; the skill decides what to do next.
+
+### Re-invocation protocol
+
+After any **environment detour** — service startup failure, test debugging iteration loop, CI failure fix — the native agent must re-invoke this skill to get back on track:
+
+```
+Skill(name: "sdlc-implementer", args: "resume REQ-XXX — <detour description>, re-enter at Phase N")
+```
+
+The skill re-reads state from the filesystem and continues from where it left off. It is idempotent on re-entry:
+
+- Re-read `compliance/RTM.md` to confirm the REQ-XXX row exists and has a provenance stamp.
+- Re-read `compliance/evidence/REQ-XXX/` to see which artefacts already exist.
+- Check `git log` for commits already made on this branch.
+- Resume at the appropriate phase: if Phase 2 implementation is complete but Phase 3 artefacts are missing, resume at Phase 3 step 1.
+
+The native agent must NOT continue to the next phase (Phase 3 → Phase 4, Phase 2 → Phase 3) without re-invoking the skill. The only exception is the skill's own auto-continue steps (Phase 2 step 11) where the skill explicitly says it will continue to the next phase in the same turn.
+
+**PR merged to main ≠ done.** After the release PR is merged to `main`, the native agent must re-invoke the skill for Phase 5 close-out (see Phase 5 step 0 below). The merge is not the end of the workflow — post-merge compliance steps are mandatory.
+
+### Commit-scoping rule for SRS updates (devaudit-installer#226)
+
+When a commit is authored as part of REQ-XXX's SDLC flow, the commit subject must cite `[REQ-XXX]` — the **active REQ** driving the current SDLC flow — regardless of which other REQs the content touches. Other REQs may appear in the body for traceability, but never in the subject.
+
+**Correct:**
+```
+docs: [REQ-085] add SRS stubs for REQ-083/084/085 — order status revert, checkout separation, tab payment
+
+Ref: REQ-083, REQ-084
+```
+
+**Incorrect:**
+```
+docs: [REQ-083/084] update SRS with order status revert fix and checkout separation
+```
+
+The portal's commit scanner parses `REQ-XXX` tags from commit subjects within a PR's diff. Citing the wrong REQ in the subject causes the portal to associate out-of-scope REQs with the current release.
+
 ## Compliance constraints
 
 Hard rules — the skill's SKILL.md fails review if any of these are violated. Audited against ISO 29119, ISO 27001, SOC 2, GDPR, and the EU AI Act; details in [`references/compliance-constraints.md`](./references/compliance-constraints.md).