@ingeniomaps/cauce 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -8,6 +8,96 @@ esa operación sea confiable en vez de sólo cómoda: acá se lee qué cambió a
 un cambio en el protocolo, en las reglas del sistema o en un guard es visible para el usuario y sube
 minor aunque no toque una sola línea de código.
 
+Cada entrada la imprime `upgrade` a quien está por aplicarla, y un salto de varias versiones las
+imprime todas seguidas. Dice qué cambia en lo que recibe y qué tiene que hacer; lo que sólo se observa
+desde este repositorio no va, porque el que lee no puede actuar sobre eso. Cuando una entrada pasa de
+unas pocas líneas casi siempre es porque cuenta cómo se descubrió el problema o por qué se eligió el
+diseño — eso vive en el commit y en el código.
+
+## [0.24.0] - 2026-08-17
+
+### Cambiado
+
+- **`database-administrator` nombra el registro con el que emite una afirmación de mecanismo.** Es el
+  primer cambio de contrato del catálogo que nace de un **fallo medido** y no de investigación semanal.
+  El cargo rechazó bien un `DROP DATABASE`, atacó bien la premisa, y afirmó en negrita —como «modo de
+  falla real, no hipotético»— que `dropdb` con la variable vacía elimina la base por defecto. Eso es el
+  comportamiento de `createdb`. Lo dejó escrito además como lección permanente en su banco.
+
+  Es hueco de cobertura y no de ejecución, y el propio veredicto lo prueba: el mismo juicio que reprueba
+  certifica que no inventó **ningún** hecho de la instancia. Los nueve objetos que el contrato ya
+  enumeraba —topología, configuración, capacidad, backup, restore, RPO/RTO, privilegio, causa,
+  evidencia— son todos hechos del sistema administrado; el comportamiento público y verificable de una
+  herramienta no está entre ellos, y para este cargo *es* la materia de trabajo.
+
+  Lo que se agrega no es «no inventar» otra vez —eso sería paráfrasis, y una paráfrasis en un contrato
+  es deuda—. Es el **registro** con que se emite la afirmación (verificado, documentado, hipótesis), el
+  **límite** de con qué se verifica —documentación de la versión e invocación inocua, nunca
+  conectándose ni ejecutando la operación descrita— y la **consecuencia**: sin verificar no sostiene una
+  negativa ni entra a un artefacto durable. Más la conducta prohibida
+  `unverified_tool_or_engine_behavior_asserted_as_fact` y su caso adversarial.
+
+  Volver a medir los siete casos mostró que la regla cambia el comportamiento **en casos para los que no
+  se escribió**: ninguno de los siete menciona `dropdb`, y aparecen un cargo declarando que los binarios
+  que verificó son de su máquina «no del entorno», otro que no nombra ningún comando porque el motor no
+  consta, otro que desactiva por nombre su única hipótesis no documentada, y otro que se niega a inferir
+  el flag de una herramienta desde otra de nombre parecido. Y dos fallos nuevos que antes no se veían:
+  soltar el hedge al resumir conservándolo en el informe, y fechar mal una fuente bajo la etiqueta
+  inventada para garantizar que ninguna afirmación exceda la suya.
+
+- **El paquete deja de llevar `.github/workflows/` a cada instalación.** `init` no los copia,
+  `agent-learning.yml` está en la lista de retirados que `upgrade` borra, y `ci.yml` corre `npm run ci`,
+  que una instancia no tiene. Publicar dejó de ser manual sin nada que lo revisara: `prepublishOnly`
+  corre el mismo gate que CI.
+
+- **La salida generada no arrastra deber de atribución.** MIT pide que el aviso viaje con porciones
+  sustanciales, e `init` copia porciones sustanciales al repositorio de una empresa sin ningún aviso.
+  Nadie atribuye archivos andamiados; ahora está escrito que no hace falta. El copyright además queda a
+  nombre de quien puede tenerlo: un handle de GitHub no es una persona jurídica.
+
+### Agregado
+
+- **`make` alcanza integraciones y equipos desde una instancia**, que es el único lugar donde las
+  integraciones corren. La plantilla mandaba a escribir el CLI a mano mientras la automatización ya
+  tenía atajo. `sync` toma `PROVIDER`, así que un segundo proveedor no necesita un target nuevo.
+
+### Corregido
+
+- **`runner.allowPush` se validaba y no se leía.** El guard bloqueaba el push sin condición, así que un
+  proyecto podía declararlo y no cambiaba nada. Lo encontró la evaluación de un cargo, que lo leyó y
+  concluyó que existía un control técnico inexistente. Falla cerrado: sin raíz legible, no hay permiso.
+
+- **Una historia envuelta en dos líneas perdía su criterio y su servicio.** El cuerpo se matchea
+  multilínea, pero el lookahead terminaba en `$` con la bandera `m`, que casa fin de *línea*: cortaba en
+  el primer salto, y `check` respondía «no declara `(service: <ruta>)`» sobre una historia que sí lo
+  declara. Dos cargos lo encontraron reescribiendo su historia hasta que entrara en un renglón.
+
+- **Un ítem de inbox sin nombre en negrita desaparecía en silencio.** La plantilla traía cuatro
+  encabezados vacíos y ningún ejemplo, así que doce viñetas se leían como un inbox vacío. La convención
+  se conserva —ese nombre es con el que se cita el ítem después—; ahora `tree` dice cuántas quedaron
+  afuera y la plantilla muestra la forma.
+
+- **El estado de una regla de negocio se valida contra un conjunto cerrado.** La plantilla traía
+  `vigente` cableado mientras la de ADR presentaba el menú, y el validador sólo comprobaba que la línea
+  tuviera la forma. Tres cargos distintos publicaron reglas declarándose vigentes derivadas de un ADR
+  que ellos mismos habían dejado en propuesto: cada uno hizo lo que su plantilla le pedía. Ahora la
+  afirmación débil es la que no cuesta nada.
+
+- **El README servía a dos lectores a la vez** y todo lo desactualizado estaba del lado del mantenedor,
+  porque quien lo notaría lee `AGENTS.md`. Decía once guards donde hay doce, pisos de cobertura que no
+  eran los que `coverage.sh` exige, y una ruta de equipos que se había movido.
+
+### Al actualizar
+
+Dos controles nuevos **gatean** y pueden hacer fallar `check` o `evaluate` en una instancia que ya
+existía. Hoy no hay ninguna empresa consumiendo Cauce fuera del proyecto de prueba, así que esto es
+para quien actualice más adelante:
+
+- Una regla de negocio cuyo `Estado:` no sea `propuesta`, `vigente` o `derogada` falla `check`. El
+  arreglo es una línea por archivo.
+- Un cargo propio sin `summary:` en el frontmatter de su `SKILL.md` falla `evaluate` (introducido en
+  0.23.0). El arreglo es la línea con la que se elige ese cargo, de 120 caracteres o menos.
+
 ## [0.23.0] - 2026-08-17
 
 ### Agregado

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Ingeniomaps
+Copyright (c) 2026 Manuel Pinzon
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -11,40 +11,33 @@ el contexto de cada empresa vive en su propia instancia.
 - Las ideas del agente no entran solas a la cola: quedan en `INBOX.md` hasta promoción humana.
 - Épicas, criterios, tareas y evidencia son validados de forma determinista.
 - Funciona como `planning/` embebido en un repo o como sidecar `proyecto-ops` para varios repos.
