create-byan-agent 2.20.0 → 2.21.0

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

@@ -0,0 +1,112 @@
+// Single source of truth for MODEL ROUTING of native-workflow leaves.
+//
+// Claude Code's in-CLI Workflow tool runs each agent() leaf on the main-loop
+// model unless that call sets opts.model. Ported BYAN workflows never set it,
+// so every leaf ran on the session model (Opus) — the read-the-file leaf paid
+// the same tier as the implement-and-verify leaf. This module is the one place
+// that decides a leaf's model tier, so the rule lives once and the linter
+// (workflows-lint.js) can enforce it.
+//
+// This is a DISTINCT concern from src/byan-v2/dispatcher/complexity-scorer.js,
+// which scores task COMPLEXITY (0-100) to route a whole task to an executor.
+// That scorer answers "how hard is this task"; this module answers "which model
+// tier does this workflow LEAF deserve". They share the same exploration intent
+// but produce different outputs, so they stay separate (clarified, not merged).
+//
+// The sandbox forbids import INSIDE a .claude/workflows/*.js script, so a script
+// cannot require() this file at runtime. The contract it encodes is instead a
+// literal (model: 'haiku') the author writes on exploration leaves, validated
+// against this module by the linter. This module is the canonical reference.
+
+// The three-tier vocabulary. cheap/balanced are explicit downgrades; deep is the
+// default and means "inherit the main-loop model".
+export const TIERS = Object.freeze({ CHEAP: 'cheap', BALANCED: 'balanced', DEEP: 'deep' });
+
+// tier -> concrete opts.model value, or null = OMIT opts.model (inherit).
+//
+// deep MUST be null. Omitting opts.model lets the leaf inherit whatever model the
+// 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.
+//
+// Values are the harness model-selection aliases (same set as the Agent tool:
+// 'haiku' | 'sonnet' | 'opus'). They are version-independent. If a future
+// runtime needs full model ids, this map is the ONLY edit — the linter then
+// 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).
+export const LEAF_TYPES = Object.freeze({
+  EXPLORATION: 'exploration',
+  IMPLEMENTATION: 'implementation',
+  VERIFICATION: 'verification',
+  ANALYSIS: 'analysis',
+});
+
+// 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).
+// Note: 'test' is deliberately ABSENT. It collides both ways — 'discover-tests'
+// is exploration (find the test files) while 'test-design' is analysis — so the
+// bare token decides nothing. Real verification leaves carry verify/validate/
+// check/review/gate/audit/assert/lint; a leaf that runs tests is labelled
+// 'verify-*' in practice.
+const VERIFICATION_KEYWORDS = ['verify', 'validate', 'check', 'assert', 'gate', 'lint', 'audit', 'review'];
+const ANALYSIS_KEYWORDS = ['analy', 'design', 'architect', 'assess', 'evaluate', 'strategy', 'risk', 'nfr', 'recommend', 'judge', 'score', 'coverage'];
+const IMPLEMENTATION_KEYWORDS = ['implement', 'build', 'write', 'generate', 'create', 'dev', 'rgr', 'refactor', 'fix', 'scaffold', 'save', 'optimize', 'aggregate', 'report', 'present', 'plan', 'map', 'select', 'subprocess', 'sub-'];
+const EXPLORATION_KEYWORDS = ['load', 'read', 'scan', 'list', 'parse', 'detect', 'discover', 'fetch', 'lookup', 'source-tree', 'mode-detection'];
+
+function matchesAny(text, keywords) {
+  return keywords.some((kw) => text.includes(kw));
+}
+
+// classifyLeaf({ label }) -> a LEAF_TYPES value.
+//
+// Keys off the LABEL, deliberately NOT the prompt. A leaf's prompt is noisy: an
+// exploration leaf like load-story says "Read... Parse... Report the story key",
+// and 'report' would wrongly pull it to implementation. The label is the curated,
+// stable signal the author controls. Priority is protect-first: VERIFICATION,
+// then ANALYSIS, then IMPLEMENTATION, then EXPLORATION. Anything unmatched
+// defaults to IMPLEMENTATION (deep), so an unknown leaf is never downgraded.
+export function classifyLeaf(leaf) {
+  const label = String((leaf && leaf.label) || '').toLowerCase();
+  if (!label) return LEAF_TYPES.IMPLEMENTATION;
+  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;
+  if (matchesAny(label, EXPLORATION_KEYWORDS)) return LEAF_TYPES.EXPLORATION;
+  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.
+export function tierFor(taskType) {
+  return taskType === LEAF_TYPES.EXPLORATION ? TIERS.CHEAP : TIERS.DEEP;
+}
+
+// modelForLeaf({ label }) -> the opts.model value to write (a string) or null
+// (omit opts.model). This is what F2 stamps onto exploration leaves.
+export function modelForLeaf(leaf) {
+  return TIER_MODEL[tierFor(classifyLeaf(leaf))];
+}
+
+// isKnownTierModel(modelId) -> true if modelId is one of the concrete downgrade
+// models (cheap/balanced). Used by the linter to reject an opts.model literal
+// that is not a recognised tier. null/'' are not "known" (deep = omission, not a
+// literal). 'opus' is intentionally NOT known — we never pin up.
+export function isKnownTierModel(modelId) {
+  if (!modelId) return false;
+  return Object.values(TIER_MODEL).filter(Boolean).includes(modelId);
+}
+
+// isDowngradeModel(modelId) -> true if modelId pins a leaf BELOW the inherited
+// tier (cheap or balanced). The linter's anti-downgrade rule uses this: a
+// protected leaf must never carry a downgrade model.
+export function isDowngradeModel(modelId) {
+  return modelId === TIER_MODEL.cheap || modelId === TIER_MODEL.balanced;
+}

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

@@ -0,0 +1,45 @@
+// Feeder B — adversarial-pass verdict -> ledger outcome (F3).
+//
+// The adversarial VALIDATE pass runs N skeptics against ONE downgraded leaf,
+// each trying to REFUTE that the cheap model is adequate there. The leaf is
+// "flagged" (cheap inadequate) when at least half the skeptics refute it. This
+// module maps that vote into the ledger's binary outcome:
+//
+//   success = the cheap model SURVIVED the panel (refuters fell short of half).
+//
+// It is PURE and DETERMINISTIC and does no I/O. The actual byan_suitability_record
+// call happens in the orchestrating skill on a main-thread turn — a workflow
+// script cannot call MCP tools or write state (sandbox/state-coupling rule), so
+// the script returns the verdicts as DATA and the skill records them. This
+// module is the shared shaping step both sides agree on.
+
+// At least half the panel refuting flags the leaf. Ties resolve AGAINST the
+// cheap model — the conservative bias for an anti-downgrade rail. The adversarial
+// pass uses an odd panel (3) so ties do not arise in practice; the rule is
+// defined for any n so an even panel still degrades safely.
+function isFlagged(refutedVotes, totalVotes) {
+  return refutedVotes * 2 >= totalVotes;
+}
+
+// verdictToOutcome({ model, leafId, refutedVotes, totalVotes }) ->
+//   { model, leafId, success }. Throws on malformed input (programmer error);
+// the no-op-on-failure contract lives one layer up, at the MCP store boundary.
+export function verdictToOutcome({ model, leafId, refutedVotes, totalVotes } = {}) {
+  if (!model || !leafId) throw new Error('verdictToOutcome requires model and leafId');
+  const total = Number(totalVotes);
+  const refuted = Number(refutedVotes);
+  if (!Number.isInteger(total) || total <= 0) {
+    throw new Error('totalVotes must be a positive integer');
+  }
+  if (!Number.isInteger(refuted) || refuted < 0 || refuted > total) {
+    throw new Error('refutedVotes must be an integer in 0..totalVotes');
+  }
+  return { model, leafId, success: !isFlagged(refuted, total) };
+}
+
+// verdictsToOutcomes([verdict, ...]) -> [outcome, ...]. The skill iterates this
+// and calls byan_suitability_record once per outcome.
+export function verdictsToOutcomes(verdicts = []) {
+  if (!Array.isArray(verdicts)) throw new Error('verdictsToOutcomes expects an array');
+  return verdicts.map(verdictToOutcome);
+}

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

@@ -0,0 +1,102 @@
+// Model-suitability ledger — persistence + MCP-facing surface (F2).
+//
+// The pure math lives in suitability.js (no I/O). This module is the ONLY place
+// that writes the ledger to disk, which is what makes the sandbox/state-coupling
+// rule hold: a .claude/workflows/*.js script cannot import this file (the sandbox
+// forbids it) and therefore cannot write ledger state. State changes flow only
+// through the MCP tools (byan_suitability_record / _report), which call into
+// here. The workflow feeds the tool; the tool owns the write.
+//
+// Best-effort contract (mirrors strict-sync.js): record() NEVER throws. Bad
+// input or a failed write degrades to { recorded: false, reason } and leaves the
+// on-disk ledger untouched. A telemetry write must never block or corrupt the
+// real work — losing one outcome is acceptable; crashing the caller is not.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { recordOutcome as pureRecord, rating, report } from './suitability.js';
+
+export function resolveRoot(projectRoot) {
+  return projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+// The ledger lives beside the FD state, under the gitignored _byan-output/.
+export function ledgerPath(projectRoot) {
+  return path.join(resolveRoot(projectRoot), '_byan-output', 'suitability-ledger.json');
+}
+
+// readLedger never throws: a missing, corrupt, or non-object file reads as {}.
+// A consumer should always get a usable ledger, even degraded to empty.
+export function readLedger({ projectRoot, io = fs } = {}) {
+  const p = ledgerPath(projectRoot);
+  try {
+    if (!io.existsSync(p)) return {};
+    const parsed = JSON.parse(io.readFileSync(p, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeLedger(ledger, { projectRoot, io = fs } = {}) {
+  const p = ledgerPath(projectRoot);
+  io.mkdirSync(path.dirname(p), { recursive: true });
+  // Atomic write: stage into a temp file ADJACENT to the target (same directory,
+  // hence same filesystem, so the rename is atomic and EXDEV-free), then rename
+  // over the target. A partial or failed write leaves the existing ledger
+  // byte-identical. The "untouched on failure" guarantee is then literally true,
+  // not merely tolerated downstream by readLedger.
+  const tmp = `${p}.tmp`;
+  try {
+    io.writeFileSync(tmp, JSON.stringify(ledger, null, 2));
+    io.renameSync(tmp, p);
+  } catch (err) {
+    // Best-effort cleanup so a failed write leaves no orphan staged file behind.
+    try {
+      io.unlinkSync(tmp);
+    } catch {
+      void 0; // nothing was staged, or unlink is unsupported — nothing to clean
+    }
+    throw err;
+  }
+  return p;
+}
+
+// record one adequacy outcome. Returns { recorded, reason, rating, source }.
+// recorded:false with reason 'invalid_input' (bad args) or 'persist_failed'
+// (write threw). On a persist failure the rating reflects the PRE-write ledger,
+// so the caller never sees a phantom update. Never throws.
+export function record({ model, leafId, success, source, projectRoot, io = fs } = {}) {
+  const before = readLedger({ projectRoot, io });
+
+  let after;
+  try {
+    after = pureRecord(before, { model, leafId, success });
+  } catch (err) {
+    return { recorded: false, reason: 'invalid_input', error: err.message, source: source || null };
+  }
+
+  let recorded = true;
+  let reason = null;
+  try {
+    writeLedger(after, { projectRoot, io });
+  } catch (err) {
+    recorded = false;
+    reason = 'persist_failed';
+    void err; // swallowed by contract — the outcome is lost, the caller is safe
+  }
+
+  return {
+    recorded,
+    reason,
+    rating: rating(recorded ? after : before, { model, leafId }),
+    source: source || null,
+  };
+}
+
+// reportLedger -> advisory ratings (most-actionable first), each carrying the
+// credible lower bound and n. Optional model filter. Read-only.
+export function reportLedger({ model, projectRoot, io = fs } = {}) {
+  const rows = report(readLedger({ projectRoot, io }));
+  return model ? rows.filter((r) => r.model === model) : rows;
+}

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

@@ -0,0 +1,234 @@
+// Model-suitability ledger — the math core (design D1, advisory only).
+//
+// It answers ONE question per (model x leaf) pair: from the binary adequacy
+// outcomes we have seen, is this CHEAP model safe to keep on this leaf? The
+// answer is conservative by construction — it commits to "keep-cheap" only when
+// the evidence is both good AND plentiful, and to "demote" only when the
+// evidence is clearly bad. Everything in between is "watch": not enough proof to
+// move, so the safe default (deep / no downgrade) stands.
+//
+// This module is PURE and DETERMINISTIC. No Date, no Math.random, no I/O. The
+// ledger is a plain object the caller owns; every update returns a NEW ledger.
+// Persistence lives behind the MCP tools (F2) so the sandbox/state-coupling rule
+// holds: a workflow script never writes ledger state, the MCP tool does. The
+// statistics here are the part a downgraded model would get subtly wrong, which
+// is exactly why this leaf was kept on the strong model.
+
+// Defaults. The math does not hard-depend on these — they are the policy knobs,
+// passed through opts and overridable per call.
+//
+// Prior Beta(1,1) is uniform/neutral: the conservatism comes from the credible
+// INTERVAL (a thin sample yields a wide interval and therefore a low floor),
+// not from a stacked prior. keepThreshold > demoteThreshold leaves a deliberate
+// "watch" band between them that a straddling interval falls into.
+export const DEFAULTS = Object.freeze({
+  priorAlpha: 1,
+  priorBeta: 1,
+  credibleLevel: 0.95, // equal-tailed credible interval width
+  keepThreshold: 0.85, // lower credible bound >= this  -> keep-cheap (proven safe)
+  demoteThreshold: 0.70, // upper credible bound <= this -> demote (proven unsafe)
+});
+
+// --- Statistics: regularized incomplete beta and its inverse ---------------
+//
+// We need P(p <= x) for a Beta(a,b) posterior (the regularized incomplete beta
+// I_x(a,b)) and its inverse (the quantile) to read off a credible interval.
+// Implemented from first principles (Lanczos log-gamma + Numerical-Recipes
+// continued fraction + bisection) so there is no dependency and the result is
+// reproducible to ~1e-10.
+
+const LANCZOS_G = 7;
+const LANCZOS_C = [
+  0.99999999999980993,
+  676.5203681218851,
+  -1259.1392167224028,
+  771.32342877765313,
+  -176.61502916214059,
+  12.507343278686905,
+  -0.13857109526572012,
+  9.9843695780195716e-6,
+  1.5056327351493116e-7,
+];
+
+// Natural log of the Gamma function (Lanczos approximation, reflection for z<0.5).
+export function lgamma(z) {
+  if (z < 0.5) {
+    return Math.log(Math.PI / Math.sin(Math.PI * z)) - lgamma(1 - z);
+  }
+  z -= 1;
+  let x = LANCZOS_C[0];
+  for (let i = 1; i < LANCZOS_G + 2; i++) x += LANCZOS_C[i] / (z + i);
+  const t = z + LANCZOS_G + 0.5;
+  return 0.5 * Math.log(2 * Math.PI) + (z + 0.5) * Math.log(t) - t + Math.log(x);
+}
+
+// Continued fraction for the incomplete beta (Lentz's method). The 300-iteration
+// cap is a backstop, not a working limit: betai only ever calls this on the
+// fast-converging side (x < (a+1)/(a+b+2), enforced by its reflection), where
+// Lentz reaches the 1e-12 tolerance in tens of steps for any realistic posterior.
+function betacf(x, a, b) {
+  const FPMIN = 1e-300;
+  const qab = a + b;
+  const qap = a + 1;
+  const qam = a - 1;
+  let c = 1;
+  let d = 1 - (qab * x) / qap;
+  if (Math.abs(d) < FPMIN) d = FPMIN;
+  d = 1 / d;
+  let h = d;
+  for (let m = 1; m <= 300; m++) {
+    const m2 = 2 * m;
+    let aa = (m * (b - m) * x) / ((qam + m2) * (a + m2));
+    d = 1 + aa * d;
+    if (Math.abs(d) < FPMIN) d = FPMIN;
+    c = 1 + aa / c;
+    if (Math.abs(c) < FPMIN) c = FPMIN;
+    d = 1 / d;
+    h *= d * c;
+    aa = (-(a + m) * (qab + m) * x) / ((a + m2) * (qap + m2));
+    d = 1 + aa * d;
+    if (Math.abs(d) < FPMIN) d = FPMIN;
+    c = 1 + aa / c;
+    if (Math.abs(c) < FPMIN) c = FPMIN;
+    d = 1 / d;
+    const del = d * c;
+    h *= del;
+    if (Math.abs(del - 1) < 1e-12) break;
+  }
+  return h;
+}
+
+// Regularized incomplete beta I_x(a,b) = P(X <= x) for X ~ Beta(a,b).
+export function betai(x, a, b) {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+  const logBeta = lgamma(a + b) - lgamma(a) - lgamma(b);
+  const front = Math.exp(logBeta + a * Math.log(x) + b * Math.log(1 - x));
+  // Use the fraction on the side where it converges fastest, then reflect.
+  if (x < (a + 1) / (a + b + 2)) {
+    return (front * betacf(x, a, b)) / a;
+  }
+  return 1 - (front * betacf(1 - x, b, a)) / b;
+}
+
+// Inverse CDF: smallest x with I_x(a,b) = p. Bisection — monotone, dependency
+// free, deterministic. 100 halvings drive the bracket below 1e-30, far tighter
+// than the betai accuracy, so the quantile is exact for our purposes.
+export function betaQuantile(p, a, b) {
+  if (p <= 0) return 0;
+  if (p >= 1) return 1;
+  let lo = 0;
+  let hi = 1;
+  for (let i = 0; i < 100; i++) {
+    const mid = (lo + hi) / 2;
+    if (betai(mid, a, b) < p) lo = mid;
+    else hi = mid;
+  }
+  return (lo + hi) / 2;
+}
+
+// --- Ledger ----------------------------------------------------------------
+
+// Key for a (model x leaf) pair. '::' is reserved as the separator; model and
+// leafId are also stored on the entry so the report never has to parse keys.
+export function leafKey(model, leafId) {
+  return `${model}::${leafId}`;
+}
+
+function emptyEntry(model, leafId) {
+  return { model, leafId, successes: 0, failures: 0 };
+}
+
+// recordOutcome(ledger, { model, leafId, success }) -> a NEW ledger.
+//
+// success === true  : the cheap model was adequate on this leaf this time.
+// success === false : it was not (the adversarial pass refuted it).
+// Stores RAW counts (prior-independent) so the prior stays a read-time policy.
+// Throws on malformed input — that is a programmer error, surfaced loudly, not
+// silently swallowed. (The MCP tool's no-op-on-failure contract is about
+// transport/persistence, not input validation.)
+export function recordOutcome(ledger, { model, leafId, success } = {}) {
+  if (!model || !leafId) throw new Error('recordOutcome requires model and leafId');
+  if (typeof success !== 'boolean') throw new Error('recordOutcome requires success:boolean');
+  const key = leafKey(model, leafId);
+  const cur = ledger[key] || emptyEntry(model, leafId);
+  const next = {
+    model,
+    leafId,
+    successes: cur.successes + (success ? 1 : 0),
+    failures: cur.failures + (success ? 0 : 1),
+  };
+  return { ...ledger, [key]: next };
+}
+
+// posterior(entry, opts) -> { alpha, beta }. Applies the prior to raw counts.
+export function posterior(entry, opts) {
+  const o = { ...DEFAULTS, ...opts };
+  return {
+    alpha: o.priorAlpha + (entry ? entry.successes : 0),
+    beta: o.priorBeta + (entry ? entry.failures : 0),
+  };
+}
+
+// verdictFromBounds(lower, upper, opts) -> 'keep-cheap' | 'demote' | 'watch'.
+// keep-cheap and demote are mutually exclusive (lower <= upper), so the order
+// of the two tests does not matter; "watch" is everything the evidence has not
+// settled. This is the whole safety policy in three lines.
+export function verdictFromBounds(lower, upper, opts) {
+  const o = { ...DEFAULTS, ...opts };
+  if (lower >= o.keepThreshold) return 'keep-cheap';
+  if (upper <= o.demoteThreshold) return 'demote';
+  return 'watch';
+}
+
+// rating(ledger, { model, leafId }, opts) -> the full advisory record. ALWAYS
+// carries the credible lower bound and n; a consumer that shows only `mean`
+// would be discarding the very signal that makes a thin sample untrustworthy.
+export function rating(ledger, { model, leafId }, opts) {
+  const o = { ...DEFAULTS, ...opts };
+  const entry = ledger[leafKey(model, leafId)] || emptyEntry(model, leafId);
+  const { alpha, beta } = posterior(entry, o);
+  const n = entry.successes + entry.failures;
+  const tail = (1 - o.credibleLevel) / 2;
+  const lower = betaQuantile(tail, alpha, beta);
+  const upper = betaQuantile(1 - tail, alpha, beta);
+  const mean = alpha / (alpha + beta);
+  return {
+    model,
+    leafId,
+    n,
+    successes: entry.successes,
+    failures: entry.failures,
+    mean,
+    lower,
+    upper,
+    credibleLevel: o.credibleLevel,
+    verdict: verdictFromBounds(lower, upper, o),
+  };
+}
+
+// Most-actionable first: demote, then watch, then keep-cheap; ties by leaf then
+// model for stable output.
+const SEVERITY = { demote: 0, watch: 1, 'keep-cheap': 2 };
+
+// report(ledger, opts) -> ratings for every pair, severity-sorted.
+export function report(ledger, opts) {
+  return Object.values(ledger || {})
+    .map((e) => rating(ledger, { model: e.model, leafId: e.leafId }, opts))
+    .sort(
+      (a, b) =>
+        SEVERITY[a.verdict] - SEVERITY[b.verdict] ||
+        a.leafId.localeCompare(b.leafId) ||
+        a.model.localeCompare(b.model),
+    );
+}
+
+// formatRating(rating) -> one advisory line. It REFUSES to print a bare point
+// estimate: the credible lower bound and n are always present, because "92%"
+// over 3 samples and "92%" over 300 are not the same claim, and only the second
+// should ever move a human to drop a downgrade.
+export function formatRating(r) {
+  const pct = (x) => (x * 100).toFixed(1);
+  const lvl = Math.round(r.credibleLevel * 100);
+  return `${r.model} x ${r.leafId}: lower${lvl}=${pct(r.lower)}% (mean ${pct(r.mean)}%, n=${r.n}) -> ${r.verdict}`;
+}

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

@@ -12,6 +12,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { isKnownTierModel, isDowngradeModel, classifyLeaf, LEAF_TYPES } 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.
@@ -87,10 +88,79 @@ export function metaLiteralViolations(src) {
   }];
 }
 
+// Model-routing anti-downgrade guard (enforcement-bridge F3).
+//
+// A native leaf may pin a CHEAPER model (opts.model) ONLY when it is an
+// EXPLORATION leaf (read/load/parse/detect). Implement, verify and analysis
+// leaves must inherit the session model (no opts.model). This is the structural
+// net that stops a cheap model from silently landing on a heavy leaf — the exact
+// STRICT-2 (No Downgrade) line. The source of truth for tiers and leaf
+// classification is native-tiers.js; this rule only enforces it.
+//
+// Parsing is comment-stripped (a model: token in a comment is not a real call).
+// Each model: is keyed to the nearest preceding label: within the SAME opts
+// object (no intervening }). Downgraded leaves carry static-string labels by
+// convention, so a quoted-literal match is sufficient.
+const MODEL_RE = /\bmodel:\s*(['"`])([^'"`]*)\1/g;
+const LABEL_RE = /\blabel:\s*(['"`])([^'"`]*)\1/g;
+
+function nearestLabelBefore(code, modelIndex) {
+  const before = code.slice(0, modelIndex);
+  let last = null;
+  let m;
+  LABEL_RE.lastIndex = 0;
+  while ((m = LABEL_RE.exec(before))) {
+    last = { value: m[2], end: m.index + m[0].length };
+  }
+  if (!last) return null;
+  // Same object only: an object-close between the label and the model means the
+  // label belongs to a different (earlier) call.
+  if (before.slice(last.end).includes('}')) return null;
+  return last.value;
+}
+
+export function modelRoutingViolations(src) {
+  const code = stripComments(src);
+  const out = [];
+  let m;
+  MODEL_RE.lastIndex = 0;
+  while ((m = MODEL_RE.exec(code))) {
+    const model = m[2];
+    if (!isKnownTierModel(model)) {
+      out.push({
+        id: 'unknown-tier-model',
+        msg: `opts.model '${model}' is not a known downgrade tier (cheap/balanced); never pin up — omit opts.model to inherit the session model on deep leaves`,
+      });
+      continue;
+    }
+    const label = nearestLabelBefore(code, m.index);
+    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`,
+      });
+      continue;
+    }
+    if (isDowngradeModel(model) && classifyLeaf({ label }) !== LEAF_TYPES.EXPLORATION) {
+      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)`,
+      });
+    }
+  }
+  return out;
+}
+
 // Full native-workflow contract: state-coupling (comment-stripped) + clock/RNG
-// (raw) + meta-literal-first. Returns the combined [{ id, msg }] violations.
+// (raw) + meta-literal-first + model-routing anti-downgrade. Returns the
+// combined [{ id, msg }] violations.
 export function validateContract(src) {
-  return [...lintSource(src), ...clockRngViolations(src), ...metaLiteralViolations(src)];
+  return [
+    ...lintSource(src),
+    ...clockRngViolations(src),
+    ...metaLiteralViolations(src),
+    ...modelRoutingViolations(src),
+  ];
 }
 
 // Lint every *.js in a directory (non-recursive; native workflows are flat)

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

@@ -5,18 +5,24 @@
   "main": "server.js",
   "type": "module",
   "bin": {
-    "byan-mcp": "./server.js"
+    "byan-mcp": "./server.js",
+    "byan-sync-rules": "./bin/byan-sync-rules.js"
   },
   "scripts": {
     "start": "node server.js",
     "test": "node --test test/*.test.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "js-yaml": "^4.1.1"
   },
   "engines": {
     "node": ">=18.0.0"
   },
-  "keywords": ["mcp", "byan", "claude-code"],
+  "keywords": [
+    "mcp",
+    "byan",
+    "claude-code"
+  ],
   "license": "MIT"
 }