Every presentation is a presentation of the JSON: formatting rules, list, and stage 1 - #747

#754)

REGISTERING THE COMMON SET NOW WIRES IT. AddOutputFlags binds --output and
--store to a PersistentPreRunE, so the two flags whose meaning does not
depend on a command rendering anything cannot come apart from their
registration.

  #754 -- writ accepted any --output value. FormatterByName is the only
  place the string is checked, reached from BuildPipeline, and writ reaches
  it once: runVerify. Everything else compared the value to the literal
  "json" and discarded it, so `writ status -o bogus` printed its report and
  exited 0. A typo was honored as a request for the default. Not only
  status -- every writ command but verify.

  #753 -- writ read --store nowhere. outputOptions is consumed in exactly
  two places: config.go:160 takes .Format, commands.go:302 hands the struct
  to BuildPipeline in runVerify. Meanwhile readback.go reads TracesDir()
  and GraphsDir() to fold runs, so `writ status --store <elsewhere>`
  reported on the DEFAULT store as though it had complied. Not the wrong
  shape -- the wrong data.

Both were one defect: a flag registered on a root that no leaf consumes.
Cobra advertised the whole set on every command's help while one command
honored it. A flag that is present and inert is worse than an absent one:
an absent flag errors, and the user tries something else.

The store selection is undone when the command tree finishes. Leaving it
set is harmless in a process that runs one command and exits, and
corrupting in a test binary that runs many -- the root is a package-level
value, so the first command passing --store would silently relocate every
command after it. The existing subcommand test passed "/tmp/store", which
was inert before this and leaked into four sibling tests the moment it
was not.

A NUMBER IS A NUMBER IN BOTH DOCUMENT FORMATS. Stage 1 keeps json.Number so
a presenter renders the digits it was given rather than a float64 rounded
past 2^53. encoding/json special-cases the type and emits it bare; yaml.v3
does not, and json.Number is a string type -- so `-o yaml` answered
unit_count: "2" where `-o json` answered 2. One value, two types, decided
by the rendering. This was a regression from 6bd5328, in this PR.

The conformance suite passed it throughout, because it asserted the digits
were PRESENT and they were: in quotes. A second test now asserts the type,
which is the assertion that would have caught it.

--output DOCUMENTS ITSELF. Each rendering closes with what it is for, and
the free text orders them by usefulness while the list stays alphabetical
-- the order the error message and §7 already used, and the one that helps
in everyday use. Lines are hand-wrapped to 88 so they fit 120 once pflag
adds its 32-column indent: FlagUsages calls FlagUsagesWrapped(0), and 0
means no wrapping, so a long line is the author's to prevent.

devlore-docs learns that a table cell holds neither a newline nor a pipe.

INTEGRATION COVERAGE. A two-operation fixture -- write a file, then remove
it, the removal consuming the write's promise so the graph has one real
edge -- rendered through every value of --output, each verified as the
thing it claims to be: json parses as JSON, csv as CSV, table has one
header and one row, none is empty, template renders. Plus the rejection
case, which is what #754 was.

The point is coverage of the SET. writ answered `-o yaml` with a human
dashboard for months because nothing asserted across the whole of it.

…755)

