@devrik-tools/claude-gates 0.6.0 → 0.7.1

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/gates/circuit-breaker/index.mjs

@@ -448,7 +448,7 @@ function identityKey(signature) {
 
 function denyRepeatedAttempt(count) {
   deny(
-    GATE_ID,
+    CONFIG_KEY,
     `This same task received ${count} consecutive attempts (same goal, same scope and the same files) ` +
       'in this session, regardless of which subagent_type carried it. STOP retrying and ASK THE USER ' +
       'for help now: state what you tried, what blocked it, and the specific decision or input you need ' +

package/plugins/gates/hooks/gates/dependency-skills/index.mjs

@@ -112,7 +112,7 @@ runGate(
     if (unmatched.length === 0) return;
 
     deny(
-      GATE_ID,
+      CONFIG_KEY,
       `New dependencies without a matching skill in ${parameters.projectSkillsDir}: ${unmatched.join(', ')}. ` +
         'Add a skill documenting how to use each (directory name matching or containing the ' +
         'package name), OR, if a dependency genuinely needs no skill, declare it in ' +

package/plugins/gates/hooks/gates/diagnosis-before-patch/index.mjs

@@ -41,7 +41,7 @@ runGate(
     if (!touchesTimeout) return;
 
     warn(
-      GATE_ID,
+      CONFIG_KEY,
       'Diagnosis before patch: you are adjusting a timeout/deadline/retry value. Before changing a value to fix a symptom ("X is slow/fails"), confirm you read the evidence that proves the cause (a log line from the failing provider/process, not a hypothesis). A timeout should measure inactivity, not total time: a process that is progressing should not be cut off.',
     );
   },

package/plugins/gates/hooks/gates/feature-catalog/index.mjs

@@ -61,7 +61,7 @@ runGate(
     // Base, non-negotiable: `done` is never written directly to the catalog.
     if (DONE_STATUS_PATTERN.test(content)) {
       deny(
-        GATE_ID,
+        CONFIG_KEY,
         `Writing 'status: done' directly to ${catalogFileName} is not allowed. ` +
           'Only a review/QA subagent or a validated automated process may close a feature.',
       );
@@ -74,7 +74,7 @@ runGate(
       .length;
     if (inProgressCount > maxInProgress) {
       deny(
-        GATE_ID,
+        CONFIG_KEY,
         `${catalogFileName} would have ${inProgressCount} features 'in_progress'; ` +
           `the maximum allowed is ${maxInProgress}.`,
       );

package/plugins/gates/hooks/gates/force-parallel/index.mjs

@@ -122,7 +122,7 @@ runGate(
     if (nextCount < threshold) return;
 
     warn(
-      GATE_ID,
+      CONFIG_KEY,
       WARN_MESSAGE.replace('{count}', String(nextCount))
         .replace(
           '{windowSeconds}',

package/plugins/gates/hooks/gates/forge-flow/index.mjs

@@ -121,11 +121,11 @@ runGate(
     const result = await forgeRunState(root, forgeDatabasePath);
 
     if (result.state === 'active') return; // pipeline is running → allow
-    if (result.state === 'none') deny(GATE_ID, DENY_MESSAGE); // no run → block
+    if (result.state === 'none') deny(CONFIG_KEY, DENY_MESSAGE); // no run → block
     // state 'unknown': the DB could not be read. Allow so a broken lookup never freezes work,
     // but surface it loudly — a silent allow here would disable the enforcer without a trace.
     warn(
-      GATE_ID,
+      CONFIG_KEY,
       `forge enforcement is degraded: the forge DB could not be read (${result.reason}). ` +
         'Allowing this action, but the pipeline is NOT being enforced. Check that forge is ' +
         `installed and ${forgeDatabasePath} is readable, or turn this gate off if intended.`,