okf-mcp y vord: memoria y guardarraíles para agentes de IA

El código necesita controles repetibles para proteger la arquitectura, y los agentes necesitan límites, no prompts pidiendo por favor que se porten bien.

Aquí es donde okf-mcp y vord encajan perfectamente: 🧠 okf-mcp aporta memoria técnica estructurada, versionada y navegable (como servidor MCP puro en Rust). 🛡️ vord aporta análisis estático y validación de políticas configurables.

La idea no es añadir otro linter aislado, sino conectar contexto, decisión, implementación y validación en un único flujo coherente.

1. El ciclo empieza leyendo, no escribiendo

Antes de que un agente (o un humano) modifique código, debe mapear el terreno. Con la herramienta memory_search de okf-mcp, localizamos decisiones y convenciones mediante búsqueda semántica. Después, memory_resolve y memory_reason recuperan el concepto completo y deducen relaciones implícitas en el grafo.

La memoria deja de ser pasiva: ofrece un vocabulario y relaciones recuperables que ayudan a mantener consistencia semántica, reduciendo el riesgo de que la IA llame hoy depends_on a lo que ayer llamó requires.

2. Convertir la idea en un Acuerdo Técnico

Una vez entendido el contexto, usamos spec_propose para crear un spec. Este documento define el problema, el comportamiento esperado y —crucialmente— las alternativas descartadas.

La memoria permite recuperar estas alternativas descartadas y sus razones, reduciendo la probabilidad de reabrir debates ya resueltos. Luego, spec_tasks descompone el spec en un grafo de tareas reales, evitando que queden desconectadas de su intención técnica.

3. El “Kickoff” y el Contrato BDD como evidencia 🚀

La calidad no empieza con el primer warning, empieza al estructurar el proyecto. Ejecutar vord kickoff <template> genera una base con dirección arquitectónica (React, Rust, Python, TypeScript o Fullstack Hexagonal). Para repositorios existentes, vord init permite generar un vord.toml ajustado al proyecto sin necesidad de arrancar desde una plantilla.

