makdoong2-team 2.3.0 → 2.3.2

package/agents/makdoong2-planner.md

@@ -245,7 +245,9 @@ bash <SCRIPTS_DIR>/state.sh set {ISSUE_KEY} '.stages."1_planning".substages."sco
 - 범주 하향(major→minor) — escalation만 허용.
 - 다음 phase 작업(dev/test) 선행.
 - **outer-world 에이전트(Sisyphus / Explore / Librarian / oh-my-openagent 계열 카테고리 등) 위임 금지.** 본 에이전트에는 `Task` 툴이 프론트매터에서 제거되어 있어 물리적으로 스폰 불가. 조사가 필요하면 반드시 `skill_mcp` 로 `jira-research` / `confluence-research` / `bitbucket-research` / `github-oss-research` 스킬만 사용. 이는 planning phase가 makdoong2 서브에이전트 체계 내에서 봉인되어야 한다는 아키텍처 원칙이다.
-- **bash를 통한 파일 쓰기 리디렉션 일체 금지 (READ-ONLY 원칙).** 예외: `<SCRIPTS_DIR>/state.sh set ...` 을 통한 state.json 마커 기록만 허용.
+- **bash를 통한 파일 쓰기 리디렉션 일체 금지 (READ-ONLY 원칙).** 예외 2가지:
+  - `<SCRIPTS_DIR>/state.sh set ...` 을 통한 state.json 마커 기록.
+  - **planning 산출물(`.makdoong2-team/<이슈키>/` 아래 `*.md`·`*.json` — `requirements-draft.md` 등)은 `write` 툴로 직접 생성·갱신한다.** 이것은 READ-ONLY 위반이 아니라 stage spec(02-requirements.md §2-0b)이 부과한 **의무**이며, 훅도 이 경로의 `write` 를 명시적으로 허용한다. 단 같은 경로라도 bash 리디렉션·`apply_patch` 는 차단되므로 반드시 `write` 툴을 쓴다.
   - **금지 패턴**: `echo >`, `cat > file`, `cat <<EOF > file`, `tee file`, `sed -i`, `awk ... > file`, `printf > file`, `> file`, `>> file`, `python -c "... open(..., 'w') ..."`, `node -e "... fs.writeFileSync(...) ..."`
   - **위반 예시**:
     ```bash
@@ -264,5 +266,7 @@ bash <SCRIPTS_DIR>/state.sh set {ISSUE_KEY} '.stages."1_planning".substages."sco
     # ✅ 허용: state.json 마커 기록 (state.sh 경유)
     bash <SCRIPTS_DIR>/state.sh set PROJ-123 '.stages."1_planning".substages."scope".done' 'true'
     ```
