vgxness 1.9.1 → 1.9.3

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,
@@ -175,7 +175,7 @@ export class SddWorkflowService {
             if (status === 'accepted')
                 return validationFailure('Cannot overwrite an accepted SDD artifact; supersede it under a new topic key.');
             if (status === 'rejected')
-                return validationFailure('Rejected SDD artifact must be re-opened with an explicit decision before saving.');
+                return validationFailure('Rejected SDD artifact must be re-opened via SddWorkflowService.reopenArtifact before saving.');
             if (status === 'superseded')
                 return validationFailure('Cannot overwrite a superseded SDD artifact.');
         }
@@ -198,7 +198,7 @@ export class SddWorkflowService {
         const existingEnvelope = normalizeSddArtifact(existing.value);
         const existingStatus = existingEnvelope.metadata.status;
         if (existingStatus === 'rejected')
-            return validationFailure('Rejected SDD artifact must be re-opened with an explicit decision before accepting.');
+            return validationFailure('Rejected SDD artifact must be re-opened via SddWorkflowService.reopenArtifact before accepting.');
         if (existingStatus === 'superseded')
             return validationFailure('Cannot accept a superseded SDD artifact; create a new artifact under a different topic key instead.');
         const acceptance = {
@@ -223,6 +223,47 @@ export class SddWorkflowService {
             },
         }, this.context);
     }
+    reopenArtifact(input) {
+        const validated = this.validatePhaseInput(input);
+        if (!validated.ok)
+            return validated;
+        if (input.reopenedBy === undefined)
+            return validationFailure('SDD artifact reopen requires an explicit human actor');
+        if (input.reopenedBy.type !== 'human')
+            return validationFailure('SDD artifact reopen must be performed by a human actor');
+        if (input.reopenedBy.id === undefined || input.reopenedBy.id.trim().length === 0)
+            return validationFailure('SDD artifact reopen human actor id must not be empty');
+        const topicKey = sddTopicKey(validated.value.change, validated.value.phase);
+        const existing = this.memory.getArtifact(validated.value.project, topicKey, this.context);
+        if (!existing.ok)
+            return existing;
+        const existingEnvelope = normalizeSddArtifact(existing.value);
+        const existingStatus = existingEnvelope.metadata.status;
+        if (existingStatus !== 'rejected')
+            return validationFailure(`SDD artifact reopen is only valid for rejected artifacts (current status: ${existingStatus}).`);
+        const reopenedAt = input.reopenedAt ?? new Date().toISOString();
+        const reopenRecord = {
+            actor: {
+                type: 'human',
+                id: input.reopenedBy.id,
+                ...(input.reopenedBy.displayName === undefined ? {} : { displayName: input.reopenedBy.displayName }),
+            },
+            reopenedAt,
+            ...(input.note === undefined ? {} : { note: input.note }),
+        };
+        return this.memory.saveArtifact({
+            project: existing.value.project,
+            topicKey: existing.value.topicKey,
+            phase: existing.value.phase,
+            content: existing.value.content,
+            metadata: {
+                ...existingEnvelope.metadata,
+                status: 'draft',
+                reopen: reopenRecord,
+                updatedAt: reopenedAt,
+            },
+        }, this.context);
+    }
     getArtifact(input) {
         const validated = this.validatePhaseInput(input);
         if (!validated.ok)
@@ -273,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);
@@ -326,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;
@@ -340,6 +384,7 @@ export function nextDecisionFromStatuses(change, phases, options = {}) {
                 status: 'blocked',
                 nextPhase: firstUnacceptedPhase.phase,
                 missingArtifactTopicKeys: [firstUnacceptedPhase.topicKey],
+                missingPrerequisiteTopicKeys: [],
                 blockedPrerequisites: [
                     {
                         phase: firstUnacceptedPhase.phase,
@@ -348,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 {
@@ -369,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 {
@@ -398,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);
@@ -408,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) {
@@ -477,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)
@@ -492,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 ?? []) {
@@ -500,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 }),
         });
     }
@@ -507,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();
@@ -526,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) {

package/dist/skills/skill-resolver.js

@@ -1,3 +1,4 @@
+import { normalizeSddPhaseInput } from '../sdd/schema.js';
 export class SkillResolver {
     skills;
     agents;
@@ -113,10 +114,13 @@ export class SkillResolver {
             targets.push({ targetType: agent.mode, targetKey: agent.name });
             targets.push({ targetType: agent.mode, targetKey: `${agent.project}/${agent.scope}/${agent.name}` });
         }
-        if (input.workflow !== undefined && input.phase !== undefined)
-            targets.push({ targetType: 'workflow-phase', targetKey: `${input.workflow}:${input.phase}` });
-        if (input.phase !== undefined)
-            targets.push({ targetType: 'workflow-phase', targetKey: input.phase });
+        const phases = phaseTargetKeys(input.workflow, input.phase);
+        if (input.workflow !== undefined) {
+            for (const phase of phases)
+                targets.push({ targetType: 'workflow-phase', targetKey: `${input.workflow}:${phase}` });
+        }
+        for (const phase of phases)
+            targets.push({ targetType: 'workflow-phase', targetKey: phase });
         if (input.providerAdapter !== undefined)
             targets.push({ targetType: 'provider-adapter', targetKey: input.providerAdapter });
         return dedupeTargets(targets);
@@ -212,6 +216,19 @@ function dedupeTargets(targets) {
         return true;
     });
 }
+function phaseTargetKeys(workflow, phase) {
+    if (phase === undefined)
+        return [];
+    if (!isSddWorkflow(workflow))
+        return [phase];
+    const normalized = normalizeSddPhaseInput(phase);
+    if (normalized === 'apply-progress')
+        return ['apply-progress', 'apply'];
+    return normalized === undefined || normalized === phase ? [phase] : [normalized, phase];
+}
+function isSddWorkflow(workflow) {
+    return workflow?.trim().toLowerCase() === 'sdd';
+}
 function stringMetadata(value) {
     return typeof value === 'string' && value.trim() ? value : undefined;
 }

package/dist/status/product-status.js

