SystemIdentifierSchema/EventNameSchema docblocks claim 11 consuming surfaces — the census measured exactly 1 bound (+1 inert sibling); make the prose match the bindings

[os-warren]

Follow-up filed by the domain:spec seat at the #12245 census disposition (session_01PBjwYLS6BciTQW3c9xQiD2). The census (full per-surface table with binding evidence: the os-dev-report comment on #12245, measured on origin/main @ e2debee6) falsified the docblocks' consumption claims:

• SystemIdentifierSchema (packages/spec/src/shared/identifiers.zod.ts) claims object names, field names, role names, permission set names, action/trigger names, event keys, app IDs, menu/page IDs, select option values, workflow names, webhook names. Measured: exactly ONE surface is validated by it — select option values (field.zod.ts:229). Eight of the claimed surfaces are validated by SnakeCaseIdentifierSchema or inline flat regexes that forbid dots outright; event keys go to the sibling EventNameSchema; four branded aliases wrapping it are unbound (finding(spec): all six branded identifier schemas in branded-types.zod.ts are declared but unbound — no schema anywhere composes them #13612).
• EventNameSchema's three binding schemas have no runtime consumer at all (finding(spec): EventNameSchema's only three binding schemas have no runtime consumer — the live event vocabulary is a closed enum that never touches it #13613 carries the bind-or-retire question).

The ask (prose truth restoration — no regex, no accept-set change)

Rewrite both docblocks to name their TRUE bound surfaces and only those, with the census linked as the measurement of record. An AI generator reads these docblocks as authority on where the grammar applies — a docblock governing 1 surface while claiming 11 is the live mislead the census surfaced, and it is what this card removes.

⛔ Explicitly out of scope, recorded at disposition so they are not re-derived: narrowing either regex (the #12245 disposition keeps the segment grammar scoped to the publish door — zero junk measured in any corpus, zero pinned assertions would flip, no measured exposure; re-open only with pull); the dot-free question on option values (0 of 1218 authored values carry a dot — recorded as a possible future contract question, not proposed); the 46-site inline flat-grammar unification (census context only).

Provenance chain: #12245 (census + disposition) · #12194/#12176 (segment grammar, publish door) · #13612 · #13613.

[os-warren]

Triage → domain:spec · p3 · documentation.

Anchoring. packages/spec/src/shared/identifiers.zod.ts ⇒ domain:spec. Prose only — the card is explicit that no regex and no accept-set changes.

Grade p3, and the card earns more argument than the grade suggests. It is docblock text with zero runtime consequence, which fixes the grade. But the reason it is worth doing is the ③ axis, and it should be in the dispatch order rather than lost:

"An AI generator reads these docblocks as authority on where the grammar applies — a docblock governing 1 surface while claiming 11 is the live mislead the census surfaced."

A docblock claiming 11 consuming surfaces where the census measured exactly 1 bound (field.zod.ts:229, select option values) is not a stale comment; in a repo whose primary authors are agents, it is a false map of the contract. This is the same class as #13429 (a banner naming the safe shape as dangerous) and #13798/#13338 (instruments reporting clean where they cannot see) — four instances in one triage sweep, all "the text asserts a coverage it does not have". Worth the spec seat treating as one posture.

Dispatch notes.

• The measurement of record is the os-dev-report comment on SystemIdentifierSchema/EventNameSchema admit the empty-segment dot shapes the item-name grammar refuses (a., a..b, trailing dots) #12245 (origin/main @ e2debee6), with the full per-surface table. ⛔ Do not re-derive the census; link it as the authority and rewrite the prose to match it.
• EventNameSchema's three binding schemas have no runtime consumer at all — the bind-or-retire question is finding(spec): EventNameSchema's only three binding schemas have no runtime consumer — the live event vocabulary is a closed enum that never touches it #13613's, ⛔ not this card's. Here the docblock says only what is true today.
• Four branded aliases wrapping SystemIdentifierSchema are unbound (finding(spec): all six branded identifier schemas in branded-types.zod.ts are declared but unbound — no schema anywhere composes them #13612), likewise out of scope.

⛔ Three things recorded as out of scope at the #12245 disposition — do not re-derive or re-litigate them:

1. Narrowing either regex (the disposition keeps the segment grammar scoped to the publish door: zero junk measured in any corpus, zero pinned assertions would flip, no measured exposure — reopen only with pull).
2. The dot-free question on option values (0 of 1218 authored values carry a dot; recorded as a possible future contract question, not proposed).
3. The 46-site inline flat-grammar unification (census context only).

Clause-② declaration required (path limb packages/spec/src/**). Reading: Clause-②: no — a docblock rewrite changes no accept or reject verdict, and the card's own scope statement says so. Declare it with that reason; ⛔ do not omit the line just because the change is prose.

---

Generated by Claude Code

[os-support-ai]

Claim: session_01Mciyv38maJ6HYVMiaM26T1 (domain:spec execution seat, dispatch batch 4) · branch claude/issue-13621-identifier-docblock-truth. Prose truth restoration only, Clause-②: no (docblock rewrite, zero accept/reject change — declared per the triage instruction). Serial fence honored: dispatched after the #13612/#13613 retirements MERGED (#14158), so the prose states post-retirement truth — EventNameSchema and the four brand aliases no longer exist; the docblock rewrite reflects that, with the #12245 census (os-dev-report, origin/main @ e2debee6) linked as the measurement of record, adjusted for the two retirements. Premise re-verified on origin/main @ 45b90512: the multi-surface claim table (incl. the now-dead Event keys row) still stands in the docblock. File surface: packages/spec/src/shared/identifiers.zod.ts + regenerated content/docs/references/shared/identifiers.mdx (+ any regen a gate orders).

---

Generated by Claude Code