Ground every ADR in principles, not development history

An ADR is read by someone deciding whether a change fits the design, who
has never seen the branch that produced it and cannot reconstruct a state
of the world that no longer exists. A passage turning on what the package
used to do asks them to hold exactly that, and ages into lines that teach
nothing once the thing being contrasted against is releases gone.

Restates every such passage across the fifteen records as a property that
holds now. Rejected alternatives stay -- relitigating them is what the
record prevents -- but as standing arguments against designs a reader
might propose again rather than as accounts of attempts: per-command
stream setters, desc as a parsing stage, a Negatable field on the
compiled flag, an unexported ir, and embedding a description into the
implementation type.

Amendment notes fold into the documents they qualify, with any content
only they carried moving into the body. Status lines keep their dates.

Also records in registries-carry-library-contributions that the pairing
of a flag with its wrapper is a convention the package cannot enforce.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: cavaliercoder

docs/adr/argument-errors-print-usage.md

@@ -63,22 +63,21 @@ output formatted differently has `UsageFunc`.
 Exit codes and prefixes are untouched. The three-code contract in
 `docs/adr/exit-code-contract.md` and the `Argument error:` /
 `Program error:` / `Error:` prefixes in
-`docs/adr/human-readable-errors.md` stand as decided; this changes only
-what follows the error line.
+`docs/adr/human-readable-errors.md` stand as decided; only what follows
+the error line is settled here.
 
 ## Consequences
 
-- Every bad command line now shows usage, so misuse costs more output.
+- Every bad command line shows usage, so misuse costs more output.
   A program that wants the terse behavior back reports errors itself:
   `Dispatch` returns the raw error and prints nothing.
 - The error line stays the first line on stderr, which is what scripts
   and tests that read only the head of the stream already observe.
 - A long usage message can scroll the error line away on a terminal.
   Printing usage first would keep the diagnostic nearest the prompt, but
   reads backwards and contradicts the prior art; rejected.
-- The no-handler report is two lines where it was one. Anything scraping
-  that output now sees `Argument error: missing subcommand` before the
-  usage message.
+- The no-handler report is two lines: anything scraping that output sees
+  `Argument error: missing subcommand` before the usage message.
 - The shape of the report is wording, not API, with the same caveat
   `docs/adr/human-readable-errors.md` attaches to the prefixes: a caller
   must branch on `errors.As` and the exit code, never on stderr's

docs/adr/configuration-types-carry-no-behavior.md

@@ -54,10 +54,6 @@ configuration only and keep everything they have.
 
 ## Consequences
 
-- Breaking, but narrowly. Every program in the documentation already ended
-  with `climux.Run(ctx, App)`, and the only non-test caller of any moved
-  method was `RunWithArgs` itself. It breaks a program that reached for the
-  methods rather than the functions, which the docs never taught.
 - `command.go` is now legibly the configuration type: a struct, a
   constructor, `Compile`, `lower`, and setters. The entry points and the
   error reporting live together in `climux.go`, which is what a reader

docs/adr/exit-code-contract.md

@@ -1,8 +1,6 @@
 # Run reports outcomes as exit codes 0, 1 and 2
 
 Status: accepted, 2026-08-23.
-Amended 2026-08-26: the constant for code 2 is `ExitCodeUsage`. It was
-`ExitCodeBadArgument`, which named only one of the three cases below.
 
 ## Context
 

docs/adr/handler-receives-invocation.md

@@ -81,44 +81,38 @@ parse result, which keeps the source type sealed.
   message built from it may show a full binary path. That is the composing
   author's call, not the package's.
 
-## Note: the streams travel with the invocation
-
-Added 2026-08-23, with the same status as the decision above.
-
-`Command.Output(stdout, stderr)` was read only by help and error messages,
-so a program that pointed a command at a buffer captured the
-`Argument error:` line and nothing the handler printed, which is most of
-what a CLI emits. There was no stdin in the API at all. `Invocation`
-therefore carries `Stdin`, `Stdout` and `Stderr`, resolved from the invoked
-command and its ancestors, and `Output` gives way to `Command.Stdin`,
-`Command.Stdout` and `Command.Stderr`, one setter per stream. The setters
-were later removed and the streams moved onto `Run`; what survives here
-is that the invocation is where a handler finds them. See
+## The streams travel with the invocation
+
+Where a handler's output goes is the second thing its author cannot know.
+The premise above is that a command is mounted by someone other than the
+person who wrote it, and the stream that command writes to is decided in
+the same place, and at the same time, as the path it is reached by. So
+`Invocation` carries `Stdin`, `Stdout` and `Stderr` alongside `Path`, and
+a handler looks in one place for both. Where those streams are set is
 docs/adr/streams-are-run-environment.md.
 
