vgxness 1.9.1 → 1.9.3

package/dist/cli/dispatcher.js

@@ -4,7 +4,8 @@ import { isWorkflowId } from '../workflows/schema.js';
 import { databasePathFor, parseArgs, requiredFlag } from './cli-flags.js';
 import { okText, usageFailure, visibleHelpText } from './cli-help.js';
 import { openCliDatabase, resultFailure } from './cli-helpers.js';
-import { runAgentCommand, runApprovalsCommand, runCodeCliCommand, runDefaultInteractiveEntrypoint, runDoctorAliasCommand, runInitCommand, runMcpDoctorCommand, runMcpInstallCommand, runMcpSetupCommand, runMemoryCommand, runMemoryImportCommand, runOpenCodeCommand, runOrchestratorCommand, runPermissionsCommand, runRunsCommand, runSddCommand, runSetupApplyCommand, runSetupLifecycleCommand, runSetupPlanCommand, runSetupRollbackCommand, runSkillCommand, runSubagentCommand, runVerificationPlanCommand, runVerificationReportCommand, runWorkflowExecuteCommand, runWorkflowPreviewCommand, runWorkflowRunCommand, } from './commands/index.js';
+import { runBootAgentSeedUpgrade } from '../agents/boot-upgrade.js';
+import { runAgentCommand, runApprovalsCommand, runCodeCliCommand, runDefaultInteractiveEntrypoint, runDoctorAliasCommand, runInitCommand, runMcpDoctorCommand, runMcpInstallCommand, runMcpSetupCommand, runMemoryCommand, runMemoryImportCommand, runOpenCodeCommand, runOrchestratorCommand, runPermissionsCommand, runProductNextCommand, runProductResumeCommand, runRunsCommand, runSddCommand, runSetupApplyCommand, runSetupLifecycleCommand, runSetupPlanCommand, runSetupRollbackCommand, runProductStatusCommand, runSkillCommand, runSubagentCommand, runVerificationPlanCommand, runVerificationReportCommand, runWorkflowExecuteCommand, runWorkflowPreviewCommand, runWorkflowRunCommand, } from './commands/index.js';
 const _promptBuffers = new WeakMap();
 const require = createRequire(import.meta.url);
 const packageJson = require('../../package.json');
@@ -16,6 +17,12 @@ export function dispatchCli(argv, environment) {
     const [area, command] = parsed.positionals;
     if (!area || area === 'help' || area === '--help' || area === '-h')
         return okText(visibleHelpText());
+    if (area === 'status')
+        return runProductStatusCommand(parsed, environment);
+    if (area === 'next')
+        return runProductNextCommand(parsed, environment);
+    if (area === 'resume')
+        return runProductResumeCommand(parsed, environment);
     if (area === 'init')
         return runSetupPlanCommand(parsed, environment);
     if (area === 'doctor')
@@ -48,6 +55,7 @@ export function dispatchCli(argv, environment) {
     const opened = openCliDatabase(databasePath);
     if (!opened.ok)
         return resultFailure(opened);
+    runBootAgentSeedUpgrade(opened.value, environment.env);
     try {
         if (isWorkflowId(area) && command === 'run')
             return runWorkflowRunCommand(area, parsed, opened.value);
@@ -190,10 +198,12 @@ function validateCommand(area, command) {
             command === 'execute' ||
             command === 'status' ||
             command === 'next' ||
+            command === 'continue' ||
             command === 'cockpit' ||
             command === 'ready' ||
             command === 'save-artifact' ||
             command === 'accept-artifact' ||
+            command === 'reopen-artifact' ||
             command === 'get-artifact' ||
             command === 'list-artifacts' ||
             command === 'export' ||

package/dist/cli/product-resume-renderer.js

@@ -0,0 +1,32 @@
+export function renderProductResume(resume) {
+    const lines = [
+        'Resume',
+        ...resume.resume.map((line) => `- ${line}`),
+        '',
+        'Why',
+        ...resume.why.map((line) => `- ${line}`),
+        '',
+        'Blockers',
+        ...(resume.blockers.length === 0 ? ['- none'] : resume.blockers.map((line) => `- ${line}`)),
+        ...(resume.candidateRuns.length === 0
+            ? []
+            : [
+                '',
+                'Candidate runs',
+                ...resume.candidateRuns.flatMap((run) => [
+                    `- ${run.runId} [${run.status}] ${run.workflow}/${run.phase}`,
+                    ...(run.userIntent === undefined ? [] : [`  Intent: ${run.userIntent}`]),
+                    `  Latest checkpoint: ${run.latestCheckpointLabel ?? 'none'}`,
+                    `  Resume command: ${run.command}`,
+                ]),
+            ]),
+        '',
+        'Command',
+        `- ${resume.command}`,
+        ...(resume.manualNextCommands.length === 0 ? [] : ['', 'Related commands', ...resume.manualNextCommands.map((line) => `- ${line}`)]),
+        '',
+        'Safety',
+        ...resume.safety.map((line) => `- ${line}`),
+    ];
+    return `${lines.join('\n')}\n`;
+}

package/dist/cli/product-status-renderer.js

@@ -0,0 +1,74 @@
+export function renderProductStatus(status) {
+    const lines = [
+        'Status',
+        ...status.status.map((line) => `- ${line}`),
+        '',
+        'Blockers',
+        ...status.blockers.map((line) => `- ${line}`),
+        '',
+        'Next',
+        ...status.next.map((line) => `- ${line}`),
+        '',
+        'Command',
+        `- ${status.command}`,
+        '',
+        ...(status.relatedRunContext === undefined ? [] : relatedRunContextLines(status.relatedRunContext, true)),
+        'Safety',
+        ...status.safety.map((line) => `- ${line}`),
+    ];
+    return `${lines.join('\n')}\n`;
+}
+export function buildProductNext(status) {
+    const blockers = status.blockers.filter((line) => line !== 'none');
+    const blocked = status.sddNextStatus === undefined ? blockers.length > 0 : status.sddNextStatus === 'blocked';
+    const visibleBlockers = blocked ? blockers : [];
+    const command = blocked ? buildBlockedNextCommand(status) : status.command;
+    return {
+        version: 1,
+        kind: 'product-next',
+        project: status.project,
+        ...(status.change === undefined ? {} : { change: status.change }),
+        blocked,
+        next: status.next,
+        why: status.status,
+        blockers: visibleBlockers,
+        command,
+        ...(status.relatedRunContext === undefined ? {} : { relatedRunContext: status.relatedRunContext }),
+        safety: status.safety,
+    };
+}
+function buildBlockedNextCommand(status) {
+    const change = status.change === undefined ? '<change>' : status.change;
+    const dbHint = status.command.includes('--db <path>') ? ' --db <path>' : '';
+    return `vgxness next --project ${status.project.value} --change ${change}${dbHint}`;
+}
+export function renderProductNext(next) {
+    const lines = [
+        'Next',
+        ...next.next.map((line) => `- ${line}`),
+        '',
+        'Why',
+        ...next.why.map((line) => `- ${line}`),
+        ...(next.blockers.length === 0 ? [] : ['', 'Blockers', ...next.blockers.map((line) => `- ${line}`)]),
+        '',
+        'Command',
+        `- ${next.command}`,
+        '',
+        ...(next.relatedRunContext === undefined ? [] : relatedRunContextLines(next.relatedRunContext, true)),
+        'Safety',
+        ...next.safety.map((line) => `- ${line}`),
+    ];
+    return `${lines.join('\n')}\n`;
+}
+function relatedRunContextLines(relatedRunContext, includeTrailingBlank) {
+    return [
+        'Related interrupted run:',
+        `- Run ID: ${relatedRunContext.runId}`,
+        `- Status: ${relatedRunContext.status}`,
+        `- Workflow/phase: ${relatedRunContext.workflow}/${relatedRunContext.phase}`,
+        `- Latest checkpoint: ${relatedRunContext.latestCheckpointLabel ?? 'none'}`,
+        `- Recommendation: ${relatedRunContext.recommendation}`,
+        `- Resume command: ${relatedRunContext.resumeCommand}`,
+        ...(includeTrailingBlank ? [''] : []),
+    ];
+}

package/dist/cli/sdd-renderer.js

@@ -1,4 +1,5 @@
-import { normalizeSddArtifact, sddPhases } from '../sdd/schema.js';
+import { normalizeSddArtifact, sddPhases, } from '../sdd/schema.js';
+export { sddContinuationPlanFrom } from '../sdd/sdd-continuation-plan.js';
 export function renderSddStatus(input) {
     const missing = input.status.phases.filter((phase) => !phase.present).map((phase) => phase.topicKey);
     const blockers = input.status.phases.filter((phase) => phase.present && phase.accepted !== true);
@@ -34,6 +35,7 @@ export function renderSddStatus(input) {
 }
 export function renderSddNext(input) {
     const blockers = input.decision.blockedPrerequisites ?? [];
+    const guidance = input.decision.blockerGuidance ?? [];
     const phase = input.decision.nextPhase ?? 'none';
     const commandGuidance = input.decision.status === 'runnable' && input.decision.nextPhase !== undefined
         ? `vgxness code sdd ${input.decision.change} ${input.decision.nextPhase} --save-artifact`
@@ -47,17 +49,70 @@ export function renderSddNext(input) {
         `Reason: ${input.decision.reason}`,
         '',
         'Blockers:',
-        ...(blockers.length === 0 ? ['- none'] : blockers.map((blocker) => `- ${blocker.phase}: ${blocker.reason} at ${blocker.topicKey}`)),
+        ...(blockers.length === 0
+            ? ['- none']
+            : blockers.map((blocker) => `- ${blocker.phase}: ${blocker.reason} at ${blocker.topicKey}${blocker.action === undefined ? '' : `; action=${blocker.action}`}`)),
         '',
         'Missing topic keys:',
         ...(input.decision.missingArtifactTopicKeys.length === 0 ? ['- none'] : input.decision.missingArtifactTopicKeys.map((topicKey) => `- ${topicKey}`)),
         '',
+        'Missing prerequisite topic keys:',
+        ...((input.decision.missingPrerequisiteTopicKeys ?? []).length === 0
+            ? ['- none']
+            : (input.decision.missingPrerequisiteTopicKeys ?? []).map((topicKey) => `- ${topicKey}`)),
+        '',
+        'Next actions:',
+        ...(guidance.length === 0 ? ['- none'] : guidance.map((item) => `- ${item.phase}: ${item.action}`)),
+        '',
         `Recommended action: ${input.decision.recommendedAction}`,
         `Command: ${commandGuidance}`,
         `JSON: vgxness sdd next --project ${input.project} --change ${input.decision.change} --json`,
     ];
     return `${lines.join('\n')}\n`;
 }
+export function renderSddContinuationPlan(plan) {
+    const lines = [
+        'SDD Continue (read-only)',
+        `Project: ${plan.project}`,
+        `Change: ${plan.change}`,
+        `Status: ${plan.status}`,
+        `Next phase: ${plan.nextPhase ?? 'none'}`,
+        `Actionable phase: ${plan.actionablePhase ?? 'none'}`,
+        `Reason: ${plan.reason}`,
+        '',
+        'Recommended plan:',
+        `- ${plan.recommendedAction}`,
+        `- Suggested command: ${plan.suggestedCommand}`,
+        `- Inspect command: ${plan.inspectCommand}`,
+        '',
+        'Blocker-specific next actions:',
+        ...(plan.blockerActions.length === 0
+            ? ['- none']
+            : plan.blockerActions.map((item) => {
+                const draftRun = item.draftRunCommand === undefined ? '' : `; draftRunCommand=${item.draftRunCommand}`;
+                const warning = item.warning === undefined ? '' : `; warning=${item.warning}`;
+                return `- ${item.phase}: ${item.action}; command=${item.command}${draftRun}${warning}`;
+            })),
+        '',
+        ...(plan.relatedRunContext === undefined
+            ? []
+            : [
+                'Related interrupted run:',
+                `- Run ID: ${plan.relatedRunContext.runId}`,
+                `- Status: ${plan.relatedRunContext.status}`,
+                `- Workflow/phase: ${plan.relatedRunContext.workflow}/${plan.relatedRunContext.phase}`,
+                `- Latest checkpoint: ${plan.relatedRunContext.latestCheckpointLabel ?? 'none'}`,
+                `- Recommendation: ${plan.relatedRunContext.recommendation}`,
+                `- Resume command: ${plan.relatedRunContext.resumeCommand}`,
+                '',
+            ]),
+        'Safety:',
+        ...plan.safety.map((line) => `- ${line}`),
+        '',
+        `JSON: vgxness sdd continue --project ${plan.project} --change ${plan.change} --json${continuationDbFlag(plan.explicitDatabasePath)}`,
+    ];
+    return `${lines.join('\n')}\n`;
+}
 export function renderSddCockpit(cockpit) {
     const blockers = cockpit.aggregateBlockers;
     const lines = [
@@ -71,13 +126,18 @@ export function renderSddCockpit(cockpit) {
         `Legacy artifacts: ${cockpit.legacyCount}`,
         '',
         'Aggregate blockers:',
-        ...(blockers.length === 0 ? ['- none'] : blockers.map((blocker) => `- ${blocker.kind}: ${blocker.phase} at ${blocker.topicKey} — ${blocker.reason}`)),
+        ...(blockers.length === 0
+            ? ['- none']
+            : blockers.map((blocker) => `- ${blocker.kind}: ${blocker.phase} at ${blocker.topicKey} - ${blocker.reason}${blocker.action === undefined ? '' : `; action=${blocker.action}`}`)),
         '',
         `Inspect: ${cockpit.inspectCommand}`,
         `Cockpit JSON: ${cockpit.inspectCommand}`,
     ];
     return `${lines.join('\n')}\n`;
 }
+function continuationDbFlag(explicitDatabasePath) {
+    return explicitDatabasePath === undefined ? '' : ` --db ${explicitDatabasePath}`;
+}
 export function renderSddArtifactAccepted(input) {
     const lines = [
         'SDD Artifact Accepted',
@@ -93,6 +153,23 @@ export function renderSddArtifactAccepted(input) {
     ];
     return `${lines.join('\n')}\n`;
 }
+export function renderSddArtifactReopened(input) {
+    const lines = [
+        'SDD Artifact Reopened',
+        `- Project: ${input.project}`,
+        `- Change: ${input.change}`,
+        `- Phase: ${input.phase}`,
+        `- Status: ${input.status}`,
+        `- Topic key: ${input.topicKey}`,
+        `- Artifact ID: ${input.artifactId}`,
+        `- Reopened by: ${input.reopenedBy.displayName} (${input.reopenedBy.id})`,
+        `- Reopened at: ${input.reopenedAt}`,
+        ...(input.note === undefined ? [] : [`- Note: ${input.note}`]),
+        `Next step: update the ${input.phase} artifact, then request human acceptance again.`,
+        `JSON: vgxness sdd reopen-artifact --project ${input.project} --change ${input.change} --phase ${input.phase} --actor ${input.reopenedBy.id} --json`,
+    ];
+    return `${lines.join('\n')}\n`;
+}
 export function renderSddArtifactList(input) {
     const artifactsByPhase = new Map(input.artifacts.map((artifact) => [artifact.phase, artifact]));
     const hasArtifacts = input.artifacts.length > 0;

package/dist/code/cli/code-command.js

@@ -1,3 +1,4 @@
+import { normalizeSddPhaseInput } from '../../sdd/schema.js';
 import { resolveCodeConfig } from '../config/defaults.js';
 import { CodeProviderRegistry } from '../providers/provider-registry.js';
 import { exitCodeForCodeStatus, renderHumanCodeSummary } from '../reporting/summary.js';
@@ -31,11 +32,12 @@ export async function runCodeCommand(input) {
         };
     const intent = input.command === 'sdd' ? `Run SDD ${input.args[1] ?? ''} for ${input.args[0] ?? ''}`.trim() : input.args.join(' ').trim();
     const changeId = input.command === 'sdd' ? input.args[0] : undefined;
-    const phase = input.command === 'sdd' ? input.args[1] : undefined;
-    if (input.command === 'sdd' && (changeId === undefined || phase === undefined))
+    const phaseInput = input.command === 'sdd' ? input.args[1] : undefined;
+    const phase = phaseInput === undefined ? undefined : normalizeSddPhaseInput(phaseInput);
+    if (input.command === 'sdd' && (changeId === undefined || phaseInput === undefined))
         return { exitCode: 1, stdout: '', stderr: 'Missing sdd change and phase\n' };
-    if (input.command === 'sdd' && phase !== undefined && !isSddCodePhase(phase))
-        return { exitCode: 1, stdout: '', stderr: `Unknown SDD phase: ${phase}\n` };
+    if (input.command === 'sdd' && phaseInput !== undefined && phase === undefined)
+        return { exitCode: 1, stdout: '', stderr: `Unknown SDD phase: ${phaseInput}\n` };
     if (!intent)
         return {
             exitCode: 1,
@@ -77,6 +79,7 @@ export async function runCodeCommand(input) {
         cwd: input.cwd,
         ...(changeId === undefined ? {} : { changeId }),
         ...(phase !== undefined && isSddCodePhase(phase) ? { phase } : {}),
+        ...(input.sddRuntimeMode === undefined ? {} : { sddRuntimeMode: input.sddRuntimeMode }),
         ...(input.persistArtifact === undefined ? {} : { persistArtifact: input.persistArtifact }),
         ...(input.sddGateway === undefined ? {} : { sddGateway: input.sddGateway }),
         ...(input.memoryGateway === undefined ? {} : { memoryGateway: input.memoryGateway }),

package/dist/code/reporting/summary.js

@@ -21,7 +21,10 @@ export function renderHumanCodeSummary(summary) {
         ...(summary.sdd === undefined
             ? []
             : [
-                `SDD: ${summary.sdd.changeId}/${summary.sdd.phase} saved=${summary.sdd.artifactSaved ? 'yes' : 'no'}`,
+                `SDD: ${summary.sdd.changeId}/${summary.sdd.phase} mode=${summary.sdd.sddRuntimeMode ?? 'strict'} saved=${summary.sdd.artifactSaved ? 'yes' : 'no'}`,
+                ...(summary.sdd.sddRuntimeMode === 'draft-run'
+                    ? ['SDD draft-run note: draft prerequisites are used for planning only; human acceptance is still required; apply-progress remains gated.']
+                    : []),
                 `Next SDD step: ${summary.sdd.nextRecommendation}`,
             ]),
         `Risks: ${summary.risks.length === 0 ? 'none reported' : summary.risks.join('; ')}`,

package/dist/code/runtime/code-runtime.js

@@ -1,4 +1,5 @@
 import { createHash, randomUUID } from 'node:crypto';
+import { normalizeSddPhaseInput } from '../../sdd/schema.js';
 import { resolveCodeConfig } from '../config/defaults.js';
 import { buildCodePrompt } from '../prompts/prompt-builder.js';
 import { CodeProviderError } from '../providers/provider-adapter.js';
@@ -30,7 +31,13 @@ export class CodeRuntime {
             if (input.changeId === undefined || input.phase === undefined || !isSddCodePhase(input.phase))
                 throw new Error('SDD mode requires a valid changeId and phase');
             const gateway = input.sddGateway ?? new InMemorySddGateway();
-            sddContext = await loadSddContext({ gateway, project, changeId: input.changeId, phase: input.phase });
+            sddContext = await loadSddContext({
+                gateway,
+                project,
+                changeId: input.changeId,
+                phase: input.phase,
+                ...(input.sddRuntimeMode === undefined ? {} : { runtimeMode: input.sddRuntimeMode }),
+            });
         }
         const availableDefinitions = input.mode === 'sdd' && input.phase !== undefined
             ? sddToolDefinitions({ phase: input.phase, persist: input.persistArtifact === true })
@@ -117,6 +124,7 @@ export class CodeRuntime {
                 ...(diagnostics === undefined ? {} : { diagnostics: diagnostics }),
             },
             ...(sddContext === undefined ? {} : { changeId: sddContext.changeId, sddPhase: sddContext.phase }),
+            ...(sddContext === undefined ? {} : { sddRuntimeMode: sddContext.runtimeMode }),
         });
         if (sddContext !== undefined) {
             await this.checkpoint(run.id, session, 'sdd-context-loaded', {
@@ -480,7 +488,15 @@ export class CodeRuntime {
             memory,
             ...(sddContext === undefined
                 ? {}
-                : { sdd: { changeId: sddContext.changeId, phase: sddContext.phase, artifactSaved, nextRecommendation: sddContext.next.recommendedAction } }),
+                : {
+                    sdd: {
+                        changeId: sddContext.changeId,
+                        phase: sddContext.phase,
+                        ...(sddContext.runtimeMode === undefined ? {} : { sddRuntimeMode: sddContext.runtimeMode }),
+                        artifactSaved,
+                        nextRecommendation: sddContext.next.recommendedAction,
+                    },
+                }),
         };
         const summary = config.transcriptMode === 'off' ? baseSummary : { ...baseSummary, transcript: buildTranscript(config.transcriptMode, session.checkpoints, toolResults) };
         if (sddContext !== undefined)
@@ -533,7 +549,13 @@ export class CodeRuntime {
             verification: { status: 'not-run', reason: 'SDD phase blocked before provider execution.' },
             filesChanged: [],
             risks: [answer],
-            sdd: { changeId: sddContext.changeId, phase: sddContext.phase, artifactSaved: false, nextRecommendation: sddContext.next.recommendedAction },
+            sdd: {
+                changeId: sddContext.changeId,
+                phase: sddContext.phase,
+                ...(sddContext.runtimeMode === undefined ? {} : { sddRuntimeMode: sddContext.runtimeMode }),
+                artifactSaved: false,
+                nextRecommendation: sddContext.next.recommendedAction,
+            },
         };
         await this.runGateway.finalize(runId, { status: 'blocked', outcome: 'blocked', outcomeReason: answer });
         return summary;
@@ -641,7 +663,8 @@ export class CodeRuntime {
                     changedFiles: [],
                 };
             if (call.name === 'sdd_read_artifact') {
-                const phase = typeof call.input.phase === 'string' && isSddCodePhase(call.input.phase) ? call.input.phase : context.phase;
+                const requestedPhase = typeof call.input.phase === 'string' ? normalizeSddPhaseInput(call.input.phase) : undefined;
+                const phase = requestedPhase !== undefined && isSddCodePhase(requestedPhase) ? requestedPhase : context.phase;
                 const artifact = await gateway.getArtifact({ project, change: context.changeId, phase });
                 return {
                     result: { toolCallId: call.id, toolName: call.name, ok: true, output: { phase, artifact }, metadata: { capability, truncated: false } },

package/dist/code/runtime/sdd-context.js

@@ -10,6 +10,7 @@ export function shellEnabledForSddPhase(phase) {
     return phase === 'apply-progress' || phase === 'verify';
 }
 export async function loadSddContext(input) {
+    const runtimeMode = input.runtimeMode ?? 'strict';
     const [status, next] = await Promise.all([
         input.gateway.getStatus({ project: input.project, change: input.changeId }),
         input.gateway.getNextPhase({ project: input.project, change: input.changeId }),
@@ -22,7 +23,7 @@ export async function loadSddContext(input) {
         if (artifact !== null)
             artifacts.push(toContextArtifact(input.project, input.changeId, phase, phase === input.phase ? 'active' : 'accepted', artifact.content, phaseStatus));
     }
-    return { changeId: input.changeId, phase: input.phase, status, next, artifacts };
+    return { changeId: input.changeId, phase: input.phase, runtimeMode, status, next, artifacts };
 }
 function toContextArtifact(project, change, phase, role, content, phaseStatus) {
     const bytes = Buffer.byteLength(content, 'utf8');
@@ -98,6 +99,8 @@ export function validateSddReadiness(context) {
                 recommendedAction: `Accept or restore prerequisites before running ${context.phase}.`,
             },
         };
+    if (isDraftRun(context) && isPlanningPhase(context.phase))
+        return { ok: true };
     if (present)
         return { ok: true };
     if (context.status.nextReadyPhase === context.phase)
@@ -123,10 +126,23 @@ export function activeBlockedPrerequisites(context) {
             return [{ phase, topicKey, reason: 'missing' }];
         if (status.accepted === true && status.legacy !== true)
             return [];
-        const reason = status.legacy === true ? 'legacy' : status.state === 'rejected' || status.state === 'superseded' ? status.state : 'draft';
+        if (status.legacy === true)
+            return [{ phase, topicKey, reason: 'legacy', ...(status.artifactId === undefined ? {} : { artifactId: status.artifactId }) }];
+        if (draftPrerequisiteAllowed(context, status.state ?? 'draft'))
+            return [];
+        const reason = status.state === 'rejected' || status.state === 'superseded' ? status.state : 'draft';
         return [{ phase, topicKey, reason, ...(status.artifactId === undefined ? {} : { artifactId: status.artifactId }) }];
     });
 }
+function draftPrerequisiteAllowed(context, state) {
+    return isDraftRun(context) && isPlanningPhase(context.phase) && state === 'draft';
+}
+function isDraftRun(context) {
+    return context.runtimeMode === 'draft-run';
+}
+function isPlanningPhase(phase) {
+    return phase === 'explore' || phase === 'proposal' || phase === 'spec' || phase === 'design' || phase === 'tasks';
+}
 function acceptedArtifactPhases(active) {
     return prerequisitePhases(active);
 }

package/dist/governance/governance-report-builder.js

@@ -1,5 +1,5 @@
 import { getSddPhasePermissionMatrixForPhase, permissionCategories, sddPhasePermissionMatrixVersion } from '../permissions/policy-evaluator.js';
-import { isSddPhase, normalizeSddArtifact } from '../sdd/schema.js';
+import { isSddPhase, normalizeSddArtifact, normalizeSddPhaseInput } from '../sdd/schema.js';
 import { fingerprintManagerProfileOverlay } from './overlay-fingerprint.js';
 export class GovernanceReportBuilder {
     services;
@@ -27,11 +27,13 @@ export class GovernanceReportBuilder {
             warnings.push('run-service-unavailable');
         }
         const workflow = input.workflow ?? run?.workflow;
-        const phase = input.phase ?? run?.phase;
+        const rawPhase = input.phase ?? run?.phase;
+        const phase = canonicalReportPhase(workflow, rawPhase);
         const agent = buildAgentRef(input, run);
         const change = input.change;
         const payloadMode = input.payloadMode ?? 'compact';
         const resolvedRunId = input.runId ?? run?.id;
+        const permissionsPhase = phase === undefined ? undefined : (normalizeSddPhaseInput(phase) ?? phase);
         const report = {
             version: 1,
             kind: 'governance-report',
@@ -44,7 +46,7 @@ export class GovernanceReportBuilder {
             ...(agent === undefined ? {} : { agent }),
             sdd: {},
             permissions: {
-                ...buildPermissionsMode(phase),
+                ...buildPermissionsMode(permissionsPhase),
             },
             openCode: {
                 mode: 'audit-only',
@@ -72,7 +74,8 @@ export class GovernanceReportBuilder {
     tryBuildOptimizedSddSnapshot(report, project, change, phase, payloadMode, warnings) {
         if (this.services.sdd.getGovernanceSnapshot === undefined)
             return false;
-        if (phase !== undefined && !isSddPhase(phase)) {
+        const canonicalPhase = phase === undefined ? undefined : normalizeSddPhaseInput(phase);
+        if (phase !== undefined && canonicalPhase === undefined) {
             warnings.push('sdd-readiness-skipped-non-sdd-phase');
             return false;
         }
@@ -80,7 +83,7 @@ export class GovernanceReportBuilder {
             project,
             change,
             payloadMode,
-            ...(phase === undefined ? {} : { phase }),
+            ...(canonicalPhase === undefined ? {} : { phase: canonicalPhase }),
         });
         if (!snapshot.ok) {
             warnings.push(`sdd-snapshot-unavailable:${snapshot.error.code}`);
@@ -125,8 +128,9 @@ export class GovernanceReportBuilder {
         else {
             warnings.push(`sdd-artifacts-unavailable:${listed.error.code}`);
         }
-        if (phase !== undefined && isSddPhase(phase)) {
-            const readiness = this.services.sdd.getReady({ project, change, phase });
+        const canonicalPhase = phase === undefined ? undefined : normalizeSddPhaseInput(phase);
+        if (canonicalPhase !== undefined) {
+            const readiness = this.services.sdd.getReady({ project, change, phase: canonicalPhase });
             if (readiness.ok) {
                 report.sdd.readiness = readiness.value;
                 for (const blocker of readiness.value.blockedPrerequisites ?? [])
@@ -280,6 +284,13 @@ function buildAgentRef(input, run) {
 function dedupe(values) {
     return [...new Set(values)];
 }
+function canonicalReportPhase(workflow, phase) {
+    if (phase === undefined)
+        return undefined;
+    if (workflow !== undefined && workflow.trim().toLowerCase() !== 'sdd')
+        return phase;
+    return normalizeSddPhaseInput(phase) ?? phase;
+}
 function validationFailure(message) {
     return { ok: false, error: { code: 'validation_failed', message } };
 }

package/dist/mcp/claude-code-agent-config.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { join, parse, resolve } from 'node:path';
 import { projectCanonicalAgentManifestToClaudeCode } from '../agents/canonical-agent-projection.js';
 import { assertInsideWorkspace } from './claude-code-config.js';
 export const claudeCodeGeneratedMarker = 'VGXNESS-GENERATED';
@@ -29,10 +29,16 @@ export function resolveClaudeAgentTarget(input) {
     return { workspaceRoot: input.workspaceRoot, scope, directoryPath: join(home, '.claude', 'agents'), ...(input.env === undefined ? {} : { env: input.env }) };
 }
 export function safeHomeDirectory(env = process.env) {
-    const candidate = env.HOME?.trim() || homedir();
-    if (!candidate || candidate === '/' || candidate.includes('\0') || candidate.includes('~'))
+    const homeDrive = env.HOMEDRIVE?.trim();
+    const homePath = env.HOMEPATH?.trim();
+    const homeDrivePath = homeDrive && homePath ? `${homeDrive}${homePath}` : '';
+    const candidate = env.HOME?.trim() || env.USERPROFILE?.trim() || homeDrivePath || homedir();
+    if (!candidate || candidate.startsWith('~') || candidate.includes('\0'))
         throw new Error('Unable to resolve a safe home directory for Claude user agents.');
-    return resolve(candidate);
+    const expanded = resolve(candidate);
+    if (parse(expanded).root === expanded)
+        throw new Error('Unable to resolve a safe home directory for Claude user agents.');
+    return expanded;
 }
 export function isVgxnessOwnedClaudeAgentMarkdown(contents) {
     return contents.includes(claudeCodeGeneratedMarker) && contents.includes('provider=claude') && contents.includes('artifact=claude-code-subagent');

package/dist/mcp/client-install-claude-code-contract.js

@@ -1,3 +1,4 @@
+import { withEffectiveManagerInstructions } from '../agents/canonical-agent-projection.js';
 import { expectedClaudeCodeAgentFiles, inspectClaudeCodeAgents, renderClaudeCodeAgentMarkdown } from './claude-code-agent-config.js';
 import { buildClaudeCodeMcpAddCommand } from './claude-code-cli.js';
 import { createClaudeCodeMcpDoctorCommand, createClaudeCodeMcpServerConfig, inspectClaudeCodeMcpConfig, resolveClaudeCodeMcpJsonPath } from './claude-code-config.js';
@@ -63,11 +64,25 @@ export function planClaudeCodeMcpInstall(input) {
         status: 'would_install',
     };
 }
-export function expectedClaudeCodeRenderedAgents(workspaceRoot) {
-    return expectedClaudeCodeAgentFiles(workspaceRoot).map((agent) => ({ path: agent.path, agentName: agent.name, contents: renderClaudeCodeAgentMarkdown(agent) }));
+export function expectedClaudeCodeRenderedAgents(workspaceRoot, options) {
+    const files = expectedClaudeCodeAgentFiles(workspaceRoot);
+    const projection = withEffectiveManagerInstructions({ defaultAgent: 'vgxness-manager', agents: files.map(({ path: _path, ...rest }) => rest) }, options?.effectiveManagerInstructions);
+    return projection.agents.map((agent) => {
+        const file = files.find((entry) => entry.name === agent.name);
+        if (file === undefined)
+            throw new Error(`Expected Claude agent file missing for ${agent.name}`);
+        return { path: file.path, agentName: agent.name, contents: renderClaudeCodeAgentMarkdown(agent) };
+    });
 }
-export function expectedClaudeCodeRenderedUserAgents(workspaceRoot, env) {
-    return expectedClaudeCodeAgentFiles({ workspaceRoot, scope: 'user', ...(env === undefined ? {} : { env }) }).map((agent) => ({ path: agent.path, agentName: agent.name, contents: renderClaudeCodeAgentMarkdown(agent) }));
+export function expectedClaudeCodeRenderedUserAgents(workspaceRoot, env, options) {
+    const files = expectedClaudeCodeAgentFiles({ workspaceRoot, scope: 'user', ...(env === undefined ? {} : { env }) });
+    const projection = withEffectiveManagerInstructions({ defaultAgent: 'vgxness-manager', agents: files.map(({ path: _path, ...rest }) => rest) }, options?.effectiveManagerInstructions);
+    return projection.agents.map((agent) => {
+        const file = files.find((entry) => entry.name === agent.name);
+        if (file === undefined)
+            throw new Error(`Expected Claude user agent file missing for ${agent.name}`);
+        return { path: file.path, agentName: agent.name, contents: renderClaudeCodeAgentMarkdown(agent) };
+    });
 }
 function planUserInstall(input, server, overwriteVgxness, cliCommand, scopeWarnings) {
     const mcpState = inspectClaudeCodeUserMcpConfig(input.env);

package/dist/mcp/client-install-claude-code.js

@@ -62,7 +62,7 @@ export async function installClaudeCodeMcpClient(input) {
     if (!mcpWrite.ok)
         return refusal('post_write_validation_failed', mcpWrite.error.message, plan, server, writtenPaths, backups);
     writtenPaths.push(mcpWrite.value);
-    for (const agent of expectedClaudeCodeRenderedAgents(input.cwd)) {
+    for (const agent of expectedClaudeCodeRenderedAgents(input.cwd, { effectiveManagerInstructions: input.effectiveManagerInstructions })) {
         const target = plan.targets.find((item) => item.kind === 'agent-file' && item.path === agent.path);
         if (target?.action !== 'create' && target?.action !== 'update-vgxness')
             continue;
@@ -140,7 +140,7 @@ async function applyUserInstall(input, plan, server, writtenPaths, backups) {
     if (!mcpWrite.ok)
         return refusal('post_write_validation_failed', mcpWrite.error.message, plan, server, writtenPaths, backups);
     writtenPaths.push(mcpWrite.value);
-    for (const agent of expectedClaudeCodeRenderedUserAgents(input.cwd, input.env)) {
+    for (const agent of expectedClaudeCodeRenderedUserAgents(input.cwd, input.env, { effectiveManagerInstructions: input.effectiveManagerInstructions })) {
         const target = plan.targets.find((item) => item.kind === 'agent-file' && item.path === agent.path);
         if (target?.action !== 'create' && target?.action !== 'update-vgxness')
             continue;