@devrik-tools/claude-gates 0.1.0

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

@@ -0,0 +1,118 @@
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { runGate, warn, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'dependency-skills';
+const CONFIG_KEY = 'requireSkillForNewDependency';
+
+const DEFAULT_DEPS_WITHOUT_OWN_API = [
+  'clsx',
+  'classnames',
+  'lodash.debounce',
+  'lodash.throttle',
+  'lodash.merge',
+  'tslib',
+  'core-js',
+  'regenerator-runtime',
+];
+
+function normalize(name) {
+  return name.replace(/^@/, '').replace(/\//g, '-').toLowerCase();
+}
+
+function isExempt(dependencyName, dependenciesWithoutOwnApi) {
+  if (dependencyName.startsWith('@types/')) return true;
+  return dependenciesWithoutOwnApi.includes(dependencyName);
+}
+
+function listSkillDirectories(skillsDirectoryPath) {
+  try {
+    return readdirSync(skillsDirectoryPath, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name);
+  } catch {
+    // No skills directory in this project — nothing to cross-check against.
+    return [];
+  }
+}
+
+function skillNameMatches(normalizedDependency, skillDirectoryName) {
+  const normalizedSkill = normalize(skillDirectoryName);
+  return (
+    normalizedDependency.includes(normalizedSkill) ||
+    normalizedSkill.includes(normalizedDependency)
+  );
+}
+
+function hasMatchingSkill(dependencyName, skillDirectories) {
+  const normalizedDependency = normalize(dependencyName);
+  return skillDirectories.some((skillDirectoryName) =>
+    skillNameMatches(normalizedDependency, skillDirectoryName),
+  );
+}
+
+function needsSkillReview(dependencyName, parameters, skillDirectories) {
+  if (isExempt(dependencyName, parameters.depsWithoutOwnApi)) return false;
+  return !hasMatchingSkill(dependencyName, skillDirectories);
+}
+
+/** Parsed `package.json` dependency names, or null when it cannot be read yet. */
+function dependencyNamesIn(content) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    // Mid-edit or partially written package.json — nothing reliable to check yet.
+    return null;
+  }
+  const dependencies = {
+    ...(parsed.dependencies ?? {}),
+    ...(parsed.devDependencies ?? {}),
+  };
+  return Object.keys(dependencies);
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      depsWithoutOwnApi: DEFAULT_DEPS_WITHOUT_OWN_API,
+      projectSkillsDir: '.claude/skills',
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    if (!TOOL_GROUPS.write.includes(toolName)) return;
+
+    const filePath = toolInput?.file_path ?? '';
+    if (!filePath.replace(/\\/g, '/').endsWith('package.json')) return;
+
+    const content = toolInput?.content ?? toolInput?.new_string;
+    if (typeof content !== 'string') return;
+
+    const dependencyNames = dependencyNamesIn(content);
+    if (!dependencyNames || dependencyNames.length === 0) return;
+
+    const skillDirectories = listSkillDirectories(
+      join(process.cwd(), parameters.projectSkillsDir),
+    );
+
+    const unmatched = dependencyNames.filter((name) =>
+      needsSkillReview(name, parameters, skillDirectories),
+    );
+    if (unmatched.length === 0) return;
+
+    warn(
+      GATE_ID,
+      `New dependencies without a matching skill in ${parameters.projectSkillsDir}: ${unmatched.join(', ')}. Consider adding a skill documenting how to use them, or add them to depsWithoutOwnApi if they need none.`,
+    );
+  },
+);
+
+// Deliberately simplified vs. the source guard (guard-dependencies-skills.mjs):
+// dropped the hardcoded alias table (stripe -> stripe-payments, etc.) and the
+// .ai/skills-baseline.json freeze mechanism — that belongs to a separate
+// adopt-stack-and-skills.mjs script that does not exist in this repo. This
+// gate only does simple substring matching between dependency name and skill
+// directory name, both normalized.

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

