odgs-maturity 1.0.0__tar.gz

odgs_maturity-1.0.0/.gitignore

@@ -0,0 +1,34 @@
+# Byte-compiled / optimised / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+audit_logs/

odgs_maturity-1.0.0/CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+authors:
+  - name: "Kartik Iyer"
+    email: "partner@metricprovenance.com"
+title: "ODGS Maturity — Governance Maturity Assessment"
+abstract: "Industry-agnostic governance maturity assessment for ODGS workspaces. Evaluates configuration across 8 pillars (Governance Foundations, Quality Enforcement, Semantic Architecture, Regulatory Coverage, Certification Readiness, Operational Execution, Integration Ecosystem, Continuous Improvement) and generates DAMA DMBOK-aligned improvement charters with SPOT root cause classification."
+version: 1.0.0
+date-released: 2026-04-30
+license: Apache-2.0
+url: "https://github.com/MetricProvenance/odgs-maturity"
+repository-code: "https://github.com/MetricProvenance/odgs-maturity"
+keywords:
+  - "data-governance"
+  - "maturity-assessment"
+  - "dama-dmbok"
+  - "data-quality"
+  - "odgs"
+  - "charter-generation"

odgs_maturity-1.0.0/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Metric Provenance B.V.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

odgs_maturity-1.0.0/MATURITY_BUSINESS_GUIDE.md

