claude-token-saver 3.0.0 → 3.2.0

package/src/harness.js

@@ -278,79 +278,58 @@ export function harnessPromote(ruleText, { root = findProjectRoot(), scope = 'pr
 }
 
 /**
- * harness pull — copy the user's GLOBAL ratchet rules (~/.claude/ratchet.md)
- * into the current project's .claude/ratchet.md, on demand. Opt-in by design:
- * install/init never auto-injects rules; this is the explicit "땡겨오기" verb.
+ * harness pull — register the CURATED ratchet rules bundled with this package
+ * (presets/ratchet-rules.md) into the user's ratchet, global by default.
  *
- * Rules are deduped by text (ignoring the leading YYYY-MM-DD stamp) so
- * repeated pulls are idempotent. With `includeBlock`, the global CLAUDE.md
- * harness block (including any user customizations) is also copied into the
- * project CLAUDE.md — replacing the project's block if one exists.
+ * Rationale: a project ratchet already inherits the global one (global is the
+ * upper layer of the hierarchy), so there is nothing to copy between the
+ * user's own scopes. What CAN'T reach the user any other way is the package
+ * author's field-tested rules — pull ships those, strictly opt-in:
+ * install/init never auto-injects anything.
  *
- * Returns { root, added, skippedRules, wrote, skipped }.
+ * Deduped by rule text (ignoring the YYYY-MM-DD stamp) — idempotent.
+ * Returns { path, scope, added, skippedRules, presets }.
  */
-export function harnessPull({ root = findProjectRoot(), includeBlock = false } = {}) {
-  const result = { root, added: [], skippedRules: 0, wrote: [], skipped: [] };
+export function harnessPull({ root = findProjectRoot(), scope = 'global' } = {}) {
+  const presets = presetRules();
+  const rmPath = resolveRatchetPath(scope, root);
+  const result = { path: rmPath, scope, added: [], skippedRules: 0, presets: presets.length };
   const stripDate = (t) => t.replace(/^\d{4}-\d{2}-\d{2}:\s*/, '').trim();
 
-  // 1) Ratchet rules: global → project, dedup by rule text.
-  const globalRules = harnessListRules({ scope: 'global' }).rules;
-  const projPath = ratchetMdPath(root);
-  let content = existsSync(projPath)
-    ? readFileSync(projPath, 'utf8')
+  let content = existsSync(rmPath)
+    ? readFileSync(rmPath, 'utf8')
     : harnessRatchetMdInitial();
   const have = new Set(
-    harnessListRules({ root, scope: 'project' }).rules.map((r) => stripDate(r.text)),
+    harnessListRules({ root, scope }).rules.map((r) => stripDate(r.text)),
   );
-  for (const g of globalRules) {
-    const key = stripDate(g.text);
-    if (have.has(key)) {
+  for (const rule of presets) {
+    if (have.has(rule)) {
       result.skippedRules += 1;
       continue;
     }
-    content = appendRatchetRule(content, key);
-    have.add(key);
-    result.added.push(key);
+    content = appendRatchetRule(content, rule);
+    have.add(rule);
+    result.added.push(rule);
   }
   if (result.added.length) {
-    mkdirSync(dirname(projPath), { recursive: true });
-    writeFileSync(projPath, content);
-    result.wrote.push(projPath);
+    mkdirSync(dirname(rmPath), { recursive: true });
+    writeFileSync(rmPath, content);
   }
+  return result;
+}
 
-  // 2) Harness block (opt-in): copy the global block as-is so user edits to
-  //    the global sections travel with it.
-  if (includeBlock) {
-    const gPath = globalClaudeMdPath();
-    const blockRe = new RegExp(
-      `${escapeRe(HARNESS_BLOCK_BEGIN)}[\\s\\S]*?${escapeRe(HARNESS_BLOCK_END)}\\n?`,
-      'm',
-    );
-    const gContent = existsSync(gPath) ? readFileSync(gPath, 'utf8') : '';
-    const m = gContent.match(blockRe);
-    if (!m) {
-      result.skipped.push(`${gPath} (no global harness block to pull)`);
-    } else {
-      const block = m[0];
-      const pPath = claudeMdPath(root);
-      if (existsSync(pPath)) {
-        const pc = readFileSync(pPath, 'utf8');
-        if (pc.includes(HARNESS_BLOCK_BEGIN)) {
-          writeFileSync(pPath, pc.replace(blockRe, block));
-          result.wrote.push(`${pPath} (harness block replaced with global copy)`);
-        } else {
-          const sep = pc.endsWith('\n') ? '\n' : '\n\n';
-          writeFileSync(pPath, pc + sep + block);
-          result.wrote.push(`${pPath} (harness block appended from global)`);
-        }
-      } else {
-        writeFileSync(pPath, block);
-        result.wrote.push(pPath);
-      }
-    }
+/** Parse the bundled preset rules (markdown bullets under presets/). */
+export function presetRules() {
+  try {
+    const path = join(dirname(new URL(import.meta.url).pathname), '..', 'presets', 'ratchet-rules.md');
+    return readFileSync(path, 'utf8')
+      .split('\n')
+      .filter((l) => /^\s*-\s+/.test(l))
+      .map((l) => l.replace(/^\s*-\s+/, '').trim())
+      .filter(Boolean);
+  } catch {
+    return [];
   }
-
-  return result;
 }
 
 /**
@@ -365,7 +344,8 @@ export function harnessListRules({ root = findProjectRoot(), scope = 'project' }
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
     // A "rule line" starts with "- " (markdown bullet). Header lines, blanks,
-    // and the "## Rules" anchor are ignored.
+    // and the "## Rules" anchor are ignored. (Model-fitting rules live in a
+    // separate tool-owned file, ratchet-model.md — never listed here.)
     if (/^\s*-\s+/.test(line)) {
       rules.push({ index: rules.length + 1, lineNo: i, text: line.replace(/^\s*-\s+/, '') });
     }

package/src/model-rules.js

@@ -0,0 +1,174 @@
+/**
+ * model-rules — the MODEL-FITTING ratchet registry.
+ *
+ * Model-fitting rules (tier-delegation rules promoted from route-scan) are
+ * managed SEPARATELY from user-authored ratchet rules, for two reasons the
+ * user set as requirements:
+ *   1. They must never tangle with hand-written rules — so they live in a
+ *      fully tool-owned FILE (ratchet-model.md) next to ratchet.md,
+ *      regenerated wholesale. A separate file (rather than a managed block
+ *      inside ratchet.md) keeps auto-refresh churn out of the user's file:
+ *      per-scan stat updates only ever touch ratchet-model.md, which can be
+ *      gitignored, and there are no block markers a hand edit could corrupt.
+ *   2. They must keep updating from subsequent logs — recurrence counts and
+ *      post-promotion error rates are refreshed on every route-scan, and a
+ *      rule whose delegated episodes start failing gets flagged for review
+ *      (rule-health, per docs/TIER_CRITERIA.md).
+ *
+ * Registry file (source of truth): <stateDir>/model-rules.json
+ *   { rules: [ { signature, tier, category, label, agent, scope,   // 'project'|'global'
+ *                targetRoot,           // project root path (project scope)
+ *                rule, example, count, errRate, promotedAt, lastSeen,
+ *                status } ] }          // 'active' | 'review'
+ *
+ * Rendered files (regenerated from the registry, never edited in place):
+ *   project scope → <root>/.claude/ratchet-model.md
+ *   global scope  → ~/.claude/ratchet-model.md
+ * The harness CLAUDE.md block points Claude at these files alongside
+ * ratchet.md.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+// Post-promotion delegated-category error rate above this flags the rule
+// for review (rule-health). Calibrated against local T0 avg error incidence.
+export const HEALTH_ERR_RATE = 0.2;
+
+function stateDir() {
+  if (process.platform === 'win32') {
+    return join(process.env.APPDATA || homedir(), 'claude-token-saver');
+  }
+  if (process.platform === 'darwin') {
+    return join(homedir(), 'Library', 'Application Support', 'claude-token-saver');
+  }
+  const xdg = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(xdg, 'claude-token-saver');
+}
+
+export function modelRulesPath() {
+  return join(stateDir(), 'model-rules.json');
+}
+
+export function loadModelRules() {
+  try {
+    const data = JSON.parse(readFileSync(modelRulesPath(), 'utf8'));
+    return Array.isArray(data.rules) ? data : { rules: [] };
+  } catch {
+    return { rules: [] };
+  }
+}
+
+export function saveModelRules(data) {
+  const dir = stateDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(modelRulesPath(), JSON.stringify(data, null, 2) + '\n');
+}
+
+/** Add (or re-activate) a promoted rule; returns the stored entry. */
+export function addModelRule(entry) {
+  const data = loadModelRules();
+  const existing = data.rules.find((r) => r.signature === entry.signature && r.scope === entry.scope);
+  if (existing) {
+    Object.assign(existing, entry, { status: 'active' });
+    saveModelRules(data);
+    return existing;
+  }
+  const stored = { status: 'active', errRate: 0, ...entry };
+  data.rules.push(stored);
+  saveModelRules(data);
+  return stored;
+}
+
+export function removeModelRule(index1) {
+  const data = loadModelRules();
+  if (index1 < 1 || index1 > data.rules.length) return null;
+  const [removed] = data.rules.splice(index1 - 1, 1);
+  saveModelRules(data);
+  return removed;
+}
+
+/** Render the full ratchet-model.md for one target (scope+root). */
+export function renderModelRatchet(rules) {
+  const lines = [
+    '# Model-Fitting Ratchet (claude-token-saver 자동 관리)',
+    '',
+    '로그 기반 티어 위임 룰. 이 파일은 route-scan이 매 스캔마다 통째로 재생성하므로',
+    '직접 수정하지 마세요 — 목록/제거: `claude-token-saver route-scan rules [rm <N>]`.',
+    '',
+    '## Rules',
+    '',
+  ];
+  for (const r of rules) {
+    const health = r.status === 'review'
+      ? ` ⚠ rule-health: 최근 위임 대상 에러율 ${Math.round((r.errRate || 0) * 100)}% — 조건을 좁히거나 제거 검토`
+      : '';
+    const stats = ` <!-- ×${r.count || 0}, err ${Math.round((r.errRate || 0) * 100)}%, seen ${r.lastSeen || r.promotedAt} -->`;
+    lines.push(`- ${r.rule}${health}${stats}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+export function modelRatchetPathFor(scope, targetRoot) {
+  return scope === 'global'
+    ? join(homedir(), '.claude', 'ratchet-model.md')
+    : join(targetRoot, '.claude', 'ratchet-model.md');
+}
+
+/**
+ * Regenerate ratchet-model.md for every target that carries model rules.
+ * A target whose rules are all gone gets its file removed (it's fully
+ * tool-owned, so deletion is safe).
+ */
+export function syncAllFiles({ previousPaths = [] } = {}) {
+  const data = loadModelRules();
+  const byPath = new Map();
+  for (const r of data.rules) {
+    const p = modelRatchetPathFor(r.scope, r.targetRoot);
+    if (!byPath.has(p)) byPath.set(p, []);
+    byPath.get(p).push(r);
+  }
+  const written = [];
+  for (const [p, rules] of byPath) {
+    try {
+      mkdirSync(dirname(p), { recursive: true });
+      writeFileSync(p, renderModelRatchet(rules));
+      written.push(p);
+    } catch { /* unwritable target — skip, registry stays authoritative */ }
+  }
+  for (const p of previousPaths) {
+    if (!byPath.has(p) && existsSync(p)) {
+      try { unlinkSync(p); } catch { /* leave stale file; regenerated next sync */ }
+    }
+  }
+  return written;
+}
+
+/**
+ * Continuous update from logs (route-scan calls this on every refresh):
+ * for each registered rule, recompute recurrence count and the error rate
+ * of episodes in its (tier-eligible) category — the rule-health signal.
+ *
+ * `episodeStats`: Map "category|project" → { count, errCount, epCount }
+ * where errCount/epCount measure post-promotion delegated-category episodes.
+ */
+export function refreshModelRules(episodeStats, { now } = {}) {
+  const data = loadModelRules();
+  let changed = false;
+  for (const r of data.rules) {
+    const s = episodeStats.get(`${r.category}|${r.project}`)
+      || (r.scope === 'global' ? episodeStats.get(`${r.category}|*`) : null);
+    if (!s) continue;
+    r.count = s.count;
+    r.errRate = s.epCount > 0 ? s.errCount / s.epCount : 0;
+    r.lastSeen = now || r.lastSeen;
+    r.status = r.errRate > HEALTH_ERR_RATE ? 'review' : 'active';
+    changed = true;
+  }
+  if (changed) {
+    saveModelRules(data);
+    syncAllFiles();
+  }
+  return data;
+}

package/src/route-scan.js

@@ -2,38 +2,74 @@
  * route-scan — detect recurring "easy" work running on expensive models and
  * propose model-delegation ratchet rules.
  *
- * Runs the frugon-style difficulty idea at the EPISODE level (one user
- * request = the consecutive API calls it triggered), because per-call scoring
- * saturates on Claude Code's large session contexts. An episode is easy when
- * the whole request finished in few calls with little generation — exactly
- * the work a haiku subagent could take.
+ * Difficulty is judged at the EPISODE level (one user request = the
+ * consecutive API calls it triggered), because per-call scoring saturates on
+ * Claude Code's large session contexts — prompt size carries no signal when
+ * every call ships a 100k+ cached prefix. An episode is easy when the whole
+ * request finished in few calls with little generation — exactly the work a
+ * haiku subagent could take.
  *
  * Fully local, zero token cost. Results are cached (24h) so the SessionStart
  * hook can read them without re-parsing a month of transcripts.
  *
- * Pipeline position (per design discussion): frugon/this scan is NOT a
- * real-time router — it is a session-boundary calibrator that feeds the
- * existing ratchet promote flow (`harness promote R<N> --project|--global`).
+ * Pipeline position (per design discussion): this scan is NOT a real-time
+ * router — it is a session-boundary calibrator that feeds the existing
+ * ratchet promote flow (`harness promote R<N> --project|--global`).
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { discoverSessionFiles } from './parser.js';
-import { collectSessionRecords } from './frugon-export.js';
+import { collectSessionRecords } from './session-records.js';
 
-// Episode is "easy" when the whole user request finished within these bounds.
-// Calibrated on real data (2026-07): 27% of episodes, 3-6% of tokens.
-export const EASY_MAX_CALLS = 6;
-export const EASY_MAX_OUT_TOKENS = 1500;
+// ── Tier bands (docs/TIER_CRITERIA.md §3) ────────────────────────────────
+// T2 (haiku): finished in few calls, tiny output, near-zero mutation, no
+//   errors. T1 (sonnet): moderate output/mutation, at most one tool error.
+// T0: everything else stays on the session model. Output-token thresholds
+// are calibrated per-user from their own 14-day distribution (fixed
+// thresholds drift with workload — RouteLLM's stated limitation), clamped
+// to sane ranges so a skewed window can't stretch them absurdly.
+export const T2_MAX_CALLS = 6;
+export const T2_MAX_MUTATING = 2;
+export const T2_OUT_CLAMP = [1000, 3000];   // default 1500 pre-calibration
+export const T1_MAX_MUTATING = 6;
+export const T1_MAX_ERRORS = 1;
+export const T1_OUT_CLAMP = [5000, 15000];  // default 8000 pre-calibration
+export const T0_MIN_ERRORS = 2;             // repeated tool errors = hard, by outcome
+export const T0_MIN_MUTATING = 7;
+// Episodes below this output size carry no delegable work (conversational
+// acks, feedback) — skip entirely.
+export const MIN_DELEGABLE_OUT = 100;
+// Escalation keywords: design/analysis judgement stays on the top tier.
+export const ESCALATE_RE = /설계|아키텍처|리팩토링|원인 분석|개선할|검토해보|비교|왜 |analyze|compare|evaluate|architect|refactor/i;
 // A pattern must recur this often before we nag about it.
 export const MIN_RECURRENCE = 3;
-// Cache is fresh for a day — the SessionStart hook never rescans inline.
-export const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
 
-// Category → recommended haiku subagent. First match wins; order matters
-// (translate before read: "번역해줘" also matches the read keywords).
+// ── Rescan gate (data-driven, not time-driven) ───────────────────────────
+// A scan over unchanged transcripts is deterministic — identical output —
+// so time alone is a bad trigger: it wastes scans on idle days and lags a
+// full day behind heavy ones. Instead we rescan when enough NEW transcript
+// data accumulated (~5MB ≈ 20-40 episodes on measured data — enough for a
+// pattern to newly cross MIN_RECURRENCE), with guardrails: a minimum
+// interval against session-churn thrash, a daily fallback so small trickles
+// still refresh rule-health, and a hard skip when nothing changed at all.
+export const RESCAN_MIN_INTERVAL_MS = 60 * 60 * 1000;      // never more than hourly
+export const RESCAN_BIG_DELTA_BYTES = 5 * 1024 * 1024;     // this much new data → rescan now
+export const RESCAN_MAX_AGE_MS = 24 * 60 * 60 * 1000;      // any new data + a day old → rescan
+
+// Category → recommended subagent. First match wins; order matters
+// (paste before everything: keywords inside pasted UI/log text would
+// otherwise mislabel the episode; translate before read: "번역해줘" also
+// matches the read keywords).
+const PASTE_MIN_LEN = 400;
 const CATEGORIES = [
+  {
+    id: 'paste',
+    label: '붙여넣은 화면·로그 질문',
+    agent: 'haiku-explore',
+    re: null, // matched by length, see categorize()
+  },
   {
     id: 'translate',
     label: '배치 번역·정형 텍스트 변환',
@@ -92,7 +128,8 @@ export function mungeProjectPath(p) {
 }
 
 function categorize(text) {
-  for (const c of CATEGORIES) if (c.re.test(text)) return c;
+  if (text.length >= PASTE_MIN_LEN) return CATEGORIES.find((c) => c.id === 'paste');
+  for (const c of CATEGORIES) if (c.re && c.re.test(text)) return c;
   return null;
 }
 
@@ -109,11 +146,14 @@ function toEpisodes(records) {
   for (const r of records) {
     const text = (r.userText || '').trim();
     if (!cur || cur.text !== text) {
-      cur = { text, calls: 0, out: 0, models: new Set(), cwd: '' };
+      cur = { text, calls: 0, out: 0, mutating: 0, errors: 0, delegated: 0, models: new Set(), cwd: '' };
       episodes.push(cur);
     }
     cur.calls += 1;
     cur.out += r.completion_tokens;
+    cur.mutating += r.mutatingToolCalls || 0;
+    cur.errors += r.toolErrors || 0;
+    cur.delegated += r.delegationCalls || 0;
     cur.models.add(r.model);
     if (!cur.cwd && r.cwd) cur.cwd = r.cwd;
   }
@@ -124,67 +164,139 @@ function isExpensiveModel(model) {
   return !/haiku/i.test(model);
 }
 
+const clamp = (v, [lo, hi]) => Math.min(hi, Math.max(lo, v));
+const percentile = (sorted, p) => sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))];
+
+/**
+ * Per-user output-token thresholds from this window's episode distribution.
+ * Falls back to mid-clamp defaults when the sample is too small to trust.
+ */
+export function calibrateThresholds(episodeOuts) {
+  if (episodeOuts.length < 100) return { t2Out: 1500, t1Out: 8000, calibrated: false };
+  const sorted = [...episodeOuts].sort((a, b) => a - b);
+  return {
+    t2Out: clamp(Math.max(percentile(sorted, 0.25), 1500), T2_OUT_CLAMP),
+    t1Out: clamp(percentile(sorted, 0.75), T1_OUT_CLAMP),
+    calibrated: true,
+  };
+}
+
+/**
+ * Tier classification (docs/TIER_CRITERIA.md §3). Returns 'T0'|'T1'|'T2',
+ * or null when the episode carries nothing delegable. Order matters: hard
+ * evidence (errors, heavy mutation, big output, judgement keywords) wins
+ * before any cheap-band check.
+ */
+export function tierOf(ep, category, th) {
+  if (ep.out < MIN_DELEGABLE_OUT) return null;
+  if (
+    ep.errors >= T0_MIN_ERRORS ||
+    ep.mutating >= T0_MIN_MUTATING ||
+    ep.out > th.t1Out ||
+    ESCALATE_RE.test(ep.text)
+  ) return 'T0';
+  if (!category || ep.delegated > 0) return 'T0';
+  if (ep.calls <= T2_MAX_CALLS && ep.out <= th.t2Out && ep.mutating <= T2_MAX_MUTATING && ep.errors === 0) return 'T2';
+  if (ep.out <= th.t1Out && ep.mutating <= T1_MAX_MUTATING && ep.errors <= T1_MAX_ERRORS) return 'T1';
+  return 'T0';
+}
+
 /**
  * Scan transcripts and build delegation candidates.
  * Returns the cache object (also written to disk).
  */
 export async function runRouteScan({ days = 14 } = {}) {
   const files = await discoverSessionFiles({ days });
-  const groups = new Map(); // "category|project" → aggregate
-  let totalEpisodes = 0;
-  let easyEpisodes = 0;
 
+  // Pass 1 — collect episodes (needed up front: thresholds are calibrated
+  // from the full window's output distribution before any tiering).
+  const all = []; // { ep, projectDir }
+  let dataBytes = 0; // window size snapshot — the rescan gate diffs against it
   for (const f of files) {
     let records;
     try {
-      // Raw counts are irrelevant here (we classify by output size), and
-      // content is required for categorization.
-      records = await collectSessionRecords(f.path, { cacheWeighted: false, includeContent: true });
+      dataBytes += statSync(f.path).size;
+      records = await collectSessionRecords(f.path, { includeContent: true });
     } catch {
       continue;
     }
     for (const ep of toEpisodes(records)) {
       if (!ep.text) continue;
-      totalEpisodes += 1;
-      const easy = ep.calls <= EASY_MAX_CALLS && ep.out <= EASY_MAX_OUT_TOKENS;
-      if (!easy) continue;
-      easyEpisodes += 1;
-      if (isSkippable(ep.text)) continue;
-      if (![...ep.models].some(isExpensiveModel)) continue; // already cheap
-      const cat = categorize(ep.text);
-      if (!cat) continue;
-      const key = `${cat.id}|${f.projectDir}`;
-      const g = groups.get(key) || {
-        category: cat.id,
-        label: cat.label,
-        agent: cat.agent,
-        project: f.projectDir,
-        projectPath: '',
-        count: 0,
-        models: new Set(),
-        example: '',
-      };
-      g.count += 1;
-      for (const m of ep.models) g.models.add(m);
-      if (!g.projectPath && ep.cwd) g.projectPath = ep.cwd;
-      if (!g.example || (ep.text.length < g.example.length && ep.text.length > 10)) {
-        g.example = ep.text.slice(0, 80).replace(/\s+/g, ' ');
+      all.push({ ep, projectDir: f.projectDir });
+    }
+  }
+  const totalEpisodes = all.length;
+  const thresholds = calibrateThresholds(all.map((x) => x.ep.out));
+
+  // Pass 2 — tier, group by tier×category×project, and accumulate the
+  // per-category outcome stats that keep promoted model rules fresh.
+  const groups = new Map(); // "tier|category|project" → aggregate
+  const episodeStats = new Map(); // "category|project" (+ "category|*") → outcome stats
+  let tieredEpisodes = 0;
+  const bumpStats = (key, ep) => {
+    const s = episodeStats.get(key) || { count: 0, errCount: 0, epCount: 0 };
+    s.count += 1;
+    s.epCount += 1;
+    if (ep.errors > 0) s.errCount += 1;
+    episodeStats.set(key, s);
+  };
+
+  for (const { ep, projectDir } of all) {
+    if (isSkippable(ep.text)) continue;
+    if (![...ep.models].some(isExpensiveModel)) continue; // already cheap
+    const cat = categorize(ep.text);
+    if (cat) {
+      // rule-health denominator: episodes that LOOK delegable by shape
+      // (tier judged with the error signal zeroed — using real errors here
+      // would be circular, since T2 requires errors=0 by definition). The
+      // numerator is those that still hit errors: exactly the "light-looking
+      // work in this category keeps failing" risk a delegation rule cares about.
+      const shapeTier = tierOf({ ...ep, errors: 0 }, cat, thresholds);
+      if (shapeTier === 'T1' || shapeTier === 'T2') {
+        bumpStats(`${cat.id}|${projectDir}`, ep);
+        bumpStats(`${cat.id}|*`, ep);
       }
-      groups.set(key, g);
     }
+    const tier = tierOf(ep, cat, thresholds);
+    if (tier !== 'T1' && tier !== 'T2') continue;
+    tieredEpisodes += 1;
+    const key = `${tier}|${cat.id}|${projectDir}`;
+    const g = groups.get(key) || {
+      tier,
+      category: cat.id,
+      label: cat.label,
+      agent: tier === 'T2' ? cat.agent : 'sonnet',
+      project: projectDir,
+      projectPath: '',
+      count: 0,
+      models: new Set(),
+      example: '',
+    };
+    g.count += 1;
+    for (const m of ep.models) g.models.add(m);
+    if (!g.projectPath && ep.cwd) g.projectPath = ep.cwd;
+    if (!g.example || (ep.text.length < g.example.length && ep.text.length > 10)) {
+      g.example = ep.text.slice(0, 80).replace(/\s+/g, ' ');
+    }
+    groups.set(key, g);
   }
 
   // Keep prior dismissed/promoted signatures across rescans.
   const prev = readRouteScan();
   const resolved = new Set(prev?.resolved || []);
 
+  const ruleText = (g) => g.tier === 'T2'
+    ? `"${g.label}" 유형의 단순 요청(예: "${g.example}")은 ${g.agent}(haiku) 서브에이전트로 위임한다`
+    : `"${g.label}" 유형의 중간 난도 요청(예: "${g.example}")은 model: sonnet 서브에이전트로 위임한다 (설계 판단·반복 에러 발생 시 메인 모델이 이어받음)`;
+
   const candidates = [...groups.values()]
     .filter((g) => g.count >= MIN_RECURRENCE)
     .sort((a, b) => b.count - a.count)
-    .slice(0, 5)
+    .slice(0, 8)
     .map((g, i) => ({
       id: i + 1,
-      signature: `${g.category}|${g.project}`,
+      signature: `${g.tier}|${g.category}|${g.project}`,
+      tier: g.tier,
       category: g.category,
       label: g.label,
       agent: g.agent,
@@ -200,7 +312,7 @@ export async function runRouteScan({ days = 14 } = {}) {
       // project already, so scope suggestion is per-candidate 'project' unless
       // the same category recurs across 2+ projects (then 'global').
       suggestedScope: 'project',
-      rule: `"${g.label}" 유형의 단순 요청(예: "${g.example}")은 ${g.agent}(haiku) 서브에이전트로 위임한다`,
+      rule: ruleText(g),
     }));
 
   // Same category appearing in 2+ projects → suggest global for each.
@@ -216,7 +328,10 @@ export async function runRouteScan({ days = 14 } = {}) {
     scannedAt: new Date().toISOString(),
     days,
     totalEpisodes,
-    easyEpisodes,
+    dataBytes,
+    // kept as `easyEpisodes` for statusline/back-compat; now counts T1+T2.
+    easyEpisodes: tieredEpisodes,
+    thresholds,
     candidates,
     resolved: [...resolved],
   };
@@ -227,6 +342,15 @@ export async function runRouteScan({ days = 14 } = {}) {
   } catch {
     // best-effort — scan results are still returned
   }
+
+  // Continuous update (user requirement): every rescan refreshes promoted
+  // model-fitting rules from the new window — recurrence counts, error
+  // rates, and rule-health flags — and rewrites their managed blocks.
+  try {
+    const { refreshModelRules } = await import('./model-rules.js');
+    refreshModelRules(episodeStats, { now: cache.scannedAt });
+  } catch { /* registry unwritable — scan result still valid */ }
+
   return cache;
 }
 
@@ -239,10 +363,34 @@ export function readRouteScan() {
   }
 }
 
-export function isCacheFresh(cache) {
-  if (!cache?.scannedAt) return false;
+/**
+ * Data-driven rescan gate (see constants above). Cheap: one stat() per
+ * transcript file (~32 files on measured data) — a few milliseconds.
+ */
+export async function shouldRescan(cache, { days = 14 } = {}) {
+  if (!cache?.scannedAt) return true;
   const ts = Date.parse(cache.scannedAt);
-  return Number.isFinite(ts) && Date.now() - ts < CACHE_TTL_MS;
+  if (!Number.isFinite(ts)) return true;
+  const age = Date.now() - ts;
+  if (age < RESCAN_MIN_INTERVAL_MS) return false;
+
+  let total = 0;
+  let anyNew = false;
+  try {
+    for (const f of await discoverSessionFiles({ days })) {
+      const s = statSync(f.path);
+      total += s.size;
+      if (s.mtimeMs > ts) anyNew = true;
+    }
+  } catch {
+    return age >= RESCAN_MAX_AGE_MS; // can't stat — degrade to daily
+  }
+  if (!anyNew) return false; // nothing changed → identical scan, skip forever
+  // Append-only transcripts: window growth ≈ new data. Files aging out of
+  // the window shrink the total, making this estimate conservative.
+  const newBytes = Math.max(0, total - (cache.dataBytes || 0));
+  if (newBytes >= RESCAN_BIG_DELTA_BYTES) return true;
+  return age >= RESCAN_MAX_AGE_MS;
 }
 
 /** Candidates not yet promoted/dismissed. */