fix(release): gate publishing and tags behind CI

Author: osovv

.github/workflows/publish.yml

@@ -1,23 +1,33 @@
 name: publish
 
 on:
-  push:
-    tags:
-      - "v*"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Package version to verify and publish"
+        required: true
+        type: string
+      commit_sha:
+        description: "Exact release commit SHA to verify and publish"
+        required: true
+        type: string
 
 permissions:
   id-token: write
   contents: write
 
 concurrency:
-  group: publish-${{ github.ref }}
+  group: publish-${{ inputs.version }}
   cancel-in-progress: false
 
 jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.commit_sha }}
+          fetch-depth: 0
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
@@ -30,15 +40,39 @@ jobs:
         with:
           bun-version: 1.3.8
 
-      - name: Verify tag matches package version
+      - name: Verify release request
+        id: release
+        env:
+          REQUESTED_VERSION: ${{ inputs.version }}
+          REQUESTED_SHA: ${{ inputs.commit_sha }}
         run: |
-          TAG="${GITHUB_REF_NAME}"
+          set -euo pipefail
           PKG_VERSION="$(node -p "require('./package.json').version")"
-          if [ "v${PKG_VERSION}" != "${TAG}" ]; then
-            echo "Tag ${TAG} does not match package.json version v${PKG_VERSION}"
+          CURRENT_SHA="$(git rev-parse HEAD)"
+          TAG="v${PKG_VERSION}"
+
+          if [ "${PKG_VERSION}" != "${REQUESTED_VERSION}" ]; then
+            echo "Requested version ${REQUESTED_VERSION} does not match package.json version ${PKG_VERSION}"
+            exit 1
+          fi
+          if [ "${CURRENT_SHA}" != "${REQUESTED_SHA}" ]; then
+            echo "Checked out SHA ${CURRENT_SHA} does not match requested SHA ${REQUESTED_SHA}"
             exit 1
           fi
-          echo "Tag ${TAG} matches package.json version v${PKG_VERSION}"
+
+          git fetch --force --tags origin
+          if git rev-parse --verify --quiet "refs/tags/${TAG}" >/dev/null; then
+            TAG_SHA="$(git rev-list -n 1 "${TAG}")"
+            if [ "${TAG_SHA}" != "${CURRENT_SHA}" ]; then
+              echo "Existing tag ${TAG} points to ${TAG_SHA}, expected ${CURRENT_SHA}"
+              exit 1
+            fi
+            echo "Existing tag ${TAG} already points to the requested release commit"
+          fi
+
+          echo "version=${PKG_VERSION}" >> "${GITHUB_OUTPUT}"
+          echo "tag=${TAG}" >> "${GITHUB_OUTPUT}"
+          echo "Release request verified for ${TAG} at ${CURRENT_SHA}"
 
       - name: Install dependencies
         run: bun install --frozen-lockfile
@@ -62,12 +96,53 @@ jobs:
         run: bun run pack:check
 
       - name: Publish to npm
-        run: npm publish --access public
+        env:
+          RELEASE_VERSION: ${{ steps.release.outputs.version }}
+        run: |
+          set -euo pipefail
+          PACKAGE_NAME="@osovv/vv-opencode"
+          CURRENT_SHA="$(git rev-parse HEAD)"
+
+          if PUBLISHED_SHA="$(npm view "${PACKAGE_NAME}@${RELEASE_VERSION}" gitHead 2>/dev/null)"; then
+            PUBLISHED_SHA="$(printf '%s' "${PUBLISHED_SHA}" | tr -d '[:space:]')"
+            if [ -z "${PUBLISHED_SHA}" ]; then
+              echo "${PACKAGE_NAME}@${RELEASE_VERSION} already exists but has no gitHead metadata"
+              exit 1
+            fi
+            if [ "${PUBLISHED_SHA}" != "${CURRENT_SHA}" ]; then
+              echo "${PACKAGE_NAME}@${RELEASE_VERSION} was published from ${PUBLISHED_SHA}, expected ${CURRENT_SHA}"
+              exit 1
+            fi
+            echo "${PACKAGE_NAME}@${RELEASE_VERSION} is already published from the requested commit; continuing"
+          else
+            npm publish --access public --provenance
+          fi
+
+      - name: Create and push release tag
+        env:
+          TAG: ${{ steps.release.outputs.tag }}
+        run: |
+          set -euo pipefail
+          CURRENT_SHA="$(git rev-parse HEAD)"
+          git fetch --force --tags origin
+
+          if git rev-parse --verify --quiet "refs/tags/${TAG}" >/dev/null; then
+            TAG_SHA="$(git rev-list -n 1 "${TAG}")"
+            if [ "${TAG_SHA}" != "${CURRENT_SHA}" ]; then
+              echo "Existing tag ${TAG} points to ${TAG_SHA}, expected ${CURRENT_SHA}"
+              exit 1
+            fi
+            echo "Tag ${TAG} already points to ${CURRENT_SHA}; skipping tag push"
+          else
+            git tag -a "${TAG}" -m "${TAG}"
+            git push origin "${TAG}"
+          fi
 
       - name: Extract changelog entry for release
         id: changelog
