claude-token-saver 3.0.0 → 3.2.0

package/README.en.md

@@ -82,7 +82,6 @@ Run these in your shell (inside Claude Code, the `/claude-token-saver` Skill is
 | `claude-token-saver handoff` | Back work up to `HANDOFF-*.md` before a cap blocks you |
 | `claude-token-saver mode [keywords...]` | Output config (`icon`/`text`, `en`/`ko`, `1h`–`30d` window, …) |
 | `claude-token-saver harness ...` | 🅷 Harness management (below) |
-| `claude-token-saver frugon` | Export sessions → [frugon](https://github.com/Rodiun/frugon)-compatible JSONL (model-routing savings analysis, below) |
 | `claude-token-saver route-scan` | Detect recurring easy work on expensive models → propose haiku-delegation ratchet rules (below) |
 | `claude-token-saver install` | Manually register Skill + statusline |
 
@@ -117,14 +116,13 @@ claude-token-saver harness init --global       # ~/.claude/CLAUDE.md — every p
 claude-token-saver harness check               # current score (global fallback honored)
 claude-token-saver harness promote <N> --project|--global   # warning #N → ratchet rule (scope required)
 claude-token-saver harness promote "<rule text>" --project|--global  # register your own hand-written rules the same way
-claude-token-saver harness pull                # pull your global ratchet rules into this project (dedupes)
-claude-token-saver harness pull --harness      # also pull the global harness block (5 sections)
+claude-token-saver harness pull                # register the package's curated ratchet rules into your global ratchet (opt-in, dedupes)
 claude-token-saver harness list / rm <N>       # view / delete rules (auto .bak)
 claude-token-saver harness off | on            # toggle the 🅷 chip
 ```
 
 - `promote` **requires** `--project`/`--global` in non-TTY contexts (scripts, LLM calls) — a scope choice is never silently made for the caller.
-- `install` / `init` never auto-inject rules into a project. When you want the rules you've accumulated globally in a new project, pull them explicitly with `harness pull` (idempotent — re-running adds nothing twice).
+- `pull` registers the **author-curated ratchet rules** bundled with the package (`presets/ratchet-rules.md` — only general-purpose rules promoted from real recurring mistakes) into your global ratchet (`~/.claude/ratchet.md`). `install`/`init` never auto-inject anything; `pull` is always opt-in and idempotent. Drop any rule you dislike with `harness rm`.
 - 🅷⚠ runtime warnings (`ratchet?` `no-evidence` `PEV-skip`) expire after 30 minutes, subdirectory sessions match their project correctly, and PEV-skip counts only mutating tools (Edit/Write/Bash) so read-only research sessions don't trip it (v2.16.0+).
 
 <details>
@@ -139,37 +137,39 @@ The whole point of the ratchet is **one-direction accumulation**. Deleting rules
 An auto `.bak` is kept, but **the session context that earned the rule its place is not recoverable.**
 </details>
 
-## 🔀 frugon integration — "which calls could a cheaper model handle?"
 
-claude-token-saver catches cache/context waste; [frugon](https://github.com/Rodiun/frugon) (a local LLM cost analyzer) covers **model routing** — finding calls that never needed your most expensive model. The `frugon` subcommand bridges the two:
+## 🔀 route-scan — "this recurring task could run on a cheaper tier"
 
-```bash
-claude-token-saver frugon               # last 30 days → ./frugon-export.jsonl
-claude-token-saver frugon --run         # export + run frugon analyze immediately
-claude-token-saver frugon --days 7 --project myproj --out logs.jsonl
-```
-
-- Converts `~/.claude/projects/` transcripts into the OpenAI-compatible JSONL frugon reads. **Analysis is fully local** — no logs or keys leave your machine (same principle frugon holds).
-- **Cache-weighted tokens (default):** frugon doesn't know about prompt caching, so raw physical tokens would overstate your spend ~10x. By default the export folds in Anthropic's cache multipliers (read 0.1x · 5m write 1.25x · 1h write 2x) so frugon's dollar figures match your real bill. Use `--raw-tokens` for physical counts.
-- Preserves the signals frugon's easy/hard router reads (prompt/completion tokens, conversation depth) plus the last user prompt and reply text for `--measure` quality sampling. Strip text with `--no-content`.
-- Install frugon with `pipx install frugon` (if models show as unpriced, run `frugon update`).
+Analyzes your session history at the **episode (user request) level**, classifies the work your expensive model (opus/fable) keeps doing into **tiers**, and proposes delegation rules. Fully local, zero token cost. Criteria design and evidence: [docs/TIER_CRITERIA.md](./docs/TIER_CRITERIA.md).
 
-## 🔀 route-scan — "this recurring task could run on haiku"
+- **T2 → haiku**: few calls, tiny output, near-zero mutation, no errors (lookups, pasted-screen Q&A, simple runs)
+- **T1 → sonnet**: moderate output, few mutations, ≤1 error (build pipelines, status checks)
+- **T0 stays**: repeated errors, heavy mutation, big output, design/analysis keywords — the session model keeps it
 
-The practical follow-through of the frugon integration. It applies frugon-style difficulty analysis at the **episode (user request) level** to your session history, finds easy work your expensive model (opus/fable) keeps doing, and proposes promoting it into a haiku-subagent delegation rule. Fully local, zero token cost.
+Signals: call count, output tokens, **mutating tool calls (Edit/Write/Bash)**, **tool errors**, and request text. Output thresholds are auto-calibrated from your own 14-day distribution (fixed constants drift with workload).
 
 ```bash
-claude-token-saver route-scan                    # scan (24h cache) + print candidates
-claude-token-saver harness promote R1 --project  # promote candidate R1 to a ratchet rule
+claude-token-saver route-scan                    # scan (24h cache) + tiered candidates
+claude-token-saver harness promote R1 --project  # promote candidate R1 to a model-fitting rule
 claude-token-saver route-scan dismiss 1          # not interested — won't resurface
+claude-token-saver route-scan rules              # list model-fitting rules (rm <N> to remove)
 ```
 
+### Model-fitting ratchet — a separate file, continuously refreshed
+
+Promoted delegation rules never mix with hand-written ratchet rules: they live in a **separate, fully tool-owned file** — `.claude/ratchet-model.md` per project, `~/.claude/ratchet-model.md` for global scope — regenerated wholesale on every scan, and they stay alive afterward:
+
+- **Auto-refresh**: every rescan recomputes recurrence counts and the category's error rate from fresh logs and rewrites the file. Your `ratchet.md` is never touched by stat churn, so repos that commit `.claude/` see no diff noise (`ratchet-model.md` is safe to gitignore — it's always regenerable from the registry).
+- **rule-health**: when the delegated category's error rate exceeds 20%, the rule gets a `⚠ rule-health` flag suggesting you narrow or remove it — the "define difficulty by outcome" principle applied to rule lifecycle.
+- Your rules are managed by `harness list/rm`; model-fitting rules by `route-scan rules [rm <N>]` — separate files, separate indexes.
+- The CLAUDE.md ratchet section planted by `harness init` references both files, so Claude applies them together (existing users: re-run `harness init` to refresh the block).
+
 How it works (session-boundary calibration, NOT a real-time router):
-1. `install` registers a SessionStart hook that injects the cached scan results as session context on startup and `/clear` (the scan itself refreshes in the background, once a day).
-2. When a recurring (≥3×) easy pattern exists, the statusline shows a `🅷⚠ route? R1` chip and Claude asks you whether to register it, and at which scope (`--project`/`--global`).
-3. Promoted rules accumulate in ratchet.md, so **from the next session on, the main model delegates that work type to a haiku subagent automatically**.
+1. `install` registers a SessionStart hook that injects the cached scan results as session context on startup and `/clear`. Rescans are **data-triggered, not time-triggered**: ~5MB of new transcripts since the last scan rescans immediately, a small trickle rescans daily, and no change means no rescan at all (an unchanged-input scan is deterministic). A 1-hour minimum-interval guard applies, and promoting a rule triggers one immediate refresh to establish its stat baseline.
+2. When a recurring (≥3×) pattern exists, the statusline shows a `🅷⚠ route? R1` chip and Claude asks you whether to register it, and at which scope (`--project`/`--global`).
+3. Promoted rules make **the main model delegate that work type to a haiku/sonnet subagent automatically from the next session on**.
 
-Recommended companion setup: create `model: haiku` subagents under `~/.claude/agents/` (e.g. haiku-explore / haiku-runner / haiku-translate) so the rules are immediately actionable.
+Recommended companion setup: create `model: haiku` subagents under `~/.claude/agents/` (e.g. haiku-explore / haiku-runner / haiku-translate) plus a `model: sonnet` general worker so the rules are immediately actionable.
 
 ## Spike issue codes
 
@@ -251,10 +251,22 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.2.0 (2026-07-13)
+- **Tier classification (T0/T1/T2)** — route-scan grows from a binary easy/other split into three tiers. New signals: mutating tool calls and tool errors; output thresholds auto-calibrate to the user's own distribution (clamped); a dedicated category for pasted screen/log Q&A; conversational episodes (<100 output tokens) excluded. Design and research evidence in `docs/TIER_CRITERIA.md`.
+- **Model-fitting ratchet separated** — promoted delegation rules live in their own file (`.claude/ratchet-model.md` / `~/.claude/ratchet-model.md`), file-level-separated from hand-written rules, managed via `route-scan rules [rm <N>]`; the harness CLAUDE.md block references both files.
+- **Log-driven auto-refresh + rule-health** — every rescan recomputes each registered rule's recurrence count and error rate (over delegation-shaped episodes) and rewrites the file. An error rate >20% flags the rule with `⚠ rule-health`, suggesting narrowing or removal.
+- **Data-triggered rescans** — the fixed 24h TTL is gone; new transcript volume triggers rescans (~5MB → immediately, a trickle → daily, no change → skip, 1h minimum interval, one immediate refresh after promote).
+
+### v3.1.0 (2026-07-13)
+- **frugon integration removed** — the `claude-token-saver frugon` JSONL-export subcommand is gone. An external analyzer's aggregate report can't be turned into ratchet rules (condition → action), so it never fed the delegation pipeline; 3.x instead invests in **first-party tier classification over session logs**. route-scan is unaffected (the shared parser moved to `src/session-records.js`).
+
+### v3.0.1 (2026-07-13)
+- **`harness pull` redefined** — v3.0.0's "copy global ratchet → project" was pointless (the global ratchet already applies to every project as the upper layer of the hierarchy) and is removed. `pull` now registers the **author-curated ratchet rules** bundled with the package (`presets/ratchet-rules.md`) into your global ratchet — six general-purpose rules promoted from real recurring mistakes; opt-in and idempotent.
+
 ### v3.0.0 (2026-07-13)
 - **Major bump** — with v2.19's frugon integration and v2.20's route-scan, the product's character shifted from "after-the-fact token monitor" to "a routing layer that pushes recurring easy work down to cheaper models", so this ships as a major. No breaking changes (every existing command and setting remains compatible).
 - **route-scan promote fix** — `harness promote R<N> --project` now writes the rule into the `.claude/ratchet.md` of the project the candidate was **detected in** (previously it landed in whatever directory the CLI ran from). The scan stores each candidate's real session path (`projectPath`); promoting a foreign-project candidate from a pre-3.0 cache without that field is refused with a pointer to `route-scan --refresh`.
-- **New `harness pull`** — explicitly pull your global ratchet rules into a project (`--harness` also pulls the global harness block). Dedupes by rule text, so re-running is idempotent. `install`/`init` still never auto-inject anything — pulling is always opt-in.
+- **New `harness pull`** — redefined in v3.0.1 (see above).
 
 ### v2.20.0 (2026-07-13)
 - **route-scan**: detect recurring easy work on expensive models → `🅷⚠ route? R<N>` chip + SessionStart hook context injection + `harness promote R<N> --project|--global` to promote haiku-delegation ratchet rules.

package/README.md

@@ -82,7 +82,6 @@ Claude 안에서 `/claude-token-saver` Skill을 실행하거나 칩 문구를
 | `claude-token-saver handoff` | 작업 상태를 `HANDOFF-*.md`로 백업 (캡 임박 시) |
 | `claude-token-saver mode [keywords...]` | 출력 설정 (`icon`/`text`, `ko`/`en`, `1h`~`30d` 윈도 등) |
 | `claude-token-saver harness ...` | 🅷 Harness 관리 (아래 참고) |
-| `claude-token-saver frugon` | 세션 기록 → [frugon](https://github.com/Rodiun/frugon) 호환 JSONL 내보내기 (모델 라우팅 절감 분석, 아래 참고) |
 | `claude-token-saver route-scan` | 상위 모델이 반복 처리한 easy 작업 감지 → haiku 위임 랫쳇 룰 제안 (아래 참고) |
 | `claude-token-saver install` | Skill·statusline 수동 등록 |
 
@@ -98,14 +97,13 @@ claude-token-saver harness init --global       # ~/.claude/CLAUDE.md — 모든
 claude-token-saver harness check               # 현재 점수 (글로벌 fallback 인정)
 claude-token-saver harness promote <N> --project|--global   # 경고 #N → ratchet 룰 (스코프 필수)
 claude-token-saver harness promote "<룰 텍스트>" --project|--global  # 내가 직접 정의한 룰도 같은 명령으로 등록
-claude-token-saver harness pull                # 글로벌 랫쳇 룰을 이 프로젝트로 가져오기 (중복 자동 스킵)
-claude-token-saver harness pull --harness      # 글로벌 하네스 블록(5개 섹션)까지 함께 가져오기
+claude-token-saver harness pull                # 패키지 동봉 큐레이션 룰 → 내 글로벌 랫쳇에 등록 (opt-in, 중복 스킵)
 claude-token-saver harness list / rm <N>       # 룰 조회 / 삭제 (자동 .bak)
 claude-token-saver harness off | on            # 🅷 표시 토글
 ```
 
 - `promote`는 non-TTY(스크립트·LLM 호출)에서 `--project`/`--global` 플래그가 **필수** — 스코프가 묻지 않고 결정되는 사고를 막기 위한 설계입니다.
-- 설치(`install`)나 `init`은 프로젝트에 룰을 자동 주입하지 않습니다. 글로벌에 쌓아둔 룰을 새 프로젝트에서 쓰고 싶을 때만 `harness pull`로 명시적으로 가져오세요 (재실행해도 중복 없음).
+- `pull`은 패키지에 동봉된 **제작자 큐레이션 랫쳇 룰**(`presets/ratchet-rules.md` — 실제 반복 사고에서 승격된 범용 룰만)을 내 글로벌 랫쳇(`~/.claude/ratchet.md`)에 등록합니다. 설치(`install`)나 `init`은 아무것도 자동 주입하지 않으며, `pull`은 항상 opt-in이고 재실행해도 중복이 없습니다(멱등). 마음에 안 드는 룰은 `harness rm`으로 제거하면 됩니다.
 - 🅷⚠ 런타임 경고(`ratchet?` `no-evidence` `PEV-skip`)는 30분 후 자동 만료되고, 하위 디렉터리 세션도 프로젝트에 올바르게 매칭됩니다. PEV-skip은 변경성 도구(Edit/Write/Bash)만 카운트해 읽기 위주 세션에서는 발동하지 않습니다 (v2.16.0+).
 
 <details>
@@ -120,37 +118,39 @@ ratchet의 가치는 **한 방향 누적**에 있습니다. 룰을 가볍게 지
 삭제 시 `.bak`이 남지만 **그 룰이 박힌 세션 컨텍스트(왜)는 복원되지 않습니다.**
 </details>
 
-## 🔀 frugon 연계 — "어떤 호출을 싼 모델로 내릴 수 있나"
 
-claude-token-saver가 캐시·컨텍스트 낭비를 잡는다면, [frugon](https://github.com/Rodiun/frugon)(로컬 LLM 비용 분석기)은 **모델 라우팅** 절감 — 굳이 비싼 모델이 필요 없는 호출 찾기 — 을 다룹니다. `frugon` 서브커맨드가 둘을 연결합니다:
+## 🔀 route-scan — "이 반복 작업, 더 싼 티어로 내려도 됩니다"
 
-```bash
-claude-token-saver frugon               # 최근 30일 세션 → ./frugon-export.jsonl
-claude-token-saver frugon --run         # 내보내기 + frugon analyze 바로 실행
-claude-token-saver frugon --days 7 --project myproj --out logs.jsonl
-```
-
-- `~/.claude/projects/`의 transcript를 frugon이 읽는 OpenAI 호환 JSONL로 변환합니다. **분석은 전부 로컬** — 로그도 키도 밖으로 나가지 않습니다 (frugon의 원칙과 동일).
-- **캐시 가중 토큰(기본):** frugon은 프롬프트 캐싱을 모르기 때문에 물리 토큰을 그대로 주면 비용이 ~10배 과대평가됩니다. 기본값은 캐시 read 0.1x · 5m write 1.25x · 1h write 2x를 접어 넣은 유효 토큰이라 frugon의 달러 견적이 실제 청구액과 일치합니다. 물리 토큰이 필요하면 `--raw-tokens`.
-- frugon의 easy/hard 분류가 쓰는 신호(프롬프트·응답 토큰, 대화 깊이)와 `--measure` 품질 검증에 쓰는 마지막 유저 프롬프트·응답 텍스트를 보존합니다. 텍스트를 빼고 싶으면 `--no-content`.
-- frugon 설치: `pipx install frugon` (모델이 unpriced로 나오면 `frugon update`).
+세션 기록을 **에피소드(사용자 요청) 단위**로 분석해 상위 모델(opus/fable)이 반복 처리해 온 작업을 **티어로 분류**하고, 위임 룰로 승격하도록 제안합니다. 전 과정 로컬, 토큰 비용 0. 기준 설계와 근거는 [docs/TIER_CRITERIA.md](./docs/TIER_CRITERIA.md) 참고.
 
-## 🔀 route-scan — "이 반복 작업, haiku로 내려도 됩니다"
+- **T2 → haiku**: 적은 호출·작은 출력·변경 거의 없음·에러 0으로 끝난 요청 (탐색·조회, 붙여넣은 화면 질문, 단순 실행 등)
+- **T1 → sonnet**: 중간 출력·변경 소수·에러 ≤1 (빌드 파이프라인, 상태 점검 등)
+- **T0 유지**: 에러 반복, 대량 변경, 큰 출력, 설계·분석 키워드 — 세션 모델이 계속 담당
 
-frugon 연계의 실전 버전입니다. frugon식 난이도 분석을 **에피소드(사용자 요청) 단위**로 세션 기록에 적용해, 상위 모델(opus/fable)이 반복 처리해 온 easy 작업을 찾아 haiku 서브에이전트 위임 룰로 승격하도록 제안합니다. 전 과정 로컬, 토큰 비용 0.
+판정 신호는 호출 수·출력 토큰·**변경성 도구 수(Edit/Write/Bash)**·**도구 에러 수**·요청 텍스트이고, 출력 임계값은 사용자 자신의 최근 14일 분포에서 자동 보정됩니다 (고정 상수는 워크로드가 바뀌면 어긋나기 때문).
 
 ```bash
-claude-token-saver route-scan                    # 스캔 (24h 캐시) + 후보 출력
-claude-token-saver harness promote R1 --project  # 후보 R1을 랫쳇 룰로 등록
+claude-token-saver route-scan                    # 스캔 (24h 캐시) + 티어별 후보 출력
+claude-token-saver harness promote R1 --project  # 후보 R1을 모델 피팅 룰로 등록
 claude-token-saver route-scan dismiss 1          # 관심 없으면 무시 (재스캔에도 안 뜸)
+claude-token-saver route-scan rules              # 등록된 모델 피팅 룰 목록 (rm <N>으로 제거)
 ```
 
+### 모델 피팅 랫쳇 — 사용자 룰과 파일부터 분리, 로그 기반 자동 갱신
+
+승격된 위임 룰은 손으로 쓴 랫쳇 룰과 섞이지 않도록 **별도 파일**에 저장됩니다 — 프로젝트는 `.claude/ratchet-model.md`, 글로벌은 `~/.claude/ratchet-model.md`. 이 파일은 전적으로 도구 소유라 매 스캔마다 통째로 재생성되며, 이후에도 살아 움직입니다:
+
+- **자동 갱신**: 매 스캔마다 반복 횟수·해당 유형의 에러율을 최신 로그로 다시 계산해 파일을 재작성합니다. 통계가 바뀌어도 사용자의 `ratchet.md`는 전혀 건드리지 않으므로, `.claude/`를 커밋하는 프로젝트에서도 diff 소음이 없습니다 (`ratchet-model.md`는 gitignore해도 무방 — 레지스트리에서 항상 재생성 가능).
+- **rule-health**: 위임 대상 유형의 에러율이 20%를 넘으면 룰에 `⚠ rule-health` 경고가 붙어 조건을 좁히거나 제거하라고 알립니다 — "결과(outcome)로 난이도를 정의"하는 원칙을 룰 수명 관리에 재적용한 것.
+- 사용자 룰은 `harness list/rm`, 모델 피팅 룰은 `route-scan rules [rm <N>]`로 각각 관리 — 서로의 파일도 인덱스도 침범하지 않습니다.
+- `harness init`이 심는 CLAUDE.md 랫쳇 섹션이 두 파일을 모두 참조하므로 Claude가 세션에서 함께 적용합니다 (기존 사용자는 `harness init` 재실행으로 블록 갱신).
+
 동작 구조 (실시간 라우팅이 아니라 **세션 경계 캘리브레이션**):
-1. `install` 시 SessionStart 훅이 등록되어, 새 세션 시작·`/clear` 때 캐시된 스캔 결과를 세션 컨텍스트로 주입합니다 (스캔 자체는 백그라운드에서 일 1회).
-2. 반복(≥3회) easy 패턴이 있으면 statusline에 `🅷⚠ route? R1` 칩이 뜨고, Claude가 등록 여부와 scope(`--project`/`--global`)를 물어봅니다.
-3. 등록된 룰은 ratchet.md에 쌓여 **다음 세션부터 메인 모델이 해당 유형을 haiku 서브에이전트로 자동 위임**합니다.
+1. `install` 시 SessionStart 훅이 등록되어, 새 세션 시작·`/clear` 때 캐시된 스캔 결과를 세션 컨텍스트로 주입합니다. 재스캔은 시간이 아니라 **데이터가 트리거**: 마지막 스캔 이후 새 transcript가 ~5MB 이상 쌓이면 즉시, 소량이면 하루 1회, 아무 변화가 없으면 아예 돌지 않습니다 (변화 없는 재스캔은 결과가 동일하므로). 최소 간격 1시간 가드 포함, 룰 등록(promote) 직후에는 통계 기준선 확보를 위해 즉시 1회.
+2. 반복(≥3회) 패턴이 있으면 statusline에 `🅷⚠ route? R1` 칩이 뜨고, Claude가 등록 여부와 scope(`--project`/`--global`)를 물어봅니다.
+3. 등록된 룰은 **다음 세션부터 메인 모델이 해당 유형을 haiku/sonnet 서브에이전트로 자동 위임**하게 합니다.
 
-권장 사전 준비: `~/.claude/agents/`에 `model: haiku` 서브에이전트(예: haiku-explore / haiku-runner / haiku-translate)를 만들어 두면 룰이 바로 실행 가능해집니다.
+권장 사전 준비: `~/.claude/agents/`에 `model: haiku` 서브에이전트(예: haiku-explore / haiku-runner / haiku-translate)와 `model: sonnet` 범용 서브에이전트를 만들어 두면 룰이 바로 실행 가능해집니다.
 
 ## 토큰 급증 원인 코드
 
@@ -208,10 +208,22 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.2.0 (2026-07-13)
+- **티어 분류 (T0/T1/T2)** — route-scan이 이분법(easy/그외)에서 3티어로 진화. 신호에 변경성 도구 수·도구 에러 수 추가, 출력 임계값은 사용자 분포 기반 자동 보정(클램프 포함), 붙여넣은 화면·로그 질문 전용 카테고리 신설, 대화성 응답(출력 <100토큰) 제외. 기준 설계·리서치 근거는 `docs/TIER_CRITERIA.md`.
+- **모델 피팅 랫쳇 분리** — 승격된 위임 룰은 별도 파일(`.claude/ratchet-model.md` / `~/.claude/ratchet-model.md`)에 저장돼 사용자 룰과 파일 단위로 분리. `route-scan rules [rm <N>]`로 관리하며, 하네스 CLAUDE.md 블록이 두 파일을 함께 참조.
+- **로그 기반 자동 갱신 + rule-health** — 매 스캔마다 등록 룰의 반복 횟수·에러율(위임 적격 모양의 에피소드 기준)을 재계산해 파일을 재작성. 에러율 >20%면 `⚠ rule-health` 플래그로 조건 좁히기/제거를 제안.
+- **데이터 트리거 재스캔** — 고정 24h TTL을 폐기하고 신규 transcript 양이 재스캔을 트리거 (~5MB 즉시 / 소량 일 1회 / 무변화 스킵 / 최소 간격 1h / promote 직후 즉시 1회).
+
+### v3.1.0 (2026-07-13)
+- **frugon 연계 제거** — `claude-token-saver frugon` 서브커맨드(JSONL 내보내기)를 삭제했습니다. 외부 분석기의 집계 리포트는 랫쳇 룰(조건→행동)로 변환할 수 없어 위임 파이프라인에 기여하지 못했고, 3.x의 방향은 **세션 로그 기반 티어 분류를 자체적으로 탄탄히** 가져가는 것입니다. route-scan은 영향 없이 그대로 동작합니다 (공용 파서는 `src/session-records.js`로 분리).
+
+### v3.0.1 (2026-07-13)
+- **`harness pull` 재정의** — v3.0.0의 "글로벌 랫쳇 → 프로젝트 복사"는 글로벌 랫쳇이 이미 프로젝트의 상위 계층으로 항상 적용되므로 무의미해 제거. `pull`은 이제 패키지에 동봉된 **제작자 큐레이션 랫쳇 룰**(`presets/ratchet-rules.md`)을 사용자의 글로벌 랫쳇에 등록합니다 — 실제 반복 사고에서 승격된 범용 룰 6종, opt-in·멱등.
+
 ### v3.0.0 (2026-07-13)
 - **메이저 승격** — v2.19 frugon 연계 + v2.20 route-scan으로 "사후 토큰 모니터링 도구"에서 "반복 easy 작업을 싼 모델로 내려보내는 라우팅 계층"으로 제품 성격이 바뀌어 메이저 버전을 올립니다. Breaking change는 없습니다 (기존 명령·설정 전부 호환).
 - **route-scan promote 교정** — `harness promote R<N> --project`가 이제 후보가 **감지된 프로젝트**의 `.claude/ratchet.md`에 룰을 기록합니다 (이전에는 CLI를 실행한 디렉터리에 기록되는 버그). 스캔이 후보에 실제 세션 경로(`projectPath`)를 저장하며, 이 필드가 없는 구버전 캐시에서 다른 프로젝트 후보를 승격하려 하면 `route-scan --refresh`를 안내하고 중단합니다.
-- **`harness pull` 신설** — 글로벌 랫쳇 룰을 프로젝트로 명시적으로 가져옵니다 (`--harness`로 글로벌 하네스 블록까지). 룰 텍스트 기준 중복 자동 스킵이라 재실행해도 안전(멱등). 설치·init은 계속 아무것도 자동 주입하지 않습니다 — 가져오기는 항상 opt-in.
+- **`harness pull` 신설** — v3.0.1에서 재정의됨 (위 참고).
 
 ### v2.20.0 (2026-07-13)
 - **route-scan**: 상위 모델이 반복 처리한 easy 작업 감지 → `🅷⚠ route? R<N>` 칩 + SessionStart 훅 컨텍스트 주입 + `harness promote R<N> --project|--global`로 haiku 위임 랫쳇 룰 승격.

package/bin/cli.js

@@ -10,8 +10,6 @@
  *   npx claude-token-saver --format csv       # CSV output
  *   npx claude-token-saver --project myproj   # filter by project
  *   npx claude-token-saver route-scan         # detect recurring easy work → haiku-delegation candidates
- *   npx claude-token-saver frugon             # export transcripts → frugon JSONL (model-routing analysis)
- *   npx claude-token-saver frugon --run       # export + run `frugon analyze`
  *   npx claude-token-saver --install-hook     # install PostToolUse hook
  *   npx claude-token-saver --uninstall-hook   # remove hook
  *   npx claude-token-saver --hook-run         # internal: called by hook
@@ -480,6 +478,37 @@ async function main() {
     const { userLanguage } = await import('../src/config.js');
     const lang = userLanguage();
 
+    // route-scan rules [rm <N>] — the model-fitting rule registry (rules
+    // promoted from candidates; auto-refreshed from logs on every rescan).
+    if (args[1] === 'rules') {
+      const mr = await import('../src/model-rules.js');
+      if (args[2] === 'rm') {
+        const n = parseInt(args[3], 10);
+        const removed = Number.isFinite(n) ? mr.removeModelRule(n) : null;
+        if (!removed) {
+          console.error('Usage: claude-token-saver route-scan rules rm <N>   # N from `route-scan rules`');
+          process.exit(1);
+        }
+        // A target whose last rule was removed gets its (tool-owned) file deleted.
+        mr.syncAllFiles({ previousPaths: [mr.modelRatchetPathFor(removed.scope, removed.targetRoot)] });
+        console.log(`Removed model-fitting rule #${n}: ${removed.rule}`);
+        return;
+      }
+      const { rules } = mr.loadModelRules();
+      if (rules.length === 0) {
+        console.log(lang === 'ko' ? '등록된 모델 피팅 룰 없음.' : 'No model-fitting rules registered.');
+        return;
+      }
+      console.log(lang === 'ko' ? '📐 모델 피팅 룰 (로그 기반 자동 갱신):' : '📐 Model-fitting rules (auto-refreshed from logs):');
+      rules.forEach((r, i) => {
+        const health = r.status === 'review' ? '  ⚠ rule-health' : '';
+        console.log(`  #${i + 1} [${r.tier}|${r.scope}] ×${r.count || 0} err ${Math.round((r.errRate || 0) * 100)}%${health}`);
+        console.log(`      ${r.rule}`);
+      });
+      console.log('\n제거: claude-token-saver route-scan rules rm <N>');
+      return;
+    }
+
     if (args[1] === 'dismiss') {
       const n = parseInt(args[2], 10);
       if (!Number.isFinite(n)) {
@@ -502,7 +531,7 @@ async function main() {
     // prints delegation-candidate context for the new session.
     if (hasFlag('--hook')) {
       let cache = rs.readRouteScan();
-      if (!rs.isCacheFresh(cache)) {
+      if (await rs.shouldRescan(cache)) {
         try {
           const { spawn } = await import('node:child_process');
           spawn(process.execPath, [process.argv[1], 'route-scan', '--refresh', '--quiet'],
@@ -512,9 +541,10 @@ async function main() {
       const open = rs.openCandidates(cache);
       if (open.length === 0) return; // silent — nothing to inject
       const lines = [];
-      lines.push(`[claude-token-saver route-scan] 최근 ${cache.days}일 세션에서 상위 모델(opus/fable)이 처리한 반복 easy 작업이 감지되었습니다:`);
+      lines.push(`[claude-token-saver route-scan] 최근 ${cache.days}일 세션에서 상위 모델(opus/fable)이 처리한 위임 가능 반복 작업이 감지되었습니다:`);
       for (const c of open) {
-        lines.push(`  R${c.id} (×${c.count}, ${c.project}): ${c.label} → ${c.agent} 위임 권장 (scope 제안: ${c.suggestedScope})`);
+        const tierNote = c.tier === 'T1' ? 'sonnet 위임(중간 난도)' : `${c.agent} 위임(경량)`;
+        lines.push(`  R${c.id} [${c.tier || 'T2'}] (×${c.count}, ${c.project}): ${c.label} → ${tierNote} 권장 (scope 제안: ${c.suggestedScope})`);
         lines.push(`      예시: "${c.example}"`);
       }
       lines.push('이 패턴을 랫쳇 룰로 등록하면 다음 세션부터 자동 위임됩니다. 적절한 시점에 사용자에게 등록 여부와 scope를 물어본 뒤 실행하세요:');
@@ -526,7 +556,7 @@ async function main() {
 
     const days = parseFloat(getArg('--days') || '14');
     let cache = rs.readRouteScan();
-    if (hasFlag('--refresh') || !rs.isCacheFresh(cache) || (cache && cache.days !== days)) {
+    if (hasFlag('--refresh') || (cache && cache.days !== days) || await rs.shouldRescan(cache, { days })) {
       cache = await rs.runRouteScan({ days });
     }
     if (hasFlag('--quiet')) return;
@@ -547,7 +577,7 @@ async function main() {
     }
     console.log(lang === 'ko' ? '\n위임 후보:' : '\nDelegation candidates:');
     for (const c of open) {
-      console.log(`  R${c.id}  ×${c.count}  ${c.label} → ${c.agent}  [${c.project}] (scope 제안: ${c.suggestedScope})`);
+      console.log(`  R${c.id}  [${c.tier || 'T2'}] ×${c.count}  ${c.label} → ${c.agent}  [${c.project}] (scope 제안: ${c.suggestedScope})`);
       console.log(`       예시: "${c.example}"`);
       console.log(`       룰: ${c.rule}`);
     }
@@ -558,81 +588,12 @@ async function main() {
     return;
   }
 
-  // Subcommand: frugon — export Claude Code transcripts to the JSONL format
-  // frugon (local LLM cost analyzer, github.com/Rodiun/frugon) analyzes, so
-  // users can see which calls could route to a cheaper model.
-  //   claude-token-saver frugon                      # export last 30 days → ./frugon-export.jsonl
-  //   claude-token-saver frugon --days 7             # narrower window
-  //   claude-token-saver frugon --project myproj     # filter by project dir substring
-  //   claude-token-saver frugon --out PATH           # custom output path
-  //   claude-token-saver frugon --raw-tokens         # physical token counts (no cache weighting)
-  //   claude-token-saver frugon --no-content         # strip prompt/reply text (counts only)
-  //   claude-token-saver frugon --run                # run `frugon analyze` on the export
-  if (args[0] === 'frugon') {
-    const { exportFrugonLogs } = await import('../src/frugon-export.js');
-    const { userLanguage } = await import('../src/config.js');
-    const lang = userLanguage();
-    const days = parseFloat(getArg('--days') || '30');
-    const outPath = getArg('--out') || 'frugon-export.jsonl';
-    const cacheWeighted = !hasFlag('--raw-tokens');
-    const includeContent = !hasFlag('--no-content');
-    const res = await exportFrugonLogs({
-      days,
-      projectFilter: getArg('--project') || undefined,
-      outPath,
-      cacheWeighted,
-      includeContent,
-    });
-    if (res.records === 0) {
-      console.log(lang === 'ko'
-        ? `최근 ${days}일 내 세션 기록이 없습니다 (~/.claude/projects).`
-        : `No session records in the last ${days} days (~/.claude/projects).`);
-      return;
-    }
-    console.log(lang === 'ko'
-      ? `frugon 로그 내보내기 완료: ${res.outPath}`
-      : `frugon log export complete: ${res.outPath}`);
-    console.log(`  ${res.records} calls / ${res.sessions} sessions / last ${days}d`);
-    const byModel = Object.entries(res.models).sort((a, b) => b[1] - a[1]);
-    for (const [model, count] of byModel) console.log(`    ${model}: ${count}`);
-    console.log(cacheWeighted
-      ? (lang === 'ko'
-        ? '  prompt_tokens는 캐시 가중치 적용값 (read 0.1x, 5m write 1.25x, 1h write 2x) — frugon 비용이 실제 청구액과 일치. 해제: --raw-tokens'
-        : '  prompt_tokens are cache-weighted (read 0.1x, 5m write 1.25x, 1h write 2x) so frugon costs match your real bill. Disable: --raw-tokens')
-      : (lang === 'ko'
-        ? '  prompt_tokens는 물리 토큰 수 (캐시 가중치 없음 — frugon 비용이 실제보다 크게 나옴)'
-        : '  prompt_tokens are raw physical counts (no cache weighting — frugon will overstate cost)'));
-    if (hasFlag('--run')) {
-      const { spawnSync } = await import('node:child_process');
-      console.log('');
-      const run = spawnSync('frugon', ['analyze', res.outPath], { stdio: 'inherit' });
-      if (run.error && run.error.code === 'ENOENT') {
-        console.error(lang === 'ko'
-          ? 'frugon이 PATH에 없습니다. 설치: pipx install frugon  (또는 pip install frugon)'
-          : 'frugon not found on PATH. Install: pipx install frugon  (or pip install frugon)');
-        process.exit(1);
-      }
-      if (typeof run.status === 'number' && run.status !== 0) process.exit(run.status);
-      return;
-    }
-    console.log('');
-    console.log(lang === 'ko' ? '다음 단계:' : 'Next step:');
-    console.log(`  frugon analyze ${res.outPath}`);
-    console.log(lang === 'ko'
-      ? '  (frugon 미설치 시: pipx install frugon — 분석은 전부 로컬에서 실행됩니다)'
-      : '  (if frugon is not installed: pipx install frugon — analysis runs fully local)');
-    console.log(lang === 'ko'
-      ? '  (unpriced 모델이 나오면: frugon update 로 가격표를 갱신하세요)'
-      : '  (if models show as unpriced: run `frugon update` to refresh the pricing table)');
-    return;
-  }
-
   // Subcommand: harness — manage the project's CLAUDE.md harness rules.
   //   claude-token-saver harness init       # write CLAUDE.md (5 sections) + ratchet.md
   //   claude-token-saver harness uninit     # remove harness block from CLAUDE.md (backup kept)
   //   claude-token-saver harness check      # show 🅷 N/5 + which sections are missing
   //   claude-token-saver harness promote "<rule>"  # append a rule to ratchet.md
-  //   claude-token-saver harness pull [--harness]   # copy global ratchet rules (+block) into this project
+  //   claude-token-saver harness pull [--global|--project]  # register the package's curated preset rules (default global)
   //   claude-token-saver harness off | on   # toggle the statusline 🅷 segment
   if (args[0] === 'harness') {
     const sub = args[1];
@@ -792,31 +753,63 @@ async function main() {
           process.exit(1);
         }
       }
-      // Route candidates were detected in a specific project's sessions — a
-      // --project rule must land in THAT project's ratchet.md, not the cwd's.
-      // The candidate carries the real session cwd (projectPath); older cached
-      // scans predate that field, so fall back to verifying the cwd matches.
-      let promoteRoot;
-      if (routeCandidate && scope === 'project') {
+      // Route candidates become MODEL-FITTING rules: they live in a
+      // tool-managed block (separate from user-authored ratchet rules) and
+      // keep updating from subsequent logs — recurrence counts, error rates,
+      // rule-health — on every rescan.
+      if (routeCandidate) {
         const rs = await import('../src/route-scan.js');
-        if (routeCandidate.projectPath) {
-          promoteRoot = findProjectRoot(routeCandidate.projectPath);
-        } else if (rs.mungeProjectPath(findProjectRoot()) !== routeCandidate.project) {
-          console.error(`Route candidate R${routeCandidateId} was detected in another project (${routeCandidate.project}),`);
-          console.error('but this cached scan predates project-path tracking.');
-          console.error('Re-scan to capture it, then promote again:');
-          console.error('  claude-token-saver route-scan --refresh');
-          process.exit(1);
+        const mr = await import('../src/model-rules.js');
+        // A --project rule must land in THE project the pattern was detected
+        // in, not the cwd's. Old caches without projectPath: verify cwd match.
+        let targetRoot = null;
+        if (scope === 'project') {
+          if (routeCandidate.projectPath) {
+            targetRoot = findProjectRoot(routeCandidate.projectPath);
+          } else if (rs.mungeProjectPath(findProjectRoot()) === routeCandidate.project) {
+            targetRoot = findProjectRoot();
+          } else {
+            console.error(`Route candidate R${routeCandidateId} was detected in another project (${routeCandidate.project}),`);
+            console.error('but this cached scan predates project-path tracking.');
+            console.error('Re-scan to capture it, then promote again:');
+            console.error('  claude-token-saver route-scan --refresh');
+            process.exit(1);
+          }
         }
+        const entry = mr.addModelRule({
+          signature: routeCandidate.signature,
+          tier: routeCandidate.tier || 'T2',
+          category: routeCandidate.category,
+          label: routeCandidate.label,
+          agent: routeCandidate.agent,
+          scope,
+          targetRoot,
+          project: routeCandidate.project,
+          rule: routeCandidate.rule,
+          example: routeCandidate.example,
+          count: routeCandidate.count,
+          promotedAt: new Date().toISOString().slice(0, 10),
+          lastSeen: new Date().toISOString().slice(0, 10),
+        });
+        const written = mr.syncAllFiles();
+        rs.resolveCandidate(routeCandidateId);
+        console.log(`Model-fitting rule registered [${scope}${targetRoot ? ` → ${targetRoot}` : ''}] (tier ${entry.tier}):`);
+        console.log(`  - ${entry.rule}`);
+        for (const p of written) console.log(`  ratchet-model.md updated: ${p}`);
+        console.log('(route candidate R' + routeCandidateId + ' resolved — 다음 세션부터 자동 위임, 이후 스캔마다 로그 기반 갱신됩니다)');
+        console.log('룰 목록/제거: claude-token-saver route-scan rules [rm <N>]');
+        // Event-triggered refresh: establish the new rule's stat baseline
+        // right away instead of waiting for the next data-gated rescan.
+        try {
+          const { spawn } = await import('node:child_process');
+          spawn(process.execPath, [process.argv[1], 'route-scan', '--refresh', '--quiet'],
+            { detached: true, stdio: 'ignore' }).unref();
+        } catch { /* baseline arrives on the next gated rescan instead */ }
+        return;
       }
-      const r = harnessPromote(rule, promoteRoot ? { scope, root: promoteRoot } : { scope });
+      const r = harnessPromote(rule, { scope });
       console.log(`Appended to ${r.path} [${r.scope}]:`);
       console.log(`  - ${rule}`);
-      if (routeCandidateId !== null) {
-        const rs = await import('../src/route-scan.js');
-        rs.resolveCandidate(routeCandidateId);
-        console.log(`(route candidate R${routeCandidateId} resolved — 다음 세션부터 자동 위임 룰로 적용됩니다)`);
-      }
       if (/^\d+$/.test(raw)) {
         console.log('\n👉 ratchet.md를 열어 TODO 부분을 실제 룰로 다듬어주세요.');
       }
@@ -870,22 +863,21 @@ async function main() {
     }
 
     if (sub === 'pull') {
-      // Pull the user's GLOBAL ratchet rules (and optionally the global
-      // harness block) into this project. Explicitly opt-in — install/init
-      // never auto-injects rules into a project.
-      const includeBlock = args.includes('--harness');
-      const r = harnessPull({ includeBlock });
-      console.log(`Pull global → project (${r.root})`);
+      // Register the package's curated preset rules (presets/ratchet-rules.md)
+      // into the user's ratchet — global by default (they're tool/environment
+      // rules, and a project ratchet inherits global anyway). Strictly opt-in:
+      // install/init never auto-injects rules.
+      const scope = parseHarnessScope(args.slice(2), 'global');
+      const r = harnessPull({ scope });
+      console.log(`Curated preset rules → ${r.path} [${r.scope}]`);
       if (r.added.length) {
-        console.log(`✅ ${r.added.length} rule(s) pulled into .claude/ratchet.md:`);
+        console.log(`✅ ${r.added.length}/${r.presets} rule(s) registered:`);
         for (const t of r.added) console.log(`  - ${t}`);
       } else {
-        console.log('No new rules to pull.');
+        console.log(`No new rules — all ${r.presets} presets already registered.`);
       }
-      if (r.skippedRules) console.log(`   (${r.skippedRules} already present — skipped)`);
-      for (const f of r.wrote.filter((w) => w.includes('CLAUDE.md'))) console.log(`✅ ${f}`);
-      for (const f of r.skipped) console.log(`   skip: ${f}`);
-      if (!includeBlock) console.log('\n글로벌 하네스 블록(CLAUDE.md 5개 섹션)까지 가져오려면: claude-token-saver harness pull --harness');
+      if (r.skippedRules && r.added.length) console.log(`   (${r.skippedRules} already present — skipped)`);
+      console.log('\n필요 없는 룰은 언제든: claude-token-saver harness list / rm <N>');
       return;
     }
 
@@ -952,7 +944,7 @@ async function main() {
     }
 
     console.error(`Unknown harness subcommand: ${sub}`);
-    console.error('Usage: claude-token-saver harness [check|init|uninit [--purge-ratchet]|promote "<rule>"|pull [--harness]|list|rm <N>|off|on]');
+    console.error('Usage: claude-token-saver harness [check|init|uninit [--purge-ratchet]|promote "<rule>"|pull [--global|--project]|list|rm <N>|off|on]');
     process.exit(1);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Save tokens on Claude Code — spike diagnosis, 1M-context detection, TTL countdown, statusline. (formerly claude-cache-monitor)",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
   "files": [
     "bin/",
     "src/",
+    "presets/",
     "examples/",
     "README.md",
     "README.en.md"

package/presets/ratchet-rules.md

@@ -0,0 +1,16 @@
+# claude-token-saver 추천 Ratchet 룰 (curated presets)
+
+이 파일은 패키지에 동봉되는 제작자 큐레이션 랫쳇 룰입니다.
+`claude-token-saver harness pull`을 실행하면 아래 룰이 사용자의
+글로벌 랫쳇(`~/.claude/ratchet.md`)에 등록됩니다 (opt-in, 중복 자동 스킵).
+
+실제 반복 실수에서 승격된 룰만 담습니다 — 이론이 아니라 사고 이력.
+
+## Rules
+
+- 웹 fetch/search에서 robots·UA 차단('unable to fetch' 등)이 발생하면 → curl에 브라우저 UA(Mozilla/5.0 ... Chrome/...) 헤더를 붙여 재시도. reddit 등은 .json 엔드포인트 + UA 조합으로 접근 가능
+- ratchet 룰 promote 호출 직전 사용자에게 scope(project/global)를 먼저 묻는다 — Bash 환경은 non-TTY라 CLI readline 프롬프트가 안 뜨므로, 호출자(LLM)가 대신 묻고 --project/--global 플래그를 명시해 실행
+- 자동화 도구가 grep·정규식으로 찾는 마커 텍스트(헤더·앵커·키워드 라인)는 리팩터링·압축·수정 금지 — 정확 매칭 검출은 한 글자만 바뀌어도 깨짐
+- 자동화 설계에서 vision/screenshot 루프가 보이면 → 호출 가능한 함수·API·MCP tool부터 찾는다. 통제 가능한 내부 도구는 무조건 API, 통제 불가 외부 SaaS만 vision 차선책. 인터페이스를 바꾼 뒤에 모델을 내린다 — 거꾸로 가면 토큰 폭발
+- 입력 데이터(ground-truth) 변경 시 그에 의존하는 모든 파생 자산을 끝까지 재생성한다 — 중간 단계를 생략하면 stale 산출물이 새 입력 위에 얹혀 결과가 깨짐
+- 탐색·조회·상태 확인·명령 실행 같은 단순 요청은 haiku 서브에이전트(haiku-explore·haiku-runner 등)로 위임해 상위 모델 토큰을 아낀다

package/src/harness-templates.js

@@ -37,6 +37,10 @@ ${HARNESS_SECTIONS[0].heading}
   non-TTY라 CLI의 readline 프롬프트가 안 뜨므로, 호출자(LLM)가 직접 묻고
   플래그를 명시해야 함. 묻지 않고 기본값으로 등록하지 말 것.
 - 승인된 룰은 다음 세션부터 자동 적용.
+- **모델 피팅 랫쳇**: \`.claude/ratchet-model.md\`(프로젝트)와
+  \`~/.claude/ratchet-model.md\`(글로벌)에 있는 티어 위임 룰도 ratchet.md와
+  동일하게 따를 것. 이 파일은 claude-token-saver가 로그 기반으로 자동
+  생성·갱신하므로 직접 수정하지 말 것 (관리: \`route-scan rules\`).
 
 ${HARNESS_SECTIONS[1].heading}
 완료 보고("다 됐어요", "테스트 통과") 시 다음 중 1개 이상을 항상 첨부: