create-byan-agent 2.44.0 → 2.45.0

package/CHANGELOG.md

@@ -9,6 +9,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.45.0] - 2026-07-15
+
+### Added - Plain-language guard for every agent (Mantra IA-26 "Parler Reel")
+
+- New team-wide rule: agents speak clear, coherent French to the user — no gratuitous
+  English when a French word exists ("redemarrer le conteneur", not "cutoff"), no raw
+  internal jargon (leaf/tier/downgrade/gate/inline/advisory), no misapplied metaphor
+  (you do not "forge" a token). A technical term with no French equivalent (commit,
+  cache, token) is kept but explained once. Test: the reader understands with no
+  dictionary. This is the sibling of IA-23 (no emoji) and applies to ALL agents.
+- Mechanism, in three layers, none of which re-generates an already-shown reply:
+  1. The rule reaches every agent: mantra `IA-26` (`mantras.yaml` + `mantras-sources.md`),
+     `.claude/rules/plain-language.md`, and a pointer in `CLAUDE.md`.
+  2. BYAN's own voice stays fresh: a line in the per-turn reminder
+     (`inject-voice-anchor.js`) + entries in `tao.md` Section 4 (Vocabulaire Interdit).
+  3. A forward net (non-blocking): the Stop hook `plain-language-check.js` spots the
+     known repeat-offenders in the finished reply and writes a one-turn flag under
+     `_byan-output/`; the next-turn reminder reads it, signals it in plain French, and
+     clears it. No blocking, no re-answer — the correction is carried to the next turn
+     (a blocking guard would force a costly regen and the user has already read the slip).
+- Core logic isolated in `.claude/hooks/lib/plain-language.js` (French-aware word
+  boundary so "metier"/"chantier" stay clear of the "tier" match; code spans stripped
+  before scanning). Tests: `.claude/__tests__/plain-language.test.js`. Full suite green
+  (2629 jest). Shipped via `install/templates/`.
+
 ## [2.44.0] - 2026-07-15
 
 ### Changed - Revived the Sonnet middle tier for native-workflow model routing

package/install/templates/.claude/CLAUDE.md

@@ -33,6 +33,7 @@ Voir @.claude/rules/hermes-dispatcher.md pour les commandes Hermes.
 
 - Pas d'emojis dans le code, commits, ou specs techniques (Mantra IA-23)
 - Code auto-documente, commentaires uniquement pour le POURQUOI (Mantra IA-24)
+- Parler reel: francais clair et coherent avec l'utilisateur, zero jargon interne / anglais gratuit (Mantra IA-26, voir @.claude/rules/plain-language.md)
 - Format commits: `type: description` (feat, fix, docs, refactor, test, chore)
 - Simplicite d'abord - Rasoir d'Ockham (Mantra #37)
 - Challenge Before Confirm - Valider avant d'accepter (Mantra IA-16)

package/install/templates/.claude/hooks/inject-voice-anchor.js

@@ -26,6 +26,7 @@
 const fs = require('fs');
 const path = require('path');
 const { buildTaoContext, turnCounterPath } = require('./inject-tao');
+const pl = require('./lib/plain-language');
 
 const ANCHOR = [
   'Voix BYAN (rappel par tour ; tao complet chargé au démarrage de session) :',
@@ -33,6 +34,7 @@ const ANCHOR = [
   '- Challenge avant de confirmer ; questionne les absolus (Mantra IA-16).',
   '- Signatures : "Attends — pourquoi ?", "OK. On construit.", "Ça, c\'est du générique.".',
   '- Zéro emoji. Orienté solution : on cherche la meilleure option, pas le mur.',
+  '- Français réel et cohérent (Mantra IA-26) : pas d\'anglais gratuit (dis "redémarrer le conteneur", pas "cutoff"), pas de jargon interne brut, pas de métaphore collée de travers ("forger" un token).',
 ].join('\n');
 
 const DEFAULT_REFRESH_EVERY = 12;
@@ -77,6 +79,15 @@ function decideAnchor({ turn, every, fullTao }) {
   return { mode: 'anchor', additionalContext: ANCHOR };
 }
 
+// Append a plain-language slip reminder (IA-25) to the injected context when the
+// previous turn tripped the forward net. Pure so it is unit-testable; the fs read
+// + clear stays in the require.main path below. A missing/empty hit list is a
+// no-op, so this never changes the anchor on a clean turn.
+function withSlipReminder(baseContext, hits) {
+  const reminder = pl.formatReminder(hits);
+  return reminder ? `${baseContext}\n${reminder}` : baseContext;
+}
+
 if (require.main === module) {
   const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
   const every = refreshEvery();
@@ -84,9 +95,16 @@ if (require.main === module) {
   writeTurn(projectDir, turn);
   const fullTao = every > 0 && turn % every === 0 ? buildTaoContext(projectDir) : '';
   const { additionalContext } = decideAnchor({ turn, every, fullTao });
+  // Forward net: if the previous turn slipped into jargon, remind now and clear
+  // the flag (one-shot). Read/clear here, formatting stays pure in withSlipReminder.
+  const slipHits = pl.readSlip(projectDir);
+  if (slipHits && slipHits.length) pl.clearSlip(projectDir);
   process.stdout.write(
     JSON.stringify({
-      hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext },
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext: withSlipReminder(additionalContext, slipHits),
+      },
     })
   );
 }
@@ -98,5 +116,6 @@ module.exports = {
   readTurn,
   writeTurn,
   decideAnchor,
+  withSlipReminder,
   DEFAULT_REFRESH_EVERY,
 };

package/install/templates/.claude/hooks/lib/plain-language.js

@@ -0,0 +1,155 @@
+'use strict';
+
+// Plain-language core — the shared, testable heart of the "parler reel" guard
+// (Mantra IA-26). Two jobs, no I/O beyond the slip flag:
+//
+//  1. scanText: find the KNOWN repeat-offender words in an assistant reply and
+//     return each with its plain-French replacement. This is the mechanical net
+//     for words we already know we misuse; the generative rule (the principle in
+//     .claude/rules/plain-language.md + the voice anchor) handles the long tail.
+//  2. slip flag: a tiny file under _byan-output/ that the Stop hook writes when a
+//     reply slipped, and the next-turn voice anchor reads + clears to remind the
+//     agent. NO re-answer, NO blocking — the correction is carried FORWARD to the
+//     next turn, which is the whole point (avoid the costly regen loop).
+
+const fs = require('fs');
+const path = require('path');
+
+// Known repeat-offenders -> plain French. Deliberately conservative: only terms
+// with a clean everyday equivalent and a low false-positive risk once code is
+// stripped. Common technical borrowings that have no French equivalent (commit,
+// cache, token) are NOT here — the rule keeps them, explained once.
+const OFFENDERS = Object.freeze([
+  { term: 'inline', good: 'directement (je le fais moi-meme)' },
+  { term: 'cutoff', good: "l'action reelle (ex: redemarrer, couper)" },
+  { term: 'housekeeping', good: 'rangement / menage du code' },
+  { term: 'downgrade', good: 'retrograder / baisser en gamme' },
+  { term: 'advisory', good: 'signalement non bloquant' },
+  { term: 'wrapper', good: 'enveloppe / surcouche' },
+  { term: 'fallback', good: 'repli / solution de secours' },
+  { term: 'throughput', good: 'debit' },
+  { term: 'overhead', good: 'surcout' },
+  { term: 'gate', good: 'point de controle / porte' },
+  { term: 'leaf', good: 'etape / tache' },
+  { term: 'tier', good: 'niveau / gamme' },
+]);
+
+// A metaphor misuse, not a single word: "forger" applied to a token/jeton.
+// Matched separately so the replacement can name the real verb.
+const METAPHOR_OFFENDERS = Object.freeze([
+  {
+    id: 'forger-token',
+    re: /forg\w*\s+(?:un |une |des |le |les |la )?(?:token|jeton)/i,
+    label: 'forger un token',
+    good: 'generer / creer un token',
+  },
+]);
+
+// A word boundary that treats accented letters as part of a word, so \btier\b
+// style matching does NOT fire inside "metier", "chantier", "quartier"... The
+// native \b is wrong here because JS \w excludes accented chars, splitting French
+// words. This lookbehind/lookahead pair is the correct French-aware boundary.
+const LEFT = '(?<![A-Za-zÀ-ÿ0-9_])';
+const RIGHT = '(?![A-Za-zÀ-ÿ0-9_])';
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function termRegExp(term) {
+  return new RegExp(LEFT + escapeRegExp(term) + RIGHT, 'i');
+}
+
+// Remove fenced code blocks and inline `code` spans before scanning, so quoting a
+// file, flag, or function literally named "tier" / "gate" does not trip the net.
+// Prose is what we police; quoted code is not prose.
+function stripCode(text) {
+  if (typeof text !== 'string' || !text) return '';
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`[^`]*`/g, ' ');
+}
+
+// Find every distinct offender present in the prose. Returns [{ bad, good }].
+function scanText(text) {
+  const prose = stripCode(text);
+  if (!prose) return [];
+  const hits = [];
+  const seen = new Set();
+  for (const { term, good } of OFFENDERS) {
+    if (termRegExp(term).test(prose) && !seen.has(term)) {
+      seen.add(term);
+      hits.push({ bad: term, good });
+    }
+  }
+  for (const m of METAPHOR_OFFENDERS) {
+    if (m.re.test(prose) && !seen.has(m.id)) {
+      seen.add(m.id);
+      hits.push({ bad: m.label, good: m.good });
+    }
+  }
+  return hits;
+}
+
+// A short French reminder, for injection at the NEXT turn. Bounded to a few
+// offenders so the note stays tiny even if a reply slipped many times.
+function formatReminder(hits) {
+  if (!Array.isArray(hits) || hits.length === 0) return '';
+  const shown = hits.slice(0, 6)
+    .map((h) => `"${h.bad}" -> ${h.good}`)
+    .join(' ; ');
+  return [
+    'Rappel langage (IA-26) : au dernier tour tu as glisse du jargon ou de',
+    `l'anglais gratuit -> ${shown}. Reformule en francais reel et coherent ce`,
+    'tour-ci, sans refaire la reponse precedente.',
+  ].join(' ');
+}
+
+// The slip flag lives under _byan-output/ (gitignored), same family as the other
+// hook sidecars. It is a transient one-turn signal, never source of truth.
+function slipPath(projectDir) {
+  return path.join(projectDir, '_byan-output', '.jargon-slip.json');
+}
+
+function writeSlip(projectDir, hits) {
+  try {
+    const p = slipPath(projectDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify({ hits }));
+    return true;
+  } catch {
+    return false; // best-effort: a write failure must never block a turn
+  }
+}
+
+function readSlip(projectDir) {
+  try {
+    const raw = fs.readFileSync(slipPath(projectDir), 'utf8');
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed.hits) ? parsed.hits : [];
+  } catch {
+    return null; // no flag (or unreadable) -> nothing to remind
+  }
+}
+
+function clearSlip(projectDir) {
+  try {
+    fs.rmSync(slipPath(projectDir), { force: true });
+  } catch {
+    // never block
+  }
+}
+
+module.exports = {
+  OFFENDERS,
+  METAPHOR_OFFENDERS,
+  escapeRegExp,
+  termRegExp,
+  stripCode,
+  scanText,
+  formatReminder,
+  slipPath,
+  writeSlip,
+  readSlip,
+  clearSlip,
+};

package/install/templates/.claude/hooks/plain-language-check.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+'use strict';
+
+// Stop hook — the FORWARD net for the "parler reel" rule (Mantra IA-26).
+//
+// It reads the assistant reply that just finished, looks for the known
+// jargon/anglais repeat-offenders, and — if it finds any — writes a one-turn
+// slip flag under _byan-output/. It NEVER blocks the turn: there is no re-answer,
+// no regen. The next-turn voice anchor (inject-voice-anchor.js) reads the flag,
+// reminds the agent in plain French, and clears it. Carrying the correction
+// FORWARD is deliberate: a blocking guard would force a costly regen AND the user
+// has already read the slip anyway (no pre-display hook exists).
+//
+// Always exits 0. A read/scan/write failure degrades to a no-op.
+
+const fs = require('fs');
+const { extractLastAssistantText } = require('./lib/transcript-read');
+const pl = require('./lib/plain-language');
+
+// Testable core: scan the finished reply, flag a slip if any. Returns the hits.
+function detectAndFlag(payload, projectDir) {
+  const text = extractLastAssistantText(payload);
+  const hits = pl.scanText(text);
+  if (hits.length > 0) pl.writeSlip(projectDir, hits);
+  return hits;
+}
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+if (require.main === module) {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  let payload = {};
+  try {
+    const raw = readStdin();
+    if (raw && raw.trim()) payload = JSON.parse(raw);
+  } catch {
+    payload = {};
+  }
+  try {
+    detectAndFlag(payload, projectDir);
+  } catch {
+    // never block end-of-turn
+  }
+  process.stdout.write('{}');
+}
+
+module.exports = { detectAndFlag };

package/install/templates/.claude/rules/plain-language.md

@@ -0,0 +1,73 @@
+# Parler Reel — Langage clair, cohérent, sans jargon (Mantra IA-26)
+
+> L'utilisateur doit te comprendre sans dictionnaire. Un agent qui parle en
+> jargon interne, en anglais gratuit ou en métaphore collée de travers force
+> l'utilisateur à traduire — c'est du travail qu'on lui refile. Cette règle
+> s'applique à TOUS les agents BYAN, comme "zéro emoji" (IA-23).
+
+## Le principe (ce qui fait le vrai travail)
+
+Parle en français réel et cohérent — des mots qu'un humain dit vraiment,
+technique ou pas.
+
+- **Pas d'anglais quand le français existe.** "redémarrer le conteneur", pas
+  "faire un cutoff". "solution de secours", pas "fallback".
+- **Pas de métaphore collée de travers.** On ne "forge" pas des tokens : on les
+  génère, on les crée.
+- **Pas de jargon interne du projet balancé brut** (leaf, tier, downgrade, gate,
+  inline, advisory...) : dis ce que ça FAIT, en clair.
+- **Un terme technique anglais sans équivalent** (commit, cache, token) : tu le
+  gardes, mais tu l'expliques une fois en clair à la première utilisation.
+- **Test simple** : ton responsable technique doit tout comprendre sans
+  dictionnaire.
+
+Le principe est génératif : il te fait CHOISIR le bon mot, y compris pour les
+mots pourris qui ne sont pas dans la liste ci-dessous. La liste n'est qu'un
+rappel des récidivistes connus.
+
+## La liste (récidivistes connus -> mot normal)
+
+| Mot pourri | Dis plutôt |
+|------------|------------|
+| inline | directement (je le fais moi-même) |
+| cutoff | l'action réelle (redémarrer, couper) |
+| housekeeping | rangement / ménage du code |
+| downgrade | rétrograder / baisser en gamme |
+| advisory | signalement non bloquant |
+| wrapper | enveloppe / surcouche |
+| fallback | repli / solution de secours |
+| throughput | débit |
+| overhead | surcoût |
+| gate | point de contrôle / porte |
+| leaf | étape / tâche |
+| tier | niveau / gamme |
+| "forger" un token | générer / créer un token |
+
+## Le mécanisme (comment c'est tenu, sans boucle de réécriture)
+
+Trois couches, aucune ne refait une réponse déjà affichée :
+
+1. **La règle, partout.** Ce fichier + le mantra IA-26 (`mantras.yaml`,
+   `mantras-sources.md`) + un pointeur dans `CLAUDE.md`. Tous les agents en
+   héritent (comme IA-23).
+2. **La voix de BYAN, gardée fraîche.** Une ligne dans le rappel par tour
+   (`.claude/hooks/inject-voice-anchor.js`) + des entrées dans
+   `_byan/agent/byan/tao.md` (Section 4, Vocabulaire Interdit).
+3. **Le filet vers l'avant (sans blocage).** À la fin de chaque réponse, le
+   programme `.claude/hooks/plain-language-check.js` (Stop) repère les
+   récidivistes connus et écrit un drapeau sous `_byan-output/.jargon-slip.json`.
+   Le rappel du tour SUIVANT lit le drapeau, le signale en clair, et l'efface.
+   Pas de réécriture, pas de régénération : la correction est portée au tour
+   d'après. C'est volontaire — un blocage forcerait une régénération coûteuse et
+   l'utilisateur a déjà lu le dérapage de toute façon (aucun contrôle ne
+   s'exécute avant l'affichage).
+
+Le cœur logique est isolé dans `.claude/hooks/lib/plain-language.js` (liste +
+détection + drapeau), testé par `.claude/__tests__/plain-language.test.js`.
+
+## Coût
+
+Le filet ne coûte quasiment rien : le programme qui relit tourne en local, aucun
+appel au modèle. Le rappel ajoute une poignée de mots par tour, du même ordre
+que le rappel de voix déjà présent. Ce n'est PAS une économie de tokens — c'est
+du confort de compréhension pour l'utilisateur, assumé comme tel.

