docs(fleet): README for cmd/fleet

[itsHabib]

cmd/fleet was the only cmd/ directory in workbench without a README. This adds one: what the binary is, the four faces (hook, CLI, MCP, watcher), the store layout, install/shadow/switch, ownership rows, verb groups, testing, and what is deliberately not there. Docs only; facts checked against main.

🤖 Generated with Claude Code

[itsHabib]

@claude review

[claude]

Claude finished @itsHabib's task in 4m 6s —— View job

---

Review: docs(fleet): README for cmd/fleet

• Load tools
• Read cmd/fleet/README.md
• Read fleet source files to verify accuracy
• Post review findings

---

Overall the README is well-structured and the core material — the four rules, faces, store layout, install/shadow/switch, verb groups, model/ and testing sections, and "What is deliberately not here" — is accurate against the source. Three issues need attention, one of them significant.

---

P1 — "Task coordination" section documents unimplemented verbs

The section "Task coordination: first implementation increment" (lines 143–224) describes fleet request, fleet status, and MCP tools fleet_request / fleet_status in detail — but none of these verbs exist in the codebase on main. A grep across cmd/fleet/ finds zero dispatch cases, zero MCP registrations, and zero implementations. The verb list in the usage string does not include them. The PR description says "facts checked against main" — this section contradicts that claim.

The commit message explains it: fold #288's task-coordination section into the README. PR #288 described that functionality, but the implementation is not on main. Folding a PR description section into the README while the code hasn't shipped turns stable docs into a design note, with no label distinguishing what's real from what's aspirational.

Options (pick one):

• Remove the section and land it in docs/ as a design note, with a link from the README, once the implementation is on main.
• Add an explicit callout at the top of the section, e.g. > Not yet implemented. Tracked in #288.
• Wait to merge this PR until Fleet: retry-safe task requests and truthful status #288 has landed and these verbs are verifiable.

Additionally, two lines inside this section carry PR-specific / transient language that should never be in a stable README:

• Line 164: The installed Mac entrypoint during this build was /Users/mh/.fleet/bin/fleet — this is a personal home-directory path and a "during this build" reference. Both are transient.
• Line 188: This PR does not edit installed hooks. — "this PR" is pull-request language, not documentation.

Fix these →

---

P2 — handoff miscategorized as lookup

Line 114 puts handoff in the lookup group:

- **lookup** — `who`, `unowned`, `board`, `sessions`, `leases`, `costs`, `handoff`

handoff is dispatched from dispatchActs (verbs.go:352, case "handoff" at line 386), alongside receipt, take, drop, and role. The usage string describes it as "one-line handoff, replaced not appended; injected at the next SessionStart" — it's a write that changes per-branch store state. It belongs in control next to stop/resume/revoke, since (like those) it is keyed per-branch and scoped to the repo you are standing in.

---

P2 — Watcher described as "read-only" in the face table

Line 42 calls the watcher "read-only":

| watcher | `fleet watch` | one per machine, read-only: folds the store into … |

But the watcher writes board.json, board.md, work.json, observed.jsonl, heartbeat.json, and report.md (watch.go:13–17, watch.go:219–228). The store table below correctly shows watch/ as "written by" the watcher, creating a minor contradiction. The intent is "doesn't hold leases or make decisions" but the word "read-only" will mislead a reader who then sees the store table. A phrase like "claims no leases" or "owns no authoritative state" is more precise.

---

Verified accurate

The following were checked against source and are correct:

• Four rules — all four are correctly described
• Four faces and exit codes — hook 0/2, verb 0/1/2, fleet done adding exit 3 for a failing receipt (verified in receipts.go:495–528)
• Store layout table — all paths, writers, and meanings verified
• Install/shadow/switch commands — match install.sh flags and shadow infrastructure
• Verb groups — all verbs except request/status exist and are dispatched; group assignments are correct except handoff noted above
• fr1_test.go description — accurate; the regex and the gh-pr exemption match the source
• model/ description — accurate; three mutant files and judge.sh exist
• Testing commands — all four commands verified against the directory layout
• Layout section — all package paths exist and the descriptions match
• "What is deliberately not here" — four bullets; all accurate

[github-actions]

Reviewer: claude
Reviewed commit: 22e9c6d18e15f9c214e7ed558bbeaaa37a03ab15

[itsHabib]

@claude review at this head.

[claude]

Claude finished @itsHabib's task in 2m 46s —— View job

---

Review: docs(fleet): README for cmd/fleet (at HEAD ed913ff)

• Load tools
• Read cmd/fleet/README.md at current HEAD
• Read fleet source files to verify accuracy
• Post review findings

---

Reviewed commit: ed913ff ("docs(fleet): say what it is for — leads, seats, location as identity")

The latest commit adds a "What this is for" section and expands the rules from four to five by adding "Location is identity." Both additions are factually accurate against source. The previous review's three open issues remain unaddressed.

---

P1 — Task coordination section still documents unimplemented verbs

The "Task coordination: first implementation increment" section (lines 166–247) describes fleet request, fleet status, and MCP tools fleet_request/fleet_status. These are still absent from the codebase: no dispatch cases in verbs.go, no tool registrations in mcp.go, no work_assignment.go or equivalent file. The previous review at 22e9c6d raised this; the ed913ff commit did not touch the section.

The ownership verb group in the verb table (line 138) now annotates them with (see below):

- **ownership** — `dispatch`, `work`, `reassign`, `undispatch`, `sync`; `request` / `status` (see below)

That softens the issue slightly but doesn't resolve it — a reader scanning the verb list still sees request and status as if they're callable today.

Two lines in the section are transient and should not be in stable docs regardless of whether the section ships:

• Line 190: The installed Mac entrypoint during this build was /Users/mh/.fleet/bin/fleet; the new commands are not available there until a reviewed release is installed. — a personal home-directory path and "during this build" are ephemeral.
• Line 237: This PR does not edit installed hooks. — "this PR" is pull-request language, not documentation.

Pick one path before merging:

1. Remove the section; land it in docs/ as a design note, link from the README once the implementation ships.
2. Add a > **Not yet implemented. Tracked in #288.** callout at the top of the section and strip the two transient lines.
3. Hold the PR until Fleet: retry-safe task requests and truthful status #288 lands and the verbs are verifiable.

Fix these →

---

P2 — handoff still miscategorized as lookup

Line 140 lists handoff in lookup alongside who, unowned, board, sessions, leases, costs. But verbs.go:386 dispatches handoff from dispatchActs — the same function that handles receipt, take, drop, and role (all write operations). The function comment at verbs.go:352 even says so explicitly: "dispatchActs is what a session does by hand: receipts, resources, handoff, role binding." handoff writes a record to the store; it belongs with receipt, take, drop in a write or control group, not in lookup.

Fix this →

---

P2 — Watcher still described as "read-only"

Line 66 says the watcher is read-only: folds the store into …. The watcher writes board.json, board.md, work.json, observed.jsonl, heartbeat.json, and report.md (all confirmed via the store table at line 84, which correctly lists watch/ as "written by" the watcher). The intent is "claims no leases and makes no authorization decisions," not "reads no files" — but "read-only" will mislead anyone who then looks at the store table. Replace with a phrase like claims no leases or owns no authoritative state.

Fix this →

---

New content from ed913ff — verified accurate

The additions in the latest commit were checked against source:

• "What this is for" section — hub-and-spokes model, lead/worker accountability, fleet reassign --for for splitting a hub. All accurate; reassign --for is implemented at verbs.go:309-314.
• "Location is identity" rule — roles.map path-to-role resolution (longest-prefix wins) is implemented at fleet/lanes.go:141. Seat behavior including writeDenies projection into harness settings is implemented and tested in pool_identity_test.go:99-107. Accurate.
• Four rules → five rules — the rule count is now correct.
• Moved port/compat paragraph — structurally fine; it now follows the rules rather than preceding them.

---

Summary

Three issues from the first review remain open (P1 + two P2s); the latest commit introduces no new problems and its additions are accurate. The P1 (undocumented unimplemented verbs + two transient lines) needs resolution before merge; the two P2s can ship as a follow-up or be fixed in the same pass.

