Repair nine dangling markdown anchors - #78
Merged
Merged
Conversation
One broken link was known -- `windows-waitable-queues`' design notes pointed at a workspace DESIGN-NOTES section explaining its own name, and that section has never been on `main`. Sweeping every anchored markdown link in the repository rather than fixing the reported one found **nine** broken across three files, with three distinct causes needing three distinct fixes. **Seven: heading slugs that do not match the ids linked to.** `windows-file-watcher-example-test-harness`' DESIGN-NOTES links `#d-1` .. `#d-7` into its DESIGN-RATIONALE, whose headings read `## D-1: an example, not a framework` and therefore slug to `#d-1-an-example-not-a-framework`. Fixed by giving those headings explicit `<a id="d-n">` anchors -- the convention already used in the DESIGN-NOTES that link to them, and stable against the heading text being reworded later, which is exactly what would break them again. **One: the waitable-queues naming decision, which is not on `main`.** The full record is 88 lines and lives on a feature branch. Rather than link to it or delete the pointer, the crate's notes now state the substance -- why no `-sys` suffix, why plural -- and cite the README's crate-naming section, which does exist here. A reader gets the answer instead of a 404. **One: a Tier-3 design session citing a section that never existed.** The 2026-08-30 session linked `#the-value-is-existence-not-cleverness`, which is not in any DESIGN-NOTES on any branch. The sentence around it already states the principle in full, so the link is dropped and annotated in brackets rather than the session being rewritten -- dated records are not edited to look like they were always right. Two further findings, deliberately not changed: - `crates/windows-ioring-sys/PLANS.md` links `COMPLETED-PLANS.md`, which does not exist. The prose says "once there are any", so it is a deliberate forward reference rather than an oversight. Left as-is; noted so the next sweep does not re-litigate it. - The remaining hits were inside inline-code examples, where a checker matching link syntax cannot tell an illustration from a link. A limitation of the sweep, not defects. After: 273 anchored links across 130 markdown files, zero broken. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
Changes are isolated to documentation/link-targeting and the updated anchors/links resolve against existing on-branch targets.
Pull request overview
Repairs nine dangling markdown anchors across the repo by making anchor targets stable (explicit <a id="..."> where appropriate) and removing or inlining references that pointed to content not present on main.
Changes:
- Add explicit
<a id="d-n">anchors towindows-file-watcher-example-test-harnessTier-2 decision headings so existing#d-nlinks resolve. - Replace a
windows-waitable-queueslink to a non-mainworkspace decision with an on-mainsummary plus a pointer to the rootREADME.md#crate-naming. - Remove a design-session link to a nonexistent anchor and annotate the removal inline to preserve the session record without leaving a dangling link.
File summaries
| File | Description |
|---|---|
| design-sessions/DESIGN-SESSION-2026-08-30-numa-sharded-io-execution-domains.md | Drops an unresolvable anchor link and leaves an inline bracketed note explaining why. |
| crates/windows-waitable-queues/DESIGN-NOTES.md | Replaces a link to a non-main decision section with an on-main summary and a valid pointer to README.md#crate-naming. |
| crates/windows-file-watcher-example-test-harness/DESIGN-RATIONALE.md | Adds explicit d-1..d-7 anchors to match existing inbound #d-n links from Tier-1 notes. |
Review details
- Files reviewed: 3/3 changed files
- Comments generated: 0
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
MikeGrier
pushed a commit
that referenced
this pull request
Sep 7, 2026
Brings in everything peeled and reviewed since the last merge: the namespace-request tests (#74), the Unicode terminology sweep (#75), the security last-error correction (#76), the flush-barrier instruments (#77), and the dangling-anchor repairs (#78). Two conflicts, both in files this branch originated and main has since improved through review. Took main's side in every hunk, which is the whole point of the peel-and-review cycle -- the branch holds the drafts, main holds what survived: path/tests.rs the branch still measured path lengths in bytes and scalars; main's version measures UTF-16 units, guards the helper against an underflowing length, and adds the case that separates the units security/tests.rs the branch still asserted a non-zero last-error from `IsValidSecurityDescriptor`, which Windows does not document as setting it; main's version compares the typed accessor against the source chain instead Verified beyond the conflicts: - ci.yml auto-merged with no conflict; enumerated its job keys -- 20, no duplicates. An earlier merge on this branch produced a duplicate job exactly this way, and it is invisible to conflict markers. - No conflict markers anywhere in the tree. - cargo check --all-targets clean. - cargo test --workspace --all-features: 3000 passed, 0 failed, 24 ignored. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The dangling link reported on #74 was still on
main. Rather than fix the one site, I swept every anchored markdown link in the repository -- nine were broken across three files, with three distinct causes needing three distinct fixes.1. Seven: heading slugs that do not match the linked ids
windows-file-watcher-example-test-harness' DESIGN-NOTES links#d-1..#d-7into its DESIGN-RATIONALE, whose headings read:So every one of the seven missed. Fixed by giving those headings explicit
<a id="d-n">anchors -- the convention the linking DESIGN-NOTES already uses, and stable against the heading text being reworded, which is exactly what would break them again.2. One: the reported link -- a decision that is not on
mainwindows-waitable-queues' notes pointed at a workspace DESIGN-NOTES section explaining its own name. That section is 88 lines and lives only onmikegrier/deferred-namespace-ops.Rather than link to it or delete the pointer, the crate's notes now state the substance -- why no
-syssuffix, why plural -- and cite the README's#crate-namingsection, which does exist here. A reader gets the answer instead of a 404.3. One: a Tier-3 session citing a section that never existed anywhere
The 2026-08-30 design session linked
#the-value-is-existence-not-cleverness, which is in no DESIGN-NOTES on any branch. The surrounding sentence already states the principle in full, so the link is dropped and annotated in brackets rather than the session being rewritten -- dated records should not be edited to look like they were always right.Deliberately not changed
crates/windows-ioring-sys/PLANS.mdlinksCOMPLETED-PLANS.md, which does not exist. The prose says "once there are any", so it is a deliberate forward reference rather than an oversight. Left as-is and recorded here so the next sweep does not re-litigate it.Verification
273 anchored links across 130 markdown files, zero broken -- up from 9 broken before. Every target checked for both an explicit
<a id>and the GitHub-generated heading slug, resolved against each link's own directory (relative paths in this repo legitimately target two different DESIGN-NOTES files, and a checker that assumes one manufactures false positives).Encoding check clean, all three files 7-bit ASCII. Typed
docs, so no release.