statecraft.
Catalog/spec-spine

034-machine-readable-verdicts

Machine-readable verdicts: `--json` on the adjudicating verbs

Lifecycle approvedImplementation completeVerification unknownQualification unknown

The read verbs speak JSON; the verbs that render a verdict do not. `registry` (four subcommands), `index orphans` and `index coverage` have `--json`, while `couple`, `lint`, `compile --check`, `index check`, `attest` and `verify-attestation` emit prose to stdout and nothing else. A programmatic consumer of the gate chain is therefore forced to string-match sentences like `index is fresh` and to infer the reasons for a refusal from formatted text, which is precisely the ad-hoc parsing constitution §II forbids and the governed-artifact-reads rule was written against; the CLI currently leaves no alternative for exactly the commands whose output is a decision. The reports already exist: every one of these verbs is backed by a facade function returning a typed structure, and only the CLI surface is missing. This spec adds `--json` to each of them, behind one versioned envelope (`schemaVersion`, `verb`, `ok`, `exitCode`, and either `report` or `error`) whose `report` member is byte-identical to the corresponding facade output, so a consumer parses one header shape across the whole chain and one payload shape per verb, never two spellings of the same verdict. `--json` changes what is written, never what is decided: the exit code for every outcome is unchanged, and a failure is reported inside the envelope rather than as bare prose on stderr, so the machine consumer's happy path and error path have the same shape.

Read the full pinned specification ↗

Relationships

Claimed units

  • establishes
    {
  "kind": "file",
  "path": "crates/spec-spine-types/src/verdict.rs"
}
  • extends
    {
  "nature": "additive",
  "spec": "001-compile-registry",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/src/cmd_compile.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "001-compile-registry",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/src/main.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "001-compile-registry",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/tests/cli.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "003-conformance-lint",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/src/cmd_lint.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "004-codebase-index",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/src/cmd_index.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "005-coupling-gate",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/src/cmd_couple.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "021-ledger-seal",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/src/cmd_attest.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "021-ledger-seal",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/src/verify_attestation.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "032-stdout-closed-reader",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-cli/src/out.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "000-spec-spine-bootstrap",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-types/src/version.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "000-spec-spine-bootstrap",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-types/src/lib.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "000-spec-spine-bootstrap",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-types/tests/dtos.rs"
  }
}

Source headings

  1. 034: Machine-readable verdicts
  2. 1. Purpose
  3. 2. Territory
  4. 3. Behavior
  5. 3.1 One envelope, one payload per verb
  6. 3.2 `--json` changes what is written, never what is decided
  7. 3.3 Failure is inside the envelope
  8. 3.4 The envelope is versioned
  9. 3.5 Canonical bytes and a closed reader
  10. 3.6 Tests (minimum)
  11. 4. Out of scope
  12. 5. Resolved decisions

Frozen anchors

No frozen anchors declared.