Add upstream compatibility baseline check and commit-trace helpers

[jooh]

Motivation

• Prevent accidental drift of the upstream/ submodule by making the pinned upstream commit explicit and traceable in CI output.
• Provide machine-friendly helpers and a dedicated CI guard to fail early when the pinned upstream commit changes so parity updates are intentional.
• Document the recommended submodule bump workflow so maintainers run parity checks and update the recorded baseline together.

Description

• Add formatUpstreamCommitTraceLine(...) and reportUpstreamCommitRegression(...) helpers to src/spec-node/migration/upstreamCompatibility.ts to format trace log lines and report commit-change regressions.
• Add unit tests in src/test/upstreamCompatibility.test.ts to cover trace formatting and regression detection, and extend existing compatibility contract tests.
• Introduce build/check-upstream-compatibility.js and baseline metadata at docs/upstream/compatibility-baseline.json to emit the pinned commit trace and fail CI when recorded and current pinned commits diverge.
• Wire the new check into npm scripts (check-upstream-compatibility) and the CI workflow (.github/workflows/dev-containers.yml), and add the recommended update sequence to README.md and mark TODO subtasks complete.

Testing

• Ran the updated unit tests with node -r ts-node/register ./node_modules/mocha/bin/mocha --exit src/test/upstreamCompatibility.test.ts which passed (6 passing).
• Ran npm run check-upstream-compatibility which printed the pinned commit trace and reported the baseline as matching (exit 0).
• Ran npm run check-upstream-submodule which passed the existing upstream presence checks (exit 0).
• Ran npm run type-check which completed successfully (no TypeScript build errors).
• Note: npm test -- --grep "upstream compatibility contract helpers" failed in this environment due to ESM/ts-node resolution quirks, so tests were validated via the direct node -r ts-node/register mocha invocation above.

---

Codex Task

[jooh]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fdf33752c6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Read submodule gitlink from index instead of HEAD

git rev-parse HEAD:upstream reads the gitlink from the current commit tree, so this check ignores submodule pointer changes that are staged but not yet committed (git add upstream). In the documented bump workflow, the script can therefore report that the baseline matches even after changing the pinned upstream commit, and only fail later once a commit is created in CI. Resolve the gitlink from the index (for example :upstream) or cached submodule status so staged updates are detected immediately.

Useful? React with 👍 / 👎.

[jooh]

@codex fix comment

[chatgpt-codex-connector]

Summary

• Updated the upstream compatibility guard to resolve the upstream submodule gitlink from the Git index (git rev-parse :upstream) instead of from HEAD, so staged submodule pointer updates are detected immediately (before commit).

Testing

• ✅ npm run check-upstream-compatibility

View task →