@ingeniomaps/cauce 0.52.0 → 0.53.1

package/engine/automation/runners.js

@@ -0,0 +1,162 @@
+'use strict'
+
+// El modelo de un adaptador de runner: qué archivos trae, contra qué carpeta se resuelven y cómo se
+// rellenan sus marcadores. Vive aparte de los comandos porque cambia por otra razón —cuando se agrega
+// un runner o se mueve un marcador— y porque `check`, `doctor`, `install` y `uninstall` lo consumen
+// los cuatro igual.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { spawnSync } = require('node:child_process')
+const F = require('../core/files')
+const O = require('../core/ownership')
+
+const RUNNER_NAMES = ['claude', 'codex', 'gemini', 'antigravity']
+
+// Adaptadores y workflows viven en el paquete, no en la instancia: son definiciones que el motor
+// consume y que ninguna empresa edita —`RUNNER_NAMES` es cerrado, así que ni siquiera puede agregar
+// uno propio—. Los hooks sí se quedan en el proyecto: la configuración del runner los nombra por
+// ruta literal y no sabe resolver en cascada.
+//
+// Se busca por `runners/` y no por `automatization/`: toda instancia tiene el segundo —ahí viven sus
+// hooks— y encontrarlo daría por buena una dependencia sin instalar.
+function packagedAutomation(root) {
+  const runners = O.packagePath(root, path.join('automatization', 'runners'))
+  return runners ? path.dirname(runners) : ''
+}
+
+function runnerManifest(root, name) {
+  if (!RUNNER_NAMES.includes(name)) {
+    throw new Error(`runner debe ser ${RUNNER_NAMES.join(', ')}`)
+  }
+  const packaged = packagedAutomation(root)
+  if (!packaged) {
+    throw new Error('no encuentro automatization/: corré "npm install" en la raíz del repo ops')
+  }
+  const file = path.join(packaged, 'runners', name, 'manifest.json')
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')) } catch (error) {
+    throw new Error(`${name}: manifest inválido (${error.message})`)
+  }
+}
+
+// Dónde abre el dev su herramienta, que no siempre es la raíz ops. En modo sidecar el repo ops es
+// un hermano de los repos de producto: `<empresa>-ops/` coordina, `<empresa>/` es lo que se abre.
+// Instalar dentro del sidecar dejaría al runner sin ver una sola línea de código.
+function installRoot(root) {
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8'))
+    if (config.mode === 'sidecar') return path.resolve(root, '..')
+  } catch { /* sin configuración legible, instalar donde está */ }
+  return root
+}
+
+// Cómo se nombra la raíz ops desde ahí: `<empresa>-ops/` en sidecar, vacío cuando coinciden.
+function opsPrefix(root) {
+  const relative = path.relative(installRoot(root), root)
+  return relative ? `${relative.split(path.sep).join('/')}/` : ''
+}
+
+function runnerPaths(root, name, runner) {
+  const automationRoot = packagedAutomation(root)
+  const sourceDir = path.join(automationRoot, 'runners', name)
+  const install = installRoot(root)
+  const configSource = F.assertWithin(
+    sourceDir,
+    path.resolve(sourceDir, runner.config.source),
+    `${name}: config.source`,
+  )
+  const configTarget = F.assertWithin(
+    install,
+    path.resolve(install, runner.config.target),
+    `${name}: config.target`,
+  )
+  return { automationRoot, sourceDir, configSource, configTarget, install }
+}
+
+function resolveItem(paths, root, name, item) {
+  return {
+    automationRoot: paths.automationRoot,
+    opsRoot: root,
+    source: F.assertWithin(
+      paths.automationRoot,
+      path.resolve(paths.sourceDir, item.source),
+      `${name}: source`,
+    ),
+    target: F.assertWithin(
+      paths.install,
+      path.resolve(paths.install, item.target),
+      `${name}: target`,
+    ),
+  }
+}
+
+// Todo lo que un adaptador copia —configuración, instrucciones, workflows— nombra rutas relativas a
+// la carpeta donde se abre la herramienta. Cuando la raíz ops no es esa carpeta, cada una necesita el
+// prefijo. El marcador es explícito en la fuente en vez de adivinarse con reemplazos de texto:
+// `{{OPS_DIR}}` significa "acá va la raíz ops, o nada si coinciden".
+//
+// Un solo render, y `install` escribe exactamente lo que `doctor` compara.
+const OPS_DIR = '{{OPS_DIR}}'
+
+// Un fragmento que varios adaptadores comparten, resuelto contra la raíz de `automatization/`. El
+// arranque es el mismo trabajo en tres formatos —la sección de un `AGENTS.md`, el cuerpo de un
+// `SKILL.md`, el prompt de un `.toml`—, y escrito tres veces hizo lo que hace siempre una copia: dos
+// de ellas anunciaban cinco puntos y enumeraban seis, con el sexto doblado dentro del quinto.
+//
+// El workflow de Claude queda afuera a propósito: es un programa con fases y esquemas, no una prosa
+// enmarcada, así que su arranque no es una copia de éste sino otra cosa.
+//
+// Se resuelve antes que `{{OPS_DIR}}` para que el fragmento también reciba el prefijo, y no anida:
+// lo incluido se copia tal cual.
+const INCLUDE = /\{\{INCLUDE:([^}]+)\}\}/g
+
+function inline(text, automationRoot) {
+  return text.replace(INCLUDE, (_, relative) => {
+    const shared = F.assertWithin(
+      automationRoot,
+      path.resolve(automationRoot, relative.trim()),
+      'INCLUDE',
+    )
+    return fs.readFileSync(shared, 'utf8').trimEnd()
+  })
+}
+
+// `{{OPS_ROOT}}` es la raíz absoluta. La necesita quien no puede deducirla de dónde lo ejecutaron
+// —el puente de Antigravity—, y por eso no reemplaza a `{{OPS_DIR}}`: una ruta absoluta escrita en un
+// archivo se rompe si el proyecto se mueve, así que la lleva sólo el que se queda sin alternativa.
+const OPS_ROOT = '{{OPS_ROOT}}'
+
+function render(file, prefix, automationRoot, opsRoot = '') {
+  return inline(fs.readFileSync(file, 'utf8'), automationRoot)
+    .split(OPS_ROOT).join(opsRoot)
+    .split(OPS_DIR).join(prefix)
+}
+
+function runnerConfig(paths, root) {
+  return JSON.parse(render(paths.configSource, opsPrefix(root), paths.automationRoot, root))
+}
+
+// Runners que además de los archivos necesitan un registro propio para que el wiring cuente. Copiar
+// y quedarse ahí deja un plugin inerte: los archivos están, `doctor` da verde y nada se ejecuta.
+function activated(runner) {
+  if (!runner.activation) return true
+  const result = spawnSync(runner.command, runner.activation.verify, { encoding: 'utf8' })
+  if (result.status !== 0) return null
+  return `${result.stdout || ''}`.includes(runner.activation.expect)
+}
+
+module.exports = {
+  activated,
+  RUNNER_NAMES,
+  OPS_DIR,
+  OPS_ROOT,
+  packagedAutomation,
+  runnerManifest,
+  installRoot,
+  opsPrefix,
+  runnerPaths,
+  resolveItem,
+  inline,
+  render,
+  runnerConfig,
+}

