/release

name: release
description: End-to-end npm release workflow with verification gates and hardcoded-version protection
trust_tier: 0
domain: release-management

Release Workflow

Execute a safe, verified npm release for the `agentic-qe` package. STOP after each phase for user confirmation.

Architecture

This project uses a **flat single-package structure** (post v3.7.4 flatten):

| File | Package Name | Role | |------|-------------|------| | `package.json` (root) | `agentic-qe` | **Published to npm** — the installable package |

• `npm run build` executes `tsc && build:cli && build:mcp` producing `dist/` at root
• `npm publish` runs from the **root** directory
• GitHub Actions triggers on `release: published` event via `.github/workflows/npm-publish.yml`

**Important**: There is NO `v3/` subdirectory. All source is at root (`src/`, `dist/`, `tests/`).

Arguments

• `<version>` — Target version (e.g., `3.7.5`). If omitted, prompt the user.

Steps

1. Pre-Flight: Ensure Clean State

git status
git branch --show-current

Verify working directory is clean and you know which branch you're on. If there are uncommitted changes, stop and ask the user. The release prep happens on the **current working branch** — we PR to main later.

**STOP — confirm clean state and current branch.**

2. Version Audit

Read the current version from `package.json` (source of truth). Then grep the ENTIRE codebase for hardcoded version strings — current version, old versions, and any version-like patterns.

# Read current version
node -p "require('./package.json').version"

# Search for version strings in source files (exclude node_modules, dist, .git, docs/releases)
grep -rn --include="*.ts" --include="*.js" --include="*.json" '"3\.[0-9]\+\.[0-9]\+"' . \
  --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=.git --exclude-dir=releases

Also check `.claude/skills/skills-manifest.json` for `fleetVersion` — must be updated to match.

If any stale version strings are found in source files, fix them ALL before continuing.

**STOP — show findings and wait for user confirmation.**

3. Bump Version

Update package.json to the target version:

cd /workspaces/agentic-qe && npm version <version> --no-git-tag-version

Also update `fleetVersion` in `.claude/skills/skills-manifest.json`.

Verify:

grep '"version"' package.json

**STOP — confirm version is correct.**

4. Update CHANGELOG

Add a new section to `CHANGELOG.md` (at root) following Keep a Changelog format:

## [<version>] - YYYY-MM-DD

### Added
- ...

### Fixed
- ...

### Changed
- ...

Write user-friendly descriptions focused on value, not implementation details.

**STOP — show changelog entry for review.**

4b. Update Release Docs

Create a release notes file at `docs/releases/v<version>.md` following the existing format:

# v<version> Release Notes

**Release Date:** YYYY-MM-DD

## Highlights

<1-2 sentence summary of the most important changes>

## Added
- ...

## Fixed
- ...

## Changed
- ...

Then update `docs/releases/README.md` — add a new row at the TOP of the table:

| [v<version>](v<version>.md) | YYYY-MM-DD | <Short highlights> |

Use existing entries as formatting reference. Keep highlights concise (under 80 chars).

5. Build

npm run build

Executes `tsc && build:cli && build:mcp`. Verify zero errors. If build fails, diagnose and fix.

**STOP — show build output.**

6. Type Check

npm run typecheck

Runs `tsc --noEmit`. Must produce zero errors.

**STOP — show type check output.**

7. Unit Tests

npx vitest run tests/unit/

Run REAL tests against the actual codebase. Do NOT simulate, mock, or skip any tests. ALL unit tests must pass.

**STOP — show test results.**

8. Artifact & Integration Verification

This is the critical pre-release gate. Verify the built package works end-to-end as a user would experience it.

8a. Verify Build Artifacts

# Verify dist/ exists with expected bundles
ls -la dist/cli/bundle.js
ls -la dist/index.js
ls -la dist/mcp/bundle.js

All three must exist: CLI bundle, main entry point, MCP server.

8b. Test `aqe init --auto` in a Fresh Project

# Create a temporary test project
mkdir -p /tmp/aqe-release-test && cd /tmp/aqe-release-test

# Run init using the LOCAL build (not published version)
node /workspaces/agentic-qe/dist/cli/bundle.js init --auto

Verify init completes without errors and creates the expected project structure (`.agentic-qe/` directory, config files).

8c. Verify CLI

# Version output
node /workspaces/agentic-qe/dist/cli/bundle.js --version

# System status
node /workspaces/agentic-qe/dist/cli/bundle.js status

Both must succeed without errors.

8d. Verify Self-Learning & Fleet Capabilities

cd /tmp/aqe-release-test

# Verify learning subsystem
node /workspaces/agentic-qe/dist/cli/bundle.js learning stats 2>&1 | head -10

# Verify agent listing works
node /workspaces/agentic-qe/dist/cli/bundle.js agent list 2>&1 | head -10

# Verify health check
node /workspaces/agentic-qe/dist/cli/bundle.js health 2>&1 | head -10

These should respond (even if empty results) without errors, confirming the subsystems initialize properly.

8e. Isolated Dependency Check (catches missing externals)

# Pack and install in a clean temp directory to simulate real user install
CLEAN_DIR=$(mktemp -d)
npm pack --pack-destination "$CLEAN_DIR" 2>&1 | tail -2
cd "$CLEAN_DIR"
npm init -y > /dev/null 2>&1
npm install ./agentic-qe-<version>.tgz 2>&1 | tail -3
node node_modules/.bin/aqe --version 2>&1
EXIT=$?
echo "Exit code: $EXIT"
cd /workspaces/agentic-qe
rm -rf "$CLEAN_DIR"

Must exit 0 and print the correct version. If it crashes with `ERR_MODULE_NOT_FOUND`, a dependency is marked as external in the build scripts but not listed in `dependencies`. Fix by either bundling it, lazy-loading