create-byan-agent 2.19.2 → 2.20.0

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,102 @@
+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();
+
+  const explicit = parseFrontmatterScopes(content);
+  if (explicit) 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>