package/engine/cli/catalog.js

@@ -14,8 +14,6 @@ const O = require('../core/ownership')
 const IN = require('./instance')
 const { fail, opsRoot } = require('./io')
 
-// La raíz ops de un comando que no la recibe. El shim `tools/ops.js` la exporta porque sabe dónde
-
 function agentsFork(slug, dir) {
   const root = opsRoot(dir)
   if (!slug) fail('Falta el cargo: ops agents fork <cargo> [ops-root]', 2)
@@ -37,7 +35,7 @@ function agents(action, dir, extra, cli) {
   if (action !== 'list') fail(`Acción de agents desconocida: ${action || '(vacía)'}`, 2)
   const root = opsRoot(dir)
   // Una empresa mantiene sus cargos, no los nuestros: `learn` sobre uno del catálogo se niega, así que
-  // recorrer los 48 para encontrar el suyo es ruido. `--own` es lo que hace ejecutable ese recorrido.
+  // recorrer el catálogo entero para encontrar el suyo es ruido. `--own` hace ejecutable ese recorrido.
   const own = cli.has('--own')
   const system = cli.has('--system')
   const roles = AG.list(root).filter((role) => (own ? !role.system : true) && (system ? role.system : true))
@@ -53,7 +51,7 @@ function agents(action, dir, extra, cli) {
       path: path.relative(root, role.dir).split(path.sep).join('/'),
     }))))
   }
