release

リリースワークフロー

agentic-qe パッケージを安全に検証済みの状態で npm リリースします。各フェーズの後で停止し、ユーザーの確認を待ってください。

アーキテクチャ

このプロジェクトでは フラットな単一パッケージ構成（v3.7.4 以降のフラット化後）を使用しています。

ファイル	パッケージ名	役割
package.json（ルート）	agentic-qe	npm に公開 — インストール可能なパッケージ

• npm run build は tsc && build:cli && build:mcp を実行し、ルートに dist/ を生成します
• npm publish はルートディレクトリから実行します
• GitHub Actions は .github/workflows/npm-publish.yml を介して release: published イベントで起動します

重要：v3/ サブディレクトリはありません。すべてのソースはルート（src/、dist/、tests/）にあります。

引数

• <version> — 対象のバージョン（例：3.7.5）。省略された場合はユーザーに確認します。

手順

1. 事前確認：クリーンな状態であることを確認

git status
git branch --show-current

作業ディレクトリがクリーンで、現在のブランチを把握していることを確認します。未コミットの変更がある場合は停止してユーザーに確認してください。リリース準備は現在の作業ブランチで行い、後で main に PR を作成します。

停止 — クリーンな状態と現在のブランチを確認してください。

2. バージョン監査

package.json（信頼できる唯一の情報源）から現在のバージョンを読み取ります。その後、コードベース全体を grep して、現在のバージョン、古いバージョン、バージョンらしきパターンなど、ハードコードされたバージョン文字列をすべて確認します。

# 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

さらに、.claude/skills/skills-manifest.json の fleetVersion も確認します。一致するよう更新する必要があります。

ソースファイル内に古いバージョン文字列が見つかった場合は、続行する前にすべて修正します。

停止 — 調査結果を示し、ユーザーの確認を待ってください。

3. バージョンを更新

package.json を対象バージョンに更新します。

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

.claude/skills/skills-manifest.json の fleetVersion も更新します。

npm version は version ライフサイクルスクリプト（scripts/sync-plugin-versions.cjs）を実行し、Claude Code プラグインの各箇所も更新します。.claude-plugin/plugin.json（バージョンと agentic-qe@ MCP ピン）、plugins/agentic-qe-fleet/.claude-plugin/plugin.json（バージョン）、および plugins/agentic-qe-fleet/.mcp.json（agentic-qe@ ピン）が対象です。プラグイン自体に変更があった場合は、plugins/agentic-qe-fleet/CHANGELOG.mdに## — ` の項目を追加します。

確認：

grep '"version"' package.json
node scripts/sync-plugin-versions.cjs --check   # must print "in sync"
bash plugins/agentic-qe-fleet/scripts/smoke.sh  # plugin contract incl. MCP pin

停止 — バージョンが正しいことを確認してください。

4. CHANGELOG を更新

Keep a Changelog 形式に従い、ルートの CHANGELOG.md に新しいセクションを追加します。

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

### Added
- ...

### Fixed
- ...

### Changed
- ...

実装の詳細ではなく、ユーザーにとっての価値を中心に、分かりやすく説明します。

停止 — changelog の項目を提示し、レビューを待ってください。

4b. リリースドキュメントを更新

既存の形式に従い、docs/releases/v<version>.md にリリースノートファイルを作成します。

# v<version> Release Notes

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

## Highlights

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

## Added
- ...

## Fixed
- ...

## Changed
- ...

次に、docs/releases/README.md を更新し、表の先頭に新しい行を追加します。

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

既存の項目を形式の参考にしてください。ハイライトは簡潔に（80 文字未満）まとめます。

5. ビルド

npm run build

tsc && build:cli && build:mcp を実行します。エラーがゼロであることを確認してください。ビルドに失敗した場合は、原因を特定して修正します。

停止 — ビルド出力を提示してください。

6. 型チェック

npm run typecheck

tsc --noEmit を実行します。エラーがゼロでなければなりません。

停止 — 型チェックの出力を提示してください。

7. 単体テスト

npx vitest run tests/unit/

実際のコードベースに対してテストを実行します。テストをシミュレート、モック、またはスキップしてはいけません。すべての単体テストに合格する必要があります。

停止 — テスト結果を提示してください。

8. 成果物と統合の検証

リリース前の重要なゲートです。ユーザーが実際に利用するときと同じように、ビルド済みパッケージがエンドツーエンドで動作することを検証します。

8a. ビルド成果物を確認

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

CLI バンドル、メインのエントリーポイント、MCP サーバーの 3 つがすべて存在する必要があります。

