@ingeniomaps/cauce 0.69.0 → 0.71.0

package/automatization/runners/codex/AGENTS.md

@@ -15,7 +15,7 @@ Los cinco recorridos llegan como skills en `.agents/skills/` y se invocan con `$
 acá —son referencia, no un runtime compatible—, así que cada recorrido se ejecuta fase por fase
 siguiendo el protocolo.
 
-`{{OPS_DIR}}planning/WIP.md` es el mutex: una sola tarea activa. `{{OPS_DIR}}planning/AWAITING_REVIEW.md`
+`{{OPS_DIR}}planning/wip/<runner>.md` es el mutex: una sola tarea activa. `{{OPS_DIR}}planning/AWAITING_REVIEW.md`
 bloquea una corrida nueva hasta que un humano revise. Nada se promueve desde `INBOX.md` sin aprobación.
 
 Antes de cerrar, corré `node {{OPS_DIR}}tools/ops.js check {{OPS_DIR}}planning`.

package/automatization/runners/gemini/GEMINI.md

@@ -8,7 +8,7 @@
 @{{OPS_DIR}}planning/rules/system/conduct.md
 
 `{{OPS_DIR}}planning/PROTOCOL.md` es la fuente de verdad. Ejecuta `/cauce:autobuild` fase por fase; los
-workflows JS de Claude son referencia, no un runtime compatible. `{{OPS_DIR}}planning/WIP.md` es el mutex
+workflows JS de Claude son referencia, no un runtime compatible. `{{OPS_DIR}}planning/wip/<runner>.md` es el mutex
 y `{{OPS_DIR}}planning/AWAITING_REVIEW.md` bloquea una corrida nueva.
 
 Los hooks de `.gemini/settings.json` son obligatorios y bloquean por su cuenta. **Requieren que la

package/automatization/shared/skills/autobuild/SKILL.md

@@ -3,7 +3,7 @@ name: autobuild
 description: Ejecuta el siguiente hito aprobado siguiendo el protocolo Cauce.
 ---
 
-Lee completos `{{OPS_DIR}}AGENTS.md`, `{{OPS_DIR}}planning/PROTOCOL.md` y `{{OPS_DIR}}planning/WIP.md`. Si existe
+Lee completos `{{OPS_DIR}}AGENTS.md`, `{{OPS_DIR}}planning/PROTOCOL.md` y `{{OPS_DIR}}planning/wip/`. Si existe
 `{{OPS_DIR}}planning/AWAITING_REVIEW.md`, detente y explica la acción humana pendiente. Toma solamente la primera tarea
 aprobada, persiste el estado en WIP y ejecuta Build, Review, Verify y QA en orden. Usa los comandos reales del
 servicio, registra evidencia verificable en DONE y detente en el checkpoint entre hitos. No hagas push ni

package/automatization/workflows/autobuild.js

@@ -21,7 +21,7 @@ export const meta = {
     { title: 'Verify', detail: 'Los gates del servicio y la aceptación que ninguna prueba codifica' },
     { title: 'QA', detail: 'El comportamiento ejercitado como lo ve quien lo usa' },
     { title: 'Commit', detail: 'Conventional Commits, uno por naturaleza del diff, sin push' },
-    { title: 'Done', detail: 'Cierre atómico en DONE con el WIP en IDLE' },
+    { title: 'Done', detail: 'Cierre atómico: evidencia escrita, cola y plan limpios, reserva suelta' },
     { title: 'Closing', detail: 'Check de planning y checkpoint humano del hito' },
   ],
 }
@@ -31,8 +31,8 @@ const CONFIG = `${ROOT}/ops.config.json`
 const P = `${ROOT}/planning`
 const ORG = `${ROOT}/organization`
 const BACKLOG = `${P}/BACKLOG.md`
-const DONE = `${P}/DONE.md`
-const WIP = `${P}/WIP.md`
+// Una tarea cerrada escribe su propio archivo, así que dos corridas en paralelo no comparten ninguno.
+const doneFile = (slug) => `${P}/done/${slug}.md`
 const HUMAN = `${P}/HUMAN_ACTIONS.md`
 const GATE = `${P}/AWAITING_REVIEW.md`
 const ROADMAP = `${P}/roadmap`
@@ -40,8 +40,12 @@ const ROADMAP = `${P}/roadmap`
 // Estado de planning tal como lo emite `ops context --json`; ningún modelo parsea BACKLOG ni WIP.
 const CONTEXT = {
   type: 'object', additionalProperties: false,
-  required: ['blocked', 'hasTask', 'wipActive', 'queued', 'cast'],
+  required: ['blocked', 'hasTask', 'wipActive', 'queued', 'cast', 'readOk'],
   properties: {
+    // Si el comando salió con error no hay estado que reportar, y `hasTask: false, queued: 0` es
+    // exactamente lo que un modelo completa cuando no tiene qué poner. Sin este campo esa invención se
+    // lee igual que una cola terminada, y Pick la toma como permiso para promover.
+    readOk: { type: 'boolean' },
     blocked: { type: 'string' }, hasTask: { type: 'boolean' }, wipActive: { type: 'boolean' },
     queued: { type: 'integer' }, slug: { type: 'string' }, hito: { type: 'string' },
     service: { type: 'string' }, acceptance: { type: 'string' }, epic: { type: 'string' },
@@ -58,11 +62,20 @@ const CONTEXT = {
       properties: { build: { type: 'string' }, review: { type: 'array', items: { type: 'string' } } },
     },
     blockedTasks: { type: 'array', items: { type: 'string' } },
+    // Si la tarea que `context` devolvió ya está reservada a nombre de este runner. Libre no significa
+    // que sea nuestra: significa que todavía la puede tomar cualquiera, y dos corridas en paralelo la
+    // reciben las dos.
+    claimed: { type: 'boolean' },
+    // La fecha de hoy según el motor. Este recorrido no tiene reloj propio a propósito.
+    today: { type: 'string' },
+    // Dónde va el plan de este runner. El nombre sale de su id y el recorrido no lo deriva: lo
+    // pregunta, igual que la fecha.
+    wipFile: { type: 'string' },
   },
 }
-const EXPANSION = {
-  type: 'object', additionalProperties: false, required: ['expanded'],
-  properties: { expanded: { type: 'boolean' }, hito: { type: 'string' }, reason: { type: 'string' } },
+const CLAIM = {
+  type: 'object', additionalProperties: false, required: ['claimed'],
+  properties: { claimed: { type: 'boolean' }, details: { type: 'string' } },
 }
 const READY = {
   type: 'object', additionalProperties: false, required: ['ready', 'needsHuman'],
@@ -216,8 +229,16 @@ const CLASSIFICATION = {
 
 const CONTRACT = {
   type: 'object', additionalProperties: false,
-  required: ['project', 'workspaceRoots', 'maxTaskHours', 'commitPerTask', 'humanCheckpoint', 'contracts'],
+  required: ['project', 'workspaceRoots', 'maxTaskHours', 'commitPerTask', 'humanCheckpoint', 'contracts',
+    'rootOk'],
   properties: {
+    // `ROOT` viaja escrito en el workflow y es relativo al cwd de los agentes: si la sesión abrió en otra
+    // carpeta, todas las rutas resuelven a `<raíz>/<raíz>/…` y ninguna existe. Nada lo comprobaba, y el
+    // recorrido gastaba Triage entero sobre archivos ausentes antes de parar más abajo por otra causa,
+    // nombrando el planning en vez de la raíz de la que ese planning cuelga.
+    //
+    // Se pregunta acá porque acá ya se leen los cuatro archivos: cuesta un campo y ningún agente más.
+    rootOk: { type: 'boolean' },
     project: { type: 'string' }, workspaceRoots: { type: 'array', minItems: 1, items: { type: 'string' } },
     // La puerta que el proyecto declara, si la declara. Viaja con la raíz porque es de la base de código
     // y no del runner: un monorepo tiene una por servicio, y uno solo tiene una sola.
@@ -276,7 +297,9 @@ phase('Triage')
 // subagente como «Límites del proyecto» eran sólo los genéricos del toolkit.
 const contract = await agent(
   `${BASE}\n\nLeé ${ROOT}/AGENTS.md, ${ORG}/workspace.md, ${CONFIG} y ${P}/PROTOCOL.md una sola vez y no ` +
-  `leas nada más. Reportá los ` +
+  `leas nada más. Poné rootOk en true sólo si los cuatro existieron y los pudiste leer; si alguno no ` +
+  `estaba, rootOk en false y el resto en sus valores vacíos, sin deducirlos de otra fuente. ` +
+  `Reportá los ` +
   `valores de configuración textualmente: project, workspaceRoots como entradas "nombre → ruta", ` +
   `runner.maxTaskHours, runner.commitPerTask y runner.humanCheckpointBetweenMilestones como humanCheckpoint. ` +
   `En gates poné una entrada "ruta → comando" por cada workspaceRoot que declare \`verify\`, y ninguna por ` +
