@ingeniomaps/cauce 0.2.0 → 0.3.0

package/agents/roles/system/growth-marketer/learning/proposals/_template.md

@@ -0,0 +1,15 @@
+---
+agent: data-analyst
+period: YYYY-MM
+status: proposed
+automatic_apply: false
+---
+
+# Propuesta mensual — YYYY-MM
+
+## Hallazgos
+## Evidencia
+## Cambio propuesto
+## Riesgos y regresiones
+## Evaluación
+## Aprobación humana

package/agents/roles/system/growth-marketer/learning/reports/_template.md

@@ -0,0 +1,14 @@
+---
+agent: data-analyst
+date: YYYY-MM-DD
+status: draft
+---
+
+# Investigación profesional semanal — YYYY-MM-DD
+
+## Fuentes consultadas
+## Hallazgos
+## Evidencia
+## Posibles prácticas obsoletas
+## Recomendación
+## Preguntas abiertas

package/agents/roles/system/growth-marketer/learning/sources.yaml

@@ -0,0 +1,33 @@
+version: 1
+rules:
+  require_primary_source: true
+  require_version_applicability: true
+  require_corroboration_for_major_change: true
+  reject_unsourced_claims: true
+  automatic_apply: false
+
+sources:
+  - name: Company funnel definitions cohorts spend and decisions
+    url: local://growth-context
+    tier: company-primary
+    topics: [funnel, cohorts, spend, decisions]
+  - name: Official advertising and analytics platform documentation
+    url: local://growth-stack-docs
+    tier: platform-primary
+    topics: [attribution, tracking, audiences, reporting]
+  - name: NIST Statistical Methods Handbook
+    url: https://www.itl.nist.gov/div898/handbook/
+    tier: primary-method
+    topics: [experiments, uncertainty, sampling, inference]
+  - name: ICC Advertising and Marketing Communications Code
+    url: https://iccwbo.org/business-codes/advertising-and-marketing-communications-code/
+    tier: professional-primary
+    topics: [claims, honesty, substantiation, disclosure]
+  - name: EDPB Guidelines on targeting and consent
+    url: https://www.edpb.europa.eu/our-work-tools/general-guidance/guidelines-recommendations-best-practices_en
+    tier: regulator-primary
+    topics: [privacy, consent, targeting, transfers]
+  - name: FTC Truth in Advertising
+    url: https://www.ftc.gov/business-guidance/advertising-marketing
+    tier: regulator-primary
+    topics: [claims, endorsements, substantiation, disclosure]

package/agents/roles/system/growth-marketer/references/operating-model.md

