@ingeniomaps/cauce 0.1.0 → 0.3.0

package/engine/core/ownership.js

@@ -0,0 +1,168 @@
+'use strict'
+
+// Frontera entre lo que actualiza el toolkit y lo que pertenece al proyecto.
+// Es la fuente única: `check` reporta overrides contra esto y `upgrade` decide qué reemplaza.
+//
+// La regla es una carpeta, no un diff: nada fuera de esta declaración se toca jamás.
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+// Archivos de los que el toolkit es único autor. Un proyecto que necesite cambiarlos no los
+// edita: agrega una regla propia junto a las de `system/`, que sí sobrevive al upgrade.
+const SYSTEM_FILES = [
+  'planning/PROTOCOL.md',
+  'planning/FLOW.md',
+  'planning/METHODOLOGY.md',
+  'planning/README.md',
+  'planning/adr/000-template.md',
+  'planning/adr/README.md',
+  'planning/business-rules/000-template.md',
+  'planning/business-rules/README.md',
+  'planning/rules/README.md',
+  'planning/roadmap/README.md',
+  'planning/roadmap/epic-000-template.md',
+]
+
+// Colecciones mixtas: el toolkit posee `<dir>/system/`, el proyecto todo lo demás del directorio.
+const SYSTEM_COLLECTIONS = [
+  'planning/adr',
+  'planning/business-rules',
+  'planning/rules',
+  'teams',
+]
+
+// Copias del runtime: el proyecto las recibe para poder ejecutar sin red, pero no las escribe.
+// Se reemplazan enteras. Mientras no tengan su propio `system/`, una edición local se detecta y
+// se reporta antes de pisarla, nunca después.
+const RUNTIME_PATHS = [
+  '.ops/engine',
+  'automatization/hooks',
+  'automatization/runners',
+  'automatization/workflows',
+]
+
+// Rutas que el paquete tiene por duplicado: una versión para el proyecto en `template/` y otra
+// interna del toolkit. Gana la del template, que es la que le habla a quien usa la instancia.
+const TEMPLATE_OWNED = ['automatization/runners/README.md']
+
+// Dentro del paquete, lo que una instancia recibe en su raíz vive bajo `template/`; el catálogo,
+// los equipos y la automatización están en la raíz del paquete, y el motor en `engine/`.
+function sourceOf(relative) {
+  if (relative === '.ops/engine') return 'engine'
+  if (relative.startsWith('planning/')) return path.join('template', relative)
+  return relative
+}
+
+// Dónde puede estar el motor, en orden de preferencia. Lo mismo que resuelven `tools/ops.js`,
+// el wrapper de hooks y el bridge de Antigravity: declararlo una vez evita que un consumidor
+// quede afuera cuando aparece una forma nueva de instalarlo.
+function engineCandidates(root) {
+  return [
+    path.join(root, 'node_modules', '@ingeniomaps', 'cauce', 'engine'),
+    path.join(root, '.ops', 'engine'),
+    path.join(root, 'engine'),
+  ]
+}
+
+function engineAt(root, relative = '') {
+  return engineCandidates(root)
+    .map((dir) => (relative ? path.join(dir, relative) : dir))
+    .find((candidate) => fs.existsSync(candidate)) || ''
+}
+
+// Identidad de una entrada dentro de una colección, para detectar que el proyecto sobrescribe
+// algo del sistema. Las reglas y decisiones se identifican por su ID; el resto, por su nombre.
+const ID_PATTERN = /^(?:BR-)?[A-Z][A-Z0-9]*-\d{3}/
+
+function identity(name) {
+  const base = name.replace(/\.md$/, '')
+  const id = base.match(ID_PATTERN)
+  return id ? id[0] : base
+}
+
+function entries(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.name !== 'README.md' && !entry.name.startsWith('.'))
+      .map((entry) => entry.name)
+  } catch { return [] }
+}
+
+// Entradas del proyecto que reemplazan a una del sistema con la misma identidad.
+function overrides(root) {
+  const found = []
+  for (const collection of SYSTEM_COLLECTIONS) {
+    const dir = path.join(root, collection)
+    const system = new Map()
+    for (const name of entries(path.join(dir, 'system'))) system.set(identity(name), name)
+    if (!system.size) continue
+    for (const name of entries(dir)) {
+      if (name === 'system' || name === '000-template.md') continue
+      const key = identity(name)
+      if (system.has(key)) found.push({ collection, id: key, project: name, system: system.get(key) })
+    }
+  }
+  return found
+}
+
+// Rutas que `upgrade` reemplaza. Todo lo que no aparezca acá pertenece al proyecto.
+function systemPaths(root) {
+  const paths = []
+  for (const file of SYSTEM_FILES) {
+    if (fs.existsSync(path.join(root, file))) paths.push(file)
+  }
+  for (const collection of SYSTEM_COLLECTIONS) {
+    const dir = path.join(root, collection, 'system')
+    if (fs.existsSync(dir)) paths.push(`${collection}/system`)
+  }
+  return paths
+}
+
+// Archivos de un árbol, relativos a él, para comparar instancia contra paquete.
+function treeFiles(dir, prefix = '') {
+  const found = []
+  let list = []
+  try { list = fs.readdirSync(dir, { withFileTypes: true }) } catch { return found }
+  for (const entry of list) {
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name
+    if (entry.isDirectory()) found.push(...treeFiles(path.join(dir, entry.name), relative))
+    else found.push(relative)
+  }
+  return found.sort()
+}
+
+// Archivos del runtime que el proyecto editó: existen en las dos partes y difieren. Un archivo
+// que sólo existe en la instancia es un agregado propio, no una edición, y sobrevive intacto.
+function localChanges(root, packageRoot) {
+  const changed = []
+  for (const target of RUNTIME_PATHS) {
+    const from = path.join(packageRoot, sourceOf(target))
+    const to = path.join(root, target)
+    if (!fs.existsSync(to) || !fs.existsSync(from)) continue
+    for (const file of treeFiles(from)) {
+      if (TEMPLATE_OWNED.includes(`${target}/${file}`)) continue
+      const mine = path.join(to, file)
+      if (!fs.existsSync(mine)) continue
+      if (fs.readFileSync(mine, 'utf8') !== fs.readFileSync(path.join(from, file), 'utf8')) {
+        changed.push(`${target}/${file}`)
+      }
+    }
+  }
+  return changed
+}
+
+module.exports = {
+  RUNTIME_PATHS,
+  engineAt,
+  engineCandidates,
+  TEMPLATE_OWNED,
+  SYSTEM_COLLECTIONS,
+  SYSTEM_FILES,
+  identity,
+  localChanges,
+  overrides,
+  sourceOf,
+  systemPaths,
+  treeFiles,
+}

