create-byan-agent 2.23.0 → 2.26.0

package/install/templates/.claude/hooks/lib/autobench-runtime.js

@@ -0,0 +1,199 @@
+// Shared runtime helpers for the BYAN Auto-Benchmark Stop hook.
+//
+// Reads one static file :
+//   - .claude/hooks/lib/autobench-config.json : the runtime subset generated
+//     from _byan/_config/autobench.yaml by byan-sync-rules (never_list regexes,
+//     choice_language regexes, marker patterns, escape-hatch paths, banners,
+//     ledger path).
+//
+// Owns the ephemeral session artifacts the Stop hook needs :
+//   - .byan-autobench/off : session escape-hatch flag (touch to disable).
+//   - .byan-autobench/blocked-<turnHash> : the block-once token, written when a
+//     turn is blocked so the regenerated turn is never blocked a second time.
+//   - _byan-output/benchmark-ledger.jsonl : the append-only fire/miss audit.
+//
+// This module is deliberately SEPARATE from strict-runtime.js : the two hook
+// families have different state shapes and lifecycles, and coupling them would
+// make a change to one risk the other.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+function projectRoot() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function readJson(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function configPath() {
+  return path.join(projectRoot(), '.claude', 'hooks', 'lib', 'autobench-config.json');
+}
+
+function loadAutobenchConfig() {
+  return readJson(configPath());
+}
+
+// Session-scoped flag file. Its mere presence disables blocking for the
+// session. The cross-session opt-out lives in the config (escape_hatch.disabled)
+// so it survives across sessions and is regenerated from the YAML.
+function sessionFlagPath() {
+  return path.join(projectRoot(), '.byan-autobench', 'off');
+}
+
+function escapeHatchActive(config) {
+  // Session flag : touch .byan-autobench/off to disable for this session.
+  try {
+    if (fs.existsSync(sessionFlagPath())) return true;
+  } catch {
+    // ignore — fall through to the cross-session check
+  }
+  // Cross-session opt-out, carried in the generated config.
+  const eh = config && config.escape_hatch;
+  if (eh && eh.disabled === true) return true;
+  return false;
+}
+
+// Arming. The Stop hook ships DISARMED (approach C) : it observes and ledgers
+// but never blocks until explicitly armed, so day one is zero noise / latency.
+// Arming is config-only : set enforcement.armed === true in
+// _byan/_config/autobench.yaml and run byan-sync-rules to regenerate the
+// config. There is NO loose flag file — a stray file on disk must not silently
+// arm a machine (the incoherent state the integration audit found). Default : OFF.
+function isArmed(config) {
+  const en = config && config.enforcement;
+  return !!(en && en.armed === true);
+}
+
+function blockDir() {
+  return path.join(projectRoot(), '.byan-autobench');
+}
+
+function blockTokenPath(turnHash) {
+  return path.join(blockDir(), `blocked-${turnHash}`);
+}
+
+function readBlockToken(turnHash) {
+  try {
+    return fs.existsSync(blockTokenPath(turnHash));
+  } catch {
+    return false;
+  }
+}
+
+function writeBlockToken(turnHash) {
+  try {
+    fs.mkdirSync(blockDir(), { recursive: true });
+    // Content is irrelevant — presence is the signal. We still stamp the hash so
+    // a human inspecting .byan-autobench/ can tell which turn was blocked.
+    fs.writeFileSync(blockTokenPath(turnHash), turnHash + '\n');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function ledgerPath(config) {
+  const rel =
+    (config && config.ledger && config.ledger.path) ||
+    path.join('_byan-output', 'benchmark-ledger.jsonl');
+  return path.isAbsolute(rel) ? rel : path.join(projectRoot(), rel);
+}
+
+// Append ONE JSONL line. Best-effort : a failed append never traps the turn.
+// The caller supplies any timestamp/session via the entry so this stays
+// deterministic and unit-testable (no clock read here).
+function appendLedger(entry, config) {
+  try {
+    const p = ledgerPath(config);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.appendFileSync(p, JSON.stringify(entry) + '\n');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Transcript extraction (text + raw content) is shared with the other Stop hooks
+// through transcript-read.js — one canonical reader for the real Stop payload
+// (last_assistant_message + transcript_path JSONL) instead of divergent per-hook
+// copies. extractLastAssistantContent feeds hasChoiceArtifact below.
+const {
+  extractLastAssistantText,
+  extractLastAssistantContent,
+  lastAssistantContentFromTranscriptFile,
+  contentToText,
+} = require('./transcript-read');
+
+// ARTIFACT-primary fork signal : a real choice surfaced through the
+// AskUserQuestion tool (the multiple-choice UI) is unambiguous, unlike prose
+// that merely contains 'or' / 'option'. Keys on the structural tool_use block in
+// the finished turn, NOT on choice-WORDS. The lexical regex stays a last-resort
+// fallback for inline-prose forks that never call the tool. Post-hoc by
+// construction (GH #28273) : the tool_use is read from the finished transcript.
+function hasChoiceArtifact(content) {
+  if (!Array.isArray(content)) return false;
+  return content.some(
+    (b) =>
+      b &&
+      b.type === 'tool_use' &&
+      typeof b.name === 'string' &&
+      /askuserquestion/i.test(b.name)
+  );
+}
+
+// Content-only hash : NO clock, NO RNG. Block-once must be stable across the
+// original turn and its regeneration would only differ if the text differs.
+function turnHash(text) {
+  return crypto.createHash('sha1').update(String(text || '')).digest('hex').slice(0, 16);
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve('');
+    let data = '';
+    process.stdin.on('data', (c) => (data += c));
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', () => resolve(data));
+  });
+}
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+module.exports = {
+  projectRoot,
+  configPath,
+  loadAutobenchConfig,
+  sessionFlagPath,
+  escapeHatchActive,
+  isArmed,
+  blockDir,
+  blockTokenPath,
+  readBlockToken,
+  writeBlockToken,
+  ledgerPath,
+  appendLedger,
+  extractLastAssistantText,
+  extractLastAssistantContent,
+  lastAssistantContentFromTranscriptFile,
+  contentToText,
+  hasChoiceArtifact,
+  turnHash,
+  readStdin,
+  parseJson,
+};

package/install/templates/.claude/hooks/lib/fact-check-core.js

@@ -0,0 +1,69 @@
+/**
+ * fact-check-core — pure detection engine shared by the fact-check hooks.
+ *
+ * No IO, no process exit. The PreToolUse doc gate (fact-check-absolutes.js)
+ * and the Stop conversation nudge (fact-check-claims.js) both consume this so
+ * the absolute-detection logic lives in one place.
+ */
+
+'use strict';
+
+const ABSOLUTES = [
+  /\btoujours\b/i,
+  /\bjamais\b/i,
+  /\bforc[eé]ment\b/i,
+  /\bobviously\b/i,
+  /\balways\b/i,
+  /\bnever\b/i,
+  /\bclearly\b/i,
+  /\bundoubtedly\b/i,
+  /\bfaster than\b/i,
+  /\bbetter than\b/i,
+  /\bplus rapide que\b/i,
+  /\bmeilleur que\b/i,
+];
+
+const SOURCE_MARKERS = [
+  /\bRFC\s*\d+/i,
+  /\bCVE-\d{4}-\d+/i,
+  /https?:\/\//,
+  /\[CLAIM\s+L[1-5]\]/i,
+  /\[FACT\s+USER-VERIFIED/i,
+  /\bsource\s*:/i,
+  /_byan\/knowledge\/sources\.md/,
+];
+
+// Strip content that cannot be a claim :
+//   - fenced code blocks ``` ... ```
+//   - inline backticks `...`
+//   - block quotes (lines starting with >)
+//   - list-of-pattern lines (e.g. "- toujours")
+function stripNonClaimZones(text) {
+  if (!text) return '';
+  return text
+    .replace(/```[\s\S]*?```/g, '')
+    .replace(/`[^`\n]+`/g, '')
+    .replace(/^> .*$/gm, '')
+    .replace(/^[\s-]*['"]?\b(toujours|jamais|forc[eé]ment|obviously|always|never|clearly|undoubtedly)\b['"]?/gim, '');
+}
+
+// Return the first unsourced absolute (with surrounding context) or null when
+// every absolute has a source marker within a +/-240 char window.
+function findUnsourced(text) {
+  if (!text) return null;
+  for (const re of ABSOLUTES) {
+    const match = text.match(re);
+    if (!match) continue;
+    const idx = match.index || 0;
+    const windowStart = Math.max(0, idx - 240);
+    const windowEnd = Math.min(text.length, idx + match[0].length + 240);
+    const ctx = text.slice(windowStart, windowEnd);
+    const hasSource = SOURCE_MARKERS.some((sm) => sm.test(ctx));
+    if (!hasSource) {
+      return { absolute: match[0], context: text.slice(Math.max(0, idx - 80), idx + 80) };
+    }
+  }
+  return null;
+}
+
+module.exports = { ABSOLUTES, SOURCE_MARKERS, stripNonClaimZones, findUnsourced };

package/install/templates/.claude/hooks/lib/failure-detector.js

@@ -10,14 +10,27 @@ const ERROR_PATTERNS = [
   /tool_use_error/i,
 ];
 
-// Tools whose response echoes user-authored or file content (Write/Edit
+// Tools whose response echoes user-authored or stored content (Write/Edit
 // return file paths + content fragments, Read echoes file content
 // verbatim). Pattern match on their response fires false positives when
-// the file content itself contains the literal phrase "internal error"
+// the content itself contains the literal phrase "internal error"
 // (e.g. a doc about errors, a test fixture, a hook that detects errors).
 // For these, only trust the explicit is_error flag.
 const ECHO_TOOLS = new Set(['Write', 'Edit', 'NotebookEdit', 'Read']);
 
+// Two more tool classes echo DATA (not a stderr stream), so content-pattern
+// matching on their response is noise. A genuine failure of either sets is_error
+// (checked before this guard), so we lose no real-failure detection:
+//   - MCP tools (mcp__server__tool): byan_fd_* echoes the FD state (which can
+//     hold user-authored raw_ideas / notes containing the literal phrase),
+//     byan_*_status echoes ledger content, etc.
+//   - Bash: its response is command stdout - diagnostics, log greps, test output
+//     that legitimately surface error-words. A real Bash failure exits non-zero,
+//     which the harness marks as is_error.
+function isEchoHeavy(toolName) {
+  return ECHO_TOOLS.has(toolName) || toolName === 'Bash' || toolName.startsWith('mcp__');
+}
+
 function detectFailure(payload) {
   if (!payload || typeof payload !== 'object') return null;
 
@@ -30,8 +43,9 @@ function detectFailure(payload) {
     }
   }
 
-  // Do not pattern-match on echo-heavy tools — only trust is_error flag.
-  if (ECHO_TOOLS.has(toolName)) {
+  // Do not pattern-match on echo-heavy tools (file-echo + MCP data) — only
+  // trust the is_error flag, checked above.
+  if (isEchoHeavy(toolName)) {
     return null;
   }
 

package/install/templates/.claude/hooks/lib/transcript-read.js

@@ -0,0 +1,137 @@
+// Shared transcript reader for Claude Code Stop hooks.
+//
+// The real Stop-hook payload carries NO inline transcript: the runtime hands a
+// `last_assistant_message` string and a `transcript_path` pointing at a JSONL
+// file. A hook that reads `payload.transcript || payload.messages` (an inline
+// array) extracts nothing in production and silently never fires — the bug this
+// module exists to prevent, in one place instead of four divergent copies.
+//
+// Transcript JSONL shape (one object per line): a turn is
+//   { type: 'user'|'assistant', message: { role, content: string | block[] } }
+// where a block is { type: 'text', text } or { type: 'tool_use', name, input, ... }.
+//
+// Every function is best-effort: an unreadable/short file or a malformed line
+// yields empty/null so a hook never traps a turn it cannot read.
+
+'use strict';
+
+const fs = require('fs');
+
+// Flatten an assistant message content (string or block array) to plain text.
+function contentToText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content.map((c) => (c && typeof c.text === 'string' ? c.text : '')).join(' ');
+  }
+  return '';
+}
+
+// Parse a transcript JSONL file into the array of its message objects
+// ({ type, message:{role, content} }), skipping blank/malformed lines.
+function readTranscriptLines(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const out = [];
+    for (const line of raw.split('\n')) {
+      if (!line || !line.trim()) continue;
+      try {
+        out.push(JSON.parse(line));
+      } catch {
+        // skip a malformed line, keep the rest
+      }
+    }
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+function isAssistantLine(o) {
+  return Boolean((o && o.type === 'assistant') || (o && o.message && o.message.role === 'assistant'));
+}
+
+// The RAW content (string or block array) of the last assistant turn in the
+// file, or null. Used for artifact detection (tool_use blocks survive here).
+function lastAssistantContentFromTranscriptFile(filePath) {
+  const lines = readTranscriptLines(filePath);
+  if (!lines) return null;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const o = lines[i];
+    if (isAssistantLine(o) && o.message && o.message.content != null) return o.message.content;
+  }
+  return null;
+}
+
+// The user/assistant messages from the file as { role, content } objects, in
+// order, or null. Lets a hook reconstruct the last N turns of a conversation.
+function messagesFromTranscriptFile(filePath) {
+  const lines = readTranscriptLines(filePath);
+  if (!lines) return null;
+  const out = [];
+  for (const o of lines) {
+    const m = o && o.message;
+    if (m && (m.role === 'user' || m.role === 'assistant')) {
+      out.push({ role: m.role, content: m.content });
+    }
+  }
+  return out.length ? out : null;
+}
+
+// The RAW content of the finished assistant turn from ANY payload shape: an
+// inline array (test fixtures / legacy) first, then the transcript_path file.
+// last_assistant_message is text-only, so it cannot feed artifact detection and
+// is handled in extractLastAssistantText, not here.
+function extractLastAssistantContent(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+
+  const inline = payload.transcript || payload.messages;
+  if (Array.isArray(inline)) {
+    for (let i = inline.length - 1; i >= 0; i--) {
+      const m = inline[i];
+      if (m && m.role === 'assistant') return m.content;
+    }
+  }
+
+  const tp = payload.transcript_path || payload.transcriptPath;
+  if (typeof tp === 'string') {
+    const content = lastAssistantContentFromTranscriptFile(tp);
+    if (content != null) return content;
+  }
+
+  return null;
+}
+
+// The finished assistant turn as plain text (the primary signal for most hooks).
+// Prefer the runtime-provided last_assistant_message; else derive from content.
+function extractLastAssistantText(payload) {
+  if (!payload || typeof payload !== 'object') return '';
+  if (typeof payload.last_assistant_message === 'string') return payload.last_assistant_message;
+  if (typeof payload.lastAssistantMessage === 'string') return payload.lastAssistantMessage;
+  return contentToText(extractLastAssistantContent(payload));
+}
+
+// The last N user/assistant messages as { role, content }, from any payload
+// shape (inline array or transcript_path file), or null when none are readable.
+function extractRecentMessages(payload, limit) {
+  if (!payload || typeof payload !== 'object') return null;
+  let msgs = payload.transcript || payload.messages;
+  if (!Array.isArray(msgs)) {
+    const tp = payload.transcript_path || payload.transcriptPath;
+    if (typeof tp === 'string') msgs = messagesFromTranscriptFile(tp);
+  }
+  if (!Array.isArray(msgs)) return null;
+  const filtered = msgs.filter((m) => m && (m.role === 'user' || m.role === 'assistant'));
+  if (!filtered.length) return null;
+  return typeof limit === 'number' ? filtered.slice(-limit) : filtered;
+}
+
+module.exports = {
+  contentToText,
+  readTranscriptLines,
+  lastAssistantContentFromTranscriptFile,
+  messagesFromTranscriptFile,
+  extractLastAssistantContent,
+  extractLastAssistantText,
+  extractRecentMessages,
+};

package/install/templates/.claude/hooks/soul-memory-check.js

@@ -3,23 +3,30 @@
  * SessionStart hook — checks soul-memory last-revision and reminds the
  * agent when > 14 days since last introspection.
  *
- * Parses _byan/soul-memory.md looking for "last-revision: YYYY-MM-DD"
- * (common soul-memory protocol). If missing or stale, emits a reminder
- * as additionalContext. Never blocks, always exits 0.
+ * Parses the soul-memory file looking for a "last-revision: YYYY-MM-DD"
+ * marker (tolerant of markdown bold, e.g. "**last-revision:** 2026-02-21").
+ * If missing or stale, emits a reminder as additionalContext so the agent
+ * (not just the user) sees it. Never blocks, always exits 0.
  */
 
 const fs = require('fs');
 const path = require('path');
 
 const STALE_DAYS = 14;
+const SOUL_REVISION_WORKFLOW = '_byan/workflow/simple/byan/soul-revision.md';
 
-const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-// Gen3 _byan/agent/byan/soul-memory.md first, Gen2 _byan/soul-memory.md fallback.
-const memoryGen3 = path.join(projectDir, '_byan', 'agent', 'byan', 'soul-memory.md');
-const memoryPath = fs.existsSync(memoryGen3) ? memoryGen3 : path.join(projectDir, '_byan', 'soul-memory.md');
+function memoryPathFor(projectDir) {
+  // Gen3 _byan/agent/byan/soul-memory.md first, Gen2 _byan/soul-memory.md fallback.
+  const gen3 = path.join(projectDir, '_byan', 'agent', 'byan', 'soul-memory.md');
+  return fs.existsSync(gen3) ? gen3 : path.join(projectDir, '_byan', 'soul-memory.md');
+}
 
 function findLastRevision(content) {
-  const m = content.match(/last[-_ ]revision\s*[:=]\s*(\d{4}-\d{2}-\d{2})/i);
+  // [^\d]{0,8} tolerates markdown punctuation between the label and the date
+  // (e.g. "**last-revision:** 2026-02-21" or "last_revision = 2026-02-21")
+  // while forbidding any digit in the gap, so a stray earlier year cannot be
+  // captured instead of the real date.
+  const m = (content || '').match(/last[-_ ]revision[^\d]{0,8}(\d{4}-\d{2}-\d{2})/i);
   return m ? m[1] : null;
 }
 
@@ -29,26 +36,43 @@ function daysSince(dateStr, now = new Date()) {
   return Math.floor((now - then) / (1000 * 60 * 60 * 24));
 }
 
-let additionalContext = '';
+// Pure reminder builder — returns the additionalContext string (or '').
+function buildReminder(content, memoryRel, now = new Date()) {
+  const last = findLastRevision(content);
+  const age = last ? daysSince(last, now) : null;
+
+  if (last == null) {
+    return `BYAN soul-memory reminder: no last-revision marker found in ${memoryRel}. Consider running the soul-revision workflow (${SOUL_REVISION_WORKFLOW}) early this session.`;
+  }
+  if (age != null && age > STALE_DAYS) {
+    return `BYAN soul-memory reminder: last revision of ${memoryRel} was ${last} (${age} days ago, threshold ${STALE_DAYS}). Per soul-activation protocol, offer to run ${SOUL_REVISION_WORKFLOW} after greeting. User can postpone with "pas maintenant" (+7 days).`;
+  }
+  return '';
+}
 
-try {
-  if (fs.existsSync(memoryPath)) {
-    const content = fs.readFileSync(memoryPath, 'utf8');
-    const last = findLastRevision(content);
-    const age = last ? daysSince(last) : null;
+if (require.main === module) {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const memoryPath = memoryPathFor(projectDir);
+  let additionalContext = '';
 
-    if (last == null) {
-      additionalContext = `BYAN soul-memory reminder: no last-revision marker found in _byan/soul-memory.md. Consider running the soul-revision workflow early this session.`;
-    } else if (age != null && age > STALE_DAYS) {
-      additionalContext = `BYAN soul-memory reminder: last revision was ${last} (${age} days ago, threshold ${STALE_DAYS}). Per soul-activation protocol, offer to run _byan/workflows/byan/soul-revision.md after greeting. User can postpone with "pas maintenant" (+7 days).`;
+  try {
+    if (fs.existsSync(memoryPath)) {
+      const content = fs.readFileSync(memoryPath, 'utf8');
+      additionalContext = buildReminder(content, path.relative(projectDir, memoryPath));
     }
+  } catch {
+    // never block
   }
-} catch {
-  // never block
-}
 
-if (additionalContext) {
-  process.stdout.write(JSON.stringify({ systemMessage: additionalContext }));
-} else {
-  process.stdout.write('{}');
+  if (additionalContext) {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext },
+      })
+    );
+  } else {
+    process.stdout.write('{}');
+  }
 }
+
+module.exports = { findLastRevision, daysSince, buildReminder, memoryPathFor, SOUL_REVISION_WORKFLOW };

package/install/templates/.claude/hooks/soul-memory-triggers.js

@@ -4,19 +4,30 @@
  * signals in the user message and suggests a mid-session soul-memory entry.
  *
  * Non-blocking: never rejects the prompt. Emits a short nudge when a
- * trigger keyword matches. Max one nudge per session is enforced via a
- * file marker under _byan/_memory/.
+ * trigger keyword matches. One nudge per session is enforced via a file
+ * marker; the marker is reset at SessionStart by inject-soul.js so the
+ * one-shot is per-session, not per-lifetime.
+ *
+ * The nudge names the byan_soul_memory_append MCP tool explicitly so the
+ * reflect -> append loop actually closes (the agent knows HOW to persist
+ * the entry, after the user validates it).
  */
 
 const fs = require('fs');
 const path = require('path');
 
 const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
 // State marker lives under the memory dir: Gen3 _byan/memoire/ first, Gen2
-// _byan/_memory/ fallback (whichever dir exists; default Gen2).
-const memoireDir = path.join(projectDir, '_byan', 'memoire');
-const memoryDir = fs.existsSync(memoireDir) ? memoireDir : path.join(projectDir, '_byan', '_memory');
-const markerPath = path.join(memoryDir, '.soul-memory-nudge-sent');
+// _byan/_memory/ fallback (whichever dir exists; default Gen2). MUST resolve
+// identically to inject-soul.js nudgeMarkerPath (it resets this marker at
+// SessionStart) — the soul-hooks parity test pins that invariant.
+function markerPathFor(dir) {
+  const memoireDir = path.join(dir, '_byan', 'memoire');
+  const memoryDir = fs.existsSync(memoireDir) ? memoireDir : path.join(dir, '_byan', '_memory');
+  return path.join(memoryDir, '.soul-memory-nudge-sent');
+}
+const markerPath = markerPathFor(projectDir);
 
 const TRIGGERS = {
   resonance: ['resonne', 'ca me parle', 'exactement', 'c\'est ca', 'that resonates'],
@@ -44,7 +55,13 @@ function findTrigger(text) {
   return null;
 }
 
-(async () => {
+// Build the nudge text. It names the byan_soul_memory_append MCP tool so the
+// reflect -> append loop closes instead of dead-ending at "consider offering".
+function buildNudge(hit) {
+  return `BYAN soul-memory trigger detected (${hit.category}): "${hit.pattern}". Per soul-memory protocol, offer the user a mid-session introspection entry; if they validate it, persist it by calling the byan_soul_memory_append MCP tool (entry = the insight, category = ${hit.category}). One nudge per session, always validated by the user first.`;
+}
+
+if (require.main === module) (async () => {
   let additionalContext = '';
 
   try {
@@ -60,7 +77,7 @@ function findTrigger(text) {
     if (!fs.existsSync(markerPath)) {
       const hit = findTrigger(prompt);
       if (hit) {
-        additionalContext = `BYAN soul-memory trigger detected (${hit.category}): "${hit.pattern}". Per soul-memory protocol, consider offering the user a mid-session introspection entry. Maximum 2 entries per session, always validated by user.`;
+        additionalContext = buildNudge(hit);
         try {
           fs.mkdirSync(path.dirname(markerPath), { recursive: true });
           fs.writeFileSync(markerPath, new Date().toISOString());
@@ -82,3 +99,5 @@ function findTrigger(text) {
     })
   );
 })();
+
+module.exports = { findTrigger, buildNudge, markerPathFor, TRIGGERS };