@devrik-tools/claude-gates 0.7.1 → 0.8.0

package/.claude-plugin/marketplace.json

@@ -11,13 +11,13 @@
       "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.1"
+      "version": "0.8.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.1"
+      "version": "0.8.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 44 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 (44, en 10 familias)
 
 `[on]` = encendidos por defecto; `[off]` = los prendes si los quieres.
 
@@ -117,6 +117,7 @@ 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. |
 
 ### 🔎 Tool discovery — no reinventar la rueda
 | Gate | | Qué hace |
@@ -124,6 +125,13 @@ 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 |
 |---|---|---|
@@ -164,7 +172,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 +193,8 @@ 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). `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 +215,36 @@ 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: cerrar exige evidencia verificada
+
+`task close` rechaza texto libre. Una tarea está hecha solo cuando una verificación pasa:
+
+```bash
+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"
+```
+
+El resultado verificado (comando, código de salida, cola de la salida, fecha) queda guardado con la tarea.
+
+---
+
 ## Comandos del CLI
 
 ```bash
@@ -206,10 +254,19 @@ 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?
 
 # 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
 ```
 
 ---
@@ -225,7 +282,7 @@ 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.
@@ -233,7 +290,9 @@ plugins/tasks/                    El plugin de tareas (en construcción): persis
 ```
 
 **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 +304,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 44 gates**; the config decides **which
 > ones run**. So you can turn one on without reinstalling — it is one line in a JSON file.
 
 ---
@@ -119,6 +119,7 @@ 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. |
 
 ### 🔎 Tool discovery — don't reinvent the wheel
 
@@ -127,6 +128,13 @@ 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                                                                                                                                                                                            |
@@ -175,7 +183,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 +206,8 @@ 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).
+  `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 +227,36 @@ 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: closing needs verified evidence
+
+`task close` refuses free text. A task is done only when a check passes:
+
+```bash
+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"
+```
+
+The verified result (command, exit code, output tail, timestamp) is stored with the task.
+
+---
+
 ## CLI commands
 
 ```bash
@@ -217,10 +266,19 @@ 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?
 
 # 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,7 +303,7 @@ 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.
@@ -253,7 +311,9 @@ plugins/tasks/                    The tasks plugin (work in progress): persists
 ```
 
 **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 +325,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`;
+}

package/cli/evidence.mjs

@@ -0,0 +1,78 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+
+const DEFAULT_TIMEOUT_MS = 120000;
+const OUTPUT_TAIL_LINES = 20;
+
+function tail(text) {
+  return String(text ?? '')
+    .split(/\r?\n/)
+    .filter((line) => line.length > 0)
+    .slice(-OUTPUT_TAIL_LINES)
+    .join('\n');
+}
+
+export function verifyCommand(
+  command,
+  { cwd, expect, timeoutMs = DEFAULT_TIMEOUT_MS } = {},
+) {
+  const result = spawnSync(command, {
+    cwd,
+    shell: true,
+    encoding: 'utf8',
+    timeout: timeoutMs,
+  });
+  const output = `${result.stdout ?? ''}${result.stderr ?? ''}`;
+  const exitCode = result.error ? null : result.status;
+  const failure = commandFailure(result, exitCode, output, expect);
+  return {
+    kind: 'command',
+    command,
+    expect: expect ?? null,
+    exitCode,
+    outputTail: tail(output),
+    verified: failure === null,
+    verifiedAt: new Date().toISOString(),
+    failure,
+  };
+}
+
+function commandFailure(result, exitCode, output, expect) {
+  if (result.error) return `could not run: ${result.error.message}`;
+  if (exitCode !== 0) return `exit code ${exitCode}`;
+  if (expect && !output.includes(expect))
+    return `output does not contain "${expect}"`;
+  return null;
+}
+
+export function verifyPath(path, { cwd, contains } = {}) {
+  const absolute = isAbsolute(path) ? path : join(cwd, path);
+  const exists = existsSync(absolute);
+  let containsFound = true;
+  if (exists && contains) {
+    try {
+      containsFound =
+        statSync(absolute).isFile() &&
+        readFileSync(absolute, 'utf8').includes(contains);
+    } catch {
+      containsFound = false;
+    }
+  }
+  const failure = pathFailure(path, exists, containsFound, contains);
+  return {
+    kind: 'path',
+    path,
+    contains: contains ?? null,
+    exists,
+    verified: failure === null,
+    verifiedAt: new Date().toISOString(),
+    failure,
+  };
+}
+
+function pathFailure(path, exists, containsFound, contains) {
+  if (!exists) return `"${path}" does not exist`;
+  if (!containsFound) return `"${path}" does not contain "${contains}"`;
+  return null;
+}