-This follows from the decision above rather than qualifying it. The premise
-was that a command is mounted by someone other than its author; where its
-output goes is another thing that author cannot know, decided in the same
-place and at the same time as the path. The invocation is already where a
-handler looks for such answers, so there is nothing new to discover, and a
-handler that writes to `os.Stdout` cannot be tested by the very party who
-mounted it.
+Anything narrower fails the party doing the mounting. Streams reachable
+only by help and error messages let a program point a command at a buffer
+and capture the `Argument error:` line while missing everything the
+handler printed, which is most of what a CLI emits. A handler writing to
+`os.Stdout` cannot be tested by the very party that mounted it.
 
 Consequences, beyond those above:
 
-- `Invocation` is no longer only "what the command line said". It is what
-  the handler needs in order to run, which is the wider promise and the one
+- `Invocation` is not only "what the command line said". It is what the
+  handler needs in order to run, which is the wider promise and the one
   worth keeping: anything else the package resolves on a handler's behalf
   belongs here too.
 - Three more field names join the v1 surface, and handlers should use them.
   Nothing enforces it, as nothing can: `fmt.Println` in a handler is a
   defect the package can document but not detect. This mirrors `flag`,
   which offers `SetOutput` and cannot stop anyone printing past it.
 - Each stream is set and resolved on its own, so redirecting stdout leaves
-  errors on stderr. Taking both writers at once meant inheriting them as a
-  set: `Output(&buf, nil)` resolved a nil stderr and panicked on the first
-  error message, and saying "leave this one alone" required passing a nil.
-- One word now follows each stream from the option that supplies it to
+  errors on stderr. Taking both writers at once would inherit them as a
+  set: a call like `Output(&buf, nil)` has to resolve a nil stderr or
+  panic on the first error message, and saying "leave this one alone"
+  means passing a nil.
+- One word follows each stream from the option that supplies it to
   `Invocation.Stdout`. That is worth more than matching
   `flag.FlagSet.SetOutput`, which has a single output stream and so never
   had to name a second one.

docs/adr/human-readable-errors.md

@@ -29,11 +29,12 @@ mistyped a flag, and a library announcing its own name inside a host
 program's stderr is a leak of an implementation detail nobody asked to
 see, in the one case — the human's — where nobody benefits from it.
 
-Separately, `docs/adr/exit-code-contract.md` already named a related loose
-end in its Consequences: a parse error prints `Argument error:` and a
-handler-raised usage error prints `Error:`, "because only the parser
-produces an `ArgumentError`" — true at the time, but no longer the whole
-story once a handler has a real reason to construct one itself.
+Separately, `docs/adr/exit-code-contract.md` names a related loose end in
+its Consequences: a parse error prints `Argument error:` while a
+handler-raised usage error prints `Error:`. That split holds only while
+the parser is the sole producer of an `ArgumentError`, and a handler has
+real reason to construct one itself — two mutually exclusive flags is a
+misuse only the handler can detect.
 
 ## Decision
 
@@ -92,12 +93,12 @@ the flag's exact name and scope — which overlaps the still-undecided
 is worth designing once, not twice — and whether the JSON goes to stdout
 or stderr.
 
-The prefix follows the error's type, not who constructed it. An earlier
-pass qualified this — `Argument error:` only when the `*ArgumentError`
-carried a `Cmd`, so that a handler raising one still printed `Error:` —
-which the code never implemented and which this amendment drops. A bad
-argument is a bad argument whoever noticed it, and the reader the prefix
-serves is the person who typed it, who does not care which layer caught
+The prefix follows the error's type, not who constructed it. Qualifying it
+by provenance — `Argument error:` only when the `*ArgumentError` carries a
+`Cmd`, so that a handler raising one prints `Error:` — serves nobody. A
+bad argument is a bad argument whoever noticed it, and the reader the
+prefix serves is the person who typed it, who does not care which layer
+caught
 them out.
 
 There is still no `UsageErrorf`. A handler that discovers a usage problem
@@ -126,9 +127,9 @@ that a refactor had quietly reverted to 1.
 - An agent or script that only sees a CLI's stdout/stderr, rather than
   calling into the library, still has nothing structured to read. The
   direction is decided — a flag, JSON, built on `desc` — but not built.
-- Three prefixes now map onto three causes, so the wording of a message is
-  no longer the only thing telling a misconfigured program apart from a
-  mistyped command line. Exit codes cannot: both are 2.
+- Three prefixes map onto three causes, so the wording of a message is not
+  the only thing telling a misconfigured program apart from a mistyped
+  command line. Exit codes cannot: both are 2.
 - The prefixes are wording, not API, and the same caveat as `String()`
   applies — a program must not branch on them. A caller needing to tell
   the cases apart uses `errors.As`, and an agent reading only stderr still
@@ -141,9 +142,9 @@ that a refactor had quietly reverted to 1.
   because a successful `Compile` is what makes a program well-formed and
   the stream overrides are part of what failed it — `getStderr` resolves
   by walking the very parent links `Compile` checks. Honoring them would
-  mean reading configuration the library has just declared invalid, and it
-  used to address the report to the offending command's stream, chosen by
-  that command's author rather than by the composer the message is for.
+  mean reading configuration the library has just declared invalid, and
+  addressing the report to the offending command's stream — chosen by that
+  command's author rather than by the composer the message is for.
   Nothing is lost by writing early: `Compile` runs before argv is lexed,
   so no handler has run and the process exits 2 immediately. A program
   that wants these faults as values, which is the better place to catch

docs/adr/machine-readable-schema.md

@@ -69,29 +69,27 @@ points at the leaf deliberately. A consumer that only reads documents —
 a tool diffing two of them, with no command tree anywhere in it — gets
 the plain data and none of the implementation.
 
-The name is the one the retired package had, because the role it names is
-the one that survived. What is different is that `desc` is no longer a
-*stage*: it failed as one because the lexer read a projection carrying no
-`Value`, so resolving an argument to something the applier could act on
-grew a private parallel tree and a `bind()` pass, eighty lines spent
-keeping one field off a struct. Nothing internal reads a description. The
-parser still runs on `ir`, and the conversion happens once, at the
-boundary, on the way out. Calling the package `schema` was considered and
-dropped: the format is published as a JSON Schema document, and one word
-should not name both the Go types and the thing that validates them.
-
-Embedding the description into the implementation type was the other
-candidate and does not work, for a reason independent of that history:
-`encoding/json` flattens an anonymous embedded struct, so
-`ir.Command{desc.Command; Handler ...}` marshals to exactly the keys it
-marshals to today. It would buy a type and not a format.
-
-### `ir` no longer marshals
-
-Nothing in `ir` is encoded or decoded, and its `json:"-"` tags come off
-with the field comments that explain them. The guarantee that behavior
-never leaks into a document stops being a tag discipline pinned by
-`TestMarshalOmitsBehavior`, which retires, and becomes structural:
+`desc` is a boundary, not a *stage*. Nothing internal reads a description:
+the parser runs on `ir`, and the conversion happens once, on the way out.
+A description used as a stage does not work, because a lexer reading a
+projection that carries no `Value` cannot resolve an argument to anything
+the applier can act on, and putting that back costs a private parallel
+tree and a `bind()` pass — eighty lines spent keeping one field off a
+struct. The package is not called `schema`, because the format is
+published as a JSON Schema document and one word should not name both the
+Go types and the thing that validates them.
+
+Embedding the description into the implementation type is the other
+candidate and does not work either: `encoding/json` flattens an anonymous
+embedded struct, so
+`ir.Command{desc.Command; Handler ...}` marshals to exactly the keys
+`ir.Command` marshals on its own. It buys a type and not a format.
+
+### `ir` does not marshal
+
+Nothing in `ir` is encoded or decoded, and it carries no `json:"-"` tags.
+The guarantee that behavior never leaks into a document is not a tag
+discipline pinned by a test but a structural property:
 `Describe` copies named fields, so a behavior field added to `ir` later is
 absent from the output because nothing wrote it there, not because a tag
 excluded it.
@@ -327,17 +325,13 @@ operands is an ordinary configuration error naming the author's own
 mistake. That question can stay open on its own merits rather than
 blocking this.
 
