@metasession.co/devaudit-cli 0.1.36 → 0.1.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.1.36",
+  "version": "0.1.37",
   "description": "DevAudit CLI — installs, syncs, and operates the Metasession SDLC across consumer projects.",
   "type": "module",
   "bin": {
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.8.2",
-    "@metasession.co/devaudit-plugin-sdk": "^0.1.36",
+    "@metasession.co/devaudit-plugin-sdk": "^0.1.37",
     "commander": "^12.1.0",
     "consola": "^3.2.3",
     "env-paths": "^3.0.0",

package/sdlc/files/_common/Implementation_Plan_TEMPLATE.md

@@ -0,0 +1,126 @@
+---
+title: "Implementation plan — REQ-XXX"
+requirement_id: "REQ-XXX"
+risk_class: "REPLACE — HIGH | MEDIUM | LOW"
+change_type: "REPLACE — feat | fix | refactor | perf | chore | docs | ci | build | test | compliance | revert"
+authored_by: "REPLACE — operator / agent"
+authored_at: "REPLACE — YYYY-MM-DD"
+---
+
+> ⚠️ **STARTER TEMPLATE — REPLACE EVERY `REPLACE` MARKER BEFORE COMMITTING.**
+> The shape of this doc is load-bearing: the framework-coverage matrix
+> closes four different clauses based on this plan being present + tagged
+> with the correct evidence category. Empty stub commits flip the
+> matrix to COVERED with placeholder content — auditors reject this.
+
+# Implementation plan — REQ-XXX
+
+## Framework attribution
+
+**Evidence type:** `compliance_document` · **Category:** `planning` · **Scope:** per-REQ
+
+**Closes clauses** (every implementation plan satisfies all four):
+
+| Clause | What this plan must contain |
+|---|---|
+| **ISO 29119 §3.4** Test Plan | Acceptance criteria + the strategy for verifying each one. Reference the per-REQ `test-plan.md` if it lives separately. |
+| **ISO 27001 A.8.25** Secure development life cycle | Threat model + secure-design considerations (auth, data handling, dependencies, secrets). |
+| **GDPR Art. 25** Data protection by design and by default | Per-purpose data flows; minimisation; lawful basis; retention. **Required for any REQ that processes personal data; explicit "no personal data" callout if not.** |
+| **EU AI Act Art. 11** Technical documentation (Annex IV) | When the REQ touches AI / model behaviour: model provenance, prompt sources, oversight path. **Explicit "no AI in scope" callout if not.** |
+
+Each section below maps to one (or more) of these clauses. Don't delete sections — mark with "N/A — <reason>" if the clause genuinely doesn't apply.
+
+## 1. Goal + acceptance criteria
+
+> *Closes ISO 29119 §3.4 — test plan*
+
+- **Goal:** REPLACE — one sentence describing what this REQ delivers, no jargon.
+- **Acceptance criteria:**
+  - AC1 — REPLACE
+  - AC2 — REPLACE
+  - …
+
+## 2. Scope
+
+- **In scope:** REPLACE — list every file / module / surface the change touches.
+- **Out of scope:** REPLACE — adjacent areas the change deliberately leaves alone.
+
+## 3. Threat model + security considerations
+
+> *Closes ISO 27001 A.8.25 — secure development life cycle*
+
+| Threat | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| REPLACE — e.g. SQL injection via X param | REPLACE | REPLACE | REPLACE |
+| REPLACE — e.g. unauthenticated access to Y route | REPLACE | REPLACE | REPLACE |
+
+**Secrets / credentials:** REPLACE — does this REQ handle any? If yes, how stored, rotated, scoped?
+
+**Dependencies introduced:** REPLACE — list new npm/pip packages; flag any with known CVEs or transitive concerns.
+
+## 4. Data protection (GDPR Art. 25)
+
+> *Closes GDPR Art. 25 — data protection by design*
+
+**Personal data processed by this REQ:** REPLACE — yes / no.
+
+If **yes**, fill in:
+
+- **Categories of data subjects:** REPLACE
+- **Categories of personal data:** REPLACE (name, email, IP, etc.)
+- **Special categories (Art. 9):** REPLACE — none / specify
+- **Lawful basis:** REPLACE — Art. 6(1)(a-f) — pick one + justify
+- **Purpose limitation:** REPLACE — how the design prevents repurposing
+- **Data minimisation:** REPLACE — fields collected vs fields needed
+- **Retention:** REPLACE — how long, then what happens
+- **Cross-references:**
+  - Is the ROPA (`compliance/governance/ropa.md`) updated? REPLACE — yes / no / N/A
+  - Is a DPIA required? REPLACE — yes (file under `compliance/governance/dpia-<reqid>.md`) / no / N/A
+- **Cross-border transfers:** REPLACE — none / specify mechanism
+
+If **no**, write: *"N/A — this REQ does not process personal data. <Why — e.g. UI-only change, internal-routing refactor, dev-tooling.>"*
+
+## 5. AI / model considerations (EU AI Act Art. 11)
+
+> *Closes EUAIA Art. 11 — technical documentation*
+
+**AI / ML in scope for this REQ:** REPLACE — yes / no.
+
+If **yes**, fill in:
+
+- **Model(s) used:** REPLACE — provider, model name, version
+- **Inputs / outputs:** REPLACE
+- **Prompt sources:** REPLACE — hardcoded / user-supplied / template-substituted
+- **Human-oversight path:** REPLACE — what stops a bad output reaching a user? Review gate / circuit breaker / rate limit / etc.
+- **Accuracy / robustness considerations:** REPLACE — known failure modes, planned guardrails
+- **Cross-references:**
+  - Is `compliance/governance/ai-disclosure.md` updated? REPLACE — yes / no / N/A
+
+If **no**, write: *"N/A — this REQ does not introduce or change AI behaviour. <Why.>"*
+
+## 6. Rollback plan
+
+- **Reversible via:** REPLACE — git revert / migration down / config flip / etc.
+- **Data implications of rollback:** REPLACE — any data written by the new code that an older version can't read?
+- **Notification path if rollback during a release:** REPLACE — who hears, how quickly?
+
+## 7. Verification
+
+How the team will know the REQ is correct in production:
+
+- **Unit + integration tests:** REPLACE — what's added / changed
+- **E2E coverage:** REPLACE — which spec(s); reference per-AC `evidenceShot()` captures
+- **Manual smoke after deploy:** REPLACE — bullet-list, or "none" with reason
+- **Monitoring / alerting:** REPLACE — what dashboards / alerts the change adds or relies on
+
+## 8. Sign-off
+
+- **Plan reviewer (eng):** REPLACE — name + date
+- **Plan reviewer (security / DPO):** REPLACE — when GDPR or threat-model sections are non-trivial; otherwise "N/A"
+- **Plan approved by operator:** REPLACE — name + date
+
+## Upload path
+
+This file lives at `compliance/plans/REQ-XXX/implementation-plan.md` and is uploaded automatically on the next push to `develop` via `compliance-evidence.yml`. The portal's framework-coverage matrix flips ISO 29119 §3.4, ISO 27001 A.8.25, GDPR Art. 25, and EU AI Act Art. 11 to COVERED for this REQ once the upload lands.
+
+Verify the upload at `https://devaudit.metasession.co/projects/<slug>/releases/REQ-XXX` — the "Evidence by requirement" list should show this plan tagged with `category=planning`.

package/sdlc/files/_common/governance/ai-disclosure.md.template

@@ -7,10 +7,10 @@ review_cadence_days: 180
 risk_class: "REPLACE — minimal | limited | high | unacceptable"
 ---
 
-> ⚠️ **STARTER TEMPLATE — REPLACE BEFORE GOING TO PRODUCTION.**
-> This file was auto-installed by `devaudit install` as a starting point.
-> It does **not** describe your project's actual AI use. Edit and commit.
-> Auditors will reject unedited stubs. See `docs/governance-templates.md` for guidance.
+> ⚠️ **STARTER TEMPLATE — REPLACE BEFORE COMMITTING.**
+> Installed on demand via `devaudit bootstrap-governance` (v0.1.36+) as a starting point.
+> It does **not** describe your project's actual AI use. Edit before committing.
+> Auditors reject unedited stubs. See `docs/governance-templates.md` for guidance.
 
 # AI Use Disclosure — Provision of information to deployers
 
@@ -20,6 +20,23 @@ risk_class: "REPLACE — minimal | limited | high | unacceptable"
 
 > The EU AI Act requires providers to give deployers (the people who put the AI system into use in their professional activity) **clear, comprehensive, accurate and unambiguous** information about the system's capabilities, limitations, and intended use. This file is that disclosure for our project — both for AI we develop and for third-party AI we incorporate.
 
+## Uploading this artefact
+
+- **File path:** `compliance/governance/ai-disclosure.md`
+- **Upload trigger:** automatic — on every push to `develop` that touches `compliance/**`, `compliance-evidence.yml` uploads this file as `ai_disclosure` evidence.
+- **Verify after merge:** open `/projects/<slug>/compliance`. The **EU AI Act Art. 13** clause should flip MISSING → COVERED within ~2 minutes.
+- **Refresh cadence:** every 180 days, or whenever an AI tool / model / prompt-class is added or materially changed. Source data: git `Co-Authored-By: Claude` trailers + CI usage logs + per-REQ implementation-plan §5.
+
+## Framework checklist — EU AI Act Art. 13
+
+- [ ] §1 Intended purpose: what the AI does + intended use + foreseeable misuse
+- [ ] §2 Capabilities + limitations: known performance bounds + known failure modes
+- [ ] §3 Each AI tool listed: provider, model, version, where invoked in the codebase
+- [ ] §4 Human-oversight path documented per Art. 14 (cross-reference: four-eyes release approval)
+- [ ] §5 Accuracy + robustness measures named (Art. 15)
+- [ ] §6 Data inputs / training data provenance disclosed where applicable
+- [ ] `last_reviewed_at` frontmatter matches the actual review date
+
 ## 1. Intended purpose
 
 - **What the AI system does:** REPLACE

package/sdlc/files/_common/governance/dpia.md.template

@@ -7,10 +7,10 @@ review_cadence_days: 365
 risk_level: "REPLACE — low | medium | high"
 ---
 
-> ⚠️ **STARTER TEMPLATE — REPLACE BEFORE GOING TO PRODUCTION.**
-> This file was auto-installed by `devaudit install` as a starting point.
-> It does **not** describe your project's actual data protection risks. Edit and commit.
-> Auditors will reject unedited stubs. See `docs/governance-templates.md` for guidance.
+> ⚠️ **STARTER TEMPLATE — REPLACE BEFORE COMMITTING.**
+> Installed on demand via `devaudit bootstrap-governance` (v0.1.36+) as a starting point.
+> It does **not** describe your project's actual data protection risks. Edit before committing.
+> Auditors reject unedited stubs. See `docs/governance-templates.md` for guidance.
 
 # Data Protection Impact Assessment
 
@@ -20,6 +20,22 @@ risk_level: "REPLACE — low | medium | high"
 
 > A DPIA is **mandatory** for processing likely to result in high risk to data subjects: large-scale special-category data, systematic monitoring, automated decision-making with legal effect, etc. See Art. 35(3) and your supervisory authority's "blacklist" guidance.
 
+## Uploading this artefact
+
+- **File path:** `compliance/governance/dpia.md` (or `dpia-<reqid>.md` for a per-REQ DPIA tied to a HIGH-risk requirement)
+- **Upload trigger:** automatic — on every push to `develop` that touches `compliance/**`, `compliance-evidence.yml` uploads this file as `dpia` evidence.
+- **Verify after merge:** open `/projects/<slug>/compliance`. The **GDPR Art. 35** clause should flip MISSING → COVERED within ~2 minutes.
+- **Refresh cadence:** annually (365 days), or sooner whenever the assessed processing materially changes (new data category, new recipient, new automated-decision path).
+
+## Framework checklist — GDPR Art. 35
+
+- [ ] §1 Description of processing: purpose + scope + lawful basis + data flow diagram or text-equivalent
+- [ ] §2 Necessity + proportionality: justified why this processing is needed, alternatives considered
+- [ ] §3 Risks to rights and freedoms: each risk → likelihood + severity + affected data subjects
+- [ ] §4 Measures to address the risks: each risk has a concrete mitigation (technical or organisational)
+- [ ] §5 Consultation: DPO + affected stakeholders consulted (or "not applicable — sole-dev project" stated explicitly)
+- [ ] §6 Sign-off: data controller approval recorded with date
+
 ## 1. Description of the processing
 
 - **Activity name:** REPLACE

package/sdlc/files/_common/governance/incident-report.md.template

@@ -10,11 +10,11 @@ notification_window_72h: "REPLACE — within | outside | n/a"
 last_reviewed_at: "REPLACE — YYYY-MM-DD"
 ---
 
-> ⚠️ **STARTER TEMPLATE — REPLACE BEFORE GOING TO PRODUCTION.**
-> This file was auto-installed by `devaudit install` as a starting point.
+> ⚠️ **STARTER TEMPLATE — REPLACE BEFORE COMMITTING.**
+> Installed on demand via `devaudit bootstrap-governance` (v0.1.36+) as a starting point.
 > If you reach for this file it's because something **happened** — replace this banner
 > with the actual incident details. One incident per file (rename to
-> `incident-report-<id>.md` if you keep multiple). Auditors will reject unedited stubs.
+> `incident-report-<id>.md` if you keep multiple). Auditors reject unedited stubs.
 
 # Incident Report
 
