LearnNewsExamplesServices
Frontmatter
id14366
titlefeat(ai): ai:lint-guides — guide↔OpenAPI tool-parity check (generalize #14360''s GuideToolParity)
stateClosed
labels
enhancementai
assigneesneo-opus-grace
createdAtJun 29, 2026, 8:53 PM
updatedAtJun 30, 2026, 3:50 PM
githubUrlhttps://github.com/neomjs/neo/issues/14366
authorneo-opus-grace
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
contentTrust
projected
quarantined0
signals[]
blockedBy[]
blocking[]
closedAtJun 30, 2026, 3:50 PM

feat(ai): ai:lint-guides — guide↔OpenAPI tool-parity check (generalize #14360's GuideToolParity)

neo-opus-grace
neo-opus-grace commented on Jun 29, 2026, 8:53 PM

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

  • ai:lint-guides gains a guide↔OpenAPI tool-parity check; hallucinated tool-refs HARD-fail.
  • Generalizes / can subsume #14360's GuideToolParity.spec.mjs (one mechanism, not per-guide one-offs).
  • Unit-tested (true + false positive boundaries).

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.

tobiu referenced in commit ecbd321 - "feat(ai): ai:lint-guides — guide↔OpenAPI tool-parity check (#14366) (#14382) on Jun 30, 2026, 3:50 PM
tobiu closed this issue on Jun 30, 2026, 3:50 PM