okstra 0.67.0 → 0.68.0

package/docs/superpowers/specs/2026-06-06-stage-worktree-isolation-design.md

@@ -4,7 +4,7 @@
 - 범위: `implementation` phase에서 stage를 **별도 git worktree로 격리**해, 사용자가 수동으로 동시에 띄운 여러 `implementation` run이 안전하게 서로 다른 stage를 진행하도록 한다. `started-exclusion`(A2)을 같은 설계에 통합한다.
 - 비범위
   - **자동 fan-out 없음** — okstra가 ready stage들을 여러 프로세스로 자동 분기하지 않는다. 병렬 트리거는 사용자가 stage별 run을 각각 기동하는 **수동 동시**만 지원한다.
-  - **okstra 자동 머지 없음** — stage 브랜치 합류는 사용자 수동 머지(또는 release-handoff 수집)다.
+  - **okstra 자동 머지 없음** — stage 브랜치 합류는 사용자 수동 머지(또는 release-handoff 수집)다. (2026-06-10 개정: release-handoff stage-group 모드의 수집 머지는 예외 — [2026-06-10-stage-group-handoff-design.md](2026-06-10-stage-group-handoff-design.md))
   - `implementation` 외 phase(`requirements-discovery` / `error-analysis` / `implementation-planning` / `final-verification` / `release-handoff`)의 worktree 모델은 불변 — 기존 task-key worktree 1개 유지.
   - ADR↔gitignore(C1)는 별도 plan. 다국어/i18n.
 - 관계: [`2026-05-20-implementation-planning-multi-stage-design.md`](2026-05-20-implementation-planning-multi-stage-design.md)의 stage 개념·carry-in 모델 위에 선다. [`2026-06-04-stage-run-batching.md`](../plans/2026-06-04-stage-run-batching.md)가 known gap으로 남긴 **started-exclusion 미구현**을 본 설계가 해소한다. [`2026-06-04-stage-splitting-cost-aware-design.md`](2026-06-04-stage-splitting-cost-aware-design.md)의 "병렬=부수효과, run batch=비용 단위" 원칙과 양립한다(본 설계는 부수효과인 병렬을 **안전하게** 만들 뿐, 분할 기준을 바꾸지 않는다).

package/docs/superpowers/specs/2026-06-10-concurrent-run-team-guard-design.md

