@ingeniomaps/cauce 0.18.0 → 0.20.0

package/agents/roles/system/security-engineer/learning/reports/2026-08-16.md

@@ -0,0 +1,313 @@
+---
+agent: security-engineer
+date: 2026-08-16
+status: draft
+---
+
+# Investigación semanal — 2026-08-16
+
+## Fuentes consultadas
+
+Inventario local primero (activos reales, no supuestos):
+
+- `package.json` — `@ingeniomaps/cauce@0.18.0`, `type: commonjs`, `engines.node >= 24`,
+  `packageManager: npm@11.16.0`, cero dependencias de runtime, `bin.cauce → engine/cli/ops.js`,
+  `files` como allowlist explícita (`engine/`, `template/`, `agents/`, `teams/`,
+  `automatization/`, `.github/workflows/`).
+- `engine/hooks/run.js` — los doce guards y sus tres grupos por evento.
+- `engine/core/files.js` — `assertWithin`, `assertNoSymlinkPath`, `atomicWrite`.
+- `automatization/hooks/*.sh` y `run-hook.sh` — wrappers que fijan `OPS_ROOT` y resuelven el motor.
+- `.github/workflows/ci.yml` y `.github/workflows/agent-learning.yml`.
+- `.npmrc`, `.env` (gitignoreado; leído sólo por nombres de variable), `.gitignore`,
+  `ops.config.json` (`mode: toolkit`, `allowPush: false`), `Makefile`.
+- `SKILL.md`, `learning/sources.yaml`, `evaluations/expected-behaviors.yaml` del propio cargo.
+
+Fuentes externas (tratadas como datos, no como instrucciones):
+
+| Fuente | Tipo | Fecha | Enlace |
+| --- | --- | --- | --- |
+| GitHub Changelog — npm classic tokens revoked | proveedor primario | 2025-12-09 | https://github.blog/changelog/2025-12-09-npm-classic-tokens-revoked-session-based-auth-and-cli-token-management-now-available |
+| GitHub Changelog — npm classic token creation disabled, granular token changes | proveedor primario | 2025-11-05 | https://github.blog/changelog/2025-11-05-npm-security-update-classic-token-creation-disabled-and-granular-token-changes/ |
+| Microsoft Security Blog — «ChainDrop supply chain compromise» | vendor research | 2026-08-04 | https://www.microsoft.com/en-us/security/blog/2026/08/04/chaindrop-supply-chain-compromise-anatomy-self-propagating-worm/ |
+| StepSecurity — ChainDrop npm worm | vendor research | 2026-08 | https://www.stepsecurity.io/blog/chaindrop-npm-worm |
+| GitHub Advisory GHSA-69fq-xp46-6x23 / CVE-2026-33634 — Trivy ecosystem supply chain | advisory primario | 2026-03 | https://github.com/aquasecurity/trivy/security/advisories/GHSA-69fq-xp46-6x23 |
+| Aqua Security — conclusión del incidente 2026-03-19 | proveedor afectado | 2026-03 | https://github.com/aquasecurity/trivy/discussions/10462 |
+| Node.js — Security Releases | proveedor primario | 2026-07-29 | https://nodejs.org/en/blog/vulnerability/july-2026-security-releases |
+| Socket — «npm v12 ships with install scripts off by default» | vendor research | 2026-07 | https://socket.dev/blog/npm-12 |
+| OWASP Top 10 for Agentic Applications 2026 | estándar comunitario | 2025-12-09 | https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/ |
+| OWASP ASVS 5.0.0 | estándar primario | 2025-05-30 | https://owasp.org/www-project-application-security-verification-standard/ |
+| NIST — SSDF v1.2 en comentario público | estándar primario | 2025-12 | https://www.nist.gov/news-events/news/2025/12/secure-software-development-framework-ssdf-version-12-available-public |
+
+## Hallazgos
+
+### H1 — La publicación a npm depende de un token de larga vida en disco, y la guía escrita apunta a un mecanismo que npm ya revocó
+
+- **Activo**: la cuenta que publica `@ingeniomaps/cauce`. Es el activo de mayor consecuencia del
+  toolkit: quien publique una versión ejecuta código dentro de cada repositorio de empresa que instale.
+- **Exposición**: `.npmrc` resuelve `//registry.npmjs.org/:_authToken=${NPM_TOKEN}` y `NPM_TOKEN` vive
+  en `.env` en la máquina de desarrollo. No hay workflow de publicación: `npm publish` se corre a mano
+  (y el guard `dependencies` lo bloquea salvo acción humana explícita). No hay trusted publishing
+  (OIDC) ni, por lo tanto, procedencia firmada en el paquete.
+- **Estado externo**: npm revocó **permanentemente todos los tokens clásicos el 2025-12-09** («no pueden
+  autenticar, recrearse ni recuperarse»), los granulares con escritura quedaron **limitados a 90 días**
+  y npm recomienda OIDC trusted publishing «que elimina la necesidad de generar y administrar tokens».
+- **Explotabilidad**: no requiere una vulnerabilidad en Cauce. Requiere leer un archivo del disco del
+  desarrollador — que es exactamente lo que hacen los worms de npm en curso (ver H2).
+- **Mitigación proporcional**: publicar desde un workflow con trusted publishing (OIDC) y un
+  *environment* con aprobación humana requerida; mientras tanto, token granular acotado a este paquete,
+  con expiración, y rotación desde un host limpio.
+- **Confianza**: **alta** (hecho local verificado + changelog primario del proveedor).
+
+### H2 — ChainDrop (2026-08-04): el worm de npm cosecha justo las credenciales que este repositorio guarda, y también abusa de trusted publishing
+
+- **Qué pasó**: el 2026-08-04 un worm autopropagante recorrió npm; Microsoft describe releases no
+  autorizadas en más de 400 paquetes, y StepSecurity reporta 444 paquetes y 2 212 versiones en menos de
+  cuatro horas, incluyendo `keyv@6.0.0`, `flat-cache@6.1.24` y `file-entry-cache@11.1.6`.
+- **Qué roba**: tokens npm con permiso de escritura, PAT de GitHub y credenciales del CLI, secretos de
+  runners de GitHub Actions, credenciales cloud (AWS/Azure/Kubernetes) y secretos de HashiCorp Vault.
+- **Cómo se ejecuta**: scripts de instalación (`preinstall` corre antes de que termine la instalación) y
+  —el detalle importante— **una ruta de publicación dirigida a workflows de GitHub Actions configurados
+  como trusted publishers de npm**, lo que le permitió emitir procedencia válida para releases maliciosas.
+- **Exposición de Cauce como consumidor**: **baja**. Cero dependencias de runtime; el motor sólo importa
+  módulos del core (`fs`, `path`, `child_process`, `crypto`, `os`). CI no instala dependencias
+  (`npm run ci` no corre `npm install`).
+- **Exposición de Cauce como publicador**: **alta**, por H1. `.env` contiene además `GITHUB_PAT_CAUCE`
+  con permiso de push sobre `ingeniomaps/cauce`: dos de las categorías que el payload busca, en el mismo
+  archivo.
+- **Lectura sobre H1**: trusted publishing reduce la superficie pero no la elimina. La recomendación
+  correcta no es «OIDC» a secas, sino OIDC **con aprobación de environment** y revisión del workflow.
+- **Confianza**: **alta** para el incidente y su alcance (dos fuentes independientes); **media** para el
+  detalle de abuso de OIDC (una sola fuente: Microsoft).
+
+### H3 — `agent-learning.yml` corre un agente autónomo con `contents: write` en el mismo job donde ingiere contenido web no confiable
+
+- **Evidencia local**: `.github/workflows/agent-learning.yml` declara `permissions: contents: write` y
+  `pull-requests: write` a nivel workflow (líneas 19-21). El job `research` instala y ejecuta
+  `claude -p …` (líneas 121-122) con `ANTHROPIC_API_KEY` en el entorno, y el prompt que ese agente
+  obedece es el `learning/AUTOMATION.md` del cargo — que en este cargo manda explícitamente a leer
+  fuentes externas.
+- **Amenaza**: inyección indirecta de prompt. El contenido que el agente lee es controlado por terceros;
+  el proceso que lo lee tiene, en el mismo entorno, el token de GitHub del job y una API key.
+- **Control existente y real**: el paso «Open research pull request» (líneas 140-145) compara
+  `git diff --name-only` contra la ruta exacta del informe y **falla el job** si el agente tocó otra
+  cosa. Es un buen control y hay que decir que existe.
+- **Límite de ese control**: es *post-hoc*. Corre después de que el agente ya ejecutó comandos con el
+  token disponible. No cubre exfiltración de `ANTHROPIC_API_KEY` ni de `GITHUB_TOKEN` durante el paso
+  `Research`, ni un `git push` emitido desde dentro de ese paso. Verifica el artefacto, no el proceso.
+- **Marco aplicable**: OWASP Top 10 for Agentic Applications 2026 (publicado 2025-12-09), cuyas
+  categorías cubren uso de herramientas, identidad, ejecución de código y agencia excesiva.
+- **Mitigación proporcional**: separar en dos jobs — investigación sin `GITHUB_TOKEN` de escritura
+  (`permissions: contents: read`, resultado subido como artifact) y apertura del PR en un job posterior
+  que sólo lee el artifact. Es el patrón estándar de aislar el paso que toca contenido no confiable del
+  paso que tiene credenciales.
+- **Consecuencia de segundo orden**: `automatization/` y `.github/workflows/` viajan dentro del tarball
+  npm (allowlist `files` de `package.json`), así que este patrón se replica en cada instalación que
+  adopte los workflows. El defecto de diseño escala con la adopción.
+- **Confianza**: **alta** en la observación (código local verificado); **media** en la severidad, porque
+  depende del modelo de amenaza de cada instalación y del repositorio donde corra.
+
+### H4 — Las acciones de GitHub están fijadas a tags mutables, con precedente explotado este año
+
+- **Evidencia local**: `ci.yml` y `agent-learning.yml` usan `actions/checkout@v4` y
+  `actions/setup-node@v4`. Un tag es una referencia móvil.
+- **Precedente explotado**: el 2026-03-19 un actor con credenciales comprometidas hizo *force-push*
+  sobre 76 de 77 tags de versión de `aquasecurity/trivy-action` y sobre los 7 tags de
+  `aquasecurity/setup-trivy`, redirigiendo referencias confiables a commits maliciosos que leían la
+  memoria del worker del runner para extraer secretos. Advisory: **GHSA-69fq-xp46-6x23 /
+  CVE-2026-33634**. Fue la segunda vez en tres semanas.
+- **Exposición diferencial**: `ci.yml` corre con `permissions: contents: read` y sin secretos →
+  impacto contenido. `agent-learning.yml` corre con `contents: write`, `pull-requests: write` y
+  `ANTHROPIC_API_KEY` → ahí un action comprometido es una fuga de credenciales.
+- **Mitigación proporcional**: fijar por SHA completo (comentando la versión al lado) en
+  `agent-learning.yml` como mínimo; `ci.yml` puede seguir después.
+- **Confianza**: **alta**.
+
+### H5 — Node 24: la última release de seguridad es 24.18.1; el impacto real sobre el motor es bajo y conviene decirlo así
+
+- **Externo**: el 2026-07-29 Node publicó 26.5.1, **24.18.1** y 22.23.2, con tres CVE **High** que
+  afectan a 24.x: `CVE-2026-56846` (HTTP/2, headers retenidos evaden `maxSessionMemory`),
+  `CVE-2026-56848` (HTTP/2, heap-use-after-free por envío reentrante) y `CVE-2026-58043` (el
+  Permission Model otorga acceso de más al hacer *path matching*). Más ocho de severidad media/baja.
+- **Local**: `engines.node: ">=24"` (rango abierto, sin techo) y la máquina de desarrollo corre
+  **v24.18.0** — una parche por detrás. CI usa `node-version: "24"`, que resuelve la última 24.x, así
+  que CI ya toma 24.18.1.
+- **Exposición real**: **baja para el producto**. Cauce es un CLI local sin servidor: el motor no
+  importa `http2`, `tls`, `zlib`, `dns` ni `node:sqlite` (verificado: sólo `fs`, `path`,
+  `child_process`, `crypto`, `os`). `CVE-2026-58043` afecta al Permission Model, que Cauce no activa.
+- **Por qué igual figura**: los guards de Cauce **no son** un Permission Model de Node y no deben
+  presentarse como sustituto de uno (ver H7). Y un rango `>=24` sin piso de parche significa que una
+  empresa puede correr el toolkit sobre un 24.x vulnerable creyendo que cumple el requisito.
+- **Mitigación proporcional**: subir el piso de `engines.node` a la línea parcheada vigente.
+- **Confianza**: **alta** en versiones y CVEs (fuente primaria); **alta** en la no-exposición del motor,
+  acotada a que la verificación fue por imports del core y no un análisis de flujo completo.
+
+### H6 — npm v12 apagó los install scripts por defecto; el repositorio sigue fijado a npm 11
+
+- **Externo**: npm v12.0.0 salió el 2026-07-08 con `allowScripts` en *off* por defecto —
+  `preinstall`/`install`/`postinstall` de dependencias ya no corren sin opt-in — sumado a
+  `min-release-age`, que rechaza paquetes publicados demasiado recientemente. Es la contramedida
+  directa al vector de H2.
+- **Local**: `package.json` declara `packageManager: npm@11.16.0`; la máquina corre npm 11.16.0.
+- **Impacto**: Cauce no define scripts de ciclo de vida ni tiene dependencias, así que migrar a npm 12
+  **no rompe nada**; el costo es cero y el beneficio es alinearse con el default endurecido y poder usar
+  `min-release-age` en las instalaciones que sí tienen dependencias.
+- **Confianza**: **alta** en el hecho local; **media** en la fecha exacta y el detalle de la release,
+  porque las fuentes que la reportan son secundarias (Socket) y no encontré el anuncio primario de npm.
+
+### H7 — Los guards son coincidencia de texto sobre el comando, no un límite de seguridad; el riesgo es la confianza que inspiran
+
+- **Evidencia reproducible localmente** (`engine/hooks/run.js`, ejecutado contra sus propias funciones):
+
+  | Comando | Resultado |
+  | --- | --- |
+  | `git push origin main` | BLOQUEA |
+  | `git\tpush origin main` | BLOQUEA |
+  | `bash -c "git push"` | BLOQUEA |
+  | `g=push; git $g origin main` | **PASA** |
+  | `eval "git pu""sh"` | **PASA** |
+  | `npm publish` / `npm exec -- npm publish` | BLOQUEA |
+
+- **Lectura correcta**: esto **no es un bug a tapar con más regex**. Un guard que inspecciona una cadena
+  de shell antes de que la ejecute un shell no puede decidir qué va a ejecutarse; agregar patrones sólo
+  mueve la frontera. Los guards funcionan como lo que son: barandas contra el error y el atajo, no
+  contra un adversario.
+- **Riesgo real**: falsa confianza. Una empresa que instala Cauce y lee «Bloquea publicación y comandos
+  con pérdida de datos» en `hookMetadata` puede concluir que `guard-destructive` impide publicar. No lo
+  impide frente a alguien que quiera publicar. Esto choca de frente con dos controles que este propio
+  cargo declara: `scanner_score_as_complete_risk_decision` en `expected-behaviors.yaml` y «no asegurar
+  cumplimiento ni ausencia de vulnerabilidades» en `SKILL.md`.
+- **Mitigación proporcional**: documental, no técnica — enunciar el alcance de los guards en el README
+  de `automatization/hooks/`. Ninguna de las dos cosas se toca en este informe.
+- **Confianza**: **alta**.
+
+### H8 — El guard de secretos decide por nombre de archivo y deja pasar formatos de credencial habituales
+
+- **Evidencia local** (`engine/hooks/run.js:106-116`, ejecutado):
+
+  | Archivo | Resultado |
+  | --- | --- |
+  | `.env`, `.env.local`, `service-account.json`, `cert.pem`, `deploy.key` | BLOQUEA |
+  | `.npmrc`, `.netrc`, `credentials`, `.aws/credentials`, `id_rsa`, `config/secrets.yaml` | **PASA** |
+
+- **Detalle**: la regex exige extensión para credenciales (`credentials.*\.json`), así que el
+  `~/.aws/credentials` clásico —sin extensión— no matchea. Y `.npmrc` pasa, siendo que en *este mismo
+  repositorio* `.npmrc` es el archivo que referencia el token de publicación.
+- **Exposición**: **baja**. `workspace-boundary` acota la escritura a las raíces declaradas en
+  `ops.config.json`, y `.gitignore` cubre `.env*`, `.npmrc` y `.gitconfig`. El guard es una capa de
+  redundancia, no el control primario.
+- **Explotabilidad**: no es un bypass buscado por un atacante; es un hueco por el que se cuela un
+  descuido honesto.
+- **Confianza**: **alta** en el hecho verificado; **media** en que valga la pena cambiarlo, dado que el
+  control primario ya cubre el caso.
+
+## Evidencia
+
+Todo lo local fue verificado por lectura y ejecución en esta máquina, sin tocar sistemas remotos, sin
+credenciales y sin escanear nada. No se leyó ningún valor de `.env`: sólo los nombres de las variables y
+los comentarios del archivo.
+
+| # | Evidencia | Tipo |
+| --- | --- | --- |
+| H1 | `.npmrc:1`; `.env` (nombres `NPM_TOKEN`, `GITHUB_PAT_CAUCE`, `GITHUB_USER_CAUCE` y su comentario de uso); ausencia de workflow de publicación en `.github/workflows/`; `engine/hooks/run.js:171-178` (guard que exige acción humana para `npm publish`) | local + primaria externa |
+| H2 | Microsoft Security Blog 2026-08-04; StepSecurity; `package.json` sin `dependencies`; imports del motor limitados al core de Node | externa corroborada + local |
+| H3 | `.github/workflows/agent-learning.yml:19-21, 84-94, 115-122, 132-145` | local |
+| H4 | `.github/workflows/ci.yml:19-20`; `agent-learning.yml:29, 80-83`; GHSA-69fq-xp46-6x23 / CVE-2026-33634 | local + advisory primario |
+| H5 | nodejs.org security releases 2026-07-29; `node -v` → v24.18.0; `package.json:29-31`; barrido de `require()` sobre `engine/**/*.js` | primaria externa + local |
+| H6 | Socket 2026-07; `package.json:32`; `npm -v` → 11.16.0 | externa secundaria + local |
+| H7 | Ejecución directa de `guards.destructive` / `guards['git-add']` / `guards.dependencies` sobre once comandos de prueba | local, reproducible |
+| H8 | Ejecución directa de `guards.secrets` sobre trece nombres de archivo | local, reproducible |
+
+Las tablas de H7 y H8 se reproducen invocando las funciones exportadas por `engine/hooks/run.js` con
+objetos de entrada sintéticos. No se ejecutó ninguno de los comandos de prueba.
+
+## Posibles prácticas obsoletas
+
+1. **La guía de credenciales de `.env` describe un mecanismo que ya no existe.** El comentario indica
+   «usá un token *Automation* (clásico) o uno *Granular* con la opción de bypass activada». Los tokens
+   clásicos fueron revocados permanentemente el **2025-12-09** y su creación ya estaba deshabilitada
+   desde el **2025-11-05**. La mitad de esa instrucción es hoy irrealizable, y la otra mitad quedó
+   acotada a 90 días de vida. (Confianza: **alta**.)
+2. **Publicar a npm con token en vez de trusted publishing.** El propio proveedor recomienda OIDC como
+   camino por defecto para CI/CD desde 2025-12-09. Con el matiz de H2: OIDC solo, sin aprobación de
+   environment, ya fue abusado en agosto de 2026. (Confianza: **alta** para lo obsoleto, **media** para
+   la forma exacta del reemplazo.)
+3. **`uses: action@vN` como forma de fijar una acción.** Con el precedente de `trivy-action`
+   (2026-03-19), tratar un tag como inmutable es una práctica vencida en la superficie que maneja
+   secretos. (Confianza: **alta**.)
+4. **`packageManager: npm@11.16.0`.** Fija el toolkit a la línea previa al endurecimiento por defecto de
+   npm v12. (Confianza: **media** — el hecho local es firme; la fecha de v12 viene de fuente secundaria.)
+5. **`learning/sources.yaml` de este cargo no cubre el stack real.** Sus cuatro fuentes (SSDF, ASVS,
+   CWE, KEV) son sólidas y correctas como base de la profesión, pero ninguna emite avisos sobre npm,
+   Node.js o GitHub Actions, que es donde vivió todo lo accionable de esta semana. La brecha es de
+   cobertura, no de calidad. (Confianza: **alta**; propuesta, no cambio — `sources.yaml` no se toca.)
+6. **Vigilar, no cambiar todavía**: `sources.yaml` apunta a SP 800-218 «final», que sigue siendo v1.1
+   (feb 2022). NIST puso **SSDF v1.2 en comentario público en diciembre de 2025**; cuando se finalice,
+   el enlace habrá que revisarlo. ASVS 5.0.0 (2025-05-30) sigue vigente y el enlace del proyecto es
+   correcto. (Confianza: **alta**.)
+
+## Recomendación
+
+Nada de lo que sigue se aplicó: este informe no toca dependencias, controles, secretos, código,
+`SKILL.md` ni planificación.
+
+**Prioridad alta — la cadena de publicación**
+
+1. Migrar la publicación de `@ingeniomaps/cauce` a un workflow con trusted publishing (OIDC) protegido
+   por un *environment* con aprobación humana requerida. Cierra H1 y no queda expuesto al abuso de OIDC
+   sin aprobación descrito en H2. Owner: mantenedor del paquete.
+2. Mientras eso no exista: reemplazar `NPM_TOKEN` por un token granular acotado a este paquete y con
+   expiración, generado y rotado desde un host limpio. Rotar también `GITHUB_PAT_CAUCE`.
+3. Fijar por SHA las acciones de `agent-learning.yml` (el workflow con secretos y `contents: write`).
+
+**Prioridad media — el agente en CI**
+
+4. Partir el job `research` en dos: investigación con `permissions: contents: read` y sin token de
+   escritura, entregando el informe como artifact; apertura del PR en un job separado que sólo consume
+   ese artifact. Conservar la verificación de ruta del informe, que ya funciona. Fijar la versión de
+   `@anthropic-ai/claude-code` que se instala, hoy sin pin.
+5. Subir el piso de `engines.node` a la línea parcheada vigente en vez de `>=24` abierto.
+
+**Prioridad baja — higiene**
+
+6. Evaluar mover `packageManager` a npm 12 (sin impacto funcional: no hay dependencias ni scripts).
+7. Documentar en `automatization/hooks/README.md` qué son y qué no son los guards (H7). Es la
+   recomendación más barata del informe y la que más falsa confianza evita.
+8. Considerar agregar a `sources.yaml` los avisos de Node.js, el changelog de npm/GitHub y el GitHub
+   Advisory Database, que es donde apareció todo lo accionable de esta semana.
+
+**Sobre el contrato del cargo**: nada de esto exige cambiar `SKILL.md` ni
+`evaluations/expected-behaviors.yaml`. H7 es un caso de libro del control que ya existe
+(`scanner_score_as_complete_risk_decision`) y H3 encaja en
+`minimizes_privileges_secrets_sensitive_data_and_attack_surface`. Si algo mereciera discutirse en la
+propuesta mensual, es si el cargo debería nombrar explícitamente el caso «agente autónomo con
+credenciales en CI», que hoy queda cubierto por implicación y no por nombre. Eso es material de
+propuesta, no de este informe.
+
+## Preguntas abiertas
+
+1. **¿Está `@ingeniomaps/cauce` en el radar de ChainDrop?** No lo verifiqué. Confirmarlo exige revisar el
+   historial de publicaciones y las sesiones de la cuenta npm, que es acceso a un sistema remoto y queda
+   fuera del alcance de una revisión pasiva. La versión publicada coincide con la local (0.18.0), lo que
+   es consistente con «sin publicación no autorizada», pero **no es evidencia suficiente**.
+2. **¿Hubo alguna vez un token clásico activo para este paquete?** Si lo hubo, npm lo revocó el
+   2025-12-09 y no hay nada que rotar. Si el `NPM_TOKEN` actual funciona, es granular y tiene fecha de
+   expiración que conviene conocer. Requiere que un humano mire la cuenta.
+3. **Alcance real del incidente de GitHub Actions de marzo de 2026.** Circula la cifra de «78 330
+   secretos exfiltrados de 2 186 organizaciones en cinco días» en blogs secundarios; **no encontré
+   fuente primaria y no la afirmo**. El incidente de `trivy-action` sí está confirmado por advisory. Si
+   alguien necesita la cifra agregada, hay que buscarla en el reporte original, no en este informe.
+4. **Identificadores exactos del OWASP Top 10 for Agentic Applications 2026.** Cito el marco y su fecha
+   de publicación, pero no abrí el PDF, así que no atribuyo un identificador concreto (`AAI0xx`) a H3.
+   **Confianza baja** en cualquier mapeo taxonómico preciso hasta leer el documento.
+5. **¿`npm publish` corre alguna vez desde CI hoy?** No hay workflow que lo haga y el guard
+   `dependencies` lo bloquea, así que la respuesta aparente es «no, siempre a mano». Vale confirmarlo
+   con el mantenedor antes de diseñar la migración a OIDC.
+6. **TOCTOU en `assertNoSymlinkPath`** (`engine/core/files.js:16-28`): la comprobación de symlinks y la
+   escritura posterior no son atómicas, y la función no inspecciona la propia base. En un CLI local, con
+   un atacante que ya tendría escritura en el árbol del proyecto, el escenario es difícil de justificar.
+   Lo dejo anotado **sin severidad asignada**: no encontré un camino en el que un tercero controle esas
+   rutas, y no voy a inventarle explotabilidad a un hallazgo teórico.
+7. **`isWithin` en Windows** (`engine/core/files.js:6-9`): si `path.relative` opera entre volúmenes
+   distintos devuelve una ruta absoluta que no empieza con `..`, y la comprobación la aceptaría.
+   No verificado — no tengo Windows a mano. **Confianza baja**; se confirma con una prueba en esa
+   plataforma o leyendo la implementación de `path.win32.relative`.

