Command-line interfaces are public contract surfaces. A README or
--help screen may help users discover commands, but release
signoff needs a stable command inventory, design intent, contract links,
and verification ownership that reviewers and agents can audit without
reverse-engineering the implementation.
The docs.cli audit scope owns CLI-specific governance:
command inventory, canonical command identity, aliases, deterministic
parser/help parity, design-document coverage, command-design structure,
config contract links, output contract links, compatibility notes, and
migration allowances.
docs.cli does not replace docs.surfaces.
docs.surfaces remains the generic evidence graph for public
behavior: typed verification refs, fixture refs, coverage modes, rationale,
exceptions, parity relationships, local path safety, and external repository
metadata. CLI manifests should either link to governed surfaces with
surface_ref or use the same typed-ref semantics as
docs.surfaces.
Existing repositories may keep a current command manifest such as
docs/contracts/command_manifest.v0.json. The richer portable
CLI contract follows the project stepping convention and should use
command_manifest.a0 semantics. Paths named with
.a0. require schema equal to
"wn_dev_std.command_manifest.a0"; explicitly versioned
.v0. paths remain the legacy migration lane. An a0 command
entry uses a canonical command path so nested subcommands do not collide:
{
"schema": "wn_dev_std.command_manifest.a0",
"commands": [
{
"path": ["plan", "step", "add"],
"name": "plan step add",
"status": "public",
"summary": "Add a structured plan step.",
"design_doc": "docs/design/cli.html",
"data_command": "plan step add",
"surface_ref": "core.cli.plan.step.add"
}
]
}Enforced commands must declare a canonical path or full command name, status, summary or description, and a design reference. Public and experimental commands should also declare a governed-surface link or shared typed evidence refs. Config and output contract refs are required only when the command owns config files, generates config templates, or emits stable machine-readable artifacts.
The a0 manifest shape is validated by the committed JSON Schema contract
docs/contracts/command_manifest.a0.schema.json. The audit code
must not duplicate schema-owned structural checks except as compatibility
handling for declared legacy formats.
| Status | Meaning | Default enforcement |
|---|---|---|
public |
Documented, tested, release-facing command behavior. | Enforced. |
experimental |
Discoverable behavior whose compatibility may still change. | Enforced, with clear compatibility notes. |
deprecated |
Public behavior retained temporarily before removal or replacement. | Enforced, including replacement or removal notes. |
hidden |
Internal or support command outside the public CLI contract. | Not public unless explicitly configured. |
deferred |
Planned or known gap that is not release-ready behavior. | Requires issue, ADR, or exception tracking. |
A command design reference may be a per-command HTML file or an aggregate
CLI design document. Per-command docs may carry command metadata on the
document body or another top-level container. Aggregate docs satisfy
command coverage with elements such as section[data-command].
Both patterns are valid because mature projects may need a separate page
per large workflow while small tools may be clearer as one aggregate page.
Enforced command design docs should cover usage, arguments or options, inputs, config behavior, output artifacts, errors and exit behavior, side effects, compatibility or aliases, and tests. Simple commands may state that a topic is not applicable. The audit checks structural coverage and machine-readable links; reviewers remain responsible for judging whether the prose accurately captures intent.
Parser/help parity should run only when a repository configures a deterministic inventory provider. Providers may be a safe parser object, a static generated inventory, or a controlled command invocation. The audit must not arbitrarily execute project CLIs by default. When a provider is configured, visible parser/help command paths should match the enforced manifest command set and declared aliases.
Linked config and output schemas should live under docs/contracts
and be committed JSON Schema documents. Generated JSONC config templates are
valuable user-facing editing surfaces, but portable generated-template
validation is deferred to project-local signoff or a future generic
contract/template scope unless the project declares deterministic generator
evidence.
README command tables are useful for discoverability, but they are not the authoritative signoff target. The reviewed source of truth is the command manifest, command design docs, linked contracts, and evidence refs. A future optional discoverability check may compare README summaries against the manifest without making README prose the contract.