GenAI Ops Handbook Epic

User Journey

The GenAI Ops bounded context delivers spec-first AI governance through GovernedSpeed™ components, Policy Gateway (SDS-042), and Evidence Service (SDS-043). It enables governance as code, continuous compliance, built-in risk management, and multi-stakeholder design for NIST AI RMF, ISO 42001, EU AI Act, and CPMAI+E frameworks.

Jobs to be Done & EARS Requirements

Job: Configure GovernedSpeed™ Components

User Story: As a platform engineer, I want to configure GovernedSpeed™ components (Policy Gateway, Evidence Service), so that AI governance is enforced in real-time.

EARS Requirement:

While configuring governance, when GovernedSpeed™ is initialized, the genai ops context shall:
1. Policy Gateway Setup:
  - Configure policy enforcement point with OPA/Rego policies
  - Set circuit breaker pattern with configurable fail mode
  - Enable development bypass only via audited opt-in (disabled by default, non-production only, expires automatically)
  - Set timeout and retry parameters
2. Evidence Service Setup:
  - Configure immutable audit trail storage
  - Enable SHA256 hashing for evidence integrity
  - Set retention period per compliance policy (configurable with regulatory guardrails)
  - Configure tamper-evident logging
3. Environment Validation:
  - Run just doctor to verify all components
  - Check connectivity to policy engine
  - Validate evidence storage access
  - Return health status with issues identified

Job: Author Governance Policies as Code

User Story: As a governance author, I want to write policies in SEA™ DSL instead of Word documents, so that policies are machine-readable and testable.

EARS Requirement:

While authoring policies, when a policy is defined in SEA™ DSL, the genai ops context shall:
1. Accept policy declaration with:
  - Policy name and type (Constraint, Obligation, Permission)
  - Priority level (1-100)
  - Rationale annotation for documentation
  - Policy expression using quantifiers and operators
2. Validate Policy:
  - Parse policy expression syntax
  - Verify referenced symbols are in scope
  - Check policy type has required attributes
  - Return validation errors with specific locations
3. Compile to Runtime:
  - Translate SEA™ DSL policy to Rego for OPA
  - Generate policy metadata for Evidence Service
  - Load policy into Policy Gateway
  - Return policy ID and compilation status

Job: Enforce Policy Gateway Filtering

User Story: As a safety engineer, I want Policy Gateway to filter all LLM outputs in real-time, so that harmful content is blocked before reaching users.

EARS Requirement:

While processing LLM requests, when Policy Gateway evaluates a response, the genai ops context shall:
1. Intercept LLM Response:
  - Capture response content before returning to user
  - Extract metadata (model, timestamp, user context)
2. Evaluate Policies:
  - Submit response to policy engine with context
  - Evaluate against all applicable governance policies
  - Check for prohibited content (harm, bias, privacy breaches)
3. Enforce Decision:
  - Allow: Response complies with all policies
  - Block: Response violates policy (return 403 with reason)
  - Modify: Response requires sanitization (filter and return)
  - Escalate: Response requires human review (queue for approval)
4. Log to Evidence Service:
  - Record decision with policy IDs and rationale
  - Store response content (or hash) for audit
  - Include timestamp and user context
  - Generate immutable evidence record

Job: Process Human Review Queue

User Story: As a governance reviewer, I want to process escalated items in a review queue, so that high-risk decisions receive human approval.

EARS Requirement:

While items are escalated, when a review is required, the genai ops context shall:
1. Define reviewers (admin, policy-reviewer, owner) and queue access rules
2. Support assignment modes: manual, round-robin, or rule-based auto-assign
3. Enforce SLA targets: triage <15 minutes, final decision <4 hours
4. Require reviewers to record decision, rationale, and evidence references
5. Handle timeouts with auto-escalation or default deny per policy

Job: Collect Evidence for Compliance

User Story: As a compliance officer, I want Evidence Service to maintain immutable audit trails, so that I can demonstrate regulatory compliance.

EARS Requirement:

While collecting evidence, when a governance event occurs, the genai ops context shall:
1. Generate Evidence Record:
  - Create unique evidence ID
  - Include event type (policy_decision, model_call, user_action)
  - Record actor ID, target ID, and timestamp
  - Add event details as JSON object
2. Hash for Integrity:
  - Calculate SHA256 hash of evidence content
  - Store hash alongside evidence for tamper detection
  - Maintain hash chain for provenance:
    - Include previousHash in every record (genesis block for first record)
    - Store recordHash = SHA256(previousHash + content)
    - Expose validateChain endpoint to verify continuity
    - Detect chain breaks and trigger incident workflow
3. Store Immutable Record:
  - Append to tamper-evident log (append-only)
  - Prevent modification or deletion
  - Enable retrospective queries
4. Return Evidence ID for correlation and retrieval

Job: Run Spec-Guard for Continuous Compliance

User Story: As a developer, I want just spec-guard to validate every commit against governance policies, so that non-compliant code is blocked before merge.

EARS Requirement:

