claude-token-saver 3.37.0 → 3.38.0

package/README.ko.md

@@ -214,6 +214,7 @@ Claude Code 안에서 `/claude-token-saver` Skill을 실행하거나, 칩에 적
 | `claude-token-saver route-scan savings` | 라우팅 절감 원장입니다. 모델 이동별 합계와 실행별 내역을 함께 보여 주며, 표시되는 금액의 근거가 됩니다 |
 | `claude-token-saver compact-window` | 1M 컨텍스트를 쓰면서 자동 압축 창이 설정되지 않았으면 경고하고, `set`으로 40만에 고정합니다 (아래 참고) |
 | `claude-token-saver korean on\|off\|status` | 한국어 문체 지침을 세션 시작 시 주입하고, 쓰기 시점 검사를 함께 설치합니다 (아래 참고) |
+| `claude-token-saver cohesion on\|off\|status\|show` | 영어 문장 연결(응집성) 지침을 세션 시작 시 주입합니다 |
 | `claude-token-saver korean lint block\|warn\|off` | 쓰기 시점 검사가 위반을 어떻게 처리할지 정합니다 |
 | `claude-token-saver korean lint scope all\|prose` | 검사 범위를 모든 텍스트 파일과 문서 전용 사이에서 고릅니다 |
 | `claude-token-saver doc2md on\|off` | 첨부 문서를 모델이 읽기 전에 Markdown 으로 변환합니다 (아래 참고) |
@@ -416,7 +417,7 @@ Claude Code의 output style로도 같은 일을 할 수 있지만, output style
 - **상투 패턴**: 자동으로 붙는 수식어("다양한", "핵심적인"), 표지판 문장, 수사적 질문 뒤 즉답, 근거 없는 긍정 마무리.
 - **응집성**: 문장이 이어지는 방식이라 정규식으로는 검사하지 못합니다. 이 절의 방향을 정한 연구 결과가 있습니다. 접속어·지시어 같은 표층 연결 장치는 글의 품질과 상관이 없거나 오히려 부적 상관이고, 앞 문장이 내놓은 정보를 다음 문장이 받아 풀어 주는 상술형 연결만 정적 상관을 보였습니다. 그래서 지침은 연결이 어색할 때 접속어를 더하지 말고 정보의 배열(아는 것 먼저, 새 것 나중)을 고치라고 말합니다.
 
-응집성 층의 원칙 대부분은 한국어에만 해당하지 않습니다. 구정보 우선 배열, 대명사의 단일 지시, 문단 안 주어 유지, 비약을 잇는 다리 문장, 짧은 반복 문장 병합은 영어 산문에도 그대로 적용됩니다. 논문이 한국어 학습자를 다뤘을 뿐, 검증된 원칙은 텍스트언어학의 표준 응집성 모형입니다.
+응집성 층의 원칙 대부분은 한국어에만 해당하지 않습니다. 구정보 우선 배열, 대명사의 단일 지시, 문단 안 주어 유지, 비약을 잇는 다리 문장, 짧은 반복 문장 병합은 영어 산문에도 그대로 적용됩니다. 논문이 한국어 학습자를 다뤘을 뿐, 검증된 원칙은 텍스트언어학의 표준 응집성 모형입니다. 영어 산출물에는 `claude-token-saver cohesion on`이 같은 다섯 원칙을 영어 블록으로 주입합니다 (korean 지침이 켜져 있으면 중복이라 생략됩니다).
 
 마지막 절은 고치면 안 되는 것을 명시합니다. 정착된 전문 용어, 문어체, 원문 인용이 그것이고, 검사가 내는 지적은 판정이 아니라 확인 요청입니다.
 
@@ -601,6 +602,7 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 전체 내역은 [CHANGELOG.md](./CHANGELOG.md)로 옮겼습니다. 최근 변경은 다음과 같습니다.
 
