Skip to content

Commit c259224

Browse files
DTTerastarorca-ide
andcommitted
docs(contract): codify partial-codec policy in §4
§4 enumerated three codecs (markdown, json, csv) without saying whether implementing all three was required. The Status table after PR #10 acknowledges partial-codec exporters (crono and liftoff ship markdown+json, not csv), but a reader who jumps straight to §4 still gets the "all three required" impression. Add explicit language: - CLIs MAY implement a subset. - markdown and json are both REQUIRED — markdown serves human terminal use, json serves agent/script use, omitting either leaves a use case unserved. - csv is recommended but optional. - compat.Runner.SupportedFormats (per PR #10) is the framework affordance that lets a partial-codec exporter wire the bundle. This is mergeable standalone — the policy stands whether or not PR #10's harness affordance has merged. Without #10 the policy is purely documentary; with #10 the policy becomes machine-verifiable. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> Co-authored-by: Orca <[email protected]>
1 parent fcdcded commit c259224

1 file changed

Lines changed: 2 additions & 0 deletions

File tree

CONTRACT.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,8 @@ When neither flag is given, each subcommand picks its own default (typical: `7d`
6767

6868
A single `--format` flag, not separate `--json` / `--csv` flags. `markdown` is the default because terminals are humans by default; agents pass `--format json` once.
6969

70+
CLIs MAY implement a subset of these codecs. A CLI MUST implement `markdown` and `json`; `csv` is recommended but optional. The Status table tracks per-CLI implementation per codec, and `compat.Runner.SupportedFormats` lets the conformance bundle target the declared subset so a partial-codec exporter can adopt the bundle without an immediate `--format csv` failure. Declaring less than `{markdown, json}` is non-conforming — markdown is required for human terminal use, json is required for agent/script use, and either alone leaves one of the two use cases unserved.
71+
7072
Output rules:
7173

7274
- **stdout**: data only, in the requested format.

0 commit comments

Comments
 (0)