@ingeniomaps/cauce 0.98.0 → 0.99.1

package/automatization/workflows/autobuild.js

@@ -28,6 +28,7 @@ export const meta = {
 
 {{INCLUDE:shared/workflow-root.js}}
 {{INCLUDE:shared/inbox.js}}
+{{INCLUDE:shared/acceptance.js}}
 const CONFIG = `${ROOT}/ops.config.json`
 const P = `${ROOT}/planning`
 const ORG = `${ROOT}/organization`
@@ -190,19 +191,28 @@ const REVIEWED = { ...DECISION, required: [...DECISION.required, 'rules'],
 // menos —o que ni existe— sale verde igual, y el guard de verify tampoco lo ve porque también mira exit
 // codes. Por eso `uncovered` se contrasta contra la aceptación leyendo el fuente, no la salida (R9).
 const VERIFY = {
-  type: 'object', additionalProperties: false, required: ['passed', 'commands', 'details', 'uncovered'],
+  type: 'object', additionalProperties: false, required: ['passed', 'commands', 'details', 'uncovered', 'covered'],
   properties: {
     passed: { type: 'boolean' }, details: { type: 'string' },
-    // Dos causas que se leen igual en el resultado y piden cosas opuestas: a una le falta trabajo que
-    // el propio recorrido puede hacer, a la otra le falta una decisión que no es suya. Sin separarlas,
-    // la corrida frena por las dos y una persona termina resolviendo lo que se resolvía solo.
+    // Tres causas que se leen igual en el resultado y piden cosas distintas: a una le falta trabajo que
+    // el propio recorrido puede hacer, a otra le falta una decisión que no es suya, y la tercera no tiene
+    // prueba posible porque su entregable no se ejecuta —un ADR, una política—. Sin separarlas, la corrida
+    // frena por las tres, una persona resuelve lo que se resolvía solo y la tarea de decisión no cierra
+    // nunca (caso 189). `reason` es lo que Done escribe en `tests: n/a — <razón>`.
     uncovered: { type: 'array', items: { type: 'object', additionalProperties: false,
       required: ['criterion', 'cause'],
       properties: {
         criterion: { type: 'string' },
-        cause: { type: 'string', enum: ['missing-test', 'ambiguous'] },
+        cause: { type: 'string', enum: ['missing-test', 'ambiguous', 'no-surface'] },
+        reason: { type: 'string' },
       },
     } },
+    // El mapeo que Verify arma al contrastar y del que sale `tests: CN → prueba`. Sin viajar, Done lo
+    // componía de memoria (hallazgo del 189).
+    covered: { type: 'array', items: { type: 'object', additionalProperties: false,
+      required: ['criterion', 'test'],
+      properties: { criterion: { type: 'string' }, test: { type: 'string' } },
+    } },
     commands: { type: 'array', items: { type: 'object', required: ['cmd', 'exitCode'], properties: {
       cmd: { type: 'string' }, exitCode: { type: 'integer' }, note: { type: 'string' },
       ranTests: { type: 'boolean' },
@@ -582,13 +592,13 @@ while (rounds++ < MAX_TASKS) {
   // por eso perder la carrera no es un error: se relee y se sigue con la que quedó libre.
   if (!planning.claimed && !planning.wipActive) {
     phase('Claim')
-    const reserva = await write(
+    const claim = await write(
       `Corré "node tools/ops.js claim ${P} ${task.id}" desde ${ROOT}. No escribas ningún archivo vos: lo ` +
       `escribe el comando. claimed=true sólo con exit 0; si falla porque la tomó otro, claimed=false y ` +
       `copiá el mensaje en details.`,
       { schema: CLAIM, label: `claim:${task.id}` },
     )
-    if (!reserva || !reserva.claimed) {
+    if (!claim || !claim.claimed) {
       planning = await readContext()
       if (!planning) return stop('context-unavailable', `no se pudo releer el estado de ${P}`)
       // Perder la carrera es legítimo y se ve en que la cola pasa a ofrecer **otra** tarea: quien la
@@ -607,7 +617,7 @@ while (rounds++ < MAX_TASKS) {
       if (planning.hasTask && planning.slug === task.id && !planning.claimed) {
         return stop('claim-stuck', `${task.id} sigue siendo la próxima tarea y no se pudo reclamar. `
           + `context la ofrece y claim la rechaza, así que repetir no cambia nada. `
-          + `El reclamo contestó: ${(reserva && reserva.details) || '(sin detalle)'}`)
+          + `El reclamo contestó: ${(claim && claim.details) || '(sin detalle)'}`)
       }
       // Con qué sigue, que es lo que cambia respecto de lo que esperaba quien autorizó la corrida: se
       // pidió un hito y se va a construir otra tarea de ese hito. Sin decirlo, el cambio sólo aparece al
@@ -721,12 +731,12 @@ while (rounds++ < MAX_TASKS) {
 
   const planRejected = async (reason, unit, found) => {
     const detail = found.join('; ') || 'sin condiciones nombradas'
-    const nota = await registerHuman(
+    const note = await registerHuman(
       `Registrá ${unit.id} en ${HUMAN}: nadie pudo escribir un plan que sobreviva a la crítica. `
       + `Motivo: ${detail}. La acción humana es revisar si la unidad son dos resultados con vidas `
       + `distintas y partirla, o dejarla entera con la razón escrita.`, 'plan-human', unit.id)
     await releaseBlocked()
-    return stop(reason, `${detail}${nota}`)
+    return stop(reason, `${detail}${note}`)
   }
 
   if (!planning.wipActive) {
@@ -741,11 +751,11 @@ while (rounds++ < MAX_TASKS) {
       )
       if (!ready) return stop('agent-unavailable', 'Ready no devolvió resultado')
       if (!ready.ready) {
-        const nota = await registerHuman(
+        const note = await registerHuman(
           `Registrá ${task.id} en ${HUMAN} con el motivo y una acción humana exacta: ${ready.reason}.`,
           'ready-human', task.id)
         await releaseBlocked()
-        return stop('not-ready', `${ready.reason}${nota}`)
+        return stop('not-ready', `${ready.reason}${note}`)
       }
       if (ready.refinedAcceptance) task.acceptance = ready.refinedAcceptance
     }
@@ -1045,11 +1055,11 @@ while (rounds++ < MAX_TASKS) {
     if (filed.length) {
       // La nota que devuelve viaja al hecho: sin ella la entrega afirma una fila que el disco no tiene,
       // que es el caso 087 entrando por otra puerta.
-      const nota = await registerHuman(`Registrá en ${HUMAN} una fila por cada decisión que la revisión de `
+      const note = await registerHuman(`Registrá en ${HUMAN} una fila por cada decisión que la revisión de `
         + `${task.id} dejó abierta, con qué la cierra y quién puede tomarla. La primera columna nunca es `
         + `${task.id} —el porqué es el mismo que en Build—: va la épica, el hito o el recorrido al que `
         + `alcanza. No inventes responsables ni fechas: ${JSON.stringify(filed)}`, 'review-human')
-      decidedNote = `${nota}`
+      decidedNote = `${note}`
     }
     reviewFact = `${review.verdict} por ${cast.review}, sobre ${review.consulted.join(', ')}`
       + (filed.length ? ` · ${filed.length} decisión(es) registrada(s)${decidedNote}` : '')
@@ -1083,11 +1093,25 @@ while (rounds++ < MAX_TASKS) {
   }
 
   phase('Verify')
+  // Lo declarado `(fuera de verify: …)` se separa acá y no se le explica a Verify: la aceptación es texto
+  // conocido antes de preguntar, y dejar que el modelo reconozca la marca en la respuesta es apostar a que
+  // enumere los criterios con el mismo corte. `check` ofrecía la marca y el recorrido la mandaba igual,
+  // así que la condición terminaba en `uncovered` y la corrida en `verify-hollow` (caso 195).
+  const conditions = acceptanceConditions(task.acceptance)
+  const outOfVerify = conditions.filter((one) => OUT_OF_VERIFY.test(one))
+  const checkable = outOfVerify.length
+    ? conditions.filter((one) => !OUT_OF_VERIFY.test(one)).join('; ')
+      || 'ninguna: todas se declararon fuera de verify'
+    : task.acceptance
   const VERIFY_ASK = `${asRole(cast.verify)}Abrí el fuente de los tests que la tarea agregó o cambió y ` +
     `contrastá cada criterio ` +
     `de aceptación contra sus aserciones: en uncovered va el criterio que ningún test codifica, con su causa ` +
     `—missing-test si el test falta o no asercia la propiedad, ambiguous si el criterio no dice qué habría ` +
-    `que aserciar—. Un test que pasa sin aserciarla no la cubre. Después corré los gates reales de ${task.service}. ` +
+    `que aserciar, no-surface si se cumple en un artefacto que no se ejecuta, como un documento o una ` +
+    `decisión escrita, y con reason diciendo cuál—. no-surface vale sólo si la tarea no tocó ningún archivo ` +
+    `que no termine en ${NON_EXECUTABLE.join(', ')}; con cualquier otro en el diff es missing-test. En ` +
+    `covered va cada criterio que un test sí codifica, con el nombre de ese test. ` +
+    `Un test que pasa sin aserciarla no la cubre. Después corré los gates reales de ${task.service}. ` +
     // Descubrir la puerta es trabajo de modelo repetido en cada tarea sobre una respuesta que no cambia,
     // y encima adivinable: el proyecto la declara en `verify` y ahí deja de adivinarse. Cuando no la
     // declara se vuelve a descubrir, que es lo que pasaba siempre.
@@ -1100,7 +1124,7 @@ while (rounds++ < MAX_TASKS) {
     `Leé los exit codes de verdad. ` +
     `passed=true exige comandos corridos y ninguna regresión causada por la tarea. Marcá ranTests en el ` +
     `comando que haya corrido las pruebas, sea cual sea su nombre. ` +
-    `Aceptación: ${task.acceptance}.`
+    `Aceptación: ${checkable}.`
   let verified = await run(VERIFY_ASK, { schema: VERIFY, label: 'verify' })
   if (!verified) return stop('agent-unavailable', 'Verify no devolvió resultado')
   // Un criterio que nadie sabe cómo aserciar no es trabajo que falta sino una definición que falta, y
@@ -1108,14 +1132,18 @@ while (rounds++ < MAX_TASKS) {
   // hacer parar a una persona por eso le cobra una interrupción por algo que se resolvía solo.
   const ambiguous = verified.uncovered.find((entry) => entry.cause === 'ambiguous')
   if (ambiguous) {
-    const nota = await registerHuman(
+    const note = await registerHuman(
       `Registrá ${task.id} en ${HUMAN}: el criterio "${ambiguous.criterion}" no dice qué habría ` +
       `que aserciar, y hace falta la decisión que lo fija.`, 'verify-human', task.id)
-    return stop('acceptance-ambiguous', `${ambiguous.criterion}${nota}`)
+    return stop('acceptance-ambiguous', `${ambiguous.criterion}${note}`)
   }
-  if (verified.uncovered.length) {
+  // Lo que no tiene superficie no frena ni rebota: viaja a Done, que lo escribe como `tests: n/a`. Se filtra
+  // por exclusión y no por `missing-test` para que una causa que no se conozca siga frenando (R27). Que
+  // el modelo no lo use para cerrar sin pruebas lo sostiene `check`, que mira qué tocó el commit.
+  const lacking = () => verified.uncovered.filter((entry) => entry.cause !== 'no-surface')
+  if (lacking().length) {
     await run(`${asRole(cast.build)}Escribí sólo las pruebas que faltan en ${task.id}, con el mismo rojo ` +
-      `previo, y no toques el código de producción: ${verified.uncovered.map((e) => e.criterion).join('; ')}`,
+      `previo, y no toques el código de producción: ${lacking().map((e) => e.criterion).join('; ')}`,
       { label: 'missing-tests' })
     verified = await run(VERIFY_ASK, { schema: VERIFY, label: 'verify' })
     if (!verified) return stop('agent-unavailable', 'la segunda pasada de Verify no devolvió resultado')
@@ -1127,21 +1155,29 @@ while (rounds++ < MAX_TASKS) {
   if (build.redFirst.length && !ranTests) {
     return stop('verify-untested', `${task.id} escribió pruebas y ningún gate corrió una`)
   }
-  if (verified.uncovered.length) {
-    return stop('verify-hollow', `sin test que lo codifique: ${verified.uncovered.map((e) => e.criterion).join('; ')}`)
+  if (lacking().length) {
+    return stop('verify-hollow', `sin test que lo codifique: ${lacking().map((e) => e.criterion).join('; ')}`)
   }
+  const noSurface = verified.uncovered.filter((entry) => entry.cause === 'no-surface')
+  const covered = verified.covered || []
+  // Toda la tarea sin superficie: no hay comportamiento que ejercitar, y saltear QA en silencio dejaría sin
+  // mirar lo único que se puede mirar, que el documento esté y diga lo que la aceptación enumera.
+  const onlyDocument = noSurface.length > 0 && !covered.length
 
   // QA ejercita comportamiento, y lo mecánico no lo cambia: el valor literal que la aceptación nombra
   // ya lo comprobó Verify contra el test, y en `directo` además lo mira el revisor que nombra el cast.
   let qa = { passed: true, evidence: 'carril mecánico: la aceptación queda comprobada en Verify' }
   if (!mechanical) {
     phase('QA')
-    qa = await run(
-      `${asRole(cast.qa)}${lite
+    qa = await run(onlyDocument
+      ? `${asRole(cast.qa)}${task.id} no tiene superficie ejecutable: comprobá que el documento existe y cubre ` +
+        `cada elemento que la aceptación enumera, y en evidence decí cuáles encontraste y dónde. ` +
+        `Aceptación: ${checkable}.`
+      : `${asRole(cast.qa)}${lite
         ? 'Hacé la comprobación de aceptación real más barata'
         : 'Ejercitá el comportamiento real que ve quien lo usa'} para ` +
       `${task.id}. Las pruebas unitarias solas no son QA. Levantá el mínimo runtime necesario y bajalo ` +
-      `después. Aceptación: ${task.acceptance}.`,
+      `después. Aceptación: ${checkable}.`,
       { schema: QA, label: 'qa' },
     )
     if (!qa) return stop('agent-unavailable', 'QA no devolvió resultado')
@@ -1169,7 +1205,14 @@ while (rounds++ < MAX_TASKS) {
     `"node tools/ops.js release ${P} ${task.id}". En decisions no nombres una fase ni un cargo ` +
     `que no figure en estos hechos. Hechos: lane=${planning.lane || 'sin clasificar'}; ` +
     `review=${reviewFact}; fases=${ran.join(' → ')}; build=${build.summary}; ` +
-    `verify=${JSON.stringify(verified.commands)}; qa=${qa.evidence}; commit=${commit.hash || commit.reason}.`,
+    `verify=${JSON.stringify(verified.commands)}; cubiertos=${JSON.stringify(covered)}; ` +
+    (noSurface.length ? `sin-superficie=${JSON.stringify(noSurface.map(({ criterion, reason }) => ({
+      criterion, reason: reason || 'no se ejecuta' })))}; ` : '') +
+    (outOfVerify.length ? `fuera-de-verify=${JSON.stringify(outOfVerify)}; ` : '') +
+    `qa=${qa.evidence}; commit=${commit.hash || commit.reason}. En tests rastreá cada criterio con la ` +
+    `prueba que cubiertos le asigna` +
+    (noSurface.length ? ', y los de sin-superficie con tests: n/a — <razón>' : '') +
+    (outOfVerify.length ? '; cada condición de fuera-de-verify queda cumplida en tests, qa o commit' : '') + '.',
     { label: 'done' },
   )
   completed.push(task.id)

package/engine/agents/learning-seal.js

@@ -14,6 +14,8 @@ const {
   isoDate, proposalFiles, proposalState, assertWritable, lastOfPeriod, undecided, SIGNED,
 } = require('./learning-files')
 const { section } = require('../planning/parser')
+const ownership = require('../core/ownership')
+const changelog = require('../core/changelog')
 // La misma identidad con la que se reclama una tarea: quién es la persona, no qué runner corre.
 const { owner } = require('../planning/claims')
 
@@ -28,7 +30,7 @@ const UNSEALED = /^-[ \t]*Estado:[ \t]*(?:pendiente|aprobada)[ \t]*$/mi
 // aprobada con responsable — y «aprobada y aplicada» cumple eso—, así que volver a correrlo sobre una
 // propuesta ya aplicada la aplicaba de nuevo. Como los cambios son aditivos por diseño, el resultado
 // no es un error visible sino un contrato con cada viñeta y cada fuente duplicadas.
-function seal(root, agent, period = '', kind = 'agent') {
+function seal(root, agent, period = '', kind = 'agent', { note = true } = {}) {
   const file = proposalFile(root, agent, period, kind)
   const dir = path.dirname(file)
   const text = fs.readFileSync(file, 'utf8')
@@ -66,9 +68,26 @@ function seal(root, agent, period = '', kind = 'agent') {
   // así que el registro que la plantilla promete no existía nunca. Se escribe acá porque es determinista:
   // la fecha, el documento, quién aprobó y qué dice que cambia, todo sale de lo que se acaba de sellar.
   if (kind === 'flow') appendHistory(path.dirname(path.dirname(dir)), file, responsible.trim(), change)
+  // Sólo en el toolkit: ahí el cargo es del catálogo que se publica, y su cambio tiene que viajar en una
+  // versión. En una empresa el cargo es suyo y no hay CHANGELOG de Cauce que escribir. `note: false` es
+  // el mes revisado sin cambios, que se sella igual y no le cambia nada a quien actualiza.
+  if (kind === 'agent' && note && ownership.mode(root) === 'toolkit') {
+    const noted = changelog.noteAgentChange(root, {
+      agent, proposal: path.basename(file), summary: summarize(change), today: isoDate(new Date()),
+    })
+    return { file, already: false, noted }
+  }
   return { file, already: false }
 }
 
+// La primera idea de «Cambio propuesto», en una línea: el documento entero está en el cargo, y el
+// CHANGELOG lo lee quien actualiza antes de decidir, no quien aplica.
+function summarize(change, limit = 240) {
+  const first = change.split(/\n\s*\n/)[0].replace(/^\s*(?:\d+\.|[-*])\s+/, '').replace(/\s+/g, ' ').trim()
+  if (first.length <= limit) return first.replace(/[.:;]$/, '')
+  return `${first.slice(0, first.lastIndexOf(' ', limit)).replace(/[.,:;]$/, '')}…`
+}
+
 // Archivar es el tercer destino de una propuesta, y hasta ahora no existía: aplicarla, dejarla
 // esperando, o **mirarla y decidir que no cambia nada**. Ese tercero se venía haciendo mergeando el PR
 // sin firmar, que deja el documento en `proposed` para siempre — indistinguible de una que espera

package/engine/automation/index.js

@@ -25,6 +25,7 @@ const {
 // Qué le falta a la superficie de automatización, que no comparte ayudantes con los tres verbos que
 // escriben. Se reexporta para que sus consumidores sigan pidiéndoselo a este módulo.
 const { check } = require('./check')
+const { registrationProblems } = require('./registration')
 
 // Ejecuta el puente del runner tal como él lo invoca, y desde otra carpeta. Instalado no es lo mismo que
 // operativo: un bridge que el runner no puede lanzar —porque su ruta es relativa y el cwd es otro, o
@@ -48,7 +49,12 @@ function probeBridge(paths, runner) {
   const launchDirs = [paths.install, path.dirname(script)]
   for (const event of hookEvents) {
     for (const cwd of launchDirs) {
-      const payload = JSON.stringify({ toolCall: { args: { CommandLine: 'ls', Cwd: paths.install } } })
+      // Una llamada inocua para el evento que la juzga, y ninguna para los demás: un `pre-files` con un
+      // comando no describe ningún archivo, y el puente niega lo que no sabe describir (caso 200). La
+      // entrada vacía es la forma legítima de no describir nada, y ejercita igual el arranque y la raíz.
+      const payload = JSON.stringify(event === 'pre-shell'
+        ? { toolCall: { args: { CommandLine: 'ls', Cwd: paths.install } } }
+        : {})
       const result = spawnSync(process.execPath, [script, event], { cwd, input: payload, encoding: 'utf8' })
       let response = {}
       try { response = JSON.parse((result.stdout || '').trim()) } catch { response = {} }
@@ -68,7 +74,9 @@ function probeBridge(paths, runner) {
   return problems
 }
 
-function doctor(root, name, output = console) {
+// `afterInstall` es la llamada con la que cierra `install`: ahí una copia registrada vieja es el paso que sigue
+// —registrar lo que se acaba de instalar—, no una instalación rota, así que se avisa en vez de fallar.
+function doctor(root, name, output = console, { afterInstall = false } = {}) {
   const runner = runnerManifest(root, name)
   const paths = runnerPaths(root, name, runner)
   const errors = []
@@ -151,6 +159,7 @@ function doctor(root, name, output = console) {
   }
   // Un puente que no responde niega cada llamada del runner: es error, no advertencia.
   for (const problem of probeBridge(paths, runner)) errors.push(problem)
+  for (const problem of registrationProblems(paths, runner)) (afterInstall ? warnings : errors).push(problem)
 
   const executable = spawnSync(
     'sh',

package/engine/automation/registration.js

@@ -0,0 +1,89 @@
+'use strict'
+
+// La copia que el runner ejecuta, cuando no es la del workspace. `agy` corre la que registra
+// `agy plugin install`, una por usuario y no por proyecto, así que el plugin del workspace puede estar
+// perfecto mientras el runner ejecuta el de otro proyecto, de otra versión o roto. `doctor` sondeaba sólo
+// el del workspace y decía «operativo» con cada llamada del runner fallando (caso 201).
+//
+// El runner declara dónde vive esa copia —`activation.registered` en su manifiesto—, y sin esa
+// declaración esto no dice nada: no hay copia aparte que mirar.
+
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const { spawnSync } = require('node:child_process')
+
+function registeredCopy(runner) {
+  const declared = runner.activation && runner.activation.registered
+  return declared ? declared.replace(/^~(?=\/|$)/, os.homedir()) : ''
+}
+
+// Los archivos del plugin, relativos a su carpeta: los que el adaptador entrega bajo ella, más su
+// configuración de hooks.
+function pluginFiles(paths, runner, pluginDir) {
+  const targets = [...(runner.artifacts || []).map((item) => path.resolve(paths.install, item.target)),
+    paths.configTarget]
+  return [...new Set(targets)]
+    .filter((file) => file.startsWith(`${pluginDir}${path.sep}`))
+    .map((file) => path.relative(pluginDir, file))
+}
+
+// Lanza cada comando de la configuración registrada como lo lanza el runner: el texto literal, desde la
+// carpeta del plugin. Así se ve el wiring que no resuelve, que ejecutando el puente directo no aparece.
+// Con tope: la copia registrada puede ser vieja o estar rota, y una que no contesta colgaba a `doctor`. Diez
+// segundos sobran para una copia sana —arranca y contesta en menos de uno— y con una que no contesta ya
+// alcanza para el diagnóstico, así que el sondeo corta ahí en vez de esperar el tope una vez por evento.
+const LAUNCH_LIMIT_MS = 10000
+
+function launch(dir, event, command) {
+  const payload = event === 'pre-shell' ? { toolCall: { args: { CommandLine: 'ls' } } } : {}
+  const input = JSON.stringify(payload)
+  const result = spawnSync('sh', ['-c', command],
+    { cwd: dir, input, encoding: 'utf8', timeout: LAUNCH_LIMIT_MS, killSignal: 'SIGKILL' })
+  if (result.error && result.error.code === 'ETIMEDOUT') return `no respondió en ${LAUNCH_LIMIT_MS / 1000} s`
+  let response = {}
+  try { response = JSON.parse((result.stdout || '').trim()) } catch { response = {} }
+  const healthy = event === 'stop' ? 'stop' : 'allow'
+  if (response.decision === healthy && !response.reason) return ''
+  const stderr = (result.stderr || '').split('\n').find((line) => /Error|error/.test(line)) || ''
+  return response.reason || (response.decision ? `respondió ${response.decision}` : stderr.trim() || 'sin respuesta')
+}
+
+// Qué impide que la copia registrada sea esta instalación funcionando. Vacío si el runner no declara una
+// copia aparte o si todavía no hay ninguna registrada —eso lo dice `activated`—.
+function registrationProblems(paths, runner) {
+  const dir = registeredCopy(runner)
+  if (!dir || !fs.existsSync(dir)) return []
+  const bridge = (runner.artifacts || []).find((item) => item.target.endsWith('hook.js'))
+  if (!bridge) return []
+  const pluginDir = path.dirname(path.resolve(paths.install, bridge.target))
+  const differ = pluginFiles(paths, runner, pluginDir).filter((file) => {
+    const ours = path.join(pluginDir, file)
+    const theirs = path.join(dir, file)
+    if (!fs.existsSync(ours)) return false
+    return !fs.existsSync(theirs) || !fs.readFileSync(ours).equals(fs.readFileSync(theirs))
+  })
+  const problems = []
+  if (differ.length) {
+    const shown = differ.length > 5 ? [...differ.slice(0, 5), `y ${differ.length - 5} más`] : differ
+    problems.push(`${runner.command} ejecuta ${dir}, que no es esta instalación: difiere(n) ${shown.join(', ')}. `
+      + `Corré desde ${paths.install}: ${runner.activation.hint}`)
+  }
+  let config = {}
+  try { config = JSON.parse(fs.readFileSync(path.join(dir, path.basename(paths.configTarget)), 'utf8')) } catch {
+    return problems
+  }
+  const commands = [...new Set(JSON.stringify(config).match(/"command":"([^"]*hook\.js [a-z-]+)"/g) || [])]
+    .map((entry) => entry.slice(11, -1))
+  for (const command of commands) {
+    const event = command.split(' ').pop()
+    const failure = launch(dir, event, command)
+    if (failure) {
+      problems.push(`la copia registrada no responde a ${event} lanzada como la lanza ${runner.command}: ${failure}`)
+    }
+    if (/^no respondió/.test(failure)) break
+  }
+  return problems
+}
+
+module.exports = { registrationProblems }

package/engine/cli/args.js

@@ -36,7 +36,7 @@ const FLAGS = {
   integration: ['--fixture'],
   secrets: [],
   automation: ['--force'],
-  learn: ['--flow', '--proposal', '--applied', '--archived', '--period', '--reason'],
+  learn: ['--flow', '--proposal', '--applied', '--unchanged', '--archived', '--period', '--reason'],
   evaluate: ['--cases', '--json', '--bench', '--force', '--record', '--flow'],
   flow: ['--json'],
 }

package/engine/cli/catalog.js

@@ -104,11 +104,17 @@ function learn(agent, cli) {
         : `✓ ${relative} queda archivada: ${porque}`)
     }
     if (cli.has('--applied')) {
-      const result = L.seal(opsRoot(), agent, cli.value('--period'), kind)
+      const result = L.seal(opsRoot(), agent, cli.value('--period'), kind, { note: !cli.has('--unchanged') })
       const relative = path.relative(opsRoot(), result.file)
-      return console.log(result.already
+      console.log(result.already
         ? `= ${relative} ya estaba aplicada`
         : `✓ ${relative} queda aplicada: no se vuelve a aplicar`)
+      if (result.noted) {
+        console.log(result.noted.already
+          ? `= CHANGELOG.md ya nombraba este cambio en ${result.noted.version}`
+          : `✓ CHANGELOG.md: el cambio sale en ${result.noted.version}`)
+      }
+      return
     }
     // Un recorrido no tiene informe de investigación: su propuesta se compone de los veredictos de sus
     // propias corridas y nunca lee `learning/reports/`. La forma desnuda —la que para un cargo abre su

package/engine/cli/ops.js

@@ -180,7 +180,7 @@ function usage() {
   ops automation doctor <ops-root> claude|codex|gemini|antigravity
   ops automation install <ops-root> claude|codex|gemini|antigravity
   ops automation uninstall <ops-root> claude|codex|gemini|antigravity
-  ops learn <agent|flow> [--flow] [--proposal [--period <AAAA-MM>]] [--applied [--period <AAAA-MM>]]
+  ops learn <agent|flow> [--flow] [--proposal [--period <AAAA-MM>]] [--applied [--period <AAAA-MM>] [--unchanged]]
   ops learn <agent|flow> [--flow] --archived [--period <AAAA-MM>] [--reason <motivo>]
   ops evaluate <agent|flow> [--flow] [--cases [--json]] [--bench [caso]] [--record [AAAA-MM-DD]]
   ops agents list [ops-root] [--own|--system] [--json]

package/engine/cli/validate.js

@@ -26,6 +26,7 @@ const O = require('../core/ownership')
 const TR = require('../core/trails')
 const OB = require('../core/onboarding')
 const C = require('../config/validate')
+const MG = require('../core/migrations')
 const CP = require('../config/paths')
 const AG = require('../agents/catalog')
 const RL = require('../automation/rules')
@@ -62,6 +63,7 @@ function check(dir, cli) {
       if (!raw.includes('{{')) {
         errors.push(...C.validateOpsConfig(config))
         warnings.push(...C.configWarnings(config))
+        warnings.push(...MG.coverageWarnings(R.reposFor(path.dirname(configPath), '.'), config))
         if (Array.isArray(config.workspaceRoots)) {
           for (const workspace of config.workspaceRoots) {
             if (workspace && workspace.name && workspace.path
@@ -108,6 +110,7 @@ function check(dir, cli) {
   // corre en los cuatro carriles, incluidos los que saltean Ready (caso 140).
   warnings.push(...PC.unverifiableAcceptance(milestones))
   warnings.push(...R.coverageWarnings(path.resolve(root, '..'), done))
+  errors.push(...PC.surfaceWithoutTests(done.entries, R.commitFiles(path.resolve(root, '..')), new Set(adopted)))
   // Sin `RECURRING.md` no dice una palabra: una instancia que actualiza y no declara trabajo recurrente
   // no tiene por qué enterarse de que el contrato existe. Vencida avisa y no frena — lo que frena vive
   // en `HUMAN_ACTIONS.md`, y un aviso que salta siempre se termina apagando.

package/engine/cli/wiring.js

@@ -283,7 +283,7 @@ function automation(action, rootArg, runnerName, cli) {
     if (!runner.capabilities.nativeHooks) {
       console.log(`  ${runnerName} no expone hooks nativos; aplica guards como prechecks.`)
     }
-    const result = A.doctor(root, runnerName)
+    const result = A.doctor(root, runnerName, console, { afterInstall: true })
     if (result.errors.length) fail(`${runnerName}: instalación incompleta`, REFUSED)
     console.log(`✓ ${runnerName}: adaptador operativo (${result.warnings.length} advertencia(s))`)
     return

package/engine/config/validate.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { PATH_SHAPE, EXTENSION_SHAPE } = require('../core/migrations')
+
 const MODES = ['embedded', 'sidecar', 'toolkit']
 
 // Campos que existieron y se retiraron. Se nombran en vez de caer en «propiedad desconocida» porque
@@ -69,18 +71,35 @@ function validateMigrations(migrations, errors) {
     return
   }
   for (const key of Object.keys(migrations)) {
-    if (key !== 'extensions') errors.push(`ops.config.json: migrations.${key} no está permitido`)
-  }
-  if (!('extensions' in migrations)) return
-  const declaradas = migrations.extensions
-  if (!Array.isArray(declaradas) || !declaradas.length) {
-    errors.push('ops.config.json: migrations.extensions debe listar al menos una extensión, o no estar')
-    return
+    if (!['extensions', 'paths'].includes(key)) errors.push(`ops.config.json: migrations.${key} no está permitido`)
+  }
+  if ('extensions' in migrations) {
+    const declared = migrations.extensions
+    if (!Array.isArray(declared) || !declared.length) {
+      errors.push('ops.config.json: migrations.extensions debe listar al menos una extensión, o no estar')
+    } else {
+      for (const one of declared) {
+        if (typeof one !== 'string' || !EXTENSION_SHAPE.test(one)) {
+          errors.push(`ops.config.json: migrations.extensions "${one}" debe ser la extensión sin el punto `
+            + 'y en minúscula, como "sql" o "ts"')
+        }
+      }
+    }
   }
-  for (const one of declaradas) {
-    if (typeof one !== 'string' || !/^[a-z0-9]+$/.test(one)) {
-      errors.push(`ops.config.json: migrations.extensions "${one}" debe ser la extensión sin el punto `
-        + 'y en minúscula, como "sql" o "ts"')
+  // Las carpetas, por lo mismo que las extensiones y con una razón más: el guard las busca dentro de la
+  // ruta que recibe, que puede ser relativa, así que una absoluta o una que sale con `..` no nombraría
+  // nada que pudiera encontrar (caso 196).
+  if ('paths' in migrations) {
+    const paths = migrations.paths
+    if (!Array.isArray(paths) || !paths.length) {
+      errors.push('ops.config.json: migrations.paths debe listar al menos una carpeta, o no estar')
+      return
+    }
+    for (const one of paths) {
+      if (typeof one !== 'string' || !PATH_SHAPE.test(one)) {
+        errors.push(`ops.config.json: migrations.paths ${JSON.stringify(one)} debe ser una carpeta relativa, `
+          + 'sin barra al principio ni al final y sin «.» ni «..», como "migrations" o "alembic/versions"')
+      }
     }
   }
 }

package/engine/core/changelog.js

@@ -47,4 +47,63 @@ function read(packageRoot) {
   try { return fs.readFileSync(path.join(packageRoot, 'CHANGELOG.md'), 'utf8') } catch { return '' }
 }
 
-module.exports = { between, compare, entries, read }
+// La línea que `agent-promote` deja al aplicar un cargo, en la versión que todavía no salió. Sin ella el
+// cambio quedaba en `main` sin versión que lo llevara: `release-pr.yml` sólo abre el PR cuando el
+// CHANGELOG declara un número nuevo, y escribirlo era un paso que nadie tenía asignado.
+//
+// Abierta es la entrada más nueva si va por delante de `package.json`; si no, ya salió y se abre la
+// minor siguiente. Minor porque cambia lo que recibe quien hace `upgrade`, que es la regla de este
+// archivo. Varios cargos del mismo mes caen así en una sola versión.
+function noteAgentChange(root, { agent, proposal, summary, today }) {
+  const file = path.join(root, 'CHANGELOG.md')
+  const lines = fs.readFileSync(file, 'utf8').split('\n')
+  const released = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version
+  const first = lines.findIndex((line) => /^##\s*\[\d/.test(line))
+  if (first < 0) throw new Error('CHANGELOG.md no tiene ninguna entrada con versión.')
+  const bullet = wrap(`- **\`${agent}\`**: ${summary} (propuesta \`${proposal}\`).`)
+  const top = lines[first].match(HEADING)[1]
+  if (compare(top, released) <= 0) {
+    const [major, minor] = released.split('.').map(Number)
+    const version = `${major}.${minor + 1}.0`
+    lines.splice(first, 0, `## [${version}] - ${today}`, '', '### Cargos', '', ...bullet, '')
+    fs.writeFileSync(file, lines.join('\n'))
+    return { version, already: false }
+  }
+  let end = lines.findIndex((line, index) => index > first && HEADING.test(line))
+  if (end < 0) end = lines.length
+  // Una propuesta ya anotada no se anota dos veces: `seal` puede volver a correr sobre un cuerpo sin sellar.
+  // Con los espacios normalizados porque la viñeta se envuelve, y el corte puede caer entre las dos mitades.
+  const entry = lines.slice(first, end).join(' ').replace(/\s+/g, ' ')
+  if (entry.includes(`- **\`${agent}\`**`) && entry.includes(`(propuesta \`${proposal}\`)`)) {
+    return { version: top, already: true }
+  }
+  const section = lines.findIndex((line, index) => index > first && index < end && /^###\s+Cargos\s*$/.test(line))
+  let at = end
+  if (section >= 0) {
+    at = lines.findIndex((line, index) => index > section && index < end && /^#{2,3}\s/.test(line))
+    if (at < 0) at = end
+  }
+  while (at > first + 1 && lines[at - 1].trim() === '') at--
+  lines.splice(at, 0, ...(section >= 0 ? bullet : ['', '### Cargos', '', ...bullet]))
+  fs.writeFileSync(file, lines.join('\n'))
+  return { version: top, already: false }
+}
+
+// Al ancho del resto del archivo, con la sangría de continuación que ya usan sus viñetas.
+function wrap(text, width = 110) {
+  const out = []
+  let line = ''
+  for (const word of text.split(/\s+/)) {
+    const next = line ? `${line} ${word}` : word
+    if (next.length > width && line) {
+      out.push(line)
+      line = `  ${word}`
+    } else {
+      line = next
+    }
+  }
+  if (line) out.push(line)
+  return out
+}
+
+module.exports = { between, compare, entries, read, noteAgentChange }