release-proprietary

Create a full Packmind proprietary release with version {{version}}.

This skill orchestrates a cross-repository release that spans the OSS sibling (../packmind, cloned next to the proprietary repo) and the proprietary repo itself (the current working directory). All real release content (version bumps, CHANGELOG) lives on OSS; the proprietary side receives the OSS commit through the oss-sync workflow and gets its own release/{{version}} tag pointing at a different SHA than the OSS tag — see below.

Invocation requirement: run this skill from the root of the proprietary repo, with the OSS sibling checked out at ../packmind. All commands below assume that layout.

Dual-SHA model — important:

• On OSS, the release/{{version}} tag points at the release commit itself (subject chore: release {{version}}). That commit's tree contains OSS code, which is what OSS deployments need.
• On proprietary, the same tag points at the sync-merge commit that brought the OSS release into proprietary main. The OSS release commit has no proprietary-only files in its tree, so tagging it on proprietary would break deployments (the build can't find @packmind/proprietary/* modules). The sync-merge commit's tree combines OSS-at-release with the proprietary-only files, which is what proprietary deployments need.

The wait/tag scripts handle this for you — Phase 2 emits the proprietary merge SHA, and Phase 3 tags that SHA.

Repository layout assumed by every command in this file:

• OSS repo: ../packmind (remote PackmindHub/packmind)
• Proprietary repo: . — the current working directory (remote PackmindHub/packmind-proprietary)

Scripts live next to this file under ./scripts/. From the proprietary repo root, paths are .claude/skills/release-proprietary/scripts/<name>.

Phase 0 — Pre-flight (proprietary repo)

0.1 Feature flags audit gate (MANDATORY)

Before doing anything, stop and ask the user:

Has the feature-flags-audit skill been run on the proprietary repo for this release? (yes / no)

If the answer is anything other than an explicit yes, abort and tell the user to run feature-flags-audit on the proprietary repo first.

If the audit surfaced any loose / stale flags that should have been removed, instruct the user to:

1. Check whether each loose flag also exists in the OSS sibling at ../packmind. Most code flows from OSS → proprietary via oss-sync, so flags should generally be cleaned up on the OSS side.
2. Remove them in OSS first, let the oss-sync workflow land the cleanup on proprietary, then re-invoke this skill.

0.2 No open oss-sync PR

./.claude/skills/release-proprietary/scripts/check-oss-sync-pr.sh PackmindHub/packmind-proprietary

When the auto-sync hits a merge conflict it opens a PR on branch oss-sync instead of fast-forwarding. If such a PR is open, Phase 2 polling cannot succeed. Abort and ask the user to resolve and merge the PR first.

0.3 CI green on both repos

Run the check script for both repositories:

./.claude/skills/release-proprietary/scripts/check-ci.sh PackmindHub/packmind
./.claude/skills/release-proprietary/scripts/check-ci.sh PackmindHub/packmind-proprietary

Exit codes:

• 0 — green, proceed.
• 1 — the run failed (or no run found, or auth missing). Abort, surface the URL.
• 2 — the run is still in progress / queued. Not a failure: ask the user whether to wait and retry, or abort.

0.4 Clean working tree on proprietary and no local divergence

git status --porcelain   # must be empty
git fetch origin main
git merge-base --is-ancestor HEAD origin/main \
  || (echo "local main has diverged from origin/main — reconcile before releasing" && exit 1)

If the working tree is dirty, or local HEAD is not an ancestor of origin/main, abort and ask the user to reconcile.

Phase 1 — Drive the OSS release (../packmind)

All commands in this phase target the OSS repo via git -C or cd.

1.1 Verify clean OSS state and update

git -C ../packmind status --porcelain   # must be empty
git -C ../packmind checkout main
git -C ../packmind pull --ff-only origin main

If the working tree is dirty or the pull is not fast-forward, abort and ask the user to reconcile.

1.2 Bump versions

node ./.claude/skills/release-proprietary/scripts/bump-versions.mjs {{version}} ../packmind
( cd ../packmind && npm install )

npm install regenerates package-lock.json with the new version.

1.3 Rewrite CHANGELOG for release

Resolve today's date in ISO 8601 (YYYY-MM-DD) — call it {{today}}.

node ./.claude/skills/release-proprietary/scripts/changelog-release.mjs {{version}} {{today}} ../packmind

1.4 Commit the release and push main

./.claude/skills/release-proprietary/scripts/commit-release.sh ../packmind {{version}}

This stages package.json, apps/api/docker-package.json, package-lock.json, and CHANGELOG.MD, commits with the exact subject chore: release {{version}} (Phase 2 polls for this fixed string), and pushes main. The script never uses --no-verify.

1.5 Tag the release and push the tag

./.claude/skills/release-proprietary/scripts/tag-release.sh ../packmind {{version}}

Creates release/{{version}} at HEAD (the release commit just pushed) and pushes the tag. If the tag already exists, the script verifies it points at HEAD before re-pushing.

1.6 Prepare next dev cycle on OSS

node ./.claude/skills/release-proprietary/scripts/changelog-next.mjs {{version}} ../packmind
./.claude/skills/release-proprietary/scripts/commit-next-cycle.sh ../packmind

Phase 2 — Wait for oss-sync to land on proprietary

The sync-from-oss-repository.yml workflow on the proprietary repo merges OSS commits into proprietary main automatically (usually under a minute). It will land BOTH the release commit AND the subsequent "prepare next development cycle" commit; each goes through its own sync-merge commit on proprietary main.

PROP_TAG_SHA=$(./.claude/skills/release-proprietary/scripts/wait-for-oss-sync.sh \
  . {{version}})

The script writes the proprietary sync-merge SHA to stdout (captured into PROP_TAG_SHA) and progress to stderr. Internally it:

1. Polls origin/main every 5 seconds for the OSS release commit (subject exactly chore: release {{version}}), with a 10-minute timeout.
2. Once found, locates the proprietary merge commit whose 2nd parent is that OSS commit — that's the upstream side of the sync merge. Requiring the OSS release to be the direct 2nd parent (not a grandparent) ensures the merge's tree is exactly "OSS at release + proprietary state at that moment" — i.e. version {{version}}, not {{next}}-next.

This is the SHA you tag on proprietary. It is NOT the OSS release SHA — that one's tree contains only OSS code and would break proprietary deployments. See the "Dual-SHA model" note at the top.

If it times out, abort and instruct the user to:

• Check the sync-from-oss-repository workflow on PackmindHub/packmind-proprietary.
• Check whether an open oss-sync PR appeared after Phase 0 ran.

If the script reports OSS release commit … is on proprietary origin/main, but no merge commit has it as its direct upstream (2nd) parent, the auto-sync either fast-forwarded or batched release + next-cycle into one merge. The operator must resolve manually before continuing — there is no merge commit with the right tree to tag.

Once PROP_TAG_SHA is set, fast-forward the local proprietary checkout (purely to keep the working tree in sync — we do NOT rely on HEAD for the tag):

git checkout main
git pull --ff-only origin main

Phase 3 — Tag proprietary

3.1 Re-check proprietary CI green

The sync just pushed new commits to proprietary main; the Phase 0 CI gate is now stale. Re-run it (allowing exit 2 = still running) and either wait or abort:

./.claude/skills/release-proprietary/scripts/check-ci.sh PackmindHub/packmind-proprietary

3.2 Tag the proprietary release commit

./.claude/skills/release-proprietary/scripts/tag-release.sh \
  . {{version}} "${PROP_TAG_SHA}"

Passing the SHA explicitly is essential — tagging HEAD would tag a later sync-merge or the next-cycle commit. The script re-verifies that the target is either a direct release commit OR a merge commit whose 2nd parent is the release commit, and refuses to tag otherwise. It will not allow retagging an existing tag at a different commit.

3.3 Done

Report to the user:

• OSS release commit URL: https://github.com/PackmindHub/packmind/releases/tag/release/{{version}} (or the compare link)
• Proprietary tag URL: https://github.com/PackmindHub/packmind-proprietary/releases/tag/release/{{version}}
• Reminder: any deployment workflow that watches release/* tags will trigger.

Important notes

• Do NOT use --no-verify on any commit. If a hook fails, fix the root cause and create a new commit.
• The release commit subject MUST be exactly chore: release {{version}} — Phase 2 matches subjects by exact equality and tag-release.sh verifies subject equality before tagging. Any prefix/suffix (e.g. gitmoji) will break the flow.
• Date format MUST be ISO 8601 (YYYY-MM-DD).
• Verify each commit and push succeeded before proceeding to the next step.
• If anything fails mid-way after the OSS tag is pushed, do NOT delete the OSS tag — coordinate a follow-up patch release instead.

Recovery cheatsheet

If the flow fails at a known phase, recover as follows:

• After 1.4, before 1.5 (release commit pushed, no OSS tag yet): re-run tag-release.sh <oss-dir> {{version}} from Phase 1.5. The script tags HEAD only if HEAD's subject is chore: release {{version}}.
• After 1.5, before 1.6 (OSS is tagged, no next-cycle commit): re-run changelog-next.mjs + commit-next-cycle.sh. Then proceed to Phase 2.
• After 1.6, Phase 2 timed out: investigate the sync workflow / oss-sync PR. Once unstuck, re-run only Phase 2 + Phase 3.
• After Phase 3 failure (OSS tagged, proprietary not tagged): once any blocker is cleared, re-run only Phase 3, passing the same PROP_TAG_SHA. Recover it by re-running wait-for-oss-sync.sh (idempotent — it finds and emits the same merge SHA as before) or manually with:

  OSS_SHA=$(git log origin/main \
    --format='%H%x09%s' -500 | awk -F '\t' -v subj="chore: release {{version}}" '$2 == subj { print $1; exit }')
  git log origin/main --merges \
    --format='%H %P' -500 | awk -v oss="${OSS_SHA}" '$3 == oss { print $1; exit }'