Skip to content

docs: fleet is 23 pairs now, and why a kit-only file needs no wave #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mcarter-astronautdev wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: fleet is 23 pairs now, and why a kit-only file needs no wave #32

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 15 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -230,22 +230,29 @@ carries the six caller stubs above plus `claude.yml` (the implementer, still a f
workflows) and `pull_request_template.md`.

**Not every repo takes the whole kit.** A repo that is not on the Bonsai → PR pipeline can install
`pr-first-review.yml` + `lint.yml` alone and skip the rest as inert weight. That subset is proposed for
[`driver-agents`](https://github.com/DriverDigital/driver-agents/pull/6) and
[`driver-agents-app`](https://github.com/DriverDigital/driver-agents-app/pull/2) — **both PRs are open,
not merged**, and they should land only *after* this repo ships `templates/github/lint.yml`, since until
then the file they install has no upstream source to be re-copied from. The trade-off is written up in
`pr-first-review.yml` + `lint.yml` alone and skip the rest as inert weight.
[`driver-agents`](https://github.com/DriverDigital/driver-agents) and
[`driver-agents-app`](https://github.com/DriverDigital/driver-agents-app) run that subset as of
2026-08-02 — neither had any `.github/workflows` before. The trade-off is written up in
`templates/github/README.md` under *Partial install*.

**A kit-only addition does not need a tag or a wave.** `lint.yml` shipped without either, and that was
correct: it changes no reusable, repins no stub, and carries no `uses: DriverDigital/workflows@<sha>` of
its own, so nothing deployed had to move. Note the direction of the obligation — **cutting the tag is what
creates the wave**, because the moment the latest tag is not `90f0d066` the audit's reference check fires
against all six stubs and `templates/` must be repinned and re-copied everywhere. Let a kit-only file ride
along with the next release that actually changes a reusable.

**`bonsai-status-sync.yml` finished converting at `v1.11.0`.** The reusable landed 2026-08-02 and its stub
landed in this tag's repin commit, so the kit now installs a 66-line stub instead of the old 190-line copy —
see *Release + repin order* above and [`docs/reusable-conversion-scope.md`](docs/reusable-conversion-scope.md).
The two-step was deliberate and matches how `dependabot-keep-current` was added: a new reusable's stub cannot
be pinned until the tag containing that reusable exists, so the reusable lands first and the stub follows in
the repin commit. `lint.yml` fails the build on any stub still carrying a placeholder pin. **The v1.11.0 wave
has landed** — `tools/fleet-pin-audit.sh` reads clean across all 21 repo@branch pairs (108 pin rows at
`90f0d066`, 127 files byte-identical to `templates/` after store-handle normalization, verified 2026-08-02),
so every consumer repo now runs the 66-line stub.
has landed** — `tools/fleet-pin-audit.sh` reads clean across all **23** repo@branch pairs (110 pin rows at
`90f0d066`, 131 files matching `templates/` after the two documented normalizations, verified 2026-08-02),
so every consumer repo now runs the 66-line stub. The count moved 21 → 23 the same day, when `driver-agents`
and `driver-agents-app` took the partial install below; the wave itself covered the original 21.

**`claude.yml` stays a per-repo copy** — that half of the conversion is tabled pending the OIDC spike (whether
Claude App token minting survives inside a cross-repo reusable), so it remains the kit's main drift surface
Expand Down
12 changes: 6 additions & 6 deletions docs/fleet-operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,14 @@ Written 2026-08-02 from the v1.7.0 → v1.11.0 waves.

## The fleet

**21 repo@branch pairs**, and the split matters because two different numbers are correct depending
**23 repo@branch pairs**, and the split matters because two different numbers are correct depending
on the question:

| Set | Size | What it is |
|---|---|---|
| **Repin-wave targets** | **21** | Every pair carrying any kit caller stub. What `tools/fleet-pin-audit.sh` enumerates, and what a pin-only wave must cover — miss one and `--stale` never reads clean. |
| **Repin-wave targets** | **23** | Every pair carrying any kit caller stub. What `tools/fleet-pin-audit.sh` enumerates, and what a pin-only wave must cover — miss one and `--stale` never reads clean. |
| **Full-kit targets** | **18** | Pairs carrying `claude.yml` *and* `bonsai-status-sync.yml`. Verified branch-by-branch across all 618 org branches: zero rows where one is present without the other, so a wave touching one can touch both. |
| **Difference** | **3** | `Team-Laird@develop`, `The-Gathery@develop`, `driver-bonsai-mcp@main` — stub rails only, neither full workflow. They still need the pin repin. |
| **Difference** | **5** | `Team-Laird@develop`, `The-Gathery@develop`, `driver-bonsai-mcp@main`, and (2026-08-02) `driver-agents@main` + `driver-agents-app@main` — stub rails only, neither full workflow. They still need the pin repin. |

Palmers contributes **8** of the 18 (one per country branch: `main`, `-au`, `-ca`, `-in`, `-ma`,
`-me`, `-sa`, `-uk`); the other 10 are single-branch repos including Avara.
Expand Down Expand Up @@ -177,16 +177,16 @@ the installed stub — the wave covers it anyway.
`enforce_admins` is `false` fleet-wide, which is what makes direct-push waves work. Two live kit
branches have **no protection at all** — `studio-sulzer@main` and `Team-Laird@develop` (404 on the
protection endpoint). Every other kit branch has a protection object — but **having one is not the
same as requiring a human**, and the gap is wider than those two. Surveyed across all 21 pairs
same as requiring a human**, and the gap is wider than those two. Surveyed across all 23 pairs
2026-08-02:

| Pairs | `required_approving_review_count` | |
|---|---|---|
| 11 | `1` | Avara, Driver-Digital-Website, Kissy-Kissy, LaPointe, LittleMe, The-Gathery, client-workspaces, driver-bonsai-mcp, foundrae-blackridge, plugins, vite-plugin-shopify-clean |
| 13 | `1` | Avara, Driver-Digital-Website, Kissy-Kissy, LaPointe, LittleMe, The-Gathery, client-workspaces, driver-agents, driver-agents-app, driver-bonsai-mcp, foundrae-blackridge, plugins, vite-plugin-shopify-clean |
| **8** | **`0`** | **every Palmers branch** — `main`, `-au`, `-ca`, `-in`, `-ma`, `-me`, `-sa`, `-uk` |
| **2** | **no protection at all** | **`studio-sulzer@main`, `Team-Laird@develop`** |

The kit's onboarding steps assume a human-approver rule exists. On **10** of the 21 pairs it does
The kit's onboarding steps assume a human-approver rule exists. On **10** of the 23 pairs it does
not, so a bot signal alone could satisfy a merge — not the 2 this section used to name.

On this repo, `main` requires **`actionlint`** (set 2026-08-02; before that `required_status_checks`
Expand Down