P7.MRD.001 — Exit codes are documented when the repository ships a CLI

Field	Value
Principle	P7 (Machine-readability)
Severity	warn
Evidence	strong
Stability	experimental

What it checks

The rule triggers when the repository has a cmd/, bin/, or exe/ directory containing at least one source file (.go, .py, .ts, .js, .rs, .rb, .java, .kt, .swift, .php, .sh) — a strong signal of a binary entrypoint. It then looks for exit-code documentation at one of:

• docs/exit-codes.md
• docs/EXIT_CODES.md
• docs/exit_codes.md
• EXIT_CODES.md (root)

If the repo ships a CLI but none of those paths exist, the rule fires.

Why it matters

Machine-readability (P7) is what lets an agent drive a CLI reliably. Exit codes are the lowest-bandwidth signal the CLI emits; if they aren't documented, agents either guess or invent retry policies that don't match reality. A documented exit-code contract also forces the author to think about which failure modes are part of the API surface — most of the time, the answer is "more than I realized."

When to care

• Care always for a public or shared CLI.
• Care less for internal one-off scripts. Suppress with a rationale.

How to fix

Create docs/exit-codes.md listing every exit code the CLI may emit, its meaning, and whether it is part of the stability contract. archfit's own docs/exit-codes.md is a reasonable starting template.

Suppressing this rule

ignore:
  - rule: P7.MRD.001
    reason: "Private bootstrap script; no machine consumer"
    expires: 2026-10-01

History

• 0.1.0 — introduced at stability: experimental.