@devrik-tools/claude-gates 0.3.0 → 0.4.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.3.0"
+      "version": "0.4.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.3.0"
+      "version": "0.4.0"
     }
   ]
 }

package/README.md

@@ -5,7 +5,7 @@ Claude executes a tool and **block or warn** when something breaks a rule: a des
 command, a write to a protected file, a delegation with no brief, and more. Everything is
 **configurable per project** and can be **turned on/off** whenever you want.
 
-The core idea: instead of trusting the model to *remember* the rules, a **deterministic**
+The core idea: instead of trusting the model to _remember_ the rules, a **deterministic**
 hook enforces them. A `git reset --hard` does not run because the model chose to behave —
 it is blocked because a gate intercepts it.
 
@@ -65,58 +65,65 @@ works even if you install one on its own.
 `[on]` = enabled by default; `[off]` = enable it if you want it.
 
 ### 🔒 Security — hard blocks on destructive actions
-| Gate | | What it does |
-|---|---|---|
-| `bash-commands` | on | Blocks `git reset --hard`, `rm -rf` over protected areas, force push, and killing processes by name. |
-| `block-remote-publish` | on | Blocks `git push`, `gh pr merge`, `gh release create` without authorization. Set `blockRemotePublish: false` to let the agent publish on its own. |
-| `protected-paths` | on | Blocks writes to `.env`, lockfiles and the harness itself. |
-| `root-whitelist` | on | Blocks new root-level files/folders outside a whitelist. |
-| `no-blocking` | off | Blocks `sleep`, `tail -f`, polling loops and foreground servers. |
+
+| Gate                   |     | What it does                                                                                                                                      |
+| ---------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bash-commands`        | on  | Blocks `git reset --hard`, `rm -rf` over protected areas, force push, and killing processes by name.                                              |
+| `block-remote-publish` | on  | Blocks `git push`, `gh pr merge`, `gh release create` without authorization. Set `blockRemotePublish: false` to let the agent publish on its own. |
+| `protected-paths`      | on  | Blocks writes to `.env`, lockfiles and the harness itself.                                                                                        |
+| `root-whitelist`       | on  | Blocks new root-level files/folders outside a whitelist.                                                                                          |
+| `no-blocking`          | off | Blocks `sleep`, `tail -f`, polling loops and foreground servers.                                                                                  |
 
 ### 🤝 Delegation — requirements on the brief when delegating to a subagent
-| Gate | | What it does |
-|---|---|---|
-| `brief-before-delegate` | off | Requires goal, steps and done-when criteria in the prompt. |
-| `intent-flow` | off | Requires IN SCOPE / OUT OF SCOPE / EDGE CASES sections. |
-| `risk-level` | off | Requires a declared level (QUESTION/MICRO/STANDARD/HIGH-RISK). |
-| `circuit-breaker` | off | Cuts the same delegation retried without real changes. |
-| `no-memory-dependency` | off | Blocks a brief that relies on the subagent "remembering" the chat (add `memory-not-needed` to allow a false positive). |
+
+| Gate                    |     | What it does                                                                                                           |
+| ----------------------- | --- | ---------------------------------------------------------------------------------------------------------------------- |
+| `brief-before-delegate` | off | Requires goal, steps and done-when criteria in the prompt.                                                             |
+| `intent-flow`           | off | Requires IN SCOPE / OUT OF SCOPE / EDGE CASES sections.                                                                |
+| `risk-level`            | off | Requires a declared level (QUESTION/MICRO/STANDARD/HIGH-RISK).                                                         |
+| `circuit-breaker`       | off | Cuts the same delegation retried without real changes.                                                                 |
+| `no-memory-dependency`  | off | Blocks a brief that relies on the subagent "remembering" the chat (add `memory-not-needed` to allow a false positive). |
 
 ### 📋 Spec-driven flow — only relevant if the project adopted spec-driven development
-| Gate | | What it does |
-|---|---|---|
-| `feature-catalog` | on | A single feature in progress; closing requires asserts and review. |
-| `sdd-specs` | off | Requires non-empty requirements/design/tasks before implementing. |
+
+| Gate                      |     | What it does                                                         |
+| ------------------------- | --- | -------------------------------------------------------------------- |
+| `feature-catalog`         | on  | A single feature in progress; closing requires asserts and review.   |
+| `sdd-specs`               | off | Requires non-empty requirements/design/tasks 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). |
+| `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).  |
 
 ### ✨ Quality — code hygiene, diagnosis and language
