openspec-archive-change

実験的なワークフローで、完了した変更をアーカイブします。

ストアの選択: ユーザーがストア（ストアとは、このマシンに登録されている独立した OpenSpec リポジトリです）を指定した場合、または作業対象がストア内にある場合は、openspec store list --json を実行して登録済みのストア ID を確認し、仕様と変更を読み書きするコマンド（new change、status、instructions、list、show、validate、archive、doctor、context、schemas、view）に --store <id> を指定してください。いったん選択したら、ワークフローの残りの間は --store <id> を引き継いでください。以下に示すこれらのコマンドの、ストアを指定していない例はすべて省略形です。実行する前にフラグを追加してください。たとえば、以下に示すストア未指定の形式ではなく、openspec status --change "<name>" --json --store "<id>" を実行してください。ほかのコマンドにはこのフラグを指定しません。コマンドが表示するヒントには、すでにフラグが含まれています。後続のコマンドでもそのまま付けてください。ストアを指定しない場合、コマンドは最も近いローカルの openspec/ ルートを対象にします。

プロジェクトの確認: ここでの手順は、すでに OpenSpec を使用しているプロジェクトを対象としています。最初に書き込みを行う手順（new change、archive、sync specs、または成果物ファイルの作成）の前に、プロジェクトにルートがあることを確認してください。openspec list --json を実行し（ストアを選択している場合は、ストアがルートとなるため --store <id> を付けます）、root を読み取ってください。ルートオブジェクトがあれば、プロジェクトはセットアップ済みです。"root": null の場合、セットアップされていません。ここに openspec/ ディレクトリはなく、openspec new change などの書き込みによって副作用として作成される可能性があります。このコマンドはゼロ以外の終了コードも返しますが、それは CLI の不具合ではなく、その状態を示すものです。再試行したり回避策を講じたりせず、JSON を読み取ってください。

次のケースに該当する場合、"root": null はセットアップに関するものではありません。status のエラーメッセージが Declared in または Invalid store declaration in で始まり、このプロジェクトの openspec/config.yaml（または config.yml）を示している場合、プロジェクトは宣言済みのストアを通じて OpenSpec を使用していますが、このマシンでは解決できません（ストアが登録されていないか、store: 行の形式が不正です）。未初期化として扱って以下の分岐に進んではいけません。書き込みの前に停止し、そのエラーの message と fix をユーザーに提示してください。

それ以外の場合、ルートがないときの次の手順は、このワークフローに至った経緯によって異なります。

• 自動選択の場合: ユーザーが OpenSpec に言及したり、このスキルを指定したり、そのスラッシュコマンドを実行したりせず、あなた自身がこのワークフローを選択した場合です。OpenSpec の使用を中止し、OpenSpec がインストールされていない場合と同様に、通常どおり依頼に回答してください。セットアップを促したり、OpenSpec のセットアップについて言及したりしないでください。
• OpenSpec を明示的にリクエストされた場合: ユーザーが OpenSpec に言及した、このスキルを指定した、またはそのスラッシュコマンドを実行した場合です。書き込みを行う前に停止し、どのように進めるかを尋ねてください。このプロジェクトをセットアップする（openspec init）、すでにあるストアを対象にする（--store <id>）、または今回のリクエストでは OpenSpec を使わずに進める、のいずれかです。回答を待ってください。

どちらの分岐でも、副作用としてルートを作成してはいけません。ユーザーに求められるまで openspec init を実行せず、openspec/ ファイルを手作業で作成せず、コマンドによって作成させることも避けてください。

<capability-path> は、specs/ からの相対パスで示す仕様ディレクトリです（例: user-auth または identity/user-auth）。メイン仕様を特定するときは、各差分仕様に記載されたパス全体を維持してください。

入力: 変更名は任意で指定できます。省略された場合は、会話の文脈から推測できるか確認してください。曖昧な場合は、利用可能な変更を必ずユーザーに尋ねてください。

手順

