@ingeniomaps/cauce 0.43.0 → 0.46.0

package/engine/core/onboarding.js

@@ -8,9 +8,16 @@
 
 const fs = require('node:fs')
 const path = require('node:path')
+const { inventory } = require('./scan')
 
-// El molde llega con estos marcadores. Que sigan ahí es la señal de que nadie escribió todavía.
-const PLACEHOLDERS = /Por completar|Por definir/
+// La raíz del paquete: el molde contra el que se compara lo que una instancia escribió.
+const PACKAGE_ROOT = path.resolve(__dirname, '..', '..')
+
+// El molde llega con estos marcadores, y quien redacta los deja donde todavía no hay decisión. Que
+// sigan ahí es la señal de que nadie escribió: vale para una instancia sin arrancar y para una épica
+// que no se puede activar. Sin distinguir mayúsculas, porque `por definir` en medio de una frase dice
+// exactamente lo mismo que al principio de una.
+const PLACEHOLDERS = /Por completar|Por definir/i
 
 // La única pregunta que no depende de ninguna respuesta, y por eso la única que se puede escribir de
 // antemano. Las cuatro fijas que había antes daban por sentado que el proyecto vende algo: a uno libre,
@@ -64,4 +71,57 @@ function guide(root, services = []) {
   }
 }
 
-module.exports = { guide, OPENING, DIMENSIONS, FOLLOW_UPS, PLACEHOLDERS }
+function missingSections(root) {
+  const warnings = []
+  const template = path.join(PACKAGE_ROOT, 'template', 'organization')
+  for (const name of ['company.md', 'product.md', 'domains.md']) {
+    const written = path.join(root, 'organization', name)
+    if (!fs.existsSync(written) || !fs.existsSync(path.join(template, name))) continue
+    const headings = (text) => new Set((text.match(/^##\s+(.+)$/gm) || []).map((line) => line.trim()))
+    const expected = headings(fs.readFileSync(path.join(template, name), 'utf8'))
+    const present = headings(fs.readFileSync(written, 'utf8'))
+    const missing = [...expected].filter((heading) => !present.has(heading))
+    if (!missing.length) continue
+    // Reescrito entero, faltan todas: enumerarlas hace una línea ilegible y el número dice más.
+    const summary = missing.length > 3
+      ? `${missing.slice(0, 3).join(', ')} y ${missing.length - 3} más`
+      : missing.join(', ')
+    warnings.push(`organization/${name}: sin ${summary} — el molde las trae y acá no están`)
+  }
+  return warnings
+}
+
+// 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.
+//
+// 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 []
+  const contracts = ['AGENTS.md', path.join('planning', 'HUMAN_ACTIONS.md')]
+    .map((file) => { try { return fs.readFileSync(path.join(root, file), 'utf8') } catch { return '' } })
+    .join('\n')
+  if (!contracts) return []
+  const orphans = []
+  for (const service of inventory(root)) {
+    for (const name of (service.env || {}).names || []) {
+      if (!contracts.includes(name)) orphans.push(`${name} (${service.path})`)
+    }
+  }
+  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`]
+}
+
+module.exports = {
+  missingSections,
+  orphanCredentials,
+  guide,
+  OPENING,
+  DIMENSIONS,
+  FOLLOW_UPS,
+  PLACEHOLDERS,
+}

package/engine/core/ownership.js

@@ -22,9 +22,19 @@ const SYSTEM_FILES = [
   'planning/rules/README.md',
   'planning/roadmap/README.md',
   'planning/roadmap/epic-000-template.md',
+  // La guía de entrega no tiene una línea de la empresa: describe el camino que Cauce recomienda, y lo
+  // que el proyecto declara vive en `delivery/project.md`, que sí es suyo. Sin declararla, cada mejora
+  // de la guía se quedaba en el molde: una instancia conservaba para siempre la versión del día que se
+  // creó, y `upgrade` informaba «todo lo propio quedó intacto» sobre algo que nunca fue propio.
+  'planning/delivery/README.md',
+  'planning/delivery/branches.md',
+  'planning/delivery/release.md',
+  'planning/delivery/environments.md',
+  'planning/delivery/flags.md',
+  'planning/delivery/multi-repo.md',
   'organization/roles/README.md',
-  'teams/000-template.md',
-  'teams/README.md',
+  'flows/000-template.md',
+  'flows/README.md',
   'automatization/README.md',
   'automatization/AGENTS.md',
   'integrations/README.md',
@@ -60,7 +70,7 @@ const TEMPLATE_PREFIXES = [
   'planning/',
   'organization/',
   'integrations/',
-  'teams/',
+  'flows/',
   'automatization/',
   'tools/',
 ]
@@ -163,7 +173,7 @@ function overrides(root) {
 // alguna versión suya copió: `upgrade` agrega y reemplaza, pero nunca quitaba nada.
 const RETIRED = [
   'agents/roles/system',
-  'teams/system',
+  'flows/system',
   '.github/workflows/agent-learning.yml',
   'automatization/runners',
   'automatization/workflows',

package/engine/core/scan.js

@@ -171,4 +171,48 @@ function scan(root, skip = '') {
   }
 }
 
-module.exports = { scan, services, expectedEnv, IGNORED, DEPTH, ENV_MAX }
+function workspaceRoots(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] }
+}
+
+// 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
+// comandos en el nivel de arriba, y dejarlo afuera hacía desaparecer justo al proyecto principal.
+function candidates(workspace, skip = '') {
+  const result = scan(workspace, skip)
+  const found = result.rootManifests.length
+    ? [{ path: '.', root: workspace, runtimes: ['raíz'], commands: result.rootCommands, env: result.rootEnv }]
+    : []
+  return [...found, ...result.services.map((service) => ({ ...service, root: workspace }))]
+}
+
+// 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.
+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) => ({
+    ...service,
+    path: service.path === '.' ? path.basename(workspace) : `${path.basename(workspace)}/${service.path}`,
+  })))
+}
+
+function commandsLine(commands) {
+  const entries = Object.entries(commands || {})
+  if (!entries.length) return ' — sin comandos declarados'
+  return ` — ${entries.map(([kind, value]) => `${kind}: ${value.command} (${value.source})`).join(', ')}`
+}
+
+// La guía de arranque: qué hay, qué falta y qué preguntar. Determinista y en milisegundos, porque es lo
+// primero que ve alguien que acaba de instalar y todavía no sabe qué hace la herramienta.
+module.exports = {
+  workspaceRoots,
+  candidates,
+  inventory,
+  commandsLine, scan, services, expectedEnv, IGNORED, DEPTH, ENV_MAX }

package/engine/{teams → flows}/registry.js

@@ -10,18 +10,18 @@ const PHASES = ['discovery', 'delivery']
 // lo aprendido. Sin declararlo, el workflow sólo sabría terminar de una forma.
 const OUTCOMES = ['epic', 'report']
 
-// El proyecto manda sobre el sistema: un team propio con el mismo slug reemplaza al de `system/`,
+// El proyecto manda sobre el sistema: un flow propio con el mismo slug reemplaza al de `system/`,
 // que se sigue actualizando debajo sin que nadie tenga que forkearlo.
 function systemTeams(root) {
-  return require('../core/ownership').packageDir(root, 'teams')
+  return require('../core/ownership').packageDir(root, 'flows')
 }
 
-function teamFile(root, slug) {
-  if (!SLUG.test(slug || '')) throw new Error(`team inválido: ${slug || '(vacío)'}`)
-  const own = path.join(root, 'teams', slug, 'team.json')
+function flowFile(root, slug) {
+  if (!SLUG.test(slug || '')) throw new Error(`flow inválido: ${slug || '(vacío)'}`)
+  const own = path.join(root, 'flows', slug, 'flow.json')
   if (fs.existsSync(own)) return own
   const system = systemTeams(root)
-  return system ? path.join(system, 'system', slug, 'team.json') : own
+  return system ? path.join(system, 'system', slug, 'flow.json') : own
 }
 
 // Devuelve el motivo real: "no existe" y "ambiguo" piden acciones distintas de quien lo lea.
@@ -32,11 +32,11 @@ function agentProblem(root, slug) {
 }
 
 function read(root, slug) {
-  const file = teamFile(root, slug)
-  if (!fs.existsSync(file)) throw new Error(`no existe teams/${slug}/team.json`)
+  const file = flowFile(root, slug)
+  if (!fs.existsSync(file)) throw new Error(`no existe flows/${slug}/flow.json`)
   let manifest
   try { manifest = JSON.parse(fs.readFileSync(file, 'utf8')) } catch (error) {
-    throw new Error(`teams/${slug}/team.json inválido: ${error.message}`)
+    throw new Error(`flows/${slug}/flow.json inválido: ${error.message}`)
   }
   return { file, manifest }
 }
@@ -86,9 +86,9 @@ function validate(root, slug) {
   if (!(manifest.stages || []).some((stage) => stage.phase === 'discovery')) {
     errors.push('falta al menos una etapa de discovery: un equipo sin descubrimiento no propone nada')
   }
-  // Junto al team.json que ganó la resolución, no en una ruta fija: el team puede venir de system/.
-  const workflow = path.join(path.dirname(teamFile(root, slug)), 'WORKFLOW.md')
-  if (!fs.existsSync(workflow)) errors.push('falta WORKFLOW.md')
+  // Junto al flow.json que ganó la resolución, no en una ruta fija: el flow puede venir de system/.
+  const workflow = path.join(path.dirname(flowFile(root, slug)), 'FLOW.md')
+  if (!fs.existsSync(workflow)) errors.push('falta FLOW.md')
   return { errors, stages: (manifest.stages || []).length, agents: agents.size, manifest }
 }
 
@@ -96,7 +96,7 @@ function slugsIn(dir) {
   try {
     return fs.readdirSync(dir, { withFileTypes: true })
       .filter((entry) => entry.isDirectory() && entry.name !== 'system')
-      .filter((entry) => fs.existsSync(path.join(dir, entry.name, 'team.json')))
+      .filter((entry) => fs.existsSync(path.join(dir, entry.name, 'flow.json')))
       .map((entry) => entry.name)
   } catch { return [] }
 }
@@ -106,7 +106,7 @@ function slugsIn(dir) {
 function list(root) {
   const system = systemTeams(root)
   const slugs = new Set([
-    ...slugsIn(path.join(root, 'teams')),
+    ...slugsIn(path.join(root, 'flows')),
     ...(system ? slugsIn(path.join(system, 'system')) : []),
   ])
   return [...slugs].sort()

package/engine/hooks/run.js

@@ -35,10 +35,10 @@ function fileOf(input) {
 // encabezado en vez de aceptar cualquier `command`, para no leer un comando de shell como si fuera
 // contenido de archivo.
 function patchOf(input) {
-  const campos = input.tool_input || {}
-  const command = String(campos.command || '')
-  const sobre = command.startsWith('*** Begin Patch') ? command : ''
-  return String(campos.patch || campos.input || input.patch || sobre || '')
+  const fields = input.tool_input || {}
+  const command = String(fields.command || '')
+  const envelope = command.startsWith('*** Begin Patch') ? command : ''
+  return String(fields.patch || fields.input || input.patch || envelope || '')
 }
 
 function filesOf(input) {
@@ -181,6 +181,51 @@ function generated(input) {
   }
 }
 
+// Las dos formas de que una prueba deje de juzgar sin que nadie lo note: apagarla o borrarla. Ninguna
+// sale roja —el runner informa una suite verde más corta—, así que el verde pasa de decir «el
+// comportamiento está» a decir «nadie lo miró», y `verify` tampoco lo ve porque también lee exit codes.
+// Lo que se inspecciona es el contenido entrante, no el archivo: una marca que ya estaba no la apagó
+// este cambio.
+const TEST_OFF = [
+  [/\b(?:describe|context|it|test|suite)\s*\.\s*(?:skip|only|todo)\b/, 'skip/only'],
+  [/\b[xf](?:it|test|describe|context)\s*[("'`]/, 'xit/fit'],
+  [/\bt\.Skip(?:Now)?\s*\(/, 't.Skip'],
+  [/@pytest\.mark\.(?:skip|skipif|xfail)\b/, 'pytest.mark.skip'],
+  [/@unittest\.skip/, 'unittest.skip'],
+  [/@(?:Ignore|Disabled)\b/, 'Ignore/Disabled'],
+  [/#\[ignore\]/, 'ignore'],
+]
+
+function isTestFile(raw) {
+  const file = raw.replace(/\\/g, '/')
+  const base = path.basename(file)
+  return /(?:^|\/)(?:tests?|specs?|__tests__)\//i.test(file)
+    || /\.(?:test|spec)\.[jt]sx?$/i.test(base)
+    || /_(?:test|spec)\.(?:go|py|rb|ts|js|jsx|tsx|rs|exs?)$/i.test(base)
+    || /^test_.+\.py$/i.test(base)
+}
+
+function testEvidence(input) {
+  if (process.env.OPS_TEST_EVIDENCE_OVERRIDE === '1') return
+  const why = 'Una prueba apagada no falla y una suite sin ella sale verde igual: el verde deja de ' +
+    'decir que el comportamiento está y pasa a decir que nadie lo miró.\n' +
+    'Si la aserción está mal, corregila; si el comportamiento cambió, cambialo junto con la prueba que ' +
+    'lo fija. Si tiene que quedar afuera igual —flake conocido, entorno que acá no existe—, es una ' +
+    'decisión con dueño: OPS_TEST_EVIDENCE_OVERRIDE=1 y que conste en el commit.'
+  for (const match of patchOf(input).matchAll(/^\*\*\* Delete File:\s*(.+)$/gm)) {
+    const removed = match[1].trim()
+    if (isTestFile(removed)) block(`${removed} borra una prueba.\n${why}`)
+  }
+  const content = contentOf(input)
+  if (!content) return
+  for (const raw of filesOf(input)) {
+    if (!isTestFile(raw)) continue
+    for (const [marca, nombre] of TEST_OFF) {
+      if (marca.test(content)) block(`${raw} apaga una prueba con ${nombre}.\n${why}`)
+    }
+  }
+}
+
 function workspaceBoundary(input) {
   const root = findOpsRoot(process.env.OPS_ROOT || process.env.CLAUDE_PROJECT_DIR || cwdOf(input))
   if (!root) return
@@ -413,14 +458,14 @@ function engineWrites(input) {
 const guards = {
   destructive, 'git-add': gitAdd, secrets, generated, 'workspace-boundary': workspaceBoundary,
   migrations, dependencies, governance, verify, 'planning-drift': planningDrift,
-  'integration-snapshot': integrationSnapshot, engine: engineWrites,
+  'integration-snapshot': integrationSnapshot, engine: engineWrites, 'test-evidence': testEvidence,
 }
 
 // Grupos por evento: un runner corre el grupo entero en un solo proceso en lugar de un guard por hook.
 const hookGroups = {
   'pre-shell': ['destructive', 'git-add', 'dependencies', 'governance', 'verify'],
   'pre-files': ['secrets', 'generated', 'workspace-boundary', 'engine', 'migrations',
-    'integration-snapshot'],
+    'integration-snapshot', 'test-evidence'],
   stop: ['planning-drift'],
 }
 
@@ -428,38 +473,63 @@ const hookMetadata = [
   {
     name: 'destructive',
     event: 'PreToolUse · shell',
-    purpose: 'Bloquea publicación y comandos con pérdida de datos.',
+    purpose: 'Bloquea publicación y comandos capaces de destruir datos o el working tree.',
+  },
+  {
+    name: 'git-add',
+    event: 'PreToolUse · shell',
+    purpose: 'Impide `git add .`, `-A` y `--all`; exige rutas explícitas.',
   },
-  { name: 'git-add', event: 'PreToolUse · shell', purpose: 'Exige stagear rutas explícitas.' },
   {
     name: 'dependencies',
     event: 'PreToolUse · shell',
-    purpose: 'Protege manifests, lockfiles y publicación de paquetes.',
+    purpose: 'Protege manifests y lockfiles; bloquea publicar e instalar global.',
   },
   {
     name: 'governance',
     event: 'PreToolUse · shell',
     purpose: 'Impide commitear cambios de gobernanza sin aprobación.',
   },
-  { name: 'verify', event: 'PreToolUse · shell', purpose: 'Ejecuta los gates reales antes de cada commit.' },
-  { name: 'secrets', event: 'PreToolUse · files', purpose: 'Bloquea escritura de secretos y credenciales.' },
+  {
+    name: 'verify',
+    event: 'PreToolUse · shell',
+    purpose: 'Ejecuta los gates del stack y comprueba drift generado antes de un commit.',
+  },
+  {
+    name: 'secrets',
+    event: 'PreToolUse · files',
+    purpose: 'Bloquea escribir secretos, claves privadas y credenciales en texto plano.',
+  },
   { name: 'generated', event: 'PreToolUse · files', purpose: 'Impide editar código generado manualmente.' },
-  { name: 'workspace-boundary', event: 'PreToolUse · files', purpose: 'Limita escrituras a las raíces declaradas.' },
+  {
+    name: 'workspace-boundary',
+    event: 'PreToolUse · files',
+    purpose: 'Limita escrituras a las raíces declaradas en ops.config.json.',
+  },
   {
     name: 'engine',
     event: 'PreToolUse · files',
-    purpose: 'Impide editar el motor instalado: se actualiza con npm.',
+    purpose: 'Impide editar el motor instalado por npm. Inerte en el propio toolkit.',
+  },
+  {
+    name: 'migrations',
+    event: 'PreToolUse · files',
+    purpose: 'Protege migraciones existentes y bloquea SQL destructivo sin override.',
   },
-  { name: 'migrations', event: 'PreToolUse · files', purpose: 'Protege migraciones existentes y SQL destructivo.' },
   {
     name: 'integration-snapshot',
     event: 'PreToolUse · files',
     purpose: 'Protege snapshots administrados por integraciones.',
   },
+  {
+    name: 'test-evidence',
+    event: 'PreToolUse · files',
+    purpose: 'Impide apagar o borrar la prueba que juzga el cambio.',
+  },
   {
     name: 'planning-drift',
     event: 'Stop / SessionEnd',
-    purpose: 'Evita cerrar con planning o integraciones desalineados.',
+    purpose: 'Evita cerrar una sesión con planning o integraciones desalineados.',
   },
 ]
 

package/engine/integrations/registry.js

@@ -381,7 +381,20 @@ const slugify = (value) => String(value).normalize('NFD').replace(/[\u0300-\u036
   .replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 70)
 const oneLine = (value) => String(value).replace(/\s+/g, ' ').trim()
 
+// En cuál de tres estados está el proveedor: `ready`, `incomplete` o `unreadable`. Lee su propio
+// `config.json`, que es donde vive la decisión, y no el registro: un proveedor listado y apagado no es
+// un proveedor disponible.
+function providerState(root, name) {
+  const configFile = path.join(root, 'integrations', name, 'config.json')
+  let raw
+  // Ausente y roto son distintos y decían lo mismo. Al que falta hay que completarlo; al que no parsea,
+  // mandarlo a completar manda a reescribir lo que ya estaba escrito, y el error queda sin nombrar.
+  try { raw = fs.readFileSync(configFile, 'utf8') } catch { return 'incomplete' }
+  try { return JSON.parse(raw).enabled === true ? 'ready' : 'incomplete' } catch { return 'unreadable' }
+}
+
 module.exports = {
+  providerState,
   STATES,
   adapter,
   frontmatter,

package/engine/integrations/state.js

@@ -3,6 +3,7 @@
 const crypto = require('node:crypto')
 const fs = require('node:fs')
 const path = require('node:path')
+const { frontmatter } = require('../core/frontmatter')
 const F = require('../core/files')
 
 const STATES = ['context', 'pending', 'ready', 'rejected', 'promoted']
@@ -28,16 +29,6 @@ const sha256 = (value) => {
   return crypto.createHash('sha256').update(String(value)).digest('hex')
 }
 
-function frontmatter(text) {
-  const block = (String(text).match(/^---\s*\n([\s\S]*?)\n---/) || [])[1] || ''
-  const values = {}
-  for (const line of block.split('\n')) {
-    const match = line.match(/^([A-Za-z][\w-]*):\s*(.*)$/)
-    if (match) values[match[1]] = match[2].trim().replace(/^['"]|['"]$/g, '')
-  }
-  return values
-}
-
 function replaceField(text, name, value) {
   const line = new RegExp(`^${name}:.*$`, 'm')
   return line.test(text) ? text.replace(line, `${name}: ${value}`) : text