changelog

changelog

現在のブランチについて、changelog/YYYYMMDD-HHMMSS-<slug>.md に変更履歴エントリーを生成または更新します。Git と差分からメタデータを導き出し、フロントマターと分類別にグループ化した本文を記述し、決定的な補完スクリプトを実行してから、結果を検証します。

このスキルは、有効な変更履歴エントリーの内容に関する唯一の信頼できる情報源です。フロントマターのスキーマ、フィールドの所有範囲、冪等な更新と新規作成、検証ゲートを定義します。同じ契約は、利用側リポジトリの CI と、マージ後のフィールドを補完するマージ後エンリッチャー（@rheged-studio/changelog-core。リポジトリ内で reusable-changelog-enrich.yml によって実行され、中央のリリースオーケストレーターのステップではなくなりました）によって、後続工程でも適用されます。そのため、作成ルールはここに一元化されています。

次の 2 つの方法で実行されます。

• 単独実行（/changelog）— このブランチのエントリーを作成、更新、修復し、レビュー用に未コミットのまま作業ツリーに残します。コミット、プッシュ、PR は行いません。
• 出荷フロー内（例：/send-it）— プッシュ前に実行される変更履歴ステップです。出荷フローがエントリーをコミットし、プッシュして、PR を作成します。

設定

設定はこのファイルと同じ場所にある config.json に記述されています。同梱スクリプトが自動的に読み込みます。利用側リポジトリに合わせて、コピーした config.json を編集してください（テンプレートとして、中立的な config.example.json が同梱されています）。issueKeys と linearWorkspaceSlug は必須で、デフォルト値はありません。そのため、config.json がない場合や、どちらかのキーが欠けている場合、スクリプトは ACME の識別情報を暗黙に引き継ぐのではなく、明確にエラーを出して失敗します。その他は構造的な設定で、汎用的な上書き可能なデフォルト値が設定されています。

キー	意味	デフォルト
issueKeys	ブランチと本文から課題 ID を認識するためのチームキー接頭辞。リポジトリが扱うすべてのチームを指定します（例：["R"]、または Cadogan にまたがるリポジトリでは ["C", "R"]）。課題 ID の正規表現はこれらの値から生成されます。	必須
linearWorkspaceSlug	課題リンク（https://linear.app/<slug>/issue/<id>）の生成に使う Linear ワークスペースのスラッグ。	必須
baseBranch	ブランチの差分を取る対象となる trunk（origin/<baseBranch>）。実行ごとに BASE_REF 環境変数で上書きできます。	"main"
changelogDir	日付付きエントリーを格納するディレクトリ（補完スクリプトと検証スクリプトが走査します）。	"changelog"
packageRoots	モノレポのディレクトリ接頭辞。<root>/<x>/… を、affected_packages の導出時にパッケージ <x> に対応付けます。	["apps", "packages", "services"]
fallbackPackage	packageRoots のどの接頭辞にも一致しない変更パスに使うパッケージ名。	"infrastructure"
affectedPackages	affected_packages フィールドを出力するかどうか。単一パッケージのリポジトリでは false のままにします（このフィールドは書き込み専用で冗長なため、エントリーを簡潔に保てます）。実際のモノレポでは true に設定します。rheged-skills-setup はワークスペース設定を検出すると、この値を有効にします。	false

同梱されているすべてのスクリプトは Node の組み込み機能のみを使用し、npm install もビルド手順も不要です。これらのスクリプトは利用側リポジトリのルートにある changelog/ ディレクトリを対象とするため、リポジトリのルートから実行してください。

実行方法

ステップ 1 — 既存エントリーの検出（冪等性）

changelog/ を検索し、フロントマターに branch: "<current-branch>" を含むファイルを探します。一致するファイルがちょうど 1 つなら、更新モードです。created_at とファイル名を保持し、残りを書き換えます。それ以外の場合は、新規作成モードです。

ステップ 2 — ブランチを分析する

• git log origin/<base>..HEAD --pretty=full — 本文とトレーラーを含むコミット一覧全体。
• git diff origin/<base>...HEAD --name-only — 変更されたファイル。本文をパッケージごとにグループ化するために使います。

<base> は config.json の baseBranch（デフォルトは main）です。差分を正確にするため、先にフェッチします（git fetch origin <base>）。呼び出し元がすでにフェッチ済みの場合（例：出荷フローが事前確認のステップでフェッチする場合）は、フェッチを省略してください。

複数コミットとマージコミットの安全性（R-825）

複数コミットのフィーチャーブランチとマージマージ（スクワッシュ／リベースマージも含む）において、作成とマージ後の拡充を安全に行えます。

