Check reference

Check a CLI command's contract footprint

A command can gain flags and subcommands faster than its requirements, help, and tests evolve. contract_alignment_clean highlights that mismatch in Proof's own CLI source layout.

What the check observes

The analyzer scans Go command files under cmd/proof, recognizes Cobra command declarations, and counts public-surface indicators such as flags, subcommands, and configuration keys. It compares this footprint with requirement references, help coverage, and command tests. Files below a surface score of eight are skipped; larger surfaces use additional thresholds for requirement references and dedicated tests. This is a static heuristic for this repository structure. It is not a general API contract verifier for every application or language.

Example: a command grows several new modes

Illustrative case. A command file adds retry policy flags and new subcommands while keeping one broad requirement reference and no dedicated command tests. The finding is a prompt to inspect which public decisions remain unspecified.

Command surface to review:
  retry count and timeout interaction
  invalid flag combinations
  exit status on exhausted retries
  help text for defaults and errors

Evidence to inspect:
  governing requirements, command help, command tests

Resolve the finding

Open the named command file and enumerate the behavior exposed by its flags and subcommands.
Write or refine the actual requirements, document the public contract, and add tests for meaningful outcomes and invalid combinations.
Rerun the lint check and inspect its remaining diagnostics. Do not add empty test files or unrelated requirement IDs merely to increase the footprint.

Run and interpret

proof lint --check contract_alignment_clean --format json

The check reports a static contract-footprint warning. Its source-layout assumptions matter: a project without the expected command directory is not meaningfully assessed by this analyzer.

Counts and file presence cannot establish that documentation is accurate or that tests exercise the promised behavior. A small surface can still contain a serious defect, and a large well-documented surface can still be wrong. Use the result to focus review, then run the relevant execution checks.

Continue from here

Design tests from the contract. Review requirement and implementation together.

Bring a command whose new options have become difficult to specify or test consistently. Bring a change to Proof.