openspec-archive-change

Imported from fujiihiroaki/json-cli-formatter (.factory/skills/openspec-archive-change/SKILL.md). Install upstream with npx skills add fujiihiroaki/json-cli-formatter --skill openspec-archive-change. Copyright stays with the author (MIT).

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

ストアの選択: ユーザーがストア（この端末に登録された独立した 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/ ルートを対象にします。

<capability-path> は specs/ からの相対仕様ディレクトリです（例: user-auth または identity/user-auth）。各仕様差分から本仕様を解決するときは、完全なパスを維持します。

入力: 必要に応じて、変更名を指定します。省略した場合は、会話の文脈から推測できるかどうかを確認します。曖昧またはあいまいな場合は、利用可能な変更を要求する必要があります。

手順

1. 変更を選択する

   名前が指定されていれば使用します。それ以外の場合:

   • 会話で変更に言及していれば、そのコンテキストから推測する
   • アクティブな変更が1つだけなら自動選択する
   • 曖昧なら openspec list --json で利用可能な変更を取得し、ユーザーに選択してもらう

   選択を求める場合は、アーカイブ済みではないアクティブな変更だけを表示します。 利用可能であれば、各変更で使用するスキーマも含めます。

   必ず「使用する変更: 」と、変更方法（例: /opsx-archive <other>）を伝えます。

   既存のarchive検査の前に、現在のarchive入力を読み込む:

   選択した変更とplanning rootを解決した後、次を実行します:

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

   このコマンドでも、選択したルートのフラグを維持します。この検索は参考情報を得る任意の処理です。 追加のプロンプト入力を提供するだけなので、archiveをブロックしてはいけません。 このコマンドに未対応の古いCLIなどで、終了コードが0以外または無効なJSONが返された場合は、 contextとoperation guidanceなしでarchiveワークフローを続行します。エラーを報告せず、停止もしません。

   成功したレスポンスでも、2つの任意フィールドが省略される場合があります。context は プロンプトレベルの必須入力として読み取り、関連するプロジェクトの事実、規約、制約を適用します。 operationGuidance は任意の追加助言として扱います。すべての項目を読み取って検討し、 組み込みのarchiveワークフローに適用可能で互換性のあるものに従います。

   両フィールドは、組み込み手順、ユーザーの明示的な選択、解決済みパス、CLI検査、 コマンドの契約とは分けて扱います。contextがこれらの制御入力と競合する場合は、 競合を報告して制御側の値を維持します。ガイダンスが適用不能または制御入力と競合する場合は 従わず、理由を説明します。どちらのフィールドからも代替パス、省略するプロンプト、フラグを 推測しません。また、ユーザーが別途求めない限り、本文を仕様、変更アーティファクト、 archive概要へそのままコピーしません。これらはプロンプトレベルの振る舞いの契約であり、 強制可能な検査ではありません。

2. アーティファクトの完了ステータスを確認します

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

JSONを解析して次を把握します:

• schemaName: 使用中のワークフロー
• planningHome、changeRoot、artifactPaths、actionContext: パスとスコープのコンテキスト
• artifacts: 各アーティファクトとその状態（done、skipped、その他）の一覧

done でも skipped でもないアーティファクトがある場合（変更がskip_specsを宣言しているため、skippedは要件を満たします）:

• 未完了アーティファクトの一覧を警告として表示する
• 続行するかユーザーへ確認する
• ユーザーが確認した場合は続行する

3. タスクの完了ステータスを確認します

タスク ファイル (通常は tasks.md) を読んで、不完全なタスクがないか確認します。

- [ ] (未完了) と - [x] (完了) でマークされたタスクを数えます。

未完了タスクが見つかった場合:

• 未完了タスク数を警告として表示する
• 続行するかユーザーへ確認する
• ユーザーが確認した場合は続行する

タスク ファイルが存在しない場合: タスク関連の警告なしで続行します。

4. 仕様差分の同期状態を評価します

   status JSONの artifactPaths.specs.existingOutputPaths だけを仕様差分の情報源として使用します。 specs 項目がない、または existingOutputPaths が空の場合は、同期の確認なしで続行し、 他のアーティファクトから仕様差分を推測しません。

   仕様差分がある場合:

   • 各仕様差分を、対応する <planningHome.root>/openspec/specs/<capability-path>/spec.md の本仕様と比較します（リポジトリパスを固定せず、手順2で得た store 対応の planningHome.root を使用します）
   • 追加、変更、削除、名称変更として適用される内容を判定します
   • 確認前に統合した要約を表示します

プロンプトオプション:

• 変更が必要な場合: 「今すぐ同期 (推奨)」、「同期せずにアーカイブ」