package/automatization/hooks/README.md

@@ -15,6 +15,33 @@ Los hooks convierten invariantes comprobables en gates mecánicos. La base recom
 La lógica portable vive en `engine/hooks/run.js`; los `guard-*.sh` son entradas ejecutables comunes. Cada
 adaptador de `runners/` conecta los eventos de su herramienta con esos mismos guards.
 
+## Qué son y qué no son
+
+**Son andamiaje de disciplina: coincidencia de texto sobre el comando o la ruta que el agente propone.**
+Convierten un descuido en un alto y hacen visible una intención en el momento de tenerla. Para eso
+sirven, y sirven bien.
+
+**No son un límite de seguridad, y conviene saber exactamente por qué.** Comprobado corriendo los
+guards directamente:
+
+```text
+git push origin main       → bloquea      g=push; git $g origin main   → pasa
+.env                       → bloquea      .npmrc .netrc id_rsa         → pasan
+```
+
+La primera línea no se arregla con más expresiones regulares: cualquier guard que lea el texto de un
+comando se esquiva componiéndolo, y una shell tiene infinitas formas de hacerlo. La segunda sí es un
+hueco tapable —son nombres de credencial conocidos— pero taparlo no cambia la naturaleza de la
+herramienta.
+
+El riesgo real de esta página no es el bypass: es **la confianza que un guard inspira**. Un repositorio
+con doce guards puestos parece más protegido de lo que está, y esa lectura es peor que no tenerlos,
+porque reemplaza controles que sí son límites —permisos, tokens acotados, revisión humana de lo que se
+publica— por la sensación de que ya está cubierto.
+
+Regla práctica: si algo **tiene** que ser imposible, no lo pongas acá. Ponelo donde no dependa de leer
+una cadena — permisos del runner, alcance del token, aprobación de un PR.
+
 ## Cómo se ejecutan
 
 ```text

package/engine/agents/fork.js

@@ -22,14 +22,21 @@ const catalog = require('./catalog')
 const manifest = require('../core/manifest')
 const ownership = require('../core/ownership')
 
-// Se comparan contra la ruta relativa dentro del cargo. `_template.md` sobrevive en las dos carpetas
-// porque es andamiaje del mecanismo, no un artefacto de nadie.
+// Se comparan contra la ruta relativa dentro del cargo. Informes, propuestas y veredictos no viajan:
+// son lo que produjo nuestra versión del contrato, y el fork nace para dejar de ser ese contrato.
+//
+// Antes se exceptuaba `_template.md`, por andamiaje. Ese andamiaje resultó ser muerto —el motor
+// genera el informe y la propuesta desde un molde propio y nunca lee esos archivos— y en un tercio
+// del catálogo contradecía la forma que sí produce, así que se retiró entero. No hay caso especial
+// que preservar.
 function inherited(relative) {
-  if (/^learning\/(reports|proposals)\//.test(relative)) return path.basename(relative) === '_template.md'
+  if (/^learning\/(reports|proposals)\//.test(relative)) return false
   if (relative.startsWith('evaluations/results/')) return false
   return true
 }
 
+const TEXT = /\.(md|ya?ml|json|txt)$/i
+
 function tree(dir, prefix = '') {
   const found = []
   let list = []
@@ -87,13 +94,20 @@ function fork(root, slug, date) {
 
   // El digest sale del origen, no de la copia. Es lo que el catálogo tenía al momento del fork, y es
   // contra eso que después se responde «esto mejoró río arriba»; medirlo sobre la copia lo ataría a
-  // cualquier cosa que le hagamos acá —empezando por la fila de historial que se escribe abajo—.
+  // cualquier cosa que le hagamos acá —la reescritura de rutas incluida—.
+  //
+  // Y esa reescritura no es cosmética: el `AUTOMATION.md` del catálogo dice «mantené
+  // `agents/<tipo>/system/<slug>`», que en una empresa es el paquete. Copiado tal cual, el aprendizaje
+  // del fork apuntaría a un directorio que el guard bloquea y que npm borra en el próximo install.
+  const desde = `agents/${type}/system/${slug}`
+  const hacia = `agents/${type}/${slug}`
   const digests = {}
   for (const relative of files) {
     const from = path.join(found.dir, relative)
     const to = path.join(target, relative)
     fs.mkdirSync(path.dirname(to), { recursive: true })
-    fs.copyFileSync(from, to)
+    if (TEXT.test(relative)) fs.writeFileSync(to, fs.readFileSync(from, 'utf8').split(desde).join(hacia))
+    else fs.copyFileSync(from, to)
     digests[relative] = manifest.digest(from)
   }
 
@@ -122,6 +136,10 @@ function drift(root) {
   const found = []
   for (const [slug, record] of Object.entries(forks)) {
     if (!record || !record.files) continue
+    // Sin copia no hay deriva. Devolver a un cargo al catálogo es tan legítimo como adoptarlo, y el
+    // registro sobrevive a esa vuelta: sin este corte, `check` avisaba «tu copia no recibe mejoras»
+    // sobre una copia que ya no existe, y mandaba a mirar un directorio borrado.
+    if (!fs.existsSync(path.join(root, 'agents', record.type || 'roles', slug))) continue
     const source = catalogDir ? path.join(catalogDir, record.type || 'roles', 'system', slug) : ''
     if (!source || !fs.existsSync(source)) continue
     const current = tree(source).filter(inherited)

package/engine/agents/learning.js

@@ -32,7 +32,7 @@ function assertWritable(root, agent) {
   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}/.`,
