@metasession.co/devaudit-cli 0.1.42 → 0.1.44

package/package.json

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

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

@@ -25,7 +25,7 @@ description: Define a new requirement in the RTM, classify risk, create implemen
 
 ### Step 1: Identify the GitHub Issue
 
-Every tracked change starts from a GitHub Issue. The issue provides the *what* and *why*; the RTM provides the compliance audit trail.
+Every tracked change starts from a GitHub Issue. The issue provides the _what_ and _why_; the RTM provides the compliance audit trail.
 
 - If the user references an issue number (e.g., `#123`): fetch its title, description, and labels using `gh issue view 123`.
 - If the user describes work without an issue: ask **"Is there a GitHub Issue for this, or should we create one?"**
@@ -42,11 +42,11 @@ The next ID is one higher (e.g., if the last is REQ-007, use REQ-008).
 
 ### Step 3: Classify Risk Level
 
-| Risk Level | Criteria |
-|---|---|
-| **Low** | Internal tools, no regulated data, no auth changes |
+| Risk Level | Criteria                                                         |
+| ---------- | ---------------------------------------------------------------- |
+| **Low**    | Internal tools, no regulated data, no auth changes               |
 | **Medium** | Touches PII, user-facing features, API changes, new dependencies |
-| **High** | Security, payments, RBAC, data handling, authentication |
+| **High**   | Security, payments, RBAC, data handling, authentication          |
 
 AI involvement raises risk by one level when touching Medium or High categories. See Test Policy for the full risk matrix.
 
@@ -68,11 +68,12 @@ mkdir -p compliance/evidence/REQ-XXX
 
 ### Step 6: Implementation Plan (MEDIUM/HIGH Risk — Required)
 
-For MEDIUM and HIGH risk requirements, create an implementation plan before defining test scope. The implementation plan defines *what code changes are needed* — the test scope is then derived from it.
+For MEDIUM and HIGH risk requirements, create an implementation plan before defining test scope. The implementation plan defines _what code changes are needed_ — the test scope is then derived from it.
 
 **Skip this step** for LOW risk requirements — proceed directly to Step 7.
 
 **6a. Explore the codebase:**
+
 - Understand existing patterns, models, services, and API routes relevant to the change
 - Identify files that will be created, modified, or affected
 
@@ -89,25 +90,35 @@ Create `compliance/evidence/REQ-XXX/implementation-plan.md`:
 **Date:** [YYYY-MM-DD]
 
 ## Approach
+
 [1-3 sentences describing the overall approach]
 
 ## Files to Create
+
 - `path/to/new-file.ts` — [purpose]
 
 ## Files to Modify
+
 - `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"]
 
 ## Risks / Considerations
-- [Anything that could go wrong or needs special attention]
+
+> Populated by the [`risk-register-keeper` skill](../skills/risk-register-keeper/SKILL.md) at Stage 1 for MEDIUM/HIGH risk REQs (LOW skipped by default per `sdlc-config.json:risk_register_keeper.stage_1_min_risk_class`). The skill identifies discrete risks the change introduces, allocates `RISK-NNN` per project, drafts canonical rows in `compliance/risk-register.md`, and injects the RISK-NNN reference list here (replacing the inline bullets). Don't author this section inline as bullets — the persistent risk record lives in `compliance/risk-register.md`, not buried in the plan.
+
+- RISK-NNN — <title> (`compliance/risk-register.md`) — Operator edits canonical row + signs off residual rating before APPROVAL — OR — @risk-deferred — <rationale>
 
 ## Post-Deploy Actions
+
 - [Data migrations, backfill scripts, schema changes — or "None"]
 - [If any: create script in `scripts/`, document exact command and target environment]
 ```
@@ -115,6 +126,7 @@ Create `compliance/evidence/REQ-XXX/implementation-plan.md`:
 ### WAIT CHECKPOINT: Implementation Plan Review
 
 **Present the implementation plan to the developer.** Summarize:
+
 - Approach and rationale
 - Files to create/modify
 - Architecture decisions
@@ -275,6 +287,7 @@ EOF
 ### WAIT CHECKPOINT: Test Scope Review
 
 **Present the test scope to the developer.** Summarize:
+
 - Risk classification and rationale
 - Test approach (which additional testing applies)
 - Acceptance criteria
