@ingeniomaps/cauce 0.66.0 → 0.67.0

package/CHANGELOG.md

@@ -14,6 +14,76 @@ desde este repositorio no va, porque el que lee no puede actuar sobre eso. Cuand
 unas pocas líneas casi siempre es porque cuenta cómo se descubrió el problema o por qué se eligió el
 diseño — eso vive en el commit y en el código.
 
+## [0.67.0] - 2026-09-07
+
+### Agregado
+
+- **Guard `plan-first`: no se cambia el producto sin un plan escrito.** R1 y el paso 7 del protocolo lo
+  piden desde siempre y nada lo comprobaba: tocar el archivo primero y redactar después la aceptación
+  que lo justifica salía igual de verde y se leía igual en DONE. Ahora una escritura de producto exige
+  un WIP activo con al menos un paso numerado.
+
+  No juzga lo que tu instancia posee —`planning/`, `organization/`, `agents/`, `flows/`,
+  `integrations/`, `automatization/`, `tools/`—: el plan se escribe en `planning/`, y exigirlo ahí sería
+  un candado con la llave adentro. Y queda **inerte mientras tu planning no declare ninguna tarea**, que
+  es una instancia recién creada; `automation check` te lo dice cuando lo está.
+
+  **Lo que te pide algo**: si el cambio no es trabajo de una tarea, aprobá la ruta en
+  `planning/.ops-approval`. La variable `OPS_PLAN_FIRST_OVERRIDE=1` lo apaga para toda la sesión.
+
+- **`ops evidence <planning-dir>`: contrasta la evidencia de una entrada de DONE contra lo que no
+  escribió su autor.** Los dos lados de `tests: CN → prueba` los escribía la misma mano en el mismo
+  acto, así que compararlos medía prosa. Ahora se comprueban dos cosas independientes: si el artefacto
+  que el rastro nombra existe en tus raíces de código, y qué gates corrió `verify` al commitear con su
+  código de salida. Dice también lo que **no** puede contestar —que la prueba nombrada haya corrido
+  depende del runner— y no reemplaza a leer su fuente, que es lo que R9 pide.
+
+  **Lo que te pide algo**: `verify` deja ese registro en `planning/.verify-log`. Tu `.gitignore` no se
+  actualiza con el molde —es de `init`—, así que agregale esa línea o el archivo te va a aparecer sin
+  trackear en cada commit.
+
+### Cambiado
+
+- **`upgrade` conserva lo editado y actualiza el resto, en vez de abortar.** Antes cortaba si algún
+  archivo del molde estaba editado, y el único flag que lo destrababa descartaba todos tus cambios de
+  una: quien adoptó Cauce sobre un proceso propio quedaba eligiendo entre no actualizar nunca y perder
+  su corpus. Ahora recibís `rules/system/` y `adr/system/` frescos y conservás lo tuyo, y la corrida
+  nombra qué congeló — en cada corrida, no sólo la primera.
+
+  `check` cuenta esos archivos como advertencia para que la deuda no desaparezca entre actualización y
+  actualización. Y el consejo nombra los cuatro que no tienen contraparte propia adónde mudarse
+  —`PROTOCOL.md`, `METHODOLOGY.md`, `FLOW.md` y el `Makefile`—, en vez de mandarte a mudarlos.
+
+  **Lo que te pide algo**: `upgrade` ya no devuelve código distinto de cero por una edición local. Si lo
+  llamás desde un script que esperaba ese fallo, ese script cambia. `--force` sigue reemplazando todo.
+
+### Corregido
+
+- **Un pipe escapado en `HUMAN_ACTIONS.md` corría las columnas de su fila.** En markdown un pipe dentro
+  de una celda se escribe `\|` —es la única forma— y el parser lo tomaba como separador. La cara que
+  importa era silenciosa: con el pipe detrás de la palabra del vocabulario, `check` pasaba y el runner
+  recibía el contenido de `Origen` como si fuera la acción de desbloqueo. El escape ya no parte la
+  celda, y se quita al leerla porque esa columna existe para que una persona la lea.
+
+  **Puede que empieces a ver un error nuevo**, y es correcto: una fila con las columnas corridas podía
+  esconder un estado fuera del vocabulario y desbloquear una tarea que nadie resolvió. Leída bien, ese
+  estado se ve.
+
+- **La cabecera de `HUMAN_ACTIONS.md` sólo se salteaba si decía exactamente `Tarea`.** Cualquier otro
+  encabezado —`Tarea Requerida`, `Bloqueo`— caía del lado de los datos y `check` reportaba las etiquetas
+  de tus columnas como una acción rota. Ahora la cabecera se reconoce por su forma —es la fila anterior
+  a la de separadores— y se saltea la de **cada** tabla del archivo, no sólo la primera.
+
+- **Los gates de `verify` corrían con el `GIT_DIR` de tu repositorio.** Un gate que escribe con git
+  —una suite que levanta repositorios de prueba y les commitea— escribía entonces en el tuyo: commits
+  ajenos en tu rama, archivos trackeados que nadie agregó y un `core.worktree` apuntando a un temporal
+  ya borrado, sin que nada lo anunciara. Se disparaba al committear una naturaleza por vez, que es lo
+  que R8 pide. Ahora la copia que `verify` materializa es un repositorio propio.
+
+  **Lo que te pide algo**: esa copia no tiene historia. Un gate que lea una etiqueta o un `git log` no
+  la encuentra, y un gate cuyo efecto **es** una escritura de git —taggear, commitear un lockfile
+  regenerado— la hace sobre la copia, que se borra. Si tenés un gate así, sacá esa escritura del gate.
+
 ## [0.66.0] - 2026-09-07
 
 ### Corregido

package/automatization/hooks/README.md

@@ -7,6 +7,7 @@ Los hooks convierten invariantes comprobables en gates mecánicos. La base recom
 - edición manual de código generado y drift respecto a OpenAPI/SQL;
 - commits sin Verify aplicable;
 - apagado o borrado de la prueba que juzga el cambio;
+- cambio de producto sin un WIP activo que traiga el plan;
 - cierre de sesión con planning o integraciones inválidas;
 - modificación del protocolo durante una tarea de producto.
 - escrituras fuera de las raíces declaradas del workspace;

package/automatization/hooks/guard-plan-first.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# Shim: delega `plan-first` en run-hook.sh; el registro de engine/hooks/run.js nombra su módulo.
+exec "$(dirname "$0")/run-hook.sh" plan-first

package/engine/cli/args.js

@@ -7,6 +7,7 @@
 // Banderas que consumen el argumento siguiente: su valor no es un posicional.
 const VALUED_FLAGS = new Set([
   '--name', '--mode', '--fixture', '--period', '--record', '--runner', '--integration',
+  '--task',
 ])
 
 // Qué acepta cada comando, y a la vez qué comandos existen. Una bandera desconocida se rechaza en vez
@@ -19,6 +20,7 @@ const FLAGS = {
   check: ['--json'],
   tree: ['--json', '--no-color'],
   context: ['--json'],
+  evidence: ['--json', '--task'],
   upgrade: ['--check', '--force'],
   destroy: ['--force'],
   archive: [],

package/engine/cli/catalog.js

@@ -129,7 +129,14 @@ function evaluationBench(root, agent, caso, force, kind) {
   // uno contestó un resumen y escribió el contrato entero en su `INBOX.md`, y el juez —que sólo leía
   // la respuesta— lo dio por ausente. Con git, `status` y `diff` muestran qué produjo, separado del
   // andamiaje. Se ignora `node_modules`: es un symlink al toolkit, no obra del cargo.
-  const git = (...args) => spawnSync('git', ['-C', dir, ...args], { stdio: 'ignore' })
+  // `-C` dice dónde mirar y `GIT_DIR` gana igual —comprobado: con `GIT_DIR` puesto,
+  // `git -C otro rev-parse --absolute-git-dir` contesta el de la variable—, así que sin limpiarla el
+  // banco commitea en el repositorio que la haya exportado. Es lo que hizo el caso 045 antes de
+  // arreglarse en `hooks/shell.js`: el banco de una evaluación dejó sus commits en la rama del usuario.
+  const env = { ...process.env }
+  delete env.GIT_DIR
+  delete env.GIT_WORK_TREE
+  const git = (...args) => spawnSync('git', ['-C', dir, ...args], { stdio: 'ignore', env })
   fs.appendFileSync(path.join(dir, '.gitignore'), '\nnode_modules/\n')
   git('init', '-q')
   git('config', 'user.email', 'banco@cauce.local')

package/engine/cli/instance.js

@@ -65,7 +65,10 @@ function copyTemplate(source, target, replacements, force, skip = [], quiet = fa
 
 // Devuelve lo conservado igual que `copyTemplate`, y por la misma razón: acá el runtime no lleva
 // reemplazos, así que lo que habríamos escrito es el archivo del paquete tal cual.
-function copyRuntime(source, target, preserve = false, boundary = target, skip = []) {
+// `preserve` conserva todo lo que ya exista —es lo que `init` necesita— y `conservar` conserva sólo lo
+// que responda que sí, que es lo que `upgrade` necesita para saltear una edición local sin congelar el
+// resto del directorio. Son dos preguntas distintas y por eso no se unifican en una.
+function copyRuntime(source, target, preserve = false, boundary = target, skip = [], conservar = () => false) {
   F.assertNoSymlinkPath(boundary, target)
   fs.mkdirSync(target, { recursive: true })
   const preserved = {}
@@ -73,7 +76,8 @@ function copyRuntime(source, target, preserve = false, boundary = target, skip =
     if (skip.includes(entry.name)) continue
     const from = path.join(source, entry.name)
     const to = path.join(target, entry.name)
-    if (entry.isDirectory()) Object.assign(preserved, copyRuntime(from, to, preserve, boundary, skip))
+    if (!entry.isDirectory() && conservar(to)) continue
+    if (entry.isDirectory()) Object.assign(preserved, copyRuntime(from, to, preserve, boundary, skip, conservar))
     else if (preserve && fs.existsSync(to)) {
       console.log(`= conservado ${to}`)
       preserved[to] = M.digest(from)
@@ -293,12 +297,19 @@ function upgrade(dir, cli) {
     )
   }
 
-  if (changed.length && !force) {
-    for (const file of changed) console.error(`✗ ${file}`)
-    fail(
-      `\n${changed.length} archivo(s) que mantiene Cauce fueron editados y se perderían.\n\n` +
-      `${adviceFor(changed)}\n\nSi el cambio ya no te sirve, repetí con --force para descartarlo.`,
-    )
+  // Lo que el 001 protege es que una edición local no se pierda, y abortar la corrida entera era una
+  // forma cara de conseguirlo: dejaba a quien adoptó Cauce sobre un proceso propio eligiendo entre no
+  // actualizar nunca y descartar su corpus. Se conserva archivo por archivo y se actualiza el resto,
+  // que es donde viven las reglas que los agentes leen.
+  //
+  // El aviso sale en **cada** corrida y no sólo la primera: una instancia con medio molde congelado y
+  // sin enterarse es el otro modo de fallo, y es silencioso.
+  const conservados = force ? new Set() : new Set(changed)
+  if (conservados.size) {
+    for (const file of conservados) console.log(`= conservado ${file} (editado localmente)`)
+    console.log(`\n${conservados.size} archivo(s) del molde quedan congelados por tu edición.`)
+    console.log(`${adviceFor([...conservados])}\n`)
+    console.log('Para tomar la versión nueva y descartar la tuya, repetí con --force.\n')
   }
 
   // Lo que una versión agrega y es del proyecto: se crea si falta y nunca se pisa. `systemPaths` no lo
@@ -339,13 +350,15 @@ function upgrade(dir, cli) {
     }
   }
 
+  const conservar = (file) => conservados.has(path.relative(root, file).replace(/\\/g, '/'))
   for (const relative of [...system, ...O.RUNTIME_PATHS]) {
     const origin = path.join(PROJECT_ROOT, O.sourceOf(relative))
     if (!fs.existsSync(origin)) continue
     const target = path.join(root, relative)
+    if (conservados.has(relative)) continue
     // Sobrescribe lo que trae el paquete y deja intacto lo demás: un guard propio de la empresa,
     // o un adaptador de runner que el toolkit no conoce, sobreviven a la actualización.
-    if (fs.statSync(origin).isDirectory()) copyRuntime(origin, target, false, root)
+    if (fs.statSync(origin).isDirectory()) copyRuntime(origin, target, false, root, [], conservar)
     else {
       F.assertNoSymlinkPath(root, target)
       F.atomicWrite(target, fs.readFileSync(origin, 'utf8'))
@@ -368,11 +381,17 @@ function upgrade(dir, cli) {
   // Dejar registrado lo que se entregó, para poder distinguir después una edición local de una
   // mejora del toolkit.
   let record = M.read(root)
+  // Lo que el toolkit entregó la última vez, antes de re-registrar. Un archivo conservado tiene que
+  // conservar **ese** digest: registrar el de disco lo volvería idéntico a lo entregado, dejaría de
+  // detectarse como editado y la corrida siguiente lo pisaría sin decir nada. Es el 001 de vuelta por
+  // la puerta de atrás, y no se ve mirando el archivo — se ve dos upgrades después.
+  const entregado = { ...record }
   for (const relative of O.trackedPaths()) {
     const dir = path.join(root, relative)
     if (fs.existsSync(dir)) record = M.record(root, relative, O.treeFiles(dir), record)
   }
   record = M.recordPaths(root, O.SYSTEM_FILES, record)
+  for (const file of conservados) if (entregado[file]) record[file] = entregado[file]
   // El registro de forks se poda igual que el de archivos: un cargo devuelto al catálogo deja su
   // entrada, y una entrada sin copia sólo puede producir avisos sobre algo que no está.
   const kept = Object.fromEntries(Object.entries(M.readForks(root)).filter(

package/engine/cli/ops.js

@@ -143,6 +143,7 @@ function usage() {
   ops check <planning-dir> [--json]
   ops tree <planning-dir> [--no-color] [--json]
   ops context <planning-dir> [--json]
+  ops evidence <planning-dir> [--task <slug>] [--json]
   ops upgrade <ops-root> [--check] [--force]
   ops destroy <ops-root> [--force]
   ops archive <planning-dir> <NNN|human-actions>
@@ -195,6 +196,7 @@ async function run(cli) {
   else if (command === 'check') PL.check(arg[1], cli)
   else if (command === 'tree') PL.tree(arg[1], cli)
   else if (command === 'context') PL.context(arg[1], cli)
+  else if (command === 'evidence') PL.evidence(arg[1], cli)
   else if (command === 'upgrade') IN.upgrade(arg[1], cli)
   else if (command === 'destroy') IN.destroy(arg[1], cli)
   else if (command === 'agents') CAT.agents(arg[1], arg[2], arg[3], cli)

package/engine/cli/planning.js

@@ -14,6 +14,7 @@ const AD = require('../planning/adoption')
 const AP = require('../hooks/approval')
 const I = require('../integrations/registry')
 const O = require('../core/ownership')
+const EV = require('../core/evidence')
 const OB = require('../core/onboarding')
 const C = require('../config/validate')
 const CP = require('../config/paths')
@@ -27,6 +28,44 @@ const { fail } = require('./io')
 //
 // Va como advertencia y no como error: la empresa es dueña de esos archivos y puede reestructurarlos a
 // propósito. Lo que no puede pasar es que una dimensión desaparezca sin que se vea.
+// El contraste de la evidencia de una entrada de DONE contra lo que no lo escribió su autor. No es una
+// puerta y por eso no vive en `check`: `check` juzga todo DONE, y el registro de gates es rodante —una
+// entrada de hace tres meses no tiene con qué cruzarse—. Acá se pregunta por una entrada, que es como
+// se cierra una tarea: se escribe la evidencia y se la mira contra el árbol y contra lo que corrió.
+function evidence(dir, cli) {
+  const root = path.resolve(dir || '.')
+  const opsDir = path.join(root, '..')
+  const entries = P.readDone(root).entries
+  const slug = cli.value('--task')
+  const entry = slug ? entries.find((one) => one.slug === slug) : entries[entries.length - 1]
+  if (!entry) return fail(slug ? `DONE no tiene la entrada ${slug}` : 'DONE no tiene ninguna entrada', 2)
+
+  let config = {}
+  try { config = JSON.parse(fs.readFileSync(path.join(opsDir, 'ops.config.json'), 'utf8')) } catch { /* sin raíces */ }
+  const roots = (Array.isArray(config.workspaceRoots) ? config.workspaceRoots : [])
+    .filter((workspace) => workspace && workspace.path)
+    .map((workspace) => path.resolve(opsDir, workspace.path))
+    .filter((one) => fs.existsSync(one))
+  const traces = EV.contrast(entry.tests, roots)
+  const runs = EV.runs(opsDir)
+  const report = { task: entry.slug, epic: entry.epic, traces, runs }
+  if (cli.has('--json')) return console.log(JSON.stringify(report))
+
+  console.log(`TAREA  ${entry.slug}${entry.epic ? ` (epic: ${entry.epic})` : ''}`)
+  if (!traces.length) console.log('TESTS  (la entrada no rastrea ningún criterio)')
+  for (const trace of traces) {
+    const nota = trace.verdict === 'inbuscable'
+      ? (roots.length ? 'describe la prueba en vez de nombrarla' : 'el proyecto no declara raíces de código')
+      : ''
+    console.log(`  ${trace.criterion} → ${trace.artifact}  [${trace.verdict}]${nota ? ` — ${nota}` : ''}`)
+  }
+  if (!runs.length) console.log('GATES  (sin corridas registradas; `verify` todavía no corrió acá)')
+  for (const run of runs) console.log(`GATES  ${run.at}  ${run.gate} (exit ${run.status})`)
+  // Un contraste que no dice qué no puede ver se lee como si lo hubiera visto todo.
+  console.log('Este contraste dice si el artefacto existe y qué gates corrieron al commitear. No dice '
+    + 'que la prueba nombrada haya corrido: eso depende del runner, y varios no la nombran al pasar.')
+}
+
 function check(dir, cli) {
   const root = path.resolve(dir || '.')
   const errors = []
@@ -96,6 +135,15 @@ function check(dir, cli) {
       + 'el archivo sigue autorizándolas')
   }
 
+  // Lo que `upgrade` conserva por estar editado deja de recibir mejoras, y eso es una deuda que no
+  // avisa sola: la instancia queda con medio molde viejo y todo se ve normal. Sale acá para que se vea
+  // en cada corrida y no sólo el día que alguien actualiza.
+  const congelados = O.localChanges(path.resolve(root, '..'))
+  if (congelados.length) {
+    warnings.push(`${congelados.length} archivo(s) del molde congelados por edición local; `
+      + '`upgrade` los conserva y no les trae mejoras')
+  }
+
   const integration = I.validate(path.resolve(root, '..'))
   errors.push(...integration.errors)
   warnings.push(...integration.warnings)
@@ -356,4 +404,4 @@ function archive(dir, rawNum) {
   console.log(`✓ epic-${num}: ${entries.length} entrada(s) archivadas`)
 }
 
-module.exports = { check, tree, context, archive, adopt }
+module.exports = { check, evidence, tree, context, archive, adopt }

package/engine/cli/upgrade-report.js

@@ -44,6 +44,18 @@ function adviceFor(changed) {
       + 'es suyo —una ADR propia, una regla propia, o `planning/delivery/project.md` para la entrega—.',
     )
   }
+  // El consejo de arriba manda mudar lo propio a donde sí es del proyecto, y para estos cuatro no hay
+  // adónde: no existe un PROTOCOL de la empresa que le gane al del toolkit como sí lo hay en `rules/`.
+  // Sin decirlo, quien adoptó Cauce sobre su propio proceso lee un consejo que no puede seguir.
+  const SIN_CONTRAPARTE = ['planning/PROTOCOL.md', 'planning/METHODOLOGY.md', 'planning/FLOW.md', 'Makefile']
+  const propios = docs.filter((file) => SIN_CONTRAPARTE.includes(file))
+  if (propios.length) {
+    advice.push(
+      `${propios.join(', ')} no tienen contraparte propia adónde mudarse: son del toolkit y no hay\n`
+      + 'una versión del proyecto que le gane. Quedan congelados con tu versión y el resto se actualiza\n'
+      + 'igual. Adoptar el del toolkit es trabajo propio —comparar los dos procesos y decidir—, no un flag.',
+    )
+  }
   // `AGENTS.md` se lo gana aparte porque hasta ahora el README mandaba completarlo, así que el consejo
   // genérico de arriba —«no llevan una línea de la empresa»— le miente justo a quien le hizo caso.
   if (docs.includes('AGENTS.md')) {

package/engine/cli/wiring.js

@@ -12,6 +12,7 @@ const A = require('../automation')
 const SC = require('../core/scan')
 const OB = require('../core/onboarding')
 const IN = require('./instance')
+const ST = require('../planning/state')
 const { fail, opsRoot } = require('./io')
 
 // Cuántos servicios se listan en pantalla antes de recortar. El resto sigue en `--json`, que es lo que
@@ -234,6 +235,13 @@ function automation(action, rootArg, runnerName, cli) {
     console.log(
       `✓ automatización válida: ${A.GUARD_NAMES.length} guards, ${A.RUNNER_NAMES.length} adaptadores`,
     )
+    // De los guards instalados hay uno que no siempre corre, y un guard que a veces no corre tiene que
+    // decir cuándo. `plan-first` queda inerte mientras el planning no declare ninguna tarea; sin esta
+    // línea la condición sería invisible y el conteo de arriba prometería una cobertura que no está.
+    const planning = path.join(root, 'planning')
+    if (fs.existsSync(planning) && !ST.hasTasks(planning)) {
+      console.log('  plan-first: inerte, el planning todavía no declara tareas')
+    }
     return
   }
   if (action === 'doctor') {

package/engine/core/evidence.js

@@ -0,0 +1,107 @@
+'use strict'
+
+// El contraste entre lo que una entrada de DONE dice haber probado y lo que se puede comprobar sin
+// creerle. Existe porque los dos lados de `tests: CN → prueba` los escribe el mismo autor en el mismo
+// acto: comparar eso mide consistencia de prosa, no que la prueba exista.
+//
+// Son dos preguntas con alcances distintos y por eso se responden por separado:
+//
+// - **El artefacto existe**: se busca el nombre en las raíces declaradas. Vale para cualquier stack y
+//   es lo que atrapa la prueba inventada o renombrada, que es la forma de la evidencia falsa.
+// - **El gate corrió**: sale del registro que escribe `verify`, que es la única vez que el toolkit
+//   ejecuta algo y ve su código de salida.
+//
+// Lo que NO se puede responder acá, y decirlo es parte del contraste: que la prueba nombrada haya
+// corrido. Depende del runner, y no de una forma que se pueda normalizar: verificado corriendo una
+// prueba que pasa en go1.26.3, donde `go test ./...` imprime `ok <paquete>` y nunca su nombre, y en
+// node v24.18.0, donde `node --test` imprime `✔ <nombre>`. Una comprobación construida sobre la
+// salida diría «no aparece» sobre los stacks del primer tipo, donde sí corrió.
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const LOG = path.join('planning', '.verify-log')
+// Rodante: interesa el trabajo en curso, no la historia. Sin tope, el archivo crece con cada commit y
+// nadie lo mira; con tope, lo que queda es lo que todavía se puede cruzar contra una entrada abierta.
+const MAX_RUNS = 20
+
+function logPath(root) {
+  return path.join(root, LOG)
+}
+
+// Una línea por gate corrido. Nunca lanza: es un efecto de borde de un guard, y un registro que no se
+// puede escribir no puede impedir el commit que estaba juzgando.
+function record(root, gate, status) {
+  if (!root) return
+  try {
+    const file = logPath(root)
+    const previous = fs.existsSync(file) ? fs.readFileSync(file, 'utf8').split('\n').filter(Boolean) : []
+    const entry = JSON.stringify({ at: new Date().toISOString(), gate, status })
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, `${[...previous, entry].slice(-MAX_RUNS).join('\n')}\n`)
+  } catch { /* el registro es evidencia, no una puerta */ }
+}
+
+function runs(root) {
+  try {
+    return fs.readFileSync(logPath(root), 'utf8').split('\n').filter(Boolean)
+      .map((line) => { try { return JSON.parse(line) } catch { return null } }).filter(Boolean)
+  } catch { return [] }
+}
+
+// Los rastros de una línea `tests:`, ya partidos en criterio y artefacto. `n/a — razón` no rastrea
+// ninguno a propósito y sale de acá vacío, igual que en `contracts`.
+function traces(tests) {
+  return String(tests || '').split(/\s*;\s*/).filter(Boolean)
+    .map((item) => item.match(/^(A|C\d+)\s*(?:→|->)\s*(.+)$/i))
+    .filter(Boolean)
+    .map((match) => ({ criterion: match[1].toUpperCase(), artifact: match[2].trim() }))
+}
+
+// Qué se puede ir a buscar. Un artefacto con espacios describe la prueba en vez de nombrarla —el molde
+// admite «nombre de prueba o comando»—, y buscar una frase en el código devuelve siempre que no. Se
+// declara inbuscable en vez de darlo por ausente: un contraste que confunde «no lo encontré» con «no
+// existe» enseña a no leerlo.
+function searchable(artifact) {
+  return /^[^\s]{4,}$/.test(artifact) && /[A-Za-z]/.test(artifact)
+}
+
+function sourceFiles(dir, found = [], depth = 0) {
+  if (depth > 8 || found.length > 5000) return found
+  let entries = []
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch { return found }
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name === '.git' || entry.name.startsWith('.')) continue
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) sourceFiles(full, found, depth + 1)
+    else found.push(full)
+  }
+  return found
+}
+
+// Si el nombre aparece en el árbol: como parte de una ruta de archivo o dentro del fuente de alguno.
+// Se mira el contenido y no sólo los nombres porque lo que un rastro nombra suele ser la prueba
+// —`TestAddSuma`— y no el archivo que la contiene.
+function findsArtifact(roots, artifact) {
+  for (const root of roots) {
+    for (const file of sourceFiles(root)) {
+      if (file.replace(/\\/g, '/').includes(artifact)) return true
+      let text = ''
+      try { text = fs.readFileSync(file, 'utf8') } catch { continue }
+      if (text.includes(artifact)) return true
+    }
+  }
+  return false
+}
+
+// El veredicto por rastro: `encontrado`, `ausente` o `inbuscable`. Sin raíces declaradas no se afirma
+// nada — no hay dónde mirar, y decir «ausente» ahí sería inventar el hallazgo.
+function contrast(tests, roots) {
+  return traces(tests).map((trace) => {
+    if (!searchable(trace.artifact)) return { ...trace, verdict: 'inbuscable' }
+    if (!roots.length) return { ...trace, verdict: 'inbuscable' }
+    return { ...trace, verdict: findsArtifact(roots, trace.artifact) ? 'encontrado' : 'ausente' }
+  })
+}
+
+module.exports = { MAX_RUNS, record, runs, traces, contrast }

package/engine/core/ownership.js

@@ -295,6 +295,7 @@ function localChanges(root) {
 module.exports = {
   RETIRED,
   TEMPLATE_OWN,
+  TEMPLATE_PREFIXES,
   addedPaths,
   trackedPaths,
   packageDir,

package/engine/hooks/files.js

@@ -11,6 +11,9 @@ const {
   writableRoots, outsideRoots, DECLARE_IT,
 } = require('./input')
 const AP = require('./approval')
+const { readWip } = require('../planning/parser')
+const { hasTasks } = require('../planning/state')
+const { TEMPLATE_PREFIXES } = require('../core/ownership')
 
 // La raíz donde vive `planning/`, que es donde se busca la aprobación por operación.
 function opsRoot(input) {
@@ -108,6 +111,54 @@ function testEvidence(input) {
   }
 }
 
+// Lo que la instancia recibe del molde, más los cargos que forkeó. `plan-first` no lo juzga, y no es una
+// concesión: el plan se escribe en `planning/`, así que exigirlo ahí sería un candado cuya llave está
+// adentro. Los recorridos que no pasan por la máquina de tareas escriben en las otras raíces —`onboard`
+// en `organization/`, una evaluación en `agents/`, el sincronizador en `integrations/`— y tampoco tienen
+// un WIP que mostrar. Sale de `ownership` para que una raíz nueva del molde quede exenta sola; `agents/`
+// se suma acá porque no viene del molde, la escribe `fork` en la instancia.
+const OPS_OWNED = [...TEMPLATE_PREFIXES, 'agents/']
+
+function opsOwned(root, file) {
+  const relative = path.relative(root, file).replace(/\\/g, '/')
+  if (!relative || relative.startsWith('../') || path.isAbsolute(relative)) return false
+  return OPS_OWNED.some((prefix) => relative.startsWith(prefix))
+}
+
+// R1 y el paso 7 del protocolo piden el plan antes del primer cambio, y hasta acá nadie lo comprobaba:
+// tocar el archivo primero y redactar después la aceptación que lo justifica sale igual de verde que
+// hacerlo al revés, y se lee igual en DONE. Lo que se exige es lo mínimo que separa un plan de una
+// intención —WIP activo con al menos un paso escrito—, no que el paso sea bueno; eso lo mira Critique.
+//
+// El conteo sale del mismo parser que `check` y `context`, así que lo que el guard llama plan es lo que
+// el resto del motor llama plan. Un WIP con frontmatter y sin pasos es el estado intermedio que esto
+// vigila: la tarea ya está nombrada y el plan todavía no existe.
+function planFirst(input) {
+  if (process.env.OPS_PLAN_FIRST_OVERRIDE === '1') return
+  const root = opsRoot(input)
+  if (!root) return
+  const planning = path.join(root, 'planning')
+  const wip = readWip(planning)
+  if (wip && wip.complete + wip.pending > 0) return
+  // Una instancia recién creada no tiene de dónde sacar una tarea: `onboard` deja el roadmap vacío y
+  // dice que alguien lo llene. Exigir el plan ahí es un candado delante de la puerta, y la salida que
+  // enseña es apagar el guard en el entorno, que lo deja sin morder para siempre. Se pregunta recién
+  // acá: en una instancia con trabajo el camino común sale por el WIP de arriba y no paga esta lectura.
+  // Que el guard quede inerte lo dice `automation check`, porque una condición invisible es peor que
+  // no tenerla.
+  if (!hasTasks(planning)) return
+  const estado = wip ? `WIP tiene la tarea ${wip.task} y ningún paso` : 'WIP está en IDLE'
+  const why = `${estado}, así que el plan todavía no está escrito.\n`
+    + 'Escribí en planning/WIP.md la tarea y su plan aprobado —pasos numerados, cada uno con un estado '
+    + 'verificable— y volvé al cambio. Si esto no es trabajo de una tarea, aprobá la ruta.\n'
+    + AP.HOW('OPS_PLAN_FIRST_OVERRIDE')
+  for (const raw of filesOf(input)) {
+    if (opsOwned(root, path.resolve(cwdOf(input), raw))) continue
+    if (approved(input, raw)) continue
+    block(`${raw} cambia el producto sin plan. ${why}`)
+  }
+}
+
 function workspaceBoundary(input) {
   const allowed = writableRoots(input)
   if (!allowed) return
@@ -182,4 +233,7 @@ function engineWrites(input) {
   }
 }
 
-module.exports = { secrets, integrationSnapshot, generated, testEvidence, workspaceBoundary, migrations, engineWrites }
+module.exports = {
+  secrets, integrationSnapshot, generated, testEvidence, planFirst, workspaceBoundary,
+  migrations, engineWrites,
+}

package/engine/hooks/run.js

@@ -46,6 +46,7 @@ const guards = {
   migrations: files.migrations,
   'integration-snapshot': files.integrationSnapshot,
   'test-evidence': files.testEvidence,
+  'plan-first': files.planFirst,
   'planning-drift': planningDrift,
 }
 
@@ -53,7 +54,7 @@ const guards = {
 const hookGroups = {
   'pre-shell': ['destructive', 'git-add', 'dependencies', 'governance', 'verify', 'shell-boundary'],
   'pre-files': ['secrets', 'generated', 'workspace-boundary', 'engine', 'migrations',
-    'integration-snapshot', 'test-evidence'],
+    'integration-snapshot', 'test-evidence', 'plan-first'],
   stop: ['planning-drift'],
 }
 
@@ -119,6 +120,11 @@ const hookMetadata = [
     event: 'PreToolUse · files',
     purpose: 'Impide apagar o borrar la prueba que juzga el cambio.',
   },
+  {
+    name: 'plan-first',
+    event: 'PreToolUse · files',
+    purpose: 'Exige WIP activo con plan escrito antes de cambiar el producto.',
+  },
   {
     name: 'planning-drift',
     event: 'Stop / SessionEnd',

package/engine/hooks/shell.js

@@ -13,6 +13,7 @@ const {
   writableRoots, outsideRoots, DECLARE_IT, unquoted, findOpsRoot, withoutGitGlobals,
 } = require('./input')
 const AP = require('./approval')
+const EV = require('../core/evidence')
 
 // Dónde empieza y dónde termina una palabra dentro de un comando. Tres reglas de la tabla de abajo lo
 // decidían por su cuenta admitiendo sólo un espacio, el principio o el fin, y en un shell una palabra
@@ -394,14 +395,24 @@ function commitTree(dir) {
     fs.mkdirSync(path.dirname(link), { recursive: true })
     fs.symlinkSync(path.join(dir, name), link, 'junction')
   }
-  // Un índice materializado no trae `.git`, y un gate que llama a git —listar lo trackeado, leer una
-  // etiqueta— falla ahí por no encontrarlo: el guard frenaría un commit correcto por su propia
-  // mecánica. Comprobado sobre la suite de este repositorio, que pasa de dos fallos a ninguno con estas
-  // dos variables. Apuntan al repositorio de verdad con el árbol puesto en la copia, así que `git`
-  // contesta sobre lo que se va a commitear.
-  const gitDir = run('git', ['-C', dir, 'rev-parse', '--absolute-git-dir'], dir)
-  const env = gitDir.ok ? { GIT_DIR: gitDir.output.trim(), GIT_WORK_TREE: temp } : {}
-  return { root: temp, temp, env }
+  // Un índice materializado no trae `.git`, y un gate que llama a git —listar lo trackeado— falla ahí
+  // por no encontrarlo: el guard frenaría un commit correcto por su propia mecánica. La copia se vuelve
+  // un repositorio propio, con su índice cargado desde lo que se acaba de materializar, así que `git`
+  // contesta sobre lo que el commit va a grabar.
+  //
+  // Antes esto se resolvía exportando `GIT_DIR` del repositorio de verdad, y ahí el gate que **escribe**
+  // con git escribía en él: la suite de un proyecto levanta repositorios de prueba y les commitea, y
+  // esos commits caían en la rama del usuario junto con un `core.worktree` apuntando a un temporal ya
+  // borrado. Nada lo anunciaba (caso 045).
+  //
+  // Lo que se pierde a cambio, y son dos cosas. La copia no tiene historia, así que un gate que lea una
+  // etiqueta o un `git log` no la encuentra: falla y se ve. Y un gate cuyo efecto ES una escritura de
+  // git —taggear, commitear un lockfile regenerado— la hace sobre la copia, que se borra: ese efecto se
+  // pierde en silencio. Se elige el silencio de acá sobre el de antes, que era escribir en la rama de
+  // quien commitea; un proyecto con un gate así tiene que sacar esa escritura del gate.
+  const started = run('git', ['init', '--quiet'], temp)
+  if (started.ok) run('git', ['add', '--all'], temp)
+  return { root: temp, temp, env: {} }
 }
 
 function verify(input) {
@@ -429,7 +440,7 @@ function verify(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)
   try {
-    verifyGates(root, dir, aprobado, env)
+    verifyGates(root, dir, aprobado, env, opsRoot(input))
   } finally {
     if (temp) fs.rmSync(temp, { recursive: true, force: true })
   }
@@ -438,7 +449,11 @@ function verify(input) {
 // Corre lo que el stack declare y bloquea si algo sale en rojo. `root` es dónde corre —el índice
 // materializado o el árbol, que ahí son lo mismo— y `dir` es el repositorio, que es el nombre que le
 // dice algo a quien lee el mensaje.
-function verifyGates(root, dir, aprobado, env) {
+//
+// Cada gate deja su rastro en `ops`; para qué sirve ese registro lo dice `core/evidence.js`. Lo que se
+// decide acá es que el rojo se anota igual que el verde: un gate que falló y se commiteó con
+// aprobación es exactamente lo que alguien va a querer ver después.
+function verifyGates(root, dir, aprobado, env, ops) {
   const failures = []
   if (fs.existsSync(path.join(root, 'package.json'))) {
     const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'))
@@ -448,16 +463,19 @@ function verifyGates(root, dir, aprobado, env) {
     for (const script of ['test', 'lint', 'typecheck', 'build']) {
       if (!pkg.scripts || !pkg.scripts[script]) continue
       const result = run(pm, ['run', script], root, env)
+      EV.record(ops, script, result.status)
       if (!result.ok) failures.push(`${script} (exit ${result.status})`)
     }
   } 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)
       if (!result.ok) failures.push(`make ci (exit ${result.status})`)
     } else {
       for (const args of [['test', './...'], ['build', './...']]) {
         const result = run('go', args, root, env)
+        EV.record(ops, `go ${args[0]}`, result.status)
         if (!result.ok) failures.push(`go ${args[0]} (exit ${result.status})`)
       }
     }
@@ -465,6 +483,7 @@ function verifyGates(root, dir, aprobado, env) {
     const makefile = path.join(root, 'Makefile')
     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)
       if (!result.ok) failures.push(`make test (exit ${result.status})`)
     }
   }

package/engine/planning/parser.js

@@ -286,10 +286,34 @@ const HUMAN_ACTION_STATES = ['pendiente', 'resuelta']
 // («resuelta 2026-08-17») siga valiendo sin que una palabra suelta dentro de un texto largo resuelva
 // una fila que sigue abierta. `valid` distingue la fila mal escrita de la fila pendiente: las dos
 // bloquean, pero sólo una es un error que hay que reportar.
+// En markdown un pipe dentro de una celda se escribe `\|` —es la única forma que hay— así que partir
+// por todo `|` abre esa celda en dos y corre las columnas de la fila. El daño peor es silencioso: con el
+// pipe detrás de la palabra del vocabulario, el estado sigue leyéndose bien, `check` pasa y lo que se
+// entrega como acción de desbloqueo es el contenido de `Origen`.
+//
+// Lo que no cubre: una celda que termine en una barra invertida literal. En markdown eso se escribe
+// `\\` y acá se leería como escape del separador. Es un borde que nadie escribe y taparlo pedía un
+// parser de verdad; queda dicho en vez de supuesto.
+const SEPARADOR = /(?<!\\)\|/
+const SEPARADORES = /^\|\s*:?-+/
+
+// El escape se quita al normalizar. Esta columna existe para que una persona lea qué tiene que hacer, y
+// `\|` no es parte de lo que quiso decir: es cómo markdown escribe un pipe. La fila archivada no se ve
+// afectada —`archive` reescribe `raw`, la línea original, no las celdas—, así que quitarlo no pierde nada.
+const celda = (cell) => cell.trim().replace(/\\\|/g, '|')
+
 function readHumanActions(dir) {
-  const rows = withoutComments(read(path.join(dir, 'HUMAN_ACTIONS.md'))).split('\n')
-    .filter((line) => /^\|/.test(line) && !/^\|\s*:?-+/.test(line))
-    .map((line) => ({ line, cells: line.split('|').slice(1, -1).map((cell) => cell.trim()) }))
+  const lineas = withoutComments(read(path.join(dir, 'HUMAN_ACTIONS.md'))).split('\n')
+  // En markdown la cabecera es la fila anterior a la de separadores, diga lo que diga su primera celda.
+  // Se marcan todas y no la primera: un archivo con una tabla por sección tiene una cabecera por tabla,
+  // y con `findIndex` la segunda y la tercera vuelven a leerse como datos. Nada más se mueve, porque una
+  // fila de datos nunca está inmediatamente antes de los guiones.
+  const cabeceras = new Set(lineas.map((line, i) => (SEPARADORES.test(line) ? i - 1 : -1)))
+  const rows = lineas
+    .filter((line, i) => /^\|/.test(line) && !SEPARADORES.test(line) && !cabeceras.has(i))
+    .map((line) => ({ line, cells: line.split(SEPARADOR).slice(1, -1).map(celda) }))
+  // El literal queda como resguardo de la tabla escrita sin su fila de separadores: markdown no la
+  // renderiza como tabla, y este parser lee sus filas igual.
   return rows.filter(({ cells }) => cells.length >= 4 && !/^tarea$/i.test(cells[0]))
     .map(({ line, cells }) => {
       const state = (cells[1].match(new RegExp(`^(${HUMAN_ACTION_STATES.join('|')})\\b`, 'i')) || [])[1] || ''

package/engine/planning/state.js

@@ -50,4 +50,14 @@ function currentTask({ milestones, done, wip }, blockers = []) {
 }
 
 
-module.exports = { snapshot, pendingHumanActions, currentTask }
+// Si el planning declara trabajo, en cualquiera de sus dos estados. Lo preguntan dos: el guard
+// `plan-first`, para no exigir un plan donde todavía no hay de dónde sacar una tarea, y
+// `automation check`, para poder decir que ese guard está inerte. Vive acá y no en el guard porque con
+// dos copias una se pudre y el reporte anuncia una condición distinta de la que el guard aplica.
+function hasTasks(root) {
+  return P.readBacklog(root).some((milestone) => milestone.tasks.length > 0)
+    || P.readDone(root).entries.length > 0
+}
+
+
+module.exports = { snapshot, pendingHumanActions, currentTask, hasTasks }

package/package.json

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

package/template/AGENTS.md

@@ -139,6 +139,7 @@ y eso lo deja apagado **hasta que cierres la sesión**, no para un comando.
 | `OPS_MIGRATIONS_OVERRIDE=1` | el de migraciones |
 | `OPS_TEST_EVIDENCE_OVERRIDE=1` | el de evidencia de pruebas |
 | `OPS_DEPENDENCIES_OVERRIDE=1` | el de dependencias, incluido publicar e instalar global |
+| `OPS_PLAN_FIRST_OVERRIDE=1` | el que exige plan antes de cambiar el producto |
 | `OPS_SKIP_VERIFY=1` | el que corre los gates |
 
 Por eso la aprobación es la vía recomendada y esto es lo que queda cuando no alcanza: prendela para lo
@@ -153,8 +154,14 @@ muta nada.
   aceptación y sus criterios. Es la entrada correcta para empezar a trabajar.
 - `node tools/ops.js tree planning` — panorama de roadmap, backlog, WIP, inbox y done.
 - `node tools/ops.js check planning` — validación de contratos y trazabilidad.
-
-Los tres aceptan `--json`. Leer `BACKLOG.md`, `WIP.md` o `HUMAN_ACTIONS.md` completos sólo cuando haga
+- `node tools/ops.js evidence planning [--task <slug>]` — contrasta la evidencia de una entrada de DONE
+  contra lo que no escribió su autor: si el artefacto que `tests:` nombra existe en las raíces de
+  código, y qué gates corrió `verify` al commitear, con su código de salida. Al cerrar una tarea, es la
+  única parte de esa evidencia que no sale de la misma mano que la afirma. No dice que la prueba
+  nombrada haya corrido —eso depende del runner, y varios no la nombran al pasar— ni reemplaza a leer
+  su fuente, que es lo que R9 pide.
+
+Los cuatro aceptan `--json`. Leer `BACKLOG.md`, `WIP.md` o `HUMAN_ACTIONS.md` completos sólo cuando haga
 falta editarlos o cuando el CLI no responda la pregunta.
 
 ## Autonomía

package/template/gitignore

@@ -5,5 +5,9 @@ node_modules/
 .env.*
 !.env.example
 
+# El registro de gates que escribe `verify`: es evidencia de una corrida local, rodante y de la
+# máquina. Committearlo sería historia que nadie lee y un conflicto por commit.
+planning/.verify-log
+
 *.tgz
 .DS_Store