onto-mcp 0.3.0

package/dist/core-runtime/evolve/commands/apply.js

@@ -0,0 +1,161 @@
+/**
+ * /apply command orchestration.
+ *
+ * State-dependent behavior:
+ * - compiled → apply.started (start applying delta-set)
+ * - compiled → apply.completed (delta-set applied successfully)
+ * - compiled → apply.decision_gap_found (edge case found during apply → constraints_resolved)
+ * - applied → validation.started (begin validation)
+ * - applied → validation.completed (validate() + record result)
+ *
+ * Apply and validation are agent-driven.
+ * This module provides the event recording orchestration.
+ */
+import { readEvents } from "../../scope-runtime/event-store.js";
+import { reduce } from "../../scope-runtime/reducer.js";
+import { appendScopeEvent } from "../../scope-runtime/event-pipeline.js";
+import { wrapGateError } from "./error-messages.js";
+import { refreshScopeMd } from "./shared.js";
+import { validate } from "../adapters/code-product/validators/validate.js";
+import { loadProjectConfig } from "../config/project-config.js";
+// ─── Main ───
+export function executeApply(paths, action, options) {
+    switch (action.type) {
+        case "start_apply":
+            return handleStartApply(paths, action, options?.projectRoot);
+        case "complete_apply":
+            return handleCompleteApply(paths, action);
+        case "report_gap":
+            return handleReportGap(paths, action);
+        case "start_validation":
+            return handleStartValidation(paths, action);
+        case "complete_validation":
+            return handleCompleteValidation(paths, action);
+    }
+}
+// ─── Action Handlers ───
+// Note: apply.started is a self-transition (compiled → compiled).
+// If the process is interrupted before complete_apply, this event can be
+// re-recorded on resume without state corruption. Duplicate self-transitions are acceptable.
+function handleStartApply(paths, action, projectRoot) {
+    const config = projectRoot ? loadProjectConfig(projectRoot) : { default_sources: [] };
+    const result = appendScopeEvent(paths, {
+        type: "apply.started",
+        actor: "agent",
+        payload: { build_spec_hash: action.buildSpecHash },
+    }, { apply_enabled: config.apply_enabled });
+    if (!result.success)
+        return { success: false, reason: wrapGateError(result.reason) };
+    refreshScopeMd(paths, result.state);
+    return {
+        success: true,
+        nextState: result.next_state,
+        message: "Apply가 시작되었습니다. delta-set의 변경 사항을 적용하세요.",
+    };
+}
+function handleCompleteApply(paths, action) {
+    const result = appendScopeEvent(paths, {
+        type: "apply.completed",
+        actor: "agent",
+        payload: { result: action.result },
+    });
+    if (!result.success)
+        return { success: false, reason: wrapGateError(result.reason) };
+    refreshScopeMd(paths, result.state);
+    return {
+        success: true,
+        nextState: result.next_state,
+        message: "구현이 완료되었습니다. validation을 시작하세요.",
+    };
+}
+function handleReportGap(paths, action) {
+    // 1. constraint.discovered 먼저 기록 (참조 무결성)
+    const discoverResult = appendScopeEvent(paths, {
+        type: "constraint.discovered",
+        actor: "system",
+        payload: action.constraintPayload,
+    });
+    if (!discoverResult.success)
+        return { success: false, reason: wrapGateError(discoverResult.reason) };
+    // 2. apply.decision_gap_found 기록 → constraints_resolved로 역전이
+    const gapResult = appendScopeEvent(paths, {
+        type: "apply.decision_gap_found",
+        actor: "agent",
+        payload: action.gapPayload,
+    });
+    if (!gapResult.success)
+        return { success: false, reason: wrapGateError(gapResult.reason) };
+    refreshScopeMd(paths, gapResult.state);
+    return {
+        success: true,
+        nextState: gapResult.next_state,
+        message: `Gap이 발견되었습니다 (${action.gapPayload.new_constraint_id}). Draft에서 재결정 후 재compile이 필요합니다.`,
+    };
+}
+// Note: validation.started is a self-transition (applied → applied).
+// Same resilience pattern as apply.started above.
+function handleStartValidation(paths, action) {
+    const result = appendScopeEvent(paths, {
+        type: "validation.started",
+        actor: "agent",
+        payload: { validation_plan_hash: action.validationPlanHash },
+    });
+    if (!result.success)
+        return { success: false, reason: wrapGateError(result.reason) };
+    refreshScopeMd(paths, result.state);
+    return {
+        success: true,
+        nextState: result.next_state,
+        message: "Validation이 시작되었습니다. 각 VAL 항목을 검증하세요.",
+    };
+}
+function handleCompleteValidation(paths, action) {
+    // 1. validate() 순수 함수 호출
+    const state = reduce(readEvents(paths.events));
+    const validateOutput = validate({
+        state,
+        plan: action.plan,
+        results: action.results,
+        actualPlanHash: action.actualPlanHash,
+    });
+    if (!validateOutput.success) {
+        return { success: false, reason: wrapGateError(validateOutput.reason) };
+    }
+    // 2. validation.completed 이벤트 기록
+    const result = appendScopeEvent(paths, {
+        type: "validation.completed",
+        actor: "agent",
+        payload: {
+            result: validateOutput.result,
+            pass_count: validateOutput.pass_count,
+            fail_count: validateOutput.fail_count,
+            items: validateOutput.items,
+        },
+    });
+    if (!result.success)
+        return { success: false, reason: wrapGateError(result.reason) };
+    refreshScopeMd(paths, result.state);
+    if (validateOutput.result === "pass") {
+        return {
+            success: true,
+            nextState: result.next_state,
+            message: "모든 검증이 통과했습니다. 결과를 확인하시고, 종료하려면 '완료'라고 말씀해 주세요.",
+            data: {
+                result: validateOutput.result,
+                pass_count: validateOutput.pass_count,
+                fail_count: validateOutput.fail_count,
+            },
+        };
+    }
+    return {
+        success: true,
+        nextState: result.next_state,
+        message: `검증 실패: ${validateOutput.fail_count}건. 해당 constraint에 대해 재결정이 필요합니다.`,
+        data: {
+            result: validateOutput.result,
+            pass_count: validateOutput.pass_count,
+            fail_count: validateOutput.fail_count,
+        },
+    };
+}
+// refreshScopeMd is imported from ./shared.ts (UF-CONCISENESS-SCOPE-MD consolidated)

