aep-wrap

Wrap

マージ後のアーカイブとワークスペースのクリーンアップです。PR のマージ後に統合ブランチ（$BASE）で実行します。/aep-git-ref "Integration Branch" に従って $BASE を解決してください。これにより、OpenSpec の変更をアーカイブし、ビルドのランタイムシグナルを収束させ、ワークスペースを削除します。

この手順の位置付け：

/aep-onboard → /aep-scaffold → [ /aep-design → /aep-launch → /aep-build → /aep-wrap ]
                                                        ▲ you are here

セッション： メインセッション、マージ後
入力： マージ済み PR の通知
出力： アーカイブ済みの OpenSpec の変更、収束済みの実行記録、クリーンアップ済みのワークスペース

---

Phase 13：統合ブランチでのアーカイブとクリーンアップ

厳守事項： /opsx:archive は統合ブランチ（$BASE）上のメインチェックアウトから実行します。ワークスペースからは決して実行しないでください。openspec/specs/ に書き込みが行われ、並行するワークツリーと競合します。

1. マージ済みの状態を取得し、統合ブランチを早送りする

/aep-git-ref "Integration Branch" に従って $BASE を解決し（上書き → develop を自動検出 → main）、ローカルの統合ブランチを更新して、マージ済み PR を取り込みます。

git fetch origin
git checkout "$BASE"
git pull --ff-only origin "$BASE"
git status

--ff-only を指定するのは意図的です。$BASE にプッシュされていないローカルコミットがあって失敗した場合は、先にそれらをプッシュするかリベースしてください。このチェックアウト後は統合ブランチ上にいます。後続の手順では、BASE=$(git branch --show-current) でその名前を取得します。

事後条件： HEAD が $BASE 上にあり、git status がクリーンであること。wrap 中に差分があってよいのは openspec/ と product-context.yaml のみです。apps/／packages/ 配下のコードに変更がある場合は、まず調査してください。openspec/changes/<name>/ が見つからない場合（起動前に dispatch コミットが失われた場合）は、/aep-git-ref "Recovery" → "OpenSpec files missing after rebase" に従って復元してから続行してください（git restore --source=<dispatch-sha> -- openspec/）。

2. 開発サーバーを停止する（まだ実行中の場合はワークスペースから停止）

source .feature-workspaces/<name>/.dev-workflow/ports.env 2>/dev/null
lsof -ti :$SERVER_PORT | xargs kill 2>/dev/null
lsof -ti :$WEB_PORT | xargs kill 2>/dev/null

2.5. Convergence Gather — 実行記録を収集する（アーカイブ前）

ワークスペースのビルド時ランタイムシグナルを、アーカイブ前の変更ディレクトリ（openspec/changes/<change-name>/convergence/）に収束させます。これにより、ステップ 3 のアーカイブ時の mv で、実行記録を 1 つのコミットにまとめられます。収集コマンドを実行し、references/convergence.md §1 のプロデューサー契約（コピー対象のリスト、マニフェストのフィールド一覧、スキーマ）に従って execution-record.yaml を書き込みます。収集はベストエフォートです。ソースが見つからない場合は明示的な null にするか、コピーを行わないものとし、wrap を失敗させてはいけません。

ゲート（順序の不変条件 — アーカイブ前に収集）： ファイルを openspec/changes/<change-name>/ に置いておけば、アーカイブ時の mv によって 1 つのコミットにまとめられます。ステップ 3 の後に収集すると別のコミットが必要になり、ティアダウンと競合して、データが黙って失われる可能性があります。

事後条件： アーカイブ前の変更ディレクトリに convergence/execution-record.yaml が存在すること。

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

/opsx:archive <change-name>

4. アーカイブをコミットしてプッシュする

コントロールプレーンコミットを使用します。ステップ 4、5、5.5 で共通の早送りコミットパターンです（ステップ 1 で統合ブランチをチェックアウト済みです）。

BASE=$(git branch --show-current)   # integration branch, from step 1
git add openspec/                   # stages the convergence/ records from step 2.5 — the archive commit carries them, no extra commit
git commit -m "chore: archive <change-name>"
git pull --ff-only origin "$BASE"
git push origin "$BASE"

5. ワークスペースのシグナルからストーリーのステータスを同期する（Product-Cycle モードのみ）

スタンドアロンモード： product-context.yaml が存在しない場合は、手順 6 に進みます。

この機能がディスパッチされたストーリーの場合は、ワークスペースのシグナルを読み取り、実際の PR の状態と照合します。シグナルが古くなっている場合があります（マージ後もワークスペースに in_review と表示される場合があります）。

cat .feature-workspaces/<name>/.dev-workflow/signals/status.json
gh pr view <pr-number> --json state,mergedAt

PR がマージ済みなのにシグナルが in_review を示している場合は、ストーリーを completed として扱います。PR の状態を反映したシグナルに基づき、product-context.yaml 内の該当するストーリーを更新します。