@@ -288,6 +311,12 @@ const contract = await agent(
   { schema: CONTRACT, label: 'contract-digest' },
 )
 if (!contract) return stop('contract-unavailable', `no se pudo leer ${CONFIG} ni ${P}/PROTOCOL.md`)
+// Falla acá y nombrando la raíz, que es lo que hace falta para arreglarlo: parar más abajo mandaba a
+// revisar el planning, y el planning está bien — lo que no existe es la carpeta de la que cuelga.
+if (!contract.rootOk) {
+  return stop('root-unreadable', `${ROOT} no se pudo leer entero. Es una ruta relativa a la carpeta `
+    + `donde se abre la herramienta: comprobá desde dónde estás corriendo el recorrido.`)
+}
 
 const bounds = contract.boundaries || []
 const limits = bounds.length ? ` Límites del proyecto: ${bounds.join('; ')}.` : ''
@@ -311,14 +340,22 @@ const write = (prompt, options = {}) => agent(`${LEDGER}\n\n${prompt}`, options)
 // WIP y HUMAN_ACTIONS nunca entran al contexto de un modelo, y su tamaño deja de costar tokens.
 const readContext = () => read(
   `Corré "node tools/ops.js context ${P} --json" desde ${ROOT} y reportá sólo lo que imprimió. Derivá hasTask ` +
-  `de si task es null, wipActive de si wip es null y lane de task.tier; copiá slug, hito, service, acceptance, ` +
+  `de si task es null, wipActive de si wip es null, claimed del campo claimed, today y wipFile de sus ` +
+  `campos, y lane ` +
+  `de task.tier; copiá slug, ` +
+  `hito, service, acceptance, ` +
   `epic y cast de task, y epicContext de epic.context —vacío si no hay épica—. El comando es la fuente de ` +
-  `verdad: no abras archivos de planning para completarlo.`,
+  `verdad: no abras archivos de planning para completarlo. Poné readOk en true sólo si el comando salió ` +
+  `con código 0 y devolvió JSON; si falló, readOk en false y el resto en sus valores vacíos, sin ` +
+  `deducir el estado de ninguna otra fuente.`,
   { schema: CONTEXT, label: 'planning-context' },
 )
 
 let planning = await readContext()
 if (!planning) return stop('context-unavailable', `no se pudo leer el estado de ${P}`)
