vgxness 1.16.0 → 1.17.1

package/README.md

@@ -8,7 +8,7 @@ This package is proprietary software. The npm package ships inspectable JavaScri
 
 OpenCode is the primary supported provider. Claude setup support is secondary. VGX-managed OpenCode and Claude provider configuration is user-global only; provider config writes require explicit CLI confirmation.
 
-VGXNESS v1.14.x has a current project health audit describing the implemented CLI/MCP/SDD control plane, OpenCode-first workflow, release-readiness checks, and the remaining execution/recovery gaps. See [Project health audit v1.14.x](./docs/project-health-audit-v1.14.x.md) for the current system snapshot; [v1.10.x](./docs/project-health-audit-v1.10.x.md) and [v1.9.1](./docs/project-health-audit-v1.9.1.md) remain historical validation evidence for those releases.
+VGXNESS is currently versioned from `package.json` (`1.17.1`). The latest full project health audit is the historical [v1.14.x snapshot](./docs/project-health-audit-v1.14.x.md), which documents the implemented CLI/MCP/SDD control plane, OpenCode-first workflow, release-readiness checks, and the remaining execution/recovery gaps at that point in time. [v1.10.x](./docs/project-health-audit-v1.10.x.md) and [v1.9.1](./docs/project-health-audit-v1.9.1.md) remain historical validation evidence for those releases.
 
 ## Requirements
 
@@ -165,6 +165,15 @@ vgxness setup apply --yes
 
 The daily SDD happy path is OpenCode conversation with the installed VGXNESS MCP server and hidden SDD subagents. Use CLI commands for bootstrap, setup, diagnostics, recovery, fallback, and scripting: `status`, `next`, and `sdd continue` inspect state and print read-only continuation guidance; `resume` helps inspect interrupted work. After a draft is ready, `sdd accept-artifact` records explicit human acceptance, and `sdd reopen-artifact` returns rejected artifacts to draft.
 
+Copy this prompt into OpenCode for normal daily SDD work:
+
+```text
+Continue VGXNESS SDD for project <project> and change <change>.
+Use the VGXNESS MCP tools to inspect status/readiness/artifacts, then delegate phase work to the exact hidden SDD subagent when needed.
+Save draft artifacts when appropriate and report evidence, tests, blockers, and the next human decision.
+Do not accept or reopen artifacts for me; ask me before any human-only, provider-config, git, destructive, external, install, or secret-sensitive action.
+```
+
 ## Code runtime status
 
 The experimental `vgxness code` runtime and principal OpenTUI code surface have been removed temporarily because they were copied OpenCode-like runtime work. Continue SDD work in OpenCode through VGXNESS MCP, and use the safe CLI commands above for diagnostics and recovery.
@@ -179,7 +188,7 @@ The experimental `vgxness code` runtime and principal OpenTUI code surface have
 - `vgxness sdd accept-artifact` records explicit human-only acceptance; saving a draft never implies acceptance.
 - `vgxness sdd reopen-artifact` is the explicit path from a rejected artifact back to draft before revision.
 - OpenCode is the primary supported provider; other providers are preview/manual extension points.
-- VGXNESS exposes 41 typed MCP tools across SDD, memory, sessions, agents, skills, runs, providers, and verification. See [MCP tools](./docs/mcp.md).
+- VGXNESS exposes 42 typed MCP tools across SDD, memory, sessions, agents, skills, runs, providers, and verification. See [MCP tools](./docs/mcp.md).
 
 ## Principal entrypoint
 
@@ -256,7 +265,7 @@ Remove any user-global OpenCode/Claude config entries and local/global VGXNESS d
 ## More docs
 
 - [CLI reference](./docs/cli.md)
-- [Project health audit v1.14.x](./docs/project-health-audit-v1.14.x.md)
+- [Project health audit v1.14.x](./docs/project-health-audit-v1.14.x.md) — historical snapshot
 - [Project health audit v1.10.x](./docs/project-health-audit-v1.10.x.md)
 - [Project health audit v1.9.1](./docs/project-health-audit-v1.9.1.md)
 - [Architecture](./docs/architecture.md)

package/dist/agents/canonical-agent-manifest.js

