release

リリース調整スキル

npm への公開だけではなく、Paperclip メンテナー向けの完全なリリースワークフローを実行します。

このスキルでは、次の作業を調整します。

• release-changelog による安定版変更履歴の作成
• master からのカナリア検証と公開状況の確認
• scripts/docker-onboard-smoke.sh による Docker スモークテスト
• 選択したソース参照からの手動による安定版への昇格
• GitHub Release の作成
• ウェブサイト／告知のフォローアップタスク
• リリースコンテンツの Cases でのドッグフーディング：トップレベルの release ケースと、その子となる blog_post および tweet_storm ケースを作成し、すべてリリースの issue／run にリンクします

トリガー

リーダーから次のような依頼があった場合に、このスキルを使用します。

• 「リリースしてください」
• 「リリースを出してください」
• 「このカナリアを安定版に昇格してください」
• 「安定版リリースを作成してください」

前提条件

作業を進める前に、次のすべてを確認してください。

1. .agents/skills/release-changelog/SKILL.md が存在し、使用可能であること。
2. 未追跡ファイルも含め、リポジトリの作業ツリーがクリーンであること。
3. 最後の安定版タグ以降に、カナリアまたは候補となるコミットが少なくとも1つあること。
4. 候補の SHA が検証ゲートに合格しているか、まもなく合格すること。
5. マニフェストが変更されている場合、CI が管理する pnpm-lock.yaml の更新がすでに master にマージされていること。
6. GitHub Trusted Publishing を通じた npm の公開権限、または緊急時／手動で使用するローカルの npm 認証情報が利用可能であること。
7. Paperclip 経由で実行する場合、ステータス更新とフォローアップタスクの作成に必要な issue のコンテキストがあること。

前提条件を満たさない場合は、作業を中止して阻害要因を報告してください。

入力

事前に次の情報を集めてください。

• 対象がカナリアの確認か、安定版への昇格か
• 安定版の候補となる source_ref
• 安定版の実行がドライランか本番実行か
• ウェブサイトと告知のフォローアップに必要なリリース issue／会社のコンテキスト

ステップ 0 — リリースモデル

Paperclip は現在、コミット主導のリリースモデルを採用しています。

1. master へのプッシュごとに、カナリアが自動的に公開されます。
2. カナリアでは YYYY.MDD.P-canary.N を使用します。
3. 安定版リリースでは YYYY.MDD.P を使用します。
4. 中央のスロットは MDD で、M は UTC の月、DD はゼロ埋めした UTC の日です。
5. 同じ UTC 日に複数の安定版を公開する場合、安定版のパッチスロットを増やします。
6. 安定版リリースは、選択したテスト済みコミットまたはカナリアのソースコミットから手動で昇格します。
7. releases/vYYYY.MDD.P.md、Git タグ vYYYY.MDD.P、GitHub Release が作成されるのは安定版リリースのみです。

重要な点：

• リリースブランチを既定の手順として使用しないでください。
• メジャー／マイナー／パッチのバージョンアップを決めないでください。
• カナリアの変更履歴ファイルを作成しないでください。
• カナリアの GitHub Release を作成しないでください。

ステップ 1 — 候補の選択

カナリアを検証する場合：

• master 上の最新の成功したカナリア実行を確認します。
• カナリアのバージョンとソース SHA を記録します。

安定版へ昇格する場合：

1. テスト済みのソース参照を選択します。
2. 昇格する対象が正確にその SHA であることを確認します。
3. ./scripts/release.sh stable --date YYYY-MM-DD --print-version で安定版のバージョンを決定します。

便利なコマンド：

git tag --list 'v*' --sort=-version:refname | head -1
git log --oneline --no-merges
npm view paperclipai@canary version

ステップ 2 — 安定版の変更履歴を作成する

安定版の変更履歴ファイルは、次の場所にあります。

• releases/vYYYY.MDD.P.md

release-changelog を実行し、安定版のリリースノートのみを生成または更新します。

ルール：

• 公開前に、人が下書きを確認します。
• ファイルがすでに存在する場合は、手動での編集内容を保持します。
• ファイル名は安定版専用のままにします。
• カナリアの変更履歴ファイルは作成しないでください。

ステップ 3 — 候補 SHA を検証する

標準ゲートを実行します。

pnpm -r typecheck
pnpm test:run
pnpm build

GitHub リリースワークフローで公開する場合、このゲートを再実行できます。それでも、ローカルで確認した場合はその状況を報告してください。

リリースロジックに触れる PR では、リポジトリの CI でもカナリアリリースのドライランを実行します。これはリリース固有のガードであり、標準ゲートの代わりにはなりません。

ステップ 4 — カナリアを検証する

通常のカナリア公開は、次のワークフローによって master から自動的に行われます。

• .github/workflows/release.yml

次の点を確認します。

1. 検証に合格していること。
2. npm へのカナリア公開が成功していること。
3. Git タグ canary/vYYYY.MDD.P-canary.N が存在すること。

便利な確認コマンド：

npm view paperclipai@canary version
git tag --list 'canary/v*' --sort=-version:refname | head -5

ステップ 5 — カナリアをスモークテストする

実行します。

PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh

分離して実行する場合に便利なバリアント：

HOST_PORT=3232 DATA_DIR=./data/release-smoke-canary PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh

以下を確認します。

1. インストールが成功する
2. クラッシュせずにオンボーディングが完了する
3. サーバーが起動する
4. UI が読み込まれる
5. 基本的な会社の作成とダッシュボードの読み込みが機能する

スモークテストに失敗した場合：

