session-flow: topic-docs placement contract resolved via hardcoded raw.githubusercontent URL instead of bundled copy

[kyle-sexton]

Plugin: session-flow · Categories: hardcoded repo coupling (1), missing externalization (2)
Source: work-readiness sweep (read-only audit vs docs/PLUGIN-PHILOSOPHY.md + docs/MIGRATION-PLAYBOOK.md)

Findings

• plugins/session-flow/reference/topic-docs.md:7-8 — https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/topic-docs/README.md
• reference/topic-docs.md:32-38 — "The contract owns both … apply its 'Resolution order' and 'Runtime guards' sections as written"
• plugins/session-flow/CHANGELOG.md:3-11 — 0.10.1 deliberately removed the local restatement of the resolution order + runtime guards

Why it breaks agnosticism

An installed plugin cannot reach docs/conventions/topic-docs/ (not bundled under ${CLAUDE_PLUGIN_ROOT}), so authoritative placement resolution depends on fetching an org/repo/main-branch-coupled URL at runtime — coupling runtime behavior to the publisher's repo name, the branch, and the path staying put, plus a network dependency. Cuts against PLUGIN-PHILOSOPHY ("runtime behavior must not depend on … repository names") and the cache-isolation rule. Mitigation: handoff/SKILL.md:29-37 and context/structure.md:110-166 still restate the load-bearing essentials, so the common path works offline; the exposure is the "apply the contract as written" instruction leaning on the external fetch.