While running CI/CD pipeline, when just spec-guard is executed, the genai ops context shall:
1. Load Governance Policies:
  - Read SEA™ DSL policy files from specs/
  - Compile to runtime format
  - Load into policy engine
2. Validate Changed Specs:
  - Identify modified SEA™ DSL files
  - Parse and validate each file
  - Check for drift from generated code
3. Check Policy Compliance:
  - Verify new specifications comply with governance policies
  - Check for unauthorized invariants or flows
  - Validate required documentation is present
4. Generate Report:
  - List all compliance issues with severity
  - Provide file locations and remediation guidance
  - Return exit code 1 if any critical issues found
5. Block Merge on non-compliance (CI gate)

Job: Detect Architecture Drift

User Story: As an architect, I want to detect when documentation diverges from implementation, so that I can prevent architecture drift.

EARS Requirement:

While validating specs, when drift detection is enabled, the genai ops context shall:
1. Compare Spec to Code:
  - Parse SEA™ DSL specifications
  - Scan generated code files
  - Identify discrepancies between spec and implementation
2. Detect Drift Patterns:
  - Missing entities in code (defined in spec, not implemented)
  - Orphaned code (implemented without spec)
  - Mismatched types or signatures
  - Policy violations in implementation
3. Report Drift:
  - List all drift instances with file locations
  - Calculate drift score (percentage of spec/code alignment)
  - Flag critical drift that blocks deployment
4. Trigger Alert if drift exceeds threshold

Job: Query Semantic Debt Ledger

User Story: As a technical lead, I want to track technical debt as governance artifacts, so that I can measure and prioritize remediation.

EARS Requirement:

While querying debt, when Semantic Debt Ledger is accessed, the genai ops context shall:
1. Aggregate Debt Items:
  - Identify spec-code drift as debt
  - Track policy violations as debt
  - Monitor missing documentation as debt
  - Calculate technical debt interest (compound over time)
2. Categorize Debt:
  - By severity (critical, high, medium, low)
  - By type (architecture, documentation, governance, performance)
  - By age (new, accumulating, stale)
3. Prioritize Remediation:
  - Rank debt items by severity × age
  - Calculate ROI for remediation efforts
  - Recommend order of fixes
4. Return Debt Report with metrics and trends

Job: Configure Kill Switch Response

User Story: As a safety officer, I want <1 second kill switch response for critical AI safety violations, so that I can immediately halt harmful operations.

EARS Requirement:

While monitoring AI operations, when critical invariant violation is detected (SDS-035), the genai ops context shall:
1. Detect Violation:
  - Monitor for SEA™ Invariants violations (see SDS-035 for the 15 non-negotiable controls)
  - Identify critical safety issues (harmful content, data breaches, unauthorized actions)
2. Trigger Kill Switch:
  - Immediately block all AI operations
  - Terminate active LLM requests
  - Disable Policy Gateway pass-through
  - Return error response to all clients
3. Complete Response in <1 second from violation detection to full shutdown
4. Log Incident to Evidence Service with full context

Domain Entities Summary

Root Aggregates

GovernancePolicy: SEA™ DSL policy definition with name, type, priority, rationale, and expression
PolicyDecision: Policy Gateway evaluation result with allow/block/modify decision, policy IDs, and rationale
EvidenceRecord: Immutable audit trail entry with evidence ID, event type, content hash, timestamp, and actor
SemanticDebt: Technical debt item with type, severity, age, interest rate, and remediation priority

Value Objects

PolicyViolation: Specific breach with type, severity, location, and remediation guidance
DriftInstance: Spec-code discrepancy with file location, expected, and actual values
EvidenceHash: SHA256 hash for tamper-evident audit trail
DebtCategory: Debt classification by type (architecture, documentation, governance, performance) and severity

Policy Rules

SpecFirstCode: All code must be generated from specifications, never hand-written
ContinuousCompliance: Every commit must pass just spec-guard before merge
EvidenceImmutability: All evidence records must be tamper-evident and append-only
KillSwitchSpeed: Critical violations must trigger kill switch in <1 second

Integration Points

Policy Gateway (SDS-042): Real-time policy enforcement with OPA/Rego
Evidence Service (SDS-043): Immutable audit trail with SHA256 hashing
SEA™ DSL: Policy as code language for governance definitions
CI/CD Pipeline: Spec-guard integration for continuous compliance
Monitoring Systems: Alerts for critical violations and drift detection

Success Metrics

Documentation Accuracy: 100% (generated from specs, never stale)
Deployment Cycle Time: 40% reduction (governance built-in, not bolted-on)
Compliance Preparation: 90% reduction (always ready, no manual evidence gathering)
Policy Enforcement Latency: <100ms for Policy Gateway evaluation

Non-Functional Requirements

NFR-001: All policies written in SEA™ DSL, version-controlled, and testable
NFR-002: Policy Gateway filters all LLM outputs in real-time
NFR-003: Evidence Service maintains tamper-evident audit trail with configurable retention (per regulatory requirements)
NFR-004: Spec-guard completes validation in <30 seconds for typical diff Justification: retention must be policy-configurable to satisfy regional compliance mandates while preserving tamper-evidence.