create-byan-agent 2.49.0 → 2.52.0

package/install/templates/.claude/hooks/lib/fact-check-core.js

@@ -8,7 +8,14 @@
 
 'use strict';
 
+// WI-5 — the absolute-claim patterns. Kept HIGH-SIGNAL on purpose : this gate
+// hard-blocks a doc write, so a false positive costs the user a block. Every
+// entry is either a plain absolute, a comparative superlative, an unsourced
+// best-practice claim, or a certainty phrase — the exact trigger families named
+// in .claude/rules/fact-check.md. Noisy bare words ("mieux", "the best",
+// "impossible", "bien sur") are deliberately excluded.
 const ABSOLUTES = [
+  // plain absolutes
   /\btoujours\b/i,
   /\bjamais\b/i,
   /\bforc[eé]ment\b/i,
@@ -17,10 +24,31 @@ const ABSOLUTES = [
   /\bnever\b/i,
   /\bclearly\b/i,
   /\bundoubtedly\b/i,
+  /\b[ée]videmment\b/i,
+  /\bcertainly\b/i,
+  /\bwithout a doubt\b/i,
+  /\bsans aucun doute\b/i,
+  /\bguaranteed\b/i,
+  // comparative superlatives (a claim, not phrasing)
   /\bfaster than\b/i,
   /\bbetter than\b/i,
   /\bplus rapide que\b/i,
   /\bmeilleur que\b/i,
+  /\bthe fastest\b/i,
+  /\ble plus rapide\b/i,
+  /\bsuperior to\b/i,
+  // ("optimal" alone was dropped in WI-5 review : too common in legit doc prose
+  //  ("the optimal layout") to hard-block a doc write without a false positive.)
+  // unsourced best-practice / authority claims
+  /\bbest practice\b/i,
+  /\bbonne pratique\b/i,
+  /\bindustry standard\b/i,
+  /\bstandard de l['’]industrie\b/i,
+  // certainty framing
+  /\bil est clair que\b/i,
+  /\bit is well[- ]known\b/i,
+  /\bwell[- ]known that\b/i,
+  /\bprouv[eé] que\b/i,
 ];
 
 const SOURCE_MARKERS = [
@@ -37,14 +65,18 @@ const SOURCE_MARKERS = [
 //   - fenced code blocks ``` ... ```
 //   - inline backticks `...`
 //   - block quotes (lines starting with >)
-//   - list-of-pattern lines (e.g. "- toujours")
+//   - BULLET list-example lines (e.g. "- toujours") — a doc listing the trigger
+//     words as examples, not asserting them. WI-5 review fix : this REQUIRES a
+//     bullet marker (- or *), so a prose sentence merely STARTING with an
+//     absolute ("Never mutate state directly.") is NOT stripped and stays policed
+//     (the old `^[\s-]*` matched any leading whitespace -> a false negative).
 function stripNonClaimZones(text) {
   if (!text) return '';
   return text
     .replace(/```[\s\S]*?```/g, '')
     .replace(/`[^`\n]+`/g, '')
     .replace(/^> .*$/gm, '')
-    .replace(/^[\s-]*['"]?\b(toujours|jamais|forc[eé]ment|obviously|always|never|clearly|undoubtedly)\b['"]?/gim, '');
+    .replace(/^\s*[-*]\s+['"]?\b(toujours|jamais|forc[eé]ment|obviously|always|never|clearly|undoubtedly|[ée]videmment|certainly|guaranteed)\b['"]?/gim, '');
 }
 
 // Return the first unsourced absolute (with surrounding context) or null when

package/install/templates/.claude/hooks/lib/voice-conformance.js

@@ -0,0 +1,97 @@
+'use strict';
+
+// WI-2 core — the reactive net for BYAN voice conformance (soul/tao).
+//
+// The tao is injected as context (inject-tao / voice-anchor) but nothing checks
+// that a reply actually holds the voice : it is prose Claude can drift from. This
+// net scans the finished reply for the OBJECTIVE, low-false-positive voice
+// signals and flags a slip carried to the next turn — the same forward-net
+// mechanics as plain-language / agent-gate. It is NON-BLOCKING by design : the
+// register/timbre of the tao is semantic and cannot be a hard wall without
+// constant false positives (honest ceiling ; deep audit stays byan-mantra-audit).
+//
+// Two objective signals only :
+//   1. emoji in the reply (Mantra IA-23 : zero emoji — hard, unambiguous).
+//   2. vouvoiement (BYAN tutoies always, per tao) — flagged only on a CLUSTER
+//      (>= 2 occurrences) so a single quoted "vous" does not trip it.
+//
+// Pure (no I/O beyond the slip flag). Code spans are stripped before scanning so
+// a quoted `vous` variable or an emoji inside a code sample is not policed.
+
+const fs = require('fs');
+const path = require('path');
+const { stripCode } = require('./plain-language');
+
+// True pictographic emoji (Mantra IA-23). Excludes plain arrows (U+2190-21FF)
+// which BYAN uses legitimately in prose ("->", "→").
+const EMOJI_RE = /[\u{1F000}-\u{1FAFF}\u{2600}-\u{26FF}\u{2700}-\u{27BF}\u{2B00}-\u{2BFF}\u{1F1E6}-\u{1F1FF}\u{FE0F}]/u;
+
+// Second-person-plural address. French-aware boundaries so "nous"/"vousXYZ" and
+// accented neighbours do not false-match.
+const VOUS_RE = /(?<![A-Za-zÀ-ÿ0-9_])(vous|votre|vos|vôtre|vôtres)(?![A-Za-zÀ-ÿ0-9_])/gi;
+
+// scanVoice(text) -> [{ kind, good }]. Empty when the reply holds the voice.
+function scanVoice(text) {
+  const prose = stripCode(text);
+  if (!prose) return [];
+  const hits = [];
+  if (EMOJI_RE.test(prose)) {
+    hits.push({ kind: 'emoji', good: 'zero emoji (Mantra IA-23) — retire-les' });
+  }
+  const vousCount = (prose.match(VOUS_RE) || []).length;
+  if (vousCount >= 2) {
+    hits.push({ kind: 'vouvoiement', good: 'BYAN tutoie toujours (tao) — dis "tu", pas "vous"' });
+  }
+  return hits;
+}
+
+function formatReminder(hits) {
+  if (!Array.isArray(hits) || hits.length === 0) return '';
+  const shown = hits.map((h) => `${h.kind} (${h.good})`).join(' ; ');
+  return [
+    'Rappel voix (tao / soul) : au dernier tour la voix BYAN a glisse ->', `${shown}.`,
+    'Reformule ce tour-ci dans la voix BYAN (tutoiement, zero emoji), sans refaire',
+    'la reponse precedente.',
+  ].join(' ');
+}
+
+// --- slip flag (isolated I/O, same family as the other forward nets) ----------
+
+function slipPath(projectDir) {
+  return path.join(projectDir, '_byan-output', '.voice-slip.json');
+}
+
+function writeSlip(projectDir, hits) {
+  try {
+    const p = slipPath(projectDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify({ hits }));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readSlip(projectDir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(slipPath(projectDir), 'utf8'));
+    return Array.isArray(parsed.hits) ? parsed.hits : null;
+  } catch {
+    return null;
+  }
+}
+
+function clearSlip(projectDir) {
+  try { fs.rmSync(slipPath(projectDir), { force: true }); } catch { /* never block */ }
+}
+
+module.exports = {
+  EMOJI_RE,
+  VOUS_RE,
+  scanVoice,
+  formatReminder,
+  slipPath,
+  writeSlip,
+  readSlip,
+  clearSlip,
+};

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

@@ -57,9 +57,48 @@ function matchesPrefix(rel, prefix) {
   return rel === p || rel.startsWith(p + '/');
 }
 
-// Pure decision : returns { deny, reason }.
-function decideScope({ state, config, toolName, filePath }) {
-  if (!['Write', 'Edit'].includes(toolName)) return { deny: false };
+// WI-6 — the Bash write-redirection leak.
+//
+// The Write/Edit deny is bypassable : `cat > src/x.js`, `echo >> a`, `tee f`,
+// `cmd <<EOF > f` write files through Bash, which the tool-name check missed.
+// bashWriteTargets extracts the file targets of write-redirections from a Bash
+// command so the SAME allowed-paths rule applies. Deliberately conservative to
+// avoid denying legit Bash : it skips fd-dups (`2>&1`, `>&2`), process
+// substitution (`>(...)`), and the /dev/* sinks. It is not a hermetic sandbox
+// (pipes, `python -c open()`, variables escape) — it closes the COMMON reflex
+// leak, honestly bounded (see docs).
+function bashWriteTargets(command) {
+  const cmd = String(command || '');
+  const out = [];
+  // A redirection target only counts when it LOOKS like a file path : it contains
+  // a "/" or a file extension. This is the false-positive kill switch : it drops
+  // comparison / arithmetic / here-string operands (`[ 5 > 3 ]`, `(( a > 2 ))`,
+  // `<<< "a > b"` -> "3", "2", "b") which are numbers or bare words, and drops an
+  // unexpanded variable target (`> $F`) which we cannot resolve — denying it would
+  // be a false positive on a possibly in-scope path. Honest ceiling : a bare
+  // filename with no extension (`> outfile`) or a variable target is NOT caught.
+  const consider = (t) => {
+    if (!t) return;
+    if (t.startsWith('$') || t.startsWith('&') || t.startsWith('-')) return; // variable / fd-dup / flag
+    if (/^\/dev\//.test(t)) return; // /dev sinks
+    const pathShaped = t.includes('/') || /\.[A-Za-z0-9]+$/.test(t);
+    if (pathShaped) out.push(t);
+  };
+  // > , >> , &> , &>> , and fd-prefixed (2>) redirections. The lookahead (?![&(])
+  // drops `>&1` (fd dup) and `>(` (process substitution).
+  const redir = /(?:^|[\s;|&(])\d*(?:>>?|&>>?)\s*(?![&(])("?)([^\s"'`|;&<>()]+)\1/g;
+  let m;
+  while ((m = redir.exec(cmd)) !== null) consider(m[2]);
+  // tee [flags] file...
+  const tee = /\btee\b((?:\s+-\S+)*)\s+("?)([^\s"'`|;&<>()]+)\2/g;
+  while ((m = tee.exec(cmd)) !== null) consider(m[3]);
+  return out;
+}
+
+// Pure decision : returns { deny, reason }. Handles Write/Edit (file_path) and,
+// since WI-6, Bash (write-redirection targets that land INSIDE the repo).
+function decideScope({ state, config, toolName, filePath, command }) {
+  if (!['Write', 'Edit', 'Bash'].includes(toolName)) return { deny: false };
   if (!isEngaged(state)) return { deny: false };
 
   const guard = (config && config.scope_guard) || {};
@@ -69,25 +108,42 @@ function decideScope({ state, config, toolName, filePath }) {
   if (!Array.isArray(allowed) || allowed.length === 0) return { deny: false };
 
   const root = projectRoot();
-  const rel = toRelative(filePath, root);
-  if (!rel) return { deny: false };
-
   const exempt = guard.exempt_globs || [];
-  if (exempt.some((g) => matchesPrefix(rel, g))) return { deny: false };
-
-  if (allowed.some((a) => matchesPrefix(rel, a))) return { deny: false };
-
   const base =
     (config && config.banners && config.banners.scope_deny) ||
     'Strict mode: this write targets a path outside the locked scope.';
-  const reason =
+
+  // Returns the offending rel path, or null when the target is allowed/exempt.
+  const offending = (rawTarget, { repoOnly = false } = {}) => {
+    const rel = toRelative(rawTarget, root);
+    if (!rel) return null;
+    // repoOnly (Bash): a target outside the repo (../, /tmp, absolute elsewhere)
+    // is transient, not a repo change under cover of the locked task -> ignore.
+    if (repoOnly && rel.startsWith('..')) return null;
+    if (exempt.some((g) => matchesPrefix(rel, g))) return null;
+    if (allowed.some((a) => matchesPrefix(rel, a))) return null;
+    return rel;
+  };
+
+  const buildReason = (rel) =>
     `${base}\n` +
     `Target: ${rel}\n` +
     `Locked paths: ${allowed.join(', ')}\n` +
     `Either this file belongs to the scope (re-lock with byan_strict_lock_scope ` +
     `including the corrected paths) or it does not (do not write it).`;
 
-  return { deny: true, reason };
+  if (toolName === 'Write' || toolName === 'Edit') {
+    const bad = offending(filePath);
+    return bad ? { deny: true, reason: buildReason(bad) } : { deny: false };
+  }
+
+  // Bash : deny if any in-repo write-redirection target is out of scope.
+  const targets = bashWriteTargets(command);
+  for (const t of targets) {
+    const bad = offending(t, { repoOnly: true });
+    if (bad) return { deny: true, reason: buildReason(bad) };
+  }
+  return { deny: false };
 }
 
 function allow() {
@@ -106,8 +162,9 @@ if (require.main === module) {
     const toolName = payload.tool_name || payload.toolName || '';
     const input = payload.tool_input || payload.toolInput || {};
     const filePath = input.file_path || '';
+    const command = input.command || '';
 
-    const decision = decideScope({ state, config, toolName, filePath });
+    const decision = decideScope({ state, config, toolName, filePath, command });
     if (!decision.deny) {
       process.stdout.write(JSON.stringify(allow()));
       process.exit(0);
@@ -125,4 +182,4 @@ if (require.main === module) {
   })();
 }
 
-module.exports = { decideScope, toRelative, matchesPrefix };
+module.exports = { decideScope, toRelative, matchesPrefix, bashWriteTargets };

package/install/templates/.claude/hooks/voice-conformance-check.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+'use strict';
+
+// Stop hook — WI-2, the reactive net for BYAN voice conformance (soul/tao).
+//
+// At end of turn it scans the finished reply for the objective voice slips (emoji,
+// vouvoiement cluster) and, on a slip, writes a one-turn flag under _byan-output/.
+// The next-turn voice anchor surfaces it in plain French. It NEVER blocks the turn
+// (the register is semantic — a hard wall would false-positive) : always exits 0.
+//
+// The judgment lives in lib/voice-conformance.js (pure) ; this shell only pulls
+// the reply text from the transcript.
+
+const { extractLastAssistantText } = require('./lib/transcript-read');
+const voice = require('./lib/voice-conformance');
+
+function detect(payload, projectDir) {
+  const text = extractLastAssistantText(payload);
+  const hits = voice.scanVoice(text);
+  if (hits.length) voice.writeSlip(projectDir, hits);
+  return hits;
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.on('data', (c) => (data += c));
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', () => resolve(''));
+  });
+}
+
+if (require.main === module) {
+  (async () => {
+    const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    let payload = {};
+    try {
+      const raw = await readStdin();
+      if (raw && raw.trim()) payload = JSON.parse(raw);
+    } catch {
+      payload = {};
+    }
+    try {
+      detect(payload, projectDir);
+    } catch {
+      // never block end-of-turn
+    }
+    process.stdout.write('{}');
+    process.exit(0);
+  })();
+}
+
+module.exports = { detect };

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

@@ -26,7 +26,8 @@ A native workflow script mutates FD/strict state only through the `byan_fd_*` /
 
 Each `agent()` leaf runs on the session model unless the call sets `opts.model`.
 The tiering decision lives in one place — `_byan/mcp/byan-mcp-server/lib/native-tiers.js`
-(tier vocabulary, leaf classifier, model map). Three tiers:
+(tier vocabulary, leaf classifier, model map). Three AUTO-routed tiers, plus an
+explicit UP-TIER an author may pin by complexity (v3):
 
 - **cheap (`model: 'haiku'`)** — a pure EXPLORATION leaf (read/load/parse/detect).
 - **balanced (`model: 'sonnet'`)** — two classes land here. (1) MECHANICAL
@@ -40,16 +41,25 @@ The tiering decision lives in one place — `_byan/mcp/byan-mcp-server/lib/nativ
   leaf may carry `model: 'sonnet'` (its tier) but not `haiku` (`analysis-below-tier`).
   Semantic/adversarial VERIFICATION is NOT analysis and stays deep.
 - **deep (OMIT `opts.model`)** — implementation + verification leaves inherit the
-  session model (no pin-up to opus). A genuinely frontier ANALYSIS leaf opts back to
-  deep with the `deep-` label prefix (`deep-assess-architecture`), the mirror of the
-  `mech-` opt-in.
+  session model (the cost-safe default: no AUTO pin-up). A genuinely frontier
+  ANALYSIS leaf opts back to deep with the `deep-` label prefix
+  (`deep-assess-architecture`), the mirror of the `mech-` opt-in.
+- **up-tier (`model: 'opus'` / `model: 'fable'`)** — an EXPLICIT authoring choice
+  to raise a genuinely complex leaf ABOVE the inherited tier (v3). `opus` for a
+  hard leaf, `fable` as the last-resort top-reasoning model for extreme complexity
+  (~2x Opus price). This is the workflow-leaf mirror of the dispatch-router
+  complexity ladder (haiku -> sonnet -> opus -> fable). Auto-routing does not pick
+  it — the author writes it deliberately. The anti-downgrade floor does not apply
+  upward, so the linter allows an up-tier pin on any leaf (it costs more, it does
+  not regress quality). The old blanket "no pin-up / no Fable" ban is lifted.
 
 The linter splits the two directions:
 
-- **Floor (HARD, blocks the commit)** — a downgrade model on a PROTECTED leaf, a
-  pin-up, or a half-applied `mech-` opt-in is a contract violation
+- **Floor (HARD, blocks the commit)** — a DOWNGRADE model (haiku/sonnet) on a
+  PROTECTED leaf, or a half-applied `mech-` opt-in, is a contract violation
   (`modelRoutingViolations` + `mechanicalLabelViolations`). This is the STRICT-2
-  No Downgrade net.
+  No Downgrade net. An UP-TIER pin (opus/fable) is not a violation — the floor
+  guards downward only.
 - **Ceiling (ADVISORY, non-blocking)** — an exploration- OR analysis-labelled leaf
   that runs deep is *reported* (`byan-lint-workflows.js --advise`:
   `untiered-exploration` -> `model: 'haiku'`, `untiered-analysis` -> `model: 'sonnet'`),

package/install/templates/.claude/settings.json

@@ -90,6 +90,10 @@
             "type": "command",
             "command": "p=\"$CLAUDE_PROJECT_DIR/.claude/hooks/agent-gate-check.js\"; [ -f \"$p\" ] || exit 0; exec node \"$p\""
           },
+          {
+            "type": "command",
+            "command": "p=\"$CLAUDE_PROJECT_DIR/.claude/hooks/voice-conformance-check.js\"; [ -f \"$p\" ] || exit 0; exec node \"$p\""
+          },
           {
             "type": "command",
             "command": "p=\"$CLAUDE_PROJECT_DIR/.claude/hooks/drain-advisory.js\"; [ -f \"$p\" ] || exit 0; exec node \"$p\""
@@ -112,6 +116,10 @@
           {
             "type": "command",
             "command": "p=\"$CLAUDE_PROJECT_DIR/.claude/hooks/strict-scope-guard.js\"; [ -f \"$p\" ] || exit 0; exec node \"$p\""
+          },
+          {
+            "type": "command",
+            "command": "p=\"$CLAUDE_PROJECT_DIR/.claude/hooks/codex-delegate-guard.js\"; [ -f \"$p\" ] || exit 0; exec node \"$p\""
           }
         ]
       },

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

@@ -21,8 +21,10 @@ the user should not have to ask for it. Four moments:
    (`_byan/mcp/byan-mcp-server/lib/agent-matcher.js`), the right model + effort
    (`dispatch-router.js` / native-tiers), and the right runtime — Codex for
    execution / shell / deploy / devops / browser ; Claude for architecture /
-   refactor / quality / planning ; verification stays on Claude ; Fable is not
-   emitted. No user ask. A suited agent -> use it. NO suited agent -> interview to
+   refactor / quality / planning ; verification stays on Claude. The Claude model
+   scales on a four-rung complexity ladder (haiku -> sonnet -> opus -> fable, fable
+   the extreme last resort) ; Fable is refused on the Codex path only. No user ask.
+   A suited agent -> use it. NO suited agent -> interview to
    frame the need, web-research the trade's competencies + best practices, create
    the tailored agent (the one place the human is required upstream).
 3. **Execute in party-mode with a live visual.** The user SEES what happens, live:
@@ -30,13 +32,17 @@ the user should not have to ask for it. Four moments:
    `TaskCreate` / `TaskUpdate`) plus the dispatch table shown at the top of BUILD.
    - **Codex-lane** — when the lane is ARMED (yanstaller option on AND Codex
      linked, i.e. `_byan/_config/autodelegate.json` present with `enabled:true`
-     AND `~/.codex/auth.json` or `CODEX_API_KEY`) and the task is delegable,
+     AND `~/.codex/auth.json` or `CODEX_API_KEY`) and the task is delegable code,
      ACTUALLY delegate via `codex-bridge.js` (`codex exec` -> unified diff -> YOU
-     apply it). Fall back to Claude if Codex is unavailable. When armed, the
-     injected `[BYAN auto-delegate]` note is a DIRECTIVE, not a mere suggestion:
-     you delegate the delegable work rather than doing it on Claude by default.
-     When NOT armed (option off or Codex not linked), there is no delegation —
-     you run it on Claude.
+     apply it) or the `codex:codex-rescue` agent. This is a DIRECTIVE, enforced by
+     the `codex-delegate-guard` PreToolUse tooth : it DENIES a delegable code
+     Write/Edit that skipped Codex. The ONLY valid reasons to stay on Claude are
+     (1) Codex unavailable (auto-detected), or (2) the USER asked to stay on Claude
+     ("reste sur Claude" / "sans codex", or the `.byan-codex-autodelegate/off`
+     switch). "Small script / latency / I verify anyway" is NOT valid — that is
+     exactly the self-dodge the tooth closes (option B). You cannot self-grant a
+     bypass. When NOT armed (option off or Codex not linked), there is no
+     delegation — you run it on Claude.
    - **Claude-lane** — run it on Claude at the chosen model.
 4. **User gate at the END.** The user-validation gate lands at the end, once the
    feature/task is done and there is a deliverable to review — not upstream. (In a
@@ -129,9 +135,9 @@ Never call `byan_update_apply` without explicit user consent. That tool returns
     - nature `exploration` (load/read/scan/list/parse/fetch...) → `haiku`
     - nature `mechanical` (binary judgment-free checks : JSON parses, schema matches, lint passes — label prefix `mech-`, explicit opt-in only) → `sonnet`
     - nature `implementation` / `verification` / `analysis` / unknown → deep = **inherit the session model**
-    - Keep protected work (verify/analysis/implement) off haiku/sonnet regardless of size ; no pin-up to opus. Pass an explicit `nature` to `byan_dispatch` when you know it.
+    - Keep protected work (verify/analysis/implement) off haiku/sonnet regardless of size. Auto-routing does not pin up ; but an author MAY deliberately UP-TIER a genuinely complex leaf to `opus` (hard) or `fable` (extreme, last resort) — the linter allows it (the floor guards downward only). Pass an explicit `nature` to `byan_dispatch` when you know it.
   - **Inside native workflow scripts** (`.claude/workflows/*.js` OR ad-hoc) the SAME tiering applies per `agent()` leaf via `opts.model`, enforced as a FLOOR not a ceiling on TWO nets :
-    - **Repo linter** (committed scripts, pre-commit) : `modelRoutingViolations` HARD-blocks a downgrade on a protected leaf, a pin-up, or a half-applied `mech-` opt-in (`mechanical-without-model` / `mechanical-below-tier`) ; an exploration-labelled leaf left deep is a NON-blocking ADVISORY (`byan-lint-workflows.js --advise`), since many such leaves bear a gate/classification/exact-conversion and must stay deep — the human owns that call.
+    - **Repo linter** (committed scripts, pre-commit) : `modelRoutingViolations` HARD-blocks a downgrade (haiku/sonnet) on a protected leaf, or a half-applied `mech-` opt-in (`mechanical-without-model` / `mechanical-below-tier`) ; an UP-TIER pin (opus/fable) is allowed, not blocked (the floor guards downward only) ; an exploration-labelled leaf left deep is a NON-blocking ADVISORY (`byan-lint-workflows.js --advise`), since many such leaves bear a gate/classification/exact-conversion and must stay deep — the human owns that call.
     - **Tier gate hook** (EVERY Workflow invocation, inline or scriptPath) : `tier-script-guard.js` (PreToolUse) runs the same analysis (`lib/tier-script.js`) and DENIES ONCE when exploration/`mech-` leaves have no tier, with the exact leaf list to fix. Acknowledge deliberate deep choices with the `// BYAN-TIER: reviewed` comment marker ; an identical resubmission passes (deny-once by design, no trap). Every decision lands in `_byan-output/tier-ledger.jsonl` (the measurement basis for token gains). Escape hatch : `.byan-tier/off`.
     - **Authoring aid** : BEFORE writing a script, call `byan_dispatch` with `{ leaves: [{ label, nature? }] }` (batch mode) to get the `opts.model` per leaf ; write `model:` only where non-null. Report with `node _byan/mcp/byan-mcp-server/bin/byan-tier-script.js <file> [--json]`.
     - No per-leaf effort knob exists (the API exposes only `model`), so effort-by-complexity reduces to model-by-complexity.

package/install/templates/_byan/mcp/byan-mcp-server/bin/byan-armament-report.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// WI-7 — the armament observation report (CLI, ESM).
+//
+// Reads the observation ledgers under _byan-output/, reads the CURRENT armed
+// flags from config, and prints per-guard : sample size, would-fire count (the
+// false-positive risk proxy), current armed state, and a calibrated
+// recommendation. It NEVER arms anything — arming is a deliberate config flip the
+// human makes after reading this.
+//
+// Usage : node bin/byan-armament-report.js [--json] [--root <dir>]
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildReport } from '../lib/armament-report.js';
+
+function parseArgs(argv) {
+  const a = { json: false, root: process.env.CLAUDE_PROJECT_DIR || process.cwd() };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--json') a.json = true;
+    else if (argv[i] === '--root') a.root = argv[++i];
+  }
+  return a;
+}
+
+function readLedger(root, name) {
+  try {
+    const p = path.join(root, '_byan-output', name);
+    return fs.readFileSync(p, 'utf8').split('\n').filter(Boolean).map((l) => {
+      try { return JSON.parse(l); } catch { return null; }
+    }).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+// Best-effort read of the current armed flags from config (absent -> false).
+function readArmedFlags(root) {
+  const flags = { autobench: false, punt: false, completeness: false };
+  try {
+    const a = JSON.parse(fs.readFileSync(path.join(root, '.claude', 'hooks', 'lib', 'autobench-config.json'), 'utf8'));
+    flags.autobench = Boolean(a && a.enforcement && a.enforcement.armed);
+  } catch { /* absent -> false */ }
+  try {
+    const d = JSON.parse(fs.readFileSync(path.join(root, '_byan', '_config', 'delivery-default.json'), 'utf8'));
+    flags.punt = Boolean(d && d.puntGuard && d.puntGuard.armed);
+    flags.completeness = Boolean(d && d.completenessGate && d.completenessGate.armed);
+  } catch { /* absent -> false */ }
+  return flags;
+}
+
+function render(report) {
+  const lines = ['BYAN armament report (observe first, arm on evidence) :', ''];
+  const label = { autobench: 'Auto-Benchmark', punt: 'Punt guard', completeness: 'Completeness gate' };
+  for (const key of Object.keys(report)) {
+    const g = report[key];
+    const s = g.summary;
+    lines.push(`- ${label[key] || key} : armed=${g.armed} | observations=${s.total} | would-fire=${s.wouldFire} (${Math.round(s.fireRate * 100)}%)`);
+    lines.push(`    -> ${g.recommend.arm ? 'ARM' : 'HOLD'} : ${g.recommend.reason}`);
+  }
+  lines.push('');
+  lines.push('Note : "would-fire" est un indicateur de risque a relire, pas un compte prouve de faux positifs.');
+  lines.push('Armer reste une decision manuelle (autobench-config.json enforcement.armed, delivery-default.json puntGuard/completenessGate.armed).');
+  return lines.join('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const report = buildReport(
+    {
+      benchmark: readLedger(args.root, 'benchmark-ledger.jsonl'),
+      punt: readLedger(args.root, 'punt-ledger.jsonl'),
+      completeness: readLedger(args.root, 'completeness-ledger.jsonl'),
+    },
+    readArmedFlags(args.root)
+  );
+  if (args.json) process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+  else process.stdout.write(render(report) + '\n');
+}
+
+main();
+
+export { readLedger, readArmedFlags, render };

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

@@ -0,0 +1,80 @@
+// WI-7 core — the armament observation report (ESM, matches this package's type).
+//
+// Two BYAN teeth are BUILT but DISARMED by config : the auto-benchmark Stop guard
+// and the punt / completeness guards. They only observe + ledger today. Arming
+// one turns it into a refuse-once, which costs a regeneration on every FALSE
+// positive — the risk the user rejected for a hard wall. So arming must be a
+// measured decision, not a blind flip.
+//
+// This pure core reads the observation ledgers and, per guard, reports : how many
+// entries the guard WOULD have acted on if armed (the false-positive risk proxy),
+// over how large a sample, and a recommendation. It NEVER arms anything — the
+// human flips the config after reading this. Honest limit : the ledger has no
+// ground truth, so "wouldFire" is a risk proxy to eyeball, not a proven
+// false-positive count.
+
+// Per-ledger classifiers : does this entry represent the guard ACTING (a block /
+// refuse-once) if it were armed ?
+export function classifyBenchmark(e) {
+  if (!e || typeof e !== 'object') return 'skip';
+  if (typeof e.event === 'string' && /block|regen|unmarked/i.test(e.event)) return 'wouldFire';
+  // a real choice presented (choice-language + an artifact) without a marker and
+  // not on the never-list is exactly what the armed guard blocks.
+  if (e.choiceLang && e.artifact && !e.marker && !e.neverHit) return 'wouldFire';
+  return 'satisfied';
+}
+
+export function classifyPunt(e) {
+  if (!e || typeof e !== 'object') return 'skip';
+  if (e.punt === true) return 'wouldFire';
+  if (typeof e.event === 'string' && /punt/i.test(e.event)) return 'wouldFire';
+  return 'satisfied';
+}
+
+export function classifyCompleteness(e) {
+  if (!e || typeof e !== 'object') return 'skip';
+  if (Array.isArray(e.missing) && e.missing.length > 0) return 'wouldFire';
+  if (typeof e.event === 'string' && /block|gap|fire/i.test(e.event)) return 'wouldFire';
+  return 'satisfied';
+}
+
+export function summarize(entries, classify) {
+  const s = { total: 0, wouldFire: 0, satisfied: 0, armedSeen: false };
+  for (const e of Array.isArray(entries) ? entries : []) {
+    const c = classify(e);
+    if (c === 'skip') continue;
+    s.total += 1;
+    if (e && e.armed === true) s.armedSeen = true;
+    if (c === 'wouldFire') s.wouldFire += 1;
+    else s.satisfied += 1;
+  }
+  s.fireRate = s.total ? s.wouldFire / s.total : 0;
+  return s;
+}
+
+// recommend — the calibrated arming call. Never arm on a small sample ; arm only
+// on a clean record ; otherwise send the human to review the contexts first.
+export function recommend(summary, { minSample = 20 } = {}) {
+  if (!summary || summary.total < minSample) {
+    return { arm: false, reason: `echantillon trop petit (${summary ? summary.total : 0} < ${minSample}) — continuer d'observer avant de decider` };
+  }
+  if (summary.wouldFire === 0) {
+    return { arm: true, reason: `0 declenchement sur ${summary.total} observations — armement sur (aucun faux positif observe)` };
+  }
+  const pct = Math.round(summary.fireRate * 100);
+  return { arm: false, reason: `${summary.wouldFire}/${summary.total} declenchements (${pct}%) — relire ces contextes avant d'armer (chaque faux positif coute une regeneration)` };
+}
+
+// buildReport — the whole picture. `armedFlags` carries the CURRENT config state
+// (read by the bin) so the report shows observed-vs-armed side by side.
+export function buildReport({ benchmark = [], punt = [], completeness = [] } = {}, armedFlags = {}) {
+  const guards = {
+    autobench: { summary: summarize(benchmark, classifyBenchmark), armed: Boolean(armedFlags.autobench) },
+    punt: { summary: summarize(punt, classifyPunt), armed: Boolean(armedFlags.punt) },
+    completeness: { summary: summarize(completeness, classifyCompleteness), armed: Boolean(armedFlags.completeness) },
+  };
+  for (const k of Object.keys(guards)) {
+    guards[k].recommend = recommend(guards[k].summary);
+  }
+  return guards;
+}