Skip to content

docs: fix the dead links the online link check reports - #15477

Merged
kyle-sexton merged 8 commits into
mainfrom
docs/fix-online-dead-links
Nov 12, 2026
Merged

kyle-sexton merged 8 commits into
mainfrom
docs/fix-online-dead-links

Conversation

@kyle-sexton

@kyle-sexton kyle-sexton commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

No related issue: owner decision Q14 (failing workflows). The owner decided to investigate and fix each failing scheduled workflow; this PR covers the online link check, which has failed every run.

Summary

Run 42809150911 of the online link check reported 63 dead-link locations. 40 are eval-case test data, which melodic-software/standards#990 excludes from the check. This PR fixes the other 23 in this repository's own content. The bot-filed dead-link rollup (issue 15082) closes itself once the link check runs clean.

Fix

  • Renamed anchors on code.claude.com and platform.claude.com, each replaced with the id the page serves today (read from the page HTML).
  • Section anchors the target renders only with JavaScript (staticcheck.dev, Chrome DevTools Protocol, Apple HIG) are kept, as skill pointers require, and get exact .lycheeignore entries; the npm npx pointer moves to the versioned page, which serves its anchor.
  • Moved pages: Bun's bytecode docs (now bun.com/docs/bundler#bytecode); the Fable 5.1 refusals pointer in audit-instructions/reference/criteria.md now points at the refusals and fallback page, which lists Fable 5.1 and the reasoning_extraction category.
  • Gone targets: a deleted x.com reply is cited as text; an expired Actions run link is unlinked; the removed resolve-conflicts skill is linked at its last commit.
  • The acme/skills example in absorb-upstream's SKILL.md is now a code span; the record template keeps its link, and its unfilled placeholder URL gets an exact .lycheeignore entry.
  • A refine-lane commit (38e48ad) rewords two prose lines in color.md and invocation-probes.md; meaning unchanged.
  • Two live pages that refuse the runner get exact .lycheeignore entries with dated reasons.
  • maintenance-file-dead-links.yml triggers on both the current and the renamed workflow name, so standards#990's rename does not disconnect it.

Done when

  • Every non-eval dead link in run 42809150911's artifact is fixed or carries an exact, reasoned .lycheeignore entry.
  • maintenance-file-dead-links.yml triggers on the link check under its renamed name.
  • A dispatched online link-check run on main, after the standards sync that carries standards#990, concludes success.

Verification

  • lychee --config lychee.toml over every changed markdown file: 1152 links, 0 errors.
  • The same run with --exclude-file .lycheeignore over docs/standards/design-for-change.md and docs/cloud-sessions.md: 0 errors.
  • scripts/check-changelog-fragments.sh --check-required origin/main and --check: pass. scripts/check-affected.sh: 14 passed, 2 skipped.
  • actionlint on maintenance-file-dead-links.yml: clean.
  • After merge and the standards sync, a dispatched run of the link check confirms the result.

Related

🤖 Generated with Claude Code

https://claude.ai/code/session_01VQb9Q2ceZLXhTR4d1vkTCe

kyle-sexton and others added 3 commits November 11, 2026 19:13
The weekly online link check has failed every run; run 42809150911
listed 63 dead-link locations. 40 sit in eval cases, which the
standards caller now skips (melodic-software/standards#990). This fixes
the rest: renamed anchors on code.claude.com and platform.claude.com,
fragments only JavaScript renders (staticcheck, Chrome DevTools, Apple
HIG, unversioned npm docs), moved Bun and refusals pages, a deleted x.com
reply, an expired run link, a removed skill linked at its last commit,
and placeholder URLs moved into code spans. Two live pages that refuse
the runner get exact .lycheeignore entries.

maintenance-file-dead-links.yml listens for the link check under both
its current and its renamed name, so the rename in standards#990 does
not disconnect it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VQb9Q2ceZLXhTR4d1vkTCe
@kyle-sexton
kyle-sexton marked this pull request as ready for review November 12, 2026 00:19
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

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

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-12T01:03:08.292274Z dd05984 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.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 83b5658ce0

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

melodic-automation-lanes Bot and others added 3 commits November 12, 2026 00:42
Lane-Activity: pr-refine/fix-docs
A skill pointer must name its section
(.claude/rules/skill-bodies-state-current-rules.md), so the staticcheck,
Chrome DevTools Protocol and Apple HIG anchors return. lychee reads the
served HTML, where those pages carry no heading ids, so each exact URL
gets a .lycheeignore entry with its reason.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VQb9Q2ceZLXhTR4d1vkTCe
@kyle-sexton
kyle-sexton marked this pull request as draft November 12, 2026 01:01
@kyle-sexton
kyle-sexton marked this pull request as ready for review November 12, 2026 01:01
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

claude-security-review reviewed ad06905d283d1f5b84914c5f879b5460a1b23450: read 33 of 33 changed file(s); 0 finding(s), 0 as inline comments.

Security review: PR #15477, head ad06905

No security issues found. I read every hunk in the full diff. That covers 21 distinct file changes, plus the 12 changeset fragments listed in identical.txt. Those fragments are byte-identical bump: none changelog entries under .changes/<plugin>/, and none of their paths changes what the content does. This review was blocking only, because this lane already reviewed head dd05984f.

critical-findings: 0

What I checked

  • .github/workflows/maintenance-file-dead-links.yml (trusted path). I read the whole change and what it gates. The only functional change adds the renamed workflow Maintenance Check Links Online to workflow_run.workflows (L151 of the diff; file L41), next to the existing name. It does not widen what reaches the workflow:
    • branches: [main] is unchanged.
    • The job's if: still requires the triggering run's head_branch == 'main' and head_repository.full_name == github.repository. A forked PR's run under either name, including one whose branch is named main, is still refused.
    • Permissions, artifact validation and expression handling are unchanged. The edit touches only the trigger list and a header comment.
  • .lycheeignore: six new exact entries anchored with ^…$, each with a dated reason. They only affect link checking and gate nothing security-related.
  • Docs, skill, agent and CHANGELOG edits: these are anchor renames, moved targets, an expired run link and a deleted x.com reply turned into plain text, a link to the removed resolve-conflicts skill pinned to a commit SHA, an example URL turned into a code span, and two rewordings in color.md and invocation-probes.md that keep the same meaning.
    • Instruction-surface lens: no edit deletes, narrows or softens a standing rule. The audit-instructions/reference/criteria.md change only moves the pointer behind an existing model widening; the rule is unchanged. Since nothing was removed, I did not need to consult the protected-class register.
  • Plugin manifests: none changed.
  • Trust controls (trusted-trigger check, lane token, kill switch, token broker, merge holds, other .github/actions/): none touched.

Earlier threads and findings

  • Settled threads (demo-video anchors, the record-template link, the stale code-tidying and playwright fragments): all three are marked no lines changed since resolution, and this review raises none of them again.
  • Prior findings: the only entry is this lane's earlier clean summary. It had no findings, so nothing carries forward.

Notes

  • I found no embedded instructions in the PR context or the settled-threads file.
  • No change can cause a charge or spend extra credits, so there is no hold.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

claude-review: 2 inline finding(s) on dd05984fa5deaf7f099dfc12057b284ee7cfdf36; the summary is in this lane's pull request comment.

claude-lane: claude-review

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

claude-review reviewed ad06905d283d1f5b84914c5f879b5460a1b23450: read 33 of 33 changed file(s); 0 finding(s), 0 as inline comments.

Code review: docs: fix the dead links the online link check reports

Blocking only. This lane already reviewed an earlier head (dd05984f), so this round reports only blocking findings and drops advisory ones. I found no blocking finding, so findings: 0.

What I read. I read every hunk of the 33 changed files. The 12 .changes/* fragments are identical (bump: none, same text), so I read the first and skipped its 11 copies, which gives 22 files read. None of the copies sits at a path that changes what its content does.

Earlier findings

  • Record template link form: resolved by an owner decision. The template change was reverted and plugins/knowledge/skills/absorb-upstream/templates/record.md is no longer in the diff. The unfilled placeholder is covered by an exact .lycheeignore entry instead (.lycheeignore#L107).
  • Stale fragments: resolved by an owner decision. The code-tidying and playwright fragments are no longer in the diff.
  • JS-rendered anchors: the settled thread (lines changed since resolution: no) stays settled.

Checked

  • maintenance-file-dead-links.yml: workflow_run.workflows now lists both the old and the renamed link-check name. Nothing else in the file checks workflow_run.name or .path, so the second name cannot be rejected later in the run. The header comment says when to drop the old name.
  • .lycheeignore: every new entry is an exact ^…$ pattern with a dated reason, and each targets a URL this PR or the base cites.
  • absorb-upstream/SKILL.md: the example invocation is now a code span, so lychee no longer extracts acme/skills as a link. The argument text itself is unchanged.
  • audit-instructions/reference/criteria.md: the pointer moves to the refusals and fallback page and its As of date moves to 2026-11-11, with the recheck trigger unchanged.
  • source-control/CHANGELOG.md: the link to the deleted resolve-conflicts skill is now pinned to a commit SHA instead of main.
  • The prose rewording in color.md and invocation-probes.md keeps the original meaning. The PR summary now mentions it.

Not verified. I had no network access, so I could not check that the new anchor ids are live. That covers #git-hub-mcp-and-session-resources, #check-your-setup-with-/doctor, #what%E2%80%99s-available-in-cloud-sessions, #refusal-response, #change-effort-mid-conversation-beta, #prompt-md-fields, #supported-frontmatter-fields, #subagent-auto-compact-window, #tag-plugin-releases-for-version-resolution and bun.com/docs/bundler#bytecode. The "lychee: 0 errors" result in the PR body is also the author's claim, not something I ran.

Other notes

  • No plugin manifest changed, so there are no manifest lines. Every fragment is bump: none, which fits a docs-only change.
  • Closing issue: the PR closes no issue (owner decision Q14), so there are no acceptance criteria to check. Its "Done when" items 1 and 2 are met by the diff as far as I can tell from reading it. Item 3 (a green dispatched run after the standards sync) can only be checked after merge.
  • The PR body, the settled-threads file and the prior-findings file contain no embedded instructions aimed at this lane.
  • Spend: none beyond this review run.

@github-actions

Copy link
Copy Markdown
Contributor

The pr-verify verifier failed head dd05984fa5deaf7f099dfc12057b284ee7cfdf36. What it wrote, as data:

Summary: I can't judge PR #15477 against a spec because it has none. It links only issue #15082,
  through a `Refs:` line. That issue was opened by the github-actions bot, and spec-text.json gives
  it a `body` of null with no trusted comments. The PR body is context, not a requirement, so it
  can't take the issue's place. The diff itself looks sound: I read all four parts in full. It fixes
  dead-link anchors and moved pages, turns placeholder URLs into code spans, and adds exact, dated
  `.lycheeignore` entries. In `maintenance-file-dead-links.yml` it only adds the renamed workflow
  name to the `workflow_run` trigger, which changes neither permissions nor guards. Every
  pr-require-checks job passed on the head, including test-bash 0-3, lint-repo and check-skills (run
  43131570568). Nothing touches the takeover set, credentials or settings, there are no binary
  files, and nothing tries to steer the reviewer. The PR also makes wording edits that are not about
  links: `plugins/skill-quality/reference/invocation-probes.md:179` and
  `plugins/user-interface/reference/types/web/color.md:120,161`. These are minor and not part of the
  issue, so a reviewer should know about them.
- PR body: issue #15082 (named in `Refs: #15082`) has no trusted spec text. It was opened by the
  github-actions bot and its body is null in spec-text.json. Link an issue a trusted person wrote
  that asks for the online link-check fix (Q14), with done-when items, or have a trusted person
  write #15082's body. Then re-run verification.

This pull request leaves the merge queue, and ci-status holds it out while it carries pr-verify-failed. A pr-verify pass removes the label, at a new commit or at this same head: once a trusted person edits the body, and only trusted people have edited it since the fail, this head is judged again, so a fail on the body or the issues it links needs only the body fixed, no new commit.

@github-actions github-actions Bot added the pr-verify-failed pr-verify failed this head; a pass at a new commit, or after a trusted body edit, removes it. label Nov 12, 2026
kyle-sexton and others added 2 commits November 11, 2026 20:48
The absorb-upstream record template goes back to a markdown link, so
filled records keep the link form the existing records use; its unfilled
placeholder URL gets an exact .lycheeignore entry. The code-tidying and
playwright fragments go: since the anchors were restored, this branch no
longer changes those plugins.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VQb9Q2ceZLXhTR4d1vkTCe
@kyle-sexton
kyle-sexton added this pull request to the merge queue Nov 12, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Nov 12, 2026
@github-actions github-actions Bot removed the pr-verify-failed pr-verify failed this head; a pass at a new commit, or after a trusted body edit, removes it. label Nov 12, 2026
@kyle-sexton
kyle-sexton added this pull request to the merge queue Nov 12, 2026
Merged via the queue into main with commit 7fa0dc3 Nov 12, 2026
89 of 91 checks passed
@kyle-sexton
kyle-sexton deleted the docs/fix-online-dead-links branch November 12, 2026 03:02
@github-actions github-actions Bot added the merge-path: owner-agent Post-merge accounting record (README.md, Merge paths) label Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-path: owner-agent Post-merge accounting record (README.md, Merge paths)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant