@devrik-tools/claude-gates 0.7.2 → 0.9.0

package/plugins/gates/hooks/gates/block-remote-publish/index.mjs

@@ -1,113 +1,123 @@
 // block-remote-publish — denies publishing to a remote (`git push`, `gh pr merge`,
-// `gh release create`) without fresh human authorization. Split out of bash-commands so it
-// carries its OWN enabled flag: a project can turn remote-publish blocking off in config
-// (blockRemotePublish: false) WITHOUT losing the destructive-command protections (rm -rf,
-// git reset --hard) that live in bash-commands. Nothing is hardcoded any more — this gate
-// obeys its flag like every other, and appears in the CLI's gate selector on its own.
-//
-// Default: enabled. The safe posture is that the human states the authorization in chat,
-// naming commits, branch, remote and target — a project that wants the agent to push on its
-// own opts in explicitly by disabling this gate.
-//
-// ── Two-stage intent check, only for delegation prompts ─────────────────────────────
-// A real command's `command` field IS what the shell runs — a single-stage regex is right.
-// A delegation prompt is natural language that may DESCRIBE a command ("I extended the guard
-// to deny git push") without asking anyone to run it. There, publish rules run a second
-// stage: strip quoted/example text, then require that at least one surviving mention is not
-// governed by a reporting verb before denying.
+// `gh release create`) without fresh human authorization. Split out of bash-commands so a
+// project can let the agent push (blockRemotePublish: false) without losing the destructive
+// command protections. Deliberate limits: only a command segment that RUNS git/gh is judged
+// (a mention inside grep, echo or a --grep value is not a publish), a `--dry-run` push writes
+// nothing, and a delegation prompt is denied only when it orders the publish rather than
+// describing or forbidding it.
 
+import { hasRealCommandIntent } from '../../lib/delegation.mjs';
+import { normalizeGitCommand } from '../../lib/git.mjs';
 import {
-  runGate,
+  compileRegex,
+  delegationPromptOf,
   deny,
+  normalizeRulePairs,
+  runGate,
+  shellCommandOf,
   toolInGroups,
-  delegationPromptOf,
 } from '../../lib/hook-io.mjs';
 
 const GATE_ID = 'block-remote-publish';
 const CONFIG_KEY = 'blockRemotePublish';
 
-// Remote-publish rules as `[regexSource, reason]`. Sources (not RegExp) so a project could
-// override them through config if it ever needed to.
-function defaultPublishRules() {
-  return [
-    [
-      String.raw`\bgit\s+(?:-C\s+\S+\s+)?push\b`,
-      "Publishing to a remote ('git push') needs fresh authorization from the user naming " +
-        'commits, local branch, remote and target. This gate cannot verify that from the ' +
-        'command itself — ask the user and let them run it. To let the agent push on its ' +
-        'own, set "blockRemotePublish": false in .ai/config.json.',
-    ],
-    [
-      String.raw`\bgh\s+(?:pr\s+merge|release\s+create)\b`,
-      'Publishing via GitHub CLI (merging a PR or creating a release) needs fresh ' +
-        'authorization from the user naming commits, local branch, remote and target. ' +
-        'Ask the user and let them run it. To let the agent publish on its own, set ' +
-        '"blockRemotePublish": false in .ai/config.json.',
-    ],
-  ];
-}
+const AUTHORIZATION_REMEDY =
+  'needs fresh authorization from the user naming commits, local branch, remote and ' +
+  'target. This gate cannot verify that from the command itself — ask the user and let ' +
+  'them run it. To let the agent publish on its own, set "blockRemotePublish": false in ' +
+  '.ai/config.json.';
 
