@ingeniomaps/cauce 0.53.0 → 0.53.2

package/engine/hooks/shell.js

@@ -0,0 +1,197 @@
+'use strict'
+
+// Los guards que juzgan un comando antes de que se ejecute: qué destruye, qué publica, qué toca una
+// dependencia y qué gate hay que haber corrido. Todos leen `commandOf` y miran el índice de git —de
+// ahí que vayan juntos—, y son el grupo `pre-shell` que el registro ya declaraba.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { spawnSync } = require('node:child_process')
+const {
+  commandOf, cwdOf, block, gitDirectory, isCommit, stagedFiles, pushAllowed,
+} = require('./input')
+
+function destructive(input) {
+  const command = commandOf(input)
+  if (/\bgit\s+push\b/.test(command) && !pushAllowed(input)) {
+    block("'git push' publica cambios y requiere una acción humana. Se habilita con runner.allowPush.")
+  }
+  const rules = [
+    [/\bgit\s+reset\s+--hard\b/, "'git reset --hard' destruye cambios locales."],
+    [/\bgit\s+clean\s+-[^\s]*f/, "'git clean -f' borra archivos sin seguimiento."],
+    // `git checkout -- .` destruye lo mismo que `reset --hard` y sin recuperación, pero se escribe como
+    // una limpieza. Se bloquea sólo la forma ancha —`.`, `*`, `:/`, o sin ruta—: revertir un archivo
+    // nombrado es trabajo corriente y no se toca.
+    //
+    // Pasó dos veces en una sesión, las dos limpiando restos de una prueba: el comando revirtió también
+    // el trabajo de al lado, que no estaba commiteado. Lo que engaña es que el alcance no se ve en el
+    // comando — `.` es el cwd, y el cwd suele tener más de lo que uno está mirando.
+    [
+      // `git restore .` no lleva `--` y destruye igual: comprobado en `git restore --help` (git 2.43.0),
+      // que restaura el working tree por defecto y toma el pathspec sin separador.
+      /\bgit\s+(?:checkout|restore)\s+(?:[^;&|]*?\s)?(?:--\s*(?:$|[;&|])|(?:--\s+)?(?:\.|\*|:\/)\s*(?:$|[;&|]))/,
+      "'git checkout -- .' revierte todo lo no commiteado del directorio, no sólo lo que estás mirando. "
+      + 'Nombrá el archivo, o commiteá lo que quieras conservar antes.',
+    ],
+    [
+      /\bdocker(?:\s+\w+)*\s+(?:volume\s+(?:rm|prune)|system\s+prune|network\s+prune)\b/,
+      'La limpieza global de Docker puede borrar datos compartidos.',
+    ],
+    [
+      /\bdocker(?:\s+compose|-compose)\s+(?:\S+\s+)*(?:down|stop|kill|rm)\b/,
+      'Detener un stack Compose puede interrumpir servicios compartidos.',
+    ],
+    [
+      /(?:^|\s)(?:mkfs\S*|shred)\s|\bdd\s+[^;&|]*\bof=\/dev\/|>\s*\/dev\/(?:sd|nvme|disk)/,
+      'Operación destructiva sobre disco o dispositivo.',
+    ],
+    [
+      /\brm\s+(?:-[^\s]*r[^\s]*\s+)+(?:\/\*?|~\/?|\$HOME|\.\.)(?:\s|$)/,
+      "'rm -r' sobre /, home o el directorio padre es catastrófico.",
+    ],
+  ]
+  for (const [pattern, message] of rules) if (pattern.test(command)) block(message)
+}
+
+function gitAdd(input) {
+  const command = commandOf(input)
+  if (/\bgit\s+add\s+(?:[^;&|]*\s)?(?:-A\b|--all\b|\.)(?:\s|$|[;&|])/.test(command)) {
+    block("'git add -A/--all/.' está prohibido. Stagea rutas explícitas.")
+  }
+}
+
+function dependencies(input) {
+  if (process.env.OPS_DEPENDENCIES_OVERRIDE === '1') return
+  const command = commandOf(input)
+  const unsafePackageCommand = /\b(?:npm|pnpm|yarn|bun)\s+publish\b/.test(command)
+    || /\b(?:npm|pnpm|yarn)\s+(?:install|add)\b[^;&|]*(?:\s-g\b|\s--global\b)/.test(command)
+  if (unsafePackageCommand) {
+    block('Publicar paquetes o instalar dependencias globales requiere una acción humana explícita.')
+  }
+  if (!isCommit(command)) return
+  const dir = gitDirectory(command, cwdOf(input))
+  const staged = stagedFiles(dir)
+  const manifests = new Set(['package.json', 'pyproject.toml', 'requirements.txt', 'go.mod', 'Cargo.toml'])
+  const locks = new Set([
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'yarn.lock',
+    'bun.lock',
+    'bun.lockb',
+    'poetry.lock',
+    'uv.lock',
+    'go.sum',
+    'Cargo.lock',
+  ])
+  const byDir = new Map()
+  for (const file of staged) {
+    const base = path.basename(file)
+    if (!manifests.has(base) && !locks.has(base)) continue
+    const parent = path.dirname(file)
+    const state = byDir.get(parent) || { manifests: [], locks: [] }
+    state[manifests.has(base) ? 'manifests' : 'locks'].push(base)
+    byDir.set(parent, state)
+  }
+  for (const [parent, state] of byDir) {
+    const existingLocks = [...locks].filter((name) => fs.existsSync(path.join(dir, parent, name)))
+    if (existingLocks.length > 1) {
+      block(`${parent}: hay varios lockfiles (${existingLocks.join(', ')}). Conserva uno solo.`)
+    }
+    if (state.manifests.length && existingLocks.length && !state.locks.length) {
+      block(`${parent}: cambió ${state.manifests.join(', ')} sin actualizar su lockfile.`)
+    }
+    if (state.locks.length && !state.manifests.length) {
+      block(`${parent}: cambió ${state.locks.join(', ')} sin un cambio explícito en el manifest.`)
+    }
+  }
+}
+
+function governance(input) {
+  if (process.env.OPS_GOVERNANCE_OVERRIDE === '1') return
+  const command = commandOf(input)
+  if (!isCommit(command)) return
+  const dir = gitDirectory(command, cwdOf(input))
+  // El contrato de un cargo y lo que lo mide son gobernanza, igual que un ADR o una regla. La firma de
+  // «Aprobación humana» sólo estaba protegida por una frase en un prompt; `SKILL.md` y `references/`
+  // son lo que la propuesta cambia, y editarlos directo saltea el ciclo entero; y `evaluations/` es el
+  // denominador con que se juzga, así que moverlo ablanda toda medición pasada sin tocar una regla.
+  //
+  // Quedan afuera las dos clases de evidencia, que registran lo que pasó un día en vez de decidir algo:
+  // `learning/reports/` y `evaluations/results/` —esta última se escribe en cada corrida, así que
+  // gobernarla pediría un override por evaluación—. Por eso `evaluations/` se nombra por partes.
+  const governedPattern = new RegExp(
+    String.raw`^(?:(?:template\/)?planning\/(?:rules\/|adr\/|PROTOCOL\.md|` +
+      String.raw`METHODOLOGY\.md|FLOW\.md)|automatization\/|engine\/` +
+      String.raw`|agents\/[a-z0-9-]+\/(?:system\/)?[a-z0-9-]+\/(?:SKILL\.md|references\/` +
+      String.raw`|evaluations\/(?:cases\/|expected-behaviors\.yaml)|learning\/proposals\/))`,
+  )
+  const governed = stagedFiles(dir).filter((file) => governedPattern.test(file))
+  if (governed.length) {
+    const files = governed.map((file) => `  - ${file}`).join('\n')
+    block(`El commit toca gobernanza protegida:\n${files}\n` +
+      'Usa OPS_GOVERNANCE_OVERRIDE=1 solo con aprobación.')
+  }
+}
+
+function run(program, args, cwd) {
+  const env = { ...process.env }
+  delete env.NODE_TEST_CONTEXT
+  const result = spawnSync(program, args, { cwd, encoding: 'utf8', stdio: 'pipe', env })
+  return {
+    ok: result.status === 0,
+    status: result.status,
+    output: `${result.stdout || ''}${result.stderr || ''}`.trim(),
+  }
+}
+
+function verify(input) {
+  if (process.env.OPS_SKIP_VERIFY === '1') return
+  const command = commandOf(input)
+  if (!isCommit(command)) return
+  const dir = gitDirectory(command, cwdOf(input))
+  const staged = stagedFiles(dir)
+  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 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))
+  if (changedOpenApi && !hasApiGenerated) {
+    block('Cambió una fuente OpenAPI/Swagger sin incluir código regenerado. Ejecuta el generador y stagea su salida.')
+  }
+  if (changedSqlSource && !hasSqlGenerated) {
+    block('Cambió una consulta SQL fuente sin artefactos regenerados. Ejecuta el generador.')
+  }
+  if (!staged.some((file) => /\.(?:ts|tsx|js|jsx|mjs|cjs|go|py|html|css|scss|prisma)$/.test(file))) return
+  const failures = []
+  if (fs.existsSync(path.join(dir, 'package.json'))) {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'))
+    const usesPnpm = fs.existsSync(path.join(dir, 'pnpm-lock.yaml'))
+      && !fs.existsSync(path.join(dir, 'package-lock.json'))
+    const pm = usesPnpm ? 'pnpm' : 'npm'
+    for (const script of ['test', 'lint', 'typecheck', 'build']) {
+      if (!pkg.scripts || !pkg.scripts[script]) continue
+      const result = run(pm, ['run', script], dir)
+      if (!result.ok) failures.push(`${script} (exit ${result.status})`)
+    }
+  } else if (fs.existsSync(path.join(dir, 'go.mod'))) {
+    const makefile = path.join(dir, 'Makefile')
+    if (fs.existsSync(makefile) && /^ci:/m.test(fs.readFileSync(makefile, 'utf8'))) {
+      const result = run('make', ['ci'], dir)
+      if (!result.ok) failures.push(`make ci (exit ${result.status})`)
+    } else {
+      for (const args of [['test', './...'], ['build', './...']]) {
+        const result = run('go', args, dir)
+        if (!result.ok) failures.push(`go ${args[0]} (exit ${result.status})`)
+      }
+    }
+  } else if (fs.existsSync(path.join(dir, 'pyproject.toml')) || fs.existsSync(path.join(dir, 'requirements.txt'))) {
+    const makefile = path.join(dir, 'Makefile')
+    if (fs.existsSync(makefile) && /^test:/m.test(fs.readFileSync(makefile, 'utf8'))) {
+      const result = run('make', ['test'], dir)
+      if (!result.ok) failures.push(`make test (exit ${result.status})`)
+    }
+  }
+  if (failures.length) block(`Verify falló en ${path.basename(dir)}: ${failures.join(', ')}. No se commitea en rojo.`)
+}
+
+module.exports = { destructive, gitAdd, dependencies, governance, verify, run }

