sdd-agent-platform 0.4.1 → 0.5.0

package/packages/core/dist/workflow-state/resolve.js

@@ -1,15 +1,29 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
 import { WORKFLOW_STATE_RESOLVER_CONTRACT_VERSION } from '../contracts.js';
-import { recordRuntimeProjection } from '../storage/runtime-store.js';
+import { listRuntimeProjections, listRuntimeRepairs, recordRuntimeProjection } from '../storage/runtime-store.js';
 import { affectedFileConflictsForSelectedRun } from './affected-file-conflicts.js';
 import { readAllRunStates, summarizeRunState } from '../run-state/run-state.js';
 import { resolveSddContext } from '../sdd-docs/context.js';
 import { parseSddBranch } from '../sdd-docs/task-parser.js';
 import { dependencyBlockingReasonsForTask, workflowDependencyBlockers } from './dependencies.js';
 import { selectLatestEligibleRunsByTask } from './latest-eligible-run.js';
+import { EXECUTE_COLLABORATION_ADJUDICATION_PROJECTION_TYPE, PLAN_COLLABORATION_ADJUDICATION_PROJECTION_TYPE, readTruthAlignmentProjection, SHIP_COLLABORATION_ADJUDICATION_PROJECTION_TYPE, SPEC_COLLABORATION_ADJUDICATION_PROJECTION_TYPE, TASKS_COLLABORATION_ADJUDICATION_PROJECTION_TYPE } from '../stage-collaboration.js';
+import { buildTruthReconciliationDecision, minimalReworkFrontier, recordTruthReconciliationDecision, truthDriftClassForAlignment, truthReconciliationOwnerStage } from '../truth-reconciliation.js';
+import { normalizePortablePath } from '../path-safety.js';
+import { hashDocumentContent } from '../sdd-docs/document-hashes.js';
+import { recordWorkflowRuntimeProjections } from './runtime-projections.js';
+export const COMMAND_BUNDLES = {
+    spec: ['spec'],
+    plan: ['plan'],
+    tasks: ['tasks'],
+    execute: ['execute'],
+    ship: ['ship']
+};
 export async function resolveWorkflowState(projectRoot, options = {}) {
     const context = await resolveSddContext(projectRoot, options);
     const branch = context.partition;
-    const [model, states] = await Promise.all([parseSddBranch(projectRoot, branch), readAllRunStates(projectRoot)]);
+    const [model, states, openRepairs, truthAlignmentEnvelope] = await Promise.all([parseSddBranch(projectRoot, branch), readAllRunStates(projectRoot), listRuntimeRepairs(projectRoot, { branchSlug: branch, status: 'open' }), readTruthAlignmentProjection(projectRoot, { branch })]);
     const visibleGaps = workflowIsActive(model) ? model.gaps : [];
     const latestEligibleRunsByTask = selectLatestEligibleRunsByTask({ states, model, partition: branch, currentGitBranch: context.currentGitBranch });
     const latestRunsByTask = selectedLatestTaskRuns(latestEligibleRunsByTask);
@@ -20,10 +34,13 @@ export async function resolveWorkflowState(projectRoot, options = {}) {
     const affectedFileConflicts = latestRunState ? affectedFileConflictsForSelectedRun(states, latestRunState) : [];
     const runtimeByTask = latestRuntimeTaskStates(latestEligibleRunsByTask, states);
     const dependencyBlockers = workflowDependencyBlockers(model, { runtimeByTask });
-    const blockingReasons = blockingWorkflowReasons(visibleGaps, affectedFileConflicts, dependencyBlockers);
+    const readiness = workflowReadinessSummary(model, latestRunsByTask);
+    const generatedAt = new Date().toISOString();
+    const blockingReasons = [...blockingWorkflowReasons(visibleGaps, affectedFileConflicts, dependencyBlockers), ...openRepairs.map(formatOpenRepairReason)];
+    const truthReconciliation = await resolveTruthReconciliationDecision(projectRoot, branch, truthAlignmentEnvelope?.payload ?? null, generatedAt, { states, model });
     const resolution = {
         contract: WORKFLOW_STATE_RESOLVER_CONTRACT_VERSION,
-        generatedAt: new Date().toISOString(),
+        generatedAt,
         branch,
         workflowStatus: workflowIsActive(model) ? 'active' : 'not_started',
         context,
@@ -37,13 +54,18 @@ export async function resolveWorkflowState(projectRoot, options = {}) {
         latestEligibleRunsByTask,
         affectedFileConflicts,
         dependencyBlockers,
+        openRepairs,
         blockingReasons,
-        nextIntent: recommendedWorkflowNextIntent(context, model, latestRunsByTask, visibleGaps, dependencyBlockers, runtimeByTask),
+        workflowReadiness: readiness,
+        whyNotShip: readiness.whyNotShip,
+        nextIntent: recommendedWorkflowNextIntent(context, model, latestRunsByTask, visibleGaps, dependencyBlockers, runtimeByTask, readiness, openRepairs, truthReconciliation),
+        truthReconciliation,
         recommendedNextCommand: ''
     };
     resolution.recommendedNextCommand = resolution.nextIntent.canonicalCommand;
     try {
         await recordRuntimeProjection(projectRoot, 'workflow_state', branch, projectWorkflowStateProjection(resolution));
+        await recordWorkflowRuntimeProjections(projectRoot, resolution);
     }
     catch {
         // Projection writes are rebuildable and must not block workflow resolution.
@@ -75,7 +97,6 @@ function selectedLatestTaskRuns(selections) {
         runId: candidate.runId,
         runStatus: candidate.runStatus,
         validationStatus: candidate.validationStatus,
-        syncBackStatus: candidate.syncBackStatus,
         affectedFiles: candidate.affectedFiles,
         updatedAt: candidate.updatedAt,
         compatibility: candidate.compatibility,
@@ -94,7 +115,325 @@ function blockingWorkflowReasons(gaps, conflicts, dependencyBlockers) {
     }
     return reasons;
 }
-function recommendedWorkflowNextIntent(context, model, latestRunsByTask, gaps, dependencyBlockers, runtimeByTask) {
+async function resolveTruthReconciliationDecision(projectRoot, branch, truthAlignment, generatedAt, progress) {
+    if (!truthAlignment) {
+        return null;
+    }
+    const freshness = await refreshAlignedTruthAlignmentFreshness(projectRoot, branch, truthAlignment);
+    if (freshness.truthAlignment.status === 'aligned') {
+        return null;
+    }
+    const changeKind = truthDriftClassForAlignment(freshness.truthAlignment);
+    const ownerStage = truthReconciliationOwnerStage(changeKind, freshness.truthAlignment.ownerStage);
+    const minimalFrontier = minimalReworkFrontier({ ownerStage, semanticImpact: freshness.truthAlignment.semanticImpact, invalidatesStages: freshness.truthAlignment.invalidatesStages });
+    const targetStage = await activeTruthReconciliationStage(projectRoot, minimalFrontier, freshness.truthAlignment, progress);
+    const nextIntent = truthReconciliationNextIntent(branch, targetStage, freshness.truthAlignment.reasons);
+    const decision = buildTruthReconciliationDecision({
+        truthAlignment: freshness.truthAlignment,
+        nextIntent,
+        changeKind,
+        changedRef: freshness.changedRef,
+        oldHash: freshness.oldHash,
+        newHash: freshness.newHash
+    });
+    await recordTruthReconciliationDecision(projectRoot, decision, generatedAt);
+    return decision;
+}
+async function refreshAlignedTruthAlignmentFreshness(projectRoot, branch, truthAlignment) {
+    if (truthAlignment.status !== 'aligned') {
+        return { truthAlignment };
+    }
+    const staleRefs = [];
+    for (const ref of [...truthAlignment.declaredTruthRefs, ...truthAlignment.acceptedRealityRefs]) {
+        if (!ref.hash || ref.kind === 'projection' || ref.kind === 'run') {
+            continue;
+        }
+        const currentHash = await currentTruthRefHash(projectRoot, ref);
+        if (currentHash !== ref.hash) {
+            staleRefs.push({ ref, currentHash });
+        }
+    }
+    const unresolvedStaleRefs = await unresolvedStaleTruthRefs(projectRoot, branch, truthAlignment, staleRefs);
+    const firstStaleRef = unresolvedStaleRefs[0];
+    if (!firstStaleRef) {
+        return { truthAlignment };
+    }
+    const ownerStage = ownerStageForTruthRef(branch, firstStaleRef.ref) ?? truthAlignment.ownerStage ?? 'ship';
+    const semanticImpact = semanticImpactForTruthRef(branch, firstStaleRef.ref);
+    const reasons = [
+        ...truthAlignment.reasons,
+        ...unresolvedStaleRefs.map((entry) => `TruthAlignment ref hash is stale for ${entry.ref.ref}: expected ${entry.ref.hash ?? 'unknown'}, actual ${entry.currentHash}.`)
+    ];
+    return {
+        truthAlignment: {
+            ...truthAlignment,
+            status: 'update_required',
+            ownerStage,
+            semanticImpact,
+            staleRefs: uniqueRuntimeRefs([...truthAlignment.staleRefs, ...unresolvedStaleRefs.map((entry) => entry.ref)]),
+            invalidatesStages: uniqueStages([...truthAlignment.invalidatesStages, ownerStage]),
+            reasons: uniqueStrings(reasons)
+        },
+        changedRef: firstStaleRef.ref,
+        oldHash: firstStaleRef.ref.hash,
+        newHash: firstStaleRef.currentHash
+    };
+}
+async function unresolvedStaleTruthRefs(projectRoot, branch, truthAlignment, staleRefs) {
+    const unresolved = [];
+    for (const entry of staleRefs) {
+        if (!await staleTruthRefReconciledAfterAlignment(projectRoot, branch, truthAlignment, entry)) {
+            unresolved.push(entry);
+        }
+    }
+    return unresolved;
+}
+async function staleTruthRefReconciledAfterAlignment(projectRoot, branch, truthAlignment, entry) {
+    const stage = ownerStageForTruthRef(branch, entry.ref);
+    return stage ? await stageCloseAcceptedTruthRefAfterTruthAlignment(projectRoot, truthAlignment, stage, entry.ref, entry.currentHash) : false;
+}
+async function activeTruthReconciliationStage(projectRoot, frontier, truthAlignment, progress) {
+    for (const stage of frontier) {
+        if (!await truthReconciliationStageCompleted(projectRoot, stage, truthAlignment, progress)) {
+            return stage;
+        }
+    }
+    return frontier[frontier.length - 1] ?? truthAlignment.ownerStage ?? 'ship';
+}
+async function truthReconciliationStageCompleted(projectRoot, stage, truthAlignment, progress) {
+    if (await stageCloseCompletedAfterTruthAlignment(projectRoot, truthAlignment, stage)) {
+        return true;
+    }
+    const taskIds = reconciliationTaskIds(truthAlignment, progress);
+    if (stage === 'execute') {
+        return taskIds.every((taskId) => progress.states.some((state) => stateAfterTruthAlignment(state, truthAlignment) && stateTaskImplemented(state.tasks[taskId]) && stateTaskValidationPassed(state.tasks[taskId], state)));
+    }
+    return false;
+}
+function reconciliationTaskIds(truthAlignment, progress) {
+    const requiredIds = requiredTaskIds(progress.model);
+    const requiredIdSet = new Set(requiredIds);
+    const targetRefs = new Set([...truthAlignment.staleRefs, ...truthAlignment.acceptedRealityRefs].map((ref) => normalizePortablePath(ref.ref)).filter(Boolean));
+    const taskIds = new Set();
+    for (const state of progress.states) {
+        if (state.partition && state.partition !== truthAlignment.branch) {
+            continue;
+        }
+        if (!stateReferencesAnyRef(state, targetRefs)) {
+            continue;
+        }
+        for (const taskId of stateTaskIds(state)) {
+            if (requiredIdSet.has(taskId)) {
+                taskIds.add(taskId);
+            }
+        }
+    }
+    const scopedTaskIds = [...taskIds].sort();
+    return scopedTaskIds.length > 0 ? scopedTaskIds : requiredIds;
+}
+function stateReferencesAnyRef(state, targetRefs) {
+    if (targetRefs.size === 0) {
+        return false;
+    }
+    const refs = [
+        ...state.artifacts.map((artifact) => artifact.path),
+        ...Object.values(state.tasks).flatMap((runtime) => [...(runtime.artifacts ?? []), ...(runtime.evidence ?? [])])
+    ];
+    return refs.some((ref) => refMatchesTarget(ref, targetRefs));
+}
+function refMatchesTarget(ref, targetRefs) {
+    const normalized = normalizePortablePath(ref);
+    return Boolean(normalized && [...targetRefs].some((target) => normalized === target || normalized.endsWith(`/${target}`) || target.endsWith(`/${normalized}`)));
+}
+function stateTaskIds(state) {
+    return [...new Set([state.taskId, state.currentTask, ...Object.keys(state.tasks)].filter((taskId) => typeof taskId === 'string' && taskId.length > 0))];
+}
+async function stageCloseCompletedAfterTruthAlignment(projectRoot, truthAlignment, stage) {
+    const projectionType = stageAdjudicationProjectionType(stage);
+    if (!projectionType) {
+        return false;
+    }
+    const projections = await listRuntimeProjections(projectRoot, [projectionType]);
+    return projections
+        .map((projection) => projection.payload)
+        .some((envelope) => stageAdjudicationCompletedAfterTruthAlignment(envelope, truthAlignment, stage));
+}
+function stageAdjudicationProjectionType(stage) {
+    const projectionTypes = {
+        spec: SPEC_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+        plan: PLAN_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+        tasks: TASKS_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+        execute: EXECUTE_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+        ship: SHIP_COLLABORATION_ADJUDICATION_PROJECTION_TYPE
+    };
+    return projectionTypes[stage] ?? null;
+}
+async function stageCloseAcceptedTruthRefAfterTruthAlignment(projectRoot, truthAlignment, stage, staleRef, currentHash) {
+    const projectionType = stageAdjudicationProjectionType(stage);
+    if (!projectionType) {
+        return false;
+    }
+    const projections = await listRuntimeProjections(projectRoot, [projectionType]);
+    return projections
+        .map((projection) => projection.payload)
+        .some((envelope) => stageAdjudicationCompletedAfterTruthAlignment(envelope, truthAlignment, stage)
+        && acceptedStageRefs(envelope.payload).some((acceptedRef) => acceptedTruthRefMatchesCurrent(acceptedRef, staleRef, currentHash)));
+}
+function acceptedTruthRefMatchesCurrent(acceptedRef, staleRef, currentHash) {
+    return acceptedRef.kind === staleRef.kind
+        && normalizePortablePath(acceptedRef.ref) === normalizePortablePath(staleRef.ref)
+        && acceptedRef.hash === currentHash;
+}
+function stageAdjudicationCompletedAfterTruthAlignment(envelope, truthAlignment, stage) {
+    const expectedHealth = expectedStageCloseHealth(stage);
+    return envelope.payload?.scope?.branch === truthAlignment.branch
+        && envelope.payload.stage === stage
+        && Date.parse(envelope.generatedAt) > Date.parse(truthAlignment.createdAt)
+        && envelope.payload.stageDecision?.status === 'completed'
+        && (envelope.payload.health === expectedHealth || envelope.payload.stageDecision?.health === expectedHealth)
+        && acceptedStageRefs(envelope.payload).some((ref) => ownerStageForTruthRef(truthAlignment.branch, ref) === stage);
+}
+function expectedStageCloseHealth(stage) {
+    const expectedHealth = {
+        spec: 'ready_for_plan',
+        plan: 'ready_for_tasks',
+        tasks: 'ready_for_execute',
+        execute: 'ready_for_ship',
+        ship: 'ship_ready'
+    };
+    return expectedHealth[stage];
+}
+function acceptedStageRefs(adjudication) {
+    const refs = Array.isArray(adjudication.stageDecision?.acceptedDecisionRefs) ? adjudication.stageDecision.acceptedDecisionRefs : [];
+    const closureRefs = adjudication.closureRefs ?? {};
+    const closureRefKeys = [
+        'acceptedSpecRef',
+        'acceptedPlanRef',
+        'acceptedTasksRef',
+        'acceptedVerifyRef',
+        'acceptedImplementationRef',
+        'acceptedTestEvidenceRef',
+        'acceptedEvidenceJudgmentRef',
+        'acceptedShipReadinessRef'
+    ];
+    return [
+        ...refs,
+        ...closureRefKeys.map((key) => runtimeRefFromUnknown(closureRefs[key]))
+    ].filter((ref) => ref !== null);
+}
+function runtimeRefFromUnknown(value) {
+    if (!value || typeof value !== 'object') {
+        return null;
+    }
+    const candidate = value;
+    if (typeof candidate.kind !== 'string' || typeof candidate.ref !== 'string') {
+        return null;
+    }
+    return {
+        kind: candidate.kind,
+        ref: candidate.ref,
+        hash: typeof candidate.hash === 'string' ? candidate.hash : undefined
+    };
+}
+function requiredTaskIds(model) {
+    return model.tasks.filter((task) => task.status !== 'deferred').map((task) => task.id);
+}
+function stateAfterTruthAlignment(state, truthAlignment) {
+    return Date.parse(state.updatedAt) > Date.parse(truthAlignment.createdAt);
+}
+function stateTaskImplemented(runtime) {
+    return runtimeTaskImplemented(runtime);
+}
+function stateTaskValidationPassed(runtime, state) {
+    return runtime?.verificationStatus === 'pass' || runtime?.status === 'implemented_verified' || state.validation.status === 'pass';
+}
+async function currentTruthRefHash(projectRoot, ref) {
+    const normalized = normalizePortablePath(ref.ref);
+    if (!normalized || normalized === '.' || normalized === '..' || normalized.includes('..') || path.isAbsolute(ref.ref)) {
+        return 'unsafe-ref';
+    }
+    const projectPath = path.resolve(projectRoot);
+    const filePath = path.resolve(projectPath, normalized);
+    if (!filePath.startsWith(`${projectPath}${path.sep}`)) {
+        return 'escaped-ref';
+    }
+    try {
+        return hashDocumentContent(await readFile(filePath, 'utf8'));
+    }
+    catch {
+        return 'missing-ref';
+    }
+}
+function ownerStageForTruthRef(branch, ref) {
+    const normalized = normalizePortablePath(ref.ref);
+    if (!normalized) {
+        return null;
+    }
+    if (normalized === `specs/${branch}/spec.md`) {
+        return 'spec';
+    }
+    if (normalized === `specs/${branch}/plan.md`) {
+        return 'plan';
+    }
+    if (normalized === `specs/${branch}/tasks.md`) {
+        return 'tasks';
+    }
+    if (normalized === `specs/${branch}/verify.md`) {
+        return 'tasks';
+    }
+    if (normalized === `specs/${branch}/release.md`) {
+        return 'ship';
+    }
+    const runStage = normalized.match(new RegExp(`^\\.sdd/runs/${escapeRegExp(branch)}/([^/]+)/`))?.[1];
+    return runStage && isSddStage(runStage) ? runStage : null;
+}
+function semanticImpactForTruthRef(branch, ref) {
+    const ownerStage = ownerStageForTruthRef(branch, ref);
+    return ref.kind === 'document' || ownerStage === 'spec' || ownerStage === 'plan' || ownerStage === 'tasks' ? 'none' : 'material';
+}
+function uniqueRuntimeRefs(refs) {
+    const seen = new Set();
+    const result = [];
+    for (const ref of refs) {
+        const key = `${ref.kind}:${ref.ref}:${ref.hash ?? ''}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(ref);
+        }
+    }
+    return result;
+}
+function uniqueStages(stages) {
+    return ['spec', 'plan', 'tasks', 'execute', 'ship'].filter((stage) => stages.includes(stage));
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function truthReconciliationNextIntent(branch, ownerStage, reasons) {
+    const bundle = commandBundleForRuntimeStage(ownerStage);
+    return workflowNextIntent(bundle, 'reconcile_truth', truthReconciliationCommand(branch, ownerStage), `Reconcile truth drift in ${ownerStage}-manager before downstream ship readiness.`, reasons.join('; ') || 'truthAlignment requires reconciliation', {
+        targetRuntimeStage: ownerStage,
+        resumeMode: 'reconcile',
+        canAutoAdvanceWithinBundle: ownerStage === 'execute',
+        evidenceSurface: [...evidenceSurfaceForRuntimeStage(ownerStage), 'truthReconciliation projection']
+    });
+}
+function truthReconciliationCommand(branch, ownerStage) {
+    return stageCloseCommandForRuntimeStage(branch, ownerStage);
+}
+function stageCloseCommandForRuntimeStage(branch, stage) {
+    if (stage === 'execute') {
+        return `sdd execute close --branch ${branch} --compact-json`;
+    }
+    return `sdd ${stage} close --branch ${branch} --compact-json`;
+}
+function formatOpenRepairReason(repair) {
+    return `Open ${repair.repairType} ${repair.repairId}: ${repair.blockers.join('; ')}`;
+}
+function recommendedWorkflowNextIntent(context, model, latestRunsByTask, gaps, dependencyBlockers, runtimeByTask, readiness, openRepairs, truthReconciliation) {
     if (!workflowIsActive(model)) {
         return workflowNextIntent('spec', 'start_spec', `sdd spec --branch ${context.partition}`, 'Start the spec stage before planning or task execution.', null);
     }
@@ -102,23 +441,38 @@ function recommendedWorkflowNextIntent(context, model, latestRunsByTask, gaps, d
     if (blockingGap) {
         return workflowNextIntent('tasks', 'resolve_task_gaps', `sdd tasks gaps --branch ${context.partition}`, 'Resolve blocking task document gaps before execution evidence can be trusted.', `${blockingGap.field}: ${blockingGap.message}`);
     }
+    const openRepair = openRepairs[0];
+    if (openRepair) {
+        return workflowNextIntent('execute', 'repair_failure', openRepair.recommendedCommands[0] ?? `sdd doctor --branch ${context.partition} --latest-only`, openRepair.requiredEvidence.join('; ') || 'Resolve the open repair with new accepted evidence or a fresh gate PASS.', formatOpenRepairReason(openRepair));
+    }
+    if (truthReconciliation) {
+        return truthReconciliation.nextIntent;
+    }
     const strictTask = model.tasks.find((task) => needsTaskValidation(task, runtimeByTask.get(task.id)));
     if (strictTask) {
-        return workflowNextIntent('test', 'run_task_validation', `sdd test task ${strictTask.id} --branch ${context.partition}`, 'Validate this strict or task_end task before more implementation proceeds.', null);
+        return workflowNextIntent('execute', 'run_task_validation', validationUnitCommand(context.partition, validationUnitIdForTask(strictTask)), 'Validate this task before more implementation proceeds.', null);
     }
     const readyBoundary = readyValidationBoundary(model, runtimeByTask);
     if (readyBoundary?.kind === 'batch') {
-        return workflowNextIntent('test', 'run_batch_validation', `sdd test batch ${readyBoundary.id} --branch ${context.partition}`, `Validate accumulated implementation evidence for batch ${readyBoundary.id}.`, null);
+        return workflowNextIntent('execute', 'run_batch_validation', validationUnitCommand(context.partition, readyBoundary.id), `Validate accumulated implementation evidence for validation unit ${readyBoundary.id}.`, null);
     }
     if (readyBoundary?.kind === 'wave') {
-        return workflowNextIntent('test', 'run_wave_validation', waveValidationCommand(context.partition, readyBoundary.wave), `Validate accumulated implementation evidence for wave ${readyBoundary.wave ?? 'all'}.`, null);
+        return workflowNextIntent('execute', 'run_wave_validation', validationUnitCommand(context.partition, readyBoundary.id), `Validate accumulated implementation evidence for validation unit ${readyBoundary.id}.`, null);
     }
-    if (latestRunsByTask.some(latestEligibleRunReadyForShip)) {
-        return workflowNextIntent('ship', 'ship_readiness', `sdd ship --branch ${context.partition} --dry-run`, 'Run release readiness after validation PASS; create a decision card only if the gate requires human review.', null);
+    if (readiness.readyForShip) {
+        if (evidenceJudgmentPassedForShip(model, runtimeByTask)) {
+            return workflowNextIntent('ship', 'ship_readiness', `sdd ship close --branch ${context.partition} --compact-json`, 'Execute evidence judgment passed; close ship readiness with ship-stage evidence.', null);
+        }
+        return workflowNextIntent('execute', 'continue_execute', stageCloseCommandForRuntimeStage(context.partition, 'execute'), 'Close execute with evidence-judgment material before ship readiness can run.', null, {
+            targetRuntimeStage: 'execute',
+            resumeMode: 'resume',
+            canAutoAdvanceWithinBundle: true,
+            evidenceSurface: ['.sdd/runs/<branch>/execute/*.md', 'truthAlignment projection']
+        });
     }
     const nextTask = model.tasks.find((task) => task.status === 'pending' && !runtimeTaskImplemented(runtimeByTask.get(task.id)) && dependencyBlockingReasonsForTask(model, task.id, { runtimeByTask }).length === 0);
     if (nextTask) {
-        return workflowNextIntent('do', 'continue_do', `sdd do task ${nextTask.id} --branch ${context.partition}`, 'Continue sequential implementation; validation can wait until the declared task or batch boundary.', null);
+        return workflowNextIntent('execute', 'continue_execute', `sdd execute --branch ${context.partition}`, `Continue public execute stage for ready task ${nextTask.id}.`, null);
     }
     const dependencyBlocker = dependencyBlockers[0];
     if (dependencyBlocker) {
@@ -126,10 +480,10 @@ function recommendedWorkflowNextIntent(context, model, latestRunsByTask, gaps, d
     }
     const pendingTask = model.tasks.find((task) => task.status === 'pending');
     return pendingTask
-        ? workflowNextIntent('tasks', 'inspect_task', `sdd tasks inspect ${pendingTask.id} --branch ${context.partition}`, 'Inspect task boundary, acceptance, validation, and capability needs before do/test.', null)
+        ? workflowNextIntent('tasks', 'inspect_task', `sdd tasks inspect ${pendingTask.id} --branch ${context.partition}`, 'Inspect task boundary, acceptance, validation, and capability needs before execute.', null)
         : workflowNextIntent('tasks', 'list_tasks', `sdd tasks list --branch ${context.partition}`, 'Inspect task state and decide whether to continue or ship.', null);
 }
-function latestRuntimeTaskStates(selections, states) {
+export function latestRuntimeTaskStates(selections, states) {
     const stateByRunId = new Map(states.map((state) => [state.runId, state]));
     const result = new Map();
     for (const selection of selections) {
@@ -147,6 +501,9 @@ function latestRuntimeTaskStates(selections, states) {
 function needsTaskValidation(task, runtime) {
     return Boolean(runtimeTaskImplemented(runtime) && runtime?.verificationStatus !== 'pass' && (task.requiresVerifyBeforeNext || task.validationTiming === 'task_end'));
 }
+function validationUnitIdForTask(task) {
+    return task.validationBatch ?? `task-${task.id}`;
+}
 function readyValidationBoundary(model, runtimeByTask) {
     const batchGroups = new Map();
     const waveGroups = new Map();
@@ -155,10 +512,8 @@ function readyValidationBoundary(model, runtimeByTask) {
             batchGroups.set(task.validationBatch, [...(batchGroups.get(task.validationBatch) ?? []), task]);
         }
         if (task.validationTiming === 'wave_end') {
-            const key = String(task.wave ?? 'all');
-            const group = waveGroups.get(key) ?? { wave: task.wave, tasks: [] };
-            group.tasks.push(task);
-            waveGroups.set(key, group);
+            const id = validationUnitIdForTask(task);
+            waveGroups.set(id, [...(waveGroups.get(id) ?? []), task]);
         }
     }
     for (const [id, tasks] of batchGroups) {
@@ -166,9 +521,9 @@ function readyValidationBoundary(model, runtimeByTask) {
             return { kind: 'batch', id };
         }
     }
-    for (const group of waveGroups.values()) {
-        if (validationBoundaryReady(group.tasks, runtimeByTask)) {
-            return { kind: 'wave', wave: group.wave };
+    for (const [id, tasks] of waveGroups) {
+        if (validationBoundaryReady(tasks, runtimeByTask)) {
+            return { kind: 'wave', id };
         }
     }
     return null;
@@ -183,26 +538,120 @@ function runtimeTaskImplemented(runtime) {
 function latestEligibleRunReadyForShip(run) {
     return run.runStatus === 'completed' && run.validationStatus === 'pass';
 }
-function waveValidationCommand(branch, wave) {
-    return wave === null ? `sdd test wave --branch ${branch}` : `sdd test wave --branch ${branch} --wave ${wave}`;
+function evidenceJudgmentPassedForShip(model, runtimeByTask) {
+    const requiredTasks = model.tasks.filter((task) => task.status !== 'deferred');
+    return requiredTasks.length > 0 && requiredTasks.every((task) => {
+        const runtime = runtimeByTask.get(task.id);
+        return runtime?.verifyStatus === 'PASS' || runtime?.status === 'implemented_verified';
+    });
+}
+function workflowReadinessSummary(model, latestRunsByTask) {
+    const requiredTaskIds = model.tasks.filter((task) => task.status !== 'deferred').map((task) => task.id).sort();
+    const acceptedTaskIds = requiredTaskIds.filter((taskId) => latestRunsByTask.some((run) => run.taskId === taskId && latestEligibleRunReadyForShip(run))).sort();
+    const missingTaskIds = requiredTaskIds.filter((taskId) => !acceptedTaskIds.includes(taskId));
+    return {
+        requiredTaskIds,
+        acceptedTaskIds,
+        missingTaskIds,
+        readyForShip: requiredTaskIds.length > 0 && missingTaskIds.length === 0,
+        whyNotShip: missingTaskIds.length === 0 ? [] : missingTaskIds.map((taskId) => `Task ${taskId} has no accepted validation PASS evidence.`)
+    };
+}
+function validationUnitCommand(branch, validationUnitId) {
+    return `sdd execute --branch ${branch} --json`;
 }
-function workflowNextIntent(stage, intent, canonicalCommand, evidenceRequirement, blockingReason) {
+export function workflowNextIntent(stage, intent, canonicalCommand, evidenceRequirement, blockingReason, options = {}) {
+    const targetRuntimeStage = options.targetRuntimeStage ?? runtimeStageForCommand(canonicalCommand, stage);
+    const bundle = commandBundleForRuntimeStage(targetRuntimeStage);
+    const stages = [...COMMAND_BUNDLES[bundle]];
+    const autoAdvanceTo = options.autoAdvanceTo ?? null;
+    const canAutoAdvanceWithinBundle = options.canAutoAdvanceWithinBundle ?? Boolean(autoAdvanceTo && stages.includes(autoAdvanceTo));
+    const displayCommand = options.displayCommand ?? commandBundleDisplayCommand(bundle, targetRuntimeStage, canonicalCommand);
+    const stopReasons = options.stopReasons ?? [];
+    const evidenceSurface = options.evidenceSurface ?? evidenceSurfaceForRuntimeStage(targetRuntimeStage);
+    const resumeMode = options.resumeMode ?? defaultResumeMode(intent, targetRuntimeStage);
+    const commandBundle = {
+        contract: 'sdd-command-bundle-plan-v1',
+        branch: branchFromCommand(canonicalCommand),
+        bundle,
+        stages,
+        targetRuntimeStage,
+        resumeMode,
+        canonicalCommand,
+        displayCommand,
+        canAutoAdvanceWithinBundle,
+        autoAdvanceTo,
+        stopReasons,
+        evidenceSurface
+    };
     return {
-        stage,
+        stage: bundle,
+        bundle,
+        targetRuntimeStage,
+        resumeMode,
         intent,
         canonicalCommand,
-        commandSemantics: stage === 'do' || stage === 'test' || stage === 'ship' ? 'gate_execution' : 'inspection_navigation',
+        displayCommand,
+        commandSemantics: commandSemanticsForTarget(bundle, targetRuntimeStage, canonicalCommand),
         evidenceRequirement,
         blockingReason,
-        hostProjections: hostCommandProjections(canonicalCommand)
+        canAutoAdvanceWithinBundle,
+        autoAdvanceTo,
+        stopReasons,
+        evidenceSurface,
+        commandBundle,
+        hostProjections: hostCommandProjections(commandBundle)
     };
 }
-function hostCommandProjections(canonicalCommand) {
+export function commandBundleForRuntimeStage(stage) {
+    return stage;
+}
+function runtimeStageForCommand(canonicalCommand, fallbackBundle) {
+    const command = canonicalCommand.replace(/^sdd\s+/, '').split(/\s+/)[0];
+    return isSddStage(command) ? command : COMMAND_BUNDLES[fallbackBundle][0];
+}
+function isSddStage(value) {
+    return value === 'spec' || value === 'plan' || value === 'tasks' || value === 'execute' || value === 'ship';
+}
+function defaultResumeMode(intent, targetRuntimeStage) {
+    if (intent === 'repair_failure') {
+        return 'repair';
+    }
+    if (targetRuntimeStage === 'execute') {
+        return 'resume';
+    }
+    return 'start';
+}
+function commandSemanticsForTarget(bundle, targetRuntimeStage, canonicalCommand) {
+    if (/^sdd\s+status\b/.test(canonicalCommand)) {
+        return 'inspection_navigation';
+    }
+    return bundle === 'execute' || bundle === 'ship' || /\sclose\b/.test(canonicalCommand) || targetRuntimeStage === 'execute' ? 'gate_execution' : 'inspection_navigation';
+}
+function evidenceSurfaceForRuntimeStage(stage) {
+    const surfaces = {
+        spec: ['specs/<branch>/spec.md', '.sdd/runs/<branch>/spec/*.md'],
+        plan: ['specs/<branch>/plan.md', '.sdd/runs/<branch>/plan/*.md'],
+        tasks: ['specs/<branch>/tasks.md', 'specs/<branch>/verify.md', '.sdd/runs/<branch>/tasks/*.md'],
+        execute: ['.sdd/runs/<branch>/execute/*.md', 'truthAlignment projection'],
+        ship: ['.sdd/runs/<branch>/ship/*.md', 'truthAlignment projection']
+    };
+    return surfaces[stage] ?? [`.sdd/runs/<branch>/${stage}/*.md`];
+}
+function branchFromCommand(canonicalCommand) {
+    const tokens = canonicalCommand.split(/\s+/);
+    const branchIndex = tokens.indexOf('--branch');
+    return branchIndex >= 0 ? tokens[branchIndex + 1] ?? '<branch>' : '<branch>';
+}
+function commandBundleDisplayCommand(bundle, targetRuntimeStage, canonicalCommand) {
+    return claudeCodeSlashEntry({ bundle, targetRuntimeStage, canonicalCommand });
+}
+function hostCommandProjections(commandBundle) {
     return [
         {
             host: 'claude_code',
             status: 'active',
-            entry: claudeCodeSlashEntry(canonicalCommand),
+            entry: claudeCodeSlashEntry(commandBundle),
             projectionSurfaces: ['slash command', 'skill', 'settings/hooks/statusline metadata'],
             permissionProjection: 'Claude Code permission mode/tool prompts remain host enforcement, not SDD lifecycle truth.',
             reason: 'Claude Code supports slash/skill/statusline projections; the canonical CLI command remains the portable source of workflow intent.'
@@ -218,19 +667,48 @@ function hostCommandProjections(canonicalCommand) {
         {
             host: 'opencode',
             status: 'active',
-            entry: opencodeCommandEntry(canonicalCommand),
+            entry: opencodeCommandEntry(commandBundle),
             projectionSurfaces: ['opencode.json/jsonc', '.opencode/commands', '.opencode/agents', '.opencode/skills', 'permissions'],
             permissionProjection: 'OpenCode allow/ask/deny permissions can project SDD tool policy; SDD artifacts remain authoritative evidence.',
             reason: 'OpenCode documents project commands, agents, skills, and permissions suitable for host-specific projection.'
         }
     ];
 }
-function claudeCodeSlashEntry(canonicalCommand) {
-    const [command, ...rest] = canonicalCommand.replace(/^sdd\s+/, '').split(' ');
-    return `/sdd:${command}${rest.length > 0 ? ` ${rest.join(' ')}` : ''}`;
+function claudeCodeSlashEntry(commandBundle) {
+    return projectedCommandEntry('/sdd:', commandBundle, ':');
+}
+function opencodeCommandEntry(commandBundle) {
+    return projectedCommandEntry('/sdd ', commandBundle, ' ');
+}
+function projectedCommandEntry(prefix, commandBundle, separator) {
+    const tokens = commandBundle.canonicalCommand.replace(/^sdd\s+/, '').split(/\s+/).filter(Boolean);
+    const [command, ...rest] = tokens;
+    if (!command) {
+        return `/sdd ${tokens.join(' ')}`;
+    }
+    if (command === 'execute') {
+        const head = separator === ':' ? `${prefix}execute` : `${prefix}execute`;
+        return `${head}${rest.length > 0 ? ` ${rest.join(' ')}` : ''}`;
+    }
+    if (!isSddStage(command)) {
+        return `/sdd ${tokens.join(' ')}`;
+    }
+    const tailTokens = stripTargetOption(rest);
+    const publicClose = command === commandBundle.bundle && tailTokens[0] === 'close';
+    const target = publicClose || commandBundle.targetRuntimeStage === commandBundle.bundle ? '' : ` target=${commandBundle.targetRuntimeStage}`;
+    const head = separator === ':' ? `${prefix}${commandBundle.bundle}` : `${prefix}${commandBundle.bundle}`;
+    return `${head}${target}${tailTokens.length > 0 ? ` ${tailTokens.join(' ')}` : ''}`;
 }
-function opencodeCommandEntry(canonicalCommand) {
-    return `/sdd ${canonicalCommand.replace(/^sdd\s+/, '')}`;
+function stripTargetOption(tokens) {
+    const result = [];
+    for (let index = 0; index < tokens.length; index += 1) {
+        if (tokens[index] === '--target') {
+            index += 1;
+            continue;
+        }
+        result.push(tokens[index]);
+    }
+    return result;
 }
 function projectWorkflowStateProjection(resolution) {
     return {
@@ -245,8 +723,12 @@ function projectWorkflowStateProjection(resolution) {
         latestEligibleRunsByTask: resolution.latestEligibleRunsByTask,
         affectedFileConflicts: resolution.affectedFileConflicts,
         dependencyBlockers: resolution.dependencyBlockers,
+        openRepairs: resolution.openRepairs,
         blockingReasons: resolution.blockingReasons,
+        workflowReadiness: resolution.workflowReadiness,
+        whyNotShip: resolution.whyNotShip,
         nextIntent: resolution.nextIntent,
+        truthReconciliation: resolution.truthReconciliation,
         recommendedNextCommand: resolution.recommendedNextCommand
     };
 }