@metasession.co/devaudit-cli 0.1.40 → 0.1.42

package/package.json

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

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

@@ -58,6 +58,38 @@ Both `ci.yml` and `compliance-evidence.yml` call the same helper, so a feature s
 
 If you need a separate release container for a sub-piece of work — e.g. carving REQ-038 out of an in-flight feature — give it its own REQ-ID and tag the commits accordingly.
 
+## Two release shapes
+
+A release is classified by its version pattern. **Most of this doc walks the tracked path** (a REQ-XXX-tagged release for a single requirement). For develop pushes that don't carry a REQ tag — typically `docs:`, `chore:`, `ci:`, `build:`, `test:`, `compliance:`, `revert:` — the version-deriver falls back to a bare date and the release is **housekeeping**.
+
+| Shape | Version pattern | Triggered by | Per-REQ ceremony |
+|---|---|---|---|
+| **Tracked** | `REQ-037`, `REQ-046-FIX`, etc. | A `feat`/`fix`/`refactor`/`perf` commit (REQ tag required by commitlint) | Yes — full Steps 1-9 |
+| **Housekeeping** | `v2026.06.04` (bare date, optionally `.N`) | A push containing only REQ-exempt commit types | **No** per-REQ artefacts; the portal auto-skips test-scope, test-plan, implementation-plan, and test-execution-summary completeness checks |
+
+### Housekeeping releases — what's required
+
+Housekeeping releases **skip** the per-requirement evidence (no REQ → no `compliance/evidence/REQ-XXX/` folder) but **still produce two release-scoped artefacts**:
+
+| Artefact | Tracked path | Housekeeping path | Auto-generated by CI? |
+|---|---|---|---|
+| Release ticket | `compliance/pending-releases/RELEASE-TICKET-REQ-XXX.md` (Step 8) | `compliance/pending-releases/RELEASE-TICKET-<version>.md` (e.g. `RELEASE-TICKET-v2026.06.04.md`) | **Yes** — `generate-housekeeping-release-ticket.sh` runs after `derive-release-version.sh` and emits a stub the operator reviews + signs off |
+| Security summary | `compliance/evidence/REQ-XXX/security-summary.md` (Step 4) | `compliance/security-summary-<version>.md` at the compliance root (release-scoped, not REQ-scoped) | **Yes** — `generate-security-summary.sh` scrapes the SAST + dep-audit gate JSON and emits a stub with an operator sign-off block |
+
+**The portal evidence check is lenient on filename.** Any file whose name (case-insensitive) starts with `release-ticket` satisfies the release-ticket check, and any file named exactly `security-summary.md` satisfies the security-summary check. The version-suffixed conventions above are recommended for **searchability + audit trail** when a project has many housekeeping releases stacked up — they keep the artefacts distinct per release without needing folder scoping.
+
+**What housekeeping operators do, end to end:**
+
+1. Push the `docs:` / `chore:` / `ci:` commits to develop. CI runs the four gates as usual.
+2. CI's `compliance-evidence.yml` workflow auto-opens a PR (`chore/housekeeping-release-<version>`) containing the two stubs.
+3. Review the stubs — confirm the commit-summary list in the release ticket is sensible, confirm the SAST + dep-audit summary reads correctly, fill in the operator sign-off block on each.
+4. Merge that PR. The next CI run picks up the artefacts and the portal's release-completeness checklist flips both items to ✓.
+5. Submit for UAT review on the portal. The approval flow is identical to the tracked path — same four-eyes rules (per project risk tier), same `draft → uat_review → uat_approved → prod_review → prod_approved → released` state machine.
+
+**No auto-approval.** Housekeeping releases still require operator action to advance through the gates. The CI-generated stubs replace the operator's authoring effort, not the operator's review.
+
+> **Versions of the framework before 2026-06 produced housekeeping stubs by hand.** Older release records may have `security-summary.md` under a REQ-XXX-shaped folder or no release ticket at all — leave those in DRAFT for the audit trail; backfilling isn't required.
+
 ## Steps
 
 ### Step 0: Confirm CI Is Green
@@ -233,6 +265,20 @@ cat compliance/evidence/REQ-XXX/test-scope.md
 # If not, complete the outstanding items before proceeding
 ```
 
+The test-scope artefact carries an **SRS-ID cross-reference table** so each test maps back to the requirement (SoT) it pins. Format:
+
+```markdown
+## SRS coverage
+
+| Test (file) | AC | SRS item |
+|---|---|---|
+| e2e/admin-order-flow.spec.ts | AC1 | REQ-ORDER-005 |
+| services/order-service.test.ts | AC2 | REQ-INV-010 |
+| e2e/incident-dashboard.spec.ts | AC9 | REQ-OPS-001 |
+```
+
+The SRS-ID column populates from the implementation plan's SRS-ID column (populated by the `requirements-aligner` skill at Stage 1). Stage 3 cross-checks consistency: every AC's SRS item should resolve to a real entry in `docs/SRS.md`, every test should pin at least one AC. The skill also drops a `srs-alignment.md` per-REQ artefact alongside this one (Tier 3 evidence with `evidence_type=srs_alignment`).
+
 For MEDIUM/HIGH risk, verify the implementation plan exists and matches what was built:
 
 ```bash