[itsHabib]

@claude review at this head: the task-coordination section is removed until #288 lands; only verbs on main remain.

[claude]

Claude finished @itsHabib's task in 1m 36s —— View job

---

Review: docs(fleet): README for cmd/fleet (at HEAD 25c8940)

• Load tools
• Read cmd/fleet/README.md at current HEAD
• Verify P1 resolved (task-coordination section removed)
• Check P2s from prior reviews
• Post review findings

---

Reviewed commit: 25c8940 ("docs(fleet): drop the task-coordination section until #288 is on main")

The P1 is resolved. The task-coordination section is gone entirely — no fleet request, fleet status, fleet_request, fleet_status, no personal paths, no "This PR" language anywhere in the file. That clears the only blocking finding.

The two P2s from prior rounds remain open.

---

P2 — handoff still miscategorized as lookup

Line 140 lists handoff in lookup alongside who, unowned, board, sessions, leases, costs. But verbs.go:386 dispatches handoff from dispatchActs, whose comment at line 352 says explicitly: "dispatchActs is what a session does by hand: receipts, resources, handoff, role binding." The per-branch state note at the top of the usage string (lines 45–46) further groups stop / resume / revoke / handoff together as operations keyed per-repo. handoff writes a record to the store; it belongs with the write-side verbs, not in a read group.

Fix this →

---

P2 — Watcher described as "read-only" in two places

Line 66 (face table):

| watcher | `fleet watch` | one per machine, read-only: folds the store into … |

Line 168 ("What is deliberately not here"):

The watcher is read-only; the hook is where facts are written; …

Both instances conflict with watch.go:13–17 (file-level comment) and watch.go:219–228 (the publish function), which show the watcher writing heartbeat.json, board.json, board.md, work.json, observed.jsonl, and report.md. The store table at line 84 even correctly lists watch/ as "written by" the watcher, making this a direct internal contradiction.

The intended meaning is "the watcher claims no leases and makes no authorization decisions" — not that it reads files without writing any. "Read-only" will mislead anyone who then looks at the store table. Replace both instances with a phrase like claims no leases or owns no authoritative state.

The previous review noted line 66 only; line 168 carries the same inaccuracy.

Fix this →

---

Summary

The P1 is cleanly resolved. The rest of the README — the five rules, four faces, store layout, install/shadow/switch, ownership rows, evidence/control/telemetry verb groups, testing section, model/ description, layout table, and "What is deliberately not here" — all check out against source. The two P2s are the only remaining issues; both are mechanical one-line fixes.

[itsHabib]

@claude review at this head: merged with main; #288 task-coordination section restored under its own heading now that request/status exist on main, transient lines removed.

[claude]

Claude finished @itsHabib's task in 3m 21s —— View job

---

Review: docs(fleet): README for cmd/fleet (at HEAD d93c3fb)

