docs: remove derivable/copied content, convert external copies to pointers, fix upstream drift

[kyle-sexton]

No linked issue

Summary

Repo-wide tri-skill audit (/docs-hygiene:audit-derivability, /discipline:recheck-against-upstream-deep, /discipline:point-dont-copy) over all 1,270 tracked markdown files, applying only the high-confidence, verification-backed subset: derivable working files whose conclusions were absorbed elsewhere are deleted, content copied from external sources is replaced with pointers to the living owners, and stale upstream restatements are corrected against docs fetched this session.

Fix

• Copied external content → pointers. docs/topics/fable-field-guide-audit/source-article.md (verbatim copy of the Anthropic "Field guide to Claude Fable 5" blog post) is now a pointer stub keeping the URL and the S1–S14 legend; its raw-capture.txt twin is deleted. A ~25-row hook-events table lifted from the official docs (session-flow retro catalog) now links to code.claude.com/docs/en/hooks; copied MCP initialize JSON shapes (testing run-e2e) now link to the MCP spec lifecycle page.
• Absorbed working files deleted (14). fable-field-guide-audit findings S2–S6/S8–S14, audit-brief.md, coverage-reconcile.md — a fresh-context verifier confirmed every conclusion survives in dispositions.md/repair-ledger.md. S1/S7 kept (cited as evidence by surviving reviews); the two surviving prose mentions of the removed file were reworded.
• Internal duplicates consolidated to their owners. work-items gh-auth-status rationale (→ providers.md), cadence table (→ add.md, which the repo already declares as its SSOT), claude-ops retention table (→ operator-setup-retention.md), shadowed-skill-renames grammar bullets (→ PLUGIN-PHILOSOPHY.md § Naming, verified superset).
• Unsourced figure removed. The "27K vs 114K / 4x" token claim (playwright, testing) is not in upstream's docs; qualitative claim kept.
• Upstream drift fixes, each verified against currently-fetched docs: Monitor allow-rules added to the permission-rule-hygiene quote (v2.1.236); install-state sweep table gains uploads/, feedback/drafts/, usage-data/ and image-cache's distinct sweep rule; DISABLE_DOCTOR_COMMAND re-hedged as unconfirmed (docs row has flip-flopped); fork-mode default-on framing (≥ v2.1.232); .NET 10 --project gotcha scoped to the opt-in MTP runner; git 2.56 worktree: includeIf marked unreleased.

Deliberate multi-copies (artifact-protocol.md ×5 plugins, #2698 inline boilerplate) were recognized and left intact. Larger judgment calls (Pattison corpus posture, the userConfig-defaults upstream change, #1419 topic graduation) are report-only, not in this diff.

Verification

• markdownlint-cli2: 0 issues across all 20 changed markdown files (re-run after merging main's config update); typos: clean.
• All introduced links/anchors resolved (#naming, #cadence-duration-table, #retention-knobs, providers.md); lychee fragment rule respected.
• Deletion set verified by a fresh-context subagent: zero inbound references repo-wide to any deleted path; contract-slice prune gate confirmed unaffected (deletions are exempt by design; the fable-field-guide-audit slug's directory survives).
• Independent fresh-context review of the full diff against seven pass/fail criteria; its one finding (two dangling prose references) fixed in the follow-up commit.

Related

Refs #1419 (docs/topics graduate-then-prune debt — surfaced by the audit, not addressed here). Refs #2698 (inline-boilerplate adjudication honored). Report-only findings, including four independent hits on the upstream userConfig-defaults change (CLAUDE_PLUGIN_OPTION_<KEY> now exported), were delivered to the repo owner outside this PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_018a2V2EdWMNPTx411FGdbes

---

Generated by Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1d5016c011

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 2m 40s —— View job

---

Code Review

• Gather context (PR diff, changed files, review criteria)
• Apply skip gate checks
• Review changed files for correctness/maintainability findings
• Check prior Codex review comments for context
• Post findings (inline + summary)

Skip gate: does not apply — PR is open, not draft, and the change has real review surface (upstream-drift corrections, deletions, pointer conversions across 35 files).

Scope reviewed: full origin/main...HEAD diff (88 insertions / 2552 deletions across 35 files), per /review:code-review's code-correctness lane (security findings are out of scope for this lane).

Prior Codex findings — both resolved in the latest commit

The two open review comments from chatgpt-codex-connector were both addressed by commit 432dd3a ("docs: address Codex review — pin MCP recipe revision, reconcile doctor-suppression status"), which landed after those comments:

1. MCP handshake recipe pinned version (non-ui.md) — now explicitly states the recipe was written against the pinned 2025-06-18 revision, links /specification/latest for the current one, and calls out that revisions after 2025-11-25 drop the initialize handshake. Confirms the drift the original comment flagged.
2. DISABLE_DOCTOR_COMMAND status reconciled (doctor-handoff.md) — item 3's title, the "Suppression channels" paragraph, and the closing summary now consistently call the variable unconfirmed; the flip-flop history (absent → present → absent) is recorded once and referenced rather than restated inconsistently.

I re-read both sections end-to-end and didn't find any remaining internal contradiction (title, body, and the two later restatements all agree now).

Independent findings

None. I checked, in addition to the above:

• Every new/rewritten internal link and anchor (PLUGIN-PHILOSOPHY.md#naming, operator-setup-retention.md#retention-knobs, add.md#cadence-duration-table, providers.md, findings/S7.md) — all resolve to real headings/files.
• Repo-wide grep for dangling references to the 14 deleted fable-field-guide-audit files and the two deleted files (audit-brief.md, coverage-reconcile.md) — none found; the one remaining fable-field-guide-audit hit (scripts/contract-slice-baseline.txt) is a directory-listing entry, and the directory still exists (S1.md, S7.md, dispositions.md, etc. survive).
• The rewritten dotnet.md, worktree-root-convention.md, and permission-rule-hygiene/README.md upstream-drift claims are self-consistent and appropriately hedged (dated, version-scoped) — I did not re-fetch upstream docs myself, so I'm not independently verifying the cited version numbers/dates, only that the prose is internally consistent and appropriately hedges what wasn't reconfirmed.
• Table/markdown structure in the touched files (surfaces.md's expanded sweep-rule table, etc.) is well-formed.

No correctness or maintainability issues found beyond what's already fixed.

[claude]

Claude finished @kyle-sexton's task in 48s —— View job

---

CI Security Review

• Gather context (PR diff, review comments, custom instructions)
• Invoke /review:security-review per custom instructions
• Post findings

Skip gate: no security-relevant surface.

This PR's diff (git diff origin/main...HEAD against 432dd3a) touches 34 files, and all of them are .md/.txt documentation — no .github/workflows/**, no scripts, no application code, no settings/permissions files. The change deletes absorbed working files, replaces copied external content (an MCP initialize JSON shape, an Anthropic blog post excerpt, a hook-events table) with links to the canonical source, and corrects stale upstream claims about Claude Code env vars and version gating.

Per this lane's skip gate, that means no deep review is warranted:

2. Change has no security-relevant surface after reading the diff

Confirmed no security issues in scope for this lane (logic flaws, auth/access-control gaps, injection surfaces, secret/token handling, or dangerous GitHub Actions patterns) — there's no code or workflow to carry them.

Two prior Codex findings on this PR (MCP spec pinning in plugins/testing/skills/run-e2e/context/non-ui.md, and the doctor-suppression status reconciliation in plugins/claude-config/skills/audit-pass/reference/doctor-handoff.md) are documentation-accuracy concerns, not security findings, and both are already addressed in the latest commit (432dd3a).

[github-actions]

Last security-reviewed head: 14904e97fbf5f8939ee56bf448d0ff3e6542fc5c. On the next push, the relevance gate compares only the commits since this SHA; delete this comment to force a full re-review.

[github-actions]

Claude has reviewed this PR 2 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[claude]

Claude finished @kyle-sexton's task in 2m 17s —— View job

---

Code review — /review:code-review

• Gather context (PR diff, review comments, custom instructions)
• Invoke /review:code-review and follow its instructions
• Post findings

No new findings.

This is a docs-only PR (53 files, all .md/.txt/plugin.json/CHANGELOG.md; no application code, workflows, or scripts). Scope per REVIEW.md: code-review lane covers correctness/design/conventions/docs; this repo carries a claude-security-review workflow so security is fully out of scope here (already handled by that lane's earlier pass).

What I checked:

• Both prior Codex findings are resolved in 432dd3a and stayed correct through the final 14904e9 bump commit:
  • plugins/testing/skills/run-e2e/context/non-ui.md now names the pinned 2025-06-18 revision explicitly, links /specification/latest, and scopes the handshake smoke test to legacy/dual-era servers (post-2025-11-25 revisions replace initialize with per-request _meta).
  • plugins/claude-config/skills/audit-pass/reference/doctor-handoff.md treats DISABLE_DOCTOR_COMMAND as unconfirmed consistently everywhere it's mentioned (title, re-check note, suppression-channels paragraph, and the closing detection-vs-prediction paragraph) — no contradictory "documented" language survives.
• Deletion set is clean. Repo-wide grep for coverage-reconcile, audit-brief.md, raw-capture.txt, and findings/S{2-6,8-14}.md turns up zero dangling references outside the two prose mentions already reworded to describe the removed working file in the past tense (disposition-review.md:188, dispositions.md:31). findings/S1.md and findings/S7.md correctly remain (still cited by codex-review.md and disposition-review.md).
• New/changed pointers resolve.
  • docs/topics/shadowed-skill-renames/PLAN.md → ../../PLUGIN-PHILOSOPHY.md#naming resolves, and the target section is a genuine superset of the deleted bullet list (verb table, audit-mutation rule, and exception list are all present, plus more).
  • plugins/claude-ops/skills/observability/context/read-routing.md → operator-setup-retention.md#retention-knobs resolves (same directory, heading exists), and the retention numbers that used to live inline match the table still in that target file.
  • plugins/work-items/skills/track/actions/recheck.md → add.md#cadence-duration-table resolves, and the cadence-to-days values match exactly what was removed.
  • plugins/work-items/skills/setup/reference/{autonomous-apply,check}.md → providers.md (same directory) both resolve, and providers.md does carry the gh auth status account-vs-repo rationale being pointed to.
• Version/changelog bookkeeping is internally consistent across all 9 touched plugins — each plugin.json version matches its CHANGELOG.md's top entry heading, and each changelog entry accurately describes that plugin's diff.

Nothing here rises to a blocking or suggestion-level finding; the diff does what its description claims and the two items an earlier reviewer already caught are verifiably fixed.
· branch: claude/repo-content-derivability-audit-qvqsiu

[claude]

Claude finished @kyle-sexton's task in 39s —— View job

---

CI Security Review

• Gather context (PR diff, review comments, custom instructions)
• Invoke /review:security-review per custom instructions
• Post findings

Skip gate: no security-relevant surface.

Re-checked the full diff at HEAD 14904e9 (git diff origin/main...HEAD, base 9f000d7) — 53 files, +154/-2561. Every file is one of:

• .md / .txt documentation (deletions of absorbed working files under docs/topics/fable-field-guide-audit/, pointer conversions, upstream-drift corrections)
• .claude-plugin/plugin.json — version-number bumps only (verified via diff, no other field changes)
• CHANGELOG.md — release-note entries only

No .github/workflows/**, no scripts, no application/tool code, no settings or permissions files are touched. Per this lane's skip gate:

Change has no security-relevant surface after reading the diff

No security findings in scope for this lane (logic flaws, auth/access-control gaps, injection surfaces, secret/token handling, dangerous GitHub Actions patterns) — there's no code or workflow to carry them.

The two prior Codex findings (MCP spec revision pinning in plugins/testing/skills/run-e2e/context/non-ui.md, doctor-suppression status reconciliation in plugins/claude-config/skills/audit-pass/reference/doctor-handoff.md) are documentation-accuracy concerns, not security findings, and were already addressed in commit 432dd3a per the author's own review replies.