package/dist/core-runtime/evolve/commands/apply.test.js

@@ -0,0 +1,138 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { executeApply } from "./apply.js";
+import { createScope } from "../../scope-runtime/scope-manager.js";
+import { appendScopeEvent } from "../../scope-runtime/event-pipeline.js";
+import { readEvents } from "../../scope-runtime/event-store.js";
+import { reduce } from "../../scope-runtime/reducer.js";
+let tmpDir;
+beforeEach(() => { tmpDir = mkdtempSync(join(tmpdir(), "sprint-apply-")); });
+afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+/** Set up scope through compiled state */
+function setupCompiled() {
+    writeFileSync(join(tmpDir, ".sprint-kit.yaml"), "apply_enabled: true\ndefault_sources: []\n", "utf-8");
+    const paths = createScope(tmpDir, "SC-APPLY-001");
+    appendScopeEvent(paths, { type: "scope.created", actor: "user", payload: { title: "Test", description: "d", entry_mode: "experience" } });
+    appendScopeEvent(paths, { type: "grounding.started", actor: "system", payload: { sources: [{ type: "add-dir", path_or_url: "/test" }] } });
+    appendScopeEvent(paths, { type: "grounding.completed", actor: "system", payload: { snapshot_revision: 1, source_hashes: { "add-dir:/test": "h1" }, perspective_summary: { experience: 1, code: 1, policy: 1 } } });
+    appendScopeEvent(paths, { type: "align.proposed", actor: "system", payload: { packet_path: "build/align-packet.md", packet_hash: "h", snapshot_revision: 1 } });
+    appendScopeEvent(paths, { type: "align.locked", actor: "user", payload: { locked_direction: "test", locked_scope_boundaries: { in: ["a"], out: ["b"] }, locked_in_out: true } });
+    appendScopeEvent(paths, { type: "surface.generated", actor: "system", payload: { surface_type: "experience", surface_path: "surface/preview/", content_hash: "sf1", based_on_snapshot: 1 } });
+    appendScopeEvent(paths, { type: "surface.confirmed", actor: "user", payload: { final_surface_path: "surface/preview/", final_content_hash: "sf1", total_revisions: 0 } });
+    appendScopeEvent(paths, { type: "constraint.discovered", actor: "system", payload: { constraint_id: "CST-001", perspective: "code", summary: "test constraint", severity: "required", discovery_stage: "draft_phase2", decision_owner: "product_owner", impact_if_ignored: "fails", source_refs: [{ source: "test.ts", detail: "d" }] } });
+    appendScopeEvent(paths, { type: "constraint.decision_recorded", actor: "user", payload: { constraint_id: "CST-001", decision: "inject", selected_option: "fix", decision_owner: "product_owner", rationale: "필수" } });
+    appendScopeEvent(paths, { type: "target.locked", actor: "system", payload: { surface_hash: "sf1", constraint_decisions: [{ constraint_id: "CST-001", decision: "inject" }] } });
+    appendScopeEvent(paths, { type: "compile.started", actor: "system", payload: { snapshot_revision: 1, surface_hash: "sf1" } });
+    appendScopeEvent(paths, { type: "compile.completed", actor: "system", payload: { build_spec_path: "build/build-spec.md", build_spec_hash: "bs1", brownfield_detail_path: "build/brownfield-detail.md", brownfield_detail_hash: "bf1", delta_set_path: "build/delta-set.json", delta_set_hash: "ds1", validation_plan_path: "build/validation-plan.md", validation_plan_hash: "vp1" } });
+    appendScopeEvent(paths, { type: "pre_apply.review_completed", actor: "agent", payload: { verdict: "pass", findings: [] } });
+    appendScopeEvent(paths, { type: "prd.review_completed", actor: "agent", payload: { verdict: "pass", perspectives: ["prd_logic", "prd_structure", "prd_dependency", "prd_semantics", "prd_pragmatics", "prd_evolution", "prd_coverage", "prd_conciseness"], findings: [] } });
+    return paths;
+}
+/** Set up scope through applied state */
+function setupApplied() {
+    const paths = setupCompiled();
+    appendScopeEvent(paths, { type: "apply.started", actor: "agent", payload: { build_spec_hash: "bs1" } }, { apply_enabled: true });
+    appendScopeEvent(paths, { type: "apply.completed", actor: "agent", payload: { result: "success" } });
+    return paths;
+}
+describe("executeApply", () => {
+    it("start_apply → compiled (self transition)", () => {
+        const paths = setupCompiled();
+        const result = executeApply(paths, { type: "start_apply", buildSpecHash: "bs1" }, { projectRoot: tmpDir });
+        expect(result.success).toBe(true);
+        if (!result.success)
+            return;
+        expect(result.nextState).toBe("compiled");
+        const state = reduce(readEvents(paths.events));
+        expect(state.current_state).toBe("compiled");
+    });
+    it("complete_apply → applied", () => {
+        const paths = setupCompiled();
+        executeApply(paths, { type: "start_apply", buildSpecHash: "bs1" });
+        const result = executeApply(paths, { type: "complete_apply", result: "success" });
+        expect(result.success).toBe(true);
+        if (!result.success)
+            return;
+        expect(result.nextState).toBe("applied");
+        const state = reduce(readEvents(paths.events));
+        expect(state.current_state).toBe("applied");
+    });
+    it("full happy path: start → complete → validate → pass", () => {
+        const paths = setupCompiled();
+        // start_apply
+        const startResult = executeApply(paths, { type: "start_apply", buildSpecHash: "bs1" }, { projectRoot: tmpDir });
+        expect(startResult.success).toBe(true);
+        // complete_apply
+        const completeResult = executeApply(paths, { type: "complete_apply", result: "success" });
+        expect(completeResult.success).toBe(true);
+        // start_validation
+        const valStartResult = executeApply(paths, { type: "start_validation", validationPlanHash: "vp1" });
+        expect(valStartResult.success).toBe(true);
+        // complete_validation (pass)
+        const valCompleteResult = executeApply(paths, {
+            type: "complete_validation",
+            plan: [{ val_id: "VAL-001", related_cst: "CST-001", decision_type: "inject", target: "test.ts", method: "manual", pass_criteria: "works", fail_action: "fix" }],
+            results: [{ val_id: "VAL-001", related_cst: "CST-001", result: "pass", detail: "확인 완료" }],
+            actualPlanHash: "vp1",
+        });
+        expect(valCompleteResult.success).toBe(true);
+        if (!valCompleteResult.success)
+            return;
+        expect(valCompleteResult.nextState).toBe("validated");
+        const state = reduce(readEvents(paths.events));
+        expect(state.current_state).toBe("validated");
+    });
+    it("report_gap → constraints_resolved (backward transition)", () => {
+        const paths = setupCompiled();
+        executeApply(paths, { type: "start_apply", buildSpecHash: "bs1" });
+        const result = executeApply(paths, {
+            type: "report_gap",
+            constraintPayload: {
+                constraint_id: "CST-002",
+                perspective: "code",
+                summary: "edge case 발견",
+                severity: "required",
+                discovery_stage: "apply",
+                decision_owner: "product_owner",
+                impact_if_ignored: "data loss",
+                source_refs: [{ source: "handler.ts", detail: "line 42" }],
+            },
+            gapPayload: {
+                new_constraint_id: "CST-002",
+                description: "미결정 edge case 발견",
+            },
+        });
+        expect(result.success).toBe(true);
+        if (!result.success)
+            return;
+        expect(result.nextState).toBe("constraints_resolved");
+        const state = reduce(readEvents(paths.events));
+        expect(state.current_state).toBe("constraints_resolved");
+    });
+    it("validation fail → constraints_resolved", () => {
+        const paths = setupApplied();
+        // start_validation
+        executeApply(paths, { type: "start_validation", validationPlanHash: "vp1" });
+        // complete_validation (fail)
+        const result = executeApply(paths, {
+            type: "complete_validation",
+            plan: [{ val_id: "VAL-001", related_cst: "CST-001", decision_type: "inject", target: "test.ts", method: "manual", pass_criteria: "works", fail_action: "fix" }],
+            results: [{ val_id: "VAL-001", related_cst: "CST-001", result: "fail", detail: "구현 누락" }],
+            actualPlanHash: "vp1",
+        });
+        expect(result.success).toBe(true);
+        if (!result.success)
+            return;
+        expect(result.nextState).toBe("constraints_resolved");
+        expect(result.data?.result).toBe("fail");
+        const state = reduce(readEvents(paths.events));
+        expect(state.current_state).toBe("constraints_resolved");
+    });
+    it("start_apply fails when not in compiled state", () => {
+        const paths = setupApplied(); // already applied
+        const result = executeApply(paths, { type: "start_apply", buildSpecHash: "bs1" }, { projectRoot: tmpDir });
+        expect(result.success).toBe(false);
+    });
+});

