@devrik-tools/claude-gates 0.7.1 → 0.7.2

package/.claude-plugin/marketplace.json

@@ -11,13 +11,13 @@
       "name": "gates",
       "source": "./plugins/gates",
       "description": "PreToolUse gates: destructive-command blocks, protected paths, delegation/spec/quality rules, tool-discovery and forge-pipeline enforcement. Which gates run is decided by .ai/config.json (project) or ~/.claude/claude-gates/config.json (global).",
-      "version": "0.7.1"
+      "version": "0.7.2"
     },
     {
       "name": "tasks",
       "source": "./plugins/tasks",
       "description": "Deterministic task tracking: the model registers tasks via the CLI, a UserPromptSubmit hook reminds of open tasks every few messages, and a SessionStart hook lists active tasks when a session opens.",
-      "version": "0.7.1"
+      "version": "0.7.2"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devrik-tools/claude-gates",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "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.7.1",
+  "version": "0.7.2",
   "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/audit-before-build/index.mjs

@@ -54,7 +54,11 @@ function checkDelegation(toolInput) {
 
   deny(
     CONFIG_KEY,
-    'Delegating creation of a new script/checker/gate/hook/linter/tool without evidence of a prior audit. State what you searched and why no existing tool covers this (e.g. "audited and no existing tool...").',
+    'Blocked: this delegation prompt asks to create a new script/checker/gate/hook/linter/' +
+      'tool, and nothing in the prompt shows a prior audit. No filesystem exploration is ' +
+      'needed to fix this — add ONE phrase to the prompt matching ' +
+      `/${AUDIT_EVIDENCE_PATTERN.source}/i, e.g.: "audited and no existing tool covers this" ` +
+      '(this exact phrase is guaranteed to match). Then relaunch the same delegation.',
   );
 }
 
@@ -85,7 +89,11 @@ function checkWrite(toolInput, parameters) {
 
   deny(
     CONFIG_KEY,
-    `Creating a new executable tool at ${filePath} without a justification comment (e.g. "justification: ..."). Document why no existing tool covers this before building a new one.`,
+    `Blocked: '${filePath}' is a new executable tool with no justification comment in its ` +
+      'content. No filesystem exploration is needed to fix this — add ONE line to the ' +
+      `file's content matching /${INLINE_JUSTIFICATION_PATTERN.source}/i, e.g.: ` +
+      '"// justification: no existing tool covers this" (this exact phrase is guaranteed ' +
+      'to match). Then retry the exact same write.',
   );
 }
 

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

@@ -194,21 +194,26 @@ runGate(
     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);
-    });
+    const unapproved = citedFeatures
+      .map((feature) => ({
+        feature,
+        contractPath: contractFileFor(treeRoot, feature),
+      }))
+      .filter(({ contractPath }) => contractPath) // no contractPath: sdd-specs already denies that case
+      .filter(({ contractPath }) => !isApproved(contractPath));
 
     if (unapproved.length === 0) return;
 
+    const fileList = unapproved
+      .map(({ feature, contractPath }) => `${feature} -> ${contractPath}`)
+      .join('\n  ');
     deny(
       CONFIG_KEY,
-      `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' +
+      `This implementation delegation cites unapproved feature(s):\n  ${fileList}\n` +
+        '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 that exact contract file before ' +
+        'relaunching (no filesystem exploration needed — the path above is the file to edit):\n' +
         '---\nstatus: approved\napproved_at: <ISO timestamp>\n' +
         'approval_quote: "<the user\'s own confirming words>"\n---',
     );

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

@@ -3,6 +3,7 @@ import {
   warn,
   toolInGroups,
   writtenContentOf,
+  writtenPathOf,
 } from '../../lib/hook-io.mjs';
 
 const GATE_ID = 'diagnosis-before-patch';
@@ -37,12 +38,21 @@ runGate(
     const patterns = parameters.timeoutPatterns.map(
       (source) => new RegExp(source, 'i'),
     );
-    const touchesTimeout = patterns.some((pattern) => pattern.test(text));
-    if (!touchesTimeout) return;
+    const matched = patterns
+      .map((pattern) => pattern.exec(text))
+      .find((match) => match !== null);
+    if (!matched) return;
 
+    const filePath = writtenPathOf(toolInput) || '(unknown path)';
     warn(
       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.',
+      `You are writing '${matched[0].trim()}' into ${filePath} — a timeout/deadline/retry ` +
+        'value. Before changing a value to fix a symptom ("X is slow/fails"), confirm you ' +
+        'have the evidence that proves the cause: a log line from the failing provider/' +
+        "process, not a hypothesis. If you don't have that log line yet, get it before " +
+        'writing this change — do not guess a new number. A timeout should measure ' +
+        'inactivity, not total time: a process that is still progressing should not be cut ' +
+        'off. This is a warning, not a block — the write proceeds either way.',
     );
   },
 );

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

@@ -147,7 +147,10 @@ function checkLiveTask(pointerPath) {
       CONFIG_KEY,
       `The active task '${slug}' has no contract on disk: none of ` +
         `${TASK_CONTRACT_FILES.join(', ')} exists under ${taskDirectory}. ` +
-        'Write the contract before implementing.',
+        `Write ONE of those files there before implementing (this gate's contract root is ` +
+        `.ai/pipeline/${slug}/ — a brief.md under .ai/features/${slug}/ satisfies a ` +
+        'different gate, sdd-specs, but NOT this one; if you already wrote a brief there, ' +
+        `create a short asserts.md under ${taskDirectory} referencing it).`,
     );
   }
 }

