docs: cut defensive rationale that doesn't change a reader's action - #61
docs: cut defensive rationale that doesn't change a reader's action#61LeTuR wants to merge 1 commit into
Conversation
Apply one test to every rationale in the context files: keep it only if a reader who ignores it would DO something wrong. Cut: why OPERATOR.md is not called CONSTITUTION.md; why the squash-only merge policy deviates from a standing preference; why the queue pane is not an [[external_files]] payload; why POLICY.md is tracked and why its artifact check exists; the retellings of past incidents in files whose reader cannot act on them, kept once in the file that owns each. Kept: every rationale naming a specific failure a reader would re-cause — the trust dialog before the brief, the glyph width hazard, ensure-honours- the-down-flag, the 64-byte name cap, the attestation that must name the head that would merge. No rule and no cross-reference removed; 973 words across twelve files. Claude-Session: https://claude.ai/code/session_018AmsrLXAqeo1zVTsbTyshc
|
Closing as redundant. The work in this branch already landed on Its diff is now actively harmful: because the branch is behind Nothing from the prose-pruning task is missing from |
1 participant
Intent
Fleet task prune-the-rationale/01-01-cut-defensive-prose. Re-running to re-attest the CURRENT head: the previous run reached checks-passed but then rebased my commit onto e861cf3 (#57) and pushed eb80794, leaving the attestation naming cbd9481 — the exact stale-attestation case orchestration/queue/POLICY.md requires a worker to fix before reporting done.
The change itself is unchanged and is prose-only across twelve control-plane context files. The operator objected to a paragraph in orchestration/queue/OPERATOR.example.md 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 applies one test to every rationale in those files — keep it only if a reader who ignores it would DO something wrong — and cuts the rest.
Scope was fixed by the brief: 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 comment headers in scripts/.sh, scripts/lib/*.py and interface/fleet_queue.lua were explicitly EXCLUDED by the brief — their reader is already editing that file, which is exactly who a 'we tried X and it broke' note is for. README.md and update-fleet/SKILL.md were read in full and nothing in them failed the test, so they are deliberately unchanged.
Decisions a reviewer reading only the diff would not know:
Cuts, each because ignoring the passage leads to no wrong action: the 'Why not CONSTITUTION.md' paragraph; 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; POLICY.md's paragraph on why POLICY.md is tracked and why its artifact check exists (POLICY.md's reader is a worker who can change neither); and 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'.
Incident evidence was deduplicated, not 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: 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 and leaves AGENTS.md; the 19-of-20-empty-timelines story stays in fleet-queue §5d and fleet-onboarding §6 and leaves FLEET.md; the 2026-09-09 'did my message land' incident stays in thurbox-session §4c with fleet-queue §4a now cross-referencing it; 'twice a hand-made PR was collected as shipped' stays in fleet-queue's collect section and leaves POLICY.md and §5b.
Rationale naming a specific failure a reader would otherwise re-cause was KEPT on purpose and is not leftover waffle: dispatch answering the trust dialog before it sends the brief; the fuel-glyph width hazard; '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'.
Two constraints held throughout: no rule was removed while removing its justification (an over-argued passage 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'). AGENTS.md's 'Maintaining this file' section is the mandate for this task and was preserved verbatim.
The rebase onto fix(pane): show a task's next move instead of dead text or a fixed method #57 was inspected: fix(pane): show a task's next move instead of dead text or a fixed method #57's new wording in fleet-pane/SKILL.md about a publish state's note being its next move, and its PUBLISH_WORD/PUBLISH_LADDER pointer, survived intact and were deliberately left alone — the brief says to apply the test to a concurrent task's new text rather than restoring mine, and none of that new text is defensive history.
Net effect: 973 words removed across the twelve files (31,611 -> 30,638). No behaviour, script, schema or test changes — prose only. ./scripts/check.sh passes green locally on the rebased tree.
What Changed
AGENTS.md,FLEET.md,CONTRIBUTING.md,orchestration/queue/{POLICY.md,README.md,OPERATOR.example.md}, and five.agents/skills/*/SKILL.mdfiles) that defended a choice or retold history without changing what a reader would do.fleet-queue/SKILL.md; the empty-timelines story stays infleet-queue/SKILL.mdandfleet-onboarding/SKILL.md; the "did my message land" incident stays inthurbox-session/SKILL.mdwith a cross-reference fromfleet-queue/SKILL.md).fleet-pane/SKILL.md's pointer about the TUI pane not being an[[external_files]]payload) down to the pointer itself, without dropping the reference or the underlying rule.Risk Assessment
✅ Low: Prose-only change across twelve control-plane documentation files with no script, schema, or behavior changes; verified word-count claim (973 words removed) exactly matches the diff, spot-checked every deduplication claim (incident stories relocated to their stated destination files), confirmed every rule that had rationale trimmed still states the rule itself, and confirmed no cross-reference was left dangling (e.g. extension.toml.in still carries the fact AGENTS.md's trimmed pointer now only points to).
Testing
Baseline
./scripts/check.shalready passed; since this is a prose-only documentation change with no executable behavior, targeted verification consisted of diffing the base and target commits against every itemized claim in the user intent (scope, specific cuts, dedup, preserved rationale, cross-reference trimming, and the exact 973-word removal count) — all claims checked out exactly, and no findings were raised.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./scripts/check.sh (baseline, already run successfully before this phase)git diff --stat e861cf32..eb807947 to confirm the changed-file set matches the brief's declared scope (12 files minus README.md and update-fleet/SKILL.md)per-filewc -wdiff across all twelve scoped files at base vs target, summed to 973 words removed, matching the stated 31,611→30,638 net-effect claimgrep of the diff for the specific cut passages named in the intent (CONSTITUTION.md paragraph, squash-merge blockquote, external_files pointer defenses)diff inspection of the cross-reference trim example (fleet-pane/SKILL.md 'Its header owns the details...') against the intent's stated trimgrep of the target-commit files for rationale claimed to be intentionally kept (trust dialog, quota window, 64-byte cap) and for #57's PUBLISH_WORD/PUBLISH_LADDER wording, confirming both remain intact✅ **Document** - passed
✅ No issues found.
✅ **Lint** - passed
✅ No issues found.
✅ **Push** - passed
✅ No issues found.