onto-mcp 0.3.0

package/dist/core-runtime/evolve/renderers/draft-packet.test.js

@@ -0,0 +1,377 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { renderDraftPacket } from "./draft-packet.js";
+import { reduce } from "../../scope-runtime/reducer.js";
+// ─── Helpers ───
+function emptyPool() {
+    return { constraints: [], summary: { total: 0, required: 0, recommended: 0, decided: 0, clarify_pending: 0, invalidated: 0, undecided: 0 } };
+}
+function makeEntry(id, overrides = {}) {
+    return {
+        constraint_id: id, perspective: "code", summary: `summary ${id}`,
+        severity: "recommended", discovery_stage: "draft_phase2", decision_owner: "product_owner",
+        impact_if_ignored: `impact ${id}`, source_refs: [{ source: "t.ts", detail: "d" }],
+        evidence_status: "unverified",
+        status: "undecided", discovered_at: 1, ...overrides,
+    };
+}
+function makePoolWith(...entries) {
+    let req = 0, rec = 0, inv = 0;
+    for (const e of entries) {
+        if (e.severity === "required")
+            req++;
+        else
+            rec++;
+        if (e.status === "invalidated")
+            inv++;
+    }
+    return { constraints: entries, summary: { total: entries.length, required: req, recommended: rec, decided: 0, clarify_pending: 0, invalidated: inv, undecided: entries.length - inv } };
+}
+function makeState(overrides = {}) {
+    return {
+        scope_id: "SC-TEST", title: "테스트", description: "d", entry_mode: "experience",
+        current_state: "surface_confirmed", constraint_pool: emptyPool(),
+        stale: false, compile_ready: false, convergence_blocked: false,
+        revision_count_align: 0, revision_count_surface: 0, retry_count_compile: 0,
+        snapshot_revision: 0, pre_apply_completed: false, prd_review_completed: false,
+        verdict_log: [], feedback_history: [], latest_revision: 0, ...overrides,
+    };
+}
+function makeContent(overrides = {}) {
+    return {
+        surface_path: "surface/preview/", scenario_guide: [],
+        constraint_details: [], guardrails: [], decision_questions: [], ...overrides,
+    };
+}
+function poDet(id) {
+    return {
+        constraint_id: id, decision_owner: "product_owner", situation: `situation ${id}`,
+        options_table: [{ choice: "inject", pros: "빠른 적용", description: "desc", risk: "low", reversal_cost: "낮음" }],
+        recommendation: "inject 추천",
+    };
+}
+function builderDet(id) {
+    return {
+        constraint_id: id, decision_owner: "builder", situation: `situation ${id}`,
+        builder_decision: "DB 테이블 생성", builder_judgment: "필수. 되돌림 비용 낮음",
+    };
+}
+// ─── Golden data ───
+describe("draft-packet — golden data structure", () => {
+    it("renders Draft Packet matching golden structure", () => {
+        const goldenPath = resolve(import.meta.dirname, "../../scope-runtime/__fixtures__/example-tutor-block/events.ndjson");
+        const events = readFileSync(goldenPath, "utf-8").trimEnd().split("\n").map((l) => JSON.parse(l));
+        // State at surface_confirmed + all constraints discovered (first 18 events)
+        const state = reduce(events.slice(0, 18));
+        const content = {
+            surface_path: "scopes/SC-2026-001/surface/preview/",
+            run_command: "cd surface/preview && npm run dev",
+            mockup_revisions: 3,
+            scenario_guide: [
+                { scenario: "차단 생성", start: "튜터 프로필", steps: "차단 버튼 → 확인", confirmed: "성공 메시지" },
+                { scenario: "차단 해제", start: "설정 → 차단 관리", steps: "해제 버튼 → 확인", confirmed: "목록에서 제거" },
+            ],
+            constraint_details: [
+                { constraint_id: "CST-001", decision_owner: "product_owner", situation: "매칭 시스템에 제외 기능 없음", options_table: [{ choice: "inject (제외 기능 추가)", pros: "완전한 차단", description: "매칭 시스템에 제외 기능 추가", risk: "가장 큰 변경", reversal_cost: "낮음" }], recommendation: "inject" },
+                { constraint_id: "CST-005", decision_owner: "builder", situation: "차단 정보 저장 공간 없음", builder_decision: "DB 테이블 신규 생성", builder_judgment: "필수. 되돌림 비용 낮음" },
+                { constraint_id: "CST-008", decision_owner: "product_owner", situation: "차단 남용 방지 한도 없음", options_table: [{ choice: "inject (언어별 5명)", pros: "남용 방지", description: "언어별 5명 제한", risk: "한도 낮음 불만", reversal_cost: "낮음" }], recommendation: "inject (언어별 5명)" },
+                { constraint_id: "CST-002", decision_owner: "product_owner", situation: "이용약관 충돌", options_table: [{ choice: "inject (예외 조항)", pros: "법적 안정", description: "약관 예외 추가", risk: "법무 비용", reversal_cost: "중간" }], recommendation: "clarify" },
+                { constraint_id: "CST-003", decision_owner: "product_owner", situation: "버튼 공간 부족", options_table: [{ choice: "inject (간격 확보)", pros: "UX 개선", description: "레이아웃 재배치", risk: "사용자 혼동", reversal_cost: "낮음" }], recommendation: "inject" },
+                { constraint_id: "CST-004", decision_owner: "product_owner", situation: "차단 관리 메뉴 위치", options_table: [{ choice: "defer (현재 유지)", pros: "변경 없음", description: "4번째 항목 유지", risk: "찾기 어려움", reversal_cost: "낮음" }], recommendation: "defer" },
+                { constraint_id: "CST-006", decision_owner: "builder", situation: "API 응답 변경 위험", builder_decision: "optional 필드 방식", builder_judgment: "호환성 유지. 비용 적음", guardrail: "기존 API 응답 형식을 깨지 않는다" },
+                { constraint_id: "CST-007", decision_owner: "product_owner", situation: "개인정보 삭제 의무", options_table: [{ choice: "inject (자동 삭제)", pros: "규정 준수", description: "3년 후 삭제", risk: "차단 자연 해제", reversal_cost: "낮음" }], recommendation: "inject" },
+            ],
+            guardrails: [
+                "기존 예약된 수업은 취소하지 않는다",
+                "차단 행위는 중복 요청 시 오류 없이 기존 상태를 유지한다",
+                "튜터에게 차단 사실을 알리지 않는다",
+                "기존 API 응답 형식을 깨지 않는다",
+            ],
+            decision_questions: [
+                "위 8건에 대해 각각 선택해 주세요",
+                "clarify를 선택한 항목은 해소될 때까지 잠글 수 없습니다",
+                "모든 결정이 완료되면 compile을 시작합니다",
+            ],
+        };
+        const md = renderDraftPacket(state, content);
+        // Section existence
+        expect(md).toContain("### 1. 확정된 Surface");
+        expect(md).toContain("### 2. 현재까지의 결정 현황");
+        expect(md).toContain("### 3. 결정이 필요한 항목");
+        expect(md).toContain("### 5. 제약 조건");
+        expect(md).toContain("### 6. 지금 결정할 것");
+        // CST tracking + severity
+        expect(md).toContain("CST-001");
+        expect(md).toContain("CST-008");
+        expect(md).toContain("필수");
+        expect(md).toContain("권장");
+        expect(md).toContain("(Builder 결정)");
+        // Impact from pool
+        expect(md).toContain("차단 버튼을 눌러도 실제 매칭에 반영되지 않습니다");
+        // Scenario table
+        expect(md).toContain("| 시나리오 | 시작 | 동작 순서 | 확인된 동작 |");
+        // Builder format
+        expect(md).toContain("Builder 결정 예정");
+        expect(md).toContain("guardrail 확인 후 승인");
+        // Decision choices
+        expect(md).toContain("**Approve**");
+    });
+});
+// ─── Section 2: auto-generated ───
+describe("draft-packet — Section 2 auto status", () => {
+    it("shows Align decisions from state", () => {
+        const state = makeState({ direction: "test direction", scope_boundaries: { in: ["A"], out: ["B"] } });
+        const md = renderDraftPacket(state, makeContent());
+        expect(md).toContain("방향 승인");
+        expect(md).toContain("범위 확정");
+    });
+    it("shows grounding CST IDs", () => {
+        const entries = [makeEntry("CST-001", { discovery_stage: "grounding" }), makeEntry("CST-002", { discovery_stage: "draft_phase2" })];
+        const state = makeState({ constraint_pool: makePoolWith(...entries) });
+        const md = renderDraftPacket(state, makeContent());
+        expect(md).toContain("CST-001 인지 완료");
+        expect(md).not.toContain("CST-002 인지 완료");
+    });
+    it("shows clarify lock warning", () => {
+        const pool = emptyPool();
+        pool.summary.clarify_pending = 2;
+        pool.summary.total = 5;
+        const md = renderDraftPacket(makeState({ constraint_pool: pool }), makeContent());
+        expect(md).toContain("2건");
+    });
+});
+// ─── Section 3: sorting ───
+describe("draft-packet — Section 3 sorting", () => {
+    it("sorts required before recommended", () => {
+        const e1 = makeEntry("CST-002", { severity: "recommended" });
+        const e2 = makeEntry("CST-001", { severity: "required" });
+        const state = makeState({ constraint_pool: makePoolWith(e1, e2) });
+        const content = makeContent({ constraint_details: [poDet("CST-002"), poDet("CST-001")] });
+        const md = renderDraftPacket(state, content);
+        const idx001 = md.indexOf("CST-001");
+        const idx002 = md.indexOf("CST-002");
+        expect(idx001).toBeLessThan(idx002);
+    });
+});
+// ─── Section 3: PO vs Builder ───
+describe("draft-packet — Section 3 PO/Builder detail", () => {
+    it("renders PO detail with options table", () => {
+        const entry = makeEntry("CST-001");
+        const state = makeState({ constraint_pool: makePoolWith(entry) });
+        const content = makeContent({ constraint_details: [poDet("CST-001")] });
+        const md = renderDraftPacket(state, content);
+        expect(md).toContain("| 선택 | 이점 | 내용 | 리스크 | 되돌림 비용 |");
+        expect(md).toContain("추천:");
+        expect(md).toContain("선택: ___");
+    });
+    it("renders Builder detail with builder_decision", () => {
+        const entry = makeEntry("CST-001", { decision_owner: "builder" });
+        const state = makeState({ constraint_pool: makePoolWith(entry) });
+        const content = makeContent({ constraint_details: [builderDet("CST-001")] });
+        const md = renderDraftPacket(state, content);
+        expect(md).toContain("**Builder가 결정할 사항:**");
+        expect(md).toContain("Builder 결정 예정");
+    });
+    it("renders Builder without guardrail — '제품 관점 제약 조건 없음'", () => {
+        const entry = makeEntry("CST-001", { decision_owner: "builder" });
+        const state = makeState({ constraint_pool: makePoolWith(entry) });
+        const md = renderDraftPacket(state, makeContent({ constraint_details: [builderDet("CST-001")] }));
+        expect(md).toContain("제품 관점 제약 조건 없음");
+        expect(md).not.toContain("위 guardrail 확인 후 승인");
+    });
+    it("renders Builder guardrail when present", () => {
+        const entry = makeEntry("CST-001", { decision_owner: "builder" });
+        const state = makeState({ constraint_pool: makePoolWith(entry) });
+        const det = builderDet("CST-001");
+        det.guardrail = "API 호환성 유지";
+        const md = renderDraftPacket(state, makeContent({ constraint_details: [det] }));
+        expect(md).toContain("**guardrail:** API 호환성 유지");
+    });
+    it("uses pool impact_if_ignored for '처리하지 않으면'", () => {
+        const entry = makeEntry("CST-001", { impact_if_ignored: "big problem" });
+        const state = makeState({ constraint_pool: makePoolWith(entry) });
+        const md = renderDraftPacket(state, makeContent({ constraint_details: [poDet("CST-001")] }));
+        expect(md).toContain("**처리하지 않으면:** big problem");
+    });
+});
+// ─── Section 4: invalidated ───
+describe("draft-packet — Section 4 invalidated", () => {
+    it("omits section when no invalidated", () => {
+        const md = renderDraftPacket(makeState(), makeContent());
+        expect(md).not.toContain("### 4.");
+    });
+    it("shows invalidated constraints", () => {
+        const entry = makeEntry("CST-003", { status: "invalidated" });
+        const state = makeState({ constraint_pool: makePoolWith(entry) });
+        const md = renderDraftPacket(state, makeContent());
+        expect(md).toContain("### 4. 시스템이 제외한 항목");
+        expect(md).toContain("CST-003");
+        expect(md).toContain("복원");
+    });
+    it("shows required invalidated warning", () => {
+        const entry = makeEntry("CST-001", { status: "invalidated", severity: "required" });
+        const state = makeState({ constraint_pool: makePoolWith(entry) });
+        const md = renderDraftPacket(state, makeContent());
+        expect(md).toContain("기능 불능 또는 규정 위반");
+        expect(md).toContain("제외에 동의하시나요");
+    });
+});
+// ─── Section 5: guardrails ───
+describe("draft-packet — Section 5 guardrails", () => {
+    it("renders guardrail bullets", () => {
+        const md = renderDraftPacket(makeState(), makeContent({ guardrails: ["규칙1", "규칙2"] }));
+        expect(md).toContain("- 규칙1");
+        expect(md).toContain("- 규칙2");
+    });
+});
+// ─── Section 6: decision ───
+describe("draft-packet — Section 6 decision", () => {
+    it("shows approve-only when no constraints", () => {
+        const md = renderDraftPacket(makeState(), makeContent());
+        expect(md).toContain("Approve만 선택");
+    });
+    it("shows full choices with constraint questions", () => {
+        const entry = makeEntry("CST-001");
+        const state = makeState({ constraint_pool: makePoolWith(entry) });
+        const md = renderDraftPacket(state, makeContent({
+            constraint_details: [poDet("CST-001")],
+            decision_questions: ["8건에 대해 선택해 주세요"],
+        }));
+        expect(md).toContain("각 CST 결정");
+        expect(md).toContain("compile을 시작합니다");
+    });
+    it("shows clarify warning when pending", () => {
+        const pool = emptyPool();
+        pool.summary.clarify_pending = 1;
+        pool.summary.total = 1;
+        const entry = makeEntry("CST-001");
+        pool.constraints = [entry];
+        const state = makeState({ constraint_pool: pool });
+        const md = renderDraftPacket(state, makeContent({
+            constraint_details: [poDet("CST-001")],
+            decision_questions: ["선택하세요"],
+        }));
+        expect(md).toContain("clarify");
+        expect(md).toContain("잠글 수 없습니다");
+    });
+});
+// ─── Edge cases: empty and undefined fields ───
+describe("draft-packet — empty/undefined edge cases", () => {
+    it("renders with empty scenario_guide (no table)", () => {
+        const md = renderDraftPacket(makeState(), makeContent({ scenario_guide: [] }));
+        expect(md).toContain("### 1. 확정된 Surface");
+        expect(md).not.toContain("| 시나리오 | 시작 |");
+    });
+    it("renders '없음' when guardrails is empty", () => {
+        const md = renderDraftPacket(makeState(), makeContent({ guardrails: [] }));
+        expect(md).toContain("없음");
+    });
+    it("omits run_command when undefined", () => {
+        const md = renderDraftPacket(makeState(), makeContent({
+            run_command: undefined,
+        }));
+        expect(md).not.toContain("**실행 방법**");
+    });
+    it("omits mockup_revisions when undefined", () => {
+        const md = renderDraftPacket(makeState(), makeContent({
+            mockup_revisions: undefined,
+        }));
+        expect(md).not.toContain("mockup 반복");
+    });
+    it("renders run_command when provided", () => {
+        const md = renderDraftPacket(makeState(), makeContent({
+            run_command: "npm run dev",
+        }));
+        expect(md).toContain("`npm run dev`");
+    });
+    it("renders mockup_revisions when provided", () => {
+        const md = renderDraftPacket(makeState(), makeContent({
+            mockup_revisions: 5,
+        }));
+        expect(md).toContain("5회 수정 후 주체자 확정");
+    });
+});
+// ─── Validation ───
+describe("draft-packet — validation", () => {
+    it("throws when constraint_id not in pool", () => {
+        expect(() => renderDraftPacket(makeState(), makeContent({
+            constraint_details: [poDet("CST-MISSING")],
+        }))).toThrow("CST-MISSING");
+    });
+    it("throws when decision_owner mismatch", () => {
+        const entry = makeEntry("CST-001", { decision_owner: "builder" });
+        const state = makeState({ constraint_pool: makePoolWith(entry) });
+        expect(() => renderDraftPacket(state, makeContent({
+            constraint_details: [poDet("CST-001")], // PO detail for builder constraint
+        }))).toThrow("decision_owner");
+    });
+});
+// ─── Section 2: source consistency (content.constraint_details canonical) ───
+describe("draft-packet — Section 2 source consistency", () => {
+    it("Section 2 active count matches content.constraint_details length, not pool.summary.total", () => {
+        // pool에 3건 있지만 content에는 2건만 — Section 3에 실제 보이는 수와 일치해야 함
+        const e1 = makeEntry("CST-001");
+        const e2 = makeEntry("CST-002");
+        const e3 = makeEntry("CST-003");
+        const state = makeState({ constraint_pool: makePoolWith(e1, e2, e3) });
+        const content = makeContent({ constraint_details: [poDet("CST-001"), poDet("CST-002")] });
+        const md = renderDraftPacket(state, content);
+        expect(md).toContain("아래 2건");
+        expect(md).not.toContain("아래 3건");
+    });
+    it("decided/undecided counts derive from pool lookup of detail ids", () => {
+        const e1 = makeEntry("CST-001", { status: "decided", decision: "inject" });
+        const e2 = makeEntry("CST-002", { status: "undecided" });
+        const state = makeState({ constraint_pool: makePoolWith(e1, e2) });
+        const content = makeContent({ constraint_details: [poDet("CST-001"), poDet("CST-002")] });
+        const md = renderDraftPacket(state, content);
+        expect(md).toContain("1건 결정 완료, 1건 미결정");
+    });
+    it("clarify_pending detail counts into '미결정' group", () => {
+        const e1 = makeEntry("CST-001", { status: "clarify_pending" });
+        const state = makeState({ constraint_pool: makePoolWith(e1) });
+        const content = makeContent({ constraint_details: [poDet("CST-001")] });
+        const md = renderDraftPacket(state, content);
+        expect(md).toContain("0건 결정 완료, 1건 미결정");
+    });
+});
+describe("draft-packet — validation (invalidated detail rejection)", () => {
+    it("throws when constraint_details references an invalidated constraint", () => {
+        const entry = makeEntry("CST-001", { status: "invalidated" });
+        const state = makeState({ constraint_pool: makePoolWith(entry) });
+        expect(() => renderDraftPacket(state, makeContent({
+            constraint_details: [poDet("CST-001")],
+        }))).toThrow("invalidated");
+    });
+});
+// ─── requires_policy_change rendering ───
+describe("draft-packet — requires_policy_change", () => {
+    it("shows policy tag and callout when requires_policy_change=true", () => {
+        const entry = makeEntry("CST-001", { requires_policy_change: true, decision: "inject", status: "decided" });
+        const state = makeState({ constraint_pool: makePoolWith(entry) });
+        const md = renderDraftPacket(state, makeContent({
+            constraint_details: [poDet("CST-001")],
+        }));
+        expect(md).toContain("[정책 변경 검토 필요]");
+        expect(md).toContain("정책 변경 전제");
+        expect(md).toContain("requires_policy_change=false");
+    });
+    it("no policy tag when requires_policy_change is false", () => {
+        const entry = makeEntry("CST-001", { requires_policy_change: false });
+        const state = makeState({ constraint_pool: makePoolWith(entry) });
+        const md = renderDraftPacket(state, makeContent({
+            constraint_details: [poDet("CST-001")],
+        }));
+        expect(md).not.toContain("[정책 변경 검토 필요]");
+        expect(md).not.toContain("정책 변경 전제");
+    });
+    it("no policy tag when requires_policy_change is undefined", () => {
+        const entry = makeEntry("CST-001"); // no requires_policy_change
+        const state = makeState({ constraint_pool: makePoolWith(entry) });
+        const md = renderDraftPacket(state, makeContent({
+            constraint_details: [poDet("CST-001")],
+        }));
+        expect(md).not.toContain("[정책 변경 검토 필요]");
+    });
+});