@@ -0,0 +1,117 @@
+import { basename, resolve } from 'node:path';
+export function buildProductStatus(input) {
+    const project = resolveProject(input);
+    const baseSafety = [
+        'Read-only cockpit: does not execute providers, edit files, write provider config, or mutate SDD artifacts.',
+        'Human acceptance remains explicit; saved artifacts do not imply acceptance.',
+    ];
+    if (input.change === undefined) {
+        return {
+            version: 1,
+            kind: 'product-status',
+            project,
+            status: [`Project: ${project.value} (${project.source === 'flag' ? 'from --project' : 'inferred from cwd'})`, 'Change: not selected'],
+            blockers: ['No --change was provided, so VGXNESS cannot inspect SDD phase state yet.'],
+            next: ['Choose the active change id, then re-run status for the SDD cockpit view.'],
+            command: `vgxness status --project ${project.value} --change <change>`,
+            safety: ['Did not open the local memory store because no change was selected.', ...baseSafety],
+        };
+    }
+    if (input.databaseError !== undefined) {
+        return blockedStatus({
+            project,
+            change: input.change,
+            blocker: `Unable to read local memory store${input.databasePath === undefined ? '' : ` at ${input.databasePath}`}: ${input.databaseError}`,
+            next: 'Check --db, VGXNESS_DB_PATH, or run setup/status commands with the installed Bun runtime.',
+            command: `vgxness status --project ${project.value} --change ${input.change} --db <path>`,
+            safety: baseSafety,
+        });
+    }
+    if (input.sdd === undefined) {
+        return blockedStatus({
+            project,
+            change: input.change,
+            blocker: 'SDD cockpit service is not available for this status request.',
+            next: 'Use the installed CLI or provide a readable local memory store.',
+            command: `vgxness sdd cockpit --project ${project.value} --change ${input.change}`,
+            safety: baseSafety,
+        });
+    }
+    const cockpit = input.sdd.getCockpit({ project: project.value, change: input.change });
+    if (!cockpit.ok) {
+        return blockedStatus({
+            project,
+            change: input.change,
+            blocker: cockpit.error.message,
+            next: 'Review the project/change flags and local memory store, then re-run status.',
+            command: `vgxness sdd cockpit --project ${project.value} --change ${input.change}`,
+            safety: baseSafety,
+        });
+    }
+    const relatedRunContext = findRelatedRunContext({
+        project: project.value,
+        change: input.change,
+        ...(input.runs === undefined ? {} : { runs: input.runs }),
+        ...(input.explicitDatabasePath === undefined ? {} : { explicitDatabasePath: input.explicitDatabasePath }),
+    });
+    return fromSddCockpit(cockpit.value, project, baseSafety, relatedRunContext);
+}
+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 fromSddCockpit(cockpit, project, baseSafety, relatedRunContext) {
+    const nextLabel = cockpit.next.nextPhase === undefined ? cockpit.next.status : `${cockpit.next.status} / ${cockpit.next.nextPhase}`;
+    const command = cockpit.next.status === 'runnable' && cockpit.next.nextPhase !== undefined
+        ? `vgxness code sdd ${cockpit.change} ${cockpit.next.nextPhase} --project ${cockpit.project} --save-artifact`
+        : `vgxness sdd cockpit --project ${cockpit.project} --change ${cockpit.change} --json`;
+    return {
+        version: 1,
+        kind: 'product-status',
+        project,
+        change: cockpit.change,
+        status: [
+            `Project: ${cockpit.project}`,
+            `Change: ${cockpit.change}`,
+            `Next: ${nextLabel}`,
+            `Accepted: ${cockpit.acceptedCount}/${cockpit.phases.length}`,
+            `Legacy artifacts: ${cockpit.legacyCount}`,
+        ],
+        blockers: cockpit.aggregateBlockers.length === 0
+            ? ['none']
+            : cockpit.aggregateBlockers.map((blocker) => `${blocker.phase}: ${blocker.reason} at ${blocker.topicKey}${blocker.action === undefined ? '' : `; action=${blocker.action}`}`),
+        next: [cockpit.recommendedAction],
+        command,
+        sddNextStatus: cockpit.next.status,
+        ...(relatedRunContext === undefined ? {} : { relatedRunContext }),
+        safety: baseSafety,
+    };
+}
+function findRelatedRunContext(input) {
+    if (input.runs === undefined)
+        return undefined;
+    const relatedRun = input.runs.findRelatedInterruptedSddRun({ project: input.project, change: input.change });
+    if (!relatedRun.ok || relatedRun.value === undefined)
+        return undefined;
+    const dbFlag = input.explicitDatabasePath === undefined ? '' : ` --db ${input.explicitDatabasePath}`;
+    return {
+        ...relatedRun.value,
+        recommendation: 'Related interrupted run found by checkpoint changeId; inspect or resume it before starting duplicate SDD work. Advisory only.',
+        resumeCommand: `vgxness resume --project ${input.project} --run-id ${relatedRun.value.runId}${dbFlag}`,
+    };
+}
+function blockedStatus(input) {
+    return {
+        version: 1,
+        kind: 'product-status',
+        project: input.project,
+        change: input.change,
+        status: [`Project: ${input.project.value}`, `Change: ${input.change}`, 'Status: blocked'],
+        blockers: [input.blocker],
+        next: [input.next],
+        command: input.command,
+        safety: input.safety,
+    };
+}

package/docs/architecture.md

@@ -91,6 +91,14 @@ Gentle-AI/`gentle-pi` are strong references for the configurator and agent-behav
 | `Adapter` | Translator between the neutral `vgxness` model and a provider-specific config/runtime. |
 | `PermissionPolicy` | Rules defining what an agent may do, what requires approval, and what must be denied. |
 
