/**
 * WorkflowSchema — TypeScript types for OpenLife workflows.
 *
 * A workflow is a YAML-declared executable sequence of steps. Each step
 * names an agent (or squad), an action to perform, and the artifacts it
 * is expected to create or update. Workflows are loaded by the
 * WorkflowEngine, validated by the WorkflowParser, and persisted as runs
 * under `.openlife/workflows/<runId>.json`.
 *
 * Story 4.1 — OpenLife v1.2 Royal Stack.
 *
 * The schema is intentionally close to community story-cycle workflow
 * conventions so the four ported workflows in dist-templates/workflows/
 * (Story 4.4) round-trip without contortion. Two OpenLife-specific
 * extensions:
 *
 *   1. `squad: <id>` — a step may dispatch to a Squad instead of a
 *      single agent, so the design-squad / qa-squad can be addressed as
 *      a single unit.
 *   2. `idempotent: true` — declares the step is safe to re-execute on
 *      resume after a partial-run crash. WorkflowEngine.resume() uses
 *      this flag to decide whether to retry or skip a partially-
 *      completed step.
 */
export type WorkflowType = 'greenfield' | 'brownfield' | 'story-cycle' | 'qa-loop' | 'custom';
export interface WorkflowMetadata {
    /** Whether any step in the sequence may pause for human input. */
    elicit?: boolean;
    /** Whether each phase transition requires explicit confirmation. */
    confirmation_required?: boolean;
}
export interface WorkflowPhaseMarker {
    /** Phase number (0, 1, 2, …). Acts as a chapter header in the sequence. */
    phase: number;
    /** Human-readable phase name. */
    name: string;
    /** Optional narrative description of what happens in this phase. */
    description?: string;
}
export interface WorkflowExecutableStep {
    /** Unique step id within the workflow. Used by `requires` references. */
    id: string;
    /** Named agent that executes the step. Either `agent` or `squad` is required. */
    agent?: string;
    /** Named squad that executes the step. Either `agent` or `squad` is required. */
    squad?: string;
    /** Action name (typically a task slug like `create-prd` or `qa-gate`). */
    action?: string;
    /** Task file (e.g. `create-prd.md`) — looked up in squad's tasks/ or dist-templates/tasks/. */
    task?: string;
    /** Artifact paths the step is expected to create. */
    creates?: string[];
    /** Artifact paths the step is expected to update (not create). */
    updates?: string[];
    /** Either a step id or an artifact path that must exist before this step runs. */
    requires?: string | string[];
    /** Free-form duration estimate string (e.g. `30-60 min`). Used for UX, not enforcement. */
    duration_estimate?: string;
    /** Boolean expression literal (e.g. `user_wants_ai_generation`). v1.2 supports only literal flags. */
    condition?: string;
    /** If true, executor may skip this step entirely without failing the workflow. */
    optional?: boolean;
    /** If true, the step requires human input (`elicit: true`); engine pauses with state `awaiting_input`. */
    elicit?: boolean;
    /** If true, step is safe to re-execute after partial-run crash. WorkflowEngine.resume() respects this. */
    idempotent?: boolean;
    /** Free-form operator notes. Carried into run logs for human review. */
    notes?: string;
    /** Optional alternative sub-steps the operator may run before this step. */
    optional_steps?: string[];
}
/** A sequence entry is either a phase marker or an executable step. */
export type WorkflowSequenceEntry = WorkflowPhaseMarker | WorkflowExecutableStep;
/**
 * Workflow execution mode. v1.3 makes this explicit:
 *   - `task`    : default. One-shot mission. Result completes the workflow.
 *   - `service` : long-running. Must be explicitly requested (no auto-promotion).
 */