1. 変更を選択する

   名前が指定されている場合は、それを使用してください。指定されていない場合:

   • ユーザーが変更に言及していれば、会話の文脈から推測します
   • アクティブな変更が1つだけの場合は、自動選択します
   • 判断できない場合は、openspec list --json を実行して利用可能な変更を取得し、ユーザーに選択してもらいます

   確認を求めるときは、アーカイブ済みではないアクティブな変更のみを表示してください。 利用可能な場合は、各変更で使用されているスキーマを含めてください。

   必ず「Using change: 」と、上書き方法（例: /openspec-archive-change <other>）を案内してください。

   既存のアーカイブ確認を行う前に、現在のアーカイブ入力を読み込んでください: 選択した変更とプランニングルートを解決した後、次を実行します:

   openspec instructions archive --change "<name>" --json
   

   このコマンドでは、選択したルートのフラグを同じままにしてください。このルックアップは補助的かつ オプションです。追加のプロンプト入力を行うだけなので、アーカイブを妨げてはなりません。 終了コードが非ゼロであるか、無効な JSON を返した場合 — たとえば、このコマンドにまだ 対応していない古い CLI の場合 — コンテキストも操作ガイダンスもなしでアーカイブワークフローを 続行します。エラーを報告せず、停止もしないでください。

   成功したレスポンスでは、両方のオプションフィールドが省略される場合があります。context は 必須のプロンプトレベルの入力として扱ってください。それを読み、検討し、関連するプロジェクトの 事実、規約、制約を適用します。operationGuidance はオプションの追加的なアドバイスとして扱って ください。すべてのエントリを読み、検討し、適用可能で、組み込みのアーカイブワークフローと 互換性のあるエントリには従います。

   両方のフィールドは、組み込みのステップ、ユーザーの明示的な選択、解決されたパス、CLI チェック、 コマンド契約とは分けておいてください。コンテキストがそれらの制御入力のいずれかと競合する場合は、 競合を報告し、制御値を保持してください。ガイダンスが適用できない場合、または制御入力と競合する 場合は、それに従わず、その理由を説明してください。どちらのフィールドからも、代替パス、スキップ されたプロンプト、フラグを推測しないでください。また、ユーザーが別途要求しない限り、そのテキストを 仕様、変更アーティファクト、アーカイブサマリーにそのままコピーしないでください。これらは プロンプトレベルの動作契約であり、強制可能なチェックではありません。

2. アーティファクトの完了状態を確認する

   openspec status --change "<name>" --json を実行して、アーティファクトの完了状態を確認します。

   JSON を解析して、以下を把握します:

   • schemaName: 使用されているワークフロー
   • planningHome、changeRoot、artifactPaths、actionContext: パスとスコープのコンテキスト
   • artifacts: ステータス (done、skipped、またはその他) を持つアーティファクトのリスト

   いずれかのアーティファクトが done でも skipped でもない場合 (スキップされたアーティファクトは 要件を満たします - その変更は skip_specs を宣言しています):

   • 不完全なアーティファクトを一覧表示する警告を表示する
   • 続行してよいかユーザーに確認する
   • ユーザーが確認したら続行する

3. タスクの完了状態を確認する

   同じ選択したルートのフラグを付けて openspec list --json を実行し、changes の中から name が 選択した変更に完全一致するエントリを探します。 完全に 1 件だけ一致すること、および totalTasks と completedTasks が負でない整数であり、 completedTasks <= totalTasks であることを必須とします。CLI は、カスタムアーティファクト名、 出力パス、glob を含む、スキーマの追跡対象タスクファイルを解決します。 不完全なタスク = totalTasks - completedTasks。

   アーティファクトのステータスや、トップレベルの tasks.md の不在からタスクの完了を推測しないで ください。ルックアップが失敗した場合、無効な JSON を返した場合、選択した変更を省略または重複させた 場合、あるいは無効なカウントを返した場合は、問題を報告し、同期またはアーカイブの前に停止して ください。 CLI は x/X のチェックボックスマーカーのみを完了としてカウントします。 その他のマーカーは、なじみのないものであっても、不完全のままです。

   不完全なタスクが見つかった場合:

   • 不完全なタスクの件数を示す警告を表示する
   • 続行してよいかユーザーに確認する
   • ユーザーが確認したら続行する

   totalTasks がゼロの場合: タスク関連の警告なしで続行します。

