claude-token-saver 3.0.0 → 3.0.1

package/README.en.md

@@ -117,14 +117,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>
@@ -251,10 +250,13 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### 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

@@ -98,14 +98,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>
@@ -208,10 +207,13 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### 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

@@ -632,7 +632,7 @@ async function main() {
   //   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];
@@ -870,22 +870,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 +951,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.0.1",
   "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.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;
 }
 
 /**