sdd-agent-platform 0.4.0 → 0.4.2

package/node_modules/@sdd-agent-platform/core/src/workflow-state/affected-file-conflicts.ts

@@ -7,7 +7,6 @@ export interface WorkflowAffectedFileConflict {
   taskId: string;
   runId: string;
   runStatus: RunState['status'];
-  syncBackStatus: RunState['syncBack']['status'];
   updatedAt: string;
 }
 
@@ -31,7 +30,6 @@ export function affectedFileConflictsForSelectedRun(states: RunState[], selected
           taskId: state.taskId,
           runId: state.runId,
           runStatus: state.status,
-          syncBackStatus: state.syncBack.status,
           updatedAt: state.updatedAt
         });
       }
@@ -40,6 +38,11 @@ export function affectedFileConflictsForSelectedRun(states: RunState[], selected
   return conflicts.sort((left, right) => left.file.localeCompare(right.file) || left.partition.localeCompare(right.partition) || left.taskId.localeCompare(right.taskId) || left.runId.localeCompare(right.runId));
 }
 
+export function affectedFileConflictsForSelectedRuns(states: RunState[], selectedRuns: RunState[]): WorkflowAffectedFileConflict[] {
+  const conflicts = selectedRuns.flatMap((selected) => affectedFileConflictsForSelectedRun(states, selected));
+  return uniqueBy(conflicts, (conflict) => `${conflict.file}:${conflict.partition}:${conflict.taskId}:${conflict.runId}`);
+}
+
 function isAffectedFileConflictCandidate(candidate: RunState, selected: RunState): candidate is RunState & { partition: string; taskId: string } {
   if (candidate.runId === selected.runId || candidate.status === 'archived' || !candidate.partition || !candidate.taskId) {
     return false;
@@ -54,7 +57,7 @@ function isAffectedFileConflictCandidate(candidate: RunState, selected: RunState
 }
 
 function isActiveAffectedFileRun(state: RunState): boolean {
-  return state.status === 'created' || state.status === 'running' || state.syncBack.status === 'proposed';
+  return state.status === 'created' || state.status === 'running';
 }
 
 function selectedSupersedesCandidate(selected: RunState, candidate: RunState): boolean {
@@ -66,7 +69,7 @@ function selectedSupersedesCandidate(selected: RunState, candidate: RunState): b
     selected.status === 'completed' &&
     selected.validation.status === 'pass' &&
     Date.parse(selected.updatedAt) > Date.parse(candidate.updatedAt) &&
-    (candidate.status === 'failed' || candidate.status === 'blocked' || candidate.validation.status === 'fail' || candidate.validation.status === 'blocked' || candidate.syncBack.status === 'proposed')
+    (candidate.status === 'failed' || candidate.status === 'blocked' || candidate.validation.status === 'fail' || candidate.validation.status === 'blocked')
   );
 }
 
@@ -77,3 +80,15 @@ function isNonAuthoritativeForegroundRun(state: RunState): boolean {
   const delegations = Object.values(state.delegations);
   return delegations.length > 0 && delegations.every((delegation) => delegation.runMode === 'foreground' && !delegation.blocking && !delegation.requiredForPhaseExit);
 }
+
+function uniqueBy<T>(items: T[], keyOf: (item: T) => string): T[] {
+  const seen = new Set<string>();
+  return items.filter((item) => {
+    const key = keyOf(item);
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+}

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

@@ -16,7 +16,7 @@ test('dependency readiness blocks tasks until dependencies are completed', () =>
 
   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 status is pending/);
+  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']);
 });
 

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

@@ -1,6 +1,11 @@
+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';
@@ -22,13 +27,13 @@ export interface WorkflowDependencyBlocker {
   reason: string;
 }
 
-export function resolveTaskDependencyReadiness(model: TaskDependencyModel, taskId: string): TaskDependencyReadiness {
+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));
+  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,
@@ -38,17 +43,17 @@ export function resolveTaskDependencyReadiness(model: TaskDependencyModel, taskI
   };
 }
 