4. デルタ仕様の同期状態を評価する

   ステータス JSON の artifactPaths.specs.existingOutputPaths を、唯一のデルタ仕様ソースとして 使用します。specs エントリが存在しないか、existingOutputPaths が空の場合は、同期プロンプト なしで続行し、他のアーティファクトからデルタ仕様を推測しないでください。 デルタスペックが存在する場合:

   • 各デルタスペックを、<planningHome.root>/openspec/specs/<capability-path>/spec.md にある対応するメインスペックと比較します（ステップ 2 のストア対応の planningHome.root を使用し、ハードコードされたリポジトリパスは使わないでください）
   • メインスペックが存在しないことは、自動的に「すでに同期済み」という意味ではありません。新しいケイパビリティの場合、メインスペックは同期の出力であり、入力ではありません:
     • デルタに MODIFIED または RENAMED の要件がある場合、新しいメインスペックを作成できるのは ADDED の要件だけであることを報告し、そのケイパビリティを同期ブロックとしてマークします。現在のバージョンを持たない要件を決してでっち上げないでください。
     • それ以外の場合、デルタに REMOVED の要件のみがあり、変更の .openspec.yaml が retire_capabilities: true を宣言しているときは、そのケイパビリティはすでに廃止されています。すでに同期済みとしてカウントし、削除するものが残っていないことを警告し、メインスペックを再作成しないでください。このルールは今も、完了した同期を検証するときも適用します。
     • それ以外の場合、デルタに ADDED の要件がないときは、同期は不可能であることを報告し、そのケイパビリティを同期ブロックとしてマークします。REMOVED のみのデルタについては、削除元となるメインスペックが存在しないことを警告し、メインスペックツリーを変更しないでください。openspec archive は、マークされていない REMOVED のみのケースを Spec must have at least one requirement で拒否します。
     • それ以外の場合は、そのケイパビリティを同期が必要としてカウントし、サマリーで名前を挙げます（<capability-path>: new main spec will be created）。デルタに REMOVED の要件もある場合は、削除元となるメインスペックが存在しないためそれらが無視されることを警告します。同期は、openspec archive が行うのとまったく同じように、デルタの ADDED の要件のみからメインスペックを作成します。
   • どのような変更が適用されるか（追加、変更、削除、名前変更）を判断します
   • 1 つが同期ブロックであっても、残りのケイパビリティの評価を続けます。プロンプトを表示する前に、統合されたサマリーを表示します。

   プロンプトの選択肢:

   • いずれかのケイパビリティが同期ブロックの場合: その理由を説明し、「Archive without syncing」「Cancel」のみを提示します
   • それ以外で、変更が必要な場合: 「Sync now (recommended)」「Archive without syncing」
   • それ以外で、すでに同期済みの場合: 「Archive now」「Sync anyway」「Cancel」

   回答に応じてルーティングします:

   • 「Cancel」 — 停止し、アーカイブしません
   • 「Archive without syncing」または「Archive now」 — アーカイブへ進みます
   • 「Sync now」または「Sync anyway」 — 同期し、その後（以下で）検証します。ケイパビリティが同期ブロックの間は同期を開始しないでください。ブロッカーを説明し、利用可能な選択肢を再度提示します。
   • それ以外 — アーカイブせずに再度尋ねます

   選択された同期がメインスペックを書き込む前に、同じ選択済みルートのフラグを付けて openspec instructions specs --change "<name>" --json を一度実行します。終了ステータスがゼロで、有効な artifact-instruction JSON であることを必須とします。ルックアップが失敗するか無効な JSON を返した場合は、エラーを報告し、 メインスペックを書き込む前、または変更を移動する前に停止します。rules が省略された有効なレスポンスは、ルールなしのケースです。返された rules は、このマージで生成されるメインスペックの内容と形式にのみ適用します。アーカイブのガイダンスとして使ったり、CLI の動作を変更したり、ルールのテキストを出力ファイルにコピーしたりしないでください。

   次に、変更 '' に対して openspec-sync-specs ワークフローをインラインで（エージェント駆動のインテリジェントマージとして）実行し、上記のデルタスペック分析と取得した specs ルールのスナップショットを渡して、完了するまで待ちます。インライン同期は、specs 命令を再度取得することなく、そのスナップショットを再利用しなければなりません。これをバックグラウンドタスクに委任しないでください。ステップ 5 は、まだそれを読み取っている同期の下から changeRoot を移動させてしまい、変更がアーカイブされ、メインスペックが更新されないままになります。エージェントが委任によってのみ実行できる場合は、同期的に委任し、結果を待ちます。

   同期が停止またはブロック条件を報告した場合は、同期を失敗として扱います。 アーカイブを直ちに停止します。同期後の内容比較を行わず、その changeRoot を移動しないでください。 何も移動していないため、ユーザーはブロック条件を修正するか、同期を再実行できます。 同期が各メイン仕様を書き込んだ後、正規の同期コントラクトに照らしてその構造を検証します:

   • 新しいメイン仕様は # <capability> Specification というタイトルで始まります。既存のメイン仕様はタイトルをそのまま正確に維持します。
   • 確立されたメイン仕様では、既存の ## Purpose セクションを完全にそのまま保持します。
   • 新しいメイン仕様の場合、デルタの ## Purpose をそのままコピーします。目的のテキストが標準の検証で期待される長さより短い場合にのみ警告します。既存の作成済みの目的を再生成したり書き換えたりしないでください。使用可能な ## Purpose が提供されていない場合は、既存の TBD Purpose の動作と警告を使用します。
   • メイン仕様にデルタ形式のセクション見出し(## ADDED Requirements、## MODIFIED Requirements、## REMOVED Requirements、## RENAMED Requirements)が残っていないことを確認し、同期ワークフローのフォーマット規則に厳密に従います。
   • 同期が書き込んだ、または変更した要件ブロックは ### Requirement: 見出しを使用し、そのシナリオは仕様の ## Requirements セクションの下で #### Scenario: 見出しを使用します。デルタが言及していない内容はそのまま正確に残します。

   次に、このステップの冒頭からの比較を、明示的に廃止された、仕様が欠落しているケースも含めて、artifactPaths.specs.existingOutputPaths 内にデルタ仕様があるすべてのケイパビリティに対して再実行します — 同期が変更したと報告したものだけではありません。同期が成功すれば適用すべきものは何も残らないため、各ケイパビリティは今や同期済みとして読み取れなければなりません:

   • ADDED 要件が存在する
   • MODIFIED 要件が、デルタで指定されたシナリオと説明の変更を伴って存在し、その他のシナリオはそのまま維持されている
   • REMOVED 要件が削除されている — そして、この同期でケイパビリティを廃止した場合(最後の要件を削除し、## Requirements を空のままにした場合)、そのメイン仕様は空のまま残されるのではなく削除されている。
   • RENAMED 要件が新しい名前で存在し、古い名前では存在しない

   同期が失敗した場合、またはいずれかのケイパビリティが一致しない場合は、異なる点を報告して停止します — アーカイブしないでください。何も移動されておらず changeRoot はそのままなので、ユーザーは不一致を修正するか、同期を再実行してアーカイブを最初からやり直すことができます。

5. アーカイブを実行する

   planningHome.changesDir の下に archive ディレクトリが存在しない場合は作成します:

   mkdir -p "<planningHome.changesDir>/archive"
   

   ターゲット名を生成します: 変更名がすでに YYYY-MM-DD- プレフィックスで始まっている場合はそのまま使用し、そうでない場合は現在の日付を YYYY-MM-DD-<change-name> として先頭に付けます。2 つ目の日付を重ねないでください(openspec archive と同じ規則)。

   ターゲットがすでに存在するか確認する:

   • 存在する場合: エラーで失敗し、既存のアーカイブの名前を変更するか、別の日付を使用することを提案します
   • 存在しない場合: changeRoot をアーカイブディレクトリへ移動します

   mv "<changeRoot>" "<planningHome.changesDir>/archive/<target-name>"
   

6. サマリーを表示する

   以下を含むアーカイブ完了サマリーを表示します:

   • 変更名
   • 使用されたスキーマ
   • アーカイブの場所
   • 仕様が同期されたかどうか(該当する場合)
   • 警告に関する注記(不完全なアーティファクト/タスク)

成功時の出力

## Archive Complete

**Change:** <change-name>
**Schema:** <schema-name>
**Archived to:** the archive path derived from `planningHome.changesDir`/<target-name>/
**Specs:** <"✓ Synced to main specs" only if the step 4 verification passed; otherwise "No delta specs" or "Sync skipped">

<"All artifacts complete. All tasks complete." — or, if archived with warnings, list them instead (e.g. "Archived with 2 incomplete tasks")>

ガードレール

• 選択した変更を通知します。不明確な場合は、選択を促します
• 完了確認にはアーティファクトグラフ（openspec status --json）を使用します
• 警告があってもアーカイブを妨げず、通知して確認するだけにします
• アーカイブに移動する際は、.openspec.yaml を保持します（ディレクトリと一緒に移動します）
• 実行内容を明確に要約して表示します
• 同期が要求された場合は、openspec-sync-specs ワークフローをインラインで実行します（エージェント主導）
• 仕様の同期が進行中の間は、アーカイブしないでください。同期をインラインで実行し、メインの仕様を確認してから changeRoot を移動します
• 差分仕様が存在する場合は、必ず同期評価を実行し、プロンプトを表示する前に統合した要約を示します
• 関連する実行時コンテキストを適用して、競合を報告します。操作ガイダンスはあくまで参考情報です
• ガイダンスの各項目をすべて検討し、適用できない助言や競合する助言について説明します
• 既存の CLI チェック、解決済みのパス、プロンプト、コマンドの契約は変更しません
• アーティファクトルールは、作成する仕様のみに適用され、操作ガイダンスには適用されません
• 実行時コンテキスト、操作ガイダンス、アーティファクトルールの文面を、そのまま出力ファイルにコピーしないでください