toolchain: publisher org/repo/branch URL propagates into consumer-tracked .claude/ecosystems/*.yaml headers

[kyle-sexton]

Plugin: toolchain · Categories: hardcoded org string (1), string leakage into consumer artifacts (4) — keep/soften decision needed
Source: work-readiness sweep (read-only audit vs docs/PLUGIN-PHILOSOPHY.md + docs/MIGRATION-PLAYBOOK.md)

Findings

• plugins/toolchain/reference/ecosystems/dotnet.yaml:4 (identical header in bash.yaml:3, python.yaml:3, typescript.yaml:3, powershell.yaml:3, markdown.yaml:3, yaml.yaml:3, cross-cutting.yaml:3): # https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/ecosystem-commands/README.md
• plugins/toolchain/reference/resolution-ladder.md:7, plugins/toolchain/reference/topic-docs.md:9
• Propagation trigger: plugins/toolchain/skills/setup/SKILL.md:107 — "Each file carries a one-line header comment citing the contract"

Why flagged

Bundled defaults are seeds for consumer-written files: setup copies the contract-citing header, so the hardcoded melodic-software/claude-code-plugins org+repo+main-branch string lands in the consumer's tracked .claude/ecosystems/*.yaml — the one vector by which the publisher name reaches a consumer artifact. Nuance: it is provenance documentation, not runtime behavior (nothing resolves the URL at runtime), and publisher metadata is sanctioned — but the main pin will rot if the contract moves, and PLUGIN-PHILOSOPHY's design boundary says runtime surfaces must not depend on publisher/repo names. Filed as an explicit keep-vs-soften decision.

Fix direction

If softening: have setup write consumer files with a neutral header (e.g. # conforms to ecosystem-commands contract (see toolchain plugin reference)), keeping the full contract URL only in the plugin's own bundled reference files. Do not hardcode-swap the org name.

[kyle-sexton]

This was generated by AI during triage.

Triage → needs-human, priority: high. String-leakage-into-consumer-artifacts finding on a priority plugin (toolchain): setup copies a contract-citing header carrying the melodic-software/claude-code-plugins/main publisher string into consumer-tracked .claude/ecosystems/*.yaml. High per directive. The body frames this as an explicit keep-vs-soften decision (provenance doc vs main-pin rot / publisher-name-in-consumer-artifact) — human judgment required.

[kyle-sexton]

Decision brief (2-minute read)

Problem. /toolchain:setup writes consumer-tracked .claude/ecosystems/<ecosystem>.yaml files whose header cites the contract by full URL — https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/… — landing the publisher org, repo name, and a main branch pin inside the consumer's own tracked files. It is provenance only (nothing resolves the URL at runtime), but it is the one vector by which the publisher's identity reaches consumer artifacts, and the main pin rots if the contract ever moves.

Today. Verified on main:

• Bundled seeds carry the URL: plugins/toolchain/reference/ecosystems/dotnet.yaml:4 (same header in bash/python/typescript/powershell/markdown/yaml/cross-cutting at :3).
• Propagation trigger: plugins/toolchain/skills/setup/SKILL.md:107 — "Each file carries a one-line header comment citing the contract."
• Plugin-internal occurrences (NOT written to consumers): plugins/toolchain/reference/resolution-ladder.md:7, plugins/toolchain/reference/topic-docs.md:9, and the schema $id in docs/conventions/ecosystem-commands/ecosystem.schema.json:3.
• The bundled seeds themselves are never written into a consumer repo (dotnet.yaml:1-3 states this; resolution-ladder.md:40-43 confirms rung-4-only) — only setup's header convention propagates.

Options.

1. RECOMMENDED — Soften at the write boundary: neutral, versioned header in consumer files; full URL stays plugin-internal. Setup writes something like # ecosystem-commands contract v<version> — schema and docs ship with the toolchain plugin (reference/resolution-ladder.md), taking the version from the contract's CHANGELOG; the plugin's own bundled reference files keep the full URL. Tradeoffs: a consumer reaching the contract doc goes through the installed plugin (one hop) instead of a raw URL — but that pointer cannot rot, names no publisher in consumer-tracked files (the PLUGIN-PHILOSOPHY boundary this issue was filed against), and survives a repo rename/re-home/branch change with zero consumer diffs. Naming contract + version preserves provenance and drift detection. Trivially reversible; already-written consumer files keep their old header until the next setup re-run, and headers are inert to the tolerant reader either way. Per the issue's own guidance: do not hardcode-swap the org name.
2. Keep as-is. Publisher metadata is sanctioned and this is documentation, not behavior. But it institutionalizes the single publisher-string leak into consumer artifacts plus a main pin that will silently dangle — and consumer-tracked config is the artifact most likely to outlive the plugin install.
3. Keep a URL but pin to a tag/release ref. Fixes the main-rot half only: still writes org/repo into consumer files and adds a tag-maintenance chore to every contract release. Worst of both.

Scope note: this decision covers only the consumer-write path. The same raw URLs inside the plugin's own reference files are the publisher self-referencing within its own artifacts and stay; the runtime-resolved raw-URL case is #432's separate, harder question — don't conflate them.

Related.

• verification: consumer override seams gestured ("when the project documents…") but no declared location exists #423 — if its recommended option lands, the same .claude/ecosystems/*.yaml files gain verification keys (and discovery: ecosystem-discovery table is a closed set with no consumer-extension seam #408's recommended Option A adds discovery keys), raising the file's consumer footprint — softening the header before more consumers materialize these files is the cheap moment.
• discovery: ecosystem-discovery table is a closed set with no consumer-extension seam #408 / verification: .NET/Blazor globs shipped as "portable defaults" — silent-skip for non-.NET consumers #421 — family members whose recommended direction routes more config through these same consumer files.
• session-flow: topic-docs placement contract resolved via hardcoded raw.githubusercontent URL instead of bundled copy #432 — sibling: a raw.githubusercontent URL actually resolved at runtime; separate decision.

[kyle-sexton]

Operator decision carrier (2026-07-19, decision-session; relayed). Decided by the #432 batch-1 acceptance: the topic-docs contract is bundled via the sync-script pattern, and consumer-file headers cite the bundled contract name + version instead of the org/repo/branch URL — which is exactly this issue's fix. Implement together with #432. Re-intake: removing needs-human, adding priority: needs-triage.