create-byan-agent 2.23.0 → 2.25.0

package/CHANGELOG.md

@@ -9,6 +9,81 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.25.0] - 2026-06-09
+
+### Added - Advisory auto-feed (BYAN learns from each session, automatically)
+
+The insight loop observed and proposed; the missing half was the LEARNING. BYAN's
+advisory ledgers (ELO trust, the suitability ledger) updated only when the agent
+remembered to call a record tool. This wires the automatic half — outcomes are
+recorded at end of turn, with no agent action — while behavior surfaces stay
+human-gated.
+
+- **Capture.** The `byan_outcome_log` MCP tool appends one validated advisory
+  outcome to a buffer (cheap; it does not write a ledger directly). kind=elo logs
+  `{domain, result}`; kind=suitability logs `{model, leafId, success}`.
+- **Drain.** `.claude/hooks/drain-advisory.js` is a Stop hook that, at end of each
+  turn, records the buffered outcomes into the ELO ledger (full Glicko update) and
+  the suitability ledger, advancing a line cursor for idempotency. It is strictly
+  non-blocking (all work in try/catch, emits `{continue:true}` and exit 0 on every
+  path) and crosses the ESM/CJS boundary (the CJS ELO engine via require, the ESM
+  suitability store via dynamic import).
+- **Advisory-only.** The loop writes only the buffer and the two advisory ledgers.
+  Behavior surfaces (routing, personas, mantra thresholds) are left untouched —
+  those stay a human decision, consistent with the insight loop's gated philosophy.
+- 71 tests (the pure planners, the buffer, and a drain-hook e2e with ledger
+  snapshot/restore) plus a live smoke test recording a real Glicko update. The tool
+  and hook ship in the template; the hook registers alongside the existing Stop
+  hooks.
+- Explicit follow-ups (out of this scope): the adversarial verdict panel that would
+  feed suitability without a manual log, and a fact-graph-derived ELO source.
+
+## [2.24.0] - 2026-06-09
+
+### Added - Session insight loop (gated self-improvement)
+
+BYAN already has advisory learning surfaces (ELO trust, the suitability ledger)
+and the native Claude Code hooks already leave outcome trails on disk, but the
+loop was open: the agent had to read and act on them by hand. This closes it,
+under a strict gated philosophy.
+
+- **Harvester** `_byan/mcp/byan-mcp-server/lib/insight-harvest.js` +
+  `bin/byan-insight-digest.js` + the `byan_insight_digest` MCP tool: read the
+  native trails (`tool-log.jsonl` health, strict `audit.log` recurring gaps,
+  the suitability ledger routing outcomes, the ELO profile trends) and aggregate
+  them into a digest with conservative, GATED proposals. Pure aggregation +
+  IO-isolated reader, mirroring the template-fidelity pattern.
+- **Gated by design.** The harvester only READS; it writes nothing to a behavior
+  surface (routing, personas, mantra thresholds). Every proposal carries
+  `gated: true` and is surfaced for a human to ratify — an agent that rewrote its
+  own routing on a heuristic would be the silent-downgrade BYAN exists to prevent.
+- **Skill** `byan-insight` presents the digest as a gated improvement proposal
+  (observe, propose, human ratifies), consistent with the advisory ELO /
+  suitability doctrine.
+- **Guard false-positive fix.** `tool-failure-guard` flagged any tool whose result
+  echoed the literal phrase "internal error" as a failure, exempting only
+  Write/Edit/Read. Bash (diagnostic stdout) and MCP tools (echoed stored data) now
+  join the echo-heavy set: their `is_error` flag is trusted, content patterns are
+  not. A genuine failure still sets `is_error`. Caught live (a Bash log-grep
+  blocked the session twice) and covered by unit + e2e tests.
+- 43 harvester unit tests + the detector tests; the e2e guard tests moved their
+  content-pattern cases onto a non-echo tool. The tool and skill ship in the
+  template.
+
+### Changed - Closed the fused-route and output-folder legacy debts
+
+- Removed the dead parallel router `src/core/dispatcher/execution-router.js` (zero
+  live consumers) and its test; the routing docs (`workers.md`,
+  `feature-workflow.md`) and the loadbalancer architecture comment now point only
+  to `byan_dispatch` and its two-axis model (strategy from score, model tier from
+  nature).
+- Standardized the documented output folder from the legacy `_bmad-output/` to the
+  runtime's `_byan-output/` across the agent and platform docs plus an inert config
+  default. Left untouched on purpose: the deliberate back-compat read in
+  `agent-packager.js` (recovers agent creations from older installs under
+  `_bmad-output/bmb-creations`), the migration guides, and the anti-regression
+  tests that assert the old name is gone.
+
 ## [2.23.0] - 2026-06-09
 
 ### Added - Stub path normalizer + a 5th pre-commit gate (no _bmad/@bmad drift)

package/install/src/byan-v2/index.js

@@ -52,7 +52,7 @@ class ByanV2 {
         low: 30,
         medium: 60
       },
-      outputDir: './_bmad-output/bmb-creations',
+      outputDir: './_byan-output/bmb-creations',
       env: customConfig.env || (process.env.GITHUB_COPILOT ? 'copilot' : 'standalone')
     };
 