Help text did not wrap at all. Cobra's template calls FlagUsages, which is
FlagUsagesWrapped(0), and wrap() reads zero as "re-indent after existing
newlines, break nothing":

    func wrap(i, w int, s string) string {
        if w == 0 {
            return strings.Replace(s, "\n", "\n"+strings.Repeat(" ", i), -1)
        }

So every line's width was the author's to maintain by hand -- --output's
usage was wrapped to 88 columns by counting, a constant no test enforced
and one that was wrong on any terminal narrower than 120.

PFLAG'S OWN WRAPPING IS NOT THE FIX. wrapN indents every continuation to the
flag's description column: one indent level, no notion of structure. A
two-column usage collapses the moment it wraps, and the column was what made
it scannable:

    csv            quoted and parseable; when
    a spreadsheet or a data tool reads it

wrapUsageLine hangs continuations under the text they continue, finding that
column as the first run of two or more spaces after the line's first
non-space character. On a flag line that is pflag's description column; on
one of --output's renderings it is the sentence column, one level in:

    csv            quoted and parseable; when a
                   spreadsheet or a data tool reads
                   it

Below helpMinimumTextWidth the hang is abandoned and the line falls back to
its leading indent, because a sliver of text is worse than a lost column.
Widths are counted in runes, so a description carrying a multi-byte
character breaks where it looks like it should.

The width is COLUMNS when set and sane -- a user who exports it has said
what they want, and it is the only answer available when stdout is a pipe --
then the terminal, then a fallback. golang.org/x/term is already a
dependency through pkg/sink.

--output's prose becomes one logical line, joined across source lines, so
the wrapper reflows it rather than honoring a width guessed at authoring
time. The rendering list stays one line each, because those carry the column
the hanging indent exists for.

Cobra is not the obstacle here and this does not fight it: AddTemplateFunc
and SetUsageTemplate are the extension point, and this is what they are for.
What is primitive is pflag's renderer, which we were reaching through them.

Not addressed: a command's Long text, which cobra prints verbatim. It is
hand-authored prose with intentional shape -- examples, lists -- and
reflowing it would damage that.

…#740)

Three rulings and one measurement, written down so none has to be recalled.

§2 -- MEMBERSHIP IS ABOUT INFRASTRUCTURE, NOT ABOUT SHIPPING. An in-scope
program builds its command tree the way every other in-scope program does:
NewRootCmd for the root, AddOutputFlags on that root, cmd/internal/cli for
the exit codes and the store. devlore-test is subject to this whether or not
it is ever shipped, and whether it ships does not enter into it.

The reason is not symmetry. A program that assembles its own root inherits
nothing later. #755's help wrapping reached lore and writ and not
devlore-test, because devlore-test constructs a cobra.Command directly.
Nobody decided to exclude it; a construction choice made elsewhere did, and
measurement found it afterwards. Tracked as #757.

§13 -- TWO VERSION NUMBERS, ONE COMPUTED AND ONE DECLARED. An application
and the documents it writes version separately. The application version is
COMPUTED from the build -- git describe appends commit distance and a hash,
so it differs between two builds of identical source. A document format
version is DECLARED, written down by hand, and changes only when someone
changes it. Stamping a computed version into a document would claim a new
format on every build.

The hedge: the document version is a semver string whose value tracks the
application's for now. A reader seeing "1.0.0" attributes a document to a
release with no lookup table, which is the benefit of one number; and
because the value is a literal rather than a computed one, the two diverge
the day a format changes and the application does not, by editing one
constant. Nothing is decided in advance.

schema_version is a uint32 today, which forecloses that -- an integer cannot
express 1.2.0, so an additive change becomes a major bump or goes
unrecorded. Widening it moves the canonical form and every stored checksum,
so it belongs with the serialization work rather than a CLI branch. Tracked
with the rest of #758.

On the release of a major application version the store version is bumped
with it, so a document is attributable to a release without a lookup table.
Policy, not invariant: the two stay independently versionable, a format
bumps whenever it actually changes, and this is revisited regularly.

What it buys is #758's distinction. A document whose schema_version is
absent or below the floor was written by a RETIRED format; one at the
current version that fails to decode is DAMAGED. A trace carries no version
today, so the two are indistinguishable and both read as corruption.

§15 -- A FIX TO THE SHARED PACKAGE REACHES ONLY ITS CALLERS. Measured after
#753, #754, and #755 landed in cmd/internal/cli:

    COLUMNS=70, longest flag line
      writ           70
      lore           70
      devlore-test  389   <- unwrapped
      star           65

devlore-test builds its own root. star binds its own cmd/star/cli, which is
#743's cost made concrete: a defect fixed in the shared package is fixed
once per package. lore registers the set on inspect rather than its root, so
every other lore command lacks the flags entirely.

The general form: a repair in cmd/internal/cli reaches exactly the programs
that route through cmd/internal/cli. Registration on a root is what makes
one fix program-wide; a second copy of the package is what stops it being
suite-wide.

The plan gains Phase 4b for the three, so the coverage gap is work rather
than an observation.

Not settled here: whether to tag v1.0.0. §13 says there are no released CLI
contracts to preserve, release-path.md says we are not ready to release, and
this branch removes flags outright. Raised, not resolved.