@devrik-tools/claude-gates 0.4.0 → 0.7.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.4.0"
+      "version": "0.7.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.4.0"
+      "version": "0.7.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 30 gates**; la configuración decide
+> **¿Por qué dos cosas?** El plugin **siempre trae los 41 gates**; la configuración decide
 > **cuáles se ejecutan**. Así puedes prender uno sin reinstalar: es una línea en un JSON.
 
 ---
@@ -88,6 +88,7 @@ ejecución), así que funciona aunque instales uno suelto por fuera.
 |---|---|---|
 | `feature-catalog` | on | Una sola feature en progreso; cerrar exige asserts y revisión. |
 | `sdd-specs` | off | Exige requirements/design/tasks no vacíos antes de implementar. |
+| `brief-approved` | on | Exige una aprobación del usuario registrada (`status: approved` + cita) en el brief de la feature citada antes de implementar. |
 | `implementation-pipeline` | off | Exige declarar definición → escritura → validación → QA → cierre. |
 | `mandatory-flow` | off | Exige una tarea activa con contrato antes de implementar. |
 | `test-matrix` | off | Exige una matriz de tests (los tipos que el requerimiento vuelve obligatorios). |
@@ -105,6 +106,11 @@ ejecución), así que funciona aunque instales uno suelto por fuera.
 | `no-reconfirm` | on | Nunca vuelve a preguntar lo que ya respondiste. |
 | `neutral-spanish` | on | Bloquea voseo o léxico regional en el texto escrito (marcador `neutral-spanish:allow` para una cita/fixture deliberada). |
 | `diagnosis-before-patch` | on | Avisa cuando se cambian timeouts/reintentos sin evidencia. |
+| `lint-commit` | off | Bloquea `git commit` mientras el script de lint del proyecto falla (autodetecta `npm run lint`; silencioso si no hay). |
+| `staged-lint` | off | Bloquea `git commit` cuando los archivos **en el stage** fallan lint — lintea solo lo que agregaste al stage, así tu cambio no puede meter deuda de lint nueva y la deuda preexistente en archivos que no tocaste nunca te bloquea. Marcador `[skip-lint]` para una excepción deliberada. |
+| `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. |
 
 ### 🔎 Tool discovery — no reinventar la rueda
 | Gate | | Qué hace |
@@ -117,9 +123,13 @@ 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. |
 
-### 🩺 Session start — validaciones al arrancar la sesión *(en construcción)*
-`doctor`, `ask-adoption`, `wiring-check` — declarados en el catálogo; sus scripts se migran
-a continuación.
+### 🩺 Sesión y contexto — validaciones al arrancar e inyección de capacidades
+| Gate | | Qué hace |
+|---|---|---|
+| `doctor` | on | Al iniciar la sesión, corre el validador de entorno y solo habla si algo falla. |
+| `ask-adoption` | on | En un proyecto que nunca respondió, hace que el asistente pregunte qué adoptar. |
+| `wiring-check` | on | Avisa cuando un hook registrado falta o un script quedó huérfano. |
+| `capability-map` | on | Cada `injectEveryMessages` mensajes (default 10; siempre en la primera corrida y cuando se agrega/borra una capacidad), inyecta el catálogo de capacidades del proyecto — skills, agents/subagents, comandos — como dato compacto, y lo persiste en `.ai/capability-map.json` (como el mapa de herramientas). Autosincronizado desde el disco. Nunca bloquea. |
 
 ---
 
@@ -153,6 +163,31 @@ ves y editas cada perilla:
   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
   tuvieras en el archivo (por ejemplo `autoCommit`) se conservan intactas.
+- **Válvulas de escape:** algunos gates bloquean (deny) pero aceptan un marcador explícito
+  de exención en el contenido/prompt para un caso legítimo: `neutral-spanish:allow` (una cita
+  regional deliberada), `test-after-impl:allow` (un test de regresión), `memory-not-needed`
+  (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`.
+- **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á
+  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
+  necesidad de configurar nada), sumadas a cualquier `extraSkillsDirs` que el proyecto
+  declare. Una descripción que no entra en `maxClauseChars` cae al truncado mecánico por
+  palabra completa, pero podés escribir a mano un resumen mejor por capacidad en
+  `~/.claude/blurb-overrides.json` (global) o `<proyecto>/<blurbOverridesFile>` (default
+  `.ai/blurb-overrides.json`, el proyecto gana por clave) — un mapa
+  `{ "nombre-skill": "resumen corto" }`, usado tal cual en vez del corte mecánico. El
+  re-escaneo de una capacidad se saltea (se reusa su blurb tal cual) cuando el disco no
+  cambió desde el último escaneo (mismos archivos fuente, mismos mtimes); borrar una
+  skill/agente/comando saca su entrada del mapa en la corrida siguiente.
 
 ---
 

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 30 gates**; the config decides **which
+> **Why two things?** The plugin **always ships all 41 gates**; the config decides **which
 > ones run**. So you can turn one on without reinstalling — it is one line in a JSON file.
 
 ---
