trackops 2.0.3 → 2.0.5

package/templates/opera/references/opera-cycle.md

@@ -1,193 +1,193 @@
-# El Ciclo O.P.E.R.A. — Referencia Completa
-
-Este documento detalla cada fase del ciclo con sus reglas, procedimientos y Definitions of Done.
-
----
-
-## 1️⃣ O — Orquestar (Visión y Lógica)
-
-### Descubrimiento
-
-Haz al usuario las 5 preguntas clave:
-
-1. **Directriz Principal**: ¿Cuál es el resultado singular deseado?
-2. **Integraciones**: ¿Qué servicios externos necesitamos? ¿Están listas las claves?
-3. **Fuente de la Verdad**: ¿Dónde viven los datos primarios?
-4. **Carga Útil (Payload)**: ¿Cómo y dónde debe entregarse el resultado final?
-5. **Reglas de Comportamiento**: Restricciones o tono específico.
-
-### Regla "Datos-Primero"
-
-Antes de pasar a la siguiente fase, DEBES definir el **Esquema de Datos JSON** (Input/Output) en `genesis.md`.
-
-Ejemplo de schema en genesis.md:
-
-```json
-{
-  "input": {
-    "source": "API externa",
-    "schema": {
-      "id": "string (UUID)",
-      "timestamp": "ISO 8601",
-      "data": "object"
-    }
-  },
-  "output": {
-    "destination": "webhook POST",
-    "schema": {
-      "processed_id": "string (UUID)",
-      "result": "object",
-      "status": "enum: success|error"
-    }
-  }
-}
-```
-
-### Definition of Done — Fase O
-
-- [ ] Las 5 preguntas de descubrimiento están respondidas.
-- [ ] Esquema JSON de Input/Output definido en `genesis.md`.
-- [ ] Reglas de comportamiento documentadas en `genesis.md`.
-- [ ] `task_plan.md` tiene plano aprobado por el usuario.
-
----
-
-## 2️⃣ P — Probar (Conectividad)
-
-Verifica las tuberías antes de pasar el agua. El objetivo es confirmar que todos los servicios externos responden y devuelven datos con la forma esperada.
-
-### Procedimiento
-
-1. **Verificación de credenciales**: Lee `.env` y confirma que todas las claves necesarias existen y no están vacías.
-2. **Handshake**: Construye scripts mínimos en `tools/` (ej: `test_api.py`) para verificar cada servicio.
-3. **Validación de Shape**: No basta con un HTTP 200. Verifica que la respuesta coincide con el schema definido en `genesis.md`. Compara campos, tipos de datos y estructura.
-4. **Bloqueo**: Si algún test falla, NO procedas a la fase de Estructurar. Documenta el fallo en `findings.md`.
-
-### Ejemplo de test mínimo
-
-```python
-# tools/test_api.py
-import os
-import requests
-
-API_KEY = os.getenv("API_KEY")
-BASE_URL = os.getenv("API_BASE_URL")
-
-def test_connection():
-    """Verifica conexión y shape de respuesta."""
-    response = requests.get(f"{BASE_URL}/health", headers={"Authorization": f"Bearer {API_KEY}"})
-    assert response.status_code == 200, f"Expected 200, got {response.status_code}"
-    data = response.json()
-    assert "id" in data, "Missing 'id' field in response"
-    assert "status" in data, "Missing 'status' field in response"
-    print("✅ API connection and shape validated")
-
-if __name__ == "__main__":
-    test_connection()
-```
-
-### Definition of Done — Fase P
-
-- [ ] Todas las credenciales `.env` verificadas (existen y no están vacías).
-- [ ] Scripts `test_*.py` ejecutados y pasando.
-- [ ] Respuestas de APIs validadas contra el schema de `genesis.md`.
-- [ ] Resultados documentados en `findings.md`.
-
----
-
-## 3️⃣ E — Estructurar (La Construcción de 3 Capas)
-
-### Capa 1: Arquitectura (`architecture/`)
-
-SOPs (Standard Operating Procedures) técnicos en Markdown. Cada SOP define:
-
-- Propósito del script.
-- Entradas esperadas (con referencia al schema en `genesis.md`).
-- Salidas producidas.
-- Casos extremos y cómo manejarlos.
-- Dependencias con otras herramientas.
-
-**Regla**: Si la lógica cambia, actualiza el SOP **antes** que el código.
-
-### Capa 2: Navegación (El Agente)
-
-Capa de razonamiento. Enruta datos entre SOPs y herramientas. No ejecuta lógica de negocio directamente; delega a los scripts.
-
-### Capa 3: Herramientas (`tools/`)
-
-- Scripts atómicos y deterministas.
-- Las variables de entorno van en `.env`.
-- Usa `.tmp/` para todas las operaciones intermedias.
-- Cada script hace UNA cosa bien.
-
-### Regla de Idempotencia
-
-Toda herramienta DEBE ser idempotente. Herramientas con side-effects irreversibles se marcan:
-
-```python
-# META: side-effect: true
-# META: idempotent: false
-# META: requires-confirmation: true
-```
-
-### Grafo de Dependencias
-
-Si una herramienta produce output que consume otra, documéntalo en `genesis.md` bajo `## Pipeline`:
-
-```markdown
-## Pipeline
-### tool_fetch.py → tool_transform.py
-- Output: `.tmp/raw_data.json`
-- Formato: JSON array según schema X
-```
-
-### Definition of Done — Fase E
-
-- [ ] SOPs escritos en `architecture/` para cada herramienta.
-- [ ] Scripts implementados en `tools/`.
-- [ ] Grafo de dependencias documentado en `genesis.md`.
-- [ ] Tests de integración entre herramientas pasando.
-- [ ] Herramientas con side-effects marcadas con META tags.
-
----
-
-## 4️⃣ R — Refinar (Refinamiento)
-
-### Templates de Output
-
-Toda salida del sistema se valida contra una plantilla definida en `templates/`. Las plantillas se referencian desde `genesis.md` bajo `## Templates`.
-
-El refinamiento no es subjetivo; es verificable contra una plantilla. Si el output no coincide con el template, no pasa.
-
-### Refinamiento de Carga Útil
-
-Formatea todas las salidas (Markdown, HTML, JSON limpio) para entrega profesional según lo definido en `genesis.md`.
-
-### UX/UI
-
-Si el proyecto tiene interfaz, aplica diseños limpios e intuitivos según las especificaciones.
-
-### Definition of Done — Fase R
-
-- [ ] Todas las salidas validadas contra sus templates en `templates/`.
-- [ ] Formatos de entrega (Markdown, HTML, JSON) verificados.
-- [ ] Si hay interfaz: revisión visual completada.
-
----
-
-## 5️⃣ A — Automatizar (Despliegue)
-
-### Procedimiento
-
-1. **Limpieza**: Elimina residuos de `.tmp/`.
-2. **Transferencia**: Mueve la lógica finalizada a producción/nube.
-3. **Configuración**: Establece los disparadores (Cron, Webhooks).
-4. **Smoke Test**: Verificación mínima en el entorno de producción.
-
-### Definition of Done — Fase A
-
-- [ ] `.tmp/` limpio (sin archivos residuales).
-- [ ] Código desplegado en destino final.
-- [ ] Triggers configurados y verificados.
-- [ ] Smoke test en producción pasando.
-- [ ] `progress.md` actualizado con estado final.
+# El Ciclo O.P.E.R.A. — Referencia Completa
+
+Este documento detalla cada fase del ciclo con sus reglas, procedimientos y Definitions of Done.
+
+---
+
+## 1️⃣ O — Orquestar (Visión y Lógica)
+
+### Descubrimiento
+
+Haz al usuario las 5 preguntas clave:
+
+1. **Directriz Principal**: ¿Cuál es el resultado singular deseado?
+2. **Integraciones**: ¿Qué servicios externos necesitamos? ¿Están listas las claves?
+3. **Fuente de la Verdad**: ¿Dónde viven los datos primarios?
+4. **Carga Útil (Payload)**: ¿Cómo y dónde debe entregarse el resultado final?
+5. **Reglas de Comportamiento**: Restricciones o tono específico.
+
+### Regla "Datos-Primero"
+
+Antes de pasar a la siguiente fase, DEBES definir el **Esquema de Datos JSON** (Input/Output) en `genesis.md`.
+
+Ejemplo de schema en genesis.md:
+
+```json
+{
+  "input": {
+    "source": "API externa",
+    "schema": {
+      "id": "string (UUID)",
+      "timestamp": "ISO 8601",
+      "data": "object"
+    }
+  },
+  "output": {
+    "destination": "webhook POST",
+    "schema": {
+      "processed_id": "string (UUID)",
+      "result": "object",
+      "status": "enum: success|error"
+    }
+  }
+}
+```
+
+### Definition of Done — Fase O
+
+- [ ] Las 5 preguntas de descubrimiento están respondidas.
+- [ ] Esquema JSON de Input/Output definido en `genesis.md`.
+- [ ] Reglas de comportamiento documentadas en `genesis.md`.
+- [ ] `task_plan.md` tiene plano aprobado por el usuario.
+
+---
+
+## 2️⃣ P — Probar (Conectividad)
+
+Verifica las tuberías antes de pasar el agua. El objetivo es confirmar que todos los servicios externos responden y devuelven datos con la forma esperada.
+
+### Procedimiento
+
+1. **Verificación de credenciales**: Lee `.env` y confirma que todas las claves necesarias existen y no están vacías.
+2. **Handshake**: Construye scripts mínimos en `tools/` (ej: `test_api.py`) para verificar cada servicio.
+3. **Validación de Shape**: No basta con un HTTP 200. Verifica que la respuesta coincide con el schema definido en `genesis.md`. Compara campos, tipos de datos y estructura.
+4. **Bloqueo**: Si algún test falla, NO procedas a la fase de Estructurar. Documenta el fallo en `findings.md`.
+
+### Ejemplo de test mínimo
+
+```python
+# tools/test_api.py
+import os
+import requests
+
+API_KEY = os.getenv("API_KEY")
+BASE_URL = os.getenv("API_BASE_URL")
+
+def test_connection():
+    """Verifica conexión y shape de respuesta."""
+    response = requests.get(f"{BASE_URL}/health", headers={"Authorization": f"Bearer {API_KEY}"})
+    assert response.status_code == 200, f"Expected 200, got {response.status_code}"
+    data = response.json()
+    assert "id" in data, "Missing 'id' field in response"
+    assert "status" in data, "Missing 'status' field in response"
+    print("✅ API connection and shape validated")
+
+if __name__ == "__main__":
+    test_connection()
+```
+
+### Definition of Done — Fase P
+
+- [ ] Todas las credenciales `.env` verificadas (existen y no están vacías).
+- [ ] Scripts `test_*.py` ejecutados y pasando.
+- [ ] Respuestas de APIs validadas contra el schema de `genesis.md`.
+- [ ] Resultados documentados en `findings.md`.
+
+---
+
+## 3️⃣ E — Estructurar (La Construcción de 3 Capas)
+
+### Capa 1: Arquitectura (`architecture/`)
+
+SOPs (Standard Operating Procedures) técnicos en Markdown. Cada SOP define:
+
+- Propósito del script.
+- Entradas esperadas (con referencia al schema en `genesis.md`).
+- Salidas producidas.
+- Casos extremos y cómo manejarlos.
+- Dependencias con otras herramientas.
+
+**Regla**: Si la lógica cambia, actualiza el SOP **antes** que el código.
+
+### Capa 2: Navegación (El Agente)
+
+Capa de razonamiento. Enruta datos entre SOPs y herramientas. No ejecuta lógica de negocio directamente; delega a los scripts.
+
+### Capa 3: Herramientas (`tools/`)
+
+- Scripts atómicos y deterministas.
+- Las variables de entorno van en `.env`.
+- Usa `.tmp/` para todas las operaciones intermedias.
+- Cada script hace UNA cosa bien.
+
+### Regla de Idempotencia
+
+Toda herramienta DEBE ser idempotente. Herramientas con side-effects irreversibles se marcan:
+
+```python
+# META: side-effect: true
+# META: idempotent: false
+# META: requires-confirmation: true
+```
+
+### Grafo de Dependencias
+
+Si una herramienta produce output que consume otra, documéntalo en `genesis.md` bajo `## Pipeline`:
+
+```markdown
+## Pipeline
+### tool_fetch.py → tool_transform.py
+- Output: `.tmp/raw_data.json`
+- Formato: JSON array según schema X
+```
+
+### Definition of Done — Fase E
+
+- [ ] SOPs escritos en `architecture/` para cada herramienta.
+- [ ] Scripts implementados en `tools/`.
+- [ ] Grafo de dependencias documentado en `genesis.md`.
+- [ ] Tests de integración entre herramientas pasando.
+- [ ] Herramientas con side-effects marcadas con META tags.
+
+---
+
+## 4️⃣ R — Refinar (Refinamiento)
+
+### Templates de Output
+
+Toda salida del sistema se valida contra una plantilla definida en `templates/`. Las plantillas se referencian desde `genesis.md` bajo `## Templates`.
+
+El refinamiento no es subjetivo; es verificable contra una plantilla. Si el output no coincide con el template, no pasa.
+
+### Refinamiento de Carga Útil
+
+Formatea todas las salidas (Markdown, HTML, JSON limpio) para entrega profesional según lo definido en `genesis.md`.
+
+### UX/UI
+
+Si el proyecto tiene interfaz, aplica diseños limpios e intuitivos según las especificaciones.
+
+### Definition of Done — Fase R
+
+- [ ] Todas las salidas validadas contra sus templates en `templates/`.
+- [ ] Formatos de entrega (Markdown, HTML, JSON) verificados.
+- [ ] Si hay interfaz: revisión visual completada.
+
+---
+
+## 5️⃣ A — Automatizar (Despliegue)
+
+### Procedimiento
+
+1. **Limpieza**: Elimina residuos de `.tmp/`.
+2. **Transferencia**: Mueve la lógica finalizada a producción/nube.
+3. **Configuración**: Establece los disparadores (Cron, Webhooks).
+4. **Smoke Test**: Verificación mínima en el entorno de producción.
+
+### Definition of Done — Fase A
+
+- [ ] `.tmp/` limpio (sin archivos residuales).
+- [ ] Código desplegado en destino final.
+- [ ] Triggers configurados y verificados.
+- [ ] Smoke test en producción pasando.
+- [ ] `progress.md` actualizado con estado final.

package/templates/opera/registry.md

@@ -1,28 +1,28 @@
-# Skills Registry — {{PROJECT_NAME}}
-
-> Índice de skills instaladas en este proyecto. Gestionado automáticamente por `trackops skill`.
-
----
-
-## Skills Instaladas
-
-_Sin skills instaladas. Usa `trackops skill install <nombre>` para añadir una._
-
----
-
-## Cómo Usar una Skill
-
-1. Identifica el contexto en `.agent/hub/router.md`.
-2. Abre el archivo `SKILL.md` de la skill correspondiente.
-3. Sigue las instrucciones del protocolo definido en la skill.
-
----
-
-## Gestión
-
-```bash
-trackops skill list          # Ver skills instaladas
-trackops skill catalog       # Ver skills disponibles
-trackops skill install <n>   # Instalar una skill
-trackops skill remove <n>    # Desinstalar una skill
-```
+# Skills Registry — {{PROJECT_NAME}}
+
+> Índice de skills instaladas en este proyecto. Gestionado automáticamente por `trackops skill`.
+
+---
+
+## Skills Instaladas
+
+_Sin skills instaladas. Usa `trackops skill install <nombre>` para añadir una._
+
+---
+
+## Cómo Usar una Skill
+
+1. Identifica el contexto en `.agent/hub/router.md`.
+2. Abre el archivo `SKILL.md` de la skill correspondiente.
+3. Sigue las instrucciones del protocolo definido en la skill.
+
+---
+
+## Gestión
+
+```bash
+trackops skill list          # Ver skills instaladas
+trackops skill catalog       # Ver skills disponibles
+trackops skill install <n>   # Instalar una skill
+trackops skill remove <n>    # Desinstalar una skill
+```