@@ -0,0 +1,107 @@
+# 동시-run team 가드: 후발 run no-team background 회피 설계
+
+- 작성일: 2026-06-10
+- 상태: 설계 승인됨 (구현 전, 실측 게이트 미통과)
+- 범위: 같은 task-key 의 implementation run 이 동시에 돌 때 발생하는 `~/.claude/teams/` team config race 의 **예방**. 이미 발생한 race 의 복구는 범위 밖(§6).
+
+## 1. 문제 (런타임으로 관찰)
+
+사용자가 같은 task-key(`fontradar-v2-api:calcule-des-prix-1-1:dev-9185`)에 대해 두 Claude Code 세션을 동시에 돌렸다. 세션 A 는 implementation stage-4 의 Claude verifier 를 dispatch 하려 했고, 세션 B 는 stage-5 를 동시에 실행 중이었다. 결과:
+
+| 관찰 | 내용 |
+|---|---|
+| dispatch 실패 | stage-4 verifier 의 `Agent(... team_name ...)` 가 `Team config file unreadable (lock acquired, read failed)` 로 거부 |
+| team config 소실 | stage-4 team 의 `~/.claude/teams/<team>/config.json` 이 사라짐 |
+| 다른 team 정상 | `okstra-…-dev-9185-s5` team 은 정상 존재 (config.json 15K, 20:27 생성) |
+| 코드는 무사 | stage-4 의 코드/worktree 는 intact, real-DB PASS 완료 — **데이터 손실 없음, dispatch 만 막힘** |
+
+즉 stage-4·stage-5 는 코드상 독립(둘 다 deps 1,2,6)이라 worktree/코드 충돌은 없었고, **공유 상태(`~/.claude/teams/` team config)에서만 race** 가 났다.
+
+## 2. 근본 원인 (코드로 확정)
+
+1. **team 생성/삭제는 lead AI 의 하네스 도구 호출이라 okstra 의 flock 밖이다.** `prepare_task_bundle` 은 launch prompt 에 team 이름과 "Team Creation Gate (BLOCKING)" 블록만 렌더하고([scripts/okstra_ctl/render.py:1665](../../../scripts/okstra_ctl/render.py)) 즉시 반환한다. 실제 `TeamCreate`/`TeamDelete` 는 lead 가 Phase 3·7 에서 직접 호출한다([agents/SKILL.md:212](../../../agents/SKILL.md), [prompts/profiles/_common-contract.md:60](../../../prompts/profiles/_common-contract.md)). lead 가 team 을 들고 도는 수십 분간 okstra 의 Python 프로세스는 이미 종료돼 있어, TeamCreate~TeamDelete 임계구역을 flock 으로 감쌀 수단이 없다.
+
+2. **worktree/registry 레이어는 stage-key 까지 격리되지만 team 레이어는 그 격리 밖이다.** worktree 프로비저닝은 task-key flock([scripts/okstra_ctl/locks.py:30](../../../scripts/okstra_ctl/locks.py) `worktree_provision_mutex`)으로, stage 예약은 registry flock([scripts/okstra_ctl/worktree_registry.py:264](../../../scripts/okstra_ctl/worktree_registry.py) `list_active_stage_numbers`)으로 직렬화된다. team_name 도 stage 별로 분리된다(`okstra-<task-key>-s<N>`, [scripts/okstra_ctl/render.py:1659](../../../scripts/okstra_ctl/render.py)). 그러나 이 어떤 okstra flock 도 team 생성/삭제를 감싸지 않는다.
+
+3. **`Team config file unreadable (lock acquired, read failed)` 문자열은 okstra 레포 어디에도 없다**(grep 전수 확인). 이는 Claude Code 하네스의 team config I/O 계층이 내는 메시지이며, team config 파일의 atomicity 는 okstra 가 통제할 수 없다([scripts/okstra_ctl/team_reconcile.py:17](../../../scripts/okstra_ctl/team_reconcile.py) 주석: "harness behaviour that can only be confirmed inside a real run").
+
+종합: 두 동시 run 이 같은 `~/.claude/teams/` 부모를 동시에 건드린 것이 race 의 원천이다. team 이름이 stage 별로 달라도(파일 경로는 안 겹쳐도) 하네스의 부모-디렉토리 단위 동작이 한쪽 team config 를 관측 불가능하게 만들 수 있다.
+
+## 3. 검토한 대안과 채택 근거
+
+| 방향 | stage 병렬 보존 | enforce 지점 | race 회피 | 기각/채택 |
+|---|---|---|---|---|
+| A. lead-driven advisory lock (TeamCreate~TeamDelete 구간 직렬화) | ✅ | lead 프롬프트(협조 의존) | △ 부분 | 기각 |
+| B. 같은 task-key 동시 run 전체 직렬화 (한 번에 하나) | ❌ | Python | ✅ | 기각 |
+| **C. 진입 가드 + 후발 no-team background 회피** (채택) | ✅ | Python 렌더(확정) | ✅ | 채택 |
+
+- **A 기각**: flock 은 호출 프로세스 생존 중에만 유효한데 team 작업은 lead 행위라 PID-liveness 기반 advisory lock 으로만 구현된다. "선언만 하고 강제는 못 하는" 상태(CLAUDE.md "declaration vs enforcement" 위반 위험)이고, lead 가 acquire 를 빼먹으면 무효다.
+- **B 기각**: stage 병렬성은 명시적 설계 기능이다([CLAUDE.md](../../../CLAUDE.md) "two concurrent implementation runs safely pick different ready stages — this is how stage parallelism works"). 전체 직렬화는 이 기능을 죽인다.
+- **C 채택 근거 (핵심)**: 후발 run 이 team 을 **아예 만들지 않고** `run_in_background: true` + no `team_name` 으로 worker 를 dispatch 하면 `~/.claude/teams/` 를 건드리지 않아 race 가 원천 차단된다. 이 no-team 경로는 **okstra 에 이미 존재하는 Phase 5 fallback**([agents/SKILL.md:219](../../../agents/SKILL.md), [agents/SKILL.md:225](../../../agents/SKILL.md))이고, worker 완료는 team 유무와 무관하게 **result 파일 출현 polling** 으로 감지되므로([agents/SKILL.md:233](../../../agents/SKILL.md)) 분석 산출물은 동등하다. 잃는 것은 Teams split-pane 관찰성(FleetView)뿐이다. enforce 지점이 Python 렌더라 lead 협조에 기대지 않는다.
+
+## 4. 설계
+
+### 4.1 감지 (새 추적 없음)
+
+`prepare_task_bundle` 은 implementation stage 선택 시 이미 `list_active_stage_numbers` 를 호출한다([scripts/okstra_ctl/run.py:1342](../../../scripts/okstra_ctl/run.py)). 이 호출은 task-key mutex 안에서 일어나고([scripts/okstra_ctl/run.py:1798](../../../scripts/okstra_ctl/run.py) `worktree_provision_mutex` → [run.py:1825](../../../scripts/okstra_ctl/run.py) stage 선택), 예약이 직렬화되므로 **후발 run 은 반드시 선발의 active stage 를 본다**(둘 다 못 보는 경우 없음).
+
+판정: 선택된 stage 를 제외한 `reserved_stages` 가 비어있지 않으면 **동시-run**.
+
+> 비대칭(한계): 선발 run 은 예약 시점에 후발이 아직 없어 후발을 영영 못 본다. 그러나 채택안에서는 **후발이 양보(no-team)** 하므로 선발의 team 이 보호된다 — 비대칭이 안전성을 깨지 않는다.
+
+### 4.2 안전 기본값 — 동시-run 이면 no-team background 로 렌더
+
+동시-run 감지 시 `prepare_task_bundle` 은 기본적으로 no-team 경로로 bundle 을 렌더한다:
+
+- `render._build_team_creation_gate`(현 [render.py:1640](../../../scripts/okstra_ctl/render.py) 분기)에 동시-run 분기를 추가한다. "Team Creation Gate (BLOCKING)" 대신 **"Concurrent-run: no-team background" 블록**을 emit 한다. 이 블록은:
+  - lead 에게 `TeamCreate` 를 **시도하지 말고** 곧장 Phase 5(no-`team_name`, `run_in_background: true`)로 가라고 지시한다.
+  - team-state 에 `teamCreate: { attempted: false, status: "skipped", reason: "concurrent-run", concurrentStages: [<stages>] }` 를 **사전 기록**하라고 지시한다.
+- `PrepareOutputs.extras`([scripts/okstra_ctl/run.py:309](../../../scripts/okstra_ctl/run.py))에 `concurrent_run: { detected: true, active_stages: [...] }` 를 담는다 — 대화형 분기(§4.3)와 비대화형 로그(§4.4)가 읽는다.
+
+### 4.3 대화형 분기 (okstra-run 스킬)
+
+스킬은 `extras.concurrent_run.detected` 가 참이면, conformance-waiver picker 와 **동형의 자체 3-옵션 recommendation picker**([skills/okstra-run/SKILL.md:192](../../../skills/okstra-run/SKILL.md))를 띄운다:
+
+1. **(추천) 이대로 no-team background 로 진행** — 이미 §4.2 로 렌더된 bundle 을 그대로 사용. race 회피, Teams 관찰성만 포기.
+2. **대기** — 지금 dispatch 를 보류한다. stage worktree·run-context 는 보존되고(registry release 는 worktree dir 을 보존한다 — [worktree_registry.py:283](../../../scripts/okstra_ctl/worktree_registry.py)) stage-key 예약은 이 stage 를 "내가 나중에 한다"로 유지한다. 다른 run 종료 후 **resume 명령으로 재개**(그때는 동시-run 이 아니므로 정상 team 경로). 스킬은 resume 명령을 산출물에 명시한다(메모리: next-step 내장).
+3. **직접 입력** (마지막 옵션 고정 — 메모리: okstra run 입력은 항상 "직접 입력"으로 끝난다).
+
+> 이 picker 는 스킬이 author 하는 것이라 run-prompt recommendation 규칙(1–2 추천 + 직접 입력)을 따른다 — wizard 가 emit 하는 `options[]` 가 아니므로 [skills/okstra-run/SKILL.md:52](../../../skills/okstra-run/SKILL.md) 의 "wizard option 을 줄이지 말라" 제약과 충돌하지 않는다.
+
+### 4.4 비대화형 분기 (okstra.sh / node CLI)
+
+사용자 상호작용이 불가하므로 **§4.2 안전 기본값(no-team background)으로 자동 진행** 하고, `extras.concurrent_run` 을 경고로 로그한다(`PROGRESS:` 또는 stderr). race 를 회피하면서 run 을 멈추지 않는다.
+
+### 4.5 단일 수렴점
+
+감지·렌더 결정은 `prepare_task_bundle` 안에서 한 번만 한다. 세 진입점(okstra-run 스킬 / okstra.sh / node CLI)은 모두 이 함수로 수렴하므로([CLAUDE.md](../../../CLAUDE.md) "All three must converge on `prepare_task_bundle()`"), 분기 UI(대화형 picker vs 비대화형 로그)만 진입점별로 다르고 결정 로직은 공유된다.
+
+### 4.6 no-team fallback 의 새 legal 사유
+
+현재 no-`team_name` fallback 은 "team-state `teamCreate.status == "error"` 일 때만 legal" 이다([agents/SKILL.md:231](../../../agents/SKILL.md)). 본 설계는 **`status == "skipped"` + `reason == "concurrent-run"`** 을 새 legal 사유로 추가한다. 수정 대상:
+
+- [agents/SKILL.md:231](../../../agents/SKILL.md) — legal 사유에 concurrent-run skipped 추가.
+- [prompts/profiles/_common-contract.md:53](../../../prompts/profiles/_common-contract.md) — Phase 7 teardown 의 "no-`team_name` fallback 에는 삭제할 team 이 없다" 조건이 skipped 에도 적용됨을 명시(이미 team 이 없으므로 silent-skip).
+
+## 5. 구현 단위
+
+| 단위 | 파일 | 변경 |
+|---|---|---|
+| 감지 플래그 | [scripts/okstra_ctl/run.py](../../../scripts/okstra_ctl/run.py) | stage 선택 결과에서 `reserved_stages\{선택}` 를 `extras.concurrent_run` 으로 전파 |
+| 렌더 분기 | [scripts/okstra_ctl/render.py:1640](../../../scripts/okstra_ctl/render.py) | 동시-run 시 no-team 블록 + 사전 team-state 지시 emit |
+| 대화형 picker | [skills/okstra-run/SKILL.md](../../../skills/okstra-run/SKILL.md) | `extras.concurrent_run` 분기 → 3-옵션 picker |
+| no-team legal | [agents/SKILL.md:231](../../../agents/SKILL.md), [prompts/profiles/_common-contract.md:53](../../../prompts/profiles/_common-contract.md) | concurrent-run skipped 를 legal 사유로 |
+| 빌드 | `npm run build` | 위 소스를 `runtime/` 로 동기화(직접 편집 금지) |
+
+## 6. 한계 (명시)
+
+- **후발이 대기·background 를 거부하고 team 생성을 강행** 하면 race 창은 다시 열린다. 진입 가드는 advisory 경계까지가 한계다(임계구역 lock 을 안 쓰기로 한 §3-A 의 귀결).
+- **이미 발생한 race 의 복구**(config.json 소실 상태)는 본 설계 범위 밖이다. team_reconcile / 재생성은 별도 작업으로 다룬다.
+- **미검증**: no-team background 가 dispatch→완료→convergence→리포트 전체 사이클을 끝까지 도는 것은 실제 run 으로만 최종 확인된다. 현재는 정적 설계 수준이다(화면에서 해당 dispatch 경로 자체는 관찰됨).
+
+## 7. 테스트 계획
+
+- **단위**: `list_active_stage_numbers` 가 비어있지 않을 때 `prepare_task_bundle` 결과의 `extras.concurrent_run.detected` 가 참이 되는지([tests/](../../../tests/)).
+- **단위**: 동시-run 일 때 render 가 Team Creation Gate 대신 no-team 블록을 emit 하고 사전 team-state 지시(`status: "skipped", reason: "concurrent-run"`)를 포함하는지.
+- **단위**: 동시-run 이 아닐 때(=`reserved_stages` 가 선택 stage 뿐) 기존 Team Creation Gate 가 그대로 나오는지(회귀 방지).
+- **e2e**: 같은 task-key 두 implementation run 을 직렬로 시뮬레이션(첫 run 의 stage-key 예약을 active 로 둔 채 둘째 run prepare)해 둘째가 no-team 경로로 가는지([tests-e2e/](../../../tests-e2e/) scenario 추가).

package/docs/superpowers/specs/2026-06-10-git-reconcile-stale-sha-recovery-design.md