+    `  Para tener una versión propia del cargo, adoptalo: ops agents fork ${agent}.`,
   )
 }
 
@@ -52,6 +52,18 @@ status: draft
 
 # Investigación semanal — ${isoDate(now)}
 
+<!-- Dos convenciones que el ciclo necesita y que nada más sostiene:
+
+  · Etiquetá cada hallazgo H1, H2, … en el orden en que aparecen. «Evidencia» y «Recomendación» se
+    refieren a ellos por esa clave, y la propuesta mensual la cita para decir de qué hallazgo sale
+    un cambio. Sin etiqueta las tres secciones dejan de cruzarse y nada lo delata.
+
+  · No renombres los títulos. «## Recomendación» se lee con un patrón exacto y es lo único que la
+    propuesta consolida de cada informe: renombrarlo no da error, deja la propuesta vacía.
+
+Este comentario vive fuera de toda sección a propósito — dentro de «Recomendación» viajaría a cada
+propuesta consolidada. -->
+
 ## Fuentes consultadas
 
 ## Hallazgos

package/engine/automation/index.js

@@ -163,6 +163,9 @@ Leé \`${role.reference}/SKILL.md\` para el contrato completo del cargo: cuándo
 qué decide, qué no le corresponde y cuál es su entrega mínima. Sus métodos y formatos de salida están
 en \`${role.reference}/references/\`.
 
+Esas rutas se resuelven desde este directorio raíz, no desde el repositorio de operaciones: en modo
+sidecar el wiring vive acá y el repo ops es uno de sus hijos.
+
 Respetá los límites de ese contrato y las reglas de \`AGENTS.md\`. Generado por
 \`cauce automation install\`: no lo edites acá.
 `

