@ingeniomaps/cauce 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -14,6 +14,68 @@ 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.29.0] - 2026-08-18
+
+### Añadido
+
+- **`ops scan`: qué hay en el workspace, resuelto por código.** Lista los subproyectos con manifiesto
+  propio, su runtime y los comandos de test, lint y build que cada uno declara, diciendo de qué archivo
+  salió cada comando. No corre ninguno y no inventa ninguno: un comando que nadie declaró se lee igual
+  que uno real, y el primer Verify de una tarea es donde eso se descubre. Saltea `node_modules` y todo
+  directorio oculto, que es lo que lo mantiene en milisegundos. Una instancia sidecar escanea su carpeta
+  madre, donde vive el código; cualquier otro modo, donde está parada.
+
+### Cambiado
+
+- **`/onboard` cuesta lo que encuentra.** Empezaba pidiéndole a un agente que explorara el repositorio y
+  terminaba corriendo la suite de tests de cada servicio: una corrida sobre una carpeta vacía gastó doce
+  minutos sin poder producir nada. Ahora arranca con `ops scan` —una llamada, milisegundos— y, si el
+  workspace no tiene código y nadie aportó contexto, termina ahí diciendo qué le falta, en vez de escribir
+  una empresa inventada.
+
+  El recorrido ya no ejecuta nada del proyecto. El mapa real anota cada comando **tal como está
+  declarado**, con su archivo de origen, y verificarlo corriéndolo pasa a ser una historia de la épica
+  001, donde tiene dueño y tiempo asignado. Lo que escribe y lo que deja a una persona no cambió:
+  borradores marcados como supuestos, credenciales y MCP en `HUMAN_ACTIONS.md`, épica sin promover.
+
+  Si ya tenés una instancia, el recorrido actualizado llega con `automation install`, no con `upgrade`:
+  los workflows viven en el runner.
+
+## [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

package/README.md

@@ -96,9 +96,23 @@ falta igual —el motor, los guards y los workflows son JavaScript—.
 
 ### El primer ciclo
 
-Desde el runner, `/team` recorre un equipo y deja escrita una épica candidata en `planning/roadmap/`, y
-`/autobuild` toma una tarea ya promovida y la ejecuta fase por fase. Sin runner el recorrido es el
-mismo: la [tabla de comandos](#comandos) y [FLOW.md](template/planning/FLOW.md) lo operan a mano.
+`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    parte del inventario de `ops scan` y escribe organization/, el «Mapa real» de
+            AGENTS.md —cada comando como está declarado y de qué archivo salió— 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.
+            No corre nada del proyecto: verificar los comandos es una historia de esa épica.
+/team       evalúa si una intención posterior es viable y propone su épica.
+/autobuild  ejecuta una tarea ya promovida, fase por fase.
+```
+
+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 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
@@ -128,6 +142,7 @@ Lee [template/planning/PROTOCOL.md](template/planning/PROTOCOL.md) para el contr
 | Comando | Función |
 |---|---|
 | `ops init [destino]` | Materializa una instancia y la deja usable; sin destino, en `ops/` y modo sidecar. |
+| `ops scan [workspace]` | Inventaría servicios y comandos declarados, sin correr ninguno. |
 | `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. |

package/automatization/runners/antigravity/manifest.json

@@ -39,6 +39,10 @@
     {
       "source": "skills/team/SKILL.md",
       "target": ".agents/plugins/cauce/skills/team/SKILL.md"
+    },
+    {
+      "source": "skills/onboard/SKILL.md",
+      "target": ".agents/plugins/cauce/skills/onboard/SKILL.md"
     }
   ],
   "capabilities": {

package/automatization/runners/antigravity/skills/onboard/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: onboard
+description: Escanea el repositorio y deja escrito el contexto de la empresa y la primera épica.
+---
+
+Es el arranque de una instancia recién creada: `init` la instaló, pero nadie le explicó todavía qué es
+este proyecto. Antes de empezar comprobá que siga vacía —`{{OPS_DIR}}organization/company.md` con sus
+«Por completar» y `{{OPS_DIR}}planning/roadmap/` sin épicas—: reescribir un contexto que alguien ya
+corrigió no deja rastro de lo que se perdió.
+
+El inventario no lo hagas a mano: `node {{OPS_DIR}}tools/ops.js scan --json` devuelve los subproyectos con
+manifiesto propio, su runtime y los comandos que cada uno declara, con el archivo del que salieron.
+Recorrer directorios es determinista y cuesta milisegundos; explorarlo vos cuesta minutos y encuentra lo
+mismo. No corras ningún comando del proyecto: el mapa dice lo que está declarado y de dónde, y
+verificarlo corriéndolo es una historia de la épica, con dueño y tiempo asignado.
+
+Con eso escribí `{{OPS_DIR}}organization/company.md` y `product.md`, la sección «Mapa real» de
+`{{OPS_DIR}}AGENTS.md` con el resultado que obtuviste por comando, y las raíces reales en
+`workspaceRoots` de `{{OPS_DIR}}ops.config.json`, que es lo que un guard usa para bloquear una escritura
+fuera de lugar. Lo deducido va marcado `(supuesto)` y lo que nada sostiene queda «Por definir»: no
+inventes clientes, ingresos ni objetivos.
+
+Credenciales, MCP y el permiso de push no te corresponden. Cada uno va como fila en
+`{{OPS_DIR}}planning/HUMAN_ACTIONS.md` con la acción concreta que lo desbloquea y sin proponer ningún
+valor; las preguntas abiertas, a la sección Ideas de `{{OPS_DIR}}planning/INBOX.md`.
+
+Cerrá escribiendo `epic-001` en `{{OPS_DIR}}planning/roadmap/`: su resultado es que una tarea pueda
+atravesar el ciclo entero, y sus criterios salen de lo que hoy falta —contexto sin supuestos, cada
+comando en verde, el guard de límites probado en las dos direcciones, una tarea piloto en DONE—. Validá
+con `node {{OPS_DIR}}tools/ops.js check planning`. **Nunca promuevas al BACKLOG**: esa firma es humana.

package/automatization/runners/claude/CLAUDE.md

@@ -7,8 +7,9 @@
 @{{OPS_DIR}}planning/rules/system/commits.md
 @{{OPS_DIR}}planning/rules/system/conduct.md
 
-Los hooks de `.claude/settings.json` son obligatorios. Usa `/team` para evaluar si una intención es viable
-y proponer una épica, y `/autobuild` para ejecutar trabajo ya promovido; `/integration-sync` e
+Los hooks de `.claude/settings.json` son obligatorios. En una instancia recién creada, `/onboard` escanea el
+repositorio y deja escrito el contexto de la empresa y la primera épica. Después, `/team` evalúa si una
+intención es viable y propone una épica, y `/autobuild` ejecuta trabajo ya promovido; `/integration-sync` e
 `/integration-promote` gestionan staging local sin escritura remota. Ninguno promueve al BACKLOG.
 
 Antes de iniciar, respeta `{{OPS_DIR}}planning/AWAITING_REVIEW.md` y el mutex de `{{OPS_DIR}}planning/WIP.md`. Si el protocolo y

package/automatization/runners/claude/manifest.json

@@ -29,6 +29,10 @@
       "source": "../../workflows/team.js",
       "target": ".claude/workflows/team.js"
     },
+    {
+      "source": "../../workflows/onboard.js",
+      "target": ".claude/workflows/onboard.js"
+    },
     {
       "source": "../../workflows/agent-eval.js",
       "target": ".claude/workflows/agent-eval.js"

package/automatization/runners/codex/AGENTS.md

@@ -31,6 +31,20 @@ node {{OPS_DIR}}tools/ops.js agents list
 Leé el `SKILL.md` del cargo que corresponda antes de actuar en su terreno, y respetá sus límites. Lo que
 ese cargo debe saber de esta empresa está en `{{OPS_DIR}}organization/roles/<slug>.md`.
 
+## El arranque
+
+En una instancia recién creada nadie le explicó todavía al toolkit qué es este proyecto:
+`{{OPS_DIR}}organization/` llega como molde y el roadmap está vacío. El primer recorrido lo llena, y una vez: reescribir un contexto
+que alguien ya corrigió no deja rastro de lo que se perdió.
+
+Empezá por `node {{OPS_DIR}}tools/ops.js scan --json`, que devuelve los subproyectos con manifiesto propio
+y los comandos que cada uno declara: recorrer el árbol vos mismo cuesta minutos y encuentra lo mismo. Con
+eso escribí `{{OPS_DIR}}organization/`, la sección «Mapa real» de `{{OPS_DIR}}AGENTS.md` con cada comando
+tal como está declarado y de qué archivo salió —sin correrlo—, y las raíces reales en `workspaceRoots`. Lo deducido va marcado `(supuesto)`. Credenciales, MCP y el permiso de push van como
+filas en `{{OPS_DIR}}planning/HUMAN_ACTIONS.md`, sin proponer valores. Cerrá con `epic-001` en
+`{{OPS_DIR}}planning/roadmap/`: que una tarea pueda atravesar el ciclo entero, con criterios que salen de
+lo que falta. Nunca la promuevas.
+
 ## Los equipos
 
 Un equipo es una secuencia de cargos con etapas y exit gates, para evaluar una intención antes de que

package/automatization/runners/gemini/GEMINI.md

@@ -24,6 +24,20 @@ node {{OPS_DIR}}tools/ops.js agents list
 node {{OPS_DIR}}tools/ops.js team list
 ```
 
+## El arranque
+
+En una instancia recién creada nadie le explicó todavía al toolkit qué es este proyecto:
+`{{OPS_DIR}}organization/` llega como molde y el roadmap está vacío. El primer recorrido lo llena, y una vez: reescribir un contexto
+que alguien ya corrigió no deja rastro de lo que se perdió.
+
+Empezá por `node {{OPS_DIR}}tools/ops.js scan --json`, que devuelve los subproyectos con manifiesto propio
+y los comandos que cada uno declara: recorrer el árbol vos mismo cuesta minutos y encuentra lo mismo. Con
+eso escribí `{{OPS_DIR}}organization/`, la sección «Mapa real» de `{{OPS_DIR}}AGENTS.md` con cada comando
+tal como está declarado y de qué archivo salió —sin correrlo—, y las raíces reales en `workspaceRoots`. Lo deducido va marcado `(supuesto)`. Credenciales, MCP y el permiso de push van como
+filas en `{{OPS_DIR}}planning/HUMAN_ACTIONS.md`, sin proponer valores. Cerrá con `epic-001` en
+`{{OPS_DIR}}planning/roadmap/`: que una tarea pueda atravesar el ciclo entero, con criterios que salen de
+lo que falta. Nunca la promuevas.
+
 Nunca omitas aprobaciones, inventes credenciales, escribas remoto, hagas push/deploy o promociones
 trabajo desde INBOX.
 

package/automatization/workflows/onboard.js

@@ -0,0 +1,211 @@
+// Arranque de una instancia recién creada: convierte un repositorio que nadie le explicó al toolkit en
+// contexto escrito —`organization/`, el mapa real de `AGENTS.md`, las raíces de código— y en la primera
+// épica.
+//
+// El orden importa y se pagó caro: la primera versión le pedía a un agente que «inventariara el
+// repositorio», y en una carpeta vacía eso gastó doce minutos para no encontrar nada. Recorrer el árbol
+// es determinista y lo hace `ops scan` en milisegundos; el modelo entra después, y sólo si hay algo
+// sobre lo que decidir. Cuando no lo hay, este recorrido termina en una llamada.
+//
+// Escribe borradores y no decide por nadie: lo deducido queda marcado como supuesto, las credenciales y
+// los sistemas externos van a HUMAN_ACTIONS —R12 se los prohíbe a un runner— y la épica queda sin
+// promover, que sigue siendo la firma humana.
+export const meta = {
+  name: 'onboard',
+  description: 'Inventaría el workspace y deja escrito el contexto de la empresa y la primera épica',
+  whenToUse: 'Primera corrida después de "cauce init", cuando organization/ y el roadmap están vacíos.',
+  phases: [
+    { title: 'Scan', detail: 'Inventario determinista: ops scan, sin modelo recorriendo nada' },
+    { title: 'Draft', detail: 'organization/, mapa real y raíces de código' },
+    { title: 'Human', detail: 'Credenciales, MCP y permisos: lo que no le toca al runner' },
+    { title: 'Epic', detail: 'La épica que deja al ciclo poder correr' },
+    { title: 'Closing', detail: 'check y lo que queda esperando a una persona' },
+  ],
+}
+
+// El prefijo lo completa `automation install`: el runtime no expone `process`, así que la ruta de la
+// raíz ops viaja escrita, relativa a donde se abre la herramienta.
+const ROOT = '{{OPS_DIR}}'.replace(/\/+$/, '') || '.'
+const P = `${ROOT}/planning`
+const ORG = `${ROOT}/organization`
+const HUMAN = `${P}/HUMAN_ACTIONS.md`
+const INBOX = `${P}/INBOX.md`
+const ROADMAP = `${P}/roadmap`
+
+// Lo que la persona ya sabe y el repositorio no puede decir: `/onboard vendemos ruteo a PYMEs de
+// logística`. Entra como hecho; lo que se deduce, no.
+const input = typeof args === 'string' ? { context: args } : (args || {})
+const CONTEXT = String(input.context || '').trim()
+const FORCE = Boolean(input.force)
+
+const BASE = `Nunca inventes clientes, métricas, ingresos, plazos ni responsables. Distinguí lo que leíste ` +
+  `en un archivo de lo que estás suponiendo: lo segundo va marcado "(supuesto)" en el texto que escribas. ` +
+  `No leas archivos de credenciales —.env, *.pem, claves— ni copies su contenido a ningún lado; ` +
+  `.env.example sí, y sólo los nombres de las variables. No corras comandos del proyecto: este recorrido ` +
+  `no ejecuta nada, sólo lee. No escribas en ningún sistema externo y no promuevas trabajo al BACKLOG.`
+
+function finish(result) {
+  log(`Fin: ${JSON.stringify(result)}`)
+  return result
+}
+
+const stop = (reason, detail = '') => {
+  log(`Checkpoint: ${reason}${detail ? ` — ${detail}` : ''}`)
+  return finish({ stopped: true, reason, detail })
+}
+
+const SCAN = {
+  type: 'object', additionalProperties: false, required: ['fresh', 'services'],
+  properties: {
+    fresh: { type: 'boolean' },
+    reason: { type: 'string' },
+    services: { type: 'array', items: { type: 'object', additionalProperties: false,
+      required: ['path'], properties: {
+        path: { type: 'string' },
+        runtimes: { type: 'array', items: { type: 'string' } },
+        // Comando declarado y de qué archivo salió. Verificar que además corra es una historia de la
+        // épica: correr la suite de cada servicio acá convertía el arranque en una espera larga.
+        commands: { type: 'array', items: { type: 'object', additionalProperties: false,
+          required: ['kind', 'command', 'source'], properties: {
+            kind: { type: 'string' }, command: { type: 'string' }, source: { type: 'string' },
+          } } },
+      } } },
+    externals: { type: 'array', items: { type: 'string' } },
+    secrets: { type: 'array', items: { type: 'string' } },
+  },
+}
+
+const WRITTEN = {
+  type: 'object', additionalProperties: false, required: ['files'],
+  properties: {
+    files: { type: 'array', items: { type: 'string' } },
+    assumptions: { type: 'array', items: { type: 'string' } },
+    humanActions: { type: 'array', items: { type: 'string' } },
+    openQuestions: { type: 'array', items: { type: 'string' } },
+  },
+}
+
+phase('Scan')
+
+// Una sola llamada, y todo lo que hace es correr dos comandos y mirar dos archivos. Lo que sigue depende
+// de lo que devuelva, así que gastar más antes de saberlo es gastar a ciegas.
+const state = await agent(
+  `${BASE}\n\nFrom ${ROOT}, run exactly these two commands and report what they printed. Explore nothing ` +
+  `else and open no other file than the two named below.\n` +
+  `1. "node tools/ops.js scan --json": the workspace inventory. Copy each service with its path, its ` +
+  `runtimes and its declared commands, keeping the source file each command came from. Add nothing that ` +
+  `the command did not print.\n` +
+  `2. "node tools/ops.js check planning".\n` +
+  `Then read ${ORG}/company.md and list ${ROADMAP}. Set fresh=true only if the organization file still ` +
+  `carries the mold's "Por completar" placeholders and the roadmap holds nothing but its template and ` +
+  `README; otherwise fresh=false and say in reason what is already written. If .env.example exists at ` +
+  `the workspace root, report the variable names in secrets —names only— and the external services they ` +
+  `point at in externals.`,
+  { schema: SCAN, label: 'inventario' },
+)
+if (!state) return stop('scan-unavailable', 'no se pudo leer el estado del workspace')
+if (!state.fresh && !FORCE) {
+  return stop('ya-arrancado', `${state.reason || 'la instancia ya tiene contexto escrito'}. ` +
+    `Pasá force:true si querés reescribir los borradores.`)
+}
+
+const services = state.services || []
+const listado = services.map((service) => service.path).join(', ')
+log(`${services.length} servicio(s) en el workspace${listado ? `: ${listado}` : ''}`)
+
+// Sin código y sin contexto no hay nada que escribir que no sea inventado, y esa es exactamente la
+// corrida que no puede costar nada: se termina acá, diciendo qué falta y cómo darlo.
+if (!services.length && !CONTEXT) {
+  return stop('sin-contexto', `no hay servicios en el workspace y no me diste contexto, así que no hay ` +
+    `nada que escribir sin inventarlo. Volvé a correrlo cuando estén los repos, o dame el contexto en ` +
+    `una línea: /onboard qué vende la empresa, a quién, y cuál es el objetivo del trimestre.`)
+}
+
+const INVENTARIO = { services, externals: state.externals || [], secrets: state.secrets || [] }
+const EVIDENCE = `Inventario del workspace:\n${JSON.stringify(INVENTARIO)}` +
+  `${CONTEXT ? `\n\nContexto aportado por la persona, que vale como hecho: ${CONTEXT}` : ''}` +
+  `${services.length ? '' : '\n\nNo hay ningún servicio en el workspace: el código todavía no está acá.'}`
+
+phase('Draft')
+
+const drafted = await agent(
+  `${BASE}\n\n${EVIDENCE}\n\nEscribí los borradores de contexto de esta instancia, reemplazando el molde ` +
+  `en vez de comentarlo:\n` +
+  `1. ${ORG}/company.md y ${ORG}/product.md: lo que el contexto aportado y los nombres del repositorio ` +
+  `permiten afirmar. Lo que nada sostiene queda "Por definir" y su pregunta va a openQuestions.\n` +
+  `2. La sección "## Mapa real" de ${ROOT}/AGENTS.md: una entrada por servicio con su ruta, su runtime y ` +
+  `sus comandos **tal como los declara**, diciendo de qué archivo salió cada uno. No afirmes que ` +
+  `funcionan: nadie los corrió. Un servicio sin comandos declarados se escribe así, que es información.\n` +
+  `3. ${ROOT}/ops.config.json: dejá en workspaceRoots las raíces de código reales, que es lo que un guard ` +
+  `usa para bloquear una escritura fuera de lugar. Una raíz de más lo apaga.\n` +
+  `${services.length ? '' : 'Sin servicios, el mapa queda declarado como pendiente, diciendo qué lo ' +
+    'completa.\n'}` +
+  `Devolvé en files cada archivo que tocaste y en assumptions cada supuesto que dejaste marcado.`,
+  { schema: WRITTEN, label: 'contexto' },
+)
+if (!drafted) return stop('draft-unavailable', 'los borradores no devolvieron resultado')
+
+phase('Human')
+
+// Credenciales, MCP y permiso de push no son trabajo del runner: R12 se los prohíbe y R13 exige dejar
+// dicho quién los resuelve y con qué. La fila vale más que la negativa.
+const pending = await agent(
+  `${BASE}\n\n${EVIDENCE}\n\nRegistrá en ${HUMAN} una fila por cada cosa que necesita a una persona, con ` +
+  `la tarea, el estado pendiente, el origen "onboard" y la acción concreta que la desbloquea. Como ` +
+  `mínimo: una por cada credencial que el proyecto espera —dónde se cargan y quién lo hace, sin proponer ` +
+  `ningún valor—, una por cada servicio externo o MCP a conectar —con su alcance y contra qué entorno— y ` +
+  `una por la autoridad del runner, que hoy declara runner.allowPush=false en ops.config.json. Las ` +
+  `preguntas abiertas van a la sección Ideas de ${INBOX}, sin promover: ` +
+  `${JSON.stringify(drafted.openQuestions || [])}`,
+  { schema: WRITTEN, label: 'acciones-humanas' },
+)
+
+phase('Epic')
+
+const epic = await agent(
+  `${BASE}\n\n${EVIDENCE}\n\nSupuestos que quedaron escritos: ${JSON.stringify(drafted.assumptions || [])}\n\n` +
+  `Escribí en ${ROADMAP} la épica epic-001-<slug>.md siguiendo el contrato de ${P}/PROTOCOL.md: ` +
+  `frontmatter epic/title/status/service con status open, criterios **CN** observables, "## Contexto ` +
+  `relevante" con rutas reales e historias con (→ CN) y (service: ruta), cada una de menos de cuatro ` +
+  `horas.\n\n` +
+  `Su resultado es que una tarea pueda atravesar el ciclo entero sin que nadie tenga que volver a ` +
+  `explicar este proyecto. Los criterios salen de lo que hoy falta y son verificables: que organization/ ` +
+  `no tenga supuestos sin confirmar, que cada comando del mapa esté verificado corriéndolo y anotado con ` +
+  `su resultado, que las raíces declaradas hagan que el guard de límites bloquee una escritura afuera y ` +
+  `deje pasar una adentro, y que una tarea piloto real llegue a DONE con evidencia. ` +
+  `${services.length
+    ? 'Verificar los comandos es una historia: nadie los corrió todavía.'
+    : 'La primera historia es traer los repos y declararlos en workspaceRoots.'} ` +
+  `En "## Riesgos y decisiones humanas" citá las filas que quedaron en HUMAN_ACTIONS. No toques BACKLOG.md.`,
+  { schema: { type: 'object', additionalProperties: false, required: ['file'],
+    properties: {
+      file: { type: 'string' }, title: { type: 'string' },
+      criteria: { type: 'array', items: { type: 'string' } },
+      stories: { type: 'array', items: { type: 'string' } },
+    } }, label: 'epica-001' },
+)
+if (!epic) return stop('epic-unavailable', 'la épica no devolvió resultado')
+
+phase('Closing')
+
+const closing = await agent(
+  `${BASE}\n\nFrom ${ROOT}, run "node tools/ops.js check planning" and report whether it passed. If it ` +
+  `failed, repair only what this run wrote —the epic, the config— so it satisfies the contract; never ` +
+  `weaken a criterion to force green.`,
+  { schema: { type: 'object', additionalProperties: false, required: ['passed', 'details'],
+    properties: { passed: { type: 'boolean' }, details: { type: 'string' } } }, label: 'closing-check' },
+)
+if (!closing || !closing.passed) return stop('check-failed', closing ? closing.details : 'sin resultado')
+
+const supuestos = (drafted.assumptions || []).length
+const acciones = ((pending || {}).humanActions || []).length
+log(`Contexto escrito con ${supuestos} supuesto(s) por confirmar y ${acciones} acción(es) humana(s) en ${HUMAN}.`)
+log(`Épica en ${epic.file}, sin promover: revisala, promoví una historia a un hito del BACKLOG y corré /autobuild.`)
+
+return finish({
+  services: services.length,
+  assumptions: supuestos,
+  humanActions: acciones,
+  epic: epic.file,
+  promoted: false,
+})

package/engine/cli/args.js

@@ -14,6 +14,7 @@ const VALUED_FLAGS = new Set([
 // —un agente, típicamente— recibía texto sin ninguna señal de que su bandera no existía.
 const FLAGS = {
   init: ['--name', '--mode', '--force', '--runner', '--integration', '--install', '--no-install'],
+  scan: ['--json'],
   check: ['--json'],
   tree: ['--json', '--no-color'],
   context: ['--json'],

package/engine/cli/ops.js

@@ -14,6 +14,7 @@ const F = require('../core/files')
 const O = require('../core/ownership')
 const CL = require('../core/changelog')
 const M = require('../core/manifest')
+const SC = require('../core/scan')
 const C = require('../config/validate')
 const T = require('../teams/registry')
 const AG = require('../agents/catalog')
@@ -35,6 +36,7 @@ function usage() {
   console.log(`Uso:
   ops init [destino] [--name <nombre>] [--mode embedded|sidecar] [--force]
            [--runner claude|codex|gemini|antigravity] [--integration <proveedor>] [--install|--no-install]
+  ops scan [workspace] [--json]
   ops check <planning-dir> [--json]
   ops tree <planning-dir> [--no-color] [--json]
   ops context <planning-dir> [--json]
@@ -226,6 +228,15 @@ function evaluationBench(root, agent, caso, force) {
   return dir
 }
 
+// Dónde va la instancia cuando nadie eligió destino. Parada frecuente: el dev ya creó `acme-ops/` y
+// corre `init` adentro. Sin esto la instancia caía en `acme-ops/ops/` —una carpeta del toolkit dentro
+// de otra— y el proyecto quedaba llamándose «acme-ops». La carpeta que ya nombra al toolkit es la
+// instancia; no hay una segunda adentro.
+function implicitTarget(cwd) {
+  const base = path.basename(cwd)
+  return base === DEFAULT_TARGET || base.endsWith('-ops') ? '.' : DEFAULT_TARGET
+}
+
 // El nombre sale de la carpeta del proyecto, no de la que aloja la instancia: `ops/` y `acme-ops/`
 // nombran al toolkit, y quien lee `project` en la configuración espera leer «acme».
 function defaultName(root) {
@@ -268,12 +279,15 @@ async function init(target, cli) {
   // nivel deja de distinguir qué es suyo y qué llegó del toolkit. Es el layout que `automation
   // install` ya asume —el wiring del runner va al padre, donde se abre la herramienta—, así que lo
   // único que faltaba era que fuera lo que pasa cuando no se elige nada.
-  const root = path.resolve(target || DEFAULT_TARGET)
+  const root = path.resolve(target || implicitTarget(process.cwd()))
   const mode = cli.value('--mode', target ? 'embedded' : 'sidecar')
   if (!['embedded', 'sidecar'].includes(mode)) fail('--mode debe ser embedded o sidecar.', 2)
   const name = cli.value('--name', defaultName(root))
   const force = cli.has('--force')
-  const existing = fs.existsSync(root) ? fs.readdirSync(root) : []
+  // `.git` no cuenta como contenido: es lo único que hay en la carpeta que alguien acaba de crear y
+  // versionar para la instancia, y el toolkit no escribe nada adentro. Sin esta excepción el camino
+  // más natural —`mkdir acme-ops && git init && cauce init`— pedía `--force` para no pisar nada.
+  const existing = (fs.existsSync(root) ? fs.readdirSync(root) : []).filter((entry) => entry !== '.git')
   if (existing.length && !force) {
     fail(`El destino no está vacío: ${root}. Usa --force para agregar solo archivos faltantes.`)
   }
@@ -306,12 +320,48 @@ async function init(target, cli) {
 
   if (resultado.instalado) {
     check(path.join(root, 'planning'), SIN_BANDERAS)
+    // Una instancia recién instalada funciona y no sabe nada de este proyecto: `organization/` es el
+    // molde y el roadmap está vacío. Llenarlo exige leer el repositorio y decidir qué es cada cosa, que
+    // es justo lo que un CLI determinista no puede hacer; el recorrido vive en el runner, así que lo
+    // único útil acá es decir cuál es y con qué se abre.
+    if (resultado.runner !== BOOT.SIN_RUNNER) {
+      console.log(`  siguiente: abrí ${resultado.runner} en este directorio y corré /onboard`)
+      console.log('    escanea el repositorio y deja escrito el contexto de la empresa y la primera épica')
+    }
     console.log(`  listo: el ciclo empieza en ${path.join(relative || '.', 'planning', 'FLOW.md')}`)
   }
   for (const paso of initSteps(enter, resultado)) console.log(paso)
   if (resultado.error) fail(`${resultado.error}: la instancia quedó creada pero todavía no funciona.`)
 }
 
+// Qué hay en el workspace, antes de que nadie razone sobre él. La raíz ops se saltea: no es un servicio
+// del proyecto, y su `package.json` sólo declara el motor.
+function scan(target, cli) {
+  // Sólo el sidecar tiene su workspace afuera: la instancia es hija de la carpeta donde vive el código.
+  // Cualquier otro modo —embedded, y este mismo repositorio, que es `toolkit`— escanea donde está
+  // parado. Confundirlos hacía que un `scan` sin argumentos se fuera a recorrer la carpeta de al lado.
+  const sidecar = O.mode(process.cwd()) === 'sidecar'
+  const root = path.resolve(target || (sidecar ? path.join(process.cwd(), '..') : '.'))
+  const result = SC.scan(root, sidecar ? process.cwd() : '')
+  if (cli.has('--json')) return console.log(JSON.stringify(result, null, 2))
+  console.log(`workspace ${result.root}`)
+  if (result.rootManifests.length) {
+    console.log(`. ${result.rootManifests.join(', ')}${comandos(result.rootCommands)}`)
+  }
+  for (const service of result.services) {
+    console.log(`${service.path} [${service.runtimes.join(', ')}]${comandos(service.commands)}`)
+  }
+  const total = result.services.length + (result.rootManifests.length ? 1 : 0)
+  console.log(`${total} candidato(s). Cuál es el producto y cuál quedó muerto lo decide una persona.`)
+}
+
+// Sólo lo declarado y de dónde salió: un comando inventado se lee igual que uno real.
+function comandos(commands) {
+  const entries = Object.entries(commands || {})
+  if (!entries.length) return ' — sin comandos declarados'
+  return ` — ${entries.map(([kind, value]) => `${kind}: ${value.command} (${value.source})`).join(', ')}`
+}
+
 function check(dir, cli) {
   const root = path.resolve(dir || '.')
   const errors = []
@@ -1118,6 +1168,7 @@ async function run(cli) {
   }
   const arg = cli.positional
   if (command === 'init') await init(arg[1], cli)
+  else if (command === 'scan') scan(arg[1], cli)
   else if (command === 'check') check(arg[1], cli)
   else if (command === 'tree') tree(arg[1], cli)
   else if (command === 'context') context(arg[1], cli)

package/engine/core/scan.js

@@ -0,0 +1,120 @@
+'use strict'
+
+// Qué hay en el workspace, resuelto por código y no por un modelo. Existe porque el arranque empezaba
+// pidiéndole a un agente que «inventariara el repositorio»: en una carpeta vacía eso gastó doce minutos
+// para no encontrar nada. Recorrer directorios y leer manifiestos es determinista, y lo que no lo es
+// —qué de todo esto es el producto, qué está muerto— recién vale la pena preguntárselo a un modelo
+// cuando esta lista existe.
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+// Lo que nunca es un servicio del proyecto. `node_modules` es el que hace la diferencia entre
+// milisegundos y minutos: adentro hay un manifiesto por dependencia. Los directorios ocultos se saltean
+// enteros —regla, no lista—: ahí viven la configuración del runner, el banco de evaluación y las cachés,
+// y un servicio del producto no se esconde detrás de un punto.
+const IGNORED = new Set([
+  'node_modules', 'vendor', 'dist', 'build', 'target', 'out', 'coverage', 'venv', '__pycache__', 'tmp',
+])
+
+const skippable = (name) => name.startsWith('.') || IGNORED.has(name)
+
+// Un servicio anidado más hondo que esto es una excepción, y recorrer el árbol entero para encontrarlo
+// cuesta más que declararlo a mano en `AGENTS.md`.
+const DEPTH = 3
+
+const MANIFESTS = [
+  { file: 'package.json', runtime: 'node' },
+  { file: 'go.mod', runtime: 'go' },
+  { file: 'pyproject.toml', runtime: 'python' },
+  { file: 'requirements.txt', runtime: 'python' },
+  { file: 'Cargo.toml', runtime: 'rust' },
+  { file: 'composer.json', runtime: 'php' },
+  { file: 'pom.xml', runtime: 'java' },
+  { file: 'build.gradle', runtime: 'java' },
+  { file: 'Gemfile', runtime: 'ruby' },
+  { file: 'Makefile', runtime: 'make' },
+  { file: 'docker-compose.yml', runtime: 'compose' },
+  { file: 'docker-compose.yaml', runtime: 'compose' },
+  { file: 'Dockerfile', runtime: 'docker' },
+]
+
+// Sólo lo declarado, con su archivo: un comando inventado se lee igual que uno real, y el primer Verify
+// de una tarea es donde se descubre que no existe.
+function npmScripts(file) {
+  try {
+    const scripts = JSON.parse(fs.readFileSync(file, 'utf8')).scripts || {}
+    return ['test', 'lint', 'build'].reduce((found, key) => (
+      scripts[key] ? { ...found, [key]: { command: `npm run ${key}`, source: 'package.json' } } : found
+    ), {})
+  } catch { return {} }
+}
+
+function makeTargets(file) {
+  try {
+    const text = fs.readFileSync(file, 'utf8')
+    return ['test', 'lint', 'build'].reduce((found, key) => (
+      new RegExp(`^${key}:`, 'm').test(text)
+        ? { ...found, [key]: { command: `make ${key}`, source: 'Makefile' } }
+        : found
+    ), {})
+  } catch { return {} }
+}
+
+function commandsOf(dir) {
+  const packageJson = path.join(dir, 'package.json')
+  const makefile = path.join(dir, 'Makefile')
+  return {
+    // El Makefile gana sobre los scripts cuando los dos existen: el que envuelve al otro es el que el
+    // proyecto quiere que se corra.
+    ...(fs.existsSync(packageJson) ? npmScripts(packageJson) : {}),
+    ...(fs.existsSync(makefile) ? makeTargets(makefile) : {}),
+  }
+}
+
+function manifestsOf(dir) {
+  return MANIFESTS.filter((entry) => fs.existsSync(path.join(dir, entry.file)))
+}
+
+// Servicios candidatos bajo `root`, sin entrar en `skip` —típicamente la raíz ops, que no es un
+// servicio del proyecto—. El resultado es una lista, no un veredicto: decidir cuál es el producto y
+// cuál quedó muerto sigue siendo trabajo de una persona o de un cargo.
+function services(root, skip = '') {
+  const found = []
+  const excluded = skip ? path.resolve(skip) : ''
+  const walk = (dir, depth) => {
+    const manifests = manifestsOf(dir)
+    if (manifests.length && path.resolve(dir) !== path.resolve(root)) {
+      found.push({
+        path: path.relative(root, dir).split(path.sep).join('/'),
+        runtimes: manifests.map((entry) => entry.runtime),
+        manifests: manifests.map((entry) => entry.file),
+        commands: commandsOf(dir),
+      })
+    }
+    if (depth >= DEPTH) return
+    let entries = []
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch { return }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || skippable(entry.name)) continue
+      const child = path.join(dir, entry.name)
+      if (excluded && path.resolve(child) === excluded) continue
+      walk(child, depth + 1)
+    }
+  }
+  walk(root, 0)
+  return found
+}
+
+// El primer nivel del workspace también puede ser un solo proyecto sin subcarpetas: se reporta aparte
+// para no confundir «un servicio en la raíz» con «no hay nada».
+function scan(root, skip = '') {
+  return {
+    root: path.resolve(root),
+    rootManifests: manifestsOf(root).map((entry) => entry.file),
+    rootCommands: commandsOf(root),
+    services: services(root, skip),
+  }
+}
+
+module.exports = { scan, services, IGNORED, DEPTH }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingeniomaps/cauce",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Sistema portable de planificación y ejecución verificable para cualquier proyecto",
   "keywords": [
     "planning",