package/templates/opera/reviews/delivery-audit.md

@@ -1,18 +1,18 @@
-# Delivery Audit
-
-## Scope
-
-Review the final output shape against the active templates and compiled contract.
-
-## Checklist
-
-- `ops/genesis.md` matches the current contract.
-- `ops/task_plan.md`, `ops/progress.md` and `ops/findings.md` are synchronized.
-- Public copy matches runtime behavior.
-- API and dashboard reflect the same operational state.
-- Visual review completed when a UI change exists.
-
-## Result
-
-- Status: pending review
-- Notes: replace this section with project-specific evidence.
+# Delivery Audit
+
+## Scope
+
+Review the final output shape against the active templates and compiled contract.
+
+## Checklist
+
+- `ops/genesis.md` matches the current contract.
+- `ops/task_plan.md`, `ops/progress.md` and `ops/findings.md` are synchronized.
+- Public copy matches runtime behavior.
+- API and dashboard reflect the same operational state.
+- Visual review completed when a UI change exists.
+
+## Result
+
+- Status: pending review
+- Notes: replace this section with project-specific evidence.

package/templates/opera/reviews/integration-audit.md

@@ -1,18 +1,18 @@
-# Integration Audit
-
-## Scope
-
-Review credentials, connectivity assumptions and external response shapes before expanding delivery.
-
-## Checklist
-
-- Required keys identified from the contract and environment contract.
-- Missing keys documented without exposing secret values.
-- External services listed in the contract.
-- Response shapes aligned with `ops/contract/operating-contract.json`.
-- Findings recorded in `ops/findings.md` when applicable.
-
-## Result
-
-- Status: pending review
-- Notes: replace this section with project-specific evidence.
+# Integration Audit
+
+## Scope
+
+Review credentials, connectivity assumptions and external response shapes before expanding delivery.
+
+## Checklist
+
+- Required keys identified from the contract and environment contract.
+- Missing keys documented without exposing secret values.
+- External services listed in the contract.
+- Response shapes aligned with `ops/contract/operating-contract.json`.
+- Findings recorded in `ops/findings.md` when applicable.
+
+## Result
+
+- Status: pending review
+- Notes: replace this section with project-specific evidence.

