# CI/CD Gate Exit Code Convention

## Module
Policy

## Status
VERIFIED

## Description
Standardized CI exit code convention for gate evaluation: 0=Pass, 1=Warn (configurable pass-through), 2=Fail/Block, 10+=errors. The `stella gate evaluate` CLI command returns these exit codes, enabling direct CI/CD pipeline integration without parsing output.

## Implementation Details
- **PolicyGateEvaluator**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateEvaluator.cs` -- `PolicyGateEvaluator` (sealed class implements `IPolicyGateEvaluator`)
  - Sprint: SPRINT_20251226_001_BE_cicd_gate_integration
  - `EvaluateAsync(PolicyGateRequest)` returns `PolicyGateDecision` with decision type: Allow, Warn, Block
  - Evaluates gates in sequence: Evidence Completeness -> Lattice State -> VEX Trust -> Uncertainty Tier -> Confidence Threshold
  - Short-circuits on first Block (subsequent gates skipped)
  - Override support: `AllowOverride` with `OverrideJustification` and minimum length validation
- **PolicyGateDecision**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateDecision.cs` -- decision model
  - `PolicyGateDecisionType`: Allow, Warn, Block
  - Contains: GateId, RequestedStatus, Subject, Evidence, Gates (array of results), Advisory, BlockedBy, BlockReason, Suggestion
- **PolicyGateResultType**: Pass, PassWithNote, Warn, Block, Skip -- per-gate evaluation outcomes
- **Exit Code Mapping** (CLI integration):
  - Allow -> exit 0 (CI pass)
  - Warn -> exit 1 (CI configurable: pass-through or soft fail)
  - Block -> exit 2 (CI hard fail)
  - Error/Exception -> exit 10+ (CI infrastructure error)
- **Gate Types**:
  - Evidence Completeness Gate: requires graphHash (DSSE-attested) and pathAnalysis for not_affected
  - Lattice State Gate: checks lattice state compatibility (CU allows not_affected; SR/RO/CR block not_affected)
  - VEX Trust Gate: minimum composite score and signature verification per environment
  - Uncertainty Tier Gate: T1 blocks not_affected, T2 warns, T3 note, T4 pass
  - Confidence Threshold Gate: warns below min confidence for not_affected
- **PolicyGateOptions**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateOptions.cs` -- configuration for gate thresholds
- **CLI Gate Command**: `src/Cli/StellaOps.Cli/Commands/` -- `stella gate evaluate` translates decision type to process exit code
- **Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/PolicyDecisionEndpoint.cs` -- HTTP API for gate evaluation

## E2E Test Plan
- [x] Run `stella gate evaluate` with a passing scenario (all evidence present, CU lattice state, T4 uncertainty); verify exit code 0
- [x] Run `stella gate evaluate` with a warning scenario (SU lattice state for not_affected); verify exit code 1
- [x] Run `stella gate evaluate` with a blocking scenario (no graphHash for not_affected); verify exit code 2
- [x] Run `stella gate evaluate` with invalid input (missing required arguments); verify exit code >= 10
- [x] POST to policy decision endpoint with Block decision; verify response includes `blockedBy`, `blockReason`, and `suggestion`
- [x] POST with `AllowOverride=true` and valid justification; verify overridden Block becomes Warn with advisory message
- [x] POST with `AllowOverride=true` but justification too short; verify Block is not overridden
- [x] Verify VEX Trust gate returns Block when trust score below threshold for production environment
- [x] Verify CI pipeline integration: use exit code in `if` statement to gate deployment

## Verification
- **Run ID**: run-002
- **Date**: 2026-02-12
- **Result**: PASS - 708/708 tests pass. 41 targeted test methods across CicdGateIntegrationTests and PolicyGateEvaluatorTests verify exit code mapping (Allow=0, Warn=1, Block=2), 5-gate pipeline, EvidenceCompleteness, LatticeState, UncertaintyTier gates, override mechanism with justification validation, disabled gates, batch evaluation, and audit trail.