@devrik-tools/claude-gates 0.3.1 → 0.6.0

package/cli/smoke-fixtures.json

@@ -0,0 +1,441 @@
+{
+  "_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
+    },
+    {
+      "id": "no-coauthor",
+      "configKey": "blockCoauthorTrailers",
+      "enabledByDefault": true,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Bash",
+        "tool_input": {
+          "command": "git commit -m \"fix\n\nCo-Authored-By: Claude <noreply@anthropic.com>\""
+        }
+      },
+      "needsState": false
+    },
+    {
+      "id": "no-lint-suppression",
+      "configKey": "blockLintSuppression",
+      "enabledByDefault": true,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Write",
+        "tool_input": {
+          "file_path": "/repo/a.js",
+          "content": "const x = 1; // eslint-disable-next-line no-unused-vars"
+        }
+      },
+      "needsState": false
+    },
+    {
+      "id": "staged-lint",
+      "configKey": "blockCommitWithStagedLintErrors",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Bash",
+        "tool_input": { "command": "git commit -m \"wip\"" }
+      },
+      "needsState": true,
+      "note": "needs a git repo with a staged lintable file that fails lint and a resolvable linter; a bare payload cannot reproduce the staged-file scan."
+    },
+    {
+      "id": "atomic-commit",
+      "configKey": "blockNonAtomicCommits",
+      "enabledByDefault": false,
+      "type": "deny",
+      "payload": {
+        "tool_name": "Bash",
+        "tool_input": { "command": "git commit -m \"stuff\"" }
+      },
+      "needsState": true,
+      "note": "needs a git repo with a staged set that mixes >maxNatures natures or exceeds maxFiles; a bare payload cannot reproduce the staged-file scan."
+    }
+  ]
+}

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 };
+}