Prefix the PowerShell invocation, and name the interpreter per platform - #484
Merged
Conversation
Two corrections from the #483 Windows and WSL2 testing, both of which disproved something the merged contract asserted. The PowerShell installer invocation needs the .\ prefix. PowerShell does not load a command from a relative path without it, and warns that it does not assume the current location. I declined this during the #482 review, arguing that a multi-segment path resolves where a bare filename does not, and flagged that I could not run PowerShell to check. The maintainer's direct experience is that both the current-directory and the subdirectory form need either .\ or an absolute path. Both files that carry the line are corrected, since docs/host-setup.md and the kit README shipped the same unprefixed form. The interpreter is not called python3 everywhere, so the contract's presence check was wrong on the platform it most needed to be right about. On native Windows the installer registers python, py and python3.13 but not python3, where that name resolves to a Microsoft Store alias stub that reports the interpreter as missing. A correctly set-up Windows host therefore failed the check and read as broken. Stock Debian is the mirror image, carrying python3 and no bare python. The row now names py -3 for native Windows, and the prose states the split and why a cross-platform script should still prefer python3. Three other findings from that testing are deliberately not carried here. Docker Desktop performs the WSL2 enabling itself and exposes the per-distro integration toggle the matrix already documents. The WSL interop credential helper failure was an upstream bug since fixed, so the durable part is only that Docker Desktop must be quit rather than paused before wsl --update. And the /mnt/c permission behavior does not apply to a workflow that treats WSL2 as an ordinary Debian host and never cross-shares files. The kit README's dash backlog is cleared, per the corrected-as-next-edited rule. It is hub-only, so no re-vendor debt. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the host-setup contract documentation to reflect two Windows-specific realities discovered during #483 testing: PowerShell requires .\ to run scripts from a relative path, and the Python 3 interpreter is not consistently named python3 on native Windows.
Changes:
- Fix Windows PowerShell invocation examples to use the required
.\prefix. - Update the host contract to describe Python 3 interpreter name differences (
python3vspy -3) and why cross-platform scripts should still preferpython3. - Clean up punctuation/wording in the write-safety kit README while making the Windows invocation explicit.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| host-setup/agent-safety/README.md | Corrects the Windows install command example to use .\ and refines related prose. |
| docs/host-setup.md | Updates the host tooling contract to account for Windows/POSIX differences in PowerShell invocation and Python interpreter naming. |
The consolidated verify block still ran python3 --version, the one name this same PR establishes a correctly set-up Windows host does not have, so the block contradicted the contract table a few sections above it and would report a healthy machine as broken. The caveat now sits under the block: read the interpreter line as py -3 on native Windows, and note that Git Bash inherits the Windows PATH, so python3 reaches the same Store alias stub there as in PowerShell. That case is not obvious, since the shell note already sends Windows readers to WSL2 or Git Bash and only WSL2 shadows the stub. A PowerShell equivalent of the block is deliberately not written. It has not been run on a Windows host, and this PR exists because an unverified PowerShell invocation shipped and was wrong. #483 is where a verified one belongs, under its rule that a cell is filled only by someone who has run it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ptr727
added a commit
that referenced
this pull request
Aug 1, 2026
Forward promotion of five commits. `main` carries no content beyond the merge-base (`8771e62`, #478), so this is a clean forward merge with no conflicts. **This one has a consumer waiting.** The Blog standup (#456) is mid-correction and has been told to carry its instruction set from `main`, because `main` is the audit ground truth. Every fix for the failure it just hit is currently on `develop` only: `main`'s `STANDUP.md` still begins at "1. Classify and Catalog", with no step 0 and no step 1A, and `main` does not yet require `OPERATIONS.md`. Until this promotes, a repo following the corrected instructions re-runs the uncorrected procedure. ## What promotes - **#480 - Name where repo-specific content goes.** `STANDUP.md` step 2 named no destination for content that is not a carried file. The three destinations existed only in `spec/section-model.md`, which nothing on the scaffolding path pointed at. - **#481 - Verify commit identity before the first commit, and require `OPERATIONS.md`.** Step 0 verifies identity and signing before `git init`, framed **verify, never set**, because the host carries the identity globally and a repo-local override shadows it silently. `OPERATIONS.md` becomes required for an `operational` repo, presence-checked like `README.md`. - **#482 - State what a host must provide.** The tooling contract, naming no installer so it stays true on every platform, plus a route to the write-safety kit which the host-setup document never referenced. - **#484 - Prefix the PowerShell invocation, and name the interpreter per platform.** Both corrections came from real Windows and WSL2 testing in #483 and disproved something #482 asserted. - **#485 - Require the instruction set before any authoring.** Step 1A, the direct fix for the Blog failure. ## Verification on the merged `develop` The full 180-case `scripts/` suite, `scripts/repo_gate.py`, `spec/validate.py` and `spec/audit.py --selftest` all pass. The blocking prose run (charset, dupword, spelling) is clean tree-wide, markdownlint reports 0 issues over 39 files, and editorconfig-checker is clean. ## Release A human merge never auto-publishes, so this fires no release, as designed. The latest release stays `2.0.108`. ## Re-vendor debt #481 changed `GOVERNANCE.md` "Git and Commit Rules", a `verbatim` section, so this promotion re-vendors it across the fleet. That was accepted deliberately when the change was made. The debt is pre-existing and still untracked, and `spec/audit.py --branch <ref>` checks a repo's convergence before it promotes. ## Known backlog, not in this promotion The hub's own `.editorconfig`, `.gitattributes` and `.gitignore` carry 44 comment-shape findings, which downstream repos inherit by copying them and reading them for house style. #485 works around it by telling agents to trust the rule text over a carried file's formatting. Cleaning those three files is owed and deliberately separate. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two corrections from the #483 Windows and WSL2 testing. Both disproved something the contract merged in #482 asserted, which is the matrix working as intended.
1. The PowerShell invocation needs
.\PowerShell does not load a command from a relative path without the prefix, and warns that it does not assume the current location.
I declined this during the #482 review and was wrong. My argument was that a multi-segment path resolves where a bare filename does not, and I flagged explicitly that I could not run PowerShell to verify it. The maintainer's direct experience is that both forms need either
.\or an absolute path. Worth noting the Windows column of #483 was filled by an agent, so the documented invocation itself was never exercised, only the tool installs around it.Both files carried the same unprefixed line, so both are corrected:
docs/host-setup.mdandhost-setup/agent-safety/README.md.2. The interpreter is not called
python3everywhereThe contract's presence check was wrong on the platform it most needed to be right about. From the #483 Windows notes: the winget package registers
python,pyandpython3.13but notpython3, and on a default box that name resolves to a Microsoft Store alias stub that errors with the interpreter missing (exit 9009).So a correctly set-up Windows host failed the
python3 --versioncheck and read as broken — the same false-negative shape that has bitten repeatedly in this doc's history, where a verification step reports a healthy machine as faulty and routes a non-problem to the maintainer.Stock Debian is the mirror image, carrying
python3and no barepython(#483 WSL2 note 4). The row now readspython3 --version, orpy -3 --versionon native Windows, and the prose states the split plus why a cross-platform script should still preferpython3, since WSL2 shadows the Windows stub.Deliberately not carried
Three findings from the same testing that I raised as candidates and the maintainer ruled out, recorded so they are not re-proposed:
dockergroup and context on WSL2 — Docker Desktop performs the WSL2 enabling itself, and the per-distro integration toggle is already the matrix cell.wsl --update, already captured in Per-host-type tooling install matrix (implements the host-setup contract) #483./mnt/cpermissions — does not apply to a workflow that treats WSL2 as an ordinary Debian host and never cross-shares files.Also
The kit README's dash backlog (8 findings) is cleared, per the corrected-as-next-edited rule. It is hub-only, so no re-vendor debt.
Verification
markdownlint over 39 files, editorconfig-checker, the 180-case suite, and all prose rules on both edited files are clean. The diff is 14 insertions and 12 deletions with line endings intact, checked against the committed blobs rather than assumed.