export type WorkflowMode = 'task' | 'service';
/** Status of the workflow as a catalog asset (independent of any specific run). */
export type WorkflowStatus = 'draft' | 'tested' | 'active' | 'deprecated';
/** What triggers a workflow run. */
export type WorkflowTrigger = 'manual' | 'cron' | 'webhook' | 'event';
export interface WorkflowSuccessCriterion {
    /** Stable id, e.g. `coverage-above-80`. */
    id: string;
    /** Human description. */
    description: string;
    /** Optional measurement hint. */
    metric?: string;
}
export interface WorkflowIO {
    /** Stable id, e.g. `brief`, `report-path`. */
    id: string;
    /** TS-style type hint as free text: `string`, `string[]`, `{path:string}`. */
    type: string;
    /** Whether this is required at run time. */
    required?: boolean;
    /** Human description. */
    description?: string;
}
export interface WorkflowToolsPolicy {
    allowed?: string[];
    restricted?: string[];
    forbidden?: string[];
}
export interface WorkflowFailureHandling {
    /** What to do on step failure: 'abort' | 'continue' | 'retry'. Default 'abort'. */
    on_step_failure?: 'abort' | 'continue' | 'retry';
    /** Max retries when on_step_failure='retry'. Default 0. */
    max_retries?: number;
    /** Optional id of a recovery step to run on abort. */
    recovery_step?: string;
}
export interface WorkflowValidationRule {
    /** Stable id, e.g. `must-have-evidence`. */
    id: string;
    /** Human description. */
    description: string;
    /** Optional rule type tag for the engine (e.g. 'artifact_exists', 'json_schema'). */
    kind?: string;
    /** Optional configuration payload (engine-defined). */
    config?: Record<string, unknown>;
}
export interface WorkflowLearningRule {
    /** Stable id, e.g. `record-citation-failures`. */
    id: string;
    /** When to fire: 'on_success' | 'on_failure' | 'always'. */
    trigger: 'on_success' | 'on_failure' | 'always';
    /** Free-text description of what the rule captures. */
    description: string;
}
export interface Workflow {
    id: string;
    name: string;
    description?: string;
    type: WorkflowType;
    version: string;
    /** Catalog-asset status. Default 'active'. */
    status?: WorkflowStatus;
    /** Execution mode. Default 'task'. */
    mode?: WorkflowMode;
    /** What can initiate a run. Default ['manual']. */
    triggers?: WorkflowTrigger[];
    /** One-line goal statement. */
    objective?: string;
    /** Measurable success criteria. */
    success_criteria?: WorkflowSuccessCriterion[];
    /** Declared inputs the runner must supply. */
    inputs?: WorkflowIO[];
    /** Declared outputs the runner produces. */
    outputs?: WorkflowIO[];
    /** Free-text required context (files, knowledge bases, etc.). */
    required_context?: string[];
    /** Top-level squads referenced by step squads[]. */
    squads?: string[];
    /** Top-level skills referenced by steps. */
    skills?: string[];
    /** Tool access policy enforced at step dispatch. */
    tools?: WorkflowToolsPolicy;
    /** Pack-level governance policy tags (resolved via CapabilityPackPolicy). */
    policies?: string[];
    /** Validation rules executed at workflow boundaries (start/end). */
    validation?: WorkflowValidationRule[];
    /** Evidence artifacts the workflow MUST produce to be considered complete. */
    evidence?: string[];
    /** Failure / retry strategy. */
    failure_handling?: WorkflowFailureHandling;
    /** Audit events of interest (free-text tags emitted to the audit ledger). */
    audit_events?: string[];
    /** Hooks fired after run completion for the LearningRouter. */
    learning_rules?: WorkflowLearningRule[];
    project_types?: string[];
    metadata?: WorkflowMetadata;
    /** Narrative list of phases (optional — sequence's phase markers are the source of truth). */
    phases?: Record<string, string>[];
    /** The executable plan: a flat list of phase markers interleaved with executable steps. */
    sequence: WorkflowSequenceEntry[];
}
/** The root YAML document is `workflow: { … }`. */
export interface WorkflowDocument {
    workflow: Workflow;
}
export declare function isPhaseMarker(entry: unknown): entry is WorkflowPhaseMarker;
export declare function isExecutableStep(entry: unknown): entry is WorkflowExecutableStep;
export declare const WORKFLOW_ERRORS: {
    readonly INVALID_YAML: "workflow_invalid_yaml";
    readonly INVALID_SCHEMA: "workflow_invalid_schema";
    readonly MISSING_ROOT: "workflow_missing_root";
    readonly MISSING_REQUIRED_FIELD: "workflow_missing_required_field";
    readonly INVALID_TYPE: "workflow_invalid_type";
    readonly DUPLICATE_STEP_ID: "workflow_duplicate_step_id";
    readonly CIRCULAR_REQUIRES: "workflow_circular_requires";
    readonly UNKNOWN_REQUIRES: "workflow_unknown_requires";
    readonly AGENT_AND_SQUAD: "workflow_agent_and_squad";
    readonly NEITHER_AGENT_NOR_SQUAD: "workflow_neither_agent_nor_squad";
    readonly INVALID_MODE: "workflow_invalid_mode";
    readonly INVALID_TOOLS_POLICY: "workflow_invalid_tools_policy";
    readonly INVALID_TRIGGERS: "workflow_invalid_triggers";
    readonly INVALID_SUCCESS_CRITERIA: "workflow_invalid_success_criteria";
};
export type WorkflowErrorCode = typeof WORKFLOW_ERRORS[keyof typeof WORKFLOW_ERRORS];
export interface WorkflowParseError {
    code: WorkflowErrorCode;
    message: string;
    /** Optional context: step id, field path, etc. */
    context?: Record<string, string | number>;
}
export interface WorkflowParseResult {
    ok: boolean;
    workflow?: Workflow;
    errors: WorkflowParseError[];
}