-  // Una línea por cargo, alineadas, para elegir a quién asignarle una tarea sin abrir 47 carpetas.
+  // Una línea por cargo, alineadas, para elegir a quién asignarle una tarea sin abrir una carpeta.
   const width = roles.reduce((max, role) => Math.max(max, role.slug.length), 0)
   for (const role of roles) {
     const mark = role.system ? '' : ' (propio)'
@@ -161,8 +159,7 @@ function learn(agent, cli) {
 
 function evaluate(agent, caso, cli) {
   const root = opsRoot()
-  // De quién son los casos. Se nombra en vez de deducirse del slug: un cargo y un recorrido pueden
-  // llamarse igual sin colisionar, y deducirlo los volvería ambiguos el día que eso pase.
+  // De quién son los casos, resuelto por bandera y no por el slug. Por qué no se deduce, en `subject`.
   const kind = cli.has('--flow') ? 'flow' : 'agent'
   // El banco sólo tiene sentido acá: en una empresa el cargo que se evalúa es suyo —propio o
   // adoptado— y su `planning/` ya es el lugar legítimo donde trabajar.
@@ -206,15 +203,13 @@ function evaluate(agent, caso, cli) {
     for (const warning of [...result.warnings, ...runs.warnings]) console.warn(`⚠ ${warning}`)
     for (const error of errors) console.error(`✗ ${error}`)
     if (errors.length) fail(`\n${errors.length} error(es)`, 1)
-    // El veredicto vigente de cada caso, compuesto sobre todas las corridas, no el de la última: desde
-    // que `--cases` existe una corrida cubre menos casos a propósito, y leer sólo la última decía «1/1
-    // pasan» de un sujeto con los cuatro medidos. Cuándo se midió es un rango cuando hubo más de una,
-    // porque lo compuesto es tan viejo como su parte más rancia.
-    const cuando = runs.state && runs.state.oldest !== runs.state.newest
+    // Cuándo se midió es un rango cuando el veredicto vigente lo aportó más de una corrida. Por qué se
+    // compone en vez de leerse la última, en `composed`.
+    const measuredAt = runs.state && runs.state.oldest !== runs.state.newest
       ? `${runs.state.oldest}…${runs.state.newest}`
       : (runs.state ? runs.state.newest : '')
     const lastRun = runs.state
-      ? `${runs.state.passed}/${runs.state.total} pasan (${cuando})`
+      ? `${runs.state.passed}/${runs.state.total} pasan (${measuredAt})`
       : 'sin correr'
     if (kind === 'flow') {
       return console.log(`✓ ${agent}: ${runs.cases} caso(s) — ${lastRun}, ` +

package/engine/cli/instance.js

@@ -21,6 +21,9 @@ const { fail } = require('./io')
 
 const PROJECT_ROOT = path.resolve(__dirname, '..', '..')
 
+// Proveedores que el toolkit conoce, para saltearlos al copiar la plantilla: su andamiaje
+// —configuración, staging/, proposed/— no se materializa hasta que alguien lo habilite. Antes cada
+// instancia recibía el de un proveedor apagado que quizá no usaba nunca, y que nadie actualizaba.
 function providerNames() {
   try {
     const file = path.join(PROJECT_ROOT, 'template', 'integrations', 'config.json')
@@ -34,7 +37,8 @@ function copyTemplate(source, target, replacements, force, skip = [], quiet = fa
   for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
     if (skip.includes(entry.name)) continue
     const from = path.join(source, entry.name)
-    // npm no incluye un `.gitignore` dentro de un tarball, así que viaja sin punto y se restituye
+    // npm no incluye un `.gitignore` dentro de un tarball —comprobado con `npm pack --dry-run` en npm
+    // 11.16.0: lo deja afuera en la raíz y en subdirectorios—, así que viaja sin punto y se restituye
     // acá. Sin esto el archivo existe en el repo del toolkit y desaparece para todo consumidor real.
     const to = path.join(target, entry.name === 'gitignore' ? '.gitignore' : entry.name)
     if (entry.isDirectory()) copyTemplate(from, to, replacements, force, skip, quiet)
@@ -99,9 +103,9 @@ function undeclareEngine(manifest) {
   if (!('@ingeniomaps/cauce' in dev)) return []
   delete dev['@ingeniomaps/cauce']
   pkg.devDependencies = dev
-  const generado = !Object.keys(dev).length && !Object.keys(pkg.dependencies || {}).length
+  const ours = !Object.keys(dev).length && !Object.keys(pkg.dependencies || {}).length
     && !Object.keys(pkg.scripts || {}).length && pkg.private === true && pkg.version === '0.0.0'
-  if (generado) {
+  if (ours) {
     fs.rmSync(manifest, { force: true })
     return ['package.json (lo había creado init: sin dependencias ni scripts propios)']
   }
@@ -110,9 +114,6 @@ function undeclareEngine(manifest) {
   return ['package.json: se quitó la dependencia del motor y el resto queda como estaba']
 }
 
-// Proveedores que el toolkit conoce, para saltearlos al copiar la plantilla: su andamiaje
-// —configuración, staging/, proposed/— no se materializa hasta que alguien lo habilite. Antes cada
-
 // El andamiaje de una instancia, sin leer argv. `init` es la cáscara que traduce banderas a esto, y
 // el banco de evaluación lo llama directo: crear una instancia programáticamente no puede depender de
 // cómo venga escrita la línea de comandos.
@@ -123,8 +124,8 @@ function scaffold(root, { name, mode, force = false, quiet = false }) {
     '{{WORKSPACE_PATH}}': mode === 'embedded' ? '.' : '..',
   }, force, providerNames(), quiet)
   // No se copia `.github/`: `ci.yml` valida el toolkit con `npm run ci` —que una instancia no tiene— y
-  // el ciclo de aprendizaje dejó de distribuirse en 0.4.0. Copiar salteando los dos únicos archivos
-  // que existen dejaba `.github/workflows/` vacío en cada instancia.
+  // el ciclo de aprendizaje dejó de distribuirse en 0.4.0. Copiar salteando lo que no aplica dejaba
+  // `.github/workflows/` vacío en cada instancia.
   copyRuntime(
     path.join(PROJECT_ROOT, 'automatization', 'hooks'),
     path.join(root, 'automatization', 'hooks'),
@@ -173,7 +174,7 @@ function instanceVersion(root) {
 // Lo cuenta el mismo parser que usan `check` y `tree`, no una expresión regular propia: los moldes traen
 // ejemplos comentados, y contarlos a mano anunciaba una tarea en cola y otra terminada en una instancia
 // recién creada. Un aviso que exagera lo que se pierde se deja de leer igual que uno que lo minimiza.
-function loQueSePierde(root) {
+function whatIsLost(root) {
   const planning = path.join(root, 'planning')
   const queued = P.readBacklog(planning).reduce((total, hito) => total + (hito.tasks || []).length, 0)
   const humanActions = ST.pendingHumanActions(planning).length
@@ -200,7 +201,7 @@ function destroy(dir, cli) {
   }
   if (O.mode(root) === 'toolkit') fail(`${root} es el toolkit: acá se fabrica Cauce, no se lo borra.`, 2)
 
-  const loss = loQueSePierde(root)
+  const loss = whatIsLost(root)
   const lines = [
     loss.epicas && `${loss.epicas} épica(s) en el roadmap`,
     loss.enCola && `${loss.enCola} tarea(s) en la cola`,

package/engine/cli/io.js

@@ -4,12 +4,12 @@ const path = require('node:path')
 
 // Terminar la corrida con un mensaje y un código. Vive aparte porque lo usa cada familia de comandos, y
 // dejarlo en el despacho obligaría a que cada módulo dependa del que lo invoca.
-
 function fail(message, code = 1) {
   console.error(message)
   process.exit(code)
 }
 
+// La raíz ops de un comando que no la recibe. El shim `tools/ops.js` la exporta porque sabe dónde
 // vive: sin eso, invocarlo desde otra carpeta —lo normal en sidecar— la resolvía contra el cwd.
 function opsRoot(dir) {
   return path.resolve(dir || process.env.OPS_ROOT || '.')

package/engine/cli/ops.js

@@ -32,15 +32,10 @@ const BOOT = require('./bootstrap')
 // Dónde aterriza una instancia cuando nadie eligió: una carpeta propia junto al código.
 const DEFAULT_TARGET = 'ops'
 
-// Cuántos servicios se listan en pantalla antes de recortar. El resto sigue en `--json`, que es lo que
-// consume el recorrido de arranque: recortar la lista es para leerla, no para acotar lo que se sabe.
-
 // 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.
-// instancia recibía el de un proveedor apagado que quizá no usaba nunca, y que nadie actualizaba.
-
 function implicitTarget(cwd) {
   const base = path.basename(cwd)
   return base === DEFAULT_TARGET || base.endsWith('-ops') ? '.' : DEFAULT_TARGET
@@ -55,10 +50,19 @@ function defaultName(root) {
 
 // El motor no se instala solo: `npm install` baja el paquete que `init` acaba de declarar, y sin él el
 // shim, los cargos, los equipos y los adaptadores no se resuelven. Correrlo desde acá es lo que hace que
-// una instalación sea un comando y no una lista. En Windows el ejecutable es `npm.cmd`.
+// una instalación sea un comando y no una lista.
+//
+// En Windows no alcanza con nombrarlo `npm.cmd`. Node documenta que un `.cmd` «no es ejecutable por sí
+// solo» y nombra como salida lanzar cmd.exe con el comando de argumento —nodejs.org/api/child_process,
+// consultado 2026-08-29—, que es lo que va acá. La otra salida obvia queda descartada: pasar `args`
+// junto a la opción `shell` está deprecado en runtime (DEP0190, nodejs.org/api/deprecations).
+//
+// Documentado y no comprobado: acá no hay Windows, y ninguna prueba llega a esta línea porque el
+// arranque recibe `npm` inyectado.
 function npmInstall(root) {
-  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm'
-  const result = spawnSync(npm, ['install'], { cwd: root, stdio: 'inherit' })
+  const result = process.platform === 'win32'
+    ? spawnSync('cmd.exe', ['/c', 'npm', 'install'], { cwd: root, stdio: 'inherit' })
+    : spawnSync('npm', ['install'], { cwd: root, stdio: 'inherit' })
   if (result.error) {
     console.error(`  no pude ejecutar npm (${result.error.code || result.error.message}).`)
     return 1
@@ -179,8 +183,6 @@ function usage() {
 // molde y no del wiring del runner, así que pasarle el suyo instalaría a la fuerza algo que nadie pidió.
 const NO_FLAGS = { has: () => false, value: (_flag, fallback = '') => fallback }
 
-// Si el proveedor terminó su propia configuración. Son dos interruptores y `sync` exige los dos: el
-
 async function run(cli) {
   const [command] = cli.positional
   if (!command || ['help', '--help', '-h'].includes(command)) return usage()

package/engine/cli/wiring.js

@@ -14,9 +14,10 @@ const OB = require('../core/onboarding')
 const IN = require('./instance')
 const { fail, opsRoot } = require('./io')
 
+// Cuántos servicios se listan en pantalla antes de recortar. El resto sigue en `--json`, que es lo que
+// consume el recorrido de arranque: recortar la lista es para leerla, no para acotar lo que se sabe.
 const MAX_LISTED = 20
 
-
 const INTEGRATION = {
   list: {
     run: (root) => {
@@ -111,9 +112,6 @@ const INTEGRATION = {
   },
 }
 
-// Dónde puede mirar una instancia: exactamente las raíces que declara, y nada por encima de ellas. Sale
-// de `ops.config.json` en vez de suponerse —el sidecar declara `..`, el embebido `.`— para que acotar las
-// raíces acote también el escaneo, y para que nadie termine recorriendo la carpeta de al lado.
 // Las tres reconciliaciones son el mismo comando con otra operación: se declaran en el mismo lugar
 // para que agregar una cuarta no pida tocar el despachador.
 for (const operation of ['reset', 'rebase', 'reconcile']) {

package/engine/config/validate.js

@@ -6,7 +6,8 @@ const MODES = ['embedded', 'sidecar', 'toolkit']
 // quien actualiza merece saber qué hacer con la línea, no sólo que sobra.
 //
 // `planningDir` no configuraba, prometía: nadie lo honraba y la ubicación no es opinable —`findOpsRoot`
-// reconoce una raíz ops justamente por tener `planning/` en la raíz—.
+// reconoce una raíz ops por tener `ops.config.json` y `planning/` en ella, así que moverlo la
+// desconocería—.
 const RETIRED = {
   planningDir: 'el motor siempre busca planning/ en la raíz del repositorio. Borrá la línea',
 }

package/engine/core/frontmatter.js

@@ -6,7 +6,8 @@
 // draft se leía distinto según quién lo abriera.
 //
 // Se resuelve por el lado estricto: frontmatter es lo que encabeza el documento, y un `---` en el medio
-// es una línea horizontal de markdown. La clave admite lo que admite YAML.
+// es una línea horizontal de markdown. La clave admite letras, dígitos, `_` y `-` —de ahí sale la
+// discrepancia del dígito inicial, resuelta a favor de admitirlo—, y no lo que admitiría YAML entero.
 
 function frontmatter(text) {
   const block = (String(text).match(/^---\s*\n([\s\S]*?)\n---/) || [])[1] || ''

package/engine/core/ownership.js

@@ -117,8 +117,8 @@ function mode(root) {
   }
 }
 
-// Dónde quedó el motor. El bridge de Antigravity repite esta cascada a mano porque corre antes de
-// poder cargar este módulo: si cambia acá, cambia allá.
+// Dónde quedó el motor. El bridge de Antigravity y `run-hook.sh` repiten esta cascada a mano porque
+// corren antes de poder cargar este módulo: si cambia acá, cambia en los dos.
 function engineAt(root, relative = '') {
   return packagePath(root, relative ? path.join('engine', relative) : 'engine')
 }
@@ -200,8 +200,9 @@ function retiredWithLearning(root) {
 }
 
 // Rutas que `upgrade` reemplaza. Todo lo que no aparezca acá pertenece al proyecto.
-// Se listan aunque todavía no existan en la instancia: así un archivo nuevo del sistema llega en
-// vez de esperar a que alguien lo cree a mano.
+// Los archivos sueltos se listan aunque todavía no existan en la instancia, así que uno nuevo del
+// sistema llega en vez de esperar a que alguien lo cree a mano. Una colección no: entra sólo si su
+// `system/` ya está, porque el que se lista es el directorio y no cada archivo de adentro.
 function systemPaths(root) {
   const paths = [...SYSTEM_FILES]
   for (const collection of SYSTEM_COLLECTIONS) {

package/engine/core/scan.js

@@ -171,6 +171,9 @@ function scan(root, skip = '') {
   }
 }
 
+// Dónde puede mirar una instancia: exactamente las raíces que declara, y nada por encima de ellas. Sale
+// de `ops.config.json` en vez de suponerse —el sidecar declara `..`, el embebido `.`— para que acotar las
+// raíces acote también el escaneo, y para que nadie termine recorriendo la carpeta de al lado.
 function workspaceRoots(root) {
   try {
     const config = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8'))

package/engine/flows/registry.js

@@ -101,8 +101,8 @@ function slugsIn(dir) {
   } catch { return [] }
 }
 
-// Un slug aparece una sola vez aunque exista en los dos niveles: el del proyecto ya ganó.
-// Los propios de la empresa y los que trae Cauce, sin duplicar un slug que ya ganó el proyecto.
+// Los propios de la empresa y los que trae Cauce, con cada slug una sola vez aunque exista en los
+// dos niveles: el del proyecto ya ganó.
 function list(root) {
   const system = systemTeams(root)
   const slugs = new Set([

package/engine/hooks/files.js

@@ -0,0 +1,160 @@
+'use strict'
+
+// Los guards que juzgan lo que está por escribirse: un secreto, un archivo generado, una migración,
+// una prueba que se apaga, el motor de la dependencia. Todos leen el contenido entrante y no el disco
+// —lo que ya estaba no lo escribió este cambio— y son el grupo `pre-files` del registro.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { patchOf, filesOf, contentOf, cwdOf, block, configOf, findOpsRoot } = require('./input')
+
+function secrets(input) {
+  for (const file of filesOf(input)) {
+    const base = path.basename(file)
+    if (/^(?:\.env|\.env\..+)$/.test(base) && !/\.(?:example|sample|template|schema|dist|tpl)$/.test(base)) {
+      block(`${file} parece contener secretos. Edita una plantilla o registra una acción humana.`)
+    }
+    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_rsa` y sus tres
+    // hermanas una clave privada de SSH, y `credentials` las de AWS. Los cuatro son estándar, no
+    // exóticos — y las claves SSH van por nombre de algoritmo, no por prefijo.
+    //
+    // 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.`)
+    }
+  }
+}
+
+function integrationSnapshot(input) {
+  for (const raw of filesOf(input)) {
+    const file = raw.replace(/\\/g, '/')
+    if (/(?:^|\/)integrations\/[^/]+\/staging\/(?:.+\/remote\.json|sync-state\.json)$/.test(file)) {
+      block(`${file} pertenece al sincronizador. Cura draft.md; no edites snapshots a mano.`)
+    }
+  }
+}
+
+function generated(input) {
+  for (const raw of filesOf(input)) {
+    const file = raw.replace(/\\/g, '/')
+    const base = path.basename(file)
+    if (/(?:^|[._-])generated\.[^.]+$/i.test(base) || /(?:^|[._-])gen\.(?:go|ts|js|py)$/i.test(base)) {
+      block(`${file} parece código generado. Modifica su fuente y ejecuta el generador; no lo edites a mano.`)
+    }
+  }
+}
+
+// Las dos formas de que una prueba deje de juzgar sin que nadie lo note: apagarla o borrarla. Ninguna
+// sale roja —el runner informa una suite verde más corta—, así que el verde pasa de decir «el
+// comportamiento está» a decir «nadie lo miró», y `verify` tampoco lo ve porque también lee exit codes.
+// Lo que se inspecciona es el contenido entrante, no el archivo: una marca que ya estaba no la apagó
+// este cambio.
+const TEST_OFF = [
+  [/\b(?:describe|context|it|test|suite)\s*\.\s*(?:skip|only|todo)\b/, 'skip/only'],
+  [/\b[xf](?:it|test|describe|context)\s*[("'`]/, 'xit/fit'],
+  [/\bt\.Skip(?:Now)?\s*\(/, 't.Skip'],
+  [/@pytest\.mark\.(?:skip|skipif|xfail)\b/, 'pytest.mark.skip'],
+  [/@unittest\.skip/, 'unittest.skip'],
+  [/@(?:Ignore|Disabled)\b/, 'Ignore/Disabled'],
+  [/#\[ignore\]/, 'ignore'],
+]
+
+function isTestFile(raw) {
+  const file = raw.replace(/\\/g, '/')
+  const base = path.basename(file)
+  return /(?:^|\/)(?:tests?|specs?|__tests__)\//i.test(file)
+    || /\.(?:test|spec)\.[jt]sx?$/i.test(base)
+    || /_(?:test|spec)\.(?:go|py|rb|ts|js|jsx|tsx|rs|exs?)$/i.test(base)
+    || /^test_.+\.py$/i.test(base)
+}
+
+function testEvidence(input) {
+  if (process.env.OPS_TEST_EVIDENCE_OVERRIDE === '1') return
+  const why = 'Una prueba apagada no falla y una suite sin ella sale verde igual: el verde deja de ' +
+    'decir que el comportamiento está y pasa a decir que nadie lo miró.\n' +
+    'Si la aserción está mal, corregila; si el comportamiento cambió, cambialo junto con la prueba que ' +
+    'lo fija. Si tiene que quedar afuera igual —flake conocido, entorno que acá no existe—, es una ' +
+    'decisión con dueño: OPS_TEST_EVIDENCE_OVERRIDE=1 y que conste en el commit.'
+  for (const match of patchOf(input).matchAll(/^\*\*\* Delete File:\s*(.+)$/gm)) {
+    const removed = match[1].trim()
+    if (isTestFile(removed)) block(`${removed} borra una prueba.\n${why}`)
+  }
+  const content = contentOf(input)
+  if (!content) return
+  for (const raw of filesOf(input)) {
+    if (!isTestFile(raw)) continue
+    for (const [marca, nombre] of TEST_OFF) {
+      if (marca.test(content)) block(`${raw} apaga una prueba con ${nombre}.\n${why}`)
+    }
+  }
+}
+
+function workspaceBoundary(input) {
+  const root = findOpsRoot(process.env.OPS_ROOT || process.env.CLAUDE_PROJECT_DIR || cwdOf(input))
+  if (!root) return
+  const config = configOf(root)
+  const allowed = [root, ...(config.workspaceRoots || []).map((entry) => path.resolve(root, entry.path))]
+  for (const raw of filesOf(input)) {
+    const file = path.resolve(cwdOf(input), raw)
+    if (!allowed.some((base) => file === base || file.startsWith(`${base}${path.sep}`))) {
+      block(`${file} está fuera de las raíces declaradas en ops.config.json.`)
+    }
+  }
+}
+
+function migrations(input) {
+  if (process.env.OPS_MIGRATIONS_OVERRIDE === '1') return
+  // Cada rama cierra su propio límite. Cuando el `\b` estaba al final del grupo se aplicaba a las tres, y
+  // la de `delete` termina a propósito en `;`: después de un punto y coma no hay límite de palabra, así que
+  // `DELETE FROM pedidos;` —la forma que tiene en cualquier migración— pasaba y sólo frenaba la variante sin
+  // punto y coma. `drop column` y `drop constraint` faltaban: pierden datos y garantías igual que `drop table`.
+  const destructiveSql = new RegExp(
+    String.raw`\bdrop\s+(?:table|database|schema|column|constraint)\b` +
+      String.raw`|\btruncate\b` +
+      String.raw`|\bdelete\s+from\s+\S+\s*(?:;|$)`,
+    'i',
+  )
+  if (destructiveSql.test(contentOf(input))) {
+    block('La migración contiene SQL destructivo. Requiere revisión y OPS_MIGRATIONS_OVERRIDE=1.')
+  }
+  for (const raw of filesOf(input)) {
+    const normalized = raw.replace(/\\/g, '/')
+    if (!/(?:^|\/)(?:migrations?|migrate)\/.*\.sql$/i.test(normalized)) continue
+    const file = path.resolve(cwdOf(input), raw)
+    if (fs.existsSync(file)) {
+      block(`${raw} es una migración existente. Crea una nueva en vez de reescribir historial.`)
+    }
+  }
+}
+
+// Hace falta un guard aparte porque `workspace-boundary` no lo cubre: `node_modules/` cae dentro de
+// la raíz declarada, así que editar el motor le parece legítimo.
+//
+// Editarlo rompe dos veces: el próximo `npm install` borra el cambio sin avisar, y hasta entonces la
+// empresa corre un motor que no coincide con la versión que declara —la clase de diferencia que
+// aparece como un bug irreproducible—. En modo `toolkit` no aplica: ahí el motor es el producto.
+function engineWrites(input) {
+  const root = findOpsRoot(process.env.OPS_ROOT || process.env.CLAUDE_PROJECT_DIR || cwdOf(input))
+  if (!root) return
+  const config = configOf(root)
+  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 llega por 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. Para traer una versión nueva son dos pasos —el motor y después ' +
+      'las rutas del sistema de tu instancia—:\n' +
+      '  npm install --save-dev --save-exact @ingeniomaps/cauce@latest\n' +
+      '  node tools/ops.js upgrade\n' +
+      'Y reportá el problema arriba. Lo que sí es tuyo son tus cargos, equipos e integraciones.')
+  }
+}
+
+module.exports = { secrets, integrationSnapshot, generated, testEvidence, workspaceBoundary, migrations, engineWrites }