Spec · r2 · meta-adversary findings folded · for red-pen

The Legible Fleet

Every future site ridiculously easy to diagnose and fix — diagnosability installed at birth by the factory, not brought at midnight by the operator.

Draft for Robert’s annotation · not approved · no building yet · build sequenced after both certificates

Reference strip: Your three calls · Locked decisions · Honest risks · How this spec was tried

The story, in one paragraph

Tonight, when a site fails, an expert digs: logs, artifacts, re-runs — hours. After this arc, any failure on any site is one of two things: a named class with a written next action, or a ten-minute local replay from a recording that is proven complete. Every site’s repo carries a health ledger a teammate can read. And the 400th practice is cheap to run because the first 399 already taught the machine their tricks — permanently, with proof the lessons still bite.

The one-sentence version: diagnosability becomes a property the factory installs, not a skill the operator brings at midnight.

★ Your three calls

1. When do we build it?

Recommended: after Alie’s certificate and Southtown’s link land. The pieces already mid-flight (the pre-run checks, the replay mode, the offline localizer) keep going either way. Alternative: build everything in parallel now — more speed, more risk of tripping over the certificate lane’s files.

2. Where does a site’s health ledger live?

Recommended: split by audience. Rows a client may see live in their site’s repo (the self-contained diagnosis kit). Internal rows — and anything security-sensitive, like malware-scan observations — live in a fleet-side home only we can read. The panel caught that the original design would have shipped our security worry-notes into repos the client can open; this split is the cure.

3. Who may name new failure classes?

Recommended: you ratify the launch set once; new classes get added by the lead with your review at merge. The taxonomy is doctrine-adjacent — failure names shape what the team believes went wrong. Alternative: fully lead-owned (faster, less oversight on a trust surface).

Locked decisions (the trial changed these — say if you disagree)

Watch, don’t list. What must be kept for replay is derived from a tracer that watches what the instruments actually read — never a hand-list. A hand-list is how the deploy tree got dropped in the first place.
Teeth must bite. A regression fixture only counts if reverting its fix turns it red — proven and recorded, per fixture.
No quiet escape hatches. The one override that can skip the completeness check makes the run’s certificate refuse, loudly. There is no switch that skips a safety check and stays green.
One name per failure family. The new class registry absorbs the two older vocabularies (the capture confessions, the walk’s origin notes) with explicit lineage — run 8’s four-names-for-one-problem confusion ends.

The journey — one bad night at a 200-page practice, after the arc

  1. The failure lands already named. A stage fails and the record it leaves carries a class — site problem, harness problem, or environment problem — enforced by the compiler, so a classless failure cannot even build. Novel failures get the class NOVEL, which is itself the page-a-human signal. Tonight’s measured reality folded in: four of five hard diagnoses were harness-side, so the launch classes lead with those.
    ↘ go deeper — the machinery
    stageFail gains a required class parameter typed as a closed union — the compiler is the total gate, no grep denominators. The class flows into the persisted stage record and the sweep manifest. Raw throws that bypass the wrapper are caught by an assertion over the recorded sweep: no FAIL row without a class. Registry rows: class, locus, first-seen, fixture-path, bite-proof-ref, playbook, supersedes/alias.
  2. The recording is complete — proven, not promised. The run preserves its evidence, and a gate checks the preserved set against what the diagnostic instruments actually read — recorded by a tracer that already exists in the repo and watches every file each of the ~39 probes opens. The artifact upload ships that same derived set, errors loudly if anything is missing, and counts what it shipped. This is the panel’s biggest catch folded in: the first draft trusted a hand vocabulary, and a hand vocabulary is exactly what silently dropped the deploy tree from tonight’s artifact.
    ↘ go deeper — the machinery
    One tracer (the oracle FS-trace hook), three adapters: the preservation gate (RED on any absent traced member), per-probe basis fields (inputsRead with digests, compared with denominator source, absent named), and the upload allowlist emitted into the workflow with if-no-files-found: error plus a post-upload count assertion. Red-proofs delete a traced member, not a declared one. The probe-root seam (one probe resolving against the repo while siblings used the artifact — live in tonight’s log) becomes a basis-field consistency assertion.
  3. The system’s own notes were already waiting. Every confession the pipeline makes — skipped fetches, alarms, timings, walk observations — routes to one health ledger per site, drained before every run so a note is never discovered after the failure it predicted. Every row carries an audience class: client-safe rows travel in the site’s repo; internal and security-sensitive rows stay in the fleet home, along with confessions from runs that failed before the site repo existed, and harness-wide patterns that would otherwise fragment across 400 repos.
    ↘ go deeper — the machinery
    Pinned name (_site-health-ledger.jsonl — avoiding the two legacy ledger collisions), one schema module, writers enumerated by a derived coverage check on the emitter’s consumers, reader = the pre-run drain (its in-flight build unifies to this file at integration). Rows: ts, runId, class, locus, audience (deliverable-safe / internal-only / security-sensitive, fail-closed internal), detail, basis. Abort paths flush before exit.
  4. Ten minutes later, the failure is reproduced on a laptop. Because the recording is provably complete, the replay tooling (already merged tonight: the diagnostic mode plus the offline localizer) re-runs exactly the failing check against exactly the preserved evidence — no fresh 75-minute run, no cloud credentials, no archaeology. Certificates still only ever come from full runs; replays are structurally unable to mint one.
    ↘ go deeper — the machinery
    Gating-RED moments get promoted to durable storage keyed to their ledger row (the 14-day artifact window otherwise silently outlives the replay promise — panel finding, folded). The external judge replays one past-retention moment to prove the promise holds beyond the default window.
  5. The fix cannot merge without its permanent tooth. The defect class gets a rehearsal fixture, and the fixture is bite-proven: revert the fix, the tooth’s test goes red — recorded on the registry row, so a decorative tooth cannot exist. Scale is the one class that is not a fixture (a single test page cannot rehearse a 445-page capture) — it becomes a measured budget plus a nightly big-capture lane instead.
  6. And we know it worked because the clock says so. Judge one: time-to-named-root-cause on the first new site after the arc — a mechanical clock against tonight’s hours-long baseline, measured by someone who is not the builder. Judge two: the ratchet count rises and every counted tooth carries its bite-proof. Judge three: one past-retention replay succeeds.

What could go wrong — honestly

The tracer over-collects. Keeping everything the instruments read could bloat artifacts. Cure in the design: a measured budget gate on the derived set — bloat becomes a number with a ceiling, not a surprise.
The ledger becomes a graveyard. Confessions written, never read — tonight’s exact disease. Cure: the pre-run drain is the ledger’s reader by construction, and an undrained row is itself surfaced as an alarm.
Failure names ossify wrong. Classes are append-only with supersede lineage — the same claims discipline the genome uses, applied to failure names.

How this spec was tried before reaching you

You commissioned a meta-adversary — an independent Fable that designed its own attack plan, spawned its own four-agent panel, and adjudicated their findings (it corrected one panelist’s factual error along the way). Verdict on draft one: 5/10, revise-then-build — four blockers, eight majors, one minor, with one convergent root: the draft’s gates counted artifacts instead of proving they bite. Every finding is folded into what you just read. The direction survived untouched; the mechanisms got the beating before a single line was built.