package/engine/integrations/registry.js

@@ -178,6 +178,8 @@ function validate(root, onlyProvider = '') {
 
 async function sync(root, name, options = {}) {
   const { entry, config } = providerConfig(root, name)
+  // Son dos interruptores y se exigen los dos: el del registro dice que el proveedor está conectado
+  // al proyecto, y el suyo que hay a dónde apuntar.
   if (!entry.enabled || !config.enabled) throw new Error(`${name} está deshabilitado`)
   const provider = adapter(name)
   const items = options.fixture

package/engine/planning/contracts.js

@@ -206,9 +206,9 @@ function validateRules(dir) {
 }
 
 // Una decisión que no dice si rige no decide nada, y el molde traía el menú entero en la línea de estado:
-// tres de las dieciséis decisiones escritas con este modelo se publicaron con el menú intacto. Presentar
+// casi una de cada cinco decisiones escritas con este modelo se publicó con el menú intacto. Presentar
 // las opciones no obliga a elegir; esto sí. Las secciones son las cuatro que se escriben siempre —las
-// alternativas quedan en el molde sin exigirse, porque pedirlas rechazaría quince decisiones que existen—.
+// alternativas quedan en el molde sin exigirse, porque pedirlas rechazaría a casi todas las que existen—.
 const ADR_STATES = ['Propuesto', 'Aceptado', 'Obsoleto']
 const ADR_SUPERSEDED = /^Reemplazada por \[[^\]]+\]\([^)]+\)(?: \(\d{4}-\d{2}-\d{2}\))?$/
 const ADR_SECTIONS = ['Contexto', 'Decisión', 'Consecuencias', 'Estado de implementación']