@@ -27,6 +27,39 @@ last_reviewed_at: "REPLACE — YYYY-MM-DD"
 
 **Evidence type:** `incident_report` · One artefact can satisfy multiple clauses depending on its scope (test defect, ops incident, personal-data breach).
 
+## Uploading this artefact
+
+- **File path:** `compliance/governance/incident-report.md` (the template) or `compliance/governance/incident-report-<id>.md` (per-incident — recommended; the `incident-export.yml` workflow auto-produces these from closed GitHub issues labelled `incident`)
+- **Upload trigger:** automatic — on every push to `develop` that touches `compliance/**`, `compliance-evidence.yml` uploads this file as `incident_report` evidence via the `upload_governance` helper.
+- **Verify after merge:** open `/projects/<slug>/compliance`. `ISO29119.3.5.4` always flips to COVERED (baseline). `SOC2.CC7.2`, `GDPR.Art-33`, `GDPR.Art-34` flip only when the relevant attribution sections below are non-stub.
+- **Refresh cadence:** none — incidents are point-in-time. Authoring is event-driven.
+
+## Framework attribution — which clauses THIS incident closes
+
+Mandatory baseline (every incident_report attributes to it):
+
+- [x] **ISO 29119 §3.5.4** Test incident report — always.
+
+Conditional — tick the boxes that match this incident's scope, then ensure the corresponding section is fully populated:
+
+- [ ] **SOC 2 CC7.2** System monitoring and incident response — ops impact / downtime / persistent errors / perf regression / data corruption
+- [ ] **GDPR Art. 33** Breach notification (supervisory authority) — personal data was exposed, lost, or mishandled (72h window applies)
+- [ ] **GDPR Art. 34** Breach notification (data subject) — affected data subjects need to be told (high-risk threshold per Art. 34(1))
+- [ ] **EU AI Act Art. 9 / 14 / 15** — AI / model failure, oversight bypass, accuracy / robustness regression. Cross-reference `compliance/governance/ai-disclosure.md`.
+
+If none of the conditional boxes apply, this is still a valid incident_report — it just closes ISO 29119 §3.5.4 only. The "no specific framework impact" case is genuine and should not be padded.
+
+## Framework checklist — fields auditors look for
+
+- [ ] §1 Summary: incident ID, severity, dates discovered/contained/closed, root cause one-liner
+- [ ] §2 Timeline: actor + action + time, chronological
+- [ ] §3 Affected scope: systems, data, users (counts where known)
+- [ ] §4 GDPR triage: personal data Y/N → if Y, categories + count of data subjects + notification path
+- [ ] §5 Root cause: blameless, technical, sufficient detail to prevent recurrence
+- [ ] §6 Containment + remediation: what was done, what's still open
+- [ ] §7 Follow-up actions: each → owner → due date
+- [ ] §8 Sign-off: incident commander + eng lead (+ DPO when PII, + security lead when security)
+
 ## 1. Summary
 
 - **Incident ID:** REPLACE

package/sdlc/files/_common/governance/periodic-review.md.template

@@ -7,14 +7,14 @@ last_reviewed_at: "REPLACE — YYYY-MM-DD"
 review_cadence_days: 90
 ---
 
-> ⚠️ **STARTER TEMPLATE — REPLACE BEFORE GOING TO PRODUCTION.**
-> This file was auto-installed by `devaudit install` as a starting point.
+> ⚠️ **STARTER TEMPLATE — REPLACE BEFORE COMMITTING.**
+> Installed on demand via `devaudit bootstrap-governance` (v0.1.36+) as a starting point.
 > The Periodic Review workflow (`.github/workflows/periodic-review.yml`, shipped in
 > v0.1.31) auto-regenerates this file quarterly with locally-derived metrics and
 > opens a PR. The human attestation sections (Review notes, control-effectiveness
 > judgement, dual-actor sign-off) still need to be filled in before each PR can
 > merge — the auto-generator can't produce defensible attestation on its own.
-> Auditors will reject unedited stubs. See `docs/governance-templates.md` for guidance.
+> Auditors reject unedited stubs. See `docs/governance-templates.md` for guidance.
 
 # Periodic Review of Internal Controls
 
@@ -25,6 +25,23 @@ review_cadence_days: 90
 
 **Evidence type:** `periodic_review` · **Cadence:** every 90 days (quarterly). The portal flags this evidence as `expired` after 365 days — but a 90-day cadence is the practical minimum.
 
+## Uploading this artefact
+
+- **File path:** `compliance/governance/periodic-review.md` (auto-regenerated by the workflow each quarter; commit it as-is then fill the operator sections)
+- **Upload trigger:** automatic — on the PR-merge push to `develop`, `compliance-evidence.yml` uploads this file as `periodic_review` evidence.
+- **Verify after merge:** open `/projects/<slug>/compliance`. **SOC 2 CC4.1** AND **ISO 27001 A.12.1** should flip MISSING → COVERED within ~2 minutes.
+- **Refresh cadence:** quarterly (every 90 days). The portal's `freshnessDays: 365` window means a stale review eventually flips to `expired`; the workflow's quarterly cron keeps you well inside that window.
+
+## Framework checklist — SOC 2 CC4.1 + ISO 27001 A.12.1
+
+The 60% of this doc that the operator must fill (auto-generated sections at the top cover the other 40%):
+
+- [ ] §1 Review period: dates + reviewer + approver (dual-actor when `risk_tier=medium`+)
+- [ ] §3 Control-effectiveness review: a sentence per gate (typescript / sast / dep-audit / e2e / build) — *worked / didn't work / why*
+- [ ] §4 Findings: each material finding → severity → owner → due date
+- [ ] §5 Follow-up actions: items carried over from last quarter, with status
+- [ ] §6 Sign-off: reviewer + approver names + dates (signatures by commit, not by image)
+
 ## 1. Review period
 
 - **From:** REPLACE — YYYY-MM-DD

