Roadmap item 5. GAP analysis and measure-prioritisation are the SAME computation: Required −
Known = the Capability Delta. The Capability Delta Engine (RS-005) computes it once; renderers
read that ONE delta. Interview Renderer (missing info → questions) was already built; this adds
the Roadmap/Management Renderer (missing capabilities → measures ranked by regulatory leverage).
- compliance/optimization/: regulatory_leverage() + select_within_budget() (pure leverage math)
+ roadmap_from_delta(assessment, ...) — the keystone binding optimization to the RS-005 delta
(dependency optimization → transition_reasoning, acyclic; the delta engine stays hermetic).
leverage(measure) = number of regulatory requirements it closes at once (e.g. patch management
→ CRA+MaschinenVO+IEC62443+ISO27001 = 4). No new corpus, no new meta-model class (freeze v1.0).
- Welt-1 honesty: percentages are exact count ratios over the IDENTIFIED requirements (the known
delta), never "% gesetzeskonform".
- reference suite: "Regulatory Optimization" section runs the SAME convergence delta → ranked
measures + budget answer + the management sentence "of N identified requirements you close M
with the top-K measures (X%) — highest regulatory leverage".
- ADR-003: Capability Delta Engine — one delta, many renderers; rename Gap → Capability Delta.
13 optimization tests (31 with transition+company), mypy --strict clean, check-loc 0.
Product code with no app caller + ADR/reference = non-runtime → no deploy (ADR-001).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Aligns the spec with RS-005 v0: the Transition Planning Engine owns the INFORMATION
GAPS (TransitionQuestionRequest), not the questions. Chain: Planning Engine ->
TransitionQuestionRequest -> Question Renderer (RS-005.1) -> Interview. RS-005.1
(renderer/templates) deliberately deferred; GeneratedQuestion reframed as the renderer's
output (a swappable policy layer), not part of the engine.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
v1.1: interview questions are GENERATED from the existing (Master) Controls, not
hand-written. Three building blocks: Control->question_intent (corpus/Execution),
~30-40 Master Question Templates (Reasoning), Transition-Prioritization (certs decide
which generated questions can be skipped; 217->19 funnel, reuses Company 2A + cert map).
v1.2: knowledge production. LLMs produce the first expert DRAFT (the prioritization per
transition); BreakPilot reviews + versions + OWNS the canonical library (in Git, not the
AI; model-independent, MDQ-00127 v4). Offline multi-model workflow, NOT runtime
(deterministic-first: LLM offline-propose, never online-mutate). Hard boundary: the
library is an expert DRAFT, not a normative/legal proof -- "cert probably covers X" is
Welt-1 (ClaimCoverage), never "erfuellt" (anti-fake-evidence).
Reframes the 100 seed questions as validation/template-extraction set. Spec only, no
code; non-runtime docs -> no deploy (ADR-001).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Second reasoning mode (extends, does not replace): BreakPilot answers MIGRATION
questions (start state -> target state -> delta), not regulation Q&A. New package
compliance/transition_reasoning/ (spec only). Transition Reasoning is RCI
generalized; reuses Company 2A (have), Master Capability Registry (MCAP) and RCI.
MDQ Registry = 4th identity-machine instance (after Master Controls/Obligations/
Capabilities): every Master Delta Question is a versioned, identifiable knowledge
unit (verifies MCAP, supports obligations, transition patterns, evidence types,
information gain, confidence impact, follow-up). Transition Patterns hold only MDQ
references -> reuse across transitions. Delta interview = information-gain
optimization, not a sequential questionnaire.
ADR-002: transitions are DATA (patterns + capability/MDQ knowledge), never engine
or metamodel extensions. 100 seed questions captured as v1.
Spec only (no code; freeze-respecting: additive package, no new graph/base class/
meta-model class). Non-runtime docs -> no deploy (ADR-001).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
A dev deploy must always have a verifiable runtime effect. Deploy only on
runtime/API/data-model/reasoning/security changes; docs, reference suites, ADRs,
board and ownership texts are merged to origin/main but NOT pushed to dev (no Orca
build). Keeps the CI/CD history meaningful: every build == a runtime change.
Architecture/release decision (not a developer convention) -> own folder
docs-src/architecture/adr/. Non-runtime: this commit triggers no deploy, per its
own policy.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
User-Reframe (die eigentliche Reife): nicht „Session X besitzt Knoten Y", sondern jede Session
besitzt KANTEN. Edge-Ownership-Tabelle: Feature/Cert->Cap = S3 · Cap->Obligation/Procedure/
Control/Evidence = S2 · Citation-Span->Legal-Basis = S1. Kein Owner hält alle ein+ausgehenden
Kanten eines Knotens. `cap.*` = kanonische ID auf obligation_id-Niveau. Capability = EINZIGER
Knoten über 3 Welten (Recht/Produkt/Nachweis) = semantischer Mittelpunkt. Künftiger Vertrag:
Confidence/Disambiguierung bei mehreren Capabilities = Domaene 3, Domaene 2 vertraut geliefertem
cap.X. Domaene 2 ruht stabil bis Wake-up.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
User-Praezisierung: Domaene 2 ruht NICHT unbestimmt. Wake-up-Trigger (EINER reicht):
Feature Graph>=200 Features · Span-Anker verfuegbar · neue Regulierung ingestiert · Runtime
kennt neue Evidence-Typen. Erster Folgeauftrag (gated auf Feature Library v1):
FEATURE COVERAGE REPORT = Wissenslueckenanalyse pro Feature (Feature->cap.*->Obligation->
Procedure->Evidence -> Coverage %; zeigt fehlende Capability/Procedure/Evidence je Feature).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
User-Antwort auf „wie verteilen wir die Arbeit": nach BESITZ der Datenmodelle, NICHT nach
Regulierung. 3 Domaenen (Legal Knowledge / Compliance Execution / Product Knowledge), jede
besitzt EIN Modell (andere read-only). 3 Vertraege: Legal->Compliance citation_span->legal_basis ·
Product->Compliance Feature->Capability (WICHTIGSTE Schnittstelle) · Compliance->Legal
obligation_id->legal_basis. Product Knowledge Graph = naechster Meilenstein (Reasoning-Session
umfokussieren, besitzt schon CanonicalProductRegulatoryProfile+Navigator). NIS2 verschoben.
Offene Fragen: Legal-KG-Owner, IACE-4.-Session, Compliance-2-Branch-Split.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
User-Entscheidung: Metamodell als v1.0 einfrieren (nur META-SEMANTIK: 6 Klassen + Kanten-
Vokabular + Attribute; NICHT Registry/Capabilities/Procedures). Architektur-Freeze in Kraft:
neue Regulierung = DATEN nicht Architektur; 0 neue Objektklassen erwartet; reopen nur bei
nachgewiesenem Scheitern (Hazard/Threat = einzige bekannte künftige Öffnungs-Ursache, nur fuer
FMEA). Reuse-Metrik-KPI definiert (Wissens-Akkumulations-Beweis). Validiert gegen 5
Regulierungsarten (DSGVO/CRA/MaschVO/Data-Act/NIS2). Erster Live-Durchlauf: MaschVO.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
User-Stresstest VOR der naechsten Regulierung: passt MaschVO/Data-Act/AI-Act/NIS2 ins
6-Klassen-Modell (Obligation/Capability/Procedure/Control/Evidence + Guidance) OHNE neue
Objektklasse? Ergebnis 4x NEIN -> Compliance Meta Model steht. 2 Verfeinerungen
(realized_by Capability OPTIONAL; Risiko-Niveau/Frist/Hazard-Schwere/Risiko-Tier = Attribute,
keine Klassen). 1 Watch-Point: Hazard/Threat (erst noetig bei quantitativem FMEA-Risiko als
First-Class-Knoten, nicht fuer Compliance-Abbildung). Kein Code, keine Regulierung ingestiert.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Schema-Papier statt capabilities.json (User-Entscheidung). Befund: die 8 SHARED_CAPABILITY-
Cluster zerfallen in Typ-1 (technische Capabilities: mfa/tls/code_signing/session/anomaly)
und Typ-2 (Sicherheitsziele: attack_surface_min/software_integrity = die #4-Gaps). Empfehlung
Modell C: Capability = EINZIGE neue Klasse; Sicherheitsziele = CORE Legal Obligations
(CORE/DOMAIN existiert bereits). Kanten-Graph (realized_by/specializes/...). guidance_basis
gehört konzeptionell an die Capability. 4 Entscheidungen offen (User). #5b Materialisierung
GEGATED auf Modell-Annahme — keine Daten verschoben.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
9 docs + index in docs-src/architecture/ documenting the deterministic
retrieval engine: retrieval pipeline, authority rerank, source_class,
source_role, control-intent + diversity, assessment, confidence,
explainability + supersede, framework_* layer. Each doc carries the exact
constants, the rationale behind them, code refs, and the failure class
it addresses. Audit/onboarding reference.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Schreibt das Zielmodell fest: Legal Obligation = gemeinsame Sprache zwischen
Legal Knowledge Graph (Chat) und Compliance Execution Graph (Engine).
- Registry-Schema v1 (id/tier/legal_basis/guidance_basis/facets/citation_anchor_ids/
relationships/decision_method)
- Zitierfähigkeit hängt an der OBLIGATION, nicht an Controls (Regulierungsänderung =
Anchor tauschen, Controls unverändert)
- legal_basis (Primärrecht) vs guidance_basis (NIST/OWASP/...) + source_role
(LEGAL_BASIS/GUIDANCE/EVIDENCE/IMPLEMENTATION/OUT_OF_SCOPE)
- HARTE Regel: LEGAL_MINIMUM nur mit Primärrechts-Anker
- Beziehungsgraph: requires/implements/supports/produces_evidence_for/depends_on/derived_from
- Citation-Anchor-Pipeline Document→Obligation (KEIN Re-Ingest zum Control-Neubau)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Friert das Kriterien-Meta-Modell ein: atomare getypte Kriterien mit drei
Achsen (verification_method, decision_method, compliance_tier), 3-Status-Gating
nur auf LEGAL_MINIMUM (ERFÜLLT/TEILWEISE/FEHLT), 3-Ebenen-Reporting und
Grün/Blau/Rot-Semantik. Control-UUID bleibt stabil (kein physischer Split),
Speicherung in generation_metadata jsonb (keine Schema-Änderung). Validiert am
Pilot (6/6 Disagreements korrigiert, TEILWEISE empirisch bestätigt).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
ai-sdk (legal_rag_client/scroll/types) liest die gepinnten Spec-Felder
article_label/regulation_code/article/paragraph/sub/citation_style/is_recital
mit Fallback auf alt-ingestierte Chunks (regulation_id, section); neuer getBool-Helfer.
Advisor + Drafting-Engine bilden die Quellenzeile primaer aus article_label
("BDSG § 38 Abs. 1"), sonst aus den strukturierten Feldern. 17 Tests gruen, tsc sauber.
Vertrag: docs-src/development/rag_reingest_spec.md (§2/§7). Deploy an den Re-Ingest
gekoppelt — neue Felder sind bis dahin leer (graceful Fallback).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
11 Modul-Eintraege entfernt, deren exakte Route bereits ein immer-sichtbarer
Pipeline-Schritt ist (advisory-board, ai-act, source-policy, loeschfristen,
einwilligungen, cookie-banner, dsr, vendor-compliance, consent-management,
email-templates, training) — Heimat bleibt die Pipeline, kein Feature-Verlust
(keiner dieser Schritte hat visibleWhen). "Datenschutz"-Gruppe zu "Cookie &
Consent" (Consent Dashboard + Cookie Live-Vorschau) verschlankt. Aehnlich
benannte, aber VERSCHIEDENE Seiten bewusst behalten (document-generator≠
catalog-manager, control-library≠coverage, consent≠consent-management,
cookie-banner≠/preview, vendor-compliance≠vendor-assessment).
Vollstaendige Routen-Inventur (Pipeline + Module + aufgeloeste Dups) in
docs-src/development/sdk-navigation-inventory.md — damit kein Feature
unsichtbar verloren geht.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Jede Normreferenz einer Maßnahme wird lizenzklassifiziert (eu_law /
public_domain / open / paid_reference) — paid-reference-Normen werden nur als
Verweis geführt, nie im Text gespeichert (idea/expression). Kuratierte
Maßnahmen tragen Tier 'core', KI-/Fallback-Maßnahmen 'review' (indikativ).
Frontend zeigt Quellen-Badges + "indikativ"-Kennzeichnung. Methodik in
docs-src/development/mapping-methodology.md (Szenario C, Due-Diligence).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Ergänzt nach Rückmeldung der Controls-Session: ID-Stabilität schützt auch deren
atom_classification (~161k) + addressee (control_uuid-gebunden); deren Step-1/2 ist
additiv (tier/source_type/core_count/addressee, bricht Verträge nicht); eine
Wahrheit — Muster-Schicht aus atom_classification speisen, nicht neu ableiten.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Andock-Vertrag für die Maßnahmen-Schicht: stabile Muster-Einheit + feste ID,
control→pattern-Mapping, Framework-Crosswalk pro Muster. Abstimmung mit der
Controls-Session (core/control-pipeline). CRA-Spine/M5xx bleiben unabhängig.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
check-rebuild-needed.sh war seit Mai funktionsfähig nur fuer 3 von 10
Containern. Die anderen 7 Dockerfiles hatten kein ARG/ENV BUILD_SHA und
docker-compose.yml hat fuer KEINEN Service den Wert durchgereicht — daher
defaultete BUILD_SHA ueberall auf "unknown" und die Drift-Check war
zahnlos.
- ARG BUILD_SHA + ENV BUILD_SHA in 8 zusaetzlichen Dockerfiles
(ai-compliance-sdk, developer-portal, document-crawler, dsms-gateway,
compliance-tts-service, docs-src, docs-site, dsms-node)
- docker-compose.yml: BUILD_SHA: \${BUILD_SHA:-unknown} in jedem build:
Block (10 Services)
- .gitea/workflows/ci.yaml: neuer Job build-sha-integrity validiert dass
jedes Dockerfile ARG+ENV hat und jeder compose-build den Arg durchreicht.
Faellt bei jedem PR/Push gegen master, der einen neuen Service oder
Dockerfile ohne BUILD_SHA einfuehrt.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Pin-free pymdownx gets latest version which fixes NoneType error
on bare code fences in Python 3.11.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Older pymdown-extensions (10.12) crashes on bare code fences.
Upgraded to 10.14.3 + mkdocs-material 9.6.14.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
pymdownx.highlight requires language specification on code fences.
Bare ``` causes NoneType error during MkDocs build.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There is only one remote (origin). Removed all occurrences of:
- git push gitea / git push origin main && git push gitea main
- "Pushing to gitea (external)" in deploy.sh
- # gitea: git@gitea.meghsakha.com:... remote comment in docs-src/index.md
- "Push auf gitea triggert" → "Push auf origin triggert" in docs
- Clone URL updated to ssh://git@coolify.meghsakha.com:22222/... in
README.md and CONTRIBUTING.md
Web UI URLs (gitea.meghsakha.com/...) are unchanged — those are still valid.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Squash of branch refactor/phase0-guardrails-and-models-split — 4 commits,
81 files, 173/173 pytest green, OpenAPI contract preserved (360 paths /
484 operations).
## Phase 0 — Architecture guardrails
Three defense-in-depth layers to keep the architecture rules enforced
regardless of who opens Claude Code in this repo:
1. .claude/settings.json PreToolUse hook on Write/Edit blocks any file
that would exceed the 500-line hard cap. Auto-loads in every Claude
session in this repo.
2. scripts/githooks/pre-commit (install via scripts/install-hooks.sh)
enforces the LOC cap locally, freezes migrations/ without
[migration-approved], and protects guardrail files without
[guardrail-change].
3. .gitea/workflows/ci.yaml gains loc-budget + guardrail-integrity +
sbom-scan (syft+grype) jobs, adds mypy --strict for the new Python
packages (compliance/{services,repositories,domain,schemas}), and
tsc --noEmit for admin-compliance + developer-portal.
Per-language conventions documented in AGENTS.python.md, AGENTS.go.md,
AGENTS.typescript.md at the repo root — layering, tooling, and explicit
"what you may NOT do" lists. Root CLAUDE.md is prepended with the six
non-negotiable rules. Each of the 10 services gets a README.md.
scripts/check-loc.sh enforces soft 300 / hard 500 and surfaces the
current baseline of 205 hard + 161 soft violations so Phases 1-4 can
drain it incrementally. CI gates only CHANGED files in PRs so the
legacy baseline does not block unrelated work.
## Deprecation sweep
47 files. Pydantic V1 regex= -> pattern= (2 sites), class Config ->
ConfigDict in source_policy_router.py (schemas.py intentionally skipped;
it is the Phase 1 Step 3 split target). datetime.utcnow() ->
datetime.now(timezone.utc) everywhere including SQLAlchemy default=
callables. All DB columns already declare timezone=True, so this is a
latent-bug fix at the Python side, not a schema change.
DeprecationWarning count dropped from 158 to 35.
## Phase 1 Step 1 — Contract test harness
tests/contracts/test_openapi_baseline.py diffs the live FastAPI /openapi.json
against tests/contracts/openapi.baseline.json on every test run. Fails on
removed paths, removed status codes, or new required request body fields.
Regenerate only via tests/contracts/regenerate_baseline.py after a
consumer-updated contract change. This is the safety harness for all
subsequent refactor commits.
## Phase 1 Step 2 — models.py split (1466 -> 85 LOC shim)
compliance/db/models.py is decomposed into seven sibling aggregate modules
following the existing repo pattern (dsr_models.py, vvt_models.py, ...):
regulation_models.py (134) — Regulation, Requirement
control_models.py (279) — Control, Mapping, Evidence, Risk
ai_system_models.py (141) — AISystem, AuditExport
service_module_models.py (176) — ServiceModule, ModuleRegulation, ModuleRisk
audit_session_models.py (177) — AuditSession, AuditSignOff
isms_governance_models.py (323) — ISMSScope, Context, Policy, Objective, SoA
isms_audit_models.py (468) — Finding, CAPA, MgmtReview, InternalAudit,
AuditTrail, Readiness
models.py becomes an 85-line re-export shim in dependency order so
existing imports continue to work unchanged. Schema is byte-identical:
__tablename__, column definitions, relationship strings, back_populates,
cascade directives all preserved.
All new sibling files are under the 500-line hard cap; largest is
isms_audit_models.py at 468. No file in compliance/db/ now exceeds
the hard cap.
## Phase 1 Step 3 — infrastructure only
backend-compliance/compliance/{schemas,domain,repositories}/ packages
are created as landing zones with docstrings. compliance/domain/
exports DomainError / NotFoundError / ConflictError / ValidationError /
PermissionError — the base classes services will use to raise
domain-level errors instead of HTTPException.
PHASE1_RUNBOOK.md at backend-compliance/PHASE1_RUNBOOK.md documents
the nine-step execution plan for Phase 1: snapshot baseline,
characterization tests, split models.py (this commit), split schemas.py
(next), extract services, extract repositories, mypy --strict, coverage.
## Verification
backend-compliance/.venv-phase1: uv python install 3.12 + pip -r requirements.txt
PYTHONPATH=. pytest compliance/tests/ tests/contracts/
-> 173 passed, 0 failed, 35 warnings, OpenAPI 360/484 unchanged
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Neue Endpunkte POST /obligations/dedup und GET /obligations/dedup-stats.
Pro candidate_id wird der aelteste Eintrag behalten, alle weiteren erhalten
release_state='duplicate' mit merged_into_id + quality_flags fuer Traceability.
Detail-View filtert Duplikate aus. MKDocs aktualisiert.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
DB-Constraint erlaubt nur must/should/may. 'can' gibt es nicht.
Alle Referenzen auf 'can' durch 'may' ersetzt.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
QA process, article types, match rates, preamble dedup rules,
and next steps documented in MkDocs under Entwicklung.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Benjamin Admin
Benjamin_Boenisch