sdd-agent-platform 0.4.1 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/workflow-state/dependencies.ts

@@ -1,114 +1,114 @@
-import type { RunStateTaskRuntime } from '../run-state/model.js';
-import type { SddTask, SddTaskModel } from '../sdd-docs/task-parser.js';
-type TaskDependencyModel = Pick<SddTaskModel, 'tasks'>;
-
-export interface TaskDependencyReadinessOptions {
-  runtimeByTask?: Map<string, RunStateTaskRuntime>;
-}
-
-export interface TaskDependencyReadinessEntry {
-  taskId: string;
-  status: SddTask['status'] | 'missing';
-  ready: boolean;
-  reason: string | null;
-}
-
-export interface TaskDependencyReadiness {
-  taskId: string;
-  ready: boolean;
-  dependencies: TaskDependencyReadinessEntry[];
-  blockingReasons: string[];
-}
-
-export interface WorkflowDependencyBlocker {
-  taskId: string;
-  dependencyId: string;
-  dependencyStatus: SddTask['status'] | 'missing';
-  reason: string;
-}
-
-export function resolveTaskDependencyReadiness(model: TaskDependencyModel, taskId: string, options: TaskDependencyReadinessOptions = {}): TaskDependencyReadiness {
-  const task = model.tasks.find((candidate) => candidate.id === taskId) ?? null;
-  if (!task) {
-    return { taskId, ready: false, dependencies: [], blockingReasons: [`Task ${taskId} was not found.`] };
-  }
-
-  const dependencies = task.dependsOn.map((dependencyId) => dependencyReadinessEntry(task.id, dependencyId, model.tasks.find((candidate) => candidate.id === dependencyId) ?? null, options.runtimeByTask?.get(dependencyId)));
-  const blockingReasons = dependencies.map((dependency) => dependency.reason).filter((reason): reason is string => Boolean(reason));
-  return {
-    taskId: task.id,
-    ready: blockingReasons.length === 0,
-    dependencies,
-    blockingReasons
-  };
-}
-
-export function dependencyBlockingReasonsForTask(model: TaskDependencyModel, taskId: string, options: TaskDependencyReadinessOptions = {}): string[] {
-  return resolveTaskDependencyReadiness(model, taskId, options).blockingReasons;
-}
-
-export function workflowDependencyBlockers(model: TaskDependencyModel, options: TaskDependencyReadinessOptions = {}): WorkflowDependencyBlocker[] {
-  const blockers: WorkflowDependencyBlocker[] = [];
-  for (const task of model.tasks) {
-    if (task.status === 'completed' || task.status === 'deferred') {
-      continue;
-    }
-    for (const dependency of resolveTaskDependencyReadiness(model, task.id, options).dependencies) {
-      if (!dependency.ready && dependency.reason) {
-        blockers.push({
-          taskId: task.id,
-          dependencyId: dependency.taskId,
-          dependencyStatus: dependency.status,
-          reason: dependency.reason
-        });
-      }
-    }
-  }
-  return blockers;
-}
-
-export function nextDependencyTaskId(model: TaskDependencyModel, taskId: string, options: TaskDependencyReadinessOptions = {}): string | null {
-  return resolveTaskDependencyReadiness(model, taskId, options).dependencies.find((dependency) => !dependency.ready)?.taskId ?? null;
-}
-
-function dependencyReadinessEntry(taskId: string, dependencyId: string, dependency: SddTask | null, runtime: RunStateTaskRuntime | undefined): TaskDependencyReadinessEntry {
-  if (!dependency) {
-    return {
-      taskId: dependencyId,
-      status: 'missing',
-      ready: false,
-      reason: `Task ${taskId} depends on ${dependencyId}, but ${dependencyId} was not found; restore or remove the dependency before continuing ${taskId}.`
-    };
-  }
-  if (dependency.status === 'completed' || dependencyRuntimeSatisfiesImplementationBoundary(dependency, runtime)) {
-    return {
-      taskId: dependency.id,
-      status: dependency.status,
-      ready: true,
-      reason: null
-    };
-  }
-  return {
-    taskId: dependency.id,
-    status: dependency.status,
-    ready: false,
-    reason: dependencyRequiresVerifiedBoundary(dependency)
-      ? `Task ${taskId} depends on ${dependency.id}, but ${dependency.id} has not passed required verification; run sdd test task ${dependency.id} before continuing ${taskId}.`
-      : `Task ${taskId} depends on ${dependency.id}, but ${dependency.id} is not implemented; run sdd do task ${dependency.id} before continuing ${taskId}.`
-  };
-}
-
-function dependencyRuntimeSatisfiesImplementationBoundary(task: SddTask, runtime: RunStateTaskRuntime | undefined): boolean {
-  if (!runtimeTaskImplemented(runtime)) {
-    return false;
-  }
-  return !dependencyRequiresVerifiedBoundary(task) || runtime?.verificationStatus === 'pass' || runtime?.status === 'implemented_verified';
-}
-
-function dependencyRequiresVerifiedBoundary(task: SddTask): boolean {
-  return task.requiresVerifyBeforeNext || task.validationTiming === 'task_end';
-}
-
-function runtimeTaskImplemented(runtime: RunStateTaskRuntime | undefined): boolean {
-  return runtime?.implementationStatus === 'implemented' || runtime?.status === 'implemented_pending_validation' || runtime?.status === 'implemented_verified';
-}
+import type { RunStateTaskRuntime } from '../run-state/model.js';
+import type { SddTask, SddTaskModel } from '../sdd-docs/task-parser.js';
+type TaskDependencyModel = Pick<SddTaskModel, 'tasks'>;
+
+export interface TaskDependencyReadinessOptions {
+  runtimeByTask?: Map<string, RunStateTaskRuntime>;
+}
+
+export interface TaskDependencyReadinessEntry {
+  taskId: string;
+  status: SddTask['status'] | 'missing';
+  ready: boolean;
+  reason: string | null;
+}
+
+export interface TaskDependencyReadiness {
+  taskId: string;
+  ready: boolean;
+  dependencies: TaskDependencyReadinessEntry[];
+  blockingReasons: string[];
+}
+
+export interface WorkflowDependencyBlocker {
+  taskId: string;
+  dependencyId: string;
+  dependencyStatus: SddTask['status'] | 'missing';
+  reason: string;
+}
+
+export function resolveTaskDependencyReadiness(model: TaskDependencyModel, taskId: string, options: TaskDependencyReadinessOptions = {}): TaskDependencyReadiness {
+  const task = model.tasks.find((candidate) => candidate.id === taskId) ?? null;
+  if (!task) {
+    return { taskId, ready: false, dependencies: [], blockingReasons: [`Task ${taskId} was not found.`] };
+  }
+
+  const dependencies = task.dependsOn.map((dependencyId) => dependencyReadinessEntry(task.id, dependencyId, model.tasks.find((candidate) => candidate.id === dependencyId) ?? null, options.runtimeByTask?.get(dependencyId)));
+  const blockingReasons = dependencies.map((dependency) => dependency.reason).filter((reason): reason is string => Boolean(reason));
+  return {
+    taskId: task.id,
+    ready: blockingReasons.length === 0,
+    dependencies,
+    blockingReasons
+  };
+}
+
+export function dependencyBlockingReasonsForTask(model: TaskDependencyModel, taskId: string, options: TaskDependencyReadinessOptions = {}): string[] {
+  return resolveTaskDependencyReadiness(model, taskId, options).blockingReasons;
+}
+
+export function workflowDependencyBlockers(model: TaskDependencyModel, options: TaskDependencyReadinessOptions = {}): WorkflowDependencyBlocker[] {
+  const blockers: WorkflowDependencyBlocker[] = [];
+  for (const task of model.tasks) {
+    if (task.status === 'completed' || task.status === 'deferred') {
+      continue;
+    }
+    for (const dependency of resolveTaskDependencyReadiness(model, task.id, options).dependencies) {
+      if (!dependency.ready && dependency.reason) {
+        blockers.push({
+          taskId: task.id,
+          dependencyId: dependency.taskId,
+          dependencyStatus: dependency.status,
+          reason: dependency.reason
+        });
+      }
+    }
+  }
+  return blockers;
+}
+
+export function nextDependencyTaskId(model: TaskDependencyModel, taskId: string, options: TaskDependencyReadinessOptions = {}): string | null {
+  return resolveTaskDependencyReadiness(model, taskId, options).dependencies.find((dependency) => !dependency.ready)?.taskId ?? null;
+}
+
+function dependencyReadinessEntry(taskId: string, dependencyId: string, dependency: SddTask | null, runtime: RunStateTaskRuntime | undefined): TaskDependencyReadinessEntry {
+  if (!dependency) {
+    return {
+      taskId: dependencyId,
+      status: 'missing',
+      ready: false,
+      reason: `Task ${taskId} depends on ${dependencyId}, but ${dependencyId} was not found; restore or remove the dependency before continuing ${taskId}.`
+    };
+  }
+  if (dependency.status === 'completed' || dependencyRuntimeSatisfiesImplementationBoundary(dependency, runtime)) {
+    return {
+      taskId: dependency.id,
+      status: dependency.status,
+      ready: true,
+      reason: null
+    };
+  }
+  return {
+    taskId: dependency.id,
+    status: dependency.status,
+    ready: false,
+    reason: dependencyRequiresVerifiedBoundary(dependency)
+      ? `Task ${taskId} depends on ${dependency.id}, but ${dependency.id} has not passed required verification; run sdd test task ${dependency.id} before continuing ${taskId}.`
+      : `Task ${taskId} depends on ${dependency.id}, but ${dependency.id} is not implemented; run sdd do task ${dependency.id} before continuing ${taskId}.`
+  };
+}
+
+function dependencyRuntimeSatisfiesImplementationBoundary(task: SddTask, runtime: RunStateTaskRuntime | undefined): boolean {
+  if (!runtimeTaskImplemented(runtime)) {
+    return false;
+  }
+  return !dependencyRequiresVerifiedBoundary(task) || runtime?.verificationStatus === 'pass' || runtime?.status === 'implemented_verified';
+}
+
+function dependencyRequiresVerifiedBoundary(task: SddTask): boolean {
+  return task.requiresVerifyBeforeNext || task.validationTiming === 'task_end';
+}
+
+function runtimeTaskImplemented(runtime: RunStateTaskRuntime | undefined): boolean {
+  return runtime?.implementationStatus === 'implemented' || runtime?.status === 'implemented_pending_validation' || runtime?.status === 'implemented_verified';
+}