package/plugins/gates/hooks/gates/recurrence-lock/index.mjs

@@ -76,6 +76,7 @@ runGate(
   ({ toolName, parameters }) => {
     if (!toolInGroups(toolName, ['execution', 'delegation'])) return;
 
+    const recurrencesFile = join('.ai', 'reincidencias.json');
     const openRecurrences = loadOpenRecurrences(
       process.cwd(),
       parameters.thresholdAppearances,
@@ -85,7 +86,11 @@ runGate(
     const names = openRecurrences.map((entry) => entry.class).join(', ');
     deny(
       CONFIG_KEY,
-      `Registered recurring issue classes are still open and at/above threshold: ${names}. Resolve or close them before proceeding.`,
+      `Registered recurring issue class(es) still open and at/above the ` +
+        `${parameters.thresholdAppearances}-occurrence threshold: ${names}. Fix the root ` +
+        `cause of the class (not this one instance), then in ${recurrencesFile} set that ` +
+        'class\'s "status" to "closed" (or "cerrada") before proceeding — no other file to ' +
+        'find, this is the only source this gate reads.',
     );
   },
 );

package/plugins/gates/hooks/gates/reuse-before-build/index.mjs

@@ -196,14 +196,50 @@ function isToolLikePath(filePath, parameters) {
   );
 }
 
-const DENY_MESSAGE =
-  'Do not reinvent the wheel. Before building this, confirm nothing already covers it, ' +
-  'auditing in this order: (1) LOCAL — the repo and installed deps (search by name and ' +
-  'usage, read the manifest); (2) CONTEXT7 — resolve the candidate library and read its ' +
-  'docs to confirm whether it truly covers the need; (3) WEB — search npm and plugin ' +
-  'marketplaces for a maintained package. If it is genuinely absent, record the finding ' +
-  '(e.g. `claude-gates tool-map add`) and state the audit in the text, so the exploration ' +
-  'is not repeated next time.';
+// The exact phrase AUDIT_DONE_PATTERN matches — quoted verbatim in the deny message so the
+// model can copy it instead of guessing a paraphrase the regex might not recognize (a vague
+// "I checked" or "no lo encontré" does NOT match AUDIT_DONE_PATTERN and the gate fires again).
+const AUDIT_DONE_EXAMPLE_PHRASE = 'no existing tool covers this';
+
+/** The concrete deny message for a blocked WRITE: names the exact file and gives the exact
+ * text to add (copy-pasteable, matches AUDIT_DONE_PATTERN verbatim) — no exploration needed
+ * to find any of this, it is the gate's own job to hand it over. Adding the phrase also
+ * satisfies the tool-map gate (maintainToolMap), which records the file + this same line
+ * into .ai/tool-map.json automatically — no separate command to run. */
+function writeDenyMessage(filePath) {
+  return (
+    `Blocked: '${filePath}' looks like a new tool/helper, and nothing shows the wheel was ` +
+    'checked first. Pick ONE, then retry the exact same write:\n' +
+    `  1. It already exists here or in an installed dep — don't create '${filePath}'; ` +
+    'reuse/import the existing one instead.\n' +
+    '  2. It does not exist anywhere you checked (repo, installed deps, npm/marketplaces) — ' +
+    "add ONE line to the file's content stating that, e.g.: " +
+    `"// ${AUDIT_DONE_EXAMPLE_PHRASE}" (any phrase matching /${AUDIT_DONE_PATTERN.source}/i ` +
+    'works, this one is guaranteed to). That line also gets this file auto-recorded into ' +
+    '.ai/tool-map.json — nothing further to run.\n' +
+    'No filesystem exploration is required to satisfy this gate — the audit is a sentence ' +
+    'in the file or a matching package.json dependency, nothing else.'
+  );
+}
+
+/** The concrete deny message for a blocked DELEGATION prompt: same two options, but no file
+ * name exists yet (only a prompt), so both talk about the prompt text, not a file. */
+function delegationDenyMessage() {
+  return (
+    "Blocked: this delegation's prompt asks to build a new tool/helper, and nothing in " +
+    'the prompt shows the wheel was checked first. Pick ONE, then relaunch the same ' +
+    'delegation with the prompt updated:\n' +
+    '  1. It already exists (repo, installed dep) — do not delegate a new build; ' +
+    'reference the existing one in the prompt instead.\n' +
+    '  2. It does not exist anywhere you checked — add ONE line to the prompt stating ' +
+    `that, e.g.: "${AUDIT_DONE_EXAMPLE_PHRASE}" (any phrase matching ` +
+    `/${AUDIT_DONE_PATTERN.source}/i works, this one is guaranteed to). Once the delegate ` +
+    'actually writes the file, include the same phrase in its content so it also gets ' +
+    'auto-recorded into .ai/tool-map.json.\n' +
+    'No filesystem exploration is required to satisfy this gate — the audit is a sentence ' +
+    'in the prompt, or a matching package.json dependency, nothing else.'
+  );
+}
 
 /** A build is cleared when its text declares an audit, its name is already recorded in the
  * map, or an installed dependency covers it. `toolBaseName` is used for the last two. */
@@ -224,7 +260,7 @@ function checkDelegation(toolInput, cwd, parameters) {
   const prompt = delegationPromptOf(toolInput);
   if (!isBuildIntent(prompt)) return;
   if (buildIsCleared(prompt, cwd, parameters, null)) return;
-  deny(CONFIG_KEY, DENY_MESSAGE);
+  deny(CONFIG_KEY, delegationDenyMessage());
 }
 
 /** Write: block a new tool-like file that is not cleared by content, map, or an installed dep. */
@@ -237,7 +273,7 @@ function checkWrite(toolInput, cwd, parameters) {
   const content = writtenContentOf(toolInput);
   const toolBaseName = basename(filePath).replace(/\.[^.]+$/, '');
   if (buildIsCleared(content, cwd, parameters, toolBaseName)) return;
-  deny(CONFIG_KEY, DENY_MESSAGE);
+  deny(CONFIG_KEY, writeDenyMessage(filePath));
 }
 
 runGate(

package/plugins/gates/hooks/gates/rule-skill-autodiscovery/index.mjs

@@ -150,14 +150,14 @@ runGate(
     for (const script of scripts) {
       const before = snapshotConfigs(watchedConfigPaths);
 
-      let failed = false;
+      let failure = null;
       try {
         execFileSync(process.execPath, [script], {
-          stdio: 'ignore',
+          stdio: ['ignore', 'ignore', 'pipe'],
           timeout: 5000,
         });
-      } catch {
-        failed = true;
+      } catch (error) {
+        failure = error;
       }
 
       if (configsTampered(before)) {
@@ -169,10 +169,16 @@ runGate(
         return;
       }
 
-      if (failed) {
+      if (failure) {
+        const stderr = String(failure.stderr ?? '').trim();
+        const detail = stderr || failure.message || String(failure);
         deny(
           CONFIG_KEY,
-          `Sub-gate failed: ${relative(projectRoot, script)}. Fix it before continuing.`,
+          `Sub-gate '${relative(projectRoot, script)}' failed (exit ` +
+            `${failure.status ?? 'unknown'}): ${detail}\n` +
+            'No filesystem exploration is needed — fix that script (open it at the path ' +
+            'above and address the error shown), or remove it from ' +
+            `${parameters.rulesDir}/ if it should not run as a gate.`,
         );
         return;
       }

package/plugins/gates/hooks/gates/sdd-specs/index.mjs

@@ -147,15 +147,31 @@ function parseJsonOrNull(text) {
 }
 
 /** Denies the single first advanced-status feature in the new catalog content that has
- * no contract on disk, or does nothing when every advanced feature has one. */
+ * no contract on disk, or does nothing when every advanced feature has one. A feature
+ * object missing its `name` field is denied too (not silently skipped) — it is malformed
+ * catalog data, not a feature this gate has decided has no obligations. */
 function denyIfAdvancedFeatureLacksContract(features, treeRoot) {
   for (const feature of features) {
-    if (!feature?.name || !ADVANCED_STATUSES.has(feature.status)) continue;
+    if (!ADVANCED_STATUSES.has(feature?.status)) continue;
+    if (!feature?.name) {
+      deny(
+        CONFIG_KEY,
+        `A feature entry has status '${feature.status}' but no 'name' field: ` +
+          `${JSON.stringify(feature)}. Every feature needs a 'name' so its contract tree ` +
+          '(.ai/features/<name>/) can be located — add it before writing this status.',
+      );
+      continue;
+    }
     if (contractExistsFor(treeRoot, feature.name)) continue;
+    const featureDirectory = join(
+      treeRoot ?? join(process.cwd(), '.ai', 'features'),
+      feature.name,
+    );
     deny(
       CONFIG_KEY,
       `Feature '${feature.name}' is set to '${feature.status}' but has no non-empty ` +
-        `contract (${CONTRACT_FILES.join(', ')}) under the discovered contract tree.`,
+        `contract on disk. Write ONE of these files under ${featureDirectory}/ (any one ` +
+        `is enough): ${CONTRACT_FILES.join(', ')}.`,
     );
   }
 }
@@ -172,9 +188,10 @@ function checkCatalogWrite(toolInput, catalogPath, treeRoot) {
     // hidden behind a malformed payload must not be silently allowed through.
     deny(
       CONFIG_KEY,
-      `The write to ${CATALOG_FILE_NAME} does not parse as JSON. A catalog write that ` +
-        'cannot be verified for the spec-contract invariant is not allowed; fix the JSON ' +
-        'or write valid content.',
+      `The write to ${CATALOG_FILE_NAME} does not parse as JSON (JSON.parse threw). This ` +
+        'is a syntax problem in the content being written, not a missing-field one — check ' +
+        'for a trailing comma, unquoted key, or unclosed bracket in what you are about to ' +
+        'write. No filesystem exploration needed; the payload itself is the thing to fix.',
     );
   }
   const features = Array.isArray(parsed?.features) ? parsed.features : [];
@@ -212,11 +229,15 @@ function checkDelegation(toolInput, treeRoot, exemptSubagents) {
     (feature) => !contractExistsFor(treeRoot, feature),
   );
   if (missing.length === citedFeatures.length) {
+    const root = treeRoot ?? join(process.cwd(), '.ai', 'features');
+    const fileList = missing
+      .map((feature) => `${feature} -> ${join(root, feature)}/`)
+      .join('\n  ');
     deny(
       CONFIG_KEY,
-      `This implementation delegation cites feature(s) [${missing.join(', ')}] with no ` +
-        `non-empty contract (${CONTRACT_FILES.join(', ')}) on disk. Write the contract ` +
-        'before implementing.',
+      `This implementation delegation cites feature(s) with no contract on disk:\n  ${fileList}\n` +
+        `Write ONE of these files in each directory above (any one is enough): ` +
+        `${CONTRACT_FILES.join(', ')}. Then relaunch.`,
     );
   }
 }

package/plugins/gates/hooks/lib/hook-io.mjs

@@ -178,7 +178,15 @@ const SHELL_WRITE_PATTERNS = [
   /\b(?:touch|tee)\s+(?:-\S+\s+)*(['"]?)([^\s'"|;&<>]+)\1/g,
   // cp / mv / install destination is the LAST path; capture the first arg after the command
   // as a cheap proxy (over-detects the source too, which is acceptable — a gate re-checks).
-  /\b(?:cp|mv|install)\s+(?:-\S+\s+)*(['"]?)([^\s'"|;&<>]+)\1/g,
+  // Anchored to the START of a command (start of string, or right after a separator like
+  // `;`/`&&`/`||`/`|`), NOT `\b`, which matched "install" as a bare word anywhere — including
+  // as npm/pip/yarn's SUBCOMMAND (`npm install -D daisyui` was misread as the Unix `install`
+  // utility, capturing the package name "daisyui" as a phantom root-level file target and
+  // tripping root-whitelist on a plain dependency install). `npm install`/`pip install`/
+  // `yarn install` never start a shell command with the bare word "install" as argv[0], so
+  // anchoring at the command boundary excludes them while still catching a real `install ...`
+  // invocation (the coreutils/BSD command) at the start of a command.
+  /(?:^|[;&|])\s*(?:cp|mv|install)\s+(?:-\S+\s+)*(['"]?)([^\s'"|;&<>]+)\1/g,
 ];
 
 /**

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

@@ -1,6 +1,6 @@
 {
   "name": "tasks",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "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"