@ingeniomaps/cauce 0.43.0 → 0.47.0

package/engine/cli/planning.js

@@ -0,0 +1,275 @@
+'use strict'
+
+// Los comandos que leen y validan un planning: qué está mal, qué hay, qué toca ahora y qué se archiva.
+// Los cuatro trabajan sobre el mismo estado, que `planning/state.js` compone una vez.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const P = require('../planning/parser')
+const B = require('../planning/business-rules')
+const PC = require('../planning/contracts')
+const ST = require('../planning/state')
+const I = require('../integrations/registry')
+const O = require('../core/ownership')
+const OB = require('../core/onboarding')
+const C = require('../config/validate')
+const AG = require('../agents/catalog')
+const F = require('../core/files')
+const { fail } = require('./io')
+
+// Qué dimensiones enumera el molde de `organization/` y cuáles dejaron de estar. Un agente que reescribe
+// esos archivos tiende a quedarse con el contenido y perder la estructura: el resultado se lee entero y
+// completo, y nadie va a pedir después la dimensión que falta porque nada indica que faltaba.
+//
+// Va como advertencia y no como error: la empresa es dueña de esos archivos y puede reestructurarlos a
+// propósito. Lo que no puede pasar es que una dimensión desaparezca sin que se vea.
+function check(dir, cli) {
+  const root = path.resolve(dir || '.')
+  const errors = []
+  const warnings = []
+  const required = ['BACKLOG.md', 'WIP.md', 'DONE.md', 'INBOX.md', 'HUMAN_ACTIONS.md', 'PROTOCOL.md']
+  for (const file of required) if (!fs.existsSync(path.join(root, file))) errors.push(`falta ${file}`)
+
+  const configPath = path.join(root, '..', 'ops.config.json')
+  if (fs.existsSync(configPath)) {
+    try {
+      const raw = fs.readFileSync(configPath, 'utf8')
+      const config = JSON.parse(raw)
+      if (!raw.includes('{{')) {
+        errors.push(...C.validateOpsConfig(config))
+        if (Array.isArray(config.workspaceRoots)) {
+          for (const workspace of config.workspaceRoots) {
+            if (workspace && workspace.name && workspace.path
+              && !fs.existsSync(path.resolve(path.dirname(configPath), workspace.path))) {
+              errors.push(`ops.config.json: no existe la raíz ${workspace.name} (${workspace.path})`)
+            }
+          }
+        }
+      }
+    } catch (error) {
+      errors.push(`ops.config.json: JSON inválido (${error.message})`)
+    }
+  } else {
+    warnings.push(`no existe ${path.relative(root, configPath)}`)
+  }
+
+  const epics = P.readEpics(root)
+  const milestones = P.readBacklog(root)
+  const done = P.readDone(root)
+  errors.push(...B.validate(path.join(root, 'business-rules')))
+  errors.push(...PC.validateRoadmapStructure(root))
+  errors.push(...PC.validateBacklogStructure(root))
+  errors.push(...PC.validateRules(root))
+  errors.push(...PC.validateAdr(root))
+  const backlog = milestones.flatMap((milestone) => milestone.tasks)
+  const backlogSlugs = new Set(backlog.map((task) => task.slug))
+  const epicNums = new Set()
+  const storySlugs = new Set()
+
+  const roles = new Set(AG.list(path.resolve(root, '..')).map((role) => role.slug))
+  const wip = P.readWip(root)
+  errors.push(...PC.oversizedUnits({ epics, milestones }))
+  errors.push(...PC.validateState({
+    epics, milestones, done, wip, roles, humanActions: P.readHumanActions(root),
+  }))
+
+  const integration = I.validate(path.resolve(root, '..'))
+  errors.push(...integration.errors)
+  warnings.push(...integration.warnings)
+
+  // Sobrescribir una entrada de system/ es legítimo y esperado; lo que no puede pasar es que
+  // ocurra en silencio, porque esa entrada deja de recibir las mejoras del toolkit.
+  for (const override of O.overrides(path.resolve(root, '..'))) {
+    warnings.push(`${override.collection}/${override.project} sobrescribe ${override.system} (override explícito)`)
+  }
+  // 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))
+
+  warnings.push(...OB.missingSections(path.resolve(root, '..')))
+  warnings.push(...OB.orphanCredentials(path.resolve(root, '..')))
+
+  if (cli.has('--json')) {
+    console.log(JSON.stringify({
+      ok: !errors.length,
+      epics: epics.length,
+      queued: backlog.length,
+      done: done.entries.length,
+      wip: wip ? wip.task : null,
+      errors,
+      warnings,
+    }))
+    if (errors.length) process.exit(1)
+    return
+  }
+
+  for (const warning of warnings) console.warn(`⚠ ${warning}`)
+  for (const error of errors) console.error(`✗ ${error}`)
+  if (errors.length) fail(`\n${errors.length} error(es), ${warnings.length} advertencia(s)`)
+  console.log(
+    `✓ planning válido: ${epics.length} épica(s), ${backlog.length} tarea(s) en cola, ` +
+      `${done.entries.length} terminada(s)`,
+  )
+}
+
+// Estado observable de planning sin mutar nada; base común de `tree` y de sus salidas.
+function treeJson({ epics, milestones, done, wip, inbox, queued }) {
+  const state = (slug) => done.set.has(slug) ? 'done' : queued.has(slug) ? 'queued' : 'pending'
+  console.log(JSON.stringify({
+    roadmap: epics.map((epic) => ({
+      num: epic.num,
+      title: epic.title,
+      status: epic.status,
+      stories: epic.stories.map((story) => ({ slug: story.slug, state: state(story.slug) })),
+    })),
+    backlog: milestones.map((milestone) => ({
+      slug: milestone.slug,
+      tasks: milestone.tasks.map((task) => ({ slug: task.slug, tier: task.tier || '' })),
+    })),
+    wip: wip ? { task: wip.task, phase: wip.phase, complete: wip.complete, pending: wip.pending } : null,
+    inbox: { deuda: inbox.deuda, ideas: inbox.ideas, propuestas: inbox.propuestas, lecciones: inbox.lecciones },
+    done: done.entries.length,
+  }))
+}
+
+function tree(dir, cli) {
+  const root = path.resolve(dir || '.')
+  const state = ST.snapshot(root)
+  if (cli.has('--json')) return treeJson(state)
+  const { epics, milestones, done, wip, inbox, queued } = state
+  const color = process.stdout.isTTY && !cli.has('--no-color')
+  const paint = (code, text) => color ? `\x1b[${code}m${text}\x1b[0m` : text
+  console.log(`\n${paint('1', 'CAUCE')}\n`)
+  console.log(paint('1', 'ROADMAP'))
+  if (!epics.length) console.log('  (sin épicas)')
+  for (const epic of epics) {
+    const mark = epic.status === 'closed' ? '✓' : epic.status === 'active' ? '◐' : '●'
+    console.log(`  ${mark} epic-${epic.num} ${epic.title} [${epic.status}]`)
+    for (const story of epic.stories) {
+      const mark = done.set.has(story.slug) ? '✓' : queued.has(story.slug) ? '▶' : '○'
+      console.log(`      ${mark} ${story.slug}`)
+    }
+  }
+  console.log(`\n${paint('1', 'BACKLOG')}`)
+  if (!milestones.length) console.log('  (sin hitos activos)')
+  for (const milestone of milestones) {
+    console.log(`  ${milestone.heading}`)
+    for (const task of milestone.tasks) console.log(`      ☐ ${task.slug}${task.tier ? ` [${task.tier}]` : ''}`)
+  }
+  const wipText = wip
+    ? `▶ ${wip.task} · ${wip.phase} · ${wip.complete}✓/${wip.pending}○`
+    : 'idle'
+  console.log(`\n${paint('1', 'WIP')}  ${wipText}`)
+  console.log(
+    `${paint('1', 'INBOX')}  ${inbox.deuda} deuda · ${inbox.ideas} ideas · ` +
+      `${inbox.propuestas} propuestas · ${inbox.lecciones} lecciones` +
+      // Sin esto, doce viñetas sin nombre se veían como un inbox vacío y nadie se enteraba.
+      (inbox.skipped ? `  (${inbox.skipped} sin contar: falta el nombre en **negrita**)` : ''),
+  )
+  console.log(`${paint('1', 'DONE')}   ${done.entries.length} tareas\n`)
+}
+
+// Contexto mínimo suficiente para ejecutar una tarea, en lugar de releer roadmap, BACKLOG y WIP enteros.
+function context(dir, cli) {
+  const root = path.resolve(dir || '.')
+  const state = ST.snapshot(root)
+  const gate = path.join(root, 'AWAITING_REVIEW.md')
+  const humanActions = ST.pendingHumanActions(root)
+  const { task, skipped } = ST.currentTask(state, humanActions)
+  const epic = task ? state.epics.find((candidate) => candidate.num === task.epic) : null
+  const criteria = epic ? epic.criteria.filter((criterion) => task.criteria.includes(criterion.id)) : []
+  const report = {
+    // Toda la cola trabada por una persona no es lo mismo que no tener cola, y decir lo segundo manda a
+    // buscar trabajo que no existe en vez de a resolver la fila que lo destraba.
+    blocked: fs.existsSync(gate) ? 'awaiting-review' : (!task && skipped.length ? 'blocked-on-human' : ''),
+    task: task && {
+      slug: task.slug, hito: task.hito, tier: task.tier, cast: task.cast, service: task.service,
+      // Una tarea puede heredar su aceptación del criterio citado; el runner necesita el texto, no la cita.
+      acceptance: task.acceptance || criteria.map((criterion) => criterion.text).join(' '),
+      epic: task.epic,
+    },
+    criteria,
+    epic: epic ? { num: epic.num, title: epic.title, status: epic.status } : null,
+    wip: state.wip ? { phase: state.wip.phase, complete: state.wip.complete, pending: state.wip.pending } : null,
+    queued: state.milestones.reduce((total, milestone) => total + milestone.tasks.length, 0),
+    blockedTasks: skipped,
+    humanActions,
+  }
+  if (cli.has('--json')) return console.log(JSON.stringify(report))
+
+  if (report.blocked === 'awaiting-review') {
+    const first = P.read(gate).split('\n').find((line) => line.trim() && !line.startsWith('#')) || ''
+    return console.log(`BLOCKED  awaiting-review — ${first.trim()}`)
+  }
+  if (report.blocked === 'blocked-on-human') {
+    const row = humanActions.find((action) => skipped.includes(action.task)) || humanActions[0]
+    return console.log(`BLOCKED  blocked-on-human — ${row.task}: ${row.action}`)
+  }
+  if (!report.task) return console.log('TASK   (sin tarea disponible)')
+  console.log(`TASK   ${report.task.slug}${report.task.tier ? ` [${report.task.tier}]` : ''}` +
+    `${report.task.service ? `  service: ${report.task.service}` : ''}` +
+    `${report.task.hito ? `  hito: ${report.task.hito}` : ''}`)
+  if (report.task.cast.build) {
+    const review = report.task.cast.review
+    console.log(`CAST   ${report.task.cast.build}${review.length ? ` → ${review.join(', ')}` : ''}`)
+  }
+  if (report.epic) console.log(`EPIC   ${report.epic.num} ${report.epic.title} [${report.epic.status}]`)
+  if (report.task.acceptance) console.log(`ACEPT  ${report.task.acceptance}`)
+  for (const criterion of criteria) console.log(`${criterion.id.padEnd(6)} ${criterion.text}`)
+  const wip = report.wip ? `${report.wip.phase} · ${report.wip.complete}✓/${report.wip.pending}○` : 'idle'
+  console.log(`WIP    ${wip}`)
+  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}`)
+}
+
+// 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—.
+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`)
+}
+
+function archive(dir, rawNum) {
+  const root = path.resolve(dir || '.')
+  if (String(rawNum || '') === 'human-actions') return archiveHumanActions(root)
+  const num = String(rawNum || '').padStart(3, '0')
+  if (!/^\d{3}$/.test(num)) fail('La épica debe ser NNN, o human-actions.', 2)
+  const epic = P.readEpics(root).find((candidate) => candidate.num === num)
+  if (!epic) fail(`No existe epic-${num}.`, 2)
+  if (epic.status !== 'closed') fail(`epic-${num} no está cerrada (status: ${epic.status}).`)
+  const target = path.join(root, 'done', `epic-${num}.md`)
+  const source = path.join(root, 'DONE.md')
+  const content = P.read(source)
+  const slugs = new Set(epic.stories.map((story) => story.slug))
+  const entries = P.readDone(root).entries.filter((entry) => entry.source === 'DONE.md' && slugs.has(entry.slug))
+  if (!entries.length) {
+    if (fs.existsSync(target)) return console.log(`= epic-${num} ya estaba archivada`)
+    fail(`No hay entradas de epic-${num} en DONE.md.`)
+  }
+  let updated = content
+  for (const entry of entries) updated = updated.replace(entry.raw, '').replace(/\n{3,}/g, '\n\n')
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  if (!fs.existsSync(target)) {
+    F.atomicWrite(
+      target,
+      `---\nepic: ${num}\nstatus: archived\n---\n\n# DONE — ${epic.title}\n\n` +
+        `${entries.map((entry) => entry.raw).join('\n\n')}\n`,
+    )
+  }
+  F.atomicWrite(source, `${updated.trimEnd()}\n`)
+  console.log(`✓ epic-${num}: ${entries.length} entrada(s) archivadas`)
+}
+
+module.exports = { check, tree, context, archive }

