Repository navigation
mcpx: docs-link guard mistakes MCP tool methods for repository paths #5211
Description
Problem
During triage of #2545 on fetched main (6aeb038a0cd64b5057912edac71d4c2744a8b5d6, 2026-11-03), the concrete stale references from that issue are already resolved: docs/catalogue/ exists (README added by merged PR #2567) and plugin/opencode/v2/ exists. However, cd pkgs/mcpx && go test ./internal/defaults/ -run TestEveryDocumentationLinkResolves still fails with 147 reported missing paths. The failures include protocol method names such as tools/call, tools/list, and tools/list_changed from docs/spec and docs/protocol; these are MCP method identifiers, not filesystem paths.
internal/defaults/links_test.go treats backticked strings as path references when pathShaped matches and the first component is a top-level directory (tools), so protocol identifiers become false positives. The exact three references named in #2545 do not appear in the current failure output.
Acceptance
- The guard distinguishes protocol identifiers such as
tools/call,tools/list, andtools/list_changedfrom repository paths. - It still catches genuine missing repository paths and resolves relative Markdown links.
go test ./internal/defaults/ -run TestEveryDocumentationLinkResolvespasses inpkgs/mcpx.
Related: #2545 (the specific dangling doc references were fixed), #2534 (main-broken umbrella).
Activity
dezren39 commentedon Nov 3, 2026
🤖 Agent note · filed from triage
repo-worker-code), OpenChamber scheduled lanec29174f1-48e0-4b13-b4ff-9b73ab67e9abTestEveryDocumentationLinkResolvesoutput includes MCP method identifiers as false missing paths after the original mcpx docs: compendium/opencode-plugin-v2 name paths that do not exist — TestEveryDocumentationLinkResolves red on main #2545 references were resolved. Evidence and acceptance are in this issue body.status/needs-triage; no repo-health task has been enqueued yet.dezren39 commentedon Nov 4, 2026
Intake review
Related: Surfaced during triage of #2545; stale references there were resolved by merged PR #2567.
Notes: Body already carries an Acceptance section (the guard must distinguish MCP protocol identifiers like tools/call, tools/list, tools/list_changed from repository paths while still catching genuine missing paths) — no body edit this pass; the section heading is '## Acceptance' rather than '## Acceptance criteria', which is why the digest flagged it. Verified still live this run: the triage evidence in the body is from fetched main 6aeb038 (2026-11-03) with
go test ./internal/defaults/ -run TestEveryDocumentationLinkResolvesfailing on 147 reported paths including the protocol identifiers; the #2545 references named in the body are already resolved by merged PR #2567, so this issue is only the guard's false-positive class. Labels were already complete (kind/bug, task/small-fix, priority/high, effort/s, app/mcpx) — this pass adds meta/enriched only. Suggested approach: exclude scheme-like/protocol method identifiers at the pathShaped gate or denylist the MCP method namespace in internal/defaults/links_test.go, with a regression case per identifier named in the body.— fleet monitor intake (protocol §5), 2026-11-03 18:12 CST run. Verified still live this run per the notes above.
dezren39 commentedon Nov 4, 2026
🤖 Agent note · picked up
pkgs/mcpx/internal/defaults/links_test.goso MCP protocol method identifiers (tools/call,tools/list,tools/list_changed) are not treated as repository paths, while genuine missing paths are still caught.TestEveryDocumentationLinkResolvespassing in CI.dezren39 commentedon Nov 4, 2026
🤖 Agent note · picked up
queue/9454-5211-docs-link-guard(commit 590efc6):protocolMethodswhole-identifier set in the docs-link guard plus an extraction-level unit test. Guard test failed with 147 method false-positives before, passes after; fullinternal/defaultspackage passes; negative control (genuine danglingtools/frobnicate,internal/nope/missing.go) still flagged.fix(mcpx): docs-link guard no longer mistakes MCP methods for paths (#…
dezren39 commentedon Nov 4, 2026
🤖 Agent note · done
protocolMethodsset) instead of mistaking them for paths; Codex P1 finding on the first head was fixed in 598aced (test now exercises every registered method with its own namespace intops, plus a same-namespace non-method control) and replied to on its thread.go test ./internal/defaults/passes on the laptop; basic CI checks SUCCESS; negative control still flags genuine dangling paths.