vgxness 1.6.0 → 1.8.0

package/dist/mcp/provider-change-plan.js

@@ -2,12 +2,10 @@ import { resolveMemoryDatabasePath } from '../memory/storage-paths.js';
 import { planClaudeCodeMcpInstall } from './client-install-claude-code-contract.js';
 import { planOpenCodeMcpInstall } from './client-install-opencode-contract.js';
 import { ProviderDoctorService } from './provider-doctor.js';
-import { CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, isUserGlobalScope } from './provider-health-types.js';
 import { ProviderStatusService } from './provider-status.js';
-import { createClaudeCodeCliRegistrationPreview } from './claude-code-cli.js';
 import { resolveClaudeCodeScope } from './claude-code-scope.js';
 export const providerChangePlanProviders = ['opencode', 'claude', 'antigravity', 'custom'];
-export const providerChangePlanTypes = ['opencode-mcp-install', 'setup', 'install', 'config-preparation'];
+export const providerChangePlanTypes = ['opencode-mcp-install', 'claude-mcp-install', 'setup', 'install', 'config-preparation'];
 const safety = {
     readOnly: true,
     willWrite: false,
@@ -81,51 +79,13 @@ export class ProviderChangePlanService {
         const claudeScope = resolveClaudeCodeScope(normalized.scope);
         if (!claudeScope.ok)
             return claudeScope;
-        if (isUserGlobalScope(normalized.scope) || claudeScope.value.canonical === 'local')
-            return { ok: true, value: claudeUserGlobalEnvelope(normalized, status.value, doctor.value, claudeScope.value.canonical, claudeScope.value.warnings) };
         const databasePath = resolveMemoryDatabasePath({ cwd: normalized.workspaceRoot, env: this.deps.env ?? process.env });
         if (!databasePath.ok)
             return { ok: true, value: blockedPlanEnvelope(normalized, status.value, doctor.value, databasePath.error.message) };
-        const installPlan = planClaudeCodeMcpInstall({ cwd: normalized.workspaceRoot, databasePath: databasePath.value.path, databasePathSource: databasePath.value.source });
+        const installPlan = planClaudeCodeMcpInstall({ cwd: normalized.workspaceRoot, databasePath: databasePath.value.path, databasePathSource: databasePath.value.source, scope: normalized.scope, env: this.deps.env ?? process.env });
         return { ok: true, value: claudeEnvelope(normalized, status.value, doctor.value, installPlan, databasePath.value.source) };
     }
 }