• すでに同期されている場合: 「今すぐアーカイブ」、「とにかく同期」、「キャンセル」

  回答に応じて分岐します:

  • 「キャンセル」— 停止し、archiveしない
  • 「同期せずにarchive」または「今すぐarchive」— archiveへ進む
  • 「今すぐ同期」または「とにかく同期」— 同期してから、後述の検証を行う
  • その他 — archiveせず、もう一度質問する

  選択された同期で本仕様へ書き込む前に、同じ選択済みルートのフラグを付けて openspec instructions specs --change "<name>" --json を1回実行します。 終了コード0と有効なアーティファクト指示JSONを必須とします。検索に失敗するか無効なJSONが 返された場合はエラーを報告し、本仕様の書き込みや変更の移動前に停止します。 有効なレスポンスで rules が省略されていれば、ルールなしとして扱います。返された rules は、 このマージで生成する本仕様の内容と形式だけに適用します。archiveのガイダンスとして使ったり、 CLIの動作を変えたり、ルール本文を出力ファイルへコピーしたりしません。

  次に変更「」について、上記の仕様差分分析と取得済みspecsルールのスナップショットを渡し、 openspec-sync-specs ワークフローをインライン（エージェントによる知的マージ）で実行して完了を待ちます。 インライン同期はこのスナップショットを再利用し、specs の指示を再取得してはいけません。 バックグラウンドタスクへ委任しないでください。手順5が、まだ changeRoot を読み取っている同期処理の 配下からそれを移動し、変更だけがarchiveされて本仕様が更新されない状態になるためです。 委任でしか実行できないエージェントでは、同期的に委任して結果を待ちます。

  次に、この手順の先頭から比較をやり直し、artifactPaths.specs.existingOutputPaths に仕様差分があるすべての機能を確認します。同期で更新したと報告されたものだけには限定しません。同期が成功すれば適用すべき内容は残らないため、各機能は同期済みとして次を満たす必要があります:

  • ADDED 要件が存在する
  • MODIFIED 要件には delta で示したシナリオおよび説明の変更が反映され、その他のシナリオは維持されている
  • REMOVED 要件が存在しない。さらに、この同期が機能を廃止した場合（最後の要件を削除して ## Requirements が空になる場合）は、本仕様を空のまま残さず削除する。意図的に保持され、その旨が報告された本仕様も一致とみなす
  • RENAMED 要件は新しい名前で存在し、古い名前では存在しない

  同期に失敗した場合や、いずれかの機能が一致しない場合は差異を報告して停止し、archiveしません。 何も移動されず changeRoot も維持されるため、ユーザーは不一致を修正するか同期を再実行して、 archiveを最初からやり直せます。

5. アーカイブを実行します

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

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. 概要を表示

以下を含むアーカイブ完了の概要を表示します。

• 名前の変更
• 使用されたスキーマ
• アーカイブの場所
• 仕様が同期されたかどうか (該当する場合)
• 警告に関するメモ (不完全な成果物/タスク)

成功時の出力

## アーカイブ完了

**変更:** <change-name>
**スキーマ:** <schema-name>
**archive先:** `planningHome.changesDir` から導出したarchiveパス/<target-name>/
**仕様:** <手順4の検証に成功した場合のみ「✓ 本仕様へ同期済み」、それ以外は「仕様差分なし」または「同期をスキップ」>

<「すべてのアーティファクトとタスクが完了」— または警告付きでarchiveした場合は、その一覧（例:「未完了タスク2件を含めてarchive」）>

ガードレール

• 選択した変更を伝え、曖昧な場合は選択を求める
• 完了検査にはアーティファクトグラフ（openspec status --json）を使用する
• 警告だけでarchiveをブロックせず、内容を伝えて確認する
• archiveへ移動するときも .openspec.yaml を維持する（ディレクトリとともに移動する）
• 実行内容の明確な概要を表示する
• 同期を求められた場合は、openspec-sync-specs ワークフローをインラインで実行する
• 仕様同期の実行中にarchiveしない。同期をインライン実行し、changeRoot の移動前に本仕様を検証する
• 仕様差分があれば必ず同期評価を実行し、選択を求める前に統合した概要を表示する
• 関連する実行時contextを適用して競合を報告する。operation guidanceは参考情報のままとする
• すべてのガイダンス項目を検討し、適用不能または競合する助言の理由を説明する
• 既存のCLI検査、解決済みパス、プロンプト、コマンドの契約を変更しない
• アーティファクトルールは書き込む仕様だけを制約し、operation guidanceとして扱わない
• 実行時context、operation guidance、アーティファクトルールの本文を出力ファイルへそのままコピーしない