vgxness 1.9.1 → 1.9.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +15 -5
  2. package/dist/agents/agent-activation-service.js +13 -4
  3. package/dist/agents/agent-registry-service.js +8 -2
  4. package/dist/agents/agent-resolver.js +33 -3
  5. package/dist/agents/agent-seed-upgrade-service.js +231 -0
  6. package/dist/agents/boot-upgrade.js +59 -0
  7. package/dist/agents/canonical-agent-manifest.js +39 -18
  8. package/dist/agents/canonical-agent-projection.js +38 -4
  9. package/dist/agents/manager-profile-overlay-service.js +14 -0
  10. package/dist/agents/repositories/agent-seed-history.js +128 -0
  11. package/dist/cli/cli-help.js +14 -3
  12. package/dist/cli/commands/index.js +1 -0
  13. package/dist/cli/commands/interactive-entrypoint-dispatcher.js +8 -0
  14. package/dist/cli/commands/mcp-dispatcher.js +7 -0
  15. package/dist/cli/commands/memory-sdd-dispatcher.js +71 -5
  16. package/dist/cli/commands/status-dispatcher.js +130 -0
  17. package/dist/cli/commands/workflow-dispatcher.js +11 -5
  18. package/dist/cli/dispatcher.js +11 -1
  19. package/dist/cli/product-resume-renderer.js +32 -0
  20. package/dist/cli/product-status-renderer.js +74 -0
  21. package/dist/cli/sdd-renderer.js +80 -3
  22. package/dist/code/cli/code-command.js +7 -4
  23. package/dist/code/reporting/summary.js +4 -1
  24. package/dist/code/runtime/code-runtime.js +27 -4
  25. package/dist/code/runtime/sdd-context.js +18 -2
  26. package/dist/governance/governance-report-builder.js +18 -7
  27. package/dist/mcp/claude-code-agent-config.js +10 -4
  28. package/dist/mcp/client-install-claude-code-contract.js +19 -4
  29. package/dist/mcp/client-install-claude-code.js +2 -2
  30. package/dist/mcp/control-plane.js +78 -5
  31. package/dist/mcp/provider-status.js +89 -88
  32. package/dist/mcp/schema.js +42 -8
  33. package/dist/mcp/stdio-server.js +6 -0
  34. package/dist/mcp/validation.js +77 -5
  35. package/dist/memory/sqlite/migrations/016_agent_seed_history.sql +15 -0
  36. package/dist/resume/product-resume.js +166 -0
  37. package/dist/runs/repositories/runs.js +12 -1
  38. package/dist/runs/run-service.js +62 -5
  39. package/dist/runs/schema.js +4 -0
  40. package/dist/sdd/schema.js +20 -0
  41. package/dist/sdd/sdd-continuation-plan.js +81 -0
  42. package/dist/sdd/sdd-workflow-service.js +146 -18
  43. package/dist/skills/skill-resolver.js +21 -4
  44. package/dist/status/product-status.js +117 -0
  45. package/docs/architecture.md +9 -1
  46. package/docs/cli.md +38 -13
  47. package/docs/code-runtime.md +3 -0
  48. package/docs/contributing.md +1 -1
  49. package/docs/glossary.md +2 -2
  50. package/docs/mcp.md +20 -6
  51. package/docs/project-health-audit-v1.9.1.md +126 -0
  52. package/docs/providers.md +4 -4
  53. package/docs/safety.md +1 -1
  54. package/package.json +1 -1
@@ -35,6 +35,7 @@ Common flags across modes:
35
35
  | Flag | Effect |
36
36
  |---|---|
37
37
  | `--save-artifact` | Persist the phase artifact when explicit persistence is intended. |
38
+ | `--draft-run` | Let planning phases use draft prerequisites for planning only; human acceptance is still required and `apply-progress` remains gated. |
38
39
  | `--change-id <id>` | Override change id. |
39
40
  | `--approval-policy`, `--approval-channel`, `--memory` | Same as the other modes. |
40
41
 
@@ -172,6 +173,8 @@ Prompts, reports, checkpoints, transcripts, and memory saves redact secret-like
172
173
 
173
174
  `vgxness code sdd <change> <phase>` loads existing artifacts for the requested change/phase and exposes phase-appropriate tools. Non-implementation phases stay read/artifact oriented. `apply-progress` may expose edit and shell tools. `verify` may expose verification shell tools. Artifact saves require explicit `--save-artifact` (or the equivalent runtime flag); passing it is the only way persistence is triggered.
174
175
 
176
+ Use `vgxness sdd continue --project <project> --change <change>` first when you want the read-only continuation plan. It may suggest `vgxness code sdd ... --draft-run --save-artifact` for planning phases when draft prerequisites exist. `--draft-run` does not accept a value, does not weaken human acceptance, and does not unblock `apply-progress`; it only lets planning phases produce or revise draft artifacts before a human accepts them.
177
+
175
178
  ## Project detection
176
179
 
177
180
  `detectProject()` (in `src/code/runtime/project-detection.ts`) reports repository root, stack hints, config files, and verification presets such as `npm run typecheck` or `npm run test` when package scripts exist. The fake provider is deterministic for local tests.
@@ -69,7 +69,7 @@ The configurator/setup plane (rendering/installing provider config) is separate
69
69
 
70
70
  These rules are non-negotiable. The harness is loaded with capability; do not remove these guards.
71
71
 
72
- - 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.
72
+ - 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.
73
73
  - Provider config writes require explicit consent (`--yes` or equivalent confirmed flow) plus backup/rollback behavior.
74
74
  - Do not create or write `openspec/`. SDD artifacts are stored through the local SQLite artifact service under canonical topic keys `sdd/{change}/{phase}`.
75
75
  - 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 CHANGED
@@ -64,7 +64,7 @@ A permission resolution: `allow`, `ask`, or `deny`. For SDD-phase gating the mat
64
64
 
65
65
  ## Dry-run
66
66
 
67
- 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.
67
+ 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.
68
68
 
69
69
  ## Eval target
70
70
 
@@ -80,7 +80,7 @@ A redacted, structured report over SDD state, runs, and approvals. Surfaced thro
80
80
 
81
81
  ## MCP
82
82
 
83
- Model Context Protocol. The agent-facing transport. VGXNESS exposes 38 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).
83
+ 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).
84
84
 
85
85
  ## Memory observation
86
86
 
package/docs/mcp.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # MCP tools
2
2
 
3
- VGXNESS exposes 38 typed MCP tools over stdio through `vgxness mcp start`. The canonical list is the `SUPPORTED_VGX_MCP_TOOL_NAMES` array in `src/mcp/schema.ts` — treat that as the source of truth. The list below mirrors it; if a tool appears here that is not in the array, or vice versa, the array wins.
3
+ VGXNESS exposes 41 typed MCP tools over stdio through `vgxness mcp start`. The canonical list is the `SUPPORTED_VGX_MCP_TOOL_NAMES` array in `src/mcp/schema.ts` — treat that as the source of truth. The list below mirrors it; if a tool appears here that is not in the array, or vice versa, the array wins.
4
4
 
5
5
  Tools are exposed under the `vgxness_*` prefix. Some MCP hosts strip the prefix and accept the short form (`sdd_status`, `memory_save`, etc.). The schema accepts both.
6
6
 
@@ -11,16 +11,18 @@ All tools:
11
11
  - Return either a typed result or a `VgxMcpError` with a `code` and `message`.
12
12
  - Do not require the agent to import or instantiate anything; pass JSON, get JSON.
13
13
 
14
- ## SDD workflow (10)
14
+ ## SDD workflow (12)
15
15
 
16
16
  | Tool | Purpose | Required inputs | Notes |
17
17
  |---|---|---|---|
18
18
  | `vgxness_sdd_status` | Report per-phase artifact presence and the next ready missing phase. | `project`, `change` | |
19
19
  | `vgxness_sdd_next` | Recommend the next phase decision for a change. | `project`, `change` | |
20
+ | `vgxness_sdd_continue` | Build a read-only continuation plan for a blocked or interrupted SDD change. | `project`, `change`; optional `payloadMode` (`compact`/`verbose`) | Complements `vgxness_sdd_next` and `vgxness_sdd_cockpit` with copyable next steps. Does not mutate artifacts or runs, execute providers, write provider config, create `openspec/`, or bypass human acceptance. |
20
21
  | `vgxness_sdd_ready` | Check whether a specific phase is ready. | `project`, `change`, `phase`; optional `runId`, `agentId` | Returns structured `SddReadiness` with `blockedPrerequisites`. |
21
22
  | `vgxness_sdd_get_readiness` | Same as `ready` with explicit output shape. | same as `ready` | |
22
23
  | `vgxness_sdd_save_artifact` | Persist phase content under canonical topic key `sdd/{change}/{phase}`. | `project`, `change`, `phase`, `content` | Saving does not imply acceptance. |
23
- | `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. |
24
+ | `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. |
25
+ | `vgxness_sdd_reopen_artifact` | Move a rejected artifact back to draft for revision. | `project`, `change`, `phase`, `reopenedBy` (`{type:"human", id, displayName?}`); optional `reopenedAt`, `note`, `runId`, `agentId` | Human-only recovery path. Does not imply acceptance or bypass downstream gates. |
24
26
  | `vgxness_sdd_get_artifact` | Read one full artifact. | `project`, `change`, `phase`; optional `payloadMode` (`compact`/`verbose`) | |
25
27
  | `vgxness_sdd_list_artifacts` | List all artifacts for a change in canonical phase order. | `project`, `change`; optional `payloadMode` | |
26
28
  | `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`. |
@@ -64,7 +66,7 @@ All tools:
64
66
  | `vgxness_opencode_manager_payload` | Build the OpenCode manager payload envelope. | `OpenCodeManagerPayloadInput` shape (project, scope, agent, workflow/phase, workspaceRoot, maxSourceBytes, payloadMode) | `installable: false`, `readOnly: true`. |
65
67
  | `vgxness_opencode_handoff_preview` | Compose a full handoff preview: provider artifacts + skill diagnostics + SDD status + provider status + safety flags. | `project`; optional `scope`, `agentId`, `agentName`, `workspaceRoot`, `maxSourceBytes`, `change`, `phase` | Read-only preview. Does not execute OpenCode, install hooks, or write provider config. |
66
68
 
67
- ## Runs (8)
69
+ ## Runs (9)
68
70
 
69
71
  | Tool | Purpose | Required inputs | Notes |
70
72
  |---|---|---|---|
@@ -74,6 +76,7 @@ All tools:
74
76
  | `vgxness_run_checkpoint` | Append a resumable JSON state. | `AppendRunCheckpointInput` shape | |
75
77
  | `vgxness_run_finalize` | Finalize a run with `outcome` and `outcomeReason`. | `FinalizeRunInput` shape | `outcome` must match a terminal `status`. Re-finalization is rejected. |
76
78
  | `vgxness_run_preflight` | Run policy evaluation and return the decision + planned execution isolation strategy. | `PreflightRunOperationInput` shape | May create a pending approval when the decision is `ask`. Does not invoke an executor. |
79
+ | `vgxness_run_resume_candidates` | List recent interrupted runs for a project when the run id is unknown. | `project`; optional `limit` (1-100, default 5) | Returns failed, blocked, and needs-human candidates with `inspectInput` for `run_resume_inspect`. Does not retry, resume, mutate runs, create sandboxes/worktrees, invoke providers, or write artifacts/config. |
77
80
  | `vgxness_run_resume_inspect` | Plan-only resume advisory. | `runId` | Returns `RunResumeOrchestrationPlan` with blockers and `nextAction` (`resolve-approval`/`inspect-run`/`retry-check`/`manual-recovery`/`no-action`). |
78
81
  | `vgxness_run_resume_gate` | Evaluate retry policy for an approval without executing. | `approvalId`; optional `policy` | Default policy is `never`. See [Safety model](./safety.md) for the policy table. |
79
82
 
@@ -107,17 +110,18 @@ Inspecting SDD before doing any work:
107
110
 
108
111
  ```text
109
112
  vgxness_sdd_cockpit { project: "vgxness", change: "new-flow" }
113
+ vgxness_sdd_continue { project: "vgxness", change: "new-flow" }
110
114
  vgxness_sdd_get_readiness { project: "vgxness", change: "new-flow", phase: "proposal" }
111
115
  ```
112
116
 