package/cli/hooks-manifest.mjs

@@ -0,0 +1,89 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { matcherFor } from '../plugins/gates/hooks/lib/hook-io.mjs';
+import { JSON_INDENT, REPOSITORY_ROOT } from './constants.mjs';
+import { allGates } from './registry.mjs';
+
+const DEFAULT_TIMEOUT_SECONDS = 30;
+const MATCHED_EVENTS = new Set(['PreToolUse', 'PostToolUse']);
+const PLUGIN_ROOT_VARIABLE = '${CLAUDE_PLUGIN_ROOT}';
+
+export function hooksJsonPathFor(pluginName) {
+  return join(REPOSITORY_ROOT, 'plugins', pluginName, 'hooks', 'hooks.json');
+}
+
+function hookEntry(script, timeoutSeconds, tools, event) {
+  const entry = {
+    hooks: [
+      {
+        type: 'command',
+        command: `node "${PLUGIN_ROOT_VARIABLE}/hooks/${script}"`,
+        timeout: timeoutSeconds,
+      },
+    ],
+  };
+  if (MATCHED_EVENTS.has(event)) entry.matcher = matcherFor(tools);
+  return MATCHED_EVENTS.has(event)
+    ? { matcher: entry.matcher, hooks: entry.hooks }
+    : entry;
+}
+
+export function buildHooksManifest(registry, pluginName) {
+  const hooks = {};
+  const pluginGates = allGates(registry).filter(
+    (gate) => gate.plugin === pluginName,
+  );
+  for (const gate of pluginGates) {
+    const timeoutSeconds = gate.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
+    const scripts = [
+      { event: gate.event, script: gate.script, tools: gate.tools },
+      ...(gate.extraScripts ?? []).map((extra) => ({
+        event: extra.event,
+        script: extra.script,
+        tools: extra.tools ?? gate.tools,
+      })),
+    ];
+    for (const { event, script, tools } of scripts) {
+      hooks[event] ??= [];
+      hooks[event].push(hookEntry(script, timeoutSeconds, tools, event));
+    }
+  }
+  return { hooks };
+}
+
+export function pluginNamesIn(registry) {
+  return [...new Set(allGates(registry).map((gate) => gate.plugin))];
+}
+
+function readManifestJson(pluginName) {
+  try {
+    return JSON.stringify(
+      JSON.parse(readFileSync(hooksJsonPathFor(pluginName), 'utf8')),
+    );
+  } catch {
+    return null;
+  }
+}
+
+export function hooksManifestDrift(registry) {
+  const drifted = [];
+  for (const pluginName of pluginNamesIn(registry)) {
+    const expected = JSON.stringify(buildHooksManifest(registry, pluginName));
+    if (readManifestJson(pluginName) !== expected) drifted.push(pluginName);
+  }
+  return drifted;
+}
+
+export function writeHooksManifests(registry) {
+  const written = [];
+  for (const pluginName of pluginNamesIn(registry)) {
+    const path = hooksJsonPathFor(pluginName);
+    writeFileSync(
+      path,
+      `${JSON.stringify(buildHooksManifest(registry, pluginName), null, JSON_INDENT)}\n`,
+      'utf8',
+    );
+    written.push(path);
+  }
+  return written;
+}