@metasession.co/devaudit-cli 0.1.42 → 0.1.43

package/package.json

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

@@ -50,7 +50,23 @@ 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
+
+> *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*
 
@@ -63,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*
 
@@ -85,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*
 
@@ -103,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:
 
@@ -118,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/sdlc-implementer/SKILL.md

@@ -161,9 +161,10 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
 
    **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. **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.
+7. **Invoke `adr-author` to decide ADR-worthiness + draft the ADR if needed.** The plan's "Architecture decisions" section is no longer authored inline as bullets — `adr-author` applies its decision tree (new third-party dependency / new database/cache/queue / new external service / pattern change spanning >3 files / HIGH-CRITICAL risk class / file-path signals from `sdlc-config.json:adr_author.file_paths_signal_architecture`), allocates the next `ADR-NNN`, drafts a Context/Decision/Consequences/Alternatives/Status stub at `docs/ADR/ADR-NNN-<slug>.md`, and injects either *"Produced ADR-NNN: <title>"* or *"No ADR needed — <rationale>"* into the plan's section. Call via the standard Claude Code Skill mechanism (`Skill(name: "adr-author", …)`). Configurable via `sdlc-config.json:adr_author.block_on_stage_1`; advisory by default in v1.
+8. **Update `compliance/RTM.md`** with the new entry: REQ-XXX, title, risk class, linked issue, linked test cases (placeholder).
+9. **Post plan summary as an issue comment.** Format: TL;DR; Risk class + signals; Acceptance criteria (with SRS-IDs); Architectural decisions (ADR-NNN reference or no-ADR rationale); Technical approach (one paragraph); Dependencies; Test scope.
+10. **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)
 
@@ -194,14 +195,16 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
 
 ### Phase 3 — Compile evidence (SDLC stage 3)
 
-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:
+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` (visible in Documents tab + audit-pack export; v1 orphan-by-design per META-COMPLY framework-registry-auditor). Call via the standard Skill mechanism; don't inline the alignment logic.
+2. **Invoke `adr-author` to drop the per-REQ architecture-decision artefact.** The skill's Phase 2 produces `compliance/evidence/REQ-XXX/architecture-decision.md` — either *"Produced ADR-NNN: <title>"* with the file pointer, or *"No ADR needed — <rationale>"*. Operator sign-off block at the bottom. The artefact uploads with `evidence_type=architecture_decision`; clause attribution per the META-COMPLY framework-registry-auditor review. Call via the standard Skill mechanism.
+3. **Re-run the full test pack** with artefact capture:
    - `npm run test:e2e -- --reporter=html` (produces `playwright-report/`)
    - `npx vitest run --coverage` (produces `coverage/`)
-3. **Organise artefacts** under `compliance/evidence/REQ-XXX/` with date-prefixed naming:
+4. **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
+   ├── architecture-decision.md          ← produced in step 2 by adr-author
    ├── YYYY-MM-DD_e2e-results.json
    ├── YYYY-MM-DD_playwright-report/
    ├── YYYY-MM-DD_traces/                ← per-test trace.zip + error-context.md
@@ -210,7 +213,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.
-4. **Upload each artefact to the portal**:
+5. **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 \
@@ -218,9 +221,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`, `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.
+   Evidence types: `screenshot`, `e2e_result`, `test_report`, `audit_log`, `compliance_document`, `manual_upload`, `srs_alignment` (from step 1), `architecture_decision` (from step 2).
+6. **Verify uploads landed.** `gh api` or `curl` against `https://devaudit.metasession.co/projects/<slug>/requirements/REQ-XXX/evidence` should show every artefact.
+7. **Update `compliance/RTM.md`** with portal links for each evidence row.
 
 ### Phase 4 — Submit for UAT review (SDLC stage 4)
 

package/sdlc/files/ci/compliance-evidence.yml.template

@@ -34,6 +34,18 @@ jobs:
   upload-compliance-evidence:
     name: Upload Compliance Evidence
     runs-on: {{RUNNER}}
+    # Permissions are needed because the "Auto-generate housekeeping stubs"
+    # step pushes a new branch + opens a PR via `gh pr create` when the
+    # current push triggers a housekeeping release (vYYYY.MM.DD) that
+    # doesn't yet have its stub release-ticket on disk. Without these
+    # the github-actions[bot] token gets HTTP 403 on the push + on the PR
+    # create, and the auto-housekeeping path silently leaves a red badge
+    # on every docs-only / chore push. DEVAUDIT_USER_TOKEN remains optional
+    # for orgs with restricted Actions permissions — but is no longer
+    # required for the default-config flow. See DevAudit-Installer#122.
+    permissions:
+      contents: write       # push the auto-PR branch
+      pull-requests: write  # gh pr create
     env:
       DEVAUDIT_BASE_URL_VAR: ${{ vars.DEVAUDIT_BASE_URL }}
       DEVAUDIT_API_KEY: ${{ secrets.DEVAUDIT_API_KEY }}

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

@@ -93,5 +93,18 @@
     "block_on_stage_3": true,
     "auto_file_followup_issue": false,
     "ramp_up_runs": 5
+  },
+
+  "_comment_adr_author": "adr-author skill toggles (DevAudit-Installer#120, v0.1.43+). The skill applies a decision tree at Stage 1 plan APPROVAL to judge ADR-worthiness, drafts docs/ADR/ADR-NNN-<slug>.md when warranted, and drops compliance/evidence/REQ-XXX/architecture-decision.md at Stage 3. block_on_stage_1=false (default) means advisory-with-strong-recommend in v1; flip to true once the project's calibrated on the heuristic. block_on_stage_3=true means the per-REQ architecture-decision.md artefact is the hard gate. file_paths_signal_architecture lists path prefixes that should trigger an ADR-worthy verdict when touched — defaults cover lib/services/, lib/repositories/, prisma/schema.prisma, infra/; add project-specific load-bearing paths.",
+  "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/"
+    ]
   }
 }