diff --git a/.github/workflows/governance-reports.yml b/.github/workflows/governance-reports.yml new file mode 100644 index 0000000..db19d94 --- /dev/null +++ b/.github/workflows/governance-reports.yml @@ -0,0 +1,54 @@ +name: Governance Reports Validation + +on: + workflow_dispatch: + pull_request: + paths: + - 'docs/reports/**' + - 'docs/schemas/governance_reports_manifest.schema.json' + - 'tools/validate_governance_reports.py' + - 'tool_tests/**' + - 'Makefile' + - '.pre-commit-config.yaml' + - '.github/workflows/governance-reports.yml' + push: + paths: + - 'docs/reports/**' + - 'docs/schemas/governance_reports_manifest.schema.json' + - 'tools/validate_governance_reports.py' + - 'tool_tests/**' + - 'Makefile' + - '.pre-commit-config.yaml' + - '.github/workflows/governance-reports.yml' + +concurrency: + group: governance-reports-${{ github.ref }} + cancel-in-progress: true + +jobs: + validate-governance-reports: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + cache: 'pip' + + - name: Cache pre-commit environments + uses: actions/cache@v4 + with: + path: ~/.cache/pre-commit + key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }} + + - name: Install pre-commit + run: python3 -m pip install --upgrade pre-commit + + - name: Run pre-commit hooks + run: pre-commit run --all-files + + - name: Run governance validation suite + run: make governance-check diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 5037ea8..09285a3 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,4 +1,18 @@ repos: + - repo: local + hooks: + - id: governance-report-pack-validate + name: governance-report-pack-validate + entry: make governance-validate + language: system + pass_filenames: false + stages: [pre-commit] + - id: governance-report-pack-check + name: governance-report-pack-check + entry: make governance-check + language: system + pass_filenames: false + stages: [pre-push] - repo: https://github.com/pre-commit/pre-commit-hooks rev: v5.0.0 hooks: diff --git a/Makefile b/Makefile index 523c8f4..50b7ff2 100644 --- a/Makefile +++ b/Makefile @@ -1,3 +1,19 @@ +.PHONY: governance-test governance-validate governance-validate-json governance-validate-json-check governance-check + +governance-test: + python3 -m unittest discover tool_tests + +governance-validate: + python3 tools/validate_governance_reports.py + +governance-validate-json: + python3 tools/validate_governance_reports.py --json + +governance-validate-json-check: + python3 tools/validate_governance_reports.py --json > /tmp/governance_validation.json + python3 -c 'import json; p=json.load(open("/tmp/governance_validation.json", "r", encoding="utf-8")); assert p.get("status")=="passed", f"Validator JSON status not passed: {p}"; print("Validator JSON status is passed.")' + +governance-check: governance-test governance-validate governance-validate-json-check .PHONY: governance-setup governance-deps-check governance-lint governance-validate governance-artifact-inventory governance-policy-test governance-validator-test governance-evidence-manifest governance-evidence-verify governance-evidence-schema governance-report governance-report-schema governance-check-generated governance-setup: diff --git a/docs/reports/BOARD_BRIEF_AGI_ASI_GOVERNANCE_2026_2030.md b/docs/reports/BOARD_BRIEF_AGI_ASI_GOVERNANCE_2026_2030.md new file mode 100644 index 0000000..331ead0 --- /dev/null +++ b/docs/reports/BOARD_BRIEF_AGI_ASI_GOVERNANCE_2026_2030.md @@ -0,0 +1,41 @@ + +Board Brief: Institutional-Grade AGI/ASI and Enterprise AI Governance (2026–2030) + + + +This board-focused brief summarizes the minimum governance posture required for enterprise AI, AGI-adjacent, and high-risk model deployments from 2026 to 2030. It highlights decision rights, risk appetite, supervisory readiness, and management accountability. + + + + +## 1) Board Decisions Required +1. Approve AI Risk Appetite Statement (AIRAS) and prohibited-use taxonomy. +2. Approve risk-tier model for autonomy and frontier capability unlocking. +3. Approve materiality thresholds for model changes and independent validation. +4. Approve annual crisis simulation charter and notification escalation protocol. + +## 2) What the Board Should Review Quarterly +- Top KRIs: policy overrides, severe incidents, unresolved validation findings. +- Control effectiveness: release gate pass rates and remediation aging. +- Regulatory readiness: jurisdiction heatmap and examination packet completeness. +- Frontier exposure: capability unlocks, containment events, anomaly index trend. + +## 3) Minimum Assurances the Board Should Demand +- WORM-backed evidence chain for critical decisions. +- Independent 2LOD challenge on high/critical model changes. +- 3LOD internal audit review of governance controls at least annually. +- Documented kill switch and tested fallback path for critical services. + +## 4) Board Dashboard Template +- AIRAS adherence (% systems inside approved risk envelope). +- Open high-severity findings (count + aging distribution). +- Regulator-readiness score by jurisdiction. +- Incident trend (SEV-1/SEV-2 rolling 12 months). + +## 5) Escalation Triggers for Immediate Board Notification +- Any SEV-1 AI incident with customer/systemic impact. +- Any unapproved frontier capability unlock in production. +- Any sustained fairness/explainability control breach in regulated decisions. +- Any supervisory action requiring formal remediation program. + + diff --git a/docs/reports/ENGINEERING_IMPLEMENTATION_PLAYBOOK_AI_GOVERNANCE_2026_2030.md b/docs/reports/ENGINEERING_IMPLEMENTATION_PLAYBOOK_AI_GOVERNANCE_2026_2030.md new file mode 100644 index 0000000..d5ed302 --- /dev/null +++ b/docs/reports/ENGINEERING_IMPLEMENTATION_PLAYBOOK_AI_GOVERNANCE_2026_2030.md @@ -0,0 +1,41 @@ + +Engineering Implementation Playbook: Regulator-Ready AI Governance (2026–2030) + + + +This engineering playbook translates governance policy into implementable controls for platform, security, MLOps, and application teams. It focuses on automation, evidence quality, and operational resilience. + + + + +## 1) Build Priorities (First 90 Days) +- Implement policy decision point (OPA/Rego) in CI/CD and runtime. +- Standardize governance sidecars for Node.js/Python inference pathways. +- Create Kafka governance topics and WORM archival integration. +- Add model/system card generation to release workflow. + +## 2) Non-Negotiable Technical Controls +- Deny-by-default policy for high-risk actions and privileged tool calls. +- Signed build artifacts and reproducible training manifests. +- Per-decision trace IDs linking inference, policy decision, and approval. +- Drift/fairness/quality monitors with automated incident hooks. + +## 3) High-Assurance RAG and Agentic Guardrails +- Retrieval from allowlisted corpora only. +- Prompt injection defenses and output policy filters. +- Planner/executor/verifier separation for sensitive workflows. +- Human approval requirement for material financial or legal actions. + +## 4) CI/CD Governance Gate Template +- Gate 1: model card completeness. +- Gate 2: validation pass + challenger comparison. +- Gate 3: privacy/fairness/explainability checks. +- Gate 4: required 2LOD approval for high/critical releases. + +## 5) Operational Runbook Baseline +- Incident severity classification (SEV-1 through SEV-4). +- Kill switch execution and rollback protocol. +- Forensic evidence export from Kafka+WORM stack. +- Post-incident corrective action tracking to closure. + + diff --git a/docs/reports/INSTITUTIONAL_GRADE_AGI_ASI_GOVERNANCE_2026_2030.md b/docs/reports/INSTITUTIONAL_GRADE_AGI_ASI_GOVERNANCE_2026_2030.md new file mode 100644 index 0000000..6007420 --- /dev/null +++ b/docs/reports/INSTITUTIONAL_GRADE_AGI_ASI_GOVERNANCE_2026_2030.md @@ -0,0 +1,465 @@ + +Institutional-Grade, Regulator-Ready AGI/ASI and Enterprise AI Governance Frameworks and Architectures (2026–2030) + + + +This document is a design-and-implementation reference for Fortune 500, Global 2000, and G-SIFI institutions building regulator-ready AI programs from 2026 to 2030. It operationalizes multilayer AI governance using a control-first architecture aligned to EU AI Act, NIST AI RMF 1.0, ISO/IEC 42001, OECD AI Principles, GDPR, FCRA/ECOA, Basel III, SR 11-7, PRA/FCA, MAS, and HKMA expectations. It specifies a production-grade enterprise reference architecture (Sentinel AI Governance Platform v2.4, WorkflowAI Pro, EAIP, high-assurance RAG, governed agentic workflows, Kafka-based WORM evidence, Docker Swarm hardening, Node.js/Python governance sidecars, Next.js explainability frontends, OPA/Rego compliance-as-code, and hyperparameter governance). It further introduces AGI/ASI containment controls (Luminous Engine Codex, Cognitive Resonance Protocol, Sentinel/Omni-Sentinel), financial-services model risk operating patterns, global compute governance proposals, and implementation roadmaps with board- and regulator-ready reporting templates. + + + + +## 0. Scope, Assumptions, and Point-in-Time Statement + +- **Point-in-time context**: this document is authored for planning cycles spanning **2026–2030** and should be refreshed as legal texts, supervisory statements, and technical standards evolve. +- **Scope**: enterprise and financial-sector AI systems (predictive, generative, and agentic), including frontier capability governance where applicable. +- **Not legal advice**: institutions should validate all controls against internal counsel interpretation per jurisdiction. +- **Usage model**: this report is a reference baseline; local implementations should tailor control thresholds to risk appetite, legal entity structure, and product criticality. + +--- + +## 1. Executive Design Principles + +1. **Policy-driven engineering**: all material obligations become machine-verifiable controls. +2. **One control library, many jurisdictions**: common control taxonomy with regional overlays. +3. **Evidence by default**: every critical action emits signed audit evidence to immutable storage. +4. **Risk-tiered autonomy**: autonomy and compute access scale only with safety assurance maturity. +5. **Three-lines accountability**: product ownership (1LOD), risk/compliance challenge (2LOD), internal audit assurance (3LOD). + +--- + +## 1.1 Document Governance and Approval Metadata (for regulators/auditors) + +| Field | Requirement | Example | +|---|---|---| +| Document owner | Named senior accountable executive | Group Chief AI Officer | +| First line approver | Business/technology accountable owner | CIO / Head of AI Platform | +| Second line approver | Independent risk/compliance function | CRO delegate + Compliance Officer | +| Third line review | Independent assurance checkpoint | Internal Audit model-risk review | +| Review frequency | Maximum policy refresh interval | Quarterly operational; annual full refresh | +| Distribution class | Information classification | Confidential – Regulatory/Audit | + +This metadata block should be retained in the final board and regulator version so evidence consumers can immediately identify accountable parties and approval recency. + +--- + +## 2. Multilayer Governance Pillars (Institutional Operating Model) + +## Pillar 1 — Board and Management Accountability +- Board-approved **AI Risk Appetite Statement (AIRAS)** with explicit prohibited-use catalog. +- Senior Manager Function mapping (or equivalent) for accountable executives. +- Mandatory quarterly AI risk reporting to Board Risk and Audit committees. + +## Pillar 2 — Legal and Regulatory Compliance +- Common Control Taxonomy (CCT) with control IDs, ownership, testing frequency, evidence type. +- Regulatory change management cadence (monthly horizon scan; quarterly policy refresh). +- Jurisdictional overlays with conflict-resolution rules and legal escalation triggers. + +## Pillar 3 — Model Risk and Validation (SR 11-7 Style) +- Conceptual soundness, data integrity, development controls, independent validation. +- Materiality-based change governance: minor/major/material retrain thresholds. +- Ongoing outcomes analysis: stability, drift, fairness, concentration, and explainability quality. + +## Pillar 4 — Security, Resilience, and Operational Risk +- Zero-trust service-to-service controls, secret lifecycle governance, signed artifacts. +- Runtime guardrails for model/agent calls (OPA policy checks + sidecar telemetry). +- Operational resilience targets (RTO/RPO) for critical AI services. + +## Pillar 5 — Data, Privacy, and Rights Management +- Data minimization, purpose limitation, retention, and deletion orchestration. +- PII/sensitive feature controls, regional data residency and transfer governance. +- Automated rights workflows (access, correction, explanation, contestability where applicable). + +## Pillar 6 — Fairness, Explainability, and Conduct +- Fairness testing protocol by use case (credit, trading, advisory, HR, fraud). +- Explainability standards for end-users, auditors, and regulators. +- Conduct-risk controls for manipulative interaction, unsuitable recommendations, and dark patterns. + +## Pillar 7 — Incident, Crisis, and Supervisory Response +- AI incident severity levels (SEV-1 to SEV-4) and mandatory response windows. +- Kill switch, safe fallback mode, and regulator-notification runbooks. +- Annual independent crisis simulation and postmortem remediation governance. + +## Pillar 8 — Frontier AGI/ASI Containment +- Capability gating, controlled tool-use, and strict egress restrictions. +- Compute access approvals with dual control and independent signoff. +- Frontier evaluation, anomaly monitoring, and emergency isolation procedures. + +--- + +## 3. Regulatory Alignment Matrix (Control-Centric) + +## 3.1 Common Control Taxonomy (sample) +- **CCT-GOV-001**: AIRAS approved and reviewed annually. +- **CCT-REG-004**: high-risk use-case legal review before deployment. +- **CCT-MRM-010**: independent validation for high/critical models. +- **CCT-PRV-007**: DPIA/PIA completion and residual-risk acceptance. +- **CCT-EXP-006**: adverse-action and explanation generation controls. +- **CCT-OPS-012**: incident runbook tested every quarter. +- **CCT-FRT-003**: frontier capability unlock requires dual approval. + +## 3.2 Mapping approach +- EU AI Act: risk classification + high-risk obligations + GPAI transparency. +- NIST AI RMF 1.0: Govern/Map/Measure/Manage control tagging. +- ISO/IEC 42001: AI management system process controls and internal audit loops. +- OECD principles: transparency, robustness, accountability outcomes. +- GDPR: lawful basis, automated decisioning safeguards, rights management. +- FCRA/ECOA: fair lending + adverse action and explainability. +- Basel III/SR 11-7: capital/risk integration and model lifecycle governance. +- PRA/FCA, MAS, HKMA: local model risk, outsourcing, conduct, and resilience overlays. + +## 3.2.1 Crosswalk table (sample for implementation teams) + +| CCT ID | EU AI Act intent | NIST AI RMF function | ISO/IEC 42001 alignment | Financial-sector relevance | +|---|---|---|---|---| +| CCT-GOV-001 | Governance and accountability duties | Govern | AI governance and leadership controls | Board risk oversight and committee evidence | +| CCT-MRM-010 | High-risk quality/monitoring obligations | Measure + Manage | AI lifecycle evaluation and monitoring | SR 11-7 conceptual soundness and ongoing monitoring | +| CCT-PRV-007 | Data governance/transparency constraints | Map + Govern | Data governance and impact assessment controls | Privacy/consumer compliance and model input controls | +| CCT-EXP-006 | Transparency to affected persons | Measure + Manage | Explainability/communication controls | FCRA/ECOA adverse action and rationale consistency | +| CCT-OPS-012 | Post-market monitoring and incident response | Manage | Incident and corrective action management | Operational resilience and supervisory reporting | + +## 3.3 Required evidence per control +1. Policy evidence (approved standard/procedure, owner, revision history). +2. Design evidence (threat model, architecture, data flow, test design). +3. Execution evidence (CI/CD logs, policy test output, approvals). +4. Outcome evidence (monitoring KPIs/KRIs, incident records, remediation closure). + +## 3.4 Regulator-ready control implementation matrix (sample) + +| Control ID | Objective | Automated Gate | Human Approval | Evidence Artifact | Typical Frequency | +|---|---|---|---|---|---| +| CCT-MRM-010 | Independent validation for high/critical models | CI status + validation signature check | 2LOD model risk signoff | Validation report hash + approval record | Pre-release + annual | +| CCT-PRV-007 | Privacy impact and lawful basis assurance | DPIA presence check in release manifest | Privacy officer approval | DPIA ID + residual-risk acceptance | Pre-release + material change | +| CCT-EXP-006 | Explanation/adverse-action readiness | Explanation coverage test threshold | Product/legal confirmation for wording | Explanation QA logs + sample outputs | Per release | +| CCT-OPS-012 | Incident readiness and response timeliness | Runbook version + drill recency checks | Operations risk committee | Drill report + corrective actions | Quarterly | +| CCT-FRT-003 | Frontier capability unlock controls | Capability-class policy gate | Dual authorization (1LOD + 2LOD) | Capability unlock ticket + attestation | Per unlock | + +--- + +## 4. Enterprise AI Reference Architecture (Design + Build) + +## 4.1 Layered architecture +1. **Channel/Experience**: Next.js explainability and governance dashboards. +2. **Workflow Orchestration**: WorkflowAI Pro and EAIP controlled workflows. +3. **Model + Agent Runtime**: predictive models, LLMs, and governed multi-agent systems. +4. **Knowledge + Retrieval**: high-assurance RAG with source trust policies. +5. **Governance Control Plane**: Sentinel AI Governance Platform v2.4 + OPA/Rego PDP. +6. **Evidence and Ledger Plane**: Kafka governance topics + WORM evidence store. +7. **Platform and Security Plane**: Docker Swarm hardened clusters + secret management. + +## 4.2 Sentinel AI Governance Platform v2.4 implementation details +- AI system registry: owner, model card, use case, risk tier, criticality, jurisdictions. +- Control obligations engine: attaches CCT controls by risk tier and jurisdiction. +- Exception workflow: time-bound exemptions with compensating controls. +- Regulator packet generator: policy matrix + test evidence + incident summaries. + +## 4.3 WorkflowAI Pro / EAIP governed workflow pattern +- Stage gates: ideation -> design review -> validation -> release -> post-release monitoring. +- Mandatory approvals for material changes in credit, trading, and fiduciary use cases. +- Signed workflow manifests persisted to evidence store. + +## 4.4 High-assurance RAG reference design +- Approved corpus allowlist + data freshness SLAs. +- Retrieval policy checks (classification, purpose, region restrictions). +- Prompt injection defense and tool-call sanitization. +- Mandatory citation/provenance with abstention policy for low-confidence responses. + +## 4.5 Governed agentic workflows +- Planner/executor/verifier separation for sensitive operations. +- Tool-permission envelopes (budget, scope, time, region, data class). +- Human-in-the-loop for elevated-risk actions (funds movement, underwriting override, policy changes). +- Continuous behavior monitoring and rollback to constrained mode. + +## 4.6 Kafka-based WORM audit logging architecture +- Core topics: `policy_decisions`, `model_inference`, `agent_actions`, `human_approvals`, `incidents`. +- Schema governance with compatibility checks and signed schema releases. +- Immutable archival stream to WORM store with chain-hash manifests. +- Regulator replay API for deterministic event reconstruction. + +## 4.7 Docker Swarm security baseline +- mTLS service mesh-style communication controls. +- Signed images + SBOM verification at deploy time. +- Runtime hardening: seccomp, apparmor, least privilege capabilities. +- Separate node pools for frontier workloads vs production business workloads. + +## 4.8 Node.js/Python governance sidecars +- Intercept inference requests and enforce pre-flight policy decisions. +- Enrich calls with classification tags (risk tier, data class, jurisdiction). +- Emit signed governance event payloads to Kafka. +- Block and log denied actions with reason codes for auditors. + +## 4.9 Next.js explainability frontend patterns +- Views by persona: board, regulator, model owner, operations, internal audit. +- Per-decision trace with model version, features/data classes, policy outcomes. +- Consumer-compliant adverse-action narratives for applicable decisions. + +## 4.10 OPA compliance-as-code and hyperparameter governance +- Rego policy packs: privacy, fairness, validation, deployment, incident response. +- CI/CD policy gates (build, deploy, promote, rollback). +- Hyperparameter envelopes with materiality triggers and revalidation requirements. +- Signed training manifest with dataset and config fingerprints. + +## 4.11 Architecture decision records (ADR) that should be mandatory + +1. **ADR-AI-001**: why this model class is suitable for the use case and risk tier. +2. **ADR-AI-002**: why this explainability strategy is sufficient for customer/regulator needs. +3. **ADR-AI-003**: why chosen retrieval corpus and freshness SLA are acceptable. +4. **ADR-AI-004**: why autonomy level/tool permissions are safe for this workflow. +5. **ADR-AI-005**: why fallback and kill-switch mechanisms satisfy resilience objectives. + +### Example Rego control (deployment gate) +```rego +package ai.deploy + +default allow = false + +allow { + input.risk_tier != "critical" + input.validation.status == "passed" + input.model_card.approved == true +} + +allow { + input.risk_tier == "critical" + input.validation.status == "passed" + input.model_card.approved == true + input.second_line_approval == true +} +``` + +### Example Terraform governance guardrail (conceptual) +```hcl +resource "kafka_acl" "policy_decisions_read" { + principal = "User:governance-sidecar" + resource = "policy_decisions" + operation = "Read" + permission = "Allow" +} +``` + +--- + +## 5. AGI/ASI Safety and Containment Framework + +## 5.1 Minimum viable AGI governance stack +1. Capability eval suite (autonomy, deception, cyber, persuasion, replication behaviors). +2. Compute governance gateway (approved clusters, budget caps, dual authorization). +3. Execution sandbox with egress-deny defaults and tool allowlists. +4. Real-time anomaly detection and policy violation interrupts. +5. Emergency isolation, model freeze, and revocation workflows. + +## 5.2 Luminous Engine Codex +- Tiered capability catalog: allowed, restricted, prohibited, and escalation-required. +- Pre-unlock checks: technical safety tests, legal signoff, 2LOD risk approval. +- Independent assurance requirement for highest-tier capabilities. + +## 5.3 Cognitive Resonance Protocol (CRP) +- Consistency and intent-alignment probes under adversarial prompt perturbation. +- Divergence index with hard thresholds for restricted mode fallback. +- CRP breach handling integrated with SEV incident process. + +## 5.4 Sentinel / Omni-Sentinel supervisory controls +- Unified telemetry graph across model, agent, workflow, and user events. +- Predictive incident scoring and proactive containment triggers. +- Safe-mode profile: no external tools, no stateful long-horizon tasks, no privileged APIs. + +## 5.5 Crisis simulation program +- Quarterly tabletop + technical simulation for frontier and systemic incidents. +- Scenarios: market abuse enablement, autonomous fraud chain, deceptive behavior emergence. +- Outputs: regulator-ready postmortem, control updates, owner-assigned actions. + +## 5.6 Frontier risk taxonomy +- Technical, operational, legal, geopolitical, and systemic externality classes. +- Probability-impact score plus control sufficiency and detection latency metrics. + +--- + +## 6. Civilizational-Scale Governance and Compute/Legal Proposals + +## 6.1 International Compute Governance Consortium (ICGC) +- Multilateral governance forum for frontier compute reporting and assurance norms. +- Common templates for incident reporting and safety case disclosures. + +## 6.2 Global compute registry model +- Tiered reporting thresholds by compute scale and demonstrated capability class. +- Cryptographic attestation of training runs and compute provenance. +- Emergency cross-border escalation protocol for systemic incidents. + +## 6.3 Treaty-aligned systemic governance +- Baseline safety requirements for frontier systems with mutual-audit recognition. +- Interoperable, machine-readable regulatory evidence APIs. +- National overlay modules preserving sovereign legal requirements. + +--- + +## 7. Financial Services Deep-Dive (G-SIFI Priority) + +## 7.1 Credit decisioning and underwriting +- FCRA/ECOA controls embedded from feature engineering through decision issuance. +- Adverse action explanations generated from approved reason-code ontology. +- Fair lending monitoring: segment-level drift, disparity thresholds, override audits. + +## 7.2 Trading and market activity AI +- Pre-trade compliance checks against mandate, concentration, and suitability. +- Intraday anomaly detection for behavior drift and market abuse indicators. +- Autonomous strategy constraints by product, venue, and volatility regime. + +## 7.3 Risk and treasury analytics +- Independent challenger models for VaR/stress and liquidity forecasting use cases. +- Governance linkage to ICAAP/CCAR-like planning and capital committee reviews. +- Model risk tiering tied to capital impact and supervisory materiality. + +## 7.4 Fiduciary AI advisors +- Best-interest and suitability policy engine for recommendation generation. +- Vulnerable-client protections and mandatory human escalation conditions. +- Full recommendation provenance and communication archiving. + +--- + +## 8. Kafka ACL Governance + Continuous Compliance Engine + +## 8.1 Kafka ACL governance +- ACLs declared in code repositories; production mutations only via CI/CD. +- Service identities mapped to least-privilege topic permissions. +- Daily reconcile job detects drift and triggers remediation workflow. + +## 8.2 Terraform governance-as-code +- Reusable modules for topics, ACLs, retention, encryption, schema policy. +- Policy checks run at `plan` and `apply` with blocking severity for critical failures. +- Time-bound exception process with automatic expiry and reapproval. + +## 8.3 Continuous compliance engine +- OPA/Rego evaluates infrastructure, workflow, and runtime telemetry controls. +- Non-compliance produces tickets, incident hooks, and regulator evidence bundles. +- WORM archive stores daily signed compliance snapshots. + +## 8.4 Auditor workflow +- Read-only auditor portal with search by control ID, system ID, date range, incident ID. +- One-click examination binder generation (policy, tests, approvals, event replay). +- Chain-of-custody metadata included for each evidence artifact. + +## 8.5 Evidence retention baseline (policy template) + +| Evidence Class | Minimum Retention | Storage Requirement | Integrity Requirement | +|---|---|---|---| +| Policy and standards versions | 7 years | WORM-backed archive | Version hash + approval signature | +| Validation reports and challenge logs | 7 years | WORM + restricted access | Signed artifact digest | +| Inference and policy decision telemetry (critical systems) | 2–7 years (jurisdiction dependent) | Tiered WORM/object storage | Chain-hash manifest per batch | +| Incident and regulator communication records | 7 years | WORM + legal hold capability | Immutable audit trail with access logs | + +--- + +## 9. Implementation Roadmap (2026–2030) + +## Wave 1 (0–6 months): Control Foundation +- Establish AIRAS, CCT, and enterprise AI inventory baseline. +- Deploy Sentinel v2.4 registry and OPA policy decision point. +- Introduce mandatory CI/CD governance gates for critical use cases. + +## Wave 2 (6–12 months): Platform Integration +- Integrate WorkflowAI Pro/EAIP and governance sidecars. +- Stand up Kafka governance streams and WORM evidence pipeline. +- Launch explainability dashboards and regulator packet automation. + +## Wave 3 (12–24 months): Supervisory Readiness +- Complete jurisdiction overlays (EU/UK/US/APAC) and control attestations. +- Operationalize independent validation cadence for all high/critical models. +- Execute full crisis simulation cycle and independent assurance review. + +## Wave 4 (24–48 months): Frontier and Systemic Resilience +- Expand AGI/ASI containment controls and compute governance rigor. +- Implement cross-entity systemic risk telemetry and coordination protocols. +- Participate in interoperable registry/evidence standards initiatives. + +## 9.1 Delivery workplan by function (RACI-aligned) + +| Workstream | 1LOD (Build/Run) | 2LOD (Challenge/Policy) | 3LOD (Assure) | Primary Deliverable | +|---|---|---|---|---| +| Control taxonomy and policy codification | AI Platform + Enterprise Architecture | Risk + Compliance + Legal | Internal Audit | Approved CCT + policy-as-code baseline | +| Evidence and WORM implementation | Platform Engineering + SRE | Operational Risk | Internal Audit | Immutable evidence chain and replay API | +| Model validation uplift | Data Science + MLOps | Model Risk Management | Internal Audit | Validation standards + annual test calendar | +| Frontier containment program | Research/Advanced AI Engineering | Risk + Legal | Internal Audit | Capability gating and crisis drill protocol | +| Regulator reporting automation | Governance Engineering | Compliance + Regulatory Affairs | Internal Audit | Regulator-ready packet templates and exports | + +## 9.2 30-60-90 day execution starter (for transformation offices) + +- **Day 0–30**: establish AIRAS, freeze uncontrolled deployments, stand up initial inventory and control gap assessment. +- **Day 31–60**: deploy minimum policy gates in CI/CD, implement evidence topic taxonomy in Kafka, launch validation triage for high-risk systems. +- **Day 61–90**: operationalize regulator packet prototype, run first crisis simulation, and produce board dashboard with KPI/KRI baseline. + +--- + +## 10. Report Templates for Boards, Regulators, and Engineering Teams + +## 10.1 Board quarterly pack +- AIRAS adherence, top KRIs, top incidents, residual risk acceptance decisions. +- Frontier exposure scorecard and containment readiness status. + +## 10.2 C-suite monthly operating report +- AI deployment velocity vs control pass rates. +- Material model changes, exception usage, and remediation aging. +- Business value realization with risk-adjusted performance. + +## 10.3 Regulator examination pack +- Jurisdiction-specific control matrix and independent validation summaries. +- Incident log, root cause analysis, and remediation closure evidence. +- WORM-backed replay artifacts and policy decision trace samples. + +## 10.4 Enterprise architect/engineer pack +- Architecture conformance status, drift findings, and control coverage. +- Policy test failure distribution and mean-time-to-remediation metrics. +- Sidecar enforcement efficacy and false-block/false-allow analysis. + +--- + +## 11. KPI/KRI Catalog (Sample) + +### KPI samples +- `% critical AI systems with current independent validation`. +- `% releases passing mandatory controls on first attempt`. +- `median time from policy update to enterprise-wide enforcement`. + +### KRI samples +- `count of policy overrides by severity and business line`. +- `rate of unexplained or contested decisions above threshold`. +- `frontier anomaly index (CRP divergence + containment events)`. + +--- + +## 12. Practical Adoption Guidance + +1. Start with a control catalog and evidence model before expanding use cases. +2. Make high-risk AI release impossible without automated control pass. +3. Build regulator-ready packets continuously, not only before exams. +4. Use crisis simulations to validate not only controls, but decision rights and escalation speed. +5. Treat AGI/ASI readiness as an operational resilience program, not only an R&D safety activity. + +--- + +## 13. Conclusion + +The 2026–2030 window requires institutions to mature from policy documentation to enforceable governance systems. The architecture and operating model in this paper enable that shift: controls are codified, evidence is immutable, autonomy is risk-tiered, and supervisory interactions are supported by deterministic audit trails. For Fortune 500, Global 2000, and G-SIFIs, this approach balances innovation velocity with fiduciary duty, systemic stability, and regulator trust. + +## 14. Companion Reports (Audience-Specific) + +- `docs/reports/BOARD_BRIEF_AGI_ASI_GOVERNANCE_2026_2030.md` for boards and risk committees. +- `docs/reports/REGULATOR_EXAM_PACK_AI_GOVERNANCE_2026_2030.md` for supervisory examinations. +- `docs/reports/ENGINEERING_IMPLEMENTATION_PLAYBOOK_AI_GOVERNANCE_2026_2030.md` for platform and engineering teams. + +## Appendix A — Minimum artifacts required before production approval (high/critical systems) + +1. Final model card + system card with owner, risk tier, and use-case limits. +2. Completed threat model and data-flow diagram with jurisdiction routing. +3. Independent validation report with challenge log and issue closure evidence. +4. Signed policy test bundle (OPA/Rego outputs + CI/CD run metadata). +5. Incident runbook with named on-call roles and kill-switch evidence. +6. Explainability package with end-user and supervisory-facing rationale format. +7. Frontier evaluation summary (if applicable) with containment control status. + +## Appendix B — Review cadence and operating forums (recommended) + +- Weekly: AI operations risk stand-up (incidents, overrides, drift alerts). +- Monthly: model governance forum (material changes, validation backlog, control failures). +- Quarterly: board/regulator readiness review (KRIs, incidents, remediation completion, frontier posture). +- Annual: independent assurance deep-dive and policy library refresh. + + diff --git a/docs/reports/README_GOVERNANCE_REPORTS.md b/docs/reports/README_GOVERNANCE_REPORTS.md new file mode 100644 index 0000000..22a5eb9 --- /dev/null +++ b/docs/reports/README_GOVERNANCE_REPORTS.md @@ -0,0 +1,45 @@ +# Governance Report Pack (2026–2030) + +This folder includes a multi-audience governance documentation pack: + +- `INSTITUTIONAL_GRADE_AGI_ASI_GOVERNANCE_2026_2030.md` (master reference) +- `BOARD_BRIEF_AGI_ASI_GOVERNANCE_2026_2030.md` (board package) +- `REGULATOR_EXAM_PACK_AI_GOVERNANCE_2026_2030.md` (regulator packet template) +- `ENGINEERING_IMPLEMENTATION_PLAYBOOK_AI_GOVERNANCE_2026_2030.md` (engineering playbook) +- `governance_reports_manifest.json` (machine-readable report inventory) +- `../schemas/governance_reports_manifest.schema.json` (manifest reference schema) + +## Validation + +Run the structural validator: + +```bash +python3 -m unittest discover tool_tests +python3 tools/validate_governance_reports.py +python3 tools/validate_governance_reports.py --json +make governance-validate-json-check +make governance-check +``` + +The validator checks: +- required ``, `<abstract>`, `<content>` wrappers +- required section anchors per audience artifact +- basic title-content sanity +- report index consistency in `README_GOVERNANCE_REPORTS.md` +- report inventory consistency in `governance_reports_manifest.json` +- manifest entries must map exactly to the governed report set (no missing or unexpected entries) +- manifest report paths must exist in the repository +- manifest schema integrity for required root/item fields + +## Optional local git hook + +A local pre-commit configuration is available at repository root: + +```bash +pre-commit install +pre-commit run --all-files +``` + +The hook configuration in `.pre-commit-config.yaml` runs: +- `make governance-validate` on pre-commit (fast local check) +- `make governance-check` on pre-push (full suite) diff --git a/docs/reports/REGULATOR_EXAM_PACK_AI_GOVERNANCE_2026_2030.md b/docs/reports/REGULATOR_EXAM_PACK_AI_GOVERNANCE_2026_2030.md new file mode 100644 index 0000000..6b057e4 --- /dev/null +++ b/docs/reports/REGULATOR_EXAM_PACK_AI_GOVERNANCE_2026_2030.md @@ -0,0 +1,50 @@ +<title> +Regulator Examination Pack Template: Enterprise AI Governance (2026–2030) + + + +This regulator-facing template organizes examination evidence for enterprise AI governance programs, including policy, design, execution, and outcomes. It is designed for supervisory reviews across major jurisdictions. + + + + +## 1) Examination Packet Index +1. Governance charter and accountable executive mapping. +2. AI inventory with risk tiers and jurisdictional scope. +3. Control matrix (CCT) mapped to applicable regulatory obligations. +4. Independent validation summaries and issue remediation logs. +5. Incident register, root cause analyses, and closure evidence. +6. Sample deterministic replay artifacts from WORM evidence stores. + +## 2) Required Evidence Tables + +### 2.1 Policy Evidence +- AIRAS and policy version history with approval signatures. +- Change logs showing legal/compliance review on high-risk policies. + +### 2.2 Design Evidence +- Reference architecture diagrams (control plane, evidence plane, runtime). +- Threat models, data flow maps, and model/system card templates. + +### 2.3 Execution Evidence +- CI/CD policy gate outputs (OPA/Rego). +- Release manifests and approval records for high/critical systems. +- Kafka evidence topic integrity checks and archival proofs. + +### 2.4 Outcomes Evidence +- KPI/KRI trend history and thresholds. +- Drift/fairness/explainability monitoring output. +- Exception/override logs with compensating control evidence. + +## 3) Supervisory Q&A Readiness Checklist +- Can each material decision be traced end-to-end? +- Are control exceptions time-bound and approved by accountable owners? +- Are independent validation findings resolved within policy SLA? +- Are incident notification thresholds aligned with legal requirements? + +## 4) Examination-Day Operating Model +- Named spokespersons: 1LOD, 2LOD, 3LOD. +- Evidence custodian role for artifact provenance and chain-of-custody. +- Real-time replay support for selected model/agent decisions. + + diff --git a/docs/reports/governance_reports_manifest.json b/docs/reports/governance_reports_manifest.json new file mode 100644 index 0000000..b93eb7d --- /dev/null +++ b/docs/reports/governance_reports_manifest.json @@ -0,0 +1,26 @@ +{ + "version": "2026.1", + "report_pack": "institutional_agi_asi_governance", + "reports": [ + { + "path": "docs/reports/INSTITUTIONAL_GRADE_AGI_ASI_GOVERNANCE_2026_2030.md", + "audience": "enterprise", + "required": true + }, + { + "path": "docs/reports/BOARD_BRIEF_AGI_ASI_GOVERNANCE_2026_2030.md", + "audience": "board", + "required": true + }, + { + "path": "docs/reports/REGULATOR_EXAM_PACK_AI_GOVERNANCE_2026_2030.md", + "audience": "regulator", + "required": true + }, + { + "path": "docs/reports/ENGINEERING_IMPLEMENTATION_PLAYBOOK_AI_GOVERNANCE_2026_2030.md", + "audience": "engineering", + "required": true + } + ] +} diff --git a/docs/schemas/governance_reports_manifest.schema.json b/docs/schemas/governance_reports_manifest.schema.json new file mode 100644 index 0000000..8d266e3 --- /dev/null +++ b/docs/schemas/governance_reports_manifest.schema.json @@ -0,0 +1,31 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://example.org/schemas/governance_reports_manifest.schema.json", + "title": "Governance Reports Manifest", + "type": "object", + "required": ["version", "report_pack", "reports"], + "properties": { + "version": { + "type": "string", + "minLength": 1 + }, + "report_pack": { + "type": "string", + "minLength": 1 + }, + "reports": { + "type": "array", + "items": { + "type": "object", + "required": ["path", "audience", "required"], + "properties": { + "path": {"type": "string", "minLength": 1}, + "audience": {"type": "string", "minLength": 1}, + "required": {"type": "boolean"} + }, + "additionalProperties": false + } + } + }, + "additionalProperties": false +} diff --git a/tool_tests/test_validate_governance_reports.py b/tool_tests/test_validate_governance_reports.py new file mode 100644 index 0000000..ac8fc69 --- /dev/null +++ b/tool_tests/test_validate_governance_reports.py @@ -0,0 +1,346 @@ +import tempfile +import unittest +from pathlib import Path +import json +import subprocess +import sys + +from tools.validate_governance_reports import ( + collect_validation_errors, + validate_file, + validate_manifest, + validate_manifest_schema, + validate_readme_index, +) + + +VALID_DOC = """ +Sample Title For Validation + + +Short abstract text. + + +## Required Heading +Some content here. + +""" + + +def _write_json(path: Path, payload: dict) -> None: + path.write_text(json.dumps(payload, indent=2), encoding="utf-8") + + +class ValidateGovernanceReportsTests(unittest.TestCase): + def test_validate_file_accepts_valid_document(self): + with tempfile.TemporaryDirectory() as tmpdir: + path = Path(tmpdir) / "doc.md" + path.write_text(VALID_DOC, encoding="utf-8") + errors = validate_file(path, ["## Required Heading"]) + self.assertEqual(errors, []) + + def test_validate_file_rejects_missing_tag(self): + with tempfile.TemporaryDirectory() as tmpdir: + path = Path(tmpdir) / "doc.md" + path.write_text("Only title", encoding="utf-8") + errors = validate_file(path, []) + self.assertTrue(any("missing tag " in e for e in errors)) + self.assertTrue(any("missing tag " in e for e in errors)) + + def test_validate_file_rejects_missing_required_heading(self): + with tempfile.TemporaryDirectory() as tmpdir: + path = Path(tmpdir) / "doc.md" + path.write_text(VALID_DOC, encoding="utf-8") + errors = validate_file(path, ["## Heading Not Present"]) + self.assertTrue(any("missing required heading" in e for e in errors)) + + def test_validate_file_rejects_duplicate_title_blocks(self): + with tempfile.TemporaryDirectory() as tmpdir: + path = Path(tmpdir) / "doc.md" + path.write_text( + VALID_DOC + "\n\nAnother title\n\n", + encoding="utf-8", + ) + errors = validate_file(path, ["## Required Heading"]) + self.assertTrue(any("expected exactly one block" in e for e in errors)) + + def test_validate_file_rejects_duplicate_abstract_blocks(self): + with tempfile.TemporaryDirectory() as tmpdir: + path = Path(tmpdir) / "doc.md" + path.write_text( + VALID_DOC + "\n<abstract>\nAnother abstract\n</abstract>\n", + encoding="utf-8", + ) + errors = validate_file(path, ["## Required Heading"]) + self.assertTrue(any("expected exactly one <abstract> block" in e for e in errors)) + + def test_validate_file_rejects_duplicate_content_blocks(self): + with tempfile.TemporaryDirectory() as tmpdir: + path = Path(tmpdir) / "doc.md" + path.write_text( + VALID_DOC + "\n<content>\n## Required Heading\nMore content\n</content>\n", + encoding="utf-8", + ) + errors = validate_file(path, ["## Required Heading"]) + self.assertTrue(any("expected exactly one <content> block" in e for e in errors)) + + def test_validate_file_rejects_missing_file(self): + with tempfile.TemporaryDirectory() as tmpdir: + missing = Path(tmpdir) / "missing.md" + errors = validate_file(missing, []) + self.assertEqual(len(errors), 1) + self.assertIn("missing file", errors[0]) + + def test_validate_readme_index_accepts_valid_readme(self): + with tempfile.TemporaryDirectory() as tmpdir: + path = Path(tmpdir) / "README_GOVERNANCE_REPORTS.md" + path.write_text( + "\n".join( + [ + "INSTITUTIONAL_GRADE_AGI_ASI_GOVERNANCE_2026_2030.md", + "BOARD_BRIEF_AGI_ASI_GOVERNANCE_2026_2030.md", + "REGULATOR_EXAM_PACK_AI_GOVERNANCE_2026_2030.md", + "ENGINEERING_IMPLEMENTATION_PLAYBOOK_AI_GOVERNANCE_2026_2030.md", + "governance_reports_manifest.json", + "governance_reports_manifest.schema.json", + "python3 -m unittest discover tool_tests", + "python3 tools/validate_governance_reports.py", + "make governance-check", + ] + ), + encoding="utf-8", + ) + reports = [ + "docs/reports/INSTITUTIONAL_GRADE_AGI_ASI_GOVERNANCE_2026_2030.md", + "docs/reports/BOARD_BRIEF_AGI_ASI_GOVERNANCE_2026_2030.md", + "docs/reports/REGULATOR_EXAM_PACK_AI_GOVERNANCE_2026_2030.md", + "docs/reports/ENGINEERING_IMPLEMENTATION_PLAYBOOK_AI_GOVERNANCE_2026_2030.md", + ] + errors = validate_readme_index(path, reports) + self.assertEqual(errors, []) + + def test_validate_readme_index_rejects_missing_entries(self): + with tempfile.TemporaryDirectory() as tmpdir: + path = Path(tmpdir) / "README_GOVERNANCE_REPORTS.md" + path.write_text("placeholder", encoding="utf-8") + reports = [ + "docs/reports/INSTITUTIONAL_GRADE_AGI_ASI_GOVERNANCE_2026_2030.md", + ] + errors = validate_readme_index(path, reports) + self.assertTrue(any("missing report reference" in e for e in errors)) + self.assertTrue(any("missing manifest reference" in e for e in errors)) + self.assertTrue(any("missing schema reference" in e for e in errors)) + self.assertTrue(any("missing unit test command" in e for e in errors)) + self.assertTrue(any("missing validator command" in e for e in errors)) + self.assertTrue(any("missing make command 'make governance-check'" in e for e in errors)) + + def test_validate_manifest_accepts_valid_manifest(self): + with tempfile.TemporaryDirectory() as tmpdir: + path = Path(tmpdir) / "governance_reports_manifest.json" + _write_json( + path, + { + "version": "2026.1", + "report_pack": "institutional_agi_asi_governance", + "reports": [ + { + "path": "docs/reports/INSTITUTIONAL_GRADE_AGI_ASI_GOVERNANCE_2026_2030.md", + "audience": "enterprise", + "required": True, + }, + { + "path": "docs/reports/BOARD_BRIEF_AGI_ASI_GOVERNANCE_2026_2030.md", + "audience": "board", + "required": True, + }, + ], + }, + ) + report_paths = [ + "docs/reports/INSTITUTIONAL_GRADE_AGI_ASI_GOVERNANCE_2026_2030.md", + "docs/reports/BOARD_BRIEF_AGI_ASI_GOVERNANCE_2026_2030.md", + ] + errors = validate_manifest(path, report_paths) + self.assertEqual(errors, []) + + def test_validate_manifest_rejects_missing_report_entries(self): + with tempfile.TemporaryDirectory() as tmpdir: + path = Path(tmpdir) / "governance_reports_manifest.json" + _write_json( + path, + { + "version": "2026.1", + "report_pack": "institutional_agi_asi_governance", + "reports": [ + { + "path": "docs/reports/BOARD_BRIEF_AGI_ASI_GOVERNANCE_2026_2030.md", + "audience": "board", + "required": True, + } + ], + }, + ) + report_paths = [ + "docs/reports/INSTITUTIONAL_GRADE_AGI_ASI_GOVERNANCE_2026_2030.md", + "docs/reports/BOARD_BRIEF_AGI_ASI_GOVERNANCE_2026_2030.md", + ] + errors = validate_manifest(path, report_paths) + self.assertTrue(any("missing report entries" in e for e in errors)) + + def test_validate_manifest_rejects_unexpected_entries(self): + with tempfile.TemporaryDirectory() as tmpdir: + path = Path(tmpdir) / "governance_reports_manifest.json" + _write_json( + path, + { + "version": "2026.1", + "report_pack": "institutional_agi_asi_governance", + "reports": [ + { + "path": "docs/reports/INSTITUTIONAL_GRADE_AGI_ASI_GOVERNANCE_2026_2030.md", + "audience": "enterprise", + "required": True, + }, + {"path": "docs/reports/EXTRA.md", "audience": "misc", "required": False}, + ], + }, + ) + report_paths = [ + "docs/reports/INSTITUTIONAL_GRADE_AGI_ASI_GOVERNANCE_2026_2030.md", + ] + errors = validate_manifest(path, report_paths) + self.assertTrue(any("unexpected report entries" in e for e in errors)) + + def test_validate_manifest_rejects_nonexistent_paths(self): + with tempfile.TemporaryDirectory() as tmpdir: + path = Path(tmpdir) / "governance_reports_manifest.json" + _write_json( + path, + { + "version": "2026.1", + "report_pack": "institutional_agi_asi_governance", + "reports": [ + { + "path": "docs/reports/DOES_NOT_EXIST.md", + "audience": "enterprise", + "required": True, + } + ], + }, + ) + report_paths = [ + "docs/reports/DOES_NOT_EXIST.md", + ] + errors = validate_manifest(path, report_paths) + self.assertTrue(any("path does not exist" in e for e in errors)) + + def test_validate_manifest_rejects_missing_metadata_fields(self): + with tempfile.TemporaryDirectory() as tmpdir: + path = Path(tmpdir) / "governance_reports_manifest.json" + _write_json(path, {"reports": []}) + errors = validate_manifest(path, []) + self.assertTrue(any("'version' must be a non-empty string" in e for e in errors)) + self.assertTrue(any("'report_pack' must be a non-empty string" in e for e in errors)) + + def test_validate_manifest_schema_accepts_valid_schema(self): + with tempfile.TemporaryDirectory() as tmpdir: + path = Path(tmpdir) / "schema.json" + path.write_text( + """ +{ + "required": ["version", "report_pack", "reports"], + "properties": { + "reports": { + "items": { + "required": ["path", "audience", "required"] + } + } + } +} +""".strip(), + encoding="utf-8", + ) + errors = validate_manifest_schema(path) + self.assertEqual(errors, []) + + def test_validate_manifest_schema_rejects_missing_required_fields(self): + with tempfile.TemporaryDirectory() as tmpdir: + path = Path(tmpdir) / "schema.json" + path.write_text( + """ +{ + "required": ["version"], + "properties": { + "reports": { + "items": { + "required": ["path"] + } + } + } +} +""".strip(), + encoding="utf-8", + ) + errors = validate_manifest_schema(path) + self.assertTrue(any("schema missing root required fields" in e for e in errors)) + self.assertTrue(any("schema missing report item required fields" in e for e in errors)) + + def test_validate_manifest_uses_schema_required_fields(self): + with tempfile.TemporaryDirectory() as tmpdir: + manifest = Path(tmpdir) / "manifest.json" + schema = Path(tmpdir) / "schema.json" + + _write_json( + manifest, + { + "version": "2026.1", + "report_pack": "pack", + "reports": [ + { + "path": "docs/reports/INSTITUTIONAL_GRADE_AGI_ASI_GOVERNANCE_2026_2030.md", + "audience": "enterprise", + "required": True, + } + ], + }, + ) + _write_json( + schema, + { + "required": ["version", "report_pack", "reports", "owner"], + "properties": { + "reports": { + "items": { + "required": ["path", "audience", "required"] + } + } + }, + }, + ) + + errors = validate_manifest( + manifest, + ["docs/reports/INSTITUTIONAL_GRADE_AGI_ASI_GOVERNANCE_2026_2030.md"], + schema, + ) + self.assertTrue(any("missing required manifest field 'owner'" in e for e in errors)) + + def test_collect_validation_errors_returns_tuple(self): + errors, report_count = collect_validation_errors() + self.assertIsInstance(errors, list) + self.assertIsInstance(report_count, int) + + def test_validator_json_output_mode(self): + result = subprocess.run( + [sys.executable, "tools/validate_governance_reports.py", "--json"], + check=True, + capture_output=True, + text=True, + ) + payload = json.loads(result.stdout.strip()) + self.assertEqual(payload["status"], "passed") + self.assertIn("validated_report_files", payload) + + +if __name__ == "__main__": + unittest.main() diff --git a/tools/validate_governance_reports.py b/tools/validate_governance_reports.py new file mode 100755 index 0000000..e6164e5 --- /dev/null +++ b/tools/validate_governance_reports.py @@ -0,0 +1,302 @@ +#!/usr/bin/env python3 +"""Validate governance report artifacts for required XML-like wrappers and section anchors.""" +from __future__ import annotations + +import argparse +import json +from pathlib import Path +import re + +ROOT = Path(__file__).resolve().parents[1] +README_PATH = ROOT / "docs/reports/README_GOVERNANCE_REPORTS.md" +MANIFEST_PATH = ROOT / "docs/reports/governance_reports_manifest.json" +MANIFEST_SCHEMA_PATH = ROOT / "docs/schemas/governance_reports_manifest.schema.json" + +REPORT_RULES = { + "docs/reports/INSTITUTIONAL_GRADE_AGI_ASI_GOVERNANCE_2026_2030.md": [ + "## 3. Regulatory Alignment Matrix (Control-Centric)", + "## 4. Enterprise AI Reference Architecture (Design + Build)", + "## 5. AGI/ASI Safety and Containment Framework", + "## 9. Implementation Roadmap (2026–2030)", + ], + "docs/reports/BOARD_BRIEF_AGI_ASI_GOVERNANCE_2026_2030.md": [ + "## 1) Board Decisions Required", + "## 2) What the Board Should Review Quarterly", + ], + "docs/reports/REGULATOR_EXAM_PACK_AI_GOVERNANCE_2026_2030.md": [ + "## 1) Examination Packet Index", + "## 2) Required Evidence Tables", + ], + "docs/reports/ENGINEERING_IMPLEMENTATION_PLAYBOOK_AI_GOVERNANCE_2026_2030.md": [ + "## 1) Build Priorities (First 90 Days)", + "## 4) CI/CD Governance Gate Template", + ], +} + +REQUIRED_TAGS = ("<title>", "", "", "", "", "") + + +def validate_file(path: Path, required_headings: list[str]) -> list[str]: + errors: list[str] = [] + if not path.exists(): + return [f"missing file: {path}"] + + text = path.read_text(encoding="utf-8") + + for tag in REQUIRED_TAGS: + if tag not in text: + errors.append(f"{path}: missing tag {tag}") + + if text.count("") != 1 or text.count("") != 1: + errors.append(f"{path}: expected exactly one block") + if text.count("<abstract>") != 1 or text.count("</abstract>") != 1: + errors.append(f"{path}: expected exactly one <abstract> block") + if text.count("<content>") != 1 or text.count("</content>") != 1: + errors.append(f"{path}: expected exactly one <content> block") + + title_match = re.search(r"<title>\s*(.*?)\s*", text, re.DOTALL) + if not title_match or len(title_match.group(1).strip()) < 10: + errors.append(f"{path}: title is empty or too short") + + for heading in required_headings: + if heading not in text: + errors.append(f"{path}: missing required heading '{heading}'") + + return errors + + +def validate_readme_index(path: Path, report_paths: list[str]) -> list[str]: + errors: list[str] = [] + if not path.exists(): + return [f"missing file: {path}"] + + text = path.read_text(encoding="utf-8") + for report_path in report_paths: + name = Path(report_path).name + if name not in text: + errors.append(f"{path}: missing report reference '{name}'") + + if "governance_reports_manifest.json" not in text: + errors.append(f"{path}: missing manifest reference 'governance_reports_manifest.json'") + if "governance_reports_manifest.schema.json" not in text: + errors.append(f"{path}: missing schema reference 'governance_reports_manifest.schema.json'") + + if "python3 -m unittest discover tool_tests" not in text: + errors.append(f"{path}: missing unit test command in validation instructions") + if "python3 tools/validate_governance_reports.py" not in text: + errors.append(f"{path}: missing validator command in validation instructions") + if "make governance-check" not in text: + errors.append(f"{path}: missing make command 'make governance-check' in validation instructions") + + return errors + + +def _schema_required_sets(schema_path: Path) -> tuple[set[str], set[str], list[str]]: + errors: list[str] = [] + try: + schema = json.loads(schema_path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError) as exc: + return set(), set(), [f"{schema_path}: failed to read schema ({exc})"] + + root_required = set(schema.get("required", [])) if isinstance(schema, dict) else set() + item_required: set[str] = set() + if isinstance(schema, dict): + props = schema.get("properties", {}) + reports_prop = props.get("reports", {}) if isinstance(props, dict) else {} + items = reports_prop.get("items", {}) if isinstance(reports_prop, dict) else {} + if isinstance(items, dict): + item_required = set(items.get("required", [])) + + if not root_required: + errors.append(f"{schema_path}: could not determine root required fields") + if not item_required: + errors.append(f"{schema_path}: could not determine report item required fields") + + return root_required, item_required, errors + + +def validate_manifest(path: Path, report_paths: list[str], schema_path: Path | None = None) -> list[str]: + errors: list[str] = [] + if not path.exists(): + return [f"missing file: {path}"] + + try: + data = json.loads(path.read_text(encoding="utf-8")) + except json.JSONDecodeError as exc: + return [f"{path}: invalid JSON ({exc})"] + + if not isinstance(data, dict): + return [f"{path}: manifest root must be an object"] + + root_required = {"version", "report_pack", "reports"} + item_required = {"path", "audience", "required"} + if schema_path is not None and schema_path.exists(): + schema_root_required, schema_item_required, schema_errors = _schema_required_sets(schema_path) + errors.extend(schema_errors) + if schema_root_required: + root_required = schema_root_required + if schema_item_required: + item_required = schema_item_required + + for field in sorted(root_required): + if field not in data: + errors.append(f"{path}: missing required manifest field '{field}'") + + version = data.get("version") + if "version" in root_required and (not isinstance(version, str) or not version.strip()): + errors.append(f"{path}: 'version' must be a non-empty string") + + report_pack = data.get("report_pack") + if "report_pack" in root_required and (not isinstance(report_pack, str) or not report_pack.strip()): + errors.append(f"{path}: 'report_pack' must be a non-empty string") + + reports = data.get("reports") + if not isinstance(reports, list): + return [f"{path}: 'reports' must be a list"] + + manifest_paths: set[str] = set() + for idx, report in enumerate(reports): + if not isinstance(report, dict): + errors.append(f"{path}: reports[{idx}] must be an object") + continue + for field in sorted(item_required): + if field not in report: + errors.append(f"{path}: reports[{idx}] missing required field '{field}'") + + report_path = report.get("path") + audience = report.get("audience") + required = report.get("required") + if not isinstance(report_path, str): + errors.append(f"{path}: reports[{idx}].path must be a string") + else: + manifest_paths.add(report_path) + abs_report_path = ROOT / report_path + if not abs_report_path.exists(): + errors.append(f"{path}: reports[{idx}].path does not exist ({report_path})") + if not isinstance(audience, str): + errors.append(f"{path}: reports[{idx}].audience must be a string") + if not isinstance(required, bool): + errors.append(f"{path}: reports[{idx}].required must be a boolean") + + missing = set(report_paths) - manifest_paths + if missing: + errors.append(f"{path}: missing report entries {sorted(missing)}") + unexpected = manifest_paths - set(report_paths) + if unexpected: + errors.append(f"{path}: unexpected report entries {sorted(unexpected)}") + + return errors + + +def validate_manifest_schema(path: Path) -> list[str]: + errors: list[str] = [] + if not path.exists(): + return [f"missing file: {path}"] + + try: + schema = json.loads(path.read_text(encoding="utf-8")) + except json.JSONDecodeError as exc: + return [f"{path}: invalid JSON ({exc})"] + + if not isinstance(schema, dict): + return [f"{path}: schema root must be an object"] + + required = schema.get("required") + if not isinstance(required, list): + return [f"{path}: schema 'required' must be a list"] + + expected_root_required = {"version", "report_pack", "reports"} + missing_root_required = expected_root_required - set(required) + if missing_root_required: + errors.append( + f"{path}: schema missing root required fields {sorted(missing_root_required)}" + ) + + props = schema.get("properties") + if not isinstance(props, dict): + return [f"{path}: schema 'properties' must be an object"] + + reports_prop = props.get("reports") + if not isinstance(reports_prop, dict): + return [f"{path}: schema missing 'reports' property definition"] + + items = reports_prop.get("items") + if not isinstance(items, dict): + return [f"{path}: schema 'reports.items' must be an object"] + + item_required = items.get("required") + if not isinstance(item_required, list): + return [f"{path}: schema 'reports.items.required' must be a list"] + + expected_item_required = {"path", "audience", "required"} + missing_item_required = expected_item_required - set(item_required) + if missing_item_required: + errors.append( + f"{path}: schema missing report item required fields {sorted(missing_item_required)}" + ) + + return errors + + +def collect_validation_errors() -> tuple[list[str], int]: + all_errors: list[str] = [] + report_count = 0 + for rel_path, headings in REPORT_RULES.items(): + all_errors.extend(validate_file(ROOT / rel_path, headings)) + report_count += 1 + all_errors.extend(validate_readme_index(README_PATH, list(REPORT_RULES.keys()))) + all_errors.extend(validate_manifest(MANIFEST_PATH, list(REPORT_RULES.keys()), MANIFEST_SCHEMA_PATH)) + all_errors.extend(validate_manifest_schema(MANIFEST_SCHEMA_PATH)) + return all_errors, report_count + + +def main() -> int: + parser = argparse.ArgumentParser(description="Validate governance report pack artifacts.") + parser.add_argument( + "--json", + action="store_true", + help="Print machine-readable JSON output.", + ) + args = parser.parse_args() + + all_errors, report_count = collect_validation_errors() + + if all_errors: + if args.json: + print( + json.dumps( + { + "status": "failed", + "error_count": len(all_errors), + "errors": all_errors, + } + ) + ) + else: + print("Governance report validation failed:") + for err in all_errors: + print(f"- {err}") + return 1 + + if args.json: + print( + json.dumps( + { + "status": "passed", + "validated_report_files": report_count, + "validated_index_files": 1, + "validated_manifest_files": 1, + "validated_schema_files": 1, + } + ) + ) + else: + print("Governance report validation passed.") + print( + f"Validated {report_count} report files, 1 report index README, 1 manifest, and 1 schema." + ) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main())