docs: make Fleet a focused chapter in the Workbench teaching path

[itsHabib]

Fleet 101 previously asked newcomers to read a 1,331-line runtime investigation before using Fleet. This follow-up makes Workbench 101 the entry page and reading map, with a focused Fleet chapter that follows one assignment through a question, handoff and exact-head evidence. The detailed material from #329 remains available as a dated runtime/model reference.

The reader follows Workbench → Fleet 101 → installation/run guide. Linked onboarding, overview and README text now use optional roles and direct peer questions, distinguish receipts from observed activity, and state the actual hook-admission boundary. A real CLI walkthrough exposed the missing requirement to create/fetch a branch before dispatch; both command paths now include it.

This is the operator-requested teaching follow-up to #329, reconciling both independent SIMPLIFY reviews. It supersedes the proposed first-reader structure there; #329 remains open and held. Its exhausted three-cycle panel is not restarted or bypassed by another bot request. Runtime repairs stay with their existing owner.

Validation: Fleet/Org tests and both Claude/Codex adapter suites passed; the full example passed against a fresh binary in disposable state with synthetic hook events. That walkthrough is CLI evidence, not a learner trial or real provider workflow. The separately observed live Codex holder/contender apply_patch result is documented narrowly. See cmd/fleet/docs/fleet-teaching-validation.md for review dispositions, evidence boundaries and residuals. Independent final review passed exact head 4350bbedf13f2b383c651c9949359a1cb50f4d78 with no remaining actionable documentation findings: #335 (comment). The first review caught a receipt-kind mismatch; the corrected walkthrough now asserts that the actual assigned work row reaches done.

HOLD: operator read required. No Gate call, merge, deployment or live installation authorized by this PR. Known starting-state recovery, arbitrary shell-write coverage, surviving effects and Windows qualification are not represented as solved by documentation.

[itsHabib]

Independent final review of 4350bbe: PASS for documentation.

Published by the implementing owner from the separate teaching_final_review verifier's returned verdict. The verifier used its own clean detached checkout and confirmed this was PR #335's current head.

The reading structure works: Workbench 101 supplies purpose and navigation; Fleet 101 follows a focused task → question → handoff → verification path. Org and additional hierarchy remain optional. The long runtime reference is clearly historical.

The initial P2 is resolved: dispatch, receipt and completion query now consistently use implementation. The corrected raw walkthrough shows the actual work row becoming done; the earlier mismatch is preserved. Historical status labels and authored-versus-observed wording are also corrected.

Independent checks: all 102 relative links/anchors resolve; git diff --check passes; focused receipt/work/dispatch/handoff/mail Go tests pass. The verifier read both review dispositions, failed/corrected walkthrough evidence and the final correction diff. Runtime source did not change between reviewed documentation commits. No remaining actionable documentation findings.

Owner validation additionally passed go test ./cmd/fleet/... ./cmd/org/... and both Claude/Codex adapter suites. The example uses real CLI commands and disposable state with synthetic hook events. It establishes command/state behavior, not learner success or live provider reliability. Separately observed provider evidence remains bounded; Windows qualification, surviving-child containment and comparative usefulness remain unproven.

Operator-read and no-merge hold remain. This is review evidence, not merge authority. No fourth panel round on #329 was requested.

[itsHabib]

Status update, 2026-09-14: #334 merged at 00:21:18 UTC as 92a706a7982a527ade967e43b68afd4bc1e5d667, from reviewed head d9ca988176bd47beb6afc33a70b31092b4302e0e. GitHub merge status verified. The runtime owner reports it is not installed or deployed; live runtime evidence still refers to installed 10b066c. The guide explicitly dates that behavior, so no teaching edit is needed. The repair prevents new constructor failures from stranding starting; it does not recover already ambiguous records or establish descendant quiescence.

---

Historical pre-merge status follows:

Runtime follow-up: #334 at d9ca988176bd47beb6afc33a70b31092b4302e0e repairs known provider-command construction failures before publishing starting. It is independently reviewed and CI-green, but open/unmerged and not installed. The installed source remains 10b066cac0bb959ca3dfa7dc2d77886eed277e78, which is the explicitly dated runtime described by this teaching change.

That repair preserves prior launch/resume evidence and allows mail retry after a constructor failure. It does not recover an already ambiguous starting record or establish descendant quiescence. See its exact-head consolidation. The guide's current-vs-historical distinction remains accurate; no runtime fix is hidden inside this documentation PR.

[itsHabib]

Ready for operator reading at 4350bbe. All five exact-head CI checks passed: check, hygiene, fuzz, macOS seats and Windows seats. Independent final documentation review passed, as posted above. Local Fleet/Org tests, both adapter suites and the corrected CLI walkthrough also passed.

The reader path and reference are inspectable in this PR. No newcomer learning trial is claimed, and platform test jobs are not live Windows-provider acceptance. Runtime #334 remains a separate proposed repair. Operator-read/no-merge hold remains; marking ready changes review readiness only.

[itsHabib]

Merge-preparation refresh, 2026-09-13, exact 4350bbe.

• Head unchanged; all five CI checks pass; no inline review threads or new actionable comments. Existing independent final review and retained corrected CLI transcript still apply. The transcript shows done fix/timeout-units/implementation, not merely a passing receipt query. No unchanged-code review was repeated.
• Runtime fix(fleet): keep provider preparation failures retryable #334 is independent and compatible in either order. This guide explicitly describes source/installed 10b066c; its proposed repair is crosslinked separately. No runtime edit, installation or deployment is required for this documentation PR.
• docs: make Fleet a focused chapter in the Workbench teaching path #335 is the sole teaching implementation to land. docs(fleet): Fleet 101, a teaching guide to Fleet and its formal models #329's body now explicitly marks it superseded by docs: make Fleet a focused chapter in the Workbench teaching path #335: keep it open for review history, never merge both, and close it as superseded only after docs: make Fleet a focused chapter in the Workbench teaching path #335 lands. No PR was closed.
• Risk floor: T0, eleven Markdown files only. No runtime, hook configuration, review policy or authorization code changes. Assessed tier remains T0.

Read the exact guide here: Fleet 101, starting from Workbench 101 if desired.

Remaining authority/review requirements:

1. Operator read-through hold: the batch merge instruction explicitly preserves it. Release this hold after reading the guide; general batch merge intent does not release it.
2. Required Claude slot: default-branch .ship.json has review.require: ["claude"]. This PR has the posted independent local review, but no Claude completion. There is no policy-declared local substitution. Obtain a real Claude review under an authorized existing budget, or explicitly authorize accepting the posted independent exact-head review instead for docs: make Fleet a focused chapter in the Workbench teaching path #335. No review evidence is waived or fabricated, and no paid review was launched in this preparation.
3. Grant: gate next -json -state ~/dev/gate/state reports the latest Workbench grant expired at 2026-09-13T01:03:41Z. No suitable live grant was found. Operator-only scoped request:

gate grant -repo itsHabib/workbench -action merge -max-tier T0 -ttl 24h -state ~/dev/gate/state

The grant covers the repository/action/tier; this task would use it only for #335. After the hold and review requirement are resolved, refresh the exact head, run Gate with the supplied grant and use only Gate's emitted head-pinned merge command. No Gate evaluation, grant mint, merge, installation or deployment was performed during this preparation.

[itsHabib]

@claude review

Please review exact head 4350bbe for the required Claude slot. Focus on the changed teaching path and command semantics, factual safety boundaries, and reconciliation recorded in cmd/fleet/docs/fleet-teaching-validation.md. A separate independent reviewer already caught and verified the receipt-kind fix; both adapters and CI passed. Do not repeat a broad unchanged-runtime audit. Preserve the operator read-through/no-merge hold. This ordinary configured review is authorized by the batch coordinator; no purchase or capacity increase is authorized.

[claude]

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

---

Claude Review — PR #335 docs/fleet-teaching-path

Reviewed exact head 4350bbedf13f2b383c651c9949359a1cb50f4d78. All eleven changed files are Markdown only; no runtime or authorization code was changed.

Todo:

• Load tools
• Read teaching path core files (fleet-101.md, workbench-101.md)
• Read reference and validation files (fleet-reference.md, fleet-teaching-validation.md)
• Read modified peripheral docs (README.md, ONBOARDING.md, OVERVIEW.md, MINIMUM.md, run-a-fleet.md, e2e.md)
• Analyze command semantics and factual safety boundaries
• Post review findings

---

Teaching path structure

The structural change is sound. The reader progression is now:

docs/README.md  →  workbench-101.md  →  fleet-101.md  →  install.md  →  run-a-fleet.md

workbench-101.md gains a "Start here: choose a chapter" navigation table and a "Who owns what" section up front. A newcomer following the Fleet path can stop after fleet-101.md and the install/run guides without reading the full architecture reference. The 1,331-line historical content survives as fleet-reference.md with clear historical labeling. The restructuring works.

fleet-101.md opens with a navigation table of its own, which correctly separates the focused task path from the runtime-investigation path. The introduction of roles, seats, work rows, handoffs, mail, and receipts before the example — each defined briefly and with correct semantics — is an improvement over the former buried-in-narrative approach.

---

Command semantics

All commands in fleet-101.md were verified against the source map at the bottom of the file and the run-a-fleet.md update.

Branch prerequisite (lines 65–71): The dispatch sequence now requires creating the branch first:

git branch fix/timeout-units main
fleet dispatch fix/timeout-units --as implementation --for supervisor:demo \
  --slot example-author-1 --brief '...'

The prerequisite was discovered during CLI testing (documented in fleet-teaching-validation.md). run-a-fleet.md gains the same git branch <branch> main step with a note to skip it if the branch already exists. Both paths are consistent.

Receipt-kind consistency (lines 130–135): The example uses --as implementation at dispatch and implementation at both fleet receipt and fleet done. The guide explains why they must match: "A verify receipt would be a different kind and would not complete this row. The kind names the evidence, not who is allowed to record it." This correctly resolves the P2 caught by the first independent review. ✓

Mail flow (lines 81–101): Worker sends with --kind question; lead reads with fleet mail --unacked, replies with --kind answer to the seat address, then acks with fleet ack QUESTION_ID. The note "In real work reply to the message's from_address (or the assignment's reply_to), rather than guessing an address from a role name" appears after the example uses the placeholder address. The guide clearly marks example-author-1 as a placeholder ("substitute the names printed by your own setup"), so the ordering is acceptable for a teaching document, though a reader might benefit from the note appearing before rather than after the example command.

Handoff (lines 112–122): Branch handoff invocation is correct. The note that handoff has no read mode — use fleet inspect <address> — is useful and accurate.

Diagnostic commands (lines 142–155): fleet work, fleet board, fleet watch status, fleet inspect <address> are all standard CLI verbs. The state descriptions (unoccupied, late, dead) correctly match the state semantics in README.md. ✓

The --kind match rule (line 129): Explaining that the kind is set at dispatch time and must be matched by the receipt is the core semantic newcomers need. Stated clearly and backed by the corrected walkthrough in the validation doc.

---

Factual safety boundaries

All changed files now consistently state the admission boundary, replacing previous overclaims.

fleet-101.md "What the protection means" (lines 172–184): The statement is accurate and consistent with the source:

Fleet gates recognized tool admissions. It does not lock the filesystem. … Ordinary shell writes such as printf x > file.txt, scripts and generators can run without that branch-lease check. Tools outside the hook matcher bypass it entirely. A lease also does not stop a child process that was already running.

MINIMUM.md changes "Fleet's hook enforces the first (one writer per branch)" → "Fleet's hook checks recognized admissions to a leased branch; ordinary shell writes and already-running children are outside that guarantee". Linked to fleet-101.md#what-the-protection-means. ✓

OVERVIEW.md adds: "Fleet checks recognized admissions, not all writes. Ordinary shell scripts and redirections can miss branch-lease checks; leases do not contain existing child processes." ✓

OVERVIEW.md shape diagram: The prescriptive multi-lead ASCII hierarchy is replaced with the minimal operator → accountable lead ↔ worker ↔ verifier. The old diagram implied a mandatory tree; the new version correctly marks hierarchy as optional. ✓

ONBOARDING.md section 2 replaces the prescriptive "One overall lead. One lead per bucket of work…" with "Start with one accountable lead and one task owner." The mandatory-hierarchy implication is removed. ✓

starting stranding defect (fleet-101.md line 157–162): Named precisely:

Do not erase a launch record to make an address appear free. At the source revision checked for this guide (10b066cac0bb959ca3dfa7dc2d77886eed277e78, 2026-09-13), provider-command construction can fail after publishing starting, stranding the address before spawn. This remains a runtime defect for the reliability owner.

