@devrik-tools/claude-gates 0.7.2 → 0.8.0

package/plugins/gates/hooks/gates/brief-approved/index.mjs

@@ -1,38 +1,25 @@
-// brief-approved — denies an implementation delegation (STANDARD/HIGH-RISK, an
-// implementation verb) that targets a feature whose brief/spec has no recorded human
-// approval. Migrated from a real incident: the assistant took an ambiguous user reply
-// ("hagamos el brief") as approval of a spec it had already written, delegated
-// implementation straight away, and never pasted the full brief into the chat for the
-// user to confirm line by line. `sdd-specs` already blocks implementing a feature with
-// NO contract at all; this gate blocks implementing a feature whose contract exists but
-// was never actually approved by the user — a distinct failure this incident exposed.
+// brief-approved — denies a STANDARD/HIGH-RISK implementation delegation that cites a
+// feature whose brief.md carries no recorded human approval. Born from a real incident: an
+// ambiguous reply ("hagamos el brief") was taken as approval of a spec the assistant had
+// written itself, and implementation was delegated without the user ever reading it.
 //
-// ── What "approved" means here (deliberately narrow) ────────────────────────────────
-// A hook cannot read the chat, so it cannot verify the assistant actually pasted the
-// full brief and that the user actually read it. What IS checkable: the brief file
-// itself carries a frontmatter block written ONLY once that confirmation happened —
-//   ---
-//   status: approved
-//   approved_at: <ISO timestamp>
-//   approval_quote: "<user's own words>"
-//   ---
-// The gate does not (cannot) verify the quote is genuine; it verifies the field exists
-// and is non-empty, which at minimum forces the assistant to stop and produce a
-// specific artifact instead of silently inferring consent from a vague reply.
-//
-// ── Auto-off when there is no brief to approve ──────────────────────────────────────
-// Same discovery as sdd-specs: only fires once a feature contract tree exists under
-// .ai/features/<name>/ (or the configured catalog's sibling `features` dir) AND that
-// feature has a brief.md/asserts.md file. A project with no such file for the cited
-// feature is out of this gate's scope (sdd-specs already denies that case).
-//
-// ── What is NOT configurable (base, non-negotiable) ─────────────────────────────────
-// The frontmatter field names (status/approved_at/approval_quote) are fixed, not a
-// project param — a configurable field name would let a delegation "approve" itself by
-// pointing the gate at whatever key it just wrote.
+// Decisions: a hook cannot read the chat, so "approved" means the brief's frontmatter
+// carries `status: approved` AND a non-empty `approval_quote` — an artifact the assistant
+// must stop and produce. The field names are fixed on purpose: a configurable key would let
+// a delegation approve itself. The gate enforces ONLY when the feature directory contains
+// brief.md; a feature with other contract files or none is sdd-specs' business.
 
 import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
