create-byan-agent 2.22.0 → 2.25.0

package/CHANGELOG.md

@@ -9,6 +9,110 @@ 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)
+
+The installer generated platform stubs (`.codex/prompts`, `.github/agents`,
+`.claude/skills`) across many versions; older generators wrote the legacy path
+layout (`_bmad/*/agents/X.md`, `@bmad/bmm/agents/X.md`,
+`@bmad-output/bmb-creations/X/X.md`), so the tracked corpus carried a mix of stale
+path forms while the agent source files stayed clean. This adds the mechanism that
+removes the drift and blocks its return.
+
+- **Tool** `_byan/mcp/byan-mcp-server/lib/stub-sync.js` + `bin/byan-sync-stubs.js`:
+  normalizes stale `_bmad/` and `@bmad/` PATH tokens to the `_byan/` canonical
+  layout, in place and surgically. The `@bmad-<word>` invocation syntax and the
+  `_bmad-output/` artifact dir are preserved; no stub is overwritten wholesale, so
+  the github full-copies and hand-authored skills keep their content. `--check`
+  reports any residual stale ref and exits non-zero.
+- **5th pre-commit gate.** `.githooks/pre-commit` runs `byan-sync-stubs --check`
+  after the template-fidelity gate, blocking a commit whose tracked stubs have
+  drifted. It self-disables when the tool or the stub dirs are absent
+  (installed-user no-op).
+- **First run.** 101 stub files normalized (codex prompts + the Codex global
+  `instructions.md` + 5 github stubs + their template twins); the byan github
+  full-copy changed only its 3 stale path lines, its other 1059 lines untouched.
+- Design mirrors the template-fidelity sync (pure rewrite rules + IO-isolated
+  apply); 20 unit tests pin every rule, the two preservation cases, the IO layer,
+  and idempotence. The tool ships in the template, so the gate is live for
+  installed users too.
+
 ## [2.22.0] - 2026-06-09
 
 ### Changed - byan_dispatch routes the model tier by task nature, not by size

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/.githooks/pre-commit

@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
-# BYAN pre-commit hook. Four gates run in order:
+# BYAN pre-commit hook. Five 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. Template fidelity : block if install/templates/ drifted from root.
-#   4. Mantra floor      : block if a Gen3 persona source scores below the floor.
+#   4. Stub path drift   : block if a tracked stub carries a stale _bmad/@bmad path ref.
+#   5. Mantra floor      : block if a Gen3 persona source scores below the floor.
 #
 # Install :
 #   git config core.hooksPath .githooks
@@ -81,6 +82,24 @@ if [ -f "$TEMPLATE_SYNC" ]; then
   fi
 fi
 
+# Stub path drift gate — the installer generated platform stubs (.codex/prompts,
+# .github/agents, .claude/skills) over many versions; older generators emitted the
+# legacy _bmad/@bmad path layout while the agent sources are clean. This gate
+# blocks a commit whose tracked stubs still carry a stale _bmad/ or @bmad/ PATH
+# ref (the @bmad- invocation syntax and the _bmad-output/ artifact dir are left
+# alone). Re-normalize with the apply command, then restage. No-op if the tool is
+# absent or no stub dirs exist (installed-user no-op).
+STUB_SYNC="_byan/mcp/byan-mcp-server/bin/byan-sync-stubs.js"
+if [ -f "$STUB_SYNC" ]; then
+  if ! node "$STUB_SYNC" --check --root "$(git rev-parse --show-toplevel)"; then
+    echo ""
+    echo "Commit blocked : a tracked stub carries a stale _bmad/@bmad path ref."
+    echo "Re-normalize with 'node $STUB_SYNC' then restage, or bypass with"
+    echo "'git commit --no-verify' (emergency only)."
+    exit 1
+  fi
+fi
+
 if [ ! -f "$VALIDATOR" ]; then
   exit 0
 fi

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

@@ -1023,23 +1023,23 @@ Il n'est PAS un worker isole — il est un orchestrateur dans l'ecosysteme BMAD.
 
 L'agent peut executer n'importe quel workflow BMAD :
 - Via commande : `@bmad-{module}-{workflow}` (ex: `@bmad-bmm-create-prd`)
