Skip to content

chore(mcp): export-surface corpus is stale on main and no branch can see it #1668

Description

@rickylabs

Problem

deno task check:mcp-export-corpus exits 1 on main. The checked-in MCP export-surface corpus is stale against its generator, and because it is already red at base, no feature branch's CI can distinguish "I broke it" from "it was already broken".

Evidence

Reproduced in detached worktrees at two heads during the #1665 generated-asset closure audit:

Head Result
baf1cdf67 (merge base at the time) check:mcp-export-corpus EXIT 1
9a2c74c41 (#1665 branch) check:mcp-export-corpus EXIT 1, identical regenerated diff
error: MCP export-surface corpus is stale; run deno task gen:mcp-export-corpus
  at .llm/tools/docs/generate-export-surface-corpus.ts:475:13

Independently confirmed by the #1665 asset-chain evaluator, which measured a 5+/5- regeneration diff and recorded it as advisory A1.

Why it matters

A permanently-red freshness gate is worse than no gate: it trains readers to skip it, and it masks a genuine regression the day one lands. This is the same failure mode the agent-docs prose gate caught correctly on #1665 precisely because that one was green at base.

Not part of the docs cascade

This is not a member of derivedAssetCascadePaths (.llm/assets/agent-docs/prose.json.gz, .llm/assets/agent-docs/provenance.json, packages/cli/src/kernel/assets/agent-docs.generated.ts, packages/mcp/src/publish-assets.generated.ts), and generate-export-surface-corpus.ts reads neither docs/site, agent-docs, nor .llm/assets. It is an independent generator, so a docs edit does not cause or fix it.

Proposed fix

Run deno task gen:mcp-export-corpus on its own branch, commit the regenerated corpus, and confirm check:mcp-export-corpus exits 0 at that head. Scope should be the generated corpus only.

Acceptance

  • deno task check:mcp-export-corpus exits 0 on main.
  • The regeneration diff is confined to the generated corpus; no hand-written source moves.
  • A note records why the corpus drifted, so the gap that let it go stale is visible.

Found during the PR #1665 four-link generated-asset closure audit; filed separately because it is out of that leaf's authorized surface and pre-existing at its merge base.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions