@kitsy/coop-core 0.0.1 → 2.0.0

package/dist/index.d.cts

@@ -91,7 +91,7 @@ interface FilterSpec {
     search?: string;
 }
 
-type ValueOf<T> = T[keyof T];
+type ValueOf$1<T> = T[keyof T];
 declare const TaskType: {
     readonly feature: "feature";
     readonly bug: "bug";
@@ -99,7 +99,7 @@ declare const TaskType: {
     readonly spike: "spike";
     readonly epic: "epic";
 };
-type TaskType = ValueOf<typeof TaskType>;
+type TaskType = ValueOf$1<typeof TaskType>;
 declare const TaskStatus: {
     readonly todo: "todo";
     readonly blocked: "blocked";
@@ -108,14 +108,14 @@ declare const TaskStatus: {
     readonly done: "done";
     readonly canceled: "canceled";
 };
-type TaskStatus = ValueOf<typeof TaskStatus>;
+type TaskStatus = ValueOf$1<typeof TaskStatus>;
 declare const TaskPriority: {
     readonly p0: "p0";
     readonly p1: "p1";
     readonly p2: "p2";
     readonly p3: "p3";
 };
-type TaskPriority = ValueOf<typeof TaskPriority>;
+type TaskPriority = ValueOf$1<typeof TaskPriority>;
 declare const TaskComplexity: {
     readonly trivial: "trivial";
     readonly small: "small";
@@ -123,14 +123,14 @@ declare const TaskComplexity: {
     readonly large: "large";
     readonly unknown: "unknown";
 };
-type TaskComplexity = ValueOf<typeof TaskComplexity>;
+type TaskComplexity = ValueOf$1<typeof TaskComplexity>;
 declare const TaskDeterminism: {
     readonly high: "high";
     readonly medium: "medium";
     readonly low: "low";
     readonly experimental: "experimental";
 };
-type TaskDeterminism = ValueOf<typeof TaskDeterminism>;
+type TaskDeterminism = ValueOf$1<typeof TaskDeterminism>;
 declare const IdeaStatus: {
     readonly captured: "captured";
     readonly exploring: "exploring";
@@ -138,7 +138,7 @@ declare const IdeaStatus: {
     readonly parked: "parked";
     readonly rejected: "rejected";
 };
-type IdeaStatus = ValueOf<typeof IdeaStatus>;
+type IdeaStatus = ValueOf$1<typeof IdeaStatus>;
 declare const DeliveryStatus: {
     readonly planning: "planning";
     readonly committed: "committed";
@@ -146,14 +146,14 @@ declare const DeliveryStatus: {
     readonly delivered: "delivered";
     readonly canceled: "canceled";
 };
-type DeliveryStatus = ValueOf<typeof DeliveryStatus>;
+type DeliveryStatus = ValueOf$1<typeof DeliveryStatus>;
 declare const ExecutorType: {
     readonly human: "human";
     readonly ai: "ai";
     readonly ci: "ci";
     readonly hybrid: "hybrid";
 };
-type ExecutorType = ValueOf<typeof ExecutorType>;
+type ExecutorType = ValueOf$1<typeof ExecutorType>;
 declare const RunbookAction: {
     readonly generate: "generate";
     readonly run: "run";
@@ -161,7 +161,7 @@ declare const RunbookAction: {
     readonly test: "test";
     readonly deploy: "deploy";
 };
-type RunbookAction = ValueOf<typeof RunbookAction>;
+type RunbookAction = ValueOf$1<typeof RunbookAction>;
 declare const ArtifactType: {
     readonly pr: "pr";
     readonly migration: "migration";
@@ -169,14 +169,14 @@ declare const ArtifactType: {
     readonly document: "document";
     readonly config: "config";
 };
-type ArtifactType = ValueOf<typeof ArtifactType>;
+type ArtifactType = ValueOf$1<typeof ArtifactType>;
 declare const RiskLevel: {
     readonly low: "low";
     readonly medium: "medium";
     readonly high: "high";
     readonly critical: "critical";
 };
-type RiskLevel = ValueOf<typeof RiskLevel>;
+type RiskLevel = ValueOf$1<typeof RiskLevel>;
 
 interface DeliveryBudget {
     engineering_hours?: number;
@@ -286,6 +286,7 @@ interface TaskCore {
     updated: string;
 }
 interface TaskPlanning {
+    aliases?: string[];
     priority?: TaskPriority;
     track?: string;
     assignee?: string | null;
@@ -397,6 +398,18 @@ interface Track {
     };
 }
 
+interface ExternalDependencyRef {
+    raw: string;
+    repo: string;
+    task_id: string;
+}
+type ExternalDependencyResolutionStatus = "resolved" | "blocked" | "unreachable" | "missing" | "unknown";
+interface ExternalDependencyResolution {
+    dependency: ExternalDependencyRef;
+    status: ExternalDependencyResolutionStatus;
+    task_status?: string | null;
+    warning?: string;
+}
 interface TaskGraph {
     nodes: Map<string, Task>;
     forward: Map<string, Set<string>>;
@@ -405,6 +418,7 @@ interface TaskGraph {
     tracks: Map<string, Track>;
     resources: Map<string, ResourceProfile>;
     deliveries: Map<string, Delivery>;
+    external_dependencies?: Map<string, ExternalDependencyRef[]>;
 }
 interface GraphValidationResult {
     level: "error" | "warning";
@@ -413,6 +427,26 @@ interface GraphValidationResult {
     task_ids?: string[];
 }
 
+interface CriticalPathTaskMetrics {
+    id: string;
+    ES: number;
+    EF: number;
+    LS: number;
+    LF: number;
+    slack: number;
+    on_critical_path: boolean;
+}
+interface CriticalPathResult {
+    critical_path: string[];
+    project_duration_hours: number;
+    per_task: CriticalPathTaskMetrics[];
+}
+/**
+ * Computes CPM earliest/latest times and slack over delivery-scoped task subgraph.
+ * [SPEC: Scheduler v2.0 §6]
+ */
+declare function compute_critical_path(delivery: Delivery, graph: TaskGraph): CriticalPathResult;
+
 interface BuildGraphContext {
     tracks?: Map<string, Track>;
     resources?: Map<string, ResourceProfile>;
@@ -424,18 +458,262 @@ declare function transitive_dependencies(graph: TaskGraph, taskId: string): Set<
 declare function transitive_dependents(graph: TaskGraph, taskId: string): Set<string>;
 declare function build_graph(tasks: Task[], context?: BuildGraphContext): TaskGraph;
 
+type ExternalRepoConfig = {
+    base_url: string;
+};
+type ExternalDependencyResolverOptions = {
+    remotes: Record<string, ExternalRepoConfig>;
+    fetch_impl?: typeof fetch;
+};
+declare function is_external_dependency(value: string): boolean;
+declare function parse_external_dependency(value: string): ExternalDependencyRef | null;
+declare function external_dependencies_for_task(graph: TaskGraph, taskId: string): ExternalDependencyRef[];
+declare function resolve_external_dependencies(graph: TaskGraph, options: ExternalDependencyResolverOptions): Promise<Map<string, ExternalDependencyResolution[]>>;
+
 declare function load_graph(coopDir: string): TaskGraph;
 
 declare function extract_subgraph(graph: TaskGraph, taskIds: string[]): TaskGraph;
 declare function find_external_dependencies(subgraph: TaskGraph, fullGraph: TaskGraph): string[];
 
-declare function validate_graph(graph: TaskGraph): GraphValidationResult[];
+declare const COOP_EVENT_TYPES: readonly ["task.created", "task.transitioned", "task.assigned", "delivery.committed", "delivery.at_risk", "run.started", "run.completed", "run.failed", "graph.cycle_detected"];
+type CoopEventType = (typeof COOP_EVENT_TYPES)[number];
+type BaseEvent<TType extends CoopEventType, TPayload> = {
+    type: TType;
+    timestamp: string;
+    payload: TPayload;
+};
+type TaskCreated = BaseEvent<"task.created", {
+    task_id: string;
+    title?: string;
+    task_type?: string;
+    file_path?: string;
+}>;
+type TaskTransitioned = BaseEvent<"task.transitioned", {
+    task_id: string;
+    from: TaskStatus;
+    to: TaskStatus;
+    actor?: string;
+}>;
+type TaskAssigned = BaseEvent<"task.assigned", {
+    task_id: string;
+    from: string | null;
+    to: string | null;
+    actor?: string;
+}>;
+type DeliveryCommitted = BaseEvent<"delivery.committed", {
+    delivery_id: string;
+    from: DeliveryStatus;
+    to: DeliveryStatus;
+    actor?: string;
+}>;
+type DeliveryAtRisk = BaseEvent<"delivery.at_risk", {
+    delivery_id: string;
+    status: "FEASIBLE" | "NOT_FEASIBLE";
+    risks: string[];
+}>;
+type RunStarted = BaseEvent<"run.started", {
+    run_id: string;
+    task_id: string;
+    executor?: string;
+}>;
+type RunCompleted = BaseEvent<"run.completed", {
+    run_id: string;
+    task_id: string;
+    duration_ms?: number;
+}>;
+type RunFailed = BaseEvent<"run.failed", {
+    run_id: string;
+    task_id: string;
+    error: string;
+}>;
+type GraphCycleDetected = BaseEvent<"graph.cycle_detected", {
+    cycle: string[];
+}>;
+type CoopEvent = TaskCreated | TaskTransitioned | TaskAssigned | DeliveryCommitted | DeliveryAtRisk | RunStarted | RunCompleted | RunFailed | GraphCycleDetected;
+type EventByType = {
+    "task.created": TaskCreated;
+    "task.transitioned": TaskTransitioned;
+    "task.assigned": TaskAssigned;
+    "delivery.committed": DeliveryCommitted;
+    "delivery.at_risk": DeliveryAtRisk;
+    "run.started": RunStarted;
+    "run.completed": RunCompleted;
+    "run.failed": RunFailed;
+    "graph.cycle_detected": GraphCycleDetected;
+};
+
+/**
+ * Minimal typed synchronous event emitter for core domain events.
+ * [SPEC: Architecture v2.0 §14]
+ */
+declare class CoopEventEmitter {
+    private handlers;
+    on<TType extends CoopEventType>(eventType: TType, handler: (event: EventByType[TType]) => void): () => void;
+    emit(event: CoopEvent): void;
+}
+
+interface GraphValidationContext {
+    eventEmitter?: CoopEventEmitter;
+}
+declare function validate_graph(graph: TaskGraph, context?: GraphValidationContext): GraphValidationResult[];
+
+type IndexStatus = {
+    exists: boolean;
+    stale: boolean;
+    graph_path: string;
+    source_max_mtime_ms: number;
+    changed_files: string[];
+    generated_at?: string;
+    reason?: string;
+};
+declare class IndexManager {
+    readonly coopDir: string;
+    readonly indexDir: string;
+    readonly graphPath: string;
+    readonly tasksPath: string;
+    readonly capacityPath: string;
+    constructor(coopDir: string);
+    is_stale(): boolean;
+    status(): IndexStatus;
+    load_indexed_graph(): TaskGraph | null;
+    build_full_index(): TaskGraph;
+    update_incremental(changedFiles: string[]): TaskGraph;
+    private ensureIndexDir;
+    private writeIndexFiles;
+    private readGraphIndexFile;
+    private serializeGraph;
+    private deserializeGraph;
+    private scanSources;
+    private normalizeChangedFile;
+    private fileKind;
+    private computeTaskIndexRows;
+    private computeCapacitySnapshot;
+}
+
+interface HookRunResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+/**
+ * Executes a hook script with JSON event payload piped to stdin.
+ * [SPEC: Architecture v2.0 §14]
+ */
+declare function run_hook(hookPath: string, event: CoopEvent, timeoutMs?: number): Promise<HookRunResult>;
+
+type Role = "admin" | "lead" | "contributor" | "viewer";
+type Permission = "all" | "read" | "comment" | "create_task" | "transition_task" | "transition_own_task" | "create_delivery" | "plan_delivery" | "assign_task" | "delete_task" | "commit_delivery" | "override_blocked";
+type PolicyAction = "delete_task" | "commit_delivery" | "override_blocked" | "transition_task" | "create_delivery";
+type AuthPolicy = {
+    action: PolicyAction;
+    requires: Role[];
+};
+type AuthConfig = {
+    enabled: boolean;
+    roles: Record<Role, {
+        permissions: Permission[];
+    }>;
+    assignments: Record<string, Role>;
+    policies: AuthPolicy[];
+};
+type PermissionContext = {
+    config: AuthConfig;
+    taskOwner?: string | null;
+};
+/**
+ * Loads authorization policy from config.yml-compatible object.
+ * [SPEC: Architecture v2.0 §20]
+ */
+declare function load_auth_config(config: unknown): AuthConfig;
+/**
+ * Returns mapped role for a user, defaulting to viewer.
+ * [SPEC: Architecture v2.0 §20]
+ */
+declare function get_user_role(user: string, config: AuthConfig): Role;
+/**
+ * Checks whether user is allowed to perform a given action in context.
+ * [SPEC: Architecture v2.0 §20]
+ */
+declare function check_permission(user: string, action: Permission, context: PermissionContext): boolean;
+
+type PluginActionWebhook = {
+    type: "webhook";
+    url: string;
+    template?: string;
+    headers?: Record<string, string>;
+};
+type PluginActionConsole = {
+    type: "console";
+    template: string;
+};
+type PluginActionGitHubPr = {
+    type: "github_pr";
+    operation: "create_or_update" | "merge";
+    branch?: string;
+    base_branch?: string;
+    draft?: boolean;
+};
+type PluginAction = PluginActionWebhook | PluginActionConsole | PluginActionGitHubPr;
+type PluginTrigger = {
+    event: CoopEventType;
+    filter?: Record<string, unknown>;
+    action: PluginAction;
+};
+type PluginManifest = {
+    id: string;
+    name: string;
+    version: string;
+    triggers: PluginTrigger[];
+    secrets: string[];
+    file_path: string;
+};
+/**
+ * Loads and validates plugin manifests from .coop/plugins.
+ * [SPEC: Architecture v2.0 §19]
+ */
+declare function load_plugins(coopDir: string): PluginManifest[];
+
+type EnvMap = Record<string, string | undefined>;
+type PluginRunRecord = {
+    plugin_id: string;
+    plugin_name: string;
+    trigger_event: string;
+    action_type: string;
+    success: boolean;
+    status_code?: number;
+    error?: string;
+    message?: string;
+    timestamp: string;
+};
+type PluginRunOptions = {
+    graph?: TaskGraph;
+    env?: EnvMap;
+    fetch_impl?: typeof fetch;
+    action_handlers?: Partial<Record<PluginAction["type"], PluginActionHandler>>;
+};
+type PluginActionHandlerResult = {
+    statusCode?: number;
+    message?: string;
+};
+type PluginActionHandler = (plugin: PluginManifest, trigger: PluginTrigger, action: PluginAction, context: TemplateContext, env: EnvMap) => Promise<PluginActionHandlerResult>;
+type TemplateContext = {
+    event: Record<string, unknown>;
+    task?: Record<string, unknown>;
+    delivery?: Record<string, unknown>;
+};
+/**
+ * Runs matching plugin triggers for a single event.
+ * [SPEC: Architecture v2.0 §19]
+ */
+declare function run_plugins_for_event(coopDir: string, event: CoopEvent, options?: PluginRunOptions): Promise<PluginRunRecord[]>;
 
 interface CoopConfig {
     version: number;
     project: {
         name: string;
         id: string;
+        aliases?: string[];
     };
     id_prefixes?: {
         idea?: string;
@@ -471,12 +749,20 @@ interface CoopConfig {
         on_task_transition?: string;
         on_delivery_complete?: string;
     };
+    api?: {
+        host?: string;
+        port?: number;
+        remotes?: Record<string, {
+            base_url: string;
+        }>;
+    };
 }
 
 interface Idea {
     id: string;
     title: string;
     created: string;
+    aliases?: string[];
     author: string;
     status: IdeaStatus;
     tags: string[];
@@ -484,6 +770,52 @@ interface Idea {
     linked_tasks: string[];
 }
 
+type ValueOf<T> = T[keyof T];
+declare const RunStatus: {
+    readonly pending: "pending";
+    readonly running: "running";
+    readonly paused: "paused";
+    readonly completed: "completed";
+    readonly failed: "failed";
+    readonly canceled: "canceled";
+};
+type RunStatus = ValueOf<typeof RunStatus>;
+declare const RunStepStatus: {
+    readonly completed: "completed";
+    readonly failed: "failed";
+    readonly paused: "paused";
+    readonly skipped: "skipped";
+};
+type RunStepStatus = ValueOf<typeof RunStepStatus>;
+interface RunStepResult {
+    step: string;
+    action: string;
+    status: RunStepStatus;
+    started: string;
+    completed?: string;
+    duration_seconds?: number;
+    output_summary?: string;
+    reviewer?: string;
+    notes?: string;
+    exit_code?: number;
+    tokens_used?: number;
+}
+interface RunResourcesConsumed {
+    ai_tokens: number;
+    compute_minutes: number;
+    file_changes: number;
+}
+interface Run {
+    id: string;
+    task: string;
+    executor: string;
+    status: RunStatus;
+    started: string;
+    completed?: string;
+    steps: RunStepResult[];
+    resources_consumed: RunResourcesConsumed;
+}
+
 interface ParsedDelivery {
     delivery: Delivery;
     body: string;
@@ -520,11 +852,212 @@ interface WriteTaskOptions {
     body?: string;
     raw?: Record<string, unknown>;
     filePath?: string;
+    eventEmitter?: CoopEventEmitter;
 }
 declare function writeTask(task: Task, options?: WriteTaskOptions): string;
 
 declare function parseYamlContent<T extends object = Record<string, unknown>>(content: string, source?: string): T;
 declare function parseYamlFile<T extends object = Record<string, unknown>>(filePath: string): T;
+declare function stringifyYamlContent(content: Record<string, unknown>): string;
+declare function writeYamlFile(filePath: string, content: Record<string, unknown>): void;
+
+interface CapacityLedger {
+    slots: Map<string, Map<number, number>>;
+    weeks: Map<number, {
+        start: string;
+        end: string;
+    }>;
+    ai_tokens: Map<string, number>;
+    ai_tokens_by_agent: Map<string, Map<string, number>>;
+    ai_tokens_consumed_by_agent: Map<string, Map<string, number>>;
+}
+interface AllocationResult {
+    success: boolean;
+    reason?: "capacity_exhausted" | "ai_capacity_exhausted";
+    start_week?: number;
+    end_week?: number;
+    duration_weeks?: number;
+}
+/**
+ * Computes net weekly human capacity after calendar and overhead adjustments.
+ * [SPEC: Architecture v2.0 §9]
+ */
+declare function effective_weekly_hours(profile: HumanResource, week_start: string | Date, week_end: string | Date): number;
+/**
+ * Builds per-track weekly capacity and AI token ledgers for a delivery horizon.
+ * [SPEC: Scheduler v2.0 §3 Stage 4]
+ */
+declare function build_capacity_ledger(delivery: Delivery, resources: Map<string, ResourceProfile> | ResourceProfile[], today: string | Date): CapacityLedger;
+/**
+ * Attempts to allocate task effort into contiguous weekly slots for its track.
+ * [SPEC: Scheduler v2.0 §3 Stage 4]
+ */
+declare function allocate(ledger: CapacityLedger, task: Task, start_week: number): AllocationResult;
+/**
+ * Validates current in-progress count against track max concurrent limit.
+ * [SPEC: Architecture v2.0 §8]
+ */
+declare function check_wip(track: Track | undefined, graph: TaskGraph): boolean;
+/**
+ * Reserves AI token budget for an AI/hybrid task on a given execution day.
+ * [SPEC: Scheduler v2.0 §4.6]
+ */
+declare function allocate_ai(ledger: CapacityLedger, task: Task, day: string, fallback_tokens?: number): AllocationResult;
+/**
+ * Reserves AI tokens for a specific agent on a specific day.
+ * [SPEC: Scheduler v2.0 §4.6]
+ */
+declare function allocate_ai_tokens(ledger: CapacityLedger, agent: string, tokens: number, day: string): boolean;
+/**
+ * Returns remaining AI tokens for an agent/day pair from the capacity ledger.
+ * [SPEC: Scheduler v2.0 §4.6]
+ */
+declare function get_remaining_tokens(ledger: CapacityLedger, agent: string, day: string): number;
+
+/**
+ * Returns PERT expected effort from optimistic/expected/pessimistic triplet.
+ * [SPEC: Scheduler v2.0 §4.2]
+ */
+declare function pert_hours(estimate: TaskEstimate): number;
+/**
+ * Returns PERT standard deviation used for uncertainty calculations.
+ * [SPEC: Scheduler v2.0 §4.2]
+ */
+declare function pert_stddev(estimate: TaskEstimate): number;
+/**
+ * Resolves effective task effort from estimate/resources/fallback heuristics.
+ * [SPEC: Scheduler v2.0 §4.1]
+ */
+declare function task_effort_hours(task: Task): number;
+/**
+ * Returns task effort with complexity-based defaults when explicit estimate is absent.
+ * [SPEC: Scheduler v2.0 §4.1]
+ */
+declare function effort_or_default(task: Task, config: CoopConfig): number;
+
+interface TaskScheduleEntry {
+    task_id: string;
+    track: string;
+    start_week: number | null;
+    end_week: number | null;
+    already_complete?: boolean;
+}
+interface TrackUtilization {
+    track: string;
+    allocated_hours: number;
+    capacity_hours: number;
+    utilization: number;
+}
+interface SimulationResult {
+    schedule: Record<string, TaskScheduleEntry>;
+    projected_completion: string | null;
+    total_weeks: number;
+    utilization_by_track: TrackUtilization[];
+    error?: {
+        code: "schedule_overflow";
+        task: string;
+    };
+}
+interface MonteCarloOptions {
+    iterations?: number;
+    workers?: number;
+    today?: string | Date;
+    rng?: () => number;
+    seed?: number;
+}
+interface MonteCarloHistogramBucket {
+    week_index: number;
+    start_date: string;
+    end_date: string;
+    count: number;
+    probability: number;
+}
+interface MonteCarloResult {
+    iterations: number;
+    successful_iterations: number;
+    p50: string | null;
+    p75: string | null;
+    p85: string | null;
+    p95: string | null;
+    mean_date: string | null;
+    stddev_days: number;
+    probability_by_target: number | null;
+    histogram: MonteCarloHistogramBucket[];
+}
+interface MonteCarloWorkerPayload {
+    delivery: Delivery;
+    graph: TaskGraph;
+    today: string;
+    iterations: number;
+    start_index: number;
+    seed: number;
+}
+/**
+ * Simulates week-by-week task placement under dependency, capacity, and WIP constraints.
+ * [SPEC: Scheduler v2.0 §5]
+ */
+declare function simulate_schedule(tasks: Task[], graph: TaskGraph, delivery: Delivery, today: string | Date): SimulationResult;
+declare function create_seeded_rng(seed: number): () => number;
+declare function run_monte_carlo_chunk(delivery: Delivery, graph: TaskGraph, options: {
+    today: string | Date;
+    iterations: number;
+    start_index?: number;
+    seed?: number;
+    rng?: () => number;
+}): number[];
+/**
+ * Runs Monte Carlo schedule simulations and returns probabilistic completion forecasts.
+ * [SPEC: Scheduler v2.0 §10.1]
+ */
+declare function monte_carlo_forecast(delivery: Delivery, graph: TaskGraph, options?: MonteCarloOptions): Promise<MonteCarloResult>;
+
+type FeasibilityStatus = "FEASIBLE" | "NOT_FEASIBLE";
+interface FeasibilityRisk {
+    type: "budget_exceeded" | "cost_budget_exceeded" | "capacity_exceeded" | "schedule_exceeded" | "high_utilization" | "external_dependencies" | "schedule_overflow";
+    message: string;
+    overage_hours?: number;
+    overage_days?: number;
+    overage_cost_usd?: number;
+    track?: string;
+    tasks?: string[];
+    utilization?: number;
+}
+interface FeasibilitySummary {
+    total_tasks: number;
+    completed: number;
+    remaining: number;
+    effort_hours: {
+        required: number;
+        budget: number;
+    };
+    capacity_hours: {
+        available: number;
+        by_track: Record<string, number>;
+    };
+    pert: {
+        mean: number;
+        stddev: number;
+    };
+    dates: {
+        target: string | null;
+        projected: string | null;
+        buffer_days: number | null;
+    };
+    critical_path: string[];
+    critical_path_hours: number;
+}
+interface FeasibilityResult {
+    delivery: string;
+    status: FeasibilityStatus;
+    risks: FeasibilityRisk[];
+    summary: FeasibilitySummary;
+    simulation: SimulationResult;
+}
+/**
+ * Evaluates delivery feasibility from scope, dependencies, capacity, and schedule simulation.
+ * [SPEC: Scheduler v2.0 §9]
+ */
+declare function analyze_feasibility(deliveryId: string, graph: TaskGraph, today: string | Date): FeasibilityResult;
 
 type ReadinessState = "ready" | "blocked" | "in_progress" | "waiting_review" | "done";
 interface ReadinessPartitions {
@@ -557,6 +1090,213 @@ declare function compute_all_readiness(graph: TaskGraph): Map<string, ReadinessS
 declare function partition_by_readiness(graph: TaskGraph): ReadinessPartitions;
 declare function compute_readiness_with_corrections(graph: TaskGraph): ReadinessComputation;
 
+type VelocityTrend = "accelerating" | "stable" | "decelerating";
+interface VelocityPoint {
+    week_index: number;
+    week_start: string;
+    week_end: string;
+    completed_tasks: number;
+    delivered_hours: number;
+}
+interface VelocityMetrics {
+    window_weeks: number;
+    completed_runs: number;
+    tasks_completed_total: number;
+    delivered_hours_total: number;
+    tasks_completed_per_week: number;
+    hours_delivered_per_week: number;
+    accuracy_ratio: number | null;
+    trend: VelocityTrend;
+    points: VelocityPoint[];
+}
+/**
+ * Loads completed run logs from `.coop/runs/*.yml`.
+ * [SPEC: Architecture v2.0 §12]
+ */
+declare function load_completed_runs(coopDir: string): Run[];
+/**
+ * Computes historical delivery velocity from completed run logs.
+ * [SPEC: Scheduler v2.0 §5.3]
+ */
+declare function compute_velocity(runs: Run[], windowWeeks: number, options?: {
+    today?: string | Date;
+    graph?: TaskGraph;
+}): VelocityMetrics;
+
+type DeliveryRiskType = "behind_schedule" | "capacity_crunch" | "critical_path_not_started" | "high_risk_critical_path";
+interface DetectedDeliveryRisk {
+    type: DeliveryRiskType;
+    message: string;
+    task_ids?: string[];
+    track?: string;
+}
+/**
+ * Detects delivery risks from feasibility, critical path, and historical velocity.
+ * Emits `delivery.at_risk` when an emitter is provided and risks are found.
+ * [SPEC: Scheduler v2.0 §5.3]
+ */
+declare function detect_delivery_risks(delivery: Delivery, graph: TaskGraph, velocity: VelocityMetrics, options?: {
+    today?: string | Date;
+    eventEmitter?: CoopEventEmitter;
+}): DetectedDeliveryRisk[];
+
+/**
+ * Samples from the standard PERT-Beta distribution.
+ * [SPEC: Scheduler v2.0 §10.1]
+ */
+declare function sample_pert_beta(optimistic: number, expected: number, pessimistic: number, rng?: () => number): number;
+/**
+ * Samples task effort for Monte Carlo simulation.
+ * Tasks with estimates use PERT-Beta; others use +/-30% around fallback effort.
+ * [SPEC: Scheduler v2.0 §10.1]
+ */
+declare function sample_task_hours(task: Task, rng?: () => number): number;
+
+interface ScheduleOptions {
+    track?: string;
+    delivery?: string;
+    executor?: ExecutorType;
+    limit?: number;
+    today?: string | Date;
+    config?: CoopConfig;
+}
+interface ScoredTask {
+    task: Task;
+    score: number;
+    readiness: ReadinessState;
+    fits_capacity: boolean;
+    fits_wip: boolean;
+}
+/**
+ * Returns ranked ready tasks with score, capacity-fit, and WIP-fit annotations.
+ * [SPEC: Scheduler v2.0 §3 Stage 3-5]
+ */
+declare function schedule_next(graph: TaskGraph, options?: ScheduleOptions): ScoredTask[];
+
+interface ScoreWeights {
+    priority: Record<TaskPriority, number>;
+    urgency: {
+        days_7: number;
+        days_14: number;
+        days_28: number;
+    };
+    dependency_unlock: {
+        gte_5: number;
+        gte_3: number;
+        gte_1: number;
+        transitive_cap: number;
+    };
+    critical_path: number;
+    determinism: Record<TaskDeterminism, number>;
+    executor_fit: {
+        match: number;
+        mismatch: number;
+        ci_match: number;
+    };
+    type: Record<TaskType, number>;
+    complexity_penalty: Record<TaskComplexity, number>;
+    risk_penalty: Record<RiskLevel, number>;
+}
+interface ScoreContext {
+    deliveries?: Map<string, Delivery> | Delivery[];
+    cpm?: CriticalPathResult;
+    today?: string | Date;
+    target_executor?: ExecutorType;
+    config?: CoopConfig;
+}
+/**
+ * Default readiness ranking weights used by `compute_score`.
+ * [SPEC: Scheduler v2.0 §4.6]
+ */
+declare const DEFAULT_SCORE_WEIGHTS: ScoreWeights;
+/** [SPEC: Scheduler v2.0 §4.6] */
+declare function priority_weight(task: Task, config?: CoopConfig): number;
+/** [SPEC: Scheduler v2.0 §4.6] */
+declare function urgency_weight(task: Task, deliveries: Map<string, Delivery> | Delivery[], today: string | Date, config?: CoopConfig): number;
+/** [SPEC: Scheduler v2.0 §4.6] */
+declare function dependency_unlock_weight(taskId: string, graph: TaskGraph, config?: CoopConfig): number;
+/** [SPEC: Scheduler v2.0 §4.6] */
+declare function critical_path_weight(taskId: string, cpm: CriticalPathResult | undefined, config?: CoopConfig): number;
+/** [SPEC: Scheduler v2.0 §4.6] */
+declare function determinism_weight(task: Task, config?: CoopConfig): number;
+/** [SPEC: Scheduler v2.0 §4.6] */
+declare function executor_fit_weight(task: Task, targetExecutor?: ExecutorType, config?: CoopConfig): number;
+/** [SPEC: Scheduler v2.0 §4.6] */
+declare function type_weight(task: Task, config?: CoopConfig): number;
+/** [SPEC: Scheduler v2.0 §4.6] */
+declare function complexity_penalty(task: Task, config?: CoopConfig): number;
+/** [SPEC: Scheduler v2.0 §4.6] */
+declare function risk_penalty(task: Task, config?: CoopConfig): number;
+/**
+ * Computes composite scheduling score for one ready task.
+ * [SPEC: Scheduler v2.0 §4.6]
+ */
+declare function compute_score(task: Task, graph: TaskGraph, context?: ScoreContext): number;
+
+type WhatIfModification = {
+    kind: "without";
+    task_id: string;
+} | {
+    kind: "add_member";
+    target: string;
+    hours_per_week?: number;
+} | {
+    kind: "target";
+    target_date: string;
+} | {
+    kind: "set_priority";
+    task_id: string;
+    priority: NonNullable<Task["priority"]>;
+};
+interface WhatIfBaseline {
+    delivery_id: string;
+    graph: TaskGraph;
+    today: string | Date;
+}
+interface ComparisonRow {
+    metric: string;
+    original: string;
+    scenario: string;
+    delta: string;
+}
+interface ComparisonResult {
+    delivery: string;
+    label: string;
+    baseline: FeasibilityResult;
+    scenario: FeasibilityResult;
+    rows: ComparisonRow[];
+}
+/**
+ * Runs a cloned-delivery feasibility analysis with one or more scenario modifications.
+ * [SPEC: Scheduler v2.0 §9.2]
+ */
+declare function analyze_what_if(baseline: WhatIfBaseline, modification: WhatIfModification | WhatIfModification[]): ComparisonResult;
+
+interface MigrationContext {
+    file_path?: string;
+    file_mtime_iso?: string;
+}
+interface MigrationDefinition {
+    from: number;
+    to: number;
+    description: string;
+    migrate: (raw: Record<string, unknown>, context?: MigrationContext) => Record<string, unknown>;
+}
+interface MigrationReport {
+    from_version: number;
+    to_version: number;
+    dry_run: boolean;
+    files_scanned: number;
+    files_changed: number;
+    changed_files: string[];
+}
+interface MigrateRepositoryOptions {
+    dry_run?: boolean;
+}
+declare const MIGRATIONS: MigrationDefinition[];
+declare function migrate_task(rawTask: Record<string, unknown>, fromVersion: number, toVersion: number, context?: MigrationContext): Record<string, unknown>;
+declare function migrate_repository(coopDir: string, targetVersion?: number, options?: MigrateRepositoryOptions): MigrationReport;
+
 declare const CURRENT_SCHEMA_VERSION = 2;
 declare function read_schema_version(coopDir: string): number;
 declare function write_schema_version(coopDir: string, version: number): void;
@@ -582,6 +1322,7 @@ type TransitionContext = {
     actor?: string;
     dependencyStatuses?: Map<string, TaskStatus> | Record<string, TaskStatus>;
     now?: string | Date;
+    eventEmitter?: CoopEventEmitter;
 };
 type TransitionResult = {
     success: boolean;
@@ -645,6 +1386,43 @@ interface ValidationResult {
 }
 declare function validate(task: Task, context?: ValidationContext): ValidationResult;
 
+type CoopWorkspaceConfig = {
+    version?: number;
+    current_project?: string;
+};
+type CoopProjectRef = {
+    id: string;
+    name: string;
+    aliases: string[];
+    root: string;
+    repo_root: string;
+    layout: "legacy" | "v2";
+};
+type ResolveProjectOptions = {
+    project?: string;
+    require?: boolean;
+};
+declare function coop_workspace_dir(repoRoot: string): string;
+declare function coop_projects_dir(repoRoot: string): string;
+declare function coop_workspace_config_path(repoRoot: string): string;
+declare function coop_project_root(repoRoot: string, projectId: string): string;
+declare function coop_project_config_path(projectRoot: string): string;
+declare function repo_default_project_id(repoRoot: string): string;
+declare function repo_default_project_name(repoRoot: string): string;
+declare function has_v2_projects_layout(repoRoot: string): boolean;
+declare function has_legacy_project_layout(repoRoot: string): boolean;
+declare function read_workspace_config(repoRoot: string): CoopWorkspaceConfig;
+declare function write_workspace_config(repoRoot: string, config: CoopWorkspaceConfig): void;
+declare function read_project_config(projectRoot: string): CoopConfig;
+declare function list_projects(repoRoot: string): CoopProjectRef[];
+declare function resolve_project(repoRoot: string, options?: ResolveProjectOptions): CoopProjectRef;
+declare function ensure_workspace_layout(repoRoot: string): string;
+declare function is_project_initialized(projectRoot: string): boolean;
+
+/**
+ * Finds the nearest workspace root that contains package + workspace metadata.
+ * [SPEC: Architecture v2.0 §2]
+ */
 declare function findRepoRoot(cwd?: string): string | null;
 interface CompletionResult {
     item: BacklogItem;
@@ -652,19 +1430,59 @@ interface CompletionResult {
     releaseFile?: string;
     alreadyComplete: boolean;
 }
+/**
+ * Marks an item as done and appends release-note metadata when status changes.
+ * [SPEC: Architecture v2.0 §2]
+ */
 declare function completeItem(rootDir: string, id: string): CompletionResult;
+/**
+ * Ensures the canonical .coop workspace layout and default config exist.
+ * [SPEC: Architecture v2.0 §2, §3]
+ */
 declare function ensureCoopLayout(rootDir: string): void;
+/**
+ * Loads repository config and backlog state from disk into an indexed in-memory view.
+ * [SPEC: Architecture v2.0 §2]
+ */
 declare function loadState(rootDir: string): RepoState;
+/**
+ * Filters and sorts backlog items by status/owner/label/type/search.
+ * [SPEC: Architecture v2.0 §23]
+ */
 declare function queryItems(state: RepoState, filter: FilterSpec): BacklogItem[];
+/**
+ * Resolves an item by case-insensitive identifier.
+ * [SPEC: Architecture v2.0 §2]
+ */
 declare function getItemById(state: RepoState, id: string): BacklogItem | null;
+/**
+ * Creates and persists a new backlog item with generated or explicit identifier.
+ * [SPEC: Schema v2.0 §3]
+ */
 declare function createItem(rootDir: string, params: CreateItemParams): BacklogItem;
+/**
+ * Updates mutable backlog fields and rewrites frontmatter/body atomically.
+ * [SPEC: Schema v2.0 §3]
+ */
 declare function updateItem(rootDir: string, id: string, patch: UpdateItemParams): BacklogItem;
+/**
+ * Deletes an item if it has no remaining child references.
+ * [SPEC: Architecture v2.0 §2]
+ */
 declare function deleteItem(rootDir: string, id: string): BacklogItem;
+/**
+ * Renders a plain-text agent prompt from task metadata and acceptance criteria.
+ * [SPEC: Architecture v2.0 §13]
+ */
 declare function renderAgentPrompt(item: BacklogItem): string;
+/**
+ * Performs repository-wide structural and referential checks for backlog files.
+ * [SPEC: Schema v2.0 §12]
+ */
 declare function validateRepo(rootDir: string): {
     valid: boolean;
     errors: string[];
     warnings: string[];
 };
 
-export { type AIAgent, type AIResource, type AgentSpec, ArtifactType, type AutoTransitionResult, type AvailabilityWindow, type BacklogItem, type BacklogItemData, CURRENT_SCHEMA_VERSION, type ComputeNode, type ComputeResource, type CoopConfig, type CreateItemParams, type Delivery, type DeliveryBudget, type DeliveryGovernance, type DeliveryRisk, type DeliveryScope, DeliveryStatus, type EffectiveCapacity, type ExecutionConstraints, type ExecutionPermissions, ExecutorType, type FilterSpec, type FrontmatterParseResult, type GraphValidationResult, type HumanMember, type HumanResource, ITEM_STATUSES, ITEM_TYPES, type Idea, IdeaStatus, type ItemLinks, type ItemStatus, type ItemType, type ParsedDelivery, type ParsedIdea, type ParsedTask, type ReadinessComputation, type ReadinessPartitions, type ReadinessState, type ReadinessTransitionEvent, type ReadinessWarning, type ReferentialValidationContext, type RepoConfig, type RepoState, type ResourceProfile, RiskLevel, RunbookAction, type RunbookStep, type SemanticValidationContext, type StructuralValidationContext, type Task, TaskComplexity, type TaskComputed, type TaskCore, TaskDeterminism, type TaskEstimate, type TaskEstimation, type TaskExecution, type TaskGovernance, type TaskGraph, type TaskPlanning, TaskPriority, type TaskResources, TaskStatus, type TaskTransitionedEvent, TaskType, type Track, type TrackWip, type TransitionContext, type TransitionResult, type TransitionValidationContext, type UpdateItemParams, VALID_TASK_TRANSITIONS, VALID_TRANSITIONS, type ValidationContext, type ValidationError, type ValidationLevel, type ValidationResult, type WriteTaskOptions, build_graph, check_blocked, check_unblocked, completeItem, compute_all_readiness, compute_readiness, compute_readiness_with_corrections, createItem, deleteItem, detect_cycle, ensureCoopLayout, extract_subgraph, findRepoRoot, find_external_dependencies, getItemById, loadState, load_graph, parseDeliveryContent, parseDeliveryFile, parseFrontmatterContent, parseFrontmatterFile, parseIdeaContent, parseIdeaFile, parseTaskContent, parseTaskFile, parseYamlContent, parseYamlFile, partition_by_readiness, queryItems, read_schema_version, renderAgentPrompt, stringifyFrontmatter, topological_sort, transition, transitive_dependencies, transitive_dependents, updateItem, validate, validateReferential, validateRepo, validateSemantic, validateStructural, validateTransition, validate_graph, validate_transition, writeTask, write_schema_version };
+export { type AIAgent, type AIResource, type AgentSpec, type AllocationResult, ArtifactType, type AuthConfig, type AuthPolicy, type AutoTransitionResult, type AvailabilityWindow, type BacklogItem, type BacklogItemData, COOP_EVENT_TYPES, CURRENT_SCHEMA_VERSION, type CapacityLedger, type ComparisonResult, type ComparisonRow, type ComputeNode, type ComputeResource, type CoopConfig, type CoopEvent, CoopEventEmitter, type CoopEventType, type CoopProjectRef, type CoopWorkspaceConfig, type CreateItemParams, type CriticalPathResult, type CriticalPathTaskMetrics, DEFAULT_SCORE_WEIGHTS, type Delivery, type DeliveryAtRisk, type DeliveryBudget, type DeliveryCommitted, type DeliveryGovernance, type DeliveryRisk, type DeliveryRiskType, type DeliveryScope, DeliveryStatus, type DetectedDeliveryRisk, type EffectiveCapacity, type EventByType, type ExecutionConstraints, type ExecutionPermissions, ExecutorType, type ExternalDependencyRef, type ExternalDependencyResolution, type ExternalDependencyResolutionStatus, type ExternalDependencyResolverOptions, type ExternalRepoConfig, type FeasibilityResult, type FeasibilityRisk, type FeasibilityStatus, type FeasibilitySummary, type FilterSpec, type FrontmatterParseResult, type GraphCycleDetected, type GraphValidationContext, type GraphValidationResult, type HookRunResult, type HumanMember, type HumanResource, ITEM_STATUSES, ITEM_TYPES, type Idea, IdeaStatus, IndexManager, type IndexStatus, type ItemLinks, type ItemStatus, type ItemType, MIGRATIONS, type MigrateRepositoryOptions, type MigrationContext, type MigrationDefinition, type MigrationReport, type MonteCarloHistogramBucket, type MonteCarloOptions, type MonteCarloResult, type MonteCarloWorkerPayload, type ParsedDelivery, type ParsedIdea, type ParsedTask, type Permission, type PermissionContext, type PluginAction, type PluginActionConsole, type PluginActionGitHubPr, type PluginActionHandler, type PluginActionHandlerResult, type PluginActionWebhook, type PluginManifest, type PluginRunOptions, type PluginRunRecord, type PluginTrigger, type PolicyAction, type ReadinessComputation, type ReadinessPartitions, type ReadinessState, type ReadinessTransitionEvent, type ReadinessWarning, type ReferentialValidationContext, type RepoConfig, type RepoState, type ResourceProfile, RiskLevel, type Role, type Run, type RunCompleted, type RunFailed, type RunResourcesConsumed, type RunStarted, RunStatus, type RunStepResult, RunStepStatus, RunbookAction, type RunbookStep, type ScheduleOptions, type ScoreContext, type ScoredTask, type SemanticValidationContext, type SimulationResult, type StructuralValidationContext, type Task, type TaskAssigned, TaskComplexity, type TaskComputed, type TaskCore, type TaskCreated, TaskDeterminism, type TaskEstimate, type TaskEstimation, type TaskExecution, type TaskGovernance, type TaskGraph, type TaskPlanning, TaskPriority, type TaskResources, type TaskScheduleEntry, TaskStatus, type TaskTransitioned, type TaskTransitionedEvent, TaskType, type Track, type TrackUtilization, type TrackWip, type TransitionContext, type TransitionResult, type TransitionValidationContext, type UpdateItemParams, VALID_TASK_TRANSITIONS, VALID_TRANSITIONS, type ValidationContext, type ValidationError, type ValidationLevel, type ValidationResult, type VelocityMetrics, type VelocityPoint, type VelocityTrend, type WhatIfBaseline, type WhatIfModification, type WriteTaskOptions, allocate, allocate_ai, allocate_ai_tokens, analyze_feasibility, analyze_what_if, build_capacity_ledger, build_graph, check_blocked, check_permission, check_unblocked, check_wip, completeItem, complexity_penalty, compute_all_readiness, compute_critical_path, compute_readiness, compute_readiness_with_corrections, compute_score, compute_velocity, coop_project_config_path, coop_project_root, coop_projects_dir, coop_workspace_config_path, coop_workspace_dir, createItem, create_seeded_rng, critical_path_weight, deleteItem, dependency_unlock_weight, detect_cycle, detect_delivery_risks, determinism_weight, effective_weekly_hours, effort_or_default, ensureCoopLayout, ensure_workspace_layout, executor_fit_weight, external_dependencies_for_task, extract_subgraph, findRepoRoot, find_external_dependencies, getItemById, get_remaining_tokens, get_user_role, has_legacy_project_layout, has_v2_projects_layout, is_external_dependency, is_project_initialized, list_projects, loadState, load_auth_config, load_completed_runs, load_graph, load_plugins, migrate_repository, migrate_task, monte_carlo_forecast, parseDeliveryContent, parseDeliveryFile, parseFrontmatterContent, parseFrontmatterFile, parseIdeaContent, parseIdeaFile, parseTaskContent, parseTaskFile, parseYamlContent, parseYamlFile, parse_external_dependency, partition_by_readiness, pert_hours, pert_stddev, priority_weight, queryItems, read_project_config, read_schema_version, read_workspace_config, renderAgentPrompt, repo_default_project_id, repo_default_project_name, resolve_external_dependencies, resolve_project, risk_penalty, run_hook, run_monte_carlo_chunk, run_plugins_for_event, sample_pert_beta, sample_task_hours, schedule_next, simulate_schedule, stringifyFrontmatter, stringifyYamlContent, task_effort_hours, topological_sort, transition, transitive_dependencies, transitive_dependents, type_weight, updateItem, urgency_weight, validate, validateReferential, validateRepo, validateSemantic, validateStructural, validateTransition, validate_graph, validate_transition, writeTask, writeYamlFile, write_schema_version, write_workspace_config };