create-byan-agent 2.19.2 → 2.20.1

package/install/templates/.githooks/pre-commit

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
-# BYAN pre-commit hook — enforce mantras score >= 80% on staged agent
-# and skill files. Blocks the commit if any file drops below the
-# threshold so the user can't accidentally push non-compliant artefacts.
+# BYAN pre-commit hook. Three gates run in order:
+#   1. Strict Mode gate  : block if a strict session is engaged but not completed.
+#   2. Native-workflow lint : block if a .claude/workflows/*.js couples to state.
+#   3. Mantra floor      : block if a Gen3 persona source scores below the floor.
 #
 # Install :
 #   git config core.hooksPath .githooks
@@ -9,16 +10,22 @@
 # Bypass (emergency only) :
 #   git commit --no-verify
 #
-# Scope : only files matching
-#   _byan/bmb/agents/*.md, _byan/agents/*.md,
-#   .github/agents/*.md, .claude/skills/*/SKILL.md,
-#   .claude/agents/*.md
-# are validated. Non-agent files are ignored.
+# Mantra gate scope : the canonical Gen3 persona SOURCES
+#   _byan/agent/<name>/<name>.md
+# are validated with DOMAIN-AWARE scoring (each persona is scored only against
+# the mantras applicable to its declared scope, via scope-resolver). Deployed
+# artifacts (.github/agents, .claude/skills, .claude/agents) are derived loader
+# stubs or non-persona procedures; the non-blocking Stop hook (mantra-validate.js)
+# warns on those. THRESHOLD is an anti-stub FLOOR, not a quality bar: it catches
+# near-empty / zombie persona files. Genuine personas score well above it; deep
+# quality is the job of the semantic embodiment audit (src/byan-v2/generation/mantra-audit.js),
+# which runs out-of-band, not at commit time.
 
 set -euo pipefail
 
-THRESHOLD=80
+THRESHOLD=30
 VALIDATOR="src/byan-v2/generation/mantra-validator.js"
+RESOLVER="src/byan-v2/generation/scope-resolver.js"
 
 if ! command -v node >/dev/null 2>&1; then
   echo "[byan pre-commit] node not found, skipping mantra check"
@@ -40,11 +47,27 @@ if [ -f "$STRICT_GATE" ]; then
   fi
 fi
 
+# Native workflow lint — a .claude/workflows/*.js script runs outside the
+# conversation turn where the strict/FD hooks fire, so the surviving net is this
+# gate : a native script must not couple directly to BYAN state internals
+# (import/require lib/fd-state.js or the strict-mode lib). State goes through the
+# byan_fd_* / byan_strict_* MCP tools. No-op if the linter is absent.
+WF_LINT="_byan/mcp/byan-mcp-server/bin/byan-lint-workflows.js"
+if [ -f "$WF_LINT" ]; then
+  if ! node "$WF_LINT" --root "$(git rev-parse --show-toplevel)"; then
+    echo ""
+    echo "Commit blocked : native workflow script couples to BYAN state internals."
+    echo "Use the byan_fd_* / byan_strict_* MCP tools instead of importing lib/fd-state.js."
+    echo "Bypass with 'git commit --no-verify' (emergency only)."
+    exit 1
+  fi
+fi
+
 if [ ! -f "$VALIDATOR" ]; then
   exit 0
 fi
 
-staged=$(git diff --cached --name-only --diff-filter=ACM | grep -E '^(_byan/bmb/agents/.*\.md|_byan/agents/.*\.md|\.github/agents/.*\.md|\.claude/skills/.*SKILL\.md|\.claude/agents/.*\.md)$' || true)
+staged=$(git diff --cached --name-only --diff-filter=ACM | grep -E '^_byan/agent/[^/]+/[^/]+\.md$' || true)
 
 if [ -z "$staged" ]; then
   exit 0
@@ -55,13 +78,23 @@ while IFS= read -r file; do
   [ -z "$file" ] && continue
   [ ! -f "$file" ] && continue
 
