Structured command contracts are descriptor-first
Decision
Section titled “Decision”Day Shift treats authoritative command descriptors plus versioned structured envelopes as the automation contract. Help text remains an operator surface, not the only machine contract.
Rationale
Section titled “Rationale”Descriptors make aliases, inputs, capability, authorization, effects, availability, examples, and transitions inspectable without executing a command. Typed success/failure envelopes preserve exit classification, retryability, write outcome, findings, completeness, and recovery. Bounded projection and pagination keep large evidence usable without silently pretending it is complete.
Consequences
Section titled “Consequences”Every callable command must maintain descriptor/runtime/tool-manifest alignment. Review and validation remain no-write evidence. Preview, explicit write, destructive, and externally consequential actions remain distinct. Contributors must add drift tests and documentation ownership with the command.
Alternatives rejected: parsing help output as the sole contract, inferring write safety from command names, and returning untyped errors that hide partial-state boundaries.