sdd-agent-platform 0.4.1 → 0.4.2

package/node_modules/@sdd-agent-platform/core/src/workflow-gate/policy.ts

@@ -27,11 +27,12 @@ export function synthesizeWorkflowGateDecision(packet: WorkflowGateEvidencePacke
     forbiddenNextActions,
     humanRequired,
     reasons: decisionReasons(status, hardBlocks, warnings, advisorSummary),
-    evidenceRefs: sortedUnique([...packet.canonicalEvidenceRefs, ...packet.fanInEvidenceSets.flatMap((set) => [...set.evidenceRefs, ...set.canonicalEvidenceRefs])]),
+    evidenceRefs: sortedUnique(selectedEvidenceRefs(packet)),
     payload: {
       contract: WORKFLOW_GATE_RUNTIME_CONTRACT_VERSION,
       packetId: packet.packetId,
-      workflowScope: packet.workflowScope
+      workflowScope: packet.workflowScope,
+      evidenceBinding: gateEvidenceBinding(packet)
     }
   };
 }
@@ -65,10 +66,14 @@ export function inputHash(packet: WorkflowGateEvidencePacket): string {
     durableGaps: packet.durableGaps,
     dependencyBlockers: packet.dependencyBlockers,
     affectedFileConflicts: packet.affectedFileConflicts,
-    syncBackDecision: packet.syncBackDecision,
-    syncBackDecisions: packet.syncBackDecisions,
     fanInEvidenceSets: packet.fanInEvidenceSets,
     advisorAssessments: packet.advisorAssessments,
+    selectedEvidence: {
+      source: packet.selectedEvidence.source,
+      evidenceSetId: packet.selectedEvidence.evidenceSet?.evidenceSetId ?? null,
+      selectedEvidenceSetId: packet.selectedEvidence.pointer?.selectedEvidenceSetId ?? null,
+      payloads: packet.selectedEvidence.payloads.map((payload) => ({ payloadId: payload.payloadId, logicalRef: payload.logicalRef, digest: payload.digest, status: payload.status }))
+    },
     canonicalEvidenceRefs: packet.canonicalEvidenceRefs,
     requiredArtifactRefs: packet.requiredArtifactRefs,
     artifactPayloadHealth: packet.artifactPayloadHealth,
@@ -113,7 +118,7 @@ function allowedActions(status: WorkflowGateStatus, packet: WorkflowGateEvidence
 
 function forbiddenActions(status: WorkflowGateStatus, packet: WorkflowGateEvidencePacket): string[] {
   if (status === 'BLOCKED') {
-    return ['ship', 'sync-back-apply', 'mark-task-complete', 'stage-pass'];
+    return ['ship', 'truth-alignment-approval', 'mark-task-complete', 'stage-pass'];
   }
   if (status === 'HUMAN_REQUIRED') {
     return ['satisfy-with-role-result', 'satisfy-with-subagent-output'];
@@ -121,7 +126,7 @@ function forbiddenActions(status: WorkflowGateStatus, packet: WorkflowGateEviden
   if (status === 'ADVISORY_ONLY') {
     return ['treat-advisor-as-pass'];
   }
-  return status === 'WARN' ? ['ship', 'sync-back-apply', 'mark-task-complete', 'stage-pass'] : packet.decisionKind === 'ship' ? [] : ['skip-evidence-recording'];
+  return status === 'WARN' ? ['ship', 'truth-alignment-approval', 'mark-task-complete', 'stage-pass'] : packet.decisionKind === 'ship' ? [] : ['skip-evidence-recording'];
 }
 
 function decisionReasons(status: WorkflowGateStatus, hardBlocks: WorkflowGateHardCheck[], warnings: WorkflowGateHardCheck[], advisorSummary: WorkflowGateAdvisorSummary): string[] {
@@ -140,6 +145,40 @@ function decisionReasons(status: WorkflowGateStatus, hardBlocks: WorkflowGateHar
   return [`runtime_policy produced ${status}`];
 }
 
+function selectedEvidenceRefs(packet: WorkflowGateEvidencePacket): string[] {
+  return packet.selectedEvidence.payloads.map((payload) => payload.logicalRef);
+}
+
+function gateEvidenceBinding(packet: WorkflowGateEvidencePacket): Record<string, unknown> {
+  const selectedRefs = packet.selectedEvidence.payloads.map((payload) => ({
+    payloadId: payload.payloadId,
+    logicalRef: payload.logicalRef,
+    digest: payload.digest,
+    status: payload.status
+  }));
+  return {
+    contract: 'sdd-gate-evidence-binding-v1',
+    branch: packet.partition,
+    gate: packet.decisionKind,
+    selectionPointerRef: packet.selectedEvidence.pointer ? `selection:${packet.selectedEvidence.pointer.scopeKind}:${packet.selectedEvidence.pointer.scopeId}` : null,
+    acceptedEvidenceSetRef: packet.selectedEvidence.evidenceSet?.evidenceSetId ?? null,
+    source: packet.selectedEvidence.source,
+    selectedRefs,
+    blockedRefs: packet.hardChecks.flatMap((check) => check.refs),
+    selectionReasons: sortedUnique([packet.selectedEvidence.pointer?.reason ?? '', ...evidenceSetSelectionReasons(packet.selectedEvidence.evidenceSet?.payload)]),
+    decision: packet.hardChecks.some((check) => check.severity === 'blocked') ? 'blocked' : 'pass',
+    reasons: packet.hardChecks.map((check) => `${check.code}: ${check.message}`)
+  };
+}
+
+function evidenceSetSelectionReasons(payload: unknown): string[] {
+  if (!payload || typeof payload !== 'object') {
+    return [];
+  }
+  const reasons = (payload as { selectionReasons?: unknown }).selectionReasons;
+  return Array.isArray(reasons) ? reasons.filter((reason): reason is string => typeof reason === 'string') : [];
+}
+
 function sortedUnique(values: string[]): string[] {
   return [...new Set(values.filter(Boolean))].sort();
 }

package/node_modules/@sdd-agent-platform/core/src/workflow-gate/types.ts

@@ -1,5 +1,5 @@
 import type { FanInEvidenceSetRecord, LlmAdvisorAssessmentRecord } from '../execution/stage-team-runtime.js';
-import type { RuntimeDurableGapRecord, RuntimeSyncBackDecisionRecord } from '../storage/runtime-store.js';
+import type { RuntimeDurableGapRecord, RuntimeResolvedEvidenceSelection } from '../storage/runtime-store.js';
 import type { LatestEligibleRunSelection } from '../workflow-state/latest-eligible-run.js';
 import type { WorkflowDependencyBlocker } from '../workflow-state/dependencies.js';
 import type { WorkflowAffectedFileConflict } from '../workflow-state/affected-file-conflicts.js';
@@ -8,7 +8,7 @@ import type { SddTaskModel } from '../sdd-docs/task-parser.js';
 export type WorkflowGateStatus = 'PASS' | 'WARN' | 'BLOCKED' | 'HUMAN_REQUIRED' | 'ADVISORY_ONLY';
 export type WorkflowGateHardCheckSeverity = 'info' | 'warning' | 'blocked';
 export type WorkflowGateAdvisorSummaryStatus = 'none' | 'low_concern' | 'medium_concern' | 'high_concern' | 'invalid';
-export type WorkflowGateDecisionKind = 'test' | 'validation_wave' | 'review_gate' | 'sync_back' | 'ship' | 'stage_transition';
+export type WorkflowGateDecisionKind = 'test' | 'validation_wave' | 'review_gate' | 'ship' | 'stage_transition';
 
 export type WorkflowGateHardCheckCode =
   | 'schema_health_unavailable'
@@ -21,10 +21,12 @@ export type WorkflowGateHardCheckCode =
   | 'missing_payload'
   | 'digest_drift'
   | 'missing_required_artifact'
+  | 'missing_evidence_selection'
+  | 'non_consumable_evidence'
+  | 'non_primary_evidence'
   | 'validation_failure'
   | 'dependency_blocker'
   | 'authority_violation'
-  | 'sync_back_divergence'
   | 'affected_file_conflict'
   | 'durable_gap_blocking';
 
@@ -73,10 +75,9 @@ export interface WorkflowGateEvidencePacket {
   durableGaps: RuntimeDurableGapRecord[];
   dependencyBlockers: WorkflowDependencyBlocker[];
   affectedFileConflicts: WorkflowAffectedFileConflict[];
-  syncBackDecision: RuntimeSyncBackDecisionRecord | null;
-  syncBackDecisions: RuntimeSyncBackDecisionRecord[];
   fanInEvidenceSets: FanInEvidenceSetRecord[];
   advisorAssessments: LlmAdvisorAssessmentRecord[];
+  selectedEvidence: RuntimeResolvedEvidenceSelection;
   canonicalEvidenceRefs: string[];
   requiredArtifactRefs: string[];
   artifactPayloadHealth: WorkflowGateArtifactPayloadHealth[];

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
         });
       }
@@ -71,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')
   );
 }
 

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

@@ -93,7 +93,7 @@ function dependencyReadinessEntry(taskId: string, dependencyId: string, dependen
     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} 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}.`
   };
 }

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

@@ -10,7 +10,6 @@ export interface LatestEligibleRunCandidate {
   runId: string;
   runStatus: RunState['status'];
   validationStatus: RunState['validation']['status'];
-  syncBackStatus: RunState['syncBack']['status'];
   affectedFiles: string[];
   updatedAt: string;
   compatibility: DocumentCompatibilityClass;
@@ -54,7 +53,7 @@ export function selectLatestEligibleRunsByTask(input: { states: RunState[]; mode
 
 function latestEligibleCandidate(state: RunState, model: SddTaskModel): LatestEligibleRunCandidate {
   const compatibility = classifyDocumentCompatibility(state, model);
-  const reasons = candidateRejectionReasons(state, compatibility);
+  const reasons = candidateRejectionReasons(state, model, compatibility);
   return {
     partition: state.partition ?? model.branch,
     gitBranch: state.gitBranch,
@@ -62,7 +61,6 @@ function latestEligibleCandidate(state: RunState, model: SddTaskModel): LatestEl
     runId: state.runId,
     runStatus: state.status,
     validationStatus: state.validation.status,
-    syncBackStatus: state.syncBack.status,
     affectedFiles: state.affectedFiles,
     updatedAt: state.updatedAt,
     compatibility,
@@ -83,14 +81,21 @@ export function classifyDocumentCompatibility(state: RunState, model: SddTaskMod
   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)
+    ? 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.tasksStale) {
+  if (model.documents.planStale || model.documents.verifyStale) {
+    return 'strict_stale';
+  }
+  if (taskContractMismatch) {
     return 'strict_stale';
   }
   if (tasksSemanticMismatch) {
@@ -102,7 +107,7 @@ export function classifyDocumentCompatibility(state: RunState, model: SddTaskMod
   return 'compatible';
 }
 
-function candidateRejectionReasons(state: RunState, compatibility: DocumentCompatibilityClass): string[] {
+function candidateRejectionReasons(state: RunState, model: SddTaskModel, compatibility: DocumentCompatibilityClass): string[] {
   const reasons: string[] = [];
   if (state.status === 'archived') {
     reasons.push('Run is archived.');
@@ -117,7 +122,7 @@ function candidateRejectionReasons(state: RunState, compatibility: DocumentCompa
     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.');
@@ -125,6 +130,69 @@ function candidateRejectionReasons(state: RunState, compatibility: DocumentCompa
   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;

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'];
+}

package/node_modules/@sdd-agent-platform/core/src/workflow-state/resolve-task-run.ts

@@ -0,0 +1,114 @@
+import type { RunState } from '../run-state/model.js';
+import { readAllRunStates, readRunState } from '../run-state/run-state.js';
+import type { ContextResolverContract } from '../sdd-docs/context.js';
+import { resolveRunStateContext, resolveSddContext } from '../sdd-docs/context.js';
+import { documentHashMatches } from '../sdd-docs/document-hashes.js';
+import { inspectSddTask } from '../sdd-docs/task-inspection.js';
+import { parseSddBranch, type SddTask, type SddTaskModel } from '../sdd-docs/task-parser.js';
+import { affectedFileConflictsForSelectedRun, type WorkflowAffectedFileConflict } from './affected-file-conflicts.js';
+import { resolveWorkflowState } from './resolve.js';
+
+export interface ResolvedTaskRun {
+  runId: string;
+  state: RunState;
+  context: ContextResolverContract;
+  model: SddTaskModel;
+  task: SddTask | null;
+  explicitRunId: boolean;
+  staleReasons: string[];
+  affectedFileConflicts: WorkflowAffectedFileConflict[];
+  selectorRejectionReasons: string[];
+}
+
+export async function resolveTaskRun(projectRoot: string, options: { runId?: string; branch?: string; taskId: string }): Promise<ResolvedTaskRun> {
+  if (options.runId) {
+    const state = await readRunState(projectRoot, options.runId);
+    const context = options.branch
+      ? await resolveSddContext(projectRoot, { branch: options.branch, branchSource: 'cli_option' })
+      : await resolveRunStateContext(projectRoot, state);
+    const model = await parseSddBranch(projectRoot, context.partition);
+    const inspected = inspectSddTask(model, options.taskId);
+    if (state.partition && state.partition !== context.partition) {
+      throw new Error(`Run ${state.runId} belongs to partition ${state.partition}, not ${context.partition}.`);
+    }
+    if (state.taskId && state.taskId !== options.taskId) {
+      throw new Error(`Run ${state.runId} belongs to task ${state.taskId}, not ${options.taskId}.`);
+    }
+    return {
+      runId: state.runId,
+      state,
+      context,
+      model,
+      task: inspected.task,
+      explicitRunId: true,
+      staleReasons: runDocumentStaleReasons(state, model),
+      affectedFileConflicts: await affectedFileConflictsForRun(projectRoot, state),
+      selectorRejectionReasons: []
+    };
+  }
+
+  const workflow = await resolveWorkflowState(projectRoot, {
+    branch: options.branch,
+    branchSource: options.branch ? 'cli_option' : undefined,
+    taskId: options.taskId
+  });
+  const inspected = inspectSddTask(workflow.model, options.taskId);
+  const selection = workflow.latestEligibleRunsByTask.find((entry) => entry.taskId === options.taskId);
+  const candidate = selection?.selected ?? selection?.rejected[0] ?? null;
+  if (!candidate) {
+    throw new Error(`No eligible run found for ${workflow.context.partition}/${options.taskId}. Run sdd do task ${options.taskId} first, or pass --run <run_id>.`);
+  }
+  const state = selection?.selected && workflow.latestRunState && selection.selected.runId === workflow.latestRunState.runId
+    ? workflow.latestRunState
+    : await readRunState(projectRoot, candidate.runId);
+  if (!state) {
+    throw new Error(`Run state ${candidate.runId} is unavailable for ${workflow.context.partition}/${options.taskId}. Pass --run <run_id> or rerun the task.`);
+  }
+  return {
+    runId: state.runId,
+    state,
+    context: workflow.context,
+    model: workflow.model,
+    task: inspected.task,
+    explicitRunId: false,
+    staleReasons: runDocumentStaleReasons(state, workflow.model),
+    affectedFileConflicts: workflow.affectedFileConflicts,
+    selectorRejectionReasons: selection?.selected ? [] : candidate.reasons
+  };
+}
+
+export function runDocumentStaleReasons(state: RunState, model: SddTaskModel): string[] {
+  const reasons: string[] = [];
+  const snapshot = state.documentSnapshot;
+  if (!snapshot.specHash && !snapshot.planHash && !snapshot.tasksHash) {
+    reasons.push('Run has no document snapshot hashes; rerun do task before test or goal-verify.');
+  }
+  appendDocumentHashMismatch(reasons, 'spec.md', snapshot.specHash, model.documents.specHash ?? null);
+  appendDocumentHashMismatch(reasons, 'plan.md', snapshot.planHash, model.documents.planHash ?? null);
+  appendDocumentHashMismatch(reasons, 'tasks.md', snapshot.tasksHash, model.documents.tasksHash ?? null);
+  if (model.documents.planStale) {
+    reasons.push('Current plan.md is stale against spec.md.');
+  }
+  if (model.documents.tasksStale) {
+    reasons.push('Current tasks.md is stale against plan.md or spec.md.');
+  }
+  return reasons;
+}
+
+async function affectedFileConflictsForRun(projectRoot: string, state: RunState): Promise<WorkflowAffectedFileConflict[]> {
+  const states = await readAllRunStates(projectRoot);
+  return affectedFileConflictsForSelectedRun(states, state);
+}
+
+function appendDocumentHashMismatch(reasons: string[], documentName: string, expected: string | null, actual: string | null): void {
+  if (shouldReportDocumentHashMismatch(expected, actual)) {
+    reasons.push(`Run snapshot for ${documentName} is ${expected ?? 'missing'}, current hash is ${actual ?? 'missing'}.`);
+  }
+}
+
+function shouldReportDocumentHashMismatch(expected: string | null, actual: string | null): boolean {
+  if (!expected && !actual) {
+    return false;
+  }
+  return !expected || !actual || !documentHashMatches(expected, actual);
+}