+  # Skip dev/test/variant artifacts that are not shipped personas.
+  case "$file" in
+    *test*|*optimized*|*turbo-whisper*) continue ;;
+  esac
+
+  # Domain-aware score : resolve the persona's scope set, then score only the
+  # applicable mantras (universal + the persona's domain, behavioral excluded).
   score=$(node -e "
     const V = require('./$VALIDATOR');
+    const R = require('./$RESOLVER');
     const fs = require('fs');
+    const path = require('path');
     try {
       const content = fs.readFileSync('$file', 'utf8');
-      const v = new V();
-      const res = v.validate(content);
+      const name = path.basename('$file').replace(/\\.md\$/, '');
+      const scopes = R.resolveAgentScopes({ name, content });
+      const res = new V().validate(content, { scope: scopes });
       const pct = Math.round((res.compliant.length / res.totalMantras) * 100);
       process.stdout.write(String(pct));
     } catch (e) {
@@ -75,15 +108,16 @@ while IFS= read -r file; do
   fi
 
   if [ "$score" -lt "$THRESHOLD" ]; then
-    echo "[byan pre-commit] FAIL $file : mantra score $score% < $THRESHOLD%"
+    echo "[byan pre-commit] FAIL $file : mantra score $score% < $THRESHOLD% (anti-stub floor)"
     failed=1
   fi
 done <<< "$staged"
 
 if [ "$failed" -eq 1 ]; then
   echo ""
-  echo "Commit blocked by BYAN mantra pre-commit hook."
-  echo "Fix the flagged files above, or bypass with 'git commit --no-verify' (emergency only)."
+  echo "Commit blocked by BYAN mantra pre-commit floor."
+  echo "The flagged persona scores below the anti-stub floor : flesh it out, or bypass"
+  echo "with 'git commit --no-verify' (emergency only)."
   exit 1
 fi
 

package/install/templates/.mcp.json.tmpl

@@ -4,8 +4,7 @@
       "command": "node",
       "args": ["{{PROJECT_ROOT}}/_byan/mcp/byan-mcp-server/server.js"],
       "env": {
-        "BYAN_API_URL": "http://localhost:3737",
-        "BYAN_API_TOKEN": ""
+        "BYAN_API_URL": "http://localhost:3737"
       }
     }
   }

package/install/templates/_byan/config.yaml

@@ -58,15 +58,25 @@ bmad_features:
     validate_at_phase_end: true
     auto_summarize: true
   
-  # MantraValidator: Validate agents against 64 mantras
+  # MantraValidator: Validate agents against 71 mantras
   mantras:
     validate: true
-    min_score: 80
+    # Domain-aware anti-stub floor for the pre-commit gate and Stop hook. Each
+    # persona is scored only against its applicable mantras (universal + its
+    # declared scope) via src/byan-v2/generation/scope-resolver.js. This is a
+    # floor that catches empty / zombie personas, not a deep quality bar; deep
+    # embodiment is the out-of-band audit (src/byan-v2/generation/mantra-audit.js).
+    min_score: 30
     enforce_on_generation: true
     fail_on_low_score: false  # If true, fails generation on low score
-    categories:
-      - merise-agile
-      - ia
+    # Mantra scopes (revived from the former dead `categories` list). The
+    # per-agent scope map lives in src/byan-v2/data/agent-scopes.json.
+    scopes:
+      - universal
+      - sdlc-process
+      - sdlc-code
+      - sdlc-modeling
+      - sdlc-test
 
   # VoiceIntegration: Turbo Whisper voice input for hands-free interaction
   voice_integration:

package/install/templates/_byan/mcp/byan-mcp-server/bin/byan-build-workflows.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { buildWorkflowsRegistry } from '../lib/workflows-generator.js';
+
+// Regenerate .claude/workflows/INDEX.md from the workflow manifest.
+// Usage: node bin/byan-build-workflows.js [--root <dir>]
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--root') args.projectRoot = argv[++i];
+  }
+  return args;
+}
+
+const r = buildWorkflowsRegistry(parseArgs(process.argv));
+const c = r.counts;
+process.stdout.write(
+  `[byan-build-workflows] ${r.written ? 'wrote' : 'unchanged'} ${r.path} ` +
+    `(autonomous ${c.autonomous}, pipeline ${c.pipeline})\n`
+);

package/install/templates/_byan/mcp/byan-mcp-server/bin/byan-lint-workflows.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { validateContract } from '../lib/workflows-lint.js';
+
+// Validate native workflow scripts under .claude/workflows/ against the full
+// contract (state-coupling + clock/RNG + meta-literal) AND node --check syntax.
+// Exits non-zero on any violation (used by the pre-commit gate).
+// Usage: node bin/byan-lint-workflows.js [--root <dir>]
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--root') args.projectRoot = argv[++i];
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv);
+const root = args.projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const dir = path.join(root, '.claude', 'workflows');
+
+let files = [];
+try {
+  files = fs.readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith('.js'))
+    .map((e) => path.join(dir, e.name));
+} catch (_e) {
+  process.stdout.write('[byan-lint-workflows] no .claude/workflows/ directory - nothing to lint\n');
+  process.exit(0);
+}
+
+let failed = 0;
+for (const file of files) {
+  const violations = validateContract(fs.readFileSync(file, 'utf8'));
+
+  // Syntax gate: a native script must parse.
+  try {
+    execFileSync('node', ['--check', file], { stdio: 'pipe' });
+  } catch (e) {
+    violations.push({ id: 'node-check', msg: `node --check failed: ${String(e.stderr || e.message).split('\n')[0]}` });
+  }
+
+  if (violations.length) {
+    failed += 1;
+    for (const v of violations) {
+      process.stderr.write(`[byan-lint-workflows] ${file}: ${v.id} - ${v.msg}\n`);
+    }
+  }
+}
+
+if (failed === 0) {
+  process.stdout.write(`[byan-lint-workflows] OK - ${files.length} native workflows pass the contract (state, clock/RNG, meta, node --check)\n`);
+  process.exit(0);
+}
+process.exit(1);

package/install/templates/_byan/mcp/byan-mcp-server/lib/native-loop.js

@@ -0,0 +1,39 @@
+// Pure, tested helpers for native-workflow RGR (red-green-refactor) loops.
+//
+// The in-CLI Workflow runtime sandbox forbids import/require/fs INSIDE a
+// .claude/workflows/*.js script, so a native script MUST inline these tiny
+// functions verbatim. This module is the canonical, unit-tested reference; the
+// inlined copies in scripts must mirror it. Keeping the logic here (and tested)
+// is what lets the doc-only "3 consecutive failures -> HALT" rule become a real,
+// verifiable JS counter.
+
+export const DEFAULT_MAX_CYCLES = 3;
+
+// Decide whether the RGR loop must stop.
+//   green=true                 -> done, not aborted (story task is green)
+//   not green, cycles >= cap   -> done, aborted (no convergence; hard exit)
+//   otherwise                  -> keep looping
+// Returns { done, abort, reason }.
+export function convergenceGuard({ cycles, green, maxCycles = DEFAULT_MAX_CYCLES }) {
+  if (green) return { done: true, abort: false, reason: 'green' };
+  if (cycles >= maxCycles) {
+    return { done: true, abort: true, reason: `no convergence after ${maxCycles} cycles` };
+  }
+  return { done: false, abort: false, reason: 'continue' };
+}
+
+// Structured verdict a native dev-story run returns to the orchestrating skill
+// for the human gate. Pure constructor — no side effects, no state mutation.
+export function buildVerdict({ storyKey, green, cycles, blocking = [], maxCycles = DEFAULT_MAX_CYCLES }) {
+  const aborted = !green && cycles >= maxCycles;
+  return {
+    workflow: 'dev-story',
+    storyKey: storyKey || null,
+    status: green ? 'review-ready' : aborted ? 'aborted-no-convergence' : 'in-progress',
+    green: Boolean(green),
+    cycles,
+    maxCycles,
+    blocking: Array.isArray(blocking) ? blocking : [],
+    needsHumanGate: true,
+  };
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/workflows-generator.js

@@ -0,0 +1,149 @@
+// BYAN native-workflow registry generator + dual-path resolver.
+//
+// Phase 1 of the native-workflow bridge: BYAN's markdown/YAML workflows are
+// LLM-interpreted and human-gated; Claude Code's in-CLI Workflow tool runs a
+// deterministic JS script with no in-run human gate. Only the workflows whose
+// steps run WITHOUT a per-step human gate (autonomous + deterministic pipeline)
+// can be hosted by the native tool. The gated majority stays markdown by design.
+//
+// This module is the single source of truth for "which workflows are portable"
+// and "where does a workflow physically live" (dual-path: native .js preferred,
+// markdown fallback). It is manifest-driven and deterministic so regeneration is
+// idempotent (writeIfChanged). It mirrors the index-generator pattern and reuses
+// its CSV loader — no duplicate parser.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadManifests } from './index-generator.js';
+
+function resolveRoot(projectRoot) {
+  return projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+// Portable buckets, derived from the read-based classification of the 45-row
+// manifest (see docs/native-workflows-contract.md). Membership is data, not a
+// guess: each name must also exist in the manifest or it is surfaced as drift.
+export const PORTABLE = {
+  autonomous: [
+    'dev-story',
+    'create-story',
+    'qa-automate',
+    'testarch-atdd',
+    'testarch-automate',
+    'testarch-ci',
+    'testarch-framework',
+    'testarch-nfr',
+    'testarch-test-design',
+    'testarch-test-review',
+    'testarch-trace',
+  ],
+  pipeline: [
+    'sprint-planning',
+    'code-review',
+    'document-project',
+    'check-implementation-readiness',
+    'quick-dev',
+    'create-excalidraw-diagram',
+    'create-excalidraw-dataflow',
+    'create-excalidraw-flowchart',
+    'create-excalidraw-wireframe',
+  ],
+};
+
+// Bucket of a workflow name. 'gated' = stays LLM-interpreted markdown.
+export function classify(name) {
+  if (PORTABLE.autonomous.includes(name)) return 'autonomous';
+  if (PORTABLE.pipeline.includes(name)) return 'pipeline';
+  return 'gated';
+}
+
+function nativeRel(name) {
+  return `.claude/workflows/${name}.js`;
+}
+
+// Dual-path resolver. Prefers the native script .claude/workflows/<name>.js if
+// it exists, else falls back to the markdown workflow path from the manifest.
+// Pure existence check, no side effects. Returns {name, kind, rel, path} or null.
+export function resolveWorkflow(name, { projectRoot, workflows } = {}) {
+  const root = resolveRoot(projectRoot);
+  const nativeAbs = path.join(root, '.claude', 'workflows', `${name}.js`);
+  if (fs.existsSync(nativeAbs)) {
+    return { name, kind: 'native', rel: nativeRel(name), path: nativeAbs };
+  }
+  const rows = workflows || loadManifests(root).workflows;
+  const row = rows.find((w) => w.name === name);
+  if (row && row.path) {
+    return { name, kind: 'markdown', rel: row.path, path: path.join(root, row.path) };
+  }
+  return null;
+}
+
+// Render the human/agent-readable registry of portable workflows. Deterministic:
+// sorted, no timestamp. native/markdown status reflects which .js exist on disk.
+export function renderRegistry({ workflows = [], projectRoot } = {}) {
+  const root = resolveRoot(projectRoot);
+  const byName = new Map(workflows.map((w) => [w.name, w]));
+  const lines = [];
+  lines.push('# BYAN Native Workflows');
+  lines.push('');
+  lines.push("> Registre des workflows portables vers l'outil Workflow natif de Claude Code.");
+  lines.push('> Genere automatiquement — ne pas editer a la main. Source : `_byan/_config/workflow-manifest.csv`.');
+  lines.push('> Regenerer : `node _byan/mcp/byan-mcp-server/bin/byan-build-workflows.js`.');
+  lines.push('>');
+  lines.push("> Resolution dual-path : le skill prefere `.claude/workflows/<name>.js` s'il existe,");
+  lines.push('> sinon il retombe sur le workflow markdown du manifest. Les workflows gated (a gate');
+  lines.push('> humain par etape) restent markdown interprete — ils ne sont pas portables.');
+  lines.push('');
+
+  for (const bucket of ['autonomous', 'pipeline']) {
+    const names = PORTABLE[bucket].filter((n) => byName.has(n)).slice().sort();
+    lines.push(`## ${bucket} (${names.length})`);
+    lines.push('');
+    for (const name of names) {
+      const nativeAbs = path.join(root, '.claude', 'workflows', `${name}.js`);
+      const status = fs.existsSync(nativeAbs) ? 'native' : 'markdown';
+      const src = byName.get(name).path || '';
+      lines.push(`- \`${name}\` — ${status} — source \`${src}\``);
+    }
+    lines.push('');
+  }
+
+  // Drift guard: a portable name absent from the manifest is a real problem
+  // (renamed/removed upstream). Surface it instead of silently dropping it.
+  const declared = [...PORTABLE.autonomous, ...PORTABLE.pipeline];
+  const missing = declared.filter((n) => !byName.has(n)).slice().sort();
+  if (missing.length) {
+    lines.push('## drift (noms portables absents du manifest)');
+    lines.push('');
+    for (const n of missing) lines.push(`- \`${n}\``);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function writeIfChanged(filePath, content) {
+  const prev = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null;
+  if (prev === content) return false;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+  return true;
+}
+
+// Build (or refresh) .claude/workflows/INDEX.md from the manifest. Idempotent.
+export function buildWorkflowsRegistry({ projectRoot } = {}) {
+  const root = resolveRoot(projectRoot);
+  const { workflows } = loadManifests(root);
+  const content = renderRegistry({ workflows, projectRoot: root });
+  const indexPath = path.join(root, '.claude', 'workflows', 'INDEX.md');
+  const written = writeIfChanged(indexPath, content);
+  const inManifest = (n) => workflows.some((w) => w.name === n);
+  return {
+    written,
+    path: indexPath,
+    counts: {
+      autonomous: PORTABLE.autonomous.filter(inManifest).length,
+      pipeline: PORTABLE.pipeline.filter(inManifest).length,
+    },
+  };
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/workflows-lint.js

@@ -0,0 +1,113 @@
+// Linter for native workflow scripts (enforcement-bridge F3).
+//
+// A .claude/workflows/*.js runs OUTSIDE the conversation turn, so BYAN's
+// main-thread hooks (strict-scope-guard, strict-stop-guard, fd-phase-guard) do
+// not fire for it. The structural net that survives is this lint + the
+// pre-commit gate: a native script must NOT couple directly to BYAN state
+// internals. State goes through the byan_fd_* / byan_strict_* MCP tools.
+//
+// Forbidden: importing/requiring lib/fd-state.js (or the strict-mode lib).
+// Comments are stripped before matching so the contract comment in a script
+// that NAMES fd-state.js (to explain the rule) does not self-trip.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Strip /* block */ and // line comments. Preserve "://" inside strings (URLs)
+// by only treating // as a comment when not preceded by a colon.
+export function stripComments(src) {
+  let s = String(src).replace(/\/\*[\s\S]*?\*\//g, '');
+  s = s.replace(/(^|[^:])\/\/[^\n]*/g, '$1');
+  return s;
+}
+
+const RULES = [
+  {
+    id: 'import-fd-state',
+    re: /\bimport\b[^\n;]*?from\s*['"][^'"]*fd-state[^'"]*['"]/,
+    msg: 'import of fd-state is forbidden; mutate FD state via the byan_fd_* MCP tools',
+  },
+  {
+    id: 'require-fd-state',
+    re: /\brequire\s*\(\s*['"][^'"]*fd-state[^'"]*['"]\s*\)/,
+    msg: 'require of fd-state is forbidden; mutate FD state via the byan_fd_* MCP tools',
+  },
+  {
+    id: 'dynamic-import-fd-state',
+    re: /\bimport\s*\(\s*['"][^'"]*fd-state[^'"]*['"]\s*\)/,
+    msg: 'dynamic import of fd-state is forbidden; mutate FD state via the byan_fd_* MCP tools',
+  },
+  {
+    id: 'import-strict-mode-lib',
+    re: /\b(?:import\b[^\n;]*?from\s*|require\s*\(\s*|import\s*\(\s*)['"][^'"]*lib\/strict-mode[^'"]*['"]/,
+    msg: 'import of the strict-mode lib is forbidden; use the byan_strict_* MCP tools',
+  },
+];
+
+// Lint one script's source for state coupling. Comment-stripped so a contract
+// comment that NAMES fd-state does not self-trip. Returns [{ id, msg }].
+export function lintSource(src) {
+  const code = stripComments(src);
+  const out = [];
+  for (const rule of RULES) {
+    if (rule.re.test(code)) out.push({ id: rule.id, msg: rule.msg });
+  }
+  return out;
+}
+
+// Wall-clock / RNG primitives break the Workflow runtime's resume (the launch
+// validator rejects them). It scans the RAW text, so a token in a COMMENT or a
+// string literal breaks invocation just the same - we therefore check the raw
+// source, NOT the comment-stripped one. This is the exact failure that a manual
+// review caught while porting; mechanizing it here keeps it from recurring.
+const CLOCK_RNG_RE = /Date\.now|Math\.random|new Date/;
+
+export function clockRngViolations(src) {
+  const m = String(src).match(CLOCK_RNG_RE);
+  if (!m) return [];
+  return [{
+    id: 'clock-or-rng',
+    msg: `wall-clock/RNG token "${m[0]}" is forbidden anywhere in a native workflow (breaks resume; the launch validator scans raw text - even comments and strings). Pass timestamps/ids via args.`,
+  }];
+}
+
+// A native workflow script must start with a pure `export const meta = {` literal
+// (after an optional shebang and blank lines). Otherwise the launch validator
+// rejects it.
+export function metaLiteralViolations(src) {
+  const body = String(src).replace(/^/, '');
+  const firstReal = body
+    .split('\n')
+    .map((l) => l.trim())
+    .find((l) => l.length > 0 && !l.startsWith('#!'));
+  if (firstReal && /^export const meta\s*=\s*\{/.test(firstReal)) return [];
+  return [{
+    id: 'meta-literal-first',
+    msg: 'a native workflow script must begin with `export const meta = {` (pure literal) after an optional shebang',
+  }];
+}
+
+// Full native-workflow contract: state-coupling (comment-stripped) + clock/RNG
+// (raw) + meta-literal-first. Returns the combined [{ id, msg }] violations.
+export function validateContract(src) {
+  return [...lintSource(src), ...clockRngViolations(src), ...metaLiteralViolations(src)];
+}
+
+// Lint every *.js in a directory (non-recursive; native workflows are flat)
+// against the FULL contract. Returns [{ file, violations }] for offending files.
+export function lintWorkflowsDir(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (_e) {
+    return [];
+  }
+  const results = [];
+  for (const e of entries) {
+    if (!e.isFile() || !e.name.endsWith('.js')) continue;
+    const file = path.join(dir, e.name);
+    const violations = validateContract(fs.readFileSync(file, 'utf8'));
+    if (violations.length) results.push({ file, violations });
+  }
+  return results;
+}

package/install/templates/_byan/workflow/simple/byan/feature-workflow.md

@@ -27,7 +27,7 @@ INIT
   → DISPATCH     (Worker: EconomicDispatcher — quelle brique BYAN ?)
   → BUILD        (Agent ou Worker selon complexité)
   → REVIEW       (Agent: Quinn — pre-flight humain vs critères VALIDATE)
-  → VALIDATE     (MantraValidator + tests — score ≥ 80%)
+  → VALIDATE     (MantraValidator domain-aware + tests — score ≥ 30 floor anti-stub)
        ├─ OK   → DOC       (Agent: Paige — documenter ce qui a été livré)
        └─ KO   → REFACTOR  (boucle vers BUILD avec correctifs ciblés)
   → COMPLETED
@@ -105,13 +105,16 @@ INIT
 **Qui :** Worker — EconomicDispatcher logic
 **Rôle :** Pour chaque feature du backlog, déterminer quelle brique BYAN est impliquée.
 
-**Matrice de dispatch :**
+**Matrice de dispatch** (source de vérité : `byan_dispatch` MCP / `_byan/mcp/byan-mcp-server/lib/dispatch.js`) :
 
-| Score complexité | Type | Exemples |
-|-----------------|------|---------|
-| < 30 | Worker (existant ou nouveau) | Format, recherche, liste |
-| 30–60 | Agent Sonnet (existant ou nouveau) | Implémentation, création |
-| ≥ 60 | Agent Opus (existant ou nouveau) | Architecture, stratégie, analyse |
+| Score complexité | Route | Stratégie |
+|------------------|-------|-----------|
+| < 15 | `main-thread` | Inline dans le contexte courant, zéro overhead de délégation |
+| < 40 + parallélisable | `agent-subagent-worktree` | Agent tool Claude Code avec isolation worktree |
+| < 40 séquentiel | `mcp-worker-haiku` | Worker Haiku léger via MCP |
+| ≥ 40 | `main-thread-opus` | Garde en main thread, raisonnement Opus |
+
+> Le score (0-100) est estimé depuis la complexité de la tâche (longueur si absent). Appeler `byan_dispatch` pour le calcul — ne pas réinventer les seuils ici.
 
 **Questions posées pour chaque feature :**
 1. Un **Agent existant** peut-il gérer ça ? (lister les candidats)
@@ -136,7 +139,7 @@ INIT
 
 ## Étape 5 : BUILD
 
-**Qui :** Agent (Sonnet/Opus) ou Worker selon score dispatch
+**Qui :** Agent ou worker selon la route `byan_dispatch` (voir la matrice Étape 4)
 **Rôle :** Implémenter la feature — code, agent, workflow, ou context.
 
 **Règles BUILD :**
@@ -165,7 +168,7 @@ INIT
 **Protocole :**
 1. Charger les critères VALIDATE attendus :
    - Tests prévus pour cette feature (liste TDD de l'étape BUILD)
-   - Score MantraValidator cible (≥ 80%)
+   - Score MantraValidator cible (≥ 30, floor anti-stub domain-aware)
    - Mantras les plus à risque selon le type de changement
 2. Quinn (ou reviewer) inspecte le diff :
    - Lisibilité, nommage, taille des fonctions
@@ -197,13 +200,13 @@ INIT
 
 **Protocole :**
 1. Lancer `npm test` — tous les tests doivent passer (zéro régression)
-2. Score MantraValidator ≥ 80%
+2. Score MantraValidator domain-aware ≥ 30 (floor anti-stub)
 3. Fact-check final sur tout claim absolu introduit dans la doc
 4. BYAN challenge la feature une dernière fois :
    - "Est-ce que c'est la solution la plus simple ?" (mantra #37)
    - "Quelles sont les conséquences non voulues ?" (mantra #39)
 5. **Décision binaire :**
-   - Tests verts ET score ≥ 80% ET fact-check OK → `VALIDATE: OK` → étape DOC
+   - Tests verts ET score ≥ 30 (floor anti-stub) ET fact-check OK → `VALIDATE: OK` → étape DOC
    - Sinon → `VALIDATE: KO` → étape REFACTOR
 
 **Output :** Verdict `{ status: "OK" | "KO", tests, mantra_score, blocking_issues }`