@metasession.co/devaudit-cli 0.1.43 → 0.1.45

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/dist/index.js +1 -1
  2. package/dist/index.js.map +1 -1
  3. package/package.json +2 -2
  4. package/sdlc/SKILLS.md +27 -6
  5. package/sdlc/files/_common/1-plan-requirement.md +20 -8
  6. package/sdlc/files/_common/Implementation_Plan_TEMPLATE.md +32 -21
  7. package/sdlc/files/_common/governance/risk-register.md.template +116 -0
  8. package/sdlc/files/_common/skills/governance-doc-author/SKILL.md +30 -27
  9. package/sdlc/files/_common/skills/risk-register-keeper/SKILL.md +241 -0
  10. package/sdlc/files/_common/skills/sdlc-implementer/SKILL.md +38 -28
  11. package/sdlc/files/ci/compliance-evidence.yml.template +20 -4
  12. package/sdlc/files/sdlc-config.example.json +17 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@metasession.co/devaudit-cli",
3
- "version": "0.1.43",
3
+ "version": "0.1.45",
4
4
  "description": "DevAudit CLI — installs, syncs, and operates the Metasession SDLC across consumer projects.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -33,7 +33,7 @@
33
33
  },
34
34
  "dependencies": {
35
35
  "@clack/prompts": "^0.8.2",
36
- "@metasession.co/devaudit-plugin-sdk": "^0.1.43",
36
+ "@metasession.co/devaudit-plugin-sdk": "^0.1.45",
37
37
  "commander": "^12.1.0",
38
38
  "consola": "^3.2.3",
39
39
  "env-paths": "^3.0.0",
package/sdlc/SKILLS.md CHANGED
@@ -93,18 +93,39 @@ node scripts/validate-adapter.cjs sdlc/files/_common/skills/<name>/SKILL.md
93
93
 
94
94
  ## Skills currently shipped
95
95
 
96
- | Skill | Location | Triggers (paraphrased) | Additional emissions |
97
- | ----------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
98
- | `e2e-test-engineer` | `_common/skills/` | "add e2e tests", "bootstrap an e2e suite", "update the test pack", "are any tests obsolete", "run e2e tests and file issues" | `e2e/helpers/evidence.ts` + `evidence-shot-core.ts` (node-stack consumers) |
99
- | `sdlc-implementer` | `_common/skills/` | "implement issue #N under the SDLC", "run the SDLC for issue #N", "automate REQ-XXX from issue to release", "resume REQ-XXX" | — (orchestrator; invokes `e2e-test-engineer` + `governance-doc-author`) |
100
- | `governance-doc-author` | `_common/skills/` | "create / refresh the RoPA", "write a DPIA", "update the AI disclosure", "set up the periodic review schedule", "GDPR.Art-30 is MISSING on the matrix" (v0.1.37+) | `references/incident-classification.md` (shared with `e2e-test-engineer`) |
96
+ | Skill | Location | Triggers (paraphrased) | Additional emissions |
97
+ | ----------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
98
+ | `e2e-test-engineer` | `_common/skills/` | "add e2e tests", "bootstrap an e2e suite", "update the test pack", "are any tests obsolete", "run e2e tests and file issues" | `e2e/helpers/evidence.ts` + `evidence-shot-core.ts` (node-stack consumers) |
99
+ | `sdlc-implementer` | `_common/skills/` | "implement issue #N under the SDLC", "run the SDLC for issue #N", "automate REQ-XXX from issue to release", "resume REQ-XXX" | — (orchestrator; invokes `e2e-test-engineer`, `governance-doc-author`, and the three SoT-alignment skills) |
100
+ | `governance-doc-author` | `_common/skills/` | "create / refresh the RoPA", "write a DPIA", "update the AI disclosure", "set up the periodic review schedule", "GDPR.Art-30 is MISSING on the matrix" (v0.1.37+) | `references/incident-classification.md` (shared with `e2e-test-engineer`) |
101
+ | `requirements-aligner` | `_common/skills/` | "align SRS for REQ-XXX", "what SRS items did this REQ need?", "is the SRS in sync with this branch?" (v0.1.42+). Auto-invoked by `sdlc-implementer` at Stage 1 plan-APPROVAL + Stage 3 evidence-pack. | Maintains `docs/SRS.md`; drops `compliance/evidence/REQ-XXX/srs-alignment.md` per cycle. |
102
+ | `adr-author` | `_common/skills/` | "draft an ADR for REQ-XXX", "does this REQ need an ADR?", "is the architectural decision documented?" (v0.1.43+). Auto-invoked by `sdlc-implementer` at Stage 1 + Stage 3. | Maintains `docs/ADR/ADR-NNN-<slug>.md`; drops `compliance/evidence/REQ-XXX/architecture-decision.md` per cycle. Closes `ISO27001.A.8.25`. |
103
+ | `risk-register-keeper` | `_common/skills/` | "draft a risk-register entry for REQ-XXX", "is the risk register up to date for this branch?", "incident-report-N just exported, draft the residual-risk entry" (v0.1.44+). Auto-invoked by `sdlc-implementer` at Stage 1 (MEDIUM/HIGH) + Stage 3, and by `incident-export.yml` at incident close. | Maintains `compliance/risk-register.md` + the `governance/risk-register.md.template` starter; drops `compliance/evidence/REQ-XXX/risk-assessment.md`. Closes `SOC2.CC3.2`. |
101
104
 
102
105
  `sdlc-implementer` is the **default entry point for a tracked change** — an **orchestration skill** that drives Claude Code's native tools (`gh`, shell, `devaudit` CLI, portal API) through the full 5-stage flow against a single GitHub issue, pausing only at the UAT-review gate (and at the plan checkpoint for HIGH/CRITICAL risk). It is synced into every consumer (`.claude/skills/sdlc-implementer/`) by `devaudit update`. It replaces an earlier roadmap of five atomic skills (`risk-classifier`, `commit-message-author`, `compliance-evidence-author`, `sast-triager`, `release-ticket-author`) that were deprioritised — Claude Code's innate capabilities already cover what those atomic skills wrapped; the value-add is end-to-end orchestration with framework-compliant pauses, not five discoverable helpers a human still has to compose.
103
106
 
104
- **Sub-skill invocation requirement.** During its Phase 2 (Implement & test), the orchestrator **MUST** invoke `e2e-test-engineer` for any end-to-end or visual-regression test work — both scenario derivation from the implementation plan and execution of the resulting suite. The orchestrator does NOT author e2e tests directly. (Unit tests stay with the orchestrator until a unit-test counterpart skill ships.) The invocation pattern is documented in [docs/adding-a-skill.md §Orchestrator skills](../docs/adding-a-skill.md#orchestrator-skills-calling-other-skills); this is a hard contract — the orchestrator's SKILL.md fails review if it inlines `e2e-test-engineer`'s procedure.
107
+ **Sub-skill invocation contract.** The orchestrator delegates at every phase rather than authoring inline:
108
+
109
+ - **Phase 1 (Plan)** — invoke `requirements-aligner` to populate the AC table's SRS-ID column; invoke `adr-author` to decide ADR-worthiness + draft the ADR when warranted; invoke `risk-register-keeper` (MEDIUM/HIGH only by default) to draft RISK-NNN entries.
110
+ - **Phase 2 (Implement & test)** — invoke `e2e-test-engineer` for ALL end-to-end or visual-regression test work. The orchestrator does NOT author e2e tests directly. (Unit tests stay with the orchestrator until a unit-test counterpart skill ships.)
111
+ - **Phase 3 (Compile evidence)** — invoke each of `requirements-aligner`, `adr-author`, `risk-register-keeper` to drop their per-REQ Tier 3 traceability artefacts (`srs-alignment.md`, `architecture-decision.md`, `risk-assessment.md`).
112
+
113
+ These delegations are hard contracts — the orchestrator's SKILL.md fails review if it inlines a specialist skill's procedure. The invocation pattern is documented in [docs/adding-a-skill.md §Orchestrator skills](../docs/adding-a-skill.md#orchestrator-skills-calling-other-skills).
105
114
 
106
115
  `sdlc-implementer` is **not** used for trivial / housekeeping changes (docs, formatting, dependency bumps, CI tweaks) — those skip the requirement and the ceremony. See [the change-type matrix](../docs/change-workflows.md) and the [trivial-change walkthrough](./files/_common/implementing-an-sdlc-issue.md#trivial-change-walkthrough).
107
116
 
117
+ ### The SoT-alignment skill family
118
+
119
+ `requirements-aligner`, `adr-author`, and `risk-register-keeper` form the **SoT-alignment family** (v0.1.42 → v0.1.44). They share a uniform shape: each owns one persistent Tier 2 source-of-truth document, fires at Stage 1 plan-APPROVAL (advisory by default, configurable to block) and Stage 3 evidence-pack (hard gate on the per-REQ Tier 3 artefact), and produces a per-REQ traceability evidence file the CI uploads to the portal. The family closes the silent-drift gap between shipped code and the project's three SoT documents at edit time.
120
+
121
+ | Skill | Tier 2 SoT it maintains | Tier 3 per-REQ artefact | Closes framework clause |
122
+ | ---------------------- | ----------------------------- | ------------------------------------ | ------------------------------------------------------------------- |
123
+ | `requirements-aligner` | `docs/SRS.md` | `srs-alignment.md` (per REQ) | none in v1 (orphan-by-design per framework-registry-auditor review) |
124
+ | `adr-author` | `docs/ADR/ADR-NNN-<slug>.md` | `architecture-decision.md` (per REQ) | `ISO27001.A.8.25` Secure development life cycle |
125
+ | `risk-register-keeper` | `compliance/risk-register.md` | `risk-assessment.md` (per REQ) | `SOC2.CC3.2` Risk identification and assessment |
126
+
127
+ Each skill is **configurable per project** via `sdlc-config.json` (`requirements_aligner`, `adr_author`, `risk_register_keeper` blocks) — `block_on_stage_1: false` is the default in v1 so the skill advises but doesn't block plan APPROVAL; flip to `true` once calibrated.
128
+
108
129
  ## Skills on the roadmap
109
130
 
110
131
  No concrete candidates are queued. A `unit-test-engineer` counterpart to `e2e-test-engineer` is the most likely next skill, but it lands only when day-to-day work repeatedly surfaces the pain and the orchestrator demonstrably needs it as a separable component. Tracking: [`metasession-dev/DevAudit-Installer#29`](https://github.com/metasession-dev/DevAudit-Installer/issues/29).
package/sdlc/files/_common/1-plan-requirement.md CHANGED
@@ -25,7 +25,7 @@ description: Define a new requirement in the RTM, classify risk, create implemen
25
25
 
26
26
  ### Step 1: Identify the GitHub Issue
27
27
 
28
- Every tracked change starts from a GitHub Issue. The issue provides the *what* and *why*; the RTM provides the compliance audit trail.
28
+ Every tracked change starts from a GitHub Issue. The issue provides the _what_ and _why_; the RTM provides the compliance audit trail.
29
29
 
30
30
  - If the user references an issue number (e.g., `#123`): fetch its title, description, and labels using `gh issue view 123`.
31
31
  - 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).
42
42
 
43
43
  ### Step 3: Classify Risk Level
44
44
 
45
- | Risk Level | Criteria |
46
- |---|---|
47
- | **Low** | Internal tools, no regulated data, no auth changes |
45
+ | Risk Level | Criteria |
46
+ | ---------- | ---------------------------------------------------------------- |
47
+ | **Low** | Internal tools, no regulated data, no auth changes |
48
48
  | **Medium** | Touches PII, user-facing features, API changes, new dependencies |
49
- | **High** | Security, payments, RBAC, data handling, authentication |
49
+ | **High** | Security, payments, RBAC, data handling, authentication |
50
50
 
51
51
  AI involvement raises risk by one level when touching Medium or High categories. See Test Policy for the full risk matrix.
52
52
 
@@ -68,11 +68,12 @@ mkdir -p compliance/evidence/REQ-XXX
68
68
 
69
69
  ### Step 6: Implementation Plan (MEDIUM/HIGH Risk — Required)
70
70
 
71
- 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.
71
+ 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.
72
72
 
73
73
  **Skip this step** for LOW risk requirements — proceed directly to Step 7.
74
74
 
75
75
  **6a. Explore the codebase:**
76
+
76
77
  - Understand existing patterns, models, services, and API routes relevant to the change
77
78
  - Identify files that will be created, modified, or affected
78
79
 
@@ -89,27 +90,35 @@ Create `compliance/evidence/REQ-XXX/implementation-plan.md`:
89
90
  **Date:** [YYYY-MM-DD]
90
91
 
91
92
  ## Approach
93
+
92
94
  [1-3 sentences describing the overall approach]
93
95
 
94
96
  ## Files to Create
97
+
95
98
  - `path/to/new-file.ts` — [purpose]
96
99
 
97
100
  ## Files to Modify
101
+
98
102
  - `path/to/existing-file.ts` — [what changes and why]
99
103
 
100
104
  ## Architecture Decisions
101
105
 
102
106
  > 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.
103
107
 
104
- - ADR-NNN — <title> (`docs/ADR/ADR-NNN-<slug>.md`) — Operator edits stub + flips to *Accepted* before APPROVAL — OR — No ADR needed — <rationale>
108
+ - ADR-NNN — <title> (`docs/ADR/ADR-NNN-<slug>.md`) — Operator edits stub + flips to _Accepted_ before APPROVAL — OR — No ADR needed — <rationale>
105
109
 
106
110
  ## Dependencies
111
+
107
112
  - [New packages needed, or "None"]
108
113
 
109
114
  ## Risks / Considerations
110
- - [Anything that could go wrong or needs special attention]
115
+
116
+ > 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.
117
+
118
+ - RISK-NNN — <title> (`compliance/risk-register.md`) — Operator edits canonical row + signs off residual rating before APPROVAL — OR — @risk-deferred — <rationale>
111
119
 
112
120
  ## Post-Deploy Actions
121
+
113
122
  - [Data migrations, backfill scripts, schema changes — or "None"]
114
123
  - [If any: create script in `scripts/`, document exact command and target environment]
115
124
  ```
@@ -117,6 +126,7 @@ Create `compliance/evidence/REQ-XXX/implementation-plan.md`:
117
126
  ### WAIT CHECKPOINT: Implementation Plan Review
118
127
 
119
128
  **Present the implementation plan to the developer.** Summarize:
129
+
120
130
  - Approach and rationale
121
131
  - Files to create/modify
122
132
  - Architecture decisions
@@ -277,6 +287,7 @@ EOF
277
287
  ### WAIT CHECKPOINT: Test Scope Review
278
288
 
279
289
  **Present the test scope to the developer.** Summarize:
290
+
280
291
  - Risk classification and rationale
281
292
  - Test approach (which additional testing applies)
282
293
  - Acceptance criteria
@@ -332,6 +343,7 @@ EOF
332
343
  ### WAIT CHECKPOINT: Test Plan Review
333
344
 
334
345
  **Present the test plan to the developer.** Summarize:
346
+
335
347
  - Tests to add, update, and remove
336
348
  - How acceptance criteria map to specific tests
337
349
  - Any non-functional testing required
package/sdlc/files/_common/Implementation_Plan_TEMPLATE.md CHANGED
@@ -21,27 +21,27 @@ authored_at: "REPLACE — YYYY-MM-DD"
21
21
 
22
22
  **Closes clauses** (every implementation plan satisfies all four):
23
23
 
24
- | Clause | What this plan must contain |
25
- |---|---|
26
- | **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. |
27
- | **ISO 27001 A.8.25** Secure development life cycle | Threat model + secure-design considerations (auth, data handling, dependencies, secrets). |
24
+ | Clause | What this plan must contain |
25
+ | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
26
+ | **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. |
27
+ | **ISO 27001 A.8.25** Secure development life cycle | Threat model + secure-design considerations (auth, data handling, dependencies, secrets). |
28
28
  | **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.** |
29
- | **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.** |
29
+ | **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.** |
30
30
 
31
31
  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.
32
32
 
33
33
  ## 1. Goal + acceptance criteria
34
34
 
35
- > *Closes ISO 29119 §3.4 — test plan*
35
+ > _Closes ISO 29119 §3.4 — test plan_
36
36
 
37
37
  - **Goal:** REPLACE — one sentence describing what this REQ delivers, no jargon.
38
38
  - **Acceptance criteria:**
39
39
 
40
- | AC | Description | SRS item it traces to |
41
- |---|---|---|
40
+ | AC | Description | SRS item it traces to |
41
+ | --- | ------------------------------------------ | --------------------------------------------------------------------------------------- |
42
42
  | AC1 | REPLACE — one-line behavioural description | REQ-AREA-NNN (existing) / REQ-AREA-NNN (new — propose stub) / `@srs-deferred: <reason>` |
43
- | AC2 | REPLACE | REPLACE |
44
- | … | | |
43
+ | AC2 | REPLACE | REPLACE |
44
+ | … | | |
45
45
 
46
46
  > **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).
47
47
 
@@ -52,13 +52,13 @@ Each section below maps to one (or more) of these clauses. Don't delete sections
52
52
 
53
53
  ## 3. Architecture decisions
54
54
 
55
- > *Populated by the [`adr-author` skill](../skills/adr-author/SKILL.md) at Stage 1 plan APPROVAL.*
55
+ > _Populated by the [`adr-author` skill](../skills/adr-author/SKILL.md) at Stage 1 plan APPROVAL._
56
56
 
57
57
  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.
58
58
 
59
59
  When **ADR warranted**:
60
60
 
61
- - **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.
61
+ - **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.
62
62
 
63
63
  When **No ADR needed**:
64
64
 
@@ -68,20 +68,31 @@ The negative case is audit evidence too — auditors examine "no ADR — <ration
68
68
 
69
69
  ## 4. Threat model + security considerations
70
70
 
71
- > *Closes ISO 27001 A.8.25 — secure development life cycle*
71
+ > _Closes ISO 27001 A.8.25 — secure development life cycle_
72
72
 
73
- | Threat | Likelihood | Impact | Mitigation |
74
- |---|---|---|---|
75
- | REPLACE — e.g. SQL injection via X param | REPLACE | REPLACE | REPLACE |
76
- | REPLACE — e.g. unauthenticated access to Y route | REPLACE | REPLACE | REPLACE |
73
+ | Threat | Likelihood | Impact | Mitigation |
74
+ | ------------------------------------------------ | ---------- | ------- | ---------- |
75
+ | REPLACE — e.g. SQL injection via X param | REPLACE | REPLACE | REPLACE |
76
+ | REPLACE — e.g. unauthenticated access to Y route | REPLACE | REPLACE | REPLACE |
77
77
 
78
78
  **Secrets / credentials:** REPLACE — does this REQ handle any? If yes, how stored, rotated, scoped?
79
79
 
80
80
  **Dependencies introduced:** REPLACE — list new npm/pip packages; flag any with known CVEs or transitive concerns.
81
81
 
82
+ ### Risk register entries
83
+
84
+ > _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._
85
+
86
+ When **risk class is MEDIUM or HIGH**, expect a list like:
87
+
88
+ - **RISK-NNN — <title>** — Status: OPEN. Opened by `risk-register-keeper`. Operator edits canonical row + signs off residual rating before plan APPROVAL.
89
+ - **RISK-NNN — <title>** — Status: MITIGATED. Controls landing in this PR close the residual.
90
+
91
+ 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.
92
+
82
93
  ## 5. Data protection (GDPR Art. 25)
83
94
 
84
- > *Closes GDPR Art. 25 — data protection by design*
95
+ > _Closes GDPR Art. 25 — data protection by design_
85
96
 
86
97
  **Personal data processed by this REQ:** REPLACE — yes / no.
87
98
 
@@ -99,11 +110,11 @@ If **yes**, fill in:
99
110
  - Is a DPIA required? REPLACE — yes (file under `compliance/governance/dpia-<reqid>.md`) / no / N/A
100
111
  - **Cross-border transfers:** REPLACE — none / specify mechanism
101
112
 
102
- If **no**, write: *"N/A — this REQ does not process personal data. <Why — e.g. UI-only change, internal-routing refactor, dev-tooling.>"*
113
+ If **no**, write: _"N/A — this REQ does not process personal data. <Why — e.g. UI-only change, internal-routing refactor, dev-tooling.>"_
103
114
 
104
115
  ## 6. AI / model considerations (EU AI Act Art. 11)
105
116
 
106
- > *Closes EUAIA Art. 11 — technical documentation*
117
+ > _Closes EUAIA Art. 11 — technical documentation_
107
118
 
108
119
  **AI / ML in scope for this REQ:** REPLACE — yes / no.
109
120
 
@@ -117,7 +128,7 @@ If **yes**, fill in:
117
128
  - **Cross-references:**
118
129
  - Is `compliance/governance/ai-disclosure.md` updated? REPLACE — yes / no / N/A
119
130
 
120
- If **no**, write: *"N/A — this REQ does not introduce or change AI behaviour. <Why.>"*
131
+ If **no**, write: _"N/A — this REQ does not introduce or change AI behaviour. <Why.>"_
121
132
 
122
133
  ## 7. Rollback plan
123
134
 
package/sdlc/files/_common/governance/risk-register.md.template ADDED
@@ -0,0 +1,116 @@
1
+ ---
2
+ title: 'Risk register'
3
+ project: 'REPLACE — project name'
4
+ maintained_by: 'risk-register-keeper skill (DevAudit-Installer v0.1.44+)'
5
+ scoring_matrix: 'likelihood × impact (3×3)'
6
+ last_reviewed_at: 'REPLACE — YYYY-MM-DD'
7
+ review_cadence_days: 90
8
+ ---
9
+
10
+ > ⚠️ **STARTER TEMPLATE — REPLACE BEFORE COMMITTING.**
11
+ > Installed on demand via `devaudit bootstrap-governance` as a starting point.
12
+ > 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.
13
+ > Auditors reject unedited stubs.
14
+
15
+ # Risk register — REPLACE project
16
+
17
+ **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.
18
+
19
+ **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).
20
+
21
+ **Scoring:** likelihood × impact, 3×3 matrix (low / medium / high). CVSS-aware scoring deferred to Phase B.
22
+
23
+ ---
24
+
25
+ ## Scoring matrix
26
+
27
+ | Inherent + Residual rating | Likelihood (frequency / ease-of-exploit) | Impact (worst-case if realised) |
28
+ |---|---|---|
29
+ | **Low** | Unlikely in a typical year; requires unusual access or coincidence | Recoverable inconvenience; no regulatory exposure |
30
+ | **Medium** | Plausible within a year; standard skill or access | Recoverable but disruptive; possible reportable incident |
31
+ | **High** | Probable within months; trivial to trigger | Material loss; regulatory reporting required |
32
+
33
+ Residual = post-mitigation rating. **A risk's residual rating drives review cadence:** Low = annual, Medium = quarterly, High = monthly until reduced.
34
+
35
+ ---
36
+
37
+ ## OPEN risks
38
+
39
+ > Risks currently being treated — controls planned but not yet demonstrated effective, or monitoring continues.
40
+
41
+ ### RISK-001 — REPLACE one-line title
42
+
43
+ - **Status:** OPEN
44
+ - **Opened:** YYYY-MM-DD (REQ-XXX) — REPLACE
45
+ - **Owner:** REPLACE — operator
46
+ - **Description:** REPLACE — what the risk is, in operator-readable terms (2-3 sentences).
47
+ - **Inherent likelihood × impact:** REPLACE (e.g. medium × high)
48
+ - **Mitigations planned / in flight:** REPLACE — list controls being applied
49
+ - **Residual likelihood × impact (post-mitigation):** REPLACE
50
+ - **Framework cross-references:** REPLACE — ISO27001.A.X.Y / SOC2.CC3.2 / GDPR.Art-32 (as applicable)
51
+ - **Review due:** YYYY-MM-DD (default: monthly for OPEN-HIGH, quarterly for OPEN-MEDIUM, annually for OPEN-LOW)
52
+ - **Cross-links:** REPLACE — REQ-XXX implementation plan / ADR-NNN / incident-report-N
53
+
54
+ ---
55
+
56
+ ## MITIGATED risks
57
+
58
+ > Risks whose controls have landed and been demonstrated effective. Residual rating ≤ Low. Periodic re-validation confirms controls remain effective.
59
+
60
+ ### RISK-NNN — example template
61
+
62
+ - **Status:** MITIGATED
63
+ - **Opened:** YYYY-MM-DD (REQ-XXX) / **Mitigated:** YYYY-MM-DD
64
+ - **Owner:** REPLACE
65
+ - **Description:** REPLACE
66
+ - **Original inherent likelihood × impact:** medium × high
67
+ - **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`")
68
+ - **Residual likelihood × impact:** low × low
69
+ - **Framework cross-references:** REPLACE
70
+ - **Re-validation due:** YYYY-MM-DD (default: annually for MITIGATED)
71
+ - **Cross-links:** REPLACE
72
+
73
+ ---
74
+
75
+ ## ACCEPTED risks
76
+
77
+ > 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.
78
+
79
+ ### RISK-NNN — example template
80
+
81
+ - **Status:** ACCEPTED
82
+ - **Opened:** YYYY-MM-DD / **Accepted:** YYYY-MM-DD
83
+ - **Owner:** REPLACE
84
+ - **Description:** REPLACE
85
+ - **Inherent likelihood × impact:** REPLACE
86
+ - **Mitigations applied:** REPLACE — partial mitigations + why full mitigation isn't pursued
87
+ - **Residual likelihood × impact:** REPLACE — tolerated
88
+ - **Acceptance rationale:** REPLACE — why the operator judges this acceptable (cost / use-case / compensating controls / regulatory context)
89
+ - **Acceptance sign-off:** REPLACE — operator name + date. For organisations with separate risk-owner role, the risk-owner signs off here, not the implementing engineer.
90
+ - **Framework cross-references:** REPLACE
91
+ - **Re-validation due:** YYYY-MM-DD (default: every 365d; sooner if the risk landscape changes)
92
+ - **Cross-links:** REPLACE
93
+
94
+ ---
95
+
96
+ ## CLOSED risks
97
+
98
+ > 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.
99
+
100
+ ### RISK-NNN — example template
101
+
102
+ - **Status:** CLOSED
103
+ - **Opened:** YYYY-MM-DD / **Closed:** YYYY-MM-DD
104
+ - **Owner:** REPLACE
105
+ - **Description:** REPLACE
106
+ - **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")
107
+ - **Cross-links:** REPLACE
108
+
109
+ ---
110
+
111
+ ## Audit-trail rules
112
+
113
+ - **Append-only edits.** Never delete a RISK-NNN entry. Status transitions (OPEN → MITIGATED → ACCEPTED → CLOSED) are visible audit history.
114
+ - **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.
115
+ - **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.
116
+ - **`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/governance-doc-author/SKILL.md CHANGED
@@ -7,25 +7,27 @@ description: Author or refresh one of the project's governance documents — RoP
7
7
 
8
8
  Author or refresh a single governance document so it correctly closes the framework clauses it's meant to satisfy. Five document classes covered:
9
9
 
10
- | Document | Tier | File | Upload path | Closes |
11
- |---|---|---|---|---|
12
- | **RoPA** | 2 | `compliance/governance/ropa.md` | **Portal Upload form** (type `ropa`) — CI does NOT auto-upload since v0.1.39 | `GDPR.Art-30` |
13
- | **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` |
14
- | **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` |
15
- | **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) |
16
- | **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]] |
10
+ | Document | Tier | File | Upload path | Closes |
11
+ | -------------------------------------------- | ---- | ------------------------------------------------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
12
+ | **RoPA** | 2 | `compliance/governance/ropa.md` | **Portal Upload form** (type `ropa`) — CI does NOT auto-upload since v0.1.39 | `GDPR.Art-30` |
13
+ | **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` |
14
+ | **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` |
15
+ | **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) |
16
+ | **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]] |
17
17
 
18
- 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.
18
+ 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.
19
19
 
20
20
  ## Scope
21
21
 
22
22
  **In scope**
23
+
23
24
  - Authoring or refreshing one (or more) of the five governance docs above.
24
25
  - Gathering source data from the codebase / CI runs / git history.
25
26
  - Confirming framework attribution before commit.
26
27
  - Driving the commit + push → portal upload (manual for Tier 1/2, CI auto for Tier 3) → portal verification loop.
27
28
 
28
29
  **Out of scope**
30
+
29
31
  - Incident response itself — that path is the `e2e-test-engineer` skill's defect-filing flow plus `incident-export.yml` on issue close.
30
32
  - Test execution evidence — handled by `e2e-test-engineer`.
31
33
  - 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.
39
41
 
40
42
  Determine which document the operator needs. Ask if ambiguous; otherwise infer from the trigger phrase.
41
43
 
42
- - *"create / refresh the RoPA"* → Phase 1 with doc = ROPA
43
- - *"write / update a DPIA"* → Phase 1 with doc = DPIA (ask: tied to a specific HIGH-risk REQ, or project-wide?)
44
- - *"AI use disclosure"* / *"document our AI use"* → Phase 1 with doc = AI_DISCLOSURE
45
- - *"periodic security review schedule"* / *"how often do we review"* → Phase 1 with doc = REVIEW_SCHEDULE
46
- - *"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)
44
+ - _"create / refresh the RoPA"_ → Phase 1 with doc = ROPA
45
+ - _"write / update a DPIA"_ → Phase 1 with doc = DPIA (ask: tied to a specific HIGH-risk REQ, or project-wide?)
46
+ - _"AI use disclosure"_ / _"document our AI use"_ → Phase 1 with doc = AI_DISCLOSURE
47
+ - _"periodic security review schedule"_ / _"how often do we review"_ → Phase 1 with doc = REVIEW_SCHEDULE
48
+ - _"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)
49
+ - _"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.
47
50
 
48
- When the trigger is *"GDPR.Art-30 is MISSING on the matrix, what do I upload?"* and similar — route to the matching doc above.
51
+ 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`.
49
52
 
50
53
  ### Phase 1 — Confirm the starter exists
51
54
 
@@ -61,7 +64,7 @@ Each doc class has different inputs. Read what's needed; don't ask the operator
61
64
  - Read `app/`, `lib/`, `prisma/schema.prisma` (or equivalent) to enumerate processing activities.
62
65
  - For each, infer: data categories, recipients (third-party SDKs / services), retention (DB triggers, env vars naming retention windows), lawful basis where reasonable.
63
66
  - Read `.env.example` for third-party service names.
64
- - Ask the operator to confirm purposes (you can guess the technical surface; the *purpose* is a business decision).
67
+ - Ask the operator to confirm purposes (you can guess the technical surface; the _purpose_ is a business decision).
65
68
 
66
69
  - **DPIA**
67
70
  - 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
92
95
 
93
96
  For each clause the doc closes, confirm the corresponding section of the doc is non-stub:
94
97
 
95
- | Doc | Clause | Section that must be non-stub |
96
- |---|---|---|
97
- | ROPA | GDPR.Art-30 | §Controller + ≥1 §Processing activities row with all fields filled |
98
- | DPIA | GDPR.Art-35 | All six sections (description / necessity / risks / measures / consultation / sign-off) |
99
- | AI_DISCLOSURE | EUAIA.Art-13 | All six checklist items in the template's Framework checklist |
100
- | REVIEW_SCHEDULE | ISO27001.A.12.1 | A schedule entry per control area + a named reviewer per cadence |
101
- | INCIDENT_TEMPLATE | ISO29119.3.5.4 baseline | §1–§8 of the template are skeletal but coherent (per-incident files inherit the shape) |
98
+ | Doc | Clause | Section that must be non-stub |
99
+ | ----------------- | ----------------------- | --------------------------------------------------------------------------------------- |
100
+ | ROPA | GDPR.Art-30 | §Controller + ≥1 §Processing activities row with all fields filled |
101
+ | DPIA | GDPR.Art-35 | All six sections (description / necessity / risks / measures / consultation / sign-off) |
102
+ | AI_DISCLOSURE | EUAIA.Art-13 | All six checklist items in the template's Framework checklist |
103
+ | REVIEW_SCHEDULE | ISO27001.A.12.1 | A schedule entry per control area + a named reviewer per cadence |
104
+ | INCIDENT_TEMPLATE | ISO29119.3.5.4 baseline | §1–§8 of the template are skeletal but coherent (per-incident files inherit the shape) |
102
105
 
103
106
  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.
104
107
 
@@ -118,10 +121,10 @@ Tier 1/2 docs (RoPA, DPIA, AI Disclosure, Periodic Security Review Schedule) and
118
121
 
119
122
  These are **two different artefacts** and the skill must not conflate them:
120
123
 
121
- | Artefact | What | Closes | Cadence | Skill responsibility |
122
- |---|---|---|---|---|
123
- | **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. |
124
- | **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. |
124
+ | Artefact | What | Closes | Cadence | Skill responsibility |
125
+ | ---------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
126
+ | **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. |
127
+ | **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. |
125
128
 
126
129
  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`).
127
130
 
@@ -139,7 +142,7 @@ When Phase 5 commits successfully, append a short narrator update in the final r
139
142
 
140
143
  **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.
141
144
 
142
- **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.
145
+ **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.
143
146
 
144
147
  **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.
145
148