+### Agent registry self-healing
+
+The canonical agent manifest in `src/agents/canonical-agent-manifest.ts` is the source of truth for built-in agents (1 manager + 10 SDD subagents). At every CLI/MCP boot, `src/agents/boot-upgrade.ts` reconciles the live `agents` table with that manifest via `src/agents/agent-seed-upgrade-service.ts`: missing rows are created, drifted rows (changed `vgxnessPromptContractVersion`, instructions, adapters, or description) are overwritten, and matches are recorded as noop. Each non-noop outcome is appended to the `agent_seed_history` table for audit. Operators can opt out with `VGXNESS_SKIP_AGENT_SEED_AUTO_UPGRADE=1`. This eliminates the long-standing drift between the canonical prompt contract and stored agent rows after a version bump.
+
+### Manager overlay parity across providers
+
+A user-saved `manager_profile_overlay` flows to both providers symmetrically. OpenCode consults the overlay inside `OpenCodeManagerPayloadService.applyManagerOverlayWhenAvailable` (`src/providers/opencode/manager-payload.ts:152-156`), which calls `ManagerProfileOverlayService.resolveEffectiveManager` before producing the OpenCode manager payload. Claude Code was previously canonical-only; the fix routes the overlay through `withEffectiveManagerInstructions` (`src/agents/canonical-agent-projection.ts`) into the render path (`expectedClaudeCodeRenderedAgents` / `expectedClaudeCodeRenderedUserAgents`), with the caller (`mcp install claude` in `src/cli/commands/mcp-dispatcher.ts`) computing the effective instructions via `computeEffectiveManagerInstructions(database)` and passing them into `installClaudeCodeMcpClient`. As a result, `vgxness mcp install claude` writes the user's customized instructions into `.claude/agents/vgxness-manager.md` instead of silently falling back to canonical.
+
 ## Storage model
 
 `vgxness` should keep local storage split by scope.
@@ -617,7 +625,7 @@ The code runtime layers a second, finer-grained decision on top of the policy ev
 
 CLI surface groups are documented in [CLI reference](./cli.md). The plural form is canonical — singular shortcuts are not added.
 
-MCP tools mirror the same core services for agent use. The full, current list of 38 tools is in [MCP tools](./mcp.md) and `SUPPORTED_VGX_MCP_TOOL_NAMES` (`src/mcp/schema.ts`); treat that array as the source of truth. The CLI and TUI are human/operator control surfaces. MCP is the agent-facing control surface. Provider integrations and the code runtime sit on the execution plane.
+MCP tools mirror the same core services for agent use. The full, current list of 41 tools is in [MCP tools](./mcp.md) and `SUPPORTED_VGX_MCP_TOOL_NAMES` (`src/mcp/schema.ts`); treat that array as the source of truth. The CLI and TUI are human/operator control surfaces. MCP is the agent-facing control surface. Provider integrations and the code runtime sit on the execution plane.
 
 ## Evaluation strategy
 

package/docs/cli.md

@@ -24,7 +24,7 @@ vgx --help
 vgxness mcp start --db <temp-memory.sqlite> # then call verification_plan with { changeType: 'mcp' }
 ```
 
-`vgxness setup plan` and `vgxness setup status` are human-readable and read-only by default; pass `--json` when you need parseable automation output. The MCP plan is read-only. Installed-package setup plans should use `vgxness mcp start` and must not mention `npm run cli`, `tsx`, or repository-relative source paths.
+`vgxness setup plan` and `vgxness setup status` are human-readable and do not write provider config by default; local VGXNESS store initialization may occur when the selected SQLite store is needed. Pass `--json` when you need parseable automation output. The MCP plan does not write provider config. Installed-package setup plans should use `vgxness mcp start` and must not mention `npm run cli`, `tsx`, or repository-relative source paths.
 
 Only apply the OpenCode user/global config after reviewing the plan (use `--scope project` only when you intentionally want project config):
 
@@ -59,14 +59,31 @@ vgxness setup plan           # human-readable, read-only plan
 vgxness setup status         # human-readable, read-only setup status
 vgxness setup apply --yes    # writes OpenCode config only after explicit consent
 vgxness doctor               # human-readable readiness checks
-vgxness sdd next --project <project> --change <change>
+vgxness status --project <project> --change <change>
+vgxness next --project <project> --change <change>
+vgxness resume --project <project> --run-id <id>
 vgxness setup rollback --backup <path>
 ```
 
