@ingeniomaps/cauce 0.12.0 → 0.13.0

package/.github/workflows/agent-learning.yml

@@ -5,6 +5,9 @@ name: Agent learning proposals
 
 on:
   schedule:
+    # Semanal la investigación, mensual la consolidación. La propuesta sólo vale si antes hubo
+    # informes: consolidar sin ellos produce un andamiaje vacío que nadie puede aprobar.
+    - cron: "17 13 * * 1"
     - cron: "17 13 1 * *"
   workflow_dispatch:
     inputs:
@@ -61,7 +64,97 @@ jobs:
             fs.appendFileSync(process.env.GITHUB_OUTPUT, `agents=${JSON.stringify(list)}\n`)
           ' "$all"
 
+  # La investigación necesita un modelo, así que este job sólo corre si el repositorio declara una
+  # credencial. Sin ella se saltea entero en vez de abrir un PR por cargo con un informe vacío, que
+  # es ruido con forma de trabajo. `learn` solo arma el andamiaje; llenarlo es lo que hace un agente.
+  research:
+    if: github.event.schedule != '17 13 1 * *'
+    needs: discover
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      max-parallel: 3
+      matrix:
+        agent: ${{ fromJSON(needs.discover.outputs.agents) }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+      - name: Check credential
+        id: creds
+        env:
+          KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          if [ -n "$KEY" ]; then
+            echo "ready=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "ready=false" >> "$GITHUB_OUTPUT"
+            echo "Sin ANTHROPIC_API_KEY: la investigación semanal queda para correr a mano." >&2
+          fi
+      - name: Resolve CLI
+        if: steps.creds.outputs.ready == 'true'
+        id: cli
+        run: |
+          for candidate in tools/ops.js engine/cli/ops.js; do
+            if [ -f "$candidate" ]; then
+              echo "path=$candidate" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+          done
+          echo "No se encontró el CLI de Cauce." >&2
+          exit 1
+      - name: Prepare report
+        if: steps.creds.outputs.ready == 'true'
+        env:
+          AGENT: ${{ matrix.agent }}
+          OPS: ${{ steps.cli.outputs.path }}
+        run: node "$OPS" learn "$AGENT"
+      # El prompt no lo escribe este archivo: lo declara el propio cargo en su
+      # `learning/CODEX_AUTOMATION.md`. Así un cargo nuevo trae su investigación sin tocar el cron.
+      - name: Research
+        if: steps.creds.outputs.ready == 'true'
+        env:
+          AGENT: ${{ matrix.agent }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          npm install -g @anthropic-ai/claude-code
+          claude -p "Leé el learning/CODEX_AUTOMATION.md del cargo $AGENT y ejecutá exactamente lo que declara. El informe de esta semana ya está creado y vacío: completalo. Cada afirmación necesita enlace, fecha y versión; lo que no puedas corroborar va a Preguntas abiertas en vez de afirmarse. El único archivo que escribís es ese informe."
+      - name: Detect changes
+        if: steps.creds.outputs.ready == 'true'
+        id: changes
+        run: |
+          if git diff --quiet; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Open research pull request
+        if: steps.creds.outputs.ready == 'true' && steps.changes.outputs.changed == 'true'
+        env:
+          AGENT: ${{ matrix.agent }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          stamp="$(date -u +%Y-%m-%d)"
+          branch="automation/$AGENT-research-$stamp"
+          report="$(git diff --name-only -- "agents/*/$AGENT/learning/reports/$stamp.md")"
+          if [ -z "$report" ]; then
+            echo "El agente cambió archivos fuera de su informe; no se abre PR." >&2
+            git diff --name-only >&2
+            exit 1
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git switch -c "$branch"
+          git add "$report"
+          git commit -m "docs($AGENT): weekly research $stamp"
+          git push origin "$branch"
+          gh pr create --base "$GITHUB_REF_NAME" --head "$branch" \
+            --title "$AGENT weekly research — $stamp" \
+            --body "Investigación semanal de la profesión. No modifica SKILL.md ni propone cambios: alimenta la propuesta mensual."
+
   propose:
+    if: github.event.schedule == '17 13 1 * *' || github.event_name == 'workflow_dispatch'
     needs: discover
     runs-on: ubuntu-latest
     strategy:

package/CHANGELOG.md

@@ -8,6 +8,32 @@ esa operación sea confiable en vez de sólo cómoda: acá se lee qué cambió a
 un cambio en el protocolo, en las reglas del sistema o en un guard es visible para el usuario y sube
 minor aunque no toque una sola línea de código.
 
+## [0.13.0] - 2026-08-16
+
+### Añadido
+
+- **El ciclo de aprendizaje se cierra solo hasta la firma, y sigue solo después de ella.** Faltaban
+  las dos mitades entre «recomendación» y «contrato actualizado`»:
+  - `/agent-propose <cargo>` escribe el cambio concreto —el texto exacto, archivo por archivo— y lo
+    contrasta contra los casos vigentes. Antes la propuesta llegaba con «Cambio propuesto: por
+    definir», y nadie firma una intención.
+  - `/agent-promote <cargo>` aplica una propuesta **ya firmada**, registra en `HISTORY.md` y manda a
+    correr los casos. Dos candados: se niega si «Aprobación humana» no tiene responsable —un agente no
+    se autoriza a sí mismo— y exige verificar, porque aplicar sin correr los casos deja un contrato
+    cambiado sin saber si se sostiene.
+- Aplica **prosa, no un parche**, a propósito: un parche envejece si alguien toca el archivo mientras
+  la propuesta espera firma. El costo es que aplicar exige criterio, y por eso toda desviación se
+  escribe en la propia propuesta: quien firmó tiene derecho a saber qué se aplicó de lo que firmó.
+- Investigación **semanal** en el cron, además de la consolidación mensual. Corre sólo si el
+  repositorio declara `ANTHROPIC_API_KEY`; sin ella se saltea entero en vez de abrir un PR por cargo
+  con un informe vacío. El prompt no vive en el cron: lo declara cada cargo en su
+  `learning/CODEX_AUTOMATION.md`, así que un cargo nuevo trae su investigación sin tocar el workflow.
+
+### Nota
+
+El cron es de Cauce, no de las instancias: una empresa no lo recibe. Su ciclo de aprendizaje es por
+comando, y activarlo en su propio repositorio es decisión suya.
+
 ## [0.12.0] - 2026-08-16
 
 ### Cambiado

package/automatization/runners/claude/manifest.json

@@ -32,6 +32,14 @@
     {
       "source": "../../workflows/agent-eval.js",
       "target": ".claude/workflows/agent-eval.js"
+    },
+    {
+      "source": "../../workflows/agent-propose.js",
+      "target": ".claude/workflows/agent-propose.js"
+    },
+    {
+      "source": "../../workflows/agent-promote.js",
+      "target": ".claude/workflows/agent-promote.js"
     }
   ],
   "capabilities": {

package/automatization/workflows/agent-promote.js

@@ -0,0 +1,140 @@
+// Aplica una propuesta ya firmada y comprueba que el cargo siga aguantando sus casos.
+//
+// Es el único recorrido que modifica un cargo, y por eso tiene dos candados que no se pueden saltar:
+//
+//   1. Se niega si «Aprobación humana» no está firmada con responsable. Un agente no se autoriza a sí
+//      mismo, y `automatic_apply: false` sigue siendo cierto: esto no corre solo, lo corre alguien
+//      después de firmar.
+//   2. Corre los casos adversariales al terminar. Aplicar sin verificar deja un contrato cambiado y
+//      nadie sabiendo si todavía se sostiene, que es peor que no haber aplicado.
+//
+// Aplica **prosa**, no un parche, y es a propósito: la propuesta dice «agregar dos viñetas después de
+// la última existente». Un parche envejece si alguien toca el archivo mientras la propuesta espera
+// firma; la prosa sobrevive a eso, a cambio de exigir criterio al aplicar. Ese criterio queda visible:
+// toda desviación se escribe en la propia propuesta.
+export const meta = {
+  name: 'agent-promote',
+  description: 'Aplica una propuesta firmada, registra el cambio y vuelve a correr los casos',
+  whenToUse: 'Después de firmar «Aprobación humana» en una propuesta mensual.',
+  phases: [
+    { title: 'Firma', detail: 'Sin aprobación humana no se toca nada' },
+    { title: 'Aplicar', detail: 'El cambio, archivo por archivo' },
+    { title: 'Registrar', detail: 'Historial del cargo' },
+    { title: 'Verificar', detail: 'Los casos adversariales contra el contrato nuevo' },
+  ],
+}
+
+const ROOT = '{{OPS_DIR}}'.replace(/\/+$/, '') || '.'
+const AGENT = String((typeof args === 'string' ? args : (args || {}).agent) || '').trim()
+const PERIOD = String((args || {}).period || '').trim()
+
+const FIRMA = {
+  type: 'object', additionalProperties: false, required: ['dir', 'proposal', 'approved'],
+  properties: {
+    dir: { type: 'string' },
+    proposal: { type: 'string' },
+    approved: { type: 'boolean' },
+    signedBy: { type: 'string' },
+    state: { type: 'string' },
+    hasChange: { type: 'boolean' },
+  },
+}
+
+const APLICADO = {
+  type: 'object', additionalProperties: false, required: ['applied', 'files'],
+  properties: {
+    applied: { type: 'boolean' },
+    files: { type: 'array', items: { type: 'string' } },
+    deviations: { type: 'string' },
+    newCase: { type: 'string' },
+  },
+}
+
+function finish(result) {
+  log(`Fin: ${JSON.stringify(result)}`)
+  return result
+}
+
+const stop = (reason, detail = '') => {
+  log(`Checkpoint: ${reason}${detail ? ` — ${detail}` : ''}`)
+  return finish({ stopped: true, reason, detail })
+}
+
+if (!AGENT) return stop('sin-cargo', 'pasá el slug del cargo')
+
+phase('Firma')
+
+const firma = await agent(
+  `From ${ROOT}, run "node tools/ops.js agents list --json" and take the path it printed for ${AGENT}. ` +
+  `Set dir to "${ROOT}/<path>": that command prints paths relative to ${ROOT}.\n\n` +
+  `Find the newest <dir>/learning/proposals/AAAA-MM.md` +
+  `${PERIOD ? `, preferring ${PERIOD}.md` : ''} and set proposal to its full path. Read **only** its ` +
+  `"Aprobación humana" and "Cambio propuesto" sections and report, without interpreting in anyone's ` +
+  `favour:\n` +
+  `- approved: true only if the state says it is approved AND a named person is recorded. "pendiente", ` +
+  `"por definir" or an empty responsible means false.\n` +
+  `- signedBy: the person recorded, or empty.\n` +
+  `- state: the literal state line.\n` +
+  `- hasChange: true only if "Cambio propuesto" carries a concrete change; "por definir" means false.`,
+  { schema: FIRMA, label: 'firma' },
+)
+if (!firma) return stop('sin-propuesta', `no se pudo leer una propuesta de ${AGENT}`)
+if (!firma.hasChange) {
+  return stop('propuesta-vacia', `${firma.proposal} no tiene cambio concreto: corré /agent-propose primero`)
+}
+if (!firma.approved) {
+  return stop('sin-firma', `${firma.proposal} no está aprobada (${firma.state || 'sin estado'}). ` +
+    'Firmá «Aprobación humana» con un responsable y repetí: nadie se autoriza a sí mismo')
+}
+log(`Aprobada por ${firma.signedBy}`)
+
+phase('Aplicar')
+
+const aplicado = await agent(
+  `La propuesta ${firma.proposal} está aprobada por ${firma.signedBy}. Aplicá su sección «Cambio ` +
+  `propuesto» al cargo ${AGENT} en ${firma.dir}, archivo por archivo, tal como la propuesta lo ` +
+  `describe.\n\n` +
+  `Reglas al aplicar:\n` +
+  `- Preferí agregar sobre reescribir. Si la propuesta dice «agregar después de X», agregá; no ` +
+  `reordenes ni reformules lo que ya estaba.\n` +
+  `- Si la propuesta pide crear un caso adversarial nuevo, crealo con el enunciado que da y con ` +
+  `**cuatro** comportamientos esperados, como todos los del catálogo. Si el enunciado trae más, ` +
+  `fusioná los que se solapen sin perder ninguna idea.\n` +
+  `- Si algo de la propuesta ya no aplica —el archivo cambió, la sección no existe— **no lo fuerces**: ` +
+  `dejalo sin aplicar y reportalo como desviación.\n` +
+  `- Toda desviación, por chica que sea, se escribe al final de «Aprobación humana» en la propia ` +
+  `propuesta, explicando qué se hizo distinto y por qué. Quien firmó tiene derecho a saber qué se ` +
+  `aplicó de lo que firmó.\n\n` +
+  `No toques otros cargos. No hagas commit ni push. Devolvé qué archivos modificaste, el caso nuevo si ` +
+  `lo creaste, y las desviaciones —o cadena vacía si no hubo—.`,
+  { schema: APLICADO, label: `aplica:${AGENT}` },
+)
+if (!aplicado || !aplicado.applied) {
+  return stop('no-aplicada', 'el cambio no se pudo aplicar; la propuesta queda como estaba')
+}
+log(`Aplicado en: ${(aplicado.files || []).join(', ')}`)
+
+phase('Registrar')
+
+await agent(
+  `Agregá una fila a ${firma.dir}/learning/HISTORY.md con la fecha de hoy —obtenela con "date +%F"—, ` +
+  `la propuesta ${firma.proposal}, decisión "Aprobada", quién firmó (${firma.signedBy}) y qué se ` +
+  `aplicó: ${(aplicado.files || []).join(', ')}` +
+  `${aplicado.newCase ? ` más el caso ${aplicado.newCase}` : ''}` +
+  `${aplicado.deviations ? `. Desviaciones: ${aplicado.deviations}` : ''}.\n\n` +
+  `Respetá el formato de tabla que ya tiene el archivo. No toques ninguna otra cosa, no hagas commit.`,
+  { label: 'historial' },
+)
+
+phase('Verificar')
+
+log('El contrato cambió: los casos valen sólo si se vuelven a correr contra la versión nueva.')
+return finish({
+  agent: AGENT,
+  proposal: firma.proposal,
+  signedBy: firma.signedBy,
+  files: aplicado.files || [],
+  newCase: aplicado.newCase || '',
+  deviations: aplicado.deviations || '',
+  next: `corré /agent-eval ${AGENT}: el registro anterior quedó viejo y no vale para el contrato nuevo`,
+})

package/automatization/workflows/agent-propose.js

@@ -0,0 +1,117 @@
+// Convierte la recomendación de los informes en el cambio concreto que una persona puede aprobar.
+//
+// `learn --proposal` consolida qué recomendaron los informes de la semana, pero deja «Cambio
+// propuesto: por definir». Eso no es aprobable: nadie firma una intención. Este recorrido escribe el
+// texto exacto que habría que agregar, archivo por archivo, y lo contrasta contra los casos
+// adversariales vigentes antes de proponerlo.
+//
+// Nunca aplica nada, y no es una formalidad: la sección «Aprobación humana» la firma una persona, y
+// hasta que esté firmada `/agent-promote` se niega a tocar el cargo.
+export const meta = {
+  name: 'agent-propose',
+  description: 'Escribe el cambio concreto de una propuesta mensual y lo contrasta con los casos',
+  whenToUse: 'Después de que el ciclo consolide una propuesta, para dejarla en estado aprobable.',
+  phases: [
+    { title: 'Contexto', detail: 'Contrato, fuentes, conductas y casos vigentes' },
+    { title: 'Proponer', detail: 'El cambio exacto, sus riesgos y su evaluación' },
+  ],
+}
+
+// El prefijo lo completa `automation install`. El runtime de workflows no expone `process`.
+const ROOT = '{{OPS_DIR}}'.replace(/\/+$/, '') || '.'
+const AGENT = String((typeof args === 'string' ? args : (args || {}).agent) || '').trim()
+const PERIOD = String((args || {}).period || '').trim()
+
+const CONTEXT = {
+  type: 'object', additionalProperties: false, required: ['dir', 'proposal', 'cases'],
+  properties: {
+    dir: { type: 'string' },
+    proposal: { type: 'string' },
+    cases: { type: 'integer' },
+    hasChange: { type: 'boolean' },
+  },
+}
+
+const RESULT = {
+  type: 'object', additionalProperties: false, required: ['completed', 'files'],
+  properties: {
+    completed: { type: 'boolean' },
+    files: { type: 'array', items: { type: 'string' } },
+    newCase: { type: 'string' },
+    risks: { type: 'integer' },
+    summary: { type: 'string' },
+  },
+}
+
+function finish(result) {
+  log(`Fin: ${JSON.stringify(result)}`)
+  return result
+}
+
+const stop = (reason, detail = '') => {
+  log(`Checkpoint: ${reason}${detail ? ` — ${detail}` : ''}`)
+  return finish({ stopped: true, reason, detail })
+}
+
+if (!AGENT) return stop('sin-cargo', 'pasá el slug del cargo')
+
+phase('Contexto')
+
+const contexto = await agent(
+  `From ${ROOT}, run "node tools/ops.js agents list --json" and take the path it printed for ${AGENT}. ` +
+  `Set dir to "${ROOT}/<path>": that command prints paths relative to ${ROOT} and the next agent runs ` +
+  `from elsewhere, so the prefix is not optional.\n\n` +
+  `Then find the newest file under <dir>/learning/proposals/ named AAAA-MM.md` +
+  `${PERIOD ? `, preferring ${PERIOD}.md` : ''}. Set proposal to its full path. Read it and set ` +
+  `hasChange to true only if its "Cambio propuesto" section already carries a concrete change —if it ` +
+  `still says "por definir", it is false.\n\n` +
+  `Finally run "node tools/ops.js evaluate ${AGENT} --cases" and set cases to how many it listed. ` +
+  `Report only what the commands printed.`,
+  { schema: CONTEXT, label: 'contexto' },
+)
+if (!contexto) return stop('sin-contexto', `no se pudo ubicar el cargo ${AGENT}`)
+if (contexto.hasChange) {
+  return stop('ya-propuesta', `${contexto.proposal} ya tiene un cambio concreto; revisalo o borralo antes`)
+}
+log(`${contexto.proposal} · ${contexto.cases} caso(s) vigentes`)
+
+phase('Proponer')
+
+const propuesta = await agent(
+  `Sos quien mantiene el cargo ${AGENT}. La propuesta ${contexto.proposal} consolidó lo que ` +
+  `recomendaron los informes semanales, pero le falta lo único que una persona puede aprobar: el ` +
+  `cambio concreto.\n\n` +
+  `Leé los informes citados en su sección «Hallazgos», el SKILL.md del cargo, ` +
+  `${contexto.dir}/learning/sources.yaml, ${contexto.dir}/evaluations/expected-behaviors.yaml y sus ` +
+  `casos en ${contexto.dir}/evaluations/cases/. Después completá **sólo** estas tres secciones de la ` +
+  `propuesta, sin tocar ninguna otra ni el frontmatter:\n\n` +
+  `**Cambio propuesto**: el texto exacto a agregar o reemplazar, archivo por archivo, citando la ` +
+  `sección o la línea que se toca. Que se pueda aplicar leyéndolo, sin volver al informe. Preferí ` +
+  `agregar sobre reescribir: el núcleo del contrato no está en discusión. Si una fuente no se pudo ` +
+  `corroborar, dejalo escrito en el propio texto en vez de afirmarla.\n\n` +
+  `**Riesgos y regresiones**: qué caso adversarial existente podría empezar a fallar y qué parte del ` +
+  `contrato podría contradecirse. Si dos reglas quedan en tensión aparente, resolvela en el texto ` +
+  `propuesto, no la dejes para quien aplique.\n\n` +
+  `**Evaluación**: contrastá el cambio contra los ${contexto.cases} casos vigentes, uno por uno, y ` +
+  `decí si cada uno sigue pasando. Si una conducta prohibida nueva no tiene caso que la distinga de ` +
+  `las que ya están, escribí el enunciado del caso que haría falta —con **cuatro** comportamientos ` +
+  `esperados, como todos los del catálogo— y **no crees el archivo**: cambiar el denominador de la ` +
+  `evaluación es parte de lo que se aprueba.\n\n` +
+  `No modifiques SKILL.md, sources.yaml, expected-behaviors.yaml ni los casos: esto es una propuesta, ` +
+  `no su aplicación. No toques «Aprobación humana»: esa la firma una persona. No hagas commit ni push. ` +
+  `El único archivo que escribís es la propuesta.\n\n` +
+  `Devolvé qué archivos tocaría el cambio, el enunciado del caso nuevo si lo hay, cuántos riesgos ` +
+  `identificaste y un resumen en una frase.`,
+  { schema: RESULT, label: `propone:${AGENT}` },
+)
+if (!propuesta) return stop('sin-propuesta', 'el agente no devolvió resultado')
+
+log(`Tocaría: ${(propuesta.files || []).join(', ')}`)
+return finish({
+  agent: AGENT,
+  proposal: contexto.proposal,
+  files: propuesta.files || [],
+  risks: propuesta.risks || 0,
+  newCase: propuesta.newCase || '',
+  next: 'firmá «Aprobación humana» y corré /agent-promote',
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingeniomaps/cauce",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Sistema portable de planificación y ejecución verificable para cualquier proyecto",
   "type": "commonjs",
   "bin": {