-function claudeUserGlobalEnvelope(input, status, doctor, canonicalScope = 'user', scopeWarnings = []) {
-    const warnings = [
-        ...scopeWarnings,
-        ...statusWarnings(status),
-        ...doctor.recommendations,
-        'Claude private config mutation is intentionally unsupported by VGXNESS; future apply uses Claude CLI argv only after confirmation/preflight.',
-    ];
-    const envelope = {
-        ...baseEnvelope(input),
-        supported: true,
-        status: 'planned',
-        summary: `Read-only Claude ${canonicalScope} change planning completed. VGXNESS will not read or write private Claude config files from this plan. Future apply requires confirmation/preflight and uses Claude CLI argv only: claude mcp add --scope ${canonicalScope} vgxness -- vgxness mcp start.`,
-        providerIdentity: { provider: 'claude', adapter: 'claude', support: 'supported' },
-        statusSummary: statusSummary(status),
-        statusFindings: status.config,
-        doctorSummary: doctorSummary(doctor),
-        doctorFindings: doctor.checks,
-        previewEffects: {
-            action: 'none',
-            backupRequired: false,
-            preservedTopLevelKeys: [],
-            cliCommandPreview: createClaudeCodeCliRegistrationPreview(canonicalScope),
-            installsAgents: false,
-            agentNames: [],
-            refusalMessage: 'Read-only plan only; future apply requires confirmation/preflight and does not mutate ~/.claude.json manually.',
-        },
-        backupRollback: descriptiveBackupPolicy(false),
-        confirmations: confirmationPolicy(),
-        risks: [
-            `VGXNESS cannot verify Claude ${canonicalScope} MCP registration from read-only planning because it intentionally avoids reading private Claude config and does not execute Claude Code.`,
-            `Supported Claude read-only capabilities are: ${CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES.join(', ')}.`,
-        ],
-        warnings,
-    };
-    return input.payloadMode === 'verbose' ? { ...envelope, rawSources: { status, doctor } } : envelope;
-}
 function normalizeInput(input) {
     return {
         project: input.project?.trim() || 'vgxness',
@@ -142,7 +102,7 @@ function unsupportedProviderEnvelope(input) {
         supported: false,
         status: 'unsupported',
         code: 'UNSUPPORTED_PROVIDER',
-        summary: `${input.provider} is a recognized provider value, but provider change planning is currently implemented only for OpenCode.`,
+        summary: `${input.provider} is a recognized provider value, but read-only provider change planning currently supports OpenCode and Claude.`,
         providerIdentity: {
             provider: input.provider,
             adapter: input.provider,
@@ -160,15 +120,16 @@ function unsupportedProviderEnvelope(input) {
     };
 }
 function blockedPlanEnvelope(input, status, doctor, message) {
+    const providerName = input.provider === 'claude' ? 'Claude' : 'OpenCode';
     return {
         ...baseEnvelope(input),
         supported: true,
         status: 'blocked',
         code: 'PLAN_UNAVAILABLE',
-        summary: `OpenCode change planning could not resolve the future MCP server command: ${message}`,
+        summary: `${providerName} change planning could not resolve the future MCP server command: ${message}`,
         providerIdentity: {
-            provider: 'opencode',
-            adapter: 'opencode',
+            provider: input.provider,
+            adapter: input.provider,
             support: 'supported',
         },
         statusSummary: statusSummary(status),
@@ -224,7 +185,7 @@ function claudeEnvelope(input, status, doctor, installPlan, source) {
         supported: true,
         status: installPlan.status === 'refused' ? 'blocked' : 'planned',
         ...(installPlan.status === 'refused' ? { code: 'PLAN_UNAVAILABLE' } : {}),
-        summary: installPlan.status === 'refused' ? `Read-only Claude ${input.changeType} planning completed; future install is currently refused: ${installPlan.message}` : `Read-only Claude ${input.changeType} planning completed; future confirmed write would update project .mcp.json, ${installPlan.agentNames.length} agent file(s), and project-root CLAUDE.md as needed.`,
+        summary: installPlan.status === 'refused' ? `Read-only Claude ${input.changeType} planning completed; future install is currently refused: ${installPlan.message}` : `Read-only Claude ${input.changeType} planning completed; future confirmed write would update ${installPlan.canonicalClaudeScope === 'user' ? '~/.claude.json, user agents, and ~/.claude/CLAUDE.md' : 'project .mcp.json, agent files, and project-root CLAUDE.md'} as needed.`,
         providerIdentity: { provider: 'claude', adapter: 'claude', support: 'supported' },
         statusSummary: statusSummary(status),
         statusFindings: status.config,
@@ -246,14 +207,24 @@ function baseEnvelope(input) {
         scope: input.scope,
         provider: input.provider,
         requestedChangeType: input.changeType,
-        normalizedChangeType: normalizeChangeType(input.changeType),
+        normalizedChangeType: normalizeChangeType(input.provider, input.changeType),
         payloadMode: input.payloadMode,
         workspaceRoot: input.workspaceRoot,
         safety,
     };
 }
-function normalizeChangeType(changeType) {
-    return changeType === 'setup' || changeType === 'install' || changeType === 'config-preparation' ? 'opencode-mcp-install' : changeType;
+function normalizeChangeType(provider, changeType) {
+    if (provider === 'opencode') {
+        return changeType === 'setup' || changeType === 'install' || changeType === 'config-preparation' || changeType === 'claude-mcp-install'
+            ? 'opencode-mcp-install'
+            : changeType;
+    }
+    if (provider === 'claude') {
+        return changeType === 'setup' || changeType === 'install' || changeType === 'config-preparation' || changeType === 'opencode-mcp-install'
+            ? 'claude-mcp-install'
+            : changeType;
+    }
+    return changeType;
 }
 function statusSummary(status) {
     return {
@@ -309,11 +280,11 @@ function previewEffectsClaude(plan) {
     const projectMemory = projectMemoryPreview(plan.targets);
     if (plan.status === 'refused')
         return { action: 'refused', targetPath: plan.targetPath, backupRequired: false, preservedTopLevelKeys: plan.preservedTopLevelKeys, serverCommand: ['vgxness', ...plan.server.args], installsAgents: true, agentNames: plan.agentNames, installPlanStatus: 'refused', refusalReason: plan.reason, refusalMessage: plan.message, ...(projectMemory === undefined ? {} : { projectMemory }) };
-    const mcpTarget = plan.targets.find((target) => target.kind === 'mcp-json');
+    const mcpTarget = plan.targets.find((target) => target.kind === 'mcp-json' || target.kind === 'user-mcp-json');
     return { action: mcpTarget?.action === 'create' ? 'would-create' : 'would-merge', targetPath: plan.targetPath, backupRequired: plan.backupRequired, preservedTopLevelKeys: plan.preservedTopLevelKeys, serverCommand: ['vgxness', ...plan.server.args], installsAgents: true, agentNames: plan.agentNames, installPlanStatus: 'would_install', ...(projectMemory === undefined ? {} : { projectMemory }) };
 }
 function projectMemoryPreview(targets) {
-    const target = targets.find((item) => item.kind === 'project-memory');
+    const target = targets.find((item) => item.kind === 'project-memory' || item.kind === 'user-memory');
     if (target === undefined)
         return undefined;
     const action = target.action === 'create' ? 'would-create' : target.action === 'append-managed-block' ? 'would-append' : target.action === 'update-managed-block' ? 'would-update-managed-block' : target.action === 'none' ? 'up-to-date' : 'refused';
@@ -352,7 +323,7 @@ function risksForOpenCode(status, doctor, plan, source) {
     return risks;
 }
 function risksForClaude(status, doctor, plan, source) {
-    const risks = ['Claude project .mcp.json and project-root CLAUDE.md may affect collaborators if committed; review before committing.', 'Claude Code runtime MCP approval happens in Claude Code; this plan does not prove runtime connection.'];
+    const risks = [plan.canonicalClaudeScope === 'user' ? 'Claude user/global files affect this OS user; backups are required before merging existing files.' : 'Claude project .mcp.json and project-root CLAUDE.md may affect collaborators if committed; review before committing.', 'Claude Code runtime MCP approval happens in Claude Code; this plan does not prove runtime connection.'];
     if (status.status !== 'ready')
         risks.push(`Provider status is ${status.status}; future writes should review status findings first.`);
     if (doctor.status !== 'healthy')

package/dist/mcp/provider-doctor.js

@@ -3,6 +3,8 @@ import { inspectClaudeCodeAgents } from './claude-code-agent-config.js';
 import { claudeAdvisoryPaths, inspectClaudeCodeMcpConfig } from './claude-code-config.js';
 import { inspectClaudeProjectMemory } from './claude-code-project-memory.js';
 import { resolveClaudeCodeScope } from './claude-code-scope.js';
+import { inspectClaudeCodeUserMcpConfig } from './claude-code-user-config.js';
+import { inspectClaudeUserMemory } from './claude-code-user-memory.js';
 import { vgxnessOpenCodeDefaultAgent, vgxnessOpenCodeSddSubagents } from './opencode-default-agent-config.js';
 import { buildCanonicalAgentManifestDiagnostic } from './provider-canonical-agent-manifest.js';
 import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, providerHealthFailure, isUserGlobalScope, REQUIRED_PROVIDER_NATIVE_MCP_TOOLS, rollupProviderDoctor, } from './provider-health-types.js';
@@ -132,21 +134,35 @@ export class ProviderDoctorService {
         return { ok: true, value: { version: 1, kind: 'provider-doctor', project: normalized.project, providerAdapter: 'claude', scope: normalized.scope, workspaceRoot: normalized.workspaceRoot, status, payloadMode: normalized.payloadMode, overallStatus: status, checkCount: checks.length, passedCount: checks.filter((check) => check.status === 'pass').length, warningCount: checks.filter((check) => check.status === 'warn' || check.status === 'not-configured').length, errorCount: failedChecks.length, skippedCount: checks.filter((check) => check.status === 'skip').length, failedChecks, summary: summarizeDoctor(status, failedChecks.length, recommendations.length), recommendations, checks: compactChecksValue, checkedPaths, bytes: { originalBytes: Buffer.byteLength(JSON.stringify({ checks, checkedPaths: checkedPathList }), 'utf8'), compactBytes: Buffer.byteLength(JSON.stringify({ checks: compactChecksValue, checkedPaths }), 'utf8') }, verboseAvailable: normalized.payloadMode === 'compact', fullContentRef: `provider-doctor:claude:${normalized.workspaceRoot}`, generatedAt: 'read-only-snapshot', safety: PROVIDER_HEALTH_SAFETY } };
     }
     getClaudeUserGlobalDoctor(normalized, canonicalScope = 'user', scopeWarnings = []) {
+        const mcp = inspectClaudeCodeUserMcpConfig(normalized.env);
+        const agents = inspectClaudeCodeAgents({ workspaceRoot: normalized.workspaceRoot, scope: 'user', env: normalized.env });
+        const userMemory = inspectClaudeUserMemory(normalized.env);
+        const checkedPathList = [mcp.path, agents.directoryPath, ...agents.agents.map((agent) => agent.path), userMemory.path];
+        const before = snapshotPaths(checkedPathList, normalized.workspaceRoot);
+        const missingAgents = agents.agents.filter((agent) => agent.status === 'missing');
+        const blockingAgents = agents.agents.filter((agent) => agent.status === 'conflicting' || agent.status === 'invalid');
+        const badFrontmatter = agents.agents.filter((agent) => agent.exists && agent.frontmatter === 'invalid');
+        const badMarkers = agents.agents.filter((agent) => agent.exists && !agent.generatedMarker);
         const checks = [
             { id: 'workspace-root', status: existsSync(normalized.workspaceRoot) ? 'pass' : 'fail', detail: `Workspace root ${existsSync(normalized.workspaceRoot) ? 'exists' : 'does not exist'}: ${normalized.workspaceRoot}` },
-            { id: 'provider-supported', status: 'warn', detail: `Claude ${canonicalScope} scope is supported as read-only advisory status/doctor/change-plan. Future install requires explicit confirmation/preflight and Claude CLI; private config mutation is unsupported.` },
+            { id: 'provider-supported', status: 'pass', detail: `Claude ${canonicalScope} scope supports guarded ~/.claude.json MCP merge, user agents, and ~/.claude/CLAUDE.md managed block after confirmation/preflight.` },
             { id: 'claude-scope', status: scopeWarnings.length === 0 ? 'pass' : 'warn', detail: scopeWarnings.join(' ') || `Claude scope resolved to canonical ${canonicalScope}.` },
             { id: 'claude-cli-presence', status: 'warn', detail: 'Read-only doctor does not execute `claude --version`; no provider process was launched.' },
-            { id: 'provider-config-readonly-safety', status: 'pass', detail: `No Claude ${canonicalScope} paths were inspected or mutated; no repair/install/write occurred.` },
+            { id: 'claude-user-mcp-readable', status: mcp.status === 'invalid' ? 'fail' : mcp.status === 'missing' ? 'not-configured' : 'pass', detail: mcp.message, ...(mcp.status === 'invalid' ? { remediation: 'Fix malformed ~/.claude.json before installing VGXNESS Claude user support.' } : {}) },
+            { id: 'claude-user-vgxness-mcp-entry', status: mcp.status === 'configured' ? 'pass' : mcp.status === 'conflicting' ? 'fail' : 'not-configured', detail: mcp.message, ...(mcp.status === 'conflicting' ? { remediation: 'Manually reconcile mcpServers.vgxness in ~/.claude.json before applying VGXNESS Claude user support.' } : {}) },
+            { id: 'claude-user-agents-directory', status: agents.directoryExists ? 'pass' : 'not-configured', detail: agents.directoryExists ? 'Claude user agents directory exists.' : 'Claude user agents directory is missing; confirmed apply may create it.' },
+            { id: 'claude-user-vgxness-agents', status: blockingAgents.length > 0 ? 'fail' : missingAgents.length > 0 ? 'not-configured' : 'pass', detail: blockingAgents.length > 0 ? `Conflicting or invalid VGXNESS Claude user agents: ${blockingAgents.map((agent) => agent.agentName).join(', ')}.` : missingAgents.length > 0 ? `Missing VGXNESS Claude user agents: ${missingAgents.map((agent) => agent.agentName).join(', ')}.` : 'Expected VGXNESS Claude user agent targets were inspected.' },
+            { id: 'claude-user-agent-frontmatter', status: badFrontmatter.length === 0 ? 'pass' : 'fail', detail: badFrontmatter.length === 0 ? 'Expected Claude user agent frontmatter is valid.' : `Invalid or missing frontmatter for: ${badFrontmatter.map((agent) => agent.agentName).join(', ')}.` },
+            { id: 'claude-user-agent-generated-metadata', status: badMarkers.length === 0 ? 'pass' : 'fail', detail: badMarkers.length === 0 ? 'Existing VGXNESS Claude user agent files include generated metadata markers.' : `Missing VGXNESS generated marker for: ${badMarkers.map((agent) => agent.agentName).join(', ')}.` },
+            { ...claudeProjectMemoryCheck(userMemory), id: 'claude-user-memory-managed-block' },
+            readonlySafetyCheck(before, snapshotPaths(checkedPathList, normalized.workspaceRoot)),
         ];
         const status = rollupProviderDoctor(checks.map((check) => check.status));
         const compactChecksValue = compactChecks(checks, normalized.payloadMode);
         const failedChecks = checks.filter((check) => check.status === 'fail').map((check) => check.id);
-        const recommendations = [
-            `If you choose to configure Claude ${canonicalScope} scope manually, run Claude Code yourself and use a command like: claude mcp add --scope ${canonicalScope} vgxness -- vgxness mcp start.`,
-            'VGXNESS will not read or write private Claude config files during status/doctor/change-plan, repair config, or execute Claude Code from read-only surfaces.',
-        ];
-        return { ok: true, value: { version: 1, kind: 'provider-doctor', project: normalized.project, providerAdapter: 'claude', scope: normalized.scope, workspaceRoot: normalized.workspaceRoot, status, payloadMode: normalized.payloadMode, overallStatus: status, checkCount: checks.length, passedCount: checks.filter((check) => check.status === 'pass').length, warningCount: checks.filter((check) => check.status === 'warn' || check.status === 'not-configured').length, errorCount: failedChecks.length, skippedCount: checks.filter((check) => check.status === 'skip').length, failedChecks, summary: `Claude ${canonicalScope} doctor is advisory and read-only; no private Claude files were inspected, no config was changed, and Claude Code was not executed.`, recommendations, checks: compactChecksValue, checkedPaths: [], bytes: { originalBytes: Buffer.byteLength(JSON.stringify({ checks, checkedPaths: [] }), 'utf8'), compactBytes: Buffer.byteLength(JSON.stringify({ checks: compactChecksValue, checkedPaths: [] }), 'utf8') }, verboseAvailable: normalized.payloadMode === 'compact', fullContentRef: `provider-doctor:claude:${canonicalScope}:${normalized.workspaceRoot}`, generatedAt: 'read-only-snapshot', safety: { ...PROVIDER_HEALTH_SAFETY, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES } } };
+        const recommendations = checks.flatMap((check) => (check.remediation === undefined ? [] : [check.remediation]));
+        const checkedPaths = normalized.payloadMode === 'verbose' ? checkedPathList : checkedPathList.filter((path) => existsSync(path) || path === mcp.path || path === userMemory.path);
+        return { ok: true, value: { version: 1, kind: 'provider-doctor', project: normalized.project, providerAdapter: 'claude', scope: normalized.scope, workspaceRoot: normalized.workspaceRoot, status, payloadMode: normalized.payloadMode, overallStatus: status, checkCount: checks.length, passedCount: checks.filter((check) => check.status === 'pass').length, warningCount: checks.filter((check) => check.status === 'warn' || check.status === 'not-configured').length, errorCount: failedChecks.length, skippedCount: checks.filter((check) => check.status === 'skip').length, failedChecks, summary: summarizeDoctor(status, failedChecks.length, recommendations.length), recommendations, checks: compactChecksValue, checkedPaths, bytes: { originalBytes: Buffer.byteLength(JSON.stringify({ checks, checkedPaths: checkedPathList }), 'utf8'), compactBytes: Buffer.byteLength(JSON.stringify({ checks: compactChecksValue, checkedPaths }), 'utf8') }, verboseAvailable: normalized.payloadMode === 'compact', fullContentRef: `provider-doctor:claude:${canonicalScope}:${normalized.workspaceRoot}`, generatedAt: 'read-only-snapshot', safety: { ...PROVIDER_HEALTH_SAFETY, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES } } };
     }
 }
 function summarizeDoctor(status, failedCount, recommendationCount) {

package/dist/mcp/provider-status.js

@@ -1,10 +1,11 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { inspectClaudeCodeAgents } from './claude-code-agent-config.js';
-import { createClaudeCodeCliRegistrationPreview } from './claude-code-cli.js';
 import { claudeAdvisoryPaths, claudeMcpConfigPathStatus, claudeMcpEntryStatus, inspectClaudeCodeMcpConfig } from './claude-code-config.js';
 import { inspectClaudeProjectMemory } from './claude-code-project-memory.js';
 import { resolveClaudeCodeScope } from './claude-code-scope.js';
+import { claudeUserMcpConfigPathStatus, claudeUserMcpEntryStatus, inspectClaudeCodeUserMcpConfig } from './claude-code-user-config.js';
+import { inspectClaudeUserMemory } from './claude-code-user-memory.js';
 import { resolveOpenCodeMcpInstallTarget } from './client-install-opencode-contract.js';
 import { vgxnessOpenCodeDefaultAgent, vgxnessOpenCodePromptContractVersion, vgxnessOpenCodeSddSubagents } from './opencode-default-agent-config.js';
 import { buildCanonicalAgentManifestDiagnostic } from './provider-canonical-agent-manifest.js';
@@ -147,28 +148,20 @@ export class ProviderStatusService {
     }
     getClaudeUserGlobalStatus(normalized, canonicalScope = 'user', scopeWarnings = []) {
         const canonicalAgentManifest = (this.deps.canonicalAgentManifestDiagnostic ?? buildCanonicalAgentManifestDiagnostic)();
-        const paths = [
-            {
-                label: `Claude ${canonicalScope} scope`,
-                path: `${canonicalScope} Claude configuration (not inspected)`,
-                exists: false,
-                readable: false,
-                parsed: false,
-                status: 'warn',
-                detail: `Claude ${canonicalScope} scope is advisory only in read-only status: VGXNESS does not read private Claude files, write config, execute Claude Code, or install provider config.`,
-            },
-        ];
-        const mcpEntry = {
-            configured: false,
-            status: 'warn',
-            serverName: 'vgxness',
-            detail: `${canonicalScope} Claude MCP status is not inspected by VGXNESS; use this as planning guidance only. Future apply uses Claude CLI argv only: ${createClaudeCodeCliRegistrationPreview(canonicalScope).join(' ')}`,
-        };
-        const tools = requiredToolPresence();
-        const status = rollupProviderHealth([canonicalAgentManifest.status, 'warn']);
+        const mcpState = inspectClaudeCodeUserMcpConfig(normalized.env);
+        const agents = inspectClaudeCodeAgents({ workspaceRoot: normalized.workspaceRoot, scope: 'user', env: normalized.env });
+        const userMemory = inspectClaudeUserMemory(normalized.env);
+        const userMemoryPathStatus = { ...claudeProjectMemoryPathStatus(userMemory), label: 'user ~/.claude/CLAUDE.md managed block' };
+        const paths = [claudeUserMcpConfigPathStatus(mcpState), userMemoryPathStatus];
+        const mcpEntry = claudeUserMcpEntryStatus(mcpState);
+        const agentStatuses = agents.agents.map((agent) => (agent.status === 'managed' ? 'pass' : agent.status === 'missing' ? 'not-configured' : 'fail'));
+        const configStatus = claudeConfigHealthStatus([...paths.map((path) => path.status), ...agentStatuses]);
+        const tools = [...requiredToolPresence(), { tool: 'claude-cli', present: false, diagnostic: 'Read-only status does not execute `claude --version`; no Claude Code process was launched.' }];
+        const status = rollupProviderHealth([canonicalAgentManifest.status, configStatus]);
         const sdd = normalized.change.length > 0 ? this.readSdd(normalized.project, normalized.change) : undefined;
-        const verboseShape = { config: { status: 'warn', paths, mcpEntry }, canonicalAgentManifest, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, scopeWarnings, sdd, mcpRequiredTools: tools };
-        const compactShape = { config: { status: 'warn', paths: compactPaths(paths, 'compact'), mcpEntry: compactMcpEntry(mcpEntry, 'compact') }, canonicalAgentManifest, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, sdd: sdd === undefined ? undefined : compactSdd(sdd, 'compact'), mcpRequiredTools: tools };
+        const checkedPaths = normalized.payloadMode === 'verbose' ? [mcpState.path, agents.directoryPath, ...agents.agents.map((agent) => agent.path), userMemory.path] : [mcpState.path, userMemory.path, ...agents.agents.filter((agent) => agent.exists || agent.status !== 'missing').map((agent) => agent.path)];
+        const verboseShape = { config: { status: configStatus, paths, mcpEntry }, canonicalAgentManifest, agents, userMemory: { status: userMemory.status, action: userMemory.action }, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, scopeWarnings, sdd, mcpRequiredTools: tools };
+        const compactShape = { config: { status: configStatus, paths: compactPaths(paths, 'compact'), mcpEntry: compactMcpEntry(mcpEntry, 'compact') }, canonicalAgentManifest, agentSummary: summarizeClaudeAgents(agents), userMemory: { status: userMemory.status, action: userMemory.action }, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, sdd: sdd === undefined ? undefined : compactSdd(sdd, 'compact'), mcpRequiredTools: tools };
         return {
             ok: true,
             value: {
@@ -181,14 +174,14 @@ export class ProviderStatusService {
                 status,
                 payloadMode: normalized.payloadMode,
                 overallStatus: status,
-                inspectedPaths: [],
-                issueCount: canonicalAgentManifest.status === 'fail' ? 1 : 0,
-                warningCount: 1 + scopeWarnings.length,
-                summary: `Claude ${canonicalScope} scope status is read-only/advisory; no private Claude files are inspected or written, and Claude Code is not executed.`,
-                nextAction: { kind: 'review', message: 'Review the planning-only guidance; future apply requires explicit confirmation/preflight and uses Claude CLI argv, not private config mutation.' },
-                checkedPaths: [],
+                inspectedPaths: checkedPaths,
+                issueCount: [canonicalAgentManifest.status, configStatus, ...agentStatuses].filter((item) => item === 'fail' || item === 'not-configured').length,
+                warningCount: scopeWarnings.length + paths.filter((path) => path.status === 'warn').length + 1,
+                summary: summarizeClaudeStatus(status, mcpEntry),
+                nextAction: nextActionFor(status, mcpEntry, sdd?.next),
+                checkedPaths,
                 canonicalAgentManifest,
-                config: { status: 'warn', paths: compactPaths(paths, normalized.payloadMode), mcpEntry: compactMcpEntry(mcpEntry, normalized.payloadMode) },
+                config: { status: configStatus, paths: compactPaths(paths, normalized.payloadMode), mcpEntry: compactMcpEntry(mcpEntry, normalized.payloadMode) },
                 ...(sdd === undefined ? {} : { sdd: compactSdd(sdd, normalized.payloadMode) }),
                 mcpRequiredTools: tools,
                 originalBytes: Buffer.byteLength(JSON.stringify(verboseShape), 'utf8'),

package/dist/mcp/schema.js

@@ -99,7 +99,7 @@ const finalRunStatuses = ['completed', 'failed', 'blocked', 'cancelled'];
 const runOutcomes = ['success', 'partial', 'failure', 'blocked', 'cancelled'];
 const payloadModes = ['compact', 'verbose'];
 const providerChangePlanProviders = ['opencode', 'claude', 'antigravity', 'custom'];
-const providerChangePlanTypes = ['opencode-mcp-install', 'setup', 'install', 'config-preparation'];
+const providerChangePlanTypes = ['opencode-mcp-install', 'claude-mcp-install', 'setup', 'install', 'config-preparation'];
 const jsonValueSchema = z.lazy(() => z.union([z.string(), z.number().finite(), z.boolean(), z.null(), z.array(jsonValueSchema), z.record(z.string(), jsonValueSchema)]));
 export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
     vgxness_sdd_status: z

package/dist/mcp/validation.js

@@ -13,7 +13,7 @@ const runOutcomes = ['success', 'partial', 'failure', 'blocked', 'cancelled'];
 const permissionDecisions = ['allow', 'ask', 'deny'];
 const payloadModes = ['compact', 'verbose'];
 const providerChangePlanProviders = ['opencode', 'claude', 'antigravity', 'custom'];
-const providerChangePlanTypes = ['opencode-mcp-install', 'setup', 'install', 'config-preparation'];
+const providerChangePlanTypes = ['opencode-mcp-install', 'claude-mcp-install', 'setup', 'install', 'config-preparation'];
 const validChangePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const validMemoryTopicKeyPattern = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
 const maxMemoryTitleLength = 200;

package/dist/sdd/schema.js

@@ -1,5 +1,20 @@
 import { z } from 'zod';
 export const sddPhases = ['explore', 'proposal', 'spec', 'design', 'tasks', 'apply-progress', 'verify', 'archive'];
+/**
+ * Governance status of an SDD artifact.
+ *
+ * - `draft`     — present in the DB; satisfies downstream readiness when the
+ *                 `VGXNESS_SDD_AUTO_ADVANCE` feature flag is on (or
+ *                 `SddWorkflowService` is constructed with `autoAdvance: true`).
+ *                 Does NOT count toward the change being `complete`.
+ * - `accepted`  — content has been frozen by an explicit human
+ *                 `vgxness_sdd_accept_artifact` call. Satisfies downstream
+ *                 readiness regardless of the auto-advance flag.
+ * - `rejected`  — explicit human rejection. Hard-blocker for downstream
+ *                 readiness; can only be cleared by re-opening the artifact.
+ * - `superseded`— replaced by a newer artifact under a different topic key.
+ *                 Hard-blocker; cannot be re-saved or accepted.
+ */
 export const sddArtifactStatuses = ['draft', 'accepted', 'rejected', 'superseded'];
 export const sddArtifactNormalizationWarnings = ['legacy-artifact-defaulted-to-draft', 'invalid-artifact-metadata-defaulted-to-draft'];
 export const SddArtifactStatusSchema = z.enum(sddArtifactStatuses);

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

@@ -2,12 +2,32 @@ import { summarizePayloadContent } from '../payload/payload-summary.js';
 import { isSddPhase, normalizeSddArtifact, sddPhases, sddPrerequisites, sddTopicKey, } from './schema.js';
 const defaultContext = { actor: 'sdd-workflow-service' };
 const validChangePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function readAutoAdvanceFromEnv() {
+    const value = process.env.VGXNESS_SDD_AUTO_ADVANCE;
+    return value === 'true' || value === '1';
+}
+function isPrerequisiteSatisfied(status) {
+    if (status === undefined)
+        return false;
+    if (status.legacy === true)
+        return false;
+    if (status.accepted === true)
+        return true;
+    if (status.state === 'draft')
+        return true;
+    return false;
+}
 export class SddWorkflowService {
     memory;
     context;
-    constructor(memory, context = defaultContext) {
+    options;
+    constructor(memory, context = defaultContext, options = {}) {
         this.memory = memory;
         this.context = context;
+        this.options = {
+            ...options,
+            autoAdvance: options.autoAdvance ?? readAutoAdvanceFromEnv(),
+        };
     }
     getWorkflow(change) {
         return sddPhases.map((phase) => ({
@@ -23,7 +43,7 @@ export class SddWorkflowService {
         const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
         if (!phases.ok)
             return phases;
-        const readiness = getReadinessFromStatuses(validated.value.change, validated.value.phase, phases.value);
+        const readiness = getReadinessFromStatuses(validated.value.change, validated.value.phase, phases.value, this.options);
         return {
             ok: true,
             value: {
@@ -40,7 +60,7 @@ export class SddWorkflowService {
         const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
         if (!phases.ok)
             return phases;
-        return statusFromPhases(validated.value.change, phases.value);
+        return statusFromPhases(validated.value.change, phases.value, this.options);
     }
     getNext(input) {
         const validated = validateProjectAndChange(input.project, input.change);
@@ -49,7 +69,7 @@ export class SddWorkflowService {
         const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
         if (!phases.ok)
             return phases;
-        return ok(nextDecisionFromStatuses(validated.value.change, phases.value));
+        return ok(nextDecisionFromStatuses(validated.value.change, phases.value, this.options));
     }
     getCockpit(input) {
         const validated = validateProjectAndChange(input.project, input.change);
@@ -59,12 +79,12 @@ export class SddWorkflowService {
         if (!snapshot.ok)
             return snapshot;
         const phases = snapshot.value.phases;
-        const next = nextDecisionFromStatuses(validated.value.change, phases);
+        const next = nextDecisionFromStatuses(validated.value.change, phases, this.options);
         const cockpitPhases = phases.map((phaseStatus) => {
             const readiness = {
                 change: validated.value.change,
                 phase: phaseStatus.phase,
-                ...getReadinessFromStatuses(validated.value.change, phaseStatus.phase, phases),
+                ...getReadinessFromStatuses(validated.value.change, phaseStatus.phase, phases, this.options),
             };
             const artifact = phaseStatus.present ? cockpitArtifactSummaryFromSnapshotItem(phaseStatus) : undefined;
             const blockers = cockpitBlockersForPhase(phaseStatus, readiness);
@@ -115,7 +135,7 @@ export class SddWorkflowService {
         if (!snapshot.ok)
             return snapshot;
         const phases = snapshot.value.phases;
-        const status = statusFromPhases(validated.value.change, phases);
+        const status = statusFromPhases(validated.value.change, phases, this.options);
         if (!status.ok)
             return status;
         const warnings = [];
@@ -137,7 +157,7 @@ export class SddWorkflowService {
             }
             return [{ phase: phase.phase, topicKey: phase.topicKey, artifact: phase.artifact, envelope }];
         });
-        const readiness = input.phase === undefined ? undefined : { change: validated.value.change, phase: input.phase, ...getReadinessFromStatuses(validated.value.change, input.phase, phases) };
+        const readiness = input.phase === undefined ? undefined : { change: validated.value.change, phase: input.phase, ...getReadinessFromStatuses(validated.value.change, input.phase, phases, this.options) };
         return ok({ status: status.value, artifacts, ...(readiness === undefined ? {} : { readiness }), warnings });
     }
     saveArtifact(input) {
@@ -146,13 +166,20 @@ export class SddWorkflowService {
             return validated;
         if (input.content.trim().length === 0)
             return validationFailure('SDD artifact content must not be empty');
-        return this.memory.saveArtifact({
-            project: validated.value.project,
-            topicKey: sddTopicKey(validated.value.change, validated.value.phase),
-            phase: validated.value.phase,
-            content: input.content,
-            metadata: { status: 'draft' },
-        }, this.context);
+        const { project, change, phase } = validated.value;
+        const topicKey = sddTopicKey(change, phase);
+        const existing = this.memory.getArtifact(project, topicKey, this.context);
+        if (existing.ok) {
+            const envelope = normalizeSddArtifact(existing.value);
+            const status = envelope.metadata.status;
+            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.');
+            if (status === 'superseded')
+                return validationFailure('Cannot overwrite a superseded SDD artifact.');
+        }
+        return this.memory.saveArtifact({ project, topicKey, phase, content: input.content, metadata: { status: 'draft' } }, this.context);
     }
     acceptArtifact(input) {
         const validated = this.validatePhaseInput(input);
@@ -169,6 +196,11 @@ export class SddWorkflowService {
         if (!existing.ok)
             return existing;
         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.');
+        if (existingStatus === 'superseded')
+            return validationFailure('Cannot accept a superseded SDD artifact; create a new artifact under a different topic key instead.');
         const acceptance = {
             actor: {
                 type: 'human',
@@ -203,7 +235,7 @@ export class SddWorkflowService {
         const statuses = this.getPhaseStatuses(validated.value.project, validated.value.change);
         if (!statuses.ok)
             return statuses;
-        return ok(compactArtifactProjection(artifact.value, validated.value.change, validated.value.phase, getReadinessFromStatuses(validated.value.change, validated.value.phase, statuses.value)));
+        return ok(compactArtifactProjection(artifact.value, validated.value.change, validated.value.phase, getReadinessFromStatuses(validated.value.change, validated.value.phase, statuses.value, this.options)));
     }
     listArtifacts(input) {
         const validated = validateProjectAndChange(input.project, input.change);
@@ -219,7 +251,7 @@ export class SddWorkflowService {
                 artifacts: snapshot.value.phases.flatMap((phase) => {
                     if (phase.artifact === undefined)
                         return [];
-                    return [compactArtifactProjection(phase.artifact, validated.value.change, phase.phase, getReadinessFromStatuses(validated.value.change, phase.phase, snapshot.value.phases))];
+                    return [compactArtifactProjection(phase.artifact, validated.value.change, phase.phase, getReadinessFromStatuses(validated.value.change, phase.phase, snapshot.value.phases, this.options))];
                 }),
                 fullRetrieval: {
                     tool: 'vgxness_sdd_list_artifacts',
@@ -280,14 +312,14 @@ export class SddWorkflowService {
         return ok({ project, change, phases });
     }
 }
-export function nextDecisionFromStatuses(change, phases) {
+export function nextDecisionFromStatuses(change, phases, options = {}) {
     const blockedPresentPhase = phases.find((status) => {
         if (!status.present)
             return false;
-        return (getReadinessFromStatuses(change, status.phase, phases).blockedPrerequisites ?? []).length > 0;
+        return (getReadinessFromStatuses(change, status.phase, phases, options).blockedPrerequisites ?? []).length > 0;
     });
     if (blockedPresentPhase !== undefined) {
-        const readiness = getReadinessFromStatuses(change, blockedPresentPhase.phase, phases);
+        const readiness = getReadinessFromStatuses(change, blockedPresentPhase.phase, phases, options);
         const blockers = readiness.blockedPrerequisites ?? [];
         return {
             change,
@@ -329,7 +361,7 @@ export function nextDecisionFromStatuses(change, phases) {
             recommendedAction: 'No next SDD phase remains for this change.',
         };
     }
-    const readiness = getReadinessFromStatuses(change, nextMissingPhase, phases);
+    const readiness = getReadinessFromStatuses(change, nextMissingPhase, phases, options);
     if (!readiness.ready) {
         const blockers = readiness.blockedPrerequisites ?? [];
         return {
@@ -352,24 +384,26 @@ export function nextDecisionFromStatuses(change, phases) {
         recommendedAction: `Run the ${nextMissingPhase} SDD phase for ${change}.`,
     };
 }
-function statusFromPhases(change, phases) {
+function statusFromPhases(change, phases, options = {}) {
     const nextReadyPhase = sddPhases.find((phase) => {
         if (phases.find((status) => status.phase === phase)?.present)
             return false;
-        return getReadinessFromStatuses(change, phase, phases).ready;
+        return getReadinessFromStatuses(change, phase, phases, options).ready;
     });
     const status = { change, phases };
     if (nextReadyPhase !== undefined)
         status.nextReadyPhase = nextReadyPhase;
     return { ok: true, value: status };
 }
-function getReadinessFromStatuses(change, phase, phases) {
+function getReadinessFromStatuses(change, phase, phases, options = {}) {
     const satisfiedPrerequisites = [];
     const missingArtifactTopicKeys = [];
     const blockedPrerequisites = [];
+    const useAutoAdvance = options.autoAdvance === true;
     for (const prerequisite of sddPrerequisites[phase]) {
         const status = phases.find((candidate) => candidate.phase === prerequisite);
-        if (status?.accepted) {
+        const satisfied = useAutoAdvance ? isPrerequisiteSatisfied(status) : status?.accepted === true;
+        if (satisfied) {
             satisfiedPrerequisites.push(prerequisite);
             continue;
         }
@@ -508,10 +542,6 @@ function blockerReasonForStatus(status) {
     if (status.legacy === true)
         return 'legacy';
     const state = status.state ?? (status.present ? 'draft' : 'missing');
-    if (state === 'missing')
-        return 'missing';
-    if (state === 'accepted')
-        return 'draft';
     return state;
 }
 function formatBlockers(blockers) {