From 01313cd7b2b2c46eeb835bc2f800bfbd18240be4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9D=90=8E=F0=9D=90=A7=F0=9D=90=9E=20=F0=9D=90=85?= =?UTF-8?q?=F0=9D=90=A2=F0=9D=90=A7=F0=9D=90=9E=20=F0=9D=90=92=F0=9D=90=AD?= =?UTF-8?q?=F0=9D=90=9A=F0=9D=90=AB=F0=9D=90=AC=F0=9D=90=AD=F0=9D=90=AE?= =?UTF-8?q?=F0=9D=90=9F=F0=9D=90=9F?= Date: Mon, 27 Apr 2026 12:52:58 +0630 Subject: [PATCH] Refresh artifact manifest timestamp after validation runner updates --- .github/workflows/governance-artifacts-ci.yml | 44 ++ .pre-commit-config.yaml | 9 + ..._AGI_ASI_GOVERNANCE_BLUEPRINT_2026_2030.md | 703 ++++++++++++++++++ Makefile | 43 ++ governance_blueprint/artifact_manifest.json | 18 + .../control_mapping_matrix.csv | 8 + .../evidence_event_schema.json | 46 ++ governance_blueprint/opa/release_gate.rego | 40 + governance_blueprint/roadmap_2026_2030.yaml | 50 ++ governance_blueprint/validation/README.md | 134 ++++ .../validation/generate_artifact_manifest.py | 100 +++ .../validation/lint_python_sources.py | 32 + .../validation/run_validation_suite.py | 148 ++++ .../selftest_run_validation_suite.py | 180 +++++ .../validation/selftest_validate_artifacts.py | 175 +++++ .../validation/validate_artifacts.py | 230 ++++++ .../validation/validate_dashboard_links.py | 49 ++ ...terprise-agi-asi-governance-blueprint.html | 80 ++ .../public/whitepaper-suite.html | 13 + 19 files changed, 2102 insertions(+) create mode 100644 .github/workflows/governance-artifacts-ci.yml create mode 100644 .pre-commit-config.yaml create mode 100644 ENTERPRISE_AGI_ASI_GOVERNANCE_BLUEPRINT_2026_2030.md create mode 100644 Makefile create mode 100644 governance_blueprint/artifact_manifest.json create mode 100644 governance_blueprint/control_mapping_matrix.csv create mode 100644 governance_blueprint/evidence_event_schema.json create mode 100644 governance_blueprint/opa/release_gate.rego create mode 100644 governance_blueprint/roadmap_2026_2030.yaml create mode 100644 governance_blueprint/validation/README.md create mode 100644 governance_blueprint/validation/generate_artifact_manifest.py create mode 100644 governance_blueprint/validation/lint_python_sources.py create mode 100644 governance_blueprint/validation/run_validation_suite.py create mode 100644 governance_blueprint/validation/selftest_run_validation_suite.py create mode 100644 governance_blueprint/validation/selftest_validate_artifacts.py create mode 100644 governance_blueprint/validation/validate_artifacts.py create mode 100644 governance_blueprint/validation/validate_dashboard_links.py create mode 100644 rag-agentic-dashboard/public/enterprise-agi-asi-governance-blueprint.html diff --git a/.github/workflows/governance-artifacts-ci.yml b/.github/workflows/governance-artifacts-ci.yml new file mode 100644 index 0000000..efc9f79 --- /dev/null +++ b/.github/workflows/governance-artifacts-ci.yml @@ -0,0 +1,44 @@ +name: Governance Artifacts CI + +on: + pull_request: + paths: + - 'ENTERPRISE_AGI_ASI_GOVERNANCE_BLUEPRINT_2026_2030.md' + - 'governance_blueprint/**' + - '.github/workflows/governance-artifacts-ci.yml' + push: + branches: [ main, master ] + paths: + - 'ENTERPRISE_AGI_ASI_GOVERNANCE_BLUEPRINT_2026_2030.md' + - 'governance_blueprint/**' + - '.github/workflows/governance-artifacts-ci.yml' + +jobs: + validate-governance-artifacts: + runs-on: ubuntu-latest + timeout-minutes: 10 + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Run governance validation suite + run: python3 governance_blueprint/validation/run_validation_suite.py --quiet --json-report governance-artifact-validation-report.json --suite-report governance-validation-suite-report.json + + - name: Show validation report + run: | + cat governance-artifact-validation-report.json + cat governance-validation-suite-report.json + + - name: Upload validation report + uses: actions/upload-artifact@v4 + with: + name: governance-validation-reports + path: | + governance-artifact-validation-report.json + governance-validation-suite-report.json diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..6129078 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,9 @@ +repos: + - repo: local + hooks: + - id: governance-validation-suite + name: governance validation suite + entry: python3 governance_blueprint/validation/run_validation_suite.py --skip-selftest --quiet + language: system + pass_filenames: false + files: '^(governance_blueprint/|ENTERPRISE_AGI_ASI_GOVERNANCE_BLUEPRINT_2026_2030\.md)' diff --git a/ENTERPRISE_AGI_ASI_GOVERNANCE_BLUEPRINT_2026_2030.md b/ENTERPRISE_AGI_ASI_GOVERNANCE_BLUEPRINT_2026_2030.md new file mode 100644 index 0000000..3fe945e --- /dev/null +++ b/ENTERPRISE_AGI_ASI_GOVERNANCE_BLUEPRINT_2026_2030.md @@ -0,0 +1,703 @@ +# Enterprise AGI/ASI Governance Master Reference and Implementation Blueprint (2026–2030) + +**Audience:** C-suite, Board Risk Committees, regulators/supervisors, enterprise architects, AI platform engineers, model risk teams, AI safety researchers. +**Scope:** Fortune 500, Global 2000, and G-SIFI financial institutions operating across US, UK, EU, APAC. + +--- + +## 0) Executive brief + +This blueprint provides a regulator-ready operating model for advanced AI (including frontier model usage and potential AGI/ASI-adjacent capabilities) anchored to: + +- **EU AI Act implementation windows** (GPAI obligations from **2 Aug 2025**, broad application from **2 Aug 2026**). +- **NIST AI RMF 1.0** and operational playbooks. +- **ISO/IEC 42001 AI management systems** as certifiable management-system backbone. +- **Financial-services model risk and prudential expectations** (SR 11-7, Basel-aligned governance, PRA/FCA, MAS, HKMA). + +It combines policy, technology, assurance, and response engineering in one reference architecture: + +1. **Three-lines-of-defense AI governance with Board accountability**. +2. **Compliance-as-code** (OPA policies + SDLC gates + immutable evidence). +3. **Model risk lifecycle controls** (inventory, validation, drift, challenge, usage restrictions). +4. **AGI/ASI safety controls** (capability thresholds, staged release, containment, kill-switches, compute governance). +5. **2026–2030 phased implementation and resource plan**. + +--- + +## 1) Regulatory and standards crosswalk (practical, regulator-ready) + +> **Date clarity (as of March 26, 2026):** +> - EU AI Act: obligations already partially active (e.g., prohibited practices and GPAI-related timelines), with major high-risk obligations broadly applying in 2026. +> - NIST AI RMF 1.0 remains foundational and is being evolved operationally through companion resources. +> - US EO 14110 was issued on Oct 30, 2023 and later rescinded on Jan 20, 2025; organizations should treat it as a historical policy driver and map current obligations to active agency/regulator requirements. + +### 1.1 Core frameworks and what they control + +- **EU AI Act (High-Risk + GPAI)** + - Risk classification, provider/deployer obligations, technical documentation, human oversight, logging, transparency, post-market monitoring, incident reporting. + - For banks/insurers/market infrastructure: materially relevant for creditworthiness, fraud, AML, identity, HR screening, customer communications, and GPAI-enabled decision support. + +- **NIST AI RMF 1.0** + - Four functions: **Govern, Map, Measure, Manage**. + - Use as common control language across legal, risk, engineering, and internal audit. + +- **ISO/IEC 42001** + - AI management system (AIMS): policy, roles, controls, objectives, internal audit, continual improvement. + - Use to institutionalize governance operating rhythm and external assurance. + +- **OECD AI Principles** + - Values-based baseline: robustness, transparency, accountability, human-centered outcomes. + +- **Data/privacy and conduct regimes** + - **GDPR** (lawfulness, purpose limitation, data minimization, rights, DPIA, transfers). + - **FCRA/ECOA** (US consumer lending fairness/adverse action explainability). + - **Consumer Duty (UK)** and analogous fair outcomes obligations. + +- **Prudential/model risk supervision** + - **SR 11-7** model risk management discipline. + - **Basel III** governance, capital and operational risk interaction. + - **PRA/FCA, MAS, HKMA** expectations on model governance, outsourcing, operational resilience, and accountable senior management (incl. **SMCR** in UK). + +### 1.2 Enterprise control objective taxonomy + +Create a unified control catalog with 12 control families: + +1. Governance & accountability +2. AI system inventory & tiering +3. Data governance & lineage +4. Development controls & secure SDLC +5. Validation & independent challenge +6. Explainability & human oversight +7. Fairness/non-discrimination & consumer protection +8. Logging, monitoring, and incident response +9. Third-party/outsourcing and GPAI supplier controls +10. Cybersecurity & resilience +11. Change/release management and kill-switch controls +12. Documentation, records, and regulatory reporting + +Each family maps to legal articles/sections, internal policy IDs, technical controls, test procedures, evidence artifacts, and accountable role (RACI). + +--- + +## 2) Target governance operating model (Board to runtime) + +### 2.1 Board and executive structure + +- **Board Risk Committee / Technology Committee** + - Approves AI risk appetite and annual AI assurance plan. + - Receives quarterly reports: high-risk inventory, material incidents, concentration risks (vendors/models), and unresolved exceptions. + +- **Executive AI Governance Council (EAGC)** + - Chaired by CRO/CAIO with CISO, CIO/CTO, CDO, General Counsel, Compliance, Internal Audit observer, and business heads. + - Decision rights: model tiering, production approvals for high-risk AI, exception waivers, emergency shutdown authority. + +- **Three Lines of Defense** + - **1LOD**: Product/engineering owns controls in design and operations. + - **2LOD**: Risk/compliance sets policy and challenges controls. + - **3LOD**: Internal Audit tests design/operating effectiveness. + +### 2.2 Role clarity for regulated FS institutions + +- **Model Owner**: business accountability and usage boundaries. +- **Model Validator**: independent testing (performance, stability, bias, explainability, stress). +- **Data Owner/Steward**: lawful basis, quality, lineage, retention. +- **AI Safety Officer**: frontier-capability oversight, containment protocols. +- **SMF/Accountable Executive (UK)**: explicit statement of responsibilities for AI governance outcomes. + +### 2.3 AI risk tiering (enterprise standard) + +- **Tier 0**: Non-material productivity AI (low impact). +- **Tier 1**: Customer-influencing, non-decisional. +- **Tier 2**: Material operational or financial impact. +- **Tier 3 (High-Risk)**: Rights/safety/credit/access impacts, prudential impact, regulatory materiality. +- **Tier 4 (Frontier/GPAI/Systemic)**: advanced capabilities with broad emergent risk or high compute dependency. + +Tier drives minimum controls, approvers, testing depth, and monitoring intensity. + +--- + +## 3) Enterprise reference architecture (regulator-ready) + +### 3.1 Logical architecture layers + +1. **Engagement layer** + - Channels/apps, including **Next.js explainability frontends** for model cards, rationale views, adverse action explanation workflows, override capture. + +2. **Decision & orchestration layer** + - Business services invoking models through policy-enforced gateways. + +3. **AI runtime layer** + - Traditional ML + LLM/GPAI services with model registry and feature/prompt pipelines. + +4. **Governance control plane** + - **OPA policy engine** (pre-deploy and runtime checks). + - Governance sidecars in **Node.js/Python** for telemetry, policy attestations, and evidence bundling. + +5. **Evidence and audit layer** + - **Kafka-based immutable audit streams** with retention controls and downstream WORM storage. + - Cryptographic integrity checks, tamper-evident hashes, signed attestations. + +6. **Platform/security layer** + - Container orchestration (including hardened **Docker Swarm** clusters where used), secrets management, IAM, KMS/HSM, network segmentation. + +7. **Automation layer** + - **Terraform + CI/CD governance automation** with policy gates, segregation of duties, break-glass controls, and full deployment provenance. + +### 3.2 Minimum technical controls by pipeline stage + +- **Build-time** + - Dependency and SBOM scanning, provenance (SLSA-aligned), secrets scanning, policy linting. +- **Pre-deploy** + - Mandatory risk tier metadata, validator sign-off for Tier 3+, fairness and robustness thresholds. +- **Deploy-time** + - OPA admission controls, signed artifacts only, environment policy matching. +- **Runtime** + - Drift, performance, bias, abuse, prompt-injection/jailbreak telemetry; automatic fallback and throttling. +- **Post-incident** + - Forensic replay from immutable logs; regulator report packs generated from evidence graph. + +### 3.3 Evidence architecture details (Kafka + WORM) + +- Event classes: model registration, data version, approval decisions, inference metadata, override actions, user notices, incident events. +- Integrity pattern: + - Append-only Kafka topics with strict ACLs. + - Periodic hash-chaining and notarized checkpoints. + - Export to WORM-capable storage (retention/legal hold aligned to jurisdictional rules). +- Access governance: + - RBAC + ABAC + purpose binding. + - Dual-control for deletion/legal hold release. + - Quarterly entitlement recertification. + +--- + +## 4) Compliance-as-code and policy automation + +### 4.1 OPA policy domain model + +Implement policy bundles for: + +- Risk tiering and mandatory controls. +- GDPR lawful basis checks and data minimization constraints. +- FCRA/ECOA explanation/notice conditions for lending decisions. +- SR 11-7 model validation prerequisites. +- Geographic controls (EU/UK/APAC residency and transfer restrictions). +- Vendor/GPAI contract clauses and assurance artifacts. + +### 4.2 CI/CD governance blueprint + +- **Pull request gates**: policy unit tests, control completeness score, architecture decision record requirement. +- **Release gates**: validator attestation for Tier 3/4, legal/compliance approval for use-case scope expansion. +- **Production gates**: runtime guardrail policy hash must equal approved baseline. +- **Continuous controls monitoring**: daily policy drift scans with exception SLAs. + +### 4.3 “Control as product” operating model + +- Assign product owners to each control family. +- Publish versioned control APIs and SDKs. +- Track control adoption and override rates as key platform metrics. + +--- + +## 5) Financial services model risk management specialization + +### 5.1 SR 11-7 aligned lifecycle for AI/GenAI + +1. **Model definition and intended use** (explicit prohibited uses). +2. **Data suitability and representativeness testing**. +3. **Conceptual soundness review** (including prompt/process architecture). +4. **Outcomes analysis** (accuracy, calibration, fairness, stability). +5. **Ongoing monitoring** with challenger models and periodic revalidation. +6. **Change governance** for model updates, prompt changes, and dependency changes. + +### 5.2 High-sensitivity FS use cases and required safeguards + +- **Credit underwriting / line management** + - Adverse action reason mapping, proxy discrimination testing, reason-code traceability. +- **Fraud and AML alerting** + - Explainable alert prioritization, false-positive governance, escalation to human investigators. +- **Treasury and liquidity forecasting** + - Stress scenarios, model overlays, conservative fallback in uncertainty spikes. +- **Customer communications** + - Hallucination controls, approved knowledge bases, compliance phrase libraries. + +### 5.3 Independent challenge and model committees + +- Monthly Model Risk Committee for Tier 3/4. +- Mandatory challenger evidence before major threshold changes. +- Sunset criteria for stale or underperforming models. + +--- + +## 6) AGI/ASI safety and containment protocols + +### 6.1 Capability threshold framework + +Define internal capability levels (C1–C5) across autonomy, code-generation potency, cyber capability, persuasion/social engineering potential, and self-improvement indicators. + +- **C1–C2**: standard enterprise controls. +- **C3**: enhanced red teaming, stricter human-in-the-loop, restricted tool access. +- **C4**: containment enclave, dual-key approvals, external expert review. +- **C5**: executive + Board escalation, deployment moratorium pending safety case. + +### 6.2 Containment architecture + +- Isolated execution environments (network egress controls, tool whitelists). +- Strict permission brokering for code execution and external actions. +- Runtime tripwires (policy violation, anomalous autonomy, data exfil signals). +- Immediate revocation pathways (credential kill, model endpoint quarantine). + +### 6.3 Safety assurance practices + +- Pre-release adversarial evaluation and capability audits. +- External red-team partnerships for frontier systems. +- Harm modeling for misuse scenarios (fraud acceleration, cyber abuse, market manipulation, disinformation). +- Documented safety case with sign-offs by AI Safety Officer, CISO, CRO, and Legal. + +--- + +## 7) Global AI and compute governance + +### 7.1 Compute governance + +- Inventory and classify AI compute assets (on-prem, cloud, accelerated clusters). +- Attribute compute consumption to approved use cases and model IDs. +- Enforce compute quotas by tier and risk class. +- Monitor concentration risk (single cloud/vendor/model dependence). + +### 7.2 Data and model sovereignty + +- Regionalized deployments for data residency constraints. +- Controlled cross-border transfer workflows and transfer impact assessments. +- Model artifact location controls and cryptographic attestation of residency. + +### 7.3 Third-party and GPAI supplier governance + +- Contractual controls: audit rights, incident notification SLAs, model update/change notification, safety documentation delivery. +- Supplier scorecards: security posture, legal compliance, transparency maturity, resilience. +- Exit strategy: portability plans and emergency substitution playbooks. + +--- + +## 8) Platform implementation specifications + +> The names below are implemented as enterprise capability domains. If your organization already has similarly named products, map by capability rather than brand. + +### 8.1 Sentinel AI Governance Platform v2.4 + +**Purpose:** central governance control plane. + +- Policy registry (OPA bundles, legal mappings, risk thresholds). +- AI system inventory + tiering workflow. +- Approval orchestration and exception management. +- Evidence graph linking artifacts, approvals, runtime telemetry, incidents. +- Regulator report generation packs (EU AI Act technical docs, SR 11-7 evidence excerpts, DPIA links). + +### 8.2 WorkflowAI Pro + +**Purpose:** controlled AI workflow automation. + +- Human-in-the-loop task routing by risk tier. +- Role-based approval checkpoints. +- Full action traceability and replay. +- Override reason capture with mandatory rationale taxonomy. + +### 8.3 EAIP (Enterprise AI Integration Plane) + +**Purpose:** standardized runtime integration for models/tools. + +- Model gateway with policy enforcement and token/data guardrails. +- Prompt/template registry with approved variants. +- Tool-use broker with least privilege and runtime attestations. +- Multi-model routing with resilience/fallback profiles. + +### 8.4 Enterprise AI Governance Hub + +**Purpose:** governance UX and executive intelligence layer. + +- Board and regulator dashboards. +- Risk heatmaps (by business unit, jurisdiction, model family). +- Control effectiveness KPIs and KRIs. +- Incident command center views and postmortem knowledge base. + +--- + +## 9) Phased roadmap (2026–2030) + +### Phase 1 — Foundation (Q2 2026 to Q4 2026) + +- Establish unified AI policy framework and control taxonomy. +- Complete enterprise AI inventory and tiering baseline. +- Deploy minimum compliance-as-code in CI/CD. +- Stand up immutable logging and evidence retention baseline. +- Launch regulator engagement pack and supervisory briefing cycle. + +**Exit criteria:** +- 100% production AI systems inventoried and tiered. +- Tier 3+ models have independent validation and monitoring. +- Board-approved AI risk appetite in force. + +### Phase 2 — Industrialization (2027) + +- Scale control automation across all material business lines. +- Implement supplier/GPAI assurance program and concentration dashboards. +- Deploy standardized explainability UX for regulated decisions. +- Add incident simulation exercises with regulators (tabletop). + +**Exit criteria:** +- >90% policy controls continuously monitored. +- Mean time to evidence pack (regulator request) < 72 hours. +- Documented AI incident playbooks tested at least twice annually. + +### Phase 3 — Advanced assurance (2028) + +- Integrate frontier capability thresholding and containment controls. +- Introduce quantitative model risk capital overlays where relevant. +- External assurance reviews against ISO/IEC 42001 and sector obligations. + +**Exit criteria:** +- Tier 4 systems subject to safety case approval. +- End-to-end control testing demonstrates reproducible compliance evidence. + +### Phase 4 — Resilience and strategic advantage (2029–2030) + +- Continuous adaptive governance (policy auto-tuning with human approval). +- Cross-border supervisory interoperability and shared evidence schemas. +- Mature scenario planning for AGI-discontinuity events. + +**Exit criteria:** +- Enterprise can safely scale advanced AI with stable audit/regulatory outcomes. +- Governance cost-per-model decreases while control efficacy improves. + +--- + +## 10) Resource plan (illustrative for large FS enterprise) + +### 10.1 Core team sizing (steady-state target) + +- AI Governance Office: 15–30 FTE +- Model Risk (AI/GenAI-specialized): 25–60 FTE +- AI Safety/Red Team: 10–25 FTE +- Platform Engineering (governance controls): 30–80 FTE +- Legal/Compliance Privacy specialists: 15–35 FTE +- Internal Audit AI assurance: 8–20 FTE + +### 10.2 Budget structure (indicative bands) + +- Year 1 foundation uplift: policy + platform + controls + validation uplift. +- Year 2–3: automation expansion and supplier assurance. +- Year 4–5: frontier safety, advanced resilience, supervisory interoperability. + +Track by capability value stream rather than only cost center: +- Compliance readiness +- Model risk loss avoidance +- Operational efficiency +- Customer trust and conduct outcomes + +### 10.3 Skills and training + +- Role-specific curricula for executives, model owners, validators, engineers, and investigators. +- Mandatory annual certification for high-risk AI roles. +- Incident command and red-team drills semi-annually. + +--- + +## 11) KPI/KRI framework for Board and regulators + +### Key performance indicators (KPIs) + +- % AI systems inventoried and tiered. +- % Tier 3/4 models with current independent validation. +- Policy automation coverage in SDLC and runtime. +- Mean lead time from model change request to compliant release. +- % decisions with usable explanations delivered within SLA. + +### Key risk indicators (KRIs) + +- Unapproved model or prompt changes detected. +- Fairness threshold breaches by segment. +- Drift beyond tolerance windows. +- Supplier concentration and critical dependency scores. +- Incident severity rate and time-to-containment. + +--- + +## 12) Regulator engagement and assurance playbook + +1. **Supervisory narrative**: explain governance design, risk appetite, accountability chain. +2. **Evidence walk-through**: show immutable logs, approvals, validation artifacts, issue remediation. +3. **Outcome testing**: demonstrate fairness/explainability/robustness on recent production data slices. +4. **Incident readiness**: prove command structure, notification timelines, and lessons-learned loop. +5. **Forward plan**: provide roadmap, milestones, and residual-risk treatment. + +Prepare jurisdiction-specific annexes (EU, US, UK, SG, HK) with local citations and accountable owners. + +--- + +## 13) 12-month implementation checklist (quick start) + +- Approve enterprise AI risk appetite and governance charter. +- Complete AI inventory, tiering, and criticality mapping. +- Implement OPA policy baseline for release gates. +- Deploy Kafka immutable logging + WORM retention flow. +- Establish Tier 3/4 model committee and independent challenge cadence. +- Deploy explainability portal for customer-impacting decisions. +- Build supplier/GPAI assurance framework and contract templates. +- Run first enterprise AI incident simulation. +- Deliver Board dashboard and regulator-ready evidence packs. +- Launch AI safety thresholding pilot for frontier-capability systems. + +--- + +## 14) Reference implementation principles (non-negotiables) + +1. **No high-risk AI in production without independent validation.** +2. **No model change without traceable approval and rollback path.** +3. **No decisioning AI without auditable explanation and human override.** +4. **No frontier-capability deployment without containment and safety case.** +5. **No third-party GPAI dependency without contractual auditability and exit plan.** + +--- + +## 15) Concluding guidance + +Treat AI governance as an **operating system**, not a policy document. The institutions that succeed from 2026–2030 will unify legal interpretation, engineering controls, model risk discipline, and safety science into a single execution fabric with provable evidence. + +This blueprint is intentionally implementation-oriented: if adopted with disciplined change management, it enables both supervisory confidence and faster, safer AI scale. + +--- + +## 16) Regulator-ready control mapping matrix (starter) + +| Control Family | Example Internal Control ID | EU AI Act | NIST AI RMF | ISO/IEC 42001 | FS Regulatory Anchor | Evidence Artifact | +|---|---|---|---|---|---|---| +| Governance & accountability | AIGOV-01 | Governance, accountability obligations | Govern | Clauses on leadership/planning/support | SR 11-7 governance, SMCR accountability | Board minutes, RACI, charter | +| Inventory & tiering | AIGOV-02 | Risk classification, high-risk scoping | Map | Context/risk assessment controls | PRA/FCA model inventory expectations | Inventory export, tier decision logs | +| Data governance | AIGOV-03 | Logging/traceability, data governance dependencies | Map/Measure | Data and operational controls | GDPR, MAS/HKMA data controls | Data lineage graph, DPIA/TIA records | +| Validation/challenge | AIGOV-04 | Conformity/performance support artifacts | Measure/Manage | Performance monitoring and evaluation | SR 11-7 independent validation | Validation reports, challenger results | +| Explainability/oversight | AIGOV-05 | Human oversight and transparency | Govern/Manage | Operational controls for human oversight | FCRA/ECOA, Consumer Duty | Explanation logs, override audit | +| Monitoring/incident response | AIGOV-06 | Post-market monitoring, serious incident handling | Measure/Manage | Improvement and incident handling | Operational resilience expectations | Incident tickets, containment timeline | +| Third-party/GPAI | AIGOV-07 | GPAI and provider/deployer dependency controls | Govern/Map | External provider controls | Outsourcing and third-party risk rules | Contract clauses, supplier scorecards | + +**Implementation note:** treat this as a starting matrix and extend to full article/section-level mappings for each jurisdictional annex. + +--- + +## 17) Reference technical implementation patterns + +### 17.1 Kafka + WORM evidence pipeline (minimum secure configuration) + +- Dedicated cluster or logically isolated tenant for governance logs. +- Topic strategy: + - `aigov.model_registry.events` + - `aigov.validation.decisions` + - `aigov.runtime.inference.meta` + - `aigov.override.actions` + - `aigov.incident.timeline` +- Security baseline: + - mTLS between producers/consumers and brokers. + - ACLs by service identity and least privilege. + - Envelope encryption for sensitive payload fields. +- Immutability pattern: + - No compact/delete policy for core evidence topics. + - Daily Merkle root of topic offsets + payload hashes. + - Signed digest escrow and periodic export to WORM object store. + +### 17.2 OPA compliance-as-code gate example (policy intent) + +```rego +package aigov.release + +default allow = false + +allow { + input.tier <= 2 + input.model_card_exists + input.security_scan_passed +} + +allow { + input.tier >= 3 + input.model_card_exists + input.security_scan_passed + input.independent_validation_approved + input.legal_compliance_approved + input.explainability_test_passed +} +``` + +### 17.3 Governance sidecar contract (Node.js/Python services) + +Each AI-serving workload should emit a normalized evidence envelope: + +- `model_id`, `model_version`, `prompt_template_id` (if applicable) +- `risk_tier`, `decision_context`, `policy_bundle_hash` +- `input_data_contract_version`, `explanation_reference` +- `human_override_flag`, `override_reason_code` +- `latency_ms`, `confidence`, `safety_filter_events` +- `trace_id`, `request_id`, `jurisdiction_code`, `timestamp_utc` + +### 17.4 Terraform and CI/CD governance controls + +- Enforce policy checks in plan/apply pipelines (deny drift from approved baseline tags). +- Require signed module versions from trusted registries. +- Bind environment deployment rights to segregated IAM roles. +- Record all approvals and pipeline metadata into the evidence stream. + +--- + +## 18) Financial services scenario packs (implementation detail) + +### 18.1 Credit underwriting scenario pack + +- Pre-decision checks: + - data recency and completeness controls, + - prohibited-feature proxy screening, + - fairness threshold checks by protected segments (jurisdiction-appropriate). +- Decision-time controls: + - adverse-action reason code determinism, + - explanation generation with plain-language rendering, + - mandatory human review for boundary-score ranges. +- Post-decision monitoring: + - approval/decline distribution drift, + - adverse impact trend analysis, + - customer complaint correlation analysis. + +### 18.2 Fraud/AML scenario pack + +- Alert model transparency scorecards. +- Analyst feedback loop to reduce false positives and detect automation bias. +- Rule-model hybrid fallback when model confidence degrades. +- Governance on suspicious activity narrative generation (factuality controls). + +### 18.3 Treasury/market risk support scenario pack + +- Stress and reverse-stress testing for forecasting AI. +- Hard limits: AI recommendations cannot auto-execute high-impact market actions without human authorization. +- Real-time anomaly monitors for regime shifts. + +--- + +## 19) AGI/ASI readiness protocol (enterprise safety case template) + +### 19.1 Safety case minimum sections + +1. System boundary and intended capability envelope. +2. Hazard analysis and misuse threat model. +3. Control claims (preventive/detective/corrective) and test evidence. +4. Residual risk statement and acceptance authority. +5. Monitoring triggers and rollback/kill criteria. +6. External review summary (for Tier 4/C4+ systems). + +### 19.2 Escalation triggers for potential frontier discontinuity + +Escalate immediately to executive crisis governance when any of the following are observed: + +- sustained autonomous multi-step planning beyond approved scope, +- successful circumvention of policy guardrails during internal red team, +- emergent high-impact cyber capability indicators, +- repeated unsafe behavior despite policy hardening. + +--- + +## 20) Jurisdictional annex structure (for legal/compliance teams) + +Create annexes per operating region using a common template: + +- **Annex EU:** AI Act obligations by role (provider/deployer/importer/distributor), GDPR links. +- **Annex US:** federal/state consumer and sector obligations, OCC/FRB/FDIC expectations, model risk anchors. +- **Annex UK:** PRA/FCA + Consumer Duty + SMCR responsibility mapping. +- **Annex SG/HK:** MAS/HKMA governance expectations and outsourcing/operational resilience dependencies. + +Each annex should include: +- legal citation, +- internal policy mapping, +- control owner, +- required evidence, +- regulatory reporting path, +- breach/incident notification timeline. + +--- + +## 21) Implementation PMO structure and milestone governance + +### 21.1 Program governance cadence + +- Weekly control implementation stand-up (engineering + risk + compliance). +- Monthly AI Governance Council deep-dive (exceptions and KPI/KRI movement). +- Quarterly Board reporting and risk appetite reaffirmation. + +### 21.2 Milestone quality gates + +- **Gate A (Design):** controls mapped, RACI complete, architecture approved. +- **Gate B (Build):** policy-as-code tests pass, evidence pipeline active, docs complete. +- **Gate C (Run):** monitoring/KRIs stable for 60 days, incident drills complete. +- **Gate D (Scale):** independent assurance confirms operating effectiveness. + +--- + +## 22) Deliverables checklist for first supervisory review cycle + +- Enterprise AI policy suite (approved and version-controlled). +- Complete AI inventory with risk tiering rationale. +- High-risk model validation dossiers and committee minutes. +- Immutable evidence architecture records and retention/legal hold policy. +- Incident response runbooks and exercise outputs. +- Third-party/GPAI risk assessments and contract clause library. +- Board and executive reporting packs (KPI/KRI trend history). +- Forward remediation plan with dates, owners, and residual-risk acceptance. + +This package should be deliverable within 48–72 hours under supervisory request conditions. + +--- + +## 23) Companion implementation artifacts (machine-readable) + +To accelerate execution and reduce ambiguity, this blueprint includes machine-readable implementation assets: + +- `governance_blueprint/control_mapping_matrix.csv` — starter control crosswalk with owners, evidence, and review frequencies. +- `governance_blueprint/roadmap_2026_2030.yaml` — phased program plan and exit criteria. +- `governance_blueprint/opa/release_gate.rego` — reference OPA release policy for risk-tiered approvals. +- `governance_blueprint/evidence_event_schema.json` — normalized evidence event contract for Kafka/WORM pipelines. +- `governance_blueprint/artifact_manifest.json` — package manifest with SHA-256 integrity hashes for governance assets. + +These artifacts are intended to be adapted into enterprise repositories and integrated into SDLC gates, model lifecycle pipelines, and supervisory evidence workflows. + +--- + +## 24) Validation and CI readiness for companion artifacts + +To prevent documentation drift and ensure governance artifacts remain deployment-ready, include an automated static validation step in CI: + +```bash +python3 governance_blueprint/validation/validate_artifacts.py +``` + +This verifies: +- control mapping completeness and required fields, +- evidence event schema structure, +- OPA policy structure for tiered release gates, +- roadmap structural integrity checks. + +Reference implementation notes are provided in: +- `governance_blueprint/validation/README.md` +- `governance_blueprint/validation/validate_artifacts.py` + +For validator quality assurance, run: + +```bash +python3 governance_blueprint/validation/selftest_validate_artifacts.py +``` + +For CI enforcement, wire these checks into `.github/workflows/governance-artifacts-ci.yml` (or equivalent enterprise pipeline controls). + +For manifest integrity lifecycle management, generate/check hashes with: + +```bash +python3 governance_blueprint/validation/generate_artifact_manifest.py +python3 governance_blueprint/validation/generate_artifact_manifest.py --check +``` + +For developer workstation guardrails, optionally enable local hooks with `.pre-commit-config.yaml`. + +For consistency between local and CI execution paths, use `governance_blueprint/validation/run_validation_suite.py` as the canonical entrypoint. +If preferred, run the equivalent repo-level Make targets (`make gov-suite`, `make gov-suite-json`) for developer ergonomics. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..e3b7f07 --- /dev/null +++ b/Makefile @@ -0,0 +1,43 @@ +PYTHON ?= python3 + +.PHONY: gov-manifest gov-manifest-check gov-validate gov-validate-json gov-lint gov-dashboard-check gov-selftest gov-suite gov-suite-json gov-suite-report gov-suite-ci gov-clean + +gov-manifest: + $(PYTHON) governance_blueprint/validation/generate_artifact_manifest.py + +gov-manifest-check: + $(PYTHON) governance_blueprint/validation/generate_artifact_manifest.py --check + +gov-validate: + $(PYTHON) governance_blueprint/validation/validate_artifacts.py + +gov-validate-json: + $(PYTHON) governance_blueprint/validation/validate_artifacts.py --json + +gov-lint: + $(PYTHON) governance_blueprint/validation/lint_python_sources.py + +gov-dashboard-check: + $(PYTHON) governance_blueprint/validation/validate_dashboard_links.py + +gov-selftest: + $(PYTHON) governance_blueprint/validation/selftest_validate_artifacts.py + $(PYTHON) governance_blueprint/validation/selftest_run_validation_suite.py + +gov-suite: + $(PYTHON) governance_blueprint/validation/run_validation_suite.py + +gov-suite-json: + $(PYTHON) governance_blueprint/validation/run_validation_suite.py --json-report governance-artifact-validation-report.json + @echo "Wrote governance-artifact-validation-report.json" + +gov-suite-report: + $(PYTHON) governance_blueprint/validation/run_validation_suite.py --json-report governance-artifact-validation-report.json --suite-report governance-validation-suite-report.json + @echo "Wrote governance-artifact-validation-report.json and governance-validation-suite-report.json" + +gov-suite-ci: + $(PYTHON) governance_blueprint/validation/run_validation_suite.py --quiet --json-report governance-artifact-validation-report.json --suite-report governance-validation-suite-report.json + @echo "Wrote governance-artifact-validation-report.json and governance-validation-suite-report.json (quiet mode)" + +gov-clean: + $(PYTHON) -c "from pathlib import Path; import shutil; report=Path('governance-artifact-validation-report.json'); suite=Path('governance-validation-suite-report.json'); report.exists() and report.unlink(); suite.exists() and suite.unlink(); [shutil.rmtree(p) for p in Path('governance_blueprint/validation').rglob('__pycache__') if p.is_dir()]" diff --git a/governance_blueprint/artifact_manifest.json b/governance_blueprint/artifact_manifest.json new file mode 100644 index 0000000..4b68145 --- /dev/null +++ b/governance_blueprint/artifact_manifest.json @@ -0,0 +1,18 @@ +{ + "package": "enterprise_agi_asi_governance_blueprint", + "version": "1.3.1", + "generated_utc": "2026-04-27T06:11:04Z", + "artifacts": { + "control_mapping_matrix.csv": "8af4170e62e6aec3c12f3f554d29fe31e6c59c196cd9b3e1590f1238597ce228", + "evidence_event_schema.json": "7c84f8fce1cefeff08308a2763c086eb4ede05881881cd53c484e879df04196a", + "opa/release_gate.rego": "bd117bddd2c77a0fd5cc4741aa6805b6f1f711d2baa5732ca037ea4db7b60c43", + "roadmap_2026_2030.yaml": "35132b486b360d91ceab94e7949278c755a28dbab0cccf64e0b3a776d7dab485", + "validation/validate_artifacts.py": "0908bb44ecf2b209861fb3fe0259bad2b652d94b1f6c50c45592b074f52848e0", + "validation/selftest_validate_artifacts.py": "50414aa4ecf39166268d76ab0363ad2ec9ac32cde6b27ae5c631764fd7bce29b", + "validation/generate_artifact_manifest.py": "654479289df4a57ab58288adcbb5c9e23861f3b3a6e4d524b8214bb8c992d060", + "validation/run_validation_suite.py": "4c7038c4d3da1d6fb3f4c43bddd5b2237856b90bd568a17d03a1d16cfc904781", + "validation/selftest_run_validation_suite.py": "2f987933769c0530eaa7ad51a0454781e8bd90bb700c120219dae5a96645adbe", + "validation/lint_python_sources.py": "52b36b1427679624fd9778dc93cb7b318b4c882930e78c0947a37d5185dafae9", + "validation/validate_dashboard_links.py": "e854e2c61ac6e31f880fce8e28c6ed95856d13a85fdfdbcf124df74925b1461a" + } +} diff --git a/governance_blueprint/control_mapping_matrix.csv b/governance_blueprint/control_mapping_matrix.csv new file mode 100644 index 0000000..029e974 --- /dev/null +++ b/governance_blueprint/control_mapping_matrix.csv @@ -0,0 +1,8 @@ +control_family,control_id,description,eu_ai_act_anchor,nist_ai_rmf_anchor,iso_42001_anchor,financial_anchor,evidence_artifacts,control_owner,review_frequency +Governance & accountability,AIGOV-01,Board-approved AI governance charter and accountability model,Governance/accountability obligations,Govern,Leadership & planning controls,SR 11-7 governance + SMCR,Board minutes|charter|RACI,CRO/CAIO,Quarterly +Inventory & tiering,AIGOV-02,Enterprise inventory and risk tiering for all AI systems,Risk classification/high-risk scoping,Map,Context & risk assessment controls,PRA/FCA model inventory expectations,Inventory export|tier rationale logs,Model Risk,Monthly +Data governance,AIGOV-03,Lawful basis and lineage for training/serving datasets,Logging/traceability dependencies,Map+Measure,Operational data controls,GDPR + MAS/HKMA data controls,DPIA|TIA|lineage graph,CDO/Privacy,Monthly +Validation & challenge,AIGOV-04,Independent validation before high-risk deployment,Conformity/performance support obligations,Measure+Manage,Evaluation & monitoring controls,SR 11-7 independent validation,Validation report|challenger tests,Model Validation,Per release +Explainability & oversight,AIGOV-05,Human oversight and adverse-action explainability controls,Human oversight/transparency,Govern+Manage,Human-in-the-loop controls,FCRA/ECOA + Consumer Duty,Explanation logs|override audit,Business Owner,Per release +Monitoring & incident response,AIGOV-06,Continuous monitoring with incident escalation workflows,Post-market monitoring/incident handling,Measure+Manage,Incident handling and improvement,Operational resilience expectations,Incident timeline|postmortem|notifications,SRE/CISO,Continuous +Third-party & GPAI,AIGOV-07,Supplier assurance and contractual auditability,GPAI provider/deployer dependencies,Govern+Map,External provider controls,Outsourcing/third-party risk guidance,Contracts|assessments|exit plan,TPRM,Quarterly diff --git a/governance_blueprint/evidence_event_schema.json b/governance_blueprint/evidence_event_schema.json new file mode 100644 index 0000000..6758ceb --- /dev/null +++ b/governance_blueprint/evidence_event_schema.json @@ -0,0 +1,46 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "AI Governance Evidence Event", + "type": "object", + "required": [ + "event_id", + "timestamp_utc", + "event_type", + "model_id", + "model_version", + "risk_tier", + "policy_bundle_hash", + "trace_id", + "jurisdiction_code" + ], + "properties": { + "event_id": { "type": "string", "description": "UUID for immutable event identity." }, + "timestamp_utc": { "type": "string", "format": "date-time" }, + "event_type": { + "type": "string", + "enum": [ + "model_registered", + "validation_approved", + "release_approved", + "inference_executed", + "override_recorded", + "incident_opened", + "incident_closed" + ] + }, + "model_id": { "type": "string" }, + "model_version": { "type": "string" }, + "risk_tier": { "type": "integer", "minimum": 0, "maximum": 4 }, + "policy_bundle_hash": { "type": "string" }, + "trace_id": { "type": "string" }, + "request_id": { "type": "string" }, + "decision_context": { "type": "string" }, + "explanation_reference": { "type": "string" }, + "human_override_flag": { "type": "boolean" }, + "override_reason_code": { "type": "string" }, + "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, + "latency_ms": { "type": "number", "minimum": 0 }, + "jurisdiction_code": { "type": "string" } + }, + "additionalProperties": false +} diff --git a/governance_blueprint/opa/release_gate.rego b/governance_blueprint/opa/release_gate.rego new file mode 100644 index 0000000..b3cd500 --- /dev/null +++ b/governance_blueprint/opa/release_gate.rego @@ -0,0 +1,40 @@ +package aigov.release + +# Deny by default. +default allow = false + +# Baseline requirements for all models. +baseline_requirements { + input.model_card_exists + input.security_scan_passed + input.policy_bundle_hash_approved +} + +# Low/medium risk release path. +allow { + input.risk_tier <= 2 + baseline_requirements +} + +# High-risk release path. +allow { + input.risk_tier >= 3 + baseline_requirements + input.independent_validation_approved + input.legal_compliance_approved + input.explainability_test_passed + input.human_oversight_plan_approved +} + +# Additional controls for frontier/special risk systems. +allow { + input.risk_tier == 4 + baseline_requirements + input.independent_validation_approved + input.legal_compliance_approved + input.explainability_test_passed + input.human_oversight_plan_approved + input.safety_case_approved + input.containment_controls_verified + input.executive_signoff +} diff --git a/governance_blueprint/roadmap_2026_2030.yaml b/governance_blueprint/roadmap_2026_2030.yaml new file mode 100644 index 0000000..7d1cc22 --- /dev/null +++ b/governance_blueprint/roadmap_2026_2030.yaml @@ -0,0 +1,50 @@ +program: enterprise_agi_asi_governance +version: 1.0 +horizon: 2026-2030 +phases: + - name: foundation + window: "2026-Q2 to 2026-Q4" + objectives: + - Establish policy framework and control taxonomy + - Complete AI inventory and tiering + - Deploy minimum CI/CD compliance-as-code gates + - Enable immutable evidence logging baseline + exit_criteria: + - "100% production AI systems inventoried and tiered" + - "Tier 3+ systems independently validated" + - "Board-approved AI risk appetite ratified" + - name: industrialization + window: "2027" + objectives: + - Scale control automation across material business lines + - Implement supplier/GPAI assurance program + - Deploy explainability UX for regulated decisions + - Run regulator-inclusive tabletop exercises + exit_criteria: + - ">90% policy controls continuously monitored" + - "Regulator evidence packs generated in <72h" + - name: advanced_assurance + window: "2028" + objectives: + - Integrate frontier capability thresholding + - Deploy containment and safety-case workflow + - Complete external assurance against ISO/IEC 42001 + exit_criteria: + - "Tier 4 systems require approved safety case" + - "End-to-end control tests reproducible" + - name: resilience_and_advantage + window: "2029-2030" + objectives: + - Introduce adaptive governance with human approval + - Improve cross-border supervisory evidence interoperability + - Embed AGI discontinuity scenario planning + exit_criteria: + - "Stable audit outcomes while AI portfolio scales" + - "Reduced governance cost per model with higher control efficacy" +workstreams: + - governance_and_policy + - model_risk_and_validation + - safety_and_containment + - platform_controls_and_evidence + - third_party_and_gpai_assurance + - supervisory_engagement diff --git a/governance_blueprint/validation/README.md b/governance_blueprint/validation/README.md new file mode 100644 index 0000000..4211ac2 --- /dev/null +++ b/governance_blueprint/validation/README.md @@ -0,0 +1,134 @@ +# Governance Artifact Validation + +Run the validator from repository root: + +```bash +python3 governance_blueprint/validation/validate_artifacts.py +``` + +Machine-readable report (for CI parsers): + +```bash +python3 governance_blueprint/validation/validate_artifacts.py --json +``` + +Run validator self-tests (stdlib `unittest`): + +```bash +python3 governance_blueprint/validation/selftest_validate_artifacts.py +python3 governance_blueprint/validation/selftest_run_validation_suite.py +``` + +Run full suite (manifest check + validator + lint + dashboard check + self-tests): + +```bash +python3 governance_blueprint/validation/run_validation_suite.py +``` + +Optional full suite execution report (includes per-step statuses and embedded validator JSON): + +```bash +python3 governance_blueprint/validation/run_validation_suite.py --json-report governance-artifact-validation-report.json --suite-report governance-validation-suite-report.json +``` + +Quiet mode (less log noise in local scripts): + +```bash +python3 governance_blueprint/validation/run_validation_suite.py --quiet +``` + +Lint validation Python sources: + +```bash +python3 governance_blueprint/validation/lint_python_sources.py +``` + +Validate dashboard wiring: + +```bash +python3 governance_blueprint/validation/validate_dashboard_links.py +``` + +Generate/update artifact manifest: + +```bash +python3 governance_blueprint/validation/generate_artifact_manifest.py +``` + +Refresh manifest timestamp explicitly (optional): + +```bash +python3 governance_blueprint/validation/generate_artifact_manifest.py --stamp-now +``` + +Check artifact manifest freshness (CI-friendly): + +```bash +python3 governance_blueprint/validation/generate_artifact_manifest.py --check +``` + +What the validator checks: +- Required headers and non-empty values in `control_mapping_matrix.csv`. +- Required top-level fields and property definitions in `evidence_event_schema.json`. +- Structural expectations in `opa/release_gate.rego` (baseline block + tiered `allow` rules). +- Required roadmap tokens and indentation sanity in `roadmap_2026_2030.yaml`. +- SHA-256 integrity verification using `artifact_manifest.json`. +- Python syntax compile checks across `governance_blueprint/validation/*.py`. +- Dashboard navigation link checks between whitepaper and blueprint pages. + +CI automation: +- GitHub Actions workflow: `.github/workflows/governance-artifacts-ci.yml`. +- Runs `run_validation_suite.py` on PRs/pushes that touch governance blueprint assets. +- Optional local git hook enforcement via `.pre-commit-config.yaml`. + +Optional local pre-commit setup: + +- The included hook runs a fast check path (`--skip-selftest --quiet`) for better commit ergonomics. +- Full coverage remains enforced in CI and available locally via `make gov-suite` / `make gov-suite-ci`. + + +```bash +pip install pre-commit +pre-commit install +pre-commit run --all-files +``` + +This validator is intentionally dependency-light (standard library only) so it can run in minimal CI environments. + +Convenience Make targets (repo root): + +```bash +make gov-manifest +make gov-manifest-check +make gov-validate +make gov-validate-json +make gov-lint +make gov-dashboard-check +make gov-selftest +make gov-suite +make gov-suite-json +make gov-suite-report +make gov-suite-ci +make gov-clean +``` + + +Note: The suite runner invokes scripts via the active Python interpreter (`sys.executable`) to avoid PATH/interpreter drift across local/CI environments. + +Make targets honor `PYTHON` (default: `python3`) so teams can pin an interpreter explicitly when needed. + + +Exit code conventions (run_validation_suite.py): +- `0`: all checks passed. +- Any other non-zero code: propagated from an invoked check command (for example manifest/check/selftest failure codes). +- `3`: validator JSON output was malformed when `--json-report` was requested. + + +`make gov-suite-ci` runs the suite in quiet report mode, matching the CI workflow command line. + + +Optional: run through all steps even after failures (captures a fuller suite report): + +```bash +python3 governance_blueprint/validation/run_validation_suite.py --no-fail-fast --suite-report governance-validation-suite-report.json +``` diff --git a/governance_blueprint/validation/generate_artifact_manifest.py b/governance_blueprint/validation/generate_artifact_manifest.py new file mode 100644 index 0000000..4de8864 --- /dev/null +++ b/governance_blueprint/validation/generate_artifact_manifest.py @@ -0,0 +1,100 @@ +#!/usr/bin/env python3 +"""Generate or verify governance_blueprint/artifact_manifest.json.""" + +from __future__ import annotations + +import argparse +import hashlib +import json +from datetime import datetime, timezone +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +ARTIFACTS = ROOT / "governance_blueprint" +MANIFEST_PATH = ARTIFACTS / "artifact_manifest.json" +DEFAULT_FILES = [ + "control_mapping_matrix.csv", + "evidence_event_schema.json", + "opa/release_gate.rego", + "roadmap_2026_2030.yaml", + "validation/validate_artifacts.py", + "validation/selftest_validate_artifacts.py", + "validation/generate_artifact_manifest.py", + "validation/run_validation_suite.py", + "validation/selftest_run_validation_suite.py", + "validation/lint_python_sources.py", + "validation/validate_dashboard_links.py", +] + + +def sha256_of(path: Path) -> str: + return hashlib.sha256(path.read_bytes()).hexdigest() + + +def _existing_generated_utc() -> str | None: + if not MANIFEST_PATH.exists(): + return None + try: + current = json.loads(MANIFEST_PATH.read_text(encoding="utf-8")) + except json.JSONDecodeError: + return None + value = current.get("generated_utc") + return value if isinstance(value, str) and value else None + + +def build_manifest(*, preserve_timestamp: bool = True) -> dict: + artifacts: dict[str, str] = {} + for rel in DEFAULT_FILES: + p = ARTIFACTS / rel + artifacts[rel] = sha256_of(p) + + generated_utc = _existing_generated_utc() if preserve_timestamp else None + if not generated_utc: + generated_utc = ( + datetime.now(timezone.utc) + .replace(microsecond=0) + .isoformat() + .replace("+00:00", "Z") + ) + + return { + "package": "enterprise_agi_asi_governance_blueprint", + "version": "1.3.1", + "generated_utc": generated_utc, + "artifacts": artifacts, + } + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument("--check", action="store_true", help="Fail if manifest is out of date.") + parser.add_argument( + "--stamp-now", + action="store_true", + help="When generating, refresh generated_utc to current UTC time.", + ) + args = parser.parse_args() + + if args.check: + if not MANIFEST_PATH.exists(): + print("artifact_manifest.json is missing") + return 1 + current_obj = json.loads(MANIFEST_PATH.read_text(encoding="utf-8")) + expected_obj = build_manifest(preserve_timestamp=True) + current_artifacts = current_obj.get("artifacts", {}) + expected_artifacts = expected_obj.get("artifacts", {}) + if current_artifacts != expected_artifacts: + print("artifact_manifest.json is out of date; run generate_artifact_manifest.py") + return 1 + print("artifact_manifest.json is up to date") + return 0 + + manifest = build_manifest(preserve_timestamp=not args.stamp_now) + rendered = json.dumps(manifest, indent=2) + "\n" + MANIFEST_PATH.write_text(rendered, encoding="utf-8") + print(f"Wrote {MANIFEST_PATH}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/governance_blueprint/validation/lint_python_sources.py b/governance_blueprint/validation/lint_python_sources.py new file mode 100644 index 0000000..d99301f --- /dev/null +++ b/governance_blueprint/validation/lint_python_sources.py @@ -0,0 +1,32 @@ +#!/usr/bin/env python3 +"""Compile validation Python sources to catch syntax errors early.""" + +from __future__ import annotations + +import py_compile +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +VALIDATION_DIR = ROOT / "governance_blueprint" / "validation" + + +def main() -> int: + failures: list[str] = [] + for path in sorted(VALIDATION_DIR.glob("*.py")): + try: + py_compile.compile(str(path), doraise=True) + except py_compile.PyCompileError as exc: + failures.append(f"{path}: {exc.msg}") + + if failures: + print("Python source lint failed:") + for failure in failures: + print(f"- {failure}") + return 1 + + print("Python source lint passed for validation scripts.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/governance_blueprint/validation/run_validation_suite.py b/governance_blueprint/validation/run_validation_suite.py new file mode 100644 index 0000000..5e75b62 --- /dev/null +++ b/governance_blueprint/validation/run_validation_suite.py @@ -0,0 +1,148 @@ +#!/usr/bin/env python3 +"""Single entrypoint to run governance artifact checks consistently. + +Used by CI and local pre-commit hooks to avoid command drift. +""" + +from __future__ import annotations + +import argparse +import json +import subprocess +import sys +from datetime import datetime, timezone +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +MALFORMED_VALIDATOR_JSON_RC = 3 + + +def _run(cmd: list[str], *, quiet: bool = False) -> int: + if not quiet: + print("$", " ".join(cmd)) + completed = subprocess.run(cmd, cwd=ROOT) + return completed.returncode + + +def build_steps(*, json_report: bool, skip_selftest: bool) -> list[list[str]]: + steps: list[list[str]] = [ + [sys.executable, "governance_blueprint/validation/generate_artifact_manifest.py", "--check"], + ] + + if json_report: + steps.append( + [ + sys.executable, + "governance_blueprint/validation/validate_artifacts.py", + "--json", + ] + ) + else: + steps.append([sys.executable, "governance_blueprint/validation/validate_artifacts.py"]) + + steps.append([sys.executable, "governance_blueprint/validation/lint_python_sources.py"]) + steps.append([sys.executable, "governance_blueprint/validation/validate_dashboard_links.py"]) + + if not skip_selftest: + steps.append([sys.executable, "governance_blueprint/validation/selftest_validate_artifacts.py"]) + steps.append([sys.executable, "governance_blueprint/validation/selftest_run_validation_suite.py"]) + + return steps + + +def _write_suite_report(path: Path, step_results: list[dict], validator_report: dict | None) -> None: + payload = { + "ok": all(step["returncode"] == 0 for step in step_results), + "generated_utc": datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z"), + "steps": step_results, + "validator_report": validator_report, + } + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8") + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument( + "--json-report", + type=str, + default="", + help="Optional output path for validator JSON report.", + ) + parser.add_argument( + "--suite-report", + type=str, + default="", + help="Optional output path for full suite execution report JSON.", + ) + parser.add_argument( + "--skip-selftest", + action="store_true", + help="Skip validator self-tests (not recommended).", + ) + parser.add_argument( + "--quiet", + action="store_true", + help="Suppress per-step command echo output.", + ) + parser.add_argument( + "--no-fail-fast", + action="store_true", + help="Continue running remaining steps after a failure and return the first non-zero code.", + ) + args = parser.parse_args() + + steps = build_steps(json_report=bool(args.json_report), skip_selftest=args.skip_selftest) + step_results: list[dict] = [] + validator_payload: dict | None = None + first_failure_rc = 0 + + for cmd in steps: + step_name = Path(cmd[1]).name if len(cmd) > 1 else "unknown" + + if args.json_report and cmd[-1] == "--json": + report_path = Path(args.json_report) + report_path.parent.mkdir(parents=True, exist_ok=True) + with report_path.open("w", encoding="utf-8") as out: + completed = subprocess.run(cmd, cwd=ROOT, stdout=out) + rc = completed.returncode + if rc == 0: + try: + validator_payload = json.loads(report_path.read_text(encoding="utf-8")) + except json.JSONDecodeError: + rc = MALFORMED_VALIDATOR_JSON_RC + print("Validator JSON report is malformed.") + step_results.append({"name": step_name, "command": cmd, "returncode": rc}) + if rc != 0: + if first_failure_rc == 0: + first_failure_rc = rc + if not args.no_fail_fast: + if args.suite_report: + _write_suite_report(Path(args.suite_report), step_results, validator_payload) + return rc + continue + + rc = _run(cmd, quiet=args.quiet) + step_results.append({"name": step_name, "command": cmd, "returncode": rc}) + if rc != 0: + if first_failure_rc == 0: + first_failure_rc = rc + if not args.no_fail_fast: + if args.suite_report: + _write_suite_report(Path(args.suite_report), step_results, validator_payload) + return rc + + if first_failure_rc != 0: + if args.suite_report: + _write_suite_report(Path(args.suite_report), step_results, validator_payload) + return first_failure_rc + + if not args.quiet: + print("Governance validation suite passed.") + if args.suite_report: + _write_suite_report(Path(args.suite_report), step_results, validator_payload) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/governance_blueprint/validation/selftest_run_validation_suite.py b/governance_blueprint/validation/selftest_run_validation_suite.py new file mode 100644 index 0000000..b244522 --- /dev/null +++ b/governance_blueprint/validation/selftest_run_validation_suite.py @@ -0,0 +1,180 @@ +#!/usr/bin/env python3 +"""Unit tests for run_validation_suite.py behavior.""" + +from __future__ import annotations + +from contextlib import redirect_stdout +import importlib.util +import io +import json +import sys +import tempfile +import unittest +from pathlib import Path +from unittest.mock import patch + +MODULE_PATH = Path(__file__).with_name("run_validation_suite.py") +spec = importlib.util.spec_from_file_location("run_validation_suite", MODULE_PATH) +rs = importlib.util.module_from_spec(spec) +assert spec and spec.loader +spec.loader.exec_module(rs) + + +class RunValidationSuiteTests(unittest.TestCase): + def test_build_steps_without_json_report(self) -> None: + steps = rs.build_steps(json_report=False, skip_selftest=False) + expected = [ + [sys.executable, "governance_blueprint/validation/generate_artifact_manifest.py", "--check"], + [sys.executable, "governance_blueprint/validation/validate_artifacts.py"], + [sys.executable, "governance_blueprint/validation/lint_python_sources.py"], + [sys.executable, "governance_blueprint/validation/validate_dashboard_links.py"], + [sys.executable, "governance_blueprint/validation/selftest_validate_artifacts.py"], + [sys.executable, "governance_blueprint/validation/selftest_run_validation_suite.py"], + ] + self.assertEqual(steps, expected) + + def test_build_steps_with_json_and_skip_selftest(self) -> None: + steps = rs.build_steps(json_report=True, skip_selftest=True) + expected = [ + [sys.executable, "governance_blueprint/validation/generate_artifact_manifest.py", "--check"], + [sys.executable, "governance_blueprint/validation/validate_artifacts.py", "--json"], + [sys.executable, "governance_blueprint/validation/lint_python_sources.py"], + [sys.executable, "governance_blueprint/validation/validate_dashboard_links.py"], + ] + self.assertEqual(steps, expected) + + def test_suite_writes_json_report_path(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + report = Path(tmp) / "report.json" + + def fake_run(cmd, cwd=None, stdout=None): + class R: + returncode = 0 + + if stdout is not None: + stdout.write('{"ok": true}\n') + return R() + + with patch.object(rs.subprocess, "run", side_effect=fake_run): + with patch("sys.argv", ["run_validation_suite.py", "--json-report", str(report), "--skip-selftest", "--quiet"]): + rc = rs.main() + + self.assertEqual(rc, 0) + self.assertTrue(report.exists()) + self.assertIn('"ok": true', report.read_text(encoding="utf-8")) + + def test_suite_writes_suite_report(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + validator_report = Path(tmp) / "validator.json" + suite_report = Path(tmp) / "suite.json" + + def fake_run(cmd, cwd=None, stdout=None): + class R: + returncode = 0 + + if stdout is not None: + stdout.write('{"ok": true}\n') + return R() + + with patch.object(rs.subprocess, "run", side_effect=fake_run): + with patch( + "sys.argv", + [ + "run_validation_suite.py", + "--json-report", + str(validator_report), + "--suite-report", + str(suite_report), + "--skip-selftest", + "--quiet", + ], + ): + rc = rs.main() + + self.assertEqual(rc, 0) + self.assertTrue(suite_report.exists()) + suite_payload = json.loads(suite_report.read_text(encoding="utf-8")) + self.assertTrue(suite_payload["ok"]) + self.assertEqual(len(suite_payload["steps"]), 4) + self.assertEqual(suite_payload["validator_report"], {"ok": True}) + + def test_failure_writes_suite_report_with_failed_step(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + suite_report = Path(tmp) / "suite-fail.json" + + with patch.object(rs, "_run", return_value=2): + with patch("sys.argv", ["run_validation_suite.py", "--suite-report", str(suite_report), "--skip-selftest", "--quiet"]): + rc = rs.main() + + self.assertEqual(rc, 2) + self.assertTrue(suite_report.exists()) + payload = json.loads(suite_report.read_text(encoding="utf-8")) + self.assertFalse(payload["ok"]) + self.assertEqual(payload["steps"][0]["name"], "generate_artifact_manifest.py") + self.assertEqual(payload["steps"][0]["returncode"], 2) + + + def test_malformed_validator_json_fails(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + report = Path(tmp) / "bad-validator.json" + suite_report = Path(tmp) / "suite.json" + + def fake_run(cmd, cwd=None, stdout=None): + class R: + returncode = 0 + + if stdout is not None: + stdout.write('{not-json}\n') + return R() + + with patch.object(rs.subprocess, "run", side_effect=fake_run): + with patch( + "sys.argv", + [ + "run_validation_suite.py", + "--json-report", + str(report), + "--suite-report", + str(suite_report), + "--skip-selftest", + "--quiet", + ], + ): + with redirect_stdout(io.StringIO()): + rc = rs.main() + + self.assertEqual(rc, 3) + payload = json.loads(suite_report.read_text(encoding="utf-8")) + self.assertFalse(payload["ok"]) + self.assertEqual(payload["steps"][1]["name"], "validate_artifacts.py") + self.assertEqual(payload["steps"][1]["returncode"], 3) + + + def test_no_fail_fast_runs_all_steps(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + suite_report = Path(tmp) / "suite-no-fail-fast.json" + + with patch.object(rs, "_run", side_effect=[2, 0, 0, 0]): + with patch( + "sys.argv", + [ + "run_validation_suite.py", + "--suite-report", + str(suite_report), + "--skip-selftest", + "--quiet", + "--no-fail-fast", + ], + ): + rc = rs.main() + + self.assertEqual(rc, 2) + payload = json.loads(suite_report.read_text(encoding="utf-8")) + self.assertEqual(len(payload["steps"]), 4) + self.assertEqual(payload["steps"][0]["returncode"], 2) + self.assertEqual(payload["steps"][-1]["returncode"], 0) + + + +if __name__ == "__main__": + unittest.main() diff --git a/governance_blueprint/validation/selftest_validate_artifacts.py b/governance_blueprint/validation/selftest_validate_artifacts.py new file mode 100644 index 0000000..e0ed58f --- /dev/null +++ b/governance_blueprint/validation/selftest_validate_artifacts.py @@ -0,0 +1,175 @@ +#!/usr/bin/env python3 +"""Unit tests for validate_artifacts.py using stdlib unittest.""" + +from __future__ import annotations + +import importlib.util +import hashlib +import json +import tempfile +import unittest +from pathlib import Path + +MODULE_PATH = Path(__file__).with_name("validate_artifacts.py") +spec = importlib.util.spec_from_file_location("validate_artifacts", MODULE_PATH) +va = importlib.util.module_from_spec(spec) +assert spec and spec.loader +spec.loader.exec_module(va) + + +class ValidateArtifactsTests(unittest.TestCase): + def setUp(self) -> None: + self.tmp = tempfile.TemporaryDirectory() + self.tmp_path = Path(self.tmp.name) + self.artifacts = self.tmp_path / "governance_blueprint" + self._seed_valid_artifacts() + self.original_artifacts = va.ARTIFACTS + va.ARTIFACTS = self.artifacts + + def tearDown(self) -> None: + va.ARTIFACTS = self.original_artifacts + self.tmp.cleanup() + + def _write(self, path: Path, text: str) -> None: + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text, encoding="utf-8") + + def _seed_valid_artifacts(self) -> None: + self._write( + self.artifacts / "control_mapping_matrix.csv", + "control_family,control_id,description,eu_ai_act_anchor,nist_ai_rmf_anchor,iso_42001_anchor,financial_anchor,evidence_artifacts,control_owner,review_frequency\n" + "A,B,C,D,E,F,G,H,I,J\n" + "A2,B2,C2,D2,E2,F2,G2,H2,I2,J2\n" + "A3,B3,C3,D3,E3,F3,G3,H3,I3,J3\n" + "A4,B4,C4,D4,E4,F4,G4,H4,I4,J4\n" + "A5,B5,C5,D5,E5,F5,G5,H5,I5,J5\n", + ) + + schema = { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "x", + "type": "object", + "required": [ + "event_id", + "timestamp_utc", + "event_type", + "model_id", + "model_version", + "risk_tier", + "policy_bundle_hash", + "trace_id", + "jurisdiction_code", + ], + "properties": { + "event_id": {"type": "string"}, + "timestamp_utc": {"type": "string"}, + "event_type": {"type": "string"}, + "model_id": {"type": "string"}, + "model_version": {"type": "string"}, + "risk_tier": {"type": "integer"}, + "policy_bundle_hash": {"type": "string"}, + "trace_id": {"type": "string"}, + "jurisdiction_code": {"type": "string"}, + }, + } + self._write(self.artifacts / "evidence_event_schema.json", json.dumps(schema)) + + self._write( + self.artifacts / "opa" / "release_gate.rego", + "package aigov.release\n" + "default allow = false\n" + "baseline_requirements { true }\n" + "allow { input.risk_tier <= 2 }\n" + "allow { input.risk_tier >= 3 }\n" + "allow { input.risk_tier == 4 }\n", + ) + + self._write( + self.artifacts / "roadmap_2026_2030.yaml", + "program: p\n" + "version: 1\n" + "horizon: h\n" + "phases:\n" + " - name: foundation\n" + " - name: industrialization\n" + " - name: advanced_assurance\n" + " - name: resilience_and_advantage\n" + "workstreams:\n" + " - one\n" + " - two\n" + " - three\n", + ) + + # Generate manifest hashes for seeded files. + hash_targets = [ + "control_mapping_matrix.csv", + "evidence_event_schema.json", + "opa/release_gate.rego", + "roadmap_2026_2030.yaml", + ] + manifest = { + "package": "test", + "version": "test", + "generated_utc": "test", + "artifacts": {}, + } + for rel in hash_targets: + p = self.artifacts / rel + manifest["artifacts"][rel] = hashlib.sha256(p.read_bytes()).hexdigest() + self._write(self.artifacts / "artifact_manifest.json", json.dumps(manifest)) + + def test_all_validators_pass_for_good_assets(self) -> None: + self.assertEqual(va.validate_csv(), []) + self.assertEqual(va.validate_json_schema(), []) + self.assertEqual(va.validate_rego(), []) + self.assertEqual(va.validate_yaml_shape(), []) + self.assertEqual(va.validate_manifest_hashes(), []) + + def test_schema_missing_model_id_fails(self) -> None: + schema_path = self.artifacts / "evidence_event_schema.json" + schema = json.loads(schema_path.read_text(encoding="utf-8")) + schema["properties"].pop("model_id") + schema_path.write_text(json.dumps(schema), encoding="utf-8") + + errors = va.validate_json_schema() + self.assertTrue(any("model_id" in e for e in errors)) + + def test_rego_missing_blocks_fails(self) -> None: + (self.artifacts / "opa" / "release_gate.rego").write_text( + "package aigov.release\ndefault allow = false\nallow { input.risk_tier <= 2 }\n", + encoding="utf-8", + ) + + errors = va.validate_rego() + self.assertTrue(any("baseline_requirements" in e or "allow blocks" in e for e in errors)) + + def test_manifest_hash_mismatch_fails(self) -> None: + # Mutate a file after manifest generation. + (self.artifacts / "roadmap_2026_2030.yaml").write_text( + "program: changed\nversion: 1\nhorizon: h\nphases:\n - name: foundation\nworkstreams:\n - one\n", + encoding="utf-8", + ) + errors = va.validate_manifest_hashes() + self.assertTrue(any("Hash mismatch" in e for e in errors)) + + def test_yaml_shape_fails_when_insufficient_workstreams(self) -> None: + (self.artifacts / "roadmap_2026_2030.yaml").write_text( + "program: p\n" + "version: 1\n" + "horizon: h\n" + "phases:\n" + " - name: foundation\n" + " - name: industrialization\n" + " - name: advanced_assurance\n" + " - name: resilience_and_advantage\n" + "workstreams:\n" + " - one\n" + " - two\n", + encoding="utf-8", + ) + errors = va.validate_yaml_shape() + self.assertTrue(any("at least 3 workstreams" in e for e in errors)) + + +if __name__ == "__main__": + unittest.main() diff --git a/governance_blueprint/validation/validate_artifacts.py b/governance_blueprint/validation/validate_artifacts.py new file mode 100644 index 0000000..76436cd --- /dev/null +++ b/governance_blueprint/validation/validate_artifacts.py @@ -0,0 +1,230 @@ +#!/usr/bin/env python3 +"""Static validator for governance blueprint machine-readable artifacts. + +Runs dependency-light checks so CI can validate artifacts without requiring +external tooling (OPA/yq/etc.). +""" + +from __future__ import annotations + +import argparse +import csv +import hashlib +import json +import re +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +ARTIFACTS = ROOT / "governance_blueprint" + + +def validate_csv() -> list[str]: + errors: list[str] = [] + path = ARTIFACTS / "control_mapping_matrix.csv" + required_headers = { + "control_family", + "control_id", + "description", + "eu_ai_act_anchor", + "nist_ai_rmf_anchor", + "iso_42001_anchor", + "financial_anchor", + "evidence_artifacts", + "control_owner", + "review_frequency", + } + + with path.open(newline="", encoding="utf-8") as f: + reader = csv.DictReader(f) + if reader.fieldnames is None: + errors.append("CSV has no header row.") + return errors + + missing = required_headers.difference(reader.fieldnames) + if missing: + errors.append(f"CSV missing required headers: {sorted(missing)}") + + rows = list(reader) + if len(rows) < 5: + errors.append("CSV must contain at least 5 control rows.") + + for i, row in enumerate(rows, start=2): + for key in required_headers: + if not (row.get(key) or "").strip(): + errors.append(f"CSV row {i} has empty value for '{key}'.") + + return errors + + +def validate_json_schema() -> list[str]: + errors: list[str] = [] + path = ARTIFACTS / "evidence_event_schema.json" + with path.open(encoding="utf-8") as f: + data = json.load(f) + + required_top_level = {"$schema", "title", "type", "required", "properties"} + missing = required_top_level.difference(data.keys()) + if missing: + errors.append(f"JSON schema missing top-level keys: {sorted(missing)}") + + properties = data.get("properties", {}) + for field in [ + "event_id", + "timestamp_utc", + "event_type", + "model_id", + "model_version", + "risk_tier", + "policy_bundle_hash", + "trace_id", + "jurisdiction_code", + ]: + if field not in properties: + errors.append(f"JSON schema missing required property definition: {field}") + + return errors + + +def validate_rego() -> list[str]: + errors: list[str] = [] + path = ARTIFACTS / "opa" / "release_gate.rego" + text = path.read_text(encoding="utf-8") + + expected_tokens = [ + "package aigov.release", + "default allow = false", + "baseline_requirements", + "input.risk_tier <= 2", + "input.risk_tier >= 3", + "input.risk_tier == 4", + ] + for token in expected_tokens: + if token not in text: + errors.append(f"Rego policy missing expected token: {token}") + + allow_count = text.count("allow {") + if allow_count < 3: + errors.append("Rego policy must define at least three allow blocks.") + + return errors + + +def validate_yaml_shape() -> list[str]: + """Structure checks without external YAML parser dependency.""" + errors: list[str] = [] + path = ARTIFACTS / "roadmap_2026_2030.yaml" + text = path.read_text(encoding="utf-8") + + required_tokens = [ + "program:", + "version:", + "horizon:", + "phases:", + "workstreams:", + "name: foundation", + "name: industrialization", + "name: advanced_assurance", + "name: resilience_and_advantage", + ] + for token in required_tokens: + if token not in text: + errors.append(f"YAML roadmap missing expected token: {token}") + + phase_names = re.findall(r"^\s*-\s+name:\s*([a-zA-Z0-9_]+)\s*$", text, flags=re.MULTILINE) + expected_phases = [ + "foundation", + "industrialization", + "advanced_assurance", + "resilience_and_advantage", + ] + if phase_names[:4] != expected_phases: + errors.append(f"YAML roadmap phase order mismatch: expected {expected_phases}, got {phase_names[:4]}") + + workstream_entries = re.findall(r"^\s*-\s+([a-zA-Z0-9_]+)\s*$", text.split("workstreams:")[-1], flags=re.MULTILINE) + if len(workstream_entries) < 3: + errors.append("YAML roadmap must define at least 3 workstreams.") + + # Lightweight indentation sanity for list entries. + for ln, line in enumerate(text.splitlines(), start=1): + if "\t" in line: + errors.append(f"YAML roadmap has tab indentation at line {ln}; use spaces only.") + + return errors + + +def validate_manifest_hashes() -> list[str]: + errors: list[str] = [] + manifest_path = ARTIFACTS / "artifact_manifest.json" + if not manifest_path.exists(): + return ["artifact_manifest.json not found."] + + with manifest_path.open(encoding="utf-8") as f: + manifest = json.load(f) + + artifacts = manifest.get("artifacts") + if not isinstance(artifacts, dict) or not artifacts: + return ["artifact_manifest.json must contain a non-empty 'artifacts' object."] + + for rel_path, expected_hash in artifacts.items(): + artifact_path = ARTIFACTS / rel_path + if not artifact_path.exists(): + errors.append(f"Manifest references missing file: {rel_path}") + continue + actual_hash = hashlib.sha256(artifact_path.read_bytes()).hexdigest() + if actual_hash != expected_hash: + errors.append( + f"Hash mismatch for {rel_path}: expected {expected_hash}, got {actual_hash}" + ) + return errors + + +def run_checks() -> dict[str, list[str]]: + checks = { + "control_mapping_matrix.csv": validate_csv, + "evidence_event_schema.json": validate_json_schema, + "opa/release_gate.rego": validate_rego, + "roadmap_2026_2030.yaml": validate_yaml_shape, + "artifact_manifest.json": validate_manifest_hashes, + } + + results: dict[str, list[str]] = {} + for name, fn in checks.items(): + results[name] = fn() + return results + + +def main() -> int: + parser = argparse.ArgumentParser(description="Validate governance blueprint artifacts.") + parser.add_argument( + "--json", + action="store_true", + help="Print machine-readable JSON output for CI integrations.", + ) + args = parser.parse_args() + + results = run_checks() + all_errors: list[str] = [] + for name, errors in results.items(): + if errors: + all_errors.append(f"[{name}]") + all_errors.extend([f" - {e}" for e in errors]) + + if args.json: + payload = { + "ok": len(all_errors) == 0, + "results": results, + } + print(json.dumps(payload, indent=2)) + return 0 if payload["ok"] else 1 + + if all_errors: + print("Artifact validation failed:") + print("\n".join(all_errors)) + return 1 + + print("Artifact validation passed for all governance blueprint assets.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/governance_blueprint/validation/validate_dashboard_links.py b/governance_blueprint/validation/validate_dashboard_links.py new file mode 100644 index 0000000..210f35f --- /dev/null +++ b/governance_blueprint/validation/validate_dashboard_links.py @@ -0,0 +1,49 @@ +#!/usr/bin/env python3 +"""Validate dashboard wiring for the governance blueprint page.""" + +from __future__ import annotations + +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +PUBLIC = ROOT / "rag-agentic-dashboard" / "public" +WHITEPAPER = PUBLIC / "whitepaper-suite.html" +BLUEPRINT = PUBLIC / "enterprise-agi-asi-governance-blueprint.html" + + +def main() -> int: + errors: list[str] = [] + + if not WHITEPAPER.exists(): + errors.append("whitepaper-suite.html is missing") + if not BLUEPRINT.exists(): + errors.append("enterprise-agi-asi-governance-blueprint.html is missing") + + if errors: + print("Dashboard link validation failed:") + print("\n".join(f"- {e}" for e in errors)) + return 1 + + whitepaper_text = WHITEPAPER.read_text(encoding="utf-8") + blueprint_text = BLUEPRINT.read_text(encoding="utf-8") + + if "enterprise-agi-asi-governance-blueprint.html" not in whitepaper_text: + errors.append("whitepaper-suite.html does not link to enterprise-agi-asi-governance-blueprint.html") + + if "whitepaper-suite.html" not in blueprint_text: + errors.append("blueprint page is missing backlink to whitepaper-suite.html") + + if "index.html" not in blueprint_text: + errors.append("blueprint page is missing backlink to index.html") + + if errors: + print("Dashboard link validation failed:") + print("\n".join(f"- {e}" for e in errors)) + return 1 + + print("Dashboard link validation passed.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/rag-agentic-dashboard/public/enterprise-agi-asi-governance-blueprint.html b/rag-agentic-dashboard/public/enterprise-agi-asi-governance-blueprint.html new file mode 100644 index 0000000..3ec6cdc --- /dev/null +++ b/rag-agentic-dashboard/public/enterprise-agi-asi-governance-blueprint.html @@ -0,0 +1,80 @@ + + + + + + Enterprise AGI/ASI Governance Blueprint (2026–2030) + + + +
+
+

