ci: run the offline lychee link check and repoint moved doc anchors

[kyle-sexton]

No related issue: found during an org-wide lychee audit.

Summary

This repository syncs lychee.toml from standards but no CI lane ran lychee, so broken local links and anchors merged unnoticed. An online run on 2026-10-11 also found 13 links whose upstream doc anchor or target had moved.

Fix

• pr-require-checks.yml: a lychee-offline step in lint-repo (ci-workflows v0.39.8, same pin as ci-runner), fed into the job's aggregated results like the other whole-repo scanners. It excludes two test-data paths whose links are meant not to resolve: the attribution audit's golden fixtures and scripts/fixtures/hooks-lifecycle-table.md.
• Repointed 12 external links to the anchor ids their pages serve today (code.claude.com hooks, hooks-guide, costs, advisor, settings-reference, plugin loading, mods troubleshooting, marketplaces; clig.dev) and one moved local path; sandboxing#platform-and-tool-compatibility, a section upstream removed, now points at sandboxing#os-level-enforcement. As-of dates updated on every changed pointer record.
• Corrects the released permission-rule-hygiene 1.3.1 entry in place: its quote is now a code span (declared in 1.6.2).
• .lycheeignore: the host-wide claude.ai, dl.acm.org and reddit patterns are narrowed to the 10 exact URLs tracked markdown links, each group under a one-line reason verified 2026-10-11; every kept entry has a one-line reason.
• Version bumps and changelog fragments per the repository's rules.

Verification

• Offline lychee 0.24.2 with the lane's excludes: 0 errors outside the two excluded paths (fresh verifier run).
• Every new external anchor: old id absent and new id present in the fetched HTML (fresh verifier).
• actionlint, aggregator self-test, docs-only gate, changelog parity (--check, --check-bump, --check-preserved) and fragments (--check-required): exit 0.
• Linux CI on d9ef747: lychee-offline=success (15580 links, 0 errors).
• .lycheeignore narrowing: lychee --dump with the repo config, before and after, sorted and unique, is identical (6826 links). The offline dump is identical too, but it skips remote URLs, so it proves nothing about this change.

Related

Standards companion: melodic-software/standards#767 (adds hidden = true, which extends **/*.md to dot-directories; this branch was also checked under that setting with 0 new errors). Online link-check workflow: #7124. Left unfixed and listed for the owner: 23 GitHub issue-comment anchors and other JavaScript-rendered anchors (lychee false positives), bot-blocked 403s, the kitao/pyxel repository (gone), two Suno help articles in CHANGELOG history, and two Fable 5 anchors that need a content decision.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-11T14:31:55.357772Z	d9ef747	Draft marked ready

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

Claude finished @kyle-sexton's task in 1m 30s —— View job

---

Security review (/review:security-review)

• Gather context (diff, changed files, repo instructions)
• Run /review:security-review
• Post findings

Scope reviewed: the PR's own 3 commits (c4ad0b6..d9ef747), 24 files — a new lychee-offline CI step in .github/workflows/pr-require-checks.yml, and otherwise doc-only anchor/link repoints, a changelog correction, and version bumps/changelog fragments.

Findings: none.

• The new CI step (blob permalink) runs melodic-software/ci-workflows/.github/actions/lychee-offline pinned to a commit SHA, passes only static config/exclude inputs (no run: block, no interpolation of PR-controlled text into a shell command or the github context), and is explicitly offline — it reads local files only, so there's no SSRF/exfiltration surface from scanning untrusted PR content. The new lychee-offline=${{ steps.lychee.outcome }} aggregation line follows the exact pattern of the existing scanner lines and only ever carries one of GitHub's fixed step-outcome values, not attacker-influenced data. Action pinning/hardening itself is zizmor's lane, not this one.
• Checked the diff against the instruction-surface-deletion lens (docs/conventions/instruction-exception-register/README.md is present in this checkout and was consulted): nothing here removes, narrows, or softens an enforced guardrail. The permission-rule-hygiene/CHANGELOG.md edit only replaces a dead markdown link with a code span inside a historical (already-released) changelog entry's quoted text — the convention body and its enforcement are unchanged.
• The remaining changes (anchor/URL repoints, windows-surfaces.md, CHANGELOG/plugin.json version bumps, .changes/* fragments) are prose/doc-only with no logic, authz, injection, or secrets-handling surface.

No code changes made; this was a review-only pass.

[claude]

Claude finished @kyle-sexton's task in 6m 4s —— View job

---

Code review complete

• Gather context (PR diff, body, changed files)
• Understand request: run /review:code-review for this PR
• Invoke /review:code-review skill and follow its instructions
• Post inline comments for file-anchored findings
• Post summary comment with cross-file findings (if any)

Summary

Reviewed the full diff (origin/main...HEAD via gh pr diff 7064, since the shallow checkout here had no local merge base with origin/main) against this repo's CLAUDE.md → AGENTS.md and the auto-loaded .claude/rules/skill-bodies-state-current-rules.md (triggers on plugins/*/skills/**, which several changed files sit under).

This is a tightly-scoped, well-executed change: a new lychee-offline step wired into lint-repo's aggregate exactly like the other ungated whole-repo scanners (same continue-on-error, same aggregator feed, same exclude-list idiom used elsewhere in the file for typos/check-machine-paths/check-comment-markers), plus 13 anchor/target repoints with fragments and version bumps that correctly follow scripts/fragment-plugins.txt (all 7 touched plugins with fragments are listed there; developer-experience, which isn't listed, got a direct CHANGELOG.md + plugin.json bump instead). The permission-rule-hygiene 1.3.1 correction and new 1.6.2 entry match the repo's released-entry-correction pattern.

I couldn't independently verify the new anchor IDs against the live HTML (no network access from this sandbox, and WebFetch only returns markdown-converted content, not raw id attributes), so I'm treating the PR's own anchor-verification claims as author-reported and unverified by me, not confirmed.

One finding posted inline: plugins/autonomy/skills/setup/context/windows-surfaces.md:19 — the sandboxing repoint falls back to a bare page-level link (no #anchor) because the upstream section was removed. The repo's own .claude/rules/skill-bodies-state-current-rules.md explicitly calls a docs-page pointer without a section anchor defective, exempting only an upstream issue or probe citation — not a docs page whose section disappeared. Every other repoint in this PR kept a working anchor; this is the one that didn't.

No other correctness issues found in the workflow YAML, the exclude-pattern folding (consistent with established same-file idiom), or the remaining doc edits.

[github-actions]

claude-security-review has reviewed this pull request through f992fa8; a later push is reviewed from there.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d9ef747317

ℹ️ 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".

[github-actions]

claude-review has reviewed this pull request through f992fa8; a later push is reviewed from there.

[claude]

Claude finished @kyle-sexton's task in 1m 55s —— View job

---

Code review complete

• Gather context (PR diff, body, prior comments/review threads)
• Invoke /review:code-review and follow its instructions
• Post inline comments for file-anchored findings
• Post summary comment with cross-file findings (if any)

Summary

This is a re-review triggered by a new push. The lane's prior review rounds (through d9ef747) already covered the bulk of this PR — the new lychee-offline CI step, the 12 external anchor repoints, and the permission-rule-hygiene changelog correction — with no findings beyond the one inline finding both Codex and this lane raised on windows-surfaces.md.

The only PR-specific change since that review is commit 1477c1e (ci: narrow host-wide link-check excludes to the exact URLs linked), plus a clean merge of origin/main with no conflict markers. That commit directly fixes the open finding:

• windows-surfaces.md now points at sandboxing#os-level-enforcement instead of the bare page-level link. I fetched the live page and confirmed the ### OS-level enforcement heading exists and states macOS uses Seatbelt, Linux and WSL2 use bubblewrap — matching the claim in the file and satisfying .claude/rules/skill-bodies-state-current-rules.md's requirement for an anchored citation. This resolves both the Codex P1 comment and this lane's prior inline finding.
• .lycheeignore replaced the three host-wide patterns (claude.ai, dl.acm.org, reddit.com) with ten exact-URL entries, each with a one-line verified reason. I checked each new pattern against the repo's actual markdown links (claude.ai/code, claude.ai/code/routines, claude.ai/code/artifact/bfdfaef9-..., the three ACM DOIs, and the four Reddit URLs) and every one matches a real link currently in the docs — no stale or over-broad entries.

Codex's P2 comment (hidden-file traversal: lychee.toml not scanning .claude, .github, .changes without hidden = true) is already addressed in the PR's own "Related" section — it's deferred to the standards companion PR (melodic-software/standards#767), which this branch was separately checked against with 0 new errors. Not a gap in this PR.

No new findings. No inline comments posted — nothing on the changed lines of 1477c1e or the merge commit rises to this lane's bar beyond what was already fixed.

[claude]

Claude finished @kyle-sexton's task in 1m 21s —— View job

---

Security review (/review:security-review)

• Gather context (diff, changed files, repo instructions)
• Run /review:security-review
• Post findings

---

Scope: this push added one commit since the last reviewed SHA (d9ef747 → f992fa8, plus a merge of origin/main). The PR's own diff against the current merge base (git diff origin/main...HEAD) is unchanged at 25 files; the only new content is commit 1477c1e, touching .lycheeignore and plugins/autonomy/skills/setup/context/windows-surfaces.md.

Findings: none.

• .lycheeignore (blob) replaces three host-wide regexes (claude.ai, dl.acm.org, reddit.com) with ten exact, anchored URL patterns. This is lychee config consumed only by the offline link-check step reviewed on the prior push (no run:-block interpolation, no network calls from this file) — narrowing it only shrinks what the scanner ignores, so it can't introduce new risk, and the regexes are simple anchored literals with no catastrophic-backtracking shape.
• plugins/autonomy/skills/setup/context/windows-surfaces.md (blob#L16-L23) repoints the sandboxing citation from the bare page-level link to the anchored #os-level-enforcement section — this resolves the defective-pointer finding both Codex and this bot's own code-review pass raised on the prior commit (d9ef747). It's a documentation-citation fix with no executable surface.
• The .github/workflows/pr-require-checks.yml lychee-offline step itself is unchanged since the prior review on this PR (d9ef747), which found no findings; that assessment still applies.
• Re-checked the instruction-surface-deletion lens (docs/conventions/instruction-exception-register/README.md is present in this checkout): this commit only tightens exclusions (host pattern → exact URL) and strengthens a citation (page-level → anchored section). Nothing here removes, narrows, or softens an enforced guardrail.

No code changes made; this was a review-only pass.