@ingeniomaps/cauce 0.97.0 → 0.99.0

package/engine/hooks/migrations.js

@@ -0,0 +1,93 @@
+'use strict'
+
+// El guard `migrations`: no reescribir una migración que ya viajó y no aplicar un borrado sin que una
+// persona lo apruebe. Qué archivo es una migración, qué parte aplica y qué cuenta como destruir lo decide
+// `core/migrations`, que `check` también lee.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { spawnSync } = require('node:child_process')
+const { filesOf, contentOf, patchOf, cwdOf, block, configOf, opsRoot } = require('./input')
+const AP = require('./approval')
+const M = require('../core/migrations')
+
+// Si la migración ya viajó a otra copia, que es lo que el bloqueo de abajo quiere saber y `existsSync`
+// no contesta. Devuelve el motivo del bloqueo o cadena vacía.
+//
+// **`HEAD` y no el índice**: un archivo apenas `git add`eado no viajó a ninguna parte, y `git ls-files`
+// lo daría por historial. Y **resolver la raíz es una pregunta aparte** de si el archivo está en `HEAD`:
+// las dos fallan con 128 y confundirlas repite el error que este caso arregla —decidir por la respuesta
+// equivocada—. Sin raíz resoluble se degrada a la conducta de antes, que bloquea de más, porque cuando
+// no se puede saber ése es el lado correcto para equivocarse. Es la degradación que `check` ya declara
+// cuando no puede resolver el repositorio de un servicio. Caso 086.
+function alreadyShipped(file) {
+  if (!fs.existsSync(file)) return ''
+  const cwd = path.dirname(file)
+  const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' })
+  if (top.status !== 0) {
+    return 'existe, y acá no hay repositorio con el que saber si ya viajó a otra copia'
+  }
+  const rel = path.relative(top.stdout.trim(), file).split(path.sep).join('/')
+  return spawnSync('git', ['cat-file', '-e', `HEAD:${rel}`], { cwd }).status === 0
+    ? 'ya está en el historial del repositorio'
+    : ''
+}
+
+const approved = (input, file) => !AP.pending(opsRoot(input), [file], input).length
+
+// El `Edit` trae lo que reemplaza; el archivo en disco dice dónde cae (caso 185). Se lo lee sólo para
+// ubicar el fragmento: lo que ya estaba no se juzga.
+function editOf(input, file) {
+  const fields = input.tool_input || {}
+  if (typeof fields.old_string !== 'string' || typeof fields.content === 'string') return {}
+  let disk = null
+  try { disk = fs.readFileSync(file, 'utf8') } catch { /* sin archivo se juzga el fragmento */ }
+  return { disk, old: fields.old_string, all: fields.replace_all === true }
+}
+
+function migrations(input) {
+  if (process.env.OPS_MIGRATIONS_OVERRIDE === '1') return
+  // Las dos condiciones deciden sobre el mismo alcance, y por eso comparten el filtro. El bloqueo por
+  // SQL destructivo corría antes de este bucle, o sea sobre el contenido y sin mirar la ruta que ya
+  // tenía a mano: frenaba un ADR que citaba la migración o un comentario que advertía que eso no se
+  // hace, y encima afirmaba «La migración contiene…» sobre un archivo que no lo era. Un guard que
+  // frena donde no corresponde enseña a apagarlo, que es la salida más ancha que hay.
+  //
+  // El precio de compartir el filtro es que una migración escrita fuera de las carpetas declaradas deja de
+  // frenarse. Es deliberado: el otro chequeo ya vivía con esa convención, y dos condiciones de la misma
+  // función con dos alcances distintos es lo que hizo falta arreglar acá.
+  const root = opsRoot(input)
+  const isMigration = M.pattern(root ? configOf(root) : {})
+  // Un parche trae varios archivos en un sobre: cada uno se juzga por su sección, no por el sobre entero.
+  const sections = M.patchSections(patchOf(input))
+  for (const raw of filesOf(input)) {
+    const normalized = raw.replace(/\\/g, '/')
+    if (!isMigration.test(normalized)) continue
+    if (approved(input, normalized)) continue
+    const file = path.resolve(cwdOf(input), raw)
+    // El mensaje nombra el archivo y la sentencia: un falso positivo se lee igual que un bloqueo correcto
+    // mientras no diga sobre qué está decidiendo. Y cuando la migración se partió, dice que la reversión
+    // no se juzgó, para que quien lo lea no busque la sentencia en el bloque equivocado.
+    const section = sections.get(raw)
+    const scope = section
+      ? M.judgedPatch(normalized, section)
+      : M.judged(normalized, contentOf(input), editOf(input, file))
+    const found = M.destructive(scope.text)
+    if (found) {
+      const where = scope.label ? ` en el bloque que aplica (la reversión, \`${scope.label}\`, no se juzga)` : ''
+      block(`${raw} contiene ${found.kind}${where}: \`${found.what}\`.\n`
+        + AP.HOW('OPS_MIGRATIONS_OVERRIDE', [normalized], input))
+    }
+    // El mensaje nombra el hecho que sostiene el bloqueo y no su interpretación: «historial» era una
+    // lectura que `existsSync` no podía dar, y se la daba igual sobre stubs de la misma sesión. Y lleva
+    // la salida angosta, que hasta 0.79.0 sólo tenía el bloqueo hermano: éste es el que aparece en el
+    // flujo normal de escribir una migración, así que era justo el que no podía quedarse sin decirla.
+    const shipped = alreadyShipped(file)
+    if (shipped) {
+      block(`${raw} ${shipped}. Crea una nueva en vez de reescribirla.\n`
+        + AP.HOW('OPS_MIGRATIONS_OVERRIDE', [normalized], input))
+    }
+  }
+}
+
+module.exports = { migrations }

