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
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)
Goal
Fix internal contradictions in the command-surface/output-format/stability
contract docs so
stability-tiers.mdandoutput-formats.mdaccuratelydescribe the actual flag and format contracts documented elsewhere.
Background
A documentation review of the reference/contract layer found:
docs/stability-tiers.md:81-82lists--keep-tempamong internal flags"rejected by
basectl" (alongside--debug,--quiet,--config,--environment). Butdocs/command-reference.md:21-25,docs/base-cli.md:379-384, anddocs/observability.md:169-171all treatbasectl --keep-temp <command>as a documented, public wrapper-level flag.The same list also omits
--log-file, whichcommand-reference.mdandbase-cli.mddo list as rejected — this looks like--keep-tempwasswapped in for
--log-fileby mistake.docs/stability-tiers.md:49-60("Stable JSON contracts") omitsrun --list/build --list, whichdocs/command-reference.md:100-101explicitly 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:178documents the full--format <text|csv|tsv|yaml|json>set, butrelease checkis also one ofthe "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 astext|jsononly, and
docs/output-formats.md:86-88's exceptions section nevermentions
release check, leaving its actual format contract undefined.docs/output-formats.md:90-94'srelease checkCSV/TSV row shape(
STATUS,NAME,MESSAGE) is never explicitly tied todocs/inspection-json.md's nesteddata.findings[].{status,name,message}records, leaving readers to infer how the envelope becomes flat rows.
Scope
docs/stability-tiers.mddocs/output-formats.mddocs/inspection-json.mddocs/command-reference.md(only if needed to align wording)Acceptance Criteria
stability-tiers.md's internal/rejected-flag list matchescommand-reference.md/base-cli.md(fix the--keep-temp/--log-filemix-up).stability-tiers.md's "Stable JSON contracts" list includesrun --list/build --listor explains why it's intentionally excluded.release check's actual supported output formats are statedunambiguously in one place and match across
command-reference.md,output-formats.md, andinspection-json.md.release checkis explicitly connected tothe JSON envelope fields it's derived from.
Validation
git diff --check; if feasible, runbasectl release check --format jsonand
--format csvagainst a sample project to confirm the documentedcontract matches actual output.
Non-Goals
documented contract to match (or explicitly reconcile with) reality.
Project Metadata
against docs to resolve the
release checkformat ambiguity correctly)