chore(release): auto-create GitHub Release on tag publish

.github/workflows/release.yml

@@ -1,6 +1,7 @@
 name: release
 
-# Publishes to npm when a version tag is pushed (v4.0.0, v4.1.0-alpha.1, …).
+# Publishes to npm when a version tag is pushed (v4.0.0, v4.1.0-alpha.1, …),
+# then creates the matching GitHub Release with auto-generated notes.
 # Requires the NPM_TOKEN repository secret (npm "Automation" token: repo
 # Settings → Secrets and variables → Actions → New repository secret).
 # The tag must match package.json's version — the guard below enforces it.
@@ -45,3 +46,23 @@ jobs:
             *-*) pnpm publish --provenance --access public --tag next --no-git-checks ;;
             *)   pnpm publish --provenance --access public --no-git-checks ;;
           esac
+
+  # Runs only after a successful npm publish, so a Release object never exists
+  # for a version that didn't actually ship.
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+      - name: Create GitHub Release (auto-generated notes)
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # mirror the npm dist-tag split: prereleases get the badge and are
+          # excluded from releases/latest; stable versions become Latest
+          case "$GITHUB_REF_NAME" in
+            *-*) gh release create "$GITHUB_REF_NAME" --verify-tag --generate-notes --prerelease ;;
+            *)   gh release create "$GITHUB_REF_NAME" --verify-tag --generate-notes --latest ;;
+          esac

MAINTAINER.md

@@ -245,6 +245,12 @@ Publishing is driven **entirely by pushing a `v*` tag**. `release.yml` re-runs t
 test gate, enforces `tag == package.json version`, and `pnpm publish`es with npm
 provenance. There is no manual `npm publish` step — and you should never run one.
 
+After a successful publish, the workflow's `github-release` job **automatically
+creates the matching GitHub Release** with auto-generated notes. Prereleases are
+flagged `--prerelease` (excluded from `releases/latest`); stable versions are
+marked `--latest` — the same version-shape split as the npm dist-tag. No manual
+`gh release create` step exists anymore.
+
 ### Checklist
 
 ```bash
@@ -273,6 +279,9 @@ gh run watch "$(gh run list --workflow=release.yml -L1 --json databaseId -q '.[0
 # 6. Verify it landed on the right dist-tag.
 npm dist-tag ls @pacphi/agentic-kit
 npm view @pacphi/agentic-kit@4.0.0-alpha.5 version dist.tarball
+
+# 7. Confirm the GitHub Release object was created (automatic, after publish).
+gh release view v4.0.0-alpha.5 --json tagName,isPrerelease
 ```
 
 **The tag↔version guard is unforgiving:** if the tag name and `package.json`
@@ -301,7 +310,7 @@ if a release run fails on the guard, you tagged the wrong string.
 | Workflow | Trigger | What it does | Gate? |
 |----------|---------|--------------|-------|
 | **`ci.yml`** | push to `main`/`npm-kit`, any PR, `workflow_dispatch` | Matrix **3 OS × 3 Node** (ubuntu/macos/windows × 22/24/26): `pnpm test` + CLI smoke against a sandboxed `HOME` | PR merge signal |
-| **`release.yml`** | push tag `v*` | Test gate → **tag↔version guard** → `pnpm publish --provenance` (prerelease→`next`, stable→`latest`) | **Publishes** |
+| **`release.yml`** | push tag `v*` | Test gate → **tag↔version guard** → `pnpm publish --provenance` (prerelease→`next`, stable→`latest`) → **GitHub Release** with generated notes (prerelease-flagged by version shape) | **Publishes** |
 | **`nightly.yml`** | cron `17 6 * * *` (06:17 UTC), `workflow_dispatch` | Installs the **real latest** ruflo + agentic-qe via `npm -g`, runs `ak sync --no-upgrade` + deep proofs; fails on upstream drift in `natives`/`security` | Upstream-drift alarm |
 | **`dependabot.yml`** | weekly, Monday | Grouped bumps: `github-actions` (keeps action majors current) + `npm` (watchdog even though repo is zero-dep) | Opens PRs |
 
@@ -351,12 +360,19 @@ gh secret set NPM_TOKEN                               # rotate the publish token
 gh repo view --web                                    # open on GitHub
 ```
 
-**Optional — GitHub Releases**
-The kit currently ships via npm on tag push and does **not** create GitHub Release
-objects. To add human-readable release notes alongside a tag:
+**GitHub Releases (automated)**
+Every tag push that publishes successfully also creates the GitHub Release
+automatically (`github-release` job in `release.yml`). Manual `gh release`
+commands are only for inspection or repair:
 ```bash
-gh release create v4.0.0-alpha.5 --generate-notes     # after the tag is pushed
+gh release view v4.0.0-alpha.5                        # inspect one
+gh release list --limit 10                            # recent ledger
+# Backfill/repair only — notes bounded to exactly one release:
+gh release create vX --verify-tag --prerelease --generate-notes --notes-start-tag vW
 ```
+Note: `--generate-notes` diffs against the **previous Release object**, not the
+previous tag — a missing Release corrupts the next one's notes window, which is
+why the ledger must stay gap-free (history was backfilled 2026-07-24).
 
 ---