package/dist/core-runtime/evolve/renderers/format.js

@@ -0,0 +1,5 @@
+/**
+ * Re-export from kernel/types.ts for backward compatibility.
+ * Single source of truth is kernel/types.ts.
+ */
+export { formatPerspective } from "../../scope-runtime/types.js";

package/dist/core-runtime/evolve/renderers/scope-md.js

@@ -0,0 +1,237 @@
+import { isPolicyChangeRequired } from "../../scope-runtime/types.js";
+import { MAX_COMPILE_RETRIES } from "../../scope-runtime/constants.js";
+/**
+ * Render scope.md — the current status view of a scope.
+ *
+ * Pure function: (state) → string.
+ * No side effects, no external I/O.
+ */
+export function renderScopeMd(state) {
+    const lines = [];
+    // ── Header ──
+    lines.push(`# Scope: ${state.title}`);
+    lines.push("");
+    // ── Current stage ──
+    lines.push("## 현황");
+    lines.push("");
+    lines.push(`- **상태**: ${formatState(state.current_state)}`);
+    if (state.direction) {
+        lines.push(`- **방향**: ${state.direction}`);
+    }
+    lines.push(`- **마지막 업데이트**: revision ${state.latest_revision}`);
+    lines.push("");
+    // ── Blockers (only when present) ──
+    const blockers = collectBlockers(state);
+    if (blockers.length > 0) {
+        lines.push("## 차단 상태");
+        lines.push("");
+        for (const b of blockers) {
+            lines.push(`- ${b}`);
+        }
+        lines.push("");
+    }
+    // ── Next action ──
+    lines.push("## 다음 행동");
+    lines.push("");
+    lines.push(`- ${formatNextAction(state)}`);
+    lines.push("");
+    // ── Scope boundaries (if locked) ──
+    if (state.scope_boundaries) {
+        lines.push("## 범위");
+        lines.push("");
+        if (state.scope_boundaries.in.length > 0) {
+            lines.push("**포함:**");
+            for (const item of state.scope_boundaries.in) {
+                lines.push(`- ${item}`);
+            }
+            lines.push("");
+        }
+        if (state.scope_boundaries.out.length > 0) {
+            lines.push("**제외:**");
+            for (const item of state.scope_boundaries.out) {
+                lines.push(`- ${item}`);
+            }
+            lines.push("");
+        }
+    }
+    // ── Scanned sources ──
+    if (state.grounding_sources && state.grounding_sources.length > 0) {
+        lines.push("## 스캔 소스");
+        lines.push("");
+        for (const src of state.grounding_sources) {
+            lines.push(`- \`${src.type}\`: ${src.path_or_url}`);
+        }
+        lines.push("");
+    }
+    // ── Constraint summary ──
+    const { summary } = state.constraint_pool;
+    if (summary.total > 0) {
+        lines.push("## Constraint 현황");
+        lines.push("");
+        lines.push(`- 전체: ${summary.total}건 (필수 ${summary.required}, 권장 ${summary.recommended})`);
+        lines.push(`- 결정 완료: ${summary.decided}건`);
+        if (summary.undecided > 0) {
+            lines.push(`- 미결정: ${summary.undecided}건`);
+        }
+        if (summary.clarify_pending > 0) {
+            lines.push(`- clarify 대기: ${summary.clarify_pending}건`);
+        }
+        if (summary.invalidated > 0) {
+            lines.push(`- 제외됨: ${summary.invalidated}건`);
+        }
+        const policyChangeCount = state.constraint_pool.constraints.filter(isPolicyChangeRequired).length;
+        if (policyChangeCount > 0) {
+            lines.push(`- 정책 변경 검토 필요: ${policyChangeCount}건`);
+        }
+        lines.push("");
+    }
+    // ── Validation results ──
+    if (state.validation_result) {
+        const vr = state.validation_result;
+        lines.push("## 검증 결과");
+        lines.push("");
+        lines.push(`- **결과**: ${vr.result === "pass" ? "통과" : "실패"}`);
+        lines.push(`- **통과**: ${vr.pass_count}건, **실패**: ${vr.fail_count}건`);
+        if (vr.fail_count > 0 && vr.items.length > 0) {
+            const failItems = vr.items.filter(i => i.result === "fail");
+            for (const item of failItems) {
+                lines.push(`- ${item.val_id} (${item.related_cst}): ${item.detail}`);
+            }
+        }
+        lines.push("");
+    }
+    // ── Constraint decision details (#8) ──
+    const decidedConstraints = state.constraint_pool.constraints.filter(c => c.status === "decided");
+    if (decidedConstraints.length > 0) {
+        lines.push("<details>");
+        lines.push(`<summary>Constraint 결정 상세 (${decidedConstraints.length}건)</summary>`);
+        lines.push("");
+        lines.push("| CST-ID | 결정 | 선택 |");
+        lines.push("|--------|------|------|");
+        for (const c of decidedConstraints) {
+            lines.push(`| ${c.constraint_id} | ${c.decision ?? "-"} | ${c.selected_option ?? "-"} |`);
+        }
+        lines.push("");
+        lines.push("</details>");
+        lines.push("");
+    }
+    // ── Recent decisions ──
+    if (state.verdict_log.length > 0) {
+        lines.push("## 최근 결정");
+        lines.push("");
+        const recent = state.verdict_log.slice(-5);
+        for (const entry of recent) {
+            lines.push(`- ${formatVerdictEntry(entry)}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+// ─── Helpers ───
+const STATE_LABELS = {
+    draft: "초안 (소스 스캔 전)",
+    grounded: "소스 스캔 완료",
+    exploring: "요구사항 탐색 중",
+    align_proposed: "Align Packet 검토 중",
+    align_locked: "방향·범위 확정됨",
+    surface_iterating: "Surface 반복 수정 중",
+    surface_confirmed: "Surface 확정됨 — constraint 결정 필요",
+    constraints_resolved: "모든 constraint 결정 완료",
+    target_locked: "Target 잠김 — compile 진행 중",
+    compiled: "Build Spec 생성 완료",
+    applied: "구현 적용 완료 — 검증 대기",
+    validated: "검증 통과 — 종료 가능",
+    closed: "종료됨",
+    deferred: "보류됨",
+    rejected: "거절됨",
+};
+function formatState(state) {
+    return STATE_LABELS[state] ?? state;
+}
+function formatNextAction(state) {
+    if (state.stale) {
+        return "소스가 변경되었습니다. 재스캔이 필요합니다 (`/start`를 다시 실행하세요)";
+    }
+    if (state.convergence_blocked) {
+        return "수렴 차단 상태입니다. 다음 중 하나를 선택하세요: (1) 방향 변경 (`/align redirect`) (2) scope 축소 (`/align revise`) (3) scope 보류 (`scope.deferred`)";
+    }
+    switch (state.current_state) {
+        case "draft":
+            return "소스를 스캔하세요 (`/start`를 실행하세요)";
+        case "grounded":
+            return "스캔이 끝났습니다. 대화 에이전트가 주체자에게 선택지 기반 질문으로 방향·범위·제약을 확인한 뒤, 수렴된 답을 bounded evolve runtime input으로 제출하세요. Runtime이 constraint.discovered 이벤트 + align-packet.md + align.proposed 이벤트를 기록합니다.";
+        case "exploring": {
+            const ep = state.exploration_progress;
+            const phaseInfo = ep ? ` (Phase ${ep.current_phase}/6: ${ep.current_phase_name})` : "";
+            return `요구사항을 탐색하고 있습니다${phaseInfo}. 질문에 답하여 scope를 구체화하세요`;
+        }
+        case "align_proposed":
+            return "Align Packet을 읽고 방향과 범위를 확정하세요 (승인/수정/거절/재스캔 중 선택)";
+        case "align_locked":
+            return "방향이 확정되었습니다. 화면 설계를 시작하세요 (`/draft`를 실행하세요)";
+        case "surface_iterating":
+            return state.entry_mode === "experience"
+                ? "mockup을 확인하세요 (`cd surface/preview && npm run dev`). 수정이 필요하면 피드백을, 맞으면 '확정합니다'라고 말씀하세요"
+                : "API 명세를 확인하세요 (`surface/contract-diff/`). 수정이 필요하면 피드백을, 맞으면 '확정합니다'라고 말씀하세요";
+        case "surface_confirmed":
+            return state.constraint_pool.summary.undecided > 0
+                ? `${state.constraint_pool.summary.undecided}건의 제약 사항에 대해 결정이 필요합니다. 각 항목의 선택지를 검토하고 결정하세요`
+                : state.constraint_pool.summary.clarify_pending > 0
+                    ? `${state.constraint_pool.summary.clarify_pending}건의 확인이 필요합니다. 외부에서 정보를 확보한 뒤 \`/draft\`를 실행하여 결정을 제출하세요`
+                    : "모든 결정이 완료되었습니다. 확정을 진행합니다 (`/draft`를 실행하세요)";
+        case "constraints_resolved":
+            if (state.validation_result?.result === "fail") {
+                return "검증에서 실패한 항목이 있습니다. 해당 제약 사항을 재검토한 뒤 다시 구현 명세를 생성하세요 (`/draft`를 실행하세요)";
+            }
+            if (state.retry_count_compile > 0) {
+                return `compile 중 새 제약이 발견되었습니다 (재시도 ${state.retry_count_compile}회). 새 제약에 대해 결정한 뒤 진행하세요 (\`/draft\`를 실행하세요)`;
+            }
+            return "모든 제약 사항이 해결되었습니다. 구현 명세를 생성합니다 (`/draft`를 실행하세요)";
+        case "target_locked":
+            return "구현 명세(Build Spec)를 생성하고 있습니다";
+        case "compiled":
+            return "구현 명세가 완성되었습니다. Builder가 코드를 작성합니다";
+        case "applied":
+            return "코드 작성이 완료되었습니다. 검증을 진행합니다";
+        case "validated":
+            return "모든 검증을 통과했습니다. 결과를 확인하시고, 완료하려면 '완료'라고 말씀하세요";
+        case "closed":
+            return "이 scope는 완료되었습니다";
+        case "deferred":
+            return "이 scope는 보류 중입니다";
+        case "rejected":
+            return "이 scope는 거절되었습니다";
+        default:
+            return `현재 상태: ${state.current_state}`;
+    }
+}
+function collectBlockers(state) {
+    const blockers = [];
+    if (state.stale) {
+        const sources = state.stale_sources?.map((s) => s.path).join(", ") ?? "알 수 없음";
+        blockers.push(`소스가 변경되었습니다: ${sources} (revision ${state.stale_since ?? "?"}부터)`);
+    }
+    if (state.convergence_blocked) {
+        blockers.push("수렴 차단: revise가 차단되었습니다. 행동을 선택해야 합니다");
+    }
+    if (state.constraint_pool.summary.clarify_pending > 0) {
+        blockers.push(`clarify 미해소: ${state.constraint_pool.summary.clarify_pending}건. 해소 전까지 target 잠금 불가`);
+    }
+    if (state.current_state === "constraints_resolved" && state.retry_count_compile > 0) {
+        blockers.push(`compile 중 새 제약이 발견되어 결정이 필요합니다 (재시도 ${state.retry_count_compile}/${MAX_COMPILE_RETRIES}회)`);
+    }
+    if (state.last_backward_reason) {
+        blockers.push(`이전 단계 복귀 사유: ${state.last_backward_reason}`);
+    }
+    return blockers;
+}
+function formatVerdictEntry(entry) {
+    switch (entry.type) {
+        case "align.locked":
+            return `rev ${entry.revision}: 방향 확정 — "${entry.locked_direction}"`;
+        case "constraint.decision_recorded":
+            return `rev ${entry.revision}: ${entry.constraint_id} → ${entry.decision} (${entry.decision_owner})`;
+        case "constraint.clarify_resolved":
+            return `rev ${entry.revision}: ${entry.constraint_id} clarify 해소 → ${entry.decision} (${entry.decision_owner})`;
+    }
+}