fix(release): finalize tags after CI publication

Author: osovv

.github/workflows/publish.yml

@@ -14,7 +14,7 @@ on:
 
 permissions:
   id-token: write
-  contents: write
+  contents: read
 
 concurrency:
   group: publish-${{ inputs.version }}
@@ -71,7 +71,6 @@ jobs:
           fi
 
           echo "version=${PKG_VERSION}" >> "${GITHUB_OUTPUT}"
-          echo "tag=${TAG}" >> "${GITHUB_OUTPUT}"
           echo "Release request verified for ${TAG} at ${CURRENT_SHA}"
 
       - name: Install dependencies
@@ -117,45 +116,3 @@ jobs:
           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 config user.name "github-actions[bot]"
-            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-            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: |
-          awk -v ver="$VERSION" '
-            $0 ~ "^## " && $0 ~ ver { found=1; print; next }
-            found && /^## / { exit }
-            found { print }
-          ' CHANGELOG.md > /tmp/release-body.md
-
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
-        with:
-          tag_name: ${{ steps.release.outputs.tag }}
-          body_path: /tmp/release-body.md
-          fail_on_unmatched_files: false
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.grace/context/deployment.xml

@@ -35,11 +35,11 @@
   </ReleaseGates>
   <Publishing>
     <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>
+    <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, then publishes to npm with read-only repository contents access.</Workflow>
+    <LocalBump>bun run release:bump wraps npm version, AI changelog summary generation, schema id patching, release checks, release commit creation, branch-only push, publish.yml dispatch with exact version/SHA inputs, CI waiting, bounded npm metadata retry and gitHead verification, then authenticated local annotated-tag push and GitHub Release creation.</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>
+    <Recovery>A rerun may skip npm publication only when the existing package version gitHead matches the exact requested release SHA; missing tag or GitHub Release finalization is recovered with the maintainer's authenticated local git and gh clients.</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/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, create and push the release commit, then dispatch publish.yml with exact version/SHA inputs without creating a local tag.</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, dispatch and wait for exact-SHA CI publication, retry npm metadata and verify gitHead, then create the annotated tag and GitHub Release locally.</Script>
     <Script name="prepare">Installs lefthook hooks.</Script>
   </Scripts>
   <TestingStack>

.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, 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-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 publication, CI-result waiting, bounded npm metadata retry and gitHead verification, and authenticated local tag/GitHub Release finalization.</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, git CLI, 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 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-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 an exact release commit, dispatches and waits for publish.yml, CI verifies all gates before npm publication, then the local authenticated process retries npm metadata, verifies gitHead, and creates the annotated tag plus GitHub Release.</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>

.grace/verification/main.xml

@@ -14,7 +14,7 @@
       <VF-LAYERED-CONFIG><Flow>DF-LAYERED-CONFIG</Flow><Priority>high</Priority><Expected>vvoc, runtime, and TUI reads choose env, nearest project, global, then defaults where allowed; project writes stay inside selected project root.</Expected></VF-LAYERED-CONFIG>
       <VF-VVOC-LAUNCH><Flow>DF-VVOC-LAUNCH</Flow><Priority>high</Priority><Expected>Launch plan sets OPENCODE_CONFIG and VVOC_CONFIG, conditionally sets OPENCODE_TUI_CONFIG for an existing selected file, forwards args, preserves child exit code, and reports missing project runtime layer with install hint.</Expected></VF-VVOC-LAUNCH>
       <VF-CONTEXT-INSPECTION><Flow>DF-CONTEXT-INSPECTION</Flow><Priority>high</Priority><Expected>/context registers only when enabled, requires an active session, keeps latest provider usage as measured truth, derives percentages only from a positive context limit, reconciles observable current schemas with active post-compaction per-tool history, marks connected MCP schema catalogs unavailable when public OpenCode APIs omit them, attributes MCP tools by unique longest sanitized prefix, fails closed on collisions, renders scrollable Overview/Tools/MCP tabs, and handles missing state without crashing.</Expected></VF-CONTEXT-INSPECTION>
-      <VF-RELEASE-AUTOMATION><Flow>DF-RELEASE</Flow><Priority>high</Priority><Expected>OpenTUI Solid transforms preload before all Bun test discovery; tui:local replaces only the managed package with the local dist export inside an isolated temporary config; release:bump pushes no tag and dispatches publish.yml with exact version/SHA inputs; CI verifies release consistency, typecheck, lint, format, tests, and pack before npm publication, then creates the matching remote tag and GitHub Release; reruns accept existing npm bytes only when gitHead matches the requested SHA.</Expected></VF-RELEASE-AUTOMATION>
+      <VF-RELEASE-AUTOMATION><Flow>DF-RELEASE</Flow><Priority>high</Priority><Expected>OpenTUI Solid transforms preload before all Bun test discovery; tui:local replaces only the managed package with the local dist export inside an isolated temporary config; release:bump pushes no pre-verification tag, dispatches and waits for publish.yml with exact version/SHA inputs; CI verifies release consistency, typecheck, lint, format, tests, and pack before npm publication; the local authenticated process tolerates bounded npm metadata propagation delay and verifies gitHead before creating the matching annotated tag and GitHub Release.</Expected></VF-RELEASE-AUTOMATION>
       <VF-ROLE-MANAGEMENT><Flow>DF-ROLE-MANAGEMENT</Flow><Priority>high</Priority><Expected>Built-in roles are visible, custom roles round-trip, concrete assignments normalize, and built-in role deletion is blocked.</Expected></VF-ROLE-MANAGEMENT>
       <VF-ROLE-RESOLUTION><Flow>DF-ROLE-RESOLUTION</Flow><Priority>high</Priority><Expected>Supported vv-role:* fields resolve to concrete model selections and unknown roles fail without fallback.</Expected></VF-ROLE-RESOLUTION>
       <VF-PRESET-SWITCH><Flow>DF-PRESET-SWITCH</Flow><Priority>high</Priority><Expected>Preset validates all roles and orchestration before one atomic write; custom presets without orchestration preserve the current profile; invalid input leaves original bytes unchanged.</Expected></VF-PRESET-SWITCH>
