create-byan-agent 2.44.0 → 2.47.0

package/CHANGELOG.md

@@ -9,6 +9,101 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.47.0] - 2026-07-16
+
+### Added - Mandatory agent entry gate (match-or-create), the base of BYAN
+
+- Makes the agent dispatch the front door of every non-conversational task: BYAN +
+  Hermes evaluate which specialist agent fits the need and PROPOSE it ; the user
+  validates (double validation IA + human) ; THEN the workflow runs. No suited
+  agent -> propose an interview to frame the need -> web research on the trade's
+  competencies + best practices -> create the tailored agent -> workflow. The
+  interview is triggered by the ABSENCE of a suited agent, not by task size (a fit
+  routes directly, no ceremony). This closes the gap where a plain task got done
+  inline without any dispatch.
+- F1 `lib/agent-matcher.js` — pure suitability pre-filter: (task text + roster)
+  -> ranked candidates + a {fit | no-fit} verdict. Curated Hermes trigger words
+  (weighted) over a title/role text overlap ; accent-insensitive ; a no-fit is the
+  interview signal. Loader reads the roster from agent-manifest.csv (robust CSV
+  parse). It PROPOSES, it does not decide alone.
+- F2/F3 doctrine `.claude/rules/agent-entry-gate.md` (+ pointer in CLAUDE.md + a
+  section 0 in the byan-byan skill): the rail, the two dispatch layers (agent vs
+  runtime), the proportionality (verify every task, interview only on no-fit), the
+  double validation, and the web-research step in agent creation.
+- F4 reactive net `.claude/hooks/agent-gate-check.js` (+ pure core
+  `lib/agent-gate.js`): a Stop hook that flags a task done directly (files written)
+  with no agent proposal and outside an active FD cycle ; the next-turn voice
+  reminder surfaces it in plain French. Non-blocking (the correction lands next
+  turn) ; exits 0 in every path. Honest ceiling: no pre-display interception, so
+  the rail is doctrine + this net, not a first-turn wall.
+- F5: tests (`test/agent-matcher.test.js` node:test, `.claude/__tests__/agent-gate.test.js`
+  jest). Full MCP suite + jest suite green ; workflow linter OK ; skill bundles
+  re-checked ; zero emoji. Shipped via install/templates (5 files added to the sync
+  manifest). Doc: `.claude/rules/agent-entry-gate.md`.
+
+## [2.46.0] - 2026-07-15
+
+### Added - Intelligent dispatch: Codex/Claude routing + architect-dev loop (option B)
+
+- Route each task to the runtime that is genuinely better for it, on the right
+  model and effort for its complexity, and let an architect (Claude) and a dev
+  (Codex or Claude) exchange turn by turn until the work converges. Layered,
+  ports-and-adapters design so the durable core stays independent of the transport.
+- F1 `lib/dispatch-router.js` — pure routing brain: {nature, complexity} ->
+  {runtime, model, effort}. Runtime table is the cross-checked result (Codex for
+  execution/shell/deploy/devops/browser ; Claude for architecture/refactor/quality/
+  planning ; unknown -> Claude). Complexity picks the Claude model tier via
+  native-tiers (haiku/sonnet/inherit) or the Codex reasoning-effort (low/med/high).
+  Two red lines enforced in code, not left to the caller: Fable is refused
+  (assertNoFable throws) and verification is forced to Claude (a runtime does not
+  grade its own work).
+- F2 `lib/codex-bridge.js` — Codex transport behind a swappable adapter. The
+  shipped codex-exec adapter runs `codex exec` read-only for a unified diff that
+  Claude applies with git apply (Codex writes nothing -> works under a locked-down
+  sandbox e.g. Landlock). Failure is a value (ok:false + reason) so the loop falls
+  back to Claude. codex-mcp is a declared V2 slot (available:false) for the tighter
+  `codex mcp-server` coupling later, with no change to F1/F4.
+- F3 `lib/dispatch-blackboard.js` — the turn-by-turn shared board the agents use to
+  exchange (build/render pure ; JSONL sidecar I/O isolated). The honest substitute
+  for a live peer chat: an orchestrated loop, like a chat server holding the turns.
+- F4 `lib/dispatch-orchestrator.js` — the loop core: routes via F1, runs
+  architect<->dev through the board until convergence, executors injected (Codex vs
+  Claude) so it is fully unit-tested. `.claude/workflows/intelligent-dispatch.js` is
+  the native launch facade for one routed task (design -> implement -> verify ;
+  the verify leaf is a Claude reviewer, not the dev).
+- Enforcement: the Codex auto-delegate config ships DISARMED (absent = off) ;
+  arming stays a per-machine opt-in (`_byan/_config/autodelegate.json`, gitignored).
+  Unit tests: `test/dispatch-router|codex-bridge|dispatch-blackboard|dispatch-orchestrator.test.js`.
+  Also corrected a pre-existing api-tools test drift (byan_api_knowledge_retrieve
+  was registered in server.js but absent from the test's tool list). Full MCP suite
+  green (833 node:test) + jest suite green. Doc: `docs/intelligent-dispatch.md`.
+  Shipped via install/templates (10 files added to the sync manifest).
+
+## [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

@@ -15,6 +15,16 @@ Pour invoquer Hermes, tape: `@hermes` ou demande simplement "quel agent pour [ta
 
 Voir @.claude/rules/hermes-dispatcher.md pour les commandes Hermes.
 
+## Porte d'entree — dispatch d'agent obligatoire (match-or-create)
+
+La base de BYAN : toute tache non-conversationnelle passe d'abord par le dispatch
+d'agent. BYAN + Hermes evaluent quel agent specialiste colle au besoin et le
+PROPOSENT ; l'utilisateur valide (double validation IA + humain), PUIS on lance le
+workflow. Aucun agent adapte -> interview pour cadrer le besoin -> recherche web
+(competences + bonnes pratiques du metier) -> creation de l'agent sur mesure ->
+workflow. Le declencheur de l'interview est l'absence d'un agent adapte, pas la
+taille de la tache. Detail + enforcement : voir @.claude/rules/agent-entry-gate.md
+
 ## Architecture BYAN
 
 ```
@@ -33,6 +43,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/agent-gate-check.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+'use strict';
+
+// Stop hook — the reactive net for BYAN's mandatory agent entry gate (F4).
+//
+// At end of turn it asks: was a task handled DIRECTLY (files written) without any
+// agent proposal and outside an active FD cycle ? If so it writes a one-turn flag
+// under _byan-output/ ; the next-turn voice reminder surfaces it in plain French.
+// It NEVER blocks the turn (the user asked to signal, not trap) — always exits 0.
+//
+// The judgment lives in lib/agent-gate.js (pure) ; this shell only extracts the
+// signals from the transcript + fd-state.
+
+const fs = require('fs');
+const { extractLastAssistantText, extractRecentMessages } = require('./lib/transcript-read');
+const gate = require('./lib/agent-gate');
+
+// detect(payload, projectDir) — testable core. Returns the assessment and writes
+// the flag on a slip.
+function detect(payload, projectDir) {
+  const text = extractLastAssistantText(payload);
+  const messages = extractRecentMessages(payload, 8) || [];
+  const assessment = gate.assessTurn({
+    wroteFiles: gate.hasWriteActivity(messages),
+    proposedAgent: gate.hasProposalMarker(text),
+    fdActive: gate.fdIsActive(projectDir),
+  });
+  if (assessment.slip) gate.writeSlip(projectDir, assessment.reason);
+  return assessment;
+}
+
+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 {
+    detect(payload, projectDir);
+  } catch {
+    // never block end-of-turn
+  }
+  process.stdout.write('{}');
+}
+
+module.exports = { detect };

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

@@ -26,6 +26,8 @@
 const fs = require('fs');
 const path = require('path');
 const { buildTaoContext, turnCounterPath } = require('./inject-tao');
+const pl = require('./lib/plain-language');
+const gate = require('./lib/agent-gate');
 
 const ANCHOR = [
   'Voix BYAN (rappel par tour ; tao complet chargé au démarrage de session) :',
@@ -33,6 +35,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 +80,22 @@ 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;
+}
+
+// Append the agent-gate reminder (F4) when the previous turn did a task directly
+// without proposing an agent. Pure; the fs read + clear stays in require.main.
+function withGateReminder(baseContext, slip) {
+  const reminder = gate.formatReminder(slip);
+  return reminder ? `${baseContext}\n${reminder}` : baseContext;
+}
+
 if (require.main === module) {
   const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
   const every = refreshEvery();
@@ -84,9 +103,21 @@ 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);
+  // Forward net #2 (F4): agent entry-gate slip. Read + clear one-shot.
+  const gateSlip = gate.readSlip(projectDir);
+  if (gateSlip) gate.clearSlip(projectDir);
+  let ctx = withSlipReminder(additionalContext, slipHits);
+  ctx = withGateReminder(ctx, gateSlip);
   process.stdout.write(
     JSON.stringify({
-      hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext },
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext: ctx,
+      },
     })
   );
 }
@@ -98,5 +129,7 @@ module.exports = {
   readTurn,
   writeTurn,
   decideAnchor,
+  withSlipReminder,
+  withGateReminder,
   DEFAULT_REFRESH_EVERY,
 };

package/install/templates/.claude/hooks/lib/agent-gate.js

@@ -0,0 +1,127 @@
+'use strict';
+
+// F4 core — the reactive net for the mandatory agent entry gate.
+//
+// BYAN's philosophy: every non-conversational task passes through Hermes+BYAN
+// PROPOSING a suited agent (or an interview to create one), validated by the
+// user, BEFORE any work. No pre-display hook exists, so this net is post-hoc: at
+// end of turn it detects a task done DIRECTLY (files written) without any agent
+// proposal and without an active FD cycle, writes a one-turn flag, and the
+// next-turn reminder surfaces it. Non-blocking by design (the user asked to
+// "signal", not to trap the turn) — the correction lands on the next turn.
+//
+// Pure: assessTurn + the marker/write detectors take plain inputs. The flag I/O
+// is isolated. The hook shell feeds it transcript + fd-state signals.
+
+const fs = require('fs');
+const path = require('path');
+
+// Text signals that the entry gate WAS engaged this turn (an agent was proposed,
+// an FD phase is being narrated, a specialist was addressed, or the interview /
+// no-fit path was surfaced). Any of these means "not a silent direct-do".
+const PROPOSAL_MARKERS = [
+  '[fd:', '@hermes', 'agent adapte', 'aucun agent', 'je propose', 'proposition d\'agent',
+  'interview', 'byan-hermes-dispatch', 'dispatch d\'agent', 'quel agent',
+];
+
+// Tool names that count as "did real work on the repo" this turn.
+const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
+
+function hasProposalMarker(text) {
+  const t = String(text == null ? '' : text).toLowerCase();
+  return PROPOSAL_MARKERS.some((m) => t.includes(m));
+}
+
+// hasWriteActivity(messages) — true if any recent assistant message carried a
+// tool_use block that writes to the repo. `messages` is an array of
+// { role, content } where content is a string or a block array.
+function hasWriteActivity(messages) {
+  if (!Array.isArray(messages)) return false;
+  for (const m of messages) {
+    if (!m || m.role !== 'assistant' || !Array.isArray(m.content)) continue;
+    for (const block of m.content) {
+      if (block && block.type === 'tool_use' && WRITE_TOOLS.has(block.name)) return true;
+    }
+  }
+  return false;
+}
+
+// assessTurn — the decision. A slip is a task done directly (files written) with
+// no agent proposal AND no active FD cycle. When an FD is engaged, the gate is
+// already in play (DISPATCH is part of it), so it is never a slip.
+function assessTurn({ wroteFiles = false, proposedAgent = false, fdActive = false } = {}) {
+  const slip = Boolean(wroteFiles && !proposedAgent && !fdActive);
+  return {
+    slip,
+    reason: slip
+      ? 'files written directly without an agent proposal and no active FD cycle'
+      : 'ok',
+  };
+}
+
+// --- slip flag (isolated I/O, mirrors the plain-language forward net) ------
+
+function slipPath(projectDir) {
+  return path.join(projectDir, '_byan-output', '.agent-gate-slip.json');
+}
+
+function writeSlip(projectDir, detail) {
+  try {
+    const p = slipPath(projectDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify({ detail: String(detail || '') }));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readSlip(projectDir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(slipPath(projectDir), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function clearSlip(projectDir) {
+  try { fs.rmSync(slipPath(projectDir), { force: true }); } catch { /* never block */ }
+}
+
+// formatReminder — the plain-French note injected next turn. Empty when no slip.
+function formatReminder(slip) {
+  if (!slip) return '';
+  return [
+    'Rappel dispatch (porte d\'entree BYAN) : au dernier tour une tache a ete',
+    'traitee en direct sans proposer d\'agent adapte. La base de BYAN, c\'est de',
+    'passer par Hermes : proposer l\'agent qui colle (ou une interview pour en',
+    'creer un), l\'utilisateur valide, PUIS on lance le travail. Applique-le ce tour-ci.',
+  ].join(' ');
+}
+
+// fdIsActive(projectDir) — reads _byan-output/fd-state.json ; active means a live
+// phase (not COMPLETED / ABORTED / absent). Read-only, best-effort.
+function fdIsActive(projectDir) {
+  try {
+    const state = JSON.parse(fs.readFileSync(path.join(projectDir, '_byan-output', 'fd-state.json'), 'utf8'));
+    const phase = state && state.phase;
+    return Boolean(phase) && phase !== 'COMPLETED' && phase !== 'ABORTED';
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  PROPOSAL_MARKERS,
+  WRITE_TOOLS,
+  hasProposalMarker,
+  hasWriteActivity,
+  assessTurn,
+  slipPath,
+  writeSlip,
+  readSlip,
+  clearSlip,
+  formatReminder,
+  fdIsActive,
+};

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/agent-entry-gate.md

@@ -0,0 +1,83 @@
+# Porte d'entree BYAN — dispatch d'agent obligatoire (match-or-create)
+
+> La base de BYAN : mettre la personne sur des rails pour toute tache ou projet.
+> Avant de faire le travail, on regarde quel agent specialiste colle au besoin.
+> Un agent adapte existe -> on le propose et on lance son workflow. Aucun ne
+> colle -> on interviewe pour cadrer le besoin, on cherche les competences du
+> metier, et on cree l'agent sur mesure. Le dispatch d'agent n'est pas une
+> option : c'est l'entree de tout.
+
+## Le principe
+
+Il y a DEUX dispatch, ne pas les confondre :
+- **Dispatch d'agent (Hermes)** — QUI fait le travail : quel agent BYAN, ou on en
+  cree un. C'est le rail decrit ici.
+- **Dispatch de runtime** — une fois l'agent choisi, sur quel moteur (Codex ou
+  Claude) + modele + effort. C'est la couche du dessous (voir
+  `docs/intelligent-dispatch.md`).
+
+Cette regle porte sur le premier : la porte d'entree.
+
+## Le flux (sur toute tache non-conversationnelle)
+
+```
+demande utilisateur
+  -> BYAN + Hermes evaluent quel agent specialiste colle (matcher F1)
+       AGENT ADAPTE TROUVE
+         -> BYAN le PROPOSE ("je pars sur @dev, tu valides ?")
+         -> l'utilisateur valide (double validation IA + humain)
+         -> on lance le workflow de cet agent (+ dispatch runtime)
+       AUCUN AGENT ADAPTE
+         -> BYAN le dit et propose une interview
+         -> interview : cadrer precisement le besoin de l'agent
+         -> recherche web : competences + bonnes pratiques du metier vise
+         -> creation de l'agent sur mesure
+         -> on lance le workflow
+```
+
+Le declencheur de l'interview, c'est **l'absence d'un agent adapte**, pas la
+taille de la tache. "code un script" -> l'agent dev existe -> workflow direct,
+zero ceremonie. "il me faut un agent art moderne" -> aucun agent -> interview +
+recherche + creation.
+
+## La proportion (pour que le rail ne devienne pas un mur)
+
+Le rail impose de **verifier** la pertinence d'un agent a chaque tache — pas de
+declencher une interview a chaque fois. Agent existant qui colle = on route
+direct. Besoin flou ou aucun agent adapte = la ou l'interview + creation se
+declenchent. La ceremonie est proportionnee au manque, pas systematique.
+
+## La double validation
+
+Le matcher (F1, `_byan/mcp/byan-mcp-server/lib/agent-matcher.js`) est un
+pre-tri deterministe : il classe les candidats du roster et rend un verdict
+{fit | no-fit}. Il PROPOSE, il ne tranche pas seul. BYAN presente la proposition
+en clair ; l'utilisateur valide. IA propose, humain confirme.
+
+## La creation d'agent enrichie (chemin no-fit)
+
+Quand aucun agent ne colle, la creation passe par :
+1. **Interview** — cadrer le besoin (ce que l'agent doit faire, ses lignes
+   rouges, son perimetre). Flux INT / agent-builder existant.
+2. **Recherche web** — avant de generer l'agent, chercher les competences reelles
+   et les bonnes pratiques du metier vise (ex : pour un agent "art moderne",
+   courants, techniques, references). C'est ce qui evite l'agent-zombie generique.
+3. **Generation** — generer l'agent sur mesure a partir de l'interview + la
+   recherche.
+4. **Workflow** — lancer le travail avec le nouvel agent.
+
+## L'enforcement (honnete sur son plafond)
+
+Aucun controle ne s'execute AVANT que la reponse s'affiche (pas de hook de
+pre-affichage cote Claude Code). Le rail tient donc par deux forces, pas par un
+mur beton au premier tour :
+1. **Doctrine** — cette regle + le skill byan-byan + `CLAUDE.md` font que BYAN
+   lance la proposition d'agent d'office.
+2. **Filet reactif** — `.claude/hooks/agent-gate-check.js` (Stop) repere une tache
+   traitee en direct (fichiers ecrits) sans proposition d'agent et hors cycle FD,
+   pose un drapeau, et le rappel du tour suivant le signale en clair. Non
+   bloquant : la correction est portee au tour d'apres (meme methode que les
+   autres filets BYAN). Coeur teste : `.claude/hooks/lib/agent-gate.js`.
+
+Quand un cycle FD est deja engage, la porte est deja en jeu (la phase DISPATCH en
+fait partie) : le filet ne se declenche pas.