@kynetic-ai/spec 0.1.2 → 0.4.0

package/dist/cli/commands/workflow.js

@@ -0,0 +1,851 @@
+/**
+ * Workflow run CLI commands
+ *
+ * Implements workflow run lifecycle management:
+ * - kspec workflow start @ref [--task @ref] [--json]
+ * - kspec workflow runs [--active] [--completed] [--workflow @ref] [--json]
+ * - kspec workflow show @run [--json]
+ * - kspec workflow abort @run [--reason text] [--json]
+ * - kspec workflow complete @run [--result <result>] [--json]
+ */
+import chalk from "chalk";
+import Table from "cli-table3";
+import { ulid } from "ulid";
+import { markMutating } from "../command-annotations.js";
+import { deleteWorkflowRuns, findActiveRuns, findWorkflowRunByRef, getAuthor, initContext, loadAllTasks, loadMetaContext, loadWorkflowRuns, ReferenceIndex, saveWorkflowRun, updateWorkflowRun, } from "../../parser/index.js";
+import { commitIfShadow } from "../../parser/shadow.js";
+import { WorkflowRunResultSchema } from "../../schema/index.js";
+import { errors } from "../../strings/errors.js";
+import { EXIT_CODES } from "../exit-codes.js";
+import { error, isJsonMode, output, success } from "../output.js";
+/**
+ * Find a workflow by reference
+ */
+function resolveWorkflowRef(ref, workflows) {
+    const cleanRef = ref.startsWith("@") ? ref.slice(1) : ref;
+    // Try by ID first
+    let workflow = workflows.find((w) => w.id === cleanRef);
+    if (workflow)
+        return workflow;
+    // Try by ULID or ULID prefix
+    workflow = workflows.find((w) => w._ulid === cleanRef ||
+        w._ulid.toLowerCase().startsWith(cleanRef.toLowerCase()));
+    return workflow || null;
+}
+/**
+ * Format a short ULID (first 8 chars)
+ */
+function shortUlid(ulid) {
+    return ulid.slice(0, 8).toUpperCase();
+}
+/**
+ * Format run status with color
+ */
+function formatStatus(status) {
+    switch (status) {
+        case "active":
+            return chalk.green(status);
+        case "paused":
+            return chalk.yellow(status);
+        case "completed":
+            return chalk.blue(status);
+        case "aborted":
+            return chalk.red(status);
+        default:
+            return status;
+    }
+}
+/**
+ * Command: kspec workflow start @workflow-ref [--task @task-ref] [--json]
+ * AC: @workflow-run-foundation ac-1, ac-6
+ */
+async function workflowStart(workflowRef, options) {
+    const ctx = await initContext();
+    const metaCtx = await loadMetaContext(ctx);
+    // DEBUG: Log loaded workflows
+    // Resolve workflow reference
+    const workflow = resolveWorkflowRef(workflowRef, metaCtx.workflows);
+    if (!workflow) {
+        error(errors.workflowRun.workflowNotFound(workflowRef));
+        process.exit(EXIT_CODES.NOT_FOUND);
+    }
+    // Validate task reference if provided (AC: @workflow-run-foundation ac-6)
+    let taskRef;
+    if (options.task) {
+        const tasks = await loadAllTasks(ctx);
+        const index = new ReferenceIndex(tasks, []);
+        const result = index.resolve(options.task);
+        if (!result.ok) {
+            error(errors.reference.taskNotFound(options.task));
+            process.exit(EXIT_CODES.NOT_FOUND);
+        }
+        taskRef = `@${result.ulid}`;
+    }
+    // Create new workflow run
+    const run = {
+        _ulid: ulid(),
+        workflow_ref: `@${workflow._ulid}`,
+        status: "active",
+        current_step: 0,
+        total_steps: workflow.steps.length,
+        started_at: new Date().toISOString(),
+        step_results: [],
+        initiated_by: getAuthor(ctx.config?.identity?.author),
+        task_ref: taskRef,
+    };
+    // Save the run
+    await saveWorkflowRun(ctx, run);
+    // Commit to shadow
+    await commitIfShadow(ctx.shadow, "workflow-start");
+    // Output result
+    if (isJsonMode()) {
+        output({
+            run_id: run._ulid,
+            workflow_ref: run.workflow_ref,
+            status: run.status,
+        });
+    }
+    else {
+        success(`Started workflow run: ${shortUlid(run._ulid)}`);
+        console.log(`  Workflow: ${workflow.id}`);
+        console.log(`  Steps: ${run.total_steps}`);
+        if (taskRef) {
+            console.log(`  Linked task: ${taskRef}`);
+        }
+    }
+}
+/**
+ * Command: kspec workflow runs [--active] [--completed] [--workflow @ref] [--json]
+ * AC: @workflow-run-foundation ac-2
+ */
+async function workflowRuns(options) {
+    const ctx = await initContext();
+    const metaCtx = await loadMetaContext(ctx);
+    let runs = await loadWorkflowRuns(ctx);
+    // Apply filters
+    if (options.active) {
+        runs = runs.filter((r) => r.status === "active");
+    }
+    if (options.completed) {
+        runs = runs.filter((r) => r.status === "completed");
+    }
+    if (options.workflow) {
+        const workflow = resolveWorkflowRef(options.workflow, metaCtx.workflows);
+        if (!workflow) {
+            error(errors.workflowRun.workflowNotFound(options.workflow));
+            process.exit(EXIT_CODES.NOT_FOUND);
+        }
+        runs = runs.filter((r) => r.workflow_ref === `@${workflow._ulid}`);
+    }
+    if (isJsonMode()) {
+        output({ runs });
+    }
+    else {
+        if (runs.length === 0) {
+            console.log(chalk.gray("No workflow runs found"));
+            return;
+        }
+        const table = new Table({
+            head: ["ID", "Workflow", "Status", "Step", "Started"],
+            colWidths: [12, 25, 12, 10, 20],
+        });
+        for (const run of runs) {
+            const workflow = metaCtx.workflows.find((w) => `@${w._ulid}` === run.workflow_ref);
+            const workflowName = workflow?.id || run.workflow_ref;
+            const stepProgress = `${run.current_step + 1}/${run.total_steps}`;
+            const started = new Date(run.started_at).toLocaleString();
+            table.push([
+                shortUlid(run._ulid),
+                workflowName,
+                formatStatus(run.status),
+                stepProgress,
+                started,
+            ]);
+        }
+        console.log(table.toString());
+    }
+}
+/**
+ * Command: kspec workflow show @run-id [--json]
+ * AC: @workflow-run-foundation ac-4
+ */
+async function workflowShow(runRef, _options) {
+    const ctx = await initContext();
+    const metaCtx = await loadMetaContext(ctx);
+    const run = await findWorkflowRunByRef(ctx, runRef);
+    if (!run) {
+        error(errors.workflowRun.runNotFound(runRef));
+        process.exit(EXIT_CODES.NOT_FOUND);
+    }
+    if (isJsonMode()) {
+        output({ run });
+    }
+    else {
+        const workflow = metaCtx.workflows.find((w) => `@${w._ulid}` === run.workflow_ref);
+        const workflowName = workflow?.id || run.workflow_ref;
+        console.log(chalk.bold("Workflow Run Details"));
+        console.log(chalk.gray("─".repeat(50)));
+        console.log(`ID:           ${shortUlid(run._ulid)}`);
+        console.log(`Workflow:     ${workflowName} (${run.workflow_ref})`);
+        console.log(`Status:       ${formatStatus(run.status)}`);
+        console.log(`Progress:     ${run.current_step + 1}/${run.total_steps}`);
+        console.log(`Started:      ${new Date(run.started_at).toLocaleString()}`);
+        if (run.initiated_by) {
+            console.log(`Initiated by: ${run.initiated_by}`);
+        }
+        if (run.task_ref) {
+            console.log(`Task:         ${run.task_ref}`);
+        }
+        if (run.paused_at) {
+            console.log(`Paused:       ${new Date(run.paused_at).toLocaleString()}`);
+        }
+        if (run.completed_at) {
+            console.log(`Completed:    ${new Date(run.completed_at).toLocaleString()}`);
+        }
+        if (run.abort_reason) {
+            console.log(`Abort reason: ${run.abort_reason}`);
+        }
+        if (run.step_results.length > 0) {
+            console.log(chalk.gray("\nStep Results:"));
+            const table = new Table({
+                head: ["Step", "Status", "Started", "Completed"],
+                colWidths: [8, 12, 20, 20],
+            });
+            for (const result of run.step_results) {
+                table.push([
+                    (result.step_index + 1).toString(),
+                    formatStatus(result.status),
+                    new Date(result.started_at).toLocaleString(),
+                    new Date(result.completed_at).toLocaleString(),
+                ]);
+            }
+            console.log(table.toString());
+        }
+    }
+}
+/**
+ * Command: kspec workflow abort @run-id [--reason text] [--json]
+ * AC: @workflow-run-foundation ac-3, ac-5
+ */
+async function workflowAbort(runRef, options) {
+    const ctx = await initContext();
+    const run = await findWorkflowRunByRef(ctx, runRef);
+    if (!run) {
+        error(errors.workflowRun.runNotFound(runRef));
+        process.exit(EXIT_CODES.NOT_FOUND);
+    }
+    // AC: @workflow-run-foundation ac-5 - Cannot abort completed or aborted runs
+    if (run.status === "completed") {
+        error(errors.workflowRun.cannotAbortCompleted);
+        process.exit(EXIT_CODES.VALIDATION_FAILED);
+    }
+    if (run.status === "aborted") {
+        error(errors.workflowRun.cannotAbortAborted);
+        process.exit(EXIT_CODES.VALIDATION_FAILED);
+    }
+    // Update run status
+    run.status = "aborted";
+    run.abort_reason = options.reason;
+    run.completed_at = new Date().toISOString();
+    await updateWorkflowRun(ctx, run);
+    await commitIfShadow(ctx.shadow, "workflow-abort");
+    if (isJsonMode()) {
+        output({ run_id: run._ulid, status: run.status });
+    }
+    else {
+        success(`Aborted workflow run: ${shortUlid(run._ulid)}`);
+        if (options.reason) {
+            console.log(`  Reason: ${options.reason}`);
+        }
+    }
+}
+/**
+ * Command: kspec workflow complete @run-id [--result <result>] [--json]
+ * Marks a workflow run as completed with an optional result.
+ * Use this for graceful exits (e.g., no_work_available) instead of aborting.
+ */
+async function workflowComplete(runRef, options) {
+    const ctx = await initContext();
+    const run = await findWorkflowRunByRef(ctx, runRef);
+    if (!run) {
+        error(errors.workflowRun.runNotFound(runRef));
+        process.exit(EXIT_CODES.NOT_FOUND);
+    }
+    // Cannot complete already finished runs
+    if (run.status === "completed") {
+        error(`Cannot complete run ${shortUlid(run._ulid)}: already completed`);
+        process.exit(EXIT_CODES.VALIDATION_FAILED);
+    }
+    if (run.status === "aborted") {
+        error(`Cannot complete run ${shortUlid(run._ulid)}: already aborted`);
+        process.exit(EXIT_CODES.VALIDATION_FAILED);
+    }
+    // Validate result if provided
+    let result;
+    if (options.result) {
+        const parseResult = WorkflowRunResultSchema.safeParse(options.result);
+        if (!parseResult.success) {
+            const validResults = WorkflowRunResultSchema.options.join(", ");
+            error(`Invalid result: ${options.result}. Must be one of: ${validResults}`);
+            process.exit(EXIT_CODES.VALIDATION_FAILED);
+        }
+        result = parseResult.data;
+    }
+    // Update run status
+    run.status = "completed";
+    run.completed_at = new Date().toISOString();
+    if (result) {
+        run.result = result;
+    }
+    await updateWorkflowRun(ctx, run);
+    await commitIfShadow(ctx.shadow, "workflow-complete");
+    if (isJsonMode()) {
+        output({
+            run_id: run._ulid,
+            status: run.status,
+            result: run.result,
+            completed_at: run.completed_at,
+        });
+    }
+    else {
+        const resultInfo = run.result ? ` (${run.result})` : "";
+        success(`Completed workflow run: ${shortUlid(run._ulid)}${resultInfo}`);
+    }
+}
+/**
+ * Command: kspec workflow pause @run-id [--json]
+ * AC: @workflow-advanced-features ac-1
+ */
+async function workflowPause(runRef, _options) {
+    const ctx = await initContext();
+    const run = await findWorkflowRunByRef(ctx, runRef);
+    if (!run) {
+        error(errors.workflowRun.runNotFound(runRef));
+        process.exit(EXIT_CODES.NOT_FOUND);
+    }
+    // Only active runs can be paused
+    if (run.status !== "active") {
+        error(`Cannot pause run ${shortUlid(run._ulid)}: current status is ${run.status}`);
+        process.exit(EXIT_CODES.VALIDATION_FAILED);
+    }
+    // Update run status
+    run.status = "paused";
+    run.paused_at = new Date().toISOString();
+    await updateWorkflowRun(ctx, run);
+    await commitIfShadow(ctx.shadow, "workflow-pause");
+    if (isJsonMode()) {
+        output({ run_id: run._ulid, status: run.status, paused_at: run.paused_at });
+    }
+    else {
+        success(`Paused run ${shortUlid(run._ulid)} at step ${run.current_step + 1}/${run.total_steps}`);
+    }
+}
+/**
+ * Command: kspec workflow resume @run-id [--json]
+ * AC: @workflow-advanced-features ac-2, ac-4
+ */
+async function workflowResume(runRef, _options) {
+    const ctx = await initContext();
+    const metaCtx = await loadMetaContext(ctx);
+    const run = await findWorkflowRunByRef(ctx, runRef);
+    if (!run) {
+        error(errors.workflowRun.runNotFound(runRef));
+        process.exit(EXIT_CODES.NOT_FOUND);
+    }
+    // AC: @workflow-advanced-features ac-4 - Error if not paused
+    if (run.status !== "paused") {
+        error(`Cannot resume run ${shortUlid(run._ulid)}: current status is ${run.status} (expected paused)`);
+        process.exit(EXIT_CODES.VALIDATION_FAILED);
+    }
+    // Update run status
+    run.status = "active";
+    run.paused_at = undefined;
+    await updateWorkflowRun(ctx, run);
+    await commitIfShadow(ctx.shadow, "workflow-resume");
+    // Get workflow definition to show current step
+    const workflow = metaCtx.workflows.find((w) => `@${w._ulid}` === run.workflow_ref);
+    if (!workflow) {
+        error(errors.workflowRun.workflowNotFound(run.workflow_ref));
+        process.exit(EXIT_CODES.NOT_FOUND);
+    }
+    const currentStep = workflow.steps[run.current_step];
+    if (isJsonMode()) {
+        output({
+            run_id: run._ulid,
+            status: run.status,
+            current_step: run.current_step,
+            total_steps: run.total_steps,
+            next_step: {
+                type: currentStep.type,
+                content: currentStep.content,
+            },
+        });
+    }
+    else {
+        success(`Resumed run ${shortUlid(run._ulid)}`);
+        console.log(`\nStep ${run.current_step + 1}/${run.total_steps}: [${currentStep.type}] ${currentStep.content}`);
+    }
+}
+/**
+ * Command: kspec workflow next [run-ref] [--skip] [--notes text] [--confirm] [--force] [--input key=value] [--json]
+ * AC: @workflow-step-navigation ac-1 through ac-6
+ * AC: @workflow-enforcement-modes ac-1 through ac-4
+ * AC: @workflow-advanced-features ac-3
+ */
+async function workflowNext(runRef, options) {
+    const ctx = await initContext();
+    const metaCtx = await loadMetaContext(ctx);
+    let run;
+    // AC: @workflow-step-navigation ac-3, ac-4, ac-5
+    if (!runRef) {
+        const activeRuns = await findActiveRuns(ctx);
+        if (activeRuns.length === 0) {
+            // AC: @workflow-step-navigation ac-5
+            error(errors.workflowRun.noActiveRuns);
+            process.exit(EXIT_CODES.NOT_FOUND);
+        }
+        if (activeRuns.length > 1) {
+            // AC: @workflow-step-navigation ac-4
+            const runIds = activeRuns.map((r) => shortUlid(r._ulid));
+            error(errors.workflowRun.multipleActiveRuns(runIds));
+            process.exit(EXIT_CODES.VALIDATION_FAILED);
+        }
+        // AC: @workflow-step-navigation ac-3 - exactly one active run
+        run = activeRuns[0];
+    }
+    else {
+        run = await findWorkflowRunByRef(ctx, runRef);
+        if (!run) {
+            error(errors.workflowRun.runNotFound(runRef));
+            process.exit(EXIT_CODES.NOT_FOUND);
+        }
+        if (run.status !== "active") {
+            error(errors.workflowRun.runNotActive(runRef, run.status));
+            process.exit(EXIT_CODES.VALIDATION_FAILED);
+        }
+    }
+    // Get workflow definition to access steps
+    const workflow = metaCtx.workflows.find((w) => `@${w._ulid}` === run.workflow_ref);
+    if (!workflow) {
+        error(errors.workflowRun.workflowNotFound(run.workflow_ref));
+        process.exit(EXIT_CODES.NOT_FOUND);
+    }
+    // Get current step and next step
+    const currentStepIndex = run.current_step;
+    const currentStep = workflow.steps[currentStepIndex];
+    const isStrictMode = workflow.enforcement === "strict";
+    const isLastStep = currentStepIndex === run.total_steps - 1;
+    // AC: @workflow-advanced-features ac-3 - Handle step inputs
+    const stepInputs = {};
+    if (currentStep.inputs && currentStep.inputs.length > 0) {
+        // Display required inputs if not in JSON mode
+        if (!isJsonMode()) {
+            console.log(`Step ${currentStepIndex + 1}/${run.total_steps}: [${currentStep.type}] ${currentStep.content}`);
+            console.log(chalk.cyan("  Inputs required:"));
+            for (const input of currentStep.inputs) {
+                const requiredLabel = input.required !== false ? "" : " (optional)";
+                const typeLabel = input.type ? ` (${input.type})` : "";
+                const desc = input.description ? `: ${input.description}` : "";
+                console.log(chalk.cyan(`    - ${input.name}${typeLabel}${requiredLabel}${desc}`));
+            }
+            console.log();
+        }
+        // Parse --input flags
+        if (options.input) {
+            for (const inputStr of options.input) {
+                const [key, ...valueParts] = inputStr.split("=");
+                if (!valueParts.length) {
+                    error(`Invalid input format: "${inputStr}". Expected format: key=value`);
+                    process.exit(EXIT_CODES.VALIDATION_FAILED);
+                }
+                stepInputs[key] = valueParts.join("="); // Rejoin in case value contains '='
+            }
+        }
+        // Validate required inputs
+        for (const input of currentStep.inputs) {
+            if (input.required !== false && !stepInputs[input.name]) {
+                error(`Missing required input: ${input.name}`);
+                process.exit(EXIT_CODES.VALIDATION_FAILED);
+            }
+        }
+    }
+    // AC: @workflow-enforcement-modes ac-3 - Strict mode: --skip requires --force
+    if (options.skip && isStrictMode && !options.force) {
+        error(errors.workflowRun.skipRequiresForce);
+        process.exit(EXIT_CODES.VALIDATION_FAILED);
+    }
+    // AC: @workflow-enforcement-modes ac-2, ac-3 - Check exit criteria for CURRENT step
+    if (currentStep.exit_criteria &&
+        currentStep.exit_criteria.length > 0 &&
+        !options.skip) {
+        // AC: @workflow-enforcement-modes ac-3 - Strict mode requires --confirm
+        if (isStrictMode && !options.confirm) {
+            if (!isJsonMode()) {
+                console.log(`Completing step ${currentStepIndex + 1}/${run.total_steps}: [${currentStep.type}] ${currentStep.content}`);
+                console.log(chalk.yellow("  Exit criteria:"));
+                for (const criterion of currentStep.exit_criteria) {
+                    console.log(chalk.yellow(`    - ${criterion}`));
+                }
+                console.log();
+            }
+            error(errors.workflowRun.exitCriteriaNotConfirmed);
+            process.exit(EXIT_CODES.VALIDATION_FAILED);
+        }
+        // AC: @workflow-enforcement-modes ac-4 - Advisory mode shows criteria as guidance
+        if (!isStrictMode && !isJsonMode()) {
+            console.log(chalk.gray("  Exit criteria:"));
+            for (const criterion of currentStep.exit_criteria) {
+                console.log(chalk.gray(`    - ${criterion}`));
+            }
+        }
+    }
+    // AC: @workflow-enforcement-modes ac-1, ac-3 - Check entry criteria for NEXT step
+    // (Only applies when advancing from current step normally, not when skipping or completing the workflow)
+    // When skipping, we don't check entry criteria because we're not actually starting the next step yet
+    if (!isLastStep && !options.skip) {
+        const nextStep = workflow.steps[currentStepIndex + 1];
+        if (nextStep.entry_criteria && nextStep.entry_criteria.length > 0) {
+            // AC: @workflow-enforcement-modes ac-3 - Strict mode requires --confirm
+            if (isStrictMode && !options.confirm) {
+                if (!isJsonMode()) {
+                    console.log(`Step ${currentStepIndex + 2}/${run.total_steps}: [${nextStep.type}] ${nextStep.content}`);
+                    console.log(chalk.yellow("  Entry criteria:"));
+                    for (const criterion of nextStep.entry_criteria) {
+                        console.log(chalk.yellow(`    - ${criterion}`));
+                    }
+                    console.log();
+                }
+                error(errors.workflowRun.entryCriteriaNotConfirmed);
+                process.exit(EXIT_CODES.VALIDATION_FAILED);
+            }
+            // AC: @workflow-enforcement-modes ac-4 - Advisory mode shows criteria as guidance
+            if (!isStrictMode && !isJsonMode()) {
+                console.log(`Step ${currentStepIndex + 2}/${run.total_steps}: [${nextStep.type}] ${nextStep.content}`);
+                console.log(chalk.gray("  Entry criteria:"));
+                for (const criterion of nextStep.entry_criteria) {
+                    console.log(chalk.gray(`    - ${criterion}`));
+                }
+                console.log();
+            }
+        }
+    }
+    // AC: @workflow-step-navigation ac-1, ac-6 - Complete current step
+    const previousResult = run.step_results[run.step_results.length - 1];
+    const startedAt = previousResult
+        ? previousResult.completed_at
+        : run.started_at;
+    // AC: @workflow-enforcement-modes ac-3 - Record confirmations in StepResult
+    // Check if a stub result already exists for this step (created when we advanced to it)
+    const existingResultIndex = run.step_results.findIndex((r) => r.step_index === currentStepIndex);
+    if (existingResultIndex >= 0) {
+        // Update existing stub result with completion data
+        const existingResult = run.step_results[existingResultIndex];
+        run.step_results[existingResultIndex] = {
+            ...existingResult,
+            status: options.skip ? "skipped" : "completed",
+            completed_at: new Date().toISOString(),
+            notes: options.notes,
+            exit_confirmed: currentStep.exit_criteria &&
+                currentStep.exit_criteria.length > 0 &&
+                options.confirm
+                ? true
+                : undefined,
+            inputs: Object.keys(stepInputs).length > 0 ? stepInputs : undefined,
+        };
+    }
+    else {
+        // No stub exists (first step or old data), create complete result
+        const stepResult = {
+            step_index: currentStepIndex,
+            status: options.skip ? "skipped" : "completed",
+            started_at: startedAt,
+            completed_at: new Date().toISOString(),
+            notes: options.notes,
+            exit_confirmed: currentStep.exit_criteria &&
+                currentStep.exit_criteria.length > 0 &&
+                options.confirm
+                ? true
+                : undefined,
+            entry_confirmed: undefined,
+            inputs: Object.keys(stepInputs).length > 0 ? stepInputs : undefined,
+        };
+        run.step_results.push(stepResult);
+    }
+    // AC: @workflow-step-navigation ac-1 - Advance to next step or complete run
+    if (isLastStep) {
+        // AC: @workflow-step-navigation ac-2 - Complete the run
+        run.status = "completed";
+        run.completed_at = new Date().toISOString();
+        await updateWorkflowRun(ctx, run);
+        await commitIfShadow(ctx.shadow, "workflow-next");
+        // Calculate summary stats
+        const totalDuration = new Date(run.completed_at).getTime() - new Date(run.started_at).getTime();
+        const completedSteps = run.step_results.filter((r) => r.status === "completed").length;
+        const skippedSteps = run.step_results.filter((r) => r.status === "skipped").length;
+        if (isJsonMode()) {
+            output({
+                run_id: run._ulid,
+                status: run.status,
+                completed_at: run.completed_at,
+                total_duration_ms: totalDuration,
+                steps_completed: completedSteps,
+                steps_skipped: skippedSteps,
+            });
+        }
+        else {
+            const currentStep = workflow.steps[currentStepIndex];
+            success(`Completed step ${currentStepIndex + 1}/${run.total_steps}: [${currentStep.type}] ${currentStep.content}`);
+            console.log();
+            console.log(chalk.bold("Workflow completed!"));
+            console.log(`  Duration: ${Math.round(totalDuration / 1000)}s`);
+            console.log(`  Steps completed: ${completedSteps}`);
+            console.log(`  Steps skipped: ${skippedSteps}`);
+        }
+    }
+    else {
+        // Advance to next step
+        run.current_step += 1;
+        // AC: @workflow-enforcement-modes ac-3 - Record entry confirmation for the next step
+        // Create a stub step result for the next step to capture entry_confirmed and started_at
+        // This will be updated with completion data when the step is completed
+        const nextStep = workflow.steps[run.current_step];
+        const nextStepStartedAt = run.step_results[run.step_results.length - 1]?.completed_at ||
+            new Date().toISOString();
+        const nextStepStub = {
+            step_index: run.current_step,
+            status: "completed", // Placeholder, will be updated
+            started_at: nextStepStartedAt,
+            completed_at: nextStepStartedAt, // Placeholder, will be updated
+            entry_confirmed: nextStep.entry_criteria &&
+                nextStep.entry_criteria.length > 0 &&
+                options.confirm
+                ? true
+                : undefined,
+        };
+        run.step_results.push(nextStepStub);
+        await updateWorkflowRun(ctx, run);
+        await commitIfShadow(ctx.shadow, "workflow-next");
+        if (isJsonMode()) {
+            output({
+                run_id: run._ulid,
+                current_step: run.current_step,
+                total_steps: run.total_steps,
+                next_step: {
+                    type: nextStep.type,
+                    content: nextStep.content,
+                },
+            });
+        }
+        else {
+            const previousStep = workflow.steps[currentStepIndex];
+            success(`Completed step ${currentStepIndex + 1}/${run.total_steps}: [${previousStep.type}] ${previousStep.content}`);
+            console.log();
+            console.log(`Step ${run.current_step + 1}/${run.total_steps}: [${nextStep.type}] ${nextStep.content}`);
+        }
+    }
+}
+/**
+ * Command: kspec workflow prune [--older-than <duration>] [--status <status>] [--abandoned] [--dry-run]
+ * AC: @workflow-prune ac-1, ac-2, ac-3, ac-4
+ */
+async function workflowPrune(options) {
+    const ctx = await initContext();
+    let runs = await loadWorkflowRuns(ctx);
+    // Track which runs to prune
+    let toPrune = [];
+    // AC: @workflow-prune ac-1 - Filter by age
+    if (options.olderThan) {
+        const match = options.olderThan.match(/^(\d+)([dhm])$/);
+        if (!match) {
+            error('Invalid duration format. Use format like: 30d (days), 12h (hours), 45m (minutes)');
+            process.exit(EXIT_CODES.USAGE_ERROR);
+        }
+        const [, amount, unit] = match;
+        const amountNum = parseInt(amount);
+        const milliseconds = {
+            m: amountNum * 60 * 1000,
+            h: amountNum * 60 * 60 * 1000,
+            d: amountNum * 24 * 60 * 60 * 1000,
+        }[unit];
+        if (milliseconds === undefined) {
+            error('Invalid duration unit. Use d (days), h (hours), or m (minutes)');
+            process.exit(EXIT_CODES.USAGE_ERROR);
+        }
+        const cutoffTime = Date.now() - milliseconds;
+        toPrune = runs.filter((r) => {
+            const runTime = new Date(r.started_at).getTime();
+            return runTime < cutoffTime;
+        });
+    }
+    // AC: @workflow-prune ac-2 - Filter by status
+    if (options.status) {
+        const validStatuses = ['active', 'paused', 'completed', 'aborted'];
+        if (!validStatuses.includes(options.status)) {
+            error(`Invalid status: ${options.status}. Must be one of: ${validStatuses.join(', ')}`);
+            process.exit(EXIT_CODES.USAGE_ERROR);
+        }
+        if (toPrune.length > 0) {
+            // Filter existing toPrune list
+            toPrune = toPrune.filter((r) => r.status === options.status);
+        }
+        else {
+            // No age filter, just status
+            toPrune = runs.filter((r) => r.status === options.status);
+        }
+    }
+    // AC: @workflow-prune ac-3 - Filter by abandoned (active with no activity for 7+ days)
+    if (options.abandoned) {
+        const abandonedCutoff = Date.now() - 7 * 24 * 60 * 60 * 1000; // 7 days
+        const abandonedRuns = runs.filter((r) => {
+            if (r.status !== 'active')
+                return false;
+            // Find most recent activity time
+            let lastActivity = new Date(r.started_at).getTime();
+            if (r.step_results.length > 0) {
+                const lastStep = r.step_results[r.step_results.length - 1];
+                lastActivity = new Date(lastStep.completed_at).getTime();
+            }
+            return lastActivity < abandonedCutoff;
+        });
+        if (toPrune.length > 0) {
+            // Intersect with existing toPrune list
+            const abandonedUlids = new Set(abandonedRuns.map((r) => r._ulid));
+            toPrune = toPrune.filter((r) => abandonedUlids.has(r._ulid));
+        }
+        else {
+            toPrune = abandonedRuns;
+        }
+    }
+    // If no filters provided, error
+    if (!options.olderThan && !options.status && !options.abandoned) {
+        error('Must specify at least one filter: --older-than, --status, or --abandoned');
+        process.exit(EXIT_CODES.USAGE_ERROR);
+    }
+    // AC: @workflow-prune ac-4 - Dry run mode
+    if (options.dryRun || isJsonMode()) {
+        const output_data = {
+            would_delete: toPrune.length,
+            runs: toPrune.map((r) => ({
+                _ulid: r._ulid,
+                workflow_ref: r.workflow_ref,
+                status: r.status,
+                started_at: r.started_at,
+            })),
+        };
+        if (isJsonMode()) {
+            output(output_data);
+        }
+        else {
+            console.log(chalk.yellow(`Would delete ${toPrune.length} workflow run${toPrune.length === 1 ? '' : 's'}:`));
+            if (toPrune.length > 0) {
+                const table = new Table({
+                    head: ['ID', 'Workflow', 'Status', 'Started'],
+                    colWidths: [12, 25, 12, 20],
+                });
+                const metaCtx = await loadMetaContext(ctx);
+                for (const run of toPrune) {
+                    const workflow = metaCtx.workflows.find((w) => `@${w._ulid}` === run.workflow_ref);
+                    const workflowName = workflow?.id || run.workflow_ref;
+                    const started = new Date(run.started_at).toLocaleString();
+                    table.push([
+                        shortUlid(run._ulid),
+                        workflowName,
+                        formatStatus(run.status),
+                        started,
+                    ]);
+                }
+                console.log(table.toString());
+                console.log(chalk.gray('\nRun without --dry-run to actually delete these runs'));
+            }
+        }
+        return;
+    }
+    // Actually delete
+    if (toPrune.length === 0) {
+        if (!isJsonMode()) {
+            console.log(chalk.gray('No runs match the specified criteria'));
+        }
+        else {
+            output({ deleted: 0 });
+        }
+        return;
+    }
+    const ulidsToDelete = toPrune.map((r) => r._ulid);
+    await deleteWorkflowRuns(ctx, ulidsToDelete);
+    await commitIfShadow(ctx.shadow, 'workflow-prune');
+    if (isJsonMode()) {
+        output({ deleted: toPrune.length });
+    }
+    else {
+        success(`Deleted ${toPrune.length} workflow run${toPrune.length === 1 ? '' : 's'}`);
+    }
+}
+/**
+ * Register workflow commands
+ */
+export function registerWorkflowCommand(program) {
+    const workflow = program
+        .command("workflow")
+        .description("Manage workflow runs");
+    markMutating(workflow.command("start"))
+        .description("Start a new workflow run")
+        .argument("<workflow-ref>", "Workflow reference (@id or @ulid)")
+        .option("--task <task-ref>", "Link run to a task")
+        .option("--json", "Output JSON")
+        .action(workflowStart);
+    workflow
+        .command("runs")
+        .description("List workflow runs")
+        .option("--active", "Show only active runs")
+        .option("--completed", "Show only completed runs")
+        .option("--workflow <ref>", "Filter by workflow")
+        .option("--json", "Output JSON")
+        .action(workflowRuns);
+    workflow
+        .command("show")
+        .description("Show workflow run details")
+        .argument("<run-ref>", "Run reference (@ulid or ulid prefix)")
+        .option("--json", "Output JSON")
+        .action(workflowShow);
+    markMutating(workflow.command("abort"))
+        .description("Abort an active workflow run")
+        .argument("<run-ref>", "Run reference (@ulid or ulid prefix)")
+        .option("--reason <text>", "Reason for aborting")
+        .option("--json", "Output JSON")
+        .action(workflowAbort);
+    markMutating(workflow.command("complete"))
+        .description("Mark workflow run as completed (graceful exit)")
+        .argument("<run-ref>", "Run reference (@ulid or ulid prefix)")
+        .option("--result <result>", "Completion result (success, no_work_available, early_exit)")
+        .option("--json", "Output JSON")
+        .action(workflowComplete);
+    markMutating(workflow.command("next"))
+        .description("Advance workflow run to next step")
+        .argument("[run-ref]", "Run reference (optional if only one active run)")
+        .option("--skip", "Mark current step as skipped")
+        .option("--notes <text>", "Notes for the completed step")
+        .option("--confirm", "Acknowledge entry/exit criteria (required in strict mode)")
+        .option("--force", "Allow --skip in strict mode")
+        .option("--input <key=value>", "Provide step input (repeatable)", (value, previous = []) => [...previous, value])
+        .option("--json", "Output JSON")
+        .action(workflowNext);
+    markMutating(workflow.command("pause"))
+        .description("Pause an active workflow run")
+        .argument("<run-ref>", "Run reference (@ulid or ulid prefix)")
+        .option("--json", "Output JSON")
+        .action(workflowPause);
+    markMutating(workflow.command("resume"))
+        .description("Resume a paused workflow run")
+        .argument("<run-ref>", "Run reference (@ulid or ulid prefix)")
+        .option("--json", "Output JSON")
+        .action(workflowResume);
+    markMutating(workflow.command("prune"))
+        .description("Remove old or stale workflow runs")
+        .option("--older-than <duration>", "Delete runs older than specified duration (e.g., 30d, 12h, 45m)")
+        .option("--status <status>", "Delete runs with specific status (active, paused, completed, aborted)")
+        .option("--abandoned", "Delete active runs with no activity for 7+ days")
+        .option("--dry-run", "Show what would be deleted without deleting")
+        .option("--json", "Output JSON")
+        .action(workflowPrune);
+}
+//# sourceMappingURL=workflow.js.map