@@ -381,23 +381,25 @@ function validateState({ epics, milestones, done, wip, roles = new Set(), humanA
 const R17 = { taskCriteria: 5, epicCriteria: 7, milestoneTasks: 9 }
 
 // Se cuenta lo que está estructurado: criterios de la épica, criterios que hereda una tarea, tareas del
-// hito. La aceptación escrita en prosa no se cuenta —cuántas condiciones tiene una frase es una lectura,
-// y un número inventado ahí sería peor que ninguno—; ésa la mira el review, que para eso está R3.
+// hito. Quedan afuera las dos cosas que no son un conteo: la aceptación escrita en prosa —cuántas
+// condiciones tiene una frase es una lectura, y un número inventado ahí sería peor que ninguno— y la
+// segunda barra de R17, las cuatro horas de esfuerzo, que no está en el artefacto. Las dos las mira el
+// review, que para eso está R3, y la de esfuerzo es la que R17 dice que encuentra lo que ésta deja pasar.
 function oversizedUnits({ epics = [], milestones = [] }) {
   const errors = []
-  const decidir = (what, count, limit) =>
+  const undecided = (what, count, limit) =>
     `${what}: ${count} (umbral ${limit} de R17). Revisá si son dos resultados con vidas distintas y `
     + 'partilo; si es uno solo, partirlo lo empeora — dejalo entero agregando "(sin partir: <razón>)"'
-  const juzgar = (unit, what, count, limit) => {
-    if (count > limit && !unit.noSplit) errors.push(decidir(what, count, limit))
+  const judge = (unit, what, count, limit) => {
+    if (count > limit && !unit.noSplit) errors.push(undecided(what, count, limit))
   }
   for (const epic of epics) {
-    juzgar(epic, `roadmap/${epic.file}: criterios`, epic.criteria.length, R17.epicCriteria)
+    judge(epic, `roadmap/${epic.file}: criterios`, epic.criteria.length, R17.epicCriteria)
   }
   for (const milestone of milestones) {
-    juzgar(milestone, `hito ${milestone.slug}: tareas`, milestone.tasks.length, R17.milestoneTasks)
+    judge(milestone, `hito ${milestone.slug}: tareas`, milestone.tasks.length, R17.milestoneTasks)
     for (const task of milestone.tasks) {
-      juzgar(task, `BACKLOG ${task.slug}: criterios`, task.criteria.length, R17.taskCriteria)
+      judge(task, `BACKLOG ${task.slug}: criterios`, task.criteria.length, R17.taskCriteria)
     }
   }
   return errors

package/engine/planning/parser.js

@@ -23,9 +23,10 @@ const STOP_REASONS = [
 // que el lector no leía, que es la manera más cara de tener las dos cosas.
 const MILESTONE_HEADING = /^##\s+Hito\s+([^\s]+)\s+[—-]\s+(.+)$/
 
-// Los carriles, en orden de ceremonia creciente. El orden es parte del vocabulario: la prosa que los
-// describe va de menos a más y `check` lo contrasta, porque un carril leído fuera de orden se elige por
-// su nombre y no por su criterio.
+// Los carriles, en orden de ceremonia creciente. El orden es parte del vocabulario, porque un carril
+// leído fuera de orden se elige por su nombre y no por su criterio. Que la prosa del PROTOCOL vaya en
+// este mismo orden lo ata la suite del toolkit —`planning-template.test.js`—, no `check`: un workflow
+// en sandbox no puede importar este módulo, así que la atadura es una prueba y no una validación.
 const LANES = ['express', 'directo', 'lite', 'full']
 const TASK_LINE = new RegExp(
   String.raw`^-\s+\[\s\]\s+\*\*([^*]+)\*\*\s*(?:\[(${LANES.join('|')})\])?\s+[—-]\s+(.+)$`,

package/engine/planning/state.js

@@ -29,7 +29,8 @@ function pendingHumanActions(root) {
 
 // Selecciona la tarea que un runner debe ejecutar ahora, con la misma precedencia que el protocolo:
 // WIP activo primero —es el mutex y manda incluso si tiene una acción humana abierta—, si no la
-// primera tarea no terminada y no bloqueada del primer hito.
+// primera tarea no terminada y no bloqueada recorriendo los hitos en su orden: agotado el primero,
+// sigue por el que viene.
 function currentTask({ milestones, done, wip }, blockers = []) {
   const queue = milestones.flatMap((milestone) => milestone.tasks.map((task) => ({ ...task, hito: milestone.slug })))
   if (wip) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingeniomaps/cauce",
-  "version": "0.53.0",
+  "version": "0.53.2",
   "description": "Sistema portable de planificación y ejecución verificable para cualquier proyecto",
   "keywords": [
     "planning",
@@ -30,10 +30,10 @@
     "check": "node engine/cli/ops.js check template/planning",
     "automation:check": "node engine/cli/ops.js automation check .",
     "integration:check": "node engine/cli/ops.js integration check template jira",
-    "test": "bash test/hooks-smoke.sh && node --test test/*.test.js",
-    "coverage": "bash test/coverage.sh",
-    "coverage:update": "bash test/coverage.sh --update",
-    "dead-imports": "node test/dead-imports.js",
+    "test": "bash test/tools/hooks-smoke.sh && node --test \"test/**/*.test.js\"",
+    "coverage": "bash test/tools/coverage.sh",
+    "coverage:update": "bash test/tools/coverage.sh --update",
+    "dead-imports": "node test/tools/dead-imports.js",
     "ci": "npm run check && npm run automation:check && npm run integration:check && npm run coverage",
     "prepublishOnly": "npm run ci"
   },

package/template/tools/ops.js

@@ -4,7 +4,7 @@
 // Punto de entrada estable del proyecto: nadie —ni una persona ni un agente— necesita saber de
 // dónde sale el motor. Viene de la dependencia npm, que el lockfile versiona.
 //
-// Nada de `require`, `__dirname` ni `import`: el shim se instala dentro del proyecto y hereda el
+// Nada de `require`, `__dirname` ni un `import` estático: el shim se instala en el proyecto y hereda el
 // `type` de su `package.json`, así que el mismo archivo se carga como CommonJS en un repo y como
 // ESM en el de al lado. `import()` dinámico y `process.argv[1]` son las dos únicas formas que
 // existen bajo los dos cargadores; cualquier otra revienta en la mitad de los proyectos —`require
@@ -16,7 +16,7 @@ const root = self.slice(0, self.lastIndexOf('/', self.lastIndexOf('/') - 1)) ||
 
 // El shim sabe dónde vive; quien lo invoca, no. En modo sidecar se lo llama desde la carpeta de la
 // compañía —`node <empresa>-ops/tools/ops.js …`— y sin esto cada comando resolvería su raíz contra
-// el cwd: `agents list` y `team list` devolvían vacío en vez de fallar.
+// el cwd: `agents list` y `flow list` devolvían vacío en vez de fallar.
 process.env.OPS_ROOT = process.env.OPS_ROOT || root
 
 // El especificador se resuelve contra este archivo, así que sube a `<raíz>/node_modules` igual que