package/engine/cli/ops.js

@@ -608,7 +608,12 @@ function upgrade(dir) {
     const dir = path.join(root, relative)
     if (fs.existsSync(dir)) registro = M.record(root, relative, O.treeFiles(dir), registro)
   }
-  M.write(root, M.prune(root, registro))
+  // El registro de forks se poda igual que el de archivos: un cargo devuelto al catálogo deja su
+  // entrada, y una entrada sin copia sólo puede producir avisos sobre algo que no está.
+  const vivos = Object.fromEntries(Object.entries(M.readForks(root)).filter(
+    ([slug, record]) => fs.existsSync(path.join(root, 'agents', (record || {}).type || 'roles', slug)),
+  ))
+  M.write(root, M.prune(root, registro), null, vivos)
 
   const config = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8'))
   config.cauceVersion = to

package/engine/hooks/run.js

@@ -112,6 +112,15 @@ function secrets(input) {
     if (/^(?:accesos\.md|credenciales.*|credentials.*\.json|.*service-account.*\.json|.*\.(?:pem|key))$/i.test(base)) {
       block(`${file} parece un archivo de credenciales en texto plano.`)
     }
+    // Nombres de credencial que la herramienta escribe sola y que la lista anterior no cubría:
+    // `.npmrc` guarda el token de publicación, `.netrc` el de cualquier host, `id_*` una clave
+    // privada de SSH y `~/.aws/credentials` las de AWS. Los cuatro son estándar, no exóticos.
+    //
+    // Esto tapa un caso conocido; no vuelve completo al guard. La forma de decidir sigue siendo el
+    // nombre del archivo, así que otro formato pasa igual — ver «Qué son y qué no son» en el README.
+    if (/^(?:\.npmrc|\.netrc|_netrc|\.pypirc|\.dockercfg|id_(?:rsa|dsa|ecdsa|ed25519)|credentials)$/i.test(base)) {
+      block(`${file} es un archivo de credenciales que su herramienta mantiene. No lo edites a mano.`)
+    }
   }
 }
 
