Repository navigation
Require Orderly SIGINT and SIGTERM Handling in Shell and Python Scripts - #4078
Conversation
Add an "Interrupts" rule to CODESTYLE.md General, with the Python and Shell mechanics in their own sections, per the maintainer's answer on the issue. The python-codestyle and shell-codestyle skills carry the sections as generated includes. The shell mechanics are the last section of CODESTYLE.md, which exposed a generator defect: an include of a file's last heading also copied the file's trailing link-reference definitions. build_dist.py now ends such a body before them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Send SIGTERM to a shell script's children and wait for them, since a background child ignores SIGINT. Every shell script sets both traps, so one with no children still prints the line and keeps the status. A Python script exits 130 unless its SIGTERM handler recorded a signal, and waits for a terminated Popen child. Drop the generator's marker and code-block branches, which no case reaches, and state the end-of-file case in heading_body's docstring. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Discard the trap's kill and wait statuses so errexit cannot end it before the signal line prints, give a stdin-reading background child its input with <&0, let a lower Python handler re-raise rather than forbidding it, and name os.replace for the rename. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
A recorded local strict-review pass covers head |
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the
|
Name Bash rather than shell, so a PowerShell script is not read as owing the rule. Skip the signal-mid-run test on Windows, which cannot deliver either signal for a script to handle. Say a script with no children skips the trap's kill and wait, and quiet kill for a child that already exited so the trap prints one line. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
🟡 Changes recommended
Approval is blocked by an active moderate issue in trailing link-definition extraction, along with unresolved documentation and cross-platform edge cases.
4 open issues
What changed in this PR
This PR adds orderly SIGINT and SIGTERM handling requirements for Bash and Python scripts, updates the canonical coding guidance and generated Skills, and fixes trailing link-reference extraction in the Skill generator.
Changes:
- Adds general, Python-specific, and Bash-specific interrupt-handling rules.
- Regenerates authored and distributed Skills with updated guidance and source digests.
- Prevents trailing link-reference definitions from being copied into generated regions, with regression tests.
| File | Description |
|---|---|
| tests/test_build_dist.py | Adds regression tests for trimming trailing link definitions and preserving unrelated trailing comments. |
| scripts/build_dist.py | Updates region extraction to exclude trailing document-level link definitions from generated sections. |
| CODESTYLE.md | Defines general, Python, and Bash interrupt-handling requirements. |
| .github/skills/shell-codestyle/SKILL.md | Regenerates the GitHub Copilot shell-codestyle Skill with interrupt guidance. |
| .github/skills/python-codestyle/SKILL.md | Regenerates the GitHub Copilot python-codestyle Skill with interrupt guidance. |
| .claude-plugin/fleet-skills/skills/shell-codestyle/SKILL.md | Regenerates the Claude shell-codestyle Skill with interrupt guidance. |
| .claude-plugin/fleet-skills/skills/python-codestyle/SKILL.md | Regenerates the Claude python-codestyle Skill with interrupt guidance. |
| .claude-plugin/fleet-skills/.source-digests/shell-codestyle | Updates the source digest for the shell-codestyle Skill. |
| .claude-plugin/fleet-skills/.source-digests/python-codestyle | Updates the source digest for the python-codestyle Skill. |
| .agents/skills/shell-codestyle/SKILL.md | Updates the authored shell-codestyle Skill with interrupt guidance. |
| .agents/skills/python-codestyle/SKILL.md | Updates the authored python-codestyle Skill with interrupt guidance. |
Review effort: Lite
A signal arriving before the first child starts would otherwise expand an unset variable inside the trap, which nounset turns into an exit before the signal line prints. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #4078 +/- ##
===========================================
- Coverage 82.34% 82.30% -0.05%
===========================================
Files 38 38
Lines 12951 12961 +10
===========================================
+ Hits 10664 10667 +3
- Misses 2287 2294 +7
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
An emptiness test that expands an empty array is an unbound-variable error under set -u on Bash before 4.4, while a count is not. A bare wait returns 0 whatever the child's status, so name the ID it waits on. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
A recorded local strict-review pass covers head |
A background function, group, or subshell is a Bash subshell, and a SIGTERM to it leaves its own command running. A Popen child under shell=True has the same gap, so run it without the shell. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
State the rule by the property: a shell running other commands, sh -c and a pipeline included, runs in the foreground, where the trap waits for it rather than orphaning its commands. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A backgrounded pipeline has no shell around it, but the trap's kill still reaches only the process $! names, so that is the reason stated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
A recorded local strict-review pass covers head |
A function or a group runs in the script's own shell, so the trap runs once the command it interrupted returns rather than after every command in it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A subshell or a pipeline element resets caught traps, so a child it backgrounds is one no trap stops. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The child misses the script's process ID array and its wait, which is what fails on a SIGTERM sent to the script alone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
A recorded local strict-review pass covers head |
…s Rule, Companion-Free Lint, Root hub_fetch_run, .codecov.yml (#4083) ## Summary Promotes burndown round 3 of the attended run of 2026-11-10, together with two pull requests from other hub sessions, from `develop` to `main`. - #4082: `configure.sh apply` refuses a repository the registry does not list, before any write. A repository whose entry is on `develop` but not yet on `main` is configured and audited from a hub checkout at `develop`. `OPERATIONS.md`, `AUDIT.md`, `GOVERNANCE.md` "Hub-Hosted Tooling", and the standup, audit, and branch-protection skill text now say so. - #4081: `WORKFLOW.md`'s contradictory trigger, merge, and release rules are reconciled. D1.5 requires a gate to trigger on `pull_request`, and the audit reports a gate that does not. A retarget is cleared by a push or a close and reopen. - #4078: `CODESTYLE.md` gains an Interrupts rule with Python and Shell mechanics. `build_dist.py` no longer carries a file's trailing link definitions into an include of its last heading. - #4076: `docker_lint.py` imports only the standard library, so the Lint tasks fetch no companions. The provenance label and the ruff task labels are corrected. `GOVERNANCE.md` "Repo-Scoped Secrets" states the owner-first host secret stem. - #4080, from another session: `hub_fetch_run.py` lives in the repository root for both hook shapes. - #4077, from another session: only `.codecov.yml` is accepted as the Codecov configuration name. Fixes #4061 Fixes #4011 Fixes #4051 Fixes #4048 Fixes #4060 Fixes #3947 Fixes #4072 Fixes #3915 Fixes #4059 Fixes #4071 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> <!-- coderabbit-ai-generated:v1 --> ## Summary by CodeRabbit * **Documentation** * Clarified when repository checks and configuration use the `develop` branch, and documented that configuration changes are not applied to unregistered repositories. * Expanded scripting guidance for handling interruptions, cleaning up resources, and saving persistent state safely. * Updated workflow, coverage, and hook setup guidance to reflect current requirements and locations. * **Bug Fixes** * Audits now check only the declared baseline filename; repositories using a different filename are reported as missing. * Markdown heading extraction no longer includes trailing link definitions in the heading body. <!-- end of auto-generated comment: release notes by coderabbit.ai -->


Summary
Adds the narrowed SIGINT and SIGTERM rule the maintainer chose on #3947 (option 1, answered 2026-11-10).
CODESTYLE.mdGeneral gains an "Interrupts" subsection after "Operations and Failure Messages". A Bash or Python script releases its temporary paths, locks, and child processes on SIGINT or SIGTERM. It writes persistent state through a temporary path and a rename. It prints one line naming the signal, with no traceback, and exits 130 or 143. The rule applies when a script is created or next edited, with no retrofit sweep. Only a script holding a lock, temporary state, or a child process owes a test that signals it mid-run, and that test is skipped on Windows.CODESTYLE.mdPython gains "Interrupts in Python": a SIGTERM handler maps the signal ontoKeyboardInterrupt, and the entry point catches that exception once.CODESTYLE.mdShell gains "Interrupts in Shell": cleanup runs in theEXITtrap, and theINTandTERMtraps stop children and keep the status.python-codestyleandshell-codestyleskills carry these sections as generated includes, regenerated withscripts/build_dist.py. Each skill's description names the rule, and python-codestyle's stays within the 1024-character limit.Mechanics stated for the answer's rules
These implement the answer's rules rather than adding new ones. They are listed so reviewers can check them:
INTandTERMtraps, and they also print the signal line. A trap is the only place a shell script knows which signal ended it, and without one a childless script would print nothing.|| :on both and2>/dev/nullonkill. The children's process IDs sit in an array set to()before the traps, and the trap skips both while${#pids[@]}is 0. On Bash 3.2 underset -u, a constructed check showed that count works on an empty array while${pids[*]}fails. A background child ignores SIGINT. Underset -eu, a failedkillorwait, or an unset variable, would end the trap before the line prints.wait "$pid", so its status still reachesset -e, with<&0when it reads standard input. The trap'skillreaches only the process$!names. So a function, a group, a subshell, a pipeline, orsh -cruns in the foreground, where the trap runs once the interrupted command returns. Only the script's own shell starts a background child, so the child reaches the script's array and itswait. Bash runs a trap only after a foreground command returns, while a trapped signal ends awaitat once.subprocess.Popenchild runs withoutshell=Trueand is terminated and waited for in afinallyclause, since leaving itswithblock does not stop it. A lower Python handler that catchesKeyboardInterruptre-raises it. The rename usesos.replace, sinceos.renamefails on Windows when the target exists.Generator fix (pre-existing defect this change exposes)
"Interrupts in Shell" is the last heading in
CODESTYLE.md. An include of a file's last heading also copied that file's trailing link-reference definitions into the skill, which failed markdownlint MD053 in every copy. This is apre-existingdefect inscripts/build_dist.py, fixed here because this change needs it. A body that runs to the end of its file now ends before those trailing definitions and their grouping comments. Nothing else about region extraction changes.tests/test_build_dist.pyadds a test that fails ondevelopand passes here, plus a guard showing that a trailing comment with no definitions after it is kept.Verification
scripts/build_dist.py --check: current.tests/test_build_dist.py: all tests pass. The new trailing-definitions test fails againstdevelop's generator.--diff origin/develop), repo gate, ruff, and the Docker markdownlint and editorconfig-checker runs: all clean.EXITtrap runs when SIGINT or SIGTERM ends the script. A background child outlives the script unless anINTorTERMtrap stops it. With the stated trap, SIGINT exits 130 and SIGTERM exits 143, each printing its line and leaving no child running.Declined local-pass findings
scripts/build_dist.py,introduced: a pass read "A script takes this rule when it is created or next edited" as binding this script now, since this pull request edits it. Declined. The rule binds an edit made after it is ondevelop, and this pull request is the one that lands it. The maintainer's answer also rules out a retrofit sweep. So the script's next edit owes the rule, and the generator fix here stays limited to ending a body before the trailing definitions..agents/skills/skill-lifecycle/SKILL.mdline 28,introduced: a pass called its account of where an include body ends stale. Declined. It describes a body that ends at a heading, which is unchanged, andheading_body's docstring now states the end-of-file case.CODESTYLE.md"Interrupts in Shell" and "Interrupts in Python",introduced: a pass noted that an external command which starts children of its own and does not pass SIGTERM on, such asfind -exec, leaves those children running. Declined. The decision names the children the script started, and a command's own children are that command's to stop.spec/fidelity_text.py,introduceddesign finding: a pass suggested taking definition extents from the parser token's line map. Declined. The scan reuseslink_definitionsfor where each definition starts. The only shape it misreads is a paragraph line directly after a trailing definition, which this repository's Markdown never has.Closes on promotion: #3947
🤖 Generated with Claude Code