package/node_modules/@sdd-agent-platform/core/src/workflow-state/latest-eligible-run.ts

@@ -1,156 +1,184 @@
-import type { RunState } from '../run-state/model.js';
-import type { SddTaskModel } from '../sdd-docs/task-parser.js';
-
-export type DocumentCompatibilityClass = 'compatible' | 'soft_stale' | 'strict_stale' | 'incompatible';
-
-export interface LatestEligibleRunCandidate {
-  partition: string;
-  gitBranch: string | null;
-  taskId: string;
-  runId: string;
-  runStatus: RunState['status'];
-  validationStatus: RunState['validation']['status'];
-  syncBackStatus: RunState['syncBack']['status'];
-  affectedFiles: string[];
-  updatedAt: string;
-  compatibility: DocumentCompatibilityClass;
-  eligibleForDefaultApply: boolean;
-  reasons: string[];
-}
-
-export interface LatestEligibleRunSelection {
-  partition: string;
-  taskId: string;
-  selected: LatestEligibleRunCandidate | null;
-  candidates: LatestEligibleRunCandidate[];
-  rejected: LatestEligibleRunCandidate[];
-}
-
-export function selectLatestEligibleRun(input: { states: RunState[]; model: SddTaskModel; partition: string; taskId: string; currentGitBranch?: string | null }): LatestEligibleRunSelection {
-  const candidates = input.states
-    .filter((state) => state.partition === input.partition && state.taskId === input.taskId)
-    .map((state) => latestEligibleCandidate(state, input.model));
-  const visible = candidates.filter((candidate) => candidate.runStatus !== 'archived').sort(compareCandidates);
-  const eligible = visible.filter((candidate) => candidate.eligibleForDefaultApply);
-  return {
-    partition: input.partition,
-    taskId: input.taskId,
-    selected: eligible[0] ?? null,
-    candidates: visible,
-    rejected: candidates.filter((candidate) => !candidate.eligibleForDefaultApply).sort(compareCandidates)
-  };
-}
-
-export function selectLatestEligibleRunsByTask(input: { states: RunState[]; model: SddTaskModel; partition: string; currentGitBranch?: string | null }): LatestEligibleRunSelection[] {
-  const taskIds = Array.from(new Set([
-    ...input.model.tasks.map((task) => task.id),
-    ...input.states
-      .filter((state) => state.partition === input.partition && state.taskId)
-      .map((state) => state.taskId as string)
-  ]))
-    .sort((left, right) => left.localeCompare(right));
-  return taskIds.map((taskId) => selectLatestEligibleRun({ ...input, taskId }));
-}
-
-function latestEligibleCandidate(state: RunState, model: SddTaskModel): LatestEligibleRunCandidate {
-  const compatibility = classifyDocumentCompatibility(state, model);
-  const reasons = candidateRejectionReasons(state, compatibility);
-  return {
-    partition: state.partition ?? model.branch,
-    gitBranch: state.gitBranch,
-    taskId: state.taskId ?? state.currentTask ?? '',
-    runId: state.runId,
-    runStatus: state.status,
-    validationStatus: state.validation.status,
-    syncBackStatus: state.syncBack.status,
-    affectedFiles: state.affectedFiles,
-    updatedAt: state.updatedAt,
-    compatibility,
-    eligibleForDefaultApply: reasons.length === 0,
-    reasons
-  };
-}
-
-export function classifyDocumentCompatibility(state: RunState, model: SddTaskModel): DocumentCompatibilityClass {
-  const snapshot = state.documentSnapshot;
-  const hasSnapshot = Boolean(snapshot.specHash || snapshot.planHash || snapshot.tasksHash || snapshot.specContractHash || snapshot.planContractHash || snapshot.tasksContractHash);
-  if (!hasSnapshot) {
-    return 'incompatible';
-  }
-  const specMismatch = snapshot.specContractHash !== null
-    ? documentHashMismatch(snapshot.specContractHash, model.documents.specContractHash ?? null)
-    : documentHashMismatch(snapshot.specHash, model.documents.specHash ?? null);
-  const planMismatch = snapshot.planContractHash !== null
-    ? documentHashMismatch(snapshot.planContractHash, model.documents.planContractHash ?? null)
-    : documentHashMismatch(snapshot.planHash, model.documents.planHash ?? null);
-  const tasksSemanticMismatch = snapshot.tasksContractHash !== null
-    ? documentHashMismatch(snapshot.tasksContractHash, model.documents.tasksContractHash ?? null)
-    : false;
-  const tasksDocMismatch = documentHashMismatch(snapshot.tasksHash, model.documents.tasksHash ?? null);
-  if (specMismatch || planMismatch) {
-    return 'strict_stale';
-  }
-  if (model.documents.planStale || model.documents.tasksStale) {
-    return 'strict_stale';
-  }
-  if (tasksSemanticMismatch) {
-    return 'strict_stale';
-  }
-  if (tasksDocMismatch) {
-    return 'soft_stale';
-  }
-  return 'compatible';
-}
-
-function candidateRejectionReasons(state: RunState, compatibility: DocumentCompatibilityClass): string[] {
-  const reasons: string[] = [];
-  if (state.status === 'archived') {
-    reasons.push('Run is archived.');
-  }
-  if (state.status === 'failed') {
-    reasons.push('Run failed.');
-  }
-  if (state.status === 'blocked') {
-    reasons.push('Run is blocked.');
-  }
-  if (state.validation.status === 'fail' || state.validation.status === 'blocked') {
-    reasons.push(`Run validation status is ${state.validation.status}.`);
-  }
-  if (compatibility === 'strict_stale') {
-    reasons.push('Run document compatibility is strict_stale.');
-  }
-  if (compatibility === 'incompatible') {
-    reasons.push('Run document compatibility is incompatible.');
-  }
-  return reasons;
-}
-
-function documentHashMismatch(expected: string | null, actual: string | null): boolean {
-  if (!expected && !actual) {
-    return false;
-  }
-  return expected !== actual;
-}
-
-function compareCandidates(left: LatestEligibleRunCandidate, right: LatestEligibleRunCandidate): number {
-  const leftRank = compatibilityRank(left.compatibility);
-  const rightRank = compatibilityRank(right.compatibility);
-  if (leftRank !== rightRank) {
-    return leftRank - rightRank;
-  }
-  const updatedAt = Date.parse(right.updatedAt) - Date.parse(left.updatedAt);
-  return updatedAt !== 0 ? updatedAt : right.runId.localeCompare(left.runId);
-}
-
-function compatibilityRank(compatibility: DocumentCompatibilityClass): number {
-  switch (compatibility) {
-    case 'compatible':
-      return 0;
-    case 'soft_stale':
-      return 1;
-    case 'strict_stale':
-      return 2;
-    case 'incompatible':
-      return 3;
-  }
-}
+import type { RunState } from '../run-state/model.js';
+import type { SddTaskModel } from '../sdd-docs/task-parser.js';
+
+export type DocumentCompatibilityClass = 'compatible' | 'soft_stale' | 'strict_stale' | 'incompatible';
+
+export interface LatestEligibleRunCandidate {
+  partition: string;
+  gitBranch: string | null;
+  taskId: string;
+  runId: string;
+  runStatus: RunState['status'];
+  validationStatus: RunState['validation']['status'];
+  syncBackStatus: RunState['syncBack']['status'];
+  affectedFiles: string[];
+  updatedAt: string;
+  compatibility: DocumentCompatibilityClass;
+  eligibleForDefaultApply: boolean;
+  reasons: string[];
+}
+
+export interface LatestEligibleRunSelection {
+  partition: string;
+  taskId: string;
+  selected: LatestEligibleRunCandidate | null;
+  candidates: LatestEligibleRunCandidate[];
+  rejected: LatestEligibleRunCandidate[];
+}
+
+export function selectLatestEligibleRun(input: { states: RunState[]; model: SddTaskModel; partition: string; taskId: string; currentGitBranch?: string | null }): LatestEligibleRunSelection {
+  const candidates = input.states
+    .filter(isRunState)
+    .filter((state) => state.partition === input.partition && state.taskId === input.taskId)
+    .map((state) => latestEligibleCandidate(state, input.model));
+  const visible = candidates.filter((candidate) => candidate.runStatus !== 'archived').sort(compareCandidates);
+  const eligible = visible.filter((candidate) => candidate.eligibleForDefaultApply);
+  return {
+    partition: input.partition,
+    taskId: input.taskId,
+    selected: eligible[0] ?? null,
+    candidates: visible,
+    rejected: candidates.filter((candidate) => !candidate.eligibleForDefaultApply).sort(compareCandidates)
+  };
+}
+
+export function selectLatestEligibleRunsByTask(input: { states: RunState[]; model: SddTaskModel; partition: string; currentGitBranch?: string | null }): LatestEligibleRunSelection[] {
+  const states = input.states.filter(isRunState);
+  const taskIds = Array.from(new Set([
+    ...input.model.tasks.map((task) => task.id),
+    ...states
+      .filter((state) => state.partition === input.partition && state.taskId)
+      .map((state) => state.taskId as string)
+  ]))
+    .sort((left, right) => left.localeCompare(right));
+  return taskIds.map((taskId) => selectLatestEligibleRun({ ...input, states, taskId }));
+}
+
+function isRunState(state: RunState | undefined | null): state is RunState {
+  return Boolean(state?.runId && state.status && state.validation && state.syncBack && Array.isArray(state.affectedFiles));
+}
+
+function latestEligibleCandidate(state: RunState, model: SddTaskModel): LatestEligibleRunCandidate {
+  const compatibility = classifyDocumentCompatibility(state, model);
+  const reasons = candidateRejectionReasons(state, compatibility, model);
+  return {
+    partition: state.partition ?? model.branch,
+    gitBranch: state.gitBranch,
+    taskId: state.taskId ?? state.currentTask ?? '',
+    runId: state.runId,
+    runStatus: state.status,
+    validationStatus: state.validation.status,
+    syncBackStatus: state.syncBack.status,
+    affectedFiles: state.affectedFiles,
+    updatedAt: state.updatedAt,
+    compatibility,
+    eligibleForDefaultApply: reasons.length === 0,
+    reasons
+  };
+}
+
+export function classifyDocumentCompatibility(state: RunState, model: SddTaskModel): DocumentCompatibilityClass {
+  const snapshot = state.documentSnapshot;
+  const hasSnapshot = Boolean(snapshot.specHash || snapshot.planHash || snapshot.tasksHash || snapshot.specContractHash || snapshot.planContractHash || snapshot.tasksContractHash);
+  if (!hasSnapshot) {
+    return 'incompatible';
+  }
+  const specMismatch = snapshot.specContractHash !== null
+    ? documentHashMismatch(snapshot.specContractHash, model.documents.specContractHash ?? null)
+    : documentHashMismatch(snapshot.specHash, model.documents.specHash ?? null);
+  const planMismatch = snapshot.planContractHash !== null
+    ? documentHashMismatch(snapshot.planContractHash, model.documents.planContractHash ?? null)
+    : documentHashMismatch(snapshot.planHash, model.documents.planHash ?? null);
+  const tasksSemanticMismatch = snapshot.tasksContractHash !== null
+    ? documentHashMismatch(snapshot.tasksContractHash, model.documents.tasksContractHash ?? null)
+    : false;
+  const tasksDocMismatch = documentHashMismatch(snapshot.tasksHash, model.documents.tasksHash ?? null);
+  if (specMismatch || planMismatch) {
+    return 'strict_stale';
+  }
+  if (model.documents.planStale || model.documents.tasksStale) {
+    return 'strict_stale';
+  }
+  if (tasksSemanticMismatch) {
+    return 'strict_stale';
+  }
+  if (tasksDocMismatch) {
+    return 'soft_stale';
+  }
+  return 'compatible';
+}
+
+function candidateRejectionReasons(state: RunState, compatibility: DocumentCompatibilityClass, model: SddTaskModel): string[] {
+  const reasons: string[] = [];
+  if (state.status === 'archived') {
+    reasons.push('Run is archived.');
+  }
+  if (state.status === 'failed') {
+    reasons.push('Run failed.');
+  }
+  if (state.status === 'blocked') {
+    reasons.push('Run is blocked.');
+  }
+  if (state.validation.status === 'fail' || state.validation.status === 'blocked') {
+    reasons.push(`Run validation status is ${state.validation.status}.`);
+  }
+  if (compatibility === 'strict_stale') {
+    reasons.push('Run document compatibility is strict_stale.');
+    reasons.push(...strictStaleReasons(state, model));
+  }
+  if (compatibility === 'incompatible') {
+    reasons.push('Run document compatibility is incompatible.');
+  }
+  return reasons;
+}
+
+function strictStaleReasons(state: RunState, model: SddTaskModel): string[] {
+  const snapshot = state.documentSnapshot;
+  const reasons: string[] = [];
+  if (snapshot.specContractHash !== null && documentHashMismatch(snapshot.specContractHash, model.documents.specContractHash ?? null)) {
+    reasons.push('spec contract hash drift');
+  }
+  if (snapshot.planContractHash !== null && documentHashMismatch(snapshot.planContractHash, model.documents.planContractHash ?? null)) {
+    reasons.push('plan contract hash drift');
+  }
+  if (snapshot.tasksContractHash !== null && documentHashMismatch(snapshot.tasksContractHash, model.documents.tasksContractHash ?? null)) {
+    reasons.push('tasks contract hash drift');
+  }
+  if (model.documents.planStale) {
+    reasons.push('plan document is stale against accepted spec');
+  }
+  if (model.documents.tasksStale) {
+    reasons.push('tasks document is stale against accepted plan');
+  }
+  return reasons;
+}
+
+function documentHashMismatch(expected: string | null, actual: string | null): boolean {
+  if (!expected && !actual) {
+    return false;
+  }
+  return expected !== actual;
+}
+
+function compareCandidates(left: LatestEligibleRunCandidate, right: LatestEligibleRunCandidate): number {
+  const leftRank = compatibilityRank(left.compatibility);
+  const rightRank = compatibilityRank(right.compatibility);
+  if (leftRank !== rightRank) {
+    return leftRank - rightRank;
+  }
+  const updatedAt = Date.parse(right.updatedAt) - Date.parse(left.updatedAt);
+  return updatedAt !== 0 ? updatedAt : right.runId.localeCompare(left.runId);
+}
+
+function compatibilityRank(compatibility: DocumentCompatibilityClass): number {
+  switch (compatibility) {
+    case 'compatible':
+      return 0;
+    case 'soft_stale':
+      return 1;
+    case 'strict_stale':
+      return 2;
+    case 'incompatible':
+      return 3;
+  }
+}