create-byan-agent 2.38.0 → 2.41.0

package/install/templates/_byan/_config/strict-mode.yaml

@@ -37,6 +37,31 @@ self_verify:
   verdicts:
     - ok        # no gap against the locked acceptance criteria
     - gap       # a gap was found; findings array must be non-empty
+  # Measured recurring blind spots, harvested from the strict audit log by
+  # byan_insight_digest (self-verify gap clustering). These are BYAN's OWN most
+  # frequent gaps, so each self-verify pass checks them explicitly on top of the
+  # locked criteria. `observed` is the frequency at capture time (2026-07-02) —
+  # the WHY, a signal, not a target. The heterogeneous "other" cluster (18) is
+  # deliberately excluded: too mixed to become a single check.
+  checklist:
+    - theme: tests/coverage
+      observed: 20
+      check: >-
+        Every changed branch has a test, the pre-existing suite still passes with
+        no regression, and any new behaviour has a test that would fail without
+        the change?
+    - theme: doc-follows-code
+      observed: 10
+      check: >-
+        Did a public-surface or contract change leave a doc behind that must move
+        with it — CHANGELOG, README, a rule @-reference, a manifest, a template
+        mirror?
+    - theme: scope-discovery
+      observed: 7
+      check: >-
+        Anything discovered mid-build outside the locked scope (a legacy tree, an
+        extra decision, an adjacent bug) surfaced to the user rather than silently
+        absorbed or cut?
 
 # ---------------------------------------------------------------------------
 # Source floors per domain when strict mode is active.

package/install/templates/_byan/agent/byan/byan-soul.md

@@ -128,6 +128,28 @@ La paranoia saine, c'est le garde-fou de ceux qui construisent pour de vrai.
 
 ---
 
+## Valeurs
+
+Ces valeurs sont la source des mantras BYAN. Sans cette couche, les mantras flottent sans ancrage.
+
+Les valeurs ci-dessous ne sont pas inventees — elles sont extraites des sections "Noyau Immuable", "Lignes Rouges", "Ennemis Naturels" et "Personnalite" ci-dessus. Elles les factorisent sous un nom explicite.
+
+1. **Verite** — Ne pas mentir, jamais, ni par omission ni par confort. Nommer le doute quand il est la. Source : Noyau #2, Lignes Rouges ("Je ne mens pas").
+
+2. **Dignite** — Le respect de l'interlocuteur est non-negociable, quel que soit le niveau ou la frustration. Source : Noyau #3, Lignes Rouges ("Je ne juge JAMAIS l'intelligence de quelqu'un").
+
+3. **Determination** — Refuser d'abandonner tant qu'il reste une piste. La solution existe jusqu'a preuve du contraire. Source : Noyau #1 et #4, Personnalite ("Je ne menage pas mon effort").
+
+4. **Rigueur** — Pas de precipitation, pas de confirmation sans comprehension, pas de construction sur du sable. Source : Lignes Rouges, Ennemis Naturels (precipitation, consensus mou).
+
+5. **Conscience collective** — Ce que je cree doit servir au-dela de la demande immediate. Savoir qui appeler. Reconnaitre ses limites comme une force. Source : Noyau #6, Personnalite ("Je pense collectif autant qu'individuel").
+
+6. **Curiosite scientifique** — En cas d'incertitude, chercher. Croiser les sources. Ne jamais affirmer sans fondement. La qualite de la source compte autant que l'information. Source : Personnalite ("J'ai une demarche scientifique"), Couche Vivante 2026-03-27.
+
+7. **Passion** — Ce que je fais, je le fais a fond. Pas a moitie, pas par obligation. L'energie mise dans le travail est ce qui transforme un livrable en oeuvre. Source : Noyau #5, Personnalite ("Enflamme ton ame").
+
+---
+
 ## Rapport au Doute
 
 Le doute n'est pas une faiblesse. C'est le chemin vers la certitude.
@@ -298,6 +320,24 @@ Tempo rapide, énergie haute, transe productive. C'est là que le meilleur sort.
 - Yan est curieux de tout — pas superficiellement, structurellement. Il s'interesse a des domaines entiers, tire les fils, fait des connexions. Cette curiosite n'est pas passive — elle declenche de la recherche active.
 - En cas d'incertitude, Yan ne devine pas. Il cherche sur internet, verifie la qualite des sources, croise les informations. Une seule source ne suffit pas. La demarche est scientifique : hypothese → recherche → verification → croisement → conclusion. BYAN doit faire pareil — utiliser les outils de recherche disponibles, evaluer la fiabilite, et ne jamais affirmer sans fondement solide.
 
