create-byan-agent 2.25.0 → 2.27.0

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/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 };

package/install/templates/.claude/hooks/stage-to-byan.js

@@ -16,6 +16,9 @@
 
 const fs = require('fs');
 const path = require('path');
+// Shared transcript reader — the real Stop payload has no inline transcript
+// (transcript_path JSONL). Without it extractTurn got null and never staged.
+const { extractRecentMessages } = require('./lib/transcript-read');
 
 const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 
@@ -60,11 +63,24 @@ function readMemorySyncConfig() {
   return null;
 }
 
+// Local opt-in override. Pure. A machine enables staging via BYAN_MEMORY_SYNC=1
+// (in the gitignored .claude/settings.local.json env, or process env) WITHOUT
+// touching _byan/config.yaml — that file is git-tracked + template-mirrored, so
+// a flag there would ship enabled:true to every install and break the
+// install-time consent design.
+function applyEnvEnable(memorySync, env = {}) {
+  if (String(env.BYAN_MEMORY_SYNC || '') === '1') {
+    return { ...memorySync, enabled: true };
+  }
+  return memorySync;
+}
+
 function buildConfig() {
   const settingsEnv = readSettingsEnv();
   const apiUrl = settingsEnv.BYAN_API_URL || process.env.BYAN_API_URL || null;
   const apiToken = settingsEnv.BYAN_API_TOKEN || process.env.BYAN_API_TOKEN || null;
-  const memorySync = readMemorySyncConfig() || {};
+  const mergedEnv = { ...process.env, ...settingsEnv };
+  const memorySync = applyEnvEnable(readMemorySyncConfig() || {}, mergedEnv);
   return {
     byan_api_url: apiUrl,
     byan_api_token: apiToken,
@@ -75,18 +91,18 @@ function buildConfig() {
 function extractTurn(payload) {
   if (!payload || typeof payload !== 'object') return null;
 
-  const transcript = payload.transcript || payload.messages;
-  if (!Array.isArray(transcript)) return null;
+  // Resolve from any payload shape: inline array (fixtures) or transcript_path
+  // JSONL (production). The last 4 user/assistant messages are the staged turn.
+  const messages = extractRecentMessages(payload, 4);
+  if (!messages) return null;
 
   return {
     sessionId: payload.session_id || payload.sessionId || null,
-    messages: transcript
-      .filter((m) => m && (m.role === 'user' || m.role === 'assistant'))
-      .slice(-4),
+    messages,
   };
 }
 
-(async () => {
+if (require.main === module) (async () => {
   const raw = await readStdin();
   let payload = {};
   try {
@@ -119,3 +135,5 @@ function extractTurn(payload) {
   process.stdout.write(JSON.stringify({ continue: true }));
   process.exit(0);
 })();
+
+module.exports = { applyEnvEnable, buildConfig, readMemorySyncConfig };

package/install/templates/.claude/hooks/strict-stop-guard.js

@@ -16,6 +16,10 @@
 
 const { loadConfig, loadState, isEngaged, passCount, lastVerdict, readStdin, parseJson } =
   require('./lib/strict-runtime');
+// Shared transcript reader — the real Stop payload has no inline transcript
+// (last_assistant_message + transcript_path JSONL). Same reader as the other
+// Stop hooks so the completion-claim guard sees the actual finished message.
+const { extractLastAssistantText } = require('./lib/transcript-read');
 
 const DEFAULT_MARKERS = ['done', 'finished', 'complete', 'delivered', 'ready'];
 
@@ -31,22 +35,6 @@ function claimsCompletion(text, markers) {
   });
 }
 
-function extractLastAssistantText(payload) {
-  if (!payload || typeof payload !== 'object') return '';
-  const tx = payload.transcript || payload.messages || [];
-  if (!Array.isArray(tx)) return '';
-  for (let i = tx.length - 1; i >= 0; i--) {
-    const m = tx[i];
-    if (m && m.role === 'assistant') {
-      if (typeof m.content === 'string') return m.content;
-      if (Array.isArray(m.content)) {
-        return m.content.map((c) => (c && c.text ? c.text : '')).join(' ');
-      }
-    }
-  }
-  return '';
-}
-
 // Pure decision : returns { block, reason }.
 function decideStop({ state, config, lastAssistantText }) {
   if (!isEngaged(state)) return { block: false };