@metasession.co/devaudit-cli 0.1.41 → 0.1.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.1.41",
+  "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.41",
+    "@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

@@ -265,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/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).

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

@@ -160,9 +160,10 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
    For HIGH/CRITICAL also include: threat model (against STRIDE categories applicable to the touched surfaces), four-eyes attestation slot, rollback plan — the template has slots for all of these.
 
    **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.
-6. **Update `compliance/RTM.md`** with the new entry: REQ-XXX, title, risk class, linked issue, linked test cases (placeholder).
-7. **Post plan summary as an issue comment.** Format: TL;DR; Risk class + signals; Acceptance criteria; Technical approach (one paragraph); Dependencies; Test scope.
-8. **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.
+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).
+7. **Update `compliance/RTM.md`** with the new entry: REQ-XXX, title, risk class, linked issue, linked test cases (placeholder).
+8. **Post plan summary as an issue comment.** Format: TL;DR; Risk class + signals; Acceptance criteria (with SRS-IDs); Technical approach (one paragraph); Dependencies; Test scope.
+9. **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.
 
 ### Phase 2 — Implement and test (SDLC stage 2)
 
@@ -193,12 +194,14 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
 
 ### Phase 3 — Compile evidence (SDLC stage 3)
 
-1. **Re-run the full test pack** with artefact capture:
+1. **Invoke `requirements-aligner` to drop the per-REQ SRS-alignment artefact.** The skill's Phase 2 produces `compliance/evidence/REQ-XXX/srs-alignment.md` — the per-REQ trace from each AC to its SRS item, with an operator sign-off block. The artefact uploads with `evidence_type=srs_alignment` and closes `ISO29119.3.4` + `SOC2.CC2.1` for the REQ. Call via the standard Skill mechanism; don't inline the alignment logic.
+2. **Re-run the full test pack** with artefact capture:
    - `npm run test:e2e -- --reporter=html` (produces `playwright-report/`)
    - `npx vitest run --coverage` (produces `coverage/`)
-2. **Organise artefacts** under `compliance/evidence/REQ-XXX/` with date-prefixed naming:
+3. **Organise artefacts** under `compliance/evidence/REQ-XXX/` with date-prefixed naming:
    ```
    compliance/evidence/REQ-XXX/
+   ├── srs-alignment.md                  ← produced in step 1 by requirements-aligner
    ├── YYYY-MM-DD_e2e-results.json
    ├── YYYY-MM-DD_playwright-report/
    ├── YYYY-MM-DD_traces/                ← per-test trace.zip + error-context.md
@@ -207,7 +210,7 @@ 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.
-3. **Upload each artefact to the portal**:
+4. **Upload each artefact to the portal**:
    ```bash
    devaudit push <project-slug> REQ-XXX <evidence-type> <file> \
      --release "v$(date +%Y.%m.%d)" --create-release-if-missing \
@@ -215,9 +218,9 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
      --git-sha "$(git rev-parse HEAD)" \
      --branch "$(git rev-parse --abbrev-ref HEAD)"
    ```
-   Evidence types: `screenshot`, `e2e_result`, `test_report`, `audit_log`, `compliance_document`, `manual_upload`.
-4. **Verify uploads landed.** `gh api` or `curl` against `https://devaudit.metasession.co/projects/<slug>/requirements/REQ-XXX/evidence` should show every artefact.
-5. **Update `compliance/RTM.md`** with portal links for each evidence row.
+   Evidence types: `screenshot`, `e2e_result`, `test_report`, `audit_log`, `compliance_document`, `manual_upload`, `srs_alignment` (from step 1).
+5. **Verify uploads landed.** `gh api` or `curl` against `https://devaudit.metasession.co/projects/<slug>/requirements/REQ-XXX/evidence` should show every artefact.
+6. **Update `compliance/RTM.md`** with portal links for each evidence row.
 
 ### Phase 4 — Submit for UAT review (SDLC stage 4)
 

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

@@ -84,5 +84,14 @@
   "production_review": {
     "enabled": true,
     "terminal_status": "prod_review"
+  },
+
+  "_comment_requirements_aligner": "requirements-aligner skill toggles (DevAudit-Installer#119, v0.1.42+). Controls when the skill blocks vs advises. block_on_stage_1=false (default) means the skill advises on AC-to-SRS mapping at plan APPROVAL but doesn't block; flip to true once docs/SRS.md is populated enough for the check to be reliably surfacing real drift (not false-positives on sparse SoT). block_on_stage_3=true means the per-REQ srs-alignment.md artefact is required before Stage 3 completes — the per-REQ evidence is the hard gate. auto_file_followup_issue=false means the skill never opens GitHub issues automatically; if gaps are detected and operator defers, operator files follow-up manually. ramp_up_runs=5 means the first 5 invocations on a project are audit-only regardless of block_on_stage_1, so legacy projects with sparse SRS get time to populate before blocking enforces.",
+  "requirements_aligner": {
+    "enabled": true,
+    "block_on_stage_1": false,
+    "block_on_stage_3": true,
+    "auto_file_followup_issue": false,
+    "ramp_up_runs": 5
   }
 }