@ingeniomaps/cauce 0.80.0 → 0.82.0

package/engine/cli/instance.js

@@ -13,6 +13,7 @@ const M = require('../core/manifest')
 const OB = require('../core/onboarding')
 const P = require('../planning/parser')
 const ST = require('../planning/state')
+const RC = require('../planning/recurring')
 const A = require('../automation')
 const { fail } = require('./io')
 const { declareEngine, pinEngine, undeclareEngine } = require('./dependency')
@@ -97,6 +98,7 @@ function scaffold(root, { name, mode, force = false, quiet = false }) {
     '{{PROJECT_NAME}}': name,
     '{{MODE}}': mode,
     '{{WORKSPACE_PATH}}': mode === 'embedded' ? '.' : '..',
+    ...RC.sinceValues(new Date().toISOString().slice(0, 10)),
   }, force, providerNames(), quiet)
   // No se copia `.github/`: `ci.yml` valida el toolkit con `npm run ci` —que una instancia no tiene— y
   // el ciclo de aprendizaje dejó de distribuirse en 0.4.0. Copiar salteando lo que no aplica dejaba
@@ -113,8 +115,9 @@ function scaffold(root, { name, mode, force = false, quiet = false }) {
   declareEngine(path.join(root, 'package.json'), version)
   let deliveredPaths = {}
   for (const relative of O.trackedPaths()) {
-    const dir = path.join(root, relative)
-    if (fs.existsSync(dir)) deliveredPaths = M.record(root, relative, O.treeFiles(dir), deliveredPaths)
+    if (fs.existsSync(path.join(root, relative))) {
+      deliveredPaths = M.record(root, relative, O.deliveredFiles(root, relative), deliveredPaths)
+    }
   }
   deliveredPaths = M.recordPaths(root, O.SYSTEM_FILES, deliveredPaths)
   // Adoptar Cauce en un repositorio con contenido es `init --force`, y lo que se conserva ahí lo
@@ -277,12 +280,14 @@ function upgrade(dir, cli) {
   const to = require(path.join(PROJECT_ROOT, 'package.json')).version
   const system = O.systemPaths(root)
   const changed = O.localChanges(root)
+  const colliding = O.collisions(root)
   const overrides = O.overrides(root)
 
   // El código de salida lo aplica acá y no adentro: `--check` mira y cuenta, y quien decide qué hacer
   // con lo que vio es el comando. Escondido en la función que informa, el corte del flujo no se ve.
   if (dry) {
-    const code = previewUpgrade({ from, to, changed })
+    for (const file of colliding) console.log(`  choca con uno tuyo: ${file}`)
+    const code = previewUpgrade({ from, to, changed }) || (colliding.length ? 1 : 0)
     if (code) process.exit(code)
     return
   }
@@ -311,6 +316,16 @@ function upgrade(dir, cli) {
     console.log(`${adviceFor([...conservados])}\n`)
     console.log('Para tomar la versión nueva y descartar la tuya, repetí con --force.\n')
   }
+  // Un archivo propio que se llama como uno que el paquete empieza a traer (caso 110): se conserva y se
+  // dice, igual que una edición local, y `--force` lo reemplaza diciéndolo.
+  const choques = new Set(force ? [] : colliding)
+  for (const file of choques) {
+    console.log(`= conservado ${file}: ya existía y Cauce no lo entregó, así que el del paquete no se `
+      + 'instaló. Renombrá el tuyo y repetí, o repetí con --force para reemplazarlo.')
+  }
+  if (force) {
+    for (const file of colliding) console.log(`− reemplazado ${file}, que era tuyo y se llamaba como uno del paquete`)
+  }
 
   // Lo que una versión agrega y es del proyecto: se crea si falta y nunca se pisa. `systemPaths` no lo
   // incluye a propósito —lo reemplazaría en cada actualización, que es lo que un archivo del proyecto
@@ -330,6 +345,7 @@ function upgrade(dir, cli) {
       '{{PROJECT_NAME}}': config.project || path.basename(root),
       '{{MODE}}': O.mode(root),
       '{{WORKSPACE_PATH}}': O.mode(root) === 'embedded' ? '.' : '..',
+      ...RC.sinceValues(new Date().toISOString().slice(0, 10)),
     })) content = content.replaceAll(key, value)
     F.atomicWrite(target, content)
     added.push(relative)
@@ -350,7 +366,10 @@ function upgrade(dir, cli) {
     }
   }
 
-  const conservar = (file) => conservados.has(path.relative(root, file).replace(/\\/g, '/'))
+  const conservar = (file) => {
+    const relative = path.relative(root, file).replace(/\\/g, '/')
+    return conservados.has(relative) || choques.has(relative)
+  }
   for (const relative of [...system, ...O.RUNTIME_PATHS]) {
     const origin = path.join(PROJECT_ROOT, O.sourceOf(relative))
     if (!fs.existsSync(origin)) continue
@@ -396,11 +415,21 @@ function upgrade(dir, cli) {
   // 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)
+    if (fs.existsSync(path.join(root, relative))) {
+      record = M.record(root, relative, O.deliveredFiles(root, relative), record)
+    }
+  }
+  // Migración: una versión anterior pudo haber registrado un guard propio —qué cuenta, en `deliveredFiles`—.
+  // Se olvida acá. Y un choque que se conservó no se registra, para que la corrida siguiente lo vuelva a ver.
+  for (const relative of O.RUNTIME_PATHS) {
+    const shipped = O.shippedFiles(relative)
+    for (const key of Object.keys(record)) {
+      if (key.startsWith(`${relative}/`) && !shipped.has(key.slice(relative.length + 1))) delete record[key]
+    }
   }
   record = M.recordPaths(root, O.SYSTEM_FILES, record)
   for (const file of conservados) if (entregado[file]) record[file] = entregado[file]
+  for (const file of choques) delete record[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/planning.js

@@ -11,6 +11,7 @@ const PC = require('../planning/contracts')
 const SR = require('../planning/structure')
 const SZ = require('../planning/sizing')
 const RC = require('../planning/recurring')
+const IB = require('../planning/inbox')
 const CL = require('../planning/claims')
 const R = require('../core/repos')
 const ST = require('../planning/state')
@@ -23,6 +24,7 @@ const OB = require('../core/onboarding')
 const C = require('../config/validate')
 const CP = require('../config/paths')
 const AG = require('../agents/catalog')
+const RL = require('../automation/rules')
 const { fail, planningRoot } = require('./io')
 
 // Qué dimensiones enumera el molde de `organization/` y cuáles dejaron de estar. Un agente que reescribe
@@ -97,12 +99,14 @@ function check(dir, cli) {
   for (const file of required) if (!fs.existsSync(path.join(root, file))) errors.push(`falta ${file}`)
 
   const configPath = path.join(root, '..', 'ops.config.json')
+  let config = null
   if (fs.existsSync(configPath)) {
     try {
       const raw = fs.readFileSync(configPath, 'utf8')
-      const config = JSON.parse(raw)
+      config = JSON.parse(raw)
       if (!raw.includes('{{')) {
         errors.push(...C.validateOpsConfig(config))
+        warnings.push(...C.configWarnings(config))
         if (Array.isArray(config.workspaceRoots)) {
           for (const workspace of config.workspaceRoots) {
             if (workspace && workspace.name && workspace.path
@@ -169,6 +173,7 @@ function check(dir, cli) {
   const recurring = RC.read(root)
   errors.push(...RC.validate(recurring))
   warnings.push(...RC.warnings(RC.status({ ...recurring, done, today: TODAY() })))
+  warnings.push(...IB.warnings(root, done, config))
   warnings.push(...AD.sealWarnings(root))
   // Una aprobación vale para el conjunto que nombra, así que olvidada sigue autorizando
   // esas mismas rutas la próxima vez que alguien las stagee. No caduca sola: lo que la cierra es que se
@@ -213,6 +218,8 @@ function check(dir, cli) {
     warnings.push(`${override.collection}/${override.project} sobrescribe ${override.system} `
       + `(override explícito)${retired.length ? `; deja de regir ${retired.join(', ')}` : ''}`)
   }
+  // Y lo que instaló cada runner, contra esas mismas reglas (caso 099).
+  warnings.push(...RL.staleLines(path.resolve(root, '..')))
   // Misma regla para los cargos, que es donde más caro sale: un fork se hace una vez y se olvida.
   const FK = require('../agents/fork')
   for (const entry of FK.drift(path.resolve(root, '..'))) warnings.push(FK.driftLine(entry))
@@ -380,8 +387,14 @@ function context(dir, cli) {
     // mismo criterio. Por qué no la encola una máquina está en la fase Pick de `autobuild`.
     nextEpic: (!task && [...state.epics].filter((one) => one.status === 'open')
       .sort((a, b) => String(a.num).localeCompare(String(b.num)))[0]) || null,
+    // Sólo en el JSON: lo leen los recorridos que escriben en el INBOX, para no repetir un nombre.
+    inbox: P.inboxHeads(root),
+    // Las reglas que rigen, con los overrides resueltos. Van acá porque `autobuild` ya lee este comando y
+    // tiene prohibido abrir otros archivos para completar su contrato (caso 105).
+    rules: O.effectiveRules(path.resolve(root, '..')),
   }
   if (cli.has('--json')) return console.log(JSON.stringify(report))
+  const reglas = () => console.log(`RULES  ${report.rules.join(', ') || '(ninguna)'}`)
 
   if (report.blocked === 'awaiting-review') {
     const first = P.read(gate).split('\n').find((line) => line.trim() && !line.startsWith('#')) || ''
@@ -419,7 +432,7 @@ function context(dir, cli) {
     espera()
     for (const action of report.humanActions) console.log(`HUMAN  ${action.task}: ${action.action}`)
     due()
-    return
+    return reglas()
   }
   console.log(`TASK   ${report.task.slug}${report.task.tier ? ` [${report.task.tier}]` : ''}` +
     `${report.task.service ? `  service: ${report.task.service}` : ''}` +
@@ -448,6 +461,7 @@ function context(dir, cli) {
   if (report.blockedTasks.length) console.log(`SKIP   ${report.blockedTasks.join(', ')} (acción humana abierta)`)
   for (const action of report.humanActions) console.log(`HUMAN  ${action.task}: ${action.action}`)
   due()
+  reglas()
 }
 
 // Qué trabajo recurrente vence, y la línea con la que se promueve. Emite esa línea y no la escribe:

package/engine/config/validate.js

@@ -20,7 +20,7 @@ function validateOpsConfig(config) {
   // `cauceVersion` la escribe el toolkit, no la persona: registra de qué versión salió la instancia.
   const allowed = new Set([
     '$schema', 'cauceVersion', 'project', 'mode', 'workspaceRoots', 'writableOutsideRoots', 'runner',
-    'migrations',
+    'migrations', 'inbox',
   ])
   for (const key of Object.keys(config)) {
     if (RETIRED[key]) errors.push(`ops.config.json: ${key} ya no se usa: ${RETIRED[key]}`)
@@ -34,9 +34,26 @@ function validateOpsConfig(config) {
   validateWritable(config.writableOutsideRoots, errors)
   validateRunner(config.runner, errors)
   validateMigrations(config.migrations, errors)
+  validateInbox(config.inbox, errors)
   return errors
 }
 
+// El umbral del aviso de tamaño del INBOX. Sólo un entero positivo: un cero o un texto se leerían como
+// «avisá siempre» o «nunca», y ninguno de los dos es algo que alguien escriba a propósito.
+function validateInbox(inbox, errors) {
+  if (inbox === undefined) return
+  if (!inbox || typeof inbox !== 'object' || Array.isArray(inbox)) {
+    errors.push('ops.config.json: inbox debe ser un objeto')
+    return
+  }
+  for (const key of Object.keys(inbox)) {
+    if (key !== 'warnLines') errors.push(`ops.config.json: inbox.${key} no está permitido`)
+  }
+  if ('warnLines' in inbox && !(Number.isInteger(inbox.warnLines) && inbox.warnLines > 0)) {
+    errors.push('ops.config.json: inbox.warnLines debe ser un entero mayor que cero, o no estar')
+  }
+}
+
 // Qué cuenta como migración para el guard. Sin declararlo, sólo `.sql` — y ése es el default que hace
 // falta decir, porque un proyecto TypeORM, Prisma, Django o Rails tiene el guard cableado y en verde sin
 // que mire una sola migración (caso 077).
@@ -68,11 +85,36 @@ function validateMigrations(migrations, errors) {
   }
 }
 
+// Lo que la configuración tiene de dudoso y no de inválido. Va aparte de `validateOpsConfig` porque lo que
+// aquélla devuelve son errores y la leen también los guards: una advertencia ahí sería un rechazo.
+//
+// Hoy sólo el nombre repetido: dos raíces con el mismo `name` dejan dos servicios indistinguibles en
+// `check`, `onboard` y `scan`, y una credencial que no se puede atribuir a ninguno (caso 113). Avisa y no
+// falla porque nadie eligió su `name` pensando que fuera único, así que rechazarlo le rompería la puerta a
+// una instancia que hoy funciona, y lo que está en juego es un nombre ambiguo, no algo que se pierda.
+function configWarnings(config) {
+  const roots = Array.isArray(config && config.workspaceRoots) ? config.workspaceRoots : []
+  const found = []
+  const named = new Map()
+  for (const workspace of roots) {
+    const name = workspace && typeof workspace.name === 'string' ? workspace.name.trim() : ''
+    if (!name) continue
+    if (named.has(name)) {
+      found.push(`ops.config.json: ${name} nombra dos raíces (${named.get(name)} y ${workspace.path}): `
+        + 'sus servicios salen con el mismo nombre. Renombrá una')
+    } else named.set(name, workspace.path)
+  }
+  return found
+}
+
 function validateWorkspaces(workspaces, errors) {
   if (!Array.isArray(workspaces) || !workspaces.length) {
     errors.push('ops.config.json: workspaceRoots debe contener al menos una raíz')
     return
   }
+  // El nombre repetido no se rechaza acá: lo avisa `check`, que es quien puede hacerlo sin romperle la
+  // puerta a una instancia que hoy funciona (caso 113). Este validador lo leen también los guards, y lo
+  // que devuelve son errores: meterlo acá era decidir que la configuración es inválida.
   for (const [index, workspace] of workspaces.entries()) {
     if (!workspace || typeof workspace !== 'object' || Array.isArray(workspace)) {
       errors.push(`ops.config.json: workspaceRoots[${index}] debe ser un objeto`)
@@ -119,10 +161,18 @@ function validateRunner(runner, errors) {
     return
   }
   const booleans = ['humanCheckpointBetweenMilestones', 'commitPerTask', 'allowPush']
-  const allowed = new Set(['maxTaskHours', ...booleans])
+  const allowed = new Set(['maxTaskHours', 'pushToLiveBranches', ...booleans])
   for (const key of Object.keys(runner)) {
     if (!allowed.has(key)) errors.push(`ops.config.json: runner.${key} no está permitido`)
   }
+  // Un patrón haría de un permiso por rama un permiso por familia, que es lo que el campo vino a evitar
+  // (caso 108): el guard compara el nombre tal cual, y `release/*` no publicaría en ninguna.
+  const live = runner.pushToLiveBranches
+  if (live !== undefined && (!Array.isArray(live)
+    || live.some((branch) => typeof branch !== 'string' || !/^[^\s*?[]+$/.test(branch)))) {
+    errors.push('ops.config.json: runner.pushToLiveBranches debe ser una lista de nombres de rama exactos, '
+      + 'sin espacios ni patrones')
+  }
   if (typeof runner.maxTaskHours !== 'number' || runner.maxTaskHours <= 0) {
     errors.push('ops.config.json: runner.maxTaskHours debe ser mayor que cero')
   }
@@ -133,4 +183,4 @@ function validateRunner(runner, errors) {
   }
 }
 
-module.exports = { validateOpsConfig }
+module.exports = { configWarnings, validateOpsConfig }

package/engine/core/onboarding.js

@@ -9,6 +9,7 @@
 const fs = require('node:fs')
 const path = require('node:path')
 const { inventory } = require('./scan')
+const { sensitiveKey } = require('../integrations/registry')
 
 // La raíz del paquete: el molde contra el que se compara lo que una instancia escribió.
 const PACKAGE_ROOT = path.resolve(__dirname, '..', '..')
@@ -91,11 +92,23 @@ function missingSections(root) {
   return warnings
 }
 
+// Una aparición cuenta sólo si lo que la rodea no puede ser parte de otro nombre de variable: buscada
+// como subcadena, API_SECRET_ROTATION daba por cargada a API_SECRET (caso 111). El escaneo sólo deja
+// pasar identificadores, así que el nombre entra a la expresión sin nada que escapar.
+function named(text, name) {
+  return new RegExp(`(?<![A-Za-z0-9_])${name}(?![A-Za-z0-9_])`).test(text)
+}
+
 // Credenciales que el proyecto declara y que no aparecen en ningún contrato. El arranque tiene que
 // dejar una fila por cada una —quién la carga y dónde— y en la práctica cubre las que se hablaron en la
 // conversación: las que sólo estaban en el inventario se pierden, y con ellas el servicio externo que
 // hay detrás. Una variable sin dueño no rompe nada hoy; rompe el día que alguien tiene que desplegar.
 //
+// Credencial es lo que tiene nombre de secreto según `sensitiveKey`, la misma regla con la que la
+// declaración de secretos y la configuración de una integración rechazan un valor. Contando cualquier
+// variable, el aviso listaba ciento ocho nombres de build y la única credencial quedaba en «y 1 más»
+// (caso 102). El precio es el secreto con nombre de configuración, y el aviso lo dice.
+//
 // Sólo cuando la instancia ya tiene contexto escrito: antes del arranque no hay dónde estuvieran.
 function orphanCredentials(root) {
   if (guide(root).fresh) return []
@@ -108,16 +121,33 @@ function orphanCredentials(root) {
     .join('\n')
   if (!contracts) return []
   const orphans = []
+  const cut = []
   for (const service of inventory(root)) {
-    for (const name of (service.env || {}).names || []) {
-      if (!contracts.includes(name)) orphans.push(`${name} (${service.path})`)
+    const env = service.env || {}
+    for (const name of env.names || []) {
+      if (sensitiveKey(name) && !named(contracts, name)) orphans.push({ name, service: service.path })
     }
+    if (env.truncated) cut.push(`${service.path} (${env.truncated} de ${env.names.length + env.truncated})`)
   }
-  if (!orphans.length) return []
-  const summary = orphans.length > 4
-    ? `${orphans.slice(0, 4).join(', ')} y ${orphans.length - 4} más`
-    : orphans.join(', ')
-  return [`el proyecto declara ${summary} y no aparecen en el mapa ni en HUMAN_ACTIONS: nadie las carga`]
+  const warnings = []
+  if (orphans.length) {
+    const listed = orphans.map((one) => `${one.name} (${one.service})`)
+    const summary = listed.length > 4
+      ? `${listed.slice(0, 4).join(', ')} y ${listed.length - 4} más`
+      : listed.join(', ')
+    const services = [...new Set(orphans.map((one) => one.service))].join(', ')
+    warnings.push(`credenciales por nombre sin dueño (${orphans.length}, en ${services}): ${summary} — no `
+      + 'aparecen en el mapa ni en HUMAN_ACTIONS: nadie las carga. El dueño se escribe en '
+      + 'organization/workspace.md o en una fila de planning/HUMAN_ACTIONS.md; el criterio es el nombre, así '
+      + 'que una credencial con nombre de configuración no aparece acá')
+  }
+  // El escaneo corta cada ejemplo en un tope, y lo que quedó afuera no se miró: con el filtro, puede ser
+  // justo la credencial.
+  if (cut.length) {
+    warnings.push(`sin revisar por credenciales sin dueño, pasado el tope de variables por servicio: `
+      + `${cut.join(', ')} — lo que quedó afuera puede incluir una credencial que nadie carga`)
+  }
+  return warnings
 }
 
 module.exports = {

package/engine/core/ownership.js

@@ -8,6 +8,9 @@
 const fs = require('node:fs')
 const path = require('node:path')
 
+// El paquete que corre: contra él se decide qué del runtime es una entrega de Cauce (casos 100 y 110).
+const PACKAGE_ROOT = path.resolve(__dirname, '..', '..')
+
 // Archivos de los que el toolkit es único autor. Un proyecto que necesite cambiarlos no los
 // edita: agrega una regla propia junto a las de `system/`, que sí sobrevive al upgrade.
 const SYSTEM_FILES = [
@@ -176,6 +179,27 @@ function overrides(root) {
   return found
 }
 
+// Las reglas que rigen una instancia, relativas a su raíz: cada `planning/rules/*.md` del proyecto y cada una de
+// `system/` que el proyecto no sobrescribió. `overrides()` ya sabía cuál reemplaza a cuál y sólo servía para
+// avisar; esto es lo que se entrega a quien trabaja (casos 099 y 105). Sólo el primer nivel, igual que `check`.
+function effectiveRules(root) {
+  const dir = path.join(root, 'planning', 'rules')
+  const markdown = (sub) => {
+    try {
+      return fs.readdirSync(path.join(dir, sub), { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'README.md'
+          && !entry.name.startsWith('.'))
+        .map((entry) => entry.name).sort()
+    } catch { return [] }
+  }
+  const replaced = new Set(overrides(root).filter((one) => one.collection === 'planning/rules')
+    .map((one) => one.system))
+  return [
+    ...markdown('system').filter((name) => !replaced.has(name)).map((name) => `planning/rules/system/${name}`),
+    ...markdown('').map((name) => `planning/rules/${name}`),
+  ]
+}
+
 // Rutas que el toolkit dejó de materializar. Sin esto una instancia arrastra para siempre lo que
 // alguna versión suya copió: `upgrade` agrega y reemplaza, pero nunca quitaba nada.
 // Cada archivo propio del molde, con cómo llega a una instancia que **ya existe**. `upgrade` sólo
@@ -302,7 +326,7 @@ function localChanges(root) {
   for (const target of trackedPaths()) {
     const dir = path.join(root, target)
     if (!fs.existsSync(dir)) continue
-    for (const file of manifest.edited(root, target, treeFiles(dir))) changed.push(`${target}/${file}`)
+    for (const file of manifest.edited(root, target, deliveredFiles(root, target))) changed.push(`${target}/${file}`)
   }
   // Los archivos sueltos del sistema entran por la misma puerta. Quedaban afuera, así que `upgrade`
   // los reemplazaba en silencio: un cargo escribió el índice de ADR que el propio README le pedía
@@ -311,8 +335,47 @@ function localChanges(root) {
   return changed
 }
 
+// Lo que el paquete que corre trae en una ruta del runtime. El resto de esa carpeta es de la empresa —un
+// guard propio—, y no es una entrega: registrado, pasaba a «editado» en cuanto la empresa lo tocaba, y
+// `upgrade --check` salía con 1 por algo que nunca fue de Cauce (caso 100).
+function shippedFiles(relative) {
+  return new Set(treeFiles(path.join(PACKAGE_ROOT, sourceOf(relative))))
+}
+
+// Lo que de una ruta rastreada cuenta como entregado: todo, salvo en el runtime, donde sólo lo que el
+// paquete trae. Lo usan el registro de `init` y de `upgrade` y la detección de ediciones, que tienen que
+// contar lo mismo.
+function deliveredFiles(root, relative) {
+  const files = treeFiles(path.join(root, relative))
+  return RUNTIME_PATHS.includes(relative) ? files.filter((file) => shippedFiles(relative).has(file)) : files
+}
+
+// Lo que el paquete empieza a traer con un nombre que la instancia ya usaba para algo suyo: un guard propio
+// que se llama como uno nuevo del toolkit (caso 110). Sin huella en el registro no cuenta como edición, así
+// que copiar encima lo borraba sin decirlo. Sólo si el registro ya conoce la ruta: en una instancia
+// anterior al registro, «sin huella» también es «lo entregó una versión vieja».
+function collisions(root) {
+  const manifest = require('./manifest')
+  const recorded = manifest.read(root)
+  const found = []
+  for (const relative of RUNTIME_PATHS) {
+    if (!Object.keys(recorded).some((key) => key.startsWith(`${relative}/`))) continue
+    for (const file of shippedFiles(relative)) {
+      const local = path.join(root, relative, file)
+      if (recorded[`${relative}/${file}`] || !fs.existsSync(local)) continue
+      const shipped = path.join(PACKAGE_ROOT, sourceOf(relative), file)
+      if (manifest.digest(local) !== manifest.digest(shipped)) found.push(`${relative}/${file}`)
+    }
+  }
+  return found
+}
+
 module.exports = {
   RETIRED,
+  collisions,
+  deliveredFiles,
+  effectiveRules,
+  shippedFiles,
   RETIRED_COMPARTIDO,
   TEMPLATE_OWN,
   TEMPLATE_PREFIXES,

package/engine/core/scan.js

@@ -171,17 +171,28 @@ function scan(root, skip = '') {
   }
 }
 
-// Dónde puede mirar una instancia: exactamente las raíces que declara, y nada por encima de ellas. Sale
+// Dónde puede mirar una instancia: exactamente las raíces que declara, con el nombre que les puso. Sale
 // de `ops.config.json` en vez de suponerse —el sidecar declara `..`, el embebido `.`— para que acotar las
 // raíces acote también el escaneo, y para que nadie termine recorriendo la carpeta de al lado.
-function workspaceRoots(root) {
+//
+// El nombre cae a la carpeta cuando la raíz no lo declara: `check` lo exige, pero `scan` y `onboard`
+// corren igual sobre una configuración que nunca pasó por ahí, y ahí el prefijo saldría `undefined`.
+function declaredRoots(root) {
+  const fallback = [{ name: path.basename(root), dir: root }]
   try {
     const config = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8'))
-    const declared = (config.workspaceRoots || []).map((entry) => path.resolve(root, entry.path || '.'))
-    return declared.length ? declared : [root]
-  } catch { return [root] }
+    const declared = (config.workspaceRoots || []).map((entry) => {
+      const dir = path.resolve(root, entry.path || '.')
+      return { name: String(entry.name || '').trim() || path.basename(dir), dir }
+    })
+    return declared.length ? declared : fallback
+  } catch { return fallback }
 }
 
+// Sólo las rutas. Es lo que mira quien acota una escritura, y `onboard --json` las emite tal cual en
+// `roots`: darles forma de objeto habría cambiado ese contrato para quien no necesita el nombre.
+const workspaceRoots = (root) => declaredRoots(root).map((one) => one.dir)
+
 // Qué hay en las raíces declaradas, antes de que nadie razone sobre ello. La raíz ops se saltea: no es
 // un servicio del proyecto, y su `package.json` sólo declara el motor.
 // Los candidatos de una raíz, con el proyecto que vive en ella misma primero: un monolito declara sus
@@ -197,12 +208,15 @@ function candidates(workspace, skip = '') {
 // Con varias raíces, cada repositorio es la raíz de su propio escaneo y su candidato principal se llama
 // `.`: tres servicios con el mismo nombre y nada que los distinga. El prefijo los vuelve nombrables, que
 // es la única forma de que una credencial pueda atribuirse a un servicio en vez de quedar suelta.
+//
+// El prefijo es el `name` declarado y no la carpeta, que es lo que dejaba a `gouduet/keycloak` y
+// `hypixo/keycloak` llamándose las dos `keycloak` (caso 113). Que no se repita lo exige el validador.
 function inventory(root) {
-  const roots = workspaceRoots(root)
-  if (roots.length === 1) return candidates(roots[0], root)
-  return roots.flatMap((workspace) => candidates(workspace, root).map((service) => ({
+  const roots = declaredRoots(root)
+  if (roots.length === 1) return candidates(roots[0].dir, root)
+  return roots.flatMap(({ name, dir }) => candidates(dir, root).map((service) => ({
     ...service,
-    path: service.path === '.' ? path.basename(workspace) : `${path.basename(workspace)}/${service.path}`,
+    path: service.path === '.' ? name : `${name}/${service.path}`,
   })))
 }
 

package/engine/hooks/approval.js

@@ -20,14 +20,20 @@
 //
 // Queda a la vista porque `check` avisa mientras exista. Sin eso, un archivo olvidado sigue autorizando
 // esas mismas rutas la próxima vez que alguien las stagee, que es la puerta abierta que esto evitaba.
+//
+// El archivo es la vía de cuando no hay chat. Con una persona hablando, lo que ella pidió ya está
+// aprobado —cómo se sabe, en `chat.js`—, y escribir el archivo deja de ser necesario (caso 098).
 
 const path = require('node:path')
 const fs = require('node:fs')
+const { opsRoot, cwdOf } = require('./input')
+const CHAT = require('./chat')
 
 const APPROVAL = '.ops-approval'
 
 // Una ruta por línea, `#` para lo demás. El archivo ausente y el vacío son lo mismo: no hay nada
-// aprobado, que es el estado normal.
+// aprobado, que es el estado normal. Un push se aprueba igual, con la línea `push <remoto> <rama>`
+// tal cual y sin patrones: `feat/*` convertiría una aprobación puntual en un permiso (caso 103).
 function read(root) {
   let text = ''
   try { text = fs.readFileSync(path.join(root, 'planning', APPROVAL), 'utf8') } catch { return [] }
@@ -35,10 +41,23 @@ function read(root) {
 }
 
 // Qué queda sin aprobar de lo que un guard está por bloquear. Se reporta sólo eso: mandar a revisar lo
-// que ya se aprobó es lo que hace que la próxima vez nadie lea el mensaje.
-function pending(root, files) {
+// que ya se aprobó es lo que hace que la próxima vez nadie lea el mensaje. Cuenta también lo que la
+// persona pidió en el chat.
+function pending(root, files, input) {
   const approved = new Set(root ? read(root) : [])
-  return files.filter((file) => !approved.has(file))
+  return CHAT.unauthorized(input, files.filter((file) => !approved.has(file)))
+}
+
+// El archivo que el guard va a leer, nombrado desde la carpeta en la que está la sesión. En sidecar la
+// sesión se abre en el workspace y la instancia es una subcarpeta, así que `planning/` a secas nombraba
+// otro directorio y pegar ahí no destrababa nada (caso 097).
+function where(input) {
+  const root = opsRoot(input)
+  if (!root) return `planning/${APPROVAL}`
+  const file = path.join(root, 'planning', APPROVAL)
+  const session = process.env.CLAUDE_PROJECT_DIR || process.env.GEMINI_PROJECT_DIR || cwdOf(input)
+  const relative = path.relative(session, file)
+  return relative && !relative.startsWith('..') && !path.isAbsolute(relative) ? relative : file
 }
 
 // Cómo se toma la salida angosta, dicho una vez porque lo dicen todos los bloqueos que la tienen. Lleva
@@ -46,9 +65,21 @@ function pending(root, files) {
 // de un Write, relativa al repositorio la que sale del índice— y una línea en la otra forma no pega: sin
 // decirla, lo que quedaba a mano era la variable (caso 089). Nombra también la variable: sigue
 // existiendo, y esconderla haría que quien la necesite la descubra sin saber su alcance.
-const HOW = (variable, lines) => `Aprobalo pegando tal cual en planning/${APPROVAL} estas líneas:\n`
-  + lines.map((line) => `  ${line}\n`).join('')
-  + `Valen para ese conjunto y dejan de valer en cuanto cambie. La variable ${variable}=1 sigue existiendo `
-  + 'y apaga el guard para toda la sesión, que es por lo que no es la vía recomendada.'
+//
+// Con una persona en el chat, además, deja anotado lo que se frenó —para eso llama a `hold`— y lo dice
+// primero: contestar es más corto que editar un archivo, y es lo que la persona ya está haciendo. El
+// archivo queda como cosa de ella: dicho en imperativo, el agente leía «aprobalo» como una orden para él
+// e intentaba escribírselo en vez de reintentar, medido en una sesión real de Claude Code.
+function HOW(variable, lines, input) {
+  const chat = CHAT.hold(input, lines)
+  return (chat
+    ? 'Decile a la persona qué se frenó y por qué, y esperá: si contesta «dale», reintentá el mismo cambio y '
+      + 'pasa. Si prefiere aprobarlo a mano, que pegue ella tal cual en'
+    : 'Aprobalo pegando tal cual en')
+    + ` ${where(input)} estas líneas:\n`
+    + lines.map((line) => `  ${line}\n`).join('')
+    + `Valen para ese conjunto y dejan de valer en cuanto cambie. La variable ${variable}=1 sigue existiendo `
+    + 'y apaga el guard para toda la sesión, que es por lo que no es la vía recomendada.'
+}
 
-module.exports = { APPROVAL, read, pending, HOW }
+module.exports = { APPROVAL, read, pending, where, HOW }