@devrik-tools/claude-gates 0.7.2 → 0.9.0

package/plugins/gates/hooks/gates/engram-first/session-start.mjs

@@ -0,0 +1,64 @@
+import { gateParameters, isGateEnabled } from '../../lib/config.mjs';
+import { coerceParameters, readHookPayload } from '../../lib/hook-io.mjs';
+import { CONFIG_KEY, DEFAULT_PARAMS } from './shared.mjs';
+
+const PROBE_TIMEOUT_MS = 1500;
+const SESSION_START_EVENT = 'SessionStart';
+const NOT_ENROLLED = 'non_enrolled_pending_mutations';
+
+async function getJson(url) {
+  const response = await fetch(url, {
+    signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+  });
+  if (!response.ok) return null;
+  return response.json();
+}
+
+function withoutTrailingSlash(text) {
+  let end = text.length;
+  while (end > 0 && text[end - 1] === '/') end -= 1;
+  return text.slice(0, end);
+}
+
+function speak(context) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: SESSION_START_EVENT,
+        additionalContext: context,
+      },
+    }),
+  );
+}
+
+function enrollmentProblem(status, projectName) {
+  if (!status || status.reason_code !== NOT_ENROLLED) return null;
+  const message = String(status.reason_message ?? '');
+  if (projectName && !message.includes(`${projectName}=`)) return null;
+  return projectName ?? 'this project';
+}
+
+async function main() {
+  const cwd = process.cwd();
+  if (!isGateEnabled(CONFIG_KEY, true, cwd)) return;
+  const { parameters } = coerceParameters(
+    DEFAULT_PARAMS,
+    gateParameters(CONFIG_KEY, cwd),
+  );
+  const base = withoutTrailingSlash(String(parameters.engramUrl));
+  const status = await getJson(`${base}/sync/status`);
+  if (!status) return;
+  const current = await getJson(
+    `${base}/project/current?cwd=${encodeURIComponent(cwd)}`,
+  );
+  const project = enrollmentProblem(status, current?.project);
+  if (!project) return;
+  speak(
+    `[${CONFIG_KEY}] Engram cloud is configured but "${project}" is not enrolled, so its memories stay ` +
+      `local only (daemon reports ${status.reason_code}). Run \`engram cloud enroll ${project}\` once ` +
+      'to replicate them; local SQLite remains the source of truth either way.',
+  );
+}
+
+readHookPayload();
+main().catch(() => {});

package/plugins/gates/hooks/gates/engram-first/shared.mjs

@@ -0,0 +1,90 @@
+import {
+  mcpActionSegment,
+  mcpServerSegment,
+  toolInGroups,
+} from '../../lib/hook-io.mjs';
+import {
+  readSessionState,
+  writeSessionState,
+} from '../../lib/session-state.mjs';
+
+export const GATE_ID = 'engram-first';
+export const CONFIG_KEY = 'requireEngramBeforeResearch';
+
+export const DEFAULT_PARAMS = Object.freeze({
+  engramServers: ['engram', 'plugin_engram_engram'],
+  context7Servers: ['context7', 'plugin_context7_context7'],
+  researchTools: ['WebSearch', 'WebFetch'],
+  engramUrl: 'http://127.0.0.1:7437',
+  requireSaveBeforeStop: true,
+});
+
+const MAX_RECORDED_QUERIES = 30;
+const MAX_QUERY_LENGTH = 200;
+
+export const EMPTY_STATE = Object.freeze({
+  memSearchCount: 0,
+  memSearchHits: 0,
+  memSearchQueries: [],
+  memSaveCount: 0,
+  researchCalls: 0,
+  lastResearchAt: 0,
+  lastMemSaveAt: 0,
+});
+
+function serverMatches(toolName, servers) {
+  const server = mcpServerSegment(String(toolName ?? '')).toLowerCase();
+  return servers.some((name) => String(name).toLowerCase() === server);
+}
+
+export function isEngramTool(toolName, parameters) {
+  return serverMatches(toolName, parameters.engramServers);
+}
+
+export function isContext7Tool(toolName, parameters) {
+  return serverMatches(toolName, parameters.context7Servers);
+}
+
+export function isResearchTool(toolName, parameters) {
+  if (isEngramTool(toolName, parameters)) return false;
+  const lowered = String(toolName ?? '').toLowerCase();
+  if (parameters.researchTools.some((name) => name.toLowerCase() === lowered))
+    return true;
+  if (isContext7Tool(toolName, parameters)) return true;
+  return toolInGroups(toolName, ['research']);
+}
+
+export function engramActionOf(toolName) {
+  return mcpActionSegment(String(toolName ?? '')).toLowerCase();
+}
+
+export function readState(sessionId, cwd) {
+  return {
+    ...EMPTY_STATE,
+    ...readSessionState(GATE_ID, sessionId, {}, { cwd }),
+  };
+}
+
+export function writeState(sessionId, state, cwd) {
+  return writeSessionState(GATE_ID, sessionId, state, { cwd });
+}
+
+export function rememberQuery(state, query) {
+  const queries = [
+    ...state.memSearchQueries,
+    String(query ?? '').slice(0, MAX_QUERY_LENGTH),
+  ];
+  return queries.slice(-MAX_RECORDED_QUERIES);
+}
+
+export function queryOf(toolInput) {
+  if (!toolInput || typeof toolInput !== 'object') return '';
+  return String(
+    toolInput.query ??
+      toolInput.title ??
+      toolInput.libraryName ??
+      toolInput.prompt ??
+      toolInput.url ??
+      '',
+  );
+}

