create-byan-agent 2.22.0 → 2.23.0

package/CHANGELOG.md

@@ -9,6 +9,35 @@ 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

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/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/package.json

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