@ingeniomaps/cauce 0.15.0 → 0.16.0

package/automatization/hooks/README.md

@@ -39,7 +39,7 @@ runner, mientras la lógica se prueba y mantiene una sola vez en `engine/hooks/r
 | Grupo | Guards | Wrapper |
 |---|---|---|
 | `pre-shell` | destructive, git-add, dependencies, governance, verify | `guard-shell.sh` |
-| `pre-files` | secrets, generated, workspace-boundary, migrations, integration-snapshot | `guard-files.sh` |
+| `pre-files` | secrets, generated, workspace-boundary, engine, migrations, integration-snapshot | `guard-files.sh` |
 | `stop` | planning-drift | `guard-planning-drift.sh` |
 
 Registrar el grupo gasta un proceso por herramienta en lugar de cinco, con el mismo orden y la misma
@@ -51,3 +51,19 @@ Para inspeccionar qué hace cada hook y cuándo se ejecuta:
 ```bash
 node tools/ops.js automation list-hooks .
 ```
+
+## El motor no se edita desde la empresa
+
+`engine` es el único guard cuyo comportamiento depende de dónde corre, y la distinción es deliberada:
+en una instancia bloquea toda escritura bajo `node_modules/@ingeniomaps/cauce`; en el repositorio del
+toolkit —`mode: toolkit` en `ops.config.json`— queda inerte, porque ahí el motor es el producto.
+
+`workspace-boundary` no alcanzaba: en una instalación `node_modules/` cae dentro de la raíz declarada,
+así que editar el motor le parecía legítimo. Y el daño de esa edición es silencioso por partida doble.
+El próximo `npm install` la borra, de modo que el arreglo se pierde justo cuando alguien creyó haberlo
+hecho; y hasta entonces la empresa corre un motor que no coincide con la versión que declara, que es la
+forma habitual de un bug irreproducible.
+
+La regla que codifica: **un problema del motor se reporta y se arregla arriba.** Lo que sí es de cada
+empresa —sus cargos, sus equipos, sus integraciones, su planificación— queda abierto y el guard no lo
+toca.

package/automatization/hooks/guard-engine.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Impide editar el motor instalado por npm. Inerte en el propio toolkit.
+# Implementación compartida: engine/hooks/run.js → engineWrites().
+exec "$(dirname "$0")/run-hook.sh" engine

package/automatization/workflows/agent-eval.js

@@ -7,6 +7,16 @@
 // Si los viera, el caso mediría su capacidad de repetirlos. Y quien juzga no es quien respondió, por
 // la misma razón por la que nadie corrige su propio examen.
 //
+// **Dónde se corre importa.** Un cargo cuyo trabajo es producir artefactos de planning —una épica, una
+// entrada de INBOX— necesita un `planning/` donde escribir sea legítimo. Corrido dentro del repositorio
+// del toolkit, ese directorio es `template/planning`, que se distribuye a cada instalación: el cargo se
+// niega, con razón, y su caso lo cuenta como fallo. Medido así, `product-manager` falla exactamente los
+// dos casos que piden escribir, y ninguno de los otros tres.
+//
+// Por eso el recorrido se niega cuando `mode` es `toolkit`. Dejarlo escrito en este comentario no
+// alcanzaba: un comentario no impide nada, y la primera vez que pasó fue justamente porque estaba
+// documentado y nadie lo leyó a tiempo. Evaluar los cargos que Cauce distribuye exige una instancia.
+//
 // La respuesta no lleva tope de extensión, y eso se probó: con un tope de doce líneas, dos casos que
 // pasan fallaban. Un comportamiento esperado puede exigir seis elementos —«versión, entorno, datos,
 // pasos, frecuencia y artefactos»— y cuatro de esos no entran en doce líneas. El caso define qué hace
@@ -41,6 +51,7 @@ const CASES = {
       },
     } },
     skill: { type: 'string' },
+    mode: { type: 'string' },
   },
 }
 
@@ -80,12 +91,19 @@ const contexto = await agent(
   `1. "node tools/ops.js evaluate ${AGENT} --cases --json" — the cases, verbatim.\n` +
   `2. "node tools/ops.js agents list --json" — set skill to "${ROOT}/<path>/SKILL.md" using the path it ` +
   `printed for ${AGENT}. That command prints paths relative to ${ROOT} and the next agents run from ` +
-  `elsewhere, so the prefix is not optional.`,
+  `elsewhere, so the prefix is not optional.\n` +
+  `Then read ${ROOT}/ops.config.json and set mode to its "mode" field, verbatim.`,
   { schema: CASES, label: 'cases' },
 )
 if (!contexto || !contexto.items || !contexto.items.length) {
   return stop('sin-casos', `${AGENT} no tiene casos, o no se pudieron leer`)
 }
+if (contexto.mode === 'toolkit') {
+  return stop('en-el-toolkit',
+    'este recorrido mide cargos trabajando, y acá no pueden: `planningDir` apunta a la plantilla que ' +
+    'se distribuye, así que un cargo que deba escribir en planning se niega —con razón— y su caso lo ' +
+    'cuenta como fallo. Medido así el resultado no dice nada del cargo. Corrélo desde una instancia.')
+}
 log(`${contexto.items.length} caso(s) de ${AGENT}`)
 
 const veredictos = await pipeline(

package/engine/automation/index.js

@@ -245,6 +245,7 @@ function check(root) {
     'guard-secrets.sh',
     'guard-generated.sh',
     'guard-workspace-boundary.sh',
+    'guard-engine.sh',
     'guard-migrations.sh',
     'guard-dependencies.sh',
     'guard-governance.sh',

package/engine/cli/ops.js

@@ -155,7 +155,6 @@ function init(target) {
   copyTemplate(path.join(PROJECT_ROOT, 'template'), root, {
     '{{PROJECT_NAME}}': name,
     '{{MODE}}': mode,
-    '{{PLANNING_DIR}}': 'planning',
     '{{WORKSPACE_PATH}}': mode === 'embedded' ? '.' : '..',
   }, process.argv.includes('--force'), providerNames())
   // No se copia `.github/`: `ci.yml` valida el toolkit con `npm run ci` —que una instancia no tiene— y

package/engine/config/validate.js

@@ -2,6 +2,20 @@
 
 const MODES = ['embedded', 'sidecar', 'toolkit']
 
+// Campos que existieron y se retiraron. Se nombran en vez de caer en «propiedad desconocida» porque
+// quien actualiza merece saber qué hacer con la línea, no sólo que sobra.
+//
+// `planningDir` era obligatorio y nadie lo honraba: el renderizador de la plantilla lo resolvía
+// siempre a `planning`, y `findOpsRoot` y el registro de integraciones lo tienen escrito a mano. Un
+// campo así no configura, promete. En el propio toolkit decía `template/planning` —el molde que se
+// distribuye—, y un cargo que lo leyó concluyó que ahí vivía la planificación del proyecto.
+//
+// Se retira en vez de honrarse porque la ubicación no es opinable: `findOpsRoot` reconoce un
+// repositorio de operaciones justamente por tener `planning/` en la raíz.
+const RETIRED = {
+  planningDir: 'el motor siempre busca planning/ en la raíz del repositorio. Borrá la línea',
+}
+
 function validateOpsConfig(config) {
   const errors = []
   if (!config || typeof config !== 'object' || Array.isArray(config)) {
@@ -9,18 +23,16 @@ function validateOpsConfig(config) {
   }
   // `cauceVersion` la escribe el toolkit, no la persona: registra de qué versión salió la instancia.
   const allowed = new Set([
-    '$schema', 'cauceVersion', 'project', 'mode', 'planningDir', 'workspaceRoots', 'runner',
+    '$schema', 'cauceVersion', 'project', 'mode', 'workspaceRoots', 'runner',
   ])
   for (const key of Object.keys(config)) {
-    if (!allowed.has(key)) errors.push(`ops.config.json: propiedad desconocida ${key}`)
+    if (RETIRED[key]) errors.push(`ops.config.json: ${key} ya no se usa: ${RETIRED[key]}`)
+    else if (!allowed.has(key)) errors.push(`ops.config.json: propiedad desconocida ${key}`)
   }
   if (typeof config.project !== 'string' || !config.project.trim()) {
     errors.push('ops.config.json: project debe ser un string no vacío')
   }
   if (!MODES.includes(config.mode)) errors.push('ops.config.json: mode inválido')
-  if (typeof config.planningDir !== 'string' || !config.planningDir.trim()) {
-    errors.push('ops.config.json: planningDir debe ser un string no vacío')
-  }
   validateWorkspaces(config.workspaceRoots, errors)
   validateRunner(config.runner, errors)
   return errors

package/engine/hooks/run.js

@@ -324,16 +324,44 @@ function planningDrift(input) {
   block(`Planning o integraciones quedaron desalineados:\n${result.output}`)
 }
 
+// El motor llega por npm y se actualiza por npm. `workspace-boundary` no lo cubre: en una instalación
+// `node_modules/` cae dentro de la raíz declarada, así que editar el motor le parece legítimo.
+//
+// Editarlo desde la empresa rompe dos veces. El próximo `npm install` borra el cambio sin avisar, así
+// que el arreglo se pierde justo cuando alguien creyó haberlo hecho; y hasta entonces la empresa corre
+// un motor que no coincide con la versión que declara, que es la clase de diferencia que aparece como
+// un bug irreproducible. Un problema del motor se reporta y se arregla arriba, no acá.
+//
+// El toolkit se exceptúa, y esa distinción ya estaba escrita: en su `ops.config.json` el modo es
+// `toolkit`. Ahí el motor es el producto y editarlo es exactamente el trabajo.
+function engineWrites(input) {
+  const root = findOpsRoot(process.env.OPS_ROOT || process.env.CLAUDE_PROJECT_DIR || cwdOf(input))
+  if (!root) return
+  let config
+  try { config = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8')) } catch { return }
+  if (config.mode === 'toolkit') return
+  const pkg = path.join(root, 'node_modules', '@ingeniomaps', 'cauce')
+  for (const raw of filesOf(input)) {
+    const file = path.resolve(cwdOf(input), raw)
+    if (file !== pkg && !file.startsWith(`${pkg}${path.sep}`)) continue
+    block(`${raw} pertenece al motor de Cauce, que se actualiza con npm.\n` +
+      'Un cambio acá lo borra el próximo install y mientras tanto corrés un motor que no coincide ' +
+      'con la versión que declarás. Actualizá con "npm update @ingeniomaps/cauce" y reportá el ' +
+      'problema arriba; lo que sí es tuyo son tus cargos, equipos e integraciones.')
+  }
+}
+
 const guards = {
   destructive, 'git-add': gitAdd, secrets, generated, 'workspace-boundary': workspaceBoundary,
   migrations, dependencies, governance, verify, 'planning-drift': planningDrift,
-  'integration-snapshot': integrationSnapshot,
+  'integration-snapshot': integrationSnapshot, engine: engineWrites,
 }
 
 // Grupos por evento: un runner corre el grupo entero en un solo proceso en lugar de un guard por hook.
 const hookGroups = {
   'pre-shell': ['destructive', 'git-add', 'dependencies', 'governance', 'verify'],
-  'pre-files': ['secrets', 'generated', 'workspace-boundary', 'migrations', 'integration-snapshot'],
+  'pre-files': ['secrets', 'generated', 'workspace-boundary', 'engine', 'migrations',
+    'integration-snapshot'],
   stop: ['planning-drift'],
 }
 
@@ -358,6 +386,11 @@ const hookMetadata = [
   { name: 'secrets', event: 'PreToolUse · files', purpose: 'Bloquea escritura de secretos y credenciales.' },
   { name: 'generated', event: 'PreToolUse · files', purpose: 'Impide editar código generado manualmente.' },
   { name: 'workspace-boundary', event: 'PreToolUse · files', purpose: 'Limita escrituras a las raíces declaradas.' },
+  {
+    name: 'engine',
+    event: 'PreToolUse · files',
+    purpose: 'Impide editar el motor instalado: se actualiza con npm.',
+  },
   { name: 'migrations', event: 'PreToolUse · files', purpose: 'Protege migraciones existentes y SQL destructivo.' },
   {
     name: 'integration-snapshot',

package/engine/schemas/ops-config.schema.json

@@ -2,13 +2,12 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "Cauce engine configuration",
   "type": "object",
-  "required": ["project", "mode", "planningDir", "workspaceRoots", "runner"],
+  "required": ["project", "mode", "workspaceRoots", "runner"],
   "properties": {
     "$schema": { "type": "string", "minLength": 1 },
     "cauceVersion": { "type": "string", "minLength": 1 },
     "project": { "type": "string", "minLength": 1 },
     "mode": { "enum": ["embedded", "sidecar", "toolkit"] },
-    "planningDir": { "type": "string", "minLength": 1 },
     "workspaceRoots": {
       "type": "array",
       "minItems": 1,

package/package.json

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

package/template/ops.config.json

@@ -2,7 +2,6 @@
   "$schema": "node_modules/@ingeniomaps/cauce/engine/schemas/ops-config.schema.json",
   "project": "{{PROJECT_NAME}}",
   "mode": "{{MODE}}",
-  "planningDir": "{{PLANNING_DIR}}",
   "workspaceRoots": [
     { "name": "main", "path": "{{WORKSPACE_PATH}}" }
   ],