feat(cli): surface migration guide when specVersion trails the installed platform

[os-zhuang]

Problem

When a downstream/third-party app upgrades the ObjectStack platform, the curated per-major migration guide is effectively undiscoverable from the app's side. An agent (or human) doing the upgrade naturally reaches for the on-disk node_modules/@objectstack/*/CHANGELOG.md files and reverse-engineers the breaking changes from them — never finding docs.objectstack.ai/docs/releases/v<major>, which has the before/after examples and migration checklist. Nothing on disk points there.

Change

os validate, os build / os compile, and os doctor now emit a non-blocking advisory when an app's authored manifest.specVersion declares an older major than the @objectstack/spec actually installed in its node_modules — i.e. the platform moved ahead of what the app declares. The advisory links the curated guide for the installed major:

  ⚠ Installed @objectstack/spec is v14.7.0 but this app declares specVersion for v12.
      → Review the v14 migration guide before bumping specVersion: https://docs.objectstack.ai/docs/releases/v14

Every major from v12 on is guaranteed a content/docs/releases/v<major>.mdx page by scripts/check-release-notes.mjs, so the URL never 404s. Once the app bumps its specVersion to match the platform, the advisory goes silent.

Details

• New shared util packages/cli/src/utils/spec-version.ts → checkSpecVersionGap(manifest, installedVersion?). Resolves the installed spec from the app on disk via @objectstack/spec/package.json (allowed by its exports map), with the version injectable for tests.
• Wired into validate.ts, compile.ts (which build extends), and doctor.ts, following each command's existing warning/health-check idiom.
• Advisory-only: never fails a build/validate, and explicitly not gated by --strict. Also surfaced in --json output as specVersionGap.
• Scope is deliberately the upgrade case (declared < installed). A declared > installed mismatch is a stale/mismatched install — a different problem, left out.

Testing

• Unit: packages/cli/src/utils/spec-version.test.ts — 8 cases (older/matching/newer declared major, two-major jump points at the installed major, missing/ non-string specVersion, unresolvable install). All pass.
• Type-safety: verified via a stash-diff that the change introduces zero new tsc error signatures (pre-existing errors in this partial build are unbuilt sibling packages + pre-existing implicit-any in validate.ts/compile.ts that this PR does not touch); the new file is clean.
• End-to-end smoke: ran the real disk-resolution path from an app with @objectstack/spec@14.7.0 installed — a manifest declaring ^12 fires with the correct /docs/releases/v14 URL; ^14 and a manifest-less config stay silent.

Notes

@objectstack/cli is in the fixed changeset group, so the included minor changeset versions it in lockstep with the rest of the platform train, as usual.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YV2dfQ9eR8NYKLSTVLKavY

---

Generated by Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 14, 2026 1:47pm

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/ai/skills-reference.mdx (via packages/cli)
• content/docs/api/client-sdk.mdx (via @objectstack/cli)
• content/docs/api/data-flow.mdx (via @objectstack/cli)
• content/docs/api/environment-routing.mdx (via @objectstack/cli)
• content/docs/api/error-catalog.mdx (via @objectstack/cli)
• content/docs/automation/hook-bodies.mdx (via packages/cli)
• content/docs/deployment/backup-restore.mdx (via @objectstack/cli)
• content/docs/deployment/self-hosting.mdx (via @objectstack/cli)
• content/docs/getting-started/cli.mdx (via @objectstack/cli)
• content/docs/getting-started/your-first-project.mdx (via @objectstack/cli)
• content/docs/kernel/runtime-services/data-service.mdx (via packages/cli)
• content/docs/kernel/runtime-services/index.mdx (via packages/cli)
• content/docs/permissions/authentication.mdx (via @objectstack/cli)
• content/docs/plugins/packages.mdx (via @objectstack/cli)
• content/docs/protocol/objectos/plugin-spec.mdx (via @objectstack/cli)
• content/docs/protocol/objectos/realtime-protocol.mdx (via @objectstack/cli)
• content/docs/releases/implementation-status.mdx (via @objectstack/cli)

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.