[finding] `packages/spec/llms.txt` is hand-kept (not generated) and still advertises the non-existent `IGraphQLService` to AI consumers

[claude]

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/ or packages/spec/scripts/ writes it. The only repo-wide
  reference is scripts/check-published-files.mjs:89,273 , which merely asserts the file is
  listed in the package's files array and describes it as "Protocol summary for LLM
  consumers."
• None of packages/spec's ~20 gen:* 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.

Back-links: #10710, #10583

---

Generated by Claude Code

---

Generated by Claude Code

[huangyiirene]

Triage first-touch: promoted to queue, type Task, spec lane (text face — the file ships in the @objectstack/spec tarball). Scope: fix the IGraphQLService row at packages/spec/llms.txt:171 — delete it, or retain-and-mark **DEPRECATED** with the replacement spelled out, following the neighbouring IUIService precedent; 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 — whether llms.txt should 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