-export function dependencyBlockingReasonsForTask(model: TaskDependencyModel, taskId: string): string[] {
-  return resolveTaskDependencyReadiness(model, taskId).blockingReasons;
+export function dependencyBlockingReasonsForTask(model: TaskDependencyModel, taskId: string, options: TaskDependencyReadinessOptions = {}): string[] {
+  return resolveTaskDependencyReadiness(model, taskId, options).blockingReasons;
 }
 
-export function workflowDependencyBlockers(model: TaskDependencyModel): WorkflowDependencyBlocker[] {
+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).dependencies) {
+    for (const dependency of resolveTaskDependencyReadiness(model, task.id, options).dependencies) {
       if (!dependency.ready && dependency.reason) {
         blockers.push({
           taskId: task.id,
@@ -62,11 +67,11 @@ export function workflowDependencyBlockers(model: TaskDependencyModel): Workflow
   return blockers;
 }
 
-export function nextDependencyTaskId(model: TaskDependencyModel, taskId: string): string | null {
-  return resolveTaskDependencyReadiness(model, taskId).dependencies.find((dependency) => !dependency.ready)?.taskId ?? null;
+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): TaskDependencyReadinessEntry {
+function dependencyReadinessEntry(taskId: string, dependencyId: string, dependency: SddTask | null, runtime: RunStateTaskRuntime | undefined): TaskDependencyReadinessEntry {
   if (!dependency) {
     return {
       taskId: dependencyId,
@@ -75,7 +80,7 @@ function dependencyReadinessEntry(taskId: string, dependencyId: string, dependen
       reason: `Task ${taskId} depends on ${dependencyId}, but ${dependencyId} was not found; restore or remove the dependency before continuing ${taskId}.`
     };
   }
-  if (dependency.status === 'completed') {
+  if (dependency.status === 'completed' || dependencyRuntimeSatisfiesImplementationBoundary(dependency, runtime)) {
     return {
       taskId: dependency.id,
       status: dependency.status,
@@ -87,6 +92,23 @@ function dependencyReadinessEntry(taskId: string, dependencyId: string, dependen
     taskId: dependency.id,
     status: dependency.status,
     ready: false,
-    reason: `Task ${taskId} depends on ${dependency.id}, but ${dependency.id} status is ${dependency.status}; complete and sync-back ${dependency.id} before continuing ${taskId}.`
+    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,224 @@
+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'];
+  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, model, 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,
+    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 task = (state.taskId ?? state.currentTask) ? model.tasks.find((candidate) => candidate.id === (state.taskId ?? state.currentTask)) ?? null : null;
+  const taskContractMismatch = snapshot.taskContractHash !== null && task
+    ? documentHashMismatch(snapshot.taskContractHash, task.contractHash)
+    : false;
+  const tasksSemanticMismatch = snapshot.tasksContractHash !== null
+    ? documentHashMismatch(snapshot.tasksContractHash, model.documents.tasksContractHash ?? null) && !runTaskContractStillCompatible(state, task)
+    : false;
+  const tasksDocMismatch = documentHashMismatch(snapshot.tasksHash, model.documents.tasksHash ?? null);
+  if (specMismatch || planMismatch) {
+    return 'strict_stale';
+  }
+  if (model.documents.planStale || model.documents.verifyStale) {
+    return 'strict_stale';
+  }
+  if (taskContractMismatch) {
+    return 'strict_stale';
+  }
+  if (tasksSemanticMismatch) {
+    return 'strict_stale';
+  }
+  if (tasksDocMismatch) {
+    return 'soft_stale';
+  }
+  return 'compatible';
+}
+
+function candidateRejectionReasons(state: RunState, model: SddTaskModel, 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(...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 (documentHashMismatch(snapshot.specContractHash ?? snapshot.specHash, snapshot.specContractHash !== null ? model.documents.specContractHash ?? null : model.documents.specHash ?? null)) {
+    reasons.push('Run document compatibility is strict_stale: spec hash drift.');
+  }
+  if (documentHashMismatch(snapshot.planContractHash ?? snapshot.planHash, snapshot.planContractHash !== null ? model.documents.planContractHash ?? null : model.documents.planHash ?? null)) {
+    reasons.push('Run document compatibility is strict_stale: plan hash drift.');
+  }
+  const task = (state.taskId ?? state.currentTask) ? model.tasks.find((candidate) => candidate.id === (state.taskId ?? state.currentTask)) ?? null : null;
+  if (snapshot.taskContractHash !== null && task && documentHashMismatch(snapshot.taskContractHash, task.contractHash)) {
+    reasons.push('Run document compatibility is strict_stale: task contract hash drift.');
+  }
+  if (snapshot.tasksContractHash !== null && documentHashMismatch(snapshot.tasksContractHash, model.documents.tasksContractHash ?? null) && !runTaskContractStillCompatible(state, task)) {
+    reasons.push('Run document compatibility is strict_stale: tasks contract hash drift.');
+  }
+  if (snapshot.tasksContractHash === null && documentHashMismatch(snapshot.tasksHash, model.documents.tasksHash ?? null) && !runTaskContractStillCompatible(state, task)) {
+    reasons.push('Run document compatibility is strict_stale: tasks semantic hash drift.');
+  }
+  if (model.documents.planStale) {
+    reasons.push('Run document compatibility is strict_stale: plan contract hash drift.');
+  }
+  if (model.documents.verifyStale) {
+    reasons.push('Run document compatibility is strict_stale: verify contract hash drift.');
+  }
+  return reasons.length > 0 ? reasons : ['Run document compatibility is strict_stale.'];
+}
+
+function runTaskContractStillCompatible(state: RunState, task: SddTaskModel['tasks'][number] | null): boolean {
+  if (!task) {
+    return false;
+  }
+  const snapshot = state.documentSnapshot;
+  if (snapshot.taskContractHash !== null) {
+    return !documentHashMismatch(snapshot.taskContractHash, task.contractHash);
+  }
+  if (state.affectedFiles.length > 0 && !sameStringList(state.affectedFiles, task.affectedFiles)) {
+    return false;
+  }
+  const runtime = state.tasks[task.id];
+  if (runtime) {
+    if ((runtime.validationBatch ?? null) !== (task.validationBatch ?? null)) {
+      return false;
+    }
+    if ((runtime.validationTiming ?? 'task_end') !== task.validationTiming) {
+      return false;
+    }
+    if ((runtime.requiresVerifyBeforeNext ?? true) !== task.requiresVerifyBeforeNext) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function sameStringList(left: string[], right: string[]): boolean {
+  if (left.length !== right.length) {
+    return false;
+  }
+  const normalizedLeft = [...left].sort();
+  const normalizedRight = [...right].sort();
+  return normalizedLeft.every((value, index) => value === normalizedRight[index]);
+}
+
+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;
+  }
+}

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

@@ -0,0 +1,158 @@
+import type { SddTask, SddTaskModel } from '../sdd-docs/task-parser.js';
+import type { LatestEligibleRunSelection } from './latest-eligible-run.js';
+
+export type MixedVersionRecoveryIssueKind = 'legacy_artifact_ref' | 'non_executable_validation' | 'strict_stale_contract_drift' | 'legacy_stage_state' | 'missing_stage_evidence_rule';
+export type MixedVersionRecoveryIssueSeverity = 'info' | 'warn' | 'blocking';
+
+export interface MixedVersionRecoveryIssue {
+  kind: MixedVersionRecoveryIssueKind;
+  severity: MixedVersionRecoveryIssueSeverity;
+  file?: string;
+  taskId?: string;
+  current?: string;
+  expected?: string;
+  safeFixAvailable: boolean;
+  message: string;
+}
+
+export interface MixedVersionMechanicalUpdate {
+  issueKind: MixedVersionRecoveryIssueKind;
+  file: string;
+  current: string;
+  expected: string;
+  preview: string;
+}
+
+export interface MixedVersionStaleRunImpact {
+  taskId: string;
+  runId: string;
+  reasons: string[];
+}
+
+export interface MixedVersionRecoveryPlan {
+  detectedIssues: MixedVersionRecoveryIssue[];
+  safeMechanicalUpdates: MixedVersionMechanicalUpdate[];
+  behaviorChangingUpdates: MixedVersionRecoveryIssue[];
+  staleRunImpact: MixedVersionStaleRunImpact[];
+  evidenceReplayNeeded: string[];
+  nextCommands: string[];
+}
+
+export function buildMixedVersionRecoveryPlan(input: { model: SddTaskModel; latestEligibleRunsByTask: LatestEligibleRunSelection[]; verifyText?: string | null }): MixedVersionRecoveryPlan {
+  const issues = [
+    ...legacyArtifactRefIssues(input.model),
+    ...validationCommandIssues(input.model),
+    ...strictStaleIssues(input.latestEligibleRunsByTask)
+  ];
+  if (input.model.documents.verifyExists && input.verifyText !== undefined && !mentionsStageEvidenceRule(input.verifyText)) {
+    issues.push({
+      kind: 'missing_stage_evidence_rule',
+      severity: 'warn',
+      file: input.model.verifyPath,
+      current: 'missing stage evidence ref rule',
+      expected: 'verify.md states result evidence must use .sdd/runs/<branch>/<stage>/*.md refs',
+      safeFixAvailable: false,
+      message: 'verify.md does not state the stage evidence reference rule.'
+    });
+  }
+  const safeMechanicalUpdates = issues.flatMap((issue) => mechanicalUpdateForIssue(issue));
+  const staleRunImpact = input.latestEligibleRunsByTask.flatMap((selection) => selection.rejected
+    .filter((candidate) => candidate.reasons.some((reason) => reason.includes('strict_stale')))
+    .map((candidate) => ({ taskId: selection.taskId, runId: candidate.runId, reasons: candidate.reasons })));
+  const evidenceReplayNeeded = [...new Set(staleRunImpact.map((impact) => impact.taskId))].sort();
+  return {
+    detectedIssues: issues,
+    safeMechanicalUpdates,
+    behaviorChangingUpdates: issues.filter((issue) => !issue.safeFixAvailable),
+    staleRunImpact,
+    evidenceReplayNeeded,
+    nextCommands: nextCommands(input.model.branch, safeMechanicalUpdates.length, evidenceReplayNeeded)
+  };
+}
+
+export function canonicalRunRelativeArtifactRef(_branch: string, _ref: string): string | null {
+  return null;
+}
+
+function legacyArtifactRefIssues(model: SddTaskModel): MixedVersionRecoveryIssue[] {
+  return model.tasks.flatMap((task) => task.requiredArtifacts.flatMap((artifact) => {
+    const canonical = canonicalRunRelativeArtifactRef(model.branch, artifact);
+    return canonical ? [{
+      kind: 'legacy_artifact_ref' as const,
+      severity: 'warn' as const,
+      file: task.source.filePath,
+      taskId: task.id,
+      current: artifact,
+      expected: canonical,
+      safeFixAvailable: true,
+      message: `Task ${task.id} uses legacy evidence ref ${artifact}; use .sdd/runs/<branch>/<stage>/*.md stage evidence refs instead.`
+    }] : [];
+  }));
+}
+
+
+function validationCommandIssues(model: SddTaskModel): MixedVersionRecoveryIssue[] {
+  return model.tasks.flatMap((task) => task.validationCommands.flatMap((command) => nonExecutableValidationIssue(task, command.command)));
+}
+
+function nonExecutableValidationIssue(task: SddTask, command: string): MixedVersionRecoveryIssue[] {
+  const normalized = command.trim().toLowerCase();
+  if (!normalized.startsWith('```') && !normalized.startsWith('powershell') && !normalized.startsWith('manual:')) {
+    return [];
+  }
+  return [{
+    kind: 'non_executable_validation',
+    severity: 'blocking',
+    file: task.source.filePath,
+    taskId: task.id,
+    current: command,
+    expected: 'plain executable validation command',
+    safeFixAvailable: normalized.startsWith('```'),
+    message: `Task ${task.id} validation command is not directly executable: ${command}`
+  }];
+}
+
+function strictStaleIssues(selections: LatestEligibleRunSelection[]): MixedVersionRecoveryIssue[] {
+  return selections.flatMap((selection) => selection.rejected.flatMap((candidate) => candidate.reasons
+    .filter((reason) => reason.includes('strict_stale'))
+    .map((reason) => ({
+      kind: 'strict_stale_contract_drift' as const,
+      severity: 'warn' as const,
+      taskId: selection.taskId,
+      current: candidate.runId,
+      expected: 'replay evidence against current document contracts',
+      safeFixAvailable: false,
+      message: reason
+    }))));
+}
+
+function mentionsStageEvidenceRule(verifyText: string | null): boolean {
+  return Boolean(verifyText && /runs\/<branch>\/<stage>|stage evidence/i.test(verifyText));
+}
+
+function mechanicalUpdateForIssue(issue: MixedVersionRecoveryIssue): MixedVersionMechanicalUpdate[] {
+  if (!issue.safeFixAvailable || !issue.file || !issue.current || !issue.expected) {
+    return [];
+  }
+  return [{
+    issueKind: issue.kind,
+    file: issue.file,
+    current: issue.current,
+    expected: issue.expected,
+    preview: `replace ${issue.current} -> ${issue.expected}`
+  }];
+}
+
+function nextCommands(branch: string, safeFixes: number, replayTaskIds: string[]): string[] {
+  const commands: string[] = [];
+  if (safeFixes > 0) {
+    commands.push(`sdd doctor --branch ${branch} --latest-only`);
+  }
+  for (const taskId of replayTaskIds) {
+    commands.push(`sdd test task-${taskId} --branch ${branch}`);
+  }
+  if (commands.length === 0) {
+    commands.push(`sdd status --branch ${branch}`);
+  }
+  return commands;
+}

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

@@ -0,0 +1,77 @@
+import type { RuntimeRepairRecord, RuntimeRepairType } from '../storage/runtime-store.js';
+import { runtimeScopedId } from '../storage/runtime-store.js';
+
+export interface RepairClassificationInput {
+  branchSlug: string;
+  taskId?: string | null;
+  runId?: string | null;
+  gateDecisionId?: string | null;
+  message: string;
+  recommendedCommands?: string[];
+  requiredEvidence?: string[];
+}
+
+export function classifyRepairType(message: string): RuntimeRepairType {
+  const normalized = message.toLowerCase();
+  if (normalized.includes('mixed-version') || normalized.includes('legacy') || normalized.includes('0.4.x')) {
+    return 'migration_repair';
+  }
+  if (normalized.includes('contract') || normalized.includes('stale') || normalized.includes('spec') || normalized.includes('plan') || normalized.includes('verify.md') || normalized.includes('tasks.md')) {
+    return 'contract_repair';
+  }
+  if (normalized.includes('validation command') || normalized.includes('not directly executable') || normalized.includes('manual:')) {
+    return 'validation_command_repair';
+  }
+  if (normalized.includes('artifact') || normalized.includes('digest') || normalized.includes('evidence')) {
+    return 'artifact_repair';
+  }
+  if (normalized.includes('env') || normalized.includes('node:sqlite') || normalized.includes('maven') || normalized.includes('jdk') || normalized.includes('external service')) {
+    return 'environment_repair';
+  }
+  if (normalized.includes('gate') || normalized.includes('policy') || normalized.includes('human')) {
+    return 'gate_policy_repair';
+  }
+  return 'implementation_repair';
+}
+
+export function buildOpenRepairRecord(input: RepairClassificationInput): RuntimeRepairRecord {
+  const repairType = classifyRepairType(input.message);
+  const taskId = input.taskId ?? null;
+  const runId = input.runId ?? null;
+  return {
+    repairId: runtimeScopedId('repair', input.branchSlug, taskId ?? 'workflow', runId ?? 'none', repairType, input.message),
+    branchSlug: input.branchSlug,
+    taskId,
+    repairType,
+    repairOfRunId: runId,
+    repairOfGateDecisionId: input.gateDecisionId ?? null,
+    status: 'open',
+    affectedTasks: taskId ? [taskId] : [],
+    blockers: [input.message],
+    recommendedCommands: input.recommendedCommands ?? defaultRepairCommands(input.branchSlug, taskId, repairType),
+    requiredEvidence: input.requiredEvidence ?? defaultRequiredEvidence(repairType),
+    createdAt: new Date().toISOString(),
+    resolvedAt: null,
+    payload: { source: 'repair_classifier' }
+  };
+}
+
+function defaultRepairCommands(branchSlug: string, taskId: string | null, repairType: RuntimeRepairType): string[] {
+  if (repairType === 'contract_repair' || repairType === 'migration_repair' || repairType === 'validation_command_repair') {
+    return [`sdd doctor --branch ${branchSlug} --latest-only`];
+  }
+  if (taskId) {
+    return [`sdd test task-${taskId} --branch ${branchSlug}`];
+  }
+  return [`sdd status --branch ${branchSlug}`];
+}
+
+function defaultRequiredEvidence(repairType: RuntimeRepairType): string[] {
+  if (repairType === 'contract_repair' || repairType === 'migration_repair' || repairType === 'validation_command_repair') {
+    return ['current document contract and executable validation evidence'];
+  }
+  if (repairType === 'gate_policy_repair') {
+    return ['accepted workflow gate PASS decision'];
+  }
+  return ['new accepted validation evidence'];
+}