Documentación de Gentle AI

Gentle AI equipa a los agentes de IA que ya usás con memoria persistente, desarrollo guiado por especificación, skills curadas, servidores MCP, ruteo de modelos, una persona orientada a la enseñanza y revisión nativa acotada.

Estable v3.4.0Go 1.25.10+Licencia MIT16 agentes soportados

Qué es Gentle AI

Es un configurador de ecosistema. Toma tu agente de IA y le agrega las piezas que le faltan para dejar de ser un chatbot que escribe código.

La regla de oro

Gentle AI configura tu agente con memoria, skills, flujos y persona — y después se corre del camino. Según su propia documentación: cuanto menos pienses en Gentle AI después de instalarlo, mejor está funcionando.

Instalación

Requisitos previos

• Git 2.38+ en todas las plataformas.
• Go 1.25.10+ para compilar desde el código fuente (obligatorio en Windows, porque ahí se instala vía go install).
• Node.js 18+ y npm: gentle-ai install los verifica como requisito en toda plataforma y avisa con una sugerencia de instalación específica de tu distro si falta alguno. No los instala por vos.
• macOS: Homebrew en el PATH. Si el tap pide confianza, corré una vez brew trust --formula gentleman-programming/tap/gentle-ai.
• Ubuntu/Debian, Arch, Fedora/RHEL: el gestor de paquetes correspondiente (apt-get, pacman, dnf) y acceso sudo.
• Pi: si seleccionás el agente Pi, pi tiene que estar instalado y disponible en el PATH.

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bash

Homebrew

brew tap Gentleman-Programming/homebrew-tap
brew trust --formula gentleman-programming/tap/gentle-ai
brew install gentle-ai

Go install (cualquier plataforma con Go 1.25.10+)

go install github.com/gentleman-programming/gentle-ai/v3/cmd/gentle-ai@latest

Fijate en el sufijo /v3 en la ruta del módulo: Go lo exige para la versión mayor 2 en adelante. Los releases anteriores a v2.0.0 usan la ruta sin sufijo.

Alcance de instalación

Por defecto, gentle-ai install escribe los archivos por agente en el directorio de configuración global de cada agente seleccionado. Para mantener el stack aislado a un solo proyecto:

gentle-ai install --scope=workspace

El alcance workspace aplica a los archivos por agente: prompts de sistema, skills, agentes SDD y archivos de persona se escriben en la raíz del proyecto actual cuando el agente soporta configuración local. Las integraciones que solo existen a nivel global — como instalación de paquetes o settings que el agente solo lee de su config global — siguen siendo globales por diseño. También se puede fijar con la variable de entorno GENTLE_AI_INSTALL_SCOPE para CI o uso no interactivo.

Contexto del proyecto

Una vez configurados tus agentes, abrí el agente en un proyecto. Estos dos comandos registran el contexto del proyecto. Ninguno es obligatorio para el uso básico.

Solo un flujo SDD seleccionado explícitamente puede correr /sdd-init automáticamente cuando necesita contexto. Los tests detectables no activan Strict TDD: resolvé su modo, fuente y runner exacto desde la configuración del proyecto/sesión o una elección explícita. Los hooks de arranque normalmente mantienen fresco el registro de skills en los agentes que soportan hooks — Codex, Claude Code, OpenCode y Pi a través de gentle-pi. Si arrancás Pi con pi -ns, se saltea la carga de skills y los hooks de inicio, así que ahí conviene refrescar el registro a mano.

En cualquier momento podés correr gentle-ai doctor, un chequeo de salud de solo lectura del ecosistema.

Componentes, skills y presets

Componentes

Lista de rutas sensibles denegadas por defecto

El componente de permisos aplica esta lista de negación:

~/.ssh/*            ~/.ssh/**/*        **/*.pem
**/*.key            **/.env*           ~/.credentials/*
~/.aws/credentials  ~/.config/gh/hosts.yml
~/Library/Keychains/*                  **/secrets/*
**/*.p12            **/*.pfx

Presets

La persona se selecciona por separado en su propia pantalla y se aplica de forma independiente del preset.

Engram — memoria persistente

Engram es la memoria persistente de tu agente. Guarda decisiones, descubrimientos, arreglos de bugs y contexto entre sesiones, de forma automática. El agente administra todo vía herramientas MCP.

Comandos del día a día

# Navegar memorias visualmente: buscar, filtrar, entrar a cada observación
engram tui

# Buscar desde la terminal sin abrir la TUI
engram search "refactor de auth"

# Exportar memorias del proyecto a .engram/ para commitearlas a git
engram sync

engram tui es la forma más rápida de ver qué viene guardando tu agente. Empezá por ahí.

Gestión de proyectos

Engram agrupa memorias por nombre de proyecto, autodetectado desde tu remoto de git desde la v1.11.0. A veces un mismo proyecto termina con nombres duplicados ("my-app" vs "My-App" vs "my-app-frontend"). Estos comandos lo arreglan:

engram projects list          # Lista todos los proyectos con su conteo de observaciones
engram projects consolidate   # Fusiona nombres duplicados de forma interactiva

El equivalente MCP es mem_merge_projects, que el agente puede llamar directamente cuando detecta deriva de nombres.

Cómo funciona la detección de proyecto

Desde la v1.11.0, Engram lee la URL del remoto de git al arrancar, la normaliza a minúsculas y la usa como nombre del proyecto. Si encuentra nombres existentes parecidos, te avisa. Esto previene el problema más común: que el mismo proyecto acumule memorias bajo variantes ligeramente distintas del nombre. Si trabajás fuera de un repo git, Engram usa el nombre del directorio.

Compartir con el equipo

Las memorias de Engram viven localmente por defecto. Para compartirlas vía git:

# Después de una sesión de trabajo: exportá las memorias a .engram/ en tu repo
engram sync

# En otra máquina: importá las memorias después de clonar
engram sync --import

Agregá .engram/ al repo y commiteálo. Cuando alguien del equipo clona y corre engram sync --import, obtiene el contexto completo del proyecto. Es especialmente útil para onboarding: quien recién entra arranca con el conocimiento acumulado del equipo.

Herramientas MCP principales

Las herramientas avanzadas — mem_update, mem_suggest_topic_key, mem_session_start/mem_session_end, mem_stats, mem_delete, mem_timeline, mem_capture_passive y mem_merge_projects — rara vez hacen falta, pero están disponibles.

SDD — desarrollo guiado por especificación

SDD es un flujo de planificación estructurada para funcionalidades sustanciales. Tiene fases, pero no necesitás aprender ninguna.

Las diez fases

A eso se suma Judgment Day (judgment-day): revisión adversarial en paralelo donde dos jueces independientes revisan el mismo objetivo.

Dónde viven los artefactos

Los artefactos de SDD pueden persistirse en tres modos:

• Engram — memoria entre sesiones.
• OpenSpec — archivos versionados en el repositorio.
• Híbrido — ambos.

Sub-agentes: más inteligentes de lo que parecen

Cuando el orquestador delega trabajo a un sub-agente, ese sub-agente no es un ejecutor tonto corriendo un script. Es un agente completo, con su propia sesión, herramientas y contexto.

1. El orquestador los mantiene enfocados. Resuelve el registro de skills una vez, pasa las rutas relevantes de SKILL.md dentro del prompt de cada sub-agente y le da un rol concreto. Los sub-agentes leen los archivos de skill exactos en lugar de recibir resúmenes generados.
2. Se adaptan a tu proyecto. Un sdd-apply trabajando sobre React recibe patrones de React. El mismo sub-agente sobre Go recibe convenciones de testing de Go. Las reglas dependen del registro y del contexto de la tarea, no de una lista hardcodeada.
3. Persisten artefactos de fase cuando el backend lo soporta. En flujos SDD respaldados por Engram, los agentes de fase guardan artefactos antes de retornar. La fase siguiente puede continuar desde la propuesta, spec, diseño, tareas o progreso de apply guardados — incluso entre sesiones.

SDD Research — evidencia opcional

La investigación es trabajo opcional de solo lectura para una incertidumbre nombrada. Puede informar ODD o SDD seleccionado explícitamente, pero no es una fase ni un contrato administrativo de SDD.

Cómo usarla

Planteá la pregunta y usá solo herramientas que estén disponibles y autorizadas. Priorizá fuentes primarias cuando respondan la pregunta; no infieras acceso por el nombre de una herramienta ni por una clase de fuente no disponible. Cuando se delega, el colector dedicado es un colector de evidencia solo de salida: no lee artefactos locales ni estado del repositorio, y el orquestador aporta el contexto de código.

Qué devuelve

Devolvé evidencia concisa y atribuida: los claims materiales enlazan URLs de fuentes o ubicaciones de código y distinguen hechos verificados, supuestos, contradicciones, frescura y brechas explícitas. El padre maneja cualquier persistencia autorizada según las prácticas existentes del proyecto.

Cómo informa una propuesta

La investigación aporta una recomendación, tradeoffs, preguntas abiertas e implicancias de implementación. La evidencia faltante se revela en vez de inventarse; solo pausa una decisión insegura que dependa de ella. No crea una fase, contrato, grant de admisión, requisito de persistencia, gate de preparación ni bloqueo de propuesta de SDD.

OpenSpec — openspec/config.yaml

openspec/config.yaml es una convención documentada a nivel proyecto para SDD cuando trabajás en modo de persistencia openspec o hybrid.

Qué se puede personalizar

• Contexto del proyecto reutilizado entre fases.
• Activación de TDD estricto.
• Reglas específicas por fase para propuesta, specs, diseño, tareas, apply, verify y archive.
• Overrides de comandos y cobertura usados por los prompts de apply/verify.
• Caché de capacidades de testing detectadas para los flujos de apply/verify.

Qué fases lo referencian

Ejemplo de estructura

Combinando el documento de convención compartida, la guía de sdd-init y las referencias de apply/verify, la estructura práctica de nivel superior se ve así:

schema: spec-driven

context: |
  Tech stack: ...
  Architecture: ...
  Testing: ...
  Style: ...

strict_tdd: true

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then for scenarios
  design:
    - Document architecture decisions with rationale
  tasks:
    - Keep tasks completable in one session
  apply:
    - Follow existing code patterns
  verify:
    test_command: ""
    build_command: ""
    coverage_threshold: 0
  archive:
    - Warn before merging destructive deltas

testing:
  strict_tdd: true
  detected: "YYYY-MM-DD"
  runner:
    command: "go test ./..."
    framework: "Go standard testing"

Tomalo como una síntesis práctica de los campos que la capa de prompts puede leer o emitir hoy, no como una definición estricta de esquema.

Inconsistencias conocidas

La forma del archivo todavía no es uniforme. En los ejemplos actuales:

• sdd-init muestra rules.apply y rules.verify como listas planas de instrucciones.
• El documento de convención compartida muestra rules.apply con tdd y test_command, y rules.verify con claves de override estructuradas.
• sdd-apply/strict-tdd.md se refiere a rules.apply.test_command.
• sdd-verify se refiere a rules.verify.test_command, rules.verify.build_command y rules.verify.coverage_threshold.

Es decir: rules.apply y rules.verify se tratan hoy como si pudieran contener claves estructuradas, mientras otros ejemplos muestran esas mismas reglas de fase como listas planas.

Strict TDD

Resolvé Strict TDD desde la configuración del proyecto/sesión o una elección explícita, con su fuente y runner exacto. El soporte de testing detectable por sí solo no lo activa.

• Cuando está activado, observá RED → GREEN → REFACTOR: agregá un test de comportamiento enfocado, observá su falla, implementá el cambio mínimo y mantené verdes los chequeos enfocados al mejorar la claridad.
• Cuando está desactivado, corré chequeos funcionales ordinarios; desactivar TDD nunca significa no chequear.
• Registrá y pasá a la implementación el modo resuelto, la fuente y el runner exacto. En este proyecto, openspec/config.yaml configura Strict TDD y npx playwright test es el runner.
• El modo desconocido o conflictivo, o falta el runner, falla de forma cerrada hacia una aclaración para la próxima acción. No inventes precedencia, un comando ni una corrida de /sdd-init.

En Pi, los assets de soporte viven en .pi/gentle-ai/support/strict-tdd.md y .pi/gentle-ai/support/strict-tdd-verify.md.

Skills y registro de skills

Dos capas de skills

Gentle AI instala skills de SDD y skills de base (flujo de trabajo, patrones de testing) directamente en el directorio de skills de tu agente. Están embebidas en el binario y siempre actualizadas. Son 22 archivos de skill.

Para skills de código — React 19, Angular, TypeScript, Tailwind 4, Zod 4, Playwright, etc. — la comunidad mantiene un repositorio aparte: Gentleman-Programming/Gentleman-Skills. Esas se instalan a mano:

git clone https://github.com/Gentleman-Programming/Gentleman-Skills.git
cp -r Gentleman-Skills/curated/react-19 ~/.claude/skills/
cp -r Gentleman-Skills/curated/typescript ~/.claude/skills/
# ... o copiá el directorio curated/ completo

Una vez instaladas, el agente detecta sobre qué estás trabajando y carga las skills relevantes automáticamente. No hace falta activarlas ni invocarlas.

Skills de base incluidas

El registro de skills

El registro es un índice local del proyecto que permite que todos los agentes soportados encuentren las mismas skills sin reescribirlas. Guarda nombres, descripciones completas, alcances y rutas exactas de SKILL.md.

gentle-ai skill-registry refresh
# Solo si necesitás explícitamente volver a escanear todo:
gentle-ai skill-registry refresh --force
gentle-ai skill-registry refresh --cwd /ruta/al/proyecto --quiet

Flujo de refresco

gentle-ai skill-registry refresh
   │
   ├─ Escanea primero las raíces de skills del proyecto
   │     skills/, .opencode/skills/, .claude/skills/, .github/skills/, ...
   │
   ├─ Escanea después las raíces globales del agente
   │     ~/.config/opencode/skills/, ~/.claude/skills/, ...
   │
   ├─ Deduplica por nombre de skill
   │     la skill del proyecto gana sobre la global
   │
   ├─ Parsea el frontmatter
   │     name + description completa + path + scope
   │
   └─ Escribe .atl/skill-registry.md + caché

Flujo en runtime

Tarea del usuario
   │
   ▼
El orquestador lee .atl/skill-registry.md
   │
   ▼
Compara tarea + contexto de archivos contra las descripciones completas
   │
   ▼
Pasa las rutas exactas de SKILL.md al sub-agente
   │
   ▼
El sub-agente lee las skills completas antes de trabajar
   │
   ▼
El sub-agente ejecuta con la intención original de la skill intacta

Contrato del registro

Skills excluidas

El registro nunca indexa _shared, skill-registry, ni ninguna skill sdd-*. Las dos primeras son plomería interna; las sdd-* las administra el flujo de SDD, no el delegador. La exclusión es intencional y silenciosa, así que una skill de usuario cuyo nombre colisione con estos prefijos se descarta sin aviso.

Inspeccionar sin escribir

gentle-ai skill-registry list          # name<TAB>scope<TAB>path
gentle-ai skill-registry list --json   # legible por máquina, incluye descripciones

La caché usa un fingerprint que incluye la versión de esquema más la ruta, mtime y tamaño de cada SKILL.md descubierto, así que un arranque normal es un cache-hit barato cuando las skills no cambiaron.

Personas

custom es una elección de compatibilidad y propiedad, no un editor de personas. Usalo cuando ya tenés tus propias instrucciones de persona y querés que Gentle AI las deje en paz.

Ruteo orgánico de implementación

Pedí el resultado. Gentle AI mantiene inline el trabajo ya comprendido, delega solo las acciones que se benefician de contexto fresco, y crea artefactos formales de SDD solo después de un pedido explícito o una propuesta aceptada.

• Para trabajo autorizado sustancial, ODD persiste la continuidad en odd/tasks/<feature>.md con un espejo en Engram, y después retoma el trabajo sin terminar desde esos registros reconciliados.
• ODD usa el modo TDD configurado resuelto y su runner exacto. La sola presencia de tests no activa TDD silenciosamente.
• Cada tarea ODD completada cierra con un work-unit commit revisable en la rama de la funcionalidad.
• Cuando RDD está activado, cada commit se evalúa contra el último límite revisado: los commits de alto riesgo se revisan de inmediato, el trabajo de riesgo medio se acumula en slices de PR revisables, y se aplica una estrategia de PRs encadenados cuando hace falta.

Cuando se dispara un trigger de la tabla de Reglas de parada de la delegación, delegar es obligatorio; la tabla define esos triggers sin cambiar la ruta de implementación.

Las tres rutas

Los conteos de archivos describen el contexto necesario para la acción actual, no un puntaje de riesgo ni un umbral de SDD. El riesgo puede fortalecer la verificación nativa o la revisión, pero nunca fuerza SDD.

La delegación también aplica por acción: tests, builds, instalaciones y actores nativos de revisión pueden usar workers frescos sin cambiar la ruta de implementación ni crear una corrida de SDD. El trabajo directo y el delegado no crean artefactos de SDD, intentos de fase ni ciclos SDD sintéticos.

Si un trabajo aparentemente simple revela ambigüedad sustancial, Gentle AI la resuelve en ODD con investigación, aclaración o Necesita tu decisión; no ofrece ni selecciona artefactos formales de SDD por ambigüedad sola.

Reglas de parada de la delegación

El orquestador debe dejar de actuar como ejecutor monolítico cuando aparece complejidad. Estos disparadores son obligatorios, no opcionales:

Estados públicos

La interacción normal reporta solo cuatro estados. El usuario no elige internos de revisión, hashes, receipts ni transiciones de ciclo de vida.

La proyección de estado de SDD es el contrato gentle-ai.sdd-status/v2. El estado de runtime lleva la verdad de planificación, tareas, verificación, selected-untracked e intentos, y no proyecta bindings de revisión activos ni receipts. Los registros históricos de runtime que contienen binding, receipt o binding/set rechazan en lugar de reproducirse.

Una pregunta es necesaria solo cuando la respuesta cambia el alcance pedido, el impacto destructivo o irreversible, la exposición de permisos o seguridad, el costo de verificación o efectos secundarios externos, el riesgo residual aceptado, o la entrega.

RDD — Receipt-Driven Development

RDD revisa un candidato terminado sin apropiarse de la entrega. Es deliberadamente chico: el código nativo congela un candidato de worktree, coordina la revisión acotada, quema la autoridad completada y devuelve el control al humano.

El modelo en tres frases

Prender y apagar RDD

gentle-ai review mode status --cwd <repo>
gentle-ai review mode enable --scope global --cwd <repo>
gentle-ai review mode disable --cwd <repo>
gentle-ai review mode disable --scope clone --cwd <repo>
gentle-ai review mode enable  --scope clone --cwd <repo>

Cualquier fuente en estado desactivado gana. Un clon puede optar por salirse, pero no puede exigirle revisión al usuario, así que el alcance global es la única forma de entrar. Sin ninguna fuente expresando una opinión, el modo efectivo es off, reportado como decidido por default.

Los arranques interactivos preguntan antes del trabajo de revisión, una vez por clon. Aceptar registra esa elección; "ahora no" aplica solo a ese candidato y no cambia el modo de revisión. Los arranques no interactivos de tier-1/tier-2 proceden sin preguntar y reportan cómo desactivar el modo de revisión.

Mientras RDD está desactivado, el trabajo continúa por ruteo directo inline, delegado directo o SDD opcional, sin iniciar, reintentar ni reactivar la revisión por cuenta propia. Los gates nativos de entrega reportan disabled/unmanaged cuando no aplica ningún receipt exacto, y nunca fabrican una aprobación.

El ciclo atómico

STATUS sin selector → START exacto → colección acotada → captura terminal → aprobado pendiente de acuse exacto → el acuse quema la autoridad → política ordinaria del repositorio

Un resultado terminal de reviewer, refuter, validator, plan de corrección o zero-lens registra approved; la autoridad aprobada queda pendiente de su acuse exacto. No hay un paso FINALIZE separado. No sobrevive ningún receipt compacto ni autoridad de entrega.

1. STATUS sin selector solo hace preflight

STATUS sin selector evalúa únicamente el candidato del worktree actual y renderiza una invocación START exacta. No descubre autoridad ambiente, no retoma otro worktree, no recupera historia ni selecciona un linaje viejo. El padre corre solo la next_transition devuelta y sus tokens ordenados.

gentle-ai review status \
  --cwd <repo> \
  --contract gentle-ai.review-integration/v2 \
  --agent claude-code \
  --next-transition

Esto evita que una autoridad histórica, un worktree hermano o una respuesta de ciclo de vida obsoleta dirijan el candidato actual.

2. START congela una transacción independiente

START congela el candidato en una transacción compacta, explícitamente atada a su linaje, worktree y objetivo. Selecciona riesgo y lentes de forma nativa. El padre captura los tokens de lineage, revision y target devueltos.

Un replay exacto de un START activo puede devolver replayed. Un START genuinamente nuevo es independiente. Un linaje quemado nunca se reutiliza.

3. Las llamadas atadas manejan la transacción

Cada STATUS y review capture-result posterior lleva esos tokens exactos. Tras la aprobación terminal, STATUS atado vuelve a ofrecer el mismo acuse mientras la autoridad queda pendiente. El padre rutea únicamente desde la next_transition devuelta:

Un forecast es descriptivo, no una ruta. Se relata completo, pero se ejecuta solo next_transition.

4. La aprobación espera acuse

El código nativo devuelve approved con una continuación de acuse exacta. Solo la continuación de acuse exacta quema la autoridad: valida el linaje, objetivo, revisión y token atados, y luego elimina esa autoridad y sus artefactos. Un acuse incorrecto, obsoleto o fallido no muta nada; STATUS atado vuelve a ofrecer la continuación pendiente. No sobrevive ningún receipt compacto ni autoridad de entrega. Otros linajes y worktrees quedan intactos.

Continuidad entre repositorios

Una sesión con raíz en el repositorio A puede revisar un objetivo anidado — explícitamente autorizado por el usuario — en un repositorio B no relacionado. Go resuelve la ruta pedida a la raíz canónica de worktree de B; los adaptadores permanecen opacos y nunca parsean autorización ni raíces.

Este ciclo de vida está disponible únicamente para Claude Code, Codex, OpenCode y Pi. Los runtimes no soportados fallan antes de cualquier mutación de repositorio o autoridad.

Riesgo y lentes

START clasifica el riesgo una sola vez a partir de evidencia del repositorio y lo congela. Una corrección no puede recalcular el riesgo hacia abajo para escapar de la revisión, ni hacia arriba para fabricar más trabajo.

Esa forma de 0, 1 o 4 es control estructural de costos. Un cambio de solo documentación no debería pagar cuatro llamadas amplias al modelo. Un cambio de código normal se beneficia de un pase enfocado. Autenticación, pagos, tokens de servicio, rutas sensibles a seguridad o un cambio grande merecen cuatro perspectivas independientes.

Las lentes son de solo lectura

Cada lente seleccionada es de solo lectura y está separada de la autoría. Lee el candidato, juzga una preocupación, emite un resultado JSON estricto y para. Ninguna lente edita archivos, genera un corrector ni avanza el estado del ciclo de vida. Como dice el Capítulo 21: el jurado no es el contratista.

Los revisores reciben contexto inmutable emitido por el proveedor, no estado vivo del workspace. Inspeccionan solo los árboles inmutables atados por el proveedor: nunca el worktree vivo, el índice, el HEAD ni otra revisión. Los bytes del candidato no deben pasar por /tmp, un archivo scratch del repositorio ni GENTLE_AI_FROZEN_CANDIDATE_CONTEXT.

La forma de un resultado de revisor

{
  "findings": [
    {
      "location": "internal/auth/token.go:84",
      "severity": "CRITICAL",
      "claim": "the candidate accepts an expired service token",
      "proof_refs": [
        "TestExpiredToken passes on base and fails on candidate"
      ],
      "evidence_class": "deterministic",
      "causal_disposition": "introduced"
    }
  ],
  "evidence": [
    "inspected the complete candidate diff and ran the focused differential test"
  ]
}

La omisión es deliberada: sin ID de finding, sin nombre de lente, sin hash, sin metadata de linaje. El facade ya sabe qué resultado de lente llegó en qué posición seleccionada. Go completa los IDs faltantes, canonicaliza el orden, valida la prueba requerida y rechaza campos desconocidos. Un modelo es bueno para afirmaciones y evidencia; es una pésima elección para construir bytes canónicos.

Evidencia independiente

La opinión de revisión y la evidencia de verificación son cosas distintas. Una lente puede decir "los tests parecen adecuados". La evidencia dice go test ./... salió con éxito, el build completó, los ejemplos de aceptación pasaron.

Corrección acotada

Solo los findings severos causados por el candidato pueden bloquear. Los preexistentes o de solo base se convierten en seguimientos; lo desconocido escala; WARNING y SUGGESTION quedan como información.

Una revisión compacta ordinaria permite exactamente una transacción de corrección. START congela su presupuesto en 0 para cero líneas originales; si no, en max(2, min(200, ceil(original_changed_lines / 2))). La fórmula anterior min(200, ceil(original_changed_lines / 2)) queda para autoridad histórica y no compacta.

• Antes de editar se da un forecast positivo, y se continúa solo por la siguiente transición devuelta por el proveedor.
• Después de la edición acotada, se corre un validador de arreglo de solo lectura, únicamente cuando el input de colección exacto lo pide.
• Un validador que no puede inspeccionar los árboles inmutables no tiene veredicto. Hay que reportar ese bloqueo en lugar de enviar una validación fallida: un chequeo inconcluso registrado como fallido consume el único intento de corrección de forma irreversible.
• Una vez aceptado el intento — incluso con un delta medido de cero líneas — la corrección ordinaria queda agotada. Un cambio posterior requiere un sucesor autorizado.
• Las observaciones posteriores son seguimientos, no otra corrección.

Entrega y gates

Los receipts compactos y sus gates de entrega están retirados. La entrega sigue la política ordinaria del repositorio, y ningún estado de receipt cuenta como aprobación.

gentle-ai review validate y sus gates nombrados — post-apply, pre-commit, pre-push, pre-pr y release — sobreviven solo como comandos de compatibilidad e información. Nunca descubren autoridad ni deciden la entrega:

Nunca permiten, aprueban, bloquean, commitean, pushean ni abren un pull request.

Proyecciones del candidato

gentle-ai review start usa por defecto la proyección workspace. Para un monorepo o un worktree compartido, se puede revisar exactamente lo que está en el índice de Git:

git add apps/mi-servicio
git diff --cached
gentle-ai review start --projection staged

La proyección staged congela el índice existente completo, incluidas todas las rutas ya stageadas. Excluye el contenido no stageado y sin trackear del worktree, y no modifica el índice ni el worktree vivos al derivar evidencia. Una proyección solo elige qué bytes se congelan en START: los receipts compactos están retirados, así que ninguna proyección emite uno.

Una autoridad existente nunca se convierte automáticamente entre proyecciones. La recuperación hereda la proyección del predecesor cuando se omite --projection.

Códigos de parada

Un stop lleva exactamente un código de razón y ninguna transición ejecutable. Estos son algunos de los códigos más frecuentes y su continuación:

Para cada salida con alcance de clon, gentle-ai review mode disable --scope clone --cwd <repo> devuelve la entrega a la política ordinaria del repositorio. Ningún código de parada se resuelve cambiando de runtime, proveedor o toolchain.

Límites de confianza

El modelo mental viene del Capítulo 21 — Verifiable Trust:

"El modelo juzga el candidato. El facade construye la autoridad. El gate re-deriva la verdad."

La separación central: Go hace el trabajo determinista, el modelo hace el trabajo de juicio. El modelo no inventa un ID de linaje, no calcula hashes, no serializa payloads de operación para quince transiciones de estado, no congela ledgers a mano ni construye contextos de gate.

Qué protege el modelo de amenazas — y qué no

El store compacto de revisión protege la autoridad válida de corrupción accidental y escritores concurrentes. No pretende autenticar el estado contra un actor local malicioso con el mismo usuario y acceso al sistema de archivos: sin un ancla de confianza externa, ese actor puede reescribir el estado, el receipt, el repositorio Git o el binario.

Controles retenidos

• Validación estricta de esquema y semántica antes de aceptar o reemplazar autoridad.
• Validación de transiciones legales contra el estado actualmente bloqueado y la evidencia derivada del repositorio.
• Reemplazo atómico de archivos, con sincronización de archivo y directorio donde sea practicable.
• Un lock de escritor y una revisión esperada para detectar escritores concurrentes.
• Un lock de mantenimiento compartido en <git-common-dir>/gentle-ai/REVIEW-MAINTENANCE.lock, fuera del subárbol de autoridad reemplazable. Coordina solo participantes cooperativos de Gentle AI; no es una defensa contra un actor malicioso del mismo usuario.
• Reconocimiento de reintentos exactos para operaciones idempotentes.
• Re-derivación de contexto desde Git vivo en lugar de confiar en espejos persistidos.
• Checksums solo donde son útiles para detectar corrupción accidental: no son autenticación.

Esquemas de entrada

Se pueden imprimir los esquemas JSON versionados:

gentle-ai review schema reviewer
gentle-ai review schema refuter
gentle-ai review schema validator
gentle-ai review schema verification-evidence-record
gentle-ai review schema final-verification-incident

La evidencia de verificación cruda sigue siendo bytes arbitrarios no vacíos, pero por sí sola nunca es autoridad de resultado. La captura nativa persiste un registro estricto gentle-ai.review-verification-evidence/v2 con un resultado cerrado y bindings inmutables de candidato, revisión, payload, ruta y ledger.

Mantenimiento del store de revisión

El acuse exitoso quema y elimina la autoridad aprobada. Los linajes retenidos, abiertos o degradados pueden acumularse en un clon de vida larga, por eso el reset sigue disponible para la autoridad que todavía existe.

Elimina candidate-views/ y los subárboles v1, v2, quarantine, effect-markers e incidents de review-transactions/.

Preserva el interruptor de RDD — tanto en review-mode/ como en el espejo previo a #2882 — junto con sdd-runtime/, defect-reports/, review-artifacts/, incidents/ y REVIEW-MAINTENANCE.lock. Las revisiones que estaban apagadas siguen apagadas. La lista es una lista de permitidos, así que cualquier ruta que el comando no reconozca — incluida una que agregue un release futuro — se reporta y se deja en su lugar en lugar de adivinar.

Retiene reviews/, el store de grafo que escribe el adaptador de gentle-pi, y solo lo elimina con --include-adapter-reviews. Una corrida por defecto no puede distinguir un grafo muerto de una revisión viva, y un comando destructivo no borra lo que no puede garantizar.

La TUI expone la misma acción como Reset review store en el menú principal, entre Manage backups y Managed uninstall, con el cursor de confirmación arrancando en Cancel. La TUI no tiene equivalente de --include-in-flight ni --include-adapter-reviews: cuando existen revisiones abiertas se niega e imprime la invocación de CLI, para que destruir trabajo en vuelo nunca esté a una sola tecla de distancia.

Flujo orgánico completo

ODD sigue siete etapas: autorizar el pedido, explorar, resolver la incertidumbre, clasificar el trabajo, registrar el trabajo sustancial antes de la primera escritura, implementar tarea por tarea y cerrar con resultados verificados.

flowchart TD
    A["1. Autorizar
cambio o pedido de solo lectura"] --> B{"¿Implementación
autorizada?"}
    B -->|"no"| Z["Resultado de solo lectura"]
    B -->|"sí"| C["2. Explorar
código y requisitos"]
    C --> D["3. Resolver la incertidumbre
investigación, aclaración o desafío"]
    D --> E["4. Clasificar
chico o sustancial"]
    E -->|"sustancial"| F["5. Registrar antes de la primera escritura
documento de funcionalidad + espejo en Engram"]
    E -->|"chico"| G["6. Implementar tarea por tarea
TDD configurado + chequeos aplicables"]
    F --> G
    G --> H["7. Cerrar
resultado verificado, chequeos, próximo paso"]

    style H fill:#2B3328,stroke:#98BB6C,color:#DCD7BA
    style Z fill:#1F1F28,stroke:#54546D,color:#727169

Flujo SDD completo

Primero los artefactos durables de planificación y después apply. Verify es opcional y no bloquea Archive. Puede sugerir volver a Apply, pero cualquier reporte puede avanzar a Archive con el estado real. Archive puede registrar trabajo sin terminar cuando el usuario lo elige. SDD nunca invoca RDD. El archivado y la entrega siguen la política ordinaria del repositorio.

flowchart TD
    A["sdd-new / sdd-explore
(o sdd-ff para adelantar la planificación)"] --> B["Explorar
investigar código y enfoques"]
    B --> C["Proponer
intención - alcance - enfoque"]
    C --> D{"¿El usuario aprueba
la propuesta?"}
    D -->|"no"| B
    D -->|"sí"| E["Spec
requerimientos + escenarios"]
    E --> F["Diseño
decisiones de arquitectura"]
    F --> G["Tareas
checklist ordenado"]
    G --> H["Apply
el sub-agente implementa
contra las specs"]
    H --> Q["Verify opcional
diagnósticos prácticos contra
spec - diseño - tareas"]
    H --> R["Archive
fusiona delta-specs - cierra el ciclo"]
    Q -->|"sugiere rehacer"| H
    Q -->|"reporta findings"| R
    Q -->|"completa"| R
    R --> S["Política ordinaria del repositorio"]
    S --> T["Commit → Push → PR"]

    style R fill:#2B3328,stroke:#98BB6C,color:#DCD7BA
    style T fill:#43242B,stroke:#D27E99,color:#DCD7BA

Matriz de agentes compatibles

Compatibilidad con SDD multimodo

Todos los agentes soportan el orquestador de SDD y SDD de modo único. El multi-modo — asignar modelos distintos a cada fase de SDD — lo soportan:

• OpenCode y Kilo Code, a través del overlay multi-modo compatible con OpenCode.
• Kiro IDE, a través del frontmatter model: de subagentes nativos.
• Pi, donde el multi-modo es propiedad de los paquetes: gentle-pi instala agentes y cadenas SDD en .pi/agents/ y .pi/chains/, y los overrides de modelo viven en esos archivos o pasos de cadena.

Todos los demás se ejecutan en modo único: el orquestador gestiona todo con el modelo que el agente ya está usando. El modo único no es una limitación: es la opción predeterminada más simple y funciona bien. El modo multimodo es útil cuando se desea equilibrar deliberadamente el costo, la velocidad o el razonamiento por fase.

Modelos de delegación

Notas por agente

Claude Code

• Sub-agentes vía la herramienta nativa Task con ventanas de contexto aisladas.
• Servidores MCP configurados como plugins en ~/.claude/mcp/.
• Output styles en ~/.claude/output-styles/.
• Prompt de sistema vía secciones markdown en ~/.claude/CLAUDE.md.

OpenCode

• Overlay multi-agente completo con 11 agentes nombrados en opencode.json: gentle-orchestrator más 10 agentes de fase SDD.
• Slash commands para las fases de SDD (/sdd-new, /sdd-explore, etc.).
• La ejecución en background administrada se configura con --opencode-background-subagents=auto|on|off o la variable GENTLE_AI_OPENCODE_BACKGROUND_SUBAGENTS. La precedencia de CLI es: flag, entorno no vacío, estado administrado previo, y después auto.
• Los jobs en background son locales al proceso y no durables, no tienen aislamiento de filesystem, y no deben usarse para fases dependientes ni escritores paralelos en un mismo worktree.
• Los modelos custom de opencode.json deben declarar tool_call: true explícitamente para aparecer como opciones seleccionables con capacidad SDD.
• Requisito para multimodo: primero conectá tus proveedores de IA y después ejecutá opencode models --verbose para inspeccionar los modelos descubiertos.
• Gentle AI pone el sharing de agentes SDD en disabled por defecto, por privacidad; los valores de share ya administrados por el usuario, como manual o auto, se preservan.
• El comportamiento de OpenCode V1 no cambia. OpenCode V2 beta usa su propio manejo nativo de configuración, plugins administrados y presentación beta.
• Las versiones desconocidas de OpenCode fallan de forma cerrada. La revisión RDD nativa en OpenCode V2 sigue sin estar disponible en v3.4.0.

Codex

• Agente nativo de CLI con config TOML en ~/.codex/config.toml.
• Perfiles de selección de modelo escritos como archivos separados en ~/.codex/<nombre>.config.toml. Los defaults de GPT-5.6 requieren Codex >= 0.144.0.
• Los tres carriles se dividen por lo que la fase realmente hace: sdd-strong razona sobre contexto que le entregan, sdd-mid escribe código en un loop agéntico donde el esfuerzo importa más que la fuerza bruta del modelo, y sdd-cheap hace transcripción estructurada con contexto corto y salida verificable — así que compra esfuerzo en lugar de un modelo más grande.
• La delegación multi-agente está activada por defecto: se escriben features.multi_agent = true, agents.max_threads = 4 y agents.max_depth = 2. Si la configuración o las herramientas nativas no están disponibles, la orquestación cae elegantemente a ejecución inline solo-agente.

Cursor

• Subagentes nativos en ~/.cursor/agents/sdd-{fase}.md (10 archivos). El Agent de Cursor autodelega al subagente correcto según el campo description del frontmatter YAML.
• sdd-explore y sdd-verify corren con readonly: false para poder inspeccionar el código y ejecutar comandos de verificación.
• Skills en ~/.cursor/skills/, prompt de sistema en ~/.cursor/rules/gentle-ai.mdc, MCP en ~/.cursor/mcp.json.

Kiro IDE

• Detección: por el binario kiro en el PATH. Un directorio de config solo no marca a Kiro como instalado.
• Archivo de steering en ~/.kiro/steering/gentle-ai.md con frontmatter inclusion: always.
• La config MCP siempre está en una raíz separada: ~/.kiro/settings/mcp.json.
• Flujo nativo de specs de Kiro: .kiro/specs/<feature>/requirements.md, design.md, tasks.md, con puertas de aprobación antes de las fases de apply y archive.
• Instalación solo manual desde kiro.dev/downloads.

Windsurf

• Corre como solo-agente y aprovecha funcionalidades nativas: Plan Mode (documentos de plan persistentes que se pueden @mencionar entre sesiones, ideal para artefactos de spec y diseño), Code Mode, y workflows nativos (sdd-new disponible en .windsurf/workflows/sdd-new.md).
• El orquestador rutea las tareas por caminos de decisión Chico/Mediano/Grande.

Hermes

• Detect-only: Gentle AI no puede instalar Hermes. Instálelo manualmente primero y después ejecute gentle-ai install --agent hermes.
• La delegación efímera se ajusta en ~/.hermes/config.yaml bajo la clave delegation: max_spawn_depth (2), max_concurrent_children (4), max_iterations, child_timeout_seconds, inherit_mcp_toolsets (false) y subagent_auto_approve (false).
• Los toolsets, servidores MCP y skills no se heredan automáticamente del padre: hay que pasarlos explícitamente en la misión.
• La salida del worker se trata como auto-reporte: hay que verificar escrituras de archivos, resultados de tests, URLs y efectos externos antes de reportar éxito.

Perfiles SDD de OpenCode

Permiten asignar modelos distintos a fases distintas de SDD: uno potente para diseño, uno rápido para implementación, uno barato para exploración. OpenCode usa gentle-orchestrator como conductor SDD base.

# Crear un perfil "cheap" con un modelo gratuito para todas las fases
gentle-ai sync --profile cheap:openrouter/qwen/qwen3-30b-a3b:free

# Sobrescribir la fase de diseño con un modelo más fuerte
gentle-ai sync --profile-phase cheap:sdd-design:anthropic/claude-sonnet-4-20250514

# Crear varios perfiles en un solo comando
gentle-ai sync \
  --profile cheap:openrouter/qwen/qwen3-30b-a3b:free \
  --profile premium:anthropic/claude-sonnet-4-20250514

Después de crear un perfil, abra OpenCode y presione Tab para cambiar entre gentle-orchestrator y sus perfiles personalizados.

Si prefiere un gestor de perfiles en runtime que mantenga los perfiles fuera de opencode.json, Gentle AI también lo admite: durante el sync, OpenCode puede detectar automáticamente archivos de perfil externos en ~/.config/opencode/profiles/*.json y cambiar a una ruta de compatibilidad más segura que preserva el prompt activo de gentle-orchestrator en lugar de sobrescribirlo. Se activa con --sdd-profile-strategy external-single-active.

Pi y el harness gentle-pi

Instalación

Pi debe estar instalado y disponible como pi en el PATH. Después:

gentle-ai install --agent pi
pi

Si Pi es el único agente seleccionado, el instalador igualmente provisiona el componente real de Engram, pero omite las preguntas sobre persona, selección de componentes del ecosistema y Strict TDD, porque gentle-pi gestiona esas decisiones dentro de Pi.

Paquetes que instala

pi install npm:gentle-pi
pi install npm:gentle-engram
pi install npm:pi-mcp-adapter
npm exec --yes --package gentle-engram@latest -- pi-engram init
pi install npm:@juicesharp/rpiv-ask-user-question
pi install npm:pi-web-access
pi install npm:pi-btw

Descubrir y correr agentes SDD desde .pi/agents/ lo proveen los Gentle Agents de gentle-pi, que incluyen las mismas herramientas subagent_* que proveía el paquete complementario retirado. Cuando un archivo de settings fija gentle-pi por debajo de 2.5.0, Gentle AI conserva npm:pi-subagents-j0k3r. Para una instalación actual o sin pin, o un pin de gentle-pi en 2.5.0 o posterior, elimina npm:pi-subagents-j0k3r y npm:@juicesharp/rpiv-todo de settings.json en la próxima instalación o actualización para que Pi los desinstale en su próxima sincronización de paquetes.

Comandos de Pi

Asignación de modelos recomendada

Archivos del proyecto

En un session_start normal, gentle-pi copia recursos locales del proyecto sin sobrescribir ediciones locales:

.pi/agents/sdd-*.md
.pi/chains/sdd-*.chain.md
.pi/gentle-ai/support/strict-tdd.md
.pi/gentle-ai/support/strict-tdd-verify.md

Solución de problemas

Referencia de CLI

TUI interactiva

gentle-ai

La TUI Bubbletea guía la selección de agentes, componentes, skills, presets y flujos de desinstalación administrada. Antes de modificar cualquier archivo administrado, Gentle AI crea un snapshot de backup.

install

# Ecosistema completo para varios agentes
gentle-ai install \
  --agent claude-code,opencode,gemini-cli \
  --preset full-gentleman

# Setup mínimo para Cursor
gentle-ai install --agent cursor --preset minimal

# Elegir componentes y skills específicos
gentle-ai install \
  --agent claude-code \
  --component engram,sdd,skills,context7,persona,permissions \
  --skill go-testing,skill-creator,branch-pr,issue-creation \
  --persona gentleman

# Vista previa sin aplicar cambios
gentle-ai install --dry-run --agent claude-code,opencode --preset full-gentleman

Al instalar un solo agente con --agent X, Gentle AI fusiona el agente nuevo en la lista installed_agents existente de state.json y preserva cualquier model_assignments existente. No sobrescribe el estado completo.

Flags de install

sync

Refresca los assets administrados a la versión actual. Ejecútelo después de reemplazar o actualizar el binario, incluso con brew upgrade, gentle-ai upgrade o go install. No reinstala binarios: solo actualiza contenido de prompts, skills, configs MCP y orquestadores SDD.

gentle-ai sync --dry-run                          # Vista previa del alcance
gentle-ai sync                                     # Agentes registrados en state.json
gentle-ai sync --agent claude-code --agent opencode # Solo agentes específicos

Sync es seguro e idempotente: ejecutarlo dos veces no produce cambios la segunda vez. No soporta --component; para los componentes opt-in excluidos del alcance por defecto se usan --include-permissions e --include-theme.

Flags de sync

uninstall

Quita solo la configuración administrada por Gentle AI de uno o más agentes. No desinstala paquetes ni binarios externos. Antes de aplicar cualquier cambio se crea un snapshot de backup.

gentle-ai uninstall --agent claude-code --agent opencode
gentle-ai uninstall --agent claude-code --component sdd,persona,context7
gentle-ai uninstall --all
gentle-ai uninstall --agent cursor --component skills --yes

Si no se pasa --component en una desinstalación parcial, se quitan todos los componentes desinstalables administrados del conjunto de agentes seleccionado.

update / upgrade

gentle-ai update    # Chequea si hay una versión más nueva
gentle-ai upgrade   # Actualiza al último release

Después de cualquier actualización o reemplazo manual del binario, ejecute gentle-ai sync.

Si GitHub limita por tasa los chequeos de actualización, exporte GITHUB_TOKEN o GH_TOKEN antes de ejecutar update/upgrade.

doctor

gentle-ai doctor

Diagnóstico de salud de solo lectura: no hace ningún cambio en la configuración.

Cada chequeo reporta pass, warn o fail, con una sugerencia de remedio opcional. Ejecute doctor primero cuando algo sea distinto de lo esperado.

Flujo de trabajo típico

# Primera vez: instalar todo
brew install gentleman-programming/tap/gentle-ai
gentle-ai install --agent claude-code,cursor --preset full-gentleman

# Después de un release nuevo: actualizar y sincronizar
brew upgrade gentle-ai
gentle-ai sync

# Quitar solo la config administrada de SDD y persona de un agente
gentle-ai uninstall --agent claude-code --component sdd,persona

# Agregar un agente nuevo más adelante
gentle-ai install --agent windsurf --preset full-gentleman

Backups y rollback

El sistema de backups toma un snapshot de los archivos de configuración antes de cada install, sync y upgrade. Los backups son comprimidos, deduplicados y podados automáticamente.

Cómo funciona

1. Calcula un checksum de todos los archivos que se van a respaldar.
2. Omite el backup si sería idéntico al más reciente (deduplicación).
3. Crea un snapshot comprimido (snapshot.tar.gz) con todos los archivos de config.
4. Poda los backups viejos: mantiene los 5 más recientes y borra el resto.

Contenido del snapshot

• manifest.json — metadata: origen, timestamp, cantidad de archivos, checksum, estado de pin.
• snapshot.tar.gz — archivo comprimido con todos los archivos respaldados.
• Para rutas que no existían antes de la operación, el manifest registra existed=false.

Política de retención

Gestión desde la TUI

Comportamiento de restauración

• Si existed=true: restaura el archivo del snapshot a su ruta original.
• Si existed=false: elimina el archivo, revirtiendo archivos creados durante la instalación.
• La restauración es atómica por escritura de archivo: no hay restauraciones parciales.
• Funciona con backups comprimidos (tar.gz) y con los legacy anteriores a v1.16 (directorio files/ con copias planas).

Si la verificación falla

1. Revise los chequeos fallidos en el reporte de verificación.
2. Restaure desde el último snapshot vía la TUI o gentle-ai restore latest.
3. Vuelva a ejecutar install con --dry-run para validar el plan.
4. Vuelva a ejecutar install después de resolver las dependencias externas.

Verificación de releases

v3.4.0 publica ocho assets bajo un único manifiesto de checksums firmado: cuatro archivos .tar.gz de plataforma para macOS y Linux (amd64 y arm64), gentle-ai-review-provider-contract-1.2.0.tar.gz, el archivo de procedencia del release, checksums.txt y checksums.txt.minisig. El manifiesto cubre los seis archivos y está autenticado por la firma Minisign.

Los archivos oficiales de release para macOS y Linux requieren ese checksums.txt autenticado. El actualizador integrado verifica su firma Minisign, su binding exacto a Gentleman-Programming/gentle-ai más el tag del release, y el checksum del archivo seleccionado antes de reemplazar el binario instalado.

Los archivos de release tienen un tope de 128 MiB, incluidas respuestas por chunks o de longitud desconocida. Material de clave faltante, sobredimensionado, malformado, no confiable o de relleno falla de forma cerrada sin cambiar el binario instalado.

minisign -VQm checksums.txt -x checksums.txt.minisig -P "$GENTLE_AI_MINISIGN_PUBLIC_KEY"
# Comentario de confianza esperado en v3.4.0: repo=Gentleman-Programming/gentle-ai;tag=v3.4.0
sha256sum --check --strict --ignore-missing checksums.txt

Los archivos de Windows y la publicación en Scoop siguen omitidos hasta que se provisione firma Authenticode RSA de confianza pública, ambos ejecutables (amd64 y arm64) estén firmados antes de generar archivos y checksums, y la verificación de release falle si alguno de los dos está sin firmar. Hasta entonces, Windows se instala desde fuente con go install.

Política de versiones

v3.4.0 se publicó como estable el 2026-09-19. Esta página es un snapshot fijado de ese release; su contrato de proveedor permanece congelado byte a byte en 1.2.0.

@latest describe el canal estable y @main describe desarrollo sin release. Para este snapshot reproducible, instalá el release exacto: go install github.com/gentleman-programming/gentle-ai/v3/cmd/gentle-ai@v3.4.0.

Actualizar a v3.4.0

Novedades

• review assess informa candidate.consumed, review_due, review_due_reason y la next_transition exacta para el ruteo del host.
• Los roles de refutador y validador de Pi pasan a estar mediados por el host.
• Cada runtime prueba que su contexto entra en 200 KiB antes de START.

Cambio incompatible: se retira la integración RTK.

Seis fixes: relay de provider-task para lens-capture V1 de OpenCode; techo de scrape de 64 MiB en VictoriaMetrics; retención de deduplicación de telemetría y compactación diaria; ninguna configuración de OpenCode cuando no está seleccionado; test de descubrimiento nativo de Claude condicionado a CLI v2.1.154; y fixes para los tests de Windows Full Suite.

Después de reemplazar el binario, corré gentle-ai sync para instalar assets administrados compatibles. El contrato de proveedor 1.2.0 permanece congelado byte a byte.

Glosario

Candidato candidate

El conjunto exacto de bytes que se va a revisar. Existe antes de que empiece la revisión y queda congelado en START.

Linaje lineage

El identificador de una transacción de revisión. Se captura en START y se replica sin cambios en cada llamada atada, incluido el acuse pendiente. Un linaje quemado nunca se reutiliza.

Aprobación

El estado terminal approved pendiente de su acuse exacto. No es autoridad de entrega.

Receipt

Un registro terminal histórico. La revisión compacta no publica un receipt, y ningún receipt autoriza la entrega.

Lente lens

Un revisor de solo lectura que juzga una sola preocupación y emite un JSON estricto. Las cuatro canónicas son Riesgo, Resiliencia, Legibilidad y Confiabilidad (4R).

Quema burn

La eliminación de la autoridad exacta y sus artefactos después de que el acuse exacto tiene éxito. No es un receipt compacto ni autoridad de entrega.

Proyección projection

Qué congela START: workspace (todo el espacio de trabajo, default) o staged (exactamente el índice de Git).

Gate

Un punto de chequeo nombrado — post-apply, pre-commit, pre-push, pre-pr, release. Son comandos informativos y de compatibilidad: nunca permiten ni bloquean una entrega. Retirado en v2.5.0 junto con los receipts compactos.

Finding causado por el candidato

Un hallazgo que el cambio introdujo. Solo los severos de esta clase pueden bloquear. Los preexistentes se convierten en seguimientos.

Presupuesto de corrección

El límite de líneas para la única corrección compacta: 0 para cero líneas originales; si no, max(2, min(200, ceil(original_changed_lines / 2))). Se congela en START; la fórmula anterior aplica solo a autoridad histórica y no compacta.

Delta-spec

La especificación parcial de un cambio en curso. Al archivar, se fusiona con las specs principales del proyecto.

Escalado escalated

El estado de un linaje cuya corrección falló con evidencia. No se inicia otro revisor, refutador, corrección ni validador: requiere un sucesor autorizado vía review recover.

Documentación oficial

Esta página resume la documentación oficial de Gentle AI. Ante cualquier diferencia, la fuente de verdad son los documentos del repositorio enlazados arriba. Gentle AI se distribuye bajo licencia MIT.