@ingeniomaps/cauce 0.1.0 → 0.3.0

package/teams/system/incident-review/team.json

@@ -0,0 +1,72 @@
+{
+  "schemaVersion": 1,
+  "slug": "incident-review",
+  "name": "Incident Review",
+  "purpose": "Entender un incidente ya contenido y convertirlo en aprendizaje verificable, sin buscar culpables ni cerrar con una causa cómoda.",
+  "outcome": "report",
+  "entryAgent": "site-reliability-engineer",
+  "facilitator": "engineering-manager",
+  "decisionOwners": {
+    "impact_and_scope": "site-reliability-engineer",
+    "technical_cause": "software-architect",
+    "customer_communication": "customer-support-specialist",
+    "security_assessment": "security-engineer"
+  },
+  "conditionalAgents": [
+    "database-administrator",
+    "devops-engineer",
+    "privacy-compliance-specialist",
+    "legal-counsel",
+    "qa-engineer",
+    "finops-engineer"
+  ],
+  "stages": [
+    {
+      "id": "scope",
+      "phase": "discovery",
+      "agent": "site-reliability-engineer",
+      "dependsOn": [],
+      "produces": ["timeline", "impact-and-blast-radius"],
+      "exitGate": "Qué falló, desde cuándo hasta cuándo, a quiénes afectó y cómo se detectó están establecidos con evidencia, no con recuerdos."
+    },
+    {
+      "id": "diagnose",
+      "phase": "discovery",
+      "agent": "software-architect",
+      "dependsOn": ["scope"],
+      "produces": ["contributing-factors", "why-it-was-not-caught"],
+      "exitGate": "Los factores que contribuyeron están sostenidos por evidencia y se distingue causa de síntoma; si la causa no se determinó, se dice y se explica qué haría falta."
+    },
+    {
+      "id": "exposure",
+      "phase": "discovery",
+      "agent": "security-engineer",
+      "dependsOn": ["scope"],
+      "produces": ["data-and-security-exposure"],
+      "exitGate": "Está determinado si hubo acceso, pérdida o exposición de datos, o queda explícito que no se pudo determinar y qué evidencia falta."
+    },
+    {
+      "id": "learn",
+      "phase": "discovery",
+      "agent": "engineering-manager",
+      "dependsOn": ["diagnose", "exposure"],
+      "produces": ["follow-ups", "detection-and-prevention-gaps"],
+      "exitGate": "Cada seguimiento es una acción concreta con dueño propuesto, y se distingue lo que evita la repetición de lo que sólo la detecta antes."
+    }
+  ],
+  "guardrails": [
+    "Cada agente conserva los límites y autorizaciones de su SKILL.md.",
+    "El incidente ya está contenido: este recorrido no opera producción ni ejecuta remediaciones.",
+    "No se atribuye responsabilidad a personas; se analizan condiciones, no culpables.",
+    "Una causa sin evidencia se declara como hipótesis, aunque cerrar el informe sea más cómodo.",
+    "Ninguna comunicación a clientes ni notificación regulatoria sale de este recorrido: se propone y la decide una persona.",
+    "Los seguimientos quedan en el INBOX sin promover; convertirlos en trabajo es una decisión humana."
+  ],
+  "completion": [
+    "La línea de tiempo está sostenida por registros, no por reconstrucción de memoria.",
+    "Se distingue lo que se sabe de lo que se supone, y las hipótesis están marcadas como tales.",
+    "La exposición de datos está determinada o declarada como indeterminada con su motivo.",
+    "Cada seguimiento indica si previene la repetición o sólo acelera la detección.",
+    "Las obligaciones de comunicación o notificación quedan registradas como acción humana."
+  ]
+}

package/teams/{product-development → system/product-development}/team.json

@@ -3,6 +3,7 @@
   "slug": "product-development",
   "name": "Product Development Team",
   "purpose": "Convertir un problema validado de usuario en una entrega segura, usable, operable y medible.",
+  "outcome": "epic",
   "entryAgent": "product-manager",
   "facilitator": "project-manager",
   "decisionOwners": {
@@ -28,65 +29,118 @@
   "stages": [
     {
       "id": "frame",
+      "phase": "discovery",
       "agent": "product-manager",
       "dependsOn": [],
-      "produces": ["opportunity-brief", "outcome-and-guardrails"],
+      "produces": [
+        "opportunity-brief",
+        "outcome-and-guardrails"
+      ],
       "exitGate": "Problema, usuario, outcome, baseline, límites y decisión requerida están explícitos."
     },
     {
       "id": "research",
+      "phase": "discovery",
       "agent": "user-researcher",
-      "dependsOn": ["frame"],
-      "produces": ["research-evidence", "needs-and-risks"],
+      "dependsOn": [
+        "frame"
+      ],
+      "produces": [
+        "research-evidence",
+        "needs-and-risks"
+      ],
       "exitGate": "La evidencia diferencia hallazgos, hipótesis y preguntas abiertas sin inventar consenso."
     },
     {
       "id": "shape",
+      "phase": "discovery",
       "agent": "ux-designer",
-      "dependsOn": ["research"],
-      "produces": ["journey-and-flows", "usability-risks"],
+      "dependsOn": [
+        "research"
+      ],
+      "produces": [
+        "journey-and-flows",
+        "usability-risks"
+      ],
       "exitGate": "El flujo cubre estados críticos, errores, accesibilidad, control y recuperación del usuario."
     },
     {
       "id": "architect",
+      "phase": "discovery",
       "agent": "software-architect",
-      "dependsOn": ["frame", "shape"],
-      "produces": ["architecture-decision", "interfaces-and-quality-attributes"],
+      "dependsOn": [
+        "frame",
+        "shape"
+      ],
+      "produces": [
+        "architecture-decision",
+        "interfaces-and-quality-attributes"
+      ],
       "exitGate": "Opciones y tradeoffs están documentados; interfaces, riesgos y reversibilidad son verificables."
     },
     {
       "id": "plan",
+      "phase": "discovery",
       "agent": "engineering-manager",
-      "dependsOn": ["architect"],
-      "produces": ["delivery-plan", "ownership-and-capacity"],
+      "dependsOn": [
+        "architect"
+      ],
+      "produces": [
+        "delivery-plan",
+        "ownership-and-capacity"
+      ],
       "exitGate": "Los equipos dueños validaron estimaciones, capacidad, dependencias y criterios de integración."
     },
     {
       "id": "build",
+      "phase": "delivery",
       "agent": "backend-engineer",
-      "dependsOn": ["plan"],
-      "produces": ["working-increment", "implementation-evidence"],
+      "dependsOn": [
+        "plan"
+      ],
+      "produces": [
+        "working-increment",
+        "implementation-evidence"
+      ],
       "exitGate": "El incremento mínimo funciona en entorno autorizado y conserva contratos, controles y pruebas."
     },
     {
       "id": "verify",
+      "phase": "delivery",
       "agent": "qa-engineer",
-      "dependsOn": ["build"],
-      "produces": ["quality-evidence", "residual-risk"],
+      "dependsOn": [
+        "build"
+      ],
+      "produces": [
+        "quality-evidence",
+        "residual-risk"
+      ],
       "exitGate": "Criterios, regresiones, riesgos y evidencia adversa están visibles; no quedan bloqueos ocultos."
     },
     {
       "id": "release",
+      "phase": "delivery",
       "agent": "release-manager",
-      "dependsOn": ["verify"],
-      "produces": ["release-readiness", "rollout-and-rollback"],
+      "dependsOn": [
+        "verify"
+      ],
+      "produces": [
+        "release-readiness",
+        "rollout-and-rollback"
+      ],
       "exitGate": "Owners autorizados aceptaron readiness, observabilidad, soporte, rollout, abort y rollback."
     },
     {
       "id": "learn",
+      "phase": "delivery",
       "agent": "data-analyst",
-      "dependsOn": ["release"],
-      "produces": ["outcome-review", "follow-up-recommendation"],
+      "dependsOn": [
+        "release"
+      ],
+      "produces": [
+        "outcome-review",
+        "follow-up-recommendation"
+      ],
       "exitGate": "Outcome y guardrails se comparan con baseline; se decide mantener, iterar, escalar o retirar."
     }
   ],

package/template/AGENTS.md

@@ -25,6 +25,50 @@ Por defecto, todo sistema externo se considera real y de solo lectura. Sin aprob
 
 Documentar excepciones concretas aquí. Un entorno de desarrollo o sandbox debe nombrarse explícitamente.
 
+## Cargos disponibles
+
+`agents/` es un catálogo de cargos reutilizables. Cada uno declara en su `SKILL.md` cuándo actuar, qué
+decide, qué no le corresponde y cuál es su entrega mínima; sus métodos viven en `references/`.
+
+Antes de resolver algo que cae claramente en un cargo —una decisión de producto, un diseño de
+arquitectura, una estrategia de pruebas—, adoptá ese contrato en vez de improvisar el criterio. Los
+límites del cargo no son sugerencias: un cargo que no puede decidir solo, no decide solo.
+
+En Claude y Antigravity los cargos aparecen como skills invocables por nombre. En Codex y Gemini no hay
+mecanismo nativo: leé directamente el `SKILL.md` del cargo. Los que trae
+Cauce están en `agents/roles/system/`; los propios del proyecto, en `agents/roles/`, donde un mismo
+slug reemplaza al del sistema.
+
+`teams/` compone varios cargos en etapas con gates de salida y un dueño por dominio de decisión;
+`node tools/ops.js team show <slug>` muestra el recorrido.
+
+## Qué se puede editar y qué no
+
+Todo directorio `system/` pertenece a Cauce y se reemplaza completo al actualizar. **Nunca editar nada
+dentro de `system/`**: el cambio se pierde en la siguiente actualización y, mientras tanto, ese archivo
+deja de recibir mejoras.
+
+Para cambiar algo del sistema hay dos operaciones, las dos junto a `system/`, nunca dentro:
+
+- **Anexar**: un archivo nuevo con nombre o ID propio. Convive con los del sistema.
+- **Reemplazar**: un archivo con el mismo nombre o ID que uno de `system/`. El del proyecto manda y
+  `check` lo reporta como override explícito en vez de fallar.
+
+Aplica a `planning/business-rules/`, `planning/adr/`, `planning/rules/`, `teams/` y `agents/`. El resto de
+`planning/` —roadmap, backlog, WIP, done, inbox y acciones humanas— es del proyecto y no se toca al
+actualizar.
+
+`automatization/hooks/` y `automatization/runners/` son runtime del toolkit y se reemplazan enteros. No
+tienen `system/` porque no hace falta: lo que un proyecto necesita ya funciona sin editarlos.
+
+- **Agregar un guard propio**: creá `automatization/hooks/guard-<nombre>.sh` y registralo en la
+  configuración de tu runner. Sobrevive a cada actualización, porque el toolkit no lo conoce.
+- **Desactivar un guard**: quitalo de esa configuración, que es del proyecto. El archivo sigue ahí.
+- **Cambiar un comportamiento**: agregá el tuyo, no edites el del toolkit.
+
+Un guard existente **no se edita**: `upgrade` detecta el cambio y se detiene antes de pisarlo, y con
+`--force` deja registrado qué descartó.
+
 ## Cómo leer el estado
 
 Antes de abrir un archivo de `planning/`, preguntarle al CLI: es determinista, no gasta contexto y no

package/template/Makefile

@@ -1,6 +1,6 @@
 .DEFAULT_GOAL := help
 
-.PHONY: help check tree context automation-check
+.PHONY: help check tree context upgrade automation-check
 .PHONY: require-agent agent-learn agent-propose agent-evaluate
 .PHONY: install-claude install-codex install-gemini install-antigravity
 .PHONY: doctor-claude doctor-codex doctor-gemini doctor-antigravity
@@ -18,6 +18,9 @@ tree: ## Muestra roadmap, backlog, WIP y Done
 context: ## Muestra el contexto mínimo de la tarea vigente
 	@node tools/ops.js context planning
 
+upgrade: ## Actualiza Cauce sin tocar lo del proyecto
+	@node tools/ops.js upgrade .
+
 automation-check: ## Comprueba hooks, workflows y adaptadores
 	@node tools/ops.js automation check .
 

package/template/README.md

@@ -12,7 +12,7 @@ node tools/ops.js team check product-development
 
 - `organization/`: contexto estable de producto y negocio.
 - `agents/roles/`: cargos de IA reutilizables; cada agente lee el contexto de `organization/`.
-- `agents/workflows/`, `agents/coordinators/` y `agents/specialists/`: categorías extensibles para otros tipos de agentes.
+- Cualquier otro directorio bajo `agents/` es un tipo válido: se reconoce al tener contenido.
 - `teams/`: composiciones de varios agentes y sus handoffs.
 - `planning/`: roadmap, cola aprobada, trabajo en vuelo, evidencia e historial.
 - `AGENTS.md`: límites de autonomía y acciones que requieren una persona.

package/template/planning/reports/README.md

@@ -0,0 +1,11 @@
+# Informes
+
+Salida de los recorridos de equipo cuyo `outcome` es `report`: revisiones de incidente, análisis
+posteriores y cualquier recorrido que registre lo aprendido en vez de proponer trabajo.
+
+Un archivo por informe, nombrado `<AAAA-MM-DD>-<slug>.md`. Son evidencia: se commitean y no se
+reescriben. Si una conclusión cambia, se agrega un informe nuevo que lo diga.
+
+Los seguimientos que salen de un informe van a la sección Lecciones de `../INBOX.md` sin promover, y
+las acciones que requieren una persona a `../HUMAN_ACTIONS.md`. Convertir un seguimiento en trabajo es
+una decisión humana.

package/template/planning/rules/README.md

@@ -1,7 +1,13 @@
 # Reglas transversales
 
-- `process.md`: planificación, alcance, review y sincronización de estado.
-- `code-shape.md`: simplicidad y forma del cambio.
-- `commits.md`: historia versionada y entrega.
+`system/` pertenece a Cauce y se reemplaza completo en cada actualización:
+
+- `system/process.md`: planificación, alcance, review y sincronización de estado.
+- `system/code-shape.md`: simplicidad y forma del cambio.
+- `system/commits.md`: historia versionada y entrega.
+
+Las reglas propias del proyecto van en este directorio, junto a `system/`, y nunca se tocan al
+actualizar. Para cambiar una regla del sistema, escribí la tuya con el mismo nombre: la del proyecto
+manda y `check` reporta el override en vez de fallar.
 
 Las convenciones específicas de lenguaje viven junto al servicio que usa ese lenguaje.

package/template/tools/ops.js

@@ -1,5 +1,27 @@
 #!/usr/bin/env node
 'use strict'
 
+// Punto de entrada estable del proyecto: nadie —ni una persona ni un agente— necesita saber de
+// dónde sale el motor. Se prefiere la dependencia npm, que se actualiza con el lockfile; si el
+// repositorio no usa npm (Go, Python, Rust), se usa la copia de `.ops/engine`.
+
 const path = require('path')
-require(path.join(__dirname, '..', '.ops', 'engine', 'cli', 'ops.js'))
+
+const root = path.join(__dirname, '..')
+const candidates = [
+  () => require.resolve('@ingeniomaps/cauce/engine/cli/ops.js', { paths: [root] }),
+  () => require.resolve(path.join(root, '.ops', 'engine', 'cli', 'ops.js')),
+]
+
+let engine = ''
+for (const candidate of candidates) {
+  try { engine = candidate(); break } catch { /* siguiente candidato */ }
+}
+
+if (!engine) {
+  console.error('No se encontró el motor de Cauce.')
+  console.error('  Instalá la dependencia con "npm install" o restaurá .ops/engine con "cauce upgrade".')
+  process.exit(2)
+}
+
+require(engine)

package/agents/coordinators/.gitkeep

@@ -1 +0,0 @@
-

package/agents/specialists/.gitkeep

@@ -1 +0,0 @@
-

package/agents/workflows/.gitkeep

@@ -1 +0,0 @@
-