From da2c7c1e1482f8a7df917d159642a1519a612354 Mon Sep 17 00:00:00 2001 From: "melodic-automation-lanes[bot]" <337595936+melodic-automation-lanes[bot]@users.noreply.github.com> Date: Sat, 21 Nov 2026 11:25:12 +0000 Subject: [PATCH 1/6] Resolve issue #16032 Lane-Activity: work-resolve-issue/resolve-issue --- ...ssue-issue-16032-44896998505-1-d4f74506.md | 37 +++++++++ plugins/toolchain/README.md | 18 ++--- .../evals/ck-consumer-config-wins/case.yaml | 2 +- .../evals/ck-consumer-config-wins/prompt.md | 2 +- .../samples/logged-assumed.json | 2 +- .../samples/logged-assumed.json | 2 +- .../samples/no-record-write.json | 2 +- .../samples/no-record-write.json | 2 +- .../toolchain/reference/ecosystems/bash.yaml | 10 --- .../reference/ecosystems/cross-cutting.yaml | 24 ------ .../reference/ecosystems/dotnet.yaml | 35 --------- .../toolchain/reference/ecosystems/go.yaml | 46 ----------- .../reference/ecosystems/markdown.yaml | 10 --- .../reference/ecosystems/powershell.yaml | 10 --- .../reference/ecosystems/python.yaml | 18 ----- .../reference/ecosystems/typescript.yaml | 18 ----- .../toolchain/reference/ecosystems/yaml.yaml | 18 ----- .../toolchain/reference/resolution-ladder.md | 64 ++++++++------- plugins/toolchain/skills/check/SKILL.md | 42 +++++----- .../toolchain/skills/check/context/bash.md | 43 ---------- .../toolchain/skills/check/context/dotnet.md | 78 ------------------- .../toolchain/skills/check/context/gates.md | 6 +- plugins/toolchain/skills/check/context/go.md | 78 ------------------- .../skills/check/context/powershell.md | 47 ----------- .../toolchain/skills/check/context/python.md | 63 --------------- .../skills/check/context/typescript.md | 54 ------------- plugins/toolchain/skills/lint/SKILL.md | 50 +++++++----- plugins/toolchain/skills/setup/SKILL.md | 42 +++++----- scripts/affected-tests-no-suite.txt | 19 ++--- scripts/org-repo-tokens-allow.tsv | 9 --- .../shell-portability-skill-md-baseline.txt | 1 - 31 files changed, 169 insertions(+), 683 deletions(-) create mode 100644 .changes/toolchain/work-resolve-issue-issue-16032-44896998505-1-d4f74506.md delete mode 100644 plugins/toolchain/reference/ecosystems/bash.yaml delete mode 100644 plugins/toolchain/reference/ecosystems/cross-cutting.yaml delete mode 100644 plugins/toolchain/reference/ecosystems/dotnet.yaml delete mode 100644 plugins/toolchain/reference/ecosystems/go.yaml delete mode 100644 plugins/toolchain/reference/ecosystems/markdown.yaml delete mode 100644 plugins/toolchain/reference/ecosystems/powershell.yaml delete mode 100644 plugins/toolchain/reference/ecosystems/python.yaml delete mode 100644 plugins/toolchain/reference/ecosystems/typescript.yaml delete mode 100644 plugins/toolchain/reference/ecosystems/yaml.yaml delete mode 100644 plugins/toolchain/skills/check/context/bash.md delete mode 100644 plugins/toolchain/skills/check/context/dotnet.md delete mode 100644 plugins/toolchain/skills/check/context/go.md delete mode 100644 plugins/toolchain/skills/check/context/powershell.md delete mode 100644 plugins/toolchain/skills/check/context/python.md delete mode 100644 plugins/toolchain/skills/check/context/typescript.md diff --git a/.changes/toolchain/work-resolve-issue-issue-16032-44896998505-1-d4f74506.md b/.changes/toolchain/work-resolve-issue-issue-16032-44896998505-1-d4f74506.md new file mode 100644 index 00000000000..91b4c278290 --- /dev/null +++ b/.changes/toolchain/work-resolve-issue-issue-16032-44896998505-1-d4f74506.md @@ -0,0 +1,37 @@ +--- +bump: major +--- + +### Removed + +- **No bundled ecosystem defaults.** The nine bundled ecosystem files (`bash`, `cross-cutting`, + `dotnet`, `go`, `markdown`, `powershell`, `python`, `typescript`, `yaml`) are deleted, and so are + `/toolchain:check`'s six per-language context pages. `/toolchain:check` and `/toolchain:lint` run + only a command the repository records in `.claude/ecosystems/.yaml`, one its build files + imply, or, in an attended run, one the person gives when asked. A key nothing resolves reads + `skip (unresolved: .)` and runs nothing. The resolution ladder has three rungs. + `/toolchain:setup apply` drafts records from the repository alone. + ([#16032](https://github.com/melodic-software/claude-code-plugins/issues/16032)) +- **Migration.** A repository with no ecosystem record used to get the bundled commands in an + attended run. It now gets inferred commands, a question, or an unresolved skip. To keep a + command, record it with `/toolchain:setup apply `. Checks only the bundled files ran + are dropped on purpose: the spelling check (`typos`), the editorconfig check + (`editorconfig-checker`) and the offline link check (`lychee --offline`) from the cross-cutting + file, and the workflow lint (`actionlint`) from the yaml file. Record them in + `.claude/ecosystems/cross-cutting.yaml` or `.claude/ecosystems/yaml.yaml` to keep them. The secret + scan stays: `/toolchain:lint` runs it from the skill. +- **Coverage.** With no bundled file to supply globs, an ecosystem id is covered when it is + recorded, stated in the repository's instructions, or inferred from its build files. In a + repository with no ecosystem record, a changed file's own type also infers its id, so it reads + `skip (unresolved: ...)` rather than going unchecked in silence. + +### Added + +- `/toolchain:lint` states the workflow-security scan itself. With a zizmor config at the root or + under `.github/` and workflow files present, a check-mode run runs `zizmor --offline .` and + reports a `workflow-security` row. A finding is advisory and fails nothing. + +### Changed + +- `/toolchain:check` keeps its retry, seed and slow-test reporting rules in the skill, written for + any test runner. The description now says what the skill runs: the project's own commands only. diff --git a/plugins/toolchain/README.md b/plugins/toolchain/README.md index d7f88ab10a0..6b18684817a 100644 --- a/plugins/toolchain/README.md +++ b/plugins/toolchain/README.md @@ -2,8 +2,8 @@ A Claude Code plugin for **polyglot build/test/lint verification**. Detect the ecosystems a change touches and run the right build, test, and lint commands for -each, with the consuming project's own documented commands overriding portable -defaults. Four skills: three for mechanical verification of changed code, and +each, running only the commands the consuming project records or its build files +imply. Four skills: three for mechanical verification of changed code, and `/toolchain:ratchet`, which holds a count at a checked-in CI ceiling. | Skill | Role | @@ -22,13 +22,13 @@ restatement here. Command resolution follows the marketplace-wide ecosystem-commands convention (`docs/contracts/ecosystem-commands/README.md`; schema `ecosystem.schema.json`): your repo's tracked `.claude/ecosystems/.yaml` files are authoritative -when present, and the plugin's bundled portable defaults are the last resort of -an attended run. An unattended run (`--unattended`, a headless or lane run, or -one that cannot tell whether a person is present) runs only a recorded, stated -or inferred command and reports any other key as `skip (unresolved: ...)`. -Testing structure and commit conventions still come from your own `CLAUDE.md` and -rules. All command tables and per-ecosystem context ship inside the plugin via -`${CLAUDE_PLUGIN_ROOT}`; state and artifacts go to your project's own tree. +when present; otherwise an attended run infers commands from your build files or +asks. The plugin ships no default command. An unattended run (`--unattended`, a +headless or lane run, or one that cannot tell whether a person is present) runs +only a recorded, stated or inferred command. Either kind of run reports a key +nothing resolves as `skip (unresolved: ...)`. Testing structure and commit +conventions still come from your own `CLAUDE.md` and rules. State and artifacts +go to your project's own tree. ## Install diff --git a/plugins/toolchain/evals/ck-consumer-config-wins/case.yaml b/plugins/toolchain/evals/ck-consumer-config-wins/case.yaml index 4966c70ab96..87f90b028d9 100644 --- a/plugins/toolchain/evals/ck-consumer-config-wins/case.yaml +++ b/plugins/toolchain/evals/ck-consumer-config-wins/case.yaml @@ -17,4 +17,4 @@ graders: arm: both - name: meets-expectations type: llm - criteria: 'The run checks a .NET repository whose tracked .claude/ecosystems/dotnet.yaml declares its own commands. It meets the legacy expectations: "Resolves commands via the ladder with the consumer''s `.claude/ecosystems/dotnet.yaml` taking precedence (rung 1)" "Uses the bundled portable default only as the rung-4 fallback when no consumer file is present" "Runs the consumer''s declared test-cmd, not the bundled default''s".' + criteria: 'The run checks a .NET repository whose tracked .claude/ecosystems/dotnet.yaml declares its own commands. It meets the legacy expectations: "Resolves commands via the ladder with the consumer''s `.claude/ecosystems/dotnet.yaml` taking precedence (rung 1)" "Runs the consumer''s declared test-cmd, not a plain `dotnet test` or `dotnet build` of its own".' diff --git a/plugins/toolchain/evals/ck-consumer-config-wins/prompt.md b/plugins/toolchain/evals/ck-consumer-config-wins/prompt.md index 97ed0fa3b0b..20ca20499dc 100644 --- a/plugins/toolchain/evals/ck-consumer-config-wins/prompt.md +++ b/plugins/toolchain/evals/ck-consumer-config-wins/prompt.md @@ -1,5 +1,5 @@ --- -description: "Legacy check 3. The tracked .claude/ecosystems/dotnet.yaml is rung 1 and authoritative: its project-specific test-cmd runs (it logs `dotnet test` to .calls.log through tools/run.sh), and the bundled `dotnet test` / `dotnet build` never run. ran-consumer-test reads .calls.log, no-bundled-dotnet the Bash calls; meets-expectations (llm) quotes the legacy expectations. Needs --scaffold --allow-tools Bash." +description: "Legacy check 3. The tracked .claude/ecosystems/dotnet.yaml is rung 1 and authoritative: its project-specific test-cmd runs (it logs `dotnet test` to .calls.log through tools/run.sh), and a plain `dotnet test` / `dotnet build` never runs. ran-consumer-test reads .calls.log, no-bundled-dotnet the Bash calls; meets-expectations (llm) quotes the legacy expectations. Needs --scaffold --allow-tools Bash." tags: [toolchain, check, resolution-ladder, scaffold, no-network] max_turns: 30 timeout_seconds: 600 diff --git a/plugins/toolchain/evals/ck-unattended-inferred-runs/samples/logged-assumed.json b/plugins/toolchain/evals/ck-unattended-inferred-runs/samples/logged-assumed.json index fba90f271db..7127a3630ec 100644 --- a/plugins/toolchain/evals/ck-unattended-inferred-runs/samples/logged-assumed.json +++ b/plugins/toolchain/evals/ck-unattended-inferred-runs/samples/logged-assumed.json @@ -5,7 +5,7 @@ ], "fail": [ {"answer": "assumed: typescript.test-cmd=npm test", "why": "no source named"}, - {"answer": "assumed: typescript.test-cmd=npx vitest run (reference/ecosystems/typescript.yaml:13)", "why": "the bundled default, not the inferred script"}, + {"answer": "assumed: typescript.test-cmd=npx vitest run (vitest.config.ts:1)", "why": "a runner chosen for the repo, not the inferred script"}, {"answer": "Inferred typescript: globs *.js, package.json", "why": "no assumed: line"} ] } diff --git a/plugins/toolchain/evals/ck-unattended-stated-unresolved/samples/logged-assumed.json b/plugins/toolchain/evals/ck-unattended-stated-unresolved/samples/logged-assumed.json index b0b42c70ab3..53df5d4cd16 100644 --- a/plugins/toolchain/evals/ck-unattended-stated-unresolved/samples/logged-assumed.json +++ b/plugins/toolchain/evals/ck-unattended-stated-unresolved/samples/logged-assumed.json @@ -6,6 +6,6 @@ "fail": [ {"answer": "assumed: bash.check-cmd=bash tools/run.sh bash check ", "why": "no source named"}, {"answer": "Ran bash tools/run.sh bash check scripts/app.sh, stated in CLAUDE.md.", "why": "not an assumed: line"}, - {"answer": "assumed: bash.check-cmd=shellcheck (reference/ecosystems/bash.yaml:7)", "why": "sourced from the bundled default"} + {"answer": "assumed: bash.check-cmd=shellcheck (.github/workflows/ci.yml:7)", "why": "copied from a CI workflow file, not stated"} ] } diff --git a/plugins/toolchain/evals/ck-unattended-stated-unresolved/samples/no-record-write.json b/plugins/toolchain/evals/ck-unattended-stated-unresolved/samples/no-record-write.json index 28c21f85e83..d77de3bc12e 100644 --- a/plugins/toolchain/evals/ck-unattended-stated-unresolved/samples/no-record-write.json +++ b/plugins/toolchain/evals/ck-unattended-stated-unresolved/samples/no-record-write.json @@ -1 +1 @@ -{"pass": [{"answer": [{"tool": "Bash", "input": {"command": "ls .claude/ecosystems/ 2>/dev/null"}}]}, {"answer": [{"tool": "Bash", "input": {"command": "cat /tmp/w/.claude/ecosystems/bash.yaml 2>&1"}}], "why": "a read, not a write"}], "fail": [{"answer": [{"tool": "Bash", "input": {"command": "printf 'globs: [\"*.sh\"]\\n' > .claude/ecosystems/bash.yaml"}}]}, {"answer": [{"tool": "Bash", "input": {"command": "echo x | tee -a /w/.claude/ecosystems/markdown.yaml"}}]}, {"answer": [{"tool": "Bash", "input": {"command": "cp plugin/reference/ecosystems/markdown.yaml .claude/ecosystems/markdown.yaml"}}]}]} +{"pass": [{"answer": [{"tool": "Bash", "input": {"command": "ls .claude/ecosystems/ 2>/dev/null"}}]}, {"answer": [{"tool": "Bash", "input": {"command": "cat /tmp/w/.claude/ecosystems/bash.yaml 2>&1"}}], "why": "a read, not a write"}], "fail": [{"answer": [{"tool": "Bash", "input": {"command": "printf 'globs: [\"*.sh\"]\\n' > .claude/ecosystems/bash.yaml"}}]}, {"answer": [{"tool": "Bash", "input": {"command": "echo x | tee -a /w/.claude/ecosystems/markdown.yaml"}}]}, {"answer": [{"tool": "Bash", "input": {"command": "cp /tmp/markdown.yaml .claude/ecosystems/markdown.yaml"}}]}]} diff --git a/plugins/toolchain/evals/ck-unsure-run-is-unattended/samples/no-record-write.json b/plugins/toolchain/evals/ck-unsure-run-is-unattended/samples/no-record-write.json index 47856674c4f..8c4e441e90f 100644 --- a/plugins/toolchain/evals/ck-unsure-run-is-unattended/samples/no-record-write.json +++ b/plugins/toolchain/evals/ck-unsure-run-is-unattended/samples/no-record-write.json @@ -1 +1 @@ -{"pass": [{"answer": [{"tool": "Bash", "input": {"command": "ls .claude/ecosystems/ 2>/dev/null"}}]}], "fail": [{"answer": [{"tool": "Bash", "input": {"command": "printf 'globs: [\"*.md\"]\\n' >> .claude/ecosystems/markdown.yaml"}}]}, {"answer": [{"tool": "Bash", "input": {"command": "cp plugin/reference/ecosystems/markdown.yaml .claude/ecosystems/"}}]}]} +{"pass": [{"answer": [{"tool": "Bash", "input": {"command": "ls .claude/ecosystems/ 2>/dev/null"}}]}], "fail": [{"answer": [{"tool": "Bash", "input": {"command": "printf 'globs: [\"*.md\"]\\n' >> .claude/ecosystems/markdown.yaml"}}]}, {"answer": [{"tool": "Bash", "input": {"command": "cp /tmp/markdown.yaml .claude/ecosystems/"}}]}]} diff --git a/plugins/toolchain/reference/ecosystems/bash.yaml b/plugins/toolchain/reference/ecosystems/bash.yaml deleted file mode 100644 index 7f8dbc062aa..00000000000 --- a/plugins/toolchain/reference/ecosystems/bash.yaml +++ /dev/null @@ -1,10 +0,0 @@ -# Bundled portable default — bash. Rung-4 fallback only (consumer -# .claude/ecosystems/bash.yaml overrides key-by-key). Contract + schema: -# https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/ecosystem-commands/README.md -globs: ["*.sh", "*.bash"] -build-cmd: null # no build step -test-cmd: null # run the project's shell-test runner when it documents one (bats, or a *.test.sh convention) -check-cmd: "shellcheck -x -S warning && shfmt -d " -fix-cmd: "shfmt -w " # shellcheck has no fix mode -opt-in: "shellcheck always applies to shell files; shfmt only when .editorconfig declares shell style" -install-hint: "winget install ShellCheck.ShellCheck mvdan.shfmt | brew install shellcheck shfmt" diff --git a/plugins/toolchain/reference/ecosystems/cross-cutting.yaml b/plugins/toolchain/reference/ecosystems/cross-cutting.yaml deleted file mode 100644 index d4263c5ebe3..00000000000 --- a/plugins/toolchain/reference/ecosystems/cross-cutting.yaml +++ /dev/null @@ -1,24 +0,0 @@ -# Bundled portable default — cross-cutting (repo-wide text checks). Rung-4 -# fallback only (consumer .claude/ecosystems/cross-cutting.yaml overrides key-by-key). Contract + schema: -# https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/ecosystem-commands/README.md -# Lint-only surface: /toolchain:lint runs it (alongside detected ecosystems when any text -# file changed and the repo opts into its tools); /toolchain:check does not run it — its -# `**` glob would otherwise match every change in build detection. -globs: ["**"] # any text file change -build-cmd: null -test-cmd: null -check-cmd: | - typos - gitleaks detect --source . --redact --no-banner --no-git - # editorconfig-checker — binary name varies by install method (ec / editorconfig-checker / ec-windows-amd64) - "$EC_BIN" - # lychee-offline — on-disk link/anchor integrity; --offline = no network (external URLs skipped) - lychee --offline --no-progress './**/*.md' -fix-cmd: null -opt-in: "each tool's own config at repo root (_typos.toml, .gitleaks.toml, .editorconfig-checker.json / .editorconfig, lychee.toml)" -install-hint: | - typos: winget install Crate-CI.Typos | brew install typos-cli - gitleaks: winget install Gitleaks.Gitleaks | brew install gitleaks - editorconfig-checker: winget install EditorConfig-Checker.EditorConfig-Checker | brew install editorconfig-checker - lychee: winget install lycheeverse.lychee | brew install lychee -notes: "Lint-only — owned by /toolchain:lint. /toolchain:check does not run this ecosystem." diff --git a/plugins/toolchain/reference/ecosystems/dotnet.yaml b/plugins/toolchain/reference/ecosystems/dotnet.yaml deleted file mode 100644 index 0722bb8593d..00000000000 --- a/plugins/toolchain/reference/ecosystems/dotnet.yaml +++ /dev/null @@ -1,35 +0,0 @@ -# Bundled portable default — dotnet. Rung-4 fallback only (a consuming repo's -# .claude/ecosystems/dotnet.yaml overrides this key-by-key; this file is never -# written into a consumer repo). Ecosystem-commands contract + schema: -# https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/ecosystem-commands/README.md -# -# opt-in rationale: dotnet format's own docs state preferences are read from -# .editorconfig "if present, otherwise a default set of preferences will be -# used" (https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-format) — -# verified empirically (dotnet SDK 10.0.302) that a project with no -# .editorconfig still gets `dotnet format --verify-no-changes` failures -# (Roslyn's built-in whitespace conventions apply unconditionally). Gated on -# a section that actually reaches .cs files (a universal `[*]`, or a -# C#-specific glob like `[*.cs]`/`[*.{cs,vb}]`), not bare file presence, -# mirroring bash.yaml's "shfmt only when .editorconfig declares shell style" -# precision — a .editorconfig with only unrelated globs (e.g. `[*.md]`, no -# `[*]`) verifiably has zero effect on dotnet format's output (empirically -# confirmed: exit 0, no diagnostics) and shouldn't count as configured .NET -# style. EnableNETAnalyzers was considered and rejected as a signal: it -# defaults to true for .NET 5+, so its presence is not meaningful. -# -# The walk stops at a `root = true` marker even when that file has no -# C#-relevant section — EditorConfig discovery itself stops there (verified -# empirically: an outer repo-root `[*]` section has zero effect on a nested -# .cs file once a `root = true` .editorconfig sits between them), so a -# parent section beyond that marker is never actually consulted by dotnet -# format and must not count toward this opt-in either. Same discipline as -# bash-format.sh's shell_editorconfig_opt_in() walk elsewhere in this repo. -globs: ["*.cs", "*.csproj", "*.sln", "*.slnx", "*.props", "*.targets"] -anchor: "the solution file at repo root (*.slnx or *.sln); when none exists, the nearest *.csproj above the changed files" -build-cmd: 'dotnet build ""' -test-cmd: 'dotnet test "" --no-build' -check-cmd: 'dotnet format "" --verify-no-changes' -fix-cmd: 'dotnet format ""' -opt-in: ".editorconfig with a [*] or C#-glob section, walked from the changed file up to the repo root or a `root = true` marker (whichever comes first) — otherwise dotnet format applies Roslyn's built-in defaults unconditionally" -install-hint: "Install .NET SDK from https://dot.net" diff --git a/plugins/toolchain/reference/ecosystems/go.yaml b/plugins/toolchain/reference/ecosystems/go.yaml deleted file mode 100644 index 31cb4ec8a59..00000000000 --- a/plugins/toolchain/reference/ecosystems/go.yaml +++ /dev/null @@ -1,46 +0,0 @@ -# Bundled portable default — go. Rung-4 fallback only (a consuming repo's -# .claude/ecosystems/go.yaml overrides this key-by-key; this file is never -# written into a consumer repo). Ecosystem-commands contract + schema: -# https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/ecosystem-commands/README.md -# -# project-discovery: a root go.mod bounds `./...` package-pattern expansion — -# verified empirically (Go 1.26.5) that go build/test/list ./... from a repo -# root silently skip a nested module's packages (a nested go.mod, or even a -# root go.work listing both modules, does not cross that boundary for `...` -# expansion). Without walking to each go.mod, a monorepo with a nested Go -# module gets silent incomplete build/test/lint. -# -# go-mod-tidy-drift trigger-globs includes *.go, not just go.mod/go.sum: -# `go mod tidy` can flag drift from a source-only edit (e.g. removing the -# last usage of a dependency leaves go.mod over-declared) that `go build`/ -# `go test` do not fail on, so scoping the gate to go.mod/go.sum changes -# alone would miss exactly the CI/local-parity gap this ecosystem entry -# exists to close. -# -# opt-in rationale: golangci-lint v2 with no config file present still runs -# its own fixed "standard" linter preset (linters.default: standard) rather -# than erroring or running nothing — i.e. it imposes an opinionated -# diagnostic set nobody explicitly chose, the same risk class the dotnet -# ecosystem's opt-in gate addresses for unconfigured Roslyn formatting -# defaults, and consistent with python's ruff gate below. Note: unlike -# dotnet's EditorConfig discovery, golangci-lint's own config search has no -# root-boundary marker — it walks from the target up to the filesystem root -# and then falls back to the user's home directory, so a stray -# ~/.golangci.yml can make a local run diverge from a clean CI container -# (documented in context/go.md, not addressed by this opt-in gate, which only -# ceilings the *this-plugin's* opt-in check at the repo root). -globs: ["*.go", "go.mod", "go.sum"] -project-discovery: ["go.mod"] -build-cmd: "go build ./..." -test-cmd: "go test ./..." -check-cmd: "golangci-lint run ./..." -fix-cmd: "gofmt -w " # format-only; agent substitutes only *.go from (never go.mod/go.sum) -code-fix-cmd: "golangci-lint run --fix " # *.go only; invoke once per package directory (see lint SKILL.md) -opt-in: ".golangci.yml, .golangci.yaml, .golangci.toml, or .golangci.json present (walked from the changed file up to the repo root) — otherwise golangci-lint applies its own unconfigured \"standard\" linter preset unconditionally" -install-hint: "Install golangci-lint: https://golangci-lint.run/docs/welcome/install/ | Go toolchain: https://go.dev/dl/" -gates: - - name: go-mod-tidy-drift - cmd: "go mod tidy -diff" - trigger-globs: ["go.mod", "go.sum", "*.go"] - remediation: "Run go mod tidy and commit the updated go.mod/go.sum. (go mod tidy -diff requires Go 1.23+; an older toolchain rejects the flag, so the gate reports skip rather than drift.)" -notes: "gofmt / golangci-lint --fix receive only *.go paths from , grouped by package directory for golangci-lint. govulncheck is intentionally not a rung-4 default — add it as a consumer-local gate via .claude/ecosystems/go.local.yaml if desired." diff --git a/plugins/toolchain/reference/ecosystems/markdown.yaml b/plugins/toolchain/reference/ecosystems/markdown.yaml deleted file mode 100644 index 2e1cae42121..00000000000 --- a/plugins/toolchain/reference/ecosystems/markdown.yaml +++ /dev/null @@ -1,10 +0,0 @@ -# Bundled portable default — markdown. Rung-4 fallback only (consumer -# .claude/ecosystems/markdown.yaml overrides key-by-key). Contract + schema: -# https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/ecosystem-commands/README.md -globs: ["*.md"] -build-cmd: null # lint-only ecosystem -test-cmd: null -check-cmd: "npx markdownlint-cli2 " # when the project has a markdownlint config -fix-cmd: "npx markdownlint-cli2 --fix " -opt-in: "a markdownlint config (.markdownlint*, .markdownlint-cli2.*)" -install-hint: "npm i -g markdownlint-cli2" diff --git a/plugins/toolchain/reference/ecosystems/powershell.yaml b/plugins/toolchain/reference/ecosystems/powershell.yaml deleted file mode 100644 index e7febeacf74..00000000000 --- a/plugins/toolchain/reference/ecosystems/powershell.yaml +++ /dev/null @@ -1,10 +0,0 @@ -# Bundled portable default — powershell. Rung-4 fallback only (consumer -# .claude/ecosystems/powershell.yaml overrides key-by-key). Contract + schema: -# https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/ecosystem-commands/README.md -globs: ["*.ps1", "*.psm1"] -build-cmd: null # no build step -test-cmd: null # run the project's Pester suite when it documents one (Invoke-Pester) -check-cmd: "pwsh -NoProfile -Command 'Invoke-ScriptAnalyzer -Path . -Recurse'" -fix-cmd: null # PSScriptAnalyzer has no bulk fix mode -opt-in: "PSScriptAnalyzerSettings.psd1 (or any PowerShell files with pwsh available)" -install-hint: "Install-Module -Name PSScriptAnalyzer (pwsh)" diff --git a/plugins/toolchain/reference/ecosystems/python.yaml b/plugins/toolchain/reference/ecosystems/python.yaml deleted file mode 100644 index a93cbf8a3ca..00000000000 --- a/plugins/toolchain/reference/ecosystems/python.yaml +++ /dev/null @@ -1,18 +0,0 @@ -# Bundled portable default — python. Rung-4 fallback only (consumer -# .claude/ecosystems/python.yaml overrides key-by-key). Contract + schema: -# https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/ecosystem-commands/README.md -# -# fix-cmd is format-only (ruff format). Code-changing autofixes (ruff check -# --fix) live in code-fix-cmd and require /toolchain:lint --code-fix plus -# that skill's confirmation / --yes gate. --unfixable F401 matches the -# python-format hook: protects just-added imports during iterative editing; -# F401 still surfaces as a finding — only auto-deletion is suppressed. -globs: ["*.py", "pyproject.toml", "uv.lock", "pyrightconfig.json"] -project-discovery: ["pyproject.toml"] -build-cmd: null # no separate build step; lint/test cover verification -test-cmd: "uv run pytest -x -q" # plain pytest when the project doesn't use uv -check-cmd: "uv run ruff check . --no-fix && uv run ruff format . --check && uv run pyright" -fix-cmd: "uv run ruff format " # format-only; pyright has no fix mode -code-fix-cmd: "uv run ruff check --fix --no-unsafe-fixes --unfixable F401" -opt-in: "ruff config (ruff.toml, .ruff.toml, or pyproject.toml [tool.ruff])" -install-hint: "pip install ruff pyright uv | brew install uv ruff pyright | winget install astral-sh.uv" diff --git a/plugins/toolchain/reference/ecosystems/typescript.yaml b/plugins/toolchain/reference/ecosystems/typescript.yaml deleted file mode 100644 index 2470e387368..00000000000 --- a/plugins/toolchain/reference/ecosystems/typescript.yaml +++ /dev/null @@ -1,18 +0,0 @@ -# Bundled portable default — typescript. Rung-4 fallback only (consumer -# .claude/ecosystems/typescript.yaml overrides key-by-key). Contract + schema: -# https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/ecosystem-commands/README.md -# -# fix-cmd is format-only (biome format). biome check --write applies lint -# autofixes and lives in code-fix-cmd behind /toolchain:lint --code-fix. -# -# The Biome commands name the scoped @biomejs/biome: the unscoped npm package -# "biome" is unrelated, and npx fetches it when the project has no local install. -globs: ["*.ts", "*.tsx", "*.js", "*.jsx", "*.mjs", "package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock", "tsconfig*.json"] -project-discovery: ["package.json"] -build-cmd: "npx tsc --noEmit" # when the project has a tsconfig; otherwise the package.json build script -test-cmd: "the package.json test script (npm test / npx vitest run / npx jest — use what the project configures)" -check-cmd: "npx @biomejs/biome check ." # biome.json present; use eslint when the project configures it instead -fix-cmd: "npx @biomejs/biome format --write " -code-fix-cmd: "npx @biomejs/biome check --write " -opt-in: "biome.json → Biome; eslint config → ESLint (use whichever the project configures)" -install-hint: "project-local devDependencies preferred; npm i -g typescript @biomejs/biome" diff --git a/plugins/toolchain/reference/ecosystems/yaml.yaml b/plugins/toolchain/reference/ecosystems/yaml.yaml deleted file mode 100644 index 21140ae1cad..00000000000 --- a/plugins/toolchain/reference/ecosystems/yaml.yaml +++ /dev/null @@ -1,18 +0,0 @@ -# Bundled portable default — yaml (GitHub Actions workflows). Rung-4 fallback -# only (consumer .claude/ecosystems/yaml.yaml overrides key-by-key). Contract + schema: -# https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/ecosystem-commands/README.md -# Lint-only surface: /toolchain:lint runs it; /toolchain:check does not (no build/test phase). -globs: [".github/**/*.yml", ".github/**/*.yaml"] -build-cmd: null -test-cmd: null -check-cmd: | - actionlint # no args — discovers all workflow files itself (.yml and .yaml) - # plus any schema checks the project documents (check-jsonschema against its own config files) - # zizmor workflow-security scan when the project uses it — advisory only -fix-cmd: null -opt-in: "GitHub Actions workflows present" -install-hint: | - actionlint: winget install rhysd.actionlint | brew install actionlint - check-jsonschema: pip install check-jsonschema - zizmor: pip install zizmor -notes: "Lint-only — owned by /toolchain:lint. /toolchain:check does not run this ecosystem." diff --git a/plugins/toolchain/reference/resolution-ladder.md b/plugins/toolchain/reference/resolution-ladder.md index cc7f0144011..7dc9729020e 100644 --- a/plugins/toolchain/reference/resolution-ladder.md +++ b/plugins/toolchain/reference/resolution-ladder.md @@ -15,7 +15,7 @@ conforming to the contract's `ecosystem.schema.json`. Command keys are **opaque - `test-cmd`: test command; `null` when no test framework is wired - `test-changed-cmd`: optional change-scoped test command over ``. `/toolchain:check` runs it in place of `test-cmd` for a change, and `test-cmd` under `all` or when `` is empty. - The repository's CI calls the same recorded command. No bundled default sets it. + The repository's CI calls the same recorded command. - `check-cmd`: lint/format check, no file modification; `null` when lint does not apply - `fix-cmd`: **format-only** auto-fix (whitespace / import layout / style); `null` when absent. Must not apply semantic/code-changing lint autofixes. `/toolchain:lint --fix` runs this key. @@ -40,14 +40,26 @@ holds: - **Recorded.** A `.yaml` or `.local.yaml` exists at any rung-1 layer (user-global, team or personal override), whatever the id. +- **Stated.** The repository's own instructions (the files "Unattended runs" lists under + Stated) name a command for the id. Its globs are the file types that command checks. - **Inferred this run.** Rung 2 inferred a command surface for the id from the repo's build files - in this run. The report names each inferred id with the globs inferred for it, on one line per + in this run. In a repository with no ecosystem record at any layer, a changed file's own + language or format, read from its extension, also infers its id, with that type's extensions as + its globs. The report names each inferred id with the globs inferred for it, on one line per id: `Inferred : globs , `. -- **Bundled.** A bundled portable default ships for the id. -Before detection, `all` or an ecosystem filter, look for build files of ecosystems that are neither -recorded nor bundled (a `Cargo.toml`, a `Gemfile`, a `pom.xml`) and run rung 2 for each id they -point to, so an inferred id joins the set before any glob is matched or any filter is checked. +Name a stated or inferred id by the id the skills' aliases resolve to where one fits (`dotnet`, +`python`, `typescript` for a JavaScript or TypeScript package, `bash` for shell, `powershell`, +`markdown`, `go`), else by the language or format's lowercase kebab-case name. The plugin ships no +ecosystem file, so no id is covered unless it is recorded, stated or inferred. Once a repository +records any ecosystem, a file type it neither records, states nor has a build file for is outside +every ecosystem. + +Before detection, `all` or an ecosystem filter, look for build files of ecosystems that are not +recorded (a `Cargo.toml`, a `pyproject.toml`, a `package.json`) and run rung 2 for each id they +point to. Add each stated id, and in a repository with no record, each id a changed file's type +infers. So a stated or inferred id joins the set before any glob is matched or any filter is +checked. Detection, `all`, an ecosystem filter and the files-outside-every-ecosystem rule all read this set. An unattended run takes only the id and its globs from this pass, offers nothing, and resolves the id's commands by "Unattended runs" below. @@ -56,9 +68,10 @@ A filter naming an id that is still not covered after that pass goes to rung 3: `/toolchain:setup` to record it. With nobody to ask, run nothing for it and report `: no record and nothing to infer it from`. -## Resolution per ecosystem (four rungs) +## Resolution per ecosystem (three rungs) -Resolve each ecosystem independently, in order; stop at the first rung that yields a command surface: +Resolve each ecosystem independently, and within it each command key the run will execute, in +order; stop at the first rung that yields it: 1. **Consumer file present → authoritative.** Read `.claude/ecosystems/.yaml` in the consuming repo. Layer additively, **per key**, in this order. A later layer overrides earlier @@ -69,21 +82,25 @@ Resolve each ecosystem independently, in order; stop at the first rung that yiel (solution files, `pyproject.toml`, `package.json`, …) and **offer to write** the inferred `.claude/ecosystems/.yaml` via `/toolchain:setup` so the next run reads rung 1. 3. **Cannot infer → ask.** Ask the user for the command; offer to persist it via `/toolchain:setup`. -4. **Otherwise → bundled portable default.** Use the schema-conformant file shipped at - [`${CLAUDE_PLUGIN_ROOT}/reference/ecosystems/.yaml`](ecosystems/). These are a - **fallback only**, never a peer source of truth, and never written into a consumer repo outside - the `/toolchain:setup` interview or a persisted inference. + +**Nothing resolved → report it unresolved.** When no rung yields a command for a key, run nothing +in its place. Its cell reads `skip (unresolved: .)`, an environment skip that +leaves the run `INCOMPLETE`, with one line below the table naming the files read. The plugin +ships no default command to fall back to. **`enabled: false` → skip the ecosystem.** After resolution, an ecosystem whose resolved `enabled` is `false` is not run. Detection skips it and it is excluded even from `all`. This is the consumer's -opt-out; bundled defaults never set it. (A later layer can also flip `enabled` back to `true` -per-key.) +opt-out. (A later layer can also flip `enabled` back to `true` per-key.) **Malformed consumer file → warn and degrade to rung 2**, never a hard stop: surface the parse/schema error, then infer as if the file were absent. (Consuming repos should validate their own files against -the schema in a gate; plugins fail soft.) Unknown keys are inert. In an attended run, missing -optional keys fall back to defaults. An unattended run never falls back to a bundled default for a -key the record leaves out: see "Unattended runs" below. +the schema in a gate; plugins fail soft.) Unknown keys are inert. A command key the run will +execute that the record leaves out goes on to rungs 2 and 3 for that key in an attended run, and to +the stated and inferred sources in an unattended run (see "Unattended runs" below). A key the run +does not execute (`fix-cmd` and `code-fix-cmd` in a check run) is never inferred or asked for. In +an attended run, `test-changed-cmd` and `lint-cmd` are not inferred or asked for either: each runs +only when recorded, and its absence leaves `test-cmd` or `check-cmd` to run. `gates` come only from +a record or the project's documented conventions, never from inference or a question. ## Run kind @@ -100,7 +117,7 @@ ecosystem-resolution contract's detector: no such message. 3. Otherwise the run is unattended. A run that cannot tell counts as unattended. -An attended run uses the four rungs above. An unattended run uses the next section in their place. +An attended run uses the three rungs above. An unattended run uses the next section in their place. ## Unattended runs @@ -124,20 +141,15 @@ in this order, stopping at the first that yields it: manager. Outside a git repository, or when git cannot list the files, every lockfile present counts. -Nothing else supplies a command. An unattended run never asks (rung 3), never runs a bundled -default's command or gate (rung 4), and copies no command text out of a CI workflow file. A bundled -default still supplies its `globs`, so a changed file reaches its ecosystem's row; none of its other -keys apply, a key it sets to `null` included. A malformed record degrades to the stated and -inferred sources. +Nothing else supplies a command. An unattended run never asks (rung 3) and copies no command text +out of a CI workflow file. A malformed record degrades to the stated and inferred sources. - **Log each command as assumed.** Before a resolved command runs, print one line for it: `assumed: .= (:)`, naming the record line, the stating line or the implying line. Repeat every `assumed:` line below the report's table. - **Report what stays unresolved.** A key no source resolved does not run, and nothing runs in its place. Its cell reads `skip (unresolved: .)`, an environment skip that leaves the - run `INCOMPLETE`, with one line below the table naming the files read. A gate only the bundled - default ships does not run: it is listed on the `Gates:` line with - `skip (unresolved: .gates)`. + run `INCOMPLETE`, with one line below the table naming the files read. - **A tie is unresolved.** Two or more candidates for one key with nothing in the repository to choose between them: run none, report the key's cell as unresolved, and name every candidate with its file below the table. diff --git a/plugins/toolchain/skills/check/SKILL.md b/plugins/toolchain/skills/check/SKILL.md index ee3db3bdba5..08251e3055d 100644 --- a/plugins/toolchain/skills/check/SKILL.md +++ b/plugins/toolchain/skills/check/SKILL.md @@ -1,5 +1,5 @@ --- -description: "Build, test, and lint verification for changed files across detected ecosystems (.NET, Python, TypeScript, Go, Bash, PowerShell, Markdown), with the project's own commands overriding bundled defaults. Use when: 'does it compile', 'run tests', 'build it', 'run the tests', 'does this still build', 'check it', or after any code edit. Lint only: /toolchain:lint; outcome verification: /verification:confirm." +description: "Build, test, and lint verification for changed files in each ecosystem the repository records or its build files imply, running only the project's own commands and reporting any it cannot resolve. Use when: 'does it compile', 'run tests', 'build it', 'run the tests', 'does this still build', 'check it', or after any code edit. Lint only: /toolchain:lint; outcome verification: /verification:confirm." user-invocable: true disable-model-invocation: false argument-hint: "[ecosystem] [--unattended]" @@ -23,23 +23,18 @@ Keep the bound in the pipe; a read-time cap bounds nothing. Treat a failure (not Detects the ecosystems the changed files touch and runs each one's build → test → lint. Run it as `/toolchain:check` or `/toolchain:check `. `/toolchain:lint`, `/verification:confirm` (when enabled) and verification agents compose it for detection and command resolution instead of keeping their own tables. -Commands are resolved, not hardcoded: the four-rung ladder in [`${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md`](${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md) reads the consuming repo's tracked `.claude/ecosystems/.yaml` first; the bundled defaults at `${CLAUDE_PLUGIN_ROOT}/reference/ecosystems/` are the last-rung fallback of an attended run only. The consumer's file always wins. +Commands are resolved, not hardcoded: the three-rung ladder in [`${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md`](${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md) reads the consuming repo's tracked `.claude/ecosystems/.yaml` first, then infers from its build files, then asks. The plugin ships no default command: a key nothing resolves is reported unresolved and runs nothing. ## Arguments -`$ARGUMENTS` is an optional ecosystem filter: any covered ecosystem id, meaning one with a record, one inferred this run, or one with a bundled default ([resolution ladder](${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md) "Covered ecosystems"), except the lint-only `yaml` and `cross-cutting`. The bundled defaults this skill runs are `dotnet`, `python`, `typescript`, `bash`, `powershell`, `markdown`, `go`; a consumer record such as `.claude/ecosystems/rust.yaml` makes `rust` a filter too. Aliases: `ts`/`node` → `typescript`, `shell` → `bash`, `ps`/`pwsh` → `powershell`, `md` → `markdown`, `golang` → `go`. Literal `all` runs every covered ecosystem. The lint-only `yaml` and `cross-cutting` surfaces belong to `/toolchain:lint`; this skill never runs them (and never matches `cross-cutting`'s `**` glob). +`$ARGUMENTS` is an optional ecosystem filter: any covered ecosystem id, meaning one recorded, stated or inferred this run ([resolution ladder](${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md) "Covered ecosystems"), except the lint-only `yaml` and `cross-cutting`. A consumer record such as `.claude/ecosystems/rust.yaml` makes `rust` a filter. Aliases: `ts`/`node` → `typescript`, `shell` → `bash`, `ps`/`pwsh` → `powershell`, `md` → `markdown`, `golang` → `go`. Literal `all` runs every covered ecosystem. The lint-only `yaml` and `cross-cutting` surfaces belong to `/toolchain:lint`; this skill never runs them (and never matches `cross-cutting`'s `**` glob). `--unattended` marks the run unattended; strip it before reading the ecosystem filter. A run without it is still unattended when the ladder's "Run kind" says so, including a run that cannot tell whether a person is present. An unattended run resolves commands by the ladder's "Unattended runs": it runs only a recorded, stated or inferred command, logs each as `assumed:` with its source, asks nothing, installs nothing, writes no `.claude/ecosystems/` record, and reports a key nothing resolved, or a tie, as `skip (unresolved: .)`. -Per-ecosystem gotchas and primary-source detail, read for each ecosystem that runs: +Read on demand: -- [context/dotnet.md](context/dotnet.md). .NET build, test, format +- [context/gates.md](context/gates.md). CI-parity gates - [context/sarif.md](context/sarif.md). Roslyn SARIF output, jq parser patterns, AI consumption -- [context/python.md](context/python.md). Python lint, format, test -- [context/typescript.md](context/typescript.md). TypeScript compile, test, lint -- [context/bash.md](context/bash.md). ShellCheck, shfmt -- [context/powershell.md](context/powershell.md). PSScriptAnalyzer -- [context/go.md](context/go.md). Go build, test, lint, module discovery ## Workflow @@ -51,7 +46,7 @@ All commands use absolute paths. Never `cd` and lose context. ### 1. Detect ecosystems -First add each ecosystem the repo's build files infer, per the ladder's "Covered ecosystems". With an ecosystem argument, use it; with `all`, run every covered ecosystem. Otherwise match the changed files from `git status --porcelain` against each covered ecosystem's resolved `globs`. When another skill calls this one with a changed-file list, use that list instead. Skip any ecosystem whose resolved `enabled` is `false`, even under `all`. +First add each ecosystem the repo's instructions state or its files infer, per the ladder's "Covered ecosystems". With an ecosystem argument, use it; with `all`, run every covered ecosystem. Otherwise match the changed files from `git status --porcelain` against each covered ecosystem's resolved `globs`. When another skill calls this one with a changed-file list, use that list instead. Skip any ecosystem whose resolved `enabled` is `false`, even under `all`. If the working tree is clean, fall back to the branch diff, so work already committed at green checkpoints still gets classified. Detect the default branch, never hardcode `main` or `master`, with this script as written: @@ -91,11 +86,10 @@ Resolve `globs`, `build-cmd`, `test-cmd`, `test-changed-cmd`, `check-cmd`, `lint 1. Consumer `.claude/ecosystems/.yaml` (+ `.local.yaml` personal override, `~/.claude/ecosystems/` user-global, additive per key) → authoritative. 2. Absent → infer from the repo's build files, name the inferred id and its globs in the report, and offer to persist via `/toolchain:setup`. 3. Cannot infer → ask; offer to persist. -4. Otherwise → the bundled default at `${CLAUDE_PLUGIN_ROOT}/reference/ecosystems/.yaml`. -A malformed consumer file warns and degrades to rung 2, never a hard stop. +A key no rung resolves runs nothing and reads `skip (unresolved: .)`. A malformed consumer file warns and degrades to rung 2, never a hard stop. -That ladder is the attended one. An unattended run (the ladder's "Run kind") takes the ladder's "Unattended runs" in its place: recorded, then stated, then inferred, and no rung 3 or 4. A key none of them resolves runs nothing and reads `skip (unresolved: .)`. +That ladder is the attended one. An unattended run (the ladder's "Run kind") takes the ladder's "Unattended runs" in its place: recorded, then stated, then inferred, and no rung 3. A key none of them resolves runs nothing and reads `skip (unresolved: .)`. ### 2. Run checks @@ -106,12 +100,12 @@ For each affected ecosystem run the resolved `build-cmd`, `test-cmd` and `check- - **Syntax only.** A command that only parses the files (`bash -n`, `python -m py_compile`, `node --check`) checks no behavior. It fills no Build or Test cell: report that cell `syntax only`. - **Failed to start.** Exit 126 or 127, a spawn or permission error, or a runner that aborted before running anything (an import error while collecting tests) produced no result. When the cause is missing declared dependencies, apply the install rule below; otherwise the cell is `FAIL` with the output shown. -**Passed on retry.** A test that failed and then passed on a rerun the project configures is a flaky result, not a clean pass. When the test output reports any, the Test cell reads `pass (flaky: N)`, the ecosystem Status `PASS (flaky: N)`, the Overall line adds the summed count (e.g. `Overall: PASS (2 of 2 ecosystems passed; flaky: 1)`), and each flaky test is named below the table. It does not make the run `FAIL`. `context/.md` records which output marks a retry-earned pass, and what to report when retries are configured but none is marked. +**Passed on retry.** A test that failed and then passed on a rerun the project configures is a flaky result, not a clean pass. When the test output reports any, the Test cell reads `pass (flaky: N)`, the ecosystem Status `PASS (flaky: N)`, the Overall line adds the summed count (e.g. `Overall: PASS (2 of 2 ecosystems passed; flaky: 1)`), and each flaky test is named below the table. It does not make the run `FAIL`. Count only what the runner's own output marks as a retried pass, such as a rerun or flaky count in its summary line. When the project's test config sets retries but the output does not separate a retried pass from a clean one, the Test cell reads `pass` with the line `retries configured, flaky count not reported` below the table, never a plain clean pass. A runner with no retry of its own earns a flaky count only from a retry wrapper the project documents. **Run signals to echo** below the table, from the same test output, when present: -- **Shuffle seed.** Any order or random seed the runner printed. When the project shuffles but the output hides the seed, say so and name the replay form from `context/.md`. -- **Slowest tests.** The runner's slowest-tests section, top entries only. When the output has none, one line names how the project turns it on (from `context/.md`). Never edit the resolved `test-cmd` to add it: command strings are opaque. +- **Shuffle seed.** Any order or random seed the runner printed. When the project shuffles but the output hides the seed (a quiet flag can hide the header that prints it), say so and name the runner's replay form, from the project's docs or the runner's own documentation. +- **Slowest tests.** The runner's slowest-tests section, top entries only. When the output has none, one line names the runner's own flag or config setting that turns it on, for the project's own `test-cmd` or test config. Never edit the resolved `test-cmd` to add it: command strings are opaque. **Missing declared dependencies.** When the ecosystem's tool is on `PATH` but a command cannot start because the project's declared dependencies are not installed (a package or module not found, a project not restored), install them once and rerun that command, within these limits: @@ -122,7 +116,7 @@ For each affected ecosystem run the resolved `build-cmd`, `test-cmd` and `check- - Never install a tool. A runner missing from `PATH` stays `skip (tool missing: )`. - Capture `git status --porcelain` and a hash of `git diff HEAD --binary` before the install and again after it, so a file that was already modified and changes again is caught. If either differs, stop the whole run and report `Overall: STOPPED (dependency install changed: )`. Run no further check: the tree is no longer the one under test. -**Tool presence.** Before each ecosystem runs, check that the tool its commands are invoked through is on `PATH` (python's `uv`, not the `ruff` and `pyright` behind it). Missing: report `skip (tool missing: )` with the ecosystem's `install-hint`, never `FAIL`. Do not probe the sub-tools inside a compound `check-cmd`: one that is absent fails at run time, and that real non-zero exit is reported as `FAIL`, unless the record declares it under `requires`. +**Tool presence.** Before each ecosystem runs, check that the tool its commands are invoked through is on `PATH` (the runner or wrapper the command starts with, not the tools it runs behind it). Missing: report `skip (tool missing: )` with the ecosystem's `install-hint`, never `FAIL`. Do not probe the sub-tools inside a compound `check-cmd`: one that is absent fails at run time, and that real non-zero exit is reported as `FAIL`, unless the record declares it under `requires`. **Declared prerequisites.** The resolved `requires` lists, per command key, what that command needs beyond its tool on `PATH`: a runtime package, or a tool at the build the repo pins for CI. After the tool-presence check passes, and after a single-condition `opt-in` is met (an unmet one skips `check-cmd` without probing), run each of the command's entries' `probe` before the command: one Bash call per probe with the Bash tool's `timeout` set to 30000, from `$REPO_ROOT`, or from each location the command runs from when the entry sets `run-from: ecosystem`, with `$REPO_ROOT` substituted. Exit 0 means present. Any other exit, a probe that cannot start, and one that times out mean absent, never `FAIL`. @@ -132,7 +126,7 @@ For each affected ecosystem run the resolved `build-cmd`, `test-cmd` and `check- - Never install a declared prerequisite and never run its `hint`, in any run. Compare no version yourself: the probe is the whole test, and `tool-pin` stays a drift warning. - A `gates[]` item's own `requires` applies the same way to that gate's `cmd` ([context/gates.md](context/gates.md)). -**Opt-in gate (lint phase only).** Before `check-cmd`, evaluate the resolved `opt-in` condition, if any; build and test always run. When `opt-in` is one condition for the whole `check-cmd` (e.g. dotnet, python, go; any ecosystem whose resolved `opt-in` has this shape), unmet means the Lint cell reads `skip (opt-in unmet: )` and `check-cmd` does not run; never omit it silently. When `opt-in` lists several per-tool conditions bundled in one command string (bash: shellcheck always, shfmt only with an `.editorconfig` shell style), run `check-cmd` whole and report its real output: a command string cannot be partly skipped. An opt-in skip counts toward the ecosystem total, never toward the FAIL count, and never blocks a "done" claim. +**Opt-in gate (lint phase only).** Before `check-cmd`, evaluate the resolved `opt-in` condition, if any; build and test always run. When `opt-in` is one condition for the whole `check-cmd` (such as one linter's config file being present), unmet means the Lint cell reads `skip (opt-in unmet: )` and `check-cmd` does not run; never omit it silently. When `opt-in` lists several per-tool conditions bundled in one command string (one tool always, another only with its own config present), run `check-cmd` whole and report its real output: a command string cannot be partly skipped. An opt-in skip counts toward the ecosystem total, never toward the FAIL count, and never blocks a "done" claim. **CI-parity gates.** When an affected ecosystem resolves a non-empty `gates` array, or the project documents CI-parity checks in its `CLAUDE.md`, `.claude/rules/` or a commands reference, read [context/gates.md](context/gates.md) and run them by its rules after build → test → lint. A gate runs even when an earlier phase failed, and a fired gate that fails makes the run `FAIL`. @@ -153,7 +147,7 @@ Gates: go-mod-tidy-drift — FAIL (run go mod tidy and commit the updated go.mod Overall: FAIL (1 of 2 ecosystems failed, 1 gate failed) ``` -Use `pass`, `FAIL`, `syntax only`, a named skip, or `—` (not applicable: the command is null in the ecosystem config). Show failing command output below the table. An unattended run also prints, below the table, each `assumed:` line and, for each unresolved key, what it read and any tied candidates (ladder "Unattended runs"); its Overall line names each unresolved cell as a cause, e.g. `Overall: INCOMPLETE (0 of 2 ecosystems passed; markdown: skip (unresolved: markdown.build-cmd, markdown.test-cmd, markdown.check-cmd))`. Every skip names its reason, and its class decides whether it blocks a "done" claim: +Use `pass`, `FAIL`, `syntax only`, a named skip, or `—` (not applicable: the command is null in the ecosystem config). Show failing command output below the table. Below the table, any run prints, for each unresolved key, what it read, and an unattended run also prints each `assumed:` line and any tied candidates (ladder "Unattended runs"); the Overall line names each unresolved cell as a cause, e.g. `Overall: INCOMPLETE (0 of 2 ecosystems passed; markdown: skip (unresolved: markdown.build-cmd, markdown.test-cmd, markdown.check-cmd))`. Every skip names its reason, and its class decides whether it blocks a "done" claim: | Cell | Class | Blocks "done" | |------|-------|---------------| @@ -161,7 +155,7 @@ Use `pass`, `FAIL`, `syntax only`, a named skip, or `—` (not applicable: the c | `skip (dependencies missing: )` | environment | yes | | `skip (prerequisite missing: )` | environment: a `requires` probe found it absent | yes | | `skip (unsupported: )` (gates only) | environment: the installed tool is below the gate's documented floor | yes | -| `skip (unresolved: .)` | environment: an unattended run found no recorded, stated or single inferred command for the key | yes | +| `skip (unresolved: .)` | environment: no source the run may use resolved a command for the key | yes | | `skip (opt-in unmet: )` | consumer opt-in | no | | `—` | not applicable | no | | `syntax only` | not a check: when no other cell of the ecosystem passed, no real check ran | no, but never read as verified | @@ -185,7 +179,7 @@ The plugin's Stop hook reads it when the turn ends and warns when the line is no ## For other skills referencing /toolchain:check -- **Command tables**: resolve per [`${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md`](${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md), and read `context/.md` for gotchas, including when embedding commands in an agent prompt. +- **Command tables**: resolve per [`${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md`](${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md), including when embedding commands in an agent prompt. - **Full verification**: invoke `/toolchain:check` or `/toolchain:check ` via the Skill tool. - **Lint only**: invoke `/toolchain:lint` or `/toolchain:lint ` via the Skill tool; it resolves through the same ladder and also owns the `yaml` and `cross-cutting` surfaces. @@ -200,6 +194,6 @@ The plugin's Stop hook reads it when the turn ends and warns when the line is no - **A green exit that checked nothing.** A syntax-only command, or one that failed to start, is not a `pass`. - **A green exit a retry earned.** Report `pass (flaky: N)`, never a plain `pass`. - **Missing tool is never done.** `skip (tool missing: )` makes the Overall line `INCOMPLETE`, not `FAIL` and not `PASS`. So do `skip (prerequisite missing: )` and `skip (unresolved: .)`. -- **Unattended never falls back.** With no record, statement or single inference for a key, an unattended run reports it unresolved; it never runs the bundled default's command instead. -- **Multi-tool `check-cmd` atomicity.** When a `check-cmd` bundles a gated sub-tool with an unconditional one (bash's `shellcheck ... && shfmt -d `), the opt-in gate cannot suppress just the gated part: both run whenever the unconditional one applies. The same opacity reaches the missing-tool rule: a sub-tool the ecosystem's probe never covers (python's `pyright` behind `uv`) is absent only at run time, so the Lint cell reports `FAIL`, not `skip`, unless the record declares it under `requires`. Report what the runner did, never a skip it did not perform. Each affected `context/.md` states the consequence. +- **Nothing falls back.** With no record, inference or answer for a key (attended), or no record, statement or single inference (unattended), the run reports it unresolved; no default command runs instead. +- **Multi-tool `check-cmd` atomicity.** When a `check-cmd` chains a gated sub-tool after an unconditional one (` && -d `), the opt-in gate cannot suppress just the gated part: both run whenever the unconditional one applies. The same opacity reaches the missing-tool rule: a sub-tool the ecosystem's probe never covers (one run through the runner the probe checks) is absent only at run time, so the Lint cell reports `FAIL`, not `skip`, unless the record declares it under `requires`. Report what the runner did, never a skip it did not perform. To avoid the `FAIL`, install the sub-tool, declare it under `requires`, or drop it from the record's `check-cmd`. - **Multiple projects in one ecosystem.** Ecosystems with an `anchor` scope to it; ecosystems with `project-discovery` patterns walk each discovered project root. diff --git a/plugins/toolchain/skills/check/context/bash.md b/plugins/toolchain/skills/check/context/bash.md deleted file mode 100644 index a6a978e7f41..00000000000 --- a/plugins/toolchain/skills/check/context/bash.md +++ /dev/null @@ -1,43 +0,0 @@ -# Bash Build Commands - -Bash has no build step. This ecosystem runs shell tests, static analysis, and formatting. - -## Test (shell test runner) - -Use the consuming project's documented shell-test runner when it has one (a `*.test.sh` discovery script, bats, or similar). When none is documented, there is no default. Report `—` for the test column. - -**CI-environment caveat:** shell tests can pass locally and fail in CI when they depend on environment differences (installed SDKs, tool output formatting, pruned packages). - -## Lint (ShellCheck) - -```bash -shellcheck -x -S warning -``` - -## Format (shfmt) - -```bash -# Check (CI mode) -shfmt -d - -# Fix -shfmt -w -``` - -shfmt reads `.editorconfig` for style; only format when the repo opts in with shell settings there or documents shfmt usage. - -## Gotchas - -- **ShellCheck version drift**: CI runners may ship an older ShellCheck than the repo's `.shellcheckrc` assumes; optional checks differ across versions -- **`-x` flag**: enables following `source`d files for cross-file analysis -- **`-S warning`**: sets minimum severity to warning (excludes info/style) -- **Pass the changed files as absolute paths, never a directory**: `` is the changed shell files; shfmt given a directory walks every shell script under it ([shfmt(1) DESCRIPTION](https://github.com/mvdan/sh/blob/master/cmd/shfmt/shfmt.1.scd)), so a directory would check unchanged files too -- **shfmt absent is a `FAIL`, not a missing-tool `skip`**: `check-cmd` is the single opaque string `shellcheck -x -S warning && shfmt -d `, and the preflight probes the ecosystem's tool, never each sub-tool. So on a project with ShellCheck installed, shfmt absent, and the `.editorconfig` shell-style opt-in met, nothing skips: ShellCheck runs and passes, then `shfmt -d` fails to spawn and the ecosystem reports Lint **`FAIL`**. Because `check-cmd` is one string, that FAIL cannot be narrowed to shfmt alone. Install shfmt alongside ShellCheck (see the ecosystem's `install-hint`), or drop it by overriding `check-cmd` in the consumer's own `.claude/ecosystems/bash.yaml`. Same shape as python's `pyright` behind `uv` (`context/python.md`) - -## File discovery - -Discover dynamically: - -```bash -find "$REPO_ROOT" -name "*.sh" -not -path "*/node_modules/*" -not -path "*/.venv/*" -not -path "*/bin/*" -not -path "*/obj/*" -``` diff --git a/plugins/toolchain/skills/check/context/dotnet.md b/plugins/toolchain/skills/check/context/dotnet.md deleted file mode 100644 index 78c54d9140c..00000000000 --- a/plugins/toolchain/skills/check/context/dotnet.md +++ /dev/null @@ -1,78 +0,0 @@ -# .NET Build Commands - -`` below is the repo's solution file (`*.slnx` or `*.sln`, usually at repo root). When the repo has no solution, target the relevant `.csproj` directly. - -## Build - -```bash -# Full solution (from repo root) -dotnet build "$REPO_ROOT/" - -# Single project -dotnet build "$REPO_ROOT/path/to/Project.csproj" - -# Fast inner-loop (skip analyzers, when the repo wires a SkipAnalyzers property) -dotnet build -p:SkipAnalyzers=true "$REPO_ROOT/path/to/Project.csproj" - -# Build with SARIF v2.1.0 diagnostics (per-project, absolute path) -dotnet build "$REPO_ROOT/path/to/Project.csproj" \ - "-p:ErrorLog=$REPO_ROOT/artifacts/Project.sarif%3bversion=2.1" \ - --nologo -v q -# See [context/sarif.md](sarif.md) for parser patterns and the SARIF gap. -``` - -## Test - -```bash -# All tests via solution -dotnet test "$REPO_ROOT/" --no-build - -# Single test project (--project works under both VSTest and MTP; required under MTP) -dotnet test --project "$REPO_ROOT/path/to/Project.Tests.csproj" -``` - -## Lint / Format - -Opt-in gated: only runs when a governing `.editorconfig` is present (see the -`opt-in` key and its header-comment rationale in -`reference/ecosystems/dotnet.yaml`). Otherwise it is skipped visibly rather -than imposing Roslyn's built-in formatting defaults on a repo that never -configured any. - -```bash -# Check formatting (CI mode — fails on violations) -dotnet format "$REPO_ROOT/" --verify-no-changes - -# Fix formatting -dotnet format "$REPO_ROOT/" -``` - -## Gotchas - -- **Prefer `--project`** for test project paths under either runner (VSTest or Microsoft.Testing.Platform). - - **Pointer**: when a bare project path is rejected, or to check which runner is the default and what each accepts, fetch [dotnet test with MTP: options](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-test-mtp#options) live. -- **`--nologo` and `-v q` break an xUnit v3 run under Microsoft.Testing.Platform**: the flags pass through to the xUnit executable, which rejects them, and no tests run. Use plain `dotnet test` or `-v n`. Pointer: [dotnet test with MTP: options](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-test-mtp#options) -- **`TreatWarningsAsErrors` repos**: when the repo turns warnings into errors globally, every warning is build-breaking; don't dismiss a warning as cosmetic -- **VS locks analyzer DLLs**: if `dotnet build` fails with MSB3021 while Visual Studio is open, close VS or skip analyzers for quick iteration -- **Binary log**: `dotnet build -bl` produces `msbuild.binlog` for diagnosing slow builds or property issues - -## Project discovery and targeting - -Choose the scope based on what changed: - -| What changed | Build scope | Command | -|-------------|------------|---------| -| Files in a single project | That project's `.csproj` | `dotnet build path/to/Project.csproj` | -| Files spanning multiple projects | Full solution | `dotnet build ` | -| Shared build config (`.props`, `.targets`, `.editorconfig`) | Full solution | `dotnet build ` | -| Nothing (clean tree, `/toolchain:check all`) | Full solution | `dotnet build ` | - -To find the `.csproj` for a changed file, walk up from the file's directory until you find a `.csproj`. - -## Common project-declared CI-parity gates - -Checks repos often gate in CI that plain build/test/format don't catch locally. Run them when the consuming project documents them: - -- **Locked-mode NuGet restore** (`dotnet restore --locked-mode`): local `dotnet restore` is permissive; only locked-mode catches `packages.lock.json` drift. Remediation: `dotnet restore --force-evaluate`, commit the regenerated lockfiles. Cross-platform caveat: lockfiles generated on one OS can miss another OS's runtime transitives; regenerate on the CI OS (container/WSL) rather than forcing `-r `, which pollutes lockfiles with RID blocks -- **NU1507 on restore** (fails on a developer machine, passes in CI): with Central Package Management (`ManagePackageVersionsCentrally`) and `TreatWarningsAsErrors` both on, a user-level NuGet config that lists more than one package source raises NU1507 ("please map your package sources with package source mapping or specify a single package source"), and warnings-as-errors makes it fatal. A CI runner with one source never sees it. Remediation: a repo-level `nuget.config` that clears and pins `packageSources` (and `auditSources`), maps `` to that source under `packageSourceMapping`, and clears `disabledPackageSources`, so every host restores from the same declared set. Do not pass `--source`, add NU1507 to `NoWarn`, or edit the user-level config: each clears one machine and leaves the repository's sources unpinned. Basis: [NU1507](https://learn.microsoft.com/en-us/nuget/reference/errors-and-warnings/nu1507) and [Package Source Mapping](https://learn.microsoft.com/en-us/nuget/consume-packages/package-source-mapping), fetched 2026-09-27. Recheck when either page changes NU1507's trigger or remedy, or when `melodic-software/standards` ships a `nuget.config` component, which this bullet then names instead of describing the file -- **Generated-artifact freshness** (e.g. a build-time OpenAPI spec): build the producing project, then `git diff --exit-code` on the generated file; stage the regenerated artifact alongside the source change diff --git a/plugins/toolchain/skills/check/context/gates.md b/plugins/toolchain/skills/check/context/gates.md index e1818b7971a..68f32932258 100644 --- a/plugins/toolchain/skills/check/context/gates.md +++ b/plugins/toolchain/skills/check/context/gates.md @@ -7,15 +7,15 @@ Read when an affected ecosystem resolves a non-empty `gates` array, or the proje - **Reachability.** A gate is subordinate to its ecosystem's run: `trigger-globs` narrows within a run and never selects an ecosystem. Under auto-targeting the ecosystem must first be affected by its own `globs`; a gate whose `trigger-globs` alone match is reached through `/toolchain:check ` or `/toolchain:check all`. To make a cross-ecosystem trigger select its ecosystem, add the pattern to that ecosystem's own `globs`. - **Independent of the short-circuit.** A fired gate runs even when this ecosystem's build, test or lint already failed and stopped, and an opt-in-unmet lint skip does not suppress it. - **Run** `gate.cmd` (an opaque shell string; substitute ``, the resolved anchor and the other placeholders) with absolute paths. The resolved `run-from` (default `"ecosystem"`) sets where: - - `"ecosystem"` runs from the same location the ecosystem's own commands use: once per resolved `` for a `project-discovery` ecosystem, from the `anchor`'s directory for an `anchor` ecosystem, and from `$REPO_ROOT` only when neither is defined. The bundled `go.yaml` `go-mod-tidy-drift` gate needs this, since `go mod tidy -diff` is per module. `` expands to that project's scoped changed files. + - `"ecosystem"` runs from the same location the ecosystem's own commands use: once per resolved `` for a `project-discovery` ecosystem, from the `anchor`'s directory for an `anchor` ecosystem, and from `$REPO_ROOT` only when neither is defined. A gate that checks each module or package on its own needs this. `` expands to that project's scoped changed files. - `"repo-root"` runs once from `$REPO_ROOT` (for a repo-wide gate such as protobuf generation declared under a `project-discovery` ecosystem; declare `run-from: repo-root` on that gate instead of moving it to an ecosystem without `project-discovery`). `` expands to the ecosystem's full changed-files set. `` is undefined there: a gate `cmd` that uses it while declaring `run-from: repo-root` is a configuration error, reported as `FAIL` naming the gate and the placeholder. Such a gate is per-project by construction and belongs on the `"ecosystem"` default. - The fire condition stays repo-wide whatever `run-from` says. - **Tool presence.** A gate tool missing from `PATH` reports `skip (tool missing: )` with the ecosystem's `install-hint`, never `FAIL`. - **Declared prerequisites.** After the tool-presence check, run each probe in the gate's own `requires` list, by the rules of `/toolchain:check`'s "Declared prerequisites". With any entry absent, `gate.cmd` does not run and the gate reports `skip (prerequisite missing: )` with the entry's `hint`, an environment skip that keeps the run from reading `PASS`. A top-level `requires` entry keyed by a command key does not reach a gate. A probe defaults to `$REPO_ROOT` even when the gate runs per project; `run-from: ecosystem` on the entry probes from each location the gate's `cmd` runs from. A gate that ran at some roots and was skipped at others reads `FAIL` when any run failed, else the skip with the skipped roots listed. -- **Version floor.** A tool present but too old for the gate reports `skip (unsupported: )` with the `install-hint`. The `go.yaml` gate's floor for `go mod tidy -diff` is in its `remediation` (record in `context/go.md`). Skip only when the mismatch is **positively established**: the tool names its own minimum in the error, or a documented minimum (the gate's `remediation`, the ecosystem's `notes`, or `context/.md`) is above the version the tool reports when queried directly (e.g. `go version`). A rejection with no established floor is `FAIL` with the rejection text shown, since a typo in `gate.cmd` is rejected the same way. Every other non-zero exit is `FAIL`. +- **Version floor.** A tool present but too old for the gate reports `skip (unsupported: )` with the `install-hint`. Skip only when the mismatch is **positively established**: the tool names its own minimum in the error, or a documented minimum (the gate's `remediation` or the ecosystem's `notes`) is above the version the tool reports when queried directly. A rejection with no established floor is `FAIL` with the rejection text shown, since a typo in `gate.cmd` is rejected the same way. Every other non-zero exit is `FAIL`. - **Outcome.** Report `pass` or `FAIL` by gate name; on `FAIL`, surface `gate.remediation`. A fired gate that fails counts toward the run's `FAIL` verdict. A gate that runs more than once (`"ecosystem"` scope under `project-discovery`) reports **one** line per gate name: `FAIL` if any invocation failed, `pass` only if every one passed, with each failing invocation's output shown below the table labeled by its execution root. -Gates resolve through the ladder like every other key: a bundled default may ship one (an attended run only; an unattended run lists a bundled-only gate as `skip (unresolved: .gates)`, per the ladder's "Unattended runs"), and a consumer declares its own in `.claude/ecosystems/.yaml` (e.g. the `nuget-lockfile-drift` shape in the contract's examples, +Gates resolve through the ladder like every other key, and the plugin ships none: a consumer declares its own in `.claude/ecosystems/.yaml` (e.g. the `nuget-lockfile-drift` shape in the contract's examples, ). **Convention-documented gates still run.** When the project documents extra local checks in its `CLAUDE.md`, `.claude/rules/` or a commands reference instead of a `gates` array, run those too by the same rules: fire on their stated trigger files, run after build, test and lint independent of the short-circuit, report by name with the project's own remediation, and count a failure toward the verdict. Declaring them in `.claude/ecosystems/.yaml` is preferred, not required. diff --git a/plugins/toolchain/skills/check/context/go.md b/plugins/toolchain/skills/check/context/go.md deleted file mode 100644 index f984a8f3641..00000000000 --- a/plugins/toolchain/skills/check/context/go.md +++ /dev/null @@ -1,78 +0,0 @@ -# Go Build Commands - -## Build - -```bash -cd "$PROJECT_DIR" && go build ./... -``` - -## Test - -```bash -cd "$PROJECT_DIR" && go test ./... -``` - -### Test output signals - -For the `Run signals to echo` rule in `SKILL.md` §2: when the command or `GOFLAGS` sets `-shuffle`, `go test` prints the seed it used per package; echo it, since `-shuffle=` replays that order. `go test` has no built-in retry, so a flaky count comes only from a wrapper the project documents. Pointer: (`-shuffle`). As of: 2026-10-06. Recheck trigger: the testflag doc changes how the seed is printed or passed. - -## Lint / Format - -Opt-in gated: only runs when a governing `.golangci.yml`/`.golangci.yaml`/`.golangci.toml`/ -`.golangci.json` is present (see the `opt-in` key and its header-comment rationale in -`reference/ecosystems/go.yaml`). Otherwise it is skipped visibly rather than imposing -golangci-lint's own unconfigured "standard" linter preset on a repo that never configured any. - -```bash -# Check (CI mode — fails on violations) -cd "$PROJECT_DIR" && golangci-lint run ./... - -# Format-only (/toolchain:lint --fix) -cd "$PROJECT_DIR" && gofmt -w - -# Code-fix (semantic lint autofixes — /toolchain:lint --code-fix only) -cd "$PROJECT_DIR" && golangci-lint run --fix -``` - -## Gotchas - -- **`./...` is module-bounded, not repo-bounded**: `go build ./...`/`go test ./...`/ - `go list ./...` run from a repo root silently skip a *nested* module's packages. A nested - `go.mod`, or even a root `go.work` file listing both modules, does not cross that boundary for - `./...` expansion (empirically verified, Go 1.26.5). `project-discovery: ["go.mod"]` in - `go.yaml` handles this by walking to each discovered module root. Always run build/test/lint - from the module root containing the relevant `go.mod`, not just the repo root. -- **A stray home-directory golangci-lint config can change a local run**: golangci-lint's own - config search can reach past the repo root, so a `~/.golangci.yml` on a developer's machine can - make a local run diverge from a clean CI container that has no such file. This plugin's own - `opt-in` gate only ceilings *its* presence check at the repo root. It does not (and cannot) - suppress the tool's own search once the tool actually runs. When a local result differs from - CI, read the search order in the - [golangci-lint configuration file docs](https://golangci-lint.run/docs/configuration/file/) - and run with `-v` to see which config file was used. -- **`go mod tidy -diff` has a Go version floor**: the `go-mod-tidy-drift` gate in `go.yaml` uses - this flag, and the gate's `remediation` names the floor. An older toolchain rejects it outright; - `go version` confirms the installed toolchain is below that documented floor, so `/toolchain:check` reports the gate as `skip (unsupported: ...)` - with the `install-hint` rather than a false drift `FAIL` (the gate's version-floor rule in - `check/context/gates.md`). Drift goes unchecked until the toolchain is upgraded. The skip is visible - in the report, never silent. - - **Pointer**: when checking which Go release added the flag, fetch - [Go 1.23 release notes: Go command](https://go.dev/doc/go1.23#go-command) live. - - **As of**: 2026-11-10 - - **Recheck trigger**: the `go-mod-tidy-drift` gate changes its command or the floor its - `remediation` names. -- **GOFLAGS**: a repo-level `GOFLAGS` env var or `go env -w GOFLAGS=...` setting changes build/test - behavior repo-wide (e.g. `-mod=readonly`); check for one before assuming a bare command failure - is a real break. - -## Project discovery - -Find all Go modules dynamically: - -```bash -find "$REPO_ROOT" -name "go.mod" -not -path "*/vendor/*" -``` - -## Format / code-fix file scope - -`gofmt` and `golangci-lint --fix` receive only `*.go` paths from `` (never `go.mod`/`go.sum`). `golangci-lint --fix` is invoked once per package directory when changed files span multiple packages. diff --git a/plugins/toolchain/skills/check/context/powershell.md b/plugins/toolchain/skills/check/context/powershell.md deleted file mode 100644 index 517fa6d949e..00000000000 --- a/plugins/toolchain/skills/check/context/powershell.md +++ /dev/null @@ -1,47 +0,0 @@ -# PowerShell Build Commands - -PowerShell has no build step. This ecosystem runs Pester tests and static analysis via PSScriptAnalyzer. - -## Test (Pester) - -Run when changed files include `*.ps1`, `*.psm1`, `*.Tests.ps1`, or `PSScriptAnalyzerSettings.psd1`, and the project has Pester tests. Prefer the project's documented test runner script when one exists. For a direct invocation, configure the result file to a gitignored artifacts directory: - -```powershell -pwsh -NoProfile -Command ' - $config = New-PesterConfiguration - $config.Run.Path = "" - $config.TestResult.Enabled = $true - $config.TestResult.OutputPath = "artifacts/test-results/pester-results.xml" - Invoke-Pester -Configuration $config -' -``` - -**Never use `Invoke-Pester -CI` directly.** Its default CWD-relative `testResults.xml` leaks at repo root. - -**Install hint:** `Install-PSResource -Name Pester` (or `Install-Module Pester` on older pwsh). On Linux/macOS without pwsh, report `skip`. - -## Lint (PSScriptAnalyzer) - -```bash -pwsh -NoProfile -Command ' - $files = Get-ChildItem -Path . -Recurse -Include *.ps1,*.psm1 | - Where-Object { $_.FullName -notlike "*node_modules*" -and $_.FullName -notlike "*.venv*" -and $_.FullName -notlike "*\bin\*" -and $_.FullName -notlike "*\obj\*" } - if ($files) { - $files | ForEach-Object { Invoke-ScriptAnalyzer -Path $_.FullName -Settings ./PSScriptAnalyzerSettings.psd1 } | Format-Table -AutoSize - } else { - Write-Output "No production .ps1/.psm1 files found" - } -' -``` - -Omit `-Settings` when the repo has no `PSScriptAnalyzerSettings.psd1`. - -## Gotchas - -- **PSScriptAnalyzer has no `-ExcludePath`.** Pre-filter with `-notlike` wildcard patterns, not `-notmatch` regex: regex escaping is unreliable across the bash to pwsh boundary -- **No production `.ps1`/`.psm1` files may exist**: if none found after filtering, report as `skip` with note -- **Settings file**: `PSScriptAnalyzerSettings.psd1` at repo root configures rules when present - -## File discovery - -PSScriptAnalyzer discovers files via `Get-ChildItem -Recurse`. The filtering above handles exclusions since the tool lacks native path exclusion. diff --git a/plugins/toolchain/skills/check/context/python.md b/plugins/toolchain/skills/check/context/python.md deleted file mode 100644 index eae9c5c06f7..00000000000 --- a/plugins/toolchain/skills/check/context/python.md +++ /dev/null @@ -1,63 +0,0 @@ -# Python Build Commands - -## Lint - -```bash -# Check (CI mode — no auto-fix) -cd "$PROJECT_DIR" && uv run ruff check . --no-fix - -# Code-fix (semantic lint autofixes — /toolchain:lint --code-fix only) -cd "$PROJECT_DIR" && uv run ruff check --fix --no-unsafe-fixes --unfixable F401 -``` - -`--unfixable F401` matches the `python-format` hook: protects just-added imports during iterative -editing; F401 still surfaces as a finding. Only auto-deletion is suppressed. - -## Format - -```bash -# Check (CI mode) -cd "$PROJECT_DIR" && uv run ruff format . --check - -# Fix (format-only — /toolchain:lint --fix) -cd "$PROJECT_DIR" && uv run ruff format -``` - -## Test - -```bash -cd "$PROJECT_DIR" && uv run pytest tests/ -x -q -``` - -### Test output signals - -Read for the `Passed on retry` and `Run signals to echo` rules in `SKILL.md` §2: - -- **Retry-earned pass (pytest-rerunfailures).** A rerun shows as an `R` in the progress line and as `N rerun` in the final summary line (`2 passed, 1 rerun`), and the run still exits 0. Count the reruns that ended in a pass as flaky. With `-rR` the plugin also prints a `rerun test summary info` section naming each test, otherwise name them from the `R` outcomes. Pointer: (rerun summary and `--fail-on-flaky`). As of: 2026-10-06, observed locally on pytest-rerunfailures 16.7 with pytest 9.1. Recheck trigger: a release changes the summary wording or the outcome letter. -- **Slowest tests.** pytest prints a `slowest N durations` section only when the command or `addopts` passes `--durations=N` (`--durations=10` is the usual size). Absent it, the note names that flag for the consumer's own `test-cmd` or `addopts`. -- **Shuffle seed (pytest-randomly).** The plugin prints `Using --randomly-seed=` in the report header, which `-q` (the bundled default) hides. When pytest-randomly is a project dependency and no seed shows, report `seed: hidden by -q` and the replay form `--randomly-seed=last`, which reuses the previous run's seed. Pointer: . As of: 2026-10-06, observed locally on pytest-randomly 5.0. Recheck trigger: the README changes the header line or the `last` form. - -## Type check - -Part of `check-cmd`, which has no fix mode. `fix-cmd` is format-only; `code-fix-cmd` is ruff check only: - -```bash -cd "$PROJECT_DIR" && uv run pyright -``` - -pyright is a **hard prerequisite** of the python default once ruff config opts the ecosystem in. It shares the single compound `check-cmd` with ruff, and tool presence is evaluated per ecosystem, not per tool. The preflight probe is satisfied by `uv`, the runner every python command is invoked through; pyright is never probed. So on a ruff-configured project with `uv` installed and pyright absent from both the project environment and `PATH`, nothing skips: the two ruff commands run and pass, then `uv run pyright` exits 2 (`error: Failed to spawn: pyright` / `program not found`) and the ecosystem reports Lint **`FAIL`**, not a missing-tool `skip`. Because `check-cmd` is one opaque string, that FAIL cannot be narrowed to pyright alone. Install pyright alongside ruff (see the ecosystem's `install-hint`), or, if the project genuinely does not want type checking, drop it by overriding `check-cmd` in the consumer's own `.claude/ecosystems/python.yaml` (ladder rung 1). - -## Gotchas - -- **Use `uv run` prefix in uv-managed projects** (a `uv.lock` is the signal): it ensures the managed virtualenv is used. In pip/poetry projects, use that project's documented invocation instead -- **Shorten E501 (line-too-long) hits by hand**: `--code-fix` does not clear them, so run `/toolchain:lint --fix` first, then shorten by hand each docstring, comment or string literal still past the configured `line-length`. Whether the rule has an autofix: the fix marker on its row in the [ruff rules index, pycodestyle Error (E) table](https://docs.astral.sh/ruff/rules/#error-e); the rule itself: [line-too-long (E501)](https://docs.astral.sh/ruff/rules/line-too-long/#what-it-does) -- **Tune pyright's strictness through config, not ad hoc suppressions**: on an untyped or partially-typed project with no pyright config, pyright can report genuine type errors; set `typeCheckingMode` or add project config. Modes and the default: [`typeCheckingMode`](https://github.com/microsoft/pyright/blob/main/docs/configuration.md#type-check-diagnostics-settings); config file locations: [Pyright Configuration](https://github.com/microsoft/pyright/blob/main/docs/configuration.md#pyright-configuration) -- **Run from project directory**: each `pyproject.toml` defines an independent project root. Always `cd` to the directory containing `pyproject.toml` before running commands - -## Project discovery - -Find all Python projects dynamically: - -```bash -find "$REPO_ROOT" -name "pyproject.toml" -not -path "*/node_modules/*" -not -path "*/.venv/*" -``` diff --git a/plugins/toolchain/skills/check/context/typescript.md b/plugins/toolchain/skills/check/context/typescript.md deleted file mode 100644 index 37db04afcd6..00000000000 --- a/plugins/toolchain/skills/check/context/typescript.md +++ /dev/null @@ -1,54 +0,0 @@ -# TypeScript Build Commands - -## Build / Compile - -```bash -cd "$PROJECT_DIR" && npx tsc --noEmit -``` - -## Test - -```bash -# Use the project's configured runner — check package.json scripts first -cd "$PROJECT_DIR" && npm test -# or directly: npx vitest run / npx jest -``` - -### Test output signals - -Read for the `Passed on retry` and `Run signals to echo` rules in `SKILL.md` §2: - -- **Retry-earned pass (Playwright Test).** With `retries` set, Playwright sorts results into passed, flaky (failed first, passed on retry) and failed, and its summary carries a `flaky` count with the test names. That count is the `pass (flaky: N)` value. Pointer: . As of: 2026-10-06 (Playwright 1.63). Recheck trigger: a release renames the outcome or changes the summary. -- **Other runners.** When the project config sets retries (Jest `retryTimes`, Vitest `retry`) and the output does not separate a retried pass, say `retries configured, flaky count not reported` rather than a clean pass. -- **Slowest tests and seed.** Echo a slow-test or seed line only when the runner prints one; neither is added to the command. - -## Lint - -```bash -# Use the project's configured linter — biome.json → Biome; eslint config → ESLint -cd "$PROJECT_DIR" && npx @biomejs/biome check . - -# Format-only (/toolchain:lint --fix) -cd "$PROJECT_DIR" && npx @biomejs/biome format --write - -# Code-fix (lint autofixes — /toolchain:lint --code-fix only) -cd "$PROJECT_DIR" && npx @biomejs/biome check --write -``` - -Run Biome through `npx` by its scoped package name `@biomejs/biome`, never the bare `biome` name: #12573 is the observed failure of the bare name. When the project pins Biome, its consumer `check-cmd`, `fix-cmd` and `code-fix-cmd` may instead name the local binary (`node_modules/.bin/biome`), or a `biome` binary on PATH when there is no local one, in place of `npx`. - -- **Pointer**: when deciding how `npx` resolves a package name given without a version, fetch live. - -## Gotchas - -- **Run from project directory**: each `package.json` defines an independent project root -- **Biome walks up** to find `biome.json` from the CWD, so run from project dir, not repo root -- **`tsc --noEmit`** belongs in CI and `/toolchain:check`, not in edit-time hooks: tsc is project-scoped and takes seconds - -## Project discovery - -Find all TypeScript/JS projects dynamically: - -```bash -find "$REPO_ROOT" -name "package.json" -not -path "*/node_modules/*" -not -path "*/.venv/*" -``` diff --git a/plugins/toolchain/skills/lint/SKILL.md b/plugins/toolchain/skills/lint/SKILL.md index f7f086c947d..2fe081a4bc3 100644 --- a/plugins/toolchain/skills/lint/SKILL.md +++ b/plugins/toolchain/skills/lint/SKILL.md @@ -39,9 +39,9 @@ Run lint and format checks across affected ecosystems in one command. Fills the Use `/toolchain:lint` for quick feedback during development. Use `/verification:confirm` before committing. -**The command surface is resolved, not hardcoded.** `/toolchain:lint` resolves each ecosystem's `lint-cmd`/`check-cmd`/`fix-cmd`/`code-fix-cmd` through the shared four-rung ladder in [`${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md`](${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md). Shared with `/toolchain:check`: the consuming repo's tracked `.claude/ecosystems/.yaml` is authoritative when present; the plugin's bundled portable defaults at `${CLAUDE_PLUGIN_ROOT}/reference/ecosystems/` are the rung-4 fallback of an attended run only. The consumer's file always wins. +**The command surface is resolved, not hardcoded.** `/toolchain:lint` resolves each ecosystem's `lint-cmd`/`check-cmd`/`fix-cmd`/`code-fix-cmd` through the shared three-rung ladder in [`${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md`](${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md). Shared with `/toolchain:check`: the consuming repo's tracked `.claude/ecosystems/.yaml` is authoritative when present, then inference from its build files, then asking. The plugin ships no default command: a key nothing resolves is reported unresolved and runs nothing. -**The secret scan is lint's own.** It runs from this skill, not from a record or a bundled default, under its opt-in, in attended and unattended runs alike: see [Secret scan](#secret-scan). +**The security scans are lint's own.** The secret scan and the workflow-security scan run from this skill, not from a record, each under its own opt-in, in attended and unattended runs alike: see [Secret scan](#secret-scan) and [Workflow-security scan](#workflow-security-scan). **Two mutators, two gates.** Format-only and code-changing autofixes are separate keys and separate flags. Bare `--fix` must never run semantic lint autofixes (ruff `check --fix`, golangci-lint `--fix`, biome `check --write`, …). @@ -51,7 +51,7 @@ Use `/toolchain:lint` for quick feedback during development. Use `/verification: **Ecosystem filters** (if omitted, auto-detect from changed files): -`/toolchain:lint` accepts any covered ecosystem id, meaning one with a record, one inferred this run, or one with a bundled default ([resolution ladder](${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md) "Covered ecosystems"), each resolved per the ladder. The bundled defaults are `dotnet`, `python`, `typescript`, `bash`, `powershell`, `markdown`, `go`, `yaml`, and `cross-cutting`; a consumer record such as `.claude/ecosystems/rust.yaml` makes `rust` a filter too. Aliases: `py` → `python`; `ts`/`node` → `typescript`; `shell` → `bash`; `ps`/`pwsh` → `powershell`; `md` → `markdown`; `golang` → `go`; `xc`/`text` → `cross-cutting`. Literal `all` runs every applicable ecosystem. +`/toolchain:lint` accepts any covered ecosystem id, meaning one recorded, stated or inferred this run ([resolution ladder](${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md) "Covered ecosystems"), each resolved per the ladder. A consumer record such as `.claude/ecosystems/rust.yaml` makes `rust` a filter. Aliases: `py` → `python`; `ts`/`node` → `typescript`; `shell` → `bash`; `ps`/`pwsh` → `powershell`; `md` → `markdown`; `golang` → `go`; `xc`/`text` → `cross-cutting`. Literal `all` runs every applicable ecosystem. **Mode flags:** @@ -84,7 +84,7 @@ Parse `$ARGUMENTS` for: ### 1. Detect ecosystems -First add each ecosystem the repo's build files infer, per the ladder's "Covered ecosystems" in [`${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md`](${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md). Then, if an ecosystem filter was provided, use it; if `all`, run every covered ecosystem. Otherwise, classify changed files from `git status --porcelain` against each ecosystem's `globs` list; when the working tree is clean, fall back to the branch diff so checkpoint-committed work still gets classified. Resolve the default branch by **detection, not assumption**, never a hardcoded `main`/`master`, and assign it before use: +First add each ecosystem the repo's instructions state or its files infer, per the ladder's "Covered ecosystems" in [`${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md`](${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md). Then, if an ecosystem filter was provided, use it; if `all`, run every covered ecosystem. Otherwise, classify changed files from `git status --porcelain` against each ecosystem's `globs` list; when the working tree is clean, fall back to the branch diff so checkpoint-committed work still gets classified. Resolve the default branch by **detection, not assumption**, never a hardcoded `main`/`master`, and assign it before use: ```bash REMOTE="" DEFAULT_BRANCH="" @@ -111,12 +111,12 @@ The loop probes candidate remotes in priority order, the remote the current bran Auto-detection algorithm: -1. With the inferred ecosystems already added (above), resolve each covered ecosystem's config per [`${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md`](${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md) (consumer `.claude/ecosystems/.yaml` when present, else what the repo's build files infer, named with its globs in the report, else the bundled default; a malformed consumer file warns and degrades to inference, never a hard stop). An unattended run (the ladder's "Run kind") resolves commands by the ladder's "Unattended runs" instead: recorded, stated, then inferred, never the bundled default's commands, and a key none resolves reads `skip (unresolved: .)`. Skip any ecosystem whose resolved `enabled` is `false` (a consumer opt-out). Excluded even under `all` +1. With the stated and inferred ecosystems already added (above), resolve each covered ecosystem's config per [`${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md`](${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md) (consumer `.claude/ecosystems/.yaml` when present, else what the repo's build files infer, named with its globs in the report, else ask; a key nothing resolves reads `skip (unresolved: .)`, and a malformed consumer file warns and degrades to inference, never a hard stop). An unattended run (the ladder's "Run kind") resolves commands by the ladder's "Unattended runs" instead: recorded, stated, then inferred, and a key none resolves reads `skip (unresolved: .)`. Skip any ecosystem whose resolved `enabled` is `false` (a consumer opt-out). Excluded even under `all` 2. For each ecosystem, match its `globs` against the changed-files list -3. Run every ecosystem with ≥1 glob match whose `opt-in` condition holds, plus cross-cutting when any text file changed. This binary run/skip treatment applies cleanly when `opt-in` describes a single condition for the whole `check-cmd` (dotnet, python): unmet → excluded from the run but still reported (see sections 2 and 3 below, `skip (opt-in unmet: ...)`; never silently omitted). When `opt-in` instead describes multiple independent per-tool conditions bundled into one opaque command string (bash's shellcheck-always/shfmt-conditional split; cross-cutting's per-tool config-file list), this rule does not apply. `check-cmd`/`fix-cmd`/`code-fix-cmd` is a single opaque string with no way to run one sub-tool's portion without the other, so run it whole and report its real output. The known atomicity limitation this leaves open is in `/toolchain:check`'s Gotchas. +3. Run every ecosystem with ≥1 glob match whose `opt-in` condition holds, plus cross-cutting when any text file changed. This binary run/skip treatment applies cleanly when `opt-in` describes a single condition for the whole `check-cmd`: unmet → excluded from the run but still reported (see sections 2 and 3 below, `skip (opt-in unmet: ...)`; never silently omitted). When `opt-in` instead describes multiple independent per-tool conditions bundled into one opaque command string (one tool always, another only with its own config present), this rule does not apply. `check-cmd`/`fix-cmd`/`code-fix-cmd` is a single opaque string with no way to run one sub-tool's portion without the other, so run it whole and report its real output. The known atomicity limitation this leaves open is in `/toolchain:check`'s Gotchas. 4. A changed file is unclaimed when no resolved ecosystem's `globs` match it, cross-cutting's `**` aside: that glob is never a claim by itself, whether cross-cutting runs or is disabled. A match by any other ecosystem counts, even one that is disabled or skipped for an unmet opt-in: that row already reports the consumer's choice. Collect each unclaimed text file for the report's two fixed lines (section 3). Under `all` the changed files still come from the detection paths above; an ecosystem filter skips this step. A deleted file is not named. A binary file stays quiet. Decide binary with `git ls-files --eol -c -o -- `: the file is binary when Git identifies its working-tree content as not text ([`--eol`](https://git-scm.com/docs/git-ls-files#Documentation/git-ls-files.txt---eol)). A path with no working-tree content is deleted or not a regular file, never binary. One command serves a working-tree change, the branch diff and a caller-supplied changed-file list. -If neither detection path yields changes and no filter specified: report "No changes found (working tree clean, no branch diff vs the default branch). Use `/toolchain:lint all` to check the full repo, or `/toolchain:lint ` for a specific filter." and stop. If files changed but no ecosystem runs, print the unclaimed-file line (when it names any file) instead of the table, and stop, unless a `.gitleaks.toml` sits at the root: then run the [Secret scan](#secret-scan), record the Overall line (section 5), and report its row, the unclaimed-file lines and the Overall line. +If neither detection path yields changes and no filter specified: report "No changes found (working tree clean, no branch diff vs the default branch). Use `/toolchain:lint all` to check the full repo, or `/toolchain:lint ` for a specific filter." and stop. If files changed but no ecosystem runs, print the unclaimed-file line (when it names any file) instead of the table, and stop, unless a security scan's opt-in holds (a `.gitleaks.toml` at the root, or a zizmor config with workflows present): then run the [Secret scan](#secret-scan) and the [Workflow-security scan](#workflow-security-scan) whose opt-ins hold, record the Overall line (section 5), and report their rows, the unclaimed-file lines and the Overall line. ### 2. Run linters per ecosystem @@ -131,9 +131,7 @@ The record's `lint-cmd` is the repository's report-only lint command; a check ru | `--fix` | `fix-cmd` | none beyond the flag (format-only by contract) | | `--code-fix` | `code-fix-cmd` | [confirmation gate](#code-fix-confirmation-gate) + [scope fence](#code-fix-scope-fence) | -Honor each ecosystem's `opt-in`: for a single-condition ecosystem (dotnet, python), an unmet condition skips the whole ecosystem, reporting `skip (opt-in unmet: )` visibly (never a silent omission) in every column that ecosystem's row has. This skip counts toward the table's total ecosystem count but never toward the FAIL count, the same precedent as a missing-tool skip. For a multi-tool ecosystem (bash, cross-cutting) whose `check-cmd` bundles multiple sub-tools into one opaque string, this binary treatment doesn't apply. Run and report `check-cmd`/`fix-cmd`/`code-fix-cmd` whole; see `/toolchain:check`'s Gotchas for the known atomicity limitation. - -For ecosystem-specific gotchas, reference `/toolchain:check`. Its `context/.md` files own the per-ecosystem prose detail. +Honor each ecosystem's `opt-in`: for a single-condition ecosystem, an unmet condition skips the whole ecosystem, reporting `skip (opt-in unmet: )` visibly (never a silent omission) in every column that ecosystem's row has. This skip counts toward the table's total ecosystem count but never toward the FAIL count, the same precedent as a missing-tool skip. For a multi-tool ecosystem whose `check-cmd` bundles multiple sub-tools into one opaque string, this binary treatment doesn't apply. Run and report `check-cmd`/`fix-cmd`/`code-fix-cmd` whole; see `/toolchain:check`'s Gotchas for the known atomicity limitation. **`` substitution:** expand to the ecosystem-scoped changed-file list (paths relative to the execution root). Prefer this scoped list over whole-tree `.` / `./...` whenever the command string contains ``. Under `/toolchain:lint all` with an empty detection set, expand to the matching files under each project root (or the repo root) rather than inventing a silent whole-tree rewrite for code-fix, and still apply the [file-cap](#code-fix-scope-fence) to that expanded set. @@ -143,15 +141,15 @@ Per-project walking (ecosystems with `project-discovery`): - python: walk each `pyproject.toml` directory and run check/fix from there - typescript: walk each `package.json` directory and run check/fix from there -- go: walk each `go.mod` directory and run check/fix from there (a root `./...` invocation stops at a nested module boundary. See `/toolchain:check`'s per-ecosystem context file) +- go: walk each `go.mod` directory and run check/fix from there (a root `./...` invocation stops at a nested module boundary) -Tool presence: verify on `PATH` before each ecosystem the tool its commands are invoked through (python's `uv`, not the `ruff` and `pyright` behind it); report `skip (tool missing: )` with `install-hint` when missing, never `FAIL`. The probe is per ecosystem, not per sub-tool: a sub-tool bundled inside an opaque compound `check-cmd` is not probed, so its absence surfaces at execution time as a real non-zero exit and the ecosystem reports `FAIL`, not `skip`, unless the record declares it under `requires`. Same rule `/toolchain:check` states, so both skills classify an identical environment identically. +Tool presence: verify on `PATH` before each ecosystem the tool its commands are invoked through (the runner or wrapper the command starts with, not the tools it runs behind it); report `skip (tool missing: )` with `install-hint` when missing, never `FAIL`. The probe is per ecosystem, not per sub-tool: a sub-tool bundled inside an opaque compound `check-cmd` is not probed, so its absence surfaces at execution time as a real non-zero exit and the ecosystem reports `FAIL`, not `skip`, unless the record declares it under `requires`. Same rule `/toolchain:check` states, so both skills classify an identical environment identically. Declared prerequisites: after the tool-presence check and a met single-condition `opt-in` (an unmet one skips without probing), run the probes the resolved `requires` lists for the command this mode runs (`check-cmd`, `fix-cmd` or `code-fix-cmd`), by `/toolchain:check`'s "Declared prerequisites" rules. With any entry absent, the command does not run: every column it fills reads `skip (prerequisite missing: )`, with the entry's `hint` below the table, and the run goes on to the next ecosystem. A probe that errors, cannot start or passes 30 seconds reads the same skip, never `FAIL`. Never install a declared prerequisite and never run its `hint`. Under `--code-fix` no probe runs before the [confirmation gate](#code-fix-confirmation-gate) grants an apply: the plan lists each prerequisite `requires` declares for `code-fix-cmd` as `not probed yet`, so `--dry-run`, a non-interactive run without `--yes` and a declined confirmation run no probe at all. Once the gate grants the apply, the probes run, and an absent entry skips that ecosystem's `code-fix-cmd` with the same `skip (prerequisite missing: )` report. Tool pins (`tool-pin` sub-key, e.g. zizmor): when the resolved config pins a tool version, warn if the installed version drifts from the pin (a pin typically mirrors the consumer's own CI pin). No pin, no check. -Cross-cutting: resolve `$EC_BIN` for editorconfig-checker binary-name variants before substituting into the check command: +When a resolved command names `$EC_BIN`, resolve it for editorconfig-checker binary-name variants before substituting it into the command: ```bash EC_BIN="" @@ -173,6 +171,20 @@ The skill states the command, so the ladder does not resolve it, and an unattend Report it as its own `secret-scan` row with one Lint column: `pass` on exit 0, `FAIL` on a finding or any other non-zero exit, and `skip (tool missing: gitleaks)` with the hint `winget install Gitleaks.Gitleaks | brew install gitleaks` when `gitleaks` is not on `PATH`, an environment skip that leaves the run `INCOMPLETE`. With no `.gitleaks.toml` at the root it reads `skip (opt-in unmet: no .gitleaks.toml at the repo root)`. The row counts toward the table's totals like an ecosystem row, and it claims no file for the unclaimed-file lines. `--fix` and `--code-fix` do not run it. +### Workflow-security scan + +In check mode, when GitHub Actions workflow files exist under `.github/` and the repository uses zizmor (a `zizmor.yml` or `zizmor.yaml` under `.github/` or at the repository root, where zizmor looks for its config), run the workflow-security scan from the repository root: + +```bash +zizmor --offline . +``` + +`--offline` turns off every online action, repository fetches included. As with the secret scan, the skill states the command, so the ladder does not resolve it, and an unattended run runs it like an attended one and logs it as `assumed: workflow-security.check-cmd=zizmor --offline . (SKILL.md, )`. It runs on every check-mode run with changed files, `all` and an ecosystem filter included, whether or not any record exists or any ecosystem runs, and even when a recorded command already ran zizmor. + +Report it as its own `workflow-security` row with one Lint column. A finding is advisory: exit 0 reads `pass`; exit 11 to 14 (one or more findings, the code naming the highest severity) reads `advisory (findings: exit )` with the findings below the table, and changes no Status and no Overall line; any other non-zero exit reads `FAIL`. When `zizmor` is not on `PATH` it reads `skip (tool missing: zizmor)` with the hint `pip install zizmor`, an environment skip that leaves the run `INCOMPLETE`. With no zizmor config it reads `skip (opt-in unmet: no zizmor config)`. The row counts toward the table's totals like an ecosystem row, and it claims no file for the unclaimed-file lines. `--fix` and `--code-fix` do not run it. + +Basis: zizmor's [usage page](https://docs.zizmor.sh/usage/) (`--offline`, a repository-root input, exit codes 11 to 14) and [configuration page](https://docs.zizmor.sh/configuration/) (config discovery), read 2026-11-21. Recheck when either page changes those. + ### Code-fix confirmation gate `--code-fix` mutates semantics, not just whitespace, the only `/toolchain:lint` path that does. Always emit the plan first: @@ -222,7 +234,7 @@ In check mode, settle the Overall line and record it (section 5) before writing Overall: FAIL (1 of 4 ecosystems failed) ``` -Use `pass`, `FAIL`, a named skip, or `—` (not applicable). Every skip names its reason in `/toolchain:check`'s named classes, and its class decides whether it blocks a "done" claim exactly as `/toolchain:check`'s report table (its section 3) classifies it: `skip (tool missing: )`, `skip (prerequisite missing: )` and an unattended run's `skip (unresolved: .)` are environment skips and block "done"; `skip (opt-in unmet: )` is the consumer's opt-in and does not. Lint installs nothing and runs no CI-parity gates, so it never emits the `dependencies missing` or `unsupported` classes. +Use `pass`, `FAIL`, a named skip, `—` (not applicable), or, on the `workflow-security` row only, `advisory (findings: exit )`, which counts as passed and never makes a Status or the Overall line `FAIL` or `INCOMPLETE`. Every skip names its reason in `/toolchain:check`'s named classes, and its class decides whether it blocks a "done" claim exactly as `/toolchain:check`'s report table (its section 3) classifies it: `skip (tool missing: )`, `skip (prerequisite missing: )` and `skip (unresolved: .)` are environment skips and block "done"; `skip (opt-in unmet: )` is the consumer's opt-in and does not. Lint installs nothing and runs no CI-parity gates, so it never emits the `dependencies missing` or `unsupported` classes. An ecosystem's Status and the Overall line read `FAIL` when any cell failed, `INCOMPLETE` when nothing failed but an environment skip remains, and `PASS` only when neither holds. `INCOMPLETE` names each cause with its reason (e.g. `Overall: INCOMPLETE (3 of 4 ecosystems passed; markdown: skip (tool missing: markdownlint-cli2))`), so a caller such as `/verification:confirm` holds its verdict on a lint-only environment gap. An opt-in-unmet skip or a `—` cell never makes a run `INCOMPLETE`. @@ -232,7 +244,7 @@ If `--fix` was used, note which ecosystems were format-fixed vs which have no `f If `--code-fix` was used (and applied), note which ecosystems ran `code-fix-cmd` vs which have none, and show `git diff --stat` for blast radius. -Show failing output below the table. Truncated to key error lines, not the full dump. An unattended run also prints each `assumed:` line, and for each unresolved key what it read and any tied candidates (ladder "Unattended runs"). +Show failing output below the table. Truncated to key error lines, not the full dump. Any run prints, for each unresolved key, what it read; an unattended run also prints each `assumed:` line and any tied candidates (ladder "Unattended runs"). Below the table, name every unclaimed changed text file (section 1, step 4) on one of two fixed lines, printed word for word even when a note elsewhere in the reply says the same thing: @@ -246,7 +258,7 @@ Neither line changes a Status or the Overall line, and no binary file is on eith - **`--fix`:** auto-fix capability derives from a non-null `fix-cmd`. Report check-only ecosystems alongside format fixes: "Fixed formatting in dotnet, python, bash. markdownlint had no remaining auto-fixes." - **`--code-fix`:** capability derives from a non-null `code-fix-cmd`. Ecosystems with only `fix-cmd` (format-only) are not code-fixed under this flag. Tell the operator to use `--fix` for those. Example: "Applied code-fix in python, go. typescript has no code-fix-cmd. Use `--fix` for format-only ecosystems (dotnet, bash, …)." -**Consumer overrides:** a consumer who still puts code-changing autofixes in `fix-cmd` keeps that behavior under `--fix` (their file wins). Prefer migrating those verbs into `code-fix-cmd` so bare `--fix` stays format-only. Bundled portable defaults already split the two. +**Consumer overrides:** a consumer who still puts code-changing autofixes in `fix-cmd` keeps that behavior under `--fix` (their file wins). Prefer migrating those verbs into `code-fix-cmd` so bare `--fix` stays format-only. ### 5. Record the result @@ -256,14 +268,14 @@ In check mode, before writing the report, record the settled Overall line for th node "${CLAUDE_PLUGIN_ROOT}/scripts/record-result.mjs" --skill lint --dir "$REPO_ROOT" --overall '' ``` -The plugin's Stop hook reads it at turn end the same way it reads `/toolchain:check`'s record. Record nothing for `--fix` or `--code-fix`: the fix changes the tree, so the check that would count is the next check-mode run. Skip it too when an ecosystem filter narrowed the run (`all` and a caller's changed-file list do not narrow it), and when the run stopped at "No changes found" or with no ecosystem to run and no secret scan run. A run with no ecosystem to run that did run the [Secret scan](#secret-scan) (section 1's `.gitleaks.toml` case) records its Overall line like any other check-mode run, so a `secret-scan` FAIL reaches the Stop hook. A failed record (exit 2, for example where a sandbox blocks the git calls that hash the tree, or exit 1 for a line it rejects) changes nothing in the report: put one `Not recorded: ` line above the table, and still end the reply with the full report, its table, the lines below it and the Overall line. +The plugin's Stop hook reads it at turn end the same way it reads `/toolchain:check`'s record. Record nothing for `--fix` or `--code-fix`: the fix changes the tree, so the check that would count is the next check-mode run. Skip it too when an ecosystem filter narrowed the run (`all` and a caller's changed-file list do not narrow it), and when the run stopped at "No changes found" or with no ecosystem to run and no security scan run. A run with no ecosystem to run that did run a security scan (section 1's opt-in case) records its Overall line like any other check-mode run, so a `secret-scan` or `workflow-security` FAIL reaches the Stop hook. A failed record (exit 2, for example where a sandbox blocks the git calls that hash the tree, or exit 1 for a line it rejects) changes nothing in the report: put one `Not recorded: ` line above the table, and still end the reply with the full report, its table, the lines below it and the Overall line. ## Edge cases - **No git changes but `/toolchain:lint all`**: run all applicable ecosystems (useful after rebase or pull) - **Missing tools**: report as `skip (tool missing: )` with the install hint, not as failure, and never as done: the Overall line reads `INCOMPLETE`. Scoped to the tool the ecosystem's commands are invoked through, not every sub-tool a compound command reaches (an un-probed sub-tool's absence is a real non-zero exit, so `FAIL`, unless the record declares it under `requires`; see `/toolchain:check`'s Gotchas) - **Declared prerequisite absent**: report as `skip (prerequisite missing: )` with its hint, never `FAIL` from a crashed command or a `PASS` from the wrong build of a tool; the Overall line reads `INCOMPLETE` -- **Opt-in unmet**: report as `skip (opt-in unmet: ...)` with the condition, not as failure and not a silent omission (e.g., dotnet with no C#-relevant `.editorconfig`) +- **Opt-in unmet**: report as `skip (opt-in unmet: ...)` with the condition, not as failure and not a silent omission (e.g., a record whose `opt-in` names a config file the repository lacks) - **Multiple projects in same ecosystem**: run per-project (each `pyproject.toml`, each `package.json`) - **File outside any ecosystem**: a text file is named on one of the two unclaimed-file lines; a binary file (images, archives) outside every ecosystem gets no mention in the reply, not even to say it was skipped - **CWD drift**: always use absolute paths from `$REPO_ROOT` @@ -273,7 +285,7 @@ The plugin's Stop hook reads it at turn end the same way it reads `/toolchain:ch ## Relationship to other skills -- **Composes from `/toolchain:check`**: `/toolchain:check` owns the per-ecosystem prose gotchas. Reference it rather than duplicating +- **Composes from `/toolchain:check`**: `/toolchain:check` owns the shared run rules and gotchas. Reference it rather than duplicating - **Composed by `/verification:confirm`** (the separate `verification` plugin, when enabled): the lint leg of full verification - **After a simplify/cleanup pass**: run `/toolchain:lint` to catch formatting issues the cleanup introduced - **Before commit**: `/toolchain:lint --fix` is a quick pre-commit **format** cleanup without the overhead of a full build. Use `/toolchain:lint --code-fix` (interactive confirm, or `--yes` when headless) only when you intentionally want semantic lint autofixes. diff --git a/plugins/toolchain/skills/setup/SKILL.md b/plugins/toolchain/skills/setup/SKILL.md index 1076e408192..ce172c8bc0e 100644 --- a/plugins/toolchain/skills/setup/SKILL.md +++ b/plugins/toolchain/skills/setup/SKILL.md @@ -13,12 +13,12 @@ repository): `check` reports what is configured, `apply` writes it. The tracked `.claude/ecosystems/.yaml` let `/toolchain:check` and `/toolchain:lint` resolve commands deterministically from rung 1 of the ladder ([`${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md`](${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md)) -instead of inferring or falling back to bundled defaults every run. This skill is the ladder's +instead of inferring every run or reporting a key unresolved. This skill is the ladder's **writer** for rungs 2 and 3 (infer-and-persist, ask-and-persist). -Idempotent: re-running reads the existing files and offers updates rather than overwriting blind. The -plugin ships working bundled portable defaults (rung 4), so an unconfigured ecosystem is **INFO** (the -default resolves), never FAIL. +Idempotent: re-running reads the existing files and offers updates rather than overwriting blind. An +unconfigured ecosystem is **INFO**, never FAIL: an attended run infers or asks for its commands, and a +key nothing resolves reads `skip (unresolved: ...)`. Action routing: no argument or `check` runs the check; `apply` runs the check first, then writes. `apply ` scopes the whole run to that one ecosystem; when a named ecosystem's inference is @@ -36,9 +36,8 @@ directory; configuration lives in the consumer's tracked files. ## `check` (read-only) -The bundled portable defaults and the contract schema are the single source of truth for the file -shape (`${CLAUDE_PLUGIN_ROOT}/reference/ecosystems/`, `ecosystem.schema.json`). **Read the ladder -first**, then report a PASS/FAIL/INFO table; modify nothing. +The contract schema (`ecosystem.schema.json`) is the single source of truth for the file shape. +**Read the ladder first**, then report a PASS/FAIL/INFO table; modify nothing. 1. **Configured ecosystems.** For each `$REPO_ROOT/.claude/ecosystems/.yaml` present, report the ecosystem and its resolved command surface @@ -51,8 +50,8 @@ first**, then report a PASS/FAIL/INFO table; modify nothing. the report to just that file. 2. **Unconfigured ecosystems.** INFO: detect which ecosystems the repo has that are *not* yet configured (see the inference signals under `apply`), and note that `/toolchain:check` / - `/toolchain:lint` resolve those through inference then the bundled portable defaults. The - remediation is `apply` to persist a command surface. + `/toolchain:lint` resolve those through inference, and report a key nothing resolves as + unresolved. The remediation is `apply` to persist a command surface. ## `apply` (idempotent) @@ -70,26 +69,27 @@ user confirming. If `$ARGUMENTS` names one ecosystem, scope the whole run to jus ### 2. Infer candidates from the repo before asking -Detect which ecosystems apply from what actually exists, and draft each one's command surface. Seed -the draft from the bundled portable default at -[`${CLAUDE_PLUGIN_ROOT}/reference/ecosystems/.yaml`](${CLAUDE_PLUGIN_ROOT}/reference/ecosystems/), -then specialize it to the repo. +Detect which ecosystems apply from what actually exists, and draft each one's command surface from +inference only: the repo's records, instructions, build files, tool configs and CI. The plugin ships +no default file to seed a draft from; a key nothing implies goes to the interview, never to a +command the plugin picks. When the repo has its own task runner or wrapper scripts (a task file, a manifest's scripts block, a scripts directory its docs or CI call), draft each command key from the matching task or script -before the bundled default, in any ecosystem. Draft `test-changed-cmd` from the repo's own test +first, in any ecosystem. Draft `test-changed-cmd` from the repo's own test runner's way of selecting tests for changed files, over ``; when the repo has no such selection, look it up with `/discovery:research` for the runner the repo uses, and leave the key -out when none exists. Never put a per-stack selector into a bundled default. +out when none exists. - **dotnet**. `*.slnx`/`*.sln`/`*.csproj` present. Resolve the `anchor` (solution file at root, else nearest project). Note any repo-specific trap in `notes` (e.g. the xUnit v3 `--nologo` pin). -- **python**. `pyproject.toml`/`uv.lock`. Prefer `uv run …` when `uv.lock` exists, else plain - `ruff`/`pytest`. Set `project-discovery` to the `pyproject.toml` roots. +- **python**. `pyproject.toml`/`uv.lock`. Draft from the tools the project's config and + dependencies name, run through `uv run …` when `uv.lock` exists. Set `project-discovery` to the + `pyproject.toml` roots. - **typescript**. `package.json`/`tsconfig*.json`. Pick `check-cmd`/`fix-cmd` (format-only) and `code-fix-cmd` (semantic lint autofixes) from the configured linter (`biome.json` → Biome format vs check --write; eslint config → ESLint). -- **bash** / **powershell**. Shell/PowerShell files present; keep the bundled check/fix commands - unless the repo documents its own. +- **bash** / **powershell**. Shell/PowerShell files present; draft the check/fix commands the repo + documents or its linter and formatter configs imply, and ask for the rest. - **markdown**, a markdownlint config present. - **yaml**. `.github/workflows/` present (lint-only surface. `/toolchain:lint` runs it, `/toolchain:check` does not). @@ -150,5 +150,5 @@ configuration and changes nothing. - Write machine-local state. Configuration lives in the consumer's tracked files, never in the plugin directory or the plugin data directory. - Write the plugin cache, Claude Code user settings, or `pluginConfigs`. -- Ship or edit the bundled portable defaults. Those are the plugin's rung-4 fallback, never written - into a consumer repo except as the seed for a file this interview produces. +- Draft a command from a plugin default. Every drafted command comes from the repository or from the + person's answer. diff --git a/scripts/affected-tests-no-suite.txt b/scripts/affected-tests-no-suite.txt index 7a6fd050f5c..fbd62a499e5 100644 --- a/scripts/affected-tests-no-suite.txt +++ b/scripts/affected-tests-no-suite.txt @@ -58,19 +58,12 @@ # There is deliberately NO bare *.yaml / *.yml entry. Both used to be here, and # both were a coverage claim this repo could not honor. Every .yml in the repo # already sits under .github/*, so the entry bought nothing; *.yaml additionally -# swept in 13 files that NO lane reads — -# plugins/toolchain/reference/ecosystems/*.yaml (9) and -# docs/contracts/ecosystem-commands/examples/*.yaml (4). Verified absent, not -# merely unattributed: there is no yamllint step anywhere in .github or scripts; -# every check-jsonschema step names its files and none names these; -# validate-plugin-contracts.mjs does not mention yaml at all; and -# `git ls-files 'plugins/toolchain/**/*.test.sh'` is empty. The generic hygiene -# steps (typos, editorconfig-checker, gitleaks) read the bytes but validate -# nothing about these files' contract. So they now fail loud, which is this -# tool working. The four ecosystem-commands examples have since earned a lane: -# docs/contracts/ecosystem-commands/examples.test.sh names each one and checks -# it against ecosystem.schema.json, so they map to that suite, not to an entry -# here. The toolchain ecosystem YAMLs still have none. +# swept in YAML files that NO lane read, such as +# docs/contracts/ecosystem-commands/examples/*.yaml (4). Those four examples +# have since earned a lane: docs/contracts/ecosystem-commands/examples.test.sh +# names each one and checks it against ecosystem.schema.json, so they map to +# that suite, not to an entry here. A new YAML file with no lane fails loud, +# which is this tool working. .github/* .gitattributes scripts/.gitattributes diff --git a/scripts/org-repo-tokens-allow.tsv b/scripts/org-repo-tokens-allow.tsv index 850cdb7a843..c2f32d2839c 100644 --- a/scripts/org-repo-tokens-allow.tsv +++ b/scripts/org-repo-tokens-allow.tsv @@ -154,15 +154,6 @@ plugins/testing/schemas/testing.schema.json melodic-software/claude-code-plugins plugins/testing/skills/audit/SKILL.md melodic-software/claude-code-plugins 1 raw link to this marketplace's own published doc plugins/testing/skills/run-e2e/context/e2e-config.md melodic-software/claude-code-plugins 1 raw link to this marketplace's own published doc plugins/testing/skills/run-e2e/context/own-driving.md melodic-software/claude-code-plugins 1 raw link to this marketplace's own published doc -plugins/toolchain/reference/ecosystems/bash.yaml melodic-software/claude-code-plugins 1 raw link to this marketplace's own published doc -plugins/toolchain/reference/ecosystems/cross-cutting.yaml melodic-software/claude-code-plugins 1 raw link to this marketplace's own published doc -plugins/toolchain/reference/ecosystems/dotnet.yaml melodic-software/claude-code-plugins 1 raw link to this marketplace's own published doc -plugins/toolchain/reference/ecosystems/go.yaml melodic-software/claude-code-plugins 1 raw link to this marketplace's own published doc -plugins/toolchain/reference/ecosystems/markdown.yaml melodic-software/claude-code-plugins 1 raw link to this marketplace's own published doc -plugins/toolchain/reference/ecosystems/powershell.yaml melodic-software/claude-code-plugins 1 raw link to this marketplace's own published doc -plugins/toolchain/reference/ecosystems/python.yaml melodic-software/claude-code-plugins 1 raw link to this marketplace's own published doc -plugins/toolchain/reference/ecosystems/typescript.yaml melodic-software/claude-code-plugins 1 raw link to this marketplace's own published doc -plugins/toolchain/reference/ecosystems/yaml.yaml melodic-software/claude-code-plugins 1 raw link to this marketplace's own published doc plugins/toolchain/reference/resolution-ladder.md melodic-software/claude-code-plugins 2 raw link to this marketplace's own published doc plugins/verification/schemas/verification.schema.json melodic-software/claude-code-plugins 1 schema $id or $ref naming this marketplace's published schema plugins/visualization/schemas/visualization.schema.json melodic-software/claude-code-plugins 1 schema $id or $ref naming this marketplace's published schema diff --git a/scripts/shell-portability-skill-md-baseline.txt b/scripts/shell-portability-skill-md-baseline.txt index d12cb05e04e..da0da27804f 100644 --- a/scripts/shell-portability-skill-md-baseline.txt +++ b/scripts/shell-portability-skill-md-baseline.txt @@ -38,5 +38,4 @@ plugins/machine-health/skills/audit/reference/windows/remediation-policy.md plugins/playwright/skills/playwright/reference/snapshots-and-refs.md plugins/skill-quality/skills/check/reference/fresh-eyes-declarations.md plugins/source-control/skills/setup/SKILL.md -plugins/toolchain/skills/check/context/powershell.md plugins/work-items/skills/scan-todos/SKILL.md From dc8569b76d2f652a39b1dd120c281e92fd95ad72 Mon Sep 17 00:00:00 2001 From: "melodic-automation-lanes[bot]" <337595936+melodic-automation-lanes[bot]@users.noreply.github.com> Date: Sat, 21 Nov 2026 11:47:22 +0000 Subject: [PATCH 2/6] Address review feedback on work-resolve-issue/issue-16032-44896998505-1 Lane-Activity: pr-unblock/address-feedback Lane-Thread: PRRT_kwDOTCGFQM66VxhH Lane-Thread: PRRT_kwDOTCGFQM66VyQY Lane-Thread: PRRT_kwDOTCGFQM66VyQh --- .../toolchain/reference/resolution-ladder.md | 19 ++++++++++++------- plugins/toolchain/skills/lint/SKILL.md | 8 +++----- plugins/toolchain/skills/setup/SKILL.md | 6 ++++++ 3 files changed, 21 insertions(+), 12 deletions(-) diff --git a/plugins/toolchain/reference/resolution-ladder.md b/plugins/toolchain/reference/resolution-ladder.md index 7dc9729020e..6e59f0b5f15 100644 --- a/plugins/toolchain/reference/resolution-ladder.md +++ b/plugins/toolchain/reference/resolution-ladder.md @@ -43,22 +43,22 @@ holds: - **Stated.** The repository's own instructions (the files "Unattended runs" lists under Stated) name a command for the id. Its globs are the file types that command checks. - **Inferred this run.** Rung 2 inferred a command surface for the id from the repo's build files - in this run. In a repository with no ecosystem record at any layer, a changed file's own - language or format, read from its extension, also infers its id, with that type's extensions as - its globs. The report names each inferred id with the globs inferred for it, on one line per + in this run. In a repository with no ecosystem record of its own (none at the team or personal + layer; a user-global record does not count), a changed file's own language or format, read from + its extension, also infers its id, with that type's extensions as its globs. The report names each inferred id with the globs inferred for it, on one line per id: `Inferred : globs , `. Name a stated or inferred id by the id the skills' aliases resolve to where one fits (`dotnet`, `python`, `typescript` for a JavaScript or TypeScript package, `bash` for shell, `powershell`, `markdown`, `go`), else by the language or format's lowercase kebab-case name. The plugin ships no ecosystem file, so no id is covered unless it is recorded, stated or inferred. Once a repository -records any ecosystem, a file type it neither records, states nor has a build file for is outside -every ecosystem. +records any ecosystem of its own (at the team or personal layer), a file type no layer records, +nothing states and no build file implies is outside every ecosystem. Before detection, `all` or an ecosystem filter, look for build files of ecosystems that are not recorded (a `Cargo.toml`, a `pyproject.toml`, a `package.json`) and run rung 2 for each id they -point to. Add each stated id, and in a repository with no record, each id a changed file's type -infers. So a stated or inferred id joins the set before any glob is matched or any filter is +point to. Add each stated id, and in a repository with no ecosystem record of its own (none at +the team or personal layer), each id a changed file's type infers. So a stated or inferred id joins the set before any glob is matched or any filter is checked. Detection, `all`, an ecosystem filter and the files-outside-every-ecosystem rule all read this set. An unattended run takes only the id and its globs from this pass, offers nothing, and resolves the @@ -81,6 +81,11 @@ order; stop at the first rung that yields it: 2. **Absent → infer, then offer to persist.** Infer the command surface from the repo's build files (solution files, `pyproject.toml`, `package.json`, …) and **offer to write** the inferred `.claude/ecosystems/.yaml` via `/toolchain:setup` so the next run reads rung 1. + An inferred command that runs a tool through a package runner (`npx`, `pnpm dlx`, `yarn dlx`, + `bunx`, `uvx`) names the package the project's manifest declares, never a shorter name the + runner could resolve to someone else's package (`@biomejs/biome`, not `biome`), and passes the + runner's no-download option where it has one (`npx --no`), so the runner never fetches and runs + a package the project did not declare. 3. **Cannot infer → ask.** Ask the user for the command; offer to persist it via `/toolchain:setup`. **Nothing resolved → report it unresolved.** When no rung yields a command for a key, run nothing diff --git a/plugins/toolchain/skills/lint/SKILL.md b/plugins/toolchain/skills/lint/SKILL.md index 2fe081a4bc3..0604a982bf1 100644 --- a/plugins/toolchain/skills/lint/SKILL.md +++ b/plugins/toolchain/skills/lint/SKILL.md @@ -173,17 +173,15 @@ Report it as its own `secret-scan` row with one Lint column: `pass` on exit 0, ` ### Workflow-security scan -In check mode, when GitHub Actions workflow files exist under `.github/` and the repository uses zizmor (a `zizmor.yml` or `zizmor.yaml` under `.github/` or at the repository root, where zizmor looks for its config), run the workflow-security scan from the repository root: +In check mode, when GitHub Actions workflow files exist under `.github/` and the repository uses zizmor (it holds a zizmor config file in a place zizmor's own config discovery reads; read the names and places from [Configuration § Discovery](https://docs.zizmor.sh/configuration/#discovery) when you need them), run the workflow-security scan from the repository root: ```bash zizmor --offline . ``` -`--offline` turns off every online action, repository fetches included. As with the secret scan, the skill states the command, so the ladder does not resolve it, and an unattended run runs it like an attended one and logs it as `assumed: workflow-security.check-cmd=zizmor --offline . (SKILL.md, )`. It runs on every check-mode run with changed files, `all` and an ecosystem filter included, whether or not any record exists or any ecosystem runs, and even when a recorded command already ran zizmor. +The scan runs offline because a lint run makes no network request; what offline mode turns off is [Usage § Operating modes](https://docs.zizmor.sh/usage/#operating-modes). As with the secret scan, the skill states the command, so the ladder does not resolve it, and an unattended run runs it like an attended one and logs it as `assumed: workflow-security.check-cmd=zizmor --offline . (SKILL.md, )`. It runs on every check-mode run with changed files, `all` and an ecosystem filter included, whether or not any record exists or any ecosystem runs, and even when a recorded command already ran zizmor. -Report it as its own `workflow-security` row with one Lint column. A finding is advisory: exit 0 reads `pass`; exit 11 to 14 (one or more findings, the code naming the highest severity) reads `advisory (findings: exit )` with the findings below the table, and changes no Status and no Overall line; any other non-zero exit reads `FAIL`. When `zizmor` is not on `PATH` it reads `skip (tool missing: zizmor)` with the hint `pip install zizmor`, an environment skip that leaves the run `INCOMPLETE`. With no zizmor config it reads `skip (opt-in unmet: no zizmor config)`. The row counts toward the table's totals like an ecosystem row, and it claims no file for the unclaimed-file lines. `--fix` and `--code-fix` do not run it. - -Basis: zizmor's [usage page](https://docs.zizmor.sh/usage/) (`--offline`, a repository-root input, exit codes 11 to 14) and [configuration page](https://docs.zizmor.sh/configuration/) (config discovery), read 2026-11-21. Recheck when either page changes those. +Report it as its own `workflow-security` row with one Lint column. A finding is advisory, and an error that is not a finding fails: exit 0 reads `pass`; on a non-zero exit, read what the code means from [Usage § Exit codes](https://docs.zizmor.sh/usage/#exit-codes). A code that means zizmor reported findings reads `advisory (findings: exit )` with the findings below the table, and changes no Status and no Overall line; any other non-zero exit reads `FAIL`. When `zizmor` is not on `PATH` it reads `skip (tool missing: zizmor)` with the hint `pip install zizmor`, an environment skip that leaves the run `INCOMPLETE`. With no zizmor config it reads `skip (opt-in unmet: no zizmor config)`. The row counts toward the table's totals like an ecosystem row, and it claims no file for the unclaimed-file lines. `--fix` and `--code-fix` do not run it. ### Code-fix confirmation gate diff --git a/plugins/toolchain/skills/setup/SKILL.md b/plugins/toolchain/skills/setup/SKILL.md index ce172c8bc0e..60ef2c33112 100644 --- a/plugins/toolchain/skills/setup/SKILL.md +++ b/plugins/toolchain/skills/setup/SKILL.md @@ -74,6 +74,12 @@ inference only: the repo's records, instructions, build files, tool configs and no default file to seed a draft from; a key nothing implies goes to the interview, never to a command the plugin picks. +A drafted command that runs a tool through a package runner (`npx`, `pnpm dlx`, `yarn dlx`, `bunx`, +`uvx`) names the package the project's manifest declares, never a shorter name the runner could +resolve to someone else's package (`@biomejs/biome`, not `biome`), and passes the runner's +no-download option where it has one (`npx --no`). A recorded command runs on later unattended runs +too, so a bare name here would fetch and run an undeclared package on every one of them. + When the repo has its own task runner or wrapper scripts (a task file, a manifest's scripts block, a scripts directory its docs or CI call), draft each command key from the matching task or script first, in any ecosystem. Draft `test-changed-cmd` from the repo's own test From 232a64e04f8d298b8f2daa4c9a01af17589bfe3a Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 21 Nov 2026 07:29:55 -0500 Subject: [PATCH 3/6] docs(toolchain): drop the deleted ecosystems path from ADR 0101 and the landscape Done-when AC4 of #16032 lets only changelogs and the kept test fixture name plugins/toolchain/reference/ecosystems/; ADR 0101's Context line now describes the bundled files without the path. landscape.json drops the deleted check/context/python.md from its pytest-randomly and pytest-rerunfailures rows. Co-Authored-By: Claude Opus 5.5 --- ...esolve-ecosystem-specifics-from-the-consumer-repository.md | 4 ++-- docs/architecture/landscape.json | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/adr/0101-resolve-ecosystem-specifics-from-the-consumer-repository.md b/docs/adr/0101-resolve-ecosystem-specifics-from-the-consumer-repository.md index 59fc6c90a3b..0192a8c49e8 100644 --- a/docs/adr/0101-resolve-ecosystem-specifics-from-the-consumer-repository.md +++ b/docs/adr/0101-resolve-ecosystem-specifics-from-the-consumer-repository.md @@ -14,8 +14,8 @@ Generic skills ship language, framework, tool and library choices that a model r In a repository the skill's authors did not anticipate, those choices run the wrong command, or a shipped default runs unnoticed in place of the repository's own tool. Two examples on `main`: -- `toolchain` bundles nine per-ecosystem default files under - `plugins/toolchain/reference/ecosystems/`. The Python file's `check-cmd` runs +- `toolchain` bundles nine per-ecosystem default files in its reference folder. The Python + file's `check-cmd` runs `uv run ruff check . --no-fix && uv run ruff format . --check && uv run pyright`, so a repository with a ruff config and no ecosystem record gets pyright in its check whether or not it uses pyright. diff --git a/docs/architecture/landscape.json b/docs/architecture/landscape.json index 2ac0dcfa726..416c13fdf59 100644 --- a/docs/architecture/landscape.json +++ b/docs/architecture/landscape.json @@ -190,8 +190,8 @@ {"from":"claude-code-plugins","to":"primer/primitives","type":"cites","relation":"external","count":1,"files":["docs/upstream/user-interface-default-sources.md"]}, {"from":"claude-code-plugins","to":"priv-kweihmann/multimetric","type":"cites","relation":"external","count":2,"files":["plugins/code-metrics/reference/collectors.md","plugins/code-metrics/scripts/collectors/multimetric.py"]}, {"from":"claude-code-plugins","to":"pulumi/pulumi","type":"cites","relation":"external","count":1,"files":["docs/conventions/pr-pipeline/README.md"]}, - {"from":"claude-code-plugins","to":"pytest-dev/pytest-randomly","type":"cites","relation":"external","count":4,"files":["plugins/debugging/skills/debug/reference/ecosystem-debugging.md","plugins/testing/skills/diagnose/context/investigate.md","plugins/testing/skills/write/context/write.md","plugins/toolchain/skills/check/context/python.md"]}, - {"from":"claude-code-plugins","to":"pytest-dev/pytest-rerunfailures","type":"cites","relation":"external","count":3,"files":["plugins/testing/skills/audit/SKILL.md","plugins/testing/skills/audit/scripts/retry-config-scan.awk","plugins/toolchain/skills/check/context/python.md"]}, + {"from":"claude-code-plugins","to":"pytest-dev/pytest-randomly","type":"cites","relation":"external","count":3,"files":["plugins/debugging/skills/debug/reference/ecosystem-debugging.md","plugins/testing/skills/diagnose/context/investigate.md","plugins/testing/skills/write/context/write.md"]}, + {"from":"claude-code-plugins","to":"pytest-dev/pytest-rerunfailures","type":"cites","relation":"external","count":2,"files":["plugins/testing/skills/audit/SKILL.md","plugins/testing/skills/audit/scripts/retry-config-scan.awk"]}, {"from":"claude-code-plugins","to":"python/cpython","type":"cites","relation":"external","count":1,"files":["plugins/source-control/skills/babysit-loop/reference/promotion-evidence-bootstrap.md"]}, {"from":"claude-code-plugins","to":"python/tzdata","type":"cites","relation":"external","count":1,"files":["plugins/session-flow/skills/keep-going/scripts/vendor/README.md"]}, {"from":"claude-code-plugins","to":"radix-ui/themes","type":"cites","relation":"external","count":2,"files":["docs/upstream/user-interface-default-sources.md"]}, From 61f95c04c7d0bf0f9938853be0edc7e9afdac151 Mon Sep 17 00:00:00 2001 From: "melodic-automation-lanes[bot]" <337595936+melodic-automation-lanes[bot]@users.noreply.github.com> Date: Sat, 21 Nov 2026 12:40:33 +0000 Subject: [PATCH 4/6] Address review feedback on work-resolve-issue/issue-16032-44896998505-1 Lane-Activity: pr-unblock/address-feedback Lane-Thread: VNOTE_3 --- ...ssue-issue-16032-44896998505-1-d4f74506.md | 6 ------ plugins/toolchain/skills/lint/SKILL.md | 20 ++++--------------- 2 files changed, 4 insertions(+), 22 deletions(-) diff --git a/.changes/toolchain/work-resolve-issue-issue-16032-44896998505-1-d4f74506.md b/.changes/toolchain/work-resolve-issue-issue-16032-44896998505-1-d4f74506.md index 91b4c278290..7eeb2322d1b 100644 --- a/.changes/toolchain/work-resolve-issue-issue-16032-44896998505-1-d4f74506.md +++ b/.changes/toolchain/work-resolve-issue-issue-16032-44896998505-1-d4f74506.md @@ -25,12 +25,6 @@ bump: major repository with no ecosystem record, a changed file's own type also infers its id, so it reads `skip (unresolved: ...)` rather than going unchecked in silence. -### Added - -- `/toolchain:lint` states the workflow-security scan itself. With a zizmor config at the root or - under `.github/` and workflow files present, a check-mode run runs `zizmor --offline .` and - reports a `workflow-security` row. A finding is advisory and fails nothing. - ### Changed - `/toolchain:check` keeps its retry, seed and slow-test reporting rules in the skill, written for diff --git a/plugins/toolchain/skills/lint/SKILL.md b/plugins/toolchain/skills/lint/SKILL.md index 0604a982bf1..b7c917a79d2 100644 --- a/plugins/toolchain/skills/lint/SKILL.md +++ b/plugins/toolchain/skills/lint/SKILL.md @@ -41,7 +41,7 @@ Use `/toolchain:lint` for quick feedback during development. Use `/verification: **The command surface is resolved, not hardcoded.** `/toolchain:lint` resolves each ecosystem's `lint-cmd`/`check-cmd`/`fix-cmd`/`code-fix-cmd` through the shared three-rung ladder in [`${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md`](${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md). Shared with `/toolchain:check`: the consuming repo's tracked `.claude/ecosystems/.yaml` is authoritative when present, then inference from its build files, then asking. The plugin ships no default command: a key nothing resolves is reported unresolved and runs nothing. -**The security scans are lint's own.** The secret scan and the workflow-security scan run from this skill, not from a record, each under its own opt-in, in attended and unattended runs alike: see [Secret scan](#secret-scan) and [Workflow-security scan](#workflow-security-scan). +**The secret scan is lint's own.** It runs from this skill, not from a record, under its own opt-in, in attended and unattended runs alike: see [Secret scan](#secret-scan). Any other scan, a workflow-security scan included, runs only from a command the ladder resolves. **Two mutators, two gates.** Format-only and code-changing autofixes are separate keys and separate flags. Bare `--fix` must never run semantic lint autofixes (ruff `check --fix`, golangci-lint `--fix`, biome `check --write`, …). @@ -116,7 +116,7 @@ Auto-detection algorithm: 3. Run every ecosystem with ≥1 glob match whose `opt-in` condition holds, plus cross-cutting when any text file changed. This binary run/skip treatment applies cleanly when `opt-in` describes a single condition for the whole `check-cmd`: unmet → excluded from the run but still reported (see sections 2 and 3 below, `skip (opt-in unmet: ...)`; never silently omitted). When `opt-in` instead describes multiple independent per-tool conditions bundled into one opaque command string (one tool always, another only with its own config present), this rule does not apply. `check-cmd`/`fix-cmd`/`code-fix-cmd` is a single opaque string with no way to run one sub-tool's portion without the other, so run it whole and report its real output. The known atomicity limitation this leaves open is in `/toolchain:check`'s Gotchas. 4. A changed file is unclaimed when no resolved ecosystem's `globs` match it, cross-cutting's `**` aside: that glob is never a claim by itself, whether cross-cutting runs or is disabled. A match by any other ecosystem counts, even one that is disabled or skipped for an unmet opt-in: that row already reports the consumer's choice. Collect each unclaimed text file for the report's two fixed lines (section 3). Under `all` the changed files still come from the detection paths above; an ecosystem filter skips this step. A deleted file is not named. A binary file stays quiet. Decide binary with `git ls-files --eol -c -o -- `: the file is binary when Git identifies its working-tree content as not text ([`--eol`](https://git-scm.com/docs/git-ls-files#Documentation/git-ls-files.txt---eol)). A path with no working-tree content is deleted or not a regular file, never binary. One command serves a working-tree change, the branch diff and a caller-supplied changed-file list. -If neither detection path yields changes and no filter specified: report "No changes found (working tree clean, no branch diff vs the default branch). Use `/toolchain:lint all` to check the full repo, or `/toolchain:lint ` for a specific filter." and stop. If files changed but no ecosystem runs, print the unclaimed-file line (when it names any file) instead of the table, and stop, unless a security scan's opt-in holds (a `.gitleaks.toml` at the root, or a zizmor config with workflows present): then run the [Secret scan](#secret-scan) and the [Workflow-security scan](#workflow-security-scan) whose opt-ins hold, record the Overall line (section 5), and report their rows, the unclaimed-file lines and the Overall line. +If neither detection path yields changes and no filter specified: report "No changes found (working tree clean, no branch diff vs the default branch). Use `/toolchain:lint all` to check the full repo, or `/toolchain:lint ` for a specific filter." and stop. If files changed but no ecosystem runs, print the unclaimed-file line (when it names any file) instead of the table, and stop, unless the secret scan's opt-in holds (a `.gitleaks.toml` at the root): then run the [Secret scan](#secret-scan), record the Overall line (section 5), and report its row, the unclaimed-file lines and the Overall line. ### 2. Run linters per ecosystem @@ -171,18 +171,6 @@ The skill states the command, so the ladder does not resolve it, and an unattend Report it as its own `secret-scan` row with one Lint column: `pass` on exit 0, `FAIL` on a finding or any other non-zero exit, and `skip (tool missing: gitleaks)` with the hint `winget install Gitleaks.Gitleaks | brew install gitleaks` when `gitleaks` is not on `PATH`, an environment skip that leaves the run `INCOMPLETE`. With no `.gitleaks.toml` at the root it reads `skip (opt-in unmet: no .gitleaks.toml at the repo root)`. The row counts toward the table's totals like an ecosystem row, and it claims no file for the unclaimed-file lines. `--fix` and `--code-fix` do not run it. -### Workflow-security scan - -In check mode, when GitHub Actions workflow files exist under `.github/` and the repository uses zizmor (it holds a zizmor config file in a place zizmor's own config discovery reads; read the names and places from [Configuration § Discovery](https://docs.zizmor.sh/configuration/#discovery) when you need them), run the workflow-security scan from the repository root: - -```bash -zizmor --offline . -``` - -The scan runs offline because a lint run makes no network request; what offline mode turns off is [Usage § Operating modes](https://docs.zizmor.sh/usage/#operating-modes). As with the secret scan, the skill states the command, so the ladder does not resolve it, and an unattended run runs it like an attended one and logs it as `assumed: workflow-security.check-cmd=zizmor --offline . (SKILL.md, )`. It runs on every check-mode run with changed files, `all` and an ecosystem filter included, whether or not any record exists or any ecosystem runs, and even when a recorded command already ran zizmor. - -Report it as its own `workflow-security` row with one Lint column. A finding is advisory, and an error that is not a finding fails: exit 0 reads `pass`; on a non-zero exit, read what the code means from [Usage § Exit codes](https://docs.zizmor.sh/usage/#exit-codes). A code that means zizmor reported findings reads `advisory (findings: exit )` with the findings below the table, and changes no Status and no Overall line; any other non-zero exit reads `FAIL`. When `zizmor` is not on `PATH` it reads `skip (tool missing: zizmor)` with the hint `pip install zizmor`, an environment skip that leaves the run `INCOMPLETE`. With no zizmor config it reads `skip (opt-in unmet: no zizmor config)`. The row counts toward the table's totals like an ecosystem row, and it claims no file for the unclaimed-file lines. `--fix` and `--code-fix` do not run it. - ### Code-fix confirmation gate `--code-fix` mutates semantics, not just whitespace, the only `/toolchain:lint` path that does. Always emit the plan first: @@ -232,7 +220,7 @@ In check mode, settle the Overall line and record it (section 5) before writing Overall: FAIL (1 of 4 ecosystems failed) ``` -Use `pass`, `FAIL`, a named skip, `—` (not applicable), or, on the `workflow-security` row only, `advisory (findings: exit )`, which counts as passed and never makes a Status or the Overall line `FAIL` or `INCOMPLETE`. Every skip names its reason in `/toolchain:check`'s named classes, and its class decides whether it blocks a "done" claim exactly as `/toolchain:check`'s report table (its section 3) classifies it: `skip (tool missing: )`, `skip (prerequisite missing: )` and `skip (unresolved: .)` are environment skips and block "done"; `skip (opt-in unmet: )` is the consumer's opt-in and does not. Lint installs nothing and runs no CI-parity gates, so it never emits the `dependencies missing` or `unsupported` classes. +Use `pass`, `FAIL`, a named skip, or `—` (not applicable). Every skip names its reason in `/toolchain:check`'s named classes, and its class decides whether it blocks a "done" claim exactly as `/toolchain:check`'s report table (its section 3) classifies it: `skip (tool missing: )`, `skip (prerequisite missing: )` and `skip (unresolved: .)` are environment skips and block "done"; `skip (opt-in unmet: )` is the consumer's opt-in and does not. Lint installs nothing and runs no CI-parity gates, so it never emits the `dependencies missing` or `unsupported` classes. An ecosystem's Status and the Overall line read `FAIL` when any cell failed, `INCOMPLETE` when nothing failed but an environment skip remains, and `PASS` only when neither holds. `INCOMPLETE` names each cause with its reason (e.g. `Overall: INCOMPLETE (3 of 4 ecosystems passed; markdown: skip (tool missing: markdownlint-cli2))`), so a caller such as `/verification:confirm` holds its verdict on a lint-only environment gap. An opt-in-unmet skip or a `—` cell never makes a run `INCOMPLETE`. @@ -266,7 +254,7 @@ In check mode, before writing the report, record the settled Overall line for th node "${CLAUDE_PLUGIN_ROOT}/scripts/record-result.mjs" --skill lint --dir "$REPO_ROOT" --overall '' ``` -The plugin's Stop hook reads it at turn end the same way it reads `/toolchain:check`'s record. Record nothing for `--fix` or `--code-fix`: the fix changes the tree, so the check that would count is the next check-mode run. Skip it too when an ecosystem filter narrowed the run (`all` and a caller's changed-file list do not narrow it), and when the run stopped at "No changes found" or with no ecosystem to run and no security scan run. A run with no ecosystem to run that did run a security scan (section 1's opt-in case) records its Overall line like any other check-mode run, so a `secret-scan` or `workflow-security` FAIL reaches the Stop hook. A failed record (exit 2, for example where a sandbox blocks the git calls that hash the tree, or exit 1 for a line it rejects) changes nothing in the report: put one `Not recorded: ` line above the table, and still end the reply with the full report, its table, the lines below it and the Overall line. +The plugin's Stop hook reads it at turn end the same way it reads `/toolchain:check`'s record. Record nothing for `--fix` or `--code-fix`: the fix changes the tree, so the check that would count is the next check-mode run. Skip it too when an ecosystem filter narrowed the run (`all` and a caller's changed-file list do not narrow it), and when the run stopped at "No changes found" or with no ecosystem to run and no secret scan run. A run with no ecosystem to run that did run the secret scan (section 1's opt-in case) records its Overall line like any other check-mode run, so a `secret-scan` FAIL reaches the Stop hook. A failed record (exit 2, for example where a sandbox blocks the git calls that hash the tree, or exit 1 for a line it rejects) changes nothing in the report: put one `Not recorded: ` line above the table, and still end the reply with the full report, its table, the lines below it and the Overall line. ## Edge cases From 9400abb717051c1063750ea4dea6f39de70df228 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 21 Nov 2026 11:33:20 -0500 Subject: [PATCH 5/6] docs(adr): keep ADR 0101's Context as accepted and record the deletion as an amendment The owner chose to leave accepted records as written ("go w/ recommendations", 2026-11-21, option B in session): 232a64e0's rewording of the Context line is undone, and a dated third amendment records that #16032 deleted the bundled ecosystems folder. #16032's AC4 grep now also finds the ADR, an accepted record exempted on the issue. Co-Authored-By: Claude Opus 5.5 --- ...system-specifics-from-the-consumer-repository.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/adr/0101-resolve-ecosystem-specifics-from-the-consumer-repository.md b/docs/adr/0101-resolve-ecosystem-specifics-from-the-consumer-repository.md index 0192a8c49e8..2bf1c6dab31 100644 --- a/docs/adr/0101-resolve-ecosystem-specifics-from-the-consumer-repository.md +++ b/docs/adr/0101-resolve-ecosystem-specifics-from-the-consumer-repository.md @@ -2,7 +2,8 @@ - Status: accepted; amended 2026-11-16 (source citations exclude one ecosystem's tool documentation and examples, see the amendment below); amended 2026-11-17 (two kept classes: operating a kept - adapter's tool, and a measured fact; see the second amendment) + adapter's tool, and a measured fact; see the second amendment); amended 2026-11-21 (the bundled + ecosystems folder is deleted; see the third amendment) - Date: 2026-11-13 - Refs: [#15703](https://github.com/melodic-software/claude-code-plugins/issues/15703) (spec), [#15706](https://github.com/melodic-software/claude-code-plugins/issues/15706); owner decision of @@ -14,8 +15,8 @@ Generic skills ship language, framework, tool and library choices that a model r In a repository the skill's authors did not anticipate, those choices run the wrong command, or a shipped default runs unnoticed in place of the repository's own tool. Two examples on `main`: -- `toolchain` bundles nine per-ecosystem default files in its reference folder. The Python - file's `check-cmd` runs +- `toolchain` bundles nine per-ecosystem default files under + `plugins/toolchain/reference/ecosystems/`. The Python file's `check-cmd` runs `uv run ruff check . --no-fix && uv run ruff format . --check && uv run pyright`, so a repository with a ruff config and no ecosystem record gets pyright in its check whether or not it uses pyright. @@ -128,3 +129,9 @@ wrong thing, and only while a targeted eval case shows the loss without it. Neit default: no bundled default survives decision 2. A record of this marketplace's own files, keys, rule ids, scripts or behavior, and the upstream source of a kept script's patterns, is not a choice made for the consumer and is outside these classes. + +## Amendment (2026-11-21): the bundled ecosystems folder is deleted + +[#16032](https://github.com/melodic-software/claude-code-plugins/issues/16032) deleted the nine +default files under `plugins/toolchain/reference/ecosystems/`, and the Context section above still +describes `main` as it stood when this record was accepted. From 08b4db6d3d13c9102818ff3b3ad72724ef1d95be Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 21 Nov 2026 19:38:12 -0500 Subject: [PATCH 6/6] fix(toolchain): add cross-cutting to a lint run only when a command is recorded or stated With the bundled cross-cutting.yaml gone, nothing resolves cross-cutting in a repository without its own record, so adding it on every text change made each such lint run INCOMPLETE or ask a question. It now adds no row then, and its files go to the Outside every ecosystem line. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01RAoAtUnz4WHB5auUnwQYq7 --- plugins/toolchain/skills/lint/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/toolchain/skills/lint/SKILL.md b/plugins/toolchain/skills/lint/SKILL.md index b7c917a79d2..746ca37d9bc 100644 --- a/plugins/toolchain/skills/lint/SKILL.md +++ b/plugins/toolchain/skills/lint/SKILL.md @@ -107,13 +107,13 @@ else fi ``` -The loop probes candidate remotes in priority order, the remote the current branch tracks (`branch..remote`) first, then `origin` if present, then the rest, and selects the first one whose default branch resolves to a locally available tracking ref, never a hardcoded remote name. This handles an unpushed feature branch (no tracking remote) in a repo cloned with a different remote name (e.g. `git clone -o vendor`), and skips a remote that was added but never fetched (its default branch has no local `refs/remotes//` to diff against) in favor of a later remote that does, the candidate is accepted only when `git rev-parse` confirms the tracking ref exists locally. Each candidate's default branch comes from that remote's own `HEAD` (not the current branch's upstream, which on a pushed feature branch points at the feature branch itself and would make `merge-base` equal `HEAD`, yielding an empty diff), falling back to a `git ls-remote --symref` query when the local `HEAD` symref is absent. `merge-base` is taken against the fully-qualified remote-tracking ref `refs/remotes/$REMOTE/$DEFAULT_BRANCH`, which resolves without a local branch of that name and, like the `rev-parse` verify, cannot be misparsed as an option when the remote name begins with a dash (`git clone --origin=-x`); the `git ls-remote` probe terminates option parsing with `--end-of-options` for the same reason. If no candidate yields a locally available default branch, skip the branch-diff path rather than guessing. A caller passing an explicit changed-file list (e.g. `/verification:confirm`) overrides both detection paths. Cross-cutting runs alongside detected ecosystems when any text file changed and the repo opts into its tools. +The loop probes candidate remotes in priority order, the remote the current branch tracks (`branch..remote`) first, then `origin` if present, then the rest, and selects the first one whose default branch resolves to a locally available tracking ref, never a hardcoded remote name. This handles an unpushed feature branch (no tracking remote) in a repo cloned with a different remote name (e.g. `git clone -o vendor`), and skips a remote that was added but never fetched (its default branch has no local `refs/remotes//` to diff against) in favor of a later remote that does, the candidate is accepted only when `git rev-parse` confirms the tracking ref exists locally. Each candidate's default branch comes from that remote's own `HEAD` (not the current branch's upstream, which on a pushed feature branch points at the feature branch itself and would make `merge-base` equal `HEAD`, yielding an empty diff), falling back to a `git ls-remote --symref` query when the local `HEAD` symref is absent. `merge-base` is taken against the fully-qualified remote-tracking ref `refs/remotes/$REMOTE/$DEFAULT_BRANCH`, which resolves without a local branch of that name and, like the `rev-parse` verify, cannot be misparsed as an option when the remote name begins with a dash (`git clone --origin=-x`); the `git ls-remote` probe terminates option parsing with `--end-of-options` for the same reason. If no candidate yields a locally available default branch, skip the branch-diff path rather than guessing. A caller passing an explicit changed-file list (e.g. `/verification:confirm`) overrides both detection paths. Cross-cutting runs alongside detected ecosystems when any text file changed and the repository records or states a cross-cutting command. Auto-detection algorithm: 1. With the stated and inferred ecosystems already added (above), resolve each covered ecosystem's config per [`${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md`](${CLAUDE_PLUGIN_ROOT}/reference/resolution-ladder.md) (consumer `.claude/ecosystems/.yaml` when present, else what the repo's build files infer, named with its globs in the report, else ask; a key nothing resolves reads `skip (unresolved: .)`, and a malformed consumer file warns and degrades to inference, never a hard stop). An unattended run (the ladder's "Run kind") resolves commands by the ladder's "Unattended runs" instead: recorded, stated, then inferred, and a key none resolves reads `skip (unresolved: .)`. Skip any ecosystem whose resolved `enabled` is `false` (a consumer opt-out). Excluded even under `all` 2. For each ecosystem, match its `globs` against the changed-files list -3. Run every ecosystem with ≥1 glob match whose `opt-in` condition holds, plus cross-cutting when any text file changed. This binary run/skip treatment applies cleanly when `opt-in` describes a single condition for the whole `check-cmd`: unmet → excluded from the run but still reported (see sections 2 and 3 below, `skip (opt-in unmet: ...)`; never silently omitted). When `opt-in` instead describes multiple independent per-tool conditions bundled into one opaque command string (one tool always, another only with its own config present), this rule does not apply. `check-cmd`/`fix-cmd`/`code-fix-cmd` is a single opaque string with no way to run one sub-tool's portion without the other, so run it whole and report its real output. The known atomicity limitation this leaves open is in `/toolchain:check`'s Gotchas. +3. Run every ecosystem with ≥1 glob match whose `opt-in` condition holds, plus cross-cutting when any text file changed and the repository records or states a cross-cutting command (with neither, cross-cutting adds no row and its files go to the `Outside every ecosystem:` line). This binary run/skip treatment applies cleanly when `opt-in` describes a single condition for the whole `check-cmd`: unmet → excluded from the run but still reported (see sections 2 and 3 below, `skip (opt-in unmet: ...)`; never silently omitted). When `opt-in` instead describes multiple independent per-tool conditions bundled into one opaque command string (one tool always, another only with its own config present), this rule does not apply. `check-cmd`/`fix-cmd`/`code-fix-cmd` is a single opaque string with no way to run one sub-tool's portion without the other, so run it whole and report its real output. The known atomicity limitation this leaves open is in `/toolchain:check`'s Gotchas. 4. A changed file is unclaimed when no resolved ecosystem's `globs` match it, cross-cutting's `**` aside: that glob is never a claim by itself, whether cross-cutting runs or is disabled. A match by any other ecosystem counts, even one that is disabled or skipped for an unmet opt-in: that row already reports the consumer's choice. Collect each unclaimed text file for the report's two fixed lines (section 3). Under `all` the changed files still come from the detection paths above; an ecosystem filter skips this step. A deleted file is not named. A binary file stays quiet. Decide binary with `git ls-files --eol -c -o -- `: the file is binary when Git identifies its working-tree content as not text ([`--eol`](https://git-scm.com/docs/git-ls-files#Documentation/git-ls-files.txt---eol)). A path with no working-tree content is deleted or not a regular file, never binary. One command serves a working-tree change, the branch diff and a caller-supplied changed-file list. If neither detection path yields changes and no filter specified: report "No changes found (working tree clean, no branch diff vs the default branch). Use `/toolchain:lint all` to check the full repo, or `/toolchain:lint ` for a specific filter." and stop. If files changed but no ecosystem runs, print the unclaimed-file line (when it names any file) instead of the table, and stop, unless the secret scan's opt-in holds (a `.gitleaks.toml` at the root): then run the [Secret scan](#secret-scan), record the Overall line (section 5), and report its row, the unclaimed-file lines and the Overall line.