@devrik-tools/claude-gates 0.1.2 → 0.2.0

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

@@ -1,251 +1,256 @@
-// 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);
-    }
-  },
-);
+// 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,
+  toolInGroups,
+  writtenContentOf,
+  writtenPathOf,
+  delegationPromptOf,
+} from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'sdd-specs';
+const CONFIG_KEY = 'requireSpecBeforeImplementing';
+
+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, writtenPath) {
+  const roots = [process.cwd()];
+  // A write can target a catalog that lives elsewhere than cwd (a monorepo subpackage's
+  // own .ai/feature_list.json): also resolve catalogLocations relative to the directory
+  // of the file actually being written, not only the process cwd.
+  if (writtenPath) roots.push(dirname(writtenPath));
+  for (const root of roots) {
+    for (const relative of catalogLocations) {
+      const path = join(root, 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;
+  }
+}
+
+/** 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 = writtenPathOf(toolInput);
+  if (!catalogPath || !target.includes(CATALOG_FILE_NAME)) return;
+
+  const rawContent = writtenContentOf(toolInput);
+  const parsed = parseJsonOrNull(rawContent);
+  if (parsed === null) {
+    // Fail-closed, not fail-open: a write whose content does not parse as JSON but
+    // still targets the catalog is suspicious on its own -- a spec_ready/done transition
+    // hidden behind a malformed payload must not be silently allowed through.
+    deny(
+      GATE_ID,
+      `The write to ${CATALOG_FILE_NAME} does not parse as JSON. A catalog write that ` +
+        'cannot be verified for the spec-contract invariant is not allowed; fix the JSON ' +
+        'or write valid content.',
+    );
+  }
+  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 = delegationPromptOf(toolInput);
+  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 = toolInGroups(toolName, ['write']);
+    const isDelegation = toolInGroups(toolName, ['delegation']);
+    if (!isWrite && !isDelegation) return;
+
+    const catalogLocations =
+      parameters.catalogLocations ?? DEFAULT_CATALOG_LOCATIONS;
+    const catalogPath = findCatalog(
+      catalogLocations,
+      isWrite ? writtenPathOf(toolInput) : null,
+    );
+    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);
+    }
+  },
+);