• コミットごとではなく、ブランチごとに1つのエントリー。 ステップ1ではフロントマターの branch: で検索します。中間コミットの後に /changelog を再実行すると、同じ日付のファイルが更新されます。同じブランチに対して2つ目のエントリーが作成されることはありません。
• ブランチの分析はPR全体にわたります。 ステップ2では git log origin/<base>..HEAD（および対称差分）を使うため、マージ前に何件のコミットがあっても、フィーチャーブランチ上のすべてのコミットがメタデータと本文の生成に反映されます。
• マージ後の commit はトランクへのマージSHAです。 最終処理／拡充では、commit にマージ済みPRの mergeCommit.oid の先頭7文字、つまり実際にトランクに取り込まれたコミットを設定します。マージマージでは2つの親を持つマージコミット、スクワッシュでは単一のスクワッシュコミット（フィーチャーブランチの先端とは異なります）です。
• stats.commits はマージによるノイズではなく、PRで作成した作業のコミット数を数えます。 PRのコミットRESTエンドポイントを調べ、親が2つ以上あるコミット（ブランチ main のマージ解決コミット）を除外するため、ときどきマージコミットが含まれる複数コミットのブランチでも、作成したコミット数が正しく報告されます。

ステップ 3 — メタデータを導出する

フィールド	導出方法
issues	issueKeysから取得します。ブランチの先頭IDのみ（大文字に変換。extractBranchIssueIdを使用するため、-c-2-のようなスラッグトークンは無視されます）に加え、コミットの件名／本文に含まれる issue ID 正規表現のすべての一致（buildIssueRe）を含めます。重複は削除します。
author	git config user.email。
co_authors	ブランチのすべてのコミットからCo-authored-by: Name <email>トレーラーを解析します。メールアドレス、またはName <email>形式で保存します。該当がない場合は空の配列です。
category	コミットの件名と差分から推定します。feature、fix、chore、docs、refactor、perfのいずれかです。判断が難しい場合は、ユーザーに確認を求めます。
breaking	BREAKING CHANGE:トレーラー、conventional commitの件名に含まれる!、または公開インターフェースの削除から推定します。不明確な場合はユーザーに確認します。デフォルトはfalseです。
release_note	titleとは異なる、ユーザー向けの1文の要約です。省略可能です。変更にユーザー向けの影響がない場合（chore、内部リファクタリング）は空欄のままにします。

フィールドの所有権 — このスキルが作成するフィールドと変更してはならないフィールドを定めることが、この契約の要点です。すべてのルールについてはreferences/changelog-contract.mdを参照してください。要約すると、次のとおりです。

• このスキルで作成するフィールド： title、release_note、category、breaking、issues、 co_authors、author、および**affectedPackagesが有効な場合のみ**、 affected_packages（手動編集ではなく、ステップ 5 のエンリッチメントスクリプトが 書き込みます）。単一パッケージのリポジトリではaffectedPackages: false（ デフォルト）のままにし、フィールド自体を省略します。
• created_atは変更禁止です — 作成時に一度だけ設定します（初回実行時のUTC時刻）。更新時は、 値をそのまま保持します。
• このスキルでは決して作成しないフィールド： stats（files_changed、loc_added、loc_removed、 commits）およびマージ後のフィールドmerged_at／commit／pr。マージ後 のエンリッチャーは、マージ後に正規のGitHub PRデータを基にこれらの値を確定します。prも含まれ、 マージされたPRのbranch:から解決されます（shipフローでは決して書き込みません）。commitは mergeCommit.oidの短縮SHA（trunkへのマージコミット）です。stats.commitsは PRブランチのマージ以外のコミット数です（上記の複数コミットとマージコミットの安全性 を参照）。作成時はマージ後のフィールドに空のプレースホルダーを出力し、更新時は 既存の値を変更せずに保持します。

このスキルは、引き継ぎ情報として導出したissues配列を出力します。shipフローは これをPR本文やLinearへの書き戻し（たとえばlinear-syncスキルを介した処理）に再利用します。

Step 4 — 本文を生成する

箇条書きをパッケージごとにまとめ、## Added／## Changed／## Fixed の下に分類します。 項目がある見出しのみを含めます。複数のパッケージにまたがる変更には、 **<pkg-name>:** のサブ見出しを使用します。

breaking: true の場合、本文は変更内容と移行方法を説明する ## Breaking セクションから始める必要があります。

title、release_note、本文の文章は、利用先リポジトリで文書化されている文章の言語で記述します。このリポジトリ群では、イギリス英語（colour、behaviour、-ise／-yse）を使用します。対象は文章のみで、識別子、依存関係名、上流 API のフィールド名は含みません。

Step 5 — ファイルを作成または更新する

