@ingeniomaps/cauce 0.78.0 → 0.80.0

package/template/integrations/README.md

@@ -22,3 +22,24 @@ node tools/ops.js integration promote . jira KEY-123
 El motor compara base reconciliada, remoto actual y curación local. Usa `reset` para adoptar el remoto,
 `reconcile` para conservar la edición local sobre la nueva base y `rebase` para reparar hashes mecánicos.
 Ninguno de esos comandos escribe en el proveedor.
+
+## Un proveedor propio
+
+Cauce trae Jira. Para conectar otra herramienta, el adaptador se escribe acá, en la instancia, sin tocar
+Cauce:
+
+1. Crear `integrations/<nombre>/` con su `config.json` y el adaptador, por ejemplo `adapter.js`.
+2. Registrarlo en `config.json` con la ruta, relativa a `integrations/<nombre>/`:
+   `"adapter": "./adapter.js"`. Un nombre sin `./` —`"jira"`— es un adaptador de Cauce.
+3. `node tools/ops.js integration enable . <nombre>` lo conecta y `integration check .` lo valida.
+
+El adaptador exporta `contract: 1` y tres funciones:
+
+- `validateConfig(config, errors)` valida sin conectarse, y empuja a `errors` lo que impide correr.
+- `fetchItems(config, options)` hace la lectura paginada completa del proveedor.
+- `normalizeFixture(payload, config)` usa el mismo normalizador sin red, para pruebas e importaciones.
+
+`check` rechaza un adaptador con otra versión o sin alguna de las funciones, y una ruta que salga de
+`integrations/<nombre>/`. Puede ser CommonJS o ESM. El motor lo ejecuta con los mismos permisos que el
+CLI: la contención es de ruta, no de capacidad. Staging, revisión, promoción y validación son los mismos
+que para Jira; el adaptador sólo traduce la API del proveedor.

package/template/organization/README.md

@@ -18,4 +18,56 @@ Recomendados, sin molde: escribilos con la forma que le sirva a este proyecto.
 La lista no es cerrada. Todo hecho de negocio o producto que cambie lentamente vive acá —una guía de
 marca, un manual de operación, un pipeline de contenido— aunque no tenga una línea propia arriba.
 
+Opcional, con forma fija: `secrets.json`, el contrato de secretos que la empresa comparte entre sus
+repositorios. Ver «Secretos compartidos» abajo.
+
 Principio: cada hecho tiene un dueño. Enlaza en vez de copiar información que ya vive en otro lugar.
+
+## Secretos compartidos
+
+Cuando varios servicios usan el mismo gestor de secretos —Infisical, Vault, Doppler—, terminan con los
+mismos scripts y workflows copiados en cada repositorio, y la copia que se quedó atrás no avisa.
+`secrets.json` declara ese contrato una vez y `node tools/ops.js secrets check .` lo compara contra cada
+servicio **sin conectarse a nada**. Cauce no conoce ningún gestor: lo que habla con él es de la empresa.
+
+```json
+{
+  "schemaVersion": 1,
+  "accounts":   { "principal": { "url": "https://app.infisical.com" } },
+  "projects":   { "tienda": { "account": "principal" } },
+  "identities": {
+    "local-dev": { "account": "principal", "source": "file", "file": "~/.config/acme/local-dev.env" },
+    "ci":        { "account": "principal", "source": "ci-secret" }
+  },
+  "shared":   { "check-schema": "organization/secrets/check-schema.py" },
+  "services": {
+    "api": { "root": "api", "project": "tienda", "identity": "local-dev",
+             "files": { "scripts/check-schema.py": "check-schema" } }
+  }
+}
+```
+
+- **Nunca guarda un valor.** Una clave con forma de secreto —`token`, `password`, `secret`— es un error.
+  Las entradas pueden llevar otros campos que lean los scripts de la empresa (un id de proyecto, sus
+  ambientes); el chequeo no los mira.
+- **Una identidad por nivel de acceso, no por repositorio.** Compartir credenciales es apuntar al mismo
+  alias, y rotar es cambiar un archivo. `source: file` es un archivo **fuera de todo repositorio**, que
+  carga una persona; `source: ci-secret` vive en el CI y no lleva ruta.
+- **`shared` guarda la copia canónica** de cada archivo compartido, dentro de esta instancia, y
+  `services.<nombre>.files` dice dónde va en el servicio. Cada `root` es una raíz de `ops.config.json`.
+- **Varios proyectos, una instancia.** El chequeo compara los servicios de esta instancia; para que el
+  esqueleto de un proyecto y los servicios de otro se midan contra lo mismo, los dos van como raíces acá.
+
+`secrets check` falla si una copia no coincide con la canónica —y dice el `cp` que la pone al día—, si
+falta, si una referencia no cierra o si una credencial está dentro de un repositorio. Una identidad que
+no está en esta máquina es una advertencia: en el CI no tiene por qué estar.
+
+El recorrido:
+
+- **Adoptar un servicio**: declararlo, copiar los archivos de `shared` y correr `secrets check`. Cargar
+  la identidad en su archivo y los secretos del CI lo hace una persona: el guard de secretos frena que
+  un agente escriba un `.env.*`, y es lo correcto.
+- **Mantener**: se cambia la copia canónica, `secrets check` lista los servicios que quedaron atrás y
+  cada uno se actualiza con un commit en su repositorio.
+- **Rotar**: se reemplaza el archivo de la identidad; los servicios que la usan no cambian.
+- **Dar de baja**: se saca el servicio de `services` y se borran sus copias en su repositorio.

package/template/planning/adr/README.md

@@ -47,3 +47,4 @@ archivo lo mantiene Cauce, así que una fila agregada acá se perdería en el pr
 - [OPS-004](system/OPS-004-promocion-humana-y-evidencia-verificable.md): promoción controlada y verificable.
 - [OPS-005](system/OPS-005-catalogo-en-el-paquete.md): el catálogo viaja dentro del paquete.
 - [OPS-006](system/OPS-006-ceremonia-por-superficie.md): la ceremonia escala con la superficie del cambio.
+- [OPS-007](system/OPS-007-contrato-de-secretos-compartido.md): un contrato de secretos compartido, sin gestor.

package/template/planning/adr/system/OPS-007-contrato-de-secretos-compartido.md

@@ -0,0 +1,62 @@
+# OPS-007 — Un contrato de secretos compartido, sin conocer ningún gestor
+
+**Estado:** Aceptado
+**Fecha:** 2026-09-10
+
+> Decide qué parte del manejo de secretos es de la base; el gestor, sus scripts y su CI siguen siendo de
+> la empresa.
+
+## Contexto
+
+Una empresa que adopta un gestor de secretos termina con el mismo modelo copiado en cada repositorio:
+la identidad con que se lee el gestor, un script que compara el gestor contra el contrato de variables y
+los workflows que avisan en el PR. Nada dice qué servicio usa qué cuenta ni qué identidad, y nada detecta
+que una copia se quedó atrás. En una instancia real se contaron dieciséis copias de un mismo script en
+tres variantes, y el arreglo que tenía una sola no había llegado ni al esqueleto del que salen los
+servicios nuevos.
+
+`integrations/` no sirve para esto: su ciclo es de contenido de trabajo que baja a planning (OPS-003), y
+su README prohíbe guardar secretos ahí.
+
+## Decisión
+
+**La base declara y compara; no se conecta, no genera y no conoce ningún gestor.**
+
+- La declaración vive en `organization/secrets.json`, que es del proyecto: cuentas, proyectos,
+  identidades, servicios y los archivos que comparten. Nunca un valor: una clave con forma de secreto es
+  un error.
+- Una identidad es un nivel de acceso, no un repositorio. `source: file` es un archivo **fuera de todo
+  repositorio**, que carga una persona; `source: ci-secret` vive en el CI.
+- La copia canónica de cada archivo compartido vive en la instancia. `ops secrets check` compara cada
+  copia de cada servicio contra ella por hash, sin red, y dice el `cp` que la pone al día. Cauce no
+  escribe en los repositorios de producto.
+- El chequeo compara los servicios de una instancia. Una empresa con varios proyectos los declara como
+  raíces de la misma instancia, que es lo que hace que un esqueleto y sus derivados se midan contra lo
+  mismo.
+
+## Alternativas consideradas
+
+- **Un adaptador de la empresa que genere los archivos**: flexible, pero obliga al motor a cargar código
+  de la instancia y a versionar una interfaz, para resolver lo mismo que una copia comparada por hash.
+- **El adaptador como paquete versionado que cada instancia instala**: mantiene una instancia por
+  proyecto a cambio de publicar y versionar un paquete más.
+- **Un workflow reutilizable compartido**: una sola copia, pero supone GitHub y una organización, y deja
+  a la base atada a un proveedor de CI.
+- **Hacerlo un proveedor de `integrations/`**: su staging, reconciliación y promoción no se aplican a
+  secretos.
+
+## Consecuencias
+
+**Ganamos:** la copia que se quedó atrás se ve, con su arreglo al lado; rotar una identidad compartida
+es cambiar un archivo; y la base sigue sin saber de ningún gestor.
+
+**Costos que aceptamos:** un arreglo sigue siendo un commit por repositorio —el chequeo los lista, no los
+aplica—. Juntar varios proyectos en una instancia comparte también su `planning/`. Y una credencial
+dentro de un repositorio es un error aunque esté ignorada por git: es la copia por repositorio que esta
+decisión viene a sacar.
+
+## Estado de implementación
+
+Implementado en 0.80.0: `organization/secrets.json`, `ops secrets check` y el recorrido documentado en
+`organization/README.md`. Cauce no trae adaptadores ni un workflow de ejemplo que corra el chequeo en CI;
+correrlo ahí es un paso de la empresa.