@@ -330,6 +343,7 @@ EOF
 ### WAIT CHECKPOINT: Test Plan Review
 
 **Present the test plan to the developer.** Summarize:
+
 - Tests to add, update, and remove
 - How acceptance criteria map to specific tests
 - Any non-functional testing required

package/sdlc/files/_common/Implementation_Plan_TEMPLATE.md

@@ -21,27 +21,27 @@ authored_at: "REPLACE — YYYY-MM-DD"
 
 **Closes clauses** (every implementation plan satisfies all four):
 
-| Clause | What this plan must contain |
-|---|---|
-| **ISO 29119 §3.4** Test Plan | Acceptance criteria + the strategy for verifying each one. Reference the per-REQ `test-plan.md` if it lives separately. |
-| **ISO 27001 A.8.25** Secure development life cycle | Threat model + secure-design considerations (auth, data handling, dependencies, secrets). |
+| Clause                                                    | What this plan must contain                                                                                                                                       |
+| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **ISO 29119 §3.4** Test Plan                              | Acceptance criteria + the strategy for verifying each one. Reference the per-REQ `test-plan.md` if it lives separately.                                           |
+| **ISO 27001 A.8.25** Secure development life cycle        | Threat model + secure-design considerations (auth, data handling, dependencies, secrets).                                                                         |
 | **GDPR Art. 25** Data protection by design and by default | Per-purpose data flows; minimisation; lawful basis; retention. **Required for any REQ that processes personal data; explicit "no personal data" callout if not.** |
-| **EU AI Act Art. 11** Technical documentation (Annex IV) | When the REQ touches AI / model behaviour: model provenance, prompt sources, oversight path. **Explicit "no AI in scope" callout if not.** |
+| **EU AI Act Art. 11** Technical documentation (Annex IV)  | When the REQ touches AI / model behaviour: model provenance, prompt sources, oversight path. **Explicit "no AI in scope" callout if not.**                        |
 
 Each section below maps to one (or more) of these clauses. Don't delete sections — mark with "N/A — <reason>" if the clause genuinely doesn't apply.
 
 ## 1. Goal + acceptance criteria
 
-> *Closes ISO 29119 §3.4 — test plan*
+> _Closes ISO 29119 §3.4 — test plan_
 
 - **Goal:** REPLACE — one sentence describing what this REQ delivers, no jargon.
 - **Acceptance criteria:**
 
-| AC | Description | SRS item it traces to |
-|---|---|---|
+| 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 |
-| … | | |
+| 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).
 
@@ -50,22 +50,49 @@ Each section below maps to one (or more) of these clauses. Don't delete sections
 - **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
 
-> *Closes ISO 27001 A.8.25 — secure development life cycle*
+> _Populated by the [`adr-author` skill](../skills/adr-author/SKILL.md) at Stage 1 plan APPROVAL._
 
-| Threat | Likelihood | Impact | Mitigation |
-|---|---|---|---|
-| REPLACE — e.g. SQL injection via X param | REPLACE | REPLACE | REPLACE |
-| REPLACE — e.g. unauthenticated access to Y route | REPLACE | REPLACE | REPLACE |
+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_
+
+| Threat                                           | Likelihood | Impact  | Mitigation |
+| ------------------------------------------------ | ---------- | ------- | ---------- |
+| REPLACE — e.g. SQL injection via X param         | REPLACE    | REPLACE | REPLACE    |
+| REPLACE — e.g. unauthenticated access to Y route | REPLACE    | REPLACE | REPLACE    |
 
 **Secrets / credentials:** REPLACE — does this REQ handle any? If yes, how stored, rotated, scoped?
 
 **Dependencies introduced:** REPLACE — list new npm/pip packages; flag any with known CVEs or transitive concerns.
 
-## 4. Data protection (GDPR Art. 25)
+### Risk register entries
+
+> _Populated by the [`risk-register-keeper` skill](../skills/risk-register-keeper/SKILL.md) for MEDIUM/HIGH risk REQs at Stage 1 plan APPROVAL. The persistent risk record lives in [`compliance/risk-register.md`](../../risk-register.md); this section references the RISK-NNN entries this REQ opened, mitigated, or accepted._
+
+When **risk class is MEDIUM or HIGH**, expect a list like:
+
+- **RISK-NNN — <title>** — Status: OPEN. Opened by `risk-register-keeper`. Operator edits canonical row + signs off residual rating before plan APPROVAL.
+- **RISK-NNN — <title>** — Status: MITIGATED. Controls landing in this PR close the residual.
+
+When **risk class is LOW** OR no register-worthy risk is identified, write: _"@risk-deferred: <one-line rationale>"_ — the negative case is audit evidence too. Don't leave this section empty.
+
+## 5. Data protection (GDPR Art. 25)
 
