docs(agents): list which spec artifact each CI gate guards, and how to regenerate it - #4046
Merged
Merged
Conversation
…o regenerate it `packages/spec` has eight checked-in generated artifacts, each with its own gate, split across two CI jobs that run their gates sequentially — so the first stale artifact masks every one behind it and you get one red build per artifact. AGENTS.md documented the auto-gen boundary but never mapped a change to the generator it invalidates, so the mapping had to be rediscovered from red CI. #4040 paid that twice, neither time a logic error: a `.describe()` string landed in `content/docs/references/` (`check:docs`), and one new export landed in `api-surface.json` (`check:api-surface`) — the second only visible after the first was fixed. Adds a change → gate → regenerate table, plus a loop that runs all eight so the tooling reports which artifact is stale instead of CI doing it one per push. Also records that `check:liveness` / `check:empty-state` / `check:skill-examples` / `check:react-conformance` have no generator — a failure there is a real finding, not an artifact to regenerate. Includes a caveat found while verifying this: `check:api-surface` reads the built `dist/*.d.ts`, so a stale `dist` reports exports as REMOVED when nothing was removed — the snapshot is just newer than the build. It reported two phantom breaking removals (`canonicalAstOperator`, `FieldErrorCode`) on an untouched tree until `pnpm build` was run, which is exactly the shape of a bug someone would otherwise file against `main`. Every command in the new section was run as written, from a clean checkout of the merged main: all eight gates PASS. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QoA8AV99Ss1RRkLLAYmDzq
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
`Check Changeset` requires every PR to add a `.changeset/*.md` (diffed against the PR base, so the directory's existing entries can't mask a missing one). An empty-frontmatter changeset is the sanctioned "releases nothing" declaration, on par with the `skip-changeset` label, and there is ample precedent for docs-only changes (`adr-0104-design-doc-only.md` and others). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QoA8AV99Ss1RRkLLAYmDzq
os-zhuang
marked this pull request as ready for review
July 30, 2026 06:45
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #4040 — the DX gap that PR hit twice. Docs only, no code.
Why
packages/spechas eight checked-in generated artifacts, each with its own CI gate, split across two jobs (TypeScript Type Checkinlint.yml,Check Generated Artifactsinci.yml). Each job runs its gates sequentially, so the first stale artifact masks every one behind it — you get one red build per artifact, not one for all of them.AGENTS.md documents the auto-gen boundary ("never hand-edit
content/docs/references/") but never maps a change to the generator it invalidates. So the mapping gets rediscovered from red CI.#4040 paid it twice, neither time a logic error:
.describe()string → stalecontent/docs/references/automation/node-executor.mdx→check:docsred.check:api-surfacered, because five new exports weren't inapi-surface.json. Invisible until the first was fixed.A
.describe()reads like a comment and lands in published docs; adding one export lands in a snapshot. Neither is obvious from the diff.What this adds
A change → gate → regenerate table:
.describe()/ TSDoc on any schemacheck:docsgen:schema && gen:docscheck:api-surfacegen:api-surfacecheck:authorable-surfacegen:schemacheck:spec-changes,check:upgrade-guidegen:spec-changes,gen:upgrade-guideSKILL.mdcheck:skill-docs,check:skill-refsgen:skill-docs,gen:skill-refscheck:react-blocksgen:react-blocksPlus a copy-pasteable loop that runs all eight, so the tooling says which artifact is stale instead of CI saying it one push at a time.
It also records that
check:liveness,check:empty-state,check:skill-examplesandcheck:react-conformancehave no generator — a failure there is a real finding to fix, not an artifact to regenerate. Worth stating, because the reflex after reading the table would be to look for agen:counterpart that doesn't exist.A trap found while verifying this section
Running the loop on a clean checkout of merged
mainreported:Nothing had been removed.
check:api-surfacereads the builtdist/*.d.ts, notsrc/— and mydistpredated the merge, so the newer checked-in snapshot looked like it had lost exports.pnpm buildand it passes.That is exactly the shape of a bug someone would otherwise file against
main, so the caveat is now in the section, the loop starts withpnpm build, and the phantom pair is named so the next person recognises it.Test plan
Every command in the new section was run as written, from a clean checkout of merged
main(e4c61a7) afterpnpm build:Single file, +43/−0, no code touched.
Note on the branch
The designated branch's previous PR (#4040) is merged and GitHub auto-deleted the branch, so this is a fresh branch of the same name off merged
main(e4c61a7) with one new commit — not stacked on merged history, and no force-push involved.Not done here
An aggregate
gen:all/check:generatedscript would beat a documented loop, but it adds a script name and a maintenance surface to a repo with strong conventions — worth your call rather than my guess. Say the word and I'll add it.🤖 Generated with Claude Code
https://claude.ai/code/session_01QoA8AV99Ss1RRkLLAYmDzq
Generated by Claude Code