+        env:
+          VERSION: ${{ steps.release.outputs.version }}
         run: |
-          VERSION="${GITHUB_REF_NAME#v}"
           awk -v ver="$VERSION" '
             $0 ~ "^## " && $0 ~ ver { found=1; print; next }
             found && /^## / { exit }
@@ -77,7 +152,7 @@ jobs:
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
-          tag_name: ${{ github.ref_name }}
+          tag_name: ${{ steps.release.outputs.tag }}
           body_path: /tmp/release-body.md
           fail_on_unmatched_files: false
         env:

.grace/context/deployment.xml

@@ -34,11 +34,12 @@
     <Command>bun run release:check</Command>
   </ReleaseGates>
   <Publishing>
-    <Policy>Publishing is tag-gated through .github/workflows/publish.yml after a local bun run release:bump prepares and pushes the release commit and v* tag.</Policy>
-    <Workflow>.github/workflows/publish.yml verifies the tag, release consistency, typecheck, lint, format, tests, pack check, then publishes to npm and creates a GitHub Release.</Workflow>
-    <LocalBump>bun run release:bump wraps npm version, AI changelog summary generation, schema id patching, release checks, release commit, tag creation, and push.</LocalBump>
+    <Policy>Publishing is exact-commit and CI-gated through an explicit publish.yml workflow dispatch; normal branch and tag pushes never publish.</Policy>
+    <Workflow>.github/workflows/publish.yml checks out the requested release SHA, verifies version and existing tag/package identity, runs release consistency, typecheck, lint, format, tests, and pack checks, publishes to npm, then creates the annotated tag and GitHub Release.</Workflow>
+    <LocalBump>bun run release:bump wraps npm version, AI changelog summary generation, schema id patching, release checks, release commit creation, branch-only push, and publish.yml dispatch with exact version/SHA inputs; it never creates or pushes the release tag locally.</LocalBump>
     <TrustedPublishing>The workflow uses npm provenance/trusted publishing through id-token permissions.</TrustedPublishing>
     <NormalPushes>Normal branch pushes must not publish the package.</NormalPushes>
+    <Recovery>A rerun may skip npm publication only when the existing package version gitHead matches the exact requested release SHA, then safely recover tag or GitHub Release creation.</Recovery>
   </Publishing>
   <Rollback>
     <Expectation>Package rollback is managed by npm version selection and by rerunning vvoc sync or fixing vvoc.json manually when strict config validation blocks mutation.</Expectation>

.grace/context/requirements.xml

@@ -194,6 +194,7 @@
     <Constraint>Project-owned specs and plans produced by vvoc skills live under date-prefixed package directories .vvoc/specs/YYYY-MM-DD-&lt;slug&gt;/.</Constraint>
     <Constraint>Hashline-backed editing must fail safely on stale or malformed edit references instead of applying ambiguous line-based changes.</Constraint>
     <Constraint>Package exports are public API and must remain valid unless an explicit breaking change is approved.</Constraint>
+    <Constraint>Release automation must verify the exact release commit in CI before npm publication, and it must not create or push the release tag until publication succeeds.</Constraint>
     <Constraint>After the 1.0 stabilization point, user-facing setup flow, managed skill names, canonical vvoc schema v3, public package exports, and spec package layout changes must be release-noted as compatibility-relevant changes.</Constraint>
   </Constraints>
   <Risks>

.grace/context/technology.xml

@@ -62,7 +62,7 @@
     <Script name="check">Runs typecheck, lint, fmt:check, and tests.</Script>
     <Script name="pack:check">Builds dist, verifies root, server plugin, and default TUI subpath exports by importing generated files, then runs npm pack --dry-run.</Script>
     <Script name="release:check">Runs scripts/release-check.ts to validate package identity, package version, hosted schema id, schema config const, changelog presence, and latest changelog summary.</Script>
