sdd-agent-platform 0.4.0 → 0.4.2

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

@@ -1,15 +1,24 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtemp, rm } from 'node:fs/promises';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
 
 import { initProject } from '../config/init-project.js';
 import { createRun, readRunState, writeRunState } from '../run-state/run-state.js';
-import { validTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
-import { bindTestRunState, markTestRunReadyForSyncBack } from '../test-support/run-state.js';
+import { hashTestDocument, validTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
+import { bindTestRunState, markTestRunReadyForShip } from '../test-support/run-state.js';
 import { createDelegationRecord } from '../delegation/validation.js';
+import { recordRuntimeProjectionEnvelope, recordRuntimeRepair } from '../storage/runtime-store.js';
+import { buildOpenRepairRecord } from './repair-contract.js';
+import { recordTruthAlignmentProjection, SPEC_COLLABORATION_ADJUDICATION_PROJECTION_TYPE, specCollaborationScopeKey, TEST_COLLABORATION_ADJUDICATION_PROJECTION_TYPE, testCollaborationScopeKey, type TruthAlignmentProjection } from '../stage-collaboration.js';
+import { readTruthReconciliationProjection } from '../truth-reconciliation.js';
 import { resolveWorkflowState } from './resolve.js';
+import { readNextIntentProjection, readTaskOrchestrationProjection, readValidationUnitProjection, readWorkflowCurrentStateProjection } from './runtime-projections.js';
+
+const execFileAsync = promisify(execFile);
 
 test('workflow state resolver projects branch docs latest run and next action', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-'));
@@ -18,7 +27,7 @@ test('workflow state resolver projects branch docs latest run and next action',
     await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
     const run = await createRun(root, { runId: 'run-1' });
     await bindTestRunState(root, run.runId, 'feature', 'T1');
-    await markTestRunReadyForSyncBack(root, run.runId, 'T1');
+    await markTestRunReadyForShip(root, run.runId, 'T1');
 
     const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'T1' });
 
@@ -27,7 +36,480 @@ test('workflow state resolver projects branch docs latest run and next action',
     assert.equal(workflow.latestRun?.runId, 'run-1');
     assert.deepEqual(workflow.latestRunsByTask.map((entry) => `${entry.partition}:${entry.taskId}:${entry.runId}`), ['feature:T1:run-1']);
     assert.equal(workflow.taskCounts.total, 1);
-    assert.equal(workflow.recommendedNextCommand, 'sdd sync-back inspect --branch feature --task T1');
+    assert.equal(workflow.recommendedNextCommand, 'sdd ship close --branch feature --compact-json');
+    assert.equal(workflow.nextIntent.bundle, 'ship');
+    assert.equal(workflow.nextIntent.targetRuntimeStage, 'ship');
+    assert.equal(workflow.nextIntent.hostProjections.find((projection) => projection.host === 'claude_code')?.entry, '/sdd:ship close --branch feature --compact-json');
+    const currentStateProjection = await readWorkflowCurrentStateProjection(root, 'feature');
+    const nextIntentProjection = await readNextIntentProjection(root, 'feature');
+    const taskOrchestrationProjection = await readTaskOrchestrationProjection(root, 'feature');
+    const validationUnitProjection = await readValidationUnitProjection(root, 'feature');
+
+    assert.equal(currentStateProjection?.payload.contract, 'sdd-workflow-current-state-projection-v1');
+    assert.equal(currentStateProjection?.payload.lifecycle.currentStage, 'ship');
+    assert.equal(currentStateProjection?.payload.lifecycle.writer, 'runtime_sqlite');
+    assert.equal(currentStateProjection?.payload.tasks[0]?.taskId, 'T1');
+    assert.equal(currentStateProjection?.payload.tasks[0]?.consumability, 'consumable');
+    assert.equal(currentStateProjection?.payload.validationUnits[0]?.validationUnitId, 'T1');
+    assert.equal(taskOrchestrationProjection?.payload.contract, 'sdd-task-orchestration-projection-v1');
+    assert.equal(taskOrchestrationProjection?.payload.tasks[0]?.taskId, 'T1');
+    assert.equal(taskOrchestrationProjection?.payload.tasks[0]?.sourceRef.ref, 'specs/feature/tasks.md#T1');
+    assert.equal(validationUnitProjection?.payload.contract, 'sdd-validation-unit-projection-v1');
+    assert.deepEqual(validationUnitProjection?.payload.validationUnits[0]?.taskIds, ['T1']);
+    assert.equal(nextIntentProjection?.payload.contract, 'sdd-next-intent-projection-v1');
+    assert.equal(nextIntentProjection?.payload.advisory, true);
+    assert.equal(nextIntentProjection?.payload.rules.recommendationIsNotAGate, true);
+    assert.equal(nextIntentProjection?.payload.primary.canonicalCommand, workflow.nextIntent.canonicalCommand);
+    assert.equal(nextIntentProjection?.payload.primary.targetRuntimeStage, 'ship');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('workflow state routes validation PASS to goal-verify before ship readiness', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-test-pass-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const run = await createRun(root, { runId: 'run-pass-no-syncback' });
+    await bindTestRunState(root, run.runId, 'feature', 'T1');
+    const bound = await readRunState(root, run.runId);
+    await writeRunState(root, {
+      ...bound,
+      status: 'completed',
+      validation: {
+        status: 'pass',
+        commands: ['npm test'],
+        evidence: ['artifacts/validation-T1.md']
+      }
+    });
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'T1' });
+
+    assert.equal(workflow.nextIntent.stage, 'test');
+    assert.equal(workflow.nextIntent.bundle, 'test');
+    assert.equal(workflow.nextIntent.targetRuntimeStage, 'goal-verify');
+    assert.equal(workflow.nextIntent.intent, 'run_goal_verify');
+    assert.equal(workflow.recommendedNextCommand, 'sdd test close --branch feature --target goal-verify --compact-json');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('workflow state routes non-aligned truthAlignment to owner stage-manager reconciliation', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-truth-reconcile-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    await recordTruthAlignmentProjection(root, truthAlignmentProjection({
+      branch: 'feature',
+      status: 'drift_detected',
+      ownerStage: 'do',
+      semanticImpact: 'material',
+      invalidatesStages: ['do'],
+      staleRefs: [{ kind: 'artifact', ref: '.sdd/runs/feature/do/implementation-v1.md', hash: 'old-implementation-hash' }],
+      reasons: ['accepted implementation evidence no longer matches declared truth']
+    }));
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'T1' });
+    const projection = await readTruthReconciliationProjection(root, 'feature');
+
+    assert.equal(workflow.nextIntent.intent, 'reconcile_truth');
+    assert.equal(workflow.nextIntent.bundle, 'do');
+    assert.equal(workflow.nextIntent.targetRuntimeStage, 'do');
+    assert.equal(workflow.recommendedNextCommand, 'sdd do task <task_id> --branch feature');
+    assert.equal(workflow.truthReconciliation?.changeKind, 'implementation_mismatch');
+    assert.deepEqual(workflow.truthReconciliation?.minimalFrontier, ['do', 'test', 'goal-verify', 'ship']);
+    assert.equal(workflow.truthReconciliation?.preservesEvidenceRefs.length, 0);
+    assert.equal(workflow.truthReconciliation?.supersedesEvidenceRefs.length, 2);
+    assert.equal(projection?.payload.nextIntent.canonicalCommand, workflow.nextIntent.canonicalCommand);
+    assert.equal(workflow.nextIntent.hostProjections.find((host) => host.host === 'claude_code')?.entry, '/sdd:do task <task_id> --branch feature');
+    assert.equal(workflow.nextIntent.canonicalCommand.includes('sync-back'), false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('workflow state advances material truth reconciliation frontier after do correction evidence', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-truth-frontier-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    await recordTruthAlignmentProjection(root, truthAlignmentProjection({
+      branch: 'feature',
+      status: 'drift_detected',
+      ownerStage: 'do',
+      semanticImpact: 'material',
+      invalidatesStages: ['do'],
+      staleRefs: [{ kind: 'artifact', ref: '.sdd/runs/feature/do/implementation-v1.md', hash: 'old-implementation-hash' }],
+      reasons: ['accepted implementation evidence no longer matches declared truth'],
+      createdAt: '2020-01-01T00:00:00.000Z'
+    }));
+    const run = await createRun(root, { runId: 'run-post-truth-do', branch: 'feature', taskId: 'T1' });
+    await writeRunState(root, {
+      ...run,
+      status: 'completed',
+      createdAt: '2026-06-01T00:00:01.000Z',
+      updatedAt: '2026-06-01T00:00:01.000Z',
+      tasks: {
+        T1: {
+          status: 'implemented_pending_validation',
+          implementationStatus: 'implemented',
+          verificationStatus: 'not_run',
+          validationBatch: null,
+          validationTiming: 'task_end',
+          requiresVerifyBeforeNext: true,
+          gaps: [],
+          artifacts: ['.sdd/runs/feature/do/implementation-v2.md']
+        }
+      }
+    });
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'T1' });
+
+    assert.equal(workflow.truthReconciliation?.ownerStage, 'do');
+    assert.deepEqual(workflow.truthReconciliation?.minimalFrontier, ['do', 'test', 'goal-verify', 'ship']);
+    assert.equal(workflow.nextIntent.intent, 'reconcile_truth');
+    assert.equal(workflow.nextIntent.bundle, 'test');
+    assert.equal(workflow.nextIntent.targetRuntimeStage, 'test');
+    assert.equal(workflow.recommendedNextCommand, 'sdd test close --branch feature --compact-json');
+    assert.equal(workflow.nextIntent.canonicalCommand.includes('sync-back'), false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('workflow state advances material truth reconciliation frontier after test stage close', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-truth-test-frontier-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    await recordTruthAlignmentProjection(root, truthAlignmentProjection({
+      branch: 'feature',
+      status: 'drift_detected',
+      ownerStage: 'do',
+      semanticImpact: 'material',
+      invalidatesStages: ['do'],
+      staleRefs: [{ kind: 'artifact', ref: '.sdd/runs/feature/do/implementation-v1.md', hash: 'old-implementation-hash' }],
+      reasons: ['accepted implementation evidence no longer matches declared truth'],
+      createdAt: '2020-01-01T00:00:00.000Z'
+    }));
+    const doRun = await createRun(root, { runId: 'run-post-truth-do', branch: 'feature', taskId: 'T1' });
+    await writeRunState(root, {
+      ...doRun,
+      status: 'completed',
+      tasks: {
+        T1: {
+          status: 'implemented_pending_validation',
+          implementationStatus: 'implemented',
+          verificationStatus: 'not_run',
+          validationBatch: null,
+          validationTiming: 'task_end',
+          requiresVerifyBeforeNext: true,
+          gaps: [],
+          artifacts: ['.sdd/runs/feature/do/implementation-v2.md']
+        }
+      }
+    });
+    const acceptedTestRef = { kind: 'artifact' as const, ref: '.sdd/runs/feature/test/validation-v2.md', hash: 'validation-v2-hash' };
+    const generatedAt = '2026-06-01T00:00:02.000Z';
+    await recordRuntimeProjectionEnvelope(root, {
+      projectionType: TEST_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+      scopeKey: testCollaborationScopeKey({ branch: 'feature' }),
+      inputHash: 'test-adjudication-v2',
+      producer: 'phase9.6-test-stage-collaboration-runtime',
+      producerVersion: 'phase9.6-test-stage-collaboration-runtime-v1',
+      generatedAt,
+      payload: {
+        contract: 'phase-9.1-stage-collaboration-runtime-v1',
+        adjudicationId: 'test-adjudication-v2',
+        stage: 'test',
+        scope: { branch: 'feature' },
+        health: 'ready_for_goal_verify',
+        stageDecision: {
+          contract: 'phase-9.1-stage-collaboration-runtime-v1',
+          decisionId: 'test-stage-decision-v2',
+          stage: 'test',
+          scope: { branch: 'feature' },
+          status: 'completed',
+          health: 'ready_for_goal_verify',
+          acceptedDecisionRefs: [acceptedTestRef],
+          advisoryRefs: [],
+          capabilityRefs: [],
+          blockingReasons: [],
+          createdAt: generatedAt
+        },
+        handoffPacket: null,
+        rejection: null,
+        nextActions: [],
+        closureRefs: {
+          runRef: { kind: 'run', ref: 'run-post-truth-test' },
+          acceptedTestEvidenceRef: acceptedTestRef,
+          testAcceptanceStatus: 'accepted',
+          testEvidenceHash: 'validation-v2-hash',
+          acceptedDoHandoffRef: null,
+          artifactRefs: [acceptedTestRef],
+          collaborationContractRef: null,
+          lifecycleRiskProjectionRef: { kind: 'projection', ref: 'phase8_lifecycle_risk_decision:feature:all:none:none' },
+          adjudicationProjectionRef: { kind: 'projection', ref: `${TEST_COLLABORATION_ADJUDICATION_PROJECTION_TYPE}:${testCollaborationScopeKey({ branch: 'feature' })}` },
+          stageRunProjectionRef: { kind: 'projection', ref: 'phase8_stage_run:feature:all:run-post-truth-test:none:test' },
+          reasons: []
+        },
+        createdAt: generatedAt
+      }
+    });
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'T1' });
+
+    assert.equal(workflow.nextIntent.intent, 'reconcile_truth');
+    assert.equal(workflow.nextIntent.bundle, 'test');
+    assert.equal(workflow.nextIntent.targetRuntimeStage, 'goal-verify');
+    assert.equal(workflow.recommendedNextCommand, 'sdd test close --branch feature --target goal-verify --compact-json');
+    assert.equal(workflow.nextIntent.canonicalCommand.includes('sync-back'), false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('workflow state maps intra-bundle truth reconciliation to task and test command bundles', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-truth-bundles-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    await recordTruthAlignmentProjection(root, truthAlignmentProjection({
+      branch: 'feature',
+      status: 'update_required',
+      ownerStage: 'verifies',
+      semanticImpact: 'none',
+      invalidatesStages: ['verifies'],
+      staleRefs: [{ kind: 'document', ref: 'specs/feature/verify.md', hash: 'old-verify-hash' }],
+      reasons: ['verify contract needs documentation catch-up']
+    }));
+
+    const verifiesWorkflow = await resolveWorkflowState(root, { branch: 'feature' });
+
+    assert.equal(verifiesWorkflow.nextIntent.bundle, 'tasks');
+    assert.equal(verifiesWorkflow.nextIntent.targetRuntimeStage, 'verifies');
+    assert.equal(verifiesWorkflow.nextIntent.displayCommand, '/sdd:tasks target=verifies close --branch feature --compact-json');
+    assert.equal(verifiesWorkflow.nextIntent.canonicalCommand, 'sdd tasks close --branch feature --target verifies --compact-json');
+
+    await recordTruthAlignmentProjection(root, truthAlignmentProjection({
+      branch: 'feature',
+      status: 'drift_detected',
+      ownerStage: 'goal-verify',
+      semanticImpact: 'bounded',
+      invalidatesStages: ['goal-verify'],
+      staleRefs: [{ kind: 'projection', ref: 'phase9_12_truth_alignment:feature', hash: 'old-gate-hash' }],
+      reasons: ['goal verification gate policy changed']
+    }));
+
+    const goalVerifyWorkflow = await resolveWorkflowState(root, { branch: 'feature' });
+
+    assert.equal(goalVerifyWorkflow.nextIntent.bundle, 'test');
+    assert.equal(goalVerifyWorkflow.nextIntent.targetRuntimeStage, 'goal-verify');
+    assert.equal(goalVerifyWorkflow.nextIntent.displayCommand, '/sdd:test target=goal-verify close --branch feature --compact-json');
+    assert.equal(goalVerifyWorkflow.nextIntent.canonicalCommand, 'sdd test close --branch feature --target goal-verify --compact-json');
+    assert.equal(goalVerifyWorkflow.nextIntent.canonicalCommand.includes('sync-back'), false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('workflow state routes stale aligned truthAlignment refs to minimal document reconciliation', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-stale-truth-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const specPath = path.join(root, 'specs', 'feature', 'spec.md');
+    const tasksPath = path.join(root, 'specs', 'feature', 'tasks.md');
+    const specHash = hashTestDocument(await readFile(specPath, 'utf8'));
+    const tasksHash = hashTestDocument(await readFile(tasksPath, 'utf8'));
+    await recordTruthAlignmentProjection(root, {
+      contract: 'sdd-truth-alignment-v1',
+      branch: 'feature',
+      sourceStage: 'goal-verify',
+      declaredTruthRefs: [
+        { kind: 'document', ref: 'specs/feature/spec.md', hash: specHash },
+        { kind: 'document', ref: 'specs/feature/tasks.md', hash: tasksHash }
+      ],
+      acceptedRealityRefs: [{ kind: 'artifact', ref: '.sdd/runs/feature/goal-verify/goal-verification-v1.md' }],
+      status: 'aligned',
+      ownerStage: null,
+      semanticImpact: 'none',
+      staleRefs: [],
+      invalidatesStages: [],
+      reasons: ['Accepted goal verification is structurally aligned with declared upstream truth refs.'],
+      createdAt: '2026-06-01T00:00:00.000Z'
+    });
+    await writeFile(tasksPath, `${await readFile(tasksPath, 'utf8')}\nAdditional documentation-only acceptance clarification.\n`, 'utf8');
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature' });
+
+    assert.equal(workflow.nextIntent.intent, 'reconcile_truth');
+    assert.equal(workflow.nextIntent.bundle, 'tasks');
+    assert.equal(workflow.nextIntent.targetRuntimeStage, 'tasks');
+    assert.equal(workflow.recommendedNextCommand, 'sdd tasks close --branch feature --compact-json');
+    assert.equal(workflow.truthReconciliation?.changeKind, 'documentation_catchup');
+    assert.equal(workflow.truthReconciliation?.semanticImpact, 'none');
+    assert.deepEqual(workflow.truthReconciliation?.minimalFrontier, ['tasks']);
+    assert.equal(workflow.truthReconciliation?.changedRef.ref, 'specs/feature/tasks.md');
+    assert.equal(workflow.truthReconciliation?.oldHash, tasksHash);
+    assert.notEqual(workflow.truthReconciliation?.newHash, tasksHash);
+    assert.equal(workflow.nextIntent.canonicalCommand.includes('sync-back'), false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('workflow state skips document truth refs already accepted by stage close', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-stale-truth-close-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const specPath = path.join(root, 'specs', 'feature', 'spec.md');
+    const tasksPath = path.join(root, 'specs', 'feature', 'tasks.md');
+    const originalSpecHash = hashTestDocument(await readFile(specPath, 'utf8'));
+    const originalTasksHash = hashTestDocument(await readFile(tasksPath, 'utf8'));
+    await recordTruthAlignmentProjection(root, {
+      contract: 'sdd-truth-alignment-v1',
+      branch: 'feature',
+      sourceStage: 'goal-verify',
+      declaredTruthRefs: [
+        { kind: 'document', ref: 'specs/feature/spec.md', hash: originalSpecHash },
+        { kind: 'document', ref: 'specs/feature/tasks.md', hash: originalTasksHash }
+      ],
+      acceptedRealityRefs: [{ kind: 'artifact', ref: '.sdd/runs/feature/goal-verify/goal-verification-v1.md' }],
+      status: 'aligned',
+      ownerStage: null,
+      semanticImpact: 'none',
+      staleRefs: [],
+      invalidatesStages: [],
+      reasons: ['Accepted goal verification is structurally aligned with declared upstream truth refs.'],
+      createdAt: '2026-06-01T00:00:00.000Z'
+    });
+    await writeFile(specPath, `${await readFile(specPath, 'utf8')}\nSpec documentation-only correction.\n`, 'utf8');
+    await writeFile(tasksPath, `${await readFile(tasksPath, 'utf8')}\nTasks documentation-only correction.\n`, 'utf8');
+    const currentSpecHash = hashTestDocument(await readFile(specPath, 'utf8'));
+    const currentTasksHash = hashTestDocument(await readFile(tasksPath, 'utf8'));
+    const acceptedSpecRef = { kind: 'document' as const, ref: 'specs/feature/spec.md', hash: currentSpecHash };
+    const generatedAt = '2026-06-01T00:00:02.000Z';
+    await recordRuntimeProjectionEnvelope(root, {
+      projectionType: SPEC_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+      scopeKey: specCollaborationScopeKey({ branch: 'feature' }),
+      inputHash: 'spec-adjudication-v2',
+      producer: 'phase9.1-spec-stage-collaboration-runtime',
+      producerVersion: 'phase9.1-spec-stage-collaboration-runtime-v1',
+      generatedAt,
+      payload: {
+        contract: 'phase-9.1-stage-collaboration-runtime-v1',
+        adjudicationId: 'spec-adjudication-v2',
+        stage: 'spec',
+        scope: { branch: 'feature' },
+        health: 'ready_for_plan',
+        stageDecision: {
+          contract: 'phase-9.1-stage-collaboration-runtime-v1',
+          decisionId: 'spec-stage-decision-v2',
+          stage: 'spec',
+          scope: { branch: 'feature' },
+          status: 'completed',
+          health: 'ready_for_plan',
+          acceptedDecisionRefs: [acceptedSpecRef],
+          advisoryRefs: [],
+          capabilityRefs: [],
+          blockingReasons: [],
+          createdAt: generatedAt
+        },
+        handoffPacket: null,
+        rejection: null,
+        nextActions: [],
+        closureRefs: {
+          acceptedSpecRef,
+          specHash: currentSpecHash,
+          reasons: []
+        },
+        createdAt: generatedAt
+      }
+    });
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature' });
+
+    assert.equal(workflow.nextIntent.intent, 'reconcile_truth');
+    assert.equal(workflow.nextIntent.bundle, 'tasks');
+    assert.equal(workflow.nextIntent.targetRuntimeStage, 'tasks');
+    assert.equal(workflow.recommendedNextCommand, 'sdd tasks close --branch feature --compact-json');
+    assert.equal(workflow.truthReconciliation?.changedRef.ref, 'specs/feature/tasks.md');
+    assert.equal(workflow.truthReconciliation?.oldHash, originalTasksHash);
+    assert.equal(workflow.truthReconciliation?.newHash, currentTasksHash);
+    assert.equal(workflow.truthReconciliation?.reasons.some((reason) => reason.includes('specs/feature/spec.md')), false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('workflow state routes open repairs before repeating do or validation', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-repair-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    await recordRuntimeRepair(root, buildOpenRepairRecord({
+      branchSlug: 'feature',
+      taskId: 'T1',
+      message: 'validation command is not directly executable: manual: inspect service',
+      recommendedCommands: ['sdd doctor --branch feature --latest-only']
+    }));
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'T1' });
+
+    assert.equal(workflow.openRepairs.length, 1);
+    assert.equal(workflow.nextIntent.intent, 'repair_failure');
+    assert.equal(workflow.recommendedNextCommand, 'sdd doctor --branch feature --latest-only');
+    assert.equal(workflow.blockingReasons.some((reason) => reason.includes('not directly executable')), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('workflow state strict stale rejection names tasks contract drift', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-stale-dimension-'));
+  try {
+    await initProject(root);
+    const originalTasks = validTaskMarkdown('T1', []);
+    await writeBranchDocs(root, 'feature', originalTasks);
+    const run = await createRun(root, { runId: 'run-stale-contract' });
+    await bindTestRunState(root, run.runId, 'feature', 'T1');
+    await markTestRunReadyForShip(root, run.runId, 'T1');
+    await writeBranchDocs(root, 'feature', originalTasks.replace('risk: []', 'required_artifacts:\n  - artifacts/implement-T1.md\nrisk: []'));
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'T1' });
+    const rejected = workflow.latestEligibleRunsByTask.find((selection) => selection.taskId === 'T1')?.rejected.find((candidate) => candidate.runId === 'run-stale-contract');
+
+    assert.equal(workflow.latestRun, null);
+    assert.equal(rejected?.compatibility, 'strict_stale');
+    assert.equal(rejected?.reasons.some((reason) => reason.includes('tasks contract hash drift')), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+
+test('workflow state does not route to ship until every required task has PASS evidence', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-readiness-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `# Tasks\n\n${validTaskMarkdown('T1', []).replace('packages/core/src/index.ts', 'docs/t1.md')}\n${validTaskMarkdown('T2', []).replace('T1', 'T2').replace('packages/core/src/index.ts', 'docs/t2.md')}`);
+    const run = await createRun(root, { runId: 'run-t1-pass' });
+    await bindTestRunState(root, run.runId, 'feature', 'T1');
+    await markTestRunReadyForShip(root, run.runId, 'T1');
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'T1' });
+
+    assert.equal(workflow.nextIntent.stage, 'do');
+    assert.equal(workflow.recommendedNextCommand, 'sdd do task T2 --branch feature');
+    assert.deepEqual(workflow.workflowReadiness.requiredTaskIds, ['T1', 'T2']);
+    assert.deepEqual(workflow.workflowReadiness.acceptedTaskIds, ['T1']);
+    assert.deepEqual(workflow.workflowReadiness.missingTaskIds, ['T2']);
+    assert.equal(workflow.workflowReadiness.readyForShip, false);
+    assert.deepEqual(workflow.whyNotShip, ['Task T2 has no accepted validation PASS evidence.']);
   } finally {
     await rm(root, { recursive: true, force: true });
   }
@@ -40,7 +522,7 @@ test('workflow state resolver reports affected-file conflicts without run-index
     await writeBranchDocs(root, 'feature', `${validTaskMarkdown('T1', []).replace('packages/core/src/index.ts', 'src/shared.ts')}\n${validTaskMarkdown('T2', []).replace('T1', 'T2').replace('packages/core/src/index.ts', 'src/shared.ts')}`);
     const runA = await createRun(root, { runId: 'run-a' });
     await bindTestRunState(root, runA.runId, 'feature', 'T1');
-    await markTestRunReadyForSyncBack(root, runA.runId, 'T1');
+    await markTestRunReadyForShip(root, runA.runId, 'T1');
     const runB = await createRun(root, { runId: 'run-b' });
     await bindTestRunState(root, runB.runId, 'feature', 'T2');
     const archived = await createRun(root, { runId: 'run-c' });
@@ -86,7 +568,7 @@ test('workflow state ignores superseded failed and foreground observer conflict
     });
     const retry = await createRun(root, { runId: 'run-retry' });
     await bindTestRunState(root, retry.runId, 'feature', 'T1');
-    await markTestRunReadyForSyncBack(root, retry.runId, 'T1');
+    await markTestRunReadyForShip(root, retry.runId, 'T1');
 
     const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'T1' });
 
@@ -108,8 +590,368 @@ test('workflow state resolver surfaces dependency blockers and points next actio
 
     assert.deepEqual(workflow.dependencyBlockers.map((blocker) => `${blocker.taskId}->${blocker.dependencyId}`), ['DEP2->DEP1']);
     assert.equal(workflow.blockingReasons.some((reason) => reason.includes('DEP2 depends on DEP1')), true);
-    assert.equal(workflow.recommendedNextCommand, 'sdd tasks inspect DEP1 --branch feature');
+    assert.equal(workflow.recommendedNextCommand, 'sdd do task DEP1 --branch feature');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('workflow state treats implemented batch dependency as ready for downstream do', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-runtime-dependency-ready-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `# Tasks
+
+${validTaskMarkdown('DEP1', [])
+  .replace('packages/core/src/index.ts', 'docs/dep1.md')
+  .replace('validation:\n  - npm test', 'validation_batch: dep-batch\nvalidation_timing: batch_end\nrequires_verify_before_next: false\nvalidation:\n  - npm test')}
+${validTaskMarkdown('DEP2', ['DEP1'])
+  .replace('packages/core/src/index.ts', 'docs/dep2.md')
+  .replace('validation:\n  - npm test', 'validation_batch: dep-batch\nvalidation_timing: batch_end\nrequires_verify_before_next: false\nvalidation:\n  - npm test')}`);
+    const run = await createRun(root, { runId: 'run-dep1-implemented' });
+    await bindTestRunState(root, run.runId, 'feature', 'DEP1');
+    const bound = await readRunState(root, run.runId);
+    await writeRunState(root, {
+      ...bound,
+      status: 'completed',
+      tasks: {
+        ...bound.tasks,
+        DEP1: {
+          status: 'implemented_pending_validation',
+          implementationStatus: 'implemented',
+          verificationStatus: 'pending_batch',
+          validationBatch: 'dep-batch',
+          validationTiming: 'batch_end',
+          requiresVerifyBeforeNext: false,
+          gaps: [],
+          artifacts: []
+        }
+      }
+    });
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'DEP2' });
+
+    assert.deepEqual(workflow.dependencyBlockers, []);
+    assert.equal(workflow.recommendedNextCommand, 'sdd do task DEP2 --branch feature');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('workflow state blocks downstream do until strict dependency verification passes', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-runtime-dependency-strict-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `# Tasks
+
+${validTaskMarkdown('DEP1', [])
+  .replace('packages/core/src/index.ts', 'docs/dep1.md')
+  .replace('validation:\n  - npm test', 'validation_timing: task_end\nrequires_verify_before_next: true\nvalidation:\n  - npm test')}
+${validTaskMarkdown('DEP2', ['DEP1']).replace('packages/core/src/index.ts', 'docs/dep2.md')}`);
+    const run = await createRun(root, { runId: 'run-dep1-strict-implemented' });
+    await bindTestRunState(root, run.runId, 'feature', 'DEP1');
+    const bound = await readRunState(root, run.runId);
+    await writeRunState(root, {
+      ...bound,
+      status: 'completed',
+      tasks: {
+        ...bound.tasks,
+        DEP1: {
+          status: 'implemented_pending_validation',
+          implementationStatus: 'implemented',
+          verificationStatus: 'not_run',
+          validationBatch: null,
+          validationTiming: 'task_end',
+          requiresVerifyBeforeNext: true,
+          gaps: [],
+          artifacts: []
+        }
+      }
+    });
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'DEP2' });
+
+    assert.deepEqual(workflow.dependencyBlockers.map((blocker) => `${blocker.taskId}->${blocker.dependencyId}`), ['DEP2->DEP1']);
+    assert.equal(workflow.blockingReasons.some((reason) => reason.includes('has not passed required verification')), true);
+    assert.equal(workflow.recommendedNextCommand, 'sdd test task-DEP1 --branch feature');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+
+test('latest eligible selector prefers older compatible evidence over newer strict-stale evidence', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-eligible-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const compatible = await createRun(root, { runId: 'run-compatible' });
+    await bindTestRunState(root, compatible.runId, 'feature', 'T1');
+    await markTestRunReadyForShip(root, compatible.runId, 'T1');
+
+    const strictStale = await createRun(root, { runId: 'run-strict-stale' });
+    await bindTestRunState(root, strictStale.runId, 'feature', 'T1');
+    await markTestRunReadyForShip(root, strictStale.runId, 'T1');
+    const strictStaleState = await readRunState(root, strictStale.runId);
+    await writeRunState(root, {
+      ...strictStaleState,
+      documentSnapshot: {
+        ...strictStaleState.documentSnapshot,
+        tasksContractHash: 'stale-tasks-contract-hash',
+        taskContractHash: 'stale-task-contract-hash',
+      }
+    });
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'T1' });
+    const selection = workflow.latestEligibleRunsByTask.find((entry) => entry.taskId === 'T1');
+
+    assert.equal(workflow.latestRun?.runId, 'run-compatible');
+    assert.equal(selection?.selected?.runId, 'run-compatible');
+    assert.deepEqual(selection?.rejected.map((entry) => `${entry.runId}:${entry.compatibility}`), ['run-strict-stale:strict_stale']);
+    assert.equal(selection?.rejected[0]?.reasons.some((reason) => reason.includes('strict_stale')), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('latest eligible selector keeps task-local evidence when another task changes', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-task-local-eligible-'));
+  try {
+    await initProject(root);
+    const task1 = validTaskMarkdown('T1', []).replace('packages/core/src/index.ts', 'docs/t1.md');
+    const task2 = validTaskMarkdown('T2', []).replace('T1', 'T2').replace('packages/core/src/index.ts', 'docs/t2.md');
+    await writeBranchDocs(root, 'feature', `# Tasks\n\n${task1}\n${task2}`);
+    const run = await createRun(root, { runId: 'run-t1-compatible' });
+    await bindTestRunState(root, run.runId, 'feature', 'T1');
+    await markTestRunReadyForShip(root, run.runId, 'T1');
+    await writeBranchDocs(root, 'feature', `# Tasks\n\n${task1}\n${task2.replace('risk: []', 'risk:\n  - security')}`);
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'T1' });
+    const selection = workflow.latestEligibleRunsByTask.find((entry) => entry.taskId === 'T1');
+
+    assert.equal(workflow.latestRun?.runId, 'run-t1-compatible');
+    assert.equal(selection?.selected?.runId, 'run-t1-compatible');
+    assert.deepEqual(selection?.rejected.map((entry) => entry.runId), []);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('latest eligible selector rejects newer blocked runs and keeps older completed evidence eligible', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-blocked-eligible-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const completed = await createRun(root, { runId: 'run-completed' });
+    await bindTestRunState(root, completed.runId, 'feature', 'T1');
+    await markTestRunReadyForShip(root, completed.runId, 'T1');
+
+    const blocked = await createRun(root, { runId: 'run-blocked' });
+    await bindTestRunState(root, blocked.runId, 'feature', 'T1');
+    await markTestRunReadyForShip(root, blocked.runId, 'T1');
+    await writeRunState(root, { ...await readRunState(root, blocked.runId), status: 'blocked' });
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'T1' });
+    const selection = workflow.latestEligibleRunsByTask.find((entry) => entry.taskId === 'T1');
+
+    assert.equal(selection?.selected?.runId, 'run-completed');
+    assert.equal(selection?.rejected.some((entry) => entry.runId === 'run-blocked' && entry.reasons.includes('Run is blocked.')), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('latest eligible selector returns visible candidates and rejects archived or failed runs with reasons', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-rejected-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const failed = await createRun(root, { runId: 'run-failed' });
+    await bindTestRunState(root, failed.runId, 'feature', 'T1');
+    await writeRunState(root, {
+      ...await readRunState(root, failed.runId),
+      status: 'failed',
+      validation: { status: 'fail', commands: ['npm test'], evidence: [] }
+    });
+    const archived = await createRun(root, { runId: 'run-archived' });
+    await bindTestRunState(root, archived.runId, 'feature', 'T1');
+    await writeRunState(root, { ...await readRunState(root, archived.runId), status: 'archived' });
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'T1' });
+    const selection = workflow.latestEligibleRunsByTask.find((entry) => entry.taskId === 'T1');
+
+    assert.equal(workflow.latestRun, null);
+    assert.deepEqual(selection?.candidates.map((entry) => entry.runId), ['run-failed']);
+    assert.deepEqual(selection?.rejected.map((entry) => entry.runId).sort(), ['run-archived', 'run-failed']);
+    assert.equal(selection?.rejected.some((entry) => entry.reasons.includes('Run failed.')), true);
+    assert.equal(selection?.rejected.some((entry) => entry.reasons.includes('Run is archived.')), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('workflow state uses explicit partition runtime despite divergent git branch', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-divergent-'));
+  try {
+    await initProject(root);
+    await execFileAsync('git', ['init'], { cwd: root });
+    await execFileAsync('git', ['checkout', '-b', 'current-branch'], { cwd: root });
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', [])
+      .replace('packages/core/src/index.ts', 'docs/t1.md')
+      .replace('validation:\n  - npm test', 'validation_timing: task_end\nrequires_verify_before_next: true\nvalidation:\n  - npm test'));
+    const divergent = await createRun(root, { runId: 'run-divergent' });
+    await bindTestRunState(root, divergent.runId, 'feature', 'T1');
+    const bound = await readRunState(root, divergent.runId);
+    await writeRunState(root, {
+      ...bound,
+      status: 'completed',
+      tasks: {
+        ...bound.tasks,
+        T1: {
+          status: 'implemented_pending_validation',
+          implementationStatus: 'implemented',
+          verificationStatus: 'not_run',
+          validationBatch: null,
+          validationTiming: 'task_end',
+          requiresVerifyBeforeNext: true,
+          gaps: [],
+          artifacts: []
+        }
+      }
+    });
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'T1' });
+    const selection = workflow.latestEligibleRunsByTask.find((entry) => entry.taskId === 'T1');
+
+    assert.equal(workflow.latestRun?.runId, 'run-divergent');
+    assert.equal(selection?.selected?.runId, 'run-divergent');
+    assert.deepEqual(selection?.rejected.map((entry) => entry.runId), []);
+    assert.equal(workflow.nextIntent.intent, 'run_task_validation');
+    assert.equal(workflow.recommendedNextCommand, 'sdd test task-T1 --branch feature');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('workflow state recommends wave validation for implemented wave_end boundary', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-wave-boundary-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `# Tasks
+
+${validTaskMarkdown('W1', [])
+  .replace('packages/core/src/index.ts', 'docs/w1.md')
+  .replace('validation:\n  - npm test', 'validation_batch: docs-wave\nvalidation_timing: wave_end\nrequires_verify_before_next: false\nvalidation:\n  - npm test')}`);
+    const run = await createRun(root, { runId: 'run-w1-implemented' });
+    await bindTestRunState(root, run.runId, 'feature', 'W1');
+    const bound = await readRunState(root, run.runId);
+    await writeRunState(root, {
+      ...bound,
+      status: 'completed',
+      tasks: {
+        ...bound.tasks,
+        W1: {
+          status: 'implemented_pending_validation',
+          implementationStatus: 'implemented',
+          verificationStatus: 'pending_batch',
+          validationBatch: 'docs-wave',
+          validationTiming: 'wave_end',
+          requiresVerifyBeforeNext: false,
+          gaps: [],
+          artifacts: []
+        }
+      }
+    });
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'W1' });
+
+    assert.equal(workflow.nextIntent.intent, 'run_wave_validation');
+    assert.equal(workflow.recommendedNextCommand, 'sdd test docs-wave --branch feature');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('workflow state dependency readiness ignores newer ineligible runtime state', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-workflow-state-eligible-runtime-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', `# Tasks
+
+${validTaskMarkdown('DEP1', [])
+  .replace('packages/core/src/index.ts', 'docs/dep1.md')
+  .replace('validation:\n  - npm test', 'validation_batch: dep-batch\nvalidation_timing: batch_end\nrequires_verify_before_next: false\nvalidation:\n  - npm test')}
+${validTaskMarkdown('DEP2', ['DEP1']).replace('packages/core/src/index.ts', 'docs/dep2.md')}`);
+    const eligible = await createRun(root, { runId: 'run-dep1-eligible' });
+    await bindTestRunState(root, eligible.runId, 'feature', 'DEP1');
+    const eligibleState = await readRunState(root, eligible.runId);
+    await writeRunState(root, {
+      ...eligibleState,
+      status: 'completed',
+      tasks: {
+        ...eligibleState.tasks,
+        DEP1: {
+          status: 'implemented_pending_validation',
+          implementationStatus: 'implemented',
+          verificationStatus: 'pending_batch',
+          validationBatch: 'dep-batch',
+          validationTiming: 'batch_end',
+          requiresVerifyBeforeNext: false,
+          gaps: [],
+          artifacts: []
+        }
+      }
+    });
+    const blocked = await createRun(root, { runId: 'run-dep1-blocked-newer' });
+    await bindTestRunState(root, blocked.runId, 'feature', 'DEP1');
+    const blockedState = await readRunState(root, blocked.runId);
+    await writeRunState(root, {
+      ...blockedState,
+      status: 'blocked',
+      updatedAt: new Date(Date.parse(eligibleState.updatedAt) + 1000).toISOString(),
+      tasks: {
+        ...blockedState.tasks,
+        DEP1: {
+          status: 'pending',
+          implementationStatus: 'not_started',
+          verificationStatus: 'not_run',
+          validationBatch: 'dep-batch',
+          validationTiming: 'batch_end',
+          requiresVerifyBeforeNext: false,
+          gaps: [],
+          artifacts: []
+        }
+      }
+    });
+
+    const workflow = await resolveWorkflowState(root, { branch: 'feature', taskId: 'DEP2' });
+
+    assert.deepEqual(workflow.dependencyBlockers, []);
+    assert.equal(workflow.recommendedNextCommand, 'sdd test dep-batch --branch feature');
   } finally {
     await rm(root, { recursive: true, force: true });
   }
-});
+});
+
+function truthAlignmentProjection(input: Pick<TruthAlignmentProjection, 'branch' | 'status' | 'ownerStage' | 'semanticImpact' | 'invalidatesStages' | 'staleRefs' | 'reasons'> & { createdAt?: string }): TruthAlignmentProjection {
+  return {
+    contract: 'sdd-truth-alignment-v1',
+    branch: input.branch,
+    sourceStage: 'goal-verify',
+    declaredTruthRefs: [
+      { kind: 'document', ref: `specs/${input.branch}/spec.md`, hash: 'spec-hash' },
+      { kind: 'document', ref: `specs/${input.branch}/tasks.md`, hash: 'tasks-hash' }
+    ],
+    acceptedRealityRefs: [
+      { kind: 'artifact', ref: `.sdd/runs/${input.branch}/goal-verify/goal-verification-v1.md`, hash: 'goal-hash' },
+      { kind: 'artifact', ref: `.sdd/runs/${input.branch}/do/implementation-v1.md`, hash: 'implementation-hash' }
+    ],
+    status: input.status,
+    ownerStage: input.ownerStage,
+    semanticImpact: input.semanticImpact,
+    staleRefs: input.staleRefs,
+    invalidatesStages: input.invalidatesStages,
+    reasons: input.reasons,
+    createdAt: input.createdAt ?? '2026-06-01T00:00:00.000Z'
+  };
+}