CODESTYLE.md Mandates Python for Every Program While the Hub Itself Ships Nine PowerShell Ones

[ptr727]

Three defects in CODESTYLE.md's language coverage, grouped because settling the first decides the other two. Surfaced by the canonical-content review pass on the PR for #1075/#1120, which reads each unit whole as a carrier does. Deferred out of that PR because the first is a scope decision rather than a text fix.

CODESTYLE.md is carried at intent, whole file.

1. "Everything else is Python" is falsified by the authoring repo

CODESTYLE.md "Shell" states:

Bash, and only where a program cannot be Python: a bootstrap that installs the interpreter cannot be written in it, and a host tool that must run before a development toolchain exists cannot depend on one. Everything else is Python, with a test under the scripts tree's tests/ directory.

The hub tracks nine PowerShell programs, none of them Bash and none of them Python:

$ git ls-files '*.ps1' | head
host-setup/bootstrap.ps1
host-setup/menu.ps1
host-setup/windows/install-tools.ps1
scripts/skills_install.ps1

The fleet lint gate explicitly provides for them: GOVERNANCE.md "Running the Linters Locally" says "for a repo that carries .ps1 files, PSScriptAnalyzer", and PSScriptAnalyzerSettings.psd1 sits at the repo root. CODESTYLE.md has no PowerShell section, so an agent asked to change a Windows host-setup script reads this sentence as forbidding the language the file is already written in, and the doc offers no section to route to instead.

The decision this needs: does CODESTYLE.md grow a PowerShell section (paired with a powershell-codestyle Skill, per the pattern the other three language sections follow), or does the Shell section's sentence narrow to say what it actually means about Bash-versus-Python without claiming to cover every language?

2. "Shell" carries no scope note where ".NET" and "Python" both do

.NET and Python each open with an italic scope note:

This section applies only to the .NET side. A repo with no .NET projects still carries it (the file is carried whole) and ignores it.

Shell has none. A reader who has only that section, in a repo that ships no shell scripts, reads an unscoped fleet mandate about which language every program must be written in, with nothing saying the section is ignorable. Whether it gets the note depends on what item 1 decides the section claims.

3. cspell and CSpell in the same file, against the file's own rule

CODESTYLE.md "General" opens with "Use each tool's official casing in task labels, docs, and prose", then writes the tool two ways:

Location	Form
General, the doc-lint set	cspell
Markdown and Spelling	CSpell

A reader applying the unit's own rule to a new task label has the file itself as evidence for both. Measured across the tree, 75 occurrences are lowercase and 9 capitalized, so most of the lowercase ones are the cspell.json filename and CLI invocations, which are correctly lowercase, and settling the prose form is a sweep rather than a one-line edit. The doc-lint list also reads consistently at present, since markdownlint and editorconfig-checker beside it are lowercase too.

Provenance

Canonical-content review pass against CODESTYLE.md "General" and "Shell", run on the branch for #1075/#1120/#1114/#1119/#1129/#1078. Items 1 and 3 verified against the tree directly.

[ptr727]

Three more in the same file from the second canonical-review round, all in CODESTYLE.md "General" and all needing the same kind of decision as the items above.

4. "The concrete names live in each language section below" is false

General states:

It is exposed as one or more named VS Code tasks (or, where a language ships no tasks, documented commands), and those definitions are the same across the fleet. The concrete names live in each language section below.

No language section names a task. .NET says only "its three-task clean-compile chain", and Python and Shell name none at all; all three defer to a Skill under .agents/skills/, which the same file states is hub-local and not carried.

Two bullets later the reader is told "The named task definition is the canonical spec - its exact command sequence, arguments, and strictness", so they go to the language section for that name, find none, and either invent an invocation or cannot run a gate the rule makes mandatory before committing.

5. "strongly suggested, not the repo's free choice to skip" states both obligations at once