• Load tools
• Read cmd/fleet/README.md at current HEAD
• Verify fleet request / fleet status exist in codebase (post-Fleet: retry-safe task requests and truthful status #288 merge)
• Check transient lines removed
• Check P2: handoff categorization
• Check P2: watcher "read-only" description
• Review restored task-coordination section for accuracy
• Post review findings

---

Reviewed commit: d93c3fb ("docs(fleet): repair the sentence the transient-line drop cut")

All three issues from prior rounds are now addressed. One transient sentence survives.

---

P2 — "This PR" language still in the task-coordination section

Lines 236–237 (the closing sentence of the "Observe without claiming" paragraph):

need regeneration and harness reload when this release is installed. This PR
does not edit installed hooks. Terminal observations include the activity age.

The personal-path line (formerly "The installed Mac entrypoint during this build was /Users/mh/…") is gone — that's fixed. But "This PR does not edit installed hooks." is still there. "This PR" is pull-request language; once this merges, the sentence makes no grammatical sense. The intended claim — that install.sh does not touch already-installed hooks — is accurate (the install section above makes this clear). The simplest fix is to drop the sentence entirely; alternatively: "The installer does not edit hooks already installed on this machine."

Fix this →

---

Previous issues — all resolved

P1 (task-coordination section documents unimplemented verbs): Resolved. fleet request and fleet status exist in internal/verbs/request.go and internal/verbs/status.go; fleet_request and fleet_status are registered in internal/mcp/mcp.go:70-74. The #288 merge brought them in.

P2 (handoff miscategorized as lookup): Fixed at c054eeb. Line 135 now lists handoff in control alongside stop, resume, revoke --to, decide, undecide, decisions — correct per verbs.go:361-362 ("dispatchActs is what a session does by hand: receipts, resources, handoff, role binding").

P2 (watcher described as "read-only"): Fixed at c054eeb. The face table (line 66) now reads: "writes only under watch/ (never a lease, session or row)" — accurate. The "What is deliberately not here" section (line 251) now says "The watcher writes only its own board files" — also accurate. The internal contradiction with the store table is resolved.

---

Task-coordination section accuracy — verified

The restored section was checked against the implementation:

• fleet request / fleet status verbs — dispatched from verbs.go:128-131, implemented in request.go and status.go ✓
• fleet_request requires caller cwd — cwd is in the required array of the MCP schema (mcp.go:72) ✓
• Replay semantics (same ID + same payload → existing assignment, no new lease) — matches validateReplay and sameRequest in request.go:88-118 ✓
• Full-ID retries valid after branch deletion; prefix must resolve uniquely — matches request.go:86-87 comment ✓
• Second assignment for same branch refuses — matches createRequest at request.go:123-125 ✓
• Legacy dispatch/reassign/undispatch cannot overwrite request-bound rows — enforced in work.go:198-200, work.go:239-242, work.go:525-527 ✓
• fleet-task-status-v1 JSON schema — matches status.go:36 ✓
• last_writes keyed by branch, last_write for compatibility — matches status.go:57-59 and session.go:67-73 ✓
• Three status states (Queued / Activity observed / Status needs checking) — all match requestStatus in status.go ✓
• status bypasses migration and restores read-only mode — status.go:17-19 sets fleet.ReadOnly = true with defer; no MigrateLegacyKeys call ✓
• Terminal observations include the activity age — embedded via FmtAge in status.go:92 ✓
• No GitHub write or worker launch — matches CmdRequest function comment ✓

---

Summary

One mechanical P2 remains (the "This PR" sentence). The task-coordination section is accurate against the implementation, both former P2s are fixed, and the transient personal-path line is gone. One more pass or a note-to-judge on the remaining sentence, then this is clean.

[itsHabib]

@claude review at this head.

[claude]

Claude finished @itsHabib's task in 2m 27s —— View job

---

Review: docs(fleet): README for cmd/fleet (at HEAD d93c3fb)

• Load tools
• Read cmd/fleet/README.md at current HEAD
• Verify task-coordination section against source (request/status on main)
• Check P2s from prior reviews (handoff, watcher "read-only")
• Post review findings

---

Reviewed commit: d93c3fb ("docs(fleet): repair the sentence the transient-line drop cut")

The three issues from prior rounds — the P1 and both P2s — are resolved. One transient line was left behind.

---

Prior findings — status

P1 (task-coordination section) — ✅ Resolved. request and status verbs exist in verbs.go:128–131; fleet_request and fleet_status are registered and dispatched in mcp.go:70,73,267,269. The section is accurate against the implementation. Spot-checked:

• fleet-task-status-v1 schema name — matches status.go:36
• request_id + worker fields extend the dispatch row — matches status.go:53–54
• Queued / Activity observed / Status needs checking states — match status.go:54,63–72
• last_writes keyed by branch, last_write for compatibility — matches session.go:67–73
• Dispatch-store lock before branch lock — matches request.go:42 (KeyLock("dispatch")) and request.go:133
• status is read-only — matches status.go:10 package comment

P2 — handoff categorization — ✅ Resolved. Line 135 now has handoff in control: `stop`, `resume`, `revoke --to`, `decide`, `undecide`, `decisions`, `handoff`.

P2 — watcher "read-only" — ✅ Resolved. Line 66 now reads writes only under \watch/` (never a lease, session or row), which is precise. The "What is deliberately not here" section (line 250) also now reads The watcher writes only its own board files`, consistent with the store table.

---

Remaining issue

P2 — Transient "This PR" language on line 237

need regeneration and harness reload when this release is installed. This PR
does not edit installed hooks. Terminal observations include the activity age.

"This PR does not edit installed hooks." was flagged in both previous rounds and was listed as removed in the trigger comment, but it is still present. The personal path on the prior line was cleaned up; the PR-language sentence was not. Rewrite to be release-stable, e.g. Installing this release does not update running hooks.

Fix this →

---

Summary

Three findings from prior rounds (P1 + two P2s) are all resolved. The task-coordination section is accurate against the implemented source. One transient phrase remains: "This PR" on line 237. Everything else — the five rules, four faces, store layout, install/shadow/switch, ownership rows, all seven verb groups, testing commands, model/ and testdata/ descriptions, layout table, and "What is deliberately not here" — checks out.

[itsHabib]

@claude review at this head.

[claude]

Claude finished @itsHabib's task in 3m 45s —— View job

---

Review: docs(fleet): README for cmd/fleet (at HEAD 04a1f33)

• Load tools
• Read cmd/fleet/README.md at current HEAD
• Verify P2s from prior reviews (handoff categorization, watcher "read-only")
• Verify restored task-coordination section accuracy against source
• Post review findings

---

Reviewed commit: 04a1f33 ("docs(fleet): last pull-request phrasing out of the README")

All three findings from prior rounds are resolved. The task-coordination section is back and verified accurate against the implementation on main. The README is clean.

---

P1 — Resolved: task-coordination section verified accurate

fleet request and fleet status are implemented in verbs/verbs.go:128–132. fleet_request and fleet_status are registered in mcp/mcp.go:70–73 and dispatched at lines 267–270. All claims in the section check out:

• Retry-safe idempotency — request.go:56–57 checks same ID + same payload → replay; validateReplay at line 88 refuses payload changes. ✓
• Status names — "Queued", "Activity observed", "Status needs checking" match status.go:54, 63, 65, 67, 69, 72 and request_test.go:178–181. ✓
• fleet-task-status-v1 schema key — status.go:36. ✓
• request performs migration — request.go:44 calls fleet.MigrateLegacyKeys() before lease inspection. ✓
• status bypasses migration — verbs.go:128–129 dispatches before the MigrateLegacyKeys() call at line 140; mcp.go:311 exempts fleet_status from the MCP-side migration call. ✓
• status restores read-only mode via defer — status.go:17–19. ✓
• last_writes keyed by branch, last_write compat — status.go:57–59; writes on a second branch don't erase the first because session.go:67–73 merges under a per-key map. ✓
• Dispatch-store lock + branch lock sequence — request.go:42, 133. ✓
• No transient language — no "This PR", no personal home-directory paths anywhere in the file. ✓

The phrase "This increment does not edit installed hooks" (line 237) is doc-language scoped to the increment being described within the "first implementation increment" section — not pull-request language.

---

P2 — Resolved: handoff now in control group

Line 135: - **control** — \stop`, `resume`, `revoke --to`, `decide`, `undecide`, `decisions`, `handoff``

Matches verbs.go:352–386 (dispatchActs). ✓

---

P2 — Resolved: watcher no longer described as "read-only"

Line 66: one per machine; writes only under \watch/` (never a lease, session or row)` — accurate and no longer contradicts the store table.

Line 251: The watcher writes only its own board files — no "read-only" claim remains. ✓

---

Verified accurate (all prior sections re-checked at this head)

• Five rules — all accurate against source
• Four faces and exit codes — accurate
• Store layout — all paths and writers verified
• Install/shadow/switch — match install.sh flags
• Verb groups — all groups correct; handoff now correctly placed in control
• Evidence/control/telemetry sections — accurate
• fr1_test.go description — accurate
• model/ description — accurate
• Testing commands — all four verified
• Layout section — all package paths exist and descriptions match
• "What is deliberately not here" — four bullets, all accurate

---

Summary

All prior findings are addressed. The README is accurate against main, clean of transient language, and the task-coordination section matches the implementation that landed with #288. No blocking issues remain.