From b66f0677ed127caa3bdddf64803cd9861ed70493 Mon Sep 17 00:00:00 2001 From: Dai Ha Date: Mon, 31 Aug 2026 09:14:22 +0700 Subject: [PATCH] #168: audit current wiki snapshot --- docs/wiki-audit.md | 201 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 docs/wiki-audit.md diff --git a/docs/wiki-audit.md b/docs/wiki-audit.md new file mode 100644 index 0000000..7789626 --- /dev/null +++ b/docs/wiki-audit.md @@ -0,0 +1,201 @@ +# Wiki audit for #168 + +**Source checked:** `.wiki-snapshot/` at `68e32c6` (2026-08-31). I did not use +`wiki/`. Code references below are from the current `fleetd` source tree. A quoted +line is a concrete claim that needs correction, unless the table says `KEEP`. + +| Page | Verdict | One-line reason | +|---|---|---| +| `Home.md` | REVISE | Good overview, but it still names the retired product. | +| `_Sidebar.md` | REVISE | The heading still says `claude-bridge`. | +| `1-Architecture.md` | REBUILD | Its component contract mixes current names with removed tools, routes, and planned backends. | +| `2-Message-Server.md` | REBUILD | The claimed MCP schema, mount command, REST/SSE surface, and fallback paths are pre-build design. | +| `3-Approaches.md` | REVISE | Useful research history, but it presents unbuilt AgentAPI as a selectable fallback. | +| `4-Setup.md` | RETIRE | It is an intentional stub that only redirects to chapter 13. | +| `5-Operations.md` | RETIRE | It is an intentional stub that only redirects to chapter 13. | +| `6-Team.md` | REBUILD | It teaches role-addressed sends and a Claude-only team model that the shipped API does not have. | +| `7-Use-Cases.md` | REBUILD | Its flagship flow depends on removed `ccs` profiles and removed send parameters. | +| `8-Roadmap.md` | REBUILD | It is a historical plan, but it presents old implementation choices and planned work as the current stack. | +| `9-Implementation.md` | REBUILD | Its package, class, endpoint, and outcome map has drifted from the source. | +| `10-Cross-Host-Messaging.md` | REVISE | It labels most federation work proposed, but misses the shipped `coordinator:` lead channel. | +| `11-Features.md` | REVISE | It is the right catalogue, but code-path names are old and it misses the second-herdr-daemon capability. | +| `12-Claude-to-OpenCode.md` | REVISE | The porting guide is mostly current, but calls the product and spawned-member path a bridge. | +| `13-User-Guide.md` | REVISE | It is the best operator page, but needs the product rename and the second-herdr-daemon setup. | + +## Pages needing work + +### `Home.md` โ€” REVISE + +- Quote: `# claude-bridge` (line 1) and `` `claude-bridge` keeps`` (line 11). + The product is `fleet` / `fleetd`. The MCP server identifies itself as `fleet` in + `fleetd/src/main/java/dev/ltms/fleet/mcp/FleetMcp.java:313-315`. +- Quote: `AgentAPI ... swappable fallback injector` (lines 73-76). + There is no AgentAPI implementation under `fleetd/src/main/java`; the actual + launchers are selected by `Profile.kind` in + `fleetd/src/main/java/dev/ltms/fleet/config/FleetConfig.java:265-270`. + +### `_Sidebar.md` โ€” REVISE + +- Quote: `### ๐Ÿ“– claude-bridge` (line 1). + Rename it to `fleet`. `FleetMcp` registers the current product-facing tool set at + `fleetd/src/main/java/dev/ltms/fleet/mcp/FleetMcp.java:301-326`. + +### `1-Architecture.md` โ€” REBUILD + +- Quote: `` `claude-bridge` lets`` (line 3). The product was renamed; the MCP + server name is `fleet` (`FleetMcp.java:313-315`). +- Quote: ``fleet_read`` in the tool list (line 102). No such tool is registered. + The complete registered list is `fleet_send` through `fleet_whoami` at + `FleetMcp.java:301-326`; `fleet_read` is absent. +- Quote: `SSE (GET /events)` (line 143). `FleetApp.build()` registers no `/events` + route; its routes are listed at `FleetApp.java:143-159`. +- Quote: `Redis Streams / NATS JetStream, or an embedded queue` (line 106). + The shipped durable inbox is AMQP, configured by `broker`, at + `FleetConfig.java:49-50` and `FleetConfig.java:655-714`. +- Quote: `AgentAPI (fallback)` (line 107). No AgentAPI adapter exists; shipped + launcher kinds are `claude-code` and `opencode` (`FleetConfig.java:265-270`). + +### `2-Message-Server.md` โ€” REBUILD + +- Quote: `claude mcp add --transport http bridge http://127.0.0.1:8080/mcp` + (line 67). The daemon defaults to port `8765` in `FleetConfig.java:183-187`, + and identifies its server as `fleet` at `FleetMcp.java:313-315`. +- Quote: ``fleet_send(message, target?, {block, timeout_seconds, auto_spawn, + turn_id})`` (line 80). The real parameters are `sessionId`, `content`, + `timeoutMs`, `wait`, `turnId`, and `coordId` (`FleetMcp.java:1096-1108`). +- Quote: ``fleet_read(target, source)`` (line 85). It is not registered; see the + complete registration at `FleetMcp.java:301-326`. +- Quote: `docs/MCP-Contract.md ... normative` (lines 87-88). That is not a valid + reference: only ยง6 is current, as the current operator guide itself says at + `.wiki-snapshot/13-User-Guide.md:466`. +- Quote: `SSE (GET /events)` (line 45). No route exists in the built REST surface, + `FleetApp.java:143-159`. + +### `3-Approaches.md` โ€” REVISE + +- Quote: `AgentAPI ... remains a swappable fallback injector` (lines 78-84). + It was never built. The shipped adapter selection is only `claude-code` or + `opencode` (`FleetConfig.java:265-270`). Keep it as discarded research, not an + operational fallback. +- Quote: `claude-bridge` (line 109). Rename the product to `fleet`; the runtime + package is `dev.ltms.fleet`, for example `FleetMcp.java:1`. + +### `4-Setup.md` โ€” RETIRE + +It is a 25-line redirect and says its procedure was never written (lines 3-9). +Chapter 13 is the maintained install procedure. Keeping a second navigation page +adds no working documentation. + +### `5-Operations.md` โ€” RETIRE + +It is a 35-line redirect and says its runbook was never written (lines 3-14). +Chapter 13 now owns run and recovery instructions. + +### `6-Team.md` โ€” REBUILD + +- Quote: `fleet_send {role: w-claude, prompt: A}` (line 98). `fleet_send` accepts + `sessionId` and `content`, not `role` or `prompt` (`FleetMcp.java:1096-1108`). +- Quote: `some on Claude, some on the remote local LLM` (lines 3-5) and `Every + worker is ... Claude Code` (line 25). `opencode` is a first-class launcher kind, + not a Claude worker (`FleetConfig.java:265-270`). +- Quote: `fleetd's concurrency policy` (line 121). The configured capacity control + is per-profile `maxLoad` (`FleetConfig.java:251-264`), not the role routing model + described here. + +### `7-Use-Cases.md` โ€” REBUILD + +- Quote: `ccs profile` (line 10), `ccs + herdr` (line 22), and `ccs-spawn` + (line 45). The configuration has `profiles` and `fleet`, not `ccs`: + `FleetConfig.java:34-58` and `FleetConfig.java:81-101`. +- Quote: `fleet_send({"to", "kind", "body", "block"})` (lines 55-62). + None of those are the shipped send parameters. The schema is + `FleetMcp.java:1096-1108`. +- Quote: `fleet_list() โ†’ { "profiles": ... }` (lines 74-80). `fleet_list` is a + roster view; `fleet_profiles` is the configured-backend view, as registered at + `FleetMcp.java:307-311` and described at `FleetMcp.java:1176-1182`. + +### `8-Roadmap.md` โ€” REBUILD + +- Quote: `Java 21+` (line 43). The current project guidance and source use Java 25; + the `FleetConfig` source itself uses Java 25 unnamed lambda parameters, for + example `FleetConfig.java:102`. +- Quote: `herdr 0.7.0 / protocol 14` (line 46). The current REST health endpoint + reports the live protocol returned by herdr (`FleetApp.java:240-244`), while the + current operator guide records protocol 19 at + `.wiki-snapshot/13-User-Guide.md:76-85`. +- Quote: `ccs claude` and `ccs env ` (lines 47-48). Shipped + configuration uses `Profile` records and launcher `kind`, + `FleetConfig.java:313-330` and `FleetConfig.java:265-270`. +- Quote: `Redis Streams via Lettuce` (line 50). The actual durable inbox is AMQP + `broker`, `FleetConfig.java:655-714`. + +### `9-Implementation.md` โ€” REBUILD + +- Quote: `rest.FleetdApp` and `mcp.BridgeMcp` (lines 29-30). The classes are + `rest.FleetApp` and `mcp.FleetMcp` (`FleetApp.java:46`; `FleetMcp.java:67`). +- Quote: `dev.ltms.fleetd` (line 67). The source package is `dev.ltms.fleet` + (`FleetMcp.java:1`). +- Quote: `WorkerPresence` (line 110). The current class is `MemberPresence`, as + imported and used by `FleetMcp` at `FleetMcp.java:12` and `465-469`. +- Quote: the outcome list ending in `STALE_TURN` (lines 128-131). The code also + has `BACKEND_EXHAUSTED` (`FleetMcp.java:550-554`) and async `ASKING` handling + (`FleetMcp.java:664-668`). +- Quote: `FleetdApp` (line 207) and `FleetdConfig` (line 211). These names do not + resolve; current classes are `FleetApp` and `FleetConfig`. + +### `10-Cross-Host-Messaging.md` โ€” REVISE + +- Quote: the chapter says the cross-host fabric is proposed except for the + single-host inbox (lines 3-8). Cross-host **lead-to-lead** delivery shipped: + `fleet_send` accepts `coordId` (`FleetMcp.java:1094-1107`) and publishes it at + `FleetMcp.java:616-641`; configuration has `coordinator` at + `FleetConfig.java:74-78` and `99-101`. +- Quote: `bridge.dlx` (line 90). This product name is stale. The shipped lead path + uses `LeadChannel`, not the proposed exchange flow (`FleetMcp.java:95-96` and + `616-641`). Keep the proposed federation design, but add a clear shipped/proposed + boundary for CB-637. + +### `11-Features.md` โ€” REVISE + +- Quote: `mcp/BridgeMcp` (line 22), `config/FleetdConfig` (lines 25-27), and other + index references. These paths no longer resolve; the source classes are + `mcp/FleetMcp` (`FleetMcp.java:67`) and `config/FleetConfig` + (`FleetConfig.java:81`). +- Quote: `fleet_whoami` returns only `primary` or `worker` (lines 99-100). + It also returns `architect` (`FleetMcp.java:1235-1244`). +- The page needs the missing separate member-herdr-daemon feature listed below. + +### `12-Claude-to-OpenCode.md` โ€” REVISE + +- Quote: `same bridge mount` (line 5) and `a bridge-spawned worker` (line 94). + Rename the product path to `fleet`. The daemon exposes the MCP server as `fleet` + (`FleetMcp.java:313-315`), and profiles select OpenCode with `kind: opencode` + (`FleetConfig.java:332-335`). +- Quote: the sample mount name is `fleetd` (line 67). The server name is `fleet`; + update the sample to avoid teaching a second product name. + +### `13-User-Guide.md` โ€” REVISE + +- Quote: `The bridge is the only channel` (line 63). The invariant is correct, but + the product term needs the `fleet` rename. The daemon's MCP server name is + `fleet` (`FleetMcp.java:313-315`). +- Quote: it describes one herdr socket (lines 72-85). It needs the optional + `memberHerdrSocket` setup and two-daemon health meaning. The config key is in + `FleetConfig.java:34-37`, and `/healthz` checks both daemons when configured at + `FleetApp.java:210-245`. + +## MISSING + +`11-Features.md` has no entry for **routing members through a separate herdr daemon** +(#185). Operators can set `memberHerdrSocket`; member spawn and member status use that +daemon, and `/healthz` becomes degraded if either the lead or member daemon is down. +Evidence: `FleetConfig.java:34-37` and `FleetApp.java:103-115`, `210-245`, and +`247-263`. Add one chapter-11 entry with the knob, why, and the two-daemon health gotcha. + +## Audit method and coverage + +I checked all 15 pages. I checked concrete tool, route, config, class, file, and +product-name claims claim-by-claim on 11 pages: Home, Sidebar, 1, 2, 4, 5, 6, 7, 9, +11, and 13. I skimmed the remaining four long historical or research pages (3, 8, 10, +12), then checked their concrete claims that affect the verdict. This is an audit of +the supplied snapshot, not a wiki rewrite.