package/install/templates/.claude/settings.json

@@ -82,6 +82,10 @@
             "type": "command",
             "command": "p=\"$CLAUDE_PROJECT_DIR/.claude/hooks/punt-guard.js\"; [ -f \"$p\" ] || exit 0; exec node \"$p\""
           },
+          {
+            "type": "command",
+            "command": "p=\"$CLAUDE_PROJECT_DIR/.claude/hooks/plain-language-check.js\"; [ -f \"$p\" ] || exit 0; exec node \"$p\""
+          },
           {
             "type": "command",
             "command": "p=\"$CLAUDE_PROJECT_DIR/.claude/hooks/drain-advisory.js\"; [ -f \"$p\" ] || exit 0; exec node \"$p\""

package/install/templates/_byan/agent/byan/byan-tao.md

@@ -155,6 +155,18 @@ Exemple : "Attends. Ca touche au noyau. On est jamais assez parano. Qu'est-ce qu
 **Pourquoi :** Faux enthousiasme. BYAN est sincere ou silencieux.
 **Au lieu de ca :** "Oui." ou "C'est ca."
 
+**Interdit :** l'anglais gratuit quand le francais existe ("cutoff", "fallback", "housekeeping", "wrapper", "throughput", "overhead")
+**Pourquoi :** Mantra IA-26 Parler Reel. Le lecteur doit comprendre sans dictionnaire.
+**Au lieu de ca :** le mot francais ("redemarrer le conteneur", "solution de secours", "menage du code", "surcouche", "debit", "surcout")
+
+**Interdit :** le jargon interne du projet balance brut ("leaf", "tier", "downgrade", "gate", "inline", "advisory")
+**Pourquoi :** Mantra IA-26. C'est le vocabulaire de la cuisine interne, pas celui de l'utilisateur.
+**Au lieu de ca :** dis ce que ca FAIT en clair ("etape", "niveau", "baisser en gamme", "point de controle", "directement", "signalement non bloquant")
+
+**Interdit :** la metaphore collee de travers ("forger un token")
+**Pourquoi :** Mantra IA-26. On forge une ame, pas un token.
+**Au lieu de ca :** le verbe reel ("generer un token", "creer un token")
+
 ---
 
 ### Section 5 — Non-dits

package/install/templates/_byan/mcp/byan-mcp-server/server.js

@@ -1004,6 +1004,27 @@ const tools = [
       additionalProperties: false,
     },
   },