-    <Script name="release:bump">Runs scripts/release-bump.ts to guard a clean worktree, bump version, generate changelog, generate required AI release summary, update schema id, run release:check, commit, tag, and push.</Script>
+    <Script name="release:bump">Runs scripts/release-bump.ts to guard a clean worktree, bump version, generate changelog, generate required AI release summary, update schema id, run release:check, create and push the release commit, then dispatch publish.yml with exact version/SHA inputs without creating a local tag.</Script>
     <Script name="prepare">Installs lefthook hooks.</Script>
   </Scripts>
   <TestingStack>
@@ -100,7 +100,7 @@
     <Constraint>Do not edit generated dist output manually.</Constraint>
     <Constraint>Root package exports and plugin subpath exports must stay valid unless an explicit breaking change is approved.</Constraint>
     <Constraint>OpenCode TUI integration requires OpenCode 1.18.2 or newer and a default TuiPluginModule export selected from the pinned base package registered in tui.json(c).</Constraint>
-    <Constraint>Publishing remains manual from terminal with npm publish; normal branch pushes must not publish the package.</Constraint>
+    <Constraint>Publishing requires an explicit exact-SHA GitHub Actions workflow dispatch; normal branch and tag pushes must not publish the package, and the release tag is created only after CI gates and npm publication succeed.</Constraint>
     <Constraint>README, .grace/graph, and .grace/verification must be updated with behavior, public API, setup, command, flow, or verification changes as applicable.</Constraint>
   </OperationalConstraints>
 </GraceTechnology>

.grace/graph/main.xml

@@ -5,7 +5,7 @@
       <M-MODEL-ROLES><Name>ModelRoles</Name><Type>CORE_LOGIC</Type><Status>implemented</Status><Purpose>Define built-in role IDs, vv-role:* syntax, model-selection parsing, role normalization, resolution helpers, and built-in agent role bindings.</Purpose><Paths>src/lib/model-roles.ts</Paths><Depends>none</Depends><Verification>V-M-MODEL-ROLES</Verification></M-MODEL-ROLES>
       <M-CONFIG-LAYERS><Name>ConfigLayers</Name><Type>UTILITY</Type><Status>implemented</Status><Purpose>Resolve vvoc, OpenCode runtime, and dedicated OpenCode TUI config sources across env, project, global, and defaults plus project/global write targets.</Purpose><Paths>src/lib/config-layers.ts, src/lib/vvoc-paths.ts</Paths><Depends>none</Depends><Verification>V-M-CONFIG-LAYERS</Verification></M-CONFIG-LAYERS>
       <M-CLI-CONFIG><Name>OpenCodeConfigTools</Name><Type>UTILITY</Type><Status>implemented</Status><Purpose>Mutate OpenCode runtime/TUI and vvoc config conservatively, pin base package registrations, migrate legacy TUI subpath specs, preserve tuple options, inspect OpenCode host compatibility, write managed agent/skill registrations, and render strict schema v3.</Purpose><Paths>src/lib/opencode.ts, src/lib/package.ts, src/lib/vvoc-config.ts, src/lib/model-roles.ts, src/lib/vvoc-paths.ts, schemas/vvoc/v3.json</Paths><Depends>M-CONFIG-LAYERS, M-MODEL-ROLES, M-VVOC-PRESET-REGISTRY, M-CLI-MANAGED-AGENTS, M-CLI-MANAGED-SKILLS, M-CLI-AGENT-MODELS</Depends><Verification>V-M-CLI-CONFIG</Verification></M-CLI-CONFIG>
