fix(toolchain): python.yaml pyright skip granularity + config-glob + opt-in wording gaps

[kyle-sexton]

Summary

Three mature, well-scoped follow-up findings on the bundled python ecosystem default
(plugins/toolchain/reference/ecosystems/python.yaml and its owning check-skill context doc),
deferred from PR #859's review threads and batched here via the #657 triage sweep. All three are
scoped to the python ecosystem surface; no cross-ecosystem mechanism changes.

Fix

Site 1 (P1) — pyright skip granularity. uv run pyright is the first check-cmd tool whose
presence is not implied by the ruff-config opt-in gate, and tool presence is evaluated per
ecosystem, not per tool (per the check skill's tool-presence rule). So a ruff-configured project
with pyright absent reports a whole-ecosystem missing-tool skip that also drops ruff coverage,
rather than skipping pyright alone.

Chose the issue's defaulted decision — document pyright as a hard prerequisite of the python
default once ruff opts the ecosystem in (skills/check/context/python.md, Type-check section) —
over a per-tool skip-granularity code change. Rationale: per-tool skip is a larger cross-ecosystem
mechanism change (every check-cmd tool would need independent-skip semantics); the documented
prerequisite is the smaller, reversible fix that resolves the reported fail-closed surprise without
redesigning the skip model. A maintainer wanting the larger mechanism can veto and redirect.

Site 2 (P2) — detection globs. Added pyrightconfig.json to the python globs so a standalone
pyright-config-only change is auto-detected as python-affecting by /toolchain:check and
/toolchain:lint local runs (CI already enforces its own check). The [tool.pyright] table is
already covered by the existing pyproject.toml glob.

Site 3 (P2) — opt-in wording. Reduced the opt-in value to its single ruff-config gating
condition. The trailing semicolon-separated pyright-mode clause structurally resembled the
multi-clause per-tool opt-in form (per the ecosystem-commands contract, whose schema defines
opt-in as either a single whole-check-cmd condition or a per-tool multi-clause value), risking
a misread of python's single-condition gate as multi-condition. Removed rather than reworded:
opt-in is a condition field, not a mode note, and the descriptive pyright-mode text already lives
verbatim in skills/check/context/python.md gotchas (single source of truth — no duplication). The
reduced value is now identical to the contract's own clean example
(docs/conventions/ecosystem-commands/examples/python.yaml), confirming the intended single-condition
form.

Includes the per-plugin version bump (0.9.0 → 0.9.1, patch — scoped bugfix/hardening) and a
matching top-inserted CHANGELOG.md entry.

Verification

Ran against the changed files in the worktree:

check-jsonschema --schemafile docs/conventions/ecosystem-commands/ecosystem.schema.json \
  plugins/toolchain/reference/ecosystems/python.yaml
  -> ok -- validation done

check-jsonschema --schemafile https://json.schemastore.org/claude-code-plugin-manifest.json \
  plugins/toolchain/.claude-plugin/plugin.json
  -> ok -- validation done

markdownlint-cli2 --config .markdownlint-cli2.jsonc \
  plugins/toolchain/skills/check/context/python.md plugins/toolchain/CHANGELOG.md
  -> Summary: 0 error(s)

typos --config _typos.toml <changed files>
  -> clean

(/toolchain:check and /toolchain:lint are model-driven skills, not runnable scripts; the
ecosystem YAML is validated against its published ecosystem.schema.json contract as the concrete
static gate. No CI lane enforces the ecosystem schema — it is a reference contract — so the schema
run above is the authoritative structural check for the YAML edit.)

Related

• Closes toolchain: python.yaml pyright per-tool skip granularity + config-glob + opt-in wording gaps (PR #859 follow-ups) #1017
• feat(toolchain): add pyright to python ecosystem check-cmd #859 — originating PR whose review threads deferred these as follow-ups
• lane sweep: triage — week of 7/20 (rolling paper-cut batch) #657 — triage-sweep source (T8h batch conversion)

🤖 Generated with Claude Code

Work-class: C3 (bug-fix-shaped) — attended triage 2026-07-23, operator-ratified. 🤖

[claude]

Claude finished @kyle-sexton's task in 2m 21s —— View job

---

PR Review

• Gather context and understand the request
• Read changed files
• Review for correctness, security, and CLAUDE.md alignment
• Post findings

---

Verdict: Approve with one minor omission noted. All three fixes are correct, internally consistent, and well-scoped. No security concerns. One small gap and two editorial observations below.

---

Site 2 — examples/python.yaml not updated

The pyrightconfig.json glob is added to the plugin's bundled rung-4 fallback (plugins/toolchain/reference/ecosystems/python.yaml:4) but not to the consumer-facing example at docs/conventions/ecosystem-commands/examples/python.yaml:3.

The example still reads:

globs: ["*.py", "pyproject.toml", "uv.lock"]

Consuming repos that bootstrapped from this example won't inherit the detection improvement. If the fix is worth making in the plugin default, it's arguably worth propagating to the example so both surfaces stay in sync. Not a blocker, but the example is the doc that drives consumer adoption.

Fix this →

---

Site 1 — prerequisite paragraph placement (editorial, not a bug)

The new text at python.md:37 is a plain paragraph floating between the Type check code block and ## Gotchas. The rest of the file uses bullet points under ## Gotchas for warning-style content. The existing pyright gotcha (line 43) and the new prerequisite note are split across sections, so a reader scanning Gotchas won't see the prerequisite. The placement gives the warning more prominence (intentional per the PR description), but the prose style doesn't match the surrounding bullet pattern. Not a blocker — the content is correct and discoverable.

---

Site 3 — opt-in reduction (confirmed correct)

The reduced value "ruff config (ruff.toml, .ruff.toml, or pyproject.toml [tool.ruff])" is now identical to docs/conventions/ecosystem-commands/examples/python.yaml:9, confirming the intended single-condition form per the schema's opt-in description. The schema's own definition of the multi-clause form ("each clause names a sub-tool and its own condition") makes clear the old semicolon-separated mode note was a misuse of the field. Reduction is correct.

---

CHANGELOG format

## [0.9.1] omits the date (CHANGELOG.md:6). Keep a Changelog recommends ## [0.9.1] - YYYY-MM-DD, but this matches the existing project convention (## [0.9.0], ## [0.8.0] also lack dates), so it's intentional and consistent. No action needed.

---

Version bump

0.9.0 → 0.9.1 is the correct semver tier for a scoped bug-fix and documentation-hardening patch with no API surface changes.

---

Security

No concerns. All changes are config YAML, documentation text, and a version bump — no code execution paths, no new external URLs, no credential handling.

[claude]

Claude finished @kyle-sexton's task in 1m 26s —— View job

---

Security Review — PR #1025

• Load tools
• Read PR diff
• Review changed files for security issues
• Post findings

---

No security issues found.

The four changed files are purely documentation and static configuration — no executable code paths, no injection surfaces, no credential handling, no authorization changes, and no supply chain exposure.

File	Change	Security verdict
plugins/toolchain/.claude-plugin/plugin.json	Version bump 0.9.0 → 0.9.1	No impact
plugins/toolchain/CHANGELOG.md	Release notes text	No impact
plugins/toolchain/reference/ecosystems/python.yaml	Added pyrightconfig.json to globs; simplified opt-in string	No impact
plugins/toolchain/skills/check/context/python.md	Added prerequisite note for pyright	No impact

Rationale for each category checked:

• Injection surfaces — globs values are file-detection patterns read by the skill runtime, not passed to a shell. The opt-in and check-cmd fields are unchanged command strings with no new interpolated variables. The find "$REPO_ROOT" snippet in python.md is illustrative documentation, not executed by this PR.
• Credential / secret handling — no new variables, environment references, or external calls introduced.
• Authorization / access-control — no permission widening; the opt-in simplification removes a clause, narrowing rather than broadening activation scope.
• GitHub Actions / supply-chain — no workflow files touched; no dependency pins added or changed.
• Command execution surface — check-cmd is pre-existing and unchanged. The new pyrightconfig.json glob only affects which file changes trigger the skill — it does not alter what the skill executes.

[kyle-sexton]

🔒 merge-drive lane claiming this PR for on-branch fix work this cycle (amendment-round: 16, worker tier). Will fix clear branch-owned CI/bot findings, defer non-DEFER-FORBIDDEN items with reply+resolve, push, then re-check the merge gate.

[claude]

Claude finished @kyle-sexton's task in 1m 21s —— View job

---

PR Review

• Gather context and understand the request
• Read changed files and git diff
• Check if previously noted gap (examples/python.yaml glob) has been addressed
• Review for correctness, security, and CLAUDE.md alignment
• Post findings

---

Verdict: Approve with one minor omission still outstanding. All three fixes are correct and internally consistent. The gap flagged in the previous review cycle (2026-07-22) has not yet been resolved.

---

Outstanding gap — examples/python.yaml glob still missing pyrightconfig.json

The previous review noted this, and it remains unaddressed. The plugin's bundled default was updated:

plugins/toolchain/reference/ecosystems/python.yaml:4:

globs: ["*.py", "pyproject.toml", "uv.lock", "pyrightconfig.json"]

But the consumer-facing example was not:

docs/conventions/ecosystem-commands/examples/python.yaml:3:

globs: ["*.py", "pyproject.toml", "uv.lock"]   # ← pyrightconfig.json absent

Consuming repos that bootstrapped from this example won't get the detection improvement for pyright-config-only changes. Not a blocker, but both surfaces should stay in sync if the fix is considered correct.

Fix this →

---

All three fixes confirmed correct

Site 1 — pyright prerequisite (python.md:37). The paragraph is accurate: tool presence is evaluated per ecosystem, so a ruff-configured project with pyright absent triggers a whole-ecosystem skip. The chosen approach (document the prerequisite rather than redesign the per-tool skip model) is the right scoped call. Content is correct and discoverable.

Site 2 — pyrightconfig.json glob (python.yaml:4). Addition is correct. The [tool.pyright] table in pyproject.toml was already covered; pyrightconfig.json is the standalone config file that was missing from auto-detection.

Site 3 — opt-in reduction (python.yaml:10). The reduced value "ruff config (ruff.toml, .ruff.toml, or pyproject.toml [tool.ruff])" is now identical to docs/conventions/ecosystem-commands/examples/python.yaml:9, confirming the intended single-condition form. The old semicolon-separated clause was a structural misuse of the opt-in field per the schema definition.

Version and CHANGELOG. 0.9.0 → 0.9.1 is the correct semver tier for a scoped bug-fix/documentation-hardening patch. The three CHANGELOG bullets accurately describe each fix. The dateless header (## [0.9.1]) is consistent with the existing project convention.

Security. No concerns — all changes are static config YAML and documentation text with no execution surfaces, no new external references, and no credential handling.

---

[claude]

Claude finished @kyle-sexton's task in 1m 2s —— View job

---

Security Review — PR #1025

• Gather context and understand the request
• Read PR diff and changed files
• Hunt for security vulnerabilities
• Post findings

---

No security issues found.

All four changed files are documentation and static configuration — no executable code paths, no injection surfaces, no credential handling, no authorization changes, and no supply-chain exposure.

File	Change	Security verdict
plugins/toolchain/.claude-plugin/plugin.json	Version bump 0.9.0 → 0.9.1	No impact
plugins/toolchain/CHANGELOG.md	Release notes text	No impact
plugins/toolchain/reference/ecosystems/python.yaml	Added pyrightconfig.json to globs; simplified opt-in string	No impact
plugins/toolchain/skills/check/context/python.md	Added prerequisite note for pyright	No impact

Rationale per category checked:

• Injection surfaces — globs values ("pyrightconfig.json") are file-detection patterns matched by the skill runtime, not passed to a shell. The opt-in and check-cmd fields are unchanged command strings with no new interpolated variables. The illustrative find "$REPO_ROOT" snippet in python.md is pre-existing and not modified in this PR.
• Credential / secret handling — no new variables, environment references, or external calls introduced.
• Authorization / access-control — no permission widening. The opt-in simplification removes a clause, narrowing rather than broadening activation scope.
• GitHub Actions / supply-chain — no workflow files touched; no dependency pins added or changed.
• Command execution surface — check-cmd (uv run ruff check . --no-fix && uv run ruff format . --check && uv run pyright) is pre-existing and unchanged. The new glob only affects which file changes trigger the skill — it does not alter what the skill executes.