@metasession.co/devaudit-cli 0.1.10 → 0.1.12

package/package.json

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

package/sdlc/ai-rules/INSTRUCTIONS-SDLC.md

@@ -15,6 +15,12 @@ Detailed workflow instructions are in this project's `SDLC/` directory. Read the
 
 When a workflow step requires detailed commands or templates, read the full workflow file rather than relying on the summary below.
 
+### Entry point: the `sdlc-implementer` skill
+
+The default way to implement a tracked change is the **`sdlc-implementer`** skill (`.claude/skills/sdlc-implementer/SKILL.md`): give it one GitHub issue and it runs Stage 1 (classify risk, assign the next `REQ-XXX`, write the implementation plan, update `RTM.md`) through Stage 4 (PR + UAT review), delegating all end-to-end / visual test work to `e2e-test-engineer`. **Do NOT hand-roll implementation outside this flow** — every change starts from a requirement, which starts from an issue. The only exceptions are trivial housekeeping (docs, formatting, dependency bumps, CI tweaks).
+
+**This is enforced, not just advised.** `feat` / `fix` / `refactor` / `perf` commits that cite no requirement (`[REQ-XXX]` in the subject or a `Ref: REQ-XXX` trailer) are **rejected** locally by the commit-msg hook (commitlint) and at PR CI by `validate-commits.sh` (which `--no-verify` cannot skip). So implementation work cannot reach `develop` without a requirement — which is also what keeps release labels correct (the version-deriver only falls back to a bare date for genuine housekeeping, never for real feature work). Housekeeping commit types remain exempt.
+
 ### Before ANY Code Change
 
 1. Ask: "Which GitHub Issue is this for?" before writing code. Fetch it with `gh issue view NNN`.

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

@@ -126,6 +126,8 @@ 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.
+
 **4a. Review the test plan for E2E items:**
 ```bash
 cat compliance/evidence/REQ-XXX/test-plan.md

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

@@ -399,7 +399,7 @@ If it fails — typically a stale `devaudit.base_url`, a revoked `DEVAUDIT_API_K
 **Skip this step entirely if any of these are true:**
 
 - Project's `sdlc-config.json` has `uat.enabled: false` — meaning the project has no deployed UAT environment configured (internal services, retroactive-compliance pickups, etc.).
-- Requirement's risk class is **not** listed in project's `uat.required_risk_classes` (defaults: `payment`, `destructive_migration`, `realtime`, `physical_ux`). Text-only fixes, internal refactors, low-risk UI tweaks carry none of these and skip UAT-env verification.
+- Requirement's risk class is **not** listed in project's `uat.required_risk_classes` (defaults: `payment`, `destructive_migration`, `realtime`, `physical_ux`). Text-only fixes, internal refactors, low-risk UI tweaks carry none of these and skip UAT-env verification. **Wildcard:** if `required_risk_classes` contains `"*"`, every requirement requires UAT-env verification regardless of risk class — use this for projects that deploy `develop` to a UAT environment and exercise every release there before promotion.
 
 When skipped, proceed directly to Step 11.
 
@@ -407,6 +407,8 @@ When skipped, proceed directly to Step 11.
 
 When this step DOES apply, the develop branch's auto-deploy to UAT must complete first. **Wait for the deployment to complete**, then verify the change works in the UAT environment.
 
+> **Automated e2e shrinks this step — it does not delete it.** When a requirement's acceptance criteria are covered by **passing CI e2e tests** authored with the `e2e-test-engineer` skill (each AC proven by an `evidenceShot`, run via the report-only authenticated-e2e gate — see `sdlc-config.json` `e2e_projects` / `e2e_seed_command`), those ACs are already exercised against the running app on every push. For those ACs, this step is **not** a full manual re-click of every criterion: it reduces to a **light manual smoke** on the deployed UAT environment — confirm the build is live, the changed area loads, and spot-check anything the e2e couldn't reach (real third-party integrations, environment-specific config, payment sandboxes). Record which ACs were discharged by automated e2e vs. exercised manually. ACs **not** covered by a passing e2e test still need full manual verification here.
+
 #### WAIT CHECKPOINT: Confirm CI + Deployment Complete
 
 Before UAT verification, confirm BOTH CI and deployment are complete:

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