package/install/templates/.claude/hooks/drain-advisory.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// drain-advisory.js — Stop hook. At the end of each assistant turn, drain the
+// outcome buffer into BYAN's ADVISORY ledgers (ELO trust, suitability). This is the
+// automatic half of the closed learning loop: outcomes logged during the turn (via
+// byan_outcome_log) are recorded with NO agent action. Behavior surfaces (routing /
+// personas / mantras) are never touched — only advisory data is written.
+//
+// STRICTLY non-blocking. All work is wrapped in try/catch; the hook ALWAYS emits
+// {continue:true} and exits 0, and never throws or exits 2. An advisory feed must
+// never break a turn (the stage-to-byan.js contract: "staging must never break the
+// session"). Idempotent via a line cursor, so a re-fired Stop (stop_hook_active)
+// records nothing new.
+//
+// ESM/CJS: this hook is CommonJS. The ELO engine is CJS (require). The pure libs and
+// the suitability store are ESM under a type:module package, reached via dynamic
+// import() with a file:// URL.
+
+const path = require('path');
+const { pathToFileURL } = require('url');
+
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve('');
+    let data = '';
+    process.stdin.on('data', (c) => (data += c));
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', () => resolve(data));
+  });
+}
+
+function done() {
+  process.stdout.write(JSON.stringify({ continue: true }));
+  process.exit(0);
+}
+
+(async () => {
+  try {
+    await readStdin(); // the Stop payload is not needed — we drain disk state
+    const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    const esm = (rel) => import(pathToFileURL(path.join(root, rel)).href);
+
+    const af = await esm('_byan/mcp/byan-mcp-server/lib/advisory-autofeed.js');
+    const buf = await esm('_byan/mcp/byan-mcp-server/lib/outcome-buffer.js');
+
+    const outcomes = af.parseOutcomes(buf.readBuffer({ rootDir: root }));
+    const cursor = buf.readCursor({ rootDir: root });
+    const { pending, newCursor } = af.planDrain(outcomes, cursor);
+    if (!pending.length) return done();
+
+    let eloEngine = null;
+    let suitability = null;
+    for (const o of pending) {
+      const rec = af.classifyOutcome(o);
+      if (!rec) continue;
+      try {
+        if (rec.kind === 'elo') {
+          if (!eloEngine) {
+            const EloEngine = require(path.join(root, 'src', 'byan-v2', 'elo', 'index.js'));
+            eloEngine = new EloEngine({
+              storagePath: path.join(root, '_byan', 'memoire', 'elo-profile.json'),
+            });
+          }
+          eloEngine.recordResult(rec.domain, rec.result);
+        } else if (rec.kind === 'suitability') {
+          if (!suitability) {
+            suitability = await esm('_byan/mcp/byan-mcp-server/lib/suitability-store.js');
+          }
+          suitability.record({
+            model: rec.model,
+            leafId: rec.leafId,
+            success: rec.success,
+            source: 'autofeed',
+            projectRoot: root,
+          });
+        }
+      } catch {
+        // one bad record must not abort the drain or block the turn
+      }
+    }
+    buf.writeCursor(newCursor, { rootDir: root });
+  } catch {
+    // any failure degrades silently — the feed is housekeeping, never a blocker
+  }
+  done();
+})();

package/install/templates/.claude/hooks/lib/failure-detector.js

@@ -10,14 +10,27 @@ const ERROR_PATTERNS = [
   /tool_use_error/i,
 ];
 
-// Tools whose response echoes user-authored or file content (Write/Edit
+// Tools whose response echoes user-authored or stored content (Write/Edit
 // return file paths + content fragments, Read echoes file content
 // verbatim). Pattern match on their response fires false positives when
-// the file content itself contains the literal phrase "internal error"
+// the content itself contains the literal phrase "internal error"
 // (e.g. a doc about errors, a test fixture, a hook that detects errors).
 // For these, only trust the explicit is_error flag.
 const ECHO_TOOLS = new Set(['Write', 'Edit', 'NotebookEdit', 'Read']);
 
+// Two more tool classes echo DATA (not a stderr stream), so content-pattern
+// matching on their response is noise. A genuine failure of either sets is_error
+// (checked before this guard), so we lose no real-failure detection:
+//   - MCP tools (mcp__server__tool): byan_fd_* echoes the FD state (which can
+//     hold user-authored raw_ideas / notes containing the literal phrase),
+//     byan_*_status echoes ledger content, etc.
+//   - Bash: its response is command stdout - diagnostics, log greps, test output
+//     that legitimately surface error-words. A real Bash failure exits non-zero,
+//     which the harness marks as is_error.
+function isEchoHeavy(toolName) {
+  return ECHO_TOOLS.has(toolName) || toolName === 'Bash' || toolName.startsWith('mcp__');
+}
+
 function detectFailure(payload) {
   if (!payload || typeof payload !== 'object') return null;
 
@@ -30,8 +43,9 @@ function detectFailure(payload) {
     }
   }
 
-  // Do not pattern-match on echo-heavy tools — only trust is_error flag.
-  if (ECHO_TOOLS.has(toolName)) {
+  // Do not pattern-match on echo-heavy tools (file-echo + MCP data) — only
+  // trust the is_error flag, checked above.
+  if (isEchoHeavy(toolName)) {
     return null;
   }
 

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

@@ -57,6 +57,10 @@
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/strict-stop-guard.js"
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/drain-advisory.js"
           }
         ]
       }

package/install/templates/.claude/skills/byan-insight/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: byan-insight
+description: Harvest the native Claude Code outcome trails (tool-log, strict-audit gaps, suitability ledger, ELO) into a GATED self-improvement digest for BYAN. Invoke when the user asks "what did this session teach BYAN", "insight digest", "self-improvement", "qu'est-ce que BYAN a appris", or wants to review recurring gaps / routing outcomes / tool health before deciding what to improve. Observe and propose; the human ratifies each change.
+---
+
+# BYAN Insight Loop (gated self-improvement)
+
+BYAN already has advisory learning surfaces (ELO trust, the suitability ledger,
+soul-memory) and the native Claude Code hooks already leave outcome trails on
+disk. This skill closes the loop: it READS those trails, aggregates them into a
+digest, and surfaces GATED proposals. It does not modify a behavior surface.
+
+## The one hard rule: observe and propose, do not silently self-modify
+
+An agent that rewrote its own routing, personas, or mantra thresholds on a
+heuristic would be the exact silent-downgrade BYAN exists to prevent. So this
+loop stops at a PROPOSAL. Applying a change (a routing tweak, a new checklist
+item, a persona edit) stays a human decision — ideally run as its own FD. The
+advisory data (ELO, suitability) is read-only here; behavior surfaces are left
+to the human gate.
+
+## Protocol
+
+1. **Harvest.** Call the MCP tool `byan_insight_digest` (read-only, no args). It
+   returns `{ gated: true, digest, render }` where `digest` is
+   `{ toolHealth, recurringGaps, routingOutcomes, eloTrends, proposals }`.
+   - `toolHealth` : call count, failure rate, top failing tools, output-token cost
+     (from `_byan-output/tool-log.jsonl`).
+   - `recurringGaps` : clustered self-verify gap themes with counts (from
+     `.byan-strict/audit.log`) — what BYAN keeps missing.
+   - `routingOutcomes` : per cheap-model x leaf keep-rate (from the suitability
+     ledger) — where a downgrade is proven good or bad.
+   - `eloTrends` : per-domain trust rating.
+   - `proposals` : conservative, GATED suggestions (each `gated: true`).
+2. **Present.** Show the `render` text, then the proposals as a numbered list.
+   Make explicit that nothing has been applied.
+3. **Gate.** For each proposal the user accepts, run the change as its own scoped
+   work (a short FD for a behavior change; a direct edit for a doc/checklist).
+   Do not auto-apply a proposal.
+
+## CLI equivalent
+
+```
+node _byan/mcp/byan-mcp-server/bin/byan-insight-digest.js [--root <dir>] [--json]
+```
+
+Prints the human-readable digest, or the raw JSON with `--json`. Self-disables
+(empty digest) when the trails are absent, so a fresh checkout is not an error.
+
+## What it deliberately leaves alone
+
+- It does not call `byan_elo_record` / `byan_suitability_record` for you (those
+  stay where the outcome actually happens, e.g. a VALIDATE pass).
+- It does not edit `lib/dispatch.js`, `native-tiers.js`, a persona, or the mantra
+  thresholds. Those are behavior surfaces; a proposal names them, a human
+  changes them.

package/install/templates/.claude/workflows/check-implementation-readiness.js

