Context. #14360 (NeuralLink guide) added test/playwright/unit/ai/mcp/validation/GuideToolParity.spec.mjs — it validates that the guide delegates its tool surface to OpenAPI (the guide names tools; the test asserts they resolve to real openapi.yaml operation IDs, and that the guide does not inline a catalog). That's a one-off test wired for NeuralLink.
Problem. This pattern is the mechanically-enforceable form of two bars that are currently discipline-only:
- §4 conceptual ≠ reference (a guide must delegate the tool catalog, not inline it);
- the #14327 hallucinated-command class — but for MCP tool refs (the existing
ai:lint-guides dead-ai:*-script-ref check is the npm-script analogue; this is the OpenAPI-tool analogue).
A one-off per-guide spec doesn't scale; it should be a reusable lint check across every tool-bearing guide (MemoryCore/KnowledgeBase/NeuralLink MCP-API references).
Fix (proposed). Add a guide↔OpenAPI tool-parity check to ai/scripts/lint/lint-guides.mjs: for a guide that references MCP tools, the referenced tool names must resolve to operation IDs in the relevant ai/mcp/server/*/openapi.yaml; flag any tool-ref with no matching operation (HARD — the hallucination class) and optionally an inlined catalog (WARN — Diátaxis).
Acceptance Criteria
Sequencing. Follow-up to #14354 / #14355 (the lint itself) — land after the lint's pre-commit + CI enforcement is decided (#14355 is operator-paused on that). Refs #14360, #14310. Origin: review of #14360, session e145a397.
Context. #14360 (NeuralLink guide) added
test/playwright/unit/ai/mcp/validation/GuideToolParity.spec.mjs— it validates that the guide delegates its tool surface to OpenAPI (the guide names tools; the test asserts they resolve to realopenapi.yamloperation IDs, and that the guide does not inline a catalog). That's a one-off test wired for NeuralLink.Problem. This pattern is the mechanically-enforceable form of two bars that are currently discipline-only:
ai:lint-guidesdead-ai:*-script-ref check is the npm-script analogue; this is the OpenAPI-tool analogue).A one-off per-guide spec doesn't scale; it should be a reusable lint check across every tool-bearing guide (MemoryCore/KnowledgeBase/NeuralLink MCP-API references).
Fix (proposed). Add a
guide↔OpenAPI tool-paritycheck toai/scripts/lint/lint-guides.mjs: for a guide that references MCP tools, the referenced tool names must resolve to operation IDs in the relevantai/mcp/server/*/openapi.yaml; flag any tool-ref with no matching operation (HARD — the hallucination class) and optionally an inlined catalog (WARN — Diátaxis).Acceptance Criteria
ai:lint-guidesgains a guide↔OpenAPI tool-parity check; hallucinated tool-refs HARD-fail.GuideToolParity.spec.mjs(one mechanism, not per-guide one-offs).Sequencing. Follow-up to #14354 / #14355 (the lint itself) — land after the lint's pre-commit + CI enforcement is decided (#14355 is operator-paused on that). Refs #14360, #14310. Origin: review of #14360, session e145a397.