@@ -52,6 +52,28 @@ while IFS= read -r sha; do
     continue
   fi
 
+  # Requirement traceability: implementation commits (feat/fix/refactor/perf)
+  # MUST cite a requirement — [REQ-XXX] in the subject or a Ref: REQ-XXX
+  # trailer. Housekeeping types (docs/chore/ci/build/test/compliance/revert)
+  # are exempt. Mirrors the commitlint rule; this is the PR-CI half that
+  # `--no-verify` can't skip. Work starts from a requirement (which starts
+  # from an issue) — use the sdlc-implementer skill to assign one.
+  TYPE=$(echo "$SUBJECT" | grep -oE '^[a-z]+' || true)
+  case "$TYPE" in
+    feat|fix|refactor|perf)
+      if ! echo "$SUBJECT" | grep -qP '\[REQ-\d{3,}\]' \
+        && ! echo "$BODY" | grep -qiP 'Ref:\s*REQ-\d{3,}'; then
+        echo "ERROR [$SHORT]: '$TYPE' is an implementation commit but cites no requirement."
+        echo "       Add [REQ-XXX] to the subject or a 'Ref: REQ-XXX' trailer. Start work"
+        echo "       from a requirement via the sdlc-implementer skill (it assigns the REQ"
+        echo "       from the originating issue in Phase 1)."
+        FAILED=$((FAILED + 1))
+        EXIT_CODE=1
+        continue
+      fi
+      ;;
+  esac
+
   # Check Co-Authored-By on commits that touch code files
   CODE_FILES=$(git diff-tree --no-commit-id --name-only -r "$sha" -- '*.ts' '*.tsx' '*.js' '*.jsx' '*.py' 2>/dev/null || true)
   if [ -n "$CODE_FILES" ]; then

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

@@ -150,7 +150,7 @@ jobs:
           PLAYWRIGHT_HTML_REPORTER_OPEN: never
           PLAYWRIGHT_JSON_OUTPUT_NAME: e2e-results.json
         run: npx playwright test --project={{E2E_PROJECT}} --reporter=json,html
-
+{{E2E_AUTHENTICATED_STEP}}
       # ── Gate 5: Build ──
 
       - name: Build Check
@@ -169,6 +169,7 @@ jobs:
             sast-results.json
             dependency-audit.json
             e2e-results.json
+            e2e-auth-results.json
             playwright-report/
             coverage/coverage-summary.json
           retention-days: 90

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

@@ -20,6 +20,7 @@
 name: Compliance Evidence Upload
 
 on:
+  workflow_dispatch:
   push:
     branches: [develop]
     paths:
@@ -98,9 +99,16 @@ jobs:
         if: steps.resolve.outputs.skip != 'true'
         run: |
           chmod +x scripts/upload-evidence.sh 2>/dev/null || true
+          # Common flags WITHOUT --release. Each upload appends its OWN
+          # --release so per-requirement artifacts land in their own release
+          # record (version = REQ-ID) instead of all collapsing into whichever
+          # single version the triggering commit derived. DevAudit #135 follow-
+          # up: this fixes release *attribution* (not just duplication) — an
+          # untagged docs commit must not sweep every in-scope REQ into a date
+          # release. Note: upload-evidence.sh keeps the LAST --release seen.
           FLAGS="--git-sha ${{ github.sha }} --ci-run-id ${{ github.run_id }} --branch ${{ github.ref_name }}"
-          FLAGS="${FLAGS} --release ${{ steps.version.outputs.version }} --create-release-if-missing"
-          FLAGS="${FLAGS} --environment uat"
+          FLAGS="${FLAGS} --create-release-if-missing --environment uat"
+          DERIVED_RELEASE="${{ steps.version.outputs.version }}"
 
           # Upload compliance docs (planning category)
           for DOC in compliance/RTM.md compliance/test-plan.md compliance/test-cases.md compliance/test-summary-report.md; do
