@metasession.co/devaudit-cli 0.1.41 → 0.1.43

package/package.json

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

package/sdlc/files/_common/1-plan-requirement.md

@@ -98,8 +98,10 @@ Create `compliance/evidence/REQ-XXX/implementation-plan.md`:
 - `path/to/existing-file.ts` — [what changes and why]
 
 ## Architecture Decisions
-- [Key decision 1 and rationale]
-- [Key decision 2 and rationale]
+
+> Populated by the [`adr-author` skill](../skills/adr-author/SKILL.md) at Stage 1 plan APPROVAL. The skill applies a decision tree (new third-party dependency / new database, cache, or queue / new external service / pattern change spanning > 3 files / HIGH-CRITICAL risk) and either drafts `docs/ADR/ADR-NNN-<slug>.md` + injects "Produced ADR-NNN: <title>" here, or injects "No ADR needed — <one-line rationale>" so the question is visibly asked and answered. Don't author this section inline as bullets — the persistent decision lives in `docs/ADR/`, not buried in the plan.
+
+- ADR-NNN — <title> (`docs/ADR/ADR-NNN-<slug>.md`) — Operator edits stub + flips to *Accepted* before APPROVAL — OR — No ADR needed — <rationale>
 
 ## Dependencies
 - [New packages needed, or "None"]

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,16 +36,37 @@ 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
 
 - **In scope:** REPLACE — list every file / module / surface the change touches.
 - **Out of scope:** REPLACE — adjacent areas the change deliberately leaves alone.
 
-## 3. Threat model + security considerations
+## 3. Architecture decisions
+
+> *Populated by the [`adr-author` skill](../skills/adr-author/SKILL.md) at Stage 1 plan APPROVAL.*
+
+Either an ADR-NNN reference list (when the skill judges the REQ architecturally significant) OR an explicit "no ADR" rationale. **Don't author this section inline as bullets** — the `adr-author` skill applies its decision tree and either drafts a `docs/ADR/ADR-NNN-<slug>.md` stub the operator edits, or annotates the no-ADR case.
+
+When **ADR warranted**:
+
+- **ADR-NNN — <decision title>** — Drafted by `adr-author`. File at `docs/ADR/ADR-NNN-<slug>.md`. Operator edits stub to canonical prose + flips status to *Accepted* before plan APPROVAL.
+
+When **No ADR needed**:
+
+- **No ADR needed** — REPLACE one-line rationale. Examples: "Bug fix touching only `lib/services/order-service.ts:applyDiscount` — no structural change." / "CSS-only adjustment — no behavioural or dependency change." / "Patch-level dependency bump with no API change."
+
+The negative case is audit evidence too — auditors examine "no ADR — <rationale>" to confirm the question was asked. Never leave this section empty.
+
+## 4. Threat model + security considerations
 
 > *Closes ISO 27001 A.8.25 — secure development life cycle*
 
@@ -58,7 +79,7 @@ Each section below maps to one (or more) of these clauses. Don't delete sections
 
 **Dependencies introduced:** REPLACE — list new npm/pip packages; flag any with known CVEs or transitive concerns.
 
-## 4. Data protection (GDPR Art. 25)
+## 5. Data protection (GDPR Art. 25)
 
 > *Closes GDPR Art. 25 — data protection by design*
 
@@ -80,7 +101,7 @@ If **yes**, fill in:
 
 If **no**, write: *"N/A — this REQ does not process personal data. <Why — e.g. UI-only change, internal-routing refactor, dev-tooling.>"*
 
-## 5. AI / model considerations (EU AI Act Art. 11)
+## 6. AI / model considerations (EU AI Act Art. 11)
 
 > *Closes EUAIA Art. 11 — technical documentation*
 
@@ -98,13 +119,13 @@ If **yes**, fill in:
 
 If **no**, write: *"N/A — this REQ does not introduce or change AI behaviour. <Why.>"*
 
-## 6. Rollback plan
+## 7. Rollback plan
 
 - **Reversible via:** REPLACE — git revert / migration down / config flip / etc.
 - **Data implications of rollback:** REPLACE — any data written by the new code that an older version can't read?
 - **Notification path if rollback during a release:** REPLACE — who hears, how quickly?
 
-## 7. Verification
+## 8. Verification
 
 How the team will know the REQ is correct in production:
 
