Delete the never-implemented worktree-backend docs, and guard README against --help - #356
Conversation
The README section documented `--shared` and `--warm` with worked examples of two flags the Rust dl has never had -- both exit 2 -- and called the storage layout git worktrees where the implementation cuts hardlinked clones from a bare cache. `docs/worktree-backend-spec.md` documented a `--backend` switch that was never built, beside a directory layout the shipped one contradicts. Deleted, per the decision on #306: the accurate freshness subsection survives under a heading that says what it is, the `dl <ws> up` paragraph survives without the `--warm` framing it hung off, and git history keeps the spec. The guard that stops the next one is the point. `test/test_readme_cli_doc.py` reads every long flag the README writes on a `dl` command line and hands it to the binary's own parser -- so a documented flag that does not exist fails here rather than in a reader's shell. Attribution is what keeps it actionable: the README also explains git's `--shared` and runs cargo and pixi lines, and a guard that failed on those would be one nobody could act on. Refs #306
The `dl --version` transcript quoted `dl 0.1.0` under a paragraph promising "the version and nothing else", and the conda badge advertised v0.0.9; the shipped version is 0.6.0. Both are hand-written restatements of a number `rust/Cargo.toml` owns, so both are now read back against it. Compared against the manifest rather than against a `dl --version` run on purpose: a run would only confirm the binary agrees with itself, and a `-dev` build could launder a stale number through it. The paragraph that calls Cargo.toml "the only place it is written down" now says where the two copies are and what holds them, since a claim of single-sourcing that two strings quietly break is worse than no claim.
The forward direction only catches the flag that already went stale. This is the one that catches the next flag: added to the CLI, shown by --help, and never written up. Strictness is deliberately asymmetric with the forward check, because the question is. Forward asks the parser, so the hidden completion flags count as existing -- "would this work if I typed it" is about the parser, not the help. Reverse asks --help, so they do not count as needing 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; `-y` is documented and `--yes` appears nowhere, which is a complete answer for a reader rather than a gap. A guard that went red on it would be red for a reason nobody would fix, and the fix people reach for then is deleting the guard. Proved it can fail before trusting it: with every `--reconcile` stripped from the README the check names that flag and goes red.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Reviewer's GuideThis PR removes stale documentation for a never-implemented worktree backend and adds an automated test guard ensuring the README’s CLI flags and version strings stay consistent with the shipped binary and Cargo workspace metadata. Sequence diagram for README CLI consistency validationsequenceDiagram
participant Test as test_readme_cli_doc.py
participant README
participant dl as dl parser
participant Cargo as rust/Cargo.toml
Test->>README: Extract long flags from dl command lines
Test->>dl: Parse each documented flag with mutually exclusive flags
dl-->>Test: Accept or reject flag
Test->>dl: Request --help
dl-->>Test: Return visible flags
Test->>README: Check visible flags have documented spellings
Test->>README: Read version transcript and Conda badge
Test->>Cargo: Read shipped version
Cargo-->>Test: Return package version
Test-->>Test: Fail when flags or versions diverge
Flow diagram for README freshness and documentation guardflowchart LR
Changes[README documentation changes] --> Remove[Remove never-implemented worktree backend examples]
Remove --> Clarify[Describe actual bare-cache hardlinked clones and launch freshness]
Clarify --> Guard[test_readme_cli_doc.py]
Guard --> Flags[Validate documented dl flags with the real parser]
Guard --> Help[Ensure visible --help flags are documented]
Guard --> Versions[Match README versions to rust/Cargo.toml]
Flags --> Red[Fail on stale or unknown CLI documentation]
Help --> Red
Versions --> Red
File-Level Changes
Assessment against linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files
Flags with carried forward coverage won't be shown. Click here to find out more.
🚀 New features to boost your workflow:
|
blooop
left a comment
blooop
left a comment
There was a problem hiding this comment.
This was generated by AI during review.
Retrospective wf-review of a merged PR, judged against current main (a5f7ed8, version 0.12.0). This PR merged with no review — Sourcery was rate-limited and no wf-review ran — so the two axes are run here after the fact. Every finding below was reproduced against the working tree, not read off the diff.
Guard exercised with DEVLAUNCH_DL_CMD=rust/target/debug/dl python -m pytest test/test_readme_cli_doc.py — 20 passed on arrival, so the baseline is green and each mutation below is measured against it.
Standards
1. The guard cannot see a flag's documentation being deleted. (non-blocking, but it is the one thing this file was added to prevent)
Deleting the whole --reconcile row from the Global Commands table — README.md:456, the line a reader actually goes to — leaves the suite 20 passed. test_every_flag_dl_offers_a_reader_is_named_in_the_readme (test/test_readme_cli_doc.py:275) searches the whole document for any spelling, and --reconcile is written six more times outside that table. This is not specific to --reconcile: every non-hidden flag is named between 2 and 38 times in README.md, so no flag's documentation row can be removed detectably.
The file argues for this at test/test_readme_cli_doc.py:237 — "This direction is coverage, not attribution, and a false pass here costs a reader nothing while a false failure costs the guard its life." That reasoning holds for the direction it was written for (catching the next flag), and it does catch that: adding a plain --verbose to Cli and rebuilding turns the check red, verified. What it does not do is notice an existing flag losing its documentation. This repo's own review history has found the identical hole twice (#351, #353).
Fix: keep the loose whole-document check as the floor, and add a strict one over the two reference tables — every non-hidden --help flag must have a row in ## Global Commands or ## Options. That is the assertion that would have gone red above, and it still passes today with no allowlist.
2. Flag descriptions are unguarded. (non-blocking)
Rewriting --prune's Description cell to "Delete every workspace and every container on the machine, immediately and without asking" — the opposite of what the flag does, and the exact confusion --prune/--purge invites — leaves the suite 20 passed. The module docstring's premise is "a hand-written copy of a fact the binary already knows"; the description is the largest such copy in the table and nothing owns it. Fix: either compare each row against the first sentence of its --help text, or say in the docstring that descriptions are deliberately out of scope, so the next reader does not assume the table is covered.
3. The probe's safety rests on an unasserted invariant. (non-blocking)
MUTUALLY_EXCLUSIVE_PROBE = ["--ls", "--purge"] (test/test_readme_cli_doc.py:65) is safe only while clap's group = "what" keeps those two in conflict — confirmed today: dl --ls --purge --rm → error: the argument '--ls' cannot be used with '--purge'. Nothing asserts it. If that group is ever loosened, the parametrized test stops probing and starts running dl --purge against the developer's real devlaunch state, once per documented flag. Fix: one test asserting the bare probe is refused with cannot be used with.
4. FENCE is copied where this repo has a fixture for exactly this. (non-blocking)
test/test_readme_cli_doc.py:52 and test/test_bench_doc.py:72 both define, byte for byte:
FENCE = re.compile(r"^```[^\n]*\n(.*?)^```", re.MULTILINE | re.DOTALL)test/fixtures/markdown_sections.py exists precisely to stop this — its docstring says "a second implementation of 'the text under this heading' is a second thing that can drift from the document" — and test_bench_doc.py:47 imports section from it rather than copying. The fence regex is the same kind of thing and did get copied. Fix: move FENCE (and ideally _code_spans) into test/fixtures/markdown_sections.py and import it in both guards.
5. No [Unreleased] entry. (non-blocking) CHANGELOG.md:8. Deleting docs/worktree-backend-spec.md and stripping the README's --shared/--warm material is logged nowhere, though this repo has recorded the identical class of change before: CHANGELOG.md:2911-2919 (0.0.8, Removed) lists WORKTREE_BACKEND_PLAN.md/WORKTREE_BACKEND_README.md and "The README's 'Backend Selection' section, which documented a --backend flag and DEVLAUNCH_BACKEND env var that exist nowhere in the code." #373 and #332, merged the same week, both added entries. Fix: one ### Removed bullet plus a line for the new guard.
Verified clean: the deleted docs/worktree-backend-spec.md leaves no dangling reference anywhere in the tree, and all 32 in-document anchors in README.md still resolve. The surviving closing note at README.md:1919-1923 is accurate. Both version guards are real and currently pinned at 0.12.0.
Spec
Ticket #307: "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)."
- "Apply the worktree-section decision" — done. #306's decision was delete-or-implement; the section and
docs/worktree-backend-spec.mdare gone, the accurate freshness material survives, and nothing references either. ✅ - "It should catch the current staleness class" — all four named items are covered and currently green against
0.12.0.--sharedand--warmare gone from everydlline; the transcript and the badge are both asserted againstrust/Cargo.toml. ✅ - "decide the reverse direction's strictness" — decided, argued, and enforced. ✅ (Finding 1 is about how strict, not whether.)
- "every flag the README names must exist in
dl --help" — deviation. The forward check asks the binary's parser, not--help. The PR argues this well and it is the right call fordl --completion-data, but the ticket left only the reverse direction's strictness open; the forward direction was specified as--helpand was quietly widened. The practical consequence is visible today:DOCUMENTED_FLAGSextracts 15 flags, of which--autorm,--stopand--completion-dataare hidden and therefore invisible to--help. Nothing is wrong with that outcome, but it is a self-authorised reading of the one sentence the ticket did not delegate, and it belongs in the ticket rather than only in the module docstring.
Verdict
Comment. No blocking findings. The delete is clean and the version guards do their job. The guard is weaker than the PR body claims in one specific way that this repo has already been bitten by twice: it catches a flag arriving undocumented, and does not catch a documented flag's row being deleted or its description going wrong. Finding 1 is the one worth a follow-up ticket; findings 4 and 5 are housekeeping.
1 participant
Applies the decision on #306 and adds the guard that keeps it applied.
The delete
## Worktree Backendpublished worked examples of--sharedand--warm— two flags the Rustdlhas never had, both of which exit 2 — and described the storage as git worktrees whereworkspace_clone.rscuts hardlinked clones from a bare cache. The accurate freshness subsection survives under## How fresh a launch is, which is what it was always about; thedl <ws> upparagraph survives without the--warmframing it hung off; a short closing note records that neither flag ever existed, so the next reader arriving from an old copy gets an answer instead of exit 2.docs/worktree-backend-spec.md(a--backendswitch never built, beside a directory layout the shipped one contradicts) is deleted — git history keeps it.The guard
test/test_readme_cli_doc.py, in the style oftest/test_agents_doc.py: the document's hand-written copies of facts the binary already knows, read back against their owners.dlcommand line is a flagdlaccepts. The flag is handed to the binary's own parser — the movetest_bench_doc.pymakes when it hands documented flags to the script's real parser — not compared against parsed help text, because--helpanswers a different question and the README legitimately documents one hidden completion flag. The probe pairs the flag with two mutually exclusive real flags, so the parse always fails and nothing is ever launched; the only thing read off the failure is which refusal came back.dl --helpoffers is named somewhere in the README — the reverse direction, see below.$ dl --versiontranscript and the conda badge, againstrust/Cargo.toml.Attribution is what makes the forward direction actionable. The README also explains git's
--shared/--referenceand runs plenty ofcargoandpixilines; a guard that failed on those would be failing for a reason no reader could act on, which is how guards get deleted. So what is extracted is flags on a line whose first word isdl.The sub-decision the ticket left open: reverse strictness
Enforced, but asymmetrically with the forward check — because the question is asymmetric.
dl --completion-data.--help, so hidden flags do not count as needing documentation.--reposand--update-cacheare hidden precisely so nobody is sent to them; demanding they be documented would demand the opposite of what hiding them said.-yis documented and--yesappears nowhere in the document — a complete answer for a reader, not a gap.What nearly won was leaving it one-directional. The argument for that is real: a guard that fails for a reason nobody can act on gets disabled, and the whole staleness class the ticket names is forward-facing. It lost because the reverse failure is the cheapest kind to act on — write the sentence — and because under the two rules above it passes today with zero exemptions and no allowlist, so it will not cry wolf. A maximally strict version (all flags including hidden, long spelling only) was the other candidate and lost outright: it fails today on
-y, and it would demand documenting the completion plumbing.Staleness class, confirmed and now caught
Checked live rather than taken from the review:
--shared,--warmand the0.1.0transcript andv0.0.9badge were all still stale atorigin/main. The transcript saiddl 0.1.0and the badgev0.0.9against a shipped 0.6.0.Red→green, one slice each:
--shared,--warmanddl --test interrupt→ green after the section delete and after that last one is written as thecargo test -p dl --test interruptit actually meansdl 0.1.0→ green atdl 0.6.0v0.0.9→ green atv0.6.0--reconcilestripped from the README it names that flag and goes redThe paragraph calling
rust/Cargo.toml"the only place it is written down" now says where the two copies are and what holds them: a single-sourcing claim that two strings quietly break is worse than no claim.Full python suite and
pixi run stylegreen. Confined to the worktree-backend section, the two version strings, and one sentence in the coverage section, so the branches on this map merge cleanly.Closes #307
Summary by Sourcery
Remove obsolete worktree backend documentation and add automated checks to keep the README’s CLI examples and version references aligned with the shipped application.
Bug Fixes:
--sharedand--warmoptions and correct the documented release version.Enhancements:
dlflags and help-listed options against the shipped CLI, while accepting hidden parser flags and short aliases appropriately.Documentation:
Tests: