vgxness 1.9.1 → 1.9.2

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

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

package/dist/mcp/control-plane.js

@@ -32,7 +32,9 @@ export function callVgxTool(call, services) {
         case 'vgxness_sdd_save_artifact':
             return auditedEnvelope(validated.tool, services.sdd.saveArtifact(validated.input), services, sddSaveAuditPayload(validated.input));
         case 'vgxness_sdd_accept_artifact':
-            return auditedEnvelope(validated.tool, services.sdd.acceptArtifact(toAcceptArtifactServiceInput(validated.input)), services, sddAcceptanceAuditPayload(validated.input));
+            return auditedEnvelope(validated.tool, services.sdd.acceptArtifact(validated.input), services, sddAcceptanceAuditPayload(validated.input));
+        case 'vgxness_sdd_reopen_artifact':
+            return auditedEnvelope(validated.tool, services.sdd.reopenArtifact(validated.input), services, sddReopenAuditPayload(validated.input));
         case 'vgxness_sdd_get_artifact':
             return toEnvelope(validated.tool, services.sdd.getArtifact(validated.input));
         case 'vgxness_sdd_list_artifacts':
@@ -117,10 +119,6 @@ export function callVgxTool(call, services) {
     }
     return errorEnvelope('validation_failed', 'Tool dispatch is not implemented');
 }