@@ -0,0 +1,109 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const GATE = join(dirname(fileURLToPath(import.meta.url)), 'index.mjs');
+
+function runGate(payload, { config, skills } = {}) {
+  const project = mkdtempSync(join(tmpdir(), 'dependency-skills-'));
+  mkdirSync(join(project, '.git'));
+  if (config) {
+    mkdirSync(join(project, '.ai'));
+    writeFileSync(join(project, '.ai', 'config.json'), JSON.stringify(config));
+  }
+  if (skills) {
+    for (const name of skills) {
+      mkdirSync(join(project, '.claude', 'skills', name), { recursive: true });
+    }
+  }
+  const out = execFileSync(process.execPath, [GATE], {
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    cwd: project,
+    // Isolate from the user's real global config: point homedir() at the temp
+    // project so the global-config fallback finds nothing (registry default).
+    env: { ...process.env, HOME: project, USERPROFILE: project },
+  });
+  return out.trim() ? JSON.parse(out.trim()) : null;
+}
+
+function writePackageJson(content) {
+  return {
+    tool_name: 'Write',
+    tool_input: { file_path: '/repo/package.json', content },
+  };
+}
+function isWarn(result) {
+  return result?.hookSpecificOutput?.additionalContext !== undefined;
+}
+
+test('warns when a new dependency has no matching skill', () => {
+  const package_ = JSON.stringify({ dependencies: { stripe: '1.0.0' } });
+  assert.ok(isWarn(runGate(writePackageJson(package_))));
+});
+
+test('allows when the dependency has a matching skill directory', () => {
+  const package_ = JSON.stringify({ dependencies: { stripe: '1.0.0' } });
+  assert.equal(
+    runGate(writePackageJson(package_), { skills: ['stripe'] }),
+    null,
+  );
+});
+
+test('allows an exempt dependency without its own API', () => {
+  const package_ = JSON.stringify({
+    dependencies: { clsx: '1.0.0', '@types/node': '1.0.0' },
+  });
+  assert.equal(runGate(writePackageJson(package_)), null);
+});
+
+test('allows a non-package.json write and unparseable content', () => {
+  assert.equal(
+    runGate({
+      tool_name: 'Write',
+      tool_input: { file_path: '/repo/src/index.js', content: 'x' },
+    }),
+    null,
+  );
+  assert.equal(
+    runGate(writePackageJson('{ "dependencies": { incomplete')),
+    null,
+  );
+});
+
+test('disabled by config: the gate does not run', () => {
+  const package_ = JSON.stringify({ dependencies: { stripe: '1.0.0' } });
+  assert.equal(
+    runGate(writePackageJson(package_), {
+      config: { gates: { requireSkillForNewDependency: false } },
+    }),
+    null,
+  );
+});
+
+test('project projectSkillsDir override is honored', () => {
+  const package_ = JSON.stringify({ dependencies: { stripe: '1.0.0' } });
+  const config = {
+    gates: {
+      requireSkillForNewDependency: {
+        enabled: true,
+        projectSkillsDir: 'custom-skills',
+      },
+    },
+  };
+  const project = mkdtempSync(join(tmpdir(), 'dependency-skills-'));
+  mkdirSync(join(project, '.git'));
+  mkdirSync(join(project, '.ai'));
+  writeFileSync(join(project, '.ai', 'config.json'), JSON.stringify(config));
+  mkdirSync(join(project, 'custom-skills', 'stripe'), { recursive: true });
+  const out = execFileSync(process.execPath, [GATE], {
+    input: JSON.stringify(writePackageJson(package_)),
+    encoding: 'utf8',
+    cwd: project,
+  });
+  assert.equal(out.trim() ? JSON.parse(out.trim()) : null, null);
+});

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

@@ -0,0 +1,49 @@
+import { runGate, warn } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'diagnosis-before-patch';
+const CONFIG_KEY = 'warnTimeoutChangeWithoutDiagnosis';
+
+const DEFAULT_TIMEOUT_PATTERNS = [
+  String.raw`\b[A-Z_]*TIMEOUT[A-Z_]*\s*[:=]\s*['"]?\d`,
+  String.raw`\b[A-Z_]*DEADLINE[A-Z_]*\s*[:=]\s*['"]?\d`,
+  String.raw`\b[A-Z_]*IDLE[A-Z_]*\s*[:=]\s*['"]?\d`,
+  String.raw`\b(max_?retry|retries|backoff)\b\s*[:=]\s*['"]?\d`,
+  String.raw`\b(query_?timeout|hard_?deadline)\b`,
+];
+
+function extractText(toolName, toolInput) {
+  if (toolName === 'Write') return String(toolInput?.content ?? '');
+  if (toolName === 'Edit') return String(toolInput?.new_string ?? '');
+  if (toolName === 'MultiEdit' && Array.isArray(toolInput?.edits)) {
+    return toolInput.edits
+      .map((edit) => String(edit?.new_string ?? ''))
+      .join('\n');
+  }
+  return '';
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      timeoutPatterns: DEFAULT_TIMEOUT_PATTERNS,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    const text = extractText(toolName, toolInput);
+    if (!text) return;
+
+    const patterns = parameters.timeoutPatterns.map(
+      (source) => new RegExp(source, 'i'),
+    );
+    const touchesTimeout = patterns.some((pattern) => pattern.test(text));
+    if (!touchesTimeout) return;
+
+    warn(
+      GATE_ID,
+      '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/diagnosis-before-patch/test.mjs

@@ -0,0 +1,68 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const GATE = join(dirname(fileURLToPath(import.meta.url)), 'index.mjs');
+
+function runGate(payload, { config } = {}) {
+  const project = mkdtempSync(join(tmpdir(), 'diagnosis-before-patch-'));
+  mkdirSync(join(project, '.git'));
+  if (config) {
+    mkdirSync(join(project, '.ai'));
+    writeFileSync(join(project, '.ai', 'config.json'), JSON.stringify(config));
+  }
+  const out = execFileSync(process.execPath, [GATE], {
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    cwd: project,
+    // Isolate from the user's real global config: point homedir() at the temp
+    // project so the global-config fallback finds nothing (registry default).
+    env: { ...process.env, HOME: project, USERPROFILE: project },
+  });
+  return out.trim() ? JSON.parse(out.trim()) : null;
+}
+
+function write(content) {
+  return {
+    tool_name: 'Write',
+    tool_input: { file_path: '/repo/src/config.js', content },
+  };
+}
+function isWarn(result) {
+  return result?.hookSpecificOutput?.additionalContext !== undefined;
+}
+
+test('warns when a timeout value is being changed', () => {
+  assert.ok(isWarn(runGate(write('const REQUEST_TIMEOUT_MS = 30000;'))));
+  assert.ok(isWarn(runGate(write('max_retry: 5'))));
+});
+
+test('allows content that does not touch a timeout/retry key', () => {
+  assert.equal(runGate(write('const x = 1;')), null);
+});
+
+test('disabled by config: the gate does not run', () => {
+  assert.equal(
+    runGate(write('TIMEOUT_MS = 5000'), {
+      config: { gates: { warnTimeoutChangeWithoutDiagnosis: false } },
+    }),
+    null,
+  );
+});
+
+test('project timeoutPatterns override replaces the built-in list', () => {
+  const config = {
+    gates: {
+      warnTimeoutChangeWithoutDiagnosis: {
+        enabled: true,
+        timeoutPatterns: ['custom_limit'],
+      },
+    },
+  };
+  assert.equal(runGate(write('TIMEOUT_MS = 5000'), { config }), null);
+  assert.ok(isWarn(runGate(write('custom_limit = 5'), { config })));
+});

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

@@ -0,0 +1,100 @@
+// feature-catalog — enforces the machine-readable feature catalog's own invariants on
+// a write to that file: at most one feature `in_progress` at a time, and `done` is
+// never written directly (only a review/QA process closes a feature). Migrated from
+// ~/.claude/hooks/guard-feature-catalog.mjs.
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   catalogFileName   basename of the catalog file this gate watches for (default
+//                      feature_list.json). A write to any other file is ignored.
+//   maxInProgress     how many features may be `in_progress` simultaneously.
+// The defaults live here, in the source, so a project reads them and knows exactly what
+// its override replaces.
+//
+// ── Auto-off when the project never adopted the catalog ────────────────────────────
+// This gate only inspects the CONTENT being written to a file named `catalogFileName`.
+// A project that never uses that file never triggers it — there is nothing to disable
+// separately, the check is inert by construction rather than by a discovery pass.
+//
+// ── What is NOT configurable (base, non-negotiable) ─────────────────────────────────
+// Writing `status: done` directly is always denied, regardless of `maxInProgress`: only
+// a review/QA subagent or a validated automated process may close a feature, and this
+// gate has no way to tell who is writing, so it blocks the write itself.
+
+import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'feature-catalog';
+const CONFIG_KEY = 'requireFeatureCatalog';
+
+const WRITE_TOOLS = new Set(TOOL_GROUPS.write);
+
+const DEFAULT_CATALOG_FILE_NAME = 'feature_list.json';
+const DEFAULT_MAX_IN_PROGRESS = 1;
+
+const DONE_STATUS_PATTERN = /"status"\s*:\s*"done"|status\s*:\s*['"]done['"]/i;
+const IN_PROGRESS_STATUS_PATTERN = /"status"\s*:\s*"in_progress"/g;
+
+/** The path a write tool targets, across the field names different tools use. */
+function writeTargetFrom(toolInput) {
+  return String(
+    toolInput.TargetFile ??
+      toolInput.target_file ??
+      toolInput.file_path ??
+      toolInput.path ??
+      '',
+  );
+}
+
+/** The content a write tool is about to write, across the field names tools use. */
+function writeContentFrom(toolInput) {
+  return String(
+    toolInput.CodeContent ??
+      toolInput.ReplacementContent ??
+      toolInput.content ??
+      '',
+  );
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      catalogFileName: DEFAULT_CATALOG_FILE_NAME,
+      maxInProgress: DEFAULT_MAX_IN_PROGRESS,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    if (!WRITE_TOOLS.has(toolName)) return;
+
+    const target = writeTargetFrom(toolInput);
+    const catalogFileName = String(
+      parameters.catalogFileName ?? DEFAULT_CATALOG_FILE_NAME,
+    );
+    if (!target.includes(catalogFileName)) return;
+
+    const content = writeContentFrom(toolInput);
+
+    // Base, non-negotiable: `done` is never written directly to the catalog.
+    if (DONE_STATUS_PATTERN.test(content)) {
+      deny(
+        GATE_ID,
+        `Writing 'status: done' directly to ${catalogFileName} is not allowed. ` +
+          'Only a review/QA subagent or a validated automated process may close a feature.',
+      );
+    }
+
+    const maxInProgress = Number(
+      parameters.maxInProgress ?? DEFAULT_MAX_IN_PROGRESS,
+    );
+    const inProgressCount = (content.match(IN_PROGRESS_STATUS_PATTERN) ?? [])
+      .length;
+    if (inProgressCount > maxInProgress) {
+      deny(
+        GATE_ID,
+        `${catalogFileName} would have ${inProgressCount} features 'in_progress'; ` +
+          `the maximum allowed is ${maxInProgress}.`,
+      );
+    }
+  },
+);

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

@@ -0,0 +1,97 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const GATE = join(dirname(fileURLToPath(import.meta.url)), 'index.mjs');
+
+function runGate(payload, { config } = {}) {
+  const project = mkdtempSync(join(tmpdir(), 'feature-catalog-'));
+  mkdirSync(join(project, '.git'));
+  if (config) {
+    mkdirSync(join(project, '.ai'));
+    writeFileSync(join(project, '.ai', 'config.json'), JSON.stringify(config));
+  }
+  const out = execFileSync(process.execPath, [GATE], {
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    cwd: project,
+    // Isolate from the user's real global config: point homedir() at the temp
+    // project so the global-config fallback finds nothing (registry default).
+    env: { ...process.env, HOME: project, USERPROFILE: project },
+  });
+  return out.trim() ? JSON.parse(out.trim()) : null;
+}
+
+function writeCatalog(content, targetFile = 'feature_list.json') {
+  return {
+    tool_name: 'Write',
+    tool_input: { file_path: targetFile, content },
+  };
+}
+
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+test('denies writing status:done directly to the catalog', () => {
+  const content = JSON.stringify({
+    features: [{ name: 'checkout', status: 'done' }],
+  });
+  assert.ok(isDeny(runGate(writeCatalog(content))));
+});
+
+test('denies more than maxInProgress features in_progress', () => {
+  const content = JSON.stringify({
+    features: [
+      { name: 'a', status: 'in_progress' },
+      { name: 'b', status: 'in_progress' },
+    ],
+  });
+  assert.ok(isDeny(runGate(writeCatalog(content))));
+});
+
+test('allows a write with one in_progress feature and no direct done', () => {
+  const content = JSON.stringify({
+    features: [
+      { name: 'a', status: 'in_progress' },
+      { name: 'b', status: 'spec_ready' },
+    ],
+  });
+  assert.equal(runGate(writeCatalog(content)), null);
+});
+
+test('allows a write to an unrelated file (auto-off: no catalog targeted)', () => {
+  const content = JSON.stringify({ status: 'done' });
+  assert.equal(runGate(writeCatalog(content, 'notes.json')), null);
+});
+
+test('disabled by config: the gate does not run', () => {
+  const content = JSON.stringify({
+    features: [{ name: 'checkout', status: 'done' }],
+  });
+  assert.equal(
+    runGate(writeCatalog(content), {
+      config: { gates: { requireFeatureCatalog: false } },
+    }),
+    null,
+  );
+});
+
+test('project param maxInProgress override raises/lowers the threshold', () => {
+  const content = JSON.stringify({
+    features: [
+      { name: 'a', status: 'in_progress' },
+      { name: 'b', status: 'in_progress' },
+    ],
+  });
+  const config = {
+    gates: {
+      requireFeatureCatalog: { enabled: true, maxInProgress: 2 },
+    },
+  };
+  assert.equal(runGate(writeCatalog(content), { config }), null);
+});

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

@@ -0,0 +1,112 @@
+// forge-flow — the enforcer forge cannot be. A forge MCP directs a pipeline but cannot
+// intercept Edit/Write/Bash, so nothing makes you actually use it. This gate closes that
+// hole: in a project that ADOPTED forge, a code-mutating action is denied unless there is
+// an active forge run for this project — so every change goes through the pipeline and you
+// always know which phase you are in.
+//
+// justification: no existing tool covers this. A forge MCP audit (see memory
+// forge-mcp-auditoria-flujo) confirmed the structural hole: an MCP cannot gate other tools;
+// only a Claude Code PreToolUse hook can. This is that hook.
+//
+// ── When it acts (never surprises you) ──────────────────────────────────────────────
+// Only when the project adopted forge — a marker on disk (.ai/forge.json, or `forge: true`
+// in .ai/config.json). In any other project it stays silent. Off by default in the
+// registry, so it never fires unless a project turns it on.
+//
+// ── How it checks (deterministic, no judgment) ──────────────────────────────────────
+// forge persists its runs in a SQLite DB (global by default). This gate reads that DB with
+// node:sqlite (a Node built-in — no npm, contract intact) and looks for an active run whose
+// cwd matches this project. Absent → deny with an actionable message. The DB unreadable or
+// node:sqlite unavailable → allow (fail open: a broken lookup must not block all work).
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'forge-flow';
+const CONFIG_KEY = 'requireForgeRunToEdit';
+
+const ACTING_TOOLS = new Set([...TOOL_GROUPS.write, ...TOOL_GROUPS.shell]);
+const PROJECT_ROOT_MARKERS = ['.git', '.ai'];
+const DEFAULT_FORGE_DB = join('.forge', 'forge-mcp.db');
+const FORGE_MARKER_FILE = join('.ai', 'forge.json');
+const PROJECT_CONFIG_FILE = join('.ai', 'config.json');
+
+function projectRootOf(startDirectory) {
+  let current = startDirectory;
+  while (true) {
+    if (
+      PROJECT_ROOT_MARKERS.some((marker) => existsSync(join(current, marker)))
+    ) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** True when this project opted into forge: a marker file, or forge:true in .ai/config.json. */
+function projectAdoptedForge(root) {
+  if (existsSync(join(root, FORGE_MARKER_FILE))) return true;
+  const config = readJson(join(root, PROJECT_CONFIG_FILE));
+  return config?.forge === true;
+}
+
+/**
+ * True when forge has an active run whose cwd is this project. Reads forge's SQLite DB with
+ * node:sqlite (imported dynamically so an older Node without it degrades instead of
+ * throwing). Any failure — module missing, DB absent, locked, unreadable, schema drift —
+ * returns true: the gate must fail OPEN, since a broken lookup must never block every edit.
+ */
+async function hasActiveForgeRun(root, forgeDatabasePath) {
+  if (!existsSync(forgeDatabasePath)) return false; // no DB yet → no runs at all → deny
+  try {
+    const { DatabaseSync } = await import('node:sqlite');
+    const database = new DatabaseSync(forgeDatabasePath, { readOnly: true });
+    const rows = database
+      .prepare("SELECT cwd FROM runs WHERE status = 'active'")
+      .all();
+    database.close();
+    return rows.some((row) => String(row.cwd) === root);
+  } catch {
+    return true; // node:sqlite missing, or DB locked/unreadable → fail open
+  }
+}
+
+const DENY_MESSAGE =
+  'This project uses forge, but there is no active forge run for it. Every change should ' +
+  'go through the pipeline so the next step is always clear. Start or resume a run ' +
+  '(forge_start / forge_next) before editing — that is how forge tells you which phase ' +
+  'you are in. To work outside the pipeline, turn this gate off in .ai/config.json.';
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: { forgeDatabasePath: join(homedir(), DEFAULT_FORGE_DB) },
+  },
+  async ({ toolName, parameters }) => {
+    if (!ACTING_TOOLS.has(toolName)) return;
+
+    const root = projectRootOf(process.cwd());
+    if (!root) return; // no project
+    if (!projectAdoptedForge(root)) return; // project did not opt into forge
+
+    const forgeDatabasePath =
+      parameters.forgeDatabasePath ?? join(homedir(), DEFAULT_FORGE_DB);
+    if (await hasActiveForgeRun(root, forgeDatabasePath)) return;
+
+    deny(GATE_ID, DENY_MESSAGE);
+  },
+);