docs: replace restated upstream facts with pointers in docs-hygiene, mcp-tools, plugin-quality, session-flow #12695

Refs: #7292

Outcome

28 passages in 18 files state a fact an external source owns. Rewrite each as a pointer to the live upstream section, or remove it, so the next upstream change cannot leave a stale copy here. Plugins: docs-hygiene, mcp-tools, plugin-quality, session-flow.

Done when

• Every row below is fixed: the restated value is deleted, the local decision stays in this repository's own words, and the pointer goes to the exact upstream section with an as-of date and a recheck trigger, per .claude/rules/skill-bodies-state-current-rules.md. A record beside a restated value does not fix it. A row marked Remove has no local dependency on the fact.
• The PR passes check-stamps.sh --trigger-less (plugins/attribution/skills/audit/scripts/check-stamps.sh) on the files it touches.
• Each touched plugin has a changelog fragment.

Rows

docs-hygiene

• plugins/docs-hygiene/skills/audit-progressive-disclosure/SKILL.md:23-28 (r137). Pointer: https://code.claude.com/docs/en/skills#how-injected-commands-run Drop the claim about how the harness runs the pre-compute block and the dated record link; keep the decision to use separate body Bash calls and treat failures as unknown, and point at the section. Same text also at: plugins/docs-hygiene/skills/rename-references/SKILL.md:26-31; a row of its own covers it only if listed.
• plugins/docs-hygiene/skills/audit-progressive-disclosure/SKILL.md:48,54 (r139). Pointer: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#structure-longer-reference-files-with-a-table-of-contents Replace the 200-line CLAUDE.md figure and TOC line thresholds with pointers (also https://code.claude.com/docs/en/memory#write-effective-instructions for size); keep the definite-versus-awareness tiering decision.
• plugins/docs-hygiene/skills/audit-progressive-disclosure/SKILL.md:159-161,169-171 (r140). Pointer: https://code.claude.com/docs/en/memory#write-effective-instructions Drop the 200-line figure and the account of the two sources' TOC thresholds; keep the ceilings-not-targets rule, and point at memory plus the best-practices TOC section.
• plugins/docs-hygiene/skills/extract-ssot/actions/batch.md:159 (r141). Remove. Delete the parenthetical about silent overwrites and no file locking; keep the rule that a wave with shared files between candidates is not run in parallel. No fetched page documents it.
• plugins/docs-hygiene/skills/extract-ssot/context/anti-patterns.md:43 (r142). Pointer: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#avoid-deeply-nested-references Drop the description of the partial-read failure mode; keep the rule that deep reference chains are an anti-pattern here and point at the section.
• plugins/docs-hygiene/skills/rename-references/SKILL.md:26-31 (r144). Pointer: https://code.claude.com/docs/en/skills#how-injected-commands-run Drop the claim about how the harness runs the pre-compute block and the dated record link; keep the decision to use separate body Bash calls, and point at the section. Same text also at: plugins/docs-hygiene/skills/audit-progressive-disclosure/SKILL.md:24-28; a row of its own covers it only if listed.
• plugins/docs-hygiene/skills/rename-references/SKILL.md:160 (r145). Pointer: https://code.claude.com/docs/en/tools-reference#edit-tool-behavior Drop the claim that the read-before-write guard catches racing edits; keep the decision to report to the user and abort when an edit fails, and point at the section.

mcp-tools

• plugins/mcp-tools/README.md:29 (r335). Pointer: https://modelcontextprotocol.io/specification/2026-07-28/server/tools#tool Drop the claim that annotations are optional in the spec; keep the decision that a missing annotation is WARN, never FAIL, and point at the Tool data type section.
• plugins/mcp-tools/README.md:44-45 (r336). Pointer: https://code.claude.com/docs/en/sandboxing#what-runs-outside-the-sandbox Drop the parenthetical claim that a stdio server does not run in the sandbox; keep the sandbox field in the inventory and point at the section.
• plugins/mcp-tools/skills/audit-posture/SKILL.md:38-41 (r337). Pointer: https://code.claude.com/docs/en/mcp#mcp-installation-scopes Drop the claims about what ~/.claude.json and server entries hold; keep the rule to read MCP configuration only through the inventory script, and point at the scopes section.
• plugins/mcp-tools/skills/audit-posture/reference/checklist.md:55-58,62-65 (r338). Pointer: https://docs.npmjs.com/cli/commands/npx (confirm the section) Drop the claims about runner resolution at start and the registry not republishing versions; keep the decisions (floating spec is the only FAIL, versioned tarball reads exact) and point at the npx page.
• plugins/mcp-tools/skills/audit/reference/checklist.md:163-168 (r339). Pointer: https://github.com/modelcontextprotocol/python-sdk (confirm the section) Drop the per-SDK list of how _meta is attached; keep the instruction to accept each SDK's native form when auditing source, and point at each SDK's docs (python, typescript, csharp). Same text also at: plugins/mcp-tools/skills/audit/reference/server-discovery.md:70, plugins/mcp-tools/skills/audit/reference/server-discovery.md:82, plugins/mcp-tools/skills/audit/reference/server-discovery.md:94; a row of its own covers it only if listed.
• plugins/mcp-tools/skills/audit/reference/server-discovery.md:29-38 (r340). Pointer: https://modelcontextprotocol.io/specification/2026-07-28/changelog#major-changes Drop the per-SDK instructions spellings and the revision-to-message mapping; keep the decision to extract server instructions and point at the changelog and SDK docs.
• plugins/mcp-tools/skills/audit/reference/server-discovery.md:63-100 (r341). Pointer: https://github.com/modelcontextprotocol/typescript-sdk (confirm the section) Drop the SDK-specific meta-extraction behavior descriptions; keep each language's tool-marker needed for discovery and point at each SDK's docs (python, typescript, csharp).

plugin-quality

• plugins/plugin-quality/skills/audit/reference/component-types/command.md:3-6 (r385). Pointer: https://code.claude.com/docs/en/skills#how-a-skill-gets-its-command-name Drop the statement that commands and skills both produce the same slash command and what skills support; keep the 'should this be a skill?' finding and point at the section.
• plugins/plugin-quality/skills/audit/reference/component-types/config.md:27-28 (r387). Pointer: https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration Drop the keychain-backed description of sensitive; keep the rule that credential options must be marked sensitive and point at the user configuration section.
• plugins/plugin-quality/skills/audit/reference/component-types/config.md:31-33 (r388). Pointer: https://code.claude.com/docs/en/plugins/components#default-settings Drop the list of supported keys, the unknown-key behavior and the precedence claim; keep the instruction to flag unsupported keys and point at the default settings section.
• plugins/plugin-quality/skills/audit/reference/component-types/config.md:34-36 (r389). Pointer: https://code.claude.com/docs/en/plugins/components#lsp-servers Drop how invalid entries and failed servers surface; keep the check that the server binary prerequisite is documented for installers and point at the LSP servers section.
• plugins/plugin-quality/skills/audit/reference/component-types/hook.md:7 (r390). Pointer: https://code.claude.com/docs/en/hooks#matcher-patterns Drop the matcher definition in the parenthetical; keep the list of hooks.json aspects the audit inspects and point at the matcher patterns section.
• plugins/plugin-quality/skills/audit/reference/recurring-concerns.md:10-13 (r392). Pointer: https://code.claude.com/docs/en/hooks#matcher-patterns Drop the statement that hooks match on tool name and the bypass mechanics; keep the concern to check coverage of alternate tools and point at the matcher section.
• plugins/plugin-quality/skills/audit/reference/recurring-concerns.md:66-68 (r393). Pointer: https://code.claude.com/docs/en/settings#settings-files-and-who-they-affect (confirm the section) Drop the claim about .claude/ write protection and storage status; keep the question of whether an artifact must live there and the tool-agnostic placement advice, with a pointer.

session-flow

• plugins/session-flow/reference/structure.md:340-341,357-363 (r427). Pointer: https://code.claude.com/docs/en/tools-reference#task-tool-availability Drop the claims about which task tools exist, TodoWrite having no read call, and /clear destroying the task list; keep the branch-on-tool-list rule and render format, pointing at the section.
• plugins/session-flow/reference/structure.md:825-828 (r429). Pointer: https://code.claude.com/docs/en/claude-directory#application-data Drop the statement that the transcript lives at the projects glob path; keep the stat-at-write, unresolved fallback and validate behavior, and point at the transcript location in the docs.
• plugins/session-flow/skills/clean-stop/SKILL.md:93-96 (r430). Pointer: https://git-scm.com/docs/git-worktree#commands (confirm the section) Drop the claims that plain git status hides ignored files and worktree remove deletes them; keep the rule to inspect and preserve ignored content before removal, pointing at the docs.
• plugins/session-flow/skills/recommend-skills/SKILL.md:57-58 (r439). Pointer: none found; Find the Claude Code docs page and section on plugin cache location and layout; plugins-reference#plugin-caching-and-file-resolution does not exist (the page has no such section). Drop the description of the plugin cache layout; keep the decision to reuse the existing result instead of walking the cache, and point at the docs section on the cache.
• plugins/session-flow/skills/reconcile/SKILL.md:70-76 (r435). Pointer: https://code.claude.com/docs/en/sub-agents#finished-subagents-in-the-panel-and-task-list (confirm the section) Drop the claim about why a returned worker stays listed; keep the rule to check for a still-running background task before retiring it, and point at the section.
• plugins/session-flow/skills/running-retro/SKILL.md:43-46 (r437). Pointer: https://code.claude.com/docs/en/how-claude-code-works#work-with-sessions (confirm the section) Drop the lossless and survives-compaction claims about the on-disk transcript; keep that running-retro reads it with the retro parser, and point at the section.
• plugins/session-flow/skills/running-retro/SKILL.md:242-245 (r438). Pointer: https://code.claude.com/docs/en/scheduled-tasks#how-session-scoped-scheduled-tasks-run Drop the statement that a /loop cannot fire after the session ends; keep that running-retro ships no scheduler, composes with /loop, and the observer is the push counterpart.

Notes

Lines are as of 3bd42cabfe (https://github.com/melodic-software/claude-code-plugins/blob/3bd42cabfe6bdef37a05778d396869af0381bb51); locate each passage by its text if main has moved. Each rNNN is that row's number in the order of #7292's "Findings by plugin". Every row was upheld by three blind judges and survived a refutation pass, run report-only for #12072. Pointers are candidates: fetch each before writing it, and confirm the section still documents the fact.

Parent: #7292