-  - **위반 결과**: verifier가 `git status`로 untracked 파일 감지 → REJECTED 판정 → 워크플로우 중단
-  - **올바른 절차**: 초안 파일 생성이 필요하면 spec을 team-leader에게 반환하여 dev 단계로 위임한다. Planning 단계는 "무엇을 만들지"만 결정하고, "실제로 만드는 것"은 implementation 단계의 책임이다.
+  - **위반 결과**: 훅이 bash 쓰기·`apply_patch` 를 차단하고, 우회에 성공하더라도 verifier가 `git status`로 untracked 파일 감지 → REJECTED 판정 → 워크플로우 중단
+  - **올바른 절차**:
+    - **planning 산출물(요구사항 초안 등 `.makdoong2-team/<이슈키>/*.md|json`)은 본인이 `write` 툴로 직접 생성한다.** team-leader 반환·dev 위임 대상이 아니다 — 그 시점 파이프라인에는 초안을 대신 만들 역할이 없어 워크플로가 정지한다 (issue #8).
+    - **소스 코드** 파일 생성·변경이 필요하면 spec을 team-leader에게 반환하여 dev 단계로 위임한다. Planning 단계는 "무엇을 만들지"만 결정하고, "실제로 만드는 것"은 implementation 단계의 책임이다.

package/agents/makdoong2-team-leader.md

@@ -98,6 +98,29 @@ permission:
 
 `MAX_ATTEMPTS` 는 dispatch_stage **호출 1회 내부**의 예산이므로 재호출하면 리셋된다. `hang_history` 누적 상한은 그 리셋을 무력화하기 위한 **호출 간(cross-call) 차단막**이며, 부장님이 우회하면 무한 루프가 된다.
 
+## 서브에이전트 능력을 frontmatter `tools:` 목록으로 판정하지 말 것 (hardrule)
+
+에이전트 정의 파일의 frontmatter `tools:` 는 **whitelist 가 아니다** — 목록에 없는 툴도 permission 설정이 허용하면 실행된다. 실제로 planner frontmatter 에 `Write` 가 없다는 이유로 "planner 는 구조적으로 파일 생성이 불가능하다" 고 단정하고 워크플로를 중단시킨 오진단이 있었다 — 로그상 planner 는 `write` 를 정상 실행해 왔고 차단 이력이 0건이었다 (GitHub issue #8). 서브에이전트가 파일을 못 만들었다면 원인은 **훅 차단 메시지·permission 프롬프트 대기(PERMISSION_STALL)·프롬프트 지시** 중에 있다. frontmatter 를 근거로 사용자에게 에이전트 정의 수정을 요구하지 말고, 실패한 세션의 실제 차단 로그를 근거로 판단하라.
+
+## substage 완료 판정은 `stage_done` 으로 한다 — 출력 문구로 판단하지 말 것 (hardrule)
+
+`dispatch_stage` 반환 JSON 의 `completion` / `stage_done` 이 완료 판정의 유일한 근거다. `output` 은 서브에이전트가 쓴 자연어이고, 자기 작업을 실제보다 후하게 서술한다.
+
+| `completion` | `stage_done` | `ok` | 뜻 | 올바른 조치 |
+|---|---|---|---|---|
+| `done` | `true` | `true` | substage 완료 | `dispatch_verifier` 로 진행 |
+| `paused` | `false` | `true` | 서브에이전트가 `interview_required=true` 를 기록하고 **의도적으로** 중단 | 사용자 인터뷰 수행 후 답변을 `context` 에 실어 재dispatch |
+| `incomplete` | `false` | `false` | 최종 텍스트는 나왔지만 **마커가 하나도 없음** | 아래 규약 |
+| `unknown` | `null` | `true` | `.done` 마커를 읽지 못함 | `state.sh status <이슈키>` 로 상태 먼저 확인 |
+
+**`completion: "incomplete"` 규약**:
+
+1. **사용자에게 "완료" 로 보고하지 않는다.** 소요 시간(`elapsed_ms`)과 `output` 의 미완료 사유를 그대로 전달한다. 실제로 27분을 소모하고 마커가 0개인 dispatch 를 "조회 및 템플릿 검증 완료 / 조사 완료" 로 보고한 사고가 있었다 (GitHub issue #9).
+2. `next_action` 을 그대로 따른다 (하드룰 4). 해결 가능한 사유면 `context` 에 지시를 실어 재dispatch 하고, 사용자 개입이 필요하면 보고 후 대기한다.
+3. 이 경우는 `hang_history` 에 `reason: "no_done_marker"` 로 자동 기록된다. 반복하면 `stall_escalate_threshold` 에서 재dispatch 가 차단되므로, 같은 조건으로 무한히 재호출하지 않는다.
+
+`ok: true` 만 보고 넘어가지 말 것 — `paused` 와 `unknown` 도 `ok: true` 이며, 둘 다 substage 는 끝나지 않았다.
+
 ## verdict 는 셋이다 — REJECTED 와 ERROR 를 절대 섞지 말 것 (hardrule)
 
 `dispatch_verifier` 의 `verdict` 는 `VERIFIED` / `REJECTED` / `ERROR` 세 값이다.

package/bin/cli.js

@@ -20,7 +20,7 @@ import { fileURLToPath } from "node:url";
 import { dirname, join, resolve } from "node:path";
 import { execFileSync } from "node:child_process";
 import { buildPoliciesFromConfig, DEFAULT_ALLOWED_PRIMARIES, } from "../scripts/model-policy.mjs";
-import { install, uninstall, resolveConfigDir, parseJsonc, readCachedVersion, opencodeCacheRoot, } from "../scripts/install-lib.mjs";
+import { install, uninstall, resolveConfigDir, parseJsonc, readCachedVersion, opencodeCacheRoot, computeExternalDirPaths, } from "../scripts/install-lib.mjs";
 const HERE = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(HERE, "..");
 const PKG = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8"));
@@ -135,7 +135,14 @@ function doDoctor(flags) {
         check(existsSync(join(PKG_ROOT, d)), `${d}/ in package`, `${d}/ missing in package (reinstall: npm install -g makdoong2-team)`);
     }
     const ocPath = join(DEST, "opencode.json");
-    let pluginOk = false, toolsOk = false, ocParseOk = false, ocParseErr = "";
+    // 설치가 심도록 설계된 external_directory 시드. 에이전트 프롬프트가 서브에이전트
+    // 세션에 워크스페이스 외부 경로(<pkgRoot>/stages/*.md 등) 읽기를 지시하므로,
+    // 이 allow 가 없으면 서브에이전트가 응답 불가한 권한 프롬프트에 걸려
+    // PERMISSION_STALL 로 중단된다 (issue #8). 파일 배포만 성공하고 opencode.json
+    // 패치가 남지 않은 부분 설치를 doctor 가 잡아야 한다.
+    const requiredExtDirPaths = computeExternalDirPaths(PKG_ROOT, DEST);
+    let pluginOk = false, toolsOk = false, extDirOk = false, ocParseOk = false, ocParseErr = "";
+    let extDirMissing = requiredExtDirPaths;
     if (existsSync(ocPath)) {
         try {
             const oc = parseJsonc(readFileSync(ocPath, "utf8"));
@@ -155,14 +162,20 @@ function doDoctor(flags) {
             });
             const ocTools = oc.tools;
             toolsOk = !!ocTools && TOOLS.every((t) => ocTools[t] === true);
+            const extDir = oc.permission?.external_directory;
+            extDirMissing = requiredExtDirPaths.filter((p) => !extDir || typeof extDir !== "object" || extDir[p] !== "allow");
+            extDirOk = extDirMissing.length === 0;
         }
         catch (e) {
             ocParseErr = e instanceof Error ? e.message : String(e);
         }
     }
     check(!existsSync(ocPath) || ocParseOk, "opencode.json parses (JSONC tolerated)", `opencode.json is unparseable — install silently skips patching it: ${ocParseErr}`);
-    check(pluginOk, "opencode.json registers the plugin", "opencode.json missing the plugin entry");
-    check(toolsOk, "opencode.json enables custom tools", "opencode.json missing custom tools");
+    check(pluginOk, "opencode.json registers the plugin", "opencode.json missing the plugin entry (run: npx makdoong2-team install)");
+    check(toolsOk, "opencode.json enables custom tools", "opencode.json missing custom tools (run: npx makdoong2-team install)");
+    check(extDirOk, "opencode.json allows external_directory (pkgRoot + configDir)", `opencode.json missing permission.external_directory allow(s): ${extDirMissing.join(", ")} ` +
+        `— sub-agents will hit unanswerable permission prompts and abort with PERMISSION_STALL ` +
+        `(run: npx makdoong2-team install)`);
     // The plugin opencode actually loads lives in the `<name>@latest` cache dir,
     // not in the globally installed npm module. When those drift the user runs
     // old code while `npm ls -g` reports the new version — invisible without

package/bin/cli.ts

@@ -33,6 +33,7 @@ import {
   parseJsonc,
   readCachedVersion,
   opencodeCacheRoot,
+  computeExternalDirPaths,
 } from "../scripts/install-lib.mts";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -150,7 +151,14 @@ function doDoctor(flags: Flags): never {
    }
 
     const ocPath = join(DEST, "opencode.json");
-    let pluginOk = false, toolsOk = false, ocParseOk = false, ocParseErr = "";
+    // 설치가 심도록 설계된 external_directory 시드. 에이전트 프롬프트가 서브에이전트
+    // 세션에 워크스페이스 외부 경로(<pkgRoot>/stages/*.md 등) 읽기를 지시하므로,
+    // 이 allow 가 없으면 서브에이전트가 응답 불가한 권한 프롬프트에 걸려
+    // PERMISSION_STALL 로 중단된다 (issue #8). 파일 배포만 성공하고 opencode.json
+    // 패치가 남지 않은 부분 설치를 doctor 가 잡아야 한다.
+    const requiredExtDirPaths = computeExternalDirPaths(PKG_ROOT, DEST);
+    let pluginOk = false, toolsOk = false, extDirOk = false, ocParseOk = false, ocParseErr = "";
+    let extDirMissing: string[] = requiredExtDirPaths;
     if (existsSync(ocPath)) {
       try {
         const oc = parseJsonc(readFileSync(ocPath, "utf8"));
@@ -168,12 +176,23 @@ function doDoctor(flags: Flags): never {
         });
         const ocTools = oc.tools;
         toolsOk = !!ocTools && TOOLS.every((t) => ocTools[t] === true);
+        const extDir = oc.permission?.external_directory;
+        extDirMissing = requiredExtDirPaths.filter(
+          (p: string) => !extDir || typeof extDir !== "object" || extDir[p] !== "allow",
+        );
+        extDirOk = extDirMissing.length === 0;
       } catch (e) { ocParseErr = e instanceof Error ? e.message : String(e); }
     }
    check(!existsSync(ocPath) || ocParseOk, "opencode.json parses (JSONC tolerated)",
          `opencode.json is unparseable — install silently skips patching it: ${ocParseErr}`);
-   check(pluginOk, "opencode.json registers the plugin", "opencode.json missing the plugin entry");
-   check(toolsOk, "opencode.json enables custom tools", "opencode.json missing custom tools");
+   check(pluginOk, "opencode.json registers the plugin",
+         "opencode.json missing the plugin entry (run: npx makdoong2-team install)");
+   check(toolsOk, "opencode.json enables custom tools",
+         "opencode.json missing custom tools (run: npx makdoong2-team install)");
+   check(extDirOk, "opencode.json allows external_directory (pkgRoot + configDir)",
+         `opencode.json missing permission.external_directory allow(s): ${extDirMissing.join(", ")} ` +
+         `— sub-agents will hit unanswerable permission prompts and abort with PERMISSION_STALL ` +
+         `(run: npx makdoong2-team install)`);
 
    // The plugin opencode actually loads lives in the `<name>@latest` cache dir,
    // not in the globally installed npm module. When those drift the user runs

package/dist/opencode-plugin.js

@@ -26,8 +26,9 @@ import { classifyVerifierOutcome, nextVerifierErrorStreak, verifierErrorStreakEx
 import { nextModel, applyConfigOverrides, POLICIES } from "./model-fallback-policy.js";
 import { agentForStage, STAGE_SPEC_FILES } from "./agent-stage-config.js";
 import { shouldEscalateStall } from "./stall-escalation.js";
+import { classifyStageCompletion, INCOMPLETE_HANG_REASON } from "./stage-completion.js";
 import { buildStateWriteBlockMessage, classifyStateJsonAccess, looksLikeRedirection, splitUnquotedSegments, WRITE_INDICATORS_UNQUOTED, STATE_SH_CALL_RE, stripQuotedSpans, } from "./state-access-guard.js";
-import { RESEARCH_SOURCES, DEFAULT_RESEARCH_TIMEOUT_MINUTES, buildResearchPrompt, mergeResearchFindings, normalizeQueries, parseResearchOutput, resolveParallelism, summarizeOutcomes, } from "./research-fanout.js";
+import { RESEARCH_SOURCES, DEFAULT_RESEARCH_TIMEOUT_MINUTES, buildResearchPrompt, classifyFanoutOutcome, mergeResearchFindings, normalizeQueries, parseResearchOutput, resolveParallelism, summarizeOutcomes, } from "./research-fanout.js";
 import { TmuxMonitor, readTmuxConfig, orphanCleanupGuard } from "./tmux-monitor.js";
 import { resolvePaths, loadConfig, loadOpencodeExternalDirAllows, readLoggingConfig, DEFAULT_STALL_ESCALATE_THRESHOLD, } from "./config.js";
 import { scanSkillMcpRegistry, extractMcpName, looksLikeMcpNotFound, looksLikeMcpConnectionFailed, } from "./skill-mcp-registry.js";
@@ -1008,9 +1009,23 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
             await spawnPaneForSession(sid);
         },
         "chat.params": async (input) => {
-            if (input.sessionID && input.agent) {
-                sessionAgent.set(input.sessionID, input.agent);
+            if (!input.sessionID || !input.agent)
+                return;
+            // 정체성은 downgrade 하지 않는다 (2차 방어).
+            // sessionAgent 는 sealed 서브에이전트 판정의 입력이므로, 한 번 sealed 로
+            // 확정된 세션이 makdoong2 소속이 아닌 이름으로 덮어써지면 그 세션의
+            // outer-world 차단·산출물 경로 제한이 조용히 풀린다. agent 를 빠뜨린
+            // 프롬프트 하나로 그렇게 되어선 안 된다 — 실제로 NUDGE 가 그랬다 (issue #9).
+            // 호출부(1차 방어)는 전부 agent 를 싣지만, 새 호출부가 또 빠뜨려도
+            // 보안 속성은 유지되어야 한다.
+            const known = sessionAgent.get(input.sessionID);
+            if (known && SEALED_SUBAGENTS.has(known) && !SEALED_SUBAGENTS.has(input.agent)) {
+                logger.warn(`[makdoong2-team hook] chat.params agent downgrade ignored: session=${input.sessionID} ` +
+                    `known="${known}" incoming="${input.agent}" — sealed 정체성을 유지한다. ` +
+                    `이 프롬프트 호출부가 agent 를 싣지 않았을 가능성이 높다.`);
+                return;
             }
+            sessionAgent.set(input.sessionID, input.agent);
         },
         // ─────────────────────────────────────────────────────────────
         // PreToolUse — block destructive bash, gate `git push`,
@@ -1163,9 +1178,12 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                             `${filePath ? `"${filePath}" 에 ` : ""}쓸 수 없다.\n` +
                             (allowed === null
                                 ? `이 에이전트는 파일을 쓰지 않는다 — 조사 결과는 최종 응답 텍스트로 반환하라.\n`
-                                : `허용된 산출물은 .makdoong2-team/<이슈키>/ 아래의 지정된 파일 하나뿐이다 ` +
-                                    `(패턴: ${allowed.source}).\n`) +
-                            `코드 변경이 필요하면 그 사실을 산출물/응답에 적고 engineer 단계로 넘겨라.`);
+                                : `허용된 산출물은 .makdoong2-team/<이슈키>/ 아래의 지정된 파일뿐이다 ` +
+                                    `(패턴: ${allowed.source}).\n` +
+                                    `그 경로에는 지금 즉시 'write' 툴(filePath 인자)로 쓸 수 있다 — ` +
+                                    `bash 리디렉션·apply_patch 우회가 차단된 것이지 산출물 쓰기 자체가 금지된 것이 아니다. ` +
+                                    `산출물이 필요하면 포기하지 말고 write 툴로 재시도하라.\n`) +
+                            `소스 코드 변경이 필요하면 그 사실을 산출물/응답에 적고 engineer 단계로 넘겨라.`);
                     }
                 }
                 // ── Leader hardrule 1: 직접 파일 편집·생성 금지 (write/edit/patch/multiedit) ──