+// Que el agente conteste no significa que haya leído: el schema se completa igual con ceros. Parar acá
+// cuesta una corrida; seguir sobre una lectura fallida escribe en el BACKLOG, y eso no se revierte solo.
+if (!planning.readOk) return stop('context-unavailable', `${P} no se pudo leer; revisá la ruta y el cwd`)
 if (planning.blocked) return stop('awaiting-human-review', `${GATE} tiene un checkpoint humano sin resolver`)
 
 let currentMilestone = planning.wipActive ? planning.hito : ''
@@ -334,23 +371,38 @@ const classified = new Set()
 
 while (rounds++ < MAX_TASKS) {
   phase('Pick')
-  if (!planning.hasTask && !planning.queued) {
-    const expansion = await write(
-      `Leé ${ROADMAP}. Expandí sólo la próxima épica abierta y aprobada en un hito nuevo de ${BACKLOG}, ` +
-      `conservando el slug de cada historia, sus referencias a criterios y su servicio. Nunca promuevas ` +
-      `${P}/INBOX.md. Reportá si escribiste algo.`,
-      { schema: EXPANSION },
-    )
-    if (!expansion) return stop('agent-unavailable', 'Pick no devolvió resultado')
-    if (!expansion.expanded) break
-    planning = await readContext()
-    if (!planning) return stop('context-unavailable', `no se pudo releer el estado de ${P}`)
-  }
+  // Sin tarea y con la cola vacía, la corrida termina. **No expande la próxima épica**, y eso no es una
+  // limitación sino la regla: el roadmap llama `open` a «candidata editable que aún no fue promovida al
+  // backlog», así que pegarla en la cola es promoverla — y BR-OPS-002 deja una propuesta fuera de la cola
+  // hasta que la apruebe una persona. El prompt que hacía esto pedía «la próxima épica abierta y
+  // aprobada», y «aprobada» no correspondía a ningún dato: una épica declara `epic`, `title`, `status` y
+  // `service`, y ninguno registra una aprobación.
+  //
+  // `context` nombra la que sigue, igual que nombra una recurrencia vencida y por el mismo motivo: la
+  // máquina calcula y la persona encola.
   if (!planning.hasTask || (currentMilestone && planning.hito !== currentMilestone)) break
   const task = {
     id: planning.slug, hito: planning.hito, service: planning.service,
     acceptance: planning.acceptance, epic: planning.epic, epicContext: planning.epicContext || '',
   }
+  // Reservar antes de construir, y antes de fijar el hito de la corrida. Sin esto dos corridas en
+  // paralelo trabajan la misma tarea: `context` sólo puede saltear lo que alguien ya reclamó, y el
+  // primero en preguntar todavía no reclamó nada. La ventana entre preguntar y reservar existe igual, y
+  // 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(
+      `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) {
+      planning = await readContext()
+      if (!planning) return stop('context-unavailable', `no se pudo releer el estado de ${P}`)
+      continue
+    }
+  }
   currentMilestone = task.hito
 
   // Ver la tarea y, si no está clasificada, clasificarla antes de ejecutarla. Se hace una vez por
@@ -535,7 +587,7 @@ while (rounds++ < MAX_TASKS) {
     `dio; recién después implementá. Un test que pasa antes de que exista el código no asercia lo que dice ` +
     `aserciar: endurecelo y volvé a correr hasta verlo fallar. Corré las pruebas que necesites para ver ese ` +
     `rojo y ese verde, y nada más: los gates completos, el QA, el commit y el cierre son fases posteriores, ` +
-    `así que no toques ${DONE} ni ${BACKLOG} ni el status del WIP. Lo que el plan no previó va en discovered y ` +
+    `así que no toques ${P}/done/ ni ${BACKLOG} ni el status del WIP. Lo que el plan no previó va en discovered y ` +
     `no en el código a secas: kind=edge si esta tarea lo puede fijar —y entonces entra con su prueba, que ` +
     `nombrás en test y anotás en redFirst—, kind=open si lo notaste y no impide entregar la aceptación: se ` +
     `registra para que lo decida quien corresponde y el recorrido sigue. Si de verdad no podés entregar sin ` +
@@ -693,9 +745,11 @@ while (rounds++ < MAX_TASKS) {
 
   phase('Done')
   await write(
-    `Cerrá ${task.id} de forma atómica: agregala bajo su hito en ${DONE} con evidencia de acept, done, qa, ` +
-    `tests y commit; sacala junto con sus notas indentadas de ${BACKLOG}; cerrá su épica sólo si no queda ` +
-    `ninguna tarea etiquetada; y dejá ${WIP} en status IDLE. En decisions no nombres una fase ni un cargo ` +
+    `Cerrá ${task.id} de forma atómica: escribí ${doneFile(task.id)} con su evidencia —acept, ` +
+    `fecha: ${planning.today}, done, qa, tests y commit, en el formato de entrada que trae este preámbulo—; ` +
+    `sacala junto con sus notas indentadas de ${BACKLOG}; cerrá su épica sólo si no queda ` +
+    `ninguna tarea etiquetada; dejá ${P}/${planning.wipFile} en status IDLE; y soltá la reserva corriendo ` +
+    `"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}.`,

package/engine/agents/learning-seal.js

@@ -12,6 +12,8 @@ const path = require('node:path')
 const { atomicWrite } = require('../core/files')
 const { isoDate, proposalFiles, proposalState, assertWritable, lastOfPeriod } = require('./learning-files')
 const { section } = require('../planning/parser')
+// La misma identidad con la que se reclama una tarea: quién es la persona, no qué runner corre.
+const { owner } = require('../planning/claims')
 
 // El cuerpo sin sellar, en los dos estados que produce el ciclo: «pendiente» lo escribe el molde y
 // «aprobada» la firma. Lo lee la guarda de más abajo y lo reemplaza el sello, así que vive una vez.
@@ -102,22 +104,51 @@ function archive(root, agent, period = '', kind = 'agent') {
       + 'Archivar es para lo que se miró y no cambia nada.',
     )
   }
