aep-git-ref

Git + Worktree リファレンス（AEP）

/aep-launch、/aep-build、/aep-wrap は、エージェントを並列実行する際の分離に、通常の Git リポジトリと git worktree を使用します。これらのスキルで「コミット」とある場合は、git commit を意味します。このスキルは、AEP の Git 規約をまとめた正式な参照先です。他のすべてのスキルでは、$BASE の解決、worktree の作成・削除、PR の作成について、該当箇所を再掲するのではなく、ここを参照します。通常の Git を使う理由（エージェントのトレーニングデータ、汎用ツール）：docs/decisions/migrate-from-jj-to-git.md。

---

統合ブランチ

AEP のすべての Git 操作は統合ブランチを対象とします。統合ブランチは、機能開発用の worktree の作成元、リベース先、PR のマージ先であり、コントロールプレーンのコミット（/aep-dispatch、/aep-design、/aep-wrap のアーカイブ）の反映先です。このスキル、および /aep-launch、/aep-build、/aep-wrap とプロダクトコンテキストスキル内の bash ブロックでは、このブランチを $BASE と呼びます。

AEP は自動検出により、一般的なケースでは設定不要で、次の2つのモードを使い分けます。

モード	条件	統合ブランチ（$BASE）	本番ブランチ
single-branch（デフォルト）	develop ブランチがない	main	main（同一ブランチ）
two-branch	develop が存在する	develop（ステージング）	main（昇格のみ）

develop ブランチを作成するだけで、プロジェクトは再設定なしに single-branch モードから two-branch モードへ移行できます。two-branch モードでは、AEP は本番ブランチ（main）に一切触れません。統合ブランチから本番ブランチへの昇格（develop → main）はユーザーの担当です。これは、すでに AEP の対象外であるデプロイと同様です。

$BASE の解決

Git を操作する各スキルでは、最初の bash ブロックの冒頭で統合ブランチを解決します。

# Resolve AEP integration branch ($BASE): override → auto-detect develop → main
BASE=$(git config --get aep.integration-branch 2>/dev/null || true)
if [ -z "$BASE" ]; then
  if git show-ref --verify --quiet refs/heads/develop \
     || git show-ref --verify --quiet refs/remotes/origin/develop; then
    BASE=develop
  else
    BASE=main
  fi
fi

解決の優先順位：

1. 明示的なオーバーライド — git config --get aep.integration-branch。これは標準以外の統合ブランチ名（例：staging、integration）を使う場合に限るオーバーライドです。標準の main／develop の場合は設定しないでください。これらは自動検出されます。/aep-onboard は検出されたモードを報告し、標準以外の名前を使用する場合にのみこのキーを書き込みます（git config aep.integration-branch <name> で設定し、git config --unset aep.integration-branch で解除します）。
2. 自動検出 — ローカルまたは origin に存在する場合は develop。
3. デフォルト — main（single-branch モード）。

標準のケースは固定ではなく自動検出されるため、プロジェクトは再設定なしに single-branch モードから two-branch モードへ移行できます。develop を作成すれば、次回の実行時にすべてのスキルが $BASE をそれに解決します。（aep.integration-branch=main を固定していた場合は、そのオーバーライドが優先され、移行が抑止されます。そのため、セットアップではデフォルト値を固定しません。）

git config --get aep.integration-branch はリポジトリローカルの設定であり、共通の .git/config を介してすべての worktree で共有されるため、メインセッションと .feature-workspaces/<name> 内のどの worktree でも $BASE は同じように解決されます。

---

Worktree のライフサイクル

作成

# Resolve $BASE first — see "Resolving $BASE" above
mkdir -p .feature-workspaces
git worktree add -b feat/<name> .feature-workspaces/<name> "$BASE"

• パスは必ず .feature-workspaces/<name> の下に置きます（Git の追跡対象から除外されます）。
• ブランチは必ず feat/<name> です。OpenSpec の変更名またはストーリー ID に対応します。
• ベースは必ず統合ブランチ $BASE です。

worktree はメインリポジトリと .git/objects を共有するため、作成は高速で、履歴も重複しません。ディスク上で複製されるのは、作業ツリー内のファイルのみです。

確認

git worktree list                            # all worktrees, branches, paths
git -C .feature-workspaces/<name> status     # status inside a specific worktree
git -C .feature-workspaces/<name> log --oneline "$BASE"..HEAD   # commits unique to the feature branch

削除（/aep-wrap のステップ 6）