+- **v3.38.0**: `cohesion on`이 응집성 다섯 원칙을 영어 블록으로 주입합니다. 옵트인이고, korean 지침이 켜져 있으면 중복 주입을 막습니다.
 - **v3.37.0**: 한국어 지침에 보강 지침(supplement)이 붙습니다. 번역투·상투 패턴·응집성(문장 이어짐) 조항이며, 쓰기 시점 검사에도 번역투 5종이 추가됐습니다. 실파일 255개 실측에서 오탐 1건으로 검증했습니다.
 - **v3.35.0**: 이번 달 1일 00시 이후 지출 추정치를 `💵 Sep $42` 세그먼트로 상시 표시합니다. LiteLLM 게이트웨이 사용자는 키의 max_budget/spend 를 `🔑 budget` 게이지로 봅니다 (5h/7d cap 이 없는 Bedrock·LiteLLM 환경 대응).
 - **v3.34.0**: seed 프리셋 제안, 설치 시 출력 언어 선택, 컨텍스트 경고 500k 상향. 상세는 CHANGELOG 참고.

package/README.md

@@ -217,6 +217,7 @@ Run these in your shell (inside Claude Code, the `/claude-token-saver` Skill is
 | `claude-token-saver route-scan savings` | The routing-savings ledger — per-model-change rollup + per-run log (the evidence behind the figure) |
 | `claude-token-saver compact-window` | Warn when a 1M-context session has no auto-compact cap → pin 400k with `set` (below) |
 | `claude-token-saver korean on\|off\|status` | Inject Korean writing guidance at session start and install the write-time check (below) |
+| `claude-token-saver cohesion on\|off\|status\|show` | Inject English cohesion guidance (sentence-connection rules) at session start |
 | `claude-token-saver korean lint block\|warn\|off` | How the write-time check handles findings |
 | `claude-token-saver korean lint scope all\|prose` | Check every text file, or documents only |
 | `claude-token-saver doc2md on\|off` | Convert attached documents to Markdown before the model reads them (below) |
@@ -428,7 +429,7 @@ It adds three layers:
 - **AI-writing tics**: automatic intensifiers ("다양한", "핵심적인"), signpost sentences, rhetorical question-then-answer, unconditionally upbeat endings.
 - **Cohesion** — how sentences connect, which no regex can check. The research finding that shapes this section: surface connectives (conjunctions, demonstratives) correlate *negatively or not at all* with judged text quality, while elaboration — the next sentence picking up and unpacking what the previous one introduced — is the only connection type with a positive correlation. So the guidance says: when a transition feels rough, fix the information order (given before new), don't add a connective.
 
-**Most of the cohesion layer is not Korean-specific.** Given-before-new ordering (the "given-new contract"), one clear referent per pronoun, keeping one subject per paragraph, bridging sentences instead of leaping, and merging choppy repetitive sentences into a modifier-plus-core structure apply to English prose the same way — the studies happen to be about Korean learners, but the principles they validate are the standard cohesion model from text linguistics. If you write English deliverables with Claude, those five rules are worth pinning in your own CLAUDE.md even with this feature off.
+**Most of the cohesion layer is not Korean-specific.** Given-before-new ordering (the "given-new contract"), one clear referent per pronoun, keeping one subject per paragraph, bridging sentences instead of leaping, and merging choppy repetitive sentences into a modifier-plus-core structure apply to English prose the same way — the studies happen to be about Korean learners, but the principles they validate are the standard cohesion model from text linguistics. If you write English deliverables with Claude, run `claude-token-saver cohesion on` — it injects exactly those five rules as a standalone English block (~0.5k tokens per session), no Korean feature required. While `korean on` is active the block is suppressed, because the Korean supplement already carries the same rules.
 
 A final subsection lists what must **not** be "corrected": settled domain terms, formal register, and verbatim quotations — every lint finding is a request to confirm, not a verdict.
 
@@ -722,6 +723,7 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 The full history moved to [CHANGELOG.md](./CHANGELOG.md) (Korean; version headings and command names are language-neutral). Recent changes:
 
+- **v3.38.0**: `cohesion on` — the language-neutral cohesion rules from the Korean supplement become a standalone English injection (given-before-new, one referent per pronoun, subject consistency, bridging, merging choppy sentences). Opt-in, ~0.5k tokens per session, suppressed while `korean on` already carries them.
 - **v3.37.0**: Korean guidance grows a conservative supplement (translationese, AI-writing tics, a research-backed cohesion section whose principles apply to English prose too) and the write-time lint gains 5 translationese patterns, validated at 1 false positive across 255 real files.
 - **v3.35.0**: A `💵 Sep $42` segment now shows estimated spend since 00:00 on the 1st of the current month, always on — including gateway setups with no 5h/7d caps. LiteLLM gateway users get a `🔑 budget ▰▱ 34% $34/$100` gauge built from the key's budget (`GET /key/info` + `GET /user/info`, team-membership budget first, then key, then internal user — verified against a Dockerized LiteLLM).
 - **v3.34.0**: seed presets offered one at a time, output-language choice at install, context warning raised to 500k.

package/bin/cli.js

@@ -85,7 +85,7 @@ function readUpdateChip() {
 
 // Subcommands this build knows how to run. Used only by the guard below.
 const KNOWN_SUBCOMMANDS = new Set([
-  'last', 'brief', 'history', 'handoff', 'install', 'uninstall', 'mode', 'korean',
+  'last', 'brief', 'history', 'handoff', 'install', 'uninstall', 'mode', 'korean', 'cohesion',
   'doc2md', 'harness', 'route-scan', 'compact-window', 'update-check', 'upgrade',
   'seed', 'litellm-budget',
 ]);
@@ -218,6 +218,13 @@ async function main() {
     return (await import('../src/commands/korean.js')).run({ args, hasFlag });
   }
 
+  // Subcommand: cohesion — English sentence-connection guidance injected at
+  // session start; the language-neutral half of the Korean supplement.
+  //   claude-token-saver cohesion on | off | status | show
+  if (args[0] === 'cohesion') {
+    return (await import('../src/commands/cohesion.js')).run({ args, hasFlag });
+  }
+
   // Subcommand: doc2md — convert pptx/xlsx/pdf/docx to Markdown before the
   // model reads them, so an unreadable binary never enters the context window.
   //   claude-token-saver doc2md on | off | <file> | --clean

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.37.0",
+  "version": "3.38.0",
   "description": "Route the easy work your expensive Claude model keeps repeating down to haiku/sonnet — post-hoc session analysis, no realtime router, no extra LLM calls.",
   "type": "module",
   "bin": {

package/presets/cohesion/cohesion-en.md

@@ -0,0 +1,26 @@
+<!--
+  English cohesion guidance — claude-token-saver's own text, distilled from the
+  same sources as the Korean supplement's cohesion section: the given-new
+  contract from text linguistics, and three studies on Korean learner writing
+  whose validated principles are language-neutral (surface connectives
+  correlate negatively or not at all with judged text quality; elaboration is
+  the only connection type with a positive correlation).
+
+  Injected at session start when `claude-token-saver cohesion on` is set and
+  the Korean guidance is off (the Korean supplement already carries these
+  rules, so injecting both would bill the same principles twice).
+-->
+
+Follow these rules whenever you write English prose the user will read — answers, documents, reports, comments, UI copy. They govern how sentences connect, which is where generated text most often reads as stilted even when every sentence is individually fine.
+
+1. **Move from known to new.** Start each sentence with information the reader already has; put the new information at the end. Let the next sentence pick up that new information and unpack it. When a transition feels rough, fix this ordering first — do not reach for a connective. Research on text quality found that surface connectives (however, moreover, additionally) correlate negatively or not at all with judged quality; elaboration — the next sentence developing what the previous one introduced — is the only connection type that correlates positively.
+
+2. **One clear referent per pronoun.** If "it", "this", or "they" could point at more than one thing in the previous sentence, repeat the noun instead. Introduce people and organizations with a role tag on first mention ("the maintainer, Alice Park") rather than dropping a bare name.
+
+3. **Keep one subject per paragraph.** Changing the grammatical subject every sentence forces the reader to reorient each time. Stay with one subject unless the topic actually shifts.
+
+4. **No leaps.** If a sentence presupposes a condition or a cause the text has not established, add the bridging sentence rather than trusting the reader to reconstruct it. The most common failure is a new entity appearing with a definite article ("the report", "the agent") before anything has introduced it.
+
+5. **Merge choppy repetition.** Three short sentences circling the same subject read worse than one sentence with the minor facts folded into modifiers. Demote the less important sentence to a clause; keep the core claim as the main clause.
+
+Do not overcorrect: settled domain terms, formal register, and verbatim quotations stay as they are.

package/src/cohesion.js

@@ -0,0 +1,70 @@
+/**
+ * cohesion — English sentence-connection guidance injected at session start.
+ *
+ * The Korean supplement's cohesion section turned out to be language-neutral:
+ * given-before-new ordering, one referent per pronoun, subject consistency,
+ * bridging instead of leaping, merging choppy sentences. English-only users
+ * never run `korean on`, so those rules never reached them. This module ships
+ * the same principles as a standalone English block.
+ *
+ * Off by default for the same reason the Korean guidance is opt-in: a
+ * token-saving tool has no business silently billing ~0.5k tokens a session.
+ * Enable with `claude-token-saver cohesion on`.
+ *
+ * When the Korean guidance is enabled, this block is NOT injected even if
+ * enabled: the Korean supplement already carries the cohesion rules, and
+ * injecting the same principles twice bills them twice.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadConfig, saveConfig } from './config.js';
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+export const COHESION_PATH = join(packageRoot, 'presets', 'cohesion', 'cohesion-en.md');
+
+/** Whether session-start injection is enabled. Off unless the user asked. */
+export function cohesionEnabled(cfg = loadConfig()) {
+  return cfg?.cohesion?.enabled === true;
+}
+
+export function setCohesionEnabled(enabled) {
+  const cfg = loadConfig();
+  cfg.cohesion = { ...(cfg.cohesion || {}), enabled: !!enabled };
+  saveConfig(cfg);
+  return cfg.cohesion;
+}
+
+/** The guidance text with the provenance comment stripped, or null. */
+export function cohesionText() {
+  try {
+    if (!existsSync(COHESION_PATH)) return null;
+    const raw = readFileSync(COHESION_PATH, 'utf8');
+    const body = raw.replace(/^<!--[\s\S]*?-->\s*/, '').trim();
+    return body || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Block to inject at session start, or null when disabled, unavailable, or
+ * redundant (Korean guidance on — its supplement already carries these rules).
+ */
+export async function cohesionInjection({ cfg = loadConfig() } = {}) {
+  if (!cohesionEnabled(cfg)) return null;
+  try {
+    const { koreanStyleEnabled } = await import('./korean-style.js');
+    if (koreanStyleEnabled(cfg)) return null;
+  } catch { /* korean module unavailable: inject normally */ }
+  const text = cohesionText();
+  if (!text) return null;
+  return [
+    '[claude-token-saver cohesion] Follow this guidance for English prose in this session.',
+    'The user enabled it in claude-token-saver.',
+    '',
+    text,
+  ].join('\n');
+}

package/src/commands/cohesion.js

@@ -0,0 +1,59 @@
+/**
+ * Subcommand: cohesion — English sentence-connection guidance for every session.
+ *   claude-token-saver cohesion on       # inject at session start, all projects
+ *   claude-token-saver cohesion off      # stop injecting
+ *   claude-token-saver cohesion status   # current state and cost
+ *   claude-token-saver cohesion show     # print the guidance itself
+ *
+ * The English sibling of `korean on`, carrying only the language-neutral
+ * cohesion rules (given-before-new, one referent per pronoun, subject
+ * consistency, bridging, merging choppy sentences). No lint: every clause
+ * needs judgement, so nothing here is machine-checkable.
+ */
+
+export async function run({ args }) {
+  const sub = args[1] || 'status';
+  const co = await import('../cohesion.js');
+  const { userLanguage } = await import('../config.js');
+  const lang = userLanguage();
+
+  if (sub === 'on' || sub === 'off') {
+    co.setCohesionEnabled(sub === 'on');
+    if (sub === 'on') {
+      console.log(lang === 'ko'
+        ? '✍️ cohesion on: 다음 세션부터 영어 문장 연결 지침이 주입됩니다 (약 0.5k 토큰/세션, 세션 시작 1회).'
+        : '✍️ cohesion on — English cohesion guidance will be injected from the next session (~0.5k tokens per session, once at session start).');
+      const { koreanStyleEnabled } = await import('../korean-style.js');
+      if (koreanStyleEnabled()) {
+        console.log(lang === 'ko'
+          ? '참고: korean 지침이 켜져 있는 동안에는 같은 원칙이 이미 들어가므로 이 블록은 주입되지 않습니다.'
+          : 'Note: while the Korean guidance is on, its supplement already carries these rules, so this block is not injected.');
+      }
+    } else {
+      console.log(lang === 'ko' ? 'cohesion off: 더 이상 주입하지 않습니다.' : 'cohesion off — no longer injected.');
+    }
+    return;
+  }
+
+  if (sub === 'show') {
+    const text = co.cohesionText();
+    if (!text) {
+      console.error('cohesion guidance file missing: ' + co.COHESION_PATH);
+      process.exit(1);
+    }
+    console.log(text);
+    return;
+  }
+
+  // status (default)
+  const enabled = co.cohesionEnabled();
+  const { koreanStyleEnabled } = await import('../korean-style.js');
+  const suppressed = enabled && koreanStyleEnabled();
+  if (lang === 'ko') {
+    console.log(`cohesion: ${enabled ? 'on' : 'off'}${suppressed ? ' (korean 지침이 켜져 있어 주입은 생략됨)' : ''}`);
+    console.log('영어 산문의 문장 연결 지침을 세션 시작에 주입합니다. 켜기: claude-token-saver cohesion on');
+  } else {
+    console.log(`cohesion: ${enabled ? 'on' : 'off'}${suppressed ? ' (suppressed while the Korean guidance is on — it already carries these rules)' : ''}`);
+    console.log('Injects English cohesion guidance at session start. Enable with: claude-token-saver cohesion on');
+  }
+}

package/src/commands/route-scan.js

@@ -251,6 +251,14 @@ export async function run({ args, hasFlag, numArg }) {
         koreanBlock = koreanStyleInjection();
       } catch (e) { debug('route-scan:korean-style', e); /* style is optional */ }
 
+      // English cohesion guidance, when enabled. Same round-trip; skipped
+      // internally when the Korean guidance already carries the same rules.
+      let cohesionBlock = null;
+      try {
+        const { cohesionInjection } = await import('../cohesion.js');
+        cohesionBlock = await cohesionInjection();
+      } catch (e) { debug('route-scan:cohesion', e); /* the guidance is optional */ }
+
       // doc2md's standing note, only when the user turned the feature on.
       // Rides the same SessionStart round-trip as the style block for the same
       // reason: one injection, one cached prefix. It carries the two things the
@@ -312,6 +320,7 @@ export async function run({ args, hasFlag, numArg }) {
         if (seedBlock) console.log(seedBlock);
         if (doc2mdBlock) console.log(doc2mdBlock);
         if (koreanBlock) console.log(koreanBlock);
+        if (cohesionBlock) console.log(cohesionBlock);
         return; // nothing else to inject
       }
       if (updateBlock) console.log(updateBlock);
@@ -383,6 +392,7 @@ export async function run({ args, hasFlag, numArg }) {
       // Style first, briefing second: the briefing is Korean prose too, so the
       // guidance has to be in context before the model reads it.
       if (koreanBlock) console.log(koreanBlock + '\n');
+      if (cohesionBlock) console.log(cohesionBlock + '\n');
       console.log(lines.join('\n'));
       // Record what was actually briefed so the UserPromptSubmit brief hook
       // suppresses exactly these — a candidate landing after this read (e.g.