-function toAcceptArtifactServiceInput(input) {
-    const note = input.note ?? input.notes ?? input.rationale;
-    return note === undefined ? input : { ...input, note };
-}
 function auditedEnvelope(tool, result, services, audit) {
     if (result.ok && audit.runId !== undefined) {
         services.runs.appendEvent({
@@ -171,6 +169,24 @@ function sddAcceptanceAuditPayload(input) {
         }),
     };
 }
+function sddReopenAuditPayload(input) {
+    return {
+        runId: input.runId,
+        title: 'Audit: sdd-artifact-reopened',
+        relatedType: 'sdd-artifact',
+        relatedId: `${input.change}:${input.phase}`,
+        payload: (value) => ({
+            eventType: 'sdd-artifact-reopened',
+            project: input.project,
+            change: input.change,
+            phase: input.phase,
+            topicKey: value.topicKey,
+            artifactId: value.id,
+            reopenedBy: { type: 'human', id: input.reopenedBy.id },
+            ...(input.agentId === undefined ? {} : { agentId: input.agentId }),
+        }),
+    };
+}
 function sddSaveAuditPayload(input) {
     return {
         runId: input.runId,
@@ -237,6 +253,7 @@ export function createVgxMcpControlPlane(options = {}) {
     let closed = false;
     return {
         callVgxTool: (tool, input) => callVgxTool({ tool, input }, services),
+        database,
         close: () => {
             if (closed)
                 return;

package/dist/mcp/provider-status.js

@@ -221,16 +221,12 @@ function claudeProjectMemoryPathStatus(state) {
 function compactPaths(paths, mode) {
     if (mode === 'verbose')
         return paths;
-    return paths.map((path) => path.status === 'pass'
-        ? { ...path, detail: `${path.label}: pass` }
-        : path.status === 'not-configured'
-            ? { ...path, detail: `${path.label}: not configured` }
-            : path);
+    return paths.map((path) => ({ label: path.label, path: path.path, status: path.status }));
 }
 function compactMcpEntry(entry, mode) {
-    if (mode === 'verbose' || entry.status !== 'pass')
+    if (mode === 'verbose')
         return entry;
-    return { ...entry, detail: 'MCP server entry found.' };
+    return { configured: entry.configured, status: entry.status, serverName: entry.serverName };
 }
 function compactSdd(sdd, mode) {
     if (mode === 'verbose')

package/dist/mcp/schema.js

@@ -9,6 +9,7 @@ export const SUPPORTED_VGX_MCP_TOOL_NAMES = [
     'vgxness_sdd_get_readiness',
     'vgxness_sdd_save_artifact',
     'vgxness_sdd_accept_artifact',
+    'vgxness_sdd_reopen_artifact',
     'vgxness_sdd_get_artifact',
     'vgxness_sdd_list_artifacts',
     'vgxness_sdd_next',
@@ -49,6 +50,7 @@ export const EXPOSED_VGX_MCP_TOOL_NAMES = [
     'sdd_get_readiness',
     'sdd_save_artifact',
     'sdd_accept_artifact',
+    'sdd_reopen_artifact',
     'sdd_get_artifact',
     'sdd_list_artifacts',
     'sdd_next',
@@ -148,8 +150,22 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
         }),
         acceptedAt: z.string().min(1).optional(),
         note: z.string().min(1).optional(),
-        notes: z.string().min(1).optional(),
-        rationale: z.string().min(1).optional(),
+        runId: z.string().min(1).optional(),
+        agentId: z.string().min(1).optional(),
+    })
+        .passthrough(),
+    vgxness_sdd_reopen_artifact: z
+        .object({
+        project: z.string().min(1),
+        change: z.string().min(1),
+        phase: z.enum(sddPhases),
+        reopenedBy: z.object({
+            type: z.literal('human'),
+            id: z.string().min(1),
+            displayName: z.string().min(1).optional(),
+        }),
+        reopenedAt: z.string().min(1).optional(),
+        note: z.string().min(1).optional(),
         runId: z.string().min(1).optional(),
         agentId: z.string().min(1).optional(),
     })

package/dist/mcp/stdio-server.js

@@ -1,9 +1,11 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { runBootAgentSeedUpgrade } from '../agents/boot-upgrade.js';
 import { createVgxMcpControlPlane } from './control-plane.js';
 import { EXPOSED_VGX_MCP_TOOL_NAMES, toInternalVgxMcpToolName, VGX_MCP_TOOL_INPUT_SCHEMAS, } from './schema.js';
 export async function startVgxMcpStdioServer(options = {}) {
     const controlPlane = createVgxMcpControlPlane(options.databasePath === undefined ? {} : { databasePath: options.databasePath });
+    runBootAgentSeedUpgrade(controlPlane.database);
     const mcpServer = new McpServer({ name: 'vgxness', version: '0.1.0' });
     const transport = new StdioServerTransport();
     let closed = false;

package/dist/mcp/validation.js

@@ -42,6 +42,8 @@ export function validateVgxMcpToolCall(call) {
             return validationSuccess(tool.value, validateSddSaveArtifactInput(input, tool.value));
         case 'vgxness_sdd_accept_artifact':
             return validationSuccess(tool.value, validateSddAcceptArtifactInput(input, tool.value));
+        case 'vgxness_sdd_reopen_artifact':
+            return validationSuccess(tool.value, validateSddReopenArtifactInput(input, tool.value));
         case 'vgxness_sdd_get_artifact':
             return validationSuccess(tool.value, validateSddGetArtifactInput(input, tool.value));
         case 'vgxness_sdd_list_artifacts':
@@ -312,7 +314,7 @@ function validateSddSaveArtifactInput(input, tool) {
     return { ok: true, value: { ...base.value, phase: phase.value, content: content.value } };
 }
 function validateSddAcceptArtifactInput(input, tool) {
-    const record = inputRecord(input, tool, ['project', 'change', 'phase', 'acceptedBy', 'acceptedAt', 'note', 'notes', 'rationale', 'runId', 'agentId']);
+    const record = inputRecord(input, tool, ['project', 'change', 'phase', 'acceptedBy', 'acceptedAt', 'note', 'runId', 'agentId']);
     if (!record.ok)
         return record;
     const base = readProjectAndChange(record.value, tool);
@@ -340,7 +342,41 @@ function validateSddAcceptArtifactInput(input, tool) {
     if (displayName.value !== undefined)
         acceptedBy.displayName = displayName.value;
     const result = { ...base.value, phase: phase.value, acceptedBy };
-    const copied = copyOptionalLimitedStrings(result, record.value, tool, ['acceptedAt', 'note', 'notes', 'rationale', 'runId', 'agentId'], undefined);
+    const copied = copyOptionalLimitedStrings(result, record.value, tool, ['acceptedAt', 'note', 'runId', 'agentId'], undefined);
+    if (!copied.ok)
+        return copied;
+    return { ok: true, value: result };
+}
+function validateSddReopenArtifactInput(input, tool) {
+    const record = inputRecord(input, tool, ['project', 'change', 'phase', 'reopenedBy', 'reopenedAt', 'note', 'runId', 'agentId']);
+    if (!record.ok)
+        return record;
+    const base = readProjectAndChange(record.value, tool);
+    if (!base.ok)
+        return base;
+    const phase = readPhase(record.value, tool);
+    if (!phase.ok)
+        return phase;
+    const reopenedByRecord = asRecord(record.value.reopenedBy, tool, 'reopenedBy is required');
+    if (!reopenedByRecord.ok)
+        return reopenedByRecord;
+    const reopenedByExtra = Object.keys(reopenedByRecord.value).find((key) => !['type', 'id', 'displayName'].includes(key));
+    if (reopenedByExtra !== undefined)
+        return validationFailure(`Unexpected field: reopenedBy.${reopenedByExtra}`, tool);
+    const type = readRequiredOneOf(reopenedByRecord.value, 'type', ['human'], tool);
+    if (!type.ok)
+        return type;
+    const id = readNonEmptyString(reopenedByRecord.value, 'id', tool);
+    if (!id.ok)
+        return id;
+    const displayName = readOptionalNonEmptyString(reopenedByRecord.value, 'displayName', tool);
+    if (!displayName.ok)
+        return displayName;
+    const reopenedBy = { type: type.value, id: id.value };
+    if (displayName.value !== undefined)
+        reopenedBy.displayName = displayName.value;
+    const result = { ...base.value, phase: phase.value, reopenedBy };
+    const copied = copyOptionalLimitedStrings(result, record.value, tool, ['reopenedAt', 'note', 'runId', 'agentId'], undefined);
     if (!copied.ok)
         return copied;
     return { ok: true, value: result };

package/dist/memory/sqlite/migrations/016_agent_seed_history.sql

@@ -0,0 +1,15 @@
+CREATE TABLE agent_seed_history (
+  id TEXT PRIMARY KEY,
+  applied_at TEXT NOT NULL,
+  from_version INTEGER,
+  to_version INTEGER NOT NULL,
+  agent_name TEXT NOT NULL,
+  project TEXT NOT NULL,
+  scope TEXT NOT NULL,
+  outcome TEXT NOT NULL,
+  reason TEXT,
+  source TEXT NOT NULL
+);
+
+CREATE INDEX idx_agent_seed_history_applied_at ON agent_seed_history(applied_at);
+CREATE INDEX idx_agent_seed_history_project_scope_name ON agent_seed_history(project, scope, agent_name);

package/dist/runs/schema.js

@@ -1 +1,5 @@
+export const TERMINAL_RUN_STATUSES = ['completed', 'failed', 'blocked', 'cancelled'];
+export function isTerminalRunStatus(status) {
+    return TERMINAL_RUN_STATUSES.includes(status);
+}
 export const runSnapshotPackageKind = 'vgxness.run-snapshot-package';

package/dist/sdd/schema.js

@@ -30,10 +30,22 @@ export const SddArtifactAcceptanceRecordSchema = z
     note: z.string().optional(),
 })
     .strict();
+export const SddArtifactReopenRecordSchema = z
+    .object({
+    actor: z.object({
+        type: z.literal('human'),
+        id: z.string().min(1),
+        displayName: z.string().min(1).optional(),
+    }),
+    reopenedAt: z.string().min(1),
+    note: z.string().optional(),
+})
+    .strict();
 export const SddArtifactMetadataSchema = z
     .object({
     status: SddArtifactStatusSchema,
     acceptance: SddArtifactAcceptanceRecordSchema.optional(),
+    reopen: SddArtifactReopenRecordSchema.optional(),
     supersededByTopicKey: z.string().min(1).optional(),
     updatedAt: z.string().min(1).optional(),
 })

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

@@ -175,7 +175,7 @@ export class SddWorkflowService {
             if (status === 'accepted')
                 return validationFailure('Cannot overwrite an accepted SDD artifact; supersede it under a new topic key.');
             if (status === 'rejected')
-                return validationFailure('Rejected SDD artifact must be re-opened with an explicit decision before saving.');
+                return validationFailure('Rejected SDD artifact must be re-opened via SddWorkflowService.reopenArtifact before saving.');
             if (status === 'superseded')
                 return validationFailure('Cannot overwrite a superseded SDD artifact.');
         }
@@ -198,7 +198,7 @@ export class SddWorkflowService {
         const existingEnvelope = normalizeSddArtifact(existing.value);
         const existingStatus = existingEnvelope.metadata.status;
         if (existingStatus === 'rejected')
-            return validationFailure('Rejected SDD artifact must be re-opened with an explicit decision before accepting.');
+            return validationFailure('Rejected SDD artifact must be re-opened via SddWorkflowService.reopenArtifact before accepting.');
         if (existingStatus === 'superseded')
             return validationFailure('Cannot accept a superseded SDD artifact; create a new artifact under a different topic key instead.');
         const acceptance = {
@@ -223,6 +223,47 @@ export class SddWorkflowService {
             },
         }, this.context);
     }
+    reopenArtifact(input) {
+        const validated = this.validatePhaseInput(input);
+        if (!validated.ok)
+            return validated;
+        if (input.reopenedBy === undefined)
+            return validationFailure('SDD artifact reopen requires an explicit human actor');
+        if (input.reopenedBy.type !== 'human')
+            return validationFailure('SDD artifact reopen must be performed by a human actor');
+        if (input.reopenedBy.id === undefined || input.reopenedBy.id.trim().length === 0)
+            return validationFailure('SDD artifact reopen human actor id must not be empty');
+        const topicKey = sddTopicKey(validated.value.change, validated.value.phase);
+        const existing = this.memory.getArtifact(validated.value.project, topicKey, this.context);
+        if (!existing.ok)
+            return existing;
+        const existingEnvelope = normalizeSddArtifact(existing.value);
+        const existingStatus = existingEnvelope.metadata.status;
+        if (existingStatus !== 'rejected')
+            return validationFailure(`SDD artifact reopen is only valid for rejected artifacts (current status: ${existingStatus}).`);
+        const reopenedAt = input.reopenedAt ?? new Date().toISOString();
+        const reopenRecord = {
+            actor: {
+                type: 'human',
+                id: input.reopenedBy.id,
+                ...(input.reopenedBy.displayName === undefined ? {} : { displayName: input.reopenedBy.displayName }),
+            },
+            reopenedAt,
+            ...(input.note === undefined ? {} : { note: input.note }),
+        };
+        return this.memory.saveArtifact({
+            project: existing.value.project,
+            topicKey: existing.value.topicKey,
+            phase: existing.value.phase,
+            content: existing.value.content,
+            metadata: {
+                ...existingEnvelope.metadata,
+                status: 'draft',
+                reopen: reopenRecord,
+                updatedAt: reopenedAt,
+            },
+        }, this.context);
+    }
     getArtifact(input) {
         const validated = this.validatePhaseInput(input);
         if (!validated.ok)

package/docs/architecture.md

@@ -91,6 +91,14 @@ Gentle-AI/`gentle-pi` are strong references for the configurator and agent-behav
 | `Adapter` | Translator between the neutral `vgxness` model and a provider-specific config/runtime. |
 | `PermissionPolicy` | Rules defining what an agent may do, what requires approval, and what must be denied. |
 
+### Agent registry self-healing
+
+The canonical agent manifest in `src/agents/canonical-agent-manifest.ts` is the source of truth for built-in agents (1 manager + 10 SDD subagents). At every CLI/MCP boot, `src/agents/boot-upgrade.ts` reconciles the live `agents` table with that manifest via `src/agents/agent-seed-upgrade-service.ts`: missing rows are created, drifted rows (changed `vgxnessPromptContractVersion`, instructions, adapters, or description) are overwritten, and matches are recorded as noop. Each non-noop outcome is appended to the `agent_seed_history` table for audit. Operators can opt out with `VGXNESS_SKIP_AGENT_SEED_AUTO_UPGRADE=1`. This eliminates the long-standing drift between the canonical prompt contract and stored agent rows after a version bump.
+
+### Manager overlay parity across providers
+
+A user-saved `manager_profile_overlay` flows to both providers symmetrically. OpenCode consults the overlay inside `OpenCodeManagerPayloadService.applyManagerOverlayWhenAvailable` (`src/providers/opencode/manager-payload.ts:152-156`), which calls `ManagerProfileOverlayService.resolveEffectiveManager` before producing the OpenCode manager payload. Claude Code was previously canonical-only; the fix routes the overlay through `withEffectiveManagerInstructions` (`src/agents/canonical-agent-projection.ts`) into the render path (`expectedClaudeCodeRenderedAgents` / `expectedClaudeCodeRenderedUserAgents`), with the caller (`mcp install claude` in `src/cli/commands/mcp-dispatcher.ts`) computing the effective instructions via `computeEffectiveManagerInstructions(database)` and passing them into `installClaudeCodeMcpClient`. As a result, `vgxness mcp install claude` writes the user's customized instructions into `.claude/agents/vgxness-manager.md` instead of silently falling back to canonical.
+
 ## Storage model
 
 `vgxness` should keep local storage split by scope.

package/docs/cli.md

@@ -24,7 +24,7 @@ vgx --help
 vgxness mcp start --db <temp-memory.sqlite> # then call verification_plan with { changeType: 'mcp' }
 ```
 
-`vgxness setup plan` and `vgxness setup status` are human-readable and read-only by default; pass `--json` when you need parseable automation output. The MCP plan is read-only. Installed-package setup plans should use `vgxness mcp start` and must not mention `npm run cli`, `tsx`, or repository-relative source paths.
+`vgxness setup plan` and `vgxness setup status` are human-readable and do not write provider config by default; local VGXNESS store initialization may occur when the selected SQLite store is needed. Pass `--json` when you need parseable automation output. The MCP plan does not write provider config. Installed-package setup plans should use `vgxness mcp start` and must not mention `npm run cli`, `tsx`, or repository-relative source paths.
 
 Only apply the OpenCode user/global config after reviewing the plan (use `--scope project` only when you intentionally want project config):
 
@@ -63,7 +63,7 @@ vgxness sdd next --project <project> --change <change>
 vgxness setup rollback --backup <path>
 ```
 
-`setup plan`, `setup status`, and non-TTY `init` planning are read-only and do not write provider config. They are human-readable by default; pass `--json` when you need parseable automation output. With the default global database, the OpenCode MCP command is `vgxness mcp start`; for custom/project-local DBs it includes `--db <path>`. The default OpenCode target is `$HOME/.config/opencode/opencode.json`; pass `--scope project` to opt into `<workspace>/.opencode/opencode.json`. `setup apply --yes` is the explicit OpenCode provider-config write path. `setup rollback --backup <path>` validates a VGXNESS/OpenCode backup such as `opencode.json.backup-<timestamp>`, creates a pre-rollback backup of the current target when present, restores the selected backup byte-for-byte, and recommends `vgxness doctor`.
+`setup plan`, `setup status`, and non-TTY `init` planning do not write provider config. Local VGXNESS store initialization may occur when the selected SQLite store is needed. They are human-readable by default; pass `--json` when you need parseable automation output. With the default global database, the OpenCode MCP command is `vgxness mcp start`; for custom/project-local DBs it includes `--db <path>`. The default OpenCode target is `$HOME/.config/opencode/opencode.json`; pass `--scope project` to opt into `<workspace>/.opencode/opencode.json`. `setup apply --yes` is the explicit OpenCode provider-config write path. `setup rollback --backup <path>` validates a VGXNESS/OpenCode backup such as `opencode.json.backup-<timestamp>`, creates a pre-rollback backup of the current target when present, restores the selected backup byte-for-byte, and recommends `vgxness doctor`.
 
 `vgxness init` prompts in English when stdin/stdout are TTYs: project name, DB location, provider, OpenCode scope, install mode, then shows the plan and asks `Apply this setup? Type "yes" to continue:`. Any answer other than `yes` exits successfully without writes. In CI/non-TTY without `--yes`, `init` returns the read-only plan and never waits for input. `vgxness doctor`, `vgxness sdd status`, `vgxness sdd next`, `vgxness sdd get-artifact`, and `vgxness sdd list-artifacts` are also human-readable by default; use `--json` for scripts.
 
@@ -112,7 +112,7 @@ Release-candidate checklist, without publishing:
 
 1. `bun install --frozen-lockfile` completes on a clean checkout.
 2. `bun run check:bun-lock` passes.
-3. `bun run verify:typecheck`, `bun run verify:test`, and `bun run verify:bun-sqlite` pass.
+3. `bun run verify:typecheck`, `bun run verify:test`, `bun run verify:test:bun-storage`, and `bun run verify:bun-sqlite` pass.
 4. `bun run package:bun:evidence -- --require-pass` passes on supported CI OSes.
 5. Uploaded JSON shows `status: pass`, artifact/install smoke pass, no retired scripts, no `package-lock.json`, `publicationAttempted: false`, and `releaseReadiness.status: pass`.
 6. Version, release notes, proprietary license boundary, and rollback criteria are reviewed.
@@ -312,7 +312,7 @@ bun run cli:bun -- <workflow> run --project <name> --intent <text> [--phase <nam
 bun run cli:bun -- <workflow> execute --run-id <id> --confirm [--override-escalation] [--workspace <path>] [--db <path>] [--executor safe-non-dispatching|provider|command]
 ```
 
-`preview` is read-only: it returns the workflow registry plus optional planner output, does not open or write the database, does not create runs, does not call providers, does not edit files, and does not write provider config. Use it to choose between `quickfix`, `debug`, `sdd`, or another workflow before recording state.
+`preview` is read-only: it returns the workflow registry plus optional planner output, does not open or write the database, does not create runs, does not call providers, does not edit files, and does not write provider config. Use it to choose between `quickfix`, `debug`, `sdd`, or another workflow before recording state. Other status/plan surfaces may open or initialize the selected VGXNESS SQLite store; that local store state is separate from provider config.
 
 `run` records the selected workflow intent and a `workflow-run-planned` checkpoint in the local SQLite store. It selects or validates an agent, stores the run id, and reports any planner recommendation such as SDD escalation. It does not dispatch providers, edit files, write provider config, create subagents, or mutate SDD artifacts.
 
@@ -437,7 +437,7 @@ A rejected approval is recorded in the run audit trail and prevents the matching
 
 ## MCP setup preview and doctor
 
-Use this flow to manually verify MCP readiness after implementation. Setup preview is read-only: it does **not** install anything, create `.opencode/` or `.claude/`, or write provider/user/global config.
+Use this flow to manually verify MCP readiness after implementation. Setup preview does **not** install anything, create `.opencode/` or `.claude/`, or write provider/user/global config. Local VGXNESS store initialization may occur when a command needs the selected SQLite store.
 
 ```bash
 bun run cli:bun -- mcp setup --preview --provider opencode --db <path>

package/docs/contributing.md

@@ -69,7 +69,7 @@ The configurator/setup plane (rendering/installing provider config) is separate
 
 These rules are non-negotiable. The harness is loaded with capability; do not remove these guards.
 
-- Read-only/preview commands must stay non-mutating. Setup plans, MCP setup previews, OpenCode previews, workflow previews, and status views must not write provider config or call providers.
+- Read-only/preview commands must not mutate provider config or external tool state. Setup plans, MCP setup previews, OpenCode previews, workflow previews, and status views must not write provider config or call providers. Local VGXNESS store initialization may occur when a command needs the selected SQLite store.
 - Provider config writes require explicit consent (`--yes` or equivalent confirmed flow) plus backup/rollback behavior.
 - Do not create or write `openspec/`. SDD artifacts are stored through the local SQLite artifact service under canonical topic keys `sdd/{change}/{phase}`.
 - Human acceptance is distinct from artifact presence. Do not infer acceptance from generated content or saved drafts. The runtime rejects `acceptedBy.type !== 'human'`.

package/docs/glossary.md

@@ -64,7 +64,7 @@ A permission resolution: `allow`, `ask`, or `deny`. For SDD-phase gating the mat
 
 ## Dry-run
 
-A read-only preview. Setup plans, MCP setup previews, OpenCode previews, workflow previews, and status views are dry-runs by contract — they must not write provider config or call providers.
+A read-only preview. Setup plans, MCP setup previews, OpenCode previews, workflow previews, and status views are dry-runs by contract for provider config and external tools: they must not write provider config or call providers. Local VGXNESS store initialization may occur when a command needs the selected SQLite store.
 
 ## Eval target
 

package/docs/mcp.md

@@ -20,7 +20,7 @@ All tools:
 | `vgxness_sdd_ready` | Check whether a specific phase is ready. | `project`, `change`, `phase`; optional `runId`, `agentId` | Returns structured `SddReadiness` with `blockedPrerequisites`. |
 | `vgxness_sdd_get_readiness` | Same as `ready` with explicit output shape. | same as `ready` | |
 | `vgxness_sdd_save_artifact` | Persist phase content under canonical topic key `sdd/{change}/{phase}`. | `project`, `change`, `phase`, `content` | Saving does not imply acceptance. |
-| `vgxness_sdd_accept_artifact` | Record explicit human acceptance for a phase. | `project`, `change`, `phase`, `acceptedBy` (`{type:"human", id, displayName?}`); optional `acceptedAt`, `note`, `notes`, `rationale`, `runId`, `agentId` | `acceptedBy.type` must be `"human"`. Runtime rejects agent or anonymous acceptance. |
+| `vgxness_sdd_accept_artifact` | Record explicit human acceptance for a phase. | `project`, `change`, `phase`, `acceptedBy` (`{type:"human", id, displayName?}`); optional `acceptedAt`, `note`, `runId`, `agentId` | `acceptedBy.type` must be `"human"`. Runtime rejects agent or anonymous acceptance. Only `note` is accepted; `notes` and `rationale` are rejected as unexpected fields. |
 | `vgxness_sdd_get_artifact` | Read one full artifact. | `project`, `change`, `phase`; optional `payloadMode` (`compact`/`verbose`) | |
 | `vgxness_sdd_list_artifacts` | List all artifacts for a change in canonical phase order. | `project`, `change`; optional `payloadMode` | |
 | `vgxness_sdd_cockpit` | Aggregate per-phase status, blockers, and recommended next action. | `project`, `change` | Returns `SddCockpit` with `aggregateBlockers` of kinds `missing-topic-key`, `unaccepted-phase`, `legacy-artifact`, `readiness`. |
@@ -117,7 +117,7 @@ Recording a phase with explicit human acceptance:
 ```text
 vgxness_sdd_save_artifact    { project, change, phase: "proposal", content: "..." }
 # human opens the harness and runs:
-vgxness_sdd_accept_artifact  { project, change, phase: "proposal", acceptedBy: { type: "human", id: "uziel" }, rationale: "Reviewed proposal." }
+vgxness_sdd_accept_artifact  { project, change, phase: "proposal", acceptedBy: { type: "human", id: "uziel" }, note: "Reviewed proposal." }
 ```
 
 Running a planned operation:

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

@@ -0,0 +1,126 @@
+# Auditoría de salud del proyecto VGXNESS v1.9.1
+
+## Resumen v1.9.1
+
+VGXNESS v1.9.1 fue validado exitosamente como CLI/MCP control plane local-first, con runtime instalado basado en Bun, almacenamiento SQLite local y gobernanza SDD con aceptación humana explícita. Esta auditoría es la fuente canónica para la evidencia v1.9.1; si los conteos o comandos cambian, actualiza este documento en vez de duplicar la matriz en otros docs.
+
+## Evidencia oficial validada
+
+- VGXNESS v1.9.1 validado exitosamente.
+- MCP expone 38 tools tipadas.
+- Inventario de tests: 106 test files.
+- Validación oficial aprobada:
+  - `bun run verify:typecheck`
+  - `bun run verify:test` con 437 pass, 0 fail
+  - `bun run verify:test:bun-storage`
+  - `bun run verify:bun-sqlite`
+  - `bun run package:bun:evidence` con `releaseReadiness: pass`
+
+## Matriz de validación
+
+| Superficie | Evidencia v1.9.1 | Taxonomía | Resultado esperado |
+|---|---|---|---|
+| Typecheck | `bun run verify:typecheck` | `test-run` | TypeScript estricto compila sin errores. |
+| Node tests | `bun run verify:test` | `test-run` | Suite Node pasa; evidencia validada: 437 pass, 0 fail. |
+| Bun storage tests | `bun run verify:test:bun-storage` | `test-run/local-store` | Tests storage-backed pasan vía runner oficial bajo Bun. |
+| Bun SQLite probe | `bun run verify:bun-sqlite` | `test-run/local-store` | `bun:sqlite` aplica migraciones en DB temporal y valida integridad. |
+| Package evidence | `bun run package:bun:evidence` | `package evidence` | Evidencia de paquete sin publicar; `releaseReadiness: pass`. |
+| MCP schema/tools | `docs/mcp.md` + `SUPPORTED_VGX_MCP_TOOL_NAMES` | `governance/read model` | 38 tools documentadas; schema y tabla deben mantenerse sincronizados. |
+| Test inventory | Inventario v1.9.1 | `test-run` | 106 test files como evidencia versionada. |
+| Setup/provider status | `setup plan/status`, provider status/doctor/change-plan | `read-only/no provider writes` | No escriben provider config; pueden leer o inicializar el store local de VGXNESS si hace falta. |
+| Provider previews | MCP setup preview, OpenCode preview, agent render | `read-only/provider-preview` | Preview sin ejecutar proveedores ni escribir `.opencode/`, `.claude/` o config global. |
+| SDD workflow | `sdd status/ready/get/list/next/save/accept` | `governance/read model` | Artefactos en SQLite bajo `sdd/{change}/{phase}`; aceptación humana explícita. |
+| Runs/preflight | `run_start`, `run_preflight`, resume inspect/gate | `guarded apply` | Operaciones riesgosas pasan por preflight/approval antes de ejecución. |
+| Memory/session local state | Memory, sessions, cockpit | `local-store possible` | Estado durable vive en SQLite local; no implica provider config writes. |
+| Workflow executor | Workflow preview/run/execute + allowlist | `requires explicit consent` | Preview no muta; ejecución requiere confirmación y comandos allowlisted. |
+| Package runtime Bun | Bins `vgxness`/`vgx` y MCP instalado | `package evidence` | Runtime instalado usa wrapper Bun y evidencia de paquete sin publicación. |
+
+## Taxonomía de seguridad
+
+- `docs-only`: documentación sin cambios de runtime.
+- `test-run`: verificación local o CI que puede consumir CPU/IO pero no cambia el contrato de producto.
+- `test-run/local-store`: tests/probes que crean o usan storage local temporal.
+- `package evidence`: inspección de artefacto/install smoke sin publicar.
+- `read-only/no provider writes`: no escribe configuración de proveedor, aunque puede abrir o preparar estado local de VGXNESS.
+- `read-only/provider-preview`: produce planes o previews sin instalar hooks, ejecutar proveedores ni escribir provider config.
+- `local-store possible`: puede leer/escribir SQLite local de VGXNESS por diseño del comando.
+- `governance/read model`: estado SDD/runs/memory consultable, con aceptación humana separada de la presencia del artefacto.
+- `guarded apply`: operación mutante detrás de preflight, approval y auditoría.
+- `requires explicit consent`: requiere `--yes`, confirmación equivalente o aprobación humana registrada.
+- `future/not implemented`: documentado como trabajo futuro, no como alcance actual.
+
+## Read-only, provider config y local store
+
+En esta auditoría, “read-only” debe leerse con precisión operacional: una superficie puede ser read-only respecto de proveedor y workspace, pero aun así abrir, leer o preparar el store local de VGXNESS. La regla canónica es:
+
+> No provider config writes; local VGXNESS store initialization may occur.
+
+Esto distingue tres planos:
+
+1. **Provider config**: `.opencode/`, `opencode.json`, `.claude/`, `.mcp.json`, `CLAUDE.md` y archivos equivalentes. Escribirlos requiere consentimiento explícito y backup/rollback cuando aplique.
+2. **Local VGXNESS store**: SQLite local para memoria, sesiones, runs, SDD artifacts, agentes, skills y perfiles. Algunos comandos pueden abrir o inicializar este store.
+3. **Workspace/source**: archivos del repo y artefactos de código. Este cambio es docs-only y no cambia runtime, permisos, approvals, provider setup ni packaging.
+
+## Comandos oficiales de validación
+
+Validación oficial completa para v1.9.1:
+
+```bash
+bun run verify:typecheck
+bun run verify:test
+bun run verify:test:bun-storage
+bun run verify:bun-sqlite
+bun run package:bun:evidence
+```
+
+Para release-readiness, el package evidence debe requerir pase explícito:
+
+```bash
+bun run package:bun:evidence -- --require-pass
+```
+
+## Notas sobre tests storage-backed
+
+Los tests storage-backed no deben documentarse como invocaciones genéricas directas de `node --test`. Usa los runners oficiales porque preparan el runtime correcto, paths temporales y expectativas de Bun/SQLite:
+
+- `bun run verify:test:bun-storage` para tests storage-backed bajo Bun.
+- `bun run verify:bun-sqlite` para el probe SQLite real con `bun:sqlite`.
+
+Node.js sigue siendo tooling de desarrollo/build/test para TypeScript, `node:test` y scripts auxiliares, pero el storage runtime soportado es Bun.
+
+## Riesgos y mitigaciones
+
+| Riesgo | Mitigación |
+|---|---|
+| Duplicar la matriz en README u otros docs y crear drift. | Mantener este archivo como fuente canónica; README solo resume y enlaza. |
+| Prometer “no mutation” absoluta donde puede inicializarse SQLite local. | Usar wording preciso: no provider config writes; local VGXNESS store initialization may occur. |
+| Confundir package evidence con publicación. | Package evidence no publica; publishing requiere proceso humano explícito separado. |
+| Tratar aceptación SDD como presencia de artifact. | Mantener aceptación humana explícita como requisito independiente. |
+| Ejecutar storage tests con runner incorrecto. | Documentar runners oficiales Bun para storage-backed tests. |
+| Expandir esta auditoría hacia refactors P1/P2. | Mantener P1/P2 bajo future work solamente. |
+
+## Fuera de alcance
+
+- Cambios de runtime, approvals, preflight, permisos, SDD acceptance o provider setup.
+- Cambios de package metadata, scripts, packaging o publicación.
+- Escritura de provider config o creación de `.opencode/`, `.claude/` u `openspec/`.
+- Refactors de MCP control-plane, SDD workflow, runs, storage o CLI.
+- Nuevos comandos de health audit o nuevos MCP tools.
+
+## Future work P1/P2
+
+Estos puntos son notas futuras (`future/not implemented`), no alcance de v1.9.1:
+
+- Modularizar MCP control-plane.
+- Separar SDD projections/read models.
+- Unificar lenguaje de guarded apply/Claude.
+- Crear un comando/reporte integrado de health audit.
+
+## Cómo actualizar esta auditoría
+
+1. Revalidar los comandos oficiales y registrar conteos nuevos solo si fueron medidos.
+2. Si cambia el número de MCP tools, actualizar `SUPPORTED_VGX_MCP_TOOL_NAMES` y `docs/mcp.md` en el mismo cambio.
+3. Si cambia el inventario de tests, actualizar esta evidencia versionada y evitar duplicar conteos en README.
+4. Si cambia la semántica de setup/provider preview/status, revisar wording de provider config vs local store.
+5. Si cambian runners o package evidence, actualizar `README.md`, `docs/cli.md` y `docs/contributing.md` según corresponda.
+6. No marcar esta auditoría ni artefactos SDD como aceptados salvo aceptación humana explícita.

package/docs/providers.md

@@ -2,7 +2,7 @@
 
 VGXNESS is provider-agnostic at the core: the registry stores provider-neutral definitions and adapters translate them into provider-specific config and runtime behavior. This document covers the two adapter layers: the **control-plane adapter** (OpenCode primary plus supported secondary Claude Code support) and the **code-runtime provider adapter** (OpenAI-compatible + fake).
 
-## Status (v1.6.0)
+## Status (v1.9.1)
 
 | Provider | Control plane | Code runtime | Notes |
 |---|---|---|---|
@@ -44,7 +44,7 @@ vgxness agents render --provider json --project vgxness --name apply-agent
 
 ### Claude Code support
 
-Claude Code is supported as a secondary, non-default control-plane target. Read-only status, doctor, setup plan, and change-plan surfaces can inspect or preview Claude targets without Claude Code installed and without writing files.
+Claude Code is supported as a secondary, non-default control-plane target. Status, doctor, setup plan, and change-plan surfaces can inspect or preview Claude targets without Claude Code installed and without writing provider config. Local VGXNESS store initialization may occur when the selected SQLite store is needed.
 
 Claude scopes are canonicalized to `local`, `project`, and `user`; VGXNESS compatibility aliases `personal` and legacy `global` map to Claude `user` with warnings. MCP registration is represented as structured config/argv, for example `claude mcp add --scope user vgxness -- vgxness mcp start`; no shell strings are generated. For user/global apply, VGXNESS narrowly merges only `mcpServers.vgxness` in `~/.claude.json`, preserves unknown keys, backs up existing files, and does not manage auth/session data. Status/doctor/change-plan are read-only and do not execute Claude Code.
 
@@ -128,13 +128,13 @@ Deterministic, offline. Used by `test/code/` and `bun run smoke:opentui-code` to
 
 Provider install and doctor flows live in `src/mcp/client-install-opencode.ts` and `src/mcp/provider-doctor.ts` and are exposed through the MCP server and the CLI:
 
-- `vgxness mcp install opencode --plan` — read-only plan; never writes config.
+- `vgxness mcp install opencode --plan` — plan that never writes provider config; local VGXNESS store initialization may occur when the selected SQLite store is needed.
 - `vgxness mcp install opencode --yes` — explicit write path; creates a backup first.
 - `vgxness mcp doctor opencode` — JSON report of provider health.
 - `vgxness provider status` / `vgxness provider doctor` (planned CLI) — same shape through the operator surface.
 - `vgxness setup rollback --backup <path>` — restores a previous OpenCode config byte-for-byte after validation.
 
-Writes happen only through `apply` with explicit consent. Plans, status, doctor, change-plan, and previews are read-only by contract.
+Provider config writes happen only through `apply` with explicit consent. Plans, status, doctor, change-plan, and previews do not write provider config; local VGXNESS store initialization may occur when the selected SQLite store is needed.
 
 ## Safety boundary
 

package/docs/safety.md

@@ -132,7 +132,7 @@ Retry policy evaluation is separate from execution. `vgxness_run_resume_gate` ev
 
 ## Safety boundaries (enforced everywhere)
 
-- Read-only/preview commands must stay non-mutating: setup plans, MCP setup previews, OpenCode previews, workflow previews, status views, and the natural-language orchestrator preview never write provider config, call providers, or install global memory.
+- Read-only/preview commands must not mutate provider config or external tool state: setup plans, MCP setup previews, OpenCode previews, workflow previews, status views, and the natural-language orchestrator preview never write provider config, call providers, or install global memory. Local VGXNESS store initialization may occur when a command needs the selected SQLite store.
 - Provider config writes (`opencode.json`, `.opencode/`, `.claude/`, `CLAUDE.md`) require explicit consent (`--yes` or an equivalent confirmed flow) plus backup/rollback behavior.
 - The control plane and the code runtime do not create or write `openspec/`. SDD artifacts are stored through the local SQLite artifact service under canonical topic keys.
 - Human acceptance is distinct from artifact presence: `vgxness_sdd_accept_artifact` records explicit human-only acceptance; saving a draft never implies acceptance.

package/package.json

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