fix(toolchain): wire the ecosystem-commands `gates` schema array into an actual execution step

[kyle-sexton]

Summary

docs/conventions/ecosystem-commands/ecosystem.schema.json defines a structured gates array (name/cmd/trigger-globs/remediation) that any ecosystem config — bundled or consumer-tracked — can declare. Demonstrated in docs/conventions/ecosystem-commands/examples/dotnet.yaml's nuget-lockfile-drift entry (pre-existing) and, as of PR #910, plugins/toolchain/reference/ecosystems/go.yaml's go-mod-tidy-drift entry.

Neither plugins/toolchain/skills/check/SKILL.md nor skills/lint/SKILL.md actually execute this resolved array. The only gate-execution mechanism either skill documents is "Project-declared CI-parity gates" (check/SKILL.md line ~121), which is explicitly prose-based and consumer-CLAUDE.md-only — "These live in the consumer's own conventions (its CLAUDE.md / rules / commands reference) — this plugin ships none of its own." That sentence is itself now stale once a bundled ecosystem YAML does ship a gates entry.

Net effect: a gates entry in any ecosystem config (bundled default or a consumer's own tracked .claude/ecosystems/<eco>.yaml) is currently inert — resolved as part of the four-rung ladder's command surface, never invoked by any documented workflow step.

Where this was caught

Surfaced by an automated Codex review pass on PR #910 (plugins/toolchain/reference/ecosystems/go.yaml line 42 / plugins/toolchain/skills/check/SKILL.md line 121) while adding the Go ecosystem's go-mod-tidy-drift gate. Confirmed by re-reading check/SKILL.md in full — no loop/step consumes the resolved gates field anywhere.

Scope

Cross-cutting toolchain plugin change (affects every ecosystem that declares or could declare gates, not Go-specific) — deliberately not folded into #832's PR, which is scoped to adding the Go ecosystem itself. The go-mod-tidy-drift entry in go.yaml is left in place (schema-correct, matches the existing example-fixture precedent, documents intent) — it will start actually running once this is wired up, with no further Go-specific change needed.

Suggested fix shape

Add a step to check/SKILL.md (and lint/SKILL.md if applicable) that, after resolving each affected ecosystem's command surface, iterates its resolved gates array and runs each gate.cmd when the changed-files set matches gate.trigger-globs, reporting pass/fail + gate.remediation on failure — same reporting shape already described for "project-declared" gates, just sourced from the structured array instead of requiring consumer CLAUDE.md prose. Update the stale "this plugin ships none of its own" sentence once real bundled gates exist.

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

[kyle-sexton]

This was generated by AI (triage-lane planning subagent).

Implementation plan: wire the ecosystem-commands gates array into an executable step

Grounding (verified against origin/main)

• plugins/toolchain/skills/check/SKILL.md:90 already resolves gates as part of each ecosystem's command surface through the four-rung ladder.
• plugins/toolchain/skills/check/SKILL.md:121 is the only gate-related workflow step. It is prose/consumer-CLAUDE.md-only and ends with the now-stale sentence "this plugin ships none of its own."
• plugins/toolchain/skills/check/SKILL.md:119 and :140 reference these "project-declared CI-parity gates" (independence from check-cmd; the report scaffold that summarizes fired gates).
• plugins/toolchain/skills/check/SKILL.md:135 computes the Overall verdict per ecosystem — gates do not currently feed it.
• plugins/toolchain/reference/ecosystems/go.yaml:40-44 ships a real gates entry (go-mod-tidy-drift); docs/conventions/ecosystem-commands/examples/dotnet.yaml:11-15 ships nuget-lockfile-drift. So a bundled default already declares a gate.
• docs/conventions/ecosystem-commands/ecosystem.schema.json:59-77 defines the array: name (required), cmd (required), trigger-globs (optional — "omit to run whenever the ecosystem runs"), remediation (optional pointer shown on failure).
• plugins/toolchain/skills/setup/SKILL.md:86-87 already routes new gates "into the ecosystem file's gates array" — the array is the declared channel.
• plugins/toolchain/skills/lint/SKILL.md — grep confirms no mention of gates anywhere (it resolves only check-cmd/fix-cmd).
• Plugin is semver'd: plugins/toolchain/.claude-plugin/plugin.json:4 = 0.8.0; plugins/toolchain/CHANGELOG.md follows Keep a Changelog.

Design decision (the one maintainer-vetoable fork): wire gates into check only, not lint — RECOMMENDED

Recommendation: add the gates-execution step to check/SKILL.md only; leave lint/SKILL.md untouched.

Rationale: every gate the schema describes and both shipped examples are CI-parity checks beyond build/test/lint — lockfile drift (dotnet restore --locked-mode), module drift (go mod tidy -diff), generated-artifact freshness. None is a lint/format operation. They belong with the heavier build+test+lint step, and /verification:confirm (which composes check) is the real pre-commit gate. Adding them to /toolchain:lint would violate its stated speed contract (lint/SKILL.md:21, "Fast ~5-15s"), duplicate the execution/report logic, and run a full go mod tidy/restore on the fast path.

Counterpoint the maintainer should weigh before accepting: lint/SKILL.md:158 explicitly bills /toolchain:lint --fix as a pre-commit step, so a user whose pre-commit habit is lint-only would never trip a lockfile/mod-tidy gate locally — the parity gap the array exists to close would stay open for them. The rebuttal (gates are CI-parity, /verification:confirm is the sanctioned pre-commit gate, lint stays fast) still wins, but this is the fork to veto if the maintainer disagrees. If lint should ever run gates, the cleaner path is a future phase/scope discriminator on gate entries rather than running the whole array on the fast path — deferred, not part of this change.

Concrete edits to check/SKILL.md

1. Replace the prose step at :121 ("Project-declared CI-parity gates … this plugin ships none of its own") with a structured-array execution step. The resolved gates array (bundled default or consumer file, per the ladder already invoked in §1.5) becomes the channel — matching what setup/SKILL.md:86-87 already declares; drop the consumer-CLAUDE.md-prose framing (it was an unverifiable "agent notices prose" path). New step semantics, slotted after build→test→lint in §2 "Run checks":

CI-parity gates (resolved gates array). After an affected ecosystem's build → test → lint, iterate its resolved gates array (§1.5). For each gate:

• Fire condition: if trigger-globs is present, run the gate only when ≥1 changed file matches (matched against the full changed-files set, not the ecosystem-scoped subset — a gate's trigger files need not classify into the ecosystem's own globs). If trigger-globs is omitted, run whenever the ecosystem runs. A present trigger-globs with no matching changed file (e.g. check all on a clean tree) → the gate does not fire.
• Run gate.cmd (opaque shell string; substitute the same placeholders as other commands — <files>, $REPO_ROOT, …) from $REPO_ROOT with absolute paths.
• Tool presence: as with check-cmd, if the gate's tool is missing from PATH, report skip (reusing the ecosystem's install-hint) — never FAIL.
• Outcome: report pass/FAIL by name. On FAIL, surface gate.remediation. A fired gate that fails is a real failure and counts toward the run's FAIL verdict (unlike opt-in/missing-tool skips).

