create-byan-agent 2.38.0 → 2.41.0

package/install/templates/.claude/hooks/lib/usage-estimator.js

@@ -0,0 +1,262 @@
+/**
+ * usage-estimator — estimate Claude's rolling-5h token consumption from Claude
+ * Code's LOCAL usage accounting, so BYAN can decide when to auto-delegate to a
+ * secondary pool (Codex) BEFORE the 5h wall.
+ *
+ * The honest ceiling (stated plainly, not hidden): no provider exposes a
+ * machine-readable 5h quota, and Claude Code fetches the authoritative
+ * "/usage" figure live from Anthropic — it is NOT persisted locally. What IS
+ * local is per-session token accounting under
+ * `~/.claude/usage-data/session-meta/*.json` (real input/output token totals +
+ * start_time + duration). This module sums those over the rolling window and
+ * returns an ESTIMATE with an explicit confidence, never a false-precision
+ * figure. `pct` is only produced when a budget (the plan's rough token ceiling)
+ * is supplied — otherwise it is null (we do not invent the ceiling).
+ *
+ * Portable-core posture (PORTABLE-3): `~/.claude` is a per-machine native
+ * accelerator, NOT a BYAN source of truth. When it is absent the estimator
+ * degrades to a null/none result rather than throwing — the nature-based
+ * delegation path stays functional without any gauge.
+ *
+ * Purity: normalizeSession / sumWindowTokens / estimatePct are pure. All I/O is
+ * behind an injected `fs`, so the unit tests never touch the real home dir.
+ */
+
+const realFs = require('fs');
+const realPath = require('path');
+const os = require('os');
+
+const FIVE_HOURS_MS = 5 * 60 * 60 * 1000;
+
+// Parse one session-meta object into { startMs, endMs, tokens }, or null when it
+// carries no usable start time. Token fields default to 0 (never NaN) so the
+// downstream sum is always safe.
+function normalizeSession(meta) {
+  if (!meta || typeof meta !== 'object') return null;
+  const startMs = Date.parse(meta.start_time);
+  if (!Number.isFinite(startMs)) return null;
+  const durationMin = Number(meta.duration_minutes) || 0;
+  const endMs = startMs + Math.max(0, durationMin) * 60 * 1000;
+  const input = Number(meta.input_tokens) || 0;
+  const output = Number(meta.output_tokens) || 0;
+  return { startMs, endMs, tokens: input + output };
+}
+
+// Sum tokens attributable to the rolling window [now-windowMs, now], pro-rating
+// a session by the fraction of its own span that overlaps the window. A
+// zero-duration session is an instant: counted fully if inside, else zero. This
+// pro-rata is the honest approximation available from per-session totals (the
+// meta has no per-message breakdown).
+function sumWindowTokens(sessions, now, windowMs = FIVE_HOURS_MS) {
+  const windowStart = now - windowMs;
+  let total = 0;
+  for (const s of sessions) {
+    if (!s) continue;
+    const span = s.endMs - s.startMs;
+    if (span <= 0) {
+      if (s.startMs >= windowStart && s.startMs <= now) total += s.tokens;
+      continue;
+    }
+    const overlap = Math.min(s.endMs, now) - Math.max(s.startMs, windowStart);
+    if (overlap <= 0) continue;
+    total += s.tokens * (overlap / span);
+  }
+  return Math.round(total);
+}
+
+// Turn an estimated token count into a percentage of a supplied budget. Without
+// a budget we return { pct: null, confidence: 'none' } — we do not fabricate the
+// ceiling. With a budget the percentage is a LOW-confidence estimate (the token
+// units are not the exact rate-limit units Anthropic meters), clamped to [0,100].
+function estimatePct(estimatedTokens, budget) {
+  if (!budget || budget <= 0) return { pct: null, confidence: 'none' };
+  const pct = Math.max(0, Math.min(100, Math.round((estimatedTokens / budget) * 100)));
+  return { pct, confidence: 'low' };
+}
+
+// Weighted token cost of one assistant message's usage block. Fresh tokens
+// (input + output + cache creation) count at full weight; cache READS are
+// weighted down (CACHE_READ_WEIGHT) because the same context is re-read from
+// cache every turn and Anthropic bills a cache hit at roughly a tenth of a fresh
+// input token — counting it at full weight would inflate a long conversation to
+// hundreds of millions of tokens (the same context re-counted each turn). This
+// yields a proportional pressure estimate, not an exact bill. Pure.
+const CACHE_READ_WEIGHT = 0.1;
+
+function sumTokensFromUsage(usage) {
+  if (!usage || typeof usage !== 'object') return 0;
+  const fresh = (Number(usage.input_tokens) || 0)
+    + (Number(usage.output_tokens) || 0)
+    + (Number(usage.cache_creation_input_tokens) || 0);
+  const cacheRead = (Number(usage.cache_read_input_tokens) || 0) * CACHE_READ_WEIGHT;
+  return Math.round(fresh + cacheRead);
+}
+
+// Sum tokens across transcript events whose timestamp lands in the rolling
+// window. Only `assistant` events carry a usage block. Pure — takes already
+// parsed events. Returns { tokens, messagesCounted }.
+function sumTranscriptWindow(events, now, windowMs = FIVE_HOURS_MS) {
+  const windowStart = now - windowMs;
+  let tokens = 0;
+  let messagesCounted = 0;
+  for (const ev of events) {
+    if (!ev || ev.type !== 'assistant' || !ev.message) continue;
+    const ts = Date.parse(ev.timestamp);
+    if (!Number.isFinite(ts) || ts < windowStart || ts > now) continue;
+    tokens += sumTokensFromUsage(ev.message.usage);
+    messagesCounted += 1;
+  }
+  return { tokens, messagesCounted };
+}
+
+// Read the LIVE per-message usage from the session transcripts under
+// ~/.claude/projects/<hash>/*.jsonl. Unlike session-meta (written at session
+// END), transcripts are appended live, so they capture the IN-PROGRESS session
+// — exactly the signal needed to react before the wall. Files untouched within
+// the window are skipped by mtime when statSync is available (perf). Corrupt
+// lines are skipped, not fatal. Returns { tokens, messagesCounted, filesRead }.
+function readTranscriptUsage({ home, now = Date.now(), windowMs = FIVE_HOURS_MS, fs = realFs, path = realPath } = {}) {
+  const root = path.join(home, '.claude', 'projects');
+  const empty = { tokens: 0, messagesCounted: 0, filesRead: 0 };
+  let projectDirs;
+  try {
+    if (!fs.existsSync(root)) return empty;
+    projectDirs = fs.readdirSync(root);
+  } catch {
+    return empty;
+  }
+  const windowStart = now - windowMs;
+  let tokens = 0;
+  let messagesCounted = 0;
+  let filesRead = 0;
+  for (const pd of projectDirs) {
+    const dir = path.join(root, pd);
+    let files;
+    try {
+      files = fs.readdirSync(dir).filter((n) => String(n).endsWith('.jsonl'));
+    } catch {
+      continue;
+    }
+    for (const name of files) {
+      const fp = path.join(dir, name);
+      try {
+        if (typeof fs.statSync === 'function') {
+          const st = fs.statSync(fp);
+          if (Number.isFinite(st.mtimeMs) && st.mtimeMs < windowStart) continue;
+        }
+      } catch {
+        /* stat failed — fall through and try to read */
+      }
+      let content;
+      try {
+        content = fs.readFileSync(fp, 'utf8');
+      } catch {
+        continue;
+      }
+      filesRead += 1;
+      const events = [];
+      for (const line of String(content).split('\n')) {
+        const t = line.trim();
+        if (!t) continue;
+        try {
+          events.push(JSON.parse(t));
+        } catch {
+          /* skip corrupt line */
+        }
+      }
+      const r = sumTranscriptWindow(events, now, windowMs);
+      tokens += r.tokens;
+      messagesCounted += r.messagesCounted;
+    }
+  }
+  return { tokens, messagesCounted, filesRead };
+}
+
+// Read the raw session-meta JSON objects from ~/.claude/usage-data/session-meta.
+// Returns [] when the directory is absent (degraded path). A corrupt file is
+// skipped, not fatal.
+function readSessionMetas({ home, fs = realFs, path = realPath } = {}) {
+  const dir = path.join(home, '.claude', 'usage-data', 'session-meta');
+  let names;
+  try {
+    if (!fs.existsSync(dir)) return [];
+    names = fs.readdirSync(dir).filter((n) => String(n).endsWith('.json'));
+  } catch {
+    return [];
+  }
+  const metas = [];
+  for (const name of names) {
+    try {
+      metas.push(JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8')));
+    } catch {
+      /* skip corrupt file */
+    }
+  }
+  return metas;
+}
+
+// Top-level: estimate Claude's rolling-window usage. Returns a stable shape in
+// every path (including degraded), so callers never branch on undefined:
+//   { estimatedTokens, pct, confidence, source, sessionsCounted, messagesCounted, windowMs }
+// Source precedence, most-live first:
+//   'transcript'   — per-message usage, captures the in-progress session (best)
+//   'session-meta' — coarse per-session totals, blind to the live session
+//   'none'         — no local data (home absent) -> honest null pct
+function estimateClaudeUsage({
+  home = os.homedir(),
+  now = Date.now(),
+  budget = null,
+  windowMs = FIVE_HOURS_MS,
+  fs = realFs,
+  path = realPath,
+} = {}) {
+  // 1. Live transcript signal — preferred (sees the session you are burning NOW).
+  const tr = readTranscriptUsage({ home, now, windowMs, fs, path });
+  if (tr.messagesCounted > 0) {
+    const { pct, confidence } = estimatePct(tr.tokens, budget);
+    return {
+      estimatedTokens: tr.tokens,
+      pct,
+      confidence,
+      source: 'transcript',
+      sessionsCounted: 0,
+      messagesCounted: tr.messagesCounted,
+      windowMs,
+    };
+  }
+
+  // 2. Fallback: coarse per-session totals (post-hoc; blind to the live session).
+  const metas = readSessionMetas({ home, fs, path });
+  if (metas.length === 0) {
+    return { estimatedTokens: 0, pct: null, confidence: 'none', source: 'none', sessionsCounted: 0, messagesCounted: 0, windowMs };
+  }
+  const sessions = metas.map(normalizeSession).filter(Boolean);
+  const inWindow = sessions.filter((s) => {
+    const span = s.endMs - s.startMs;
+    if (span <= 0) return s.startMs >= now - windowMs && s.startMs <= now;
+    return Math.min(s.endMs, now) - Math.max(s.startMs, now - windowMs) > 0;
+  });
+  const estimatedTokens = sumWindowTokens(sessions, now, windowMs);
+  const { pct, confidence } = estimatePct(estimatedTokens, budget);
+  return {
+    estimatedTokens,
+    pct,
+    confidence,
+    source: 'session-meta',
+    sessionsCounted: inWindow.length,
+    messagesCounted: 0,
+    windowMs,
+  };
+}
+
+module.exports = {
+  FIVE_HOURS_MS,
+  normalizeSession,
+  sumWindowTokens,
+  estimatePct,
+  sumTokensFromUsage,
+  sumTranscriptWindow,
+  readTranscriptUsage,
+  readSessionMetas,
+  estimateClaudeUsage,
+};

package/install/templates/.claude/hooks/tier-script-guard.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+// PreToolUse hook — BYAN tier gate on the Workflow tool.
+//
+// The Workflow runtime executes every agent() leaf on the session model unless
+// the script pins opts.model, and a script cannot import native-tiers at
+// runtime (sandbox). The repo linter only sees committed .claude/workflows/
+// files — an AD-HOC script written inline crosses exactly one chokepoint
+// before it runs: this hook. It analyzes the script text with the same source
+// of truth as the linter (lib/tier-script.js -> native-tiers.js) and:
+//
+//   - DENIES ONCE when exploration/mech- leaves have no model tier and no
+//     acknowledgment marker, with the exact leaf list to fix. It never
+//     rewrites the script (a wrong auto-stamp would be the STRICT-2 No
+//     Downgrade regression the doctrine forbids).
+//   - allows an IDENTICAL resubmission after a deny (forces a decision,
+//     never traps the turn) — the deny memory lives in .byan-tier/ (sidecar,
+//     gitignored) keyed by script hash.
+//   - allows registry (name-only) invocations: those resolve to committed
+//     scripts the pre-commit linter already owns.
+//   - logs EVERY decision with a per-model histogram to
+//     _byan-output/tier-ledger.jsonl — the measurement basis for real token
+//     gains (no replay theatre).
+//
+// Escape hatch: `touch .byan-tier/off` disables gating (still ledger-logged as
+// escape-hatch, so misses stay auditable). Non-blocking on any internal error.
+//
+// CJS shell + ESM lib via dynamic import() (the leantime-fd-sync bridge). The
+// lib resolves relative to THIS file so tests can pass a bare tmp root for
+// sidecar/ledger state without needing the lib copied there.
+
+const fs = require('fs');
+const path = require('path');
+const { pathToFileURL } = require('url');
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const LIB_PATH = path.resolve(__dirname, '../../_byan/mcp/byan-mcp-server/lib/tier-script.js');
+
+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(''));
+  });
+}
+
+function allow() {
+  return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow' } };
+}
+
+function deny(reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
+function sidecarPath(root) {
+  return path.join(root, '.byan-tier', 'last-deny.json');
+}
+
+function readPriorDenyHash(root) {
+  try {
+    return JSON.parse(fs.readFileSync(sidecarPath(root), 'utf8')).hash || null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+function writePriorDenyHash(root, hash) {
+  try {
+    fs.mkdirSync(path.dirname(sidecarPath(root)), { recursive: true });
+    fs.writeFileSync(sidecarPath(root), JSON.stringify({ hash }));
+  } catch (_e) {
+    // best-effort: losing the deny memory only means one extra deny, never a trap
+  }
+}
+
+function clearPriorDeny(root) {
+  try {
+    fs.unlinkSync(sidecarPath(root));
+  } catch (_e) {
+    // already absent
+  }
+}
+
+function ledgerLog(root, entry) {
+  try {
+    const dir = path.join(root, '_byan-output');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(path.join(dir, 'tier-ledger.jsonl'), JSON.stringify(entry) + '\n');
+  } catch (_e) {
+    // the ledger is observability, never a blocker
+  }
+}
+
+// Per-model histogram: pinned tiers by value; 'inherit' = deep labelled leaves
+// plus unlabelled agent() calls (both run on the session model).
+function modelHistogram(analysis) {
+  const h = { haiku: 0, sonnet: 0, inherit: 0 };
+  for (const l of analysis.leaves) {
+    if (l.model === 'haiku') h.haiku += 1;
+    else if (l.model === 'sonnet') h.sonnet += 1;
+    else h.inherit += 1;
+  }
+  h.inherit += Math.max(0, analysis.agentCalls - analysis.leaves.length);
+  return h;
+}
+
+async function runGuard(payload, { root = ROOT } = {}) {
+  const toolName = payload.tool_name || payload.toolName || '';
+  if (toolName !== 'Workflow') return allow();
+  const input = payload.tool_input || payload.toolInput || {};
+
+  let src = null;
+  let source = null;
+  if (typeof input.script === 'string' && input.script.trim()) {
+    src = input.script;
+    source = 'inline';
+  } else if (typeof input.scriptPath === 'string' && input.scriptPath.trim()) {
+    source = 'scriptPath';
+    const p = path.isAbsolute(input.scriptPath) ? input.scriptPath : path.join(root, input.scriptPath);
+    try {
+      src = fs.readFileSync(p, 'utf8');
+    } catch (_e) {
+      // unreadable path: the Workflow tool will surface the real error itself
+      return allow();
+    }
+  } else {
+    // registry (name-only) invocation: resolves to a committed script the
+    // pre-commit linter already validated
+    return allow();
+  }
+
+  const lib = await import(pathToFileURL(LIB_PATH).href);
+  const analysis = lib.analyzeScript(src);
+  const scriptHash = lib.hashScript(src);
+  const escaped = fs.existsSync(path.join(root, '.byan-tier', 'off'));
+  const decision = lib.decideTierGate({
+    analysis,
+    escaped,
+    scriptHash,
+    priorDenyHash: readPriorDenyHash(root),
+  });
+
+  ledgerLog(root, {
+    ts: new Date().toISOString(),
+    source,
+    decision: decision.decision,
+    code: decision.code,
+    hash: scriptHash,
+    agentCalls: analysis.agentCalls,
+    leaves: analysis.leaves.length,
+    gaps: analysis.gaps.map((g) => g.label),
+    violations: analysis.violations.map((v) => v.label),
+    models: modelHistogram(analysis),
+    acknowledged: analysis.acknowledged,
+  });
+
+  if (decision.decision === 'deny') {
+    writePriorDenyHash(root, scriptHash);
+    return deny(decision.reason);
+  }
+  if (decision.code === 'unchanged-after-deny') clearPriorDeny(root);
+  return allow();
+}
+
+if (require.main === module) {
+  (async () => {
+    let out;
+    try {
+      const payload = JSON.parse((await readStdin()) || '{}');
+      out = await runGuard(payload);
+    } catch (_e) {
+      out = allow();
+    }
+    process.stdout.write(JSON.stringify(out));
+    process.exit(0);
+  })();
+}
+
+module.exports = { runGuard };

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

@@ -26,16 +26,24 @@ 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). 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).
+(tier vocabulary, leaf classifier, model map). Three tiers:
+
+- **cheap (`model: 'haiku'`)** — a pure EXPLORATION leaf (read/load/parse/detect).
+- **balanced (`model: 'sonnet'`)** — MECHANICAL verification, opt-in ONLY through
+  the `mech-` label prefix (`mech-validate-json`): a binary, judgment-free check
+  (JSON parses, schema matches, lint passes). Semantic/adversarial verification
+  is NOT mechanical and stays deep. The prefix is an authoring declaration the
+  linter holds the script to: a `mech-` leaf without `model: 'sonnet'` is a hard
+  violation (`mechanical-without-model` / `mechanical-below-tier`).
+- **deep (OMIT `opts.model`)** — implementation / verification / analysis leaves
+  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.
+- **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
+  (`modelRoutingViolations` + `mechanicalLabelViolations`). 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
@@ -43,6 +51,24 @@ The linter splits the two directions:
   consumed verbatim downstream. The human owns that per-leaf call. Forcing haiku
   on them would be the very downgrade the floor forbids.
 
+## Ad-hoc scripts — the tier gate hook
+
+The repo linter only sees committed files. An AD-HOC script (written inline for
+one run) crosses exactly one chokepoint before it executes: the Workflow tool
+invocation. `.claude/hooks/tier-script-guard.js` (PreToolUse, matcher `Workflow`)
+runs the same analysis there via `lib/tier-script.js` and DENIES ONCE when
+exploration/`mech-` leaves carry no tier — with the exact leaf list to fix. The
+`// BYAN-TIER: reviewed` comment marker acknowledges deliberate deep choices; an
+identical resubmission passes (deny-once by design); registry (name-only)
+invocations pass untouched. Every decision lands in
+`_byan-output/tier-ledger.jsonl` with a per-model histogram — the measurement
+basis for token gains. Escape hatch: `touch .byan-tier/off`.
+
+Authoring flow: 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. Standalone report:
+`node _byan/mcp/byan-mcp-server/bin/byan-tier-script.js <file> [--json]`.
+
 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.

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

@@ -42,6 +42,10 @@
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/strict-context-inject.js"
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/codex-autodelegate.js"
           }
         ]
       }
