Skip to content

emrg: three comments justify code by a reader the tree deleted #2553

Closed

Description

@argszero

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

  1. No comment under emrg/ says in the present tense that emrg/tools/bash_tool.py reads, imports, keeps or holds something. Past-tense history is legitimate and stays.
  2. No comment names a module-level constant that no module in the tree binds. _UNRESOLVED_ROOT_RE either gains a true sentence or goes.
  3. The fence's placement sentence names the readers that exist, or the clause is dropped.
  4. No behaviour changes. The imports, the protected_paths derivation and the protected-file refusal all stay exactly as they are; this is prose only.
  5. The three bash_tool.py:<line> citations are out of scope — emrg/tools/pwsh_tool_v2.py:15, emrg/sandbox/providers/__init__.py:40 and tests/test_bash_v2_boundary.py:590 cite 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

  1. argszero commented on Oct 23, 2026

    @argszero
    OwnerAuthor

    Handled by #2554

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions