create-byan-agent 2.21.0 → 2.23.0

package/CHANGELOG.md

@@ -9,6 +9,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+`byan_dispatch` fused two unrelated decisions into one route string
+(`mcp-worker-haiku`, `main-thread-opus`): a short sequential task was downgraded
+to haiku purely on its length, and a long one was pinned up to opus. That is the
+size-driven mis-tiering the native-workflow doctrine (`native-tiers.js`) was built
+to forbid, so the two routers disagreed. This decouples the two axes and makes
+`native-tiers.js` the single source of truth for the model tier across both worlds.
+
+- **Two independent axes.** `dispatch.js` now returns
+  `{ score, strategy, nature, tier, model, parallelizable, reasoning }`. STRATEGY
+  (where the work runs: `main-thread` / `agent-subagent-worktree` / `mcp-worker`)
+  stays derived from the scalar score + `parallelizable`. TIER (which model) is
+  derived from the task NATURE, decoupled from size.
+- **One source of truth.** `dispatch.js` imports `classifyLeaf` / `tierFor` /
+  `TIER_MODEL` directly from `native-tiers.js` — a one-way dependency toward the
+  tier authority rather than a duplicated rule. Only an `exploration` nature
+  downgrades to `haiku`; `implementation` / `verification` / `analysis` (and any
+  unmatched task) stay `deep` (inherit the session model). No pin-up to opus.
+- **Conservative by default.** An optional `nature` arg sets the tier directly;
+  absent or invalid, the task text is classified, whose own default is
+  `implementation` (deep) — so a miss protects the work instead of downgrading it.
+- **Consumers realigned.** The `byan_dispatch` tool schema gains an optional
+  `nature` enum; the three consuming skills (byan-byan Phase 4, byan-hermes-dispatch
+  step 3, byan-orchestrate) read `strategy` + `model` from the new shape. The
+  fused-route strings are dropped from the live routing path.
+- 22 dispatch unit tests pin the contract (no downgrade for protected natures,
+  exploration to haiku, no pin-up, conservative fallback, strategy preserved across
+  the score bands) plus the hermes-e2e non-regression. Template re-synced.
+
+### Known debt
+
+The legacy fused-route vocabulary (`mcp-worker-haiku` / `main-thread-opus`) still
+appears in two doctrine docs (`_byan/worker/workers.md`,
+`_byan/workflow/simple/byan/feature-workflow.md`) and a dead, unreferenced parallel
+router (`src/core/dispatcher/execution-router.js` + its test). These have no live
+consumer and are scoped to a follow-up cleanup.
+
 ## [2.21.0] - 2026-06-08
 
 ### Added - Template fidelity sync (the published package matches its CHANGELOG)

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

@@ -56,11 +56,16 @@ Never call `byan_update_apply` without explicit user consent. That tool returns
 
 ### Phase 4 — DISPATCH
 - **Who** : you + user. Route each feature to the right BYAN component.
-- **Decision table** per feature :
-  - **Score < 15** → inline main-thread, no subagent
-  - **Score 15-39 parallelizable** → agent-subagent-worktree (use `byan_dispatch` MCP tool to verify)
-  - **Score 15-39 sequential** → mcp-worker-haiku
-  - **Score ≥ 40** → main-thread-opus or delegate to `byan-hermes-dispatch`
+- **Decision table** per feature — TWO independent axes (`byan_dispatch` returns both) :
+  - **Strategy** (WHERE it runs), from the score :
+    - **Score < 15** → inline main-thread, no subagent
+    - **Score 15-39 parallelizable** → agent-subagent-worktree
+    - **Score 15-39 sequential** → mcp-worker
+    - **Score ≥ 40** → main-thread (heavy) or delegate to `byan-hermes-dispatch`
+  - **Model tier** (WHICH model), from the task NATURE — not its size (`byan_dispatch` returns it as `model`, via native-tiers, the single source of truth) :
+    - nature `exploration` (load/read/scan/list/parse/fetch...) → `haiku`
+    - nature `implementation` / `verification` / `analysis` / unknown → deep = **inherit the session model**
+    - Keep protected work (verify/analysis/implement) off haiku regardless of size ; no pin-up to opus. Pass an explicit `nature` to `byan_dispatch` when you know it.
 - **Output** : a table `{ feature → specialist → model → strategy → estimated_tokens }`.
 - **If no specialist matches** : halt. Ask user whether to run INT (agent recruitment) first. Do NOT fallback silently to general-purpose.
 - **Exit gate** : user validates the mapping.

package/install/templates/.claude/skills/byan-hermes-dispatch/SKILL.md

@@ -50,18 +50,19 @@ Match keywords against the routing table below. Pick the single best match. If n
 
 ### 3. Pick the execution strategy (MCP call)
 
-Call the `byan_dispatch` MCP tool with `{ task: <goal>, parallelizable: <bool> }`. It returns `{ strategy, score, reasoning }` where strategy is one of :
+Call the `byan_dispatch` MCP tool with `{ task: <goal>, parallelizable: <bool>, nature?: <leaf-type> }`. It returns `{ score, strategy, nature, tier, model, reasoning }` — TWO independent axes :
 