@@ -0,0 +1,76 @@
+# Modelo operativo de Growth Marketing
+
+## Contrato de embudo
+
+Antes de proponer inversión, cada etapa queda definida con la misma precisión que una métrica:
+
+- **Población**: quién entra y quién queda excluido, con la regla explícita.
+- **Etapas**: impresión, clic, visita, registro, activación y retención temprana, cada una con su
+  evento de origen y su ventana.
+- **Denominador**: contra qué se divide cada tasa. La mayoría de las discusiones de conversión son
+  desacuerdos sobre el denominador.
+- **Ventana de atribución**: declarada y constante entre comparaciones. Cambiarla a mitad de un análisis
+  invalida la serie.
+
+Una tasa sin población, ventana y denominador no es una métrica: es una opinión con decimales.
+
+## Economía unitaria
+
+Toda propuesta de inversión reporta, con supuestos visibles:
+
+- costo por resultado en la etapa que se está comprando;
+- costo de adquisición hasta el usuario activado, no hasta el registro;
+- margen de contribución y período de recuperación;
+- qué pasa si la conversión cae un tercio: si el caso sólo cierra en el escenario optimista, no cierra.
+
+El valor de vida se estima con cohortes observadas, no proyectando indefinidamente la retención del
+mejor mes.
+
+## Diseño de experimentos
+
+Antes de lanzar se escriben: hipótesis falsable, unidad de asignación, métrica primaria, métricas
+guardia, tamaño mínimo, duración y regla de decisión. Después de lanzar no se cambian.
+
+- Una sola métrica primaria. Varias métricas primarias es no tener ninguna.
+- Las métricas guardia protegen lo que el experimento podría romper: calidad del registro, carga de
+  soporte, tasa de reembolso, retención.
+- Mirar resultados antes de tiempo y cortar al ver un número favorable produce ganadores falsos.
+- Un resultado sin efecto también es un resultado: se registra, con el tamaño que se podría haber
+  detectado.
+
+## Atribución
+
+Ningún modelo de atribución es verdad. Se elige uno, se declara, y se lo trata como una lente:
+
+- Las cifras que reporta una plataforma publicitaria son de parte interesada y suelen sobreatribuir.
+- Se reconcilian contra datos propios; cuando la diferencia es grande, se reporta la diferencia en vez
+  de elegir el número conveniente.
+- Para decisiones grandes, contrastar con una prueba de incrementalidad —geo, holdout— antes que
+  discutir modelos.
+
+## Contenido y promesa
+
+Lo que se afirma en un anuncio o una landing es un compromiso del producto:
+
+- La promesa la valida quien es dueño del producto; el mensaje no crea capacidades.
+- Afirmaciones sobre resultados, seguridad, cumplimiento o comparaciones con competidores pasan por
+  legal antes de publicarse.
+- Un embudo que convierte porque promete de más traslada el costo a soporte y a la retención.
+
+## Privacidad
+
+- Minimizar datos personales: recolectar lo necesario para la decisión, no lo que sea posible.
+- Verificar base legal antes de construir audiencias, sincronizar listas o activar remarketing.
+- Coordinar con el especialista de privacidad cualquier transferencia a una plataforma externa.
+
+## Control de calidad
+
+Antes de entregar, verificar que la propuesta declara baseline, denominadores, ventana, regla de
+decisión, supuestos e incertidumbre; que el gasto tiene autorización registrada; que las métricas
+guardia existen; y que un resultado negativo también deja un aprendizaje utilizable.
+
+## Fundamento externo
+
+Los métodos de experimentación y medición se apoyan en fuentes primarias de estadística y en la
+documentación oficial de cada plataforma, con su versión y fecha. Un caso de éxito publicado por un
+proveedor es material comercial, no evidencia.

package/automatization/workflows/autobuild.js

@@ -2,10 +2,10 @@
 // Descubre proyecto, servicios y límites desde ops.config.json; no codifica rutas ni proveedores.
 export const meta = {
   name: 'autobuild',
-  description: 'Triage → Pick → Ready → Plan → Build → Review → Verify → QA → Commit → Done',
+  description: 'Triage → Pick → Cast → Ready → Plan → Build → Review → Verify → QA → Commit → Done',
   whenToUse: 'Ejecutar un hito aprobado con recuperación por WIP y checkpoint humano entre hitos.',
   phases: [
-    'Triage', 'Pick', 'Ready', 'Decompose', 'Plan', 'Critique', 'Build', 'Review',
+    'Triage', 'Pick', 'Cast', 'Ready', 'Decompose', 'Plan', 'Critique', 'Build', 'Review',
     'Verify', 'QA', 'Commit', 'Done', 'Closing',
   ].map((title) => ({ title, detail: `Fase ${title} del protocolo agnóstico` })),
 }
@@ -81,6 +81,31 @@ const COMMIT = {
     branch: { type: 'string' }, leftovers: { type: 'array', items: { type: 'string' } }, reason: { type: 'string' },
   },
 }