@@ -113,7 +134,7 @@ How the team will know the REQ is correct in production:
 - **Manual smoke after deploy:** REPLACE — bullet-list, or "none" with reason
 - **Monitoring / alerting:** REPLACE — what dashboards / alerts the change adds or relies on
 
-## 8. Sign-off
+## 9. Sign-off
 
 - **Plan reviewer (eng):** REPLACE — name + date
 - **Plan reviewer (security / DPO):** REPLACE — when GDPR or threat-model sections are non-trivial; otherwise "N/A"

package/sdlc/files/_common/skills/adr-author/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: adr-author
+description: Catch the moment a tracked change makes an architecturally significant decision and either draft the canonical `docs/ADR/ADR-NNN-<slug>.md` artefact or document why no ADR was needed. Runs at Stage 1 (plan APPROVAL) and Stage 3 (evidence pack) of the SDLC. Decides "is this REQ architecturally significant?" via a calibrated heuristic (new third-party dependency, new database/cache/queue, new external service, pattern change spanning >3 files, HIGH/CRITICAL risk class), drafts a Context/Decision/Consequences/Alternatives/Status stub when warranted, allocates the next `ADR-NNN` ID, injects an ADR-NNN reference into the implementation plan, and produces a per-REQ `compliance/evidence/REQ-XXX/architecture-decision.md` artefact. Use when invoking on a single REQ ("draft an ADR for REQ-066", "does this REQ need an ADR?", "is the architectural decision documented?"); when `sdlc-implementer` delegates at Stage 1 plan-approval or Stage 3 evidence-compilation; when an operator asks for ADR-worthiness judgement on an in-flight branch. Do NOT use for authoring full ADR prose end-to-end (the operator edits the stub to canonical wording); for supersession-lifecycle handling (deferred to Phase B); for cross-link maintenance between ADRs and risk-register entries (that's `risk-register-keeper`); for framework-clause mapping of the `architecture_decision` evidence type (that's META-COMPLY's `framework-registry-auditor`).
+---
+
+# ADR Author
+
+Catches the moment a tracked REQ makes an architecturally significant decision that should produce a persistent record — and either drafts the ADR or documents why no ADR was needed. Sibling of [`requirements-aligner`](../requirements-aligner/SKILL.md) and `risk-register-keeper` in the SoT-alignment skill family.
+
+The skill is **Phase A scope** (per [DevAudit-Installer#120](https://github.com/metasession-dev/DevAudit-Installer/issues/120)): Stage 1 + Stage 3 hooks only. Supersession-lifecycle, stale-decision detection, and cross-link maintenance between ADRs and other SoT artefacts all defer to Phase B — the v1 surface is the safest enforcement points.
+
+## What this skill owns
+
+| Artefact | Lives at | Tier |
+|---|---|---|
+| `docs/ADR/ADR-NNN-<slug>.md` (the SoT, project-spanning) | Top-level project docs | 2 (project strategy) |
+| `compliance/evidence/REQ-XXX/architecture-decision.md` (per-REQ Tier 3 evidence) | Per-REQ evidence directory | 3 (per-REQ) |
+
+The skill does **not** own the canonical ADR prose. It drafts a stub the operator edits to publication-grade wording. Inventing decision rationale without operator review is exactly the kind of silent-drift this skill exists to prevent.
+
+## Scope
+
+**In scope**
+
+- Phase 1 (Stage-1 hook) — judge "is this REQ architecturally significant?" → if yes, allocate `ADR-NNN` + draft Context/Decision/Consequences/Alternatives/Status stub → inject ADR-NNN reference into implementation plan's *Architecture Decisions* section.
+- Phase 2 (Stage-3 hook) — drop `compliance/evidence/REQ-XXX/architecture-decision.md` pointing at the ADR file (or recording the no-ADR rationale).
+- Per-REQ ADR-worthiness audit (operator invocation).
+
+**Out of scope**
+
+- Drafting canonical ADR prose end-to-end — the skill drafts a stub; the operator authors final wording.
+- Supersession lifecycle — when ADR-007 supersedes ADR-003, both stay on disk; ADR-003's status flips to `Superseded by ADR-007`. Deferred to Phase B.
+- Stale-decision detection — when the file referenced by ADR-007's *Decision* section is heavily modified in a new REQ without producing a new ADR. Deferred to Phase B.
+- Cross-link maintenance to SRS items (`requirements-aligner`'s domain) or risk-register entries (`risk-register-keeper`'s domain) — the skills cross-reference each other in their stubs but Phase B owns the bidirectional consistency.
+- Framework-clause mapping of the `architecture_decision` 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; Phase 3 is the utility audit; Phase 4 reports.
+
+### Phase 0 — Route
+
+Determine what's being decided:
+
+- **Stage-1 plan APPROVAL** — `sdlc-implementer` (or operator) says *"check ADR-worthiness for REQ-XXX before approving the plan"* / *"does this need an ADR?"* → Phase 1.
+- **Stage-3 evidence pack** — `sdlc-implementer` (or operator) says *"drop the architecture-decision.md for REQ-XXX"* → Phase 2.
+- **Per-REQ ad-hoc audit** — operator says *"is REQ-XXX's architectural decision documented?"* / *"audit ADR-worthiness across this branch"* → Phase 3.
+
+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 — Read the file list + diff.** Identify which files the REQ touches.
+
+**Step 2 — Apply the ADR-worthiness decision tree.** The skill judges *architectural significance* via these signals — any one matching ⇒ ADR warranted:
+
+| Signal | Examples | Verdict |
+|---|---|---|
+| New third-party runtime dependency | adding `redis`, `bull`, a new ORM, a new auth provider package | ADR |
+| New external service | introducing Stripe, Twilio, a new SaaS integration | ADR |
+| New database / cache / queue tier | adding Redis alongside Postgres, swapping MongoDB for Postgres | ADR |
+| Pattern change spanning > 3 files | moving from REST handlers to RPC, swapping auth flow across the API surface | ADR |
+| Schema-level data model change | new tables that other tables FK to, fundamental relationship changes | ADR |
+| Risk classification HIGH or CRITICAL | per `Test_Policy.md` §Risk-Based Testing | ADR (operator confirms) |
+| File-path signal | `sdlc-config.json:adr_author.file_paths_signal_architecture` matches a touched file | ADR (operator confirms) |
+| Bug fix touching ≤ 3 files in `app/` or `lib/` | a typo, a copy edit, a null-guard, a one-place validation | no ADR |
+| Single-file refactor | extracting one function, renaming one variable | no ADR |
+| Styling tweak | CSS-only, Tailwind class shuffle | no ADR |
+| Dependency bump | `npm update foo` with no API change | no ADR |
+| Documentation | `docs/`, `README.md`, doc-comments | no ADR |
+
+**Step 3 — Branch on verdict:**
+
+- **ADR warranted** → Phase 1 Step 4 (draft the stub).
+- **No ADR** → Phase 1 Step 7 (inject the no-ADR rationale).
+- **Ambiguous** → surface a candidate verdict + reasoning to the operator and ask. The operator can confirm or override. Do NOT silently default.
+
+**Step 4 — Allocate the next `ADR-NNN`.** Scan `docs/ADR/` for the max-existing `ADR-NNN` (zero-padded to three digits where the project's convention has it) and propose `+1`. If `docs/ADR/` doesn't exist yet, create it + allocate `ADR-001`. The skill does NOT support cross-branch ID coordination — if two parallel branches both consume the same next-free ID, the git merge on the directory is the canonical conflict signal. Re-run the skill post-merge to re-allocate.
+
+**Step 5 — Draft the stub `docs/ADR/ADR-NNN-<slug>.md`.** The slug is a kebab-case fragment of the decision (max 6 words). Format:
+
+```markdown
+---
+adr_id: "ADR-NNN"
+status: "Proposed"
+date: "YYYY-MM-DD"
+authored_by: "REPLACE — operator / agent"
+related_reqs: ["REQ-XXX"]
+supersedes: []
+superseded_by: null
+---
+
+# ADR-NNN: <decision title>
+
+## Status
+
+**Proposed** (DRAFT — operator to flip to *Accepted* on plan APPROVAL)
+
+## Context
+
+REPLACE — what forces (constraints, requirements, tradeoffs) motivate this decision? Two or three sentences. Reference REQ-XXX and any SRS items it traces to.
+
+## Decision
+
+REPLACE — the choice made. One paragraph. Specific (not "we will use a queue" — "we will use Redis Streams as the queue substrate; consumers are FastAPI workers using `redis-py` ≥ 5.x").
+
+## Consequences
+
+REPLACE — what follows. List both **good** and **bad** consequences honestly.
+
+- **Good:** REPLACE
+- **Bad:** REPLACE
+- **Neutral / tradeoffs:** REPLACE
+
+## Alternatives considered
+
+REPLACE — what other paths were on the table and why they were ruled out. At least one alternative; "we considered nothing else" is almost never honest.
+
+- **Alternative 1:** REPLACE — ruled out because REPLACE
+- **Alternative 2:** REPLACE — ruled out because REPLACE
+
+## Cross-references
+
+- Implementation plan: `compliance/plans/REQ-XXX/implementation-plan.md`
+- SRS items: REPLACE — list `REQ-AREA-NNN` items this decision affects, from `requirements-aligner` output
+- Risk register: REPLACE — list `RISK-NNN` entries this decision touches, from `risk-register-keeper` output (when that skill exists)
+- Supersedes / superseded-by: REPLACE — fill if this ADR replaces a prior one
+```
+
+The stub is **draft-quality**; the operator edits each REPLACE marker before flipping the status from *Proposed* to *Accepted*.
+
+**Step 6 — Inject ADR-NNN reference into the implementation plan.** The plan's *Architecture Decisions* section (converted from inline bullets to ADR-NNN references in this PR — see `Implementation_Plan_TEMPLATE.md`) gets a row added:
+
+```markdown
+## Architecture decisions
+
+- **ADR-NNN — <decision title>** — Proposed by `adr-author` skill. Draft at `docs/ADR/ADR-NNN-<slug>.md`. Operator edits + flips status to *Accepted* before plan APPROVAL.
+```
+
+**Step 7 — No-ADR rationale.** When the verdict is *no ADR*, the plan's *Architecture decisions* section gets:
+
+```markdown
+## Architecture decisions
+
+- **No ADR needed** — REPLACE one-line rationale. Examples: "Bug fix touching only `lib/services/order-service.ts:applyDiscount` — no structural change." / "CSS-only adjustment to dashboard layout — no behavioural or dependency change." / "Dependency bump from `foo@1.2.3` to `foo@1.2.5` (patch-level, no API change)."
+```
+
+The annotation is visible audit evidence that the *question was asked and answered* — auditors examine the negative case as well as the positive.
+
+**Step 8 — Block plan APPROVAL** until each REQ has either:
+- (a) an ADR file in this PR (status: Proposed → Accepted by operator), OR
+- (b) an explicit "No ADR needed — <rationale>" annotation.
+
+The block is configurable via `sdlc-config.json` — see *Configuration* below. Per the [#119 review](https://github.com/metasession-dev/DevAudit-Installer/issues/119#issuecomment-4631840651) defaults, advisory-with-strong-recommend in v1 (`block_on_stage_1: false`).
+
+### 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/architecture-decision.md`.** Format:
+
+```markdown
+---
+req: REQ-XXX
+generated_by: adr-author
+generated_at: <ISO timestamp>
+---
+
+# Architecture decision — REQ-XXX
+
+## Outcome
+
+REPLACE — one of:
+
+- "**Produced ADR-NNN:** <title> (`docs/ADR/ADR-NNN-<slug>.md`)" — when an ADR was authored in this cycle
+- "**No ADR needed** — <rationale>" — when the no-ADR branch was taken
+
+## Detail
+
+When **Produced ADR-NNN**:
+
+- **ADR file:** `docs/ADR/ADR-NNN-<slug>.md`
+- **Status:** Accepted (operator-confirmed during plan APPROVAL)
+- **Summary:** REPLACE — one sentence from the ADR's *Decision* section
+- **Affected files:** REPLACE — the file-path signals that triggered the verdict
+- **Cross-references:** REPLACE — SRS items, risk-register entries
+
+When **No ADR needed**:
+
+- **Rationale:** REPLACE — one-line description copied from the plan's *Architecture decisions* section
+- **Signals examined:** REPLACE — which signals from the decision tree were checked + how each scored
+
+## Operator sign-off
+
+I have reviewed the ADR-worthiness verdict above and confirm:
+
+- [ ] The verdict (ADR or no-ADR) matches the actual scope of this REQ.
+- [ ] If ADR: the file at `docs/ADR/ADR-NNN-<slug>.md` is edited from stub to canonical prose and status is Accepted.
+- [ ] If no-ADR: the rationale is specific enough that an auditor reading this in 12 months would agree.
+
+**Reviewer:** <operator-name>
+**Date:** <YYYY-MM-DD>
+```
+
+**Step 2 — Tag for upload.** The CI's `compliance-evidence.yml` uploads this file as `evidence_type=architecture_decision` (added to META-COMPLY's `EVIDENCE_TYPE_REGISTRY` in the paired sub-PR). The framework-coverage matrix maps this to clauses per `framework-registry-auditor`'s review — see the META-COMPLY-side PR for the final clause attributions (v1 may ship orphan-by-design if the auditor rejects proposed mappings; see [`requirements-aligner`](../requirements-aligner/SKILL.md) for the precedent).
+
+**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.
+
+### 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 *"does REQ-XXX need an ADR?"* outside the SDLC orchestration flow, or runs *"audit ADR-worthiness across this branch"* to surface gaps.
+
+### Phase 4 — Report
+
+- For Phase 1 — the plan's injected section + the block/allow decision.
+- For Phase 2 — the artefact path + summary line.
+- For Phase 3 — markdown report (per-REQ verdict + reasoning).
+
+## Configuration (sdlc-config.json)
+
+```json
+{
+  "adr_author": {
+    "enabled": true,
+    "block_on_stage_1": false,
+    "block_on_stage_3": true,
+    "file_paths_signal_architecture": [
+      "lib/services/",
+      "lib/repositories/",
+      "prisma/schema.prisma",
+      "infra/"
+    ]
+  }
+}
+```
+
+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 heuristic is calibrated on the project (i.e. the skill's ADR/no-ADR verdicts have agreed with operator judgement on the last N runs).
+- `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).
+- `file_paths_signal_architecture` — list of file paths/prefixes that should signal an architectural change when touched. Defaults cover the common load-bearing surfaces; operators add project-specific paths (e.g. `infra/terraform/`, `app/auth/`).
+
+## Principles
+
+**Don't author the ADR prose.** The skill drafts a stub the operator edits to publication-grade wording. Inventing decision rationale without operator review is exactly the kind of silent-drift this skill exists to prevent.
+
+**Calibrate, don't presume.** The decision tree above is a starting heuristic, not a hard rule. When a verdict surfaces on the edge — say a single-file change that introduces a new dependency — surface the candidate verdict + reasoning and ask. The operator can confirm or override. False-positive ADRs (drafting noise the team has to edit-and-delete) are worse than false-negative no-ADRs (the operator catches the gap in review and asks for one).
+
+**Block at Stage 3, advise at Stage 1.** The implementation plan can carry "No ADR needed — <rationale>" and ship. The evidence pack cannot — the per-REQ `architecture-decision.md` artefact must exist before Stage 3 completes. Symmetric with `requirements-aligner` per the [#119 review](https://github.com/metasession-dev/DevAudit-Installer/issues/119#issuecomment-4631840651).
+
+**Sibling-skill awareness.** When this skill drafts an ADR, cross-link the SRS items the decision affects (from `requirements-aligner`'s output) and the risk-register entries the decision touches (from `risk-register-keeper` when that skill ships). The three SoT-alignment skills work together; each produces its own per-REQ Tier 3 artefact but they share the per-REQ context. v1 carries the cross-references as inline references the operator fills in; Phase B will own bidirectional consistency.
+
+**The negative case is audit evidence too.** A "No ADR needed — <rationale>" annotation is what an auditor examines to confirm the question was asked. An empty *Architecture decisions* section is the silent-drift failure mode. Always inject one or the other; never leave the section unannotated.
+
+## References
+
+- [DevAudit-Installer#120](https://github.com/metasession-dev/DevAudit-Installer/issues/120) — the issue this skill closes, with the case study + 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` — *Architecture decisions* section converted from inline bullets to ADR-NNN reference list in this PR (companion change).
+- `sdlc/files/_common/1-plan-requirement.md` — stage-1 doc updated to point at the skill (companion change).
+- `sdlc/files/_common/skills/requirements-aligner/SKILL.md` — sibling skill (same SoT-alignment family); see for the symmetric shape (Stage 1 + Stage 3 hooks; advisory-then-blocking enforcement).
+- Sibling skill (forthcoming): `risk-register-keeper` (DevAudit-Installer#121).
+- Meta-reviewer (META-COMPLY): `framework-registry-auditor` reviews the `architecture_decision` evidence type's clause mappings before the META-COMPLY sub-PR opens. Per the [#119 sequencing](https://github.com/metasession-dev/DevAudit-Installer/issues/119#issuecomment-4631840651).
+- Existing ADRs in the framework itself: `DevAudit-Installer/docs/ADR/ADR-001-polyglot-sdlc-architecture.md`, `docs/devaudit-cli/ADR-001-language-and-distribution.md` — the pattern this skill maintains.

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).