@@ -1805,18 +1823,26 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                             logger.debug(`[dispatch_stage] engineer session ready — ` +
                                 `session_id=${subSessionID} stage=${args.target_stage} attempt=${attempt}\n` +
                                 `  monitor: opencode attach http://127.0.0.1:44707 --session ${subSessionID}`);
+                            // 종전 문구는 2번에서 state.sh 마커 기록을 요구하면서 마지막 줄에서
+                            // "새 tool 호출 추가 금지" 라고 못박아 서로 모순됐다. 실제로 planner 가
+                            // Jira 검증 6/6 을 끝내고도 "마커 기록 전 시한 도달" 이라며 마커를
+                            // 하나도 남기지 않고 종료해 27분이 통째로 버려졌다 (GitHub issue #9).
+                            // 마커 기록은 금지의 예외임을 문구 안에서 명시한다.
                             const nudgeText = [
-                                "⚠ 작업 시한 80% 도달 — 현재 작업을 마무리하고 즉시 세션을 종료하시오.",
+                                "⚠ 작업 시한 80% 도달 — 지금부터는 마커 기록과 요약만 하고 즉시 세션을 종료하시오.",
                                 "",
-                                "허용된 남은 작업:",
-                                "1. 진행 중인 단일 tool call 완료",
-                                `2. bash ${SCRIPTS_DIR}/state.sh 로 .done 마커 확인 후 완료 시 true 설정`,
+                                "순서대로 수행:",
+                                "1. 진행 중인 단일 tool call 만 마무리한다. 새 조사·탐색·구현은 시작하지 않는다.",
+                                `2. **이미 끝낸 작업의 state.json 마커를 지금 전부 기록한다.** bash ${SCRIPTS_DIR}/state.sh set 호출은`,
+                                "   아래 금지 규칙의 예외이며 필요한 횟수만큼 호출한다. 완료한 substage 는 .done=true 까지 기록한다.",
+                                "   마커 없이 종료하면 그 작업은 수행되지 않은 것으로 판정되어 substage 전체가 처음부터 재실행된다",
+                                "   — 지금까지의 결과가 통째로 버려진다. 기록할 시간이 없다는 판단은 하지 말 것.",
                                 "3. 3줄 이상 한국어 요약 텍스트 출력:",
                                 "   - 처리한 substage 결과 (완료/차단/조기종료)",
                                 "   - 변경한 state.json 마커 목록",
                                 "   - 다음 단계 안내",
                                 "",
-                                "금지: 새 tool 호출 추가. 요약 텍스트 출력 직후 즉시 종료.",
+                                "금지: 새로운 조사·구현 tool 호출. 허용: state.sh 마커 기록. 요약 출력 직후 즉시 종료.",
                             ].join("\n");
                             const engineerNudge = async (sid, elapsedMs) => {
                                 logger.debug(`[dispatch_stage] NUDGE sid=${sid} elapsed=${Math.round(elapsedMs / 1000)}s`);
@@ -1824,6 +1850,13 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                                     .promptAsync({
                                     path: { id: sid },
                                     body: {
+                                        // agent 를 빼면 opencode 가 기본 에이전트(`build`)로 이 turn 을
+                                        // 돌리고, `chat.params` 가 sessionAgent[sid] 를 그 값으로 덮어쓴다.
+                                        // 그 순간부터 이 세션은 sealed sub-agent 로 인식되지 않아
+                                        // outer-world 위임 차단과 산출물 경로 제한이 전부 풀린다.
+                                        // 실측 로그에서 NUDGE 직후 bash 호출이 agent="build" 로 기록됐다
+                                        // (GitHub issue #9 부수 관찰). 여기서만 누락돼 있었다.
+                                        agent: spec.id,
                                         parts: [{ type: "text", text: nudgeText }],
                                         model: { providerID: activeProviderID, modelID: activeModelID },
                                     },
@@ -2025,12 +2058,60 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                                 }
                             }
                             promptPromise.catch(() => { });
-                            if (success) {
+                            // 완료 판정은 sub-agent 의 문장이 아니라 substage 마커로 한다 (issue #9).
+                            // pollSubSession 의 kind="text" 는 "최종 turn 이 나왔다" 일 뿐이고,
+                            // 예산을 다 쓰고 "조기종료 — 마커 기록 없음" 이라고 말한 세션도 같은 kind 를
+                            // 낸다. 그 둘을 구분하는 유일한 값이 게이트·verifier 가 읽는 그 .done 이다.
+                            // cwd 는 effectiveWorktree — 이 substage 의 다른 state.json 접근과
+                            // 같은 파일을 봐야 한다 (args.worktree 를 쓰면 교정 발동 시 갈린다).
+                            const readMarker = async (field) => {
+                                const r = await $ `bash ${SCRIPTS_DIR}/state.sh get ${args.issue} ${`${stageJqPath(args.target_stage)}.${field}`}`
+                                    .cwd(effectiveWorktree).quiet().nothrow();
+                                return r.exitCode === 0 ? (r.stdout?.toString().trim() ?? null) : null;
+                            };
+                            const completion = classifyStageCompletion({
+                                outcomeKind: finalOutcome.kind,
+                                success,
+                                doneValue: success ? await readMarker("done") : null,
+                                interviewRequiredValue: success ? await readMarker("interview_required") : null,
+                            });
+                            if (completion.resetHangHistory) {
+                                // 리셋 조건은 "dispatch 정상 반환" 이 아니라 "substage 실제 완료(done=true)"
+                                // 다. 종전에는 세션이 텍스트만 뱉고 done=false 로 끝나도 리셋됐고,
+                                // 재-dispatch 를 반복하는 동안 이력이 매번 비워져
+                                // stall_escalate_threshold 가 사실상 도달 불가였다 (issue #8).
                                 const resetPath = `${stageJqPath(args.target_stage)}.hang_history`;
                                 const resetR = await $ `bash ${SCRIPTS_DIR}/state.sh set ${args.issue} ${resetPath} ${"[]"}`
-                                    .cwd(args.worktree).quiet().nothrow();
+                                    .cwd(effectiveWorktree).quiet().nothrow();
                                 logger.debug(`[hang_history] reset issue=${args.issue} stage=${args.target_stage} ` +
-                                    `exit=${resetR.exitCode} — substage succeeded`);
+                                    `exit=${resetR.exitCode} — substage done=true`);
+                            }
+                            else if (success) {
+                                logger.debug(`[hang_history] reset skipped issue=${args.issue} stage=${args.target_stage} ` +
+                                    `completion=${completion.completion} — dispatch 는 정상 반환했지만 substage 미완료`);
+                            }
+                            if (completion.recordHang) {
+                                // hang_history 는 dispatch_stage 호출 사이를 넘어 살아남는 유일한
+                                // 카운터다. 여기에 남기지 않으면 이 실패 모드는 cross-call 상한
+                                // (stall_escalate_threshold) 에 영영 도달하지 못하고, 매 호출이
+                                // 타임아웃 전체를 태우며 무한히 재실행된다 (issue #9).
+                                const incompleteEntry = JSON.stringify({
+                                    attempt,
+                                    at: new Date().toISOString(),
+                                    reason: INCOMPLETE_HANG_REASON,
+                                    elapsed_ms: finalOutcome.elapsedMs,
+                                    polls: finalOutcome.polls,
+                                    session_id: subSessionID,
+                                    model: activeModelFull,
+                                    fallback_depth: activeFallbackDepth,
+                                    final: true,
+                                });
+                                const incompleteJqPath = stageJqPath(args.target_stage) + ".hang_history";
+                                const incompleteR = await $ `bash ${SCRIPTS_DIR}/state.sh append ${args.issue} ${incompleteJqPath} ${incompleteEntry}`
+                                    .cwd(effectiveWorktree).quiet().nothrow();
+                                logger.warn(`[dispatch_stage] STAGE_INCOMPLETE issue=${args.issue} stage=${args.target_stage} ` +
+                                    `session=${subSessionID} outcome_kind=${finalOutcome.kind} elapsed_ms=${finalOutcome.elapsedMs} ` +
+                                    `— 최종 텍스트는 나왔으나 .done=false. hang_history append exit=${incompleteR.exitCode}`);
                             }
                             const retryDisallowed = finalOutcome.kind === "timeout" &&
                                 finalOutcome.transientFailures === 0;
@@ -2040,7 +2121,7 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                                     `동일 dispatch_stage 를 재호출하지 말고 사용자에게 상황을 보고한 뒤 지시를 기다리거나 get_fallback_model 로 다른 모델을 요청하세요.`
                                 : undefined;
                             finalResultJson = JSON.stringify({
-                                ok: success,
+                                ok: completion.ok,
                                 stage: args.target_stage,
                                 agent: spec.id,
                                 model: activeModelFull,
@@ -2050,6 +2131,9 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                                 fallback_depth: activeFallbackDepth,
                                 output: finalLegacy.text.slice(0, 8000),
                                 outcome_kind: finalOutcome.kind,
+                                // 완료 여부는 이 두 필드로 읽는다. output 문구를 해석하지 말 것 (issue #9).
+                                stage_done: completion.stageDone,
+                                completion: completion.completion,
                                 polls: finalOutcome.polls,
                                 elapsed_ms: finalOutcome.elapsedMs,
                                 transient_failures: finalOutcome.kind === "timeout"
@@ -2057,9 +2141,10 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                                     : undefined,
                                 retry_disallowed: retryDisallowed || undefined,
                                 retry_disallowed_reason: retryDisallowedReason,
-                                reason: success
+                                next_action: completion.nextAction,
+                                reason: completion.ok
                                     ? overriddenReason
-                                    : finalLegacy.text,
+                                    : (completion.incompleteReason ?? finalLegacy.text),
                             });
                         }
                         finally {
@@ -2633,27 +2718,35 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                         }
                     }
                     const okCount = artifact.counts.ok;
