Fix Issue #928's Internal-Inconsistency Findings in Skills

.agents/skills/comment-and-doc-style/SKILL.md

@@ -224,8 +224,8 @@ hub-hosted tool the reader runs, are in `references/carried-doc-references.md`.
 
 ## PR titles and commit messages
 
-- **Format**: an imperative subject, 72 characters or fewer, no trailing period ("Add 24-hour
-  PM2.5 average sensor", not "Added X" or "Adds X"). An optional body, blank-line separated,
+- **Format**: an imperative subject, 72 characters or fewer, no trailing period ("Add 24-Hour
+  PM2.5 Average Sensor", not "Added X" or "Adds X"). An optional body, blank-line separated,
   explains *why* the change is being made when that is non-obvious, the diff already shows *what*.
 - **Rules**: no vague titles (`update stuff`, `wip`). Dependabot's default `Bump X from Y to Z`
   titles are fine as-is. No `Co-Authored-By:` lines unless the developer explicitly asks. No
@@ -237,11 +237,11 @@ hub-hosted tool the reader runs, are in `references/carried-doc-references.md`.
   *EPA-Corrected*, *24-Hour*).
 
 ```text
-Add structured logging extensions to library
-Pin softprops/action-gh-release to commit SHA
-Drop net8.0 multi-targeting from console project
+Add Structured Logging Extensions to Library
+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
-Clarify devcontainer setup steps in README
+Clarify devcontainer Setup Steps in README
 ```
 
 ## Quantitative claims

.agents/skills/dotnet-codestyle/references/project-config.md

@@ -15,3 +15,7 @@
      <InternalsVisibleTo Include="YourTestProject" />
    </ItemGroup>
    ```
+
+5. **Nullable and XML documentation**: `<Nullable>enable</Nullable>`,
+   `<GenerateDocumentationFile>true</GenerateDocumentationFile>` (see `references/conventions.md`
+   for the XML documentation format every public surface needs).

.agents/skills/python-codestyle/SKILL.md

@@ -48,7 +48,7 @@ declaration, versioning, VS Code config), see `references/profiles.md`.
 | [ruff][ruff-link] | lint + format + import sort | `pyproject.toml` `[tool.ruff]` |
 | [pyright][pyright-link] | type checker (the default, a strict baseline) | `pyproject.toml` `[tool.pyright]` |
 | [mypy][mypy-link] | additional/alternate type checker (optional, the CI checker in a mypy-in-CI repo, required for Home Assistant) | `pyproject.toml` `[tool.mypy]` (or per home-assistant/core) |
-| [pytest][docs-link] | test runner | `pyproject.toml` `[tool.pytest.ini_options]` |
+| [pytest][docs-link] | test runner (build profile only, lint-only uses `unittest`) | `pyproject.toml` `[tool.pytest.ini_options]` |
 
 **Type checking targets strongly typed, deterministic code.** pyright in strict mode is the
 default baseline on first-party code (a repo may instead run mypy in CI and keep pyright
@@ -72,7 +72,9 @@ inherently consistent.
 
 ## Local development loop
 
-From inside the Python project directory:
+From inside a **build**-profile Python project directory. A **lint-only** Scripts profile has no
+`uv.lock` to sync and no pytest to run, substitute `uvx` per tool and `unittest` per the Two
+Profiles section above:
 
 ```sh
 uv sync                          # creates .venv, installs deps + dev group
@@ -85,15 +87,18 @@ uv run pytest                    # run tests
 uv build                         # produce wheel + sdist in ./dist (published packages only)
 ```
 
-The Python clean-compile is `uv run ruff format` + `uv run ruff check` + 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). Run it, plus `uv run pytest`, before committing. These are
-documented commands, and an optional VS Code tasks mirror (all `type: process`, no `&&` shell
-chaining, so it runs the same on any task shell) is in the hub `vscode-tasks-python.json` snippet.
-CI runs the same clean-compile commands as the authoritative backstop. A working local hook is
-strongly suggested, not opt-in: wire the Python `pre-commit` framework from the canonical
-`catalog/snippets/pre-commit/.pre-commit-config.yaml`. See GOVERNANCE.md "Running the Linters
-Locally" for what the hook must cover and what its absence means.
+The **build**-profile Python clean-compile is `uv run ruff format` + `uv run ruff check` + 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). Run it, plus `uv run pytest`, before
+committing. 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. These are documented commands, and an optional VS Code tasks mirror (all `type: process`,
+no `&&` shell chaining, so it runs the same on any task shell) is in the hub
+`vscode-tasks-python.json` snippet. CI runs the same clean-compile commands as the authoritative
+backstop. A working local hook is strongly suggested, not opt-in: wire the Python `pre-commit`
+framework from the canonical `catalog/snippets/pre-commit/.pre-commit-config.yaml`. See
+GOVERNANCE.md "Running the Linters Locally" for what the hook must cover and what its absence
+means.
 
 A restricted executor gives each task a cache directory under a writable temporary root. Point
 `UV_CACHE_DIR`, `RUFF_CACHE_DIR`, `MYPY_CACHE_DIR`, and `COVERAGE_FILE` into that directory before
@@ -142,9 +147,12 @@ For comments, docstrings, full type-hint rules, naming, imports, and all pattern
 
 ## Tests
 
-`uv run pytest`. One test file per module (`test_<module>.py`), fixtures over setup/teardown,
-fakes over mocks. Test the docstring's contract, not implementation details. See
-`references/testing.md` for the full conventions.
+`uv run pytest` for a build profile, `unittest` for a lint-only Scripts profile (see Two Profiles
+above). One test file per module (`test_<module>.py`). A build profile prefers fixtures over
+`unittest`'s `setUp`/`tearDown` lifecycle hooks. A lint-only profile uses those hooks directly,
+since `unittest` has no fixture-injection mechanism of its own. Fakes over mocks either way. Test
+the docstring's contract, not implementation details. See `references/testing.md` for the full
+build-profile conventions, and `references/profiles.md` for the lint-only `unittest` conventions.
 
 ## Versioning
 
@@ -159,10 +167,11 @@ Before pushing or opening a PR:
 - VS Code's Problems pane should be quiet for the files you touched. The relevant linters are ruff
   (via the `charliermarsh.ruff` extension) and pyright (via the `ms-python.python` extension's
   bundled Pylance).
-- The CI gate is `uv run ruff check`, `uv run ruff format --check`, the repo's type checker
-  (`uv run pyright` or `uv run mypy src`), and `uv run pytest`, the same commands as the local
-  loop above, run from the Python project directory (invoked as separate steps, not `&&`-chained,
-  so the runner shell is irrelevant).
+- The **build**-profile CI gate is `uv run ruff check`, `uv run ruff format --check`, the repo's
+  type checker (`uv run pyright` or `uv run mypy src`), and `uv run pytest`, the same commands as
+  the local loop above, run from the Python project directory (invoked as separate steps, not
+  `&&`-chained, so the runner shell is irrelevant). A **lint-only** profile's CI gate is its `uvx`
+  equivalents plus its `unittest` suite, per `references/profiles.md`.
 - Markdown in this directory follows CODESTYLE.md's repo-wide Markdown and Spelling rules,
   packaged as the `comment-and-doc-style` Skill.
 

.agents/skills/python-codestyle/references/testing.md

@@ -1,5 +1,9 @@
 # Python Testing Conventions
 
+This covers the **build** profile. A **lint-only** Scripts profile has no `uv.lock` to run pytest
+against, its testing conventions (`unittest`, `uvx coverage@latest run -m unittest discover`) are
+in `references/profiles.md`.
+
 Use `pytest` with configuration in `[tool.pytest.ini_options]`. Default invocation:
 `uv run pytest`.
 

.agents/skills/resync-a-repo/SKILL.md

@@ -82,4 +82,4 @@ One focused pull request per drift class, branched from the target's `develop`,
 push to a protected branch and never a hand edit outside a pull request. Close the review loop,
 per the `pr-review-conduct` skill, before asking the maintainer for merge permission. The
 maintainer merges, the agent drives to green and stops. Re-run the audit after the merge and
-commit the report, done means measured, not applied.
+commit the report per `git-commit-conventions`, done means measured, not applied.

.agents/skills/skill-lifecycle/SKILL.md

@@ -28,7 +28,7 @@ A skill surfaces at a trigger moment. A rule that binds every action all the tim
 3. **Author the body per the `comment-and-doc-style` skill**: LF (the repo default), present tense, ASCII tiers, no semicolon in prose. Name hub paths as plain code spans rather than repo-relative links, because an installed copy resolves no repo path, and say "from a hub checkout" for anything the reader must run.
 4. **Split bulk into `references/`** when the source doc is large: the SKILL.md carries the summary and the binding rules, and each `references/*.md` carries one topic read on demand, the shape `comment-and-doc-style` uses.
 5. **Apply the doc-packaging pattern below in the same change** when the skill packages a law doc or one of its sections.
-6. **Regenerate and commit all trees together**: `python3 scripts/build_dist.py`, then commit the source and both generated trees in one commit. CI runs `--check` on every pull request and fails a desynced distribution. `python3 scripts/tests/test_build_dist.py` covers the generator itself.
+6. **Regenerate and commit all trees together**: `python3 scripts/build_dist.py`, then commit the source and both generated trees in one commit, per `git-commit-conventions`. CI runs `--check` on every pull request and fails a desynced distribution. `python3 scripts/tests/test_build_dist.py` covers the generator itself.
 7. **Record the surfacing**: annotate the `AGENTS.md` "Where the Rules Live" row when the skill packages a GOVERNANCE section, or its closing paragraph when the skill is new content, so the map stays the one place coverage is read from.
 8. **Refresh the machines after merge**: re-run `python3 scripts/skills_install.py` per machine, the cadence `docs/host-setup.md` "Fleet Skills Install" states. Until then every machine serves the previous skill set, which `--report` says.
 

.claude-plugin/fleet-skills/.source-digest

@@ -1 +1 @@
-702692e5f8c8f60e
+9bf75d7cd0da2253

.claude-plugin/fleet-skills/skills/comment-and-doc-style/SKILL.md

@@ -224,8 +224,8 @@ hub-hosted tool the reader runs, are in `references/carried-doc-references.md`.
 
 ## PR titles and commit messages
 
-- **Format**: an imperative subject, 72 characters or fewer, no trailing period ("Add 24-hour
-  PM2.5 average sensor", not "Added X" or "Adds X"). An optional body, blank-line separated,
+- **Format**: an imperative subject, 72 characters or fewer, no trailing period ("Add 24-Hour
+  PM2.5 Average Sensor", not "Added X" or "Adds X"). An optional body, blank-line separated,
   explains *why* the change is being made when that is non-obvious, the diff already shows *what*.
 - **Rules**: no vague titles (`update stuff`, `wip`). Dependabot's default `Bump X from Y to Z`
   titles are fine as-is. No `Co-Authored-By:` lines unless the developer explicitly asks. No
@@ -237,11 +237,11 @@ hub-hosted tool the reader runs, are in `references/carried-doc-references.md`.
   *EPA-Corrected*, *24-Hour*).
 
 ```text
-Add structured logging extensions to library
-Pin softprops/action-gh-release to commit SHA
-Drop net8.0 multi-targeting from console project
+Add Structured Logging Extensions to Library
+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
-Clarify devcontainer setup steps in README
+Clarify devcontainer Setup Steps in README
 ```
 
 ## Quantitative claims

.claude-plugin/fleet-skills/skills/dotnet-codestyle/references/project-config.md

@@ -15,3 +15,7 @@
      <InternalsVisibleTo Include="YourTestProject" />
    </ItemGroup>
    ```
+
+5. **Nullable and XML documentation**: `<Nullable>enable</Nullable>`,
+   `<GenerateDocumentationFile>true</GenerateDocumentationFile>` (see `references/conventions.md`
+   for the XML documentation format every public surface needs).

.claude-plugin/fleet-skills/skills/python-codestyle/SKILL.md

@@ -48,7 +48,7 @@ declaration, versioning, VS Code config), see `references/profiles.md`.
 | [ruff][ruff-link] | lint + format + import sort | `pyproject.toml` `[tool.ruff]` |
 | [pyright][pyright-link] | type checker (the default, a strict baseline) | `pyproject.toml` `[tool.pyright]` |
 | [mypy][mypy-link] | additional/alternate type checker (optional, the CI checker in a mypy-in-CI repo, required for Home Assistant) | `pyproject.toml` `[tool.mypy]` (or per home-assistant/core) |
-| [pytest][docs-link] | test runner | `pyproject.toml` `[tool.pytest.ini_options]` |
+| [pytest][docs-link] | test runner (build profile only, lint-only uses `unittest`) | `pyproject.toml` `[tool.pytest.ini_options]` |
 
 **Type checking targets strongly typed, deterministic code.** pyright in strict mode is the
 default baseline on first-party code (a repo may instead run mypy in CI and keep pyright
@@ -72,7 +72,9 @@ inherently consistent.
 
 ## Local development loop
 
-From inside the Python project directory:
+From inside a **build**-profile Python project directory. A **lint-only** Scripts profile has no
+`uv.lock` to sync and no pytest to run, substitute `uvx` per tool and `unittest` per the Two
+Profiles section above:
 
 ```sh
 uv sync                          # creates .venv, installs deps + dev group
@@ -85,15 +87,18 @@ uv run pytest                    # run tests
 uv build                         # produce wheel + sdist in ./dist (published packages only)
 ```
 
-The Python clean-compile is `uv run ruff format` + `uv run ruff check` + 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). Run it, plus `uv run pytest`, before committing. These are
-documented commands, and an optional VS Code tasks mirror (all `type: process`, no `&&` shell
-chaining, so it runs the same on any task shell) is in the hub `vscode-tasks-python.json` snippet.
-CI runs the same clean-compile commands as the authoritative backstop. A working local hook is
-strongly suggested, not opt-in: wire the Python `pre-commit` framework from the canonical
-`catalog/snippets/pre-commit/.pre-commit-config.yaml`. See GOVERNANCE.md "Running the Linters
-Locally" for what the hook must cover and what its absence means.
+The **build**-profile Python clean-compile is `uv run ruff format` + `uv run ruff check` + 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). Run it, plus `uv run pytest`, before
+committing. 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. These are documented commands, and an optional VS Code tasks mirror (all `type: process`,
+no `&&` shell chaining, so it runs the same on any task shell) is in the hub
+`vscode-tasks-python.json` snippet. CI runs the same clean-compile commands as the authoritative
+backstop. A working local hook is strongly suggested, not opt-in: wire the Python `pre-commit`
+framework from the canonical `catalog/snippets/pre-commit/.pre-commit-config.yaml`. See
+GOVERNANCE.md "Running the Linters Locally" for what the hook must cover and what its absence
+means.
 
 A restricted executor gives each task a cache directory under a writable temporary root. Point
 `UV_CACHE_DIR`, `RUFF_CACHE_DIR`, `MYPY_CACHE_DIR`, and `COVERAGE_FILE` into that directory before
@@ -142,9 +147,12 @@ For comments, docstrings, full type-hint rules, naming, imports, and all pattern
 
 ## Tests
 
-`uv run pytest`. One test file per module (`test_<module>.py`), fixtures over setup/teardown,
-fakes over mocks. Test the docstring's contract, not implementation details. See
-`references/testing.md` for the full conventions.
+`uv run pytest` for a build profile, `unittest` for a lint-only Scripts profile (see Two Profiles
+above). One test file per module (`test_<module>.py`). A build profile prefers fixtures over
+`unittest`'s `setUp`/`tearDown` lifecycle hooks. A lint-only profile uses those hooks directly,
+since `unittest` has no fixture-injection mechanism of its own. Fakes over mocks either way. Test
+the docstring's contract, not implementation details. See `references/testing.md` for the full
+build-profile conventions, and `references/profiles.md` for the lint-only `unittest` conventions.
 
 ## Versioning
 
@@ -159,10 +167,11 @@ Before pushing or opening a PR:
 - VS Code's Problems pane should be quiet for the files you touched. The relevant linters are ruff
   (via the `charliermarsh.ruff` extension) and pyright (via the `ms-python.python` extension's
   bundled Pylance).
-- The CI gate is `uv run ruff check`, `uv run ruff format --check`, the repo's type checker
-  (`uv run pyright` or `uv run mypy src`), and `uv run pytest`, the same commands as the local
-  loop above, run from the Python project directory (invoked as separate steps, not `&&`-chained,
-  so the runner shell is irrelevant).
+- The **build**-profile CI gate is `uv run ruff check`, `uv run ruff format --check`, the repo's
+  type checker (`uv run pyright` or `uv run mypy src`), and `uv run pytest`, the same commands as
+  the local loop above, run from the Python project directory (invoked as separate steps, not
+  `&&`-chained, so the runner shell is irrelevant). A **lint-only** profile's CI gate is its `uvx`
+  equivalents plus its `unittest` suite, per `references/profiles.md`.
 - Markdown in this directory follows CODESTYLE.md's repo-wide Markdown and Spelling rules,
   packaged as the `comment-and-doc-style` Skill.
 

.claude-plugin/fleet-skills/skills/python-codestyle/references/testing.md

@@ -1,5 +1,9 @@
 # Python Testing Conventions
 
+This covers the **build** profile. A **lint-only** Scripts profile has no `uv.lock` to run pytest
+against, its testing conventions (`unittest`, `uvx coverage@latest run -m unittest discover`) are
+in `references/profiles.md`.
+
 Use `pytest` with configuration in `[tool.pytest.ini_options]`. Default invocation:
 `uv run pytest`.
 

.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md

@@ -82,4 +82,4 @@ One focused pull request per drift class, branched from the target's `develop`,
 push to a protected branch and never a hand edit outside a pull request. Close the review loop,
 per the `pr-review-conduct` skill, before asking the maintainer for merge permission. The
 maintainer merges, the agent drives to green and stops. Re-run the audit after the merge and
-commit the report, done means measured, not applied.
+commit the report per `git-commit-conventions`, done means measured, not applied.

.claude-plugin/fleet-skills/skills/skill-lifecycle/SKILL.md

@@ -28,7 +28,7 @@ A skill surfaces at a trigger moment. A rule that binds every action all the tim
 3. **Author the body per the `comment-and-doc-style` skill**: LF (the repo default), present tense, ASCII tiers, no semicolon in prose. Name hub paths as plain code spans rather than repo-relative links, because an installed copy resolves no repo path, and say "from a hub checkout" for anything the reader must run.
 4. **Split bulk into `references/`** when the source doc is large: the SKILL.md carries the summary and the binding rules, and each `references/*.md` carries one topic read on demand, the shape `comment-and-doc-style` uses.
 5. **Apply the doc-packaging pattern below in the same change** when the skill packages a law doc or one of its sections.
-6. **Regenerate and commit all trees together**: `python3 scripts/build_dist.py`, then commit the source and both generated trees in one commit. CI runs `--check` on every pull request and fails a desynced distribution. `python3 scripts/tests/test_build_dist.py` covers the generator itself.
+6. **Regenerate and commit all trees together**: `python3 scripts/build_dist.py`, then commit the source and both generated trees in one commit, per `git-commit-conventions`. CI runs `--check` on every pull request and fails a desynced distribution. `python3 scripts/tests/test_build_dist.py` covers the generator itself.
 7. **Record the surfacing**: annotate the `AGENTS.md` "Where the Rules Live" row when the skill packages a GOVERNANCE section, or its closing paragraph when the skill is new content, so the map stays the one place coverage is read from.
 8. **Refresh the machines after merge**: re-run `python3 scripts/skills_install.py` per machine, the cadence `docs/host-setup.md` "Fleet Skills Install" states. Until then every machine serves the previous skill set, which `--report` says.