@cleocode/core 2.0.0

package/dist/lifecycle/state-machine.js

@@ -0,0 +1,512 @@
+/**
+ * Pipeline State Machine - Core Logic
+ *
+ * Implements the finite state machine for pipeline lifecycle management.
+ * Handles state transitions, prerequisite validation, and transition history.
+ *
+ * State Machine States:
+ *   not_started → in_progress → completed
+ *                        ↓
+ *                   blocked/failed
+ *                        ↓
+ *                    skipped
+ *
+ * @task T4800 - Implement Canonical SQLite Pipeline State Machine
+ * @epic T4798 - Lifecycle persistence improvements
+ * @audit T4799 - Unified state machine replaces scattered logic
+ * @depends T4801 - Schema design
+ * @depends stages.ts - Stage definitions and transition rules
+ */
+import { ExitCode } from '@cleocode/contracts';
+import { CleoError } from '../errors.js';
+import { checkTransition, getPrerequisites, PIPELINE_STAGES, STAGE_DEFINITIONS } from './stages.js';
+// =============================================================================
+// PREREQUISITE CHECKING
+// =============================================================================
+/**
+ * Check if prerequisites are met for a stage.
+ *
+ * Validates that all prerequisite stages are in an acceptable state
+ * (completed or skipped) for the target stage to proceed.
+ *
+ * @param targetStage - The stage to check prerequisites for
+ * @param currentStages - Current state of all stages
+ * @throws {CleoError} If validation fails
+ * @returns Promise resolving to PrereqCheck result
+ *
+ * @example
+ * ```typescript
+ * const check = await checkPrerequisites('implement', {
+ *   research: { status: 'completed' },
+ *   spec: { status: 'completed' },
+ *   decompose: { status: 'completed' },
+ *   // ... other stages
+ * });
+ * if (check.met) {
+ *   console.log('Ready to implement');
+ * }
+ * ```
+ *
+ * @task T4800
+ * @depends T4801 - Requires pipeline_stages table
+ */
+export async function checkPrerequisites(targetStage, currentStages) {
+    // Calculate prerequisites from provided currentStages map
+    const prerequisites = getPrerequisites(targetStage);
+    const completed = [];
+    const pending = [];
+    const failed = [];
+    const blockers = [];
+    for (const prereq of prerequisites) {
+        const stageState = currentStages[prereq];
+        if (!stageState) {
+            pending.push(prereq);
+            blockers.push({
+                stage: prereq,
+                reason: 'Stage not initialized',
+                severity: 'error',
+            });
+            continue;
+        }
+        switch (stageState.status) {
+            case 'completed':
+            case 'skipped':
+                completed.push(prereq);
+                break;
+            case 'in_progress':
+                pending.push(prereq);
+                blockers.push({
+                    stage: prereq,
+                    reason: 'Stage still in progress',
+                    severity: 'error',
+                });
+                break;
+            case 'not_started':
+                pending.push(prereq);
+                blockers.push({
+                    stage: prereq,
+                    reason: 'Stage not started',
+                    severity: 'error',
+                });
+                break;
+            case 'blocked':
+                pending.push(prereq);
+                blockers.push({
+                    stage: prereq,
+                    reason: 'Stage is blocked',
+                    severity: 'error',
+                });
+                break;
+            case 'failed':
+                failed.push(prereq);
+                blockers.push({
+                    stage: prereq,
+                    reason: 'Stage failed',
+                    severity: 'error',
+                });
+                break;
+        }
+    }
+    const met = blockers.filter((b) => b.severity === 'error').length === 0;
+    const canForce = blockers.every((b) => b.severity !== 'error' || b.reason !== 'Stage not initialized');
+    let summary;
+    if (met) {
+        summary = `All ${prerequisites.length} prerequisites met for ${targetStage}`;
+    }
+    else {
+        const errorCount = blockers.filter((b) => b.severity === 'error').length;
+        summary = `${errorCount} prerequisite(s) blocking ${targetStage}`;
+    }
+    return {
+        met,
+        prerequisites,
+        completed,
+        pending,
+        failed,
+        blockers,
+        canForce,
+        summary,
+    };
+}
+/**
+ * Validate a stage transition.
+ *
+ * Comprehensive validation that checks both transition rules and prerequisites.
+ * This is the core state machine validation logic.
+ *
+ * @param transition - The transition to validate
+ * @param context - Current state machine context
+ * @throws {CleoError} If validation fails unexpectedly
+ * @returns Promise resolving to TransitionValidation
+ *
+ * @example
+ * ```typescript
+ * const validation = await validateTransition(
+ *   { from: 'spec', to: 'implement', initiatedBy: 'agent-001' },
+ *   pipelineContext
+ * );
+ * if (!validation.valid) {
+ *   console.log(validation.errors);
+ * }
+ * ```
+ *
+ * @task T4800
+ */
+export async function validateTransition(transition, context) {
+    const { from, to, force } = transition;
+    const errors = [];
+    const warnings = [];
+    // Check transition rules
+    const ruleCheck = checkTransition(from, to, force);
+    if (!ruleCheck.allowed && !ruleCheck.requiresForce) {
+        errors.push(ruleCheck.reason || `Transition from ${from} to ${to} is not allowed`);
+    }
+    if (ruleCheck.requiresForce && !force) {
+        errors.push(ruleCheck.reason || `Transition from ${from} to ${to} requires force flag`);
+    }
+    // Check prerequisites for target stage
+    let prereqCheck;
+    if (!transition.skipValidation) {
+        prereqCheck = await checkPrerequisites(to, context.stages);
+        if (!prereqCheck.met) {
+            if (!force) {
+                for (const blocker of prereqCheck.blockers) {
+                    errors.push(`${blocker.stage}: ${blocker.reason}`);
+                }
+            }
+            else {
+                warnings.push('Prerequisites not met but force flag is set');
+                for (const blocker of prereqCheck.blockers) {
+                    warnings.push(`${blocker.stage}: ${blocker.reason}`);
+                }
+            }
+        }
+    }
+    // Validate current stage matches context
+    if (context.currentStage !== from) {
+        errors.push(`Current stage mismatch: context has ${context.currentStage}, ` +
+            `but transition is from ${from}`);
+    }
+    // Check stage status allows transition
+    const fromState = context.stages[from];
+    if (!fromState) {
+        errors.push(`Source stage ${from} not found in context`);
+    }
+    else if (fromState.status === 'not_started') {
+        errors.push(`Cannot transition from ${from}: stage has not started`);
+    }
+    else if (fromState.status === 'completed') {
+        warnings.push(`Source stage ${from} is already completed`);
+    }
+    const valid = errors.length === 0;
+    return {
+        valid,
+        from,
+        to,
+        prerequisitesMet: prereqCheck?.met ?? true,
+        ruleAllowed: ruleCheck.allowed || (ruleCheck.requiresForce && !!force),
+        requiresForce: ruleCheck.requiresForce,
+        errors,
+        warnings,
+        prereqCheck,
+    };
+}
+// =============================================================================
+// STATE TRANSITION EXECUTION
+// =============================================================================
+/**
+ * Execute a state transition.
+ *
+ * Applies the transition to the state machine context, updating stage statuses
+ * and returning the new state. This function does NOT persist to database -
+ * that is handled by the pipeline module.
+ *
+ * @param transition - The transition to execute
+ * @param context - Current state machine context
+ * @throws {CleoError} If transition is invalid
+ * @returns Promise resolving to StateTransitionResult
+ *
+ * @example
+ * ```typescript
+ * const result = await executeTransition(
+ *   { from: 'spec', to: 'implement', initiatedBy: 'agent-001' },
+ *   pipelineContext
+ * );
+ * if (result.success) {
+ *   console.log(`Transitioned to ${result.newState.stage}`);
+ * }
+ * ```
+ *
+ * @task T4800
+ */
+export async function executeTransition(transition, context) {
+    // Validate first
+    const validation = await validateTransition(transition, context);
+    if (!validation.valid) {
+        return {
+            success: false,
+            transition,
+            previousState: context.stages[transition.from],
+            newState: context.stages[transition.from], // No change
+            context,
+            timestamp: new Date(),
+            errors: validation.errors,
+        };
+    }
+    const now = new Date();
+    const { from, to } = transition;
+    // Create new context (immutable update)
+    const newContext = {
+        ...context,
+        currentStage: to,
+        transitionCount: context.transitionCount + 1,
+        version: context.version + 1,
+        stages: { ...context.stages },
+    };
+    // Update from stage
+    newContext.stages[from] = {
+        ...context.stages[from],
+        status: 'completed',
+        completedAt: now,
+    };
+    // Update to stage
+    const toStageCurrent = context.stages[to];
+    newContext.stages[to] = {
+        ...toStageCurrent,
+        stage: to,
+        status: 'in_progress',
+        startedAt: toStageCurrent?.startedAt || now,
+    };
+    return {
+        success: true,
+        transition,
+        previousState: context.stages[from],
+        newState: newContext.stages[to],
+        context: newContext,
+        timestamp: now,
+    };
+}
+// =============================================================================
+// STAGE STATUS MANAGEMENT
+// =============================================================================
+/**
+ * Set the status of a stage.
+ *
+ * Updates stage status with validation of allowed state transitions.
+ *
+ * @param stage - The stage to update
+ * @param status - The new status
+ * @param context - Current state machine context
+ * @throws {CleoError} If status transition is invalid
+ * @returns Updated StageState
+ *
+ * @task T4800
+ */
+export function setStageStatus(stage, status, context) {
+    const currentState = context.stages[stage];
+    if (!currentState) {
+        throw new CleoError(ExitCode.NOT_FOUND, `Stage ${stage} not found in context`);
+    }
+    // Validate status transition
+    const validTransition = isValidStatusTransition(currentState.status, status);
+    if (!validTransition.valid) {
+        throw new CleoError(ExitCode.LIFECYCLE_TRANSITION_INVALID, `Invalid status transition from ${currentState.status} to ${status}: ${validTransition.reason}`);
+    }
+    const now = new Date();
+    const updatedState = {
+        ...currentState,
+        status,
+    };
+    // Set timestamps based on status
+    if (status === 'in_progress' && !currentState.startedAt) {
+        updatedState.startedAt = now;
+    }
+    if (status === 'completed' || status === 'skipped') {
+        updatedState.completedAt = now;
+    }
+    return updatedState;
+}
+/**
+ * Get the status of a stage.
+ *
+ * @param stage - The stage to check
+ * @param context - Current state machine context
+ * @returns The stage status
+ *
+ * @task T4800
+ */
+export function getStageStatus(stage, context) {
+    return context.stages[stage]?.status ?? 'not_started';
+}
+/**
+ * Check if a status transition is valid.
+ *
+ * State transitions:
+ *   not_started → in_progress, skipped
+ *   in_progress → completed, blocked, failed
+ *   blocked     → in_progress
+ *   failed      → in_progress (retry)
+ *   completed   → (no transition - use force to override)
+ *   skipped     → (no transition)
+ *
+ * @param from - Current status
+ * @param to - Target status
+ * @returns Object with valid flag and reason
+ *
+ * @task T4800
+ */
+export function isValidStatusTransition(from, to) {
+    // Same status - always valid (idempotent)
+    if (from === to) {
+        return { valid: true };
+    }
+    const validTransitions = {
+        not_started: ['in_progress', 'skipped'],
+        in_progress: ['completed', 'blocked', 'failed', 'not_started'],
+        blocked: ['in_progress', 'failed'],
+        failed: ['in_progress', 'not_started'],
+        completed: [],
+        skipped: [],
+    };
+    const allowed = validTransitions[from]?.includes(to);
+    if (!allowed) {
+        return {
+            valid: false,
+            reason: `Cannot transition from ${from} to ${to}. ` +
+                `Allowed: ${validTransitions[from]?.join(', ') || 'none'}`,
+        };
+    }
+    return { valid: true };
+}
+// =============================================================================
+// STATE MACHINE CONTEXT OPERATIONS
+// =============================================================================
+/**
+ * Create initial state machine context for a pipeline.
+ *
+ * @param pipelineId - The pipeline/task ID
+ * @param assignedAgent - Optional agent to assign
+ * @returns Initial StateMachineContext
+ *
+ * @task T4800
+ */
+export function createInitialContext(pipelineId, assignedAgent) {
+    const now = new Date();
+    const stages = {};
+    for (const stage of PIPELINE_STAGES) {
+        stages[stage] = {
+            stage,
+            status: stage === 'research' ? 'in_progress' : 'not_started',
+            assignedAgent,
+        };
+    }
+    // Set research started timestamp
+    stages['research'].startedAt = now;
+    return {
+        pipelineId,
+        currentStage: 'research',
+        stages,
+        transitionCount: 0,
+        version: 1,
+    };
+}
+/**
+ * Get stages that can be transitioned to from the current stage.
+ *
+ * @param context - Current state machine context
+ * @param includeForce - Whether to include transitions that require force
+ * @returns Array of valid next stages
+ *
+ * @task T4800
+ */
+export function getValidNextStages(context, includeForce = false) {
+    return PIPELINE_STAGES.filter((stage) => {
+        if (stage === context.currentStage)
+            return false;
+        const checkResult = checkTransition(context.currentStage, stage, includeForce);
+        return checkResult.allowed || (includeForce && checkResult.requiresForce);
+    });
+}
+/**
+ * Get the current stage state.
+ *
+ * @param context - State machine context
+ * @returns Current StageState
+ *
+ * @task T4800
+ */
+export function getCurrentStageState(context) {
+    return context.stages[context.currentStage];
+}
+/**
+ * Check if the pipeline is in a terminal state.
+ *
+ * @param context - State machine context
+ * @returns True if in release stage and completed
+ *
+ * @task T4800
+ */
+export function isTerminalState(context) {
+    return context.currentStage === 'release' && context.stages['release'].status === 'completed';
+}
+/**
+ * Check if the pipeline is blocked.
+ *
+ * @param context - State machine context
+ * @returns True if current stage is blocked
+ *
+ * @task T4800
+ */
+export function isBlocked(context) {
+    return context.stages[context.currentStage].status === 'blocked';
+}
+// =============================================================================
+// BATCH OPERATIONS
+// =============================================================================
+/**
+ * Validate multiple transitions.
+ *
+ * @param transitions - Array of transitions to validate
+ * @param context - State machine context
+ * @returns Array of validation results
+ *
+ * @task T4800
+ */
+export async function validateTransitions(transitions, context) {
+    return Promise.all(transitions.map((t) => validateTransition(t, context)));
+}
+/**
+ * Check if a stage can be skipped.
+ *
+ * @param stage - The stage to check
+ * @returns True if stage is skippable
+ *
+ * @task T4800
+ */
+export function canSkipStage(stage) {
+    return STAGE_DEFINITIONS[stage].skippable;
+}
+/**
+ * Skip a stage with validation.
+ *
+ * @param stage - The stage to skip
+ * @param reason - Reason for skipping
+ * @param context - State machine context
+ * @throws {CleoError} If stage cannot be skipped
+ * @returns Updated StageState
+ *
+ * @task T4800
+ */
+export function skipStage(stage, _reason, context) {
+    if (!canSkipStage(stage)) {
+        throw new CleoError(ExitCode.LIFECYCLE_TRANSITION_INVALID, `Stage ${stage} cannot be skipped`, {
+            fix: `Complete the ${stage} stage or use force flag`,
+        });
+    }
+    const currentState = context.stages[stage];
+    if (currentState.status === 'completed') {
+        throw new CleoError(ExitCode.LIFECYCLE_TRANSITION_INVALID, `Cannot skip ${stage}: already completed`);
+    }
+    return setStageStatus(stage, 'skipped', context);
+}
+//# sourceMappingURL=state-machine.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.js","sourceRoot":"","sources":["../../src/lifecycle/state-machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAoIpG,gFAAgF;AAChF,wBAAwB;AACxB,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,WAAkB,EAClB,aAAwC;IAExC,0DAA0D;IAC1D,MAAM,aAAa,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;IAEpD,MAAM,SAAS,GAAY,EAAE,CAAC;IAC9B,MAAM,OAAO,GAAY,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAE7C,KAAK,MAAM,MAAM,IAAI,aAAa,EAAE,CAAC;QACnC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QAEzC,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrB,QAAQ,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,MAAM;gBACb,MAAM,EAAE,uBAAuB;gBAC/B,QAAQ,EAAE,OAAO;aAClB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,QAAQ,UAAU,CAAC,MAAM,EAAE,CAAC;YAC1B,KAAK,WAAW,CAAC;YACjB,KAAK,SAAS;gBACZ,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACvB,MAAM;YACR,KAAK,aAAa;gBAChB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACrB,QAAQ,CAAC,IAAI,CAAC;oBACZ,KAAK,EAAE,MAAM;oBACb,MAAM,EAAE,yBAAyB;oBACjC,QAAQ,EAAE,OAAO;iBAClB,CAAC,CAAC;gBACH,MAAM;YACR,KAAK,aAAa;gBAChB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACrB,QAAQ,CAAC,IAAI,CAAC;oBACZ,KAAK,EAAE,MAAM;oBACb,MAAM,EAAE,mBAAmB;oBAC3B,QAAQ,EAAE,OAAO;iBAClB,CAAC,CAAC;gBACH,MAAM;YACR,KAAK,SAAS;gBACZ,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACrB,QAAQ,CAAC,IAAI,CAAC;oBACZ,KAAK,EAAE,MAAM;oBACb,MAAM,EAAE,kBAAkB;oBAC1B,QAAQ,EAAE,OAAO;iBAClB,CAAC,CAAC;gBACH,MAAM;YACR,KAAK,QAAQ;gBACX,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACpB,QAAQ,CAAC,IAAI,CAAC;oBACZ,KAAK,EAAE,MAAM;oBACb,MAAM,EAAE,cAAc;oBACtB,QAAQ,EAAE,OAAO;iBAClB,CAAC,CAAC;gBACH,MAAM;QACV,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;IACxE,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAC7B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,CAAC,MAAM,KAAK,uBAAuB,CACtE,CAAC;IAEF,IAAI,OAAe,CAAC;IACpB,IAAI,GAAG,EAAE,CAAC;QACR,OAAO,GAAG,OAAO,aAAa,CAAC,MAAM,0BAA0B,WAAW,EAAE,CAAC;IAC/E,CAAC;SAAM,CAAC;QACN,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,MAAM,CAAC;QACzE,OAAO,GAAG,GAAG,UAAU,6BAA6B,WAAW,EAAE,CAAC;IACpE,CAAC;IAED,OAAO;QACL,GAAG;QACH,aAAa;QACb,SAAS;QACT,OAAO;QACP,MAAM;QACN,QAAQ;QACR,QAAQ;QACR,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,UAA2B,EAC3B,OAA4B;IAE5B,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,UAAU,CAAC;IACvC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,yBAAyB;IACzB,MAAM,SAAS,GAAG,eAAe,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;IAEnD,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,aAAa,EAAE,CAAC;QACnD,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,mBAAmB,IAAI,OAAO,EAAE,iBAAiB,CAAC,CAAC;IACrF,CAAC;IAED,IAAI,SAAS,CAAC,aAAa,IAAI,CAAC,KAAK,EAAE,CAAC;QACtC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,mBAAmB,IAAI,OAAO,EAAE,sBAAsB,CAAC,CAAC;IAC1F,CAAC;IAED,uCAAuC;IACvC,IAAI,WAAoC,CAAC;IAEzC,IAAI,CAAC,UAAU,CAAC,cAAc,EAAE,CAAC;QAC/B,WAAW,GAAG,MAAM,kBAAkB,CAAC,EAAE,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAE3D,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;YACrB,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,KAAK,MAAM,OAAO,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC;oBAC3C,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,KAAK,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;gBACrD,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,QAAQ,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAC;gBAC7D,KAAK,MAAM,OAAO,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC;oBAC3C,QAAQ,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,KAAK,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;gBACvD,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,yCAAyC;IACzC,IAAI,OAAO,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;QAClC,MAAM,CAAC,IAAI,CACT,uCAAuC,OAAO,CAAC,YAAY,IAAI;YAC7D,0BAA0B,IAAI,EAAE,CACnC,CAAC;IACJ,CAAC;IAED,uCAAuC;IACvC,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CAAC,gBAAgB,IAAI,uBAAuB,CAAC,CAAC;IAC3D,CAAC;SAAM,IAAI,SAAS,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;QAC9C,MAAM,CAAC,IAAI,CAAC,0BAA0B,IAAI,yBAAyB,CAAC,CAAC;IACvE,CAAC;SAAM,IAAI,SAAS,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QAC5C,QAAQ,CAAC,IAAI,CAAC,gBAAgB,IAAI,uBAAuB,CAAC,CAAC;IAC7D,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC;IAElC,OAAO;QACL,KAAK;QACL,IAAI;QACJ,EAAE;QACF,gBAAgB,EAAE,WAAW,EAAE,GAAG,IAAI,IAAI;QAC1C,WAAW,EAAE,SAAS,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,aAAa,IAAI,CAAC,CAAC,KAAK,CAAC;QACtE,aAAa,EAAE,SAAS,CAAC,aAAa;QACtC,MAAM;QACN,QAAQ;QACR,WAAW;KACZ,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,6BAA6B;AAC7B,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,UAA2B,EAC3B,OAA4B;IAE5B,iBAAiB;IACjB,MAAM,UAAU,GAAG,MAAM,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAEjE,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACtB,OAAO;YACL,OAAO,EAAE,KAAK;YACd,UAAU;YACV,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC;YAC9C,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,YAAY;YACvD,OAAO;YACP,SAAS,EAAE,IAAI,IAAI,EAAE;YACrB,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,UAAU,CAAC;IAEhC,wCAAwC;IACxC,MAAM,UAAU,GAAwB;QACtC,GAAG,OAAO;QACV,YAAY,EAAE,EAAE;QAChB,eAAe,EAAE,OAAO,CAAC,eAAe,GAAG,CAAC;QAC5C,OAAO,EAAE,OAAO,CAAC,OAAO,GAAG,CAAC;QAC5B,MAAM,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE;KAC9B,CAAC;IAEF,oBAAoB;IACpB,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG;QACxB,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;QACvB,MAAM,EAAE,WAAW;QACnB,WAAW,EAAE,GAAG;KACjB,CAAC;IAEF,kBAAkB;IAClB,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1C,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG;QACtB,GAAG,cAAc;QACjB,KAAK,EAAE,EAAE;QACT,MAAM,EAAE,aAAa;QACrB,SAAS,EAAE,cAAc,EAAE,SAAS,IAAI,GAAG;KAC5C,CAAC;IAEF,OAAO;QACL,OAAO,EAAE,IAAI;QACb,UAAU;QACV,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;QACnC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,OAAO,EAAE,UAAU;QACnB,SAAS,EAAE,GAAG;KACf,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,0BAA0B;AAC1B,gFAAgF;AAEhF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAY,EACZ,MAAmB,EACnB,OAA4B;IAE5B,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAE3C,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,IAAI,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,KAAK,uBAAuB,CAAC,CAAC;IACjF,CAAC;IAED,6BAA6B;IAC7B,MAAM,eAAe,GAAG,uBAAuB,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7E,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAC3B,MAAM,IAAI,SAAS,CACjB,QAAQ,CAAC,4BAA4B,EACrC,kCAAkC,YAAY,CAAC,MAAM,OAAO,MAAM,KAAK,eAAe,CAAC,MAAM,EAAE,CAChG,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,YAAY,GAAe;QAC/B,GAAG,YAAY;QACf,MAAM;KACP,CAAC;IAEF,iCAAiC;IACjC,IAAI,MAAM,KAAK,aAAa,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,CAAC;QACxD,YAAY,CAAC,SAAS,GAAG,GAAG,CAAC;IAC/B,CAAC;IAED,IAAI,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACnD,YAAY,CAAC,WAAW,GAAG,GAAG,CAAC;IACjC,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,KAAY,EAAE,OAA4B;IACvE,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,aAAa,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAiB,EACjB,EAAe;IAEf,0CAA0C;IAC1C,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QAChB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IAED,MAAM,gBAAgB,GAAuC;QAC3D,WAAW,EAAE,CAAC,aAAa,EAAE,SAAS,CAAC;QACvC,WAAW,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,CAAC;QAC9D,OAAO,EAAE,CAAC,aAAa,EAAE,QAAQ,CAAC;QAClC,MAAM,EAAE,CAAC,aAAa,EAAE,aAAa,CAAC;QACtC,SAAS,EAAE,EAAE;QACb,OAAO,EAAE,EAAE;KACZ,CAAC;IAEF,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;IAErD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,MAAM,EACJ,0BAA0B,IAAI,OAAO,EAAE,IAAI;gBAC3C,YAAY,gBAAgB,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,EAAE;SAC7D,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC;AAED,gFAAgF;AAChF,mCAAmC;AACnC,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAClC,UAAkB,EAClB,aAAsB;IAEtB,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,MAAM,GAA8B,EAA+B,CAAC;IAE1E,KAAK,MAAM,KAAK,IAAI,eAAe,EAAE,CAAC;QACpC,MAAM,CAAC,KAAK,CAAC,GAAG;YACd,KAAK;YACL,MAAM,EAAE,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,aAAa;YAC5D,aAAa;SACd,CAAC;IACJ,CAAC;IAED,iCAAiC;IACjC,MAAM,CAAC,UAAU,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC;IAEnC,OAAO;QACL,UAAU;QACV,YAAY,EAAE,UAAU;QACxB,MAAM;QACN,eAAe,EAAE,CAAC;QAClB,OAAO,EAAE,CAAC;KACX,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA4B,EAC5B,eAAwB,KAAK;IAE7B,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QACtC,IAAI,KAAK,KAAK,OAAO,CAAC,YAAY;YAAE,OAAO,KAAK,CAAC;QAEjD,MAAM,WAAW,GAAG,eAAe,CAAC,OAAO,CAAC,YAAY,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;QAC/E,OAAO,WAAW,CAAC,OAAO,IAAI,CAAC,YAAY,IAAI,WAAW,CAAC,aAAa,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAA4B;IAC/D,OAAO,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,OAA4B;IAC1D,OAAO,OAAO,CAAC,YAAY,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC;AAChG,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,OAA4B;IACpD,OAAO,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC;AACnE,CAAC;AAED,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,WAA8B,EAC9B,OAA4B;IAE5B,OAAO,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAY;IACvC,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CAAC,KAAY,EAAE,OAAe,EAAE,OAA4B;IACnF,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,SAAS,CAAC,QAAQ,CAAC,4BAA4B,EAAE,SAAS,KAAK,oBAAoB,EAAE;YAC7F,GAAG,EAAE,gBAAgB,KAAK,0BAA0B;SACrD,CAAC,CAAC;IACL,CAAC;IAED,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAE3C,IAAI,YAAY,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QACxC,MAAM,IAAI,SAAS,CACjB,QAAQ,CAAC,4BAA4B,EACrC,eAAe,KAAK,qBAAqB,CAC1C,CAAC;IACJ,CAAC;IAED,OAAO,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AACnD,CAAC"}

