@metasession.co/devaudit-cli 0.1.10 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "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.11",
     "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/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/',
 };