package/sdlc/files/_common/Implementation_Plan_TEMPLATE.md

@@ -36,9 +36,14 @@ Each section below maps to one (or more) of these clauses. Don't delete sections
 
 - **Goal:** REPLACE — one sentence describing what this REQ delivers, no jargon.
 - **Acceptance criteria:**
-  - AC1 — REPLACE
-  - AC2 — REPLACE
-  - …
+
+| AC | Description | SRS item it traces to |
+|---|---|---|
+| AC1 | REPLACE — one-line behavioural description | REQ-AREA-NNN (existing) / REQ-AREA-NNN (new — propose stub) / `@srs-deferred: <reason>` |
+| AC2 | REPLACE | REPLACE |
+| … | | |
+
+> **SRS-ID column populated by the `requirements-aligner` skill** at Stage 1 plan APPROVAL. The skill fuzzy-matches each AC against `docs/SRS.md`, proposes new `REQ-AREA-NNN` stubs for behaviour the SRS doesn't yet describe, and flags stale items. Plan APPROVAL blocks (configurable per `sdlc-config.json:requirements_aligner.block_on_stage_1`, ramp-up mode default-on for legacy projects) until every AC has either an existing SRS item, a new SRS-ID stub added in this cycle, or an explicit `@srs-deferred` annotation. See [`requirements-aligner` skill](../skills/requirements-aligner/SKILL.md).
 
 ## 2. Scope
 

package/sdlc/files/_common/implementing-an-sdlc-issue.md

