claude-token-saver 3.6.2 → 3.6.3

package/README.en.md

@@ -243,6 +243,12 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.6.3 (2026-07-27)
+- **Fixed: approved ratchet rules never reached the session** — `harness promote` appended rules to `ratchet.md`, but nothing ever read that file. Claude Code loads `CLAUDE.md` (plus whatever it imports) and the harness block carried no import line, so "approved rules apply automatically from the next session" was unimplemented. The block now imports `@.claude/ratchet.md` (project) / `@~/.claude/ratchet.md` (global). Re-running `harness init` upgrades an existing block in place.
+- **`ratchet-model.md` is imported explicitly too** — delegation rules now travel the same declared path instead of relying on a host that happens to pick the file up. To keep the import from dangling, `harness init` seeds an empty file and `syncAllFiles` empties rather than deletes a target that loses its last rule.
+- **New `🅷⚠ ratchet-unloaded` warning** — all five sections can be present while the rules are dead weight, so a missing import is reported separately from `N/5`. `harness check` says the same thing and prints the fix.
+- **New `harness prune`, plus ratchet size in `check`** — an imported ratchet costs tokens on every request. `harness check` now reports rule count and per-request tokens and warns past ~2,000. Trim with `harness prune [--tag <t>] [--older-than <months>] [--dry-run]`, which moves rules to `ratchet-archive.md` rather than deleting them. Prefix a rule with `[tags]` (`- 2026-05-08: [video] ...`) to prune by topic. (`@` imports are static, so load-time filtering is not possible — the only lever is fewer rules.)
+
 ### v3.6.2 (2026-07-26)
 - Docs-only release — restores the missing v3.4.0–v3.5.3 release notes below. Published because the npm package page renders the README of the published version. No code changes.
 

package/README.md

@@ -200,6 +200,12 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.6.3 (2026-07-27)
+- **승인한 ratchet 룰이 세션에 전달되지 않던 버그 수정** — `harness promote`는 룰을 `ratchet.md`에 append했지만, 그 파일을 읽는 소비자가 어디에도 없었습니다. Claude Code는 `CLAUDE.md`(와 그것이 import하는 파일)만 로드하는데 harness 블록에 import 라인이 없었기 때문에, "승인된 룰은 다음 세션부터 자동 적용"은 사실상 미구현 상태였습니다. 이제 harness 블록이 `@.claude/ratchet.md`(project) / `@~/.claude/ratchet.md`(global)를 import합니다. `harness init`을 다시 돌리면 기존 블록도 제자리에서 갱신됩니다.
+- **`ratchet-model.md`도 명시적으로 import** — 모델 피팅 룰도 호스트가 알아서 읽어주길 기대하지 않고 같은 경로로 전달합니다. import가 끊기지 않도록 `harness init`이 빈 파일을 미리 만들고, 마지막 룰이 사라져도 `syncAllFiles`가 파일을 지우는 대신 비웁니다.
+- **`🅷⚠ ratchet-unloaded` 경고 추가** — 5개 섹션이 다 있어도 import 라인이 없으면 룰이 죽어 있는 상태라, `N/5`와 별개로 표시합니다. `harness check`도 같은 내용을 수정 명령과 함께 안내합니다.
+- **`harness prune` 추가 + ratchet 크기 표시** — import된 ratchet은 매 요청마다 토큰을 씁니다. `harness check`가 룰 수와 요청당 토큰을 보여주고 ~2,000 토큰을 넘으면 경고합니다. 정리는 `harness prune [--tag <t>] [--older-than <months>] [--dry-run]` — 삭제가 아니라 `ratchet-archive.md`로 이동합니다. 룰 앞에 `[태그]`를 붙여두면(`- 2026-05-08: [video] ...`) 묶어서 정리할 수 있습니다. (`@` import는 정적이라 로드 시점 필터링은 불가능합니다 — 줄일 방법은 룰 자체를 줄이는 것뿐)
+
 ### v3.6.2 (2026-07-26)
 - 문서 전용 릴리스 — 아래 v3.4.0~v3.5.3 릴리스 노트가 누락돼 있던 것을 복원했고, npm 패키지 페이지는 발행된 버전의 README를 보여주므로 이를 반영하기 위해 올립니다. 코드 변경 없음.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.6.2",
