006-command-surface

The command surface: one binary, every verb the other specs name, and what an exit code means

Lifecycle approvedImplementation in-progressVerification unknownQualification unknown

The binary, and every verb reachable through it. Specs 002 to 005 each describe operator verbs and then own only a library crate, so nothing they specify is runnable. This spec owns crates/statecraft-cli/ and binds those verbs to a process: the command tree, the rule that a command is a thin binding and never a second implementation, the closed exit-code vocabulary that distinguishes a refusal from a failure from a finding, human and --json output as two renderings of one value, and the binary's name being a recorded decision rather than a Cargo default. It also carries the work, run and accept bindings that were specified separately as 009: discovery as a join of two spec-spine reports because one of them does not carry status, inspection as a read-only fold of the run record and nothing else, and the rule that a binding needing a library entry point gets it from the crate that owns the behavior. Section 3.11.1 adds the five verbs 002 sections 3.25 to 3.29 need: inspecting and explicitly upgrading the required harness identity, obtaining the managed-session payload, and recording startup evidence beside submitting qualification evidence for admission.

Read the full pinned specification ↗

Relationships

depends on

depended on by

amended by

Claimed units

establishes

{
  "kind": "directory",
  "path": "crates/statecraft-cli/"
}

extends

{
  "nature": "additive",
  "spec": "003-work-and-run-semantics",
  "unit": {
    "kind": "directory",
    "path": "crates/statecraft-run/"
  }
}

extends

{
  "nature": "additive",
  "spec": "005-acceptance-and-evidence",
  "unit": {
    "kind": "directory",
    "path": "crates/statecraft-acceptance/"
  }
}

Source headings

006: The command surface
1. Purpose
2. Territory
3. Behavior
3.1 The command tree
3.2 A command is a binding, never a second implementation
3.3 The exit-code vocabulary
3.4 Two renderings of one value
3.5 The binary's name is recorded, not defaulted
3.6 What the binary reads, and what it does not
3.7 Observable negative cases
3.8 Discovery is a join, because one report does not carry status
3.9 Inspection is a fold, and reads nothing else
3.10 Placing the work, run and accept verbs in the vocabulary
3.11 A binding needs an entry point, not an implementation
3.11.1 The five verbs spec 002's sections 3.25 to 3.29 need
3.11.2 The sixth verb, and what a qualification exit code distinguishes
3.11.3 The seventh verb, and what `run` adds to its answer
3.11.4 The eighth verb, and the trial section `startup show` gains
3.11.5 The override verbs
3.11.6 The reconcile verb
3.11.7 The transfer verbs
3.11.8 The recover verb
3.12 What the command surface does not unlock
4. Out of scope
5. Resolved decisions
Verification

Frozen anchors

No frozen anchors declared.