makdoong2-team 3.0.0 → 3.0.2

package/agents/makdoong2-team-leader.md

@@ -147,6 +147,8 @@ permission:
 2. **REJECTED 사유는 dispatch_verifier 가 자동으로 state.json 에 기록**한다 (`last_verdict_reason` / `last_verdict_reason_hash` / `same_reason_streak` / `rejected_count`). 부장님이 별도 기록할 필요 없다.
 3. **재-dispatch 시 dispatch_stage 가 자동으로 이전 사유를 프롬프트에 재주입**한다. 부장님은 그냥 `dispatch_stage(issue, target_stage, worktree)` 를 다시 호출하면 된다.
 4. **동일 REJECTED 사유 연속 5회 감지 시 dispatch_verifier 응답에 `same_reason_streak_exceeded: true`** 가 포함된다. 이때는 재시도를 중단하고 사용자에게 상황을 보고한다 (해시 기반 자동 무한루프 방지장치).
+5. **`.done=false` 재설정은 당신의 cwd(main repo)에서 그대로 실행한다.** worktree 로 옮겨가지 않는다 — `dispatch_stage` 가 서브세션 생성 전에 main→worktree 정방향 동기화를 하므로 그 값이 전달된다. worktree 사본을 직접 고치면 그 동기화가 덮어쓴다.
+6. 그런데도 `already_done: true` 가 오면 응답의 `state_copy_mismatch` / `main_repo_done` / `worktree_done` 을 먼저 읽는다. `state_copy_mismatch: true` 는 **자동 동기화가 실패했다**는 뜻이다 — 동기화를 손으로 다시 실행하지 말고 `next_action` 이 지시하는 `state.sh status` 로 확인한 뒤, 해소되지 않으면 사용자에게 에스컬레이션한다.
 
 ### 응답 처리 순서
 

package/agents/makdoong2-verifier.md

@@ -87,6 +87,8 @@ bash <SCRIPTS_DIR>/state.sh get <이슈키> '.stages."2_implementation".substage
 
 기대: 모든 항목(boolean)이 `true`인 JSON 객체. 누락·`false`·문법 오류 = **REJECTED**.
 
