From a3bfd9acb3e5961eb05fe5b43ddb8e14805a3b4a Mon Sep 17 00:00:00 2001
From: Anand Pant <anand@testcompare.ai>
Date: Sat, 28 Feb 2026 00:53:06 -0600
Subject: [PATCH] Harden release flow verification and docs

---
 .github/workflows/publish-package.yml | 26 +++++++++
 README.md                             |  5 ++
 RELEASE.md                            | 81 +++++++++++++++++++++++++++
 3 files changed, 112 insertions(+)
 create mode 100644 RELEASE.md

diff --git a/.github/workflows/publish-package.yml b/.github/workflows/publish-package.yml
index 4a3aa17..7ad6c79 100644
--- a/.github/workflows/publish-package.yml
+++ b/.github/workflows/publish-package.yml
@@ -234,6 +234,32 @@ jobs:
           npm publish --registry https://npm.pkg.github.com --tag "${{ steps.meta.outputs.publish_tag }}"
           echo "published=true" >> "$GITHUB_OUTPUT"
 
+      - name: Verify published dist-tag
+        if: steps.publish.outputs.published == 'true'
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          PACKAGE_NAME="${{ steps.meta.outputs.name }}"
+          PUBLISH_TAG="${{ steps.meta.outputs.publish_tag }}"
+          EXPECTED_VERSION="${{ steps.meta.outputs.publish_version }}"
+
+          for attempt in 1 2 3 4 5 6; do
+            ACTUAL_VERSION="$(npm view "$PACKAGE_NAME" "dist-tags.${PUBLISH_TAG}" --registry https://npm.pkg.github.com 2>/dev/null || true)"
+
+            if [ "$ACTUAL_VERSION" = "$EXPECTED_VERSION" ]; then
+              echo "Verified dist-tag ${PUBLISH_TAG}: ${PACKAGE_NAME}@${ACTUAL_VERSION}"
+              exit 0
+            fi
+
+            if [ "$attempt" -eq 6 ]; then
+              echo "Dist-tag verification failed for ${PACKAGE_NAME}" >&2
+              echo "Expected ${PUBLISH_TAG} -> ${EXPECTED_VERSION}, found '${ACTUAL_VERSION}'" >&2
+              exit 1
+            fi
+
+            sleep 5
+          done
+
       - name: Verify registry install
         if: steps.publish.outputs.published == 'true'
         env:
diff --git a/README.md b/README.md
index 6c3265c..30b7694 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,7 @@ This project automates Daytona sandbox setup and OpenCode execution.
 - [Repository Audit Workflow](#repository-audit-workflow)
 - [Output Layout](#output-layout)
 - [Release Automation](#release-automation)
+- [Release Process](#release-process)
 - [Development](#development)
 - [Compatibility Notes](#compatibility-notes)
 
@@ -199,6 +200,10 @@ bun run analyze -- --input example.md --out-dir findings-confidence-3 --analyze-
 - Normal PR merges publish a prerelease for the next patch with npm tag `next` (for example `0.0.2-next.<run>.<attempt>.<sha>`), then keep/create a draft bump PR (for example `0.0.1 -> 0.0.2`).
 - Merging the automated bump PR publishes that bumped version as the public release (`latest`) and does not create another `.next` publish.
 
+## Release Process
+
+Release operations, required repo settings, verification commands, and rollback steps are documented in [`RELEASE.md`](RELEASE.md).
+
 ---
 
 ## Development
diff --git a/RELEASE.md b/RELEASE.md
new file mode 100644
index 0000000..cba74a6
--- /dev/null
+++ b/RELEASE.md
@@ -0,0 +1,81 @@
+# Release Process
+
+This project publishes to GitHub Packages, not npmjs.org.
+
+- Registry: `https://npm.pkg.github.com`
+- Package: `@shpitdev/opencode-sandboxed-ad-hoc-research`
+- Tags:
+  - `next` for prerelease validation builds
+  - `latest` for stable public installs
+
+## Automated Flow
+
+Workflow: `.github/workflows/publish-package.yml`
+
+1. Any merge to `main` triggers publish automation.
+2. The workflow resolves the merged PR context:
+   - Normal PR merge:
+     - publishes `0.0.(x+1)-next.<run>.<attempt>.<sha>` with npm tag `next`
+     - opens or updates draft bump PR `ci/version-bump-0.0.(x+1)`
+   - Bump PR merge (`ci/version-bump-0.0.x`):
+     - publishes `0.0.x` with npm tag `latest`
+     - does not create another bump PR
+3. The workflow verifies:
+   - dist-tag points to the just-published version
+   - clean install from GitHub Packages into a fresh project
+   - installed CLI binaries execute (`--help`)
+
+## Required Repository Configuration
+
+- GitHub Actions:
+  - `GITHUB_TOKEN` must keep `contents:write`, `pull-requests:write`, `packages:write` permissions in `publish-package.yml`.
+- Optional token:
+  - `GH_PAT` can be set to let `create-pull-request` use a PAT instead of `GITHUB_TOKEN`.
+- Branch governance:
+  - Keep required checks enforced for PRs into `main`:
+    - `Check`
+    - `ValidatePrTitle`
+    - `CodeQL`
+
+## Verify Current Published State
+
+```bash
+# requires a token with read:packages
+export NODE_AUTH_TOKEN="<token>"
+
+npm view @shpitdev/opencode-sandboxed-ad-hoc-research dist-tags --registry https://npm.pkg.github.com
+npm view @shpitdev/opencode-sandboxed-ad-hoc-research versions --json --registry https://npm.pkg.github.com
+```
+
+## Rollback Playbook
+
+### Wrong `latest` version
+
+Point `latest` back to a known-good version:
+
+```bash
+export NODE_AUTH_TOKEN="<token with packages:write>"
+npm dist-tag add @shpitdev/opencode-sandboxed-ad-hoc-research@0.0.<good> latest --registry https://npm.pkg.github.com
+```
+
+### Wrong `next` version
+
+Point `next` to a known-good prerelease or stable version:
+
+```bash
+export NODE_AUTH_TOKEN="<token with packages:write>"
+npm dist-tag add @shpitdev/opencode-sandboxed-ad-hoc-research@0.0.<good>-next.<build> next --registry https://npm.pkg.github.com
+```
+
+### Bad version must be removed
+
+Delete the package version from GitHub Packages (org package settings or API) using a token with package delete privileges.
+
+## Manual Recovery Steps
+
+1. Revert incorrect code on a PR and merge to `main`.
+2. If needed, retag `next`/`latest` first to stop new installs from pulling bad builds.
+3. Confirm dist-tags and install:
+   - `npm view ... dist-tags`
+   - install into clean temp project
+4. Keep bump PR (`ci/version-bump-*`) aligned with intended next stable patch.