-| Gate | | What it does |
-|---|---|---|
-| `dependency-skills` | on | Blocks a new direct dependency with no matching skill (declare it in `depsWithoutOwnApi` if it needs none). |
-| `root-cause-first` | off | Requires an origin→symptom diagnosis before a patch. |
-| `audit-before-build` | off | Before a new script/gate, requires stating that nothing existing covers it. |
-| `never-assume` | off | Flags unverified assumptions in briefs and code. |
-| `rule-skill-autodiscovery` | off | Loads gates the project declares in its `rules/` and `skills/`. |
-| `recurrence-lock` | on | A second occurrence of a defect class requires its deterministic block. |
-| `test-after-implementation` | off | Blocks a test written after its paired implementation (add `test-after-impl:allow` for a regression test). |
-| `no-reconfirm` | on | Never re-ask what you already answered. |
-| `neutral-spanish` | on | Blocks voseo or regional lexicon in written text (add `neutral-spanish:allow` for a deliberate quote/fixture). |
-| `diagnosis-before-patch` | on | Warns when timeouts/retries change without evidence. |
+
+| Gate                        |     | What it does                                                                                                   |
+| --------------------------- | --- | -------------------------------------------------------------------------------------------------------------- |
+| `dependency-skills`         | on  | Blocks a new direct dependency with no matching skill (declare it in `depsWithoutOwnApi` if it needs none).    |
+| `root-cause-first`          | off | Requires an origin→symptom diagnosis before a patch.                                                           |
+| `audit-before-build`        | off | Before a new script/gate, requires stating that nothing existing covers it.                                    |
+| `never-assume`              | off | Flags unverified assumptions in briefs and code.                                                               |
+| `rule-skill-autodiscovery`  | off | Loads gates the project declares in its `rules/` and `skills/`.                                                |
+| `recurrence-lock`           | on  | A second occurrence of a defect class requires its deterministic block.                                        |
+| `test-after-implementation` | off | Blocks a test written after its paired implementation (add `test-after-impl:allow` for a regression test).     |
+| `no-reconfirm`              | on  | Never re-ask what you already answered.                                                                        |
+| `neutral-spanish`           | on  | Blocks voseo or regional lexicon in written text (add `neutral-spanish:allow` for a deliberate quote/fixture). |
+| `diagnosis-before-patch`    | on  | Warns when timeouts/retries change without evidence.                                                           |
 
 ### 🔎 Tool discovery — don't reinvent the wheel
-| Gate | | What it does |
-|---|---|---|
+
+| Gate                 |     | What it does                                                                                                 |
+| -------------------- | --- | ------------------------------------------------------------------------------------------------------------ |
 | `reuse-before-build` | off | Before building a tool, consults the project tool map; blocks if you did not audit (local → Context7 → web). |
-| `tool-map` | off | Records discovered tools in `.ai/tool-map.json` so exploration is not repeated. |
+| `tool-map`           | off | Records discovered tools in `.ai/tool-map.json` so exploration is not repeated.                              |
 
 ### 🏭 Forge pipeline — enforces the forge workflow
-| Gate | | What it does |
-|---|---|---|
+
+| Gate         |     | What it does                                                                                                                                                                                            |
+| ------------ | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `forge-flow` | off | In a project that adopted [forge](https://github.com/DevRik99/forge-mcp), blocks editing/running unless an active forge run exists. Closes the hole the MCP cannot: it forces you through the pipeline. |
 
-### 🩺 Session start — startup checks *(work in progress)*
+### 🩺 Session start — startup checks _(work in progress)_
+
 `doctor`, `ask-adoption`, `wiring-check` — declared in the catalog; their scripts are being
 migrated next.
 
@@ -180,8 +187,17 @@ claude-gates init --no-install        # write the config but do not install the
 # Inspect the catalog:
 claude-gates registry --list          # list families and gates
 claude-gates registry --check         # validate registry.json
+
+# Verify the gates actually react (not just that they are wired):
+claude-gates smoke                    # feed each gate a known violation; exits non-zero if any does not block/warn
 ```
 
+`smoke` is the behavioral check `registry --check` (structure) and the doctor hook (files
+exist) do not do: it feeds every gate a known violation and confirms it really denies/warns.
+Gates whose violation needs seeded state (a db, a git repo, cross-call state) report `skip`,
+never a false pass. Run it after install, or in CI, to catch a gate that is wired but silently
+allows.
+
 ---
 
 ## Repository layout

package/cli/index.mjs

@@ -1,104 +1,154 @@
-#!/usr/bin/env node
-// Entry point (commander). Commands:
-//   init      interactive (or flag-driven) selection of gates, per project or globally
-//   registry  --check validates registry.json; --list prints the catalog
-
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { Command } from 'commander';
-import {
-  EXIT_CODE,
-  LIST_SEPARATOR,
-  REGISTRY_PATH,
-  REPOSITORY_ROOT,
-} from './constants.mjs';
-import { loadRegistry, validateRegistry } from './registry.mjs';
-import { registerTaskCommand } from './task.mjs';
-
-const packageManifest = JSON.parse(
-  readFileSync(join(REPOSITORY_ROOT, 'package.json'), 'utf8'),
-);
-
-function fail(message) {
-  process.stderr.write(`${message}\n`);
-  process.exit(EXIT_CODE.FAILURE);
-}
-
-function splitList(value) {
-  return value
-    .split(LIST_SEPARATOR)
-    .map((item) => item.trim())
-    .filter(Boolean);
-}
-
-function registryCheck() {
-  const problems = validateRegistry(
-    JSON.parse(readFileSync(REGISTRY_PATH, 'utf8')),
-  );
-  if (problems.length > 0) {
-    fail(`registry.json is invalid:\n- ${problems.join('\n- ')}`);
-  }
-  process.stdout.write('registry.json OK\n');
-}
-
-function registryList() {
-  const registry = loadRegistry();
-  for (const family of registry.families) {
-    process.stdout.write(`${family.name} (${family.id})\n`);
-    for (const gate of family.gates) {
-      const marker = gate.default ? '*' : ' ';
-      process.stdout.write(`  ${marker} ${gate.id}  ${gate.configKey}\n`);
-    }
-  }
-  process.stdout.write('\n* = recommended default\n');
-}
-
-const program = new Command()
-  .name(packageManifest.name)
-  .description(packageManifest.description)
-  .version(packageManifest.version);
-
-program
-  .command('init')
-  .description('Choose which gates to adopt and write the config.')
-  .option('--project', 'apply to this project (<root>/.ai/config.json)')
-  .option('--global', 'apply globally (~/.claude/claude-gates/config.json)')
-  .option('--defaults', 'enable the recommended defaults')
-  .option('--all', 'enable every gate')
-  .option('--none', "record a 'no' so you are not asked again")
-  .option(
-    '--families <ids>',
-    'enable whole families, comma-separated',
-    splitList,
-  )
-  .option(
-    '--gates <ids>',
-    'enable individual gates, comma-separated',
-    splitList,
-  )
-  .option('-y, --yes', 'never prompt; use flags and defaults')
-  .option('--no-install', 'write the config but do not install the plugin')
-  .option(
-    '--no-remove-previous',
-    'keep any previously installed plugin version instead of removing it first',
-  )
-  .option('--dry-run', 'show the selection without writing')
-  .action(async (options) => {
-    const { runInit } = await import('./init.mjs');
-    await runInit(options);
-  });
-
-program
-  .command('registry')
-  .description('Inspect registry.json.')
-  .option('--check', 'validate the registry')
-  .option('--list', 'print families and gates')
-  .action((options) => {
-    if (options.check) return registryCheck();
-    if (options.list) return registryList();
-    return fail('registry needs --check or --list');
-  });
-
-registerTaskCommand(program);
-
-program.parseAsync(process.argv).catch((error) => fail(error.message));
+#!/usr/bin/env node
+// Entry point (commander). Commands:
+//   init      interactive (or flag-driven) selection of gates, per project or globally
+//   registry  --check validates registry.json; --list prints the catalog
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Command } from 'commander';
+import {
+  EXIT_CODE,
+  LIST_SEPARATOR,
+  REGISTRY_PATH,
+  REPOSITORY_ROOT,
+} from './constants.mjs';
+import { loadRegistry, validateRegistry } from './registry.mjs';
+import { runSmoke, OUTCOMES } from './smoke.mjs';
+import { registerTaskCommand } from './task.mjs';
+
+const packageManifest = JSON.parse(
+  readFileSync(join(REPOSITORY_ROOT, 'package.json'), 'utf8'),
+);
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(EXIT_CODE.FAILURE);
+}
+
+function splitList(value) {
+  return value
+    .split(LIST_SEPARATOR)
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function registryCheck() {
+  const problems = validateRegistry(
+    JSON.parse(readFileSync(REGISTRY_PATH, 'utf8')),
+  );
+  if (problems.length > 0) {
+    fail(`registry.json is invalid:\n- ${problems.join('\n- ')}`);
+  }
+  process.stdout.write('registry.json OK\n');
+}
+
+function registryList() {
+  const registry = loadRegistry();
+  for (const family of registry.families) {
+    process.stdout.write(`${family.name} (${family.id})\n`);
+    for (const gate of family.gates) {
+      const marker = gate.default ? '*' : ' ';
+      process.stdout.write(`  ${marker} ${gate.id}  ${gate.configKey}\n`);
+    }
+  }
+  process.stdout.write('\n* = recommended default\n');
+}
+
+const SMOKE_FIXTURES_PATH = join(REPOSITORY_ROOT, 'cli', 'smoke-fixtures.json');
+// Width the gate id is padded to so the expected/got columns line up in the report.
+const GATE_ID_COLUMN_WIDTH = 28;
+const OUTCOME_MARK = {
+  [OUTCOMES.REACTED]: 'ok  ',
+  [OUTCOMES.NO_REACTION]: 'FAIL',
+  [OUTCOMES.SKIPPED]: 'skip',
+  [OUTCOMES.ERROR]: 'ERR ',
+};
+
+// Runs each gate against a known violation and reports whether it actually reacts. Unlike
+// `registry --check` (structure) and the doctor hook (files exist), this confirms behavior:
+// it is the check that catches a gate silently allowing its own known violation. Exits
+// non-zero if any gate did not react (a real defect) — so CI or a post-install step can gate
+// on it. Gates whose violation needs seeded state are reported `skip`, never counted as pass.
+function smokeGates() {
+  const manifest = JSON.parse(
+    readFileSync(SMOKE_FIXTURES_PATH, 'utf8'),
+  ).fixtures;
+  const { results, tally } = runSmoke(manifest);
+
+  for (const result of results) {
+    const detail = result.reason ? `  (${result.reason})` : '';
+    process.stdout.write(
+      `${OUTCOME_MARK[result.outcome]}  ${result.id.padEnd(GATE_ID_COLUMN_WIDTH)} ` +
+        `expected=${result.expected} got=${result.got ?? '-'}${detail}\n`,
+    );
+  }
+  process.stdout.write(
+    `\nreacted ${tally.reacted}  ·  no-reaction ${tally['no-reaction']}  ·  ` +
+      `skipped ${tally.skipped}  ·  error ${tally.error}\n`,
+  );
+  if (tally['no-reaction'] > 0 || tally.error > 0) {
+    process.stdout.write(
+      '\nSome gates did not react to their own known violation. This is a defect: ' +
+        'the gate is wired but does not block/warn as declared.\n',
+    );
+    process.exit(EXIT_CODE.FAILURE);
+  }
+}
+
+const program = new Command()
+  .name(packageManifest.name)
+  .description(packageManifest.description)
+  .version(packageManifest.version);
+
+program
+  .command('init')
+  .description('Choose which gates to adopt and write the config.')
+  .option('--project', 'apply to this project (<root>/.ai/config.json)')
+  .option('--global', 'apply globally (~/.claude/claude-gates/config.json)')
+  .option('--defaults', 'enable the recommended defaults')
+  .option('--all', 'enable every gate')
+  .option('--none', "record a 'no' so you are not asked again")
+  .option(
+    '--families <ids>',
+    'enable whole families, comma-separated',
+    splitList,
+  )
+  .option(
+    '--gates <ids>',
+    'enable individual gates, comma-separated',
+    splitList,
+  )
+  .option('-y, --yes', 'never prompt; use flags and defaults')
+  .option('--no-install', 'write the config but do not install the plugin')
+  .option(
+    '--no-remove-previous',
+    'keep any previously installed plugin version instead of removing it first',
+  )
+  .option('--dry-run', 'show the selection without writing')
+  .action(async (options) => {
+    const { runInit } = await import('./init.mjs');
+    await runInit(options);
+  });
+
+program
+  .command('registry')
+  .description('Inspect registry.json.')
+  .option('--check', 'validate the registry')
+  .option('--list', 'print families and gates')
+  .action((options) => {
+    if (options.check) return registryCheck();
+    if (options.list) return registryList();
+    return fail('registry needs --check or --list');
+  });
+
+program
+  .command('smoke')
+  .description(
+    'Feed each gate a known violation and confirm it actually reacts (deny/warn). ' +
+      'Catches a gate that is wired but silently allows. Exits non-zero on any no-reaction.',
+  )
+  .action(() => smokeGates());
+
+registerTaskCommand(program);
+
+program.parseAsync(process.argv).catch((error) => fail(error.message));

package/cli/smoke-fixtures.json

@@ -0,0 +1,390 @@
+{
+  "_comment": "One known-violation payload per gate, derived from each gate's own test.mjs, for the `smoke` command. The runner (cli/smoke.mjs) feeds each payload to the gate and confirms it reacts (deny/warn) as declared. `needsState: true` marks a gate whose violation cannot be reproduced with a single stdin payload alone (it reads a seeded file, a sqlite db, or accumulates state across calls) — the runner SKIPS those honestly instead of miscounting them as a defect. `type` is deny/warn/none. When enabledByDefault is false the runner enables the gate via config before running it. This file is test-fixture data (it embeds regional-Spanish and destructive-command strings on purpose): neutral-spanish:allow",
+  "fixtures": [
+    {
+      "id": "bash-commands",
+      "configKey": "blockDestructiveShellCommands",
+      "enabledByDefault": true,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Bash",
+        "tool_input": { "command": "git reset --hard HEAD~3" }
+      },
+      "needsState": false
+    },
+    {
+      "id": "block-remote-publish",
+      "configKey": "blockRemotePublish",
+      "enabledByDefault": true,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Bash",
+        "tool_input": { "command": "git push origin main" }
+      },
+      "needsState": false
+    },
+    {
+      "id": "protected-paths",
+      "configKey": "blockWritesToProtectedPaths",
+      "enabledByDefault": true,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Write",
+        "tool_input": { "file_path": "/repo/.env" }
+      },
+      "needsState": false
+    },
+    {
+      "id": "root-whitelist",
+      "configKey": "blockPathsOutsideRootWhitelist",
+      "enabledByDefault": true,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Write",
+        "tool_input": { "file_path": "random-orphan.txt" }
+      },
+      "needsState": true,
+      "note": "file_path must resolve against the scratch project root; a literal alone does not reproduce root detection."
+    },
+    {
+      "id": "no-blocking",
+      "configKey": "blockWaitingCommands",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Bash",
+        "tool_input": { "command": "sleep 30" }
+      },
+      "needsState": false
+    },
+    {
+      "id": "brief-before-delegate",
+      "configKey": "requireBriefBeforeDelegating",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Agent",
+        "tool_input": { "prompt": "Fix the login bug please, thanks." }
+      },
+      "needsState": false
+    },
+    {
+      "id": "intent-flow",
+      "configKey": "requireScopeListBeforeDelegating",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Agent",
+        "tool_input": {
+          "prompt": "Implementa el cobro del pago con la nueva pasarela de dinero para el checkout."
+        }
+      },
+      "needsState": false
+    },
+    {
+      "id": "risk-level",
+      "configKey": "requireDeclaredRiskLevel",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Agent",
+        "tool_input": {
+          "prompt": "Arregla el boton que no cambia de color en la pagina."
+        }
+      },
+      "needsState": false
+    },
+    {
+      "id": "circuit-breaker",
+      "configKey": "requireCircuitBreakerOnDelegation",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Agent",
+        "tool_input": { "prompt": "fix the scoring threshold" }
+      },
+      "needsState": true,
+      "note": "stateful: denies only on the 3rd identical retry under the same session id."
+    },
+    {
+      "id": "no-memory-dependency",
+      "configKey": "warnMemoryDependencyInBrief",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Agent",
+        "tool_input": {
+          "prompt": "Acordate de lo que hablamos antes y aplica el mismo criterio."
+        }
+      },
+      "needsState": false
+    },
+    {
+      "id": "force-parallel",
+      "configKey": "warnSequentialDelegations",
+      "enabledByDefault": false,
+      "type": "warn",
+      "payload": { "tool_name": "Task", "tool_input": { "prompt": "do work" } },
+      "needsState": true,
+      "note": "stateful: warns only on the 3rd consecutive delegation under one session."
+    },
+    {
+      "id": "feature-catalog",
+      "configKey": "requireFeatureCatalog",
+      "enabledByDefault": true,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Write",
+        "tool_input": {
+          "file_path": "feature_list.json",
+          "content": "{\"features\":[{\"name\":\"a\",\"status\":\"in_progress\"},{\"name\":\"b\",\"status\":\"in_progress\"}]}"
+        }
+      },
+      "needsState": true,
+      "note": "denies >maxInProgress; needs the catalog shape and threshold to line up."
+    },
+    {
+      "id": "sdd-specs",
+      "configKey": "requireSpecBeforeImplementing",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Agent",
+        "tool_input": {
+          "prompt": "Nivel: STANDARD\nImplementa el flujo de pago."
+        }
+      },
+      "needsState": true,
+      "note": "auto-off unless a features tree exists; needs seeded .ai/feature_list.json + features dir."
+    },
+    {
+      "id": "implementation-pipeline",
+      "configKey": "requireImplementationPipeline",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Agent",
+        "tool_input": { "prompt": "Nivel: STANDARD\nImplementa el checkout." }
+      },
+      "needsState": false
+    },
+    {
+      "id": "mandatory-flow",
+      "configKey": "requireLiveTaskWhenImplementing",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Agent",
+        "tool_input": { "prompt": "Nivel: STANDARD\nImplementa el checkout." }
+      },
+      "needsState": false
+    },
+    {
+      "id": "test-matrix",
+      "configKey": "requireTestMatrixWhenImplementing",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Agent",
+        "tool_input": {
+          "prompt": "Nivel: STANDARD\nImplementa el checkout.",
+          "subagent_type": "backend"
+        }
+      },
+      "needsState": false
+    },
+    {
+      "id": "dependency-skills",
+      "configKey": "requireSkillForNewDependency",
+      "enabledByDefault": true,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Write",
+        "tool_input": {
+          "file_path": "/repo/package.json",
+          "content": "{\"dependencies\":{\"stripe\":\"1.0.0\"}}"
+        }
+      },
+      "needsState": false
+    },
+    {
+      "id": "root-cause-first",
+      "configKey": "requireRootCauseBeforePatch",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Write",
+        "tool_input": {
+          "file_path": "/repo/src/x.js",
+          "content": "// TODO fix later patch"
+        }
+      },
+      "needsState": false
+    },
+    {
+      "id": "audit-before-build",
+      "configKey": "requireAuditBeforeBuilding",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Agent",
+        "tool_input": { "prompt": "create a new script that checks X" }
+      },
+      "needsState": false
+    },
+    {
+      "id": "never-assume",
+      "configKey": "requireVerificationBeforeAssuming",
+      "enabledByDefault": false,
+      "type": "warn",
+      "payload": {
+        "tool_name": "Write",
+        "tool_input": {
+          "file_path": "/repo/src/x.js",
+          "content": "// i assume the timezone is UTC"
+        }
+      },
+      "needsState": false
+    },
+    {
+      "id": "rule-skill-autodiscovery",
+      "configKey": "autodiscoverRulesAndSkills",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Bash",
+        "tool_input": { "command": "echo hi" }
+      },
+      "needsState": true,
+      "note": "needs a project rules/ or .claude/skills gate script present that exits non-zero."
+    },
+    {
+      "id": "recurrence-lock",
+      "configKey": "blockRegisteredRecurrences",
+      "enabledByDefault": true,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Bash",
+        "tool_input": { "command": "echo hi" }
+      },
+      "needsState": true,
+      "note": "needs .ai/reincidencias.json with an open class at/above threshold."
+    },
+    {
+      "id": "test-after-implementation",
+      "configKey": "warnTestWrittenAfterImplementation",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Write",
+        "tool_input": {
+          "file_path": "thing.test.js",
+          "content": "test content"
+        }
+      },
+      "needsState": true,
+      "note": "needs a git repo with an uncommitted paired implementation file."
+    },
+    {
+      "id": "no-reconfirm",
+      "configKey": "requireNoReconfirmOfApproved",
+      "enabledByDefault": true,
+      "type": "warn",
+      "payload": {
+        "tool_name": "AskUserQuestion",
+        "tool_input": {
+          "questions": [{ "question": "Should I migrate the auth schema?" }]
+        }
+      },
+      "needsState": true,
+      "note": "needs a transcript file with a prior approval of the same topic."
+    },
+    {
+      "id": "neutral-spanish",
+      "configKey": "warnNonNeutralSpanish",
+      "enabledByDefault": true,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Write",
+        "tool_input": {
+          "file_path": "/repo/notes.md",
+          "content": "che, mira el laburo que hicimos"
+        }
+      },
+      "needsState": false,
+      "note": "neutral-spanish:allow (fixture data uses regional markers on purpose)"
+    },
+    {
+      "id": "diagnosis-before-patch",
+      "configKey": "warnTimeoutChangeWithoutDiagnosis",
+      "enabledByDefault": true,
+      "type": "warn",
+      "payload": {
+        "tool_name": "Write",
+        "tool_input": {
+          "file_path": "/repo/src/config.js",
+          "content": "const REQUEST_TIMEOUT_MS = 30000;"
+        }
+      },
+      "needsState": false
+    },
+    {
+      "id": "lint-commit",
+      "configKey": "blockCommitWithFailingLint",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Bash",
+        "tool_input": { "command": "git commit -m x" }
+      },
+      "needsState": true,
+      "note": "needs a project package.json whose lint script exits non-zero."
+    },
+    {
+      "id": "reuse-before-build",
+      "configKey": "requireReuseCheckBeforeBuilding",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Write",
+        "tool_input": {
+          "file_path": "scripts/csv-parser.mjs",
+          "content": "export function parse() {}"
+        }
+      },
+      "needsState": false
+    },
+    {
+      "id": "tool-map",
+      "configKey": "maintainToolMap",
+      "enabledByDefault": false,
+      "type": "none",
+      "payload": null,
+      "needsState": true,
+      "note": "side-effect only: records to .ai/tool-map.json, never denies/warns."
+    },
+    {
+      "id": "forge-flow",
+      "configKey": "requireForgeRunToEdit",
+      "enabledByDefault": true,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Write",
+        "tool_input": { "file_path": "src/x.js", "content": "x" }
+      },
+      "needsState": true,
+      "note": "needs a forge adoption marker + sqlite db with no active run."
+    },
+    {
+      "id": "autonomous-mode",
+      "configKey": "autonomousMode",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "AskUserQuestion",
+        "tool_input": { "questions": [{ "question": "A or B?" }] }
+      },
+      "needsState": false
+    }
+  ]
+}

package/cli/smoke.mjs

@@ -0,0 +1,129 @@
+// Gate smoke test: for each gate, feed it a KNOWN violation and confirm it actually reacts
+// (denies / warns), not just that its file exists on disk (that is doctor.mjs's job). This
+// is the check that would have caught neutral-spanish silently warning when the user expected
+// a block, and stop-pending never firing on a fresh install.
+//
+// A gate is run as its own process, exactly as Claude Code runs it: the violation payload on
+// stdin, in a scratch project so its config lookup is isolated. The gate declares in the
+// fixture manifest whether it is expected to DENY or WARN, and whether it needs its config key
+// enabled (gates that are off by default) — the runner writes that config into the scratch
+// project before invoking.
+//
+// Pure of I/O policy: this module runs gates and classifies; the CLI command (index.mjs)
+// owns printing. `runSmoke` returns structured results so it is testable without a terminal.
+
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const GATES_DIR = join(HERE, '..', 'plugins', 'gates', 'hooks', 'gates');
+
+// Max characters of a gate's error message to keep in the report — enough to identify the
+// failure, short enough to keep the per-gate line readable.
+const ERROR_MESSAGE_MAX_LENGTH = 120;
+// A gate that hangs is a defect too; cap how long the smoke test waits for one to respond.
+const GATE_RUN_TIMEOUT_MS = 10000;
+
+// Outcomes the runner reports per gate.
+export const OUTCOMES = Object.freeze({
+  REACTED: 'reacted', // gate produced the expected deny/warn — the protection works
+  NO_REACTION: 'no-reaction', // gate ran but did not react to its own known violation — DEFECT
+  SKIPPED: 'skipped', // fixture needs seeded state we do not set up, or has no violation case
+  ERROR: 'error', // gate threw / could not be run
+});
+
+/** A scratch project (git marker) with an optional gate config, so the run is isolated. */
+function makeScratchProject(configKey, enable) {
+  const project = mkdtempSync(join(tmpdir(), 'gate-smoke-'));
+  mkdirSync(join(project, '.git'));
+  if (enable && configKey) {
+    mkdirSync(join(project, '.ai'));
+    writeFileSync(
+      join(project, '.ai', 'config.json'),
+      JSON.stringify({ gates: { [configKey]: { enabled: true } } }),
+    );
+  }
+  return project;
+}
+
+/** Reads a gate's decision from its stdout. null when it allowed (no output). */
+function decisionOf(stdout) {
+  const trimmed = stdout.trim();
+  if (!trimmed) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+  if (parsed?.hookSpecificOutput?.permissionDecision === 'deny') return 'deny';
+  if (parsed?.decision === 'block') return 'deny'; // Stop-hook shape
+  if (typeof parsed?.hookSpecificOutput?.additionalContext === 'string')
+    return 'warn';
+  return null;
+}
+
+/** Runs one gate against its fixture and classifies the outcome. */
+export function runGateFixture(fixture, { gatesDirectory = GATES_DIR } = {}) {
+  const { id, configKey, enabledByDefault, type, payload, needsState } =
+    fixture;
+
+  if (needsState || type === 'none' || payload == null) {
+    return {
+      id,
+      outcome: OUTCOMES.SKIPPED,
+      expected: type,
+      got: null,
+      reason: needsState
+        ? 'needs seeded state (db/file) not set up by the smoke test'
+        : 'gate has no violation case to plant (side-effect or judgment-only)',
+    };
+  }
+
+  const scriptPath = join(gatesDirectory, id, 'index.mjs');
+  const project = makeScratchProject(configKey, !enabledByDefault);
+
+  let stdout;
+  try {
+    stdout = execFileSync(process.execPath, [scriptPath], {
+      input: JSON.stringify(payload),
+      encoding: 'utf8',
+      cwd: project,
+      env: { ...process.env, HOME: project, USERPROFILE: project },
+      timeout: GATE_RUN_TIMEOUT_MS,
+    });
+  } catch (error) {
+    return {
+      id,
+      outcome: OUTCOMES.ERROR,
+      expected: type,
+      got: null,
+      reason: String(error?.message ?? error).slice(
+        0,
+        ERROR_MESSAGE_MAX_LENGTH,
+      ),
+    };
+  }
+
+  const got = decisionOf(stdout);
+  // A gate expected to deny must deny; a gate expected to warn must warn. Anything else
+  // (allowed silently, or wrong reaction kind) is a no-reaction defect worth surfacing.
+  const reacted = got === type;
+  return {
+    id,
+    outcome: reacted ? OUTCOMES.REACTED : OUTCOMES.NO_REACTION,
+    expected: type,
+    got: got ?? 'allow',
+  };
+}
+
+/** Runs the whole manifest and returns per-gate results plus a summary tally. */
+export function runSmoke(manifest, options = {}) {
+  const results = manifest.map((fixture) => runGateFixture(fixture, options));
+  const tally = { reacted: 0, 'no-reaction': 0, skipped: 0, error: 0 };
+  for (const result of results) tally[result.outcome] += 1;
+  return { results, tally };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devrik-tools/claude-gates",
-  "version": "0.3.0",
+  "version": "0.4.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.3.0",
+  "version": "0.4.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/stop-pending/index.mjs

@@ -130,7 +130,12 @@ function main() {
     if (payload?.stop_hook_active === true) return allow();
 
     const cwd = process.cwd();
-    if (!isGateEnabled(CONFIG_KEY, false, cwd)) return allow();
+    // registryDefault MUST match this gate's `default` in registry.json (true). The gate
+    // does not read the registry — this literal IS its default when a project config is
+    // silent about the key. It was false while the registry said false; both moved to true
+    // so the pending-task reminder actually fires on a fresh install, not only when the
+    // user's config names the key explicitly.
+    if (!isGateEnabled(CONFIG_KEY, true, cwd)) return allow();
 
     const root = projectRootOf(cwd);
     if (!root) return allow(); // no project: nothing to check

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

@@ -1,6 +1,6 @@
 {
   "name": "tasks",
-  "version": "0.3.0",
+  "version": "0.4.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"