@devrik-tools/claude-gates 0.1.0

package/plugins/gates/hooks/gates/sdd-specs/index.mjs

@@ -0,0 +1,251 @@
+// sdd-specs — denies implementation (a write to the catalog moving a feature past
+// `spec_ready`, or a delegation prompt that implements) when the feature/task it targets
+// has no non-empty contract on disk (requirements/design/tasks or brief/asserts).
+// Migrated from ~/.claude/hooks/guard-sdd-specs.mjs.
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   catalogLocations   paths (relative to the project root) searched for the feature
+//                       catalog. Replaces the built-in list wholesale.
+//   exemptSubagents     subagent types exempt from the spec requirement (read-only
+//                       stages of the pipeline that cannot require a contract of
+//                       themselves). Replaces the built-in list wholesale.
+// The defaults live here, in the source, so a project reads them and knows exactly what
+// its override replaces.
+//
+// ── Auto-off when there is no SDD harness ───────────────────────────────────────────
+// This gate only acts once a catalog is found at one of `catalogLocations` (or the
+// project's own `.ai/config.json` declares adoption). A project that never adopted the
+// spec-driven harness has no catalog and no declared adoption, so every check below is
+// skipped and the write/delegation is allowed — imposing phases on a project that never
+// asked for them is the false positive that gets a gate disabled.
+//
+// ── Two surfaces inspected ───────────────────────────────────────────────────────────
+// A write to the catalog is checked against the catalog's own declared statuses: a
+// feature marked `spec_ready`/`in_progress`/`done` needs its contract tree in place. A
+// delegation prompt is checked when it declares a STANDARD/HIGH-RISK level and an
+// implementation verb: the contract tree must have non-empty requirements/design/tasks
+// (or brief/asserts) for the feature it targets.
+
+import { existsSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'sdd-specs';
+const CONFIG_KEY = 'requireSpecBeforeImplementing';
+
+const WRITE_TOOLS = new Set(TOOL_GROUPS.write);
+const DELEGATION_TOOLS = new Set(TOOL_GROUPS.delegation);
+
+const CATALOG_FILE_NAME = 'feature_list.json';
+
+const DEFAULT_CATALOG_LOCATIONS = [
+  join('.ai', CATALOG_FILE_NAME),
+  CATALOG_FILE_NAME,
+];
+
+const DEFAULT_EXEMPT_SUBAGENTS = [
+  'explore',
+  'plan',
+  'scout',
+  'revision',
+  'contraste',
+  'test-planner',
+  'qa',
+  'ui',
+  'ux',
+];
+
+const ADVANCED_STATUSES = new Set(['spec_ready', 'in_progress', 'done']);
+
+/** Files that count as a feature's contract; at least one must be non-empty. */
+const CONTRACT_FILES = [
+  'requirements.md',
+  'design.md',
+  'tasks.md',
+  'brief.md',
+  'asserts.md',
+];
+
+function withWordBoundary(alternation) {
+  return new RegExp(
+    `(?<![\\p{L}\\p{N}_])(${alternation})(?![\\p{L}\\p{N}_])`,
+    'iu',
+  );
+}
+
+const IMPLEMENTATION_VERBS = withWordBoundary(
+  'implementa|implementar|implement(á|é)|agreg(a|á)|agregar|añad(e|í)|añadir|cre(a|á)|crear|' +
+    'arregl(a|á)|arreglar|cambi(a|á)|cambiar|migr(a|á)|migrar|' +
+    'corrige|corregir|correg(í|ir)|constru(ye|í)|construir|modific(a|á)|modificar|' +
+    'refactoriz(a|á)|refactorizar|elimin(a|á)|eliminar|reescrib(e|í)|reescribir|desplieg(a|á)|desplegar|' +
+    'escrib(í|e)|escribir|implement\\w*|writ(e|ing)|creat\\w*|fix\\w*|build\\w*|refactor\\w*|migrat\\w*|' +
+    'add\\w*|remov\\w*|delet\\w*|modify|modifies|modifying|rewrit\\w*',
+);
+
+/** Declared LEVEL near the word "level"/"classification" in Spanish or English, matching
+ * the plugin-wide convention (see risk-level.mjs). */
+const DEMANDING_LEVEL_PATTERN =
+  /(nivel|level|clasificaci[oó]n|classification)[^\n]{0,25}?\b(STANDARD|HIGH-RISK)\b/iu;
+const EXEMPT_LEVEL_PATTERN =
+  /(nivel|level|clasificaci[oó]n|classification)[^\n]{0,25}?\b(QUESTION|MICRO)\b/iu;
+
+function fileExistsNonEmpty(path) {
+  try {
+    return existsSync(path) && statSync(path).size > 0;
+  } catch {
+    return false;
+  }
+}
+
+function findCatalog(catalogLocations) {
+  for (const relative of catalogLocations) {
+    const path = join(process.cwd(), relative);
+    if (existsSync(path)) return path;
+  }
+  return null;
+}
+
+/** Discovers the contract tree root next to wherever the catalog lives, or `.ai/features`. */
+function contractTreeRootFor(catalogPath) {
+  const candidates = catalogPath
+    ? [join(dirname(catalogPath), 'features')]
+    : [];
+  candidates.push(join(process.cwd(), '.ai', 'features'));
+  candidates.push(join(process.cwd(), 'features'));
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function contractExistsFor(treeRoot, featureName) {
+  if (!treeRoot) return false;
+  const featureDirectory = join(treeRoot, featureName);
+  if (!existsSync(featureDirectory)) return false;
+  return CONTRACT_FILES.some((file) =>
+    fileExistsNonEmpty(join(featureDirectory, file)),
+  );
+}
+
+function parseJsonOrNull(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function writeTargetFrom(toolInput) {
+  return String(
+    toolInput.TargetFile ??
+      toolInput.target_file ??
+      toolInput.file_path ??
+      toolInput.path ??
+      '',
+  );
+}
+
+function writeContentFrom(toolInput) {
+  return String(
+    toolInput.CodeContent ??
+      toolInput.ReplacementContent ??
+      toolInput.content ??
+      '',
+  );
+}
+
+/** Denies the single first advanced-status feature in the new catalog content that has
+ * no contract on disk, or does nothing when every advanced feature has one. */
+function denyIfAdvancedFeatureLacksContract(features, treeRoot) {
+  for (const feature of features) {
+    if (!feature?.name || !ADVANCED_STATUSES.has(feature.status)) continue;
+    if (contractExistsFor(treeRoot, feature.name)) continue;
+    deny(
+      GATE_ID,
+      `Feature '${feature.name}' is set to '${feature.status}' but has no non-empty ` +
+        `contract (${CONTRACT_FILES.join(', ')}) under the discovered contract tree.`,
+    );
+  }
+}
+
+function checkCatalogWrite(toolInput, catalogPath, treeRoot) {
+  const target = writeTargetFrom(toolInput);
+  if (!catalogPath || !target.includes(CATALOG_FILE_NAME)) return;
+
+  const parsed = parseJsonOrNull(writeContentFrom(toolInput));
+  const features = Array.isArray(parsed?.features) ? parsed.features : [];
+  denyIfAdvancedFeatureLacksContract(features, treeRoot);
+}
+
+function isExemptDelegation(toolInput, prompt, exemptSubagents) {
+  const subagentType = String(
+    toolInput.subagent_type ?? toolInput.subagentType ?? '',
+  ).toLowerCase();
+  if (exemptSubagents.includes(subagentType)) return true;
+  if (EXEMPT_LEVEL_PATTERN.test(prompt)) return true;
+  if (!DEMANDING_LEVEL_PATTERN.test(prompt)) return true;
+  if (!IMPLEMENTATION_VERBS.test(prompt)) return true;
+  return false;
+}
+
+function featureNamesCitedIn(prompt) {
+  const pattern = /\.(?:ai)[\\/]features[\\/]([\w.@-]+)/gi;
+  const names = [];
+  let match;
+  while ((match = pattern.exec(prompt)) !== null) names.push(match[1]);
+  return names;
+}
+
+function checkDelegation(toolInput, treeRoot, exemptSubagents) {
+  const prompt = String(
+    toolInput.prompt ?? toolInput.Prompt ?? toolInput.task ?? '',
+  );
+  if (!prompt.trim()) return;
+  if (isExemptDelegation(toolInput, prompt, exemptSubagents)) return;
+
+  const citedFeatures = featureNamesCitedIn(prompt);
+  if (citedFeatures.length === 0) return; // no citation: nothing this gate can check
+
+  const missing = citedFeatures.filter(
+    (feature) => !contractExistsFor(treeRoot, feature),
+  );
+  if (missing.length === citedFeatures.length) {
+    deny(
+      GATE_ID,
+      `This implementation delegation cites feature(s) [${missing.join(', ')}] with no ` +
+        `non-empty contract (${CONTRACT_FILES.join(', ')}) on disk. Write the contract ` +
+        'before implementing.',
+    );
+  }
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: {
+      catalogLocations: DEFAULT_CATALOG_LOCATIONS,
+      exemptSubagents: DEFAULT_EXEMPT_SUBAGENTS,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    const isWrite = WRITE_TOOLS.has(toolName);
+    const isDelegation = DELEGATION_TOOLS.has(toolName);
+    if (!isWrite && !isDelegation) return;
+
+    const catalogLocations =
+      parameters.catalogLocations ?? DEFAULT_CATALOG_LOCATIONS;
+    const catalogPath = findCatalog(catalogLocations);
+    if (!catalogPath) return; // no SDD harness adopted: stay silent
+
+    const treeRoot = contractTreeRootFor(catalogPath);
+
+    if (isWrite) checkCatalogWrite(toolInput, catalogPath, treeRoot);
+    if (isDelegation) {
+      const exemptSubagents =
+        parameters.exemptSubagents ?? DEFAULT_EXEMPT_SUBAGENTS;
+      checkDelegation(toolInput, treeRoot, exemptSubagents);
+    }
+  },
+);

package/plugins/gates/hooks/gates/sdd-specs/test.mjs

@@ -0,0 +1,163 @@
+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 makeProject() {
+  const project = mkdtempSync(join(tmpdir(), 'sdd-specs-'));
+  mkdirSync(join(project, '.git'));
+  return project;
+}
+
+function writeProjectConfig(project, config) {
+  mkdirSync(join(project, '.ai'), { recursive: true });
+  writeFileSync(join(project, '.ai', 'config.json'), JSON.stringify(config));
+}
+
+function runGate(project, payload) {
+  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 delegate(prompt, subagentType = 'backend') {
+  return {
+    tool_name: 'Agent',
+    tool_input: { prompt, subagent_type: subagentType },
+  };
+}
+
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+function enableGate(project) {
+  writeProjectConfig(project, {
+    gates: { requireSpecBeforeImplementing: true },
+  });
+}
+
+test('auto-off: no catalog anywhere allows implementation delegation', () => {
+  const project = makeProject();
+  enableGate(project);
+  const prompt =
+    'Nivel: STANDARD\nImplementá el checkout citando .ai/features/checkout/tasks/t1/';
+  assert.equal(runGate(project, delegate(prompt)), null);
+});
+
+test('denies an implementation delegation citing a feature with no contract on disk', () => {
+  const project = makeProject();
+  enableGate(project);
+  mkdirSync(join(project, '.ai'), { recursive: true });
+  writeFileSync(
+    join(project, '.ai', 'feature_list.json'),
+    JSON.stringify({ features: [] }),
+  );
+  // features tree exists but the cited feature has no contract file
+  mkdirSync(join(project, '.ai', 'features', 'checkout'), { recursive: true });
+  const prompt =
+    'Nivel: STANDARD\nImplementá .ai/features/checkout/ el flujo de pago.';
+  assert.ok(isDeny(runGate(project, delegate(prompt))));
+});
+
+test('allows an implementation delegation citing a feature with a non-empty contract', () => {
+  const project = makeProject();
+  enableGate(project);
+  mkdirSync(join(project, '.ai'), { recursive: true });
+  writeFileSync(
+    join(project, '.ai', 'feature_list.json'),
+    JSON.stringify({ features: [] }),
+  );
+  mkdirSync(join(project, '.ai', 'features', 'checkout'), { recursive: true });
+  writeFileSync(
+    join(project, '.ai', 'features', 'checkout', 'brief.md'),
+    '# Checkout\n\nObjetivo: cobrar.',
+  );
+  const prompt =
+    'Nivel: STANDARD\nImplementá .ai/features/checkout/ el flujo de pago.';
+  assert.equal(runGate(project, delegate(prompt)), null);
+});
+
+test('disabled by config: the gate does not run', () => {
+  const project = makeProject();
+  writeProjectConfig(project, {
+    gates: { requireSpecBeforeImplementing: false },
+  });
+  mkdirSync(join(project, '.ai'), { recursive: true });
+  writeFileSync(
+    join(project, '.ai', 'feature_list.json'),
+    JSON.stringify({ features: [] }),
+  );
+  mkdirSync(join(project, '.ai', 'features', 'checkout'), { recursive: true });
+  const prompt =
+    'Nivel: STANDARD\nImplementá .ai/features/checkout/ el flujo de pago.';
+  assert.equal(runGate(project, delegate(prompt)), null);
+});
+
+test('a prompt that only describes, does not order, is exempt via QUESTION level', () => {
+  const project = makeProject();
+  enableGate(project);
+  mkdirSync(join(project, '.ai'), { recursive: true });
+  writeFileSync(
+    join(project, '.ai', 'feature_list.json'),
+    JSON.stringify({ features: [] }),
+  );
+  mkdirSync(join(project, '.ai', 'features', 'checkout'), { recursive: true });
+  const prompt =
+    'Nivel: QUESTION\nExplicá cómo funciona .ai/features/checkout/ hoy.';
+  assert.equal(runGate(project, delegate(prompt)), null);
+});
+
+test('exemptSubagents param override exempts a custom subagent type', () => {
+  const project = makeProject();
+  writeProjectConfig(project, {
+    gates: {
+      requireSpecBeforeImplementing: {
+        enabled: true,
+        exemptSubagents: ['worker'],
+      },
+    },
+  });
+  mkdirSync(join(project, '.ai'), { recursive: true });
+  writeFileSync(
+    join(project, '.ai', 'feature_list.json'),
+    JSON.stringify({ features: [] }),
+  );
+  mkdirSync(join(project, '.ai', 'features', 'checkout'), { recursive: true });
+  const prompt =
+    'Nivel: STANDARD\nImplementá .ai/features/checkout/ el flujo de pago.';
+  assert.equal(runGate(project, delegate(prompt, 'worker')), null);
+});
+
+test('a catalog write moving a feature to spec_ready without contract is denied', () => {
+  const project = makeProject();
+  enableGate(project);
+  mkdirSync(join(project, '.ai', 'features'), { recursive: true });
+  // The catalog already exists on disk (an Edit to an existing file); the write below
+  // is the new content about to replace it.
+  writeFileSync(
+    join(project, '.ai', 'feature_list.json'),
+    JSON.stringify({ features: [] }),
+  );
+  const write = {
+    tool_name: 'Write',
+    tool_input: {
+      file_path: join(project, '.ai', 'feature_list.json'),
+      content: JSON.stringify({
+        features: [{ name: 'checkout', status: 'spec_ready' }],
+      }),
+    },
+  };
+  assert.ok(isDeny(runGate(project, write)));
+});

package/plugins/gates/hooks/gates/test-after-implementation/index.mjs

@@ -0,0 +1,101 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { basename, dirname, relative } from 'node:path';
+import { runGate, warn, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'test-after-implementation';
+const CONFIG_KEY = 'warnTestWrittenAfterImplementation';
+
+const DEFAULT_IMPLEMENTATION_EXTENSIONS = [
+  '.ts',
+  '.tsx',
+  '.js',
+  '.jsx',
+  '.mjs',
+  '.vue',
+];
+const TEST_FILE_PATTERN = /\.(spec|test)\.[cm]?[jt]sx?$/i;
+// `git status --porcelain` prefixes each line with a 2-character status code plus a space.
+const PORCELAIN_STATUS_PREFIX_LENGTH = 3;
+
+function baseNameWithoutTestSuffix(fileName) {
+  return fileName.replace(TEST_FILE_PATTERN, '');
+}
+
+function gitStatusPorcelain(cwd) {
+  try {
+    const output = execFileSync('git', ['status', '--porcelain'], {
+      cwd,
+      timeout: 5000,
+    }).toString();
+    return output
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean);
+  } catch {
+    // Not a git repo, or git unavailable — nothing to cross-check against.
+    return [];
+  }
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: {
+      implementationExtensions: DEFAULT_IMPLEMENTATION_EXTENSIONS,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    if (!TOOL_GROUPS.write.includes(toolName)) return;
+
+    const filePath = toolInput?.file_path ?? '';
+    if (!TEST_FILE_PATTERN.test(filePath)) return;
+    if (existsSync(filePath)) return; // only new test file creation, not edits
+
+    const cwd = process.cwd();
+    const statusLines = gitStatusPorcelain(cwd);
+    if (statusLines.length === 0) return;
+
+    const testFileName = basename(filePath);
+    const stem = baseNameWithoutTestSuffix(testFileName);
+    // `git status --porcelain` reports paths relative to `cwd`; the test's own
+    // directory (relative to `cwd`) is the fair comparison, not its absolute path.
+    // `relative()` returns '' for the repo root itself, while `dirname()` on a
+    // bare file name returns '.' — normalize both to '.' so root-level files compare equal.
+    const testDirectoryRelativeToRepo = relative(cwd, dirname(filePath)) || '.';
+
+    const pairedImplementationChanged = statusLines.some((line) => {
+      const changedPath = line.slice(PORCELAIN_STATUS_PREFIX_LENGTH).trim();
+      if (
+        !parameters.implementationExtensions.some((extension) =>
+          changedPath.endsWith(extension),
+        )
+      )
+        return false;
+      if (TEST_FILE_PATTERN.test(changedPath)) return false;
+      const lastDot = changedPath.lastIndexOf('.');
+      const changedBase = basename(
+        changedPath,
+        lastDot >= 0 ? changedPath.slice(lastDot) : '',
+      );
+      return (
+        changedBase === stem &&
+        (dirname(changedPath) || '.') === testDirectoryRelativeToRepo
+      );
+    });
+
+    if (!pairedImplementationChanged) return;
+
+    warn(
+      GATE_ID,
+      `Creating test ${testFileName} after its paired implementation was already modified (uncommitted). Consider writing tests before or alongside the implementation, not after.`,
+    );
+  },
+);
+
+// Note: the source guard (guard-test-despues-de-implementar.mjs) denies this
+// case outright. This gate warns instead, because registry.json names the
+// config key warnTestWrittenAfterImplementation, which declares warn as the
+// intended severity for this migration.

package/plugins/gates/hooks/gates/test-after-implementation/test.mjs

@@ -0,0 +1,81 @@
+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 newProject({ config, git = true } = {}) {
+  const project = mkdtempSync(join(tmpdir(), 'test-after-implementation-'));
+  if (git) {
+    execFileSync('git', ['init', '-q'], { cwd: project });
+    execFileSync('git', ['config', 'user.email', 'a@b.c'], { cwd: project });
+    execFileSync('git', ['config', 'user.name', 'a'], { cwd: project });
+  }
+  if (config) {
+    mkdirSync(join(project, '.ai'));
+    writeFileSync(join(project, '.ai', 'config.json'), JSON.stringify(config));
+  }
+  return project;
+}
+
+function runGateIn(project, payload) {
+  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 writeTest(filePath) {
+  return {
+    tool_name: 'Write',
+    tool_input: { file_path: filePath, content: 'test content' },
+  };
+}
+function isWarn(result) {
+  return result?.hookSpecificOutput?.additionalContext !== undefined;
+}
+
+const ENABLE = { gates: { warnTestWrittenAfterImplementation: true } };
+
+test('warns when creating a test whose paired implementation was just modified (uncommitted)', () => {
+  const project = newProject({ config: ENABLE });
+  writeFileSync(join(project, 'thing.js'), 'export const thing = 1;');
+  const testPath = join(project, 'thing.test.js');
+  assert.ok(isWarn(runGateIn(project, writeTest(testPath))));
+});
+
+test('allows creating a test with no paired uncommitted implementation', () => {
+  const project = newProject({ config: ENABLE });
+  const testPath = join(project, 'unrelated.test.js');
+  assert.equal(runGateIn(project, writeTest(testPath)), null);
+});
+
+test('allows editing (not creating) an existing test file', () => {
+  const project = newProject({ config: ENABLE });
+  writeFileSync(join(project, 'thing.js'), 'export const thing = 1;');
+  const testPath = join(project, 'thing.test.js');
+  writeFileSync(testPath, 'existing test');
+  assert.equal(runGateIn(project, writeTest(testPath)), null);
+});
+
+test('degrades to allow when not a git repo', () => {
+  const project = newProject({ config: ENABLE, git: false });
+  const testPath = join(project, 'thing.test.js');
+  assert.equal(runGateIn(project, writeTest(testPath)), null);
+});
+
+test('disabled by default (registry default is false)', () => {
+  const project = newProject();
+  writeFileSync(join(project, 'thing.js'), 'export const thing = 1;');
+  const testPath = join(project, 'thing.test.js');
+  assert.equal(runGateIn(project, writeTest(testPath)), null);
+});