package/plugins/gates/hooks/gates/engram-first/stop.mjs

@@ -0,0 +1,23 @@
+import { block, runStopHook } from '../../lib/hook-io.mjs';
+import { CONFIG_KEY, DEFAULT_PARAMS, GATE_ID, readState } from './shared.mjs';
+
+runStopHook(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: { ...DEFAULT_PARAMS },
+  },
+  ({ sessionId, parameters, cwd }) => {
+    if (!parameters.requireSaveBeforeStop) return;
+    const state = readState(sessionId, cwd);
+    if (state.researchCalls === 0) return;
+    if (state.lastMemSaveAt >= state.lastResearchAt) return;
+    block(
+      CONFIG_KEY,
+      `This session made ${state.researchCalls} research call(s) (web/context7) and nothing was saved to ` +
+        'engram afterwards. Call mem_save with what the research established (What/Why/Where/Learned, ' +
+        'or mem_session_summary if it was broad), then end the turn. Research that is not saved is repeated next session.',
+    );
+  },
+);

package/plugins/gates/hooks/gates/engram-first/track.mjs

@@ -0,0 +1,97 @@
+import { gateParameters, isGateEnabled } from '../../lib/config.mjs';
+import {
+  allow,
+  coerceParameters,
+  readHookPayload,
+  sessionIdOf,
+  toolInputOf,
+  toolNameOf,
+  toolResponseOf,
+} from '../../lib/hook-io.mjs';
+import {
+  CONFIG_KEY,
+  DEFAULT_PARAMS,
+  engramActionOf,
+  isEngramTool,
+  isResearchTool,
+  queryOf,
+  readState,
+  rememberQuery,
+  writeState,
+} from './shared.mjs';
+
+const SAVE_ACTIONS = new Set(['mem_save', 'mem_session_summary', 'mem_update']);
+const NO_RESULT_PATTERN = /no memories found|no results|0 results/i;
+
+function responseText(toolResponse) {
+  if (typeof toolResponse === 'string') return toolResponse;
+  try {
+    return JSON.stringify(toolResponse ?? '');
+  } catch {
+    return '';
+  }
+}
+
+function searchHit(toolResponse) {
+  const text = responseText(toolResponse);
+  return text.length > 0 && !NO_RESULT_PATTERN.test(text);
+}
+
+function nextState(state, { toolName, toolInput, toolResponse, parameters }) {
+  const now = Date.now();
+  if (isEngramTool(toolName, parameters)) {
+    const action = engramActionOf(toolName);
+    if (action === 'mem_search') {
+      return {
+        ...state,
+        memSearchCount: state.memSearchCount + 1,
+        memSearchHits: state.memSearchHits + (searchHit(toolResponse) ? 1 : 0),
+        memSearchQueries: rememberQuery(state, queryOf(toolInput)),
+      };
+    }
+    if (SAVE_ACTIONS.has(action)) {
+      return {
+        ...state,
+        memSaveCount: state.memSaveCount + 1,
+        lastMemSaveAt: now,
+      };
+    }
+    return state;
+  }
+  if (isResearchTool(toolName, parameters)) {
+    return {
+      ...state,
+      researchCalls: state.researchCalls + 1,
+      lastResearchAt: now,
+    };
+  }
+  return state;
+}
+
+function main() {
+  const rawPayload = readHookPayload();
+  if (rawPayload === null) allow();
+  const cwd = process.cwd();
+  if (!isGateEnabled(CONFIG_KEY, true, cwd)) allow();
+  const { parameters } = coerceParameters(
+    DEFAULT_PARAMS,
+    gateParameters(CONFIG_KEY, cwd),
+  );
+  const sessionId = sessionIdOf(rawPayload);
+  const context = {
+    toolName: toolNameOf(rawPayload) ?? '',
+    toolInput: toolInputOf(rawPayload),
+    toolResponse: toolResponseOf(rawPayload),
+    parameters,
+  };
+  const state = readState(sessionId, cwd);
+  const updated = nextState(state, context);
+  if (updated !== state) writeState(sessionId, updated, cwd);
+  allow();
+}
+
+try {
+  main();
+} catch {
+  allow();
+}

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);
   },
 );