vgxness 1.12.0 → 1.14.0

package/dist/skills/skill-resolver.js

@@ -89,6 +89,7 @@ export class SkillResolver {
                 ...(agent.value?.name !== undefined ? { agentName: agent.value.name } : {}),
                 ...(input.workflow !== undefined ? { workflow: input.workflow } : {}),
                 ...(input.phase !== undefined ? { phase: input.phase } : {}),
+                ...(input.intentSignals !== undefined && input.intentSignals.length > 0 ? { intentSignals: normalizedIntentSignals(input.intentSignals) } : {}),
                 ...(input.providerAdapter !== undefined ? { providerAdapter: input.providerAdapter } : {}),
                 ...(input.runId !== undefined ? { runId: input.runId } : {}),
             },
@@ -121,6 +122,8 @@ export class SkillResolver {
         }
         for (const phase of phases)
             targets.push({ targetType: 'workflow-phase', targetKey: phase });
+        for (const signal of normalizedIntentSignals(input.intentSignals))
+            targets.push({ targetType: 'intent-signal', targetKey: signal });
         if (input.providerAdapter !== undefined)
             targets.push({ targetType: 'provider-adapter', targetKey: input.providerAdapter });
         return dedupeTargets(targets);
@@ -229,6 +232,9 @@ function phaseTargetKeys(workflow, phase) {
 function isSddWorkflow(workflow) {
     return workflow?.trim().toLowerCase() === 'sdd';
 }
+function normalizedIntentSignals(signals) {
+    return [...new Set((signals ?? []).map((signal) => signal.trim().toLowerCase()).filter(Boolean))];
+}
 function stringMetadata(value) {
     return typeof value === 'string' && value.trim() ? value : undefined;
 }

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

@@ -33,9 +33,8 @@ export class SkillSeedService {
                 if (!details.ok)
                     return details;
                 existingVersions.set(seed.name, details.value.versions.some((version) => version.version === seed.version));
-                for (const attachment of details.value.attachments) {
+                for (const attachment of details.value.attachments)
                     existingAttachments.set(`${seed.name}:${attachment.targetType}:${attachment.targetKey}`, true);
-                }
             }
         }
         const transaction = this.database.transaction(() => {
@@ -74,11 +73,12 @@ export class SkillSeedService {
                 const skill = this.registry.getSkillByName(manifest.project, manifest.scope, attachment.skill);
                 if (!skill.ok)
                     throw new SeedLoadError(skill.error);
-                const targetKey = `${attachment.workflow}:${attachment.phase}`;
-                const key = `${attachment.skill}:workflow-phase:${targetKey}`;
+                const targetType = attachmentTargetType(attachment);
+                const targetKey = attachmentTargetKey(attachment);
+                const key = `${attachment.skill}:${targetType}:${targetKey}`;
                 const attachInput = {
                     skillId: skill.value.id,
-                    targetType: 'workflow-phase',
+                    targetType,
                     targetKey,
                     metadata: attachmentMetadata(attachment),
                 };
@@ -138,7 +138,7 @@ function validateManifest(manifest) {
         const validation = validateAttachmentSeed(attachment, names);
         if (!validation.ok)
             return validation;
-        const key = `${attachment.workflow}:${attachment.phase}:${attachment.skill}`;
+        const key = `${attachmentTargetType(attachment)}:${attachmentTargetKey(attachment)}:${attachment.skill}`;
         if (attachments.has(key))
             return validationFailure(`Duplicate skill seed attachment: ${key}`);
         attachments.add(key);
@@ -159,10 +159,18 @@ function validateSkillSeed(skill) {
     return rejectUnsupportedNativeInputs(skill.name, skill.metadata);
 }
 function validateAttachmentSeed(attachment, names) {
-    if (!attachment.workflow?.trim())
-        return validationFailure('Skill seed attachment workflow is required');
-    if (!attachment.phase?.trim())
-        return validationFailure('Skill seed attachment phase is required');
+    if (attachment.targetType !== undefined && !isSkillAttachmentTargetType(attachment.targetType))
+        return validationFailure(`Skill seed attachment targetType is invalid: ${String(attachment.targetType)}`);
+    const targetType = attachmentTargetType(attachment);
+    if (targetType === 'workflow-phase') {
+        if (!attachment.workflow?.trim())
+            return validationFailure('Skill seed attachment workflow is required');
+        if (!attachment.phase?.trim())
+            return validationFailure('Skill seed attachment phase is required');
+    }
+    else if (!attachment.targetKey?.trim()) {
+        return validationFailure(`Skill seed attachment targetKey is required for ${targetType}`);
+    }
     if (!attachment.skill?.trim())
         return validationFailure('Skill seed attachment skill is required');
     if (!names.has(attachment.skill))
@@ -186,20 +194,35 @@ function rejectUnsupportedNativeInputs(name, metadata) {
 function compatibilityFor(seed, attachments) {
     const matching = attachments.filter((attachment) => attachment.skill === seed.name);
     return {
-        targets: ['workflow-phase'],
+        targets: [...new Set(matching.map(attachmentTargetType))],
         adapters: ['opencode'],
-        workflows: [...new Set(matching.map((attachment) => attachment.workflow))],
-        phases: [...new Set(matching.map((attachment) => attachment.phase))],
+        workflows: [...new Set(matching.map((attachment) => attachment.workflow).filter((workflow) => workflow !== undefined))],
+        phases: [...new Set(matching.map((attachment) => attachment.phase).filter((phase) => phase !== undefined))],
     };
 }
 function attachmentMetadata(attachment) {
-    return {
+    const metadata = {
         ...(attachment.metadata ?? {}),
         ...(attachment.order !== undefined ? { order: attachment.order } : {}),
         seededBy: 'vgxness',
-        workflow: attachment.workflow,
-        phase: attachment.phase,
+        targetType: attachmentTargetType(attachment),
+        targetKey: attachmentTargetKey(attachment),
     };
+    if (attachment.workflow !== undefined)
+        metadata.workflow = attachment.workflow;
+    if (attachment.phase !== undefined)
+        metadata.phase = attachment.phase;
+    return metadata;
+}
+function attachmentTargetType(attachment) {
+    return attachment.targetType ?? 'workflow-phase';
+}
+function attachmentTargetKey(attachment) {
+    const targetType = attachmentTargetType(attachment);
+    return targetType === 'workflow-phase' ? `${attachment.workflow}:${attachment.phase}` : attachment.targetKey ?? '';
+}
+function isSkillAttachmentTargetType(value) {
+    return value === 'agent' || value === 'subagent' || value === 'workflow-phase' || value === 'provider-adapter' || value === 'intent-signal';
 }
 function validationFailure(message) {
     return { ok: false, error: { code: 'validation_failed', message } };

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.