package/engine/schemas/ops-config.schema.json

@@ -5,6 +5,7 @@
   "required": ["project", "mode", "planningDir", "workspaceRoots", "runner"],
   "properties": {
     "$schema": { "type": "string", "minLength": 1 },
+    "cauceVersion": { "type": "string", "minLength": 1 },
     "project": { "type": "string", "minLength": 1 },
     "mode": { "enum": ["embedded", "sidecar", "toolkit"] },
     "planningDir": { "type": "string", "minLength": 1 },

package/engine/teams/registry.js

@@ -2,23 +2,28 @@
 
 const fs = require('fs')
 const path = require('path')
+const catalog = require('../agents/catalog')
 
 const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const PHASES = ['discovery', 'delivery']
+// Qué deja el recorrido: una épica candidata que alguien puede promover, o un informe que registra
+// lo aprendido. Sin declararlo, el workflow sólo sabría terminar de una forma.
+const OUTCOMES = ['epic', 'report']
 
+// El proyecto manda sobre el sistema: un team propio con el mismo slug reemplaza al de `system/`,
+// que se sigue actualizando debajo sin que nadie tenga que forkearlo.
 function teamFile(root, slug) {
   if (!SLUG.test(slug || '')) throw new Error(`team inválido: ${slug || '(vacío)'}`)
-  return path.join(root, 'teams', slug, 'team.json')
+  const own = path.join(root, 'teams', slug, 'team.json')
+  if (fs.existsSync(own)) return own
+  return path.join(root, 'teams', 'system', slug, 'team.json')
 }
 
-function agentMatches(root, slug) {
-  const catalog = path.join(root, 'agents')
-  let types = []
-  try {
-    types = fs.readdirSync(catalog, { withFileTypes: true }).filter((entry) => entry.isDirectory())
-  } catch { return [] }
-  return types
-    .map((entry) => path.join(catalog, entry.name, slug, 'SKILL.md'))
-    .filter((file) => fs.existsSync(file))
+// Devuelve el motivo real: "no existe" y "ambiguo" piden acciones distintas de quien lo lea.
+function agentProblem(root, slug) {
+  try { catalog.resolve(root, slug); return '' } catch (error) {
+    return /ambiguo/.test(error.message) ? `agente ambiguo: ${slug}` : `agente inexistente: ${slug}`
+  }
 }
 
 function read(root, slug) {
@@ -39,6 +44,7 @@ function validate(root, slug) {
   for (const field of ['name', 'purpose', 'entryAgent', 'facilitator']) {
     if (typeof manifest[field] !== 'string' || !manifest[field].trim()) errors.push(`falta ${field}`)
   }
+  if (!OUTCOMES.includes(manifest.outcome)) errors.push(`outcome debe ser ${OUTCOMES.join(' o ')}`)
   if (!Array.isArray(manifest.stages) || !manifest.stages.length) errors.push('stages debe contener etapas')
   if (!Array.isArray(manifest.guardrails) || !manifest.guardrails.length) errors.push('guardrails debe contener controles')
   if (!Array.isArray(manifest.completion) || !manifest.completion.length) errors.push('completion debe contener criterios')
@@ -57,29 +63,40 @@ function validate(root, slug) {
     agents.add(stage.agent)
     if (!Array.isArray(stage.produces) || !stage.produces.length) errors.push(`${stage.id}: falta produces`)
     if (typeof stage.exitGate !== 'string' || !stage.exitGate.trim()) errors.push(`${stage.id}: falta exitGate`)
+    // Descubrimiento propone, entrega ejecuta. Sin la distinción, un recorrido de descubrimiento
+    // terminaría construyendo antes de que exista la épica y antes de la promoción humana.
+    if (!PHASES.includes(stage.phase)) errors.push(`${stage.id}: phase debe ser ${PHASES.join(' o ')}`)
   }
   for (const agent of agents) {
     if (!SLUG.test(agent || '')) errors.push(`slug de agente inválido: ${agent || '(vacío)'}`)
     else {
-      const matches = agentMatches(root, agent)
-      if (!matches.length) errors.push(`agente inexistente: ${agent}`)
-      if (matches.length > 1) errors.push(`agente ambiguo: ${agent}`)
+      const problem = agentProblem(root, agent)
+      if (problem) errors.push(problem)
     }
   }
-  const workflow = path.join(root, 'teams', slug, 'WORKFLOW.md')
+  if (!(manifest.stages || []).some((stage) => stage.phase === 'discovery')) {
+    errors.push('falta al menos una etapa de discovery: un equipo sin descubrimiento no propone nada')
+  }
+  // Junto al team.json que ganó la resolución, no en una ruta fija: el team puede venir de system/.
+  const workflow = path.join(path.dirname(teamFile(root, slug)), 'WORKFLOW.md')
   if (!fs.existsSync(workflow)) errors.push('falta WORKFLOW.md')
   return { errors, stages: (manifest.stages || []).length, agents: agents.size, manifest }
 }
 
-function list(root) {
-  const catalog = path.join(root, 'teams')
+function slugsIn(dir) {
   try {
-    return fs.readdirSync(catalog, { withFileTypes: true })
-      .filter((entry) => entry.isDirectory())
-      .filter((entry) => fs.existsSync(path.join(catalog, entry.name, 'team.json')))
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && entry.name !== 'system')
+      .filter((entry) => fs.existsSync(path.join(dir, entry.name, 'team.json')))
       .map((entry) => entry.name)
-      .sort()
   } catch { return [] }
 }
 
+// Un slug aparece una sola vez aunque exista en los dos niveles: el del proyecto ya ganó.
+function list(root) {
+  const teams = path.join(root, 'teams')
+  const slugs = new Set([...slugsIn(teams), ...slugsIn(path.join(teams, 'system'))])
+  return [...slugs].sort()
+}
+
 module.exports = { list, read, validate }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingeniomaps/cauce",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Sistema portable de planificación y ejecución verificable para cualquier proyecto",
   "type": "commonjs",
   "bin": {
@@ -13,7 +13,8 @@
     "teams/",
     "automatization/",
     ".github/workflows/",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "ops": "node engine/cli/ops.js",

package/teams/000-template.md

@@ -0,0 +1,110 @@
+# Plantilla de equipo
+
+Un equipo compone varios cargos en etapas, con un dueño por dominio de decisión y un gate de salida por
+etapa. Vive en `teams/<slug>/` y necesita dos archivos: `team.json` y `WORKFLOW.md`.
+
+Los equipos que trae Cauce están en `teams/system/`. Un equipo propio con el mismo slug **reemplaza** al
+del sistema; con otro slug, convive. Nunca editar dentro de `system/`: se pierde al actualizar.
+
+Validar siempre con `node tools/ops.js team check <slug>` antes de usarlo.
+
+## `team.json`
+
+```json
+{
+  "schemaVersion": 1,
+  "slug": "acme-soporte",
+  "name": "Soporte de Acme",
+  "purpose": "Una frase: qué convierte este equipo, de qué entrada a qué salida.",
+  "outcome": "report",
+
+  "entryAgent": "customer-support-specialist",
+  "facilitator": "project-manager",
+
+  "decisionOwners": {
+    "customer_impact": "customer-support-specialist",
+    "technical_design": "software-architect"
+  },
+  "conditionalAgents": ["security-engineer", "privacy-compliance-specialist"],
+
+  "stages": [
+    {
+      "id": "triage",
+      "phase": "discovery",
+      "agent": "customer-support-specialist",
+      "dependsOn": [],
+      "produces": ["impacto-y-alcance"],
+      "exitGate": "Qué falla, a cuántos afecta y desde cuándo está explícito y verificado."
+    },
+    {
+      "id": "diagnose",
+      "phase": "discovery",
+      "agent": "software-architect",
+      "dependsOn": ["triage"],
+      "produces": ["causa-probable", "opciones"],
+      "exitGate": "Hay una causa sostenida por evidencia, o la pregunta concreta que la resolvería."
+    }
+  ],
+
+  "guardrails": [
+    "Cada agente conserva los límites y autorizaciones de su SKILL.md.",
+    "Ningún handoff convierte una propuesta en aprobación ni en ejecución."
+  ],
+  "completion": [
+    "El resultado distingue lo que se sabe de lo que se supone.",
+    "Lo que quedó pendiente tiene responsable y acción concreta."
+  ]
+}
+```
+
+## Qué exige el validador
+
+| Campo | Regla |
+|---|---|
+| `schemaVersion` | debe ser `1` |
+| `slug` | igual al nombre del directorio, en kebab-case |
+| `name`, `purpose`, `entryAgent`, `facilitator` | string no vacío |
+| `outcome` | `epic` o `report` |
+| `stages` | al menos una, con `id` único en kebab-case |
+| `stages[].phase` | `discovery` o `delivery`, y al menos una `discovery` |
+| `stages[].dependsOn` | sólo etapas **anteriores**; no se permiten ciclos ni adelantos |
+| `stages[].produces` | al menos un artefacto nombrado |
+| `stages[].exitGate` | una condición verificable, no un deseo |
+| agentes citados | deben existir en `agents/` y no ser ambiguos |
+| `guardrails`, `completion` | al menos un elemento cada uno |
+| `WORKFLOW.md` | debe existir junto al `team.json` |
+
+## `outcome`: qué deja el recorrido
+
+- **`epic`** — propone trabajo. Escribe una épica candidata en `planning/roadmap/` con criterios
+  observables, y para. Es lo que corresponde cuando la pregunta es *qué construimos*.
+- **`report`** — registra lo aprendido. Escribe un informe en `planning/reports/<fecha>-<slug>.md`,
+  deja los seguimientos en la sección Lecciones de `planning/INBOX.md` **sin promover** y las acciones
+  que requieren una persona en `planning/HUMAN_ACTIONS.md`. Es lo que corresponde a una revisión.
+
+Ninguno de los dos promueve al BACKLOG. La diferencia no es cuánta autoridad tienen —ninguno tiene—,
+sino qué artefacto dejan para que una persona decida.
+
+## `discovery` y `delivery`
+
+**Descubrimiento propone; entrega ejecuta.** `/team` recorre únicamente las etapas `discovery` y termina
+proponiendo una épica. Las etapas `delivery` las corre `autobuild`, y sólo después de que una persona
+promueva esa épica al BACKLOG.
+
+Marcar una etapa de construcción como `discovery` haría que se escriba código antes de la aprobación
+humana, que es justamente lo que el protocolo impide.
+
+## Cómo escribir un exit gate
+
+Un gate se cumple o no se cumple sin discusión. Comparar:
+
+- ❌ "El problema está bien entendido."
+- ✅ "Problema, usuario, outcome, baseline y decisión requerida están explícitos."
+
+Si para saber si un gate se cumplió hace falta interpretar, el recorrido va a avanzar siempre.
+
+## `WORKFLOW.md`
+
+Acompaña al manifiesto y explica lo que el JSON no puede: cuándo activarlo, cómo se ve un handoff, con
+qué criterio entran los agentes condicionales y qué **no** hace el equipo. Sin ese archivo, `team check`
+falla.

package/teams/README.md

@@ -0,0 +1,60 @@
+# Equipos
+
+Un equipo compone varios cargos de `agents/` en un recorrido con etapas, dueños de decisión y gates de
+salida. Es lo que convierte una intención en una épica candidata —o en la razón por la que todavía no
+lo es— sin que un solo agente decida por todos.
+
+## Los que trae Cauce
+
+| Equipo | Descubrimiento | Deja | Para qué |
+|---|---|---|---|
+| `system/feasibility-review` | 3 etapas | épica | ¿vale el esfuerzo? Con la evidencia que ya existe. |
+| `system/product-development` | 5 etapas | épica | ¿qué construimos y cómo? Produce evidencia nueva. |
+| `system/incident-review` | 4 etapas | informe | ¿qué pasó y qué aprendemos? Después de contener. |
+
+Son tres **formas**, no tres dominios. Un equipo de seguridad o uno de crecimiento tienen la misma forma
+con otros cargos: eso lo escribe cada empresa, porque cómo decide es suyo.
+
+## Escribir uno propio
+
+Copiar la estructura de [000-template.md](000-template.md) a `teams/<slug>/`, con su `team.json` y su
+`WORKFLOW.md`, y validar:
+
+```bash
+node tools/ops.js team list
+node tools/ops.js team check <slug>
+node tools/ops.js team show <slug>
+```
+
+Un equipo propio con el mismo slug que uno de `system/` lo reemplaza; con otro slug, convive. **Nunca
+editar dentro de `system/`**: se reemplaza completo en cada actualización.
+
+## Invocar un equipo
+
+Tres formas, de la más simple a la más explícita:
+
+```text
+/team quiero cobrar con tarjeta guardada
+/team incident-review: se cayó el checkout el martes a las 14:00
+/team {"team": "acme-soporte", "intent": "qué se quiere evaluar"}
+```
+
+Sin prefijo corre `product-development`. El prefijo se confirma contra los equipos que existen: si no
+es uno, el texto completo se toma como intención, así que escribir `nota: revisar esto` no dispara un
+equipo llamado `nota`. Con el equipo pasado explícitamente, un slug inexistente falla en vez de caer al
+por defecto en silencio.
+
+## Corto o largo
+
+Un recorrido largo cuesta más y aporta más certeza. La elección es la misma que con los lanes de una
+tarea: usar el corto cuando la evidencia ya existe y la pregunta es de esfuerzo, y el largo cuando hay
+que averiguar algo antes de comprometerse.
+
+Un recorrido corto que termina en "hay que investigar" no falló: acotó el problema por el costo de tres
+etapas en lugar de cinco.
+
+## Lo que un equipo nunca hace
+
+Ningún recorrido promueve trabajo al BACKLOG. Escribe la épica candidata en `planning/roadmap/` y para;
+la promoción es la firma humana que autoriza ejecución. Un gate que no se cumple se convierte en una
+acción concreta en `planning/HUMAN_ACTIONS.md`, no en un gate más blando.

package/teams/system/feasibility-review/WORKFLOW.md

@@ -0,0 +1,60 @@
+# Feasibility Review
+
+## Cómo activarlo
+
+Usar este equipo cuando hay una intención concreta y la pregunta es **si vale el esfuerzo**, no cómo
+resolverla. Tres etapas y tres dueños de decisión: encuadre, factibilidad y recomendación.
+
+```text
+Usa el team feasibility-review para evaluar esta intención:
+<qué se quiere lograr, para quién, y qué evidencia ya tenemos>
+```
+
+Si la respuesta requiere hablar con usuarios, medir algo que hoy no se mide o explorar el diseño, este
+equipo no es el indicado: lo correcto es que recomiende investigar y que después corra
+`product-development`, que sí tiene research y shape.
+
+## Cuándo usar este y cuándo el largo
+
+| | `feasibility-review` | `product-development` |
+|---|---|---|
+| Etapas de descubrimiento | 3 | 5 |
+| Pregunta que responde | ¿vale el esfuerzo? | ¿qué construimos y cómo? |
+| Evidencia | usa la que ya existe | produce evidencia nueva |
+| Salida típica | hacer, no hacer o investigar | épica con criterios y diseño |
+
+Un recorrido corto que termina en "hay que investigar" no falló: acotó el problema por el costo de tres
+etapas en lugar de cinco.
+
+## Protocolo de handoff
+
+Cada handoff incluye:
+
+```markdown
+Etapa y agente:
+Pregunta que resuelve:
+Evidencia usada y su origen:
+Supuestos e incertidumbre:
+Lo que falta averiguar:
+Exit gate: cumplido / no cumplido
+Autorizaciones pendientes:
+```
+
+No avanzar si el exit gate no se cumple. La etapa siguiente puede devolver el handoff cuando falte
+evidencia, autoridad o un criterio verificable.
+
+## Selección de agentes condicionales
+
+`user-researcher` entra cuando el encuadre depende de una necesidad que nadie verificó.
+`security-engineer` y `privacy-compliance-specialist`, cuando la opción toca autenticación, permisos o
+datos personales. `finops-engineer`, cuando el costo de operar es parte de la decisión —típico si suma
+inferencia de modelos—. `legal-counsel`, cuando hay compromiso contractual o afirmación pública.
+
+Se incorporan por riesgo, no por rutina: sumar un cargo que no aporta diluye la revisión.
+
+## Límites
+
+El recorrido produce una recomendación, no una aprobación. Escribe la épica candidata en `roadmap/`
+cuando la respuesta es hacer, y **nunca promueve al BACKLOG**: esa firma es humana. Cuando la respuesta
+es investigar, la acción concreta queda en `planning/HUMAN_ACTIONS.md`; cuando es no hacer, el motivo y
+qué lo cambiaría quedan en la sección Lecciones de `planning/INBOX.md`.

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

@@ -0,0 +1,73 @@
+{
+  "schemaVersion": 1,
+  "slug": "feasibility-review",
+  "name": "Feasibility Review",
+  "purpose": "Decidir si una intención vale el esfuerzo, con la evidencia que ya existe, antes de abrir un descubrimiento completo.",
+  "outcome": "epic",
+  "entryAgent": "product-manager",
+  "facilitator": "project-manager",
+  "decisionOwners": {
+    "value_and_priority": "product-manager",
+    "technical_design": "software-architect",
+    "capacity_and_assignment": "engineering-manager"
+  },
+  "conditionalAgents": [
+    "user-researcher",
+    "security-engineer",
+    "privacy-compliance-specialist",
+    "finops-engineer",
+    "legal-counsel"
+  ],
+  "stages": [
+    {
+      "id": "frame",
+      "phase": "discovery",
+      "agent": "product-manager",
+      "dependsOn": [],
+      "produces": [
+        "problem-and-outcome",
+        "evidence-already-available"
+      ],
+      "exitGate": "Problema, usuario, outcome y qué evidencia ya existe están explícitos; lo que falta averiguar queda listado, no supuesto."
+    },
+    {
+      "id": "assess",
+      "phase": "discovery",
+      "agent": "software-architect",
+      "dependsOn": [
+        "frame"
+      ],
+      "produces": [
+        "feasibility-and-options",
+        "risks-and-unknowns"
+      ],
+      "exitGate": "Hay al menos una opción viable con su costo grueso y sus riesgos, o la razón técnica concreta por la que no la hay."
+    },
+    {
+      "id": "decide",
+      "phase": "discovery",
+      "agent": "engineering-manager",
+      "dependsOn": [
+        "assess"
+      ],
+      "produces": [
+        "recommendation",
+        "what-would-change-the-answer"
+      ],
+      "exitGate": "La recomendación es hacer, no hacer o investigar, con el esfuerzo estimado y qué evidencia cambiaría la respuesta."
+    }
+  ],
+  "guardrails": [
+    "Cada agente conserva los límites y autorizaciones de su SKILL.md.",
+    "Este recorrido usa la evidencia que ya existe; no la produce ni la reemplaza por supuestos.",
+    "Recomendar investigar es un resultado legítimo, no una falla del recorrido.",
+    "Los agentes condicionales se incorporan por riesgo, plataforma y alcance, no por rutina.",
+    "Ningún handoff convierte una recomendación en aprobación ni en ejecución."
+  ],
+  "completion": [
+    "La recomendación distingue lo que se sabe de lo que se supone.",
+    "El esfuerzo estimado tiene rango y supuestos visibles, no un número solo.",
+    "Queda escrito qué evidencia cambiaría la decisión.",
+    "Si el resultado es investigar, la acción concreta queda registrada para una persona."
+  ]
+}

package/teams/system/incident-review/WORKFLOW.md

@@ -0,0 +1,65 @@
+# Incident Review
+
+## Qué es y qué no es
+
+Este equipo hace la **revisión posterior** de un incidente ya contenido. No responde incidentes en vivo:
+un recorrido de agentes no es un incident commander, no tiene acceso a producción, no está de guardia y
+no puede decidir bajo presión con información parcial. Confundir una cosa con la otra sería peligroso.
+
+Mientras el incidente está activo, mandan las personas de guardia. Este recorrido empieza después,
+cuando el servicio ya está estable y lo que hace falta es entender qué pasó.
+
+```text
+Usa el team incident-review para analizar este incidente:
+<qué falló, cuándo, cómo se detectó y qué evidencia hay: logs, alertas, métricas, tickets>
+```
+
+## Salida
+
+Produce un **informe**, no una épica: `planning/reports/<fecha>-<slug>.md`. Los seguimientos quedan en la
+sección Lecciones de `planning/INBOX.md` **sin promover**, y las acciones que requieren una persona
+—comunicar a clientes, notificar a un regulador, cambiar un contrato— en `planning/HUMAN_ACTIONS.md`.
+
+Convertir un seguimiento en trabajo sigue siendo una decisión humana, igual que en cualquier otro
+recorrido.
+
+## Etapas
+
+```
+scope     → sre                    línea de tiempo e impacto real
+diagnose  → software-architect     factores que contribuyeron, y por qué no se detectó antes
+exposure  → security-engineer      si hubo acceso, pérdida o exposición de datos
+learn     → engineering-manager    seguimientos con dueño propuesto
+```
+
+`diagnose` y `exposure` dependen ambas de `scope` y responden preguntas distintas: una busca por qué
+falló, la otra qué quedó expuesto. Separarlas evita que la urgencia técnica tape la evaluación de datos.
+
+## Protocolo de handoff
+
+```markdown
+Etapa y agente:
+Pregunta que resuelve:
+Evidencia usada y su origen (log, alerta, métrica, ticket):
+Hechos / hipótesis / lo indeterminado:
+Exit gate: cumplido / no cumplido
+Autorizaciones u obligaciones pendientes:
+```
+
+Una causa sin evidencia se declara **hipótesis**, aunque cerrar el informe con una causa firme sea más
+cómodo. Un informe que inventa una causa para poder cerrarse hace daño: se toman decisiones sobre él.
+
+## Selección de agentes condicionales
+
+`database-administrator` y `devops-engineer` cuando el factor está en datos o en infraestructura.
+`privacy-compliance-specialist` y `legal-counsel` en cuanto la etapa `exposure` no puede descartar
+acceso a datos personales — ahí puede haber plazos regulatorios, y esa es una acción humana urgente.
+`qa-engineer` cuando la pregunta es por qué las pruebas no lo detectaron. `finops-engineer` cuando el
+incidente fue de costo, no de disponibilidad.
+
+## Límites
+
+Nadie en este recorrido opera producción, aplica una remediación, comunica a un cliente ni notifica a
+un regulador. Todo eso se propone y lo decide una persona. Tampoco se atribuye responsabilidad a
+personas: se analizan las condiciones que hicieron posible el fallo, porque un informe que busca
+culpables consigue que la próxima vez nadie reporte nada.