ファイル名： changelog/YYYYMMDD-HHMMSS-<slug>.md。タイムスタンプは created_at（初回実行時の UTC 時刻）を使用し、スラッグは title に基づいて生成します（小文字にし、英数字以外を - に置換し、連続する - をまとめ、単語の境界で約 60 文字に制限します）。

タイムスタンプ文字列は、YAML 内では必ず引用符で囲みます（created_at: "2026-04-26T13:24:00Z"）。引用符のない ISO タイムスタンプは Date オブジェクトとして解析され、エンリッチメントの往復処理で .000Z のミリ秒が付加されます。引用符で囲むことで、値が変わらず保持されます。

更新時： created_at とファイル名を維持し、title、 release_note、category、breaking、co_authors、issues、本文を 書き換えます。merged_at／commit／pr／stats は変更しません（これらは マージ後のエンリッチャーが入力し、pr はブランチから解決されます）。

フロントマターのフィールド順序は、 references/changelog-contract.md に示されたものを使用します。affectedPackages が有効な場合に限り、プレースホルダーとして affected_packages: [] を出力します。スクリプトがその箇所を埋めます。無効な場合（単一パッケージの既定設定）は、このフィールドを省略します。set-affected-packages.mjs は何も行いません。

次に、利用先リポジトリのルートから、2 つの決定的なエンリッチメントスクリプトを実行します（どちらも冪等です。branch: フロントマターでエントリーを照合し、マージ後のフィールドは空のままにします）。

node skills/changelog/scripts/set-affected-packages.mjs   # writes affected_packages from the branch diff
node skills/changelog/scripts/add-links.mjs               # rewrites bare issue IDs in the current branch's entry to Linear URLs

スキルを別の場所にインストールした場合は、パスのプレフィックスを調整してください。

どちらのエンリッチャーも --check（--dry-run の別名）を受け付けます。これは読み取り専用のプレビューで、変更内容を報告するだけで、書き込みは行いません。エントリーが最新の場合は 0、書き換えが必要な場合は 1 を終了コードとして返します（prettier --check と同じ形式のため、CI のゲートとして使用できます）。

node skills/changelog/scripts/set-affected-packages.mjs --check   # current branch's entry only
node skills/changelog/scripts/add-links.mjs --check               # ALL entries in the changelog dir

どちらのエンリッチャーも、既定では ブランチ単位で動作します（R-603）。引数を指定せずに add-links.mjs を実行すると、現在の Git ブランチと branch: フロントマターが一致するエントリーのみを書き換えるため、新しいエントリーを作成しても、無関係なマージ済みエントリーが変更されることはありません。ディレクトリ全体を走査するモードは 2 つあります。--all（意図的にディレクトリ全体を書き換える場合）と、--check／--dry-run（過去のエントリーによって終了コードが 1 になる場合もある、完全性のゲート）です。ディレクトリ全体がエンリッチ済みであることを確認するには --check を使用し、1 つのブランチのエントリーを対象とする PR ごとの処理には既定の動作を使用します。（Git を利用できない場合、既定の動作は全体の走査にフォールバックします。）

Step 6 — コントラクトに照らして検証する

この検証がゲートとなります。

node skills/changelog/scripts/preflight-changelog-ci.mjs   # optional: checks Node vs engines/.nvmrc, then pnpm install --frozen-lockfile
node skills/changelog/scripts/validate-changelog.mjs       # validates frontmatter schema, filename format, field types, ISO timestamps, Breaking section, issue IDs

preflight-changelog-ci.mjs は省略可能で、pnpm 固有です。利用先リポジトリで pnpm を使用していない場合はスキップしてください。失敗した場合は処理を止めて、続行する前にエントリーを修正します。不正なエントリーをリリースフローに渡してはいけません。

単独実行とリリースフロー内での実行

• 単独実行（/changelog）では、Step 1〜6 を実行してから報告し、エントリーを作業ツリー内に未コミットのまま残します。ユーザーが確認してコミットできます。プッシュや PR の作成は行いません。
• リリースフロー内では、同じ手順をプッシュ前に実行します。その後、リリースフローがエントリーをコミットし（docs(changelog): <title>）、プッシュして、PR を作成または更新します。pr は空のままにします。マージ後のエンリッチャーが、マージされた PR からブランチを基に解決して入力します。

実装

変更履歴のライフサイクルに必要なすべてのスクリプトは、このバンドル内の scripts/ にあり、通常の Node で実行できます（npm の依存関係やビルド手順は不要です）。これらはこのバンドルが担うライフサイクル全体をカバーします。作成（このスキルが実行）と、マージ後の最終処理／CI ロジック（そのロジックの現在の実行場所については、以下の注記を参照）の両方です。各スクリプトは --help（使い方を表示し、終了コード 0 を返す）と --self-test（純粋なロジックをオフラインでスモークテストする）を受け付けます。ファイルを書き込むスクリプトは、--check／--dry-run（結果を報告し、書き込みは行わない）も受け付けます。

