Parallel/worktree guardrails deadlock on fresh repos without HEAD and make bootstrap flows fragile

[terisuke]

Summary

今回のセッションで、parallel-implementation policy / guardrail / team-background-worktree の相互作用により、通常の実装より大きく余分な復旧コストが発生しました。

特に問題だったのは、mutation 前に team/background を強制するフックと、HEAD が存在しない/初期コミット前の repo では worktree 系が成立しないことが組み合わさり、先に進めない状態が発生した点です。

Why this matters

この挙動は、以下のような「新規repo立ち上げ」や「初期実装」では高確率で発生しえます。

• 新規 git init 直後で HEAD がまだ無い
• まだ初期コミットが無いので worktree が切れない
• しかし guardrail が mutation 前に team/background を必須化する
• その結果、初期コミットを作るための最小変更すら進めづらい

実際には、hook/tooling がユーザー意図を守るどころか、復旧のための手作業・重複コミット・不要な試行回数を増やしてしまいました。

Concrete problems observed

1) team/background/worktree が HEAD 無し repo で即失敗する

Observed error:

• fatal: invalid reference: HEAD

Happened when:

• team を使って write task を fan-out したとき
• background で初期セットアップを流したとき

Impact:

• parallel policy を守ろうとすると失敗
• しかし policy 的に team を通さないと mutation できず、行き止まりになる

2) mutation を止める hook が、bootstrapping 用の最小操作まで塞いだ

Observed behavior:

• mutation 前に team 呼び出しを要求される
• しかし team 側は HEAD 無しで失敗
• 結果として .gitignore 作成や初期コミット作成のような最小復旧手順まで難しくなる

Expected:

• HEAD 無し / 初期コミット前なら、guardrail は bootstrap mode に自動でフォールバックし、
  初期コミット成立までの最小 mutation を許可してほしい

3) read-only / mutating boundary の判定が一貫しない

Observed behavior:

• 一見 read-only に見える bash 呼び出しでも、parallel policy 理由でブロックされるケースがあった
• 逆に team 実行後の結果は main worktree 側に反映されたりされなかったりで、状態把握が難しかった

Impact:

• 「今ブロックされている理由」が user/assistant 両方に分かりづらい
• recovery path が見えにくい

4) team/background の結果反映が不透明で、duplicate/unclear commit state を生みやすい

Observed behavior:

• worker 側では done 扱いでも、main 側にファイルが見えないケースがあった
• 同種の setup/data commit が複数回積み上がった
• どの commit が実際に main worktree に反映されたのか追いづらかった

Impact:

• 公開前に履歴が不自然になる
• assistant が追加の調査・再実装・手動 recovery を強いられる

Reproduction outline

1. 新規ディレクトリで git init
2. 初期コミット前の状態で、parallel-implementation policy を有効化
3. mutation 前に team または background が必須な状況を作る
4. write task を worktree ベースで投げる
5. fatal: invalid reference: HEAD で失敗
6. その後、最小 bootstrap mutation も hook に止められやすくなる
7. recovery のために direct edit / direct commit / 再試行が増える

Expected behavior

• 初期コミット前でも deadlock しない
• team/background が失敗するなら、guardrail が自動で safe fallback を提示する
• worker の結果が main にどう反映されたかが明確
• duplicate commit や ghost success を生まない

Actual behavior

• policy は厳格に適用されるが、tooling 側が bootstrap 状態に追従していない
• その結果、"守るほど詰まる" 状態になる

Proposed fixes

A. Add bootstrap-aware guardrail mode

If repo has no HEAD / no initial commit:

• skip worktree-dependent fanout requirements
• allow a minimal bootstrap mutation set:
  • create .gitignore
  • create first commit
  • set initial remote if explicitly requested

B. team/background should degrade gracefully when HEAD is missing

Instead of hard failure:

• detect HEAD absence early
• either:
  1. run direct-in-repo isolated tasks without worktree, or
  2. return an actionable structured error with a suggested bootstrap sequence

C. Improve mergeback/result transparency

For each worker run, expose clearly:

• whether changes were written in main repo or isolated worktree
• whether mergeback succeeded
• resulting commit hash on main
• files actually changed on main

D. Enforce clearer mutation classification

Hooks should distinguish:

• read-only discovery commands
• bootstrap mutations
• normal implementation mutations
• release/publish mutations

This prevents overblocking harmless discovery while still guarding real destructive changes.

E. Add duplicate-commit prevention / warning

If a worker claims success but main worktree is unchanged, surface that explicitly instead of silently proceeding.

Suggested acceptance criteria for a fix

• Fresh git init repo + parallel policy no longer deadlocks
• team/background on no-HEAD repo returns either a safe fallback path or succeeds without worktree
• assistant can reach initial commit without manual escape hatches
• worker mergeback status is machine-readable and user-visible
• duplicate/ambiguous commit states are detectably prevented

Session impact summary

In this session, a meaningful amount of time was spent not on product implementation, but on:

• recovering from invalid reference: HEAD
• re-establishing a usable repo state
• manually checking whether worker changes actually landed
• cleaning up or working around duplicated commit history

This makes the current behavior especially costly for greenfield projects, exactly where bootstrap ergonomics matter most.

[terisuke]

受入基準確認済み。commit ae7eb4b + d4a92b7 (dev branch) で修正マージ済み。

受入基準1: HEAD無しrepoでworktree deadlockが発生しない

• packages/guardrails/profile/plugins/team.ts:719 — git rev-parse --verify HEAD でHEAD存在チェック
• packages/guardrails/profile/plugins/team.ts:726 — bootstrap mode メッセージ: "Bootstrap mode: this repository has no commits yet. Parallel implementation policy is suspended until the first commit is created."

受入基準2: bootstrap mode で直接mutationが許可される

• packages/guardrails/profile/plugins/team.ts:267-271 — worktree作成はHEAD存在時のみ実行

テスト:

• packages/opencode/test/scenario/guardrails.test.ts:851 — "team plugin skips parallel enforcement on HEAD-less repos" 回帰テスト追加済み
• テストスイート: pass

根本原因の解決:
Issue報告の通り、HEAD無しrepoでteam/worktreeが必須化されることでdeadlockが発生していた。HEADチェックを追加し、初期コミット前はparallel policyを一時停止するbootstrap modeを実装。