+  "version": "3.6.3",
   "description": "Save tokens on Claude Code — spike diagnosis, 1M-context detection, TTL countdown, statusline. (formerly claude-cache-monitor)",
   "type": "module",
   "bin": {

package/src/commands/harness.js

@@ -27,7 +27,7 @@ export async function run({ args, hasFlag }) {
       }
       return dflt;
     };
-    const { harnessInit, harnessUninit, harnessStatus, harnessPromote, harnessPull, harnessListRules, harnessRmRule, findProjectRoot } =
+    const { harnessInit, harnessUninit, harnessStatus, harnessPromote, harnessPull, harnessListRules, harnessRmRule, harnessPrune, ratchetSizeStatus, RATCHET_TOKEN_BUDGET, findProjectRoot } =
       await import('../harness.js');
     const { HARNESS_SECTIONS } = await import('../harness-templates.js');
     const { loadConfig, saveConfig, userLanguage } = await import('../config.js');
@@ -54,6 +54,29 @@ export async function run({ args, hasFlag }) {
       } else {
         console.log('All 5 harness sections present. ✅');
       }
+      // Sections can all be present while ratchet.md still never reaches the
+      // model — blocks written before v3.6.3 have no `@` import line.
+      if (s.hasBlock && !(s.hasRatchetImport && s.hasModelRatchetImport)) {
+        const dead = [!s.hasRatchetImport && 'ratchet.md', !s.hasModelRatchetImport && 'ratchet-model.md'].filter(Boolean).join(' + ');
+        console.log(`\n⚠ ${dead} is NOT loaded into sessions — the harness block has no \`@\` import line for it.`);
+        console.log('  Those rules are being written to a file nothing reads.');
+        console.log(`  Fix: claude-token-saver harness init${s.source === 'global' ? ' --global' : ''}   (updates the block in place)`);
+      }
+      // Imported ratchets are charged on every request, so their size matters.
+      // Static `@` imports cannot be filtered at load time — the only lever is
+      // fewer rules, hence the prune pointer rather than a "filter" suggestion.
+      for (const sc of ['project', 'global']) {
+        const size = ratchetSizeStatus({ scope: sc });
+        if (!size.count) continue;
+        const line = `ratchet.md [${sc}]: ${size.count} rules, ~${size.tokens} tok/request`;
+        if (size.overBudget) {
+          console.log(`\n⚠ ${line} — over the ~${RATCHET_TOKEN_BUDGET} token budget.`);
+          console.log(`  Trim: claude-token-saver harness prune${sc === 'global' ? ' --global' : ''} --older-than 6 --dry-run`);
+          console.log('  (project-specific rules belong in --project scope, not global.)');
+        } else {
+          console.log(`${line}`);
+        }
+      }
       return;
     }
 