Related shape: toolchain header propagation (#410) — both stem from how the fleet cites the convention SSOT; fix pattern should be decided once.

Fix direction

Bundle the load-bearing contract subset (resolution order + runtime guards) inside the plugin via ${CLAUDE_PLUGIN_ROOT}, synced from upstream through the marketplace's own sync path, and point the binding doc at the bundled copy. If the URL stays as provenance, pin to a tag/commit rather than main and label it a provenance link, not a runtime dependency.

[kyle-sexton]

This was generated by AI during triage.

Triage → needs-human. Fleet-wide decision: how to cite the convention SSOT from an installed plugin. The fix is a choice — (a) bundle the load-bearing contract subset under ${CLAUDE_PLUGIN_ROOT} via the marketplace's own sync path and point the binding doc at the bundled copy, or (b) keep the URL as provenance but pin to a tag/commit (not main) and label it non-runtime. Same shape as toolchain header propagation (#410) — the issue explicitly says the fix pattern should be decided once for both. Involves the sync mechanism. Priority: high.

[kyle-sexton]

Decision brief (2-minute read)

Problem. Installed plugins run from an isolated cache and cannot reach docs/conventions/topic-docs/README.md, so session-flow's binding delegates its authoritative resolution-order and runtime-guard behavior to a runtime fetch of an org/repo/main-coupled raw.githubusercontent.com URL. That couples runtime behavior to the publisher's repo name, branch, and path stability, and adds a network dependency — against PLUGIN-PHILOSOPHY's repo-agnosticism rule.

Today. plugins/session-flow/reference/topic-docs.md:7-8 cites https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/conventions/topic-docs/README.md, and lines 32-38 say to "apply its 'Resolution order' and 'Runtime guards' sections as written" — the local restatement was deliberately removed in 0.10.1 (plugins/session-flow/CHANGELOG.md, fleet conformance wave / single-home rule). Not session-flow-specific: the same URL appears in the reference/topic-docs.md binding of 8 implementer plugins (session-flow, discovery, planning, implementation, verification, review, work-items, toolchain), plus reference/artifact-protocol.md copies and toolchain's ecosystem YAML headers (#410). Mitigation already in place: skills/handoff/SKILL.md:28-37 restates the load-bearing essentials, so the common path works offline; the exposure is the "apply as written" delegation. Directly relevant precedent: this repo already runs an automated bundle-and-sync pipeline for another convention — scripts/sync-standards-contract.sh copies docs/conventions/standards/README.md into plugins/*/reference/standards-contract.md, with CI enforcing byte-identical copies (--check) and version-bump discipline (--check-bump: plugin manifest bump + contract version bump + new CHANGELOG entry) in .github/workflows/ci.yml:212-219.

Options.

1. RECOMMENDED — Bundle the full contract via the existing sync-script pattern. Add scripts/sync-topic-docs-contract.sh mirroring sync-standards-contract.sh: source docs/conventions/topic-docs/README.md, copies at plugins/<name>/reference/topic-docs-contract.md (opt-in by committing an initial copy — all 8 implementers), CI --check + --check-bump. Bindings point at ${CLAUDE_PLUGIN_ROOT}/reference/topic-docs-contract.md; the raw URL is demoted to a commit/tag-pinned provenance link (or dropped — the bundled copy's version + contract CHANGELOG already carry provenance). Tradeoffs: fully offline/air-gapped-safe; zero runtime coupling to repo name/branch/path; drift is impossible by construction (CI-enforced cmp); the bump gate guarantees consumers actually receive contract changes (plugin version is the update cache key). Cost: ~380 lines duplicated into 8 plugins (cache-local, negligible) and every contract change fans out to 8 copies + 8 version bumps — already scripted and CI-tested for the standards contract. One adaptation: --check-bump for standards reads a frontmatter semver, which the topic-docs README lacks — add a topic-docs-contract: 2.0.0 frontmatter line or key the check on the contract's CHANGELOG.md (clause (c) of the existing script). Reversible: delete copies and restore the pointer. This is also the convention-compliant shape under the operator's global rule (never hand-copy upstream content; where local materialization is required, use the owner's automated sync path — the plugin cache makes materialization required here), and it resolves toolchain: publisher org/repo/branch URL propagates into consumer-tracked .claude/ecosystems/*.yaml headers #410 with the same decision: consumer-file headers cite the bundled contract name + version instead of the org/repo/main URL.

2. Bundle only the load-bearing subset (the issue's original fix direction). Extract resolution order + runtime guards into a small bundled file. Lighter per-plugin context, but a curated excerpt is a second home for contract text — it drifts exactly the way 0.10.1 was fixing unless subset extraction is itself automated, and no existing script does partial extraction (the proven mechanism is whole-file cmp). Choose only if full-contract size in context is demonstrated to be a real problem; can be layered onto option 1 later.

3. Pin-and-label only. Repoint the URL at a tag/commit and label it provenance-not-runtime, leaning on the SKILL.md restatements for the runtime path. Minimal diff, no new machinery — but "apply the contract's sections as written" still cannot execute offline/air-gapped, an org/repo rename still breaks the links (silently, once they're non-runtime), and a contract bump means hand-editing 8 pinned URLs anyway. Acceptable stopgap, not an endpoint; largely wasted motion if option 1 follows.

4. Revert 0.10.1 — restate the sections in each binding. Rejected: recreates the multi-home drift the fleet conformance wave just eliminated and violates the contract's own single-home rule.

Related.

• toolchain: publisher org/repo/branch URL propagates into consumer-tracked .claude/ecosystems/*.yaml headers #410 — toolchain: same SSOT-citation shape; the org/repo/main header string propagates into consumer-tracked files; that issue and this one explicitly share one fix pattern — option 1 answers both.
• planning: wayfind hardcodes GitHub Issues/gh as the only tracker backend, bypassing the work-item-tracker seam #416 / source-control: no read/consume-only posture — "safe" babysit tier and pull-request monitor write to GitHub autonomously #440 — checked for bearing operator answers; they cover different agnosticism categories (tracker-seam hardcoding; autonomous write posture) and carry nothing that constrains this decision.

[kyle-sexton]

Operator decision (2026-07-19, decision-session batch 1; relayed).

ACCEPTED — the brief's RECOMMENDED option verbatim: bundle the full topic-docs contract via the existing sync-script pattern (scripts/sync-topic-docs-contract.sh mirroring sync-standards-contract.sh; copies at plugins/<name>/reference/topic-docs-contract.md across the 8 implementers; CI --check + --check-bump; bindings point at ${CLAUDE_PLUGIN_ROOT}/reference/topic-docs-contract.md). The raw URL is demoted to a commit/tag-pinned provenance link or dropped. The same decision resolves #410's header-citation form: consumer-file headers cite bundled contract name + version, not the org/repo/main URL.

Re-intake: removing needs-human, adding priority: needs-triage for routing.