makdoong2-team 2.3.1 → 2.3.2

package/agents/makdoong2-team-leader.md

@@ -102,6 +102,25 @@ permission:
 
 에이전트 정의 파일의 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/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`,
@@ -1808,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`);
@@ -1827,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 },
                                     },
@@ -2028,30 +2058,60 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                                 }
                             }
                             promptPromise.catch(() => { });
-                            if (success) {
-                                // hang_history 리셋 조건은 "dispatch 정상 반환" 이 아니라 "substage
-                                // 실제 완료(done=true)" 다. 종전에는 세션이 텍스트만 뱉고 done=false
-                                // 로 끝나도 리셋됐고, 재-dispatch 를 반복하는 동안 이력이 매번
-                                // 비워져 stall_escalate_threshold 가 사실상 도달 불가였다 (issue #8).
-                                // cwd 는 effectiveWorktree — 이 substage 의 다른 state.json 접근과
-                                // 같은 파일을 봐야 한다 (args.worktree 를 쓰면 교정 발동 시 갈린다).
-                                const resetDonePath = `${stageJqPath(args.target_stage)}.done`;
-                                const resetDoneR = await $ `bash ${SCRIPTS_DIR}/state.sh get ${args.issue} ${resetDonePath}`
+                            // 완료 판정은 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();
-                                const resetDoneValue = resetDoneR.exitCode === 0
-                                    ? (resetDoneR.stdout?.toString().trim() ?? null)
-                                    : null;
-                                if (resetDoneValue === "true") {
-                                    const resetPath = `${stageJqPath(args.target_stage)}.hang_history`;
-                                    const resetR = await $ `bash ${SCRIPTS_DIR}/state.sh set ${args.issue} ${resetPath} ${"[]"}`
-                                        .cwd(effectiveWorktree).quiet().nothrow();
-                                    logger.debug(`[hang_history] reset issue=${args.issue} stage=${args.target_stage} ` +
-                                        `exit=${resetR.exitCode} — substage done=true`);
-                                }
-                                else {
-                                    logger.debug(`[hang_history] reset skipped issue=${args.issue} stage=${args.target_stage} ` +
-                                        `done=${resetDoneValue} — dispatch 는 정상 반환했지만 substage 미완료`);
-                                }
+                                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(effectiveWorktree).quiet().nothrow();
+                                logger.debug(`[hang_history] reset issue=${args.issue} stage=${args.target_stage} ` +
+                                    `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;
@@ -2061,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,
@@ -2071,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"
@@ -2078,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 {
@@ -2654,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "makdoong2-team",
-  "version": "2.3.1",
+  "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

@@ -132,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

@@ -124,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. 요구사항 체크리스트