-`setup plan`, `setup status`, and non-TTY `init` planning are read-only and do not write provider config. They are human-readable by default; pass `--json` when you need parseable automation output. With the default global database, the OpenCode MCP command is `vgxness mcp start`; for custom/project-local DBs it includes `--db <path>`. The default OpenCode target is `$HOME/.config/opencode/opencode.json`; pass `--scope project` to opt into `<workspace>/.opencode/opencode.json`. `setup apply --yes` is the explicit OpenCode provider-config write path. `setup rollback --backup <path>` validates a VGXNESS/OpenCode backup such as `opencode.json.backup-<timestamp>`, creates a pre-rollback backup of the current target when present, restores the selected backup byte-for-byte, and recommends `vgxness doctor`.
+`setup plan`, `setup status`, and non-TTY `init` planning do not write provider config. Local VGXNESS store initialization may occur when the selected SQLite store is needed. They are human-readable by default; pass `--json` when you need parseable automation output. With the default global database, the OpenCode MCP command is `vgxness mcp start`; for custom/project-local DBs it includes `--db <path>`. The default OpenCode target is `$HOME/.config/opencode/opencode.json`; pass `--scope project` to opt into `<workspace>/.opencode/opencode.json`. `setup apply --yes` is the explicit OpenCode provider-config write path. `setup rollback --backup <path>` validates a VGXNESS/OpenCode backup such as `opencode.json.backup-<timestamp>`, creates a pre-rollback backup of the current target when present, restores the selected backup byte-for-byte, and recommends `vgxness doctor`.
 
 `vgxness init` prompts in English when stdin/stdout are TTYs: project name, DB location, provider, OpenCode scope, install mode, then shows the plan and asks `Apply this setup? Type "yes" to continue:`. Any answer other than `yes` exits successfully without writes. In CI/non-TTY without `--yes`, `init` returns the read-only plan and never waits for input. `vgxness doctor`, `vgxness sdd status`, `vgxness sdd next`, `vgxness sdd get-artifact`, and `vgxness sdd list-artifacts` are also human-readable by default; use `--json` for scripts.
 
+## Daily workflow front doors
+
+Use these top-level commands before dropping into lower-level SDD or run inspection commands:
+
+| Question | Command | Purpose |
+|---|---|---|
+| Where am I? | `vgxness status --project <project> --change <change>` | Shows the SDD cockpit state, blockers, next recommendation, and safety notes. |
+| What should I do now? | `vgxness next --project <project> --change <change>` | Narrows the cockpit to the next action and why it is safe or blocked. |
+| How do I continue a change? | `vgxness sdd continue --project <project> --change <change>` | Builds a read-only continuation plan for the selected SDD change. |
+| How do I continue interrupted work? | `vgxness resume --project <project> [--run-id <id>]` | Lists or inspects interrupted runs and suggests manual continuation commands without retrying anything. |
+
+Without `--change`, `--project`, or `--run-id`, these commands stay orientation-only and do not open the local memory store. With a selected change, project, or run, top-level `status`, `next`, and `resume` inspect SQLite read-only; formal `sdd` commands are non-provider, non-run-executing planning/artifact commands that may use the normal local store path. Pass `--json` for automation.
+
+The usual SDD operator loop is: inspect `status`, ask `next`, run `sdd continue` for the copyable continuation plan, then either run `vgxness code sdd ...` for phase work or `vgxness resume ...` for an interrupted run. After a draft is ready, use `sdd accept-artifact` for explicit human acceptance; if an artifact was rejected, use `sdd reopen-artifact` before revising it. Related interrupted run hints in `status`, `next`, and `sdd continue` are advisory only; they help avoid duplicate work but do not retry or execute runs.
+
 ## Bun-first repository verification
 
 VGXNESS uses Bun as the canonical installed runtime and verification path for repository development and CI. Node.js `>=22` remains development/build/test tooling for TypeScript, `node:test`, and helper scripts. npm package consumer metadata remains supported, but the product runtime engine is `engines.bun`.
@@ -112,7 +129,7 @@ Release-candidate checklist, without publishing:
 
 1. `bun install --frozen-lockfile` completes on a clean checkout.
 2. `bun run check:bun-lock` passes.
-3. `bun run verify:typecheck`, `bun run verify:test`, and `bun run verify:bun-sqlite` pass.
+3. `bun run verify:typecheck`, `bun run verify:test`, `bun run verify:test:bun-storage`, and `bun run verify:bun-sqlite` pass.
 4. `bun run package:bun:evidence -- --require-pass` passes on supported CI OSes.
 5. Uploaded JSON shows `status: pass`, artifact/install smoke pass, no retired scripts, no `package-lock.json`, `publicationAttempted: false`, and `releaseReadiness.status: pass`.
 6. Version, release notes, proprietary license boundary, and rollback criteria are reviewed.
@@ -226,7 +243,9 @@ For scriptable status, use explicit read-only commands:
 
 ```bash
 bun run cli:bun -- setup status --project vgxness
-bun run cli:bun -- sdd status --project vgxness --change my-change
+bun run cli:bun -- status --project vgxness --change my-change
+bun run cli:bun -- next --project vgxness --change my-change
+bun run cli:bun -- resume --project vgxness --run-id <id>
 ```
 
 Provider support shown in the Installation surface is:
@@ -283,7 +302,7 @@ vgxness code inspect "<question>"   \
   --memory off|ask|auto
 ```
 
-SDD-aware mode is exposed through `vgxness code sdd <change> <phase>`; pass `--save-artifact` only when persistence is intended, and pass `--change-id`/`--phase` to scope work. Read-only phases stay artifact-oriented; `apply-progress` may expose edit and shell tools; `verify` may expose verification shell tools.
+SDD-aware mode is exposed through `vgxness code sdd <change> <phase>`; pass `--save-artifact` only when persistence is intended, and pass `--change-id`/`--phase` to scope work. Read-only phases stay artifact-oriented; `apply-progress` may expose edit and shell tools; `verify` may expose verification shell tools. `--draft-run` lets planning phases use draft prerequisites for planning only; human acceptance is still required, and `apply-progress` remains gated. `apply` is accepted as a user-facing alias for `apply-progress`.
 
 Useful events-only output for piping into the OpenTUI shell or your own tooling:
 
@@ -312,7 +331,7 @@ bun run cli:bun -- <workflow> run --project <name> --intent <text> [--phase <nam
 bun run cli:bun -- <workflow> execute --run-id <id> --confirm [--override-escalation] [--workspace <path>] [--db <path>] [--executor safe-non-dispatching|provider|command]
 ```
 
-`preview` is read-only: it returns the workflow registry plus optional planner output, does not open or write the database, does not create runs, does not call providers, does not edit files, and does not write provider config. Use it to choose between `quickfix`, `debug`, `sdd`, or another workflow before recording state.
+`preview` is read-only: it returns the workflow registry plus optional planner output, does not open or write the database, does not create runs, does not call providers, does not edit files, and does not write provider config. Use it to choose between `quickfix`, `debug`, `sdd`, or another workflow before recording state. Other status/plan surfaces may open or initialize the selected VGXNESS SQLite store; that local store state is separate from provider config.
 
 `run` records the selected workflow intent and a `workflow-run-planned` checkpoint in the local SQLite store. It selects or validates an agent, stores the run id, and reports any planner recommendation such as SDD escalation. It does not dispatch providers, edit files, write provider config, create subagents, or mutate SDD artifacts.
 
@@ -433,11 +452,11 @@ A rejected approval is recorded in the run audit trail and prevents the matching
 
 ### SDD workflow commands vs formal SDD commands
 
-`sdd preview`, `sdd run`, and `sdd execute` are workflow commands and use the three-mode workflow contract above. `sdd status`, `sdd ready`, `sdd save-artifact`, `sdd accept-artifact`, `sdd get-artifact`, `sdd list-artifacts`, and `sdd next` are formal SDD artifact/status commands. Formal SDD commands read or write SDD artifact state in the selected local SQLite store; they do not execute providers or continue workflow runs.
+`sdd preview`, `sdd run`, and `sdd execute` are workflow commands and use the three-mode workflow contract above. `sdd status`, `sdd ready`, `sdd continue`, `sdd save-artifact`, `sdd accept-artifact`, `sdd reopen-artifact`, `sdd get-artifact`, `sdd list-artifacts`, and `sdd next` are formal SDD artifact/status commands. Formal SDD commands read or write SDD artifact state in the selected local SQLite store; they do not execute providers or retry workflow runs. `sdd continue` is read-only and returns a continuation plan; it does not create runs, mutate artifacts, or call providers.
 
 ## MCP setup preview and doctor
 
-Use this flow to manually verify MCP readiness after implementation. Setup preview is read-only: it does **not** install anything, create `.opencode/` or `.claude/`, or write provider/user/global config.
+Use this flow to manually verify MCP readiness after implementation. Setup preview does **not** install anything, create `.opencode/` or `.claude/`, or write provider/user/global config. Local VGXNESS store initialization may occur when a command needs the selected SQLite store.
 
 ```bash
 bun run cli:bun -- mcp setup --preview --provider opencode --db <path>
@@ -549,18 +568,24 @@ Use `sdd` commands to inspect local SDD artifact state and save, read, or list p
 bun run cli:bun -- sdd status --project vgxness --change sdd-workflow-engine --db /tmp/vgxness-memory.sqlite
 bun run cli:bun -- sdd ready --project vgxness --change sdd-workflow-engine --phase spec --db /tmp/vgxness-memory.sqlite
 bun run cli:bun -- sdd save-artifact --project vgxness --change sdd-workflow-engine --phase proposal --content "# Proposal" --db /tmp/vgxness-memory.sqlite
+bun run cli:bun -- sdd continue --project vgxness --change sdd-workflow-engine --db /tmp/vgxness-memory.sqlite
+bun run cli:bun -- code sdd sdd-workflow-engine spec --project vgxness --draft-run --save-artifact --db /tmp/vgxness-memory.sqlite
 bun run cli:bun -- sdd accept-artifact --project vgxness --change sdd-workflow-engine --phase proposal --actor user --note "Approved for spec" --db /tmp/vgxness-memory.sqlite
+bun run cli:bun -- resume --project vgxness --db /tmp/vgxness-memory.sqlite
 bun run cli:bun -- sdd get-artifact --project vgxness --change sdd-workflow-engine --phase proposal --db /tmp/vgxness-memory.sqlite
 bun run cli:bun -- sdd list-artifacts --project vgxness --change sdd-workflow-engine --db /tmp/vgxness-memory.sqlite
 bun run cli:bun -- sdd next --project vgxness --change sdd-workflow-engine --db /tmp/vgxness-memory.sqlite
+bun run cli:bun -- sdd reopen-artifact --project vgxness --change sdd-workflow-engine --phase design --actor user --note "Revise rejected design" --db /tmp/vgxness-memory.sqlite
 VGXNESS_DB_PATH=/tmp/vgxness-memory.sqlite bun run cli:bun -- sdd list-artifacts --project vgxness --change sdd-workflow-engine
 ```
 
-Current phases are `explore`, `proposal`, `spec`, `design`, `tasks`, `apply-progress`, `verify`, and `archive`. Each artifact is stored under `sdd/{change}/{phase}` in the local SQLite memory store. `sdd status` reports which phase artifacts are present and the next ready missing phase. `sdd next` reports the next SDD action for a project/change. `sdd status`, `sdd next`, `sdd get-artifact`, and `sdd list-artifacts` are human-readable by default; pass `--json` for automation/stable structured output. `sdd ready` reports satisfied prerequisites and missing artifact topic keys for one phase. `sdd get-artifact` shows artifact metadata and then full content after `--- Content ---`; `sdd list-artifacts` shows one compact row for every canonical SDD phase in phase order and does not print full artifact content.
+Current canonical phases are `explore`, `proposal`, `spec`, `design`, `tasks`, `apply-progress`, `verify`, and `archive`. `apply` is accepted as a user-facing input alias, but artifacts, topic keys, readiness/status/cockpit JSON, and internal metadata continue to use canonical `apply-progress`. Each artifact is stored under `sdd/{change}/{phase}` in the local SQLite memory store. `sdd status` reports which phase artifacts are present, blocker-specific next actions, and related interrupted run hints when available. `sdd next` reports the next SDD action for a project/change. `sdd continue` turns that state into a read-only continuation plan, including draft-run suggestions for planning phases and related interrupted run context when a matching stopped run exists. `sdd status`, `sdd next`, `sdd continue`, `sdd get-artifact`, and `sdd list-artifacts` are human-readable by default; pass `--json` for automation/stable structured output. `sdd ready` reports satisfied prerequisites and missing artifact topic keys for one phase. `sdd get-artifact` shows artifact metadata and then full content after `--- Content ---`; `sdd list-artifacts` shows one compact row for every canonical SDD phase in phase order and does not print full artifact content.
+
+`sdd accept-artifact` records explicit human-only acceptance of an existing artifact through the same SDD workflow service used by MCP. It requires `--project`, `--change`, `--phase`, and `--actor`; `--display-name` defaults to the actor id. `--accepted-at` is optional, but when supplied it must be an ISO date-time with an explicit timezone (`Z` or offset) and is normalized to UTC `toISOString()` output. The default output is a human-readable confirmation with a JSON hint; `--json` returns a content-free success object with project/change/phase/topic key/artifact id/status/acceptedBy/acceptedAt and optional note. `save-artifact` creates or updates draft content only and does not imply acceptance. `sdd reopen-artifact` moves a rejected artifact back to draft after an explicit human decision, so the artifact can be revised and accepted again.
 
-`sdd accept-artifact` records explicit human-only acceptance of an existing artifact through the same SDD workflow service used by MCP. It requires `--project`, `--change`, `--phase`, and `--actor`; `--display-name` defaults to the actor id. `--accepted-at` is optional, but when supplied it must be an ISO date-time with an explicit timezone (`Z` or offset) and is normalized to UTC `toISOString()` output. The default output is a human-readable confirmation with a JSON hint; `--json` returns a content-free success object with project/change/phase/topic key/artifact id/status/acceptedBy/acceptedAt and optional note. `save-artifact` creates or updates draft content only and does not imply acceptance.
+Use `resume --project <project>` when you do not know the run id. It lists recent interrupted candidates for that project from the selected database. Use `resume --project <project> --run-id <id>` to inspect one candidate; this is still read-only and advisory.
 
-The SDD CLI is status/persistence only. It does **not** execute providers, continue workflows, create `openspec/`, or write `.opencode/`, `.claude/`, or user/global provider config.
+The SDD CLI is status, planning, and artifact persistence only. It does **not** execute providers, retry workflow runs, create `openspec/`, or write `.opencode/`, `.claude/`, or user/global provider config.
 
 ## Agent resolution
 
@@ -953,7 +978,7 @@ For more on schema, scopes, and lifecycle, see [Storage](./storage.md).
 
 - [Architecture](./architecture.md) — current-state architecture and core domain model.
 - [Code runtime](./code-runtime.md) — `vgxness code` modes, tools, providers, and approval flow.
-- [MCP tools](./mcp.md) — full reference for the 38 MCP tools exposed to agents.
+- [MCP tools](./mcp.md) — full reference for the 41 MCP tools exposed to agents.
 - [Safety model](./safety.md) — permission categories, approval flow, redactors, and runtime gates.
 - [Storage](./storage.md) — SQLite schema, scopes, and lifecycle.
 - [Providers](./providers.md) — adapter contract and how to add a new provider.