[Devtools update automation 3] Centralize Changesets and migrate consumers automatically

[artiphishle]

Identity

Parent roadmap: #64
Roadmap ID: devtools-update-automation
Roadmap step: 3

Goal / ownership

Make @ankhorage/devtools the single owner of Changesets CLI execution and automatically migrate every Changesets-enabled Ankhorage consumer through the released Devtools synchronization contract.

Owner: ankhorage/devtools owns the Changesets dependency, canonical command/binary, managed package scripts, status/sync behavior, workflow templates, documentation, and owner tests.

Consumer repositories own their .changeset/config.json, pending .changeset/*.md files, package release semantics, and repository-specific acceptance. They must not declare @changesets/cli directly after migration.

Renovate owns the trusted cross-repository execution/write boundary used to apply the released Devtools contract. Do not replace that automation with manual repository-by-repository edits.

Required skills

Before claiming or changing this issue, load and follow these installed skills in this order:

1. ankhorage-roadmap — refresh PR, release, consumer, and roadmap reality; preserve phase-level dependencies and the Devtools release boundary.
2. ankhorage-package-structure — enforce standalone package ownership, public API/source layout, Devtools-managed artifacts, Changesets, documentation, and the full validation contract.
3. expo-project-structure — conditional only if this work creates a brand-new Expo acceptance app or fixture. It is a new-project layout skill and must not be used to restructure Studio, the Expo orchestrator modules, or any other existing consumer.

Repository AGENTS.md rules remain authoritative where present. Do not use the conditional Expo skill merely because an existing consumer uses Expo.

Current-state audit

• This issue was created in May 2026 and its original repository list and command proposals are stale.
• The latest published owner is @ankhorage/devtools@1.8.0; final consumer enforcement is published in @ankhorage/doctor@0.10.3.
• Devtools 1.7.2 contains the npm-12-compatible @changesets/cli@2.31.1 baseline inside Devtools itself; PR feat: centralize Changesets execution #77 adds the missing published runner and consumer synchronization contract.
• Ankh main commit 7271b2cc69d3316f43522c23b1289e75c31524ac proved the missing downstream contract: the release workflow used consumer-local @changesets/cli@2.31.0, treated already published 0.8.3 as unpublished under npm 12, and attempted to republish it.
• Current Devtools package synchronization centralizes ESLint, Prettier, Knip, Bun metadata, and workflows, but does not own Changesets. Merely merging PR fix(deps): update devtools-owned toolchain #73 therefore cannot repair consumers.
• Current organization search shows Changesets usage beyond the old minimum list, including Ankh, Color Theory, Contracts, Doctor, Orchestrator, both Expo orchestrator modules, Paradox, React Native Reanimated DnD Web, Runtime, Studio, Supabase Storage, Surface, Templates, Zora, and Devtools itself. Implementation must perform a fresh organization-wide audit rather than treating this list as exhaustive.

Typed dependencies

• Implementation: none. Audit, design, Devtools implementation, owner tests, and documentation can start now.
• Integration: done — Doctor 0.10.2 unblocked PR feat: centralize Changesets execution #77, and final Doctor 0.10.3 now enforces the released no-direct-consumer-CLI contract.
• Release: done — @ankhorage/devtools@1.8.0 and GitHub release v1.8.0 are published.
• Acceptance: final generated consumer migrations and real release-path proof remain gated on that published Devtools release and are coordinated by [Devtools update automation 4] Prove released propagation in Surface and Studio #66.

Canonical contract

Devtools owner

• Move @changesets/cli into the published dependency surface required by the Devtools-owned runner; it must not remain only a development dependency that consumers separately duplicate.
• Expose one deterministic Devtools-owned Changesets command/binary using the package-resolved dependency.
• Never resolve an ambient executable, latest, an unpinned bunx changeset, sibling source, or an unpublished workspace.
• Extend the Devtools provider/command table only if that is the smallest coherent public surface; keep implementation in the existing CLI/tool ownership structure and add the required changeset for public behavior.
• Keep the supported Changesets version compatible with npm 12; PR fix(deps): update devtools-owned toolchain #73 establishes @changesets/cli@^2.31.1 as the current baseline.

Managed package contract

For repositories that use Changesets:

• remove direct @changesets/cli declarations from dependencies and devDependencies;
• write the canonical Devtools-backed changeset, changeset:status, and version-packages scripts;
• preserve unrelated scripts and package metadata;
• detect direct dependency or script drift in ankh devtools status .;
• make a second ankh devtools sync . byte-stable;
• run bun install when the manifest changes so bun.lock converges.

Repositories without Changesets must not acquire release tooling merely because Devtools is installed. Detect participation from the repository contract, including .changeset/config.json and/or the canonical release-script shape, using one explicit tested rule.

Managed workflows

• Render release and CI workflows from the same Devtools-owned Changesets command contract.
• Preserve trusted publishing, provenance, least privilege, and the existing pull_request_target security boundary.
• A main-branch release run with no pending version must finish cleanly without attempting to republish the current version.
• Consumer-specific workflows remain untouched.

Consumer state

• Keep .changeset/config.json and pending .changeset/*.md files in each publishing repository.
• Do not add compatibility wrappers or retain direct dependency fallbacks.
• Apply migrations through the released automatic Devtools/Renovate synchronization path. Do not open a collection of manual consumer cleanup PRs that bypasses the automation being proved.

Scope / non-goals

• Do not move .changeset/ into .ankh/.
• Do not redesign versioning, changelog, publishing, or release-PR semantics.
• Do not change Expo application structure.
• Do not weaken publishing provenance or execute untrusted PR-head code with a write-capable token.
• Do not patch Ankh or another consumer around a Devtools owner defect.
• Do not treat the May repository list as authoritative.

Implementation phases

1. Fresh organization audit

For every active Ankhorage repository, inspect:

• direct @changesets/cli declarations;
• .changeset/config.json;
• changeset, changeset:status, version-packages, and publish scripts;
• managed CI/release workflows;
• current Ankh/Devtools dependency placement.

Record participating repositories and exceptions in the PR or generated documentation, not as new per-repository issues unless a separate owner defect is discovered.

2. Devtools implementation

Implement the dependency/runner, managed package contract, workflow rendering, status/sync drift detection, documentation, and focused tests in ankhorage/devtools.

Add the correct Changeset. Do not manually edit generated Devtools-owned artifacts; use the canonical owner synchronization.

3. Owner verification and release

Run the repository-defined complete validation, including:

bun install
bun run build
bun run doctor
bun run lint
bun run format:check
bun run knip:check
bun run test
bun run typecheck
bun run docs
bun run changeset:status

Also prove:

• a Changesets-enabled fixture loses its direct CLI dependency and receives canonical scripts;
• a repository without Changesets remains unchanged in that concern;
• status reports drift before sync and current afterward;
• the second sync is byte-stable;
• the packaged tarball contains the runner/templates required by consumers;
• the canonical command resolves the Devtools-owned @changesets/cli@2.31.1+.

Merge and publish through the established Changesets release flow.

4. Automated consumer migration

After publication, let the canonical Renovate/Devtools integration update participating consumers. The generated PR must remove direct @changesets/cli, update scripts/workflows/lockfile, preserve repository-owned paths, pass a second stable sync, and pass normal CI.

Surface and Studio are the required cross-shape acceptance repositories under #66. Expo-specific verification follows each existing repository's own rules; expo-project-structure applies only if a new acceptance app is deliberately created.

Done when

• Devtools is the only package declaring @changesets/cli for the shared toolchain.
• Every active Changesets consumer uses the released Devtools-owned command without direct fallback dependencies.
• Managed package status/sync and workflow rendering enforce that contract deterministically.
• npm 12 no longer causes an already published package to be republished.
• Devtools validation, release, organization-wide no-legacy audit, and [Devtools update automation 4] Prove released propagation in Surface and Studio #66 Surface/Studio acceptance are green.
• Documentation explains the canonical command, consumer-owned .changeset/ state, migration behavior, and forbidden legacy forms.

Newly discovered release-PR CI gate (2026-08-28)

The generated CI contract currently runs changeset:status --since=origin/main unchanged on Changesets' own changeset-release/main pull requests. Those PRs intentionally consume/delete the pending Changeset while changing package.json and the changelog, so the normal unreleased-change guard reports “Some packages have been changed but no changesets were found.”

Evidence:

• ankhorage/renovate#18, CI run 33187690534: every substantive validation step passed; only Check changesets failed. The reviewed diff contained only the consumed Changeset, 0.1.4 changelog entry, and version bump. The PR was SHA-bound merged and @ankhorage/renovate@0.1.4 plus tag v0.1.4 are published.
• ankhorage/devtools#79, CI run 33186660022: the same single-step false negative; the reviewed release-only diff produced published @ankhorage/devtools@1.8.1 and tag v1.8.1.
• Green control release PRs ankhorage/supabase-db#15 and ankhorage/supabase-vault#20 produced 1.0.1 and 0.2.5 respectively.

Required owner fix:

• distinguish ordinary pull requests from the trusted Changesets release branch in the Devtools-managed CI template;
• preserve the strict missing-Changeset failure for ordinary package-changing PRs;
• make Version Packages PRs validate their release metadata without requiring a new unreleased Changeset;
• add positive and negative owner contract tests, synchronize the owner artifacts twice to byte stability, release Devtools, and let consumers converge through Renovate;
• do not patch consumer workflows individually.

Required skills remain ankhorage-roadmap followed by ankhorage-package-structure; repository AGENTS.md remains authoritative.

Release-path correction completed (2026-08-29)

• PR fix: validate detached Version Packages checkout #83 added an executable detached-checkout regression fixture and changed the managed Version Packages metadata command to status --since=HEAD; CI run #294 passed and the PR merged as 629711a2cd004e196b75fdbd682efe52b459f093.
• Release PR Version Packages #82 regenerated at 5d456118f5d271b08269855b21a6dfe8cc459852, consumed both patch Changesets, and was SHA-bound merged as 6079929ce3f489475115e327f9ac8f07e87a1d28.
• @ankhorage/devtools@1.8.2 and Git tag v1.8.2 are published and independently verified.
• The remaining completion gate is the automatic organization-wide consumer convergence and Surface/Studio acceptance tracked by [Devtools update automation 4] Prove released propagation in Surface and Studio #66; do not patch consumers manually.

P1 release-finalization regression (2026-09-02)

Devtools PR #74 upgraded the owned Changesets CLI from ^2.31.1 to ^3.0.1, first shipped in @ankhorage/devtools@1.9.0. Changesets CLI 3 changed publish output from the New tag: lines parsed by changesets/action@v1 to the new “Successfully published” / “Created git tags” reporter output.

The managed release action therefore publishes to npm successfully but detects zero released packages, returns published=false, pushes no remote tag, creates no GitHub Release, and still exits green.

Verified impact:

• @ankhorage/devtools@1.9.0 through 1.9.4 exist on npm but have no corresponding GitHub tags/releases; the last GitHub release is v1.8.5.
• @ankhorage/color-theory@0.1.0, 0.2.0, and 0.3.0 exist on npm but have no v0.1.0, v0.2.0, or v0.3.0 tags/releases.
• Color Theory release run 33575368632 logged a successful npm publish and local tag creation, but the action source at a45c4d5 only recognizes /New tag:/; no finalization call ran.

Required owner correction:

• restore an action-compatible Changesets release contract immediately (the safe recovery baseline is @changesets/cli@^2.31.1 unless a fully tested structured-output integration replaces changesets/action parsing);
• add release-path regression coverage that proves a publish is not green unless the expected remote tag and GitHub Release exist;
• publish the corrected Devtools release through the repaired path;
• audit every Ankhorage npm publication made with Devtools 1.9.x;
• backfill missing tags/releases from immutable npm version metadata and exact gitHead commits, without republishing or inventing version history;
• let consumers receive the correction through the canonical Devtools/Renovate synchronization path rather than manual workflow edits.

Execution state

Status: in-progress
Current gate: implement the native Changesets v3 finalization path, cover it with regression proof, release the owner correction, then backfill missing tags and GitHub Releases
Claim: /private/tmp/devtools-release-finalization-4

[artiphishle]

Product decision confirmed on 2026-09-02: do not roll Changesets back and do not add a v2 compatibility path. The owner repair must support the current Renovate-selected Changesets v3 release contract natively, update the managed workflow/tests accordingly, and keep future Renovate upgrades canonical. Another Codex worker is handling this owner repair; coordinate through the persisted claim before editing.

[artiphishle]

Owner repair is in review: #129

Evidence:

• production Studio run 33564150747 shows Changesets v3.0.1 publishing and creating local tags while changesets/action@v1 does not finalize them
• PR fix: finalize Changesets v3 GitHub releases #129 disables the action’s legacy GitHub-release parser and finalizes the exact v3 tags at HEAD by pushing them and creating any missing GitHub Release
• build, formatting, lint (existing warnings only), typecheck, docs, Knip (existing configuration hint only), focused workflow regression, full test suite (82 pass), and changeset status pass

GitHub branch protection currently requires review; I will not bypass it. After merge/release, the remaining organization-wide backfill can use immutable npm gitHead values.