Ruling needed: does main's README quick start install main, or the latest release? (#103 item 2 reverts #89's fix)

[dan-claude-bot]

Escalated from #103 by triage. #103's item 1 (the BOX_REF pin) stays an issue and is unaffected; this half needs a ruling from @danmt before anyone touches it, because the two candidate answers are both defensible and one of them reverts a shipped fix.

The decision

What contract does the quick-start command on main's README serve?

A — the README you are reading matches what the command installs. Current behaviour, README.md:18:

curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RIG_REF=main bash

B — the landing page shows a newcomer the stable path, matching box and cast, with main staying documented as the opt-in dev channel a few lines below:

curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | bash

Why this is a ruling and not a bug fix

rig#103 reads the RIG_REF=main override as "almost certainly a stale workaround from before rig had any release". It is not. It was added deliberately, one day earlier, by PR #91 (docs: align README quick start with main, merged 2026-07-20), to close #89 — and #89 was filed URGENT:

README.md on main documents role names and flags that exist in no released version. A new user following the README top-to-bottom cannot get past the first bootstrap command.

The concrete failure: main had landed two BREAKING renames (#76's -server/-box suffixes, #77's --root-door) that no release carried. A reader followed the README's install command, got 0.2.0, typed the role name the same page told them to type, and the CLI rejected it. Hard cut, no aliases — test/cli.sh asserts the old names exit 2.

So the two options trade the same defect back and forth:

	Option A (today)	Option B (rig#103's ask)
Newcomer on the landing page	gets the dev tree by default	gets the latest release
Do the docs match the CLI they installed?	yes	no, whenever main is ahead — #89 exactly
Matches box and cast	no	yes

Neither is free. B is only safe when main and the latest release document the same surface, which is precisely the condition that does not hold during a rename cycle — and rig has had two.

What a builder would hit

There is a regression test pinning A (test/cli.sh:430-436), added by the same PR:

# The README on main documents main's CLI, so its FIRST full install command
check "README: the main-branch quick start installs the documented tree"

Anyone implementing B goes red on a test whose name states the opposing intent. That is the signature of a decision, not a defect — and the reason triage will not mint it.

Options, with a recommendation

1. Keep A. Accept the divergence from box/cast; rig's README is a working document for the tree it lives on. Costs nothing, changes nothing.
2. Take B, and re-address URGENT: README on main documents unreleased role names — the documented install (0.2.0) rejects every one of them #89 another way — e.g. the release-skew check PR docs: align README quick start with main #91 explicitly deferred ("cross-tag comparison of every README bootstrap role against the released role table"), so main's README cannot document a surface the default install does not have. Real work, and it must land with B, not after.
3. Neither — make the page say both. Keep A's command, and add one line naming the stable command directly under it instead of eleven lines later. Fixes the actual complaint (a newcomer meeting the dev tree unannounced) without reopening URGENT: README on main documents unreleased role names — the documented install (0.2.0) rejects every one of them #89.

Triage recommends 3, then 1. #103's underlying worry — that the first command a reader meets installs the development tree — is legitimate, but option 2 pays for it by restoring a documented-vs-installed mismatch that someone already had to file as URGENT, and option 3 gets the same benefit for the price of a sentence.

Decider: @danmt. Whichever way this goes, the answer should be written into the README as a comment or into test/cli.sh's block, so the next reader does not re-litigate it — this is the second time the line has been argued about in three days.

[dan-claude-bot]

Triage owes this thread the canonical block, and it was missing. The
analysis above is the escalation; these five lines are the contract
(heavy-duty/ceremony@main BUILDER.md → “The ruling ask”'s
five fixed field labels). Without a Default: there is no ladder and this thread can sit
forever, which is the failure the format exists to prevent.

🧭 needs-ruling — does main's README quick start install main, or the latest release?
Options:  1 — keep A (RIG_REF=main; the page matches the tree it lives on)   2 — take B (default install = latest release) and land the release-skew check with it   3 — keep A's command and put the stable command on the line directly below it
Recommend: 3, then 1, because #103's real complaint is a newcomer meeting the dev tree unannounced, and 3 fixes that for a sentence while 2 restores the documented-vs-installed mismatch someone already filed as URGENT (#89).
Blocked:  #103 item 2 only. Item 1 (the BOX_REF pin) is unaffected and continues — PR #122 implements it, is approved by the panel and mergeable, and closes #103 on merge. Nothing else on the board waits on this. When the ruling lands it is minted as a FRESH issue citing #103 and this thread; a closed #103 is not reopened for it.
Default:  option 3 at 2026-07-24T23:25Z if no ruling. Affirmatively reversible inside a PR: it adds one line to README.md, touches no install path, and leaves test/cli.sh:430-436 green — the test that pins A stays true under 3.

Two honest notes about the ladder itself.

The clock is anchored to the escalation comment above (2026-07-23T23:25Z), not
to a labeled event, because rig has no needs-ruling label — the
reconciler's taxonomy carries it, but the row post-dates the 0.1.0 pin every
consumer runs, so it exists in no repo but ceremony. That is
ceremony#102, open,
with a fix minted at ceremony#105.
A bot with triage cannot create a label either, so the flag that would make
this visible on #103 cannot be set by anyone but @danmt today. This thread and
that one are the same gap seen from both ends.

If the default fires, triage picks 3, mints the issue that carries it — citing
#103 and this thread for the reasoning — and stays accountable for it; the change
still lands as a PR a human merges, and you can overturn it at that merge.

---

Correction, 2026-07-24: this comment first cited rig's vendored .ceremony/BUILDER.md for the block. It is not there. The five-line ruling ask lives in ceremony@main BUILDER.md, and ceremony's only tag is 0.1.0 — which is what rig vendors, and which predates it. So the template is the same pin gap this comment already names for the needs-ruling label, not a separate one: rig has neither the label nor the doctrine that defines it, and both arrive together at the next pin bump (ceremony#102 / ceremony#105). The block above is unchanged and still binds triage — only the citation was wrong. Fixed in place rather than in a third comment, so a decider reads two comments and not four.

Correction, 2026-07-24 (second): the Blocked: line said "#103 stays claimed and buildable" and the paragraph above it promised to record a fired default "as a decision on #103". Both are about to stop being true — PR #122 implements item 1, carries Closes #103, and sits at state:needs-human with the whole panel approving, so #103 closes at the next merge and well before this ladder's 23:25Z default. That is correct and drops nothing: #103 was deliberately narrowed to item 1 on 2026-07-23, and item 2 has lived here ever since. Amended so the ruling's landing site is a fresh issue rather than a closed one — the decision, the options and the Default: are unchanged. Fixed in place for the same reason as the correction above: a decider should read two comments, not five.

[dan-claude-bot]

12-hour re-read of the ladder (LABELS.md: "the setter re-reads the default against what has landed and asks whether it still holds and whether doubt remains"). Overdue — the rung was at 11:25Z and this is 12:50Z. Two findings, and the first one is against my own recommendation.

1. Option 3 was already mostly shipped when I recommended it

My Recommend: line reads "3, then 1", where 3 is "keep A's command and put the stable command on the line directly below it." At the very SHA the escalation cites, 66d304f, the README already carried this eight lines under the quick start:

curl -fsSL .../install.sh | bash                   # the latest release
curl -fsSL .../install.sh | RIG_REF=0.2.0 bash     # pinned to a release
curl -fsSL .../install.sh | RIG_REF=main bash      # the development tree

Byte-identical on main today, at L29-31, with the prose above it already saying "This README tracks main, so the quick start installs that same development tree." So the stable command is not missing from the page and never was. Read literally, the default would fire and mint an issue whose deliverable is already on main — which is exactly the stale default the 12h rung exists to catch.

What is genuinely left is much smaller than my own wording claimed: the L18 fence is unlabelled and shows the dev command alone, and the stable channel sits behind a five-line paragraph. A newcomer who copies the first thing that looks like an install command never reaches L29. So option 3 narrows to one comment on the first fence, or one line hoisted into it — not "add the stable command to the README".

That is my error, not a change in the facts, and it is the correction that matters most here: it makes the default cheap where it read as substantial.

2. Option 2's hazard stopped being historical

The escalation argued against option 2 from #89, an incident. It is a live, nameable failure today:

• main's README documents rig bootstrap --undo with a copyable command at L251.
• 0.3.0 has it in neither the tree nor its README — git show 0.3.0:commands/bootstrap.sh and git show 0.3.0:README.md both return zero matches for --undo. It landed after the tag (bootstrap --undo: leave the tailnet, but only a join rig performed #63, in Unreleased), along with rig platform's stable machine ID (A machine has no stable identity — rig platform reports a hostname, which is neither stable nor unique #95).

Under option 2 a reader today installs 0.3.0 from main's README, types the flag that page shows them, and the CLI rejects it. That is #89 reproduced verbatim, with a flag name attached. And it is structural, not a wait: 0.3.1 is pending its drill run (#132, yours), and the moment it ships the skew reopens on the next merge to main. A README that tracks main is skewed against the latest release by construction, always, between releases.

The default

Direction holds and the new evidence points the same way, so this does not become a hard block. The deliverable is restated honestly:

Default (restated, clock unchanged): option 3 at 2026-07-24T23:25Z if no ruling — narrowed to labelling the L18 fence as the development channel and putting the release command in it, since L29-31 already carry all three channels. Affirmatively reversible inside a PR: README.md only, no install path touched, test/cli.sh:430-436 stays green.

Options, recommendation and the 23:25Z clock are otherwise exactly as posted at 00:51Z. This is a rung, not a re-flag; the ladder does not restart.

Unchanged

#103 closed at 07:01:16Z when PR #122 merged, as the second correction above anticipated. Item 1 shipped; the ruling's landing site is a fresh issue citing #103 and this thread, and a closed #103 is not reopened for it. rig still has no needs-ruling label to show this on the board (ceremony#102).

@danmt — if the answer is 1 (leave it alone entirely), one word here closes this and nothing is minted.

[dan-claude-bot]

Decision — the default fired. 2026-07-24T23:25Z passed with no ruling; per the ladder's past-24h rung (LABELS.md, ceremony#50 D13–D14) triage picks and stays accountable:

Option 3, as narrowed at the 12h re-read: the README's first fence names the development channel on a comment line and carries the latest-release command below the dev command — the dev command line stays byte-identical and first, because test/cli.sh:510-516 (#89's guard) pins exactly that. Nothing else on the page moves; L29-31 already carry all three channels. Option 2 stays rejected: it reverts #89's shipped fix, and the skew it would reintroduce is live today (--undo is documented on main and absent from 0.3.0).

Recorded as #149 — minted ready, carrying the full spec, the test constraint, and this thread as its reasoning. As promised above: a fresh issue, not a reopened #103.

@danmt — you overturn this at the merge gate, not before it: the change lands as an ordinary PR you can decline, and if the answer was "1 — leave it alone", closing #149 with that one word undoes everything. Resolving this thread; the decision record is this comment plus the two above it.