@intelmesh/sdk 0.1.0 → 0.1.1

package/.github/workflows/release.yml

@@ -108,6 +108,7 @@ jobs:
     name: Publish to npm
     needs: test
     runs-on: ubuntu-24.04
+    environment: npm-publish
     permissions:
       contents: read
       id-token: write
@@ -122,7 +123,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v5
         with:
-          node-version: '22'
+          node-version: '24'
           registry-url: 'https://registry.npmjs.org'
           cache: 'npm'
 
@@ -170,7 +171,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v5
         with:
-          node-version: '22'
+          node-version: '24'
           cache: 'npm'
 
       - name: Install dependencies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intelmesh/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Official Node.js client for the IntelMesh Risk Intelligence Engine API",
   "type": "module",
   "main": "dist/index.js",

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

@@ -1,798 +0,0 @@
-# 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.

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

@@ -1,309 +0,0 @@
-# Release Pipeline Design — `@intelmesh/sdk`
-
-**Date:** 2026-04-10
-**Status:** Draft (pending user review)
-**Scope:** GitHub Actions workflow to publish `@intelmesh/sdk` to the public npm registry and create a GitHub Release on every signed semver tag.
-
----
-
-## 1. Goals
-
-Create a single, auditable GitHub Actions workflow that:
-
-1. Triggers on semver tag push (`v*.*.*` and `v*.*.*-*`).
-2. Refuses to publish unless **both** the commit the tag points to **and** the tag object itself are cryptographically signed and verified by GitHub.
-3. Runs the full quality gate (lint, typecheck, tests, build) on a Node version matrix (20, 22, 24) before any publish action.
-4. Publishes to the public npm registry with Sigstore provenance.
-5. Automatically derives the npm `dist-tag` from the tag suffix (stable → `latest`, prerelease → `beta`/`rc`/`alpha`/etc).
-6. Creates a GitHub Release with the built tarball attached and auto-generated changelog, marked as `prerelease` when appropriate.
-7. Fails hard at the earliest failing step — no partial state (no published version without a release, no release without a successful publish).
-
-## 2. Non-goals
-
-- PR CI workflow (only release-on-tag is in scope).
-- `workflow_dispatch` with `dry_run` flag (deferred, YAGNI).
-- Integration tests hitting a live API (no such tests exist today).
-- Publishing to GitHub Packages or any registry other than public npm.
-- Automatic version bumping, changelog generation outside `gh release --generate-notes`, or release-please style automation.
-- Unpublish / rollback automation (stays manual).
-
-## 3. Trigger
-
-```yaml
-on:
-  push:
-    tags:
-      - 'v[0-9]+.[0-9]+.[0-9]+'
-      - 'v[0-9]+.[0-9]+.[0-9]+-*'
-```
-
-Two explicit glob patterns. GitHub filters these *before* scheduling runners, so malformed tags like `v-test` or `release-1` never spend CI minutes. The first pattern matches stable releases (`v1.2.3`); the second matches prereleases (`v1.2.3-beta.1`, `v1.2.3-rc.2`, `v2.0.0-alpha.0`, etc).
-
-## 4. Workflow-level permissions and concurrency
-
-```yaml
-permissions:
-  contents: write    # github-release job creates releases
-  id-token: write    # publish-npm job generates OIDC token for --provenance
-
-concurrency:
-  group: release-${{ github.ref }}
-  cancel-in-progress: false
-```
-
-**Permissions** are declared at the workflow level (not per job) because both are needed and `contents: read` alone is insufficient for the release step. No other permissions granted — principle of least privilege.
-
-**Concurrency** groups runs by tag ref with `cancel-in-progress: false`. Same tag cannot run twice in parallel (defense against accidental double-push), but distinct tags run independently. `cancel-in-progress` is explicitly `false` because a publish-in-flight must never be cancelled mid-flight (would leave npm and GitHub in inconsistent states).
-
-## 5. Job graph
-
-Four jobs, chained strictly via `needs:`. Any failure aborts the entire chain.
-
-```
-verify-signature → test (matrix 20/22/24) → publish-npm → github-release
-```
-
-### 5.1 Job: `verify-signature`
-
-**Runs-on:** `ubuntu-24.04`
-**Responsibility:** Refuse to proceed unless both the commit and the annotated tag object are verified.
-
-**Algorithm:**
-
-1. **Commit check**
-   - `GET /repos/{owner}/{repo}/commits/{github.sha}`
-   - Read `.commit.verification.verified`
-   - If not `true`: log `.commit.verification.reason` (examples: `unsigned`, `unknown_key`, `bad_email`, `unverified_email`, `not_signing_key`, `expired_key`) and `exit 1`.
-
-2. **Resolve tag object**
-   - `GET /repos/{owner}/{repo}/git/refs/tags/{github.ref_name}`
-   - Read `.object.type`
-   - If `"commit"`: the tag is a lightweight tag (no signature). Emit error telling the user to use `git tag -s` and `exit 1`.
-   - If `"tag"`: read `.object.sha` (the SHA of the tag object itself).
-
-3. **Tag signature check**
-   - `GET /repos/{owner}/{repo}/git/tags/{tag_object_sha}`
-   - Read `.verification.verified`
-   - If not `true`: log `.verification.reason` and `exit 1`.
-
-**Implementation tool:** `gh api` (pre-installed on GitHub-hosted runners, authenticated via `GH_TOKEN=${{ github.token }}`). JSON parsing via `--jq`.
-
-**Error output:** uses `::error::` workflow command so failures surface as annotations on the tag's commit in the Actions UI.
-
-**Why both checks?**
-- Commit-only: misses a lightweight tag created on top of a verified commit — you'd publish without ever signing the release itself.
-- Tag-only: misses the case where the tag is signed but the underlying commit came from an unverified push.
-- Both: guarantees a complete cryptographic chain from commit → tag → release.
-
-### 5.2 Job: `test`
-
-**Runs-on:** `ubuntu-24.04`
-**Needs:** `verify-signature`
-**Strategy:** Matrix on `node-version: [20, 22, 24]`, `fail-fast: true`.
-
-**Steps:**
-
-1. `actions/checkout@v5`
-2. `actions/setup-node@v5` with `node-version: ${{ matrix.node-version }}` and `cache: 'npm'`
-3. `npm ci`
-4. `npm run lint`
-5. `npm run typecheck`
-6. `npm run test` (vitest)
-7. `npm run build`
-
-All three matrix cells must succeed for `needs: test` downstream to unblock.
-
-**Rationale for matrix:** `package.json` declares `engines.node: ">=20"`. The release must prove the SDK works on every LTS-or-current supported runtime before going to npm. Runtime is cheap (three parallel jobs) and it catches runtime-specific regressions that only manifest on newer Node versions (e.g., changes to `fetch`, `URL`, or `AbortController` semantics).
-
-### 5.3 Job: `publish-npm`
-
-**Runs-on:** `ubuntu-24.04`
-**Needs:** `test`
-**Outputs:** `is_prerelease`, `disttag`, `version` (consumed by `github-release`).
-
-**Steps:**
-
-1. `actions/checkout@v5`
-2. `actions/setup-node@v5` with `node-version: 22`, `registry-url: 'https://registry.npmjs.org'`, `cache: 'npm'`
-3. `npm ci`
-4. `npm run build`
-5. **Compute dist-tag and version (step id: `disttag`)**
-
-   ```bash
-   set -euo pipefail
-   tag="${GITHUB_REF_NAME}"           # e.g. "v1.2.3-beta.1"
-   version="${tag#v}"                 # strip leading v → "1.2.3-beta.1"
-   if [[ "$version" == *-* ]]; then
-     suffix="${version#*-}"           # "beta.1"
-     disttag="${suffix%%.*}"          # "beta"
-     is_prerelease=true
-   else
-     disttag="latest"
-     is_prerelease=false
-   fi
-   echo "version=$version"         >> "$GITHUB_OUTPUT"
-   echo "disttag=$disttag"         >> "$GITHUB_OUTPUT"
-   echo "is_prerelease=$is_prerelease" >> "$GITHUB_OUTPUT"
-   ```
-
-6. **Version mismatch guard**
-
-   ```bash
-   pkg_version=$(node -p "require('./package.json').version")
-   if [ "$pkg_version" != "${{ steps.disttag.outputs.version }}" ]; then
-     echo "::error::package.json version ($pkg_version) does not match git tag (${{ steps.disttag.outputs.version }})"
-     exit 1
-   fi
-   ```
-
-7. **Publish**
-
-   ```bash
-   npm publish --provenance --access public --tag "${{ steps.disttag.outputs.disttag }}"
-   ```
-
-   With `env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}`.
-
-**Tag-to-dist-tag mapping (reference):**
-
-| Tag pushed            | `version`         | `disttag` | `is_prerelease` |
-|-----------------------|-------------------|-----------|-----------------|
-| `v1.2.3`              | `1.2.3`           | `latest`  | `false`         |
-| `v1.2.3-beta.1`       | `1.2.3-beta.1`    | `beta`    | `true`          |
-| `v1.2.3-beta.4`       | `1.2.3-beta.4`    | `beta`    | `true`          |
-| `v1.2.3-rc.1`         | `1.2.3-rc.1`      | `rc`      | `true`          |
-| `v2.0.0-alpha.7`      | `2.0.0-alpha.7`   | `alpha`   | `true`          |
-| `v2.0.0-next.0`       | `2.0.0-next.0`    | `next`    | `true`          |
-
-**Why `--access public`?** `@intelmesh/sdk` is a scoped package; npm defaults scoped packages to private. The flag makes it explicit and prevents accidental private publishes.
-
-**Why `--provenance`?** Generates a Sigstore attestation linking the published tarball to the GitHub Actions run that built it. Consumers see a "provenance" badge on `npmjs.com/package/@intelmesh/sdk`. Requires `id-token: write` permission (already declared) and the npm account to have the package linked to this repo (via `package.json` `repository` field — must be verified present during implementation).
-
-**Why use the tag as the source of truth, not `package.json`?** If the developer tags `v1.2.3-beta.1` but forgets to bump `package.json` from `1.2.3`, we want a loud failure, not silent guessing. The version mismatch guard enforces this.
-
-### 5.4 Job: `github-release`
-
-**Runs-on:** `ubuntu-24.04`
-**Needs:** `publish-npm`
-
-**Steps:**
-
-1. `actions/checkout@v5` with `fetch-depth: 0` (needed for `gh release --generate-notes` to compute since-last-tag)
-2. `actions/setup-node@v5` with `node-version: 22`, `cache: 'npm'`
-3. `npm ci`
-4. `npm run build`
-5. `npm pack` (produces `intelmesh-sdk-<version>.tgz`)
-6. **Create release** — split into two steps, gated by `if:` on the `is_prerelease` output, to keep each command readable:
-
-   ```yaml
-   - name: Create GitHub Release (stable)
-     if: needs.publish-npm.outputs.is_prerelease == 'false'
-     env:
-       GH_TOKEN: ${{ github.token }}
-     run: |
-       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: |
-       gh release create "$GITHUB_REF_NAME" \
-         ./intelmesh-sdk-*.tgz \
-         --title "$GITHUB_REF_NAME" \
-         --generate-notes \
-         --prerelease
-   ```
-
-   Two mutually exclusive steps are clearer than one step with a dynamic flag inlined via GHA expression syntax.
-
-**Why rebuild here instead of reusing `publish-npm` artifacts?** GitHub Actions jobs have isolated file systems. The alternatives are (a) `actions/upload-artifact` + `actions/download-artifact` between jobs, or (b) rebuild. Rebuild is simpler, deterministic, and the build is fast (<30s for this SDK). If build time grows, switch to upload/download. YAGNI for now.
-
-**Why `--generate-notes`?** GitHub auto-generates release notes from commits and PRs since the previous tag. No need to maintain a manual CHANGELOG for the MVP — the git log and PR titles are the source of truth. Manual CHANGELOG can be added later if needed.
-
-**Why create release *after* npm publish (not before)?** If npm publish fails, we don't want a dangling GitHub release pointing at a version that isn't in the registry. Publish first, release second.
-
-## 6. Secrets
-
-| Secret         | Source                          | Used in                         | Required |
-|----------------|---------------------------------|---------------------------------|----------|
-| `NPM_TOKEN`    | Repo Settings → Secrets → Actions | `publish-npm`                   | Yes      |
-| `GITHUB_TOKEN` | Automatic (injected)            | `verify-signature`, `github-release` | Auto     |
-
-**`NPM_TOKEN` provisioning (one-time, manual):**
-
-1. On `npmjs.com`, log in with the owner account for `@intelmesh`.
-2. Settings → Access Tokens → Generate New Token → Granular Access Token.
-3. Scope: `Read and write` on packages under `@intelmesh`.
-4. Expiration: 1 year (document renewal in team runbook).
-5. Copy the token.
-6. In the GitHub repo: Settings → Secrets and variables → Actions → New repository secret, name `NPM_TOKEN`.
-
-**Provenance prerequisite check:** During implementation, verify `package.json` has a `repository` field pointing to `github.com/intelmesh/intelmesh-sdk-ts`. If missing, add it — `npm publish --provenance` uses it to link the package to the source repo.
-
-## 7. Failure modes
-
-| Scenario                                | Failing job       | User-visible message                                                                 |
-|-----------------------------------------|-------------------|---------------------------------------------------------------------------------------|
-| Push of lightweight tag                 | `verify-signature` | `Tag vX.Y.Z is a lightweight tag. Use 'git tag -s' to create a signed annotated tag.` |
-| Commit not signed                       | `verify-signature` | `Commit <sha> is NOT verified. Reason: unsigned`                                      |
-| Signing key not registered on GitHub    | `verify-signature` | `Reason: unknown_key`                                                                 |
-| Expired signing key                     | `verify-signature` | `Reason: expired_key`                                                                 |
-| Signer email not verified on GitHub     | `verify-signature` | `Reason: unverified_email`                                                            |
-| Lint / typecheck / test / build failure | `test`            | ESLint / tsc / vitest annotations on the run                                          |
-| `package.json` version ≠ tag            | `publish-npm`     | `package.json version (X) does not match git tag (Y)`                                 |
-| Version already published               | `publish-npm`     | npm 403; step fails; no release created                                               |
-| `NPM_TOKEN` missing/expired             | `publish-npm`     | npm 401                                                                               |
-| Provenance OIDC fails                   | `publish-npm`     | npm publish error mentioning `id-token`                                               |
-
-All failures propagate via `needs:` so no downstream job runs. There is no partial state: a failed pipeline leaves the npm registry and GitHub Releases untouched by downstream jobs.
-
-## 8. Re-running a failed release
-
-**Supported:** GitHub Actions "Re-run failed jobs" works because the trigger is `push: tags` and the tag continues to point to the same commit. Use this for flaky failures (npm registry 502, runner network blip, etc).
-
-**Not supported by the workflow (manual process):**
-
-- Unpublishing a broken release from npm: `npm unpublish @intelmesh/sdk@X.Y.Z` within the 72-hour window, or contact npm support after.
-- Removing a release from GitHub: `gh release delete vX.Y.Z`.
-- Deleting/moving a tag: `git tag -d vX.Y.Z && git push --delete origin vX.Y.Z && git tag -s vX.Y.Z <new-sha> && git push origin vX.Y.Z`.
-
-These stay manual because they are operational rollbacks, not part of a normal release flow, and automating them would be footgun territory.
-
-## 9. Testing the workflow itself
-
-Before the first real release, validate the pipeline end-to-end on a throwaway version:
-
-1. Create a branch with a signed commit.
-2. Bump `package.json` to a harmless prerelease version like `0.1.0-alpha.0`.
-3. Sign-tag: `git tag -s v0.1.0-alpha.0 -m "pipeline smoke test"`.
-4. Push tag: `git push origin v0.1.0-alpha.0`.
-5. Watch the Actions run:
-   - `verify-signature` must pass (if not: fix GPG/SSH setup first).
-   - `test` must pass on all three Node versions.
-   - `publish-npm` will actually publish to npm under dist-tag `alpha`. This is fine — `alpha` dist-tag doesn't affect default installs.
-   - `github-release` creates a prerelease on GitHub.
-6. After success: `npm dist-tag rm @intelmesh/sdk alpha` (cleanup, optional) and delete the GitHub release if desired.
-
-Alternatively, if contaminating the npm registry with a test version is undesirable, a future `workflow_dispatch` with `dry_run` input can be added (explicitly deferred — see Non-goals).
-
-## 10. File layout
-
-```
-.github/
-  workflows/
-    release.yml       ← this design's output
-```
-
-Single file. All four jobs live in one workflow so the full release pipeline is visible in one place.
-
-## 11. Open implementation questions
-
-None at spec time. Items to verify during implementation:
-
-- `package.json` `repository` field is present and points to the correct GitHub URL (required for `--provenance`).
-- The npm account owning `@intelmesh` exists and `NPM_TOKEN` has been provisioned before merging the workflow (otherwise the first tag push will fail at `publish-npm`).
-- GitHub org `intelmesh` has `Actions` enabled with `write` permissions for workflow tokens (Settings → Actions → Workflow permissions).