fix(docs): setup-contract drift — unstamped `--config` claim in three docs, no SSOT for the contract, stale PR-section config

[kyle-sexton]

Context

#3111 / #3115 corrected the "--config only applies on a fresh install" claim across 25 setup skills and the options-doc generator, and version-stamped the replacement. The claim survives one layer up, in docs/, and the campaign surfaced several adjacent contract gaps. Filed as a separate issue to keep #3115 reviewable.

1. The claim is still asserted, unstamped, in three docs

• docs/PLUGIN-PHILOSOPHY.md:262-263
• docs/MIGRATION-PLAYBOOK.md:1339,1391-1392
• docs/extensibility-contract-smoke-tests.md:21,110-111 — Test C: its stamped observation stands; the inference drawn from it propagated.

Correct and stamp each, matching the house style in plugins/claude-ops/skills/plugins/context/scope-semantics.md ("Empirically verified on Claude Code 2.1.228"). The empirical basis, verified on 2.1.240 against an already-installed plugin with a non-default value:

$ claude plugin install context-budget@melodic-software -s user --config settings_write_ask_enabled=false
  ✔ Plugin "context-budget@melodic-software" is already installed (scope: user)
  → {"options":{"settings_write_ask_enabled":false}}

Do not overclaim: the claim landed 2026-07-18 (fe28ffa70, #360) with no version stamp and CC 2.1.221 changed install-activation behaviour, so "always false" and "true when written, fixed since" are not distinguishable. The defect is the missing stamp as much as the wrong prescription.

2. The setup contract has no single source of truth

#3115 could not do "change the contract once rather than every consumer": the contract lives in docs/PLUGIN-PHILOSOPHY.md § Setup is explicit and repeatable, which was outside that PR's fence, so 25 setup skills were converged on identical wording instead. That wording now has no home to be derived from, and will drift again.

Two clauses need to land in the contract itself:

• Verify-it-landed — apply reads the effective value back after routing a reconfiguration, rather than claiming an unobserved change.
• Coverage rule — a plugin declaring userConfig ships a setup skill unless every declared option is trivial per this document's own trivial test. The unqualified form was tried and rejected: it forced a visualization setup skill whose single medium option matches the trivial definition almost word-for-word, which is the blanket ceremony this document warns against.

3. .claude/source-control.md declares the wrong PR sections

It sets pr_body_required_sections to Summary / Test plan / Related. The actually-enforced gate (melodic-software/ci-workflows/.github/workflows/pr-issue-linkage.yml, consumed by .github/workflows/pr-issue-linkage.yml) requires Summary / Fix / Verification / Related, each non-empty, plus a closing keyword. "Test plan" appears nowhere in the gate. Any author or agent trusting the tracked config writes a PR body that fails CI — observed twice in this campaign.

4. Contradiction: evals for hook-plugin skills

docs/MIGRATION-PLAYBOOK.md lists evals as an explicit skip for hook-plugin skills, while scripts/check-changed-skills.sh --require-evals hard-FAILs without them. In #3115, 9 of 13 eval sets exist only because the gate won the argument against the doc. One of the two is wrong; reconcile deliberately rather than letting the gate keep silently overriding the playbook.

5. Org-agnosticism has no single home

Enforced for autonomy in scripts/validate-plugin-contracts.mjs and for github in that plugin's own test, with no shared definition. Two enforcement sites, one unstated rule.

6. Contract accepts non-conforming plugins

dometrain and miro ship no apply action against a contract that calls it mandatory, and validate-plugin-contracts.mjs accepts them. Both deliberately keep /plugin configure for a sensitive option — which may be a legitimate exemption that the contract should name explicitly rather than tolerate silently.

Related

No linked issue.

[kyle-sexton]

Correction to this issue's provenance claim — the origin commit I cited is wrong.

This issue attributes the "--config only applies on a fresh install" claim to fe28ffa70 (2026-07-18, #360, "adopt the uniform setup contract across 17 shape-B plugins"). A fresh-context verifier working #3139 found that is where the claim spread, not where it originated, and I re-derived it independently:

$ git log -1 --format='%h %ad %s' --date=short eefcbb1a2
eefcbb1a2 2026-07-11 docs(playbook): codify extensibility contract v2.1 and record smoke tests (#81)

$ git show eefcbb1a2:docs/extensibility-contract-smoke-tests.md | grep -n 'fresh install'
21:`--config` is applied only on a fresh install (Test C), so uninstall before each run and read the
110:  flow"). It applies **only on a fresh install** — `--config` is ignored once the plugin is already

$ for rev in eefcbb1a2 fe28ffa70~1 fe28ffa70 origin/main; do
    git grep -l "fresh install" $rev -- 'plugins/*/skills/setup/SKILL.md' | wc -l; done
eefcbb1a2    0
fe28ffa70~1  9
fe28ffa70   14
origin/main 24

So the actual history is: the claim was born in docs/ at eefcbb1a2 (#81, 2026-07-11) as an inference from Test C, reached zero setup skills at that point, then propagated into setup skills — 9 already carried it before fe28ffa70, which took it to 14. It stands at 24 on main today, across 48 setup skills.

Two things follow:

1. The unstamped-claim framing gets stronger, not weaker. The claim did not start as boilerplate in a template sweep; it started as a documented inference from a real smoke test, and then propagated outward into skills over two weeks. That is precisely why fix(docs): setup-contract drift — unstamped --config claim in three docs, no SSOT for the contract, stale PR-section config #3127 item 2 — the setup contract having no single source of truth — is the load-bearing fix rather than a tidy-up. The docs were the origin.
2. Do not reuse the number 25 for feat: adopt the uniform setup contract across 17 shape-B plugins #360's scope. 25 is the scope of the correction campaign (fix(setup): unstamped --config claim prescribes a destructive reinstall across 18 setup skills #3111 / fix(plugins): correct the unstamped --config reconfiguration claim (#3111) #3115). The feat: adopt the uniform setup contract across 17 shape-B plugins #360 figure is 14 (from 9), and fe28ffa70 touches 17 setup SKILL.md files, matching its own subject line. The two numbers were conflated once already in fix(docs): correct setup-contract drift in docs and tracked PR config #3139 and caught by its verifier.

Nothing else in this issue changes — the empirical result on 2.1.240, the reset-hazard severity, and the remediation shape are unaffected.