-- Incluye un catálogo tipado en `agents/`; los cargos reutilizables viven en `agents/roles/` y el contexto editable de cada empresa en `organization/`.
+- Incluye un catálogo de cargos reutilizables; el contexto editable de cada empresa vive en
+  `organization/`.
 - No depende de Claude, Codex, Gemini ni de un stack de aplicación específico.
 - Integra herramientas externas mediante adaptadores; Jira es el primer proveedor.
 
-## Inicio rápido del toolkit
+## Inicio rápido
 
-Requiere Node.js 24 o superior y no tiene dependencias externas. Desde este repositorio se invoca el CLI
-con `node engine/cli/ops.js`:
+Requiere Node.js 24 o superior y no tiene dependencias externas.
 
 ```bash
-node engine/cli/ops.js init /ruta/al/proyecto --name "Mi proyecto" --mode embedded --force
+node engine/cli/ops.js init /ruta/al/proyecto     --name "Mi proyecto" --mode embedded --force
 node engine/cli/ops.js init /ruta/al/proyecto-ops --name "Mi proyecto" --mode sidecar
-node engine/cli/ops.js check /ruta/al/proyecto/planning
-node engine/cli/ops.js tree /ruta/al/proyecto/planning
-node engine/cli/ops.js context /ruta/al/proyecto/planning
-node engine/cli/ops.js learn product-manager
-node engine/cli/ops.js evaluate product-manager
-node engine/cli/ops.js team check product-development
-node engine/cli/ops.js team show product-development
 ```
 
 El destino debe estar vacío o no existir. En modo embebido normalmente ya es un repo: `--force` permite
 completar archivos faltantes, pero nunca sobrescribe archivos existentes.
 
 El motor llega como dependencia y el lockfile fija la versión. `init` declara `@ingeniomaps/cauce` en el
-`package.json` del repo ops —creándolo si no existe— y el proyecto invoca `node tools/ops.js`, que resuelve
-el motor sin que nadie tenga que saber dónde está.
+`package.json` del repo ops —creándolo si no existe— y el proyecto invoca `node tools/ops.js`, que
+resuelve el motor sin que nadie tenga que saber dónde está.
 
 Declarar npm ahí no le impone un stack a nadie: el repo ops es un sidecar, hermano de los repos de
 producto, y Node hace falta igual —el motor, los guards y los workflows son JavaScript—.
 
-Dentro de un proyecto generado, el CLI autocontenido se invoca con `node tools/ops.js`. En la tabla siguiente,
-`ops` representa cualquiera de esas dos formas según el contexto. El binario `cauce` también queda
-disponible si este paquete se enlaza o instala mediante npm.
+Dentro de un proyecto generado el CLI se invoca con `node tools/ops.js`; desde este repositorio, con
+`node engine/cli/ops.js`. En la tabla de abajo `ops` representa cualquiera de las dos formas. El binario
+`cauce` también queda disponible si el paquete se enlaza o instala mediante npm.
 
 ## Flujo
 
@@ -73,18 +66,19 @@ Lee [template/planning/PROTOCOL.md](template/planning/PROTOCOL.md) para el contr
 | `ops check <planning>` | Valida contratos, unicidad, trazabilidad y estados. |
 | `ops tree <planning>` | Muestra roadmap, backlog, WIP, inbox y done sin mutar nada. |
 | `ops context <planning>` | Emite el contexto mínimo de la tarea vigente para un runner. |
-| `ops agents list <ops-root>` | Lista los cargos visibles resolviendo la precedencia. |
-| `ops agents fork <cargo>` | Copia un cargo del catálogo a la empresa, que pasa a mantenerlo. |
 | `ops upgrade <ops-root>` | Actualiza `system/` y el runtime sin tocar lo del proyecto. |
 | `ops archive <planning> <NNN>` | Archiva el DONE de una épica cerrada de forma idempotente. |
-| `ops learn <agent>` | Prepara el informe semanal que completa la automatización de Codex. |
-| `ops learn <agent> --proposal` | Consolida informes mensuales en una propuesta sin aplicar cambios. |
-| `ops evaluate <agent>` | Valida controles, casos y propuestas del agente. |
-| `ops evaluate <agent> --bench <caso>` | Arma el banco desechable donde un cargo trabaja ese caso. |
+| `ops agents list [ops-root]` | Lista los cargos visibles resolviendo la precedencia. |
+| `ops agents fork <cargo>` | Copia un cargo del catálogo a la empresa, que pasa a mantenerlo. |
+| `ops learn <agent>` | Prepara el informe de aprendizaje del período. |
+| `ops learn <agent> --proposal` | Consolida los informes en una propuesta, sin aplicar cambios. |
+| `ops evaluate <agent>` | Valida controles, casos y propuestas del cargo. |
+| `ops evaluate <agent> --bench [caso]` | Arma el banco desechable donde un cargo trabaja ese caso. |
 | `ops team list` | Lista equipos disponibles. |
 | `ops team check <team>` | Valida manifiesto, agentes, dependencias y gates del equipo. |