@@ -322,6 +345,38 @@ export async function run({ args, hasFlag }) {
       if (wantProject) print('project');
       if (wantGlobal) print('global');
       console.log('Remove with: claude-token-saver harness rm [--global|--project] <N>');
+      console.log('Archive in bulk:  claude-token-saver harness prune [--global] [--tag <t>] [--older-than <months>] [--dry-run]');
+      return;
+    }
+
+    if (sub === 'prune') {
+      const pruneScope = parseHarnessScope(args.slice(2), 'project');
+      const argv = args.slice(2);
+      const valueOf = (flag) => {
+        const i = argv.indexOf(flag);
+        if (i !== -1 && argv[i + 1] && !argv[i + 1].startsWith('--')) return argv[i + 1];
+        const eq = argv.find((a) => a.startsWith(flag + '='));
+        return eq ? eq.slice(flag.length + 1) : null;
+      };
+      const months = valueOf('--older-than');
+      if (months !== null && !/^\d+$/.test(months)) {
+        console.error(`Invalid --older-than value: ${months} (expected a number of months)`);
+        process.exit(1);
+      }
+      const r = harnessPrune({
+        scope: pruneScope,
+        tag: valueOf('--tag'),
+        olderThanMonths: months ? parseInt(months, 10) : null,
+        dryRun: hasFlag('--dry-run'),
+      });
+      if (!r.ok) { console.error(r.error); process.exit(1); }
+      if (!r.pruned.length) { console.log(`Nothing matched — ${r.path} unchanged.`); return; }
+      console.log(`${r.dryRun ? 'Would prune' : 'Pruned'} ${r.pruned.length} rule(s) from ${r.path}:`);
+      for (const p of r.pruned) console.log(`  #${p.index}  ${p.text.slice(0, 100)}`);
+      if (!r.dryRun) {
+        console.log(`\nArchived to: ${r.archive}   (backup: ${r.backup})`);
+        console.log('Archived rules are NOT loaded into sessions — paste one back into ratchet.md to restore it.');
+      }
       return;
     }
 
@@ -378,6 +433,6 @@ export async function run({ args, hasFlag }) {
     }
 
     console.error(`Unknown harness subcommand: ${sub}`);
-    console.error('Usage: claude-token-saver harness [check|init|uninit [--purge-ratchet]|promote "<rule>"|pull [--global|--project]|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>|prune [--tag <t>] [--older-than <months>] [--dry-run]|off|on]');
     process.exit(1);
 }

package/src/harness-templates.js

@@ -17,7 +17,36 @@ export const HARNESS_SECTIONS = [
   { id: 'safe-path', heading: '### 5. Default Safe Path — 파괴적 명령 항상 확인' },
 ];
 