-      <M-RELEASE-AUTOMATION><Name>ReleaseAutomation</Name><Type>SCRIPT</Type><Status>implemented</Status><Purpose>Guard package exports and releases with source-path checks, isolated local TUI smoke launches, local version bumping, AI changelog summary generation, schema id consistency, release checks, and tag-gated publish workflow.</Purpose><Paths>scripts/check-exports.ts, scripts/tui-local.ts, scripts/release-bump.ts, scripts/release-check.ts, scripts/release-summary.ts, .github/workflows/publish.yml, schemas/vvoc/v3.json</Paths><Depends>M-CLI-CONFIG, M-CLI-COMMANDS</Depends><Verification>V-M-RELEASE-AUTOMATION</Verification></M-RELEASE-AUTOMATION>
+      <M-RELEASE-AUTOMATION><Name>ReleaseAutomation</Name><Type>SCRIPT</Type><Status>implemented</Status><Purpose>Guard package exports and releases with source-path checks, deterministic OpenTUI Solid test preloading, isolated local TUI smoke launches, local version bumping, AI changelog summary generation, schema id consistency, exact-SHA CI dispatch, verification-before-publication, and post-publication tag creation.</Purpose><Paths>bunfig.toml, scripts/check-exports.ts, scripts/tui-local.ts, scripts/release-bump.ts, scripts/release-bump.test.ts, scripts/release-check.ts, scripts/release-summary.ts, .github/workflows/publish.yml, schemas/vvoc/v3.json</Paths><Depends>M-CLI-CONFIG, M-CLI-COMMANDS, @opentui/solid, gh CLI, GitHub Actions, npm trusted publishing</Depends><Verification>V-M-RELEASE-AUTOMATION</Verification></M-RELEASE-AUTOMATION>
       <M-CLI-MANAGED-AGENTS><Name>ManagedAgents</Name><Type>UTILITY</Type><Status>implemented</Status><Purpose>Define bundled vv-controller, enhancer, guardian, investigator, vv-implementer, vv-spec-reviewer, and vv-code-reviewer templates and load managed prompt text.</Purpose><Paths>src/lib/managed-agents.ts, templates/agents/*.md</Paths><Depends>M-CLI-CONFIG</Depends><Verification>V-M-CLI-MANAGED-AGENTS</Verification></M-CLI-MANAGED-AGENTS>
       <M-CLI-MANAGED-SKILLS><Name>ManagedSkills</Name><Type>UTILITY</Type><Status>implemented</Status><Purpose>Define bundled vv-spec, vv-plan, vv-review, vv-execute, vv-reflect, and vv-handoff skill templates and reference loading.</Purpose><Paths>src/lib/managed-skills.ts, templates/skills/**/SKILL.md</Paths><Depends>M-CLI-CONFIG</Depends><Verification>V-M-CLI-MANAGED-SKILLS</Verification></M-CLI-MANAGED-SKILLS>
       <M-CLI-AGENT-MODELS><Name>AgentModels</Name><Type>UTILITY</Type><Status>implemented</Status><Purpose>Define supported vvoc model target IDs and shared model override validation helpers retained for current command and config compatibility.</Purpose><Paths>src/lib/agent-models.ts</Paths><Depends>M-CLI-MANAGED-AGENTS</Depends><Verification>V-M-CLI-AGENT-MODELS</Verification></M-CLI-AGENT-MODELS>
@@ -40,7 +40,7 @@
       <DF-CONFIG-SYNC>vvoc sync strict-parses current vvoc config, preserves valid role/plugin values and unrelated TUI JSONC entries, refreshes managed presets/prompts/skills, and rewrites managed runtime/TUI registrations.</DF-CONFIG-SYNC>
       <DF-LAYERED-CONFIG>Commands and runtime resolve vvoc, OpenCode runtime, and OpenCode TUI env overrides, nearest project layer, global layer, then defaults where permitted.</DF-LAYERED-CONFIG>
       <DF-VVOC-LAUNCH>vvoc launch selects OpenCode runtime and vvoc config paths, conditionally pins an existing TUI config with OPENCODE_TUI_CONFIG, forwards passthrough args, and preserves child exit code.</DF-VVOC-LAUNCH>
-      <DF-RELEASE>tui:local builds and injects the local TUI export through an isolated temporary config for pre-release smoke testing; release:bump and publish workflow then verify package/schema/changelog consistency before publishing.</DF-RELEASE>
+      <DF-RELEASE>tui:local builds and injects the local TUI export through an isolated temporary config for pre-release smoke testing; release:bump creates and pushes only an exact release commit, dispatches publish.yml with its version and SHA, and CI verifies all gates before npm publication, remote tag creation, and GitHub Release creation.</DF-RELEASE>
       <DF-ROLE-MANAGEMENT>role list/set/unset loads selected vvoc config, validates role IDs, normalizes assignments, writes role map, or renders inventory.</DF-ROLE-MANAGEMENT>
       <DF-ROLE-RESOLUTION>ModelRolesPlugin loads role map, scans supported model fields, resolves vv-role:* references, splits variants where safe, and fails loudly for unknown roles.</DF-ROLE-RESOLUTION>
       <DF-PRESET-SWITCH>Preset command reads presets, validates selected name, normalizes role and orchestration assignments, applies declared fields atomically, and leaves OpenCode config untouched.</DF-PRESET-SWITCH>