113
- The cockpit returns `aggregateBlockers`; if any are `unaccepted-phase`, the agent should not run the next phase until a human accepts the prerequisite.
117
+ The cockpit returns `aggregateBlockers`; if any are `unaccepted-phase`, the agent should not run the next phase until a human accepts the prerequisite. `vgxness_sdd_continue` uses the same SDD state to explain how to continue; it is advisory only.
114
118
 
115
119
  Recording a phase with explicit human acceptance:
116
120
 
117
121
  ```text
118
122
  vgxness_sdd_save_artifact { project, change, phase: "proposal", content: "..." }
119
123
  # human opens the harness and runs:
120
- vgxness_sdd_accept_artifact { project, change, phase: "proposal", acceptedBy: { type: "human", id: "uziel" }, rationale: "Reviewed proposal." }
124
+ vgxness_sdd_accept_artifact { project, change, phase: "proposal", acceptedBy: { type: "human", id: "uziel" }, note: "Reviewed proposal." }
121
125
  ```
122
126
 
123
127
  Running a planned operation:
@@ -130,6 +134,16 @@ vgxness_run_checkpoint { runId, label: "after-step-1", state: {...} }
130
134
  vgxness_run_finalize { runId, outcome: "success", outcomeReason: "..." }
131
135
  ```
132
136
 
137
+ Finding interrupted runs when the run id is unknown:
138
+
139
+ ```text
140
+ vgxness_run_resume_candidates { project: "vgxness", limit: 5 }
141
+ vgxness_run_resume_inspect { runId }
142
+ vgxness_run_resume_gate { approvalId, policy }
143
+ ```
144
+
145
+ `vgxness_run_resume_candidates` is discovery only. It points to `run_resume_inspect` for a selected candidate and does not admit a retry or resume execution; `run_resume_gate` remains the advisory retry-policy check for a known approval id.
146
+
133
147
  ## Safety boundary
134
148
 
135
149
  MCP tools do not:
@@ -0,0 +1,126 @@
1
+ # Auditoría de salud del proyecto VGXNESS v1.9.1
2
+
3
+ ## Resumen v1.9.1
4
+
5
+ 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.
6
+
7
+ ## Evidencia oficial validada
8
+
9
+ - VGXNESS v1.9.1 validado exitosamente.
10
+ - MCP expone 38 tools tipadas.
11
+ - Inventario de tests: 106 test files.
12
+ - Validación oficial aprobada:
13
+ - `bun run verify:typecheck`
14
+ - `bun run verify:test` con 437 pass, 0 fail
15
+ - `bun run verify:test:bun-storage`
16
+ - `bun run verify:bun-sqlite`
17
+ - `bun run package:bun:evidence` con `releaseReadiness: pass`
18
+
19
+ ## Matriz de validación
20
+
21
+ | Superficie | Evidencia v1.9.1 | Taxonomía | Resultado esperado |
22
+ |---|---|---|---|
23
+ | Typecheck | `bun run verify:typecheck` | `test-run` | TypeScript estricto compila sin errores. |
24
+ | Node tests | `bun run verify:test` | `test-run` | Suite Node pasa; evidencia validada: 437 pass, 0 fail. |
25
+ | Bun storage tests | `bun run verify:test:bun-storage` | `test-run/local-store` | Tests storage-backed pasan vía runner oficial bajo Bun. |
26
+ | Bun SQLite probe | `bun run verify:bun-sqlite` | `test-run/local-store` | `bun:sqlite` aplica migraciones en DB temporal y valida integridad. |
27
+ | Package evidence | `bun run package:bun:evidence` | `package evidence` | Evidencia de paquete sin publicar; `releaseReadiness: pass`. |
28
+ | MCP schema/tools | `docs/mcp.md` + `SUPPORTED_VGX_MCP_TOOL_NAMES` | `governance/read model` | 38 tools documentadas; schema y tabla deben mantenerse sincronizados. |
29
+ | Test inventory | Inventario v1.9.1 | `test-run` | 106 test files como evidencia versionada. |
30
+ | 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. |
31
+ | Provider previews | MCP setup preview, OpenCode preview, agent render | `read-only/provider-preview` | Preview sin ejecutar proveedores ni escribir `.opencode/`, `.claude/` o config global. |
32
+ | 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. |
33
+ | Runs/preflight | `run_start`, `run_preflight`, resume inspect/gate | `guarded apply` | Operaciones riesgosas pasan por preflight/approval antes de ejecución. |
34
+ | Memory/session local state | Memory, sessions, cockpit | `local-store possible` | Estado durable vive en SQLite local; no implica provider config writes. |
35
+ | Workflow executor | Workflow preview/run/execute + allowlist | `requires explicit consent` | Preview no muta; ejecución requiere confirmación y comandos allowlisted. |
36
+ | Package runtime Bun | Bins `vgxness`/`vgx` y MCP instalado | `package evidence` | Runtime instalado usa wrapper Bun y evidencia de paquete sin publicación. |
37
+
38
+ ## Taxonomía de seguridad
39
+
40
+ - `docs-only`: documentación sin cambios de runtime.
41
+ - `test-run`: verificación local o CI que puede consumir CPU/IO pero no cambia el contrato de producto.
42
+ - `test-run/local-store`: tests/probes que crean o usan storage local temporal.
43
+ - `package evidence`: inspección de artefacto/install smoke sin publicar.
44
+ - `read-only/no provider writes`: no escribe configuración de proveedor, aunque puede abrir o preparar estado local de VGXNESS.
45
+ - `read-only/provider-preview`: produce planes o previews sin instalar hooks, ejecutar proveedores ni escribir provider config.
46
+ - `local-store possible`: puede leer/escribir SQLite local de VGXNESS por diseño del comando.
47
+ - `governance/read model`: estado SDD/runs/memory consultable, con aceptación humana separada de la presencia del artefacto.
48
+ - `guarded apply`: operación mutante detrás de preflight, approval y auditoría.
49
+ - `requires explicit consent`: requiere `--yes`, confirmación equivalente o aprobación humana registrada.
50
+ - `future/not implemented`: documentado como trabajo futuro, no como alcance actual.
51
+
52
+ ## Read-only, provider config y local store
53
+
54
+ 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:
55
+
56
+ > No provider config writes; local VGXNESS store initialization may occur.
57
+
58
+ Esto distingue tres planos:
59
+
60
+ 1. **Provider config**: `.opencode/`, `opencode.json`, `.claude/`, `.mcp.json`, `CLAUDE.md` y archivos equivalentes. Escribirlos requiere consentimiento explícito y backup/rollback cuando aplique.
61
+ 2. **Local VGXNESS store**: SQLite local para memoria, sesiones, runs, SDD artifacts, agentes, skills y perfiles. Algunos comandos pueden abrir o inicializar este store.
62
+ 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.
63
+
64
+ ## Comandos oficiales de validación
65
+
66
+ Validación oficial completa para v1.9.1:
67
+
68
+ ```bash
69
+ bun run verify:typecheck
70
+ bun run verify:test
71
+ bun run verify:test:bun-storage
72
+ bun run verify:bun-sqlite
73
+ bun run package:bun:evidence
74
+ ```
75
+
76
+ Para release-readiness, el package evidence debe requerir pase explícito:
77
+
78
+ ```bash
79
+ bun run package:bun:evidence -- --require-pass
80
+ ```
81
+
82
+ ## Notas sobre tests storage-backed
83
+
84
+ 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:
85
+
86
+ - `bun run verify:test:bun-storage` para tests storage-backed bajo Bun.
87
+ - `bun run verify:bun-sqlite` para el probe SQLite real con `bun:sqlite`.
88
+
89
+ Node.js sigue siendo tooling de desarrollo/build/test para TypeScript, `node:test` y scripts auxiliares, pero el storage runtime soportado es Bun.
90
+
91
+ ## Riesgos y mitigaciones
92
+
93
+ | Riesgo | Mitigación |
94
+ |---|---|
95
+ | Duplicar la matriz en README u otros docs y crear drift. | Mantener este archivo como fuente canónica; README solo resume y enlaza. |
96
+ | Prometer “no mutation” absoluta donde puede inicializarse SQLite local. | Usar wording preciso: no provider config writes; local VGXNESS store initialization may occur. |
97
+ | Confundir package evidence con publicación. | Package evidence no publica; publishing requiere proceso humano explícito separado. |
98
+ | Tratar aceptación SDD como presencia de artifact. | Mantener aceptación humana explícita como requisito independiente. |
99
+ | Ejecutar storage tests con runner incorrecto. | Documentar runners oficiales Bun para storage-backed tests. |
100
+ | Expandir esta auditoría hacia refactors P1/P2. | Mantener P1/P2 bajo future work solamente. |
101
+
102
+ ## Fuera de alcance
103
+
104
+ - Cambios de runtime, approvals, preflight, permisos, SDD acceptance o provider setup.
105
+ - Cambios de package metadata, scripts, packaging o publicación.
106
+ - Escritura de provider config o creación de `.opencode/`, `.claude/` u `openspec/`.
107
+ - Refactors de MCP control-plane, SDD workflow, runs, storage o CLI.
108
+ - Nuevos comandos de health audit o nuevos MCP tools.
109
+
110
+ ## Future work P1/P2
111
+
112
+ Estos puntos son notas futuras (`future/not implemented`), no alcance de v1.9.1:
113
+
114
+ - Modularizar MCP control-plane.
115
+ - Separar SDD projections/read models.
116
+ - Unificar lenguaje de guarded apply/Claude.
117
+ - Crear un comando/reporte integrado de health audit.
118
+
119
+ ## Cómo actualizar esta auditoría
120
+
121
+ 1. Revalidar los comandos oficiales y registrar conteos nuevos solo si fueron medidos.
122
+ 2. Si cambia el número de MCP tools, actualizar `SUPPORTED_VGX_MCP_TOOL_NAMES` y `docs/mcp.md` en el mismo cambio.
123
+ 3. Si cambia el inventario de tests, actualizar esta evidencia versionada y evitar duplicar conteos en README.
124
+ 4. Si cambia la semántica de setup/provider preview/status, revisar wording de provider config vs local store.
125
+ 5. Si cambian runners o package evidence, actualizar `README.md`, `docs/cli.md` y `docs/contributing.md` según corresponda.
126
+ 6. No marcar esta auditoría ni artefactos SDD como aceptados salvo aceptación humana explícita.
package/docs/providers.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  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).
4
4
 
5
- ## Status (v1.6.0)
5
+ ## Status (v1.9.1)
6
6
 
7
7
  | Provider | Control plane | Code runtime | Notes |
8
8
  |---|---|---|---|
@@ -44,7 +44,7 @@ vgxness agents render --provider json --project vgxness --name apply-agent
44
44
 
45
45
  ### Claude Code support
46
46
 
47
- 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.
47
+ 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.
48
48
 
49
49
  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.
50
50
 
@@ -128,13 +128,13 @@ Deterministic, offline. Used by `test/code/` and `bun run smoke:opentui-code` to
128
128
 
129
129
  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:
130
130
 
131
- - `vgxness mcp install opencode --plan` — read-only plan; never writes config.
131
+ - `vgxness mcp install opencode --plan` — plan that never writes provider config; local VGXNESS store initialization may occur when the selected SQLite store is needed.
132
132
  - `vgxness mcp install opencode --yes` — explicit write path; creates a backup first.
133
133
  - `vgxness mcp doctor opencode` — JSON report of provider health.
134
134
  - `vgxness provider status` / `vgxness provider doctor` (planned CLI) — same shape through the operator surface.
135
135
  - `vgxness setup rollback --backup <path>` — restores a previous OpenCode config byte-for-byte after validation.
136
136
 
137
- Writes happen only through `apply` with explicit consent. Plans, status, doctor, change-plan, and previews are read-only by contract.
137
+ 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.
138
138
 
139
139
  ## Safety boundary
140
140
 
package/docs/safety.md CHANGED
@@ -132,7 +132,7 @@ Retry policy evaluation is separate from execution. `vgxness_run_resume_gate` ev
132
132
 
133
133
  ## Safety boundaries (enforced everywhere)
134
134
 
135
- - 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.
135
+ - 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.
136
136
  - Provider config writes (`opencode.json`, `.opencode/`, `.claude/`, `CLAUDE.md`) require explicit consent (`--yes` or an equivalent confirmed flow) plus backup/rollback behavior.
137
137
  - 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.
138
138
  - 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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vgxness",
3
- "version": "1.9.1",
3
+ "version": "1.9.3",
4
4
  "description": "CLI and MCP control plane for guided AI-agent workflows, SDD, memory, and OpenCode setup.",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "repository": {