@@ -18,7 +18,7 @@ export const meta = {
 // this script). No wall-clock, no randomness: any date/id is passed via args
 // so the runtime can resume deterministically.
 
-const planningArtifacts = (args && args.planningArtifacts) || '_bmad-output/planning-artifacts'
+const planningArtifacts = (args && args.planningArtifacts) || '_byan-output/planning-artifacts'
 const reportDate = (args && args.date) || 'unspecified'
 const role = 'an expert Product Manager and Scrum Master specialized in requirements traceability and spotting gaps in planning artifacts. Be adversarial: your job is to find the failures others missed, not to reassure.'
 

package/install/templates/.github/agents/bmad-agent-byan.md

@@ -1037,9 +1037,9 @@ L'agent peut invoquer n'importe quel agent specialise :
 
 Variables de session disponibles apres chargement config :
 - `{project-root}` : Racine du repository
-- `{output_folder}` : Dossier de sortie (`_bmad-output/`)
-- `{planning_artifacts}` : `_bmad-output/planning-artifacts/`
-- `{implementation_artifacts}` : `_bmad-output/implementation-artifacts/`
+- `{output_folder}` : Dossier de sortie (`_byan-output/`)
+- `{planning_artifacts}` : `_byan-output/planning-artifacts/`
+- `{implementation_artifacts}` : `_byan-output/implementation-artifacts/`
 - `{user_name}`, `{communication_language}` : Depuis config.yaml
 
 ### Orchestration Multi-Agent

package/install/templates/_byan/core/activation/soul-activation.md

@@ -158,9 +158,9 @@ L'agent peut invoquer n'importe quel agent specialise :
 
 Variables de session disponibles apres chargement config :
 - `{project-root}` : Racine du repository
-- `{output_folder}` : Dossier de sortie (`_bmad-output/`)
-- `{planning_artifacts}` : `_bmad-output/planning-artifacts/`
-- `{implementation_artifacts}` : `_bmad-output/implementation-artifacts/`
+- `{output_folder}` : Dossier de sortie (`_byan-output/`)
+- `{planning_artifacts}` : `_byan-output/planning-artifacts/`
+- `{implementation_artifacts}` : `_byan-output/implementation-artifacts/`
 - `{user_name}`, `{communication_language}` : Depuis config.yaml
 
 ### Orchestration Multi-Agent

package/install/templates/_byan/mcp/byan-mcp-server/bin/byan-insight-digest.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { harvest, renderDigest } from '../lib/insight-harvest.js';
+
+// Aggregate native Claude Code outcome trails into a GATED improvement digest.
+// Reads: _byan-output/tool-log.jsonl, .byan-strict/audit.log,
+//        _byan-output/suitability-ledger.json, _byan/memoire/elo-profile.json
+// Missing trail -> empty; digest self-disables gracefully.
+//
+// Usage: node bin/byan-insight-digest.js [--root <dir>] [--json]
+
+function parseArgs(argv) {
+  const args = { json: false };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--json') args.json = true;
+    else if (argv[i] === '--root') args.root = argv[++i];
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv);
+const root = args.root || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+const digest = harvest({ rootDir: root });
+
+if (args.json) {
+  process.stdout.write(JSON.stringify(digest, null, 2) + '\n');
+} else {
+  process.stdout.write(renderDigest(digest) + '\n');
+}
+
+process.exit(0);

package/install/templates/_byan/mcp/byan-mcp-server/lib/advisory-autofeed.js

@@ -0,0 +1,83 @@
+// Advisory auto-feed — the pure planning half of the closed learning loop.
+//
+// BYAN's advisory ledgers (ELO trust, the suitability ledger) only INFORM future
+// decisions; they never override behavior. The open gap was that nothing fed them
+// automatically: the agent had to remember to call a record tool. This loop closes
+// that — outcomes are LOGGED to a buffer during a turn (cheaply, via byan_outcome_log),
+// and a Stop hook DRAINS the buffer into the ledgers at end of turn, with no agent
+// action. Behavior surfaces (routing / personas / mantras) are out of scope: this
+// only writes advisory data.
+//
+// This module is the PURE half (no I/O), so it is exhaustively unit-testable; the
+// Stop hook supplies the buffer text + a cursor and applies the records.
+//
+// Buffer line shapes (jsonl, one outcome per line):
+//   { kind: 'elo',         domain, result }                  result: VALIDATED|PARTIAL|BLOCKED
+//   { kind: 'suitability', model, leafId, success }          success: boolean
+// A line missing required fields or with a bad type is dropped (classifyOutcome -> null),
+// never throwing — a malformed log line must not break the drain.
+
+// Parse a jsonl buffer into outcome objects, skipping malformed lines.
+export function parseOutcomes(text) {
+  if (!text) return [];
+  return text
+    .split('\n')
+    .filter((l) => l.trim())
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+// Idempotent drain plan keyed on a LINE cursor: everything from `cursor` onward is
+// pending; the new cursor is the full length. A re-fired Stop with no new lines
+// yields an empty `pending`, so an outcome is recorded at most once.
+export function planDrain(outcomes, cursor = 0) {
+  const safeCursor = Number.isInteger(cursor) && cursor >= 0 ? cursor : 0;
+  const start = Math.min(safeCursor, outcomes.length);
+  return { pending: outcomes.slice(start), newCursor: outcomes.length };
+}
+
+// The ELO engine's result vocabulary. The MCP/skill vocabulary uses PARTIAL; the
+// engine uses PARTIALLY_VALID. classifyOutcome normalizes to the engine form.
+const ELO_RESULTS = new Set(['VALIDATED', 'PARTIALLY_VALID', 'BLOCKED']);
+function normalizeEloResult(r) {
+  if (r === 'PARTIAL') return 'PARTIALLY_VALID';
+  return r;
+}
+
+// Validate + normalize one buffer outcome into a record intent, or null if invalid.
+//   elo         -> { kind: 'elo', domain, result }   (result in ELO_RESULTS)
+//   suitability -> { kind: 'suitability', model, leafId, success }  (success boolean)
+export function classifyOutcome(o) {
+  if (!o || typeof o !== 'object') return null;
+  if (o.kind === 'elo') {
+    const domain = typeof o.domain === 'string' ? o.domain.trim() : '';
+    const result = normalizeEloResult(o.result);
+    if (!domain || !ELO_RESULTS.has(result)) return null;
+    return { kind: 'elo', domain, result };
+  }
+  if (o.kind === 'suitability') {
+    const model = typeof o.model === 'string' ? o.model.trim() : '';
+    const leafId = typeof o.leafId === 'string' ? o.leafId.trim() : '';
+    if (!model || !leafId || typeof o.success !== 'boolean') return null;
+    return { kind: 'suitability', model, leafId, success: o.success };
+  }
+  return null;
+}
+
+// Validate an outcome BEFORE it is appended to the buffer (used by byan_outcome_log).
+// Returns the canonical line object to write, or null if the input is not a valid
+// outcome. Keyed on the same rules as classifyOutcome so the buffer only ever holds
+// drainable lines.
+export function validateForLog(input) {
+  const rec = classifyOutcome(input);
+  if (!rec) return null;
+  return rec.kind === 'elo'
+    ? { kind: 'elo', domain: rec.domain, result: rec.result }
+    : { kind: 'suitability', model: rec.model, leafId: rec.leafId, success: rec.success };
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/insight-harvest.js

@@ -0,0 +1,220 @@
+// Session insight harvester — read native Claude Code outcome trails and
+// aggregate them into a GATED improvement digest for BYAN.
+//
+// Philosophy (the whole point): OBSERVE and PROPOSE, never silently self-modify.
+// BYAN already has advisory learning surfaces (ELO trust, the suitability
+// ledger) the agent updates by hand; the native hooks already leave outcome
+// trails on disk. This module closes the loop by READING those trails and
+// surfacing a digest with GATED proposals. It writes nothing back to a behavior
+// surface (routing / personas / mantras): applying any change stays a human
+// decision. An agent that rewrote its own routing on a heuristic would be the
+// exact silent-downgrade BYAN exists to prevent.
+//
+// The aggregation is PURE (no I/O) so it is exhaustively unit-testable; the I/O
+// entry takes an injected reader, mirroring template-sync.js / stub-sync.js.
+//
+// Trails consumed (shapes verified against the live repo):
+//   _byan-output/tool-log.jsonl   post line {phase:'post', tool, ok, est_output_tokens?}
+//   .byan-strict/audit.log        {event:'self_verify', verdict:'gap', findings:[]}
+//   _byan-output/suitability-ledger.json  { "model::leaf": {model, leafId, successes, failures} }
+//   _byan/memoire/elo-profile.json        { domains: { <domain>: {rating, blocked_streak, ...} } }
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Parse a JSONL blob into an array of objects, skipping malformed lines.
+export function parseJsonl(text) {
+  if (!text) return [];
+  return text
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+// Tool health from tool-log.jsonl post lines: call count, failure rate, the top
+// failing tools, and an output-token cost proxy. est_output_tokens is absent on
+// older lines (added later by the hook), so it defaults to 0.
+export function harvestToolHealth(toolLogEntries) {
+  const post = (toolLogEntries || []).filter((e) => e && e.phase === 'post');
+  const failures = post.filter((e) => e.ok === false);
+  const byTool = {};
+  for (const f of failures) byTool[f.tool || 'unknown'] = (byTool[f.tool || 'unknown'] || 0) + 1;
+  const topFailing = Object.entries(byTool)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5)
+    .map(([tool, count]) => ({ tool, count }));
+  const estOutputTokens = post.reduce((s, e) => s + (e.est_output_tokens || 0), 0);
+  return {
+    calls: post.length,
+    failures: failures.length,
+    failureRate: post.length ? +(failures.length / post.length).toFixed(3) : 0,
+    topFailing,
+    estOutputTokens,
+  };
+}
+
+// Coarse theme key for a strict gap finding. The categories mirror the recurring
+// gap types BYAN actually hits; anything unmatched is 'other' (never silently
+// dropped — it still counts under 'other').
+function normalizeGap(finding) {
+  const s = String(finding).toLowerCase();
+  if (/\btest|coverage|spec\b/.test(s)) return 'tests/coverage';
+  if (/error|edge|exception|fail|throw/.test(s)) return 'error/edge handling';
+  if (/doc|comment|changelog|readme/.test(s)) return 'documentation';
+  if (/template|fidelity|sync|twin/.test(s)) return 'template fidelity';
+  if (/emoji/.test(s)) return 'emoji';
+  if (/scope|downgrade|cut|stub|mvp/.test(s)) return 'scope/downgrade';
+  return 'other';
+}
+
+// Recurring strict-gap clustering (L3): mine self_verify gap findings from the
+// audit log and group them into themes. A theme is "recurring" at count >= 2.
+export function harvestStrictGaps(auditEntries) {
+  const findings = [];
+  for (const e of auditEntries || []) {
+    if (e && e.event === 'self_verify' && e.verdict === 'gap' && Array.isArray(e.findings)) {
+      findings.push(...e.findings);
+    }
+  }
+  const themes = {};
+  for (const f of findings) {
+    const key = normalizeGap(f);
+    if (!themes[key]) themes[key] = { theme: key, count: 0, samples: [] };
+    themes[key].count++;
+    if (themes[key].samples.length < 2) themes[key].samples.push(String(f).slice(0, 100));
+  }
+  const recurring = Object.values(themes)
+    .filter((t) => t.count >= 2)
+    .sort((a, b) => b.count - a.count);
+  return { totalGapFindings: findings.length, recurring };
+}
+
+// Routing outcomes (L1): surface the suitability ledger as per (cheap-model x
+// leaf) keep-rate rows, busiest first. keepRate = successes / (successes+failures).
+export function harvestRouting(ledger) {
+  const rows = [];
+  const entries = ledger && typeof ledger === 'object' ? Object.entries(ledger) : [];
+  for (const [key, v] of entries) {
+    if (!v || typeof v !== 'object') continue;
+    const successes = Number(v.successes || 0);
+    const failures = Number(v.failures || 0);
+    const n = successes + failures;
+    if (!n) continue;
+    const model = v.model || key.split('::')[0];
+    const leaf = v.leafId || key.split('::')[1] || key;
+    rows.push({ model, leaf, successes, failures, n, keepRate: +(successes / n).toFixed(2) });
+  }
+  return rows.sort((a, b) => b.n - a.n);
+}
+
+// Domain trust trends from the ELO profile: rating + blocked streak per domain.
+export function harvestEloTrends(eloProfile) {
+  const domains = (eloProfile && eloProfile.domains) || {};
+  const rows = [];
+  for (const [domain, d] of Object.entries(domains)) {
+    if (!d || typeof d !== 'object' || typeof d.rating !== 'number') continue;
+    rows.push({ domain, rating: d.rating, blockedStreak: d.blocked_streak || 0 });
+  }
+  return rows.sort((a, b) => b.rating - a.rating);
+}
+
+// Assemble the digest and derive GATED proposals. Every proposal is a suggestion
+// for the human to ratify (gated:true) — none is auto-applied. The thresholds
+// are deliberately conservative so noise does not generate proposals.
+export function buildDigest({ toolHealth, gaps, routing, elo } = {}) {
+  const proposals = [];
+
+  if (toolHealth && toolHealth.failureRate > 0.1 && toolHealth.topFailing.length) {
+    const t = toolHealth.topFailing[0];
+    proposals.push({
+      kind: 'tool-reliability',
+      gated: true,
+      suggestion: `Tool failure rate ${toolHealth.failureRate}; top offender ${t.tool} (${t.count}). Investigate before relying on it.`,
+    });
+  }
+  for (const g of (gaps && gaps.recurring) || []) {
+    if (g.count >= 3) {
+      proposals.push({
+        kind: 'recurring-gap',
+        gated: true,
+        suggestion: `Recurring self-verify gap "${g.theme}" (${g.count}x). Consider a pre-build checklist item.`,
+      });
+    }
+  }
+  for (const r of routing || []) {
+    if (r.n >= 5 && r.keepRate < 0.5) {
+      proposals.push({
+        kind: 'routing',
+        gated: true,
+        suggestion: `Cheap model ${r.model} underperforms on "${r.leaf}" (keepRate ${r.keepRate}, n=${r.n}). Consider keeping that leaf deep.`,
+      });
+    }
+  }
+
+  return {
+    toolHealth: toolHealth || null,
+    recurringGaps: gaps || { totalGapFindings: 0, recurring: [] },
+    routingOutcomes: routing || [],
+    eloTrends: elo || [],
+    proposals,
+  };
+}
+
+// Human-readable render of a digest (for the CLI and the skill).
+export function renderDigest(d) {
+  const lines = ['BYAN session insight digest', ''];
+  if (d.toolHealth) {
+    lines.push(
+      `Tool health: ${d.toolHealth.calls} calls, ${d.toolHealth.failures} failures (rate ${d.toolHealth.failureRate}), ~${d.toolHealth.estOutputTokens} output tokens.`
+    );
+    if (d.toolHealth.topFailing.length) {
+      lines.push(`  Top failing: ${d.toolHealth.topFailing.map((t) => `${t.tool}(${t.count})`).join(', ')}`);
+    }
+  }
+  lines.push(`Recurring gaps: ${d.recurringGaps.recurring.map((g) => `${g.theme}(${g.count})`).join(', ') || 'none'}`);
+  if (d.routingOutcomes.length) {
+    lines.push('Routing outcomes (cheap-model keep-rate):');
+    for (const r of d.routingOutcomes.slice(0, 8)) {
+      lines.push(`  ${r.model}::${r.leaf} -> keep ${r.keepRate} (n=${r.n})`);
+    }
+  }
+  if (d.eloTrends.length) {
+    lines.push(`ELO trends: ${d.eloTrends.slice(0, 6).map((e) => `${e.domain}=${e.rating}`).join(', ')}`);
+  }
+  lines.push('', `Proposals (GATED — human ratifies, nothing auto-applied): ${d.proposals.length}`);
+  for (const p of d.proposals) lines.push(`  [${p.kind}] ${p.suggestion}`);
+  return lines.join('\n');
+}
+
+// I/O entry: read the trails under rootDir (missing trail -> empty, so the digest
+// self-disables gracefully on a fresh checkout) and build the digest.
+export function harvest({ rootDir, io = fs } = {}) {
+  const readText = (rel) => {
+    try {
+      return io.readFileSync(path.join(rootDir, rel), 'utf8');
+    } catch {
+      return '';
+    }
+  };
+  const readJson = (rel) => {
+    const t = readText(rel);
+    if (!t) return null;
+    try {
+      return JSON.parse(t);
+    } catch {
+      return null;
+    }
+  };
+  const toolHealth = harvestToolHealth(parseJsonl(readText('_byan-output/tool-log.jsonl')));
+  const gaps = harvestStrictGaps(parseJsonl(readText('.byan-strict/audit.log')));
+  const routing = harvestRouting(readJson('_byan-output/suitability-ledger.json'));
+  const elo = harvestEloTrends(readJson('_byan/memoire/elo-profile.json'));
+  return buildDigest({ toolHealth, gaps, routing, elo });
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/outcome-buffer.js

@@ -0,0 +1,64 @@
+// Outcome buffer — the append-only capture file the advisory auto-feed drains.
+//
+// byan_outcome_log appends one validated outcome per line here during a turn; the
+// drain-advisory Stop hook reads it at end of turn and records each new line into
+// the advisory ledgers, advancing a line cursor for idempotency. Both sides take an
+// injected `io` so the logic is testable without touching the real filesystem, and
+// every operation is best-effort: a capture buffer must never break a turn.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const BUFFER_REL = path.join('_byan-output', 'pending-outcomes.jsonl');
+export const CURSOR_REL = path.join('_byan-output', '.advisory-cursor.json');
+
+function bufferPath(rootDir) {
+  return path.join(rootDir, BUFFER_REL);
+}
+function cursorPath(rootDir) {
+  return path.join(rootDir, CURSOR_REL);
+}
+
+// Append one outcome object as a jsonl line. Best-effort: returns true on write,
+// false if the write threw (the caller stays safe).
+export function appendOutcome(outcome, { rootDir, io = fs } = {}) {
+  try {
+    const p = bufferPath(rootDir);
+    io.mkdirSync(path.dirname(p), { recursive: true });
+    io.appendFileSync(p, JSON.stringify(outcome) + '\n');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Read the raw buffer text, or '' if absent/unreadable.
+export function readBuffer({ rootDir, io = fs } = {}) {
+  try {
+    return io.readFileSync(bufferPath(rootDir), 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+// Read the drain cursor (number of buffer lines already recorded), or 0.
+export function readCursor({ rootDir, io = fs } = {}) {
+  try {
+    const obj = JSON.parse(io.readFileSync(cursorPath(rootDir), 'utf8'));
+    return Number.isInteger(obj && obj.drained) && obj.drained >= 0 ? obj.drained : 0;
+  } catch {
+    return 0;
+  }
+}
+
+// Persist the drain cursor. Best-effort.
+export function writeCursor(drained, { rootDir, io = fs } = {}) {
+  try {
+    const p = cursorPath(rootDir);
+    io.mkdirSync(path.dirname(p), { recursive: true });
+    io.writeFileSync(p, JSON.stringify({ drained }) + '\n');
+    return true;
+  } catch {
+    return false;
+  }
+}

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

@@ -9,6 +9,9 @@ import {
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import { dispatch } from './lib/dispatch.js';
+import { harvest as harvestInsights, renderDigest as renderInsightDigest } from './lib/insight-harvest.js';
+import { appendOutcome } from './lib/outcome-buffer.js';
+import { validateForLog } from './lib/advisory-autofeed.js';
 import { readSoul, appendSoulMemory } from './lib/soul.js';
 import { listSessions, readSessionEvents, searchSessions } from './lib/copilot.js';
 import {
@@ -545,6 +548,34 @@ const tools = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'byan_insight_digest',
+    description:
+      'Harvest native Claude Code outcome trails (tool-log, strict-audit gaps, the suitability ledger, ELO) into a GATED improvement digest for BYAN. Read-only: it OBSERVES and PROPOSES; every proposal is gated for a human to ratify, nothing is auto-applied to routing / personas / mantras. Returns { toolHealth, recurringGaps, routingOutcomes, eloTrends, proposals }.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'byan_outcome_log',
+    description:
+      'Log one ADVISORY outcome to the auto-feed buffer (cheap append; it never writes a ledger directly). The drain-advisory Stop hook records buffered outcomes into the ELO / suitability ledgers at end of turn, so BYAN auto-learns without the agent recording by hand. kind=elo needs { domain, result: VALIDATED|PARTIAL|BLOCKED }; kind=suitability needs { model, leafId, success }. Advisory-only: behavior surfaces (routing / personas / mantras) are never written.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        kind: { type: 'string', enum: ['elo', 'suitability'] },
+        domain: { type: 'string', description: 'elo: the technical domain of the claim' },
+        result: { type: 'string', enum: ['VALIDATED', 'PARTIAL', 'BLOCKED'], description: 'elo: the claim verdict' },
+        model: { type: 'string', description: 'suitability: the cheap model tier/id' },
+        leafId: { type: 'string', description: 'suitability: the workflow leaf' },
+        success: { type: 'boolean', description: 'suitability: did the cheap model survive adversarial review' },
+      },
+      required: ['kind'],
+      additionalProperties: false,
+    },
+  },
   {
     name: 'byan_strict_lock_scope',
     description:
@@ -1383,6 +1414,33 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       };
     }
 
+    if (name === 'byan_insight_digest') {
+      const rootDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+      const digest = harvestInsights({ rootDir });
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ gated: true, digest, render: renderInsightDigest(digest) }, null, 2),
+          },
+        ],
+      };
+    }
+
+    if (name === 'byan_outcome_log') {
+      const line = validateForLog(args);
+      if (!line) {
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ logged: false, reason: 'invalid_outcome' }) }],
+        };
+      }
+      const rootDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+      const ok = appendOutcome(line, { rootDir });
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ logged: ok, outcome: line }) }],
+      };
+    }
+
     if (name === 'byan_strict_lock_scope') {
       const r = strictLockScope({
         scopeText: args.scopeText,

package/install/templates/_byan/worker/workers.md

@@ -287,24 +287,25 @@ very different optimal targets depending on whether they run **alongside
 siblings** (parallel) or **in sequence**. The v2 router adds a
 `parallelizable` axis and emits an **execution strategy**, not a model.
 
-Implementation : `src/core/dispatcher/execution-router.js` and the MCP
-tool `byan_dispatch` (both share the same table).
+Implementation : the MCP tool `byan_dispatch`
+(`_byan/mcp/byan-mcp-server/lib/dispatch.js`), the single source of truth. The
+strategy comes from the score + `parallelizable` ; the model tier is a separate
+axis, derived from the task NATURE via `native-tiers.js`.
 
 ```
 score < 15                           → main-thread
 score 15-39 + parallelizable: true   → agent-subagent-worktree
-score 15-39 + parallelizable: false  → mcp-worker-haiku
-score >= 40                          → main-thread-opus
+score 15-39 + parallelizable: false  → mcp-worker
+score >= 40                          → main-thread (heavy)
 ```
 
 Rationale :
 
 | Strategy | When | Why |
 |---|---|---|
-| `main-thread` | Trivial task | Spawning anything costs more than solving inline. |
+| `main-thread` | Trivial or heavy task | Spawning costs more than solving inline (trivial), or the work is heavy and stays in the main thread. |
 | `agent-subagent-worktree` | Medium parallel | Claude Code Agent tool with `isolation: "worktree"` amortizes boot cost across the wall-clock savings. |
-| `mcp-worker-haiku` | Medium sequential | Delegate to a lightweight Haiku via MCP tool — no subagent boot, cheaper than main thread. |
-| `main-thread-opus` | Complex | Reasoning depth needed; subagent boot + context handoff would waste more than the delegation saves. |
+| `mcp-worker` | Medium sequential | Delegate to a worker via MCP tool — no subagent boot, cheaper than the main thread. The model tier is set separately, by nature. |
 
 The score threshold of 15 is where Claude Code `Agent` tool boot overhead
 (~5-10k tokens for system prompt + tools) stops being worth it for

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

@@ -111,8 +111,8 @@ INIT
 |------------------|-------|-----------|
 | < 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 |
+| < 40 séquentiel | `mcp-worker` | Worker léger via MCP (le tier de modèle vient de la nature, pas de la taille) |
+| ≥ 40 | `main-thread` | Garde en main thread (lourd) ; modèle hérité de la session |
 
 > 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.23.0",
+  "version": "2.25.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 (Copilot CLI, Claude Code, Codex). Merise Agile + TDD + 71 Mantras. ~54% LLM cost savings.",
   "main": "src/index.js",
   "bin": {

package/src/loadbalancer/loadbalancer.js

@@ -8,7 +8,7 @@
  *   - Integration with RateLimitTracker + SharedStateStore + SessionBridge
  *
  * Sits ABOVE existing BYAN routers:
- *   LoadBalancer (picks PLATFORM) → ExecutionRouter (picks STRATEGY) → Dispatcher (picks MODEL)
+ *   LoadBalancer (picks PLATFORM) → byan_dispatch (picks STRATEGY + model TIER)
  */
 
 const { EventEmitter } = require('events');

package/src/core/dispatcher/execution-router.js

@@ -1,66 +0,0 @@
-/**
- * Execution strategy router.
- *
- * Decides WHERE a task runs (not which model). Four strategies, routed by
- * complexity score and whether the task is parallelizable with siblings:
- *
- *   main-thread              score < 15
- *   agent-subagent-worktree  score 15-39 + parallelizable = true
- *   mcp-worker-haiku         score 15-39 + sequential
- *   main-thread-opus         score >= 40
- *
- * Complementary to EconomicDispatcher (which picks the model).
- */
-
-class ExecutionRouter {
-  /**
-   * @param {{task?: string, complexity?: number, parallelizable?: boolean}} input
-   * @returns {{score: number, strategy: string, reasoning: string, parallelizable: boolean}}
-   */
-  route(input = {}) {
-    const { task, complexity, parallelizable } = input;
-
-    const score =
-      typeof complexity === 'number'
-        ? complexity
-        : Math.min(100, Math.floor((task?.length || 0) / 10));
-
-    const isPar = parallelizable === true;
-
-    if (score < 15) {
-      return {
-        score,
-        strategy: 'main-thread',
-        reasoning: `Score ${score} < 15. Inline in current context, no delegation overhead.`,
-        parallelizable: isPar,
-      };
-    }
-
-    if (score < 40 && isPar) {
-      return {
-        score,
-        strategy: 'agent-subagent-worktree',
-        reasoning: `Score ${score} + parallelizable. Spawn Claude Code Agent tool with worktree isolation.`,
-        parallelizable: isPar,
-      };
-    }
-
-    if (score < 40) {
-      return {
-        score,
-        strategy: 'mcp-worker-haiku',
-        reasoning: `Score ${score}, sequential. Delegate to lightweight Haiku worker via MCP.`,
-        parallelizable: isPar,
-      };
-    }
-
-    return {
-      score,
-      strategy: 'main-thread-opus',
-      reasoning: `Score ${score} >= 40. Complex task, keep in main thread with Opus reasoning.`,
-      parallelizable: isPar,
-    };
-  }
-}
-
-module.exports = ExecutionRouter;