feat(spec): retired-key tombstones + ship CHANGELOG in the npm artifact#2543
Merged
Conversation
An agent upgrading a downstream app meets exactly one guaranteed channel:
the create() rejection. Today it dead-ends ('not assignable to never' /
bare unknown-key); the docs site is off-artifact and version-skewed, and
the changesets' migration notes never left the monorepo (CHANGELOG.md was
not in the files allowlist — verified absent from a real consumer's
node_modules).
- UNKNOWN_KEY_GUIDANCE tombstones for compactLayout / detail / views /
defaultDetailForm: each rejection names the replacement + version +
decision. Entries age out ~two majors after removal.
- CHANGELOG.md added to the files allowlist (216KB, grep-target).
- llms.txt: 'Upgrading Across Spec Versions' — tombstone first, then grep
the shipped CHANGELOG; never re-add keys or downgrade to pass.
- AGENTS.md: breaking changesets must carry FROM→TO migration notes, and
removing an authorable key requires a tombstone.
spec object tests 75/75 green (3 new tombstone assertions);
npm pack --dry-run confirms CHANGELOG.md ships.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 92 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
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
1 participant
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.
Closes the upgrade-path gap found by role-playing the hotcrm upgrade agent: the one channel every upgrading consumer is guaranteed to hit is the
create()rejection — and today it dead-ends. The docs site is off-artifact (version skew, needs network); the changesets' carefully-written migration notes never left the monorepo (CHANGELOG.mdwas not in thefilesallowlist — verified absent from a real consumer'snode_modules).Three pieces
UNKNOWN_KEY_GUIDANCE, reusing the Object-levelworkflows: [...](and any unknown ObjectSchema key) is silently stripped at build — no error/warning (ADR-0032 'no silent failure', metadata layer) #1535 fixable-error mechanism): rejectingcompactLayout/detail/views/defaultDetailFormnow prints the replacement key, the version/decision that removed it, and the one-line fix. Tombstones age out ~two majors after removal — the map's content always equals the upgrade paths the platform actually digests.CHANGELOG.mdships in the npm package: migration notes travel with the exact installed version, greppable offline.npm pack --dry-runconfirms (216KB).llms.txtupgrade section + AGENTS.md discipline: agents learn the tombstone→CHANGELOG protocol (and never to re-add keys or downgrade to silence errors); authors learn that breaking changesets must carry FROM→TO notes and key removals require a tombstone.Verification
npm pack --dry-runlists CHANGELOG.md.🤖 Generated with Claude Code