@intelmesh/sdk 0.1.0

package/docs/superpowers/plans/2026-04-10-release-pipeline.md

@@ -0,0 +1,798 @@
+# Release Pipeline Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship a GitHub Actions workflow that publishes `@intelmesh/sdk` to npm (with provenance) and creates a GitHub Release on every signed semver tag, with signature verification of both the commit and the annotated tag object as a hard gate.
+
+**Architecture:** Single workflow file (`.github/workflows/release.yml`) with four sequential jobs chained via `needs:` — `verify-signature` → `test` (Node 20/22/24 matrix) → `publish-npm` → `github-release`. The npm dist-tag logic is extracted into a standalone bash script (`.github/scripts/compute-disttag.sh`) with vitest unit tests, so the trickiest piece of the pipeline is deterministically covered before any tag is pushed.
+
+**Tech Stack:** GitHub Actions, `gh` CLI (pre-installed on runners), `npm publish --provenance`, actionlint (binary, downloaded ad-hoc for local validation), vitest (already in the repo), bash.
+
+**Reference spec:** `docs/superpowers/specs/2026-04-10-release-pipeline-design.md` (all design decisions live there; this plan implements them literally).
+
+**User preference — important:** Do NOT `git add` or commit anything under `docs/`. The plan document itself is not committed. Code changes outside `docs/` are committed normally.
+
+---
+
+## File Structure
+
+| File | State | Responsibility |
+|---|---|---|
+| `package.json` | modify | Add missing `repository` field (required for npm provenance). |
+| `.gitignore` | modify | Ignore `.tools/` directory where local actionlint binary is downloaded. |
+| `.github/scripts/compute-disttag.sh` | create | Pure bash: read `GITHUB_REF_NAME`, emit `version`, `disttag`, `is_prerelease` to `GITHUB_OUTPUT`. No dependencies. Testable. |
+| `tests/scripts/compute-disttag.test.ts` | create | Vitest test that execs the bash script in a temp dir and asserts outputs for stable/beta/rc/alpha/next and no-dot-suffix cases. |
+| `.github/workflows/release.yml` | create | Single-file workflow: trigger, permissions, concurrency, and four jobs. |
+
+---
+
+## Task 1: Prerequisites — `repository` field and `.gitignore` entry
+
+**Context:** `npm publish --provenance` requires `package.json` to have a `repository` field pointing to the GitHub repo — the published package's provenance attestation links back to this URL. We also prep `.gitignore` for the actionlint binary we'll download in Task 3.
+
+**Files:**
+- Modify: `package.json`
+- Modify: `.gitignore`
+
+- [ ] **Step 1.1: Read current `package.json`**
+
+Run: `cat package.json` (using Read tool in agent).
+
+Confirm: no `"repository"` key exists at the top level.
+
+- [ ] **Step 1.2: Add `repository` field to `package.json`**
+
+Add this block right after the `"license": "MIT",` line:
+
+```json
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/intelmesh/intelmesh-sdk-ts.git"
+  },
+  "homepage": "https://github.com/intelmesh/intelmesh-sdk-ts#readme",
+  "bugs": {
+    "url": "https://github.com/intelmesh/intelmesh-sdk-ts/issues"
+  },
+```
+
+The final ordering should place `repository`, `homepage`, `bugs` right after `license` and before `devDependencies`. Preserve existing formatting (2-space indent, trailing comma style of surrounding code).
+
+- [ ] **Step 1.3: Validate JSON is still parseable**
+
+Run: `node -e "JSON.parse(require('fs').readFileSync('package.json','utf8')); console.log('ok')"`
+Expected output: `ok`
+
+- [ ] **Step 1.4: Append `.tools/` to `.gitignore`**
+
+Edit `.gitignore`, add a new block at the end:
+
+```
+# Local tooling binaries (actionlint, etc)
+.tools/
+```
+
+- [ ] **Step 1.5: Commit**
+
+```bash
+git add package.json .gitignore
+git commit -m "chore: add repository metadata for npm provenance
+
+Adds repository, homepage, and bugs fields required by
+npm publish --provenance to attach Sigstore attestation,
+and ignores .tools/ where actionlint will be downloaded
+for local workflow validation."
+```
+
+---
+
+## Task 2: Extract `compute-disttag.sh` with TDD
+
+**Context:** The dist-tag computation (`v1.2.3` → `latest`, `v1.2.3-beta.1` → `beta`, etc.) is the most logic-heavy piece of the workflow. Extract it to a standalone bash script so it can be unit-tested with vitest before being wired into the YAML. The script reads `GITHUB_REF_NAME` and writes to `GITHUB_OUTPUT` — identical ABI to an inline workflow step, just testable.
+
+**Files:**
+- Create: `.github/scripts/compute-disttag.sh`
+- Create: `tests/scripts/compute-disttag.test.ts`
+
+- [ ] **Step 2.1: Write the failing test**
+
+Create `tests/scripts/compute-disttag.test.ts`:
+
+```typescript
+import { describe, expect, it } from 'vitest';
+// eslint-disable-next-line security/detect-child-process
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+interface ScriptOutput {
+  version: string;
+  disttag: string;
+  is_prerelease: string;
+}
+
+function parseOutput(raw: string): ScriptOutput {
+  const map: Record<string, string> = {};
+  for (const line of raw.split('\n')) {
+    const idx = line.indexOf('=');
+    if (idx === -1) continue;
+    map[line.slice(0, idx)] = line.slice(idx + 1);
+  }
+  return {
+    version: map.version ?? '',
+    disttag: map.disttag ?? '',
+    is_prerelease: map.is_prerelease ?? '',
+  };
+}
+
+function runScript(refName: string): ScriptOutput {
+  const dir = mkdtempSync(join(tmpdir(), 'disttag-'));
+  const outputFile = join(dir, 'github_output');
+  writeFileSync(outputFile, '');
+  const result = spawnSync('bash', ['.github/scripts/compute-disttag.sh'], {
+    env: {
+      ...process.env,
+      GITHUB_REF_NAME: refName,
+      GITHUB_OUTPUT: outputFile,
+    },
+    encoding: 'utf-8',
+  });
+  if (result.status !== 0) {
+    throw new Error(
+      `Script failed (status=${String(result.status)}): ${result.stderr}`,
+    );
+  }
+  return parseOutput(readFileSync(outputFile, 'utf-8'));
+}
+
+describe('compute-disttag.sh', () => {
+  it('stable v1.2.3 resolves to latest', () => {
+    const out = runScript('v1.2.3');
+    expect(out.version).toBe('1.2.3');
+    expect(out.disttag).toBe('latest');
+    expect(out.is_prerelease).toBe('false');
+  });
+
+  it('v1.2.3-beta.1 resolves to beta dist-tag', () => {
+    const out = runScript('v1.2.3-beta.1');
+    expect(out.version).toBe('1.2.3-beta.1');
+    expect(out.disttag).toBe('beta');
+    expect(out.is_prerelease).toBe('true');
+  });
+
+  it('v1.2.3-rc.2 resolves to rc dist-tag', () => {
+    const out = runScript('v1.2.3-rc.2');
+    expect(out.disttag).toBe('rc');
+    expect(out.is_prerelease).toBe('true');
+  });
+
+  it('v2.0.0-alpha.7 resolves to alpha dist-tag', () => {
+    const out = runScript('v2.0.0-alpha.7');
+    expect(out.disttag).toBe('alpha');
+    expect(out.is_prerelease).toBe('true');
+  });
+
+  it('v2.0.0-next.0 resolves to next dist-tag', () => {
+    const out = runScript('v2.0.0-next.0');
+    expect(out.disttag).toBe('next');
+    expect(out.is_prerelease).toBe('true');
+  });
+
+  it('v1.0.0-beta without dot suffix resolves to beta', () => {
+    const out = runScript('v1.0.0-beta');
+    expect(out.version).toBe('1.0.0-beta');
+    expect(out.disttag).toBe('beta');
+    expect(out.is_prerelease).toBe('true');
+  });
+});
+```
+
+- [ ] **Step 2.2: Run the test — verify it fails because the script does not exist**
+
+Run: `npm test -- tests/scripts/compute-disttag.test.ts`
+
+Expected: all 6 tests fail with an error like `Script failed (status=127): bash: .github/scripts/compute-disttag.sh: No such file or directory`.
+
+- [ ] **Step 2.3: Create the script**
+
+Create `.github/scripts/compute-disttag.sh`:
+
+```bash
+#!/usr/bin/env bash
+# Compute npm dist-tag and prerelease flag from a git tag name.
+#
+# Reads (env):
+#   GITHUB_REF_NAME  git tag name, e.g. "v1.2.3" or "v1.2.3-beta.1"
+#   GITHUB_OUTPUT    path to GitHub Actions step output file
+#
+# Writes to $GITHUB_OUTPUT:
+#   version          semver without leading "v"
+#   disttag          npm dist-tag ("latest" for stable, suffix prefix otherwise)
+#   is_prerelease    "true" for any tag with a "-" suffix, else "false"
+
+set -euo pipefail
+
+tag="${GITHUB_REF_NAME:?GITHUB_REF_NAME is required}"
+: "${GITHUB_OUTPUT:?GITHUB_OUTPUT is required}"
+
+version="${tag#v}"
+
+if [[ "$version" == *-* ]]; then
+  suffix="${version#*-}"
+  disttag="${suffix%%.*}"
+  is_prerelease=true
+else
+  disttag="latest"
+  is_prerelease=false
+fi
+
+{
+  echo "version=$version"
+  echo "disttag=$disttag"
+  echo "is_prerelease=$is_prerelease"
+} >> "$GITHUB_OUTPUT"
+
+echo "Resolved: tag=$tag version=$version disttag=$disttag prerelease=$is_prerelease"
+```
+
+Make it executable: `chmod +x .github/scripts/compute-disttag.sh`
+
+- [ ] **Step 2.4: Run the test — verify it passes**
+
+Run: `npm test -- tests/scripts/compute-disttag.test.ts`
+
+Expected: all 6 tests pass.
+
+- [ ] **Step 2.5: Run full test suite — verify nothing else broke**
+
+Run: `npm test`
+
+Expected: all tests across the repo pass.
+
+- [ ] **Step 2.6: Run lint — verify the test file passes ESLint strict**
+
+Run: `npm run lint`
+
+Expected: no errors. If ESLint flags anything in the new test file (e.g., security plugin or jsdoc), fix inline with targeted disable comments scoped to the minimum line, re-run, confirm clean.
+
+- [ ] **Step 2.7: Commit**
+
+```bash
+git add .github/scripts/compute-disttag.sh tests/scripts/compute-disttag.test.ts
+git commit -m "feat(ci): add compute-disttag script with tests
+
+Extracts the tag-to-disttag mapping logic into a
+standalone bash script so it can be unit-tested before
+being wired into the release workflow. Handles stable
+releases (-> latest), prereleases with .N suffix
+(beta.1 -> beta), and prereleases without a dot
+(beta -> beta)."
+```
+
+---
+
+## Task 3: Workflow skeleton and `verify-signature` job
+
+**Context:** Create the workflow file with trigger, workflow-level permissions, concurrency, and the first job (`verify-signature`). After this task the file is a syntactically valid workflow that *only* verifies signatures — the remaining jobs are added in subsequent tasks. Also download actionlint for local validation.
+
+**Files:**
+- Create: `.github/workflows/release.yml`
+- Create: `.tools/actionlint` (gitignored, not committed)
+
+- [ ] **Step 3.1: Download actionlint binary into `.tools/`**
+
+Run:
+
+```bash
+mkdir -p .tools
+cd .tools
+bash <(curl -sSf https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash) 1.7.7 .
+cd ..
+ls -la .tools/actionlint
+```
+
+Expected: `.tools/actionlint` exists and is executable. If the download script fails, fall back to:
+
+```bash
+curl -sSL -o /tmp/actionlint.tgz \
+  https://github.com/rhysd/actionlint/releases/download/v1.7.7/actionlint_1.7.7_linux_amd64.tar.gz
+tar -xzf /tmp/actionlint.tgz -C .tools actionlint
+chmod +x .tools/actionlint
+```
+
+Confirm: `.tools/actionlint --version` prints `1.7.7`.
+
+- [ ] **Step 3.2: Create `.github/workflows/release.yml` with skeleton and verify-signature job**
+
+Create the file with exactly this content:
+
+```yaml
+name: release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+      - 'v[0-9]+.[0-9]+.[0-9]+-*'
+
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  verify-signature:
+    name: Verify commit and tag are signed
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Verify commit signature
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          commit_sha="${GITHUB_SHA}"
+          repo="${GITHUB_REPOSITORY}"
+
+          verified=$(gh api "repos/${repo}/commits/${commit_sha}" \
+            --jq '.commit.verification.verified')
+          reason=$(gh api "repos/${repo}/commits/${commit_sha}" \
+            --jq '.commit.verification.reason')
+
+          echo "commit=${commit_sha} verified=${verified} reason=${reason}"
+
+          if [ "${verified}" != "true" ]; then
+            echo "::error title=Unsigned commit::Commit ${commit_sha} is NOT verified by GitHub. Reason: ${reason}. Refusing to release."
+            exit 1
+          fi
+
+      - name: Verify tag is a signed annotated tag
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME}"
+          repo="${GITHUB_REPOSITORY}"
+
+          ref_json=$(gh api "repos/${repo}/git/refs/tags/${tag}")
+          obj_type=$(echo "${ref_json}" | jq -r '.object.type')
+          obj_sha=$(echo "${ref_json}" | jq -r '.object.sha')
+
+          if [ "${obj_type}" != "tag" ]; then
+            echo "::error title=Lightweight tag::Tag ${tag} is a lightweight tag (object.type=${obj_type}). Use 'git tag -s ${tag}' to create a signed annotated tag. Refusing to release."
+            exit 1
+          fi
+
+          verified=$(gh api "repos/${repo}/git/tags/${obj_sha}" \
+            --jq '.verification.verified')
+          reason=$(gh api "repos/${repo}/git/tags/${obj_sha}" \
+            --jq '.verification.reason')
+
+          echo "tag=${tag} object_sha=${obj_sha} verified=${verified} reason=${reason}"
+
+          if [ "${verified}" != "true" ]; then
+            echo "::error title=Unsigned tag::Tag ${tag} signature is NOT verified by GitHub. Reason: ${reason}. Refusing to release."
+            exit 1
+          fi
+```
+
+- [ ] **Step 3.3: Validate with actionlint**
+
+Run: `./.tools/actionlint .github/workflows/release.yml`
+
+Expected: no output (success). If actionlint reports issues, fix them inline and re-run until clean. Common issues:
+- `shellcheck` warnings on the `run:` blocks — fix the bash per shellcheck's guidance.
+- `github.token` should work; if flagged use `${{ secrets.GITHUB_TOKEN }}` instead.
+
+- [ ] **Step 3.4: Verify YAML is parseable with Node**
+
+Run:
+
+```bash
+node -e "
+const fs = require('node:fs');
+const content = fs.readFileSync('.github/workflows/release.yml', 'utf8');
+// naive sanity: starts with 'name:' and contains 'jobs:'
+if (!content.startsWith('name: release')) throw new Error('bad header');
+if (!content.includes('jobs:\n  verify-signature:')) throw new Error('missing job');
+console.log('ok');
+"
+```
+
+Expected output: `ok`.
+
+- [ ] **Step 3.5: Commit**
+
+```bash
+git add .github/workflows/release.yml
+git commit -m "feat(ci): add release workflow skeleton with verify-signature job
+
+Adds the release workflow entry point triggered by semver
+tag pushes (v*.*.* and v*.*.*-*) with workflow-level
+permissions (contents:write, id-token:write) and a
+concurrency group per tag ref with cancel-in-progress
+disabled.
+
+The first job, verify-signature, queries the GitHub API
+to confirm both the commit the tag points to and the
+annotated tag object itself are cryptographically
+verified. Lightweight tags, unsigned commits, and any
+non-verified tag objects cause the job to fail hard with
+a ::error:: annotation, blocking the rest of the
+pipeline via needs: in subsequent tasks."
+```
+
+Note: `.tools/actionlint` is NOT staged — it is in `.gitignore` (Task 1.4).
+
+---
+
+## Task 4: Add `test` job with Node version matrix
+
+**Context:** Add the quality gate: lint, typecheck, tests, and build, running in parallel across Node 20, 22, 24. This job `needs: verify-signature` so it only runs if the signature check passed. All three matrix cells must succeed for downstream jobs to unblock.
+
+**Files:**
+- Modify: `.github/workflows/release.yml`
+
+- [ ] **Step 4.1: Append the `test` job to `.github/workflows/release.yml`**
+
+Add this block after the `verify-signature` job, inside the `jobs:` mapping, maintaining 2-space YAML indent:
+
+```yaml
+  test:
+    name: Test on Node ${{ matrix.node-version }}
+    needs: verify-signature
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: true
+      matrix:
+        node-version: ['20', '22', '24']
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Node ${{ matrix.node-version }}
+        uses: actions/setup-node@v5
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Test
+        run: npm test
+
+      - name: Build
+        run: npm run build
+```
+
+- [ ] **Step 4.2: Validate with actionlint**
+
+Run: `./.tools/actionlint .github/workflows/release.yml`
+
+Expected: no output. Fix any reported issues before continuing.
+
+- [ ] **Step 4.3: Commit**
+
+```bash
+git add .github/workflows/release.yml
+git commit -m "feat(ci): add test matrix job to release workflow
+
+Adds a test job that runs lint, typecheck, tests, and
+build across Node 20, 22, and 24 in parallel. Chained
+after verify-signature via needs: so unsigned tags never
+burn CI minutes on tests. fail-fast is enabled: the
+first matrix cell to fail aborts the others."
+```
+
+---
+
+## Task 5: Add `publish-npm` job
+
+**Context:** Add the npm publish job. Uses the bash script from Task 2 to compute the dist-tag, includes the version-mismatch guard, and publishes with `--provenance --access public`. This job `needs: test` so it only runs if all three Node matrix cells passed.
+
+**Files:**
+- Modify: `.github/workflows/release.yml`
+
+- [ ] **Step 5.1: Append the `publish-npm` job**
+
+Add this block after the `test` job, inside the `jobs:` mapping:
+
+```yaml
+  publish-npm:
+    name: Publish to npm
+    needs: test
+    runs-on: ubuntu-24.04
+    outputs:
+      version: ${{ steps.disttag.outputs.version }}
+      disttag: ${{ steps.disttag.outputs.disttag }}
+      is_prerelease: ${{ steps.disttag.outputs.is_prerelease }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Node
+        uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Compute dist-tag from git tag
+        id: disttag
+        run: bash .github/scripts/compute-disttag.sh
+
+      - name: Verify package.json version matches git tag
+        run: |
+          set -euo pipefail
+          pkg_version=$(node -p "require('./package.json').version")
+          git_version="${{ steps.disttag.outputs.version }}"
+          if [ "${pkg_version}" != "${git_version}" ]; then
+            echo "::error title=Version mismatch::package.json version (${pkg_version}) does not match git tag (${git_version}). Bump package.json before tagging."
+            exit 1
+          fi
+          echo "package.json and git tag both at ${pkg_version}"
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          set -euo pipefail
+          npm publish \
+            --provenance \
+            --access public \
+            --tag "${{ steps.disttag.outputs.disttag }}"
+```
+
+- [ ] **Step 5.2: Validate with actionlint**
+
+Run: `./.tools/actionlint .github/workflows/release.yml`
+
+Expected: no output. Fix any issues before continuing.
+
+- [ ] **Step 5.3: Verify the script is referenced correctly**
+
+Run:
+
+```bash
+test -x .github/scripts/compute-disttag.sh && echo "script exists and is executable"
+grep -q 'bash .github/scripts/compute-disttag.sh' .github/workflows/release.yml && echo "workflow references script"
+```
+
+Expected:
+```
+script exists and is executable
+workflow references script
+```
+
+- [ ] **Step 5.4: Commit**
+
+```bash
+git add .github/workflows/release.yml
+git commit -m "feat(ci): add publish-npm job with provenance
+
+Adds the npm publish job chained after the test matrix.
+Computes the npm dist-tag from the git tag via the
+compute-disttag script, verifies package.json version
+matches the git tag (fails hard on mismatch), then
+publishes with --provenance --access public. Exposes
+version, disttag, and is_prerelease as job outputs for
+the github-release job to consume."
+```
+
+---
+
+## Task 6: Add `github-release` job
+
+**Context:** Final job: creates a GitHub Release with the built tarball attached. Split into two mutually exclusive steps gated by `if:` on `needs.publish-npm.outputs.is_prerelease` — one for stable releases, one for prereleases (adds `--prerelease` flag). Auto-generates release notes from commits since the last tag.
+
+**Files:**
+- Modify: `.github/workflows/release.yml`
+
+- [ ] **Step 6.1: Append the `github-release` job**
+
+Add this block after the `publish-npm` job, inside the `jobs:` mapping:
+
+```yaml
+  github-release:
+    name: Create GitHub Release
+    needs: publish-npm
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Pack tarball
+        run: npm pack
+
+      - name: Create GitHub Release (stable)
+        if: needs.publish-npm.outputs.is_prerelease == 'false'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          gh release create "${GITHUB_REF_NAME}" \
+            ./intelmesh-sdk-*.tgz \
+            --title "${GITHUB_REF_NAME}" \
+            --generate-notes
+
+      - name: Create GitHub Release (prerelease)
+        if: needs.publish-npm.outputs.is_prerelease == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          gh release create "${GITHUB_REF_NAME}" \
+            ./intelmesh-sdk-*.tgz \
+            --title "${GITHUB_REF_NAME}" \
+            --generate-notes \
+            --prerelease
+```
+
+- [ ] **Step 6.2: Validate with actionlint**
+
+Run: `./.tools/actionlint .github/workflows/release.yml`
+
+Expected: no output. Fix any issues before continuing.
+
+- [ ] **Step 6.3: Sanity check — count jobs in final file**
+
+Run:
+
+```bash
+grep -cE '^  [a-z][a-z-]+:$' .github/workflows/release.yml
+```
+
+Expected: `4` (four jobs: verify-signature, test, publish-npm, github-release).
+
+Also verify the needs chain:
+
+```bash
+grep -n 'needs:' .github/workflows/release.yml
+```
+
+Expected: three `needs:` lines — `verify-signature` (on test), `test` (on publish-npm), `publish-npm` (on github-release).
+
+- [ ] **Step 6.4: Commit**
+
+```bash
+git add .github/workflows/release.yml
+git commit -m "feat(ci): add github-release job completing the pipeline
+
+Adds the final job that npm-packs the built SDK and
+creates a GitHub Release with the .tgz attached. Split
+into two mutually exclusive steps gated by if: on the
+publish-npm.is_prerelease output — stable releases use
+default flags, prereleases add --prerelease so they
+don't pollute /releases/latest. Release notes are
+auto-generated from commits since the previous tag via
+gh release --generate-notes, which needs fetch-depth: 0
+on checkout."
+```
+
+---
+
+## Task 7: Final full-workflow actionlint + manual review
+
+**Context:** The workflow is complete. Run the linter one last time on the full file, then do a manual sanity sweep against the spec.
+
+**Files:**
+- Read only: `.github/workflows/release.yml`, `docs/superpowers/specs/2026-04-10-release-pipeline-design.md`
+
+- [ ] **Step 7.1: Run actionlint with verbose output**
+
+Run: `./.tools/actionlint -verbose .github/workflows/release.yml`
+
+Expected: no output (success). If anything is flagged, fix it and re-run until clean.
+
+- [ ] **Step 7.2: Spec-to-implementation mapping check**
+
+Manually walk through the spec sections and confirm each corresponds to something in the final workflow. Create a checklist in your head:
+
+| Spec section | Where implemented |
+|---|---|
+| §3 Trigger (`v*.*.*` + `v*.*.*-*`) | `on.push.tags` in workflow |
+| §4 Permissions + concurrency | workflow-level `permissions:` and `concurrency:` |
+| §5.1 verify-signature (commit + tag object checks) | `verify-signature` job |
+| §5.2 test matrix (Node 20/22/24, lint+typecheck+test+build) | `test` job with strategy.matrix |
+| §5.3 publish-npm (dist-tag, version guard, provenance) | `publish-npm` job + `compute-disttag.sh` |
+| §5.4 github-release (two steps, prerelease flag, generate-notes) | `github-release` job |
+| §6 Secrets (NPM_TOKEN usage) | referenced in publish-npm step |
+
+If any row has a gap, STOP and fix the workflow before the smoke test task.
+
+- [ ] **Step 7.3: Dry-run the dist-tag script against a few tag names to build confidence**
+
+Run:
+
+```bash
+mkdir -p /tmp/disttag-manual
+for tag in v1.0.0 v1.0.0-beta.1 v2.0.0-rc.3 v3.0.0-alpha.0; do
+  out=/tmp/disttag-manual/$tag.out
+  : > "$out"
+  GITHUB_REF_NAME="$tag" GITHUB_OUTPUT="$out" bash .github/scripts/compute-disttag.sh
+  echo "--- $tag ---"
+  cat "$out"
+done
+```
+
+Expected output groups like:
+```
+--- v1.0.0 ---
+version=1.0.0
+disttag=latest
+is_prerelease=false
+--- v1.0.0-beta.1 ---
+version=1.0.0-beta.1
+disttag=beta
+is_prerelease=true
+...
+```
+
+- [ ] **Step 7.4: Final full test suite run**
+
+Run: `npm test`
+
+Expected: all tests pass, including `tests/scripts/compute-disttag.test.ts`.
+
+- [ ] **Step 7.5: No commit needed for this task**
+
+Task 7 is verification only. No files were modified. If anything needed fixing in Step 7.1, those fixes were already committed as targeted "fix(ci): ..." commits during the fix loop.
+
+---
+
+## Post-implementation: smoke test checklist (manual, operator-run)
+
+**Not part of the automated plan — this is a runbook for the human operator once the code is merged.**
+
+Before the first real release:
+
+1. Ensure `NPM_TOKEN` secret is set in the repo (Settings → Secrets → Actions → `NPM_TOKEN`, Granular Access Token with `Read and write` on `@intelmesh` packages).
+2. Ensure the npm account has the package linked to this repo (required for `--provenance`).
+3. On a throwaway branch, bump `package.json` to a prerelease like `0.1.0-alpha.0`.
+4. Sign-tag: `git tag -s v0.1.0-alpha.0 -m "pipeline smoke test"`.
+5. Push: `git push origin v0.1.0-alpha.0`.
+6. Watch the Actions run. Expected outcomes:
+   - `verify-signature` passes (if it fails, fix local GPG/SSH signing config before anything else).
+   - `test` passes on all three Node versions.
+   - `publish-npm` publishes to npm under dist-tag `alpha`.
+   - `github-release` creates a prerelease on GitHub with the `.tgz` attached.
+7. Cleanup (optional): `npm dist-tag rm @intelmesh/sdk alpha` and delete the GitHub release.
+
+---
+
+## Self-review notes (author's own)
+
+- **Spec coverage:** every requirement in the spec maps to a specific task or file created. §9 (smoke test) is represented in the post-implementation runbook above since it's a manual step.
+- **No placeholders:** every step has actual content — code blocks, commands, and expected output.
+- **Type consistency:** the bash script writes `version`, `disttag`, `is_prerelease` to `$GITHUB_OUTPUT`; the vitest test parses those same three keys; the workflow step `id: disttag` consumes `steps.disttag.outputs.{version,disttag,is_prerelease}`; the `publish-npm` job exposes the same three names as job outputs; `github-release` reads `needs.publish-npm.outputs.is_prerelease`. Names are consistent end-to-end.
+- **Commits are frequent:** Task 1 = 1 commit, Task 2 = 1 commit, Tasks 3-6 = 1 commit each, Task 7 = 0 commits. Total: 6 commits, each self-contained and reversible.
+- **User feedback honored:** nothing under `docs/` is ever staged or committed. The plan document itself is not committed.