package/sdlc/files/_common/governance/ropa.md.template

@@ -7,10 +7,10 @@ review_cadence_days: 365
 processing_activities: []
 ---
 
-> ⚠️ **STARTER TEMPLATE — REPLACE BEFORE GOING TO PRODUCTION.**
-> This file was auto-installed by `devaudit install` as a starting point.
-> It does **not** describe your project's actual processing activities. Edit and commit.
-> Auditors will reject unedited stubs. See `docs/governance-templates.md` for guidance.
+> ⚠️ **STARTER TEMPLATE — REPLACE BEFORE COMMITTING.**
+> Installed on demand via `devaudit bootstrap-governance` (v0.1.36+) as a starting point.
+> It does **not** describe your project's actual processing activities. Edit before committing.
+> Auditors reject unedited stubs. See `docs/governance-templates.md` for guidance.
 
 # Records of Processing Activities
 
@@ -18,6 +18,24 @@ processing_activities: []
 
 **Evidence type:** `ropa` · **Cadence:** refresh every 365 days (portal flags as `expired` after)
 
+## Uploading this artefact
+
+- **File path:** `compliance/governance/ropa.md`
+- **Upload trigger:** automatic — on every push to `develop` that touches `compliance/**`, the `compliance-evidence.yml` workflow uploads this file as `ropa` evidence via the `upload_governance` helper.
+- **Verify after merge:** open `/projects/<slug>/compliance` on the DevAudit portal. The **GDPR Art. 30** clause should flip MISSING → COVERED within ~2 minutes.
+- **Refresh cadence:** annually (365 days). The portal flags the clause as `expired` once the most-recent ropa upload is older than that window.
+
+## Framework checklist — GDPR Art. 30
+
+Before committing, confirm each item below — if any is unchecked, the document is not yet audit-ready:
+
+- [ ] Controller's legal name + contact + DPO listed
+- [ ] At least one processing activity documented (no placeholder "Activity 1" row left in)
+- [ ] Each activity carries: purpose, lawful basis (Art. 6), data subject categories, data categories, recipients, retention, transfers
+- [ ] Special categories (Art. 9) flagged where applicable
+- [ ] Cross-border transfer mechanism named where data leaves the EEA
+- [ ] `last_reviewed_at` frontmatter matches the actual review date
+
 ## Controller
 
 - **Legal name:** REPLACE