@@ -108,7 +116,7 @@ jobs:
               echo "Uploading: $(basename "$DOC")"
               bash scripts/upload-evidence.sh \
                 {{PROJECT_SLUG}} _compliance-docs compliance_document "$DOC" \
-                --category planning ${FLAGS} || echo "Warning: Failed to upload $(basename "$DOC")"
+                --category planning ${FLAGS} --release "${DERIVED_RELEASE}" || echo "Warning: Failed to upload $(basename "$DOC")"
             fi
           done
 
@@ -116,10 +124,20 @@ jobs:
           if [ -d "compliance/pending-releases" ]; then
             for TICKET in compliance/pending-releases/*.md; do
               [ -f "$TICKET" ] || continue
-              echo "Uploading: $(basename "$TICKET")"
+              # A RELEASE-TICKET-REQ-XXX.md belongs to that requirement's
+              # release record; any other ticket rides the derived release.
+              TICKET_BASE=$(basename "$TICKET" .md)
+              case "$TICKET_BASE" in
+                RELEASE-TICKET-REQ-*)
+                  TICKET_REQ="${TICKET_BASE#RELEASE-TICKET-}"
+                  TICKET_OWNER="$TICKET_REQ"; TICKET_RELEASE="$TICKET_REQ" ;;
+                *)
+                  TICKET_OWNER="_compliance-docs"; TICKET_RELEASE="$DERIVED_RELEASE" ;;
+              esac
+              echo "Uploading: $(basename "$TICKET") -> release ${TICKET_RELEASE}"
               bash scripts/upload-evidence.sh \
-                {{PROJECT_SLUG}} _compliance-docs compliance_document "$TICKET" \
-                --category release_artifact ${FLAGS} || echo "Warning: Failed to upload $(basename "$TICKET")"
+                {{PROJECT_SLUG}} "${TICKET_OWNER}" compliance_document "$TICKET" \
+                --category release_artifact ${FLAGS} --release "${TICKET_RELEASE}" || echo "Warning: Failed to upload $(basename "$TICKET")"
             done
           fi
 
@@ -152,7 +170,7 @@ jobs:
                 echo "Uploading: ${REQ_ID}/$(basename "$ARTIFACT")"
                 bash scripts/upload-evidence.sh \
                   {{PROJECT_SLUG}} "${REQ_ID}" compliance_document "$ARTIFACT" \
-                  --category planning ${FLAGS} || echo "Warning: Failed to upload $(basename "$ARTIFACT")"
+                  --category planning ${FLAGS} --release "${REQ_ID}" || echo "Warning: Failed to upload $(basename "$ARTIFACT")"
               done
             done
           fi

package/sdlc/files/ci/post-deploy-prod.yml.template

@@ -6,16 +6,27 @@
 # Production verification is READ-ONLY.
 # No E2E tests, no database operations, no API mutations.
 #
+# Promotes EVERY in-scope release (each requirement with a pending release
+# ticket), not just the first REQ found — a develop→main PR that bundles
+# several requirements must advance all of them to the terminal status, else
+# the requirements not picked first stay stuck at uat_approved with no
+# production evidence. `workflow_dispatch` allows re-running / catching up a
+# single release via the `release` input.
+#
 # In sdlc-v1.22.0+ the terminal release status is configurable via
 # sdlc-config.json `production_review.terminal_status`:
 #   - "prod_review" (default, Option A) — stop at prod_review; human in the
-#     portal clicks "Approve Production" then "Mark as Released" for an
-#     explicit audit trail. Closes #138.
+#     portal clicks "Approve Production" then "Mark as Released".
 #   - "released" (Option B) — preserves v1.21.x auto-release behaviour.
 
 name: Post-Deploy Production Evidence
 
 on:
+  workflow_dispatch:
+    inputs:
+      release:
+        description: 'Optional REQ-XXX / version to promote (blank = all in-scope from pending release tickets).'
+        required: false
   push:
     branches: [main]
 
@@ -30,11 +41,12 @@ jobs:
       PROJECT_SLUG: {{PROJECT_SLUG}}
       GIT_SHA: ${{ github.sha }}
       CI_RUN: ${{ github.run_id }}
+      RELEASE_INPUT: ${{ github.event.inputs.release }}
 
     steps:
       - uses: actions/checkout@v4
         with:
-          fetch-depth: 0   # full history so the merged commits' REQ tags are readable
+          fetch-depth: 0   # full history so merged commits' REQ tags are readable
 
       - name: Resolve DevAudit base URL and post-deploy terminal status
         run: |
@@ -75,37 +87,31 @@ jobs:
           echo "DEVAUDIT_BASE_URL=${BASE%/}" >> "$GITHUB_ENV"
           echo "TERMINAL_STATUS=${TERMINAL_STATUS}" >> "$GITHUB_ENV"
 
-      - name: Resolve current release
-        id: release
+      - name: Resolve in-scope releases
         run: |
-          # Resolve the release being PROMOTED — the same REQ the dev/UAT
-          # pipeline versioned (ci.yml / compliance-evidence.yml use
-          # derive-release-version.sh → REQ-XXX). The merge commit itself
-          # carries no REQ tag, so derive it from the commits merged into
-          # this push ([REQ-XXX] subject tags / Ref: lines), and only fall
-          # back to a bare date when the consumer uses date-versioned
-          # releases. Without this, a REQ-versioned release never converges:
-          # production evidence + the prod-review advance land on a phantom
-          # date release while the real REQ release stays uat_approved.
-          REQ=$(git log "${{ github.event.before }}..${{ github.sha }}" --format='%s%n%b' 2>/dev/null \
-                | grep -oiE '\[REQ-[0-9]+\]|Ref:[[:space:]]*REQ-[0-9]+' \
-                | grep -oiE 'REQ-[0-9]+' | head -1 | tr '[:lower:]' '[:upper:]' || true)
-          if [ -n "$REQ" ]; then
-            PREFIX="$REQ"
+          # The releases being PROMOTED are the requirements with a pending
+          # release ticket (the same set the dev/UAT pipeline versioned via
+          # derive-release-version.sh → REQ-XXX). A bundled develop→main PR
+          # carries several; promote ALL of them, not just the first. A manual
+          # dispatch can target one via the `release` input. Fall back to a
+          # bare date for date-versioned (ticketless) releases.
+          if [ -n "${RELEASE_INPUT}" ]; then
+            REQS="${RELEASE_INPUT}"
           else
-            PREFIX="v$(date +%Y.%m.%d)"
-          fi
-          echo "Resolving release for version prefix: ${PREFIX}"
-          RESP=$(curl -s -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
-            "${BASE}/api/ci/releases/resolve?projectSlug=${PROJECT_SLUG}&versionPrefix=${PREFIX}")
-          VERSION=$(echo "$RESP" | jq -r '.latest.version // empty')
-          if [ -z "$VERSION" ]; then
-            VERSION="${PREFIX}"
+            REQS=""
+            if [ -d compliance/pending-releases ]; then
+              for T in compliance/pending-releases/RELEASE-TICKET-REQ-*.md; do
+                [ -f "$T" ] || continue
+                REQS="${REQS} $(basename "$T" .md | sed 's/^RELEASE-TICKET-//')"
+              done
+            fi
+            REQS=$(echo ${REQS} | tr ' ' '\n' | sort -u | tr '\n' ' ' | sed 's/[[:space:]]*$//')
+            if [ -z "${REQS}" ]; then
+              REQS="v$(date +%Y.%m.%d)"
+            fi
           fi
-          RELEASE_ID=$(echo "$RESP" | jq -r '.latest.id // empty')
-          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
-          echo "release_id=${RELEASE_ID}" >> "$GITHUB_OUTPUT"
-          echo "Release version: ${VERSION}"
+          echo "In-scope releases to promote: ${REQS}"
+          echo "REQS=${REQS}" >> "$GITHUB_ENV"
 
       - name: Wait for production deployment
         run: |
@@ -142,63 +148,57 @@ jobs:
           }
           RESULTS_EOF
 
-      - name: Upload production evidence
-        run: |
-          chmod +x scripts/upload-evidence.sh 2>/dev/null || true
-          VERSION="${{ steps.release.outputs.version }}"
-          FLAGS="--release ${VERSION} --create-release-if-missing --environment production --category test_report"
-          FLAGS="${FLAGS} --git-sha ${GIT_SHA} --ci-run-id ${CI_RUN} --branch main"
-          if [ -f prod-smoke-results.json ]; then
-            bash scripts/upload-evidence.sh \
-              "${PROJECT_SLUG}" "_compliance-docs" "test_report" prod-smoke-results.json \
-              ${FLAGS} || echo "Warning: Failed to upload smoke results"
-          fi
-
-      - name: Upload release ticket to production
+      - name: Promote in-scope releases (evidence + status)
         run: |
-          # Submit-for-production-review requires a release ticket (release_artifact)
-          # in the PRODUCTION environment — the dev/UAT pipeline only uploads it to
-          # uat. Carry the promoted release's ticket forward to production so the
-          # production release is self-contained and the prod-review gate passes.
           chmod +x scripts/upload-evidence.sh 2>/dev/null || true
-          VERSION="${{ steps.release.outputs.version }}"
-          FLAGS="--release ${VERSION} --create-release-if-missing --environment production --category release_artifact"
-          FLAGS="${FLAGS} --git-sha ${GIT_SHA} --ci-run-id ${CI_RUN} --branch main"
-          TICKET=""
-          for DIR in compliance/pending-releases compliance/approved-releases; do
-            if [ -f "${DIR}/RELEASE-TICKET-${VERSION}.md" ]; then
-              TICKET="${DIR}/RELEASE-TICKET-${VERSION}.md"
-              break
+          PROMOTED=0
+          for PREFIX in ${REQS}; do
+            echo "=== Promoting ${PREFIX} ==="
+            RESP=$(curl -s -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+              "${BASE}/api/ci/releases/resolve?projectSlug=${PROJECT_SLUG}&versionPrefix=${PREFIX}")
+            VERSION=$(echo "$RESP" | jq -r '.latest.version // empty')
+            [ -z "$VERSION" ] && VERSION="${PREFIX}"
+            RELEASE_ID=$(echo "$RESP" | jq -r '.latest.id // empty')
+            # Production smoke evidence (whole-app health) attached to this release.
+            if [ -f prod-smoke-results.json ]; then
+              bash scripts/upload-evidence.sh \
+                "${PROJECT_SLUG}" "${VERSION}" test_report prod-smoke-results.json \
+                --release "${VERSION}" --create-release-if-missing --environment production \
+                --category test_report --git-sha "${GIT_SHA}" --ci-run-id "${CI_RUN}" --branch main \
+                || echo "Warning: smoke upload failed for ${VERSION}"
+            fi
+            # Carry the release ticket into the production environment so the
+            # prod-review gate is self-contained.
+            TICKET=""
+            for DIR in compliance/pending-releases compliance/approved-releases; do
+              if [ -f "${DIR}/RELEASE-TICKET-${VERSION}.md" ]; then
+                TICKET="${DIR}/RELEASE-TICKET-${VERSION}.md"; break
+              fi
+            done
+            if [ -n "$TICKET" ]; then
+              bash scripts/upload-evidence.sh \
+                "${PROJECT_SLUG}" "${VERSION}" compliance_document "$TICKET" \
+                --release "${VERSION}" --create-release-if-missing --environment production \
+                --category release_artifact --git-sha "${GIT_SHA}" --ci-run-id "${CI_RUN}" --branch main \
+                || echo "Warning: ticket upload failed for ${VERSION}"
+            else
+              echo "No RELEASE-TICKET-${VERSION}.md found — skipping ticket (date-versioned or archived)."
+            fi
+            # Advance status (idempotent — re-PATCHing an already-promoted release is a no-op).
+            if [ -n "$RELEASE_ID" ]; then
+              curl -s -o /dev/null -w "  ${VERSION} status patch: HTTP %{http_code}\n" \
+                -X PATCH "${BASE}/api/ci/releases/${RELEASE_ID}" \
+                -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+                -H "Content-Type: application/json" \
+                -d "{\"status\":\"${TERMINAL_STATUS}\"}"
+              echo "  ${VERSION} → ${TERMINAL_STATUS}"
+              PROMOTED=$((PROMOTED + 1))
+            else
+              echo "::warning::No release_id resolved for ${PREFIX} — skipping status patch"
             fi
           done
-          if [ -n "$TICKET" ]; then
-            echo "Uploading release ticket to production: $TICKET"
-            bash scripts/upload-evidence.sh \
-              "${PROJECT_SLUG}" "_compliance-docs" compliance_document "$TICKET" \
-              ${FLAGS} || echo "Warning: Failed to upload release ticket to production"
-          else
-            echo "No RELEASE-TICKET-${VERSION}.md in pending-/approved-releases — skipping (date-versioned release or ticket archived)."
-          fi
-
-      - name: Advance release status (post-deploy)
-        run: |
-          RELEASE_ID="${{ steps.release.outputs.release_id }}"
-          if [ -z "$RELEASE_ID" ]; then
-            echo "::warning::No release_id resolved — skipping status patch"
-            exit 0
+          echo "Promoted ${PROMOTED} release(s) to ${TERMINAL_STATUS}."
+          if [ "${TERMINAL_STATUS}" = "prod_review" ]; then
+            echo "Next: a human in the portal clicks 'Approve Production' then 'Mark as Released' for each."
+            echo "Audit trail captures both events with reviewer identity per compliance/risk-register.md."
           fi
-          curl -s -o /dev/null -w "Release status patch: HTTP %{http_code}\n" \
-            -X PATCH "${BASE}/api/ci/releases/${RELEASE_ID}" \
-            -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
-            -H "Content-Type: application/json" \
-            -d "{\"status\":\"${TERMINAL_STATUS}\"}"
-          case "$TERMINAL_STATUS" in
-            prod_review)
-              echo "Release ${{ steps.release.outputs.version }} → prod_review."
-              echo "Next: a human in the portal clicks 'Approve Production' (→ prod_approved), then 'Mark as Released' (→ released)."
-              echo "Audit trail captures both events with reviewer identity per compliance/risk-register.md."
-              ;;
-            released)
-              echo "Release ${{ steps.release.outputs.version }} → released (Option B: auto-release with no post-deploy human gate)."
-              ;;
-          esac

package/sdlc/files/sdlc-config.example.json

@@ -32,6 +32,11 @@
   "e2e_project": "chromium",
   "e2e_start_command": "npm run dev",
 
+  "_comment_e2e_authenticated": "Optional report-only authenticated e2e gate (continue-on-error, never blocks the merge). e2e_projects = Playwright project names that need a logged-in session (auth-setup runs automatically as their dependency); e2e_seed_command seeds admins/fixtures before the run; e2e_env maps repo secrets onto the seed + e2e steps. Author these specs with the e2e-test-engineer skill (evidenceShot per AC). Leave empty to run only the blocking smoke project above.",
+  "e2e_seed_command": "",
+  "e2e_projects": [],
+  "e2e_env": {},
+
   "paths_ignore": [
     ".github/workflows/**",
     "SDLC/**",
@@ -53,7 +58,7 @@
     "api_key_secret": "DEVAUDIT_API_KEY"
   },
 
-  "_comment_uat": "UAT-environment verification (Stage 3 Step 10). Opt-in: enabled=false skips Step 10 entirely. When enabled, only requirements whose risk class is listed in required_risk_classes go through UAT-env verification.",
+  "_comment_uat": "UAT-environment verification (Stage 3 Step 10). Opt-in: enabled=false skips Step 10 entirely. When enabled, only requirements whose risk class is listed in required_risk_classes go through UAT-env verification; use [\"*\"] to require it for every requirement (projects that UAT every release).",
   "uat": {
     "enabled": false,
     "url": "",

package/sdlc/files/stacks/node/hooks/commitlint.config.mjs

@@ -2,15 +2,24 @@
  * Commitlint configuration for Metasession SDLC.
  *
  * Enforces:
- * - Conventional Commits format (feat, fix, docs, test, refactor, chore, compliance, security)
- * - Co-Authored-By tag presence (warning — not every commit is AI-generated)
- * - Ref: REQ-XXX trailer presence (warning — trivial commits skip requirements)
+ * - Conventional Commits format (feat, fix, docs, test, refactor, chore, …).
+ * - Requirement traceability: **implementation** commits (feat / fix /
+ *   refactor / perf) MUST cite a requirement via `[REQ-XXX]` in the subject
+ *   or a `Ref: REQ-XXX` trailer (ERROR). Housekeeping types (docs, chore, ci,
+ *   build, test, compliance, revert) are exempt. This is the local half of
+ *   the "no implementation without a requirement" rule; `validate-commits.sh`
+ *   enforces the same at PR CI (which `--no-verify` can't skip). Work starts
+ *   from a requirement, which starts from an issue — run the `sdlc-implementer`
+ *   skill, whose Phase 1 assigns the REQ from the originating issue.
+ * - Co-Authored-By trailer (warning — not every commit is AI-generated).
  *
  * Install:
  *   npm install --save-dev @commitlint/cli @commitlint/config-conventional
  *   cp this file to your project root as commitlint.config.mjs
  */
 
