@ingeniomaps/cauce 0.26.0 → 0.28.0

package/CHANGELOG.md

@@ -14,6 +14,69 @@ desde este repositorio no va, porque el que lee no puede actuar sobre eso. Cuand
 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.28.0] - 2026-08-18
+
+### Añadido
+
+- **`/onboard`: el recorrido que llena una instancia recién creada.** `init` la deja funcionando y sin
+  enterar de nada —`organization/` es el molde y el roadmap está vacío—, y llenarlo exige leer el
+  repositorio y decidir qué es cada cosa, que es justo lo que un CLI determinista no puede hacer. El
+  recorrido inventaría los subproyectos con manifiesto propio, **corre** los comandos de test, lint y
+  build que cada uno declara, y escribe `organization/`, la sección «Mapa real» de `AGENTS.md` y las
+  raíces reales en `ops.config.json`.
+
+  Corre los comandos en vez de copiarlos del README porque un mapa copiado envejece sin avisar y el
+  primer Verify de una tarea real es donde aparece: cada comando queda como verificado, falla o ausente.
+  Lo que deduce va marcado «(supuesto)» y lo que nada sostiene queda «Por definir». No lee `.env` ni
+  ninguna credencial —de `.env.example` toma sólo los nombres de variable—, y las credenciales, los MCP
+  y el permiso de push salen como filas de `HUMAN_ACTIONS.md` con la acción concreta que las desbloquea,
+  sin proponer ningún valor. Cierra escribiendo la épica 001 —que una tarea pueda atravesar el ciclo
+  entero— y no la promueve.
+
+  Si la instancia ya tiene contexto escrito, para y pide `force`: reescribir un borrador que alguien
+  corrigió no deja rastro de lo que se perdió. Y un workspace todavía sin código no es un error: escribe
+  lo que el contexto permita y traer los repos pasa a ser la primera historia.
+
+  Claude y Antigravity lo reciben como recorrido ejecutable; Codex y Gemini lo operan desde la sección
+  «El arranque» que `automation install` deja en sus instrucciones. Si ya tenés una instancia, el
+  workflow llega con `automation install` —no con `upgrade`—: los workflows viven en el runner.
+
+### Corregido
+
+- **`init` dentro de una carpeta que ya nombra al toolkit deja de anidar.** Correrlo parado en
+  `acme-ops/` creaba `acme-ops/ops/` —una raíz ops dentro de otra— y llamaba «acme-ops» al proyecto.
+  Ahora la instancia es esa carpeta y el proyecto se llama «acme». Además un `.git` solo dejó de contar
+  como contenido, así que `mkdir acme-ops && git init && cauce init` no pide `--force` para no pisar
+  nada.
+
+## [0.27.0] - 2026-08-18
+
+### Añadido
+
+- **Instalar Cauce es un comando.** `npx @ingeniomaps/cauce init`, sin destino, crea `ops/` en modo
+  sidecar, te pregunta con qué runner vas a trabajar y qué integración querés, corre `npm install`,
+  deja el wiring del runner puesto y valida la instancia antes de terminar.
+
+  Antes había que elegir destino y modo a ciegas, correr `npm install` a mano —sin él la instancia no
+  funciona: el shim, los cargos, los equipos y los adaptadores se resuelven desde `node_modules`— y
+  después instalar el runner. Las dos preguntas tienen «ninguno» como default: instalar un runner
+  escribe en tu repositorio, así que un Enter apurado no deja archivos que no pediste, y los dos pasos
+  se agregan más tarde con `automation install` e `integration enable`.
+
+- **Banderas para instalar sin preguntas.** `init` acepta `--runner`, `--integration` e
+  `--install`/`--no-install`. Sin terminal —CI, un contenedor, un Dockerfile— no pregunta nada ni
+  descarga nada: materializa la instancia y dice qué falta, así que una automatización decide por
+  bandera y no hereda una descarga. Un `npm install` que falla se reporta y deja escrito por dónde
+  seguir, en vez de terminar en un error del runner tres pasos después.
+
+### Cambiado
+
+- **El destino de `init` es opcional, y sin él la instancia se aparta en `ops/`.** Antes cortaba con
+  `Falta <destino>`, así que ninguna invocación existente cambia de comportamiento. Lo que cambia es
+  a dónde va lo que no elegiste: un monorepo recibía `planning/`, `teams/`, `organization/` y
+  `AGENTS.md` en su primer nivel y dejaba de distinguir qué era suyo. El modo `embedded`, que es el que
+  despliega el molde en la raíz, ahora hay que pedirlo explícito.
+
 ## [0.26.0] - 2026-08-17
 
 ### Añadido

package/README.md

@@ -10,7 +10,8 @@ el contexto de cada empresa vive en su propia instancia.
 - Una sesión interrumpida se recupera desde `WIP.md`, sin reconstruir la intención.
 - 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.
+- Vive en su propia carpeta `ops/` dentro del repo, como sidecar `proyecto-ops` para varios repos, o
+  embebido en la raíz.
 - 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.
@@ -18,26 +19,103 @@ el contexto de cada empresa vive en su propia instancia.
 
 ## Inicio rápido
 
-Requiere Node.js 24 o superior y no tiene dependencias externas.
+Requiere Node.js 24 o superior y no tiene dependencias externas. No hace falta clonar este repositorio.
 
 ```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-ops --name "Mi proyecto" --mode sidecar
+cd mi-repo
+npx @ingeniomaps/cauce@latest init
 ```
 
-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.
+Eso alcanza. `init` crea `./ops`, pregunta con qué runner vas a trabajar y qué integraciones querés,
+instala la dependencia, deja el wiring del runner puesto y valida la instancia antes de terminar:
 
-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á.
+```text
+¿Con qué runner vas a trabajar?
+1) claude   2) codex   3) gemini   4) antigravity   5) ninguno
+[ninguno] > 1
+
+¿Habilitar alguna integración?
+1) jira   2) ninguna
+[ninguna] >
+
+· npm install (el motor viene de la dependencia)
+✓ claude: adaptador operativo (0 advertencia(s))
+✓ planning válido: 0 épica(s), 0 tarea(s) en cola, 0 terminada(s)
+  listo: el ciclo empieza en ops/planning/FLOW.md
+```
+
+El default de las dos preguntas es no hacer nada: instalar un runner escribe en tu repositorio y
+habilitar un proveedor deja andamiaje que después hay que completar, así que un Enter apurado no deja
+archivos que no pediste. Los dos pasos se pueden agregar más tarde con `automation install` e
+`integration enable`.
+
+Queda así, y el resto del repositorio sin tocar:
+
+```text
+mi-repo/
+├── apps/          tu código, intacto
+├── ops/           Cauce: planning/, organization/, teams/, tools/, AGENTS.md, Makefile
+├── .claude/       el wiring del runner elegido
+└── CLAUDE.md
+```
+
+Lo del runner va a la raíz a propósito: ahí abre el dev su herramienta, y uno que sólo viera `ops/` no
+tendría acceso a una línea de código.
+
+### Sin preguntas, para un script
+
+Sin terminal —CI, un contenedor, un Dockerfile— `init` no pregunta nada ni descarga nada: materializa la
+instancia y dice qué falta. Todo se puede decidir por bandera:
+
+```bash
+npx @ingeniomaps/cauce@latest init --runner codex --integration jira --install
+```
+
+`--install` es el que corre `npm install`; sin él la instancia queda creada pero todavía no funciona, y
+la salida lo dice. La dependencia no es opcional: el shim `tools/ops.js`, los cargos, los equipos y los
+adaptadores se resuelven desde `<ops>/node_modules/@ingeniomaps/cauce`, y el lockfile es lo que fija qué
+versión del motor corre.
+
+### Dónde vive la instancia
+
+| Situación | Comando | Qué queda |
+|---|---|---|
+| Un repo: monolito o monorepo | `init` | `ops/` dentro del repo; el runner se instala en la raíz. |
+| Varios repos de producto | `init acme-ops --mode sidecar`, desde la carpeta que los contiene | `acme-ops/` hermano de los repos. |
+| Planning en la raíz del repo | `init . --mode embedded --force` | `planning/`, `organization/`, `teams/`, `tools/`, `AGENTS.md` y `Makefile` en el primer nivel. |
+
+Los dos primeros son el mismo modo —`sidecar`— y difieren sólo en dónde queda la carpeta: adentro del
+repo o al lado. El tercero hay que pedirlo explícito porque es el único que despliega el molde en el
+primer nivel del repositorio.
+
+El destino debe estar vacío o no existir. `--force` completa archivos faltantes en un directorio que ya
+tiene cosas, y nunca sobrescribe los que ya están.
+
+Declarar npm en el repo ops no le impone un stack a nadie: ese repo coordina, no compila, y Node hace
+falta igual —el motor, los guards y los workflows son JavaScript—.
+
+### El primer ciclo
+
+`init` deja la instancia funcionando, no enterada: `organization/` llega como molde y el roadmap está
+vacío. Llenarlo exige leer el repositorio y decidir qué es cada cosa, que es lo que un CLI determinista
+no puede hacer, así que ese recorrido vive en el runner:
+
+```text
+/onboard    inventaría los servicios, corre sus comandos de test, lint y build, y escribe
+            organization/, el «Mapa real» de AGENTS.md y las raíces de ops.config.json.
+            Lo deducido queda marcado como supuesto; credenciales, MCP y el permiso de push
+            van a HUMAN_ACTIONS.md. Cierra con la épica 001, sin promoverla.
+/team       evalúa si una intención posterior es viable y propone su épica.
+/autobuild  ejecuta una tarea ya promovida, fase por fase.
+```
 
-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—.
+Claude y Antigravity lo traen como recorrido ejecutable; Codex y Gemini lo operan siguiendo las
+instrucciones que `automation install` les deja. Sin runner, la [tabla de comandos](#comandos) y
+[FLOW.md](template/planning/FLOW.md) hacen el mismo camino a mano.
 
-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.
+Dentro del proyecto el CLI se invoca con `node tools/ops.js` —o `npx cauce`, que la dependencia deja
+disponible—; desde este repositorio, con `node engine/cli/ops.js`. En la tabla de abajo `ops` representa
+cualquiera de esas formas.
 
 ## Flujo
 
@@ -62,7 +140,7 @@ Lee [template/planning/PROTOCOL.md](template/planning/PROTOCOL.md) para el contr
 
 | Comando | Función |
 |---|---|
-| `ops init <destino>` | Materializa una instancia portable. |
+| `ops init [destino]` | Materializa una instancia y la deja usable; sin destino, en `ops/` y modo sidecar. |
 | `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. |