@@ -131,8 +131,15 @@ export function createCanonicalOpenCodeSddMcpToolPermissions() {
         vgxness_sdd_get_artifact: 'allow',
         vgxness_sdd_list_artifacts: 'allow',
         vgxness_sdd_cockpit: 'allow',
+        vgxness_context_cockpit: 'allow',
         vgxness_agent_resolve: 'allow',
         vgxness_sdd_save_artifact: 'allow',
+        vgxness_memory_search: 'allow',
+        vgxness_memory_get: 'allow',
+        vgxness_memory_save: 'allow',
+        vgxness_memory_update: 'allow',
+        vgxness_skill_payload: 'allow',
+        vgxness_run_preflight: 'allow',
     };
 }
 export function createCanonicalOpenCodeSddSubagentPrompt(name) {

package/dist/cli/home-tui-app.js

@@ -28,7 +28,7 @@ function FocusedRunsView({ plan, width, runs }) {
     const badge = runs.state === 'ready' ? 'read-only' : runs.state === 'unavailable' ? 'unavailable' : 'loading';
     const tone = runs.state === 'unavailable' ? 'warning' : 'info';
     const title = runs.state === 'ready' && runs.selected !== undefined ? 'Run detail' : 'Runs';
-    return (_jsxs(Box, { flexDirection: "column", width: width, paddingX: 1, paddingY: 1, children: [_jsx(TuiHeader, { title: "VGXNESS Runs", subtitle: "Run recovery cockpit \u00B7 read-only", project: plan.project }), _jsx(TuiSummaryBar, { items: summaryItems(plan) }), _jsx(Box, { marginTop: 1, children: _jsx(TuiCard, { title: title, badge: badge, tone: tone, lines: focusedRunsLines(plan, runs) }) }), _jsx(TuiFooter, { text: "Keys: Enter opens first run detail \u00B7 Esc/b back to Home \u00B7 q exits \u00B7 read-only \u00B7 no writes" })] }));
+    return (_jsxs(Box, { flexDirection: "column", width: width, paddingX: 1, paddingY: 1, children: [_jsx(TuiHeader, { title: "VGXNESS Runs", subtitle: "Run recovery cockpit \u00B7 read-only", project: plan.project }), _jsx(TuiSummaryBar, { items: summaryItems(plan) }), _jsx(Box, { marginTop: 1, children: _jsx(TuiCard, { title: title, badge: badge, tone: tone, lines: focusedRunsLines(plan, runs) }) }), _jsx(TuiFooter, { text: "Keys: Enter inspects first run detail \u00B7 Esc/b back to Home \u00B7 q exits \u00B7 read-only \u00B7 no writes \u00B7 no retry/approval/execution" })] }));
 }
 function FocusedSddView({ plan, width, sddInput, sdd }) {
     const badge = sddInput.change.length === 0 ? 'change required' : sdd.state === 'ready' ? sdd.next.status : sdd.state === 'unavailable' ? 'unavailable' : 'change selected';
@@ -107,8 +107,9 @@ function focusedRunsLines(plan, runs) {
             '',
             runs.message,
             '',
-            'Use `vgxness resume --project <name>` to inspect interrupted runs from a Bun-backed runtime.',
+            'Interrupted runs can be inspected with `vgxness runs list --project <name> --status needs-human` from a Bun-backed runtime.',
             'Use `vgxness runs list --project <name> --status needs-human` for actionable blockers.',
+            'Safety: read-only/no writes/no retry/approval/execution.',
         ];
     }
     if (runs.state === 'ready') {
@@ -121,12 +122,13 @@ function focusedRunsLines(plan, runs) {
             field('Recent runs', String(runs.recent.length)),
             field('Interrupted', String(runs.interrupted.length)),
             '',
-            ...runSummarySection('Interrupted runs', runs.interrupted),
+            ...runSummarySection('Interrupted runs', runs.interrupted, runs.details),
             '',
-            ...runSummarySection('Recent runs', runs.recent),
+            ...runSummarySection('Recent runs', runs.recent, runs.details),
             '',
             runs.details.length === 0 ? 'No run is available for detail inspection.' : 'Press Enter to inspect the first interrupted/recent run here.',
             'CLI fallback: `vgxness runs get --id <run-id>`.',
+            'Safety: read-only/no writes/no retry/approval/execution.',
         ];
     }
     return [
@@ -135,12 +137,15 @@ function focusedRunsLines(plan, runs) {
         field('Safety', 'read-only placeholder'),
         '',
         'This panel does not open the local SQLite store yet.',
-        'Use `vgxness resume --project <name>` to inspect interrupted runs.',
+        'Use `vgxness runs list --project <name> --status needs-human` to inspect interrupted runs.',
         'Use `vgxness runs list --project <name> --status needs-human` for actionable blockers.',
         '',
-        'Next implementation slice can wire this panel to the run read model.',
+        'This panel is read-only/no writes/no retry/approval/execution.',
     ];
 }
+export function renderHomeRunsReadOnlyLines(plan, runs) {
+    return focusedRunsLines(plan, runs);
+}
 function focusedRunDetailLines(plan, databasePath, run) {
     return [
         field('Project', plan.project),
@@ -151,8 +156,8 @@ function focusedRunDetailLines(plan, databasePath, run) {
         field('Workflow/phase', `${run.workflow}/${run.phase}`),
         field('Events', String(run.events)),
         field('Checkpoints', String(run.checkpoints)),
-        field('Approvals', String(run.approvals)),
-        field('Attempts', String(run.attempts)),
+        field('Approvals', `${run.approvals} (${formatApprovalStatusCounts(run.approvalStatusCounts)})`),
+        field('Attempts', `${run.attempts} (${formatAttemptStatusCounts(run.attemptStatusCounts)})`),
         ...(run.latestCheckpointLabel === undefined ? [] : [field('Latest checkpoint', run.latestCheckpointLabel)]),
         ...(run.latestEventTitle === undefined ? [] : [field('Latest event', run.latestEventTitle)]),
         ...(run.outcome === undefined ? [] : [field('Outcome', run.outcome)]),
@@ -160,13 +165,32 @@ function focusedRunDetailLines(plan, databasePath, run) {
         ...(run.userIntent === undefined ? [] : ['', `Intent: ${run.userIntent}`]),
         '',
         `Inspect JSON: vgxness runs get --id ${run.id}`,
+        'Safety: read-only/no writes/no retry/approval/execution.',
         'No retry, approval, or execution is performed from this TUI detail.',
     ];
 }
-function runSummarySection(title, runs) {
+function runSummarySection(title, runs, details = []) {
     if (runs.length === 0)
         return [title, '- none'];
-    return [title, ...runs.map((run) => `- ${shortRunId(run.id)} ${run.status} ${run.workflow}/${run.phase}${run.userIntent === undefined ? '' : ` — ${run.userIntent}`}`)];
+    return [title, ...runs.map((run) => runSummaryLine(run, details.find((detail) => detail.id === run.id)))];
+}
+function runSummaryLine(run, detail) {
+    const base = `- ${shortRunId(run.id)} ${run.status} ${run.workflow}/${run.phase}${run.userIntent === undefined ? '' : ` — ${run.userIntent}`}`;
+    if (detail === undefined)
+        return base;
+    return [
+        base,
+        `approvals ${detail.approvals} (${formatApprovalStatusCounts(detail.approvalStatusCounts)})`,
+        `attempts ${detail.attempts} (${formatAttemptStatusCounts(detail.attemptStatusCounts)})`,
+        `latest checkpoint ${detail.latestCheckpointLabel ?? 'none'}`,
+        `latest event ${detail.latestEventTitle ?? 'none'}`,
+    ].join(' · ');
+}
+function formatApprovalStatusCounts(counts) {
+    return [`pending=${counts.pending}`, `approved=${counts.approved}`, `rejected=${counts.rejected}`, `cancelled=${counts.cancelled}`].join(' ');
+}
+function formatAttemptStatusCounts(counts) {
+    return [`reserved=${counts.reserved}`, `succeeded=${counts.succeeded}`, `failed=${counts.failed}`, `abandoned=${counts.abandoned}`].join(' ');
 }
 function shortRunId(id) {
     return id.length <= 8 ? id : id.slice(0, 8);
@@ -287,7 +311,7 @@ function skillSummarySection(skills) {
     return ['Indexed skills', ...skills.slice(0, 8).map((skill) => `- ${skill.name} ${skill.status}${skill.activeVersion === null ? '' : ` @ ${skill.activeVersion}`}`), ...(skills.length > 8 ? [`- +${skills.length - 8} more`] : [])];
 }
 function runsLines() {
-    return ['Run dashboard is not loaded in this first Home TUI slice.', '', 'Use `vgxness status` or `vgxness resume --project <name>` for current CLI diagnostics.', 'Next slice can wire this panel to the run read model.'];
+    return ['Run dashboard is not loaded in this Home TUI overview.', '', 'Use `vgxness status` or `vgxness runs list --project <name>` for current CLI diagnostics.', 'Focused Runs is read-only/no writes/no retry/approval/execution.'];
 }
 function sddLines() {
     return [

package/dist/cli/home-tui-controller.js

@@ -224,11 +224,29 @@ function runDetailSummary(run) {
         events: run.events.length,
         checkpoints: run.checkpoints.length,
         approvals: run.approvals.length,
+        approvalStatusCounts: countApprovalStatuses(run.approvals.map((approval) => approval.status)),
         attempts: run.operationAttempts.length,
+        attemptStatusCounts: countAttemptStatuses(run.operationAttempts.map((attempt) => attempt.status)),
         ...(latestCheckpoint === undefined ? {} : { latestCheckpointLabel: latestCheckpoint.label }),
         ...(latestEvent === undefined ? {} : { latestEventTitle: latestEvent.title }),
     };
 }
+function countApprovalStatuses(statuses) {
+    return {
+        pending: statuses.filter((status) => status === 'pending').length,
+        approved: statuses.filter((status) => status === 'approved').length,
+        rejected: statuses.filter((status) => status === 'rejected').length,
+        cancelled: statuses.filter((status) => status === 'cancelled').length,
+    };
+}
+function countAttemptStatuses(statuses) {
+    return {
+        reserved: statuses.filter((status) => status === 'reserved').length,
+        succeeded: statuses.filter((status) => status === 'succeeded').length,
+        failed: statuses.filter((status) => status === 'failed').length,
+        abandoned: statuses.filter((status) => status === 'abandoned').length,
+    };
+}
 function selectFirstHomeRunDetail(runs) {
     if (runs.state !== 'ready' || runs.selected !== undefined)
         return runs;

package/dist/mcp/control-plane.js

@@ -46,7 +46,7 @@ export function callVgxTool(call, services) {
         case 'vgxness_sdd_next':
             return toEnvelope(validated.tool, services.sdd.getNext(validated.input));
         case 'vgxness_sdd_cockpit':
-            return toEnvelope(validated.tool, mapMemoryResult(services.sdd.getCockpit(validated.input), buildSddCockpitSurfaceResponse));
+            return toEnvelope(validated.tool, sddCockpitSurfaceResponse(validated.input, services));
         case 'vgxness_sdd_continue':
             return sddContinueEnvelope(validated.input, services);
         case 'vgxness_governance_report':
@@ -267,6 +267,15 @@ function sddContinueEnvelope(input, services) {
         ...(relatedRun.value === undefined ? {} : { relatedRunContext: relatedRun.value }),
     }));
 }
+function sddCockpitSurfaceResponse(input, services) {
+    const cockpit = services.sdd.getCockpit(input);
+    if (!cockpit.ok)
+        return cockpit;
+    const operationalEvidence = services.runs.getSddOperationalEvidence({ project: input.project, change: input.change });
+    if (!operationalEvidence.ok)
+        return { ok: true, value: buildSddCockpitSurfaceResponse(cockpit.value) };
+    return { ok: true, value: buildSddCockpitSurfaceResponse(cockpit.value, { operationalEvidenceByPhase: operationalEvidence.value }) };
+}
 export function createVgxMcpControlPlane(options = {}) {
     const databasePath = resolveControlPlaneDatabasePath(options);
     if (!databasePath.ok)

package/dist/runs/run-service.js

@@ -1,8 +1,10 @@
+import { createHash } from 'node:crypto';
 import { evaluatePermission } from '../permissions/policy-evaluator.js';
 import { isRiskyPermissionCategory } from '../permissions/schema.js';
 import { normalizeSddPhaseInput } from '../sdd/schema.js';
 import { planExecutionIsolation, recommendWorkspaceStrategyForExecution } from './execution-planning.js';
 import { evaluateOperationRetry as evaluateOperationRetryPolicy } from './operation-retry.js';
+import { AllowlistedApplyProgressCommandExecutor } from '../workflows/command-allowlist-adapter.js';
 import { RunRepository, } from './repositories/runs.js';
 import { buildRunInsights, buildRunOperatorResumePlan } from './run-insights.js';
 const preflightSafety = {
@@ -45,6 +47,51 @@ export class RunService {
     listRuns(filters = {}) {
         return this.runs.list(filters);
     }
+    getSddOperationalEvidence(input) {
+        const runs = this.runs.list({ project: input.project, limit: input.limit ?? 50 });
+        if (!runs.ok)
+            return runs;
+        const evidenceByPhase = {};
+        for (const run of runs.value) {
+            if (!isSddWorkflow(run.workflow))
+                continue;
+            const phase = normalizeSddPhaseInput(run.phase);
+            if (phase === undefined || evidenceByPhase[phase] !== undefined)
+                continue;
+            const details = this.runs.getDetails(run.id);
+            if (!details.ok)
+                return details;
+            const matchingCheckpoints = details.value.checkpoints.filter((checkpoint) => checkpointHasChangeId(checkpoint.state, input.change));
+            if (matchingCheckpoints.length === 0)
+                continue;
+            const latestMatchingCheckpoint = matchingCheckpoints.at(-1);
+            evidenceByPhase[phase] = {
+                latestRun: {
+                    id: details.value.id,
+                    status: details.value.status,
+                    workflow: details.value.workflow,
+                    phase: details.value.phase,
+                    ...(details.value.outcome === undefined ? {} : { outcome: details.value.outcome }),
+                    createdAt: details.value.createdAt,
+                    updatedAt: details.value.updatedAt,
+                    ...(details.value.completedAt === undefined ? {} : { completedAt: details.value.completedAt }),
+                },
+                approvalCounts: countByStatus(details.value.approvals.map((approval) => approval.status)),
+                attemptCounts: countByStatus(details.value.operationAttempts.map((attempt) => attempt.status)),
+                ...(latestMatchingCheckpoint === undefined
+                    ? {}
+                    : {
+                        latestCheckpoint: {
+                            id: latestMatchingCheckpoint.id,
+                            label: latestMatchingCheckpoint.label,
+                            sequence: latestMatchingCheckpoint.sequence,
+                            createdAt: latestMatchingCheckpoint.createdAt,
+                        },
+                    }),
+            };
+        }
+        return { ok: true, value: evidenceByPhase };
+    }
     listRecentInterruptedRuns(input) {
         const runs = this.runs.list({ project: input.project, statuses: ['failed', 'blocked', 'needs-human'], limit: input.limit ?? 5 });
         if (!runs.ok)
@@ -234,6 +281,7 @@ export class RunService {
         const operation = operationFromPendingExecution(pendingExecutionEvent.payload);
         if (operation === undefined)
             return validationFailure('Pending operation metadata is incomplete and cannot be retried');
+        const replayGuard = replayGuardForApprovedOperation(approval.value, permissionEvent, pendingExecutionEvent, operation);
         const attempts = details.value.operationAttempts.filter((attempt) => attempt.approvalId === approval.value.id);
         const retryDecision = evaluateOperationRetryPolicy(input.policy === undefined ? { attempts } : { attempts, policy: input.policy });
         if (!retryDecision.allowed || retryDecision.reasonCode !== 'status_allowed_by_policy')
@@ -245,7 +293,7 @@ export class RunService {
             pendingExecutionEventId: pendingExecutionEvent.id,
             category: operation.category,
             operation: operation.operation,
-            operationMetadata: operationMetadata(operation),
+            operationMetadata: operationMetadataWithReplayGuard(operation, replayGuard),
             executorName: input.executorName ?? 'retry-admission',
         });
         if (!reserved.ok)
@@ -267,6 +315,8 @@ export class RunService {
                 retryReason: retryDecision.reason,
                 evaluatedAttemptCount: retryDecision.evaluatedAttemptCount,
                 retryableStatuses: [...retryDecision.retryableStatuses],
+                replayGuard,
+                operationFingerprint: replayGuard.operationFingerprint,
                 executorInvoked: false,
                 operationExecuted: false,
             }),
@@ -385,6 +435,10 @@ export class RunService {
         const operation = operationFromPendingExecution(pendingExecutionEvent.payload);
         if (operation === undefined)
             return validationFailure('Pending operation metadata is incomplete and cannot be resumed');
+        const replayGuard = replayGuardForApprovedOperation(approval.value, permissionEvent, pendingExecutionEvent, operation);
+        const replayValidation = validateReplayGuard(pendingExecutionEvent, replayGuard, input.expectedOperationFingerprint);
+        if (!replayValidation.ok)
+            return replayValidation;
         const retry = this.evaluateOperationRetry({ approvalId: approval.value.id });
         if (!retry.ok)
             return retry;
@@ -397,7 +451,7 @@ export class RunService {
             pendingExecutionEventId: pendingExecutionEvent.id,
             category: operation.category,
             operation: operation.operation,
-            operationMetadata: operationMetadata(operation),
+            operationMetadata: operationMetadataWithReplayGuard(operation, replayGuard),
             executorName: input.executor.name,
         });
         if (!reserved.ok)
@@ -420,6 +474,8 @@ export class RunService {
                     originalDecision: 'ask',
                     approvalStatus: 'approved',
                     policyReevaluated: false,
+                    replayGuard,
+                    operationFingerprint: replayGuard.operationFingerprint,
                     resumedFromApprovalId: approval.value.id,
                     executorInvoked: true,
                     error,
@@ -430,6 +486,9 @@ export class RunService {
             if (!executionEvent.ok)
                 return { ok: false, error: executionEvent.error };
             const linkedAttempt = this.runs.attachAttemptResultEvent(attempt.value.id, executionEvent.value.id);
+            const evidence = appendApplyProgressAllowlistEvidenceIfNeeded(this.runs, approval.value.id, permissionEvent, pendingExecutionEvent, linkedAttempt.ok ? linkedAttempt.value : attempt.value, executionEvent.value, replayGuard.operationFingerprint, input.executor.name, operation, undefined, error);
+            if (!evidence.ok)
+                return { ok: false, error: evidence.error };
             return {
                 ok: true,
                 value: {
@@ -439,6 +498,7 @@ export class RunService {
                     attempt: linkedAttempt.ok ? linkedAttempt.value : attempt.value,
                     executionEvent: executionEvent.value,
                     status: 'failed',
+                    ...(evidence.value === undefined ? {} : evidence.value),
                 },
             };
         }
@@ -458,6 +518,8 @@ export class RunService {
                 originalDecision: 'ask',
                 approvalStatus: 'approved',
                 policyReevaluated: false,
+                replayGuard,
+                operationFingerprint: replayGuard.operationFingerprint,
                 resumedFromApprovalId: approval.value.id,
                 executorInvoked: true,
                 output: output ?? null,
@@ -468,6 +530,9 @@ export class RunService {
         if (!executionEvent.ok)
             return { ok: false, error: executionEvent.error };
         const linkedAttempt = this.runs.attachAttemptResultEvent(attempt.value.id, executionEvent.value.id);
+        const evidence = appendApplyProgressAllowlistEvidenceIfNeeded(this.runs, approval.value.id, permissionEvent, pendingExecutionEvent, linkedAttempt.ok ? linkedAttempt.value : attempt.value, executionEvent.value, replayGuard.operationFingerprint, input.executor.name, operation, output, undefined);
+        if (!evidence.ok)
+            return { ok: false, error: evidence.error };
         return {
             ok: true,
             value: {
@@ -478,9 +543,17 @@ export class RunService {
                 executionEvent: executionEvent.value,
                 status: 'succeeded',
                 ...(output === undefined ? {} : { output }),
+                ...(evidence.value === undefined ? {} : evidence.value),
             },
         };
     }
+    resumeApprovedAllowlistedApplyProgressCommand(input) {
+        return this.resumeApprovedOperation({
+            approvalId: input.approvalId,
+            executor: new AllowlistedApplyProgressCommandExecutor(input.executorOptions),
+            ...(input.expectedOperationFingerprint === undefined ? {} : { expectedOperationFingerprint: input.expectedOperationFingerprint }),
+        });
+    }
     executeOperation(input) {
         const permission = this.evaluatePermissionForRun({ runId: input.runId, ...input.operation, reusePendingApproval: true });
         if (!permission.ok)
@@ -541,6 +614,7 @@ export class RunService {
                 : { ok: false, error: executionEvent.error };
         }
         if (permission.value.decision.decision === 'ask') {
+            const replayGuard = permission.value.approval === undefined ? undefined : replayGuardForApprovedOperation(permission.value.approval, permission.value.event, undefined, input.operation);
             const executionEvent = this.runs.appendEvent({
                 runId: input.runId,
                 kind: 'operation-execution',
@@ -551,6 +625,7 @@ export class RunService {
                     decision: 'ask',
                     reason: permission.value.decision.reason,
                     message: permission.value.decision.message,
+                    ...(replayGuard === undefined ? {} : { replayGuard, operationFingerprint: replayGuard.operationFingerprint }),
                     executorInvoked: false,
                     operationExecuted: false,
                 }),
@@ -855,8 +930,49 @@ export class RunService {
         return { ok: true, value: resolved[0] };
     }
 }
+export function calculateStableOperationFingerprint(input) {
+    const canonical = {
+        runId: input.runId,
+        approvalId: input.approvalId,
+        category: input.category,
+        operation: input.operation,
+    };
+    if (input.phase !== undefined)
+        canonical.phase = input.phase;
+    if (input.agentId !== undefined)
+        canonical.agentId = input.agentId;
+    if (input.workspaceRoot !== undefined)
+        canonical.workspaceRoot = input.workspaceRoot;
+    if (input.targetPath !== undefined)
+        canonical.targetPath = input.targetPath;
+    if (input.input !== undefined)
+        canonical.input = input.input;
+    return `sha256:${createHash('sha256').update(stableJson(canonical)).digest('hex')}`;
+}
 function checkpointHasChangeId(state, change) {
-    return typeof state === 'object' && state !== null && !Array.isArray(state) && state.changeId === change;
+    return typeof state === 'object' && state !== null && !Array.isArray(state) && (state.changeId === change || state.change === change);
+}
+function countByStatus(statuses) {
+    const counts = { total: statuses.length };
+    for (const status of statuses) {
+        if (status === 'pending')
+            counts.pending = (counts.pending ?? 0) + 1;
+        else if (status === 'approved')
+            counts.approved = (counts.approved ?? 0) + 1;
+        else if (status === 'rejected')
+            counts.rejected = (counts.rejected ?? 0) + 1;
+        else if (status === 'cancelled')
+            counts.cancelled = (counts.cancelled ?? 0) + 1;
+        else if (status === 'reserved')
+            counts.reserved = (counts.reserved ?? 0) + 1;
+        else if (status === 'succeeded')
+            counts.succeeded = (counts.succeeded ?? 0) + 1;
+        else if (status === 'failed')
+            counts.failed = (counts.failed ?? 0) + 1;
+        else if (status === 'abandoned')
+            counts.abandoned = (counts.abandoned ?? 0) + 1;
+    }
+    return counts;
 }
 function preflightOutcome(decision) {
     if (decision.decision === 'allow')
@@ -886,6 +1002,54 @@ function workflowConflictDecision(input, runWorkflow) {
         auditEvidence: [`runWorkflow:${runWorkflow}`, `explicitWorkflow:${input.workflow}`],
     };
 }
+function appendApplyProgressAllowlistEvidenceIfNeeded(runs, approvalId, permissionEvent, pendingExecutionEvent, attempt, executionEvent, operationFingerprint, executorName, operation, output, error) {
+    if (!isApplyProgressAllowlistedCommandOperation(operation))
+        return { ok: true, value: undefined };
+    const base = {
+        kind: 'apply-progress-operation',
+        operationKind: 'allowlisted-command',
+        runId: attempt.runId,
+        approvalId,
+        attemptId: attempt.id,
+        pendingExecutionEventId: pendingExecutionEvent.id,
+        permissionEventId: permissionEvent.id,
+        executionEventId: executionEvent.id,
+        operationFingerprint,
+        executor: executorName,
+        operation: operationMetadata(operation),
+        status: attempt.status,
+        output: output ?? null,
+        error: error ?? null,
+    };
+    const evidence = runs.appendEvent({
+        runId: attempt.runId,
+        kind: 'evidence',
+        title: `Apply-progress allowlisted command ${attempt.status}: ${operation.operation}`,
+        payload: base,
+        relatedType: 'operation-attempt',
+        relatedId: attempt.id,
+    });
+    if (!evidence.ok)
+        return { ok: false, error: evidence.error };
+    const checkpoint = runs.appendCheckpoint({
+        runId: attempt.runId,
+        label: 'apply-progress-allowlisted-command-executed',
+        state: { ...base, evidenceEventId: evidence.value.id },
+    });
+    if (!checkpoint.ok)
+        return { ok: false, error: checkpoint.error };
+    return { ok: true, value: { checkpoint: checkpoint.value, evidenceEvent: evidence.value } };
+}
+function isApplyProgressAllowlistedCommandOperation(operation) {
+    if (operation.input === undefined)
+        return false;
+    if (!isObject(operation.input))
+        return false;
+    return (operation.phase === 'apply-progress' &&
+        operation.input.kind === 'apply-progress-operation' &&
+        operation.input.operationKind === 'allowlisted-command' &&
+        /^command-allowlist:[A-Za-z0-9._/-]+$/u.test(operation.operation));
+}
 function executionPayload(operation, executorName, status, extra) {
     return {
         status,
@@ -896,6 +1060,65 @@ function executionPayload(operation, executorName, status, extra) {
         ...extra,
     };
 }
+function operationMetadataWithReplayGuard(operation, replayGuard) {
+    const metadata = operationMetadata(operation);
+    if (!isObject(metadata))
+        return metadata;
+    return { ...metadata, replayGuard };
+}
+function replayGuardForApprovedOperation(approval, permissionEvent, pendingExecutionEvent, operation) {
+    const fingerprintInput = fingerprintInputForApprovedOperation(approval, permissionEvent, operation);
+    const operationFingerprint = calculateStableOperationFingerprint(fingerprintInput);
+    return {
+        version: 1,
+        operationFingerprint,
+        fingerprintAlgorithm: 'sha256:stable-json:v1',
+        expectedPendingExecutionEventId: pendingExecutionEvent?.id ?? null,
+        associated: fingerprintInput,
+    };
+}
+function fingerprintInputForApprovedOperation(approval, permissionEvent, operation) {
+    const permissionPayload = isObject(permissionEvent.payload) ? permissionEvent.payload : {};
+    const requestedOperation = permissionPayload.requestedOperation !== undefined && isObject(permissionPayload.requestedOperation) ? permissionPayload.requestedOperation : {};
+    const agent = permissionPayload.agent !== undefined && isObject(permissionPayload.agent) ? permissionPayload.agent : undefined;
+    const phase = stringField(operation.phase) ?? stringField(requestedOperation.phase) ?? stringField(permissionPayload.phase);
+    const agentId = stringField(operation.agentId) ?? stringField(requestedOperation.agentId) ?? stringField(agent?.id);
+    const workspaceRoot = stringField(operation.workspaceRoot) ?? stringField(requestedOperation.workspaceRoot);
+    const targetPath = stringField(operation.targetPath) ?? stringField(requestedOperation.targetPath);
+    const fingerprintInput = {
+        runId: approval.runId,
+        approvalId: approval.id,
+        category: operation.category,
+        operation: operation.operation,
+    };
+    if (phase !== undefined)
+        fingerprintInput.phase = phase;
+    if (agentId !== undefined)
+        fingerprintInput.agentId = agentId;
+    if (workspaceRoot !== undefined)
+        fingerprintInput.workspaceRoot = workspaceRoot;
+    if (targetPath !== undefined)
+        fingerprintInput.targetPath = targetPath;
+    if (operation.input !== undefined)
+        fingerprintInput.input = operation.input;
+    return fingerprintInput;
+}
+function validateReplayGuard(pendingExecutionEvent, replayGuard, expectedOperationFingerprint) {
+    const actualFingerprint = replayGuard.operationFingerprint;
+    if (expectedOperationFingerprint !== undefined && expectedOperationFingerprint !== actualFingerprint) {
+        return validationFailure(`Operation fingerprint mismatch: expected ${expectedOperationFingerprint}, calculated ${actualFingerprint}`);
+    }
+    if (isObject(pendingExecutionEvent.payload)) {
+        const stored = typeof pendingExecutionEvent.payload.operationFingerprint === 'string' ? pendingExecutionEvent.payload.operationFingerprint : undefined;
+        const storedReplayGuard = pendingExecutionEvent.payload.replayGuard !== undefined && isObject(pendingExecutionEvent.payload.replayGuard) ? pendingExecutionEvent.payload.replayGuard : undefined;
+        const storedReplayFingerprint = typeof storedReplayGuard?.operationFingerprint === 'string' ? storedReplayGuard.operationFingerprint : undefined;
+        const storedFingerprint = stored ?? storedReplayFingerprint;
+        if (storedFingerprint !== undefined && storedFingerprint !== actualFingerprint) {
+            return validationFailure(`Stored operation fingerprint mismatch: stored ${storedFingerprint}, calculated ${actualFingerprint}`);
+        }
+    }
+    return { ok: true, value: undefined };
+}
 function summarizeOperation(operation) {
     return {
         category: operation.category,
@@ -1085,6 +1308,10 @@ function operationFromPendingExecution(payload) {
         operation.targetPath = requested.targetPath;
     if (typeof requested.providerToolName === 'string')
         operation.providerToolName = requested.providerToolName;
+    if (typeof requested.phase === 'string')
+        operation.phase = requested.phase;
+    if (typeof requested.agentId === 'string')
+        operation.agentId = requested.agentId;
     if (typeof requested.destructive === 'boolean')
         operation.destructive = requested.destructive;
     if (typeof requested.external === 'boolean')
@@ -1095,10 +1322,13 @@ function operationFromPendingExecution(payload) {
         operation.ambiguous = requested.ambiguous;
     if ('input' in requested)
         operation.input = requested.input;
-    if ('input' in payload)
+    if ('input' in payload && payload.input !== null)
         operation.input = payload.input;
     return operation;
 }
+function stringField(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/dist/runs/sandbox-process-execution.js

@@ -160,10 +160,12 @@ function acceptedEvidence(workspaceRoot, cwd, checks) {
     return {
         strategy: 'bounded-process',
         enforceable: true,
+        createsSandbox: false,
+        createsWorktree: false,
         workspaceRoot,
         cwd,
         capabilities: {
-            sandboxEnforceable: true,
+            sandboxEnforceable: false,
             processExecutionEnforceable: true,
             workspaceBoundaryEnforced: true,
             providerConfigWritesBlocked: true,
@@ -172,10 +174,14 @@ function acceptedEvidence(workspaceRoot, cwd, checks) {
             limitedEnvironment: true,
             timeoutEnforced: true,
             outputCapEnforced: true,
+            createsSandbox: false,
+            createsWorktree: false,
             filesystemIsolation: false,
             networkIsolation: false,
         },
         limitations: [
+            'bounded-process does not create an OS-level sandbox',
+            'bounded-process does not create or manage a git worktree',
             'bounded-process enforces local process launch constraints only; it is not an OS-level filesystem sandbox',
             'bounded-process does not prove network isolation',
         ],

package/dist/sdd/cockpit-read-model.js

@@ -17,11 +17,11 @@ export class SddCockpitReadModelService {
         return { ok: true, value: buildSddCockpitSurfaceResponse(cockpit.value) };
     }
 }
-export function buildSddCockpitSurfaceResponse(cockpit) {
-    return { ...cockpit, readModel: buildSddCockpitReadModel(cockpit) };
+export function buildSddCockpitSurfaceResponse(cockpit, options = {}) {
+    return { ...cockpit, readModel: buildSddCockpitReadModel(cockpit, options) };
 }
-export function buildSddCockpitReadModel(cockpit) {
-    const phases = cockpit.phases.map((phase) => toPhaseReadModel(phase));
+export function buildSddCockpitReadModel(cockpit, options = {}) {
+    const phases = cockpit.phases.map((phase) => toPhaseReadModel(phase, options.operationalEvidenceByPhase?.[phase.phase]));
     const blockers = toReadBlockers(cockpit);
     const nextAction = chooseNextAction(cockpit, phases);
     return {
@@ -36,7 +36,7 @@ export function buildSddCockpitReadModel(cockpit) {
         contentIncluded: false,
     };
 }
-function toPhaseReadModel(phase) {
+function toPhaseReadModel(phase, operationalEvidence) {
     const status = artifactReadStatus(phase);
     const contentAvailable = phase.present && phase.artifact !== undefined;
     const reasons = phase.blockers.map((blocker) => blocker.action ?? blocker.reason);
@@ -70,6 +70,7 @@ function toPhaseReadModel(phase) {
             reasons,
         },
         ...(phase.gates === undefined ? {} : { gates: phase.gates }),
+        ...(operationalEvidence === undefined ? {} : { operationalEvidence }),
         guidance: guidanceForPhase(phase, status, canAccept),
     };
 }

package/dist/skills/personal-skills.js

@@ -0,0 +1,38 @@
+export const GLOBAL_PERSONAL_SKILLS_PROJECT = "__personal__";
+export const skillLookupContexts = (project, scope) => {
+    const contexts = [{ project, scope }];
+    if (scope !== "personal")
+        contexts.push({ project, scope: "personal" });
+    if (project !== GLOBAL_PERSONAL_SKILLS_PROJECT)
+        contexts.push({
+            project: GLOBAL_PERSONAL_SKILLS_PROJECT,
+            scope: "personal",
+        });
+    return dedupeContexts(contexts);
+};
+export const personalIndexContexts = (project, scope) => {
+    if (scope !== "personal")
+        return [{ project, scope }];
+    return skillLookupContexts(project, "personal");
+};
+export const dedupeSkillSummariesByName = (skills) => {
+    const seen = new Set();
+    const deduped = [];
+    for (const skill of skills) {
+        if (seen.has(skill.name))
+            continue;
+        seen.add(skill.name);
+        deduped.push(skill);
+    }
+    return deduped;
+};
+export const dedupeContexts = (contexts) => {
+    const seen = new Set();
+    return contexts.filter((context) => {
+        const key = `${context.project}:${context.scope}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+};

package/dist/skills/skill-index-service.js

@@ -1,10 +1,11 @@
+import { dedupeSkillSummariesByName, personalIndexContexts } from './personal-skills.js';
 export class SkillIndexService {
     registry;
     constructor(registry) {
         this.registry = registry;
     }
     getIndex(input) {
-        const listed = this.registry.listSkills({ project: input.project, scope: input.scope });
+        const listed = this.listSkills(input);
         if (!listed.ok)
             return listed;
         const skills = [];
@@ -41,6 +42,16 @@ export class SkillIndexService {
             },
         };
     }
+    listSkills(input) {
+        const skills = [];
+        for (const context of personalIndexContexts(input.project, input.scope)) {
+            const listed = this.registry.listSkills({ project: context.project, scope: context.scope });
+            if (!listed.ok)
+                return listed;
+            skills.push(...listed.value);
+        }
+        return { ok: true, value: dedupeSkillSummariesByName(skills) };
+    }
 }
 function indexSkill(details) {
     const currentVersion = details.currentVersion;

package/dist/skills/skill-resolver.js

@@ -1,5 +1,6 @@
 import { resolveAgentSelector } from '../agents/agent-selector-resolver.js';
 import { normalizeSddPhaseInput } from '../sdd/schema.js';
+import { skillLookupContexts } from './personal-skills.js';
 export class SkillResolver {
     skills;
     agents;
@@ -163,7 +164,16 @@ export class SkillResolver {
             return validationFailure('Resolved skill candidate has neither skill id nor name');
         if (project === undefined)
             return validationFailure(`Skill ${candidate.name} needs a project context`);
-        return this.skills.getByName(project, scope, candidate.name);
+        let lastMissing;
+        for (const context of skillLookupContexts(project, scope)) {
+            const result = this.skills.getByName(context.project, context.scope, candidate.name);
+            if (result.ok)
+                return result;
+            if (result.error.code !== 'not_found')
+                return result;
+            lastMissing = result;
+        }
+        return lastMissing ?? this.skills.getByName(project, scope, candidate.name);
     }
     resolveVersion(skill, candidateVersionId) {
         const versionId = candidateVersionId ?? skill.currentVersionId;

package/dist/skills/skill-status-service.js

@@ -1,3 +1,4 @@
+import { dedupeSkillSummariesByName, personalIndexContexts } from './personal-skills.js';
 export class SkillStatusService {
     skills;
     agents;
@@ -81,11 +82,16 @@ export class SkillStatusService {
         });
     }
     skillRegistry(project, scope) {
-        const listed = this.skills.listSkills({ project, scope });
-        if (!listed.ok)
-            return listed;
+        const listedSkills = [];
+        for (const context of personalIndexContexts(project, scope)) {
+            const listed = this.skills.listSkills({ project: context.project, scope: context.scope });
+            if (!listed.ok)
+                return listed;
+            listedSkills.push(...listed.value);
+        }
+        const summaries = dedupeSkillSummariesByName(listedSkills);
         const items = [];
-        for (const skill of listed.value) {
+        for (const skill of summaries) {
             const details = this.skills.getSkillDetails(skill.id);
             if (!details.ok)
                 return details;

package/dist/workflows/command-allowlist-adapter.js

@@ -49,6 +49,9 @@ export class CommandAllowlistAdapter {
         this.plan = plan.value;
     }
     dispatch(_request) {
+        return this.executeAllowlistedCommand();
+    }
+    executeAllowlistedCommand() {
         const result = this.runner(this.request);
         if (!result.ok)
             throw new Error(`${result.error.code}: ${result.error.message}`);
@@ -86,6 +89,103 @@ export class CommandAllowlistAdapter {
         };
     }
 }
+export class AllowlistedApplyProgressCommandExecutor {
+    options;
+    name = 'allowlisted-apply-progress-command-executor';
+    constructor(options = {}) {
+        this.options = options;
+    }
+    execute(request) {
+        const contract = applyProgressCommandContract(request.operation.input);
+        if (!contract.ok)
+            return contract;
+        const operationCommandId = commandIdFromOperation(request.operation.operation);
+        if (operationCommandId === undefined)
+            return validationFailure('Allowlisted apply-progress execution requires operation command-allowlist:<id>.');
+        if (operationCommandId !== contract.value.commandId)
+            return validationFailure(`Allowlisted command mismatch: operation ${operationCommandId}, input ${contract.value.commandId}.`);
+        const workspaceRoot = this.options.workspaceRoot ?? request.operation.workspaceRoot ?? contract.value.workspaceRoot;
+        if (workspaceRoot === undefined || workspaceRoot.trim().length === 0)
+            return validationFailure('Allowlisted command execution requires a workspaceRoot.');
+        try {
+            const adapterOptions = {
+                commandId: contract.value.commandId,
+                workspaceRoot,
+                targetPaths: this.options.targetPaths ?? contract.value.targetPaths,
+            };
+            const cwd = this.options.cwd ?? contract.value.cwd;
+            if (cwd !== undefined)
+                adapterOptions.cwd = cwd;
+            if (this.options.allowlist !== undefined)
+                adapterOptions.allowlist = this.options.allowlist;
+            if (this.options.runner !== undefined)
+                adapterOptions.runner = this.options.runner;
+            const adapter = new CommandAllowlistAdapter({
+                ...adapterOptions,
+            });
+            const result = adapter.executeAllowlistedCommand();
+            return {
+                ok: true,
+                value: {
+                    output: {
+                        kind: 'apply-progress-operation-result',
+                        operationKind: 'allowlisted-command',
+                        runId: request.runId,
+                        commandId: contract.value.commandId,
+                        argv: [adapter.plan.request.command, ...adapter.plan.request.argv],
+                        executor: this.name,
+                        status: result.failure === undefined ? 'succeeded' : 'failed',
+                        audit: result.audit ?? null,
+                        command: result.output ?? null,
+                        failure: result.failure ?? null,
+                    },
+                },
+            };
+        }
+        catch (error) {
+            return validationFailure(error instanceof Error ? error.message : 'Allowlisted command adapter rejected the request.');
+        }
+    }
+}
 export function commandAllowlistIds(allowlist = defaultCommandAllowlist) {
     return Object.keys(allowlist).sort();
 }
+function commandIdFromOperation(operation) {
+    const match = /^command-allowlist:([A-Za-z0-9._/-]+)$/u.exec(operation);
+    return match?.[1];
+}
+function applyProgressCommandContract(input) {
+    if (!isObject(input))
+        return validationFailure('Allowlisted apply-progress execution requires structured input.');
+    if (input.kind !== 'apply-progress-operation')
+        return validationFailure('Allowlisted apply-progress execution requires kind apply-progress-operation.');
+    if (input.operationKind !== 'allowlisted-command')
+        return validationFailure('Allowlisted apply-progress execution requires operationKind allowlisted-command.');
+    if (typeof input.shell === 'string' || typeof input.commandString === 'string')
+        return validationFailure('Shell strings are rejected; use commandId with fixed allowlisted argv.');
+    if (typeof input.providerToolName === 'string' || input.providerDispatch === true)
+        return validationFailure('Provider dispatch is rejected on the allowlisted command execution path.');
+    const commandId = typeof input.commandId === 'string' ? input.commandId : typeof input.command === 'string' ? input.command : undefined;
+    if (commandId === undefined || commandId.trim().length === 0)
+        return validationFailure('Allowlisted command input requires commandId.');
+    const workspaceRoot = typeof input.workspaceRoot === 'string' ? input.workspaceRoot : undefined;
+    const cwd = typeof input.cwd === 'string' ? input.cwd : undefined;
+    const rawTargets = input.targetPaths;
+    if (rawTargets !== undefined && (!Array.isArray(rawTargets) || !rawTargets.every((item) => typeof item === 'string')))
+        return validationFailure('Allowlisted command targetPaths must be an array of strings.');
+    return {
+        ok: true,
+        value: {
+            commandId,
+            ...(workspaceRoot === undefined ? {} : { workspaceRoot }),
+            ...(cwd === undefined ? {} : { cwd }),
+            targetPaths: rawTargets === undefined ? [] : rawTargets,
+        },
+    };
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}

package/dist/workflows/workflow-executor.js

@@ -265,7 +265,13 @@ export class GuardedProviderWorkflowExecutor {
                 message: 'Workspace boundary constraints are present but not enforceable in this runtime.',
                 nextAction: 'Enable realpath/workspace boundary enforcement before dispatch.',
             };
-        if (!capabilities.sandboxEnforceable || !capabilities.processExecutionEnforceable)
+        if (boundedCommandAdapter && !capabilities.processExecutionEnforceable)
+            return {
+                reason: 'process-execution-not-enforceable',
+                message: 'Bounded command dispatch requires enforceable process execution constraints.',
+                nextAction: 'Build accepted bounded-process evidence before running an allowlisted command adapter.',
+            };
+        if (!boundedCommandAdapter && (!capabilities.sandboxEnforceable || !capabilities.processExecutionEnforceable))
             return {
                 reason: 'sandbox-not-enforceable',
                 message: 'Sandbox/process execution capability is not enforceable; provider dispatch is refused.',

package/docs/architecture.md

@@ -1,6 +1,6 @@
 # vgxness Architecture
 
-> **Scope:** this document describes the current v1.14.x architecture as it is actually built. It is the source of truth for how the product works today, with the latest health snapshot captured in [Project health audit v1.14.x](./project-health-audit-v1.14.x.md). Planned work that is not yet shipped lives in [Roadmap](./roadmap.md); historical planning context that no longer reflects reality has been retired. Where this doc disagrees with code, code wins — file a doc-sync task against the relevant module.
+> **Scope:** this document describes the current architecture as it is actually built. It is the source of truth for how the product works today; the latest full health snapshot is the historical [Project health audit v1.14.x](./project-health-audit-v1.14.x.md), while the package version is sourced from `package.json`. Planned work that is not yet shipped lives in [Roadmap](./roadmap.md); historical planning context that no longer reflects reality has been retired. Where this doc disagrees with code, code wins — file a doc-sync task against the relevant module.
 
 `vgxness` is a local-first, provider-agnostic, Gentle-AI-like harness for agentic development. Its core architecture separates the product domain from provider-specific tooling so agents, skills, memory, SDD workflows, runs, and traces can work across OpenCode, Claude Code, and future adapters such as Pi.
 
@@ -637,7 +637,7 @@ The experimental code runtime layer was removed. Current risky side effects are
 
 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 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 is the human/operator control surface. MCP is the agent-facing control surface.
+MCP tools mirror the same core services for agent use. The full, current list of 42 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 is the human/operator control surface. MCP is the agent-facing control surface.
 
 ## Evaluation strategy
 

package/docs/cli.md

@@ -963,7 +963,7 @@ For more on schema, scopes, and lifecycle, see [Storage](./storage.md).
 ## See also
 
 - [Architecture](./architecture.md) — current-state architecture and core domain model.
-- [MCP tools](./mcp.md) — full reference for the 41 MCP tools exposed to agents.
+- [MCP tools](./mcp.md) — full reference for the 42 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.

package/docs/glossary.md

@@ -84,7 +84,7 @@ A redacted, structured report over SDD state, runs, and approvals. Surfaced thro
 
 ## MCP
 
-Model Context Protocol. The agent-facing transport. VGXNESS exposes 41 typed tools over stdio through `vgxness mcp start`. The tool list lives in `SUPPORTED_VGX_MCP_TOOL_NAMES` (`src/mcp/schema.ts`) and is documented in [MCP tools](./mcp.md).
+Model Context Protocol. The agent-facing transport. VGXNESS exposes 42 typed tools over stdio through `vgxness mcp start`. The tool list lives in `SUPPORTED_VGX_MCP_TOOL_NAMES` (`src/mcp/schema.ts`) and is documented in [MCP tools](./mcp.md).
 
 ## Memory observation
 

package/docs/project-health-audit-v1.10.x.md

@@ -1,6 +1,6 @@
 # Auditoría de salud del proyecto VGXNESS v1.10.x
 
-> Historical snapshot: this document records the v1.10.x health review and should not be treated as current status. See [Project health audit v1.14.x](./project-health-audit-v1.14.x.md) for the current system snapshot.
+> Historical snapshot: this document records the v1.10.x health review and should not be treated as current status. See [Project health audit v1.14.x](./project-health-audit-v1.14.x.md) for a newer historical release-readiness snapshot.
 
 ## Resumen ejecutivo
 
@@ -17,7 +17,7 @@ Esta auditoría es una foto de salud v1.10.x basada en inspección read-only del
 | Package | `package.json` declara `version: 1.10.1` y describe el producto como CLI/MCP control plane. | Implementado |
 | Runtime/tooling | `package.json` usa Bun para runtime instalado y verificación (`bun run verify`, `verify:bun-sqlite`, `package:bun:evidence`). | Implementado |
 | CLI | `src/cli/dispatcher.ts` centraliza comandos para status, next, resume, setup, agents, skills, SDD, runs, permissions, MCP y verification. | Implementado |
-| MCP | `src/mcp/stdio-server.ts` y `src/mcp/schema.ts` exponen herramientas tipadas; el estado observado reporta 41 MCP tools. | Implementado |
+| MCP | `src/mcp/stdio-server.ts` y `src/mcp/schema.ts` exponen herramientas tipadas; el estado observado durante v1.10.x reportó 41 MCP tools. | Implementado |
 | SDD | `src/sdd/sdd-workflow-service.ts` y `docs/architecture.md` definen `explore → proposal → spec → design → tasks → apply-progress → verify → archive`. | Implementado |
 | Storage | `src/memory/sqlite/*` y migraciones en `src/memory/sqlite/migrations/*.sql`; runtime real depende de `bun:sqlite`. | Implementado |
 | Providers | OpenCode es primario; Claude está soportado/guarded; Antigravity/custom son extensiones futuras/placeholders. | Mixto |
@@ -76,7 +76,7 @@ Hay documentación amplia (`README.md`, `docs/architecture.md`, `docs/cli.md`, `
 - `package.json` está en `1.10.1`.
 - `README.md` y `docs/architecture.md` ya apuntan a esta auditoría v1.10.x como snapshot actual.
 - Las referencias v1.5.1/v1.9.1 que quedan están clasificadas como historia en PRD o en la auditoría versionada v1.9.1.
-- La auditoría histórica `v1.9.1` registra 38 MCP tools y 106 test files; la inspección actual reporta 41 MCP tools y un inventario distinto de tests según exploración.
+- La auditoría histórica `v1.9.1` registra 38 MCP tools y 106 test files; la inspección de v1.10.x reportó 41 MCP tools y un inventario distinto de tests según exploración.
 
 ## Riesgos principales
 

package/docs/project-health-audit-v1.14.x.md

@@ -1,5 +1,7 @@
 # Auditoría de salud del proyecto VGXNESS v1.14.x
 
+> Historical snapshot: this document records v1.14.x release-readiness evidence and should not be treated as current package status. The current package version is sourced from `package.json`.
+
 ## Resumen ejecutivo
 
 VGXNESS v1.14.x está avanzado como **CLI/MCP control plane local-first** para SDD, memoria, runs, permisos, agentes, skills y setup de OpenCode. La base de producto es sólida: el flujo SDD canónico existe como estado SQLite-backed, OpenCode es el provider primario, los drafts y la aceptación humana están separados, y la ruta oficial de verificación es Bun-first.

package/docs/project-health-audit-v1.9.1.md

@@ -1,6 +1,6 @@
 # Auditoría de salud del proyecto VGXNESS v1.9.1
 
-> Historical snapshot: this document records validated v1.9.1 evidence and should not be treated as current status. See [Project health audit v1.14.x](./project-health-audit-v1.14.x.md) for the current system snapshot.
+> Historical snapshot: this document records validated v1.9.1 evidence and should not be treated as current status. See [Project health audit v1.14.x](./project-health-audit-v1.14.x.md) for a newer historical release-readiness snapshot.
 
 ## Resumen v1.9.1
 

package/docs/providers.md

@@ -4,7 +4,7 @@ VGXNESS is provider-agnostic at the core: the registry stores provider-neutral d
 
 ## Status
 
-Current as of the v1.14.x documentation snapshot.
+Current as of the `1.16.0` package documentation snapshot. The latest full health audit remains the historical v1.14.x snapshot.
 
 | Provider | Control plane | Workspace runtime | Notes |
 |---|---|---|---|

package/docs/roadmap.md

@@ -21,7 +21,7 @@ The hard acceptance gate and the cockpit blockers are in. The remaining work is
 
 - **Verification evidence linked to the cockpit.** The cockpit currently returns blockers; surfacing the per-phase verification evidence (pass/fail/skipped counts, last-run timestamps) would make "why is this blocked" answers more useful.
 - **Per-phase model/profile routing in the cockpit.** The manager profile overlay exists. The cockpit should recommend a model for the next phase based on the active overlay.
-- **Migration of `openspec/`-style workflows.** Some users bring artifacts from other tools. A formal `import` path through the artifact portability service would help, but it should not silently convert external artifacts into accepted SDD phases.
+- **Migration of `openspec/`-style workflows.** Some users bring artifacts from other tools. The artifact portability service and CLI can now plan/import SDD packages as drafts; remaining work is better migration UX, validation guidance, and explicit human re-acceptance flows so external artifacts are never silently converted into accepted SDD phases.
 
 ## Skills and agents
 
@@ -35,7 +35,7 @@ The registries, version model, payloads, and improvement-proposal lifecycle are
 
 SQLite, scopes, migrations, and the run snapshot export are in.
 
-- **`import` path for SDD artifacts.** The `ArtifactPortabilityService` exports; an import path that re-creates acceptance records with explicit human re-acceptance is planned.
+- **SDD artifact import hardening.** The `ArtifactPortabilityService` and CLI now support import/plan flows that save artifacts as drafts. Remaining work is UX and policy hardening around overwrite review, provenance, and explicit human re-acceptance after import.
 - **Sensitive-data redaction during export.** `src/export/redaction.ts` exists. Wiring it as a default into the export path and a CLI flag (`--redact`) is the next step.
 - **Database upgrade tooling.** Forward-only migrations work; downgrade requires a snapshot. A small CLI helper for "is my DB on the latest migration?" would be useful for support.
 

package/docs/sdd-flow.md

@@ -59,6 +59,15 @@ agent_resolve
 agent_activate
 ```
 
+Copyable OpenCode prompt for the normal daily path:
+
+```text
+Continue VGXNESS SDD for project <project> and change <change>.
+Use the VGXNESS MCP tools to inspect status/readiness/artifacts, then delegate phase work to the exact hidden SDD subagent when needed.
+Save draft artifacts when appropriate and report evidence, tests, blockers, and the next human decision.
+Do not accept or reopen artifacts for me; ask me before any human-only, provider-config, git, destructive, external, install, or secret-sensitive action.
+```
+
 The CLI equivalents are useful for setup, diagnostics, recovery, and scripting:
 
 ```bash
@@ -111,7 +120,7 @@ Only a human acceptance decision should advance governance-gated downstream work
 CLI example:
 
 ```bash
-vgxness sdd accept-artifact --project <project> --change <change> --phase explore
+vgxness sdd accept-artifact --project <project> --change <change> --phase explore --actor <human-id>
 ```
 
 ## 4. `proposal`: choose the product direction

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.16.0",
+  "version": "1.17.1",
   "description": "CLI and MCP control plane for guided AI-agent workflows, SDD, memory, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {