@metasession.co/devaudit-cli 0.1.71 → 0.1.72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.1.71",
+  "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.71",
+    "@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/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,7 +581,15 @@ 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"`.
 
@@ -570,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).

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

@@ -288,14 +288,18 @@ jobs:
           echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
           echo "Release version: ${VERSION}"
 
-      - name: Ensure release exists
+      - name: Check release exists (no creation — deferred to upload-evidence)
         if: env.DEVAUDIT_BASE_URL != ''
         run: |
+          # Release creation is deferred to the upload-evidence job (which
+          # runs after gates pass) so the portal never shows a release from
+          # a push where gates weren't verified (devaudit-installer#226).
+          # This step only checks whether the release already exists (e.g.
+          # created earlier by sdlc-implementer Phase 1 step 3).
           chmod +x scripts/upload-evidence.sh 2>/dev/null || true
-          # Create the release in DevAudit (no evidence yet — just registration)
           bash scripts/upload-evidence.sh \
             {{PROJECT_SLUG}} _compliance-docs release_registration README.md \
-            --release ${{ steps.version.outputs.version }} --create-release-if-missing \
+            --release ${{ steps.version.outputs.version }} \
             --environment uat --category planning \
             --git-sha ${{ github.sha }} --branch ${{ github.ref_name }} || true
 
@@ -438,6 +442,11 @@ jobs:
         if: env.DEVAUDIT_BASE_URL != ''
         run: |
           chmod +x scripts/upload-evidence.sh 2>/dev/null || true
+          # --create-release-if-missing is intentionally here (post-gate) rather
+          # than in register-release. This ensures the portal release record only
+          # appears after gates have run — even if gates failed, the release
+          # record is created here so failure evidence attaches to it.
+          # (devaudit-installer#226)
           FLAGS="--git-sha ${{ github.sha }} --ci-run-id ${{ github.run_id }} --branch ${{ github.ref_name }}"
           FLAGS="${FLAGS} --release ${{ needs.register-release.outputs.version }} --create-release-if-missing"
           FLAGS="${FLAGS} --environment uat"

package/sdlc/files/ci/compliance-evidence.yml.template

@@ -909,35 +909,43 @@ jobs:
 
               echo "  [INCIDENT] $TEST_NAME — filing with incident label"
 
-              ISSUE_BODY="## E2E Regression Failure — ${CLASSIFICATION}
+              # DevAudit-Installer#228 — heredoc to keep markdown content
+              # inside the YAML literal block scalar (0-indent continuation
+              # lines were terminating the block and ** was parsed as YAML
+              # alias references).
+              ISSUE_BODY=$(cat <<EOF
+              ## E2E Regression Failure — ${CLASSIFICATION}
 
-**Test name:** ${TEST_NAME}
-**Error message:**
-\`\`\`
-${ERROR_MSG}
-\`\`\`
+              **Test name:** ${TEST_NAME}
+              **Error message:**
+              \`\`\`
+              ${ERROR_MSG}
+              \`\`\`
 
-**Classification:** ${CLASSIFICATION}
-**Classification rationale:** ${RATIONALE}
+              **Classification:** ${CLASSIFICATION}
+              **Classification rationale:** ${RATIONALE}
 
-**testCycleId:** ${CI_RUN_ID}
-**Workflow run:** ${WORKFLOW_URL}
-**Git SHA:** ${GIT_SHA}
+              **testCycleId:** ${CI_RUN_ID}
+              **Workflow run:** ${WORKFLOW_URL}
+              **Git SHA:** ${GIT_SHA}
 
-This regression was detected and classified by the autonomous E2E Regression CI run. A human should confirm the classification, adjust severity if needed, and close once fixed. The \`incident\` label ensures an \`incident_report\` will be generated on close.
+              This regression was detected and classified by the autonomous E2E Regression CI run. A human should confirm the classification, adjust severity if needed, and close once fixed. The \`incident\` label ensures an \`incident_report\` will be generated on close.
 
-### Framework attribution
+              ### Framework attribution
 
-This defect, once closed with the \`incident\` label, will be auto-exported as \`incident_report\` evidence and attribute to:
+              This defect, once closed with the \`incident\` label, will be auto-exported as \`incident_report\` evidence and attribute to:
 
-- [x] \`ISO29119.3.5.4\` (baseline — every incident_report)
-- [x] \`SOC2.CC7.2\` — ops impact: a regression in production-adjacent code is an ops concern
-- [ ] \`GDPR.Art-33\` — personal data scope: <REPLACE — yes/no>
-- [ ] \`GDPR.Art-34\` — data-subject notification required: <REPLACE — yes/no>
-- [ ] \`EUAIA.Art-9 / Art-14 / Art-15\` — AI failure: <REPLACE — yes/no, which article(s)>
+              - [x] \`ISO29119.3.5.4\` (baseline — every incident_report)
+              - [x] \`SOC2.CC7.2\` — ops impact: a regression in production-adjacent code is an ops concern
+              - [ ] \`GDPR.Art-33\` — personal data scope: <REPLACE — yes/no>
+              - [ ] \`GDPR.Art-34\` — data-subject notification required: <REPLACE — yes/no>
+              - [ ] \`EUAIA.Art-9 / Art-14 / Art-15\` — AI failure: <REPLACE — yes/no, which article(s)>
 
-Once closed, the \`incident-export.yml\` workflow exports this issue's body to \`compliance/governance/incident-report-<N>.md\`.
-"
+              Once closed, the \`incident-export.yml\` workflow exports this issue's body to \`compliance/governance/incident-report-<N>.md\`.
+              EOF
+              )
+              # Strip the 14-space heredoc indentation so the issue body is clean.
+              ISSUE_BODY=$(echo "$ISSUE_BODY" | sed 's/^              //')
 
               gh issue create \
                 --title "[REGRESSION] ${TEST_NAME}" \
@@ -947,23 +955,27 @@ Once closed, the \`incident-export.yml\` workflow exports this issue's body to \
             elif [ "$FILE_LABEL" = "test-bug" ]; then
               echo "  [TEST-BUG] $TEST_NAME — filing with test-bug label (no incident label)"
 
-              ISSUE_BODY="## E2E Regression Failure — ${CLASSIFICATION}
+              # DevAudit-Installer#228 — heredoc (see comment above).
+              ISSUE_BODY=$(cat <<EOF
+              ## E2E Regression Failure — ${CLASSIFICATION}
 
-**Test name:** ${TEST_NAME}
-**Error message:**
-\`\`\`
-${ERROR_MSG}
-\`\`\`
+              **Test name:** ${TEST_NAME}
+              **Error message:**
+              \`\`\`
+              ${ERROR_MSG}
+              \`\`\`
 
-**Classification:** ${CLASSIFICATION}
-**Classification rationale:** ${RATIONALE}
+              **Classification:** ${CLASSIFICATION}
+              **Classification rationale:** ${RATIONALE}
 
-**testCycleId:** ${CI_RUN_ID}
-**Workflow run:** ${WORKFLOW_URL}
-**Git SHA:** ${GIT_SHA}
+              **testCycleId:** ${CI_RUN_ID}
+              **Workflow run:** ${WORKFLOW_URL}
+              **Git SHA:** ${GIT_SHA}
 
-This failure appears to be a ${CLASSIFICATION} (not an application defect). A human should confirm and fix the ${CLASSIFICATION}, not the application. Filed with the \`test-bug\` label — this does NOT produce \`incident_report\` evidence.
-"
+              This failure appears to be a ${CLASSIFICATION} (not an application defect). A human should confirm and fix the ${CLASSIFICATION}, not the application. Filed with the \`test-bug\` label — this does NOT produce \`incident_report\` evidence.
+              EOF
+              )
+              ISSUE_BODY=$(echo "$ISSUE_BODY" | sed 's/^              //')
 
               gh issue create \
                 --title "[TEST-BUG] ${TEST_NAME}" \
@@ -974,13 +986,19 @@ This failure appears to be a ${CLASSIFICATION} (not an application defect). A hu
           done <<< "$FAILING_TESTS"
 
           # --- Post summary comment on the workflow run ---
-          SUMMARY="E2E Regression triage summary:
-- Flakes (not filed): ${FLAKE_COUNT}
-- Test bugs (filed without incident label): ${TEST_BUG_COUNT}
-- Seed-data gaps (filed without incident label): ${SEED_GAP_COUNT}
-- Visual diffs intended (not filed): ${VISUAL_INTENDED_COUNT}
-- Visual diffs unintended (filed as incident): ${VISUAL_UNINTENDED_COUNT}
-- Application defects (filed as incident): ${APP_DEFECT_COUNT}"
+          # DevAudit-Installer#228 — heredoc to keep continuation lines
+          # inside the YAML literal block scalar.
+          SUMMARY=$(cat <<EOF
+          E2E Regression triage summary:
+          - Flakes (not filed): ${FLAKE_COUNT}
+          - Test bugs (filed without incident label): ${TEST_BUG_COUNT}
+          - Seed-data gaps (filed without incident label): ${SEED_GAP_COUNT}
+          - Visual diffs intended (not filed): ${VISUAL_INTENDED_COUNT}
+          - Visual diffs unintended (filed as incident): ${VISUAL_UNINTENDED_COUNT}
+          - Application defects (filed as incident): ${APP_DEFECT_COUNT}
+          EOF
+          )
+          SUMMARY=$(echo "$SUMMARY" | sed 's/^          //')
 
           echo "$SUMMARY"
           # Post summary as a workflow run comment (using gh api).

package/sdlc/files/ci/incident-export.yml.template

@@ -198,15 +198,25 @@ jobs:
             MERGE_SHA=$(echo "$CLOSING_PRS" | jq -r '.mergeCommit.oid // .mergeCommit // "unknown"' 2>/dev/null | head -1)
             PR_TITLE=$(echo "$CLOSING_PRS" | jq -r '.title' 2>/dev/null | head -1)
             PR_NUM=$(echo "$CLOSING_PRS" | jq -r '.number' 2>/dev/null | head -1)
-            CONTAINMENT="- **Containment actions:** auto-derived from PR #${PR_NUM}: ${PR_TITLE}
-- **Mitigation deployed:** [PR #${PR_NUM}](${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/pull/${PR_NUM}) (${MERGE_SHA})
-- **Recovery actions:** REPLACE — if additional recovery steps were taken
-- **Verification that the incident is resolved:** REPLACE — how was the fix verified (re-run E2E, manual check, etc.)"
+            # DevAudit-Installer#228 — heredoc to keep markdown content
+            # inside the YAML literal block scalar.
+            CONTAINMENT=$(cat <<EOF
+            - **Containment actions:** auto-derived from PR #${PR_NUM}: ${PR_TITLE}
+            - **Mitigation deployed:** [PR #${PR_NUM}](${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/pull/${PR_NUM}) (${MERGE_SHA})
+            - **Recovery actions:** REPLACE — if additional recovery steps were taken
+            - **Verification that the incident is resolved:** REPLACE — how was the fix verified (re-run E2E, manual check, etc.)
+            EOF
+            )
+            CONTAINMENT=$(echo "$CONTAINMENT" | sed 's/^            //')
           else
-            CONTAINMENT="- **Containment actions:** REPLACE — no linked PR found
-- **Mitigation deployed:** REPLACE
-- **Recovery actions:** REPLACE
-- **Verification that the incident is resolved:** REPLACE"
+            CONTAINMENT=$(cat <<EOF
+            - **Containment actions:** REPLACE — no linked PR found
+            - **Mitigation deployed:** REPLACE
+            - **Recovery actions:** REPLACE
+            - **Verification that the incident is resolved:** REPLACE
+            EOF
+            )
+            CONTAINMENT=$(echo "$CONTAINMENT" | sed 's/^            //')
           fi
 
           # §4g — Lessons learned: scan comments for follow-up issue references.

package/sdlc/files/stacks/node/hooks/pre-push

@@ -1,9 +1,21 @@
 #!/usr/bin/env bash
-# Husky pre-push hook — runs TypeScript check as a fast gate before push.
-# The full test suite (E2E, SAST, dependency audit) runs in CI.
+# Husky pre-push hook — fast gates + E2E evidence + skill-invocation sentinel + compliance validator.
+#
+# Runs four checks before allowing a push:
+# 1. TypeScript check (fast gate)
+# 2. E2E evidence check — if UI-facing files changed, verify Playwright ran
+# 3. Skill-invocation sentinel — if feat/fix/refactor/perf commits present,
+#    verify sdlc-implementer was invoked
+# 4. Compliance artifact validation — if feat/fix/refactor/perf commits present,
+#    run validate-compliance-artifacts.sh to catch missing evidence files
+#
+# Bypass with --no-verify (last resort, not a habit).
 #
 # Install: cp this file to .husky/pre-push && chmod +x .husky/pre-push
 
+set -euo pipefail
+
+# ── 1. TypeScript check ──────────────────────────────────────────────
 echo "Pre-push: running TypeScript check..."
 npx tsc --noEmit
 if [ $? -ne 0 ]; then
@@ -13,3 +25,107 @@ if [ $? -ne 0 ]; then
   exit 1
 fi
 echo "Pre-push: TypeScript check passed."
+
+# ── 2. E2E evidence check (devaudit-installer#226) ───────────────────
+# Only fires if UI-facing files are in the push. Checks for either
+# playwright-report/ directory or .e2e-gate-passed sentinel (written by
+# e2e-test-engineer after a successful run).
+INTEGRATION_BRANCH=$(jq -r '.integration_branch // "develop"' sdlc-config.json 2>/dev/null || echo "develop")
+
+# Read stdin to get the pushed refs (husky pre-push protocol)
+while read -r local_ref local_sha remote_ref remote_sha; do
+  # Check if pushing to the integration branch
+  if [[ "$remote_ref" != *"refs/heads/$INTEGRATION_BRANCH" ]]; then
+    continue
+  fi
+
+  # Determine the commit range being pushed
+  if [ "$remote_sha" = "0000000000000000000000000000000000000000" ]; then
+    RANGE="$local_sha"
+  else
+    RANGE="${remote_sha}..${local_sha}"
+  fi
+
+  # Check for UI-facing files in the push
+  UI_FILES=$(git diff --name-only "$RANGE" -- 'app/**/*.tsx' 'src/**/*.tsx' 'pages/**/*.tsx' 'app/**/*.jsx' 'src/**/*.jsx' 'pages/**/*.jsx' 2>/dev/null || true)
+
+  if [ -n "$UI_FILES" ]; then
+    E2E_PASSED=false
+    if [ -f .e2e-gate-passed ]; then
+      E2E_PASSED=true
+    elif [ -d playwright-report ] && [ "$(find playwright-report -type f -newer .git/HEAD 2>/dev/null | head -1)" ]; then
+      E2E_PASSED=true
+    fi
+
+    if [ "$E2E_PASSED" = "false" ]; then
+      echo ""
+      echo "ERROR: E2E gate was not run before pushing."
+      echo "       UI-facing files changed in this push:"
+      echo "$UI_FILES" | sed 's/^/         /'
+      echo ""
+      echo "       Run 'npx playwright test' (or invoke e2e-test-engineer) before pushing."
+      echo "       Bypass with --no-verify (last resort, not a habit)."
+      exit 1
+    fi
+    echo "Pre-push: E2E evidence check passed."
+  fi
+done
+
+# ── 3. Skill-invocation sentinel (devaudit-installer#226) ────────────
+# If feat/fix/refactor/perf commits are in the push, verify the
+# sdlc-implementer skill was invoked (writes .sdlc-implementer-invoked).
+# Housekeeping types (docs/chore/ci/build/test/revert) are exempt.
+TRACKED_TYPES='^(feat|fix|refactor|perf)(\(.+\))?!?:'
+HAS_TRACKED=false
+
+while read -r local_ref local_sha remote_ref remote_sha; do
+  if [[ "$remote_ref" != *"refs/heads/$INTEGRATION_BRANCH" ]]; then
+    continue
+  fi
+  if [ "$remote_sha" = "0000000000000000000000000000000000000000" ]; then
+    RANGE="$local_sha"
+  else
+    RANGE="${remote_sha}..${local_sha}"
+  fi
+  COMMITS=$(git log "$RANGE" --format='%s' 2>/dev/null || true)
+  if echo "$COMMITS" | grep -qE "$TRACKED_TYPES"; then
+    HAS_TRACKED=true
+  fi
+done
+
+if [ "$HAS_TRACKED" = "true" ]; then
+  if [ ! -f .sdlc-implementer-invoked ]; then
+    echo ""
+    echo "ERROR: sdlc-implementer skill was not invoked."
+    echo "       This push contains feat/fix/refactor/perf commits which require"
+    echo "       the SDLC skill flow. Invoke sdlc-implementer to drive the process,"
+    echo "       or use --no-verify to bypass (not recommended — CI will also check"
+    echo "       RTM provenance via validate-commits.sh)."
+    exit 1
+  fi
+  echo "Pre-push: skill-invocation sentinel check passed."
+fi
+
+# ── 4. Compliance artifact validation (devaudit-installer#226) ──────
+# If feat/fix/refactor/perf commits are in the push, run
+# validate-compliance-artifacts.sh to catch missing test-scope.md,
+# test-plan.md, implementation-plan.md in compliance/evidence/.
+# Reuses HAS_TRACKED from check 3.
+if [ "$HAS_TRACKED" = "true" ]; then
+  if [ -f scripts/validate-compliance-artifacts.sh ]; then
+    echo "Pre-push: running compliance artifact validation..."
+    if ! bash scripts/validate-compliance-artifacts.sh "origin/$INTEGRATION_BRANCH"; then
+      echo ""
+      echo "ERROR: Compliance artifact validation failed."
+      echo "       Missing or incomplete artifacts in compliance/evidence/."
+      echo "       Run 'bash scripts/validate-compliance-artifacts.sh' locally to see details."
+      echo "       Bypass with --no-verify (last resort, not a habit)."
+      exit 1
+    fi
+    echo "Pre-push: compliance artifact validation passed."
+  else
+    echo "Pre-push: compliance artifact validation skipped (script not found)."
+  fi
+fi
+
+echo "Pre-push: all checks passed."