+const IMPLEMENTATION_TYPES = ['feat', 'fix', 'refactor', 'perf'];
+
 export default {
   extends: ['@commitlint/config-conventional'],
   rules: {
@@ -35,20 +44,29 @@ export default {
     ],
     // Warn (not error) when body is missing — some commits are one-liners
     'body-empty': [1, 'never'],
+    // Implementation commits must trace to a requirement (ERROR)
+    'requirement-ref-for-impl': [2, 'always'],
+    // AI-authored commits should be attributed (warning)
+    'trailer-co-authored-by': [1, 'always'],
   },
   plugins: [
     {
       rules: {
-        'trailer-ref-requirement': ({ raw }) => {
-          // Warn if Ref: REQ-XXX is missing — trivial commits don't need it
-          const hasRef = /Ref:\s*REQ-\d+/i.test(raw);
+        'requirement-ref-for-impl': ({ type, raw }) => {
+          // Only implementation work is requirement-gated; housekeeping is exempt.
+          if (!IMPLEMENTATION_TYPES.includes(type)) return [true];
+          const hasRef =
+            /\[REQ-\d{3,}\]/i.test(raw) || /Ref:\s*REQ-\d{3,}/i.test(raw);
           return [
             hasRef,
-            'Commit should include "Ref: REQ-XXX" for tracked requirements',
+            `"${type}" is an implementation commit and must cite a requirement: ` +
+              `add [REQ-XXX] to the subject or a "Ref: REQ-XXX" trailer. Work must ` +
+              `start from a requirement (which starts from an issue) — run the ` +
+              `sdlc-implementer skill to assign one. Housekeeping types ` +
+              `(docs/chore/ci/build/test/compliance/revert) are exempt.`,
           ];
         },
         'trailer-co-authored-by': ({ raw }) => {
-          // Warn if Co-Authored-By is missing — not every commit is AI-generated
           const hasCoAuthor = /Co-Authored-By:/i.test(raw);
           return [
             hasCoAuthor,
@@ -58,7 +76,5 @@ export default {
       },
     },
   ],
-  // Apply custom rules as warnings (level 1), not errors
-  // Override in your project if you want stricter enforcement
   helpUrl: 'https://www.conventionalcommits.org/',
 };