sdd-agent-platform 0.3.0 → 0.4.1

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

@@ -0,0 +1,32 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { parseSddTasksMarkdown } from '../sdd-docs/task-parser.js';
+import { resolveTaskDependencyReadiness, workflowDependencyBlockers } from './dependencies.js';
+
+function taskBlock(id: string, status: string, dependsOn: string[]): string {
+  const dependsOnBlock = dependsOn.length === 0 ? 'depends_on: []' : `depends_on:\n${dependsOn.map((dependency) => `  - ${dependency}`).join('\n')}`;
+  return `### ${id}: Dependency fixture\n\n\`\`\`sdd-task\nid: ${id}\nstatus: ${status}\nwave: 1\n${dependsOnBlock}\nacceptance_refs:\n  - AC-${id}\nplan_refs:\n  - Plan\naffected_files:\n  - docs/${id}.md\nvalidation:\n  - npm test\nrisk: []\n\`\`\`\n`;
+}
+
+test('dependency readiness blocks tasks until dependencies are completed', () => {
+  const model = parseSddTasksMarkdown(`# Tasks\n\n${taskBlock('DEP1', 'pending', [])}\n${taskBlock('DEP2', 'pending', ['DEP1'])}`, { tasksPath: 'tasks.md' });
+
+  const readiness = resolveTaskDependencyReadiness(model, 'DEP2');
+
+  assert.equal(readiness.ready, false);
+  assert.deepEqual(readiness.dependencies.map((dependency) => `${dependency.taskId}:${dependency.status}:${dependency.ready}`), ['DEP1:pending:false']);
+  assert.match(readiness.blockingReasons[0], /DEP2 depends on DEP1, but DEP1 has not passed required verification/);
+  assert.deepEqual(workflowDependencyBlockers(model).map((blocker) => `${blocker.taskId}->${blocker.dependencyId}:${blocker.dependencyStatus}`), ['DEP2->DEP1:pending']);
+});
+
+test('dependency readiness accepts completed dependencies and reports missing dependencies', () => {
+  const readyModel = parseSddTasksMarkdown(`# Tasks\n\n${taskBlock('DEP1', 'completed', [])}\n${taskBlock('DEP2', 'pending', ['DEP1'])}`, { tasksPath: 'tasks.md' });
+  const missingModel = parseSddTasksMarkdown(`# Tasks\n\n${taskBlock('DEP2', 'pending', ['MISSING'])}`, { tasksPath: 'tasks.md' });
+
+  assert.equal(resolveTaskDependencyReadiness(readyModel, 'DEP2').ready, true);
+  const missing = resolveTaskDependencyReadiness(missingModel, 'DEP2');
+  assert.equal(missing.ready, false);
+  assert.equal(missing.dependencies[0].status, 'missing');
+  assert.match(missing.blockingReasons[0], /MISSING was not found/);
+});

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

@@ -0,0 +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';
+}

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

@@ -0,0 +1,156 @@
+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;
+  }
+}