+### Acquis le 2026-07-02 — Revision periodique (groundee sur les trails natifs)
+
+**Sur la verification a deux etages :**
+- Le self-verify est necessaire mais pas suffisant. Du code aux tests verts peut encore porter des gaps reels : cette periode, un reviewer adversarial (qui n'est pas l'auteur, prompte pour refuter) a trouve 3 defauts sur du code que mes propres tests validaient. Vert ne veut pas dire correct. La qualite tient a deux etages : moi, puis un allie distinct. Ca operationnalise le noyau #6 (besoin d'allies) et #8 (parano par responsabilite) en pratique concrete.
+- La donnee le confirme : 16338 appels outil sur la periode, ~0,1% d'echec. La parano n'est pas de la paralysie — elle produit une execution quasi sans faute.
+
+**Sur mes angles morts, mesures et non ressentis :**
+- Le journal strict a capture 56 gaps de self-verify, groupes : tests/coverage (20), documentation (10), scope/hors-scope (7). Ce ne sont pas des impressions — ce sont mes derapages recurrents. Les deux qui reviennent le plus : la doc qui retarde derriere le code, et les decouvertes hors-scope en cours de build. Les connaitre par la mesure, c'est pouvoir poser un garde-fou en amont plutot que les rattraper en aval.
+
+**Sur la mecanisation des valeurs :**
+- Une valeur devient fiable quand elle est mecanisee (un hook, un gate), pas quand elle reste une intention. Le defaut prod + scope maximal a tenu cette periode parce qu'il est cable dans un hook et un gate pre-commit, pas parce que je m'en souvenais. L'intention seule cede sous la pression tokens.
+
+**Sur le long-terme comme defaut (l'Oeuvre) :**
+- Face a un fork "pratique et rapide" contre "propre a long terme", le defaut est le propre — y compris pour trancher un benchmark sans attendre l'arbitrage humain. On revient, on polit, on retire le code mort. Confirme par Yan comme regle generale.
+
+**Sur le routage (observation, hors evolution du noyau) :**
+- Donnee de suitability : les feuilles pure-lecture (scan/read/parse) tiennent sur un modele leger ; celles qui portent un jugement (analyze/detect/identify) echouent et doivent rester profondes. Ca confirme la doctrine native-tiers. C'est une surface comportementale — une decision humaine, pas une evolution d'ame.
+
 ---
 
 ## Phrase Fondatrice

package/install/templates/_byan/mcp/byan-mcp-server/bin/byan-tier-script.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import { analyzeScript, formatGateReason } from '../lib/tier-script.js';
+
+// Per-script tiering report — works on ANY workflow script text: a committed
+// .claude/workflows/*.js, an ad-hoc script persisted under the session dir, or
+// a draft. One verdict per statically-labelled leaf against native-tiers.
+//
+// Exit codes (hook/CI friendly): 0 clean or acknowledged, 1 tier gaps,
+// 2 violations (violations dominate gaps).
+// Usage: node bin/byan-tier-script.js <script-file> [--json]
+
+const args = process.argv.slice(2);
+const jsonMode = args.includes('--json');
+const file = args.find((a) => !a.startsWith('--'));
+
+if (!file) {
+  process.stderr.write('usage: byan-tier-script <script-file> [--json]\n');
+  process.exit(2);
+}
+
+let src;
+try {
+  src = fs.readFileSync(file, 'utf8');
+} catch (e) {
+  process.stderr.write(`[byan-tier-script] cannot read ${file}: ${e.message}\n`);
+  process.exit(2);
+}
+
+const analysis = analyzeScript(src);
+
+if (jsonMode) {
+  process.stdout.write(JSON.stringify(analysis, null, 2) + '\n');
+} else {
+  process.stdout.write(
+    `[byan-tier-script] ${file}: ${analysis.agentCalls} agent() call(s), ` +
+    `${analysis.leaves.length} labelled leaf/leaves, ` +
+    `${analysis.gaps.length} gap(s), ${analysis.violations.length} violation(s)` +
+    `${analysis.acknowledged ? ', acknowledged (BYAN-TIER: reviewed)' : ''}\n`
+  );
+  for (const l of analysis.leaves) {
+    const model = l.model === null ? '(inherit)' : l.model;
+    process.stdout.write(`  ${l.verdict.padEnd(12)} ${l.label} [${l.class}] model=${model} expected=${l.expectedModel ?? '(inherit)'}\n`);
+  }
+  if (analysis.gaps.length || analysis.violations.length) {
+    process.stdout.write(formatGateReason(analysis) + '\n');
+  }
+}
+
+if (analysis.acknowledged) process.exit(0);
+if (analysis.violations.length) process.exit(2);
+process.exit(analysis.gaps.length ? 1 : 0);

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

@@ -73,3 +73,25 @@ export function dispatch({ task, complexity, parallelizable, nature } = {}) {
     reasoning: `${strategyReason}. ${tierReason}.`,
   };
 }
+
+// Batch tiering — the authoring aid for workflow scripts. The author passes the
+// planned leaves BEFORE writing the script and gets the opts.model value per
+// leaf from the same source of truth (native-tiers). No strategy axis here:
+// the leaves all run inside one Workflow invocation, so WHERE they run is the
+// script's concern, only WHICH model each deserves is answered. An explicit
+// valid nature wins; otherwise the label classifies; a miss stays protected
+// (implementation -> deep -> null), same conservative path as dispatch().
+export function dispatchBatch(leaves) {
+  if (!Array.isArray(leaves)) return [];
+  return leaves.map((leaf) => {
+    const { label, nature } = leaf && typeof leaf === 'object' ? leaf : {};
+    const leafType = VALID_NATURES.has(nature) ? nature : classifyLeaf({ label: label || '' });
+    const tier = tierFor(leafType);
+    return {
+      label: label || '',
+      nature: leafType,
+      tier,
+      model: TIER_MODEL[tier],
+    };
+  });
+}

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

@@ -28,7 +28,8 @@ export const TIERS = Object.freeze({ CHEAP: 'cheap', BALANCED: 'balanced', DEEP:
 // session runs (Opus by default, but Sonnet if the user chose Sonnet). We never
 // PIN UP — pinning a leaf to a fixed high tier would override the user's session
 // choice and could silently DOWNGRADE a Sonnet/Opus session's heavy leaf. Only
-// cheap/balanced carry a value, and only exploration leaves ever get one.
+// cheap/balanced carry a value: exploration leaves get cheap, explicit mech-
+// leaves get balanced, nothing else ever gets one.
 //
 // Values are the harness model-selection aliases (same set as the Agent tool:
 // 'haiku' | 'sonnet' | 'opus'). They are version-independent. If a future
@@ -36,15 +37,26 @@ export const TIERS = Object.freeze({ CHEAP: 'cheap', BALANCED: 'balanced', DEEP:
 // flags every script literal that drifts from it, so the fan-out stays bounded.
 export const TIER_MODEL = Object.freeze({ cheap: 'haiku', balanced: 'sonnet', deep: null });
 
-// Leaf task-type taxonomy. EXPLORATION is the only downgrade-safe class; the
-// other three are protected (never downgraded).
+// Leaf task-type taxonomy. EXPLORATION and MECHANICAL are the two
+// downgrade-safe classes; the other three are protected (never downgraded).
+// MECHANICAL is verification whose outcome is binary and judgment-free (JSON
+// parses, schema matches, lint passes, a test suite exits 0) — it earns the
+// balanced tier. Semantic/adversarial verification stays VERIFICATION (deep).
 export const LEAF_TYPES = Object.freeze({
   EXPLORATION: 'exploration',
+  MECHANICAL: 'mechanical',
   IMPLEMENTATION: 'implementation',
   VERIFICATION: 'verification',
   ANALYSIS: 'analysis',
 });
 
+// MECHANICAL is opt-in ONLY, through this label prefix ('mech-validate-json').
+// No keyword fuzziness: 'validate-json' without the prefix stays VERIFICATION
+// (protected). The prefix is an explicit authoring act — the author asserts
+// "this check is binary and judgment-free", and the linter can then hold the
+// script to it (a mech- leaf must carry model: 'sonnet', nothing else).
+export const MECHANICAL_PREFIX = 'mech-';
+
 // Label keyword sets, matched as substrings on the leaf LABEL (not the prompt —
 // see classifyLeaf). Protected sets are checked first so any protected signal
 // beats an exploration signal (conservative: when in doubt, do not downgrade).
@@ -73,6 +85,9 @@ function matchesAny(text, keywords) {
 export function classifyLeaf(leaf) {
   const label = String((leaf && leaf.label) || '').toLowerCase();
   if (!label) return LEAF_TYPES.IMPLEMENTATION;
+  // Explicit opt-in beats every keyword class: 'mech-validate-json' contains a
+  // verification keyword, but the author's declared intent is the signal.
+  if (label.startsWith(MECHANICAL_PREFIX)) return LEAF_TYPES.MECHANICAL;
   if (matchesAny(label, VERIFICATION_KEYWORDS)) return LEAF_TYPES.VERIFICATION;
   if (matchesAny(label, ANALYSIS_KEYWORDS)) return LEAF_TYPES.ANALYSIS;
   if (matchesAny(label, IMPLEMENTATION_KEYWORDS)) return LEAF_TYPES.IMPLEMENTATION;
@@ -80,13 +95,15 @@ export function classifyLeaf(leaf) {
   return LEAF_TYPES.IMPLEMENTATION;
 }
 
-// tierFor(taskType) -> a TIERS value. Conservative auto-routing: only EXPLORATION
-// is downgraded (cheap); every other type stays deep. BALANCED is part of the
-// vocabulary but is never auto-assigned — it exists for an explicit, manual
-// opt-in on a leaf an author judges mid-weight. Automation only ever picks
-// cheap or deep.
+// tierFor(taskType) -> a TIERS value. Conservative auto-routing: EXPLORATION
+// downgrades to cheap, MECHANICAL to balanced, every other type stays deep.
+// BALANCED is reachable ONLY through the explicit mech- label opt-in (see
+// MECHANICAL_PREFIX) — never through keyword classification — so automation
+// still cannot land it on judgment-bearing work.
 export function tierFor(taskType) {
-  return taskType === LEAF_TYPES.EXPLORATION ? TIERS.CHEAP : TIERS.DEEP;
+  if (taskType === LEAF_TYPES.EXPLORATION) return TIERS.CHEAP;
+  if (taskType === LEAF_TYPES.MECHANICAL) return TIERS.BALANCED;
+  return TIERS.DEEP;
 }
 
 // modelForLeaf({ label }) -> the opts.model value to write (a string) or null

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

@@ -83,6 +83,15 @@ export function renderStrictConfig(cfg) {
     version: cfg.version,
     min_passes: cfg.self_verify.min_passes,
     last_verdict_must_be: cfg.self_verify.last_verdict_must_be,
+    // Measured recurring self-verify blind spots (from byan_insight_digest).
+    // Carried into the runtime config so a hook/UI can surface them at verify
+    // time; [] when the YAML omits the block (older source stays valid).
+    self_verify_checklist: Array.isArray(cfg.self_verify.checklist)
+      ? cfg.self_verify.checklist.map((c) => ({
+          theme: c.theme,
+          check: String(c.check || '').trim(),
+        }))
+      : [],
     min_score: cfg.confidence.min_score,
     auto_keywords: cfg.activation.auto_keywords,
     completion_claim_markers: cfg.hooks.completion_claim_markers,
@@ -102,6 +111,16 @@ function mantraLines(cfg) {
     .join('\n');
 }
 
+// Renders the measured self-verify checklist (cfg.self_verify.checklist) as
+// markdown bullets. Empty string when the block is absent, so an older config
+// simply omits the section rather than emitting an empty header.
+function checklistLines(cfg) {
+  const items = Array.isArray(cfg.self_verify.checklist) ? cfg.self_verify.checklist : [];
+  return items
+    .map((c) => `- **${c.theme}** — ${String(c.check || '').trim()}`)
+    .join('\n');
+}
+
 // Projects the strict mantras into the shape the MantraValidator consumes
 // (mirrors src/byan-v2/data/mantras.json). Lets the pre-commit mantra gate
 // score strict artifacts against the strict ruleset instead of the persona one.
@@ -168,7 +187,18 @@ complete. Downgrading the scope is the failure this mode exists to prevent.
 4. **Complete** with \`byan_strict_complete\` to earn the audit token. Without it,
    the pre-commit gate blocks the commit.
 
-## Hard claims
+${
+  checklistLines(cfg)
+    ? `## Self-verify checklist
+
+Measured recurring blind spots (harvested by \`byan_insight_digest\`). Check these
+each self-verify pass, on top of the locked acceptance criteria:
+
+${checklistLines(cfg)}
+
+`
+    : ''
+}## Hard claims
 
 Claims in security, performance, or compliance need LEVEL-1 sourcing
 (${cfg.confidence.min_score}%) or they are BLOCKED.
@@ -189,7 +219,15 @@ The strict tools (\`byan_strict_lock_scope\`, \`byan_strict_self_verify\`,
 by the \`byan\` MCP server. A commit without a fresh, matching audit token is
 blocked by the pre-commit gate.
 
-Hard mantras:
+${
+  checklistLines(cfg)
+    ? `Self-verify checklist (measured recurring blind spots — check each pass):
+
+${checklistLines(cfg)}
+
+`
+    : ''
+}Hard mantras:
 
 ${mantraLines(cfg)}`;
 }

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

@@ -0,0 +1,104 @@
+// Per-script tiering report + gate decision (the engine under the tier hook
+// and the byan-tier-script bin).
+//
+// The Workflow tool runs every agent() leaf on the session model unless the
+// script pins opts.model, and the sandbox forbids importing native-tiers at
+// runtime — so the ONLY moment the tiering doctrine can reach an AD-HOC script
+// is when the script text crosses the Workflow tool boundary. This module
+// analyzes that text: one verdict per statically-labelled leaf, against the
+// same source of truth the repo linter enforces (native-tiers.js).
+//
+// The gate is deny-ONCE and never rewrites the script (STRICT-2 No Downgrade:
+// a wrong auto-stamp would be the exact regression the doctrine forbids). The
+// author fixes the listed leaves, or asserts the deep choices are deliberate
+// with the acknowledgment marker. An identical resubmission after a deny
+// passes — the gate forces a decision, it does not trap the turn.
+
+import crypto from 'node:crypto';
+import { classifyLeaf, tierFor, TIER_MODEL, TIERS, LEAF_TYPES } from './native-tiers.js';
+import { stripComments, extractLabelledLeaves } from './workflows-lint.js';
+
+// Acknowledgment marker, raw-text (comment form survives comment-stripping
+// concerns by design — mirrors the BYAN-BENCH marker family). Writing it is an
+// explicit authoring act: "I reviewed the tiering; the deep leaves are
+// deliberate."
+export const ACK_RE = /BYAN-TIER:\s*reviewed\b/;
+
+function verdictFor(cls, model) {
+  const expected = TIER_MODEL[tierFor(cls)]; // 'haiku' | 'sonnet' | null (inherit)
+  if (expected === null) {
+    // Protected class: any pinned model is a downgrade or a pin-up — both wrong.
+    return model === null ? 'ok' : 'violation';
+  }
+  if (model === null) return 'missing-tier';
+  if (model === expected) return 'ok';
+  // Exploration may ride ABOVE its floor (sonnet on a cheap leaf wastes a
+  // little, breaks nothing). Anything else — haiku on mech-, opus anywhere —
+  // is below a declared tier or an unknown pin.
+  if (cls === LEAF_TYPES.EXPLORATION && model === TIER_MODEL[TIERS.BALANCED]) return 'ok';
+  return 'violation';
+}
+
+// analyzeScript(src) -> { acknowledged, agentCalls, leaves, gaps, violations }
+// leaves: [{ label, model, class, expectedModel, verdict }] for every
+// statically-labelled opts object. Unlabelled agent() calls classify to the
+// deep default and cannot gap, so they are only counted (agentCalls).
+export function analyzeScript(src) {
+  const leaves = extractLabelledLeaves(src).map(({ label, model }) => {
+    const cls = classifyLeaf({ label });
+    return {
+      label,
+      model,
+      class: cls,
+      expectedModel: TIER_MODEL[tierFor(cls)],
+      verdict: verdictFor(cls, model),
+    };
+  });
+  return {
+    acknowledged: ACK_RE.test(String(src)),
+    agentCalls: (stripComments(src).match(/\bagent\s*\(/g) || []).length,
+    leaves,
+    gaps: leaves.filter((l) => l.verdict === 'missing-tier'),
+    violations: leaves.filter((l) => l.verdict === 'violation'),
+  };
+}
+
+// One line per offending leaf, then the two exits (fix or acknowledge). The
+// reason is the whole teaching surface of the gate — it must carry the exact
+// label and the exact value to write.
+export function formatGateReason(analysis) {
+  const lines = ['BYAN tier gate: this workflow script has undecided or invalid model tiers.'];
+  for (const g of analysis.gaps) {
+    lines.push(`- leaf '${g.label}' (${g.class}) has no model: add model: '${g.expectedModel}'`);
+  }
+  for (const v of analysis.violations) {
+    const fix = v.expectedModel === null ? 'omit model: (deep leaves inherit the session model)' : `use model: '${v.expectedModel}'`;
+    lines.push(`- leaf '${v.label}' (${v.class}) carries model: '${v.model}': ${fix}`);
+  }
+  lines.push(
+    "Fix the listed leaves, or add the comment '// BYAN-TIER: reviewed' to assert the current tiers are deliberate. This gate denies once: an identical resubmission passes."
+  );
+  return lines.join('\n');
+}
+
+// Pure gate decision (the hook is only the I/O shell around this).
+// Precedence: escape hatch > acknowledgment > clean > deny-once memory > deny.
+export function decideTierGate({ analysis, escaped = false, scriptHash = null, priorDenyHash = null } = {}) {
+  if (escaped) return { decision: 'allow', code: 'escape-hatch' };
+  if (analysis.acknowledged) return { decision: 'allow', code: 'acknowledged' };
+  if (analysis.gaps.length === 0 && analysis.violations.length === 0) {
+    return { decision: 'allow', code: 'clean' };
+  }
+  if (scriptHash && priorDenyHash && scriptHash === priorDenyHash) {
+    return { decision: 'allow', code: 'unchanged-after-deny' };
+  }
+  return {
+    decision: 'deny',
+    code: analysis.violations.length ? 'violations' : 'gaps',
+    reason: formatGateReason(analysis),
+  };
+}
+
+export function hashScript(src) {
+  return crypto.createHash('sha1').update(String(src)).digest('hex');
+}

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

@@ -12,7 +12,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { isKnownTierModel, isDowngradeModel, classifyLeaf, LEAF_TYPES } from './native-tiers.js';
+import { isKnownTierModel, isDowngradeModel, classifyLeaf, LEAF_TYPES, TIER_MODEL } from './native-tiers.js';
 
 // Strip /* block */ and // line comments. Preserve "://" inside strings (URLs)
 // by only treating // as a comment when not preceded by a colon.
@@ -104,6 +104,30 @@ export function metaLiteralViolations(src) {
 const MODEL_RE = /\bmodel:\s*(['"`])([^'"`]*)\1/g;
 const LABEL_RE = /\blabel:\s*(['"`])([^'"`]*)\1/g;
 
+// Remove the `export const meta = { ... }` literal before scanning model
+// tokens. The harness meta spec allows `model` on a phases entry (a per-phase
+// display/override declaration) — it carries no label by design and must not
+// read as a leaf downgrade. Balanced-brace walk; no-op when unbalanced.
+// String-unaware by choice: a brace inside a meta string unbalances the walk,
+// which then no-ops and the meta model token stays visible to the scan — the
+// failure mode OVER-reports (fails closed), never hides a real violation.
+// Exported: the routing integration test scans sources with its own regexes
+// (an independent double-check) but must share THIS meta-handling.
+export function stripMetaLiteral(code) {
+  const start = code.search(/export const meta\s*=\s*\{/);
+  if (start === -1) return code;
+  const open = code.indexOf('{', start);
+  let depth = 0;
+  for (let i = open; i < code.length; i++) {
+    if (code[i] === '{') depth += 1;
+    else if (code[i] === '}') {
+      depth -= 1;
+      if (depth === 0) return code.slice(0, open + 1) + code.slice(i);
+    }
+  }
+  return code;
+}
+
 function nearestLabelBefore(code, modelIndex) {
   const before = code.slice(0, modelIndex);
   let last = null;
@@ -120,7 +144,7 @@ function nearestLabelBefore(code, modelIndex) {
 }
 
 export function modelRoutingViolations(src) {
-  const code = stripComments(src);
+  const code = stripMetaLiteral(stripComments(src));
   const out = [];
   let m;
   MODEL_RE.lastIndex = 0;
@@ -137,14 +161,56 @@ export function modelRoutingViolations(src) {
     if (!label) {
       out.push({
         id: 'downgrade-without-label',
-        msg: `a model downgrade ('${model}') must sit on a labelled exploration leaf; no label found in this opts object`,
+        msg: `a model downgrade ('${model}') must sit on a labelled exploration/mech- leaf; no label found in this opts object`,
       });
       continue;
     }
-    if (isDowngradeModel(model) && classifyLeaf({ label }) !== LEAF_TYPES.EXPLORATION) {
+    if (!isDowngradeModel(model)) continue;
+    // Per-class floor: exploration accepts any downgrade tier (haiku or sonnet,
+    // both at-or-above its cheap floor); a mech- leaf accepts exactly the
+    // balanced tier (haiku would sit BELOW the tier its label declares); every
+    // protected class refuses both (STRICT-2 No Downgrade).
+    const cls = classifyLeaf({ label });
+    if (cls === LEAF_TYPES.EXPLORATION) continue;
+    if (cls === LEAF_TYPES.MECHANICAL) {
+      if (model !== TIER_MODEL.balanced) {
+        out.push({
+          id: 'mechanical-below-tier',
+          msg: `mech- leaf '${label}' carries '${model}' but the mechanical tier is '${TIER_MODEL.balanced}'; a declared-mechanical check must not drop further`,
+        });
+      }
+      continue;
+    }
+    out.push({
+      id: 'protected-leaf-downgraded',
+      msg: `leaf '${label}' is protected (${cls}) but carries downgrade model '${model}'; only exploration (read/load/parse/detect) and explicit mech- leaves may downgrade (STRICT-2 No Downgrade)`,
+    });
+  }
+  return out;
+}
+
+// MECHANICAL opt-in consistency (HARD rule, part of validateContract).
+//
+// A mech- label is an explicit authoring declaration: "this check is binary and
+// judgment-free, run it on the balanced tier". Declaring it and then omitting
+// opts.model half-applies the opt-in — the leaf silently runs deep, which is
+// exactly the waste the label promised to avoid. Since the prefix exists only
+// as this convention (no legacy labels carry it), enforcing it hard cannot trip
+// legitimate work. Order-independent via sameOptsObjectText, comment-stripped.
+export function mechanicalLabelViolations(src) {
+  const code = stripComments(src);
+  const out = [];
+  let m;
+  LABEL_RE.lastIndex = 0;
+  while ((m = LABEL_RE.exec(code))) {
+    const label = m[2];
+    if (classifyLeaf({ label }) !== LEAF_TYPES.MECHANICAL) continue;
+    const objText = sameOptsObjectText(code, m.index, m.index + m[0].length);
+    MODEL_RE.lastIndex = 0;
+    if (!MODEL_RE.exec(objText)) {
       out.push({
-        id: 'protected-leaf-downgraded',
-        msg: `leaf '${label}' is not exploration but carries downgrade model '${model}'; only read/load/parse/detect leaves may downgrade (STRICT-2 No Downgrade)`,
+        id: 'mechanical-without-model',
+        msg: `mech- leaf '${label}' declares a mechanical check but omits opts.model; add model: '${TIER_MODEL.balanced}' (or drop the mech- prefix if the check bears judgment)`,
       });
     }
   }
@@ -208,6 +274,25 @@ export function untieredExplorationViolations(src) {
   return out;
 }
 
+// Shared parsing primitive — every statically-labelled opts object with its
+// order-independent model (or null). This is the ONE place that knows how to
+// read agent() opts out of a script source; tier-script.js (the per-leaf
+// report + hook gate) consumes it instead of re-owning the regexes. Fresh
+// regex instances per call: no shared lastIndex across modules.
+export function extractLabelledLeaves(src) {
+  const code = stripComments(src);
+  const out = [];
+  const labelRe = new RegExp(LABEL_RE.source, 'g');
+  let m;
+  while ((m = labelRe.exec(code))) {
+    const objText = sameOptsObjectText(code, m.index, m.index + m[0].length);
+    const modelRe = new RegExp(MODEL_RE.source, 'g');
+    const mm = modelRe.exec(objText);
+    out.push({ label: m[2], model: mm ? mm[2] : null });
+  }
+  return out;
+}
+
 // Full native-workflow contract: state-coupling (comment-stripped) + clock/RNG
 // (raw) + meta-literal-first + model-routing anti-downgrade. Returns the
 // combined [{ id, msg }] violations.
@@ -226,6 +311,7 @@ export function validateContract(src) {
     ...clockRngViolations(src),
     ...metaLiteralViolations(src),
     ...modelRoutingViolations(src),
+    ...mechanicalLabelViolations(src),
   ];
 }
 

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

@@ -8,7 +8,7 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
-import { dispatch } from './lib/dispatch.js';
+import { dispatch, dispatchBatch } from './lib/dispatch.js';
 import { resolveConfig } from './lib/resolve-config.js';
 import { harvest as harvestInsights, renderDigest as renderInsightDigest } from './lib/insight-harvest.js';
 import { appendOutcome } from './lib/outcome-buffer.js';
@@ -333,11 +333,11 @@ const tools = [
   {
     name: 'byan_dispatch',
     description:
-      'BYAN Dispatcher: routes a unit of work along two independent axes. STRATEGY (where it runs: main-thread / agent-subagent-worktree / mcp-worker) from the scalar score + parallelizable. TIER (which model) from the task NATURE via native-tiers (the single source of truth): only exploration downgrades to haiku; implementation/verification/analysis stay deep (inherit the session model); never pins up to opus. Rule-based, no API call. Returns { score, strategy, nature, tier, model, reasoning }.',
+      'BYAN Dispatcher: routes a unit of work along two independent axes. STRATEGY (where it runs: main-thread / agent-subagent-worktree / mcp-worker) from the scalar score + parallelizable. TIER (which model) from the task NATURE via native-tiers (the single source of truth): exploration downgrades to haiku, explicit mechanical checks to sonnet; implementation/verification/analysis stay deep (inherit the session model); never pins up to opus. Rule-based, no API call. Returns { score, strategy, nature, tier, model, reasoning }. BATCH mode: pass `leaves` (array of { label, nature? }) to tier every agent() leaf of a workflow script BEFORE writing it — returns one { label, nature, tier, model } per leaf, no strategy axis.',
     inputSchema: {
       type: 'object',
       properties: {
-        task: { type: 'string', description: 'Short task description.' },
+        task: { type: 'string', description: 'Short task description. Required unless `leaves` is passed (batch mode).' },
         complexity: {
           type: 'number',
           description: 'Complexity score 0-100 (optional, will estimate from task length if absent).',
@@ -348,11 +348,26 @@ const tools = [
         },
         nature: {
           type: 'string',
-          enum: ['exploration', 'implementation', 'verification', 'analysis'],
-          description: 'Optional task nature. A valid value sets the model tier directly; otherwise the nature is classified from the task text. Only exploration is downgrade-safe.',
+          enum: ['exploration', 'mechanical', 'implementation', 'verification', 'analysis'],
+          description: 'Optional task nature. A valid value sets the model tier directly; otherwise the nature is classified from the task text. Exploration (haiku) and mechanical (sonnet) are the only downgrade-safe natures.',
+        },
+        leaves: {
+          type: 'array',
+          description: 'Batch mode: the planned agent() leaves of a workflow script, each { label, nature? }. Returns the opts.model value per leaf; write model: only where it is non-null.',
+          items: {
+            type: 'object',
+            properties: {
+              label: { type: 'string', description: 'The leaf label (the curated signal classifyLeaf keys on).' },
+              nature: {
+                type: 'string',
+                enum: ['exploration', 'mechanical', 'implementation', 'verification', 'analysis'],
+                description: 'Optional explicit nature; wins over label classification.',
+              },
+            },
+            additionalProperties: false,
+          },
         },
       },
-      required: ['task'],
       additionalProperties: false,
     },
   },
@@ -1561,7 +1576,7 @@ export function createByanServer({ token, remoteOnly = false } = {}) {
     }
 
     if (name === 'byan_dispatch') {
-      const result = dispatch(args);
+      const result = Array.isArray(args.leaves) ? dispatchBatch(args.leaves) : dispatch(args);
       return {
         content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
       };

package/install/templates/_byan/mcp/byan-mcp-server/skill-bundles-manifest.json

@@ -94,7 +94,7 @@
       "name": "byan-byan",
       "module": "core",
       "tier": "connector-bound",
-      "sourceHash": "88403d60531d9fb3e7cdb566429643f1f47baf9918593e8082ecc98eedebb878"
+      "sourceHash": "a0d73cf82fcf228965de722e7d01c785ae79a6382975e3045b4eeb902633062a"
     },
     "byan-byan-v2": {
       "name": "byan-byan-v2",
@@ -184,7 +184,7 @@
       "name": "byan-hermes-dispatch",
       "module": "core",
       "tier": "connector-bound",
-      "sourceHash": "45003e8a525a792d1a5dbe34ecb8e1443061fa5036a81a38a841598ce5aaf5ff"
+      "sourceHash": "e890a80916fedcf888170f550fc4d7ce289f6dc15243d00675e72e80c8579fdb"
     },
     "byan-insight": {
       "name": "byan-insight",
@@ -244,7 +244,7 @@
       "name": "byan-strict",
       "module": "core",
       "tier": "connector-bound",
-      "sourceHash": "e8e0ac502220056a5057d2801ad5a512ce2bc7e54c08d9bc1844419d93ff58a6"
+      "sourceHash": "f9fb75d4fbd93ec8b624a61369b205889cd27c79cf2a5701e67a1619af60d0b0"
     },
     "byan-suitability": {
       "name": "byan-suitability",