@devrik-tools/claude-gates 0.7.2 → 0.9.0

package/.claude-plugin/marketplace.json

@@ -4,20 +4,20 @@
     "name": "claude-gates"
   },
   "metadata": {
-    "description": "Installable deterministic gates (hooks) for Claude Code, selectable per project or globally with `npx @devrik99/claude-gates init`."
+    "description": "Installable deterministic gates (hooks) for Claude Code, selectable per project or globally with `npx @devrik-tools/claude-gates init`."
   },
   "plugins": [
     {
       "name": "gates",
       "source": "./plugins/gates",
       "description": "PreToolUse gates: destructive-command blocks, protected paths, delegation/spec/quality rules, tool-discovery and forge-pipeline enforcement. Which gates run is decided by .ai/config.json (project) or ~/.claude/claude-gates/config.json (global).",
-      "version": "0.7.2"
+      "version": "0.9.0"
     },
     {
       "name": "tasks",
       "source": "./plugins/tasks",
       "description": "Deterministic task tracking: the model registers tasks via the CLI, a UserPromptSubmit hook reminds of open tasks every few messages, and a SessionStart hook lists active tasks when a session opens.",
-      "version": "0.7.2"
+      "version": "0.9.0"
     }
   ]
 }

package/README.es.md

@@ -30,7 +30,7 @@ npx @devrik-tools/claude-gates init
 
 Reinicia la sesión de Claude Code (o ejecuta `/plugin`) para que los hooks carguen.
 
-> **¿Por qué dos cosas?** El plugin **siempre trae los 41 gates**; la configuración decide
+> **¿Por qué dos cosas?** El plugin **siempre trae los 49 gates**; la configuración decide
 > **cuáles se ejecutan**. Así puedes prender uno sin reinstalar: es una línea en un JSON.
 
 ---
@@ -67,7 +67,7 @@ ejecución), así que funciona aunque instales uno suelto por fuera.
 
 ---
 
-## Los gates (30, en 7 familias)
+## Los gates (49, en 11 familias)
 
 `[on]` = encendidos por defecto; `[off]` = los prendes si los quieres.
 
@@ -79,6 +79,7 @@ ejecución), así que funciona aunque instales uno suelto por fuera.
 | `protected-paths` | on | Bloquea escrituras a `.env`, lockfiles y el propio harness. |
 | `root-whitelist` | on | Bloquea crear archivos/carpetas nuevos en la raíz fuera de la lista blanca. |
 | `no-blocking` | off | Bloquea `sleep`, `tail -f`, bucles de sondeo y servidores en primer plano. |
+| `require-monitor` | on | Bloquea un comando en background (`run_in_background: true`) que no declara su monitor con el marcador `MONITOR-PLANNED:`, y bloquea cualquier ejecución posterior mientras quede un background sin monitorear. |
 
 ### 🤝 Delegation — exigencias sobre el brief al delegar a un subagente
 | Gate | | Qué hace |
@@ -88,6 +89,7 @@ ejecución), así que funciona aunque instales uno suelto por fuera.
 | `risk-level` | off | Exige declarar el nivel (QUESTION/MICRO/STANDARD/HIGH-RISK). |
 | `circuit-breaker` | off | Corta la misma delegación reintentada sin cambios reales. |
 | `no-memory-dependency` | off | Bloquea un brief que depende de que el subagente "recuerde" la conversación (marcador `memory-not-needed` para un falso positivo). |
+| `force-parallel` | on | Bloquea la enésima delegación secuencial consecutiva dentro de una ventana de tiempo: las delegaciones independientes se lanzan juntas en un solo mensaje (marcador `SEQUENTIAL-JUSTIFIED` cuando la segunda depende de verdad de la primera). |
 
 ### 📋 Spec-driven flow — solo aplican si el proyecto adoptó desarrollo por specs
 | Gate | | Qué hace |
@@ -117,6 +119,8 @@ ejecución), así que funciona aunque instales uno suelto por fuera.
 | `atomic-commit` | off | Bloquea un `git commit` que no es atómico — que mezcla más de N naturalezas de cambio (código/tests/deps/config…) o stagea más archivos revisables de los que un commit debería llevar. Docs/imágenes/generados no cuentan. Marcador `[wip]` para un commit deliberadamente amplio. |
 | `no-coauthor` | on | Bloquea un `git commit` que lleve un trailer de atribución de IA (`Co-Authored-By`, `Generated with`, un trailer de sesión). Marcador `[allow-coauthor]` para un co-autor legítimo. |
 | `no-lint-suppression` | on | Bloquea una escritura que silencia el linter/type-checker (`eslint-disable`, `@ts-ignore`, una regla en `off`) en vez de arreglar el código. Marcador `lint-ok: <razón>` en la misma línea para un falso positivo documentado. |
