diff --git a/.github/workflows/governance-artifact-validation.yml b/.github/workflows/governance-artifact-validation.yml new file mode 100644 index 0000000..d3304f8 --- /dev/null +++ b/.github/workflows/governance-artifact-validation.yml @@ -0,0 +1,84 @@ +name: Governance Artifact Validation + +on: + workflow_dispatch: + pull_request: + paths: + - docs/artifacts/** + - docs/reports/INSTITUTIONAL_AGI_ASI_MASTER_REFERENCE_2026_2030.md + - scripts/validate_governance_artifact.py + - scripts/export_governance_artifact_json.py + - scripts/summarize_governance_test_results.py + - scripts/generate_governance_manifest.py + - scripts/governance_artifact_constants.py + - test_validate_governance_artifact.py + - test_export_governance_artifact_json.py + - test_summarize_governance_test_results.py + - test_governance_artifact_integrity.py + - test_generate_governance_manifest.py + - requirements-dev.txt + - Makefile + - .github/workflows/governance-artifact-validation.yml + push: + branches: ["main"] + paths: + - docs/artifacts/** + - docs/reports/INSTITUTIONAL_AGI_ASI_MASTER_REFERENCE_2026_2030.md + - scripts/validate_governance_artifact.py + - scripts/export_governance_artifact_json.py + - scripts/summarize_governance_test_results.py + - scripts/generate_governance_manifest.py + - scripts/governance_artifact_constants.py + - test_validate_governance_artifact.py + - test_export_governance_artifact_json.py + - test_summarize_governance_test_results.py + - test_governance_artifact_integrity.py + - test_generate_governance_manifest.py + - requirements-dev.txt + - Makefile + - .github/workflows/governance-artifact-validation.yml + +permissions: + contents: read + +concurrency: + group: governance-artifact-${{ github.ref }} + cancel-in-progress: true + +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' + cache: 'pip' + cache-dependency-path: 'requirements-dev.txt' + + - name: Install dependencies + run: pip install -r requirements-dev.txt + + - name: Run governance verification pipeline + run: make verify-governance + + - name: Publish test summary + if: always() + run: | + if [ -f artifacts/test-results/governance-tests.xml ]; then + SUMMARY=$(make --no-print-directory summarize-governance-tests) + echo "$SUMMARY" | tee -a "$GITHUB_STEP_SUMMARY" + else + echo "Governance tests summary unavailable: JUnit report not found." | tee -a "$GITHUB_STEP_SUMMARY" + fi + + - name: Upload governance test results + if: always() && hashFiles('artifacts/test-results/governance-tests.xml') != '' + uses: actions/upload-artifact@v4 + with: + name: governance-test-results + path: artifacts/test-results/governance-tests.xml diff --git a/.gitignore b/.gitignore index ef9741d..a819196 100644 --- a/.gitignore +++ b/.gitignore @@ -37,3 +37,6 @@ Thumbs.db next-env.d.ts __pycache__/ *.patch + +# Governance test artifacts +artifacts/test-results/ diff --git a/CHANGELOG.md b/CHANGELOG.md index aaa1378..248402c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog +## Version 1.1.0 +- Added enterprise AI governance artifact package under `docs/artifacts/` with YAML source, canonical JSON export, JSON Schema contract, and example templates. +- Added governance tooling scripts for export, validation, and JUnit result summarization: + - `scripts/export_governance_artifact_json.py` + - `scripts/validate_governance_artifact.py` + - `scripts/summarize_governance_test_results.py` +- Added Makefile-driven governance checks (`build-governance-json`, `check-governance-json-clean`, `validate-governance`, `test-governance-ci`, `summarize-governance-tests`). +- Added governance CI workflow (`.github/workflows/governance-artifact-validation.yml`) with summary publishing and test artifact upload. +- Added pytest coverage for exporter/validator/summarizer and pinned governance dev dependencies in `requirements-dev.txt`. + ## Version 1.0.1 - Integrated NLP, CV, and Speech Processor modules. - Added OAuth2 authentication. diff --git a/Makefile b/Makefile index 5042ebf..aba1401 100644 --- a/Makefile +++ b/Makefile @@ -1,3 +1,36 @@ +.PHONY: build-governance-json check-governance-json-clean check-governance-manifest-clean validate-governance test-governance test-governance-ci summarize-governance-tests build-governance-manifest verify-governance + +build-governance-json: + python scripts/export_governance_artifact_json.py --root . + +check-governance-json-clean: + python scripts/export_governance_artifact_json.py --root . --verify + +validate-governance: + python scripts/validate_governance_artifact.py --root . + +test-governance: + pytest -q test_validate_governance_artifact.py test_export_governance_artifact_json.py test_summarize_governance_test_results.py test_governance_artifact_integrity.py test_generate_governance_manifest.py + +test-governance-ci: + mkdir -p artifacts/test-results + pytest -q test_validate_governance_artifact.py test_export_governance_artifact_json.py test_summarize_governance_test_results.py test_governance_artifact_integrity.py test_generate_governance_manifest.py --junitxml=artifacts/test-results/governance-tests.xml + +summarize-governance-tests: + python scripts/summarize_governance_test_results.py --report artifacts/test-results/governance-tests.xml + +build-governance-manifest: + python scripts/generate_governance_manifest.py --root . + +check-governance-manifest-clean: + python scripts/generate_governance_manifest.py --root . --verify + +verify-governance: + $(MAKE) check-governance-json-clean + $(MAKE) check-governance-manifest-clean + $(MAKE) validate-governance + $(MAKE) test-governance-ci + $(MAKE) summarize-governance-tests .DEFAULT_GOAL := check-gsifi-governance .PHONY: validate-gsifi-governance validate-gsifi-governance-module test-gsifi-governance lint-gsifi-governance check-gsifi-governance diff --git a/README.md b/README.md index 17cbf7a..20fe8d9 100644 --- a/README.md +++ b/README.md @@ -61,3 +61,68 @@ Feel free to open issues or submit pull requests! ## License This project is licensed under the MIT License - see the LICENSE file for details. + +## Governance Artifact Tooling + +This repository includes a governance artifact package under `docs/artifacts/` with: +- YAML source-of-truth artifact +- canonical JSON export +- JSON Schema contract +- sample CI/CD policy and regulator report templates + +### Local governance checks + +```bash +pip install -r requirements-dev.txt +# non-mutating freshness checks +make check-governance-json-clean +make check-governance-manifest-clean +make validate-governance +make test-governance +# CI-style run with JUnit output +make test-governance-ci +make summarize-governance-tests +# one-shot full pipeline +make verify-governance +``` + +When generated files are intentionally updated, regenerate before commit: + +```bash +make build-governance-json +make build-governance-manifest +``` + +### Notes +- `make check-governance-json-clean` fails if committed JSON is stale (without rewriting files). +- `make check-governance-manifest-clean` fails if committed `docs/artifacts/manifest.json` is stale (without rewriting files). +- `make validate-governance` enforces schema, parity, and template checks. +- `make test-governance` includes an integrity test against the repository artifact files. +- CI runs the same targets in `.github/workflows/governance-artifact-validation.yml` and uploads JUnit results and posts a summary. + + +### Advanced path overrides + +Use custom paths when artifacts are relocated (all paths are relative to `--root`): + +```bash +python scripts/export_governance_artifact_json.py --root . \ + --yaml docs/artifacts/custom.yaml \ + --json docs/artifacts/custom.json + +python scripts/validate_governance_artifact.py --root . \ + --yaml docs/artifacts/custom.yaml \ + --json docs/artifacts/custom.json \ + --schema docs/artifacts/schemas/enterprise_ai_governance_artifact.schema.json \ + --cicd docs/artifacts/examples/cicd_policy_gate_manifest.yaml \ + --report docs/artifacts/examples/regulator_report_template.xml +``` + + +### Tool version flags + +```bash +python scripts/export_governance_artifact_json.py --version +python scripts/validate_governance_artifact.py --version +python scripts/summarize_governance_test_results.py --version +``` diff --git a/docs/artifacts/README.md b/docs/artifacts/README.md new file mode 100644 index 0000000..c77eabd --- /dev/null +++ b/docs/artifacts/README.md @@ -0,0 +1,53 @@ +# Enterprise AI Governance Artifact Package + +This folder contains the machine-readable governance package for the 2026–2030 program. + +## Contents + +- `enterprise_ai_governance_machine_readable_2026_2030.yaml` — source-of-truth artifact. +- `enterprise_ai_governance_machine_readable_2026_2030.json` — canonical exported JSON. +- `schemas/enterprise_ai_governance_artifact.schema.json` — JSON Schema contract. +- `examples/cicd_policy_gate_manifest.yaml` — CI/CD gate manifest example. +- `examples/regulator_report_template.xml` — regulator report template (`title/abstract/content`). +- `manifest.json` — SHA-256 manifest for package integrity tracking. + +## Validation workflow + +From repository root: + +```bash +pip install -r requirements-dev.txt +# non-mutating freshness checks +make check-governance-json-clean +make check-governance-manifest-clean +make validate-governance +make test-governance +# one-shot full pipeline +make verify-governance +``` + +`check-governance-json-clean` and `check-governance-manifest-clean` are non-mutating +verification gates that fail when generated artifacts need regeneration. + +When intentionally updating generated artifacts, run: + +```bash +make build-governance-json +make build-governance-manifest +``` + +CI uses the same sequence in `.github/workflows/governance-artifact-validation.yml`. + +## Custom path usage + +Both exporter and validator support path overrides relative to `--root`: + +```bash +python scripts/export_governance_artifact_json.py --root . --yaml docs/artifacts/custom.yaml --json docs/artifacts/custom.json +python scripts/validate_governance_artifact.py --root . --yaml docs/artifacts/custom.yaml --json docs/artifacts/custom.json --schema docs/artifacts/schemas/enterprise_ai_governance_artifact.schema.json --cicd docs/artifacts/examples/cicd_policy_gate_manifest.yaml --report docs/artifacts/examples/regulator_report_template.xml +``` + + +## Integrity test + +Repository-level artifact integrity is enforced by `test_governance_artifact_integrity.py`, which validates committed YAML/JSON parity and schema conformance against the files in this folder. diff --git a/docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json b/docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json new file mode 100644 index 0000000..13f6b82 --- /dev/null +++ b/docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json @@ -0,0 +1,348 @@ +{ + "agi_asi_safety": { + "crisis_simulation_frequency": "quarterly", + "monitoring": [ + "cognitive_resonance_protocol" + ], + "mvags": [ + "isolated_execution_enclaves", + "capability_gating", + "human_authorization_high_impact", + "anomaly_detection", + "emergency_stop_recovery" + ], + "platforms": [ + "sentinel_ai_governance_platform_v2_4", + "workflowai_pro", + "luminous_engine_codex" + ] + }, + "cicd_policy_gates": [ + "code_gate", + "data_gate", + "model_gate", + "risk_gate", + "compliance_gate", + "release_gate", + "runtime_gate" + ], + "civilizational_governance_corpus": { + "modules": [ + "constitutional_safety_constraints", + "cross_jurisdiction_legal_ontology", + "critical_infrastructure_risk_scenarios", + "compute_concentration_models", + "incident_archetypes_and_escalation_protocols", + "public_interest_human_rights_frameworks" + ], + "operating_model": [ + "signed_versioned_releases", + "annual_external_expert_review", + "principle_to_policy_translation" + ] + }, + "control_catalog": [ + { + "domain": "identity", + "enforcement": "spiffe_spire_mtls", + "evidence": "identity_attestation_log", + "id": "CTRL-AUTH-001", + "requirement": "workload_identity_verification" + }, + { + "domain": "compliance", + "enforcement": "opa_sidecar_deny_by_default", + "evidence": "policy_decision_stream", + "id": "CTRL-POL-014", + "requirement": "policy_check_for_all_production_inference" + }, + { + "domain": "audit", + "enforcement": "kafka_acks_all_worm_sink", + "evidence": "immutable_event_receipt", + "id": "CTRL-AUD-021", + "requirement": "immutable_logging_within_500ms" + }, + { + "domain": "model_risk", + "enforcement": "cicd_validator_signature_gate", + "evidence": "validation_packet", + "id": "CTRL-MRM-033", + "requirement": "independent_validation_pre_release" + }, + { + "domain": "containment", + "enforcement": "capability_gateway_quorum", + "evidence": "authorization_ledger", + "id": "CTRL-AGI-081", + "requirement": "multi_party_authorization_high_capability_actions" + } + ], + "control_stack": { + "legacy": { + "docker_swarm_security": [ + "mtls", + "signed_images", + "secret_rotation" + ] + }, + "runtime": { + "audit_store": "worm_pqc", + "event_bus": "kafka", + "orchestrator": "kubernetes", + "policy_engine": "opa_rego", + "sidecar": "governance_sidecar" + } + }, + "deterministic_replay_workflow": [ + "retrieve_decision_event", + "resolve_model_and_container_hashes", + "resolve_data_snapshot_and_lineage", + "replay_with_pinned_runtime", + "compare_observed_vs_replay", + "store_verdict_and_variance" + ], + "fs_mrm_controls": { + "annual_or_trigger_revalidation": true, + "challenger_models_required": true, + "independent_validation_required": true, + "quarterly_backtesting_high_materiality": true, + "sr_11_7_aligned_inventory": true + }, + "global_compute_governance": { + "proposals": [ + "ICGC", + "GlobalComputeRegistry", + "GACRA", + "GASO", + "GFMCF", + "GAICS", + "GAIVS", + "GACP", + "GATI", + "GACMO", + "FTEWS", + "GAI_SOC", + "GAIGA", + "GACRLS", + "GFCO", + "GAID", + "GASCF" + ] + }, + "hyperparameter_control_standard": { + "deployment_snapshot_required": true, + "drift_alerting_required": true, + "production_deviation_requires_change_control": true, + "requires_approved_ranges": true + }, + "incident_response_checklist": [ + "declare_severity_and_assemble_command", + "activate_containment_policy_profile", + "preserve_immutable_evidence", + "notify_legal_and_compliance", + "perform_root_cause_and_remediation", + "revalidate_before_reentry" + ], + "kpis": { + "annual_independent_assurance_pass": ">=95%", + "audit_evidence_sla": "<=24h", + "critical_incident_mttr": "<=4h", + "governance_coverage_high_risk_models": ">=99%", + "policy_decision_latency_p99": "<=10ms" + }, + "meta": { + "date": "2026-04-24", + "document_id": "MR-AGI-ASI-ENT-2026-2030", + "horizon": "2026-2030", + "sectors": [ + "fortune500", + "global2000", + "gsifi" + ], + "version": "1.0.0" + }, + "pillars": [ + { + "id": "P1", + "name": "Board and executive accountability" + }, + { + "id": "P2", + "name": "Risk taxonomy and controls" + }, + { + "id": "P3", + "name": "Policy-as-code and controls engineering" + }, + { + "id": "P4", + "name": "Data privacy and sovereignty" + }, + { + "id": "P5", + "name": "Model lifecycle and MRM" + }, + { + "id": "P6", + "name": "Security resilience and containment" + }, + { + "id": "P7", + "name": "Auditability and evidencing" + }, + { + "id": "P8", + "name": "Third-party and concentration risk" + }, + { + "id": "P9", + "name": "Human oversight and conduct" + }, + { + "id": "P10", + "name": "Systemic and cross-border coordination" + } + ], + "regulator_submission_package": { + "required_sections": [ + "architecture_and_data_flows", + "jurisdiction_control_mapping", + "independent_validation_results", + "fairness_performance_incident_metrics", + "executive_attestation", + "reproducible_evidence_manifest" + ] + }, + "regulatory_alignment": [ + { + "artifacts": [ + "risk_classification_workflow", + "conformity_pack", + "post_market_monitoring" + ], + "framework": "EU AI Act" + }, + { + "artifacts": [ + "govern_map_measure_manage_library", + "kri_dashboard" + ], + "framework": "NIST AI RMF 1.0" + }, + { + "artifacts": [ + "aims_clauses_mapping", + "internal_audit_pack" + ], + "framework": "ISO/IEC 42001" + }, + { + "artifacts": [ + "trustworthy_ai_policy", + "human_oversight_controls" + ], + "framework": "OECD AI Principles" + }, + { + "artifacts": [ + "dpia_registry", + "dsar_automation", + "ropa" + ], + "framework": "GDPR" + }, + { + "artifacts": [ + "adverse_action_reasoning_api", + "fairness_reports" + ], + "framework": "FCRA_ECOA" + }, + { + "artifacts": [ + "capital_impact_controls", + "stress_testing_outputs" + ], + "framework": "Basel_III" + }, + { + "artifacts": [ + "independent_validation_reports", + "challenger_model_results" + ], + "framework": "SR_11_7" + }, + { + "artifacts": [ + "accountability_map", + "conduct_outcomes_dashboard" + ], + "framework": "PRA_FCA_SMCR_Consumer_Duty" + }, + { + "artifacts": [ + "jurisdiction_control_pack", + "transfer_assessment" + ], + "framework": "MAS_HKMA" + }, + { + "artifacts": [ + "safety_test_pack", + "provenance_controls" + ], + "framework": "US_EO_14110" + } + ], + "rollout_roadmap": [ + { + "focus": "foundational_controls_and_policy_as_code", + "tier": 1, + "year": 2026 + }, + { + "focus": "full_cicd_gates_and_deterministic_replay", + "tier": 2, + "year": 2027 + }, + { + "focus": "cross_border_automation_and_zk_controls", + "tier": 3, + "year": 2028 + }, + { + "focus": "systemic_telemetry_and_compute_registry_connectivity", + "tier": 4, + "year": 2029 + }, + { + "focus": "adaptive_continuous_assurance", + "tier": 5, + "year": 2030 + } + ], + "technical_blueprints": { + "kafka": { + "required_controls": [ + "acl_governance", + "event_contract_validation", + "immutability_pipeline" + ] + }, + "kubernetes": { + "required_controls": [ + "namespace_risk_segmentation", + "network_policy_isolation", + "signed_admission" + ] + }, + "opa": { + "required_controls": [ + "deny_by_default", + "bundle_signing", + "decision_logging" + ] + } + } +} diff --git a/docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml b/docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml new file mode 100644 index 0000000..9aeda90 --- /dev/null +++ b/docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml @@ -0,0 +1,231 @@ +meta: + document_id: MR-AGI-ASI-ENT-2026-2030 + version: 1.0.0 + date: 2026-04-24 + horizon: 2026-2030 + sectors: + - fortune500 + - global2000 + - gsifi + +pillars: + - id: P1 + name: Board and executive accountability + - id: P2 + name: Risk taxonomy and controls + - id: P3 + name: Policy-as-code and controls engineering + - id: P4 + name: Data privacy and sovereignty + - id: P5 + name: Model lifecycle and MRM + - id: P6 + name: Security resilience and containment + - id: P7 + name: Auditability and evidencing + - id: P8 + name: Third-party and concentration risk + - id: P9 + name: Human oversight and conduct + - id: P10 + name: Systemic and cross-border coordination + +regulatory_alignment: + - framework: EU AI Act + artifacts: [risk_classification_workflow, conformity_pack, post_market_monitoring] + - framework: NIST AI RMF 1.0 + artifacts: [govern_map_measure_manage_library, kri_dashboard] + - framework: ISO/IEC 42001 + artifacts: [aims_clauses_mapping, internal_audit_pack] + - framework: OECD AI Principles + artifacts: [trustworthy_ai_policy, human_oversight_controls] + - framework: GDPR + artifacts: [dpia_registry, dsar_automation, ropa] + - framework: FCRA_ECOA + artifacts: [adverse_action_reasoning_api, fairness_reports] + - framework: Basel_III + artifacts: [capital_impact_controls, stress_testing_outputs] + - framework: SR_11_7 + artifacts: [independent_validation_reports, challenger_model_results] + - framework: PRA_FCA_SMCR_Consumer_Duty + artifacts: [accountability_map, conduct_outcomes_dashboard] + - framework: MAS_HKMA + artifacts: [jurisdiction_control_pack, transfer_assessment] + - framework: US_EO_14110 + artifacts: [safety_test_pack, provenance_controls] + +control_stack: + runtime: + orchestrator: kubernetes + event_bus: kafka + policy_engine: opa_rego + sidecar: governance_sidecar + audit_store: worm_pqc + legacy: + docker_swarm_security: + - mtls + - signed_images + - secret_rotation + +cicd_policy_gates: + - code_gate + - data_gate + - model_gate + - risk_gate + - compliance_gate + - release_gate + - runtime_gate + +hyperparameter_control_standard: + requires_approved_ranges: true + production_deviation_requires_change_control: true + deployment_snapshot_required: true + drift_alerting_required: true + +fs_mrm_controls: + sr_11_7_aligned_inventory: true + independent_validation_required: true + challenger_models_required: true + quarterly_backtesting_high_materiality: true + annual_or_trigger_revalidation: true + +agi_asi_safety: + platforms: + - sentinel_ai_governance_platform_v2_4 + - workflowai_pro + - luminous_engine_codex + monitoring: + - cognitive_resonance_protocol + mvags: + - isolated_execution_enclaves + - capability_gating + - human_authorization_high_impact + - anomaly_detection + - emergency_stop_recovery + crisis_simulation_frequency: quarterly + +global_compute_governance: + proposals: + - ICGC + - GlobalComputeRegistry + - GACRA + - GASO + - GFMCF + - GAICS + - GAIVS + - GACP + - GATI + - GACMO + - FTEWS + - GAI_SOC + - GAIGA + - GACRLS + - GFCO + - GAID + - GASCF + +incident_response_checklist: + - declare_severity_and_assemble_command + - activate_containment_policy_profile + - preserve_immutable_evidence + - notify_legal_and_compliance + - perform_root_cause_and_remediation + - revalidate_before_reentry + +rollout_roadmap: + - tier: 1 + year: 2026 + focus: foundational_controls_and_policy_as_code + - tier: 2 + year: 2027 + focus: full_cicd_gates_and_deterministic_replay + - tier: 3 + year: 2028 + focus: cross_border_automation_and_zk_controls + - tier: 4 + year: 2029 + focus: systemic_telemetry_and_compute_registry_connectivity + - tier: 5 + year: 2030 + focus: adaptive_continuous_assurance + +kpis: + governance_coverage_high_risk_models: ">=99%" + policy_decision_latency_p99: "<=10ms" + audit_evidence_sla: "<=24h" + critical_incident_mttr: "<=4h" + annual_independent_assurance_pass: ">=95%" + +control_catalog: + - id: CTRL-AUTH-001 + domain: identity + requirement: workload_identity_verification + enforcement: spiffe_spire_mtls + evidence: identity_attestation_log + - id: CTRL-POL-014 + domain: compliance + requirement: policy_check_for_all_production_inference + enforcement: opa_sidecar_deny_by_default + evidence: policy_decision_stream + - id: CTRL-AUD-021 + domain: audit + requirement: immutable_logging_within_500ms + enforcement: kafka_acks_all_worm_sink + evidence: immutable_event_receipt + - id: CTRL-MRM-033 + domain: model_risk + requirement: independent_validation_pre_release + enforcement: cicd_validator_signature_gate + evidence: validation_packet + - id: CTRL-AGI-081 + domain: containment + requirement: multi_party_authorization_high_capability_actions + enforcement: capability_gateway_quorum + evidence: authorization_ledger + +deterministic_replay_workflow: + - retrieve_decision_event + - resolve_model_and_container_hashes + - resolve_data_snapshot_and_lineage + - replay_with_pinned_runtime + - compare_observed_vs_replay + - store_verdict_and_variance + +technical_blueprints: + kubernetes: + required_controls: + - namespace_risk_segmentation + - network_policy_isolation + - signed_admission + kafka: + required_controls: + - acl_governance + - event_contract_validation + - immutability_pipeline + opa: + required_controls: + - deny_by_default + - bundle_signing + - decision_logging + +regulator_submission_package: + required_sections: + - architecture_and_data_flows + - jurisdiction_control_mapping + - independent_validation_results + - fairness_performance_incident_metrics + - executive_attestation + - reproducible_evidence_manifest + +civilizational_governance_corpus: + modules: + - constitutional_safety_constraints + - cross_jurisdiction_legal_ontology + - critical_infrastructure_risk_scenarios + - compute_concentration_models + - incident_archetypes_and_escalation_protocols + - public_interest_human_rights_frameworks + operating_model: + - signed_versioned_releases + - annual_external_expert_review + - principle_to_policy_translation diff --git a/docs/artifacts/examples/cicd_policy_gate_manifest.yaml b/docs/artifacts/examples/cicd_policy_gate_manifest.yaml new file mode 100644 index 0000000..753dc19 --- /dev/null +++ b/docs/artifacts/examples/cicd_policy_gate_manifest.yaml @@ -0,0 +1,28 @@ +version: 1 +pipeline: ai-governance-release +required_gates: + - name: code_gate + required: true + checks: [sast, sca, licenses] + - name: data_gate + required: true + checks: [lineage, pii_classification, lawful_use] + - name: model_gate + required: true + checks: [reproducibility, hyperparameter_envelope, eval_suite] + - name: risk_gate + required: true + checks: [bias_threshold, robustness_threshold, adversarial_baseline] + - name: compliance_gate + required: true + checks: [opa_bundle_eval, jurisdiction_controls] + - name: release_gate + required: true + checks: [validator_signature, legal_attestation, risk_signoff] + - name: runtime_gate + required: true + checks: [canary_health, rollback_readiness, runtime_guardrails] +policy_decision_export: + sink: kafka + topic: gov.policy_eval + include_fields: [decision_id, policy_bundle_digest, gate, outcome, timestamp] diff --git a/docs/artifacts/examples/regulator_report_template.xml b/docs/artifacts/examples/regulator_report_template.xml new file mode 100644 index 0000000..5ca06fe --- /dev/null +++ b/docs/artifacts/examples/regulator_report_template.xml @@ -0,0 +1,12 @@ +Enterprise AI Governance Supervisory Report + +This report provides regulator-ready evidence for enterprise AI governance, +model risk controls, and high-impact AI safety operations. + + +
System boundaries, model inventory, and critical services.
+
Regulation-to-control mappings and control effectiveness evidence.
+
Independent validation, internal audit, and residual risk posture.
+
Material incidents, containment actions, and remediation closure status.
+
Executive and accountable senior manager attestations.
+ diff --git a/docs/artifacts/manifest.json b/docs/artifacts/manifest.json new file mode 100644 index 0000000..8787cfa --- /dev/null +++ b/docs/artifacts/manifest.json @@ -0,0 +1,26 @@ +{ + "version": 1, + "algorithm": "sha256", + "entries": [ + { + "path": "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml", + "sha256": "aa1e25cc109d9e247d1d8b82edb0c653cc2be5ac80891ccb6bef2b85d4b9e8fc" + }, + { + "path": "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json", + "sha256": "35ed1b52a06a17749c22ddbfde53cc9c127172c0fdc0e6d518b3187c4a45591c" + }, + { + "path": "docs/artifacts/schemas/enterprise_ai_governance_artifact.schema.json", + "sha256": "be52d4966d1acfad97dd76f2ede9f847edc6e37756a4b930ca62d51a73239d81" + }, + { + "path": "docs/artifacts/examples/cicd_policy_gate_manifest.yaml", + "sha256": "935c8597965c326923c0d618b954ef4c21bad45c51d7c01b2d10f755f4a98509" + }, + { + "path": "docs/artifacts/examples/regulator_report_template.xml", + "sha256": "0aa3f24f55e42e234a8ae1156bd7274aea83861095d2ff864b3fb464e7eb4821" + } + ] +} diff --git a/docs/artifacts/schemas/enterprise_ai_governance_artifact.schema.json b/docs/artifacts/schemas/enterprise_ai_governance_artifact.schema.json new file mode 100644 index 0000000..b744701 --- /dev/null +++ b/docs/artifacts/schemas/enterprise_ai_governance_artifact.schema.json @@ -0,0 +1,79 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://example.org/schemas/enterprise_ai_governance_artifact.schema.json", + "title": "Enterprise AI Governance Artifact (2026-2030)", + "type": "object", + "required": [ + "meta", + "pillars", + "regulatory_alignment", + "control_stack", + "cicd_policy_gates", + "kpis", + "control_catalog", + "deterministic_replay_workflow" + ], + "properties": { + "meta": { + "type": "object", + "required": ["document_id", "version", "date", "horizon", "sectors"], + "properties": { + "document_id": {"type": "string"}, + "version": {"type": "string"}, + "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}, + "horizon": {"type": "string"}, + "sectors": {"type": "array", "minItems": 1, "items": {"type": "string"}} + } + }, + "pillars": { + "type": "array", + "minItems": 5, + "items": { + "type": "object", + "required": ["id", "name"], + "properties": { + "id": {"type": "string"}, + "name": {"type": "string"} + } + } + }, + "regulatory_alignment": { + "type": "array", + "minItems": 5, + "items": { + "type": "object", + "required": ["framework", "artifacts"], + "properties": { + "framework": {"type": "string"}, + "artifacts": {"type": "array", "minItems": 1, "items": {"type": "string"}} + } + } + }, + "cicd_policy_gates": { + "type": "array", + "minItems": 5, + "items": {"type": "string"} + }, + "kpis": {"type": "object", "minProperties": 3}, + "control_catalog": { + "type": "array", + "minItems": 3, + "items": { + "type": "object", + "required": ["id", "domain", "requirement", "enforcement", "evidence"], + "properties": { + "id": {"type": "string"}, + "domain": {"type": "string"}, + "requirement": {"type": "string"}, + "enforcement": {"type": "string"}, + "evidence": {"type": "string"} + } + } + }, + "deterministic_replay_workflow": { + "type": "array", + "minItems": 5, + "items": {"type": "string"} + } + } +} diff --git a/docs/reports/INSTITUTIONAL_AGI_ASI_MASTER_REFERENCE_2026_2030.md b/docs/reports/INSTITUTIONAL_AGI_ASI_MASTER_REFERENCE_2026_2030.md new file mode 100644 index 0000000..ea3c4c1 --- /dev/null +++ b/docs/reports/INSTITUTIONAL_AGI_ASI_MASTER_REFERENCE_2026_2030.md @@ -0,0 +1,475 @@ +# Institutional-Grade AGI/ASI & Enterprise AI Governance Master Reference (2026–2030) + +**Document ID:** MR-AGI-ASI-ENT-2026-2030 +**Version:** 1.0.0 +**Date:** 2026-04-24 +**Audience:** Fortune 500, Global 2000, G-SIFIs, Boards, Risk Committees, Regulators, Internal Audit, MRM, Enterprise Architecture, DevSecOps + +--- + +## 1) Executive Implementation Scope + +This master reference provides implementation blueprints for: +- Institutional governance pillars and operating models. +- Regulatory alignment controls (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, HKMA, SMCR, Consumer Duty, and U.S. Executive Order 14110). +- Enterprise reference architectures (Kubernetes/Kafka/OPA/Terraform/CI/CD, governance sidecars, explainability frontends, deterministic audit replay). +- Financial-services model risk governance for high-impact and systemic use-cases. +- AGI/ASI containment and safety operations (Sentinel v2.4, WorkflowAI Pro, Luminous Engine Codex, Cognitive Resonance Protocol). +- Global compute and AI systemic governance proposals. + +Planning horizon: **Q2 2026 to Q4 2030**. + +--- + +## 2) Governance Pillars (Institutional Core) + +1. **Board & Executive Accountability** + - AI Board Risk Committee charter, escalation thresholds, and annual attestations. + - SMCR/Consumer Duty-aligned accountability maps for Senior Managers. +2. **Risk Taxonomy & Controls** + - Model, operational, legal/compliance, cyber, conduct, systemic, and alignment risk. + - Quantified KRIs (drift, fairness, explainability failure rates, incident MTTR). +3. **Policy-as-Code & Controls Engineering** + - OPA/Rego mapped to enterprise controls and legal obligations. + - Policy lifecycle in GitOps with segregation of duties. +4. **Data, Privacy, and Sovereignty** + - Purpose limitation, minimization, lawful basis, retention schedules, lineage. +5. **Model Lifecycle & MRM** + - SR 11-7 style development-validation-approval-monitoring-retirement lifecycle. +6. **Security, Resilience, and Containment** + - Zero trust, workload isolation, incident simulation, AGI safety kill-switch controls. +7. **Auditability & Evidencing** + - WORM logs, deterministic replay, immutable evidence bundles. +8. **Third-Party & Concentration Risk** + - Cloud/LLM/provider dependency stress tests and exit plans. +9. **Human Oversight & Conduct** + - Human-in-the-loop for adverse decisions and high-impact use cases. +10. **Systemic & Cross-Border Coordination** + - Supervisory reporting and treaty-aligned compute governance hooks. + +--- + +## 3) Regulatory Alignment Matrix (Implementation View) + +| Framework / Rule Set | Implementation Artifacts | Primary Owner | Evidence | +|---|---|---|---| +| EU AI Act | Risk classification workflow, conformity evidence pack, post-market monitoring | Legal + AI Governance | Technical file, risk logs | +| NIST AI RMF 1.0 | Govern/Map/Measure/Manage control library | Enterprise Risk | KRI dashboards, control tests | +| ISO/IEC 42001 | AI management system clauses mapped to SOPs and audits | Compliance | Internal audit reports | +| OECD AI Principles | Trustworthy AI policy and human-centered design controls | Ethics Office | Impact assessments | +| GDPR | DPIA templates, DSAR automation, purpose/retention rules | DPO | DPIA registry, RoPA | +| FCRA/ECOA | Adverse action reasoning and fairness testing | Credit Risk + Legal | Model fairness reports | +| Basel III | Capital-impact model governance and stress control overlays | Treasury + Risk | ICAAP and stress outputs | +| SR 11-7 | Independent validation and challenger model governance | MRM | Validation reports | +| PRA/FCA | SMCR, Consumer Duty control mapping and monitoring | UK Compliance | Conduct dashboards | +| MAS/HKMA | Localized controls and data transfer governance | APAC Compliance | Jurisdiction packs | +| U.S. EO 14110 | Safety testing, watermarking provenance where required, reporting readiness | CISO + AI Governance | Test and assurance packs | + +--- + +## 4) Enterprise AI Reference Architecture (Target State) + +## 4.1 Control Stack + +- **Ingress & Service Mesh:** mTLS, identity-bound requests, policy tags. +- **Model Runtime:** Kubernetes workloads with governance sidecars. +- **Policy Engine:** OPA/Rego admission + runtime authorization hooks. +- **Event Backbone:** Kafka with ACL governance and immutable event contracts. +- **Audit Fabric:** Kafka-to-WORM pipeline with PQC signatures. +- **Evidence Lake:** Deterministic replay artifacts + signed compliance bundles. +- **Explainability Frontend:** Decision rationale cards, reason code APIs, user-facing disclosures. +- **Automation Plane:** Terraform + CI/CD policy gates for “golden environments”. + +## 4.2 Governance Sidecar Pattern + +Each model pod runs a sidecar enforcing: +- prompt/input policy filtering, +- output safety moderation, +- jurisdiction checks, +- runtime risk scoring, +- immutable log streaming. + +## 4.3 Kafka-Based WORM Audit Logging + +- Topic classes: `gov.decision`, `gov.policy_eval`, `gov.explainability`, `gov.incident`. +- Retention: hot (90d), warm (365d), WORM archive (7y+ by policy). +- Integrity: hash chain + post-quantum signatures (e.g., Dilithium profile). +- Replay: deterministic event ordering + model/version checkpoint references. + +## 4.4 Docker Swarm Security (Where Legacy Exists) + +- Mutual TLS between nodes. +- Signed images and admission checks. +- Secret rotation via external vault. +- Compensating controls if migration to Kubernetes is pending. + +--- + +## 5) CI/CD Governance Blueprint (Policy Gates) + +1. **Code Gate:** SAST/SCA/license/legal checks. +2. **Data Gate:** lineage, PII classification, lawful-use assertions. +3. **Model Gate:** reproducibility, hyperparameter bounds, evaluation suite. +4. **Risk Gate:** bias, robustness, adversarial score thresholds. +5. **Compliance Gate:** OPA bundle pass for jurisdiction and sector controls. +6. **Release Gate:** signed approvals (1LOD/2LOD), change ticket links. +7. **Runtime Gate:** canary + live guardrails + rollback policy. + +### Hyperparameter Control Standard + +- Define approved ranges per model family. +- Require change control for production deviations. +- Capture effective hyperparameter snapshots at deploy time. +- Alert on drift from approved envelopes. + +--- + +## 6) Financial Services Model Risk Management (FS-Specific) + +- SR 11-7 aligned model inventory with materiality tiers. +- Pre-approval validation: conceptual soundness, data quality, outcomes analysis. +- Ongoing monitoring: performance, drift, bias, and stability under stress. +- FCRA/ECOA adverse action explainability APIs. +- Basel III integration for capital-impacting models. +- PRA/FCA Consumer Duty outcomes monitoring for customer harm prevention. + +### Minimum FS Model Control Set + +- Independent challenger models. +- Quarterly backtesting for high-materiality models. +- Annual model revalidation or trigger-based immediate review. +- Mandatory incident classification: conduct, prudential, systemic. + +--- + +## 7) AGI/ASI Safety, Containment, and Crisis Preparedness + +## 7.1 Institutional Framework Components + +- **Sentinel AI Governance Platform v2.4:** control orchestration, policy attestations, incident routing. +- **WorkflowAI Pro:** regulated workflow automation with embedded checkpoints. +- **Luminous Engine Codex:** architecture codification and control traceability. +- **Cognitive Resonance Protocol (CRP):** behavior deviation detection and escalation scoring. + +## 7.2 Minimum Viable AGI Governance Stack (MVAGS) + +- Isolated execution enclaves. +- Capability gating and tool-use restrictions. +- Human authorization for high-impact actions. +- Real-time anomaly detection and containment runbooks. +- Emergency stop + staged recovery. + +## 7.3 Crisis Simulation Program + +- Quarterly simulations: model deception, coordinated prompt attack, supply-chain compromise, decision corruption. +- Required outputs: timeline, failed controls, revised runbooks, regulator-notification readiness. + +--- + +## 8) Global AI & Compute Governance Proposals (Operational Mapping) + +Proposals represented as interoperable policy domains: +- ICGC (International Compute Governance Consortium) +- Global compute registries +- Treaty-aligned systemic risk governance +- GACRA, GASO, GFMCF, GAICS, GAIVS, GACP, GATI, GACMO, FTEWS, GAI-SOC, GAIGA, GACRLS, GFCO, GAID, GASCF + +### Enterprise Integration Pattern + +- Register frontier runs above compute threshold. +- Submit standardized safety attestations and incident metrics. +- Maintain export-control and jurisdiction-aware routing controls. +- Integrate systemic telemetry with regulator-facing reports. + +--- + +## 9) Enterprise AI Governance Hub & AI Safety Report Generator + +## 9.1 Governance Hub Logical Components + +- Control Library Service (regulation-to-control mapping) +- Policy Compiler (legal text -> machine rules) +- Runtime Telemetry Bus (Kafka) +- Evidence Vault (WORM + cryptographic attestations) +- Supervisory Reporting API (regulator-ready packs) + +## 9.2 AI Safety Report Generator + +Automated generation of: +- Board reports, +- Regulator technical annexes, +- Incident post-mortems, +- Annual AI governance statements. + +--- + +## 10) Advanced Prompt Engineering & Operational Safety + +- System prompts as controlled artifacts with owner and expiry. +- Prompt threat modeling (injection, leakage, tool abuse). +- Red-team prompt libraries and regression tests. +- Context-window governance for sensitive data classes. +- Prompt provenance logs and signed approvals for high-risk deployments. + +--- + +## 11) Regulator-Ready Technical Report Sections (Tagged Format) + +AGI/ASI Governance Technical Assurance Report +This report provides implementation evidence for enterprise AI governance, AGI safety controls, and jurisdiction-specific regulatory compliance across 2026–2030 operating horizons. + +1. Scope and system boundaries. +2. Applicable regulation and standards mapping. +3. Architecture and control stack description. +4. Validation and challenge methodology. +5. Incident history, residual risk, and remediation plan. +6. Management attestation and independent assurance conclusions. + + +Model Risk & Consumer Impact Annex +Annex focused on model risk lifecycle evidence, fairness outcomes, adverse action explainability, and Consumer Duty impact monitoring. + +1. Model inventory and materiality tiers. +2. Validation findings and limitations. +3. Fairness and explainability metrics. +4. Adverse decision reason-code quality controls. +5. Monitoring thresholds and escalation triggers. + + +--- + +## 12) Implementation Blueprints (Deep Technical) + +## 12.1 Kubernetes + Kafka + OPA Stack + +- OPA sidecar and admission controller for policy enforcement. +- Kafka ACL governance by service account and jurisdiction labels. +- Namespace-level risk segmentation and network policy isolation. + +## 12.2 Terraform-Deployed Golden Environments + +- Immutable baseline modules for dev/test/prod. +- Mandatory policy checks in CI before `terraform apply`. +- Drift detection with signed plan artifacts and weekly reconciliations. + +## 12.3 WORM + PQC-Secured Logs + +- Append-only archive object lock. +- Hash-chain index per event shard. +- PQC signature envelope with periodic key rotation ceremonies. + +## 12.4 zk-SNARK-Based Access Control + +- Prove entitlement without revealing sensitive policy attributes. +- Use in cross-entity evidence sharing and regulator data rooms. + +## 12.5 Deterministic Audit Replay + +- Capture model binary hash, dataset snapshot hash, prompt/context hash, inference config. +- Reconstruct decision outcomes under controlled replay runtime. + +## 12.6 Hyperparameter Drift Analysis + +- Compare approved vs effective deployment values. +- Alert on parameter creep and correlated performance/fairness deviations. + +## 12.7 Adversarial Red Teaming + +- Threat libraries for jailbreaks, indirect prompt injection, model extraction. +- Required remediation SLAs and retest criteria. + +## 12.8 Cognitive Resonance Monitoring + +- Detect divergence between intended policy goals and observed agent behavior. +- Score-based escalation with hard-stop thresholds for high-impact domains. + +## 12.9 Incident Response Checklist (AI-Specific) + +1. Declare severity and assemble cross-functional command. +2. Activate containment policy profile. +3. Preserve immutable evidence and timeline. +4. Notify legal/compliance for reporting obligations. +5. Perform root cause and control remediation. +6. Revalidate before production re-entry. + +--- + +## 13) Tiered Rollout Roadmap (2026–2030) + +- **Tier 1 (2026):** Foundational controls, inventory, policy-as-code baseline, initial WORM. +- **Tier 2 (2027):** Full CI/CD governance gates, deterministic replay, FS MRM hardening. +- **Tier 3 (2028):** Cross-border reporting automation, advanced containment simulation, zk controls. +- **Tier 4 (2029):** Systemic risk telemetry integration and treaty-aligned compute registry connectivity. +- **Tier 5 (2030):** Continuous assurance with adaptive policy orchestration for frontier AI capabilities. + +--- + +## 14) Minimum Program KPIs + +- High-risk model governance coverage ≥ 99%. +- Policy decision latency p99 ≤ 10 ms (critical paths). +- Audit evidence extraction SLA ≤ 24 hours. +- Critical AI incident MTTR ≤ 4 hours. +- Annual independent control assurance pass ≥ 95%. + +--- + +## 15) Machine-Readable Artifacts + +See: `docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml` for: +- control objectives, +- policy gates, +- rollout tiers, +- regulator mappings, +- incident checklist, +- target KPIs. + + +--- + +## 16) Control Catalog (Implementation-Ready) + +| Control ID | Domain | Requirement | Technical Enforcement | Evidence Artifact | +|---|---|---|---|---| +| CTRL-AUTH-001 | Identity | Workload and service identity must be cryptographically verifiable | SPIFFE/SPIRE identities + mTLS + short-lived certs | Identity attestation log | +| CTRL-POL-014 | Compliance | All production inference requests must pass policy checks | OPA sidecar with deny-by-default + signed policy bundles | Policy decision stream | +| CTRL-AUD-021 | Audit | High-risk decisions must be immutably logged within 500ms | Kafka producer ACKS=all + WORM sink connector | Immutable event receipt | +| CTRL-MRM-033 | Model Risk | Material models require independent validation before release | CI/CD gate requiring validator signature token | Validation packet | +| CTRL-EXP-044 | Explainability | Customer-impacting outcomes require reason codes | Explainability API + reason-code templates | Decision card archive | +| CTRL-IR-052 | Incident | Critical incidents require regulator-assessment trigger in <1h | SOAR playbook with legal notification branch | Incident command log | +| CTRL-HP-061 | Hyperparameters | Production hyperparameter changes require approved envelope | Admission check against signed baseline | Hyperparameter drift report | +| CTRL-RED-072 | Security Testing | Quarterly adversarial red-team exercises | Scheduled attack suite + mandatory remediation SLA | Red-team report | +| CTRL-AGI-081 | Containment | High-capability agent actions require multi-party authorization | Capability gateway + quorum approval | Authorization ledger | +| CTRL-SYS-090 | Systemic Risk | Frontier training above compute threshold must be registered | Compute registry API integration | Registry submission proofs | + +--- + +## 17) Compliance-as-Code Example (OPA/Rego) + +```rego +package ai.governance.release + +default allow := false + +high_impact := input.model.materiality == "high" +validation_ok := input.signatures.validator == true +legal_ok := input.attestations.legal == true +risk_ok := input.risk.bias_score <= 0.10 + +allow if { + high_impact + validation_ok + legal_ok + risk_ok +} +``` + +Implementation notes: +- Deploy bundles through signed OCI artifacts. +- Enforce policy bundle provenance in admission controllers. +- Emit policy decision IDs into Kafka for deterministic replay joins. + +--- + +## 18) Deterministic Replay Reference Workflow + +1. Retrieve decision event by immutable ID. +2. Resolve model hash and container digest. +3. Resolve feature/data snapshot hash and lineage references. +4. Replay prompt/context through pinned runtime configuration. +5. Compare observed vs replay output with tolerance windows. +6. Store replay verdict and variance explanation in evidence vault. + +Replay must be possible for all high-impact decisions for the full retention horizon. + +--- + +## 19) Civilizational-Scale Governance Corpus (Program Structure) + +Minimum corpus modules: +- AI constitutional principles and non-negotiable safety constraints. +- Cross-jurisdiction legal ontology and machine-interpretable controls. +- Critical infrastructure risk scenarios (finance, health, energy, public sector). +- Compute concentration and supply-chain dependency models. +- Incident archetype library and transnational escalation protocols. +- Public-interest impact frameworks and human-rights safeguards. + +Operationalization pattern: +- Versioned corpus repository with signed releases. +- Annual external expert review and regulator observer sessions. +- Translation layer from corpus principles to enforceable policy bundles. + +--- + +## 20) Enterprise Rollout by Operating Model + +### 20.1 Fortune 500 (Diversified) +- Federated governance office with shared control library. +- Business-unit delegated approvals under centralized policy constraints. + +### 20.2 Global 2000 (Cross-Border) +- Jurisdiction-aware routing and localized evidence packs. +- Regional legal overlays with global minimum control baseline. + +### 20.3 G-SIFI (Systemic) +- 24x7 model command center, systemic telemetry ingestion, regulator drill cycles. +- Enhanced prudential overlays for capital, liquidity, and conduct outcomes. + +--- + +## 21) Minimum Viable Bill of Materials (MV-BOM) + +- Kubernetes cluster with hardened baseline profiles. +- Kafka cluster with ACL governance and immutability pipeline. +- OPA policy decision point and bundle distribution service. +- WORM evidence store with object lock and PQC signature workflow. +- Explainability API service and decision card UI. +- CI/CD pipeline with signed artifact provenance and release attestations. +- Model registry with validation state machine and retirement controls. + +--- + +## 22) Regulator Submission Packaging Checklist + +- Technical architecture and data-flow diagrams. +- Control mapping matrix by jurisdiction. +- Independent validation and challenge results. +- Fairness, performance, and incident trend metrics. +- Executive attestation and internal audit opinion. +- Reproducible evidence manifest (hashes, timestamps, signatures). + +--- + +## 23) Machine-Readable Package Layout and Validation + +Package layout: +- `docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml` (source-of-truth artifact) +- `docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json` (canonical exported JSON for downstream APIs) +- `docs/artifacts/schemas/enterprise_ai_governance_artifact.schema.json` (schema for contract governance) +- `docs/artifacts/examples/cicd_policy_gate_manifest.yaml` (pipeline gate manifest example) +- `docs/artifacts/examples/regulator_report_template.xml` (tagged report template) +- `scripts/validate_governance_artifact.py` (lightweight validator) + +Recommended automation: +1. Validate artifact on every PR. +2. Rebuild canonical JSON (`make build-governance-json`) and enforce YAML/JSON parity. +3. Assert exported JSON is up to date (`make check-governance-json-clean`). +4. Block merges if required keys or controls are missing. +5. Publish artifact digest and validator output into evidence store. +6. Attach validator output to regulator-ready release bundles. + +--- + +## 24) CI Enforcement Integration + +A dedicated CI workflow is included at: +- `.github/workflows/governance-artifact-validation.yml` + +Workflow behavior: +- Triggers on pushes/PRs touching governance artifact package files. +- Runs package validator (`scripts/validate_governance_artifact.py`). +- Executes validator tests (`pytest -q test_validate_governance_artifact.py test_export_governance_artifact_json.py`) including negative failure scenarios. +- Performs JSON Schema contract validation (`jsonschema`) against the primary YAML artifact. +- Blocks merge when artifact package contract checks fail. +- Uses reproducible dev dependencies from `requirements-dev.txt` and optional `Makefile` targets (`make build-governance-json`, `make check-governance-json-clean`, `make validate-governance`, `make test-governance`). +- Enforces least-privilege CI (`permissions: contents: read`), dependency caching, job timeouts, and concurrency cancellation for reliable governance checks. diff --git a/requirements-dev.txt b/requirements-dev.txt new file mode 100644 index 0000000..3f92544 --- /dev/null +++ b/requirements-dev.txt @@ -0,0 +1,3 @@ +PyYAML==6.0.2 +jsonschema==4.23.0 +pytest==8.3.3 diff --git a/scripts/export_governance_artifact_json.py b/scripts/export_governance_artifact_json.py new file mode 100755 index 0000000..4b8a79a --- /dev/null +++ b/scripts/export_governance_artifact_json.py @@ -0,0 +1,81 @@ +#!/usr/bin/env python3 +"""Export governance YAML artifact to canonical JSON.""" + +from __future__ import annotations + +import argparse +import datetime +import json +from pathlib import Path +import shlex + +import yaml + +from governance_artifact_constants import DEFAULT_JSON, DEFAULT_YAML + +TOOL_VERSION = "1.1.0" + + +def normalize(value: object) -> object: + if isinstance(value, datetime.date): + return value.isoformat() + if isinstance(value, dict): + return {k: normalize(v) for k, v in value.items()} + if isinstance(value, list): + return [normalize(v) for v in value] + return value + + +def fail(message: str) -> None: + raise SystemExit(f"ERROR: {message}") + + +def remediation_command(yaml_rel: str, json_rel: str) -> str: + cmd = "scripts/export_governance_artifact_json.py --root ." + cmd += f" --yaml {shlex.quote(yaml_rel)} --json {shlex.quote(json_rel)}" + return cmd + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser(description="Export governance artifact YAML to JSON") + parser.add_argument("--root", default=".") + parser.add_argument("--yaml", default=DEFAULT_YAML, help="YAML artifact path relative to --root") + parser.add_argument("--json", default=DEFAULT_JSON, help="JSON output path relative to --root") + parser.add_argument("--verify", action="store_true", help="Check whether JSON output is up to date without writing") + parser.add_argument("--version", action="version", version=f"export_governance_artifact_json.py {TOOL_VERSION}") + return parser.parse_args() + + +def main() -> None: + args = parse_args() + root = Path(args.root).resolve() + + yaml_path = root / args.yaml + json_path = root / args.json + + if not yaml_path.exists(): + fail(f"YAML artifact not found: {yaml_path}") + + data = yaml.safe_load(yaml_path.read_text()) + normalized = normalize(data) + rendered = json.dumps(normalized, indent=2, sort_keys=True) + "\n" + + if args.verify: + if not json_path.exists(): + fail(f"JSON artifact not found: {json_path}") + current = json_path.read_text() + if current != rendered: + fail( + "JSON artifact is stale; run " + f"{remediation_command(args.yaml, args.json)}" + ) + print(f"OK: JSON verified {json_path}") + return + + json_path.parent.mkdir(parents=True, exist_ok=True) + json_path.write_text(rendered) + print(f"OK: wrote {json_path}") + + +if __name__ == "__main__": + main() diff --git a/scripts/generate_governance_manifest.py b/scripts/generate_governance_manifest.py new file mode 100755 index 0000000..b838698 --- /dev/null +++ b/scripts/generate_governance_manifest.py @@ -0,0 +1,65 @@ +#!/usr/bin/env python3 +"""Generate or verify a SHA-256 manifest for governance artifact package files.""" + +from __future__ import annotations + +import argparse +import hashlib +import json +from pathlib import Path + +from governance_artifact_constants import DEFAULT_MANIFEST, MANIFEST_TRACKED_FILES + + +def sha256_of(path: Path) -> str: + digest = hashlib.sha256() + with path.open("rb") as f: + for chunk in iter(lambda: f.read(8192), b""): + digest.update(chunk) + return digest.hexdigest() + + +def build_manifest(root: Path) -> dict: + entries = [] + for rel in MANIFEST_TRACKED_FILES: + p = root / rel + if not p.exists(): + raise SystemExit(f"ERROR: missing required artifact file: {rel}") + entries.append({"path": rel, "sha256": sha256_of(p)}) + + return { + "version": 1, + "algorithm": "sha256", + "entries": entries, + } + + +def main() -> None: + parser = argparse.ArgumentParser(description="Generate or verify governance artifact SHA-256 manifest") + parser.add_argument("--root", default=".") + parser.add_argument("--output", default=DEFAULT_MANIFEST) + parser.add_argument("--verify", action="store_true", help="Validate existing manifest content instead of writing") + args = parser.parse_args() + + root = Path(args.root).resolve() + output = root / args.output + manifest = build_manifest(root) + + rendered = json.dumps(manifest, indent=2) + "\n" + + if args.verify: + if not output.exists(): + raise SystemExit(f"ERROR: manifest file missing: {output}") + current = output.read_text() + if current != rendered: + raise SystemExit("ERROR: manifest is stale; run scripts/generate_governance_manifest.py --root .") + print(f"OK: manifest verified {output}") + return + + output.parent.mkdir(parents=True, exist_ok=True) + output.write_text(rendered) + print(f"OK: wrote {output}") + + +if __name__ == "__main__": + main() diff --git a/scripts/governance_artifact_constants.py b/scripts/governance_artifact_constants.py new file mode 100644 index 0000000..0669102 --- /dev/null +++ b/scripts/governance_artifact_constants.py @@ -0,0 +1,18 @@ +"""Shared constants for governance artifact tooling.""" + +from __future__ import annotations + +DEFAULT_YAML = "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml" +DEFAULT_JSON = "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json" +DEFAULT_SCHEMA = "docs/artifacts/schemas/enterprise_ai_governance_artifact.schema.json" +DEFAULT_CICD = "docs/artifacts/examples/cicd_policy_gate_manifest.yaml" +DEFAULT_REPORT = "docs/artifacts/examples/regulator_report_template.xml" +DEFAULT_MANIFEST = "docs/artifacts/manifest.json" + +MANIFEST_TRACKED_FILES = [ + DEFAULT_YAML, + DEFAULT_JSON, + DEFAULT_SCHEMA, + DEFAULT_CICD, + DEFAULT_REPORT, +] diff --git a/scripts/summarize_governance_test_results.py b/scripts/summarize_governance_test_results.py new file mode 100755 index 0000000..eb44386 --- /dev/null +++ b/scripts/summarize_governance_test_results.py @@ -0,0 +1,46 @@ +#!/usr/bin/env python3 +"""Summarize governance JUnit test results for local/CI reporting.""" + +from __future__ import annotations + +import argparse +from pathlib import Path +import xml.etree.ElementTree as ET + +TOOL_VERSION = "1.0.0" + + +def main() -> None: + parser = argparse.ArgumentParser(description="Summarize governance JUnit XML test results") + parser.add_argument( + "--report", + default="artifacts/test-results/governance-tests.xml", + help="Path to JUnit XML report", + ) + parser.add_argument("--version", action="version", version=f"summarize_governance_test_results.py {TOOL_VERSION}") + args = parser.parse_args() + + path = Path(args.report) + if not path.exists(): + raise SystemExit(f"ERROR: report not found: {path}") + + root = ET.fromstring(path.read_text()) + # handle both root and / + suite = root if root.tag == "testsuite" else root.find("testsuite") + if suite is None: + raise SystemExit("ERROR: could not locate testsuite node") + + tests = int(suite.attrib.get("tests", 0)) + failures = int(suite.attrib.get("failures", 0)) + errors = int(suite.attrib.get("errors", 0)) + skipped = int(suite.attrib.get("skipped", 0)) + + summary = ( + f"Governance tests: {tests} total | " + f"{failures} failures | {errors} errors | {skipped} skipped" + ) + print(summary) + + +if __name__ == "__main__": + main() diff --git a/scripts/validate_governance_artifact.py b/scripts/validate_governance_artifact.py new file mode 100755 index 0000000..1689e95 --- /dev/null +++ b/scripts/validate_governance_artifact.py @@ -0,0 +1,278 @@ +#!/usr/bin/env python3 +"""Validator for enterprise AI governance artifact package.""" + +from __future__ import annotations + +import argparse +import datetime +import hashlib +import importlib +import importlib.util +import json +from pathlib import Path +import re +import shlex +import xml.etree.ElementTree as ET +from xml.etree.ElementTree import ParseError + +import yaml + +from governance_artifact_constants import ( + DEFAULT_CICD, + DEFAULT_JSON, + DEFAULT_MANIFEST, + DEFAULT_REPORT, + DEFAULT_SCHEMA, + DEFAULT_YAML, + MANIFEST_TRACKED_FILES, +) + +TOOL_VERSION = "1.1.0" + +REQUIRED_TOP_LEVEL = [ + "meta", + "pillars", + "regulatory_alignment", + "control_stack", + "cicd_policy_gates", + "kpis", + "control_catalog", + "deterministic_replay_workflow", +] + +REQUIRED_CICD_GATES = { + "code_gate", + "data_gate", + "model_gate", + "risk_gate", + "compliance_gate", + "release_gate", + "runtime_gate", +} + + +def fail(msg: str) -> None: + print(f"ERROR: {msg}") + raise SystemExit(1) + + +def ensure_exists(path: Path) -> None: + if not path.exists(): + fail(f"required file missing: {path}") + + +def load_yaml(path: Path) -> object: + return yaml.safe_load(path.read_text()) + + +def load_json(path: Path) -> object: + return json.loads(path.read_text()) + + +def validate_primary_artifact(data: dict) -> None: + if not isinstance(data, dict): + fail("artifact root must be a mapping") + + missing = [k for k in REQUIRED_TOP_LEVEL if k not in data] + if missing: + fail(f"missing required top-level keys: {missing}") + + if len(data["pillars"]) < 5: + fail("expected at least 5 pillars") + if len(data["regulatory_alignment"]) < 5: + fail("expected at least 5 regulatory alignments") + if len(data["cicd_policy_gates"]) < 5: + fail("expected at least 5 CI/CD policy gates") + if len(data["control_catalog"]) < 3: + fail("expected at least 3 controls in catalog") + if len(data["deterministic_replay_workflow"]) < 5: + fail("deterministic replay workflow too short") + + for i, control in enumerate(data["control_catalog"], start=1): + for field in ("id", "domain", "requirement", "enforcement", "evidence"): + if field not in control: + fail(f"control[{i}] missing field: {field}") + + meta = data["meta"] + if not re.match(r"^\d{4}-\d{2}-\d{2}$", str(meta.get("date", ""))): + fail("meta.date must be ISO format YYYY-MM-DD") + + +def validate_schema_contract(schema: dict) -> None: + if not isinstance(schema, dict): + fail("schema file must be a JSON object") + + required = schema.get("required", []) + if not isinstance(required, list): + fail("schema.required must be a list") + + missing = [k for k in REQUIRED_TOP_LEVEL if k not in required] + if missing: + fail(f"schema.required missing expected keys: {missing}") + + +def normalize_for_schema(value: object) -> object: + if isinstance(value, datetime.date): + return value.isoformat() + if isinstance(value, dict): + return {k: normalize_for_schema(v) for k, v in value.items()} + if isinstance(value, list): + return [normalize_for_schema(v) for v in value] + return value + +def validate_against_schema(schema: dict, artifact: dict) -> None: + if importlib.util.find_spec("jsonschema") is None: + fail("jsonschema dependency missing. Install with: pip install -r requirements-dev.txt") + + jsonschema = importlib.import_module("jsonschema") + exceptions = importlib.import_module("jsonschema.exceptions") + + normalized = normalize_for_schema(artifact) + try: + jsonschema.validate(instance=normalized, schema=schema) + except exceptions.ValidationError as exc: + fail(f"schema validation failed: {exc.message}") + + +def validate_cicd_example(manifest: dict) -> None: + if not isinstance(manifest, dict): + fail("CI/CD example must be a mapping") + + gates = manifest.get("required_gates", []) + if not isinstance(gates, list): + fail("required_gates must be a list") + + gate_names = {item.get("name") for item in gates if isinstance(item, dict)} + missing = sorted(REQUIRED_CICD_GATES - gate_names) + if missing: + fail(f"CI/CD example missing required gates: {missing}") + + export = manifest.get("policy_decision_export", {}) + if export.get("sink") != "kafka": + fail("policy_decision_export.sink must be kafka") + + +def validate_report_template(path: Path) -> None: + text = path.read_text().strip() + wrapped = f"{text}" + try: + root = ET.fromstring(wrapped) + except ParseError as exc: + fail(f"report template XML is invalid: {exc}") + + expected = ["title", "abstract", "content"] + tags = [child.tag for child in root] + if tags != expected: + fail(f"report template top-level tags must be {expected}, got {tags}") + + + + + + +def sha256_of(path: Path) -> str: + digest = hashlib.sha256() + with path.open("rb") as f: + for chunk in iter(lambda: f.read(8192), b""): + digest.update(chunk) + return digest.hexdigest() + + +def validate_manifest(root: Path, manifest_path: Path) -> None: + manifest = load_json(manifest_path) + if manifest.get("version") != 1: + fail("manifest version must be 1") + if manifest.get("algorithm") != "sha256": + fail("manifest algorithm must be sha256") + + entries = manifest.get("entries", []) + if not isinstance(entries, list) or len(entries) == 0: + fail("manifest entries must be a non-empty list") + + by_path: dict[str, str] = {} + for entry in entries: + rel = entry.get("path") + expected = entry.get("sha256") + if not rel or not expected: + fail("manifest entries require path and sha256") + if rel in by_path: + fail(f"manifest has duplicate path entry: {rel}") + by_path[rel] = expected + + expected_paths = sorted(MANIFEST_TRACKED_FILES) + observed_paths = sorted(by_path.keys()) + if observed_paths != expected_paths: + fail("manifest entries do not match expected tracked files") + + for rel in expected_paths: + target = root / rel + if not target.exists(): + fail(f"manifest references missing file: {rel}") + actual = sha256_of(target) + if actual != by_path[rel]: + fail(f"manifest hash mismatch for {rel}") + + +def validate_yaml_json_parity(yaml_artifact: dict, json_artifact: dict, artifact_yaml: str, artifact_json: str) -> None: + normalized_yaml = normalize_for_schema(yaml_artifact) + if normalized_yaml != json_artifact: + remediation = ( + "YAML/JSON artifact mismatch: run " + "scripts/export_governance_artifact_json.py --root . " + f"--yaml {shlex.quote(artifact_yaml)} --json {shlex.quote(artifact_json)}" + ) + fail(remediation) + + +def validate_package(root: Path, artifact_yaml: str, artifact_json: str, schema_file: str, cicd_manifest: str, report_template: str, manifest_file: str, skip_manifest: bool) -> None: + artifact_path = root / artifact_yaml + json_artifact_path = root / artifact_json + schema_path = root / schema_file + cicd_path = root / cicd_manifest + report_path = root / report_template + manifest_path = root / manifest_file + + required_paths = [artifact_path, json_artifact_path, schema_path, cicd_path, report_path] + if not skip_manifest: + required_paths.append(manifest_path) + for path in required_paths: + ensure_exists(path) + + artifact = load_yaml(artifact_path) + json_artifact = load_json(json_artifact_path) + schema = load_json(schema_path) + cicd = load_yaml(cicd_path) + + if not skip_manifest: + validate_manifest(root, manifest_path) + validate_primary_artifact(artifact) + validate_yaml_json_parity(artifact, json_artifact, artifact_yaml, artifact_json) + validate_schema_contract(schema) + validate_against_schema(schema, artifact) + validate_cicd_example(cicd) + validate_report_template(report_path) + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser(description="Validate governance artifact package") + parser.add_argument("--root", default=".", help="Repository root path") + parser.add_argument("--yaml", default=DEFAULT_YAML, help="YAML artifact path relative to --root") + parser.add_argument("--json", default=DEFAULT_JSON, help="JSON artifact path relative to --root") + parser.add_argument("--schema", default=DEFAULT_SCHEMA, help="Schema path relative to --root") + parser.add_argument("--cicd", default=DEFAULT_CICD, help="CI/CD manifest path relative to --root") + parser.add_argument("--report", default=DEFAULT_REPORT, help="Report template path relative to --root") + parser.add_argument("--manifest", default=DEFAULT_MANIFEST, help="Manifest path relative to --root") + parser.add_argument("--skip-manifest", action="store_true", help="Skip manifest hash validation") + parser.add_argument("--version", action="version", version=f"validate_governance_artifact.py {TOOL_VERSION}") + return parser.parse_args() + + +def main() -> None: + args = parse_args() + root = Path(args.root).resolve() + validate_package(root, args.yaml, args.json, args.schema, args.cicd, args.report, args.manifest, args.skip_manifest) + print("OK: enterprise AI governance package validation passed") + + +if __name__ == "__main__": + main() diff --git a/test_export_governance_artifact_json.py b/test_export_governance_artifact_json.py new file mode 100644 index 0000000..4a736cf --- /dev/null +++ b/test_export_governance_artifact_json.py @@ -0,0 +1,184 @@ +from pathlib import Path +import json +import subprocess +import sys + +import yaml + + +def run_exporter(root: Path, yaml_path: str | None = None, json_path: str | None = None, verify: bool = False): + script = Path(__file__).resolve().parent / "scripts" / "export_governance_artifact_json.py" + cmd = [sys.executable, str(script), "--root", str(root)] + if yaml_path is not None: + cmd.extend(["--yaml", yaml_path]) + if json_path is not None: + cmd.extend(["--json", json_path]) + if verify: + cmd.append("--verify") + return subprocess.run(cmd, capture_output=True, text=True) + + +def test_exporter_generates_expected_json(tmp_path): + root = tmp_path / "repo" + (root / "docs/artifacts").mkdir(parents=True, exist_ok=True) + + artifact = { + "meta": { + "document_id": "DOC-1", + "version": "1.0", + "date": "2026-04-24", + "horizon": "2026-2030", + "sectors": ["x"], + }, + "pillars": [], + } + yaml_path = root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml" + yaml_path.write_text(yaml.safe_dump(artifact, sort_keys=False)) + + result = run_exporter(root) + + assert result.returncode == 0, result.stdout + result.stderr + json_path = root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json" + assert json_path.exists() + + exported = json.loads(json_path.read_text()) + assert exported["meta"]["document_id"] == "DOC-1" + + +def test_exporter_is_idempotent(tmp_path): + root = tmp_path / "repo" + (root / "docs/artifacts").mkdir(parents=True, exist_ok=True) + yaml_path = root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml" + yaml_path.write_text("meta:\n document_id: DOC-1\n") + + first = run_exporter(root) + assert first.returncode == 0 + json_path = root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json" + first_bytes = json_path.read_bytes() + + second = run_exporter(root) + assert second.returncode == 0 + second_bytes = json_path.read_bytes() + + assert first_bytes == second_bytes + + +def test_exporter_fails_when_yaml_missing(tmp_path): + root = tmp_path / "repo" + result = run_exporter(root) + assert result.returncode != 0 + assert "yaml artifact not found" in (result.stdout + result.stderr).lower() + + +def test_exporter_normalizes_yaml_date_to_string(tmp_path): + root = tmp_path / "repo" + (root / "docs/artifacts").mkdir(parents=True, exist_ok=True) + yaml_path = root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml" + yaml_path.write_text("meta:\n date: 2026-04-24\n") + + result = run_exporter(root) + assert result.returncode == 0, result.stdout + result.stderr + + json_path = root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json" + exported = json.loads(json_path.read_text()) + assert exported["meta"]["date"] == "2026-04-24" + + +def test_exporter_supports_custom_output_path(tmp_path): + root = tmp_path / "repo" + (root / "docs/artifacts").mkdir(parents=True, exist_ok=True) + yaml_path = root / "docs/artifacts/custom.yaml" + yaml_path.write_text("meta:\n document_id: DOC-2\n") + + result = run_exporter(root, yaml_path="docs/artifacts/custom.yaml", json_path="docs/artifacts/custom.json") + assert result.returncode == 0, result.stdout + result.stderr + + out = root / "docs/artifacts/custom.json" + assert out.exists() + exported = json.loads(out.read_text()) + assert exported["meta"]["document_id"] == "DOC-2" + + +def test_exporter_verify_mode_passes_when_json_is_current(tmp_path): + root = tmp_path / "repo" + (root / "docs/artifacts").mkdir(parents=True, exist_ok=True) + yaml_path = root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml" + yaml_path.write_text("meta:\n document_id: DOC-3\n") + + generate = run_exporter(root) + assert generate.returncode == 0, generate.stdout + generate.stderr + + verify = run_exporter(root, verify=True) + assert verify.returncode == 0, verify.stdout + verify.stderr + assert "json verified" in (verify.stdout + verify.stderr).lower() + + +def test_exporter_verify_mode_detects_stale_json(tmp_path): + root = tmp_path / "repo" + (root / "docs/artifacts").mkdir(parents=True, exist_ok=True) + yaml_path = root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml" + yaml_path.write_text("meta:\n document_id: DOC-4\n") + + generate = run_exporter(root) + assert generate.returncode == 0, generate.stdout + generate.stderr + + json_path = root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json" + json_path.write_text("{\"meta\":{\"document_id\":\"mutated\"}}\n") + + verify = run_exporter(root, verify=True) + assert verify.returncode != 0 + assert "json artifact is stale" in (verify.stdout + verify.stderr).lower() + + +def test_exporter_verify_mode_message_includes_custom_paths(tmp_path): + root = tmp_path / "repo" + (root / "docs/artifacts").mkdir(parents=True, exist_ok=True) + yaml_path = root / "docs/artifacts/custom.yaml" + yaml_path.write_text("meta:\n document_id: DOC-5\n") + + generate = run_exporter(root, yaml_path="docs/artifacts/custom.yaml", json_path="docs/artifacts/custom.json") + assert generate.returncode == 0, generate.stdout + generate.stderr + + json_path = root / "docs/artifacts/custom.json" + json_path.write_text("{\"meta\":{\"document_id\":\"mutated\"}}\n") + + verify = run_exporter(root, yaml_path="docs/artifacts/custom.yaml", json_path="docs/artifacts/custom.json", verify=True) + output = verify.stdout + verify.stderr + assert verify.returncode != 0 + assert "--yaml docs/artifacts/custom.yaml" in output + assert "--json docs/artifacts/custom.json" in output + + +def test_exporter_verify_mode_quotes_paths_with_spaces(tmp_path): + root = tmp_path / "repo" + (root / "docs/artifacts/custom dir").mkdir(parents=True, exist_ok=True) + yaml_rel = "docs/artifacts/custom dir/input.yaml" + json_rel = "docs/artifacts/custom dir/output.json" + (root / yaml_rel).write_text("meta:\n document_id: DOC-6\n") + + generate = run_exporter(root, yaml_path=yaml_rel, json_path=json_rel) + assert generate.returncode == 0, generate.stdout + generate.stderr + + (root / json_rel).write_text("{\"meta\":{\"document_id\":\"mutated\"}}\n") + verify = run_exporter(root, yaml_path=yaml_rel, json_path=json_rel, verify=True) + output = verify.stdout + verify.stderr + + assert verify.returncode != 0 + assert "--yaml 'docs/artifacts/custom dir/input.yaml'" in output + assert "--json 'docs/artifacts/custom dir/output.json'" in output + + +def test_exporter_help_command_succeeds(): + script = Path(__file__).resolve().parent / "scripts" / "export_governance_artifact_json.py" + result = subprocess.run([sys.executable, str(script), "--help"], capture_output=True, text=True) + assert result.returncode == 0 + output = (result.stdout + result.stderr).lower() + assert "--yaml" in output + assert "--json" in output + + +def test_exporter_version_command_succeeds(): + script = Path(__file__).resolve().parent / "scripts" / "export_governance_artifact_json.py" + result = subprocess.run([sys.executable, str(script), "--version"], capture_output=True, text=True) + assert result.returncode == 0 + assert "export_governance_artifact_json.py" in (result.stdout + result.stderr) diff --git a/test_generate_governance_manifest.py b/test_generate_governance_manifest.py new file mode 100644 index 0000000..2884cd5 --- /dev/null +++ b/test_generate_governance_manifest.py @@ -0,0 +1,68 @@ +from pathlib import Path +import json +import subprocess +import sys + + +def test_manifest_script_generates_expected_structure(tmp_path): + root = tmp_path / "repo" + (root / "docs/artifacts/examples").mkdir(parents=True, exist_ok=True) + (root / "docs/artifacts/schemas").mkdir(parents=True, exist_ok=True) + + files = { + "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml": "a: 1\n", + "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json": "{}\n", + "docs/artifacts/schemas/enterprise_ai_governance_artifact.schema.json": "{}\n", + "docs/artifacts/examples/cicd_policy_gate_manifest.yaml": "required_gates: []\n", + "docs/artifacts/examples/regulator_report_template.xml": "xy", + } + + for rel, content in files.items(): + p = root / rel + p.parent.mkdir(parents=True, exist_ok=True) + p.write_text(content) + + script = Path(__file__).resolve().parent / "scripts" / "generate_governance_manifest.py" + out = "docs/artifacts/manifest.json" + result = subprocess.run( + [sys.executable, str(script), "--root", str(root), "--output", out], + capture_output=True, + text=True, + ) + assert result.returncode == 0, result.stdout + result.stderr + + manifest = json.loads((root / out).read_text()) + assert manifest["algorithm"] == "sha256" + assert len(manifest["entries"]) == 5 + assert all("sha256" in e for e in manifest["entries"]) + + +def test_manifest_script_verify_mode_detects_stale_manifest(tmp_path): + root = tmp_path / "repo" + (root / "docs/artifacts/examples").mkdir(parents=True, exist_ok=True) + (root / "docs/artifacts/schemas").mkdir(parents=True, exist_ok=True) + + files = { + "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml": "a: 1\n", + "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json": "{}\n", + "docs/artifacts/schemas/enterprise_ai_governance_artifact.schema.json": "{}\n", + "docs/artifacts/examples/cicd_policy_gate_manifest.yaml": "required_gates: []\n", + "docs/artifacts/examples/regulator_report_template.xml": "xy", + } + for rel, c in files.items(): + p = root / rel + p.parent.mkdir(parents=True, exist_ok=True) + p.write_text(c) + + script = Path(__file__).resolve().parent / "scripts" / "generate_governance_manifest.py" + out = "docs/artifacts/manifest.json" + + # generate clean manifest + subprocess.run([sys.executable, str(script), "--root", str(root), "--output", out], check=True) + + # mutate tracked file and verify catches staleness + (root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml").write_text("a: 2\n") + result = subprocess.run([sys.executable, str(script), "--root", str(root), "--output", out, "--verify"], capture_output=True, text=True) + + assert result.returncode != 0 + assert "manifest is stale" in (result.stdout + result.stderr).lower() diff --git a/test_governance_artifact_integrity.py b/test_governance_artifact_integrity.py new file mode 100644 index 0000000..2ed21d9 --- /dev/null +++ b/test_governance_artifact_integrity.py @@ -0,0 +1,34 @@ +from pathlib import Path +import datetime +import json + +import jsonschema +import yaml + + +def normalize(value): + if isinstance(value, datetime.date): + return value.isoformat() + if isinstance(value, dict): + return {k: normalize(v) for k, v in value.items()} + if isinstance(value, list): + return [normalize(v) for v in value] + return value + + +def test_repo_governance_artifact_yaml_json_parity_and_schema(): + root = Path(__file__).resolve().parent + yaml_path = root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml" + json_path = root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json" + schema_path = root / "docs/artifacts/schemas/enterprise_ai_governance_artifact.schema.json" + + yaml_data = yaml.safe_load(yaml_path.read_text()) + json_data = json.loads(json_path.read_text()) + schema = json.loads(schema_path.read_text()) + + assert normalize(yaml_data) == json_data + jsonschema.validate(instance=json_data, schema=schema) + + # sanity checks on key governance fields + assert "pillars" in json_data and len(json_data["pillars"]) >= 5 + assert "regulatory_alignment" in json_data and len(json_data["regulatory_alignment"]) >= 5 diff --git a/test_summarize_governance_test_results.py b/test_summarize_governance_test_results.py new file mode 100644 index 0000000..b801378 --- /dev/null +++ b/test_summarize_governance_test_results.py @@ -0,0 +1,42 @@ +from pathlib import Path +import subprocess +import sys + + +def test_summarize_script_reports_counts(tmp_path): + report = tmp_path / "governance-tests.xml" + report.write_text( + '' + ) + + script = Path(__file__).resolve().parent / "scripts" / "summarize_governance_test_results.py" + result = subprocess.run( + [sys.executable, str(script), "--report", str(report)], + capture_output=True, + text=True, + ) + + assert result.returncode == 0, result.stdout + result.stderr + assert "10 total" in result.stdout + assert "1 failures" in result.stdout + assert "2 skipped" in result.stdout + + +def test_summarize_script_fails_for_missing_report(tmp_path): + missing = tmp_path / "missing.xml" + script = Path(__file__).resolve().parent / "scripts" / "summarize_governance_test_results.py" + result = subprocess.run( + [sys.executable, str(script), "--report", str(missing)], + capture_output=True, + text=True, + ) + + assert result.returncode != 0 + assert "report not found" in (result.stdout + result.stderr).lower() + + +def test_summarize_version_command_succeeds(): + script = Path(__file__).resolve().parent / "scripts" / "summarize_governance_test_results.py" + result = subprocess.run([sys.executable, str(script), "--version"], capture_output=True, text=True) + assert result.returncode == 0 + assert "summarize_governance_test_results.py" in (result.stdout + result.stderr) diff --git a/test_validate_governance_artifact.py b/test_validate_governance_artifact.py new file mode 100644 index 0000000..11de6ec --- /dev/null +++ b/test_validate_governance_artifact.py @@ -0,0 +1,299 @@ +from pathlib import Path +import json +import hashlib +import subprocess +import sys + +import yaml + + +def run_validator(root: Path, extra_args: list[str] | None = None): + cmd = [ + sys.executable, + str(Path(__file__).resolve().parent / "scripts" / "validate_governance_artifact.py"), + "--root", + str(root), + "--skip-manifest", + ] + if extra_args: + cmd.extend(extra_args) + return subprocess.run(cmd, cwd=Path(__file__).resolve().parent, capture_output=True, text=True) + + +def write_valid_package(root: Path): + (root / "docs/artifacts/examples").mkdir(parents=True, exist_ok=True) + (root / "docs/artifacts/schemas").mkdir(parents=True, exist_ok=True) + + artifact = { + "meta": { + "document_id": "MR-AGI-ASI-ENT-2026-2030", + "version": "1.0.0", + "date": "2026-04-24", + "horizon": "2026-2030", + "sectors": ["fortune500"], + }, + "pillars": [{"id": f"P{i}", "name": f"Pillar {i}"} for i in range(1, 6)], + "regulatory_alignment": [{"framework": f"F{i}", "artifacts": ["a"]} for i in range(1, 6)], + "control_stack": {"runtime": {"orchestrator": "kubernetes"}}, + "cicd_policy_gates": [ + "code_gate", + "data_gate", + "model_gate", + "risk_gate", + "compliance_gate", + ], + "kpis": {"k1": ">=99%", "k2": "<=10ms", "k3": "<=24h"}, + "control_catalog": [ + {"id": "C1", "domain": "d", "requirement": "r", "enforcement": "e", "evidence": "x"}, + {"id": "C2", "domain": "d", "requirement": "r", "enforcement": "e", "evidence": "x"}, + {"id": "C3", "domain": "d", "requirement": "r", "enforcement": "e", "evidence": "x"}, + ], + "deterministic_replay_workflow": ["a", "b", "c", "d", "e"], + } + schema = { + "type": "object", + "required": [ + "meta", + "pillars", + "regulatory_alignment", + "control_stack", + "cicd_policy_gates", + "kpis", + "control_catalog", + "deterministic_replay_workflow", + ], + "properties": { + "meta": { + "type": "object", + "required": ["document_id", "version", "date", "horizon", "sectors"], + "properties": { + "document_id": {"type": "string"}, + "version": {"type": "string"}, + "date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}, + "horizon": {"type": "string"}, + "sectors": {"type": "array", "items": {"type": "string"}}, + }, + }, + "pillars": {"type": "array", "minItems": 5}, + "regulatory_alignment": {"type": "array", "minItems": 5}, + "cicd_policy_gates": {"type": "array", "minItems": 5}, + "kpis": {"type": "object", "minProperties": 3}, + "control_catalog": {"type": "array", "minItems": 3}, + "deterministic_replay_workflow": {"type": "array", "minItems": 5}, + }, + } + + manifest = { + "required_gates": [ + {"name": "code_gate"}, + {"name": "data_gate"}, + {"name": "model_gate"}, + {"name": "risk_gate"}, + {"name": "compliance_gate"}, + {"name": "release_gate"}, + {"name": "runtime_gate"}, + ], + "policy_decision_export": {"sink": "kafka"}, + } + + report = """TA
x
""" + + (root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml").write_text( + yaml.safe_dump(artifact, sort_keys=False) + ) + (root / "docs/artifacts/schemas/enterprise_ai_governance_artifact.schema.json").write_text( + json.dumps(schema) + ) + (root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json").write_text( + json.dumps(artifact, sort_keys=True) + ) + (root / "docs/artifacts/examples/cicd_policy_gate_manifest.yaml").write_text(yaml.safe_dump(manifest, sort_keys=False)) + (root / "docs/artifacts/examples/regulator_report_template.xml").write_text(report) + files = [ + "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml", + "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json", + "docs/artifacts/schemas/enterprise_ai_governance_artifact.schema.json", + "docs/artifacts/examples/cicd_policy_gate_manifest.yaml", + "docs/artifacts/examples/regulator_report_template.xml", + ] + entries = [] + for rel in files: + digest = hashlib.sha256((root / rel).read_bytes()).hexdigest() + entries.append({"path": rel, "sha256": digest}) + manifest = {"version": 1, "algorithm": "sha256", "entries": entries} + (root / "docs/artifacts/manifest.json").write_text(json.dumps(manifest)) + + +def test_governance_validator_script_passes_with_minimal_package(tmp_path): + root = tmp_path / "repo" + write_valid_package(root) + result = run_validator(root) + assert result.returncode == 0, result.stdout + result.stderr + assert "validation passed" in result.stdout.lower() + + +def test_governance_validator_fails_on_missing_required_key(tmp_path): + root = tmp_path / "repo" + write_valid_package(root) + + artifact_path = root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml" + artifact = yaml.safe_load(artifact_path.read_text()) + artifact.pop("meta", None) + artifact_path.write_text(yaml.safe_dump(artifact, sort_keys=False)) + + result = run_validator(root) + assert result.returncode != 0 + assert "missing required top-level keys" in (result.stdout + result.stderr) + + +def test_governance_validator_fails_on_bad_cicd_gate(tmp_path): + root = tmp_path / "repo" + write_valid_package(root) + + manifest_path = root / "docs/artifacts/examples/cicd_policy_gate_manifest.yaml" + manifest = yaml.safe_load(manifest_path.read_text()) + manifest["required_gates"] = [g for g in manifest["required_gates"] if g.get("name") != "runtime_gate"] + manifest_path.write_text(yaml.safe_dump(manifest, sort_keys=False)) + + result = run_validator(root) + assert result.returncode != 0 + assert "missing required gates" in (result.stdout + result.stderr) + + +def test_governance_validator_fails_with_readable_schema_error(tmp_path): + root = tmp_path / "repo" + write_valid_package(root) + + artifact_path = root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml" + artifact = yaml.safe_load(artifact_path.read_text()) + artifact["meta"]["date"] = "not-a-date" + artifact_path.write_text(yaml.safe_dump(artifact, sort_keys=False)) + + result = run_validator(root) + assert result.returncode != 0 + assert "meta.date" in (result.stdout + result.stderr) or "schema validation failed" in (result.stdout + result.stderr) + + +def test_governance_validator_fails_with_readable_xml_error(tmp_path): + root = tmp_path / "repo" + write_valid_package(root) + + report_path = root / "docs/artifacts/examples/regulator_report_template.xml" + report_path.write_text("bad<title>") + + result = run_validator(root) + assert result.returncode != 0 + assert "report template xml is invalid" in (result.stdout + result.stderr).lower() + + +def test_governance_validator_fails_on_yaml_json_parity_mismatch(tmp_path): + root = tmp_path / "repo" + write_valid_package(root) + + json_artifact_path = root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json" + json_artifact = json.loads(json_artifact_path.read_text()) + json_artifact["meta"]["version"] = "9.9.9" + json_artifact_path.write_text(json.dumps(json_artifact, sort_keys=True)) + + result = run_validator(root) + assert result.returncode != 0 + assert "yaml/json artifact mismatch" in (result.stdout + result.stderr).lower() + + +def test_validator_help_command_succeeds(): + script = Path(__file__).resolve().parent / "scripts" / "validate_governance_artifact.py" + result = subprocess.run([sys.executable, str(script), "--help"], capture_output=True, text=True) + assert result.returncode == 0 + assert "validate governance artifact package" in (result.stdout + result.stderr).lower() + + +def test_validator_supports_custom_paths(tmp_path): + root = tmp_path / "repo" + write_valid_package(root) + + # move files to custom locations + (root / "custom").mkdir(parents=True, exist_ok=True) + (root / "custom/examples").mkdir(parents=True, exist_ok=True) + (root / "custom/schemas").mkdir(parents=True, exist_ok=True) + + (root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml").replace(root / "custom/artifact.yaml") + (root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json").replace(root / "custom/artifact.json") + (root / "docs/artifacts/schemas/enterprise_ai_governance_artifact.schema.json").replace(root / "custom/schemas/schema.json") + (root / "docs/artifacts/examples/cicd_policy_gate_manifest.yaml").replace(root / "custom/examples/cicd.yaml") + (root / "docs/artifacts/examples/regulator_report_template.xml").replace(root / "custom/examples/report.xml") + (root / "docs/artifacts/manifest.json").replace(root / "custom/manifest.json") + + result = run_validator( + root, + extra_args=[ + "--yaml", "custom/artifact.yaml", + "--json", "custom/artifact.json", + "--schema", "custom/schemas/schema.json", + "--cicd", "custom/examples/cicd.yaml", + "--report", "custom/examples/report.xml", + "--manifest", "custom/manifest.json", + ], + ) + assert result.returncode == 0, result.stdout + result.stderr + + +def test_validator_mismatch_message_uses_custom_paths(tmp_path): + root = tmp_path / "repo" + write_valid_package(root) + + (root / "custom").mkdir(parents=True, exist_ok=True) + (root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.yaml").replace(root / "custom/artifact.yaml") + (root / "docs/artifacts/enterprise_ai_governance_machine_readable_2026_2030.json").replace(root / "custom/artifact.json") + + json_artifact_path = root / "custom/artifact.json" + json_artifact = json.loads(json_artifact_path.read_text()) + json_artifact["meta"]["version"] = "2.0.0" + json_artifact_path.write_text(json.dumps(json_artifact, sort_keys=True)) + + result = run_validator( + root, + extra_args=[ + "--yaml", "custom/artifact.yaml", + "--json", "custom/artifact.json", + ], + ) + assert result.returncode != 0 + output = (result.stdout + result.stderr) + assert "--yaml custom/artifact.yaml" in output + assert "--json custom/artifact.json" in output + + +def test_validator_version_command_succeeds(): + script = Path(__file__).resolve().parent / "scripts" / "validate_governance_artifact.py" + result = subprocess.run([sys.executable, str(script), "--version"], capture_output=True, text=True) + assert result.returncode == 0 + assert "validate_governance_artifact.py" in (result.stdout + result.stderr) + + +def test_validator_enforces_manifest_by_default(tmp_path): + root = tmp_path / "repo" + write_valid_package(root) + + # remove manifest and call validator without --skip-manifest + (root / "docs/artifacts/manifest.json").unlink() + script = Path(__file__).resolve().parent / "scripts" / "validate_governance_artifact.py" + result = subprocess.run([sys.executable, str(script), "--root", str(root)], capture_output=True, text=True) + + assert result.returncode != 0 + assert "required file missing" in (result.stdout + result.stderr).lower() + + +def test_validator_rejects_manifest_with_missing_tracked_entry(tmp_path): + root = tmp_path / "repo" + write_valid_package(root) + + manifest_path = root / "docs/artifacts/manifest.json" + manifest = json.loads(manifest_path.read_text()) + manifest["entries"] = manifest["entries"][:-1] + manifest_path.write_text(json.dumps(manifest)) + + script = Path(__file__).resolve().parent / "scripts" / "validate_governance_artifact.py" + result = subprocess.run([sys.executable, str(script), "--root", str(root)], capture_output=True, text=True) + + assert result.returncode != 0 + assert "manifest entries do not match expected tracked files" in (result.stdout + result.stderr).lower()