onto-mcp 0.3.0

package/dist/core-runtime/scope-runtime/scope-manager.js

@@ -0,0 +1,161 @@
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Resolve all standard paths for a scope.
+ */
+export function resolveScopePaths(scopesDir, scopeId) {
+    const base = join(scopesDir, scopeId);
+    return {
+        scopeId,
+        base,
+        events: join(base, "events.ndjson"),
+        state: join(base, "state"),
+        surface: join(base, "surface"),
+        build: join(base, "build"),
+        inputs: join(base, "inputs"),
+        constraintPool: join(base, "state", "constraint-pool.json"),
+        verdictLog: join(base, "state", "verdict-log.json"),
+        realitySnapshot: join(base, "state", "reality-snapshot.json"),
+        sourcesYaml: join(base, "inputs", "sources.yaml"),
+        scopeMd: join(base, "scope.md"),
+        brief: join(base, "inputs", "brief.md"),
+    };
+}
+// ─── Scope ID generation ───
+/**
+ * Normalize a project name for use in scope IDs.
+ * Lowercase, spaces→hyphens, remove chars except alphanumeric and hyphens,
+ * collapse consecutive hyphens, trim leading/trailing hyphens.
+ */
+export function normalizeProjectName(name) {
+    return name
+        .toLowerCase()
+        .replace(/\s+/g, "-")
+        .replace(/[^a-z0-9-]/g, "")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+/**
+ * Generate a scope ID in `{projectName}-{YYYYMMDD}-{NNN}` format.
+ *
+ * 1. Normalizes projectName (lowercase, spaces→hyphens, special chars removed)
+ * 2. Gets today's date as YYYYMMDD
+ * 3. Scans existing directories matching `{normalized}-{YYYYMMDD}-*`
+ * 4. Returns next sequential NNN (001-based, 3-digit zero-padded)
+ */
+export function generateScopeId(scopesDir, projectName, date) {
+    const normalized = normalizeProjectName(projectName);
+    if (normalized.length === 0) {
+        throw new Error("projectName must contain at least one alphanumeric character");
+    }
+    const d = date ?? new Date();
+    const yyyymmdd = String(d.getFullYear()) +
+        String(d.getMonth() + 1).padStart(2, "0") +
+        String(d.getDate()).padStart(2, "0");
+    const prefix = `${normalized}-${yyyymmdd}-`;
+    let maxN = 0;
+    if (existsSync(scopesDir)) {
+        const entries = readdirSync(scopesDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory() && entry.name.startsWith(prefix)) {
+                const suffix = entry.name.slice(prefix.length);
+                const n = parseInt(suffix, 10);
+                if (!isNaN(n) && n > maxN) {
+                    maxN = n;
+                }
+            }
+        }
+    }
+    const nnn = String(maxN + 1).padStart(3, "0");
+    return `${normalized}-${yyyymmdd}-${nnn}`;
+}
+/**
+ * Generate a brief.md template for a scope.
+ *
+ * 1. What it is: brief.md는 /start 실행 전에 작성하는 프로젝트 준비 문서 템플릿입니다.
+ *    변경 목적, 대상 사용자, 기대 결과 등 필수 정보를 수집합니다.
+ * 2. Why it exists: 소스 스캔 전에 프로젝트의 방향과 맥락을 명확히 해야
+ *    grounding 단계에서 올바른 constraint를 발견할 수 있습니다.
+ * 3. How it relates: createScope가 호출할 때 inputs/brief.md로 기록되며,
+ *    에이전트가 /start 실행 시 이 파일의 내용을 참조합니다.
+ */
+export function generateBriefTemplate(projectName, defaultSources) {
+    const sourcesSection = defaultSources && defaultSources.length > 0
+        ? defaultSources
+            .map((s) => {
+            const desc = s.description ?? `${s.type}: ${s.identifier}`;
+            return `- [x] ${desc} (${s.type}: ${s.identifier})`;
+        })
+            .join("\n")
+        : "- 환경설정 파일(.sprint-kit.yaml)이 없거나 소스가 정의되지 않았습니다.";
+    return `# ${projectName} — Brief
+
+<!-- 이 문서는 /start 실행 전에 작성하는 프로젝트 준비 문서입니다. -->
+<!-- 필수 항목을 채운 후 /start ${projectName}을 다시 실행하면 프로세스가 시작됩니다. -->
+
+## 변경 목적 (필수)
+<!-- 왜 이 변경이 필요한가요? 해결하려는 문제를 설명해 주세요. -->
+
+
+
+## 대상 사용자 (필수)
+<!-- 이 변경이 영향을 미치는 사용자는 누구인가요? -->
+
+
+
+## 기대 결과 (필수)
+<!-- 이 변경이 성공하면 어떤 상태가 되나요? -->
+
+
+
+## 포함 범위
+<!-- 이번에 포함할 기능이나 변경 사항을 나열해 주세요. (선택) -->
+
+
+
+## 제외 범위
+<!-- 이번에 포함하지 않을 사항을 나열해 주세요. (선택) -->
+
+
+
+## 제약 및 참고사항
+<!-- 이미 알고 있는 제약(일정, 기술 제한 등)이나 참고할 정보를 적어 주세요. (선택) -->
+
+
+
+## 소스
+<!-- .sprint-kit.yaml에서 자동 로드됨. 추가 소스를 아래에 기입하세요. -->
+
+### 자동 로드 (환경설정)
+${sourcesSection}
+
+### 추가 소스
+- [ ] (여기에 추가 소스를 기입하세요)
+`;
+}
+/**
+ * Create a scope directory with all standard subdirectories.
+ * Returns the resolved paths. Idempotent — safe to call on existing scope.
+ *
+ * If projectName is provided, generates scopeId automatically using
+ * `{projectName}-{YYYYMMDD}-{NNN}` format.
+ * If only scopeId is provided (backward compat), uses it directly.
+ */
+export function createScope(scopesDir, scopeId, options) {
+    const finalScopeId = options?.projectName != null
+        ? generateScopeId(scopesDir, options.projectName, options.date)
+        : scopeId;
+    const paths = resolveScopePaths(scopesDir, finalScopeId);
+    const dirs = [paths.base, paths.state, paths.surface, paths.build, paths.inputs];
+    for (const dir of dirs) {
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    }
+    if (!existsSync(paths.brief)) {
+        const name = options?.projectName ?? scopeId;
+        const template = generateBriefTemplate(name, options?.defaultSources);
+        writeFileSync(paths.brief, template, "utf-8");
+    }
+    return paths;
+}