package/templates/opera/router.md

@@ -1,49 +1,54 @@
-# Router de Skills
-
-## Propósito
-Este archivo define las reglas de enrutamiento entre el agente principal y las skills disponibles. Cuando el agente detecta un contexto específico, consulta estas reglas para decidir qué skill invocar.
-
-## Reglas de Enrutamiento
-
-### Contexto: Commit de código
-- **Trigger**: El usuario pide hacer un commit o se completa un cambio de código.
-- **Skill**: `commiter`
-- **Acción**: Consulta la skill para formatear el mensaje de commit.
-
-### Contexto: Post-commit
-- **Trigger**: Se acaba de realizar un commit exitoso.
-- **Skill**: `changelog-updater`
-- **Acción**: Ejecuta el script de actualización del changelog.
-
-### Contexto: Arranque asistido del proyecto
-- **Trigger**: El usuario tiene una idea, una especificación parcial o TrackOps ha generado `ops/bootstrap/agent-handoff.md`.
-- **Skill**: `project-starter-skill`
-- **Acción**: Convertir el contexto del usuario en `ops/bootstrap/intake.json`, `ops/bootstrap/spec-dossier.md` y `ops/bootstrap/open-questions.md` cuando haga falta.
-
-### Contexto: Auditoria del contrato
-- **Trigger**: Existe `ops/contract/operating-contract.json` o `ops/bootstrap/quality-report.json` y hay dudas sobre huecos o contradicciones.
-- **Skill**: `opera-contract-auditor`
-- **Acción**: Auditar consistencia, huecos y pseudoprecision antes de seguir ejecutando.
-
-### Contexto: Riesgo operativo
-- **Trigger**: La accion afecta datos persistentes, despliegues, efectos externos o permisos sensibles.
-- **Skill**: `opera-policy-guard`
-- **Acción**: Consultar `ops/policy/autonomy.json` y decidir si hace falta aprobacion explicita.
-
-### Contexto: Seguimiento operativo
-- **Trigger**: Se va a empezar, retomar o cerrar un bloque de trabajo.
-- **Skill**: No aplica skill externa.
-- **Acción**: Ejecutar `trackops status`, tomar la siguiente tarea con `trackops next`, usar `ops/contract/operating-contract.json` como contrato de maquina y mantener `ops/project_control.json` como fuente de verdad operativa del backlog.
-
-## Cómo Añadir Nuevas Reglas
-
-Cada regla sigue este formato:
-
-```markdown
-### Contexto: [descripción]
-- **Trigger**: [qué activa la regla]
-- **Skill**: [nombre de la skill]
-- **Acción**: [qué debe hacer el agente]
-```
-
-Al instalar una nueva skill con `trackops skill install <nombre>`, añade su regla de enrutamiento aquí.
+# Router de Skills
+
+## Propósito
+Este archivo define las reglas de enrutamiento entre el agente principal y las skills disponibles. Cuando el agente detecta un contexto específico, consulta estas reglas para decidir qué skill invocar.
+
+## Reglas de Enrutamiento
+
+### Contexto: Coordinacion operativa de OPERA
+- **Trigger**: El proyecto tiene OPERA instalado y el usuario pregunta que hacer ahora, en que fase esta, si puede avanzar, que comando usar o si debe delegar.
+- **Skill**: `opera-skill`
+- **Accion**: Consultarla primero para decidir fase, estado, bloqueo, comandos y skills delegables. Si `opera-skill` esta instalada, tratar como coordinadora por defecto antes de elegir otras skills.
+
+### Contexto: Commit de código
+- **Trigger**: El usuario pide hacer un commit o se completa un cambio de código.
+- **Skill**: `commiter`
+- **Acción**: Consulta la skill para formatear el mensaje de commit.
+
+### Contexto: Post-commit
+- **Trigger**: Se acaba de realizar un commit exitoso.
+- **Skill**: `changelog-updater`
+- **Acción**: Ejecuta el script de actualización del changelog.
+
+### Contexto: Arranque asistido del proyecto
+- **Trigger**: El usuario tiene una idea, una especificación parcial o TrackOps ha generado `ops/bootstrap/agent-handoff.md`.
+- **Skill**: `project-starter-skill`
+- **Acción**: Convertir el contexto del usuario en `ops/bootstrap/intake.json`, `ops/bootstrap/spec-dossier.md` y `ops/bootstrap/open-questions.md` cuando haga falta.
+
+### Contexto: Auditoria del contrato
+- **Trigger**: Existe `ops/contract/operating-contract.json` o `ops/bootstrap/quality-report.json` y hay dudas sobre huecos o contradicciones.
+- **Skill**: `opera-contract-auditor`
+- **Acción**: Auditar consistencia, huecos y pseudoprecision antes de seguir ejecutando.
+
+### Contexto: Riesgo operativo
+- **Trigger**: La accion afecta datos persistentes, despliegues, efectos externos o permisos sensibles.
+- **Skill**: `opera-policy-guard`
+- **Acción**: Consultar `ops/policy/autonomy.json` y decidir si hace falta aprobacion explicita.
+
+### Contexto: Seguimiento operativo
+- **Trigger**: Se va a empezar, retomar o cerrar un bloque de trabajo.
+- **Skill**: No aplica skill externa.
+- **Acción**: Ejecutar `trackops status`, tomar la siguiente tarea con `trackops next`, usar `ops/contract/operating-contract.json` como contrato de maquina y mantener `ops/project_control.json` como fuente de verdad operativa del backlog.
+
+## Cómo Añadir Nuevas Reglas
+
+Cada regla sigue este formato:
+
+```markdown
+### Contexto: [descripción]
+- **Trigger**: [qué activa la regla]
+- **Skill**: [nombre de la skill]
+- **Acción**: [qué debe hacer el agente]
+```
+
+Al instalar una nueva skill con `trackops skill install <nombre>`, añade su regla de enrutamiento aquí.