fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

chore(work): decompose compliance-docs-scaffolds epic

Browse Source 
Generated 1 epic + 6 stories under docs/work/epics/ from the approved
PRD docs/work/prds/compliance-docs-scaffolds.prd.md. Stories cover
landing + refreshing operator-checklist.md, the seven fill-in policy
templates, the pre-launch compliance checklist, the compliance-overview
hub, and doc wiring (CLAUDE.md, README, glossary). Final epic of
ADR-025. Ready for `pnpm work dispatch --execute`.
This commit is contained in:
Danijel Martinek
2026-05-20 13:58:24 +02:00
parent ee4af9bb96
commit 96a8554871
8 changed files with 417 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
docs/work/_system/_state.json
View File

@@ -1,5 +1,5 @@
{
"updated_at": "2026-05-20T11:49:45.039Z",
"updated_at": "2026-05-20T11:58:25.634Z",
"epics": {
"binder-wrap-helper": {
"status": "done",
@@ -142,6 +142,79 @@
}
}
},
"compliance-docs-scaffolds": {
"status": "in-progress",
"title": "Compliance docs scaffolds — Epic D of ADR-025",
"prd": "docs/work/prds/compliance-docs-scaffolds.prd.md",
"stories": {
"01-land-operator-checklist": {
"status": "in-progress",
"title": "Land operator-checklist.md verbatim",
"ac_total": 1,
"ac_completed": 0,
"depends_on": [],
"blocks": [
"02-refresh-operator-checklist"
]
},
"02-refresh-operator-checklist": {
"status": "todo",
"title": "Refresh operator-checklist.md for ADR-024 and ADR-025",
"ac_total": 1,
"ac_completed": 0,
"depends_on": [
"01-land-operator-checklist"
],
"blocks": []
},
"03-policy-templates": {
"status": "todo",
"title": "Write seven policy templates in docs/compliance/templates/",
"ac_total": 2,
"ac_completed": 0,
"depends_on": [],
"blocks": [
"04-pre-launch-compliance-checklist",
"05-compliance-overview"
]
},
"04-pre-launch-compliance-checklist": {
"status": "todo",
"title": "Write pre-launch compliance checklist",
"ac_total": 1,
"ac_completed": 0,
"depends_on": [
"03-policy-templates"
],
"blocks": [
"05-compliance-overview"
]
},
"05-compliance-overview": {
"status": "todo",
"title": "Write compliance-overview.md hub",
"ac_total": 1,
"ac_completed": 0,
"depends_on": [
"03-policy-templates",
"04-pre-launch-compliance-checklist"
],
"blocks": [
"06-doc-wiring"
]
},
"06-doc-wiring": {
"status": "todo",
"title": "Wire compliance docs into CLAUDE.md, README, and glossary",
"ac_total": 2,
"ac_completed": 0,
"depends_on": [
"05-compliance-overview"
],
"blocks": []
}
}
},
"compliance-manifests-pii-retention-subprocessors": {
"status": "done",
"title": "Declarative compliance manifests (PII + retention + sub-processors) — Epic A of ADR-025",
@@ -685,7 +758,52 @@
}
}
},
"ready": [],
"blocked": [],
"ready": [
{
"epic": "compliance-docs-scaffolds",
"story": "01-land-operator-checklist",
"title": "Land operator-checklist.md verbatim"
},
{
"epic": "compliance-docs-scaffolds",
"story": "03-policy-templates",
"title": "Write seven policy templates in docs/compliance/templates/"
}
],
"blocked": [
{
"epic": "compliance-docs-scaffolds",
"story": "02-refresh-operator-checklist",
"title": "Refresh operator-checklist.md for ADR-024 and ADR-025",
"waiting_on": [
"compliance-docs-scaffolds/01-land-operator-checklist"
]
},
{
"epic": "compliance-docs-scaffolds",
"story": "04-pre-launch-compliance-checklist",
"title": "Write pre-launch compliance checklist",
"waiting_on": [
"compliance-docs-scaffolds/03-policy-templates"
]
},
{
"epic": "compliance-docs-scaffolds",
"story": "05-compliance-overview",
"title": "Write compliance-overview.md hub",
"waiting_on": [
"compliance-docs-scaffolds/03-policy-templates",
"compliance-docs-scaffolds/04-pre-launch-compliance-checklist"
]
},
{
"epic": "compliance-docs-scaffolds",
"story": "06-doc-wiring",
"title": "Wire compliance docs into CLAUDE.md, README, and glossary",
"waiting_on": [
"compliance-docs-scaffolds/05-compliance-overview"
]
}
],
"needs_prd_ship": []
}