8b. 新規プロジェクトで aqe init --auto をテスト

# 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

init がエラーなく完了し、想定されるプロジェクト構造（.agentic-qe/ ディレクトリ、設定ファイル）が作成されることを確認します。

8c. CLI を確認

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

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

どちらもエラーなく成功する必要があります。

8d. セルフラーニングと Fleet 機能を確認

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

エラーなく応答する（結果が空でも可）ことを確認し、サブシステムが正しく初期化されていることを確かめます。

8e. 分離環境での依存関係チェック（外部依存の不足を検出します）

# 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"

終了コードが 0 で、正しいバージョンが表示される必要があります。ERR_MODULE_NOT_FOUND でクラッシュする場合、依存関係がビルドスクリプトで外部依存として指定されていますが、dependencies に記載されていません。バンドルする、遅延読み込みする、または dependencies に追加することで修正してください。

8f. クリーンアップ

rm -rf /tmp/aqe-release-test

停止 — 検証結果をすべて表示してください。次に進む前に、すべてのチェックに合格する必要があります。

9. ローカル CI テストスイート

PR および公開時に CI で実行されるものと同じテストを実行します。ユーザーが明示的に求めない限り、E2E ブラウザーテストはスキップしてください。

cd /workspaces/agentic-qe

# Performance gates (fast — validates perf thresholds)
npm run performance:gate

# Regression tests (runs full unit suite)
npm run test:regression

# Full test:ci suite (from npm-publish.yml — excludes browser/e2e)
npm run test:ci

利用可能なテストスクリプト：test:unit、test:unit:fast、test:unit:heavy、test:unit:mcp、test:ci、test:regression、test:safe、test:perf、test:e2e、test:coverage、performance:gate。

必須のテストスイートはすべて合格する必要があります。既存の MCP ハンドラーテストの失敗（ランタイムの初期化が必要なテスト）は、メインブランチでも失敗する場合に限り許容されます。

停止 — テスト結果をすべて表示してください。

10. コミットして Main に PR を作成する

重要：PR の本文は .github/PULL_REQUEST_TEMPLATE.md に従う必要があります。CI では scripts/check-pr-body.cjs によりチェックされます（issue #401）。必須事項は次の 2 つです。

1. ### Required check (issue #401) セクションを含め、failure-modes のチェックボックスに [x] を付ける
2. 禁止されている否定表現（「I believe it's unlikely」、「can't see how this would fail」など）を、同じ段落に追跡用の issue への参照がない状態で使用しない

cd /workspaces/agentic-qe

# Stage version bump + changelog + release docs + any version audit fixes
git add package.json package-lock.json CHANGELOG.md docs/releases/README.md docs/releases/v<version>.md
git add .claude/skills/skills-manifest.json  # if fleetVersion was updated
git add .claude-plugin/plugin.json plugins/agentic-qe-fleet/.claude-plugin/plugin.json \
  plugins/agentic-qe-fleet/.mcp.json plugins/agentic-qe-fleet/CHANGELOG.md
git status

git commit -m "chore(release): bump version to v<version>"
git push origin <current-branch>

# Create PR to main
gh pr create \
  --base main \
  --title "chore(release): v<version>" \
  --body "$(cat <<'EOF'
## Summary

<1-3 sentences: what changed and why, from the CHANGELOG>

## Verification

<Paste actual command output from steps 5-9: build, typecheck, test counts,
aqe init --auto result, CLI --version, performance gate results.
Real output, not summaries.>

## Failure modes

<List any failure modes this release introduces, mitigates, or doesn't cover.
Be honest about what wasn't tested. If none, say "No new failure modes introduced.">

---

### Required check (issue #401)

- [x] **Every failure mode mentioned in this PR description has either (a) a test that exercises it, or (b) a linked tracking issue.** "Unlikely" is not an acceptable substitute. If you wrote "I don't think this can happen but...", that sentence is a failure mode and needs a test or an issue link.

### Optional context

- Linked issues: #
- Trust tier change (if any): none
- Affects published API or CLI surface: yes / no
- Touches the init flow / `npm-publish.yml` / `tests/fixtures/init-corpus/`: yes / no
  - If yes: did you run `./tests/fixtures/init-corpus/run-gate.sh` locally? yes / no / not applicable

See [CHANGELOG](CHANGELOG.md) for details.
EOF
)"

停止 — PR の URL を表示し、CI チェックに合格するまで待ってください。

11. PR をマージする

PR の CI が合格したら：

gh pr merge <pr-number> --merge

マージされた main を取得します：

