Skip to content

docs(pipeline-crew): drop dead {#id} anchors from EXPLANATION.md, repoint HOW-TO links to GitHub auto-slugs (#3613)#3617

Merged
usirin merged 1 commit into
mainfrom
fix/explanation-md-dead-anchors
Jul 19, 2026
Merged

docs(pipeline-crew): drop dead {#id} anchors from EXPLANATION.md, repoint HOW-TO links to GitHub auto-slugs (#3613)#3617
usirin merged 1 commit into
mainfrom
fix/explanation-md-dead-anchors

Conversation

@usirin

@usirin usirin commented Jul 19, 2026

Copy link
Copy Markdown
Member

What & why

claude-plugins/pipeline-crew/EXPLANATION.md declared four section anchors with Kramdown {#id} custom-anchor syntax. GitHub's markdown renderer does not honor {#id} — it drops the token and auto-generates its own slug from the heading text — so every in-repo deep link of the form EXPLANATION.md#<custom-id> resolved the file but jumped nowhere on GitHub (silent dead fragment). Scope is doc navigation only; no code path is affected.

Changes

  • EXPLANATION.md — dropped the {#id} token from all four headings (roster law, §CP hard gate, verify-don't-relay, single-owner comms). GitHub now generates its own heading slugs.
  • HOW-TO.md — repointed the four sibling deep links (landed via PR docs(pipeline-crew): plugin How-to — add a role · configure personalization · reboot · carry a §CP PR · retire a crew #3611) to GitHub's real auto-generated slugs, computed with github-slugger (the algorithm GitHub's renderer uses), not hand-guessed:
    • #roster-law#the-roster-law--singleton-bridges-vs-a-fungible-engine (2 links)
    • #cp-gate#the-cp-hard-gate--the-engine-banks-a-human-approves-the-pipeline-enqueues
    • #verify-dont-relay#verify-dont-relay--a-claim-is-not-evidence-until-you-read-the-artifact

The fourth heading (single-owner comms) has no inbound link in the doc set, so no link update was needed for it.

Acceptance criteria

  • The four headings in EXPLANATION.md no longer carry {#id} tokens.
  • Every in-repo fragment link into those headings targets GitHub's auto-generated slug and resolves to the correct section.
  • No {#id} custom-anchor syntax remains in the pipeline-crew doc set (grep clean).

Non-control-plane crew doc surface (founder ruling: all crew surfaces are non-§CP) — ship-on-green.

Fixes #3613

…md, repoint HOW-TO links to GitHub auto-slugs (#3613)

GitHub's markdown renderer does not honor Kramdown `{#id}` custom-anchor
syntax — it drops the token and auto-generates a heading slug from the
heading text — so every in-repo deep link of the form `EXPLANATION.md#<id>`
resolved the file but jumped nowhere (silent dead fragment).

Drop the four `{#id}` tokens from EXPLANATION.md and repoint the four
sibling links in HOW-TO.md to GitHub's real auto-generated heading slugs
(computed with github-slugger, the algorithm GitHub uses). No `{#id}`
custom-anchor syntax remains in the pipeline-crew doc set. Doc navigation
only; no code path affected.

Fixes #3613

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@usirin

usirin commented Jul 19, 2026

Copy link
Copy Markdown
Member Author

review-code: PASS @ 5902c5e — merge-ready

Verified PR #3617 against the acceptance criteria of #3613, one at a time (docs-only diff: claude-plugins/pipeline-crew/{EXPLANATION,HOW-TO}.md; class-probe routed it to review-code — crew docs under claude-plugins/pipeline-crew/ are neither the skills/agents subpath nor a has-docs surface, so they ride the no-class fail-closed to review-code). All files read from head 5902c5e645be769bde62fbf3ca8a59715ed2c75c via git show "$PR_REF:<path>", never the launched checkout.

  • [PASS] The four EXPLANATION.md headings no longer carry {#id} custom-anchor tokens — headings at head render as plain ## The roster law — …, ## The §CP hard gate — …, ## Verify, don't relay — …, ## Single-owner human comms — …; grep for {# in EXPLANATION.md returns nothing.
  • [PASS] Every in-repo fragment link into those headings targets GitHub's real auto-slug and resolves. The three inbound HOW-TO.md links were checked against the auto-slug computed by the github-slugger algorithm from the current heading text: #the-roster-law--singleton-bridges-vs-a-fungible-engine (HOW-TO.md:41,158), #the-cp-hard-gate--the-engine-banks-a-human-approves-the-pipeline-enqueues (:120), #verify-dont-relay--a-claim-is-not-evidence-until-you-read-the-artifact (:130) — each an exact match (double hyphen from the em-dash gap, §/comma/apostrophe stripped, correct). The fourth heading (single-owner comms) has no inbound link in the doc set, so nothing to repoint. No stale old-id link (#roster-law/#cp-gate/#verify-dont-relay/#single-owner-comms as a standalone anchor) survives.
  • [PASS] No {#id} custom-anchor syntax remains anywhere in the pipeline-crew doc set — grep for {# across every file under claude-plugins/pipeline-crew/ at head is clean.

Run-evidence bundle: N/A — docs-only diff, no build/test surface; verified from the head files + github-slugger auto-slug computation.

Non-control-plane crew doc surface (founder ruling: all crew surfaces are non-§CP). All criteria pass. This PR is merge-ready. review-code does not mergeship-it is the authorized merge step; merging will auto-close #3613 via Fixes #3613.

@usirin
usirin added this pull request to the merge queue Jul 19, 2026
Merged via the queue into main with commit 2963387 Jul 19, 2026
39 checks passed
@usirin
usirin deleted the fix/explanation-md-dead-anchors branch July 19, 2026 17:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

EXPLANATION.md {#id} custom anchors render as dead fragments on GitHub

1 participant