onto-mcp 0.3.1 → 0.4.0

package/dist/core-runtime/scope-runtime/gate-guard.js

@@ -1,348 +0,0 @@
-import { resolveTransition } from "./state-machine.js";
-import { MAX_COMPILE_RETRIES, MAX_EXPLORATION_ROUNDS } from "./constants.js";
-import { findConstraint, isConstraintsResolved } from "./constraint-pool.js";
-// ─── Actor validation mapping ───
-/**
- * Allowed actors per event type.
- *
- * Events not listed here are allowed for ALL actors (gradual adoption).
- * This mapping encodes the intended actor constraints:
- * - user: human PO actions (scope creation, locking, decisions)
- * - system: automated pipeline actions (grounding, compile, surface generation)
- * - agent: AI-driven actions (apply, validation, constraint discovery/decisions)
- */
-export const ACTOR_MAPPING = {
-    // User-initiated events
-    "scope.created": new Set(["user"]),
-    "scope.closed": new Set(["user"]),
-    "surface.confirmed": new Set(["user"]),
-    "align.locked": new Set(["user"]),
-    // User or agent decisions
-    "constraint.decision_recorded": new Set(["user", "agent"]),
-    "constraint.clarify_resolved": new Set(["user", "agent"]),
-    // System-initiated pipeline events (user allowed for gradual adoption)
-    "grounding.started": new Set(["system", "user"]),
-    "grounding.completed": new Set(["system", "user"]),
-    "compile.started": new Set(["system", "user"]),
-    "compile.completed": new Set(["system", "user"]),
-    "surface.generated": new Set(["system", "user"]),
-    // Agent-driven actions (user allowed for gradual adoption)
-    "apply.started": new Set(["agent", "user"]),
-    "apply.completed": new Set(["agent", "user"]),
-    "validation.started": new Set(["agent", "user"]),
-    "validation.completed": new Set(["agent", "user"]),
-    // Mixed actors
-    "constraint.discovered": new Set(["system", "agent", "user"]),
-    "align.proposed": new Set(["system", "user"]),
-    "align.revised": new Set(["system", "user"]),
-    "exploration.started": new Set(["agent", "system"]),
-    "exploration.round_completed": new Set(["agent", "system"]),
-    "exploration.phase_transitioned": new Set(["agent", "system"]),
-};
-// ─── Events that reference a constraint_id ───
-const CONSTRAINT_REF_EVENTS = new Set([
-    "constraint.decision_recorded",
-    "constraint.clarify_requested",
-    "constraint.clarify_resolved",
-    "constraint.invalidated",
-    "surface.change_required",
-]);
-// ─── Events blocked during convergence ───
-const CONVERGENCE_BLOCKED_EVENTS = new Set([
-    "align.revised",
-    "surface.revision_applied",
-]);
-// ─── Main validation function ───
-/**
- * Validate an event before appending to the event store.
- *
- * Checks rules in order:
- * 1. State transition authorization (state machine matrix)
- * 2. Referential integrity (constraint_id existence)
- * 3. Required override validation (rationale required)
- * 3b. Required constraint invalidation protection [GC-017]
- * 4. Convergence blocking (revise blocked after convergence.blocked)
- * 5a. Apply gate (apply_enabled in config)
- * 5c. Pre-Apply Review gate (pre_apply.review_completed required before apply)
- * 5b. Compile retry limit (compile.started blocked after 3 gap_found cycles)
- *
- * On success, returns the determined next_state (resolving conditional targets).
- * On failure, returns the reason for rejection.
- */
-export function validateEvent(state, newEvent, options) {
-    const eventType = newEvent.type;
-    // ── Special case: scope.created is a bootstrap event ──
-    // Not in the state machine matrix. Allowed only when no events exist yet.
-    if (eventType === "scope.created") {
-        if (state.latest_revision === 0) {
-            return { allowed: true, next_state: "draft" };
-        }
-        return {
-            allowed: false,
-            reason: `scope.created is only allowed as the first event (current revision: ${state.latest_revision})`,
-        };
-    }
-    // ── Rule 0: Actor validation ──
-    const allowedActors = ACTOR_MAPPING[eventType];
-    if (allowedActors && !allowedActors.has(newEvent.actor)) {
-        return {
-            allowed: false,
-            reason: `Actor denied: "${newEvent.actor}" is not allowed for "${eventType}". Allowed: ${[...allowedActors].join(", ")}`,
-        };
-    }
-    // ── Rule 1: State transition authorization ──
-    const outcome = resolveTransition(state.current_state, eventType);
-    if (!outcome.allowed) {
-        return {
-            allowed: false,
-            reason: `Transition denied: "${state.current_state}" does not allow "${eventType}"`,
-        };
-    }
-    // ── Rule 2: Referential integrity ──
-    if (CONSTRAINT_REF_EVENTS.has(eventType)) {
-        const constraintId = extractConstraintId(newEvent);
-        if (constraintId !== undefined) {
-            const entry = findConstraint(state.constraint_pool, constraintId);
-            if (!entry) {
-                return {
-                    allowed: false,
-                    reason: `Referential integrity: constraint_id "${constraintId}" not found in pool`,
-                };
-            }
-            // ── Rule 3: Required override validation ──
-            if (eventType === "constraint.decision_recorded" ||
-                eventType === "constraint.clarify_resolved") {
-                const decision = newEvent.payload.decision;
-                if (entry.severity === "required" &&
-                    decision === "override") {
-                    const rationale = newEvent.payload.rationale;
-                    if (!rationale || rationale.trim() === "") {
-                        return {
-                            allowed: false,
-                            reason: `Required constraint "${constraintId}" with override decision requires non-empty rationale`,
-                        };
-                    }
-                }
-            }
-            // ── Rule 3b: Required constraint invalidation protection [GC-017] ──
-            if (eventType === "constraint.invalidated" &&
-                entry.severity === "required" &&
-                newEvent.actor === "system") {
-                return {
-                    allowed: false,
-                    reason: `Required constraint "${constraintId}" cannot be invalidated by system alone. User confirmation is required.`,
-                };
-            }
-        }
-    }
-    // ── Rule 4: Convergence blocking ──
-    if (state.convergence_blocked &&
-        CONVERGENCE_BLOCKED_EVENTS.has(eventType)) {
-        return {
-            allowed: false,
-            reason: `Convergence blocked: cannot "${eventType}" until convergence.action_taken is recorded`,
-        };
-    }
-    // ── Rule 5a: Apply gate — requires apply_enabled in .sprint-kit.yaml ──
-    if (eventType === "apply.started" && options?.apply_enabled !== true) {
-        return {
-            allowed: false,
-            reason: "Apply gate: apply 단계를 실행하려면 .sprint-kit.yaml에 apply_enabled: true를 추가하세요.",
-        };
-    }
-    // ── Rule 5c: Pre-Apply Review gate — apply requires pre_apply.review_completed ──
-    if (eventType === "apply.started" && !state.pre_apply_completed) {
-        return {
-            allowed: false,
-            reason: "Apply gate: Pre-Apply Review가 완료되어야 합니다. pre_apply.review_completed 이벤트가 먼저 기록되어야 합니다.",
-        };
-    }
-    // ── Rule 5d: PRD Review gate — apply requires prd.review_completed ──
-    if (eventType === "apply.started" && !state.prd_review_completed) {
-        return {
-            allowed: false,
-            reason: "Apply gate: PRD 다관점 리뷰가 완료되어야 합니다. prd.review_completed 이벤트가 먼저 기록되어야 합니다.",
-        };
-    }
-    // ── Rule 5b: Compile retry limit ──
-    if (eventType === "compile.started" &&
-        state.retry_count_compile >= MAX_COMPILE_RETRIES) {
-        return {
-            allowed: false,
-            reason: `Compile retry limit exceeded (${state.retry_count_compile} gap_found cycles). Consider scope.deferred or redirect.to_align.`,
-        };
-    }
-    // ── Rule 6: target.locked requires all constraints resolved ──
-    if (eventType === "target.locked" && !isConstraintsResolved(state.constraint_pool)) {
-        const { summary } = state.constraint_pool;
-        const reasons = [];
-        if (summary.undecided > 0)
-            reasons.push(`미결정 ${summary.undecided}건`);
-        if (summary.clarify_pending > 0)
-            reasons.push(`clarify 대기 ${summary.clarify_pending}건`);
-        return {
-            allowed: false,
-            reason: `Target lock 불가: ${reasons.join(", ")}. 모든 constraint 결정이 완료되어야 합니다.`,
-        };
-    }
-    // ── Rule 7: Exploration round limit ──
-    if (eventType === "exploration.round_completed" &&
-        state.exploration_progress &&
-        state.exploration_progress.total_rounds >= MAX_EXPLORATION_ROUNDS) {
-        return {
-            allowed: false,
-            reason: `Exploration round limit exceeded (${state.exploration_progress.total_rounds} rounds). align.proposed로 진행하거나 scope.deferred를 고려하세요.`,
-        };
-    }
-    // ── Rule 8: Exploration sequence integrity ──
-    // Rule 8a (align.proposed during exploration) is now handled structurally by MATRIX:
-    // exploring state allows align.proposed; grounded state allows align.proposed.
-    // Protocol determines when agent should record align.proposed.
-    // Rule 8b: exploration.round_completed/phase_transitioned require exploration.started
-    // MATRIX enforces this structurally (only exploring state allows these events).
-    // This rule provides a clearer error message.
-    if ((eventType === "exploration.round_completed" ||
-        eventType === "exploration.phase_transitioned") &&
-        !state.exploration_progress) {
-        return {
-            allowed: false,
-            reason: `exploration.started 이벤트가 먼저 기록되어야 합니다.`,
-        };
-    }
-    // Rule 8c: exploration.started blocked when exploration already in progress
-    if (eventType === "exploration.started" &&
-        state.exploration_progress &&
-        !state.exploration_progress.completed_at) {
-        return {
-            allowed: false,
-            reason: `Exploration이 이미 진행 중입니다 (Phase ${state.exploration_progress.current_phase}/6). 완료 후 재시작 가능합니다.`,
-        };
-    }
-    // ── Resolve next state (handle conditional targets) ──
-    const next_state = resolveNextState(outcome, state, newEvent);
-    return { allowed: true, next_state };
-}
-// ─── Conditional target resolution ───
-/**
- * Determine the actual next state when conditional_targets exist.
- *
- * Handles two cases:
- * 1. surface_confirmed + constraint decision/clarify/invalidated
- *    → constraints_resolved if all constraints are now resolved
- * 2. applied + validation.completed
- *    → validated (pass), constraints_resolved (fail), or grounded (fail+stale)
- */
-function resolveNextState(outcome, state, event) {
-    if (!outcome.conditional_targets || outcome.conditional_targets.length === 0) {
-        return outcome.next_state;
-    }
-    const eventType = event.type;
-    // Case 1: surface_confirmed → constraints_resolved (conditional)
-    if (state.current_state === "surface_confirmed" &&
-        (eventType === "constraint.decision_recorded" ||
-            eventType === "constraint.clarify_resolved" ||
-            eventType === "constraint.invalidated")) {
-        // Simulate: apply this event to the pool, then check resolution
-        const simulatedPool = simulateConstraintEvent(state, event);
-        if (isConstraintsResolved(simulatedPool)) {
-            return "constraints_resolved";
-        }
-        return "surface_confirmed";
-    }
-    // Case 2: applied + validation.completed → validated / constraints_resolved / grounded
-    if (state.current_state === "applied" &&
-        eventType === "validation.completed") {
-        const p = event.payload;
-        // stale → grounded (regardless of pass/fail)
-        if (state.stale) {
-            return "grounded";
-        }
-        if (p.result === "pass") {
-            return "validated";
-        }
-        // fail + target issue → constraints_resolved
-        return "constraints_resolved";
-    }
-    // Default: use matrix default
-    return outcome.next_state;
-}
-// ─── Helpers ───
-/**
- * Simulate applying a constraint event to get an updated pool.
- * Used for conditional target resolution without mutating the original pool.
- */
-function simulateConstraintEvent(state, event) {
-    // Deep clone the constraints array to avoid mutation
-    const clonedConstraints = state.constraint_pool.constraints.map((c) => ({
-        ...c,
-    }));
-    const eventType = event.type;
-    if (eventType === "constraint.decision_recorded") {
-        const p = event.payload;
-        const entry = clonedConstraints.find((c) => c.constraint_id === p.constraint_id);
-        if (entry) {
-            entry.status = "decided";
-        }
-    }
-    else if (eventType === "constraint.clarify_resolved") {
-        const p = event.payload;
-        const entry = clonedConstraints.find((c) => c.constraint_id === p.constraint_id);
-        if (entry) {
-            entry.status = "decided";
-        }
-    }
-    else if (eventType === "constraint.invalidated") {
-        const p = event.payload;
-        const entry = clonedConstraints.find((c) => c.constraint_id === p.constraint_id);
-        if (entry) {
-            entry.status = "invalidated";
-        }
-    }
-    // Recompute summary
-    let decided = 0;
-    let clarify_pending = 0;
-    let invalidated = 0;
-    let undecided = 0;
-    let required = 0;
-    let recommended = 0;
-    for (const c of clonedConstraints) {
-        if (c.severity === "required")
-            required++;
-        else
-            recommended++;
-        switch (c.status) {
-            case "decided":
-                decided++;
-                break;
-            case "clarify_pending":
-                clarify_pending++;
-                break;
-            case "invalidated":
-                invalidated++;
-                break;
-            case "undecided":
-                undecided++;
-                break;
-        }
-    }
-    return {
-        constraints: clonedConstraints,
-        summary: {
-            total: clonedConstraints.length,
-            required,
-            recommended,
-            decided,
-            clarify_pending,
-            invalidated,
-            undecided,
-        },
-    };
-}
-/** Extract constraint_id from event payload, if present. */
-function extractConstraintId(event) {
-    const payload = event.payload;
-    if (typeof payload.constraint_id === "string") {
-        return payload.constraint_id;
-    }
-    return undefined;
-}