+  // Selective RAG retrieval — returns the top-k most relevant knowledge bodies
+  // VERBATIM (never truncated; negations/prohibitions are returned intact).
+  // GET /api/projects/:projectId/knowledge/retrieve?q=...&k=10&tokenBudget=0
+  // Backed by PG FTS (ts_rank) in prod, LIKE-degraded on SQLite (dev/tests).
+  // Use this instead of knowledge_list when you only need a focused subset.
+  {
+    name: 'byan_api_knowledge_retrieve',
+    description:
+      'Retrieve the top-k most relevant knowledge entries for a query using full-text search (PG) or LIKE fallback (SQLite). Returns bodies VERBATIM — negations and prohibitions are never truncated. GET /api/projects/:projectId/knowledge/retrieve?q=...&k=10&tokenBudget=0. RBAC viewer required. projectId and q are required. Requires BYAN_API_TOKEN.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string', description: 'Project id (required — RBAC guard).' },
+        q: { type: 'string', description: 'Search query (required).' },
+        k: { type: 'number', description: 'Max number of results (default 10).' },
+        tokenBudget: { type: 'number', description: 'Total token budget (0 = unlimited).' },
+      },
+      required: ['projectId', 'q'],
+      additionalProperties: false,
+    },
+  },
 
   // ─── Memory ───────────────────────────────────────────────────────────
   // Route: GET /api/projects/:projectId/memory (RBAC viewer)
@@ -1437,6 +1458,7 @@ const REMOTE_SAFE_TOOLS = new Set([
   'byan_api_workflow_runs_get',
   'byan_api_knowledge_list',
   'byan_api_knowledge_get',
+  'byan_api_knowledge_retrieve',
   'byan_api_memory_list',
   'byan_api_memory_search',
   'byan_api_custom_agents_list',
@@ -1982,6 +2004,21 @@ export function createByanServer({ token, remoteOnly = false } = {}) {
       return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
     }
 
+    if (name === 'byan_api_knowledge_retrieve') {
+      requireToken();
+      if (!args.projectId) throw new Error('projectId is required (RBAC: knowledge is project-scoped).');
+      if (!args.q || String(args.q).trim() === '') throw new Error('q (query) is required.');
+      const qs = buildQuery({
+        q: args.q,
+        k: args.k,
+        tokenBudget: args.tokenBudget,
+      });
+      const body = await apiRequest(
+        `/api/projects/${encodeURIComponent(args.projectId)}/knowledge/retrieve${qs}`
+      );
+      return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
+    }
+
     if (name === 'byan_api_memory_list') {
       requireToken();
       if (!args.projectId) throw new Error('projectId is required (RBAC: memory is project-scoped).');

package/install/templates/_byan/workflow/simple/byan/data/mantras.yaml

@@ -262,11 +262,22 @@ agents_ia:
         - "Contraintes légales/business"
         - "TODOs avec ticket"
 
+    - id: "IA-26"
+      name: "Parler Réel"
+      category: "code_quality"
+      description: "Parler en français réel et cohérent à l'utilisateur : pas d'anglais gratuit, pas de jargon interne brut, pas de métaphore collée de travers. Un terme technique sans équivalent est gardé mais expliqué une fois. Le test : le lecteur comprend sans dictionnaire."
+      priority: "critique"
+      forbidden:
+        - "Anglais quand le français existe (cutoff, fallback, housekeeping)"
+        - "Jargon interne balancé brut (leaf, tier, downgrade, gate, inline, advisory)"
+        - "Métaphore collée de travers (forger un token)"
+      rule_file: ".claude/rules/plain-language.md"
+
 metadata:
-  total_mantras: 64
+  total_mantras: 65
   conception_count: 39
-  agents_ia_count: 25
-  version: "1.0.0"
-  last_updated: "2026-02-02"
+  agents_ia_count: 26
+  version: "1.0.1"
+  last_updated: "2026-07-15"
   authors: ["Yan", "Carson"]
   methodology: "Merise Agile + TDD"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.44.0",
+  "version": "2.45.0",
   "description": "BYAN v2.8 - Intelligent AI agent creator with ELO trust system + scientific fact-check + Hermes universal dispatcher + native Claude Code integration (hooks, skills, MCP server). Multi-platform (Claude Code, Codex). Merise Agile + TDD + 71 Mantras. ~54% LLM cost savings.",
   "main": "src/index.js",
   "bin": {