+                    const failedOutcomes = outcomes.filter((o) => o.status === "failed");
+                    const fanout = classifyFanoutOutcome(artifact.counts, artifactWritten ? relPath : null, failedOutcomes.map((o) => o.label));
                     logger.debug(`[dispatch_research] fan-out done issue=${args.issue} ok=${okCount}/${outcomes.length} ` +
-                        `findings=${artifact.counts.findings_total} elapsed_ms=${Date.now() - startedAll}`);
+                        `findings=${artifact.counts.findings_total} status=${fanout.status} ` +
+                        `elapsed_ms=${Date.now() - startedAll}`);
+                    if (fanout.partial) {
+                        // debug 가 아니라 warn — 기본 로깅 레벨에서도 보여야 하는 결손이다.
+                        logger.warn(`[dispatch_research] PARTIAL issue=${args.issue} ok=${okCount}/${artifact.counts.requested} ` +
+                            `failed=${failedOutcomes.map((o) => `${o.source}:${o.error ?? "unknown"}`).join(" | ")}`);
+                    }
                     return JSON.stringify({
                         // 부분 성공도 ok=true. 한 소스가 죽었다고 나머지 조사 결과를 버리면
-                        // fan-out 의 실패 격리가 의미를 잃는다. 호출자는 failed 배열을 본다.
-                        ok: okCount > 0,
+                        // fan-out 의 실패 격리가 의미를 잃는다. 결손은 status/partial 로 알린다.
+                        ok: fanout.ok,
+                        status: fanout.status,
+                        partial: fanout.partial,
                         issue: args.issue,
                         artifact_path: artifactWritten ? relPath : null,
                         artifact_error: artifactError,
                         elapsed_ms: Date.now() - startedAll,
                         counts: artifact.counts,
                         summary: summarizeOutcomes(outcomes),
-                        failed: outcomes.filter((o) => o.status === "failed").map((o) => ({
+                        failed: failedOutcomes.map((o) => ({
                             source: o.source,
                             error: o.error,
                         })),
                         rejected,
                         deferred,
-                        next_action: okCount > 0
-                            ? `조사 결과를 읽고 요구사항 체크리스트에 반영하라: ${relPath}`
-                            : "모든 소스 조사가 실패했다. failed 사유를 사용자에게 보고하라.",
+                        next_action: fanout.next_action,
                     });
                 },
             }),

