/dev:batch {epic_number}

development
 └── epic/{epic_number}-{slug}            ← Created in Phase 1
      ├── story/{story_1}-{slug}          ← Sequentially processed in Phase 2
      │    ├── task/{subtask_1}-{slug}    ← Sub-tasks processed sequentially within Story
      │    └── task/{subtask_2}-{slug}
      ├── story/{story_2}-{slug}
      └── story/{story_3}-{slug}
                                           ← Epic → development PR in Phase 3

1. Tooling preflight (loop 진입 전 1회):
   - command -v gh  & &   gh auth status   → 미인증이면 즉시 중단(머지 전에 실패, Epic 중간 아님)
   - command -v melos / dart / flutter  → 부재 시 /dev:run  " Step 0 Degradation Contract "   를 따른다(우회 + 경고)
2. Resume 계약 (멱등):
   - 이미 Closed 인 Story 는 건너뛴다(Phase 2에서 상태 확인).
   - 중간 실패 시 `/dev:batch {epic}` 를 다시 실행하면 마지막으로 머지된 Story 다음부터 이어서 처리한다.
   - 따라서 한 Story 실패가 Epic 전체를  " 절반-머지 "   로 영구 고착시키지 않는다.

0.5-1. Seed 탐지 (게이트):
   - SEED=$(ls -1 docs/seed-spec-*.md 2 > /dev/null | tail -1)
   - SEED 가 없으면 → **no-op (조용히 skip)**. 경고도 차단도 없음.
   - SEED 가 있으나 머리글이 `Status: LOCKED` 가 아니면(DRAFT) → **no-op + 1줄 안내**( " 기획 명세 미확정 → 정렬 점검 skip " ). DRAFT 를 강제로 잠그지 않는다.
   - → 즉, 시드가 없거나 미확정인 저장소에서 `/dev:batch` 는 **절대 하드페일하지 않는다**(submodule 동기화 no-op 와 동일한 graceful degradation 형태).

0.5-2. 정렬 점검 (LLM-SEMANTIC, /spec:status 재사용):
   - 대조 대상:
     - pre-batch  → 이번 Epic 아래 **계획된** Story·Sub-task 이슈 집합(제목/본문/AC)
     - post-batch → Phase 3 병합 직후 **완료(Closed)된** 이슈 집합 + Epic 브랜치 누적 변경(diff/PR)
   - `/spec:status --against {계획/완료 이슈 집합 또는 Epic PR}` 를 실행해 LLM-SEMANTIC 정렬 리포트를 받는다:
     - **AC-ID 상태 echo** — Seed S4(Acceptance Boundaries)의 각 합격 기준을 `AC-01`, `AC-02` … 로 식별하고 PENDING / IN-PROGRESS / MET / FAILED / WAIVED 로 표기.
     - **목표 정렬 판정** — 작업 묶음의 의도가 Seed S1(Core Problem)과 같은 방향인지 ALIGNED / MINOR-DRIFT / MAJOR-DRIFT 로 판정.
     - **제약 위반 플래그** — 작업이 위반하는 것으로 보이는 Seed S2(Immutable Constraints) 항목을 나열.
   - ⚠️ **의미 기반 판단만 사용한다(절대 어휘/토큰 일치 아님)**: Seed 와 이슈/AC 텍스트는 **한국어 우선**이라 공백·토큰 겹침 매칭은 조사·띄어쓰기에서 깨진다. drift/정렬/AC 매칭은 모두 **LLM 의미 판단**으로 수행한다(`/spec:status` 와 동일 원칙).

0.5-3. 판정별 행동:
   - ALIGNED / MINOR-DRIFT → 리포트만 출력하고 그대로 진행(차단 아님).
   - **MAJOR-DRIFT → 경고 후 일시정지(필수)**: 어긋난 지점을 요약해 보여주고 `AskUserQuestion` 으로  " 기획과 크게 어긋남 — 그래도 계속할까요? "   확인을 받는다.
     - pre-batch: 사용자가  " 중단 "   선택 시 배치를 시작하지 않고 종료(이슈/명세 조정 후 재실행).  " 계속 "   선택 시 사유를 로그에 남기고 Phase 1 로 진행.
     - post-batch:  " 중단 "   선택 시 Epic 종료를 보류(Epic PR 은 이미 병합됐으므로 추가 후속 이슈로 표류 항목을 추적).  " 계속 "   선택 시 그대로 마무리.
   - 이 점검은 **품질 게이트가 아니라 방향 점검**이다 — 테스트/lint/리뷰 Critical 처럼 hard fail 하지 않고, **MAJOR-DRIFT 에서만 사용자 확인으로 멈춘다**.

0.5-4. 멱등/재개: 읽기 전용이라 부작용이 없다. `/dev:batch {epic}` 재실행 시 pre-batch 점검도 다시 도는 게 정상이며, 이미 Closed 인 Story 는 Phase 2 에서 건너뛴다.

0. (Phase 0.5) Pre-batch seed-alignment checkpoint — LOCKED seed 있으면 LLM-SEMANTIC 정렬 점검(MAJOR-DRIFT 시 확인 후 진행), 없으면 no-op skip
1. Query Epic issue info (ZenHub)
2. Update development branch to latest
3. Create Epic branch: epic/{epic_number}-{slug}
4. Move Epic to In Progress pipeline