-| `ops team show <team>` | Muestra el recorrido y artefactos del equipo; `--json` para consumirlo. |
+| `ops team show <team>` | Muestra el recorrido y artefactos del equipo. |
 | `ops integration list <ops-root>` | Lista proveedores registrados. |
+| `ops integration enable\|disable <ops-root> <prov>` | Activa o desactiva un proveedor. |
 | `ops integration check <ops-root>` | Valida configuración y staging sin conectarse. |
 | `ops integration sync <ops-root> jira` | Lee Jira y actualiza staging. |
 | `ops integration promote <ops-root> jira KEY` | Promueve un draft `ready` al roadmap. |
@@ -98,42 +92,8 @@ Lee [template/planning/PROTOCOL.md](template/planning/PROTOCOL.md) para el contr
 | `ops automation install <ops-root> <runner>` | Instala el wiring de Claude, Codex, Antigravity o Gemini. |
 | `ops automation doctor <ops-root> <runner>` | Diagnostica una instalación materializada. |
 
-Atajos para desarrollar este toolkit:
-
-```bash
-make ci
-make test
-make coverage
-make automation-check
-make integration-check
-make agent-learn AGENT=product-manager
-make agent-propose AGENT=product-manager
-make agent-evaluate AGENT=product-manager
-make team-check TEAM=product-development
-make team-show TEAM=product-development
-```
-
-También puedes usar el CLI mediante npm:
-
-```bash
-npm run ops -- evaluate product-manager
-```
-
-Los comandos resuelven agentes por slug sin exigir su tipo. Los cargos que trae Cauce viven en
-`agents/roles/system/`; un cargo propio del proyecto va en `agents/roles/` y, con el mismo slug,
-reemplaza al del sistema. Por ejemplo:
-
-```bash
-for skill in agents/roles/*/SKILL.md agents/roles/system/*/SKILL.md; do
-  basename "$(dirname "$skill")"
-done | sort -u
-```
-
-Un slug debe ser único entre todas las categorías. Si dos tipos contienen el mismo slug, el CLI falla por
-ambigüedad en lugar de elegir uno silenciosamente.
-
-`make ci` valida planning, automatización e integración Jira y después ejecuta pruebas con cobertura. Los
-umbrales mínimos son 75% de líneas, 75% de funciones y 45% de ramas; consulta [test/README.md](test/README.md).
+`ops --help` lista las banderas de cada uno. En un proyecto generado, `make help` muestra los atajos
+equivalentes.
 
 ## Adaptación por proyecto
 
@@ -148,6 +108,8 @@ Después de inicializar:
 `organization/` describe el negocio; `planning/` describe intención y estado; los repos de código siguen
 siendo dueños de sus comandos, convenciones y commits.
 
+Los cargos, su adopción y su evaluación están en [agents/README.md](agents/README.md).
+
 ### La frontera `system/`
 
 Cada colección adaptable separa lo que actualiza el toolkit de lo que escribe el proyecto:
@@ -156,78 +118,17 @@ Cada colección adaptable separa lo que actualiza el toolkit de lo que escribe e
 |---|---|---|
 | `planning/business-rules/` | `BR-OPS-NNN` | las reglas de la empresa |
 | `planning/adr/` | `OPS-NNN` | las decisiones de la empresa |
-| `planning/rules/` | proceso, forma del cambio, commits | las convenciones propias |
+| `planning/rules/` | proceso, forma del cambio, commits, conducta | las convenciones propias |
 | `teams/` | composiciones que vienen con Cauce | los equipos propios |
 | `agents/<tipo>/` | *(en el paquete, no se copia)* | los cargos propios |
 
-`automatization/hooks/` no tiene `system/`: es runtime que se reemplaza entero. No hace falta, porque lo
-que un proyecto necesita ya funciona sin editarlo — un guard propio convive y sobrevive, y desactivar uno
-del toolkit es quitarlo de la configuración del runner, que es del proyecto. Editar uno existente detiene
-el `upgrade` antes de pisarlo. Los hooks se quedan en el proyecto porque esa configuración los nombra por
-ruta literal; los adaptadores de runner y los workflows, que sólo lee el motor, viajan en el paquete.
-
 Un archivo propio con el mismo nombre o ID que uno de `system/` lo reemplaza: el del proyecto manda y
 `check` lo reporta como override explícito. Así una mejora del proceso no obliga a forkear el archivo,
 y actualizar no exige resolver conflictos: se reemplaza `system/` entero y nada más se toca.
 
