#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.
docs: record that v1.1.0 is tagged — release 1 is finished
The Roadmap said in two places that the tag was the only step left and that
it belonged to the operator. The operator authorised it and the lead cut it,
so both lines were about to become the wrong kind of stale: a checklist that
still asks for work that is already done.
Annotated tag on 7d41ccc, pushed. 217 commits since v1.0.0, not the 214 the
page still claimed - three doc commits landed after that count was written.
The build was re-run on the tagged commit rather than trusted from earlier in
the day: 870 tests, 0 failures. Gitea milestone 16 closed, 0 open PRs.
Also recorded that no Gitea release object was made. The tag is the artifact;
a release is a separate publish and was not asked for. Writing that down
stops a later session creating one and believing it was always expected.
Added the operator guide as item 8, since chapters 4 and 5 turned out never
to have been written and that was not on any checklist either.
CB-596 is an implementation unit, not one operator command
Running the probe is what showed it. Measured inside a live member: 31
credential names, all set. CB-592 works (the sentinel matched), but
GITLAB_PERSONAL_ACCESS_TOKEN — a second forge — has nothing blocking it,
alongside 23 other live secrets with no bridge purpose.
Also records why the probe's own hash column must not be published: a
truncated SHA-256 of a 5-character value is not an anonymiser.
Moves both into the Done table with what they actually were, turns their
diagram boxes green, and cuts the Open list to CB-596 alone — the one item
no session can close, because the probe it needs is refused by the command
classifier. Commit count 204 -> 211.
1.1 close-out: CB-582 and CB-604 land; three tickets left
Moves bridge_ask reach and catalogue debt into Done, folds CB-604 into config
accuracy, and adds CB-606 — the three fields with CB-604's shape, one of which
turns authentication off on a typo.
Also fixes a sentence the cut decision had made false: the milestone intro still
said only CB-308 goes to release 2. Four tickets went. The rule that decided it
is now stated — missing is not the same as broken.
Commit count since v1.0.0 corrected 196 -> 204.
Roadmap: 1.1 is mostly done — split the section into done and open
Six of the ten themes are merged and verified today: supervision,
durability, credential scope, nudge scheduling, config accuracy and the
green build. The section still described all of them as outstanding.
Four remain: bridge_ask reach (decided, in flight), the last five
Features areas, CB-596 which needs the operator, and the four
half-shipped tickets that are the deferral candidates.
Commit count since v1.0.0 corrected from 175 to 196.
CB-595: name the 1.1 close-out, and stop Stage 5 reading as "deployed"
The roadmap ended at Stage 5 and pointed straight at CB-308, so it never
answered the obvious question: what is actually left before the single-host
story is finished?
v1.0.0 was tagged on 2026-08-10 and 175 commits have landed since with no
tag. This adds the 1.1 milestone by theme — supervision, single-host bugs,
the durability claim, credential scope, catalogue debt — plus the admission
rule that decides what is 1.1 and what is release 2: if it would still be
broken with exactly one host, it is 1.1. By that rule only CB-308 is
release 2.
Also qualifies the Stage 5 "production shape" row. CB-504 did build a
launchd agent, but no host has ever loaded it, and launchd does not source
a login shell — so the unit as shipped would start a daemon with no forge
token and no gateway token. Read that row as built, not deployed. CB-594
is the gap.
wiki: add chapter 11 Features, and stop claiming Stage 5 is finished
Roadmap said Stage 5 was "✅ All landed" and listed CB-501–505. Twenty tickets
shipped after that line was written (CB-506…CB-525) and none of them appeared
anywhere in the wiki — so the page was not merely incomplete, it asserted
something false.
Two fixes, because there were two problems:
- The stage row is corrected and a "Stage 5 continued (as-built)" section records
all twenty, split by who needs them: capabilities, contract changes, and the
quality infrastructure that makes the rest trustworthy. It also carries the
CB-521 version-coupling warning — /healthz can be green while every spawn
fails, because health pings herdr without checking that the adapter and the
binary agree on a protocol.
- Chapter 11 is new, and it is the structural fix. Chapters 1–10 are organised by
design topic and every one answers "how is this built / why this way". None
answers "what can it do and how do I turn it on", so a shipped knob like
`placement: weighted` had no page that wanted it and landed nowhere. Eleven
entries, each: what it does · the knob · why it exists · the gotcha. The `why`
line is the load-bearing one — it is what stops a decision being re-litigated
a month later.
Written from verified behaviour only; six entries that still need their config
surface confirmed against the code are listed as an explicit backfill list rather
than guessed at.
Mermaid block rendered with mermaid-cli to confirm it parses.
Roadmap: CB-402 Stage B live-dogfooded — issue #7 closed
Spawn -> CB-306 readiness gate -> bridge_send -> structured bridge_reply ->
teardown, verified end to end against opencode 1.18.5. The schema-drift risk
did not materialise: the adapter was designed against 1.1.31 and its generated
OPENCODE_CONFIG still validates unchanged. Provider question resolved without
credentials — opencode's gateway serves free-tier models, so no key was needed
and no guard entry applies.
Roadmap: Stage 5 hardening as-built; Stage 3/4 status corrected
Stage 5 (CB-501..505) is complete and documented as-built, including the
finding that drove it: bridged had exactly one security control, the loopback
bind, and any caller that was not a recognised worker pane was treated as the
PRIMARY. CB-501 inverts that default (ANONYMOUS is the fallback) and refuses to
start on a non-loopback bind under loopback-trust.
Also records that CB-505 must enforce on BOTH entry paths: BridgeMcp calls the
service layer directly and /mcp is a raw servlet that never traverses Javalin's
before filter, so the wiki's long-standing "MCP is a thin adapter over the REST
core" is not literally true at code level.
Corrections to stale rows:
- Stage 4: CB-402 landed (ded226a), was still listed as future. Flagged as
code-complete but NOT live-dogfooded — the one known-unverified item.
- Stage 3: CB-301-ext / CB-302 / CB-304 marked shipped; CB-302's "STATE.md"
framing superseded by the worker-opened-PR checkpoint that actually shipped.
- Test count 147 -> 307, and clarified that figure excludes contract tests.
Fold the now-shipped CB-307 into the as-built docs (was stale at Stage 1 only):
- Roadmap: Stage 2 (AmqpReplyInbox/LavinMQ, 2bc5f3a) and Stage 3 (ReplyPushLoop
active push-to-primary, d4c9704, gitea #5 closed) marked shipped; diagram gains
a Stage 3 node; all stages green.
- Implementation: msg core 4->6 classes (AmqpReplyInbox consume-and-hold, ReplyPushLoop
status-gated loop); mcp 6->7 (PrimaryRegistry); bridge_ack tool; stranded-reply
narrative extended with durable landing + active nudge + pull degradation.
- Architecture: late-replies note now covers durable + active push; split-host hook
note clarifies a same-host primary IS injected into (Stage-3 nudge).
Push channel resolved: the same-host primary is a herdr pane, so the loop injects a
bounded, status-gated drain nudge into its own pane; off-host degrades to pull.
Mermaid roadmap diagram re-validated (renders clean).
Record the rich-message-semantics stage as done: CB-205 reverse rendezvous
(bridge_ask, live e2e), CB-202 reviewer-role skill, and CB-201 intentionally
descoped from a {from,to,corr} envelope to a lightweight QUESTION kind + turn_id
(connection identity already routes replies). CB-203/CB-204 shipped earlier.
Bump suite to 147 green (+13). Resolve the reviewer-skill open decision (skill,
not CLAUDE.md snippet) and move bridge_ask out of Stage 3's delivers line.
roadmap: Stage 1 COMPLETE — real build status (111 tests, CB-101..108 done + dogfooded)
The Stage-1 build-status snapshot was badly stale (34 tests; CB-103/104/105/107
marked undone). Reality: all Stage-1 tickets are done, the CB-107 e2e demo gate
passes, and the bridge is dogfooded. Correct the count to 111 (105 unit/acceptance
+ 6 live-herdr contract), mark every Stage-1 ticket done, and add a 'Beyond Stage 1'
note for the shipped delivery-reliability hardening — flagging that git's CB-106..114
numbering reuses this plan's CB-106/107/108 slots (config/e2e/placement).
Dai Ha
kevin