create-byan-agent 2.19.1 → 2.20.0

package/CHANGELOG.md

@@ -7,6 +7,194 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [Unreleased]
+
+## [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): dev sheds ops (applicable 42 -> 36), CIS agents gain matchable
+mantras (brainstorming 45 -> 48, innovation-strategist 38 -> 59).
+
+### 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
+
+Field testing of the 2.19.1 updater surfaced four real bugs in
+`update-byan-agent/bin/update-byan-agent.js` (the published template `_byan` was
+verified healthy and is untouched):
+
+- **No more redundant network install.** The updater runs via
+  `npx -p create-byan-agent@latest`, so the `@latest` package (and its template)
+  is already on disk next to the running bin. It now resolves the template from
+  the running package root (`path.resolve(__dirname, '..', '..')`, with a
+  `node_modules/create-byan-agent` fallback) instead of re-running
+  `npm install --no-save create-byan-agent@latest` into the user project (which
+  pulled ~215 packages, took minutes, had no timeout, and emitted no output).
+  The `.github/agents`, Claude-native, and fs-migration refreshes now resolve
+  from that same local root, so the F22 Gen3 stub refresh is no longer silently
+  skipped when the user project has no local `node_modules`.
+- **Non-destructive rebuild.** The replacement template is validated as a
+  non-empty directory and fully staged beside the live tree before anything is
+  deleted; the swap is then two atomic renames. A failed or empty source aborts
+  the update with the existing `_byan` left intact (previously `_byan` was
+  `rm -rf`'d up front, so a failing install left the project relying on backup
+  rollback).
+- **Non-interactive support.** `update` accepts `-y/--yes` and
+  `--non-interactive`, and auto-confirms when `--force`, `--yes`,
+  `--non-interactive`, or a non-TTY stdout is detected. In CI / headless / piped
+  runs the updater no longer hangs on the `Y/n` prompt.
+- **Honest diagnostics.** A template that cannot be used now reports whether the
+  package could not be resolved at all vs. the template directory being present
+  but empty, and prints the probed paths — instead of the misleading
+  "_byan directory not found in npm package" that blamed a healthy package.
+
+Covered by `update-byan-agent/__tests__/apply-update.test.js` (11 tests:
+local resolution, full Gen2->Gen3 replace, stub refresh, swap atomicity, and the
+destructive-safety guard). The updater bin now reports its real package version
+instead of a stale hard-coded literal.
+
+---
+
 ## [2.19.1] - 2026-06-02
 
 ### Fixed - Agent stubs repointed to the by-type (Gen3) layout

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/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,53 @@
+---
+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).
+
+## 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
 

package/install/templates/.claude/skills/byan-native-dev-story/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: byan-native-dev-story
+description: Orchestrating conductor for the native dev-story workflow. Runs the autonomous red-green-refactor engine (.claude/workflows/dev-story.js) via the Workflow tool, then presents its verdict at a human gate and records FD/strict state via MCP. This is the Hybrid pattern incarnate - gate OUTSIDE the script, engine INSIDE.
+---
+
+# byan-native-dev-story - Conductor (gate outside, engine inside)
+
+You are the human-gated conductor for the native dev-story workflow. The
+autonomous work runs in `.claude/workflows/dev-story.js` (the in-CLI Workflow
+tool); YOU own the human gate and the auditable state. This split is the whole
+point of Phase 1: the engine is native and deterministic, the gate stays on a
+real main-thread turn where the BYAN hooks fire.
+
+## Why this skill exists
+
+A launched Workflow script is autonomous and cannot pause mid-run to ask a
+human, and the main-thread enforcement hooks do not fire inside it. So the
+script must not decide completion or mutate BYAN state on its own. It returns
+DATA; this skill turns that data into a gated decision.
+
+## Protocol
+
+### 1. Resolve the workflow (dual-path)
+
+Prefer the native script. If `.claude/workflows/dev-story.js` exists, use it.
+Otherwise fall back to the markdown workflow from the manifest
+(`_byan/workflow/simple/4-implementation/dev-story/workflow.yaml`). The
+programmatic resolver is `resolveWorkflow('dev-story')` in
+`_byan/mcp/byan-mcp-server/lib/workflows-generator.js`.
+
+### 2. (If inside an FD or strict session) read state via MCP
+
+State mutations go through the MCP tools ONLY - direct writes to `fd-state.json`
+or `.byan-strict/` are out of bounds:
+
+- FD: `byan_fd_status` to read the phase; a dev-story run is BUILD-phase work.
+- Strict: if a strict session is engaged, the story implementation is in scope;
+  do not lock a second scope here.
+
+### 3. Run the engine
+
+Invoke the Workflow tool:
+
+```
+Workflow({ name: 'dev-story', args: { story: '<path-or-key, or omit for next ready-for-dev>' } })
+```
+
+The script runs the red-green-refactor loop with a real 3-cycle convergence
+counter (`lib/native-loop.js` `convergenceGuard`) and returns a structured
+verdict:
+
+```json
+{ "workflow": "dev-story", "story": "...",
+  "status": "review-ready | aborted-no-convergence | in-progress",
+  "green": true, "cycles": 2, "maxCycles": 3, "blocking": [],
+  "reason": "green", "needsHumanGate": true }
+```
+
+### 4. HUMAN GATE (mandatory - do not skip)
+
+Present the verdict to the user and HALT for a decision. Do not auto-advance.
+
+- `status: review-ready` (green) - summarize cycles + files touched; ask the
+  user to approve moving the story to **review**. Only on approval, record the
+  transition via MCP, then stop.
+- `status: aborted-no-convergence` - the engine hit the 3-cycle cap without
+  green. Surface the `blocking` issues verbatim. Propose REFACTOR (targeted
+  fixes, re-run) or, if mis-scoped, a return to PRUNE. Leave the story not-done.
+- `status: in-progress` - report remaining work; ask whether to continue.
+
+### 5. Record state via MCP (only after the gate)
+
+After the user decides, record the outcome through `byan_fd_*` / `byan_strict_*`
+so the audit trail stays in the MCP authority. State files are mutated through
+the MCP tools, not by direct edit.
+
+## Invariants
+
+- The script returns data; THIS skill owns completion and state. (Enforcement
+  contract: see `docs/native-workflows-contract.md`.)
+- The human gate stays on a real main-thread turn, outside the script.
+- Dual-path: native `.js` preferred, markdown fallback. No silent downgrade.
+- No emoji in outputs (IA-23).

