Run the VS Code Lint Tasks Through docker_lint.py and Name No Dead Path in Editor and Tasks - #4069

Summary

Answers #1147 and #4049.

Closes on promotion: #1147, #4049

#1147: one rule for lint containers

Before this change, the four Docker Lint tasks in catalog/snippets/configs/vscode-tasks.json and vscode-tasks-python.json bound the live checkout, writable and with networking, into :latest images. Each now runs scripts/docker_lint.py --linter <name> through the carried hub_fetch_run.py. Each task therefore gets the wrapper's snapshot of tracked and unignored files, its read-only mount, and its disabled networking. The .NET snippet keeps its Windows py -3 override. The Python snippet keeps its uv run --no-project python form.

hub_fetch_run.py changes in two ways:

• COMPANIONS gains scripts/docker_lint.py's companions. One is scripts/local_review.py, which the wrapper imports. The other is spec/git_env.py, which local_review.py imports through a sys.path entry computed from its own location.
• A script with companions now has main's commit resolved, has every file fetched from that commit, and prints the commit on stderr. So a Lint task run names the hub commit it ran from, as "Hub-Hosted Tooling" requires of a hub tool's result. The prose gate keeps its own provenance variable. repo_gate.py, which the commit hook runs, still makes no lookup.
• Each fetched file now keeps its hub-relative path inside the scratch directory. The old flat layout put that sys.path entry at the parent of the scratch directory, which is the shared temporary root. A spec/git_env.py planted there would then be imported, and the companion that should have been read would never be found.

GOVERNANCE.md "Running the Linters Locally" now says the four tasks run the wrapper. RESYNC.md step 6 now names the Lint group rather than lint-task images, and copies the current hook helper in the same commit. Without that copy, a carrier's older helper fetches docker_lint.py without its companions, and the import fails. comment-and-doc-style loses two clauses that had nothing left to follow. One covered a repository shipping no HISTORY.md, but every repository carries one (spec/files.json). The other let a repository widen its own CI spelling list, but that list belongs to the hub's reusable validate-task.yml, which takes no spelling input. Both pointed at the Lint: Spelling task's file list, which no longer exists. Its generated copies are regenerated.

A terminated Lint task no longer leaves a snapshot behind

Now that the tasks run the wrapper, cancelling one is an ordinary way for a run to end. On Linux and macOS, closing the task's terminal sends SIGHUP. scripts/docker_lint.py now handles it the way it already handled SIGTERM, so the snapshot is removed. On Windows the process tree is killed outright, and no handler runs. So each run now holds a lock on an owner file beside its snapshot, docker-lint-snapshot-<id>.owner. The run writes that file only after it takes the lock. At the start of its execution phase, a later run removes a snapshot only when it can lock the owner file and the file is not empty. The OS releases the lock only when the holding process is gone, so a concurrent run's snapshot is never removed. A process id would not prove that, because ids get reused. A snapshot directory with no owner file, such as one left before this change, is never touched. The sweep runs on every platform. A Linux or macOS run killed with SIGKILL leaves its snapshot behind just as a Windows run does.

#4049: no literal path in "Editor and Tasks"

The sentence about the Python Environments extension now says "that folder's settings.json". So the dead-path rule no longer reads a path in it. As the maintainer answered, hub_hosted does not grow.

Local Review Notes

Two local passes raised the same design point. I declined it. The import closure of docker_lint.py is declared in each carrier's copy of COMPANIONS, so a later hub-side import needs a re-copied helper. That coupling is the design the maintainer chose on #1147 (option 1, "with local_review.py added to hub_fetch_run.py's companions"). It is also how the prose gate already pairs with prose-gate.json. The step 6 instance it exposed is fixed above.

The third local pass found that commit attribution is keyed on the script having companions. So repo_gate.py, behind Lint: EOL and the commit hook's EOL check, still fetches bare main and names no commit. I declined extending it here. Naming a commit there needs a lookup, and GOVERNANCE.md "Running the Linters Locally" limits the commit hook's network calls to the prose gate's single commit lookup. Printing @main would name no commit, so it would not meet the rule either. The gap predates this change, and it is listed below.

A later pass found that remove_snapshot passes shutil.rmtree(onexc=...), which needs Python 3.12. I declined it. host-tools.json sets the fleet's python3 floor at 3.13, and its entry says "Neither is evidence that spec/ or scripts/ code should hedge for anything older than 3.13". scripts/local_review.py, which this same wrapper imports, already calls rmtree(onexc=...).

Pre-existing findings, not filed

• catalog/snippets/hub_fetch_run.py main(), the repo_gate.py route (Lint: EOL and the commit hook's EOL check): the run names no hub commit, contrary to GOVERNANCE.md "Hub-Hosted Tooling". Class: pre-existing, contract drift.

Verification

• tests/test_hub_fetch_run.py gains eight tests: two over the task snippets, and six that run the hub's real docker_lint.py --help from the scratch directory the helper builds. With the fix reverted, all eight fail. Reverting only the commit pinning fails the six fetch tests. Two mutations fail them separately: the flat layout fails the planted-module test, and a missing spec/git_env.py companion fails four.
• tests/test_docker_lint.py gains seven tests: the SIGHUP registration, a sweep of an ended run's snapshot, a snapshot whose run still holds its lock, an owner file not yet written, a snapshot with no owner file, a clean run leaving nothing, and a cross-process run. That last one is kept while alive and removed once killed. Reverting the SIGHUP line fails the SIGHUP test, and disabling the sweep fails the sweep test. The msvcrt branch runs in this repository's Windows unit-test job.
• test_hub_fetch_run and test_cli_usage pass under the runner OPERATIONS.md names.
• An end-to-end run with real uv and Docker used a constructed repository holding a git-ignored file. The wrapper's editorconfig-checker task staged only the tracked paths and passed.
• Dead-path reproduction: a constructed repository commits .vscode/settings.json and then deletes it. prose_lint.py reports dead-path on develop's "Editor and Tasks" text, and reports nothing on this branch's text.
• scripts/build_dist.py --check reports the generated trees current.

🤖 Generated with Claude Code