Repository navigation
Fix the worktree section and guard README against --help #307
Description
Question
Apply the worktree-section decision, then add a doc guard in the style of test/test_agents_doc.py: every flag the README names must exist in dl --help (decide the reverse direction's strictness). It should catch the current staleness class: --shared, --warm, the 0.1.0 --version example (README.md:283), the v0.0.9 conda badge (README.md:15).
Activity
blooop commentedon Aug 22, 2026
breadcrumb: entering building — wf-tdd stage subagent launched (manager: wf-mid run working map #299).
blooop commentedon Aug 22, 2026
breadcrumb: building. Restating the contract: apply #306's delete (drop the
--shared/--warmworked examples and the "git worktrees" storage claim, keep the accurate push-then-launch subsection under a truthful heading, retire the never-built spec), then add the README-vs---helpguard.Seams I intend to test at, all three in the acceptance harness's doc-guard style — the README as a document, judged against the shipped binary and against the one place the version is written down:
dlcommand line is a flagdlaccepts. The flag is handed to the binary's own argument parser rather than compared against parsed help text — the same move the bench-doc guard makes when it hands documented flags to the script's real parser. The probe pairs the flag with two mutually exclusive real flags, so the parser always refuses the line and nothing is ever launched; the discriminator is whether it refuses the flag as unknown. Attribution matters: the README also documents git's--sharedand cargo's--release, so what is extracted is flags written on a line whose first word isdl, not every--wordin the file.dl --helplists is named somewhere in the README (reverse direction, see sub-decision below).dl --versiontranscript and the conda badge, against the single place the version is written down.Sub-decision (reverse strictness) settled and reasoned in a following breadcrumb.
blooop commentedon Aug 22, 2026
breadcrumb: sub-decision settled — the reverse direction is enforced, but asymmetrically with the forward one, because the question is asymmetric.
dlcommand line is handed to the binary, and hidden flags count as existing. "Would this work if I typed it" is a question about the parser, and the README legitimately documents one of the hidden completion flags.--help: every flag the help offers a reader must be named somewhere in the README. Hidden flags therefore do not need documenting — they are hidden precisely so nobody is sent to them, and requiring them to be written up would require the opposite of what hiding them said.-yis documented and the long form appears nowhere; that is a complete answer for a reader, not a gap.What nearly won: leaving it one-directional. The argument is the one the ticket raised — a guard that fails for a reason nobody can act on gets disabled — and the whole staleness class named here is forward-facing, so the reverse direction buys nothing today. It lost on maintainability, which the map ranks first: the reverse direction is the only half that catches the next flag rather than the last one, its failure is the cheapest kind to act on (write the sentence), and under the two rules above it passes as written with zero exemptions and no allowlist — so it will not cry wolf, which was the objection.
Also considered and rejected outright: maximal strictness — every flag the binary has, long spelling only. It fails today on the short-only flag and would demand documenting the completion plumbing, i.e. exactly the guard the objection describes.
Method note worth keeping: the forward check hands each flag to the binary's own parser rather than diffing against parsed help text, pairing it with two mutually exclusive real flags so the parse always fails and nothing is ever launched. And attribution is what keeps it actionable — the flags extracted are those written on a line whose first word is
dl, because the same document also explains git's and cargo's flags, and a guard failing on those is one nobody could act on.Staleness class confirmed live before being asserted: both version copies were still stale on main (transcript four minors behind, badge further). One extra catch the extraction surfaced — a sentence writing a cargo test target as though it were a
dlflag — is now written as thecargo testinvocation it means.blooop commentedon Aug 22, 2026
breadcrumb: built — PR #356, CI green on every check (ci, rust, rust-coverage, e2e, packaging, public-api, prek, gate).
Three slices: the section delete plus the flag guard (red on the two never-implemented flags); the two version copies read back against the manifest (red on both); the reverse direction (green on arrival, proved failable by mutation). Not merged, not self-reviewed — ready for review in fresh context.
blooop commentedon Aug 22, 2026
breadcrumb: build → in review. PR #356 pushed; every check green including
gate.Sub-decision settled — reverse strictness is enforced, but asymmetrically with the forward check, because the question is asymmetric. Forward asks the parser, so hidden flags count as existing (the README legitimately writes
dl --completion-data). Reverse asks--help, so hidden flags need no documentation — they are hidden precisely so nobody is sent to them — and a flag counts as documented if the README names any of its spellings (-yis documented; its long form appears nowhere).What nearly won: leaving it one-directional, on the argument I put in the handoff — a guard that fails for a reason nobody can act on gets disabled, and the named staleness class is entirely forward-facing. It lost on maintainability: reverse is the only half that catches the next flag, its failure is the cheapest of any to act on, and under those two rules it passes today with zero exemptions and no allowlist, so it will not cry wolf. Maximal strictness (all flags, long spelling only) lost outright — it fails today on
-yand would demand documenting the completion plumbing.Two things worth carrying into review:
dl --test interruptas though--testwere a dl flag, when it is a cargo test target. Nowcargo test -p dl --test interrupt.--versiontranscript said0.1.0and the conda badgev0.0.9, both now read back againstrust/Cargo.toml.The forward check hands each flag to the binary's own parser — the move
test_bench_doc.pyalready makes — pairing it with two mutually exclusive real flags so the parse always fails and nothing is ever launched. Attribution to lines whose first word isdlis what keeps it actionable, since the same README explains git's own--shared/--referenceand runs cargo and pixi lines. That is also the ironic detail: the README's git--sharedprose is why the deleted section's--sharedcould look plausible for so long.