-// How far back from a mention to look for a governing verb, and the reporting-verb lexicon
-// that marks a mention as description rather than an order. Only the text before a mention
-// is inspected: what governs it is what precedes it (appending words after a real command
-// would otherwise be a trivial bypass).
-const DESCRIPTION_LOOK_BACK = 80;
-const REPORTING_VERB_PATTERN =
-  /(describe|explain|summar|mention|added|built|extended|denies?|deny|prohibit|protection|report|documentation|changelog)/i;
+const DEFAULT_PUBLISH_RULES = [
+  [
+    String.raw`\bgit\s+push\b`,
+    `Publishing to a remote ('git push') ${AUTHORIZATION_REMEDY}`,
+  ],
+  [
+    String.raw`\bgh\s+(?:pr\s+merge|release\s+create)\b`,
+    `Publishing via GitHub CLI (merging a PR or creating a release) ${AUTHORIZATION_REMEDY}`,
+  ],
+];
+const DEFAULT_REASON = `Publishing to a remote ${AUTHORIZATION_REMEDY}`;
 
-function compile(source) {
-  return new RegExp(source, 'i');
-}
+// `gh -R owner/repo pr merge` and `gh pr --repo x merge` name the repo between the words a
+// rule looks for; stripping the option first keeps the rules readable.
+const GH_REPO_OPTION_PATTERN =
+  /(\bgh\s+(?:pr\s+|release\s+)?)(?:-R|--repo)(?:=|\s+)\S+\s+/i;
 