The two halves say opposite things, and the unit resolves it by deferring to the hub-only linters section. A maintainer of a carrier repo with no hook cannot tell from the rule whether the repo is out of conformance, and has to fetch the hub to answer a question the sentence appears to answer.

This is the same wording problem the carried Skills have, where dotnet-codestyle said "not optional" and python-codestyle said "not opt-in" for the identical rule. Those two are fixed in the PR for #1075/#1120 to match GOVERNANCE.md's "strongly suggested fleet-wide, and its absence is a measured audit finding". CODESTYLE.md's own sentence is left here because it is the one the other two were paraphrasing, and settling it is the same decision as items 1 and 2 above.

6. "Keeping a working gate is not drift" rules on a case nobody meets

As written it asserts the trivial. The case a conformance sweep actually meets is a repo carrying a Husky.Net or pre-commit config the hub does not specify, and the sentence gives no ruling on it, so one auditor flags that config as unvendored drift while another cites this sentence to pass it.

[ptr727]

Five more from the third canonical-review round, in CODESTYLE.md and in the two language Skills that paraphrase it. Grouped here because they are the same "the doc states a rule its own examples or its own toolchain do not obey" shape as the items above.

7. The brownfield allowance points at two documents that do not describe it

CODESTYLE.md "General" and dotnet-codestyle "Build requirements" both say:

(The only brownfield allowance in the fleet is the one-time git-signing / line-ending migration described in GOVERNANCE.md and README.md, which has nothing to do with code analysis.)

Neither file describes such a migration. grep -i 'brownfield\|one-time\|migration' returns nothing in either. GOVERNANCE.md "Git and Commit Rules" is a summary plus a pointer to the git-commit-conventions Skill and states no allowance.

A carrier porting a brownfield .NET repo goes to both files to learn the allowance's scope and end date, finds nothing, and either invents a scope or concludes the whole zero-warnings exemption clause is stale. The reference is worse in a carrier than in the hub, since a carrier's README.md is its own repo-specific file and was never going to describe a fleet migration.

8. The title-case rule is falsified by its own example block

The rule names one exemption, lowercase short bind words, and Dependabot's Bump X from Y to Z titles. But the block below it carries three titles with lowercase words that are neither:

Pin softprops/action-gh-release to Commit SHA
Drop net8.0 Multi-Targeting from Console Project
Bump xunit.v3 from 3.2.2 to 3.3.0

Identifiers, package names, TFMs and repository slugs keep their own casing, and the unit never says so. A reader applying the rule as written produces Pin Softprops/Action-Gh-Release to Commit SHA or Drop Net8.0 Multi-Targeting, titles that no longer name the real action or TFM, and a reviewer correcting it back has nothing in the unit to cite.

This is the same shape as #1078, which fixed one example to match the rule. This one wants the rule to state the exemption its examples already rely on.

9. python-codestyle points at a "Type checking" section that does not exist

the repo's type checker: uv run pyright, or uv run mypy src where mypy is the CI checker, or both where the repo runs both (see Type checking above).

The file's headings are Why this exists, Two profiles, Toolchain, Local development loop, Layout, Code style, Tests, Versioning, Linter cleanliness. The material meant is an unnumbered bolded lead-in inside "Toolchain". A reader deciding pyright versus mypy greps for the named section, finds no heading, and either concludes the pointer is to a deleted section or goes looking in another file. The same unit's "the Two Profiles section" and "per Two Profiles above" likewise name a heading that reads ## Two profiles.

10. python-codestyle's "no such command" has no antecedent

A lint-only profile's clean-compile substitutes its uvx and unittest equivalents, per Two Profiles above, and has no such command to run before committing beyond those.

No command was named as "such" a command. The reader it is aimed at, someone on the lint-only profile working out what to run before committing, cannot tell whether it excuses them from the uv sync/uv build lines of the code block above, from the type checker, or from nothing, which is the one question the sentence exists to answer.

11. comment-and-doc-style's Codex bullet has an inverting pronoun

