Skip to content

Docs: command/output-format/stability contract docs contradict each other #1944

Description

@codeforester

Goal

Fix internal contradictions in the command-surface/output-format/stability
contract docs so stability-tiers.md and output-formats.md accurately
describe the actual flag and format contracts documented elsewhere.

Background

A documentation review of the reference/contract layer found:

  • docs/stability-tiers.md:81-82 lists --keep-temp among internal flags
    "rejected by basectl" (alongside --debug, --quiet, --config,
    --environment). But docs/command-reference.md:21-25,
    docs/base-cli.md:379-384, and docs/observability.md:169-171 all treat
    basectl --keep-temp <command> as a documented, public wrapper-level flag.
    The same list also omits --log-file, which command-reference.md and
    base-cli.md do list as rejected — this looks like --keep-temp was
    swapped in for --log-file by mistake.
  • docs/stability-tiers.md:49-60 ("Stable JSON contracts") omits run --list/build --list, which docs/command-reference.md:100-101
    explicitly calls a "stable, side-effect-free automation contract" — the
    stability registry is incomplete relative to its own source document.
  • release check's supported output-format contract is contradictory:
    docs/command-reference.md:178 documents the full
    --format <text|csv|tsv|yaml|json> set, but release check is also one of
    the "shared v1 envelope" inspection commands per
    docs/inspection-json.md:7-11; its siblings (repo check, gh issue readiness, gh branch stale) are documented elsewhere as text|json
    only, and docs/output-formats.md:86-88's exceptions section never
    mentions release check, leaving its actual format contract undefined.
  • docs/output-formats.md:90-94's release check CSV/TSV row shape
    (STATUS, NAME, MESSAGE) is never explicitly tied to
    docs/inspection-json.md's nested data.findings[].{status,name,message}
    records, leaving readers to infer how the envelope becomes flat rows.

Scope

  • docs/stability-tiers.md
  • docs/output-formats.md
  • docs/inspection-json.md
  • docs/command-reference.md (only if needed to align wording)

Acceptance Criteria

  • stability-tiers.md's internal/rejected-flag list matches
    command-reference.md/base-cli.md (fix the --keep-temp/
    --log-file mix-up).
  • stability-tiers.md's "Stable JSON contracts" list includes run --list/build --list or explains why it's intentionally excluded.
  • release check's actual supported output formats are stated
    unambiguously in one place and match across command-reference.md,
    output-formats.md, and inspection-json.md.
  • The CSV/TSV row shape for release check is explicitly connected to
    the JSON envelope fields it's derived from.

Validation

git diff --check; if feasible, run basectl release check --format json
and --format csv against a sample project to confirm the documented
contract matches actual output.

Non-Goals

  • Changing actual command behavior — this issue is about correcting the
    documented contract to match (or explicitly reconcile with) reality.

Project Metadata

  • Priority: P1
  • Size: M
  • Area: Docs
  • Initiative: Contract Hardening
  • Agent Assignment: Human first (requires checking actual CLI behavior
    against docs to resolve the release check format ambiguity correctly)

Metadata

Metadata

Assignees

Labels

documentationDocumentation improvements

Type

No type

Projects

Status
Backlog

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions