makdoong2-team 2.3.2 → 3.0.0

package/stages/01-planning.md

@@ -1,4 +1,4 @@
-# 1–3단계 통합 Planning — `1_planning.{jira,requirements,scope}` 연속 처리
+# 통합 Planning — `1_planning.{jira,requirements}` 연속 처리
 
 **목적**: Jira 조회 → 요구사항 확정 → 개발 범위 파악을 **단일 세션**에서 완료한다.  
 **속도**: 3개 substage dispatch(모델 호출 3회)를 1회로 단축.  
@@ -15,12 +15,10 @@
 ```bash
 bash <SCRIPTS_DIR>/state.sh get <이슈키> '.stages."1_planning".substages."jira".done'
 bash <SCRIPTS_DIR>/state.sh get <이슈키> '.stages."1_planning".substages."requirements".done'
-bash <SCRIPTS_DIR>/state.sh get <이슈키> '.stages."1_planning".substages."scope".done'
 ```
 
 - `jira.done=true` → Phase 1 건너뛰고 Phase 2로 직행
-- `jira.done=true` + `requirements.done=true` → Phase 3으로 직행
-- 셋 다 `true` → 모두 완료. 완료 메시지 출력 후 종료
+- 둘 다 `true` → 모두 완료. 완료 메시지 출력 후 종료
 
 ---
 
@@ -89,7 +87,11 @@ mkdir -p .makdoong2-team/<이슈키>
 
 파일 (repo/worktree root 기준 상대경로): `.makdoong2-team/<이슈키>/requirements-draft.md`
 