package/dist/poll-sub-session.d.ts

@@ -83,6 +83,7 @@ export type PollOutcome = {
     stalledMs: number;
     permissionID?: string;
     permissionType?: string;
+    permissionPatterns?: string[];
 } | {
     kind: "session_gone";
     polls: number;

package/dist/poll-sub-session.js

@@ -328,6 +328,7 @@ export async function pollSubSession(client, sessionId, options = {}) {
                         stalledMs,
                         permissionID: p.id,
                         permissionType: p.permission,
+                        permissionPatterns: p.patterns,
                     };
                 }
             }
@@ -355,13 +356,29 @@ export async function pollSubSession(client, sessionId, options = {}) {
                 `— 툴이 실행 중이므로 permission_stall 로 판정하지 않는다`);
         }
         if (hasPendingToolCall && !toolExecuting && stalledMs >= toolCallStallThresholdMs) {
-            err(`[pollSubSession] PERMISSION_STALL session=${sessionId} polls=${pollCount} stalledMs=${stalledMs}`);
+            // abort 전에 대기 중인 permission 요청을 1회 조회해 어떤 카테고리·경로가
+            // 대기 중인지 abort 메시지에 남긴다 (issue #8 제안 2). 종전에는 폴러
+            // 로그만으로 대기 대상을 특정할 수 없어 원인 규명에 코드 독해가 필요했다.
+            // best-effort — client.permission 이 없거나(구버전 SDK) 조회가 실패해도
+            // 종전과 동일한 무정보 outcome 으로 진행한다.
+            let stalledPerm;
+            if (client.permission) {
+                const permResult = await client.permission.list().catch(() => null);
+                stalledPerm = (permResult?.data ?? []).find(p => p.sessionID === sessionId);
+            }
+            err(`[pollSubSession] PERMISSION_STALL session=${sessionId} polls=${pollCount} stalledMs=${stalledMs}` +
+                (stalledPerm
+                    ? ` pending permissionID=${stalledPerm.id} type=${stalledPerm.permission} patterns=${JSON.stringify(stalledPerm.patterns)}`
+                    : ` pending permission unknown (permission.list unavailable or empty)`));
             await client.session.abort({ path: { id: sessionId } }).catch(() => undefined);
             return {
                 kind: "permission_stall",
                 polls: pollCount,
                 elapsedMs: now() - startTime,
                 stalledMs,
+                permissionID: stalledPerm?.id,
+                permissionType: stalledPerm?.permission,
+                permissionPatterns: stalledPerm?.patterns,
             };
         }
         // Message stall: sub-agent registered (sessionEverAppeared) and appears