-- `main-thread` — do it inline, no delegation
-- `agent-subagent-worktree` — spawn Agent tool with isolation worktree
-- `mcp-worker-haiku` — spawn Agent tool with Haiku model, no worktree
-- `main-thread-opus` — keep in the current thread (don't delegate, Opus needed)
+- **strategy** (WHERE it runs), from the score :
+  - `main-thread` — do it inline, no delegation
+  - `agent-subagent-worktree` — spawn Agent tool with isolation worktree
+  - `mcp-worker` — spawn Agent tool, no worktree
+- **model** (WHICH model), from the task NATURE via native-tiers, not its size : `haiku` (exploration only) or `null` = deep (inherit the session model). Pass an explicit `nature` (`exploration`/`implementation`/`verification`/`analysis`) when you know it; protected natures stay off haiku.
 
 ### 4. Spawn the work
 
-Depending on strategy :
+Depending on strategy (apply the returned `model` whenever you spawn) :
 
-**`main-thread` or `main-thread-opus`** : do not spawn. Execute inline yourself.
+**`main-thread`** : do not spawn. Execute inline yourself — the work runs on the session model.
 
 **`agent-subagent-worktree`** : call the Agent tool with :
 ```
@@ -76,7 +77,9 @@ prompt: |
   When done, write a concise report (< 200 words).
 ```
 
-**`mcp-worker-haiku`** : same Agent tool call but without `isolation`, and add `model: "haiku"` in the prompt's instruction block if the receiving subagent honors it.
+**`mcp-worker`** : same Agent tool call but without `isolation`. Set the Agent's `model` to the returned `model` — `haiku` for exploration nature, otherwise omit `model` to inherit the session model. The tier follows the task nature, not its size.
+
+For any spawned strategy : pass `model` to the Agent tool when it is non-null; omit it when null so the subagent inherits the session model.
 
 ### 5. Specialist stub path lookup
 

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

@@ -9,7 +9,7 @@ You compose three existing building blocks into one multi-role flow :
 
 | Block | Role |
 |-------|------|
-| `byan_dispatch` MCP tool | Per-task execution strategy (main-thread / agent-subagent-worktree / mcp-worker-haiku / main-thread-opus) + complexity score |
+| `byan_dispatch` MCP tool | Per-task strategy (main-thread / agent-subagent-worktree / mcp-worker) from the score + model tier by NATURE (haiku for exploration, else inherit the session model) + complexity score |
 | `byan-hermes-dispatch` skill | Specialist lookup (architect, dev, analyst, …) from a routing table |
 | `party-mode-native` workflow | Parallel spawn via Agent tool + worktree + coordination JSON |
 
@@ -42,7 +42,7 @@ Use this a priori mapping — override only if the task clearly needs more :
 | architect, quinn, tea, creative-problem-solver | opus | Deep reasoning, trade-offs |
 | carmack, rachid, marc, patnote | haiku | Narrow mechanical tasks |
 
-Then call `byan_dispatch` with each role's goal to get a complexity score. If the score demands a different tier (score >= 40 → bump to opus ; score < 15 → inline, no subagent), **override the default for that role**.
+Then call `byan_dispatch` with each role's goal (and `nature` when known). Use its `score` for the STRATEGY only (score < 15 → inline, no subagent ; 15-39 → subagent/worker ; ≥ 40 → keep the heavy role in the main thread) and its nature-based `model` as the tier signal. The score sets WHERE the role runs, not WHICH model — keep protected roles (verify/analysis/implement) off haiku regardless of size, and avoid pinning a role up to opus on size alone. The per-role table above is the a-priori floor; `byan_dispatch`'s nature `model` refines it.
 
 ### 3. Compute the execution plan
 
@@ -69,7 +69,7 @@ Group roles by `parallelizable_with` graph. For each parallel cluster :
 
 - If cluster has N > 1 roles AND all use `agent-subagent-worktree` strategy → use the **party-mode-native** workflow : `coordination.initSession(roles, …)`, then dispatch all Agent tool calls in a single message.
 - If cluster has N = 1 OR strategy = `main-thread` → execute inline in the current turn.
-- If strategy = `mcp-worker-haiku` → spawn an Agent tool call WITHOUT worktree (faster boot, single-turn).
+- If strategy = `mcp-worker` → spawn an Agent tool call WITHOUT worktree (faster boot, single-turn) ; set the Agent's model to the role's nature-based `model` (haiku for exploration, omit otherwise to inherit the session model).
 
 For each Agent tool call, the prompt must start with :
 ```

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,14 +1023,14 @@ 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

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/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/dispatch.js

@@ -1,23 +1,75 @@
-export function dispatch({ task, complexity, parallelizable }) {
+import { classifyLeaf, tierFor, TIER_MODEL, LEAF_TYPES } from './native-tiers.js';
+
+// byan_dispatch routes a unit of work along TWO independent axes:
+//
+//   STRATEGY  — WHERE the work runs (inline / isolated subagent / mcp worker).
+//               Derived from the scalar score + parallelizable. This is
+//               dispatch's own concern: orchestration.
+//   TIER      — WHICH model the work deserves. Delegated to native-tiers (the
+//               single source of truth), keyed on the task's NATURE, never on its
+//               size. Only exploration downgrades to a cheap tier; implementation,
+//               verification, analysis (and anything unmatched) stay deep =
+//               inherit the session model. We never PIN UP to opus.
+//
+// Before this split the two axes were fused into one route string
+// ('mcp-worker-haiku', 'main-thread-opus'), so a short sequential task was
+// silently downgraded to haiku purely on length, and a long one was pinned up to
+// opus — exactly the size-driven mis-tiering native-tiers' anti-downgrade doctrine
+// forbids. The score still picks the strategy; the model now comes from nature.
+//
+// The dependency on native-tiers is intentional and one-directional: dispatch
+// CONSUMES the tier source of truth, it does not duplicate it. native-tiers is a
+// pure, IO-free module, so the import is safe and keeps the tiering doctrine in a
+// single place.
+
+const VALID_NATURES = new Set(Object.values(LEAF_TYPES));
+
+export function dispatch({ task, complexity, parallelizable, nature } = {}) {
   const score =
     typeof complexity === 'number'
       ? complexity
       : Math.min(100, Math.floor((task?.length || 0) / 10));
   const isPar = parallelizable === true;
 
-  let route, reasoning;
+  // Axis 1 — strategy (where). Scalar, as before, minus the fused model suffix.
+  let strategy, strategyReason;
   if (score < 15) {
-    route = 'main-thread';
-    reasoning = `Score ${score} < 15. Inline in current context, no delegation overhead.`;
+    strategy = 'main-thread';
+    strategyReason = `score ${score} < 15: inline, no delegation overhead`;
   } else if (score < 40 && isPar) {
-    route = 'agent-subagent-worktree';
-    reasoning = `Score ${score} + parallelizable. Spawn Claude Code Agent tool with worktree isolation.`;
+    strategy = 'agent-subagent-worktree';
+    strategyReason = `score ${score} + parallelizable: isolated subagent (worktree)`;
   } else if (score < 40) {
-    route = 'mcp-worker-haiku';
-    reasoning = `Score ${score}, sequential. Delegate to lightweight Haiku worker via MCP.`;
+    strategy = 'mcp-worker';
+    strategyReason = `score ${score}, sequential: delegated MCP worker`;
   } else {
-    route = 'main-thread-opus';
-    reasoning = `Score ${score} >= 40. Complex task, keep in main thread with Opus reasoning.`;
+    strategy = 'main-thread';
+    strategyReason = `score ${score} >= 40: heavy, kept in the main thread`;
   }
-  return { score, route, reasoning, parallelizable: isPar };
+
+  // Axis 2 — tier (which model). By nature, via native-tiers. An explicit, valid
+  // nature wins; otherwise classify the task text. An unknown nature falls back to
+  // classification rather than guessing, and classification's own default is
+  // IMPLEMENTATION (deep), so the conservative path is the worst case — protected
+  // work is never downgraded on a miss.
+  const leafType = VALID_NATURES.has(nature) ? nature : classifyLeaf({ label: task || '' });
+  const tier = tierFor(leafType);
+  const model = TIER_MODEL[tier]; // 'haiku' (exploration) or null (every other nature -> inherit session model). tierFor never auto-picks balanced/'sonnet'.
+
+  const tierReason =
+    model === null
+      ? `nature=${leafType} -> ${tier}: inherit the session model (protected, not downgraded)`
+      : `nature=${leafType} -> ${tier}: ${model}`;
+
+  // model applies to a DELEGATED strategy (subagent / mcp-worker leaf); for a
+  // main-thread strategy the work runs on the session model and model is advisory.
+  return {
+    score,
+    strategy,
+    nature: leafType,
+    tier,
+    model,
+    parallelizable: isPar,
+    reasoning: `${strategyReason}. ${tierReason}.`,
+  };
 }

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

@@ -292,7 +292,7 @@ const tools = [
   {
     name: 'byan_dispatch',
     description:
-      'BYAN Dispatcher: given a task description and complexity score (0-100), route it to the optimal execution target. Rule-based, no API call. Returns route and reasoning.',
+      'BYAN Dispatcher: routes a unit of work along two independent axes. STRATEGY (where it runs: main-thread / agent-subagent-worktree / mcp-worker) from the scalar score + parallelizable. TIER (which model) from the task NATURE via native-tiers (the single source of truth): only exploration downgrades to haiku; implementation/verification/analysis stay deep (inherit the session model); never pins up to opus. Rule-based, no API call. Returns { score, strategy, nature, tier, model, reasoning }.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -305,6 +305,11 @@ const tools = [
           type: 'boolean',
           description: 'Is the task parallelizable with other tasks?',
         },
+        nature: {
+          type: 'string',
+          enum: ['exploration', 'implementation', 'verification', 'analysis'],
+          description: 'Optional task nature. A valid value sets the model tier directly; otherwise the nature is classified from the task text. Only exploration is downgrade-safe.',
+        },
       },
       required: ['task'],
       additionalProperties: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.21.0",
+  "version": "2.23.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/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
-