@@ -90,6 +90,7 @@ works even if you install one on its own.
 | ------------------------- | --- | -------------------------------------------------------------------- |
 | `feature-catalog`         | on  | A single feature in progress; closing requires asserts and review.   |
 | `sdd-specs`               | off | Requires non-empty requirements/design/tasks before implementing.    |
+| `brief-approved`          | on  | Requires a recorded user approval (`status: approved` + quote) on the cited feature's brief before implementing. |
 | `implementation-pipeline` | off | Requires declaring definition → writing → validation → QA → closure. |
 | `mandatory-flow`          | off | Requires an active task with a contract before implementing.         |
 | `test-matrix`             | off | Requires a test matrix (the types the requirement makes mandatory).  |
@@ -108,6 +109,11 @@ works even if you install one on its own.
 | `no-reconfirm`              | on  | Never re-ask what you already answered.                                                                        |
 | `neutral-spanish`           | on  | Blocks voseo or regional lexicon in written text (add `neutral-spanish:allow` for a deliberate quote/fixture). |
 | `diagnosis-before-patch`    | on  | Warns when timeouts/retries change without evidence.                                                           |
+| `lint-commit`               | off | Blocks `git commit` while the project's lint script fails (autodetects `npm run lint`; silent if none).        |
+| `staged-lint`               | off | Blocks `git commit` when the **staged** files fail lint — lints only what you staged, so your change can't add new lint debt while pre-existing debt in untouched files never blocks you. Add `[skip-lint]` for a deliberate exception. |
+| `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. |
 
 ### 🔎 Tool discovery — don't reinvent the wheel
 
@@ -122,10 +128,14 @@ 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. |
 
-### 🩺 Session start — startup checks _(work in progress)_
+### 🩺 Session & context — startup checks and capability injection
 
-`doctor`, `ask-adoption`, `wiring-check` — declared in the catalog; their scripts are being
-migrated next.
+| Gate             |     | What it does                                                                                                                                                                                          |
+| ---------------- | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `doctor`         | on  | On session start, runs the environment validator and only speaks on failure.                                                                                                                        |
+| `ask-adoption`   | on  | In a project that never answered, makes the assistant ask what to adopt.                                                                                                                            |
+| `wiring-check`   | on  | Warns when a registered hook is missing or a script is orphaned.                                                                                                                                     |
+| `capability-map` | on | Every `injectEveryMessages` messages (default 10; always on the first run and whenever a capability is added/removed), injects the project's capability catalog — skills, agents/subagents, commands — as compact data, and persists it to `.ai/capability-map.json` (like the tool map). Autosynced from disk. Never blocks. |
 
 ---
 
@@ -170,7 +180,26 @@ see and edit every knob:
 - **Escape hatches:** a few gates block (deny) but accept an explicit opt-out marker in the
   content/prompt for a legitimate case: `neutral-spanish:allow` (a deliberate regional
   quote), `test-after-impl:allow` (a regression test), `memory-not-needed` (a
-  non-memory phrase). `dependency-skills` opts out via its `depsWithoutOwnApi` list.
+  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.
+- **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
+  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
+  `extraSkillsDirs` the project declares. A description too long to fit `maxClauseChars`
+  falls back to mechanical word-boundary truncation, but you can hand-write a better one-line
+  summary per capability in `~/.claude/blurb-overrides.json` (global) or
+  `<project>/<blurbOverridesFile>` (default `.ai/blurb-overrides.json`, project wins per
+  key) — a `{ "skill-name": "short summary" }` map, used verbatim instead of the mechanical
+  cut. A capability's re-scan is skipped (its blurb reused verbatim) whenever disk is
+  unchanged since the last scan (same set of source files, same mtimes); removing a
+  skill/agent/command drops its entry from the map on the very next run.
 
 ---
 

package/cli/config.mjs

@@ -1,124 +1,126 @@
-// Where the selection is persisted and how it merges with what is already there.
-//
-// Scope "project": `<project root>/.ai/config.json` — the file the hooks read
-//   per project. Other keys the project already has (autoCommit, etc.) are kept.
-// Scope "global": `~/.claude/claude-gates/config.json` — the fallback the hooks
-//   use when a project has no answer of its own.
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { findUpSync } from 'find-up';
-import {
-  CLAUDE_USER_DIRECTORY,
-  CONFIG_FILE,
-  GLOBAL_STATE_DIRECTORY,
-  HOME_DIRECTORY,
-  JSON_INDENT,
-  PROJECT_ROOT_MARKERS,
-  PROJECT_STATE_DIRECTORY,
-} from './constants.mjs';
-
-export const SCOPES = Object.freeze({ GLOBAL: 'global', PROJECT: 'project' });
-
-/**
- * Climbs from `startDirectory` to the nearest project marker (`.git`/`.ai`).
- * The home directory (and anything above it) is never a project root: a stray
- * `~/.ai` would otherwise turn every folder under home into "the project" and the
- * config would land in the wrong place silently. `.git` may be a file (worktrees),
- * so the matcher checks existence, not type.
- */
-export function findProjectRoot(
-  startDirectory,
-  { home = HOME_DIRECTORY } = {},
-) {
-  if (startDirectory === home) return startDirectory;
-  const markerDirectory = findUpSync(
-    (directory) => {
-      if (directory === home) return findUpSync.stop;
-      const hasMarker = PROJECT_ROOT_MARKERS.some((marker) =>
-        existsSync(join(directory, marker)),
-      );
-      return hasMarker ? directory : undefined;
-    },
-    { cwd: startDirectory, stopAt: home, type: 'directory' },
-  );
-  return markerDirectory ?? startDirectory;
-}
-
-export function configPathFor(
-  scope,
-  { cwd = process.cwd(), home = HOME_DIRECTORY } = {},
-) {
-  if (scope === SCOPES.GLOBAL)
-    return join(
-      home,
-      CLAUDE_USER_DIRECTORY,
-      GLOBAL_STATE_DIRECTORY,
-      CONFIG_FILE,
-    );
-  if (scope === SCOPES.PROJECT)
-    return join(
-      findProjectRoot(cwd, { home }),
-      PROJECT_STATE_DIRECTORY,
-      CONFIG_FILE,
-    );
-  throw new Error(`Unknown scope: ${scope}`);
-}
-
-// A leading UTF-8 BOM (EF BB BF, decoded as U+FEFF) is not stripped by readFileSync('utf8'),
-// and JSON.parse rejects a string that starts with it. Without stripping it, a config saved
-// by a BOM-adding editor or `PowerShell Set-Content -Encoding utf8` would read back as
-// `corrupt: true` — a valid, user-edited config (with its gate overrides) mistaken for
-// unreadable. init.mjs bails loudly on `corrupt`, but a caller relying on `data` alone (as
-// `mergeConfig` does) would otherwise merge onto `{}` and silently drop every existing gate
-// override the user made. This is the same failure mode fixed in the gates' own config.mjs.
-function stripBom(text) {
-  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
-}
-
-export function readConfig(path) {
-  if (!existsSync(path)) return { exists: false, data: {}, corrupt: false };
-  try {
-    return {
-      exists: true,
-      data: JSON.parse(stripBom(readFileSync(path, 'utf8'))),
-      corrupt: false,
-    };
-  } catch {
-    return { exists: true, data: {}, corrupt: true };
-  }
-}
-
-/**
- * Merges one gate's new value onto whatever the project already had, preserving the user's
- * edits. A gate with params arrives as `{ enabled, ...defaults }`; if the user already
- * tuned those params, their values win and only `enabled` follows the new selection. A
- * paramless gate is a plain boolean. This is what keeps a re-run of `init` additive: it
- * never overwrites a whitelist or pattern list the user changed by hand.
- */
-function mergeGate(existingValue, newValue) {
-  if (typeof newValue === 'boolean') return newValue;
-  if (existingValue && typeof existingValue === 'object') {
-    return { ...newValue, ...existingValue, enabled: newValue.enabled };
-  }
-  return newValue;
-}
-
-/**
- * Merges the new selection into an existing config without touching unrelated keys. Gates
- * are merged key by key: a gate absent from the new map keeps its old value (a registry
- * that dropped a gate must not silently flip it), and a gate the user configured keeps its
- * params (see mergeGate).
- */
-export function mergeConfig(existing, { adopted, gates, gateVersion }) {
-  const mergedGates = { ...(existing.gates ?? {}) };
-  for (const [key, value] of Object.entries(gates)) {
-    mergedGates[key] = mergeGate(mergedGates[key], value);
-  }
-  return { ...existing, adopted, gateVersion, gates: mergedGates };
-}
-
-export function writeConfig(path, data) {
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(data, null, JSON_INDENT)}\n`, 'utf8');
-}
+// Where the selection is persisted and how it merges with what is already there.
+//
+// Scope "project": `<project root>/.ai/config.json` — the file the hooks read
+//   per project. Other keys the project already has (autoCommit, etc.) are kept.
+// Scope "global": `~/.claude/claude-gates/config.json` — the fallback the hooks
+//   use when a project has no answer of its own.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { findUpSync } from 'find-up';
+import {
+  CLAUDE_USER_DIRECTORY,
+  CONFIG_FILE,
+  GLOBAL_STATE_DIRECTORY,
+  HOME_DIRECTORY,
+  JSON_INDENT,
+  PROJECT_ROOT_MARKERS,
+  PROJECT_STATE_DIRECTORY,
+} from './constants.mjs';
+
+export const SCOPES = Object.freeze({ GLOBAL: 'global', PROJECT: 'project' });
+
+/**
+ * Climbs from `startDirectory` to the nearest project marker (`.git`/`.ai`).
+ * The home directory (and anything above it) is never a project root: a stray
+ * `~/.ai` would otherwise turn every folder under home into "the project" and the
+ * config would land in the wrong place silently. `.git` may be a file (worktrees),
+ * so the matcher checks existence, not type.
+ */
+export function findProjectRoot(
+  startDirectory,
+  { home = HOME_DIRECTORY } = {},
+) {
+  if (startDirectory === home) return startDirectory;
+  const markerDirectory = findUpSync(
+    (directory) => {
+      if (directory === home) return findUpSync.stop;
+      const hasMarker = PROJECT_ROOT_MARKERS.some((marker) =>
+        existsSync(join(directory, marker)),
+      );
+      return hasMarker ? directory : undefined;
+    },
+    { cwd: startDirectory, stopAt: home, type: 'directory' },
+  );
+  return markerDirectory ?? startDirectory;
+}
+
+export function configPathFor(
+  scope,
+  { cwd = process.cwd(), home = HOME_DIRECTORY } = {},
+) {
+  if (scope === SCOPES.GLOBAL)
+    return join(
+      home,
+      CLAUDE_USER_DIRECTORY,
+      GLOBAL_STATE_DIRECTORY,
+      CONFIG_FILE,
+    );
+  if (scope === SCOPES.PROJECT)
+    return join(
+      findProjectRoot(cwd, { home }),
+      PROJECT_STATE_DIRECTORY,
+      CONFIG_FILE,
+    );
+  throw new Error(`Unknown scope: ${scope}`);
+}
+
+// A leading UTF-8 BOM (EF BB BF, decoded as U+FEFF) is not stripped by readFileSync('utf8'),
+// and JSON.parse rejects a string that starts with it. Without stripping it, a config saved
+// by a BOM-adding editor or `PowerShell Set-Content -Encoding utf8` would read back as
+// `corrupt: true` — a valid, user-edited config (with its gate overrides) mistaken for
+// unreadable. init.mjs bails loudly on `corrupt`, but a caller relying on `data` alone (as
+// `mergeConfig` does) would otherwise merge onto `{}` and silently drop every existing gate
+// override the user made. This is the same failure mode fixed in the gates' own config.mjs.
+const BOM_CODE_POINT = 0xfeff;
+
+function stripBom(text) {
+  return text.charCodeAt(0) === BOM_CODE_POINT ? text.slice(1) : text;
+}
+
+export function readConfig(path) {
+  if (!existsSync(path)) return { exists: false, data: {}, corrupt: false };
+  try {
+    return {
+      exists: true,
+      data: JSON.parse(stripBom(readFileSync(path, 'utf8'))),
+      corrupt: false,
+    };
+  } catch {
+    return { exists: true, data: {}, corrupt: true };
+  }
+}
+
+/**
+ * Merges one gate's new value onto whatever the project already had, preserving the user's
+ * edits. A gate with params arrives as `{ enabled, ...defaults }`; if the user already
+ * tuned those params, their values win and only `enabled` follows the new selection. A
+ * paramless gate is a plain boolean. This is what keeps a re-run of `init` additive: it
+ * never overwrites a whitelist or pattern list the user changed by hand.
+ */
+function mergeGate(existingValue, newValue) {
+  if (typeof newValue === 'boolean') return newValue;
+  if (existingValue && typeof existingValue === 'object') {
+    return { ...newValue, ...existingValue, enabled: newValue.enabled };
+  }
+  return newValue;
+}
+
+/**
+ * Merges the new selection into an existing config without touching unrelated keys. Gates
+ * are merged key by key: a gate absent from the new map keeps its old value (a registry
+ * that dropped a gate must not silently flip it), and a gate the user configured keeps its
+ * params (see mergeGate).
+ */
+export function mergeConfig(existing, { adopted, gates, gateVersion }) {
+  const mergedGates = { ...(existing.gates ?? {}) };
+  for (const [key, value] of Object.entries(gates)) {
+    mergedGates[key] = mergeGate(mergedGates[key], value);
+  }
+  return { ...existing, adopted, gateVersion, gates: mergedGates };
+}
+
+export function writeConfig(path, data) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(data, null, JSON_INDENT)}\n`, 'utf8');
+}