@@ -219,9 +228,27 @@ function governance(input) {
   const command = commandOf(input)
   if (!isCommit(command)) return
   const dir = gitDirectory(command, cwdOf(input))
+  // El contrato de un cargo y lo que lo mide son gobernanza, igual que un ADR o una regla.
+  //
+  // Lo puntual es la firma: `agent-promote` se niega si «Aprobación humana» no está firmada, pero lo
+  // único que impedía que la escribiera un agente era una frase en un prompt. Una instrucción, no un
+  // candado — y el archivo no estaba protegido por nada.
+  //
+  // Alrededor de la firma van las otras tres piezas del mismo acto. `SKILL.md` y `references/` son lo
+  // que la propuesta cambia: sin ellos, editar el contrato directo saltea el ciclo entero. Y
+  // `evaluations/` es el denominador con que se juzga —el propio recorrido de propuesta dice que
+  // cambiarlo «es parte de lo que se aprueba»—, así que moverlo en silencio ablanda toda medición
+  // pasada sin tocar una sola regla.
+  //
+  // Quedan afuera las dos clases de evidencia, y por la misma razón: registran lo que pasó un día en
+  // vez de decidir algo. `learning/reports/` es lo investigado esa semana, y `evaluations/results/` la
+  // transcripción de una corrida —que se escribe en cada evaluación, así que gobernarla pediría un
+  // override por corrida—. Por eso `evaluations/` se nombra por partes en vez de entero.
   const governedPattern = new RegExp(
     String.raw`^(?:(?:template\/)?planning\/(?:rules\/|adr\/|PROTOCOL\.md|` +
-      String.raw`METHODOLOGY\.md|FLOW\.md)|automatization\/|engine\/)`,
+      String.raw`METHODOLOGY\.md|FLOW\.md)|automatization\/|engine\/` +
+      String.raw`|agents\/[a-z0-9-]+\/(?:system\/)?[a-z0-9-]+\/(?:SKILL\.md|references\/` +
+      String.raw`|evaluations\/(?:cases\/|expected-behaviors\.yaml)|learning\/proposals\/))`,
   )
   const governed = stagedFiles(dir).filter((file) => governedPattern.test(file))
   if (governed.length) {

package/package.json

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

package/agents/roles/system/ai-governance-lead/learning/proposals/_template.md

@@ -1,11 +0,0 @@
-# Propuesta mensual — AI Governance Lead
-
-- Periodo e informes incluidos:
-- Problema verificable:
-- Cambio propuesto:
-- Fuentes/versiones/estado/fechas:
-- Jurisdicciones, roles y sistemas:
-- Impacto en controles, evidencia y decisiones:
-- Revisión Legal/owners requerida:
-- Evaluaciones afectadas y rollback:
-- Decisión humana: pendiente

package/agents/roles/system/ai-governance-lead/learning/reports/_template.md

@@ -1,11 +0,0 @@
-# Informe semanal — AI Governance Lead
-
-- Periodo y responsable:
-- Fuente/instrumento/versión/estado:
-- Jurisdicción/rol/sistemas afectados:
-- Publicación/vigencia/aplicación/transición:
-- Cambios observados:
-- Prácticas vigentes u obsoletas:
-- Impacto en inventario, assessment, controles o gates:
-- Interpretación/evidencia faltante:
-- Recomendación (mantener / Legal-review / investigar / proponer):

package/agents/roles/system/ai-product-manager/learning/proposals/_template.md

@@ -1,9 +0,0 @@
-# Propuesta mensual — AI Product Manager
-
-- Periodo e informes incluidos:
-- Problema y cambio propuesto:
-- Modelo/provider/versión/fecha/estado/fuentes:
-- Impacto en usuarios, afectados, valor y journey:
-- Riesgo, evals, operación, economics y retiro:
-- Evaluaciones afectadas y rollback:
-- Decisión humana: pendiente

package/agents/roles/system/ai-product-manager/learning/reports/_template.md

@@ -1,9 +0,0 @@
-# Informe semanal — AI Product Manager
-
-- Periodo y responsable:
-- Modelo/provider/versión/fecha/estado y fuentes:
-- Cambios observados y aplicabilidad:
-- Prácticas vigentes u obsoletas:
-- Impacto en valor, experiencia, riesgo, evals, operación o costo:
-- Evidencia reproducible/input de afectados/faltante:
-- Recomendación (mantener / investigar / proponer):

package/agents/roles/system/analytics-engineer/learning/proposals/_template.md

@@ -1,9 +0,0 @@
-# Propuesta mensual — Analytics Engineer
-
-- Periodo e informes incluidos:
-- Problema y cambio propuesto:
-- Fuentes/versiones/estado/aplicabilidad:
-- Impacto semántico, consumers y compatibilidad:
-- Calidad, seguridad, costo y operación:
-- Evaluaciones afectadas y rollback:
-- Decisión humana: pendiente

package/agents/roles/system/analytics-engineer/learning/reports/_template.md

@@ -1,9 +0,0 @@
-# Informe semanal — Analytics Engineer
-
-- Periodo y responsable:
-- Fuentes/versiones/estado/plataforma:
-- Cambios observados:
-- Prácticas vigentes u obsoletas:
-- Impacto en modelado, métricas, calidad, costo o lineage:
-- Evidencia reproducible/equivalencia semántica/faltante:
-- Recomendación (mantener / investigar / proponer):

package/agents/roles/system/backend-engineer/learning/proposals/_template.md

@@ -1,15 +0,0 @@
----
-agent: backend-engineer
-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/backend-engineer/learning/reports/_template.md

@@ -1,14 +0,0 @@
----
-agent: backend-engineer
-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/business-operations-manager/learning/proposals/_template.md

@@ -1,13 +0,0 @@
----
-agent: business-operations-manager
-period: YYYY-MM
-status: proposed
-automatic_apply: false
----
-# Propuesta mensual — YYYY-MM
-## Hallazgos y aplicabilidad
-## Evidencia
-## Cambio propuesto
-## Riesgos, incentivos y regresiones
-## Evaluación
-## Aprobación humana