@devrik-tools/claude-gates 0.7.2 → 0.8.0

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

@@ -1,28 +1,22 @@
-// 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.
+// feature-catalog — enforces the feature catalog's own invariants on a change to that
+// file: at most `maxInProgress` features in_progress, and no feature moved to `done` by a
+// direct write (only a review/QA process closes a feature).
 //
-// ── 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.
+// Decisions: the gate judges the CHANGE, not the content — the existing catalog is read
+// from disk and a feature that was already `done` stays writable; only a NEW transition to
+// done is denied. An Edit is applied to the disk content when its old_string is found, so
+// the in_progress count covers the whole file, not the fragment. A shell redirect/copy
+// onto the catalog is denied outright: its resulting content cannot be judged. An empty
+// `catalogFileName` turns the gate off.
 
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { projectRootOf, stripBom } from '../../lib/config.mjs';
 import {
   runGate,
   deny,
+  shellCommandOf,
+  shellWrittenPaths,
   toolInGroups,
   writtenContentOf,
   writtenPathOf,
@@ -34,8 +28,131 @@ const CONFIG_KEY = 'requireFeatureCatalog';
 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;
+const DONE_STATUS = 'done';
+const IN_PROGRESS_STATUS = 'in_progress';
+const STATUS_PATTERN = /["']?status["']?\s*:\s*["']?(done|in_progress)["']?/gi;
+
+function parseJsonOrNull(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function featuresOf(parsed) {
+  if (Array.isArray(parsed)) return parsed;
+  if (parsed && Array.isArray(parsed.features)) return parsed.features;
+  return null;
+}
+
+function countStatuses(text) {
+  const counts = { done: 0, inProgress: 0 };
+  for (const match of String(text).matchAll(STATUS_PATTERN)) {
+    if (match[1].toLowerCase() === DONE_STATUS) counts.done += 1;
+    else counts.inProgress += 1;
+  }
+  return counts;
+}
+
+function snapshotOf(text) {
+  const features = featuresOf(parseJsonOrNull(text));
+  if (!features) {
+    const counts = countStatuses(text);
+    return {
+      parsed: false,
+      done: null,
+      doneCount: counts.done,
+      inProgress: counts.inProgress,
+    };
+  }
+  const done = new Set();
+  let inProgress = 0;
+  features.forEach((feature, index) => {
+    const status = String(feature?.status ?? '').toLowerCase();
+    if (status === DONE_STATUS)
+      done.add(String(feature?.name ?? feature?.id ?? `#${index}`));
+    if (status === IN_PROGRESS_STATUS) inProgress += 1;
+  });
+  return { parsed: true, done, doneCount: done.size, inProgress };
+}
+
+function newlyDone(before, after) {
+  if (before.parsed && after.parsed)
+    return [...after.done].filter((name) => !before.done.has(name));
+  return after.doneCount > before.doneCount ? ['(unnamed feature)'] : [];
+}
+
+function diskContentOf(path) {
+  try {
+    return stripBom(readFileSync(path, 'utf8'));
+  } catch {
+    return '';
+  }
+}
+
+function applyEdits(diskContent, toolInput) {
+  const edits = Array.isArray(toolInput.edits) ? toolInput.edits : [toolInput];
+  let content = diskContent;
+  for (const edit of edits) {
+    const oldString = String(edit?.old_string ?? '');
+    const newString = String(edit?.new_string ?? '');
+    if (!oldString || !content.includes(oldString)) return null;
+    content = edit?.replace_all
+      ? content.replaceAll(oldString, newString)
+      : content.replace(oldString, newString);
+  }
+  return content;
+}
+
+function isEdit(toolInput) {
+  return (
+    Array.isArray(toolInput.edits) ||
+    typeof toolInput.old_string === 'string' ||
+    typeof toolInput.new_string === 'string'
+  );
+}
+
+function beforeAndAfter(toolInput, catalogPath) {
+  const diskContent = diskContentOf(catalogPath);
+  if (!isEdit(toolInput))
+    return { before: diskContent, after: writtenContentOf(toolInput) };
+  const applied = applyEdits(diskContent, toolInput);
+  if (applied !== null) return { before: diskContent, after: applied };
+  // The fragment cannot be placed in the file: judge it on its own, against nothing.
+  return { before: '', after: writtenContentOf(toolInput) };
+}
+
+function judgeChange(before, after, catalogFileName, maxInProgress) {
+  const beforeSnapshot = snapshotOf(before);
+  const afterSnapshot = snapshotOf(after);
+
+  const closed = newlyDone(beforeSnapshot, afterSnapshot);
+  if (closed.length > 0) {
+    deny(
+      CONFIG_KEY,
+      `This write moves ${closed.join(', ')} to 'status: done' in ${catalogFileName}. A feature is ` +
+        'never closed by a direct write: only a review/QA subagent or a validated automated process ' +
+        'may set done. Leave the previous status and let the review step close it.',
+    );
+  }
+
+  if (afterSnapshot.inProgress > maxInProgress) {
+    deny(
+      CONFIG_KEY,
+      `${catalogFileName} would have ${afterSnapshot.inProgress} features 'in_progress'; ` +
+        `the maximum allowed is ${maxInProgress} (maxInProgress). Finish or park one before starting another.`,
+    );
+  }
+}
+
+function denyShellWrite(catalogFileName, path) {
+  deny(
+    CONFIG_KEY,
+    `This shell command writes to the feature catalog (${path}) through a redirect/copy/move. ` +
+      `Edit ${catalogFileName} with the Write/Edit tool instead, so the status transitions can be checked.`,
+  );
+}
 
 runGate(
   {
@@ -47,37 +164,26 @@ runGate(
       maxInProgress: DEFAULT_MAX_IN_PROGRESS,
     },
   },
-  ({ toolName, toolInput, parameters }) => {
-    if (!toolInGroups(toolName, ['write'])) return;
-
-    const target = writtenPathOf(toolInput);
-    const catalogFileName = String(
-      parameters.catalogFileName ?? DEFAULT_CATALOG_FILE_NAME,
-    );
-    if (!target.includes(catalogFileName)) return;
+  ({ toolName, toolInput, parameters, cwd }) => {
+    const catalogFileName = String(parameters.catalogFileName ?? '').trim();
+    if (!catalogFileName) return;
+    const targetsCatalog = (path) => String(path).includes(catalogFileName);
 
-    const content = writtenContentOf(toolInput);
-
-    // Base, non-negotiable: `done` is never written directly to the catalog.
-    if (DONE_STATUS_PATTERN.test(content)) {
-      deny(
-        CONFIG_KEY,
-        `Writing 'status: done' directly to ${catalogFileName} is not allowed. ` +
-          'Only a review/QA subagent or a validated automated process may close a feature.',
+    if (toolInGroups(toolName, ['shell'])) {
+      const written = shellWrittenPaths(shellCommandOf(toolInput)).find(
+        targetsCatalog,
       );
+      if (written) denyShellWrite(catalogFileName, written);
+      return;
     }
 
-    const maxInProgress = Number(
-      parameters.maxInProgress ?? DEFAULT_MAX_IN_PROGRESS,
-    );
-    const inProgressCount = (content.match(IN_PROGRESS_STATUS_PATTERN) ?? [])
-      .length;
-    if (inProgressCount > maxInProgress) {
-      deny(
-        CONFIG_KEY,
-        `${catalogFileName} would have ${inProgressCount} features 'in_progress'; ` +
-          `the maximum allowed is ${maxInProgress}.`,
-      );
-    }
+    if (!toolInGroups(toolName, ['write'])) return;
+    const target = writtenPathOf(toolInput);
+    if (!targetsCatalog(target)) return;
+
+    const root = projectRootOf(cwd) ?? cwd;
+    const catalogPath = isAbsolute(target) ? target : join(root, target);
+    const { before, after } = beforeAndAfter(toolInput, catalogPath);
+    judgeChange(before, after, catalogFileName, parameters.maxInProgress);
   },
 );

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

@@ -1,134 +1,93 @@
-// force-parallel — nudges toward parallelizing independent delegations. WARN-only: it
-// never denies, because a PreToolUse hook sees one tool call at a time and has no way to
-// know whether the delegations it observed COULD have been sent together — only that they
-// arrived one after another.
+// force-parallel — warns when delegations keep arriving one turn at a time instead of as a
+// batch. Advisory only: a PreToolUse hook sees one call at a time and cannot prove the
+// delegations were independent, so it nudges the NEXT delegation and never denies.
 //
-// justification: no existing tool covers this. brief-before-delegate/intent-flow/risk-level
-// gate the CONTENT of a single delegation prompt; none of them look across delegations in
-// the same session to notice a sequential pattern.
-//
-// ── Honest limitation (read before trusting this gate) ──────────────────────────────
-// A PreToolUse hook fires once per tool call, synchronously, with no visibility into what
-// the model is "thinking" or whether independent work existed to batch. This gate can only
-// count consecutive delegation calls that land close together in wall-clock time and warn
-// after a threshold — it cannot prove they were independent, and it cannot force the model
-// to have sent them in one message (Claude Code's own turn structure decides that, not a
-// hook). Treat the warning as a nudge for the NEXT delegation, never as proof of a missed
-// opportunity on the ones already sent.
-//
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   sequentialThreshold      consecutive delegations (within the window) before warning.
-//   sequentialWindowMs       how close in time two delegations must land to count as the
-//                            same sequential run; a gap resets the count.
-//   sequentialJustifiedMarker  a marker token in the delegation prompt that escapes the
-//                            warning — a declared reason not to parallelize is a decision.
-// The defaults live here, in the source, so a project reads them and knows exactly what
-// its override replaces.
-//
-// ── State ─────────────────────────────────────────────────────────────────────────────
-// Per-session count + last-delegation timestamp, persisted at
-// os.tmpdir()/claude-gates/force-parallel/<sessionId>/state.json — process-local state
-// would not survive across the separate process each hook invocation spawns.
+// Decisions: delegations landing within BATCH_GAP_MS of each other are ONE batch (a parallel
+// launch in a single message) and do not raise the sequential count; only a gap between the
+// batch threshold and `sequentialWindowMs` counts as sequential, and a longer gap resets.
+// State lives in the shared session store (sanitized session segment, project-keyed bucket
+// when the payload has no session id, atomic writes, TTL pruning).
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
 import {
   runGate,
   warn,
   toolInGroups,
   delegationPromptOf,
 } from '../../lib/hook-io.mjs';
+import {
+  readSessionState,
+  writeSessionState,
+} from '../../lib/session-state.mjs';
 
 const GATE_ID = 'force-parallel';
 const CONFIG_KEY = 'warnSequentialDelegations';
 
-const DELEGATION_GROUPS = ['delegation'];
 const DEFAULT_SEQUENTIAL_THRESHOLD = 3;
 const DEFAULT_SEQUENTIAL_WINDOW_MS = 120000;
 const DEFAULT_JUSTIFIED_MARKER = 'SEQUENTIAL-JUSTIFIED';
 const MS_PER_SECOND = 1000;
-
-const STATE_ROOT = join(tmpdir(), 'claude-gates', 'force-parallel');
-const STATE_FILE = 'state.json';
-const UNKNOWN_SESSION = 'unknown-session';
-
-function statePathFor(sessionId) {
-  const safeSessionId = String(sessionId || UNKNOWN_SESSION).replace(
-    /[^\w-]/g,
-    '_',
-  );
-  return join(STATE_ROOT, safeSessionId, STATE_FILE);
+const BATCH_GAP_MS = 2000;
+
+const ORDINAL_SUFFIXES = { 1: 'st', 2: 'nd', 3: 'rd' };
+const TEENS_FROM = 11;
+const TEENS_TO = 13;
+const HUNDRED = 100;
+const TEN = 10;
+
+function ordinal(number) {
+  const lastTwo = number % HUNDRED;
+  if (lastTwo >= TEENS_FROM && lastTwo <= TEENS_TO) return `${number}th`;
+  return `${number}${ORDINAL_SUFFIXES[number % TEN] ?? 'th'}`;
 }
 
-function readState(path) {
-  if (!existsSync(path)) return { count: 0, lastAt: 0 };
-  try {
-    const parsed = JSON.parse(readFileSync(path, 'utf8'));
-    return {
-      count: Number(parsed.count) || 0,
-      lastAt: Number(parsed.lastAt) || 0,
-    };
-  } catch {
-    return { count: 0, lastAt: 0 };
-  }
+function nextCount(previous, now, windowMs) {
+  const gap = now - previous.lastAt;
+  if (gap > windowMs) return 1;
+  if (gap < BATCH_GAP_MS) return Math.max(previous.count, 1);
+  return previous.count + 1;
 }
 
-function writeState(path, state) {
-  mkdirSync(join(path, '..'), { recursive: true });
-  writeFileSync(path, JSON.stringify(state), 'utf8');
-}
-
-const WARN_MESSAGE =
-  'This is the {count}th delegation sent one-by-one within {windowSeconds}s. If the ' +
-  'remaining work is independent, launch the next batch together in a single message ' +
-  '(multiple tool calls) instead of one delegation per turn. If this delegation ' +
-  'genuinely depends on a prior result, ignore this and mark the prompt with ' +
-  '"{marker}" to skip the warning next time.';
-
 runGate(
   {
     id: GATE_ID,
     configKey: CONFIG_KEY,
     enabledByDefault: false,
+    severity: 'warn',
     defaultParams: {
       sequentialThreshold: DEFAULT_SEQUENTIAL_THRESHOLD,
       sequentialWindowMs: DEFAULT_SEQUENTIAL_WINDOW_MS,
       sequentialJustifiedMarker: DEFAULT_JUSTIFIED_MARKER,
     },
   },
-  ({ toolName, toolInput, sessionId, parameters }) => {
-    if (!toolInGroups(toolName, DELEGATION_GROUPS)) return;
+  ({ toolName, toolInput, sessionId, parameters, cwd }) => {
+    if (!toolInGroups(toolName, ['delegation'])) return;
 
-    const marker =
-      parameters.sequentialJustifiedMarker ?? DEFAULT_JUSTIFIED_MARKER;
+    const marker = String(parameters.sequentialJustifiedMarker ?? '');
     const prompt = delegationPromptOf(toolInput);
-    if (prompt.includes(marker)) return; // declared reason not to parallelize: no warning
+    if (marker && prompt.includes(marker)) return;
 
-    const threshold =
-      parameters.sequentialThreshold ?? DEFAULT_SEQUENTIAL_THRESHOLD;
-    const windowMs =
-      parameters.sequentialWindowMs ?? DEFAULT_SEQUENTIAL_WINDOW_MS;
-
-    const statePath = statePathFor(sessionId);
-    const state = readState(statePath);
+    const stateOptions = { cwd };
+    const stored = readSessionState(GATE_ID, sessionId, {}, stateOptions);
+    const previous = {
+      count: Number(stored.count) || 0,
+      lastAt: Number(stored.lastAt) || 0,
+    };
     const now = Date.now();
+    const count = nextCount(previous, now, parameters.sequentialWindowMs);
+    writeSessionState(GATE_ID, sessionId, { count, lastAt: now }, stateOptions);
 
-    const withinWindow = now - state.lastAt <= windowMs;
-    const nextCount = withinWindow ? state.count + 1 : 1;
-
-    writeState(statePath, { count: nextCount, lastAt: now });
-
-    if (nextCount < threshold) return;
+    if (count < parameters.sequentialThreshold) return;
 
+    const windowSeconds = Math.round(
+      parameters.sequentialWindowMs / MS_PER_SECOND,
+    );
     warn(
       CONFIG_KEY,
-      WARN_MESSAGE.replace('{count}', String(nextCount))
-        .replace(
-          '{windowSeconds}',
-          String(Math.round(windowMs / MS_PER_SECOND)),
-        )
-        .replace('{marker}', marker),
+      `This is the ${ordinal(count)} delegation sent one-by-one within ${windowSeconds}s. If the ` +
+        'remaining work is independent, launch the next batch together in a single message ' +
+        '(multiple tool calls) instead of one delegation per turn. If this delegation ' +
+        'genuinely depends on a prior result, ignore this and mark the prompt with ' +
+        `"${marker || DEFAULT_JUSTIFIED_MARKER}" to skip the warning next time.`,
     );
   },
 );

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

@@ -1,94 +1,53 @@
-// 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).
+// forge-flow — in a project that ADOPTED forge (.ai/forge.json, or `forge: true` in
+// .ai/config.json), a code-mutating action is denied unless forge has an active run for
+// this project. A forge MCP cannot intercept Edit/Write/Bash; only this hook can.
+// The run's cwd may be the project root or any ANCESTOR of it (a monorepo run covers its
+// packages); paths are compared normalized, case-insensitively on Windows.
+// The DB is read with node:sqlite (a built-in, so the plugin stays npm-free). A DB that is
+// absent means no runs → deny; a DB that cannot be read means "unknown" → warn and allow,
+// so a broken lookup never freezes work and never disables the enforcer silently.
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
+import { projectRootOf, readJsonOrNull } from '../../lib/config.mjs';
 import { runGate, deny, warn, toolInGroups } from '../../lib/hook-io.mjs';
 
 const GATE_ID = 'forge-flow';
 const CONFIG_KEY = 'requireForgeRunToEdit';
 
-// Any code-mutating surface: native write/shell AND their MCP equivalents. `execution`
-// already unions write+shell+mcp__ide__executeCode, and toolInGroups adds the mcp__* signal
-// match — so an MCP filesystem-write or shell-exec tool no longer slips past the enforcer.
 const ACTING_GROUPS = ['execution'];
-const PROJECT_ROOT_MARKERS = ['.git', '.ai'];
-const DEFAULT_FORGE_DB = join('.forge', 'forge-mcp.db');
+const DEFAULT_FORGE_DB_PATH = join(homedir(), '.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 projectAdoptedForge(root) {
+  if (existsSync(join(root, FORGE_MARKER_FILE))) return true;
+  return readJsonOrNull(join(root, PROJECT_CONFIG_FILE))?.forge === true;
 }
 
-function readJson(path) {
-  try {
-    return JSON.parse(readFileSync(path, 'utf8'));
-  } catch {
-    return null;
-  }
+function normalizeDirectory(path) {
+  let normalized = String(path ?? '').replace(/\\/g, '/');
+  while (normalized.endsWith('/')) normalized = normalized.slice(0, -1);
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
 }
 
-/** 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;
+function runCovers(runCwd, root) {
+  const run = normalizeDirectory(runCwd);
+  const project = normalizeDirectory(root);
+  return run !== '' && (project === run || project.startsWith(`${run}/`));
 }
 
-/**
- * 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.
- */
-// Returns one of three verdicts, so a broken lookup no longer masquerades as "run present":
-//   { state: 'active' }   → a run for this project exists; allow.
-//   { state: 'none' }     → DB readable, no active run for this project; deny.
-//   { state: 'unknown', reason } → DB absent/locked/corrupt/schema-drift, or node:sqlite
-//                                   missing; we cannot tell. Warn (visible) but allow, so a
-//                                   broken DB never blocks all work AND never disables the
-//                                   enforcer silently — the earlier code returned true here,
-//                                   which looked identical to "run present".
-async function forgeRunState(root, forgeDatabasePath) {
-  if (!existsSync(forgeDatabasePath)) return { state: 'none' }; // no DB yet → no runs → deny
+async function forgeRunState(root, databasePath) {
+  if (!existsSync(databasePath)) return { state: 'none' };
   try {
     const { DatabaseSync } = await import('node:sqlite');
-    const database = new DatabaseSync(forgeDatabasePath, { readOnly: true });
+    const database = new DatabaseSync(databasePath, { readOnly: true });
     const rows = database
       .prepare("SELECT cwd FROM runs WHERE status = 'active'")
       .all();
     database.close();
-    return rows.some((row) => String(row.cwd) === root)
+    return rows.some((row) => runCovers(row.cwd, root))
       ? { state: 'active' }
       : { state: 'none' };
   } catch (error) {
@@ -96,39 +55,48 @@ async function forgeRunState(root, forgeDatabasePath) {
   }
 }
 
+// The registry documents `forgeDbPath`; `forgeDatabasePath` is the name earlier configs
+// used. A declared forgeDbPath wins; otherwise whichever of the two was set applies.
+function configuredDatabasePath(parameters) {
+  const { forgeDbPath, forgeDatabasePath } = parameters;
+  if (typeof forgeDbPath === 'string' && forgeDbPath !== DEFAULT_FORGE_DB_PATH)
+    return forgeDbPath;
+  return typeof forgeDatabasePath === 'string' && forgeDatabasePath
+    ? forgeDatabasePath
+    : DEFAULT_FORGE_DB_PATH;
+}
+
 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.';
+  `you are in. To work outside the pipeline, set ${CONFIG_KEY} to false in .ai/config.json.`;
 
 runGate(
   {
     id: GATE_ID,
     configKey: CONFIG_KEY,
     enabledByDefault: false,
-    defaultParams: { forgeDatabasePath: join(homedir(), DEFAULT_FORGE_DB) },
+    defaultParams: {
+      forgeDbPath: DEFAULT_FORGE_DB_PATH,
+      forgeDatabasePath: DEFAULT_FORGE_DB_PATH,
+    },
   },
-  async ({ toolName, parameters }) => {
+  async ({ toolName, parameters, cwd }) => {
     if (!toolInGroups(toolName, ACTING_GROUPS)) 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);
-    const result = await forgeRunState(root, forgeDatabasePath);
+    const root = projectRootOf(cwd);
+    if (!root || !projectAdoptedForge(root)) return;
 
-    if (result.state === 'active') return; // pipeline is running → allow
-    if (result.state === 'none') deny(CONFIG_KEY, DENY_MESSAGE); // no run → block
-    // state 'unknown': the DB could not be read. Allow so a broken lookup never freezes work,
-    // but surface it loudly — a silent allow here would disable the enforcer without a trace.
+    const databasePath = configuredDatabasePath(parameters);
+    const result = await forgeRunState(root, databasePath);
+    if (result.state === 'active') return;
+    if (result.state === 'none') deny(CONFIG_KEY, DENY_MESSAGE);
     warn(
       CONFIG_KEY,
       `forge enforcement is degraded: the forge DB could not be read (${result.reason}). ` +
         'Allowing this action, but the pipeline is NOT being enforced. Check that forge is ' +
-        `installed and ${forgeDatabasePath} is readable, or turn this gate off if intended.`,
+        `installed and ${databasePath} is readable, or turn this gate off if intended.`,
     );
   },
 );