package/dist/core-runtime/scope-runtime/state-machine.js

@@ -0,0 +1,309 @@
+import { TERMINAL_STATES, OBSERVATIONAL_EVENT_TYPES } from "./types.js";
+const OBSERVATIONAL_SET = new Set(OBSERVATIONAL_EVENT_TYPES);
+// State × TransitionEvent matrix.
+// Only explicitly listed combinations are allowed. Everything else is denied.
+const MATRIX = {
+    // ── draft ──
+    draft: {
+        "input.attached": { next: "draft", kind: "self" },
+        "grounding.started": { next: "draft", kind: "self" },
+        "grounding.completed": { next: "grounded", kind: "forward" },
+        "constraint.discovered": { next: "draft", kind: "self" },
+    },
+    // ── grounded ──
+    grounded: {
+        "align.proposed": { next: "align_proposed", kind: "forward" },
+        "constraint.discovered": { next: "grounded", kind: "self" },
+        "snapshot.marked_stale": { next: "grounded", kind: "self" },
+        "exploration.started": { next: "exploring", kind: "forward" },
+    },
+    // ── exploring ──
+    exploring: {
+        "exploration.round_completed": { next: "exploring", kind: "self" },
+        "exploration.phase_transitioned": { next: "exploring", kind: "self" },
+        "align.proposed": { next: "align_proposed", kind: "forward" },
+        "constraint.discovered": { next: "exploring", kind: "self" },
+        "snapshot.marked_stale": { next: "exploring", kind: "self" },
+        "redirect.to_grounding": { next: "grounded", kind: "backward" },
+    },
+    // ── align_proposed ──
+    align_proposed: {
+        "align.locked": { next: "align_locked", kind: "forward" },
+        "align.revised": { next: "align_proposed", kind: "self" },
+        "snapshot.marked_stale": { next: "align_proposed", kind: "self" },
+        "redirect.to_grounding": { next: "grounded", kind: "backward" },
+    },
+    // ── align_locked ──
+    align_locked: {
+        "surface.generated": { next: "surface_iterating", kind: "forward" },
+        "snapshot.marked_stale": { next: "align_proposed", kind: "backward" },
+    },
+    // ── surface_iterating ──
+    surface_iterating: {
+        "surface.revision_requested": {
+            next: "surface_iterating",
+            kind: "self",
+        },
+        "surface.revision_applied": { next: "surface_iterating", kind: "self" },
+        "surface.confirmed": { next: "surface_confirmed", kind: "forward" },
+        "constraint.discovered": { next: "surface_iterating", kind: "self" },
+        "redirect.to_align": { next: "align_proposed", kind: "backward" },
+        "snapshot.marked_stale": { next: "surface_iterating", kind: "self" },
+    },
+    // ── surface_confirmed ──
+    surface_confirmed: {
+        "constraint.discovered": { next: "surface_confirmed", kind: "self" },
+        "constraint.decision_recorded": {
+            next: "surface_confirmed",
+            kind: "self",
+            conditional: ["constraints_resolved"],
+        },
+        "constraint.clarify_requested": {
+            next: "surface_confirmed",
+            kind: "self",
+        },
+        "constraint.clarify_resolved": {
+            next: "surface_confirmed",
+            kind: "self",
+            conditional: ["constraints_resolved"],
+        },
+        "constraint.invalidated": {
+            next: "surface_confirmed",
+            kind: "self",
+            conditional: ["constraints_resolved"],
+        },
+        "target.locked": { next: "target_locked", kind: "forward" },
+        "surface.change_required": {
+            next: "surface_iterating",
+            kind: "backward",
+        },
+        "redirect.to_align": { next: "align_proposed", kind: "backward" },
+        "snapshot.marked_stale": { next: "surface_confirmed", kind: "self" },
+    },
+    // ── constraints_resolved ──
+    constraints_resolved: {
+        "constraint.discovered": {
+            next: "surface_confirmed",
+            kind: "backward",
+        },
+        "constraint.decision_recorded": {
+            next: "constraints_resolved",
+            kind: "self",
+        },
+        "constraint.invalidated": { next: "constraints_resolved", kind: "self" },
+        "target.locked": { next: "target_locked", kind: "forward" },
+        "surface.change_required": {
+            next: "surface_iterating",
+            kind: "backward",
+        },
+        "redirect.to_align": { next: "align_proposed", kind: "backward" },
+        "snapshot.marked_stale": { next: "constraints_resolved", kind: "self" },
+    },
+    // ── target_locked ──
+    target_locked: {
+        "constraint.discovered": { next: "target_locked", kind: "self" },
+        "compile.started": { next: "target_locked", kind: "self" },
+        "compile.completed": { next: "compiled", kind: "forward" },
+        "compile.constraint_gap_found": {
+            next: "constraints_resolved",
+            kind: "backward",
+        },
+        "snapshot.marked_stale": {
+            next: "constraints_resolved",
+            kind: "backward",
+        },
+    },
+    // ── compiled ──
+    compiled: {
+        "constraint.discovered": { next: "compiled", kind: "self" },
+        "compile.constraint_gap_found": {
+            next: "constraints_resolved",
+            kind: "backward",
+        },
+        "apply.started": { next: "compiled", kind: "self" },
+        "apply.completed": { next: "applied", kind: "forward" },
+        "apply.decision_gap_found": {
+            next: "constraints_resolved",
+            kind: "backward",
+        },
+        "snapshot.marked_stale": { next: "grounded", kind: "backward" },
+    },
+    // ── applied ──
+    applied: {
+        "validation.started": { next: "applied", kind: "self" },
+        "validation.completed": {
+            next: "validated",
+            kind: "forward",
+            conditional: ["constraints_resolved", "grounded"],
+        },
+        "snapshot.marked_stale": { next: "applied", kind: "self" },
+    },
+    // ── validated ──
+    validated: {
+        "scope.closed": { next: "closed", kind: "forward" },
+    },
+};
+// validation.completed has conditional next state (pass vs fail).
+// The matrix records the default (pass → validated).
+// Gate guard / pipeline handles fail variants.
+// This is documented here for completeness but the conditional logic
+// lives in gate-guard.ts (Phase 2).
+// ─── Public API ───
+/**
+ * Check whether a transition event is allowed from the given state.
+ * Returns the outcome (allowed + next state, or denied).
+ */
+export function canTransition(state, eventType) {
+    const stateRow = MATRIX[state];
+    if (!stateRow) {
+        return { allowed: false };
+    }
+    const entry = stateRow[eventType];
+    if (!entry) {
+        return { allowed: false };
+    }
+    const result = {
+        allowed: true,
+        next_state: entry.next,
+        kind: entry.kind,
+    };
+    if (entry.conditional) {
+        result.conditional_targets = entry.conditional;
+    }
+    return result;
+}
+/**
+ * Check whether a global event is allowed from the given state.
+ * Global events (scope.deferred, scope.rejected) are allowed from every non-terminal state.
+ */
+export function canApplyGlobal(state, eventType) {
+    if (TERMINAL_STATES.has(state)) {
+        return { allowed: false };
+    }
+    const targetState = eventType === "scope.deferred" ? "deferred" : "rejected";
+    return { allowed: true, next_state: targetState, kind: "forward" };
+}
+/**
+ * Check whether an observational event is allowed from the given state.
+ * Observational events are allowed in every non-terminal state.
+ * They do not change state (state_after === state_before).
+ */
+export function canApplyObservational(state, _eventType) {
+    if (TERMINAL_STATES.has(state)) {
+        return { allowed: false };
+    }
+    return { allowed: true, next_state: state, kind: "self" };
+}
+/**
+ * Unified check: given current state and any event type, return the transition outcome.
+ */
+export function resolveTransition(state, eventType) {
+    // Global events
+    if (eventType === "scope.deferred" || eventType === "scope.rejected") {
+        return canApplyGlobal(state, eventType);
+    }
+    // Observational events
+    if (OBSERVATIONAL_SET.has(eventType)) {
+        return canApplyObservational(state, eventType);
+    }
+    // Transition events
+    return canTransition(state, eventType);
+}
+/**
+ * Get all allowed events from a given state (transition events only).
+ * Useful for debugging and testing.
+ */
+export function allowedTransitionEvents(state) {
+    const stateRow = MATRIX[state];
+    if (!stateRow)
+        return [];
+    return Object.keys(stateRow);
+}
+// ═══════════════════════════════════════════════════════════════════
+// Multi-domain state machine definitions (W-B-02 dedup)
+//
+// 본 파일이 모든 onto 프로세스 state machine 의 단일 SSOT.
+// - Design scope: 위의 MATRIX (15 states)
+// - Review coordinator: REVIEW_TRANSITIONS (9 states)
+// - Reconstruct session: RECONSTRUCT_TRANSITIONS (8 states)
+// ═══════════════════════════════════════════════════════════════════
+// ─── Review coordinator (10 states) ───
+// auto 3: preparing, validating_lenses, completing
+// await 4: awaiting_lens_dispatch, awaiting_adjudication, awaiting_synthesize_dispatch, awaiting_deliberation
+// terminal 3: completed, halted_partial, failed
+export const REVIEW_STATES = [
+    "preparing",
+    "awaiting_lens_dispatch",
+    "validating_lenses",
+    "awaiting_adjudication",
+    "awaiting_synthesize_dispatch",
+    "awaiting_deliberation",
+    "completing",
+    "completed",
+    "halted_partial",
+    "failed",
+];
+export const REVIEW_TERMINAL_STATES = new Set([
+    "completed",
+    "halted_partial",
+    "failed",
+]);
+export const REVIEW_TRANSITIONS = {
+    "(init)": ["preparing"],
+    preparing: ["awaiting_lens_dispatch", "failed"],
+    awaiting_lens_dispatch: ["validating_lenses"],
+    validating_lenses: ["awaiting_adjudication", "awaiting_deliberation", "halted_partial", "failed"],
+    awaiting_adjudication: ["awaiting_deliberation", "failed"],
+    awaiting_deliberation: ["awaiting_synthesize_dispatch", "failed"],
+    awaiting_synthesize_dispatch: ["completing"],
+    completing: ["completed", "failed"],
+    completed: [],
+    halted_partial: [],
+    failed: [],
+};
+/**
+ * Review coordinator 전이 검증.
+ */
+export function canReviewTransition(from, to) {
+    const allowed = REVIEW_TRANSITIONS[from];
+    return allowed != null && allowed.includes(to);
+}
+// ─── Reconstruct session (8 states) ───
+// build.md 의 Phase 0~4 를 형식화한 상태 모델.
+// auto 4: negotiating, gathering_context, exploring, adjudicating
+// await 2: awaiting_user_review, processing_responses
+// terminal 2: converted, reconstruct_failed
+export const RECONSTRUCT_STATES = [
+    "negotiating",
+    "gathering_context",
+    "reconstruct_exploring",
+    "adjudicating",
+    "awaiting_user_review",
+    "processing_responses",
+    "converting",
+    "converted",
+    "reconstruct_failed",
+];
+export const RECONSTRUCT_TERMINAL_STATES = new Set([
+    "converted",
+    "reconstruct_failed",
+]);
+export const RECONSTRUCT_TRANSITIONS = {
+    "(init)": ["negotiating"],
+    negotiating: ["gathering_context", "reconstruct_failed"], // Phase 0
+    gathering_context: ["reconstruct_exploring", "reconstruct_failed"], // Phase 0.5
+    reconstruct_exploring: ["adjudicating", "reconstruct_failed"], // Phase 1 (Stage 1+2)
+    adjudicating: ["awaiting_user_review", "reconstruct_failed"], // Phase 2
+    awaiting_user_review: ["processing_responses", "reconstruct_failed"], // Phase 3
+    processing_responses: ["converting", "awaiting_user_review", "reconstruct_failed"], // Phase 3.5 (re-entry 가능)
+    converting: ["converted", "reconstruct_failed"], // Phase 4
+    converted: [],
+    reconstruct_failed: [],
+};
+/**
+ * Reconstruct session 전이 검증.
+ */
+export function canReconstructTransition(from, to) {
+    const allowed = RECONSTRUCT_TRANSITIONS[from];
+    return allowed != null && allowed.includes(to);
+}