+> **유일한 예외**: `2_implementation.dev` 의 `new_tests_added` 는 `1_planning.requirements` 가 테스트 범위 제외를 선언한 경우(`test_scope.new_tests_required == false`) `false` 가 정상이다. 판정 규칙은 §2 의 `2_implementation.dev` 항목에 있다. 이 예외를 모르는 채 "모든 항목 true" 만 적용하면, 승인된 스코프 아웃이 무한 반려로 되돌아온다 (issue #11).
+
 > **⚠️ 스키마 규약:** state.sh 의 모든 jq path 는 `.stages."<PHASE>".substages."<SUBSTAGE>".<field>` 형태를 따른다. 참조: CLAUDE.md "워크플로우 상태 & 위임 규약".
 
 ### 2. 단계 명세 재대조
@@ -119,7 +121,15 @@ bash <SCRIPTS_DIR>/state.sh get <이슈키> '.stages."2_implementation".substage
           git status --porcelain | grep -v '\.makdoong2-team/' | grep -v 'workspace-analysis\.json'
           ```
           출력이 비어 있어야 한다. `.makdoong2-team/` 은 플러그인이 작업 트리 안에 만드는 **자기 상태**이지 analyzer 의 부산물이 아니다. 이것을 위반으로 세면 해당 패턴이 git exclude 에 없는 저장소에서 **항상 REJECTED** 가 나고, 그 시점에 exclude 를 고칠 권한을 가진 역할이 파이프라인에 없어(analyzer 는 산출물 1개만 쓰기 가능 · team-leader 는 하드룰 2 로 차단 · engineer 는 analysis 통과 후 단계) 동일 사유 무한 루프가 된다 (issue #6-②).
-- 2_implementation.dev: `done=true` + sub-agent output에 "테스트 추가" 명시 / 5체크
+- 2_implementation.dev: `done=true` + `self_check` 6항목 + **테스트 동반 원칙은 requirements 의 선언을 따른다** (issue #11)
+    - 판정 근거는 **state.json 마커와 게이트 재실행**이다. sub-agent output 은 보조 근거이며, **output 이 비어 있거나 특정 문구가 없다는 사실만으로 REJECTED 하지 않는다** — 마커가 충족되면 VERIFIED 다. (`dispatch_stage` 는 텍스트 없이 종료한 세션도 `.done=true` 만으로 성공 처리한다. 그 경로를 verifier 가 문구 검색으로 뒤집으면 재작업 루프만 남는다.)
+    - `REQ` = `.stages."1_planning".substages."requirements".test_scope.new_tests_required` 를 읽는다. **마커 부재·`null` 은 `true` 로 간주한다 (fail-closed).**
+      ```bash
+      bash <SCRIPTS_DIR>/state.sh get <이슈키> '.stages."1_planning".substages."requirements".test_scope'
+      ```
+    - `REQ == true` → `self_check.new_tests_added == true` 여야 한다. 추가로 staged 변경(`git diff --cached --name-only`)에 실제 테스트 파일이 있는지 확인한다 — 판단 기준은 `workspace-analysis.json` 의 `test_conventions` 다. 마커는 true 인데 테스트 파일이 하나도 없으면 **REJECTED**.
+    - `REQ == false` → 테스트 범위 제외가 **요구사항 단계에서 이미 승인·동결된 것**이다. `self_check.new_tests_added` 가 `false` 여도 정상이며, 이때 `.stages."2_implementation".substages."dev".new_tests_waived == true` 만 확인한다. **테스트가 없다는 이유로 REJECTED 하지 않는다** — 그 반려가 승인된 스코프 밖의 테스트 코드를 유입시킨 사고의 직접 원인이었다.
+    - 어느 경우든 `gates/stage4-dev-post-verify.sh <이슈키>` 를 재실행해 exit 0 을 확인한다.
 - 2_implementation.test: `.stages."2_implementation".substages."test"` 의 각 필드가 아래 조건을 모두 충족해야 함
         - `.unit` ∈ `{"pass", "fail", "skip"}` — `none`/`null` 은 미기록 → REJECTED
         - `.integration` ∈ `{"pass", "fail", "skip"}` — `none`/`null` 은 미기록 → REJECTED

package/dist/config.d.ts

@@ -92,7 +92,7 @@ export declare function parseJsoncLoose(text: string): unknown;
  * 서브세션의 permission 요청이 auto-reject 됐다.
  * (install-lib 의 computeExternalDirPaths 가 그 값을 쓰는 쪽이다.)
  */
-export declare function loadOpencodeExternalDirAllows(): string[];
+export declare function loadOpencodeExternalDirAllows(diag?: (reason: string) => void): string[];
 /** Resolve the five runtime path roots (JSON paths.* override → default).
  *
  * `skills` default is the opencode config dir (`${XDG_CONFIG_HOME:-$HOME/.config}/opencode/skills`)

package/dist/config.js

@@ -175,20 +175,36 @@ export function parseJsoncLoose(text) {
  * 서브세션의 permission 요청이 auto-reject 됐다.
  * (install-lib 의 computeExternalDirPaths 가 그 값을 쓰는 쪽이다.)
  */
-export function loadOpencodeExternalDirAllows() {
+export function loadOpencodeExternalDirAllows(diag) {
+    // 빈 배열로 끝나는 이유를 호출자가 알 수 있게 한다. 이 모듈은 logger 를 import
+    // 하지 못하므로(logger→config) 콜백으로 돌려준다. 같은 pid 의 두 플러그인 사본이
+    // 서로 다른 개수를 읽은 사례(issue #10: 7개→5개)에서 파일 부재였는지 파싱
+    // 실패였는지 키 부재였는지가 로그에 남지 않았다.
+    const file = join(configDir(), "opencode.json");
+    let raw;
     try {
-        const raw = readFileSync(join(configDir(), "opencode.json"), "utf8");
-        const oc = parseJsoncLoose(raw);
-        const ext = oc?.permission?.external_directory;
-        if (!ext || typeof ext !== "object")
-            return [];
-        return Object.entries(ext)
-            .filter(([, action]) => action === "allow")
-            .map(([pattern]) => pattern);
+        raw = readFileSync(file, "utf8");
     }
-    catch {
-        return []; // 부재 / 파싱 실패 → 설정된 allow 없음
+    catch (err) {
+        diag?.(`read failed: ${file}: ${err.message}`);
+        return []; // 부재 → 설정된 allow 없음
+    }
+    let oc;
+    try {
+        oc = parseJsoncLoose(raw);
+    }
+    catch (err) {
+        diag?.(`parse failed: ${file} (${raw.length} bytes): ${err.message}`);
+        return []; // 파싱 실패 → 설정된 allow 없음
+    }
+    const ext = oc?.permission?.external_directory;
+    if (!ext || typeof ext !== "object") {
+        diag?.(`permission.external_directory absent: ${file}`);
+        return [];
     }
+    return Object.entries(ext)
+        .filter(([, action]) => action === "allow")
+        .map(([pattern]) => pattern);
 }
 /** Resolve the five runtime path roots (JSON paths.* override → default).
  *

package/dist/opencode-plugin.js

@@ -21,6 +21,7 @@ import { homedir } from "node:os";
 import { basename as pathBasename, dirname as pathDirname, join, resolve as pathResolve, sep as pathSep } from "node:path";
 import { tool } from "@opencode-ai/plugin";
 import { appendSessionIndex, findWorktreeRoot, lookupSessionFromIndex } from "./session-index.js";
+import { activeToolCount, clearToolCalls, forgetSession, isToolExecuting as registryIsToolExecuting, normalizePermissionEvent, notifySessionDeleted, pendingPermissionsFor, permissionAsked, permissionReplied, settleToolCalls, sharedSubSessionRegistry, toolFinished, toolStarted, } from "./sub-session-registry.js";
 import { computeVerdictHash } from "./verdict-hash.js";
 import { classifyVerifierOutcome, nextVerifierErrorStreak, verifierErrorStreakExceeded, VERIFIER_ERROR_STREAK_LIMIT, } from "./verifier-verdict.js";
 import { nextModel, applyConfigOverrides, POLICIES } from "./model-fallback-policy.js";
@@ -327,6 +328,15 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
     const cwd = worktree || directory || ".";
     const config = loadConfig();
     applyConfigOverrides(config.agents, config.model_policy);
+    // opencode 는 디렉토리(Instance)마다 이 factory 를 따로 부른다 — 같은 pid 안에
+    // 사본이 여럿이다. 어느 사본이 어떤 로그를 찍는지 구분하려고 진입 시점에 남긴다.
+    // 로그에 worktree 경로의 `[init]` 이 없으면 서브세션 훅이 어디서도 발화하지
+    // 않는 것이고, 그것이 issue #10 의 `tool_call_stall` 처방 1번이다.
+    logger.debug(`[init] plugin instance directory=${directory} worktree=${worktree} pid=${process.pid}`);
+    // 사본을 가로지르는 세션 신호(툴 실행 · 권한 요청 · 이슈키 · worktree · deleted
+    // 대기자)는 프로세스 전역 레지스트리에 둔다. 사본마다 Map 을 들면 worktree 사본의
+    // 훅이 올린 신호를 main 사본의 폴러가 영영 보지 못한다 (issue #10).
+    const registry = sharedSubSessionRegistry();
     // Sub-session monitor — splits a tmux pane next to 부장님 for each spawned
     // 막둥이 when invoked inside tmux with tmux.enabled=true in makdoong2-team.json.
     // No-op otherwise, so non-tmux runs are unaffected.
@@ -422,8 +432,8 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                 const guard = orphanCleanupGuard(p, {
                     nowMs,
                     ownerPid: tmuxMonitor.ownerProcessId,
-                    lastToolExecuteAtMs: sessionLastToolExecuteAt.get(sid),
-                    activeToolCount: sessionActiveToolCount.get(sid),
+                    lastToolExecuteAtMs: registry.lastToolExecuteAt.get(sid),
+                    activeToolCount: activeToolCount(registry, sid),
                     toolAliveWindowMs: TOOL_EXECUTE_ALIVE_WINDOW_MS,
                 });
                 if (guard) {
@@ -448,11 +458,9 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                 if (sessionGone) {
                     logger.debug(`[orphan-scan] pane-kill-only (session gone) sid=${sid} reason=${reason}`);
                     await tmuxMonitor.forceKillBySessionId(sid).catch(() => undefined);
-                    sessionIssue.delete(sid);
+                    forgetSession(registry, sid);
                     pendingDispatch.delete(sid);
                     subSessionIds.delete(sid);
-                    sessionLastToolExecuteAt.delete(sid);
-                    sessionActiveToolCount.delete(sid);
                 }
                 else {
                     logger.debug(`[orphan-scan] cleaning sid=${sid} reason=${reason}`);
@@ -607,29 +615,29 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
     const pluginOwnPatterns = pluginOwnAllowPatterns();
     const configuredAllowPatterns = [
         ...pluginOwnPatterns,
-        ...loadOpencodeExternalDirAllows(),
+        ...loadOpencodeExternalDirAllows((reason) => logger.warn(`[permission] opencode.json external_directory allows unavailable — ${reason} directory=${directory}`)),
     ];
+    // 사본마다 한 번씩 찍힌다 — 같은 pid 에 개수가 다른 두 줄이 있으면 사본이
+    // 둘이라는 뜻이지 설정이 바뀐 것이 아니다 (issue #10 의 7개→5개). directory 를
+    // 같이 남겨 어느 사본이 몇 개를 읽었는지 바로 대응시킨다.
     logger.debug(`[permission] plugin-own allows: ${pluginOwnPatterns.length}개 ` +
-        `(${pluginOwnPatterns.join(", ")})`);
+        `(${pluginOwnPatterns.join(", ")}) directory=${directory}`);
     logger.debug(`[permission] configured external_directory allows: ${configuredAllowPatterns.length}개` +
-        (configuredAllowPatterns.length ? ` (${configuredAllowPatterns.slice(0, 3).join(", ")}…)` : ""));
-    const sessionLastToolExecuteAt = new Map();
-    const sessionActiveToolCount = new Map();
-    /** 활성 툴 카운터를 1 감소시킨다 (0 이면 항목 삭제). */
-    function releaseActiveTool(sid) {
-        const cur = sessionActiveToolCount.get(sid) ?? 0;
-        if (cur <= 1)
-            sessionActiveToolCount.delete(sid);
-        else
-            sessionActiveToolCount.set(sid, cur - 1);
-    }
+        (configuredAllowPatterns.length ? ` (${configuredAllowPatterns.slice(0, 3).join(", ")}…)` : "") +
+        ` directory=${directory}`);
+    // 툴 실행 신호는 레지스트리(`registry.activeToolCalls` / `lastToolExecuteAt`)에
+    // 있다 — before 훅에서 toolStarted, after 훅·툴 part 종결·idle 에서 toolFinished /
+    // clearToolCalls. 종전의 사본-로컬 카운터는 issue #10 으로 제거됐다.
     const TOOL_EXECUTE_ALIVE_WINDOW_MS = 300_000;
     // MESSAGE_STALL 후 client.session.abort() 는 즉시 반환하지만 opencode 서버는 잠시 후
     // session.deleted 이벤트를 fire 한다. 그 사이(관측 최대 112s) sub-agent 가 tool call 을
     // 계속 발사할 수 있어 좀비 실행이 발생한다. abort 직후 session.deleted 를 대기하는
     // 헬퍼로 이 race window 를 닫는다. event 핸들러가 session.deleted 를 수신하면 이 map 의
     // pending waiter 를 resolve 한다.
-    const sessionDeletedWaiters = new Map();
+    // 대기자 목록은 레지스트리에 있다 — session.deleted 이벤트는 세션의 디렉토리
+    // 사본에만 도착하므로(worktree 서브세션이면 worktree 사본), 여기서 기다리는
+    // main 사본과 이벤트를 받는 사본이 같은 목록을 봐야 한다.
+    const sessionDeletedWaiters = registry.sessionDeletedWaiters;
     const waitForSessionDeleted = (sessionId, maxWaitMs) => {
         return new Promise((resolve) => {
             let done = false;
@@ -659,7 +667,9 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
     const SESSION_DELETED_WAIT_MS = 30_000;
     const eventMaxChars = readLoggingConfig(config.logging).eventMaxChars;
     const WRITE_TOOLS = new Set(["write", "edit", "apply_patch"]);
-    const sessionWorktree = new Map();
+    // dispatch 사본이 채우고 worktree 사본의 tool.execute.after 가 읽는다 — 레지스트리.
+    // 디스크의 session-index.ndjson 은 사본이 다른 프로세스에 있을 때의 2차 경로로 남는다.
+    const sessionWorktree = registry.sessionWorktree;
     const extractFilePathFromToolArgs = (args) => {
         if (!args || typeof args !== "object")
             return undefined;
@@ -749,7 +759,41 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
         }
         return { ok: true, relPath };
     };
-    const pollSubSession = (sessionId, timeoutMs = substageTimeoutMs, allowedWorktree, onNudge, messageStallThresholdMs) => pollSubSessionCore(client, sessionId, {
+    // 폴러에 건네는 권한 요청 소스. v1 SDK 클라이언트에는 `permission` 네임스페이스가
+    // 없고, `GET /permission` 은 클라이언트가 묶인 디렉토리 스코프라 worktree
+    // 서브세션의 요청이 보이지 않는다 — 종전에는 이 소스가 항상 undefined 라
+    // 자동 승인·거부 루프가 한 번도 돌지 않았고 stall 메시지는 언제나 "unknown" 이었다
+    // (issue #10). 대신 그 세션의 사본이 `permission.asked` 이벤트로 레지스트리에
+    // 넣은 것을 읽고, 응답은 세션-라우팅 엔드포인트
+    // (`POST /session/{id}/permissions/{permissionID}`) 로 보낸다 — 세션 ID 로
+    // 라우팅되므로 어느 사본에서 불러도 맞는 Instance 에 닿는다.
+    const permissionSourceFor = (sessionId) => ({
+        list: async () => ({
+            data: pendingPermissionsFor(registry, sessionId).map((p) => ({
+                id: p.id,
+                sessionID: p.sessionID,
+                permission: p.permission,
+                patterns: p.patterns,
+            })),
+        }),
+        reply: async (req) => {
+            const c = client;
+            if (typeof c.postSessionIdPermissionsPermissionId !== "function") {
+                throw new Error("permission reply endpoint unavailable on this client");
+            }
+            const res = await c.postSessionIdPermissionsPermissionId({
+                path: { id: sessionId, permissionID: req.path.requestID },
+                body: { response: req.body.reply },
+            });
+            // permission.replied 이벤트는 세션의 사본에 도착하지만, 그 사본이 이벤트를
+            // 놓치더라도 다음 폴이 같은 요청을 다시 처리하지 않도록 즉시 뺀다.
+            permissionReplied(registry, sessionId, req.path.requestID);
+            return res;
+        },
+    });
+    const pollSubSession = (sessionId, timeoutMs = substageTimeoutMs, allowedWorktree, onNudge, messageStallThresholdMs) => 
+    // 클래스 인스턴스를 spread 하면 프로토타입 메서드가 빠지므로 필요한 것만 집는다.
+    pollSubSessionCore({ session: client.session, permission: permissionSourceFor(sessionId) }, sessionId, {
         timeoutMs,
         allowedWorktree,
         configuredAllowPatterns,
@@ -764,16 +808,26 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
         contentStableCompletionMs: 300_000,
         preambleOnlyTextThreshold: 200,
         isRecentlyActive: () => {
-            if ((sessionActiveToolCount.get(sessionId) ?? 0) > 0)
+            if (registryIsToolExecuting(registry, sessionId))
                 return true;
-            const last = sessionLastToolExecuteAt.get(sessionId);
+            const last = registry.lastToolExecuteAt.get(sessionId);
             return typeof last === "number" && Date.now() - last < TOOL_EXECUTE_ALIVE_WINDOW_MS;
         },
-        // "지금 이 순간 툴이 실행 중인가" — before 훅에서 올리고 after 훅에서 내리는
-        // 활성 카운터 그대로다. isRecentlyActive 의 5분 창과 달리 순간값이라 완료
+        // "지금 이 순간 툴이 실행 중인가" — before 훅에서 넣고 after 훅에서 빼는
+        // callID 집합 그대로다. isRecentlyActive 의 5분 창과 달리 순간값이라 완료
         // 판정에 쓸 수 있다. 폴러가 읽는 메시지 스냅샷보다 항상 앞선다 (issue #7:
         // tool.execute.before 발화 110ms 뒤의 폴이 tool part 를 아직 못 봤다).
-        isToolExecuting: () => (sessionActiveToolCount.get(sessionId) ?? 0) > 0,
+        //
+        // 읽기 전에 스냅샷과 대조한다: 툴이 throw 하면 after 훅이 오지 않아 항목이
+        // 남는데, 스냅샷에서 이미 completed/error 인 callID 는 확실히 끝난 것이다.
+        // 스냅샷에 아직 없는 callID 는 그대로 둔다 (110ms 창).
+        isToolExecuting: (snapshot) => {
+            const settled = settleToolCalls(registry, sessionId, snapshot.settledCallIDs);
+            if (settled > 0) {
+                logger.debug(`[pollSubSession] settled ${settled} stale tool call(s) from snapshot sid=${sessionId}`);
+            }
+            return registryIsToolExecuting(registry, sessionId);
+        },
     });
     // ── sessionID → agent 매핑. chat.params hook에서 채우고, tool.execute.before
     //    hook에서 조회한다. 이 매핑을 통해 hook input에 없는 agent 식별을 우회한다.
@@ -796,7 +850,9 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
     // git branch 이름이나 worktree 경로를 추론하지 않고 신뢰할 수 있는 ISSUE를
     // 직접 전달받을 수 있다. 이 설계로 multi-worktree / 비-makdoong2-team 워크트리
     // 오탐 문제가 근본적으로 해결된다.
-    const sessionIssue = new Map();
+    // 레지스트리에 둔다 — dispatch 사본이 넣고, 서브세션의 훅 사본(guard-bash.sh /
+    // sync-state.sh 인자)이 읽는다.
+    const sessionIssue = registry.sessionIssue;
     // ── skill_mcp lazy-load 방어 (mcp_name → skill_name 매핑).
     //    SKILL.md frontmatter 를 스캔해 각 MCP 서버가 어떤 skill 에 embedded 인지
     //    캐시한다. `skill(name="...")` 로 skill 이 로드되기 전에는 opencode 가
@@ -873,11 +929,9 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
             }
         }
         finally {
-            sessionIssue.delete(sid);
+            forgetSession(registry, sid);
             pendingDispatch.delete(sid);
             subSessionIds.delete(sid);
-            sessionLastToolExecuteAt.delete(sid);
-            sessionActiveToolCount.delete(sid);
         }
     };
     // team-leader가 직접 실행 시 물리적으로 차단할 툴 목록.
@@ -992,26 +1046,72 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
         }
     })();
     return {
+        // 이벤트는 **세션의 디렉토리 사본**에만 도착한다 (opencode 의 이벤트 브리지가
+        // `location.directory` 로 필터링한다). worktree 서브세션의 permission.asked ·
+        // message.part.updated · session.deleted 는 worktree 사본이 받고, 그 세션을
+        // 폴링하는 것은 main 사본이다. 그래서 여기서 관측한 것은 전부 레지스트리에
+        // 쓴다 — 사본-로컬 변수에 쓰면 폴러는 영영 보지 못한다 (issue #10).
         event: async ({ event }) => {
-            if (logger.isDebug() && event?.type?.startsWith("session.")) {
+            if (logger.isDebug() && (event?.type?.startsWith("session.") || event?.type?.startsWith("permission."))) {
                 try {
-                    logger.debug(`[event] type=${event.type} properties=${JSON.stringify(event.properties).slice(0, eventMaxChars)}`);
+                    logger.debug(`[event] type=${event.type} directory=${directory} properties=${JSON.stringify(event.properties).slice(0, eventMaxChars)}`);
                 }
                 catch { /* ignore */ }
             }
+            if (event?.type === "permission.asked" || event?.type === "permission.updated") {
+                const req = normalizePermissionEvent(event.type, event.properties);
+                if (req) {
+                    permissionAsked(registry, req);
+                    logger.debug(`[event] permission pending sid=${req.sessionID} requestID=${req.id} ` +
+                        `permission=${req.permission} patterns=${JSON.stringify(req.patterns)}`);
+                }
+                return;
+            }
+            if (event?.type === "permission.replied") {
+                const props = event.properties;
+                const sid = typeof props?.sessionID === "string" ? props.sessionID : undefined;
+                const requestID = typeof props?.requestID === "string" ? props.requestID
+                    : typeof props?.permissionID === "string" ? props.permissionID
+                        : undefined;
+                if (sid && requestID)
+                    permissionReplied(registry, sid, requestID);
+                return;
+            }
+            if (event?.type === "message.part.updated") {
+                // 툴 part 가 completed/error 로 바뀌면 그 호출은 끝났다. 툴이 throw 한
+                // 경우 tool.execute.after 가 오지 않으므로 이것이 유일한 종결 신호다.
+                const props = event.properties;
+                const part = props?.part;
+                if (part && part.type === "tool") {
+                    const state = part.state;
+                    const status = typeof state?.status === "string" ? state.status : undefined;
+                    if (status === "completed" || status === "error") {
+                        const sid = typeof part.sessionID === "string" ? part.sessionID
+                            : typeof props?.sessionID === "string" ? props.sessionID
+                                : undefined;
+                        const callID = typeof part.callID === "string" ? part.callID : undefined;
+                        if (sid)
+                            toolFinished(registry, sid, callID);
+                    }
+                }
+                return;
+            }
+            if (event?.type === "session.idle") {
+                // idle 로 전이한 세션에 실행 중인 툴은 정의상 없다 — 남은 항목은 전부 누수다.
+                const props = event.properties;
+                if (typeof props?.sessionID === "string")
+                    clearToolCalls(registry, props.sessionID);
+                return;
+            }
             if (event?.type === "session.deleted") {
                 const props = event.properties;
                 const sid = props?.info?.id ?? props?.sessionID;
                 if (sid) {
-                    const waiters = sessionDeletedWaiters.get(sid);
-                    if (waiters && waiters.length > 0) {
-                        for (const w of [...waiters]) {
-                            try {
-                                w();
-                            }
-                            catch { /* ignore */ }
-                        }
-                    }
+                    notifySessionDeleted(registry, sid);
+                    // 세션이 사라졌으니 실행 신호·권한 요청도 의미가 없다. sessionIssue /
+                    // sessionWorktree 는 dispatch 사본의 cleanupSubSession 이 지운다.
+                    clearToolCalls(registry, sid);
+                    registry.pendingPermissions.delete(sid);
                 }
                 return;
             }
@@ -1066,16 +1166,17 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                 : undefined;
             const toolLower = (input.tool || "").toLowerCase();
             logger.debug(`[makdoong2-team hook] tool.execute.before fired: tool="${input.tool}" sessionID="${sessionID}" agent="${agent ?? "unknown"}" callID="${input.callID}"`);
-            // 활성 툴 카운터는 **증분과 감소가 반드시 짝을 이뤄야 한다**.
+            // 활성 툴 집합은 **넣기와 빼기가 반드시 짝을 이뤄야 한다**.
             // tool.execute.after 는 툴이 실제로 실행된 뒤에만 돈다. 아래 가드들이 throw 하면
             // (차단된 bash · sealed 서브에이전트의 outer-world 툴 · leader 의 파일 쓰기 등)
-            // after 훅이 돌지 않아 카운터가 영구히 ≥1 로 남고, 그러면 isRecentlyActive() 가
+            // after 훅이 돌지 않아 항목이 영구히 남고, 그러면 isRecentlyActive() 가
             // 항상 true 가 되어 그 세션의 gone 감지와 orphan 회수가 **영구 비활성**된다.
             // 차단은 정상 동작이라 반드시 일어나므로 확정적으로 누수됐다.
-            if (sessionID) {
-                sessionLastToolExecuteAt.set(sessionID, Date.now());
-                sessionActiveToolCount.set(sessionID, (sessionActiveToolCount.get(sessionID) ?? 0) + 1);
-            }
+            // (툴 자체가 throw 하는 경우 — 권한 거부 · 파일 없음 — 는 여기서 잡을 수 없다.
+            // 그쪽은 폴러가 스냅샷의 completed/error part 로 정리한다: settleToolCalls.)
+            const activeToolKey = sessionID
+                ? toolStarted(registry, sessionID, input.callID)
+                : undefined;
             try {
                 if (sessionID && (toolLower === "dispatch_stage" || toolLower === "dispatch_verifier")) {
                     const callID = input.callID;
@@ -1322,9 +1423,9 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                 }
             }
             catch (err) {
-                // 차단으로 끝난 호출은 실행되지 않았다 → 증분을 되돌린다.
+                // 차단으로 끝난 호출은 실행되지 않았다 → 넣은 항목을 되돌린다.
                 if (sessionID)
-                    releaseActiveTool(sessionID);
+                    toolFinished(registry, sessionID, activeToolKey);
                 throw err;
             }
         },
@@ -1337,8 +1438,7 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
             const toolLowerAfter = (input.tool || "").toLowerCase();
             const afterSessionID = input.sessionID;
             if (afterSessionID) {
-                sessionLastToolExecuteAt.set(afterSessionID, Date.now());
-                releaseActiveTool(afterSessionID);
+                toolFinished(registry, afterSessionID, input.callID);
             }
             // ── Issue-reporter 표시 증명 기록·소멸 ──
             // 기록: 단독 `cat <payload>` 가 실행되면 그 시점의 파일 해시를 남긴다. 이
@@ -1611,22 +1711,73 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                             effectiveWorktree = storedWt;
                         }
                     }
+                    // ── main repo → worktree 정방향 동기화 ──
+                    // dispatch_verifier 는 서브세션 생성 전에 이 동기화를 하는데 dispatch_stage
+                    // 에는 없었다. 그 비대칭이 REJECTED 재작업 규약을 구조적으로 깨뜨린다:
+                    // 규약은 team-leader 에게 `.done=false` 재설정을 시키는데, 리더의 cwd 는
+                    // main repo 이고 아래 done 검사는 worktree 사본을 본다. 리더가 규약대로
+                    // 했는데도 `already_done: true` 로 차단되고, 리더는 오류 문구만으로는
+                    // 원인을 알 수 없어 같은 실수를 반복했다 (issue #11).
+                    // 동기화 방향은 파이프라인 불변식과 같다 — main 이 durable 사본, worktree
+                    // 는 forward-seed / reverse-merge 되는 작업 사본이다 (finally 의 REVERSE).
+                    if (effectiveWorktree !== cwd) {
+                        logger.debug(`[wt-sync] FORWARD issue=${args.issue} worktree=${effectiveWorktree} ` +
+                            `caller=dispatch_stage stage=${args.target_stage}`);
+                        const fwdSync = await $ `bash ${SCRIPTS_DIR}/wt-sync-ignored.sh ${effectiveWorktree} ${args.issue}`
+                            .cwd(cwd).quiet().nothrow();
+                        if (fwdSync.exitCode !== 0) {
+                            logger.warn(`[wt-sync] FORWARD FAIL issue=${args.issue} caller=dispatch_stage exit=${fwdSync.exitCode} ` +
+                                `stderr=${redactAndTruncate(fwdSync.stderr?.toString() ?? "", 200)}`);
+                        }
+                    }
                     // done=true stage 재-dispatch 방지 (sub-agent tool-call loop → timeout/empty output).
                     // 3_delivery.* 는 hybrid stage (publisher = spec provider) 로 재-진입이 정상 흐름이라 제외.
                     const isHybridDelivery = args.target_stage.startsWith("3_delivery.");
                     if (!isHybridDelivery) {
-                        const doneR = await $ `bash ${SCRIPTS_DIR}/state.sh get ${args.issue} ${stageJqPath(args.target_stage) + ".done"}`
+                        const donePath = stageJqPath(args.target_stage) + ".done";
+                        const doneR = await $ `bash ${SCRIPTS_DIR}/state.sh get ${args.issue} ${donePath}`
                             .cwd(effectiveWorktree).quiet().nothrow();
                         if (doneR.exitCode === 0 && doneR.stdout?.toString().trim() === "true") {
+                            // 위 정방향 동기화가 성공했다면 두 사본은 같아야 한다. 그래도 다르면
+                            // 동기화가 실패한 것이고, 그 사실을 추측이 아니라 관측으로 알린다 —
+                            // 종전 문구는 "이미 done=true" 만 말해서, 사본 불일치라는 실제 원인을
+                            // 리더가 스스로 추론해야 했다 (state_unreadable 은 이미 안내한다).
+                            let mainRepoDone = null;
+                            if (effectiveWorktree !== cwd) {
+                                const mainDoneR = await $ `bash ${SCRIPTS_DIR}/state.sh get ${args.issue} ${donePath}`
+                                    .cwd(cwd).quiet().nothrow();
+                                if (mainDoneR.exitCode === 0)
+                                    mainRepoDone = mainDoneR.stdout?.toString().trim() ?? null;
+                            }
+                            const copyMismatch = mainRepoDone !== null && mainRepoDone !== "true";
                             return JSON.stringify({
                                 ok: false,
                                 gate: args.target_stage,
                                 stage: args.target_stage,
                                 agent: spec.id,
                                 already_done: true,
-                                reason: `Stage '${args.target_stage}' is already done=true. ` +
-                                    `Re-dispatching a completed stage causes sub-agent tool-call loops (timeout/empty output). ` +
-                                    `Call auto_advance_stage to obtain the correct next stage instead.`,
+                                state_copy_mismatch: copyMismatch,
+                                worktree_done: "true",
+                                main_repo_done: mainRepoDone,
+                                reason: copyMismatch
+                                    ? `Stage '${args.target_stage}' is done=true in the worktree state.json copy but ` +
+                                        `done=${mainRepoDone} in the main repo copy. state.sh 는 호출 cwd 의 git toplevel 을 ` +
+                                        `쓰므로 두 사본은 분리돼 있고, 이 검사는 worktree 사본을 본다. ` +
+                                        `main repo cwd 에서 '.done' 을 되돌렸다면 그 변경은 worktree 사본에 반영되지 않은 것이다 ` +
+                                        `(정방향 동기화를 이미 1회 자동 시도했고 실패했다).`
+                                    : `Stage '${args.target_stage}' is already done=true. ` +
+                                        `Re-dispatching a completed stage causes sub-agent tool-call loops (timeout/empty output). ` +
+                                        `Call auto_advance_stage to obtain the correct next stage instead. ` +
+                                        `참고: 방금 '.done=false' 로 되돌렸는데도 이 응답이 왔다면, 다른 cwd(main repo)에서 ` +
+                                        `state.json 을 조작해 worktree 사본과 불일치한 경우다 — state_unreadable 과 같은 메커니즘이다.`,
+                                next_action: copyMismatch
+                                    ? `동기화는 이미 자동 시도했고 실패했습니다 — 직접 재실행하지 마세요. ` +
+                                        `'bash ${SCRIPTS_DIR}/state.sh status ${args.issue}' 로 사본 상태를 확인하고, ` +
+                                        `해소되지 않으면 사용자에게 에스컬레이션하세요.`
+                                    : `auto_advance_stage(issue: "${args.issue}") 로 올바른 다음 단계를 받으세요. ` +
+                                        `REJECTED 재작업 중이라면 '.done' 재설정이 실제로 반영됐는지 ` +
+                                        `bash ${SCRIPTS_DIR}/state.sh get ${args.issue} <done jq-path> 로 먼저 확인하세요 ` +
+                                        `(jq-path: ${donePath}).`,
                             });
                         }
                     }
@@ -1742,7 +1893,7 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                             `Stage 명세 파일은 위 Stages directory 경로에서 읽으시오. \`<SCRIPTS_DIR>/../stages/\` 상대경로를 사용하지 마시오.`,
                         ];
                         if (args.target_stage === "2_implementation.dev") {
-                            base.push(`\n=== dev substage 요구사항 소스 우선순위 ===`, `구현 착수 전 요구사항은 반드시 다음 순서로 참조한다:`, `  a) FIRST — requirements-draft.md 를 우선 확인 (아래 bash 스니펫 그대로 실행):`, buildDraftPathReadSnippet(args.issue, "       "), `     파일이 존재하고 비어있지 않으면 이 파일이 요구사항의 진실의 원천이다.`, `  b) FALLBACK — draft_path 미기록/파일 부재/빈 파일 인 경우 Jira 이슈 조회:`, `       skill(name="jira-research") 로 works MCP 로드 →`, `       skill_mcp(mcp_name="works", tool_name="getIssue", arguments={"issueKey":"${args.issue}"})`, `  c) 두 소스 모두 접근 불가하면 사용자에게 상황을 보고하고 즉시 종료.`, `주의: requirements-draft.md 없이 Jira 이슈만으로 구현 범위를 재결정하지 말 것 — draft 가 없다는 것은 planning 이 부적절하게 진행된 신호이므로 사용자에게 보고하고 종료하시오.`);
+                            base.push(`\n=== dev substage 요구사항 소스 우선순위 ===`, `구현 착수 전 요구사항은 반드시 다음 순서로 참조한다:`, `  a) FIRST — requirements-draft.md 를 우선 확인 (아래 bash 스니펫 그대로 실행):`, buildDraftPathReadSnippet(args.issue, "       "), `     파일이 존재하고 비어있지 않으면 이 파일이 요구사항의 진실의 원천이다.`, `  b) FALLBACK — draft_path 미기록/파일 부재/빈 파일 인 경우 Jira 이슈 조회:`, `       skill(name="jira-research") 로 works MCP 로드 →`, `       skill_mcp(mcp_name="works", tool_name="getIssue", arguments={"issueKey":"${args.issue}"})`, `  c) 두 소스 모두 접근 불가하면 사용자에게 상황을 보고하고 즉시 종료.`, `주의: requirements-draft.md 없이 Jira 이슈만으로 구현 범위를 재결정하지 말 것 — draft 가 없다는 것은 planning 이 부적절하게 진행된 신호이므로 사용자에게 보고하고 종료하시오.`, `\n=== 테스트 동반 원칙은 requirements 의 선언을 따른다 (issue #11) ===`, `테스트 추가 여부는 스스로 정하지 않는다. 아래를 실행해 1_planning.requirements 가 승인·동결한 선언을 먼저 읽는다:`, `  bash ${SCRIPTS_DIR}/state.sh get ${args.issue} '.stages."1_planning".substages."requirements".test_scope'`, `  - new_tests_required=true (마커 부재·null 도 true 로 간주 — fail-closed) → 변경에 대한 테스트를 함께 추가하고 self_check.new_tests_added=true 로 기록한다.`, `  - new_tests_required=false → 테스트 추가는 이번 이슈의 범위 밖이다. 추가하지 않는 것이 정답이며, self_check.new_tests_added=false 와 함께 dev.new_tests_waived=true 마커를 남긴다.`, `이 마커는 읽기 전용이다 — engineer 가 test_scope 를 쓰거나 고치지 않는다. 선언과 실제 작업이 맞지 않으면 임의로 면제·추가하지 말고 최종 출력에 적어 보고한다.`);
                         }
                         if (attemptNum > 1) {
                             base.push(`\n=== 재개(resume) 지시 — 이전 세션 중단됨 ===`, `이전 세션 ID: ${priorSessionIds.join(", ")} (attempt ${attemptNum - 1})`, `중단 원인: 이전 sub-session이 stall/gone 감지되어 새 세션으로 이어서 진행합니다.`, `context 승계 방식: opencode API는 세션 간 대화 이력을 옮기지 못하므로 state.json 을 진실의 원천으로 사용합니다.`, `첫 번째 필수 작업:`, `  1) bash ${SCRIPTS_DIR}/state.sh get ${args.issue} '.' 로 현재 상태 전량 조회`, `  2) 이미 done=true 로 기록된 substage / 마커는 재실행하지 말고 skip`, `  3) 미완료 substage 부터 stage spec 순서대로 이어서 진행`, `  4) 완료 시 관례대로 요약 출력 후 종료`, `주의: state.json 마커가 이미 target substage 완료를 나타내면 즉시 요약만 출력하고 종료하시오 (재작업 금지).`);

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

@@ -5,6 +5,19 @@ export type MessagePartLike = {
     state?: {
         status?: string;
     };
+    /** ToolPart 의 호출 ID — `tool.execute.before/after` 훅의 callID 와 같은 값. */
+    callID?: string;
+};
+/**
+ * 폴 시점 스냅샷에서 읽은 툴 호출 상태. `isToolExecuting` 에 넘겨 훅 레지스트리와
+ * 대조하게 한다 — throw 로 끝난 툴은 after 훅이 돌지 않아 레지스트리에 남는데,
+ * 스냅샷의 completed/error part 가 그 호출이 끝났음을 확정해 준다.
+ */
+export type ToolSnapshot = {
+    /** completed / error 로 끝난 호출 ID (스냅샷 전체 메시지 기준). */
+    settledCallIDs: ReadonlySet<string>;
+    /** pending / running 인 호출 ID (마지막 assistant 메시지 기준). */
+    inFlightCallIDs: ReadonlySet<string>;
 };
 export type MessageInfoLike = {
     id?: string;
@@ -109,7 +122,7 @@ export interface PollOptions {
     messageStallThresholdMs?: number;
     statusAbsentGraceMs?: number;
     isRecentlyActive?: () => boolean;
-    isToolExecuting?: () => boolean;
+    isToolExecuting?: (snapshot: ToolSnapshot) => boolean;
     contentStableCompletionMs?: number;
     preambleOnlyTextThreshold?: number;
     nudgeAtFraction?: number;

package/dist/poll-sub-session.js

@@ -29,6 +29,37 @@
 const TOOL_CALL_PART_TYPES = new Set(["tool", "tool_call", "tool-call", "tool_use"]);
 /** 아직 끝나지 않은 툴 상태 (ToolStatePending / ToolStateRunning). */
 const IN_FLIGHT_TOOL_STATUSES = new Set(["pending", "running"]);
+/** 확실히 끝난 툴 상태 (ToolStateCompleted / ToolStateError). */
+const SETTLED_TOOL_STATUSES = new Set(["completed", "error"]);
+/**
+ * 스냅샷에서 툴 호출 ID 를 상태별로 모은다. settled 는 전체 메시지를 훑는다 —
+ * 레지스트리에 남은 항목은 이전 turn 의 호출일 수도 있다. inFlight 는 마지막
+ * assistant 메시지만 본다 (`hasPendingToolCall` 과 같은 기준).
+ */
+function collectToolSnapshot(messages, lastAssistant) {
+    const settledCallIDs = new Set();
+    const inFlightCallIDs = new Set();
+    for (const m of messages) {
+        if (m.info?.role !== "assistant")
+            continue;
+        for (const part of m.parts ?? []) {
+            if (!TOOL_CALL_PART_TYPES.has(part.type))
+                continue;
+            if (typeof part.callID !== "string" || part.callID.length === 0)
+                continue;
+            const status = part.state?.status;
+            if (typeof status === "string" && SETTLED_TOOL_STATUSES.has(status))
+                settledCallIDs.add(part.callID);
+        }
+    }
+    for (const part of lastAssistant?.parts ?? []) {
+        if (!isInFlightToolPart(part))
+            continue;
+        if (typeof part.callID === "string" && part.callID.length > 0)
+            inFlightCallIDs.add(part.callID);
+    }
+    return { settledCallIDs, inFlightCallIDs };
+}
 /**
  * "지금 실행 중인 툴 호출이 있는가".
  *
@@ -236,7 +267,9 @@ export async function pollSubSession(client, sessionId, options = {}) {
         // 둘 중 하나라도 "툴이 떠 있다" 고 하면 완료로 판정하지 않는다 — 스냅샷은
         // 서버 반영이 늦고(issue #7), 훅 신호는 훅이 안 붙은 환경에서 아예 없다.
         // OR 로 묶어야 각자의 사각지대를 서로 덮는다.
-        const toolExecuting = isToolExecuting?.() === true;
+        const toolExecuting = isToolExecuting
+            ? isToolExecuting(collectToolSnapshot(messages, lastAssistant)) === true
+            : false;
         const toolInFlight = hasPendingToolCall || toolExecuting;
         const stalledMs = now() - lastProgressAt;
         // session_gone (status_absent) has two admission paths with different
@@ -376,7 +409,9 @@ export async function pollSubSession(client, sessionId, options = {}) {
             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)`));
+                    : client.permission
+                        ? ` no pending permission observed for this session (tool part in flight, no tool.execute signal)`
+                        : ` pending permission unknown (permission source unavailable)`));
             await client.session.abort({ path: { id: sessionId } }).catch(() => undefined);
             return {
                 kind: "permission_stall",
@@ -629,8 +664,10 @@ export function pollOutcomeToLegacy(outcome) {
                             "에이전트 permission 설정 문제다. 해당 에이전트의 frontmatter `permission:` 블록을 점검하라 " +
                             "(정식 키는 `edit`; `write` 키는 존재하지 않아 조용히 무시된다).";
                     default:
-                        return "대기 대상을 특정하지 못했다. 점검: opencode.json 의 permission.external_directory 시드 존재 여부 " +
-                            "(`npx makdoong2-team doctor`).";
+                        return "툴 호출 part 가 떠 있는데 실행 신호(tool.execute.before)도 권한 요청도 관측되지 않았다. 점검: " +
+                            "(1) 세션의 디렉토리에서도 플러그인이 로드되는가 — 로그의 `[init] plugin instance directory=…` 가 " +
+                            "worktree 경로로도 찍혀야 한다 (opencode 는 디렉토리마다 플러그인을 따로 초기화한다) " +
+                            "(2) opencode.json 의 permission.external_directory 시드 (`npx makdoong2-team doctor`).";
                 }
             })();
             return {

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

@@ -0,0 +1,74 @@
+export type PendingPermission = {
+    id: string;
+    sessionID: string;
+    permission: string;
+    patterns: string[];
+    askedAt: number;
+};
+export interface SubSessionRegistry {
+    readonly version: 1;
+    /** sessionID → (callID → startedAt). before 에서 넣고 after / 툴 part 종결에서 뺀다. */
+    readonly activeToolCalls: Map<string, Map<string, number>>;
+    /** sessionID → 마지막 tool.execute.* 발화 시각. */
+    readonly lastToolExecuteAt: Map<string, number>;
+    /** sessionID → (requestID → 요청). permission.asked 로 넣고 replied 로 뺀다. */
+    readonly pendingPermissions: Map<string, Map<string, PendingPermission>>;
+    /** sessionID → 이슈키. dispatch 사본이 쓰고 훅 사본(guard-bash.sh 인자)이 읽는다. */
+    readonly sessionIssue: Map<string, string>;
+    /** sessionID → worktree 절대경로. auto-git-add 가 읽는다. */
+    readonly sessionWorktree: Map<string, string>;
+    /** session.deleted 대기자. abort 후 재디스패치 전 race window 를 닫는다. */
+    readonly sessionDeletedWaiters: Map<string, Array<() => void>>;
+    /** callID 가 없는 before 훅에 붙일 대체 키 일련번호. */
+    anonSeq: number;
+}
+export declare function createSubSessionRegistry(): SubSessionRegistry;
+/**
+ * 프로세스 전역 레지스트리. 첫 호출이 만들고 이후 호출은 같은 객체를 돌려준다.
+ * 키에 버전을 박아 두어, 형태가 다른 미래 버전이 같은 프로세스에 섞여도 서로의
+ * 객체를 깨뜨리지 않는다.
+ */
+export declare function sharedSubSessionRegistry(): SubSessionRegistry;
+/** 테스트 전용 — 전역 객체를 비운다. */
+export declare function resetSharedSubSessionRegistryForTests(): void;
+/** `tool.execute.before` — 이 세션에서 callID 툴이 실행을 시작했다. 사용한 키를 돌려준다. */
+export declare function toolStarted(reg: SubSessionRegistry, sessionID: string, callID: string | undefined, now?: number): string;
+/**
+ * `tool.execute.after` 또는 툴 part 의 completed/error 관측 — 실행이 끝났다.
+ * 멱등이다: 같은 callID 를 두 번 끝내도, 모르는 callID 를 끝내도 아무 일도 없다.
+ * callID 가 없으면 가장 최근에 시작한 항목을 뺀다 (종전 카운터 의미 유지).
+ */
+export declare function toolFinished(reg: SubSessionRegistry, sessionID: string, callID: string | undefined, now?: number): boolean;
+/**
+ * 메시지 스냅샷과 대조해 이미 끝난 호출을 정리한다.
+ *
+ * 툴이 throw 하면(권한 거부 · 파일 없음 · MCP 오류) opencode 는 `tool.execute.after`
+ * 를 부르지 않는다 — 항목이 영영 남아 `isToolExecuting()` 이 참으로 굳고, 그러면
+ * 완료 판정이 유보돼 substage 가 절대 타임아웃까지 기다린다. 스냅샷의 tool part
+ * 가 completed/error 면 그 호출은 확실히 끝난 것이므로 여기서 뺀다. 스냅샷에
+ * **아직 없는** 호출은 건드리지 않는다 (issue #7 의 110ms 창 — 훅은 발화했는데
+ * 서버가 part 를 아직 반영하지 않은 상태). 정리한 개수를 돌려준다.
+ */
+export declare function settleToolCalls(reg: SubSessionRegistry, sessionID: string, settledCallIDs: Iterable<string>): number;
+/** 지금 이 순간 이 세션에서 실행 중인 툴이 있는가 (순간값). */
+export declare function isToolExecuting(reg: SubSessionRegistry, sessionID: string): boolean;
+export declare function activeToolCount(reg: SubSessionRegistry, sessionID: string): number;
+/** 세션이 idle 로 전이했다 — 실행 중인 툴은 정의상 없다. */
+export declare function clearToolCalls(reg: SubSessionRegistry, sessionID: string): void;
+/**
+ * 플러그인 `event` 훅이 받는 권한 요청 이벤트를 공통 형태로 바꾼다.
+ *
+ * 1.18 v1 브리지는 `permission.asked` 를 `PermissionRequest` 그대로 싣는다
+ * (`id / sessionID / permission / patterns`). 더 오래된 SDK 형태 `permission.updated`
+ * 는 `type` · `pattern`(문자열 또는 배열) 을 쓴다. 둘 다 받아 둔다 — 어느 쪽이 오든
+ * 폴러가 보는 것은 같은 shape 이어야 한다. 요청으로 볼 수 없는 페이로드는 null.
+ */
+export declare function normalizePermissionEvent(type: string, properties: unknown, now?: number): PendingPermission | null;
+export declare function permissionAsked(reg: SubSessionRegistry, req: PendingPermission): void;
+export declare function permissionReplied(reg: SubSessionRegistry, sessionID: string, requestID: string): void;
+/** 이 세션에 답을 기다리는 권한 요청 — 오래된 순. */
+export declare function pendingPermissionsFor(reg: SubSessionRegistry, sessionID: string): PendingPermission[];
+/** 세션 하나의 흔적을 전부 지운다 (cleanupSubSession · session.deleted). */
+export declare function forgetSession(reg: SubSessionRegistry, sessionID: string): void;
+/** session.deleted — 대기자를 전부 깨운다. 깨운 수를 돌려준다. */
+export declare function notifySessionDeleted(reg: SubSessionRegistry, sessionID: string): number;

package/dist/sub-session-registry.js

@@ -0,0 +1,204 @@
+// 프로세스 전역 서브세션 레지스트리 — 플러그인 사본 사이의 공유 신호.
+//
+// opencode 1.18 은 **디렉토리(Instance)마다 플러그인을 따로 초기화한다**.
+// `dispatch_stage` 는 서브세션을 `directory=<worktree>` 로 만들므로 그 세션의
+// `tool.execute.before/after` · `event` 훅은 worktree Instance 의 플러그인 사본에서
+// 발화하고, 그 세션을 감시하는 `pollSubSession` 은 main Instance 의 사본에서 돈다.
+// 사본마다 자기 Map 을 들고 있으면 폴러는 언제나 빈 Map 을 본다 —
+// `isToolExecuting()` 이 영영 false 라 60초를 넘는 모든 툴(sbt test 등)이
+// `permission_stall`(reason=tool_call_stall) 로 abort 됐다 (GitHub issue #10).
+//
+// 그래서 사본을 가로지르는 신호는 전부 여기, `globalThis` 에 둔다. 같은 프로세스
+// 안의 모든 사본이 — 모듈 경로가 달라 module cache 가 갈리더라도 — 한 객체를 본다.
+// 여기 두는 것은 "훅 사본이 쓰고 폴러 사본이 읽는" 세션 단위 신호뿐이다.
+// `pendingDispatch` 같은 디스패치 소유 상태는 공유하지 않는다 — 공유하면 worktree
+// 사본의 `session.created` 핸들러가 pane 을 한 번 더 띄운다.
+//
+// 이 파일은 src/opencode-plugin.ts 에서 import 만 한다 (re-export 금지 —
+// 로더가 모든 named export 를 plugin factory 로 호출한다).
+const SHARED_KEY = Symbol.for("makdoong2-team.sub-session-registry.v1");
+export function createSubSessionRegistry() {
+    return {
+        version: 1,
+        activeToolCalls: new Map(),
+        lastToolExecuteAt: new Map(),
+        pendingPermissions: new Map(),
+        sessionIssue: new Map(),
+        sessionWorktree: new Map(),
+        sessionDeletedWaiters: new Map(),
+        anonSeq: 0,
+    };
+}
+/**
+ * 프로세스 전역 레지스트리. 첫 호출이 만들고 이후 호출은 같은 객체를 돌려준다.
+ * 키에 버전을 박아 두어, 형태가 다른 미래 버전이 같은 프로세스에 섞여도 서로의
+ * 객체를 깨뜨리지 않는다.
+ */
+export function sharedSubSessionRegistry() {
+    const g = globalThis;
+    const existing = g[SHARED_KEY];
+    if (existing && existing.version === 1)
+        return existing;
+    const created = createSubSessionRegistry();
+    g[SHARED_KEY] = created;
+    return created;
+}
+/** 테스트 전용 — 전역 객체를 비운다. */
+export function resetSharedSubSessionRegistryForTests() {
+    delete globalThis[SHARED_KEY];
+}
+// ── 툴 실행 신호 ─────────────────────────────────────────────────────────────
+const ANON_PREFIX = "anon#";
+/** `tool.execute.before` — 이 세션에서 callID 툴이 실행을 시작했다. 사용한 키를 돌려준다. */
+export function toolStarted(reg, sessionID, callID, now = Date.now()) {
+    const key = typeof callID === "string" && callID.length > 0 ? callID : `${ANON_PREFIX}${++reg.anonSeq}`;
+    let calls = reg.activeToolCalls.get(sessionID);
+    if (!calls) {
+        calls = new Map();
+        reg.activeToolCalls.set(sessionID, calls);
+    }
+    calls.set(key, now);
+    reg.lastToolExecuteAt.set(sessionID, now);
+    return key;
+}
+/**
+ * `tool.execute.after` 또는 툴 part 의 completed/error 관측 — 실행이 끝났다.
+ * 멱등이다: 같은 callID 를 두 번 끝내도, 모르는 callID 를 끝내도 아무 일도 없다.
+ * callID 가 없으면 가장 최근에 시작한 항목을 뺀다 (종전 카운터 의미 유지).
+ */
+export function toolFinished(reg, sessionID, callID, now = Date.now()) {
+    reg.lastToolExecuteAt.set(sessionID, now);
+    const calls = reg.activeToolCalls.get(sessionID);
+    if (!calls || calls.size === 0)
+        return false;
+    let key;
+    if (typeof callID === "string" && callID.length > 0) {
+        if (!calls.has(callID))
+            return false;
+        key = callID;
+    }
+    else {
+        let latest = -Infinity;
+        for (const [k, startedAt] of calls) {
+            if (startedAt >= latest) {
+                latest = startedAt;
+                key = k;
+            }
+        }
+    }
+    if (key === undefined)
+        return false;
+    calls.delete(key);
+    if (calls.size === 0)
+        reg.activeToolCalls.delete(sessionID);
+    return true;
+}
+/**
+ * 메시지 스냅샷과 대조해 이미 끝난 호출을 정리한다.
+ *
+ * 툴이 throw 하면(권한 거부 · 파일 없음 · MCP 오류) opencode 는 `tool.execute.after`
+ * 를 부르지 않는다 — 항목이 영영 남아 `isToolExecuting()` 이 참으로 굳고, 그러면
+ * 완료 판정이 유보돼 substage 가 절대 타임아웃까지 기다린다. 스냅샷의 tool part
+ * 가 completed/error 면 그 호출은 확실히 끝난 것이므로 여기서 뺀다. 스냅샷에
+ * **아직 없는** 호출은 건드리지 않는다 (issue #7 의 110ms 창 — 훅은 발화했는데
+ * 서버가 part 를 아직 반영하지 않은 상태). 정리한 개수를 돌려준다.
+ */
+export function settleToolCalls(reg, sessionID, settledCallIDs) {
+    const calls = reg.activeToolCalls.get(sessionID);
+    if (!calls || calls.size === 0)
+        return 0;
+    let n = 0;
+    for (const id of settledCallIDs) {
+        if (calls.delete(id))
+            n++;
+    }
+    if (calls.size === 0)
+        reg.activeToolCalls.delete(sessionID);
+    return n;
+}
+/** 지금 이 순간 이 세션에서 실행 중인 툴이 있는가 (순간값). */
+export function isToolExecuting(reg, sessionID) {
+    return (reg.activeToolCalls.get(sessionID)?.size ?? 0) > 0;
+}
+export function activeToolCount(reg, sessionID) {
+    return reg.activeToolCalls.get(sessionID)?.size ?? 0;
+}
+/** 세션이 idle 로 전이했다 — 실행 중인 툴은 정의상 없다. */
+export function clearToolCalls(reg, sessionID) {
+    reg.activeToolCalls.delete(sessionID);
+}
+// ── 권한 요청 관측 ───────────────────────────────────────────────────────────
+/**
+ * 플러그인 `event` 훅이 받는 권한 요청 이벤트를 공통 형태로 바꾼다.
+ *
+ * 1.18 v1 브리지는 `permission.asked` 를 `PermissionRequest` 그대로 싣는다
+ * (`id / sessionID / permission / patterns`). 더 오래된 SDK 형태 `permission.updated`
+ * 는 `type` · `pattern`(문자열 또는 배열) 을 쓴다. 둘 다 받아 둔다 — 어느 쪽이 오든
+ * 폴러가 보는 것은 같은 shape 이어야 한다. 요청으로 볼 수 없는 페이로드는 null.
+ */
+export function normalizePermissionEvent(type, properties, now = Date.now()) {
+    if (type !== "permission.asked" && type !== "permission.updated")
+        return null;
+    if (!properties || typeof properties !== "object")
+        return null;
+    const p = properties;
+    const id = typeof p.id === "string" ? p.id : undefined;
+    const sessionID = typeof p.sessionID === "string" ? p.sessionID : undefined;
+    if (!id || !sessionID)
+        return null;
+    const permission = typeof p.permission === "string" ? p.permission
+        : typeof p.type === "string" ? p.type
+            : "unknown";
+    const rawPatterns = p.patterns ?? p.pattern;
+    const patterns = Array.isArray(rawPatterns)
+        ? rawPatterns.filter((x) => typeof x === "string")
+        : typeof rawPatterns === "string" ? [rawPatterns]
+            : [];
+    return { id, sessionID, permission, patterns, askedAt: now };
+}
+export function permissionAsked(reg, req) {
+    let bySession = reg.pendingPermissions.get(req.sessionID);
+    if (!bySession) {
+        bySession = new Map();
+        reg.pendingPermissions.set(req.sessionID, bySession);
+    }
+    bySession.set(req.id, req);
+}
+export function permissionReplied(reg, sessionID, requestID) {
+    const bySession = reg.pendingPermissions.get(sessionID);
+    if (!bySession)
+        return;
+    bySession.delete(requestID);
+    if (bySession.size === 0)
+        reg.pendingPermissions.delete(sessionID);
+}
+/** 이 세션에 답을 기다리는 권한 요청 — 오래된 순. */
+export function pendingPermissionsFor(reg, sessionID) {
+    const bySession = reg.pendingPermissions.get(sessionID);
+    if (!bySession)
+        return [];
+    return [...bySession.values()].sort((a, b) => a.askedAt - b.askedAt);
+}
+// ── 수명 ─────────────────────────────────────────────────────────────────────
+/** 세션 하나의 흔적을 전부 지운다 (cleanupSubSession · session.deleted). */
+export function forgetSession(reg, sessionID) {
+    reg.activeToolCalls.delete(sessionID);
+    reg.lastToolExecuteAt.delete(sessionID);
+    reg.pendingPermissions.delete(sessionID);
+    reg.sessionIssue.delete(sessionID);
+    reg.sessionWorktree.delete(sessionID);
+}
+/** session.deleted — 대기자를 전부 깨운다. 깨운 수를 돌려준다. */
+export function notifySessionDeleted(reg, sessionID) {
+    const waiters = reg.sessionDeletedWaiters.get(sessionID);
+    if (!waiters || waiters.length === 0)
+        return 0;
+    const copy = [...waiters];
+    for (const w of copy) {
+        try {
+            w();
+        }
+        catch { /* waiter 오류는 이벤트 처리를 막지 않는다 */ }
+    }
+    return copy.length;
+}

package/gates/stage4-dev-post-verify.sh

@@ -5,6 +5,7 @@
 #   1. worktree 가 존재하는가
 #   2. dev-written-files.txt 에 기록된 모든 파일이 staging(index) 혹은 HEAD tree 에 존재하는가
 #   3. .gitignore 를 존중한 untracked 파일이 0인가
+#   4. 테스트 동반 원칙이 1_planning.requirements 의 test_scope 선언과 일치하는가
 #
 # 불변식: 3_delivery.commit 는 untracked 를 자동 제외하므로,
 #         본 게이트를 통과한 파일만이 커밋 대상에 진입한다.
@@ -66,4 +67,40 @@ $(echo "$UNTRACKED" | sed 's/^/  - /')"
   fail "$MSG"
 fi
 
+# ── 4. 테스트 동반 원칙 — requirements 의 선언을 따른다 (issue #11) ──────────
+#
+# 종전에는 이 검사가 게이트에 없고 verifier 만 알고 있었으며, 그 verifier 기준은
+# "sub-agent output 에 '테스트 추가' 명시" 라는 무조건 요구였다. requirements 가
+# 테스트 범위 제외를 승인·동결해도 그 결정을 참조하는 경로가 없어서, 순수 설정·
+# 인프라 전환 작업마다 REJECTED 가 반복되고 결국 engineer 가 승인된 스코프 밖의
+# 테스트를 추가했다. 게이트·stage spec·verifier 세 곳이 같은 선언을 보게 한다.
+#
+# 판정 규칙 (fail-closed):
+#   REQ = requirements.test_scope.new_tests_required — 부재/null = true 로 간주
+#   REQ=true  → self_check.new_tests_added 는 true 여야 한다
+#   REQ=false → new_tests_added 가 false 여도 되지만, 슬립과 구분하기 위해
+#               dev.new_tests_waived=true 마커가 함께 있어야 한다
+#
+# self_check 자체가 없는 구형 state 는 검사하지 않는다 (기존 동작 보존).
+q(){ local __v; if __v="$("$HERE/../scripts/state.sh" get "$ISSUE" "$1" 2>/dev/null)"; then printf "%s" "$__v"; else printf "__MISSING__"; fi; }
+
+SELF_CHECK="$(q '.stages."2_implementation".substages."dev".self_check')"
+if [ "${SELF_CHECK}" != "__MISSING__" ] && [ "${SELF_CHECK}" != "null" ] && [ -n "${SELF_CHECK}" ]; then
+  NEW_TESTS_ADDED="$(q '.stages."2_implementation".substages."dev".self_check.new_tests_added')"
+  if [ "${NEW_TESTS_ADDED}" != "true" ]; then
+    REQ="$(q '.stages."1_planning".substages."requirements".test_scope.new_tests_required')"
+    if [ "${REQ}" != "false" ]; then
+      fail "테스트 동반 원칙 미충족: self_check.new_tests_added=${NEW_TESTS_ADDED} 인데
+requirements 의 테스트 범위 선언이 테스트 추가를 요구한다 (test_scope.new_tests_required=${REQ}; 부재/null 은 true 로 간주).
+→ 조치 A: 변경에 대한 테스트를 추가하고 new_tests_added=true 로 다시 기록한다.
+→ 조치 B: 이 이슈가 테스트를 붙일 수 없는 성질이라면 임의로 면제하지 말고 부장님에게 보고한다 —
+          테스트 범위 제외는 1_planning.requirements 에서만 승인·기록할 수 있다 (stages/02-requirements.md §2-6a)."
+    fi
+    WAIVED="$(q '.stages."2_implementation".substages."dev".new_tests_waived')"
+    [ "${WAIVED}" = "true" ] || fail "테스트 면제 마커 누락: requirements 가 테스트 추가를 제외했지만(test_scope.new_tests_required=false)
+dev.new_tests_waived 마커가 없다 — new_tests_added=false 가 의도된 면제인지 기록 누락인지 구분할 수 없다.
+→ 조치: bash <SCRIPTS_DIR>/state.sh set ${ISSUE} '.stages.\"2_implementation\".substages.\"dev\".new_tests_waived' 'true'"
+  fi
+fi
+
 echo "MAKDOONG2-GATE OK: 2_implementation.dev_post"

package/package.json

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

package/scripts/run-tests.mts

@@ -60,6 +60,7 @@ const STEPS = [
   "node --test test/gate-post-pr-verify.test.ts",
   "node --test test/gate-post-review-verify.test.ts",
   "node --test test/gate-requirements-quality.test.ts",
+  "node --test test/dev-test-scope-declaration.test.ts",
   "node --test test/worktree-sync-gate.test.ts",
   "node --test test/planner-prompt-early-exit.test.ts",
   "node --test test/plugin-bug-fixes.test.ts",
@@ -76,6 +77,7 @@ const STEPS = [
   "node --test test/verdict-reason-injection.test.ts",
   "node --test test/verdict-hash-normalize.test.ts",
   "node --test test/session-index-fallback.test.ts",
+  "node --test test/sub-session-registry.test.ts",
   "node --test test/plugin-exports-shape.test.ts",
   "node --test test/stale-worktree-recovery.test.ts",
   "node --test test/rollback-commits.test.ts",

package/scripts/state.sh

@@ -61,6 +61,37 @@ validate_issue() {
 
 sp()    { validate_issue "$1"; echo "$(root)/.makdoong2-team/$1/state.json"; }
 
+# ── 사본 불일치 경고 ────────────────────────────────────────────────────────
+# state.json 사본은 cwd(git toplevel)마다 하나씩이다. 전용 worktree 가 이미 있는데
+# main repo cwd 에서 `set` 을 실행하면, 갱신되는 것은 main 사본이고 dispatch_stage /
+# 게이트가 보는 것은 worktree 사본이다 — 쓴 사람은 반영됐다고 믿는데 파이프라인은
+# 옛 값을 본다. 실제로 REJECTED 재작업 규약(`.done=false` 재설정)이 이 경로에서
+# 두 번 연속 `already_done: true` 오차단으로 되돌아왔고, 오류 문구도 원인을 알려주지
+# 않아 같은 실수가 반복됐다 (issue #11).
+#
+# 쓰기 자체는 막지 않는다 — main 사본을 고치는 것이 옳은 상황도 있다. 어느 사본을
+# 건드렸는지 stderr 로 알리기만 한다 (stdout 계약·종료 코드 불변).
+norm_path() { if [ -d "$1" ]; then (cd "$1" && pwd -P); else printf '%s' "$1"; fi; }
+
+warn_if_copy_split() {
+  local file="$1" here there
+  [ -f "${file}" ] || return 0
+  there="$(jq -r '.worktree // ""' "${file}" 2>/dev/null || true)"
+  { [ -n "${there}" ] && [ "${there}" != "null" ] && [ -d "${there}" ]; } || return 0
+  here="$(norm_path "$(root)")"
+  there="$(norm_path "${there}")"
+  [ "${here}" != "${there}" ] || return 0
+  cat >&2 <<WARN
+[state.sh] 경고: 지금 갱신한 것은 이 cwd 의 사본이지, 이 이슈의 전용 worktree 사본이 아니다.
+  갱신한 사본 : ${here}
+  worktree    : ${there}
+  state.json 사본은 cwd(git toplevel)마다 하나씩이고, dispatch_stage 와 dev 이후 게이트는
+  worktree 사본을 본다. 자동 동기화(wt-sync-ignored.sh)는 서브에이전트 세션 앞뒤에서만 돌므로
+  이 쓰기는 다음 dispatch 까지 worktree 사본에 반영되지 않을 수 있다.
+  의도한 것이 worktree 사본이면 그 경로를 cwd 로 하여 다시 실행한다.
+WARN
+}
+
 # usage_die <시그니처> [부연 설명...]
 # `${2:?}` 가 뱉는 raw bash 에러(`line 127: 2: parameter null or not set`)는 복구
 # 작업 중인 에이전트에게 아무것도 알려주지 못한다. 대신 무엇을 어떻게 부를지 적는다.
@@ -294,6 +325,7 @@ JSON
     P="$(sp "${ISSUE}")"
     check_flat_stage_notation "$Q"
     write_json_atomic "$P" "set ${Q}" "$Q = $V"
+    warn_if_copy_split "$P"
     echo "state[$ISSUE] $Q = $V" ;;
   append)
     ISSUE="${1:-}"; Q="${2:-}"; V="${3:-}"

package/stages/01-planning.md

@@ -225,6 +225,21 @@ bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy.scope_size' '"large"'
 bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy.categorized_by' '"1_planning.requirements"'
 ```
 
+**테스트 범위 선언 (`test_scope` — 기계 판독 마커, 필수)**: 위 `**테스트 범위**` 서술은 사람이 읽는 문장이라 dev 게이트·verifier 가 해석할 수 없다. 같은 결정을 마커로 한 번 더 기록한다 — 없으면 `2_implementation.dev` 의 테스트 동반 원칙이 승인된 스코프 아웃을 보지 못하고 무조건 적용된다 (issue #11). 상세: `stages/02-requirements.md` §2-6a.
+
+```bash
+# 테스트를 동반하는 일반적인 경우
+bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."requirements".test_scope' \
+  '{"new_tests_required": true, "unit": "<대상 클래스/메서드>", "integration": "<빌드 플랜명/시나리오>", "rationale": "<한 줄 근거>"}'
+
+# 테스트 추가를 이번 이슈 범위에서 제외하기로 승인한 경우 (스코프 아웃에도 함께 명시)
+bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."requirements".test_scope' \
+  '{"new_tests_required": false, "unit": null, "integration": "<기존 통합 테스트로만 검증>", "rationale": "<왜 제외가 타당한지>"}'
+```
+
+- 마커 부재는 `new_tests_required: true` 로 간주된다 (fail-closed) — 선언 누락이 테스트 면제로 둔갑하지 않는다.
+- `test_scope_defined` self_check 항목은 **이 마커를 실제로 기록했다는 뜻**이다. 기록 후 값을 읽어 확인한다.
+
 ### 2-6. Requirements 완료 기록
 
 ```bash

package/stages/02-requirements.md

@@ -352,3 +352,25 @@ bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy.categorized_by' '"1_plannin
 ```
 
 self_check 에 `paths_explicit` / `test_scope_defined` / `atomic_units` / `scope_out_listed` 4항목을 함께 기록한다.
+
+### 2-6a. 테스트 범위 선언 (`test_scope` — 기계 판독 마커, 필수)
+
+위 `**테스트 범위**` 서술은 사람이 읽는 문장이라 dev 단계의 게이트·verifier 가 해석할 수 없다. **같은 결정을 기계가 읽는 마커로 한 번 더 기록한다** — 이 마커가 없으면 `2_implementation.dev` 의 "테스트 동반 원칙" 이 승인된 스코프 아웃을 보지 못한 채 무조건 적용되어, 요구사항 밖의 테스트 코드가 강제로 추가된다 (issue #11).
+
+```bash
+# 테스트를 동반하는 일반적인 경우
+bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."requirements".test_scope' \
+  '{"new_tests_required": true, "unit": "<대상 클래스/메서드>", "integration": "<빌드 플랜명/시나리오>", "rationale": "<한 줄 근거>"}'
+
+# 테스트 추가를 이번 이슈의 범위에서 제외하기로 승인한 경우
+bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."requirements".test_scope' \
+  '{"new_tests_required": false, "unit": null, "integration": "<기존 통합 테스트로만 검증>", "rationale": "<왜 제외가 타당한지 — 예: 애플리케이션 코드가 아닌 배포 설정 전환이라 단위 테스트 대상이 없음>"}'
+```
+
+- `new_tests_required` 는 **`true` 가 기본값**이다. 마커를 기록하지 않으면 하류(게이트·verifier)는 `true` 로 간주한다 (fail-closed) — 선언 누락이 "테스트 면제" 로 둔갑하지 않는다.
+- `false` 로 선언하려면 **스코프 아웃 항목에 그 사실이 함께 적혀 있어야 하고**, §2-3-2 의 "스코프 아웃 항목은 항상 명시적으로 확인한다" 절차를 거쳐야 한다. `rationale` 은 빈 문자열·`null` 금지.
+- `test_scope_defined` self_check 항목은 **이 마커를 실제로 기록했다는 뜻**이다. 자기선언이 아니라 값을 읽어 확인한다:
+  ```bash
+  bash <SCRIPTS_DIR>/state.sh get <이슈키> '.stages."1_planning".substages."requirements".test_scope'
+  ```
+- 이 선언은 요구사항 명세의 일부다 — 동결(2-4a) 이후 변경은 §2-4a 3번의 재승인 절차만 허용한다. **engineer / verifier 는 이 마커를 쓰지 않는다. 읽기만 한다.**

package/stages/05-worktree-dev.md

@@ -99,6 +99,25 @@ bash <SCRIPTS_DIR>/wt-sync-ignored.sh "$WT" "<이슈키>"
 - **outer-world 에이전트 위임 금지** — engineer 프론트매터에 `Task` 툴이 없으므로 물리적으로 스폰 불가. 구현·조사·리팩토링 모두 본 에이전트가 직접 수행한다. 조사가 필요하면 `skill_mcp` 로 makdoong2 스킬(`bitbucket-research` 등)만 사용.
 - 3단계 작업 단위 순서대로 구현한다. 한 단위가 끝나면 커밋 가능 상태로 만들어 둔다(실제 커밋은 6단계).
 
+## 4-4-pre. 테스트 범위 선언 조회 (필수 — 자가 검증 전)
+
+**테스트 동반 원칙은 무조건 적용되지 않는다.** `1_planning.requirements` 가 승인·동결한 테스트 범위 선언(`test_scope`)을 먼저 읽고, 그 선언이 정한 대로만 적용한다. 이 조회를 건너뛰면 "단위 테스트는 이번 변경 대상에 적용하지 않는다" 고 **이미 승인된** 이슈에서도 테스트 추가가 강제되어, 승인된 스코프 밖의 코드가 유입된다 (issue #11).
+
+```bash
+NEW_TESTS_REQUIRED="$(bash <SCRIPTS_DIR>/state.sh get <이슈키> \
+  '.stages."1_planning".substages."requirements".test_scope.new_tests_required' 2>/dev/null || echo 'true')"
+# 마커 부재("null")·조회 실패는 true 로 간주한다 (fail-closed).
+[ "$NEW_TESTS_REQUIRED" = "false" ] || NEW_TESTS_REQUIRED=true
+echo "new_tests_required=$NEW_TESTS_REQUIRED"
+
+# 근거(왜 제외됐는지)도 함께 읽어 최종 출력에 인용한다.
+bash <SCRIPTS_DIR>/state.sh get <이슈키> \
+  '.stages."1_planning".substages."requirements".test_scope.rationale' 2>/dev/null || true
+```
+
+- **이 마커를 engineer 가 쓰는 것은 금지다 (hardrule).** 읽기 전용이다. 테스트가 불필요해 보인다는 자체 판단으로 `test_scope` 를 기록·수정하면 요구사항 동결(§2-4a)을 우회하는 것이다. 선언이 실제 작업과 맞지 않으면 `done` 을 기록하지 말고 부장님에게 보고한다.
+- `new_tests_required=true` 인데 대상이 테스트를 붙일 수 없는 성질(순수 설정 파일 등)이라고 판단되면 — **임의로 면제하지 말고** 그 사실을 최종 출력에 적어 부장님이 requirements 재작업 여부를 결정하게 한다.
+
 ## 4-4. 최종 자가 검증 (Pre-Completion Checklist)
 
 `done=true` 직전, 아래 6체크를 자가 검증한다.
@@ -108,18 +127,35 @@ bash <SCRIPTS_DIR>/wt-sync-ignored.sh "$WT" "<이슈키>"
 |---|---|
 | 1 | 3단계에서 합의한 모든 수정/추가 파일이 구현되었다 (스코프 100% 충족) |
 | 2 | 기존 테스트(`sbt test` / `./gradlew test` / `mvn test` 등)가 모두 통과한다 |
-| 3 | 새 기능·버그 수정에 대한 테스트가 함께 추가되었다 (테스트 동반 원칙) |
+| 3 | **`new_tests_required=true` 인 경우에만** — 새 기능·버그 수정에 대한 테스트가 함께 추가되었다 (테스트 동반 원칙). `false` 면 이 항목은 면제되며 테스트를 추가하지 않는 것이 정답이다 |
 | 4 | 타입/린트/컴파일 에러가 0이다 |
 | 5 | `.env` / secrets / API 키 / 하드코딩된 비밀이 코드·테스트·로그에 노출되지 않았다 |
 | 6 | `write`/`edit`/`patch`/`multiedit` 로 편집한 모든 파일이 staging area 에 반영되었다 (`git ls-files --others --exclude-standard` 결과 0) |
 
 > 항목 6은 `tool.execute.after` 훅이 매 write 완료 시 자동으로 `git add`를 수행하므로 기본적으로 자동 충족된다. 훅 실패로 untracked 가 남으면 §4-5 exit gate 가 BLOCK 하여 재작업을 요구한다.
 
+**`new_tests_required=true` (기본)** — 테스트를 추가하고 `new_tests_added: true` 로 기록한다:
+
 ```bash
 bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."2_implementation".substages."dev".self_check' \
   '{"scope_met": true, "existing_tests_pass": true, "new_tests_added": true, "type_lint_clean": true, "no_secrets": true, "all_writes_staged": true}'
 ```
 
+**`new_tests_required=false` (승인된 스코프 아웃)** — `new_tests_added` 를 `false` 로 기록하고, 그것이 슬립이 아니라 선언에 따른 면제임을 나타내는 `new_tests_waived` 마커를 함께 남긴다. **두 기록은 한 쌍이다** — `new_tests_waived` 없이 `new_tests_added: false` 만 있으면 §4-5 exit gate 가 BLOCK 한다:
+
+```bash
+bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."2_implementation".substages."dev".self_check' \
+  '{"scope_met": true, "existing_tests_pass": true, "new_tests_added": false, "type_lint_clean": true, "no_secrets": true, "all_writes_staged": true}'
+bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."2_implementation".substages."dev".new_tests_waived' 'true'
+```
+
+### 최종 출력에 반드시 포함할 것
+
+verifier 는 state.json 마커로 판정하지만, 사람이 스코프 이탈을 조기에 발견할 수 있도록 출력에 한 줄을 남긴다:
+
+- `new_tests_required=true` → 추가한 테스트 파일 목록과 실행 결과
+- `new_tests_required=false` → `테스트 추가 없음 — requirements 의 test_scope.new_tests_required=false (사유: <rationale>)`
+
 ## 4-5. Exit Gate 실행 (staging 강제)
 
 ```bash