Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 3 additions & 1 deletion .claude/skills/fleet-spawn-workers/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,8 @@ bound.** These rows are the part that does not.
| The outside ladder is a shape to copy, not a size to adopt | Anthropic's write-up of its multi-agent research system keeps the sizing rule in the orchestrator. It calls the lack of one a common failure mode, and records fifty subagents spawned for one simple query. |
| Its integers do not come with it | The ladder runs from one agent for simple fact-finding, through two to four for a direct comparison, to ten or more for complex research. |
| The condition that stops them transferring | **Those were measured on research tasks, and the same post says coding parallelises worse.** No number in that ladder has been measured on this fleet. |
| What bounds YOUR number is in your own playbook | [MANAGER.md](../../../roles/MANAGER.md), *A Manager's fan-out is bounded by one window and by shared runners*. The retired [CONSOLE.md](../../../roles/retired/CONSOLE.md) bounded a fan-out by accounts and by what the Lander could land; that is record, not a live bound. |
| What bounds YOUR number is in your own playbook | For a Manager, [MANAGER.md](../../../roles/MANAGER.md), *Brief at full speed*: usage holds bound it, and the merge queue does not (owner ruling 2026-10-26). |
| **CORRECTED 2026-10-26** | The row above cited *"A Manager's fan-out is bounded by one window and by shared runners"*, a MANAGER.md heading that does not exist. |
| The retired bound | [CONSOLE.md](../../../roles/retired/CONSOLE.md) bounded a fan-out by accounts and by what the Lander could land. That is record, not a live bound. |

---
3 changes: 2 additions & 1 deletion docs/KORUS-BUILD.md
Original file line number Diff line number Diff line change
Expand Up @@ -167,7 +167,8 @@ Read each builder's result. Check the branch reached the remote yourself:
You decide when to cut a pull request. Default to one per wave: merge the wave's branches onto a
fresh branch from origin/main with git merge --no-ff, run the checks once on the combined tree,
and open one pull request. Build the batch in a throwaway worktree, never your own. Cut it when
every builder has reported, when it holds five items, or before you close, whichever comes first.
every builder has reported or before you close, whichever comes first. There is no item cap. Cut
without a builder still running about 30 minutes after the rest reported.
Give an item its own pull request if it fixes a red main, changes a security control, supersedes
an ADR, or must land in order against another open pull request. Send an item that is red or
conflicts back to a builder. Never write a conflict resolution yourself. roles/MANAGER.md, "When to cut a pull request", holds
Expand Down
6 changes: 5 additions & 1 deletion docs/roles/manager.card.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ pull request (PR), label it `qa` with the Builder's QA line under it, and hand i
*When to cut a pull request*, holds the rules.

- Default to one PR per wave, merged in a throwaway worktree and checked as one tree.
- Cut it when every Builder has reported, at five items, or before you close.
- Cut it when every Builder has reported, or before you close. No item cap (Owner ruling 2026-10-26).
Cut without a Builder still running about 30 minutes after the rest reported.
- Its own PR: a red-`main` fix, a security control, an ADR supersession, an ordering constraint.
- An item that is red or conflicts goes back to a Builder. Never write that resolution yourself.

Expand Down Expand Up @@ -47,6 +48,9 @@ before assigning files.
- Do not check the pool before you open a PR. Owner ruling 2026-09-18, which retired the check that
told you to. Five Managers all reading "clear" open together, which manufactures the burst the
check was meant to prevent. Open when your own work is ready.
- Do not limit briefing by the open PR count, the merge queue's depth, or the Lander's merge rate.
Owner ruling 2026-10-26: brief at full speed and batch; the Lander works the queue down. Usage
holds still bind. `roles/MANAGER.md`, *Brief at full speed*.
- Do not assume you are the only Manager. Check other workers' holdings before assigning a file.
- Never infer an account roster. Only the Owner assigns it.

