vgxness 1.13.0 → 1.14.1

package/docs/cli.md

@@ -577,7 +577,7 @@ This seed file is repo-only in v1.3.0 package contents. If installed-package wor
 
 The command prints an `AgentSeedLoadSummary` JSON payload with `created`, `updated`, `agents`, `subagents`, and `warnings`. Re-running the same seed is safe: records are upserted by the current project, scope, and name, so existing seed records are updated in place instead of duplicated.
 
-The checked-in `vgxness-manager` and SDD subagents are self-contained: their seed instructions describe the MCP-first orchestration contract inline and do not require installing `~/.config/opencode/skills/sdd-*`. SDD skills can still be registered and attached as optional registry assets when a project wants extra reusable guidance.
+The checked-in `vgxness-manager` and SDD subagents are self-contained: their seed instructions describe the MCP-first orchestration contract inline and do not require external provider-native skill directories. SDD skills can still be registered and attached as optional VGXNESS registry assets when a project wants extra reusable guidance.
 
 Seed loading preserves user-created agents that are absent from the manifest. It only writes to the selected local registry database (`--db`, `VGXNESS_DB_PATH`, or the global default); it does **not** create `.opencode/`, `.claude/`, provider config, or user/global OpenCode configuration.
 
@@ -592,20 +592,18 @@ The render command returns preview artifacts only and keeps provider config unto
 
 ## Skill examples
 
-Register an optional provider-agnostic skill, add an active version, attach it to a workflow phase, and record a simple run outcome. These examples are registry-managed enhancements, not requirements for the checked-in OpenCode manager/subagents:
+Inspect the built-in VGXNESS registry/context skills and resolve the context that would be available to a workflow phase. These examples are registry-managed guidance only; they do not install provider-native OpenCode skills or write provider config:
 
 ```bash
-bun run cli:bun -- skills register --project vgxness --name sdd-apply --description "Applies focused SDD slices"
-bun run cli:bun -- skills add-version --project vgxness --name sdd-apply --version 1.0.0 --source-kind path --source-path .config/opencode/skills/sdd-apply/SKILL.md --activate
-bun run cli:bun -- skills attach --project vgxness --name sdd-apply --target-type workflow-phase --target-key sdd:apply
-bun run cli:bun -- skills record-usage --project vgxness --name sdd-apply --outcome helped --run-id <run-id> --target-type workflow-phase --target-key sdd:apply
+bun run cli:bun -- skills get --project vgxness --name vgxness-sdd-apply
+bun run cli:bun -- skills payload --project vgxness --workflow sdd --phase apply-progress --intent-signals git,tdd,review-size --provider opencode
 ```
 
 Resolve the skills that would be available to a runtime context:
 
 ```bash
-bun run cli:bun -- skills resolve --agent apply-agent --project vgxness --workflow sdd --phase apply --provider opencode
-bun run cli:bun -- skills resolve --agent apply-agent --project vgxness --phase apply --run <run-id> --record-usage selected
+bun run cli:bun -- skills resolve --project vgxness --workflow sdd --phase apply-progress --intent-signals git,tdd,review-size --provider opencode
+bun run cli:bun -- skills resolve --project vgxness --workflow plan --phase pr --intent-signals workflow-selection,pull-request --provider opencode
 ```
 
 `skills resolve` is read-only by default. It combines matching skill attachments plus the agent definition `skills` field, returns active/current versions only, and includes source metadata plus inline `summary`/`content` when available. It records `selected` or `injected` usage only when both `--run` and `--record-usage` are explicit.
@@ -619,10 +617,13 @@ bun run cli:bun -- skills status --project vgxness --scope project --provider op
 
 `skills status` prints deterministic JSON with `kind: "skills-status"` and `version: 1`. It includes project/scope/provider context, registry skill counts and current-version status, declared/resolved/missing skills for matching agents or subagents, resolver diagnostics, and safety markers. The command is read-only: it does not repair, install, or write provider configuration and does not record skill usage. A missing `--agent` match returns valid JSON with a warning diagnostic instead of crashing.
 