-export function harnessClaudeMdBlock() {
+/**
+ * The `@` import that actually loads ratchet.md into the session.
+ *
+ * Without this line the promoted rules live in a file nobody reads: Claude Code
+ * only loads CLAUDE.md (plus whatever it imports), so `harness promote` was a
+ * write-only operation before v3.6.3. Project scope imports the repo-local
+ * ratchet, global scope the user-level one — mirroring resolveRatchetPath().
+ */
+export function ratchetImportLine(scope = 'project') {
+  return scope === 'global' ? '@~/.claude/ratchet.md' : '@.claude/ratchet.md';
+}
+
+/**
+ * The model-fitting ratchet is imported too, so the delegation rules reach the
+ * model through the same declared path as everything else instead of relying on
+ * a host that happens to pick the file up. harnessInit() seeds an empty
+ * ratchet-model.md and syncAllFiles() empties rather than deletes it, so this
+ * import never dangles.
+ */
+export function modelRatchetImportLine(scope = 'project') {
+  return scope === 'global' ? '@~/.claude/ratchet-model.md' : '@.claude/ratchet-model.md';
+}
+
+// Matches either scope's import line, so completeness checks don't need to know
+// which scope wrote the block. `(?!-)` keeps the ratchet-model import from
+// counting as the ratchet.md one.
+export const RATCHET_IMPORT_RE = /^@(?:~\/\.claude|\.claude)\/ratchet\.md\s*$/m;
+export const MODEL_RATCHET_IMPORT_RE = /^@(?:~\/\.claude|\.claude)\/ratchet-model\.md\s*$/m;
+
+export function harnessClaudeMdBlock(scope = 'project') {
   const sections = HARNESS_SECTIONS.map((s) => s.heading).join('\n\n... (see full block below)');
   return `${HARNESS_BLOCK_BEGIN}
 ## 🅷 Harness Rules (claude-token-saver)
@@ -36,7 +65,8 @@ ${HARNESS_SECTIONS[0].heading}
   도구·환경 일반 룰이면 \`--global\`(\`~/.claude/ratchet.md\`). Bash 환경은
   non-TTY라 CLI의 readline 프롬프트가 안 뜨므로, 호출자(LLM)가 직접 묻고
   플래그를 명시해야 함. 묻지 않고 기본값으로 등록하지 말 것.
-- 승인된 룰은 다음 세션부터 자동 적용.
+- 승인된 룰은 이 블록 맨 아래 \`@\` import로 매 세션 로드된다 — 그 import 라인을
+  지우면 ratchet.md는 컨텍스트에 들어오지 않으니 지우지 말 것.
 - **모델 피팅 랫쳇**: \`.claude/ratchet-model.md\`(프로젝트)와
   \`~/.claude/ratchet-model.md\`(글로벌)에 있는 티어 위임 룰도 ratchet.md와
   동일하게 따를 것. 이 파일은 claude-token-saver가 로그 기반으로 자동
@@ -81,6 +111,13 @@ ${HARNESS_SECTIONS[4].heading}
 - \`claude-token-saver harness check\` — 현재 셋업 점수
 - \`claude-token-saver harness promote "<룰>" --project|--global\` — ratchet에 룰 추가 (scope는 사용자에게 먼저 물어볼 것)
 - \`claude-token-saver harness off\` — statusline 표시 끄기
+
+---
+
+📥 ratchet 룰 로드 (이 줄들을 지우면 룰이 적용되지 않습니다):
+
+${ratchetImportLine(scope)}
+${modelRatchetImportLine(scope)}
 ${HARNESS_BLOCK_END}
 `;
 }
@@ -93,6 +130,11 @@ export function harnessRatchetMdInitial() {
 \`claude-token-saver harness promote "<rule>"\`로 룰을 추가하면 자동으로
 이 파일에 append 됩니다.
 
+이 파일은 CLAUDE.md의 \`@\` import로 매 세션 로드됩니다 — 즉 여기 있는 모든 줄이
+매 요청마다 토큰을 씁니다. 날짜 뒤에 \`[태그]\`를 붙여두면 나중에 묶어서 정리할 수
+있습니다: \`- 2026-05-08: [video,tts] ...\` →
+\`claude-token-saver harness prune --tag video\` (삭제 아니라 ratchet-archive.md로 이동).
+
 ## Rules
 
 `;

package/src/harness.js

@@ -18,9 +18,11 @@ import {
   harnessClaudeMdBlock,
   harnessRatchetMdInitial,
   appendRatchetRule,
+  RATCHET_IMPORT_RE,
+  MODEL_RATCHET_IMPORT_RE,
 } from './harness-templates.js';
 import { routeWarningForStatusline } from './route-scan.js';
-import { ruleHealthWarningForStatusline } from './model-rules.js';
+import { ruleHealthWarningForStatusline, modelRatchetPathFor, renderModelRatchet } from './model-rules.js';
 
 const require = createRequire(import.meta.url);
 function readHarnessState() {
@@ -96,6 +98,8 @@ function statusForFile(filePath) {
       hasFile: false,
       optOut: false,
       custom: false,
+      hasRatchetImport: false,
+      hasModelRatchetImport: false,
       file: filePath,
     };
   }
@@ -105,7 +109,7 @@ function statusForFile(filePath) {
   } catch {
     // Unreadable file (permissions, etc.) — report every section missing so
     // `harness check` can't print "All 5 sections present ✅" over a 0/5.
-    return { configured: 0, total: HARNESS_SECTIONS.length, missing: HARNESS_SECTIONS.map((s) => s.id), hasBlock: false, hasFile: true, optOut: false, custom: false, file: filePath };
+    return { configured: 0, total: HARNESS_SECTIONS.length, missing: HARNESS_SECTIONS.map((s) => s.id), hasBlock: false, hasFile: true, optOut: false, custom: false, hasRatchetImport: false, hasModelRatchetImport: false, file: filePath };
   }
   const hasBlock = content.includes(HARNESS_BLOCK_BEGIN);
   // Opt-out marker — when the user intentionally customizes the harness block
@@ -131,6 +135,11 @@ function statusForFile(filePath) {
     hasFile: true,
     optOut,
     custom,
+    // Whether the promoted ratchet rules actually reach the model. Blocks
+    // written before v3.6.3 have all 5 sections but no import, so the rules
+    // sat in a file nothing read — worth flagging separately from N/5.
+    hasRatchetImport: RATCHET_IMPORT_RE.test(content),
+    hasModelRatchetImport: MODEL_RATCHET_IMPORT_RE.test(content),
     file: filePath,
   };
 }
@@ -168,7 +177,7 @@ export function harnessInit({ root = findProjectRoot(), force = false, scope = '
   const result = { wrote: [], backedUp: [], skipped: [], root, scope };
 
   // CLAUDE.md
-  const block = harnessClaudeMdBlock();
+  const block = harnessClaudeMdBlock(scope);
   if (existsSync(cmPath)) {
     const existing = readFileSync(cmPath, 'utf8');
     if (existing.includes(HARNESS_BLOCK_BEGIN) && !force) {
@@ -209,6 +218,20 @@ export function harnessInit({ root = findProjectRoot(), force = false, scope = '
     result.skipped.push(rmPath + ' (already exists)');
   }
 
+  // ratchet-model.md — tool-owned, normally written by route-scan. The block
+  // imports it, so seed an empty one now rather than ship a dangling import
+  // into every project that has not been scanned yet.
+  const mrPath = modelRatchetPathFor(scope, root);
+  if (!existsSync(mrPath)) {
+    try {
+      mkdirSync(dirname(mrPath), { recursive: true });
+      writeFileSync(mrPath, renderModelRatchet([]));
+      result.wrote.push(mrPath);
+    } catch { /* unwritable — route-scan will retry on its next sync */ }
+  } else {
+    result.skipped.push(mrPath + ' (already exists)');
+  }
+
   return result;
 }
 
@@ -348,10 +371,74 @@ export function harnessListRules({ root = findProjectRoot(), scope = 'project' }
     // 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+/, '') });
+      const text = line.replace(/^\s*-\s+/, '');
+      rules.push({ index: rules.length + 1, lineNo: i, text, ...parseRuleMeta(text) });
     }
   }
-  return { path: rmPath, rules };
+  return { path: rmPath, rules, bytes: Buffer.byteLength(readFileSync(rmPath, 'utf8'), 'utf8') };
+}
+
+/**
+ * Rule metadata, parsed from the line the user already writes:
+ *   "- 2026-05-08: [video,tts] 자막 렌더 시 ..."
+ * Both parts are optional — `date` is null on undated rules, `tags` empty on
+ * untagged ones. Tags exist to make pruning targeted (`prune --tag video`);
+ * they deliberately do NOT filter what gets loaded, because CLAUDE.md `@`
+ * imports are static — the file that is imported is the file that is read, so
+ * the only way to spend fewer tokens is to have fewer rules in it.
+ */
+export function parseRuleMeta(text) {
+  const dateM = text.match(/^(\d{4})-(\d{2})-(\d{2})\s*:/);
+  // Tags must lead the rule body (right after the date, or at the very start),
+  // so a bracketed aside later in the sentence is not mistaken for a tag list.
+  const tagM = text.match(/^(?:\d{4}-\d{2}-\d{2}\s*:\s*)?\[([^\]]+)\]/);
+  return {
+    date: dateM ? dateM[0].replace(/\s*:$/, '') : null,
+    tags: tagM ? tagM[1].split(',').map((t) => t.trim()).filter(Boolean) : [],
+  };
+}
+
+// Rough token cost of the imported ratchet, charged on every single request of
+// every session. 4 bytes/token is the usual mixed ko/en approximation.
+export const RATCHET_TOKEN_BUDGET = 2000;
+
+export function ratchetSizeStatus({ root = findProjectRoot(), scope = 'project' } = {}) {
+  const { path, rules, bytes = 0 } = harnessListRules({ root, scope });
+  const tokens = Math.round(bytes / 4);
+  return { path, count: rules.length, bytes, tokens, overBudget: tokens > RATCHET_TOKEN_BUDGET };
+}
+
+/**
+ * harness prune — move rules out of ratchet.md into ratchet-archive.md next to
+ * it. Selection is by tag and/or age; nothing is deleted, so a pruned rule can
+ * be pasted back. Returns the pruned rules for the CLI to echo.
+ */
+export function harnessPrune({ root = findProjectRoot(), scope = 'project', tag = null, olderThanMonths = null, dryRun = false } = {}) {
+  const { path: rmPath, rules } = harnessListRules({ root, scope });
+  if (!existsSync(rmPath)) return { ok: false, error: `ratchet.md not found at ${rmPath}` };
+  if (!tag && !olderThanMonths) return { ok: false, error: 'Nothing selected — pass --tag <t> and/or --older-than <months>' };
+  const cutoff = olderThanMonths ? Date.now() - olderThanMonths * 30 * 24 * 60 * 60 * 1000 : null;
+  const doomed = rules.filter((r) => {
+    if (tag && !r.tags.includes(tag)) return false;
+    // An undated rule has no age to judge, so age-based pruning leaves it be.
+    if (cutoff !== null) {
+      const t = r.date ? Date.parse(r.date) : NaN;
+      if (!Number.isFinite(t) || t >= cutoff) return false;
+    }
+    return true;
+  });
+  if (dryRun || doomed.length === 0) return { ok: true, path: rmPath, pruned: doomed, dryRun: true };
+  const content = readFileSync(rmPath, 'utf8');
+  writeFileSync(rmPath + '.bak', content);
+  const drop = new Set(doomed.map((r) => r.lineNo));
+  const kept = content.split('\n').filter((_, i) => !drop.has(i));
+  writeFileSync(rmPath, kept.join('\n'));
+  const archivePath = join(dirname(rmPath), 'ratchet-archive.md');
+  const header = existsSync(archivePath) ? '' : '# Ratchet Archive (pruned rules — not loaded into sessions)\n\n';
+  const stamp = new Date().toISOString().slice(0, 10);
+  const body = doomed.map((r) => `- ${r.text}  <!-- pruned ${stamp} -->`).join('\n') + '\n';
+  writeFileSync(archivePath, (existsSync(archivePath) ? readFileSync(archivePath, 'utf8').replace(/\n*$/, '\n') : header) + body);
+  return { ok: true, path: rmPath, backup: rmPath + '.bak', archive: archivePath, pruned: doomed };
 }
 
 /**
@@ -420,6 +507,10 @@ export function harnessStatusForStatusline(cfg, { root } = {}) {
       else if (state.pevSkip) warning = 'PEV-skip';
     }
   }
+  // Config defect, above the optimization nudges: the harness block is there
+  // but carries no `@` import, so every promoted ratchet rule is dead weight.
+  // One `harness init` re-run fixes it and the warning goes away for good.
+  if (!warning && status.hasBlock && !(status.hasRatchetImport && status.hasModelRatchetImport)) warning = 'ratchet-unloaded';
   // Below session-quality warnings: a promoted delegation rule whose
   // category started failing (`rule-health R<N>`) — the user approved that
   // rule, so its degradation outranks a mere new-candidate nudge.

package/src/model-rules.js

@@ -28,7 +28,7 @@
  * ratchet.md.
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { userDataDir } from './paths.js';
@@ -205,9 +205,11 @@ export function syncAllFiles({ previousPaths = [] } = {}) {
       written.push(p);
     } catch { /* unwritable target — skip, registry stays authoritative */ }
   }
+  // A target that lost its last rule is emptied, NOT deleted: CLAUDE.md
+  // imports this path, and a dangling `@` import is worse than an empty file.
   for (const p of previousPaths) {
     if (!byPath.has(p) && existsSync(p)) {
-      try { unlinkSync(p); } catch { /* leave stale file; regenerated next sync */ }
+      try { writeFileSync(p, renderModelRatchet([])); } catch { /* stale content; regenerated next sync */ }
     }
   }
   return written;