@@ -0,0 +1,105 @@
+# git-reconcile — stale SHA 회복 3단 방어 — 설계
+
+- 작성일: 2026-06-10
+- 범위: okstra 밖에서 일어난 git 히스토리 변경(PR 리뷰 amend, rebase, squash merge, 외부 커밋, branch 삭제) 이후 `implementation` run 을 손편집 없이 이어가게 한다. 저장된 commit SHA 가 stale 해졌을 때의 **감지 → 내용 기반 자동 화해 → 확인 보정** 경로를 추가한다.
+- 비범위
+  - **SHA → branch 명 저장 전환 없음** — SHA 는 계속 기록의 정본(불변 스냅샷)이다. branch 는 사람이 의도를 다시 알려줄 때의 *입력 수단*일 뿐이다. branch tip 은 가변이라 anchor 고정·done 스냅샷·ancestor 게이트의 불변식과 양립하지 않고, squash merge 후에는 branch tip 도 ancestor 가 아니므로 사용자 페인을 해결하지 못한다.
+  - okstra 가 머지를 대행하지 않는다 — 보정은 *기록*(`consumers.jsonl` / registry)의 화해이지 git 조작이 아니다.
+  - `implementation` 외 phase 의 task-key worktree 모델 불변.
+- 관계: [`2026-06-06-stage-worktree-isolation-design.md`](2026-06-06-stage-worktree-isolation-design.md)의 base 결정 규칙(§2.2)·anchor 1회 고정(§3.2) 위에 선다. 그 설계가 도입한 ancestor 게이트의 known gap — 히스토리 재작성 시 회복 경로 부재 — 를 본 설계가 해소한다. [`scripts/okstra_ctl/reconcile.py`](../../../scripts/okstra_ctl/reconcile.py)는 run 상태(recent.jsonl) 보정 전용으로 별개 개념이며 건드리지 않는다.
+
+## 1. 동기
+
+stage 격리 설계는 base 를 SHA 로 고정한다: 독립 stage = anchor([`set_implementation_base`](../../../scripts/okstra_ctl/worktree_registry.py:199), 1회 고정 후 무시), 단일 의존 = 선행 done `head_commit`([run.py:526](../../../scripts/okstra_ctl/run.py:526)), 다중 의존 = `git merge-base --is-ancestor` 검증([run.py:454](../../../scripts/okstra_ctl/run.py:454), [run.py:506](../../../scripts/okstra_ctl/run.py:506)). 이 SHA 들이 okstra 밖의 작업으로 stale 해지면:
+
+1. **rebase / squash merge** — 커밋 ID 가 바뀌어 저장된 SHA 가 candidate 의 ancestor 가 아니게 된다. 내용은 머지됐는데도 `PrepareError`("not merged")로 거부된다.
+2. **PR 리뷰 반영 amend** — 내용까지 바뀐 새 커밋. 저장된 done SHA 는 검증 시점의 코드를 가리키지만 사용자 의도는 리뷰 반영본이다.
+3. **SHA 소멸** — branch 삭제 + GC 후 [`_resolve_commit_sha`](../../../scripts/okstra_ctl/worktree.py:260) 실패 → [worktree.py:781](../../../scripts/okstra_ctl/worktree.py:781) 에서 거부.
+
+현재 세 경우 모두 회복 경로가 없다. 사용자가 할 수 있는 것은 `~/.okstra/worktrees/registry.json` / `consumers.jsonl` 손편집뿐이다.
+
+## 2. 핵심 원칙
+
+1. **SHA = 정본, branch = 입력 수단.** 저장 포맷은 바꾸지 않는다. stale 시 branch(또는 사용자 지정 ref)에서 SHA 를 *다시 캡처*해 새 기록으로 append 한다.
+2. **자동화 수위 (사용자 결정 2026-06-10): 내용 동일 = 자동, 내용 변경 = 확인.** patch-id 로 내용 동일성이 *증명*되는 경우(rebase / cherry-pick / 깨끗한 squash)만 확인 없이 자동 통과·자동 재기록하고 로그를 남긴다. 내용이 바뀐 경우(리뷰 반영 amend 등)는 반드시 사용자 확인(picker)을 거친다. 증명 없는 자동 진행은 금지 — 검증 안 된 커밋이 base 에 섞이는 것을 차단한다.
+3. **append-only 유지.** 보정은 `consumers.jsonl` 에 새 done row 를 append 하는 방식이다(기존 row 수정/삭제 없음). 이를 위해 done-row 읽기를 last-wins 로 통일한다(§3.4 — 선행 조건).
+4. **단일 reference point.** 감지·화해·보정 로직은 Python 모듈 1곳(`git_reconcile.py`)에 두고, prepare 경로·`git-reconcile` subcommand·skill picker 는 모두 그것을 소비한다.
+
+## 3. 구성 요소
+
+### 3.1 content-equivalence 검사기 — `scripts/okstra_ctl/git_reconcile.py` (신규)
+
+`content_merged(project_root, commit, candidate, base) -> MatchResult`
+
+1. `git merge-base --is-ancestor commit candidate` 성공 → 기존대로 통과(`ancestor`).
+2. 실패 시 patch-id fallback, 두 granularity:
+   - **커밋 단위**: `git show <commit> | git patch-id --stable` 을 `merge-base(commit, candidate)..candidate` 구간 각 커밋의 patch-id 와 비교 — rebase / cherry-pick 커버.
+   - **범위 합산**: `git diff <base> <commit> | git patch-id --stable` (stage 작업 전체를 한 diff 로) 을 candidate 구간 커밋들의 patch-id 와 비교 — N 커밋이 1 커밋으로 합쳐진 squash merge 커버. `base` 는 해당 stage 의 base 기록(anchor 또는 선행 done SHA).
+3. 일치 시 candidate 히스토리에서 매칭된 커밋 SHA 를 반환(`patch-equivalent`, 재기록에 사용). 불일치 → `not-merged`.
+
+`commit` 자체가 unresolvable 이면 patch-id 를 계산할 수 없으므로 무조건 confirm 급이다(§3.2).
+
+### 3.2 stale 분류기 — 같은 모듈
+
+`classify(project_root, plan_run_root, task_key) -> StaleReport(JSON 직렬화 가능)`
+
+task 단위로 다음을 점검하고 항목별 `auto` / `confirm` / `ok` 를 매긴다:
+
+| 점검 | stale 조건 | 분류 |
+|---|---|---|
+| anchor (`implementation_base_commit`) | unresolvable | `confirm` (재고정 필요) |
+| 각 stage 의 최신 done `head_commit` | unresolvable | `confirm` |
+| 〃 | resolvable 이지만 해당 stage branch(`-s<N>`) tip 과 불일치 + patch-id 동등 | `auto` (tip 으로 재기록) |
+| 〃 | 〃 + patch-id 불일치 (내용 변경) | `confirm` |
+| 다중 의존 ancestor 게이트 | ancestor 아님 + `content_merged`=`patch-equivalent` | `auto` (매칭 SHA 로 재기록) |
+| 〃 | ancestor 아님 + `not-merged` | `confirm` |
+
+stage branch 가 이미 삭제된 경우 tip 비교는 건너뛰고 candidate(task-key worktree HEAD) 대상 `content_merged` 만 본다.
+
+### 3.3 보정 명령 — `git-reconcile` subcommand
+
+- Python 구현 1곳: `git_reconcile.py` 의 `check()` / `apply()`. Node CLI 는 `bin/okstra` 서브커맨드 표에 `git-reconcile` 추가 + `src/git-reconcile.mjs` 가 [`_python-helper.mjs`](../../../src/_python-helper.mjs)로 패스스루(기존 `migrate` 패턴). `okstra.sh` 는 run 런처(flag 기반)라 ops subcommand dispatch 가 없으므로 배선하지 않는다 — ops 명령은 node CLI 전용(기존 `migrate` 와 동일).
+- `--check`: §3.2 리포트를 JSON 으로 출력 (기본 indent — 사람 가독, `--json` 시 compact 단일 라인 — 기계 파싱). confirm 항목 잔존 시 exit 2.
+- `--apply`: `auto` 항목 일괄 보정. `confirm` 항목은 `--stage <N> --use-ref <branch|sha>` 로 개별 보정(ref 는 즉시 SHA 로 resolve 해 기록), `--reset-anchor <ref>` 로 anchor 재고정.
+- 보정 = `consumers.jsonl` 에 `status="done"` row 재-append. 추가 필드: `reconciled: true`, `reconcile_reason: "<auto-patch-id|user-ref>"`, `replaced_commit: "<old sha>"`. [`append_consumer`](../../../scripts/okstra_ctl/consumers.py:36)에 optional 필드 전달을 허용한다.
+
+### 3.4 done-row 읽기 last-wins 통일 (선행 조건)
+
+현재 읽기 의미가 갈라져 있다: [run.py:489](../../../scripts/okstra_ctl/run.py:489)·[run.py:527](../../../scripts/okstra_ctl/run.py:527)은 첫 행 우선, [run.py:556](../../../scripts/okstra_ctl/run.py:556)(`done_by_stage` dict)은 마지막 행 우선. 보정 row 가 효력을 가지려면 last-wins 가 유일한 의미여야 한다.
+
+- [`consumers.py`](../../../scripts/okstra_ctl/consumers.py)에 `latest_done_by_stage(rows) -> Dict[int, row]` helper 신설.
+- 소비 지점 전부를 helper 로 수렴: [run.py:489](../../../scripts/okstra_ctl/run.py:489), [run.py:527](../../../scripts/okstra_ctl/run.py:527), [run.py:556](../../../scripts/okstra_ctl/run.py:556), [run.py:1467](../../../scripts/okstra_ctl/run.py:1467) 경로. ([`backfill_done_from_carry`](../../../scripts/okstra_ctl/consumers.py:115)의 `done_stages` set 은 존재 여부만 보므로 영향 없음.)
+
+### 3.5 anchor 재고정
+
+[`set_implementation_base`](../../../scripts/okstra_ctl/worktree_registry.py:199)의 "이미 있으면 무시" 규칙(동시 first-stage 수렴용)은 유지. `worktree_registry.py` 에 `reset_implementation_base(..., commit)` 를 추가하되 **호출자는 §3.3 `--reset-anchor` 하나뿐**이다 — prepare 경로가 자동으로 anchor 를 움직이는 일은 없다.
+
+### 3.6 prepare / skill 배선
+
+- **prepare 경로 자동 화해**: [`_resolve_stage_base_commit`](../../../scripts/okstra_ctl/run.py:465)과 final-verification 의 merged 검사([`_is_ancestor`](../../../scripts/okstra_ctl/run.py:1439), [run.py:1488](../../../scripts/okstra_ctl/run.py:1488))가 ancestor 실패 시 `content_merged` 를 호출한다. `patch-equivalent` 면 통과 + 보정 row 자동 append(다음 run 부터는 ancestor 검사로 바로 통과). `not-merged`/unresolvable 이면 `PrepareError` 메시지에 stale 리포트 요약과 `okstra git-reconcile --check` / `--apply` 명령 예시를 포함한다.
+- **skill picker**: `skills/okstra-run/SKILL.md` 에 단계 추가 — prepare 가 위 안내를 담은 `PrepareError` 로 실패하면 `git-reconcile --check --json` 을 실행해 confirm 항목별 picker 를 제시한다. 옵션 구성은 추천 + 직접 입력 규칙을 따른다: ① "stage branch 현재 tip 으로 재기록 (추천)" ② "다른 ref 직접 입력" ③ "중단". 선택 시 `--apply --stage N --use-ref <ref>` 실행 후 prepare 재시도.
+
+> declaration ↔ enforcement: "내용 변경은 확인 필수" 의 강제 지점은 **`apply()` 런타임 가드**다 — `confirm` 분류 항목은 `--use-ref` 없이 절대 보정되지 않으며, 이를 검증하는 pytest 가 박제한다. 프로파일/스킬 문구만으로 끝내지 않는다.
+
+## 4. 시나리오별 동작
+
+| okstra 밖에서 일어난 일 | 동작 |
+|---|---|
+| stage branch rebase (내용 동일) | patch-id 증명 → 자동 통과 + tip SHA 재기록 |
+| squash merge 후 branch 삭제 | 범위 patch-id 일치 → 자동 통과 + squash SHA 재기록 |
+| PR 리뷰 반영 amend (내용 변경) | `confirm` → picker → 사용자 ref 로 재기록 후 진행 |
+| done SHA GC 로 소멸 | `confirm` → picker (ref 직접 입력) |
+| anchor unresolvable | `confirm` → `--reset-anchor` 안내 |
+| 외부 커밋이 단순히 쌓임 (재작성 없음) | stale 아님 — 기존 동작 그대로 |
+
+## 5. 테스트
+
+- **pytest (실 git)**: `mktemp` git repo 에서 rebase / cherry-pick / squash merge / amend / branch 삭제를 실제로 만들어 `content_merged` 와 `classify` 의 분류를 검증. mock 금지 — patch-id·merge-base 는 실제 git 실행으로만 검증된다.
+- **last-wins 회귀**: 같은 stage 에 done row 2개(원본 + reconciled)를 append 한 뒤 base 해석·whole-task 게이트가 마지막 row 를 쓰는지 검증.
+- **enforcement 테스트**: `confirm` 항목이 `--use-ref` 없이 `apply()` 로 보정되지 않음을 박제.
+- **e2e**: `tests-e2e/scenario-<id>-git-reconcile-squash.sh` — stage1 done → squash merge → branch 삭제 → stage2 prepare 가 자동 통과하는 흐름.
+
+## 6. 미해결 / 후속
+
+- 다중 stage 가 섞인 octopus 머지·부분 머지(stage diff 의 일부만 반영)는 patch-id 로 증명 불가 → `confirm` 으로 떨어진다. 의도된 보수성.
+- `--apply` 의 wizard(okstra.sh 대화형) 통합은 skill picker 가 안정된 뒤 별도 plan.

