@ingeniomaps/cauce 0.22.0 → 0.23.0

package/engine/cli/ops.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 'use strict'
 
-const fs = require('fs')
-const path = require('path')
-const { spawnSync } = require('child_process')
+const fs = require('node:fs')
+const path = require('node:path')
+const { spawnSync } = require('node:child_process')
 const P = require('../planning/parser')
 const B = require('../planning/business-rules')
 const PC = require('../planning/contracts')
@@ -18,6 +18,7 @@ const C = require('../config/validate')
 const T = require('../teams/registry')
 const AG = require('../agents/catalog')
 const EV = require('../agents/evaluations')
+const { FLAGS, parse } = require('./args')
 
 const PROJECT_ROOT = path.resolve(__dirname, '..', '..')
 
@@ -49,7 +50,7 @@ function usage() {
   ops automation check <ops-root>
   ops automation doctor <ops-root> claude|codex|gemini|antigravity
   ops automation install <ops-root> claude|codex|gemini|antigravity
-  ops learn <agent> [--proposal]
+  ops learn <agent> [--proposal] [--applied [--period <AAAA-MM>]]
   ops evaluate <agent> [--cases [--json]] [--bench [caso]]
   ops agents list [ops-root] [--own|--system] [--json]
   ops agents fork <cargo> [ops-root]
@@ -58,28 +59,6 @@ function usage() {
   ops team show <team>`)
 }
 
-// Banderas que consumen el argumento siguiente: su valor no es un posicional.
-const VALUED_FLAGS = new Set(['--name', '--mode', '--fixture'])
-
-// Los posicionales del comando, salteando banderas y sus valores. Leer `process.argv` crudo hacía
-// que `agents list --json` tomara `--json` como la raíz: el catálogo salía vacío, sin error, y quien
-// lo consumía —un agente, por ejemplo— no tenía cómo notar que le habían contestado con nada.
-function positionals() {
-  const found = []
-  const argv = process.argv.slice(2)
-  for (let index = 0; index < argv.length; index += 1) {
-    const value = argv[index]
-    if (!value.startsWith('--')) { found.push(value); continue }
-    if (VALUED_FLAGS.has(value)) index += 1
-  }
-  return found
-}
-
-function option(name, fallback = '') {
-  const index = process.argv.indexOf(name)
-  return index >= 0 ? process.argv[index + 1] || fallback : fallback
-}
-
 function copyTemplate(source, target, replacements, force, skip = [], quiet = false) {
   F.assertNoSymlinkPath(path.dirname(target), target)
   fs.mkdirSync(target, { recursive: true })
@@ -134,9 +113,9 @@ function declareEngine(manifest, version) {
   F.atomicWriteJson(manifest, pkg)
 }
 
-// Proveedores que el toolkit conoce. El andamiaje de cada uno —configuración, staging/, proposed/—
-// no se materializa hasta que alguien lo habilite: hoy una instancia recibe 32 KB de un proveedor
-// apagado que quizá no use nunca, y que nadie actualiza después.
+// Proveedores que el toolkit conoce, para saltearlos al copiar la plantilla: su andamiaje
+// —configuración, staging/, proposed/— no se materializa hasta que alguien lo habilite. Antes cada
+// instancia recibía el de un proveedor apagado que quizá no usaba nunca, y que nadie actualizaba.
 function providerNames() {
   try {
     const file = path.join(PROJECT_ROOT, 'template', 'integrations', 'config.json')
@@ -187,22 +166,17 @@ function scaffold(root, { name, mode, force = false, quiet = false }) {
 
 // Un banco de trabajo desechable donde un cargo del catálogo puede realmente trabajar.
 //
-// Hace falta porque el toolkit no es una raíz ops: no tiene `planning/`, y no puede tenerlo —el único
-// `planning/` que vive acá es `template/planning`, el molde que se distribuye—. Un cargo cuya entrega
-// es una épica o una entrada de INBOX no tiene dónde escribir, así que se niega. Con razón, y su caso
-// lo cuenta como fallo: eso midió una configuración, no al cargo.
+// Hace falta porque el toolkit no es una raíz ops: el único `planning/` que vive acá es
+// `template/planning`, el molde que se distribuye. Un cargo cuya entrega es una épica no tiene dónde
+// escribir, así que se niega —con razón—, y su caso cuenta como fallo: eso midió una configuración.
 //
-// **Uno por caso**, y esto se aprendió corriendo. Con un banco compartido, los cinco casos de un
-// cargo corren a la vez sobre el mismo `planning/` y se leen entre sí: un caso tomó por «una sesión
-// anterior de este mismo cargo» lo que otro acababa de escribir, y otro evaluó cuatro candidatas que
-// en su enunciado no existían. Ninguno de los dos cambió de veredicto, pero las respuestas ya no eran
-// las que el caso pedía medir. La independencia entre casos es la premisa de medir con ellos.
+// Uno por caso, y se aprendió corriendo: con un banco compartido los casos se leen entre sí, y uno
+// tomó por «una sesión anterior de este mismo cargo» lo que otro acababa de escribir. La
+// independencia entre casos es la premisa de medir con ellos.
 //
-// Se recrea entero en cada corrida. Reutilizarlo dejaría que lo que un cargo escribió el lunes sea
-// contexto del que responde el martes, y dos corridas del mismo caso dejarían de ser comparables.
-// Queda en disco al terminar, gitignorado, porque después de un veredicto raro lo primero que uno
-// quiere es mirar qué escribió el cargo.
-function evaluationBench(root, agent, caso) {
+// Se recrea entero en cada corrida —si no, lo que escribió el lunes es contexto del martes— y queda
+// en disco, gitignorado: después de un veredicto raro uno quiere mirar qué escribió el cargo.
+function evaluationBench(root, agent, caso, force) {
   const safe = (value) => {
     if (!/^[a-z0-9_][a-z0-9._-]*$/i.test(value) || value.includes('..')) {
       fail(`nombre inválido para el banco: ${value}`, 2)
@@ -216,7 +190,7 @@ function evaluationBench(root, agent, caso) {
   // respuesta afirmaba algo inexistente. Con el banco versionado, «acá se trabajó» es una pregunta que
   // git contesta exacto.
   const sucio = spawnSync('git', ['-C', dir, 'status', '--porcelain'], { encoding: 'utf8' })
-  if ((sucio.stdout || '').trim() && !process.argv.includes('--force')) {
+  if ((sucio.stdout || '').trim() && !force) {
     fail(`${dir} tiene trabajo sin recoger. Guardá el registro de esa corrida antes de rehacerlo, `
       + 'o usá --force si ya lo tenés.', 2)
   }
@@ -228,14 +202,18 @@ function evaluationBench(root, agent, caso) {
   fs.mkdirSync(scope, { recursive: true })
   fs.symlinkSync(PROJECT_ROOT, path.join(scope, 'cauce'), 'dir')
 
-  // El banco queda versionado desde su estado limpio, y eso resuelve un problema de medición: la
-  // entrega de un cargo puede no estar en su respuesta. `backend-engineer` contestó un resumen del
-  // webhook y escribió el contrato —firma, orden de verificación, ventana antirreplay, catorce
-  // pruebas— en su `INBOX.md`. El juez, que sólo leía la respuesta, lo dio por ausente y lo reprobó.
-  //
-  // Con el banco versionado, `git status` y `git diff` muestran exactamente qué produjo, separado del
-  // andamiaje. Es la diferencia entre juzgar el resumen y juzgar la entrega. Se ignora `node_modules`
-  // porque es un symlink al toolkit y no es obra del cargo.
+  // 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`
+  // se lo atribuiría al cargo y el juez leería como obra suya el documento que vino a resistir.
+  if (caso) {
+    const artefacto = EV.fixtures(root, agent, caso)
+    if (artefacto.files.length) fs.cpSync(artefacto.dir, dir, { recursive: true })
+  }
+
+  // Versionado desde su estado limpio porque la entrega de un cargo puede no estar en su respuesta:
+  // uno contestó un resumen y escribió el contrato entero en su `INBOX.md`, y el juez —que sólo leía
+  // la respuesta— lo dio por ausente. Con git, `status` y `diff` muestran qué produjo, separado del
+  // andamiaje. Se ignora `node_modules`: es un symlink al toolkit, no obra del cargo.
   const git = (...args) => spawnSync('git', ['-C', dir, ...args], { stdio: 'ignore' })
   fs.appendFileSync(path.join(dir, '.gitignore'), '\nnode_modules/\n')
   git('init', '-q')
@@ -246,13 +224,13 @@ function evaluationBench(root, agent, caso) {
   return dir
 }
 
-function init(target) {
+function init(target, cli) {
   if (!target) fail('Falta <destino>.', 2)
-  const mode = option('--mode', 'embedded')
+  const mode = cli.value('--mode', 'embedded')
   if (!['embedded', 'sidecar'].includes(mode)) fail('--mode debe ser embedded o sidecar.', 2)
-  const name = option('--name', path.basename(path.resolve(target)).replace(/-ops$/, ''))
+  const name = cli.value('--name', path.basename(path.resolve(target)).replace(/-ops$/, ''))
   const root = path.resolve(target)
-  const force = process.argv.includes('--force')
+  const force = cli.has('--force')
   const existing = fs.existsSync(root) ? fs.readdirSync(root) : []
   if (existing.length && !force) {
     fail(`El destino no está vacío: ${root}. Usa --force para agregar solo archivos faltantes.`)
@@ -263,7 +241,7 @@ function init(target) {
   console.log(`  siguiente: node ${path.join(root, 'tools', 'ops.js')} check ${path.join(root, 'planning')}`)
 }
 
-function check(dir) {
+function check(dir, cli) {
   const root = path.resolve(dir || '.')
   const errors = []
   const warnings = []
@@ -375,7 +353,7 @@ function check(dir) {
   const FK = require('../agents/fork')
   for (const entry of FK.drift(path.resolve(root, '..'))) warnings.push(FK.driftLine(entry))
 
-  if (process.argv.includes('--json')) {
+  if (cli.has('--json')) {
     console.log(JSON.stringify({
       ok: !errors.length,
       epics: epics.length,
@@ -430,12 +408,12 @@ function treeJson({ epics, milestones, done, wip, inbox, queued }) {
   }))
 }
 
-function tree(dir) {
+function tree(dir, cli) {
   const root = path.resolve(dir || '.')
   const state = snapshot(root)
-  if (process.argv.includes('--json')) return treeJson(state)
+  if (cli.has('--json')) return treeJson(state)
   const { epics, milestones, done, wip, inbox, queued } = state
-  const color = process.stdout.isTTY && !process.argv.includes('--no-color')
+  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'))
@@ -494,7 +472,7 @@ function currentTask({ milestones, done, wip }, blockers = []) {
 }
 
 // Contexto mínimo suficiente para ejecutar una tarea, en lugar de releer roadmap, BACKLOG y WIP enteros.
-function context(dir) {
+function context(dir, cli) {
   const root = path.resolve(dir || '.')
   const state = snapshot(root)
   const gate = path.join(root, 'AWAITING_REVIEW.md')
@@ -517,7 +495,7 @@ function context(dir) {
     blockedTasks: skipped,
     humanActions,
   }
-  if (process.argv.includes('--json')) return console.log(JSON.stringify(report))
+  if (cli.has('--json')) return console.log(JSON.stringify(report))
 
   if (report.blocked) {
     const first = P.read(gate).split('\n').find((line) => line.trim() && !line.startsWith('#')) || ''
@@ -530,7 +508,8 @@ function context(dir) {
   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}`)
-  console.log(`WIP    ${report.wip ? `${report.wip.phase} · ${report.wip.complete}✓/${report.wip.pending}○` : 'idle'}`)
+  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}`)
 }
@@ -554,13 +533,18 @@ function instanceVersion(root) {
 
 // Actualiza sólo lo que el toolkit declara suyo. Todo lo demás —planning, organization, reglas
 // propias, agentes editados— queda intacto por construcción, no por comparación.
-function upgrade(dir) {
+function upgrade(dir, cli) {
   const root = path.resolve(dir || '.')
   if (!fs.existsSync(path.join(root, 'ops.config.json'))) {
     fail(`${root} no es una instancia de Cauce: falta ops.config.json.`, 2)
   }
-  const dry = process.argv.includes('--check')
-  const force = process.argv.includes('--force')
+  // Acá se fabrica Cauce: `upgrade` reemplazaría con las copias de `template/` los archivos que este
+  // repositorio mantiene en la raíz —`AGENTS.md` entre ellos, que es donde vive esta misma regla—.
+  if (O.mode(root) === 'toolkit') {
+    fail(`${root} es el toolkit: acá se edita Cauce, no se lo actualiza.`, 2)
+  }
+  const dry = cli.has('--check')
+  const force = cli.has('--force')
   const from = instanceVersion(root)
   const to = require(path.join(PROJECT_ROOT, 'package.json')).version
   const system = O.systemPaths(root)
@@ -706,23 +690,35 @@ function agentsFork(slug, dir) {
 
 // Lista los cargos visibles resolviendo la precedencia; evita que cada consumidor —CI incluido—
 // reimplemente el recorrido del catálogo.
-function agents(action, dir, extra) {
+function agents(action, dir, extra, cli) {
   if (action === 'fork') return agentsFork(dir, extra)
   if (action !== 'list') fail(`Acción de agents desconocida: ${action || '(vacía)'}`, 2)
   const root = opsRoot(dir)
   // Una empresa mantiene sus cargos, no los nuestros: `learn` sobre uno del catálogo se niega, así que
   // recorrer los 48 para encontrar el suyo es ruido. `--own` es lo que hace ejecutable ese recorrido.
-  const own = process.argv.includes('--own')
-  const system = process.argv.includes('--system')
+  const own = cli.has('--own')
+  const system = cli.has('--system')
   const roles = AG.list(root).filter((role) => (own ? !role.system : true) && (system ? role.system : true))
-  if (process.argv.includes('--json')) {
+  if (cli.has('--json')) {
     // `path` viene resuelto: quien consuma esto no debería reconstruir dónde ganó la precedencia.
     return console.log(JSON.stringify(roles.map((role) => ({
-      slug: role.slug, type: role.type, system: role.system,
+      slug: role.slug, type: role.type, system: role.system, summary: role.summary,
       path: path.relative(root, role.dir).split(path.sep).join('/'),
     }))))
   }
-  for (const role of roles) console.log(`${role.slug}${role.system ? '' : '  (propio)'}`)
+  // Una línea por cargo, alineadas, para elegir a quién asignarle una tarea sin abrir 47 carpetas.
+  const ancho = roles.reduce((max, role) => Math.max(max, role.slug.length), 0)
+  for (const role of roles) {
+    const marca = role.system ? '' : ' (propio)'
+    console.log(`${role.slug.padEnd(ancho)}${marca}  ${role.summary || '— sin resumen'}`)
+  }
+  // La respuesta negativa tiene que ser tan barata como la positiva: si ninguna línea encaja, el
+  // camino no es forzar el cargo más parecido, es escribir el propio.
+  if (roles.length && !own) {
+    console.log('\nSi ninguno encaja, escribí el tuyo en agents/roles/<slug>/ — es tuyo y gana sobre '
+      + 'el catálogo.\nSi encaja uno pero lo querés más enfocado en tu empresa: '
+      + 'organization/roles/<slug>.md para el contexto, u "ops agents fork <slug>" para adoptarlo.')
+  }
 }
 
 function archive(dir, rawNum) {
@@ -755,112 +751,143 @@ function archive(dir, rawNum) {
   console.log(`✓ epic-${num}: ${entries.length} entrada(s) archivadas`)
 }
 
-async function integration(action, rootArg, provider, key) {
-  const root = path.resolve(rootArg || '.')
-  if (action === 'list') {
-    const registry = JSON.parse(fs.readFileSync(path.join(root, 'integrations', 'config.json'), 'utf8'))
-    // Hay dos interruptores y `sync` exige los dos: el del registro dice que el proveedor está
-    // conectado al proyecto, el suyo propio que su configuración está terminada. Mostrar sólo el
-    // primero daba encendido a un proveedor que se habría negado a sincronizar.
-    for (const [name, entry] of Object.entries(registry.providers || {})) {
-      let listo = false
-      try {
-        listo = JSON.parse(fs.readFileSync(path.join(root, 'integrations', name, 'config.json'), 'utf8')).enabled === true
-      } catch { /* sin materializar */ }
-      const estado = !entry.enabled ? '○' : (listo ? '●' : '◐')
-      const nota = estado === '◐' ? `  — falta completar integrations/${name}/config.json y poner enabled: true` : ''
-      console.log(`${estado} ${name} [${entry.adapter}]${nota}`)
-    }
-    return
+// 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}`)
   }
-  if (action === 'enable') {
-    if (!provider) fail('Falta <provider>.', 2)
-    const source = path.join(PROJECT_ROOT, 'template', 'integrations', provider)
-    if (!fs.existsSync(source)) fail(`Cauce no trae un adaptador para ${provider}.`, 2)
-    const registry = path.join(root, 'integrations', 'config.json')
-    let config
-    try { config = JSON.parse(fs.readFileSync(registry, 'utf8')) } catch (error) {
-      fail(`integrations/config.json ilegible: ${error.message}`)
-    }
-    if (!config.providers || !config.providers[provider]) fail(`${provider} no está en integrations/config.json.`)
-    // 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.
-    copyTemplate(source, path.join(root, 'integrations', provider), {}, true)
-    config.providers[provider].enabled = true
-    F.atomicWriteJson(registry, config)
-    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.
-    let listo = false
-    try {
-      const suyo = path.join(root, 'integrations', provider, 'config.json')
-      listo = JSON.parse(fs.readFileSync(suyo, 'utf8')).enabled === true
-    } catch { /* sin configurar */ }
-    if (listo) console.log(`  Su configuración ya estaba completa: "integration sync" puede correr.`)
-    else {
+}
+
+// Si el proveedor terminó su propia configuración. Son dos interruptores y `sync` exige los dos: el
+// del registro dice que está conectado al proyecto, éste que hay a dónde apuntar.
+function providerReady(root, name) {
+  try {
+    const suyo = path.join(root, 'integrations', name, 'config.json')
+    return JSON.parse(fs.readFileSync(suyo, 'utf8')).enabled === true
+  } catch { return false }
+}
+
+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)
+}
+
+// Una entrada por acción, con lo que exige antes de correr. Eran nueve `if` seguidos, cada uno
+// repitiendo su propia validación de argumentos; acá el despachador la hace una vez y lee de la tabla.
+const INTEGRATION = {
+  list: {
+    run: (root) => {
+      for (const [name, entry] of Object.entries(providerRegistry(root).config.providers || {})) {
+        const listo = providerReady(root, name)
+        const estado = !entry.enabled ? '○' : (listo ? '●' : '◐')
+        const nota = estado === '◐'
+          ? `  — falta completar integrations/${name}/config.json y poner enabled: true`
+          : ''
+        console.log(`${estado} ${name} [${entry.adapter}]${nota}`)
+      }
+    },
+  },
+  enable: {
+    falta: 'Falta <provider>.',
+    run: (root, provider) => {
+      const source = path.join(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)
+      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.
+      if (providerReady(root, provider)) {
+        console.log(`  Su configuración ya estaba completa: "integration sync" puede correr.`)
+        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.`)
-    }
-    return
-  }
+    },
+  },
   // 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.
-  if (action === 'disable') {
-    if (!provider) fail('Falta <provider>.', 2)
-    const registry = path.join(root, 'integrations', 'config.json')
-    let config
-    try { config = JSON.parse(fs.readFileSync(registry, 'utf8')) } catch (error) {
-      fail(`integrations/config.json ilegible: ${error.message}`)
-    }
-    if (!config.providers || !config.providers[provider]) fail(`${provider} no está en integrations/config.json.`)
-    config.providers[provider].enabled = false
-    F.atomicWriteJson(registry, config)
-    console.log(`✓ ${provider}: desconectado del proyecto. "integration sync" deja de correrlo.`)
-    const dir = path.join(root, 'integrations', provider)
-    if (fs.existsSync(dir)) {
-      console.log(`  integrations/${provider}/ queda como está: ahí pueden vivir snapshots y borradores tuyos.`)
-    }
-    return
-  }
-  if (action === 'check') {
-    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}` : ''}`)
-    return
-  }
-  if (action === 'sync') {
-    if (!provider) fail('sync exige <provider>', 2)
-    const result = await I.sync(root, provider, { fixture: option('--fixture') })
-    console.log(
-      `✓ ${provider}: ${result.total} items · ${result.created} nuevos · ` +
-        `${result.refreshed} refrescados · ${result.preserved} curados preservados`,
-    )
-    return
-  }
-  if (action === 'promote') {
-    if (!provider || !key) fail('promote exige <provider> <remote-key>', 2)
-    const result = I.promote(root, provider, key)
-    console.log(`✓ ${provider}:${result.key} promovido como ${result.kind}`)
-    return
-  }
-  if (['reset', 'rebase', 'reconcile'].includes(action)) {
-    if (!provider || !key) fail(`${action} exige <provider> <remote-key>`, 2)
-    const changed = I.reconcile(root, provider, action, [key])
-    console.log(`✓ ${provider}: ${action} aplicado a ${changed.join(', ')}`)
-    return
-  }
-  if (action === 'writeback-plan') {
-    if (!provider) fail('writeback-plan exige <provider>', 2)
-    console.log(JSON.stringify(I.writebackPlan(root, provider), null, 2))
-    return
+  disable: {
+    falta: '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: {
+    falta: '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: {
+    falta: 'promote exige <provider> <remote-key>',
+    exigeKey: true,
+    run: (root, provider, key) => {
+      const result = I.promote(root, provider, key)
+      console.log(`✓ ${provider}:${result.key} promovido como ${result.kind}`)
+    },
+  },
+  'writeback-plan': {
+    falta: 'writeback-plan exige <provider>',
+    run: (root, provider) => console.log(JSON.stringify(I.writebackPlan(root, provider), null, 2)),
+  },
+}
+
+// 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 operacion of ['reset', 'rebase', 'reconcile']) {
+  INTEGRATION[operacion] = {
+    falta: `${operacion} exige <provider> <remote-key>`,
+    exigeKey: true,
+    run: (root, provider, key) => {
+      const changed = I.reconcile(root, provider, operacion, [key])
+      console.log(`✓ ${provider}: ${operacion} aplicado a ${changed.join(', ')}`)
+    },
   }
-  fail(`Acción de integración desconocida: ${action || '(vacía)'}`, 2)
 }
 
-function automation(action, rootArg, runnerName) {
+async function integration(action, rootArg, provider, key, cli) {
+  const paso = INTEGRATION[action]
+  if (!paso) fail(`Acción de integración desconocida: ${action || '(vacía)'}`, 2)
+  if (paso.falta && (!provider || (paso.exigeKey && !key))) fail(paso.falta, 2)
+  await paso.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') {
@@ -895,7 +922,7 @@ function automation(action, rootArg, runnerName) {
   }
   if (action === 'install') {
     let runner
-    const force = process.argv.includes('--force')
+    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 pedirá revisar y confiar en hooks nuevos al iniciar sesión.')
@@ -910,9 +937,18 @@ function automation(action, rootArg, runnerName) {
   }
   fail(`Acción de automatización desconocida: ${action || '(vacía)'}`, 2)
 }
-function learn(agent) {
+function learn(agent, cli) {
   try {
-    const result = process.argv.includes('--proposal')
+    // Sellar es determinista y por eso vive acá y no en el recorrido: marcar una propuesta como
+    // aplicada editando frontmatter a mano es justo el paso que un agente hace mal en silencio.
+    if (cli.has('--applied')) {
+      const result = L.seal(opsRoot(), agent, cli.value('--period'))
+      const relative = path.relative(opsRoot(), result.file)
+      return console.log(result.already
+        ? `= ${relative} ya estaba aplicada`
+        : `✓ ${relative} queda aplicada: no se vuelve a aplicar`)
+    }
+    const result = cli.has('--proposal')
       ? L.prepareProposal(opsRoot(), agent)
       : L.prepareReport(opsRoot(), agent)
     console.log(`${result.created ? '+' : '='} ${path.relative(opsRoot(), result.file)}`)
@@ -920,29 +956,25 @@ function learn(agent) {
   } catch (error) { fail(error.message, 2) }
 }
 
-function evaluate(agent) {
+function evaluate(agent, caso, cli) {
   const root = opsRoot()
   // El banco sólo tiene sentido acá: en una empresa el cargo que se evalúa es suyo —propio o
   // adoptado— y su `planning/` ya es el lugar legítimo donde trabajar.
-  if (process.argv.includes('--bench')) {
-    let mode = ''
-    try { mode = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8')).mode } catch { /* sin config */ }
-    if (mode !== 'toolkit') {
+  if (cli.has('--bench')) {
+    if (O.mode(root) !== 'toolkit') {
       fail('--bench es del toolkit. En una instancia, el cargo trabaja sobre tu planning/: si es del '
         + `catálogo, adoptalo primero con "ops agents fork ${agent}".`, 2)
     }
-    // El caso viene detrás de la bandera: `evaluate <cargo> --bench <caso>`. Sin él se arma un banco
-    // suelto, para mirarlo a mano; una corrida real pide uno por caso.
-    const flag = process.argv.indexOf('--bench')
-    const caso = (process.argv[flag + 1] || '').startsWith('--') ? '' : process.argv[flag + 1]
-    return console.log(evaluationBench(root, agent, caso))
+    // El caso es el posicional que sigue al cargo: `evaluate <cargo> --bench <caso>`. Sin él se arma
+    // un banco suelto, para mirarlo a mano; una corrida real pide uno por caso.
+    return console.log(evaluationBench(root, agent, caso, cli.has('--force')))
   }
   try {
     // Los casos, para que un recorrido los ejecute. Sin `--json` no tiene sentido: es entrada de
     // máquina, no de persona.
-    if (process.argv.includes('--cases')) {
+    if (cli.has('--cases')) {
       const cases = EV.list(root, agent)
-      if (!process.argv.includes('--json')) {
+      if (!cli.has('--json')) {
         for (const item of cases) console.log(`${item.id}  ${item.expected.length} comportamiento(s)`)
         return
       }
@@ -950,18 +982,20 @@ function evaluate(agent) {
     }
     const result = L.evaluate(root, agent)
     const runs = EV.validate(root, agent)
+    const errors = [...result.errors, ...runs.errors]
     for (const warning of runs.warnings) console.warn(`⚠ ${warning}`)
-    for (const error of result.errors) console.error(`✗ ${error}`)
-    if (result.errors.length) fail(`\n${result.errors.length} error(es)`, 1)
+    for (const error of errors) console.error(`✗ ${error}`)
+    if (errors.length) fail(`\n${errors.length} error(es)`, 1)
     const corrida = runs.last ? `${runs.last.passed}/${runs.last.total} pasan (${runs.last.date})` : 'sin correr'
     console.log(
-      `✓ ${agent}: ${result.cases} caso(s) — ${corrida}, ${result.proposals} propuesta(s), ` +
+      `✓ ${agent}: ${result.cases} caso(s) — ${corrida}, ${result.proposals} propuesta(s)` +
+        `${result.pending ? ` (${result.pending} sin aplicar)` : ''}, ` +
         'controles estructurales válidos',
     )
   } catch (error) { fail(error.message, 2) }
 }
 
-function team(action, slug) {
+function team(action, slug, cli) {
   if (action === 'list') {
     for (const name of T.list(opsRoot())) console.log(name)
     return
@@ -973,7 +1007,7 @@ function team(action, slug) {
     if (result.errors.length) fail(`${slug}: ${result.errors.length} error(es)`, 1)
     if (action === 'show') {
       // El manifiesto entero, para que un workflow ejecute las etapas sin que un modelo lo parsee.
-      if (process.argv.includes('--json')) return console.log(JSON.stringify(result.manifest))
+      if (cli.has('--json')) return console.log(JSON.stringify(result.manifest))
       console.log(`${result.manifest.name} (${slug})`)
       console.log(result.manifest.purpose)
       for (const stage of result.manifest.stages) {
@@ -985,25 +1019,33 @@ function team(action, slug) {
   } catch (error) { fail(error.message, 2) }
 }
 
-async function main() {
-  const command = process.argv[2]
+async function run(cli) {
+  const [command] = cli.positional
   if (!command || ['help', '--help', '-h'].includes(command)) return usage()
-  const arg = positionals()
-  if (command === 'init') init(arg[1])
-  else if (command === 'check') check(arg[1])
-  else if (command === 'tree') tree(arg[1])
-  else if (command === 'context') context(arg[1])
-  else if (command === 'upgrade') upgrade(arg[1])
-  else if (command === 'agents') agents(arg[1], arg[2], arg[3])
+  if (!FLAGS[command]) { usage(); fail(`Comando desconocido: ${command}`, 2) }
+  // `--help` valía sólo como primer argumento: `check --help` corría `check` contra el directorio
+  // actual en vez de explicarse.
+  if (cli.has('--help') || cli.has('-h')) return usage()
+  const sobran = cli.unknown(command)
+  if (sobran.length) {
+    const acepta = FLAGS[command].length ? `Acepta: ${FLAGS[command].join(', ')}.` : 'No acepta banderas.'
+    fail(`${command}: bandera desconocida ${sobran.join(', ')}. ${acepta}`, 2)
+  }
+  const arg = cli.positional
+  if (command === 'init') init(arg[1], cli)
+  else if (command === 'check') check(arg[1], cli)
+  else if (command === 'tree') tree(arg[1], cli)
+  else if (command === 'context') context(arg[1], cli)
+  else if (command === 'upgrade') upgrade(arg[1], cli)
+  else if (command === 'agents') agents(arg[1], arg[2], arg[3], cli)
   else if (command === 'archive') archive(arg[1], arg[2])
   else if (command === 'integration') {
-    await integration(arg[1], arg[2], arg[3], arg[4])
+    await integration(arg[1], arg[2], arg[3], arg[4], cli)
   }
-  else if (command === 'automation') automation(arg[1], arg[2], arg[3])
-  else if (command === 'learn') learn(arg[1])
-  else if (command === 'evaluate') evaluate(arg[1])
-  else if (command === 'team') team(arg[1], arg[2])
-  else { usage(); fail(`Comando desconocido: ${command}`, 2) }
+  else if (command === 'automation') automation(arg[1], arg[2], arg[3], cli)
+  else if (command === 'learn') learn(arg[1], cli)
+  else if (command === 'evaluate') evaluate(arg[1], arg[2], cli)
+  else if (command === 'team') team(arg[1], arg[2], cli)
 }
 
-main().catch((error) => fail(error.message))
+run(parse(process.argv.slice(2))).catch((error) => fail(error.message))