Per-Story Cycle:
1. Move Pipeline to  " In Progress "   (+ 활성 스프린트 배정 — /dev:run Step 2.5 상속, --no-sprint 로 opt-out)
2. Create Story branch: story/{story_number}-{slug} (based on Epic branch)
3. If Sub-tasks exist → execute Per-Sub-task Cycle
4. If no Sub-tasks → implement directly
5. Write and run tests
6. Pre-push verification (lint + DCM)
6.5. ⭐ **Per-Story Stall Budget** (verify와 review 사이): 같은 실패가 반복되면 3-rung 래더를 오른다 — (1) same-strategy retry(소폭 바운드), (2) 동일 실패가 **의미상** 반복되면 affinity 페르소나로 `/dev:unstuck solo` 호출(reframe, 재시도 아님), (3) 그래도 안 풀리면 이 Story를 `BLOCKED( ' unstuck_exhausted ' )`로 표시하고 **다음 Story로 계속**(Epic 전체 중단 금지). 상세는 `sequential-workflow.md`의  " Stall Budget "   참조.
7. Code Review Gate
8. Create PR → targeting Epic branch (base: epic/{epic_number}-{slug}); PR body에 `Closes #{story_number}` + `Parent Epic: #{epic_number}` 포함
9. Squash merge (머지 = Close) — base가 **Epic 브랜치(비기본 브랜치)** 이므로 GitHub `Closes #`는 **자동으로 닫지 않습니다**.
9.5. ⭐ **명시적 Close (필수 — 폴백 아님)**: `gh issue close {story} --reason completed` 로 직접 닫기 → `gh issue view {story} --json state`로 `CLOSED` 확인 → ZenHub `searchClosedIssues  " #{story} " `에 없으면 `updateIssue state:CLOSED` (Done ≠ closed)
10. ⭐ Post-merge: `git checkout epic/{epic_number}-{slug}  & &   git pull --ff-only origin epic/{epic_number}-{slug}  & &   git submodule sync --recursive  & &   git submodule update --init --recursive` (base 최신화 + 서브모듈 동기화) — submodule sync/update 실패는 **경고 후 계속**(Epic 중단 아님). 서브모듈 없으면 no-op.
11. Move to next Story

Per-Sub-task Cycle:
1. Create Sub-task branch: task/{subtask_number}-{slug} (based on Story branch)
2. Implementation work
3. Write and run tests
4. Verification gate
5. Create PR → targeting Story branch (base: story/{story_number}-{slug}); PR body에 `Closes #{subtask_number}` + `Parent Story: #{story_number}` 포함
6. Squash merge (머지 = Close) — base가 **Story 브랜치(비기본 브랜치)** 이므로 GitHub `Closes #`는 **자동으로 닫지 않습니다**.
6.5. ⭐ **명시적 Close (필수 — 폴백 아님)**: `gh issue close {subtask} --reason completed` 로 직접 닫기 → `CLOSED` 확인 → ZenHub 미동기화 시 `updateIssue state:CLOSED`
7. ⭐ Post-merge: `git checkout story/{story_number}-{slug}  & &   git pull --ff-only origin story/{story_number}-{slug}  & &   git submodule sync --recursive  & &   git submodule update --init --recursive` (base 최신화 + 서브모듈 동기화)
8. Move to next Sub-task

1. ⛔ 완료성 Hard Gate (필수, 실행형) — 모든 하위 Story·Sub-task 이슈가 정말 Closed 인지 확인. prose 확인 금지:
     const children = await mcp__zenhub__searchLatestIssues({ query: `parent:${epicId}` }); // getChildrenOfParent 없음
     const open = children.filter(c = >   (c.state ||  " " ).toUpperCase() !==  " CLOSED " );          // GitHub state = source of truth
     if (children.length === 0) →  " 판정 불가 " : 자식이 없는 게 맞는지 사용자 확인 후에만 진행
     if (open.length  >   0) → ⛔ Epic PR/머지/종료 중단. BLOCKED( ' unstuck_exhausted ' ) 도 OPEN 으로 간주.
       throw `Epic #${epic} 미완료: OPEN child ${open.length}개 (${open.map(c= > " # " +c.number)}). 해결/재시도 후 batch 재실행`
