sdd-agent-platform 0.4.0 → 0.4.2

package/node_modules/@sdd-agent-platform/core/dist/workflow-state/resolve.js

@@ -1,26 +1,47 @@
+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 { workflowDependencyBlockers } from './dependencies.js';
+import { dependencyBlockingReasonsForTask, workflowDependencyBlockers } from './dependencies.js';
+import { selectLatestEligibleRunsByTask } from './latest-eligible-run.js';
+import { DO_COLLABORATION_ADJUDICATION_PROJECTION_TYPE, GOAL_VERIFY_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, TEST_COLLABORATION_ADJUDICATION_PROJECTION_TYPE, VERIFIES_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', 'verifies'],
+    do: ['do'],
+    test: ['test', 'goal-verify'],
+    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 latestRunsByTask = latestTaskRuns(states, branch);
+    const latestEligibleRunsByTask = selectLatestEligibleRunsByTask({ states, model, partition: branch, currentGitBranch: context.currentGitBranch });
+    const latestRunsByTask = selectedLatestTaskRuns(latestEligibleRunsByTask);
     const selectedTaskRun = options.taskId
         ? latestRunsByTask.find((entry) => entry.taskId === options.taskId) ?? null
         : latestRunsByTask.slice().sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt))[0] ?? null;
     const latestRunState = selectedTaskRun ? states.find((state) => state.runId === selectedTaskRun.runId) ?? null : null;
     const affectedFileConflicts = latestRunState ? affectedFileConflictsForSelectedRun(states, latestRunState) : [];
-    const dependencyBlockers = workflowDependencyBlockers(model);
-    const blockingReasons = blockingWorkflowReasons(visibleGaps, affectedFileConflicts, dependencyBlockers);
+    const runtimeByTask = latestRuntimeTaskStates(latestEligibleRunsByTask, states);
+    const dependencyBlockers = workflowDependencyBlockers(model, { runtimeByTask });
+    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,
@@ -31,12 +52,25 @@ export async function resolveWorkflowState(projectRoot, options = {}) {
         latestRun: latestRunState ? summarizeRunState(latestRunState) : null,
         latestRunState,
         latestRunsByTask,
+        latestEligibleRunsByTask,
         affectedFileConflicts,
         dependencyBlockers,
+        openRepairs,
         blockingReasons,
-        recommendedNextCommand: recommendedNextCommand(context, model, latestRunState, visibleGaps, dependencyBlockers)
+        workflowReadiness: readiness,
+        whyNotShip: readiness.whyNotShip,
+        nextIntent: recommendedWorkflowNextIntent(context, model, latestRunsByTask, visibleGaps, dependencyBlockers, runtimeByTask, readiness, openRepairs, truthReconciliation),
+        truthReconciliation,
+        recommendedNextCommand: ''
     };
-    await recordRuntimeProjection(projectRoot, 'workflow_state', branch, projectWorkflowStateProjection(resolution));
+    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.
+    }
     return resolution;
 }
 function workflowIsActive(model) {
@@ -54,29 +88,23 @@ function taskCounts(model, gaps) {
         gaps: gaps.length
     };
 }
-function latestTaskRuns(states, partition) {
-    const latest = new Map();
-    for (const state of states) {
-        if (state.status === 'archived' || state.partition !== partition || !state.taskId) {
-            continue;
-        }
-        const entry = {
-            partition,
-            gitBranch: state.gitBranch,
-            taskId: state.taskId,
-            runId: state.runId,
-            runStatus: state.status,
-            validationStatus: state.validation.status,
-            syncBackStatus: state.syncBack.status,
-            affectedFiles: state.affectedFiles,
-            updatedAt: state.updatedAt
-        };
-        const existing = latest.get(entry.taskId);
-        if (!existing || Date.parse(entry.updatedAt) > Date.parse(existing.updatedAt) || (entry.updatedAt === existing.updatedAt && entry.runId.localeCompare(existing.runId) > 0)) {
-            latest.set(entry.taskId, entry);
-        }
-    }
-    return Array.from(latest.values()).sort((left, right) => left.taskId.localeCompare(right.taskId));
+function selectedLatestTaskRuns(selections) {
+    return selections
+        .flatMap((selection) => selection.selected ? [selection.selected] : [])
+        .map((candidate) => ({
+        partition: candidate.partition,
+        gitBranch: candidate.gitBranch,
+        taskId: candidate.taskId,
+        runId: candidate.runId,
+        runStatus: candidate.runStatus,
+        validationStatus: candidate.validationStatus,
+        affectedFiles: candidate.affectedFiles,
+        updatedAt: candidate.updatedAt,
+        compatibility: candidate.compatibility,
+        eligibleForDefaultApply: candidate.eligibleForDefaultApply,
+        reasons: candidate.reasons
+    }))
+        .sort((left, right) => left.taskId.localeCompare(right.taskId));
 }
 function blockingWorkflowReasons(gaps, conflicts, dependencyBlockers) {
     const reasons = gaps.filter((gap) => gap.severity === 'blocking').map((gap) => `${gap.field}: ${gap.message}`);
@@ -88,22 +116,621 @@ function blockingWorkflowReasons(gaps, conflicts, dependencyBlockers) {
     }
     return reasons;
 }
-function recommendedNextCommand(context, model, latestRun, gaps, dependencyBlockers) {
+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 === 'do') {
+        return taskIds.every((taskId) => progress.states.some((state) => stateAfterTruthAlignment(state, truthAlignment) && stateTaskImplemented(state.tasks[taskId])));
+    }
+    if (stage === 'test') {
+        return taskIds.every((taskId) => progress.states.some((state) => stateAfterTruthAlignment(state, truthAlignment) && stateTaskValidationPassed(state.tasks[taskId], state)));
+    }
+    if (stage === 'goal-verify') {
+        return truthAlignment.status === 'aligned';
+    }
+    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,
+        verifies: VERIFIES_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+        do: DO_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+        test: TEST_COLLABORATION_ADJUDICATION_PROJECTION_TYPE,
+        'goal-verify': GOAL_VERIFY_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_verifies',
+        verifies: 'ready_for_do',
+        do: 'ready_for_test',
+        test: 'ready_for_goal_verify',
+        'goal-verify': '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',
+        'acceptedGoalVerificationRef',
+        '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 'verifies';
+    }
+    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' || ownerStage === 'verifies' ? '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', 'verifies', 'do', 'test', 'goal-verify', '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 === 'verifies' || ownerStage === 'goal-verify',
+        evidenceSurface: [...evidenceSurfaceForRuntimeStage(ownerStage), 'truthReconciliation projection']
+    });
+}
+function truthReconciliationCommand(branch, ownerStage) {
+    if (ownerStage === 'do') {
+        return `sdd do task <task_id> --branch ${branch}`;
+    }
+    return stageCloseCommandForRuntimeStage(branch, ownerStage);
+}
+function stageCloseCommandForRuntimeStage(branch, stage) {
+    if (stage === 'verifies') {
+        return `sdd tasks close --branch ${branch} --target verifies --compact-json`;
+    }
+    if (stage === 'goal-verify') {
+        return `sdd test close --branch ${branch} --target goal-verify --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 context.branchSource === 'git_branch' ? '/sdd:spec' : `/sdd:spec --branch ${context.rawBranch}`;
+        return workflowNextIntent('spec', 'start_spec', `sdd spec --branch ${context.partition}`, 'Start the spec stage before planning or task execution.', null);
+    }
+    const blockingGap = gaps.find((gap) => gap.severity === 'blocking');
+    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('test', '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 (gaps.some((gap) => gap.severity === 'blocking')) {
-        return `sdd tasks gaps --branch ${context.partition}`;
+    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', validationUnitCommand(context.partition, validationUnitIdForTask(strictTask)), 'Validate this verify.md validation unit before more implementation proceeds.', null);
+    }
+    const readyBoundary = readyValidationBoundary(model, runtimeByTask);
+    if (readyBoundary?.kind === 'batch') {
+        return workflowNextIntent('test', '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', validationUnitCommand(context.partition, readyBoundary.id), `Validate accumulated implementation evidence for validation unit ${readyBoundary.id}.`, null);
+    }
+    if (readiness.readyForShip) {
+        if (goalVerificationPassedForShip(model, runtimeByTask)) {
+            return workflowNextIntent('ship', 'ship_readiness', `sdd ship close --branch ${context.partition} --compact-json`, 'Goal verification passed; close ship readiness with ship-stage evidence.', null);
+        }
+        return workflowNextIntent('test', 'run_goal_verify', stageCloseCommandForRuntimeStage(context.partition, 'goal-verify'), 'Close goal verification inside the /sdd:test bundle and compute truthAlignment before ship readiness can run.', null, {
+            targetRuntimeStage: 'goal-verify',
+            resumeMode: 'resume',
+            canAutoAdvanceWithinBundle: true,
+            evidenceSurface: ['.sdd/runs/<branch>/goal-verify/*.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);
     }
     const dependencyBlocker = dependencyBlockers[0];
     if (dependencyBlocker) {
-        return `sdd tasks inspect ${dependencyBlocker.dependencyId} --branch ${context.partition}`;
-    }
-    if (latestRun?.syncBack.status === 'proposed' && latestRun.currentTask) {
-        return `sdd sync-back inspect --branch ${context.partition} --task ${latestRun.currentTask}`;
+        return workflowNextIntent('tasks', 'inspect_dependency', `sdd tasks inspect ${dependencyBlocker.dependencyId} --branch ${context.partition}`, 'Inspect the dependency task before continuing this workflow.', dependencyBlocker.reason);
     }
     const pendingTask = model.tasks.find((task) => task.status === 'pending');
-    return pendingTask ? `sdd tasks inspect ${pendingTask.id} --branch ${context.partition}` : `sdd tasks list --branch ${context.partition}`;
+    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', 'list_tasks', `sdd tasks list --branch ${context.partition}`, 'Inspect task state and decide whether to continue or ship.', null);
+}
+export function latestRuntimeTaskStates(selections, states) {
+    const stateByRunId = new Map(states.map((state) => [state.runId, state]));
+    const result = new Map();
+    for (const selection of selections) {
+        const selected = selection.selected;
+        if (!selected) {
+            continue;
+        }
+        const taskState = stateByRunId.get(selected.runId)?.tasks[selected.taskId];
+        if (taskState) {
+            result.set(selected.taskId, taskState);
+        }
+    }
+    return result;
+}
+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();
+    for (const task of model.tasks) {
+        if (task.validationTiming === 'batch_end' && task.validationBatch) {
+            batchGroups.set(task.validationBatch, [...(batchGroups.get(task.validationBatch) ?? []), task]);
+        }
+        if (task.validationTiming === 'wave_end') {
+            const id = validationUnitIdForTask(task);
+            waveGroups.set(id, [...(waveGroups.get(id) ?? []), task]);
+        }
+    }
+    for (const [id, tasks] of batchGroups) {
+        if (validationBoundaryReady(tasks, runtimeByTask)) {
+            return { kind: 'batch', id };
+        }
+    }
+    for (const [id, tasks] of waveGroups) {
+        if (validationBoundaryReady(tasks, runtimeByTask)) {
+            return { kind: 'wave', id };
+        }
+    }
+    return null;
+}
+function validationBoundaryReady(tasks, runtimeByTask) {
+    return tasks.every((task) => runtimeTaskImplemented(runtimeByTask.get(task.id)))
+        && tasks.some((task) => runtimeByTask.get(task.id)?.verificationStatus !== 'pass');
+}
+function runtimeTaskImplemented(runtime) {
+    return runtime?.implementationStatus === 'implemented' || runtime?.status === 'implemented_pending_validation' || runtime?.status === 'implemented_verified';
+}
+function latestEligibleRunReadyForShip(run) {
+    return run.runStatus === 'completed' && run.validationStatus === 'pass';
+}
+function goalVerificationPassedForShip(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 test ${validationUnitId} --branch ${branch}`;
+}
+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: bundle,
+        bundle,
+        targetRuntimeStage,
+        resumeMode,
+        intent,
+        canonicalCommand,
+        displayCommand,
+        commandSemantics: commandSemanticsForTarget(bundle, targetRuntimeStage, canonicalCommand),
+        evidenceRequirement,
+        blockingReason,
+        canAutoAdvanceWithinBundle,
+        autoAdvanceTo,
+        stopReasons,
+        evidenceSurface,
+        commandBundle,
+        hostProjections: hostCommandProjections(commandBundle)
+    };
+}
+export function commandBundleForRuntimeStage(stage) {
+    if (stage === 'verifies') {
+        return 'tasks';
+    }
+    if (stage === 'goal-verify') {
+        return 'test';
+    }
+    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 === 'verifies' || value === 'do' || value === 'test' || value === 'goal-verify' || value === 'ship';
+}
+function defaultResumeMode(intent, targetRuntimeStage) {
+    if (intent === 'repair_failure') {
+        return 'repair';
+    }
+    if (intent === 'run_goal_verify' || targetRuntimeStage === 'verifies' || targetRuntimeStage === 'goal-verify') {
+        return 'resume';
+    }
+    return 'start';
+}
+function commandSemanticsForTarget(bundle, targetRuntimeStage, canonicalCommand) {
+    if (/^sdd\s+status\b/.test(canonicalCommand)) {
+        return 'inspection_navigation';
+    }
+    return bundle === 'do' || bundle === 'test' || bundle === 'ship' || /\sclose\b/.test(canonicalCommand) || targetRuntimeStage === 'verifies' || targetRuntimeStage === 'goal-verify'
+        ? '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', '.sdd/runs/<branch>/tasks/*.md'],
+        verifies: ['specs/<branch>/verify.md', '.sdd/runs/<branch>/verifies/*.md'],
+        do: ['.sdd/runs/<branch>/do/*.md'],
+        test: ['.sdd/runs/<branch>/test/*.md'],
+        'goal-verify': ['.sdd/runs/<branch>/goal-verify/*.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(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.'
+        },
+        {
+            host: 'codex',
+            status: 'future',
+            entry: null,
+            projectionSurfaces: ['config.toml profile', 'AGENTS.md instruction surface', 'approval_policy', 'sandbox_mode'],
+            permissionProjection: 'Codex approval and sandbox controls can project execution policy; custom command/skill projection is not marked active without stronger evidence.',
+            reason: 'Codex exposes approval, sandbox, AGENTS.md, and built-in slash surfaces, but project custom workflow command semantics stay future until validated.'
+        },
+        {
+            host: 'opencode',
+            status: 'active',
+            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(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 || !isSddStage(command)) {
+        return `/sdd ${tokens.join(' ')}`;
+    }
+    const target = commandBundle.targetRuntimeStage === commandBundle.bundle ? '' : ` target=${commandBundle.targetRuntimeStage}`;
+    const tailTokens = stripTargetOption(rest);
+    const head = separator === ':' ? `${prefix}${commandBundle.bundle}` : `${prefix}${commandBundle.bundle}`;
+    return `${head}${target}${tailTokens.length > 0 ? ` ${tailTokens.join(' ')}` : ''}`;
+}
+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 {
@@ -115,9 +742,15 @@ function projectWorkflowStateProjection(resolution) {
         taskCounts: resolution.taskCounts,
         latestRun: resolution.latestRun,
         latestRunsByTask: resolution.latestRunsByTask,
+        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
     };
 }