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

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)