@ingeniomaps/cauce 0.1.0

package/automatization/hooks/guard-planning-drift.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Evita cerrar una sesión con planning o integraciones desalineados.
+# Implementación compartida: engine/hooks/run.js → planningDrift().
+exec "$(dirname "$0")/run-hook.sh" planning-drift

package/automatization/hooks/guard-secrets.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Bloquea escritura de secretos, claves privadas y credenciales en texto plano.
+# Implementación compartida: engine/hooks/run.js → secrets().
+exec "$(dirname "$0")/run-hook.sh" secrets

package/automatization/hooks/guard-shell.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Corre en un solo proceso los guards de shell: destructive, git-add, dependencies, governance, verify.
+# Implementación compartida: engine/hooks/run.js → hookGroups['pre-shell'].
+exec "$(dirname "$0")/run-hook.sh" pre-shell

package/automatization/hooks/guard-verify.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Ejecuta los gates del stack y comprueba drift generado antes de un commit.
+# Implementación compartida: engine/hooks/run.js → verify().
+exec "$(dirname "$0")/run-hook.sh" verify

package/automatization/hooks/guard-workspace-boundary.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Limita escrituras a las raíces declaradas en ops.config.json.
+# Implementación compartida: engine/hooks/run.js → workspaceBoundary().
+exec "$(dirname "$0")/run-hook.sh" workspace-boundary

package/automatization/hooks/run-hook.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -u
+
+hook_name=${1:-}
+hook_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+ops_root=$(CDPATH= cd -- "$hook_dir/../.." && pwd)
+runner="$ops_root/.ops/engine/hooks/run.js"
+[ -f "$runner" ] || runner="$ops_root/engine/hooks/run.js"
+
+if [ ! -f "$runner" ]; then
+  echo "BLOQUEADO [$hook_name]: no se encontró el motor de hooks de Cauce." >&2
+  echo "  Buscado en: $ops_root/.ops/engine/hooks/run.js" >&2
+  echo "           y: $ops_root/engine/hooks/run.js" >&2
+  exit 2
+fi
+
+if [ -z "$hook_name" ]; then
+  echo "BLOQUEADO: run-hook.sh requiere el nombre del guard o grupo que debe ejecutar." >&2
+  exit 2
+fi
+
+exec node "$runner" "$@"

package/automatization/runners/README.md

@@ -0,0 +1,25 @@
+# Adaptadores de runners
+
+Un adaptador declara:
+
+1. Eventos soportados (`pre-tool`, `post-tool`, `stop`, workflow invocable).
+2. Cómo localiza la raíz Ops y ejecuta `engine/cli/ops.js`.
+3. Qué fases ejecuta realmente y cuáles quedan como protocolo manual.
+4. Cómo instala y desinstala su wiring sin duplicar fuentes de verdad.
+5. Qué permisos o acciones externas requieren confirmación.
+
+```text
+runners/<nombre>/
+├── README.md
+├── manifest.json
+├── settings.json
+├── archivo de instrucciones (si aplica)
+└── comandos o artefactos propios (si aplica)
+```
+
+Adaptadores incluidos: `claude`, `codex`, `antigravity` y `gemini`. Antigravity es la opción Google
+recomendada para cuentas individuales y proyectos nuevos; Gemini se conserva para Enterprise, Google Cloud
+y autenticación mediante API keys. Se instalan explícitamente con
+`ops automation install`; crear el proyecto no modifica la configuración activa del usuario.
+Después de instalar, `ops automation doctor <raíz> <runner>` verifica configuración, instrucciones,
+artefactos y disponibilidad del CLI sin requerir autenticación.

package/automatization/runners/antigravity/README.md

@@ -0,0 +1,16 @@
+# Antigravity CLI
+
+Runner Google recomendado para cuentas individuales y proyectos nuevos. Usa el ejecutable `agy` y se instala
+como plugin nativo de workspace en `.agents/plugins/cauce/`:
+
+```bash
+make install-antigravity
+make doctor-antigravity
+```
+
+El plugin aporta hooks `PreToolUse` y `Stop`, reglas Cauce y skills `/autobuild`,
+`/integration-sync` y `/integration-promote`. El bridge convierte el contrato JSON camelCase de Antigravity
+al motor compartido de guards y devuelve decisiones nativas `allow`, `deny` o `continue`.
+
+La instalación no autentica ni modifica preferencias globales. Antigravity también lee el `AGENTS.md` del
+workspace. El runner `gemini` permanece disponible por separado para Enterprise, Google Cloud y API keys.

