solveos-cli 0.1.0

package/dist/workflows/state-machine.js

@@ -0,0 +1,271 @@
+/**
+ * Cycle state machine for solveos-cli.
+ *
+ * Tracks which phase/gate the user is in, enforces valid transitions,
+ * and provides helpers for state queries. Persistence (load/save to
+ * .solveos/STATE.md) is handled by the artifacts module.
+ *
+ * The transition map encodes all ~20 valid transitions from docs/plan.md.
+ * Invalid transitions throw — they are programming errors, not user errors.
+ */
+import { CycleState } from "../types.js";
+// ---------------------------------------------------------------------------
+// Transition Map
+// ---------------------------------------------------------------------------
+/**
+ * Map from each state to its valid target states.
+ * This is the runtime representation of the StateTransition type.
+ */
+const TRANSITION_MAP = {
+    [CycleState.INIT]: [CycleState.RESEARCHING, CycleState.PLANNING],
+    [CycleState.RESEARCHING]: [CycleState.PLANNING],
+    [CycleState.PLANNING]: [CycleState.VALIDATING_PLAN, CycleState.BUILDING],
+    [CycleState.VALIDATING_PLAN]: [CycleState.PLANNING, CycleState.BUILDING],
+    [CycleState.BUILDING]: [
+        CycleState.VALIDATING_BUILD,
+        CycleState.REVIEWING_PRE,
+        CycleState.READY_TO_SHIP,
+    ],
+    [CycleState.VALIDATING_BUILD]: [
+        CycleState.BUILDING,
+        CycleState.PLANNING,
+        CycleState.REVIEWING_PRE,
+        CycleState.READY_TO_SHIP,
+    ],
+    [CycleState.REVIEWING_PRE]: [CycleState.BUILDING, CycleState.READY_TO_SHIP],
+    [CycleState.READY_TO_SHIP]: [CycleState.SHIPPED],
+    [CycleState.SHIPPED]: [CycleState.REVIEWING_POST, CycleState.CYCLE_COMPLETE],
+    [CycleState.REVIEWING_POST]: [CycleState.CYCLE_COMPLETE],
+    [CycleState.CYCLE_COMPLETE]: [CycleState.INIT],
+};
+// ---------------------------------------------------------------------------
+// Gate Tracking Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Map from state to the gate it represents (if any).
+ * States not in this map are phases, not gates.
+ */
+const STATE_TO_GATE = {
+    [CycleState.RESEARCHING]: "RESEARCH",
+    [CycleState.VALIDATING_PLAN]: "PLAN_VALIDATION",
+    [CycleState.VALIDATING_BUILD]: "BUILD_VALIDATION",
+    [CycleState.REVIEWING_PRE]: "REVIEW_PRE_SHIP",
+    [CycleState.REVIEWING_POST]: "REVIEW_POST_SHIP",
+};
+/**
+ * Determines which gates were skipped when transitioning from `from` to `to`.
+ * A gate is "skipped" when a transition bypasses a state that has a gate.
+ *
+ * Returns the list of gate names that were skipped (may be empty).
+ */
+function detectSkippedGates(from, to, alreadySkipped, alreadyCompleted) {
+    const skipped = [];
+    // INIT -> PLANNING skips RESEARCH
+    if (from === CycleState.INIT && to === CycleState.PLANNING) {
+        const gate = "RESEARCH";
+        if (!alreadySkipped.includes(gate) && !alreadyCompleted.includes(gate)) {
+            skipped.push(gate);
+        }
+    }
+    // PLANNING -> BUILDING skips PLAN_VALIDATION
+    if (from === CycleState.PLANNING && to === CycleState.BUILDING) {
+        const gate = "PLAN_VALIDATION";
+        if (!alreadySkipped.includes(gate) && !alreadyCompleted.includes(gate)) {
+            skipped.push(gate);
+        }
+    }
+    // BUILDING -> REVIEWING_PRE skips BUILD_VALIDATION
+    if (from === CycleState.BUILDING && to === CycleState.REVIEWING_PRE) {
+        const gate = "BUILD_VALIDATION";
+        if (!alreadySkipped.includes(gate) && !alreadyCompleted.includes(gate)) {
+            skipped.push(gate);
+        }
+    }
+    // BUILDING -> READY_TO_SHIP skips BUILD_VALIDATION and REVIEW_PRE_SHIP
+    if (from === CycleState.BUILDING && to === CycleState.READY_TO_SHIP) {
+        for (const gate of ["BUILD_VALIDATION", "REVIEW_PRE_SHIP"]) {
+            if (!alreadySkipped.includes(gate) && !alreadyCompleted.includes(gate)) {
+                skipped.push(gate);
+            }
+        }
+    }
+    // VALIDATING_BUILD -> READY_TO_SHIP skips REVIEW_PRE_SHIP
+    if (from === CycleState.VALIDATING_BUILD && to === CycleState.READY_TO_SHIP) {
+        const gate = "REVIEW_PRE_SHIP";
+        if (!alreadySkipped.includes(gate) && !alreadyCompleted.includes(gate)) {
+            skipped.push(gate);
+        }
+    }
+    // SHIPPED -> CYCLE_COMPLETE skips REVIEW_POST_SHIP
+    if (from === CycleState.SHIPPED && to === CycleState.CYCLE_COMPLETE) {
+        const gate = "REVIEW_POST_SHIP";
+        if (!alreadySkipped.includes(gate) && !alreadyCompleted.includes(gate)) {
+            skipped.push(gate);
+        }
+    }
+    return skipped;
+}
+/**
+ * Determines which gate was completed when leaving a gate state.
+ * Returns the gate name if the `from` state is a gate, otherwise null.
+ */
+function detectCompletedGate(from, to) {
+    const gate = STATE_TO_GATE[from];
+    if (!gate)
+        return null;
+    // A gate is "completed" when we transition forward from it.
+    // Going backward (e.g., VALIDATING_PLAN -> PLANNING) means the gate
+    // found issues and is not yet complete.
+    const backwardTransitions = {
+        [CycleState.VALIDATING_PLAN]: [CycleState.PLANNING],
+        [CycleState.VALIDATING_BUILD]: [CycleState.BUILDING, CycleState.PLANNING],
+        [CycleState.REVIEWING_PRE]: [CycleState.BUILDING],
+    };
+    const backward = backwardTransitions[from];
+    if (backward && backward.includes(to)) {
+        return null; // Going backward — gate not completed
+    }
+    return gate;
+}
+// ---------------------------------------------------------------------------
+// State Machine API
+// ---------------------------------------------------------------------------
+/**
+ * Validate and apply a state transition.
+ *
+ * @param stateData - Current cycle state data.
+ * @param target - The desired next state.
+ * @param maxPlanValidationPasses - From config; defaults to 3.
+ * @returns TransitionResult with updated state data and metadata.
+ * @throws Error if the transition is invalid.
+ */
+export function transition(stateData, target, maxPlanValidationPasses = 3) {
+    const from = stateData.current_state;
+    const validTargets = TRANSITION_MAP[from];
+    if (!validTargets.includes(target)) {
+        throw new Error(`Invalid transition: ${from} -> ${target}. ` +
+            `Valid targets from ${from}: [${validTargets.join(", ")}]`);
+    }
+    // Detect gate events
+    const gatesSkipped = detectSkippedGates(from, target, stateData.gates_skipped, stateData.gates_completed);
+    const gateCompleted = detectCompletedGate(from, target);
+    // Track plan validation passes
+    let planValidationPasses = stateData.plan_validation_passes;
+    let planValidationEscalation = false;
+    if (target === CycleState.VALIDATING_PLAN) {
+        planValidationPasses += 1;
+        if (planValidationPasses > maxPlanValidationPasses) {
+            planValidationEscalation = true;
+        }
+    }
+    // Build transition log entry
+    const now = new Date().toISOString();
+    const logEntry = {
+        from,
+        to: target,
+        at: now,
+    };
+    // Record the first gate skipped (if any) on the log entry
+    if (gatesSkipped.length > 0) {
+        logEntry.gate_skipped = gatesSkipped[0];
+    }
+    if (gateCompleted) {
+        logEntry.gate_completed = gateCompleted;
+    }
+    // Build updated state
+    const updatedState = {
+        ...stateData,
+        current_state: target,
+        gates_skipped: [...stateData.gates_skipped, ...gatesSkipped],
+        gates_completed: gateCompleted
+            ? [...stateData.gates_completed, gateCompleted]
+            : [...stateData.gates_completed],
+        plan_validation_passes: planValidationPasses,
+        transitions_log: [...(stateData.transitions_log ?? []), logEntry],
+        updated_at: now,
+    };
+    // Reset state when starting a new cycle
+    if (from === CycleState.CYCLE_COMPLETE && target === CycleState.INIT) {
+        updatedState.cycle_number = stateData.cycle_number + 1;
+        updatedState.gates_skipped = [];
+        updatedState.gates_completed = [];
+        updatedState.plan_validation_passes = 0;
+        updatedState.blockers = [];
+        updatedState.transitions_log = [];
+    }
+    return {
+        transition: [from, target],
+        stateData: updatedState,
+        gatesSkipped,
+        gateCompleted,
+        planValidationEscalation,
+    };
+}
+/**
+ * Get all valid next states from the current state.
+ */
+export function getNextStates(currentState) {
+    return [...TRANSITION_MAP[currentState]];
+}
+/**
+ * Check if a transition is valid without applying it.
+ */
+export function isValidTransition(from, to) {
+    return TRANSITION_MAP[from].includes(to);
+}
+/**
+ * Create initial state data for a new cycle.
+ */
+export function createInitialState(cycleNumber = 1) {
+    const now = new Date().toISOString();
+    return {
+        current_state: CycleState.INIT,
+        cycle_number: cycleNumber,
+        gates_skipped: [],
+        gates_completed: [],
+        plan_validation_passes: 0,
+        blockers: [],
+        transitions_log: [],
+        created_at: now,
+        updated_at: now,
+    };
+}
+/**
+ * Get a human-readable description of the current state.
+ */
+export function describeState(state) {
+    const descriptions = {
+        [CycleState.INIT]: "Project initialized — ready to start",
+        [CycleState.RESEARCHING]: "Research gate — gathering information",
+        [CycleState.PLANNING]: "Plan phase — creating the Plan Brief",
+        [CycleState.VALIDATING_PLAN]: "Plan Validation gate — checking the brief",
+        [CycleState.BUILDING]: "Build phase — executing against the plan",
+        [CycleState.VALIDATING_BUILD]: "Build Validation gate — checking the output",
+        [CycleState.REVIEWING_PRE]: "Pre-ship Review gate — final check before shipping",
+        [CycleState.READY_TO_SHIP]: "Ready to ship — all checks passed",
+        [CycleState.SHIPPED]: "Shipped — work delivered",
+        [CycleState.REVIEWING_POST]: "Post-ship Review gate — reflecting on the cycle",
+        [CycleState.CYCLE_COMPLETE]: "Cycle complete — ready for next cycle",
+    };
+    return descriptions[state];
+}
+/**
+ * Get the suggested next command for a given state.
+ */
+export function suggestNextCommand(state) {
+    const suggestions = {
+        [CycleState.INIT]: "/solveos:research or /solveos:plan",
+        [CycleState.RESEARCHING]: "Complete research, then /solveos:plan",
+        [CycleState.PLANNING]: "/solveos:validate-plan or /solveos:build",
+        [CycleState.VALIDATING_PLAN]: "Address gaps, then /solveos:plan to refine",
+        [CycleState.BUILDING]: "/solveos:validate-build or /solveos:ship",
+        [CycleState.VALIDATING_BUILD]: "Fix issues or /solveos:review",
+        [CycleState.REVIEWING_PRE]: "Address feedback or proceed to ship",
+        [CycleState.READY_TO_SHIP]: "/solveos:ship",
+        [CycleState.SHIPPED]: "/solveos:review (post-ship) or /solveos:new-cycle",
+        [CycleState.REVIEWING_POST]: "/solveos:new-cycle",
+        [CycleState.CYCLE_COMPLETE]: "/solveos:new-cycle",
+    };
+    return suggestions[state];
+}
+//# sourceMappingURL=state-machine.js.map