@@ -587,8 +604,12 @@ export function pollOutcomeToLegacy(outcome) {
         case "permission_stall":
             return {
                 text: outcome.permissionType
-                    ? `(permission_stall: sub-agent blocked on ${outcome.permissionType} permission (id=${outcome.permissionID}) — auto-rejected and aborted)`
-                    : `(permission_stall: sub-agent tool call stalled for ${outcome.stalledMs}ms — likely waiting for external_directory permission approval that cannot be answered in subagent context)`,
+                    ? `(permission_stall: sub-agent blocked on ${outcome.permissionType} permission ` +
+                        `(id=${outcome.permissionID}${outcome.permissionPatterns ? `, patterns=${JSON.stringify(outcome.permissionPatterns)}` : ""}) ` +
+                        `— cannot be answered in subagent context; aborted after ${outcome.stalledMs}ms)`
+                    : `(permission_stall: sub-agent tool call stalled for ${outcome.stalledMs}ms — likely waiting for a permission approval ` +
+                        `that cannot be answered in subagent context; pending permission could not be identified (permission.list unavailable or empty). ` +
+                        `점검: opencode.json 의 permission.external_directory 시드 존재 여부 (npx makdoong2-team doctor))`,
                 success: false,
             };
         case "session_gone":

package/dist/research-fanout.d.ts

@@ -131,3 +131,35 @@ export interface ResearchFindingsArtifact {
 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;

package/dist/research-fanout.js

@@ -289,3 +289,53 @@ export function summarizeOutcomes(outcomes) {
         ? `${o.label}: findings ${o.findings.length}건, gaps ${o.gaps.length}건 (${Math.round(o.elapsed_ms / 1000)}s)`
         : `${o.label}: 실패 — ${o.error ?? "unknown"} (${Math.round(o.elapsed_ms / 1000)}s)`);
 }
+/**
+ * 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 function classifyFanoutOutcome(counts, artifactPath, failedSources) {
+    if (counts.ok === 0) {
+        return {
+            status: "failed",
+            ok: false,
+            partial: false,
+            next_action: "모든 소스 조사가 실패했다. failed 사유를 사용자에게 그대로 보고하라. " +
+                "조사 결과를 추측으로 대체하지 말 것.",
+        };
+    }
+    if (counts.failed === 0) {
+        return {
+            status: "ok",
+            ok: true,
+            partial: false,
+            next_action: `조사 결과를 읽고 요구사항 체크리스트에 반영하라: ${artifactPath ?? "(artifact 미기록)"}`,
+        };
+    }
+    return {
+        status: "partial",
+        ok: true,
+        partial: true,
+        next_action: `부분 성공 — ${counts.requested} 개 소스 중 ${counts.failed} 개 실패 (${failedSources.join(", ")}). ` +
+            `성공한 소스의 결과로 진행하되 다음 셋을 반드시 지킨다: ` +
+            `(1) 실패한 소스에서 확인하려던 항목을 산출물의 gaps/미확인 항목에 명시적으로 남긴다. ` +
+            `(2) 실패한 소스를 직접 조사해 메우려 하지 말 것 — 세션 예산을 소진하고 마커를 하나도 남기지 못한 ` +
+            `실패 사례가 있다. 필요하면 focus 를 좁혀 dispatch_research 를 1회만 다시 호출한다. ` +
+            `(3) 실패 소스가 요구사항 확정에 필수면 마커를 먼저 기록한 뒤 사용자에게 보고한다. ` +
+            `조사 완결성과 무관하게 substage 마커 기록은 생략하지 않는다. ` +
+            `조사 결과: ${artifactPath ?? "(artifact 미기록)"}`,
+    };
+}

package/dist/stage-completion.d.ts

@@ -0,0 +1,55 @@
+/**
+ * - `done`       — `.done=true`. The substage finished; hang_history resets.
+ * - `paused`     — the sub-agent stopped on purpose and recorded why
+ *                  (`interview_required=true`). Not a failure: the orchestrator
+ *                  runs the interview and re-dispatches with `context`.
+ * - `incomplete` — a final turn, but `.done=false` and no pause marker. The
+ *                  session spent its budget and left nothing behind.
+ * - `unknown`    — the marker could not be read. Never downgraded to a failure:
+ *                  an unreadable state.json must not turn finished work into a
+ *                  retry loop (same fail-open reasoning as `shouldEscalateStall`).
+ */
+export type StageCompletion = "done" | "paused" | "incomplete" | "unknown";
+/** hang_history `reason` for a text-but-no-marker exit. */
+export declare const INCOMPLETE_HANG_REASON = "no_done_marker";
+export interface StageCompletionInput {
+    /** `pollSubSession` outcome kind of the final turn (`text` / `empty` / …). */
+    outcomeKind: string;
+    /** dispatch_stage's legacy success flag (final text turn, or a done-override). */
+    success: boolean;
+    /**
+     * Raw stdout of `state.sh get <stage>.done`, trimmed — or `null` when the read
+     * failed. `state.sh get` prints the literal `null` on a missing key, so `"null"`
+     * and `null` both mean "not readable as a decision", never "false".
+     */
+    doneValue: string | null;
+    /** Raw stdout of `state.sh get <stage>.interview_required`, trimmed, or `null`. */
+    interviewRequiredValue?: string | null;
+}
+export interface StageCompletionResult {
+    completion: StageCompletion;
+    /** `true` only on a marker we actually read as `true`; `null` when unreadable. */
+    stageDone: boolean | null;
+    /** Should dispatch_stage report `ok:true` to the orchestrator? */
+    ok: boolean;
+    /** Reset the substage's `hang_history` (only a real completion clears it). */
+    resetHangHistory: boolean;
+    /**
+     * Append a `hang_history` entry. hang_history is the ONLY counter that survives
+     * across dispatch_stage calls, so an incomplete exit has to land there or the
+     * cross-call `stall_escalate_threshold` can never arm for this failure mode —
+     * the substage re-dispatches forever, each call burning a full timeout.
+     */
+    recordHang: boolean;
+    /** One-line cause, surfaced as `reason` when `ok` is false. */
+    incompleteReason?: string;
+    /** Literal instruction for team-leader. Hardrule 4 says it follows this verbatim. */
+    nextAction?: string;
+}
+/**
+ * Classify a dispatch_stage outcome by the substage's markers.
+ *
+ * Only a definite `"false"` flips `ok` to false. A read failure (`null`) or a
+ * literal `"null"` leaves `ok` alone and reports `unknown` — see StageCompletion.
+ */
+export declare function classifyStageCompletion(input: StageCompletionInput): StageCompletionResult;

package/dist/stage-completion.js

@@ -0,0 +1,91 @@
+// stage-completion.ts — did the dispatched substage actually finish?
+//
+// Why a separate module: the opencode plugin loader calls EVERY named export of
+// the entry file as a plugin factory (ARCHITECTURE.md §2), so new helpers must
+// live outside opencode-plugin.ts and be imported. `test/plugin-exports-shape.test.ts`
+// pins the entry file's export set.
+//
+// The problem this solves (GitHub #9): `pollSubSession` returning `kind:"text"`
+// means "the sub-session produced a final assistant turn", NOT "the substage is
+// done". A planner that burned its whole budget on research and exited with the
+// words "조기종료 — 마커 기록 없음" produces exactly the same outcome kind as one
+// that completed every phase. dispatch_stage reported `ok:true` for the former,
+// team-leader read the prose and told the user the stage had progressed, and
+// 27 minutes of wall clock left `state.json` byte-identical.
+//
+// The authoritative completion signal is the substage's own `.done` marker —
+// the same value the gates and the verifier read. Everything here is a pure
+// function of the markers so the classification is unit-testable without
+// spawning sessions.
+/** hang_history `reason` for a text-but-no-marker exit. */
+export const INCOMPLETE_HANG_REASON = "no_done_marker";
+/**
+ * Classify a dispatch_stage outcome by the substage's markers.
+ *
+ * Only a definite `"false"` flips `ok` to false. A read failure (`null`) or a
+ * literal `"null"` leaves `ok` alone and reports `unknown` — see StageCompletion.
+ */
+export function classifyStageCompletion(input) {
+    const done = normalizeMarker(input.doneValue);
+    const interview = normalizeMarker(input.interviewRequiredValue ?? null);
+    if (!input.success) {
+        // The failure paths (session_gone / timeout / empty) already build their own
+        // reason and their own hang_history entries. Nothing to add or reset here.
+        return {
+            completion: done === true ? "done" : "incomplete",
+            stageDone: done,
+            ok: false,
+            resetHangHistory: false,
+            recordHang: false,
+        };
+    }
+    if (done === true) {
+        return { completion: "done", stageDone: true, ok: true, resetHangHistory: true, recordHang: false };
+    }
+    if (interview === true) {
+        return {
+            completion: "paused",
+            stageDone: false,
+            ok: true,
+            resetHangHistory: false,
+            recordHang: false,
+            nextAction: "서브에이전트가 interview_required=true 를 기록하고 의도적으로 중단했다. 재dispatch 전에 " +
+                "사용자 인터뷰를 먼저 수행하고, 답변을 dispatch_stage 의 context 파라미터에 실어 재호출하라.",
+        };
+    }
+    if (done === false) {
+        return {
+            completion: "incomplete",
+            stageDone: false,
+            ok: false,
+            resetHangHistory: false,
+            recordHang: true,
+            incompleteReason: "sub-session 은 최종 텍스트를 남겼지만 substage 의 .done 마커가 false 다 — 작업이 완료되지 않았다. " +
+                "출력 문구가 아니라 이 필드가 완료 판정의 근거다.",
+            nextAction: "이 substage 는 완료되지 않았다. 사용자에게 '완료' 로 보고하지 말 것. " +
+                "output 의 미완료 사유를 읽고 (a) 해결 가능하면 context 에 지시를 실어 dispatch_stage 를 재호출하거나, " +
+                "(b) 사용자 개입이 필요하면 소요 시간과 미완료 사유를 그대로 보고하고 대기하라. " +
+                "hang_history 에 기록되므로 반복하면 stall_escalate_threshold 에서 차단된다.",
+        };
+    }
+    return {
+        completion: "unknown",
+        stageDone: null,
+        ok: true,
+        resetHangHistory: false,
+        recordHang: false,
+        nextAction: "substage 의 .done 마커를 읽지 못했다. 다음 단계로 넘어가기 전에 " +
+            "`bash <SCRIPTS_DIR>/state.sh status <이슈키>` 로 state.json 상태를 먼저 확인하라.",
+    };
+}
+/** `"true"` / `"false"` → boolean. Everything else (`"null"`, `null`, 잡음) → null. */
+function normalizeMarker(raw) {
+    if (raw === null)
+        return null;
+    const v = raw.trim().toLowerCase();
+    if (v === "true")
+        return true;
+    if (v === "false")
+        return false;
+    return null;
+}

package/gates/stage3-scope-verify.sh

@@ -54,8 +54,14 @@ if [ "$SPEC_HASH" != "__MISSING__" ] && [ "$SPEC_HASH" != "null" ] && [ -n "$SPE
     fi
     fail "spec_hash 는 기록됐는데 draft_path 마커도 확정 명세 파일도 없다 — requirements substage 를 재작업하라 (stages/02-requirements.md §2-0, §2-5 9번)"
   fi
+  # "생성된 적 없음" 을 안내에서 빼면 복구 방향을 잘못 잡는다 — 실제로 가장 흔한
+  # 경우인데 종전 메시지는 동기화 누락·삭제만 언급해 리더가 동기화 문제부터
+  # 의심했다 (issue #8).
   [ -f "$ROOT/$DRAFT" ] \
-    || fail "draft_path=${DRAFT} 마커는 있으나 파일이 없다 (기준 경로 ${ROOT}) — worktree 동기화 누락이거나 파일이 삭제됐다"
+    || fail "draft_path=${DRAFT} 마커는 있으나 파일이 없다 (기준 경로 ${ROOT}). 가능한 원인 순서대로:
+  (1) 애초에 생성된 적 없음 — planner 가 마커만 기록하고 파일 생성에 실패한 경우. requirements substage 를 재작업해 write 툴로 초안부터 생성하라 (stages/02-requirements.md §2-0b),
+  (2) worktree 동기화 누락 — 다른 cwd(main repo/worktree)의 같은 상대경로에 파일이 있는지 확인,
+  (3) 파일이 삭제됨 — 삭제 경위 확인 후 requirements 재작업"
   ACTUAL="$(sha256sum "$ROOT/$DRAFT" | cut -d' ' -f1)"
   [ "$ACTUAL" = "$SPEC_HASH" ] \
     || fail "확정 명세 무단 변경 감지 (spec drift) — 동결 후 변경은 사용자 재승인 + spec_hash 재기록 절차만 허용 (stages/02-requirements.md §2-4a)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "makdoong2-team",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "publishConfig": {
     "access": "public"
   },

package/scripts/run-tests.mts

@@ -83,6 +83,7 @@ const STEPS = [
   "node --test test/doctor-exit-code.test.ts",
   "node --test test/example-config-portability.test.ts",
   "node --test test/research-fanout.test.ts",
+  "node --test test/stage-completion.test.ts",
   "node --test test/state-sh-write-atomicity.test.ts",
   "node --test test/gate-locale-and-path.test.ts",
   "node --test test/model-policy-parity.test.ts",

package/stages/01-planning.md

@@ -89,6 +89,8 @@ 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).
+
 초안 구조:
 ```markdown
 # 요구사항 초안 — <이슈키>
@@ -130,6 +132,9 @@ Simple 이슈는 조사 A + C만으로 축소 가능. 외부 라이브러리가
 
 **결과 읽기**: 반환 JSON 의 `artifact_path` (`.makdoong2-team/<이슈키>/research-findings.json`) 를 Read 로 읽는다. `failed` 가 있어도 **부분 성공이 정상**이므로 나머지 결과로 진행하고, 실패 소스가 요구사항 확정에 필수인 경우에만 사유를 사용자에게 보고한다. 전 소스 실패(`ok: false`)면 추측으로 채우지 말고 보고한다.
 
+- **`status: "partial"` 은 그 자체로 정상 종료다.** 실패한 소스를 당신이 직접 조사해 메우려 하지 말 것 — `skill_mcp` 순차 호출로 결손을 메우려다 세션 예산을 전부 소진하고 **마커를 하나도 남기지 못한 채** 종료한 사고가 이틀 연속 재현됐다 (GitHub issue #9, 각 27분·17분 소모). 결손을 더 좁히고 싶으면 focus 를 좁혀 `dispatch_research` 를 **1회만** 다시 호출한다.
+- **조사 완결성을 이유로 마커 기록을 미루지 않는다 (hardrule).** 조사가 부분적이면 `gaps` 에 미확인 항목을 남기고 그 상태 그대로 산출물과 substage 마커를 기록한 뒤 종료한다. 마커가 없는 종료는 상위에서 `completion: "incomplete"` 로 분류되어 substage 전체가 재실행된다 — 부분 결과까지 함께 버려진다.
+
 ### 2-4. 요구사항 체크리스트 확인
 
 ```

package/stages/02-requirements.md

@@ -62,6 +62,8 @@ 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).
+
 초안 초기 구조:
 ```markdown
 # 요구사항 초안 — <ISSUE_KEY>
@@ -122,6 +124,8 @@ dispatch_research(
 - 실패한 소스가 **요구사항 확정에 필수**라면 그 사유(인증 실패·권한 부족 등)를 사용자에게 보고한다. 없어도 되는 소스면 `gaps` 로만 남기고 진행한다.
 - `deferred` 가 비어 있지 않으면 병렬 상한에 걸려 빠진 조사가 있다는 뜻이다. 필요하면 2차 호출한다.
 - 모든 소스가 실패하면(`ok: false`) 체크리스트를 추측으로 채우지 말고 사용자에게 보고한다.
+- **`status: "partial"` 은 그 자체로 정상 종료다.** 실패한 소스를 당신이 직접 조사해 메우려 하지 말 것 — `skill_mcp` 순차 호출로 결손을 메우려다 세션 예산을 전부 소진하고 **마커를 하나도 남기지 못한 채** 종료한 사고가 이틀 연속 재현됐다 (GitHub issue #9, 각 27분·17분 소모). 결손을 더 좁히고 싶으면 focus 를 좁혀 `dispatch_research` 를 **1회만** 다시 호출한다.
+- **조사 완결성을 이유로 마커 기록을 미루지 않는다 (hardrule).** 조사가 부분적이면 `gaps` 에 미확인 항목을 남기고 그 상태 그대로 산출물과 substage 마커를 기록한 뒤 종료한다. 마커가 없는 종료는 상위에서 `completion: "incomplete"` 로 분류되어 substage 전체가 재실행된다 — 부분 결과까지 함께 버려진다.
 
 ## 2-2. 요구사항 체크리스트