-> *Closes GDPR Art. 25 — data protection by design*
+> _Closes GDPR Art. 25 — data protection by design_
 
 **Personal data processed by this REQ:** REPLACE — yes / no.
 
@@ -83,11 +110,11 @@ If **yes**, fill in:
   - Is a DPIA required? REPLACE — yes (file under `compliance/governance/dpia-<reqid>.md`) / no / N/A
 - **Cross-border transfers:** REPLACE — none / specify mechanism
 
-If **no**, write: *"N/A — this REQ does not process personal data. <Why — e.g. UI-only change, internal-routing refactor, dev-tooling.>"*
+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*
+> _Closes EUAIA Art. 11 — technical documentation_
 
 **AI / ML in scope for this REQ:** REPLACE — yes / no.
 
@@ -101,15 +128,15 @@ If **yes**, fill in:
 - **Cross-references:**
   - Is `compliance/governance/ai-disclosure.md` updated? REPLACE — yes / no / N/A
 
-If **no**, write: *"N/A — this REQ does not introduce or change AI behaviour. <Why.>"*
+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:
 
@@ -118,7 +145,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/governance/risk-register.md.template

@@ -0,0 +1,116 @@
+---
+title: 'Risk register'
+project: 'REPLACE — project name'
+maintained_by: 'risk-register-keeper skill (DevAudit-Installer v0.1.44+)'
+scoring_matrix: 'likelihood × impact (3×3)'
+last_reviewed_at: 'REPLACE — YYYY-MM-DD'
+review_cadence_days: 90
+---
+
+> ⚠️ **STARTER TEMPLATE — REPLACE BEFORE COMMITTING.**
+> Installed on demand via `devaudit bootstrap-governance` as a starting point.
+> It does **not** describe your project's actual risks. The `risk-register-keeper` skill (DevAudit-Installer#121) maintains this file as REQs land, incidents close, and accepted risks come due for re-validation.
+> Auditors reject unedited stubs.
+
+# Risk register — REPLACE project
+
+**Framework coverage:** primary audit surface for `SOC2.CC3.2` (Risk identification and assessment), `SOC2.CC3.4` (Risk monitoring), `ISO27001.A.5.1` (Policies for information security — risk-driven), `ISO27001.A.6.2` (Risk management procedures), `GDPR.Art-32` (Security of processing — risk-based) when a risk pertains to personal-data processing.
+
+**Maintained by:** the [`risk-register-keeper` skill](../../.claude/skills/risk-register-keeper/SKILL.md) at Stage 1 (MEDIUM/HIGH risk classification — open new entries), at incident close (residual-risk entries), and at Stage 3 (per-REQ `risk-assessment.md` artefact summarises entries touched).
+
+**Scoring:** likelihood × impact, 3×3 matrix (low / medium / high). CVSS-aware scoring deferred to Phase B.
+
+---
+
+## Scoring matrix
+
+| Inherent + Residual rating | Likelihood (frequency / ease-of-exploit) | Impact (worst-case if realised) |
+|---|---|---|
+| **Low** | Unlikely in a typical year; requires unusual access or coincidence | Recoverable inconvenience; no regulatory exposure |
+| **Medium** | Plausible within a year; standard skill or access | Recoverable but disruptive; possible reportable incident |
+| **High** | Probable within months; trivial to trigger | Material loss; regulatory reporting required |
+
+Residual = post-mitigation rating. **A risk's residual rating drives review cadence:** Low = annual, Medium = quarterly, High = monthly until reduced.
+
+---
+
+## OPEN risks
+
+> Risks currently being treated — controls planned but not yet demonstrated effective, or monitoring continues.
+
+### RISK-001 — REPLACE one-line title
+
+- **Status:** OPEN
+- **Opened:** YYYY-MM-DD (REQ-XXX) — REPLACE
+- **Owner:** REPLACE — operator
+- **Description:** REPLACE — what the risk is, in operator-readable terms (2-3 sentences).
+- **Inherent likelihood × impact:** REPLACE (e.g. medium × high)
+- **Mitigations planned / in flight:** REPLACE — list controls being applied
+- **Residual likelihood × impact (post-mitigation):** REPLACE
+- **Framework cross-references:** REPLACE — ISO27001.A.X.Y / SOC2.CC3.2 / GDPR.Art-32 (as applicable)
+- **Review due:** YYYY-MM-DD (default: monthly for OPEN-HIGH, quarterly for OPEN-MEDIUM, annually for OPEN-LOW)
+- **Cross-links:** REPLACE — REQ-XXX implementation plan / ADR-NNN / incident-report-N
+
+---
+
+## MITIGATED risks
+
+> Risks whose controls have landed and been demonstrated effective. Residual rating ≤ Low. Periodic re-validation confirms controls remain effective.
+
+### RISK-NNN — example template
+
+- **Status:** MITIGATED
+- **Opened:** YYYY-MM-DD (REQ-XXX) / **Mitigated:** YYYY-MM-DD
+- **Owner:** REPLACE
+- **Description:** REPLACE
+- **Original inherent likelihood × impact:** medium × high
+- **Mitigations applied:** REPLACE — list controls + evidence reference (e.g. "rate limit middleware shipped REQ-042; verified via integration test in `__tests__/auth/rate-limit.test.ts`")
+- **Residual likelihood × impact:** low × low
+- **Framework cross-references:** REPLACE
+- **Re-validation due:** YYYY-MM-DD (default: annually for MITIGATED)
+- **Cross-links:** REPLACE
+
+---
+
+## ACCEPTED risks
+
+> Risks the operator has explicitly chosen to accept (typically: residual is tolerable + mitigation cost exceeds expected loss). Each acceptance needs sign-off + a periodic re-validation date.
+
+### RISK-NNN — example template
+
+- **Status:** ACCEPTED
+- **Opened:** YYYY-MM-DD / **Accepted:** YYYY-MM-DD
+- **Owner:** REPLACE
+- **Description:** REPLACE
+- **Inherent likelihood × impact:** REPLACE
+- **Mitigations applied:** REPLACE — partial mitigations + why full mitigation isn't pursued
+- **Residual likelihood × impact:** REPLACE — tolerated
+- **Acceptance rationale:** REPLACE — why the operator judges this acceptable (cost / use-case / compensating controls / regulatory context)
+- **Acceptance sign-off:** REPLACE — operator name + date. For organisations with separate risk-owner role, the risk-owner signs off here, not the implementing engineer.
+- **Framework cross-references:** REPLACE
+- **Re-validation due:** YYYY-MM-DD (default: every 365d; sooner if the risk landscape changes)
+- **Cross-links:** REPLACE
+
+---
+
+## CLOSED risks
+
+> Risks that no longer apply (removed scope, deprecated dependency, etc.). Kept on the register for audit-trail completeness — auditors examine what was closed and why.
+
+### RISK-NNN — example template
+
+- **Status:** CLOSED
+- **Opened:** YYYY-MM-DD / **Closed:** YYYY-MM-DD
+- **Owner:** REPLACE
+- **Description:** REPLACE
+- **Close rationale:** REPLACE — why this risk no longer applies (e.g. "feature deprecated REQ-080", "dependency removed REQ-095", "external dependency now provides the control")
+- **Cross-links:** REPLACE
+
+---
+
+## Audit-trail rules
+
+- **Append-only edits.** Never delete a RISK-NNN entry. Status transitions (OPEN → MITIGATED → ACCEPTED → CLOSED) are visible audit history.
+- **Re-validation cadence is binding.** When an ACCEPTED risk's `Re-validation due:` date passes, the operator must either re-sign or change status. Stale acceptances are an audit finding.
+- **Cross-linking is bidirectional.** When an entry references an incident report, the incident report's frontmatter references the entry. When an entry references an ADR, the ADR references the entry.
+- **`solo_with_gap` projects** must carry a documented control-gap entry referencing `SOC2.CC8.1` — see the `risk-register-keeper` skill's Phase 4 for the canonical entry shape.

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.