2. Fix the Overall-verdict computation (:135 scaffold). The Overall line is currently per-ecosystem only. State explicitly that a failed gate flips Overall to FAIL and is counted even when every build/test/lint cell passed. Keep the existing report scaffold at :140 (it already summarizes fired gates by name + outcome + remediation-on-failure) — just confirm it sources from the structured array and that gate failures reach Overall.

3. Fix the stale sentence. Replace "these live in the consumer's own conventions … this plugin ships none of its own" with an accurate pointer: gates resolve through the ladder like every other key — a bundled default may ship one (e.g. go.yaml's go-mod-tidy-drift), and a consumer declares its own in .claude/ecosystems/<eco>.yaml's gates array.

4. Reconcile the cross-reference at :119 ("Project-declared CI-parity gates (below) … run independent of check-cmd") to name the structured-array step; the independence-from-check-cmd claim stays valid.

Metadata edits

• plugins/toolchain/.claude-plugin/plugin.json:4: bump 0.8.0 → 0.9.0 (new executable behavior — an "Added" per semver-minor).
• plugins/toolchain/CHANGELOG.md: new ## [0.9.0] → ### Added entry noting resolved gates arrays now execute in /toolchain:check (previously inert), closing the gap where a bundled or consumer-declared gate was resolved but never run; go.yaml's go-mod-tidy-drift and a consumer's nuget-lockfile-drift now actually run.

Explicitly NOT changed (traced, no touch needed)

• check/SKILL.md:90 — already lists gates in the resolved surface.
• reference/resolution-ladder.md:22 — already lists gates as a resolved key.
• setup/SKILL.md:86-87,103 — already routes gates into the array.
• reference/ecosystems/go.yaml, examples/dotnet.yaml — the gate entries are schema-correct and start running as-is; no per-ecosystem change.
• lint/SKILL.md — untouched (see fork above).
• ecosystem.schema.json — no schema change; the array shape is sufficient.

Acceptance criteria

1. /toolchain:check (and /toolchain:check all, /toolchain:check go) executes each affected ecosystem's resolved gates entries after build/test/lint.
2. A gate with trigger-globs runs only when a changed file matches (full changed-files set); a gate without trigger-globs runs whenever its ecosystem runs; check all on a clean tree does not fire trigger-gated gates.
3. On a repo with drift, go.yaml's go-mod-tidy-drift (or dotnet's nuget-lockfile-drift) reports FAIL, prints its remediation, and flips Overall to FAIL; on a clean repo it reports pass.
4. A missing gate tool reports skip (with the ecosystem's install-hint), never FAIL.
5. The report scaffold summarizes each fired gate by name + outcome + remediation-on-failure, and gate failures are reflected in the Overall verdict/count.
6. The stale "this plugin ships none of its own" sentence is gone; the replacement points at the ladder-resolved array (bundled or consumer).
7. lint/SKILL.md is unchanged (unless the maintainer vetoes the fork).
8. plugin.json bumped to 0.9.0 and a matching ## [0.9.0] CHANGELOG entry added.
9. Skill files remain schema/lint-clean (/skill-quality:check), and gates execution composes transparently into /verification:confirm and check-composing agents with no further change.

[kyle-sexton]

This was generated by AI (triage-decide lane — intake routing).

Routed status: ready per T2 (ready-with-noted-decision). The planning subagent's plan (above) is well-grounded with a single maintainer-vetoable fork and a clear recommended default — not open design space.

Decision defaulted: wire the gates-execution step into check/SKILL.md only, leaving lint/SKILL.md untouched — veto before merge. The implementer should confirm this scope holds (whether any gate is lint-appropriate rather than check-appropriate); if a maintainer wants gates to also run in the lint path, that is a one-line addition, not a redesign.

No open prerequisite gates this (the go-mod-tidy-drift gate in go.yaml is already schema-correct on main and starts running once this lands; #832's Go-ecosystem scope is independent).

[kyle-sexton]

Claim (work lane, T3) — dispatching an implementation subagent this cycle. 2026-07-22T16:12:32Z

[kyle-sexton]

[kyle-sexton]

Done (2026-07-22): Wired the resolved ecosystem gates array into an execution step in check/SKILL.md §2 (fire-condition/tool-presence/pass-FAIL-skip semantics, Overall verdict now covers gate-only failures). lint/SKILL.md deliberately left unchanged (gates are CI-parity checks beyond lint's fast path — flagged as maintainer-vetoable). CI green, no review threads. Will auto-close when PR #1020 merges.