From b88495105df68177cd9fb5c6369fbab354163f1d Mon Sep 17 00:00:00 2001 From: codex-bot-andresmgsl Date: Mon, 20 Jul 2026 17:32:43 +0000 Subject: [PATCH] test: tighten README channel contract --- README.md | 6 +- .../2026-07-20-readme-install-channel.md | 69 ------------------- ...026-07-20-readme-install-channel-design.md | 36 ---------- test/cli.sh | 16 ++++- 4 files changed, 16 insertions(+), 111 deletions(-) delete mode 100644 docs/superpowers/plans/2026-07-20-readme-install-channel.md delete mode 100644 docs/superpowers/specs/2026-07-20-readme-install-channel-design.md diff --git a/README.md b/README.md index 2dcdc33..73e0d12 100644 --- a/README.md +++ b/README.md @@ -458,9 +458,9 @@ command is exactly who that refusal catches (it names the new spelling). > above.** The seed preinstalls rig via its curl installer, which resolves > `RIG_REPO`/`RIG_REF` — and since rig#32 the installer defaults to the > **latest release**, with `RIG_REF=` the pin and `RIG_REF=main` the -> dev channel. Until rig cuts 0.1.0 there is no release to resolve, so the -> seed must set `RIG_REF=main` explicitly (the default channel fails loudly -> rather than falling back). That inverts the install edge on this page: +> dev channel. A seed that needs main must set `RIG_REF=main` explicitly; +> the default channel never silently falls back to a development branch. +> That inverts the install edge on this page: > rig installs box on VM-hosting machines, and box guests now install rig. > `RIG_REPO`/`RIG_REF` are the pin points, or point them at a frozen branch > of your own fork. The seed side of this edge is box#81's to document. diff --git a/docs/superpowers/plans/2026-07-20-readme-install-channel.md b/docs/superpowers/plans/2026-07-20-readme-install-channel.md deleted file mode 100644 index e5f076f..0000000 --- a/docs/superpowers/plans/2026-07-20-readme-install-channel.md +++ /dev/null @@ -1,69 +0,0 @@ -# README Install-Channel Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Ensure the `main` README installs the same development tree whose CLI it documents. - -**Architecture:** Keep installer channel behavior unchanged and correct the documentation entry point. Add one source-level regression assertion to the existing dependency-free CLI suite. - -**Tech Stack:** Bash, Markdown, the existing `test/cli.sh` assertion harness. - -## Global Constraints - -- The stable latest-release and pinned-tag channels remain documented. -- No compatibility aliases or installer behavior changes. -- The regression must run inside the existing `bash test/cli.sh` CI step. - ---- - -### Task 1: Align the README install channel - -**Files:** -- Modify: `README.md` -- Test: `test/cli.sh` - -**Interfaces:** -- Consumes: The existing `check` helper in `test/cli.sh`. -- Produces: A README quick-start command containing `RIG_REF=main bash`. - -- [ ] **Step 1: Write the failing regression test** - -Add this assertion near the existing README checks in `test/cli.sh`: - -```bash -check "README: the main-branch quick start installs the documented tree" 0 "" \ - grep -qF 'curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RIG_REF=main bash' "$ROOT/README.md" -``` - -- [ ] **Step 2: Verify the test fails for the reported mismatch** - -Run: `bash test/cli.sh` - -Expected: one failure named `README: the main-branch quick start installs the documented tree` because the full command lacks `RIG_REF=main`. - -- [ ] **Step 3: Make the minimal README correction** - -Change the primary install command to: - -```sh -curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RIG_REF=main bash -``` - -Explain that the README tracks `main`; retain examples for the default latest-release and pinned-tag channels, and delete the obsolete transitional notice about cutting 0.1.0. - -- [ ] **Step 4: Verify the focused and full suites pass** - -Run: `bash test/cli.sh` - -Expected: all CLI assertions pass with zero failures. - -Run: `bash test/release.sh` - -Expected: all release assertions pass with zero failures. - -- [ ] **Step 5: Commit** - -```bash -git add README.md test/cli.sh -git commit -m "docs: align README quick start with main" -``` diff --git a/docs/superpowers/specs/2026-07-20-readme-install-channel-design.md b/docs/superpowers/specs/2026-07-20-readme-install-channel-design.md deleted file mode 100644 index de04e19..0000000 --- a/docs/superpowers/specs/2026-07-20-readme-install-channel-design.md +++ /dev/null @@ -1,36 +0,0 @@ -# README install-channel alignment - -## Problem - -The landing-page README describes the unreleased CLI on `main`, including -the `*-server` and `*-box` role names, but its first install command selects -the latest release. At present that is 0.2.0, whose CLI accepts the retired -role names instead. A reader following the quick start therefore installs a -CLI that rejects the README's examples. - -## Decision - -The README is documentation for the branch that contains it. Its primary -install command will explicitly set `RIG_REF=main`, making the installed tree -match the commands documented below it. The stable channel remains documented -next to the development and pinned channels, but is no longer presented as the -matching prerequisite for the `main` README's quick start. - -The obsolete pre-0.1.0 transitional notice will be removed. No installer -behavior, role compatibility aliases, or release process will change. - -## Regression protection - -The dependency-free CLI test suite will assert that the README's full GitHub -installer command opts into `RIG_REF=main`. This directly protects the broken -onboarding path without trying to infer semantic compatibility between every -README example and every historical release. - -## Acceptance criteria - -- The first complete installer command in `README.md` installs `main`. -- The README still explains how to install the latest release and a pinned tag. -- The stale “until 0.1.0 is cut” notice is absent. -- `bash test/cli.sh` fails on the old README and passes after the documentation - correction. - diff --git a/test/cli.sh b/test/cli.sh index b490e7f..a2173d7 100644 --- a/test/cli.sh +++ b/test/cli.sh @@ -427,11 +427,21 @@ check "bootstrap: --users does not reach the tenant roles" 2 "unknown flag" \ "$ROOT/commands/bootstrap.sh" claude-box --users "$BOOT_USERS/ok" check "bootstrap: usage explains why tenants take no --users" 0 "box-minted GUEST" \ "$ROOT/commands/bootstrap.sh" --help -# --- README: the box rename (#12) -------------------------------------------- -# The README on main documents main's CLI, so its first full install command +# --- README: install channels (#89) ------------------------------------------ +# The README on main documents main's CLI, so its FIRST full install command # must opt into that tree instead of silently selecting an older release. +readme_first_full_install="$(grep -m1 -F 'curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh' "$ROOT/README.md")" check "README: the main-branch quick start installs the documented tree" 0 "" \ - grep -qF 'curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RIG_REF=main bash' "$ROOT/README.md" + test "$readme_first_full_install" = \ + 'curl -fsSL https://raw.githubusercontent.com/heavy-duty/rig/main/install.sh | RIG_REF=main bash' +check "README: no stale pre-0.1.0 release notice" 1 "" \ + grep -qF 'Until rig cuts 0.1.0' "$ROOT/README.md" +check "README: still documents the latest-release channel" 0 "" \ + grep -qF 'curl -fsSL .../install.sh | bash # the latest release' "$ROOT/README.md" +check "README: still documents the pinned-tag channel" 0 "" \ + grep -qF 'curl -fsSL .../install.sh | RIG_REF=0.1.0 bash # pinned to a release' "$ROOT/README.md" + +# --- README: the box rename (#12) -------------------------------------------- # The philosophy line must point at heavy-duty/box — the old claudebox slug # only works through a GitHub redirect that one squatted rename away from # breaking (box's own installer was already bitten by the rename once). A