package/dist/core-runtime/evolve/commands/close.js

@@ -0,0 +1,39 @@
+/**
+ * /close command orchestration.
+ *
+ * Closes a validated scope:
+ * - validated → scope.closed → closed
+ *
+ * Only allowed when current state is "validated".
+ */
+import { readEvents } from "../../scope-runtime/event-store.js";
+import { reduce } from "../../scope-runtime/reducer.js";
+import { appendScopeEvent } from "../../scope-runtime/event-pipeline.js";
+import { wrapGateError } from "./error-messages.js";
+import { refreshScopeMd } from "./shared.js";
+// ─── Main ───
+export function executeClose(paths) {
+    const events = readEvents(paths.events);
+    const state = reduce(events);
+    if (state.current_state !== "validated") {
+        return {
+            success: false,
+            reason: `현재 상태가 ${state.current_state}입니다. /close는 validated 상태에서만 실행할 수 있습니다.`,
+        };
+    }
+    const result = appendScopeEvent(paths, {
+        type: "scope.closed",
+        actor: "user",
+        payload: {},
+    });
+    if (!result.success)
+        return { success: false, reason: wrapGateError(result.reason) };
+    refreshScopeMd(paths, result.state);
+    return {
+        success: true,
+        nextState: "closed",
+        message: "Scope가 종료되었습니다.",
+    };
+}
+// refreshScopeMd is imported from ./shared.ts (UF-CONCISENESS-SCOPE-MD consolidated)
+// executeDefer lives in ./defer.ts so deferral has its own runtime adapter surface.

package/dist/core-runtime/evolve/commands/close.test.js

@@ -0,0 +1,99 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { executeClose } from "./close.js";
+import { createScope } from "../../scope-runtime/scope-manager.js";
+import { appendScopeEvent } from "../../scope-runtime/event-pipeline.js";
+import { readEvents } from "../../scope-runtime/event-store.js";
+import { reduce } from "../../scope-runtime/reducer.js";
+let tmpDir;
+beforeEach(() => { tmpDir = mkdtempSync(join(tmpdir(), "sprint-close-")); });
+afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+/** Set up scope through validated state */
+function setupValidated() {
+    const paths = createScope(tmpDir, "SC-CLOSE-001");
+    appendScopeEvent(paths, { type: "scope.created", actor: "user", payload: { title: "Test", description: "d", entry_mode: "experience" } });
+    appendScopeEvent(paths, { type: "grounding.started", actor: "system", payload: { sources: [{ type: "add-dir", path_or_url: "/test" }] } });
+    appendScopeEvent(paths, { type: "grounding.completed", actor: "system", payload: { snapshot_revision: 1, source_hashes: { "add-dir:/test": "h1" }, perspective_summary: { experience: 1, code: 1, policy: 1 } } });
+    appendScopeEvent(paths, { type: "align.proposed", actor: "system", payload: { packet_path: "build/align-packet.md", packet_hash: "h", snapshot_revision: 1 } });
+    appendScopeEvent(paths, { type: "align.locked", actor: "user", payload: { locked_direction: "test", locked_scope_boundaries: { in: ["a"], out: ["b"] }, locked_in_out: true } });
+    appendScopeEvent(paths, { type: "surface.generated", actor: "system", payload: { surface_type: "experience", surface_path: "surface/preview/", content_hash: "sf1", based_on_snapshot: 1 } });
+    appendScopeEvent(paths, { type: "surface.confirmed", actor: "user", payload: { final_surface_path: "surface/preview/", final_content_hash: "sf1", total_revisions: 0 } });
+    appendScopeEvent(paths, { type: "constraint.discovered", actor: "system", payload: { constraint_id: "CST-001", perspective: "code", summary: "test constraint", severity: "required", discovery_stage: "draft_phase2", decision_owner: "product_owner", impact_if_ignored: "fails", source_refs: [{ source: "test.ts", detail: "d" }] } });
+    appendScopeEvent(paths, { type: "constraint.decision_recorded", actor: "user", payload: { constraint_id: "CST-001", decision: "inject", selected_option: "fix", decision_owner: "product_owner", rationale: "필수" } });
+    appendScopeEvent(paths, { type: "target.locked", actor: "system", payload: { surface_hash: "sf1", constraint_decisions: [{ constraint_id: "CST-001", decision: "inject" }] } });
+    appendScopeEvent(paths, { type: "compile.started", actor: "system", payload: { snapshot_revision: 1, surface_hash: "sf1" } });
+    appendScopeEvent(paths, { type: "compile.completed", actor: "system", payload: { build_spec_path: "build/build-spec.md", build_spec_hash: "bs1", brownfield_detail_path: "build/brownfield-detail.md", brownfield_detail_hash: "bf1", delta_set_path: "build/delta-set.json", delta_set_hash: "ds1", validation_plan_path: "build/validation-plan.md", validation_plan_hash: "vp1" } });
+    appendScopeEvent(paths, { type: "apply.started", actor: "agent", payload: { build_spec_hash: "bs1" } });
+    appendScopeEvent(paths, { type: "apply.completed", actor: "agent", payload: { result: "success" } });
+    appendScopeEvent(paths, { type: "validation.started", actor: "agent", payload: { validation_plan_hash: "vp1" } });
+    appendScopeEvent(paths, { type: "validation.completed", actor: "agent", payload: { result: "pass", pass_count: 1, fail_count: 0, items: [{ val_id: "VAL-001", related_cst: "CST-001", result: "pass", detail: "확인 완료" }] } });
+    return paths;
+}
+describe("executeClose", () => {
+    it("validated → closed", () => {
+        const paths = setupValidated();
+        const state = reduce(readEvents(paths.events));
+        expect(state.current_state).toBe("validated");
+        const result = executeClose(paths);
+        expect(result.success).toBe(true);
+        if (!result.success)
+            return;
+        expect(result.nextState).toBe("closed");
+        const updatedState = reduce(readEvents(paths.events));
+        expect(updatedState.current_state).toBe("closed");
+    });
+    it("fails when not in validated state (draft)", () => {
+        const paths = createScope(tmpDir, "SC-CLOSE-002");
+        appendScopeEvent(paths, { type: "scope.created", actor: "user", payload: { title: "T", description: "d", entry_mode: "experience" } });
+        const result = executeClose(paths);
+        expect(result.success).toBe(false);
+        if (result.success)
+            return;
+        expect(result.reason).toContain("validated");
+    });
+    it("fails when in compiled state", () => {
+        const paths = createScope(tmpDir, "SC-CLOSE-003");
+        appendScopeEvent(paths, { type: "scope.created", actor: "user", payload: { title: "Test", description: "d", entry_mode: "experience" } });
+        appendScopeEvent(paths, { type: "grounding.started", actor: "system", payload: { sources: [{ type: "add-dir", path_or_url: "/test" }] } });
+        appendScopeEvent(paths, { type: "grounding.completed", actor: "system", payload: { snapshot_revision: 1, source_hashes: { "add-dir:/test": "h1" }, perspective_summary: { experience: 1, code: 1, policy: 1 } } });
+        appendScopeEvent(paths, { type: "align.proposed", actor: "system", payload: { packet_path: "build/align-packet.md", packet_hash: "h", snapshot_revision: 1 } });
+        appendScopeEvent(paths, { type: "align.locked", actor: "user", payload: { locked_direction: "test", locked_scope_boundaries: { in: ["a"], out: ["b"] }, locked_in_out: true } });
+        appendScopeEvent(paths, { type: "surface.generated", actor: "system", payload: { surface_type: "experience", surface_path: "surface/preview/", content_hash: "sf1", based_on_snapshot: 1 } });
+        appendScopeEvent(paths, { type: "surface.confirmed", actor: "user", payload: { final_surface_path: "surface/preview/", final_content_hash: "sf1", total_revisions: 0 } });
+        appendScopeEvent(paths, { type: "constraint.discovered", actor: "system", payload: { constraint_id: "CST-001", perspective: "code", summary: "c", severity: "required", discovery_stage: "draft_phase2", decision_owner: "product_owner", impact_if_ignored: "f", source_refs: [{ source: "t", detail: "d" }] } });
+        appendScopeEvent(paths, { type: "constraint.decision_recorded", actor: "user", payload: { constraint_id: "CST-001", decision: "inject", selected_option: "fix", decision_owner: "product_owner", rationale: "r" } });
+        appendScopeEvent(paths, { type: "target.locked", actor: "system", payload: { surface_hash: "sf1", constraint_decisions: [{ constraint_id: "CST-001", decision: "inject" }] } });
+        appendScopeEvent(paths, { type: "compile.started", actor: "system", payload: { snapshot_revision: 1, surface_hash: "sf1" } });
+        appendScopeEvent(paths, { type: "compile.completed", actor: "system", payload: { build_spec_path: "build/build-spec.md", build_spec_hash: "bs1", brownfield_detail_path: "build/brownfield-detail.md", brownfield_detail_hash: "bf1", delta_set_path: "build/delta-set.json", delta_set_hash: "ds1", validation_plan_path: "build/validation-plan.md", validation_plan_hash: "vp1" } });
+        const result = executeClose(paths);
+        expect(result.success).toBe(false);
+        if (result.success)
+            return;
+        expect(result.reason).toContain("validated");
+    });
+    it("fails when in applied state", () => {
+        const paths = createScope(tmpDir, "SC-CLOSE-004");
+        appendScopeEvent(paths, { type: "scope.created", actor: "user", payload: { title: "Test", description: "d", entry_mode: "experience" } });
+        appendScopeEvent(paths, { type: "grounding.started", actor: "system", payload: { sources: [{ type: "add-dir", path_or_url: "/test" }] } });
+        appendScopeEvent(paths, { type: "grounding.completed", actor: "system", payload: { snapshot_revision: 1, source_hashes: { "add-dir:/test": "h1" }, perspective_summary: { experience: 1, code: 1, policy: 1 } } });
+        appendScopeEvent(paths, { type: "align.proposed", actor: "system", payload: { packet_path: "build/align-packet.md", packet_hash: "h", snapshot_revision: 1 } });
+        appendScopeEvent(paths, { type: "align.locked", actor: "user", payload: { locked_direction: "test", locked_scope_boundaries: { in: ["a"], out: ["b"] }, locked_in_out: true } });
+        appendScopeEvent(paths, { type: "surface.generated", actor: "system", payload: { surface_type: "experience", surface_path: "surface/preview/", content_hash: "sf1", based_on_snapshot: 1 } });
+        appendScopeEvent(paths, { type: "surface.confirmed", actor: "user", payload: { final_surface_path: "surface/preview/", final_content_hash: "sf1", total_revisions: 0 } });
+        appendScopeEvent(paths, { type: "constraint.discovered", actor: "system", payload: { constraint_id: "CST-001", perspective: "code", summary: "c", severity: "required", discovery_stage: "draft_phase2", decision_owner: "product_owner", impact_if_ignored: "f", source_refs: [{ source: "t", detail: "d" }] } });
+        appendScopeEvent(paths, { type: "constraint.decision_recorded", actor: "user", payload: { constraint_id: "CST-001", decision: "inject", selected_option: "fix", decision_owner: "product_owner", rationale: "r" } });
+        appendScopeEvent(paths, { type: "target.locked", actor: "system", payload: { surface_hash: "sf1", constraint_decisions: [{ constraint_id: "CST-001", decision: "inject" }] } });
+        appendScopeEvent(paths, { type: "compile.started", actor: "system", payload: { snapshot_revision: 1, surface_hash: "sf1" } });
+        appendScopeEvent(paths, { type: "compile.completed", actor: "system", payload: { build_spec_path: "build/build-spec.md", build_spec_hash: "bs1", brownfield_detail_path: "build/brownfield-detail.md", brownfield_detail_hash: "bf1", delta_set_path: "build/delta-set.json", delta_set_hash: "ds1", validation_plan_path: "build/validation-plan.md", validation_plan_hash: "vp1" } });
+        appendScopeEvent(paths, { type: "apply.started", actor: "agent", payload: { build_spec_hash: "bs1" } });
+        appendScopeEvent(paths, { type: "apply.completed", actor: "agent", payload: { result: "success" } });
+        const result = executeClose(paths);
+        expect(result.success).toBe(false);
+        if (result.success)
+            return;
+        expect(result.reason).toContain("validated");
+    });
+});
+// executeDefer tests have moved to ./defer.test.ts

package/dist/core-runtime/evolve/commands/defer.js

@@ -0,0 +1,40 @@
+/**
+ * /defer command orchestration.
+ *
+ * Defers a non-terminal scope with a reason and a resume condition:
+ * any non-terminal state → scope.deferred → deferred
+ *
+ * Rejected when the scope is already in a terminal state (closed, deferred,
+ * rejected). Separated from close.ts so that deferral has its own runtime
+ * surface (BL-061: executeDefer existed but was not reachable from the evolve runtime adapter).
+ */
+import { readEvents } from "../../scope-runtime/event-store.js";
+import { reduce } from "../../scope-runtime/reducer.js";
+import { appendScopeEvent } from "../../scope-runtime/event-pipeline.js";
+import { wrapGateError } from "./error-messages.js";
+import { refreshScopeMd } from "./shared.js";
+// ─── Main ───
+export function executeDefer(paths, reason, resumeCondition) {
+    const events = readEvents(paths.events);
+    const state = reduce(events);
+    const terminalStates = ["closed", "deferred", "rejected"];
+    if (terminalStates.includes(state.current_state)) {
+        return {
+            success: false,
+            reason: `현재 상태가 ${state.current_state}입니다. 이미 종료된 scope는 보류할 수 없습니다.`,
+        };
+    }
+    const result = appendScopeEvent(paths, {
+        type: "scope.deferred",
+        actor: "user",
+        payload: { reason, resume_condition: resumeCondition },
+    });
+    if (!result.success)
+        return { success: false, reason: wrapGateError(result.reason) };
+    refreshScopeMd(paths, result.state);
+    return {
+        success: true,
+        nextState: "deferred",
+        message: "Scope가 보류되었습니다.",
+    };
+}