• 安定版リリースを停止します
• master で問題を修正します
• 次の自動カナリアを待ちます
• スモークテストを再実行します

ステップ 6 — 安定版をプレビューまたは公開する

通常の安定版リリース手順では、以下で手動の workflow_dispatch を実行します。

• .github/workflows/release.yml

入力項目：

• source_ref
• stable_date
• dry_run

安定版を本番公開する前に：

1. ./scripts/release.sh stable --date YYYY-MM-DD --print-version で対象の安定版バージョンを確定します
2. ソースリファレンスに releases/vYYYY.MDD.P.md が存在することを確認します
3. 実施可能な場合は、まず安定版ワークフローをドライランモードで実行します
4. 次に実際の安定版公開を実行します

安定版ワークフローでは、以下を行います。

• 正確なソースリファレンスを再検証します
• 選択した UTC 日付の次の安定版パッチ枠を計算します
• YYYY.MDD.P を dist-tag latest で公開します
• git タグ vYYYY.MDD.P を作成します
• releases/vYYYY.MDD.P.md を使用して GitHub Release を作成または更新します

ローカルでの緊急時／手動コマンド：

./scripts/release.sh stable --dry-run
./scripts/release.sh stable
git push public-gh refs/tags/vYYYY.MDD.P
./scripts/create-github-release.sh YYYY.MDD.P

ステップ 7 — その他の公開面を仕上げる

以下の後続作業を作成または確認します。

• ウェブサイトの変更履歴の公開
• リリース告知記事／ソーシャルメディアでの告知
• Paperclip の課題コンテキストでのリリース概要

これらではカナリアではなく、安定版リリースを参照してください。

ステップ 8 — リリースコンテンツのケースを作成する

Cases が有効な場合、安定版リリースコンテンツの実行ごとに、決定的なケースツリーを作成する必要があります。これはリリースの実地検証手順の一部であり、任意の成果物ではありません。API が 403 Cases are disabled を返した場合は停止し、オペレーターが experimental.enableCases を有効にする必要があることを報告してください。

現在のリリース課題の PAPERCLIP_COMPANY_ID、PAPERCLIP_API_URL、PAPERCLIP_API_KEY、PAPERCLIP_RUN_ID を使用します。すべての書き込みに X-Paperclip-Run-Id を含め、ケースのアクティビティフィードで実行元の課題を特定できるようにします。

最初に親の release ケースを作成またはアップサートします。

POST /api/companies/:companyId/cases
{
  "caseType": "release",
  "key": "paperclip-release:vYYYY.MDD.P",
  "title": "Paperclip vYYYY.MDD.P release",
  "summary": "Stable release content package for Paperclip vYYYY.MDD.P.",
  "status": "in_progress",
  "fields": {
    "schema_version": 1,
    "version": "vYYYY.MDD.P",
    "release_date": "YYYY-MM-DD",
    "source_ref": "git-sha-or-ref",
    "stable": true,
    "channels": ["changelog", "blog_post", "tweet_storm"],
    "artifacts": {
      "changelog_path": "releases/vYYYY.MDD.P.md",
      "github_release_url": null
    },
    "verification": {
      "typecheck": "unknown",
      "tests": "unknown",
      "build": "unknown",
      "smoke": "unknown"
    },
    "notes": null
  }
}

fields スキーマでは、文字列、数値、ブール値、配列、オブジェクト、null など、すべての汎用 JSON 値型を意図的に使用します。ケースのフィールドはオブジェクト全体が置き換えられるため、各アップサートで fields オブジェクト全体を送信してください。

アップサートの直後に、親の本文ドキュメントを書き込みます。

PUT /api/cases/:releaseCaseId/documents/body
{
  "title": "Paperclip vYYYY.MDD.P release body",
  "format": "markdown",
  "body": "# Paperclip vYYYY.MDD.P\n\nRelease summary and links...",
  "changeSummary": "Initial release case body"
}

次に、parentCaseId をリリースケースの ID に設定して、以下の子ケースを作成またはアップサートします。

• blog_post、キー paperclip-release:vYYYY.MDD.P:blog-post、ステータス in_progress、本文ドキュメントキー body
• tweet_storm、キー paperclip-release:vYYYY.MDD.P:tweet-storm、ステータス in_progress、本文ドキュメントキー body

決定的なキーを正確に使用し、リリースコンテンツのフローを再実行しても重複作成せず、同じ 3 件のケースをアップサートするようにします。子ケースの本文ドキュメントを書き込んだ後、作成されたケースの識別子とリンクを、リリース課題と、存在する場合は親の受け入れ課題に記載します。

失敗時の対応

カナリアに問題がある場合：

• 安定版を公開せず、別のカナリアを公開します

安定版の npm 公開は成功したものの、タグのプッシュまたは GitHub Release の作成に失敗した場合：

• 同じリリース結果から、git／GitHub の問題を直ちに修正します
• 同じバージョンを再公開しないでください

安定版の公開後に latest に問題がある場合：

./scripts/rollback-latest.sh <last-good-version>

その後、新しい安定版リリースで修正します。

出力

スキルの完了時に、以下を提示します。

• 候補 SHA とテスト済みカナリアバージョン（該当する場合）
• 安定版バージョン（昇格した場合）
• 検証ステータス
• npm のステータス
• スモークテストのステータス
• git タグ／GitHub Release のステータス
• ウェブサイト／告知の後続作業のステータス
• リリースコンテンツのケースツリーへのリンク：親の release ケースと、子の blog_post および tweet_storm
• 一部でも未完了の場合のロールバックの推奨事項