作成 — このスキル（/changelog フロー）が実行：

• scripts/set-affected-packages.mjs — ブランチの差分から affected_packages を書き込みます（モノレポの利用者のみ。affectedPackages がオフの場合は何もしません）。
• scripts/add-links.mjs — 本文内のプレーンなイシュー ID を Linear の URL に書き換えます。
• scripts/preflight-changelog-ci.mjs — 任意の Node／ロックファイルによる CI 同等性チェック（pnpm）を行います。
• scripts/validate-changelog.mjs — コントラクトに照らしてエントリーを検証します。

マージ後の最終処理と CI ゲート — 現在は @rheged-studio/changelog-core から実行されます。 最終処理／拡充／完全性チェックのロジックは、公開済みの @rheged-studio/changelog-core パッケージに切り出されています（CLI：validate | enrich | finalise | set-affected-packages | add-links | backfill-commits | check-completeness）。リポジトリ内のマージ後の拡充は、shared-workflows の reusable-changelog-enrich.yml（npm ターゲットでは mode: finalise、deploy ターゲットでは mode: enrich）を通じて実行されます。これは changelog-core を呼び出し、結果を road-runner-bot[bot] として書き戻します。CI の validate と完全性ゲートは、changelog-core validate／changelog-core check-completeness を呼び出します。これにより、以前の release-orchestrator のインライン最終処理ステップと、廃止された毎日実行の enrich-changelogs.yml cron（R-801）が置き換えられました — 現在は中央のオーケストレーターも cron も、これらを実行しません。

以下の同等のバンドル済みスクリプトは、依存関係ゼロの元の実装です。 引き続き公開されるスキルのソースであり（ここでも --help／--self-test が実行されます）、 利用者はこれらを直接組み込むことができます。ただし、shared workflow の利用者がこのロジックを使う場合、これらのファイルではなく changelog-core から取得します：

• scripts/finalise-changelog.mjs — npm ターゲットのリリース時の情報補完とバージョンの記録を行います。最終処理前の各エントリーについて、gh／git を使ってマージ済み PR を特定し、マージ後のフィールド（merged_at／commit／pr／stats。最後の stats には、PR のコミット API から取得するマージ対象外の commits 数も含まれます）を入力します。続いて、更新直後の package.json のバージョンを version に記録し、単独で記載された Linear ID にリンクを付けます。lib/enrich.mjs（PR メタデータの入力）、lib/commit-count.mjs（マージ対象外のコミット数）、lib/stamp.mjs（バージョンの記録）を組み合わせています。
• scripts/enrich-changelog.mjs — デプロイターゲット（octavo、shared-workflows）のマージ後の情報補完を行います。これらはリリースフロー中にチェックアウトされないため、インラインで最終処理できません。環境変数インターフェース（BRANCH_NAME／MERGED_AT／MERGE_SHA／PR_NUMBER／ADDITIONS／DELETIONS／CHANGED_FILES）からマージ済み PR 1 件分のデータを読み込み、branch: でエントリーを特定して、finalise と同じマージ後フィールド群を入力します。ただし、デプロイターゲット独自のタグ付けフローで管理される version と、enrich では特定しない commits は除きます。lib/enrich.mjs を薄くラップしたもので、一度だけ入力する冪等な処理のため、安全に再実行できます。エントリーにまだ情報補完が必要な場合、--check は終了コード 1 で終了します。--dry-run ではプレビューを表示します。
• scripts/check-changelog-completeness.mjs — CI の完全性ゲートです。リリースをトリガーする（feat／fix／breaking）PR タイトルには、日付入りの changelog/ エントリーが必要です。ない場合、ビルドは失敗します。
• scripts/backfill-commits.mjs — 既存の changelog/ のバックログ全体に stats.commits を一度だけ補完するスクリプトです（後からコミット数を導入する場合に使います）。gh で各エントリーのマージ済み PR を特定し、commits の行だけを挿入します（再シリアライズは行いません）。冪等で、--dry-run ではプレビューを表示します。作成フローにもリリースフローにも含まれません。

これらのスクリプトは、scripts/lib/ のヘルパー（changelog.mjs、derive-packages.mjs、 frontmatter.mjs、config.mjs、enrich.mjs、commit-count.mjs、stamp.mjs）を共有します。このため、このスキルの範囲は作成と検証までで、マージ後のフィールドは空欄のままにします。マージ後のフィールドは、/changelog フローではなく、マージ後に changelog-core（reusable-changelog-enrich.yml 経由）が入力します。

採用者への注意: これらのスクリプトのユニットテストは、スキルに同梱されておらず、agent-skills リポジトリで管理されています。スキルの README を参照してください。