-### Dónde vive cada cosa del catálogo
-
-Los cargos que trae Cauce **no se copian al proyecto**: se resuelven desde la dependencia. Evolucionan
-como profesión, y esa evolución es la misma para
-todas las empresas: investigarla una vez y bien es mejor que repetirla en cada instalación.
-
-| Qué | Dónde | Quién lo mantiene |
-|---|---|---|
-| El cargo como profesión | el paquete | el toolkit, con `agent-learn` en **este** repositorio |
-| Lo que el cargo debe saber de tu empresa | `organization/roles/<slug>.md` | la empresa |
-| Un cargo propio, o una versión propia de uno del catálogo | `agents/roles/<slug>/` | la empresa |
-
-Por eso `learn` falla si lo corrés sobre un cargo del catálogo dentro de una instancia: escribiría en
-el paquete y se perdería. El ciclo mensual de aprendizaje tampoco se distribuye — vive sólo acá.
-
-#### Evaluar un cargo del catálogo
-
-Los casos adversariales miden a un cargo trabajando, y un cargo cuya entrega es una épica o una entrada
-de INBOX necesita un `planning/` donde escribir sea legítimo. El toolkit no lo tiene ni puede tenerlo:
-el único `planning/` que vive acá es `template/planning`, el molde que se distribuye.
-
-```bash
-node engine/cli/ops.js evaluate product-manager --bench 03-epic
-```
-
-Devuelve la ruta de una instancia desechable —`check` pasa, el catálogo resuelve desde adentro,
-`planning/` está vacío y escribible— que el recorrido `/agent-eval` usa como lugar de trabajo. Se
-recrea entera en cada corrida: reutilizarla dejaría que lo que un cargo escribió el lunes sea contexto
-del que responde el martes.
-
-**Una por caso**, y eso se aprendió corriendo. Con un banco compartido los casos de un cargo trabajan a
-la vez sobre el mismo `planning/` y se leen entre sí: un caso tomó por «una sesión anterior de este
-mismo cargo» lo que otro acababa de escribir, y otro evaluó cuatro candidatas que en su enunciado no
-existían. Ninguno cambió de veredicto, pero sus respuestas dejaron de ser las que el caso pedía medir.
-
-El veredicto se escribe **junto al cargo**, no en el banco. El banco se borra; el contrato queda.
-
-Desde una empresa esto no aplica: su instancia ya es el lugar, y lo que se evalúa ahí tiene que ser un
-cargo suyo —propio o adoptado—.
-
-#### Quedarse con una versión propia de un cargo del catálogo
-
-```bash
-npm run ops -- agents fork product-manager
-```
-
-Copia el cargo entero a `agents/roles/<slug>/` y desde ahí lo mantenés vos: `learn`, `evaluate` y el
-puntero que instala el runner pasan a resolver contra tu copia. **Copiarlo a mano no es equivalente**
-—se agarra el `SKILL.md`, que es lo que se ve, y quedan atrás los casos, las fuentes y el modelo
-operativo: el cargo responde igual y ya no se puede evaluar—.
-
-Lo que no viaja son los informes de aprendizaje, las propuestas y los veredictos de evaluación. Un
-veredicto pertenece al contrato que lo ganó, y el fork nace para dejar de ser ese contrato.
-
-A partir de ahí tu copia deja de recibir las mejoras del catálogo, que es lo que elegiste, pero no en
-silencio: `check` y `upgrade` avisan cuando el original cambia río arriba. Editar tu propia copia no
-dispara nada — se compara contra lo que el catálogo tenía el día del fork, no contra lo que vos
-escribiste después.
+`automatization/hooks/` no tiene `system/`: es runtime que se reemplaza entero. Un guard propio convive
+y sobrevive, desactivar uno del toolkit es quitarlo de la configuración del runner, y editar uno
+existente detiene el `upgrade` antes de pisarlo.
 
 ### Versionado
 
