[brettheap]

Closes #54 (its part b, the checker; #209 did its part a). Closes #58 (its last count sites; #209 did the rest).

Landing order: after #209, which landed on main as 2cb14a9 (2026-10-18T04:01Z). Before it landed, this branch was red on exactly one case, test_no_shipped_bash_ends_its_options_after_an_operand[lanes]: the corrected rule caught lanes:520's grep -v 'not fetching; reading origin/' -- "$local_err_file", the BSD-incompatible shape #54 reported, which #209 gave its -e (part a). With main merged in (9332add), tests/test_repo_hygiene.py is green (203 passed) with no exception added, and the required Linux CI passed at bb3c7dc.

With #209 on main, this PR completes #54 and #58, so it closes both.

What was wrong

_end_of_options_after_an_operand cut each line with a bare re.split(r"[|;&()]|\$\(|", line)before tokenizing. That cut does not see quotes. A quoted pattern holding;, &, |, (, )` or a backtick came apart at that character:

• Missed findings. On main, the function returns [] for lanes, although line 520 has the shape the rule exists to catch. The ; inside 'not fetching; reading origin/' cuts the call before its --, so neither half holds both the operand and the --. restart:247 and lanes:311 carry the same BSD-incompatible grep -v 'pattern' -- file shape PR #53 fixes at skills/restart/SKILL.md:58, and the hygiene checker's own text-split can't see it #54's body shows the BSD failure with POSIXLY_CORRECT=1 grep -v 'not fetching; reading origin/' -- /tmp/x → grep: --: No such file or directory.
• False findings. A quoted message holding ; grep x -- y became a new "command" after the ; and was flagged, although nothing runs it.

What changed

• _shell_tokens now tokenizes the whole line first. It hands each command separator back as a token of its own, but only where the shell reads it as syntax:

  • Inside single quotes, nothing is a separator.
  • Inside double quotes, only $( and a backtick are, because they open a nested command whose quotes start afresh. The matching ) is tracked, so the outer double quote resumes in the right place: out="$(sed -n 'p' -- "$f")" still yields the inner sed call.
  • A backslash makes the next character plain text.

• _commands_on cuts that token stream into commands at the separator tokens, as restart:247 and lanes:311 carry the same BSD-incompatible grep -v 'pattern' -- file shape PR #53 fixes at skills/restart/SKILL.md:58, and the hygiene checker's own text-split can't see it #54 asked. _end_of_options_after_an_operand's per-command logic is unchanged; only its loop header now reads _commands_on(line).

• Quotes that span lines. The rule still reads one line at a time. A line that ends inside a quoted run could be the last line of a multi-line quote. Read from outside every quote, its closing quote would open one instead and swallow the rest of the line. For example, the tail of a multi-line awk program in lanes-edit.sh (}' | LC_ALL=C sort | awk -v s="$US" '{ … }')") would lose its second awk call. So a line that ends inside a quote is read again from inside a single-quoted run and from inside a double-quoted one, and every reading's commands are checked. A line that closes every quote it opens is read once, as before.

• The prose still says "four" about inventories that hold six, ten and eleven — six sites, all predating #45 #58. Three comments still counted the bash files. They now say it without a number:

  • "All three files here are bash" → "No command here has a PowerShell twin" (the wording Make the repoG#8 assertion able to fail, give lanes' stderr filter its -e, and stop counting the bash files in prose (#66, #54, #58) #209 used in README.md). "The files here are all bash" would be false, because lanes-index and lane-worktrees are python3.
  • "these four bash files" → "the shipped bash files".
  • In conftest.py, "these three files are bash" → "there is no Windows twin to run instead for any shipped bash file".

  These are comment and docstring changes only.

Functions and regions edited

• tests/test_repo_hygiene.py: test_no_document_offers_a_windows_powershell_twin (docstring only)
• tests/test_repo_hygiene.py: test_the_root_carries_the_line_ending_rule (docstring only)
• tests/test_repo_hygiene.py: _COMMAND_SEPARATORS (new constant, after _OPTIONS_WITH_ARGUMENTS)
• tests/test_repo_hygiene.py: _shell_tokens
• tests/test_repo_hygiene.py: _commands_on (new)
• tests/test_repo_hygiene.py: _end_of_options_after_an_operand (loop header only)
• tests/test_repo_hygiene.py: LATE_END_OF_OPTIONS_REFUSED, LATE_END_OF_OPTIONS_ACCEPTED, test_the_end_of_options_rule_sees_a_call_whose_quotes_hold_a_separator, test_the_end_of_options_rule_finds_no_call_inside_a_quoted_string (new, directly after test_no_shipped_bash_ends_its_options_after_an_operand)
• tests/conftest.py: the comment block above WINDOWS_SKIP (one line)
• lane-end: the comment in the Amendment 15 block above the canon-lane call (comment only)
• tests/test_lane_helpers.sh: the comment above the alias-read refusal's canon-lane case (comment only)
• tests/test_repo_hygiene.py: test_no_shipped_bash_opens_a_case_inside_a_command_substitution (docstring only)
• lane: the comment in the Amendment 15 block above its canon-lane call (comment only)
• lane-start: the "ONE RESOLVER, SHARED" comment in its Amendment 15 block (comment only)
• lanes-edit.sh: the comment above the canon-lane) subcommand (comment only)

Behaviour on today's files, measured

I extracted the function from main's copy and from this branch's copy (via ast, no conftest import) and compared them over every file the rule reads: the 14 ALL_BASH files, plus claude-current and claude-restart-check, which tests/test_claude_current.py holds to the same rule.

• Findings: unchanged in 15 of 16 files. The one change is a new finding at lanes:520, described above.

• Calls examined: in four lines, the old cut examined a call that the new reading does not:

  • lanes-edit.sh:2163 is a note "…| grep -c '^+' …" message.
  • tests/test_lane_helpers.sh:11732/11735/11739 have a sed inside a single-quoted bash -c '…' body.

  The old cut saw these only in pieces, split at the ( of their pattern. The new reading treats single-quoted text as text, which is what restart:247 and lanes:311 carry the same BSD-incompatible grep -v 'pattern' -- file shape PR #53 fixes at skills/restart/SKILL.md:58, and the hygiene checker's own text-split can't see it #54 asks for. Three lines now show a bare -- that the old cut hid: openRepoTools:1661 and lane:371 (both the correct -e … -- shape, no finding) and lanes:520. No line lost a --.

• Not changed here (pre-existing): the rule reads git grep as grep, so git grep -n 'x' REV -- path would be flagged. That happens with or without a separator in the quote, and no file the rule reads has the shape today.

Tests

There are 14 new parametrized cases, modelled on the bench-root rule's red and green (why, text) rows:

• 8 RED rows (must be caught): restart:247 and lanes:311 carry the same BSD-incompatible grep -v 'pattern' -- file shape PR #53 fixes at skills/restart/SKILL.md:58, and the hygiene checker's own text-split can't see it #54's own line, plus a pipe in an alternation, an & in a sed replacement, () in a double-quoted pattern, a ; in an awk program, a backtick in a single-quoted pattern, a nested $(…) inside double quotes, and the closing line of a multi-line awk program followed by a second call.
• 6 GREEN rows (must not be flagged): quoted strings holding ;, &&, |, () or backticks, and a correct -e call whose pattern holds ; sed … --.

Fail before: I appended the new block, byte-identical, to git show origin/main:tests/test_repo_hygiene.py in a scratch tree beside main's conftest.py, and ran it with OPENREPOTOOLS_CODE_ROOT pointed at this worktree and every LANES_*/TMUX* variable unset:

python3 -m pytest tests/test_repo_hygiene.py -k "sees_a_call_whose_quotes_hold_a_separator or finds_no_call_inside_a_quoted_string" -p no:cacheprovider -q
14 failed, 189 deselected

Pass after, in this worktree with the same environment:

python3 -m pytest tests/test_repo_hygiene.py -k "sees_a_call_whose_quotes_hold_a_separator or finds_no_call_inside_a_quoted_string or ends_its_options_after_an_operand or the_python_files_compile or offers_a_windows_powershell_twin or carries_the_line_ending_rule" -p no:cacheprovider -q
1 failed, 30 passed, 172 deselected
FAILED tests/test_repo_hygiene.py::test_no_shipped_bash_ends_its_options_after_an_operand[lanes]   (lanes:520; #209)

python3 -m pytest tests/test_claude_current.py -k "keep_the_repositorys_bash_rules and ends_its_options" -p no:cacheprovider -q
2 passed, 86 deselected

python3 -m py_compile is clean on both changed files. I did not run the full suite locally; CI's tests job is the suite of record.

The remaining #58-shaped counts (bb3c7dc, after #209 landed)

#209's independent review found counts of #58's kind in files #209 edits, which #58 did not list. Each true count was measured from the code (INSTALLABLES at openRepoTools:1066 holds 17: 16 commands plus repos.tsv), and each sentence now says it without a number where a number would drift again:

• docs/README-lanes.md:76 "thirteen files" → "every command and the alias table";
• docs/README-lanes.md:4 "the four commands it describes" → "the commands it then described" (the four that came from brett-wip with their history);
• docs/README-lanes.md:289 and :301, which leaned on :4's "four" and were false anyway (canon-lane is called by lane, lane-start, lane-end, lane-handoff, lane-rename and lane-worktrees besides lanes-edit.sh) → "the commands here" and "the one the commands share rather than each keeping its own";
• docs/README-lanes.md:2792 "not a thirteenth word" → "not one more word";
• docs/README-lanes.md:4127 "twenty-seven artifacts" and "all thirteen targets" (31 and 17 now) → "any of its artifacts" and "every target in the bin directory";
• tests/test_openrepotools_command.py:395 "All NINE files" → "Every INSTALLED file", and the test test_install_places_all_nine_or_none → test_install_places_all_or_none (it withholds only park, so nine was never its subject).

Proof, with every LANES_* and TMUX* variable unset: the two touched install tests pass; tests/test_repo_hygiene.py plus tests/test_skill_shell_blocks.py (which reads the manual) give 209 passed; and of the 10,748 quoted strings in the six test files that read docs/README-lanes.md, none changed whether it matches.

Three more, which the independent review at bb3c7dc found, are now fixed too (5f1c329). They are the same kind and #58 does not list them, but this PR closes #58. Comments and test prose only; no behaviour changes:

• lane-end, the Amendment 15 block: "the ONE resolver all four commands share" → "the ONE resolver the commands share rather than each keeping its own", the wording docs/README-lanes.md:301 has. The clause (h) reason after it, "four implementations of … the four would come to disagree", now reads "an implementation of … in each command … they would come to disagree", so the sentence holds no number.
• tests/test_lane_helpers.sh, the comment above the alias-read refusal: "the four commands that read canon-lane" → "the commands that read canon-lane".
• tests/test_repo_hygiene.py, the docstring of test_no_shipped_bash_opens_a_case_inside_a_command_substitution: "all twelve files already pass bash -n in CI, and the macOS job is the only place the defect exists" → "every file in ALL_BASH already passes bash -n under the Linux bash CI runs, and bash 3.2 is the only place the defect exists". ALL_BASH holds 14, and the macOS job the old sentence named was taken out of CI on 2026-10-15 (ci: run the test suite on Linux only #227).

Proof for 5f1c329, with every LANES_* and TMUX* variable unset: bash -n lane-end tests/test_lane_helpers.sh and py_compile tests/test_repo_hygiene.py are clean; tests/test_repo_hygiene.py gives 203 passed; command grep -n 'all four commands\|all twelve files' over the three files prints nothing. git merge-tree --write-tree --name-only of origin/main plus this commit against the heads of #202, #204, #205, #206, #208, #218, #220, #221 and #223 merges clean for each (#213 has landed on main).

The same clause, written out in three more places, is fixed too (7c4df04). Rewording lane-end's copy left the other three still counting, and the four copies would then have said two different things. Comments only; each file keeps its own markup, indentation and tense, and the lines are re-wrapped only where the shorter words moved them:

• lane (the Amendment 15 block above its canon-lane call): "four implementations of which row is this name's is how the four come to disagree about it" → "an implementation of which row is this name's in each command is how they come to disagree about it".
• lane-start (the "ONE RESOLVER, SHARED" comment): "four implementations of "which row is this name's" is how the four would come to disagree about it" → "an implementation of "which row is this name's" in each command is how they would come to disagree about it".
• lanes-edit.sh (the comment above the canon-lane) subcommand): the same clause, and "the amendment gives all four the SAME resolver" just before it, which counted the commands in the same sentence → "gives them all the SAME resolver" and "An implementation of "which row is this name's" in each command is how they would come to disagree about it".

Proof for 7c4df04, with every LANES_* and TMUX* variable unset: bash -n lane lane-start lanes-edit.sh is clean; command grep -in 'four implementations\|the four would\|the four come' over lane, lane-start, lanes-edit.sh and lane-end prints nothing; tests/test_repo_hygiene.py gives 203 passed. No test quotes the clause. git merge-tree --write-tree --name-only of origin/main (586dea2) plus this commit against the heads of every open PR that touches lane, lane-start or lanes-edit.sh (#204, #205, #206, #208, #210, #214, #218, #219, #220, #221, #223, #230, #246) merges clean for each. #222 conflicts with origin/main in tests/test_lane_helpers.sh lines 101-107 on its own, with or without this commit.

Remaining, not in scope here

• PR #50 round 5 (Copilot 5203628254): commit_push's recovery block leaves $LANES_REPO unquoted, git cherry unbounded for multi-commit checkouts, and git_timeout_die still push-shaped for a pull timeout #68 item 5, the die-message extraction in this same file, stays with PR #50 round 5 (Copilot 5203628254): commit_push's recovery block leaves $LANES_REPO unquoted, git cherry unbounded for multi-commit checkouts, and git_timeout_die still push-shaped for a pull timeout #68, whose other items wait for lane 4's lanes-edit.sh: a write with nothing staged still publishes the local commits origin lacks, so the RECOVERY's re-run of commit pushes the edit it stranded, and the conflict RECOVERY warns that reset --hard drops a peer's commits #214.
• specs/004-migrate-to-triad/installer-2026-10-08.md:125 still cites the old test name; it is a dated record, accurate when written, and off-limits here.

🤖 Generated with Claude Code

Summary by Sourcery

Correct shell command boundary handling in the hygiene checker and remove stale shipped-file counts from documentation and test prose.

Bug Fixes:

• Make the shell hygiene check correctly detect unsafe end-of-options usage when separators occur inside quoted strings or nested command substitutions.
• Prevent the hygiene check from reporting commands that exist only inside quoted text.

Enhancements:

• Add coverage for quoted separators, nested commands, multiline quotes, and valid end-of-options usage.
• Replace fragile file-count references in documentation, comments, and test names with descriptions that remain accurate as shipped files change.

Documentation:

• Update lane documentation to remove outdated command and installation artifact counts.

Tests:

• Expand repository hygiene tests with 14 cases covering quoted shell separators and false positives.

[sourcery-ai]

Reviewer's Guide

The PR fixes the hygiene check’s command parsing by tokenizing shell syntax with quote and nested-command awareness before splitting commands, preventing both missed BSD-incompatible calls and false findings inside quoted text. It adds focused regression tests, handles quote-spanning lines, and removes stale hard-coded Bash-file counts from comments and docstrings.

File-Level Changes

Change	Details	Files
Reworked shell-line parsing so end-of-options checks respect quoting, escaping, and nested command substitutions before splitting commands.	Added separator-aware tokenization that preserves separators inside single and double quotes while recognizing nested $() and backtick commands. Added command-stream splitting and alternate parsing for lines whose quoted runs span multiple lines. Updated the hygiene rule to evaluate parsed commands instead of regex-split line fragments. Added parametrized regression coverage for missed findings and false positives involving quoted separators and multiline quotes.	tests/test_repo_hygiene.py
Corrected documentation and comments that overstated the number or type of shipped Bash files.	Reworded Windows/PowerShell documentation to describe the absence of command twins without claiming all files are Bash. Replaced hard-coded Bash-file counts with wording applicable to the shipped scripts.	tests/test_repo_hygiene.py tests/conftest.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sourcery-ai]

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 2 days by commenting @sourcery-ai review. Upgrade to get a review now.