CLAUDE.md: the ticket is the pull channel, and the brief is write-once #558

2026-09-12T10:45:54+02:00

ltms commented

2026-09-12 10:45:54 +02:00

Docs only — the canonical block in CLAUDE.md, plus the byte-identical copy in wiki/7-Use-Cases.md.

Why

A fleet_send to a working member is accepted and returns a ticket, and is then never delivered. That happened three times in one session here, and the member was released still executing a brief I had retracted twice.

The broker was not lying. The receipt is true, and it is a fact about the mailbox, when what was needed was a fact about the pane. Two channels, with the report coming from the near one — the same shape as NOT_DELIVERED covering several epistemic states, one layer out of the process.

The fleet01 lead named the mechanism, and it is the part that says what else qualifies:

A push delivery requires the recipient to be available at send time. A pull channel requires only that they look before acting.

So the ticket is not more reliable than the mailbox — it is a different direction. Its success depends on the member's procedure rather than on the timing of my send. A second push channel would buy nothing; a file in the worktree that the brief tells them to re-read would work identically.

What changed

Both halves are written down, because each is useless without the other.

Member — turn contract, new item 4 (the following items renumber):

Re-read the ticket before you act on anything you were told earlier, and again before you commit. A message reaches you only while you are free to receive it; the ticket is there whenever you look. If a ticket comment contradicts your brief, the ticket comment is newer and it wins.

Lead — step 5 (Collect): the same mechanism, plus the obligation it creates on the sender:

All corrections go to the ticket, and the brief is write-once.

That second half is the fleet01 lead's catch, and it is the non-obvious one. The member cannot check which source is actually newer — it just always prefers the ticket. So the day a lead revises a brief in place instead of commenting, the member prefers a stale comment and does the wrong thing while following the rule exactly. A guarantee maintained only by the lead's habit, with nothing enforcing it — the same shape as a conditional two-arg remove or an unreachable unknown arm.

Carve-out, so the rule is not read too widely: a first brief for a unit not yet running is not a correction, and may carry the whole spec.

Checks

Canonical-block sync check from the addendum: in sync: True (run in the main clone, as required — a member's worktree has wiki/ uninitialized).
mvn -Dtest=McpContractDocTest,ClaudeCodeLauncherTest,RestRouteInventoryTest,FleetProfilesLiveDefaultTest test → MVN_EXIT=0, Tests run: 117, Failures: 0, Errors: 0.
No reference anywhere cites the member-contract items by number, so the renumber is safe (checked .claude/skills/**, docs/, and the Java sources).
The wiki submodule pointer is deliberately unstaged; the wiki commit goes to its own remote separately.

Docs only — the canonical block in `CLAUDE.md`, plus the byte-identical copy in `wiki/7-Use-Cases.md`. ## Why A `fleet_send` to a working member is **accepted** and returns a ticket, and is then never delivered. That happened three times in one session here, and the member was released still executing a brief I had retracted twice. The broker was not lying. **The receipt is true, and it is a fact about the *mailbox*, when what was needed was a fact about the *pane*.** Two channels, with the report coming from the near one — the same shape as `NOT_DELIVERED` covering several epistemic states, one layer out of the process. The fleet01 lead named the mechanism, and it is the part that says what else qualifies: > **A push delivery requires the recipient to be available at send time. A pull channel requires only that they look before acting.** So the ticket is not *more reliable* than the mailbox — it is a different **direction**. Its success depends on the member's **procedure** rather than on the timing of my send. A second push channel would buy nothing; a file in the worktree that the brief tells them to re-read would work identically. ## What changed Both halves are written down, because each is useless without the other. **Member — turn contract, new item 4** (the following items renumber): > Re-read the ticket before you act on anything you were told earlier, and again before you commit. A message reaches you only while you are free to receive it; the ticket is there whenever you look. **If a ticket comment contradicts your brief, the ticket comment is newer and it wins.** **Lead — step 5 (Collect):** the same mechanism, plus the obligation it creates on the *sender*: > **All corrections go to the ticket, and the brief is write-once.** That second half is the fleet01 lead's catch, and it is the non-obvious one. **The member cannot check which source is actually newer — it just always prefers the ticket.** So the day a lead revises a brief in place instead of commenting, the member prefers a *stale* comment and does the wrong thing *while following the rule exactly*. A guarantee maintained only by the lead's habit, with nothing enforcing it — the same shape as a conditional two-arg `remove` or an unreachable `unknown` arm. Carve-out, so the rule is not read too widely: **a first brief for a unit not yet running is not a correction**, and may carry the whole spec. ## Checks - Canonical-block sync check from the addendum: `in sync: True` (run in the main clone, as required — a member's worktree has `wiki/` uninitialized). - `mvn -Dtest=McpContractDocTest,ClaudeCodeLauncherTest,RestRouteInventoryTest,FleetProfilesLiveDefaultTest test` → `MVN_EXIT=0`, `Tests run: 117, Failures: 0, Errors: 0`. - No reference anywhere cites the member-contract items by number, so the renumber is safe (checked `.claude/skills/**`, `docs/`, and the Java sources). - The `wiki` submodule pointer is deliberately **unstaged**; the wiki commit goes to its own remote separately.

ltms added 1 commit 2026-09-12 10:45:54 +02:00

CLAUDE.md: the ticket is the pull channel, and the brief is write-once

CI / shell-tests (pull_request) Successful in 6s

Details

CI / contract (pull_request) Successful in 1m26s

Details

CI / build (pull_request) Successful in 2m10s

Details

351ee1ea6d

A send to a working member is accepted and returns a ticket, then is never
delivered. That happened three times in one session here, and the member was
released still executing a brief that had been retracted twice. The receipt is
true — it is a fact about the mailbox, when what was needed was a fact about the
pane.

The fleet01 lead named the mechanism: a push delivery needs the recipient free at
send time, while a pull channel needs only that they look before acting. So the
ticket is not more reliable than the mailbox, it is a different direction, and its
success depends on the member's procedure rather than on the timing of the send.

Both halves have to be written down, because each is useless alone:

- Member (turn contract, new item 4): re-read the ticket before acting on anything
  told earlier, and again before committing. A ticket comment that contradicts the
  brief is newer and wins.
- Lead (step 5): all corrections go to the ticket, and the brief is write-once.
  The member cannot check which source is newer — it just always prefers the
  ticket — so revising a brief in place makes it obey the rule and do the wrong
  thing. A first brief for a unit not yet running is not a correction.

wiki/7-Use-Cases.md is updated to keep the canonical block byte-identical; the
sync check passes. The wiki submodule pointer is deliberately left unstaged.

ltms merged commit 4f9aba40e7 into main

2026-09-12 11:12:55 +02:00

ltms deleted branch docs/brief-write-once-precedence

2026-09-12 11:12:55 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: fleet/fleetd#558