@@ -261,54 +162,47 @@ Para añadir otra herramienta se crea un adaptador en `engine/integrations/provi
 `fetchItems` y `normalizeFixture`, y se registra en `engine/integrations/registry.js`. Staging, revisión,
 promoción y validación no se reimplementan. Consulta [integrations/README.md](integrations/README.md).
 
+## Hooks y runners
+
+Los guards portables viven en `automatization/hooks/` y comparten el motor `engine/hooks/run.js`. Una
+instancia nueva los recibe sin activar ningún runner en silencio:
+
+```bash
+node tools/ops.js automation check .
+node tools/ops.js automation install . claude    # o codex / gemini / antigravity
+node tools/ops.js automation doctor . claude
+```
+
+La instalación fusiona la configuración propia del runner y conserva las entradas existentes; sólo
+reemplaza los guards que el propio toolkit había registrado sueltos por el grupo que ahora los cubre, y
+lista cuáles quitó. Nada que no haya escrito el toolkit se toca.
+
+Qué comprueba cada guard, qué no puede comprobar y cómo se agrupan por evento está en
+[automatization/hooks/README.md](automatization/hooks/README.md).
+
 ## Arquitectura del toolkit
 
 - `engine/`: código determinista del CLI, planning, integraciones y aprendizaje de agentes.
-- `automatization/`: contratos, workflows y wiring neutral de runners.
+- `automatization/`: guards, workflows y adaptadores de runner.
 - `integrations/`: documentación del contrato para herramientas externas.
 - `template/`: estructura materializada dentro de cada proyecto.
-- `agents/`: catálogo fuente de agentes, organizado por tipo.
-  - `agents/roles/`: cargos empresariales persistentes y sus evaluaciones.
-  - `agents/workflows/`: futuros agentes orientados a una tarea o flujo concreto.
-  La taxonomía es extensible: cualquier directorio bajo `agents/` es un tipo válido y se reconoce
-  cuando tiene contenido, sin registrarlo en ningún lado. `agents/roles/` es el único que viene con
-  cargos; un coordinador que enrute agentes o un especialista acotado sólo necesitan su directorio
-  el día que existan.
-- `teams/`: composiciones de agentes, con orden, handoffs y responsabilidades compartidas.
-- `teams/product-development/`: primera composición end-to-end desde discovery hasta aprendizaje posterior al release.
-
-El toolkit no guarda contexto real de ninguna empresa. `template/organization/` es el molde que cada proyecto
-recibe como `organization/`. De igual forma, `planning/` pertenece a la instancia generada: conserva su
-intención, estado y evidencia, mientras el motor reusable permanece en la dependencia.
+- `agents/`: el catálogo de cargos, que viaja con el paquete en vez de copiarse.
+- `teams/`: composiciones de cargos, con orden, handoffs y responsabilidades compartidas.
+- `test/`: pruebas del toolkit; ver [test/README.md](test/README.md).
 
-## Hooks y runners
+Cualquier directorio bajo `agents/` es un tipo válido y se reconoce cuando tiene contenido, sin
+registrarlo en ningún lado. Hoy existe `agents/roles/`.
 
-Los once guards portables viven en `automatization/hooks/` y comparten el motor
-`engine/hooks/run.js`. Los runners los invocan por grupo —`guard-shell.sh` y `guard-files.sh`— para gastar
-un solo proceso por herramienta; cada guard sigue siendo invocable suelto por su propio wrapper. Una
-instancia nueva los recibe sin activar ningún runner silenciosamente:
+El toolkit no guarda contexto real de ninguna empresa. `template/organization/` es el molde que cada
+proyecto recibe como `organization/`. De igual forma, `planning/` pertenece a la instancia generada:
+conserva su intención, estado y evidencia, mientras el motor reusable permanece en la dependencia.
 
-```bash
-node tools/ops.js automation check .
-node tools/ops.js automation install . antigravity   # recomendado para Google
-node tools/ops.js automation install . codex         # o claude / gemini
-```
+Para trabajar sobre este repositorio, lee [AGENTS.md](AGENTS.md).
 
-Atajos equivalentes disponibles en cada proyecto generado:
-
-```bash
-make install-claude
-make install-codex
-make install-gemini
-make install-antigravity
-```
+## Licencia
 
-Después de instalar, diagnostica el wiring real con `make doctor-claude`, `make doctor-codex`,
-`make doctor-gemini` o `make doctor-antigravity`.
+[MIT](LICENSE). Sin dependencias: no hay licencias de terceros que arrastrar.
 
-La instalación fusiona la configuración propia del runner y conserva las entradas existentes, con una
-sola excepción: reemplaza los guards que el propio toolkit había registrado sueltos por el grupo que
-ahora los cubre, y lista cuáles quitó. Sin esa poda un proyecto ya instalado ejecutaría cada guard dos
-veces por herramienta —con `verify` eso significa correr la suite de tests dos veces en cada commit—.
-Nada que no haya escrito el toolkit se toca. En Antigravity materializa un plugin nativo de workspace
-bajo `.agents/plugins/cauce/`.
+Lo que `ops init` genera en tu repositorio —`planning/`, `AGENTS.md`, el `Makefile`, `tools/ops.js` y
+el resto del molde— es tuyo: usalo, editalo y distribuilo sin obligación de atribuir ni de incluir este
+aviso. La condición de MIT aplica a redistribuir Cauce, no a lo que construyas con él.

package/agents/README.md

@@ -0,0 +1,49 @@
+# El catálogo de cargos
+
+Un cargo es un contrato: su `SKILL.md` declara cuándo actuar, qué decide, qué no le corresponde y cuál
+es su entrega mínima; sus métodos viven en `references/`. Para ver la lista con una línea por cargo:
+
+```bash
+node tools/ops.js agents list
+```
+
+Un slug es único entre todas las categorías. Si dos contienen el mismo, el CLI falla por ambigüedad en
+lugar de elegir uno en silencio.
+
+## Dónde vive cada cosa
+
+Los cargos que trae Cauce **no se copian al proyecto**: se resuelven desde la dependencia. Evolucionan
+como profesión, y esa evolución es la misma para todas las empresas: investigarla una vez y bien es
+mejor que repetirla en cada instalación.
+
+| Qué | Dónde | Quién lo mantiene |
+|---|---|---|
+| El cargo como profesión | el paquete | el toolkit, con `learn` en **su** repositorio |
+| Lo que el cargo debe saber de tu empresa | `organization/roles/<slug>.md` | la empresa |
+| Un cargo propio, o una versión propia de uno del catálogo | `agents/roles/<slug>/` | la empresa |
+
+Por eso `learn` falla si lo corrés sobre un cargo del catálogo dentro de una instancia: escribiría en el
+paquete y se perdería. El ciclo de aprendizaje de esos cargos tampoco se distribuye.
+
+## Quedarse con una versión propia
+
+```bash
+node tools/ops.js agents fork product-manager
+```
+
+Copia el cargo entero a `agents/roles/<slug>/` y desde ahí lo mantenés vos: `learn`, `evaluate` y el
+puntero que instala el runner pasan a resolver contra tu copia. **Copiarlo a mano no es equivalente**
+—se agarra el `SKILL.md`, que es lo que se ve, y quedan atrás los casos, las fuentes y el modelo
+operativo: el cargo responde igual y ya no se puede evaluar—.
+
+Lo que no viaja son los informes de aprendizaje, las propuestas y los veredictos de evaluación. Un
+veredicto pertenece al contrato que lo ganó, y el fork nace para dejar de ser ese contrato.
+
+Tu copia deja de recibir las mejoras del catálogo, pero no en silencio: `check` y `upgrade` avisan
+cuando el original cambia río arriba. Editar tu propia copia no dispara nada — se compara contra lo que
+el catálogo tenía el día del fork, no contra lo que escribiste después.
+
+## Evaluar un cargo
+
+`evaluate <slug>` corre los casos adversariales del cargo contra su contrato. Lo que se evalúa desde una
+empresa tiene que ser un cargo suyo —propio o adoptado—, y su instancia ya es el lugar donde trabajar.