@devrik-tools/claude-gates 0.6.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.6.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.6.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 40 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). |
@@ -128,7 +129,7 @@ ejecución), así que funciona aunque instales uno suelto por fuera.
 | `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` | off | En cada mensaje, 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. |
+| `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. |
 
 ---
 
@@ -170,10 +171,23 @@ ves y editas cada perilla:
   (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` (off por defecto) es totalmente ajustable —
+- **Inyección de capacidades:** `capability-map` (on por defecto) es totalmente ajustable —
   elegí qué tipos exponer (`"kinds": ["skills", "agents", "commands"]`), limitá cada blurb
-  (`maxClauseChars`), agregá raíces extra por tipo, o apagá la persistencia
-  (`"persist": false`) y apuntá el mapa a otro archivo (`mapFile`).
+  (`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 40 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).  |
@@ -134,7 +135,7 @@ works even if you install one on its own.
 | `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` | off | On every message, 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. |
+| `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. |
 
 ---
 
@@ -183,10 +184,22 @@ see and edit every knob:
   `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` (off by default) is fully tunable — pick which
+- **Capability injection:** `capability-map` (on by default) is fully tunable — pick which
   kinds to surface (`"kinds": ["skills", "agents", "commands"]`), cap each blurb
-  (`maxClauseChars`), add extra roots per kind, or turn off persistence (`"persist": false`)
-  and point the map file elsewhere (`mapFile`).
+  (`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/smoke-fixtures.json

@@ -157,6 +157,20 @@
       "needsState": true,
       "note": "auto-off unless a features tree exists; needs seeded .ai/feature_list.json + features dir."
     },
+    {
+      "id": "brief-approved",
+      "configKey": "requireApprovedBriefBeforeImplementing",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Agent",
+        "tool_input": {
+          "prompt": "Nivel: STANDARD\nImplementa .ai/features/checkout/brief.md."
+        }
+      },
+      "needsState": true,
+      "note": "auto-off unless a features tree exists; needs a seeded .ai/features/<name>/brief.md with no approved frontmatter."
+    },
     {
       "id": "implementation-pipeline",
       "configKey": "requireImplementationPipeline",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devrik-tools/claude-gates",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Installable, deterministic gates (hooks) for Claude Code: block destructive commands, protected paths, and enforce delegation/spec/quality rules. Configurable per project.",
   "keywords": [
     "claude-code",

package/plugins/gates/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gates",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Deterministic gates for Claude Code: destructive-command blocks, protected paths, delegation briefs, spec-driven flow and session-start validation. Selection lives in config, not in code.",
   "author": {
     "name": "Devrik"

package/plugins/gates/hooks/gates/brief-approved/index.mjs

@@ -0,0 +1,216 @@
+// brief-approved — denies an implementation delegation (STANDARD/HIGH-RISK, an
+// implementation verb) that targets a feature whose brief/spec has no recorded human
+// approval. Migrated from a real incident: the assistant took an ambiguous user reply
+// ("hagamos el brief") as approval of a spec it had already written, delegated
+// implementation straight away, and never pasted the full brief into the chat for the
+// user to confirm line by line. `sdd-specs` already blocks implementing a feature with
+// NO contract at all; this gate blocks implementing a feature whose contract exists but
+// was never actually approved by the user — a distinct failure this incident exposed.
+//
+// ── What "approved" means here (deliberately narrow) ────────────────────────────────
+// A hook cannot read the chat, so it cannot verify the assistant actually pasted the
+// full brief and that the user actually read it. What IS checkable: the brief file
+// itself carries a frontmatter block written ONLY once that confirmation happened —
+//   ---
+//   status: approved
+//   approved_at: <ISO timestamp>
+//   approval_quote: "<user's own words>"
+//   ---
+// The gate does not (cannot) verify the quote is genuine; it verifies the field exists
+// and is non-empty, which at minimum forces the assistant to stop and produce a
+// specific artifact instead of silently inferring consent from a vague reply.
+//
+// ── Auto-off when there is no brief to approve ──────────────────────────────────────
+// Same discovery as sdd-specs: only fires once a feature contract tree exists under
+// .ai/features/<name>/ (or the configured catalog's sibling `features` dir) AND that
+// feature has a brief.md/asserts.md file. A project with no such file for the cited
+// feature is out of this gate's scope (sdd-specs already denies that case).
+//
+// ── What is NOT configurable (base, non-negotiable) ─────────────────────────────────
+// The frontmatter field names (status/approved_at/approval_quote) are fixed, not a
+// project param — a configurable field name would let a delegation "approve" itself by
+// pointing the gate at whatever key it just wrote.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import {
+  runGate,
+  deny,
+  toolInGroups,
+  delegationPromptOf,
+} from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'brief-approved';
+const CONFIG_KEY = 'requireApprovedBriefBeforeImplementing';
+
+const CATALOG_FILE_NAME = 'feature_list.json';
+const DEFAULT_CATALOG_LOCATIONS = [
+  join('.ai', CATALOG_FILE_NAME),
+  CATALOG_FILE_NAME,
+];
+
+const DEFAULT_EXEMPT_SUBAGENTS = [
+  'explore',
+  'plan',
+  'scout',
+  'revision',
+  'contraste',
+  'test-planner',
+  'qa',
+  'ui',
+  'ux',
+];
+
+/** Files that count as a feature's contract; the first one found on disk is the one
+ * checked for approval (mirrors sdd-specs' CONTRACT_FILES precedence). */
+const CONTRACT_FILES = [
+  'brief.md',
+  'requirements.md',
+  'design.md',
+  'tasks.md',
+  'asserts.md',
+];
+
+const APPROVED_FRONTMATTER_PATTERN = /^---\r?\n(?<body>[\s\S]*?)\r?\n---/;
+const APPROVED_STATUS_PATTERN = /^status:[ \t]*approved[ \t]*$/im;
+const APPROVAL_QUOTE_PATTERN = /^approval_quote:[ \t]*(\S.*)$/im;
+
+function withWordBoundary(alternation) {
+  return new RegExp(
+    `(?<![\\p{L}\\p{N}_])(${alternation})(?![\\p{L}\\p{N}_])`,
+    'iu',
+  );
+}
+
+const IMPLEMENTATION_VERBS = withWordBoundary(
+  'implementa|implementar|implement(á|é)|agreg(a|á)|agregar|añad(e|í)|añadir|cre(a|á)|crear|' +
+    'arregl(a|á)|arreglar|cambi(a|á)|cambiar|migr(a|á)|migrar|' +
+    'corrige|corregir|correg(í|ir)|constru(ye|í)|construir|modific(a|á)|modificar|' +
+    'refactoriz(a|á)|refactorizar|elimin(a|á)|eliminar|reescrib(e|í)|reescribir|desplieg(a|á)|desplegar|' +
+    'escrib(í|e)|escribir|implement\\w*|writ(e|ing)|creat\\w*|fix\\w*|build\\w*|refactor\\w*|migrat\\w*|' +
+    'add\\w*|remov\\w*|delet\\w*|modify|modifies|modifying|rewrit\\w*',
+);
+
+const DEMANDING_LEVEL_PATTERN =
+  /(nivel|level|clasificaci[oó]n|classification)[^\n]{0,25}?\b(STANDARD|HIGH-RISK)\b/iu;
+const EXEMPT_LEVEL_PATTERN =
+  /(nivel|level|clasificaci[oó]n|classification)[^\n]{0,25}?\b(QUESTION|MICRO)\b/iu;
+
+function findCatalog(catalogLocations) {
+  for (const relative of catalogLocations) {
+    const path = join(process.cwd(), relative);
+    if (existsSync(path)) return path;
+  }
+  return null;
+}
+
+function contractTreeRootFor(catalogPath) {
+  const candidates = catalogPath
+    ? [join(dirname(catalogPath), 'features')]
+    : [];
+  candidates.push(join(process.cwd(), '.ai', 'features'));
+  candidates.push(join(process.cwd(), 'features'));
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** The first existing contract file's path for a feature, or null if none exists. */
+function contractFileFor(treeRoot, featureName) {
+  if (!treeRoot) return null;
+  const featureDirectory = join(treeRoot, featureName);
+  if (!existsSync(featureDirectory)) return null;
+  for (const file of CONTRACT_FILES) {
+    const path = join(featureDirectory, file);
+    if (existsSync(path)) return path;
+  }
+  return null;
+}
+
+/** Whether a contract file's frontmatter records a real approval: `status: approved`
+ * plus a non-empty `approval_quote`. Both must be present — status alone is a label
+ * the assistant could set on itself with no evidence a quote was ever collected. */
+function isApproved(contractPath) {
+  let content;
+  try {
+    content = readFileSync(contractPath, 'utf8');
+  } catch {
+    return false;
+  }
+  const frontmatter = APPROVED_FRONTMATTER_PATTERN.exec(content)?.groups?.body;
+  if (!frontmatter) return false;
+  if (!APPROVED_STATUS_PATTERN.test(frontmatter)) return false;
+  const quoteMatch = APPROVAL_QUOTE_PATTERN.exec(frontmatter);
+  const quote = quoteMatch?.[1]?.replace(/^["']|["']$/g, '').trim();
+  return Boolean(quote);
+}
+
+function isExemptDelegation(toolInput, prompt, exemptSubagents) {
+  const subagentType = String(
+    toolInput.subagent_type ?? toolInput.subagentType ?? '',
+  ).toLowerCase();
+  if (exemptSubagents.includes(subagentType)) return true;
+  if (EXEMPT_LEVEL_PATTERN.test(prompt)) return true;
+  if (!DEMANDING_LEVEL_PATTERN.test(prompt)) return true;
+  if (!IMPLEMENTATION_VERBS.test(prompt)) return true;
+  return false;
+}
+
+function featureNamesCitedIn(prompt) {
+  const pattern = /\.(?:ai)[\\/]features[\\/]([\w.@-]+)/gi;
+  const names = [];
+  let match;
+  while ((match = pattern.exec(prompt)) !== null) names.push(match[1]);
+  return names;
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      catalogLocations: DEFAULT_CATALOG_LOCATIONS,
+      exemptSubagents: DEFAULT_EXEMPT_SUBAGENTS,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    if (!toolInGroups(toolName, ['delegation'])) return;
+
+    const prompt = delegationPromptOf(toolInput);
+    if (!prompt.trim()) return;
+
+    const exemptSubagents =
+      parameters.exemptSubagents ?? DEFAULT_EXEMPT_SUBAGENTS;
+    if (isExemptDelegation(toolInput, prompt, exemptSubagents)) return;
+
+    const citedFeatures = featureNamesCitedIn(prompt);
+    if (citedFeatures.length === 0) return; // no citation: nothing this gate can check
+
+    const catalogLocations =
+      parameters.catalogLocations ?? DEFAULT_CATALOG_LOCATIONS;
+    const catalogPath = findCatalog(catalogLocations);
+    const treeRoot = contractTreeRootFor(catalogPath);
+    if (!treeRoot) return; // no SDD harness adopted: stay silent
+
+    const unapproved = citedFeatures.filter((feature) => {
+      const contractPath = contractFileFor(treeRoot, feature);
+      if (!contractPath) return false; // sdd-specs already denies this case
+      return !isApproved(contractPath);
+    });
+
+    if (unapproved.length === 0) return;
+
+    deny(
+      GATE_ID,
+      `This implementation delegation cites feature(s) [${unapproved.join(', ')}] ` +
+        'whose brief/contract has no recorded approval. Paste the FULL brief into the ' +
+        'chat, get an explicit confirmation from the user (not a vague "dale"/"sigamos" ' +
+        '— an actual sentence confirming they read it), then add this frontmatter to ' +
+        'the top of the contract file before relaunching:\n' +
+        '---\nstatus: approved\napproved_at: <ISO timestamp>\n' +
+        'approval_quote: "<the user\'s own confirming words>"\n---',
+    );
+  },
+);

package/plugins/gates/hooks/gates/capability-map/index.mjs

@@ -1,11 +1,13 @@
 // capability-map — UserPromptSubmit hook. Surfaces the REAL, current catalog of the project's
 // AI capabilities — skills, agents/subagents, and commands — as compact data ("caveman"
-// format: `name — first clause`, one line each, grouped by kind), read fresh from disk on
-// every message. It also PERSISTS that catalog to .ai/capability-map.json so the map is easy
-// to follow and read the same way the tool map (.ai/tool-map.json) is, and so another tool or
-// a human can consult it without re-scanning. Autosynced by construction: add or remove a
-// skill/agent/command file and the next message reflects it, because the map IS the directory
-// listing, never a hardcoded copy.
+// format: `name — first clause`, one line each, grouped by kind). It also PERSISTS that
+// catalog to .ai/capability-map.json so the map is easy to follow and read the same way the
+// tool map (.ai/tool-map.json) is, and so another tool or a human can consult it without
+// re-scanning. Autosynced by construction: add or remove a skill/agent/command file and the
+// next message reflects it (a removed capability's entry disappears with it — the catalog is
+// derived from what is on disk NOW, never a stale copy of what used to be there), because the
+// catalog IS the directory listing. Re-deriving blurbs (the only non-trivial per-entry work)
+// is skipped when disk is provably unchanged since the last scan — see fingerprintOf below.
 //
 // It does NOT tell the model to obey a reminder — that would be prose the model may ignore,
 // the exact antipattern guard-no-model-reliance forbids. It injects a fact (which capabilities
@@ -29,15 +31,46 @@
 // Each injected line is `name — first clause` (up to the first '. ' or a hard char cap), so
 // the whole catalog stays cheap even at dozens of entries.
 //
+// ── Blurb overrides for descriptions that don't fit ─────────────────────────────────────
+// When a description's first clause is longer than `maxClauseChars`, mechanical truncation
+// (even at a word boundary) loses the point of a dense one-liner (e.g. "Referencia normativa
+// completa de accesibilidad web (WCAG 2.2, ARIA, teclado, lectores de…" tells you nothing).
+// Writing an actual summary needs judgment a Node hook does not have — so instead this gate
+// reads a human/assistant-authored override by capability name from `~/.claude/blurb-
+// overrides.json` and `<project>/<blurbOverridesFile>` (project wins per-key) and uses it
+// verbatim (still capped at maxClauseChars, in case an override itself runs long). A
+// capability with no override falls back to the mechanical truncation — never blocked on
+// someone writing every override up front.
+//
+// ── Throttled injection, not every message ──────────────────────────────────────────────
+// Injecting the full catalog on every UserPromptSubmit burns context on every turn for a
+// catalog that rarely changes turn-to-turn. `injectEveryMessages` (default 10, same shape as
+// tasks' remindEveryMessages) counts messages via a small persisted counter next to the map
+// file and only injects on the Nth. The persisted .ai/capability-map.json is still refreshed
+// from disk on EVERY message regardless of the counter — persistence is cheap (a file write,
+// not context) and staying accurate matters even between injections.
+//
+// ── Skills also scanned outside the .claude layout, unconditionally ────────────────────
+// `~/.agents/skills`, `<project>/.agents/skills`, `~/.ai/skills`, `<project>/.ai/skills` are
+// scanned as skill roots by default (no config needed) alongside `.claude/skills` — these
+// are skill directories other installers are known to use (`.agents/skills` is what the
+// `skills` CLI several installers shell out to writes when run without its `-g` flag: a
+// project-local skill tree, not `~/.claude`). Agents/commands are NOT looked for under these
+// roots — only `.claude` is known to lay those out as siblings of `skills`.
+//
 // ── What a project can configure (params) — everything is customizable ───────────────
-//   kinds            which capability kinds to include, e.g. ["skills","agents","commands"].
-//                    Drop one to stop scanning it entirely.
-//   maxClauseChars   hard cap on each entry's one-line blurb (default 90).
+//   kinds              which capability kinds to include, e.g. ["skills","agents","commands"].
+//                      Drop one to stop scanning it entirely.
+//   maxClauseChars     hard cap on each entry's one-line blurb (default 120).
 //   extraSkillsDirs / extraAgentsDirs / extraCommandsDirs   additional roots per kind
-//                    (relative to project or absolute), added on top of the built-in ones.
-//   persist          whether to write .ai/capability-map.json (default true).
-//   mapFile          path to the persisted map, relative to project root. Default
-//                    .ai/capability-map.json.
+//                      (relative to project or absolute), added on top of the built-in ones.
+//   persist            whether to write .ai/capability-map.json (default true).
+//   mapFile            path to the persisted map, relative to project root. Default
+//                      .ai/capability-map.json.
+//   injectEveryMessages   inject the rendered catalog only every Nth message (default 10);
+//                      the persisted map file still refreshes every message regardless.
+//   blurbOverridesFile   path to the overrides JSON, relative to project root. Default
+//                      .ai/blurb-overrides.json.
 //
 // ── Fail-safe shape ──────────────────────────────────────────────────────────────────
 // Nothing found anywhere, gate disabled, or unreadable input: inject nothing (silent, no
@@ -45,11 +78,13 @@
 // swallowed: the injection is the job, the file is a convenience. Never blocks —
 // UserPromptSubmit cannot deny; it only adds context.
 
+import { createHash } from 'node:crypto';
 import {
   existsSync,
   mkdirSync,
   readFileSync,
   readdirSync,
+  statSync,
   writeFileSync,
 } from 'node:fs';
 import { homedir } from 'node:os';
@@ -58,9 +93,17 @@ import { basename, dirname, extname, isAbsolute, join } from 'node:path';
 const STDIN_FILE_DESCRIPTOR = 0;
 const CONFIG_KEY = 'injectCapabilityMap';
 const DUMP_ENV = 'CLAUDE_GATES_DUMP_DEFAULTS';
-const DEFAULT_MAX_CLAUSE_CHARS = 90;
+// The registry default this gate is shipped with. Kept here (not only in dumpDefaults) so
+// main() and dumpDefaults agree by construction — a value duplicated in two places is
+// exactly the desync that let a gate silently miss its own registry default before (see
+// the project's default-desync incident: registry.json and the gate's own hardcoded
+// enabledByDefault drifting apart across a version bump).
+const ENABLED_BY_DEFAULT = true;
+const DEFAULT_MAX_CLAUSE_CHARS = 120;
 const DEFAULT_KINDS = ['skills', 'agents', 'commands'];
 const DEFAULT_MAP_FILE = join('.ai', 'capability-map.json');
+const DEFAULT_BLURB_OVERRIDES_FILE = join('.ai', 'blurb-overrides.json');
+const DEFAULT_INJECT_EVERY_MESSAGES = 10;
 const JSON_INDENT = 2;
 
 // Config lookup mirrors config.mjs (project → global), kept local so a gate stays runnable on
@@ -91,7 +134,13 @@ function projectRootOf(startDirectory) {
   }
 }
 
-/** The capability-map gate config entry (project overrides global), or null. */
+/** The capability-map gate config entry (project overrides global). `enabled` is `true`/
+ * `false` only when a project or global config explicitly declared it — absent (undefined)
+ * means "nothing was declared, fall back to the registry default", the same three-state
+ * shape config.mjs's isGateEnabled uses for every other gate. Distinguishing "never
+ * declared" from "explicitly false" matters once ENABLED_BY_DEFAULT is true: without it, a
+ * project that never touched this gate's config would look identical to one that turned it
+ * off, and the registry default could never take effect. */
 function gateConfig(startDirectory) {
   const root = projectRootOf(startDirectory);
   const projectData = root ? readJson(join(root, PROJECT_CONFIG)) : null;
@@ -100,7 +149,7 @@ function gateConfig(startDirectory) {
   const entry = layer[CONFIG_KEY];
   if (typeof entry === 'boolean') return { enabled: entry };
   if (entry && typeof entry === 'object') return entry;
-  return null;
+  return {};
 }
 
 function readPayload() {
@@ -111,11 +160,36 @@ function readPayload() {
   }
 }
 
+// A YAML folded/literal block scalar indicator with nothing else on the line
+// (`description: >`, `description: >-`, `description: |`, `description: |-`): the real
+// value is every following indented line, not this one. Seen across `.agents/skills`
+// SKILL.md files (e.g. api-architect, babysit, branch-pr) — without this, the parser took
+// the bare indicator itself as the description, rendering blurbs like `">"` or `">-"`.
+const BLOCK_SCALAR_INDICATOR_PATTERN = /^[|>][+-]?\d*$/;
+
+/** Every following line indented relative to the block's own indentation, joined with a
+ * single space (folded-scalar semantics — good enough for a one-line blurb; literal `|`
+ * blocks are folded too, which only affects a display detail this gate strips anyway via
+ * firstClause). Stops at the first line that is blank or not indented (front matter end,
+ * or a sibling key). */
+function readBlockScalarValue(lines, startIndex) {
+  const parts = [];
+  for (let index = startIndex; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (line.trim() === '---') break;
+    if (!/^[ \t]+\S/.test(line)) break; // not indented: block scalar ended
+    parts.push(line.trim());
+  }
+  return parts.join(' ');
+}
+
 /**
  * The `name` and `description` from a markdown-style front matter block (skills, agents,
  * commands all use `---`-fenced YAML-ish front matter). Parsed line-by-line (no multi-line
- * regex) so a large file body can never trigger catastrophic backtracking. Returns
- * { name, description } with either possibly ''.
+ * regex) so a large file body can never trigger catastrophic backtracking. Handles a plain
+ * scalar value on the `key:` line itself, and a YAML folded/literal block scalar (`>`, `>-`,
+ * `|`, `|-`) whose value lives on the following indented lines. Returns { name, description }
+ * with either possibly ''.
  */
 function parseFrontMatter(fileText) {
   const lines = fileText.split(/\r?\n/);
@@ -129,25 +203,38 @@ function parseFrontMatter(fileText) {
     const separator = line.indexOf(':');
     if (separator < 0) continue;
     const key = line.slice(0, separator).trim();
-    const value = line
+    let value = line
       .slice(separator + 1)
       .trim()
       .replace(/^["']|["']$/g, ''); // toml/yaml quoting around the value
+    if (BLOCK_SCALAR_INDICATOR_PATTERN.test(value)) {
+      value = readBlockScalarValue(lines, index + 1);
+    }
     if (key === 'name') name = value;
     else if (key === 'description') description = value;
   }
   return { name, description };
 }
 
+/** Truncates text to at most maxChars, breaking at the last whitespace boundary before
+ * the limit rather than mid-word — a hard char-index cut turns "lectores de pantalla"
+ * into "lectores de…", losing the word instead of just the tail of the sentence. Falls
+ * back to a hard cut only when there is no whitespace to break on (one very long word). */
+function truncateAtWordBoundary(text, maxChars) {
+  if (text.length <= maxChars) return text;
+  const budget = text.slice(0, maxChars - 1);
+  const lastSpace = budget.lastIndexOf(' ');
+  const cut = lastSpace > 0 ? budget.slice(0, lastSpace) : budget;
+  return `${cut.trimEnd()}…`;
+}
+
 /** The description's first clause, capped — the caveman blurb. */
 function firstClause(description, maxClauseChars) {
   if (!description) return '';
   const sentenceEnd = description.indexOf('. ');
   const clause =
     sentenceEnd > 0 ? description.slice(0, sentenceEnd) : description;
-  return clause.length > maxClauseChars
-    ? `${clause.slice(0, maxClauseChars - 1).trimEnd()}…`
-    : clause;
+  return truncateAtWordBoundary(clause, maxClauseChars);
 }
 
 /** Recursively lists files under a directory whose extension is in `extensions`. */
@@ -171,7 +258,21 @@ function filesUnder(directory, extensions) {
   return files;
 }
 
-/** Skill capabilities under one root: <root>/skills/<name>/SKILL.md. */
+/** The file's mtime in ms, or null when it cannot be stat'd (broken junction, race). A
+ * source this gate cannot stat contributes nothing stable to the fingerprint — treated as
+ * absent so a dangling link does not poison every future comparison with a NaN/undefined. */
+function mtimeMsOf(path) {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+/** Skill capabilities under one root: <root>/skills/<name>/SKILL.md. Each entry carries
+ * `stamp: "<path>:<mtimeMs>"`, the unit the disk fingerprint is built from (see
+ * fingerprintOf) — cheap because it reuses the stat already needed to read the file, no
+ * second filesystem pass. */
 function skillEntriesUnder(skillsRoot, maxClauseChars) {
   if (!existsSync(skillsRoot)) return [];
   let skillDirectories;
@@ -184,7 +285,8 @@ function skillEntriesUnder(skillsRoot, maxClauseChars) {
   for (const skillDirectory of skillDirectories) {
     if (!skillDirectory.isDirectory()) continue;
     const skillFile = join(skillsRoot, skillDirectory.name, 'SKILL.md');
-    if (!existsSync(skillFile)) continue;
+    const mtimeMs = mtimeMsOf(skillFile);
+    if (mtimeMs === null) continue; // missing or a dangling link: not a real source
     let content;
     try {
       content = readFileSync(skillFile, 'utf8');
@@ -194,16 +296,21 @@ function skillEntriesUnder(skillsRoot, maxClauseChars) {
     const { name, description } = parseFrontMatter(content);
     entries.push({
       name: name || skillDirectory.name,
-      blurb: firstClause(description, maxClauseChars),
+      description,
+      maxClauseChars,
+      stamp: `${skillFile}:${mtimeMs}`,
     });
   }
   return entries;
 }
 
-/** Agent/command capabilities: flat or nested files whose front matter carries a description. */
+/** Agent/command capabilities: flat or nested files whose front matter carries a description.
+ * Same stamp shape as skillEntriesUnder, for the same reason. */
 function fileEntriesUnder(directory, extensions, maxClauseChars) {
   const entries = [];
   for (const file of filesUnder(directory, extensions)) {
+    const mtimeMs = mtimeMsOf(file);
+    if (mtimeMs === null) continue;
     let content;
     try {
       content = readFileSync(file, 'utf8');
@@ -213,7 +320,9 @@ function fileEntriesUnder(directory, extensions, maxClauseChars) {
     const { name, description } = parseFrontMatter(content);
     entries.push({
       name: name || basename(file, extname(file)),
-      blurb: firstClause(description, maxClauseChars),
+      description,
+      maxClauseChars,
+      stamp: `${file}:${mtimeMs}`,
     });
   }
   return entries;
@@ -223,11 +332,34 @@ function baseRoots(cwd) {
   return [join(homedir(), '.claude'), join(cwd, '.claude')];
 }
 
+// Skill directories seen in the wild outside the `.claude/skills` layout: the `skills`
+// upstream CLI (invoked by installers like caveman) writes to a project-local
+// `./.agents/skills` when run without its `-g` flag (see caveman/bin/install.js's own
+// comment on issue #836 — the exact bug that produced 65 dangling junctions under
+// `~/.claude/skills` in one real incident: they pointed at a `.agents/skills` that only
+// ever existed relative to the project the installer ran from). `.ai/skills` is included
+// per explicit user instruction, without independent verification of a specific installer
+// using it — kept here rather than as a project-declared default so every project gets it
+// without having to know the installer's quirk. These are SKILL roots only (the directory
+// IS the skills folder, unlike `.claude` where `skills/agents/commands` are siblings under
+// one root) — they never gain agents/commands lookup, which would be inventing a layout
+// this repo has no evidence for.
+function defaultSkillOnlyRoots(cwd) {
+  return [
+    join(homedir(), '.agents', 'skills'),
+    join(cwd, '.agents', 'skills'),
+    join(homedir(), '.ai', 'skills'),
+    join(cwd, '.ai', 'skills'),
+  ];
+}
+
 function resolveExtra(cwd, directory) {
   return isAbsolute(directory) ? directory : join(cwd, directory);
 }
 
-/** Every entry for one kind across all roots, de-duplicated by name. */
+/** Every entry for one kind across all roots, de-duplicated by name (each entry still
+ * carries description/maxClauseChars/stamp — blurb overrides and truncation are applied
+ * later, once, in applyBlurbs, not per-root). */
 function entriesForKind(kind, cwd, config, maxClauseChars) {
   const perKind = {
     skills: {
@@ -260,6 +392,11 @@ function entriesForKind(kind, cwd, config, maxClauseChars) {
 
   const collected = [];
   for (const root of baseRoots(cwd)) collected.push(...perKind.collect(root));
+  if (kind === 'skills') {
+    for (const root of defaultSkillOnlyRoots(cwd)) {
+      collected.push(...skillEntriesUnder(root, maxClauseChars));
+    }
+  }
   const extra = Array.isArray(perKind.extra) ? perKind.extra : [];
   for (const directory of extra) {
     collected.push(...perKind.collectExtra(resolveExtra(cwd, directory)));
@@ -276,14 +413,118 @@ function entriesForKind(kind, cwd, config, maxClauseChars) {
   return unique;
 }
 
+/** The two override file paths in effect for this cwd (global always; project only when a
+ * project root is found), regardless of whether either currently exists. Shared by
+ * blurbOverridesFor (reads them) and blurbOverrideStampsFor (fingerprints them) so the two
+ * can never drift to different paths. */
+function blurbOverridePathsFor(cwd, blurbOverridesFile) {
+  const globalPath = join(homedir(), '.claude', 'blurb-overrides.json');
+  const root = projectRootOf(cwd);
+  const projectPath = root ? join(root, blurbOverridesFile) : null;
+  return projectPath ? [globalPath, projectPath] : [globalPath];
+}
+
+/** The overrides map (capability name -> hand-written blurb). Project file wins over the
+ * global one entry-by-entry (spread, global first) so a project can override a single
+ * global entry without having to repeat the rest. */
+function blurbOverridesFor(cwd, blurbOverridesFile) {
+  const [globalPath, projectPath] = blurbOverridePathsFor(
+    cwd,
+    blurbOverridesFile,
+  );
+  return {
+    ...(readJson(globalPath) ?? {}),
+    ...(projectPath ? (readJson(projectPath) ?? {}) : {}),
+  };
+}
+
+/** Stamps for the override file(s) themselves, in the same "<path>:<mtimeMs>" shape as a
+ * capability's stamp — folded into the fingerprint so EDITING AN OVERRIDE (with no skill
+ * file touched at all) still invalidates the cached catalog. Without this, a fresh or
+ * changed blurb-overrides.json would sit unused: the persisted catalog's fingerprint would
+ * still match (no skill/agent/command changed) and resolveCatalog would keep serving the
+ * stale, un-overridden blurb forever — the exact bug a real run surfaced (clean-architecture
+ * got an override added to blurb-overrides.json after the map had already been generated
+ * once, and kept showing the mechanically-truncated text on every later run because nothing
+ * ever invalidated the cache). A missing override file contributes a stable "absent" stamp
+ * (not skipped) so going from absent -> present is itself a fingerprint change. */
+function blurbOverrideStampsFor(cwd, blurbOverridesFile) {
+  return blurbOverridePathsFor(cwd, blurbOverridesFile).map((path) => {
+    const mtimeMs = mtimeMsOf(path);
+    return `${path}:${mtimeMs === null ? 'absent' : mtimeMs}`;
+  });
+}
+
+/** Turns a raw entry (description/maxClauseChars/stamp) into the rendered shape
+ * (name/blurb/stamp) — an override is used verbatim (still capped, in case it runs long
+ * itself); with no override, falls back to the mechanical first-clause truncation. */
+function applyBlurbs(entries, overrides) {
+  return entries.map((entry) => {
+    const override = overrides[entry.name];
+    const blurb = override
+      ? truncateAtWordBoundary(override, entry.maxClauseChars)
+      : firstClause(entry.description, entry.maxClauseChars);
+    return { name: entry.name, blurb, stamp: entry.stamp };
+  });
+}
+
+/** A stable, order-independent fingerprint of every source file's path+mtime across the
+ * whole catalog, plus any `extraStamps` the caller folds in (the override file(s) — see
+ * blurbOverrideStampsFor; a capability's rendered blurb depends on both its own source file
+ * AND the overrides file, so both must be able to invalidate the cache). Two scans of an
+ * otherwise-unchanged disk produce the same fingerprint; adding, removing, or touching any
+ * skill/agent/command file, or the overrides file, changes it. Sorted before hashing so
+ * filesystem enumeration order (which readdirSync does not guarantee) never causes a false
+ * "changed" reading. sha256 not for any security property (this is a change-detection
+ * checksum, nothing here is adversarial) — plain sha1 just trips the linter's blanket
+ * weak-hash rule, and sha256 is just as cheap at this size. */
+function fingerprintOf(catalog, extraStamps = []) {
+  const stamps = Object.values(catalog)
+    .flat()
+    .map((entry) => entry.stamp)
+    .concat(extraStamps)
+    .sort();
+  return createHash('sha256').update(stamps.join('\n')).digest('hex');
+}
+
+/** Strips `stamp` before persisting/rendering — it is scan-time-only plumbing for the
+ * fingerprint, not part of the public map shape. */
+function withoutStamps(catalog) {
+  const stripped = {};
+  for (const [kind, entries] of Object.entries(catalog)) {
+    stripped[kind] = entries.map(({ name, blurb }) => ({ name, blurb }));
+  }
+  return stripped;
+}
+
+/** Reads the persisted map's catalog + fingerprint + injection counter, or nulls when
+ * absent/corrupt. Used to decide whether a rescan is needed and to track injectEveryMessages
+ * without a second store file. */
+function readPersistedState(mapPath) {
+  const data = readJson(mapPath);
+  if (!data || typeof data !== 'object') {
+    return { catalog: null, fingerprint: null, messageCount: 0 };
+  }
+  return {
+    catalog:
+      data.capabilities && typeof data.capabilities === 'object'
+        ? data.capabilities
+        : null,
+    fingerprint: typeof data.fingerprint === 'string' ? data.fingerprint : null,
+    messageCount: Number.isInteger(data.messageCount) ? data.messageCount : 0,
+  };
+}
+
 /** Persists the map to .ai/capability-map.json, best-effort — never throws, never blocks. */
-function persistMap(cwd, mapFile, catalog) {
+function persistMap(cwd, mapFile, catalog, fingerprint, messageCount) {
   const root = projectRootOf(cwd);
   if (!root) return;
   const mapPath = join(root, mapFile);
   const payload = {
     generatedAt: new Date().toISOString(),
-    capabilities: catalog,
+    fingerprint,
+    messageCount,
+    capabilities: withoutStamps(catalog),
   };
   try {
     mkdirSync(dirname(mapPath), { recursive: true });
@@ -309,7 +550,7 @@ function dumpDefaults() {
     JSON.stringify({
       id: 'capability-map',
       configKey: CONFIG_KEY,
-      enabledByDefault: false,
+      enabledByDefault: ENABLED_BY_DEFAULT,
       defaultParams: {
         kinds: DEFAULT_KINDS,
         maxClauseChars: DEFAULT_MAX_CLAUSE_CHARS,
@@ -318,13 +559,16 @@ function dumpDefaults() {
         extraCommandsDirs: [],
         persist: true,
         mapFile: DEFAULT_MAP_FILE,
+        blurbOverridesFile: DEFAULT_BLURB_OVERRIDES_FILE,
+        injectEveryMessages: DEFAULT_INJECT_EVERY_MESSAGES,
       },
     }),
   );
 }
 
-/** The non-empty catalog keyed by kind, in the order `kinds` lists them. */
-function buildCatalog(kinds, cwd, config, maxClauseChars) {
+/** The non-empty raw catalog (description/maxClauseChars/stamp per entry — no blurbs yet),
+ * keyed by kind, in the order `kinds` lists them. */
+function buildRawCatalog(kinds, cwd, config, maxClauseChars) {
   const catalog = {};
   for (const kind of kinds) {
     const entries = entriesForKind(kind, cwd, config, maxClauseChars);
@@ -348,6 +592,55 @@ function renderCatalog(catalog, kinds) {
   return `[capabilities] available (check before improvising something one of these covers):\n${sections.join('\n')}\n`;
 }
 
+/** Every tunable read out of the raw config object, with its default applied — keeps main()
+ * a single flat read instead of five inline `config.x || DEFAULT_X` expressions. */
+function resolvedConfig(config) {
+  return {
+    maxClauseChars: Number(config.maxClauseChars) || DEFAULT_MAX_CLAUSE_CHARS,
+    kinds: Array.isArray(config.kinds) ? config.kinds : DEFAULT_KINDS,
+    mapFile: config.mapFile || DEFAULT_MAP_FILE,
+    blurbOverridesFile:
+      config.blurbOverridesFile || DEFAULT_BLURB_OVERRIDES_FILE,
+    injectEveryMessages:
+      Number(config.injectEveryMessages) || DEFAULT_INJECT_EVERY_MESSAGES,
+    persist: config.persist !== false,
+  };
+}
+
+/** The rendered { name, blurb } catalog for this run: reused verbatim from the persisted
+ * map when disk is provably unchanged since the last scan (same fingerprint), or freshly
+ * derived (overrides applied, then mechanical truncation for the rest) otherwise. Re-
+ * deriving is the only per-entry work worth skipping — everything downstream only ever
+ * sees { name, blurb }, never `stamp`/`description`/`maxClauseChars`. */
+function resolveCatalog(rawCatalog, persisted, fingerprint, cwd, settings) {
+  if (persisted.fingerprint === fingerprint && persisted.catalog) {
+    return persisted.catalog;
+  }
+  const overrides = blurbOverridesFor(cwd, settings.blurbOverridesFile);
+  const rendered = Object.fromEntries(
+    Object.entries(rawCatalog).map(([kind, entries]) => [
+      kind,
+      applyBlurbs(entries, overrides),
+    ]),
+  );
+  return withoutStamps(rendered);
+}
+
+/** Whether this run should inject the rendered catalog, and the counter value to persist
+ * either way. A fingerprint change forces immediate injection: either this is the very
+ * first run for this project (persisted.fingerprint is null — nothing has ever been
+ * injected, and waiting up to injectEveryMessages turns before the model learns these
+ * capabilities exist is the wrong default) or the disk catalog changed since the last scan
+ * (a capability was added/removed — worth surfacing right away, not on whatever the counter
+ * happens to be). Both reset the counter, same as a normal throttled trigger. */
+function injectionDecision(persisted, fingerprint, injectEveryMessages) {
+  const catalogChanged = persisted.fingerprint !== fingerprint;
+  const nextMessageCount = persisted.messageCount + 1;
+  const shouldInject =
+    catalogChanged || nextMessageCount >= injectEveryMessages;
+  return { shouldInject, messageCount: shouldInject ? 0 : nextMessageCount };
+}
+
 function main() {
   if (process.env[DUMP_ENV]) {
     dumpDefaults();
@@ -358,20 +651,51 @@ function main() {
   const cwd = payload.cwd || process.cwd();
 
   const config = gateConfig(cwd);
-  if (!config || config.enabled !== true) return; // opt-in: off unless explicitly enabled
+  const isEnabled =
+    config.enabled === undefined ? ENABLED_BY_DEFAULT : config.enabled;
+  if (!isEnabled) return;
+
+  const settings = resolvedConfig(config);
+  const rawCatalog = buildRawCatalog(
+    settings.kinds,
+    cwd,
+    config,
+    settings.maxClauseChars,
+  );
+  if (Object.keys(rawCatalog).length === 0) return; // nothing to surface: never overwrite a good map
 
-  const maxClauseChars =
-    Number(config.maxClauseChars) || DEFAULT_MAX_CLAUSE_CHARS;
-  const kinds = Array.isArray(config.kinds) ? config.kinds : DEFAULT_KINDS;
+  const overrideStamps = blurbOverrideStampsFor(
+    cwd,
+    settings.blurbOverridesFile,
+  );
+  const fingerprint = fingerprintOf(rawCatalog, overrideStamps);
+  const root = projectRootOf(cwd);
+  const mapPath = root ? join(root, settings.mapFile) : null;
+  const persisted = mapPath
+    ? readPersistedState(mapPath)
+    : { catalog: null, fingerprint: null, messageCount: 0 };
 
-  const catalog = buildCatalog(kinds, cwd, config, maxClauseChars);
-  if (Object.keys(catalog).length === 0) return; // nothing to surface: never overwrite a good map
+  const catalog = resolveCatalog(
+    rawCatalog,
+    persisted,
+    fingerprint,
+    cwd,
+    settings,
+  );
 
-  if (config.persist !== false) {
-    persistMap(cwd, config.mapFile || DEFAULT_MAP_FILE, catalog);
+  const { shouldInject, messageCount } = injectionDecision(
+    persisted,
+    fingerprint,
+    settings.injectEveryMessages,
+  );
+
+  if (settings.persist && mapPath) {
+    persistMap(cwd, settings.mapFile, catalog, fingerprint, messageCount);
   }
 
-  process.stdout.write(renderCatalog(catalog, kinds));
+  if (shouldInject) {
+    process.stdout.write(renderCatalog(catalog, settings.kinds));
+  }
 }
 
 main();

package/plugins/gates/hooks/hooks.json

@@ -121,6 +121,16 @@
           }
         ]
       },
+      {
+        "matcher": "Agent|Task|invoke_subagent|mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gates/brief-approved/index.mjs\"",
+            "timeout": 30
+          }
+        ]
+      },
       {
         "matcher": "Agent|Task|invoke_subagent|mcp__.*",
         "hooks": [

package/plugins/tasks/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tasks",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Deterministic task tracking for Claude Code: persists tasks the model registers via the CLI, reminds of open tasks on a message counter, and lists active tasks on session start.",
   "author": {
     "name": "Devrik"

package/registry.json

@@ -293,6 +293,27 @@
             }
           ]
         },
+        {
+          "id": "brief-approved",
+          "configKey": "requireApprovedBriefBeforeImplementing",
+          "default": true,
+          "event": "PreToolUse",
+          "tools": ["delegation"],
+          "description": "Denies implementing a cited feature whose brief has no recorded user approval (status: approved + approval_quote frontmatter).",
+          "script": "gates/brief-approved/index.mjs",
+          "params": [
+            {
+              "name": "catalogLocations",
+              "type": "string[]",
+              "description": "Paths searched for the feature catalog."
+            },
+            {
+              "name": "exemptSubagents",
+              "type": "string[]",
+              "description": "Subagent types exempt from the approval requirement."
+            }
+          ]
+        },
         {
           "id": "implementation-pipeline",
           "configKey": "requireImplementationPipeline",
@@ -826,7 +847,7 @@
         {
           "id": "capability-map",
           "configKey": "injectCapabilityMap",
-          "default": false,
+          "default": true,
           "event": "UserPromptSubmit",
           "tools": [],
           "description": "Injects the current catalog of the project's AI capabilities (skills, agents/subagents, commands) as compact context on every message, grouped by kind, read fresh from disk. Also persists it to .ai/capability-map.json like the tool map. Autosynced: it lists the directories, never a hardcoded copy. Never blocks.",