@devrik-tools/claude-gates 0.8.0 → 1.0.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.8.0"
+      "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.8.0"
+      "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 44 gates**; la configuración decide
+> **¿Por qué dos cosas?** El plugin **siempre trae los 50 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 (44, en 10 familias)
+## Los gates (50, 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 |
@@ -118,12 +120,14 @@ ejecución), así que funciona aunque instales uno suelto por fuera.
 | `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 |
 |---|---|---|
 | `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. |
+| `skill-first` | off | Bloquea una escritura/comando/delegación que una **skill** disponible cubre de forma plausible hasta que la pregunta se haya hecho: cargar la skill, o decir por qué no aplica (`no skill covers this` / `using the <name> skill`). Lee el mismo catálogo que inyecta `capability-map`. |
 
 ### 🧠 Research flow — la memoria primero, nunca adivinar una librería
 
@@ -137,6 +141,26 @@ ejecución), así que funciona aunque instales uno suelto por fuera.
 |---|---|---|
 | `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 |
 |---|---|---|
@@ -160,7 +184,7 @@ ves y editas cada perilla:
 ```json
 {
   "adopted": "partial",
-  "gateVersion": "3.0.0",
+  "gateVersion": "3.1.0",
   "gates": {
     "blockDestructiveShellCommands": {
       "enabled": true,
@@ -194,12 +218,17 @@ ves y editas cada perilla:
   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), `comment-ok: <razón>` (un comentario explicativo que
-  debe quedarse). `dependency-skills` se exime vía su lista `depsWithoutOwnApi`.
+  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`. `skill-first` se despeja
+  con una frase en el contenido/prompt: `no skill covers this`, o `using the <name> skill`.
 - **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
   re-inyecta el catálogo completo (`injectEveryMessages`, default 10 — el archivo persistido
-  se refresca igual en cada mensaje), o apagá la persistencia (`"persist": false`) y apuntá
+  se refresca igual en cada mensaje; el catálogo TAMBIÉN se re-inyecta a mitad del throttle
+  cuando cambia el tipo de trabajo del prompt, por ejemplo depurar → publicar, lo que podés
+  apagar con `"reinjectOnWorkNatureChange": false`), o apagá la persistencia (`"persist": false`) y apuntá
   el mapa a otro archivo (`mapFile`). Las skills también se escanean por defecto en
   `~/.agents/skills`, `<proyecto>/.agents/skills`, `~/.ai/skills` y `<proyecto>/.ai/skills`
   (raíces exclusivas de skills que usan otros instaladores además de `.claude/skills` — sin
@@ -231,17 +260,33 @@ El archivo rota una vez a los 5 MB (`gates-log.1.jsonl`). `CLAUDE_GATES_LOG=0` l
 
 ---
 
-## Tareas: cerrar exige evidencia verificada
+## Tareas: se registran con criterio y se cierran con evidencia verificada
 
-`task close` rechaza texto libre. Una tarea está hecha solo cuando una verificación pasa:
+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.
+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.
 
 ---
 
@@ -253,6 +298,8 @@ 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 --new               # SOLO los gates sobre los que esta config nunca decidió:
+                                      # actualizás sin volver a contestar ni tocar lo ya definido
 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
 
@@ -263,12 +310,57 @@ claude-gates status                   # on/off efectivo por gate y su origen (pr
 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 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.
+
+---
+
+## Artefactos generados
+
+Todo lo que un agente produce que **no es código fuente** — un chequeo determinista que
+escribió para que veas si algo funciona, una auditoría de lo que ya existe, una nota
+explicando qué hizo — tiene una sola forma y un solo lugar, así se encuentra por convención
+y se valida en CI en vez de caer donde al modelo se le ocurra.
+
+```bash
+claude-gates new check mi-afirmacion --title "..." --source "qué pidió esto"
+```
+
+| Tipo    | Vive en       | Para                                                                 |
+| ------- | ------------- | ---------------------------------------------------------------------- |
+| `check` | `.ai/checks/` | Una afirmación verificable: el comando, qué debe imprimir, y la evidencia que realmente imprimió. |
+| `audit` | `.ai/audits/` | Mirar antes de construir: buscado / existe / falta / decisión.       |
+| `note`  | `.ai/notes/`  | Razonamiento que si no quedaría solo en el chat.                     |
+
+Cuando la misma cosa sale mal dos veces, el registro es dato y no documento: se anota la
+**clase** de defecto en `.ai/reincidencias.json`, que `recurrence-lock` lee para bloquear
+trabajo mutante hasta que la clase se cierre de raíz.
+
+El contrato es `cli/artifacts.mjs`; las reglas completas están en
+[`.ai/README.md`](./.ai/README.md). Dos tests lo sostienen — uno cubre el módulo, el otro
+recorre el árbol `.ai/` real de este repo y falla ante cualquier artefacto desviado (sin
+front matter, en el directorio equivocado, sin una sección obligatoria, o un check marcado
+`passed` cuya evidencia sigue siendo el placeholder generado).
+
 ---
 
 ## Estructura del repositorio
@@ -285,7 +377,8 @@ plugins/gates/                    El plugin de gates.
   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.
 ```
 

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 44 gates**; the config decides **which
+> **Why two things?** The plugin **always ships all 50 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 (50, 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
 
@@ -120,6 +122,7 @@ works even if you install one on its own.
 | `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,6 +130,7 @@ 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.                              |
+| `skill-first`        | off | Blocks a write/command/delegation an available **skill** plausibly covers until the question was asked: load the skill, or say why it does not fit (`no skill covers this` / `using the <name> skill`). Reads the same catalog `capability-map` injects. |
 
 ### 🧠 Research flow — memory first, never guess a library
 
@@ -141,6 +145,26 @@ works even if you install one on its own.
 | ------------ | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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                                                                                                                                                                                          |
@@ -165,7 +189,7 @@ see and edit every knob:
 ```json
 {
   "adopted": "partial",
-  "gateVersion": "3.0.0",
+  "gateVersion": "3.1.0",
   "gates": {
     "blockDestructiveShellCommands": {
       "enabled": true,
@@ -206,13 +230,18 @@ 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), `comment-ok: <reason>` (one explanatory comment that must stay).
-  `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. `skill-first` clears on
+  one sentence in the content/prompt: `no skill covers this`, or `using the <name> skill`.
 - **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
   catalog is re-injected (`injectEveryMessages`, default 10 — the persisted map file itself
-  still refreshes every message), or turn off persistence (`"persist": false`) and point the
+  still refreshes every message; the catalog is ALSO re-injected mid-throttle whenever the
+  prompt's kind of work changes, e.g. debugging → releasing, which you can turn off with
+  `"reinjectOnWorkNatureChange": false`), or turn off persistence (`"persist": false`) and point the
   map file elsewhere (`mapFile`). Skills are also scanned by default under `~/.agents/skills`,
   `<project>/.agents/skills`, `~/.ai/skills` and `<project>/.ai/skills` (skill-only roots some
   installers use besides `.claude/skills` — no config needed), in addition to any
@@ -227,6 +256,35 @@ see and edit every knob:
 
 ---
 
+## Generated artifacts
+
+Everything an agent produces that is **not source code** — a deterministic check it wrote
+so you can see whether something works, an audit of what already exists, a note explaining
+what it did — has one shape and one home, so it can be found by convention and validated
+in CI instead of landing wherever the model felt like.
+
+```bash
+claude-gates new check my-claim --title "..." --source "what asked for this"
+```
+
+| Kind    | Lives in      | For                                                              |
+| ------- | ------------- | ------------------------------------------------------------------ |
+| `check` | `.ai/checks/` | One verifiable claim: the command, what it must print, the evidence it actually printed. |
+| `audit` | `.ai/audits/` | Looking before building: searched / exists / missing / decision.  |
+| `note`  | `.ai/notes/`  | Reasoning that would otherwise live only in a chat log.           |
+
+When the same thing goes wrong twice, the record is data rather than a document: register
+the defect **class** in `.ai/reincidencias.json`, which `recurrence-lock` reads to block
+mutating work until the class is closed at the root.
+
+The contract is `cli/artifacts.mjs`; the full rules are in
+[`.ai/README.md`](./.ai/README.md). Two tests keep it honest — one covers the module, the
+other walks this repo's own `.ai/` tree and fails on any artifact that drifted (missing
+front matter, wrong directory, a missing section, or a check marked `passed` whose
+evidence is still the generated placeholder).
+
+---
+
 ## Decision log
 
 Every deny, warn and Stop-block is appended as one JSON line to
@@ -243,17 +301,33 @@ The file rotates once at 5 MB (`gates-log.1.jsonl`). Set `CLAUDE_GATES_LOG=0` to
 
 ---
 
-## Tasks: closing needs verified evidence
+## Tasks: registered with a criterion, closed with verified evidence
 
-`task close` refuses free text. A task is done only when a check passes:
+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.
 
 ---
 
@@ -265,6 +339,8 @@ 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 --new               # ONLY gates this config never decided about — upgrade
+                                      # without re-answering or changing anything already set
 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
 
@@ -275,6 +351,13 @@ claude-gates status                   # effective on/off per gate and its source
 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 and that hooks.json is in sync
@@ -306,7 +389,8 @@ plugins/gates/                    The gates plugin.
   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.
 ```