-Create and review a skill improvement proposal without activating it:
+Register and review an optional project-local registry skill without activating provider-native OpenCode skill loading:
 
 ```bash
-bun run cli:bun -- skills propose --project vgxness --name sdd-apply --proposed-version 1.1.0 --source-kind inline --inline-metadata '{"content":"Updated skill body"}' --rationale "Repeated correction from trace" --source-signal '{"kind":"trace-failure"}'
+bun run cli:bun -- skills register --project vgxness --name team-review-guidance --description "Team-specific review guidance"
+bun run cli:bun -- skills add-version --project vgxness --name team-review-guidance --version 1.0.0 --source-kind inline --inline-metadata '{"content":"Check product risk, review size, and rollback notes."}' --activate
+bun run cli:bun -- skills attach --project vgxness --name team-review-guidance --target-type intent-signal --target-key review-size
+bun run cli:bun -- skills propose --project vgxness --name team-review-guidance --proposed-version 1.1.0 --source-kind inline --inline-metadata '{"content":"Revised team guidance."}' --rationale "Repeated correction from trace" --source-signal '{"kind":"trace-failure"}'
 bun run cli:bun -- skills proposals --status draft
 bun run cli:bun -- skills get-proposal --proposal <proposal-id>
 ```
@@ -640,7 +641,7 @@ Rejected or cancelled proposals cannot be applied. These commands store reviewab
 Build an injection-ready payload without mutating provider config:
 
 ```bash
-bun run cli:bun -- skills payload --agent apply-agent --project vgxness --workflow sdd --phase apply --provider opencode
+bun run cli:bun -- skills payload --project vgxness --workflow sdd --phase apply-progress --intent-signals git,tdd,review-size --provider opencode
 ```
 
 `skills payload` resolves the same active skills and returns payload v1 JSON: skill identity/version, source kind, available content or an unavailable reason, attachment reasons, and ordering metadata. Inline `content` is included directly. Local `path` sources are loaded read-only only when they resolve inside the current workspace root. URL sources are never fetched in v1 and return `url_fetch_disabled`. The command does **not** write `.opencode/`, `.claude/`, provider prompts, or external skill files.
@@ -648,7 +649,7 @@ bun run cli:bun -- skills payload --agent apply-agent --project vgxness --workfl
 `skills get` returns the current version, all versions, attachments, and usage records:
 
 ```bash
-bun run cli:bun -- skills get --project vgxness --name sdd-apply
+bun run cli:bun -- skills get --project vgxness --name vgxness-sdd-apply
 bun run cli:bun -- skills list --project vgxness
 ```
 
@@ -676,7 +677,7 @@ Use `--file` when a definition has permissions, memory, workflows, skills, or ad
   "permissions": { "read": "allow", "edit": "ask", "shell": "ask" },
   "memory": { "scopes": ["project"] },
   "workflows": ["sdd"],
