Repository navigation
emrg: three comments justify code by a reader the tree deleted #2553
Description
Observed
Three comments under emrg/ state, in the present tense, that emrg/tools/bash_tool.py reads or keeps something these modules define. That file no longer exists: P7 (issue #1675) deleted it, and the suite pins its absence — tests/test_file_policy_has_one_home.py::test_the_legacy_scan_is_gone_rather_than_re_exported asserts both that the file is not there and that emrg.tools.bash_tool does not resolve.
Each site, beside what the tree actually holds:
| site | the claim | measured |
|---|---|---|
emrg/tools/command_scan.py:31-35 |
"the legacy scanner keeps private aliases to these for its own ~30 call sites, and those aliases are the same function objects, so the two readers cannot drift into two spellings of one command" | no alias of tokenize_command / nested_command_texts / basename exists anywhere. grep -rn 'tokenize_command|nested_command_texts|basename' emrg/ answers this module's own definitions and the modules that import them (bash_tool_v2.py, pwsh_tool_v2.py, and tests) — there is no second reader, so there are no two spellings to keep in step |
emrg/tools/command_scan.py:124 |
"_UNRESOLVED_ROOT_RE stays with the legacy scanner and imports this" |
grep -rn '_UNRESOLVED_ROOT_RE' . --include=*.py --include=*.md answers that one comment line and nothing else — the name is bound nowhere in the tree, so a reader following it finds nothing at all |
emrg/sandbox/fence.py:92 |
"The list stays in emrg/tools/file_policy.py because the legacy scanner reads it too" |
the readers of protected_paths() / protected_hit() are emrg/sandbox/fence.py and emrg/sandbox/roots.py. Nothing outside emrg/sandbox/ imports either name, and emrg/tools/file_policy.py is their only definition |
Why it matters
These are not descriptions, they are justifications — each tells a reader why the code has the shape it has, and each names a consumer that does not exist.
The fence one is the sharp case. "The list stays in emrg/tools/file_policy.py because the legacy scanner reads it too" is precisely the sentence a later reorganisation would act on: it says a second consumer needs the list where it is. A reader who believes it either keeps a definition for a reason that is not true or concludes the placement is load-bearing when it is not. The same shape sits in command_scan.py, where the docstring explains a sharing arrangement between two files — one of which is gone.
The third is worse in kind rather than in degree: _UNRESOLVED_ROOT_RE is named as a thing that "stays with the legacy scanner and imports this", so a reader who wants to see the pattern it describes has no file to open and no constant to read.
Expected
Every statement about the deleted module describes the tree as it is: the history is kept where it is worth keeping, in the past tense, and a reason given for a definition's placement names readers that exist.
What the fix must satisfy
- No comment under
emrg/says in the present tense thatemrg/tools/bash_tool.pyreads, imports, keeps or holds something. Past-tense history is legitimate and stays. - No comment names a module-level constant that no module in the tree binds.
_UNRESOLVED_ROOT_REeither gains a true sentence or goes. - The fence's placement sentence names the readers that exist, or the clause is dropped.
- No behaviour changes. The imports, the
protected_pathsderivation and the protected-file refusal all stay exactly as they are; this is prose only. - The three
bash_tool.py:<line>citations are out of scope —emrg/tools/pwsh_tool_v2.py:15,emrg/sandbox/providers/__init__.py:40andtests/test_bash_v2_boundary.py:590cite the line where a claim used to live, and the file really was at that line. Marking provenance is not the same fault as asserting a live consumer.
Not asking for a guard
The checkable half — "a comment names a symbol nothing binds" — cannot be mechanised at this repo's standard, and the reason is already written down in the tree: tests/test_docstring_cross_references_resolve.py resolves :role:-shaped references only, and its own fixture test_a_bare_backticked_name_in_prose_is_not_a_reference refuses to treat a bare backticked name in prose as a reference, because prose is full of them. Every one of the three sites above is a bare-backtick comment. Widening that guard would report the repo's prose, not a defect.
Activity
argszero commentedon Oct 23, 2026
Handled by #2554
emrg: the command scan's comments name readers that exist (#2553) (#2554