@@ -0,0 +1,73 @@
+# ODGS Maturity: The Business Value Guide
+
+> **Author:** Metric Provenance
+> **Date:** 3 May 2026
+
+## Introduction
+
+In the modern enterprise, data governance is no longer a back-office administrative task—it is a critical driver of compliance, security, and institutional value. The Open Data Governance Standard (ODGS) Maturity Model is designed to bridge the gap between technical reality and executive visibility. 
+
+This guide explains **why** measuring your data governance maturity is essential, **how** the ODGS assessment works, and **how to** use the results to drive automated, measurable improvements.
+
+---
+
+## 1. Why Measure Maturity? (The Business Case)
+
+Many organisations struggle to quantify their data governance posture. When Chief Data Officers (CDOs) ask, *"Are we compliant with DORA or the EU AI Act?"* or *"Can we trust the provenance of our data?"*, the answers are often anecdotal or buried in disconnected spreadsheets.
+
+The ODGS Maturity Model solves this by providing:
+
+1. **Objective Quantification:** It translates abstract governance concepts into a hard, reproducible score (0–100%).
+2. **Risk Surfacing:** It highlights exactly where your organisation is exposed, breaking down compliance risks into actionable technical gaps.
+3. **The ROI Baseline:** By establishing a baseline (e.g., 32% maturity), you can justify investments in automation and track the ROI as the score improves (e.g., to 75%).
+4. **Engineering-to-Executive Alignment:** It gives engineering teams a mathematical, evidence-based language to communicate infrastructure needs to CDOs and executive boards.
+
+---
+
+## 2. How the Model Works
+
+The ODGS Maturity Assessment evaluates your organisation across **8 Core Pillars**:
+
+1. **Metadata & Schema Control (META):** Are data sources mapped and catalogued?
+2. **Quality & Error Handling (QE):** Are rules enforced and errors triaged automatically?
+3. **Lineage & Provenance (LIN):** Can data be traced from origin to consumption?
+4. **Access & Sovereignty (SEC):** Is data access controlled, and are sovereign borders respected?
+5. **Regulatory Alignment (REG):** Are legal frameworks (GDPR, DORA, Basel III) mapped to physical rules?
+6. **Process & Business Logic (PROC):** Are data pipelines aligned with standard business operations (e.g., O2C, P2P)?
+7. **Certification & Audit (CERT):** Are there cryptographically verified, tamper-evident audit trails?
+8. **Bridge & Ecosystem Integration (BRIDGE):** Is the governance framework connected to physical platforms (Collibra, Databricks, Snowflake)?
+
+Based on the configuration in your `odgs-workspace.yaml`, the assessment assigns a score and categorises your maturity into a tier (e.g., *Developing*, *Measured*, *Optimised*).
+
+---
+
+## 3. How-To: Executing the Assessment
+
+### Step 1: Run the Diagnostic
+Your engineering team installs the diagnostic tool via the command line:
+```bash
+pip install odgs-maturity
+odgs-maturity assess --workspace ./odgs-workspace.yaml
+```
+
+### Step 2: Generate the Charter
+The tool evaluates your workspace and generates a **Governance Charter**. This document is not just a score—it is a detailed breakdown of your gaps, prioritised by business impact.
+- **Example Gap:** "Missing sovereign audit trail (CERT-03: 0%)"
+- **Business Impact:** "High risk of failure in compliance audits."
+
+### Step 3: Present to Leadership
+Engineers use the generated Charter to present the findings to the CDO. The Charter will typically indicate that manually closing these gaps requires **6-12 weeks of consultant time**.
+
+### Step 4: Close the Gaps
+Instead of hiring expensive consultants, your organisation can engage a **Metric Provenance certified implementation partner** — see [metricprovenance.com/brief](https://metricprovenance.com/brief) to request a partner introduction. Partners deliver pre-configured certified packs that close the identified gaps far faster than manual remediation.
+
+> The [European Data Governance Maturity Benchmark 2026](https://benchmark.metricprovenance.com) scored 99 enterprises across the EU. Average governance maturity: **37.6%** — a 62.4% enforcement gap. Your organisation is not alone, but the gap is closing faster for those who automate.
+
+### Step 5: Verify and Certify
+Re-run the maturity assessment after deploying the automation skills. The score will reflect the improvements (e.g., jumping from 32% to 65%+). You can then generate **S-Cert Certificates** to cryptographically prove your compliance to auditors and partners.
+
+---
+
+## Conclusion
+
+The ODGS Maturity Model is not just a test; it is the starting point of your automated governance journey. By diagnosing the exact gaps in your architecture, it enables you to deploy targeted, agentic solutions that turn compliance from a manual burden into an automated, verifiable asset.

odgs_maturity-1.0.0/MATURITY_GUIDE.md

@@ -0,0 +1,271 @@
+# ODGS Governance Maturity: Why It Matters and How It Works
+
+> **Author:** Metric Provenance · **Version:** 1.0 · **Standard:** ODGS v6
+> **Audience:** CDOs, Heads of Data, Governance Practitioners, Technology Leaders
+
+---
+
+## The Problem This Solves
+
+Most governance programmes fail for the same reason: they measure *activity*, not *reality*.
+
+Organisations install tools, write policies, create stewardship councils, and build dashboards — then declare victory. Six months later, nobody trusts the data, nobody reads the policies, and the stewardship council hasn't met since Q2. The dashboards, of course, still show green.
+
+This is **organisational theatre**. And it's expensive.
+
+ODGS Maturity Assessment exists because we needed a way to measure whether governance is *actually working* — not whether the governance team is *busy*.
+
+---
+
+## What ODGS Maturity Actually Measures
+
+The maturity engine reads your **actual workspace configuration** — the files, the bindings, the rules, the connections — and scores what it finds. Not what you *plan* to do. Not what your slide deck says. What exists on disk, right now.
+
+### The 8 Pillars
+
+The scoring framework spans 8 pillars, 6 adapted from DAMA DMBOK knowledge areas and 2 native to ODGS. Each pillar has a weight reflecting its importance to operational governance:
+
+| Pillar | Weight | What It Measures |
+|--------|--------|-----------------|
+| **Governance Foundations** | 20% | Are rules bound to business processes? Do you have context bindings — or just rules floating in space? |
+| **Quality Enforcement** | 18% | Do your rules have executable logic? Are there owners — real people accountable — or just "TBD" placeholders? |
+| **Operational Readiness** | 15% | Is the interceptor installed? Is enforcement set to `strict` (blocking) or `permissive` (logging, i.e. doing nothing useful)? |
+| **Metadata Integrity** | 12% | Is your ontology populated with real terms? Do metrics have calculation logic — or are they aspirational names? |
+| **Usage & Analytics** | 8% | Are rules linked to measurable DQ dimensions? Can you actually track improvement? |
+| **Organisational Adoption** | 12% | Have you customised rules for your industry? Are contexts bound to enforcement — or decorative? |
+| **Certification & Trust** | 8% | Are regulation packs installed? Are they cryptographically signed? Is the sovereign audit trail configured? |
+| **Bridge Connectivity** | 7% | Are source systems connected? Is there diversity in connection types (not just one pipe)? |
+
+> **Why these weights?** The top three pillars (Governance Foundations, Quality Enforcement, Operational Readiness) carry 53% of the total score because they represent the difference between governance that *does something* and governance that *exists on paper*. Bridge Connectivity and Usage Analytics carry less weight because they're infrastructure — important but not sufficient.
+
+### The 5 Maturity Levels
+
+The aggregate score maps to a standard 5-level maturity model aligned with DAMA DMBOK and CMMI:
+
+| Level | Range | Label | What It Means |
+|-------|-------|-------|--------------|
+| 1 | 0-19% | **Initial** | Governance exists in name only. No systematic configuration. |
+| 2 | 20-39% | **Developing** | Some artifacts are present. Basic structure but no customisation. |
+| 3 | 40-59% | **Defined** | Rules are bound to processes. Enforcement is configured. Not yet measured. |
+| 4 | 60-79% | **Measured** | Active monitoring. DQ dimensions linked. Owners assigned. Audit trail operational. |
+| 5 | 80-100% | **Optimised** | Continuous improvement. All pillars at production grade. Full automation. |
+
+---
+
+## How the Assessment Works
+
+### Step 1: Install and Run
+
+```bash
+pip install odgs-maturity
+
+# Score your workspace
+odgs-maturity score --workspace /path/to/odgs-workspace
+
+# Or auto-detect the installed ODGS package
+odgs-maturity score
+
+# JSON output for programmatic consumption
+odgs-maturity score --json
+```
+
+### Step 2: Understand What the Engine Inspects
+
+The maturity engine reads **9 protocol artifacts** from your ODGS installation, mapped to the three-branch governance model:
+
+| Branch | Artifact | What Gets Checked |
+|--------|----------|------------------|
+| **Executive** | `context_bindings.json` | Number of real (non-test) business contexts bound to rules |
+| **Executive** | `business_process_maps.json` | Number of E2E processes defined (O2C, P2P, R2R, etc.) |
+| **Executive** | `physical_data_map.json` | Source systems registered and mapped |
+| **Executive** | `interceptor.py` | Enforcement engine is installed |
+| **Judiciary** | `standard_data_rules.json` | Rules have logic expressions, owners, and DQ linkage |
+| **Judiciary** | `root_cause_factors.json` | SPOT root cause analysis framework loaded |
+| **Legislative** | `standard_metrics.json` | Metrics have calculation logic defined |
+| **Legislative** | `standard_dq_dimensions.json` | Data quality dimensions loaded and diverse |
+| **Legislative** | `ontology_graph.json` | Business terms defined in the semantic graph |
+
+Plus your `odgs-workspace.yaml` for organisation identity, enforcement mode, bridge configurations, and installed regulation packs.
+
+### Step 3: Read the Results
+
+The output gives you three things:
+
+1. **Aggregate Score** — A single 0-100 number with maturity level
+2. **Pillar Breakdown** — Per-pillar scores with gap counts and cost flags (🟢/🟡/🔴)
+3. **Red Flags** — Critical gaps requiring immediate attention
+
+```
+┌──────────────────────────────────────┐
+│  ODGS Governance Maturity Score      │
+│                                      │
+│  ████████░░░░░░░░░░░░░░░░░░░░  32%  │
+│  (Developing)                        │
+└──────────────────────────────────────┘
+
+┌─────────────────────────────┬───────┬───────────┬──────┬──────┐
+│ Pillar                      │ Score │ Level     │ Gaps │ Flag │
+├─────────────────────────────┼───────┼───────────┼──────┼──────┤
+│ Governance Foundations      │  0.0% │ Initial   │    3 │  🔴  │
+│ Quality Enforcement         │ 43.3% │ Defined   │    2 │  🟡  │
+│ Operational Readiness       │ 50.0% │ Defined   │    1 │  🟡  │
+│ ...                         │       │           │      │      │
+└─────────────────────────────┴───────┴───────────┴──────┴──────┘
+
+⚠ 3 critical gap(s):
+  • Context Bindings Populated: Map all critical business processes
+  • Business Process Maps Defined: Define E2E processes (O2C, P2P, R2R)
+  • Physical Data Map Coverage: Register source-of-record systems
+```
+
+### Step 4: Generate an Improvement Charter
+
+Once you have your score, generate a targeted improvement plan:
+
+```bash
+# Interactive charter generation
+odgs-maturity charter --workspace /path/to/workspace
+
+# Lifecycle Pain Point charter (auto-maps gaps to business processes)
+odgs-maturity charter --type lifecycle --workspace /path/to/workspace
+
+# KPI Improvement charter (maps gaps to specific KPI targets)
+odgs-maturity charter --type kpi --workspace /path/to/workspace
+
+# Strategic/AI Initiative charter (maps gaps to transformation goals)
+odgs-maturity charter --type strategic --workspace /path/to/workspace
+```
+
+The charter generator reads your maturity gaps, classifies them using SPOT analysis (Standard / Process / Organisation / Technology), maps them to DAMA dimensions, and produces a structured improvement plan with priorities, owners, and timelines.
+
+---
+
+## Why a Fresh Install Scores ~30-35%
+
+This is **by design**, not a defect.
+
+When you `pip install odgs`, the package ships with standard rules, metrics, ontology definitions, and DQ dimensions. These are the protocol's intellectual property — the legislative and judiciary branches, pre-populated. But the *executive branch* — the part that binds rules to **your** business processes, maps **your** source systems, and configures enforcement for **your** context — is necessarily empty.
+
+Nobody can pre-populate your business process maps. Nobody can pre-configure your data source bindings. Nobody can set your enforcement mode for you.
+
+The ~30-35% score tells you exactly this: **the protocol works, but it hasn't been configured for your organisation yet.** This is the honest answer. It's the difference between "we installed SAP" and "we actually configured SAP for our business."
+
+### The Urgency Gap
+
+The gap between ~30% (fresh install) and 60%+ (Measured maturity) represents the **configuration work** that transforms a generic protocol installation into an operational governance framework. This is the work that data governance consultants, systems integrators, and your internal governance team actually need to do.
+
+The maturity score makes this gap *visible* and *measurable* — which is precisely what most governance programmes lack.
+
+---
+
+## The Mathematical Integrity
+
+For those who care about the methodology (and if you're responsible for governance, you should):
+
+### Aggregate Scoring
+
+```
+Aggregate Score = Σ(Pillar_Score × Pillar_Weight)
+```
+
+Where:
+- `Pillar_Score` = Average of rule scores within the pillar (0-100)
+- `Pillar_Weight` = Fixed weight per pillar (sum to 1.0)
+- Each rule returns 0.0 to 1.0, converted to percentage at the pillar level
+
+### Properties
+
+- **Deterministic**: Same workspace state → same score. Always.
+- **Monotonic**: Improving any configuration can only increase the score. No perverse incentives.
+- **Bounded**: Score is strictly 0-100. No negative scores, no inflation.
+- **Idempotent**: Re-running the assessment on an unchanged workspace produces identical results.
+- **Read-only**: The engine *never* modifies your workspace. It reads, scores, reports.
+
+### What Gets Penalised
+
+The engine specifically penalises:
+- **Test/demo/sample contexts** in context bindings (filtered out of GOV-01)
+- **"TBD" owners** on rules (QE-02 marks these as unassigned)
+- **"All" industry targeting** on rules (ORG-01 — this means you haven't customised)
+- **Permissive enforcement mode** (OPS-02 — logging without blocking is not governance)
+
+These penalties are deliberate. They catch the most common patterns of *governance theatre* — rules that exist but aren't owned, contexts that are named but not bound, enforcement that logs but never stops anything.
+
+---
+
+## The Three-Branch Model
+
+ODGS structures governance as three independent branches — borrowing from constitutional design, not from software architecture:
+
+### Legislative Branch
+**What the organisation defines as truth.** Ontology terms, metrics definitions, DQ dimensions. These are *declarations* — "this is what 'Customer Lifetime Value' means, this is how we measure data completeness." The legislative branch is the semantic layer.
+
+### Judiciary Branch
+**How truth is enforced.** Data quality rules, logic expressions, root cause factors. These are *judgements* — "if field X is null, that violates rule Y." The judiciary branch is the enforcement layer.
+
+### Executive Branch
+**Where truth meets reality.** Context bindings, physical data maps, business process maps, the interceptor engine. These are *actions* — "bind rule Y to process Z running on system W." The executive branch is the operationalisation layer.
+
+The maturity engine scores across all three branches because governance fails when any branch is missing. Rules without context bindings are decorative. Context bindings without rules are empty. Both without an interceptor are fiction.
+
+---
+
+## Integration with Existing Investments
+
+### MCP Server (AI Agent Integration)
+
+The ODGS MCP server exposes governance capabilities to AI coding assistants (Cursor, Windsurf, Claude Desktop). The `governance_score` tool delegates to this same maturity engine, ensuring consistent scoring whether triggered from the CLI, an API, or an AI agent.
+
+### LLM Bridge (Agentic Automation)
+
+The LLM bridge provides five agentic capabilities that directly accelerate maturity:
+
+| Capability | What It Does | Maturity Impact |
+|-----------|-------------|----------------|
+| `discover_bindings` | Auto-generates context bindings from a data catalogue | Governance Foundations: 0% → 60%+ |
+| `compile_regulation` | Generates `logic_expression` from natural language rules | Quality Enforcement: +15-20% |
+| `check_drift` | Detects stale metric definitions | Metadata Integrity: maintains score |
+| `detect_conflicts` | Finds overlapping or contradictory rules | Quality Enforcement: prevents regression |
+| `narrate_audit` | Produces stakeholder-readable audit narratives | Certification & Trust: evidence generation |
+
+### Regulation Packs
+
+Regulation packs are cryptographically signed bundles of industry-specific rules (GDPR, DORA, Basel III, etc.). Installing packs directly improves CERT-01 and CERT-02 scores. Packs are distributed via the ODGS registry and verified at install time.
+
+---
+
+## What This Is *Not*
+
+- **Not a compliance checkbox.** The maturity score measures operational reality, not paper compliance.
+- **Not a vanity metric.** A fresh install gets ~30%. There is no "quick hack" to reach 80% without doing the actual work of binding rules to processes.
+- **Not a vendor assessment.** This measures *your* governance configuration, not the quality of the protocol itself.
+- **Not a replacement for governance strategy.** It measures whether your strategy has been operationalised — whether the plan became a system.
+
+---
+
+## Getting Started
+
+```bash
+# 1. Install
+pip install odgs-maturity
+
+# 2. Assess
+odgs-maturity score
+
+# 3. Understand the gaps
+odgs-maturity score --json | python -m json.tool
+
+# 4. Generate improvement plan
+odgs-maturity charter --type lifecycle
+
+# 5. Re-assess after configuration work
+odgs-maturity score
+```
+
+The gap between your current score and your target level is the work. The charter tells you what work to do. The re-assessment tells you whether you did it.
+
+That's governance grounded in reality, not theatre.
+
+---
+
+*For technical implementation details, see the [odgs-maturity README](./README.md). For the normative specification, see [ODGS v5](../odgs-v5/1_NORMATIVE_SPECIFICATION/). For the philosophical foundation, read the [Reality-Based Revolution Manifesto](../my-writings/manifesto.md).*