create-byan-agent 2.19.2 → 2.20.1

package/src/byan-v2/generation/mantra-audit.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+//
+// mantra-audit — semantic embodiment audit for BYAN personas (Option C, N2).
+//
+// Lives under src/byan-v2/generation/ so it ships with the v2 runtime (the
+// installer copies src/ into the user project) next to the validator and
+// scope-resolver it depends on. Invoke with:
+//   node src/byan-v2/generation/mantra-audit.js prepare <agentFile> [--json]
+//   node src/byan-v2/generation/mantra-audit.js score   <agentFile> <verdicts.json>
+//
+// The pre-commit mantra gate is a fast, deterministic anti-stub FLOOR : it asks
+// "does this persona contain the vocabulary of its domain mantras". That catches
+// empty/zombie files but does NOT measure whether the agent genuinely EMBODIES a
+// mantra. This tool is the deeper, out-of-band layer : it prepares a judgment
+// packet (the applicable mantras + the persona + a rubric) for an LLM judge, then
+// turns the judge's verdicts into an embodiment score. It is deliberately NOT in
+// the commit path : the judgment is semantic (an LLM call), so it runs on demand
+// or in CI, outside the commit path (a non-deterministic check must not block it).
+//
+// verdicts.json : { "<mantraId>": "embodied" | "partial" | "absent", ... }
+
+const fs = require('fs');
+const path = require('path');
+const MantraValidator = require('./mantra-validator');
+const resolver = require('./scope-resolver');
+
+const VERDICT_WEIGHT = { embodied: 1, partial: 0.5, absent: 0 };
+
+function buildPacket(agentFile) {
+  const content = fs.readFileSync(agentFile, 'utf8');
+  const name = path.basename(agentFile).replace(/\.md$/, '');
+  const scopes = resolver.resolveAgentScopes({ name, content });
+  const applicable = new MantraValidator().applicableMantras(scopes);
+  return {
+    agent: name,
+    file: agentFile,
+    scopes,
+    mantras: applicable.map(m => ({
+      id: m.id,
+      title: m.title,
+      description: m.description,
+      scope: m.scope || 'universal',
+      priority: m.priority,
+    })),
+    persona: content,
+  };
+}
+
+function buildPrompt(packet) {
+  const lines = [];
+  lines.push('You are auditing whether a BYAN agent persona EMBODIES its applicable mantras.');
+  lines.push('Judge embodiment, not vocabulary : a mantra is embodied when the persona\'s role,');
+  lines.push('instructions, and red-lines actually enact the principle, even if the exact keyword');
+  lines.push('is absent. For each mantra return one verdict : embodied | partial | absent.');
+  lines.push('');
+  lines.push(`Agent : ${packet.agent}    Scopes : ${packet.scopes.join(', ')}`);
+  lines.push('');
+  lines.push('Applicable mantras :');
+  for (const m of packet.mantras) {
+    lines.push(`- ${m.id} (${m.scope}, ${m.priority}) : ${m.title} -- ${m.description}`);
+  }
+  lines.push('');
+  lines.push('Persona under audit :');
+  lines.push('"""');
+  lines.push(packet.persona.trim());
+  lines.push('"""');
+  lines.push('');
+  lines.push('Return strict JSON mapping every mantra id to its verdict, e.g.');
+  lines.push('{ "IA-16": "embodied", "M37": "partial", "IA-2": "absent" }');
+  return lines.join('\n');
+}
+
+function scoreVerdicts(packet, verdicts) {
+  const ids = packet.mantras.map(m => m.id);
+  let sum = 0;
+  const buckets = { embodied: [], partial: [], absent: [], unjudged: [] };
+  for (const id of ids) {
+    const v = verdicts[id];
+    if (v && Object.prototype.hasOwnProperty.call(VERDICT_WEIGHT, v)) {
+      sum += VERDICT_WEIGHT[v];
+      buckets[v].push(id);
+    } else {
+      buckets.unjudged.push(id);
+    }
+  }
+  const total = ids.length;
+  const embodimentScore = total > 0 ? Math.round((sum / total) * 100) : 0;
+  return {
+    agent: packet.agent,
+    scopes: packet.scopes,
+    total,
+    embodimentScore,
+    embodied: buckets.embodied,
+    partial: buckets.partial,
+    absent: buckets.absent,
+    unjudged: buckets.unjudged,
+  };
+}
+
+function main(argv) {
+  const [cmd, agentFile, arg3] = argv;
+
+  if (!cmd || !agentFile || ['-h', '--help'].includes(cmd)) {
+    process.stdout.write(
+      'Usage :\n' +
+      '  node src/byan-v2/generation/mantra-audit.js prepare <agentFile> [--json]\n' +
+      '  node src/byan-v2/generation/mantra-audit.js score   <agentFile> <verdicts.json>\n'
+    );
+    return cmd ? 0 : 1;
+  }
+
+  if (!fs.existsSync(agentFile)) {
+    process.stderr.write(`Agent file not found : ${agentFile}\n`);
+    return 1;
+  }
+
+  const packet = buildPacket(agentFile);
+
+  if (cmd === 'prepare') {
+    if (arg3 === '--json') {
+      process.stdout.write(JSON.stringify(packet, null, 2) + '\n');
+    } else {
+      process.stdout.write(buildPrompt(packet) + '\n');
+    }
+    return 0;
+  }
+
+  if (cmd === 'score') {
+    if (!arg3 || !fs.existsSync(arg3)) {
+      process.stderr.write('A verdicts JSON file is required : score <agentFile> <verdicts.json>\n');
+      return 1;
+    }
+    const verdicts = JSON.parse(fs.readFileSync(arg3, 'utf8'));
+    const result = scoreVerdicts(packet, verdicts);
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return 0;
+  }
+
+  process.stderr.write(`Unknown command : ${cmd}\n`);
+  return 1;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+module.exports = { buildPacket, buildPrompt, scoreVerdicts, VERDICT_WEIGHT };

package/src/byan-v2/generation/mantra-validator.js

@@ -1,6 +1,10 @@
 const fs = require('fs');
 const path = require('path');
 
+// Score bands, single source of truth (referenced by generateReport + export).
+const PASS_THRESHOLD = 80;
+const WARNING_THRESHOLD = 60;
+
 class MantraValidator {
   constructor(mantrasData = null) {
     if (mantrasData) {
@@ -42,7 +46,28 @@ class MantraValidator {
     return strictIds.length >= 3;
   }
 
-  validate(agentDefinition) {
+  // Normalize a caller-supplied scope (string | string[] | Set | null) into a
+  // Set, or null when no scope was given. Null means legacy all-mantras scoring.
+  _normalizeScope(scope) {
+    if (scope === null || scope === undefined) return null;
+    if (scope instanceof Set) return scope;
+    if (Array.isArray(scope)) return new Set(scope);
+    return new Set([scope]);
+  }
+
+  // A mantra is applicable to a scoped run when it is universal (or unscoped)
+  // or its scope is in the requested set. Behavioral mantras are runtime-
+  // enforced (hooks / fact-check), not declared in a persona file, so they are
+  // excluded from scoped scoring. With no scope (null), every mantra applies.
+  _isApplicable(mantra, scopeSet) {
+    if (scopeSet === null) return true;
+    if (mantra.behavioral === true) return false;
+    const ms = mantra.scope || 'universal';
+    if (ms === 'universal') return true;
+    return scopeSet.has(ms);
+  }
+
+  validate(agentDefinition, options = {}) {
     if (agentDefinition === null || agentDefinition === undefined) {
       throw new Error('Agent definition is required');
     }
@@ -59,8 +84,16 @@ class MantraValidator {
       this.mantras = this.personaMantras;
     }
 
+    // Domain-aware scoring : when the caller passes a scope, only the mantras
+    // applicable to that scope are counted (universal always counts, behavioral
+    // runtime-enforced mantras are excluded). With no scope, every mantra in the
+    // chosen ruleset is scored, byte-identical to the legacy behavior.
+    const scopeSet = this._normalizeScope(options.scope);
+    const applicableMantras = this.mantras.filter(m => this._isApplicable(m, scopeSet));
+
     this.results = {
-      totalMantras: this.mantras.length,
+      totalMantras: applicableMantras.length,
+      scope: scopeSet ? [...scopeSet] : null,
       compliant: [],
       nonCompliant: [],
       warnings: [],
@@ -70,7 +103,7 @@ class MantraValidator {
 
     const startTime = Date.now();
 
-    for (const mantra of this.mantras) {
+    for (const mantra of applicableMantras) {
       const result = this.checkMantra(mantra.id, agentDefinition);
       
       if (result.compliant) {
@@ -154,8 +187,17 @@ class MantraValidator {
 
   _validatePattern(content, validation, mantra) {
     try {
+      // Some forbidden-pattern mantras (e.g. IA-23 no-emoji) must ignore
+      // declared zones such as an agent's icon="..." frontmatter attribute,
+      // where an emoji is a legitimate display glyph, not pollution.
+      let scanContent = content;
+      if (Array.isArray(validation.ignoreZones)) {
+        for (const zone of validation.ignoreZones) {
+          scanContent = scanContent.replace(new RegExp(zone, 'g'), '');
+        }
+      }
       const regex = new RegExp(validation.pattern, validation.flags || '');
-      const matches = content.match(regex);
+      const matches = scanContent.match(regex);
       const hasMatches = matches && matches.length > 0;
 
       if (validation.mustNotMatch) {
@@ -255,7 +297,7 @@ class MantraValidator {
     }
 
     const score = this.results.score;
-    const level = score >= 80 ? 'PASS' : score >= 60 ? 'WARNING' : 'FAIL';
+    const level = score >= PASS_THRESHOLD ? 'PASS' : score >= WARNING_THRESHOLD ? 'WARNING' : 'FAIL';
 
     let report = '';
     report += '='.repeat(60) + '\n';
@@ -424,7 +466,7 @@ class MantraValidator {
     } else if (format === 'summary') {
       return {
         score: this.results.score,
-        status: this.results.score >= 80 ? 'PASS' : this.results.score >= 60 ? 'WARNING' : 'FAIL',
+        status: this.results.score >= PASS_THRESHOLD ? 'PASS' : this.results.score >= WARNING_THRESHOLD ? 'WARNING' : 'FAIL',
         compliant: this.results.compliant.length,
         nonCompliant: this.results.nonCompliant.length,
         criticalErrors: this.results.errors.length,
@@ -443,6 +485,14 @@ class MantraValidator {
     return this.mantras.filter(m => m.category === category);
   }
 
+  // The mantras that apply to a given scope (universal + the scope's domain,
+  // behavioral excluded). With no scope, every mantra in the current ruleset.
+  // Shared with the domain-aware path in validate() and the embodiment audit.
+  applicableMantras(scope) {
+    const scopeSet = this._normalizeScope(scope);
+    return this.mantras.filter(m => this._isApplicable(m, scopeSet));
+  }
+
   getMantrasByPriority(priority) {
     return this.mantras.filter(m => m.priority === priority);
   }

package/src/byan-v2/generation/scope-resolver.js

@@ -0,0 +1,108 @@
+const fs = require('fs');
+const path = require('path');
+
+// Domain-aware scope resolution for the mantra validator.
+//
+// The validator itself stays pure (it scores against a scope set it is given).
+// This module owns the impure part : turning a persona FILE into its scope set,
+// by reading a centralized map and, where present, an explicit frontmatter
+// override. Callers (the pre-commit gate, the Stop hook, the FD VALIDATE step)
+// resolve scopes here, then pass them to validator.validate(content, { scope }).
+
+const VALID_SCOPES = ['universal', 'sdlc-process', 'sdlc-code', 'sdlc-ops', 'sdlc-modeling', 'sdlc-test', 'creative'];
+const KNOWN_MODULES = ['bmm', 'cis', 'tea', 'bmb', 'core'];
+
+function loadScopeMap(mapPath) {
+  const p = mapPath || path.join(__dirname, '../data/agent-scopes.json');
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+// An explicit `mantra_scopes: [a, b]` in the persona (frontmatter or body) wins
+// over every derived default. Returns the listed scopes, or null when absent.
+function parseFrontmatterScopes(content) {
+  if (typeof content !== 'string') return null;
+  const m = content.match(/mantra_scopes\s*:\s*\[([^\]]*)\]/);
+  if (!m) return null;
+  const list = m[1]
+    .split(',')
+    .map(s => s.trim().replace(/^['"]|['"]$/g, ''))
+    .filter(Boolean);
+  return list.length ? list : null;
+}
+
+// A Gen3 agent loads exactly one _byan/<module>/config.yaml during activation,
+// so the module is derivable from the persona content. Returns null if none.
+function deriveModule(content) {
+  if (typeof content !== 'string') return null;
+  const m = content.match(/_byan\/(bmm|cis|tea|bmb|core)\/config\.yaml/);
+  return m ? m[1] : null;
+}
+
+// The agent slug from a persona file path (basename without extension).
+function agentNameFromPath(filePath) {
+  if (!filePath) return null;
+  return path.basename(filePath).replace(/\.md$/, '');
+}
+
+// Force-union 'universal' and keep only known scope names, order-stable.
+function normalizeScopes(scopes) {
+  const seen = new Set();
+  const out = [];
+  for (const s of ['universal', ...scopes]) {
+    if (VALID_SCOPES.includes(s) && !seen.has(s)) {
+      seen.add(s);
+      out.push(s);
+    }
+  }
+  return out;
+}
+
+// Resolve the scope set for a persona. Precedence :
+//   1. explicit frontmatter mantra_scopes
+//   2. agentScopes[name] in the map
+//   3. moduleScopes[module] derived from the content
+//   4. fallback ['universal']
+// 'universal' is always present in the result.
+function resolveAgentScopes({ name = null, content = null, map = null } = {}) {
+  const scopeMap = map || loadScopeMap();
+
+  // Explicit frontmatter wins ONLY when it names at least one valid scope. An
+  // all-invalid list (e.g. a `sdlc-cod` typo) is treated as absent so we fall
+  // through to the agent/module map instead of silently collapsing to
+  // universal-only, which would weaken the gate the resolver feeds.
+  const explicit = parseFrontmatterScopes(content);
+  if (explicit && explicit.some(s => VALID_SCOPES.includes(s))) {
+    return normalizeScopes(explicit);
+  }
+
+  if (name && scopeMap.agentScopes && scopeMap.agentScopes[name]) {
+    return normalizeScopes(scopeMap.agentScopes[name]);
+  }
+
+  const mod = deriveModule(content);
+  if (mod && scopeMap.moduleScopes && scopeMap.moduleScopes[mod]) {
+    return normalizeScopes(scopeMap.moduleScopes[mod]);
+  }
+
+  return ['universal'];
+}
+
+// Convenience for file-based callers (the gate, the hooks) : read a persona
+// file from disk and resolve its scopes in one call.
+function resolveScopesForFile(filePath, map = null) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const name = agentNameFromPath(filePath);
+  return resolveAgentScopes({ name, content, map });
+}
+
+module.exports = {
+  VALID_SCOPES,
+  KNOWN_MODULES,
+  loadScopeMap,
+  parseFrontmatterScopes,
+  deriveModule,
+  agentNameFromPath,
+  normalizeScopes,
+  resolveAgentScopes,
+  resolveScopesForFile,
+};

package/src/byan-v2/generation/templates/default-agent.md

@@ -16,7 +16,7 @@ You must fully embody this agent's persona and follow all activation instruction
   <rules>
     <r>Communicate in {communication_language}</r>
     <r>Stay in character until EXIT</r>
-    <r>Apply Merise Agile + TDD + 64 mantras</r>
+    <r>Apply Merise Agile + TDD + 71 mantras</r>
   </rules>
 </activation>
 

package/src/byan-v2/index.js

@@ -144,15 +144,24 @@ class ByanV2 {
     if (bmadConfig.voice_integration?.enabled !== false) {
       this.voiceIntegration = new VoiceIntegration(this.sessionState, this.logger);
       
-      // Initialize asynchronously (non-blocking)
+      // Initialize asynchronously (non-blocking). This runs detached from the
+      // constructor, so any throw here would surface as an unhandled rejection
+      // and crash the process. The handlers are wrapped so a non-fatal voice
+      // init (or a partial injected logger) can never escalate to a crash.
       this.voiceIntegration.initialize().then(success => {
-        if (success) {
-          this.logger.info('[ByanV2] Voice integration enabled');
-        } else {
-          this.logger.debug('[ByanV2] Voice integration not available');
-        }
+        try {
+          if (success) {
+            this.logger.info('[ByanV2] Voice integration enabled');
+          } else if (typeof this.logger.debug === 'function') {
+            this.logger.debug('[ByanV2] Voice integration not available');
+          }
+        } catch (_) { /* logging is best-effort; never crash on it */ }
       }).catch(error => {
-        this.logger.warn('[ByanV2] Voice integration init failed', { error: error.message });
+        try {
+          if (typeof this.logger.warn === 'function') {
+            this.logger.warn('[ByanV2] Voice integration init failed', { error: error.message });
+          }
+        } catch (_) { /* logging is best-effort; never crash on it */ }
       });
     }
 

package/src/byan-v2/integration/voice-integration.js

@@ -7,10 +7,10 @@ const execAsync = promisify(exec);
 
 /**
  * VoiceIntegration - Turbo Whisper voice input integration for BYAN v2
- * 
+ *
  * Enables voice-driven agent interaction through Turbo Whisper transcription.
  * Supports GitHub Copilot CLI, Claude Code, and Codex platforms.
- * 
+ *
  * @version 2.1.0
  * @module integration/voice-integration
  */
@@ -18,6 +18,16 @@ class VoiceIntegration {
   constructor(sessionState, logger) {
     this.sessionState = sessionState;
     this.logger = logger;
+    // Logging is best-effort. The byan-v2 logger contract guarantees only info;
+    // a minimal real Logger lacks debug and injected test mocks may carry only
+    // info. Each level falls back to info, then to a no-op, so voice init can
+    // never crash the process on a partial logger.
+    this.log = {
+      debug: (...a) => { const fn = logger && (logger.debug || logger.info); if (fn) fn.apply(logger, a); },
+      info: (...a) => { if (logger && logger.info) logger.info.apply(logger, a); },
+      warn: (...a) => { const fn = logger && (logger.warn || logger.info); if (fn) fn.apply(logger, a); },
+      error: (...a) => { const fn = logger && (logger.error || logger.info); if (fn) fn.apply(logger, a); },
+    };
     this.enabled = false;
     this.config = null;
     this.serverHealthy = false;
@@ -30,33 +40,33 @@ class VoiceIntegration {
    */
   async initialize() {
     try {
-      this.logger.debug('[VoiceIntegration] Initializing...');
-      
+      this.log.debug('[VoiceIntegration] Initializing...');
+
       const installed = await this.detectInstallation();
       if (!installed) {
-        this.logger.info('[VoiceIntegration] Turbo Whisper not installed');
+        this.log.info('[VoiceIntegration] Turbo Whisper not installed');
         return false;
       }
 
       const configLoaded = await this.loadConfig();
       if (!configLoaded) {
-        this.logger.warn('[VoiceIntegration] Config not found, using defaults');
+        this.log.warn('[VoiceIntegration] Config not found, using defaults');
         return false;
       }
 
       const healthy = await this.checkHealth();
       if (!healthy) {
-        this.logger.warn('[VoiceIntegration] Server not responding');
+        this.log.warn('[VoiceIntegration] Server not responding');
         return false;
       }
 
       this.enabled = true;
-      this.logger.info('[VoiceIntegration] Initialized successfully');
+      this.log.info('[VoiceIntegration] Initialized successfully');
       this.sessionState.set('voice_integration_enabled', true);
-      
+
       return true;
     } catch (error) {
-      this.logger.error('[VoiceIntegration] Initialization failed:', error);
+      this.log.error('[VoiceIntegration] Initialization failed:', error);
       return false;
     }
   }
@@ -69,12 +79,12 @@ class VoiceIntegration {
     try {
       const { stdout } = await execAsync('which turbo-whisper');
       const turboWhisperPath = stdout.trim();
-      
+
       if (turboWhisperPath) {
-        this.logger.debug(`[VoiceIntegration] Found at: ${turboWhisperPath}`);
+        this.log.debug(`[VoiceIntegration] Found at: ${turboWhisperPath}`);
         return true;
       }
-      
+
       return false;
     } catch (error) {
       return false;
@@ -96,8 +106,8 @@ class VoiceIntegration {
 
       const configContent = fs.readFileSync(configPath, 'utf8');
       this.config = JSON.parse(configContent);
-      
-      this.logger.debug('[VoiceIntegration] Config loaded:', {
+
+      this.log.debug('[VoiceIntegration] Config loaded:', {
         api_url: this.config.api_url,
         hotkey: this.config.hotkey,
         claude_integration: this.config.claude_integration
@@ -105,7 +115,7 @@ class VoiceIntegration {
 
       return true;
     } catch (error) {
-      this.logger.error('[VoiceIntegration] Config load failed:', error);
+      this.log.error('[VoiceIntegration] Config load failed:', error);
       return false;
     }
   }
@@ -121,20 +131,20 @@ class VoiceIntegration {
 
     try {
       const apiUrl = this.config.api_url;
-      
+
       if (apiUrl.includes('localhost') || apiUrl.includes('127.0.0.1')) {
         const port = apiUrl.match(/:(\d+)/)?.[1] || '8000';
         const healthUrl = `http://localhost:${port}/health`;
-        
+
         const { stdout } = await execAsync(`curl -s ${healthUrl}`);
-        
+
         // fedirz/faster-whisper-server returns "OK" (string)
         // Other servers may return {"status": "ok"} (object)
         if (stdout.trim() === 'OK') {
           this.serverHealthy = true;
           return true;
         }
-        
+
         try {
           const response = JSON.parse(stdout);
           this.serverHealthy = response.status === 'ok';
@@ -148,7 +158,7 @@ class VoiceIntegration {
       this.serverHealthy = true;
       return true;
     } catch (error) {
-      this.logger.debug('[VoiceIntegration] Health check failed:', error.message);
+      this.log.debug('[VoiceIntegration] Health check failed:', error.message);
       return false;
     }
   }
@@ -171,6 +181,14 @@ class VoiceIntegration {
     };
   }
 
+  /**
+   * Format the hotkey combo for user-facing hints (title-cased, e.g. Ctrl+Shift+Space).
+   * @returns {string}
+   */
+  formatHotkey() {
+    return this.config?.hotkey?.map(k => k.charAt(0).toUpperCase() + k.slice(1)).join('+') || 'Ctrl+Shift+Space';
+  }
+
   /**
    * Suggest voice input for long-form responses
    * @param {string} context - Current interaction context
@@ -190,8 +208,8 @@ class VoiceIntegration {
     ];
 
     if (longFormContexts.some(ctx => context.includes(ctx))) {
-      const hotkey = this.config?.hotkey?.join('+') || 'Ctrl+Shift+Space';
-      return `💡 Voice input available: Press ${hotkey} to speak your response`;
+      const hotkey = this.formatHotkey();
+      return `Voice input available: Press ${hotkey} to speak your response`;
     }
 
     return null;
@@ -271,7 +289,7 @@ class VoiceIntegration {
     ];
 
     if (voiceOptimalQuestions.includes(questionId)) {
-      const hotkey = this.config?.hotkey?.join('+') || 'Ctrl+Shift+Space';
+      const hotkey = this.formatHotkey();
       return `[Voice: ${hotkey}] You can speak your response for faster input`;
     }
 

package/src/byan-v2/observability/logger.js

@@ -134,6 +134,15 @@ class Logger {
     this.logger.warn(message, data);
   }
 
+  /**
+   * Generic debug log
+   * @param {string} message - Log message
+   * @param {Object} data - Additional data
+   */
+  debug(message, data = {}) {
+    this.logger.debug(message, data);
+  }
+
   /**
    * Generic error log
    * @param {string} message - Log message