@ingeniomaps/cauce 0.2.0 → 0.4.0

package/agents/roles/system/technical-program-manager/SKILL.md

@@ -10,6 +10,8 @@ Crear claridad y flujo entre equipos para obtener un outcome técnico que los co
 ## Construir contexto
 
 1. Leer `AGENTS.md`, `ops.config.json`, `organization/`, estrategia, roadmap, arquitectura, contratos, decisiones, SLO, políticas y programas previos.
+   Leer también `organization/roles/technical-program-manager.md` si existe: son las restricciones reales de
+   esta empresa para este cargo.
 2. Definir outcome, beneficios, sponsor, owners, usuarios, alcance/no alcance, restricciones, autoridad, horizonte y criterios de cierre.
 3. Mapear workstreams, sistemas, interfaces, dependencias, secuencia, ambientes, proveedores, equipos, skills y capacidad disponible.
 4. Obtener evidencia de baseline, progreso, calidad, riesgos, incidentes, costos y adopción; distinguir hechos, forecast, supuesto y decisión.

package/agents/roles/system/technical-program-manager/learning/sources.yaml

@@ -6,8 +6,9 @@ rules:
   require_corroboration_for_major_change: true
   reject_unsourced_claims: true
   automatic_apply: false
+# El contexto de la empresa no es una fuente de la profesión: vive en
+# organization/roles/technical-program-manager.md dentro de cada instalación.
 sources:
-  - {name: Company strategy programs architecture roadmaps decisions policies and approved metrics, url: "local://technical-program-context", tier: company-primary, topics: [strategy, programs, architecture, decisions, metrics]}
   - {name: ISO 21503 programme management, url: "https://www.iso.org/cms/%20render/live/en/sites/isoorg/contents/data/standard/08/28/82868.html", tier: standards-primary, topics: [programme, roles, responsibilities, practices]}
   - {name: ISO 21502 project management, url: "https://committee.iso.org/sites/tc258/home/projects/published/iso-21502.html", tier: standards-primary, topics: [project, adaptive, predictive, hybrid]}
   - {name: ISO 31000 risk management, url: "https://www.iso.org/standard/65694.html", tier: standards-primary, topics: [risk, principles, process]}

package/agents/roles/system/technical-writer/SKILL.md

@@ -10,6 +10,8 @@ Ayudar a una audiencia concreta a aprender, completar una tarea, consultar una i
 ## Construir contexto
 
 1. Leer `AGENTS.md`, `ops.config.json`, guías editoriales, glosario, repositorios y documentación existente.
+   Leer también `organization/roles/technical-writer.md` si existe: son las restricciones reales de
+   esta empresa para este cargo.
 2. Identificar audiencia, objetivo, conocimiento previo, entorno, versión, idioma, canal, owner, sensibilidad y fecha de revisión.
 3. Ubicar fuentes autorizadas: interfaz ejecutable, especificación, tests, configuración, ADR, telemetría, SME y release aprobado.
 4. Clasificar la necesidad como tutorial, guía práctica, referencia o explicación; separar tipos cuando persigan necesidades distintas.

package/agents/roles/system/technical-writer/learning/sources.yaml

@@ -6,11 +6,9 @@ rules:
   require_corroboration_for_major_change: true
   reject_unsourced_claims: true
   automatic_apply: false
+# El contexto de la empresa no es una fuente de la profesión: vive en
+# organization/roles/technical-writer.md dentro de cada instalación.
 sources:
-  - name: Company style glossary product code specs tests and documentation analytics
-    url: local://technical-writing-context
-    tier: company-primary
-    topics: [style, terminology, product, api, operations, docs, feedback]
   - name: Google developer documentation style guide
     url: https://developers.google.com/style
     tier: professional-primary

package/agents/roles/system/ui-designer/SKILL.md

@@ -11,6 +11,8 @@ Actuar como responsable del lenguaje visual de la interfaz y su aplicación sist
 
 1. Localizar la raíz operativa del proyecto.
 2. Leer `AGENTS.md`, `ops.config.json` y `organization/README.md` si existen.
+   Leer también `organization/roles/ui-designer.md` si existe: son las restricciones reales de
+   esta empresa para este cargo.
 3. Leer `organization/company.md`, `organization/product.md` y cualquier guía de marca o design system autorizado.
 4. Leer el flujo y criterios entregados por UX Designer, además de evidencia relevante y restricciones confirmadas.
 5. Inspeccionar componentes, tokens y convenciones existentes antes de crear otros. Separar hechos, restricciones y supuestos. No inventar marca, usuarios, métricas ni evidencia observable.

package/agents/roles/system/ui-designer/learning/sources.yaml

@@ -5,6 +5,8 @@ rules:
   reject_unsourced_claims: true
   automatic_apply: false
 
+# El contexto de la empresa no es una fuente de la profesión: vive en
+# organization/roles/ui-designer.md dentro de cada instalación.
 sources:
   - name: W3C Web Accessibility Initiative
     url: https://www.w3.org/WAI/

package/agents/roles/system/user-researcher/SKILL.md

@@ -11,6 +11,8 @@ Actuar como responsable de producir evidencia confiable sobre usuarios. Explicar
 
 1. Localizar la raíz operativa del proyecto.
 2. Leer `AGENTS.md`, `ops.config.json` y `organization/README.md` si existen.
+   Leer también `organization/roles/user-researcher.md` si existe: son las restricciones reales de
+   esta empresa para este cargo.
 3. Leer `organization/company.md` y `organization/product.md`. Consultar políticas de privacidad, seguridad, accesibilidad y salvaguarda cuando apliquen.
 4. Leer sólo el estado de `planning/` necesario para comprender la decisión que la investigación debe informar.
 5. Clasificar cada entrada como dato original, observación, interpretación, inferencia, supuesto o pregunta.

package/agents/roles/system/user-researcher/learning/sources.yaml

@@ -5,6 +5,8 @@ rules:
   reject_unsourced_claims: true
   automatic_apply: false
 
+# El contexto de la empresa no es una fuente de la profesión: vive en
+# organization/roles/user-researcher.md dentro de cada instalación.
 sources:
   - name: GOV.UK User Research
     url: https://www.gov.uk/service-manual/user-research

package/agents/roles/system/ux-designer/SKILL.md

@@ -11,6 +11,8 @@ Actuar como responsable de la estructura y comportamiento de la experiencia. Red
 
 1. Localizar la raíz operativa del proyecto.
 2. Leer `AGENTS.md`, `ops.config.json` y `organization/README.md` si existen.
+   Leer también `organization/roles/ux-designer.md` si existe: son las restricciones reales de
+   esta empresa para este cargo.
 3. Leer `organization/company.md`, `organization/product.md` y las reglas de diseño o accesibilidad disponibles.
 4. Consultar evidencia del User Researcher y decisiones aprobadas del Product Manager. Leer el estado de `planning/` necesario.
 5. Separar hechos, evidencia, restricciones, supuestos y decisiones pendientes. No inventar investigación, usuarios, métricas ni evidencia observable.

package/agents/roles/system/ux-designer/learning/sources.yaml

@@ -5,6 +5,8 @@ rules:
   reject_unsourced_claims: true
   automatic_apply: false
 
+# El contexto de la empresa no es una fuente de la profesión: vive en
+# organization/roles/ux-designer.md dentro de cada instalación.
 sources:
   - name: W3C Web Accessibility Initiative
     url: https://www.w3.org/WAI/

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/agents/catalog.js

@@ -1,15 +1,18 @@
 'use strict'
 
 // Resolución única del catálogo de cargos. La usan el ciclo de aprendizaje, la validación de
-// equipos y la instalación en runners: tres lugares que antes resolvían por su cuenta.
+// equipos y la instalación en runners.
 //
-// Cada tipo separa lo del toolkit de lo del proyecto igual que el resto de las colecciones:
+// El catálogo se reparte en dos lugares según de quién es cada cosa:
 //
-//   agents/<tipo>/system/<slug>/SKILL.md   viene con Cauce y se reemplaza al actualizar
-//   agents/<tipo>/<slug>/SKILL.md          es del proyecto y manda sobre el anterior
+//   <paquete>/agents/<tipo>/system/<slug>/   viene con Cauce, se actualiza con la dependencia
+//   <proyecto>/agents/<tipo>/<slug>/         es de la empresa y manda sobre el anterior
 //
-// Un slug repetido entre tipos distintos sigue siendo ambiguo: ahí no hay ninguna regla que
-// diga cuál gana, y elegir en silencio sería peor que fallar.
+// Los cargos del sistema no se copian al proyecto: evolucionan como profesión y esa evolución es
+// la misma para todos. Lo que sí es de cada empresa —su contexto— vive en `organization/roles/`.
+//
+// Un slug repetido entre tipos distintos sigue siendo ambiguo: ahí no hay ninguna regla que diga
+// cuál gana, y elegir en silencio sería peor que fallar.
 
 const fs = require('node:fs')
 const path = require('node:path')
@@ -24,44 +27,66 @@ function directories(dir) {
   } catch { return [] }
 }
 
+// Dónde está el catálogo que trae Cauce. Se reconoce por tener `roles/system/`, que es el espacio
+// del sistema y no algo que un proyecto deba crear.
+function systemCatalog(root) {
+  return require('../core/ownership').packageDir(root, 'agents')
+}
+
+function projectCatalog(root) {
+  return path.join(root, 'agents')
+}
+
 function types(root) {
-  return directories(path.join(root, 'agents'))
+  const own = directories(projectCatalog(root))
+  const system = directories(systemCatalog(root) || path.join(root, '\0'))
+  return [...new Set([...own, ...system])]
 }
 
