PRD-010: AI Governance Runtime
Status: Planned
Version: 1.0
Date: 2025-12-25
Priority: High
Satisfies: [ADR-028, ADR-012]
Overview
- Feature: Runtime AI governance platform with inline policy enforcement
- Business Value: Enables safe, auditable AI deployment without sacrificing delivery velocity
- Target Users: MLOps engineers, governance leads, compliance officers, AI/ML teams
Requirements
REQ-GS-001: Pre-Commit Governance Gate
| Field |
Value |
| REQ-ID |
REQ-GS-001 |
| Type |
functional |
| EARS |
When a developer attempts to merge code, the system shall validate governance thresholds and block the merge if any threshold is violated. |
| Bounded-Context |
developer-tooling |
| Data Touched |
EvaluationArtifact, ThresholdConfig |
| Invariants |
INV-GS-003, INV-GS-004, INV-GS-005, INV-GS-006 |
Acceptance Criteria (Given/When/Then):
1
2
3
4
5
6
| Given evaluation artifacts exist in the artifacts/ directory
When the developer runs the pre-commit governance check
Then the system validates each metric against its threshold
And blocks the merge if any metric exceeds its threshold
And returns a detailed violation report
And INV-GS-003 (fail-closed) holds
|
Idempotency Requirement:
| Aspect |
Specification |
| Repeatable? |
yes |
| Safe to retry? |
yes |
| Dedup strategy |
N/A (read-only check) |
REQ-GS-002: Runtime Prompt Filtering
| Field |
Value |
| REQ-ID |
REQ-GS-002 |
| Type |
functional |
| EARS |
When a prompt is submitted to the Policy Gateway, the system shall evaluate all applicable policy rules and return an allow/block/safe_mode decision with reasons. |
| Bounded-Context |
cognitive-extension |
| Data Touched |
PromptRequest, PolicyRule, FilterDecision |
| Invariants |
INV-GS-001 |
Acceptance Criteria (Given/When/Then):
1
2
3
4
5
| Given a prompt containing PII without lawful basis
When the prompt is submitted to POST /filter/prompt
Then the system returns {"allowed": false, "action": "block", "reasons": ["PII without lawful basis"]}
And the decision is logged for audit
And INV-GS-001 (sidecar enforcement) holds
|
Idempotency Requirement:
| Aspect |
Specification |
| Repeatable? |
yes |
| Safe to retry? |
yes |
| Dedup strategy |
N/A (stateless decision) |
REQ-GS-003: Evidence Artifact Submission
| Field |
Value |
| REQ-ID |
REQ-GS-003 |
| Type |
functional |
| EARS |
When an evaluation artifact is submitted to the Risk & Evidence Service, the system shall compute a SHA256 hash and store the artifact with tamper-evident metadata. |
| Bounded-Context |
architectural-governance |
| Data Touched |
EvidenceArtifact, EvidenceHash, AuditLog |
| Invariants |
INV-GS-002 |
Acceptance Criteria (Given/When/Then):
1
2
3
4
5
6
| Given a valid evaluation artifact JSON
When the artifact is submitted to POST /evidence
Then the system computes SHA256 hash of the content
And stores the artifact with timestamp and hash prefix "sha256:"
And returns a unique artifact ID
And INV-GS-002 (SHA256 hashing) holds
|
Idempotency Requirement:
| Aspect |
Specification |
| Repeatable? |
yes |
| Safe to retry? |
yes |
| Dedup strategy |
Content hash deduplication |
REQ-GS-004: Governance Metrics Exposure
| Field |
Value |
| REQ-ID |
REQ-GS-004 |
| Type |
nonfunctional |
| EARS |
The system shall expose governance metrics via OpenTelemetry (OTLP) and a /metrics endpoint for real-time observability. |
| Bounded-Context |
shared |
| Data Touched |
GovernanceMetric |
| Invariants |
N/A |
Acceptance Criteria (Given/When/Then):
1
2
3
4
| Given the Risk & Evidence Service is running
When GET /metrics is called
Then the response includes llm_pass_at_5, fairness_subgroup_delta, harmful_output_rate, drift_psi gauges
And the response format is OpenTelemetry-compatible (OTLP or Prometheus text)
|
Idempotency Requirement:
| Aspect |
Specification |
| Repeatable? |
yes (inherent) |
| Safe to retry? |
yes |
| Dedup strategy |
N/A |
REQ-GS-005: Drift Detection and Retraining Trigger
| Field |
Value |
| REQ-ID |
REQ-GS-005 |
| Type |
functional |
| EARS |
When data drift (PSI) exceeds 0.2, the system shall generate a retraining alert and log the drift event. |
| Bounded-Context |
cognitive-extension |
| Data Touched |
DriftMetric, RetrainingAlert |
| Invariants |
INV-GS-007 |
Acceptance Criteria (Given/When/Then):
1
2
3
4
5
| Given model monitoring is active
When PSI metric exceeds 0.2
Then the system emits a DriftDetected alert
And logs the drift event with model version and PSI value
And INV-GS-007 (drift threshold) holds
|
Idempotency Requirement:
| Aspect |
Specification |
| Repeatable? |
yes |
| Safe to retry? |
yes |
| Dedup strategy |
Alert deduplication by model version + time window |
Success Metrics
| KPI |
Target |
Measurement Method |
| Deployment cycle time |
40% reduction |
CI/CD pipeline telemetry |
| Policy violation detection rate |
> 95% pre-production |
Gate failure logs |
| Audit evidence completeness |
100% artifacts hashed |
RES artifact audit |
| False positive rate (blocking) |
< 5% |
Manual review of blocked deploys |
Dependencies
- Depends on: ADR-028, SDS-047, SDS-047
- Blocks: Production LLM deployment workflows
- ADR: ADR-028
- SDS: SDS-047, SDS-047
- Reference: REF-020