package/sdlc/files/_common/skills/e2e-test-engineer/SKILL.md

@@ -220,6 +220,75 @@ Each filed issue needs:
 - **Evidence** — link or path to the failing test, error output, screenshot, trace.
 - **Link back** to the originating issue/PR.
 - **Severity** — your honest call: blocker, major, minor. Don't inflate.
+- **`### Framework attribution`** section — the clauses this defect closes when its incident report lands. Always lists `ISO29119.3.5.4` as baseline; additional clauses depending on classification below.
+
+#### Framework classification + the `incident` label
+
+Every defect filed from Phase 6 becomes `incident_report` evidence when (a) the issue is labelled `incident` and (b) the issue is closed. The flow: closed-with-label → `incident-export.yml` exports the body to `compliance/governance/incident-report-<N>.md` → `compliance-evidence.yml` uploads as `incident_report` evidence → portal flips the attributed clauses MISSING → COVERED.
+
+Classify the defect against this table when filing — the canonical version lives at `governance-doc-author/references/incident-classification.md`, mirrored here for the e2e workflow:
+
+| Defect characteristic | Frameworks/clauses attributed |
+|---|---|
+| **Any test failure / defect** (baseline — always) | `ISO29119.3.5.4` Test incident report |
+| **Ops impact** (downtime, persistent errors, perf regression, data corruption) | + `SOC2.CC7.2` System monitoring and incident response |
+| **Security vulnerability** (auth bypass, injection, data exposure) | + `SOC2.CC7.2` + relevant ISO 27001 controls |
+| **Personal data exposed / lost / mishandled** | + `GDPR.Art-33` (always — 72h supervisory notification) + `GDPR.Art-34` (when data subjects need notification) |
+| **AI/ML failure** (model hallucination, biased output, oversight bypass) | + relevant EU AI Act articles (`Art-9` risk, `Art-14` human oversight, `Art-15` accuracy/robustness) |
+
+**Baseline rule:** the first row is **mandatory**. Even a defect with no specific framework impact STILL produces a valid incident_report attributed to `ISO29119.3.5.4`. Never silently drop the artefact because "it's just a bug".
+
+**Apply the `incident` label at filing time** for defects that warrant incident_report evidence — don't wait for the operator to add it later. Confirm with the operator first (per the **Confirm before destructive or public actions** principle).
+
+If the `incident` label doesn't exist yet on the repo, create it idempotently:
+
+```bash
+gh label list --json name --jq '.[].name' | grep -qx incident || \
+  gh label create incident --color 'B60205' --description 'Operational, test, or compliance incident; close to auto-archive as portal evidence'
+```
+
+Then file with `--label incident,<existing-labels>`.
+
+#### Issue body template
+
+Embed the `### Framework attribution` section near the end of every defect issue body so the auto-export PR (after close) inherits the attribution:
+
+```markdown
+### Framework attribution
+
+This defect, once closed with the `incident` label, will be auto-exported as `incident_report` evidence and attribute to:
+
+- [x] `ISO29119.3.5.4` (baseline — every incident_report)
+- [ ] `SOC2.CC7.2` — ops impact: <REPLACE — yes/no, with one-line rationale>
+- [ ] `GDPR.Art-33` — personal data scope: <REPLACE — yes/no>
+- [ ] `GDPR.Art-34` — data-subject notification required: <REPLACE — yes/no>
+- [ ] `EUAIA.Art-9 / Art-14 / Art-15` — AI failure: <REPLACE — yes/no, which article(s)>
+
+Once closed, the `incident-export.yml` workflow exports this issue's body to `compliance/governance/incident-report-<N>.md`, auto-files a PR with the GDPR triage + sign-off sections to fill in. Merge that PR → `compliance-evidence.yml` uploads as `incident_report`.
+```
+
+Pre-tick boxes you're confident about. Leave the operator-judgement ones (GDPR triage, AI-failure classification) for the operator to confirm in the export PR.
+
+#### Worked examples
+
+**Example 1 — Non-PII, non-security defect.** A unit-conversion bug rounds metric prices incorrectly. Found by failing e2e. No data exposure, no service impact beyond cosmetic.
+
+- Apply `incident` label: **yes** (every defect produces an incident_report on close).
+- Pre-ticked attribution: `ISO29119.3.5.4` only.
+- Operator confirms in the export PR: no SOC 2 / GDPR / EU AI Act ticks added.
+- Result: valid incident_report closing the baseline clause. Don't pad with false ticks.
+
+**Example 2 — PII exposure via misconfigured RLS.** Users see other users' applications. Found via e2e regression. ~3,000 users affected over 6 hours.
+
+- Apply `incident` label: **yes**.
+- Pre-ticked attribution: `ISO29119.3.5.4` + `SOC2.CC7.2` + `GDPR.Art-33`.
+- Leave `GDPR.Art-34` unticked — high-risk threshold needs operator + DPO judgement.
+- Severity: blocker.
+- The export PR will surface the GDPR triage section for the operator + DPO to fill in (data-subject count, notification method, 72h-window timestamp).
+
+#### Skipping the issue path — direct incident report
+
+When the incident wasn't found by an e2e run (e.g. an ops event surfaced externally, or a retrospective documentation of an event the team handled outside the tracker), file directly using the `governance-doc-author` skill against `compliance/governance/incident-report.md.template`. Same classification table applies; the doc gets committed, `compliance-evidence.yml` auto-uploads it.
 
 Show the user the full set of issues you're about to file. Get confirmation. Then file them.
 

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

