@moretea-labs/forge 1.5.0-rc.1

package/src/cli/controller/task-status-resolver.ts

@@ -0,0 +1,403 @@
+import type { AgentJobMeta, AgentJobStatus } from "../agent-jobs/types";
+import type { ControllerIssue, ControllerTask, TaskStatus } from "./types";
+import { completionEvidenceComplete } from "./execution-policy";
+
+export type IssueLifecycleStatus = "active" | "completed" | "cancelled" | "archived";
+
+export type EffectiveTaskStatus =
+  | TaskStatus
+  | "queued"
+  | "waiting_for_user"
+  | "cancelled_by_parent"
+  | "archived_by_parent"
+  | "inactive_by_parent";
+
+export type EffectiveTaskStateReason =
+  | "issue_archived"
+  | "issue_cancelled"
+  | "issue_completed"
+  | "declared_done"
+  | "declared_cancelled"
+  | "declared_superseded"
+  | "completion_evidence_missing"
+  | "superseded_by_relation"
+  | "active_run_queued"
+  | "active_run_running"
+  | "active_run_waiting_for_user"
+  | "declared_status";
+
+export type VerificationStatus =
+  | "not_started"
+  | "pending"
+  | "passed"
+  | "changes_requested";
+
+export interface HistoricalRunOutcome {
+  runId: string;
+  status: AgentJobStatus;
+  finishedAt?: string;
+}
+
+export interface RunEvidenceAggregate {
+  latestRun?: AgentJobMeta;
+  verificationRun?: AgentJobMeta;
+  currentActiveRun?: AgentJobMeta;
+  activeRuns: AgentJobMeta[];
+  historicalOutcomes: HistoricalRunOutcome[];
+  multipleActiveRuns: boolean;
+}
+
+export interface EffectiveTaskState {
+  taskId: string;
+  declaredStatus: TaskStatus;
+  effectiveStatus: EffectiveTaskStatus;
+  reason: EffectiveTaskStateReason;
+  issueLifecycleStatus: IssueLifecycleStatus;
+  latestRunId?: string;
+  latestRunStatus?: AgentJobStatus;
+  activeRunId?: string;
+  activeRunStatus?: AgentJobStatus;
+  activeRunIds: string[];
+  historicalRunOutcomes: HistoricalRunOutcome[];
+  verificationStatus: VerificationStatus;
+  replacementTaskIds: string[];
+  terminal: boolean;
+  inactive: boolean;
+  dispatchable: boolean;
+  retryable: boolean;
+  requiresExplicitRetry: boolean;
+  dependencySatisfied: boolean;
+  multipleActiveRuns: boolean;
+}
+
+export interface SupersededDependencyMigration {
+  dependencyTaskId: string;
+  replacementTaskIds: string[];
+}
+
+export interface TaskDependencyState {
+  ready: boolean;
+  pendingTaskIds: string[];
+  cancelledTaskIds: string[];
+  missingTaskIds: string[];
+  supersededMigrations: SupersededDependencyMigration[];
+  migratedDependsOn: string[];
+}
+
+const EXPLICIT_TERMINAL = new Set<TaskStatus>(["done", "cancelled", "superseded"]);
+const ACTIVE_RUN = new Set<AgentJobStatus>(["queued", "starting", "running"]);
+const RETRYABLE_RUN = new Set<AgentJobStatus>(["failed", "cancelled", "unknown", "waiting_for_user"]);
+
+function runTimestamp(run: AgentJobMeta): number {
+  const parsed = Date.parse(run.createdAt);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function orderedTaskRuns(task: ControllerTask, runs: readonly AgentJobMeta[]): AgentJobMeta[] {
+  const taskRuns = runs.filter((run) => run.issueId === undefined || run.taskId === task.id);
+  const byId = new Map(taskRuns.map((run) => [run.runId, run]));
+  const ordered: AgentJobMeta[] = [];
+  const seen = new Set<string>();
+
+  for (const runId of task.runIds) {
+    const run = byId.get(runId);
+    if (!run || seen.has(runId)) continue;
+    seen.add(runId);
+    ordered.push(run);
+  }
+
+  const unlinked = taskRuns
+    .filter((run) => !seen.has(run.runId))
+    .sort((left, right) => runTimestamp(left) - runTimestamp(right));
+  ordered.push(...unlinked);
+  return ordered;
+}
+
+export function aggregateRunEvidence(
+  task: ControllerTask,
+  runs: readonly AgentJobMeta[] = [],
+): RunEvidenceAggregate {
+  const ordered = orderedTaskRuns(task, runs);
+  const latestRun = ordered.at(-1);
+  const activeRuns = ordered.filter((run) => ACTIVE_RUN.has(run.status));
+  const historicalOutcomes = ordered
+    .filter((run) => !ACTIVE_RUN.has(run.status))
+    .map((run) => ({ runId: run.runId, status: run.status, finishedAt: run.finishedAt }));
+  return {
+    latestRun,
+    verificationRun: task.verification?.runId
+      ? ordered.find((run) => run.runId === task.verification?.runId)
+      : undefined,
+    // Only the latest linked Run can be the current lifecycle owner. Older
+    // queued/running metadata is stale evidence and must not resurrect a Task.
+    currentActiveRun: latestRun && ACTIVE_RUN.has(latestRun.status) ? latestRun : undefined,
+    activeRuns,
+    historicalOutcomes,
+    multipleActiveRuns: activeRuns.length > 1,
+  };
+}
+
+export function resolveIssueLifecycleStatus(issue: ControllerIssue): IssueLifecycleStatus {
+  if (issue.archivedAt) return "archived";
+  if (issue.status === "cancelled") return "cancelled";
+  if (issue.status === "done") return "completed";
+  return "active";
+}
+
+function resolveVerificationStatus(issue: ControllerIssue, task: ControllerTask): VerificationStatus {
+  if (task.status === "changes_requested") return "changes_requested";
+  if (task.verification && task.status === "done" && !completionEvidenceComplete(task.verification, { issueId: issue.id, taskId: task.id })) return "pending";
+  if (task.verification && ["verified", "done"].includes(task.status)) return "passed";
+  if (["review", "integrated", "verifying", "verified"].includes(task.status)) return "pending";
+  return "not_started";
+}
+
+function baseState(
+  issue: ControllerIssue,
+  task: ControllerTask,
+  evidence: RunEvidenceAggregate,
+): Omit<EffectiveTaskState, "effectiveStatus" | "reason" | "terminal" | "inactive" | "dispatchable" | "retryable" | "requiresExplicitRetry" | "dependencySatisfied"> {
+  return {
+    taskId: task.id,
+    declaredStatus: task.status,
+    issueLifecycleStatus: resolveIssueLifecycleStatus(issue),
+    latestRunId: evidence.latestRun?.runId,
+    latestRunStatus: evidence.latestRun?.status,
+    activeRunId: evidence.currentActiveRun?.runId,
+    activeRunStatus: evidence.currentActiveRun?.status,
+    activeRunIds: evidence.activeRuns.map((run) => run.runId),
+    historicalRunOutcomes: evidence.historicalOutcomes,
+    verificationStatus: resolveVerificationStatus(issue, task),
+    replacementTaskIds: [...(task.supersededBy ?? [])],
+    multipleActiveRuns: evidence.multipleActiveRuns,
+  };
+}
+
+function finalizeState(
+  base: ReturnType<typeof baseState>,
+  effectiveStatus: EffectiveTaskStatus,
+  reason: EffectiveTaskStateReason,
+  terminal: boolean,
+  inactive: boolean,
+): EffectiveTaskState {
+  const latestRunStatus = base.latestRunStatus;
+  const requiresExplicitRetry =
+    !terminal &&
+    !inactive &&
+    latestRunStatus !== undefined &&
+    RETRYABLE_RUN.has(latestRunStatus);
+  const dispatchable =
+    !terminal &&
+    !inactive &&
+    base.activeRunIds.length === 0 &&
+    !requiresExplicitRetry &&
+    (effectiveStatus === "ready" || effectiveStatus === "changes_requested");
+  const retryable =
+    !terminal &&
+    !inactive &&
+    base.replacementTaskIds.length === 0 &&
+    base.activeRunIds.length === 0 &&
+    requiresExplicitRetry;
+  const dependencySatisfied = effectiveStatus === "done" || effectiveStatus === "superseded";
+  return {
+    ...base,
+    effectiveStatus,
+    reason,
+    terminal,
+    inactive,
+    dispatchable,
+    retryable,
+    requiresExplicitRetry,
+    dependencySatisfied,
+  };
+}
+
+export function resolveEffectiveTaskState(input: {
+  issue: ControllerIssue;
+  task: ControllerTask;
+  runs?: readonly AgentJobMeta[];
+}): EffectiveTaskState {
+  const { issue, task } = input;
+  const evidence = aggregateRunEvidence(task, input.runs ?? []);
+  const base = baseState(issue, task, evidence);
+
+  // Parent lifecycle is the strongest semantic for archived/cancelled Issues.
+  if (base.issueLifecycleStatus === "archived") {
+    return finalizeState(base, "archived_by_parent", "issue_archived", true, true);
+  }
+  if (base.issueLifecycleStatus === "cancelled") {
+    return finalizeState(base, "cancelled_by_parent", "issue_cancelled", true, true);
+  }
+
+  // supersededBy is a strong relation even when legacy data left another declared status.
+  if ((task.supersededBy?.length ?? 0) > 0) {
+    return finalizeState(base, "superseded", "superseded_by_relation", true, false);
+  }
+
+  // Explicit Task terminal state always wins over Run evidence.
+  if (task.status === "done" && completionEvidenceComplete(task.verification, { issueId: issue.id, taskId: task.id })) return finalizeState(base, "done", "declared_done", true, false);
+  if (task.status === "done") {
+    // When verification names a Run, only that Run can classify its missing
+    // closure evidence. A later unrelated Run must not rewrite the historical
+    // Task from integration-blocked to cleanup-blocked (or the reverse).
+    const closure = (task.verification?.runId
+      ? evidence.verificationRun
+      : evidence.latestRun)?.closureState;
+    const effective = closure === "cleanup_blocked" ? "cleanup_blocked"
+      : closure === "cleanup_pending" || closure === "cleaning" || closure === "integrated" ? "cleanup_pending"
+        : closure === "ready_to_integrate" || closure === "integration_pending" ? "ready_to_integrate"
+          : closure === "integrating" ? "integrating"
+            : "integration_blocked";
+    return finalizeState(base, effective, "completion_evidence_missing", false, false);
+  }
+  if (task.status === "cancelled") return finalizeState(base, "cancelled", "declared_cancelled", true, false);
+  if (task.status === "superseded") return finalizeState(base, "superseded", "declared_superseded", true, false);
+
+  if (base.issueLifecycleStatus === "completed") {
+    return finalizeState(base, "inactive_by_parent", "issue_completed", true, true);
+  }
+
+  // Only a currently active Run may override a non-terminal declared status.
+  if (evidence.currentActiveRun?.status === "queued" || evidence.currentActiveRun?.status === "starting") {
+    return finalizeState(base, "queued", "active_run_queued", false, false);
+  }
+  if (evidence.currentActiveRun?.status === "running") {
+    return finalizeState(base, "running", "active_run_running", false, false);
+  }
+  // Waiting-for-user Runs are not active execution owners: they are retryable
+  // historical evidence attached to the Task. The declared Task status
+  // (usually review after the worker preserved the worktree) controls the
+  // next action, so explicit integration, cancellation, or retry cannot
+  // deadlock behind its own attention state.
+
+  // Completed historical Runs are evidence only. They never resurrect or replace Task intent.
+  return finalizeState(base, task.status, "declared_status", EXPLICIT_TERMINAL.has(task.status), false);
+}
+
+export function resolveIssueTaskStates(
+  issue: ControllerIssue,
+  runsByTask: ReadonlyMap<string, readonly AgentJobMeta[]> = new Map(),
+): Map<string, EffectiveTaskState> {
+  return new Map(
+    issue.tasks.map((task) => [
+      task.id,
+      resolveEffectiveTaskState({ issue, task, runs: runsByTask.get(task.id) ?? [] }),
+    ]),
+  );
+}
+
+export function resolveTaskDependencies(
+  issue: ControllerIssue,
+  task: ControllerTask,
+  states: ReadonlyMap<string, EffectiveTaskState>,
+): TaskDependencyState {
+  const pendingTaskIds: string[] = [];
+  const cancelledTaskIds: string[] = [];
+  const missingTaskIds: string[] = [];
+  const supersededMigrations: SupersededDependencyMigration[] = [];
+  const migratedDependsOn: string[] = [];
+
+  for (const dependencyId of task.dependsOn) {
+    const dependency = issue.tasks.find((candidate) => candidate.id === dependencyId);
+    const state = states.get(dependencyId);
+    if (!dependency || !state) {
+      missingTaskIds.push(dependencyId);
+      continue;
+    }
+
+    if (state.effectiveStatus === "superseded") {
+      const replacements = [...(dependency.supersededBy ?? [])];
+      if (replacements.length === 0) {
+        missingTaskIds.push(dependencyId);
+        continue;
+      }
+      supersededMigrations.push({ dependencyTaskId: dependencyId, replacementTaskIds: replacements });
+      migratedDependsOn.push(...replacements);
+      // Replacement states are authoritative immediately. The stale dependency ID is only a migration warning.
+      for (const replacementId of replacements) {
+        const replacement = issue.tasks.find((candidate) => candidate.id === replacementId);
+        const replacementState = states.get(replacementId);
+        if (!replacement || !replacementState) {
+          missingTaskIds.push(replacementId);
+          continue;
+        }
+        if (replacementState.dependencySatisfied) continue;
+        if (
+          replacementState.effectiveStatus === "cancelled" ||
+          replacementState.effectiveStatus === "cancelled_by_parent" ||
+          replacementState.effectiveStatus === "archived_by_parent" ||
+          replacementState.effectiveStatus === "inactive_by_parent"
+        ) {
+          cancelledTaskIds.push(replacementId);
+        } else {
+          pendingTaskIds.push(replacementId);
+        }
+      }
+      continue;
+    }
+
+    if (state.dependencySatisfied) continue;
+    if (
+      state.effectiveStatus === "cancelled" ||
+      state.effectiveStatus === "cancelled_by_parent" ||
+      state.effectiveStatus === "archived_by_parent" ||
+      state.effectiveStatus === "inactive_by_parent"
+    ) {
+      cancelledTaskIds.push(dependencyId);
+      continue;
+    }
+    pendingTaskIds.push(dependencyId);
+  }
+
+  const normalizedMigrated = Array.from(new Set(migratedDependsOn));
+  return {
+    ready:
+      pendingTaskIds.length === 0 &&
+      cancelledTaskIds.length === 0 &&
+      missingTaskIds.length === 0,
+    pendingTaskIds,
+    cancelledTaskIds,
+    missingTaskIds,
+    supersededMigrations,
+    migratedDependsOn: normalizedMigrated,
+  };
+}
+
+export function assertTaskDispatchable(
+  issue: ControllerIssue,
+  task: ControllerTask,
+  runs: readonly AgentJobMeta[],
+  options: { retryFromRunId?: string } = {},
+): EffectiveTaskState {
+  const states = resolveIssueTaskStates(
+    issue,
+    new Map([[task.id, runs]]),
+  );
+  // Resolve every dependency without Run evidence; dependency terminal semantics remain authoritative.
+  for (const dependency of issue.tasks) {
+    if (!states.has(dependency.id)) {
+      states.set(dependency.id, resolveEffectiveTaskState({ issue, task: dependency }));
+    }
+  }
+  const state = states.get(task.id)!;
+  const dependencies = resolveTaskDependencies(issue, task, states);
+  const explicitRetryAuthorized =
+    state.retryable &&
+    state.requiresExplicitRetry &&
+    options.retryFromRunId === state.latestRunId &&
+    (state.effectiveStatus === "ready" || state.effectiveStatus === "blocked" || state.effectiveStatus === "changes_requested");
+  if (state.activeRunIds.length > 0) {
+    throw new Error(`task has active Run evidence: ${state.activeRunIds.join(", ")}`);
+  }
+  if (!state.dispatchable && !explicitRetryAuthorized) {
+    throw new Error(
+      `task is not dispatchable: declared=${state.declaredStatus}, effective=${state.effectiveStatus}, reason=${state.reason}, requiresExplicitRetry=${state.requiresExplicitRetry}`,
+    );
+  }
+  if (!dependencies.ready) {
+    throw new Error(
+      `task dependencies are not dispatchable: ${JSON.stringify(dependencies)}`,
+    );
+  }
+  return state;
+}

package/src/cli/controller/types.ts

@@ -0,0 +1,273 @@
+import type { ProcessCheckReceiptEvidence } from '../../runtime/evidence/process-check-receipt';
+
+export type IssueKind = 'bug' | 'feature' | 'governance' | 'investigation';
+export type IssueStatus = 'backlog' | 'analysis' | 'planned' | 'launch_blocked' | 'in_progress' | 'review' | 'done' | 'cancelled';
+export type TaskStatus = 'backlog' | 'analysis' | 'planned' | 'ready' | 'launch_blocked' | 'running' | 'blocked' | 'review' | 'verifying' | 'ready_to_integrate' | 'integrating' | 'integration_blocked' | 'integrated' | 'cleanup_pending' | 'cleanup_blocked' | 'changes_requested' | 'verified' | 'done' | 'cancelled' | 'superseded';
+export type TaskRisk = 'readonly' | 'low' | 'medium' | 'high' | 'destructive';
+export type ControllerAgent = 'codex' | 'claude' | 'github-copilot';
+
+export interface GitHubIssueLink {
+  owner: string;
+  repo: string;
+  number: number;
+  url: string;
+  projectOwner?: string;
+  projectNumber?: number;
+  projectItemId?: string;
+  syncedAt: string;
+}
+
+export interface TaskCommandEvidence {
+  id?: string;
+  command: string[];
+  cwd?: string;
+  ok: boolean;
+  exitCode?: number;
+  stdout?: string;
+  stderr?: string;
+  artifactPath?: string;
+  reportedBy?: string;
+  executedAt?: string;
+  source?: 'reported' | 'controller';
+}
+
+export interface IntegrationEvidence {
+  runId: string;
+  kind: 'commit' | 'no_change' | 'superseded';
+  targetBranch: string;
+  targetRevision: string;
+  sourceRevision?: string;
+  baseRevision?: string;
+  strategy: 'edit_session_commit' | 'already_integrated' | 'no_change' | 'superseded';
+  editSessionId?: string;
+  reachable: boolean;
+  recordedAt: string;
+}
+
+export interface CleanupEvidence {
+  runId: string;
+  worktreeRemovedOrNotCreated: boolean;
+  branchDeletedOrRetained: boolean;
+  leasesReleased: boolean;
+  runTerminal: boolean;
+  editSessionClosedOrNotCreated: boolean;
+  noActiveProcess: boolean;
+  noDirtyDiff: boolean;
+  retainedReason?: string;
+  maintenanceWarnings?: CompletionMaintenanceWarning[];
+  resourceBlockers?: CompletionResourceBlocker[];
+  recordedAt: string;
+}
+
+export type CompletionReceiptSource =
+  | 'direct_edit'
+  | 'controller_work'
+  | 'isolated_agent_run'
+  | 'workspace_run'
+  | 'remote_no_change_execution';
+
+export type CompletionReceiptDeliveryKind = 'commit' | 'no_change' | 'remote' | 'superseded';
+export type CompletionReceiptDeliveryStatus = 'integrated' | 'blocked';
+export type CompletionReceiptCleanupStatus = 'complete' | 'maintenance_warning' | 'blocked';
+
+export interface CompletionMaintenanceWarning {
+  code:
+    | 'worktree_cleanup_failed'
+    | 'branch_cleanup_failed'
+    | 'edit_session_backup_retained'
+    | 'cleanup_retained_by_request';
+  message: string;
+  resourceKind?: 'worktree' | 'branch' | 'edit_session' | 'lease' | 'process' | 'workspace';
+  resourceId?: string;
+  recordedAt: string;
+}
+
+export interface CompletionResourceBlocker {
+  code:
+    | 'unintegrated_changes'
+    | 'active_write_process'
+    | 'unknown_resource_ownership'
+    | 'dirty_owned_paths'
+    | 'edit_session_open'
+    | 'lease_active'
+    | 'run_not_terminal'
+    | 'target_revision_unreachable';
+  message: string;
+  resourceKind?: 'worktree' | 'branch' | 'edit_session' | 'lease' | 'process' | 'workspace';
+  resourceId?: string;
+  recordedAt: string;
+}
+
+export interface CompletionReceipt {
+  schemaVersion: 1;
+  receiptId: string;
+  source: CompletionReceiptSource;
+  issueId: string;
+  taskId: string;
+  runId?: string;
+  workId?: string;
+  editSessionId?: string;
+  targetBranch: string;
+  targetRevision: string;
+  sourceRevision?: string;
+  baseRevision?: string;
+  changedPaths: string[];
+  delivery: {
+    kind: CompletionReceiptDeliveryKind;
+    status: CompletionReceiptDeliveryStatus;
+    strategy: 'edit_session_commit' | 'already_integrated' | 'no_change' | 'remote';
+    reachable: boolean;
+    recordedAt: string;
+  };
+  cleanup: {
+    status: CompletionReceiptCleanupStatus;
+    warnings: CompletionMaintenanceWarning[];
+    blockers: CompletionResourceBlocker[];
+    recordedAt: string;
+  };
+  verifiedAt: string;
+  recordedAt: string;
+}
+
+export type TaskAcceptanceOutcome = 'passed' | 'failed' | 'not_evaluated';
+export type TaskAcceptanceSource = 'human_review' | 'controller_check' | 'run_completion' | 'reported' | 'legacy';
+
+export interface TaskAcceptanceResult {
+  criterion: string;
+  /** Backward-compatible projection. New decision code must prefer outcome/source. */
+  ok: boolean;
+  outcome?: TaskAcceptanceOutcome;
+  source?: TaskAcceptanceSource;
+  evidence?: string;
+}
+
+export interface TaskVerification {
+  repoId?: string;
+  runId?: string;
+  integratedRevision?: string;
+  reviewedDiffHash?: string;
+  checkResults: Array<{
+    checkId: string;
+    ok: boolean;
+    summary?: string;
+    receipt?: ProcessCheckReceiptEvidence;
+  }>;
+  commandEvidence?: TaskCommandEvidence[];
+  acceptanceResults: TaskAcceptanceResult[];
+  reviewer: string;
+  verifiedAt: string;
+  autoCompleted?: boolean;
+  completionReceipt?: CompletionReceipt;
+  integrationEvidence?: IntegrationEvidence;
+  cleanupEvidence?: CleanupEvidence;
+}
+
+export interface ControllerTask {
+  repoId?: string;
+  id: string;
+  title: string;
+  /**
+   * Compatibility projection link. Once present, Work owns the execution
+   * contract and this Task must not be used as a second mutable authority.
+   */
+  workId?: string;
+  /** @deprecated Read legacy snapshots only; derive from the linked Work. */
+  objective: string;
+  /** @deprecated Read legacy snapshots only; derive from the linked Work. */
+  status: TaskStatus;
+  dependsOn: string[];
+  /** @deprecated Read legacy snapshots only; derive from the linked Work. */
+  allowedPaths: string[];
+  /** @deprecated Read legacy snapshots only; derive from the linked Work. */
+  forbiddenPaths: string[];
+  /** @deprecated Read legacy snapshots only; derive from the linked Work. */
+  checks: string[];
+  /** @deprecated Read legacy snapshots only; derive from the linked Work. */
+  acceptanceCriteria: string[];
+  /** @deprecated Read legacy snapshots only; derive from the linked Work. */
+  risk: TaskRisk;
+  /** Optional planning hint only. The executor is selected at dispatch time. */
+  recommendedAgent?: ControllerAgent;
+  notes: string[];
+  runIds: string[];
+  github?: GitHubIssueLink;
+  verification?: TaskVerification;
+  supersededBy?: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ControllerIssue {
+  schemaVersion: 1 | 2 | 3 | 4 | 5 | 6;
+  repoId?: string;
+  id: string;
+  title: string;
+  slug: string;
+  kind: IssueKind;
+  status: IssueStatus;
+  summary: string;
+  goals: string[];
+  nonGoals: string[];
+  acceptanceCriteria: string[];
+  relatedArtifacts: string[];
+  tasks: ControllerTask[];
+  github?: GitHubIssueLink;
+  ephemeral?: boolean;
+  ephemeralOwnerJobId?: string;
+  archivedAt?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface TaskDraft {
+  repoId?: string;
+  title: string;
+  objective: string;
+  dependsOn?: string[];
+  allowedPaths?: string[];
+  forbiddenPaths?: string[];
+  checks?: string[];
+  acceptanceCriteria?: string[];
+  risk?: TaskRisk;
+  recommendedAgent?: ControllerAgent;
+}
+
+export interface IssueReadinessFinding {
+  code: string;
+  level: 'blocker' | 'warning';
+  message: string;
+  taskId?: string;
+}
+
+export interface TaskReadiness {
+  issueId: string;
+  taskId: string;
+  ready: boolean;
+  queueable: boolean;
+  approvalSatisfied: boolean;
+  score: number;
+  blockers: IssueReadinessFinding[];
+  warnings: IssueReadinessFinding[];
+  approval: 'auto' | 'confirm' | 'manual-only';
+  executionClass: 'read_only' | 'low_risk_change' | 'medium_risk_change' | 'high_risk_change' | 'destructive_change';
+  effectiveStatus: string;
+  requiresExplicitRetry: boolean;
+  retryable: boolean;
+}
+
+export interface IssueReadiness {
+  issueId: string;
+  score: number;
+  ready: boolean;
+  queueable: boolean;
+  blockers: IssueReadinessFinding[];
+  taskBlockers: IssueReadinessFinding[];
+  warnings: IssueReadinessFinding[];
+  readyTaskIds: string[];
+  queueableTaskIds: string[];
+  approvalPendingTaskIds: string[];
+  blockedTaskIds?: string[];
+  taskReadiness?: TaskReadiness[];
+  suggestedMaxParallel: number;
+  agents: Record<ControllerAgent, number>;
+}