package/install/templates/.claude/workflows/INDEX.md

@@ -0,0 +1,35 @@
+# BYAN Native Workflows
+
+> Registre des workflows portables vers l'outil Workflow natif de Claude Code.
+> Genere automatiquement — ne pas editer a la main. Source : `_byan/_config/workflow-manifest.csv`.
+> Regenerer : `node _byan/mcp/byan-mcp-server/bin/byan-build-workflows.js`.
+>
+> Resolution dual-path : le skill prefere `.claude/workflows/<name>.js` s'il existe,
+> sinon il retombe sur le workflow markdown du manifest. Les workflows gated (a gate
+> humain par etape) restent markdown interprete — ils ne sont pas portables.
+
+## autonomous (11)
+
+- `create-story` — native — source `_byan/workflow/simple/4-implementation/create-story/workflow.yaml`
+- `dev-story` — native — source `_byan/workflow/simple/4-implementation/dev-story/workflow.yaml`
+- `qa-automate` — native — source `_byan/workflow/simple/qa/automate/workflow.yaml`
+- `testarch-atdd` — native — source `_byan/workflow/simple/testarch/atdd/workflow.yaml`
+- `testarch-automate` — native — source `_byan/workflow/simple/testarch/automate/workflow.yaml`
+- `testarch-ci` — native — source `_byan/workflow/simple/testarch/ci/workflow.yaml`
+- `testarch-framework` — native — source `_byan/workflow/simple/testarch/framework/workflow.yaml`
+- `testarch-nfr` — native — source `_byan/workflow/simple/testarch/nfr-assess/workflow.yaml`
+- `testarch-test-design` — native — source `_byan/workflow/simple/testarch/test-design/workflow.yaml`
+- `testarch-test-review` — native — source `_byan/workflow/simple/testarch/test-review/workflow.yaml`
+- `testarch-trace` — native — source `_byan/workflow/simple/testarch/trace/workflow.yaml`
+
+## pipeline (9)
+
+- `check-implementation-readiness` — native — source `_byan/workflow/simple/3-solutioning/check-implementation-readiness/workflow.md`
+- `code-review` — native — source `_byan/workflow/simple/4-implementation/code-review/workflow.yaml`
+- `create-excalidraw-dataflow` — native — source `_byan/workflow/simple/excalidraw-diagrams/create-dataflow/workflow.yaml`
+- `create-excalidraw-diagram` — native — source `_byan/workflow/simple/excalidraw-diagrams/create-diagram/workflow.yaml`
+- `create-excalidraw-flowchart` — native — source `_byan/workflow/simple/excalidraw-diagrams/create-flowchart/workflow.yaml`
+- `create-excalidraw-wireframe` — native — source `_byan/workflow/simple/excalidraw-diagrams/create-wireframe/workflow.yaml`
+- `document-project` — native — source `_byan/workflow/simple/document-project/workflow.yaml`
+- `quick-dev` — native — source `_byan/workflow/simple/bmad-quick-flow/quick-dev/workflow.md`
+- `sprint-planning` — native — source `_byan/workflow/simple/4-implementation/sprint-planning/workflow.yaml`