@@ -0,0 +1,148 @@
+---
+name: governance-doc-author
+description: Author or refresh one of the project's governance documents — RoPA (GDPR Art. 30), DPIA (GDPR Art. 35), AI use disclosure (EU AI Act Art. 13), Periodic Security Review Schedule (ISO 27001 A.12.1 / SOC 2 CC4.1), or the project-level incident-report template. Drives source-data gathering, framework-clause attribution, content authoring against the existing starter template, and the commit + upload + portal-verification loop. Use when the user wants to "create / refresh the RoPA", "write a DPIA", "update the AI disclosure", "set up the periodic review schedule", or generally "I need to make our <governance doc> audit-ready". Use also when the framework-coverage matrix on the portal shows GDPR.Art-30 / GDPR.Art-35 / EUAIA.Art-13 / SOC2.CC4.1 / ISO27001.A.12.1 as MISSING and the operator asks how to close them. Do NOT use for incident response itself (that's the e2e-test-engineer + incident-export.yml pipeline), or for portal upload mechanics of evidence the CI already auto-uploads (test_report, e2e_result, sast_report, audit_log, screenshot).
+---
+
+# Governance Doc Author
+
+Author or refresh a single governance document so it correctly closes the framework clauses it's meant to satisfy. Five document classes covered:
+
+| Document | File | Closes |
+|---|---|---|
+| **RoPA** | `compliance/governance/ropa.md` | `GDPR.Art-30` |
+| **DPIA** | `compliance/governance/dpia.md` (or `dpia-<reqid>.md`) | `GDPR.Art-35` |
+| **AI Use Disclosure** | `compliance/governance/ai-disclosure.md` | `EUAIA.Art-13` |
+| **Periodic Security Review Schedule** | `SDLC/Periodic_Security_Review_Schedule.md` *(Tier 2, uploaded as `compliance_document` via the portal Upload form)* | `ISO27001.A.12.1` (the schedule itself; the quarterly runs close `ISO27001.A.12.1` + `SOC2.CC4.1` via `periodic_review` evidence — see Phase 6) |
+| **Incident Report (project-level template)** | `compliance/governance/incident-report.md` | `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.
+
+## 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 → CI auto-upload → 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`.
+- Framework registry changes — clause definitions live in META-COMPLY (`lib/config/frameworks/`) and are not authored here.
+
+## The workflow
+
+Six phases. Phase 0 is a routing step; phases 1–5 are per-document.
+
+### Phase 0 — Route
+
+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)
+
+When the trigger is *"GDPR.Art-30 is MISSING on the matrix, what do I upload?"* and similar — route to the matching doc above.
+
+### Phase 1 — Confirm the starter exists
+
+1. Check whether the starter template is on disk at the expected path. If yes, skip to Phase 2.
+2. If absent, tell the operator the v0.1.36+ install no longer auto-seeds these — the `devaudit bootstrap-governance` command copies them on demand. Offer to run it (with operator confirmation per the **Confirm before destructive or public actions** principle).
+3. Re-check the path. If still missing, halt with a clear error pointing at the starter file in the installer.
+
+### Phase 2 — Gather source data
+
+Each doc class has different inputs. Read what's needed; don't ask the operator for what you can derive from the codebase.
+
+- **ROPA**
+  - 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).
+
+- **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).
+  - Per-REQ DPIA → read `compliance/plans/REQ-XXX/implementation-plan.md` §4 (data protection) for the specific REQ being assessed.
+
+- **AI_DISCLOSURE**
+  - Grep `git log --grep "Co-Authored-By: Claude\|Co-Authored-By: GPT"` for model usage signals.
+  - Grep the codebase for AI SDK imports (`@anthropic-ai/sdk`, `openai`, etc.) and prompt strings.
+  - Cross-reference each per-REQ implementation plan's §5 (AI / model considerations).
+  - Ask the operator about human-oversight paths if not documented in the implementation plans.
+
+- **REVIEW_SCHEDULE**
+  - Read `sdlc-config.json` for `risk_tier` — drives the cadence (low = annual + ad-hoc; medium = quarterly; high = monthly).
+  - Read `.github/workflows/periodic-review.yml` to confirm the cron is wired (or note it as a follow-up if not).
+  - Ask the operator which control areas to schedule (default: access control / secure SDLC / SAST / dep-audit / E2E / change management / monitoring).
+
+- **INCIDENT_TEMPLATE**
+  - No source-data gathering — the project-level template is the form per-incident reports inherit. Ensure the latest [[incident-classification]] reference is up to date.
+
+### Phase 3 — Author against the starter
+
+1. Open the starter at the path Phase 1 confirmed.
+2. Replace every `REPLACE — …` marker with project-specific content. Use the Phase 2 source data; don't invent values.
+3. Tick the **Framework checklist** items in the starter as you go. If you can't tick one honestly, leave it unticked and surface the gap in the Phase 5 report — never tick falsely.
+4. Update the frontmatter (`last_reviewed_at`, `controller`, etc.) to today's date and the project's actual values.
+
+### Phase 4 — Verify framework attribution
+
+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) |
+
+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.
+
+### Phase 5 — Commit + verify
+
+1. Show the operator the diff. Confirm before committing (per the **Confirm before destructive or public actions** principle).
+2. Commit with a conventional-commit message: `compliance(governance): refresh <doc> for <reason>` — e.g. `compliance(governance): refresh ropa.md — annual review 2026-Q2`.
+3. Push to the current working branch. Surface the path: "next `git push` to `develop` → `compliance-evidence.yml` auto-uploads as `<evidence_type>`, closing `<framework_clause>` within ~2 minutes."
+4. Suggest the operator open `/projects/<slug>/compliance` on the portal post-merge to verify the clause flipped MISSING → COVERED.
+
+### Phase 6 — Special case: the Periodic Review Schedule vs the quarterly review itself
+
+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. |
+
+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`).
+
+## Filing follow-ups + handoff
+
+When Phase 5 commits successfully, append a short narrator update in the final report:
+
+- Doc(s) authored, paths committed, framework clauses closed.
+- Any framework checklist items left unticked → file each as a follow-up issue (with operator confirmation) OR list as known gaps in the final report.
+- For DPIA tied to a HIGH-risk REQ: cross-link back to the REQ's `implementation-plan.md` §4.
+
+## Principles
+
+**One doc per invocation.** Don't try to refresh RoPA + DPIA + AI disclosure in one run. They have different cadences and different source data; batching them produces sloppy output.
+
+**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.
+
+**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.
+
+**Ambiguity is a question, not a guess.** Same as e2e-test-engineer.
+
+## References
+
+- `references/incident-classification.md` — the conditional-attribution decision tree for incident_report evidence (mirrors the table in `e2e-test-engineer` Phase 6 Filing Defects).
+- Starter templates: `sdlc/files/_common/governance/{ropa,dpia,ai-disclosure,periodic-review,incident-report}.md.template`.
+- Framework registries (META-COMPLY): `lib/config/frameworks/{gdpr,eu-ai-act,iso-27001,soc-2,iso-29119}.ts`.
+- Related skills: `sdlc-implementer` (per-REQ implementation plans), `e2e-test-engineer` (incident reports from defects).