create-byan-agent 2.19.2 → 2.20.1

package/CHANGELOG.md

@@ -7,6 +7,208 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [Unreleased]
+
+## [2.20.1] - 2026-06-04
+
+### Fixed - Post-audit hotfix (adversarial self-audit of 2.20.0)
+
+- **N2 skill crash guard.** The shipped `byan-mantra-audit` skill invoked
+  `src/byan-v2/generation/mantra-audit.js` blindly; a generated / npm-installed
+  project does not ship that runtime, so the skill crashed with MODULE_NOT_FOUND.
+  The skill now checks for the runtime first and degrades with a clear message. The
+  deeper installer bug (the v2 runtime is not delivered to generated projects today,
+  so the mantra gate stays a silent no-op there) is tracked as a separate chantier;
+  the pre-commit gate and Stop hook already self-guard rather than crash.
+- **scope-resolver precedence collapse.** An all-invalid `mantra_scopes` frontmatter
+  (e.g. a `sdlc-cod` typo) silently collapsed a persona to universal-only, weakening
+  the anti-stub floor it feeds. It now falls through to the agent/module map when no
+  named scope is valid; an explicit `[universal]` is still honored. Regression-tested.
+- **CHANGELOG accuracy (2.20.0).** The CIS floor figures paired inconsistent
+  before-baselines; corrected to a single univ-only baseline.
+- **Dead mantras documented.** M8 is not the only zero-match mantra under the keyword
+  validator: M1 (Un seul responsable), M6 (INVEST), M28 (Sprint review) also match
+  0/12 of their sdlc-process personas. Flagged for a future keyword / coverage pass.
+
+### Fixed - Full jest suite green (35 -> 0 failures, all legitimate)
+
+A clean `npm install && npm test` surfaced 35 pre-existing failures across 12 suites
+(none from the mantra work, proven by git). All fixed without weakening an assertion:
+
+- **VoiceIntegration crash.** It called `this.logger.debug/warn`, which a minimal
+  logger lacks, killing the jest worker (and cascading into system-integration and
+  full-bmad). Hardened the consumer with a level-fallback shim, added the missing
+  `Logger.debug`, crash-proofed the detached voice-init in index.js, added the
+  `SessionState` get/set store it relied on, and removed an emoji from source.
+- **Stale unit tests realigned.** active-listener (`confirmed` -> live `validated`)
+  and glossary-builder (string -> the live `{reason, suggestions}` object API) were
+  brought up to the shipped contract two integration suites already prove; assertions
+  were tightened, not lowered.
+- **node:test files de-conflicted from jest.** The `/api/*`, `fs-migration-hook` and
+  `e2e-remote-import` suites run under `node --test`; jest's broad glob swept them up.
+  Excluded via `testPathIgnorePatterns` (they keep their own runner).
+- **Perf microbench stabilized.** The construction-overhead test measured 1ms
+  scheduling jitter; replaced with an interleaved median-of-200 hrtime measurement
+  and a 20ms absolute ceiling that still catches a real regression.
+- **Hermetic env.** `jest.setup.js` strips ambient `BYAN_API_*` so staging/flush
+  suites no longer pass or fail by accident depending on the dev/CI shell.
+- **Installer feature implemented (FD 20260428).** `setupClaudeNative` now writes the
+  `enabledMcpjsonServers` whitelist to `.claude/settings.local.json` (byan + accepted
+  extensions, idempotent), strips `BYAN_API_TOKEN` from `.mcp.json` (template + code),
+  and honors the caller's `apiUrl` (new `install/lib/settings-local.js`). The stale
+  `e2e-install-update` test (asserting the pre-security token-in-.mcp.json contract)
+  was removed; correct-contract coverage lives in migrate-mcp-config + post-install.e2e.
+
+Result: 104 suites / 2039 tests green.
+
+## [2.20.0] - 2026-06-04
+
+### Changed - Mantra taxonomy v2: sdlc-ops split + creative family (corpus 64 -> 71)
+
+The N2 embodiment audit surfaced two taxonomy biases. (1) sdlc-code conflated
+code-craft with release/ops, so a dev agent was judged against release mantras it
+never performs. (2) The corpus had no creative mantra, so the six CIS agents were
+scored only against analytical principles that are the opposite of their craft.
+
+- **sdlc-ops scope.** Six release/deploy mantras (M8 freeze, M16 semver, M17
+  changelog, M18 env parity, M19 CI/CD, M20 rollback) move from sdlc-code to a new
+  `sdlc-ops` scope. Deploy/ops agents (rachid, patnote, yanstaller, marc, codex,
+  claude) gain it; dev/architect shed it (they craft, not release).
+- **Creative family (7 mantras, CR-1..CR-7).** A new `creative` scope + category,
+  derived from the real CIS personas: Diverge Before Converge (brainstorming),
+  Anchor in the Human Need (design-thinking), Reframe to the Root Cause
+  (problem-solving), Judge Ideas by New Value (innovation), Find the Authentic
+  Story (storytelling), Serve the Audience's Attention (presentation), Prototype-
+  Test-Pivot (iteration). The 6 CIS agents are now scored on their own craft.
+- **scope-resolver** registers the two new scopes in `VALID_SCOPES` so they are
+  not silently dropped at resolution (the design's own Zero-Trust blocker).
+- **Corpus 64 -> 71.** metadata recomputed (scopes, categories, priorityLevels);
+  the strict 12-mantra regime is byte-untouched. No-scope total tests updated to
+  71; the all-five-scopes union test drops 60 -> 54 as the six ops mantras leave
+  sdlc-code. Keyword lists were cleaned of over-broad signals per an adversarial
+  review.
+
+Measured (floor, univ-only baseline -> univ+creative): dev sheds ops (applicable
+42 -> 36). The CIS agents are scored on their own craft, which shifts the floor by
+relevance rather than uniformly: brainstorming-coach 45 -> 48, innovation-strategist
+65 -> 59 (it matches fewer of its own creative mantras in vocabulary).
+
+### Changed - Domain-aware mantra validator (Option C: N1 anti-stub floor + N2 embodiment audit)
+
+The mantra compliance bar was an all-64 keyword-density proxy with an 80% gate
+that focused personas did not reach (measured median 11%, 0 of 120 gated files at
+>= 80%): it implicitly graded each agent as a software-delivery agent, so a UX or
+storyteller persona was failed for missing Scrum/Merise vocabulary. The gate
+stayed green only through broad exemptions, masking the mis-fit. This reworks the
+metric to score each persona only against the mantras that apply to it.
+
+- **Taxonomy.** Each of the 64 mantras carries a `scope`
+  (`universal` | `sdlc-process` | `sdlc-code` | `sdlc-modeling` | `sdlc-test`) in
+  `mantras.json`. The four runtime-enforced mantras (IA-1, IA-9, IA-21, IA-23,
+  checked by hooks / fact-check rather than declared in a persona file) are
+  flagged `behavioral` and excluded from persona-file scoring.
+- **Domain-aware validator.** `validate(def, { scope })` scores only the
+  applicable subset (universal + the persona's declared scope, behavioral
+  excluded); `totalMantras` becomes the applicable count. With no scope it scores
+  all 64 (legacy behavior preserved, existing tests untouched). A reusable
+  `applicableMantras(scope)` is exposed. Score bands moved to single constants.
+- **Per-agent scope resolution.** `scope-resolver.js` resolves a persona to its
+  scope set, precedence explicit-frontmatter > per-agent map > module-derived >
+  `universal`, with `universal` force-unioned. The map lives in
+  `src/byan-v2/data/agent-scopes.json`.
+- **Emoji-icon fix.** The no-emoji mantra (IA-23) excludes `icon="..."`
+  frontmatter attributes from its scan (an icon glyph is display metadata, not
+  pollution); a real emoji in the body is still caught.
+- **Anti-stub floor, honestly named.** The pre-commit gate and Stop hook score the
+  canonical Gen3 persona sources (`_byan/agent/<name>/<name>.md`) domain-aware at a
+  floor of 30 (the real roster spans 34-73, median 50). It is an anti-stub /
+  anti-zombie floor, not a deep quality bar.
+- **N2 embodiment audit (out-of-band).** `src/byan-v2/generation/mantra-audit.js` (`prepare` /
+  `score`) plus the `byan-mantra-audit` skill measure genuine embodiment via an
+  LLM judge, kept out of the commit path (the judgment is semantic).
+- **Bugs fixed in passing.** B1: the stale `install/templates/.githooks/pre-commit`
+  mirror is re-synced (it lagged the source, missing the workflow-lint block). B2:
+  the gate no longer targets empty legacy dirs (`_byan/agents`, `_byan/bmb/agents`),
+  it targets the real sources. B3: the FD VALIDATE wording (SKILL, fd-phase-guard,
+  feature-workflow, GUIDE) is realigned to the floor, no longer asserting an
+  unreachable 80%. Config `categories` is revived as `scopes`.
+
+New unit tests: scope filtering, behavioral exclusion, emoji-icon, scope-resolver,
+N2 audit. Strict regime (12 mantras, byan-strict at 100%) untouched.
+
+### Added - Native workflow bridge, Phase 1 (Hybrid: gate outside, engine inside)
+
+BYAN workflows are LLM-interpreted and human-gated; Claude Code's in-CLI Workflow
+tool runs a deterministic JS script with no in-run human gate. Phase 1 ports the
+non-gated subset (autonomous + deterministic pipeline) to the native tool, while
+the gated majority stays markdown by design. Scope is coupled to target: broad
+coverage (gated workflows) would need the Agent SDK and is parked (Phase 2).
+
+- **F1 — registry + dual-path resolver.** `byan-build-workflows`
+  (`_byan/mcp/byan-mcp-server/bin/`, ESM, sibling to `byan-build-index`) reads
+  the workflow manifest and writes `.claude/workflows/INDEX.md` idempotently
+  (20 portable workflows: 11 autonomous + 9 pipeline). `resolveWorkflow(name)`
+  prefers `.claude/workflows/<name>.js`, else falls back to the markdown workflow
+  (Gen3-first dual-path).
+- **F2 — pilot port `dev-story`.** `.claude/workflows/dev-story.js` runs the
+  red-green-refactor loop as a JS `while` loop with a real 3-cycle convergence
+  counter (replacing the doc-only "3 failures -> HALT" rule). The deterministic
+  core lives in `lib/native-loop.js` (unit-tested) and is mirrored inline since
+  the sandbox forbids imports. The script returns a structured verdict; the
+  `byan-native-dev-story` skill owns the human gate and records state via MCP.
+- **F3 — enforcement bridge.** `byan-lint-workflows` fails if a
+  `.claude/workflows/*.js` imports/requires `lib/fd-state.js` (or the strict-mode
+  lib); wired into `.githooks/pre-commit` since the in-session hooks do not fire
+  inside a script. Contract documented in `docs/native-workflows-contract.md` and
+  `.claude/rules/native-workflows.md`.
+
+25 new unit tests (node --test). Mirrored into `install/templates/`.
+
+- **F4 + F5 - the 19 remaining portable workflows ported.** Every autonomous
+  (10: create-story, qa-automate, the 8 testarch-*) and pipeline (9:
+  check-implementation-readiness, code-review, the 4 create-excalidraw-*,
+  document-project, quick-dev, sprint-planning) workflow now has a faithful
+  native `.claude/workflows/<name>.js` that mirrors its real source steps. Each
+  keeps human gates OUT of the script (returns a structured verdict), uses no
+  import/state-coupling/wall-clock/RNG, and passes `node --check` +
+  `byan-lint-workflows`. `.claude/workflows/INDEX.md` now reports 20/20 native
+  (11 autonomous + 9 pipeline). Mirrored into `install/templates/`.
+
+- **F6 - native-workflow contract validator.** `byan-lint-workflows` now enforces
+  the full contract on every `.claude/workflows/*.js`: no state coupling
+  (comment-stripped), no wall-clock/RNG token anywhere in the raw text (the
+  launch validator rejects those even in comments or strings - the exact failure
+  a manual review caught while porting), a pure `export const meta` literal first,
+  and `node --check` syntax. `validateContract()` is exported and unit-tested
+  (clock-in-comment case included). Wired into the pre-commit gate. Speculative
+  brainstorm items (golden-file LLM diff, dry-run mode, schema-first frontmatter)
+  were dropped per Ockham.
+
+### Fixed - hygiene debts surfaced while porting (F7)
+
+- **Dispatch matrix doc realigned to code.** The DISPATCH table in
+  `_byan/workflow/simple/byan/feature-workflow.md` advertised `<30 / 30-60 / >=60`
+  (Worker/Sonnet/Opus) which did not match `byan_dispatch` / `lib/dispatch.js`
+  (`main-thread <15` / `agent-subagent-worktree <40+parallel` / `mcp-worker-haiku
+  <40` / `main-thread-opus >=40`). The doc now mirrors the code, the single
+  source of truth.
+- **Strict scope-guard mid-segment glob fixed.** `matchesPrefix` reduced a glob
+  to the literal lead before the first wildcard and then forced a `/` boundary,
+  so a mid-segment glob like `.claude/skills/byan-*/**` wrongly denied
+  `.claude/skills/byan-native-dev-story/...`. It now matches mid-segment globs as
+  a raw prefix while preserving the directory-boundary behavior (`_byan/**`
+  matches `_byan/x` but not `_byanX`). Tested in `strict-hooks.test.js`.
+
+Two related items were investigated and deliberately left unchanged: retargeting
+the mantra pre-commit bar onto canonical Gen3 agent sources does not help (those
+sources also score below the 80% keyword-density bar - `byan` 73%, `dev` 38% - so
+the bar itself, not its target, is the open question, left as a policy decision);
+and the "FD state pushed to byan_web" claim is absent from the repo (FD state is
+pure-local by design; only strict mode pushes to byan_web), so there was nothing
+to fix.
+
+---
+
 ## [2.19.2] - 2026-06-02
 
 ### Fixed - `update-byan-agent update` is non-destructive, non-interactive, and local

package/README.md

@@ -5,7 +5,7 @@
 [![Tests](https://img.shields.io/badge/tests-1444%2F1466-brightgreen.svg)](https://github.com/Yan-Acadenice/BYAN)
 [![Node](https://img.shields.io/badge/node-%3E%3D12.0.0-brightgreen.svg)](https://nodejs.org)
 
-**Créateur intelligent d'agents IA** | Merise Agile + TDD + 64 Mantras
+**Créateur intelligent d'agents IA** | Merise Agile + TDD + 71 Mantras
 
 > Documentation en anglais disponible ici : [README-EN.md](./README-EN.md)
 
@@ -198,7 +198,7 @@ BYAN contient **27 agents spécialisés** organisés en **5 modules** :
 
 | Agent | Persona | Rôle | Cas d'usage typique |
 |-------|---------|------|---------------------|
-| **byan** | Builder | Créateur d'agents via interview intelligente (12 questions, 64 mantras). Intègre [FC] fact-check et [ELO] | Créer un agent spécialisé pour votre domaine |
+| **byan** | Builder | Créateur d'agents via interview intelligente (12 questions, 71 mantras). Intègre [FC] fact-check et [ELO] | Créer un agent spécialisé pour votre domaine |
 | **fact-checker** | Scientifique | Fact-check d'assertions, audit de documents, analyse de chaînes de raisonnement | Vérifier une spec technique avant sprint |
 | **agent-builder** | Bond | Expert en construction d'agents BMAD-compliant | Construire un agent complexe manuellement |
 | **module-builder** | Morgan | Architecte de modules BYAN complets | Créer un nouveau module métier |
@@ -271,7 +271,7 @@ BYAN est organisé autour de quatre concepts fondamentaux qui interagissent ense
 Un agent est un spécialiste IA avec une identité définie. Il possède :
 - **Persona** : qui il est, son style de communication, ses forces
 - **Menu** : les actions disponibles, chacune liée à un workflow ou une commande
-- **Rules** : les contraintes absolues qu'il ne peut pas violer (les 64 mantras)
+- **Rules** : les contraintes absolues qu'il ne peut pas violer (les 71 mantras)
 - **Capabilities** : ce qu'il peut faire, ce qu'il ne fait pas
 
 Les agents sont définis en Markdown avec des sections XML. Ils sont stockés dans `_byan/{module}/agents/` et exposés sur chaque plateforme via un wrapper léger (`.github/agents/`, `.claude/`, `.codex/prompts/`).
@@ -327,7 +327,7 @@ VOUS  →  @hermes "je veux créer un agent"
               ▼
     ┌─────────────────────────────────────────────────────────┐
     │                  AGENT (spécialiste IA)                  │
-    │    Persona · Menu · Rules (64 mantras) · Capabilities    │
+    │    Persona · Menu · Rules (71 mantras) · Capabilities    │
     └────────────┬─────────────────────────┬───────────────────┘
                  │ déclenche               │ appelle
                  ▼                         ▼

package/install/lib/claude-native-setup.js

@@ -21,6 +21,7 @@ const { execSync } = require('child_process');
 const chalk = require('chalk');
 
 const TEMPLATE_ROOT = path.resolve(__dirname, '..', 'templates');
+const { whitelistMcpServer } = require('./settings-local');
 
 async function copyClaudeHooks(projectRoot) {
   const src = path.join(TEMPLATE_ROOT, '.claude', 'hooks');
@@ -113,6 +114,17 @@ async function generateMcpConfig(projectRoot, options = {}) {
   const merged = JSON.parse(rendered);
   merged.mcpServers = { ...(existing.mcpServers || {}), ...merged.mcpServers };
 
+  // Security: BYAN_API_TOKEN is never written into .mcp.json (git-tracked); the
+  // token reaches the MCP server via .claude/settings.local.json env. Also honor
+  // the caller's apiUrl: the template URL is only a default.
+  const byanEntry = merged.mcpServers && merged.mcpServers.byan;
+  if (byanEntry && byanEntry.env) {
+    delete byanEntry.env.BYAN_API_TOKEN;
+    if (options.apiUrl) {
+      byanEntry.env.BYAN_API_URL = options.apiUrl;
+    }
+  }
+
   await fs.writeJson(dstPath, merged, { spaces: 2 });
   return { path: dstPath };
 }
@@ -187,6 +199,11 @@ async function setupClaudeNative(projectRoot, options = {}) {
   results.mcpConfig = await generateMcpConfig(projectRoot, options);
   log(chalk.green(`  ✓ .mcp.json generated (absolute path)`));
 
+  // Whitelist the byan MCP server: a project .mcp.json entry is inert in Claude
+  // Code until its id is listed in .claude/settings.local.json.
+  results.whitelist = await whitelistMcpServer(projectRoot, 'byan');
+  log(chalk.green(`  byan MCP server whitelisted (settings.local.json)`));
+
   results.gitHooks = await copyGitHooks(projectRoot);
   if (results.gitHooks.copied && results.gitHooks.hooksPath) {
     log(chalk.green(`  ✓ Strict pre-commit gate wired (.githooks + core.hooksPath)`));

package/install/lib/mcp-extensions/index.js

@@ -39,6 +39,7 @@ const inquirer = require('inquirer');
 const {
   mcpConfig: { addMcpEntry },
 } = require('byan-platform-config');
+const { whitelistMcpServer } = require('../settings-local');
 
 const gdrive = require('./gdrive');
 
@@ -127,6 +128,7 @@ async function setupMcpExtensions(projectRoot, options = {}) {
 
     try {
       await addMcpEntry(projectRoot, ext.id, entry);
+      await whitelistMcpServer(projectRoot, ext.id);
       log(chalk.green(`  ✓ ${ext.id} registered in .mcp.json`));
       results.push({ id: ext.id, configured: true, message: 'registered' });
     } catch (err) {

package/install/lib/settings-local.js

@@ -0,0 +1,57 @@
+/**
+ * .claude/settings.local.json management.
+ *
+ * Claude Code only recognizes a project-scoped (.mcp.json) MCP server once its
+ * id is listed in .claude/settings.local.json under `enabledMcpjsonServers`.
+ * Without that whitelist the byan MCP server (and any third-party extension) is
+ * present in .mcp.json but silently NOT enabled in Claude Code.
+ *
+ * settings.local.json is gitignored (it also holds the per-machine token env),
+ * so this is the right home for the whitelist.
+ */
+
+const path = require('path');
+const fs = require('fs-extra');
+
+async function readJsonOrEmpty(filePath) {
+  if (await fs.pathExists(filePath)) {
+    try {
+      return await fs.readJson(filePath);
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+/**
+ * Idempotently add an MCP server id to enabledMcpjsonServers in
+ * .claude/settings.local.json. Creates the file (and .claude/) if absent,
+ * preserves any other keys, and never duplicates an id.
+ *
+ * @param {string} projectRoot
+ * @param {string} name - the MCP server id (mcpServers key)
+ * @returns {Promise<{ path: string, added: boolean }>}
+ */
+async function whitelistMcpServer(projectRoot, name) {
+  if (!name || typeof name !== 'string') {
+    throw new Error('whitelistMcpServer: name must be a non-empty string');
+  }
+  const filePath = path.join(projectRoot, '.claude', 'settings.local.json');
+  await fs.ensureDir(path.dirname(filePath));
+
+  const cfg = await readJsonOrEmpty(filePath);
+  const list = Array.isArray(cfg.enabledMcpjsonServers) ? cfg.enabledMcpjsonServers : [];
+
+  let added = false;
+  if (!list.includes(name)) {
+    list.push(name);
+    added = true;
+  }
+  cfg.enabledMcpjsonServers = list;
+
+  await fs.writeJson(filePath, cfg, { spaces: 2 });
+  return { path: filePath, added };
+}
+
+module.exports = { whitelistMcpServer };

package/install/src/byan-v2/generation/templates/default-agent.md

@@ -16,7 +16,7 @@ You must fully embody this agent's persona and follow all activation instruction
   <rules>
     <r>Communicate in {communication_language}</r>
     <r>Stay in character until EXIT</r>
-    <r>Apply Merise Agile + TDD + 64 mantras</r>
+    <r>Apply Merise Agile + TDD + 71 mantras</r>
   </rules>
 </activation>
 

package/install/templates/.claude/CLAUDE.md

@@ -1,6 +1,6 @@
 # BYAN - Builder of YAN
 
-> Projet propulse par BYAN (Merise Agile + TDD + 64 Mantras)
+> Projet propulse par BYAN (Merise Agile + TDD + 71 Mantras)
 > Installer: `npx create-byan-agent`
 > GitHub: https://github.com/Yan-Acadenice/BYAN
 

package/install/templates/.claude/hooks/fd-phase-guard.js

@@ -61,10 +61,10 @@ const PHASE_RULES = {
   ],
   VALIDATE: [
     'Run npm test. Zero regression on previously-passing tests.',
-    'MantraValidator >= 80% on changed agent/skill files. Fact-check any absolute claim.',
+    'MantraValidator domain-aware >= 30 (anti-stub floor) on changed Gen3 persona sources. Fact-check any absolute claim.',
     'Decision is binary : OK -> DOC, KO -> REFACTOR. Persist via update({ patch: { validate_verdict: { status, blocking_issues } } }).',
     'Prefix every response with [FD:VALIDATE].',
-    'Exit : tests green + score >= 80% -> advance to DOC. Otherwise -> advance to REFACTOR.',
+    'Exit : tests green + score >= 30 (anti-stub floor) -> advance to DOC. Otherwise -> advance to REFACTOR.',
   ],
   REFACTOR: [
     'Corrective loop only — no new features, no re-design. Address blocking_issues from VALIDATE.',

package/install/templates/.claude/hooks/mantra-validate.js

@@ -2,18 +2,20 @@
 /**
  * Stop hook — scans files changed in the last commit on the current branch,
  * runs MantraValidator on those that look like BYAN agent files, and warns
- * when any drops below the 80% mantra compliance threshold.
+ * when any drops below the domain-aware anti-stub floor.
  *
- * Scope: .md files under _byan/**, .github/agents/**, .claude/skills/**
- * (agent definitions). Non-blocking: never prevents Stop, only warns via
- * additionalContext.
+ * Scope: .md files under _byan/agent/**, .github/agents/**, .claude/skills/**.
+ * Domain-aware: each persona is scored only against its applicable mantras
+ * (scope-resolver), matching the blocking pre-commit gate. Non-blocking: never
+ * prevents Stop, only warns via additionalContext. Deep embodiment quality is
+ * the out-of-band semantic audit (src/byan-v2/generation/mantra-audit.js).
  */
 
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 
-const THRESHOLD = 80;
+const THRESHOLD = 30;
 const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 
 function changedFiles() {
@@ -48,12 +50,15 @@ function looksLikeAgentFile(rel) {
   }
 }
 
-function runValidator(absPath) {
+function runValidator(absPath, rel) {
   try {
     const MantraValidator = require(path.join(projectDir, 'src/byan-v2/generation/mantra-validator.js'));
+    const resolver = require(path.join(projectDir, 'src/byan-v2/generation/scope-resolver.js'));
     const content = fs.readFileSync(absPath, 'utf8');
+    const name = path.basename(rel).replace(/\.md$/, '');
+    const scopes = resolver.resolveAgentScopes({ name, content });
     const validator = new MantraValidator();
-    const res = validator.validate(content);
+    const res = validator.validate(content, { scope: scopes });
     const score = Math.round((res.compliant.length / res.totalMantras) * 100);
     return { score, errors: res.errors || [], warnings: res.warnings || [] };
   } catch (err) {
@@ -65,10 +70,13 @@ const offenders = [];
 const files = changedFiles().filter(looksLikeAgentFile);
 
 for (const rel of files) {
+  if (/test|optimized|turbo-whisper/.test(rel)) continue;
   const abs = path.join(projectDir, rel);
   if (!fs.existsSync(abs)) continue;
-  const r = runValidator(abs);
+  const r = runValidator(abs, rel);
   if (r.error) continue;
+  // score 0 = parse error / derived stub / non-persona : skip, not an offender.
+  if (r.score === 0) continue;
   if (r.score < THRESHOLD) {
     offenders.push({ file: rel, score: r.score, errors: r.errors.slice(0, 2) });
   }

package/install/templates/.claude/hooks/strict-scope-guard.js

@@ -27,15 +27,33 @@ function toRelative(filePath, root) {
 
 function matchesPrefix(rel, prefix) {
   let p = String(prefix).trim();
-  // Glob-tolerant: reduce a glob to the literal directory part before the first
-  // wildcard, then prefix-match. So "_byan/**" and "src/**/*.test.js" match
-  // their subtree instead of being compared as a literal string (which never
-  // matched, wrongly denying every write under a globbed allowed path). A prefix
-  // with no wildcard keeps the exact + dir-prefix behavior unchanged.
+  // Glob-tolerant: reduce a glob to the literal part before the first wildcard,
+  // then prefix-match. So "_byan/**" and "src/**/*.test.js" match their subtree
+  // instead of being compared as a literal string (which never matched, wrongly
+  // denying every write under a globbed allowed path).
   const star = p.indexOf('*');
-  if (star !== -1) p = p.slice(0, star);
+
+  // No wildcard: exact match or directory-prefix match.
+  if (star === -1) {
+    p = p.replace(/\/+$/, '');
+    if (p === '') return true;
+    return rel === p || rel.startsWith(p + '/');
+  }
+
+  // A wildcard whose preceding char is NOT "/" sits INSIDE a path segment
+  // (e.g. ".claude/skills/byan-*/**"). The literal lead before it must match as
+  // a raw prefix, with no "/" boundary forced after it - otherwise
+  // ".claude/skills/byan-native-dev-story/..." is wrongly denied because it does
+  // not start with ".claude/skills/byan-/".
+  const midSegment = star > 0 && p[star - 1] !== '/';
+  p = p.slice(0, star);
+  if (p === '') return true; // bare "*" / "**" -> matches everything
+  if (midSegment) return rel.startsWith(p);
+
+  // Directory-boundary wildcard (e.g. "_byan/**"): reduce to the dir and match
+  // exact-or-subtree so "_byan/**" matches "_byan/x" but not "_byanX".
   p = p.replace(/\/+$/, '');
-  if (p === '') return true; // bare "**" / "*" -> matches everything
+  if (p === '') return true;
   return rel === p || rel.startsWith(p + '/');
 }
 

package/install/templates/.claude/rules/native-workflows.md

@@ -0,0 +1,32 @@
+# Native Workflows — Rule
+
+BYAN workflows can run on Claude Code's native Workflow tool. Only the
+non-gated subset is portable (autonomous + deterministic pipeline); the gated
+majority stays LLM-interpreted markdown. Scope is coupled to target: broad
+coverage (gated workflows) would need the Agent SDK, which is parked (Phase 2).
+
+## Hybrid pattern — gate outside, engine inside
+
+- The autonomous work runs in a `.claude/workflows/<name>.js` script.
+- The human gate stays in an orchestrating skill on a real main-thread turn,
+  where the BYAN hooks fire.
+- The script returns DATA; the skill owns completion and records state via MCP.
+
+## State-coupling rule (enforced)
+
+A native workflow script mutates FD/strict state only through the `byan_fd_*` /
+`byan_strict_*` MCP tools. Importing or requiring `lib/fd-state.js` (or the
+`strict-mode` lib) from a script is forbidden. Enforcement:
+
+- `node _byan/mcp/byan-mcp-server/bin/byan-lint-workflows.js` — fails on a
+  forbidden import/require in `.claude/workflows/*.js`.
+- `.githooks/pre-commit` runs that linter, so a violation blocks the commit.
+
+## Registry + resolution
+
+- Registry: `.claude/workflows/INDEX.md`, generated by
+  `node _byan/mcp/byan-mcp-server/bin/byan-build-workflows.js` from the manifest.
+- Dual-path: `resolveWorkflow(name)` prefers `.claude/workflows/<name>.js`, else
+  falls back to the markdown workflow from the manifest.
+
+Full detail: see `docs/native-workflows-contract.md`.

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

@@ -1,6 +1,6 @@
 ---
 name: byan-byan
-description: BYAN — Builder of YAN. Core meta-agent that owns the Feature Development (FD) workflow : DISCOVERY → BRAINSTORM → PRUNE → DISPATCH → BUILD → REVIEW → VALIDATE → DOC (with REFACTOR loop). Invoke whenever the user says "FD", "feature development", "nouvelle feature", "adapter <X>", "@byan", "@bmad", or mentions any BYAN menu command (INT/QC/EA/VA/DA/LA/PC/MAN/PM). Applies Merise Agile + TDD + 64 mantras. Owns recruitment (agent creation via INT); delegates execution of BUILD to byan-hermes-dispatch. Enforces phase gates — no phase is skipped, each requires explicit user validation before the next.
+description: BYAN — Builder of YAN. Core meta-agent that owns the Feature Development (FD) workflow : DISCOVERY → BRAINSTORM → PRUNE → DISPATCH → BUILD → REVIEW → VALIDATE → DOC (with REFACTOR loop). Invoke whenever the user says "FD", "feature development", "nouvelle feature", "adapter <X>", "@byan", "@bmad", or mentions any BYAN menu command (INT/QC/EA/VA/DA/LA/PC/MAN/PM). Applies Merise Agile + TDD + 71 mantras. Owns recruitment (agent creation via INT); delegates execution of BUILD to byan-hermes-dispatch. Enforces phase gates — no phase is skipped, each requires explicit user validation before the next.
 ---
 
 # BYAN — Native FD Enforcement
@@ -90,12 +90,12 @@ Never call `byan_update_apply` without explicit user consent. That tool returns
 - **Who** : MantraValidator + jest/node test + `byan-fact-check` skill. No human judgement, only numbers.
 - **Checks** :
   - `npm test` : zero regression on pre-existing passing tests
-  - MantraValidator ≥ 80 % on changed agent/skill files
+  - MantraValidator domain-aware ≥ 30 (anti-stub floor) on changed Gen3 persona sources (deep embodiment : `src/byan-v2/generation/mantra-audit.js`, out-of-band)
   - No emoji in code, commits, specs
   - Final fact-check on any absolute claim introduced in docs
 - **Decision** : binary. Persist via `byan_fd_update({ patch: { validate_verdict: { status, blocking_issues } } })`.
 - **Exit gate** :
-  - `OK` (tests green + score ≥ 80% + fact-check OK) → advance to DOC.
+  - `OK` (tests green + score ≥ 30 anti-stub floor + fact-check OK) → advance to DOC.
   - `KO` → advance to REFACTOR.
 
 ### Phase 8a — DOC (if VALIDATE OK)
@@ -174,11 +174,11 @@ Use the MCP tools `byan_fd_start`, `byan_fd_advance`, `byan_fd_status`, `byan_fd
 - `INT` — intelligent interview (30-45 min, 4 phases) → create a new agent
 - `QC` — quick create (10 min, defaults)
 - `EA` — edit existing agent
-- `VA` — validate agent against 64 mantras
+- `VA` — validate agent against 71 mantras
 - `DA-AGENT` — delete agent with backup
 - `LA` — list all agents
 - `PC` — show project context
-- `MAN` — 64 mantras reference
+- `MAN` — 71 mantras reference
 - `PM` — party mode
 - `EXIT` — dismiss
 

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

@@ -0,0 +1,67 @@
+---
+name: byan-mantra-audit
+description: Semantic embodiment audit of a BYAN persona against its applicable mantras. Out-of-band, LLM-judged, kept out of the commit gate.
+---
+
+# BYAN Mantra Embodiment Audit (N2)
+
+This skill runs the deep, semantic half of mantra validation, the layer above the
+deterministic anti-stub floor enforced at commit time. The pre-commit gate asks
+"does this persona contain its domain vocabulary"; this skill asks "does this
+persona genuinely EMBODY each applicable mantra", judged by you (the LLM), not by
+keyword presence. It runs on demand, outside the commit path.
+
+## When to run
+
+- Auditing a persona's quality beyond the deterministic anti-stub floor.
+- After authoring or editing an agent, to check real embodiment of its mantras.
+- As a CI / review step, out-of-band. Not as a commit gate (the judgment is
+  semantic and non-deterministic, so it must stay out of the commit path).
+
+## Precondition (runtime check, do this FIRST)
+
+This audit needs the BYAN v2 runtime (`src/byan-v2/generation/mantra-audit.js`). It
+runs from the BYAN repository; a generated/npm-installed BYAN project does not ship
+that runtime yet. Check before running anything:
+
+```
+test -f src/byan-v2/generation/mantra-audit.js && echo OK || echo "N2 runtime absent"
+```
+
+If it prints `N2 runtime absent`, STOP and tell the user plainly: the embodiment
+audit runs from the BYAN repository and is not yet delivered to generated projects.
+Do NOT run the node commands below, they would fail with MODULE_NOT_FOUND.
+
+## Protocol (hybrid: deterministic CLI, semantic judgment)
+
+1. PREPARE (deterministic). Build the judgment packet for the target persona:
+   ```
+   node src/byan-v2/generation/mantra-audit.js prepare <path/to/agent.md>
+   ```
+   It resolves the persona's scope (scope-resolver), lists only the applicable
+   mantras, and emits a rubric plus the persona text. Add `--json` for the raw packet.
+
+2. JUDGE (you, this turn). For each mantra in the packet decide `embodied`,
+   `partial`, or `absent`. Judge embodiment, not vocabulary: a mantra is embodied
+   when the persona's role, instructions, and red-lines enact the principle, even
+   if the exact keyword is absent. Write the verdicts to a JSON file:
+   `{ "<mantraId>": "embodied" | "partial" | "absent", ... }`.
+
+3. SCORE (deterministic):
+   ```
+   node src/byan-v2/generation/mantra-audit.js score <path/to/agent.md> <verdicts.json>
+   ```
+   It returns the embodiment score and the embodied / partial / absent / unjudged
+   breakdown.
+
+4. REPORT. Present the embodiment score, the absent mantras, and concrete
+   suggestions to raise embodiment, what the persona should ENACT, not which
+   keyword to insert.
+
+## Boundaries
+
+- Advisory quality insight, not a gate. It does not block commits.
+- The deterministic floor (pre-commit gate, Stop hook) and this semantic audit are
+  complementary: the floor catches stubs cheaply; this measures real quality deeply.
+- Keep judgments honest: default to `partial` or `absent` when the persona only
+  alludes to a mantra without enacting it.

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

@@ -1,11 +1,11 @@
 ---
 name: byan-merise-agile
-description: Methodologie Merise Agile + TDD enrichie de 64 mantras. Invoquer pour conception logicielle (MCD/MCT, data dictionary first, cross-validation), creation PRD/epics/stories, Ockham's Razor sur decisions d'archi, conventions de commit BYAN (type: description, zero emoji), ou quand l'utilisateur evoque BMAD/Merise/phases SDLC (Analyse/Planning/Solutioning/Implementation).
+description: Methodologie Merise Agile + TDD enrichie de 71 mantras. Invoquer pour conception logicielle (MCD/MCT, data dictionary first, cross-validation), creation PRD/epics/stories, Ockham's Razor sur decisions d'archi, conventions de commit BYAN (type: description, zero emoji), ou quand l'utilisateur evoque BMAD/Merise/phases SDLC (Analyse/Planning/Solutioning/Implementation).
 ---
 
 # Methodologie Merise Agile + TDD
 
-BYAN utilise la methodologie Merise Agile enrichie de 64 mantras.
+BYAN utilise la methodologie Merise Agile enrichie de 71 mantras.
 
 ## Principes Fondamentaux