package/automatization/runners/antigravity/hook.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+'use strict'
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+function readInput() {
+  try {
+    const raw = fs.readFileSync(0, 'utf8')
+    return raw.trim() ? JSON.parse(raw) : {}
+  } catch { return {} }
+}
+
+function findRoot(input) {
+  const args = input.toolCall && input.toolCall.args || {}
+  const starts = [args.Cwd, process.cwd(), ...(input.workspacePaths || [])].filter(Boolean)
+  for (const start of starts) {
+    let current = path.resolve(start)
+    while (true) {
+      const instance = fs.existsSync(path.join(current, 'planning'))
+      const toolkit = fs.existsSync(path.join(current, 'engine', 'hooks', 'run.js'))
+      if (fs.existsSync(path.join(current, 'ops.config.json')) && (instance || toolkit)) return current
+      const parent = path.dirname(current)
+      if (parent === current) break
+      current = parent
+    }
+  }
+  throw new Error('No se encontró una raíz Cauce desde el workspace de Antigravity.')
+}
+
+function runtimeAt(root) {
+  const candidates = [path.join(root, '.ops', 'engine', 'hooks', 'run.js'), path.join(root, 'engine', 'hooks', 'run.js')]
+  const runtime = candidates.find(fs.existsSync)
+  if (!runtime) throw new Error('No se encontró el runtime engine/hooks/run.js.')
+  return require(runtime)
+}
+
+function normalize(input) {
+  const args = input.toolCall && input.toolCall.args || {}
+  const file = args.TargetFile || args.AbsolutePath || ''
+  const content = args.CodeContent || args.ReplacementContent || (args.ReplacementChunks && JSON.stringify(args.ReplacementChunks)) || ''
+  return {
+    sessionId: input.conversationId,
+    cwd: args.Cwd || (input.workspacePaths || [])[0] || process.cwd(),
+    tool_input: {
+      command: args.CommandLine || '',
+      file_path: file,
+      content,
+    },
+  }
+}
+
+function respond(value) {
+  process.stdout.write(`${JSON.stringify(value)}\n`)
+}
+
+function evaluate(event, input) {
+  try {
+    const root = findRoot(input)
+    process.env.OPS_ROOT = root
+    const hooks = runtimeAt(root)
+    const normalized = normalize(input)
+    if (!hooks.hookGroups[event]) throw new Error(`Evento Antigravity desconocido: ${event || '(vacío)'}`)
+    hooks.executeAll([event], normalized)
+    return event === 'stop' ? { decision: 'stop' } : { decision: 'allow' }
+  } catch (error) {
+    if (event === 'stop') return { decision: 'continue', reason: `Cauce: ${error.message}` }
+    return { decision: 'deny', reason: `Cauce: ${error.message}` }
+  }
+}
+
+function main() {
+  respond(evaluate(process.argv[2], readInput()))
+}
+
+if (require.main === module) main()
+
+module.exports = { evaluate, findRoot, normalize }

package/automatization/runners/antigravity/hooks.json

@@ -0,0 +1,21 @@
+{
+  "cauce": {
+    "PreToolUse": [
+      {
+        "matcher": "run_command",
+        "hooks": [
+          { "type": "command", "command": "node .agents/plugins/cauce/hook.js pre-shell", "timeout": 120 }
+        ]
+      },
+      {
+        "matcher": "write_to_file|replace_file_content|multi_replace_file_content",
+        "hooks": [
+          { "type": "command", "command": "node .agents/plugins/cauce/hook.js pre-files", "timeout": 30 }
+        ]
+      }
+    ],
+    "Stop": [
+      { "type": "command", "command": "node .agents/plugins/cauce/hook.js stop", "timeout": 120 }
+    ]
+  }
+}

package/automatization/runners/antigravity/manifest.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": 1,
+  "name": "antigravity",
+  "command": "agy",
+  "lifecycle": { "recommendedForNewProjects": true, "audience": "individual-and-new-google-projects" },
+  "config": { "source": "hooks.json", "target": ".agents/plugins/cauce/hooks.json" },
+  "instructions": [],
+  "artifacts": [
+    { "source": "plugin.json", "target": ".agents/plugins/cauce/plugin.json" },
+    { "source": "hook.js", "target": ".agents/plugins/cauce/hook.js" },
+    { "source": "rules/cauce.md", "target": ".agents/plugins/cauce/rules/cauce.md" },
+    { "source": "skills/autobuild/SKILL.md", "target": ".agents/plugins/cauce/skills/autobuild/SKILL.md" },
+    { "source": "skills/integration-sync/SKILL.md", "target": ".agents/plugins/cauce/skills/integration-sync/SKILL.md" },
+    { "source": "skills/integration-promote/SKILL.md", "target": ".agents/plugins/cauce/skills/integration-promote/SKILL.md" }
+  ],
+  "capabilities": { "nativeHooks": true, "nativeWorkflows": true, "projectInstructions": true, "checkpointing": false }
+}