@@ -102,6 +106,15 @@
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/strict-scope-guard.js"
           }
         ]
+      },
+      {
+        "matcher": "Workflow",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tier-script-guard.js"
+          }
+        ]
       }
     ],
     "PostToolUse": [

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

@@ -64,9 +64,14 @@ Never call `byan_update_apply` without explicit user consent. That tool returns
     - **Score ≥ 40** → main-thread (heavy) or delegate to `byan-hermes-dispatch`
   - **Model tier** (WHICH model), from the task NATURE — not its size (`byan_dispatch` returns it as `model`, via native-tiers, the single source of truth) :
     - 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 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.
+    - 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.
+  - **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.
+    - **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.
 - **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/.claude/skills/byan-hermes-dispatch/SKILL.md

@@ -55,7 +55,9 @@ Call the `byan_dispatch` MCP tool with `{ task: <goal>, parallelizable: <bool>,
   - `main-thread` — do it inline, no delegation
   - `agent-subagent-worktree` — spawn Agent tool with isolation worktree
   - `mcp-worker` — spawn Agent tool, no worktree
-- **model** (WHICH model), from the task NATURE via native-tiers, not its size : `haiku` (exploration only) or `null` = deep (inherit the session model). Pass an explicit `nature` (`exploration`/`implementation`/`verification`/`analysis`) when you know it; protected natures stay off haiku.
+- **model** (WHICH model), from the task NATURE via native-tiers, not its size : `haiku` (exploration), `sonnet` (mechanical — explicit binary judgment-free checks only), or `null` = deep (inherit the session model). Pass an explicit `nature` (`exploration`/`mechanical`/`implementation`/`verification`/`analysis`) when you know it; protected natures stay off haiku/sonnet.
+
+**Batch mode (workflow authoring)** : before WRITING a workflow script, call `byan_dispatch` with `{ leaves: [{ label, nature? }, ...] }` — it returns the `opts.model` value per leaf from the same source of truth. Write `model:` only where it is non-null. The `tier-script-guard` PreToolUse hook gates every Workflow invocation against this contract (deny-once with the exact leaf list; acknowledge deliberate deep choices with the `// BYAN-TIER: reviewed` comment marker).
 
 ### 4. Spawn the work
 

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

@@ -36,6 +36,15 @@ 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.
 
+## 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:
+
+- **tests/coverage** — 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?
+- **doc-follows-code** — 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?
+- **scope-discovery** — 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?
+
 ## Hard claims
 
 Claims in security, performance, or compliance need LEVEL-1 sourcing

package/install/templates/.claude/workflows/sprint-planning.js

@@ -6,7 +6,7 @@ export const meta = {
     { title: 'STRUCTURE', detail: 'build the ordered development_status map: epic, its stories, its retrospective' },
     { title: 'DETECT', detail: 'intelligent per-story status detection, never downgrade an existing status' },
     { title: 'GENERATE', detail: 'write sprint-status.yaml with metadata as comments AND as parseable fields' },
-    { title: 'VALIDATE', detail: 'coverage + legal-status + YAML checks, then count totals and report' },
+    { title: 'VALIDATE', detail: 'coverage + legal-status + YAML checks, then count totals and report', model: 'sonnet' },
   ],
 }
 