package/dist/core-runtime/evolve/commands/defer.test.js

@@ -0,0 +1,134 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { executeDefer } from "./defer.js";
+import { executeClose } from "./close.js";
+import { createScope } from "../../scope-runtime/scope-manager.js";
+import { appendScopeEvent } from "../../scope-runtime/event-pipeline.js";
+import { readEvents } from "../../scope-runtime/event-store.js";
+import { reduce } from "../../scope-runtime/reducer.js";
+import { handleEvolveCli } from "../cli.js";
+let tmpDir;
+beforeEach(() => { tmpDir = mkdtempSync(join(tmpdir(), "sprint-defer-")); });
+afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+/** Set up a scope through validated state so terminal-state tests can close it. */
+function setupValidated(scopeId) {
+    const paths = createScope(tmpDir, scopeId);
+    appendScopeEvent(paths, { type: "scope.created", actor: "user", payload: { title: "Test", description: "d", entry_mode: "experience" } });
+    appendScopeEvent(paths, { type: "grounding.started", actor: "system", payload: { sources: [{ type: "add-dir", path_or_url: "/test" }] } });
+    appendScopeEvent(paths, { type: "grounding.completed", actor: "system", payload: { snapshot_revision: 1, source_hashes: { "add-dir:/test": "h1" }, perspective_summary: { experience: 1, code: 1, policy: 1 } } });
+    appendScopeEvent(paths, { type: "align.proposed", actor: "system", payload: { packet_path: "build/align-packet.md", packet_hash: "h", snapshot_revision: 1 } });
+    appendScopeEvent(paths, { type: "align.locked", actor: "user", payload: { locked_direction: "test", locked_scope_boundaries: { in: ["a"], out: ["b"] }, locked_in_out: true } });
+    appendScopeEvent(paths, { type: "surface.generated", actor: "system", payload: { surface_type: "experience", surface_path: "surface/preview/", content_hash: "sf1", based_on_snapshot: 1 } });
+    appendScopeEvent(paths, { type: "surface.confirmed", actor: "user", payload: { final_surface_path: "surface/preview/", final_content_hash: "sf1", total_revisions: 0 } });
+    appendScopeEvent(paths, { type: "constraint.discovered", actor: "system", payload: { constraint_id: "CST-001", perspective: "code", summary: "c", severity: "required", discovery_stage: "draft_phase2", decision_owner: "product_owner", impact_if_ignored: "f", source_refs: [{ source: "t", detail: "d" }] } });
+    appendScopeEvent(paths, { type: "constraint.decision_recorded", actor: "user", payload: { constraint_id: "CST-001", decision: "inject", selected_option: "fix", decision_owner: "product_owner", rationale: "r" } });
+    appendScopeEvent(paths, { type: "target.locked", actor: "system", payload: { surface_hash: "sf1", constraint_decisions: [{ constraint_id: "CST-001", decision: "inject" }] } });
+    appendScopeEvent(paths, { type: "compile.started", actor: "system", payload: { snapshot_revision: 1, surface_hash: "sf1" } });
+    appendScopeEvent(paths, { type: "compile.completed", actor: "system", payload: { build_spec_path: "build/build-spec.md", build_spec_hash: "bs1", brownfield_detail_path: "build/brownfield-detail.md", brownfield_detail_hash: "bf1", delta_set_path: "build/delta-set.json", delta_set_hash: "ds1", validation_plan_path: "build/validation-plan.md", validation_plan_hash: "vp1" } });
+    appendScopeEvent(paths, { type: "apply.started", actor: "agent", payload: { build_spec_hash: "bs1" } });
+    appendScopeEvent(paths, { type: "apply.completed", actor: "agent", payload: { result: "success" } });
+    appendScopeEvent(paths, { type: "validation.started", actor: "agent", payload: { validation_plan_hash: "vp1" } });
+    appendScopeEvent(paths, { type: "validation.completed", actor: "agent", payload: { result: "pass", pass_count: 1, fail_count: 0, items: [{ val_id: "VAL-001", related_cst: "CST-001", result: "pass", detail: "확인 완료" }] } });
+    return paths;
+}
+describe("executeDefer", () => {
+    it("defers from any non-terminal state", () => {
+        const paths = createScope(tmpDir, "SC-DEFER-001");
+        appendScopeEvent(paths, { type: "scope.created", actor: "user", payload: { title: "T", description: "d", entry_mode: "experience" } });
+        const result = executeDefer(paths, "방향 재정립 필요", "다음 분기 재개");
+        expect(result.success).toBe(true);
+        if (!result.success)
+            return;
+        expect(result.nextState).toBe("deferred");
+        const state = reduce(readEvents(paths.events));
+        expect(state.current_state).toBe("deferred");
+    });
+    it("fails from terminal state (closed)", () => {
+        const paths = setupValidated("SC-DEFER-002");
+        executeClose(paths); // → closed
+        const result = executeDefer(paths, "test", "test");
+        expect(result.success).toBe(false);
+        if (result.success)
+            return;
+        expect(result.reason).toContain("closed");
+    });
+    it("fails when already deferred", () => {
+        const paths = createScope(tmpDir, "SC-DEFER-003");
+        appendScopeEvent(paths, { type: "scope.created", actor: "user", payload: { title: "T", description: "d", entry_mode: "experience" } });
+        executeDefer(paths, "first", "cond");
+        const result = executeDefer(paths, "second", "cond");
+        expect(result.success).toBe(false);
+        if (result.success)
+            return;
+        expect(result.reason).toContain("deferred");
+    });
+});
+describe("onto evolve defer — CLI surface", () => {
+    let logs;
+    let errors;
+    let logSpy;
+    let errorSpy;
+    beforeEach(() => {
+        logs = [];
+        errors = [];
+        logSpy = vi.spyOn(console, "log").mockImplementation((msg) => {
+            logs.push(String(msg));
+        });
+        errorSpy = vi.spyOn(console, "error").mockImplementation((msg) => {
+            errors.push(String(msg));
+        });
+    });
+    afterEach(() => {
+        logSpy.mockRestore();
+        errorSpy.mockRestore();
+    });
+    it("routes defer subcommand to executeDefer and succeeds", async () => {
+        const scopesDir = join(tmpDir, "scopes");
+        const paths = createScope(scopesDir, "SC-CLI-DEFER-001");
+        appendScopeEvent(paths, { type: "scope.created", actor: "user", payload: { title: "T", description: "d", entry_mode: "experience" } });
+        const code = await handleEvolveCli(tmpDir, [
+            "defer",
+            "--scope-id", "SC-CLI-DEFER-001",
+            "--scopes-dir", scopesDir,
+            "--reason", "방향 재정립",
+            "--resume-condition", "다음 분기",
+        ]);
+        expect(code).toBe(0);
+        const state = reduce(readEvents(paths.events));
+        expect(state.current_state).toBe("deferred");
+        const output = logs.join("\n");
+        expect(output).toContain("\"success\": true");
+        expect(output).toContain("\"nextState\": \"deferred\"");
+    });
+    it("rejects defer when --reason missing", async () => {
+        const scopesDir = join(tmpDir, "scopes");
+        createScope(scopesDir, "SC-CLI-DEFER-002");
+        const code = await handleEvolveCli(tmpDir, [
+            "defer",
+            "--scope-id", "SC-CLI-DEFER-002",
+            "--scopes-dir", scopesDir,
+            "--resume-condition", "cond",
+        ]);
+        expect(code).toBe(1);
+        expect(errors.some(e => e.includes("--reason") && e.includes("--resume-condition"))).toBe(true);
+    });
+    it("rejects defer when --scope-id missing", async () => {
+        const code = await handleEvolveCli(tmpDir, [
+            "defer",
+            "--reason", "r",
+            "--resume-condition", "c",
+        ]);
+        expect(code).toBe(1);
+        expect(errors.some(e => e.includes("--scope-id"))).toBe(true);
+    });
+    it("lists defer in --help output", async () => {
+        const code = await handleEvolveCli(tmpDir, ["--help"]);
+        expect(code).toBe(0);
+        const output = logs.join("\n");
+        expect(output).toContain("defer --scope-id");
+        expect(output).toContain("--reason");
+        expect(output).toContain("--resume-condition");
+    });
+});