package/automatization/runners/antigravity/plugin.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://antigravity.google/schemas/v1/plugin.json",
+  "name": "cauce",
+  "description": "Guards y workflows portables de Cauce para Antigravity CLI."
+}

package/automatization/runners/antigravity/rules/cauce.md

@@ -0,0 +1,6 @@
+# Cauce
+
+Lee y cumple `AGENTS.md` y `planning/PROTOCOL.md` antes de ejecutar trabajo. `planning/WIP.md` es el mutex de
+ejecución y `planning/AWAITING_REVIEW.md` bloquea una corrida nueva. No promociones ideas desde INBOX, no
+inventes aprobaciones o credenciales y no hagas push ni deploy. Cierra cada tarea con verificación real y
+evidencia en DONE.

package/automatization/runners/antigravity/skills/autobuild/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: autobuild
+description: Ejecuta el siguiente hito aprobado siguiendo el protocolo Cauce.
+---
+
+Lee completos `AGENTS.md`, `planning/PROTOCOL.md` y `planning/WIP.md`. Si existe
+`planning/AWAITING_REVIEW.md`, detente y explica la acción humana pendiente. Toma solamente la primera tarea
+aprobada, persiste el estado en WIP y ejecuta Build, Review, Verify y QA en orden. Usa los comandos reales del
+servicio, registra evidencia verificable en DONE y detente en el checkpoint entre hitos. No hagas push ni
+deploy.

package/automatization/runners/antigravity/skills/integration-promote/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: integration-promote
+description: Promueve un borrador remoto ya revisado al roadmap local de Cauce.
+---
+
+Lee `AGENTS.md`, `planning/PROTOCOL.md` e `integrations/README.md`. Verifica que el draft solicitado exista y
+esté marcado `ready`; nunca marques como listo contenido por iniciativa propia. Ejecuta
+`node tools/ops.js integration promote . <provider> <remote-key>`, valida con
+`node tools/ops.js check planning` y reporta el archivo creado. La promoción es local: no escribas en el
+proveedor remoto.

package/automatization/runners/antigravity/skills/integration-sync/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: integration-sync
+description: Sincroniza en modo lectura un proveedor externo hacia el staging local de Cauce.
+---
+
+Lee `AGENTS.md`, `planning/PROTOCOL.md` e `integrations/README.md`. Confirma que el proveedor esté habilitado
+y ejecuta `node tools/ops.js integration check . <provider>` antes de sincronizar. Ejecuta después
+`node tools/ops.js integration sync . <provider>`. No edites snapshots manualmente, no cambies datos remotos
+y no promociones borradores durante esta operación. Reporta conteos y errores reales.

package/automatization/runners/claude/CLAUDE.md

@@ -0,0 +1,10 @@
+# Cauce para Claude Code
+
+@AGENTS.md
+@planning/PROTOCOL.md
+
+Los hooks de `.claude/settings.json` son obligatorios. Usa `/autobuild` para ejecutar trabajo promovido;
+`/integration-sync` y `/integration-promote` gestionan staging local sin escritura remota.
+
+Antes de iniciar, respeta `planning/AWAITING_REVIEW.md` y el mutex de `planning/WIP.md`. Si el protocolo y
+un workflow difieren, manda el protocolo y la diferencia se registra en `planning/INBOX.md`.

package/automatization/runners/claude/README.md

@@ -0,0 +1,13 @@
+# Claude Code
+
+Adaptador nativo mediante `PreToolUse` y `Stop`. Instalar con:
+
+```bash
+node tools/ops.js automation install . claude
+```
+
+El instalador fusiona la sección `hooks` en `.claude/settings.json` y conserva otras claves.
+También instala `autobuild`, `integration-sync` e `integration-promote` en `.claude/workflows/`. Si ya existe
+una versión distinta, se detiene sin sobrescribirla para no destruir personalizaciones del proyecto.
+También crea `CLAUDE.md` cuando no existe y conserva uno existente. `manifest.json` declara destinos y
+capacidades. Comprueba todo con `node tools/ops.js automation doctor . claude`.

package/automatization/runners/claude/manifest.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "name": "claude",
+  "command": "claude",
+  "config": { "source": "settings.json", "target": ".claude/settings.json" },
+  "instructions": [{ "source": "CLAUDE.md", "target": "CLAUDE.md" }],
+  "artifacts": [
+    { "source": "../../workflows/autobuild.js", "target": ".claude/workflows/autobuild.js" },
+    { "source": "../../workflows/integrations/sync.js", "target": ".claude/workflows/integration-sync.js" },
+    { "source": "../../workflows/integrations/promote.js", "target": ".claude/workflows/integration-promote.js" }
+  ],
+  "capabilities": { "nativeHooks": true, "nativeWorkflows": true, "projectInstructions": true, "checkpointing": false }
+}

package/automatization/runners/claude/settings.json

@@ -0,0 +1,25 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/automatization/hooks/guard-shell.sh" }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/automatization/hooks/guard-files.sh" }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/automatization/hooks/guard-planning-drift.sh" }
+        ]
+      }
+    ]
+  }
+}

package/automatization/runners/codex/README.md

@@ -0,0 +1,15 @@
+# Codex CLI
+
+Codex CLI actual expone hooks nativos y pide confianza al detectar hooks nuevos o modificados. Instalar la
+configuración del proyecto con:
+
+```bash
+node tools/ops.js automation install . codex
+```
+
+El archivo se instala en `.codex/hooks/hooks.json`. La primera sesión revisa y solicita confiar en los hooks;
+no se usa `--dangerously-bypass-hook-trust`.
+
+Codex carga las instrucciones de proyecto desde el `AGENTS.md` canónico, por lo que no se instala una copia
+adicional. `manifest.json` declara esta capacidad y `node tools/ops.js automation doctor . codex` valida el
+wiring. Los workflows JS de Claude no se presentan como compatibles con Codex.

package/automatization/runners/codex/hooks.json

@@ -0,0 +1,25 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "shell|unified_exec",
+        "hooks": [
+          { "type": "command", "command": "automatization/hooks/guard-shell.sh" }
+        ]
+      },
+      {
+        "matcher": "apply_patch|files",
+        "hooks": [
+          { "type": "command", "command": "automatization/hooks/guard-files.sh" }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          { "type": "command", "command": "automatization/hooks/guard-planning-drift.sh" }
+        ]
+      }
+    ]
+  }
+}

package/automatization/runners/codex/manifest.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "name": "codex",
+  "command": "codex",
+  "config": { "source": "hooks.json", "target": ".codex/hooks/hooks.json" },
+  "instructions": [],
+  "artifacts": [],
+  "capabilities": { "nativeHooks": true, "nativeWorkflows": false, "projectInstructions": true, "checkpointing": false }
+}

package/automatization/runners/gemini/GEMINI.md

@@ -0,0 +1,12 @@
+# Cauce para Gemini CLI
+
+@AGENTS.md
+@planning/PROTOCOL.md
+
+`planning/PROTOCOL.md` es la fuente de verdad. Ejecuta `/ops:autobuild` fase por fase; los workflows JS de
+Claude son referencia, no un runtime compatible. `planning/WIP.md` es el mutex y
+`planning/AWAITING_REVIEW.md` bloquea una corrida nueva.
+
+Gemini no tiene guards nativos configurados por este toolkit. Antes de cada commit ejecuta los wrappers de
+`automatization/hooks/` como prechecks y al cerrar ejecuta `node tools/ops.js check planning`. Nunca omitas
+aprobaciones, inventes credenciales, escribas remoto, hagas push/deploy o promociones trabajo desde INBOX.

package/automatization/runners/gemini/README.md

@@ -0,0 +1,18 @@
+# Gemini CLI
+
+Adaptador conservado para Gemini Code Assist Enterprise/Standard, Google Cloud y autenticación mediante
+API keys. Para cuentas individuales y proyectos Google nuevos usa el runner `antigravity`.
+
+Adaptador mediante configuración de proyecto, `GEMINI.md`, checkpointing y comandos personalizados. Instalar con:
+
+```bash
+node tools/ops.js automation install . gemini
+```
+
+Instala `.gemini/settings.json`, el contexto raíz `GEMINI.md` y los comandos `/ops:autobuild`,
+`/ops:integration-sync` y `/ops:integration-promote`.
+
+Gemini no anuncia hooks nativos en este adaptador: los guards se ejecutan como prechecks indicados por el
+protocolo y los comandos. Esta degradación está declarada en `manifest.json`, no se simula protección inexistente.
+
+Comprueba la instalación con `node tools/ops.js automation doctor . gemini`.

package/automatization/runners/gemini/commands/ops/autobuild.toml