2. Review changes against development
3. Create Epic PR → targeting development; PR body에 `Closes #{epic_number}` 포함
4. Conduct code review
5. Squash merge after user approval (머지 = Close)
6. **Epic 이슈 종료** — `development`가 저장소 **기본(default) 브랜치**면 `Closes #{epic_number}`로 자동 닫힘, 아니면 자동으로 닫히지 않으므로 명시적 종료 필요.
6.5. ⭐ Close 검증 + 폴백: `gh issue view {epic} --json state` → 미close 시 `gh issue close {epic} --reason completed`; ZenHub 미동기화 시 `updateIssue state:CLOSED`
6.6. ⭐ **Project 재귀 확인** — Epic이 Project(또는 Initiative)의 자식이면, `checkAndCloseParent(epic_number)`(`commands/agents/dev/issue-state-agent.md`)를 호출해 형제 Epic이 모두 Closed인지 확인 후 상위를 자동 종료(연쇄적으로 Initiative까지). Epic이 최상위(부모 없음)면 no-op.
7. ⭐ Post-merge: `git checkout development  & &   git pull --ff-only origin development  & &   git submodule sync --recursive  & &   git submodule update --init --recursive` (base 최신화 + 서브모듈 동기화)
8. (Phase 0.5) Post-batch seed-alignment checkpoint — LOCKED seed 있으면 완료된 이슈 집합 + Epic PR 을 LLM-SEMANTIC 으로 재대조(AC-ID 상태 echo + 목표 정렬 판정), MAJOR-DRIFT 시 경고 후 Epic 종료 확인. 없으면 no-op skip.

┌─────────────────────────────────────────────────────────────┐
│  /dev:batch {epic_number}                                    │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Phase 1: Epic Branch Creation                               │
│  ├── Query Epic issue (ZenHub)                               │
│  ├── git checkout development  & &   git pull                   │
│  ├── git checkout -b epic/{number}-{slug}                   │
│  └── git push -u origin epic/{number}-{slug}                │
│                                                              │
│  Phase 2: Sequential Story Processing                        │
│  ├── Query Story list (child issues)                         │
│  ├── for each Story:                                         │
│  │   ├── /dev:run --base epic/{number}-{slug} {story_num}   │
│  │   │   ├── Branch: story/{story}-{slug}                    │
│  │   │   ├── [If Sub-tasks exist]                            │
│  │   │   │   └── Per-Sub-task Cycle                          │
│  │   │   │       ├── task/{subtask}-{slug} (Story-based)    │
│  │   │   │       ├── Implement → Test → Verify               │
│  │   │   │       └── PR → Merge into Story branch            │
│  │   │   ├── Implement → Test → Verification Gate            │
│  │   │   └── PR → Merge into Epic branch                     │
│  │   └── Next Story                                          │
│  │                                                           │
│  Phase 3: Epic PR Creation                                    │
│  ├── Create Epic branch → development PR                     │
│  ├── Review full changes                                     │
│  ├── Wait for user approval                                  │
│  └── Squash merge → Epic Close                               │
│                                                              │
└─────────────────────────────────────────────────────────────┘

// Phase 1: Initialization
const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();
const epic = await mcp__zenhub__searchLatestIssues({ query: `#${epicNumber}` });
const stories = await mcp__zenhub__searchLatestIssues({
  query: `parent:${epic[0].id}`,
});

// Phase 2: Per-Story processing
for (const story of stories) {
  // Check Sub-tasks
  const subtasks = await mcp__zenhub__searchLatestIssues({
    query: `parent:${story.id}`,
  });

  if (subtasks.length  >   0) {
    // Story with Sub-tasks → create Story branch first
    // Process Sub-tasks sequentially, then integrate into Story branch
    for (const subtask of subtasks) {
      // /dev:run --base story/{story_number}-{slug} {subtask.number}
    }
    // PR Story branch to Epic branch
  } else {
    // Story without Sub-tasks → implement directly
    // /dev:run --base epic/{epic_number}-{slug} {story.number}
  }
}

// Phase 3: Epic PR
// gh pr create --base development --title  " [Epic] ... "

const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();
const pipelines = workspace.pipelines;
// Find by name in pipelines:  " New Issues " ,  " In Progress " ,  " Review/QA " , etc.
// Done pipeline is NOT used (Done ≠ closed). Merge = Close: `Closes #` → GitHub closed
// → ZenHub syncs to Closed. Verify with searchClosedIssues + fallback updateIssue.

gh pr create --base  " epic/{epic_number}-{slug} "   \
  --title  " {story.title} "   --body  " $(cat  < < ' EOF ' 
 ## Summary
- {Change summary}

## Related Issue
- Closes #{story.number}
- Parent Epic: #{epic_number}

## Test Plan
- [ ] UseCase unit tests passed
- [ ] BLoC unit tests passed

🤖 Generated with [Claude Code](https://claude.ai/claude-code)
EOF
) "

gh pr create --base  " story/{story_number}-{slug} "   \
  --title  " {subtask.title} "   --body  " $(cat  < < ' EOF ' 
 ## Summary
- {Change summary}

## Related Issue
- Closes #{subtask_number}
- Parent Story: #{story_number}

## Test Plan
- [ ] Unit tests passed

🤖 Generated with [Claude Code](https://claude.ai/claude-code)
EOF
) "

gh pr create --base  " development "   \
  --title  " [Epic] {epic.title} "   --body  " $(cat  < < ' EOF ' 
 ## Summary
- {Epic full change summary}

## Included Stories
- ✅ #{story_1} - {title}
- ✅ #{story_2} - {title}
- ✅ #{story_3} - {title}

## Related Issue
- Closes #{epic_number}

## Test Plan
- [ ] Full integration tests passed
- [ ] Manual testing complete

🤖 Generated with [Claude Code](https://claude.ai/claude-code)
EOF
) "