fix(docs): three rules in the merged setup-contract prose reach past what backs them

[kyle-sexton]

Context

Post-merge verification of #3139 (merged as ef4d53959) found three defects in the text that shipped, plus several smaller ones. All are in prose that PR added, and all are the same class that PR existed to correct: a claim or rule reaching past what backs it. Filed rather than silently corrected because the content is on main.

Verified against the merged text; every line reference is origin/main at ef4d53959.

1. The fetch prohibition's stated cause is false for half its own sanctioned set

docs/PLUGIN-PHILOSOPHY.md:22-26. The Org-agnosticism paragraph sanctions "a documentation URL" generically, then says a skill instructed to "fetch, poll, or write to it has made the publisher a runtime dependency and is not [conforming]".

Fetching code.claude.com creates no publisher runtime dependency, so the stated cause does not reach the stated rule. Live counterexample already shipped: plugins/claude-config/skills/audit/SKILL.md:167 instructs curl https://code.claude.com/docs/en/<page>.md. As written, the rule condemns a conforming practice.

Fix: scope the prohibition to publisher-owned targets — "…fetch, poll, or write to a publisher-owned file…".

Related coherence gap, worth settling in the same edit: for content an agent reads, "cited for a reader to consult" and "instructed to fetch" are not cleanly separable. plugins/architecture/reference/topic-docs.md:6 is undecidable under the rule as written.

2. The evidence-bearing bullet is unsatisfiable as worded

docs/PLUGIN-PHILOSOPHY.md:395-396 requires setup to report "the effective value it observed". The same section (:404-406) pins effective value to running-session behavior: "Verify the effective value by re-checking in a fresh session." A same-session run can only observe the stored value.

The reconciliation at :407-409 redefines what satisfies the bullet rather than fixing it, so an auditor reading the enumerated bullet alone — which is the surface other docs restate in isolation — fails every conforming setup skill.

Fix: one word. "the stored value it observed".

3. A narrowing presented as a faithful clarification

docs/MIGRATION-PLAYBOOK.md:310-312 says the hook-plugin eval skip holds "only in the case its rationale actually describes", then states that rationale as "no model-facing skill at all".

The prior text (32444dcfc:docs/MIGRATION-PLAYBOOK.md:310) said "no model-invoked skill". A setup skill sets disable-model-invocation: true and genuinely is not model-invoked — so the original rationale did cover the case the new sentence excludes. This is a substantive narrowing dressed as a clarification, which is exactly the move the surrounding doctrine tells authors not to make.

The outcome is defensible and no live case breaks (all 19 hook plugins shipping a setup skill already carry setup evals). The justification is what is wrong, and it should either argue the narrowing on its merits or restore the original term.

Non-blocking, same file family

• docs/MIGRATION-PLAYBOOK.md:1362 says "read the stored value back there" and names no location, while the paired site at :1414-1418 explicitly names the user settings.json. A reader following site 1 at project scope looks in the wrong file and misreports a failed write — the precise false-failure PLUGIN-PHILOSOPHY.md:404-406 exists to prevent. The two sites should agree.
• docs/MIGRATION-PLAYBOOK.md:1416 cites "step 3 above" from inside Reintegration's own step 1. Reintegration's local step 3 is below and is about verify-before-retiring; the intended referent is Fresh-consumer onboarding's step 3, in a different section.
• docs/PLUGIN-PHILOSOPHY.md:34 vs :37 call github.test.sh a "wider sweep" and a "narrower sweep". Both are true on different axes (token set vs file scope); neither says which.
• docs/PLUGIN-PHILOSOPHY.md:39 — "both steps of the same plugin-gate CI job". Each runs inside a distinct step (validate-plugins.sh under "Validate plugin and catalog manifests"; run-plugin-tests.sh under "Run plugin contract tests"). Substance holds; the wording does not.
• Pre-existing, now leaned on: Fresh-consumer step 3's "regardless of the enable scope" is unqualified on main, while the Reintegration sentence citing it correctly flags that record's --scope local-only provenance. Same defect class, not introduced by fix(docs): correct setup-contract drift in docs and tracked PR config #3139.
• Outside the fence: .github/workflows/pr-issue-linkage.yml's header comment still describes the gate as validating only a closing keyword and "a non-empty ## Related section". The pinned reusable requires all four sections.
• Count correction for the record: fix(docs): correct setup-contract drift in docs and tracked PR config #3139's commit message said "five plugins ship a setup skill with no apply". The real number is six — bug-report, computer-use, discipline, dometrain, education, miro, all conforming to the check-only carve-out. No shipped doc states a count, so nothing on main is wrong; the claim was in the commit message only.

Why this is worth a ticket rather than a quiet patch

#3139 shipped eight instances of this defect class across its life before merge. Six were caught by human review — one finding raised across six rounds. Two were caught only by an unbounded verification criterion telling the verifier to hunt for what no named criterion covers. None was caught by self-review, and five bounded verification passes returned PASS while one of them was live.

The generalizable finding: a verifier is bounded by its criteria, so a defect nobody thought to name survives an arbitrary number of green passes. These three were found by the unbounded criterion after the bounded ones passed. Worth keeping that criterion in the loop for doc work of this kind, and worth knowing that "verification passed" is a much weaker claim than it reads as.

Related

• fix(docs): correct setup-contract drift in docs and tracked PR config #3139 — introduced this prose (merged ef4d53959).
• fix(docs): correct the unstamped --config reconfiguration claim (#3127) #3173 — shipped part 1 into the same files; item 3's prior wording is its text.
• fix(scripts): consolidate org-agnosticism enforcement behind its stated rule #3136 — org-agnosticism enforcement consolidation; finding 1 touches the same paragraph and should be settled with it.