package/docs/superpowers/specs/2026-06-10-stage-group-handoff-design.md

@@ -0,0 +1,156 @@
+# release-handoff stage-group 모드 — 설계
+
+- 작성일: 2026-06-10
+- 상태: 설계 승인됨 (사용자 승인 2026-06-10)
+- 선행: [stage-worktree-isolation-design.md](2026-06-06-stage-worktree-isolation-design.md), [final-verification-whole-task-gate-design.md](2026-06-06-final-verification-whole-task-gate-design.md)
+
+## 1. 배경 / 문제
+
+stage-worktree-isolation 모델에서 implementation 은 **1 run = 1 stage** 이고 stage 마다 격리 브랜치(`<prefix>-<task-id>-s<N>`)가 생긴다. 정식 release 경로는 "모든 stage 를 task-key 브랜치에 수동 머지 → whole-task final-verification `accepted` → release-handoff 로 task 당 PR 1개" 다 ([final-verification.md:40](../../../prompts/profiles/final-verification.md:40)).
+
+문제: stage 단위가 작을 때 task 전체가 끝나기를 기다렸다 PR 하나로 내거나, 반대로 stage 하나짜리 PR 을 여러 번 내는 것 둘 다 비효율이다. 사용자는 **한 task 안에서 stage 일부를 골라 묶어 하나의 PR** 로 내고 싶다 (예: stage 2+3 → PR 1, stage 4+5 → PR 2).
+
+현재 계약이 이를 막는 지점 세 곳:
+
+1. release-handoff 진입 게이트가 whole-task `accepted` 보고서 1개를 요구 ([release-handoff.md:14](../../../prompts/profiles/release-handoff.md:14)).
+2. 단독-stage 검증은 release-handoff 라우팅 금지 ([final-verification.md:29](../../../prompts/profiles/final-verification.md:29), [final-verification.md:40](../../../prompts/profiles/final-verification.md:40)).
+3. release-handoff 는 커밋 생성 금지 ([release-handoff.md:57](../../../prompts/profiles/release-handoff.md:57)) + "okstra 자동 머지 없음" 비목표 ([stage-worktree-isolation-design.md:7](2026-06-06-stage-worktree-isolation-design.md)) — 독립 stage 들은 서로 다른 브랜치에 있어 묶음 PR 의 head 브랜치를 만들 주체가 없다.
+
+## 2. 결정 요약 (브레인스토밍 Q&A)
+
+| 결정점 | 선택 |
+|---|---|
+| 묶음 단위 | 한 task 안의 **stage 일부 그룹** → PR 1개 |
+| 그룹 결정 시점 | **release-handoff 실행 중** 사용자가 PR 가능 stage 목록에서 선택 |
+| 수집 브랜치(그룹 머지) 소유 | **release-handoff** 가 수집 브랜치 생성 + stage 브랜치 merge |
+| 검증 게이트 | **stage 별 단독-stage `accepted` 합산** — 그룹 내 모든 stage 가 각자 accepted 면 진입 허용. 머지된 조합 자체는 미검증이며 충돌 프로브 + PR CI 가 보완 |
+| 의존 폐포 위반 시 | **차단 + 안내** (선행 자동 포함 아님 — 조용한 범위 확장 방지) |
+
+## 3. 목표 / 비목표
+
+목표:
+- release-handoff 에 **stage-group 모드** 추가: done + 단독 검증 accepted + 미-PR stage 들을 골라 수집 브랜치로 머지하고 PR 1개 생성.
+- 자격 판정·수집 머지·PR 기록을 Python 헬퍼 한 곳에서 **강제** (선언이 아니라 enforcement).
+- 기존 whole-task 경로는 불변 — stage-group 은 추가 모드다.
+
+비목표:
+- 여러 task 를 한 PR 로 묶기 (task-group 단위 PR).
+- 그룹 조합에 대한 별도 final-verification 모드 신설 (게이트는 stage 별 accepted 합산; 머지 후 재검증은 사용자가 원하면 단독으로 수행).
+- PR 머지·릴리스 발행 (기존 비목표 유지 — [release-handoff.md:99](../../../prompts/profiles/release-handoff.md:99)).
+- implementation / planning 의 stage 모델·worktree 모델 변경.
+
+## 4. 흐름
+
+```
+stage 2 done ── fv --stage 2 accepted ─┐
+stage 3 done ── fv --stage 3 accepted ─┤
+                                       ▼
+release-handoff (stage-group 모드)
+  G1  PR base 선택 (기존 Q2 와 동일 — 의존 폐포 판정에 필요해 맨 앞으로)
+  G2  stage 선택 (PR 가능 목록에서 multi-select)
+  assemble: 수집 브랜치 생성 + merge   ← okstra_ctl 헬퍼 (강제 지점)
+  Q2b 충돌 프로브 (기존)
+  Q3  PR 제목/본문 확인 (기존)
+  push + gh pr create (head = 수집 브랜치)
+  consumers 에 pr 행 기록
+```
+
+stage-group 모드에서는 base 선택이 stage 선택보다 **앞선다** — G2 조건 4(의존 폐포)의 ancestor 판정과 assemble 이 `origin/<chosen-base>` 를 필요로 하기 때문이다. whole-task 모드의 기존 Q1→Q2 순서는 불변.
+
+### 4.1 진입 게이트 (stage-group 모드)
+
+- brief 가 그룹 후보 stage 들의 **단독-stage final-verification 보고서 N 개**를 인용하고, 각각의 `Verdict Token` 이 `accepted` 인지 lead 가 확인한다. whole-task 모드의 단일 보고서 게이트([release-handoff.md:14](../../../prompts/profiles/release-handoff.md:14))와 병렬 분기.
+- 워킹트리 clean / base 브랜치 금지 / 커밋 존재 게이트는 기존 그대로 ([release-handoff.md:16-18](../../../prompts/profiles/release-handoff.md:16)).
+
+### 4.2 G2 — stage 선택
+
+lead 가 헬퍼(§6)에 G1 에서 고른 base 를 넘겨 **PR 가능 stage 목록**을 받아 multi-select 로 제시한다. PR 가능 조건(전부 헬퍼가 판정):
+
+1. consumers `status:done` ([consumers.py:37](../../../scripts/okstra_ctl/consumers.py:37) `latest_done_by_stage`).
+2. 해당 stage 의 단독-stage final-verification `accepted` 기록 존재 (§5.2 `verified` 행).
+3. 아직 어떤 `pr` 행에도 포함되지 않음 (§5.3).
+4. **의존 폐포**: 모든 선행 stage 가 (a) 같은 그룹에 선택되었거나, (b) 이미 PR 머지되어 `origin/<chosen-base>` 의 ancestor (`git merge-base --is-ancestor <선행 done head_commit> origin/<base>`). 위반 시 해당 조합을 **차단**하고 "선행 stage <N> 을 그룹에 포함하거나 먼저 PR-머지 후 재시도" 안내. 근거: 단일-의존 stage 브랜치는 선행 브랜치 위에 적층되므로([stage-worktree-isolation-design.md §2.2](2026-06-06-stage-worktree-isolation-design.md)), 선행을 빼고 후행만 PR 하면 선행 커밋이 묵시적으로 따라간다.
+
+### 4.3 assemble — 수집 브랜치 생성 + 머지
+
+- base: registry task-key 행의 `implementation_base_commit` ([worktree_registry.py:72](../../../scripts/okstra_ctl/worktree_registry.py:72), [worktree_registry.py:239](../../../scripts/okstra_ctl/worktree_registry.py:239) `get_implementation_base`).
+- 브랜치명: `<work-category-prefix>-<task-id>-g<stage들을 -로 연결>` (예: `feat-dev-9184-g2-3`). 정렬은 stage 번호 오름차순.
+- 워크트리: `~/.okstra/worktrees/<project>/<group>/<task-id>/group-<id>/`, registry 키 `<task-key>#group-<id>` 를 flock 예약 — stage-key 예약과 동일 메커니즘.
+- merge: 선택 stage 브랜치들을 stage 번호 순으로 `git merge` (merge 커밋 허용). **충돌 시 즉시 중단**(`git merge --abort` 후 종료) + 충돌 경로 목록과 "stage 간 충돌 — 수동 해소 또는 그룹 재구성" 안내. rebase / squash / force 금지 유지.
+- 멱등성: 동일 그룹 키의 수집 브랜치가 이미 존재하면 — 그 HEAD 가 동일 stage head 들의 merge 결과(각 stage `done.head_commit` 이 모두 ancestor)일 때만 재사용, 아니면 에러로 중단하고 정리 절차 안내.
+
+### 4.4 PR 초안 / 보고서
+
+- PR 제목/본문 초안 규칙은 기존과 동일하되([release-handoff.md:44-49](../../../prompts/profiles/release-handoff.md:44)), 소스가 stage 별 implementation 보고서 + 단독 검증 보고서 N 개로 늘어난다. diff 범위는 `implementation_base_commit..<수집 브랜치 HEAD>`.
+- 최종 보고서 deliverable 에 **Stage Group** 섹션 추가: 선택 stage 목록, 각 stage 의 검증 보고서 경로·Verdict Token, 수집 브랜치명, merge 커밋 SHA 목록, 의존 폐포 판정 결과.
+
+## 5. 데이터 모델
+
+### 5.1 registry — 그룹 키
+
+stage-key 와 동형의 그룹 키 엔트리:
+
+```jsonc
+"<proj>/<group>/<task-id>#group-g2-3": {
+  "branch": "feat-dev-9184-g2-3",
+  "worktree_path": ".../<task-id>/group-g2-3",
+  "base_ref": "<implementation_base_commit>",
+  "stages": [2, 3],
+  "status": "active"
+}
+```
+
+### 5.2 consumers — `verified` 행 (신규)
+
+단독-stage final-verification 이 `accepted` 로 끝나면 plan_run_root 의 consumers.jsonl 에 기록한다:
+
+```jsonc
+{"impl_task_key": "...", "stage": 2, "status": "verified", "verdict": "accepted", "report_path": "...", "ts": "..."}
+```
+
+- 현재 [consumers.py:50](../../../scripts/okstra_ctl/consumers.py:50) 의 `append_consumer` 는 `started|done` 만 허용 — 허용 집합을 확장한다.
+- 이 행이 G2 조건 2의 SSOT 다. 보고서 파일을 재파싱하지 않고 consumers 만 읽어 자격을 판정한다.
+
+### 5.3 consumers — `pr` 행 (신규)
+
+handoff 가 PR 생성(또는 재사용 확인)에 성공하면 기록한다:
+
+```jsonc
+{"impl_task_key": "...", "stages": [2, 3], "status": "pr", "branch": "feat-dev-9184-g2-3", "url": "https://github.com/...", "ts": "..."}
+```
+
+- "이미 PR 된 stage" 판정(G2 조건 3)의 SSOT. whole-task handoff 도 동일 행을 기록한다(`stages` = 전체) — 두 경로의 중복-PR 방지가 한 데이터로 수렴.
+
+## 6. 강제 지점 — okstra_ctl 헬퍼
+
+자격 판정·assemble·기록은 lead 의 자유 git 호출이 아니라 `scripts/okstra_ctl/` 의 헬퍼 함수(예: `handoff_assemble`)와 CLI 서브커맨드로 단일화한다. lead 는 두 번 호출한다:
+
+1. `handoff-eligible --base <chosen-base>` — PR 가능 stage 목록 + 각 stage 의 차단 사유(미검증/이미 PR/의존 폐포)를 JSON 으로 반환. G2 의 표시 데이터.
+2. `handoff-assemble --stages 2,3 --base <chosen-base>` — 조건 재검증(fail-fast, [run.py](../../../scripts/okstra_ctl/run.py) 의 `PrepareError` 패턴) → registry 그룹 키 예약 → 수집 워크트리/브랜치 생성 → merge → 결과(브랜치명·HEAD·merge SHA 목록) JSON 반환. 위반·충돌 시 비정상 종료 + actionable 메시지.
+
+`pr` 행 기록도 헬퍼 서브커맨드(`handoff-record-pr`)로 수행해 lead 의 수기 JSON append 를 금지한다.
+
+> declaration ↔ enforcement: 프로파일의 MUST 문구는 헬퍼가 보장하는 불변식의 서술이고, 검사 책임은 Python 에 있다 — whole-task 게이트 설계 §5 와 동일 원칙 ([final-verification-whole-task-gate-design.md](2026-06-06-final-verification-whole-task-gate-design.md)).
+
+## 7. 계약 변경점 (문서/프로파일)
+
+| 파일 | 변경 |
+|---|---|
+| [release-handoff.md](../../../prompts/profiles/release-handoff.md) | 진입 게이트에 stage-group 분기(§4.1), G1·G2 신설, allowed actions 에 헬퍼 호출·수집 merge 추가, 커밋 금지 조항을 "수집 브랜치 위 merge 커밋만 허용, 파일 변경 커밋·history rewrite 금지"로 정밀화, deliverable 에 Stage Group 섹션 |
+| [final-verification.md](../../../prompts/profiles/final-verification.md) | line 29·40 의 단독-stage 라우팅 금지를 "단독-stage `accepted` 는 `release-handoff(stage-group)` 라우팅 허용"으로 완화. whole-task 전용 문구는 "단일 task 전체 PR" 한정으로 수정. accepted 시 consumers `verified` 행 기록 의무 추가 |
+| [stage-worktree-isolation-design.md](2026-06-06-stage-worktree-isolation-design.md) | 비목표 "okstra 자동 머지 없음"에 "release-handoff stage-group 수집 머지는 예외(본 설계)" 주석 |
+| [docs/kr/architecture.md](../../kr/architecture.md) | release-handoff 절에 stage-group 모드·consumers `verified`/`pr` 행 계약 반영 |
+
+## 8. 테스트
+
+- unit (`tests/`):
+  - 자격 계산 — done/verified/pr/의존 폐포 각 조건의 포함·제외, ancestor 판정 분기.
+  - `append_consumer` 허용 집합 확장 (`verified`, `pr` 행 round-trip).
+  - registry 그룹 키 예약 — 동시 예약 직렬화, 기존 stage-key 와 비충돌.
+  - assemble — 정상 merge 그래프, 충돌 시 중단·정리, 멱등 재사용 vs 불일치 에러.
+- e2e: `tests-e2e/scenario-<다음 빈 번호>-stage-group-handoff.sh` — 독립 stage 2개 done + verified → eligible 목록 확인 → assemble → 수집 브랜치 커밋 그래프(`git merge-base --is-ancestor` 양방향) 검증 → pr 행 기록 확인. 임시 `OKSTRA_HOME`(`mktemp -d`) + `trap` 정리 관례 준수.
+
+## 9. 미해결 / 후속
+
+- 수집 워크트리·브랜치의 PR 머지 후 정리는 기존 수동 절차(`git worktree remove` → `branch -D` → registry 키 삭제)를 따른다. 자동 GC 는 후속.
+- 그룹 PR 이 base 에 머지된 뒤 남은 stage 들의 whole-task 검증 base 정합(이미 머지된 stage diff 의 중복 표시)은 whole-task 게이트의 기존 ancestor 검사로 흡수되는지 구현 단계에서 확인한다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.67.0",
+  "version": "0.68.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.67.0",
-  "builtAt": "2026-06-10T10:33:26.768Z",
+  "package": "0.68.0",
+  "builtAt": "2026-06-10T14:01:48.019Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -211,8 +211,9 @@ These phases are governed by [okstra-team-contract](./skills/okstra-team-contrac
 
 `TeamCreate` MUST be the first Agent-related tool call after Phase 2 prompt preparation. Do not call `Agent(... team_name: ...)` for any worker until this phase has executed — the Agent tool rejects `team_name` for non-existent teams with `"team을 먼저 생성하거나 team_name 없이 호출해야 합니다"` / `"team must be created first or call without team_name"`, and silently stripping `team_name` to retry is NOT a valid recovery (it loses the Teams split-pane behavior and is indistinguishable from never having attempted Teams mode).
 