package/engine/hooks/push.js

@@ -105,7 +105,7 @@ function liveMessage(live, input) {
   // una sesión real, con «pegando tal cual» a secas el agente se ofreció a escribirse la aprobación.
   return `'git push' publica cambios en ${names}, la rama viva, y requiere una acción humana: ni `
     + 'runner.allowPush ni una orden en el chat llegan ahí sin un permiso por rama. Decile a la persona qué '
-    + 'se frenó y esperá: un «dale» no lo destraba. Lo da ella, nombrando la rama en '
+    + 'se frenó y esperá: confirmarlo en el chat no lo destraba. Lo da ella, nombrando la rama en '
     + 'runner.pushToLiveBranches de ops.config.json, que la deja como una rama de trabajo'
     + (lines.length ? `, o pegando ella tal cual en ${AP.where(input)} estas líneas:\n`
       + lines.map((line) => `  ${line}\n`).join('') : '.')
@@ -113,11 +113,14 @@ function liveMessage(live, input) {
 
 function workMessage(items, input) {
   const lines = items.filter((item) => item.startsWith('push '))
-  const chat = CHAT.hold(input, items)
-  const how = chat
-    ? 'Decile a la persona qué se frenó y esperá: si contesta «dale», reintentá el mismo push y pasa. '
+  const held = CHAT.hold(input, items)
+  const dropped = held ? held.dropped : []
+  const chat = held && dropped.length < items.length
+  const how = (dropped.length ? AP.REFUSED(dropped, input) : '') + (chat
+    ? 'Decile a la persona qué se frenó y pedile que lo confirme con sus palabras: si lo que contesta es un '
+      + 'sí, reintentá el mismo push y pasa; si duda, pregunta o dice que no, no reintentes. '
       + 'También pasa si lo pide nombrando el remoto y la rama, como «subí feat/x a origin».'
-    : 'Lo destraba una persona pidiéndolo en el chat con el remoto y la rama.'
+    : 'Lo destraba una persona pidiéndolo en el chat con el remoto y la rama.')
   const paste = lines.length
     ? `\nSi prefiere aprobarlo a mano, que pegue ella tal cual en ${AP.where(input)} estas líneas:\n`
       + lines.map((line) => `  ${line}\n`).join('')

package/engine/hooks/run.js

@@ -13,6 +13,7 @@ const { readInput, block, opsRoot } = require('./input')
 const shell = require('./shell')
 const { verify } = require('./verify')
 const files = require('./files')
+const { migrations } = require('./migrations')
 const chat = require('./chat')
 const { secretsShell } = require('./secrets-shell')
 const { opsConfig, opsConfigShell } = require('./ops-config')
@@ -50,7 +51,7 @@ const guards = {
   generated: files.generated,
   'workspace-boundary': files.workspaceBoundary,
   engine: files.engineWrites,
-  migrations: files.migrations,
+  migrations,
   'integration-snapshot': files.integrationSnapshot,
   'test-evidence': files.testEvidence,
   'plan-first': files.planFirst,
@@ -145,8 +146,10 @@ const hookMetadata = [
   {
     name: 'migrations',
     event: 'PreToolUse · files',
-    purpose: 'Protege migraciones existentes y bloquea SQL destructivo, sobre las extensiones que el '
-      + 'proyecto declare en migrations.extensions — sólo .sql si no declara ninguna.',
+    purpose: 'Protege migraciones existentes y bloquea SQL destructivo o el borrado con la API del ORM en la '
+      + 'parte que aplica —no en su reversión—, sobre las extensiones y carpetas que el proyecto declare en '
+      + 'migrations.extensions y migrations.paths — sólo .sql bajo migrations/, migration/ o migrate/ si no '
+      + 'declara nada.',
   },
   {
     name: 'integration-snapshot',
@@ -194,11 +197,13 @@ function executeAll(names, input) {
   for (const name of resolve(names)) execute(name, input)
 }
 
+// Asíncrono sólo por la lectura de stdin, que necesita un plazo (`input.js`); los guards siguen siendo
+// sincrónicos y `executeAll` también, así que quien los llama directo no cambia.
 if (require.main === module) {
-  try { executeAll(process.argv.slice(2), readInput()) } catch (error) {
+  readInput().then((input) => executeAll(process.argv.slice(2), input)).catch((error) => {
     console.error(`BLOQUEADO: ${error.message}`)
     process.exit(error.blocked ? 2 : 1)
-  }
+  })
 }
 
 module.exports = {

package/engine/hooks/self-approval.js

@@ -24,7 +24,7 @@ const CHAT_RECORD = (file) => `${file} es el registro de lo que la persona dijo
   + 'runner, nunca una herramienta.'
 
 const SELF = (file) => `${file} es la aprobación de una persona, y escribírsela es aprobarse solo. Si la `
-  + 'persona quiere autorizar algo, que lo diga en el chat —nombrándolo, o contestando «dale» al bloqueo— o '
+  + 'persona quiere autorizar algo, que lo diga en el chat —nombrándolo, o confirmando el bloqueo— o '
   + 'que edite el archivo ella.'
 
 // Las líneas van en el mensaje porque son lo que el «dale» va a aprobar: una confirmación que no muestra
@@ -32,7 +32,7 @@ const SELF = (file) => `${file} es la aprobación de una persona, y escribírsel
 const UNASKED = (file, missing) => `${file} es la aprobación de una persona y estas líneas no las pidió:\n`
   + missing.map((line) => `  ${line}\n`).join('')
   + 'Escribí sólo lo que ella nombró en su mensaje. Si hacen falta las otras, decile cuáles y por qué, y '
-  + 'esperá: si contesta «dale», reintentá la misma escritura y pasa.'
+  + 'pedile que lo confirme con sus palabras: si lo que contesta es un sí, reintentá la misma escritura y pasa.'
 
 // **Por shell se frena toda escritura.** Es la misma decisión que toma `ops-config`, y por qué un comando
 // no se puede comparar está escrito allá. Lo que la trae hasta acá es que el contenido es lo único que

package/engine/hooks/shell.js

@@ -193,6 +193,39 @@ function gitAdd(input) {
   }
 }
 
+// Un `package.json` cambia sin tocar nada de lo que su lockfile registra: un script, una descripción, la
+// configuración de una herramienta. Frenar eso por la sola presencia del archivo en el índice obligaba a
+// pedir permiso por un cambio sin riesgo (caso 181). Se deja pasar sólo lo medido, y lo demás frena como
+// antes, incluido lo que no se puede comparar.
+//
+// La lista salió de correr `npm install --package-lock-only` con npm 11.16.0 cambiando una clave por vez:
+// las claves name, version, license, engines, bin, funding, workspaces, os y cpu, y los scripts preinstall,
+// install y postinstall, sí mueven el lock. Sólo se midió el lock de npm, así que con otro gestor no se
+// afloja nada.
+const INERT_KEYS = new Set([
+  'scripts', 'description', 'keywords', 'author', 'repository', 'homepage', 'bugs', 'private', 'type',
+  'main', 'files', 'exports', 'config', 'jest', 'eslintConfig', 'prettier',
+])
+const INSTALL_SCRIPTS = ['preinstall', 'install', 'postinstall']
+
+function lockUnaffected(dir, file, lockfiles) {
+  if (path.basename(file) !== 'package.json' || lockfiles.join() !== 'package-lock.json') return false
+  const read = (ref) => {
+    const shown = run('git', ['-C', dir, 'show', `${ref}:${file}`], dir)
+    if (!shown.ok) return null
+    try { return JSON.parse(shown.output) } catch { return null }
+  }
+  const before = read('HEAD')
+  const after = read('')
+  if (!before || !after || typeof before !== 'object' || typeof after !== 'object') return false
+  const same = (one, other) => JSON.stringify(one) === JSON.stringify(other)
+  const changed = [...new Set([...Object.keys(before), ...Object.keys(after)])]
+    .filter((key) => !same(before[key], after[key]))
+  if (changed.some((key) => !INERT_KEYS.has(key))) return false
+  const scripts = (one) => (one && typeof one.scripts === 'object' ? one.scripts : {}) || {}
+  return INSTALL_SCRIPTS.every((name) => same(scripts(before)[name], scripts(after)[name]))
+}
+
 function dependencies(input) {
   if (process.env.OPS_DEPENDENCIES_OVERRIDE === '1') return
   const command = commandOf(input)
@@ -250,6 +283,7 @@ function dependencies(input) {
       block(`${parent}: hay varios lockfiles (${onDisk.join(', ')}). Conserva uno solo.`)
     }
     const manifests = sinAprobar(parent, state.manifests)
+      .filter((name) => !lockUnaffected(dir, name, existingLocks))
     if (state.manifests.length && existingLocks.length && !state.locks.length && manifests.length) {
       block(`${parent}: cambió ${state.manifests.join(', ')} sin actualizar su lockfile.\n`
         + AP.HOW('OPS_DEPENDENCIES_OVERRIDE', manifests, input))

package/engine/hooks/verify.js

@@ -144,33 +144,90 @@ function commitTree(dir, input) {
   return { root: temp, temp, env: { pnpm_config_verify_deps_before_run: 'false' } }
 }
 
+// Dónde viven la consulta de sqlc y su generado lo declara cada proyecto en su config (`queries:` y
+// `gen.go.out`), y acá no se lee: no hay parser de YAML y no se agrega uno para un guard. Lo que se usa
+// en su lugar son dos hechos que no dependen del layout.
+//
+// La consulta se busca en `queries/` a cualquier profundidad —un monorepo la tiene en `api/db/queries/`
+// (caso 192)—, y sólo cuenta si el repositorio tiene un `sqlc.yaml`, `sqlc.yml` o `sqlc.json`, los tres
+// nombres que sqlc busca: sin esa condición, desanclar el patrón frenaría consultas de un reporte o
+// fixtures que nadie genera, y cada freno falso se resuelve aprobándolo. Un `queries:` con otro nombre de
+// carpeta sigue sin verse.
+//
+// El generado se reconoce por el nombre del archivo, no por su carpeta: sqlc escribe `<consulta>.sql.go`
+// donde diga `out`, y esperar una carpeta `sqlc/` frenaba al que la llamó de otro modo (caso 187). La
+// carpeta queda como respaldo. `.ts` o `.py` no: esos generadores son plugins y su nombre no se comprobó.
+const SQL_SOURCE = /(?:^|\/)queries\/.*\.sql$/i
+const SQL_GENERATED = /\.sql\.go$|(?:^|\/)(?:sqlc|generated)(?:\/|.*\.(?:go|ts|js|py)$)/i
+function usesSqlc(dir) {
+  // `top` porque `dir` puede ser un subdirectorio y el índice se pregunta entero; `glob` para que `**/`
+  // alcance también la raíz. Se lee el índice y no el disco: una config sin trackear no es del proyecto.
+  // Si git no contesta se asume que sí: un guard que no pudo mirar no afloja.
+  const listed = run('git', ['-C', dir, 'ls-files', '--',
+    ...['yaml', 'yml', 'json'].map((ext) => `:(top,glob)**/sqlc.${ext}`)], dir)
+  return !listed.ok || Boolean(listed.output.trim())
+}
+
+// Una especificación OpenAPI se reconoce por lo que declara y no por la carpeta: `api/` guarda también la
+// config de sqlc, un compose o fixtures, y cada uno pedía regenerar un cliente que no existe (caso 197). La
+// carpeta queda como filtro barato antes de leer nada. Un fragmento de una especificación partida con `$ref`
+// no declara nada, así que cuenta si su carpeta de primer nivel tiene en el índice una raíz que sí lo haga.
+// Se lee el índice y no el disco, que es lo que el commit graba. Si git no contesta, dispara: un guard que
+// no pudo mirar no afloja.
+const OPENAPI_CANDIDATE = /^(?:(?:openapi|api|spec)\/(?:.*\/)?[^/]+|openapi|swagger)\.ya?ml$/i
+const OPENAPI_ROOT = /^(?:openapi|swagger)\s*:/m
+
+function declaresOpenApi(dir, file) {
+  // Un archivo borrado figura como cambio y ya no está en el índice: lo que era se lee en `HEAD`.
+  for (const revision of ['', 'HEAD']) {
+    const shown = run('git', ['-C', dir, 'show', `${revision}:${file}`], dir)
+    if (shown.ok) return OPENAPI_ROOT.test(shown.output.slice(0, 4096))
+  }
+  return true
+}
+
+function changedOpenApiSpec(dir, staged) {
+  const candidates = staged.filter((file) => OPENAPI_CANDIDATE.test(file))
+  if (candidates.some((file) => declaresOpenApi(dir, file))) return true
+  // Una sola búsqueda en el índice por todas las carpetas, y no un `git show` por archivo: un `spec/` con
+  // cientos de fixtures costaba cientos de procesos por commit. `git grep` sale con 1 si no encuentra nada, y
+  // con cualquier otro código no pudo mirar, que dispara igual.
+  const folders = [...new Set(candidates.filter((file) => file.includes('/')).map((file) => file.split('/')[0]))]
+  if (!folders.length) return false
+  const found = run('git', ['-C', dir, 'grep', '--cached', '-l', '-E', '^(openapi|swagger)[[:space:]]*:', '--',
+    ...folders.flatMap((folder) => [`:(top,glob)${folder}/**/*.yaml`, `:(top,glob)${folder}/**/*.yml`])], dir)
+  if (found.ok) return Boolean(found.output.trim())
+  return found.status !== 1
+}
+
 function verify(input) {
   if (process.env.OPS_SKIP_VERIFY === '1') return
   const command = commandOf(input)
   if (!isCommit(command)) return
   const { dir, staged } = stagedForCommit(command, cwdOf(input))
-  const changedOpenApi = staged.some((file) => /^(?:openapi|api|spec)(?:\/.*)?\/[^/]+\.ya?ml$/i.test(file))
-    || staged.some((file) => /^(?:openapi|swagger)\.ya?ml$/i.test(file))
-  const changedSqlSource = staged.some((file) => /^(?:db\/queries|queries)\/.*\.sql$/i.test(file))
+  const changedOpenApi = changedOpenApiSpec(dir, staged)
+  const changedSqlSource = staged.some((file) => SQL_SOURCE.test(file)) && usesSqlc(dir)
   const hasApiGenerated = staged.some((file) => /(?:^|\/)[^/]*(?:generated|\.gen)\.(?:go|ts|js|py)$/i.test(file))
-  const hasSqlGenerated = staged.some((file) => /(?:^|\/)(?:sqlc|generated)(?:\/|.*\.(?:go|ts|js|py)$)/i.test(file))
+  const hasSqlGenerated = staged.some((file) => SQL_GENERATED.test(file))
   // Acá lo aprobado es el conjunto staged entero: decir «autorizo commitear exactamente estas rutas»
   // es lo que un gate en rojo necesita, y cambia en cuanto se stagea una más. La lista sale del índice
   // y no de una regla, que es lo que la vuelve una operación y no un permiso.
-  const sinAprobar = AP.pendingNow(opsRoot(input), staged, input)
-  const aprobado = !sinAprobar.length
-  if (changedOpenApi && !hasApiGenerated && !aprobado) {
+  const unapproved = AP.pendingNow(opsRoot(input), staged, input)
+  const approved = !unapproved.length
+  if (changedOpenApi && !hasApiGenerated && !approved) {
     block('Cambió una fuente OpenAPI/Swagger sin incluir código regenerado. Ejecuta el generador y '
-      + `stagea su salida.\n${AP.HOW('OPS_SKIP_VERIFY', sinAprobar, input)}`)
+      + `stagea su salida.\n${AP.HOW('OPS_SKIP_VERIFY', unapproved, input)}`)
   }
-  if (changedSqlSource && !hasSqlGenerated && !aprobado) {
-    block('Cambió una consulta SQL fuente sin artefactos regenerados. Ejecuta el generador.\n'
-      + AP.HOW('OPS_SKIP_VERIFY', sinAprobar, input))
+  if (changedSqlSource && !hasSqlGenerated && !approved) {
+    block('Cambió una consulta SQL fuente sin artefactos regenerados: busqué en el índice un `*.sql.go`, '
+      + 'o algo bajo una carpeta `sqlc/` o `generated/`, y no hay ninguno. Si corriste `sqlc generate`, '
+      + 'stageá lo que escribió; si su `output_files_suffix` le cambia el nombre, esto no lo reconoce.\n'
+      + AP.HOW('OPS_SKIP_VERIFY', unapproved, input))
   }
   if (!staged.some((file) => /\.(?:ts|tsx|js|jsx|mjs|cjs|go|py|html|css|scss|prisma)$/.test(file))) return
   const { root, temp, env } = commitTree(dir, input)
   try {
-    verifyGates(root, dir, sinAprobar, env, input)
+    verifyGates(root, dir, unapproved, env, input)
   } finally {
     if (temp) fs.rmSync(temp, { recursive: true, force: true })
   }
@@ -201,7 +258,7 @@ const ERROR_LINE = /error|err[_!]|fail|abort|not found|cannot|no such/i
 const FAILED_TEST = /^(?:✖|not ok\b|--- FAIL:|● |× |\d+\) |FAILED )/
 const PASSED_TEST = /^(?:✔|ok\b|--- PASS:)|::\S+ PASSED\b/
 const MAX_LINE = 160
-function fallo(gate, result) {
+function failure(gate, result) {
   // La línea que empieza con `>` es el eco del script que npm y pnpm imprimen antes de correrlo, así
   // que lleva el comando entero y no dice nada de qué falló. Descartarla es lo que hace que la primera
   // coincidencia sea el error y no el comando — con el eco adentro, un script que **menciona** una
@@ -228,7 +285,7 @@ function howItReads(failures) {
     + 'una suite, así que mirá si llegaron a ejecutarse antes de aprobar esto como un rojo conocido.'
 }
 
-function verifyGates(root, dir, sinAprobar, env, input) {
+function verifyGates(root, dir, unapproved, env, input) {
   const ops = opsRoot(input)
   const failures = []
   if (fs.existsSync(path.join(root, 'package.json'))) {
@@ -240,19 +297,19 @@ function verifyGates(root, dir, sinAprobar, env, input) {
       if (!pkg.scripts || !pkg.scripts[script]) continue
       const result = run(pm, ['run', script], root, env)
       EV.record(ops, script, result.status, result.ms)
-      if (!result.ok) failures.push(fallo(script, result))
+      if (!result.ok) failures.push(failure(script, result))
     }
   } else if (fs.existsSync(path.join(root, 'go.mod'))) {
     const makefile = path.join(root, 'Makefile')
     if (fs.existsSync(makefile) && /^ci:/m.test(fs.readFileSync(makefile, 'utf8'))) {
       const result = run('make', ['ci'], root, env)
       EV.record(ops, 'make ci', result.status, result.ms)
-      if (!result.ok) failures.push(fallo('make ci', result))
+      if (!result.ok) failures.push(failure('make ci', result))
     } else {
       for (const args of [['test', './...'], ['build', './...']]) {
         const result = run('go', args, root, env)
         EV.record(ops, `go ${args[0]}`, result.status, result.ms)
-        if (!result.ok) failures.push(fallo(`go ${args[0]}`, result))
+        if (!result.ok) failures.push(failure(`go ${args[0]}`, result))
       }
     }
   } else if (fs.existsSync(path.join(root, 'pyproject.toml')) || fs.existsSync(path.join(root, 'requirements.txt'))) {
@@ -260,16 +317,16 @@ function verifyGates(root, dir, sinAprobar, env, input) {
     if (fs.existsSync(makefile) && /^test:/m.test(fs.readFileSync(makefile, 'utf8'))) {
       const result = run('make', ['test'], root, env)
       EV.record(ops, 'make test', result.status, result.ms)
-      if (!result.ok) failures.push(fallo('make test', result))
+      if (!result.ok) failures.push(failure('make test', result))
     }
   }
-  if (!failures.length || !sinAprobar.length) return
+  if (!failures.length || !unapproved.length) return
   // Se dice sobre qué corrió cuando no fue el árbol: un fallo que no se reproduce escribiendo el mismo
   // comando a mano se lee como que el guard miente, y lo que pasó es que midió lo que se va a grabar.
-  const donde = root === dir ? '' : '\nCorrió sobre el índice, que es lo que el commit graba: si en tu '
+  const where = root === dir ? '' : '\nCorrió sobre el índice, que es lo que el commit graba: si en tu '
     + 'directorio pasa, es que en disco tenés algo que no está staged.'
-  block(`Verify falló en ${path.basename(dir)}: ${howItReads(failures)}\nNo se commitea en rojo.${donde}\n`
-    + AP.HOW('OPS_SKIP_VERIFY', sinAprobar, input))
+  block(`Verify falló en ${path.basename(dir)}: ${howItReads(failures)}\nNo se commitea en rojo.${where}\n`
+    + AP.HOW('OPS_SKIP_VERIFY', unapproved, input))
 }
 
 module.exports = { verify }

package/engine/planning/acceptance.js

@@ -0,0 +1,18 @@
+'use strict'
+
+// El lado del motor de `automatization/shared/acceptance.js`: lo evalúa en vez de copiarlo. El archivo
+// declara constantes sueltas porque así lo incluye un recorrido, y un fragmento así no se puede
+// `require`; evaluado aparte da los mismos valores que recibe el recorrido renderizado.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const vm = require('node:vm')
+
+const SOURCE = path.join(__dirname, '..', '..', 'automatization', 'shared', 'acceptance.js')
+
+const { acceptanceConditions, OUT_OF_VERIFY, NON_EXECUTABLE } = vm.runInNewContext(
+  `${fs.readFileSync(SOURCE, 'utf8')}\n;({ acceptanceConditions, OUT_OF_VERIFY, NON_EXECUTABLE })`,
+  {}, { filename: SOURCE },
+)
+
+module.exports = { acceptanceConditions, OUT_OF_VERIFY, NON_EXECUTABLE }

package/engine/planning/contracts.js

@@ -4,6 +4,7 @@ const fs = require('node:fs')
 const path = require('node:path')
 const P = require('./parser')
 const { PLACEHOLDERS } = require('../core/onboarding')
+const { acceptanceConditions, OUT_OF_VERIFY, NON_EXECUTABLE } = require('./acceptance')
 
 const TEST_TRACE = /^(?:n\/a\s*[—-]\s*.+|(?:A|C\d+)\s*(?:→|->)\s*\S.+)$/i
 const DECISION_TRACE = /\[(?:fuente|supuesto):\s*[^\]]+\]/i
@@ -40,12 +41,13 @@ function validDecisionTrace(value) {
 // sha. La salida explícita existe porque hay tareas que no producen commit —abrir una fila en
 // HUMAN_ACTIONS, registrar un informe—, y forzarlas a llenar el campo produce un sha inventado, que es
 // peor que la ausencia: parece evidencia.
+// Se corta en cada `|`, y en un `;` sólo cuando detrás viene un sha: el `;` aparece también dentro del
+// paréntesis final —`(api@main; sin footer Task:)`— y cortar ahí convertiría una nota en un commit que
+// falta. Cada tramo responde por sí mismo; validar sólo el primero dejaba pasar la mitad sin artefacto.
+const commitParts = (value) => String(value || '').trim().split(/\s*(?:\||;(?=\s*[0-9a-f]{7,40}\s))\s*/)
+
 function validCommitTrace(value) {
-  // Se corta en cada `|`, y en un `;` sólo cuando detrás viene un sha: el `;` aparece también dentro del
-  // paréntesis final —`(api@main; sin footer Task:)`— y cortar ahí convertiría una nota en un commit que
-  // falta. Cada tramo responde por sí mismo; validar sólo el primero dejaba pasar la mitad sin artefacto.
-  return String(value || '').trim().split(/\s*(?:\||;(?=\s*[0-9a-f]{7,40}\s))\s*/)
-    .every((part) => COMMIT_TRACE.test(part.trim()))
+  return commitParts(value).every((part) => COMMIT_TRACE.test(part.trim()))
 }
 
 // Los criterios que la evidencia realmente rastrea. `n/a — razón` no rastrea ninguno a propósito: es
@@ -118,8 +120,8 @@ function doneEntryErrors(entry, epics = []) {
 // Un carril declara **cuánta ceremonia** merecía la tarea; `n/a` en `review:` dice que la revisión no
 // corrió. `express` es el único que no convoca revisor, así que en los otros tres esa combinación es la
 // ADR incumplida, escrita en el propio registro.
-const CONVOCAN_REVISOR = ['directo', 'lite', 'full']
-const SIN_REVISION = /^n\/a\b/i
+const REVIEWED_LANES = ['directo', 'lite', 'full']
+const NO_REVIEW = /^n\/a\b/i
 
 // Lo que el registro puede decir sobre la ceremonia, y lo que todavía no. Los dos campos avisan en vez de
 // fallar por lo que dice `doneEntryErrors`, y cuentan en vez de listar porque al principio son todas: lo
@@ -134,22 +136,22 @@ const SIN_REVISION = /^n\/a\b/i
 // completo, pero eso lo sabe el recorrido y no la entrada. Avisar sobre lo que hay que deducir es lo que
 // llena de ruido un aviso que después nadie mira.
 function doneCeremonyWarnings(done, adopted = new Set()) {
-  const propias = done.entries.filter((entry) => !adopted.has(entry.slug))
+  const own = done.entries.filter((entry) => !adopted.has(entry.slug))
   const warnings = []
-  const sinLane = propias.filter((entry) => !entry.lane)
-  if (sinLane.length) {
-    warnings.push(`planning/done: ${sinLane.length} entrada(s) sin lane:, así que no se puede comprobar `
+  const withoutLane = own.filter((entry) => !entry.lane)
+  if (withoutLane.length) {
+    warnings.push(`planning/done: ${withoutLane.length} entrada(s) sin lane:, así que no se puede comprobar `
       + 'sobre el registro que la ceremonia que recibieron fue la que su superficie pedía (OPS-006)')
   }
-  const sinReview = propias.filter((entry) => !entry.review)
-  if (sinReview.length) {
-    warnings.push(`planning/done: ${sinReview.length} entrada(s) sin review:, que es la dimensión con la `
+  const withoutReview = own.filter((entry) => !entry.review)
+  if (withoutReview.length) {
+    warnings.push(`planning/done: ${withoutReview.length} entrada(s) sin review:, que es la dimensión con la `
       + 'que OPS-006 dice que se mide si el carril elegido fue el correcto')
   }
-  const saltadas = propias.filter((entry) => CONVOCAN_REVISOR.includes(entry.lane)
-    && entry.review && SIN_REVISION.test(entry.review))
-  if (saltadas.length) {
-    warnings.push(`planning/done: ${saltadas.map((entry) => entry.slug).join(', ')} declara(n) un carril `
+  const skipped = own.filter((entry) => REVIEWED_LANES.includes(entry.lane)
+    && entry.review && NO_REVIEW.test(entry.review))
+  if (skipped.length) {
+    warnings.push(`planning/done: ${skipped.map((entry) => entry.slug).join(', ')} declara(n) un carril `
       + 'que convoca revisor y una revisión que no corrió: el carril reduce ceremonia, nunca evidencia')
   }
   return warnings
@@ -165,14 +167,6 @@ const POST_VERIFY = [
   [/\bel reclamo\b|\bclaims\//i, 'el reclamo'],
 ]
 
-// La salida explícita, con la forma que el repositorio ya usa dos veces: `(sin partir: …)` para el umbral
-// de R17 y `n/a — razón` para `tests:` y `commit:`. Acá vale lo mismo que allá —«como lleva su razón
-// escrita se lee en el propio artefacto sin que nadie la cruce»— y por eso no se intenta adivinar si la
-// prosa excluye a Verify. Adivinarlo es lo que no se puede: la única aceptación real que nombra el commit
-// lo hace justamente para decir que no es condición de Verify, y cualquier lista de frases que la
-// reconociera enseñaría a escribir esa frase exacta para silenciar el aviso.
-const OUT_OF_VERIFY = /\(fuera de verify:\s*[^)]+\)/i
-
 // Una condición de aceptación que nombra el registro en vez del producto no se puede cumplir nunca: se
 // comprueba en Verify, que corre antes que Commit y que Done. El recorrido lo detecta —y hace bien—, pero
 // recién ahí: en la corrida que originó esto fueron 1,2 M de tokens y once agentes para terminar con el
@@ -194,11 +188,11 @@ function unverifiableAcceptance(milestones = []) {
   const warnings = []
   for (const milestone of milestones) {
     for (const task of milestone.tasks || []) {
-      for (const condition of String(task.acceptance || '').split(';').map((one) => one.trim())) {
-        if (!condition || OUT_OF_VERIFY.test(condition)) continue
-        const nombra = POST_VERIFY.filter(([pattern]) => pattern.test(condition))
-        if (!nombra.length) continue
-        warnings.push(`BACKLOG ${task.slug}: una condición nombra ${nombra.map(([, what]) => what).join(', ')}`
+      for (const condition of acceptanceConditions(task.acceptance)) {
+        if (OUT_OF_VERIFY.test(condition)) continue
+        const names = POST_VERIFY.filter(([pattern]) => pattern.test(condition))
+        if (!names.length) continue
+        warnings.push(`BACKLOG ${task.slug}: una condición nombra ${names.map(([, what]) => what).join(', ')}`
           + ', que existe después de Verify, así que no se puede comprobar cuando se la comprueba. Eso va '
           + 'en tests:, qa: o commit: de su entrada de DONE, que ya lo exigen; si de verdad va acá, '
           + 'declaralo con "(fuera de verify: <razón>)"')
@@ -208,6 +202,44 @@ function unverifiableAcceptance(milestones = []) {
   return warnings
 }
 
+// `tests: n/a` dice que la tarea no produjo nada que se ejecute, y quien lo escribe es el mismo que quiere
+// cerrar: desde el 189 el recorrido lo emite cuando Verify declara `no-surface`, que es la palabra de un
+// modelo. Lo que la vuelve creíble es mirar qué tocó el commit, y eso no lo decide nadie. Se juzga el n/a
+// entero y no el mixto: en una tarea que rastrea algún criterio con su prueba, el código del commit es el
+// de esos criterios y no dice nada del que se declaró sin superficie.
+//
+// `filesOf` devuelve los archivos de un sha, o null si ningún repositorio lo conoce. Ahí calla, igual que
+// el resto de lo que pregunta a git desde `check`: un sha que no se encuentra no es superficie, y avisarlo
+// sería inventar el hallazgo. Lo adoptado queda afuera por lo mismo que en el resto de DONE: se escribió
+// antes de que el contrato lo pidiera.
+//
+// Y rige desde que existe. Una entrada cerrada antes con `tests: n/a` sobre código no violó nada que se le
+// hubiera pedido, y frenarla ahora pondría `check` en rojo con el `upgrade` —y con él al guard que lo corre
+// antes de cada commit— por algo que nadie puede corregir sin reescribir evidencia. Es la misma razón por
+// la que se exime lo adoptado, aplicada a lo que ya estaba cerrado cuando la regla llegó.
+const NOT_APPLICABLE = /^n\/a\s*[—-]/i
+const SURFACE_SINCE = '2026-09-24'
+
+function surfaceWithoutTests(entries, filesOf, adopted = new Set()) {
+  const errors = []
+  for (const entry of entries) {
+    const traces = splitTraces(entry.tests)
+    if (adopted.has(entry.slug) || !traces.length || !traces.every((one) => NOT_APPLICABLE.test(one))) continue
+    if (!(String(entry.fecha || '') >= SURFACE_SINCE)) continue
+    for (const sha of commitParts(entry.commit).map((part) => (part.match(/^([0-9a-f]{7,40})\s/) || [])[1])) {
+      if (!sha) continue
+      const surface = (filesOf(sha) || [])
+        .filter((file) => !NON_EXECUTABLE.includes(path.extname(file).toLowerCase()))
+      if (!surface.length) continue
+      const shown = surface.length > 5 ? [...surface.slice(0, 5), `y ${surface.length - 5} más`] : surface
+      errors.push(`${entry.source} ${entry.slug}: tests: n/a dice que no hay superficie ejecutable y el commit `
+        + `${sha} toca ${shown.join(', ')}; sólo ${NON_EXECUTABLE.join(', ')} cuentan como no ejecutables, `
+        + 'así que esos criterios se rastrean con su prueba')
+    }
+  }
+  return errors
+}
+
 function duplicates(values) {
   return [...new Set(values.filter((value, index) => values.indexOf(value) !== index))]
 }
@@ -260,22 +292,22 @@ function dependencyErrors(milestones, done) {
   // Recorrido en profundidad con el camino a cuestas: al reencontrar un slug que sigue en el camino,
   // ese camino **es** el ciclo, y nombrarlo entero es lo que lo hace reparable — decir sólo que hay uno
   // deja el trabajo de encontrarlo del lado de quien lee.
-  const estado = new Map()
-  const visitar = (slug, camino) => {
-    if (estado.get(slug) === 'listo') return
-    const desde = camino.indexOf(slug)
-    if (desde >= 0) {
-      const ciclo = [...camino.slice(desde), slug]
-      errors.push(`BACKLOG: ciclo de dependencias ${ciclo.join(' → ')}`)
+  const state = new Map()
+  const visit = (slug, trail) => {
+    if (state.get(slug) === 'listo') return
+    const from = trail.indexOf(slug)
+    if (from >= 0) {
+      const cycle = [...trail.slice(from), slug]
+      errors.push(`BACKLOG: ciclo de dependencias ${cycle.join(' → ')}`)
       return
     }
     for (const dep of queued.get(slug) || []) {
       // La que se depende a sí misma ya tiene su error, más claro que un ciclo de un solo paso.
-      if (dep !== slug && queued.has(dep)) visitar(dep, [...camino, slug])
+      if (dep !== slug && queued.has(dep)) visit(dep, [...trail, slug])
     }
-    estado.set(slug, 'listo')
+    state.set(slug, 'listo')
   }
-  for (const slug of queued.keys()) visitar(slug, [])
+  for (const slug of queued.keys()) visit(slug, [])
   return [...new Set(errors)]
 }
 
@@ -397,10 +429,10 @@ function validateState({
     // ofreciendo. `**slug: de qué se trata**` es la que sale natural, porque esta tabla la lee una
     // persona. Sin esto la ausencia no deja rastro, que es la forma de R15 aplicada a un mecanismo.
     if (backlogSlugs.has(row.task)) continue
-    const casi = [...backlogSlugs].find((slug) => new RegExp(`\\b${slug}\\b`).test(row.task))
-    if (casi) {
-      errors.push(`HUMAN_ACTIONS: la fila "${row.task}" nombra a ${casi} y no bloquea nada, porque el `
-        + `motor bloquea por la primera columna exacta. Dejá "${casi}" sola ahí y contá el resto en la `
+    const near = [...backlogSlugs].find((slug) => new RegExp(`\\b${slug}\\b`).test(row.task))
+    if (near) {
+      errors.push(`HUMAN_ACTIONS: la fila "${row.task}" nombra a ${near} y no bloquea nada, porque el `
+        + `motor bloquea por la primera columna exacta. Dejá "${near}" sola ahí y contá el resto en la `
         + 'acción, o nombrá la épica o el recorrido si lo que se frena no es esa tarea')
     }
   }
@@ -435,6 +467,7 @@ module.exports = {
   doneEntryErrors,
   doneCeremonyWarnings,
   unverifiableAcceptance,
+  surfaceWithoutTests,
   validCommitTrace,
   validDecisionTrace,
   validTestTrace,