Fix what a clean-room reconstruction of the spec found - #539
Open
blooop wants to merge 4 commits into
Open
Conversation
added 3 commits
August 30, 2026 16:56
README said `dl blooop/devlaunch` names the pane `devlaunch-main-3j1t`, "the workspace id, the same string `dl --ls` prints and the container's hostname carries". docs/workspace-tools.md:511 says the opposite about the same command: the pane is `devlaunch@main`, the id read for a person with the hashed suffix off, *where* `dl --ls` and the hostname say `devlaunch-main-3j1t`. The docs page is right. `titled()` in flows/launch.rs:2850 answers `workspace.label()` whenever the devpod id is the derived one, which is every launch that does not name a recorded id, and `an_id_metadata_recorded_is_titled_ by_that_id_and_not_by_the_triples_label` pins the one arm that differs. The README sentence is the pre-change behaviour that workspace-tools.md:530 already describes as what it "used to be". Nothing caught it: the README's guard (test_readme_cli_doc.py) holds flags to being mentioned, not claims to being true, so the most read sentence about this feature was the least checked one. Found by a clean-room reconstruction of the spec from the CLI surface, the docs and the test names alone, with the implementation withheld.
docs/cli.md writes `dl <ws> rm --force` a dozen times and never says that the position is load-bearing. It is: `--force` has to follow both the workspace and the verb. In the verb slot it is read as the verb (`Unknown command '--force'`) and in the workspace slot as the workspace (`Unknown workspace '--force'`), both exit 1 with nothing deleted. A global command has no slot for it to fall into, so `dl --force --prune` and `dl --prune --force` are one line. Two rules for one spelling, discoverable only by being refused, and written down until now only in the names of the tests that pin them. This says it once beside the docker paragraph that already explains which `--force` is which, and cites those tests so the rule and its guard are one lookup apart.
The terminal title is stated on two pages: the README's feature list, where a reader meets it, and docs/workspace-tools.md, where the reasoning for the spelling lives. That is a second hand-maintained copy of one fact, which this repository allows only with a test beside it that diffs the copies. The rule earned the test rather than being applied on principle. The two pages had already drifted apart on this exact sentence, in opposite directions, about the same example command, and nothing failed: the README's guard holds a flag to being mentioned, not a claim to being true. The instrument is the sentence both pages already write, "names the pane `<x>`", so neither carries a marker for this test's benefit and a page that drops the claim fails here rather than passing quietly. Reverting the README to its old wording reproduces the failure.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Reviewer's GuideThis documentation-focused PR fixes an incorrect README terminal-title example, specifies positional Flow diagram for positional force flag handlingflowchart TD
A[Parse CLI arguments] --> B{Command is global?}
B -->|Yes| C[Accept --force in either position]
B -->|No| D{--force follows workspace and verb?}
D -->|Yes| E[Execute workspace verb]
D -->|No| F[Return argument error and delete nothing]
Flow diagram for synchronized terminal-title documentationflowchart LR
A[README title claim] --> C[Title consistency regression test]
B[workspace-tools title claim] --> C
C -->|Claims agree| D[Documentation passes]
C -->|Claims differ or missing| E[Test fails]
File-Level Changes
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:
|
A fresh-context review of this branch found the `--force` paragraph asserting a
rule the grammar does not implement, and the title guard pinning something
weaker than it claimed. Both are fixed here.
**The paragraph generalised two cases into a law.** It said a misplaced `--force`
"refuses rather than being dropped". True of the workspace and verb slots; false
of everything past the verb, where only `rm` and `rme` read the flag and
`up`, `stop`, `kill`, `code`, `restart`, `recreate`, `reset` and `dotfiles` take
it and discard it in silence. cli.rs says so twice already ("the flag is the
no-op it is on `up` and `stop`"; "every other verb drops it on the floor") and
README says there is no `dl <ws> kill --force` to type, which in fact parses.
Verified against the built binary rather than inferred. The section now states
both halves, names `kill` as the one worth remembering, and adds the selector
form, which cannot be forced at all: `dl rm --force` is the verb-slot refusal and
its suggested `dl rm -- --force` would run the flag as a shell command.
It also moved. Sitting inside `### --rm: the throwaway workspace` it separated
"It stops at work that is nowhere else" from the `--rm` that sentence's "It"
refers to, and handed the reader `--force` as the antecedent: the exact thing
that goes past that check. It is its own section now, beside the other
grammar sections, and cites the 259-ordering matrix test that is its thesis.
**The guard pinned agreement, not truth.** It diffed two prose pages, so the
inverted repair, editing the docs page down to the README's wrong string, would
have passed it while reporting that `titled()` had been consulted. It had not.
`flows/launch.rs` carries the same sentence verbatim and is the one copy that
cannot be wrong without the behaviour being wrong, so the prose is now held
against it. Both drift directions are checked, including that inverted one.
Anchoring the regex on the example command fixes two more: it no longer matches
inside "every prompt *renames* the pane", which the docs and provision.rs both
say of the prompt's own later write, and set equality no longer forbids `docs/`
from documenting the examples that are titled differently, which it does.
Also: the README named one of the title's two transformations, and dropping the
suffix alone gives `devlaunch-main`, not `devlaunch@main`. Both are named now,
with the id-named case the docs page already covers. And all three copies cite
the guard, so whoever edits one learns the other two exist.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three fixes, all of them defects found by reconstructing this tool's specification from its observable surface alone, with the implementation withheld.
How they were found
Five agents were each given a sealed corpus and asked to write the implementation spec they would hand to an engineer:
README.md, the six user-facingdocs/pages, verbatimdl --helpandaid --help, and an index of all 2,496 test names with no bodies. No source, noCLAUDE.md, nodevelopment.md, and neither archival planning document, sincerust-rewrite-plan.mdstates the layer decision outright and would have given the answer away.The primary result is not in this diff and is worth recording: three of the five reconstructed the real architecture (four layers,
runnertoclientstodomaintoflows, dependencies strictly downward, the crate split withdevlaunch-runneras a leaf,render.rsowning every user-facing byte). One inferred that a fitness test must exist asserting only one type spawns processes, which isrust/devlaunch-runner/tests/one_seam.rs. The architecture is legible from outside the implementation. What the exercise actually produced was a list of places where the documented behaviour is wrong, underspecified, or self-contradictory, which is what is fixed here.Every claim was verified against the tree before being acted on. One in the same batch was verified and rejected: that the delete guard inspects a recorded clone while the delete removes a derived one. Both route through the same
resolve_clone_path, so it is not a defect and nothing here changes it.1. The README said the wrong thing about the terminal title
README.mdsaiddl blooop/devlaunchnames the panedevlaunch-main-3j1t, "the workspace id, the same stringdl --lsprints and the container's hostname carries".docs/workspace-tools.mdsays the opposite about the same command: the pane isdevlaunch@main, and it contrasts that against exactly the string the README asserted.The docs page is right.
titled()inrust/devlaunch-core/src/flows/launch.rsanswersworkspace.label()whenever the devpod id is the derived one, which is every launch that does not name a recorded id, andan_id_metadata_recorded_is_titled_by_that_id_and_not_by_the_triples_labelpins the single arm that differs. The README was describing behaviour thatworkspace-tools.mdalready calls what it "used to be".The corrected sentence names both of the title's transformations. Dropping the hashed suffix alone gives
devlaunch-main; the dash before the branch is also spelled@.2. Where
--forcemay sit was undocumented, and the first attempt got the rule wrongdocs/cli.mdwrites the flag in the trailing position a dozen times without saying the position is load-bearing. The rule has two halves, and the first version of this PR documented only the first and generalised it into a law:Unknown command '--force'); in the workspace slot as the workspace (Unknown workspace '--force'). Both exit 1, nothing deleted.rmandrmedo anything with it.up,stop,kill,code,restart,recreate,resetanddotfilestake the flag and drop it silently. That is the one place this grammar discards a word rather than refusing it, andkillis the case worth remembering, since the README says there is nodl WORKSPACE kill --forceto type and in fact it parses.dl rm --forceis the verb-slot refusal, and its suggesteddl rm -- --forcewould run the flag as a shell command.dl --force --pruneanddl --prune --forceare one line.The original text claimed "a flag that has landed somewhere it cannot mean what you meant refuses rather than being dropped", which is true of the first bullet and false of the second.
cli.rssays so twice already ("the flag is the no-op it is onupandstop"; "every other verb drops it on the floor"). Verified against the built binary rather than inferred.It is now its own section beside the other grammar sections rather than inside
### --rm: the throwaway workspace, where it had separated "It stops at work that is nowhere else" from the--rmthat sentence's "It" refers to, handing the reader--forceas the antecedent: the exact thing that goes past that check.3. A second copy of one fact, now diffed against the code
The terminal title is stated in three places: the README's feature list,
docs/workspace-tools.mdwhere the reasoning lives, andflows/launch.rswhere it is computed. The standing rule permits the copies only with a test beside them that diffs them.The first version diffed the two prose pages against each other, which pins agreement rather than truth: had the drift been repaired by editing the docs page down to the README's wrong string, that guard would have passed while its message claimed
titled()had been consulted. It had not. The guard now holds both pages against the module that computes the title, which is the one copy that cannot be wrong without the behaviour being wrong. Both drift directions were checked, including that inverted repair.Anchoring the regex on the example command fixed two more: it no longer matches inside "every prompt renames the pane", which
docs/workspace-tools.mdandflows/provision.rsboth say of the prompt's own later write, and set equality no longer forbidsdocs/from documenting the examples that are titled differently, which it does. All three copies now cite the guard, so whoever edits one learns the other two exist.This is the judgment call in the PR. If you would rather single-source the fact than guard the copies, that work is confined to the third and fourth commits.
Deliberately not fixed here
dl --lsis serial, onedevpod statusper workspace. Now #540.reconcile.rsjoins by path and never by id, plus a resumable two-phase migration. Already in flight in recent commits.every_row_carries_its_own_index_or_marking_cannot_accumulateshows indices already exist.Worth a separate look: roughly thirty tests pin behaviour byte-for-byte against the retired Python build, an oracle nothing can run any more, while
names_python_refuses_for_exotic_unicode_are_accepted_hererecords where the parity is deliberately partial.Testing
test/minuse2e: 662 pass. Doc guards (test_docs_prose,test_docs_links,test_citations_resolve, the new guard) 284 pass;test_readme_cli_docandtest_bash_completion50 pass against a freshly builtdl. The twotest_devcontainer_manifestfailures in this container are pre-existing on an unmodified tree and needpixi, which is not installed here. No Rust behaviour changed; the onlyrust/edit is a doc comment naming the guard.