-1. Call `TeamCreate(team_name: "okstra-<task-key>", description: "Lead-plus-worker okstra run for <task-key>")`.
-2. Record the `TeamCreate` outcome in team-state under `teamCreate: { attempted: true, status: "ok"|"error", error?: <message> }` before any dispatch. This is the audit trail that justifies a later no-`team_name` fallback.
+1. Call `TeamCreate(team_name: ..., description: "Lead-plus-worker okstra run for <task-key>")`. The team name comes verbatim from the launch prompt's Team Creation Gate block — `okstra-<task-key>`, and implementation stage runs append `-s<N>` (stage isolation: a leftover team from another stage of the same task must not collide).
+2. Record the `TeamCreate` outcome in team-state under `teamCreate: { attempted: true, status: "ok"|"error", error?: <message> }` AND the exact name as `teamName` before any dispatch. This is the audit trail that justifies a later no-`team_name` fallback, and `teamName` is the SSOT every later consumer (teardown, reconcile, token collector) reads.
+2-1. If `TeamCreate` fails with "team already exists" (stale leftover from an earlier attempt): call `TeamList`; if the team is listed in this session, `TeamDelete` it and retry step 1 once. If it is NOT listed, do NOT remove `~/.claude/teams/...` / `~/.claude/tasks/...` with shell commands on your own initiative — that is destructive harness-internal state and `rm -rf` is commonly denied by user permission rules. Ask the user via AskUserQuestion (recommended option: quarantine); on approval, move both dirs into `~/.okstra/trash/<UTC-timestamp>/` with `mv` (reversible), then retry step 1 once.
 3. Verify `team-state.lead.sessionId` is populated. The `okstra.sh` exec path fills it automatically (`generate_claude_session_id` → `claude --session-id ...`). The render-only / in-session takeover path (`okstra-run` skill) auto-detects the live session's jsonl via `resolve_inproc_lead_session_id`, but the detector is best-effort and may return empty if `~/.claude/projects/<encoded-cwd>/` is unreadable or has no jsonl yet. If `lead.sessionId` is empty at this point, write the running session's id into team-state before proceeding — Phase 7 token-usage collection depends on it and will fail with `lead jsonl not found (sessionId=)` otherwise.
 4. If `TeamCreate` succeeds, proceed to Phase 4 (dispatch with `team_name`).
 5. If `TeamCreate` fails (tool unavailable, permission denied, environment lacks Agent Teams support), proceed to Phase 5 fallback (dispatch with `run_in_background: true` and no `team_name`).