@@ -33,7 +33,7 @@
       <V-M-MODEL-ROLES><TestFiles><File>src/lib/model-roles.test.ts</File></TestFiles><Checks><Command>bun test src/lib/model-roles.test.ts</Command><Command>bun x tsc --noEmit</Command></Checks></V-M-MODEL-ROLES>
       <V-M-CONFIG-LAYERS><TestFiles><File>src/lib/config-layers.test.ts</File></TestFiles><Checks><Command>bun test src/lib/config-layers.test.ts</Command><Command>bun run typecheck</Command></Checks><Expected>Global/project/effective runtime and TUI sources honor env precedence, json/jsonc selection, and project-local write boundaries.</Expected></V-M-CONFIG-LAYERS>
       <V-M-CLI-CONFIG><TestFiles><File>src/lib/opencode.test.ts</File><File>src/lib/managed-agents.test.ts</File><File>src/commands/sync.test.ts</File></TestFiles><Checks><Command>bun test src/lib/opencode.test.ts src/commands/sync.test.ts</Command><Command>bun run lint</Command><Command>bun run fmt:check</Command></Checks><Expected>Dedicated tui.json(c) mutation writes the pinned base package, migrates legacy subpath specs, preserves comments, unrelated entries, and tuple options; host compatibility, install/sync idempotence, parse state, and registration state are deterministic.</Expected></V-M-CLI-CONFIG>
-      <V-M-RELEASE-AUTOMATION><TestFiles><File>bunfig.toml</File><File>scripts/tui-local.test.ts</File><File>scripts/release-bump.test.ts</File><File>scripts/release-check.test.ts</File><File>scripts/release-summary.test.ts</File></TestFiles><Checks><Command>bun test scripts/tui-local.test.ts scripts/release-bump.test.ts scripts/release-check.test.ts scripts/release-summary.test.ts</Command><Command>bun test src/tui/context/view.test.ts</Command><Command>bun run scripts/check-exports.ts</Command><Command>bun run release:check</Command><Command>bun run typecheck</Command><Command>bun run fmt:check</Command><Command>bun run pack:check</Command></Checks><Expected>The Bun test runner preloads @opentui/solid/preload before test module discovery; local release preparation pushes only the branch and dispatches exact version/SHA inputs; publish.yml is explicit-dispatch-only, orders tests before npm publication and npm publication before remote tag creation, and configures a repository-local GitHub Actions bot identity before creating an annotated tag.</Expected></V-M-RELEASE-AUTOMATION>
+      <V-M-RELEASE-AUTOMATION><TestFiles><File>bunfig.toml</File><File>scripts/tui-local.test.ts</File><File>scripts/release-bump.test.ts</File><File>scripts/release-check.test.ts</File><File>scripts/release-summary.test.ts</File></TestFiles><Checks><Command>bun test scripts/tui-local.test.ts scripts/release-bump.test.ts scripts/release-check.test.ts scripts/release-summary.test.ts</Command><Command>bun test src/tui/context/view.test.ts</Command><Command>bun run scripts/check-exports.ts</Command><Command>bun run release:check</Command><Command>bun run typecheck</Command><Command>bun run fmt:check</Command><Command>bun run pack:check</Command></Checks><Expected>The Bun test runner preloads @opentui/solid/preload before test module discovery; local release preparation pushes only the branch, captures and waits for the exact-SHA workflow run, retries delayed npm metadata, verifies gitHead, and creates the annotated tag/GitHub Release locally; publish.yml is explicit-dispatch-only, read-only for repository contents, and orders tests before npm publication without tag mutation.</Expected></V-M-RELEASE-AUTOMATION>
       <V-M-CLI-MANAGED-AGENTS><TestFiles><File>src/lib/managed-agents.test.ts</File></TestFiles><Checks><Command>bun test src/lib/managed-agents.test.ts</Command><Command>bun x tsc --noEmit</Command></Checks></V-M-CLI-MANAGED-AGENTS>
       <V-M-CLI-MANAGED-SKILLS><TestFiles><File>src/lib/opencode.test.ts</File><File>src/lib/managed-skills.test.ts</File></TestFiles><Checks><Command>bun test src/lib/opencode.test.ts</Command><Command>bun test src/lib/managed-skills.test.ts</Command><Command>bun x tsc --noEmit</Command><Command>bun run lint</Command><Command>bun run fmt:check</Command></Checks></V-M-CLI-MANAGED-SKILLS>
       <V-M-CLI-AGENT-MODELS><TestFiles><File>src/lib/agent-models.test.ts</File></TestFiles><Checks><Command>bun x tsc --noEmit</Command><Command>bun run lint</Command><Command>bun run fmt:check</Command><Command>bun run build</Command></Checks></V-M-CLI-AGENT-MODELS>