Phase 1: the exit-code contract and machine-readable output (ADR-0007)

[JumpTechCode]

Third of three Phase 1 records. Two independent adversarial reviews found three
things worth catching before anything was published.

The verdict exit codes were wrong, in the one direction that matters

The design justified 70–73 as "clear of sysexits' common values". Verified
against sysexits.h on this machine:

EX_SOFTWARE   70   internal software error
EX_OSERR      71   system error
EX_OSFILE     72   critical OS file missing
EX_CANTCREAT  73   can't create output file

Not near sysexits — four consecutive values inside its 64–78 block. And the
collision at 70 is semantically inverted: the convention reserves it for an
internal error in the program itself, which is what Assayer means by 82, not 80.
A wrapper dying of its own fault at 70 would have been reported as a regression
that never happened — the manufactured verdict this design forbids everywhere
else, arriving through the exit code rather than through any verdict logic.

Moved to 80–83, above the sysexits block and below the shell's 126/127.
Nothing had been published, so this was free today and a breaking change to
strangers' scripts after the first release.

Precedence was unspecified

A suite can carry a failing exam, a rotted pin, and an errored one at once — the
decision rule makes that routine. With no stated order, two conforming
implementations disagree, and the worst case is a real regression resolving to
the stale-pin code and being waved through. Now specified and tested:
82 > 80 > 81 > 83 > 0, with 82 first because it says the other answers could
not be trusted.

A shipped bug: trailing arguments were ignored

$ assayer version --jsonn
v0.0.0-...          # exit 0

A script asking for a machine-readable document got prose and a success code.
Flags are now checked against what each command accepts; that case exits 2.

Machine-readable output starts

assayer version --json emits the first document. Each carries its schema
identifier, a revision that moves whenever an emitted shape changes, the
stability tier, and the list of schemas the build can produce — discovery
without running anything that costs money.

Schemas are generated from the types, not hand-maintained beside them, and
asserted against the committed files. A hand-written schema plus an external
validator is two descriptions that can be wrong together: rename a field,
regenerate the sample, and it still validates. This is the arrangement the repo
already uses for its linter rules, and it needs no dependency — go.mod stays
empty.

Verified by planting a field: both the schema check and the golden fail.

assayer.dev is someone else's product

The draft rooted schema identifiers there, on the stated assumption that nothing
was served at that address. Not checked, and false — it is registered and
serving "Assayer – Production Readiness Review for Vibe-Coded Apps". Identifiers
are now rooted at this repository. The namesake collision is worth a separate
look at ADR-0002; this PR only stops the contract depending on it.

Stated rather than implied

The event stream and verdict objects are not built. They land before Phase 1
closes, with the components that produce them — and no command returns a verdict
code until a machine-readable verdict object ships alongside it, because an alarm
with no readout leaves scraping human output as the only option, and those
scrapers become an unversioned contract.

The exam format's schema is also deferred, carrying a real question: the format
is TOML, the stdlib cannot parse TOML, so validating it needs either this
module's first dependency or a different format. Recorded so it stops being
invisible.

make verify green: coverage 90.2%, 0 lint issues, 0 vulnerabilities.

[codecov]

Codecov Report

❌ Patch coverage is 94.00000% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/cli/cli.go	86.36%	2 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!