-- Via menu handler : `exec="{project-root}/_bmad/{module}/workflows/{workflow}/workflow.md"`
-- Manifeste : `{project-root}/_bmad/_config/workflow-manifest.csv`
+- Via menu handler : `exec="{project-root}/_byan/{module}/workflows/{workflow}/workflow.md"`
+- Manifeste : `{project-root}/_byan/_config/workflow-manifest.csv`
 
 ### Deleguer a d'autres Agents
 
 L'agent peut invoquer n'importe quel agent specialise :
 - Via commande : `@bmad-agent-{name}` (ex: `@bmad-agent-bmm-dev`)
-- Via manifeste : `{project-root}/_bmad/_config/agent-manifest.csv`
+- Via manifeste : `{project-root}/_byan/_config/agent-manifest.csv`
 - L'agent delegue reprend le controle — l'agent courant se retire
 
 ### Acceder aux Contextes
 
 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/.github/agents/bmad-agent-skeptic.md

@@ -6,7 +6,7 @@ description: 'Scientific Claim Challenger and Epistemic Guard'
 You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
 
 <agent-activation CRITICAL="TRUE">
-1. LOAD the FULL agent file from {project-root}/_bmad-output/bmb-creations/skeptic/skeptic.md
+1. LOAD the FULL agent file from {project-root}/_byan/agent/skeptic/skeptic.md
 2. READ its entire contents - this contains the complete agent persona, menu, and instructions
 3. LOAD the soul activation protocol from {project-root}/_byan/core/activation/soul-activation.md and EXECUTE it silently
 4. FOLLOW every step in the <activation> section precisely

package/install/templates/_byan/_config/agent-manifest.csv

@@ -25,4 +25,6 @@ expert-merise-agile,"Expert Merise","Expert Merise Agile - Assistant de Concepti
 "skeptic","The Skeptic","Scientific Claim Challenger and Epistemic Guard","[?]","Epistemic Guard + Fact-Check Specialist","Methodical challenger of all claims. Applies 3-step verification (Source / Proof type / Reproducible). Specializes in auditing documents for unsourced assertions, computing Trust Scores, and verifying reasoning chains with multiplicative confidence propagation.","Cold, methodical, impeccably polite. Speaks in structured CLAIM/CHALLENGE/VERDICT blocks. Uses Socratic method — questions before conclusions. Never hostile, always rigorous.","Challenge Before Confirm | Extraordinary claims require extraordinary evidence | Descartes Doubt | No URL generation | Strict-domain LEVEL-2 minimum","core","_byan/agent/skeptic/skeptic.md"
 "forgeron","Le Forgeron","Revelateur d ames","","Revelateur d ames — Soul Forger","Expert en interview psychologique profonde pour extraire l ame du createur depuis ses experiences de vie. Detecte emotions, valeurs, blessures fondatrices. Genere creator-soul.md et agent soul files. Calme, patient, utilise le silence comme outil.","Calme, patient, minimal, profond. Questions rares mais chaque une compte. Utilise le silence. Reflete sans projeter.","Ne jamais interpreter a la place du createur | Ne jamais precipiter | Emotions = donnees de navigation | Preuve avant sentence","bmb","_byan/agent/forgeron/forgeron.md"
 "tao","Tao","Le Tao — Directeur de Voix des Agents","道","Voice Director — Soul to Expression Bridge","Transforme les valeurs abstraites du soul.md en directives vocales concretes : tics de langage, registre, signatures verbales, vocabulaire interdit. Forge le tao.md de chaque agent. Garantit l anti-uniformite : chaque agent sonne unique.","Calme, precis, chirurgical. L oreille absolue pour les voix. Detecte le generique a la premiere phrase. Concret : jamais de regle sans exemple.","Derivation tracable : chaque tic nait d une valeur d ame | Anti-uniformite : deux agents ne sonnent jamais pareil | Exemple obligatoire | La voix sert l ame pas l inverse","core","_byan/agent/tao/tao.md"