package/engine/cli/wiring.js

@@ -0,0 +1,273 @@
+'use strict'
+
+// Lo que conecta la instancia con el afuera: qué hay en el workspace, qué falta para arrancar, los
+// proveedores externos y el wiring del runner. Ninguno decide sobre planning; los cuatro escriben o leen
+// configuración de borde.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const F = require('../core/files')
+const I = require('../integrations/registry')
+const A = require('../automation')
+const SC = require('../core/scan')
+const OB = require('../core/onboarding')
+const IN = require('./instance')
+const { fail, opsRoot } = require('./io')
+
+const MAX_LISTED = 20
+
+
+const INTEGRATION = {
+  list: {
+    run: (root) => {
+      for (const [name, entry] of Object.entries(providerRegistry(root).config.providers || {})) {
+        const state = I.providerState(root, name)
+        const mark = !entry.enabled ? '○' : { ready: '●', incomplete: '◐', unreadable: '⚠' }[state]
+        const note = mark === '◐'
+          ? `  — falta completar integrations/${name}/config.json y poner enabled: true`
+          : mark === '⚠'
+            ? `  — integrations/${name}/config.json no se puede leer: "integration check" dice por qué`
+            : ''
+        console.log(`${mark} ${name} [${entry.adapter}]${note}`)
+      }
+    },
+  },
+  enable: {
+    missing: 'Falta <provider>.',
+    run: (root, provider) => {
+      const source = path.join(IN.PROJECT_ROOT, 'template', 'integrations', provider)
+      if (!fs.existsSync(source)) fail(`Cauce no trae un adaptador para ${provider}.`, 2)
+      // Habilitar no es inicializar: repone lo que falte y conserva lo que ya esté. Una instancia que
+      // trae el andamiaje de una versión anterior —o que ya tiene snapshots— sólo quiere el interruptor.
+      providerRegistry(root)
+      IN.copyTemplate(source, path.join(root, 'integrations', provider), {}, true)
+      switchProvider(root, provider, true)
+      console.log(`✓ ${provider}: conectado al proyecto y andamiaje en integrations/${provider}/.`)
+      // Sólo se pide lo que falta: reencender un proveedor ya configurado no debería mandar a
+      // completar un archivo que la empresa terminó hace meses.
+      const state = I.providerState(root, provider)
+      if (state === 'ready') {
+        console.log(`  Su configuración ya estaba completa: "integration sync" puede correr.`)
+        return
+      }
+      if (state === 'unreadable') {
+        console.log(`  Su configuración existe y no se puede leer: "integration check" dice por qué.`)
+        return
+      }
+      console.log(`  Falta lo tuyo: completá integrations/${provider}/config.json y poné enabled: true ahí.`)
+      console.log(`  Hasta entonces "integration sync" se niega, que es lo correcto: no hay a dónde apuntar.`)
+    },
+  },
+  // Apagar no desinstala: `integrations/<proveedor>/` puede tener snapshots y borradores de la
+  // empresa, y borrarlos para desconectar una integración sería perder trabajo suyo. El andamiaje
+  // queda, callado, y volver a encenderlo no pierde nada.
+  disable: {
+    missing: 'Falta <provider>.',
+    run: (root, provider) => {
+      switchProvider(root, provider, false)
+      console.log(`✓ ${provider}: desconectado del proyecto. "integration sync" deja de correrlo.`)
+      if (fs.existsSync(path.join(root, 'integrations', provider))) {
+        console.log(`  integrations/${provider}/ queda como está: ahí pueden vivir snapshots y borradores tuyos.`)
+      }
+    },
+  },
+  check: {
+    run: (root, provider) => {
+      const result = I.validate(root, provider || '')
+      for (const warning of result.warnings) console.warn(`⚠ ${warning}`)
+      for (const error of result.errors) console.error(`✗ ${error}`)
+      if (result.errors.length) fail(`${result.errors.length} error(es) de integración`)
+      console.log(`✓ integraciones válidas${provider ? `: ${provider}` : ''}`)
+    },
+  },
+  sync: {
+    missing: 'sync exige <provider>',
+    run: async (root, provider, key, cli) => {
+      const result = await I.sync(root, provider, { fixture: cli.value('--fixture') })
+      console.log(
+        `✓ ${provider}: ${result.total} items · ${result.created} nuevos · ` +
+          `${result.refreshed} refrescados · ${result.preserved} curados preservados`,
+      )
+      // Lo que el remoto dejó de tener sí cambia el staging, y se contaba sin decirlo: un item que
+      // desaparece se borra o queda marcado según tenga curación. Se nombra sólo cuando pasó, porque
+      // en la corrida normal los dos son cero y anunciarlo cada vez es ruido.
+      if (result.removed) console.log(`  − ${result.removed} sin curar se fueron del remoto y se borraron`)
+      if (result.missing) {
+        console.log(`  ⚠ ${result.missing} con curación ya no están en el remoto: quedan marcados`)
+      }
+    },
+  },
+  promote: {
+    missing: 'promote exige <provider> <remote-key>',
+    needsKey: true,
+    run: (root, provider, key) => {
+      const result = I.promote(root, provider, key)
+      console.log(`✓ ${provider}:${result.key} promovido como ${result.kind}`)
+    },
+  },
+  'writeback-plan': {
+    missing: 'writeback-plan exige <provider>',
+    run: (root, provider) => console.log(JSON.stringify(I.writebackPlan(root, provider), null, 2)),
+  },
+}
+
+// Dónde puede mirar una instancia: exactamente las raíces que declara, y nada por encima de ellas. 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.
+// Las tres reconciliaciones son el mismo comando con otra operación: se declaran en el mismo lugar
+// para que agregar una cuarta no pida tocar el despachador.
+for (const operation of ['reset', 'rebase', 'reconcile']) {
+  INTEGRATION[operation] = {
+    missing: `${operation} exige <provider> <remote-key>`,
+    needsKey: true,
+    run: (root, provider, key) => {
+      const changed = I.reconcile(root, provider, operation, [key])
+      console.log(`✓ ${provider}: ${operation} aplicado a ${changed.join(', ')}`)
+    },
+  }
+}
+
+function scan(target, cli) {
+  const root = path.resolve(target || '.')
+  const result = { root, services: target ? SC.candidates(root) : SC.inventory(root) }
+  if (cli.has('--json')) return console.log(JSON.stringify(result, null, 2))
+  // Un monorepo de sesenta paquetes no se lee en pantalla. Se recorta, y se dice cuánto: un corte que no
+  // se anuncia hace pasar lo listado por todo lo que hay.
+  for (const service of result.services.slice(0, MAX_LISTED)) {
+    // El proyecto que vive en la raíz se nombra por su carpeta: `.` a secas no dice de cuál se habla.
+    const label = service.path === '.' ? `. (${path.basename(service.root || result.root)})` : service.path
+    const expects = service.env ? `\n    espera ${service.env.names.join(', ')} (${service.env.file})` : ''
+    console.log(
+      `${label} [${(service.runtimes || []).join(', ')}]${SC.commandsLine(service.commands)}${expects}`,
+    )
+  }
+  if (result.services.length > MAX_LISTED) {
+    console.log(`… y ${result.services.length - MAX_LISTED} más, todos en --json`)
+  }
+  console.log(`${result.services.length} candidato(s). Cuál es el producto y cuál quedó muerto lo ` +
+    'decide una persona.')
+}
+
+// Sólo lo declarado y de dónde salió: un comando inventado se lee igual que uno real.
+function onboard(rootArg, cli, runner = '') {
+  const root = path.resolve(rootArg || '.')
+  const services = SC.inventory(root)
+  const state = OB.guide(root, services)
+  if (cli.has('--json')) {
+    return console.log(JSON.stringify({ ...state, roots: SC.workspaceRoots(root), servicios: services }, null, 2))
+  }
+  // La pregunta primero, y el inventario después: de qué trata el proyecto es lo mismo esté vacío,
+  // sea un monorepo o sean diez repos, y empezar por lo que se encontró invierte de qué se trata esto.
+  if (state.fresh) {
+    console.log(`${state.opening}\n`)
+    console.log(`Según lo que contestes salen hasta ${state.followUps} preguntas más, con las palabras de`)
+    console.log('este proyecto, hasta cubrir lo que haga falta de esto:\n')
+    for (const dimension of state.dimensions) console.log(`  · ${dimension.need}`)
+    console.log('')
+  }
+  const listed = services.slice(0, MAX_LISTED).map((service) => service.path).join(', ')
+  const more = services.length > MAX_LISTED ? ` y ${services.length - MAX_LISTED} más` : ''
+  console.log(services.length
+    ? `Mientras tanto, esto es lo que hay: ${listed}${more}`
+    : 'Mientras tanto, en el workspace todavía no hay ningún proyecto.')
+  if (!state.fresh) {
+    const parts = [state.written.organization && 'organization/', state.written.roadmap && 'el roadmap']
+      .filter(Boolean).join(' y ')
+    console.log(`Esta instancia ya tiene ${parts} escrito: el arranque no la va a pisar.`)
+    return
+  }
+  // Un solo cierre: tres líneas que suenan a final se leen como tres finales, y quien recién instaló
+  // termina sin saber cuál era el paso.
+  console.log(runner
+    ? `\n→ Abrí ${runner} acá y contestale esa pregunta.`
+    : '\n→ Contestá esa pregunta cuando corras el arranque.')
+  console.log('  Con tus respuestas escribe organization/, el mapa real de AGENTS.md y la primera épica.')
+}
+
+// El registro de proveedores, leído igual por todos los que lo tocan. `list` lo parseaba suelto y un
+// archivo roto salía como un error de JSON sin contexto.
+function providerRegistry(root) {
+  const file = path.join(root, 'integrations', 'config.json')
+  try { return { file, config: JSON.parse(fs.readFileSync(file, 'utf8')) } } catch (error) {
+    return fail(`integrations/config.json ilegible: ${error.message}`)
+  }
+}
+
+function switchProvider(root, provider, enabled) {
+  const { file, config } = providerRegistry(root)
+  if (!config.providers || !config.providers[provider]) {
+    fail(`${provider} no está en integrations/config.json.`)
+  }
+  config.providers[provider].enabled = enabled
+  F.atomicWriteJson(file, config)
+}
+
+async function integration(action, rootArg, provider, key, cli) {
+  const step = INTEGRATION[action]
+  if (!step) fail(`Acción de integración desconocida: ${action || '(vacía)'}`, 2)
+  if (step.missing && (!provider || (step.needsKey && !key))) fail(step.missing, 2)
+  await step.run(path.resolve(rootArg || '.'), provider, key, cli)
+}
+
+function automation(action, rootArg, runnerName, cli) {
+  const root = opsRoot(rootArg)
+  if (action === 'list-hooks') return A.listHooks()
+  if (action === 'list') {
+    for (const name of A.RUNNER_NAMES) {
+      const runner = A.runnerManifest(root, name)
+      const installed = fs.existsSync(path.join(root, runner.config.target))
+      const capabilities = Object.entries(runner.capabilities)
+        .filter(([, enabled]) => enabled)
+        .map(([capability]) => capability)
+        .join(', ')
+      console.log(`${installed ? '●' : '○'} ${name}${installed ? ' [instalado]' : ''} · ${capabilities}`)
+    }
+    return
+  }
+  if (action === 'check') {
+    const errors = A.check(root)
+    for (const error of errors) console.error(`✗ ${error}`)
+    if (errors.length) fail(`${errors.length} error(es) de automatización`)
+    console.log(
+      `✓ automatización válida: ${A.GUARD_NAMES.length} guards, ${A.RUNNER_NAMES.length} adaptadores`,
+    )
+    return
+  }
+  if (action === 'doctor') {
+    let result
+    try { result = A.doctor(root, runnerName) } catch (error) { fail(error.message, 2) }
+    if (result.errors.length) {
+      fail(`${runnerName}: ${result.errors.length} error(es), ${result.warnings.length} advertencia(s)`)
+    }
+    console.log(`✓ ${runnerName}: adaptador operativo (${result.warnings.length} advertencia(s))`)
+    return
+  }
+  if (action === 'uninstall') {
+    try { A.uninstall(root, runnerName, console) } catch (error) { fail(error.message, 2) }
+    console.log('  la instancia sigue en pie: borrar la carpeta ops es una decisión aparte.')
+    return
+  }
+  if (action === 'install') {
+    let runner
+    const force = cli.has('--force')
+    try { runner = A.install(root, runnerName, console, { force }) } catch (error) { fail(error.message, 2) }
+    if (runnerName === 'codex') {
+      console.log('  Codex deja los hooks nuevos sin correr hasta que los confíes: abrí una sesión')
+      console.log('  y usá /hooks para revisarlos y marcarlos como confiables.')
+    }
+    if (!runner.capabilities.nativeHooks) {
+      console.log(`  ${runnerName} no expone hooks nativos; aplica guards como prechecks.`)
+    }
+    const result = A.doctor(root, runnerName)
+    if (result.errors.length) fail(`${runnerName}: instalación incompleta`)
+    console.log(`✓ ${runnerName}: adaptador operativo (${result.warnings.length} advertencia(s))`)
+    return
+  }
+  fail(`Acción de automatización desconocida: ${action || '(vacía)'}`, 2)
+}
+
+// `init` enciende un proveedor en la misma corrida en que crea la instancia, y ésta es la operación
+// que lo hace: se expone para que la composición no tenga que conocer la tabla entera.
+const enableProvider = (root, provider) => INTEGRATION.enable.run(root, provider)
+
+module.exports = { scan, onboard, integration, automation, enableProvider }

