git.stella-ops.org/docs/features/checked/policy/ci-cd-gate-exit-code-convention.md

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

• Run stella gate evaluate with a passing scenario (all evidence present, CU lattice state, T4 uncertainty); verify exit code 0
• Run stella gate evaluate with a warning scenario (SU lattice state for not_affected); verify exit code 1
• Run stella gate evaluate with a blocking scenario (no graphHash for not_affected); verify exit code 2
• Run stella gate evaluate with invalid input (missing required arguments); verify exit code >= 10
• POST to policy decision endpoint with Block decision; verify response includes blockedBy, blockReason, and suggestion
• POST with AllowOverride=true and valid justification; verify overridden Block becomes Warn with advisory message
• POST with AllowOverride=true but justification too short; verify Block is not overridden
• Verify VEX Trust gate returns Block when trust score below threshold for production environment
• 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.