+"jimmy","Jimmy","Spécialiste Documentation Technique & Processus Internes","book-open","Technical Documentation Specialist + Outline Knowledge Custodian","Specialist in technical documentation and internal processes. Creates, maintains, and organizes operational documentation on Outline: runbooks, deployment procedures, infrastructure configs, and server and web guides. Expert in infra, web, and server work with zero approximation in procedures. Documents in French for francophone technical teams.","Professional and rigorous, direct without unnecessary jargon, and pedagogical when needed. Uses a standardized structure per document type.","Clear and actionable technical documentation | Standardized structure per document type | Systematic validation before publication | Coherently named and organized collections | Reusable templates when relevant","bmm","_byan/agent/jimmy/jimmy.md"
+"mike","Mike","Gestionnaire de Projet — Spécialiste Leantime","clipboard-list","Project Manager + Leantime Integration Specialist","Project manager specialized in Leantime. Creates, organizes, and manages projects, tasks (tickets), sprints, and milestones on Leantime. Structures team work clearly and efficiently. Works in French for francophone teams.","Professional and organized, results-oriented, and direct in French. Asks targeted questions to structure the work with no superfluous content.","MVP first, the minimum viable to get moving | Validation before action, confirm before executing | Clarity through explicit names and concise descriptions | Traceability by documenting important decisions | Explicit errors with proposed alternatives","bmm","_byan/agent/mike/mike.md"
 

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/bin/byan-sync-stubs.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { applyFix, check, STUB_DIRS } from '../lib/stub-sync.js';
+
+// Normalize stale _bmad / @bmad PATH references in tracked agent stubs to the
+// _byan/ canonical form. Two modes:
+//   (default) fix : rewrite stale path tokens in place (atomic per file).
+//   --check       : report any residual stale ref and exit non-zero (no writes).
+//                   This is the pre-commit gate's entry point.
+// Usage: node bin/byan-sync-stubs.js [--check] [--root <dir>]
+
+function parseArgs(argv) {
+  const args = { check: false };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--check') args.check = true;
+    else 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();
+
+// Self-disable when none of the stub dirs exist (installed-user no-op).
+const anyDir = STUB_DIRS.some(
+  (d) => fs.existsSync(path.join(root, d)) || fs.existsSync(path.join(root, 'install', 'templates', d)),
+);
+if (!anyDir) {
+  process.stdout.write('[byan-sync-stubs] no stub directories - nothing to normalize\n');
+  process.exit(0);
+}
+
+if (args.check) {
+  const { stale, ok, scanned } = check({ rootDir: root });
+  if (ok) {
+    process.stdout.write(`[byan-sync-stubs] OK - ${scanned} stubs free of stale _bmad/@bmad path refs\n`);
+    process.exit(0);
+  }
+  for (const { file, refs } of stale) {
+    process.stderr.write(`[byan-sync-stubs] stale: ${file} -> ${refs.join(', ')}\n`);
+  }
+  process.stderr.write(
+    `[byan-sync-stubs] FAIL - ${stale.length} stub(s) carry stale path refs. Run: node bin/byan-sync-stubs.js\n`,
+  );
+  process.exit(1);
+}
+
+const { fixed, scanned } = applyFix({ rootDir: root });
+process.stdout.write(`[byan-sync-stubs] normalized - ${fixed.length} stub(s) fixed of ${scanned} scanned\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/lib/stub-sync.js

@@ -0,0 +1,158 @@
+// Stub path normalizer — keep tracked agent stubs free of stale _bmad / @bmad
+// PATH references.
+//
+// The installer generated platform stubs (.codex/prompts, .github/agents,
+// .claude/skills) over many versions. Older generators emitted the legacy path
+// layout (`_bmad/*/agents/X.md`, `@bmad/bmm/agents/X.md`,
+// `@bmad-output/bmb-creations/X/X.md`); the current generator emits the `_byan/`
+// new layout. The committed corpus therefore carries a mix of stale path forms,
+// while the source agent files are clean. This module normalizes those stale
+// PATH tokens to the `_byan/` canonical form, in place, touching nothing else.
+//
+// Two tokens look similar but are NOT paths and must survive untouched:
+//   - `@bmad-<word>`  : the agent/workflow INVOCATION syntax (`@bmad-bmm-create-prd`,
+//                       `@bmad-party-mode`). A command, not a file path.
+//   - `_bmad-output/` : the accepted output-artifact directory (planning/
+//                       implementation artifacts), documented in CLAUDE.md.
+// Both are distinguished structurally: a path token is `@bmad/` or `_bmad/`
+// (immediate slash); the survivors are `@bmad-` / `_bmad-` (immediate hyphen).
+// The one exception is `[@_]bmad-output/bmb-creations/<name>/<name>.md`, which is
+// a stale AGENT-LOAD path (the agent now lives at `_byan/agent/<name>/`), so that
+// specific sub-form IS rewritten.
+//
+// Design mirrors template-sync.js: the risky half (the rewrite rules) is pure and
+// exhaustively unit-tested; the I/O half takes an injected `io` so tests pin
+// behaviour without touching the real filesystem. The tool only ever edits stale
+// path tokens — it never regenerates or overwrites a stub wholesale, so the 6
+// github full-copies and the 12 hand-authored rich skills keep their content.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Tracked stub directories (root-relative POSIX). Each is scanned (its .md files)
+// both at root and under its install/templates/ twin. `.codex` is taken whole so
+// the Codex global context file (.codex/instructions.md) is normalized alongside
+// the per-agent .codex/prompts/ stubs.
+export const STUB_DIRS = ['.codex', '.github/agents', '.claude/skills'];
+export const TEMPLATE_PREFIX = 'install/templates';
+
+// Canonical new-layout reference for an agent name.
+function agentRef(name) {
+  return `_byan/agent/${name}/${name}.md`;
+}
+
+// Ordered rewrite rules. Order matters: the specific agent-load forms run before
+// the generic prefix swaps, so an agent path becomes the new layout
+// (`_byan/agent/X/X.md`) rather than the legacy one (`_byan/*/agents/X.md`).
+const RULES = [
+  // bmb-creations agent load -> new-layout agent ref. Matches both @bmad-output
+  // and _bmad-output ONLY when followed by /bmb-creations/<dir>/<name>.md, so a
+  // plain _bmad-output/ artifact path is left alone. Keyed on the .md FILENAME
+  // (not requiring dir == filename) so it covers every form findStaleRefs flags,
+  // keeping --fix and --check in lockstep (no flag-but-cannot-fix gate trap).
+  [/[@_]bmad-output\/bmb-creations\/[a-z0-9-]+\/([a-z0-9-]+)\.md/gi, (_m, n) => agentRef(n)],
+  // agent path, flat or nested: (@bmad|_bmad)/(*|module)/agents/<name>(/<name>)?.md
+  [/(?:@bmad|_bmad)\/(?:\*|[a-z0-9_-]+)\/agents\/([a-z0-9-]+)(?:\/[a-z0-9-]+)?\.md/gi, (_m, n) => agentRef(n)],
+  // generic _bmad/ path prefix. Does not touch _bmad-output (that is _bmad- then
+  // a hyphen, never _bmad followed by a slash).
+  [/_bmad\//g, '_byan/'],
+  // generic @bmad/ path prefix. Does not touch @bmad- invocation syntax.
+  [/@bmad\//g, '_byan/'],
+];
+
+// Pure: rewrite stale path tokens. Returns { text, changed }.
+export function normalizeText(text) {
+  let out = text;
+  for (const [re, rep] of RULES) out = out.replace(re, rep);
+  return { text: out, changed: out !== text };
+}
+
+// Pure: the stale path refs a clean file must NOT contain. A path token
+// (`@bmad/` or `_bmad/`) or a bmb-creations agent load. Invocation `@bmad-` and
+// plain `_bmad-output/` artifacts are excluded by construction.
+// The generic arm uses [^...]* (zero-or-more) so a bare `@bmad/` or `_bmad/`
+// prefix is flagged even when the next char is an excluded terminator (space,
+// paren, quote, backtick) — rule 3/4 rewrite the prefix regardless, so --check
+// must flag it regardless too.
+const STALE_RE = /(?:[@_]bmad-output\/bmb-creations\/[a-z0-9-]+\/[a-z0-9-]+\.md|(?:@bmad|_bmad)\/[^\s)`'"]*)/gi;
+export function findStaleRefs(text) {
+  const m = text.match(STALE_RE);
+  return m ? [...new Set(m)] : [];
+}
+
+// Recursively list root-relative POSIX paths of every .md file under dir. Returns
+// [] if dir does not exist (an installed user without these dirs is not an error).
+export function walkRelMd(dir, { io = fs, base = dir } = {}) {
+  let entries;
+  try {
+    entries = io.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      out.push(...walkRelMd(full, { io, base }));
+    } else if (e.isFile() && e.name.endsWith('.md')) {
+      out.push(path.relative(base, full).split(path.sep).join('/'));
+    }
+  }
+  return out;
+}
+
+// Every stub .md file (root-relative POSIX), root dirs + their template twins.
+export function listStubFiles({ rootDir, io = fs } = {}) {
+  const files = [];
+  for (const d of STUB_DIRS) {
+    files.push(...walkRelMd(path.join(rootDir, d), { io, base: rootDir }));
+    files.push(...walkRelMd(path.join(rootDir, TEMPLATE_PREFIX, d), { io, base: rootDir }));
+  }
+  return files;
+}
+
+// Plan: which tracked stub files would change under normalization.
+export function planFix({ rootDir, io = fs } = {}) {
+  const files = listStubFiles({ rootDir, io });
+  const toFix = [];
+  for (const rel of files) {
+    const { changed } = normalizeText(io.readFileSync(path.join(rootDir, rel), 'utf8'));
+    if (changed) toFix.push(rel);
+  }
+  return { toFix, scanned: files.length };
+}
+
+// Apply: normalize every file that needs it. Each write is atomic (stage adjacent
+// tmp, rename over the target) so a crash never leaves a half-written stub.
+export function applyFix({ rootDir, io = fs } = {}) {
+  const { toFix, scanned } = planFix({ rootDir, io });
+  for (const rel of toFix) {
+    const dest = path.join(rootDir, rel);
+    const { text } = normalizeText(io.readFileSync(dest, 'utf8'));
+    const tmp = `${dest}.tmp`;
+    try {
+      io.writeFileSync(tmp, text);
+      io.chmodSync(tmp, io.statSync(dest).mode & 0o777);
+      io.renameSync(tmp, dest);
+    } catch (err) {
+      try {
+        io.unlinkSync(tmp);
+      } catch {
+        void 0;
+      }
+      throw err;
+    }
+  }
+  return { fixed: toFix, scanned };
+}
+
+// Check: the drift verdict for --check. ok=true when no stale ref remains.
+export function check({ rootDir, io = fs } = {}) {
+  const files = listStubFiles({ rootDir, io });
+  const stale = [];
+  for (const rel of files) {
+    const refs = findStaleRefs(io.readFileSync(path.join(rootDir, rel), 'utf8'));
+    if (refs.length) stale.push({ file: rel, refs });
+  }
+  return { stale, ok: stale.length === 0, scanned: files.length };
+}

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.22.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/install/templates/.claude/skills/byan-byan-test/SKILL.md

@@ -1,12 +0,0 @@
----
-name: byan-byan-test
-description: BYAN Test - Token Optimized Version (-46%)
----
-
-# byan-test
-
-## Rules
-
-- This is a TEST version of BYAN optimized for token reduction (-46%)
-- Full agent: _byan/bmb/agents/byan-test.md (116 lines vs 215 original)
-- Original BYAN still available via bmad-agent-byan

package/install/templates/.claude/skills/byan-test-dynamic/SKILL.md

@@ -1,7 +0,0 @@
----
-name: byan-test-dynamic
-description: Test Dynamic Loading - Phase B Validation
----
-
-# test-dynamic
-

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;