vgxness 1.9.2 → 1.9.3

package/dist/resume/product-resume.js

@@ -0,0 +1,166 @@
+import { basename, resolve } from 'node:path';
+const candidateLimit = 5;
+const baseSafety = [
+    'Read-only resume cockpit: does not execute providers, retry operations, edit files, write provider config, create sandboxes, or create worktrees.',
+    'This command only helps inspect interrupted work; any continuation remains an explicit human decision.',
+];
+export function buildProductResume(input) {
+    const initialProject = resolveProject(input);
+    if (input.runId === undefined) {
+        return buildOrientationResume(input, initialProject);
+    }
+    if (input.databaseError !== undefined) {
+        return blockedResume({
+            project: initialProject,
+            runId: input.runId,
+            blocker: `Unable to read local memory store${input.databasePath === undefined ? '' : ` at ${input.databasePath}`}: ${input.databaseError}`,
+            why: 'Run inspection requires a readable local memory store.',
+            command: `vgxness resume --project ${initialProject.value} --run-id ${input.runId} --db <path>`,
+            safety: baseSafety,
+        });
+    }
+    if (input.runs?.getRunOperatorResumePlan === undefined) {
+        return blockedResume({
+            project: initialProject,
+            runId: input.runId,
+            blocker: 'Run resume inspection service is not available for this request.',
+            why: 'Use the installed CLI or provide a readable local memory store.',
+            command: `vgxness resume --project ${initialProject.value} --run-id ${input.runId}`,
+            safety: baseSafety,
+        });
+    }
+    const inspected = input.runs.getRunOperatorResumePlan(input.runId);
+    if (!inspected.ok) {
+        return blockedResume({
+            project: initialProject,
+            runId: input.runId,
+            blocker: inspected.error.message,
+            why: 'VGXNESS could not find or inspect the requested run.',
+            command: `vgxness runs list --project ${initialProject.value}`,
+            safety: baseSafety,
+        });
+    }
+    return fromRunOperatorResumePlan(inspected.value, initialProject, input.databasePath !== undefined);
+}
+function buildOrientationResume(input, project) {
+    const dbHint = input.databasePath === undefined ? '' : ` --db ${input.databasePath}`;
+    const command = `vgxness runs list --project ${project.value} --status failed${dbHint}`;
+    const manualNextCommands = [
+        `vgxness runs list --project ${project.value} --status failed${dbHint}`,
+        `vgxness runs list --project ${project.value} --status blocked${dbHint}`,
+        `vgxness runs list --project ${project.value} --status needs-human${dbHint}`,
+        `vgxness resume --project ${project.value} --run-id <id>${dbHint}`,
+    ];
+    if (input.databaseError !== undefined) {
+        return {
+            version: 1,
+            kind: 'product-resume',
+            mode: 'orientation',
+            project,
+            resumable: false,
+            resume: ['Find an interrupted run, then inspect it before deciding whether to continue manually.'],
+            why: ['No --run-id was provided, so VGXNESS cannot inspect checkpoint, approval, or blocker state for a selected run yet.'],
+            blockers: [`Unable to read local memory store${input.databasePath === undefined ? '' : ` at ${input.databasePath}`}: ${input.databaseError}`],
+            command,
+            manualNextCommands,
+            safety: baseSafety,
+            candidateRuns: [],
+        };
+    }
+    const listed = input.runs?.listRecentInterruptedRuns?.({ project: project.value, limit: candidateLimit });
+    if (listed !== undefined && !listed.ok) {
+        return {
+            version: 1,
+            kind: 'product-resume',
+            mode: 'orientation',
+            project,
+            resumable: false,
+            resume: ['Find an interrupted run, then inspect it before deciding whether to continue manually.'],
+            why: ['No --run-id was provided, so VGXNESS cannot inspect checkpoint, approval, or blocker state for a selected run yet.'],
+            blockers: [listed.error.message],
+            command,
+            manualNextCommands,
+            safety: baseSafety,
+            candidateRuns: [],
+        };
+    }
+    const candidateRuns = (listed?.value ?? []).map((candidate) => ({
+        ...candidate,
+        ...(candidate.userIntent === undefined ? {} : { userIntent: shorten(candidate.userIntent, 72) }),
+        command: `vgxness resume --project ${project.value} --run-id ${candidate.runId}${dbHint}`,
+    }));
+    const why = listed === undefined
+        ? ['No --run-id was provided, so VGXNESS cannot inspect checkpoint, approval, or blocker state for a selected run yet.']
+        : ['No --run-id was provided, so VGXNESS is showing recent failed, blocked, or needs-human runs for this project.'];
+    return {
+        version: 1,
+        kind: 'product-resume',
+        mode: 'orientation',
+        project,
+        resumable: false,
+        resume: candidateRuns.length === 0
+            ? ['Find an interrupted run, then inspect it before deciding whether to continue manually.']
+            : ['Recent interrupted runs were found. Inspect one before deciding whether to continue manually.'],
+        why,
+        blockers: [],
+        command,
+        manualNextCommands,
+        safety: [listed === undefined ? 'Did not open the local memory store because no project-specific run lookup was requested.' : 'Opened the local memory store read-only to list recent interrupted runs.', ...baseSafety],
+        candidateRuns,
+    };
+}
+function resolveProject(input) {
+    if (input.project !== undefined && input.project.trim().length > 0)
+        return { value: input.project.trim(), source: 'flag' };
+    const directoryName = basename(resolve(input.cwd));
+    return { value: directoryName.length > 0 ? directoryName : 'unknown-project', source: 'cwd' };
+}
+function fromRunOperatorResumePlan(inspect, fallbackProject, includeDbHint) {
+    const project = { value: inspect.run.project || fallbackProject.value, source: 'run' };
+    const blockerLines = inspect.blockers.map((blocker) => (blocker.relatedId === undefined ? blocker.message : `${blocker.message} (${blocker.relatedId})`));
+    const latestCheckpoint = inspect.latestCheckpoint === null ? 'none' : `${inspect.latestCheckpoint.label} (${inspect.latestCheckpoint.id})`;
+    const dbHint = includeDbHint ? ' --db <path>' : '';
+    return {
+        version: 1,
+        kind: 'product-resume',
+        mode: 'inspect',
+        project,
+        runId: inspect.run.id,
+        resumable: inspect.resumePlan.resumable,
+        resume: [inspect.resumePlan.recommendedAction],
+        why: [
+            `Run: ${inspect.run.id}`,
+            `Status: ${inspect.run.status}`,
+            `Workflow: ${inspect.run.workflow} / ${inspect.run.phase}`,
+            `Latest checkpoint: ${latestCheckpoint}`,
+            inspect.debug.summary,
+        ],
+        blockers: blockerLines,
+        command: `vgxness resume --project ${project.value} --run-id ${inspect.run.id}${dbHint}`,
+        manualNextCommands: inspect.manualNextCommands,
+        safety: baseSafety,
+        candidateRuns: [],
+        inspect,
+    };
+}
+function blockedResume(input) {
+    return {
+        version: 1,
+        kind: 'product-resume',
+        mode: 'inspect',
+        project: input.project,
+        runId: input.runId,
+        resumable: false,
+        resume: ['Resolve the blocker, then inspect the run again before deciding whether to continue manually.'],
+        why: [`Run: ${input.runId}`, input.why],
+        blockers: [input.blocker],
+        command: input.command,
+        manualNextCommands: [input.command],
+        safety: input.safety,
+        candidateRuns: [],
+    };
+}
+function shorten(value, maxLength) {
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    return normalized.length <= maxLength ? normalized : `${normalized.slice(0, maxLength - 3)}...`;
+}

package/dist/runs/repositories/runs.js

@@ -70,13 +70,24 @@ export class RunRepository {
                 where.push('status=@status');
                 parameters.status = filters.status;
             }
+            if (filters.statuses !== undefined && filters.statuses.length > 0) {
+                const statusPlaceholders = filters.statuses.map((_, index) => `@status${index}`);
+                where.push(`status IN (${statusPlaceholders.join(', ')})`);
+                for (const [index, status] of filters.statuses.entries())
+                    parameters[`status${index}`] = status;
+            }
+            const limitClause = filters.limit === undefined ? '' : 'LIMIT @limit';
+            const queryParameters = { ...parameters };
+            if (filters.limit !== undefined)
+                queryParameters.limit = filters.limit;
             const rows = this.db.connection
                 .prepare(`
         SELECT * FROM runs
         ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
         ORDER BY created_at DESC
+        ${limitClause}
       `)
-                .all(parameters);
+                .all(queryParameters);
             return ok(rows.map(mapRun));
         }
         catch (cause) {

package/dist/runs/run-service.js

@@ -1,5 +1,6 @@
 import { evaluatePermission } from '../permissions/policy-evaluator.js';
 import { isRiskyPermissionCategory } from '../permissions/schema.js';
+import { normalizeSddPhaseInput } from '../sdd/schema.js';
 import { planExecutionIsolation } from './execution-planning.js';
 import { evaluateOperationRetry as evaluateOperationRetryPolicy } from './operation-retry.js';
 import { RunRepository, } from './repositories/runs.js';
@@ -28,7 +29,7 @@ export class RunService {
         this.runs = new RunRepository(database);
     }
     createRun(input) {
-        return this.runs.create(input);
+        return this.runs.create({ ...input, phase: canonicalRunPhase(input.workflow, input.phase) ?? input.phase });
     }
     getRun(id) {
         return this.runs.getDetails(id);
@@ -44,6 +45,53 @@ export class RunService {
     listRuns(filters = {}) {
         return this.runs.list(filters);
     }
+    listRecentInterruptedRuns(input) {
+        const runs = this.runs.list({ project: input.project, statuses: ['failed', 'blocked', 'needs-human'], limit: input.limit ?? 5 });
+        if (!runs.ok)
+            return runs;
+        const candidates = [];
+        for (const run of runs.value) {
+            const details = this.runs.getDetails(run.id);
+            if (!details.ok)
+                return details;
+            const latestCheckpoint = details.value.checkpoints.at(-1);
+            const userIntent = details.value.userIntent.trim();
+            candidates.push({
+                runId: details.value.id,
+                status: details.value.status,
+                workflow: details.value.workflow,
+                phase: details.value.phase,
+                ...(userIntent.length === 0 ? {} : { userIntent }),
+                ...(latestCheckpoint === undefined ? {} : { latestCheckpointLabel: latestCheckpoint.label }),
+            });
+        }
+        return { ok: true, value: candidates };
+    }
+    findRelatedInterruptedSddRun(input) {
+        const runs = this.runs.list({ project: input.project, statuses: ['failed', 'blocked', 'needs-human'], limit: input.limit ?? 25 });
+        if (!runs.ok)
+            return runs;
+        for (const run of runs.value) {
+            const details = this.runs.getDetails(run.id);
+            if (!details.ok)
+                return details;
+            const hasMatchingCheckpoint = details.value.checkpoints.some((checkpoint) => checkpointHasChangeId(checkpoint.state, input.change));
+            if (!hasMatchingCheckpoint)
+                continue;
+            const latestCheckpoint = details.value.checkpoints.at(-1);
+            return {
+                ok: true,
+                value: {
+                    runId: details.value.id,
+                    status: details.value.status,
+                    workflow: details.value.workflow,
+                    phase: details.value.phase,
+                    ...(latestCheckpoint === undefined ? {} : { latestCheckpointLabel: latestCheckpoint.label }),
+                },
+            };
+        }
+        return { ok: true, value: undefined };
+    }
     appendEvent(input) {
         return this.runs.appendEvent(input);
     }
@@ -695,10 +743,11 @@ export class RunService {
         const run = this.runs.getById(input.runId);
         if (!run.ok)
             return { ok: false, error: run.error };
-        const phase = input.phase ?? canonicalRunPhase(run.value.phase);
+        const workflow = input.workflow ?? run.value.workflow;
+        const phase = canonicalRunPhase(workflow, input.phase) ?? canonicalRunPhase(run.value.workflow, run.value.phase);
         const merged = {
             ...input,
-            workflow: input.workflow ?? run.value.workflow,
+            workflow,
             ...(phase === undefined ? {} : { phase }),
             agentId: input.agentId ?? input.agent?.id ?? run.value.selectedAgentId,
         };
@@ -799,6 +848,9 @@ export class RunService {
         return { ok: true, value: resolved[0] };
     }
 }
+function checkpointHasChangeId(state, change) {
+    return typeof state === 'object' && state !== null && !Array.isArray(state) && state.changeId === change;
+}
 function preflightOutcome(decision) {
     if (decision.decision === 'allow')
         return 'allowed';
@@ -883,10 +935,15 @@ function resumeGateManualNextCommands(approval, details, operation) {
         commands.push(`Review operation manually: ${operation.category} ${operation.operation}`);
     return commands;
 }
-function canonicalRunPhase(phase) {
+function canonicalRunPhase(workflow, phase) {
     if (phase === undefined || phase.trim().length === 0)
         return undefined;
-    return phase === 'apply' ? 'apply-progress' : phase;
+    if (!isSddWorkflow(workflow))
+        return phase;
+    return normalizeSddPhaseInput(phase) ?? phase;
+}
+function isSddWorkflow(workflow) {
+    return workflow?.trim().toLowerCase() === 'sdd';
 }
 function operationMetadata(input) {
     const metadata = { category: input.category, name: input.operation };

package/dist/sdd/schema.js

@@ -98,6 +98,14 @@ export const sddPrerequisites = {
 export function isSddPhase(value) {
     return sddPhases.includes(value);
 }
+export function normalizeSddPhaseInput(value) {
+    const normalized = value.trim();
+    if (normalized === 'apply')
+        return 'apply-progress';
+    if (isSddPhase(normalized))
+        return normalized;
+    return undefined;
+}
 export function sddTopicKey(change, phase) {
     return `sdd/${change}/${phase}`;
 }

package/dist/sdd/sdd-continuation-plan.js

@@ -0,0 +1,81 @@
+export function sddContinuationPlanFrom(input) {
+    const nextPhase = input.next.nextPhase;
+    const dbFlag = continuationDbFlag(input.explicitDatabasePath);
+    const inspectCommand = `vgxness sdd cockpit --project ${input.project} --change ${input.next.change} --json${dbFlag}`;
+    const suggestedCommand = suggestedContinuationCommand(input.project, input.next, inspectCommand, dbFlag);
+    const blockerGuidance = input.next.blockerGuidance ?? [];
+    const blockerActions = blockerGuidance.map((blocker) => continuationBlockerAction(input.project, input.next.change, input.next.nextPhase, blocker, dbFlag));
+    const hasDraftRunAction = blockerActions.some((action) => action.draftRunCommand !== undefined);
+    const relatedRunContext = relatedRunContextView(input.project, input.relatedRunContext, dbFlag);
+    return {
+        kind: 'sdd-continuation-plan',
+        project: input.project,
+        change: input.next.change,
+        status: input.next.status,
+        ...(nextPhase === undefined ? {} : { nextPhase }),
+        ...(input.cockpit.actionablePhase === undefined ? {} : { actionablePhase: input.cockpit.actionablePhase }),
+        recommendedAction: input.cockpit.recommendedAction,
+        reason: input.next.reason,
+        suggestedCommand,
+        inspectCommand,
+        blockerActions,
+        ...(relatedRunContext === undefined ? {} : { relatedRunContext }),
+        ...(input.explicitDatabasePath === undefined ? {} : { explicitDatabasePath: input.explicitDatabasePath }),
+        safety: [
+            'Read-only planner: this command does not execute providers or mutate SDD artifacts, runs, provider config, or openspec/ files.',
+            'Human acceptance remains explicit; artifact presence is not treated as acceptance.',
+            ...(hasDraftRunAction ? [draftRunWarning()] : []),
+            'No openspec/ files are created or written.',
+        ],
+    };
+}
+function relatedRunContextView(project, relatedRunContext, dbFlag) {
+    if (relatedRunContext === undefined)
+        return undefined;
+    return {
+        ...relatedRunContext,
+        recommendation: 'Related interrupted run found by checkpoint changeId; inspect or resume it before starting duplicate SDD work. Advisory only.',
+        resumeCommand: `vgxness resume --project ${project} --run-id ${relatedRunContext.runId}${dbFlag}`,
+    };
+}
+function suggestedContinuationCommand(project, next, fallbackInspectCommand, dbFlag) {
+    if (next.status === 'runnable' && next.nextPhase !== undefined)
+        return runPhaseCommand(project, next.change, next.nextPhase, dbFlag);
+    return fallbackInspectCommand;
+}
+function continuationBlockerAction(project, change, blockedPhase, blocker, dbFlag) {
+    const draftRunCommand = blocker.reason === 'draft' && isDraftRunPlanningPhase(blockedPhase) ? draftRunPhaseCommand(project, change, blockedPhase, dbFlag) : undefined;
+    return {
+        phase: blocker.phase,
+        topicKey: blocker.topicKey,
+        reason: blocker.reason,
+        action: blocker.action,
+        command: blockerCommand(project, change, blocker, dbFlag),
+        ...(draftRunCommand === undefined ? {} : { draftRunCommand, warning: draftRunWarning() }),
+        ...(blocker.artifactId === undefined ? {} : { artifactId: blocker.artifactId }),
+    };
+}
+function blockerCommand(project, change, blocker, dbFlag) {
+    if (blocker.reason === 'missing')
+        return runPhaseCommand(project, change, blocker.phase, dbFlag);
+    if (blocker.reason === 'draft' || blocker.reason === 'legacy')
+        return `vgxness sdd accept-artifact --project ${project} --change ${change} --phase ${blocker.phase} --actor <human-id>${dbFlag}`;
+    if (blocker.reason === 'rejected')
+        return `vgxness sdd reopen-artifact --project ${project} --change ${change} --phase ${blocker.phase} --actor <human-id>${dbFlag}`;
+    return `vgxness sdd get-artifact --project ${project} --change ${change} --phase ${blocker.phase} --json${dbFlag}`;
+}
+function runPhaseCommand(project, change, phase, dbFlag) {
+    return `vgxness code sdd ${change} ${phase} --project ${project} --save-artifact${dbFlag}`;
+}
+function draftRunPhaseCommand(project, change, phase, dbFlag) {
+    return `vgxness code sdd ${change} ${phase} --project ${project} --draft-run --save-artifact${dbFlag}`;
+}
+function isDraftRunPlanningPhase(phase) {
+    return phase === 'explore' || phase === 'proposal' || phase === 'spec' || phase === 'design' || phase === 'tasks';
+}
+function draftRunWarning() {
+    return 'Draft-run is planning-only; human acceptance is still required; apply-progress remains gated.';
+}
+function continuationDbFlag(explicitDatabasePath) {
+    return explicitDatabasePath === undefined ? '' : ` --db ${explicitDatabasePath}`;
+}

package/dist/sdd/sdd-workflow-service.js

@@ -1,5 +1,5 @@
 import { summarizePayloadContent } from '../payload/payload-summary.js';
-import { isSddPhase, normalizeSddArtifact, sddPhases, sddPrerequisites, sddTopicKey, } from './schema.js';
+import { normalizeSddArtifact, normalizeSddPhaseInput, sddPhases, sddPrerequisites, sddTopicKey, } from './schema.js';
 const defaultContext = { actor: 'sdd-workflow-service' };
 const validChangePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 function readAutoAdvanceFromEnv() {
@@ -103,7 +103,7 @@ export class SddWorkflowService {
         const artifacts = cockpitPhases.map((phase) => phase.artifact).filter((artifact) => artifact !== undefined);
         const aggregateBlockers = dedupeCockpitBlockers([
             ...cockpitPhases.flatMap((phase) => phase.blockers),
-            ...next.missingArtifactTopicKeys.map((topicKey) => blockerFromTopicKey(validated.value.change, topicKey)),
+            ...(next.missingPrerequisiteTopicKeys ?? []).map((topicKey) => blockerFromTopicKey(validated.value.change, topicKey)),
             ...(next.blockedPrerequisites ?? []).map((blocker) => ({
                 kind: 'readiness',
                 phase: blocker.phase,
@@ -314,9 +314,10 @@ export class SddWorkflowService {
         const validated = validateProjectAndChange(input.project, input.change);
         if (!validated.ok)
             return validated;
-        if (!isSddPhase(input.phase))
+        const phase = normalizeSddPhaseInput(input.phase);
+        if (phase === undefined)
             return validationFailure(`Unknown SDD phase: ${input.phase}`);
-        return { ok: true, value: { ...validated.value, phase: input.phase } };
+        return { ok: true, value: { ...validated.value, phase } };
     }
     getPhaseStatuses(project, change) {
         const snapshot = this.loadPhaseSnapshot(project, change);
@@ -367,9 +368,11 @@ export function nextDecisionFromStatuses(change, phases, options = {}) {
             status: 'blocked',
             nextPhase: blockedPresentPhase.phase,
             missingArtifactTopicKeys: readiness.missingArtifactTopicKeys,
+            missingPrerequisiteTopicKeys: readiness.missingPrerequisiteTopicKeys ?? [],
             blockedPrerequisites: blockers,
+            blockerGuidance: readiness.blockerGuidance ?? [],
             reason: `${blockedPresentPhase.phase} is blocked by prerequisite artifacts that are not accepted: ${formatBlockers(blockers)}.`,
-            recommendedAction: `Create, restore, or accept ${readiness.missingArtifactTopicKeys.join(', ')} before continuing.`,
+            recommendedAction: blockedRecommendedAction(readiness, 'continuing'),
         };
     }
     const nextMissingPhase = phases.find((status) => !status.present)?.phase;
@@ -381,6 +384,7 @@ export function nextDecisionFromStatuses(change, phases, options = {}) {
                 status: 'blocked',
                 nextPhase: firstUnacceptedPhase.phase,
                 missingArtifactTopicKeys: [firstUnacceptedPhase.topicKey],
+                missingPrerequisiteTopicKeys: [],
                 blockedPrerequisites: [
                     {
                         phase: firstUnacceptedPhase.phase,
@@ -389,8 +393,9 @@ export function nextDecisionFromStatuses(change, phases, options = {}) {
                         ...(firstUnacceptedPhase.artifactId === undefined ? {} : { artifactId: firstUnacceptedPhase.artifactId }),
                     },
                 ],
+                blockerGuidance: [blockerGuidanceForPhaseStatus(firstUnacceptedPhase)],
                 reason: `${firstUnacceptedPhase.phase} is present but ${firstUnacceptedPhase.state ?? 'draft'}; accepted governance status is required before the change is complete.`,
-                recommendedAction: `Accept or replace ${firstUnacceptedPhase.topicKey} before archiving this SDD change.`,
+                recommendedAction: `${blockerActionForStatus(firstUnacceptedPhase)} before archiving this SDD change.`,
             };
         }
         return {
@@ -410,9 +415,11 @@ export function nextDecisionFromStatuses(change, phases, options = {}) {
             status: 'blocked',
             nextPhase: nextMissingPhase,
             missingArtifactTopicKeys: readiness.missingArtifactTopicKeys,
+            missingPrerequisiteTopicKeys: readiness.missingPrerequisiteTopicKeys ?? [],
             blockedPrerequisites: blockers,
+            blockerGuidance: readiness.blockerGuidance ?? [],
             reason: `${nextMissingPhase} is blocked by prerequisite artifacts that are not accepted: ${formatBlockers(blockers)}.`,
-            recommendedAction: `Create, restore, or accept ${readiness.missingArtifactTopicKeys.join(', ')} before running ${nextMissingPhase}.`,
+            recommendedAction: blockedRecommendedAction(readiness, `running ${nextMissingPhase}`),
         };
     }
     return {
@@ -439,7 +446,9 @@ function statusFromPhases(change, phases, options = {}) {
 function getReadinessFromStatuses(change, phase, phases, options = {}) {
     const satisfiedPrerequisites = [];
     const missingArtifactTopicKeys = [];
+    const missingPrerequisiteTopicKeys = [];
     const blockedPrerequisites = [];
+    const blockerGuidance = [];
     const useAutoAdvance = options.autoAdvance === true;
     for (const prerequisite of sddPrerequisites[phase]) {
         const status = phases.find((candidate) => candidate.phase === prerequisite);
@@ -449,19 +458,26 @@ function getReadinessFromStatuses(change, phase, phases, options = {}) {
             continue;
         }
         const topicKey = status?.topicKey ?? sddTopicKey(change, prerequisite);
+        const reason = status === undefined ? 'missing' : blockerReasonForStatus(status);
         missingArtifactTopicKeys.push(topicKey);
-        blockedPrerequisites.push({
+        if (reason === 'missing')
+            missingPrerequisiteTopicKeys.push(topicKey);
+        const blocker = {
             phase: prerequisite,
             topicKey,
-            reason: status === undefined ? 'missing' : blockerReasonForStatus(status),
+            reason,
             ...(status?.artifactId === undefined ? {} : { artifactId: status.artifactId }),
-        });
+        };
+        blockedPrerequisites.push(blocker);
+        blockerGuidance.push(blockerGuidanceForBlocker(blocker, phase));
     }
     return {
         ready: blockedPrerequisites.length === 0,
         satisfiedPrerequisites,
         missingArtifactTopicKeys,
+        missingPrerequisiteTopicKeys,
         blockedPrerequisites,
+        blockerGuidance,
     };
 }
 function compactArtifactProjection(artifact, change, phase, readiness) {
@@ -518,13 +534,20 @@ function compactGovernanceArtifact(artifact) {
 function cockpitBlockersForPhase(status, readiness) {
     const blockers = [];
     if (!status.present)
-        blockers.push({ kind: 'missing-topic-key', phase: status.phase, topicKey: status.topicKey, reason: 'Canonical SDD artifact is missing.' });
+        blockers.push({
+            kind: 'missing-topic-key',
+            phase: status.phase,
+            topicKey: status.topicKey,
+            reason: 'Canonical SDD artifact is missing.',
+            action: blockerActionForBlocker({ phase: status.phase, topicKey: status.topicKey, reason: 'missing' }),
+        });
     if (status.present && status.accepted !== true)
         blockers.push({
             kind: 'unaccepted-phase',
             phase: status.phase,
             topicKey: status.topicKey,
             reason: `${status.phase} is ${status.state ?? 'draft'}; explicit human acceptance is required.`,
+            action: blockerActionForStatus(status),
             ...(status.artifactId === undefined ? {} : { artifactId: status.artifactId }),
         });
     if (status.legacy === true)
@@ -533,6 +556,7 @@ function cockpitBlockersForPhase(status, readiness) {
             phase: status.phase,
             topicKey: status.topicKey,
             reason: 'Artifact has legacy or missing governance metadata and is treated as not accepted.',
+            action: blockerActionForStatus(status),
             ...(status.artifactId === undefined ? {} : { artifactId: status.artifactId }),
         });
     for (const blocker of readiness.blockedPrerequisites ?? []) {
@@ -541,6 +565,7 @@ function cockpitBlockersForPhase(status, readiness) {
             phase: blocker.phase,
             topicKey: blocker.topicKey,
             reason: blocker.reason,
+            action: blockerActionForBlocker(blocker),
             ...(blocker.artifactId === undefined ? {} : { artifactId: blocker.artifactId }),
         });
     }
@@ -548,7 +573,13 @@ function cockpitBlockersForPhase(status, readiness) {
 }
 function blockerFromTopicKey(change, topicKey) {
     const phase = phaseFromTopicKey(change, topicKey);
-    return { kind: 'missing-topic-key', phase, topicKey, reason: 'Required SDD topic key is missing or not accepted.' };
+    return {
+        kind: 'missing-topic-key',
+        phase,
+        topicKey,
+        reason: 'Required SDD topic key is missing or not accepted.',
+        action: blockerActionForBlocker({ phase, topicKey, reason: 'missing' }),
+    };
 }
 function dedupeCockpitBlockers(blockers) {
     const seen = new Set();
@@ -567,16 +598,72 @@ function cockpitRecommendedAction(next, blockers) {
         return next.recommendedAction;
     const legacy = blockers.find((blocker) => blocker.kind === 'legacy-artifact');
     if (legacy !== undefined)
-        return `Review and explicitly accept or replace legacy artifact ${legacy.topicKey}.`;
+        return legacy.action ?? `Inspect and explicitly accept or replace legacy artifact ${legacy.topicKey}.`;
     const unaccepted = blockers.find((blocker) => blocker.kind === 'unaccepted-phase');
     if (unaccepted !== undefined)
-        return `Accept or replace ${unaccepted.topicKey} before continuing.`;
+        return unaccepted.action ?? `Accept or replace ${unaccepted.topicKey} before continuing.`;
     return next.recommendedAction;
 }
+function blockedRecommendedAction(readiness, context) {
+    const firstGuidance = readiness.blockerGuidance?.[0];
+    if (firstGuidance !== undefined)
+        return `${firstGuidance.action} before ${context}.`;
+    const firstBlocker = readiness.blockedPrerequisites?.[0];
+    if (firstBlocker !== undefined)
+        return `${blockerActionForBlocker(firstBlocker)} before ${context}.`;
+    return `Resolve prerequisite blockers before ${context}.`;
+}
+function blockerGuidanceForPhaseStatus(status) {
+    return blockerGuidanceForBlocker({
+        phase: status.phase,
+        topicKey: status.topicKey,
+        reason: blockerReasonForStatus(status),
+        ...(status.artifactId === undefined ? {} : { artifactId: status.artifactId }),
+    });
+}
+function blockerGuidanceForBlocker(blocker, blockedPhase) {
+    return {
+        phase: blocker.phase,
+        topicKey: blocker.topicKey,
+        reason: blocker.reason,
+        action: blockerActionForBlocker(blocker, blockedPhase),
+        ...(blocker.artifactId === undefined ? {} : { artifactId: blocker.artifactId }),
+    };
+}
+function blockerActionForStatus(status) {
+    return blockerActionForBlocker({
+        phase: status.phase,
+        topicKey: status.topicKey,
+        reason: blockerReasonForStatus(status),
+        ...(status.artifactId === undefined ? {} : { artifactId: status.artifactId }),
+    });
+}
+function blockerActionForBlocker(blocker, blockedPhase) {
+    switch (blocker.reason) {
+        case 'missing':
+            return `Run or create the ${blocker.phase} SDD phase artifact at ${blocker.topicKey}`;
+        case 'draft':
+            if (blockedPhase !== undefined && isDraftRunPlanningPhase(blockedPhase))
+                return `Accept ${blocker.topicKey} if it is ready, or intentionally continue planning ${blockedPhase} with --draft-run; draft-run is planning-only, human acceptance is still required, and apply-progress remains gated`;
+            return `Accept ${blocker.topicKey}, or continue and re-run the ${blocker.phase} phase if the draft is incomplete`;
+        case 'accepted':
+            return `Inspect ${blocker.topicKey}; it is marked accepted but still appears in blocker data`;
+        case 'legacy':
+            return `Inspect ${blocker.topicKey} and explicitly accept or replace the legacy artifact`;
+        case 'rejected':
+            return `Reopen ${blocker.topicKey} for revision, or replace it with a new accepted artifact`;
+        case 'superseded':
+            return `Use the current replacement for ${blocker.topicKey}, or create and accept a new canonical ${blocker.phase} artifact`;
+    }
+}
+function isDraftRunPlanningPhase(phase) {
+    return phase === 'explore' || phase === 'proposal' || phase === 'spec' || phase === 'design' || phase === 'tasks';
+}
 function phaseFromTopicKey(change, topicKey) {
     const suffix = topicKey.slice(`sdd/${change}/`.length);
-    if (isSddPhase(suffix))
-        return suffix;
+    const phase = normalizeSddPhaseInput(suffix);
+    if (phase !== undefined)
+        return phase;
     return 'explore';
 }
 function blockerReasonForStatus(status) {