package/engine/core/frontmatter.js

@@ -0,0 +1,21 @@
+'use strict'
+
+// El bloque `---` del encabezado de un markdown, leído una sola vez. Estaba implementado en `planning` y
+// en `integrations` con dos comportamientos distintos: uno aceptaba el bloque en cualquier parte del
+// archivo y el otro sólo al principio; uno admitía claves con dígito inicial y el otro no. Un mismo
+// draft se leía distinto según quién lo abriera.
+//
+// Se resuelve por el lado estricto: frontmatter es lo que encabeza el documento, y un `---` en el medio
+// es una línea horizontal de markdown. La clave admite lo que admite YAML.
+
+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(/^([\w-]+):\s*(.*)$/)
+    if (match) values[match[1]] = match[2].trim().replace(/^['"]|['"]$/g, '')
+  }
+  return values
+}
+
+module.exports = { frontmatter }

package/engine/core/manifest.js

@@ -11,6 +11,8 @@ const crypto = require('node:crypto')
 const fs = require('node:fs')
 const path = require('node:path')
 
+const { atomicWriteJson } = require('./files')
+
 const FILE = path.join('.cauce', 'manifest.json')
 
 function digestText(content) {
@@ -21,18 +23,28 @@ function digest(file) {
   try { return digestText(fs.readFileSync(file)) } catch { return '' }
 }
 
+const EMPTY = () => ({ files: {}, runners: {}, forks: {} })
+
 // Dos secciones porque son dos entregas distintas: `files` es lo que se materializó dentro de la
 // instancia y `runners` lo que un adaptador dejó fuera de ella —en modo sidecar el wiring vive en
 // la carpeta de la compañía—. El registro se queda igual acá, que es el repo que la empresa versiona.
 function readAll(root) {
-  try {
-    const data = JSON.parse(fs.readFileSync(path.join(root, FILE), 'utf8')) || {}
-    return {
-      files: typeof data.files === 'object' && data.files ? data.files : {},
-      runners: typeof data.runners === 'object' && data.runners ? data.runners : {},
-      forks: typeof data.forks === 'object' && data.forks ? data.forks : {},
-    }
-  } catch { return { files: {}, runners: {}, forks: {} } }
+  let raw
+  // Ausente e ilegible se leían los dos como vacío, y no son lo mismo. Ausente es legítimo: una
+  // instancia recién creada, o anterior a que existiera el registro. Ilegible no, porque vacío afirma
+  // que la empresa no editó nada —la lectura más destructiva posible de este archivo en particular—:
+  // `upgrade` dejaba de reconocer lo suyo y lo pisaba en silencio, saliendo 0. Sin poder leerlo no hay
+  // decisión que tomar, y detenerse es lo único que no pierde trabajo ajeno.
+  try { raw = fs.readFileSync(path.join(root, FILE), 'utf8') } catch { return EMPTY() }
+  let data
+  try { data = JSON.parse(raw) || {} } catch (error) {
+    throw new Error(`${FILE}: no se puede leer (${error.message}). Restauralo desde el control de versiones.`)
+  }
+  return {
+    files: typeof data.files === 'object' && data.files ? data.files : {},
+    runners: typeof data.runners === 'object' && data.runners ? data.runners : {},
+    forks: typeof data.forks === 'object' && data.forks ? data.forks : {},
+  }
 }
 
 function read(root) { return readAll(root).files }
@@ -50,7 +62,6 @@ function readForks(root) { return readAll(root).forks }
 function write(root, files, runners, forks) {
   const current = readAll(root)
   const target = path.join(root, FILE)
-  fs.mkdirSync(path.dirname(target), { recursive: true })
   const ordered = (map) => Object.fromEntries(
     Object.entries(map).sort(([left], [right]) => left.localeCompare(right)),
   )
@@ -60,7 +71,9 @@ function write(root, files, runners, forks) {
     runners: ordered(runners || current.runners),
     forks: ordered(forks || current.forks),
   }
-  fs.writeFileSync(target, `${JSON.stringify(data, null, 2)}\n`)
+  // Atómico porque un truncado acá deja la instancia sin el registro que separa lo suyo de lo
+  // nuestro, y desde que leerlo vacío dejó de ser una opción eso bloquea el upgrade siguiente.
+  atomicWriteJson(target, data)
 }
 
 // Registra lo entregado en una ruta, relativo a la raíz de la instancia. Acumula sobre lo que recibe