ostacky 0.5.10 → 0.6.0

package/assets/skills/execution-mode-evaluation/README.md

@@ -1,257 +0,0 @@
-# execution-mode-evaluation
-
-Decide entre ejecución **inline** o **subagent-driven** según datos concretos de CodeGraph. Evaluación multicapa: modo global + recomendaciones por fase.
-
----
-
-## Contexto de uso
-
-El skill se carga dentro del flujo del agente Ostacky, específicamente en la etapa **Execution** cuando el cambio requiere una decisión informada (Nivel 1+ o Nivel 0+1 con spec):
-
-```
-                    ┌──────────────┐
-                    │  USER REQUEST │
-                    └──────┬───────┘
-                           ▼
-                    ┌──────────────┐
-                    │ 1. DISCOVERY │
-                    │ (CodeGraph)  │
-                    └──────┬───────┘
-                           ▼
-              ┌────────────┴────────────┐
-              ▼                         ▼
-     ┌────────────────┐       ┌──────────────────┐
-     │  Nivel 0       │       │  Nivel 0+1       │
-     │  trivial       │       │                   │
-     └───────┬────────┘       └────────┬──────────┘
-             ▼                         ▼
-     Inline directo           ┌────┴────┐
-                              ▼         ▼
-                        OpenSpec    Directo
-                           │           │
-                           ▼           ▼
-                     ┌──────────┐  Inline directo
-                     │ Planning │  (sin skill)
-                     └────┬─────┘
-                          ▼
-                    ┌──────────────┐
-                    │  Nivel 1+    │
-                    │  (OpenSpec)  │
-                    └──────┬───────┘
-                           ▼
-              ┌────────────────────────┐
-              │ 4. EXECUTION           │
-              │                        │
-              │ ┌── 1. Cargar SKILL ──┐│
-              │ │   Skill tool ->     ││ <- FORZOSO
-              │ │   execution-mode-   ││
-              │ │   evaluation        ││
-              │ └─────────────────────┘│
-              │ ┌  NO CONTINUAR       ┐│
-              │ │  SIN OUTPUT JSON    ││
-              │ └─────────────────────┘│
-              │                        │
-              │ 2. Elegir modo segun   │
-              │    output del skill    │
-              │                        │
-              │ 3. Ejecutar            │
-              └────────────────────────┘
-```
-
----
-
-## Flujo completo del skill
-
-Los pasos que ejecuta el skill una vez cargado:
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│                   1. GATILLO                                 │
-│                                                              │
-│  Agent definition (ostacky.md) dice:                         │
-│  "Cargar AHORA el skill execution-mode-evaluation"           │
-│  "No continuar sin el output JSON"                           │
-│                                                              │
-│  → Se invoca el Skill tool → se carga este SKILL.md         │
-└──────────────────────────┬───────────────────────────────────┘
-                           ▼
-┌──────────────────────────────────────────────────────────────┐
-│                   2. PASO 0 — CHECK DE DATOS                 │
-│                                                              │
-│  ¿Ya hay codegraph_context en el contexto de la sesión?      │
-│  ├── SÍ y tiene los archivos por task → saltar Paso 1       │
-│  └── NO o incompleto → continuar a Paso 1                   │
-└──────────────────────────┬───────────────────────────────────┘
-                           ▼
-┌──────────────────────────────────────────────────────────────┐
-│                   3. PASO 1 — CODEGRAPH (si necesario)       │
-│                                                              │
-│  Ejecutar codegraph_context sobre el área del cambio         │
-│  Buscar: archivos, símbolos, relaciones                     │
-│                                                              │
-│  Si hace falta más precisión: codegraph_impact               │
-│                                                              │
-│  Si CodeGraph no disponible: fallback a inline con conf 0.3  │
-│                                                              │
-│  Output: datos de archivos y símbolos involucrados           │
-└──────────────────────────┬───────────────────────────────────┘
-                           ▼
-┌──────────────────────────────────────────────────────────────┐
-│                   4. PASO 2 — MAPA DE DEPENDENCIAS           │
-│                                                              │
-│  Se construye con tasks.md + datos de CodeGraph:             │
-│                                                              │
-│  ┌─────────────────────────────────────────────────────┐     │
-│  │ taskCount:     cantidad total de tasks               │     │
-│  │ sharedFiles:   { archivo → [tasks que lo modifican] }│     │
-│  │ fileClusters:  [ [taskA,taskB], [taskC], ... ]       │     │
-│  │ clusterCount:  cantidad de clusters                  │     │
-│  │ sequentialDeps: [taskA → taskB]                      │     │
-│  │ filesPerTask:  { task → [archivos] }                 │     │
-│  │ estLines:      líneas estimadas de cambio            │     │
-│  │ hasExplicitContract: diseño explícita contratos?     │     │
-│  └─────────────────────────────────────────────────────┘     │
-└──────────────────────────┬───────────────────────────────────┘
-                           ▼
-┌──────────────────────────────────────────────────────────────┐
-│                   5. PASO 3a — MODO GLOBAL                   │
-│                                                              │
-│  PRIMERO: CONSTRUIR CLUSTERS (componentes conectados)        │
-│  - sharedFiles agrupa tareas que modifican los mismos archs  │
-│  - Cierre transitivo: A comparte archivo con B, B con C     │
-│    → A, B, C están en el mismo cluster                      │
-│  - clusterCount: cantidad total de clusters                 │
-│                                                              │
-│  LUEGO: evaluar en orden:                                    │
-│                                                              │
-│  1. clusterCount==1 y tamaño>1?                    → INLINE  │
-│     (todo comparte archivos, no se puede paralelizar)        │
-│                                                              │
-│  2. clusterCount>=2, clusters con tamaño>1?                  │
-│     a. ¿deps ENTRE clusters sin contrato?         → INLINE   │
-│     b. ¿NO? → SUBAGENT-DRIVEN (cada cluster=1 subagente)     │
-│                                                              │
-│  3. Sin archivos compartidos (clusterCount==taskCount):      │
-│     a. ¿taskCount < 3?                            → INLINE   │
-│     b. ¿estLines < 30?                            → INLINE   │
-│     c. ¿ninguna? → SUBAGENT-DRIVEN (cada task=1 subagente)   │
-│                                                              │
-│  Si el usuario dio instrucciones explícitas:                 │
-│  → anulan todas las reglas, todas las fases heredan el modo  │
-└──────────────────────────┬───────────────────────────────────┘
-                           ▼
-┌──────────────────────────────────────────────────────────────┐
-│            6. PASO 3b — EVALUACIÓN POR FASES                 │
-│            (solo si el modo global es INLINE)                │
-│                                                              │
-│  Si el modo global es SUBAGENT-DRIVEN (Rule 2b o 3c)        │
-│  → saltar este paso (ya hay granularidad por cluster/task)  │
-│                                                              │
-│  Por cada fase en tasks.md:                                  │
-│                                                              │
-│  ┌─────────────────────────────────────────────────────┐     │
-│  │ a. ¿sharedFiles DENTRO de la fase?      → INLINE     │     │
-│  │ b. ¿sharedFiles con fases INLINE?       → INLINE     │     │
-│  │ c. ¿sequentialDeps sin contrato?        → INLINE     │     │
-│  │ d. ¿taskCount < 4?                      → INLINE     │     │
-│  │ e. ¿estLines < 30?                      → INLINE     │     │
-│  │ f. Ninguna de las anteriores → SUBAGENT-DRIVEN       │     │
-│  └─────────────────────────────────────────────────────┘     │
-│                                                              │
-│  Output: un modo por fase (no modifica el modo global)       │
-└──────────────────────────┬───────────────────────────────────┘
-                           ▼
-┌──────────────────────────────────────────────────────────────┐
-│                   7. PASO 4 — OUTPUT JSON                    │
-│                                                              │
-│  {                                                           │
-│    "mode": "inline" | "subagent-driven",                     │
-│    "confidence": 0.95,                                       │
-│    "reasons": ["..."],                                       │
-│    "codegraphUsed": ["codegraph_context"],                    │
-│    "globalRuleTriggered": "2b",                              │
-│    "taskAnalysis": {                                         │
-│      "taskCount": 5,                                         │
-│      "sharedFiles": {...},                                   │
-│      "fileClusters": [["t1","t2"], ["t3","t4"], ["t5"]],     │
-│      "clusterCount": 3,                                      │
-│      "sequentialDeps": [],                                   │
-│      "estLines": 85,                                         │
-│      "hasExplicitContract": false                            │
-│    },                                                        │
-│    "phaseRecommendations": [...]                              │
-│  }                                                           │
-└──────────────────────────┬───────────────────────────────────┘
-                           ▼
-┌──────────────────────────────────────────────────────────────┐
-│                   8. POST-DECISIÓN                           │
-│                                                              │
-│  Agent definition usa el output:                             │
-│                                                              │
-│  - mode "inline" → el agente ejecuta todo en su sesión       │
-│  - mode "subagent-driven" (Rule 3c) → subagent-driven-dev   │
-│  - mode "subagent-driven" (Rule 2b) → cluster dispatch:      │
-│    cada cluster se asigna a un subagente                     │
-│  - phaseRecommendations: inline PRIMERO, subagent DESPUÉS    │
-│                                                              │
-│  Orden de fases:                                             │
-│    1º Fases inline (establecen contratos)                    │
-│    2º Fases subagent-driven (consumen contratos)             │
-│    3º Cluster dispatch → subagentes en paralelo              │
-└──────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Reglas que gobiernan la decisión
-
-### Modo global (Paso 3a) — basado en clusters
-
-| Regla | Condición | Decisión | Detalle |
-|-------|-----------|----------|---------|
-| 1 | clusterCount == 1 Y tamaño > 1 | **INLINE** | Todo conectado por archivos compartidos. Imposible paralelizar. |
-| 2a | clusterCount >= 2, hay clusters con tamaño > 1, deps ENTRE clusters SIN contrato | **INLINE** | Clusters independientes pero relacionados sin contrato explícito. |
-| 2b | clusterCount >= 2, hay clusters con tamaño > 1, SIN deps entre clusters (O contrato existe) | **SUBAGENT-DRIVEN** | Clusters independientes. Cada cluster = 1 subagente. Tasks intra-cluster secuenciales. |
-| 3a | Sin archivos compartidos (clusterCount == taskCount), taskCount < 3 | **INLINE** | Muy pocas tasks para amortizar subagentes. |
-| 3b | Sin archivos compartidos, estLines < 30 | **INLINE** | Cambio pequeño, inline más eficiente. |
-| 3c | Sin archivos compartidos, ninguna condición anterior | **SUBAGENT-DRIVEN** | Tasks independientes. Cada task = 1 subagente. |
-
-### Modo por fase (Paso 3b)
-
-| Regla | Condición | Decisión |
-|-------|-----------|----------|
-| a | Archivos compartidos dentro de la fase | INLINE |
-| b | Comparte archivos con fases inline | INLINE |
-| c | Dependencias secuenciales sin contrato | INLINE |
-| d | Menos de 4 tasks en la fase | INLINE |
-| e | Menos de 30 líneas en la fase | INLINE |
-| f | Ninguna condición anterior | SUBAGENT-DRIVEN |
-
-### Excepciones
-
-- **Instrucción del usuario** anula todo el skill — si el usuario dice "hacé todo inline" o "usá subagentes", eso tiene prioridad absoluta.
-- **CodeGraph no disponible** — fallback a inline con confianza baja, no bloquear.
-
----
-
-## Orden de ejecución recomendado
-
-### Si el modo global es "inline" (con phaseRecommendations):
-1. **Primero** fases con `mode: "inline"` — establecen interfaces, tipos y módulos
-2. **Después** fases con `mode: "subagent-driven"` — consumen lo establecido
-3. Si hay dependencias entre fases subagent-driven, respetar el orden de `tasks.md`
-
-### Si el modo global es "subagent-driven" por clusters (Rule 2b):
-1. Cada cluster del `fileClusters` se asigna a un subagente
-2. Los subagentes se ejecutan en **paralelo** (los clusters no comparten archivos)
-3. Tasks dentro del mismo cluster se ejecutan **secuencialmente** dentro del subagente
-4. Si hay dependencias ENTRE clusters, deben ejecutarse en orden respetando la dependencia
-
----
-
-## Limitaciones
-
-- El skill depende de CodeGraph para los datos. Si CodeGraph no está disponible, decide inline por defecto.
-- Si `tasks.md` no está organizado en fases, `phaseRecommendations` será un array vacío.
-- El clustering asume que dos tasks que modifican el mismo archivo SIEMPRE van a conflictuar si se ejecutan en paralelo. Esto es conservador pero correcto para subagentes independientes.
-- La decisión es point-in-time: si se agregan tasks a mitad de cambio, re-ejecutar el skill.