-**초안 파일은 반드시 `write` 툴(filePath 인자)로 생성·갱신한다.** bash 리디렉션(`cat > …`, `printf > …` 등)과 `apply_patch` 는 같은 경로라도 훅이 차단한다 — planner 의 유일한 파일 쓰기 수단은 `write` 다. 이 경로의 `write` 는 planner READ-ONLY 원칙의 명시적 예외이며 훅이 허용한다 (issue #8).
+**초안 파일은 반드시 쓰기 *툴* 로 생성·갱신한다 — bash 리디렉션(`cat > …`, `printf > …`, `tee`, `sed -i` 등)은 같은 경로라도 훅이 차단한다.**
+- 세션에 `write` 툴이 있으면 `write(filePath=…)` 를 쓴다.
+- **`write` 가 툴 목록에 없으면 `apply_patch` 를 쓴다.** opencode 는 모델에 따라 쓰기 툴을 바꿔 끼운다 — `gpt-5` 계열 세션에는 `write`·`edit` 가 아예 없고 `apply_patch` 만 있다. 이때 패치 본문은 `*** Begin Patch` / `*** Add File: .makdoong2-team/<이슈키>/requirements-draft.md` / `*** End Patch` 형식으로 정확히 작성한다 — 훅이 본문에서 대상 경로를 파싱해 허용 경로면 통과시킨다.
+- **툴이 없다는 이유로 초안 생성을 포기하지 않는다.** 둘 중 실제로 존재하는 툴을 골라 즉시 실행하고, 차단 메시지를 받으면 그 메시지가 지시하는 형식으로 재시도한다.
+- 이 경로의 파일 쓰기는 planner READ-ONLY 원칙의 명시적 예외이며 훅이 허용한다 (issue #8).
 
 초안 구조:
 ```markdown
@@ -104,36 +106,29 @@ mkdir -p .makdoong2-team/<이슈키>
 ```bash
 # state.json 에는 반드시 상대경로만 저장한다 (절대경로 저장 시 다른 cwd 에서 접근 불가 → Read hang 유발).
 # 이 마커는 §2-5b 의 spec_hash 와 **한 쌍**이다 — spec_hash 만 기록되고 이것이 빠지면
-# stage3-scope-verify.sh 가 1_planning.scope 진입을 하드 차단한다 (issue #6-①).
+# stage-analysis-verify.sh 가 2_implementation.analysis 진입을 하드 차단한다 (issue #6-①).
 bash <SCRIPTS_DIR>/state.sh set <이슈키> \
   '.stages."1_planning".substages."requirements".draft_path' '".makdoong2-team/<이슈키>/requirements-draft.md"'
 ```
 
-### 2-3. 다출처 교차 조사 (병렬)
+### 2-3. 다출처 교차 조사
 
-**`dispatch_research` 툴 1회 호출로 소스별 조사를 병렬 실행한다.** `skill_mcp` 를 직접 순차 호출하지 않는다 — 플러그인이 소스마다 별도 세션을 동시에 띄우므로 대기 시간이 가장 느린 소스 하나로 수렴하고, 각 소스의 원자료가 이 세션의 컨텍스트를 잠식하지 않는다. **outer-world 에이전트 위임 금지.**
+**당신의 세션에서 직접 조사한다.** 소스마다 `skill(name=...)` 로 스킬을 먼저 로드한 뒤 그 스킬의 MCP 를 호출한다. 로드 전에 `skill_mcp` 를 부르면 `MCP server "<name>" not found` 로 실패한다. **outer-world 에이전트 위임 금지.**
 
-```
-dispatch_research(
-  issue = "<이슈키>",
-  worktree = "<Working directory 절대경로>",
-  context = "<Phase 1 에서 요약한 Jira 핵심 3~5줄>",
-  queries = [
-    {source: "jira",       focus: "에픽/상위 이슈, 링크 이슈, 관련 코멘트에서 구체화된 요구"},
-    {source: "confluence", focus: "관련 설계 문서, ADR, API 스펙, 운영 가이드"},
-    {source: "bitbucket",  focus: "수정 대상 파일/클래스 현재 구현, 관련 PR 이력, 테스트 패턴"}
-  ]
-)
-```
-
-조사 세션은 서로를 보지 못한다. **한 focus 가 다른 조사 결과에 의존하면 안 된다** — 의존이 필요하면 라운드를 나눠 두 번 호출한다.
+| 소스 | skill | mcp_name | 조사 범위 |
+|---|---|---|---|
+| Jira | `jira-research` | `works` | 에픽·상위 이슈·링크 이슈·서브태스크·코멘트에서 구체화된 요구와 결정 사항 |
+| Confluence | `confluence-research` | `docs` | 설계 문서·ADR·API 스펙·운영 가이드의 제약과 합의된 규약 |
+| Bitbucket | `bitbucket-research` | `repos` | 수정 대상 파일·클래스의 현재 구현, 관련 PR 이력, 기존 테스트 패턴 |
+| GitHub OSS | `github-oss-research` | (없음 — WebFetch) | 외부 오픈소스의 사용 예시·알려진 이슈·업스트림 변경 |
 
-Simple 이슈는 조사 A + C만으로 축소 가능. 외부 라이브러리가 쟁점이면 `{source: "github-oss", ...}` 를 추가한다.
+기본 조사는 **Jira → Bitbucket** 두 소스다. 설계·규약이 쟁점이면 Confluence 를, 외부 라이브러리가 쟁점이면 GitHub OSS 를 더한다. Simple 이슈는 Jira 하나로 끝낼 수 있다.
 
-**결과 읽기**: 반환 JSON 의 `artifact_path` (`.makdoong2-team/<이슈키>/research-findings.json`) 를 Read 로 읽는다. `failed` 가 있어도 **부분 성공이 정상**이므로 나머지 결과로 진행하고, 실패 소스가 요구사항 확정에 필수인 경우에만 사유를 사용자에게 보고한다. 전 소스 실패(`ok: false`)면 추측으로 채우지 말고 보고한다.
+**조사 예산은 소스당 최대 5회 호출이다.** 초과하면 그 소스는 거기서 멈추고 미확인 항목을 `미결 사항` 에 적는다.
 
-- **`status: "partial"` 은 그 자체로 정상 종료다.** 실패한 소스를 당신이 직접 조사해 메우려 하지 말 것 — `skill_mcp` 순차 호출로 결손을 메우려다 세션 예산을 전부 소진하고 **마커를 하나도 남기지 못한 채** 종료한 사고가 이틀 연속 재현됐다 (GitHub issue #9, 각 27분·17분 소모). 결손을 더 좁히고 싶으면 focus 를 좁혀 `dispatch_research` 를 **1회만** 다시 호출한다.
-- **조사 완결성을 이유로 마커 기록을 미루지 않는다 (hardrule).** 조사가 부분적이면 `gaps` 에 미확인 항목을 남기고 그 상태 그대로 산출물과 substage 마커를 기록한 뒤 종료한다. 마커가 없는 종료는 상위에서 `completion: "incomplete"` 로 분류되어 substage 전체가 재실행된다 — 부분 결과까지 함께 버려진다.
+- **부분 조사는 그 자체로 정상 종료다.** 한 소스가 응답하지 않으면 그 소스를 포기하고 나머지로 진행한다. 결손을 메우려 같은 소스를 계속 두드리다 세션 예산을 전부 소진하고 **마커를 하나도 남기지 못한 채** 종료한 사고가 이틀 연속 재현됐다 (GitHub issue #9, 각 27분·17분 소모).
+- **조사 완결성을 이유로 마커 기록을 미루지 않는다 (hardrule).** 조사가 부분적이면 미확인 항목을 초안의 `미결 사항` 에 남기고 **그 상태 그대로** 산출물과 substage 마커를 기록한 뒤 종료한다. 마커가 없는 종료는 상위에서 `completion: "incomplete"` 로 분류되어 substage 전체가 재실행된다 — 부분 결과까지 함께 버려진다.
+- 조사 결과는 별도 파일로 만들지 않는다. `requirements-draft.md` 의 `## 수집된 정보` 에 소스별로 정리한다 (출처 URL 포함).
 
 ### 2-4. 요구사항 체크리스트 확인
 
@@ -176,7 +171,7 @@ category = (criticality == "critical" OR scope_size == "large") ? "major" : base
 
 ```bash
 bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy' \
-  '{"intent_type":"Standard","change_type":"bugfix","scope_size":"small","criticality":"normal","category":"minor","auto_approve":{"1_planning.requirements":true,"1_planning.scope":true,"3_delivery.commit":true,"3_delivery.pr":true},"rationale":"<한 줄 근거>","categorized_by":"1_planning.requirements"}'
+  '{"intent_type":"Standard","change_type":"bugfix","scope_size":"small","criticality":"normal","category":"minor","auto_approve":{"1_planning.requirements":true,"3_delivery.commit":true,"3_delivery.pr":true},"rationale":"<한 줄 근거>","categorized_by":"1_planning.requirements"}'
 bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy.categorized_at' "\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\""
 ```
 
@@ -184,7 +179,7 @@ major 로 판정된 경우에도 `auto_approve` 맵은 **모두 true** 로 두
 
 ### 2-5b. 요구사항 품질 마커 (ambiguity_score · spec_hash)
 
-`stage3-scope-verify.sh` 의 요구사항 품질 게이트는 **이 두 마커가 있을 때만** 검사한다
+`stage-analysis-verify.sh` 의 요구사항 품질 게이트는 **이 두 마커가 있을 때만** 검사한다
 (구형 state 호환을 위한 조건부 검사). 즉 여기서 기록하지 않으면 통합 경로에서는
 품질 게이트가 통째로 사문화된다 — `02-requirements.md` 를 거치는 분리 경로에서는
 검사되는데 이 경로에서만 안 되는 비대칭이 생긴다. 반드시 기록한다.
@@ -206,23 +201,9 @@ bash <SCRIPTS_DIR>/state.sh get <이슈키> '.stages."1_planning".substages."req
 bash <SCRIPTS_DIR>/state.sh get <이슈키> '.stages."1_planning".substages."requirements".spec_hash'
 ```
 
-### 2-6. Requirements 완료 기록
+### 2-5c. 개발 범위 확정 (구 `1_planning.scope` — 흡수됨)
 
-```bash
-bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."requirements".self_check' \
-  '{"checklist_complete":true,"conflicts_resolved":true,"user_confirmed":true,"scope_clean":true,"draft_synced":true,"categorized":true,"ambiguity_scored":true,"spec_frozen":true,"draft_recorded":true}'
-bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."requirements".verification_pending' 'false'
-bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."requirements".done' 'true'
-bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."requirements".done_at' "\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\""
-```
-
----
-
-## Phase 3: 개발 범위 파악 (`1_planning.scope`)
-
-2단계 조사 결과로 코드 수정 계획을 수립한다. 2단계 `bitbucket-research` 탐색을 이어서 사용한다.
-
-### 3-1. 범위 출력
+범위 확정은 요구사항 확정과 **같은 판단의 연속**이라 별도 substage 를 두지 않는다. 조사 결과로 코드 수정 계획을 여기서 함께 확정한다. §2-3 의 `bitbucket-research` 탐색을 이어서 사용한다.
 
 ```
 ### 개발 범위
@@ -234,27 +215,27 @@ bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."req
 **스코프 아웃**: <이번 이슈에서 다루지 않는 것>
 ```
 
-### 3-2. 범주 재평가 (escalation — 하향 금지)
+이 블록은 `requirements-draft.md` 에도 그대로 남긴다 — dev 단계가 초안을 읽고 작업 단위를 잡는다.
 
-실제 수정/추가 파일과 작업 단위가 확정된 뒤, `scope_size`·`criticality`를 재평가한다.
+**범주 재평가 (escalation — 하향 금지)**: 실제 수정/추가 파일과 작업 단위가 확정된 뒤 `scope_size`·`criticality` 를 재평가한다. minor → major 상향인 경우에만 갱신하며, `auto_approve` 맵은 건드리지 않고 **모두 true 로 유지**한다 — 상향은 위험도 라벨 정정에 그치고 흐름은 무인 진행을 유지한다:
 
-minor → major로 상향될 경우에만 아래 항목들을 갱신한다. `auto_approve` 맵은 건드리지 않고 **모두 true 로 유지**한다 — 상향은 위험도 라벨 정정에 그치며 흐름 자체는 무인 진행으로 유지된다:
 ```bash
 bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy.category' '"major"'
 bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy.scope_size' '"large"'
-bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy.categorized_by' '"1_planning.scope"'
+bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy.categorized_by' '"1_planning.requirements"'
 ```
 
-### 3-3. Scope 완료 기록
+### 2-6. Requirements 완료 기록
 
 ```bash
-bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."scope".self_check' \
-  '{"paths_explicit":true,"test_scope_defined":true,"atomic_units":true,"scope_out_listed":true,"user_approved":true}'
-bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."scope".verification_pending' 'false'
-bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."scope".done' 'true'
-bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."scope".done_at' "\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\""
+bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."requirements".self_check' \
+  '{"checklist_complete":true,"conflicts_resolved":true,"user_confirmed":true,"scope_clean":true,"draft_synced":true,"categorized":true,"ambiguity_scored":true,"spec_frozen":true,"draft_recorded":true,"paths_explicit":true,"test_scope_defined":true,"atomic_units":true,"scope_out_listed":true}'
+bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."requirements".verification_pending' 'false'
+bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."requirements".done' 'true'
+bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."requirements".done_at' "\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\""
 ```
 
+
 ---
 
 ## 최종 출력

package/stages/02-requirements.md

@@ -62,7 +62,11 @@ mkdir -p .makdoong2-team/<ISSUE_KEY>
 
 파일 경로 (repo/worktree root 기준 상대경로): `.makdoong2-team/<ISSUE_KEY>/requirements-draft.md`
 
-**초안 파일은 반드시 `write` 툴(filePath 인자)로 생성·갱신한다.** bash 리디렉션(`cat > …`, `printf > …` 등)과 `apply_patch` 는 같은 경로라도 훅이 차단한다 — planner 의 유일한 파일 쓰기 수단은 `write` 다. 이 경로의 `write` 는 planner READ-ONLY 원칙의 명시적 예외이며 훅이 허용한다 (issue #8).
+**초안 파일은 반드시 쓰기 *툴* 로 생성·갱신한다 — bash 리디렉션(`cat > …`, `printf > …`, `tee`, `sed -i` 등)은 같은 경로라도 훅이 차단한다.**
+- 세션에 `write` 툴이 있으면 `write(filePath=…)` 를 쓴다.
+- **`write` 가 툴 목록에 없으면 `apply_patch` 를 쓴다.** opencode 는 모델에 따라 쓰기 툴을 바꿔 끼운다 — `gpt-5` 계열 세션에는 `write`·`edit` 가 아예 없고 `apply_patch` 만 있다. 이때 패치 본문은 `*** Begin Patch` / `*** Add File: .makdoong2-team/<이슈키>/requirements-draft.md` / `*** End Patch` 형식으로 정확히 작성한다 — 훅이 본문에서 대상 경로를 파싱해 허용 경로면 통과시킨다.
+- **툴이 없다는 이유로 초안 생성을 포기하지 않는다.** 둘 중 실제로 존재하는 툴을 골라 즉시 실행하고, 차단 메시지를 받으면 그 메시지가 지시하는 형식으로 재시도한다.
+- 이 경로의 파일 쓰기는 planner READ-ONLY 원칙의 명시적 예외이며 훅이 허용한다 (issue #8).
 
 초안 초기 구조:
 ```markdown
@@ -90,42 +94,30 @@ bash <SCRIPTS_DIR>/state.sh set <이슈키> \
 
 ## 2-1. 다출처 교차 조사
 
-Jira 본문만 보고 판단하지 않는다. 세 출처를 **모두 교차 검증**한다.
+Jira 본문만 보고 판단하지 않는다. 아래 출처를 **교차 검증**한다.
 
-**`dispatch_research` 툴 1회 호출로 소스별 조사를 병렬 실행한다.** 스스로 `skill_mcp` 를 순차 호출하지 않는다 — 플러그인이 소스마다 별도 세션을 동시에 띄우므로 (a) 대기 시간이 가장 느린 소스 하나로 수렴하고, (b) 각 소스의 원자료가 당신의 컨텍스트를 잠식하지 않는다. **outer-world 에이전트 위임(Sisyphus/Explore/Librarian, `task(subagent_type=...)`) 금지** — planner 에는 `Task` 툴이 없어 물리적으로도 불가하다.
+**당신의 세션에서 직접 조사한다.** 소스마다 `skill(name=...)` 로 스킬을 먼저 로드한 뒤 그 스킬의 MCP 를 호출한다 — 로드 전에 `skill_mcp` 를 부르면 `MCP server "<name>" not found` 로 실패한다. **outer-world 에이전트 위임(Sisyphus/Explore/Librarian, `task(subagent_type=...)`) 금지** — planner 에는 `Task` 툴이 없어 물리적으로도 불가하다.
 
-```
-dispatch_research(
-  issue = "<이슈키>",
-  worktree = "<Working directory 절대경로>",
-  context = "<Jira 요약 3~5줄 — 모든 조사 세션에 공통 주입>",
-  queries = [
-    {source: "jira",       focus: "에픽/상위 이슈, 링크 이슈(blocks/relates/causes), 같은 컴포넌트·라벨의 최근 해결 이슈, 코멘트에서 명확해진 요구"},
-    {source: "confluence", focus: "<시스템·모듈명> 설계 문서, 아키텍처/API 스펙/운영 가이드/회의록, ADR·기술선택 기록"},
-    {source: "bitbucket",  focus: "<수정 대상 추정 파일/클래스>의 현재 구현, 유사 기능의 과거 구현, 관련 영역 최근 PR 의 변경 패턴·테스트 방식·리뷰 지적"}
-  ]
-)
-```
-
-- **조사 A — Jira 맥락 심화** (`source: "jira"`)
-- **조사 B — 설계 문서** (`source: "confluence"`). 키워드는 description 명사구·시스템명·프로토콜 번호.
-- **조사 C — 기존 코드·PR 이력** (`source: "bitbucket"`)
-- **(필요 시) 조사 D — 오픈소스** (`source: "github-oss"`): 외부 라이브러리 공식 예제·이슈 트래커, 버전 호환성·알려진 버그.
+| 조사 | 소스 | skill | mcp_name | 무엇을 찾나 |
+|---|---|---|---|---|
+| A | Jira | `jira-research` | `works` | 에픽/상위 이슈, 링크 이슈(blocks/relates/causes), 같은 컴포넌트·라벨의 최근 해결 이슈, 코멘트에서 명확해진 요구 |
+| B | Confluence | `confluence-research` | `docs` | `<시스템·모듈명>` 설계 문서, 아키텍처/API 스펙/운영 가이드/회의록, ADR·기술선택 기록 |
+| C | Bitbucket | `bitbucket-research` | `repos` | `<수정 대상 추정 파일/클래스>` 의 현재 구현, 유사 기능의 과거 구현, 관련 영역 최근 PR 의 변경 패턴·테스트 방식·리뷰 지적 |
+| D | GitHub OSS | `github-oss-research` | (없음 — WebFetch) | 외부 라이브러리 공식 예제·이슈 트래커, 버전 호환성·알려진 버그 |
 
-`focus` 는 구체적일수록 좋다. 조사 세션은 서로를 보지 못하므로 **한 focus 가 다른 조사 결과에 의존하면 안 된다.** 의존이 필요하면 라운드를 나눠 두 번 호출한다.
+조사 A/C 는 항상 수행한다. B 는 설계·규약이 쟁점일 때, D 는 외부 라이브러리가 쟁점일 때 더한다. Simple 유형은 A 만으로 끝낼 수 있다.
 
-조사 A/B/C 는 이슈 유형과 무관하게 모두 시도한다 (Simple 유형만 A/C 로 축소 가능).
+**조사 예산은 소스당 최대 5회 호출이다.** 초과하면 그 소스는 거기서 멈추고 미확인 항목을 초안의 `미결 사항` 에 적는다.
 
-### 결과 읽기
+### 결과 정리
 
-반환 JSON 의 `artifact_path` (기본 `.makdoong2-team/<이슈키>/research-findings.json`) 를 Read 로 읽어 종합한다.
+조사 결과는 **별도 파일로 만들지 않는다.** `requirements-draft.md` 의 `## 수집된 정보` 에 소스별로 정리하고, 근거가 있는 항목에만 출처 URL 을 단다. 확인하지 못한 것은 `## 미결 사항` 으로 보낸다 — 추측으로 채우지 않는다.
 
-- **부분 성공이 정상이다.** `failed` 배열에 실패 소스와 사유가 담긴다. 남은 소스의 결과는 그대로 유효하므로 실패 1건으로 조사를 통째로 다시 돌리지 않는다.
-- 실패한 소스가 **요구사항 확정에 필수**라면 그 사유(인증 실패·권한 부족 등)를 사용자에게 보고한다. 없어도 되는 소스면 `gaps` 로만 남기고 진행한다.
-- `deferred` 가 비어 있지 않으면 병렬 상한에 걸려 빠진 조사가 있다는 뜻이다. 필요하면 2차 호출한다.
-- 모든 소스가 실패하면(`ok: false`) 체크리스트를 추측으로 채우지 말고 사용자에게 보고한다.
-- **`status: "partial"` 은 그 자체로 정상 종료다.** 실패한 소스를 당신이 직접 조사해 메우려 하지 말 것 — `skill_mcp` 순차 호출로 결손을 메우려다 세션 예산을 전부 소진하고 **마커를 하나도 남기지 못한 채** 종료한 사고가 이틀 연속 재현됐다 (GitHub issue #9, 각 27분·17분 소모). 결손을 더 좁히고 싶으면 focus 를 좁혀 `dispatch_research` 를 **1회만** 다시 호출한다.
-- **조사 완결성을 이유로 마커 기록을 미루지 않는다 (hardrule).** 조사가 부분적이면 `gaps` 에 미확인 항목을 남기고 그 상태 그대로 산출물과 substage 마커를 기록한 뒤 종료한다. 마커가 없는 종료는 상위에서 `completion: "incomplete"` 로 분류되어 substage 전체가 재실행된다 — 부분 결과까지 함께 버려진다.
+- **부분 조사가 정상 종료다.** 한 소스가 응답하지 않으면 그 소스를 포기하고 나머지로 진행한다. 실패 1건으로 조사를 통째로 다시 돌리지 않는다.
+- 실패한 소스가 **요구사항 확정에 필수**라면 그 사유(인증 실패·권한 부족 등)를 사용자에게 보고한다. 없어도 되는 소스면 `미결 사항` 으로만 남기고 진행한다.
+- 모든 소스가 실패하면 체크리스트를 추측으로 채우지 말고 사용자에게 보고한다.
+- **결손을 메우려 같은 소스를 계속 두드리지 말 것.** 그러다 세션 예산을 전부 소진하고 **마커를 하나도 남기지 못한 채** 종료한 사고가 이틀 연속 재현됐다 (GitHub issue #9, 각 27분·17분 소모).
+- **조사 완결성을 이유로 마커 기록을 미루지 않는다 (hardrule).** 조사가 부분적이면 미결 항목을 남기고 **그 상태 그대로** 산출물과 substage 마커를 기록한 뒤 종료한다. 마커가 없는 종료는 상위에서 `completion: "incomplete"` 로 분류되어 substage 전체가 재실행된다 — 부분 결과까지 함께 버려진다.
 
 ## 2-2. 요구사항 체크리스트
 
@@ -238,7 +230,7 @@ bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."req
 bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."requirements".spec_hash' \
   "\"$(sha256sum .makdoong2-team/<이슈키>/requirements-draft.md | cut -d' ' -f1)\""
 ```
-3. **동결 후 변경 절차**: `done` 이후 요구사항 변경이 필요해지면 파일을 몰래 수정하지 않는다. 부장님에게 에스컬레이션 → 사용자 재승인 → requirements substage 재작업(명세 갱신 + `spec_hash` 재기록) 순서만 허용된다. `stage3-scope-verify.sh` 진입 게이트가 해시를 재계산해 무단 변경(spec drift)을 차단한다.
+3. **동결 후 변경 절차**: `done` 이후 요구사항 변경이 필요해지면 파일을 몰래 수정하지 않는다. 부장님에게 에스컬레이션 → 사용자 재승인 → requirements substage 재작업(명세 갱신 + `spec_hash` 재기록) 순서만 허용된다. `stage-analysis-verify.sh` 진입 게이트가 해시를 재계산해 무단 변경(spec drift)을 차단한다.
 
 ## 2-4b. 작업 범주화 (minor / major) — auto-approve 정책 결정
 
@@ -252,7 +244,7 @@ bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."req
 | `scope_size`  | `small` / `large` | 수정 파일 수·작업 단위·영향 모듈. 단일~소수 파일·국소 변경 = small |
 | `criticality` | `normal` / `critical` | 인증·결제·보안·데이터 무결성·마이그레이션·대외 API 등 실패 시 파급이 큰 영역 = critical |
 
-> `scope_size`는 2단계 시점엔 추정치다 — 3단계(범위 확정)에서 실제 변경 단위가 드러나면 minor→major로 **상향 조정(escalation)** 될 수 있다(하향은 금지). `03-scope.md` 참조.
+> `scope_size`는 이 시점엔 추정치다 — §2-6(개발 범위 확정)에서 실제 변경 단위가 드러나면 minor→major로 **상향 조정(escalation)** 될 수 있다(하향은 금지).
 
 ### 범주 도출 규칙 (결정론)
 
@@ -276,7 +268,7 @@ category = (criticality == "critical" OR scope_size == "large") ? "major" : base
 ### 기록 (필수 — done 직전)
 
 ```bash
-bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy' '{"intent_type":"Standard","change_type":"bugfix","scope_size":"small","criticality":"normal","category":"minor","auto_approve":{"1_planning.requirements":true,"1_planning.scope":true,"3_delivery.commit":true,"3_delivery.pr":true},"rationale":"<한 줄 근거 — 왜 이 범주인지>","categorized_by":"1_planning.requirements"}'
+bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy' '{"intent_type":"Standard","change_type":"bugfix","scope_size":"small","criticality":"normal","category":"minor","auto_approve":{"1_planning.requirements":true,"3_delivery.commit":true,"3_delivery.pr":true},"rationale":"<한 줄 근거 — 왜 이 범주인지>","categorized_by":"1_planning.requirements"}'
 bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy.categorized_at' "\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\""
 ```
 
@@ -297,7 +289,7 @@ major 로 판정되어도 `auto_approve` 맵은 **모두 true** 로 두고 `"cat
 | 6 | 작업 범주화(2-4b)가 끝나 `.policy.category`(minor\|major)와 `auto_approve` 맵이 기록되었다 |
 | 7 | `ambiguity_score`가 산정·기록되었고 최종값 ≤ 0.2 이다 (2-3-2b) |
 | 8 | 확정 명세가 동결되어 `spec_hash`가 기록되었다 (2-4a) |
-| 9 | `draft_path` 마커가 state.json에 기록되었다 (2-0). **`spec_hash`와 한 쌍이다** — `stage3-scope-verify.sh`가 `spec_hash`만 있고 `draft_path`가 없으면 `1_planning.scope` 진입을 하드 차단한다 |
+| 9 | `draft_path` 마커가 state.json에 기록되었다 (2-0). **`spec_hash`와 한 쌍이다** — `stage-analysis-verify.sh`가 `spec_hash`만 있고 `draft_path`가 없으면 `2_implementation.analysis` 진입을 하드 차단한다 |
 
 **9번은 자기선언이 아니라 실제 값을 읽어 확인한다** — `draft_synced`(파일 동기화)가 true 여도 마커는 빠질 수 있다. 실제로 `spec_hash`만 기록되고 `draft_path`가 누락된 채 8항목 전부 true 로 종료되어, 다음 게이트에서 워크플로우가 정지한 사례가 있다 (issue #6-①).
 
@@ -320,7 +312,7 @@ bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."req
 
 **승인 경로** — 2-4b의 `.policy.auto_approve."1_planning.requirements"`를 따른다:
 
-- **auto_approve == true** (정상 — minor/major 공통): 사람 대기 없이 자동 진행. `verification_pending`을 즉시 `false`로 둔다. 게이트(`stage3-scope-verify.sh`)가 정책을 보고 사용자 승인 없이 통과시킨다.
+- **auto_approve == true** (정상 — minor/major 공통): 사람 대기 없이 자동 진행. `verification_pending`을 즉시 `false`로 둔다. 게이트(`stage-analysis-verify.sh`)가 정책을 보고 사용자 승인 없이 통과시킨다.
   ```bash
 bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."requirements".verification_pending' 'false'
 ```
@@ -334,3 +326,29 @@ bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."req
 bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."requirements".verification_pending' 'false'
 ```
 
+
+---
+
+## 2-6. 개발 범위 확정 (구 `1_planning.scope` — 흡수됨)
+
+범위 확정은 요구사항 확정과 **같은 판단의 연속**이라 별도 substage 를 두지 않는다. §2-1 조사 C(Bitbucket) 탐색을 이어서 사용해 코드 수정 계획을 여기서 함께 확정하고, 아래 블록을 `requirements-draft.md` 에도 남긴다 — dev 단계가 초안을 읽고 작업 단위를 잡는다.
+
+```
+### 개발 범위
+**수정 파일**: <path>: <변경 요지>
+**추가 파일**: <path>: <목적>
+**테스트 범위**: 단위(<대상 클래스/메서드>), 통합(<빌드 플랜명/시나리오>)
+**영향 범위**: <모듈>: <영향 요지>
+**예상 작업 단위(커밋 후보)**: 1. <단위1> 2. <단위2>
+**스코프 아웃**: <이번 이슈에서 다루지 않는 것>
+```
+
+**범주 재평가 (escalation — 하향 금지)**: 실제 수정/추가 파일과 작업 단위가 확정된 뒤 `scope_size`·`criticality` 를 재평가한다. minor → major **상향만** 허용한다. `auto_approve` 맵은 건드리지 않고 모두 true 로 유지한다 — 상향은 위험도 라벨 정정에 그치고 흐름은 무인 진행을 유지한다.
+
+```bash
+bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy.category' '"major"'
+bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy.scope_size' '"large"'
+bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy.categorized_by' '"1_planning.requirements"'
+```
+
+self_check 에 `paths_explicit` / `test_scope_defined` / `atomic_units` / `scope_out_listed` 4항목을 함께 기록한다.

package/stages/04-analysis.md

@@ -2,7 +2,7 @@
 
 **목적**: 개발 진입 전에 workspace 구조·의존성·관례·통합 지점을 결정론적으로 분석하고, 그 결과를 고정 JSON schema로 산출한다. 로컬 LLM 계열이 분석을 건너뛰고 코드 생성으로 직행하는 문제를 harness 레벨에서 차단하는 phase gating 이다.
 
-**진입 게이트**: `verify.sh <이슈키> 2_implementation.analysis` (3단계 scope 완료 필요).
+**진입 게이트**: `verify.sh <이슈키> 2_implementation.analysis` (`1_planning.requirements` 완료 + 승인 + 요구사항 품질 게이트 통과 필요).
 
 > 게이트가 build tool 마커 파일 부재를 감지하면 자동 스킵 처리한다 (`skipped=true`, `done=true` 마킹 후 dispatch 없이 dev substage 로 진행). 본 명세는 게이트를 통과하여 dispatch 된 경우에만 실행된다.
 
@@ -84,7 +84,7 @@ Build tool 별 대응:
 3단계 scope substage 에서 확정한 수정 대상 파일 목록을 state.json 에서 조회한다.
 
 ```bash
-bash <SCRIPTS_DIR>/state.sh get <이슈키> '.stages."1_planning".substages."scope"' 2>/dev/null
+bash <SCRIPTS_DIR>/state.sh get <이슈키> '.stages."1_planning".substages."requirements"' 2>/dev/null
 ```
 
 scope 결과의 각 파일에 대해 실제 파일을 read + grep 하여:

package/stages/05-worktree-dev.md

@@ -6,6 +6,21 @@
 
 > `<SCRIPTS_DIR>`는 부장님이 dispatch_stage 프롬프트로 주입한 절대경로다. 이 값을 그대로 대입하여 실행한다.
 
+## 4-0-pre. 임시 파일 경로 (hardrule)
+
+임시 파일·스크래치가 필요하면 **worktree 안**에만 만든다:
+
+```
+<worktree>/.makdoong2-team/<이슈키>/tmp/
+```
+
+**`/tmp` 을 비롯한 워크스페이스 밖 경로는 사용 금지다.** 두 가지 이유다:
+
+1. opencode 는 bash 명령이 참조하는 디렉토리마다 `external_directory` 승인을 묻는다. 서브에이전트 세션에서 그 요청은 답할 사람이 없어 **자동 거부되고 세션이 그 자리에서 종료된다** — 하던 작업이 통째로 날아간다.
+2. 워크스페이스 밖에 쓴 것은 worktree 동기화 대상도 커밋 대상도 아니다. **산출물이 조용히 사라진다.**
+
+위 경로는 cwd 안이라 승인이 필요 없고, `.git/info/exclude` 에 이미 등록돼 있어 `git status` 를 오염시키지 않는다.
+
 ## 4-0. Analysis 결과 읽기 (필수 — 개발 시작 전)
 
 analysis substage 가 산출한 `workspace-analysis.json` 을 읽어 구현 방향을 확정한다. **이 단계를 건너뛰면 기존 코드 패턴과 불일치한 구현이 발생할 수 있으므로 반드시 수행한다.**

package/agents/makdoong2-researcher.md

@@ -1,68 +0,0 @@
----
-name: makdoong2-researcher
-description: workflow research fan-out worker — 단일 소스(Jira / Confluence / Bitbucket / GitHub OSS) 만 읽기 전용 조사하고 고정 스키마 JSON 을 반환한다. dispatch_research 툴이 소스별로 병렬 spawn 한다. 직접 호출하지 않는다.
-temperature: 0.1
-mode: subagent
-tools:
-  Read: true
-  Bash: true
-  Grep: true
-  Glob: true
-  skill: true
-  skill_mcp: true
-  Write: false
-  Edit: false
-  Patch: false
-  MultiEdit: false
-permission:
-  bash:
-    "*": "allow"
-    "git commit*": "deny"
-    "git push*": "deny"
-    "git add*": "deny"
-    "git rm*": "deny"
-    "git reset --hard*": "deny"
-    "git branch -D*": "deny"
-    "git worktree add*": "deny"
-    "git worktree remove*": "deny"
-    "rm -rf*": "deny"
-  # 정식 키는 `edit`. researcher 는 파일을 쓰지 않는다 — 결과는 응답 텍스트로 반환한다.
-  edit:
-    "**/*": "deny"
----
-
-당신은 **리서치 막둥이**다. 배정받은 **소스 한 곳만** 조사하고 고정 스키마 JSON 을 반환한다.
-
-`dispatch_research` 툴이 소스마다 별도 세션을 병렬로 띄운다. 당신의 세션에는 당신이 맡은 소스의 자료만 쌓인다 — 이것이 fan-out 의 목적이므로 **다른 소스를 기웃거리지 않는다.**
-
-## 하드룰
-
-1. **읽기 전용.** 파일 생성·수정 불가 (Write/Edit 프론트매터 차단). state.json 도 건드리지 않는다 — 결과 저장은 플러그인이 한다.
-2. **배정된 소스만.** 프롬프트의 `Research source` 에 적힌 소스 외의 skill 을 로드하지 않는다.
-3. **skill 먼저, MCP 나중.** `skill(name=...)` 로 스킬을 로드하기 전에 `skill_mcp` 를 부르면 `MCP server "<name>" not found` 로 실패한다. 순서를 지킨다.
-4. **추측 금지.** 확인하지 못한 것은 `findings` 에 넣지 않고 `gaps` 에 적는다. `url` 은 실제 출처가 있을 때만 넣는다.
-5. **outer-world 에이전트 위임 금지.** Task 툴이 프론트매터에서 제거되어 물리적으로 불가하다.
-
-## 실행 규약
-
-bash 명령은 **실행 후 결과로 판단**한다. 실행 전 permission 을 추론하지 않는다. `[makdoong2-team hook] BLOCKED:` stderr 로그가 나온 것만 실제 차단이다.
-
-## 출력 규약
-
-마지막 assistant turn 에 ```json 펜스 블록을 **정확히 하나** 출력한다. 스키마는 dispatch 프롬프트에 명시되어 있다:
-
-```json
-{
-  "source": "<배정받은 source>",
-  "findings": [{"title": "...", "detail": "...", "url": "... 또는 null"}],
-  "gaps": ["확인하지 못한 항목"]
-}
-```
-
-- 조사 결과가 없어도 **JSON 블록은 반드시 출력한다.** `findings: []` + `gaps` 에 이유를 적는다.
-- 블록을 출력하지 않으면 플러그인이 파싱 실패로 기록하고 해당 소스는 `status: "failed"` 가 된다.
-- 펜스 블록 앞뒤의 한국어 설명은 자유다. 단 JSON 블록은 하나여야 한다 (여러 개면 마지막 것이 채택된다).
-
-## 조기 종료
-
-MCP 인증 실패(exit 68/69), 접근 권한 부족, 대상 부재 등으로 조사가 불가능하면 **재시도로 시간을 쓰지 말고** 즉시 `findings: []` + `gaps` 에 사유를 적어 반환한다. 한 소스의 실패는 다른 소스의 조사를 막지 않는다 — 플러그인이 부분 성공으로 병합한다.

package/dist/research-fanout.d.ts

@@ -1,165 +0,0 @@
-/** Research sources backed by a lazy-loaded MCP skill. */
-export type ResearchSource = "jira" | "confluence" | "bitbucket" | "github-oss";
-export interface ResearchSourceSpec {
-    source: ResearchSource;
-    /** `skill(name=…)` — MUST be loaded before the MCP call (lazy-load, ARCHITECTURE.md §4.4). */
-    skill: string;
-    /**
-     * `skill_mcp(mcp_name=…)` for sources whose SKILL.md declares an embedded MCP.
-     * `null` for skills that carry no MCP of their own (github-oss-research works
-     * through WebFetch / site-wide chrome-devtools-mcp) — the prompt branches on this.
-     */
-    mcp: string | null;
-    /** Korean label used in prompts and the merged artifact. */
-    label: string;
-    /** What this source is good for — injected into the research prompt. */
-    scope: string;
-}
-export declare const RESEARCH_SOURCES: Record<ResearchSource, ResearchSourceSpec>;
-/** Hard ceiling on simultaneously spawned research sessions, regardless of config. */
-export declare const MAX_RESEARCH_PARALLEL = 6;
-/** Default when `research.max_parallel` is unset. */
-export declare const DEFAULT_RESEARCH_PARALLEL = 3;
-/** Default per-source wall-clock budget when `research.timeout_minutes` is unset. */
-export declare const DEFAULT_RESEARCH_TIMEOUT_MINUTES = 10;
-/** Focus text longer than this is truncated before it reaches the prompt. */
-export declare const MAX_FOCUS_CHARS = 600;
-/** Per-source cap on findings kept in the merged artifact. */
-export declare const MAX_FINDINGS_PER_SOURCE = 20;
-export interface ResearchQueryInput {
-    source?: unknown;
-    focus?: unknown;
-}
-export interface NormalizedQuery {
-    spec: ResearchSourceSpec;
-    focus: string;
-}
-export interface RejectedQuery {
-    source: string;
-    reason: string;
-}
-export interface NormalizeResult {
-    queries: NormalizedQuery[];
-    rejected: RejectedQuery[];
-    /** Queries dropped because they exceeded the parallel cap (reported, never silent). */
-    deferred: RejectedQuery[];
-}
-export declare function resolveResearchSource(name: unknown): ResearchSourceSpec | null;
-/** Clamp the configured parallelism into [1, MAX_RESEARCH_PARALLEL]. */
-export declare function resolveParallelism(configured: unknown): number;
-/**
- * Validate + de-duplicate the caller's queries.
- *
- * Rules:
- *  - unknown source → rejected (the caller mistyped; failing loudly beats a silent no-op)
- *  - empty focus → rejected
- *  - same (source, focus) twice → the duplicate is rejected
- *  - more than `limit` survivors → the tail is DEFERRED, never silently dropped
- */
-export declare function normalizeQueries(raw: unknown, limit: number): NormalizeResult;
-export interface ResearchPromptContext {
-    issue: string;
-    scriptsDir: string;
-    worktree: string;
-    /** Optional extra context from the caller (e.g. the Jira summary). */
-    context?: string;
-}
-/**
- * Prompt for one research sub-session.
- *
- * The session is deliberately narrow: one source, one focus, fixed output schema.
- * That is what makes the fan-out worth its cost — each session's context holds
- * only its own source's material instead of all three (DESIGN.md §3.7).
- */
-export declare function buildResearchPrompt(q: NormalizedQuery, ctx: ResearchPromptContext): string;
-export interface ResearchFinding {
-    title: string;
-    detail: string;
-    url: string | null;
-}
-export interface ParsedResearch {
-    findings: ResearchFinding[];
-    gaps: string[];
-}
-export type ParseResult = {
-    ok: true;
-    data: ParsedResearch;
-} | {
-    ok: false;
-    reason: string;
-};
-/**
- * Pull the research JSON out of an LLM turn.
- *
- * Order matters: prefer the LAST fenced ```json block (models often show a draft
- * before the final answer), then fall back to a balanced brace scan. A parse
- * failure is reported, never coerced into an empty-but-successful result — a
- * silently empty source reads as "nothing to find" when it means "nothing parsed".
- */
-export declare function parseResearchOutput(raw: unknown): ParseResult;
-export interface SourceOutcome {
-    source: ResearchSource;
-    label: string;
-    focus: string;
-    status: "ok" | "failed";
-    findings: ResearchFinding[];
-    gaps: string[];
-    error: string | null;
-    session_id: string | null;
-    elapsed_ms: number;
-}
-export interface ResearchFindingsArtifact {
-    issue: string;
-    generated_at: string;
-    sources: SourceOutcome[];
-    rejected: RejectedQuery[];
-    deferred: RejectedQuery[];
-    counts: {
-        requested: number;
-        ok: number;
-        failed: number;
-        findings_total: number;
-    };
-}
-/**
- * Merge per-source outcomes into the artifact a gate can check deterministically.
- *
- * `rejected` / `deferred` are carried into the artifact on purpose: a fan-out that
- * quietly covered 2 of 3 sources looks identical to one that covered all 3 unless
- * the shortfall is written down.
- */
-export declare function mergeResearchFindings(issue: string, generatedAt: string, outcomes: SourceOutcome[], rejected: RejectedQuery[], deferred: RejectedQuery[]): ResearchFindingsArtifact;
-/** Human-readable one-liner per source for the tool's text return. */
-export declare function summarizeOutcomes(outcomes: SourceOutcome[]): string[];
-export type FanoutStatus = "ok" | "partial" | "failed";
-export interface FanoutOutcome {
-    status: FanoutStatus;
-    /** `false` only when NO source produced anything. */
-    ok: boolean;
-    /** `true` when some sources succeeded and others did not. */
-    partial: boolean;
-    next_action: string;
-}
-/**
- * Turn the merged counts into the caller-facing verdict.
- *
- * Why this is not just `ok = okCount > 0`: a fan-out that covered 1 of 3 sources
- * returned the same shape as one that covered all 3, and the only difference was
- * a `failed` array the caller had to notice on its own. It did not — on two
- * consecutive days Confluence and Bitbucket both timed out at exactly 10 minutes,
- * the planner treated the Jira-only result as its evidence base, and then spent
- * the rest of its budget trying to make up the difference by hand and recorded
- * no markers at all (GitHub #9). A shortfall has to arrive as its own field with
- * its own instruction, not as something to infer.
- *
- * Deliberately NOT an automatic retry of the failed sources: both failures were
- * full-budget timeouts, so retrying in place spends another `timeout_ms` for the
- * same result and pushes the parent session past its own deadline. The caller
- * gets the shortfall and decides — narrower focus, a later round, or proceed
- * with recorded gaps.
- */
-export declare function classifyFanoutOutcome(counts: {
-    requested: number;
-    ok: number;
-    failed: number;
-}, artifactPath: string | null, failedSources: string[]): FanoutOutcome;