package/dist/workflows/state-machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.js","sourceRoot":"","sources":["../../src/workflows/state-machine.ts"],"names":[],"mappings":"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"}

package/dist/workflows/wave-executor.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Wave-based parallel execution engine for the Build phase.
+ *
+ * Implements GSD's wave execution model:
+ *  1. Decompose goal into atomic work units
+ *  2. Analyze dependencies between units
+ *  3. Group independent units into waves (topological sort)
+ *  4. Execute units within a wave concurrently
+ *  5. Wait for all units in a wave before starting the next
+ *
+ * The "execution" is orchestrated by the AI agent — this module manages
+ * the data structures, wave grouping algorithm, and state tracking.
+ * The AI agent (solveos-executor) reads the plan and processes units.
+ */
+import type { WorkUnit, Wave, WaveExecutionPlan, WaveExecutionResult, Granularity } from "../types.js";
+/** Target unit count ranges per granularity level. */
+export declare const GRANULARITY_RANGES: Record<Granularity, {
+    min: number;
+    max: number;
+}>;
+/**
+ * Create a work unit with defaults.
+ * Used by the build command / executor agent to register decomposed units.
+ */
+export declare function createWorkUnit(id: string, name: string, description: string, opts?: {
+    depends_on?: string[];
+    criteria?: string[];
+    discovered?: boolean;
+}): WorkUnit;
+/**
+ * Validate that all dependency references in a unit list are valid
+ * (no dangling references, no self-references, no cycles).
+ *
+ * @returns Array of error messages (empty if valid).
+ */
+export declare function validateDependencies(units: WorkUnit[]): string[];
+/**
+ * Group work units into waves based on dependency analysis.
+ *
+ * Algorithm:
+ *  1. Find all units with no unsatisfied dependencies → Wave 1
+ *  2. Remove those units from the graph
+ *  3. Find the next set of units with satisfied dependencies → Wave 2
+ *  4. Repeat until all units are assigned
+ *
+ * This is essentially Kahn's algorithm for topological sorting,
+ * but instead of producing a linear order, it groups by "level".
+ */
+export declare function groupIntoWaves(units: WorkUnit[]): Wave[];
+/**
+ * Build a complete wave execution plan from a list of work units.
+ * Validates dependencies, groups into waves, and detects single-unit tasks.
+ *
+ * @throws Error if dependency validation fails.
+ */
+export declare function buildExecutionPlan(units: WorkUnit[], granularity: Granularity): WaveExecutionPlan;
+/**
+ * Mark a unit as in-progress.
+ */
+export declare function startUnit(plan: WaveExecutionPlan, unitId: string): void;
+/**
+ * Mark a unit as completed with a summary.
+ */
+export declare function completeUnit(plan: WaveExecutionPlan, unitId: string, summary: string): void;
+/**
+ * Mark a unit as failed with an error message.
+ */
+export declare function failUnit(plan: WaveExecutionPlan, unitId: string, error: string): void;
+/**
+ * Skip a unit (e.g., due to a dependency failure).
+ */
+export declare function skipUnit(plan: WaveExecutionPlan, unitId: string, reason: string): void;
+/**
+ * Skip all units that depend on a failed unit (cascade).
+ * Returns the IDs of units that were skipped.
+ */
+export declare function cascadeSkip(plan: WaveExecutionPlan, failedUnitId: string): string[];
+/**
+ * Add a discovered work unit to the plan.
+ * Discovered units are added to the current or next wave depending on dependencies.
+ */
+export declare function addDiscoveredUnit(plan: WaveExecutionPlan, unit: WorkUnit): void;
+/**
+ * Generate an execution result from the current plan state.
+ */
+export declare function generateResult(plan: WaveExecutionPlan): WaveExecutionResult;
+/**
+ * Get the next wave that needs execution (first wave with pending/in_progress status).
+ * Returns null if all waves are completed or failed.
+ */
+export declare function getNextWave(plan: WaveExecutionPlan): Wave | null;
+/**
+ * Get all pending units in a specific wave.
+ */
+export declare function getPendingUnits(plan: WaveExecutionPlan, waveNumber: number): WorkUnit[];
+/**
+ * Check if a wave is fully completed (all units completed, failed, or skipped).
+ */
+export declare function isWaveComplete(plan: WaveExecutionPlan, waveNumber: number): boolean;
+/**
+ * Check if the entire plan is finished (all units in terminal state).
+ */
+export declare function isPlanComplete(plan: WaveExecutionPlan): boolean;
+/**
+ * Get a progress summary string for display.
+ */
+export declare function getProgressSummary(plan: WaveExecutionPlan): string;
+/**
+ * Render the wave execution plan as a markdown section for STATE.md.
+ */
+export declare function renderPlanMarkdown(plan: WaveExecutionPlan): string;
+//# sourceMappingURL=wave-executor.d.ts.map

package/dist/workflows/wave-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wave-executor.d.ts","sourceRoot":"","sources":["../../src/workflows/wave-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,QAAQ,EAER,IAAI,EACJ,iBAAiB,EACjB,mBAAmB,EAEnB,WAAW,EACZ,MAAM,aAAa,CAAC;AAMrB,sDAAsD;AACtD,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,WAAW,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAIhF,CAAC;AAMF;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE;IACL,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,GACA,QAAQ,CAUV;AAMD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,CAuBhE;AAqED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,CAsDxD;AAMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,QAAQ,EAAE,EACjB,WAAW,EAAE,WAAW,GACvB,iBAAiB,CAiBnB;AAMD;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAYvE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAU3F;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAUrF;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAItF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAoBnF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,iBAAiB,EACvB,IAAI,EAAE,QAAQ,GACb,IAAI,CA8BN;AAMD;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,CAgC3E;AAMD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAEhE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,GAAG,QAAQ,EAAE,CAMvF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAOnF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAI/D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAmBlE;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAiClE"}