--- task_id: task-2509 type: context scope: task created: 2026-05-08 updated: 2026-05-08 status: completed --- # 맥락 노트: task-2509 **task**: task-2509 --- ## 결정 근거 ### [1] 별도 모듈 `utils/merge_queue_executor.py` 신규 생성 (auto_merge.py 임시 하드코딩 금지) - 회장 명시: "auto_merge.py에 임시 하드코딩 금지 (별도 모듈 `utils/merge_queue_executor.py`)" — task spec L162 - task-2510~2513의 5 모듈 #1로서 후속 모듈 hook을 깔끔하게 박제하려면 단일 책임 모듈이 필요 - 대안 (auto_merge.py 확장) 기각: 단일 함수 비대화 + state machine 추적 어려움 ### [2] CLI는 dispatch.py 미경유 dry-run 우선 - merge_topology_gate.py와 동일 패턴 (Phase 1 dry-run + Phase 2 production gate) - dry-run에서 `BLOCKED_WITH_REASON: ` JSON 출력 → 호출자가 후속 분기 결정 - `--no-dry-run` 명시 시에만 실제 squash merge — 안전 default ### [3] 후속 모듈 hook은 문자열 상수로만 박제 (실제 호출 X) - task-2510~2513은 별도 task로 분리됨 → hook 호출 = 후속 task에서 구현 - 본 task는 인터페이스 정의 + 분기 path 박제 + 회귀 테스트로 인터페이스 안정성 검증 ### [4] 회귀 테스트는 subprocess CompletedProcess mock 기반 - 실제 gh CLI / git 호출 없이 12 케이스 모두 결정 분기 검증 가능 - RunnerType callable injection 패턴 (executor 내부 ExecutorContext.runner) 사용 - fixture replay (PR #57/#56/#55)은 main HEAD `2cd8178b` SHA + expected_files 단순 mock ## 3 Step Why 자문 **1st Why** — 왜 이 설계가 필요한가? A: 회장 직접 명령 — "정책 문서화가 아니라 코드 자동화 단계로 전환". 회장 승인 의존을 제거하고 Critical 7종에서만 보고하는 자동 머지 파이프라인이 5 모듈 시리즈의 핵심 entrypoint이기 때문. **2nd Why** — 왜 A가 최선의 접근인가? B: 단일 모듈 + RunnerType injection 패턴이 (1) 회귀 테스트 100% mock 가능, (2) state machine을 evaluate_pr → verify_head_lock_then_merge 2단계로 분리해 §9 SHA lock 시점이 코드에 명시됨, (3) Critical 7종을 enum으로 박제해 task-2513에서 reporter만 wiring하면 됨. 단일 책임 모듈이 후속 4 모듈의 변경 표면을 최소화한다. **3rd Why** — 왜 B가 다른 대안보다 나은가? C: 대안 1 (auto_merge.py 확장) — 단일 함수 비대화 + state 추적 불가 (회장 §6 force/admin/rebase 정적 차단 어려움). 대안 2 (dispatch.py에 통합) — dispatch 격리 원칙 위배 + 머지 후 책임 모호. 대안 3 (여러 작은 모듈) — 본 task에서 5 모듈 #1만 진입점 정의하라는 명시 위반. 따라서 단일 모듈 + injection 패턴이 정책 + 테스트 가능성 + 후속 hook 호환의 trilemma를 푼다. **검증**: A(자동 머지 파이프라인 필요) → B(단일 모듈 + injection) → C(대안 모두 trilemma 위반) — 일관됨. ## 참조 자료 - 회장 명세: `memory/tasks/task-2509.md` §1~14 (필수 구현 14건) + 회귀 §1~12 - 정책 본체: `memory/feedback/feedback_critical_escalation_only_260508.md` (자동 머지 10조건 + Critical 7종) - Merge Topology Gate: `memory/feedback/feedback_merge_topology_gate_260508.md` - 인접 모듈: `utils/merge_topology_gate.py` (CLI dry-run 패턴 참조) - 실전 fixture: PR #57 → #56 → #55 (main HEAD `2cd8178b`) - audit 디렉토리: `memory/orchestration-audit/merge-queue.jsonl` (global), `memory/events/{task_id}.merge-queue.json` (per-task) ## 주의사항 - `--admin` / `--force` / rebase / required CI bypass — 모두 정적 assert로 차단 - `auto_merge.py`에 임시 하드코딩 절대 금지 — 새 모듈로 격리 - expected_files 외 파일 수정 시 → `replacement_pr_runner` (task-2510) hook으로만 분기, 실제 cherry-pick 구현 금지 - HEAD SHA lock — 검증 시작 SHA 와 merge 직전 SHA 비교 필수 (§9) - post-merge smoke 실패는 Critical 7종 #7 (`POST_MERGE_SMOKE_FAILURE`) — 회장 보고 대상 - contaminated branch 재활용 금지 — replacement PR은 신규 브랜치만 - audit 박제는 정상 자동 처리에는 evidence만, 장문 보고 X - 본 task는 5 모듈의 #1 — 후속 hook은 인터페이스만 정의, 구현 X