@@ -45,7 +45,7 @@ A worked end-to-end example for a zero-risk change (a typo, a dependency bump, a
 3. **Commit with a housekeeping type.** `docs:` / `chore:` / `ci:` / `build:` / `test:` / `revert:` are **exempt** from the `[REQ-XXX]` rule — e.g. `git commit -m "docs: fix typo in README"`. A `feat` / `fix` / `refactor` / `perf` subject without a `[REQ-XXX]` or `Ref: REQ-XXX` is **rejected** by commitlint and `validate-commits.sh` — if that fires, you picked the wrong type and the change isn't trivial.
 4. **Run the gates locally — not optional.** `npx tsc --noEmit`, lint, and the test suite must pass before you push. Trivial ≠ unverified.
 5. **Push and open a PR.** CI runs the same quality gates. `compliance-validation.yml` finds no `REQ-XXX` and **skips** artifact validation; no release ticket, no RTM row, no evidence pack is required.
-6. **Merge once CI is green** and a reviewer approves the PR. There's **no** portal release record to approve, no UAT/Production gate, and no close-out — a housekeeping push produces at most a bare-date release (`vYYYY.MM.DD`), which carries no approval gate. (Contrast the tracked-change flow below, which produces a `REQ-XXX` release that goes through four-eyes.)
+6. **Merge once CI is green** and a reviewer approves the PR. A housekeeping push **does** produce a portal release record — a bare-date release (`vYYYY.MM.DD`) — and it **does** go through the same UAT → production four-eyes flow as a tracked release. What the portal **auto-skips for housekeeping** is the four per-REQ completeness items (test-scope / test-plan / implementation-plan / test-execution-summary) — those have nothing to evaluate without a `REQ-XXX`. What's still required: all four CI gates green, a release ticket (`compliance/pending-releases/RELEASE-TICKET-<version>.md`), and a security summary (`compliance/security-summary-<version>.md`). **CI auto-generates both stubs as an operator-sign-off PR** (DevAudit-Installer v0.1.41+, scripts `generate-housekeeping-release-ticket.sh` + `generate-security-summary.sh`). Review the stubs + replace the `REPLACE — …` markers + merge → next CI run uploads them → matrix flips both items to ✓ → submit for UAT review on the portal. See [stage-3 housekeeping section](./3-compile-evidence.md) for the full walkthrough.
 
 If at any step it stops feeling trivial — it changes behaviour, touches auth/payments/data, or an auditor would ask about it — switch to a tracked change and run `sdlc-implementer`. When unsure, it's not trivial.
 

package/sdlc/files/_common/scripts/generate-housekeeping-release-ticket.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# generate-housekeeping-release-ticket.sh
+#
+# Writes a housekeeping release-ticket stub for a bare-date release
+# (`v2026.06.04` etc.). Synced into the consumer's `scripts/` by
+# `devaudit update`; invoked from `compliance-evidence.yml` after
+# `derive-release-version.sh` when the version pattern is bare-date AND
+# no ticket file already exists.
+#
+# Usage:
+#   bash scripts/generate-housekeeping-release-ticket.sh <version> > <out>
+#
+# Where <version> is the bare-date version (e.g. `v2026.06.04`) and
+# <out> is the target path (typically `compliance/pending-releases/
+# RELEASE-TICKET-<version>.md`).
+#
+# The stub carries:
+# - Frontmatter with version + generated_at + last_reviewed_at (defaults
+#   to today; operator updates on sign-off)
+# - Commit summaries since the previous release tag (or last 20 commits
+#   if no prior tag exists)
+# - An operator sign-off block with `REPLACE — …` markers the operator
+#   must fill in before merging the auto-PR
+#
+# Companion to `generate-security-summary.sh`. Both are invoked together
+# by the CI workflow.
+#
+# DevAudit-Installer#116 WS3.
+
+set -euo pipefail
+
+VERSION="${1:-}"
+if [ -z "$VERSION" ]; then
+  echo "usage: $(basename "$0") <version>" >&2
+  exit 2
+fi
+
+# Validate bare-date pattern (matches `classifyReleaseShape` in META-COMPLY).
+if ! [[ "$VERSION" =~ ^v[0-9]{4}\.[0-9]{2}\.[0-9]{2}(\.[0-9]+)?$ ]]; then
+  echo "error: '$VERSION' is not a bare-date version (expected vYYYY.MM.DD[.N])" >&2
+  exit 2
+fi
+
+TODAY=$(date -u +%Y-%m-%d)
+
+# Last 20 commits with subject lines. Skip the version-deriver fallback
+# from itself (avoid recursion if this script is re-run on a branch
+# that already includes its own auto-commit).
+COMMIT_LINES=$(git log -20 --pretty=format:'- `%h` %s' 2>/dev/null \
+  | grep -v 'chore: housekeeping release-ticket stub' \
+  | head -15)
+if [ -z "$COMMIT_LINES" ]; then
+  COMMIT_LINES="- _(no commits found in `git log` — this stub was generated outside a git context)_"
+fi
+
+cat <<EOF
+---
+version: "$VERSION"
+release_shape: housekeeping
+generated_at: "$TODAY"
+last_reviewed_at: "$TODAY"
+generated_by: "generate-housekeeping-release-ticket.sh (DevAudit-Installer#116)"
+---
+
+> ⚠️ **AUTO-GENERATED STUB — REPLACE BEFORE MERGE**
+>
+> This release ticket was auto-generated by CI when develop received a
+> housekeeping push (no \`REQ-XXX\` in commit subjects, version derived
+> as bare-date \`$VERSION\`).
+>
+> **The operator must:**
+> 1. Confirm the **Summary** below describes the actual intent of these
+>    commits — replace the placeholder if the auto-summary is generic.
+> 2. Fill in the **Sign-off** block with the operator's name + date +
+>    risk assessment.
+> 3. Merge this PR. The next \`compliance-evidence.yml\` run will upload
+>    this file as \`release_artifact\` evidence, satisfying the
+>    portal's release-ticket completeness check.
+
+# Release Ticket: $VERSION (housekeeping)
+
+**Status:** TESTED - PENDING SIGN-OFF
+**Date:** $TODAY
+**Release Shape:** Housekeeping (bare-date, no REQ tag)
+**Version:** $VERSION
+
+---
+
+## Summary
+
+REPLACE — one or two sentences describing what these housekeeping commits delivered. Examples: *"Documentation refresh for the v0.1.39 governance changes; no code paths touched."* / *"Dependency bumps (vitest 4.0.5 → 4.0.6, prettier 4.3.0 → 4.3.1) caught by Dependabot; no behavioural change."* / *"CI workflow housekeeping: retry-on-flake threshold raised, runner image pinned."*
+
+## Commits in this release
+
+$COMMIT_LINES
+
+## Risk Assessment
+
+REPLACE — confirm risk class for this release (typically LOW for housekeeping):
+
+- [ ] **LOW** — documentation, dependency bumps, CI tweaks, internal refactors. No user-visible behaviour change.
+- [ ] **MEDIUM** — touches code paths an end-user reaches; user-visible change is small and well-contained.
+- [ ] **HIGH** — should not be a housekeeping release. If this is checked, **stop and re-tag the commits with \`REQ-XXX\`** so the release is tracked properly.
+
+## Test Evidence
+
+| Test Type | Status | Source |
+|---|---|---|
+| TypeScript | $(test -f gate-outcomes.json && echo "see gate-outcomes.json" || echo "REPLACE — green / N/A") | CI \`typecheck\` gate |
+| SAST | $(test -f gate-outcomes.json && echo "see gate-outcomes.json" || echo "REPLACE — green / N/A") | CI \`SAST\` gate |
+| Dependency audit | $(test -f gate-outcomes.json && echo "see gate-outcomes.json" || echo "REPLACE — green / N/A") | CI \`dependency_audit\` gate |
+| E2E | $(test -f gate-outcomes.json && echo "see gate-outcomes.json" || echo "REPLACE — green / N/A") | CI \`e2e\` gate |
+| Test reports | $(test -f gate-outcomes.json && echo "see gate-outcomes.json" || echo "REPLACE — green / N/A") | CI \`test_report\` gate |
+
+> Companion artefact: \`compliance/security-summary-$VERSION.md\` (auto-generated by \`generate-security-summary.sh\` in the same workflow run; contains the SAST + dep-audit findings detail).
+
+## Acceptance Criteria
+
+- [x] All four compliance gates green on the CI run that produced this stub
+- [x] No \`REQ-XXX\`-tagged commits in this release (housekeeping by definition)
+- [ ] Operator-reviewed and signed off — see Sign-off block below
+
+## Post-Deploy Actions
+
+| Type | Script / Command | Target | Required | Notes |
+|------|-----------------|--------|----------|-------|
+| — | None | — | — | Housekeeping releases typically have no post-deploy actions |
+
+<!-- Replace the "None" row above if this release requires post-deploy work. -->
+
+---
+
+## Sign-off
+
+| Role | Name | Date | Notes |
+|---|---|---|---|
+| Submitter | REPLACE | $TODAY | Auto-generated by CI; reviewed + edited |
+| Reviewer (independent if project risk_tier ≠ low) | REPLACE | REPLACE | REPLACE |
+
+## Audit Trail
+
+| Date | Action | Actor | Notes |
+|------|--------|-------|-------|
+| $TODAY | Stub auto-generated | devaudit-bot | Bare-date version $VERSION |
+| REPLACE | Operator sign-off | REPLACE | REPLACE |
+| REPLACE | Submitted for UAT review | REPLACE | Via portal |
+EOF

package/sdlc/files/_common/scripts/generate-security-summary.sh

@@ -0,0 +1,170 @@
+#!/usr/bin/env bash
+# generate-security-summary.sh
+#
+# Writes a security-summary stub for a release. Resolves the dangling
+# reference in META-COMPLY's release-checklist (the UI hint mentioned a
+# generator script that didn't exist).
+#
+# Usage:
+#   bash scripts/generate-security-summary.sh <version> > <out>
+#
+# - For housekeeping releases (bare-date version), the canonical
+#   <out> is `compliance/security-summary-<version>.md` at the
+#   compliance root.
+# - For tracked releases (REQ-XXX version), the canonical <out> is
+#   `compliance/evidence/REQ-XXX/security-summary.md`. The script
+#   outputs the same body shape; only the caller decides the path.
+#
+# Scrapes:
+# - `sast-results.json` (Semgrep) — high/critical findings count
+# - `dependency-audit.json` (npm audit / pip-audit) — high/critical
+#   vulnerability count
+# - `gate-outcomes.json` (DevAudit-Installer v0.1.29) — per-gate
+#   pass/fail/skip status
+#
+# Each source is optional — the stub gracefully reports "not found"
+# rather than erroring out. The operator fills in any missing detail
+# in the sign-off block before merging the auto-PR.
+#
+# DevAudit-Installer#116 WS4.
+
+set -euo pipefail
+
+VERSION="${1:-}"
+if [ -z "$VERSION" ]; then
+  echo "usage: $(basename "$0") <version>" >&2
+  exit 2
+fi
+
+TODAY=$(date -u +%Y-%m-%d)
+
+# Detect release shape from the version.
+SHAPE="unknown"
+if [[ "$VERSION" =~ ^v[0-9]{4}\.[0-9]{2}\.[0-9]{2}(\.[0-9]+)?$ ]]; then
+  SHAPE="housekeeping"
+elif [[ "$VERSION" =~ ^REQ- ]]; then
+  SHAPE="tracked"
+fi
+
+# Helper: scrape Semgrep JSON for high/critical counts. Soft-fails when
+# the file is absent or jq isn't available.
+sast_summary() {
+  if [ ! -f sast-results.json ]; then
+    echo "REPLACE — \`sast-results.json\` not present at CWD; check that the SAST gate ran on this commit"
+    return
+  fi
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "REPLACE — \`jq\` not available; manually inspect \`sast-results.json\`"
+    return
+  fi
+  local HIGH CRITICAL TOTAL
+  HIGH=$(jq -r '[.results[]? | select(.extra.severity == "WARNING" or .extra.severity == "ERROR")] | length' sast-results.json 2>/dev/null || echo "?")
+  CRITICAL=$(jq -r '[.results[]? | select(.extra.severity == "ERROR")] | length' sast-results.json 2>/dev/null || echo "?")
+  TOTAL=$(jq -r '[.results[]?] | length' sast-results.json 2>/dev/null || echo "?")
+  echo "$TOTAL total finding(s) · $HIGH high/warning · $CRITICAL critical/error"
+}
+
+# Helper: scrape npm audit JSON. Tolerant of both `npm audit --json`
+# shape (vulnerabilities object) and pip-audit shape (vulnerabilities
+# array).
+dep_audit_summary() {
+  if [ ! -f dependency-audit.json ]; then
+    echo "REPLACE — \`dependency-audit.json\` not present at CWD; check that the dependency-audit gate ran on this commit"
+    return
+  fi
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "REPLACE — \`jq\` not available; manually inspect \`dependency-audit.json\`"
+    return
+  fi
+  # npm audit shape: .vulnerabilities is an object keyed by package
+  # name with .severity per row.
+  local HIGH CRITICAL TOTAL
+  HIGH=$(jq -r '[.vulnerabilities | (if type == "object" then to_entries[] | .value else .[]? end) | select(.severity == "high")] | length' dependency-audit.json 2>/dev/null || echo "?")
+  CRITICAL=$(jq -r '[.vulnerabilities | (if type == "object" then to_entries[] | .value else .[]? end) | select(.severity == "critical")] | length' dependency-audit.json 2>/dev/null || echo "?")
+  TOTAL=$(jq -r '[.vulnerabilities | (if type == "object" then to_entries[] | .value else .[]? end)] | length' dependency-audit.json 2>/dev/null || echo "?")
+  echo "$TOTAL total vulnerability/ies · $HIGH high · $CRITICAL critical"
+}
+
+# Helper: gate-outcomes.json (DevAudit-Installer v0.1.29 onwards).
+gate_outcomes_summary() {
+  if [ ! -f gate-outcomes.json ]; then
+    echo "REPLACE — \`gate-outcomes.json\` not present at CWD"
+    return
+  fi
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "REPLACE — \`jq\` not available; manually inspect \`gate-outcomes.json\`"
+    return
+  fi
+  jq -r 'to_entries[] | "- **\(.key)** — \(.value // "?")"' gate-outcomes.json 2>/dev/null \
+    || echo "REPLACE — could not parse gate-outcomes.json"
+}
+
+SAST_SUMMARY=$(sast_summary)
+DEP_SUMMARY=$(dep_audit_summary)
+GATES=$(gate_outcomes_summary)
+
+cat <<EOF
+---
+version: "$VERSION"
+release_shape: $SHAPE
+generated_at: "$TODAY"
+last_reviewed_at: "$TODAY"
+generated_by: "generate-security-summary.sh (DevAudit-Installer#116)"
+---
+
+> ⚠️ **AUTO-GENERATED STUB — REVIEW BEFORE MERGE**
+>
+> This security summary was auto-generated by CI from the SAST and
+> dependency-audit gate JSON. The operator should:
+>
+> 1. Confirm the **findings summary** matches what they saw on the
+>    gate panel for this release.
+> 2. Replace any \`REPLACE — …\` markers below (typically the access-
+>    control + audit-log assessment, which the gates can't infer).
+> 3. Sign off in the **Sign-off** block before this PR merges.
+
+# Security Summary — $VERSION
+
+**Release shape:** $SHAPE
+**Generated:** $TODAY
+**Source data:** \`sast-results.json\` + \`dependency-audit.json\` + \`gate-outcomes.json\` (this CI run)
+
+## SAST findings (Semgrep)
+
+$SAST_SUMMARY
+
+> **Policy:** the SAST gate fails the build at \`high\` or \`critical\` severity. If this release shipped, both are zero.
+
+## Dependency vulnerabilities
+
+$DEP_SUMMARY
+
+> **Policy:** the dependency-audit gate fails the build at \`high\` or \`critical\` severity. If this release shipped, both are zero.
+
+## Gate outcomes (per CI run)
+
+$GATES
+
+## Access control + audit log
+
+| Check | Result | Notes |
+|---|---|---|
+| Access control unchanged | REPLACE — yes/no | If yes, no further work. If no, document the auth/RBAC delta and confirm it landed an audit event. |
+| Audit log append-only invariant preserved | REPLACE — yes/no | If yes, no further work. If no, document why and confirm the change has independent review. |
+| Sensitive data exposure | REPLACE — yes/no | If yes, escalate to the GDPR triage in \`compliance/governance/dpia.md\` before merging. |
+
+## Risk Assessment
+
+REPLACE — one paragraph summarising the security posture of this release. For housekeeping releases the typical wording is *"No code paths touched; security posture unchanged from the previous release."* For tracked releases name the touched modules + threat model assessment.
+
+---
+
+## Sign-off
+
+| Role | Name | Date | Notes |
+|---|---|---|---|
+| Author | devaudit-bot (auto-generated) | $TODAY | Stub generated from CI gate JSON |
+| Reviewer | REPLACE | REPLACE | REPLACE |
+
+Once reviewed + signed off, this file is uploaded as evidence by the next \`compliance-evidence.yml\` run; the portal's release-completeness checklist flips the security-summary item to ✓.
+EOF

package/sdlc/files/_common/skills/requirements-aligner/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: requirements-aligner
+description: Catch drift between docs/SRS.md (the requirements source-of-truth) and the in-flight implementation. Runs at Stage 1 (plan APPROVAL) and Stage 3 (evidence pack) of the SDLC. Parses each REQ's acceptance criteria, fuzzy-matches each AC against existing SRS items, proposes new `REQ-AREA-NNN` stubs for behaviour the SRS doesn't yet describe, flags potentially-stale SRS items whose source-of-truth file was modified without the SRS prose being updated, and produces a per-REQ `compliance/evidence/REQ-XXX/srs-alignment.md` artefact that traces the audit back from code to spec. Use when invoking on a single REQ ("align SRS for REQ-066", "what SRS items did this REQ need?", "is the SRS in sync with this branch?"); when `sdlc-implementer` delegates at Stage 1 plan-approval or Stage 3 evidence-compilation; when running a branch-wide audit ("audit SRS drift across this PR's commits"). Do NOT use for SRS authoring from scratch (the operator drafts new items; this skill proposes the IDs and stubs); for changing the SRS prose conventions themselves (those are operator decisions); for framework-clause mapping of the `srs_alignment` evidence type (that's META-COMPLY's `framework-registry-auditor`).
+---
+
+# Requirements Aligner
+
+Catches the class of drift the wawagardenbar-app REQ-066 cycle surfaced: code, tests, and screenshots shipped across 10 ACs in 6 PRs while `docs/SRS.md` stayed untouched. Seven new SRS items + one stale item were filed retroactively after release. This skill catches them at Stage 1 or Stage 3, before merge.
+
+The skill is **Phase A scope** (per [DevAudit-Installer#119](https://github.com/metasession-dev/DevAudit-Installer/issues/119) review): Stage 1 + Stage 3 hooks only. Stage 2 (commit-time advisory) + Stage 5 (post-release audit) + automatic follow-up issue filing all defer to Phase B/C — the v1 surface is the safest enforcement points.
+
+## What this skill owns
+
+| Artefact | Lives at | Tier |
+|---|---|---|
+| `docs/SRS.md` (the SoT, project-spanning) | Top-level project docs | 2 (project strategy) |
+| `compliance/evidence/REQ-XXX/srs-alignment.md` (per-REQ Tier 3 evidence) | Per-REQ evidence directory | 3 (per-REQ) |
+
+The skill does **not** own the SRS prose conventions (operator decision). It does propose new `REQ-AREA-NNN` IDs + Given/When/Then stubs the operator then edits.
+
+## Scope
+
+**In scope**
+
+- Phase 1 (Stage-1 hook) — parse plan AC table → fuzzy-match against `docs/SRS.md` → propose new IDs / flag stale → inject into plan's "SRS items proposed/touched" section.
+- Phase 2 (Stage-3 hook) — drop `compliance/evidence/REQ-XXX/srs-alignment.md` with the per-REQ trace from AC to SRS item.
+- Per-REQ alignment audit (operator invocation).
+- Branch-wide alignment audit (operator invocation — walks every REQ touched on the branch).
+
+**Out of scope**
+
+- Drafting SRS prose from scratch — the skill proposes stubs; the operator authors final language.
+- Stage 2 (commit-time advisory) — deferred to Phase B.
+- Stage 5 (post-release audit) — deferred to Phase B.
+- Automatic follow-up issue filing — deferred to Phase C (default OFF per [#119 review](https://github.com/metasession-dev/DevAudit-Installer/issues/119#issuecomment-4631840651)).
+- Threat modelling, ADR drafting, risk-register entries — adjacent skills (`adr-author`, `risk-register-keeper`).
+- Framework-clause mapping of the `srs_alignment` evidence type — that's META-COMPLY's `framework-registry-auditor`.
+
+## The workflow
+
+Five phases. Phase 0 routes; Phases 1–2 are the SDLC stage hooks; Phases 3–4 are utilities; Phase 5 reports.
+
+### Phase 0 — Route
+
+Determine what's being aligned:
+
+- **Stage-1 plan APPROVAL** — `sdlc-implementer` (or operator) says *"align SRS for REQ-XXX before approving the plan"* → Phase 1.
+- **Stage-3 evidence pack** — `sdlc-implementer` (or operator) says *"drop the srs-alignment.md for REQ-XXX"* → Phase 2.
+- **Per-REQ ad-hoc audit** — operator says *"is the SRS in sync with REQ-XXX?"* / *"what SRS items did this REQ need?"* → Phase 3.
+- **Branch-wide audit** — operator says *"audit SRS drift across this branch"* / *"every REQ on develop since main needs an SRS check"* → Phase 4.
+
+The skill does not fire spontaneously. The parent skill (`sdlc-implementer`) invokes it at Stages 1 + 3 per the parent's SKILL.md delegation contract.
+
+### Phase 1 — Stage-1 plan APPROVAL hook
+
+Input: the REQ's `compliance/plans/REQ-XXX/implementation-plan.md` plus the working-tree diff.
+
+**Step 1 — Parse the AC table.** The implementation plan template carries an "Acceptance Criteria" or equivalent section listing AC1, AC2, … with one-line descriptions of each behavioural change.
+
+**Step 2 — Fuzzy-match each AC against `docs/SRS.md`.** For each AC, search the SRS for items whose:
+- *Title* phrase appears in the AC description, OR
+- *Implementation source-of-truth* footnote names a file the AC's diff touches, OR
+- *Given/When/Then* prose semantically aligns with the AC (use the AC's verbs + nouns as the match-key).
+
+**Step 3 — Categorise each AC:**
+
+| AC ⇒ SRS state | Action |
+|---|---|
+| **Exact match** — AC traces 1:1 to an existing SRS item, no behavioural delta | Record the mapping; no SRS edit needed |
+| **Match + drift** — existing SRS item covers the AC's surface but the behaviour has shifted (e.g. new field, new edge case, new error path) | Flag the item as *potentially stale*; the plan must mark it for update in this cycle OR justify why the SRS prose still covers it |
+| **No match** — AC introduces behaviour the SRS doesn't yet describe | Propose new `REQ-AREA-NNN` (next free ID per area — see Step 4) with a Given/When/Then stub the operator edits |
+| **Reverse drift** — an SRS item points at code that's been removed in this REQ | Propose deprecation: the SRS item is now obsolete |
+
+**Step 4 — Allocate new SRS-IDs.** Scan `docs/SRS.md` for the max-existing ID per `REQ-AREA` prefix (`REQ-ORDER`, `REQ-INV`, `REQ-OPS`, etc.) and propose `+1` for each new item. The skill does NOT support cross-branch ID coordination — if two parallel branches both consume the same next-free ID, git merge on `docs/SRS.md` is the canonical conflict signal. Re-run the skill post-merge to re-allocate.
+
+**Step 5 — Inject into the implementation plan.** The plan's "SRS items proposed/touched" section (added to `Implementation_Plan_TEMPLATE.md` alongside this skill's introduction) carries a table:
+
+```markdown
+## SRS items proposed/touched
+
+| AC | SRS item | Status | Notes |
+|---|---|---|---|
+| AC1 | REQ-ORDER-005 (existing) | unchanged | Trace-only |
+| AC2 | REQ-INV-010 (new — proposed) | stub | <one-line behaviour description> |
+| AC3 | REQ-INV-011 (new — proposed) | stub | <one-line> |
+| AC4 | REQ-ORDER-002 (existing) | stale — update needed | <one-line: what's drifted> |
+```
+
+For **deferred** items (the operator decides the AC genuinely doesn't need an SRS entry), the row carries `@srs-deferred: <reason>` so the deferral is visible.
+
+**Step 6 — Block plan APPROVAL** until each AC has either:
+- (a) an existing SRS item it traces to, with no drift, OR
+- (b) a new SRS-ID stub added in this cycle, OR
+- (c) an explicit `@srs-deferred: <reason>` annotation in the AC row.
+
+The block is configurable via `sdlc-config.json` — see *Configuration* below. For projects with sparse SRS, the **ramp-up mode** defaults to audit-only for the first N runs (default 5) so operators get used to the surface before it starts blocking.
+
+### Phase 2 — Stage-3 evidence pack hook
+
+Input: the REQ's implementation plan (post-approval) and the working-tree diff.
+
+**Step 1 — Generate `compliance/evidence/REQ-XXX/srs-alignment.md`.** Format:
+
+```markdown
+---
+req: REQ-XXX
+generated_by: requirements-aligner
+generated_at: <ISO timestamp>
+---
+
+# SRS alignment — REQ-XXX
+
+## ACs traced
+
+| AC | SRS item | Action this cycle |
+|---|---|---|
+| AC1 | REQ-ORDER-005 | unchanged |
+| AC2 | REQ-INV-010 | added (new — see Phase 1 stub) |
+| AC3 | REQ-INV-011 | added (new) |
+| AC4 | REQ-ORDER-002 | updated (drift) |
+
+## Operator sign-off
+
+I have reviewed the AC-to-SRS-item traces above and confirm:
+- [ ] Each AC has a defensible SRS item.
+- [ ] New SRS items have been edited from stubs to canonical Given/When/Then prose.
+- [ ] Stale items have been brought current.
+
+**Reviewer:** <operator-name>
+**Date:** <YYYY-MM-DD>
+```
+
+**Step 2 — Tag for upload.** The CI's `compliance-evidence.yml` uploads this file as `evidence_type=srs_alignment` (added to META-COMPLY's `EVIDENCE_TYPE_REGISTRY` in the paired sub-PR). The framework-coverage matrix then closes `ISO29119.3.4` (Test Plan — requirements traceability) and `SOC2.CC2.1` (Communication of policies — when paired with INSTRUCTIONS.md) for this REQ.
+
+**Step 3 — Hand-off back to `sdlc-implementer`.** The skill's job ends at the artefact + the operator sign-off. The parent orchestrator continues with the rest of Stage 3 (security summary, evidence upload, release ticket).
+
+### Phase 3 — Per-REQ ad-hoc audit
+
+Same logic as Phase 1's Step 2 + Step 3, but produces a markdown report rather than blocking. Useful when an operator asks *"is REQ-XXX's SRS coverage healthy?"* outside the SDLC orchestration flow.
+
+### Phase 4 — Branch-wide audit
+
+For each REQ that has commits on the current branch (or in a specified range), run Phase 3. Produces an aggregated report listing per-REQ alignment status across the branch.
+
+### Phase 5 — Report
+
+- For Phase 1 — the plan's injected table + the block/allow decision.
+- For Phase 2 — the artefact path + summary line.
+- For Phase 3 / 4 — markdown report (one per REQ, or aggregated for branch audit).
+
+## Configuration (sdlc-config.json)
+
+```json
+{
+  "requirements_aligner": {
+    "enabled": true,
+    "block_on_stage_1": false,
+    "block_on_stage_3": true,
+    "auto_file_followup_issue": false,
+    "ramp_up_runs": 5
+  }
+}
+```
+
+Per the [#119 review](https://github.com/metasession-dev/DevAudit-Installer/issues/119#issuecomment-4631840651) defaults:
+
+- `block_on_stage_1: false` — advisory at Stage 1 by default. Operators flip to `true` once the SRS is populated enough that the skill is reliably catching real drift, not false-positives on sparse coverage.
+- `block_on_stage_3: true` — the per-REQ evidence pack is the hard gate (the Stage 3 artefact is what actually lands as evidence; missing it leaks).
+- `auto_file_followup_issue: false` — the skill never opens GitHub issues automatically. If gaps are detected at Stage 1 and the operator chooses to defer, the operator files the follow-up issue manually (or asks the skill to draft one, then confirms before filing).
+- `ramp_up_runs: 5` — on projects whose SRS is sparse, the first 5 invocations are audit-only regardless of `block_on_stage_1`. After 5 successful runs the configured blocking kicks in.
+
+## Principles
+
+**Don't author the SRS prose.** The skill proposes IDs + stubs the operator edits. Inventing canonical SRS language without operator review is exactly the kind of silent-drift this skill exists to prevent.
+
+**Fuzzy-match, don't presume.** When an AC matches an SRS item with low confidence, the skill surfaces the candidate and asks. False-positive matches (linking an unrelated SRS item to an AC) are worse than no match — they hide the gap they were trying to surface.
+
+**Block at Stage 3, advise at Stage 1.** The implementation plan can carry `@srs-deferred` annotations and ship. The evidence pack cannot — the per-REQ `srs-alignment.md` artefact must exist before Stage 3 completes. This is the asymmetric enforcement the [#119 review](https://github.com/metasession-dev/DevAudit-Installer/issues/119#issuecomment-4631840651) recommended.
+
+**Sibling-skill awareness.** When this skill proposes a new SRS-ID for an AC that documents an architectural decision, cross-link the proposed `adr-author` ADR (and vice versa). When it proposes an SRS-ID covering a HIGH-risk behaviour, cross-link the proposed `risk-register-keeper` RISK entry. The three SoT-alignment skills work together; each produces its own per-REQ Tier 3 artefact but they share the per-REQ context.
+
+**Ramp-up is the kindness.** Projects whose `docs/SRS.md` is sparse will trip every check on first contact. Audit-only first 5 runs gives operators time to populate the SoT before the blocking enforces.
+
+## References
+
+- [DevAudit-Installer#119](https://github.com/metasession-dev/DevAudit-Installer/issues/119) — the issue this skill closes, with the case study (wawagardenbar-app REQ-066) + the locked Phase A scope.
+- `sdlc-implementer/SKILL.md` Phase 1 + Phase 3 — the parent-skill invocation contract.
+- `sdlc/files/_common/Implementation_Plan_TEMPLATE.md` — carries the "SRS items proposed/touched" section this skill populates (companion change in this PR).
+- `sdlc/files/_common/3-compile-evidence.md` — the test-scope template gains an SRS-ID cross-reference table (companion change in this PR).
+- Sibling skills (forthcoming): `adr-author` (DevAudit-Installer#120), `risk-register-keeper` (DevAudit-Installer#121).
+- Meta-reviewer (META-COMPLY): `framework-registry-auditor` reviewed the `srs_alignment` evidence type's clause mappings before the META-COMPLY sub-PR opened. Per #119 sequencing.
+- Memory cross-link: `project_srs_supersedes_requirements` (docs/SRS.md is the requirements SoT — REQ-AREA-NNN; RTM uses REQ-XXX); `feedback_check_git_before_filing_from_umbrella` (Phase 5 post-release audit must grep git before claiming SRS-IDs are missing — deferred to Phase B but worth noting).