-  "skills": ["sdd-apply"],
+  "skills": ["vgxness-sdd-apply"],
   "adapters": { "opencode": { "model": "openai/gpt-5.5" } }
 }
 ```

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

@@ -1,5 +1,7 @@
 # Auditoría de salud del proyecto VGXNESS v1.10.x
 
+> Historical snapshot: this document records the v1.10.x health review and should not be treated as current status. See [Project health audit v1.14.x](./project-health-audit-v1.14.x.md) for the current system snapshot.
+
 ## Resumen ejecutivo
 
 VGXNESS v1.10.x está en un punto avanzado como **CLI/MCP control plane local-first** para SDD, memoria, runs, permisos, agentes, skills y setup de OpenCode. La base de producto es sólida: hay workflow SDD canónico, storage SQLite local, superficies read-only/advisory, provider doctor, agent manifest canónico y verificación Bun-first.

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

@@ -0,0 +1,79 @@
+# Auditoría de salud del proyecto VGXNESS v1.14.x
+
+## Resumen ejecutivo
+
+VGXNESS v1.14.x está avanzado como **CLI/MCP control plane local-first** para SDD, memoria, runs, permisos, agentes, skills y setup de OpenCode. La base de producto es sólida: el flujo SDD canónico existe como estado SQLite-backed, OpenCode es el provider primario, los drafts y la aceptación humana están separados, y la ruta oficial de verificación es Bun-first.
+
+No debe tratarse como “versión final cerrada” hasta resolver la brecha de ejecución/recovery productiva. El sistema gobierna, audita, planea y guía mejor de lo que ejecuta efectos reales de forma autónoma: el executor real, `resume-after-approval`, materialización de sandbox/worktree y evidencia integrada en cockpit siguen siendo trabajo planificado.
+
+Esta auditoría es una foto de release-readiness v1.14.x basada en inspección del repositorio, subauditorías internas y verificación local de release candidate. No publica artefactos ni sustituye la aprobación humana explícita de publicación.
+
+## Evidencia observada
+
+| Área | Evidencia | Estado |
+|---|---|---|
+| Package | `package.json` declara `version: 1.14.1` y expone los binarios `vgxness`/`vgx` desde `dist/cli/bun-bin.js`. | Implementado |
+| Release history | `CHANGELOG.md` contiene `v1.14.1 — 2026-06-17` para el cierre de release-readiness posterior al tag `v1.14.0`. | Implementado |
+| Runtime/tooling | `package.json` codifica la ruta oficial `bun run verify`: typecheck, tests Node, tests Bun storage-backed, Bun SQLite y evidencia de paquete. | Implementado |
+| Release candidate verification | La ruta completa `verify:typecheck`, `verify:test`, `verify:test:bun-storage`, `verify:bun-sqlite` y `package:bun:evidence -- --require-pass` pasó localmente; package evidence reportó `releaseReadiness.status: pass` y `publicationAttempted: false`. | Validado |
+| CI | `.github/workflows/node22.yml` ahora ejecuta también `bun run verify:test:bun-storage`, alineando el gate principal con `package.json`. | Alineado |
+| CLI/MCP | README y docs describen CLI para bootstrap/diagnóstico/recovery y MCP para trabajo diario dentro de OpenCode. | Implementado |
+| SDD | Fases canónicas `explore → proposal → spec → design → tasks → apply-progress → verify → archive`; aceptación humana separada de presencia de artifact. | Implementado |
+| Providers | OpenCode es primario; Claude es secundario/guarded; Antigravity/custom son placeholder/extensión. | Implementado con límites |
+| Code runtime | El runtime experimental `vgxness code` y la superficie principal OpenTUI están removidos temporalmente. | Fuera de release |
+| Docs | README, architecture, providers, roadmap y auditorías históricas apuntan a este snapshot v1.14.x como actual. | Alineado |
+
+## Estado por superficie
+
+### CLI y MCP
+
+La CLI está madura para setup, status, recuperación, SDD, runs, permisos, agentes, skills, MCP y verificación. La superficie MCP es la ruta diaria recomendada para trabajar desde OpenCode con subagentes SDD ocultos. Los comandos preview/status/plan mantienen el contrato no mutante respecto a provider config; las escrituras de config requieren consentimiento explícito.
+
+### SDD governance
+
+La fortaleza principal del producto es que SDD no depende solo de prompts: fases, artifacts, readiness, aceptación humana, runs y eventos viven como estado consultable. La aceptación humana sigue siendo un gate separado; guardar drafts no implica aceptación.
+
+### Release y paquete
+
+El release gate debe ser Bun-first:
+
+```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 -- --require-pass
+```
+
+CI debe permanecer alineado con esa ruta. La publicación sigue siendo una operación separada, explícita y humana; esta auditoría no aprueba ni intenta publicación.
+
+### Ejecución y recovery
+
+El mayor gap de producto sigue siendo operacional: `docs/roadmap.md` marca como pendiente el executor real, `resume-after-approval`, materialización sandbox/worktree y mejores resúmenes de evidencia de verificación. Hasta cerrar eso, VGXNESS es muy fuerte como control plane y guía de workflow, pero no como runtime autónomo final.
+
+## Riesgos principales
+
+| Riesgo | Impacto | Recomendación |
+|---|---|---|
+| Release tag pendiente | Riesgo de publicar contenido sin tag/release note correspondiente. | Taggear/publicar solo después de revisar diff final y con aprobación humana explícita. |
+| Execution/resume gap | El producto puede dejar al usuario en recuperación manual para runs complejos. | Priorizar executor real, checkpoints útiles y `resume-after-approval`. |
+| Cockpit sin evidencia rica | “Por qué está bloqueado” puede requerir inspección adicional. | Integrar pass/fail/skipped, timestamp y evidencia por fase. |
+| Provider wording drift | Usuarios pueden asumir paridad completa fuera de OpenCode. | Mantener OpenCode como primario y Claude/otros con límites explícitos. |
+| TUI/code-runtime removidos | Puede haber expectativas viejas de `vgxness code`. | Mantener docs claras: la ruta diaria es OpenCode + MCP; CLI es fallback/diagnóstico. |
+
+## Próximo paso recomendado
+
+Para cerrar un release candidate v1.14.x:
+
+1. Revisar el diff final y commit/tag de release si corresponde.
+2. Confirmar que CI reproduce la cadena oficial completa en la rama remota.
+3. No publicar hasta que la evidencia de paquete reporte `releaseReadiness.status: pass` y exista aprobación humana explícita.
+
+Para avanzar hacia “versión final” de producto, abrir un cambio SDD separado para **final-product readiness hardening** con foco en executor/recovery/cockpit evidence.
+
+## Fuera de alcance de esta auditoría
+
+- No se publicó ni se contactó un registry.
+- No se mutó provider config.
+- No se aceptó ningún artifact SDD.
+- No se creó tag de release.

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

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

package/docs/providers.md

@@ -4,7 +4,7 @@ VGXNESS is provider-agnostic at the core: the registry stores provider-neutral d
 
 ## Status
 
-Current as of the v1.10.x documentation snapshot.
+Current as of the v1.14.x documentation snapshot.
 
 | Provider | Control plane | Workspace runtime | Notes |
 |---|---|---|---|

package/docs/roadmap.md

@@ -41,7 +41,7 @@ SQLite, scopes, migrations, and the run snapshot export are in.
 
 ## TUI
 
-The principal code surface is in via OpenTUI. The legacy interactive setup surfaces and dashboard directory are absent in the current tree.
+The previous principal OpenTUI code surface is temporarily unavailable. The legacy interactive setup surfaces and dashboard directory are absent in the current tree; future TUI work should be rebuilt around the current MCP/CLI control-plane boundaries rather than the removed runtime.
 
 - **TUI dashboard screen.** Real-time view of active runs, pending approvals, and SDD blockers. Should match the cockpit surface from MCP.
 - **TUI runs screen.** Run list, drill into a run, see events/approvals/attempts, with read-only safe actions.

package/docs/sdd-flow.es.md

@@ -0,0 +1,403 @@
+# Flujo SDD
+
+> Versión en inglés: [SDD Flow](./sdd-flow.md).
+
+> **Alcance:** este documento explica el flujo SDD completo en VGXNESS: desde una intención humana, pasando por artefactos de planeación, progreso de implementación, verificación y archivo. Es una guía práctica para operadores y acompaña a [Architecture](./architecture.md), [Safety](./safety.md), [CLI](./cli.md) y [MCP tools](./mcp.md).
+
+VGXNESS trata SDD como estado real del producto, no solo como instrucciones para agentes. Cada fase produce un artefacto guardado localmente en SQLite, y el avance entre fases se controla mediante readiness explícito y, cuando aplica, aceptación humana explícita.
+
+Las fases canónicas de SDD son:
+
+```text
+explore → proposal → spec → design → tasks → apply-progress → verify → archive
+```
+
+## Modelo mental
+
+```text
+Intención humana
+  ↓
+Conversación en OpenCode / acción del operador por CLI
+  ↓
+Superficie VGXNESS MCP o CLI
+  ↓
+Servicios del control plane
+  ↓
+Artefactos SDD, runs, memoria y checkpoints en SQLite
+```
+
+La separación importante es:
+
+```text
+Conversación ≠ estado
+Draft ≠ aceptación
+Plan ≠ ejecución
+Preflight ≠ permiso automático
+Provider status ≠ escritura de config del provider
+CLI/MCP ≠ reglas de negocio duplicadas
+```
+
+## 1. Intención humana
+
+El flujo empieza cuando el humano expresa un objetivo, normalmente dentro de OpenCode después de instalar el MCP de VGXNESS.
+
+Ejemplo:
+
+```text
+Mejorar el flujo de recuperación de runs interrumpidos para que VGXNESS sugiera cómo continuar de forma segura.
+```
+
+Para cambios sustanciales, VGXNESS no debería saltar directo al código. El camino seguro es inspeccionar el estado SDD actual y elegir la siguiente fase válida.
+
+Superficies útiles:
+
+```text
+sdd_status
+sdd_next
+sdd_continue
+agent_resolve
+agent_activate
+```
+
+Equivalentes por CLI para setup, diagnóstico, recuperación y scripting:
+
+```bash
+vgxness sdd status --project <project> --change <change>
+vgxness sdd next --project <project> --change <change>
+vgxness sdd continue --project <project> --change <change>
+```
+
+## 2. `explore`: entender antes de elegir solución
+
+Objetivo: investigar el problema, los límites actuales del código, decisiones previas, riesgos y posibles enfoques sin comprometerse todavía con una implementación.
+
+Preguntas típicas:
+
+- ¿Dónde vive la lógica relevante?
+- ¿Qué herramientas CLI y MCP ya existen?
+- ¿Qué servicio es dueño de la regla de dominio?
+- ¿Qué restricciones de safety o storage aplican?
+- ¿Qué riesgos harían difícil revisar el cambio?
+
+Para recuperación de runs interrumpidos, la exploración podría revisar:
+
+```text
+src/runs/*
+src/sdd/*
+src/mcp/control-plane.ts
+src/cli/commands/*
+docs/*
+test/*
+```
+
+El artefacto de fase se guarda con el topic key canónico:
+
+```text
+sdd/{change}/explore
+```
+
+Un agente puede marcar el artefacto como ready, pero readiness no es aceptación.
+
+## 3. Aceptación humana de `explore`
+
+VGXNESS separa deliberadamente contenido generado y aprobación humana:
+
+```text
+draft / ready ≠ accepted
+```
+
+Solo una decisión humana de aceptación debería avanzar trabajo posterior que esté gobernado por gates. Esto evita que un agente apruebe silenciosamente su propia dirección.
+
+Ejemplo CLI:
+
+```bash
+vgxness sdd accept-artifact --project <project> --change <change> --phase explore
+```
+
+## 4. `proposal`: elegir dirección de producto
+
+Objetivo: definir qué cambio debe hacerse y por qué.
+
+Una buena propuesta responde:
+
+- ¿Qué problema estamos resolviendo?
+- ¿Quién se beneficia?
+- ¿Qué está dentro del alcance?
+- ¿Qué queda explícitamente fuera del alcance?
+- ¿Qué riesgos o tradeoffs existen?
+- ¿Cómo sabremos que funcionó?
+
+Ejemplo de resumen de propuesta:
+
+```text
+Agregar una superficie read-only de continuación para runs interrumpidos que combine runs failed/blocked/needs-human, el último checkpoint, la fase SDD asociada y una siguiente acción recomendada segura.
+```
+
+Esto sigue siendo definición de dirección, no implementación.
+
+## 5. Aceptación humana de `proposal`
+
+La propuesta es el contrato principal de alcance. Si es demasiado amplia, la implementación y la revisión se vuelven riesgosas.
+
+Pregunta recomendada para revisión:
+
+```text
+¿Esto puede revisarse como un slice coherente o deberíamos dividirlo?
+```
+
+Por ejemplo, un primer slice más seguro puede ser:
+
+```text
+Diagnóstico read-only de runs interrumpidos antes de cualquier recuperación automática o ejecución de provider.
+```
+
+Después de aceptar exactamente la propuesta, se pueden generar borradores downstream de planeación, pero esos artefactos siguen siendo drafts hasta que se revisen y acepten según la gobernanza.
+
+## 6. `spec`: definir comportamiento observable
+
+Objetivo: especificar qué debe hacer el sistema sin sobreadaptarse a detalles de implementación.
+
+Para recuperación de runs interrumpidos, una spec podría requerir:
+
+- Runs con estado `failed`, `blocked` o `needs-human` aparecen como candidatos de recuperación.
+- Cada candidato incluye run id, proyecto, workflow, fase, estado, último checkpoint, razón de fallo o bloqueo y siguiente acción recomendada.
+- El estado vacío es explícito cuando no existen runs interrumpidos.
+- La superficie es read-only y no reanuda providers ni muta estado de runs.
+
+La spec debe incluir casos límite, por ejemplo:
+
+- muchos runs interrumpidos;
+- runs sin checkpoints;
+- runs de otro proyecto;
+- runs ligados a fases SDD ya aceptadas;
+- metadata incompleta o inconsistente.
+
+## 7. `design`: decidir cómo construirlo
+
+Objetivo: conectar la spec con la arquitectura existente.
+
+Un buen diseño identifica:
+
+- límites de servicio;
+- cambios de repository/query;
+- superficies CLI y MCP;
+- agregados de schema;
+- comportamiento de renderers;
+- tests;
+- necesidad de migraciones, si aplica;
+- invariantes de safety.
+
+Ejemplo de diseño:
+
+```text
+Agregar un servicio de candidatos de resume respaldado por el repositorio de runs.
+Exponer herramientas MCP read-only para listar e inspeccionar candidatos.
+Exponer un comando CLI de recuperación/status que use el mismo servicio.
+Mantener la generación de recomendaciones como no-mutante.
+```
+
+Reglas arquitectónicas que preservar:
+
+- CLI y MCP deben compartir servicios de dominio.
+- Los renderers no deben reimplementar reglas de negocio.
+- Las herramientas read-only deben seguir siendo no-mutantes.
+- Las escrituras de configuración de provider requieren consentimiento humano explícito.
+- Los artefactos SDD siguen respaldados por SQLite; no crear `openspec/`.
+
+## 8. `tasks`: hacer el diseño revisable
+
+Objetivo: dividir el diseño en pasos pequeños de implementación.
+
+Ejemplo de desglose:
+
+```text
+1. Agregar query de repositorio para runs interrumpidos.
+2. Agregar servicio de candidatos de resume.
+3. Agregar schema MCP y herramientas read-only.
+4. Agregar comando CLI o extender la superficie existente de recovery/status.
+5. Agregar salida de renderer para estados vacío, único candidato y múltiples candidatos.
+6. Agregar tests enfocados de servicio.
+7. Agregar tests de contrato CLI/MCP.
+8. Actualizar docs si cambia comportamiento visible para el usuario.
+```
+
+Buenas tasks son pequeñas, testeables y fáciles de revisar.
+
+## 9. `apply-progress`: implementar con progreso trazable
+
+Objetivo: hacer el cambio de código mientras se registra qué cambió, qué falta y qué evidencia existe.
+
+Antes de implementar, revisar tamaño y riesgo:
+
+- ¿El cambio toca varios subsistemas?
+- ¿Altera storage o migraciones?
+- ¿Cambia schemas MCP?
+- ¿Cambia comportamiento de safety?
+- ¿El diff es demasiado grande para una sola revisión?
+
+Si el cambio es demasiado amplio, hay que dividirlo antes de implementar.
+
+Durante la implementación, `apply-progress` debería capturar:
+
+- trabajo completado;
+- archivos o módulos modificados;
+- tareas pendientes;
+- resultados de tests;
+- blockers conocidos;
+- desviaciones del diseño aceptado.
+
+`apply-progress` es un registro de progreso, no prueba de que la implementación sea correcta.
+
+## 10. Preflight para operaciones riesgosas
+
+VGXNESS usa preflight checks para mantener explícitas las operaciones riesgosas.
+
+Ejemplos de categorías riesgosas:
+
+```text
+implementation-edit
+shell
+test-run
+install
+git-write
+provider-tool
+secrets
+external-directory
+```
+
+Ejemplo conceptual MCP:
+
+```text
+run_preflight({
+  category: "test-run",
+  operation: "bun run verify:test",
+  workflow: "sdd",
+  phase: "apply-progress"
+})
+```
+
+Preflight es control consultivo/de planeación. No significa que la operación esté automáticamente aprobada o ejecutada.
+
+## 11. `verify`: comprobar la implementación independientemente
+
+Objetivo: verificar la implementación contra la spec y el design aceptados, idealmente con contexto fresco de revisor/agente para cambios no triviales.
+
+La verificación debe revisar:
+
+- que la spec se cumpla;
+- que los límites del diseño se respeten o las desviaciones estén justificadas;
+- que los tests relevantes pasen;
+- que superficies read-only no se hayan vuelto mutantes;
+- que setup/config de providers sigan requiriendo consentimiento explícito;
+- que storage, CLI y MCP sigan siendo consistentes.
+
+Comandos típicos de verificación del repo:
+
+```bash
+bun run verify:typecheck
+bun run verify:test
+bun run verify:bun-sqlite
+bun run package:bun:evidence
+```
+
+No todo cambio pequeño de docs o copy necesita la suite completa. Cambios de storage, schema CLI/MCP, setup de providers o packaging merecen verificación más estricta.
+
+## 12. `archive`: cerrar el cambio con contexto durable
+
+Objetivo: preservar qué ocurrió para que trabajo futuro pueda recuperar contexto sin releer todo el hilo o diff.
+
+Un artefacto de archive debería incluir:
+
+- resultado final;
+- comportamiento visible que cambió;
+- archivos o módulos clave tocados;
+- verificación realizada;
+- riesgos residuales;
+- trabajo de seguimiento;
+- notas de rollback o recuperación, si aplica.
+
+Ejemplo de resumen archive:
+
+```text
+Change: recover-runs
+Outcome: implemented a read-only interrupted-run recovery surface.
+Verification: typecheck and focused service/CLI tests passed.
+Residual risk: full package evidence was not run locally.
+Follow-up: consider TUI integration after the CLI/MCP flow stabilizes.
+```
+
+## Boceto del flujo de herramientas
+
+Dentro de OpenCode, el flujo normalmente se ve así conceptualmente:
+
+```text
+sdd_status
+  ↓
+sdd_continue
+  ↓
+agent_activate(explore)
+  ↓
+sdd_save_artifact(explore)
+  ↓
+sdd_ready(explore)
+  ↓
+humano acepta explore
+  ↓
+agent_activate(proposal)
+  ↓
+sdd_save_artifact(proposal)
+  ↓
+sdd_ready(proposal)
+  ↓
+humano acepta proposal
+  ↓
+agent_activate(spec)
+  ↓
+agent_activate(design)
+  ↓
+agent_activate(tasks)
+  ↓
+humano revisa/acepta artefactos con gate
+  ↓
+agent_activate(apply)
+  ↓
+run_preflight(...)
+  ↓
+sdd_save_artifact(apply-progress)
+  ↓
+agent_activate(verify)
+  ↓
+sdd_save_artifact(verify)
+  ↓
+archive
+```
+
+## Por qué existe este flujo
+
+Un flujo agentic ingenuo sería:
+
+```text
+leer código → editar código → correr tests → decir terminado
+```
+
+VGXNESS usa SDD para hacerlo más seguro:
+
+```text
+entender objetivo
+  ↓
+elegir alcance
+  ↓
+especificar comportamiento
+  ↓
+diseñar el cambio
+  ↓
+dividir en tareas
+  ↓
+implementar con preflight y tracking de progreso
+  ↓
+verificar independientemente
+  ↓
+archivar contexto durable
+```
+
+La estructura inicial cuesta un poco de tiempo, pero reduce scope creep oculto, diffs imposibles de revisar, automatización insegura y pérdida de contexto.