create-byan-agent 2.27.0 → 2.28.0

package/CHANGELOG.md

@@ -9,6 +9,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.28.0] - 2026-06-23
+
+### Added - Advisory model-tiering lint for native workflows
+
+- `workflows-lint.js` gains `untieredExplorationViolations`: a NON-blocking
+  advisory (surfaced by `byan-lint-workflows.js --advise`, plus a one-line
+  summary on every run) that flags an exploration-labelled `agent()` leaf in a
+  `.claude/workflows/*.js` script which runs on the session model instead of
+  downgrading to `haiku` (a possible token saving). It reuses `classifyLeaf` /
+  `isDowngradeModel` from `native-tiers.js` (single source of truth).
+- It is DELIBERATELY out of `validateContract`: the anti-downgrade floor stays a
+  hard rule, but forcing `haiku` onto a judgment-bearing leaf (a gate, a
+  classification, an exact conversion consumed verbatim downstream) would be a
+  STRICT-2 regression, so the per-leaf deep-vs-cheap call stays with the author.
+- There is no per-leaf "effort" knob in the native `agent()` / Agent API (it
+  exposes only `model`), so effort-by-complexity reduces to model-by-complexity.
+  Documented in `native-workflows.md`, the SKILL DISPATCH section, and
+  `docs/native-workflows-contract.md`.
+
+### Changed - `.mcp.json` tests realigned to the portable-config design
+
+- Five test suites still asserted the pre-portable `.mcp.json` shape
+  (`env.BYAN_API_URL` present) and failed after 2.27.0. Realigned them to the
+  portable invariant: the `byan` entry is present but carries no `BYAN_API_URL`
+  and no token (the server self-resolves its config). Security invariants are
+  unchanged: the no-token assertions and `verify`'s raw-token / `/api`-suffix
+  drift detection remain. Full suite back to green (2326/2326).
+
+## [2.27.0] - 2026-06-19
+
 ### Fixed - Portable MCP config: the server resolves its own credentials
 
 The byan MCP server now resolves its config (`BYAN_API_URL` / `BYAN_API_TOKEN`

package/install/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.27.0",
+  "version": "2.28.0",
   "description": "BYAN - Intelligent AI agent installer with multi-platform native support (Claude Code, Codex/OpenCode)",
   "bin": {
     "create-byan-agent": "bin/create-byan-agent-v2.js"

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

@@ -22,6 +22,31 @@ A native workflow script mutates FD/strict state only through the `byan_fd_*` /
   forbidden import/require in `.claude/workflows/*.js`.
 - `.githooks/pre-commit` runs that linter, so a violation blocks the commit.
 
+## Model tiering — floor enforced, ceiling advisory
+
+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). The doctrine is binary: a pure
+EXPLORATION leaf (read/load/parse/detect) may downgrade to `model: 'haiku'`;
+implementation / verification / analysis leaves OMIT `opts.model` and inherit the
+session model (no pin-up to opus).
+
+The linter splits the two directions:
+
+- **Floor (HARD, blocks the commit)** — a downgrade model on a PROTECTED leaf, or
+  a pin-up, is a contract violation (`modelRoutingViolations`). This is the
+  STRICT-2 No Downgrade net.
+- **Ceiling (ADVISORY, non-blocking)** — an exploration-labelled leaf that runs
+  deep is *reported* (`byan-lint-workflows.js --advise`), not forced. `classifyLeaf`
+  is permissive: many exploration-labelled leaves legitimately stay deep because
+  they bear a HALT/prerequisite gate, a classification, or an exact conversion
+  consumed verbatim downstream. The human owns that per-leaf call. Forcing haiku
+  on them would be the very downgrade the floor forbids.
+
+A per-leaf "effort" knob is not available: the native `agent()` / Agent API exposes
+only `model`, so model tier is the sole token lever. Effort-by-complexity reduces
+to model-by-complexity.
+
 ## Registry + resolution
 
 - Registry: `.claude/workflows/INDEX.md`, generated by

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

@@ -66,6 +66,7 @@ Never call `byan_update_apply` without explicit user consent. That tool returns
     - nature `exploration` (load/read/scan/list/parse/fetch...) → `haiku`
     - nature `implementation` / `verification` / `analysis` / unknown → deep = **inherit the session model**
     - Keep protected work (verify/analysis/implement) off haiku regardless of size ; no pin-up to opus. Pass an explicit `nature` to `byan_dispatch` when you know it.
+  - **Inside native workflow scripts** (`.claude/workflows/*.js`) the SAME tiering applies per `agent()` leaf via `opts.model`, enforced by the workflow linter as a FLOOR not a ceiling : `modelRoutingViolations` HARD-blocks a downgrade on a protected leaf (or a pin-up) ; 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. No per-leaf effort knob exists (the API exposes only `model`), so effort-by-complexity reduces to model-by-complexity.
 - **Output** : a table `{ feature → specialist → model → strategy → estimated_tokens }`.
 - **If no specialist matches** : halt. Ask user whether to run INT (agent recruitment) first. Do NOT fallback silently to general-purpose.
 - **Exit gate** : user validates the mapping.

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

@@ -2,17 +2,23 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { validateContract } from '../lib/workflows-lint.js';
+import { validateContract, untieredExplorationViolations } from '../lib/workflows-lint.js';
 
 // Validate native workflow scripts under .claude/workflows/ against the full
 // contract (state-coupling + clock/RNG + meta-literal) AND node --check syntax.
-// Exits non-zero on any violation (used by the pre-commit gate).
-// Usage: node bin/byan-lint-workflows.js [--root <dir>]
+// Exits non-zero on any contract violation (used by the pre-commit gate).
+//
+// Tiering is reported SEPARATELY and NON-BLOCKING: exploration-labelled leaves
+// that run deep are a possible token saving, but many legitimately stay deep
+// (they bear a gate/classification/exact-conversion). So they are an ADVISORY,
+// never a hard failure. A one-line summary always prints; --advise lists each one.
+// Usage: node bin/byan-lint-workflows.js [--root <dir>] [--advise]
 
 function parseArgs(argv) {
   const args = {};
   for (let i = 2; i < argv.length; i++) {
     if (argv[i] === '--root') args.projectRoot = argv[++i];
+    else if (argv[i] === '--advise') args.advise = true;
   }
   return args;
 }
@@ -32,8 +38,10 @@ try {
 }
 
 let failed = 0;
+const advisories = [];
 for (const file of files) {
-  const violations = validateContract(fs.readFileSync(file, 'utf8'));
+  const src = fs.readFileSync(file, 'utf8');
+  const violations = validateContract(src);
 
   // Syntax gate: a native script must parse.
   try {
@@ -48,6 +56,24 @@ for (const file of files) {
       process.stderr.write(`[byan-lint-workflows] ${file}: ${v.id} - ${v.msg}\n`);
     }
   }
+
+  // Non-blocking tiering advisory: exploration leaves that run deep.
+  for (const a of untieredExplorationViolations(src)) {
+    advisories.push({ file, ...a });
+  }
+}
+
+// Tiering advisory is informational only — it never changes the exit code.
+if (advisories.length) {
+  if (args.advise) {
+    for (const a of advisories) {
+      process.stdout.write(`[byan-lint-workflows] ADVISORY ${a.file}: ${a.id} - ${a.msg}\n`);
+    }
+  } else {
+    process.stdout.write(
+      `[byan-lint-workflows] advisory: ${advisories.length} exploration leaf(s) run deep (rerun with --advise to list; keep deep if they bear a gate/judgment, else add model: 'haiku')\n`
+    );
+  }
 }
 
 if (failed === 0) {

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

@@ -151,9 +151,75 @@ export function modelRoutingViolations(src) {
   return out;
 }
 
+// Positive tiering ADVISORY — the symmetric half of modelRoutingViolations.
+//
+// modelRoutingViolations stops a downgrade from landing on a PROTECTED leaf
+// (the anti-downgrade direction, a HARD contract rule). This function surfaces the
+// opposite signal: an EXPLORATION-labelled leaf (read/load/parse/detect) that does
+// NOT downgrade and so runs on the session model (Opus) for cheap I/O — a possible
+// token saving. It is NON-BLOCKING (the bin's --advise mode, not validateContract):
+// classifyLeaf is permissive, so a flagged leaf may legitimately stay deep when it
+// bears judgment (a gate, a classification, an exact conversion). The human owns
+// the call. Same source of truth: classifyLeaf + isDowngradeModel from
+// native-tiers.js; this only reports against the contract those encode.
+//
+// Membership: a model: token belongs to a label when it sits in the SAME opts
+// object — between the brace that closes the previous object and the one that
+// closes this label's object — so the rule is order-independent (model: may sit
+// before OR after label: within { ... }). Comment-stripped, like the others.
+//
+// Conservative by construction: only STATIC quoted/backtick labels are seen, and
+// only labels classifyLeaf rules EXPLORATION fire. A computed (unquoted) label or
+// a non-exploration label is never flagged, so the rule never forces a downgrade
+// onto protected or unclassifiable work — it only recovers the safe savings.
+function sameOptsObjectText(code, labelStart, labelEnd) {
+  const prevClose = code.lastIndexOf('}', labelStart);
+  const left = prevClose === -1 ? 0 : prevClose + 1;
+  const nextClose = code.indexOf('}', labelEnd);
+  const right = nextClose === -1 ? code.length : nextClose;
+  return code.slice(left, right);
+}
+
+function objectHasDowngradeModel(objText) {
+  let mm;
+  MODEL_RE.lastIndex = 0;
+  while ((mm = MODEL_RE.exec(objText))) {
+    if (isDowngradeModel(mm[2])) return true;
+  }
+  return false;
+}
+
+export function untieredExplorationViolations(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.EXPLORATION) continue;
+    const objText = sameOptsObjectText(code, m.index, m.index + m[0].length);
+    if (!objectHasDowngradeModel(objText)) {
+      out.push({
+        id: 'untiered-exploration',
+        msg: `exploration leaf '${label}' does not pin a downgrade model; add model: 'haiku' so cheap I/O does not run on the session model (token waste)`,
+      });
+    }
+  }
+  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.
+//
+// untieredExplorationViolations is DELIBERATELY NOT in the hard contract. The
+// tiering rule is a FLOOR (forbid a downgrade on a protected leaf), not a CEILING
+// (force every exploration-labelled leaf to downgrade). classifyLeaf is permissive
+// — many exploration-labelled leaves bear judgment (a HALT/prereq gate, a
+// classification, an exact conversion consumed verbatim downstream) and MUST stay
+// deep. Forcing them to haiku would be the exact STRICT-2 No Downgrade regression.
+// So the positive check ships as a non-blocking ADVISORY (the bin's --advise mode);
+// the human keeps the per-leaf judgment. See docs/native-workflows-contract.md.
 export function validateContract(src) {
   return [
     ...lintSource(src),

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": "0a1f4b1333f7f42a43b1a8ad57b0d7d687aec95f149ae13ba98b78970ed3bd09"
+      "sourceHash": "88403d60531d9fb3e7cdb566429643f1f47baf9918593e8082ecc98eedebb878"
     },
     "byan-byan-v2": {
       "name": "byan-byan-v2",

package/install/templates/docs/native-workflows-contract.md

@@ -153,6 +153,14 @@ Enforcement (because the in-session hooks do not fire inside a script):
 - `test/native-routing-integration.test.js` pins the invariant on the SHIPPED
   scripts: every script passes the contract, and every downgrade sits on an
   exploration leaf.
+- `workflows-lint.js` -> `untieredExplorationViolations` is the SYMMETRIC
+  advisory: it surfaces an exploration-labelled leaf that runs deep (a possible
+  saving). It is DELIBERATELY OUT of `validateContract` — forcing those leaves to
+  haiku is exactly the regression the curation above rejected, so it is a
+  non-blocking report (`byan-lint-workflows.js --advise`), not a gate. The
+  per-leaf deep-vs-cheap call stays with the author. There is no per-leaf effort
+  knob (the native `agent()` / Agent API exposes only `model`), so model tier is
+  the sole token lever and effort-by-complexity reduces to model-by-complexity.
 
 If a future runtime needs full model ids instead of the `haiku`/`sonnet`
 aliases, `TIER_MODEL` in `native-tiers.js` is the only edit; the linter then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.27.0",
+  "version": "2.28.0",
   "description": "BYAN v2.8 - Intelligent AI agent creator with ELO trust system + scientific fact-check + Hermes universal dispatcher + native Claude Code integration (hooks, skills, MCP server). Multi-platform (Claude Code, Codex). Merise Agile + TDD + 71 Mantras. ~54% LLM cost savings.",
   "main": "src/index.js",
   "bin": {