Enterprise AGI/ASI Governance Blueprint

+

Implementation-oriented governance reference for 2026–2030 across Fortune 500, Global 2000, and G-SIFI institutions.

+
+ EU AI Act (High-Risk + GPAI) + NIST AI RMF 1.0 + ISO/IEC 42001 + SR 11-7 / Basel / PRA / FCA / MAS / HKMA +
+
+ +

What this package contains

+
+
+

Master Blueprint

+
    +
  • Board-to-runtime governance operating model.
    • +
  • 12 control-family taxonomy and role accountability.
    • +
  • AGI/ASI safety and containment protocol design.
    • +
+
+
+

Machine-Readable Artifacts

+
    +
  • control_mapping_matrix.csv
    • +
  • evidence_event_schema.json
    • +
  • opa/release_gate.rego
    • +
  • roadmap_2026_2030.yaml
    • +
  • artifact_manifest.json
    • +
+
+
+

Validation & CI

+
    +
  • ✓ Static validator for artifact quality checks.
    • +
  • ✓ Self-tests using stdlib unittest.
    • +
  • ✓ GitHub Actions workflow for PR/push enforcement.
    • +
+
+
+ +

Operational commands

+
+

python3 governance_blueprint/validation/validate_artifacts.py

+

python3 governance_blueprint/validation/selftest_validate_artifacts.py

+

python3 governance_blueprint/validation/generate_artifact_manifest.py --check

+
+ +

Navigation

+
+

Open Whitepaper Suite

+

Back to Command Center Dashboard

+
+
+ + diff --git a/rag-agentic-dashboard/public/whitepaper-suite.html b/rag-agentic-dashboard/public/whitepaper-suite.html index 4679126..bb49d37 100644 --- a/rag-agentic-dashboard/public/whitepaper-suite.html +++ b/rag-agentic-dashboard/public/whitepaper-suite.html @@ -162,6 +162,19 @@

Kardashev-Scale Energy Futures & Compute Governance

$1.6T
Infrastructure
+
+
MREF-F500-WP-013
+

Enterprise AGI/ASI Governance Blueprint (2026–2030)

+
Implementation Blueprint
+
Regulator-ready master reference with machine-readable governance artifacts, validator self-tests, and CI enforcement workflow for supervisory evidence readiness.
+
+
24
Sections
+
4
Artifacts
+
2
Validation Cmds
+
CI
Enforced
+
Open
Blueprint
+
+