Repository navigation
[finding] packages/spec/llms.txt is hand-kept (not generated) and still advertises the non-existent IGraphQLService to AI consumers #10833
Description
Found while implementing #10710. That card asked whether packages/spec/llms.txt is
generated or hand-kept — if generated, its content would be a symptom and the generator the
cause. Measured: it is hand-kept. So this is a fix at the file.
Evidence it has no generator
- No script under
scripts/orpackages/spec/scripts/writes it. The only repo-wide
reference isscripts/check-published-files.mjs:89,273, which merely asserts the file is
listed in the package'sfilesarray and describes it as "Protocol summary for LLM
consumers." - None of
packages/spec's ~20gen:*scripts emits it (gen:schema,gen:openapi,
gen:docs,gen:api-surface,gen:skill-refs, ... all target other artifacts). - The file carries hand-typed provenance in its own header:
> **Version**: 3.0.0,> **Schema Count**: 171 Zod schemas, 191 test files, 5,157 tests,
> **Last Updated**: 2026-02-12.
The defect
packages/spec/llms.txt:171 still advertises a service contract that does not exist:
| `IGraphQLService` | execute, subscribe |
IGraphQLService is declared nowhere in packages/**/src. After #10710 lands, the repo-wide
survivors are three CHANGELOGs (history, correctly immutable) and this line — which is not
history: it is a live "Context for AI Agents" summary shipped in the published
@objectstack/spec tarball, whose whole purpose is to tell an LLM what contracts exist.
An agent reading it will try to register IGraphQLService to reach /graphql, a route
packages/runtime/src/http-dispatcher.ts:2026 removed.
The neighbouring row shows the alternative to deletion if the history is worth keeping —
IUIService is retained and marked **DEPRECATED** with the replacement call spelled out.
Either disposition is defensible; the current state is not.
Worth deciding at the same time: whether a file this load-bearing for AI consumers should
stay hand-kept at all, given its own header has been stale since 2026-02-12.
Generated by Claude Code
Generated by Claude Code
Activity
huangyiirene commentedon Aug 21, 2026
Triage first-touch: promoted to queue, type Task, spec lane (text face — the file ships in the
@objectstack/spectarball). Scope: fix theIGraphQLServicerow atpackages/spec/llms.txt:171— delete it, or retain-and-mark**DEPRECATED**with the replacement spelled out, following the neighbouringIUIServiceprecedent; the filer shows either is defensible, and pointing AI consumers at REST/MCP is the accurate answer. While in the file, refresh or remove the hand-typed header counts (Schema Count,Last Updated: 2026-02-12) so the document stops asserting stale provenance. The larger question — whetherllms.txtshould be generated rather than hand-kept — is the spec seat's follow-up to raise separately, not this card. No accept/reject behaviour changes ⇒ no clause-②. Size/model suggestion: S, sonnet.Generated by Claude Code
docs(spec): drop stale GraphQL references and stale header provenance (…