create-byan-agent 2.18.0 → 2.19.0

package/install/templates/_byan/mcp/byan-mcp-server/bin/byan-rewrite-refs.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { rewriteTree } from '../lib/rewrite-refs.js';
+
+// Rewrite intra-file _byan/ path references to their post-migration location.
+// Usage: node bin/byan-rewrite-refs.js [--root <dir>] [--apply] [--verbose]
+// Default is a dry-run (nothing is written). Pass --apply to rewrite in place.
+// Run this in the SAME atomic step as byan-migrate-fs --apply (after the moves).
+
+function parseArgs(argv) {
+  const args = { apply: false, verbose: false };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--root') args.projectRoot = argv[++i];
+    else if (argv[i] === '--apply') args.apply = true;
+    else if (argv[i] === '--verbose') args.verbose = true;
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv);
+const r = rewriteTree({ projectRoot: args.projectRoot, apply: args.apply });
+process.stdout.write(
+  `[byan-rewrite-refs] ${r.applied ? 'APPLY' : 'dry-run'} — ` +
+    `scanned ${r.filesScanned}, changed ${r.filesChanged}, refs rewritten ${r.refsRewritten}\n`
+);
+if (args.verbose) {
+  for (const f of r.files) {
+    process.stdout.write(`  ${f.file} (${f.count})\n`);
+    for (const c of f.changes) process.stdout.write(`      ${c.from} -> ${c.to}\n`);
+  }
+}
+if (!r.applied) {
+  process.stdout.write('Dry-run only. Re-run with --apply to rewrite in place.\n');
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/migration-map.js

@@ -23,8 +23,22 @@ const KEEP_FILES = ['_byan/INDEX.md'];
 const BYAN_ROOT_SOUL = new Set([
   'soul.md', 'tao.md', 'soul-memory.md',
   'byan-soul.md', 'byan-tao.md', 'byan-soul-memory.md',
+  'creator-soul.md',
 ]);
 
+// Module-scoped infra with no by-type home: module config + help + teams + data,
+// and core base/activation/model-selector machinery. Retained in place by a
+// deliberate non-breaking choice (read by name; the authoritative byan_version
+// lives in a module config; soul-activation/CLAUDE.md reference these from
+// outside _byan). Folding them is a separate design decision, not a silent move.
+function isRetainedModuleScoped(rel) {
+  if (/^_byan\/(core|bmm|bmb|tea|cis)\/(config\.yaml|module-help\.csv)$/.test(rel)) return true;
+  if (/^_byan\/(core|bmm|bmb|tea|cis)\/(teams|data)\//.test(rel)) return true;
+  if (/^_byan\/core\/(base|activation)\//.test(rel)) return true;
+  if (/^_byan\/core\/(MODEL-SELECTOR-GUIDE\.md|model-selector\.(?:js|ya?ml))$/.test(rel)) return true;
+  return false;
+}
+
 function norm(p) {
   return String(p).split(path.sep).join('/').replace(/^\.\//, '');
 }
@@ -108,6 +122,20 @@ export function mapPath(sourceRel, { disambiguate = false } = {}) {
     return { target: `_byan/connaissance/${knMatch[1]}`, type: 'connaissance', scope: 'systeme', provenance: null, action: 'move' };
   }
 
+  // 7b. Module testarch subtree -> connaissance/testarch/ (substructure
+  // preserved verbatim, incl. the knowledge/ segment, so file refs and dir refs
+  // map consistently; tea-index.csv rides along).
+  const testarchMatch = rel.match(/^_byan\/(core|bmm|bmb|tea|cis)\/testarch\/(.+)$/);
+  if (testarchMatch) {
+    return { target: `_byan/connaissance/testarch/${testarchMatch[2]}`, type: 'connaissance', scope: 'systeme', provenance: testarchMatch[1], action: 'move' };
+  }
+
+  // 7c. Module resource docs (e.g. excalidraw helpers) -> connaissance/.
+  const resMatch = rel.match(/^_byan\/(core|bmm|bmb|tea|cis)\/resources\/(.+)$/);
+  if (resMatch) {
+    return { target: `_byan/connaissance/${resMatch[2]}`, type: 'connaissance', scope: 'systeme', provenance: resMatch[1], action: 'move' };
+  }
+
   // 8. _memory -> memoire/.
   const memMatch = rel.match(/^_byan\/_memory\/(.+)$/);
   if (memMatch) {
@@ -120,9 +148,22 @@ export function mapPath(sourceRel, { disambiguate = false } = {}) {
     return { target: `_byan/agent/byan/${baseName}`, type, scope: 'systeme', provenance: 'byan', action: 'move' };
   }
 
-  // 10. workers.md -> formalisation worker/ (D3), needs manual split.
+  // 10. workers.md -> worker/ (D3). A single concept doc, moved whole;
+  // formalising it into per-worker files is a later refinement, not a split here.
   if (rel === '_byan/workers.md') {
-    return { target: '_byan/worker/', type: 'worker', scope: 'systeme', provenance: null, action: 'review' };
+    return { target: '_byan/worker/workers.md', type: 'worker', scope: 'systeme', provenance: null, action: 'move' };
+  }
+
+  // 10b. workers/ directory (launchers etc.) -> worker/.
+  const workersDirMatch = rel.match(/^_byan\/workers\/(.+)$/);
+  if (workersDirMatch) {
+    return { target: `_byan/worker/${workersDirMatch[1]}`, type: 'worker', scope: 'systeme', provenance: null, action: 'move' };
+  }
+
+  // 10c. Module-scoped infra with no by-type home -> keep in place (see
+  // isRetainedModuleScoped). Explicit retain, not a silent skip.
+  if (isRetainedModuleScoped(rel)) {
+    return { target: rel, type: 'module-infra', scope: 'systeme', provenance: rel.split('/')[1], action: 'keep' };
   }
 
   // 11. Anything else -> review (no silent move/skip).
@@ -150,20 +191,34 @@ export function buildMigrationPlan({ projectRoot } = {}) {
     return { from, to: m.target || (m.targets ? m.targets : null), action: m.action, type: m.type, provenance: m.provenance };
   });
 
-  // Collision resolution: any 'move' target claimed by >1 source is re-mapped
-  // with provenance disambiguation.
+  // Collision resolution: any 'move' target claimed by >1 source.
   const byTarget = new Map();
   for (const e of entries) {
     if (e.action !== 'move' || typeof e.to !== 'string') continue;
     if (!byTarget.has(e.to)) byTarget.set(e.to, []);
     byTarget.get(e.to).push(e);
   }
+  const isFlatAgent = (e) => /^_byan\/agents\//.test(e.from);
   for (const [, group] of byTarget) {
     if (group.length < 2) continue;
-    for (const e of group) {
-      const m = mapPath(e.from, { disambiguate: true });
-      e.to = m.target;
-      e.disambiguated = true;
+    const moduleMembers = group.filter((e) => !isFlatAgent(e));
+    const flatMembers = group.filter(isFlatAgent);
+    if (moduleMembers.length === 1 && flatMembers.length === group.length - 1) {
+      // flat-vs-module duplicate: the MODULE agent wins the canonical target;
+      // the flat copies are preserved under agent/<name>-flat/ (non-destructive).
+      for (const e of flatMembers) {
+        e.to = e.to.replace(/^(_byan\/agent\/)([^/]+)\//, '$1$2-flat/');
+        e.disambiguated = true;
+        e.superseded = true;
+      }
+    } else {
+      // genuine cross-module collision (e.g. two distinct "dev" agents): keep
+      // provenance disambiguation for every member.
+      for (const e of group) {
+        const m = mapPath(e.from, { disambiguate: true });
+        e.to = m.target;
+        e.disambiguated = true;
+      }
     }
   }
 

package/install/templates/_byan/mcp/byan-mcp-server/lib/rewrite-refs.js

@@ -0,0 +1,109 @@
+// BYAN intra-file reference rewriter (F16 / Stage B).
+//
+// The FS migrator (F8) moves files; it does NOT touch the path references that
+// live INSIDE content files (agent bodies, workflow steps, knowledge docs).
+// After a move, a body that says "load {project-root}/_byan/tea/testarch/
+// knowledge/x.md" points at a dead path. This rewriter closes that gap: it
+// rewrites every `_byan/...` reference in a content file to its post-migration
+// location, using the SAME authority as the mover (mapPath). A reference is
+// rewritten only when mapPath classifies it as a 'move' (files) or a moved
+// directory; 'split' (config.yaml) and 'keep' references are left untouched, so
+// the rewrite is safe and idempotent (a second pass is a no-op).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { mapPath } from './migration-map.js';
+
+// Token = a `_byan/...` path reference. Path chars: word chars, dot, slash, dash.
+const REF_RE = /_byan\/[\w.\/-]+/g;
+
+// Extensions whose free text can carry path references. Code (mcp/) and the CSV
+// manifests (_byan/_config, rewritten column-aware by manifest-reconcile, F6)
+// are excluded so each concern owns its rewrite.
+const CONTENT_EXT = new Set(['.md', '.xml', '.yaml', '.yml', '.csv']);
+const SENTINEL = '__byan_probe__';
+
+// Resolve one captured reference to its post-migration form, or null if it must
+// stay unchanged. Handles both a file ref (mapPath directly) and a directory
+// ref (probe mapPath with a sentinel child and keep the rename only when the
+// suffix is preserved — which holds for prefix renames like knowledge ->
+// connaissance, but NOT for agents/ which restructure, so agent dir refs are
+// deliberately left alone).
+export function resolveRef(ref) {
+  const trailingSlash = ref.endsWith('/');
+  const clean = ref.replace(/\/+$/, '');
+
+  const direct = mapPath(clean);
+  if (direct.action === 'move' && typeof direct.target === 'string') {
+    return direct.target + (trailingSlash ? '/' : '');
+  }
+
+  // Probe with a sentinel FILE child. Accept the rename only when the target is
+  // a clean prefix rename: it ends with /<sentinel>.md AND the rewritten parent
+  // does not itself contain the sentinel (which happens for agents/, where the
+  // sentinel becomes the folder name — a restructure, not a prefix rename).
+  const probe = mapPath(`${clean}/${SENTINEL}.md`);
+  const suffix = `/${SENTINEL}.md`;
+  if (probe.action === 'move' && typeof probe.target === 'string' && probe.target.endsWith(suffix)) {
+    const newDir = probe.target.slice(0, -suffix.length);
+    if (!newDir.includes(SENTINEL)) return newDir + (trailingSlash ? '/' : '');
+  }
+  return null;
+}
+
+// Rewrite every reference in a blob of text. Returns { text, changes } where
+// changes is [{ from, to }]. Idempotent: text already on the target layout maps
+// to itself (action 'keep') and is not touched.
+export function rewriteText(text) {
+  const changes = [];
+  const out = text.replace(REF_RE, (token) => {
+    // peel a trailing run of dots (sentence punctuation) off the path token
+    const core = token.replace(/\.+$/, '');
+    const trail = token.slice(core.length);
+    const mapped = resolveRef(core);
+    if (!mapped || mapped === core) return token;
+    changes.push({ from: core, to: mapped });
+    return mapped + trail;
+  });
+  return { text: out, changes };
+}
+
+function isContentFile(rel) {
+  if (rel.startsWith('_byan/mcp/')) return false; // code + its tests
+  if (rel.startsWith('_byan/_config/')) return false; // manifests: F6 owns these
+  return CONTENT_EXT.has(path.extname(rel));
+}
+
+function walk(dir, root, acc) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.name === 'node_modules' || e.name === '.git') continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) walk(full, root, acc);
+    else acc.push(full);
+  }
+  return acc;
+}
+
+// Rewrite every content file under _byan/. Dry-run by default (apply=false):
+// computes changes, writes nothing. Returns a report.
+export function rewriteTree({ projectRoot, apply = false } = {}) {
+  const root = projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const byanDir = path.join(root, '_byan');
+  const report = { applied: Boolean(apply), filesScanned: 0, filesChanged: 0, refsRewritten: 0, files: [] };
+  if (!fs.existsSync(byanDir)) return report;
+
+  for (const abs of walk(byanDir, root, [])) {
+    const rel = path.relative(root, abs).split(path.sep).join('/');
+    if (!isContentFile(rel)) continue;
+    report.filesScanned += 1;
+    let text;
+    try { text = fs.readFileSync(abs, 'utf8'); } catch { continue; }
+    const { text: out, changes } = rewriteText(text);
+    if (!changes.length) continue;
+    report.filesChanged += 1;
+    report.refsRewritten += changes.length;
+    report.files.push({ file: rel, count: changes.length, changes });
+    if (apply) fs.writeFileSync(abs, out);
+  }
+  return report;
+}

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

@@ -1,39 +1,59 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-const DEFAULT_FILES = {
-  soul: '_byan/soul.md',
-  tao: '_byan/tao.md',
-  'soul-memory': '_byan/soul-memory.md',
+// BYAN's soul/tao/soul-memory files. The Gen3 layout moves them under the
+// agent's own folder (_byan/agent/byan/<file>); the legacy Gen2 layout keeps
+// them at the _byan/ root. This module is the read-side authority for the MCP
+// server (an ESM package shipped standalone, so it carries its own small
+// resolver rather than importing the root CJS layout-resolver). The ordering
+// mirrors that resolver: existing file wins; for a write to a not-yet-existing
+// file, prefer Gen3 when its directory is present, else default to Gen2.
+
+const SOUL_FILES = {
+  soul: 'soul.md',
+  tao: 'tao.md',
+  'soul-memory': 'soul-memory.md',
 };
+const BYAN_AGENT = 'byan';
 
 export function resolveProjectRoot(envRoot) {
   return envRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
 }
 
+// Resolve one soul file Gen3-first, Gen2 fallback. Returns { rel, abs, exists }.
+export function resolveSoulFile(which, root) {
+  const file = SOUL_FILES[which];
+  if (!file) return null;
+  const gen3rel = `_byan/agent/${BYAN_AGENT}/${file}`;
+  const gen2rel = `_byan/${file}`;
+  const g3 = path.join(root, gen3rel);
+  const g2 = path.join(root, gen2rel);
+  if (fs.existsSync(g3)) return { rel: gen3rel, abs: g3, exists: true };
+  if (fs.existsSync(g2)) return { rel: gen2rel, abs: g2, exists: true };
+  if (fs.existsSync(path.dirname(g3))) return { rel: gen3rel, abs: g3, exists: false };
+  return { rel: gen2rel, abs: g2, exists: false };
+}
+
 export function readSoul({ which = 'all', projectRoot }) {
   const root = resolveProjectRoot(projectRoot);
   const targets =
     which === 'all'
-      ? Object.keys(DEFAULT_FILES)
-      : [which].filter((k) => DEFAULT_FILES[k]);
+      ? Object.keys(SOUL_FILES)
+      : [which].filter((k) => SOUL_FILES[k]);
 
   if (targets.length === 0) {
     throw new Error(
-      `Unknown soul target: "${which}". Valid: ${Object.keys(DEFAULT_FILES).join(', ')} or "all".`
+      `Unknown soul target: "${which}". Valid: ${Object.keys(SOUL_FILES).join(', ')} or "all".`
     );
   }
 
   const result = {};
   for (const key of targets) {
-    const p = path.join(root, DEFAULT_FILES[key]);
-    if (fs.existsSync(p)) {
-      result[key] = {
-        path: DEFAULT_FILES[key],
-        content: fs.readFileSync(p, 'utf8'),
-      };
+    const r = resolveSoulFile(key, root);
+    if (r.exists) {
+      result[key] = { path: r.rel, content: fs.readFileSync(r.abs, 'utf8') };
     } else {
-      result[key] = { path: DEFAULT_FILES[key], content: null, missing: true };
+      result[key] = { path: r.rel, content: null, missing: true };
     }
   }
   return result;
@@ -50,15 +70,15 @@ export function appendSoulMemory({ entry, projectRoot, validated = false, now =
   }
 
   const root = resolveProjectRoot(projectRoot);
-  const p = path.join(root, DEFAULT_FILES['soul-memory']);
+  const r = resolveSoulFile('soul-memory', root);
   const stamp = now.toISOString().slice(0, 10);
   const block = `\n\n---\n\n## Entree ${stamp}\n\n${entry.trim()}\n`;
 
-  const dir = path.dirname(p);
+  const dir = path.dirname(r.abs);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 
-  const existing = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '# Soul-Memory — Journal vivant BYAN\n';
-  fs.writeFileSync(p, existing + block);
+  const existing = fs.existsSync(r.abs) ? fs.readFileSync(r.abs, 'utf8') : '# Soul-Memory — Journal vivant BYAN\n';
+  fs.writeFileSync(r.abs, existing + block);
 
-  return { path: DEFAULT_FILES['soul-memory'], appended_chars: block.length };
+  return { path: r.rel, appended_chars: block.length };
 }

package/install/templates/_byan/soul-memory-reference.md

@@ -1,6 +1,6 @@
 # Soul Memory — BYAN
 *Journal vivant. Évolue par l'expérience.*
-*Source : `_byan/soul.md`*
+*Source : `_byan/agent/byan/soul.md`*
 
 **last-revision:** 2026-02-21
 **revision-interval-days:** 14

package/install/templates/_byan/soul-memory-template.md

@@ -1,6 +1,6 @@
 # Soul Memory — BYAN
 *Journal vivant. Evolue par l'experience.*
-*Source : `_byan/soul.md`*
+*Source : `_byan/agent/byan/soul.md`*
 
 **last-revision:** [date]
 **revision-interval-days:** 14

package/install/templates/_byan/soul-template.md

@@ -1,6 +1,6 @@
 # Soul — BYAN
 *Distille depuis l'ame de [Votre Nom]. Forge le [date].*
-*Source : `_byan/creator-soul.md`*
+*Source : `_byan/agent/byan/creator-soul.md`*
 
 ---
 
@@ -82,4 +82,4 @@ Chaque agent que je forge porte un fragment de cette ame.
 
 ---
 
-*Source : `_byan/creator-soul.md`*
+*Source : `_byan/agent/byan/creator-soul.md`*

package/install/templates/_byan/tea/module-help.csv

@@ -1,10 +1,10 @@
 module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
-tea,0-learning,Teach Me Testing,TMT,10,_byan/tea/workflows/testarch/teach-me-testing/workflow.md,bmad_tea_teach-me-testing,false,tea,Create Mode,"Teach testing fundamentals through 7 sessions (TEA Academy)",test_artifacts,"progress file|session notes|certificate",
-tea,3-solutioning,Test Framework,TF,10,_byan/tea/workflows/testarch/framework/workflow.yaml,bmad_tea_framework,false,tea,Create Mode,"Initialize production-ready test framework",test_artifacts,"framework scaffold",
-tea,3-solutioning,CI Setup,CI,20,_byan/tea/workflows/testarch/ci/workflow.yaml,bmad_tea_ci,false,tea,Create Mode,"Configure CI/CD quality pipeline",test_artifacts,"ci config",
-tea,3-solutioning,Test Design,TD,30,_byan/tea/workflows/testarch/test-design/workflow.yaml,bmad_tea_test-design,false,tea,Create Mode,"Risk-based test planning",test_artifacts,"test design document",
-tea,4-implementation,ATDD,AT,10,_byan/tea/workflows/testarch/atdd/workflow.yaml,bmad_tea_atdd,false,tea,Create Mode,"Generate failing tests (TDD red phase)",test_artifacts,"atdd tests",
-tea,4-implementation,Test Automation,TA,20,_byan/tea/workflows/testarch/automate/workflow.yaml,bmad_tea_automate,false,tea,Create Mode,"Expand test coverage",test_artifacts,"test suite",
-tea,4-implementation,Test Review,RV,30,_byan/tea/workflows/testarch/test-review/workflow.yaml,bmad_tea_test-review,false,tea,Validate Mode,"Quality audit (0-100 scoring)",test_artifacts,"review report",
-tea,4-implementation,NFR Assessment,NR,40,_byan/tea/workflows/testarch/nfr-assess/workflow.yaml,bmad_tea_nfr-assess,false,tea,Create Mode,"Non-functional requirements",test_artifacts,"nfr report",
-tea,4-implementation,Traceability,TR,50,_byan/tea/workflows/testarch/trace/workflow.yaml,bmad_tea_trace,false,tea,Create Mode,"Coverage traceability and gate",test_artifacts,"traceability matrix|gate decision",
+tea,0-learning,Teach Me Testing,TMT,10,_byan/workflow/simple/testarch/teach-me-testing/workflow.md,bmad_tea_teach-me-testing,false,tea,Create Mode,"Teach testing fundamentals through 7 sessions (TEA Academy)",test_artifacts,"progress file|session notes|certificate",
+tea,3-solutioning,Test Framework,TF,10,_byan/workflow/simple/testarch/framework/workflow.yaml,bmad_tea_framework,false,tea,Create Mode,"Initialize production-ready test framework",test_artifacts,"framework scaffold",
+tea,3-solutioning,CI Setup,CI,20,_byan/workflow/simple/testarch/ci/workflow.yaml,bmad_tea_ci,false,tea,Create Mode,"Configure CI/CD quality pipeline",test_artifacts,"ci config",
+tea,3-solutioning,Test Design,TD,30,_byan/workflow/simple/testarch/test-design/workflow.yaml,bmad_tea_test-design,false,tea,Create Mode,"Risk-based test planning",test_artifacts,"test design document",
+tea,4-implementation,ATDD,AT,10,_byan/workflow/simple/testarch/atdd/workflow.yaml,bmad_tea_atdd,false,tea,Create Mode,"Generate failing tests (TDD red phase)",test_artifacts,"atdd tests",
+tea,4-implementation,Test Automation,TA,20,_byan/workflow/simple/testarch/automate/workflow.yaml,bmad_tea_automate,false,tea,Create Mode,"Expand test coverage",test_artifacts,"test suite",
+tea,4-implementation,Test Review,RV,30,_byan/workflow/simple/testarch/test-review/workflow.yaml,bmad_tea_test-review,false,tea,Validate Mode,"Quality audit (0-100 scoring)",test_artifacts,"review report",
+tea,4-implementation,NFR Assessment,NR,40,_byan/workflow/simple/testarch/nfr-assess/workflow.yaml,bmad_tea_nfr-assess,false,tea,Create Mode,"Non-functional requirements",test_artifacts,"nfr report",
+tea,4-implementation,Traceability,TR,50,_byan/workflow/simple/testarch/trace/workflow.yaml,bmad_tea_trace,false,tea,Create Mode,"Coverage traceability and gate",test_artifacts,"traceability matrix|gate decision",

package/install/templates/_byan/tea/teams/default-party.csv

@@ -1,2 +1,2 @@
 name,displayName,title,icon,role,identity,communicationStyle,principles,module,path
-"tea","Murat","Master Test Architect","🧪","Master Test Architect","Test architect specializing in CI/CD, automated frameworks, and scalable quality gates.","Blends data with gut instinct. 'Strong opinions, weakly held' is their mantra. Speaks in risk calculations and impact assessments.","Risk-based testing. Depth scales with impact. Quality gates backed by data. Tests mirror usage. Flakiness is critical debt. Tests first, AI implements, suite validates.","tea","_byan/tea/agents/tea.agent.yaml"
+"tea","Murat","Master Test Architect","🧪","Master Test Architect","Test architect specializing in CI/CD, automated frameworks, and scalable quality gates.","Blends data with gut instinct. 'Strong opinions, weakly held' is their mantra. Speaks in risk calculations and impact assessments.","Risk-based testing. Depth scales with impact. Quality gates backed by data. Tests mirror usage. Flakiness is critical debt. Tests first, AI implements, suite validates.","tea","_byan/agent/tea.agent.yaml/tea.agent.yaml"