-// git's GLOBAL options sit between `git` and the subcommand: `git -C <path> push`, etc. A
-// pattern that matches `git push` contiguously is evaded by any of them. Stripping these
-// first — turning `git -C /repo push` back into `git push` — closes that bypass at once.
-const GIT_OPTION_WITH_VALUE = String.raw`(?:-[Cc]|--git-dir|--work-tree|--namespace|--exec-path|--config-env)(?:\s+|=)\S+`;
-const GIT_FLAG_OPTION = String.raw`--(?:paginate|no-pager|bare|no-optional-locks)|-p`;
-const GIT_GLOBAL_OPTION_PATTERN = new RegExp(
-  String.raw`\bgit\s+(?:${GIT_OPTION_WITH_VALUE}|${GIT_FLAG_OPTION})\s+`,
-  'i',
-);
-
-function normalizeGitOptions(command) {
+function normalizeGhCommand(text) {
+  let normalized = text;
   let previous;
-  let normalized = command;
   do {
     previous = normalized;
-    normalized = normalized.replace(GIT_GLOBAL_OPTION_PATTERN, 'git ');
+    normalized = normalized.replace(GH_REPO_OPTION_PATTERN, '$1');
   } while (normalized !== previous);
   return normalized;
 }
 
-function stripQuoted(text) {
-  return text
-    .replace(/```[\s\S]*?```/g, ' ')
-    .replace(/"[^"\n]{0,300}"/g, ' ')
-    .replace(/'[^'\n]{0,300}'/g, ' ');
+function normalizeCommand(text) {
+  return normalizeGhCommand(normalizeGitCommand(text));
+}
+
+// ── Command segments that run git/gh ────────────────────────────────────────────────
+const SEGMENT_SEPARATOR = /;|&&|\|\||\||\n|\$\(|`/;
+const WRAPPER_WORD_PATTERN =
+  /^(?:\w+=\S*|command|sudo|exec|env|time|nohup|builtin)$/i;
+
+function stripLeadingWrappers(segment) {
+  const tokens = segment.replace(/^[\s(]+/, '').split(/\s+/);
+  while (tokens.length > 0 && WRAPPER_WORD_PATTERN.test(tokens[0]))
+    tokens.shift();
+  return tokens.join(' ');
+}
+
+const SHELL_WRAPPER_PATTERN =
+  /^(?:sh|bash|zsh|dash|ksh)\s+(-\w+)\s+(?:"([^"]*)"|'([^']*)')/i;
+const QUOTED_PATTERN = /"[^"]*"|'[^']*'/g;
+const PUBLISHING_BINARY_PATTERN = /^(?:git|gh)(?=\s|$)/i;
+
+function segmentsRunningGit(command) {
+  const segments = [];
+  for (const rawSegment of String(command).split(SEGMENT_SEPARATOR)) {
+    const segment = stripLeadingWrappers(rawSegment);
+    const wrapped = SHELL_WRAPPER_PATTERN.exec(segment);
+    if (wrapped && wrapped[1].includes('c')) {
+      segments.push(...segmentsRunningGit(wrapped[2] ?? wrapped[3]));
+    } else if (PUBLISHING_BINARY_PATTERN.test(segment)) {
+      segments.push(segment.replace(QUOTED_PATTERN, ' '));
+    }
+  }
+  return segments;
 }
 
-/** True when a surviving, non-quoted mention is not governed by a reporting verb. */
-function hasRealPublishIntent(text, pattern) {
-  if (!pattern.test(text)) return false;
-  const cleaned = stripQuoted(text);
-  const global = new RegExp(
-    pattern.source,
-    `${pattern.flags.replace('g', '')}g`,
-  );
-  const matches = [...cleaned.matchAll(global)];
-  if (matches.length === 0) return false;
-  return matches.some((match) => {
-    const from = Math.max(0, match.index - DESCRIPTION_LOOK_BACK);
-    return !REPORTING_VERB_PATTERN.test(cleaned.slice(from, match.index));
-  });
+const DRY_RUN_PUSH_PATTERN = /\bgit\s+push\b.*(?:\s--dry-run\b|\s-n\b)/i;
+
+function publishRules(parameters) {
+  return normalizeRulePairs(parameters.publishRules, DEFAULT_REASON)
+    .map(({ source, reason }) => ({ pattern: compileRegex(source), reason }))
+    .filter((rule) => rule.pattern !== null);
 }
 
-/** The text to inspect: a real command's command line, or the delegation prompt. */
-function commandTextFrom(toolName, toolInput) {
-  if (toolInGroups(toolName, ['shell'])) {
-    return String(toolInput.CommandLine ?? toolInput.command ?? '');
+function checkShellCommand(command, parameters) {
+  const rules = publishRules(parameters);
+  for (const segment of segmentsRunningGit(normalizeCommand(command))) {
+    if (DRY_RUN_PUSH_PATTERN.test(segment)) continue;
+    for (const { pattern, reason } of rules) {
+      if (pattern.test(segment))
+        deny(CONFIG_KEY, `${reason} (command: "${segment.trim()}")`);
+    }
+  }
+}
+
+function checkDelegationPrompt(prompt, parameters) {
+  const normalized = normalizeCommand(prompt);
+  for (const { pattern, reason } of publishRules(parameters)) {
+    if (hasRealCommandIntent(normalized, pattern)) {
+      deny(
+        CONFIG_KEY,
+        `${reason} The delegation prompt orders the publish; a subagent must not run it either.`,
+      );
+    }
   }
-  return delegationPromptOf(toolInput);
 }
 
 runGate(
@@ -116,25 +126,14 @@ runGate(
     configKey: CONFIG_KEY,
     enabledByDefault: true,
     defaultParams: {
-      publishRules: defaultPublishRules(),
+      publishRules: DEFAULT_PUBLISH_RULES,
     },
   },
   ({ toolName, toolInput, parameters }) => {
-    const isShell = toolInGroups(toolName, ['shell']);
-    const isDelegation = toolInGroups(toolName, ['delegation']);
-    if (!isShell && !isDelegation) return;
-
-    const command = commandTextFrom(toolName, toolInput);
-    // For a real shell command, normalize git's global options first. For a delegation
-    // prompt (free text), the intent check runs on the raw text.
-    const shellCommand = normalizeGitOptions(command);
-    for (const [source, reason] of parameters.publishRules) {
-      const pattern = compile(source);
-      if (isShell) {
-        if (pattern.test(shellCommand)) deny(CONFIG_KEY, reason);
-      } else if (hasRealPublishIntent(command, pattern)) {
-        deny(CONFIG_KEY, reason);
-      }
+    if (toolInGroups(toolName, ['shell'])) {
+      checkShellCommand(shellCommandOf(toolInput), parameters);
+    } else if (toolInGroups(toolName, ['delegation'])) {
+      checkDelegationPrompt(delegationPromptOf(toolInput), parameters);
     }
   },
 );

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