vgxness 1.5.1 → 1.5.2

package/docs/funcionamiento-del-sistema.md

@@ -1,865 +0,0 @@
-# Funcionamiento del sistema vgxness
-
-`vgxness` es un harness local-first para desarrollo agentico. Su objetivo es darle estructura, memoria, seguridad y trazabilidad al trabajo hecho con herramientas de IA como OpenCode, Claude Code u otros proveedores futuros.
-
-La idea central del sistema es simple: los agentes pueden ejecutar trabajo, pero `vgxness` mantiene el estado verificable de lo que pasa. Ese estado incluye memoria persistente, fases SDD, artefactos, agentes registrados, skills, permisos, ejecuciones, checkpoints y evidencia.
-
-## Resumen rapido
-
-`vgxness` ataca tres problemas principales:
-
-1. La perdida de contexto entre sesiones de trabajo con IA.
-2. La falta de un flujo disciplinado para cambios grandes.
-3. La dependencia excesiva en prompts sin estado verificable.
-
-Para resolverlos, el sistema se construye sobre estos bloques:
-
-| Bloque | Funcion |
-|---|---|
-| Memoria local/global | Guarda observaciones, artefactos, sesiones y trazas en SQLite. Por defecto usa una base global de usuario; para dogfood o tests se puede forzar una base por proyecto con `--db`. |
-| SDD workflow | Ordena cambios en fases verificables: explore, proposal, spec, design, tasks, apply-progress, verify y archive. |
-| Orquestador de lenguaje natural | Clasifica pedidos del usuario en direct, plan, sdd o diagnose sin ejecutar acciones. |
-| Registro de agentes | Define agentes y subagentes con capacidades, permisos, workflows y compatibilidad por proveedor. |
-| Registro de skills | Administra skills reutilizables, versiones, adjuntos, uso y propuestas de mejora. |
-| Runtime de runs | Registra ejecuciones agenticas con estado, eventos, checkpoints, aprobaciones y resultado final. |
-| Politica de permisos | Decide si una operacion se permite, se bloquea o requiere aprobacion humana. |
-| MCP server | Expone herramientas para que agentes consulten y actualicen el control plane. |
-| CLI | Permite operar el sistema desde comandos reproducibles. |
-| TUI | Muestra setup y guias operativas locales para humanos. |
-
-## Que problema resuelve
-
-Cuando se trabaja con IA en proyectos reales aparecen problemas repetidos:
-
-1. El agente no recuerda decisiones anteriores.
-2. Cada herramienta de IA tiene su propia configuracion y sus propios limites.
-3. Los cambios grandes se vuelven improvisados: se empieza a implementar antes de entender, especificar o verificar.
-4. La seguridad queda distribuida en prompts, permisos del proveedor o disciplina manual.
-5. Despues de una interrupcion no siempre queda claro que se hizo, que falta y que evidencia existe.
-
-`vgxness` busca resolver eso agregando una capa local entre el humano, los agentes y las herramientas proveedoras.
-
-Esa capa no reemplaza a OpenCode, Claude Code o futuros adapters. Los coordina. El sistema guarda estado, valida prerrequisitos, registra actividad y ofrece APIs para que los agentes no tengan que adivinar donde estan parados.
-
-## Como esta construido
-
-El proyecto esta escrito en TypeScript. Node.js 22 o superior sigue siendo tooling de desarrollo/build/tests; la persistencia local real en SQLite corre por el runtime Bun soportado.
-
-Dependencias principales:
-
-| Dependencia | Uso |
-|---|---|
-| `@modelcontextprotocol/sdk` | Servidor MCP por stdio. |
-| `zod` | Validacion de schemas de entrada. |
-| `tsx` | Ejecucion TypeScript en desarrollo. |
-| `typescript` | Build y typecheck. |
-
-Scripts principales:
-
-| Script | Funcion |
-|---|---|
-| `bun run cli:bun -- ...` | Ejecuta la CLI local desde el repo usando el mismo runtime Bun que los bins instalados. |
-| `npm run build` | Compila TypeScript y copia migraciones. |
-| `npm run test` | Ejecuta tests con el runner nativo de Node. |
-| `npm run typecheck` | Valida tipos sin emitir archivos. |
-| `bun run package:bun:evidence` | Valida el paquete con Bun: artefacto, contenido, instalacion aislada y ambos bins. |
-
-## Vista de alto nivel
-
-```text
-Humano / operador
-      |
-      | usa
-      v
-CLI / TUI
-      |
-      | llama servicios locales
-      v
-Core de vgxness
-      |
-      | persiste y consulta
-      v
-SQLite local/global
-
-Agente IA / herramienta MCP
-      |
-      | invoca tools MCP
-      v
-MCP control plane
-      |
-      | llama los mismos servicios
-      v
-Core de vgxness
-```
-
-La regla importante es que CLI, MCP y TUI no deberian tener reglas de negocio duplicadas. Todos deben pasar por los mismos servicios de dominio.
-
-## Capas del sistema
-
-### 1. Interfaces de entrada
-
-El sistema tiene varias superficies de uso.
-
-| Superficie | Usuario principal | Archivo clave | Funcion |
-|---|---|---|---|
-| CLI | Humano, scripts, smoke tests | `src/cli/dispatcher.ts` | Parsear comandos y llamar servicios. |
-| MCP stdio | Agentes y herramientas IA | `src/mcp/stdio-server.ts` | Exponer herramientas MCP locales. |
-| MCP control plane | Capa interna MCP | `src/mcp/control-plane.ts` | Validar tool calls y despacharlas a servicios. |
-| TUI | Humano local | `src/cli/tui/` | Mostrar setup y guias operativas locales. |
-
-La CLI es intencionalmente fina. Abre la base local, instancia servicios y devuelve JSON o texto. No deberia contener la logica profunda del producto.
-
-### 2. Servicios de dominio
-
-Los servicios encapsulan la logica del sistema.
-
-| Servicio | Archivo | Responsabilidad |
-|---|---|---|
-| `MemoryService` | `src/memory/memory-service.ts` | Guardar, buscar, actualizar memoria, sesiones, artefactos y trazas. |
-| `SddWorkflowService` | `src/sdd/sdd-workflow-service.ts` | Calcular estado, readiness, siguiente fase y guardar artefactos SDD. |
-| `NaturalLanguagePlanner` | `src/orchestrator/natural-language-planner.ts` | Clasificar intenciones del usuario y producir un plan preview-only. |
-| `AgentRegistryService` | `src/agents/agent-registry-service.ts` | Registrar, listar, obtener y resolver agentes/subagentes. |
-| `SkillRegistryService` | `src/skills/skill-registry-service.ts` | Registrar skills, versiones, adjuntos, propuestas y payloads. |
-| `RunService` | `src/runs/run-service.ts` | Crear runs, eventos, checkpoints, aprobaciones, preflight y finalizacion. |
-| `SetupLifecycleService` | `src/setup/setup-lifecycle-service.ts` | Reportar si el proyecto esta listo para operar. |
-| `OpenCodeManagerPayloadService` | `src/providers/opencode/manager-payload.ts` | Construir payloads para integracion con OpenCode. |
-
-### 3. Repositorios y almacenamiento
-
-La persistencia esta basada en SQLite local.
-
-Archivo clave:
-
-```text
-src/memory/sqlite/database.ts
-```
-
-Al abrir la base con el runtime Bun, el sistema:
-
-1. Crea una conexion SQLite usando `bun:sqlite`.
-2. Activa `foreign_keys`.
-3. Configura `busy_timeout`.
-4. Aplica migraciones SQL si la base no esta en modo readonly.
-5. Devuelve una instancia `MemoryDatabase` usada por los repositorios.
-
-Ruta por defecto de usuario:
-
-```text
-macOS: ~/Library/Application Support/vgxness/memory.sqlite
-Linux: ${XDG_DATA_HOME:-~/.local/share}/vgxness/memory.sqlite
-Windows: %LOCALAPPDATA%\vgxness\memory.sqlite; fallback a %APPDATA%\vgxness\memory.sqlite
-```
-
-La ruta `.vgx/memory.sqlite` se sigue usando para dogfood local o pruebas cuando se pasa explicitamente con `--db`.
-
-Los repositorios viven debajo de carpetas como:
-
-```text
-src/memory/repositories/
-src/agents/repositories/
-src/skills/repositories/
-src/runs/repositories/
-```
-
-## Flujo principal del sistema
-
-### Paso 1: El usuario o agente inicia una accion
-
-Una accion puede entrar por CLI o por MCP.
-
-Ejemplos CLI:
-
-```bash
-vgxness sdd status --project vgxness --change my-change
-vgxness orchestrator preview --project vgxness --intent "Build a new checkout workflow" --change checkout-flow
-vgxness agents resolve --project vgxness --workflow sdd --phase apply-progress
-vgxness runs list --project vgxness
-```
-
-Ejemplo MCP:
-
-```text
-vgxness_sdd_status
-vgxness_agent_resolve
-vgxness_run_start
-vgxness_run_checkpoint
-```
-
-### Paso 2: La interfaz valida y normaliza la entrada
-
-En CLI, `dispatchCli` y `dispatchCliAsync` parsean argumentos, validan area/comando y abren la base local.
-
-En MCP, `callVgxTool` valida la tool call contra schemas antes de ejecutar la operacion.
-
-Esto evita que cada comando implemente su propio contrato de entrada de manera inconsistente.
-
-### Paso 3: Se instancia el servicio correspondiente
-
-Por ejemplo:
-
-| Accion | Servicio usado |
-|---|---|
-| Consultar estado SDD | `SddWorkflowService` |
-| Clasificar un pedido natural | `createNaturalLanguagePlan` |
-| Guardar memoria | `MemoryService` |
-| Resolver agente | `AgentRegistryService` |
-| Resolver skill payload | `SkillRegistryService` |
-| Crear run | `RunService` |
-| Evaluar permisos | `evaluatePermission` |
-
-### Paso 4: El servicio aplica reglas de negocio
-
-Ejemplos:
-
-1. SDD valida que la fase exista.
-2. El orquestador clasifica si el pedido es directo, planificable, diagnostico o requiere SDD.
-3. SDD calcula si faltan artefactos prerrequisito.
-4. Runs evalua permisos antes de operaciones riesgosas.
-5. Memory registra trazas cuando una operacion de memoria ocurre.
-6. Skills solo construye payloads con versiones activas/resueltas.
-
-### Paso 5: Se persiste o consulta estado local
-
-Si la accion cambia estado, se guarda en SQLite.
-
-Ejemplos de estado persistido:
-
-| Estado | Ejemplo |
-|---|---|
-| Observaciones | Decisiones, aprendizajes, preferencias. |
-| Artefactos SDD | `sdd/my-change/proposal`, `sdd/my-change/spec`. |
-| Sesiones | Actividad agrupada por sesion. |
-| Trazas | Registro de operaciones de memoria. |
-| Agentes | Definiciones y metadata. |
-| Skills | Versiones, adjuntos, uso y propuestas. |
-| Runs | Estado, eventos, checkpoints, aprobaciones y resultado. |
-
-### Paso 6: La respuesta vuelve como JSON o texto estructurado
-
-La CLI devuelve resultados para humanos o scripts. MCP devuelve un envelope JSON con `ok`, nombre de tool y resultado o error.
-
-## Funcionamiento del orquestador de lenguaje natural
-
-El orquestador de lenguaje natural es el nuevo punto de entrada para transformar texto humano en una decision operativa segura.
-
-Archivo principal:
-
-```text
-src/orchestrator/natural-language-planner.ts
-```
-
-Schema principal:
-
-```text
-src/orchestrator/schema.ts
-```
-
-La funcion central es `createNaturalLanguagePlan`. Recibe `project`, `intent`, un `change` opcional y contexto SDD opcional. Devuelve un plan deterministico de version 1.
-
-El plan puede elegir uno de cuatro flujos:
-
-| Flow | Cuando aparece | Que significa |
-|---|---|---|
-| `direct` | Pedido de explicacion o cambio chico de bajo riesgo. | Se puede responder o tratar sin entrar a SDD. |
-| `plan` | Pedido de plan, preview, review o dry-run sin riesgo fuerte. | Se puede preparar un plan manual sin ejecutar nada. |
-| `sdd` | Nueva capacidad, arquitectura, workflow, persistencia, seguridad, cambio amplio o pedido de ejecucion. | Conviene pasar por el flujo SDD antes de implementar. |
-| `diagnose` | Pedido de diagnostico, estado, health, logs, setup o doctor. | Se mantiene en modo lectura/diagnostico. |
-
-La decision se basa en signals extraidas del texto. Algunos ejemplos:
-
-| Signal | Detecta |
-|---|---|
-| `answer-only` | Preguntas como explain, what, how o why. |
-| `planning-request` | plan, preview, review o dry-run. |
-| `diagnostic-request` | diagnose, failure, status, health, logs, setup o doctor. |
-| `new-capability` | build, add, create, new, feature o capability. |
-| `architecture-change` | architecture, refactor o boundaries. |
-| `workflow-change` | workflow, orchestration, orchestrator, SDD o phase. |
-| `persistence-change` | persistent, storage, SQLite, database, memory o migration. |
-| `security-sensitive` | security, auth, token, secret o permission. |
-| `execution-request` | run, execute, apply, start, install o push. |
-| `destructive` | delete, remove, destroy, drop o reset. |
-
-Si el pedido es ambiguo, por ejemplo `Fix it`, el planner baja la confianza, marca `needsClarification` y devuelve una pregunta aclaratoria antes de sugerir acciones de escritura.
-
-### Contrato de seguridad
-
-El orquestador actual es preview-only. Esto es CLAVE.
-
-El plan siempre devuelve safety con estas garantias:
-
-| Campo | Valor actual |
-|---|---|
-| `executed` | `false` |
-| `callsProvider` | `false` |
-| `editsFiles` | `false` |
-| `writesProviderConfig` | `false` |
-| `recordsRuns` | `false` |
-
-Eso significa que `orchestrator preview` no llama providers, no edita archivos, no escribe configuracion, no crea runs, no instala memoria global y no crea `openspec/`.
-
-Este seam es importante porque separa la decision de ruteo de la ejecucion real. Primero se clasifica y se revisa. Despues, si corresponde, otro flujo aprobado puede ejecutar.
-
-### CLI del orquestador
-
-La CLI expone el planner con:
-
-```bash
-vgxness orchestrator preview --project vgxness --intent "Build a new persistent checkout workflow" --change checkout-flow --db .vgx/memory.sqlite
-```
-
-Parametros:
-
-| Parametro | Requerido | Funcion |
-|---|---|---|
-| `--project` | Si | Proyecto donde se interpreta la intencion. |
-| `--intent` | Si | Texto natural del usuario. |
-| `--change` | No | Change SDD a consultar o reutilizar. |
-| `--db` | No | Base SQLite local a usar. |
-
-Cuando se pasa `--change`, la CLI consulta `SddWorkflowService.getStatus` y `SddWorkflowService.getNext` contra la base local seleccionada. Ese contexto se incluye en la respuesta para que el preview pueda sugerir el siguiente paso SDD sin mutar estado.
-
-Ejemplo de decision esperada:
-
-```text
-Intent: Build a new persistent checkout workflow capability
-Flow: sdd
-Suggested change id: checkout-flow
-Preview action: vgxness sdd next --project vgxness --change checkout-flow
-Safety: no ejecuto nada
-```
-
-### Como encaja en el flujo general
-
-Antes, un humano o agente podia ir directo a `sdd status`, `agents resolve` o `runs start`. Ahora existe una puerta previa:
-
-```text
-Texto del usuario
-      |
-      v
-orchestrator preview
-      |
-      v
-Clasificacion: direct | plan | sdd | diagnose
-      |
-      v
-Accion sugerida, no ejecutada
-```
-
-Esto apunta a la vision del producto: que el usuario pueda interactuar en lenguaje natural, pero que el sistema no confunda entender una intencion con tener permiso para ejecutar.
-
-## Funcionamiento del flujo SDD
-
-SDD significa Spec-Driven Development. En `vgxness`, SDD no es solo una recomendacion en un prompt: es un workflow con fases, topic keys y prerrequisitos.
-
-Fases canonicas:
-
-```text
-explore -> proposal -> spec -> design -> tasks -> apply-progress -> verify -> archive
-```
-
-Cada fase se guarda como artefacto bajo una topic key canonica:
-
-```text
-sdd/{change}/{phase}
-```
-
-Ejemplo:
-
-```text
-sdd/add-auth/proposal
-sdd/add-auth/spec
-sdd/add-auth/design
-```
-
-Prerrequisitos actuales:
-
-| Fase | Requiere |
-|---|---|
-| `explore` | Nada. |
-| `proposal` | `explore`. |
-| `spec` | `proposal`. |
-| `design` | `proposal`, `spec`. |
-| `tasks` | `proposal`, `spec`, `design`. |
-| `apply-progress` | `tasks`. |
-| `verify` | `apply-progress`. |
-| `archive` | `verify`. |
-
-El servicio SDD puede responder tres preguntas centrales:
-
-| Pregunta | Metodo | Resultado |
-|---|---|---|
-| Que fases existen y cuales estan presentes | `getStatus` | Estado por fase y proxima fase lista. |
-| Una fase esta lista para correr | `getReady` | `ready`, prerrequisitos satisfechos y faltantes. |
-| Cual es el siguiente paso | `getNext` | `runnable`, `blocked` o `complete`. |
-
-Este flujo obliga a que los cambios grandes avancen con estructura. No impide que alguien escriba codigo manualmente, pero le da al agente y al humano una fuente de verdad para saber si el cambio esta preparado.
-
-## Funcionamiento de la memoria
-
-La memoria es local y persistente. No depende de una cuenta cloud.
-
-Por defecto, la CLI instalada usa una base global de usuario. Esto permite instalar `vgxness` y empezar a guardar memoria sin pasar `--db` en cada comando.
-
-| Plataforma | Ruta global por defecto |
-|---|---|
-| macOS | `~/Library/Application Support/vgxness/memory.sqlite` |
-| Linux | `${XDG_DATA_HOME:-~/.local/share}/vgxness/memory.sqlite` |
-| Windows | `%LOCALAPPDATA%\vgxness\memory.sqlite` si existe; si no, `%APPDATA%\vgxness\memory.sqlite` |
-
-La precedencia de seleccion de base es:
-
-```text
---db <path> > VGXNESS_DB_PATH > base global de usuario
-```
-
-La ruta historica `.vgx/memory.sqlite` sigue siendo compatible, pero ahora es explicita:
-
-```bash
-vgxness memory search --project vgxness --db .vgx/memory.sqlite
-```
-
-Este detalle es importante: `vgxness` puede funcionar como herramienta instalada globalmente sin acoplar la memoria al workdir actual, pero tambien permite aislar estado cuando se necesita reproducibilidad en tests o dogfood local.
-
-`MemoryService` trabaja con cuatro conceptos principales:
-
-| Concepto | Funcion |
-|---|---|
-| Observations | Guardan conocimiento durable: decisiones, descubrimientos, preferencias o contenido general. |
-| Sessions | Agrupan actividad por sesion de trabajo. |
-| Artifacts | Guardan documentos estructurados, especialmente artefactos SDD. |
-| Traces | Registran operaciones realizadas sobre memoria. |
-
-Cuando se guarda un artefacto SDD, internamente tambien se guarda una observation con tipo `sdd-artifact`. Eso permite que el contenido sea recuperable por topic key y tambien trazable como memoria.
-
-El flujo simplificado es:
-
-```text
-Servicio solicita guardar memoria
-      |
-      v
-ObservationRepository / ArtifactRepository
-      |
-      v
-SQLite
-      |
-      v
-TraceRepository registra la operacion
-```
-
-## Funcionamiento de agentes y subagentes
-
-El registro de agentes permite definir quien puede ejecutar trabajo y bajo que contexto.
-
-Un agente puede incluir:
-
-1. Nombre y descripcion.
-2. Instrucciones.
-3. Capacidades.
-4. Workflows y fases compatibles.
-5. Skills asociadas.
-6. Permisos.
-7. Compatibilidad con adapters como OpenCode o Claude.
-
-El sistema puede resolver candidatos para una tarea con `agents resolve`. Esa resolucion es metadata-driven: usa capacidades, workflow, fase, provider, modo y texto de tarea. No llama a un modelo para rankear en la version actual.
-
-Esto es importante porque mantiene la seleccion de agente explicable y reproducible.
-
-## Funcionamiento de skills
-
-Las skills son conocimiento operativo reutilizable.
-
-El sistema no las trata como archivos sueltos, sino como entidades versionadas con ciclo de vida.
-
-Puede manejar:
-
-1. Registro de skills.
-2. Versiones activas o historicas.
-3. Adjuntos a agentes, fases, workflows o adapters.
-4. Registro de uso.
-5. Escenarios de evaluacion.
-6. Propuestas de mejora.
-7. Aprobacion antes de activar una mejora.
-
-El flujo ideal es:
-
-```text
-Se registra una skill
-      |
-      v
-Se agrega una version
-      |
-      v
-Se adjunta a un agente o fase
-      |
-      v
-Durante un run se resuelve e inyecta el payload
-      |
-      v
-Se registra si ayudo o fallo
-      |
-      v
-Si hace falta mejorarla, se crea una propuesta revisable
-```
-
-## Funcionamiento de runs
-
-Un run representa una operacion agentica significativa.
-
-Sirve para responder preguntas como:
-
-1. Quien ejecuto esto.
-2. Para que proyecto y fase fue.
-3. Que modelo o provider se uso.
-4. Que eventos ocurrieron.
-5. Que aprobaciones hicieron falta.
-6. Que checkpoints existen para retomar.
-7. Como termino la operacion.
-
-`RunService` permite:
-
-| Accion | Funcion |
-|---|---|
-| `createRun` | Crear un registro auditable. |
-| `appendEvent` | Agregar eventos al historial. |
-| `appendCheckpoint` | Guardar estado resumible. |
-| `preflightOperation` | Evaluar seguridad antes de ejecutar. |
-| `updateFinalStatus` | Cerrar el run con estado y outcome. |
-| `getRunInsights` | Construir resumen operativo del run. |
-
-Este runtime separa memoria de ejecucion. Una decision durable puede vivir en memoria, pero una ejecucion concreta vive como run con eventos, approvals y checkpoints.
-
-## Politica de permisos
-
-La politica de permisos define si una operacion se permite, pide aprobacion o se deniega.
-
-Categorias actuales:
-
-```text
-read, edit, shell, network, git, memory, external-directory, provider-tool, secrets
-```
-
-Politica base:
-
-| Categoria | Decision default |
-|---|---|
-| `read` | `allow` |
-| `edit` | `ask` |
-| `shell` | `ask` |
-| `network` | `ask` |
-| `git` | `ask` |
-| `memory` | `ask` |
-| `external-directory` | `deny` |
-| `provider-tool` | `ask` |
-| `secrets` | `deny` |
-
-Reglas importantes:
-
-1. Acceso a secretos se deniega por defecto.
-2. Acceso a directorios externos se deniega por defecto.
-3. Operaciones destructivas, externas, privilegiadas o ambiguas requieren aprobacion humana.
-4. Operaciones de filesystem deben estar dentro del workspace.
-
-Esto evita que la seguridad dependa solamente de que el agente “se acuerde” de portarse bien.
-
-## Funcionamiento del MCP
-
-El MCP server es la puerta para que herramientas de IA interactuen con `vgxness`.
-
-Archivo principal:
-
-```text
-src/mcp/stdio-server.ts
-```
-
-El servidor:
-
-1. Crea un `McpServer` llamado `vgxness`.
-2. Crea el control plane local.
-3. Registra todas las tools soportadas.
-4. Conecta por `StdioServerTransport`.
-5. Devuelve respuestas JSON como texto MCP.
-
-El control plane crea servicios sobre la misma base SQLite:
-
-```text
-MemoryService
-SddWorkflowService
-AgentRegistryService
-SkillRegistryService
-RunService
-AgentActivationService
-OpenCodeManagerPayloadService
-```
-
-Tools representativas (no exhaustivas; la fuente actual de nombres soportados es `SUPPORTED_VGX_MCP_TOOL_NAMES`):
-
-| Tool | Funcion |
-|---|---|
-| `vgxness_sdd_status` | Consultar estado de un change SDD. |
-| `vgxness_sdd_ready` | Saber si una fase esta lista. |
-| `vgxness_sdd_next` | Decidir siguiente fase runnable, blocked o complete. |
-| `vgxness_sdd_save_artifact` | Guardar un artefacto SDD. |
-| `vgxness_sdd_get_artifact` / `vgxness_sdd_list_artifacts` | Recuperar artefactos SDD previos como fuente de verdad. |
-| `vgxness_memory_save` | Guardar memoria. |
-| `vgxness_memory_search` | Buscar memoria. |
-| `vgxness_agent_resolve` | Resolver agente para una tarea. |
-| `vgxness_skill_payload` | Construir payload de skills para un contexto. |
-| `vgxness_opencode_manager_payload` | Construir preview read-only para integracion del manager OpenCode. |
-| `vgxness_run_start` | Crear un run. |
-| `vgxness_run_preflight` | Evaluar permisos y plan de seguridad antes de operaciones riesgosas. |
-| `vgxness_run_checkpoint` | Guardar checkpoint. |
-| `vgxness_run_finalize` | Finalizar run. |
-
-## Funcionamiento de la CLI
-
-La CLI se ejecuta localmente con:
-
-```bash
-vgxness <area> <command> [flags]
-```
-
-Areas principales vistas en el dispatcher:
-
-| Area | Funcion |
-|---|---|
-| `setup` / `init` | Estado de setup local. |
-| `agents` | Registro, listado, resolucion y render de agentes. |
-| `subagents` | Operaciones sobre subagentes. |
-| `memory` | Operaciones de memoria. |
-| `runs` | Runs, checkpoints, approvals y estado. |
-| `permissions` | Evaluacion de permisos. |
-| `skills` | Registro, resolucion, propuestas y evaluacion de skills. |
-| `sdd` | Estado, readiness y guardado de artefactos SDD. |
-| `orchestrator` | Preview de ruteo desde lenguaje natural hacia direct, plan, sdd o diagnose. |
-| `opencode` | Previews/integracion OpenCode. |
-| `mcp` | Setup, doctor e instalacion MCP. |
-
-La base se selecciona con la misma regla que el resto del sistema:
-
-```text
---db <path> > VGXNESS_DB_PATH > base global de usuario
-```
-
-Sin `--db`, la CLI usa la base global de usuario. Si se quiere la base del repo para pruebas locales, se debe pedir explicitamente:
-
-```bash
-vgxness sdd status --project vgxness --change my-change --db .vgx/memory.sqlite
-```
-
-## Setup local
-
-El setup busca contestar si el proyecto esta listo para usar `vgxness`.
-
-`SetupLifecycleService` revisa:
-
-| Check | Que verifica |
-|---|---|
-| Store | Que la base local este disponible. |
-| MCP | Que OpenCode MCP este visible o tenga acciones sugeridas. |
-| Default context | Que exista el agente default `vgxness-manager`. |
-
-La respuesta incluye `nextAction`, por ejemplo sembrar agentes, revisar MCP o listar runs.
-
-## Integracion con OpenCode
-
-OpenCode aparece como primer adapter concreto.
-
-El sistema puede:
-
-1. Generar previews de configuracion.
-2. Diagnosticar visibilidad MCP desde el worktree.
-3. Planificar instalacion sin escribir archivos.
-4. Aplicar instalacion solo con confirmacion explicita.
-5. Preservar configuracion existente y crear backups cuando corresponde.
-
-Un limite importante: las operaciones de preview no escriben `.opencode/`, `.claude/` ni configuracion global. Esa separacion es intencional para mantener seguridad y revisabilidad.
-
-El manager OpenCode versionado (`vgxness-manager`) es MCP-first: al iniciar, reanudar o recuperar contexto llama `vgxness_session_restore` con proyecto y directorio del workspace antes de inferir desde el chat; consulta estado SDD con `sdd_status`/`sdd_next`/`sdd_ready`, recupera prerequisitos con `sdd_get_artifact` o `sdd_list_artifacts`, resuelve el subagente exacto con `agent_resolve`, delega la fase, guarda el artefacto aceptado con `sdd_save_artifact` y usa `run_preflight`/`run_checkpoint`/`run_finalize` cuando el trabajo es significativo. Antes de terminar, pausar, handoff o compactar llama `vgxness_session_close` con el session id actual, actor `manager` y un resumen accionable; si no hay session id, no lo inventa y preserva el resumen en la respuesta final. Preguntas simples o respuestas read-only no necesitan crear runs por defecto.
-
-La integracion mantiene `permission.task` deny-by-default: el manager solo puede delegar a subagentes SDD canonicos por nombre exacto. Las instrucciones del seed incluido son autosuficientes y no requieren archivos externos `~/.config/opencode/skills/sdd-*`; esas skills pueden registrarse como mejora opcional, pero no son requisito. `vgxness_opencode_manager_payload` es solo preview/read-only: no instala, no ejecuta OpenCode, no carga seeds y no escribe configuracion global.
-
-## Que esta implementado hoy y que es objetivo
-
-El proyecto ya contiene implementaciones concretas de:
-
-1. Memoria SQLite con migraciones.
-2. SDD workflow con estado, readiness, next y guardado de artefactos.
-3. Orquestador de lenguaje natural preview-only con clasificacion `direct`, `plan`, `sdd` y `diagnose`.
-4. Registro y resolucion de agentes.
-5. Registro, versionado, resolucion y propuestas de skills.
-6. Runs con eventos, checkpoints, approvals, preflight y finalizacion.
-7. Politica de permisos base.
-8. MCP stdio server y control plane.
-9. CLI para operar los servicios.
-10. Setup status y TUI local.
-11. Integracion inicial con OpenCode.
-12. CLI instalable con memoria global por defecto y compatibilidad explicita con `--db`.
-
-La arquitectura objetivo documentada en `docs/architecture.md` amplia esa base hacia:
-
-1. TUI mas completa.
-2. Configurador de assets mas amplio.
-3. Multiples providers como Claude Code y futuros adapters.
-4. Perfiles/model routing mas avanzados.
-5. Auditoria y trazabilidad mas profundas.
-6. Flujos de instalacion guiados mas completos.
-
-Esta distincion importa. `vgxness` ya tiene un nucleo funcional, pero tambien es una plataforma en evolucion.
-
-## Recorrido completo de ejemplo
-
-Supongamos que se quiere trabajar en un cambio llamado `add-agent-profiles`.
-
-### 1. Revisar setup
-
-```bash
-vgxness setup status --project vgxness
-```
-
-El sistema revisa store, MCP y agente default.
-
-### 2. Clasificar el pedido natural
-
-```bash
-vgxness orchestrator preview --project vgxness --intent "Build a new agent profile workflow" --change add-agent-profiles
-```
-
-El sistema devuelve un preview no ejecutable. Si detecta nueva capacidad, arquitectura, workflow, persistencia, seguridad o riesgo de ejecucion, recomienda `sdd` y puede incluir el proximo comando manual de SDD.
-
-### 3. Consultar estado SDD
-
-```bash
-vgxness sdd status --project vgxness --change add-agent-profiles
-```
-
-Si no hay artefactos, la primera fase lista deberia ser `explore`.
-
-### 4. Guardar el artefacto de exploracion
-
-```bash
-vgxness sdd save-artifact --project vgxness --change add-agent-profiles --phase explore --content "# Explore"
-```
-
-El sistema guarda el contenido en memoria como artefacto con topic key:
-
-```text
-sdd/add-agent-profiles/explore
-```
-
-### 5. Preguntar la siguiente fase
-
-```bash
-vgxness sdd next --project vgxness --change add-agent-profiles
-```
-
-Si `explore` esta presente, la siguiente fase runnable sera `proposal`.
-
-### 6. Resolver un agente para implementar
-
-```bash
-vgxness agents resolve --project vgxness --workflow sdd --phase apply-progress --provider opencode --task "Implement agent profile routing"
-```
-
-El sistema devuelve candidatos con score y razones.
-
-### 7. Crear un run
-
-El agente o la CLI crean un run para registrar la operacion.
-
-Desde MCP seria una llamada a:
-
-```text
-vgxness_run_start
-```
-
-### 8. Evaluar permisos antes de operar
-
-Antes de acciones riesgosas, el run puede hacer preflight.
-
-```text
-vgxness_run_preflight
-```
-
-Si la operacion es destructiva, externa, privilegiada o ambigua, el sistema pide aprobacion o bloquea.
-
-### 9. Guardar checkpoints
-
-Durante el trabajo, el agente puede persistir progreso.
-
-```text
-vgxness_run_checkpoint
-```
-
-Eso permite retomar si la sesion se corta.
-
-### 10. Verificar y archivar
-
-Cuando el cambio avanza, SDD exige pasar por `verify` y luego `archive`, cada uno con su artefacto correspondiente.
-
-## Principio de diseno mas importante
-
-El principio clave es separar comportamiento de agente y estado de producto.
-
-| Capa | Que hace |
-|---|---|
-| Comportamiento de agente | Prompts, skills, instrucciones, modelos y adapters ayudan a ejecutar bien. |
-| Estado de producto | SQLite, SDD, runs, permisos y trazas dicen que paso y que se puede hacer ahora. |
-
-Si todo vive solo en prompts, el sistema depende de disciplina del LLM. Si todo vive solo en estado pero los agentes no reciben buen contexto, el sistema es burocratico. `vgxness` necesita ambas partes.
-
-## Estructura de carpetas relevante
-
-```text
-src/
-  agents/        Registro, resolucion, activacion y renderers de agentes.
-  cli/           Dispatcher, TUI y renderers de salida CLI.
-  export/        Redaccion/export de snapshots.
-  harness/       Handlers reutilizables para tools internas.
-  mcp/           Servidor stdio, schemas, validacion, doctor e instalacion MCP.
-  memory/        Servicio de memoria, repositorios, busqueda y SQLite.
-  orchestrator/  Planner preview-only para clasificar lenguaje natural.
-  permissions/   Politica y schema de permisos.
-  providers/     Integraciones por proveedor, hoy principalmente OpenCode.
-  runs/          Runtime de ejecuciones, eventos, checkpoints y approvals.
-  sdd/           Workflow SDD, schemas y portabilidad de artefactos.
-  setup/         Estado de setup local.
-  skills/        Registro, resolucion, payloads y propuestas de skills.
-
-docs/
-  architecture.md                Arquitectura objetivo y decisiones principales.
-  prd.md                         Vision de producto y alcance MVP.
-  cli.md                         Uso de CLI y flujos operativos.
-  funcionamiento-del-sistema.md  Este documento.
-```
-
-## Como pensar el sistema
-
-Una buena forma de entender `vgxness` es verlo como una torre de control local.
-
-Los agentes son los aviones: ejecutan, se mueven rapido y hacen trabajo complejo. Pero la torre de control mantiene rutas, permisos, estado, historial y reglas de seguridad. Sin torre, cada avion decide por su cuenta. Sin aviones, la torre no produce valor. El sistema funciona cuando ambas partes colaboran.
-
-En terminos practicos:
-
-1. El humano define intencion y revisa decisiones importantes.
-2. Los agentes ejecutan trabajo especializado.
-3. `vgxness` guarda estado, valida readiness y registra evidencia.
-4. Las herramientas proveedoras son adaptadores, no la fuente unica de verdad.
-
-## Checklist para entender si el sistema esta funcionando
-
-Un proyecto `vgxness` sano deberia poder responder estas preguntas:
-
-1. Donde esta mi base local y esta disponible?
-2. Que flow recomienda el orquestador para este pedido natural?
-3. Que agentes tengo registrados?
-4. Que skills estan activas y para que contexto aplican?
-5. En que fase SDD esta mi cambio?
-6. Que artefactos faltan para avanzar?
-7. Que runs se ejecutaron y como terminaron?
-8. Que operaciones pidieron aprobacion?
-9. Que checkpoints permiten retomar trabajo?
-10. Que evidencia existe de verificacion?
-11. Que configuracion de proveedor fue preview, planificada o aplicada?
-
-Si esas respuestas existen en estado local y no solo en memoria conversacional del agente, el sistema esta cumpliendo su objetivo.