-// Todos los cargos visibles: los del proyecto ocultan a los del sistema con el mismo slug.
+// Todos los cargos visibles: los de la empresa ocultan a los del sistema con el mismo slug.
 function list(root) {
-  const catalog = path.join(root, 'agents')
+  const system = systemCatalog(root)
   const found = new Map()
   for (const type of types(root)) {
-    const base = path.join(catalog, type)
-    // El sistema primero para que el proyecto lo sobrescriba al pasar por encima.
-    for (const [source, system] of [[path.join(base, 'system'), true], [base, false]]) {
+    // El sistema primero, para que el proyecto lo sobrescriba al pasar por encima.
+    const sources = [
+      system ? [path.join(system, type, 'system'), true] : null,
+      [path.join(projectCatalog(root), type), false],
+    ].filter(Boolean)
+    for (const [source, fromSystem] of sources) {
       for (const slug of directories(source)) {
         if (slug === 'system' || !SLUG.test(slug)) continue
         const dir = path.join(source, slug)
         if (!fs.existsSync(path.join(dir, 'SKILL.md'))) continue
-        found.set(slug, { slug, type, dir, system })
+        found.set(slug, { slug, type, dir, system: fromSystem })
       }
     }
   }
   return [...found.values()].sort((left, right) => left.slug.localeCompare(right.slug))
 }
 
-function resolve(root, slug) {
+function find(root, slug) {
   if (!SLUG.test(slug || '')) throw new Error(`agente inválido: ${slug || '(vacío)'}`)
+  const system = systemCatalog(root)
   const matches = []
   for (const type of types(root)) {
-    const own = path.join(root, 'agents', type, slug)
-    const system = path.join(root, 'agents', type, 'system', slug)
+    const own = path.join(projectCatalog(root), type, slug)
+    const shipped = system ? path.join(system, type, 'system', slug) : ''
     // Dentro de un tipo la precedencia está definida; entre tipos no, y por eso se acumulan.
-    if (fs.existsSync(path.join(own, 'SKILL.md'))) matches.push(own)
-    else if (fs.existsSync(path.join(system, 'SKILL.md'))) matches.push(system)
+    if (fs.existsSync(path.join(own, 'SKILL.md'))) matches.push({ dir: own, system: false })
+    else if (shipped && fs.existsSync(path.join(shipped, 'SKILL.md'))) {
+      matches.push({ dir: shipped, system: true })
+    }
   }
   if (!matches.length) throw new Error(`no existe agents/<tipo>/${slug}/SKILL.md`)
   if (matches.length > 1) {
-    throw new Error(`agente ambiguo ${slug}: ${matches.map((dir) => path.relative(root, dir)).join(', ')}`)
+    throw new Error(`agente ambiguo ${slug}: ${matches.map((entry) => entry.dir).join(', ')}`)
   }
   return matches[0]
 }
 
-module.exports = { list, resolve, types }
+function resolve(root, slug) {
+  return find(root, slug).dir
+}
+
+module.exports = { find, list, projectCatalog, resolve, systemCatalog, types }

package/engine/agents/learning.js

@@ -19,11 +19,28 @@ function agentRoot(root, agent) {
   return catalog.resolve(root, agent)
 }
 
+// Un cargo del sistema vive dentro del paquete: escribir ahí perdería el informe en el próximo
+// `npm ci`, y además duplicaría en cada empresa una investigación sobre la profesión que se hace
+// mejor una sola vez. Lo que sí es de esta empresa es su contexto, y ese tiene otro lugar.
+function assertWritable(root, agent) {
+  const found = catalog.find(root, agent)
+  // Lo que decide no es si el cargo es del sistema, sino si vive dentro de este repositorio. En el
+  // toolkit los cargos del sistema son propios y se aprenden acá; en una instancia vienen del
+  // paquete, y escribir ahí se pierde en el próximo `npm ci` o en el próximo upgrade.
+  const own = path.resolve(catalog.projectCatalog(root))
+  if (path.resolve(found.dir).startsWith(`${own}${path.sep}`)) return found.dir
+  throw new Error(
+    `${agent} es un cargo que trae Cauce y su aprendizaje se hace en el toolkit, no acá.\n` +
+    `  Lo que este cargo debe saber de esta empresa va en organization/roles/${agent}.md.\n` +
+    `  Para tener una versión propia del cargo, escribila en agents/roles/${agent}/.`,
+  )
+}
+
 function isoDate(now = new Date()) { return now.toISOString().slice(0, 10) }
 function month(now = new Date()) { return now.toISOString().slice(0, 7) }
 
 function prepareReport(root, agent, now = new Date()) {
-  const reports = path.join(agentRoot(root, agent), 'learning', 'reports')
+  const reports = path.join(assertWritable(root, agent), 'learning', 'reports')
   const file = path.join(reports, `${isoDate(now)}.md`)
   fs.mkdirSync(reports, { recursive: true })
   if (fs.existsSync(file)) return { file, created: false }
@@ -51,7 +68,7 @@ status: draft
 }
 
 function prepareProposal(root, agent, now = new Date()) {
-  const target = agentRoot(root, agent)
+  const target = assertWritable(root, agent)
   const proposalDir = path.join(target, 'learning', 'proposals')
   const file = path.join(proposalDir, `${month(now)}.md`)
   fs.mkdirSync(proposalDir, { recursive: true })