makdoong2-team 2.3.2 → 3.0.0

package/dist/research-fanout.js

@@ -1,341 +0,0 @@
-// research-fanout.ts — pure helpers for the parallel multi-source research fan-out.
-//
-// Why a separate module: the opencode plugin loader calls EVERY named export of
-// the entry file as a plugin factory (see ARCHITECTURE.md §2). New helpers must
-// live outside opencode-plugin.ts and be imported. `test/plugin-exports-shape.test.ts`
-// pins the entry file's export set.
-//
-// Everything here is deterministic and side-effect free so the fan-out contract
-// (source registry, query normalisation, output parsing, merge) is unit-testable
-// without spawning sessions.
-export const RESEARCH_SOURCES = {
-    jira: {
-        source: "jira",
-        skill: "jira-research",
-        mcp: "works",
-        label: "Jira",
-        scope: "에픽·상위 이슈·링크 이슈·서브태스크·코멘트에서 구체화된 요구사항과 결정 사항",
-    },
-    confluence: {
-        source: "confluence",
-        skill: "confluence-research",
-        mcp: "docs",
-        label: "Confluence",
-        scope: "설계 문서·ADR·API 스펙·운영 가이드에서 지켜야 할 제약과 합의된 규약",
-    },
-    bitbucket: {
-        source: "bitbucket",
-        skill: "bitbucket-research",
-        mcp: "repos",
-        label: "Bitbucket",
-        scope: "수정 대상 파일·클래스의 현재 구현, 관련 PR 이력, 기존 테스트 패턴",
-    },
-    "github-oss": {
-        source: "github-oss",
-        skill: "github-oss-research",
-        // SKILL.md 에 embedded MCP 선언이 없다 — WebFetch / site-wide chrome-devtools-mcp 사용.
-        mcp: null,
-        label: "GitHub OSS",
-        scope: "외부 오픈소스 라이브러리의 사용 예시·알려진 이슈·업스트림 변경",
-    },
-};
-/** Hard ceiling on simultaneously spawned research sessions, regardless of config. */
-export const MAX_RESEARCH_PARALLEL = 6;
-/** Default when `research.max_parallel` is unset. */
-export const DEFAULT_RESEARCH_PARALLEL = 3;
-/** Default per-source wall-clock budget when `research.timeout_minutes` is unset. */
-export const DEFAULT_RESEARCH_TIMEOUT_MINUTES = 10;
-/** Focus text longer than this is truncated before it reaches the prompt. */
-export const MAX_FOCUS_CHARS = 600;
-/** Per-source cap on findings kept in the merged artifact. */
-export const MAX_FINDINGS_PER_SOURCE = 20;
-export function resolveResearchSource(name) {
-    if (typeof name !== "string")
-        return null;
-    const key = name.trim().toLowerCase();
-    return RESEARCH_SOURCES[key] ?? null;
-}
-/** Clamp the configured parallelism into [1, MAX_RESEARCH_PARALLEL]. */
-export function resolveParallelism(configured) {
-    const n = typeof configured === "number" && Number.isFinite(configured)
-        ? Math.round(configured)
-        : DEFAULT_RESEARCH_PARALLEL;
-    return Math.min(MAX_RESEARCH_PARALLEL, Math.max(1, n));
-}
-/**
- * Validate + de-duplicate the caller's queries.
- *
- * Rules:
- *  - unknown source → rejected (the caller mistyped; failing loudly beats a silent no-op)
- *  - empty focus → rejected
- *  - same (source, focus) twice → the duplicate is rejected
- *  - more than `limit` survivors → the tail is DEFERRED, never silently dropped
- */
-export function normalizeQueries(raw, limit) {
-    const queries = [];
-    const rejected = [];
-    const deferred = [];
-    if (!Array.isArray(raw) || raw.length === 0) {
-        return { queries, rejected: [{ source: "(none)", reason: "queries 배열이 비어 있다" }], deferred };
-    }
-    const seen = new Set();
-    for (const item of raw) {
-        const rawSource = typeof item?.source === "string" ? item.source : String(item?.source ?? "");
-        const spec = resolveResearchSource(item?.source);
-        if (!spec) {
-            rejected.push({
-                source: rawSource || "(unset)",
-                reason: `알 수 없는 source. 허용: ${Object.keys(RESEARCH_SOURCES).join(", ")}`,
-            });
-            continue;
-        }
-        const focus = typeof item?.focus === "string" ? item.focus.trim() : "";
-        if (!focus) {
-            rejected.push({ source: spec.source, reason: "focus 가 비어 있다" });
-            continue;
-        }
-        const key = `${spec.source}::${focus.toLowerCase()}`;
-        if (seen.has(key)) {
-            rejected.push({ source: spec.source, reason: "동일 source+focus 중복" });
-            continue;
-        }
-        seen.add(key);
-        queries.push({ spec, focus: focus.slice(0, MAX_FOCUS_CHARS) });
-    }
-    if (queries.length > limit) {
-        for (const q of queries.slice(limit)) {
-            deferred.push({ source: q.spec.source, reason: `병렬 상한 ${limit} 초과 — 이번 라운드에서 제외` });
-        }
-        queries.length = limit;
-    }
-    return { queries, rejected, deferred };
-}
-/**
- * Prompt for one research sub-session.
- *
- * The session is deliberately narrow: one source, one focus, fixed output schema.
- * That is what makes the fan-out worth its cost — each session's context holds
- * only its own source's material instead of all three (DESIGN.md §3.7).
- */
-export function buildResearchPrompt(q, ctx) {
-    const lines = [
-        `Issue: ${ctx.issue}`,
-        `Working directory (ABSOLUTE): ${ctx.worktree}`,
-        `Scripts directory (ABSOLUTE): ${ctx.scriptsDir}`,
-        `Research source: ${q.spec.label} (${q.spec.source})`,
-        "",
-        `당신은 **${q.spec.label} 한 곳만** 조사하는 리서치 막둥이다. 다른 소스는 조사하지 않는다.`,
-        "",
-        "## 조사 지시",
-        "",
-        `1. **가장 먼저** \`skill(name="${q.spec.skill}")\` 로 스킬을 세션에 로드한다.`,
-        ...(q.spec.mcp
-            ? [
-                `   로드 전에 \`skill_mcp\` 를 부르면 \`MCP server "${q.spec.mcp}" not found\` 로 실패한다.`,
-                `2. \`skill_mcp(mcp_name="${q.spec.mcp}", ...)\` 로 아래 focus 를 조사한다.`,
-            ]
-            : [
-                "   이 스킬은 전용 MCP 가 없다. SKILL.md 의 절차대로 WebFetch / chrome-devtools-mcp 를 사용한다.",
-                "2. 위 수단으로 아래 focus 를 조사한다.",
-            ]),
-        `3. 조사 범위: ${q.spec.scope}`,
-        "",
-        "## Focus",
-        "",
-        q.focus,
-        "",
-        "## 출력 형식 (엄수)",
-        "",
-        "마지막 assistant turn 에 아래 스키마의 JSON 을 ```json 펜스로 감싸 **하나만** 출력한다.",
-        "펜스 밖 설명 문장은 자유지만, JSON 블록은 정확히 하나여야 한다.",
-        "",
-        "```json",
-        "{",
-        `  "source": "${q.spec.source}",`,
-        '  "findings": [',
-        '    {"title": "<한 줄 제목>", "detail": "<300자 이내 요약>", "url": "<출처 URL 또는 null>"}',
-        "  ],",
-        '  "gaps": ["<이 소스에서 확인하지 못한 항목>"]',
-        "}",
-        "```",
-        "",
-        "## 규약",
-        "",
-        "- **읽기 전용.** 파일 생성·수정, state.json 조작, git 명령을 일절 수행하지 않는다.",
-        "- 조사 결과가 없으면 `findings: []` 로 두고 `gaps` 에 이유를 적는다. 추측으로 채우지 않는다.",
-        "- 근거가 있는 항목에만 `url` 을 넣는다. 지어내지 않는다.",
-        `- findings 는 최대 ${MAX_FINDINGS_PER_SOURCE}개. 중요도 순으로 자른다.`,
-    ];
-    if (ctx.context) {
-        lines.push("", "## 추가 컨텍스트", "", ctx.context);
-    }
-    return lines.join("\n");
-}
-/**
- * Pull the research JSON out of an LLM turn.
- *
- * Order matters: prefer the LAST fenced ```json block (models often show a draft
- * before the final answer), then fall back to a balanced brace scan. A parse
- * failure is reported, never coerced into an empty-but-successful result — a
- * silently empty source reads as "nothing to find" when it means "nothing parsed".
- */
-export function parseResearchOutput(raw) {
-    if (typeof raw !== "string" || raw.trim() === "") {
-        return { ok: false, reason: "빈 응답" };
-    }
-    const candidates = [];
-    const fence = /```(?:json)?\s*\n([\s\S]*?)```/gi;
-    let m;
-    while ((m = fence.exec(raw)) !== null)
-        candidates.push(m[1]);
-    candidates.reverse(); // last fenced block first
-    const braced = extractBalancedObject(raw);
-    if (braced)
-        candidates.push(braced);
-    for (const c of candidates) {
-        let parsed;
-        try {
-            parsed = JSON.parse(c.trim());
-        }
-        catch {
-            continue;
-        }
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
-            continue;
-        const obj = parsed;
-        if (!("findings" in obj) && !("gaps" in obj))
-            continue;
-        return { ok: true, data: coerceParsed(obj) };
-    }
-    return { ok: false, reason: "JSON 블록을 찾지 못했다 (findings/gaps 키 부재)" };
-}
-function extractBalancedObject(text) {
-    const start = text.indexOf("{");
-    if (start < 0)
-        return null;
-    let depth = 0;
-    let inStr = false;
-    let esc = false;
-    for (let i = start; i < text.length; i++) {
-        const ch = text[i];
-        if (inStr) {
-            if (esc)
-                esc = false;
-            else if (ch === "\\")
-                esc = true;
-            else if (ch === '"')
-                inStr = false;
-            continue;
-        }
-        if (ch === '"')
-            inStr = true;
-        else if (ch === "{")
-            depth++;
-        else if (ch === "}") {
-            depth--;
-            if (depth === 0)
-                return text.slice(start, i + 1);
-        }
-    }
-    return null;
-}
-function coerceParsed(obj) {
-    const rawFindings = Array.isArray(obj.findings) ? obj.findings : [];
-    const findings = [];
-    for (const f of rawFindings.slice(0, MAX_FINDINGS_PER_SOURCE)) {
-        if (!f || typeof f !== "object")
-            continue;
-        const r = f;
-        const title = typeof r.title === "string" ? r.title.trim() : "";
-        if (!title)
-            continue;
-        findings.push({
-            title,
-            detail: typeof r.detail === "string" ? r.detail.trim() : "",
-            url: typeof r.url === "string" && r.url.trim() !== "" ? r.url.trim() : null,
-        });
-    }
-    const gaps = (Array.isArray(obj.gaps) ? obj.gaps : [])
-        .filter((g) => typeof g === "string" && g.trim() !== "")
-        .map((g) => g.trim());
-    return { findings, gaps };
-}
-/**
- * Merge per-source outcomes into the artifact a gate can check deterministically.
- *
- * `rejected` / `deferred` are carried into the artifact on purpose: a fan-out that
- * quietly covered 2 of 3 sources looks identical to one that covered all 3 unless
- * the shortfall is written down.
- */
-export function mergeResearchFindings(issue, generatedAt, outcomes, rejected, deferred) {
-    const ok = outcomes.filter((o) => o.status === "ok").length;
-    return {
-        issue,
-        generated_at: generatedAt,
-        sources: outcomes,
-        rejected,
-        deferred,
-        counts: {
-            requested: outcomes.length + rejected.length + deferred.length,
-            ok,
-            failed: outcomes.length - ok,
-            findings_total: outcomes.reduce((n, o) => n + o.findings.length, 0),
-        },
-    };
-}
-/** Human-readable one-liner per source for the tool's text return. */
-export function summarizeOutcomes(outcomes) {
-    return outcomes.map((o) => o.status === "ok"
-        ? `${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/gates/stage3-scope-verify.sh

@@ -1,69 +0,0 @@
-#!/usr/bin/env bash
-# stage3-scope-verify.sh <issue> — 3단계(범위 확정) 진입 게이트
-set -euo pipefail
-HERE="$(cd "$(dirname "$0")" && pwd)"
-ISSUE="${1:?usage: stage3-scope-verify.sh <issue>}"
-P="$("$HERE/../scripts/state.sh" root)/.makdoong2-team/$ISSUE/state.json"
-fail(){ echo "MAKDOONG2-GATE BLOCKED [1_planning.scope]: $1" >&2; exit 2; }
-[ -f "$P" ] || fail "state.json 없음 — jira substage부터 시작하라"
-# state.sh get 은 실패해도 stdout 에 "null" 한 줄을 찍고 exit 1 한다 (게이트들이
-# 의존하는 계약). 종전 `|| echo "__MISSING__"` 은 그 위에 한 줄을 **덧붙여**
-# `null\\n__MISSING__` 두 줄을 만들었고, 그 값은 `= "null"` 에도 `= "__MISSING__"`
-# 에도 걸리지 않아 **부재/손상이 "값이 있음" 으로 통과**했다. 실측 확인.
-# if 형태로 성공 출력만 취하고, 실패 시에는 sentinel 하나만 낸다.
-q(){ local __v; if __v="$("$HERE/../scripts/state.sh" get "$ISSUE" "$1" 2>/dev/null)"; then printf "%s" "$__v"; else printf "__MISSING__"; fi; }
-[ "$(q '.stages."1_planning".substages."scope".done')" != "true" ] || fail "이미 done=true 완료됨 — auto_advance_stage 로 다음 단계 진행"
-[ "$(q '.stages."1_planning".substages."requirements".done')" = "true" ] || fail "requirements substage 미완료"
-
-if [ "$(q '.policy.auto_approve."1_planning.requirements"')" != "true" ]; then
-  [ "$(q '.stages."1_planning".substages."requirements".approved_by_user')" = "true" ] \
-    || fail "requirements substage 사용자 승인 없음 (또는 .policy.auto_approve.\"1_planning.requirements\" 미설정)"
-  if [ "$(q '.stages."1_planning".substages."requirements".verification_pending')" = "true" ]; then
-    fail "requirements substage 검증 대기 중 (verification_pending) — 사용자 승인 후 approved_by_user를 기록하라"
-  fi
-fi
-
-if [ "$(q '.stages."1_planning".substages."requirements".interview_required')" = "true" ]; then
-  [ "$(q '.stages."1_planning".substages."requirements".interview_completed')" = "true" ] \
-    || fail "requirements substage 인터뷰 미완료 — 모든 미결 항목 해소 후 interview_completed=true 기록 필요"
-fi
-
-# --- 요구사항 품질 게이트 (조건부 — 마커 존재 시에만 검사, 구형 state 호환) ---
-# 1) Ambiguity Score 수렴: 기록된 값이 0.2 초과면 요구사항 미수렴 (stages/02-requirements.md §2-3-2b)
-AMB="$(q '.stages."1_planning".substages."requirements".ambiguity_score')"
-if [ "$AMB" != "__MISSING__" ] && [ "$AMB" != "null" ] && [ -n "$AMB" ]; then
-  awk -v a="$AMB" 'BEGIN { exit (a + 0 <= 0.2) ? 0 : 1 }' \
-    || fail "ambiguity_score=$AMB > 0.2 — 요구사항 미수렴. 인터뷰로 미결 항목 해소 후 재산정하라"
-fi
-
-# 2) 명세 동결(spec drift) 검증: spec_hash 기록 시 draft 파일 해시 재계산 일치 필요 (§2-4a)
-SPEC_HASH="$(q '.stages."1_planning".substages."requirements".spec_hash')"
-if [ "$SPEC_HASH" != "__MISSING__" ] && [ "$SPEC_HASH" != "null" ] && [ -n "$SPEC_HASH" ]; then
-  DRAFT="$(q '.stages."1_planning".substages."requirements".draft_path')"
-  ROOT="$("$HERE/../scripts/state.sh" root)"
-  # 마커 누락과 파일 부재를 구분해서 알린다. 종전에는 둘 다 "확정 명세 파일 없음" 으로
-  # 뭉뚱그려서, 파일은 멀쩡히 있고 마커만 빠진 흔한 경우(issue #6-①)에 무엇을 해야
-  # 하는지 알 수 없었다. 마커 기록은 team-leader 에게 허용된 state.sh set 경로다.
-  DEFAULT_DRAFT=".makdoong2-team/${ISSUE}/requirements-draft.md"
-  if [ "$DRAFT" = "__MISSING__" ] || [ "$DRAFT" = "null" ] || [ -z "$DRAFT" ]; then
-    if [ -f "$ROOT/$DEFAULT_DRAFT" ]; then
-      fail "spec_hash 는 기록됐는데 draft_path 마커가 없다 — 파일은 ${DEFAULT_DRAFT} 에 있다.
-  복구: (1) sha256sum \"${ROOT}/${DEFAULT_DRAFT}\" 가 spec_hash(${SPEC_HASH}) 와 같은지 대조하고,
-        (2) 같으면 state.sh set 으로 requirements.draft_path 에 \"${DEFAULT_DRAFT}\" 를 기록한다 (stages/02-requirements.md §2-0),
-        (3) 다르면 명세가 동결 후 변경된 것이므로 requirements substage 를 재작업한다 (§2-4a)."
-    fi
-    fail "spec_hash 는 기록됐는데 draft_path 마커도 확정 명세 파일도 없다 — requirements substage 를 재작업하라 (stages/02-requirements.md §2-0, §2-5 9번)"
-  fi
-  # "생성된 적 없음" 을 안내에서 빼면 복구 방향을 잘못 잡는다 — 실제로 가장 흔한
-  # 경우인데 종전 메시지는 동기화 누락·삭제만 언급해 리더가 동기화 문제부터
-  # 의심했다 (issue #8).
-  [ -f "$ROOT/$DRAFT" ] \
-    || fail "draft_path=${DRAFT} 마커는 있으나 파일이 없다 (기준 경로 ${ROOT}). 가능한 원인 순서대로:
-  (1) 애초에 생성된 적 없음 — planner 가 마커만 기록하고 파일 생성에 실패한 경우. requirements substage 를 재작업해 write 툴로 초안부터 생성하라 (stages/02-requirements.md §2-0b),
-  (2) worktree 동기화 누락 — 다른 cwd(main repo/worktree)의 같은 상대경로에 파일이 있는지 확인,
-  (3) 파일이 삭제됨 — 삭제 경위 확인 후 requirements 재작업"
-  ACTUAL="$(sha256sum "$ROOT/$DRAFT" | cut -d' ' -f1)"
-  [ "$ACTUAL" = "$SPEC_HASH" ] \
-    || fail "확정 명세 무단 변경 감지 (spec drift) — 동결 후 변경은 사용자 재승인 + spec_hash 재기록 절차만 허용 (stages/02-requirements.md §2-4a)"
-fi
-echo "MAKDOONG2-GATE OK: 1_planning.scope"

package/stages/03-scope.md

@@ -1,81 +0,0 @@
-# 3단계: 개발 범위 파악
-
-**목적**: 어떤 코드를 어떻게 고칠지 범위를 확정한다.
-**진입 게이트**: `verify.sh <이슈키> 1_planning.scope` (2단계 완료 + 사용자 승인 필요).
-
-> `<SCRIPTS_DIR>`는 부장님이 dispatch_stage 프롬프트로 주입한 절대경로다. 이 값을 그대로 대입하여 실행한다.
-
-2단계 조사 결과로 코드 수정 계획을 수립한다. 2단계에서 `bitbucket-research`로 코드 탐색을 이미 했으므로 본 단계는 **변경 단위 확정**에 집중한다.
-
-## 출력 형식
-
-```
-### 개발 범위
-**수정 파일**: <path>: <변경 요지> ...
-**추가 파일**: <path>: <목적> ...
-**테스트 범위**: 단위(대상 클래스/메서드), 통합(빌드 플랜명/시나리오)
-**영향 범위**: <모듈/시스템>: <영향 요지> ...
-**예상 작업 단위(커밋 후보)**: 1. <단위1> 2. <단위2> ...
-**2단계에서 확정한 가정**: <가정1> ...
-```
-
-## 범주 재평가 (escalation — 하향 금지)
-
-실제 수정/추가 파일과 작업 단위가 확정된 뒤, 2단계(§2-4b)가 추정으로 기록한 `.policy.scope_size`·`.policy.criticality`를 **재평가**한다. 2단계 추정은 명세 기준 추정치이므로, 본 단계에서 코드 변경 단위가 드러난 직후가 유일한 정정 시점이다.
-
-| 차원 | 재평가 기준 |
-|---|---|
-| `scope_size` | 확정된 수정/추가 파일 수·작업 단위(커밋 후보)·영향 모듈이 다수에 걸치면 `large` |
-| `criticality` | 인증·결제·보안·데이터 무결성·마이그레이션·대외 API 등 실패 시 파급이 큰 영역이 실제 변경에 포함되면 `critical` |
-
-도출 규칙은 2-4b와 동일하다: `criticality == "critical" OR scope_size == "large"`이면 `category`는 **major**.
-
-- 2단계에서 **minor**였으나 위 재평가로 `large` 또는 `critical`이 확정되면 **major로 상향(escalation)** 한다. 상향은 위험도 라벨 정정에 그치며 `auto_approve` 맵은 건드리지 않는다 — 흐름은 여전히 무인 진행이다:
-  ```bash
-  bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy.category' '"major"'
-  bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy.scope_size' '"large"'   # 또는 criticality
-  bash <SCRIPTS_DIR>/state.sh set <이슈키> '.policy.categorized_by' '"1_planning.scope"'
-  ```
-  `auto_approve` 는 그대로 두므로 게이트는 무인 통과한다. HITL 이 필요한 특수 상황(예: 이슈 유형별 opt-in 정책)에서만 별도 지시로 `auto_approve."3_delivery.commit"` 를 `false` 로 재설정할 수 있다. 이 경우 커밋 직전 변경 보고서(`change-report.md`) + 사용자 승인이 요구된다(6단계 §6-0).
-- **상향만 허용한다. major → minor 하향은 절대 금지.** 이미 major면 그대로 둔다.
-- 재평가 결과 변동이 없으면(여전히 minor·동일 범주) `.policy`를 건드리지 않는다.
-
-## 최종 자가 검증 (Pre-Completion Checklist)
-
-`done=true` 직전, 다음 5항목을 자체 확인하고 state.json에 결과를 기록한다.
-하나라도 false면 완료 기록 금지.
-
-| 항목 | 확인 |
-|---|---|
-| 1 | 수정/추가 파일이 모두 절대경로(또는 명확한 상대경로)로 명시되었다 |
-| 2 | 테스트 범위(단위 클래스/메서드 + 통합 시나리오)가 함께 정의되었다 |
-| 3 | 예상 작업 단위가 1 commit = 1 change 원칙에 맞게 쪼개졌다 |
-| 4 | 스코프 아웃(이번 이슈에서 다루지 않는 것)이 명시적으로 적혔다 |
-| 5 | 사용자 명시 승인("이대로 진행하세요" 등)을 받았다 |
-
-```bash
-bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."scope".self_check' \
-  '{"paths_explicit": true, "test_scope_defined": true, "atomic_units": true, "scope_out_listed": true, "user_approved": true}'
-```
-
-## 완료 기록
-
-```bash
-bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."scope".done' 'true'
-bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."scope".done_at' "\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\""
-```
-
-**승인 경로** — (위 escalation 반영 후) `.policy.auto_approve."1_planning.scope"`를 따른다:
-
-- **auto_approve == true** (정상 — minor/major 공통): 사람 대기 없이 자동 진행한다. `verification_pending`을 즉시 `false`로 둔다. 게이트(`stage4-dev-verify.sh`)가 정책을 보고 사용자 승인 없이 4단계로 통과시킨다.
-  ```bash
-  bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."scope".verification_pending' 'false'
-  ```
-- **auto_approve 미설정**(구형 state — 범주화 폴백): 기존대로 사용자가 "이대로 진행하세요" 같은 명시적 승인을 준 뒤에만 4단계로 넘어간다.
-  ```bash
-  bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."scope".verification_pending' 'true'
-  # 사용자 명시 승인 직후에만:
-  bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."scope".approved_by_user' 'true'
-  bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."scope".approved_at' "\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\""
-  bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."scope".verification_pending' 'false'
-  ```