@ingeniomaps/cauce 0.2.0 → 0.4.0

package/engine/cli/ops.js

@@ -12,6 +12,7 @@ const A = require('../automation')
 const F = require('../core/files')
 const O = require('../core/ownership')
 const CL = require('../core/changelog')
+const M = require('../core/manifest')
 const C = require('../config/validate')
 const T = require('../teams/registry')
 const AG = require('../agents/catalog')
@@ -125,25 +126,13 @@ function init(target) {
     '{{PLANNING_DIR}}': 'planning',
     '{{WORKSPACE_PATH}}': mode === 'embedded' ? '.' : '..',
   }, process.argv.includes('--force'))
-  copyTemplate(path.join(PROJECT_ROOT, 'agents'), path.join(root, 'agents'), {
-    '{{PROJECT_NAME}}': name,
-    '{{MODE}}': mode,
-    '{{PLANNING_DIR}}': 'planning',
-    '{{WORKSPACE_PATH}}': mode === 'embedded' ? '.' : '..',
-  }, process.argv.includes('--force'))
-  copyTemplate(path.join(PROJECT_ROOT, 'teams'), path.join(root, 'teams'), {
-    '{{PROJECT_NAME}}': name,
-    '{{MODE}}': mode,
-    '{{PLANNING_DIR}}': 'planning',
-    '{{WORKSPACE_PATH}}': mode === 'embedded' ? '.' : '..',
-  }, process.argv.includes('--force'))
   // `ci.yml` valida el toolkit con `npm run ci`; una instancia no tiene ese script ni sus pruebas.
   copyTemplate(path.join(PROJECT_ROOT, '.github', 'workflows'), path.join(root, '.github', 'workflows'), {
     '{{PROJECT_NAME}}': name,
     '{{MODE}}': mode,
     '{{PLANNING_DIR}}': 'planning',
     '{{WORKSPACE_PATH}}': mode === 'embedded' ? '.' : '..',
-  }, process.argv.includes('--force'), ['ci.yml'])
+  }, process.argv.includes('--force'), ['ci.yml', 'agent-learning.yml'])
   const preserve = process.argv.includes('--force')
   copyRuntime(
     path.join(PROJECT_ROOT, 'automatization', 'hooks'),
@@ -176,11 +165,24 @@ function init(target) {
     const engine = path.join(root, '.ops', 'engine')
     copyRuntime(path.join(PROJECT_ROOT, 'engine'), engine, preserve, root)
     fs.chmodSync(path.join(engine, 'cli', 'ops.js'), 0o755)
+    // Sin npm no hay de dónde leer el catálogo en tiempo de ejecución: viaja junto al motor.
+    copyRuntime(path.join(PROJECT_ROOT, 'agents'), path.join(root, '.ops', 'agents'), preserve, root)
+    copyRuntime(path.join(PROJECT_ROOT, 'teams'), path.join(root, '.ops', 'teams'), preserve, root)
+  }
+  let entregado = {}
+  for (const relative of O.trackedPaths()) {
+    const dir = path.join(root, relative)
+    if (fs.existsSync(dir)) entregado = { ...entregado, ...M.record(root, relative, O.treeFiles(dir)) }
   }
+  M.write(root, entregado)
   // La instancia recuerda de qué versión salió: sin esto no hay actualización posible.
   const configFile = path.join(root, 'ops.config.json')
   const config = JSON.parse(fs.readFileSync(configFile, 'utf8'))
   config.cauceVersion = version
+  // El esquema vive donde quedó el motor; la plantilla no puede saberlo de antemano.
+  config.$schema = engineMode === 'dependency'
+    ? 'node_modules/@ingeniomaps/cauce/engine/schemas/ops-config.schema.json'
+    : '.ops/engine/schemas/ops-config.schema.json'
   F.atomicWriteJson(configFile, config)
   console.log(`\n✓ ${name}: sistema ops creado en ${root}`)
   if (engineMode === 'dependency') console.log('  siguiente: npm install (el motor viene de la dependencia)')
@@ -492,7 +494,7 @@ function upgrade(dir) {
   const from = instanceVersion(root)
   const to = require(path.join(PROJECT_ROOT, 'package.json')).version
   const system = O.systemPaths(root)
-  const changed = O.localChanges(root, PROJECT_ROOT)
+  const changed = O.localChanges(root)
   const overrides = O.overrides(root)
 
   if (dry) {
@@ -503,11 +505,37 @@ function upgrade(dir) {
     process.exit(1)
   }
 
+  // Antes de retirar nada, comprobar que no se lleve puesto aprendizaje acumulado.
+  const rescatar = O.retiredWithLearning(root)
+  if (rescatar.length && !force) {
+    for (const file of rescatar) console.error(`✗ ${file}`)
+    fail(
+      `\n${rescatar.length} archivo(s) de aprendizaje quedaron en una ruta que Cauce ya no mantiene.\n\n` +
+      'Movelos a un cargo propio en agents/roles/<slug>/learning/ y repetí, o descartalos con --force.',
+    )
+  }
+
   if (changed.length && !force) {
     for (const file of changed) console.error(`✗ ${file}`)
+    const reglas = changed.filter((file) => file.includes('/system/'))
+    const runtime = changed.filter((file) => !file.includes('/system/'))
+    const guia = []
+    if (reglas.length) {
+      guia.push(
+        'Las reglas y decisiones bajo system/ son del toolkit. Para cambiar una, escribí la tuya al\n'
+        + 'lado con el mismo ID: el proyecto manda y `check` lo reporta como override explícito.',
+      )
+    }
+    if (runtime.length) {
+      guia.push(
+        'El runtime es del toolkit: en vez de editarlo, agregá lo tuyo al lado con otro nombre —un\n'
+        + 'guard propio sobrevive a cada actualización— y registralo en la configuración de tu runner,\n'
+        + 'que sí es del proyecto. Para desactivar un guard alcanza con quitarlo de esa configuración.',
+      )
+    }
     fail(
-      `\n${changed.length} archivo(s) del runtime fueron editados y se perderían.\n` +
-      'Movelos junto a system/ como regla propia, o repetí con --force para descartarlos.',
+      `\n${changed.length} archivo(s) que mantiene Cauce fueron editados y se perderían.\n\n` +
+      `${guia.join('\n\n')}\n\nSi el cambio ya no te sirve, repetí con --force para descartarlo.`,
     )
   }
 
@@ -515,8 +543,9 @@ function upgrade(dir) {
     const origin = path.join(PROJECT_ROOT, O.sourceOf(relative))
     if (!fs.existsSync(origin)) continue
     const target = path.join(root, relative)
-    // Una instancia que toma el motor de npm no debe recuperar la copia: la actualiza el lockfile.
-    if (relative === '.ops/engine' && !fs.existsSync(target)) continue
+    // `.ops/` es el paquete vendorizado de una instancia sin npm. Si no existe, esta instancia lo
+    // toma de la dependencia y crearlo sería duplicar lo que el lockfile ya versiona.
+    if (relative.startsWith('.ops/') && !fs.existsSync(target)) continue
     const skip = O.TEMPLATE_OWNED
       .filter((owned) => owned.startsWith(`${relative}/`))
       .map((owned) => path.basename(owned))
@@ -527,11 +556,34 @@ function upgrade(dir) {
     }
   }
 
+  // Retirar lo que el toolkit ya no distribuye, después de haber actualizado lo que sí.
+  const retirado = []
+  for (const relative of O.RETIRED) {
+    const target = path.join(root, relative)
+    if (!fs.existsSync(target)) continue
+    F.assertNoSymlinkPath(root, target)
+    fs.rmSync(target, { recursive: true, force: true })
+    retirado.push(relative)
+  }
+
+  // Dejar registrado lo que se entregó, para poder distinguir después una edición local de una
+  // mejora del toolkit.
+  let registro = M.read(root)
+  for (const relative of O.trackedPaths()) {
+    const dir = path.join(root, relative)
+    if (fs.existsSync(dir)) registro = { ...registro, ...M.record(root, relative, O.treeFiles(dir)) }
+  }
+  M.write(root, registro)
+
   const config = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8'))
   config.cauceVersion = to
   F.atomicWriteJson(path.join(root, 'ops.config.json'), config)
 
   console.log(`✓ Cauce ${from || '(previa)'} → ${to}`)
+  // Descartar con --force es legítimo; hacerlo sin dejar rastro no. Queda en la salida del comando,
+  // que es la evidencia que el protocolo pide para cualquier cambio.
+  for (const file of changed) console.log(`− descartado tu cambio en ${file}`)
+  for (const relative of retirado) console.log(`− retirado ${relative}: Cauce ya no lo distribuye`)
   printChangelog(from, to)
   console.log(`  ${system.length} ruta(s) del sistema y ${O.RUNTIME_PATHS.length} del runtime actualizadas`)
   for (const override of overrides) {
@@ -547,8 +599,10 @@ function agents(action, dir) {
   const root = path.resolve(dir || '.')
   const roles = AG.list(root)
   if (process.argv.includes('--json')) {
+    // `path` viene resuelto: quien consuma esto no debería reconstruir dónde ganó la precedencia.
     return console.log(JSON.stringify(roles.map((role) => ({
       slug: role.slug, type: role.type, system: role.system,
+      path: path.relative(root, role.dir).split(path.sep).join('/'),
     }))))
   }
   for (const role of roles) console.log(`${role.slug}${role.system ? '' : '  (propio)'}`)

package/engine/core/manifest.js

@@ -0,0 +1,54 @@
+'use strict'
+
+// Qué entregó Cauce y con qué contenido. Sin este registro no se puede distinguir un archivo que
+// la empresa editó de uno que cambió río arriba: los dos se ven igual comparando la instancia
+// contra el paquete, y `upgrade` terminaría negándose ante cualquier mejora del toolkit.
+//
+// Se guarda junto a la configuración porque es estado de la instalación, no del producto, y se
+// commitea: todo el equipo tiene que ver lo mismo.
+
+const crypto = require('node:crypto')
+const fs = require('node:fs')
+const path = require('node:path')
+
+const FILE = path.join('.cauce', 'manifest.json')
+
+function digest(file) {
+  try {
+    return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex').slice(0, 16)
+  } catch { return '' }
+}
+
+function read(root) {
+  try {
+    const data = JSON.parse(fs.readFileSync(path.join(root, FILE), 'utf8'))
+    return data && typeof data.files === 'object' ? data.files : {}
+  } catch { return {} }
+}
+
+function write(root, files) {
+  const target = path.join(root, FILE)
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  const ordered = Object.fromEntries(Object.entries(files).sort(([left], [right]) => left.localeCompare(right)))
+  fs.writeFileSync(target, `${JSON.stringify({ version: 1, files: ordered }, null, 2)}\n`)
+}
+
+// Registra lo entregado en una ruta, relativo a la raíz de la instancia.
+function record(root, relative, files) {
+  const current = read(root)
+  for (const file of files) current[`${relative}/${file}`] = digest(path.join(root, relative, file))
+  return current
+}
+
+// Archivos que la empresa modificó después de recibirlos. Un archivo sin registro previo no
+// cuenta: llegó con una versión anterior a este mecanismo, o lo agregó el proyecto.
+function edited(root, relative, files) {
+  const recorded = read(root)
+  return files.filter((file) => {
+    const key = `${relative}/${file}`
+    if (!recorded[key]) return false
+    return recorded[key] !== digest(path.join(root, relative, file))
+  })
+}
+
+module.exports = { FILE, digest, edited, read, record, write }

package/engine/core/ownership.js

@@ -22,6 +22,7 @@ const SYSTEM_FILES = [
   'planning/rules/README.md',
   'planning/roadmap/README.md',
   'planning/roadmap/epic-000-template.md',
+  'organization/roles/README.md',
 ]
 
 // Colecciones mixtas: el toolkit posee `<dir>/system/`, el proyecto todo lo demás del directorio.
@@ -29,7 +30,6 @@ 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.
@@ -37,6 +37,8 @@ const SYSTEM_COLLECTIONS = [
 // se reporta antes de pisarla, nunca después.
 const RUNTIME_PATHS = [
   '.ops/engine',
+  '.ops/agents',
+  '.ops/teams',
   'automatization/hooks',
   'automatization/runners',
   'automatization/workflows',
@@ -48,9 +50,15 @@ 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/`.
+const TEMPLATE_PREFIXES = ['planning/', 'organization/', 'integrations/']
+
 function sourceOf(relative) {
   if (relative === '.ops/engine') return 'engine'
-  if (relative.startsWith('planning/')) return path.join('template', relative)
+  if (relative === '.ops/agents') return 'agents'
+  if (relative === '.ops/teams') return 'teams'
+  if (TEMPLATE_PREFIXES.some((prefix) => relative.startsWith(prefix))) {
+    return path.join('template', relative)
+  }
   return relative
 }
 
@@ -71,6 +79,19 @@ function engineAt(root, relative = '') {
     .find((candidate) => fs.existsSync(candidate)) || ''
 }
 
+// Definiciones que consume el motor —cargos y equipos— y que por eso viajan con el paquete en vez
+// de copiarse. Se reconocen por contener `system/`, que es el espacio del toolkit y no algo que un
+// proyecto deba crear. Una sola implementación para las dos, o divergen.
+function packageDir(root, name) {
+  const candidates = [
+    path.join(root, 'node_modules', '@ingeniomaps', 'cauce', name),
+    path.join(root, '.ops', name),
+    path.join(root, name),
+  ]
+  return candidates.find((dir) => fs.existsSync(path.join(dir, 'system'))
+    || fs.existsSync(path.join(dir, 'roles', 'system'))) || ''
+}
+
 // 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}/
@@ -106,12 +127,35 @@ function overrides(root) {
   return found
 }
 
+// Rutas que el toolkit dejó de materializar. Sin esto una instancia arrastra para siempre lo que
+// alguna versión suya copió: `upgrade` agrega y reemplaza, pero nunca quitaba nada.
+const RETIRED = [
+  'agents/roles/system',
+  'teams/system',
+  '.github/workflows/agent-learning.yml',
+]
+
+// Aprendizaje que quedó dentro de una ruta retirada. Es lo único ahí que no se puede reponer, así
+// que se detecta antes de borrar nada: perderlo en silencio sería peor que dejar el directorio.
+function retiredWithLearning(root) {
+  const found = []
+  for (const relative of RETIRED) {
+    const dir = path.join(root, relative)
+    if (!fs.existsSync(dir)) continue
+    for (const file of treeFiles(dir)) {
+      if (!/(^|\/)learning\/(reports|proposals)\//.test(file)) continue
+      if (path.basename(file).startsWith('_')) continue
+      found.push(`${relative}/${file}`)
+    }
+  }
+  return found
+}
+
 // Rutas que `upgrade` reemplaza. Todo lo que no aparezca acá pertenece al proyecto.
+// Se listan aunque todavía no existan en la instancia: así un archivo nuevo del sistema llega en
+// vez de esperar a que alguien lo cree a mano.
 function systemPaths(root) {
-  const paths = []
-  for (const file of SYSTEM_FILES) {
-    if (fs.existsSync(path.join(root, file))) paths.push(file)
-  }
+  const paths = [...SYSTEM_FILES]
   for (const collection of SYSTEM_COLLECTIONS) {
     const dir = path.join(root, collection, 'system')
     if (fs.existsSync(dir)) paths.push(`${collection}/system`)
@@ -132,28 +176,31 @@ function treeFiles(dir, prefix = '') {
   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) {
+// Rutas que Cauce mantiene y que por eso conviene registrar y vigilar.
+function trackedPaths() {
+  return [...RUNTIME_PATHS, ...SYSTEM_COLLECTIONS.map((collection) => `${collection}/system`)]
+}
+
+// Archivos que la empresa editó después de recibirlos. Se compara contra lo que Cauce entregó,
+// no contra el paquete: si se comparara contra el paquete, cualquier mejora del toolkit se vería
+// idéntica a una edición local y bloquearía la actualización.
+function localChanges(root) {
+  const manifest = require('./manifest')
   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}`)
-      }
-    }
+  for (const target of trackedPaths()) {
+    const dir = path.join(root, target)
+    if (!fs.existsSync(dir)) continue
+    for (const file of manifest.edited(root, target, treeFiles(dir))) changed.push(`${target}/${file}`)
   }
   return changed
 }
 
 module.exports = {
+  RETIRED,
+  trackedPaths,
+  packageDir,
   RUNTIME_PATHS,
+  retiredWithLearning,
   engineAt,
   engineCandidates,
   TEMPLATE_OWNED,

package/engine/teams/registry.js

@@ -5,14 +5,23 @@ 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 systemTeams(root) {
+  return require('../core/ownership').packageDir(root, 'teams')
+}
+
 function teamFile(root, slug) {
   if (!SLUG.test(slug || '')) throw new Error(`team inválido: ${slug || '(vacío)'}`)
   const own = path.join(root, 'teams', slug, 'team.json')
   if (fs.existsSync(own)) return own
-  return path.join(root, 'teams', 'system', slug, 'team.json')
+  const system = systemTeams(root)
+  return system ? path.join(system, 'system', slug, 'team.json') : own
 }
 
 // Devuelve el motivo real: "no existe" y "ambiguo" piden acciones distintas de quien lo lea.
@@ -40,6 +49,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')
@@ -58,6 +68,9 @@ 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)'}`)
@@ -66,6 +79,9 @@ function validate(root, slug) {
       if (problem) errors.push(problem)
     }
   }
+  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')
@@ -82,9 +98,13 @@ function slugsIn(dir) {
 }
 
 // Un slug aparece una sola vez aunque exista en los dos niveles: el del proyecto ya ganó.
+// Los propios de la empresa y los que trae Cauce, sin duplicar un slug que ya ganó el proyecto.
 function list(root) {
-  const teams = path.join(root, 'teams')
-  const slugs = new Set([...slugsIn(teams), ...slugsIn(path.join(teams, 'system'))])
+  const system = systemTeams(root)
+  const slugs = new Set([
+    ...slugsIn(path.join(root, 'teams')),
+    ...(system ? slugsIn(path.join(system, 'system')) : []),
+  ])
   return [...slugs].sort()
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingeniomaps/cauce",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Sistema portable de planificación y ejecución verificable para cualquier proyecto",
   "type": "commonjs",
   "bin": {

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.