Pero vord no solo genera estructura; también prepara un scaffold BDD (features/*.feature). Antes de implementar, los criterios de aceptación del spec se convierten en escenarios Gherkin (comportamientos, casos límite).

Un matiz importante: Gherkin no sustituye las pruebas unitarias, de integración o end-to-end. Vord no ejecuta los escenarios: lee su estructura y sus etiquetas (@covers(...)) para comprobar evidencia y aplicar políticas. La ejecución real sigue correspondiendo al runner de tests elegido por el proyecto. Así, Gherkin puede conectar la intención del spec con una política verificable de evidencia.

4. Ejecución bajo guardarraíles y cobertura real 🚧

Durante la implementación, Vord está diseñado para un ciclo de edición, escaneo y corrección muy rápido. El objetivo es reducir al mínimo la distancia entre introducir una desviación y detectarla.

vord scan analiza el workspace y reporta problemas de arquitectura, complejidad, duplicación, seguridad o reglas definidas por el repositorio. Cuando existen autofixes aplicables, vord scan --fix puede aplicarlos; para correcciones asistidas sobre un issue concreto existe vord fix.

Los hallazgos se convierten en bloqueantes cuando la política del repositorio así lo configura. En entornos donde las escrituras pasan por el hook de Vord, una modificación que incumpla una regla o carezca de evidencia Gherkin exigida puede ser denegada antes de consolidarse.

Además, Vord puede detectar desviaciones arquitectónicas en la implementación asociada a los escenarios BDD. Por ejemplo, un paso Gherkin que alcanza infraestructura directamente, en lugar de atravesar la capa de aplicación, puede reportarse como una violación de arquitectura.

Para cobertura más amplia, Vord puede importar resultados SARIF de herramientas como Oxlint, Ruff o Clippy y unificarlos en el mismo quality gate. Y mediante vord flow add, el equipo puede declarar secuencias críticas —por ejemplo, checkout: inicio → stock → cobro— que el análisis estático no puede reconstruir por sí solo.

La trazabilidad no es automática, pero puede hacerse explícita: Spec → tareas → escenarios BDD → flujos registrados → evidencia de análisis y cobertura.

5. Auditoría y gobierno de excepciones

Los guardarraíles no deben convertirse en una caja negra. Las políticas necesitan trazabilidad: qué se bloqueó, por qué se bloqueó, qué excepción fue aprobada y quién tomó esa decisión. La automatización protege el flujo, pero la responsabilidad sobre las excepciones sigue siendo humana.

Vord incorpora un registro de decisiones no silenciosas consultable con vord hook audit. Las escaladas pueden requerir una aprobación explícita y de un solo uso antes de permitir una escritura previamente denegada por la política.

6. Salud de la Memoria y Cierre del Aprendizaje 🧠

Una memoria técnica solo es útil si sigue siendo confiable. Aquí es donde el mantenimiento del grafo brilla:

memory_validate permite detectar enlaces rotos, referencias a conceptos eliminados y embeddings ausentes.
memory_status y memory_stats aportan visibilidad operativa. No basta con almacenar decisiones; hay que mantener navegable y consistente el grafo que las conecta.

Las decisiones también cambian. Con memory_history podemos entender cuándo y por qué evolucionó una norma; con memory_backlinks, evaluar su impacto antes de modificarla. Y con memory_patch o las operaciones bulk, actualizar metadatos de forma selectiva. La documentación se comporta como un activo versionado.

Cerrando el bucle: el ciclo se cierra cuando la evidencia técnica vuelve a la memoria. Tras un cambio, el equipo puede usar memory_consolidate en okf-mcp para guardar qué reglas de Vord se validaron, qué hallazgos se corrigieron, qué excepciones fueron aprobadas y qué riesgos permanecen abiertos. La siguiente tarea ya no parte solo del código actual: parte también de la evidencia y las decisiones de los cambios anteriores.

💡 La idea central

okf-mcp responde a una pregunta: ¿Qué sabemos, qué decidimos y cómo se relaciona? vord responde a otra: ¿El código respeta las reglas, la arquitectura y el nivel de calidad que esperamos?

Combinados, permiten construir un ciclo de ingeniería completo, reduciendo la distancia entre lo que el equipo sabe, lo que acuerda construir, y lo que finalmente verifica en el disco. La autonomía de la IA no se logra solo con un modelo más inteligente, sino construyendo una infraestructura auditable que canalice su trabajo.

Lista de herramientas y comandos de vord y okf-mcp

🧠 Herramientas de okf-mcp

Para descubrir y navegar conocimiento:

memory_search: busca conceptos combinando coincidencia textual y similitud semántica.
memory_resolve: recupera un concepto completo, su frontmatter y sus enlaces relacionados.
memory_reason: deduce relaciones implícitas mediante razonamiento OWL-RL/RDFS ligero.
memory_list: lista conceptos por rutas o prefijos, sin descargar su contenido completo.
memory_backlinks: muestra qué conceptos apuntan hacia una decisión o documento.

Para crear, versionar y mantener conocimiento:

memory_commit: crea o actualiza conceptos con control de concurrencia optimista mediante CAS.
memory_patch: actualiza campos concretos del frontmatter YAML sin modificar el contenido principal.
memory_bulk_commit: aplica múltiples commits, con opción de transacción atómica.
memory_bulk_patch: actualiza metadatos de varios conceptos en una sola operación.
memory_history: recupera el historial completo de revisiones de un concepto.
memory_delete: realiza un borrado lógico y preserva el historial.
memory_consolidate: conserva lo ocurrido en la sesión como un resumen durable.

Para asegurar la salud del grafo:

memory_validate: detecta enlaces rotos, referencias eliminadas y embeddings ausentes.
memory_status: muestra el estado de salud general del sistema.
memory_stats: analiza tipos, tags, hubs de enlaces y conceptos huérfanos.
memory_embed: fuerza la generación o actualización de embeddings.

Para trabajar guiado por especificaciones:

spec_propose: crea un spec con requisitos y diseño acordados.
spec_tasks: descompone un spec en tareas enlazadas a su origen.
spec_status: muestra estado, progreso y tareas listas para comenzar.

Para incorporar conocimiento externo:

skill_ingest: ingiere skills, archivos, carpetas o repositorios externos como conceptos, sin pasar su contenido por el LLM cuando el servidor tiene un descargador configurado.

🛡️ Herramientas MCP de vord

Para analizar, corregir y arrancar proyectos:

vord_scan: ejecuta análisis estático sobre el workspace y devuelve los hallazgos.
vord_fix: aplica correcciones autofixables a reglas detectadas.
vord_kickoff: genera un proyecto inicial desde una plantilla de Vord.

Para coordinación opcional por roles:

vord_swarm_roles: muestra roles, topología y alcance de políticas.
vord_swarm_handoff: crea, entrega o consulta handoffs entre roles.

Comandos CLI de Vord

Los comandos más relevantes son estos:

vord init: crea una configuración vord.toml para un repositorio existente.
vord kickoff <template>: genera una estructura inicial para un proyecto nuevo.
vord scan: analiza archivos o directorios y reporta problemas.
vord scan --fix: aplica correcciones automáticas disponibles.
vord scan --enforce-gate: falla si no se cumple el quality gate configurado.
vord fix: propone una corrección de IA para un issue concreto.
vord arch: visualiza dependencias, ciclos y métricas arquitectónicas.
vord flow add: registra flujos críticos para comprobar cobertura y deriva.
vord mcp: inicia el servidor MCP por stdio.

Para aplicar políticas de escritura y auditoría:

vord hook install: instala la configuración de políticas y hooks.
vord hook check <file>: evalúa un archivo contra la política.
vord hook claude-code: recibe una propuesta de escritura y devuelve el veredicto de política.
vord hook approve <token>: aprueba una excepción de un solo uso.
vord hook audit: consulta el registro de decisiones no silenciosas.
vord hook reset-circuit-breaker: reinicia el circuito de protección tras intervención humana.
vord hook reset-loop-guard: limpia el contador de alarmas por repeticiones.

🔗 okf-mcp: github.com/pmaojo/okf-mcp · 🔗 vord: github.com/pmaojo/vord