-The two-type-model ADR states a rule this changes, and should be edited to
-say three when this is accepted rather than before.
-
 `ir` gains two fields, neither of them behavior. A golden document for
 `examples/orbital` is what will make an unintended wire change visible,
 alongside the help goldens already there.
 
 Machine-readable error output should project through the `desc` types
-rather than defining a second vocabulary for a command and a flag. That
-was already the intent recorded for it, against the `desc` that no longer
-existed when it was written.
+rather than defining a second vocabulary for a command and a flag, which
+is what docs/adr/human-readable-errors.md leaves open for it.
 
 Recording an option's effect is a change to `ir`, and the only one here
 that is not additive. `ir.Flag`'s comment says today that what a
@@ -351,13 +345,13 @@ generated from and the effect of naming it, and `internal/argv` fills in
 the second where it already fills in the first.
 
 `ir` still knows no dialect by this, and the distinction has to be exact,
-because a narrower version of the same field was rejected twice: first as
-a negated form on the compiled flag, then as a `Negated` boolean on a
-claim, both as a dialect feature leaking into the type every dialect
-shares. The test that sank them was whether a dialect lacking the feature
-would leave the field meaningless, and a boolean fails it. A dialect
-without negation reports false everywhere, and one whose modifier is a
-repeat or a reset needs a second field while the first sits dead.
+because the narrower versions of the same field do not survive it. A
+negated form on the compiled flag, or a `Negated` boolean on a claim, is a
+dialect feature leaking into the type every dialect shares. The test is
+whether a dialect lacking the feature leaves the field meaningless, and a
+boolean fails it: a dialect without negation reports false everywhere, and
+one whose modifier is a repeat or a reset needs a second field while the
+first sits dead.
 
 An effect names no feature. It is a term the dialect writes and a
 consumer reads, over a vocabulary that is open, so a dialect with no
@@ -374,10 +368,10 @@ the shared type changing. Two rules keep it there:
   rather than by reading the effect. The modifier still lives entirely
   inside the dialect, and the effect exists for the document alone.
 
-Under those, this supersedes the earlier rejections rather than
-contradicting them. What the type records is not that this dialect
-negates, but that the dialect had something to say about an option, in a
-word it and the reader share.
+Under those two rules an effect is not the field those narrower versions
+would have been. What the type records is not that this dialect negates,
+but that the dialect had something to say about an option, in a word it
+and the reader share.
 
 A flattened per-command projection is anticipated and deliberately not
 built. Something calling one command wants that command's calling

docs/adr/middleware-wraps-handlers.md

@@ -23,19 +23,21 @@ reasons that compound:
   discovered when someone deprecates a command on data that never covered
   it.
 
-Until now the only answer was the `Wrap` idiom shown in
+Without a mechanism for it, the only answer is the `Wrap` idiom shown in
 `example_di_test.go` — a closure returning a `HandlerFunc`, which climux
-does not provide so much as permit — registered by each command at the
-point it declares its handler. That leaves the decision with the wrong
-party. climux exists so that many teams can compose one binary, and the
-team that decides a subtree must be measured, or audited, is the one
-assembling it.
+does not provide so much as permit — applied by each command where it
+declares its handler. That leaves the decision with the wrong party.
+climux exists so that many teams can compose one binary, and the team
+deciding that a subtree must be measured, or audited, is the one
+assembling it rather than each team that wrote a handler.
 
-`orbital` had already shown the cost before this change: three unrelated
-packages each imported a `middleware` package and threaded the audit
-identity through their own `HandleFunc` calls, and `--trace` advertised
-"a timing trace for every command" while tracing only the three that
-happened to opt in.
+The cost arrives as soon as a binary is large enough to want the
+mechanism. A concern applied handler by handler makes every package
+carrying it import the package defining it and thread the same state
+through its own `HandleFunc` calls, and a flag such as `--trace`, which
+advertises "a timing trace for every command", traces only the commands
+that remembered to opt in — with nothing in the flag's own description to
+tell a reader which those are.
 
 ## Decision
 

docs/adr/path-scoped-flag-names.md

@@ -50,7 +50,7 @@ mounted.
 
 ## Consequences
 
-- The debugging trap goes away: within any one invocation, a name means one
+- There is no debugging trap: within any one invocation, a name means one
   flag bound to one variable.
 - Validation becomes ancestry-aware rather than per command, so it costs a
   walk down each path rather than a pass over each command.