test(docs): validate markdown link anchors

[kiranmagic7]

Summary

• extend the docs coverage check to validate Markdown fragment anchors, not just linked file paths
• support same-page and cross-page anchors, including GitHub-style duplicate heading suffixes
• keep existing generated command and feature-doc coverage unchanged

Verification

• make docs-check
• node scripts/check-docs-coverage.mjs
• git diff --check

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed June 15, 2026, 1:34 AM ET / 05:34 UTC.

Summary
The PR updates the docs coverage script to validate same-page and cross-page Markdown fragment anchors and wires a focused Node regression test into make docs-check.

Reproducibility: not applicable. this is a docs tooling PR rather than a reported runtime bug. Source inspection confirms current main does not validate Markdown fragments in scripts/check-docs-coverage.mjs.

Review metrics: 1 noteworthy metric.

• Docs validation surface: 3 files changed, +202/-46. The PR changes a CI-invoked docs validation path, its Makefile hook, and one focused Node test without touching runtime product code.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🦪 silver shellfish
Patch quality: 🐚 platinum hermit
Result: blocked until stronger real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P1] Add redacted terminal output or a terminal screenshot showing scripts/check-docs-coverage.mjs failing on a deliberately broken Markdown fragment and passing the current valid docs set on the latest head.

Proof guidance:

• [P1] Needs stronger real behavior proof before merge: The posted terminal output shows passing checks for an earlier head but not the latest head or a deliberately broken Markdown fragment failure; add redacted terminal output, a terminal screenshot, copied live output, or logs for that failure path, then update the PR body to trigger re-review or ask a maintainer to comment @clawsweeper re-review.

Risk before merge

• [P1] The posted terminal proof predates the latest head and does not show the checker rejecting a deliberately broken Markdown fragment, so the central failure mode remains unproven before merge.

Maintainer options:

1. Decide the mitigation before merge
   Land the narrow docs-check anchor validator after proof shows both a broken fragment being rejected and the current valid docs set passing on the latest head.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P1] No repair job is queued because the remaining blocker is contributor proof from a real setup, not a code change ClawSweeper can supply.

Security
Cleared: The diff is limited to local docs validation code, a Makefile test hook, and a Node test, with no new dependencies, permissions, secrets handling, or external code download path.

Review details

Best possible solution:

Land the narrow docs-check anchor validator after proof shows both a broken fragment being rejected and the current valid docs set passing on the latest head.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a docs tooling PR rather than a reported runtime bug. Source inspection confirms current main does not validate Markdown fragments in scripts/check-docs-coverage.mjs.

Is this the best way to solve the issue?

Yes, pending proof: extending the existing docs coverage script and adding focused Node regression coverage is a narrow maintainable path. The safer merge posture is to require real command output for the broken-anchor failure path on the latest head.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 23b847ca53cf.

Label changes

Label justifications:

• P3: This is a low-risk docs tooling improvement with limited blast radius and no runtime product impact.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The posted terminal output shows passing checks for an earlier head but not the latest head or a deliberately broken Markdown fragment failure; add redacted terminal output, a terminal screenshot, copied live output, or logs for that failure path, then update the PR body to trigger re-review or ask a maintainer to comment @clawsweeper re-review.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its PR review guidance was applied by inspecting the PR without switching branches or editing files. (AGENTS.md:1, 23b847ca53cf)
• Current main coverage gap: Current main strips fragments when checking Markdown targets and skips hash-only same-page links, so source-level Markdown anchor validation is not already implemented. (scripts/check-docs-coverage.mjs:110, 23b847ca53cf)
• PR head implementation: The PR head exports checkMarkdownLinks, decodes target paths and anchors, resolves same-page fragments to the current Markdown file, and checks anchors against parsed headings. (scripts/check-docs-coverage.mjs:124, ae43ad945445)
• Regression coverage: The added Node test covers fenced-code headings, GitHub-style duplicate slugs, encoded Unicode anchors, and one broken cross-page anchor result. (scripts/check-docs-coverage.test.mjs:9, ae43ad945445)
• Proof comment inspected: The contributor posted terminal output for an earlier head showing the test and valid docs scan passing, but not the latest slug update or a deliberate broken-fragment failure path. (ca4778c70c89)
• Feature history: Blame and history show the current docs coverage checker, docs-site link validator, and docs-check Makefile target were introduced in the v0.27.0 release preparation commit. (scripts/check-docs-coverage.mjs:110, 274a2a61da98)

Likely related people:

• steipete: Blame and history show this handle introduced the current docs coverage checker, rendered docs-site link validator, and docs-check Makefile target, and also authored the latest slug-matching commit on this PR. (role: recent area contributor; confidence: high; commits: 274a2a61da98, ae43ad945445; files: scripts/check-docs-coverage.mjs, scripts/build-docs-site.mjs, Makefile)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[kiranmagic7]

Follow-up pushed in ca4778c7 to address the fenced-code anchor issue.

What changed:

• headingAnchors() now tracks Markdown fenced code blocks and ignores heading-looking lines inside them.
• Added scripts/check-docs-coverage.test.mjs to lock the regression.
• make docs-check now runs the regression test before the docs coverage scan.

Local proof:

$ node --test scripts/check-docs-coverage.test.mjs
✔ headingAnchors ignores headings inside fenced code blocks (2.323125ms)
ℹ tests 1
ℹ suites 0
ℹ pass 1
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 122.230209

$ node scripts/check-docs-coverage.mjs
docs coverage ok: 646 command pages, 23 feature pages

$ make docs-check
generated 646 command pages in docs/commands
built docs site: dist/docs-site
✔ headingAnchors ignores headings inside fenced code blocks (2.282792ms)
ℹ tests 1
ℹ suites 0
ℹ pass 1
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 119.402792
docs coverage ok: 646 command pages, 23 feature pages

$ git diff --check
# no output

[kiranmagic7]

Latest-head proof for ae43ad94:

Broken-fragment failure path:

$ node scripts/check-docs-coverage.mjs
broken docs link: docs/__proof-broken-anchor.md -> quickstart.md#definitely-missing-proof-anchor
# exit 1, with the temporary proof file present

After removing the temporary proof file, the valid docs set passes:

$ node --test scripts/check-docs-coverage.test.mjs
✔ headingAnchors ignores headings inside fenced code blocks
✔ headingAnchors follows GitHub-style heading slugs
✔ checkMarkdownLinks accepts encoded Unicode anchors
ℹ tests 3
ℹ pass 3
ℹ fail 0

$ node scripts/check-docs-coverage.mjs
docs coverage ok: 646 command pages, 23 feature pages

$ make docs-check
generated 646 command pages in docs/commands
built docs site: dist/docs-site
✔ headingAnchors ignores headings inside fenced code blocks
✔ headingAnchors follows GitHub-style heading slugs
✔ checkMarkdownLinks accepts encoded Unicode anchors
ℹ tests 3
ℹ pass 3
ℹ fail 0
docs coverage ok: 646 command pages, 23 feature pages

$ git diff --check
# no output

$ git status --short --branch
## kiran/docs-link-anchors...kiranmagic7/kiran/docs-link-anchors

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27526512773
• Updated: 2026-06-15T05:49:12.172Z