git checkout main && git pull origin main

停止 — マージが成功したことを確認してください。

12. GitHub リリースを作成する

gh release create v<version> \
  --title "v<version>: <Short Title>" \
  --notes "$(cat <<'EOF'
## What's New

<User-friendly summary — focus on value, not technical details>

## Getting Started

\`\`\`bash
npx agentic-qe init --auto
\`\`\`

See [CHANGELOG](CHANGELOG.md) for full details.
EOF
)"

これにより、次の処理が自動的に行われます。

• git タグ v<version> を作成する
• npm-publish.yml GitHub Actions ワークフローを起動する

停止 — リリースの URL を表示してください。

13. 公開ワークフローを監視する

# Watch the GitHub Actions workflow
gh run list --workflow=npm-publish.yml --limit 1
gh run watch <run-id>

ワークフローでは、次の処理が行われます。

1. コードをチェックアウトし、依存関係をインストールする
2. npm run typecheck を実行する
3. npm run build を実行する
4. dist/ に CLI と MCP のバンドルがあることを確認する
5. npm run test:ci を実行する（ブラウザー／E2E を除く単体テスト）
6. パッケージのバージョンが git タグと一致することを確認する
7. npm publish --access public --provenance を実行する

ワークフローが成功するまで待ちます。失敗した場合は、ログから原因を調査します。

gh run view <run-id> --log-failed

停止 — ワークフローが成功したことを確認してください。

14. 公開後の検証

npm view agentic-qe@<version> name version

公開されたバージョンが一致することを確認します。ローカル環境でインストールをテストします。

npx agentic-qe@<version> --version

15. 分離環境でのインストール検証（重要）

この手順では、クリーンな環境でのみ発生する依存関係の不足／外部依存の問題（例：グローバルにインストールされている typescript が利用できない場合）を検出します。リリースの成功を宣言する前に、必ずこのチェックに合格する必要があります。

# Create a completely isolated install — no access to project node_modules
CLEAN_DIR=$(mktemp -d)
npm install --prefix "$CLEAN_DIR" agentic-qe@<version> 2>&1 | tail -5

# Test CLI commands using ONLY the isolated install's dependencies
NODE_PATH="$CLEAN_DIR/node_modules" node "$CLEAN_DIR/node_modules/.bin/aqe" --version
NODE_PATH="$CLEAN_DIR/node_modules" node "$CLEAN_DIR/node_modules/.bin/aqe" --help 2>&1 | head -5

# Cleanup
rm -rf "$CLEAN_DIR"

--version でクラッシュする場合（例：ERR_MODULE_NOT_FOUND）、リリースの依存関係に問題があります。不足しているパッケージを次のどれにすべきか調査してください。

• CLI にバンドルする（ビルドスクリプトに追加し、external から削除する）
• package.json の dependencies に追加する（実行時に必要な依存関係の場合）
• try/catch で遅延読み込みする（オプション機能でのみ必要な場合）

この手順に失敗した場合は、修正して再ビルドし、再リリースしてください。--version でクラッシュする CLI を決して公開しないでください。

停止 — 分離環境でのインストールが機能することを確認してください。

ルール

• ルートに package.json を1つだけ置きます — v3/ サブディレクトリはありません
• バージョン文字列をハードコードしないでください — 常に package.json から読み取ってください
• .claude/skills/skills-manifest.json の fleetVersion も更新してください
• 必ず実際のテストを実行してください。シミュレーションは使用しないでください
• 公開はローカルではなく GitHub Actions 経由で行います（アテステーションには --provenance を使用します）
• リリースノートはユーザーにとってわかりやすい内容にしてください — 実装の詳細ではなく、価値に焦点を当ててください
• どの手順でも予期しないことが見つかった場合は、作業を止めて、先に説明してください
• ユーザーの確認なしにタグをプッシュしたり、リリースを作成したりしないでください
• ユーザーから明示的な依頼がない限り、e2e ブラウザーテストは実行しないでください
• PR を作成する前に、すべての検証（ステップ 8）に合格する必要があります — これにより、問題が main に到達する前に発見できます
• PR 本文には、失敗モードのチェックボックスを [x] にした ### Required check (issue #401) セクションを必ず含めてください。 CI は scripts/check-pr-body.cjs でこれを強制します。テンプレート全体については .github/PULL_REQUEST_TEMPLATE.md を参照してください。
• 同じ段落内に追跡用の issue 参照（#NNN）がない限り、「可能性は低いと思います」や「これが失敗するとは思えません」など、懸念を軽視する表現は使わないでください