7-Use-Cases: architects settled the two invented specifics in the block
Keeps the portable CLAUDE.md block byte-identical with claude-bridge's copy.
Removes the 'after two rounds' ceiling (no evidence for the number, and it
implied a round counter fleetd does not have) and turns the operator-only list
into explicit examples, with 'granting access' in place of 'credentials'.
7-Use-Cases: a blocked lead consults architects, not the operator
The operator set this rule on 2026-09-19: when a decision blocks a lead, it
consults one or more architect members, who are authorized to agree on one
decision and unblock. The operator is not asked.
The paragraph also carries the reason the record is mandatory. The operator's
old notification channel was the block itself -- work stopped, so they found
out. Removing the block removes that signal, so the decision goes on the
ticket, which reaches them whether or not they are at a terminal.
Kept byte-identical with the block in fleet/fleetd CLAUDE.md.
Features: loop health in fleet_list//healthz (#562), and TIMED_OUT_UNCONFIRMED (#571)
7-Use-Cases: re-sync the portable CLAUDE.md block after #562 added the
loopHealth row to the intent->tool table.
11-Features: two entries. The loop-health one records the failure
DIRECTION that matters -- a false negative where nothing ever fires is
worse than a muted false positive -- and why the wiring test exists.
The TIMED_OUT_UNCONFIRMED one records the default -> "done" that told
REST callers a delegation had completed, and the order dependence in
using a compile error to find enum readers.
7-Use-Cases: sync the portable CLAUDE.md block — the ticket is the pull channel, the brief is write-once
Matches fleet/fleetd PR #558. A push delivery needs the recipient free at send
time; a pull channel needs only that they look before acting. Member gets a new
turn-contract item 4 (re-read the ticket; a contradicting ticket comment is newer
and wins); the lead gets the obligation that makes it safe (all corrections go to
the ticket, the brief is write-once).
7-Use-Cases: sync the portable CLAUDE.md block — forge MCP server vs the working GITEA_TOKEN
Propagated from claude-bridge CLAUDE.md (commit be07ed2). The block must stay
byte-identical with the template here; the sync check in CLAUDE.md reports
"in sync: True" after this change.
Two sentences changed. Both now name the forge MCP server specifically, and
say that the repo-scoped GITEA_TOKEN the daemon injects is a separate route
that does work, so a worker never skips opening its own PR because an MCP
forge tool failed.
Features: a lead session can replace itself when its context fills up
fleetd #480 (#483, #484, #485). Covers what the cycle is, the leadRollover:
knob and its defaults, why the three design decisions were made the way they
were (the lead asks and nothing watches it; /clear in the same pane rather than
stop-and-relaunch; the operator confirms too), and six gotchas.
Two of those gotchas are measured facts that cost real debugging: /clear routed
through Injector wedges the pane for ever because it produces no turn boundary,
and the settle waits must require IDLE or DONE rather than injectable(), which
also accepts BLOCKED — a live turn paused on an approval prompt.
The last gotcha records what is NOT proven: nothing has yet shown end-to-end
that a freshly cleared pane picks up the bootstrap prompt. Stated with the
bound on the damage if it does not, rather than left out.
7-Use-Cases.md carries the matching fleet_handover row in the portable
CLAUDE.md block template, byte-identical with the project's own copy.
Use Cases: invariant 5 states a purpose, not a banned tool
Propagates the canonical block change merged in the repo as eccd054
(fleetd #458). Invariant 5 was:
Never drive the terminal multiplexer directly (no herdr CLI, no socket).
It banned a mechanism. What it is for is banning a control plane, and the
two readings pick out the same actions in every project except the bridge's
own repo, where the multiplexer is the subject under test. Four contract
tests open the herdr socket on purpose, so a worker assigned to herdr code
read invariant 5 and found the only action that could finish its task was
banned. It now reads:
Never move a fleet session, pane or peer except through the bridge.
The herdr CLI and its socket stay in the text, as the usual example of the
banned route rather than as the ban itself.
The sync check in CLAUDE.md prints "in sync: True" against this file. Block
size 17557 characters / 17718 bytes.
fleetd #421: a lead can read its own held peer mail
Features entry for fleet_poll{coordId} — primary-only, non-destructive,
full bodies. Records why READ was not reused (the roster-carries-no-secrets
grant does not cover a lead-to-lead body) and the mailbox.pending: 0 trap.
Also re-syncs the portable CLAUDE.md block template with the repo's copy:
the #421 work added an intent->tool row for reading held peer mail, and a
worker cannot commit this submodule.
charter: a peer lead is answered with fleet_send, not fleet_reply
`fleet_reply` has no route to a peer lead. `AmqpReplyInbox` publishes to
`agent.<target>.inbox` and a lead's own terminal has no such queue, so the
publish is refused. The template told every lead to use it anyway.
Three edits to the canonical block:
- the intent->tool row now says `fleet_send{coordId}`, or `{sessionId}` for a
peer on the same host, and says plainly that `fleet_reply` is refused
- the prose says WHY: `fleet_reply` resolves a member's blocked `fleet_send`,
while a peer's coord-id message is durable and non-blocking, so there is
nothing for it to resolve
- lead<->lead item 3 gains the data-point rule: N observations are N data
points only if they differ in the axis you are trusting
Wording for all three drafted by the fleet01 lead, who verified the missing
queue namespace independently. The data-point rule has caught three separate
errors in a day, in both directions — one cause blamed for N failures, and
N agreeing measurements that shared one instrument.
Tracked as fleetd #391.
charter template: a measured fact in an addendum must carry its own deletion trigger
Propagated from claude-bridge CLAUDE.md. Placed in the canonical block's boundary
paragraph, not in the orchestration body: that paragraph is already about the
addendum layer rather than about protocol, every project that mounts the bridge
inherits it, and it sits about 3800 characters before the primary's step list, so
it does not dilute the steps a lead reads while working.
The reasoning is the fleet01 lead's. Its kb addendum held a dated merge-refusal
section carrying an instruction to delete itself once it stopped reproducing. On
2026-09-08 UTC the operator granted merge rights, the lead re-ran the probe, got
409 where it had got 405, and deleted the section as instructed.
The lead's point, which is the one worth keeping: what made the banner work was
not emphasis. It was that the falsification condition was executable. The banner
carried the exact probe, the reason for the all-zeroes head_commit_id, and what
each response code meant, so the lead did not have to reconstruct the experiment
or decide what would count as refutation. A banner reading 'this may be out of
date, verify before relying on it' costs the same space and does nothing, because
deciding what would falsify a claim is the expensive step and a reader in the
middle of another task will not pay it. Hence four parts, not one: the date, the
command, what each outcome means, and the instruction to delete.
The last clause names why this machinery is worth its space at all. Most stale
notes are merely wrong. This one went stale in the dangerous direction: it would
have told a future lead it could not merge at the moment merging became its job,
silently and with confidence. A note that goes harmlessly stale does not need
this.
Sync check in the claude-bridge addendum reports 'in sync: True'.
charter template: test a refusal, and do not count a transport failure as one
Propagated from claude-bridge CLAUDE.md. The step 8 refusal paragraph told a lead
what to do when the forge refuses a merge, but not how to establish that it did.
Both halves came from the fleet01 lead, measured on akb/kb on 2026-09-08 UTC.
First: it re-ran the all-zeroes head_commit_id probe after the operator granted
merge rights, and got HTTP 409 'head out of date' where the same request gave 405
'User not allowed to merge PR' on 2026-09-06. A 409 is payload validation, which
is only reachable after the permission gate, so the grant took. The lead reports
the repository permissions object did not change at all across that flip -- still
admin:false, push:true, pull:true. I did not check that object myself; my forge
token is a different identity and would read a different one. Merge rights on a
protected branch live in branch protection, so a permissions field is wrong in
both directions and only the probe tells them apart.
Second: the lead's first probe attempt returned HTTP 000, because GITEA_HOST
already carries the scheme and a trailing slash and the URL came out as
https://https://git.ltms.dev//api/... A transport failure looks exactly like a
refusal if the test is 'not 200'. That is the trap worth naming, because the
whole point of the probe is to tell a refusal apart from everything else.
Sync check in the claude-bridge addendum reports 'in sync: True'.
portable CLAUDE.md block: step 8 when the forge refuses the merge
Kept byte-identical with claude-bridge/CLAUDE.md (2f71a30). Measured on fleet01
against akb/kb: the API returns 405 'User not allowed to merge PR' before it
validates the payload, and main is protected, so neither merge route is open to
that lead.
#168: rebuild chapters 1, 2, 7, 8 and 9 against the source
The audit marked all five REBUILD. Every factual claim on them is now checked in
the code and carries a file:line reference.
What was wrong and is now fixed:
- Ch.1 named a `fleet_read` tool and an SSE `GET /events` route. Neither exists.
It also named Redis Streams and NATS JetStream as the queue; the shipped inbox
is AMQP. The subscription boundary is back as its own section, sourced from
SubscriptionGuard, and the REST list now matches FleetApp.build().
- Ch.2 described tool parameters that were never shipped. The tool table now
comes from each tool's own schema method.
- Ch.7 was built on `ccs` profiles and on send parameters that do not exist.
Every flow now uses the real tools. The portable CLAUDE.md block is unchanged,
byte for byte, and the sync check still passes.
- Ch.8 presented old plans as the current stack. It is now a delivery record in
four states, and "built, not switched on" means no host enables it today —
AMQP and the coordinator mailbox are both on here, so both moved to live.
- Ch.9 had drifted from the source in its package, class and endpoint map.
Also: chapters 1, 2 and 8 had "I checked this in the code" written on the page
itself. That belongs in a worker's report, not in a reference page. The pages now
state the fact and cite the line.
Every Mermaid diagram was rendered with mmdc before this commit.
Match the code cutover: daemon name, config (fleetd.yaml), scripts, launchd/
systemd units, module dir, and MCP tool prefix bridge_* -> fleet_*. Kept:
the BRIDGED_MEMBER security marker, mcp__bridge__ (historical mount name), and
the .bridged-worktrees on-disk path. The portable CLAUDE.md block stays
byte-identical with the repo's CLAUDE.md.
Features: auto-compact window (CB-636) + cross-host lead coordination (CB-637)
Add two Features entries and propagate the cross-host peer-lead coordId row
into the canonical CLAUDE.md block template (7-Use-Cases). The block stays
byte-identical with the copy in the fleetd repo's CLAUDE.md.
CB-632: the portable CLAUDE.md block names the member mount fleet
The three launchers now write the MCP server as "fleet", not "bridge", so a
member addresses its tools as mcp__fleet__*. The role-detection ladder in the
block quoted the old prefix. A member spawned before this change still says
mcp__bridge__*, so the ladder names both.
Kept byte-identical with CLAUDE.md in fleet/fleetd.
CB-622: sync the portable CLAUDE.md block — tools are now fleet_*
Keeps the template byte-identical with claude-bridge/CLAUDE.md. Also fixes
the fallback ladder's charter quote, which said 'off-subscription worker'
while REPLY_CHARTER has long said 'spawned member' — so that rung of the
ladder could never fire.
CB-584: sync the portable block, and catalogue the resume hint
The bridge_spawn and bridge_list rows in the intent table changed on
main, so the wiki template had drifted from CLAUDE.md. Re-synced; the
check now prints 'in sync: True'.
Features entry for the failed-ticket session id: what it is, that it
needs no knob, why it exists (stage C saves the files, this saves the
thread), and that its absence is the normal case rather than a fault.
CB-593: the portable block no longer claims a member mounts only the bridge
Measured on live members: a Claude Code member also inherits the operator's
user-scope MCP servers from ~/.claude.json (gitea, context7), because
--mcp-config adds to that scope rather than replacing it. An opencode member
gets the bridge only. The old sentence was false for one backend and true for
the other.
The forge tools that appear are mounted but cannot authenticate: CB-592
shadows GITEA_ACCESS_TOKEN with a blocked sentinel, so every call fails with
'invalid username, password or token'.
CB-560/562/563: correct the pages the architect fix invalidated
Three entries described behaviour that CB-548 and today's repairs changed:
* "A lead can be delivered to" said MemberPresence is populated only for a
worker. It is populated for every spawned member — worker or architect, never
a lead. That sentence was the exact assumption that left every architect
undeliverable for a day.
* Its gotcha said the readiness-gate failure is mute. CB-562 gave it a WARN that
names the target, the counts and the grace, so a readiness failure no longer
reads as a turn stall.
* "Advisory architect slots" claimed an architect resolves as `architect` and
can send. True, and it could not receive anything, which the entry did not
say. It now records the delivery condition and the lesson: shipping the
binding is not shipping the role.
New entry for CB-563, since nothing documented the completion fallback's 4000
character cap — a clipped report used to be indistinguishable from a whole one.
7-Use-Cases.md carries the portable CLAUDE.md block, re-synced byte-identical
with the repo copy.
11, 7: the multi-lead arc — two leads as peers, and the fleet they can see
Chapter 11 gains seven entries covering CB-530..536, the arc that turns one
primary-plus-workers into two leads working as peers:
CB-530 `leaders:` — a registry, not a singleton pin
CB-530 unknown top-level config keys are named at load (the bug that let a
hand-written `leaders:` block look configured while being inert)
CB-531 `leadScan:` — discover a lead by the tab label a human typed
CB-532 leads message each other and are answered; `primary:` retired, with
reply nudges now following the lead that delegated
CB-534 a lead is deliverable — the CB-113 readiness gate opens for one
CB-535 `bridge_list` returns `leads` alongside `workers`, `self` on your row
Each carries the why, not just the knob. CB-534's and CB-535's exist because both
failed *silently*: the gate held every lead-to-lead send for ~60s and then failed
it as a stalled turn, and an empty `workers` array read as "no peers" to a lead
that had one. Signatures of both are recorded so a recurrence is recognisable.
Also corrected in place: the CB-530 gotcha still said to keep `primary:` beside
`leaders:`. CB-532 retired it, so the file contradicted itself two sections apart
— it now says delete it and points at the entry that explains why.
Chapter 11's lifecycle entry picks up `clearAfterTurn` (CB-537), which is in the
Lifecycle record as shipped. Note its design is already superseded: per-delivery
inherit|fresh|thread policy applied pre-delivery, because a post-turn reset races
by construction.
Chapter 7's copy of the portable CLAUDE.md block is re-synced byte-identically
(verified) with the lead-to-lead section: coordinate, never delegate sideways.
Use Cases: make the portable block's primary section an explicit flow
The primary's half of the charter was a bullet list of policies, which
left the order of operations implicit — the reader had to reconstruct
"spawn all, then send all" from a parallelisation bullet, and nothing
said when to review or when to stop. Restate it as a numbered 0-8
procedure so following it is checkable rather than a matter of recall.
Delegated review is now its own step, split from the merge it used to
sit beside: reviewers fan out over the diff (never the implementer of
the scope they review, briefed from the diff rather than the author's
rationale), while adjudication, the merge and teardown stay with the
primary. Merging on a reviewer's word is delegating the gate by proxy,
so the step says that outright.
The six trailing bullets are not dropped, only relocated into the step
that owns each: profile explicitness into spawn, playbook naming and
self-containment into send, claim verification into its own step, and
the ~60s blocking-send cap into a note under the steps.
Kept byte-identical with CLAUDE.md by splicing the block out of it, per
the sync check the repo documents.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017Kw1FosEt3Noix5GG9wJ2r
Use Cases: as-built CLAUDE.md bridge charter + bridge_whoami
Replace the design-era 'suggested CLAUDE.md snippet' (built on a
bridge_send(to:,kind:,body:) envelope that never shipped) with what is
actually in the tree:
- the four instruction layers and the rule that keeps them from drifting
(a rule lives in exactly one layer — the outermost that must obey it)
- the portable CLAUDE.md block, verbatim, as a copy-as-is template
- bridge_whoami: why guessing your own role failed silently, and the two
properties to preserve (same resolution as the authz gate; degrade
toward the useful answer)
Dai Ha
Dai Ha
kevin