git.stella-ops.org/docs/implplan/SPRINT_203_cli_iii.md

Sprint 203 - Experience & SDKs · 180.A) Cli.III

BLOCKED Tasks: Before working on BLOCKED tasks, review BLOCKED_DEPENDENCY_TREE.md for root blockers and dependencies.

Active items only. Completed/historic work now resides in docs/implplan/archived/tasks.md (updated 2025-11-08).

[Experience & SDKs] 180.A) Cli.III Depends on: Sprint 180.A - Cli.II Summary: Experience & SDKs focus on Cli (phase III).

Task ID	State	Task description	Owners (Source)
CLI-OBS-51-001	DONE (2025-11-28)	Implemented stella obs top command streaming service health metrics, SLO status, and burn-rate alerts. Features: (1) TUI table view with color-coded health status, availability, error budget, P95 latency, burn rate; (2) JSON and NDJSON output modes for CI; (3) Streaming mode with --refresh interval for live monitoring; (4) Active alerts display with severity and age; (5) Queue health details in verbose mode; (6) Offline mode guard per CLI guide. Created ObservabilityModels.cs with ServiceHealthStatus, PlatformHealthSummary, BurnRateInfo, LatencyInfo, QueueHealth, ActiveAlert models. Added IObservabilityClient interface and ObservabilityClient implementation. Extended CliErrorCodes with ERR_OBS_* codes (exit 14). Registered client in Program.cs.	DevEx/CLI Guild (src/Cli/StellaOps.Cli)
CLI-OBS-52-001	DONE (2025-11-28)	Implemented stella obs trace <trace_id> and stella obs logs --from/--to commands. Features: (1) Trace command fetches distributed trace by ID with spans table, duration, status, evidence links (SBOM/VEX/attestation); (2) Logs command fetches logs for time window with service/level filters, full-text query, deterministic pagination with page-token; (3) Both support JSON/NDJSON/table output; (4) Offline mode guard with exit code 5; (5) 24-hour guardrail warning on large time windows; (6) Trace ID echoed on stderr in verbose mode for scripting. Extended ObservabilityModels.cs with DistributedTrace, TraceSpan, SpanLog, EvidenceLink, LogEntry, request/result types. Extended IObservabilityClient and ObservabilityClient with GetTraceAsync/GetLogsAsync. Added handlers to CommandHandlers.cs.	DevEx/CLI Guild (src/Cli/StellaOps.Cli)
CLI-OBS-55-001	DONE (2025-11-28)	Implemented stella obs incident-mode command group with enable/disable/status subcommands. Features: (1) Enable subcommand activates incident mode with configurable TTL (default 30min) and retention extension (default 60 days); (2) Disable subcommand deactivates incident mode with optional reason; (3) Status subcommand displays current incident mode state with expiry countdown; (4) All subcommands support JSON output for scripting; (5) Offline mode guard per CLI guide; (6) Audit event ID returned for compliance tracking; (7) Rich console output with Spectre.Console panels showing actor, source, timestamps. Extended ObservabilityModels.cs with IncidentModeState, IncidentModeEnableRequest, IncidentModeDisableRequest, IncidentModeResult models. Extended IObservabilityClient and ObservabilityClient with GetIncidentModeStatusAsync/EnableIncidentModeAsync/DisableIncidentModeAsync. Added handlers to CommandHandlers.cs.	DevEx/CLI Guild, DevOps Guild (src/Cli/StellaOps.Cli)
CLI-ORCH-32-001	DONE (2025-11-28)	Implemented stella orch sources list/show commands for orchestrator source management. Created OrchestratorModels.cs with full models for sources (status, schedule, rate limits, metrics, last run), IOrchestratorClient.cs interface, OrchestratorClient.cs HTTP client with OrchRead scope. Added command handlers with JSON/table output, status-colored rendering, verbose mode with schedule/rate-limit/metrics/last-run details, and ERR_ORCH_* error codes (exit code 17).	DevEx/CLI Guild (src/Cli/StellaOps.Cli)
CLI-ORCH-33-001	DONE (2025-11-28)	Implemented stella orch sources test/pause/resume action verbs for orchestrator source management. Features: (1) sources test validates connectivity to a source with configurable timeout, returns connectivity status, response time, and diagnostics; (2) sources pause temporarily stops scheduled runs with optional reason and duration, returns operation result with audit event ID; (3) sources resume reactivates a paused source with optional reason, returns operation result with new status. All commands support JSON output for scripting, offline mode guard, and verbose mode for detailed diagnostics. Extended OrchestratorModels.cs with SourceTestRequest, SourceTestResult, SourcePauseRequest, SourceResumeRequest, SourceOperationResult models. Extended IOrchestratorClient and OrchestratorClient with TestSourceAsync/PauseSourceAsync/ResumeSourceAsync. Added handlers to CommandHandlers.cs.	DevEx/CLI Guild (src/Cli/StellaOps.Cli)
CLI-ORCH-34-001	DONE (2025-11-28)	Implemented stella orch backfill and stella orch quotas command groups. Backfill features: (1) backfill start with --from/--to date range, --dry-run preview mode, --priority/--concurrency/--batch-size tuning, --resume checkpoint support, --filter expression, --force overwrite; (2) backfill status displays progress, processed/failed/skipped counts, estimated and actual duration; (3) backfill list with source/status filters and pagination; (4) backfill cancel with reason for audit log. Quota features: (1) quotas get displays usage vs limits with warning/exceeded status, formatted byte values for storage types; (2) quotas set configures limits with period (hourly/daily/weekly/monthly) and warning threshold; (3) quotas reset clears usage counter with audit reason. All commands support JSON output, verbose mode, and offline mode guard. Extended OrchestratorModels.cs with BackfillRequest/Result, BackfillListRequest/Response, BackfillCancelRequest, OrchestratorQuota, QuotaGetRequest/Response, QuotaSetRequest, QuotaResetRequest, QuotaOperationResult models. Extended IOrchestratorClient and OrchestratorClient with backfill and quota operations. Added handlers to CommandHandlers.cs with Spectre.Console rich output for backfill panels and quota tables.	DevEx/CLI Guild (src/Cli/StellaOps.Cli)
CLI-PACKS-42-001	DONE (2025-11-28)	Implemented stella pack command group with plan/run/push/pull/verify subcommands. Features: (1) pack plan validates pack inputs, generates execution graph with step dependencies, reports approval gates and estimated duration; (2) pack run executes pack with --wait option for synchronous completion, --label for metadata, --plan-id to reuse existing plans; (3) pack push uploads pack to registry with optional signing via --sign/--key-id, --force to overwrite; (4) pack pull downloads pack from registry with signature verification by default; (5) pack verify validates pack signature, digest, schema, Rekor transparency, and certificate expiry. Created PackModels.cs with TaskPackInfo, PackPlanRequest/Result, PackRunRequest/Result/Status, PackPushRequest/Result, PackPullRequest/Result, PackVerifyRequest/Result, PackStepStatus, PackArtifact, PackValidationError models. Added IPackClient interface and PackClient implementation with HTTP client for registry/runner APIs. Extended CliErrorCodes with ERR_PACK_* codes (exit 15). Registered client in Program.cs. Added handlers to CommandHandlers.cs with Spectre.Console rich output for plan tables, run status, and verify panels.	DevEx/CLI Guild (src/Cli/StellaOps.Cli)
CLI-PROMO-70-002	DONE (2025-11-28)	Implemented stella promotion attest and promotion verify commands. Attest signs promotion predicates via cosign/Signer API, produces DSSE bundles, and uploads to Rekor. Verify performs offline verification of DSSE signatures (ECDSA/RSA-PKCS1), material digest comparison (SBOM/VEX), and Rekor inclusion proof validation against trusted checkpoints. Extended PromotionModels.cs with request/result types for attest/verify, added DsseEnvelope/DsseSignature models, implemented AttestAsync/VerifyAsync in PromotionAssembler.cs with PAE encoding, certificate chain verification, and Merkle inclusion proof validation.	DevEx/CLI Guild, Provenance Guild (src/Cli/StellaOps.Cli)
CLI-DETER-70-004	DONE (2025-11-28)	Implemented stella detscore report command to summarise published determinism.json files. Features: (1) Aggregates multiple manifests into unified report with overall/per-image score matrix, (2) Supports markdown/JSON/CSV output formats, (3) Computes summary statistics (average, min/max scores, pass/fail counts), (4) Tracks non-deterministic artifacts across releases, (5) Integrates with release notes and air-gap kits via --output flag. Extended DeterminismModels.cs with DeterminismReportRequest, DeterminismReport, DeterminismReportSummary, DeterminismReleaseEntry, DeterminismImageMatrixEntry, and DeterminismReportResult. Added GenerateReportAsync to IDeterminismHarness interface and implemented in DeterminismHarness.cs with markdown table generation, CSV export, and JSON serialization. Added detscore report command to CommandFactory.cs and HandleDetscoreReportAsync handler to CommandHandlers.cs with Spectre.Console rich output.	DevEx/CLI Guild (src/Cli/StellaOps.Cli)
CLI-PACKS-43-001	DONE (2025-11-28)	Implemented advanced pack features for stella pack command group. Features: (1) pack runs list lists pack runs with status/actor/pack-id filters, pagination, and deterministic ordering; (2) pack runs show displays detailed run status with step progress, artifacts, and timing; (3) pack runs cancel cancels running pack with reason for audit; (4) pack runs pause pauses run at approval gate with optional step targeting; (5) pack runs resume resumes paused run with approve/reject decision and optional comment; (6) pack runs logs retrieves run logs with step/level filters, --tail for last N lines, --since timestamp; (7) pack secrets inject injects secrets from vault/aws-ssm/azure-keyvault/k8s-secret providers with env-var or file path targeting per step; (8) pack cache list displays offline pack cache with size/age/source info; (9) pack cache add pre-fetches pack to local cache for offline execution; (10) pack cache prune cleans cache with --max-age/--max-size/--all options. Extended PackModels.cs with PackRunListRequest/Response, PackCancelRequest, PackApprovalPauseRequest, PackApprovalResumeRequest, PackApprovalResult, PackLogsRequest, PackLogEntry, PackLogsResult, PackSecretInjectRequest/Result, PackArtifactDownloadRequest/Result, PackCacheEntry, PackCacheRequest/Result models. Extended IPackClient and PackClient with 8 new operations. Added handlers to CommandHandlers.cs with Spectre.Console rich output for runs tables, log streaming, and cache management. Dependencies: CLI-PACKS-42-001.	DevEx/CLI Guild (src/Cli/StellaOps.Cli)
CLI-PARITY-41-001	DONE (2025-11-28)	Implemented stella sbom command group with full SBOM explorer and parity matrix features. Commands: (1) sbom list lists SBOMs with filters for image-ref, digest, format (spdx/cyclonedx), creation date range, vulnerability presence, with pagination and determinism score display; (2) sbom show displays detailed SBOM info with --components, --vulnerabilities, --licenses, and --explain options for determinism factors and composition path debugging; (3) sbom compare compares two SBOMs showing component/vulnerability/license diffs with added/removed/modified change tracking; (4) sbom export exports SBOM in SPDX or CycloneDX format with --format-version, --signed attestation, --include-vex options, supports stdout or file output; (5) sbom parity-matrix displays CLI command coverage matrix with deterministic, --explain, and offline capability tracking. Created SbomModels.cs with comprehensive models for SBOM summary/detail, components, vulnerabilities, licenses, attestation, determinism factors, composition path, comparison, export, and parity matrix. Added ISbomClient interface and SbomClient implementation with HTTP client for SBOM APIs. Extended CliError with ERR_SBOM_* codes (exit 18). Registered client in Program.cs. Added handlers to CommandHandlers.cs with Spectre.Console rich output for SBOM tables, detail panels, comparison summaries, and parity matrix display.	DevEx/CLI Guild (src/Cli/StellaOps.Cli)
CLI-PARITY-41-002	DONE (2025-11-28)	Implemented notify command group with comprehensive notification management capabilities. Commands: (1) notify channels list lists notification channels with type/enabled filters, pagination, failure rate display; (2) notify channels show displays detailed channel info with config, stats, health, and labels; (3) notify channels test sends test message to channel with latency and success reporting; (4) notify rules list lists routing rules with event-type/channel/enabled filters; (5) notify deliveries list lists deliveries with status/event-type/channel/date-range filters and pagination; (6) notify deliveries show displays detailed delivery info with attempt history; (7) notify deliveries retry retries failed delivery with idempotency key support; (8) notify send sends notification via rules or direct channel with event-type, subject, severity, metadata, and idempotency key. Created NotifyModels.cs with NotifyChannelListRequest/Response, NotifyChannelSummary/Detail, NotifyChannelConfigInfo/Limits/Stats/Health, NotifyChannelTestRequest/Result, NotifyRuleListRequest/Response/Summary, NotifyDeliveryListRequest/Response, NotifyDeliverySummary/Detail/Attempt, NotifyRetryRequest/Result, NotifySendRequest/Result models. Added INotifyClient interface and NotifyClient implementation with HTTP client supporting Idempotency-Key headers for mutation operations. Extended CliError with ERR_NOTIFY_* codes (exit 19). Registered client in Program.cs. Added handlers to CommandHandlers.cs with Spectre.Console rich output for channel tables, delivery status, health indicators, and attempt history. Note: aoc and auth commands already exist in the CLI. Dependencies: CLI-PARITY-41-001.	DevEx/CLI Guild (src/Cli/StellaOps.Cli)
CLI-SBOM-60-001	DONE (2025-11-28)	Implemented stella sbomer command group for deterministic SBOM composition. Commands: (1) sbomer layer list lists layer fragments for a scan with DSSE signature status; (2) sbomer layer show displays fragment details with --components and --dsse options for components list and DSSE envelope/signature info; (3) sbomer layer verify verifies fragment DSSE signature and content hash with offline mode support; (4) sbomer compose composes SBOM from layer fragments with canonical ordering, emits composition.json manifest and Merkle diagnostics, supports --verify for fragment verification before compose; (5) sbomer composition show displays composition manifest with fragment canonical order and properties; (6) sbomer composition verify verifies composition against manifest, recomputes Merkle root, and validates all fragment signatures with --recompose option; (7) sbomer composition merkle shows Merkle tree diagnostics with leaves and intermediate nodes. Created SbomerModels.cs with SbomFragment, SbomFragmentComponent, DsseEnvelopeInfo, DsseSignatureInfo, MerkleProofInfo, CompositionManifest, CompositionFragmentEntry, MerkleDiagnostics, MerkleLeafInfo, MerkleNodeInfo, request/response/result types. Added ISbomerClient interface and SbomerClient implementation. Extended CliError with ERR_SBOMER* codes (exit 20). Registered client in Program.cs. Added handlers to CommandHandlers.cs with Spectre.Console rich output for layer tables, DSSE signatures, Merkle trees, and composition manifests. Dependencies: CLI-PARITY-41-001, SCANNER-SURFACE-04.	DevEx/CLI Guild (src/Cli/StellaOps.Cli)
CLI-SBOM-60-002	DONE (2025-11-28)	Implemented stella sbomer drift command group with analyze and verify subcommands for drift detection and explanation. Commands: (1) sbomer drift analyze (alias: diff) compares current SBOM against baseline, detects component/ordering/timestamp/key/whitespace drifts, reports determinism-breaking changes with severity levels, supports --explain for detailed root cause analysis with remediation suggestions; (2) sbomer drift verify performs local recomposition from offline kit bundles, validates fragment DSSE signatures (--validate-fragments), checks Merkle proofs (--check-merkle), compares recomposed hash against stored hash, displays offline kit metadata. Extended SbomerModels.cs with SbomerDriftRequest, SbomerDriftResult, DriftSummary, DriftDetail, DriftExplanation, SbomerDriftVerifyRequest, SbomerDriftVerifyResult, OfflineKitInfo models. Extended ISbomerClient and SbomerClient with AnalyzeDriftAsync/VerifyDriftAsync. Added drift subcommands to CommandFactory.cs and handlers to CommandHandlers.cs with Spectre.Console rich output for drift tables, explanation panels, verification status, and offline kit info. Dependencies: CLI-SBOM-60-001.	DevEx/CLI Guild (src/Cli/StellaOps.Cli)
CLI-POLICY-20-001	DONE (2025-11-28)	Implemented stella policy new command for scaffolding new policy files from templates. Features: (1) Creates policy DSL files with metadata, settings, and template-specific rules; (2) Six templates available: minimal (stub), baseline (severity normalization), vex-precedence (VEX handling), reachability (telemetry-aware), secret-leak (secret detection), full (comprehensive); (3) Options: --template/-t for template selection, --description/-d for metadata, --tag for tags, --shadow to enable shadow mode (default), --fixtures to create test fixtures directory, --git-init to initialize Git repository; (4) JSON output support for scripting. Created PolicyWorkspaceModels.cs with PolicyNewRequest, PolicyNewResult, PolicyTemplate enum. Added policy new command to CommandFactory.cs and HandlePolicyNewAsync handler to CommandHandlers.cs with Spectre.Console rich output and next-steps guidance.	DevEx/CLI Guild (src/Cli/StellaOps.Cli)
CLI-POLICY-23-004	DONE (prior)	The stella policy lint command already exists, validating policy DSL files with compiler diagnostics and JSON output support. No additional implementation needed.	DevEx/CLI Guild (src/Cli/StellaOps.Cli)

2025-11-06: CLI enforces --version as mandatory and adds scheduled activation timestamp normalization tests while keeping exit codes intact. CLI-POLICY-23-006 | DONE (2025-11-28) | Implemented stella policy history and stella policy explain commands. History features: (1) Lists policy runs with run ID, version, status, start time, duration, SBOM count, findings generated/changed; (2) Filters: --tenant, --from/--to date range, --status; (3) Pagination with --limit and --cursor; (4) Color-coded status display. Explain features: (1) Shows policy decision tree for component+advisory tuple; (2) Displays subject info (PURL, component, advisory); (3) Shows decision outcome with status, severity, winning rule, rationale; (4) Rule evaluation trace with priority ordering, predicate evaluation details (verbose mode), action execution results, because clauses; (5) Color-coded matched/evaluated/skipped indicators. Extended PolicyWorkspaceModels.cs with PolicyHistoryRequest, PolicyHistoryResponse, PolicyRunSummary, PolicyExplainRequest, PolicyExplainResult, PolicyExplainSubject, PolicyDecision, PolicyRuleTraceEntry, PolicyPredicateEvaluation, PolicyActionResult, PolicyInputContext. Extended IBackendOperationsClient and BackendOperationsClient with GetPolicyHistoryAsync/GetPolicyExplainAsync. Added commands to CommandFactory.cs and handlers to CommandHandlers.cs. Dependencies: CLI-POLICY-23-005. | DevEx/CLI Guild (src/Cli/StellaOps.Cli) CLI-POLICY-27-001 | DONE (2025-11-28) | Implemented policy workspace commands. Commands: (1) stella policy init [path] initializes a policy workspace directory with policy file, test fixtures, README, .gitignore, and optional Git init; (2) stella policy compile <file> compiles policy DSL to IR JSON with digest output, supports --no-ir for validation only, --no-digest, --optimize, --strict (warnings as errors). Init options: --name for policy name, --template for template selection, --no-git/--no-readme/--no-fixtures to skip components. Compile options: --output for IR path, format selection. Edit, lint, and test commands already existed. Created workspace models in PolicyWorkspaceModels.cs: PolicyWorkspaceInitRequest, PolicyWorkspaceInitResult, PolicyCompileRequest, PolicyCompileResult, PolicyDiagnostic. Added commands to CommandFactory.cs and handlers HandlePolicyInitAsync/HandlePolicyCompileAsync to CommandHandlers.cs. Dependencies: CLI-POLICY-23-006. | DevEx/CLI Guild (src/Cli/StellaOps.Cli)