+// Dueño por defecto de cada fase. Es determinista: no hace falta preguntarle a un modelo quién
+// revisa la arquitectura o quién decide si la evidencia de calidad alcanza.
+const OWNERS = {
+  ready: 'product-manager',
+  plan: 'software-architect',
+  review: 'software-architect',
+  verify: 'qa-engineer',
+  qa: 'qa-engineer',
+  commit: 'release-manager',
+}
+
+const CAST_RULES = 'Elegís quién trabaja, no qué se hace. No inventes slugs: usá sólo los que ' +
+  'devuelve el CLI. Un cargo se suma por riesgo, plataforma o alcance, nunca por rutina.'
+
+const CAST = {
+  type: 'object', additionalProperties: false, required: ['build'],
+  properties: {
+    build: { type: 'string' },
+    review: { type: 'array', items: { type: 'string' } },
+    verify: { type: 'array', items: { type: 'string' } },
+    qa: { type: 'array', items: { type: 'string' } },
+    reason: { type: 'string' },
+  },
+}
+
 const CONTRACT = {
   type: 'object', additionalProperties: false,
   required: ['project', 'workspaceRoots', 'maxTaskHours', 'commitPerTask', 'humanCheckpoint', 'contracts'],
@@ -164,11 +189,41 @@ while (safety++ < 50) {
   const direct = planning.lane === 'directo'
   const lite = planning.lane === 'lite'
 
+  // Quién ejecuta cada fase. Los dueños por defecto son fijos y no gastan una llamada; los
+  // condicionales entran por riesgo, plataforma y alcance —nunca por rutina—, que es la misma
+  // regla que ya usa el team. En `directo` no hay condicionales: el lane baja ceremonia.
+  const cast = { ...OWNERS, build: '' }
+  if (!direct) {
+    phase('Cast')
+    const chosen = await read(
+      `${CAST_RULES}\n\nTarea ${task.id} en ${task.service}. Aceptación: ${task.acceptance}.\n` +
+      `Run "node tools/ops.js agents list ${ROOT} --json" and choose only from the slugs it lists.\n` +
+      `Elegí el cargo que implementa según la plataforma del servicio${lite ? '.' : ', y los cargos ' +
+      'condicionales que la superficie realmente justifica: seguridad si toca autenticación, permisos, ' +
+      'criptografía o datos sensibles; privacidad si toca datos personales; sre si toca disponibilidad, ' +
+      'límites o despliegue; ux si cambia una superficie que usa una persona; y el que corresponda a ' +
+      'datos o modelos si los toca. Dejá vacío lo que no aplique: sumar un cargo que no aporta es ruido ' +
+      'que diluye la revisión.'}`,
+      { schema: CAST, label: 'cast' },
+    )
+    if (chosen) {
+      cast.build = chosen.build || ''
+      for (const key of ['review', 'verify', 'qa']) {
+        cast[key] = [OWNERS[key], ...(lite ? [] : chosen[key] || [])].filter(Boolean).join(', ')
+      }
+      log(`Cargos: build=${cast.build || '(sin asignar)'} · review=${cast.review} · qa=${cast.qa}`)
+    }
+  }
+  const asRole = (slugs) => (slugs
+    ? `Actuá como ${slugs}, respetando el contrato de cada uno en su SKILL.md bajo agents/ y sus ` +
+      `límites: un cargo que no puede decidir solo, no decide solo.\n\n`
+    : '')
+
   if (!planning.wipActive) {
     phase('Ready')
     const ready = await read(
-      `As product manager, check concrete acceptance, dependencies and unresolved decisions for ${task.id}: ${task.acceptance}. ` +
-      `Clarify wording only; never expand scope.`, { schema: READY },
+      `${asRole(OWNERS.ready)}Check concrete acceptance, dependencies and unresolved decisions for ${task.id}: ` +
+      `${task.acceptance}. Clarify wording only; never expand scope.`, { schema: READY },
     )
     if (!ready.ready) {
       await write(`Register ${task.id} in ${HUMAN} with reason and an exact human action: ${ready.reason}.`)
@@ -192,7 +247,8 @@ while (safety++ < 50) {
 
     phase('Plan')
     let plan = await run(
-      `Inspect real code, repository instructions, neighbouring conventions, epic context and git status for ${task.id}. ` +
+      `${asRole(OWNERS.plan)}Inspect real code, repository instructions, neighbouring conventions, epic context ` +
+      `and git status for ${task.id}. ` +
       `Produce the smallest plan satisfying ${task.acceptance}. Planning files cannot be implementation files.`, { schema: PLAN },
     )
     if (!direct && !lite) {
@@ -209,13 +265,16 @@ while (safety++ < 50) {
     }
     await write(
       `Persist active WIP before code: task=${task.id}, hito=${JSON.stringify(task.hito)}, phase=Build, service=${task.service}, ` +
-      `acceptance=${JSON.stringify(task.acceptance)}, unchecked steps=${JSON.stringify(plan.steps)}. Follow the WIP contract exactly.`,
+      `acceptance=${JSON.stringify(task.acceptance)}, unchecked steps=${JSON.stringify(plan.steps)}. ` +
+      `Registrá además el reparto de cargos ${JSON.stringify(cast)} en las decisiones del WIP, para que ` +
+      `después se pueda auditar quién revisó qué. Follow the WIP contract exactly.`,
     )
   }
 
   phase('Build')
   const build = await run(
-    `Implement only ${task.id} inside ${task.service}. Resume at the first pending WIP step; verify completed steps on disk ` +
+    `${asRole(cast.build)}Implement only ${task.id} inside ${task.service}. Resume at the first pending WIP ` +
+    `step; verify completed steps on disk ` +
     `and tick each successful step. Use RED/GREEN for behavior. Acceptance: ${task.acceptance}.`, {
       schema: { type: 'object', required: ['completed', 'summary'], properties: {
         completed: { type: 'boolean' }, summary: { type: 'string' }, blockers: { type: 'array', items: { type: 'string' } },
@@ -227,7 +286,8 @@ while (safety++ < 50) {
   if (!direct) {
     phase('Review')
     let review = await run(
-      `Review the actual diff for acceptance, regressions, security, architecture, generated code, migrations and accidental scope.`,
+      `${asRole(cast.review)}Review the actual diff for acceptance, regressions, security, architecture, ` +
+      `generated code, migrations and accidental scope. Cada cargo revisa su dominio, no el ajeno.`,
       { schema: DECISION },
     )
     if (!review.approved) {
@@ -239,14 +299,15 @@ while (safety++ < 50) {
 
   phase('Verify')
   const verified = await run(
-    `Discover and run the real gates for ${task.service}: repository instructions first, then applicable test, lint, ` +
+    `${asRole(cast.verify)}Discover and run the real gates for ${task.service}: repository instructions first, ` +
+    `then applicable test, lint, ` +
     `typecheck and build. Read actual exit codes. passed=true needs commands and no task-caused regression.`, { schema: VERIFY },
   )
   if (!verified.passed || !verified.commands.length) return stop('verify-failed', verified.details)
 
   phase('QA')
   const qa = await run(
-    `${direct || lite ? 'Perform the cheapest real acceptance check' : 'Exercise real consumer-visible behavior'} for ` +
+    `${asRole(cast.qa)}${direct || lite ? 'Perform the cheapest real acceptance check' : 'Exercise real consumer-visible behavior'} for ` +
     `${task.id}. Unit tests alone are not QA. Start only minimum runtime and tear it down. Acceptance: ${task.acceptance}.`,
     { schema: QA },
   )
@@ -254,7 +315,8 @@ while (safety++ < 50) {
 
   phase('Commit')
   const commit = contract.commitPerTask ? await run(
-    `Find the git repo owning ${task.service}, inspect status/diff, stage explicit task files, create one Conventional ` +
+    `${asRole(OWNERS.commit)}Find the git repo owning ${task.service}, inspect status/diff, stage explicit task ` +
+    `files, create one Conventional ` +
     `Commit with footer "Task: ${task.id}", then verify log/status. Never amend or push; report unrelated leftovers.`,
     { schema: COMMIT },
   ) : { committed: true, reason: 'runner.commitPerTask is disabled' }

package/automatization/workflows/team.js

@@ -20,14 +20,27 @@ const P = `${ROOT}/planning`
 const ROADMAP = `${P}/roadmap`
 const HUMAN = `${P}/HUMAN_ACTIONS.md`
 const INBOX = `${P}/INBOX.md`
+const REPORTS = `${P}/reports`
 
-const TEAM = String(args && args.team || process.env.OPS_TEAM || 'product-development')
-const INTENT = String(args && args.intent || process.env.OPS_INTENT || '').trim()
+// Tres formas de invocarlo, porque escribir JSON en un slash command no es razonable:
+//
+//   /team quiero cobrar con tarjeta                    equipo por defecto
+//   /team feasibility-review: quiero cobrar con tarjeta   equipo elegido por prefijo
+//   /team {"team": "acme-soporte", "intent": "..."}    argumentos estructurados
+//
+// El prefijo se toma como candidato y se confirma más abajo contra los equipos que existen: si no es
+// uno, el texto completo era la intención y nadie tuvo que aprenderse una sintaxis.
+const input = typeof args === 'string' ? { intent: args } : (args || {})
+const raw = String(input.intent || process.env.OPS_INTENT || '').trim()
+const prefix = raw.match(/^([a-z][a-z0-9-]*)\s*:\s*(.+)$/s)
+const CANDIDATE = String(input.team || process.env.OPS_TEAM || (prefix ? prefix[1] : '') || 'product-development')
+const INTENT = (input.team || !prefix ? raw : prefix[2]).trim()
 
 const MANIFEST = {
   type: 'object', additionalProperties: false, required: ['name', 'purpose', 'stages', 'guardrails'],
   properties: {
     name: { type: 'string' }, purpose: { type: 'string' },
+    outcome: { type: 'string', enum: ['epic', 'report'] },
     entryAgent: { type: 'string' }, facilitator: { type: 'string' },
     guardrails: { type: 'array', items: { type: 'string' } },
     owners: { type: 'array', items: { type: 'object', additionalProperties: false, properties: {
@@ -35,6 +48,7 @@ const MANIFEST = {
     } } },
     stages: { type: 'array', items: { type: 'object', additionalProperties: false, properties: {
       id: { type: 'string' }, agent: { type: 'string' }, exitGate: { type: 'string' },
+      phase: { type: 'string', enum: ['discovery', 'delivery'] },
       produces: { type: 'array', items: { type: 'string' } },
     } } },
   },
@@ -75,10 +89,27 @@ const BASE = `Nunca inventes clientes, métricas, restricciones ni decisiones. N
   `haría falta averiguar. No promuevas trabajo al BACKLOG, no escribas en sistemas externos y no ` +
   `declares validado nada sin evidencia observable.`
 
+const resolved = await agent(
+  `${BASE}\n\nRun "node tools/ops.js team list" from ${ROOT}. Report whether "${CANDIDATE}" is one of ` +
+  `the slugs it printed, and the full list. Do not guess: report only what the command printed.`,
+  { schema: { type: 'object', required: ['exists', 'teams'], properties: {
+    exists: { type: 'boolean' }, teams: { type: 'array', items: { type: 'string' } },
+  } }, label: 'team-resolve' },
+)
+if (!resolved) return stop('teams-unavailable', 'no se pudo listar los equipos')
+if (!resolved.exists && (input.team || process.env.OPS_TEAM)) {
+  return stop('equipo-inexistente', `${CANDIDATE} no existe. Disponibles: ${resolved.teams.join(', ')}`)
+}
+// El prefijo era parte de la intención, no un equipo: se recompone y sigue con el equipo por defecto.
+const TEAM = resolved.exists ? CANDIDATE : 'product-development'
+const GOAL = resolved.exists ? INTENT : raw
+if (!resolved.exists && prefix) log(`"${CANDIDATE}" no es un equipo: se toma el texto completo como intención.`)
+
 const contract = await agent(
   `${BASE}\n\nRun "node tools/ops.js team show ${TEAM} --json" from ${ROOT} and report only what it ` +
-  `printed: name, purpose, entryAgent, facilitator, guardrails, the stages with id, agent, produces ` +
-  `and exitGate, and decisionOwners flattened into owners as domain/agent pairs. Then read ` +
+  `printed: name, purpose, outcome, entryAgent, facilitator, guardrails, the stages with id, phase, ` +
+  `agent, ` +
+  `produces and exitGate, and decisionOwners flattened into owners as domain/agent pairs. Then read ` +
   `${ROOT}/organization/ and report nothing from it: it is context for later stages, not output.`,
   { schema: MANIFEST, label: 'team-contract' },
 )
@@ -88,13 +119,17 @@ const owners = (contract.owners || []).map((owner) => `${owner.domain}=${owner.a
 const RULES = `${BASE}\n\nEquipo ${contract.name}: ${contract.purpose}\n` +
   `Guardrails: ${contract.guardrails.join(' ')}\n` +
   `${owners ? `Dueños de decisión: ${owners}. Ningún otro cargo resuelve en su dominio.\n` : ''}` +
-  `Contexto de la empresa en ${ROOT}/organization/. Intención a evaluar: ${INTENT}`
+  `Contexto de la empresa en ${ROOT}/organization/. Intención a evaluar: ${GOAL}`
 
 phase('Stages')
 
 const handoffs = []
 const blocked = []
-for (const stage of contract.stages) {
+// Sólo descubrimiento: este recorrido propone trabajo, no lo ejecuta. Las etapas de entrega las
+// corre `autobuild`, y sólo después de que una persona promueva la épica al BACKLOG.
+const discovery = contract.stages.filter((stage) => stage.phase === 'discovery')
+if (!discovery.length) return stop('sin-descubrimiento', `${TEAM} no declara etapas de discovery`)
+for (const stage of discovery) {
   const previous = handoffs.length
     ? `Handoffs previos:\n${handoffs.map((entry) => `- ${entry.id}: ${entry.findings}`).join('\n')}`
     : 'Sos la primera etapa: no hay handoff previo.'
@@ -129,6 +164,24 @@ if (blocked.length) {
 
 phase('Draft')
 
+// Un recorrido que registra lo aprendido no propone trabajo: deja el informe y las tareas de
+// seguimiento en el INBOX, donde una persona decide si alguna merece convertirse en épica.
+if (contract.outcome === 'report') {
+  const report = await agent(
+    `${RULES}\n\nHandoffs completos:\n${JSON.stringify(handoffs)}\n\nEscribí el informe en ${REPORTS} como ` +
+    `<AAAA-MM-DD>-<slug>.md: qué pasó, qué se sabe con evidencia, qué se supone, qué se decidió y qué ` +
+    `queda abierto. Separá causa de síntoma y no atribuyas responsabilidad a personas. Registrá cada ` +
+    `seguimiento en la sección Lecciones de ${INBOX}, sin promoverlo, y toda acción que requiera una ` +
+    `persona en ${HUMAN}.`,
+    { schema: { type: 'object', required: ['file', 'followUps'], properties: {
+      file: { type: 'string' }, followUps: { type: 'integer' }, summary: { type: 'string' },
+    } }, label: 'report-write' },
+  )
+  if (!report) return stop('report-unavailable', 'el informe no devolvió resultado')
+  log(`Informe en ${report.file}. ${report.followUps} seguimiento(s) en el INBOX, sin promover.`)
+  return finish({ team: TEAM, stages: handoffs.length, report: report.file, promoted: false })
+}
+
 const epic = await agent(
   `${RULES}\n\nHandoffs completos:\n${JSON.stringify(handoffs)}\n\nComo product-manager, decidí si la ` +
   `intención es viable con la evidencia reunida. Si lo es, redactá la épica: título, slug en ` +

package/engine/cli/ops.js

@@ -506,8 +506,11 @@ function upgrade(dir) {
   if (changed.length && !force) {
     for (const file of changed) console.error(`✗ ${file}`)
     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) del runtime fueron editados y se perderían.\n\n` +
+      '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.\n' +
+      'Si el cambio ya no te sirve, repetí con --force para descartarlo.',
     )
   }
 
@@ -532,6 +535,9 @@ function upgrade(dir) {
   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}`)
   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 +553,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/teams/registry.js

@@ -5,6 +5,10 @@ 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.
@@ -40,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')
@@ -58,6 +63,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 +74,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')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingeniomaps/cauce",
-  "version": "0.2.0",
+  "version": "0.3.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.