One output convention for every app: result to stdout, documents to the store - #744

Phase 1 of the output convention. make check passes.

The flags:

- --format becomes --output with the -o short form, matching aws, az,
  and kubectl. It retires by deletion, not by alias.
- --store names the execution store's root.
- The set binds to PersistentFlags, so one call on a program's root
  covers every subcommand -- the registration model all four in-scope
  programs will use.
- `none` joins the formatters: a rendering that produces no result at
  all. Not `> /dev/null`, which renders and then discards; this never
  renders, and it is reachable from config and env where no shell exists
  to redirect.

The store:

StoreHome() is the one root everything derives from -- the graphs
directory, the traces directory, the run index, and the fsroot anchor the
writers open. Relocating leaves while the anchor stayed at the state home
was the first implementation, and the round-trip test caught it:

    mkdirat ../../002/traces/sha256-5eaf00d... : path escapes from parent

It also caught IndexPath() never consulting the store root, which would
have left a relocated store's traces in one place and the index recording
them in another. Its doc comment already claimed "at the store root" and
had been wrong before this change.

TestStoreRoot_RelocatesTheWholeStore pins all of it, using different
directories for the state home and the store root so anything consulting
the wrong one is caught rather than coinciding: the trace lands under the
store root, the index is under the store root, LoadLatestTrace finds the
trace by its graph checksum, and the index carries the entry.

Docs: the spec settles one table formatter for the suite, with lore's
hand-rolled runSearch table named as Phase 4's first conversion rather
than as an argument for a second one.

Nothing consumes opts.Store yet; no root calls SetStoreRoot. That is
Phases 2 through 4, where each program adopts the set.

#740)

Phase 2 of the output convention. make check passes.

devlore-test now obeys the law. Before and after:

  result       <script>.summary.json    -> stdout, json by default
  narration    stderr                   -> stderr, unchanged
  definition   <script>.receipt.yaml    -> the store, keyed by checksum
  trace        DISCARDED                -> the store, under its definition
  t.run values the stream named "graph" -> the summary's results field

That closes all four defects in #738. The graph document was being written
to the stream named "receipt" while the stream named "graph" emitted t.run
return values and wrote nothing when a unit returned nil -- which is why
<script>.graph.yaml was empty for every file-based plan.

The execution trace was one line away the whole time: executor.Trace() sat
unused beside executor.Run in test_context.go. Persisting it is what makes
a run's resource-state transitions observable at all.

Retired by deletion, not aliased: --output stream=dest routing,
--receipt-format, the outputFlags Value type, openDest, writeSummary,
writeReceipt, and WithWriter.

This supersedes the 2026-08-20 routing ruling, which sent all three
payloads to files and kept stdout empty. That ruling predates the
three-stream split and treated one category where there are two: the
summary is a result, the definition and trace are documents.
TestCLI_DefaultsToArtifactFiles pinned the old behavior and is replaced by
TestCLI_ResultToStdoutStoreForDocuments, which asserts all of it -- result
on stdout, narration on stderr, documents in the store, working directory
untouched.

Tests now assert artifact CONTENT, which #738 records as the reason these
defects survived: the old suite checked only that the three files existed,
and a 0-byte file exists.

One stale assertion cost four false failures while doing this:
assertValidSummary scanned for the first line starting with "{" and parsed
that line alone -- correct for the old compact summary, wrong against
indented json. The output was right; the test was not.