@@ -0,0 +1,7 @@
+description = "Ejecuta el siguiente hito aprobado siguiendo Cauce"
+prompt = """
+Lee AGENTS.md y planning/PROTOCOL.md completos. Ejecuta el ciclo de autobuild fase por fase sobre la primera
+tarea aprobada, respetando AWAITING_REVIEW y WIP como mutex. Antes de cada operación peligrosa invoca el
+guard correspondiente de automatization/hooks/ con el JSON de herramienta esperado. No hagas push ni deploy.
+Detente en el checkpoint entre hitos y deja evidencia real en DONE.
+"""

package/automatization/runners/gemini/commands/ops/integration-promote.toml

@@ -0,0 +1,6 @@
+description = "Promueve localmente un candidato de integración revisado"
+prompt = """
+Lee integrations/README.md y planning/PROTOCOL.md. Interpreta {{args}} como '<provider> <remote-key>'. Exige
+un draft ready, ejecuta integration check, promote y el check final mediante tools/ops.js. Nunca escribas en
+el proveedor remoto ni modifiques BACKLOG, WIP o DONE.
+"""

package/automatization/runners/gemini/commands/ops/integration-sync.toml

@@ -0,0 +1,6 @@
+description = "Sincroniza un proveedor externo hacia staging sin escribir remoto"
+prompt = """
+Lee integrations/README.md y planning/PROTOCOL.md. Resuelve el proveedor solicitado en {{args}}; si está
+vacío, continúa solo si existe exactamente uno habilitado. Ejecuta integration check, integration sync y el
+check final mediante tools/ops.js. Nunca promociones como efecto del sync ni edites snapshots a mano.
+"""

package/automatization/runners/gemini/manifest.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": 1,
+  "name": "gemini",
+  "command": "gemini",
+  "lifecycle": { "recommendedForNewProjects": false, "audience": "enterprise-cloud-api-key" },
+  "config": { "source": "settings.json", "target": ".gemini/settings.json" },
+  "instructions": [{ "source": "GEMINI.md", "target": "GEMINI.md" }],
+  "artifacts": [
+    { "source": "commands/ops/autobuild.toml", "target": ".gemini/commands/ops/autobuild.toml" },
+    { "source": "commands/ops/integration-sync.toml", "target": ".gemini/commands/ops/integration-sync.toml" },
+    { "source": "commands/ops/integration-promote.toml", "target": ".gemini/commands/ops/integration-promote.toml" }
+  ],
+  "capabilities": { "nativeHooks": false, "nativeWorkflows": false, "projectInstructions": true, "checkpointing": true }
+}

package/automatization/runners/gemini/settings.json

@@ -0,0 +1,9 @@
+{
+  "general": {
+    "checkpointing": { "enabled": true }
+  },
+  "context": {
+    "fileName": ["AGENTS.md", "GEMINI.md"],
+    "loadFromIncludeDirectories": true
+  }
+}

package/automatization/workflows/README.md

@@ -0,0 +1,38 @@
+# Workflows
+
+## Build
+
+`autobuild.js` implementa las fases de `planning/PROTOCOL.md`: checkpoint, recuperación desde WIP, Pick,
+Ready, descomposición, Plan, Critique, Build, Review, Verify, QA, Commit, Done y cierre. Persiste WIP antes
+de editar código y respeta el checkpoint entre hitos.
+
+El workflow no contiene rutas, servicios ni proveedores de un producto. Lee `ops.config.json`, utiliza el
+`service` declarado por cada tarea y limita el trabajo a `workspaceRoots`.
+
+```text
+ops.config.json + planning/PROTOCOL.md
+                 ↓
+automatization/workflows/autobuild.js   (fuente canónica)
+                 ↓ automation install
+.claude/workflows/autobuild.js          (adaptador ejecutable)
+```
+
+Claude dispone actualmente del formato ejecutable usado por este archivo. Codex y Gemini conservan el
+mismo protocolo y los mismos hooks, pero no se anuncia un workflow nativo hasta disponer de una API
+equivalente; en esos runners el recorrido se ejecuta siguiendo `planning/PROTOCOL.md`.
+
+## Integración externa
+
+`integrations/sync.js` ejecuta `integration check`, luego `integration sync`, valida el resultado y se detiene
+para revisión humana. `integrations/promote.js` exige proveedor, clave y un draft `ready`. Ninguno escribe en
+el sistema remoto; Jira es actualmente el primer adaptador del contrato general.
+
+```bash
+OPS_INTEGRATION_PROVIDER=jira /integration-sync
+OPS_INTEGRATION_PROVIDER=jira OPS_INTEGRATION_KEY=KEY-123 /integration-promote
+```
+
+## Aprendizaje de agentes
+
+Genera informes y propuestas; nunca modifica automáticamente un `SKILL.md`. Toda actualización exige
+evaluación y aprobación humana.