fix(lint): correct stale two-agent docblock over PLATFORM_AGENT_NAMES

[os-help]

Fixes #7088

What was wrong

packages/lint/src/validate-ai-agent-authoring.ts:65 carried a docblock reading "The two platform agent ids" directly above the four-member PLATFORM_AGENT_NAMES set (:69):

const PLATFORM_AGENT_NAMES = new Set(['ask', 'build', 'data_chat', 'metadata_assistant']);

What settled this

Per the cloud-side reading in #7088's thread (measured on cloud origin/main @ 485cbd3):

The kernel ships exactly two platform agents, and the other two names are legacy aliases, not agents: registerAgentAlias(LEGACY_BUILD_AGENT_NAME, BUILD_AGENT_NAME) and registerAgentAlias(LEGACY_DATA_AGENT_NAME, ASK_AGENT_NAME) — i.e. metadata_assistant→build, data_chat→ask.

• The stack.zod.ts:413 describe ("the kernel ships exactly two (ask/build)") is factually correct — disposition A's premise ("four agents") is refuted.
• Disposition B's shrink is also wrong: the four-member PLATFORM_AGENT_NAMES set is behaviorally correct as a reserved-names set — an app declaring data_chat or metadata_assistant is shadowing a platform record via the alias registry, which is exactly what the gate exists to word differently.
• The one surface that is actually wrong is the gate's own doc comment, "The two platform agent ids" sitting over a four-member set. The durable fix is prose there — e.g. "the two platform agent ids plus their two legacy aliases (data_chat→ask, metadata_assistant→build, per the cloud alias registry)". No behavior change anywhere.

What changed

Prose-only fix in one file: the docblock above PLATFORM_AGENT_NAMES now says the set holds the two platform agent ids plus their two legacy aliases, and explains why declaring any of the four names is caught by this gate. PLATFORM_AGENT_NAMES itself, the gate logic, and its messages are untouched — no behavior change.

Out of scope per the ruling on this card: packages/spec/src/stack.zod.ts (a different seat's surface — the optional alias cross-reference note there is reported in the dispatch report for the PM to route) and packages/mcp/src/mcp-server-runtime.ts:445 (not evaluated here).

Tests

• pnpm --filter '@objectstack/lint^...' build — dependency closure builds clean.
• pnpm --workspace-concurrency=2 --filter @objectstack/lint test -- --maxWorkers=2 — 68 test files, 1771 passed, 4 skipped, 0 failed.
• pnpm --workspace-concurrency=2 --filter @objectstack/lint typecheck — clean.
• node scripts/check-nul-bytes.mjs — clean.

No changeset: comment-only change, releases nothing.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 10, 2026 2:02am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint.

2 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/automation/hook-bodies.mdx (via @objectstack/lint)
• content/docs/permissions/authorization.mdx (via @objectstack/lint)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/v17.mdx (via @objectstack/lint)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.