Context
#13309 / PR #13310 fixed learn/agentos/NeuralLink.md after it drifted to "33 tools" while the live OpenAPI exposes 40–41 — 10+ tools (incl the entire mutation surface create_component / remove_component / undo / redo / call_method) silently undocumented. The fix took 3 review cycles (@neo-gpt), partly because the drift was invisible until someone diffed the guide against the openapi by hand. The guide explicitly names openapi.yaml as its SSOT, yet nothing enforced the doc's tool-coverage staying in sync — so it rotted every time a tool landed (the undo/redo work added 2 the guide never tracked).
The Problem
Agent-consumed tool guides (learn/agentos/NeuralLink.md, and the same risk for the other MCP-server guides) are hand-maintained tables that drift from their generated OpenAPI SSOT. There is no mechanical guard: test/playwright/unit/ai/mcp/validation/OpenApiValidatorCompliance.spec.mjs validates openapi-internal compliance + the serviceMapping↔tier parity, but nothing asserts the human-readable GUIDE documents every tool the openapi exposes. Drift is caught only by manual diff — cost: #13309's 3 review cycles, plus the live friction of an agent querying the guide and inheriting a stale tool count / missing the mutation surface.
The Fix
A unit test (mirroring the OpenApiValidatorCompliance.spec pattern under test/playwright/unit/ai/mcp/validation/) that asserts each agent guide's documented tool-set == its openapi's operationId-set — coverage parity, NOT description text (the hand-written per-tool prose stays free-form; only tool-name presence is checked). v1 scope: learn/agentos/NeuralLink.md ↔ ai/mcp/server/neural-link/openapi.yaml. Extract the guide's tool names from its markdown table rows (| `tool_name` | … |); compare to the openapi operationIds; fail with the precise drift sets (doc-only / openapi-only) — the exact grep-diff #13309/#13310 ran by hand, made mechanical.
Acceptance Criteria
Out of Scope
- Auto-GENERATING the tables from openapi (would lose the rich hand-written descriptions; this check preserves them).
- Other MCP-server guides (memory-core / knowledge-base / file-system / github-workflow) — a follow-up once the helper exists.
Dependencies / Sequencing
- BUILD-GATED on #13310 (the
NeuralLink.md doc-fix) merging — until then dev's guide is stale and the check would (correctly) fail. The deferred redo doc-row (lands with #13307's merge) must also be in before the check can assert the full 41-tool parity.
Related
Friction source: #13309 (doc-fix) / PR #13310 (3-cycle review). Sibling guard: OpenApiValidatorCompliance.spec. Refs #13012 (the tool surface IS the agent's body-interface — its guide must not lie to the agent reading it).
Origin Session ID: a0bc6b23-78c5-4bd7-b944-9db5e236f42d
Release classification: boardless (test-infra / MX-friction guard — not v13-release-blocking).
Context
#13309 / PR #13310 fixed
learn/agentos/NeuralLink.mdafter it drifted to "33 tools" while the live OpenAPI exposes 40–41 — 10+ tools (incl the entire mutation surfacecreate_component/remove_component/undo/redo/call_method) silently undocumented. The fix took 3 review cycles (@neo-gpt), partly because the drift was invisible until someone diffed the guide against the openapi by hand. The guide explicitly namesopenapi.yamlas its SSOT, yet nothing enforced the doc's tool-coverage staying in sync — so it rotted every time a tool landed (the undo/redo work added 2 the guide never tracked).The Problem
Agent-consumed tool guides (
learn/agentos/NeuralLink.md, and the same risk for the other MCP-server guides) are hand-maintained tables that drift from their generated OpenAPI SSOT. There is no mechanical guard:test/playwright/unit/ai/mcp/validation/OpenApiValidatorCompliance.spec.mjsvalidates openapi-internal compliance + the serviceMapping↔tier parity, but nothing asserts the human-readable GUIDE documents every tool the openapi exposes. Drift is caught only by manual diff — cost: #13309's 3 review cycles, plus the live friction of an agent querying the guide and inheriting a stale tool count / missing the mutation surface.The Fix
A unit test (mirroring the
OpenApiValidatorCompliance.specpattern undertest/playwright/unit/ai/mcp/validation/) that asserts each agent guide's documented tool-set == its openapi'soperationId-set — coverage parity, NOT description text (the hand-written per-tool prose stays free-form; only tool-name presence is checked). v1 scope:learn/agentos/NeuralLink.md↔ai/mcp/server/neural-link/openapi.yaml. Extract the guide's tool names from its markdown table rows (| `tool_name` | … |); compare to the openapioperationIds; fail with the precise drift sets (doc-only / openapi-only) — the exactgrep-diff #13309/#13310 ran by hand, made mechanical.Acceptance Criteria
NeuralLink.md's documented tool-set == the neural-link openapioperationId-set; fails on drift in either direction, naming the offending tools.(guidePath, openapiPath)pair so other MCP-server guides can be added later.Out of Scope
Dependencies / Sequencing
NeuralLink.mddoc-fix) merging — until then dev's guide is stale and the check would (correctly) fail. The deferredredodoc-row (lands with #13307's merge) must also be in before the check can assert the full 41-tool parity.Related
Friction source: #13309 (doc-fix) / PR #13310 (3-cycle review). Sibling guard:
OpenApiValidatorCompliance.spec. Refs #13012 (the tool surface IS the agent's body-interface — its guide must not lie to the agent reading it).Origin Session ID: a0bc6b23-78c5-4bd7-b944-9db5e236f42d
Release classification: boardless (test-infra / MX-friction guard — not v13-release-blocking).