CLI Install & Update Integrity (v1) — 2025-12-01

Implementation status: the requirements below are a draft, not a delivered release contract. The current CLI supports local manifest verification and planning through self update; package application is unsupported and fails nonzero before package or health claims. --check and --dry-run always require a signed local manifest and real trust inputs; their plan/version comes only from that verified manifest. --version asserts the manifest version, and --force fails. No agent rollback command is registered; the unused sample factory was removed under PCD-293. The checksum, installer, package-signature, application and rollback requirements below remain draft requirements rather than delivered CLI behavior.

Manifest-check source verified against commit e25dab6fa702d22df9ddcf0445310645cbbc2c11 (PCD-389). Re-verify the implemented check/plan boundary with pwsh ./tools/scripts/test-targeted-xunit.ps1 -Project src/Cli/__Tests/StellaOps.Cli.Tests/StellaOps.Cli.Tests.csproj -Class '*AgentSelfUpdateVerifyTests' -BuildProjectReferences -MaxThreads 1. This verification stamp does not apply to the draft installer/application requirements.

Requirements

• Checksums: Every release publishes stellaops-cli-$version.tar.zst with SHA256SUMS + detached .sig.
• Verification: stella install and stella self-update run cosign verify by default against pinned public key fingerprint; --skip-verify prohibited.
• Offline: Provide install-offline.sh that reads from kit directory with checksum + signature checks only; no network fetches.
• Buildx plugin: pin image digest (see cli-spec-v1.yaml); implement a real rollback before exposing it in help.

Failure modes

• Missing checksum/signature → command fails with exit code 21 and structured error.
• Digest mismatch → command fails with exit code 22; log path to offending file.

Artifacts

• Public key fingerprints recorded in cli-spec-v1.yaml.
• Example verify script to be bundled in release kit: scripts/cli/verify-install.sh.