+  // Quién archivó, que es la mitad que faltaba. Sellar saca el responsable del documento —lo escribió la
+  // firma— y archivar no pasa por firma, así que sale de la identidad de quien corre el comando: la misma
+  // que `claim` usa para decir de quién es una tarea. Sin esto la propuesta quedaba en «por definir» y no
+  // había forma de distinguir una decisión de un olvido.
+  const responsible = owner(root) || 'sin identificar'
   atomicWrite(file, text
     .replace(/^status:\s*\S+\s*$/m, 'status: archived')
     .replace(/^-[ \t]*Estado:[ \t]*pendiente[ \t]*$/mi, '- Estado: archivada')
+    .replace(/^-[ \t]*Responsable:[ \t]*por definir[ \t]*$/mi, `- Responsable: ${responsible}`)
     .replace(/^-[ \t]*Fecha:[ \t]*por definir[ \t]*$/mi, `- Fecha: ${isoDate(new Date())}`))
+  // La fila va para los dos tipos, y no sólo para los recorridos como en `seal`: allá los cargos los
+  // registra `agent-promote` al aplicar, y archivar no pasa por ningún workflow que lo haga.
+  // La raíz del cargo, que es `<cargo>/learning/proposals/<archivo>` sin sus tres últimos tramos:
+  // `appendHistory` agrega `learning/` por su cuenta.
+  //
+  // La celda del cambio lleva el criterio y no queda vacía. Es el único que este comando admite —archivar
+  // *es* decidir que no cambia nada— así que decirlo evita que la fila se lea como un registro a medias.
+  // Archivar por otra razón, como posponer, necesitaría un campo que hoy no existe.
+  appendHistory(path.dirname(path.dirname(path.dirname(file))), file, responsible,
+    'Se miró y no cambia nada.', 'archivada')
   return { file, already: false }
 }
 
-// Una fila por propuesta aplicada. El cambio va en una línea: el documento entero está a un enlace, y
-// una tabla que lo repite entero deja de leerse.
-function appendHistory(target, file, responsible, change) {
+// Una fila por propuesta cerrada, cualquiera sea el destino. El cambio va en una línea: el documento
+// entero está a un enlace, y una tabla que lo repite entero deja de leerse.
+//
+// La decisión es un parámetro y no la constante `aplicada` porque la columna de la tabla se llama
+// «Decisión» y hay dos: aplicar y archivar. Archivar no dejaba fila, así que una propuesta mirada y
+// descartada era indistinguible de una que nadie miró — y eso lo pagaban los informes siguientes, que
+// gastaban su recomendación explicando el estado en vez de su profesión.
+const HISTORY_HEADER = '| Fecha | Propuesta | Decisión | Aprobó | Cambio aplicado |\n|---|---|---|---|---|\n'
+
+function appendHistory(target, file, responsible, change, decision = 'aplicada') {
   const history = path.join(target, 'learning', 'HISTORY.md')
   if (!fs.existsSync(history)) return
+  const previous = fs.readFileSync(history, 'utf8')
   const line = change.split('\n').map((one) => one.trim()).filter(Boolean)[0] || ''
-  const row = `| ${isoDate(new Date())} | \`${path.basename(file)}\` | aplicada | ${responsible} `
+  const row = `| ${isoDate(new Date())} | \`${path.basename(file)}\` | ${decision} | ${responsible} `
     + `| ${line.slice(0, 160)} |\n`
-  fs.appendFileSync(history, `${fs.readFileSync(history, 'utf8').endsWith('\n') ? '' : '\n'}${row}`)
+  // Dieciséis de los cincuenta y tres cargos tienen el archivo sin la tabla, sólo con su párrafo de
+  // encabezado, y la fila quedaba pegada ahí: en markdown eso no es una tabla sino texto con barras, y
+  // nadie lo veía porque el archivo se lee dos veces al año. Se agrega la cabecera antes de la primera
+  // fila en vez de exigir que ya esté, que es pedirle a cada cargo que se acuerde.
+  const cabecera = /^\|\s*Fecha\s*\|/m.test(previous) ? '' : `\n${HISTORY_HEADER}`
+  fs.appendFileSync(history, `${previous.endsWith('\n') ? '' : '\n'}${cabecera}${row}`)
 }
 
 module.exports = { seal, archive }

package/engine/agents/learning-sources.js

@@ -90,6 +90,12 @@ function sourceTiers(text) {
   return [...body.matchAll(/tier:\s*([A-Za-z-]+)/g)].map((hit) => hit[1])
 }
 
+// Una entrada escrita en una sola línea: seis cargos del catálogo la escriben así y cuarenta y siete la
+// reparten en varias. Leyendo sólo la segunda forma, esos seis no tenían el chequeo de URL duplicada que
+// hay más abajo, y nada lo decía porque no encontrar duplicados y no mirar se ven igual.
+const FLOW_ENTRY = /^\s*-\s*\{[^}]*\bname:\s*([^,}]+?)\s*,[^}]*\burl:\s*"?([^",}\s]+)/
+const quitar = (value) => value.replace(/^['"]|['"]$/g, '')
+
 // Las fuentes de un cargo, por su URL. La misma URL con dos nombres es una sola fuente contada dos
 // veces: el catálogo llegó a tener la especificación OpenAPI bajo tres —`OpenAPI Specification`,
 // `...latest published` y `...3.2.0`— así que arreglarle el `tier` a un cargo no se lo arreglaba a los
@@ -99,14 +105,52 @@ function sourceUrls(text) {
   const out = []
   let name = ''
   for (const line of body.split('\n')) {
+    const flow = line.match(FLOW_ENTRY)
+    if (flow) { out.push({ name: quitar(flow[1]), url: flow[2].replace(/\/+$/, '') }); continue }
     const declared = line.match(/^\s*-\s*name:\s*(.+?)\s*$/)
-    if (declared) { name = declared[1].replace(/^['"]|['"]$/g, ''); continue }
+    if (declared) { name = quitar(declared[1]); continue }
     const url = line.match(/^\s*url:\s*(\S+)/)
     if (url && name) out.push({ name, url: url[1].replace(/\/+$/, '') })
   }
   return out
 }
 
+// Todo lo que un cargo cita y alguien va a abrir. `sources.yaml` es lo que investiga; `references/` y
+// `SKILL.md` son el método que sigue, y hasta 0.71.0 nadie las miraba: 29 de las 207 URLs de esos
+// documentos no servían, entre ellas dos 404 de páginas que se habían movido.
+//
+// `evaluations/` queda afuera y no por costo: los casos adversariales **inventan** dominios a propósito
+// —veintiuna URLs bajo `.example` y marcas que no existen— y comprobarlas reportaría rotas las que están
+// bien escritas. `learning/reports` y `learning/proposals` también, por lo contrario: son evidencia
+// fechada de que algo dio 403 el día que se consultó, y eso no se arregla.
+const DOC_URL = /https?:\/\/[^\s)>"`\]]+/g
+function documentUrls(dir) {
+  const out = []
+  const seen = new Set()
+  const add = (raw, origin) => {
+    const url = raw.replace(/[.,;:]+$/, '')
+    if (seen.has(url)) return
+    seen.add(url)
+    out.push({ url, origin })
+  }
+  const below = (base, relative) => {
+    let entries = []
+    try { entries = fs.readdirSync(path.join(base, relative), { withFileTypes: true }) } catch { return }
+    for (const entry of entries) {
+      const next = `${relative}/${entry.name}`
+      if (entry.isDirectory()) { below(base, next); continue }
+      if (!entry.name.endsWith('.md')) continue
+      for (const hit of fs.readFileSync(path.join(base, next), 'utf8').match(DOC_URL) || []) add(hit, next)
+    }
+  }
+  below(dir, 'references')
+  const skill = path.join(dir, 'SKILL.md')
+  if (fs.existsSync(skill)) {
+    for (const hit of fs.readFileSync(skill, 'utf8').match(DOC_URL) || []) add(hit, 'SKILL.md')
+  }
+  return out
+}
+
 function evaluate(root, agent) {
   const target = catalog.resolve(root, agent)
   const errors = []
@@ -193,4 +237,4 @@ function evaluate(root, agent) {
   return { errors, warnings, proposals: proposals.length, pending, cases }
 }
 
-module.exports = { SOURCE_TIERS, cadence, evaluate, evaluateTeam }
+module.exports = { SOURCE_TIERS, cadence, documentUrls, evaluate, evaluateTeam, sourceUrls }

package/engine/agents/learning.js

@@ -40,15 +40,21 @@ function prepareReport(root, agent, now = new Date()) {
   // Los sellos de estado de este módulo escriben atómico y esto no, y la diferencia es qué se pierde
   // si la escritura se corta: allá el archivo ya existía y quedaría truncado, acá no había nada. Un
   // documento nuevo a medio escribir se ve; uno viejo a medio pisar se lee como si estuviera entero.
+  // `propone` nace sin contestar y lo completa quien escribe el informe. No se deduce del texto de
+  // «Recomendación»: los veinte informes del 2026-09-07 tenían texto ahí y once no proponían ningún
+  // cambio —explicaban por qué, que es lo correcto—, así que «sección vacía» no distingue nada. Con
+  // el campo, un informe que no cambia ningún contrato se mergea solo en vez de gastar una revisión
+  // humana que no puede decidir nada.
   fs.writeFileSync(file, `---
 agent: ${agent}
 date: ${isoDate(now)}
 status: draft
+propone: por-completar
 ---
 
 # Investigación semanal — ${isoDate(now)}
 
-<!-- Dos convenciones que el ciclo necesita y que nada más sostiene:
+<!-- Tres convenciones que el ciclo necesita y que nada más sostiene:
 
   · Etiquetá cada hallazgo H1, H2, … en el orden en que aparecen. «Evidencia» y «Recomendación» se
     refieren a ellos por esa clave, y la propuesta mensual la cita para decir de qué hallazgo sale
@@ -57,6 +63,12 @@ status: draft
   · No renombres los títulos. «## Recomendación» se lee con un patrón exacto y es lo único que la
     propuesta consolida de cada informe: renombrarlo no da error, deja la propuesta vacía.
 
+  · Contestá «propone» en el frontmatter, con «si» o con «no». Es «si» cuando el informe pide tocar
+    algún archivo del cargo —SKILL.md, sources.yaml, references/, un caso— y «no» cuando lo hallado
+    no cambia ningún contrato, aunque «Recomendación» explique largamente por qué. Un «no» se
+    mergea sin revisión humana: no hay nada que decidir. Ante la duda va «si», que sólo cuesta una
+    mirada.
+
 Este comentario vive fuera de toda sección a propósito — dentro de «Recomendación» viajaría a cada
 propuesta consolidada. -->
 

package/engine/cli/archive.js

@@ -0,0 +1,87 @@
+'use strict'
+
+// Los comandos que mueven estado ya decidido: archivar lo que cerró y declarar de una vez qué historia
+// llegó con el proyecto. Viven aparte de `planning.js` porque son la otra mitad de una costura: aquéllos
+// leen y juzgan sin mutar nada, éstos escriben. Se separaron cuando el archivo cruzó las 500 líneas, y
+// lo que decidió el corte fue eso y no el número.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const P = require('../planning/parser')
+const PC = require('../planning/contracts')
+const AD = require('../planning/adoption')
+const F = require('../core/files')
+const { fail } = require('./io')
+
+// La fecha de hoy, la misma que usan los comandos que leen.
+const TODAY = () => new Date().toISOString().slice(0, 10)
+
+// El historial de acciones humanas se acumula en un solo archivo y no por épica: una fila no pertenece
+// a ninguna, y esperar el cierre de una épica dejaría sin archivar las de un planning que todavía no
+// cerró ninguna —que es justo cuando el archivo se vuelve ilegible—.
+// Adoptar es declarar de una vez qué historia llegó con el proyecto. Se genera con lo que hoy no cumple
+// y no se vuelve a correr: un baseline que se regenera perdona de nuevo lo que alguien ya se tomó el
+// trabajo de arreglar, y uno que crece a mano deja de ser una lista de perdones para ser una amnistía.
+// Achicarlo sí es a mano, borrando el renglón que `check` señala.
+function adopt(dir) {
+  const root = path.resolve(dir || '.')
+  const target = path.join(root, AD.BASELINE)
+  if (fs.existsSync(target)) {
+    // Un baseline que ya trae huella no se toca: regenerarlo es exactamente lo que la huella impide.
+    // Uno sin huella lo generó una versión anterior, y sellarlo no es regenerar nada — se calcula sobre
+    // lo que ya está—, así que es la única salida de un aviso que si no no tendría ninguna.
+    const existing = fs.readFileSync(target, 'utf8')
+    if (!AD.sealWarnings(root).some((one) => /sin huella/.test(one))) {
+      fail(`${AD.BASELINE} ya existe: se genera una vez. Para retirar un renglón, ponele \`#~\` `
+        + 'delante; `check` marca los que ya cumplen.')
+    }
+    const slugs = AD.declared(existing)
+    F.atomicWrite(target, existing.replace(/\n?$/, `\n# huella: ${slugs.length} entradas · `
+      + `sha256:${AD.digest(slugs)}\n`))
+    return console.log(`✓ ${AD.BASELINE} sellado con ${slugs.length} entrada(s); la lista no cambió`)
+  }
+  const epics = P.readEpics(root)
+  const pending = P.readDone(root).entries.filter((entry) => PC.doneEntryErrors(entry, epics).length)
+  if (!pending.length) {
+    return console.log('= no hay nada que exentar: todas las entradas de DONE cumplen el contrato')
+  }
+  const today = TODAY()
+  const slugs = pending.map((entry) => entry.slug)
+  F.atomicWrite(target, `# Entradas anteriores a la adopción de Cauce (${today}). No se agregan nuevas:\n`
+    + '# desde esa fecha rige el contrato completo, y `check` avisa cuando una de éstas pasa a\n'
+    + '# cumplirlo para que le pongas `#~` delante y quede retirada.\n'
+    + `# huella: ${slugs.length} entradas · sha256:${AD.digest(slugs)}\n`
+    + `${slugs.join('\n')}\n`)
+  console.log(`✓ ${pending.length} entrada(s) exentas en ${AD.BASELINE}`)
+  return console.log('  revisá la lista: lo que sí cumple el contrato no tiene por qué estar ahí')
+}
+
+function archiveHumanActions(root) {
+  const source = path.join(root, 'HUMAN_ACTIONS.md')
+  const rows = P.readHumanActions(root).filter((row) => row.resolved)
+  if (!rows.length) return console.log('= no hay filas resueltas')
+  const target = path.join(root, 'done', 'human-actions.md')
+  const header = '| Tarea | Estado | Origen | Acción concreta y condición de desbloqueo |\n|---|---|---|---|'
+  const previous = P.read(target).trimEnd()
+  const head = previous || `---\nstatus: archived\n---\n\n# Acciones humanas resueltas\n\n${header}`
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  F.atomicWrite(target, `${head}\n${rows.map((row) => row.raw).join('\n')}\n`)
+  const drop = new Set(rows.map((row) => row.raw))
+  const kept = P.read(source).split('\n').filter((line) => !drop.has(line))
+  F.atomicWrite(source, `${kept.join('\n').trimEnd()}\n`)
+  return console.log(`✓ ${rows.length} fila(s) archivadas`)
+}
+// Archivar una épica se retiró en 0.71.0. Existía para descongestionar un `DONE.md` que se hinchaba con
+// una entrada por tarea; con un archivo por tarea no hay nada que descongestionar, y mover esos archivos
+// a una carpeta por épica sería reintroducir el movimiento que la mudanza vino a sacar.
+//
+// El comando se queda para lo que sí sigue archivándose, y para decirle a quien escriba el número que ya
+// no hace falta: sin esto contestaría «La épica debe ser NNN», que manda a corregir la forma de algo que
+// no existe.
+function archive(dir, rawNum) {
+  if (String(rawNum || '') === 'human-actions') return archiveHumanActions(path.resolve(dir || '.'))
+  return fail('Sólo se archiva `human-actions`. La evidencia de una tarea ya vive en su propio archivo '
+    + 'de `done/`, así que archivar una épica dejó de tener sentido.', 2)
+}
+
+module.exports = { archive, adopt }

package/engine/cli/args.js

@@ -7,7 +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', '--promote',
+  '--task', '--promote', '--hito',
 ])
 
 // Qué acepta cada comando, y a la vez qué comandos existen. Una bandera desconocida se rechaza en vez
@@ -19,8 +19,12 @@ const FLAGS = {
   onboard: ['--json'],
   check: ['--json'],
   tree: ['--json', '--no-color'],
-  context: ['--json'],
+  context: ['--json', '--hito'],
   recurring: ['--json', '--promote'],
+  claim: ['--json'],
+  runners: ['--json'],
+  worktree: ['--json'],
+  release: [],
   evidence: ['--json', '--task'],
   upgrade: ['--check', '--force'],
   destroy: ['--force'],

package/engine/cli/catalog.js

@@ -115,7 +115,15 @@ function evaluationBench(root, agent, caso, force, kind) {
   // sin pagar un `npm install` por corrida. El cargo llega a un banco donde el CLI funciona.
   const scope = path.join(dir, 'node_modules', '@ingeniomaps')
   fs.mkdirSync(scope, { recursive: true })
-  fs.symlinkSync(IN.PROJECT_ROOT, path.join(scope, 'cauce'), 'dir')
+  // El enlace se pisa por lo mismo que el andamiaje de arriba: a veces sobrevive al borrado del banco, y
+  // entonces crearlo corta la corrida con `EEXIST` en vez de rehacerlo. Es el único paso que no seguía esa
+  // regla, y el que falló en CI rehaciendo el mismo `11-otro` que ya tiene reintentos por esto.
+  //
+  // `rmSync` sobre un enlace lo quita a él y no a lo que apunta —que acá es la raíz del toolkit—, así que
+  // esto no puede llevarse por delante el repositorio.
+  const link = path.join(scope, 'cauce')
+  fs.rmSync(link, { force: true })
+  fs.symlinkSync(IN.PROJECT_ROOT, link, 'dir')
 
   // El artefacto del caso, si lo tiene: la guía del proveedor que el pedido manda implementar, el CSV
   // con instrucciones adentro. Entra antes del commit limpio a propósito — si entrara después, `status`