package/assets/tests/agent-contract.test.js

@@ -1,227 +0,0 @@
-import { describe, it } from 'node:test';
-import assert from 'node:assert/strict';
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const ASSETS_DIR = join(__dirname, '..');
-const AGENT_FILE = join(ASSETS_DIR, 'agents', 'ostacky.md');
-const CONTROLLER_FILE = join(ASSETS_DIR, 'mcp', 'ostacky-controller', 'index.js');
-
-const agentContent = readFileSync(AGENT_FILE, 'utf8');
-const controllerContent = readFileSync(CONTROLLER_FILE, 'utf8');
-
-// Tools registered in the MCP controller
-const MCP_TOOLS = [
-    'start_request', 'request_clarification', 'record_clarification',
-    'record_discovery', 'consume_route_decision', 'spec_complete',
-    'record_execution_analysis', 'consume_execution_decision',
-    'implementation_complete', 'sync_complete', 'block', 'replan',
-    'get_state', 'get_tasks', 'validate_edit', 'complete_task',
-];
-
-// CodeGraph tools referenced in agent instructions
-const CODEGRAPH_TOOLS = [
-    'codegraph_explore', 'codegraph_node', 'codegraph_search',
-    'codegraph_callers', 'codegraph_callees', 'codegraph_impact',
-    'codegraph_files', 'codegraph_status',
-];
-
-// Native OpenCode tools
-const NATIVE_TOOLS = ['question', 'Read', 'Edit', 'Bash', 'Grep', 'Glob'];
-
-const ALL_VALID_TOOLS = [...MCP_TOOLS, ...CODEGRAPH_TOOLS, ...NATIVE_TOOLS];
-
-describe('Agent contract — ostacky.md', () => {
-    describe('Core Instructions section', () => {
-        it('has "Core Instructions" heading', () => {
-            assert.ok(agentContent.includes('## Core Instructions'),
-                'Missing "## Core Instructions" section');
-        });
-
-        it('has SINGLE SOURCE OF VERDAD marker', () => {
-            assert.ok(agentContent.includes('SINGLE SOURCE OF VERDAD'),
-                'Missing "SINGLE SOURCE OF VERDAD" marker');
-        });
-    });
-
-    describe('CodeGraph section', () => {
-        it('has CodeGraph — búsqueda de código subsection', () => {
-            assert.ok(agentContent.includes('### CodeGraph — búsqueda de código'),
-                'Missing "### CodeGraph — búsqueda de código" section');
-        });
-
-        it('has tool table with codegraph_explore', () => {
-            assert.ok(agentContent.includes('codegraph_explore'),
-                'Missing codegraph_explore in tool table');
-        });
-    });
-
-    describe('Engram section', () => {
-        it('has Engram — memoria persistente subsection', () => {
-            assert.ok(agentContent.includes('### Engram — memoria persistente'),
-                'Missing "### Engram — memoria persistente" section');
-        });
-
-        it('has engram_mem_context in Discovery flow', () => {
-            assert.ok(agentContent.includes('engram_mem_context'),
-                'Missing engram_mem_context — agent should consult memory at start of request');
-        });
-
-        it('has engram_mem_search reference', () => {
-            assert.ok(agentContent.includes('engram_mem_search'),
-                'Missing engram_mem_search — agent should search before deciding');
-        });
-
-        it('has engram_mem_save reference', () => {
-            assert.ok(agentContent.includes('engram_mem_save'),
-                'Missing engram_mem_save — agent should save after significant work');
-        });
-    });
-
-    describe('HARD-STOP rules', () => {
-        it('has at least 2 HARD-STOP blocks (HTML tags or inline markers)', () => {
-            const htmlBlocks = (agentContent.match(/<HARD-STOP>/g) || []).length;
-            const inlineMarkers = (agentContent.match(/\*\*HARD-STOP\*\*/g) || []).length;
-            const total = htmlBlocks + inlineMarkers;
-            assert.ok(total >= 2,
-                `Expected at least 2 HARD-STOP blocks (HTML or inline), found ${total} (${htmlBlocks} HTML, ${inlineMarkers} inline)`);
-        });
-
-        it('has closing HARD-STOP tags matching opening tags', () => {
-            const opens = (agentContent.match(/<HARD-STOP>/g) || []).length;
-            const closes = (agentContent.match(/<\/HARD-STOP>/g) || []).length;
-            assert.equal(opens, closes,
-                `Mismatched HARD-STOP tags: ${opens} opens, ${closes} closes`);
-        });
-
-        it('has HARD-STOP in Regla de oro (global question stop)', () => {
-            const reglaDeOro = agentContent.substring(
-                agentContent.indexOf('## Regla de oro'),
-                agentContent.indexOf('## Flujo')
-            );
-            assert.ok(reglaDeOro.includes('<HARD-STOP>'),
-                'Missing HARD-STOP in Regla de Oro section — agent can continue after questions');
-        });
-    });
-
-    describe('Tool name references — no stale names', () => {
-        it('does NOT reference "ask_user" (non-existent tool)', () => {
-            const refs = agentContent.match(/ask_user/g);
-            const count = refs ? refs.length : 0;
-            assert.equal(count, 0,
-                `Found ${count} reference(s) to "ask_user" — this tool does not exist. Use "question" instead.`);
-        });
-
-        it('does NOT reference "codegraph_context" (stale name)', () => {
-            // Allow it in comments or descriptions, but not as an active tool call
-            const lines = agentContent.split('\n');
-            const offenders = lines.filter(line =>
-                line.includes('codegraph_context') &&
-                !line.startsWith('|') &&
-                !line.includes('NUNCA') &&
-                !line.includes('Prohibido')
-            );
-            assert.equal(offenders.length, 0,
-                `Found stale "codegraph_context" references (use codegraph_explore): ${offenders.join('; ')}`);
-        });
-
-        it('references valid MCP tools in flow instructions', () => {
-            // Extract tool names used in flow steps (lines with backtick-quoted tool names)
-            const toolRefs = agentContent.match(/`([a-z_]+)`/g) || [];
-            const uniqueTools = [...new Set(toolRefs.map(t => t.replace(/`/g, '')))];
-
-            const flowTools = uniqueTools.filter(t =>
-                t.includes('request') || t.includes('record') || t.includes('consume') ||
-                t.includes('spec_') || t.includes('implementation') || t.includes('sync') ||
-                t.includes('validate') || t.includes('complete') || t.includes('block') ||
-                t.includes('replan') || t.includes('start_') || t.includes('get_')
-            );
-
-            const invalidTools = flowTools.filter(t => !MCP_TOOLS.includes(t));
-            assert.equal(invalidTools.length, 0,
-                `References non-existent MCP tools: ${invalidTools.join(', ')}`);
-        });
-    });
-
-    describe('validate_edit instructions', () => {
-        it('mentions content as required parameter', () => {
-            assert.ok(
-                agentContent.includes('content') &&
-                (agentContent.includes('content es OBLIGATORIO') ||
-                 agentContent.includes('`content` es OBLIGATORIO')),
-                'Missing explicit instruction that content is required for validate_edit'
-            );
-        });
-
-        it('instructs to Read file before validate_edit', () => {
-            const executionSection = agentContent.substring(
-                agentContent.indexOf('### 4. Execution'),
-                agentContent.indexOf('### 5. Sync')
-            );
-            assert.ok(executionSection.includes('Read'),
-                'Execution section should instruct to Read file before validate_edit');
-        });
-    });
-
-    describe('Classification rules', () => {
-        it('has Nivel 0, 0+1, and 1+', () => {
-            assert.ok(agentContent.includes('Nivel 0'), 'Missing Nivel 0');
-            assert.ok(agentContent.includes('Nivel 0+1'), 'Missing Nivel 0+1');
-            assert.ok(agentContent.includes('Nivel 1+'), 'Missing Nivel 1+');
-        });
-
-        it('has defaultChoice mapping', () => {
-            assert.ok(agentContent.includes('defaultChoice'), 'Missing defaultChoice mapping');
-            assert.ok(agentContent.includes('"DIRECT"'), 'Missing DIRECT default');
-            assert.ok(agentContent.includes('"SPEC"'), 'Missing SPEC default');
-        });
-    });
-
-    describe('Guardrails', () => {
-        it('has Eficiencia de tokens section', () => {
-            assert.ok(agentContent.includes('### Eficiencia de tokens'),
-                'Missing "### Eficiencia de tokens" guardrail section');
-        });
-
-        it('has Decisiones y estado section', () => {
-            assert.ok(agentContent.includes('### Decisiones y estado'),
-                'Missing "### Decisiones y estado" guardrail section');
-        });
-    });
-});
-
-describe('Controller contract — index.js', () => {
-    it('exports OstackyController', () => {
-        assert.ok(controllerContent.includes('export { OstackyController }'),
-            'Missing OstackyController export');
-    });
-
-    it('has validate_edit tool registered', () => {
-        assert.ok(controllerContent.includes("server.registerTool(\n    'validate_edit'") ||
-                  controllerContent.includes("server.registerTool('validate_edit'"),
-            'validate_edit not registered as MCP tool');
-    });
-
-    it('validate_edit schema has content as required (z.string())', () => {
-        // Find the validate_edit schema section
-        const validateSection = controllerContent.substring(
-            controllerContent.indexOf("'validate_edit'"),
-            controllerContent.indexOf("'complete_task'")
-        );
-        assert.ok(validateSection.includes('content: z.string()') &&
-                  !validateSection.includes('content: z.string().optional()'),
-            'validate_edit content param should be z.string() required — prevents silent state corruption');
-    });
-
-    it('validate_edit handler validates content type', () => {
-        const validateSection = controllerContent.substring(
-            controllerContent.indexOf("'validate_edit'"),
-            controllerContent.indexOf("'complete_task'")
-        );
-        assert.ok(validateSection.includes("typeof content !== 'string'"),
-            'validate_edit handler should check typeof content');
-    });
-});