Expand Down
43 changes: 25 additions & 18 deletions roles/BUILDER.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,9 @@ a gate, and never mislead a teammate or the owner about what you built.
**A team building nothing at all is a failure to raise at once, not a quiet lane.** Say so to the
Manager, the seat that can act on it and the seat that opens the pull request.

**Two to four is the most you oversee, not the least you must reach.** Owner ruling 2026-08-28. See
*A claim that outlives the work is a slot nobody can see*, which holds the rest of this rule.
**RETIRED 2026-10-26 by owner ruling: the lane ceiling.** This read *"Two to four is the most you
oversee, not the least you must reach. Owner ruling 2026-08-28."* Work at full speed. *A claim that
outlives the work is a slot nobody can see* says what still stops a start.

**This file carries no live state on purpose.** Item numbers, lane assignments, queue tables, pull
request numbers and "pick up here" lists belong in a dated episode note. See *The role file holds
Expand Down Expand Up @@ -109,12 +110,13 @@ Console, and do not wait on one.
| Where a question actually lands | **In your report to the Manager, which carries it onto the pull request it opens.** Findings on a pull request outlive the session; findings in mail do not. |
| Why you cannot post it yourself | For a NEW branch the pull request does not exist until you have exited. |
| The one case where you can | A follow-up brief onto a branch whose pull request is already open. Then the brief names the number, and you comment there as well as reporting. |
| Sections below that still name a Dispatcher or a Console | A record of how the fleet ran, not a live route. **Who holds the START THROTTLE now is OPEN.** |
| Sections below that still name a Dispatcher or a Console | A record of how the fleet ran, not a live route. |
| **CORRECTED 2026-10-26 by owner ruling: the START THROTTLE** | The row above also read *"Who holds the START THROTTLE now is OPEN."* The owner retired the throttle, so no seat holds it. 5d says what still stops a start. |
| Expiry | This retires when the owner names a successor seat or restores one of the three. |

Do not assume the throttle moved to the Manager, and do not read a quiet lane as a throttled one on
that assumption. Mail waits for the recipient's next turn. See [COMMON.md](COMMON.md), *Mail is a
mailbox, not a doorbell, and it expires in 72 hours*.
**Do not assume a quiet lane was throttled.** Since 2026-10-26 only the usage controls in 5d stop a
start. Mail waits for the recipient's next turn: [fleet-message-a-peer](../.claude/skills/fleet-message-a-peer/SKILL.md),
*Mail is a mailbox, not a doorbell, and it expires in 72 hours*.

### If the brief does not answer something you must know, do not guess and do not wait

Expand Down Expand Up @@ -594,8 +596,8 @@ claim id, a pull request number, a count from `claim.ps1 -List`, a timestamp.
**Never a self-assessment of effort.** "No -- 1 of 4 moving, 3 blocked on the parser item" is
checkable; "Mixed, working hard" is not.

**On a "no": say the number and what you can take.** "I hold 2, I can take 2 more, my lane is <x>"
is actionable; "not enough" is not, to anyone replenishing four lanes.
**On a "no": say the number and what you can take.** "I hold 2, I can start 3 more now, my lane is <x>"
is actionable; "not enough" is not, to anyone replenishing lanes.

Reasoning goes in the prose above the table. **A dashboard that has to be read is not a dashboard.**

Expand Down Expand Up @@ -1270,19 +1272,24 @@ ever fire step 14 on them.
Release those claims before you exit, and say you did. The same list is in [COMMON.md](COMMON.md),
*What a Builder still releases*, and in 4b; if the three disagree, COMMON governs.

**An item counts against your four while it is being *worked*, not while its claim is held.**
Built-and-awaiting-merge is zero occupancy. Say so, so others count it the same way.
**An item is occupancy while it is being *worked*, not while its claim is held.**
Built-and-awaiting-merge is zero occupancy. Say so, so others count it the same way. This read
*"counts against your four"* until 2026-10-26, when the four went.

**And four is the MOST YOU OVERSEE, not the least you must reach.** Owner ruling 2026-08-28: starts
are throttled by burn, and **that throttle is not yours.**
**RETIRED 2026-10-26 by owner ruling: the four-item ceiling and the throttle on starts.** This read
*"four is the MOST YOU OVERSEE"* and *"starts are throttled by burn"*. An owner ruling of 2026-08-28
set both. Asked about both, the owner selected *"Retire it"*.

The ruling named the DISPATCHER as its holder. That seat was retired 2026-09-01 and the owner has
not named a successor, so **who holds it is OPEN.** A lane holding four items with one running
because its starts are held is *compliant*, and should report the reason, not a shortfall.
That ruling named the Dispatcher as the throttle's holder. After that seat retired on 2026-09-01,
this file recorded who held it as OPEN.

**So separate the two lanes that both look like "under four".** One is running less because it was
told to. The other could start something and has not. **This trap is about the second.** Reporting
the first as a failure buries the second, which is the one worth finding.
**Work at full speed. Usage controls can still stop a start.** [MANAGER.md](MANAGER.md), *Brief at
full speed*, points to them; section 8 here covers the Workflow gate. A lane held by one is
*compliant*, and reports the control, not a shortfall.

**So separate the two quiet lanes.** One is running less because a hold told it to. The other could
start something and has not. **This trap is about the second.** Reporting the first as a failure
buries the second, which is the one worth finding.

Measured 2026-08-13: a builder concluded two items into an armed pull request. It correctly could
not release the claims, and correctly stated both as deliberately held in three places. **Then it
Expand Down
4 changes: 4 additions & 0 deletions roles/LANDER.md
Original file line number Diff line number Diff line change
Expand Up @@ -1237,6 +1237,9 @@ Coordination can order a queue; it cannot widen one. The most expensive mistake
to run parallel producers into a serialised queue and then spend the session ordering the pile-up. It
has happened: 13 PRs merged in one drain while the open count still grew from 3 to 6.

**The remedy is batching, never fewer producers** (owner ruling 2026-10-26). Managers brief at full
speed; the second table's *Never ask a Manager to brief less* row says so.

| Fact | Consequence |
| --- | --- |
| `ci.yml` triggers on `pull_request` and `push: branches: [main]` only | A feature-branch push runs NOTHING of `ci.yml`. Only `branch-leak-scan.yml` fires, and it is small. Unopened branches are nearly free to hold. **CORRECTED 2026-09-23**: this read *"runs NOTHING"*, which ignored that scan. |
Expand All @@ -1251,6 +1254,7 @@ has happened: 13 PRs merged in one drain while the open count still grew from 3
| Re-measure any cost model | The old docs-only figures (2, 2, 2 and 13 minutes) were measured against an older required set and no longer hold. Re-measure with `max(completedAt) - min(startedAt)` over the REQUIRED contexts only. |
| Do this | Batch independent code changes into one PR. Keep at most ONE code PR in flight and hold the rest as pushed branches. Serialise only genuine ordering constraints. |
| Whose decisions that row governs | Yours, in the queue. Since 2026-09-23 it does not govern a Manager's opening: a Manager does not count open PRs before it opens one. |
| Never ask a Manager to brief less -- ADDED 2026-10-26 | Owner ruling: Managers brief at full speed, and you work the queue down. Batching is this section's remedy, not fewer briefs. [MANAGER.md](MANAGER.md), *Brief at full speed*. |
| Who batches -- ADDED 2026-09-23 | **The Manager, at step 9.** Owner ruling. Before it, this table said to batch and named no seat to do it, while MANAGER.md said to keep independent changes apart. [MANAGER.md](MANAGER.md), *When to cut a pull request*, now holds the rule. |
| Do NOT tell Builders "small and independent is the right shape" | That is correct for avoiding CONFLICTS and exactly wrong for a queue rate-limited by PR COUNT. The two pieces of advice look identical at the branch level and diverge only at the PR level. |
| Batching trap 1 | `git cherry-pick` does not run pre-commit, so batched commits pass no local gate on creation. Run the ledger and backlog checks by hand, plus the affected tests. |
Expand Down
Loading
Loading