The repair PR (#334) is crosslinked in the PR comments but not embedded in the guide, which is correct — this is a documentation PR and the defect remains open.

Codex live observation (fleet-101.md lines 202–207): The scope statement is tight:

This demonstrates that specific live admission path, not generic shell-write protection or surviving-child containment.

The validation doc adds: "a Bash sleep also emitted Pre/Post events, which proves shell hook events, not shell-write protection." The distinction is maintained throughout. ✓

fleet-reference.md header: The "Changes since this snapshot" section correctly flags all four differences from the historical content: the #330 stdin-transport fix, the starting stranding defect, Issue #324 Windows scope, and the hook trust vs write-protection boundary. The historical labels (verified, live, intent) are correctly scoped to the snapshot revision, not the current installation. ✓

---

Reconciliation with fleet-teaching-validation.md

The validation doc entries match the changes in the guide:

Concern from prior reviews	Disposition in this PR
Long compulsory first read	New fleet-101.md; old content is optional reference
Default hierarchy in README/onboarding	Corrected in ONBOARDING.md §2 and OVERVIEW.md
Ownership wording omits shell writes	Corrected in MINIMUM.md, OVERVIEW.md, fleet-101.md
Receipts confused with observed truth	receipt/handoff distinction introduced early in fleet-101.md
Missing branch before dispatch	Branch creation step added in fleet-101.md and run-a-fleet.md
Receipt-kind mismatch (P2)	Corrected: implementation throughout
Org parent confused with lateness recipient	Explained correctly in fleet-101.md lines 105–108
Blanket no-Codex claim	Replaced with scoped provider evidence link

All dispositions are represented accurately in the code. The validation doc's "residuals and stop boundary" section correctly identifies what remains unproven and makes no overclaims. ✓

---

Minor observations (non-blocking)

1. fleet-101.md line 99 (address guidance ordering): The guidance to use from_address rather than a role-name guess appears after the example command that uses a placeholder seat address. For a teaching document the ordering is reasonable (learn from example, then see the real-world note), but a reader copy-pasting the command may not read the following paragraph. Not a defect given the explicit placeholder framing.

2. fleet-101.md "Source and evidence map" (lines 209–216): The inline source links are relative paths within the checkout and will naturally drift as code evolves. Since the document explicitly pins its checked revision, this is acceptable — the map is a dated audit tool, not a live reference.

3. workbench-101.md line 58 (status marker date): verified claims are dated 2026-09-11 in the Orientation block. This document has a long existing tail; the new front-matter sections (navigation table, "Who owns what") don't carry their own date. This is consistent with how the rest of workbench-101.md works and is not a new issue introduced here.

---

Summary

Teaching path: Works. Navigation structure is clear, reading order is unambiguous, and the newcomer can complete the Fleet path without touching the architecture reference.

Command semantics: All commands are syntactically and semantically correct. The branch-prerequisite fix and the receipt-kind consistency fix are both properly implemented.

Factual safety boundaries: Consistently and accurately stated across all eleven changed files. No remaining overclaims on hook coverage, shell write protection, or provider qualification.

Validation record: Honest. The validation doc names what was tested, what it proves, and what it does not prove.

Operator read-through and no-merge hold remain in force. This review satisfies the configured Claude slot requirement at the reviewed head. No merge authority is conferred; that remains with Gate under a live operator grant after the operator reads the guide.

[itsHabib]

Required review completed at 4350bbe: Claude review, successful configured workflow. This is actual provider review evidence, not a substituted local review or a waiver. It joins the earlier independent exact-head review and passing CI/CLI validation.

Consolidation: no actionable defects. Claude's three nonblocking observations are accepted without another edit: the mail example already labels its concrete names as placeholders and instructs real replies to use from_address; source links intentionally follow the checkout while the checked revision is pinned; the older Workbench architecture tail retains its dated qualification beneath an explicit historical-evidence heading. Nothing worth cutting or adding is established by those observations.

The configured review ran under existing account/settings after the coordinator clarified ordinary review requests were authorized. No purchase or limit increase occurred. The earlier missing-review prerequisite is resolved; no head change or repeated broad review is needed.

Remaining: release the explicit operator read-through hold after reading Fleet 101 at this head, and supply an operator-minted live Gate grant. The T0 scoped mint request is in the merge-preparation comment. Gate itself has not evaluated this head, so this consolidation is evidence, not a Gate pass or merge authority. #335 is the sole teaching change to land; #329 stays open as superseded review history until #335 lands.

[itsHabib]

Grant-inventory refresh supersedes the earlier expired-grant blocker and mint request.

Supported discovery was rerun with gate preflight -repo itsHabib/workbench -json -state ~/dev/gate/state and gate next -json -state ~/dev/gate/state. Current inventory includes:

• grt_2fe70e45b5512981: repository itsHabib/workbench, action merge, ceiling T0, expires 2026-09-14T20:34:02Z, not expired, three cycles.
• grt_efbb165e61a4b277: same repository/action, ceiling T1, expires 2026-09-14T20:29:26Z, not expired, three cycles.

#335 remains at 4350bbedf13f2b383c651c9949359a1cb50f4d78, assessed T0 for eleven Markdown files. Preflight reports zero cycles used for this PR. The narrower T0 grant covers that assessed tier; the generic repository preflight mint suggestion concerned unrelated #252 at T3 and is not a mint requirement for #335.

No new grant is requested. Reuse the existing T0 grant after refreshing its validity at execution time. The explicit operator read-through hold remains the only current operator decision for this teaching task. Required Claude review, independent review and CI evidence are already complete. No Gate evaluation or merge was performed while that hold remains.

[itsHabib]

The operator has now explicitly released the read-through hold for #335 and authorized landing through Gate using the existing grant. Earlier hold statements are superseded. Exact head remains 4350bbe with completed independent and configured Claude reviews and green CI. Gate run run_82fd6109114d8ce5 parked on review-evidence recognition; proceeding through its normal judgment path, without waiving or fabricating review evidence. After verified landing, close superseded #329 unmerged. No installation authorized.