[brettheap]

What was wrong

Both defects are in skills/handoff/SKILL.md, and both were found by opensoft/workBenches' devcontainer.test/ when it vendored the file byte for byte.

#78: a block that does not parse. The late-recovery example printed a bare <profile>:

lane-handoff --late --at 2026-09-14T12:02:27Z "late; usage limit hit before the swap"
lclaude <profile>      # and only then; use pclaude --lane <lane> if lclaude is unavailable

Bash reads < and > as redirections whatever stands beside them, so a person who pasted the block got a parse error instead of a command. The command had been renamed from pclaude to lclaude and the bare placeholder carried through untouched, because nothing in this repository parsed a fenced example inside a SKILL.md (tests/test_repo_hygiene.py runs bash -n on the twelve top-level command files only). Measured on main f87fd5a, over every fenced sh/bash block in skills/*/SKILL.md:

skills/handoff/SKILL.md:755: syntax error near unexpected token `newline' -- in `lclaude <profile>      # and only then; ...` (the ```sh block that opens at line 753)

That is the only block of the 19 (12 in handoff, 7 in restart, none in lane-swap) that fails.

#79: a stale claim. Step 5's comment said "wherever a session comes up outside lane-start the operator's /rename <lane> is the only act there is". That was true until Amendment 12. Its name guard now types the rename itself into the session's own tmux pane: the SessionStart hook (lanes-edit.sh session-start, the clause (f) line in docs/README-lanes.md) and the UserPromptSubmit guard (lanes-edit.sh guard, guard_lock_rename and choice 3, via guard_type). The operator's /rename is the fallback.

What changed

• skills/handoff/SKILL.md:693: the late-recovery example prints a bare pclaude <profile> that fails to parse, unlike every other placeholder in the file #78: the block is now lclaude "${CLAUDE_PROFILE_NAME:-<profile>}" # and only then; ..., the spelling step 5 already uses for restart_cmd. Only the argument is quoted. The issue's own suggestion quotes the whole command, which would make bash look for a program literally named "pclaude ...".
• skills/handoff/SKILL.md: step 5's comment still calls /rename "the only act there is", unreconciled with Amendment 12's guard (pre-existing since 8a36eb3) #79: the sentence now says no API renames a running session from inside, but a keystroke is not an API, and the name guard sends it; it names the SessionStart hook and the UserPromptSubmit guard; the operator's /rename <lane> is the FALLBACK where the guard has not run or could not type (hooks not installed, a pane not running claude, tmux not answering). The "no API" half, which is still true, is kept. The printed echo line is unchanged, and the suite's pins on it (type /rename <lane>, 3719d97) still hold.
• tests/test_skill_shell_blocks.py (new): walks every skills/*/SKILL.md, runs bash -n on every fenced sh/bash/shell block (parse only, nothing is executed), and names the file, the line in the file and the text of any block that does not parse. A fence with no language, or one never closed, is a failure too, so a block cannot leave the check by losing its tag. Tagged non-shell blocks (text) are skipped. It is not in tests/test_repo_hygiene.py, which lane 1's Follow up #190's test roots: name a refused root's value, check the pin's commit, find paired feature worktrees, show redirected roots under -q, run the lane manual sections, and restate the installer-source test #195 owns.
• No receipt, checksum or generated copy is checked against SKILL.md: the installer's tests compare the installed bytes with this file, so nothing else needed updating.

Functions and regions edited:

• skills/handoff/SKILL.md: step 5's WHICH ACT REMOVES THIS LINE comment (about lines 645-652)
• skills/handoff/SKILL.md: the late-recovery sh block under lane-handoff --late --at <UTC> (about line 759)
• tests/test_skill_shell_blocks.py: new file: fenced_blocks, parse_problems, shipped_skills, and six tests

Not touched: lines 310-315 of the same SKILL.md and tests/test_handoff_skill_commit_block.py, which #199 edits.

Tests

Added tests/test_skill_shell_blocks.py, six tests:

• test_every_shell_block_in_every_skill_parses
• test_the_checker_is_not_blind_to_the_blocks_it_checks: handoff and restart each yield at least 5 shell blocks, and both tags appear
• test_the_checker_reports_the_defect_issue_78_filed_where_it_is: skills/handoff/SKILL.md:693: the late-recovery example prints a bare pclaude <profile> that fails to parse, unlike every other placeholder in the file #78's block as filed, in a synthetic document; the report names line 5, a text fence with the same characters is ignored, and the quoted spelling passes
• test_a_fence_with_no_language_and_a_fence_never_closed_are_refused
• test_a_fenced_example_inside_a_text_block_is_that_blocks_content
• test_the_handoff_skill_does_not_call_rename_the_only_act_there_is (skills/handoff/SKILL.md: step 5's comment still calls /rename "the only act there is", unreconciled with Amendment 12's guard (pre-existing since 8a36eb3) #79): no "only act there is" anywhere in the skill; step 5's comment names Amendment 12, SessionStart, UserPromptSubmit and FALLBACK, and keeps no API

Fail before, pass after, run as the one file only, not the suite (python3 -m pytest tests/test_skill_shell_blocks.py, scratch TMPDIR, lane seams unset):

• Before the fix (the test file against main's SKILL.md, commit 2c4b7a6): 2 failed, 4 passed. The two failures were test_every_shell_block_in_every_skill_parses (the :755 report above) and test_the_handoff_skill_does_not_call_rename_the_only_act_there_is.
• After the fix: 6 passed in 0.08s.
• Cross-check with a separate awk extractor and plain bash -n: fixed handoff 12 blocks, 0 failing; restart 7 blocks, 0 failing; main f87fd5a handoff 12 blocks, 1 failing (the block opening at line 753).

The full suite was not run locally (CI's tests job is the record).

Closes #78
Closes #79

🤖 Generated with Claude Code

Summary by Sourcery

Ensure shipped skill examples remain copy-pasteable shell and keep handoff rename guidance aligned with the current session name guards.

Bug Fixes:

• Fix the late-recovery handoff example so its shell command parses correctly when copied.
• Correct the handoff guidance to describe the session name guard as the usual rename mechanism and operator renaming as the fallback.

Enhancements:

• Add validation for all fenced shell examples in shipped skill documents, including diagnostics for missing language tags and unterminated fences.

Documentation:

• Update handoff skill guidance to reflect Amendment 12's SessionStart and UserPromptSubmit rename guards.

Tests:

• Add tests covering shell-block discovery, Bash parsing, diagnostic locations, fence handling, and the corrected handoff rename guidance.

[sourcery-ai]

Reviewer's Guide

The PR fixes the malformed late-recovery shell example, corrects stale rename guidance to reflect Amendment 12’s automatic name guard, and adds focused regression coverage that parses every fenced shell block in shipped skills.

Sequence diagram for automatic session rename with fallback

sequenceDiagram
    participant Session as Claude session
    participant Hook as SessionStart hook
    participant Guard as UserPromptSubmit guard
    participant Tmux as Session tmux pane
    participant Operator

    Hook->>Guard: lanes-edit.sh guard
    Guard->>Tmux: guard_type /rename <lane>
    Tmux->>Session: type rename command
    alt guard cannot run or type
        Operator->>Session: /rename <lane>
    end

Loading

Flow diagram for shell block validation

flowchart TD
    Skills["skills/*/SKILL.md"] --> Extract[fenced_blocks]
    Extract --> Tagged{sh/bash/shell fence?}
    Tagged -->|yes| Parse[parse_problems]
    Tagged -->|no| Skip[skip tagged non-shell block]
    Parse --> Bash[bash -n]
    Bash --> Result{parses?}
    Result -->|yes| Pass[validation passes]
    Result -->|no| Report[report file, line, and block text]

Loading

File-Level Changes

Change	Details	Files
Fix the handoff skill’s late-recovery command example so every shipped shell block is syntactically valid.	Quote the profile expansion while preserving the placeholder fallback. Add coverage that extracts all fenced shell blocks from every skill and validates them with bash -n. Report malformed, untagged, and unterminated fences with source file and line context while ignoring explicitly non-shell fences. Add regression tests covering the original malformed example and fence parsing behavior.	skills/handoff/SKILL.md tests/test_skill_shell_blocks.py
Update the handoff documentation to describe the name guard as the normal rename mechanism and operator input as fallback behavior.	Clarify that SessionStart and UserPromptSubmit guards type /rename into the session pane. Retain the distinction that no API renames a running session from inside. Document fallback cases such as missing hooks, non-Claude panes, or unavailable tmux. Add assertions preventing the stale “only act there is” claim and requiring the relevant guard terminology.	skills/handoff/SKILL.md tests/test_skill_shell_blocks.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#78	Make the late-recovery shell example parse successfully by avoiding a bare placeholder in the command.	✅
#79	Update step 5 of skills/handoff/SKILL.md so it no longer claims the operator's /rename <lane> is the only act, and accurately explains that Amendment 12's SessionStart and UserPromptSubmit guards type the rename while the operator's command is a fallback.	✅

Possibly linked issues

• #?: The PR updates step 5 to name the SessionStart and UserPromptSubmit guards and describe operator /rename as the fallback.
• skills/handoff/SKILL.md:693: the late-recovery example prints a bare pclaude <profile> that fails to parse, unlike every other placeholder in the file #78: The PR quotes the profile placeholder in the late-recovery command and adds tests to catch unparsable skill shell blocks.

---

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.

[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 3 hours and 15 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Sourcery assessment

Approved.

[sonarqubecloud]

Quality Gate passed

Issues
2 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