Release pipeline: dev/main divergence + version drift — go trunk-based (semantic-release already in place)

[EivMeyer]

Problem

Releasing currently hand-commits to main (release: promote dev to main), which makes main and dev diverge permanently, and the package.json version drifts from what's on npm. Two owned-elsewhere invariants are violated: single source of truth (version) and no manual re-sync (promotion never flows back to dev).

This is not a missing-tool problem. zeroshot already runs semantic-release correctly: .releaserc.json releases from main, @semantic-release/git commits chore(release): ${version} [skip ci] back to main, @semantic-release/npm publishes, and release.yml runs it on CI success. The drift comes entirely from the branch topology around it — a long-lived dev branch plus a manual dev → main promotion flow. semantic-release commits the version bump only to main, that commit never flows back to dev, and the manual promotions pile up one-directionally.

Evidence (as of 2026-07-13)

• main carries 6 commits dev doesn't have — all are release bookkeeping, no product work:

  557c7b9 release: promote dev to main (#632)
  e3111e7 release: publish dev promotion using package release config (#630)
  0e4a7ec release: publish dev promotion without branch-write release artifacts (#627)
  ec2c5d7 release: publish dev promotion with release-aware analyzer (#625)
  c242575 release: promote dev to main (#617)
  ac354df feat: release deterministic e2e and run-plan hardening (#591)
  

• dev is ~59 commits ahead with the actual work. Neither branch can fast-forward to the other.
• Both branches' package.json say 6.4.0; npm latest is 6.6.0. The chore(release) bump commit lives only on main, so dev != npm.
• Motivating case: fix: resume --detach runs agents in caller and leaves zombie clusters #639 (fixes Bug: resume --detach runs agents in the caller and leaves zombie clusters #637) is merged, verified, and stuck on dev with no clean path to release without dragging 59 unrelated commits or cherry-pick gymnastics.

Fix: go trunk-based on main, delete the dev → main promotion flow

Align with how the-open-engine/agents releases (Nx Release + Conventional Commits — same philosophy, single-package equivalent here is semantic-release, which we already have). The agents repo never hits this problem because it is trunk-based with no dev branch: PRs merge straight to main, the release job runs on push to main, and semantic-release's [skip ci] bump commit lands on the same trunk everyone branches from — so nothing can drift.

feature PR ──▶ main (always green, always releasable)
                 │   Conventional Commit messages drive the bump
                 ▼
   CI passes on main ──▶ semantic-release: version commit + tag vX.Y.Z + npm publish

• Keep semantic-release as-is. branches: ["main"], git+npm+github plugins stay. No Changesets — semantic-release is the correct single-package tool and it's already wired.
• Retire dev. main is the trunk: every PR targets main, main is always releasable. This removes the divergence at the source.
• Version bump stays a real tracked commit on the trunk; branch == npm, always.

If a staging branch is genuinely wanted

Keep dev as integration only if there's a real QA-staging window, and enforce mechanically: main is fast-forward-only from dev (never direct commits to main; a failed --ff-only is a hard error), plus an auto back-merge main -> dev PR after each release so the chore(release) bump flows back. Trunk is simpler and preferred.

Optional hardening (adopt from the agents repo)

These are what makes the agents pipeline robust; worth pulling in while we're here:

• Conventional Commits gate in CI — validate every non-merge commit with commitlint (@commitlint/config-conventional) on PR/push/merge queue, so the version signal can't be malformed.
• Dedicated repo-scoped GitHub App token as the only bypass actor for protected main/tags, instead of the default GITHUB_TOKEN.
• Main-didn't-move guard — confirm main still equals the tested SHA before releasing; zeroshot's current workflow_run trigger can race. (agents checks this both before and after minting the release token.)
• Refuse-to-overwrite immutable tag/artifact guards, and a workflow_dispatch recovery path to rebuild a missing release from a protected tag.

One-time reconciliation (before adopting)

Merge main's 6 release commits into dev (or rebase so main is an ancestor of dev), land the currently-stuck work, tag that as the new baseline, then delete the promotion flow and retire dev.

Acceptance

• No release: promote dev to main style commits created going forward.
• main is the single trunk; package.json version on the trunk matches npm latest at all times.
• A single merged fix can be released without touching unrelated commits.
• If dev is kept at all, it cannot diverge from main without a hard CI failure.

[EivMeyer]

#640 execution detail — reconciliation plan + release GitHub App runbook

Facts verified 2026-07-15 against a fully unshallowed clone; refs match remote (main=557c7b9c, dev=620c3ed7).

Verified current state

Fact	Value
dev ahead of main	275 commits (260 non-merge + 15 merges)
main ahead of dev	6 commits (release/promote bookkeeping)
Tree delta dev → main	96 files, +86 / −35,714 → main is a stale subset of dev
main-only content	86 net lines in orchestrator.js, cli/index.js, detached-startup.js, AGENTS.md, assert-release-published.js — small, likely stale conflict-resolution artifacts, but real → must be preserved by a merge, not dropped
#639 (the stuck fix)	merged to dev 2026-07-13, not on main
Version drift	package.json on both branches = 6.4.0; npm latest + tags = 6.6.0
main protection	required_linear_history=true, enforce_admins=true, allow_force_pushes=false, checks [check, install-matrix (ubuntu), install-matrix (macos)], 0 reviews
dev protection	linear_history=false, enforce_admins=true, force_pushes=false, checks [check]

Root cause of the version drift (the real bug)

There are two semantic-release configs and the wrong one wins:

• .releaserc.json (on main) includes @semantic-release/git + @semantic-release/changelog → commits the version bump back to the branch.
• package.json has an inline "release" block (on both branches) with no git plugin → publishes to npm + tags + GitHub Release but never writes the version back.

cosmiconfig resolves one config; the inline block is present everywhere and lacks the write-back plugin, so package.json stays at 6.4.0 while npm marches to 6.6.0. Fix = delete the inline block, keep .releaserc.json as the single source. This is coupled to the GitHub App (below): once write-back is active, the release pushes a commit+tag to protected main, which needs a bypass identity.

---

Bucket B — reconciliation plan (needs your approval; I execute)

Constraint: main requires linear history + admins-included, so a normal merge commit from dev (which has 15 merges) is blocked. Three viable paths:

	Approach	Preserves	Cost
A (recommended)	Temporarily relax main protection → merge dev↔main reconciled → re-enable with trunk config	Both sides' history + main's 86 lines	one protection toggle window
B	Rebase dev onto main → force-push dev → ff main	commit granularity	flattens 15 merges; force-push on protected dev (risky)
C	Squash dev → main	clean linear main	loses 275-commit history; must hand-re-add main's 86 lines

Recommended path A — exact steps

1. [you, admin] Temporarily allow the reconcile push on main: add yourself (or the release App) as a bypass actor, or briefly disable required_linear_history + enforce_admins. Window is minutes.
2. [me] Branch reconcile/trunk-cutover from origin/dev; git merge origin/main. Resolve:
   • inspect main's 86-line delta — keep the correct version (expect dev's newer code wins; main's are stale artifacts — verified, not blind).
   • package.json: set version to 6.6.0 (match npm) and remove the inline "release" block.
   • confirm .releaserc.json is present and authoritative; union CHANGELOG.md.
3. [me] In the same branch, the trunk cutover CI edits:
   • remove the enforce-main-pr-source job (it mandates the dev→main promotion that causes the divergence).
   • drop dev from on: triggers (push/pull_request/merge_group → [main]).
   • ensure the commitlint gate from ci: enforce Conventional Commits with a commitlint gate #660 is included.
4. [me] PR reconcile/trunk-cutover → main; merge it under the relaxed window.
5. [you] Re-enable main protection with the trunk config: required checks [check, install-matrix…, commitlint], remove enforce-main-pr-source, add the release App as bypass actor (for the [skip ci] version commit).
6. [you] Retire dev: once main == reconciled content, delete dev (or keep as ff-only staging). Update any automation that targets dev (e.g. .zeroshot/settings.json PR base, if set).
7. Verify: main package.json version == npm latest; a workflow_dispatch dry-run computes the next version correctly from tags + commits; the branch==npm invariant holds.

Decision gates for you

• G1 — approve path A / B / C.
• G2 — confirm main's 86 unique lines are droppable-if-stale (I'll show you the diff before resolving).
• G3 — approve version→6.6.0 + delete inline release block.
• G4 — retire dev outright, or keep ff-only?
• G5 — approve the branch-protection edits in steps 1 and 5.

---

Bucket C — release GitHub App runbook (only you can create it)

Needed because activating @semantic-release/git write-back means the release pushes a commit + tag to protected main — the default GITHUB_TOKEN shouldn't be the identity that bypasses main protection.

Honesty note: releases work today with GITHUB_TOKEN only because the active (inline) config never pushes back to main. The App becomes necessary the moment we fix the drift. So it's coupled to the fix, not optional polish.

1. [you, org owner] Developer settings → GitHub Apps → New GitHub App
   • Name: the-open-engine-release (or similar) · Homepage: the repo URL · uncheck the Active webhook.
   • Repository permissions: Contents: Read & write, Issues: Read & write, Pull requests: Read & write, Metadata: Read (default). (Contents = tags/releases/version commit; Issues+PRs = @semantic-release/github success comments.)
   • Install location: Only on this account.
2. Generate a private key (download .pem); note the App ID.
3. Install the App → select only the zeroshot repo.
4. Repo → Settings → Secrets and variables → Actions:
   • RELEASE_APP_ID = the App ID
   • RELEASE_APP_PRIVATE_KEY = full contents of the .pem
   • keep NPM_TOKEN (npm publish is separate — the App does not cover npm).
5. Add the App as a bypass actor on main's ruleset/branch protection (so its minted token can push the chore(release): … [skip ci] commit + tags to protected main).
6. [me] Update release.yml: mint a token via actions/create-github-app-token (app-id/private-key from the secrets), use it as GITHUB_TOKEN for the semantic-release + git steps, and add the main-didn't-move guard (agents-repo pattern) to close the workflow_run race.
7. [you+me] Verify with a workflow_dispatch dry-run before a real release.

---

What's already shipped

• ci: enforce Conventional Commits with a commitlint gate #660 — commitlint gate (validated). Targeted at dev per current rules; folds into the cutover.

Sequencing

C (create App) and B (reconcile) can proceed in parallel; the release.yml App-token wiring + write-back activation should land with or right after the reconciliation, once the App + bypass actor exist. Nothing here touches main until you approve G1–G5.