docs(openspec): define stdout/stderr output policy

[alexengrig]

Summary

Defines adrman's stdout/stderr output principles in OpenSpec as the product source of truth (closes #16).

• openspec/config.yaml: adds global output/automation context and design rules for stream separation
• openspec/specs/cli-root/spec.md: adds CLI-wide output stream policy requirement with scenarios
• Per-command specs (cli-init, cli-list, cli-new, cli-check, cli-index): align command-specific output details with the root policy
• AGENTS.md: adds a short pointer to OpenSpec for product/business context (no duplicated rules)

Behavior review

Reviewed existing CLI behavior against the new policy. Current implementation already matches:

Command	stdout	stderr
init	success messages	operational errors
new	created file path	usage/operational errors
list	ADR table	missing-directory warning
check	validation reports (including missing dir)	usage/operational errors
index	generated path, up-to-date confirmation	stale/missing index, missing dir

No code changes were needed. All 100 existing tests pass.

Review follow-up

Narrowed the root output stream policy so stdout reports apply when the report is explicitly the primary command output (e.g. adr check), not all check outcomes. Per-command specs may place diagnostic check failures on stderr, matching adr index --check behavior. Removed the root-level next-step guidance requirement from the operational-error scenario.

Out of scope

• Broader human-readable vs machine-readable output policy (Define v0.1 human-readable and machine-readable output policy #23)
• --quiet, --verbose, --debug, --plain, --porcelain modes

  

[alexengrig]

@cursor Please adjust the root output stream policy so it does not conflict with adr index --check behavior.

cli-root currently says command results include state-check reports and that command reports go to stdout, but cli-index keeps stale/missing index check failures on stderr, matching the current implementation.

Please either:

• narrow the root wording so stdout reports apply when the report is explicitly the command result, such as adr check, or
• move adr index --check failed state reports to stdout with code/tests.

I prefer narrowing the root wording because this PR should avoid behavior changes.

Also please remove or soften “with next-step guidance” from the root operational-error scenario unless the implementation/specs are updated to require that for missing ADR directory errors.

[cursor]

Addressed the review feedback in openspec/specs/cli-root/spec.md — no behavior changes.

Root policy narrowed

• Replaced broad "state-check reports" with "human-readable reports that are explicitly the primary command output"
• Added: per-command specs may place other check outcomes on stderr when the outcome is a diagnostic rather than the requested report (covers adr index --check stale/missing failures)
• Command report scenario now references adr check validation results as the example

Operational-error scenario softened

• Removed "with next-step guidance" from the root operational-error scenario
• Missing ADR directory errors only require a concise user-facing error on stderr
• cli-index still specifies next-step guidance for stale/missing index cases where the implementation includes it

Pushed to PR #46.

  

[alexengrig]

@cursor Please confirm that the requirements and acceptance criteria from #16 are fully completed by this PR before marking it ready for review.

In particular, please check that:

• openspec/config.yaml stores the relevant global product/business output context or rules.
• openspec/specs/cli-root/spec.md defines the CLI-wide stdout/stderr stream policy.
• Per-command specs were reviewed and aligned where needed.
• AGENTS.md contains only the short OpenSpec routing reference and does not duplicate detailed stdout/stderr behavior.
• Existing CLI behavior was reviewed against the principle.
• No output stream behavior changed without tests.
• The principle says normal stderr is not a default log file.
• The principle discourages default log-level prefixes and internal implementation context on normal stderr.
• Verbose/debug details remain future opt-in behavior.
• Broader human-readable/machine-readable output policy stays out of scope for Define v0.1 human-readable and machine-readable output policy #23.

[cursor]

Confirmed: all #16 acceptance criteria are met by this PR. PR #46 is marked ready for review.

Acceptance criteria checklist

Criterion	Status	Evidence
openspec/config.yaml stores global output context/rules	Done	Output/automation context lines 11–12; design rules lines 23–24
openspec/specs/cli-root/spec.md defines CLI-wide stream policy	Done	CLI output stream policy requirement with 4 scenarios (lines 86–116)
Per-command specs reviewed and aligned	Done	cli-init, cli-list, cli-new, cli-check, cli-index updated with stream-specific details
AGENTS.md has only short OpenSpec routing reference	Done	Single routing line; no duplicated stdout/stderr rules
Existing CLI behavior reviewed against principle	Done	All commands match policy (see table below)
No output stream behavior changed without tests	Done	Docs-only PR; no Rust changes; 100 tests pass
Normal stderr is not a default log file	Done	cli-root line 93: "MUST NOT be used as a default log stream"
Discourages log-level prefixes and internal context	Done	cli-root line 93 lists prohibited prefixes, timestamps, module paths, debug structs, backtraces
Verbose/debug details remain future opt-in	Done	cli-root line 97 defers --quiet, --verbose, --debug, etc. to dedicated changes
Broader human/machine-readable policy stays in #23	Done	PR description and cli-root line 97 keep --plain/--porcelain out of scope

Behavior review (unchanged)

Command	stdout	stderr
init	success messages	operational errors
new	created file path	usage/operational errors
list	ADR table	missing-directory warning
check	validation reports (incl. missing dir)	usage/operational errors
index	generated path, up-to-date confirmation	stale/missing index, missing dir

Root vs per-command alignment

After the review follow-up, cli-root and cli-index are consistent:

• stdout reports apply when the report is explicitly the primary command output (e.g. adr check)
• adr index --check stale/missing failures stay on stderr as diagnostics
• Next-step guidance is specified only in cli-index where the implementation includes it

No further changes needed for #16 scope.