@metasession.co/devaudit-cli 0.1.42 → 0.1.44

package/sdlc/files/_common/skills/governance-doc-author/SKILL.md

@@ -7,25 +7,27 @@ description: Author or refresh one of the project's governance documents — RoP
 
 Author or refresh a single governance document so it correctly closes the framework clauses it's meant to satisfy. Five document classes covered:
 
-| Document | Tier | File | Upload path | Closes |
-|---|---|---|---|---|
-| **RoPA** | 2 | `compliance/governance/ropa.md` | **Portal Upload form** (type `ropa`) — CI does NOT auto-upload since v0.1.39 | `GDPR.Art-30` |
-| **DPIA** | 2 | `compliance/governance/dpia.md` (or `dpia-<reqid>.md`) | **Portal Upload form** (type `dpia`) — CI does NOT auto-upload since v0.1.39 | `GDPR.Art-35` |
-| **AI Use Disclosure** | 2 | `compliance/governance/ai-disclosure.md` | **Portal Upload form** (type `ai_disclosure`) — CI does NOT auto-upload since v0.1.39 | `EUAIA.Art-13` |
-| **Periodic Security Review Schedule** | 2 | `SDLC/Periodic_Security_Review_Schedule.md` | **Portal Upload form** (type `compliance_document`) | `ISO27001.A.12.1` schedule expectation (quarterly runs close it via `periodic_review` evidence — see Phase 6) |
-| **Incident Report (project-level template)** | 3 | `compliance/governance/incident-report.md` | **CI auto-upload** via `compliance-evidence.yml` | `ISO29119.3.5.4` baseline; conditionals via [[incident-classification]] |
+| Document                                     | Tier | File                                                   | Upload path                                                                           | Closes                                                                                                        |
+| -------------------------------------------- | ---- | ------------------------------------------------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| **RoPA**                                     | 2    | `compliance/governance/ropa.md`                        | **Portal Upload form** (type `ropa`) — CI does NOT auto-upload since v0.1.39          | `GDPR.Art-30`                                                                                                 |
+| **DPIA**                                     | 2    | `compliance/governance/dpia.md` (or `dpia-<reqid>.md`) | **Portal Upload form** (type `dpia`) — CI does NOT auto-upload since v0.1.39          | `GDPR.Art-35`                                                                                                 |
+| **AI Use Disclosure**                        | 2    | `compliance/governance/ai-disclosure.md`               | **Portal Upload form** (type `ai_disclosure`) — CI does NOT auto-upload since v0.1.39 | `EUAIA.Art-13`                                                                                                |
+| **Periodic Security Review Schedule**        | 2    | `SDLC/Periodic_Security_Review_Schedule.md`            | **Portal Upload form** (type `compliance_document`)                                   | `ISO27001.A.12.1` schedule expectation (quarterly runs close it via `periodic_review` evidence — see Phase 6) |
+| **Incident Report (project-level template)** | 3    | `compliance/governance/incident-report.md`             | **CI auto-upload** via `compliance-evidence.yml`                                      | `ISO29119.3.5.4` baseline; conditionals via [[incident-classification]]                                       |
 
-Each doc has a starter template under `sdlc/files/_common/governance/*.md.template` (installed on demand via `devaudit bootstrap-governance` since v0.1.36). This skill does NOT regenerate the template — it walks the operator through *filling it in* against the project's actual state.
+Each doc has a starter template under `sdlc/files/_common/governance/*.md.template` (installed on demand via `devaudit bootstrap-governance` since v0.1.36). This skill does NOT regenerate the template — it walks the operator through _filling it in_ against the project's actual state.
 
 ## Scope
 
 **In scope**
+
 - Authoring or refreshing one (or more) of the five governance docs above.
 - Gathering source data from the codebase / CI runs / git history.
 - Confirming framework attribution before commit.
 - Driving the commit + push → portal upload (manual for Tier 1/2, CI auto for Tier 3) → portal verification loop.
 
 **Out of scope**
+
 - Incident response itself — that path is the `e2e-test-engineer` skill's defect-filing flow plus `incident-export.yml` on issue close.
 - Test execution evidence — handled by `e2e-test-engineer`.
 - Implementation plans for individual REQs — handled by the `sdlc-implementer` skill's Phase 1 against `Implementation_Plan_TEMPLATE.md`.
@@ -39,13 +41,14 @@ Six phases. Phase 0 is a routing step; phases 1–5 are per-document.
 
 Determine which document the operator needs. Ask if ambiguous; otherwise infer from the trigger phrase.
 
-- *"create / refresh the RoPA"* → Phase 1 with doc = ROPA
-- *"write / update a DPIA"* → Phase 1 with doc = DPIA (ask: tied to a specific HIGH-risk REQ, or project-wide?)
-- *"AI use disclosure"* / *"document our AI use"* → Phase 1 with doc = AI_DISCLOSURE
-- *"periodic security review schedule"* / *"how often do we review"* → Phase 1 with doc = REVIEW_SCHEDULE
-- *"incident-report template"* → Phase 1 with doc = INCIDENT_TEMPLATE (and remind the operator that per-incident reports come from `incident-export.yml`, not this skill)
+- _"create / refresh the RoPA"_ → Phase 1 with doc = ROPA
+- _"write / update a DPIA"_ → Phase 1 with doc = DPIA (ask: tied to a specific HIGH-risk REQ, or project-wide?)
+- _"AI use disclosure"_ / _"document our AI use"_ → Phase 1 with doc = AI_DISCLOSURE
+- _"periodic security review schedule"_ / _"how often do we review"_ → Phase 1 with doc = REVIEW_SCHEDULE
+- _"incident-report template"_ → Phase 1 with doc = INCIDENT_TEMPLATE (and remind the operator that per-incident reports come from `incident-export.yml`, not this skill)
+- _"register a new risk"_ / _"open a risk-register entry"_ / _"document a control gap"_ → **delegate to the [`risk-register-keeper` skill](../risk-register-keeper/SKILL.md)** (DevAudit-Installer#121, v0.1.44+). The risk register is a separate SoT (`compliance/risk-register.md`) with its own lifecycle (OPEN / MITIGATED / ACCEPTED / CLOSED) and stage hooks (Stage 1 / incident close / Stage 3). This skill does not maintain it.
 
-When the trigger is *"GDPR.Art-30 is MISSING on the matrix, what do I upload?"* and similar — route to the matching doc above.
+When the trigger is _"GDPR.Art-30 is MISSING on the matrix, what do I upload?"_ and similar — route to the matching doc above. When the trigger is about per-REQ risks or control gaps — route to `risk-register-keeper`.
 
 ### Phase 1 — Confirm the starter exists
 
@@ -61,7 +64,7 @@ Each doc class has different inputs. Read what's needed; don't ask the operator
   - Read `app/`, `lib/`, `prisma/schema.prisma` (or equivalent) to enumerate processing activities.
   - For each, infer: data categories, recipients (third-party SDKs / services), retention (DB triggers, env vars naming retention windows), lawful basis where reasonable.
   - Read `.env.example` for third-party service names.
-  - Ask the operator to confirm purposes (you can guess the technical surface; the *purpose* is a business decision).
+  - Ask the operator to confirm purposes (you can guess the technical surface; the _purpose_ is a business decision).
 
 - **DPIA**
   - Project-wide DPIA → same source data as RoPA, plus a risk identification pass against Art. 35(3) triggers (large-scale special category, systematic monitoring, automated decisions with legal effect).
@@ -92,13 +95,13 @@ Each doc class has different inputs. Read what's needed; don't ask the operator
 
 For each clause the doc closes, confirm the corresponding section of the doc is non-stub:
 
-| Doc | Clause | Section that must be non-stub |
-|---|---|---|
-| ROPA | GDPR.Art-30 | §Controller + ≥1 §Processing activities row with all fields filled |
-| DPIA | GDPR.Art-35 | All six sections (description / necessity / risks / measures / consultation / sign-off) |
-| AI_DISCLOSURE | EUAIA.Art-13 | All six checklist items in the template's Framework checklist |
-| REVIEW_SCHEDULE | ISO27001.A.12.1 | A schedule entry per control area + a named reviewer per cadence |
-| INCIDENT_TEMPLATE | ISO29119.3.5.4 baseline | §1–§8 of the template are skeletal but coherent (per-incident files inherit the shape) |
+| Doc               | Clause                  | Section that must be non-stub                                                           |
+| ----------------- | ----------------------- | --------------------------------------------------------------------------------------- |
+| ROPA              | GDPR.Art-30             | §Controller + ≥1 §Processing activities row with all fields filled                      |
+| DPIA              | GDPR.Art-35             | All six sections (description / necessity / risks / measures / consultation / sign-off) |
+| AI_DISCLOSURE     | EUAIA.Art-13            | All six checklist items in the template's Framework checklist                           |
+| REVIEW_SCHEDULE   | ISO27001.A.12.1         | A schedule entry per control area + a named reviewer per cadence                        |
+| INCIDENT_TEMPLATE | ISO29119.3.5.4 baseline | §1–§8 of the template are skeletal but coherent (per-incident files inherit the shape)  |
 
 If any required section is still stub, **do not commit**. Surface the gap in the Phase 5 report, ask the operator for the missing input.
 
@@ -118,10 +121,10 @@ Tier 1/2 docs (RoPA, DPIA, AI Disclosure, Periodic Security Review Schedule) and
 
 These are **two different artefacts** and the skill must not conflate them:
 
-| Artefact | What | Closes | Cadence | Skill responsibility |
-|---|---|---|---|---|
-| **Periodic_Security_Review_Schedule.md** | The *plan* — which controls get reviewed, how often, by whom | `ISO27001.A.12.1` (the schedule presence) | Once, refresh annually | **In scope.** Author / refresh via this skill. |
-| **periodic-review.md** | The *execution evidence* — this quarter's actual review | `ISO27001.A.12.1` + `SOC2.CC4.1` (effectiveness evidence) | Quarterly | **Out of scope.** Auto-generated by `periodic-review.yml`; the operator fills in the 60% operator-fill section per the PR body's checklist. |
+| Artefact                                 | What                                                         | Closes                                                    | Cadence                | Skill responsibility                                                                                                                        |
+| ---------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Periodic_Security_Review_Schedule.md** | The _plan_ — which controls get reviewed, how often, by whom | `ISO27001.A.12.1` (the schedule presence)                 | Once, refresh annually | **In scope.** Author / refresh via this skill.                                                                                              |
+| **periodic-review.md**                   | The _execution evidence_ — this quarter's actual review      | `ISO27001.A.12.1` + `SOC2.CC4.1` (effectiveness evidence) | Quarterly              | **Out of scope.** Auto-generated by `periodic-review.yml`; the operator fills in the 60% operator-fill section per the PR body's checklist. |
 
 If the operator asks for "the periodic review", clarify which they mean. If they want the quarterly execution, point them at the open auto-PR (or, if cron hasn't fired yet, suggest `gh workflow run periodic-review.yml`).
 
@@ -139,7 +142,7 @@ When Phase 5 commits successfully, append a short narrator update in the final r
 
 **Don't invent.** If you can't derive a value from the codebase / CI / git, ask the operator. Never guess at lawful basis, retention windows, controller contacts, or AI provider names.
 
-**Framework checklist is load-bearing.** The portal's matrix uses the *presence* of the doc to flip COVERED; auditors use the *content* to decide if that's defensible. Tick boxes only when they're actually true.
+**Framework checklist is load-bearing.** The portal's matrix uses the _presence_ of the doc to flip COVERED; auditors use the _content_ to decide if that's defensible. Tick boxes only when they're actually true.
 
 **Confirm before destructive or public actions.** Same as the e2e-test-engineer principle. Diff, confirm, commit. The operator approves the doc going to GitHub before push.
 

package/sdlc/files/_common/skills/risk-register-keeper/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: risk-register-keeper
+description: Maintain `compliance/risk-register.md` as the authoritative project-spanning record of risks across the SDLC lifecycle. Runs at Stage 1 (MEDIUM/HIGH risk classification — open RISK-NNN entries for risks the REQ introduces), at incident-close (residual risk after an incident), and at Stage 3 (per-REQ evidence pack). Owns the canonical risk row (description, inherent likelihood × impact, mitigations planned, residual likelihood × impact, owner, review-due, framework cross-references), allocates the next `RISK-NNN` per project, replaces the implementation plan's inline Risks/Considerations bullets with RISK-NNN reference list, and produces `compliance/evidence/REQ-XXX/risk-assessment.md` summarising which entries this REQ opened, mitigated, or accepted. Use when invoking on a single REQ ("draft a risk-register entry for REQ-XXX", "is the risk register up to date for this branch?"); when `sdlc-implementer` delegates at Stage 1 for MEDIUM/HIGH classifications or Stage 3 for the evidence artefact; when an incident closes and the residual-risk entry needs drafting; when a `solo_with_gap` approval mode requires the documented control-gap entry. Do NOT use for authoring canonical risk-treatment language (the operator owns the final wording); for periodic-review re-validation of accepted risks (deferred to Phase B); for full STRIDE/LINDDUN threat modelling (deferred to Phase B; consider folding into a separate `threat-modeller` skill if volume justifies); for framework-clause mapping of the `risk_assessment` evidence type (that's META-COMPLY's `framework-registry-auditor`).
+---
+
+# Risk Register Keeper
+
+Maintains `compliance/risk-register.md` as the authoritative record of project risks across the SDLC lifecycle. Sibling of [`requirements-aligner`](../requirements-aligner/SKILL.md) (owns `docs/SRS.md`) and [`adr-author`](../adr-author/SKILL.md) (owns `docs/ADR/`) in the SoT-alignment skill family.
+
+The skill is **Phase A scope** (per [DevAudit-Installer#121](https://github.com/metasession-dev/DevAudit-Installer/issues/121) and the [#119 review](https://github.com/metasession-dev/DevAudit-Installer/issues/119#issuecomment-4631840651)): Stage 1 + post-incident + Stage 3 hooks. Periodic-review re-validation, audit-pack inclusion, and STRIDE/LINDDUN threat modelling all defer to Phase B.
+
+## What this skill owns
+
+| Artefact                                                                   | Lives at                       | Tier                 |
+| -------------------------------------------------------------------------- | ------------------------------ | -------------------- |
+| `compliance/risk-register.md` (the SoT, project-spanning)                  | Top-level compliance directory | 2 (project strategy) |
+| `compliance/evidence/REQ-XXX/risk-assessment.md` (per-REQ Tier 3 evidence) | Per-REQ evidence directory     | 3 (per-REQ)          |
+
+The skill does **not** own the canonical risk-treatment language (operator decision — risk acceptance has legal + audit consequences). It allocates `RISK-NNN` IDs, drafts canonical row stubs the operator edits, and cross-references the register entries from per-REQ artefacts.
+
+## Scope
+
+**In scope**
+
+- Phase 1 (Stage-1 hook, MEDIUM/HIGH only by default) — read implementation plan + diff → identify risks → allocate `RISK-NNN` → draft canonical rows → replace plan's Risks/Considerations bullets with RISK-NNN reference list.
+- Phase 2 (post-incident hook) — read closed `incident`-labelled report → draft residual-risk entry → cross-link incident report ↔ register entry.
+- Phase 3 (Stage-3 hook) — drop `compliance/evidence/REQ-XXX/risk-assessment.md` with this REQ's RISK-NNN summary.
+- Phase 4 (`solo_with_gap` approval) — when project's `sdlc-config.json:approval.mode = 'solo_with_gap'`, refuse merge unless the documented control-gap RISK-NNN entry exists.
+- Per-REQ ad-hoc audit (operator invocation).
+
+**Out of scope**
+
+- Authoring canonical risk-treatment prose — the skill drafts stubs; the operator owns final language. Risk acceptance has legal + audit consequences; the operator's sign-off is the audit value.
+- Periodic-review re-validation — Phase B, paired with `governance-doc-author`'s periodic-review schedule.
+- Audit-pack inclusion — Phase B, pairs with portal audit-pack export.
+- STRIDE / LINDDUN threat modelling sub-domain — deferred; if volume justifies, graduates to a separate `threat-modeller` skill.
+- Framework-clause mapping of the `risk_assessment` evidence type — that's META-COMPLY's `framework-registry-auditor`.
+- CVSS-aware scoring — defaults to a `likelihood × impact` 3×3 matrix per `0-project-setup.md`. CVSS deferred.
+
+## The workflow
+
+Six phases. Phase 0 routes; Phases 1–4 are the SDLC stage hooks; Phase 5 is the utility audit; Phase 6 reports.
+
+### Phase 0 — Route
+
+Determine what's being assessed:
+
+- **Stage-1 plan APPROVAL (MEDIUM/HIGH risk)** — `sdlc-implementer` (or operator) says _"draft risk-register entries for REQ-XXX"_ / _"this is HIGH risk, what goes in the register?"_ → Phase 1.
+- **Incident close** — operator (or CI workflow) says _"incident-report-N.md just exported, draft the residual-risk entry"_ → Phase 2.
+- **Stage-3 evidence pack** — `sdlc-implementer` (or operator) says _"drop the risk-assessment.md for REQ-XXX"_ → Phase 3.
+- **`solo_with_gap` approval check** — operator says _"approval mode is solo_with_gap, is the control-gap entry on the register?"_ → Phase 4.
+- **Per-REQ ad-hoc audit** — operator says _"is REQ-XXX's risk record complete?"_ / _"audit the register against this branch"_ → Phase 5.
+
+The skill does not fire spontaneously. The parent skill (`sdlc-implementer`) invokes it at Stage 1 for MEDIUM/HIGH classifications + Stage 3 per the parent's SKILL.md delegation contract. `incident-export.yml` invokes it at incident close per its workflow definition.
+
+### Phase 1 — Stage-1 plan APPROVAL hook (MEDIUM/HIGH only)
+
+Input: the REQ's `compliance/plans/REQ-XXX/implementation-plan.md` plus the working-tree diff. Triggered only when the orchestrator's risk classification is **MEDIUM or HIGH** by default (LOW skipped); configurable via `sdlc-config.json:risk_register_keeper.block_on_stage_1`.
+
+**Step 1 — Read the implementation plan's Threat model + Security considerations section** (`Implementation_Plan_TEMPLATE.md` §4) and the diff scope.
+
+**Step 2 — Identify discrete risks.** Each risk is something an auditor could examine independently:
+
+- A specific attack surface the change exposes (e.g. "SQL injection via the order-id query param").
+- A specific control gap the change introduces (e.g. "no rate limit on /api/auth/forgot-password").
+- A specific dependency-introduced concern (e.g. "Redis adopted as cache — no encryption at rest by default").
+- A specific data-handling decision (e.g. "payment card last-4 stored in app DB").
+
+**Step 3 — For each risk, allocate `RISK-NNN` and draft the canonical row.** Scan `compliance/risk-register.md` for max-existing ID + 1. If the register doesn't exist yet, bootstrap it from `sdlc/files/_common/governance/risk-register.md.template`.
+
+Format per row (markdown table inside the register):
+
+```markdown
+### RISK-NNN — <one-line title>
+
+- **Status:** OPEN
+- **Opened:** YYYY-MM-DD (REQ-XXX)
+- **Owner:** <operator>
+- **Description:** REPLACE — what the risk is, in operator-readable terms (2-3 sentences).
+- **Inherent likelihood × impact:** REPLACE (low × medium = 2 / medium × medium = 4 / etc — per 3×3 matrix in 0-project-setup.md)
+- **Mitigations applied in this REQ:** REPLACE — list controls landing in this PR
+- **Residual likelihood × impact:** REPLACE (post-mitigation)
+- **Framework cross-references:** REPLACE — ISO27001.A.X.Y / SOC2.CC3.2 / GDPR.Art-32 (as applicable)
+- **Review due:** YYYY-MM-DD (default 365d for ACCEPTED + MITIGATED; OPEN reviews monthly)
+- **Cross-links:** REQ-XXX implementation plan; ADR-NNN (if produced by adr-author); incident-report-N (if post-incident)
+```
+
+**Step 4 — Replace the implementation plan's Risks/Considerations bullets with RISK-NNN references.** The plan's §4 (Threat model) gets a new sub-section:
+
+```markdown
+### Risk register entries
+
+This REQ opens / touches the following entries in `compliance/risk-register.md`:
+
+- **RISK-NNN — <title>** — Status: OPEN. Opened by `risk-register-keeper`. Operator edits the canonical row + signs off the residual rating before plan APPROVAL.
+- **RISK-NNN — <title>** — Status: MITIGATED. Controls landing in this PR close the residual.
+```
+
+For **deferred** risks (the operator decides the surface doesn't merit a register entry — typically LOW-impact + LOW-likelihood combination), the row carries `@risk-deferred: <reason>` so the deferral is visible.
+
+**Step 5 — Block plan APPROVAL** (configurable) until each MEDIUM/HIGH risk has either a RISK-NNN entry OR an explicit `@risk-deferred` annotation with rationale.
+
+### Phase 2 — Post-incident hook
+
+Triggered when `incident-export.yml` exports a closed `incident`-labelled GitHub issue to `compliance/governance/incident-report-N.md` (DevAudit-Installer v0.1.31 WS4+).
+
+**Step 1 — Read the incident report.** Severity classification, root cause, controls applied, residual concern.
+
+**Step 2 — Draft a residual-risk entry.** Status branches:
+
+| Outcome of incident                                                           | Status    | What the entry records                                                  |
+| ----------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------- |
+| Controls landed alongside the fix; residual risk now LOW                      | MITIGATED | What was wrong, what landed, what's checked going forward               |
+| Controls deferred (fix-forward shipped but follow-up work tracked)            | OPEN      | Same, plus follow-up issue reference + deadline                         |
+| Risk judged tolerable post-incident (e.g. one-off external dependency outage) | ACCEPTED  | What was wrong, why acceptance is defensible, when re-validation is due |
+
+**Step 3 — Cross-link both directions.** The register entry references `incident-report-N.md`; the incident report file's frontmatter gets a `risk_register_entry: RISK-NNN` line so the audit trail is bidirectional.
+
+### Phase 3 — 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/risk-assessment.md`.** Format:
+
+```markdown
+---
+req: REQ-XXX
+generated_by: risk-register-keeper
+generated_at: <ISO timestamp>
+---
+
+# Risk assessment — REQ-XXX
+
+## Summary
+
+This REQ opened / mitigated / accepted the following entries in `compliance/risk-register.md`:
+
+| RISK-NNN | Title   | Status this cycle                                      | Residual L × I |
+| -------- | ------- | ------------------------------------------------------ | -------------- |
+| RISK-NNN | <title> | OPEN (opened in this REQ)                              | medium × low   |
+| RISK-NNN | <title> | MITIGATED (controls landed in this REQ)                | low × low      |
+| RISK-NNN | <title> | ACCEPTED (re-validated, no change required this cycle) | low × medium   |
+
+## Framework cross-references
+
+Risks above map to the following framework clauses:
+
+- ISO27001.A.X.Y — RISK-NNN
+- SOC2.CC3.2 — RISK-NNN (Risk identification and assessment)
+- GDPR.Art-32 — RISK-NNN (Security of processing) — if applicable
+
+## Operator sign-off
+
+I have reviewed the risk register entries above and confirm:
+
+- [ ] Each entry's residual rating is defensible given the controls landing in this REQ.
+- [ ] No risk was downgraded without evidence (control demonstrated effective via tests).
+- [ ] OPEN entries have follow-up tracking (issue / deadline / next-review-due).
+
+**Reviewer:** <operator-name>
+**Date:** <YYYY-MM-DD>
+```
+
+**Step 2 — Tag for upload.** The CI's `compliance-evidence.yml` uploads this file as `evidence_type=risk_assessment` (added to META-COMPLY's `EVIDENCE_TYPE_REGISTRY` in the paired sub-PR). The framework-coverage matrix attribution depends on `framework-registry-auditor`'s review — see the META-COMPLY-side PR for final clause closures.
+
+**Step 3 — Hand-off back to `sdlc-implementer`.** The skill's job ends at the artefact + operator sign-off.
+
+### Phase 4 — `solo_with_gap` approval check
+
+When `sdlc-config.json:approval.mode = 'solo_with_gap'` and a release is about to be approved, the skill verifies the documented control-gap RISK-NNN entry exists in the register.
+
+**Step 1 — Read `sdlc-config.json:approval.mode`.** If not `solo_with_gap`, exit (no check needed).
+
+**Step 2 — Grep the register for a control-gap entry.** Look for an entry whose Framework cross-references include `SOC2.CC8.1` and whose description references `solo_with_gap` or equivalent ("self-approval", "single-actor release").
+
+**Step 3 — If absent, draft one.** Status: ACCEPTED (operator-acknowledged trade-off). Description: "Project operates in solo_with_gap approval mode — release submitter approves their own release. This is a documented control gap relative to SOC2 CC8.1 four-eyes ideal. Compensating controls: <list — typically: CI gates green, MFA on release operator, monthly audit log review>."
+
+**Step 4 — Refuse approval until the entry is signed off** by the operator. The control gap must be deliberately acknowledged, not silently inherited.
+
+### Phase 5 — 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 risk record complete?"_ outside the SDLC orchestration flow.
+
+### Phase 6 — Report
+
+- For Phase 1 — the plan's injected sub-section + the block/allow decision.
+- For Phase 2 — the new register entry + cross-link confirmation.
+- For Phase 3 — the artefact path + summary line.
+- For Phase 4 — the gap-entry confirmation + approval-blocking decision.
+- For Phase 5 — markdown report per REQ.
+
+## Configuration (sdlc-config.json)
+
+```json
+{
+  "risk_register_keeper": {
+    "enabled": true,
+    "block_on_stage_1": false,
+    "block_on_stage_3": true,
+    "scoring": "likelihood-impact",
+    "auto_open_on_high_risk_req": true,
+    "auto_open_on_closed_incident": true,
+    "stage_1_min_risk_class": "MEDIUM"
+  }
+}
+```
+
+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. Flip to `true` once the project's register is populated enough that the check is reliably surfacing real risks (not false-positives on sparse coverage).
+- `block_on_stage_3: true` — per-REQ `risk-assessment.md` artefact is the hard gate.
+- `scoring: 'likelihood-impact'` — default 3×3 matrix per `0-project-setup.md`. CVSS-aware scoring (Phase B) deferred.
+- `stage_1_min_risk_class: 'MEDIUM'` — LOW REQs skip the Stage-1 hook (the orchestrator's classification already decided no register entry is warranted). MEDIUM/HIGH trigger.
+- `auto_open_on_closed_incident: true` — fire Phase 2 on every `incident-export.yml` close. Set to `false` for projects with high incident volume + dedicated risk-management process.
+
+## Principles
+
+**Don't author canonical risk-treatment language.** The skill drafts stubs; the operator owns the final wording. Risk acceptance has legal + audit consequences; the operator's sign-off carries the audit value. Inventing canonical risk-treatment prose without operator review is exactly the kind of silent acceptance this skill exists to prevent.
+
+**Calibrate, don't over-trigger.** Not every change introduces a register-worthy risk. A typo fix doesn't. A CSS tweak doesn't. The `stage_1_min_risk_class` default skips LOW REQs precisely for this reason. False-positive register entries (drafting noise the team has to edit-and-delete) dilute the register's audit value.
+
+**The negative case is audit evidence too.** An `@risk-deferred: <rationale>` annotation in the plan's Risks-register-entries sub-section proves the operator considered the surface and decided no entry was needed. Auditors examine the negative case as well as the positive — empty/silent is the failure mode, not "considered + deferred with rationale".
+
+**Status semantics are load-bearing.** OPEN = active and unmitigated. MITIGATED = controls landed and demonstrated effective. ACCEPTED = operator-acknowledged trade-off with periodic re-validation. CLOSED = no longer relevant. Don't flip OPEN → CLOSED to make the register green for an audit — auditors check the audit log.
+
+**Sibling-skill awareness.** When this skill opens a RISK-NNN that maps to an SRS item, cross-link the SRS-ID (from `requirements-aligner`). When the risk relates to an architectural decision, cross-link the ADR-NNN (from `adr-author`). The three SoT-alignment skills work together; each produces its own per-REQ Tier 3 artefact but they share the per-REQ context.
+
+**`solo_with_gap` is a deliberate trade-off, not a silent override.** The framework supports solo-dev projects via `solo_with_gap` approval mode — but only on the explicit basis that the control gap is documented in the risk register. Phase 4 enforces this; the alternative is silently inheriting a SOC 2 CC8.1 gap that an auditor will flag.
+
+## References
+
+- [DevAudit-Installer#121](https://github.com/metasession-dev/DevAudit-Installer/issues/121) — the issue this skill closes, with the case study + locked Phase A scope.
+- `sdlc-implementer/SKILL.md` Phase 1 + Phase 3 — the parent-skill invocation contract.
+- `sdlc/files/_common/governance/risk-register.md.template` — starter template installed via `devaudit bootstrap-governance`.
+- `sdlc/files/_common/Implementation_Plan_TEMPLATE.md` — §4 Threat model gets a new "Risk register entries" sub-section 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.
+- `sdlc/files/_common/skills/adr-author/SKILL.md` — sibling skill (same family).
+- `sdlc/files/_common/skills/governance-doc-author/SKILL.md` — Phase 0 routing cross-links to this skill ("register a new risk" vs "draft a ROPA / DPIA / incident-report").
+- Meta-reviewer (META-COMPLY): `framework-registry-auditor` reviews the `risk_assessment` evidence type's clause mappings before the META-COMPLY sub-PR opens.
+- Approval mode reference: `sdlc-config.example.json:approval.mode` — `dual_actor` vs `solo_with_gap` vs `auto_low_risk`.

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

@@ -68,9 +68,10 @@ Runs **first**, before any `REQ-XXX` is assigned. It decides which of the six ch
    4. Body heuristics — acceptance criteria, or risk signals (auth, payments, RBAC, data egress, AI decisioning) → tracked, and raise the risk class.
 
    Map the result to one of the six paths in `change-workflows.md`.
+
 3. **Announce a "Workflow Decision" block** (template below): change-type, commit-type, whether a `REQ-XXX` is needed, risk class, which stages/gates run, which approvals the **operator** must perform (UAT four-eyes, Production approval), and what is **skipped**.
 4. **Pause policy — pause-when-it-matters.** Pause for explicit confirmation on **tracked / heavier** paths, or when classification is **ambiguous**; **announce-and-auto-proceed** on trivial / housekeeping. The operator can always reclassify ("treat this as housekeeping" / "this is HIGH risk").
-5. **Route — and stay on to completion.** A route is a choice of *which workflow to drive*, never a hand-off that abandons the operator. Whatever the path, the skill keeps guiding step by step until no further action is required (typically: merged).
+5. **Route — and stay on to completion.** A route is a choice of _which workflow to drive_, never a hand-off that abandons the operator. Whatever the path, the skill keeps guiding step by step until no further action is required (typically: merged).
    - **tracked** (feature / bug fix / refactor / perf) → continue into Phase 1 below (full Stages 1–5).
    - **housekeeping / trivial** → drive the **Lightweight path** below to completion. No `REQ-XXX`, no RTM row, no evidence pack, no portal release approvals — but the skill still branches, runs the gates, opens the PR, and walks the operator through review → merge.
    - **compliance-doc-only** → drive the same Lightweight path as a docs push (or PR, per the project's flow) referencing the **existing** `REQ-XXX`: no new requirement and no quality-gate ceremony, but driven through to merge.
@@ -79,6 +80,7 @@ Runs **first**, before any `REQ-XXX` is assigned. It decides which of the six ch
 **"Workflow Decision" announcement template**
 
 > **Workflow decision — #N**
+>
 > - **Change type:** \<Feature | Bug fix | Refactor/Perf | Housekeeping | Trivial | Compliance-doc-only\>
 > - **Commit type:** \<feat | fix | refactor | chore | docs | …\>
 > - **Requirement:** \<REQ-XXX assigned | none\>
@@ -87,13 +89,13 @@ Runs **first**, before any `REQ-XXX` is assigned. It decides which of the six ch
 > - **Gates/evidence:** \<…\>
 > - **Your approvals:** \<UAT four-eyes + Production approval | PR review only\>
 > - **Skipped:** \<…\>
-> Proceed? *(or reclassify)*
+>   Proceed? _(or reclassify)_
 
 Only the **tracked** route continues into Phase 1; the others run the Lightweight path below. The off-ramps are deliberate — dragging housekeeping through tracked-change machinery it doesn't need is exactly the failure mode this step exists to prevent — but they are still **driven to completion**, never dumped as a checklist for the operator to run alone.
 
 **Worked examples** (one per change-type the skill keeps mis-routing without one):
 
-*Tracked feature — REQ-XXX assigned*
+_Tracked feature — REQ-XXX assigned_
 
 > - **Change type:** Feature
 > - **Commit type:** feat
@@ -104,7 +106,7 @@ Only the **tracked** route continues into Phase 1; the others run the Lightweigh
 > - **Your approvals:** UAT four-eyes + Production approval
 > - **Skipped:** none
 
-*Test fix surfaced by suite drift*
+_Test fix surfaced by suite drift_
 
 > - **Change type:** Housekeeping (test maintenance)
 > - **Commit type:** test
@@ -115,7 +117,7 @@ Only the **tracked** route continues into Phase 1; the others run the Lightweigh
 > - **Your approvals:** PR review only
 > - **Skipped:** RTM, evidence pack, UAT four-eyes, Production approval
 
-*Workflow tweak (CI artifact upload, gate timeout bump, etc.)*
+_Workflow tweak (CI artifact upload, gate timeout bump, etc.)_
 
 > - **Change type:** Housekeeping (CI maintenance)
 > - **Commit type:** ci
@@ -128,14 +130,14 @@ Only the **tracked** route continues into Phase 1; the others run the Lightweigh
 
 ### Lightweight path (housekeeping / trivial / compliance-doc-only)
 
-Reached from Phase 0 for non-tracked change-types. The skill drives this end-to-end; the only difference from the tracked cycle is the absence of *ceremony*, not the absence of *guidance*. It pauses only where a human is genuinely required (PR review, merge).
+Reached from Phase 0 for non-tracked change-types. The skill drives this end-to-end; the only difference from the tracked cycle is the absence of _ceremony_, not the absence of _guidance_. It pauses only where a human is genuinely required (PR review, merge).
 
 1. **Branch off `$INTEGRATION_BRANCH`** with a housekeeping prefix — `chore/…`, `docs/…`, `ci/…`, `build/…`, `test/…`, or `compliance/…` for a doc-only change against an existing REQ.
 2. **Make the change**, single-purpose. If it turns out to touch runtime behaviour in `app/` / `lib/`, stop and reclassify as tracked — the commit-type rule is the backstop.
 3. **Run all gates locally** (`npm run lint`, `npx tsc --noEmit`, the test suite, `semgrep`, `npm audit` — or the stack-adapter equivalents). Trivial ≠ unverified; never `--no-verify`.
 4. **Commit** with a housekeeping type and **no** `REQ-XXX` — `docs:` / `chore:` / `ci:` / `build:` / `test:` / `revert:` are exempt from the `[REQ-XXX]` rule; a `compliance:` doc-only change references the existing REQ. `Co-Authored-By: Claude` if AI-assisted.
 5. **Push and open the PR** into `$INTEGRATION_BRANCH` (`gh pr create --base "$INTEGRATION_BRANCH" --head <branch>`). CI runs the same quality gates; `compliance-validation.yml` finds no `REQ-XXX` and skips artifact validation.
-6. **For `ci:` changes, verify-via-dispatch before merging.** `gh workflow run <workflow.yml> --ref <branch>` fires the modified workflow against the PR branch. If the change broke a step, the dispatch run fails loudly and you fix-forward *before* the merge ships the broken gate to `$INTEGRATION_BRANCH`. This is the cheapest insurance against silent CI regressions — a `ci:` change that breaks a gate is most damaging *after* it lands.
+6. **For `ci:` changes, verify-via-dispatch before merging.** `gh workflow run <workflow.yml> --ref <branch>` fires the modified workflow against the PR branch. If the change broke a step, the dispatch run fails loudly and you fix-forward _before_ the merge ships the broken gate to `$INTEGRATION_BRANCH`. This is the cheapest insurance against silent CI regressions — a `ci:` change that breaks a gate is most damaging _after_ it lands.
 7. **Report honest status** — wait for CI, name any failing check, fix and re-push. Never announce "ready" while a required check is red.
 8. **Guide review → merge.** A human still reviews the PR (separation of duties). There is **no** portal release approval, no UAT four-eyes, no Production gate, and no close-out. Merge once CI is green and the reviewer approves.
 9. **Done.** A housekeeping push produces at most a bare-date release (`vYYYY.MM.DD`) with no approval gate; a doc-only push attaches its docs to the existing `REQ-XXX` release. No further action required — report completion and stop.
@@ -150,20 +152,23 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
 4. **Detect over-scoping.** If the issue spans clearly distinct deliverables (e.g. "build SAML SSO + reorganise the admin dashboard + migrate from Postgres 14 to 16"), halt with a clear message asking the user to split the issue into separate ones. Do not proceed past Phase 1.
 5. **Write the implementation plan.** Create `compliance/plans/REQ-XXX/implementation-plan.md` from `sdlc/files/_common/Implementation_Plan_TEMPLATE.md` (synced into the consumer's `SDLC/` directory at install). The template's shape is load-bearing — it carries the **Framework attribution** section that closes four framework clauses on upload:
 
-   | Clause | What the plan must contain |
-   |---|---|
-   | **ISO 29119 §3.4** Test Plan | Acceptance criteria + verification strategy per AC. |
-   | **ISO 27001 A.8.25** Secure SDLC | Threat model + secrets / dependency considerations. |
-   | **GDPR Art. 25** Data protection by design | Per-purpose data flows + lawful basis + retention. Explicit "no personal data" callout if not applicable. |
-   | **EU AI Act Art. 11** Technical documentation | Model provenance + oversight path when AI is in scope. Explicit "no AI in scope" callout if not. |
+   | Clause                                        | What the plan must contain                                                                                |
+   | --------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+   | **ISO 29119 §3.4** Test Plan                  | Acceptance criteria + verification strategy per AC.                                                       |
+   | **ISO 27001 A.8.25** Secure SDLC              | Threat model + secrets / dependency considerations.                                                       |
+   | **GDPR Art. 25** Data protection by design    | Per-purpose data flows + lawful basis + retention. Explicit "no personal data" callout if not applicable. |
+   | **EU AI Act Art. 11** Technical documentation | Model provenance + oversight path when AI is in scope. Explicit "no AI in scope" callout if not.          |
 
    For HIGH/CRITICAL also include: threat model (against STRIDE categories applicable to the touched surfaces), four-eyes attestation slot, rollback plan — the template has slots for all of these.
 
    **Don't delete sections** — mark with `N/A — <reason>` if a clause genuinely doesn't apply (e.g. UI-only change with no personal-data scope). Empty stubs commit-then-upload as placeholder evidence and break the audit trail.
+
 6. **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. **Invoke `risk-register-keeper` for MEDIUM/HIGH risk classifications.** The plan's "Threat model" / Risks section is no longer authored as orphan bullets — when risk class is MEDIUM or HIGH (LOW skipped by default per `sdlc-config.json:risk_register_keeper.stage_1_min_risk_class`), `risk-register-keeper` reads the plan + diff, 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 into the plan's "Risk register entries" sub-section. The skill also enforces the `solo_with_gap` control-gap entry exists for projects in that approval mode. Call via the standard Claude Code Skill mechanism (`Skill(name: "risk-register-keeper", …)`). Configurable via `sdlc-config.json:risk_register_keeper.block_on_stage_1`; advisory by default in v1.
+9. **Update `compliance/RTM.md`** with the new entry: REQ-XXX, title, risk class, linked issue, linked test cases (placeholder).
+10. **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); Risk register entries (RISK-NNN list); Technical approach (one paragraph); Dependencies; Test scope.
+11. **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)
 
@@ -184,8 +189,9 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
    - `semgrep scan --config auto`
    - `npm audit --audit-level=high` (or stack-adapter equivalent)
 
-   **E2E gate** — run *once*, after the fast gates are clean:
+   **E2E gate** — run _once_, after the fast gates are clean:
    - `npx playwright test` (delegated to `e2e-test-engineer`, which has its own focused-iteration discipline for within-e2e fix-and-verify loops)
+
 6. **On gate failure**, iterate up to N=3 attempts. Each iteration: read the failure output, propose a fix, apply, re-run. On exhausted attempts, halt with the full failure output and surface to the human — never use `--no-verify`, `eslint-disable`, `@ts-expect-error`, `xfail`, or any other bypass.
 7. **Commit** using Conventional Commits with `Ref: REQ-XXX` trailer and `Co-Authored-By: Claude` trailer. One commit per logical step; never amend a commit that's already been pushed.
 8. **Land the work on `$INTEGRATION_BRANCH`.** Push the feature branch, then:
@@ -194,14 +200,19 @@ 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. **Invoke `risk-register-keeper` to drop the per-REQ risk-assessment artefact.** The skill's Phase 3 produces `compliance/evidence/REQ-XXX/risk-assessment.md` — a summary table of RISK-NNN entries this REQ opened / mitigated / accepted, framework cross-references, and an operator sign-off block. The artefact uploads with `evidence_type=risk_assessment`; clause attribution per the META-COMPLY framework-registry-auditor review. Call via the standard Skill mechanism.
+4. **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:
+5. **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
+   ├── risk-assessment.md                ← produced in step 3 by risk-register-keeper
    ├── YYYY-MM-DD_e2e-results.json
    ├── YYYY-MM-DD_playwright-report/
    ├── YYYY-MM-DD_traces/                ← per-test trace.zip + error-context.md
@@ -209,8 +220,9 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
    └── YYYY-MM-DD_screenshots/*.png
    ```
 
-   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**:
+   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.
+
+6. **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 +230,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), `risk_assessment` (from step 3).
+7. **Verify uploads landed.** `gh api` or `curl` against `https://devaudit.metasession.co/projects/<slug>/requirements/REQ-XXX/evidence` should show every artefact.
+8. **Update `compliance/RTM.md`** with portal links for each evidence row.
 
 ### Phase 4 — Submit for UAT review (SDLC stage 4)
 
@@ -237,9 +249,11 @@ Reached only on the **tracked** route from Phase 0 (the issue is already fetched
    - For HIGH/CRITICAL: Rollback plan: reference to `compliance/plans/REQ-XXX/implementation-plan.md` §Rollback
    - Test plan
    - SDLC checklist
+
 2. **Verify the UAT reviewer ≠ skill-trigger user** for HIGH/CRITICAL. If they match, halt with a configuration error: "HIGH/CRITICAL risk requires an independent UAT reviewer; the configured reviewer matches the trigger user — fix the four-eyes attestation slot in the implementation plan and re-run."
 
-   **Solo-operator teams.** On a one-person team, the literal "reviewer ≠ submitter" check is structurally unsatisfiable. The supported interpretation is *actor type, not human identity* — AI tooling (the skill-trigger) and the human operator (the portal-approver) are distinct actors. Document this on the release ticket under `## Sign-off (dual-actor)` with the explicit interpretation, and ensure the human operator has independently reviewed the diff before clicking *Approve Production* in the portal. Without this attestation the four-eyes claim is performative.
+   **Solo-operator teams.** On a one-person team, the literal "reviewer ≠ submitter" check is structurally unsatisfiable. The supported interpretation is _actor type, not human identity_ — AI tooling (the skill-trigger) and the human operator (the portal-approver) are distinct actors. Document this on the release ticket under `## Sign-off (dual-actor)` with the explicit interpretation, and ensure the human operator has independently reviewed the diff before clicking _Approve Production_ in the portal. Without this attestation the four-eyes claim is performative.
+
 3. **Apply labels** — `awaiting-uat-review`, `risk:<class>`.
 4. **Comment on the issue**: "Implementation complete. PR #M opened. Evidence on portal: <link>. UAT review requested. Resume with `resume REQ-XXX` once UAT approval is granted on the portal."
 5. **Hard stop.** Phase 4 ends here. Do not proceed to merge; the human's next action is reviewing on the portal.
@@ -258,7 +272,6 @@ Invoked separately by the user after UAT activity on the portal. Trigger: "resum
 1. **Read portal state.** `curl` `https://devaudit.metasession.co/api/projects/<slug>/releases/<version>` and inspect the approval status.
 
 2. **Branch on state:**
-
    - **UAT approved** → run stage 5:
      - `gh pr merge <M> --merge` (merge commit; `--squash` and `--rebase` are blocked by branch protection on SDLC repos and would break the audit trail).
      - Watch `post-deploy-prod.yml` via `gh run watch` — block until the workflow reaches a terminal state.

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 }}