spec-merger

Spec Merger

バンドルされたランタイム

以下の CLI コマンドを実行する前に、先頭の SSF を node "<plugin-root>/scripts/spec-superflow.mjs" に置き換えてください。<plugin-root> は、このファイルの 2 階層上にある絶対ディレクトリです。SSF をそのまま実行したり、PATH 上の ssf を呼び出したりしないでください。

最後の executing → closing 遷移の前に、差分仕様（ADDED/MODIFIED/REMOVED/RENAMED）をメイン仕様ベースに反映する必要があります。changes/<change>/ はアクティブなワークフローのソースであり、ルートの specs/ は公開済みのベースラインに限られます。同期されていない仕様は、事実と異なる内容になります。 すでに closing にある変更を spec-merger に回してはいけません。

実行状態ガード

SSF sync またはその他の書き込みを行う前に、 SSF state get <change-dir> state を実行してください。永続化された状態が厳密に executing の場合にのみ続行してください。状態が closing の場合は「Closing は終端状態です。この変更を spec-merger に回さないでください。同期は最後の executing → closing 遷移より前に行う必要があります。」として停止してください。その他の状態の場合、または状態を読み取れない場合は、停止して workflow-start に回してください。副作用を発生させてはいけません。

事前チェック

競合の検出

SSF sync <change-dir> を実行してください。競合（同じ要件を複数の変更が修正）が検出された場合は、競合の一覧をユーザーに提示し、解決順序を確認してください。

同期プロセス

ステップ 1: 差分の特定

変更フォルダー内の各 specs/<capability>/spec.md には、## ADDED/MODIFIED/REMOVED/RENAMED Requirements の下に差分操作が記載されています。

## Purpose は、任意のトップレベルの差分拡張です。正規のメイン仕様を作成する場合にのみ使用してください。存在しない場合、または空の場合は、同期結果で決定的なデフォルトの Purpose が使用され、報告されます。これにより、従来の差分仕様も引き続き使用できます。差分の Purpose で、既存のメイン仕様の Purpose を上書きしてはいけません。

ステップ 2: 操作の適用

ADDED：要件を公開済みベースラインの ## Requirements に追加します。存在しない場合は、正規のメイン仕様を作成します。

MODIFIED：### Requirement: <name> に一致する要件を見つけ、その説明とシナリオを置き換えます。正規のベースラインに要件が存在しない場合は、問題として報告します。

REMOVED：一致する要件を公開済みベースラインから削除します。要件が存在しない場合は、問題として報告します。

RENAMED：古い名前に一致する要件を見つけ、見出しを新しい名前に変更します。新しい名前が既存の要件と衝突する場合は、問題として報告します。

ステップ 3: 競合の検出

実行前に、次の項目を検出してください。

• 同じ要件が複数の未同期の変更によって修正されている → 手動で解決
• RENAMED の変更先が既存の要件と衝突している → 手動で解決
• MODIFIED/REMOVED の対象要件が存在しない → 問題として報告

ステップ 4: マージの実行

書き込みを行う前に、すべての候補となるメイン仕様を検証してください。変更された候補のみを適用してください。操作がすでにベースラインに反映されている場合は、べき等な何もしない操作とし、書き込みが行われなかったことを報告する必要があります。操作対象が見つからず、大文字・小文字または空白だけが異なる近似一致がある場合は、何もしない操作ではなくエラーとしてください。差分仕様を削除してはいけません。追跡可能性を保つために残します。ルートのベースラインには ## Requirements を含め、## ADDED/MODIFIED/REMOVED/RENAMED Requirements の見出しを含めてはいけません。解釈できない危険な従来形式の差分のみのベースラインは、推測で処理せず拒否してください。

ステップ 5: 報告

同期レポートの表を出力してください。列は Capability、ADDED/MODIFIED/REMOVED/RENAMED の件数、Status（✓/⚠）です。合計と未解決の競合を含む概要も出力してください。

ガードレール

• 差分仕様ファイルを削除しないでください（履歴記録のため）
• 複数の変更間の競合を自動で解決しないでください
• 未検証の変更の仕様をマージしないでください
• 公開前に候補となるメイン仕様をすべて検証してください。検証に失敗した場合は、対象に何も書き込まないでください
• 意味的に同等で、すでに適用済みの操作のみを何もしない操作として扱ってください。近似した要件名は失敗としてください

同期後

1. 結果を報告します。競合がなければ、アーカイブの準備が完了しています。競合がある場合は、アーカイブする前にユーザーが解決します。
2. 変更フォルダー（差分を含む）は、追跡可能性を確保するためにそのまま残します。
3. SSF sync は、公開レシートをアクティブな変更状態に自動的に書き込みます。spec_merged を手動で設定しないでください。このレガシーマーカーは、クローズの証拠にはなりません。クローズガードは差分と公開済みベースラインのハッシュを再計算するため、その後に編集した場合は、再度同期する必要があります。
4. 変更に差分セクションがない場合、公開レシートは不要です。

例外処理

• 解析エラー：ファイルとセクションを報告します。部分的なマージは試みないでください。
• 差分なし：変更に差分セクションがない場合は、マージするものがないことを報告し、正常に終了します。
• ユーザーによる中断：再開時は、処理を続行する前にマージ競合マーカーを確認します。