40
docs/work/epics/compliance-docs-scaffolds/01-land-operator-checklist/_story.md Normal file
View File

@@ -0,0 +1,40 @@
---
id: 01-land-operator-checklist
epic: compliance-docs-scaffolds
title: Land operator-checklist.md verbatim
type: technical-story
status: in-progress
feature: ~
depends-on: []
blocks: [02-refresh-operator-checklist]
created: 2026-05-20T12:00:00Z
updated: 2026-05-20T11:58:25.281Z
---
## Goal
Track the existing untracked `docs/guides/operator-checklist.md` in git without altering its content. Establishes it as the baseline before the refresh story rewrites sections.
## Why
`docs/guides/operator-checklist.md` has been untracked since the ADR-022/023 work. The PRD (Q5) calls for landing it verbatim as a separate commit so the "what existed" diff is legible for review, distinct from the "what changed" diff that story 02 produces.
## Done when
- `git status` shows `docs/guides/operator-checklist.md` as tracked (no longer `??`).
- File content is identical to its untracked state — no edits.
- Commit type is `chore(docs)`.
- `pnpm lint && pnpm typecheck && pnpm test && pnpm conformance && pnpm fallow:audit` all pass.
## In scope
- Staging and committing `docs/guides/operator-checklist.md` verbatim.
## Out of scope
- Any content changes to the file (story 02).
- Any other files.
## Tasks
- [ ] Stage and commit `docs/guides/operator-checklist.md` verbatim as `chore(docs): track operator-checklist.md verbatim`; no content edits — the file is committed exactly as found in the working tree.

42
docs/work/epics/compliance-docs-scaffolds/02-refresh-operator-checklist/_story.md Normal file
View File

@@ -0,0 +1,42 @@
---
id: 02-refresh-operator-checklist
epic: compliance-docs-scaffolds
title: Refresh operator-checklist.md for ADR-024 and ADR-025
type: technical-story
status: todo
feature: ~
depends-on: [01-land-operator-checklist]
blocks: []
created: 2026-05-20T12:00:00Z
updated: 2026-05-20T11:58:25.281Z
---
## Goal
Add two new sections to `docs/guides/operator-checklist.md` covering ADR-024 (analytics backend wiring) and ADR-025 (compliance directory, drift gate, retention purge scheduling, and sub-processors file). Preserve all existing ADR-022/023 content.
## Why
The operator checklist predates ADR-024 (analytics) and ADR-025 (the compliance epics). A template operator following the checklist today would miss compliance directory setup, the drift CI gate, and the retention purge job — all of which require a deliberate operator action.
## Done when
- `docs/guides/operator-checklist.md` contains a section for ADR-024 operator actions: note that the analytics backend is consumer-chosen + consumer-wired, and that the operator should decide whether to wire a vendor via `/evaluate-library`.
- The file contains a section for ADR-025 operator actions: `compliance/*.yml` as committed audit evidence; compliance drift gate running in pre-commit + CI; retention purge job scheduling per `custom.retention`; `compliance/sub-processors.manual.yml` hand-authored for non-npm vendors.
- All existing ADR-022/023 content is preserved unchanged.
- Commit type is `docs(compliance)`.
- `pnpm lint && pnpm typecheck && pnpm test && pnpm conformance && pnpm fallow:audit` all pass.
## In scope
- Adding ADR-024 operator actions section to `docs/guides/operator-checklist.md`.
- Adding ADR-025 operator actions section to `docs/guides/operator-checklist.md`.
## Out of scope
- Rewriting or restructuring the existing ADR-022/023 sections.
- Any other files.
## Tasks
- [ ] Add ADR-024 (analytics backend is consumer-chosen; note `/evaluate-library` decision process) and ADR-025 (commit `compliance/*.yml` as audit evidence, verify compliance drift gate in pre-commit + CI, schedule retention purge job per `custom.retention`, hand-author `compliance/sub-processors.manual.yml` for non-npm vendors) operator action sections to `docs/guides/operator-checklist.md`, preserving all existing content; commit as `docs(compliance): refresh operator-checklist with ADR-024 and ADR-025 actions`.

