feat(playbook): Implementation Playbooks — the Berater renderer ("wie komme ich dort hin?")
Roadmap item 4. After WHAT applies / WHAT is missing / WHICH first, the GF asks HOW. The Implementation Playbook renders, for one capability, the full journey — why / which regulations it closes / tools / process / evidence / controls — and chains the Optimization Roadmap into per-measure playbooks. Another renderer over the same Capability spine (ADR-003/004), not a new engine: ~95% of the data already exists, it just needs a different rendering. - compliance/playbook/: build_playbook() + playbooks_for_plan() (chains optimization -> playbook, acyclic; reuses leverage for "closes which regulations"). Capabilities without curated content render as honest status:missing stubs — the content-owed signal. - knowledge/implementation_playbooks/: curated knowledge layer (Reasoning Knowledge Acquisition), two deep expert drafts (SBOM, CVD/PSIRT, status draft, expert-draft-not-normative) + README. The bottleneck is now CONTENT, not software; Playbook (own knowledge) != regulatory domain. - ADR-004: Implementation Playbooks = renderer + knowledge layer; content is the bottleneck. - reference suite: "Implementation Playbook" section renders the SBOM journey + Roadmap->Playbook table (high-leverage caps flagged "fehlt (Inhalt)" — content backlog, highest leverage first). - refactor: extracted markdown helpers to reference_scenarios/_helpers.py to keep generate.py under the 500-LOC budget. 9 playbook tests (40 with optimization+transition+company), mypy --strict clean, check-loc 0. Product code with no app caller + knowledge/ADR/reference = non-runtime -> no deploy (ADR-001). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Benjamin Admin
@@ -39,65 +39,19 @@ from compliance.transition_reasoning import (
|
||||
regulatory_convergence,
|
||||
)
|
||||
from compliance.optimization import roadmap_from_delta, select_within_budget
|
||||
from compliance.playbook import playbooks_for_plan
|
||||
import os
|
||||
import yaml
|
||||
|
||||
Row = Tuple[str, str, str]
|
||||
OUT: List[str] = []
|
||||
ROLLUP: List[str] = []
|
||||
|
||||
|
||||
def w(s: str = "") -> None:
|
||||
OUT.append(s)
|
||||
|
||||
|
||||
def coverage_table(rows: List[Row]) -> None:
|
||||
w("**Architecture Coverage**")
|
||||
w("")
|
||||
w("| Layer | Status | Hinweis |")
|
||||
w("|---|---|---|")
|
||||
for layer, status, note in rows:
|
||||
w("| %s | **%s** | %s |" % (layer, status, note))
|
||||
ROLLUP.append(status)
|
||||
w("")
|
||||
|
||||
|
||||
def reg_map_block(rmap) -> None:
|
||||
w("**Expected Regulatory Map**")
|
||||
w("")
|
||||
w("> " + rmap.executive_summary)
|
||||
w("")
|
||||
for v in rmap.applicable_regulations:
|
||||
obs = ", ".join(o.obligation_id for o in v.obligations) or v.obligations_note
|
||||
w("- **%s** (%s) — Pflichten: %s" % (v.regulation_id, v.name, obs))
|
||||
for u in rmap.uncertain_regulations:
|
||||
w("- _unsicher_ %s — fehlt: %s" % (u.regulation_id, ", ".join(u.missing_facts) or "-"))
|
||||
for ov in rmap.overlaps:
|
||||
w("- Overlap %s: %s" % (ov.overlap_group_id, ", ".join(ov.shared_obligations)))
|
||||
for ev, ids in rmap.shared_evidence.items():
|
||||
w("- 1 Nachweis `%s` => %d Pflichten" % (ev, len(ids)))
|
||||
w("")
|
||||
|
||||
|
||||
def unsupported_block(rmap) -> None:
|
||||
w("**Expected Unsupported Domains**")
|
||||
w("")
|
||||
if not rmap.unsupported_domains:
|
||||
w("- keine — alle getriggerten Domaenen sind im Korpus")
|
||||
for d in rmap.unsupported_domains:
|
||||
w("- `%s` (Trigger: %s) -> %s" % (d.domain, d.trigger, d.note))
|
||||
w("")
|
||||
|
||||
from _helpers import ( # noqa: E402 (script-dir module; keeps generate.py under the LOC budget)
|
||||
OUT, ROLLUP, Row, w, coverage_table, reg_map_block, unsupported_block, interp_status,
|
||||
)
|
||||
|
||||
ISO_MAP = {"ISO27001": CapabilityMappingEntry(
|
||||
capability_ids=["cap_incident_response", "cap_supplier_management", "cap_asset_management"],
|
||||
confidence=Confidence.MEDIUM)}
|
||||
|
||||
|
||||
def interp_status(verdict_value: str) -> str:
|
||||
return "PARTIAL" if verdict_value in ("uncertain", "unsupported") else "PASS"
|
||||
|
||||
|
||||
w("# Reference Scenario Suite v1")
|
||||
w("")
|
||||
w("> **Kein Doku-Artefakt — die erste Ground Truth / Living Reference Suite.** Erzeugt aus den "
|
||||
@@ -442,6 +396,48 @@ coverage_table([
|
||||
("Budget-Priorisierung", "PASS", "Top-5 → %.0f%% der identifizierten Anforderungen" % (_bud.coverage_ratio * 100)),
|
||||
])
|
||||
|
||||
# ── Implementation Playbook — Berater-Renderer (wie komme ich dort hin?) ───
|
||||
w("## Implementation Playbook — wie komme ich dort hin? (Berater-Renderer)")
|
||||
w("")
|
||||
w('_Nach „was fehlt?" (Delta) und „womit anfangen?" (Hebel) die nächste Ebene: **wie umsetzen?** Pro Maßnahme eine komplette Reise aus kuratiertem Wissen + Hebel + (injizierten) Execution-Links. Inhalt ist der Engpass, nicht die Software._')
|
||||
w("")
|
||||
_pb_dir = os.path.join(os.path.dirname(__file__), "..", "knowledge", "implementation_playbooks")
|
||||
_pb_kb = {}
|
||||
for _pf in sorted(os.listdir(_pb_dir)):
|
||||
if _pf.endswith(".yaml"):
|
||||
with open(os.path.join(_pb_dir, _pf), encoding="utf-8") as _h:
|
||||
_pd = yaml.safe_load(_h)
|
||||
_pb_kb[_pd["capability_id"]] = _pd
|
||||
_pbs = playbooks_for_plan(_opt, _pb_kb) # chain Roadmap -> Playbook over the SAME delta
|
||||
_have = [p for p in _pbs if p.status != "missing"]
|
||||
_miss = [p for p in _pbs if p.status == "missing"]
|
||||
w("**Reise pro Maßnahme (aus der Roadmap):** %d von %d Maßnahmen haben ein Playbook; %d brauchen noch Inhalt (Knowledge Acquisition)." % (len(_have), len(_pbs), len(_miss)))
|
||||
w("")
|
||||
_show = next((p for p in _pbs if p.capability_id == "sbom_creation"), None)
|
||||
if _show:
|
||||
w("**Beispielreise — `%s`** _(%s, schließt %s)_" % (_show.capability_id, _show.status, "+".join(_show.closes_regulations) or "—"))
|
||||
w("> **Warum?** %s" % _show.why.strip())
|
||||
w("- **Tools:** %s" % ", ".join(_show.tools))
|
||||
w("- **Prozess:** %s" % " → ".join(s.title for s in _show.process_steps))
|
||||
w("- **Nachweise:** %s" % ", ".join(_show.expected_evidence))
|
||||
w("- **Wie andere es tun:** %s" % _show.how_others_do_it.strip())
|
||||
w("")
|
||||
w("**Roadmap → Implementation (Top-Maßnahmen nach Hebel):**")
|
||||
w("")
|
||||
w("| Maßnahme | Hebel | schließt | Playbook |")
|
||||
w("|---|---|---|---|")
|
||||
for _p in _pbs[:6]:
|
||||
w("| `%s` | %d | %s | %s |" % (_p.capability_id, _p.leverage, "+".join(_p.closes_regulations) or "—",
|
||||
("✓ " + _p.status) if _p.status != "missing" else "**fehlt (Inhalt)**"))
|
||||
w("")
|
||||
w("_Derselbe Capability-Strang, neuer Renderer: aus Diagnose wird Beratung. Die `fehlt`-Einträge sind der ehrliche Content-Backlog (höchster Hebel zuerst befüllen)._")
|
||||
w("")
|
||||
coverage_table([
|
||||
("Implementation Playbook Renderer", "PASS", "Reise pro Capability (why/tools/process/evidence/controls)"),
|
||||
("Roadmap → Playbook (Verkettung)", "PASS", "%d/%d Maßnahmen mit Playbook" % (len(_have), len(_pbs))),
|
||||
("Playbook-Inhalt (Knowledge)", "TODO" if _miss else "PASS", "%d Capabilities brauchen noch Inhalt" % len(_miss)),
|
||||
])
|
||||
|
||||
# ── Epics + roll-up ───────────────────────────────────────────────────────
|
||||
w("## Gaps → Epics (Backlog — nur erfasst, NICHT implementiert)")
|
||||
w("")
|
||||
|
||||
Reference in New Issue
Block a user