@@ -236,7 +236,7 @@ const validation = await agent(
     `- validYaml: the file parses as YAML.\n` +
     `Count totals: epicCount, storyCount, epicsInProgress, storiesDone. ` +
     `passed = true only if ALL six checks hold; otherwise list specific failures.`,
-  { label: 'validate-and-report', phase: 'VALIDATE', schema: VALIDATE_SCHEMA }
+  { label: 'mech-validate-status', phase: 'VALIDATE', schema: VALIDATE_SCHEMA, model: 'sonnet' }
 )
 
 // Single top-level return — DATA only. The orchestrating skill presents this at

package/install/templates/.claude/workflows/testarch-trace.js

@@ -6,7 +6,7 @@ export const meta = {
     { title: 'DISCOVER_TESTS' },
     { title: 'MAP_CRITERIA' },
     { title: 'ANALYZE_GAPS' },
-    { title: 'GATE_DECISION' }
+    { title: 'GATE_DECISION', model: 'sonnet' }
   ]
 }
 
@@ -260,8 +260,9 @@ const gate = await agent(
     'Return the deterministic decision, the rationale string, and the gate criteria (p0 met?, overall status MET/PARTIAL/NOT MET).'
   ].join(' '),
   {
-    label: 'gate-decision',
+    label: 'mech-gate-decision',
     phase: 'GATE_DECISION',
+    model: 'sonnet',
     schema: {
       type: 'object',
       required: ['decision', 'rationale', 'gateCriteria'],

package/install/templates/.githooks/pre-commit

@@ -82,6 +82,24 @@ if [ -f "$TEMPLATE_SYNC" ]; then
   fi
 fi
 
+# Soul source drift gate — BYAN's active soul (_byan/agent/byan/{soul,tao}.md) is
+# mirrored into the shippable prefixed copies (byan-{soul,tao}.md) that the
+# installer copies to soul.md/tao.md at setup. This gate blocks a commit whose
+# shippable soul has drifted from the active one, so a fresh install ships a
+# current identity. soul-memory is out of scope (curated seed). Dev-repo tooling:
+# the bin is not shipped, so this gate no-ops in installed projects (the [ -f ]
+# guard below). Re-sync with the apply command, then restage.
+SOUL_SYNC="_byan/mcp/byan-mcp-server/bin/byan-sync-soul.js"
+if [ -f "$SOUL_SYNC" ]; then
+  if ! node "$SOUL_SYNC" --check --root "$(git rev-parse --show-toplevel)"; then
+    echo ""
+    echo "Commit blocked : the shippable soul has drifted from the active soul."
+    echo "Re-sync with 'node $SOUL_SYNC' then restage, or bypass with"
+    echo "'git commit --no-verify' (emergency only)."
+    exit 1
+  fi
+fi
+
 # Stub path drift gate — the installer generated platform stubs (.codex/prompts,
 # .github/agents, .claude/skills) over many versions; older generators emitted the
 # legacy _bmad/@bmad path layout while the agent sources are clean. This gate