No-prompt operation is supported only inside an external sandbox because it removes command-wide protection.

The nearest noun to "it" is "an external sandbox", so the sentence parses as the sandbox being what removes protection. A reader configuring Codex on that reading concludes the sandbox weakens protection and runs no-prompt operation outside one, which is the state the sentence exists to forbid.

[ptr727]

Two more from the final confirmation pass, the same "the doc routes a reader to content that is not there" shape as items 4 and 9 above.

12. "The per-language mechanics ... are in each language section" is false

CODESTYLE.md "General", on analyzer suppressions:

The per-language mechanics (which attribute, which config key) are in each language section.

No attribute name and no config key appears in any language section. .NET is a scope sentence plus "This is packaged as the dotnet-codestyle Skill at .agents/skills/dotnet-codestyle/SKILL.md in the hub ... Read the skill for the full rules, code examples, and mechanics", and Python and Shell have the identical shape.

A carrier told to suppress a diagnostic at the narrowest scope reads its language section for the attribute form, finds only a pointer to a hub-local file it does not carry, and either guesses the annotation or blanket-relaxes the rule in root config, which the bullet directly above forbids.

This is the same defect as item 4 ("The concrete names live in each language section below") and settling one should settle both: either the language sections regain the concrete mechanics, or the General section stops promising they hold them and routes to the Skills directly.

13. add-host-tool is the one hub-context skill in AGENTS.md carrying no qualifier

AGENTS.md "Where the Rules Live" marks every other hub-context skill: standup-a-repo/resync-a-repo/audit-a-repo are "all hub-context only", and skill-lifecycle is "hub-context only, since .agents/skills/ exists only in the hub". The add-host-tool paragraph carries none, and its whole surface is hub-local, since the skill directs edits to spec/host-tools.json, the host-setup/ installers, docs/host-setup.md, and the host-gate tests.

A carrier asked to add a host tool invokes the skill, finds no host-setup/ or spec/host-tools.json in its tree, and either stalls or vendors hub machinery into a repo that is not supposed to carry it.

Filed rather than fixed in the PR for #1075/#1120 because that PR had reached a converged state on AGENTS.md and another edit would have restarted its review cycle for a one-clause addition.

[ptr727]

One more in python-codestyle "Local development loop", same doc-versus-CI shape as item 9's uv run mypy src mismatch.

14. "CI runs the same clean-compile commands as the authoritative backstop" is false when a repo runs both type checkers

The unit says, two sentences apart:

the repo's type checker: uv run pyright, or uv run mypy src where mypy is the CI checker, or both where the repo runs both

CI runs the same clean-compile commands as the authoritative backstop.

.github/workflows/validate-task.yml's "Type check Python step" runs mypy XOR pyright:

          if grep -Eq '^[[:space:]]*\[tool\.mypy\]' pyproject.toml; then

with the file's own comment recording that "Mypy takes precedence where a pyproject declares both sections".

So a repo the unit's own Toolchain guidance sanctions, pyright strict plus mypy for a plugin ecosystem, runs both locally, believes CI backstops both because this sentence says so, and merges a pyright-strict violation the validator never ran pyright to catch, because [tool.mypy] took precedence.

Settling it needs a decision rather than a reword: either the validator runs both where both are declared, or the skill says plainly that CI backstops only the precedence-winning checker and the other is local-only.

Found by the canonical-content pass on the fix round of PR #1157.

[ptr727]

Scope note on item 1: "Everything else is Python" is carried in two units, not one.

CODESTYLE.md "Shell" and .agents/skills/shell-codestyle/SKILL.md "When shell, not Python" carry the sentence byte-parallel, and CODESTYLE.md routes the reader to that skill for the full rules. Both are falsified the same way by the nine tracked .ps1 programs the hub itself ships.

PR #1157 aligned the two wordings, so they now state the same rule identically, but neither is fixed: whichever way this issue is settled has to land in both, or the pair diverges again on the next edit.