+import { projectRootOf, stripBom } from '../../lib/config.mjs';
+import {
+  DEFAULT_EXEMPT_SUBAGENTS,
+  DEMANDING_LEVELS,
+  featureNamesCitedIn,
+  isImplementationRequest,
+  isSubagentNamedIn,
+  operativeLevelOf,
+} from '../../lib/delegation.mjs';
 import {
   runGate,
   deny,
@@ -44,125 +31,68 @@ const GATE_ID = 'brief-approved';
 const CONFIG_KEY = 'requireApprovedBriefBeforeImplementing';
 
 const CATALOG_FILE_NAME = 'feature_list.json';
+const FEATURES_DIRECTORY = 'features';
+const BRIEF_FILE = 'brief.md';
 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',
-];
-
-/** Files that count as a feature's contract; the first one found on disk is the one
- * checked for approval (mirrors sdd-specs' CONTRACT_FILES precedence). */
-const CONTRACT_FILES = [
-  'brief.md',
-  'requirements.md',
-  'design.md',
-  'tasks.md',
-  'asserts.md',
-];
-
-const APPROVED_FRONTMATTER_PATTERN = /^---\r?\n(?<body>[\s\S]*?)\r?\n---/;
-const APPROVED_STATUS_PATTERN = /^status:[ \t]*approved[ \t]*$/im;
-const APPROVAL_QUOTE_PATTERN = /^approval_quote:[ \t]*(\S.*)$/im;
+const FRONTMATTER_PATTERN = /^---\r?\n(?<body>[\s\S]*?)\r?\n---/;
+const APPROVED_STATUS_PATTERN = /^status:[ \t]*["']?approved["']?[ \t]*$/im;
+const APPROVAL_QUOTE_PATTERN = /^approval_quote:(.*)$/im;
 
-function withWordBoundary(alternation) {
-  return new RegExp(
-    `(?<![\\p{L}\\p{N}_])(${alternation})(?![\\p{L}\\p{N}_])`,
-    'iu',
-  );
+function resolveFrom(root, path) {
+  return isAbsolute(path) ? path : join(root, path);
 }
 
-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*',
-);
-
-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 findCatalog(catalogLocations) {
+function findCatalog(root, catalogLocations) {
   for (const relative of catalogLocations) {
-    const path = join(process.cwd(), relative);
+    const path = resolveFrom(root, relative);
     if (existsSync(path)) return path;
   }
   return null;
 }
 
-function contractTreeRootFor(catalogPath) {
+function contractTreeRootFor(root, catalogPath) {
   const candidates = catalogPath
-    ? [join(dirname(catalogPath), 'features')]
+    ? [join(dirname(catalogPath), FEATURES_DIRECTORY)]
     : [];
-  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;
+  candidates.push(
+    join(root, '.ai', FEATURES_DIRECTORY),
+    join(root, FEATURES_DIRECTORY),
+  );
+  return candidates.find((candidate) => existsSync(candidate)) ?? null;
 }
 
-/** The first existing contract file's path for a feature, or null if none exists. */
-function contractFileFor(treeRoot, featureName) {
-  if (!treeRoot) return null;
-  const featureDirectory = join(treeRoot, featureName);
-  if (!existsSync(featureDirectory)) return null;
-  for (const file of CONTRACT_FILES) {
-    const path = join(featureDirectory, file);
-    if (existsSync(path)) return path;
-  }
-  return null;
+function briefPathFor(treeRoot, featureName) {
+  const path = join(treeRoot, featureName, BRIEF_FILE);
+  return existsSync(path) ? path : null;
 }
 
-/** Whether a contract file's frontmatter records a real approval: `status: approved`
- * plus a non-empty `approval_quote`. Both must be present — status alone is a label
- * the assistant could set on itself with no evidence a quote was ever collected. */
-function isApproved(contractPath) {
+function isApproved(briefPath) {
   let content;
   try {
-    content = readFileSync(contractPath, 'utf8');
+    content = stripBom(readFileSync(briefPath, 'utf8'));
   } catch {
     return false;
   }
-  const frontmatter = APPROVED_FRONTMATTER_PATTERN.exec(content)?.groups?.body;
+  const frontmatter = FRONTMATTER_PATTERN.exec(content)?.groups?.body;
   if (!frontmatter) return false;
   if (!APPROVED_STATUS_PATTERN.test(frontmatter)) return false;
-  const quoteMatch = APPROVAL_QUOTE_PATTERN.exec(frontmatter);
-  const quote = quoteMatch?.[1]?.replace(/^["']|["']$/g, '').trim();
-  return Boolean(quote);
+  const quote = APPROVAL_QUOTE_PATTERN.exec(frontmatter)?.[1] ?? '';
+  return (
+    quote
+      .trim()
+      .replace(/^["']|["']$/g, '')
+      .trim().length > 0
+  );
 }
 
 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;
+  if (isSubagentNamedIn(toolInput, exemptSubagents)) return true;
+  if (!DEMANDING_LEVELS.has(operativeLevelOf(prompt))) return true;
+  return !isImplementationRequest(prompt);
 }
 
 runGate(
@@ -175,45 +105,46 @@ runGate(
       exemptSubagents: DEFAULT_EXEMPT_SUBAGENTS,
     },
   },
-  ({ toolName, toolInput, parameters }) => {
+  ({ toolName, toolInput, parameters, cwd }) => {
     if (!toolInGroups(toolName, ['delegation'])) return;
 
     const prompt = delegationPromptOf(toolInput);
     if (!prompt.trim()) return;
-
-    const exemptSubagents =
-      parameters.exemptSubagents ?? DEFAULT_EXEMPT_SUBAGENTS;
-    if (isExemptDelegation(toolInput, prompt, exemptSubagents)) return;
+    if (isExemptDelegation(toolInput, prompt, parameters.exemptSubagents))
+      return;
 
     const citedFeatures = featureNamesCitedIn(prompt);
-    if (citedFeatures.length === 0) return; // no citation: nothing this gate can check
+    if (citedFeatures.length === 0) return;
 
+    const root = projectRootOf(cwd) ?? cwd;
     const catalogLocations =
-      parameters.catalogLocations ?? DEFAULT_CATALOG_LOCATIONS;
-    const catalogPath = findCatalog(catalogLocations);
-    const treeRoot = contractTreeRootFor(catalogPath);
-    if (!treeRoot) return; // no SDD harness adopted: stay silent
+      parameters.catalogLocations.length > 0
+        ? parameters.catalogLocations
+        : DEFAULT_CATALOG_LOCATIONS;
+    const treeRoot = contractTreeRootFor(
+      root,
+      findCatalog(root, catalogLocations),
+    );
+    if (!treeRoot) return;
 
     const unapproved = citedFeatures
       .map((feature) => ({
         feature,
-        contractPath: contractFileFor(treeRoot, feature),
+        briefPath: briefPathFor(treeRoot, feature),
       }))
-      .filter(({ contractPath }) => contractPath) // no contractPath: sdd-specs already denies that case
-      .filter(({ contractPath }) => !isApproved(contractPath));
-
+      .filter(({ briefPath }) => briefPath && !isApproved(briefPath));
     if (unapproved.length === 0) return;
 
     const fileList = unapproved
-      .map(({ feature, contractPath }) => `${feature} -> ${contractPath}`)
+      .map(({ feature, briefPath }) => `${feature} -> ${briefPath}`)
       .join('\n  ');
     deny(
       CONFIG_KEY,
-      `This implementation delegation cites unapproved feature(s):\n  ${fileList}\n` +
+      `This implementation delegation cites feature(s) whose brief has no recorded approval:\n  ${fileList}\n` +
         'Paste the FULL brief into the chat, get an explicit confirmation from the user ' +
-        '(not a vague "dale"/"sigamos" — an actual sentence confirming they read it), ' +
-        'then add this frontmatter to the TOP of that exact contract file before ' +
-        'relaunching (no filesystem exploration needed — the path above is the file to edit):\n' +
+        '(not a vague "ok"/"sigamos" — an actual sentence confirming they read it), ' +
+        'then add this frontmatter to the TOP of that exact brief.md before relaunching ' +
+        '(no filesystem exploration needed — the path above is the file to edit):\n' +
         '---\nstatus: approved\napproved_at: <ISO timestamp>\n' +
         'approval_quote: "<the user\'s own confirming words>"\n---',
     );

package/plugins/gates/hooks/gates/brief-before-delegate/index.mjs

@@ -1,33 +1,20 @@
-// brief-before-delegate — denies an implementation delegation whose prompt does not
-// declare, in recognizable form, a GOAL, concrete STEPS and a DONE-WHEN criterion.
+// brief-before-delegate — denies an implementation delegation whose prompt does not state a
+// GOAL, concrete STEPS and a DONE-WHEN criterion, each with real content past its marker.
 //
-// ── Why this is decidable, and what it deliberately does not judge ─────────────────
-// A hook sees a tool call, not how hard the underlying task is. "Complex" is not a
-// fact in the payload, and any heuristic that approximates it (file count, prompt
-// length, "architecture" keywords) ends up blocking trivial work sooner or later.
-// The decidable question is narrower: did THIS delegation's prompt state a goal, its
-// steps and a success criterion before the subagent starts? That is a fact about the
-// text itself, not a judgment about the task.
-//
-// Whether the declared goal is the RIGHT goal, or the steps are the RIGHT steps, or
-// the criterion truly resolves the ambiguity — that needs domain understanding a
-// script cannot supply. This gate only enforces that the brief EXISTS, never that it
-// is good. It DOES require each section to carry actual content past its marker —
-// pasting the words "Objetivo:"/"Criterio:" next to filler is not a brief either.
-//
-// ── What is exempt ───────────────────────────────────────────────────────────────
-// - Read-only exploration/subagents (readOnlySubagents param, or a prompt whose
-//   dominant verb is investigate/search/read/explain/audit with no implementation
-//   verb): that is a QUESTION, not an implementation order — forcing a brief onto it
-//   would make it simulate project structure it does not have.
-//   The readOnlySubagents exemption is a name the delegator declares, not a verified
-//   capability this hook can check — so it is void whenever the prompt itself carries
-//   a mutation-risk signal (money/auth/data/write/deploy): the signal in the text
-//   outranks the label on the call.
-// - A prompt that already carries structure (a list, numbered steps, or prose that
-//   otherwise states the three signals): the form is free, only the content is
-//   required.
+// Decisions: the gate judges that the brief EXISTS, never that it is good — "is this the
+// right goal" needs domain judgment a hook cannot supply. A read-only subagent name is a
+// declared label, not a verified capability, so it exempts only while the prompt carries no
+// mutation-risk signal. A documentary deliverable (README, report, changelog) is not an
+// implementation brief and is not judged here.
 
+import {
+  DEFAULT_READ_ONLY_SUBAGENTS,
+  isDocumentaryRequest,
+  isExemptQuery,
+  isImplementationRequest,
+  isReadOnlySubagent,
+  promptExcerpt,
+} from '../../lib/delegation.mjs';
 import {
   runGate,
   deny,
@@ -35,71 +22,29 @@ import {
   toolInGroups,
   delegationPromptOf,
 } from '../../lib/hook-io.mjs';
-import { MUTATION_RISK_SIGNAL } from '../../lib/signals.mjs';
+import { withUnicodeWordBoundary } from '../../lib/signals.mjs';
 
 const GATE_ID = 'brief-before-delegate';
 const CONFIG_KEY = 'requireBriefBeforeDelegating';
 
 const DEFAULT_MIN_BRIEF_LENGTH = 180;
-const DEFAULT_READ_ONLY_SUBAGENTS = ['explore', 'claude-code-guide', 'plan'];
 
-// How much of an over-length prompt to quote back in a denial message.
-const PROMPT_EXCERPT_LENGTH = 80;
-// Total signals this gate checks for (goal, steps, criterion): when all are missing at
-// once it is indistinguishable from "never thought through", so that combination denies
-// instead of only warning.
+// All three signals missing at once is indistinguishable from "never thought through", so
+// that combination denies where a partial brief only warns.
 const TOTAL_REQUIRED_SIGNALS = 3;
-// Minimum substantial (non-stopword) characters a section needs past its own marker to
-// count as "stated" instead of merely name-dropped. Chosen so a single short filler
-// word ("cosa.", "listo.") does not clear it, but any real sentence does.
+// A single filler word ("cosa.", "listo.") must not clear the bar; any real sentence does.
 const MIN_SECTION_SUBSTANCE_LENGTH = 12;
+const MIN_SUBSTANTIVE_WORDS = 2;
+const MIN_WORD_LENGTH = 3;
 
-/** Unicode-aware word boundary: JS's `\b` does not treat accented letters as word
- * chars, so a plain `\bcorregi\b`-style pattern silently misses an accented
- * imperative. Lookarounds over `\p{L}|\p{N}|_` cover the full alphabet instead. */
-function withUnicodeWordBoundary(alternatives) {
-  return new RegExp(
-    `(?<![\\p{L}\\p{N}_])(${alternatives})(?![\\p{L}\\p{N}_])`,
-    'iu',
-  );
-}
-
-const IMPLEMENTATION_VERBS = withUnicodeWordBoundary(
-  'implementa|implementar|escrib(e|í)|escribir|cre(a|á)|crear|corrige|correg(í|ir)|' +
-    'arregl(a|á)|arreglar|constru(ye|í)|construir|refactoriz(a|á)|refactorizar|' +
-    'migr(a|á)|migrar|agreg(a|á)|agregar|añad(e|í)|añadir|elimin(a|á)|eliminar|' +
-    'modific(a|á)|modificar|reescrib(e|í)|reescribir|desplieg(a|á)|desplegar|' +
-    'hac(e|er|é)|resuelve|resolv(é|er)|soluciona|solucion(á|ar)|encárgate|encargate|' +
-    'ocúpate|ocupate|cambi(a|á)|cambiar|actualiz(a|á)|actualizar|' +
-    'implement|write|fix|build|refactor|migrate|add|remove|modify|update',
-);
-
-const READ_ONLY_VERBS = withUnicodeWordBoundary(
-  'investiga|investigar|busca|buscar|explora|explorar|lee|leer|explica|explicar|' +
-    'audita|auditar|analiza|analizar|compara|comparar|diagnostica|diagnosticar|' +
-    'revisa|revisar|averigua|averiguar|' +
-    'investigate|search|explore|read|explain|audit|analyze|compare|diagnose|review',
-);
-
-// A prompt-level signal that a whitelisted read-only subagent name should NOT be
-// trusted to exempt this call: real mutation risk in the text outranks a self-declared
-// label. Deliberately broad (over-includes) — a false positive here only means the
-// brief check still runs, which is cheap; a false negative would let a mutator hide.
-// Centralized in lib/signals.mjs (ES+EN) — see its header for the class this covers.
-const MUTATION_RISK_SIGNAL_PATTERN = MUTATION_RISK_SIGNAL;
-
-/** Evidence of a stated GOAL, captured so its trailing content can be measured. */
 const GOAL_PATTERN = withUnicodeWordBoundary(
   'objetivo|meta|el fin es|se busca|para lograr|para que|goal|objective',
 );
 
-/** Evidence of structured STEPS: a list/bullet/numbered form. Anchored per-line (`m`
- * flag) with a single bounded `\s*` after the line start, so there is no nested
- * quantifier for a backtracking engine to explode on. Global so every item's substance
- * can be checked, not just the first. */
+// Anchored per line with a single bounded `\s*` so a backtracking engine has nothing to
+// explode on; global so every item's substance can be checked.
 const STRUCTURED_STEPS_PATTERN = /^[ \t]*(?:[-*•]|\d+[.)])[ \t]+(\S.*)$/gm;
 
-/** Evidence of a DONE-WHEN / acceptance criterion. */
 const CRITERION_PATTERN = withUnicodeWordBoundary(
   'criterio|acceptance|asserts?|se considera (hecho|terminado|listo)|' +
     'debe (verificarse|cumplir|pasar)|hasta que|done.when|' +
@@ -107,9 +52,8 @@ const CRITERION_PATTERN = withUnicodeWordBoundary(
     'given.{0,20}when.{0,20}then',
 );
 
-// Filler words that do not count toward a section's substance even though they are
-// real words — otherwise "listo cuando funcione bien y quede resuelto satisfactoriamente
-// para todos" reads as substantial despite saying nothing concrete.
+// Real words that say nothing concrete, so "listo cuando funcione bien y quede resuelto
+// satisfactoriamente para todos" does not read as substance.
 const FILLER_WORDS = new Set(
   (
     'cosa cosas cualquier corresponda correspondiente relevante sistema bien listo ' +
@@ -120,70 +64,43 @@ const FILLER_WORDS = new Set(
 );
 
 function stripDiacritics(text) {
-  return text.normalize('NFD').replace(/[̀-ͯ]/g, '');
+  return text.normalize('NFD').replace(/\p{M}/gu, '');
 }
 
-/** Non-filler word count in a chunk of text: what is left after dropping stopwords and
- * pure-filler vocabulary, so a marker followed only by empty phrasing does not count as
- * substance. */
 function substantiveWordCount(text) {
   const words = stripDiacritics(String(text).toLowerCase())
     .split(/[^\p{L}\p{N}]+/u)
     .filter(Boolean);
-  return words.filter((word) => word.length > 2 && !FILLER_WORDS.has(word))
-    .length;
+  return words.filter(
+    (word) => word.length >= MIN_WORD_LENGTH && !FILLER_WORDS.has(word),
+  ).length;
 }
 
-/** Text following a marker match, cut at end-of-line, so a following unrelated section
- * on the next line is not counted as this section's content. */
 function contentAfterMarker(prompt, markerMatch) {
   const from = markerMatch.index + markerMatch[0].length;
   const restOfLine = prompt.slice(from).split(/\r?\n/, 1)[0] ?? '';
   return restOfLine.replace(/^[\s:.\-–—]+/, '');
 }
 
-/** Whether the GOAL or CRITERION marker is followed by real substance: enough
- * substantive words, not just the marker itself or generic filler around it. */
-function markerHasSubstance(prompt, pattern) {
-  const withGlobal = new RegExp(
-    pattern.source,
-    pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`,
-  );
-  const match = withGlobal.exec(prompt);
-  if (!match) return false;
-  const content = contentAfterMarker(prompt, match);
+function hasSubstance(content) {
   return (
     content.trim().length >= MIN_SECTION_SUBSTANCE_LENGTH &&
-    substantiveWordCount(content) >= 2
+    substantiveWordCount(content) >= MIN_SUBSTANTIVE_WORDS
   );
 }
 
-/** Whether at least one structured list item carries real substance (not just a single
- * filler word like "paso"). */
-function stepsHaveSubstance(prompt) {
-  const matches = [...prompt.matchAll(STRUCTURED_STEPS_PATTERN)];
-  return matches.some((match) => substantiveWordCount(match[1]) >= 2);
-}
-
-function isReadOnlySubagentName(toolInput, readOnlySubagents) {
-  const type = String(
-    toolInput.subagent_type ?? toolInput.subagentType ?? '',
-  ).toLowerCase();
-  return new Set(readOnlySubagents.map((name) => name.toLowerCase())).has(type);
-}
-
-/** A whitelisted subagent name exempts a call ONLY when the prompt carries no
- * mutation-risk signal. The name is a declared label, never a verified capability this
- * hook can check — documented here so a future reader does not mistake it for one — and
- * a real risk signal in the text must win over it. */
-function isReadOnlySubagent(toolInput, prompt, readOnlySubagents) {
-  if (!isReadOnlySubagentName(toolInput, readOnlySubagents)) return false;
-  return !MUTATION_RISK_SIGNAL_PATTERN.test(prompt);
+function markerHasSubstance(prompt, pattern) {
+  const withGlobal = new RegExp(pattern.source, `${pattern.flags}g`);
+  for (const match of prompt.matchAll(withGlobal)) {
+    if (hasSubstance(contentAfterMarker(prompt, match))) return true;
+  }
+  return false;
 }
 
-function isReadOnlyRequest(prompt) {
-  if (IMPLEMENTATION_VERBS.test(prompt)) return false;
-  return READ_ONLY_VERBS.test(prompt);
+function stepsHaveSubstance(prompt) {
+  return [...prompt.matchAll(STRUCTURED_STEPS_PATTERN)].some(
+    (match) => substantiveWordCount(match[1]) >= MIN_SUBSTANTIVE_WORDS,
+  );
 }
 
 function missingSignals(prompt) {
@@ -205,15 +122,13 @@ function missingSignals(prompt) {
   return missing;
 }
 
-function denyTooShort(prompt) {
-  const excerpt = prompt.slice(0, PROMPT_EXCERPT_LENGTH);
-  const ellipsis = prompt.length > PROMPT_EXCERPT_LENGTH ? '…' : '';
+function denyTooShort(prompt, minBriefLength) {
   deny(
     CONFIG_KEY,
-    `This delegation asks for implementation ("${excerpt}${ellipsis}") in a ${prompt.length}-character ` +
-      'prompt — too short to carry a goal, steps and a done-when criterion. State what this aims to ' +
-      'achieve, what concretely needs doing (as a list or steps), and how completion is verified, then ' +
-      'relaunch.',
+    `This delegation asks for implementation ("${promptExcerpt(prompt)}") in a ${prompt.length}-character ` +
+      `prompt — too short to carry a goal, steps and a done-when criterion (minBriefLength: ${minBriefLength}). ` +
+      'State what this aims to achieve, what concretely needs doing (as a list or steps), and how ' +
+      'completion is verified, then relaunch.',
   );
 }
 
@@ -239,6 +154,14 @@ function reportMissingSignals(missing) {
   );
 }
 
+function isExempt(toolInput, prompt, readOnlySubagents) {
+  if (!prompt.trim()) return true;
+  if (isReadOnlySubagent(toolInput, prompt, readOnlySubagents)) return true;
+  if (isExemptQuery(prompt)) return true;
+  if (!isImplementationRequest(prompt)) return true;
+  return isDocumentaryRequest(prompt);
+}
+
 runGate(
   {
     id: GATE_ID,
@@ -253,15 +176,11 @@ runGate(
     if (!toolInGroups(toolName, ['delegation'])) return;
 
     const prompt = delegationPromptOf(toolInput);
-    if (!prompt.trim()) return;
-    if (isReadOnlySubagent(toolInput, prompt, parameters.readOnlySubagents))
-      return;
-    if (isReadOnlyRequest(prompt)) return;
-    if (!IMPLEMENTATION_VERBS.test(prompt)) return; // neither implementation nor read-only: do not guess
+    if (isExempt(toolInput, prompt, parameters.readOnlySubagents)) return;
 
     const trimmed = prompt.trim();
     if (trimmed.length < parameters.minBriefLength) {
-      denyTooShort(trimmed);
+      denyTooShort(trimmed, parameters.minBriefLength);
     }
 
     reportMissingSignals(missingSignals(prompt));