package/dist/lifecycle/tessera-engine.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Tessera Instantiation Engine
+ *
+ * Provides template management and instantiation for parameterized
+ * WarpChain workflows. Wraps buildDefaultChain() with template
+ * variables and manages the template registry.
+ *
+ * @task T5409
+ */
+import type { TesseraInstantiationInput, TesseraTemplate } from '@cleocode/contracts';
+import type { WarpChainInstance } from '@cleocode/contracts';
+/**
+ * Build the default RCASD Tessera template.
+ *
+ * Wraps buildDefaultChain() with template variables:
+ * - epicId (required, type 'epicId')
+ * - projectName (optional, type 'string', default 'unnamed')
+ * - skipResearch (optional, type 'boolean', default false)
+ *
+ * @task T5409
+ */
+export declare function buildDefaultTessera(): TesseraTemplate;
+/**
+ * Instantiate a Tessera template into a concrete WarpChainInstance.
+ *
+ * Steps:
+ * 1. Validate all required variables are provided
+ * 2. Apply defaults for missing optional variables
+ * 3. Construct concrete WarpChain from template
+ * 4. Validate chain via validateChain()
+ * 5. Store via createInstance() from chain-store
+ * 6. Return instance
+ *
+ * @task T5409
+ */
+export declare function instantiateTessera(template: TesseraTemplate, input: TesseraInstantiationInput, projectRoot: string): Promise<WarpChainInstance>;
+/**
+ * List all registered Tessera templates.
+ *
+ * @task T5409
+ */
+export declare function listTesseraTemplates(): TesseraTemplate[];
+/**
+ * Find a Tessera template by ID.
+ *
+ * @task T5409
+ */
+export declare function showTessera(id: string): TesseraTemplate | null;
+//# sourceMappingURL=tessera-engine.d.ts.map

package/dist/lifecycle/tessera-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tessera-engine.d.ts","sourceRoot":"","sources":["../../src/lifecycle/tessera-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,yBAAyB,EACzB,eAAe,EAEhB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAa,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AA6JxE;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,eAAe,CAoCrD;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,yBAAyB,EAChC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,iBAAiB,CAAC,CA6C5B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,EAAE,CAGxD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAG9D"}