git worktree remove .feature-workspaces/<name>
git branch -d feat/<name>

git branch -d でブランチが完全にはマージされていないという警告が表示された場合（PR が squash merge され、コミット SHA が異なる場合によく発生します）、gh pr view <number> --json state で PR の状態が MERGED であることを確認した後に、git branch -D feat/<name> で強制削除します。

破損したワークツリーのディレクトリから復旧する

.feature-workspaces/<name>/ が手動で削除された場合：

git worktree prune                           # forget the orphaned registration
git branch -D feat/<name>                    # delete the orphan branch (if needed)

.git/worktrees/<name>/ が存在しないパスをまだ参照している場合（例：親ディレクトリを移動した場合）：

git worktree repair .feature-workspaces/<name>

---

ブランチの命名

ブランチ	パターン	作成者
機能開発	feat/<short-name>	/aep-launch（ストーリーごとに1つ）
マイグレーション／雑務	chore/<short-name>	該当する場合に手動で作成
main からのホットフィックス	fix/<short-name>	手動で作成
マイグレーションプロジェクト	migration/<topic>	手動で作成

ルール：

• スラッシュ以降はケバブケースを使用します。スペースやアンダースコアは使用しません。
• 名前は短く保ちます（≤ 30 chars）。タブのラベル、シグナルファイル、PR のタイトルに表示されます。
• ワークツリーを完全に削除した後は、削除済みのブランチ名を再利用できます（git worktree prune により、ぶら下がった参照が削除されます）。

---

タスクごとに1コミットのパターン（/aep-build のフェーズ4）

内容

tasks.md には N 個のタスクが記載されています。機能ブランチには、同じ順序でタスクごとに1つ、合計 N 個のコミットが含まれます。コミット形式はConventional Commitsです。ワークスペースのエージェントは順番に実装し、タスクごとにコミットするため、コミット数はタスク数と一致します：

# Implement task 1
# ... edit files ...
git add -A
git commit -m "feat(auth): extract auth service"

# Implement task 2
# ... edit files ...
git add -A
git commit -m "feat(auth): add token refresh flow"

# ... etc.

各コミットの後、短縮 SHA を .dev-workflow/feature-verification.json の、該当するタスクエントリーの commit_sha フィールドに記録します。

この形式にする理由

• PR のコミット一覧は、tasks.md に対応する目次のように読めます。
• 各コミットは自己完結した単位であり、評価担当者（フェーズ5）とレビュー担当者（フェーズ11）は、それぞれ独立して git show <sha> を実行できます。
• PR のマージ時にスカッシュマージするため、コミットごとの整頓はレビューの読みやすさにのみ関係します。統合ブランチの履歴は自動的に整理された状態に保たれます。
• 作業途中で履歴を書き換える必要がなくなります。エージェントが最も道を踏み外しやすいのは、この場面です。

問題が起きた場合の対処方法

状況	対処
直前のタスクのコミットにファイルを含め忘れた	git add <file> && git commit --amend --no-edit（次のタスクをコミットする前であれば安全です）
数コミット前のタスクに問題があると気づいた	新しいコミットを追加します：fix(<scope>): correct <issue from task N> — 履歴は追記のみの状態に保たれます
レビューのフィードバックまたは評価ループでの FAIL	フォローアップコミットを追加します：fix(<scope>): address review on <topic>
新しい origin／$BASE に合わせて更新する必要がある	git fetch origin && git rebase origin/"$BASE" && git push --force-with-lease origin feat/<name>
リベース中に競合が発生した	作業ツリーで解決し、git add <files> && git rebase --continue を実行します。解決が困難な場合は、git rebase --abort を実行し、シグナルファイルを通じてオーケストレーターに伝えます。

書き換えたブランチをプッシュする際は、単なる --force ではなく --force-with-lease を使用します。このリース付きの方法では、前回のフェッチ以降に他の人がプッシュしている場合、安全に失敗します。

---

公開とPRの慣例

機能ブランチをプッシュする

# First push (after Phase 9 cleanup):
git push -u origin feat/<name>

# Subsequent pushes (review fixes, rebases):
git push origin feat/<name>
# or after a rebase:
git push --force-with-lease origin feat/<name>

PR を開く — ベースを必ず明示的に設定する

# $BASE is the integration branch — resolve it first (see "Integration Branch" above)
gh pr create --base "$BASE" --title "<title>" --body "<body>"

--base "$BASE" フラグは必須です。指定しないと、gh はローカルブランチの状態からベースを推測します（ディスパッチコミットが直近のベースに見えることがあります）。その結果、PR が統合ブランチ以外にマージされ、コードが $BASE に反映されません。2 ブランチモードでは、推測されたベースが本番環境の main になる可能性がありますが、AEP がフィーチャー作業をマージすることはありません。

PR をマージする

gh pr merge <number> --squash --delete-branch

常にスカッシュマージを使用します。フィーチャーブランチのタスクごとのコミットは、統合ブランチ（$BASE）上の 1 つのコミットにまとめられます。これにより、PR の「Commits」タブにタスクごとのレビュー履歴を残しながら、ログを読みやすく保てます。

---

コントロールプレーンのコミット（統合ブランチ上）

/aep-design、/aep-dispatch、/aep-envision、/aep-map、/aep-calibrate、/aep-validate、/aep-reflect、および /aep-wrap のアーカイブ手順は、すべて統合ブランチ（$BASE）に直接コミットします。手順はどれも同じです。

# Resolve $BASE first — see "Resolving $BASE" above
git pull --ff-only origin "$BASE"       # fail-fast if the integration branch has diverged
git add <specific-files>                # never -A on the integration branch; be explicit
git commit -m "<conventional message>"
git push origin "$BASE"

--ff-only を指定するのは意図的です。これにより、早送りできないプルを拒否し、同時に行われたプッシュを、黙ってマージするのではなく検知できます。ほかのユーザーが先にプッシュしたためにプルが失敗した場合は、フェッチして作業をリベースし、もう一度試してください。

---

復旧

コミットを紛失した場合（誤ったブランチにコミットした、または amend で失われた場合）

git reflog                              # find the orphaned commit's SHA
git cherry-pick <sha>                   # bring it onto the current branch
# or
git reset --hard <sha>                  # if you want to rewind to that point

ブランチ全体を紛失した場合（-D で削除した場合）

git reflog                              # the deleted branch's tip is in here
git branch <name> <sha>                 # recreate the branch at that tip

削除した worktree ディレクトリ内の作業を紛失した場合

コミットする前に rm -rf .feature-workspaces/<name> を実行した場合、作業は失われています。git worktree が追跡するのは、コミット済みの履歴だけです。.dev-workflow/ ファイル（シグナル、レッスン、進捗）も、Git の追跡対象外のため失われています。次回は rm -rf ではなく git worktree remove を使用してください。未コミットの変更がある場合、削除は拒否されます。

リベース後に OpenSpec ファイルが見つからない場合

リベースまたはマージ中にディスパッチコミットの OpenSpec ファイルが消えた場合：

git log --oneline -n 30                 # find the dispatch commit SHA
git restore --source=<sha> -- openspec/

これにより、ほかのものには触れずに、openspec/ をディスパッチコミット時点の状態に戻せます。

---

ディスク容量の予算

worktree を追加するたびに、ディスク上に作業ツリー全体のコピーが 1 つ増えます。.git/objects はすべての worktree で共有されるため、コミット履歴は重複しません。一般的な AEP リポジトリ（作業ツリーが約 100 MB、数年分の履歴を含む .git/objects が数 GB）の場合、3 つのエージェントを同時に実行すると、共有 .git/ に加えて約 300 MB が必要になります。

次のコマンドで監視できます：

du -sh .feature-workspaces/             # working-tree footprint
du -sh .git/objects                     # shared history

エージェントの作業完了前にディスク容量が逼迫した場合は、実行中の worktree を強制的に削除するのではなく、新しい /aep-launch の実行を一時停止してください。

---

チートシート

実行したい操作	実行するコマンド
フィーチャー worktree を作成する	git worktree add -b feat/<n> .feature-workspaces/<n> "$BASE"
すべての worktree を一覧表示する	git worktree list
フィーチャーブランチのコミットを確認する	git log --oneline "$BASE"..HEAD
最新の $BASE と同期する	git fetch origin && git rebase origin/"$BASE"
リベース後にプッシュする	git push --force-with-lease origin feat/<n>
PR を開く	gh pr create --base "$BASE"
PR をマージする	gh pr merge <#> --squash --delete-branch
マージ後に worktree を削除する	git worktree remove .feature-workspaces/<n> && git branch -d feat/<n>
削除したコミットを復旧する	git reflog の後に git cherry-pick <sha> を実行する
失われた openspec/ ファイルを復元する	git restore --source=<sha> -- openspec/