Add a README Documenting the Linux Host-Setup Nuances - #710
Merged
Conversation
The windows/ tooling has a README documenting its platform nuances while linux/ has none, and the host-setup README stays platform-agnostic by design. Document the Linux-side decisions: the three kinds of source, keyring proving, PATH shadowing, report semantics, the docker/node/dotnet gotchas, release-upgrade guards, WSL restarts, the GitHub setup gates, and the install-skills fetchability exception. Add the new technical terms to cspell.json.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds Linux-specific host-setup documentation to mirror the existing Windows host-setup README, capturing the rationale and operational semantics of the Linux scripts without duplicating the cross-platform comparison table.
Changes:
- Add
host-setup/linux/README.mddescribing the Linux host-setup scripts, their sourcing/verification model, PATH shadowing behavior, report semantics, release-upgrade guards, and verification workflow. - Update
cspell.jsonto include newly introduced Linux/apt-related technical terms used by the new documentation.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| host-setup/linux/README.md | New Linux-focused README documenting the intent and behavior of the Linux host-setup scripts and how they satisfy the host-setup contract. |
| cspell.json | Adds dictionary entries for new terms introduced by the Linux README to keep spell-checking clean. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
ptr727
added a commit
that referenced
this pull request
Aug 14, 2026
A peer session working in this same shared checkout (not an isolated worktree) was concurrently authoring host-setup/linux/README.md and adding words to cspell.json for it. My 'git add -A' in 0553d34 and 21aec10 staged and committed that in-progress content alongside my own signing-check work, entirely by accident: neither commit message mentions it, because I never intended to write it and did not notice it was staged. This also means my claim in c3127fe, that the file's dead-path finding was 'pre-existing drift, not caused by this branch', was wrong. The file never existed on develop at all; it was the peer's uncommitted draft, and my 'fix' to its stale test_bootstrap.py reference was a fix to content I should never have carried in the first place. Correction: removed host-setup/linux/README.md entirely (the peer has re-landed it cleanly on their own branch as PR #710) and reverted cspell.json to develop's content plus only the one word my own content actually needs (keyring), dropping the other seven the peer's README required. Diff against origin/develop now touches exactly the four files this PR's signing-check work owns.
ptr727
added a commit
that referenced
this pull request
Aug 14, 2026
Resolves the cspell.json conflict predicted by the peer session that authored #710: both branches added a word at the same position (mine 'keyring', develop's 'keyrings'). Resolved to develop's side per that prediction, which already superseded everything else this branch had independently added to cspell.json earlier. Ran the full local gate set post-merge: test_prose_lint.py, test_repo_gate.py, test_pr_review.py, spec/audit.py --selftest, gh-write-guard.py --selftest, repo_gate.py, prose_lint's full-tree CI invocation, and both docker linters. All green.
ptr727
added a commit
that referenced
this pull request
Aug 15, 2026
…Python CI Gates (#718) Thirty-one squashes, `56f4d7d..d54862a`. 115 files, +20436/-5298. **Merge with a merge commit, never a squash, and never with `--delete-branch`.** This pull request's head is `develop` itself. ## What lands **Fleet Skills.** The `.agents/skills/` source tree, the generated `.claude-plugin/` distribution, `scripts/build_dist.py` with its `--check` gate, and `scripts/skills_install.py` with its host stamp (#676). Packaged as skills on top of the scaffold: PR review conduct and Copilot instructions upkeep (#677), comment and doc style (#678), resync-a-repo and fleet-conformance-check (#679), the per-language codestyles (#680), git commit conventions and operational vs release workflow (#681), stand up a repo (#683), and repo-worktree (#717). Coverage gaps closed in three passes (#690, #691, #692) plus the P4 sentence-length opt-in (#697). **Host setup.** The Windows host-setup tooling and its PowerShell gate (#674), the Windows bootstrap loader (#682), Docker install and upgrade on Linux and Windows with a version floor (#701, #705), a `uv` floor in `spec/host-tools.json` (#698), self-healing of a shadowing `uv`, `jq`, or `git-restore-mtime` copy (#689), node's real winget package id (#696), and a README for the Linux host-setup nuances (#710). **Python and CI.** Python tooling in CI with the script tests moved to `scripts/tests` (#704), `ruff format` adopted and gated (#709), and the PSScriptAnalyzer claim conditioned on repos that carry `.ps1` files (#686). **Conduct rules.** Triage-order and scope guardrails in pr-review-conduct (#684), `pr_review.py wait` requesting a review rather than only polling for one (#685), a tech-agnostic signed-commit verification (#708), execution rather than analogy to verify platform-specific code (#715), and a unique worktree for every task (#717). **Docs.** The fleet map and gap register with peer messaging declared (#687), mermaid flow diagrams in the kept-authority docs (#702), and the map pointed at the shipped diagrams and current tooling (#703). ## Issues this promotion closes Each landed on `develop` on its own pull request. The keyword fires only on a merge into `main`, so it sits here rather than on the feature pull requests. Closes #700 Closes #707 Closes #711 Closes #712 Closes #714 Closes #688 #699 stays open on purpose: #717 shipped the layout convention and the skill, and the physical migration of existing checkouts is still tracked there. ## Review record Every squash closed its own Copilot loop on its own pull request before merging to `develop`. This promotion carries no new content of its own, so its review is the merged tree as a whole. ## Consequence worth stating The `GOVERNANCE.md` and `AGENTS.md` sections these squashes changed become the canonical the moment this reaches `main`, and every carrying repository reads as drifted from that point until it resyncs. That is the ordinary consequence of a canonical moving rather than a defect. The Skills installer added here is also how a machine picks the new skills up, so a session that keeps restating a rule already packaged as a skill is the signal to run it.
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.
Summary
The
host-setup/windows/directory carries a README documenting the Windows-specific nuances, whilehost-setup/linux/carries none, and the top-levelhost-setup/README.mdstays platform-agnostic by design. This adds the missing Linux counterpart.The new
host-setup/linux/README.mddocuments the decisions the four Linux scripts embody:gpgvcheck and sha256 verification.jqand the dpkg-owned-file exception.unmanagedmeans here versus on Windows, docker read from the CLI, and failures-collected versus refusals-fatal.nodedisplacing distro packages, and the dotnet feed-mixing rule.setup-github.shbrowser gates and read-only--status, and theinstall-skills.shfetchability exception.--dry-run.The comparison table stays in the Windows README, referenced rather than duplicated, so the two columns cannot drift.
cspell.jsongains the new technical terms the README uses.Verification
prose_lint.pyclean on the default checks, and the opt-insentence-lengthcheck reports zero findings.markdownlint-cli2,cspell, andeditorconfig-checkerclean.scripts/tests/test_bootstrap.py,scripts/tests/test_host_gate.py, andrepo_gate.pypass.develop, including the relocatedscripts/tests/test_bootstrap.py.🤖 Generated with Claude Code