+| `no-explanatory-comments`   | on  | Bloquea una escritura de código que agrega comentarios que narran qué hace el código. Solo pasan comentarios de decisión (el porqué, un trade-off, una limitación), directivas de herramientas, `TODO`/`FIXME` y etiquetas JSDoc con tipo. Juzga solo comentarios nuevos (diff contra disco). `comment-ok: <razón>` para una excepción documentada. |
+| `no-trivial-scripts` | on | Bloquea un script inline de intérprete que hace una operación de archivos que las herramientas `Edit`/`Write` resuelven directo (`node -e` con `writeFileSync`, `python -c` con `open(…, 'w')`, `sed -i`, `perl -i`, `Set-Content`/`Add-Content`). Los scripts inline que solo computan no caen. |
 
 ### 🔎 Tool discovery — no reinventar la rueda
 | Gate | | Qué hace |
@@ -124,11 +128,38 @@ ejecución), así que funciona aunque instales uno suelto por fuera.
 | `reuse-before-build` | off | Antes de construir una herramienta, consulta el mapa de herramientas del proyecto; bloquea si no auditaste (local → Context7 → web). |
 | `tool-map` | off | Registra las herramientas descubiertas en `.ai/tool-map.json` para no volver a explorar. |
 
+### 🧠 Research flow — la memoria primero, nunca adivinar una librería
+
+| Gate           |     | Qué hace                                                                                                                                                                                                                                                                                              |
+| -------------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `engram-first` | on  | Bloquea `WebSearch`, `WebFetch` y context7 hasta que en la sesión haya corrido un `mem_search` ([engram](https://github.com/Gentleman-Programming/engram) es la primera fuente); bloquea el Stop mientras hubo investigación sin un `mem_save` posterior; al arrancar avisa una vez si engram cloud está configurado y el proyecto no está enrolado. |
+| `library-docs` | on  | Bloquea una escritura que importa un paquete que el proyecto no usa en ningún lado, salvo que en esta sesión se haya consultado: un hit de engram sobre él, o docs de context7 seguidas de un `mem_save`. Nunca adivinar la API de una librería.                                                       |
+
 ### 🏭 Forge pipeline — obliga a seguir el flujo de forge
 | Gate | | Qué hace |
 |---|---|---|
 | `forge-flow` | off | En un proyecto que adoptó [forge](https://github.com/DevRik99/forge-mcp), bloquea editar/ejecutar si no hay un run de forge activo. Cierra el hueco que el MCP no puede: te obliga a pasar por el pipeline. |
 
+### 🤖 Autonomy — que una corrida sin supervisión decida en vez de preguntar
+
+| Gate | | Qué hace |
+|---|---|---|
+| `autonomous-mode` | off | Con el modo autónomo prendido, bloquea `AskUserQuestion` y bloquea que el turno termine solo para esperar: reinyecta, una vez por ciclo, la instrucción de decidir y seguir, dejando pendiente solo lo que de verdad necesita al usuario. |
+
+### ⏹️ Completion — el turno no termina con trabajo abierto
+
+| Gate | | Qué hace |
+|---|---|---|
+| `stop-pending` | on | Bloquea el evento Stop mientras el proyecto tiene tareas activas (`open`/`in_forge`); las lista y explica cómo cerrarlas con evidencia verificada o abandonarlas. Las tareas `blocked` no retienen el turno por defecto. |
+| `require-task-split` | on | Bloquea escrituras y ejecución mientras una tarea activa más grande que `small` no tenga sub-tareas registradas: primero se parte en piezas verificables por separado (`task add --parent <id>`). |
+
+### 🗂️ Task tracking — el plugin de tareas
+
+| Gate | | Qué hace |
+|---|---|---|
+| `remind-open-tasks` | on | Hace que el asistente clasifique y registre el trabajo nuevo por el CLI, y recita las tareas activas cada N mensajes. |
+| `list-tasks-on-session-start` | on | Lista las tareas activas del proyecto al abrir una sesión. Silencioso si no hay ninguna. |
+
 ### 🩺 Sesión y contexto — validaciones al arrancar e inyección de capacidades
 | Gate | | Qué hace |
 |---|---|---|
@@ -152,7 +183,7 @@ ves y editas cada perilla:
 ```json
 {
   "adopted": "partial",
-  "gateVersion": "3.0.0",
+  "gateVersion": "3.1.0",
   "gates": {
     "blockDestructiveShellCommands": {
       "enabled": true,
@@ -164,7 +195,17 @@ ves y editas cada perilla:
 }
 ```
 
-- **Apagar un gate:** `"enabled": false`. Se apaga al instante, sin reinstalar.
+- **Apagar un gate:** `"enabled": false`. Se apaga al instante, sin reinstalar. O desde el CLI:
+  `claude-gates disable <gate>` / `claude-gates enable <gate>` (ids de gate, claves de
+  configuración, ids de familia o `all`; `--project` o `--global`), y `claude-gates status`
+  para ver qué está prendido en el directorio actual y de dónde sale cada valor.
+- **Volver a correr `init` mergea, nunca pisa.** Un gate que ya está en el archivo solo cambia
+  si lo nombras (`--gates`, `--families`, `--all`, `--none`) y, cuando su `enabled` cambiaría,
+  lo confirmas gate por gate. Con `--yes` (sin TTY) se conservan los valores existentes y se
+  reportan; con `--force` se aplican sin preguntar.
+- **Un parámetro con el tipo equivocado nunca rompe un gate.** Un string donde se espera una
+  lista, o un regex mal escrito, cae al default incorporado y se reporta una vez por sesión
+  en el propio mensaje del gate (y en el log de decisiones).
 - **Ajustar su comportamiento:** editas sus parámetros (la lista blanca, los patrones, los
   umbrales). Lo que declara el proyecto **reemplaza** el default del gate.
 - Un gate que no aparece en la configuración usa su default del catálogo. Las claves que ya
@@ -175,8 +216,10 @@ ves y editas cada perilla:
   (una frase que no depende de memoria), `[allow-coauthor]` (un co-autor legítimo en un
   commit), `lint-ok: <razón>` (un falso positivo documentado del linter), `[skip-lint]`
   (saltea el chequeo de staged-lint por un commit), `[wip]` (permite un commit
-  deliberadamente amplio, no atómico). `dependency-skills` se exime vía su lista
-  `depsWithoutOwnApi`.
+  deliberadamente amplio, no atómico), `comment-ok: <razón>` (un comentario explicativo que
+  debe quedarse), `SEQUENTIAL-JUSTIFIED` (una delegación que sí depende de la anterior),
+  `MONITOR-PLANNED:` (el comando en background declara cómo se va a monitorear).
+  `dependency-skills` se exime vía su lista `depsWithoutOwnApi`.
 - **Inyección de capacidades:** `capability-map` (on por defecto) es totalmente ajustable —
   elegí qué tipos exponer (`"kinds": ["skills", "agents", "commands"]`), limitá cada blurb
   (`maxClauseChars`, default 120), agregá raíces extra por tipo, regulá cada cuánto se
@@ -197,6 +240,52 @@ ves y editas cada perilla:
 
 ---
 
+## Log de decisiones
+
+Cada deny, warn y bloqueo de Stop se agrega como una línea JSON a
+`<raíz>/.ai/gates-log.jsonl` (fecha, gate, clave de configuración, herramienta, un resumen de
+una línea de la acción, el motivo, la sesión). Se lee con:
+
+```bash
+claude-gates log                      # últimas 30 decisiones de este proyecto
+claude-gates log --deny --gate bash-commands --tail 100
+claude-gates log --since 2026-09-01T00:00:00Z --json
+```
+
+El archivo rota una vez a los 5 MB (`gates-log.1.jsonl`). `CLAUDE_GATES_LOG=0` lo desactiva.
+
+---
+
+## Tareas: se registran con criterio y se cierran con evidencia verificada
+
+Una tarea lleva su criterio de verificación **desde que se crea** — `task add` rechaza una
+tarea que nadie puede probar terminada — y `task close` rechaza texto libre: está hecha solo
+cuando la verificación pasa de verdad.
+
+```bash
+# Registrar: el criterio es obligatorio (--verify-command o --verify-path)
+claude-gates task add "migrar el cargador de configuración" \
+  --size medium --verify-command "npm test" --verify-expect "fail 0"
+claude-gates task add "escribir la guía de migración" \
+  --parent <id> --verify-path docs/migration.md --verify-contains "## Upgrading"
+
+claude-gates task list [--all]        # tareas activas (o todo el historial)
+
+# Cerrar: sin --check/--exists, se vuelve a correr el criterio propio de la tarea
+claude-gates task close <id>
+claude-gates task close <id> --check "npm test" --expect "fail 0" --note "suite en verde"
+claude-gates task close <id> --exists dist/report.html --contains "All green"
+claude-gates task abandon <id> --reason "obsoleta"
+claude-gates task promote <id> <runId>   # vincula la tarea a un run de forge
+```
+
+El resultado verificado (comando, código de salida, cola de la salida, fecha) queda guardado
+con la tarea. Dos gates se apoyan en este store: `require-task-split` bloquea implementar una
+tarea más grande que `small` sin sub-tareas, y `stop-pending` impide que el turno termine
+mientras queden tareas abiertas.
+
+---
+
 ## Comandos del CLI
 
 ```bash
@@ -206,12 +295,37 @@ npx @devrik-tools/claude-gates init
 # Sin menú (para CI o scripts):
 claude-gates init --project|--global  --defaults|--all|--none|--families a,b|--gates x,y  --yes  --dry-run
 claude-gates init --no-install        # escribe la configuración pero no instala el plugin
+claude-gates init --force             # aplica cambios a gates ya presentes sin preguntar
+
+# Prender, apagar e inspeccionar lo que corre aquí:
+claude-gates enable <gate|familia|all> [--project|--global]
+claude-gates disable <gate|familia|all> [--project|--global]
+claude-gates status                   # on/off efectivo por gate y su origen (project/global/default)
+claude-gates log [--tail N] [--deny] [--gate id] [--since iso] [--json]
+claude-gates doctor                   # ¿Claude Code corre ESTA versión del paquete?
+
+# Tareas (el store que leen los gates de completion):
+claude-gates task add <título> --size <tamaño> --verify-command <cmd>|--verify-path <ruta> [--parent <id>]
+claude-gates task list [--all]
+claude-gates task close <id> [--check <cmd> --expect <texto>] [--exists <ruta> --contains <texto>]
+claude-gates task abandon <id> --reason <texto>
+claude-gates task promote <id> <runId>
 
 # Inspeccionar el catálogo:
 claude-gates registry --list          # lista familias y gates
-claude-gates registry --check         # valida registry.json
+claude-gates registry --check         # valida registry.json y que hooks.json esté sincronizado
+claude-gates registry --sync-hooks    # regenera el hooks.json de cada plugin desde el registry
+
+# Verificar que los gates realmente reaccionan (no solo que están enganchados):
+claude-gates smoke                    # le da a cada gate una violación conocida; sale distinto de 0 si alguno no bloquea/avisa
 ```
 
+`smoke` es el chequeo de comportamiento que `registry --check` (estructura) y el hook doctor
+(que los archivos existan) no hacen: le da a cada gate una violación conocida y confirma que
+de verdad deniega o avisa. Los gates cuya violación necesita estado sembrado (una db, un repo
+git, estado entre llamadas) reportan `skip`, nunca un falso pase. Se corre después de
+instalar, o en CI, para detectar un gate enganchado que en silencio deja pasar todo.
+
 ---
 
 ## Estructura del repositorio
@@ -225,15 +339,18 @@ cli/                              El CLI de npm (commander + @clack/prompts + zo
   init.mjs · install.mjs          Flujo interactivo + instalar el plugin.
 plugins/gates/                    El plugin de gates.
   .claude-plugin/plugin.json
-  hooks/hooks.json                Una entrada por gate (matcher + comando). Lo carga Claude Code.
+  hooks/hooks.json                Generado desde registry.json (`registry --sync-hooks`). Lo carga Claude Code.
   hooks/lib/                      Código compartido de los hooks (Node built-ins only).
   hooks/gates/<id>/               Un gate por carpeta: index.mjs (la regla) + test.mjs (su test).
-plugins/tasks/                    El plugin de tareas (en construcción): persiste tareas por proyecto.
+plugins/tasks/                    El plugin de tareas: persiste tareas por proyecto, recuerda las abiertas
+                                  y las lista al arrancar la sesión.
 .claude-plugin/marketplace.json   Lista los plugins del marketplace.
 ```
 
 **Agregar un gate** = una carpeta en `plugins/gates/hooks/gates/<id>/` (con `index.mjs` y
-`test.mjs`) + una entrada en `registry.json`. El resto se deriva solo.
+`test.mjs`) + una entrada en `registry.json`, y luego `claude-gates registry --sync-hooks`.
+Los gates comparten `hooks/lib/` (lectura del payload, normalización de git, estado por
+sesión, vocabulario de delegación, el log de decisiones, el harness de tests): un gate es solo su regla.
 
 ---
 
@@ -245,7 +362,8 @@ npm run registry:check    # valida el catálogo
 npm run lint              # eslint (boundaries, no-magic-numbers, sonarjs, cspell…)
 ```
 
-Cada gate se testea aislado: `node --test plugins/gates/hooks/gates/<id>/test.mjs`.
+Cada gate se testea aislado: `node --test plugins/gates/hooks/gates/<id>/test.mjs`
+(nombra los archivos de test: un glob que también matchee `index.mjs` se cuelga, porque un gate espera stdin).
 
 > Este repositorio trae su propio `.ai/config.json` que apaga localmente los gates que
 > darían falso positivo al **editar los gates mismos** (por ejemplo, `audit-before-build`

package/README.md

@@ -29,7 +29,7 @@ npx @devrik-tools/claude-gates init
 
 Restart the Claude Code session (or run `/plugin`) so the hooks load.
 
-> **Why two things?** The plugin **always ships all 41 gates**; the config decides **which
+> **Why two things?** The plugin **always ships all 49 gates**; the config decides **which
 > ones run**. So you can turn one on without reinstalling — it is one line in a JSON file.
 
 ---
@@ -65,7 +65,7 @@ works even if you install one on its own.
 
 ---
 
-## The gates (in families)
+## The gates (49, in 11 families)
 
 `[on]` = enabled by default; `[off]` = enable it if you want it.
 
@@ -78,6 +78,7 @@ works even if you install one on its own.
 | `protected-paths`      | on  | Blocks writes to `.env`, lockfiles and the harness itself.                                                                                        |
 | `root-whitelist`       | on  | Blocks new root-level files/folders outside a whitelist.                                                                                          |
 | `no-blocking`          | off | Blocks `sleep`, `tail -f`, polling loops and foreground servers.                                                                                  |
+| `require-monitor`      | on  | Blocks a background command (`run_in_background: true`) that does not declare its monitor with a `MONITOR-PLANNED:` marker, and blocks further execution while an unmonitored background command is still pending. |
 
 ### 🤝 Delegation — requirements on the brief when delegating to a subagent
 
@@ -88,6 +89,7 @@ works even if you install one on its own.
 | `risk-level`            | off | Requires a declared level (QUESTION/MICRO/STANDARD/HIGH-RISK).                                                         |
 | `circuit-breaker`       | off | Cuts the same delegation retried without real changes.                                                                 |
 | `no-memory-dependency`  | off | Blocks a brief that relies on the subagent "remembering" the chat (add `memory-not-needed` to allow a false positive). |
+| `force-parallel`        | on  | Blocks the Nth consecutive sequential delegation inside a time window: independent delegations must be launched together in one message (add `SEQUENTIAL-JUSTIFIED` when the second one really depends on the first). |
 
 ### 📋 Spec-driven flow — only relevant if the project adopted spec-driven development
 
@@ -119,6 +121,8 @@ works even if you install one on its own.
 | `atomic-commit`             | off | Blocks a `git commit` that is not atomic — one mixing more than N natures of change (code/tests/deps/config…) or staging more reviewable files than a commit should carry. Docs/assets/generated aren't counted. Add `[wip]` for a deliberately broad commit. |
 | `no-coauthor`               | on  | Blocks a `git commit` carrying an AI/agent attribution trailer (`Co-Authored-By`, `Generated with`, a session trailer). Add `[allow-coauthor]` for one legitimate co-author. |
 | `no-lint-suppression`       | on  | Blocks a write that silences the linter/type-checker (`eslint-disable`, `@ts-ignore`, a rule set to `off`) instead of fixing the code. Add `lint-ok: <reason>` on the same line for a documented false positive. |
+| `no-explanatory-comments`   | on  | Blocks a code write that adds comments narrating what the code does. Only decision comments (why, trade-off, limitation), tool directives, `TODO`/`FIXME` and typed JSDoc tags pass. Judges only new comments (diff against disk). Add `comment-ok: <reason>` for a documented exception. |
+| `no-trivial-scripts`        | on  | Blocks an inline interpreter script that does a file operation the `Edit`/`Write` tool handles directly (`node -e` with `writeFileSync`, `python -c` with `open(…, 'w')`, `sed -i`, `perl -i`, `Set-Content`/`Add-Content`). Inline scripts that only compute are not caught. |
 
 ### 🔎 Tool discovery — don't reinvent the wheel
 
@@ -127,12 +131,39 @@ works even if you install one on its own.
 | `reuse-before-build` | off | Before building a tool, consults the project tool map; blocks if you did not audit (local → Context7 → web). |
 | `tool-map`           | off | Records discovered tools in `.ai/tool-map.json` so exploration is not repeated.                              |
 
+### 🧠 Research flow — memory first, never guess a library
+
+| Gate           |     | What it does                                                                                                                                                                                                                                                         |
+| -------------- | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `engram-first` | on  | Blocks `WebSearch`, `WebFetch` and context7 until a `mem_search` ran in the session ([engram](https://github.com/Gentleman-Programming/engram) is the first source); blocks the Stop event while research happened with no later `mem_save`; at session start warns once when engram cloud is configured but the project is not enrolled. |
+| `library-docs` | on  | Blocks a write that imports a package the project does not use anywhere yet unless this session looked it up: an engram hit about it, or context7 docs followed by a `mem_save`. Never guess a library API.                                                             |
+
 ### 🏭 Forge pipeline — enforces the forge workflow
 
 | Gate         |     | What it does                                                                                                                                                                                            |
 | ------------ | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `forge-flow` | off | In a project that adopted [forge](https://github.com/DevRik99/forge-mcp), blocks editing/running unless an active forge run exists. Closes the hole the MCP cannot: it forces you through the pipeline. |
 
+### 🤖 Autonomy — let an unattended run decide instead of asking
+
+| Gate               |     | What it does                                                                                                                                                                                                       |
+| ------------------ | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `autonomous-mode`  | off | With autonomous mode on, blocks `AskUserQuestion` and blocks a turn that ends only to wait: it re-injects, once per cycle, the instruction to decide and proceed, leaving pending only what genuinely needs the user. |
+
+### ⏹️ Completion — a turn does not end with work still open
+
+| Gate                 |     | What it does                                                                                                                                                                                     |
+| -------------------- | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `stop-pending`       | on  | Blocks the Stop event while this project has active tasks (`open`/`in_forge`); lists them and how to close them with verified evidence or abandon them. `blocked` tasks don't hold the turn by default. |
+| `require-task-split` | on  | Blocks writes and execution while an active task larger than `small` has no sub-tasks registered: split it into independently verifiable pieces first (`task add --parent <id>`).                     |
+
+### 🗂️ Task tracking — the tasks plugin
+
+| Gate                          |     | What it does                                                                                             |
+| ----------------------------- | --- | ---------------------------------------------------------------------------------------------------------- |
+| `remind-open-tasks`           | on  | Makes the assistant classify and register new work via the CLI, and recites the active tasks every N messages. |
+| `list-tasks-on-session-start` | on  | Lists this project's active tasks when a session opens. Silent when there are none.                          |
+
 ### 🩺 Session & context — startup checks and capability injection
 
 | Gate             |     | What it does                                                                                                                                                                                          |
@@ -157,7 +188,7 @@ see and edit every knob:
 ```json
 {
   "adopted": "partial",
-  "gateVersion": "3.0.0",
+  "gateVersion": "3.1.0",
   "gates": {
     "blockDestructiveShellCommands": {
       "enabled": true,
@@ -175,7 +206,17 @@ see and edit every knob:
 }
 ```
 
-- **Turn a gate off:** `"enabled": false`. Off instantly, no reinstall.
+- **Turn a gate off:** `"enabled": false`. Off instantly, no reinstall. Or from the CLI:
+  `claude-gates disable <gate>` / `claude-gates enable <gate>` (gate ids, config keys,
+  family ids or `all`; `--project` or `--global`), and `claude-gates status` to see what is
+  on for the current directory and where each value comes from.
+- **Re-running `init` merges, never overwrites.** A gate already in the file only changes
+  when you name it (`--gates`, `--families`, `--all`, `--none`) and, when its `enabled`
+  would flip, you confirm it gate by gate. With `--yes` (no TTY) the existing values are
+  kept and reported; pass `--force` to apply them without asking.
+- **A wrong-typed param never breaks a gate.** A string where a list is expected, or a
+  malformed regex, falls back to the built-in default and is reported once per session in
+  the gate's own message (and in the decision log).
 - **Tune its behavior:** edit its parameters (the whitelist, the patterns, the thresholds).
   What the project declares **replaces** the gate's default.
 - A gate absent from the config uses its catalog default. Keys you already had in the file
@@ -188,7 +229,10 @@ see and edit every knob:
   non-memory phrase), `[allow-coauthor]` (one legitimate co-author on a commit),
   `lint-ok: <reason>` (a documented linter false positive), `[skip-lint]` (skip the
   staged-lint check for one commit), `[wip]` (allow one deliberately broad,
-  non-atomic commit). `dependency-skills` opts out via its `depsWithoutOwnApi` list.
+  non-atomic commit), `comment-ok: <reason>` (one explanatory comment that must stay),
+  `SEQUENTIAL-JUSTIFIED` (a delegation that genuinely depends on the previous one),
+  `MONITOR-PLANNED:` (the background command declares how it will be monitored).
+  `dependency-skills` opts out via its `depsWithoutOwnApi` list.
 - **Capability injection:** `capability-map` (on by default) is fully tunable — pick which
   kinds to surface (`"kinds": ["skills", "agents", "commands"]`), cap each blurb
   (`maxClauseChars`, default 120), add extra roots per kind, throttle how often the full
@@ -208,6 +252,52 @@ see and edit every knob:
 
 ---
 
+## Decision log
+
+Every deny, warn and Stop-block is appended as one JSON line to
+`<root>/.ai/gates-log.jsonl` (timestamp, gate, config key, tool, a one-line summary of the
+action, the reason, the session). Read it with:
+
+```bash
+claude-gates log                      # last 30 decisions for this project
+claude-gates log --deny --gate bash-commands --tail 100
+claude-gates log --since 2026-09-01T00:00:00Z --json
+```
+
+The file rotates once at 5 MB (`gates-log.1.jsonl`). Set `CLAUDE_GATES_LOG=0` to disable it.
+
+---
+
+## Tasks: registered with a criterion, closed with verified evidence
+
+A task carries its verification criterion **from the moment it is created** — `task add`
+refuses a task nobody can prove done — and `task close` refuses free text: it is done only
+when the check actually passes.
+
+```bash
+# Register: the criterion is mandatory (--verify-command or --verify-path)
+claude-gates task add "migrate the config loader" \
+  --size medium --verify-command "npm test" --verify-expect "fail 0"
+claude-gates task add "write the migration guide" \
+  --parent <id> --verify-path docs/migration.md --verify-contains "## Upgrading"
+
+claude-gates task list [--all]        # active tasks (or the whole history)
+
+# Close: with no --check/--exists, the task's own verify criterion is re-run
+claude-gates task close <id>
+claude-gates task close <id> --check "npm test" --expect "fail 0" --note "suite green"
+claude-gates task close <id> --exists dist/report.html --contains "All green"
+claude-gates task abandon <id> --reason "obsolete"
+claude-gates task promote <id> <runId>   # link the task to a forge run
+```
+
+The verified result (command, exit code, output tail, timestamp) is stored with the task.
+Two gates lean on this store: `require-task-split` blocks implementing a task bigger than
+`small` that has no sub-tasks, and `stop-pending` blocks the turn from ending while tasks
+are still open.
+
+---
+
 ## CLI commands
 
 ```bash
@@ -217,10 +307,26 @@ npx @devrik-tools/claude-gates init
 # Non-interactive (for CI or scripts):
 claude-gates init --project|--global  --defaults|--all|--none|--families a,b|--gates x,y  --yes  --dry-run
 claude-gates init --no-install        # write the config but do not install the plugin
+claude-gates init --force             # apply changes to gates already in the file without asking
+
+# Toggle and inspect what runs here:
+claude-gates enable <gate|family|all> [--project|--global]
+claude-gates disable <gate|family|all> [--project|--global]
+claude-gates status                   # effective on/off per gate and its source (project/global/default)
+claude-gates log [--tail N] [--deny] [--gate id] [--since iso] [--json]
+claude-gates doctor                   # is Claude Code running THIS package version of the plugins?
+
+# Tasks (the store the completion gates read):
+claude-gates task add <title> --size <size> --verify-command <cmd>|--verify-path <path> [--parent <id>]
+claude-gates task list [--all]
+claude-gates task close <id> [--check <cmd> --expect <text>] [--exists <path> --contains <text>]
+claude-gates task abandon <id> --reason <text>
+claude-gates task promote <id> <runId>
 
 # Inspect the catalog:
 claude-gates registry --list          # list families and gates
-claude-gates registry --check         # validate registry.json
+claude-gates registry --check         # validate registry.json and that hooks.json is in sync
+claude-gates registry --sync-hooks    # regenerate each plugin's hooks.json from the registry
 
 # Verify the gates actually react (not just that they are wired):
 claude-gates smoke                    # feed each gate a known violation; exits non-zero if any does not block/warn
@@ -245,15 +351,18 @@ cli/                              The npm CLI (commander + @clack/prompts + zod)
   init.mjs · install.mjs          Interactive flow + install the plugin.
 plugins/gates/                    The gates plugin.
   .claude-plugin/plugin.json
-  hooks/hooks.json                One entry per gate (matcher + command). Loaded by Claude Code.
+  hooks/hooks.json                Generated from registry.json (`registry --sync-hooks`). Loaded by Claude Code.
   hooks/lib/                      Shared hook code (Node built-ins only).
   hooks/gates/<id>/               One gate per folder: index.mjs (the rule) + test.mjs (its test).
-plugins/tasks/                    The tasks plugin (work in progress): persists per-project tasks.
+plugins/tasks/                    The tasks plugin: persists per-project tasks, reminds of the open ones
+                                  and lists them on session start.
 .claude-plugin/marketplace.json   Lists the marketplace plugins.
 ```
 
 **Adding a gate** = one folder in `plugins/gates/hooks/gates/<id>/` (with `index.mjs` and
-`test.mjs`) + one entry in `registry.json`. Everything else derives automatically.
+`test.mjs`) + one entry in `registry.json`, then `claude-gates registry --sync-hooks`.
+Gates share `hooks/lib/` (payload readers, git normalization, session state, delegation
+vocabulary, the decision log, the test harness): a gate file is only its rule.
 
 ---
 
@@ -265,7 +374,8 @@ npm run registry:check    # validate the catalog
 npm run lint              # eslint (boundaries, no-magic-numbers, sonarjs, cspell…)
 ```
 
-Each gate is tested in isolation: `node --test plugins/gates/hooks/gates/<id>/test.mjs`.
+Each gate is tested in isolation: `node --test plugins/gates/hooks/gates/<id>/test.mjs`
+(name the test files: a glob that also matches `index.mjs` hangs, because a gate waits on stdin).
 
 > This repo ships its own `.ai/config.json` that locally disables the gates that would
 > false-positive when **editing the gates themselves** (e.g. `audit-before-build` thinks

package/cli/doctor.mjs

@@ -0,0 +1,132 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { REPOSITORY_ROOT } from './constants.mjs';
+
+const CLAUDE_BIN = 'claude';
+
+function runClaudeDefault(commandArguments) {
+  return execFileSync(CLAUDE_BIN, commandArguments, {
+    encoding: 'utf8',
+    stdio: 'pipe',
+  });
+}
+
+export function parsePluginList(listing) {
+  const plugins = [];
+  let current = null;
+  for (const line of listing.split(/\r?\n/)) {
+    const name = /^\s*(?:❯\s*)?([\w-]+)@([\w-]+)\s*$/.exec(line);
+    if (name) {
+      current = { plugin: name[1], marketplace: name[2] };
+      plugins.push(current);
+      continue;
+    }
+    if (!current) continue;
+    const version = /^\s*Version:\s*(\S+)/.exec(line);
+    if (version) current.version = version[1];
+    const scope = /^\s*Scope:\s*(\S+)/.exec(line);
+    if (scope) current.scope = scope[1];
+  }
+  return plugins;
+}
+
+export function parseMarketplaceSources(listing) {
+  const sources = {};
+  let current = null;
+  for (const line of listing.split(/\r?\n/)) {
+    const name = /^\s*(?:❯\s*)?([\w-]+)\s*$/.exec(line);
+    if (name) {
+      current = name[1];
+      continue;
+    }
+    const source = /^\s*Source:\s*(\w+)\s*\(([^)]+)\)/.exec(line);
+    if (source && current)
+      sources[current] = { kind: source[1], path: source[2] };
+  }
+  return sources;
+}
+
+function withoutTrailingSlashes(text) {
+  let end = text.length;
+  while (end > 0 && (text[end - 1] === '/' || text[end - 1] === '\\')) end -= 1;
+  return text.slice(0, end).toLowerCase();
+}
+
+function compareVersions(a, b) {
+  const left = String(a).split('.').map(Number);
+  const right = String(b).split('.').map(Number);
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const difference = (left[index] ?? 0) - (right[index] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  return 0;
+}
+
+export function diagnose({ runClaude = runClaudeDefault } = {}) {
+  const manifest = JSON.parse(
+    readFileSync(
+      join(REPOSITORY_ROOT, '.claude-plugin', 'marketplace.json'),
+      'utf8',
+    ),
+  );
+  const packageVersion = JSON.parse(
+    readFileSync(join(REPOSITORY_ROOT, 'package.json'), 'utf8'),
+  ).version;
+  const problems = [];
+  const facts = [`package: ${packageVersion} at ${REPOSITORY_ROOT}`];
+  let plugins;
+  let sources;
+  try {
+    plugins = parsePluginList(runClaude(['plugin', 'list']));
+    sources = parseMarketplaceSources(
+      runClaude(['plugin', 'marketplace', 'list']),
+    );
+  } catch (error) {
+    problems.push(
+      `could not query Claude Code (${error?.message ?? error}); is \`claude\` on PATH?`,
+    );
+    return { packageVersion, facts, problems };
+  }
+  const ours = plugins.filter((plugin) =>
+    manifest.plugins.some((declared) => declared.name === plugin.plugin),
+  );
+  if (ours.length === 0) {
+    problems.push(
+      'no claude-gates plugin is installed in Claude Code: run `claude-gates init --global --defaults --yes`',
+    );
+  }
+  for (const plugin of ours) {
+    facts.push(
+      `${plugin.plugin}@${plugin.marketplace} ${plugin.version} (${plugin.scope})`,
+    );
+    if (compareVersions(plugin.version, packageVersion) < 0) {
+      problems.push(
+        `${plugin.plugin} (${plugin.scope}) runs ${plugin.version} but this package is ${packageVersion}: ` +
+          'run `claude-gates init --global --defaults --yes` from this package to re-point the marketplace and reinstall',
+      );
+    }
+    const source = sources[plugin.marketplace];
+    if (source?.kind === 'Directory') {
+      const same =
+        withoutTrailingSlashes(source.path) ===
+        withoutTrailingSlashes(REPOSITORY_ROOT);
+      if (!same)
+        problems.push(
+          `marketplace "${plugin.marketplace}" serves from ${source.path}, not from this package (${REPOSITORY_ROOT})`,
+        );
+    }
+  }
+  return { packageVersion, facts, problems };
+}
+
+export function renderDiagnosis(report) {
+  const lines = report.facts.map((fact) => `  ${fact}`);
+  if (report.problems.length === 0) lines.push('\nAll good.');
+  else
+    lines.push(
+      '\nProblems:',
+      ...report.problems.map((problem) => `  - ${problem}`),
+    );
+  return `${lines.join('\n')}\n`;
+}