Docs: section 14 recorded star as having "no result flags at all". It has
a second copy of the cli package instead (#743), whose renderTable is the
candidate to promote into pkg/result for Phase 4 rather than a thing to
rewrite. Root internal/ holding cmd-only code is #742.

Phase 3a of the output convention. make check passes.

writ registers the common set on its root, so every subcommand accepts
every flag. --json is deleted rather than aliased: a boolean cannot
express a third format, which is why writ status and writ verify could
not emit yaml.

verify computes; the command renders. verify.Execute returned an error
and printed reports itself, choosing json or human text from cfg.JSON. It
now returns []Report and the command emits them through the pipeline,
which is where rendering belongs. The reports are emitted whether or not
the signing policy rejected -- a rejection is the answer to the question,
not a reason to withhold it.

Two consequences worth stating plainly:

- writ verify now emits JSON by default. presentReport was its human
  renderer and is deleted with the responsibility it carried. The
  friendly output returns as `-o table` once the shared TableFormatter
  lands (#741, #743).
- writ status is bridged, not converted. cfg.JSONOutput now reads
  outputOptions.Format == "json" instead of a retired boolean, so its 22
  fmt.Print calls still render themselves until phase 3b.

Phase 3 is split. The status report is a human table, and converting it
needs the TableFormatter currently scheduled in phase 4 -- so 3b (status,
the four dry-run SerializeGraphs dumps, and migrate's own --format) waits
on that. The plan records the split.

Also corrected: four flag descriptions read "Promise <noun>" where they
meant "Output <noun>", from a global replace that caught help text
(#739). Three had shipped into the generated CLI reference under
docs/cli/lore/.

My own count of writ's stdout writes was wrong when phase 3 was written:
I grepped the literal os.Stdout and missed every fmt.Print, which writes
to stdout just as surely. The real figure is 30 call sites, not seven --
22 of them in status/report.go.

…ent (#740)

make check passes.

One delimited formatter, two presets. csv and tsv differ in two attributes
at once -- a spreadsheet wants a comma and a header row; `awk '{print $2}'`
wants a tab and no header row to skip -- so each gets a name rather than a
flag. gcloud reached the same shape: its `value` format is documented as
"CSV with no heading and <TAB> separator instead of <COMMA>". The header
inference, csv tag overrides, and RFC 4180 quoting are shared, untouched.

The template formatter is gone. Reshaping a value is the filter stage's
job, and --jq does it for every format; a template is the answer tools
reach for when they have no query language. Of the five surveyed, aws, az,
and gcloud have a query language and no templates; kubectl and docker have
templates instead. Nobody has both, because they solve one problem.
FormatterByName takes one argument now.

The spec gains section 8, which draws the pipeline: two stages, one flag
each. It also records the ruling that a format needing an argument carries
it in the value -- `--output template=<body>` -- rather than in a sidecar
flag. A sidecar gives the format stage two inputs and a mutual-exclusion
rule to enforce; NAME=ARGUMENT makes the conflict impossible by
construction instead. kubectl ships that exact form (-o go-template=,
-o jsonpath=, -o custom-columns=).

Presets stay named: csv and tsv are two values a user can guess, where
csv=tab is one value with an argument to look up.

Not built yet, and recorded as phase 3c: the NAME=ARGUMENT parse itself,
template=<body>, and `value` -- the raw rendering that makes --jq complete,
since a jq-built string has no other format that prints it as written.

#740)

Phase 3c. make check passes.

--output takes NAME or NAME=ARGUMENT, split on the FIRST '=' so an
argument containing '=' survives. A format needing an argument carries it
in the value rather than in a sidecar flag: a sidecar gives the format
stage two inputs and a mutual-exclusion rule to enforce, where this makes
the conflict impossible by construction. kubectl ships the same form
(-o go-template=, -o jsonpath=, -o custom-columns=).

Three malformed specs now error, each naming the format: a missing
argument where one is required, an empty one after '=', and one given to a
format that takes none.

`value` renders raw -- no quoting, no document syntax, no header. It is
what completes the filter stage: --jq can build any line, and every other
format then imposes a syntax on it. json quotes and escapes, csv adds a
header, yaml applies scalar rules. aws ships this as `text` and gcloud as
`value`, and like gcloud's it expects a projection first:

    devlore-test run --jq '.unit_count' -o value    →  1

Applied to a whole nested struct it prints every field, pointer addresses
included. That is the same constraint gcloud documents by requiring a
projection for csv and value, not a defect to paper over.

template returns in the shape the spec describes: reached only as
template=<body>, parsed once at construction, with no flag to pair it
with. The previous implementation was removed two commits ago for being
the sidecar form.

Also fixed, found by running the binary rather than the tests: --store
rejected a relative path with "not an absolute path on this platform".
OpenTree requires absolute paths deliberately -- a drive-relative path on
Windows anchors to whichever drive the process is standing on (#392) -- so
SetStoreRoot absolutizes at the seam and returns an error, keeping the
invariant true for every later reader instead of at each one.

…le (#740, #741)

make check passes.

DelimitedFormatter carries three attributes -- Separator, SuppressHeadings,
Raw -- and ships three presets, which is gcloud's shape: its csv and value
are one renderer differing in separator, heading, and quoting, with value
documented as "CSV with no heading and <TAB> separator instead of <COMMA>".

    csv     ,     heading      RFC 4180 quoting   spreadsheets
    tsv     tab   no heading   RFC 4180 quoting   cut -f2, awk
    value   tab   no heading   raw                text --jq already built

Quoting is what separates the last from the middle. A machine-parseable
format must quote a field containing its own delimiter or the row loses a
boundary; a raw renderer must not, or text a caller composed comes back
wearing quotes it did not write.

The formatter now accepts every shape rather than only rows-with-fields. A
non-sequence is one row -- `--jq '.count'` produces exactly that, and
refusing it made the filter stage incomplete. A slice of scalars is one
column with no header, since a scalar has no field to name. A byte slice is
one value rather than a sequence of numbers.

Two tests asserted refusals that are now supported shapes, and are rewritten
as Accepts with the reason recorded rather than deleted.

That folding fixed tsv as a side effect: `-o tsv` on a scalar said "expected
slice or array, got int64" before, because value was a separate
implementation rather than a preset of the same one. The redundancy was in
the implementation, not the name.

It also simplified what it touched. With scalars no longer an error case,
csvHeadersFromElements and csvRowFromElement always returned nil errors;
lint caught it, and both lost their error returns along with the handling at
three call sites.

TableFormatter shares that column inference -- HasHeaders, csv:"name"
overrides, csv:"-" skips, the map-key union -- so one value renders the same
columns as table, csv, or tsv, and only the presentation differs. A test
pins it, because divergent column logic is how one rendering ends up showing
a field the other hides.

Alignment is text/tabwriter's, which measures in RUNES. That is half of #741
fixed at the shared formatter rather than at each call site: a hand-rolled
%-30s counts bytes, so a row with a multi-byte character is short by the
difference and every column after it shifts. The test uses a 7-rune,
21-byte name and asserts the next column starts at the same rune offset on
both rows.

The set is csv, json, none, table, template=BODY, tsv, value, yaml.

Files renamed: csv.go and its tests hold three presets now, not one format.

make check, make docs, and make test-scenario all pass.

The command help strings documented flags this branch retired. docs/cli is
gitignored -- generated by `make docs`, never committed -- so the staleness
lived in the Go source, and regenerating only proved the fix. #739's title
says the corruption "shipped into the docs"; it did not, and that claim is
corrected on the issue.

A fourth #739 site: lore inspect's long description read "Promise is JSON by
default ... Use --format", in prose rather than in a flag string, so a grep
aimed at flag descriptions never saw it. Same class of miss as counting
writ's stdout writes by grepping os.Stdout and missing 24 fmt.Print calls: a
grep for one syntactic form undercounts a semantic problem.

Section 15 claimed no root registers the common set. Two of four do. It now
also states what it had been carrying silently: writ status is bridged, not
converted, so `writ status -o yaml` produces the human report rather than
yaml, until its report goes through the pipeline.

Plan and status checkboxes were stale -- phases 1, 2, and 3c were complete
with every box unticked. Reporting progress in conversation while the
tracked document says nothing is done is the failure that rule exists to
prevent.

extract-output-package.md is corrected. It was marked complete while
describing an internal/output package that was never created; the code went
to pkg/result and pkg/sink. It also holds the last measurement of adoption
-- two call sites, one of which vanished with writ snapshot and went
unrecorded -- which is the evidence behind the enforcement invariants.

Also written down, having been noticed and left: the jq-versus-JMESPath
divergence now sits in section 16 with the rest, and section 7 states that
`value` expects a projection, as gcloud requires one for its csv and value.

Two test defects, both invisible to make check:

- scenario_integration_test.go invoked `writ status --json`, a flag deleted
  several commits ago. make check does not run scenario tests, so it would
  have gone red on CI rather than locally.
- TestCLI_BadOutputPath passed for the wrong reason: after --output became a
  rendering, "graph=/no/such/dir/out.txt" parses as an unknown format named
  "graph" and exits non-zero without reaching a filesystem. It is now
  TestCLI_UnwritableStore, against the flag that takes a path.

status was still "draft" with four phases complete, and updated still read
2026-08-28. Stale plan metadata is what makes the documentation system
untrustworthy: a reader cannot tell a plan that has not started from one
that is most of the way done.

The epic body carried two harder errors, corrected on the issue itself:

  - it cited 9-command-line-interface.md; the spec is 10-.
  - it listed --template as a reserved flag and template as a plain
    rendering. --template was deliberately removed. A format that needs an
    argument carries it in the value, split on the first "=", which is why
    there is no sidecar flag and no mutual-exclusion rule. The rendering
    list also omitted tsv and value.

pkg/result/selection.go:19 is the authority on the format names and says
so; cmd/internal/cli/output.go:93-99 registers the four flags. Both were
checked against the code rather than restated from the epic.

The epic's progress narrative was refreshed at the same time. It still
said "one command out of forty-six calls AddOutputFlags" and listed
devlore-test and writ's flags as remaining, both of which have landed.

…740)

tsv was added on an awk/cut rationale that does not survive inspection.
Those tools have no quote awareness, so quoting a field that contains a tab
does not stop the row from splitting -- cut -f2 returns "a and b" rather
than a and b. The quoting helps only a caller running a real parser, and
that caller is better served by csv, whose library support is universal.
That leaves nothing a quoted tab format does better than both of its
neighbours.

gcloud and aws each ship one raw delimited format -- value and text -- and
no tsv. The naming is why: csv and tsv promise that a parser can round-trip
the output, and a format that does not quote cannot keep that promise.
Neither tool claimed the name. Ours could have, since ours quoted, but
earning the name and earning a slot are different questions.

So the pair now splits by consumer rather than by separator. csv quotes, so
a parser round-trips it. value does not, so a shell reads exactly what was
composed, which is what makes --jq complete. DelimitedFormatter keeps all
three attributes; Raw is what separates the two survivors.

Also fixes the --output help, which never listed `table`. The rendering has
been accepted by FormatterByName since the TableFormatter landed earlier in
this branch, so it worked and was undiscoverable. The text now names what
each rendering is for rather than listing them flat:

    Output rendering: json, yaml, table, csv, value (raw, pairs with --jq),
    template=BODY, or none

The reasoning is written into 10-command-line-interface.md §8 rather than
only the outcome, because "why is there no tsv?" is a question that will be
asked again. The plan, the status document, and the epic body carry it too.

BREAKING: --output tsv is no longer accepted. Use value for raw tab-
separated output, or csv where the consumer parses.

…aml (#736)

Picks up #736, which landed on develop 67 seconds after this branch's last
CI run was created -- so every green result on this PR so far, including
the 12/12 on cece6c9, tested a merge ref that did not contain it.

No files are shared. #736 touches .goreleaser.yaml and
docs/plans/release-path.md; this branch touches pkg/result, cmd/internal/cli,
cmd/devlore-test, cmd/writ, and its own docs. The one coupling is
verify-ldflags, which greps .goreleaser.yaml for Version, Commit, and
BuildDate against pkg/application: #736's new star build block carries all
three, and the check is a whole-file grep, so an added block cannot break it.

This merge exists so CI tests the combination rather than the assertion that
it is safe.