51
docs/work/epics/compliance-docs-scaffolds/03-policy-templates/_story.md Normal file
View File

@@ -0,0 +1,51 @@
---
id: 03-policy-templates
epic: compliance-docs-scaffolds
title: Write seven policy templates in docs/compliance/templates/
type: user-story
status: todo
feature: ~
depends-on: []
blocks: [04-pre-launch-compliance-checklist, 05-compliance-overview]
created: 2026-05-20T12:00:00Z
updated: 2026-05-20T11:58:25.281Z
---
## Goal
Create `docs/compliance/templates/` and populate it with seven `*.template.md` files: two anchored templates (`incident-runbook`, `dsr-procedure`) cross-referencing real shipped features, and five skeleton templates (`backup-policy`, `password-policy`, `device-policy`, `onboarding`, `offboarding`) with "not code-enforced" banners. All templates use the `[FILL IN: <description>]` marker convention throughout.
## Why
A downstream consumer preparing for a DPA audit currently writes organizational policy documents from a blank page. These templates reduce that to copy-and-fill work. The anchored templates are substantive because the template ships the relevant code (DSR endpoints, audit channel, Sentry alerting, security headers, rate-limit) — they reference real ADR numbers and `pnpm` commands so the procedure matches the shipped system. The skeleton templates provide the document structure; the consumer supplies the organization-specific content.
## Done when
- `docs/compliance/templates/` directory exists with exactly 7 files: `incident-runbook.template.md`, `dsr-procedure.template.md`, `backup-policy.template.md`, `password-policy.template.md`, `device-policy.template.md`, `onboarding.template.md`, `offboarding.template.md`.
- Each template has YAML frontmatter with `status: template` and `playbook-section: <n>`.
- Anchored templates (`incident-runbook`, `dsr-procedure`) each reference at least one ADR number and one `pnpm` command or shipped interface/endpoint; each still contains `[FILL IN:]` markers for org-specific values (contacts, SLA targets, etc.).
- Skeleton templates all open with the "not code-enforced" banner; `password-policy.template.md`'s banner cites ADR-025's explicit deferral of MFA + password policy + lockout by ADR number.
- `grep -rn '\[FILL IN:' docs/compliance/templates/` returns hits in every template.
- Every relative Markdown link in the new files resolves to an existing file.
- `pnpm lint && pnpm typecheck && pnpm test && pnpm conformance && pnpm fallow:audit` all pass.
## In scope
- `docs/compliance/templates/incident-runbook.template.md` — breach detection → triage → containment → notification (GDPR Art. 33 72h / DPA 24h) → post-mortem; cross-references ADR-018 (audit channel), ADR-014 (Sentry alerting), Epic C (security-headers + rate-limit surfaces).
- `docs/compliance/templates/dsr-procedure.template.md` — DSR receipt → validation → fulfilment → recording; cross-references Epic B DSR endpoints (`/api/gdpr/*`), `core-dsr` interfaces, audit `CONSENT_*`/`RESTRICT` actions, `compliance/data-map.yml` (Epic A).
- `docs/compliance/templates/backup-policy.template.md` — skeleton with banner.
- `docs/compliance/templates/password-policy.template.md` — skeleton with banner; banner cites ADR-025 MFA/password/lockout deferral.
- `docs/compliance/templates/device-policy.template.md` — skeleton with banner.
- `docs/compliance/templates/onboarding.template.md` — skeleton with banner.
- `docs/compliance/templates/offboarding.template.md` — skeleton with banner.
## Out of scope
- Filling in org-specific values — the `[FILL IN:]` markers are intentionally left for the consumer.
- Any changes to existing compliance guides (`dsr.md`, `consent.md`, etc.).
- A CI gate enforcing no `[FILL IN:]` in `compliance/` (deferred).
## Tasks
- [ ] Create `docs/compliance/templates/` and write `incident-runbook.template.md` + `dsr-procedure.template.md`: both anchored with YAML frontmatter (`status: template`, `playbook-section`), procedure skeleton cross-referencing real ADRs/commands/interfaces/endpoints, and `[FILL IN:]` markers for org-specific values; commit as `docs(compliance): add anchored policy templates (incident-runbook, dsr-procedure)`.
- [ ] Write `backup-policy.template.md`, `password-policy.template.md`, `device-policy.template.md`, `onboarding.template.md`, and `offboarding.template.md` in `docs/compliance/templates/`: each with YAML frontmatter, the "not code-enforced" banner (password-policy's banner cites ADR-025 MFA/lockout deferral by number), and `[FILL IN:]` markers throughout; commit as `docs(compliance): add skeleton policy templates (backup, password, device, onboarding, offboarding)`.

46
docs/work/epics/compliance-docs-scaffolds/04-pre-launch-compliance-checklist/_story.md Normal file
View File

@@ -0,0 +1,46 @@
---
id: 04-pre-launch-compliance-checklist
epic: compliance-docs-scaffolds
title: Write pre-launch compliance checklist
type: user-story
status: todo
feature: ~
depends-on: [03-policy-templates]
blocks: [05-compliance-overview]
created: 2026-05-20T12:00:00Z
updated: 2026-05-20T11:58:25.281Z
---
## Goal
Create `docs/guides/pre-launch-compliance-checklist.md` as a two-column Markdown table mapping every playbook obligation (drawn from playbook §19 + the 22 sections) to its coverage status: "Shipped by template" (with verification command), "Consumer responsibility", or "Infra responsibility". The table operationalizes ADR-025's three-way coverage split into a checkable launch gate.
## Why
A launching team currently has no single answer to "are we compliant enough to ship to a paying customer?" The playbook §19 is generic; nothing maps it to this template's concrete features (`pnpm compliance:emit-all --check`, `core-audit`, DSR endpoints) or explicitly flags which obligations are on the consumer vs the infra vs already handled. This checklist provides that clarity and produces verification evidence on demand for compliance officers.
## Done when
- `docs/guides/pre-launch-compliance-checklist.md` exists and contains a two-column table.
- Rows are grouped by playbook section (Infrastructure, Data, Application, Secrets, Sub-Processors, Logging, Breach, DSR, Backup, SDLC, Workforce, Legal, Documentation).
- Every "Shipped by template" row names a runnable verification command (e.g. `pnpm compliance:emit-all --check`, `pnpm conformance`, securityheaders.com scan).
- Every "Consumer responsibility" and "Infra responsibility" row is explicitly labelled as such.
- The file links to `docs/guides/compliance-overview.md` and to relevant templates in `docs/compliance/templates/`.
- All 22 playbook sections are represented.
- Every relative Markdown link resolves to an existing file.
- Commit type is `docs(compliance)`.
- `pnpm lint && pnpm typecheck && pnpm test && pnpm conformance && pnpm fallow:audit` all pass.
## In scope
- `docs/guides/pre-launch-compliance-checklist.md` — the two-column launch gate table.
- Links outward to `compliance-overview.md` and `docs/compliance/templates/*.template.md`.
## Out of scope
- Machine-enforceable CI gate for this checklist (deferred).
- Changes to any existing guide files.
## Tasks
- [ ] Write `docs/guides/pre-launch-compliance-checklist.md` as a two-column table covering all 22 playbook sections (Infrastructure, Data, Application, Secrets, Sub-Processors, Logging, Breach, DSR, Backup, SDLC, Workforce, Legal, Documentation), labelling each obligation as "Shipped by template" (with inline verification command), "Consumer responsibility", or "Infra responsibility", and linking to `compliance-overview.md` + relevant templates; commit as `docs(compliance): add pre-launch compliance checklist`.

44
docs/work/epics/compliance-docs-scaffolds/05-compliance-overview/_story.md Normal file
View File

@@ -0,0 +1,44 @@
---
id: 05-compliance-overview
epic: compliance-docs-scaffolds
title: Write compliance-overview.md hub
type: user-story
status: todo
feature: ~
depends-on: [03-policy-templates, 04-pre-launch-compliance-checklist]
blocks: [06-doc-wiring]
created: 2026-05-20T12:00:00Z
updated: 2026-05-20T11:58:25.281Z
---
## Goal
Create `docs/guides/compliance-overview.md` as the single navigational entry point for compliance in this template. It maps each of the 22 playbook sections to the ADR / guide / template / epic that covers it, names ADR-025's deferrals and consumer/infra-scope items explicitly, and links outward to every compliance guide, ADR, and template.
## Why
After four epics, compliance documentation sprawls across `docs/compliance/`, `docs/guides/` (8+ files), `docs/decisions/` (6 ADRs), and root `compliance/`. An auditor, new engineer, or AI agent asked "is feature X compliant?" has no entry point and must reverse-engineer the structure from grep. ADR-025 designated this hub as the solution; it must be written last so it can link to finished templates + checklist.
## Done when
- `docs/guides/compliance-overview.md` exists.
- The file maps all 22 playbook sections; every row points at a real ADR, guide path, template path, or epic that covers it.
- A closing summary restates ADR-025's deferrals (RBAC, MFA, breach-detection, GDPR Art. 22) and the consumer/infra-scope items (EU region, TLS, MDM, legal instruments).
- The file links one-directionally to `docs/guides/pre-launch-compliance-checklist.md`, `docs/compliance/templates/*.template.md`, all relevant ADRs (`docs/decisions/`), and all relevant guides.
- Every relative Markdown link resolves to an existing file.
- Commit type is `docs(compliance)`.
- `pnpm lint && pnpm typecheck && pnpm test && pnpm conformance && pnpm fallow:audit` all pass.
## In scope
- `docs/guides/compliance-overview.md` — the 22-section hub with outbound links and deferrals summary.
## Out of scope
- Editing any existing ADR, guide, or template (one-directional only).
- Duplicating ADR-025's rationale — the overview is the navigational map, not the decision record.
- Replacing `docs/compliance/README.md` as the hub — README stays scoped to generator schema reference.
## Tasks
- [ ] Write `docs/guides/compliance-overview.md` mapping all 22 playbook sections to their covering ADR/guide/template/epic, with a closing deferrals summary (RBAC, MFA, breach-detection, GDPR Art. 22, EU region, TLS, MDM, legal instruments) and outbound links to all referenced files; verify every relative link resolves; commit as `docs(compliance): add compliance-overview hub`.

46
docs/work/epics/compliance-docs-scaffolds/06-doc-wiring/_story.md Normal file
View File

@@ -0,0 +1,46 @@
---
id: 06-doc-wiring
epic: compliance-docs-scaffolds
title: Wire compliance docs into CLAUDE.md, README, and glossary
type: technical-story
status: todo
feature: ~
depends-on: [05-compliance-overview]
blocks: []
created: 2026-05-20T12:00:00Z
updated: 2026-05-20T11:58:25.281Z
---
## Goal
Complete the one-directional wiring of Epic D's new documents into the three shared navigation surfaces: add a "Policy templates" section to `docs/compliance/README.md`, add four new glossary entries to `docs/glossary.md`, and add a `compliance-overview.md` pointer to CLAUDE.md's "Read First" section.
## Why
Without these changes, `compliance-overview.md` is orphaned from the primary AI navigation entry point (CLAUDE.md), the policy templates have no discovery path in `docs/compliance/`, and the `[FILL IN:]` marker convention has no canonical glossary definition. The PRD specifies these as the final wiring step, after all new documents exist so links resolve.
## Done when
- `docs/compliance/README.md` has a "Policy templates" section that explains: the `docs/compliance/templates/` directory, the copy-to-`compliance/` workflow, the `[FILL IN:]` convention, and the `grep -rn '\[FILL IN:' compliance/` verification one-liner.
- `docs/glossary.md` has four new entries: `pre-launch compliance checklist`, `compliance overview`, `fill-in template`, `[FILL IN:] marker`.
- CLAUDE.md "Read First" lists `compliance-overview.md` (with path and one-line description matching the existing entries' style).
- No existing content in any of the three files is removed or modified.
- Every relative Markdown link added resolves to an existing file.
- `pnpm lint && pnpm typecheck && pnpm test && pnpm conformance && pnpm fallow:audit` all pass.
## In scope
- `docs/compliance/README.md` — add "Policy templates" section.
- `docs/glossary.md` — add 4 entries.
- `CLAUDE.md` — add `compliance-overview.md` pointer to "Read First".
## Out of scope
- Any changes to `docs/guides/compliance-overview.md` or the templates (they are complete by the time this story runs).
- Any changes to the existing compliance guides (`dsr.md`, `consent.md`, etc.).
- Broadening `docs/compliance/README.md` beyond the generator schema + policy template scope.
## Tasks
- [ ] Add a "Policy templates" section to `docs/compliance/README.md` (explaining the `docs/compliance/templates/` directory, copy-to-`compliance/` workflow, `[FILL IN:]` convention, and the `grep -rn '\[FILL IN:' compliance/` one-liner) and add four glossary entries (`pre-launch compliance checklist`, `compliance overview`, `fill-in template`, `[FILL IN:] marker`) to `docs/glossary.md`; commit as `docs(compliance): document policy template convention in README and glossary`.
- [ ] Add `docs/guides/compliance-overview.md` to the "Read First" section of `CLAUDE.md` with a one-line description matching the existing entries' style; commit as `docs(core): add compliance-overview.md to CLAUDE.md Read First`.

27
docs/work/epics/compliance-docs-scaffolds/_epic.md Normal file
View File

@@ -0,0 +1,27 @@
---
id: compliance-docs-scaffolds
prd: docs/work/prds/compliance-docs-scaffolds.prd.md
title: Compliance docs scaffolds — Epic D of ADR-025
type: epic
status: in-progress
features: []
created: 2026-05-20T12:00:00Z
updated: 2026-05-20T11:58:25.281Z
---
## Goal
Ship the compliance documentation layer: seven copy-and-fill policy templates, a template-tailored pre-launch compliance checklist, a single `compliance-overview.md` hub mapping the 22 playbook sections, and a refreshed `operator-checklist.md`. Pure documentation — no code, no manifests, no conformance rules.
## Why
Epics A–C shipped the compliance machinery (PII manifests + retention + sub-processor generators, DSR + consent + cookie banner, security headers + rate-limit + SBOM). Epic D fills three remaining documentation gaps: no human-authored policy artifacts, no single launch gate, and no compliance map. A downstream consumer currently writes these from a blank page. ADR-025 settled the strategy; this epic is the implementation.
## Stories
- [ ] [01 — Land operator-checklist.md verbatim](01-land-operator-checklist/_story.md)
- [ ] [02 — Refresh operator-checklist.md for ADR-024 and ADR-025](02-refresh-operator-checklist/_story.md)
- [ ] [03 — Write seven policy templates](03-policy-templates/_story.md)
- [ ] [04 — Write pre-launch compliance checklist](04-pre-launch-compliance-checklist/_story.md)
- [ ] [05 — Write compliance-overview.md hub](05-compliance-overview/_story.md)
- [ ] [06 — Wire compliance docs into CLAUDE.md, README, and glossary](06-doc-wiring/_story.md)