PRD-010: AI Governance Runtime

Status: Planned
Version: 1.0
Date: 2025-12-25
Priority: High
Satisfies: [ADR-028, ADR-012]


Overview


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