docs: cut rationale that defends choices nobody questioned

[LeTuR]

Intent

Fleet task prune-the-rationale/01-01-cut-defensive-prose. The operator read orchestration/queue/OPERATOR.example.md and objected to a paragraph headed 'Why not CONSTITUTION.md' — 'I am not sure if those are truly helpful, it seems to be some history, legacy choices being as comments.' The task: apply one test to every rationale in the control plane's context files — keep it only if a reader who ignores it would DO something wrong — and cut the rest.

Scope was fixed by the brief and is exactly these twelve files: AGENTS.md, FLEET.md, CONTRIBUTING.md, README.md, orchestration/queue/{POLICY.md,README.md,OPERATOR.example.md} and the five .agents/skills//SKILL.md. The brief explicitly EXCLUDED the comment headers in scripts/.sh, scripts/lib/*.py and interface/fleet_queue.lua — those are read by someone already editing that file, who is exactly the person a 'we tried X and it broke' note is for. A separate task may look at them; this one must not. README.md and update-fleet/SKILL.md were read in full and nothing in them failed the test, so they are deliberately unchanged.

Deliberate decisions a reviewer reading only the diff would not know:

1. Cuts made, each because ignoring the passage leads to no wrong action: the 'Why not CONSTITUTION.md' paragraph (it argues against a filename the reader had no opinion about, by describing a file in another repository); CONTRIBUTING.md's blockquote defending squash-only against a standing rebase-merge preference (the remote enforces squash regardless); the pointer to why the TUI pane is not an [[external_files]] payload, in both AGENTS.md and fleet-pane/SKILL.md (nothing invites the reader to make it one); POLICY.md's paragraph on why POLICY.md is tracked and why its artifact check exists (POLICY.md's reader is a worker who cannot change either); narration of earlier takes — 'exactly as the URL row did before the two became one', 'the five headings ... were never the gate they looked like', 'the profiles file used to say all three rules were enforced', 'a fresh clone behaves exactly as it did before this file existed', 'The pane spent a long time as a wall of uniform text'.

2. Incident evidence was deduplicated rather than deleted. Several past failures were retold in three or four files. Each is now kept once, in the file whose reader can act on it, and cut from the files whose reader cannot: the fix(interface): make the queue pane readable and demo it in the README #25/feat(interface): add a thurbox TUI pane for the task queue #23 second-pull-request story stays in fleet-queue §5a and leaves AGENTS.md; the 19-of-20-empty-timelines story stays in fleet-queue §5d and fleet-onboarding §6 (where the reader could skip starting the reconciler) and leaves FLEET.md; the 2026-09-09 'did my message land' incident stays in thurbox-session §4c and fleet-queue §4a now cross-references it; the 'twice a hand-made PR was collected as shipped' fact stays in fleet-queue §5's collect section and leaves POLICY.md and fleet-queue §5b.

3. Rationale that names a specific failure a reader would otherwise re-cause was KEPT on purpose, and must not be flagged as leftover waffle: dispatch answering the trust dialog before it sends the brief; the ⛽ glyph width hazard and 'turn the glyph off before looking anywhere else'; 'ensure honours the down flag, start clears it'; the 64-BYTE name cap; the attestation that must name the head that would merge, and fix(queue): give every task its own watch floor so no transition is lost #38/feat(queue): archive finished topics out of default views #40/feat(reconcile): add supervised reconciler loop for queue watch/collect/shepherd/refuel #48; 'restarting into a spent quota window burns the reset'; 'a per-file negation list lands a file ignored and nobody sees it'.

4. Two constraints were held throughout, and the diff should be read against them: no rule was removed while removing its justification (where a paragraph was over-argued, it was cut to the sentence carrying the rule, never deleted), and no cross-reference was removed. Where a pointer's only content was the defence being cut, the pointer was trimmed rather than dropped — 'Its header owns the details and the reason a pane travels this way rather than as an [[external_files]] payload' became 'Its header owns the details'. queue/README.md's pointer to OPERATOR.example.md was trimmed to match the cut it points at. POLICY.md's now-cut paragraph carried a pointer to .gitignore's header; that pointer already exists in queue/README.md, which owns that fact.

5. AGENTS.md's 'Maintaining this file' section is the mandate for this task and was preserved verbatim, including its bar.

Net effect: 973 words removed across the twelve files (31,611 -> 30,638), with the largest cuts in POLICY.md (-187), fleet-queue/SKILL.md (-279) and AGENTS.md (-122). No behaviour, script, schema or test changes — this is a prose-only diff. Editing was done with exact-string replacements asserted to match once each, then affected paragraphs were rewrapped to the repo's hand-wrapped 80-column convention. ./scripts/check.sh passes green locally (all checks, including markdown and skills).

The branch was rebased onto origin/main before the work started, because three other fleet tasks are editing the same prose concurrently and this task was told to yield to them.

What Changed

• Removed defensive/historical rationale paragraphs from AGENTS.md, FLEET.md, CONTRIBUTING.md, orchestration/queue/{POLICY.md,README.md,OPERATOR.example.md}, and the four .agents/skills/{fleet-onboarding,fleet-pane,fleet-queue,thurbox-session}/SKILL.md files, keeping only rationale that tells a reader what to do differently (e.g. dispatch's trust-dialog ordering, the glyph width hazard, the reconciler's down/nudge semantics, the 64-byte name cap, attestation/head-matching requirements, quota-window restart risk).
• Deduplicated incident retellings that previously appeared in three or four files down to the one file whose reader can act on it (e.g. the fix(interface): make the queue pane readable and demo it in the README #25/feat(interface): add a thurbox TUI pane for the task queue #23 pull-request story now lives only in fleet-queue's SKILL.md, the 19-of-20-empty-timelines story in fleet-queue and fleet-onboarding, the "did my message land" incident in thurbox-session with a cross-reference from fleet-queue).
• Trimmed cross-reference pointers whose only content was the rationale being cut (e.g. the TUI pane's [[external_files]] justification in AGENTS.md and fleet-pane/SKILL.md, and queue/README.md's pointer to OPERATOR.example.md) down to the pointer itself, without dropping any cross-reference or the rule it points to.

Risk Assessment

✅ Low: Prose-only diff across the exact twelve files the brief scoped, verified against every dedup/preservation claim in the intent (incident stories relocated not deleted, pointers trimmed not dropped, no rule stripped of its justification), with no script/schema/behavior change and a green local ./scripts/check.sh run.

Testing

Baseline ./scripts/check.sh already passed green. Since this is a prose-only docs diff with no executable surface, I validated the change by verifying the diff's actual content against every specific, falsifiable claim in the user intent (file scope, exact word-count deltas per file and in total, the named rationale cuts, and the four incident-story dedup moves) - all matched exactly, and no unintended files (scripts, interface) were touched. No findings.

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• ./scripts/check.sh
• git diff --stat between base 59879e1 and target cbd9481 to confirm only the 12 scoped files (plus README.md/update-fleet with 0 delta) changed and no scripts/*.sh, scripts/lib/*.py, or interface/fleet_queue.lua files were touched
• Word-count comparison of the 12 scoped files at base vs target (wc -w) confirming total 31,611 to 30,638 (-973) and every per-file delta matches the intent's stated numbers exactly
• Manual diff inspection of AGENTS.md, FLEET.md, CONTRIBUTING.md, OPERATOR.example.md, POLICY.md, README.md, and fleet-pane/SKILL.md to confirm the specific cuts named in the intent are present and correctly removed
• grep across fleet-queue/SKILL.md, FLEET.md, thurbox-session/SKILL.md, and POLICY.md at base vs target to confirm the four deduplicated incident stories each survive in exactly the file(s) the intent claims and are removed from the others
• diff of AGENTS.md's Maintaining this file section between base and target confirming byte-identical preservation
• git rev-parse HEAD confirming the worktree is checked out exactly at the target commit with a clean git status

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.