@@ -227,7 +228,7 @@ Spawn **analysis workers only** in the same turn (Phase 4 in Teams mode; Phase 5
 
 **Agent `model:` on dispatch (BLOCKING — assignment is otherwise ignored).** The `Claude worker` `Agent(...)` call MUST set `model: "<family token of that role's modelExecutionValue>"` (`fable` / `opus` / `sonnet` / `haiku`), per [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) "Model Assignment Rules" #3–#4. The claude-worker definition is `model: inherit`, so omitting this parameter makes the worker silently run on the lead's model instead of its manifest assignment — the assigned-vs-actual deviation. `Codex worker` / `Gemini worker` are exempt: their CLI model is applied via the wrapper's own `--model` argument, so leave their Agent `model:` at `inherit` (rule #5).
 
-The no-`team_name` fallback (Phase 5) is only legal when team-state's `teamCreate.status` is `"error"` for this run. If `teamCreate` is missing or `attempted: false`, the correct action when an Agent dispatch is rejected for a missing team is to GO BACK to Phase 3 and call `TeamCreate` — never to strip `team_name` and continue.
+The no-`team_name` fallback (Phase 5) is legal when team-state's `teamCreate.status` is `"error"` (TeamCreate attempted and failed) OR `"skipped"` with `reason: "concurrent-run"` (the launch prompt's "Concurrent-run: no-team background" gate pre-decided no team to avoid racing a concurrent same-task run's `~/.claude/teams/` config). In both cases `teamCreate` is recorded in team-state before any dispatch. If `teamCreate` is missing or `attempted: false`, the correct action when an Agent dispatch is rejected for a missing team is to GO BACK to Phase 3 and call `TeamCreate` — never to strip `team_name` and continue.
 
 **Completion detection after dispatch (BLOCKING).** The `Agent(... team_name ...)` call returns `Spawned successfully` immediately; that ack is NOT completion. After dispatching the analysis workers (async), Lead MUST detect their completion via the self-scheduled polling protocol in [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) "Worker-completion detection (self-scheduled polling)" — do NOT restate the algorithm here. Lead MUST NOT end its turn with a prose "waiting for workers" statement; that path stalls the run until the user manually nudges it.
 
@@ -366,7 +367,7 @@ After persistence, reply briefly in the resolved Report Language with: completio
 | Mistake | Fix |
 |---------|-----|
 | Dispatching workers with `team_name` before calling `TeamCreate` (Phase 3 skipped) | Phase 3 is BLOCKING — call `TeamCreate` first. The Agent tool's `"team must be created first"` rejection is not an environment-availability signal |
-| Stripping `team_name` and retrying when the Agent tool rejects the call for a non-existent team | This is silent loss of Teams split-pane mode. Correct action: go back to Phase 3 and call `TeamCreate`. The no-`team_name` fallback (Phase 5) is only legal after `TeamCreate` was attempted and recorded as `error` in team-state |
+| Stripping `team_name` and retrying when the Agent tool rejects the call for a non-existent team | This is silent loss of Teams split-pane mode. Correct action: go back to Phase 3 and call `TeamCreate`. The no-`team_name` fallback (Phase 5) is legal after `TeamCreate` was attempted and recorded as `error` in team-state, OR when the launch prompt's concurrent-run gate recorded `status: "skipped", reason: "concurrent-run"` |
 | Substituting Claude lead reasoning for a worker result | Claude lead synthesizes only — spawn the worker |
 | Skipping a worker silently | Always record terminal status with reason |
 | Writing verdict before all workers report | Wait for all results or explicit terminal statuses |

package/runtime/prompts/profiles/_common-contract.md

@@ -49,16 +49,16 @@ profile document.
   - The question MUST be a clean yes/no — do NOT offer "close some / keep some" partial answers, do NOT propose alternatives like "close only codex panes". The whole-set decision keeps the wrap-up predictable.
   - This step is mandatory for every phase (`requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`). It is silent-skipped when `<RUN_DIR>/state/lead-pane.id` is empty/absent (lead running outside tmux); the lead MUST NOT fabricate a synthetic pane list in that case.
 - Run-end teammate teardown (shared — MUST run AFTER the pane disposition question and BEFORE `PROGRESS: complete`):
-  - The lead created the worker team in Phase 3 (`TeamCreate(team_name: "okstra-<task-key>")`). Worker teammates are NOT reclaimed on their own — without an explicit teardown they linger in the FleetView roster across this and later runs in the session.
-  - This step applies only when team-state's `teamCreate.status == "ok"` (Teams mode was actually used). In the no-`team_name` fallback there is no team to delete, so silent-skip.
+  - The lead created the worker team in Phase 3 (`TeamCreate` with the name recorded as team-state `teamName` — `okstra-<task-key>`, implementation stage runs `okstra-<task-key>-s<N>`). Worker teammates are NOT reclaimed on their own — without an explicit teardown they linger in the FleetView roster across this and later runs in the session. A lingering team also makes the next run of the same task-key collide on `TeamCreate` ("team already exists"), forcing the stale-team recovery path.
+  - This step applies only when team-state's `teamCreate.status == "ok"` (Teams mode was actually used). In the no-`team_name` fallback — whether `teamCreate.status` is `"error"` or `"skipped"` (`reason: "concurrent-run"`) — there is no team to delete, so silent-skip.
   - After the pane disposition step above, the lead MUST ask the user whether to disband the worker teammates. This is a strict binary choice:
-    > worker teammate 팀 `okstra-<task-key>` 을 해제할까요?
+    > worker teammate 팀 `<teamName>` 을 해제할까요?
     > (예) 팀원 정리 / (아니오) 그대로 두기
-  - On `아니오` / `n` / `keep` → do not call `TeamDelete()`. Tell the user that the team will remain visible in FleetView/Teams and can be removed later from the Teams UI, or by asking the lead in this thread to clean up `okstra-<task-key>`.
+  - On `아니오` / `n` / `keep` → do not call `TeamDelete()`. Tell the user that the team will remain visible in FleetView/Teams and can be removed later from the Teams UI, or by asking the lead in this thread to clean up `<teamName>` — and that a later run of the same task-key/stage will hit a "team already exists" collision until it is removed.
   - On `예` / `y` / `cleanup` → emit `PROGRESS: phase-7-teardown disbanding team`, then run the sequence below. Token-usage collection MUST already be complete — `TeamDelete` removes `~/.claude/teams/<team>/` + `~/.claude/tasks/<team>/` but NOT the `~/.claude/projects/` jsonls Phase 7 reads, yet the read MUST precede teardown.
-    1. Run `$HOME/.okstra/bin/okstra-team-reconcile.sh "okstra-<task-key>"` exactly once. It flips dead-pane stale-active members to inactive, and no-ops when tmux is unavailable or nothing is stale. Do NOT loop it.
+    1. Run `$HOME/.okstra/bin/okstra-team-reconcile.sh "<teamName>"` (the team-state `teamName`) exactly once. It flips dead-pane stale-active members to inactive, and no-ops when tmux is unavailable or nothing is stale. Do NOT loop it.
     2. Call `TeamDelete()` — the single synchronization point for teammate teardown. If it errors with an active-members message, send each named active member a structured `SendMessage(to: <name>, message: { type: "shutdown_request" })` — the `message` MUST be the object literal shown, NEVER a JSON string stuffed into a text field — wait briefly, run `okstra-team-reconcile.sh` one more time, retry `TeamDelete()` once, and proceed regardless of the result. NEVER loop and never use `TaskStop` (teammates are not background tasks — `TaskStop` 404s on a member address).
-  - If `TeamDelete()` is unavailable in the current host, or teardown still fails after the single retry, do not pretend cleanup succeeded. Report the exact residual action instead: `Teams/FleetView 에서 team okstra-<task-key> 삭제`, and if tmux panes were kept earlier also show the pane command `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<RUN_DIR>"`.
+  - If `TeamDelete()` is unavailable in the current host, or teardown still fails after the single retry, do not pretend cleanup succeeded. Report the exact residual action instead: `Teams/FleetView 에서 team <teamName> 삭제`, and if tmux panes were kept earlier also show the pane command `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<RUN_DIR>"`.
   - Report successful teardown in one short line (e.g. `worker teammate 팀 해제`, or `stale 멤버 1명 reconcile 후 팀 해제`) and proceed to the final `PROGRESS: complete ...` line.
 - Brief handoff contract (shared — applies whenever the run consumes a task brief produced by `okstra-brief`):
   - the brief is a **pre-discovery artifact**: it converts a domain-reporter's words (non-expert *or* developer) into expert-consumable form so this and later phases can run with zero fill-in questions to the operator. The brief is **not** authoritative on solution decisions; it is authoritative on the reporter's intent.

package/runtime/prompts/profiles/final-verification.md

@@ -26,7 +26,7 @@
 - Pre-verification entry gate (resolved & enforced by `okstra render-bundle` prep — the lead does NOT recompute it):
   - the verification target (scope / worktree / base / head / stages / source reports / diff stat) is injected as the `VERIFICATION_TARGET` block. The lead MUST treat it as authoritative and MUST NOT re-pick a target from the brief.
   - **whole-task scope** (`--stage auto`, default): prep has already verified every Stage Map stage is `status:done` in `consumers.jsonl`, every done stage's `head_commit` is an ancestor of the task worktree HEAD (all stage branches merged), and the worktree is clean outside `.okstra/`. If any check failed the run never started (PrepareError); a started whole-task run is therefore a fully-merged, clean target.
-  - **single-stage scope** (`--stage N`): prep verified stage N is `status:done` and its isolated stage worktree exists and is clean. Other stages' state is irrelevant. A single-stage run is a partial verification and MUST NOT recommend `release-handoff`.
+  - **single-stage scope** (`--stage N`): prep verified stage N is `status:done` and its isolated stage worktree exists and is clean. Other stages' state is irrelevant. A single-stage run is a partial verification: it MUST NOT recommend plain `release-handoff`, but MAY recommend `release-handoff(stage-group)` when the verdict is `accepted` — the stage becomes PR-eligible for a stage-group handoff.
   - the lead still captures `git rev-parse HEAD` / `git status --short` from the injected worktree to confirm the analysis ran against the injected head; a mismatch is a `tool-failure`, not a silent proceed.
 - Required deliverable shape (final report, in addition to the standard sections):
   - **Source Implementation Report(s)**: the `VERIFICATION_TARGET` snapshot verbatim — verification scope, worktree path, base/head SHAs, the list of stages under verification, and one row per stage citing its originating implementation final-report (`report_path` from `consumers.jsonl`; render `(report_path unrecorded)` when absent). The lead injects this same snapshot into every analyser prompt (`**Verification scope:** / **Worktree:** / **Verification base ref:** / **Verification head SHA:** / **Verification diff stat:**`); a worker that cannot confirm its analysis ran against that exact head MUST record a `tool-failure`.
@@ -37,7 +37,8 @@
   - **Read-only command log**: any pre-existing test/validation command executed during this run MUST be listed with its exact command line and exit code. No mutating commands may appear here.
   - **Two-tier command lookup (shared with `implementation`):** when this phase performs its own independent re-validation, the command source is exactly the same two tiers `implementation` verifiers use — Tier 1 is the originating task brief / approved plan's `validation` set, Tier 2 is `<PROJECT_ROOT>/.okstra/project.json` under `qaCommands`. Auto-detecting tools from manifest files is forbidden; missing tiers are recorded as `qa-command not configured: <category>` and do NOT trigger a guess. The `cmd` deny-list (`--fix`, `--write`, ` -w`, ` -u`, `--snapshot-update`, `INSTA_UPDATE=<not-no>`, `cargo update`, `npm install` without `ci`, etc.) is enforced identically. NOTE: runtime fail-fast validation (`okstra_ctl.qa_commands.validate_qa_commands`) only fires at `--task-type implementation` run-prep, so this phase MUST self-check each `qaCommands` entry against the deny-list before executing it — if a denied token is present, skip the command and record it as a `Read-only command log` line `qa-command rejected (denied token: <token>): <label>`.
   - **Tier 3 — stage conformance scripts (whole-task union):** because this phase verifies the **integrated, merged** state, it re-runs conformance against that state rather than per-stage. Read the task-level manifest `<task_root>/qa/conformance-manifest.json` (the directory is the `TASK_QA_PATH` token) and, in **whole-task scope**, run the `runCommand` of **every** `entries[]` item against the merged worktree, refreshing each `<task_root>/qa/result-<stageKey>.json` (`{ "stageKey", "overall": "PASS"|"FAIL"|"MISSING", "ranAt", "requirements" }`). In **single-stage scope**, run only the entry whose `stageKey` matches the verified stage. An entry carrying an `exemption` or user `waiver` is NOT executed — record the skip and reason; a `waiver` becomes a `conditional-accept` condition surfaced in the section 7 Verdict (conformance left unverified by user acknowledgement). Each `runCommand` runs in the worktree cwd with `qaEnv` env (replica DB DSN / app base URL / env file) — **replica / test environment only**, never shared / staging / prod, and the same source/lockfile mutation deny-list applies (a conformance script MAY mutate only its `qaEnv` replica datastore). Interpret each result from the exit code + stdout `QA-RESULT: PASS|FAIL` (last wins) and `REQ <id>: PASS|FAIL: <reason>` lines; no `QA-RESULT` marker → `MISSING`. Any entry whose result is not `PASS` (including `MISSING` or a never-run/missing sidecar) is an **Acceptance Blocker** (`major`+) — exactly like the DB real-execution gate above, since `accepted` requires zero blockers the verdict becomes `conditional-accept` / `blocked`. This is the same gate the `validate-run.py` Tier 3 check enforces on the result sidecars.
-  - **Routing recommendation**: the next safe phase — one of `release-handoff`, `done`, `error-analysis`, `implementation-planning` — tied to the verdict and blocker list. `release-handoff` is allowed ONLY when the Verdict Token is `accepted`. `release-handoff` is additionally allowed ONLY when the verification scope (the `Verification scope:` line of the injected `VERIFICATION_TARGET` block, recorded as the report's `verificationScope` field) is `whole-task`; a `single-stage` run is partial and routes to `implementation` / `done` even on an `accepted` verdict.
+  - **Routing recommendation**: the next safe phase — one of `release-handoff`, `done`, `error-analysis`, `implementation-planning` — tied to the verdict and blocker list. `release-handoff` is allowed ONLY when the Verdict Token is `accepted`. `release-handoff` is additionally allowed ONLY when the verification scope (the `Verification scope:` line of the injected `VERIFICATION_TARGET` block, recorded as the report's `verificationScope` field) is `whole-task`; a `single-stage` accepted run routes to `release-handoff(stage-group)` (or `implementation` / `done`); plain `release-handoff` remains whole-task-only. Enforcement: `validators/validate-run.py` rejects a `single-stage` report whose routing cites plain `release-handoff`.
+  - **Verified-row recording** (single-stage scope only): when the Verdict Token is `accepted`, the lead MUST run `okstra handoff record-verified --plan-run-root <plan-run-root> --stage <N> --report-path <final-report.md path> --data-json <final-report data.json path>` and quote the command + exit code in the report. The helper re-validates taskType/scope/verdict from data.json, so a non-accepted or whole-task report is rejected at the tool layer.
 - Clarification request policy (phase-specific addendum — shared policy is in `_common-contract.md`):
   - populate `## 1. Clarification Items` only when a blocker hinges on information only the user can supply (deployment intent, intended target environment, business-rule interpretation); use `Blocks=next-phase` for items that gate continuing to release-handoff
 - Self-review pass before finalising the report (`Claude lead` runs this; do not delegate to a generic subagent):

package/runtime/prompts/profiles/release-handoff.md

@@ -1,6 +1,6 @@
 # Release Handoff Profile
 
-- Purpose: take an `accepted` final-verification verdict for an already-committed implementation branch and turn it into a delivered push and/or pull request, with explicit user selection at every mutating step
+- Purpose: take an `accepted` final-verification verdict for an already-committed implementation branch and turn it into a delivered push and/or pull request, with explicit user selection at every mutating step. Two modes: **whole-task** (default — the verified task branch becomes one PR) and **stage-group** (a user-selected subset of verified stages is merged into a collector branch and becomes one PR).
 - **Execution model: single-lead, no worker dispatch.** This phase is a thin orchestrator over `git` / `gh`; it does NOT run team-mode, does NOT call `TeamCreate`, does NOT dispatch analysis or drafter sub-agents, and does NOT run convergence. The Claude lead performs every step inline (drafting PR text, asking the user, running git / gh, writing the final report) — see "Lead-only contract" below.
 - Worker roster: none — this profile intentionally has no `- Required workers:` block; the run is executed entirely by the Claude lead.
 - Lead-only contract (replaces the shared team contract for this phase):
@@ -11,7 +11,8 @@
   - The shared "authority & permissions assumption" rule from the common contract still applies: assume the user holds every permission needed; do not block on hypothetical approvals.
   - The shared "MCP read-only" rule still applies if the brief lists MCP servers, though most release-handoff runs do not use MCP.
 - Pre-handoff entry gate (mandatory — refuse to start if any item fails):
-  - the task brief MUST cite the originating `final-verification` final-report path under `## Source Verification Report`. The lead opens that file and confirms section `## 7. Final Verdict` contains a `Verdict Token` field whose value is exactly `accepted`.
+  - **whole-task mode**: the task brief MUST cite the originating `final-verification` final-report path under `## Source Verification Report`; the lead confirms its `Verdict Token` is exactly `accepted` and its `verificationScope` is `whole-task`.
+  - **stage-group mode**: the brief cites N single-stage `final-verification` reports (one per candidate stage); the lead confirms each `Verdict Token` is `accepted`. Eligibility is re-enforced by `okstra handoff` — the lead never hand-computes it.
   - if the verdict is `conditional-accept`, `blocked`, or any other token (including ambiguous phrasing like "looks good"), the run MUST end immediately with status `blocked` and a routing recommendation back to `error-analysis` or `implementation-planning`. Do NOT prompt the user; Do NOT run any git command.
   - the lead MUST capture `git status --short` and confirm the working tree is clean. Dirty state aborts the run; release-handoff packages the commits produced by `implementation`, it does not stage or commit changes.
   - the lead MUST capture `git rev-parse --abbrev-ref HEAD` and record it as the **feature branch**. If the current branch is itself `main`, `master`, `prod`, `preprod`, `staging`, or `dev`, the run MUST end immediately — release-handoff never operates on a base branch.
@@ -22,6 +23,9 @@
      - `push + PR` — push the feature branch, then open or reuse a pull request.
      - `skip` — record the verified state and end the run without any git command.
      If the user picks `skip`, route directly to the final-report self-review pass.
+  - **stage-group mode order**: G1 base branch first (same options as Q2 — the dependency-closure check needs `origin/<base>`), then G2 stage selection, then assemble, then Q2b/Q3 as usual with the collector branch as the PR head.
+  1g. **G2 — stage selection**: run `okstra handoff eligible --plan-run-root <plan-run-root> --approved-plan <approved plan path>` and present the returned stages (eligible ones selectable, blocked ones listed with their `reasons`) as a multi-select. At least one stage must be selected.
+  2g. **assemble**: run `okstra handoff assemble --plan-run-root <...> --approved-plan <...> --project-root <project root> --project-id <id> --task-group <g> --task-id <t> --work-category <c> --stages <csv> --base <chosen-base>`. Exit 2 means a stage-vs-stage merge conflict: show the `conflicts` paths and stop (route: reshape the group or resolve manually). Exit 1 means an eligibility/closure violation: show the error verbatim and re-ask G2. On success the returned `branch` is the PR head branch for every subsequent step.
   2. **PR base branch** (only when the user picked `push + PR`) — present four options and capture exactly one:
      - `staging`
      - `preprod`
@@ -42,7 +46,7 @@
      - `edit then proceed` — accept inline edits from the user, then proceed with the edited text.
      - `cancel` — end the run without executing push or PR commands; record the cancellation in the final report.
 - Inline drafting rules (Claude lead):
-  - read the run brief, the cited final-verification report, `git log --oneline <base>..HEAD`, and `git diff <base>..HEAD --stat` to ground the drafted text in actual committed changes.
+  - read the run brief, the cited final-verification report, `git log --oneline <base>..HEAD`, and `git diff <base>..HEAD --stat` to ground the drafted text in actual committed changes. In stage-group mode the draft is grounded on `git log <implementation_base_commit>..<collector HEAD>` / `git diff <implementation_base_commit>..<collector HEAD> --stat`, with source material = each selected stage's implementation report + its single-stage verification report.
   - **PR body template** — the run context exposes `PR_TEMPLATE_PATH` and `PR_TEMPLATE_SOURCE`. The path MUST be an okstra-owned project artifact under `<PROJECT_ROOT>/.okstra/**` or a file already materialised into this run's artifact directory by the prepare step. The lead MUST `Read` this file verbatim, strip HTML comments, then fill in the placeholders. Do NOT hard-code a section list — the template is the source of truth for the structure. If the resolved file is missing or outside the okstra resource boundary at draft time, abort the run with a clear error rather than inventing a structure.
   - produce **two artifacts** before showing them to the user:
     1. **PR title** — by default the subject of the most recent implementation commit, or a concise Conventional Commits-style summary of the committed range.
@@ -50,11 +54,13 @@
 - Allowed actions during the run (Claude lead only):
   - read-only inspection: `git status`, `git status --short`, `git diff`, `git log`, `git rev-parse`, `git ls-remote --heads origin <name>`, `gh pr list --head <branch>`, `gh pr view <url>`.
   - merge-conflict probe (only when the user picked `push + PR`): `git fetch origin <chosen-base>` and `git merge-tree --write-tree --merge-base origin/<chosen-base> HEAD origin/<chosen-base>`. Both are non-mutating with respect to the working tree.
-  - feature-branch push (only when the user picked `push + PR`): `git push -u origin <current-branch>`. The pushed ref MUST be the feature branch — never the chosen base branch.
+  - feature-branch push (only when the user picked `push + PR`): `git push -u origin <current-branch>`. The pushed ref MUST be the feature branch — never the chosen base branch. (stage-group mode: the collector branch returned by assemble)
   - PR creation (only when the user picked `push + PR` AND no PR with the same head already exists on origin): `gh pr create --base <chosen-base> --head <current-branch> --title "<title>" --body "<body>"`. The title and body are the user-confirmed PR draft.
   - PR reuse: if `gh pr list --head <branch> --state open --json url --jq '.[0].url'` returns a URL, treat that PR as already existing — record the URL in the final report and SKIP `gh pr create`.
+  - after `gh pr create` succeeds (or an existing PR is reused), the lead MUST run `okstra handoff record-pr --plan-run-root <...> --stages <csv> --branch <head branch> --url <pr url>` and quote the command + exit code in the final report. This applies to BOTH modes — whole-task runs record `--stages` as the full Stage Map list — so duplicate-PR prevention converges on one consumers record.
+  - stage-group helpers: `okstra handoff eligible`, `okstra handoff assemble`, `okstra handoff record-pr`. The assemble step is the ONLY path that may create commits (merge commits on the collector branch) in this phase.
 - Forbidden actions (any occurrence → terminal status `contract-violated`):
-  - local commit commands of any kind (`git add`, `git commit`, `git restore --staged`, `git stash`). Commits belong to the prior `implementation` phase.
+  - local commit commands of any kind (`git add`, `git commit`, `git restore --staged`, `git stash`), and any direct `git merge` / `git rebase` run by the lead. The single exception is the merge commits `okstra handoff assemble` itself creates on the collector branch — the lead never merges by hand.
   - any of the following git push variants, regardless of intent or whether the user said "force it":
     - `git push --force`
     - `git push --force-with-lease`
@@ -88,6 +94,7 @@
     - `- PR created: <url>` with title and base branch
     - `- PR reused: <url>` when an existing PR was found via `gh pr list`
     - `- PR creation skipped: <reason>` for any user-driven cancellation
+  - **Stage Group** (stage-group mode only): selected stages, each stage's single-stage verification report path + quoted `Verdict Token` row, collector branch name, merge commit SHAs from assemble, and the dependency-closure verdict (from the assemble output / error).
   - **Routing recommendation**: explicit `done` token, since release-handoff is the terminal lifecycle phase. If the run ended in `skip` or `cancel`, the recommendation MUST also state whether re-entry into release-handoff is appropriate.
 - Self-review pass before finalising the report (`Claude lead` runs this):
   1. **Entry-gate audit** — section 2 cites the originating final-verification report path and the literal `Verdict Token` row with value `accepted`. If either is missing, the run is invalid and MUST be re-routed to `final-verification`.

package/runtime/prompts/wizard/prompts.ko.json

@@ -139,7 +139,7 @@
         "in_worktree": "현재 worktree(`{path}`)에서 그대로 진행합니다(이미 non-main worktree) — 진행할까요?",
         "not_git": "git 저장소가 아니므로 `{path}` 에서 직접 진행합니다 — 진행할까요?"
       },
-      "options": { "proceed": "진행", "edit": "base-ref 다시 고르기" },
+      "options": { "proceed": "진행", "edit": "base-ref 다시 고르기", "abort": "중단" },
       "echo_template": "branch-confirm: {value}"
     },
     "base_ref_text": {