status: completed # from signal story_status
completed_at: <timestamp> # from signal completed_at
pr_url: <url> # from signal pr_url
cost_usd: <cost> # from signal cost_usd

story_status が failed の場合は、status: failed に設定し、構造化された failure_log を代わりに failure_logs: の下に記録します。その後、依存関係がすべて completed になった pending ストーリーを ready に移行します。YAML を検証し（npx js-yaml product-context.yaml > /dev/null。/aep-validate にはガードレールと一般的な修正方法が含まれています）、コントロールプレーンコミット（手順 4）で、すべての移行をアトミックにコミットします — git add product-context.yaml、コミットメッセージは chore: update story <id> status to completed。

並行処理プロトコル： ストーリーの完了ステータスが product-context.yaml に反映されるのはここだけです。ワークスペースエージェントはシグナルを書き込み、/aep-wrap（インテグレーションブランチ上）はシグナルを読み取って YAML に書き込みます。

5.5. 学んだ教訓をアーカイブする

ワークツリーを削除する前に — git worktree remove によって .dev-workflow/lessons.md が削除されるため、これが最後の機会です — 実際の教訓があればコピーします。

LESSONS=".feature-workspaces/<name>/.dev-workflow/lessons.md"
if [ -f "$LESSONS" ] && [ "$(wc -l < "$LESSONS")" -gt 12 ]; then   # >12 = content beyond the template header
  mkdir -p lessons-learned
  cp "$LESSONS" "lessons-learned/<change-name>.md"
fi

ファイルをコピーした場合は、コントロールプレーンコミット（手順 4）でコミットします：git add lessons-learned/<change-name>.md、コミットメッセージは docs: archive lessons from <change-name>。アーカイブされた convergence/ ディレクトリは変更ごとの完全な記録であり、lessons-learned/ は /aep-reflect の手順 1 が読む、すぐに参照できるインデックスとして維持されます。

6. ワーカーとワークツリーを終了する（executor.teardown()）

ワークツリーを削除する前に、ワークスペースのワーカーを停止します。削除済みディレクトリを対象に実行され続ける OS に紐づいたワーカーは孤立し、自動操縦の実行中に蓄積されます。停止方法は起動モードごとに異なります（自動操縦の状態に backend／agent_id として記録されるか、起動方法から判断できます）。

# Mode-specific worker stop (each is a no-op for the other modes):
#   native-bg-subagent → TaskStop(<bare-hex bg-subagent id>) (session-bound, no team)
#   claude-bg      → claude stop <agent_id>; claude rm <agent_id>
#   codex-subagent → close_agent(<agent_id>) if still running
#   codex-exec     → nothing to kill (the exec process exited with the build)
#   legacy         → tmux kill-session -t <name> 2>/dev/null || true

次に、/aep-git-ref の「Worktree Lifecycle」→「Remove (/aep-wrap step 6)」に従ってワークツリーを削除し、マージ済みのフィーチャーブランチを削除します（git worktree remove + git branch -d feat/<name>。強制削除は gh pr view <number> --json state で MERGED が確認された場合に限ります）。

---

ガードレール

順序不変条件（実世界から導かれる事後条件）。 wrap の手順チェーンは機械的です。各手順の完了は実世界の状態から確認できるため、中断された wrap はやり直すのではなく、確認して再開します：収集済み = convergence/execution-record.yaml が存在する（アーカイブ前またはアーカイブ後の場所）→ アーカイブ済み = openspec/changes/<name>/ が存在せず、archive/*<name>* ディレクトリが存在する → コミット済み = openspec/ に関する git status --porcelain がクリーン → ステータス更新済み = ストーリーが完了フィールドの設定された completed になっている → 教訓コピー済み = lessons-learned/<change-name>.md が存在する → 終了済み = ワークツリーのパスが存在しない（git worktree list で照合）。事後条件がすでに成立している手順はスキップし、決して繰り返しません。このパターンを /aep-autopilot の references/deterministic-orchestration.md が一般化しています。

---

振り返りと次への進行（Product-Cycle モード）

スタンドアロンモード： product-context.yaml が存在しない場合は、レイヤーゲートをスキップします。観察事項を分類するために /aep-reflect を実行してもかまいません。

レイヤー完了時 — product-context.yaml が存在し、アクティブレイヤーのすべてのストーリーが completed になった時点で — references/layer-advance.md を読み、2 段階の Layer Gate Check（ゲートを実行し、エビデンスを記録し、対象範囲の scripted_passed → passed を切り替える）と Layer Distillation（分離された、提案のみの統合作業）を行います。次のレイヤーの設計への移行は人間による確認が必要な手順であり、次の /aep-dispatch より前に記録します。

フィードバックループ

/aep-reflect を実行して、この機能に関する気づきを分類します。バグ、改善点、発見事項は適切なフェーズに振り分けられ、フィードバックループが完結します。

---

次のステップ

ディスパッチキュー（/aep-dispatch）から次のストーリーを選ぶか、リリースしたばかりの内容に関するフィードバックを分類します（/aep-reflect）。