claude-token-saver 2.9.3 → 2.10.0

package/README.en.md

@@ -12,6 +12,24 @@ A CLI to **diagnose and save tokens on Claude Code**. Cache hit rate, TTL countd
 
 ## Install
 
+### Prerequisite — Node.js (≥ 18)
+
+`npm` ships with Node.js. Check whether it's installed:
+
+```bash
+node -v   # v18.0.0 or later is fine
+```
+
+If not, install it:
+
+- **macOS** — `brew install node` (Homebrew) or the installer at [nodejs.org](https://nodejs.org/)
+- **Windows** — [nodejs.org](https://nodejs.org/) LTS installer, or `winget install OpenJS.NodeJS.LTS`
+- **Linux / WSL** — your distro's package manager (`apt install nodejs npm`, etc.) or — recommended — [nvm](https://github.com/nvm-sh/nvm) for a user-scoped install (no sudo)
+
+> Avoid installing globally with `sudo`. The postinstall hook writes the Skill into root's `~/.claude` instead of yours, and auto-registration silently misses. Use nvm/fnm/Volta, or set `npm config set prefix ~/.npm-global` first.
+
+### Install claude-token-saver
+
 ```bash
 # (existing users) remove the old package
 npm uninstall -g claude-cache-monitor
@@ -191,6 +209,9 @@ Node.js ≥ 18 · macOS / Windows / Linux / WSL · zero dependencies.
 
 ## Release notes
 
+### v2.9.4 (2026-04-27)
+- README now opens with a Node.js prerequisite block (macOS / Windows / Linux). First-time visitors arriving from GitHub no longer hit `npm: command not found` with no guidance. Also flags the `sudo` global-install trap where postinstall writes the Skill under root's home instead of the user's.
+
 ### v2.9.3 (2026-04-27)
 - Skill body (`SKILL.md`) now instructs Claude to respond in the user's configured output language. Previously even when the CLI was on `mode ko`, Claude itself still narrated the answer in English ("All clear — no warnings…"), so the language toggle felt half-applied.
 - `installSkill` now auto-updates the on-disk `SKILL.md` whenever the bundled body differs, so upgrades pick up new instructions without `--force`.

package/README.md

@@ -12,6 +12,24 @@ Claude Code의 **토큰 사용량을 진단·절약**하는 CLI. 캐시 히트
 
 ## 설치
 
+### 사전 준비 — Node.js (≥ 18) 필요
+
+`npm`은 Node.js에 포함되어 있습니다. 설치돼 있는지 확인:
+
+```bash
+node -v   # v18.0.0 이상이면 OK
+```
+
+설치되어 있지 않다면:
+
+- **macOS** — `brew install node` (Homebrew) 또는 [nodejs.org](https://nodejs.org/) 설치 프로그램
+- **Windows** — [nodejs.org](https://nodejs.org/) LTS 설치 프로그램, 또는 `winget install OpenJS.NodeJS.LTS`
+- **Linux / WSL** — 배포판 패키지 매니저(`apt install nodejs npm` 등) 또는 [nvm](https://github.com/nvm-sh/nvm)으로 사용자 영역 설치 (sudo 없이 가능, 추천)
+
+> sudo로 글로벌 설치하면 postinstall 훅이 root의 `~/.claude`에 SKILL을 만들어 자동 등록이 어긋납니다. 가능하면 nvm/fnm/Volta로 사용자 영역에 Node를 설치하거나 `npm config set prefix ~/.npm-global` 같은 prefix 변경 후 사용하세요.
+
+### claude-token-saver 설치
+
 ```bash
 # (기존 사용자) 구 패키지 제거
 npm uninstall -g claude-cache-monitor
@@ -151,6 +169,9 @@ Node.js ≥ 18 · macOS / Linux / Windows / WSL · 의존성 0.
 
 ## 릴리스 노트
 
+### v2.9.4 (2026-04-27)
+- README에 Node.js 사전 설치 안내 추가 (macOS/Windows/Linux별). GitHub에서 처음 본 사용자가 npm 명령부터 막히는 일을 방지. sudo 글로벌 설치 시 postinstall이 root 홈에 SKILL을 만드는 함정도 함께 안내.
+
 ### v2.9.3 (2026-04-27)
 - Skill 본문(`SKILL.md`)에 "사용자 설정 언어로 응답" 지시 추가. 이전엔 Skill이 호출돼도 Claude가 영어로 요약을 생성하는 탓에 `mode ko` 상태에서도 영문 답이 나왔습니다 (`All clear - no warnings...` 같은 문구).
 - `installSkill`이 번들된 SKILL.md와 디스크의 내용이 다르면 자동 갱신하도록 변경 (`--force` 없이도 업그레이드 시 새 지시가 적용됨).

package/bin/cli.js

@@ -444,6 +444,133 @@ async function main() {
     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 check      # show 🅷 N/5 + which sections are missing
+  //   claude-token-saver harness promote "<rule>"  # append a rule to ratchet.md
+  //   claude-token-saver harness off | on   # toggle the statusline 🅷 segment
+  if (args[0] === 'harness') {
+    const sub = args[1];
+    const { harnessInit, harnessStatus, harnessPromote, findProjectRoot } =
+      await import('../src/harness.js');
+    const { HARNESS_SECTIONS } = await import('../src/harness-templates.js');
+    const { loadConfig, saveConfig } = await import('../src/config.js');
+
+    if (!sub || sub === 'check') {
+      const root = findProjectRoot();
+      const s = harnessStatus(root);
+      console.log(`🅷 ${s.configured}/${s.total} — ${root}`);
+      console.log(`CLAUDE.md: ${s.hasFile ? 'present' : 'missing'}` +
+        (s.hasFile ? `, harness block: ${s.hasBlock ? 'yes' : 'no'}` : ''));
+      if (s.missing.length) {
+        console.log('Missing sections:');
+        for (const id of s.missing) {
+          const sec = HARNESS_SECTIONS.find((x) => x.id === id);
+          console.log(`  - ${id}: ${sec ? sec.heading.replace(/^#+\s*/, '') : ''}`);
+        }
+        console.log('\nRun: claude-token-saver harness init');
+      } else {
+        console.log('All 5 harness sections present. ✅');
+      }
+      return;
+    }
+
+    if (sub === 'init') {
+      const force = hasFlag('--force');
+      const r = harnessInit({ force });
+      console.log(`Project root: ${r.root}`);
+      for (const p of r.backedUp) console.log(`Backed up: ${p}`);
+      for (const p of r.wrote) console.log(`Wrote:     ${p}`);
+      for (const p of r.skipped) console.log(`Skipped:   ${p}`);
+      console.log('\n🅷 Harness initialized. Statusline will show 🅷 5/5 on next refresh.');
+      return;
+    }
+
+    if (sub === 'promote') {
+      const raw = args.slice(2).join(' ').trim();
+      if (!raw) {
+        console.error('Usage: claude-token-saver harness promote <N>  # from statusline 🅷⚠ ratchet? #N');
+        console.error('   or: claude-token-saver harness promote "<rule text>"');
+        process.exit(1);
+      }
+      let rule = raw;
+      // Numeric arg → look up candidate #N from analyzer state and turn its
+      // detected error pattern into a starter ratchet rule. Saves the user
+      // from retyping the error; they can edit ratchet.md afterward.
+      if (/^\d+$/.test(raw)) {
+        const n = parseInt(raw, 10);
+        const analyzer = await import('../src/harness-analyzer.cjs');
+        const a = analyzer.default || analyzer;
+        const state = a.readState();
+        const list = (state && state.ratchetCandidates) || [];
+        const cand = list.find((c) => c.id === n);
+        if (!cand) {
+          console.error(`No ratchet candidate #${n} in state. Run \`harness analyze\` or wait for the hook to populate it.`);
+          if (list.length) {
+            console.error('Available candidates:');
+            for (const c of list) console.error(`  #${c.id} (×${c.count}): ${c.pattern}`);
+          }
+          process.exit(1);
+        }
+        rule = `반복 감지 ×${cand.count}: ${cand.pattern} — TODO: 원인·예방책 한 줄로`;
+      }
+      const r = harnessPromote(rule);
+      console.log(`Appended to ${r.path}:`);
+      console.log(`  - ${rule}`);
+      if (/^\d+$/.test(raw)) {
+        console.log('\n👉 ratchet.md를 열어 TODO 부분을 실제 룰로 다듬어주세요.');
+      }
+      return;
+    }
+
+    if (sub === 'analyze') {
+      // Run the analyzer once against the most recent session JSONL under
+      // ~/.claude/projects/ and dump the resulting state. Useful for users
+      // who don't have the hook installed but want to see warnings.
+      const analyzer = await import('../src/harness-analyzer.cjs');
+      const { analyzeTranscript, writeState } = analyzer.default || analyzer;
+      const { readdirSync, statSync } = await import('node:fs');
+      const { join: pj } = await import('node:path');
+      const { homedir } = await import('node:os');
+      const dir = pj(homedir(), '.claude', 'projects');
+      let latest = null;
+      let latestMtime = 0;
+      try {
+        for (const subdir of readdirSync(dir)) {
+          const full = pj(dir, subdir);
+          if (!statSync(full).isDirectory()) continue;
+          for (const f of readdirSync(full)) {
+            if (!f.endsWith('.jsonl')) continue;
+            const fp = pj(full, f);
+            const m = statSync(fp).mtimeMs;
+            if (m > latestMtime) { latestMtime = m; latest = fp; }
+          }
+        }
+      } catch {}
+      if (!latest) {
+        console.error('No session transcripts found under ~/.claude/projects/');
+        process.exit(1);
+      }
+      const state = analyzeTranscript(latest, { cwd: process.cwd() });
+      if (state) writeState(state);
+      console.log(JSON.stringify(state, null, 2));
+      return;
+    }
+
+    if (sub === 'off' || sub === 'on') {
+      const cfg = loadConfig();
+      cfg.harness = cfg.harness || {};
+      cfg.harness.enabled = sub === 'on';
+      saveConfig(cfg);
+      console.log(`Statusline 🅷 segment: ${sub}`);
+      return;
+    }
+
+    console.error(`Unknown harness subcommand: ${sub}`);
+    console.error('Usage: claude-token-saver harness [check|init|promote "<rule>"|off|on]');
+    process.exit(1);
+  }
+
   // Hook management
   if (hasFlag('--install-hook')) {
     const { installHook } = await import('../src/hook-manager.js');

package/package.json

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

package/src/formatters/statusline.js

@@ -19,6 +19,8 @@
 
 import { formatResetClock } from '../format-time.js';
 import { labelForKey } from '../window-labels.js';
+import { harnessStatusForStatusline } from '../harness.js';
+import { loadConfig } from '../config.js';
 
 // The 8-color ANSI defaults (RED=31, GREEN=32, YELLOW=33…) read as garish
 // next to each other — terminal palettes set them with unbalanced perceptual
@@ -268,6 +270,31 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   // Spike chip — one word only, keeps the statusline single-line.
   const spikeSeg = spikeChip ? `${c(RED)}${spikeChip}${c(RESET)}` : null;
 
+  // Harness 🅷 N/5 — project-scoped completeness of CLAUDE.md harness rules.
+  // Silent when the project hasn't opted in (no CLAUDE.md and no .claude/);
+  // otherwise renders 🅷 5/5 (green) / 🅷 N/5 (yellow) so the user can spot
+  // a missing section at a glance and know to run `harness init`.
+  let harnessSeg = null;
+  try {
+    const harnessInfo = harnessStatusForStatusline(loadConfig());
+    if (harnessInfo) {
+      const icon = isIcon ? '🅷' : 'H';
+      if (harnessInfo.warning) {
+        // Warning state outranks the N/5 count — a runtime issue (repeated
+        // error / no-evidence / racing edits) is more actionable than a
+        // missing ratchet section. Always red so it stands out.
+        harnessSeg = `${c(RED)}${icon}⚠ ${harnessInfo.warning}${c(RESET)}`;
+      } else {
+        const tone = harnessInfo.configured >= harnessInfo.total ? GREEN : YELLOW;
+        harnessSeg = `${c(tone)}${icon} ${harnessInfo.configured}/${harnessInfo.total}${c(RESET)}`;
+      }
+    }
+  } catch {
+    // Harness check is best-effort — never break the statusline if the file
+    // read fails (corrupted CLAUDE.md, permission issue, etc.).
+    harnessSeg = null;
+  }
+
   // Model chip — pulled from Claude Code's stdin payload (`model.display_name`).
   // Cheap identity context: useful when the user toggles between Sonnet/Opus
   // mid-session and wants to confirm at a glance which one is answering.
@@ -382,6 +409,7 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   const segs = [];
   if (capWarnSeg && want('cap-warn')) segs.push(capWarnSeg);
   if (spikeSeg && want('spike')) segs.push(spikeSeg);
+  if (harnessSeg && want('harness')) segs.push(harnessSeg);
   if (modelSeg && want('model')) segs.push(modelSeg);
   if (want('hit')) segs.push(hitSeg);
   if (want('ttl')) segs.push(ttlSeg);

package/src/harness-analyzer.cjs

@@ -0,0 +1,250 @@
+/**
+ * Harness analyzer — scans a session transcript JSONL for warning signals
+ * and writes a small state file the statusline can read cheaply.
+ *
+ * Three signals (precedence: ratchet? > no-evidence > PEV-skip):
+ *
+ * 1. Ratchet candidate — same is_error tool_use_result appears 2+ times in
+ *    the last 30 turns. Suggests the user codify a rule so it doesn't repeat.
+ *
+ * 2. Evidence rate — fraction of recent assistant messages that ship proof
+ *    (code blocks, tool_use_result, "test"/"output"/"diff"/"screenshot"
+ *    keywords). <30% → ⚠ no-evidence — high chance the model is reporting
+ *    "done" without showing it.
+ *
+ * 3. PEV-skip — many tool_use calls (5+) in the last 15 turns with no plan
+ *    signal (no TodoWrite, no "plan"/"Phase"/"단계" mention). Suggests the
+ *    model is racing through edits without a verify pass.
+ *
+ * CommonJS so hook.cjs can `require()` it without a bundler step.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const STATE_DIR = stateDir();
+const STATE_PATH = path.join(STATE_DIR, 'harness-state.json');
+
+const RECENT_TURNS = 15;        // PEV / evidence window
+const RATCHET_TURNS = 30;       // ratchet-candidate window
+const EVIDENCE_THRESHOLD = 0.3; // <30% → ⚠ no-evidence
+const PEV_TOOLUSE_THRESHOLD = 5;
+
+function stateDir() {
+  if (process.platform === 'win32') {
+    return path.join(process.env.APPDATA || os.homedir(), 'claude-token-saver');
+  }
+  if (process.platform === 'darwin') {
+    return path.join(os.homedir(), 'Library', 'Application Support', 'claude-token-saver');
+  }
+  const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(xdg, 'claude-token-saver');
+}
+
+function readJsonl(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+      // ignore corrupt line
+    }
+  }
+  return out;
+}
+
+/**
+ * Pull the text payload out of an assistant message, regardless of whether
+ * Claude Code stored it as a string, a content-block array, or a mix.
+ */
+function assistantText(msg) {
+  if (!msg) return '';
+  if (typeof msg.content === 'string') return msg.content;
+  if (Array.isArray(msg.content)) {
+    return msg.content
+      .map((b) => {
+        if (typeof b === 'string') return b;
+        if (b && b.type === 'text') return b.text || '';
+        return '';
+      })
+      .join('\n');
+  }
+  return '';
+}
+
+function toolUsesIn(msg) {
+  if (!msg || !Array.isArray(msg.content)) return [];
+  return msg.content.filter((b) => b && b.type === 'tool_use');
+}
+
+function toolResultsIn(msg) {
+  if (!msg || !Array.isArray(msg.content)) return [];
+  return msg.content.filter((b) => b && b.type === 'tool_result');
+}
+
+function looksLikeEvidence(text) {
+  if (!text) return false;
+  // Code block (``` …) is the cheapest evidence signal — almost always
+  // present when the assistant shows actual command output or a diff.
+  if (/```[\s\S]*?```/.test(text)) return true;
+  const lower = text.toLowerCase();
+  // Korean + English keywords. Order doesn't matter — first hit wins.
+  const evidenceWords = [
+    'stdout', 'output', 'diff', 'screenshot', 'passed', 'pytest', 'jest',
+    'test result', 'verified', 'verifying',
+    '출력', '결과', '스크린샷', '통과', '검증', '확인했', '확인됨',
+  ];
+  return evidenceWords.some((w) => lower.includes(w));
+}
+
+function looksLikePlanSignal(text, toolUses) {
+  if (toolUses.some((t) => /^todowrite$/i.test(t.name || ''))) return true;
+  if (!text) return false;
+  const lower = text.toLowerCase();
+  const planWords = ['plan', 'phase', 'step 1', 'step1', 'first,', 'next,',
+    '단계', '계획', '먼저', '다음으로', '순서대로'];
+  return planWords.some((w) => lower.includes(w));
+}
+
+function errorSignature(toolResult) {
+  if (!toolResult || toolResult.is_error !== true) return null;
+  const c = toolResult.content;
+  let txt = '';
+  if (typeof c === 'string') txt = c;
+  else if (Array.isArray(c)) {
+    txt = c.map((b) => (b && typeof b.text === 'string' ? b.text : '')).join(' ');
+  }
+  txt = txt.replace(/\s+/g, ' ').trim();
+  if (!txt) return null;
+  // First 80 chars is enough to dedupe most repeated errors without overfitting
+  // to volatile bits like timestamps or pids.
+  return txt.slice(0, 80);
+}
+
+/**
+ * Walk the last `RATCHET_TURNS` turns and surface error signatures that
+ * appear 2+ times. Returns the top candidate (or null).
+ */
+function findRatchetCandidates(entries) {
+  const counts = new Map();
+  const recent = entries.slice(-RATCHET_TURNS);
+  for (const e of recent) {
+    const msg = e && e.message;
+    if (!msg) continue;
+    for (const tr of toolResultsIn(msg)) {
+      const sig = errorSignature(tr);
+      if (!sig) continue;
+      const cur = counts.get(sig) || { count: 0, lastAt: e.timestamp };
+      cur.count += 1;
+      cur.lastAt = e.timestamp || cur.lastAt;
+      counts.set(sig, cur);
+    }
+  }
+  const list = [];
+  for (const [sig, info] of counts.entries()) {
+    if (info.count < 2) continue;
+    list.push({ pattern: sig, count: info.count, lastAt: info.lastAt });
+  }
+  // Top 5 by count, ID assigned in rank order so `harness promote 1` always
+  // targets the most-repeated error — stable even as new candidates appear.
+  list.sort((a, b) => b.count - a.count);
+  return list.slice(0, 5).map((c, i) => ({ id: i + 1, ...c }));
+}
+
+/**
+ * Evidence rate — over the last RECENT_TURNS *assistant* messages, the
+ * fraction that ship proof (code block / keywords). Tool_result blocks in
+ * the immediate next user message also count as "shown the work."
+ */
+function computeEvidenceRate(entries) {
+  const recent = entries.slice(-RECENT_TURNS * 2); // both user/assistant
+  const assistants = [];
+  for (let i = 0; i < recent.length; i++) {
+    const e = recent[i];
+    if (e && e.type === 'assistant') {
+      const text = assistantText(e.message);
+      let proof = looksLikeEvidence(text);
+      // If the *next* entry is a user message with tool_result blocks, count
+      // that as evidence for the assistant turn that triggered it.
+      const next = recent[i + 1];
+      if (!proof && next && next.type === 'user' && toolResultsIn(next.message).length > 0) {
+        proof = true;
+      }
+      assistants.push(proof);
+    }
+  }
+  if (assistants.length === 0) return null;
+  const proofCount = assistants.filter(Boolean).length;
+  return proofCount / assistants.length;
+}
+
+function computePevSkip(entries) {
+  const recent = entries.slice(-RECENT_TURNS);
+  let toolUseCount = 0;
+  let planSignal = false;
+  for (const e of recent) {
+    if (!e || e.type !== 'assistant') continue;
+    const text = assistantText(e.message);
+    const tus = toolUsesIn(e.message);
+    toolUseCount += tus.length;
+    if (looksLikePlanSignal(text, tus)) planSignal = true;
+  }
+  return toolUseCount >= PEV_TOOLUSE_THRESHOLD && !planSignal;
+}
+
+function analyzeTranscript(transcriptPath, opts) {
+  opts = opts || {};
+  const entries = readJsonl(transcriptPath);
+  if (entries.length === 0) return null;
+  const evidenceRate = computeEvidenceRate(entries);
+  const pevSkip = computePevSkip(entries);
+  const ratchetCandidates = findRatchetCandidates(entries);
+  return {
+    sessionId: opts.sessionId || null,
+    cwd: opts.cwd || null,
+    transcriptPath: transcriptPath,
+    timestamp: new Date().toISOString(),
+    evidenceRate: evidenceRate,
+    evidenceLow: evidenceRate !== null && evidenceRate < EVIDENCE_THRESHOLD,
+    pevSkip: pevSkip,
+    ratchetCandidate: ratchetCandidates[0] || null, // back-compat
+    ratchetCandidates: ratchetCandidates,
+  };
+}
+
+function writeState(state) {
+  if (!state) return;
+  try {
+    if (!fs.existsSync(STATE_DIR)) fs.mkdirSync(STATE_DIR, { recursive: true });
+    fs.writeFileSync(STATE_PATH, JSON.stringify(state, null, 2) + '\n');
+  } catch {
+    // best-effort
+  }
+}
+
+function readState() {
+  try {
+    if (!fs.existsSync(STATE_PATH)) return null;
+    return JSON.parse(fs.readFileSync(STATE_PATH, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  analyzeTranscript,
+  writeState,
+  readState,
+  STATE_PATH,
+  EVIDENCE_THRESHOLD,
+};

package/src/harness-templates.js

@@ -0,0 +1,103 @@
+/**
+ * Harness templates — single-file CLAUDE.md (5 sections) + ratchet.md.
+ *
+ * Section markers (HARNESS_SECTIONS) are the source of truth for completeness
+ * detection: harness/check counts how many of these headers appear in the
+ * project's CLAUDE.md, and the statusline 🅷 N/5 indicator reports the same.
+ */
+
+export const HARNESS_BLOCK_BEGIN = '<!-- claude-token-saver:harness:begin -->';
+export const HARNESS_BLOCK_END = '<!-- claude-token-saver:harness:end -->';
+
+export const HARNESS_SECTIONS = [
+  { id: 'ratchet', heading: '### 1. Ratchet — 같은 실수는 두 번 안 한다' },
+  { id: 'evidence', heading: '### 2. Evidence — "다 됐어요" 금지' },
+  { id: 'pev', heading: '### 3. PEV — Plan → Execute → Verify' },
+  { id: 'structured', heading: '### 4. Structured Task — 입력 구조화' },
+  { id: 'safe-path', heading: '### 5. Default Safe Path — 파괴적 명령 항상 확인' },
+];
+
+export function harnessClaudeMdBlock() {
+  const sections = HARNESS_SECTIONS.map((s) => s.heading).join('\n\n... (see full block below)');
+  return `${HARNESS_BLOCK_BEGIN}
+## 🅷 Harness Rules (claude-token-saver)
+
+이 섹션은 \`claude-token-saver harness init\`이 생성합니다. 5가지 원칙 모두를
+지키면 statusline에 \`🅷 5/5\`로 표시되고, 빠진 게 있으면 \`🅷 3/5\` 식으로
+경고합니다. 수정해도 무방하지만, 섹션 헤더(### 1. ~ ### 5.)는 검출용이므로
+지우지 마세요.
+
+${HARNESS_SECTIONS[0].heading}
+- 같은 에러·오해·반복 작업이 한 번 더 발생하면 즉시 \`.claude/ratchet.md\`에
+  "조건 → 행동" 한 줄로 룰 추가.
+- claude-token-saver가 후보를 감지하면 statusline에 \`🅷⚠ ratchet?\`로 알림.
+  \`claude-token-saver harness promote "<rule>"\`로 승인.
+- 승인된 룰은 다음 세션부터 자동 적용.
+
+${HARNESS_SECTIONS[1].heading}
+완료 보고("다 됐어요", "테스트 통과") 시 다음 중 1개 이상을 항상 첨부:
+- 테스트 실행 결과 (실제 stdout)
+- 변경 파일 diff (file:line)
+- UI 작업이면 스크린샷
+- 명령 실행 출력
+
+증거 없는 완료 보고는 거짓일 확률이 매우 높음. 토큰 낭비의 주범.
+
+${HARNESS_SECTIONS[2].heading}
+3단계 이상 작업은 다음 사이클을 강제:
+1. **Plan** — 텍스트로 단계 명시 (TodoWrite 권장)
+2. **Execute** — 한 단계씩 실행, 결과 확인
+3. **Verify** — 테스트·실행·grep 등으로 결과 검증
+
+Verify를 건너뛰면 statusline에 \`🅷⚠ PEV-skip\` 표시.
+0.85의 10제곱 ≈ 0.20 — 단계당 85%만 맞아도 10단계면 80% 실패.
+
+${HARNESS_SECTIONS[3].heading}
+새 작업 시작 시 다음 4줄을 먼저 채울 것 (입력이 구조화돼야 출력도 구조화됨):
+- **목표:** 한 문장으로
+- **제약:** 시간·범위·금지사항
+- **검증 방법:** 어떻게 "됐다"고 판정할지
+- **완료 기준:** 무엇이 통과하면 완료인지
+
+${HARNESS_SECTIONS[4].heading}
+다음 작업은 **항상** 사용자 확인 후 실행:
+- 파괴적 명령: \`rm -rf\`, force push, drop table, kill process
+- 외부 시스템: deploy, slack 발송, 댓글 작성, PR merge
+- 비가역적: amend pushed commit, branch -D
+
+단순 read·local edit·테스트 실행은 묻지 말고 즉시 진행 (마찰 최소화).
+
+---
+
+📌 운영:
+- \`claude-token-saver harness check\` — 현재 셋업 점수
+- \`claude-token-saver harness promote "<룰>"\` — ratchet에 룰 추가
+- \`claude-token-saver harness off\` — statusline 표시 끄기
+${HARNESS_BLOCK_END}
+`;
+}
+
+export function harnessRatchetMdInitial() {
+  return `# Ratchet Rules (auto-grown by claude-token-saver)
+
+같은 실수가 두 번 발생하면 여기에 한 줄 추가됩니다. 형식: "YYYY-MM-DD: <조건> → <행동>".
+
+\`claude-token-saver harness promote "<rule>"\`로 룰을 추가하면 자동으로
+이 파일에 append 됩니다.
+
+## Rules
+
+`;
+}
+
+/**
+ * Append a rule to ratchet.md content. Safe to call on the initial template
+ * or on a user-edited file: we just add to the end. Rules are dated.
+ */
+export function appendRatchetRule(existing, ruleText) {
+  const today = new Date().toISOString().slice(0, 10);
+  const line = `- ${today}: ${ruleText.trim()}\n`;
+  // Ensure trailing newline so the new rule lands on its own line.
+  const base = existing.endsWith('\n') ? existing : existing + '\n';
+  return base + line;
+}

package/src/harness.js

@@ -0,0 +1,206 @@
+/**
+ * Harness module — manages CLAUDE.md (single file, 5 sections), ratchet.md,
+ * and reports completeness for the statusline 🅷 N/5 indicator.
+ *
+ * Detection is project-scoped: we look at the current working directory's
+ * CLAUDE.md (or the nearest one walking up to the git root). Statusline calls
+ * harnessStatus() per render — keep it cheap (read + regex, no parsing).
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { createRequire } from 'node:module';
+import {
+  HARNESS_SECTIONS,
+  HARNESS_BLOCK_BEGIN,
+  HARNESS_BLOCK_END,
+  harnessClaudeMdBlock,
+  harnessRatchetMdInitial,
+  appendRatchetRule,
+} from './harness-templates.js';
+
+const require = createRequire(import.meta.url);
+function readHarnessState() {
+  try {
+    const a = require('./harness-analyzer.cjs');
+    return a.readState();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Walk up from `start` looking for a project root marker (CLAUDE.md, .git,
+ * or package.json). Falls back to `start` itself so harness commands always
+ * have *some* directory to write into, even outside a repo.
+ */
+export function findProjectRoot(start = process.cwd()) {
+  let dir = resolve(start);
+  for (;;) {
+    if (
+      existsSync(join(dir, 'CLAUDE.md')) ||
+      existsSync(join(dir, '.git')) ||
+      existsSync(join(dir, 'package.json'))
+    ) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return resolve(start);
+    dir = parent;
+  }
+}
+
+function claudeMdPath(root) {
+  return join(root, 'CLAUDE.md');
+}
+
+function ratchetMdPath(root) {
+  return join(root, '.claude', 'ratchet.md');
+}
+
+/**
+ * Count how many of the 5 harness sections appear in the project's CLAUDE.md.
+ * Returns { configured, total, missing, hasBlock }. Cheap enough to call from
+ * statusline — single file read + regex.
+ */
+export function harnessStatus(root = findProjectRoot()) {
+  const path = claudeMdPath(root);
+  if (!existsSync(path)) {
+    return {
+      configured: 0,
+      total: HARNESS_SECTIONS.length,
+      missing: HARNESS_SECTIONS.map((s) => s.id),
+      hasBlock: false,
+      hasFile: false,
+      root,
+    };
+  }
+  let content = '';
+  try {
+    content = readFileSync(path, 'utf8');
+  } catch {
+    return { configured: 0, total: HARNESS_SECTIONS.length, missing: [], hasBlock: false, hasFile: true, root };
+  }
+  const hasBlock = content.includes(HARNESS_BLOCK_BEGIN);
+  const present = [];
+  const missing = [];
+  for (const s of HARNESS_SECTIONS) {
+    if (content.includes(s.heading)) present.push(s.id);
+    else missing.push(s.id);
+  }
+  return {
+    configured: present.length,
+    total: HARNESS_SECTIONS.length,
+    missing,
+    hasBlock,
+    hasFile: true,
+    root,
+  };
+}
+
+/**
+ * harness init — write CLAUDE.md (single file, 5 sections) + .claude/ratchet.md.
+ * If CLAUDE.md exists, back it up to CLAUDE.md.bak-YYYYMMDD-HHMMSS first
+ * (per user-confirmed design: backup, then overwrite with the harness block).
+ *
+ * Returns { wrote: [], backedUp: [], skipped: [] } so the CLI can report.
+ */
+export function harnessInit({ root = findProjectRoot(), force = false } = {}) {
+  const cmPath = claudeMdPath(root);
+  const rmPath = ratchetMdPath(root);
+  const result = { wrote: [], backedUp: [], skipped: [], root };
+
+  // CLAUDE.md
+  const block = harnessClaudeMdBlock();
+  if (existsSync(cmPath)) {
+    const existing = readFileSync(cmPath, 'utf8');
+    if (existing.includes(HARNESS_BLOCK_BEGIN) && !force) {
+      // Already has a harness block — replace it in-place, preserving the
+      // user's other content above/below.
+      const re = new RegExp(
+        `${escapeRe(HARNESS_BLOCK_BEGIN)}[\\s\\S]*?${escapeRe(HARNESS_BLOCK_END)}\\n?`,
+        'm',
+      );
+      const next = existing.replace(re, block);
+      writeFileSync(cmPath, next);
+      result.wrote.push(cmPath + ' (block updated in place)');
+    } else {
+      // Backup, then overwrite with the harness block. User-confirmed design:
+      // single CLAUDE.md, backup-then-overwrite (not append) so a clean reset
+      // is always one command away.
+      const stamp = new Date().toISOString().replace(/[:.]/g, '').slice(0, 15); // YYYYMMDDTHHMMSS
+      const bak = `${cmPath}.bak-${stamp}`;
+      writeFileSync(bak, existing);
+      writeFileSync(cmPath, block);
+      result.backedUp.push(bak);
+      result.wrote.push(cmPath);
+    }
+  } else {
+    writeFileSync(cmPath, block);
+    result.wrote.push(cmPath);
+  }
+
+  // .claude/ratchet.md (only if missing — don't clobber user-grown rules)
+  if (!existsSync(rmPath)) {
+    mkdirSync(dirname(rmPath), { recursive: true });
+    writeFileSync(rmPath, harnessRatchetMdInitial());
+    result.wrote.push(rmPath);
+  } else {
+    result.skipped.push(rmPath + ' (already exists)');
+  }
+
+  return result;
+}
+
+/**
+ * harness promote — append a one-line rule to .claude/ratchet.md.
+ * Creates the file from the initial template if missing.
+ */
+export function harnessPromote(ruleText, { root = findProjectRoot() } = {}) {
+  const rmPath = ratchetMdPath(root);
+  let existing = '';
+  if (existsSync(rmPath)) {
+    existing = readFileSync(rmPath, 'utf8');
+  } else {
+    mkdirSync(dirname(rmPath), { recursive: true });
+    existing = harnessRatchetMdInitial();
+  }
+  const next = appendRatchetRule(existing, ruleText);
+  writeFileSync(rmPath, next);
+  return { path: rmPath, root };
+}
+
+/**
+ * Statusline segment shape for the 🅷 indicator. Returns null when the user
+ * has explicitly disabled harness display, or when there's no CLAUDE.md and
+ * no .claude/ at all (silent in non-init'd projects so we don't nag).
+ */
+export function harnessStatusForStatusline(cfg, { root } = {}) {
+  if (cfg && cfg.harness && cfg.harness.enabled === false) return null;
+  const projectRoot = root || findProjectRoot();
+  const status = harnessStatus(projectRoot);
+  // Silent when the project has neither CLAUDE.md nor a .claude/ dir — the
+  // user hasn't opted in, no point nagging.
+  if (!status.hasFile && !existsSync(join(projectRoot, '.claude'))) return null;
+  // Attach a warning derived from the analyzer state file (if any). Precedence:
+  //   ratchet? > no-evidence > PEV-skip. Only surfaces when the state's
+  //   sessionId or cwd matches this project, so unrelated sessions don't leak.
+  const state = readHarnessState();
+  let warning = null;
+  if (state) {
+    const matches = (state.cwd && state.cwd === projectRoot) || !state.cwd;
+    if (matches) {
+      if (state.ratchetCandidate && state.ratchetCandidate.count >= 2) {
+        const id = state.ratchetCandidate.id || 1;
+        warning = `ratchet? #${id}`;
+      }
+      else if (state.evidenceLow) warning = 'no-evidence';
+      else if (state.pevSkip) warning = 'PEV-skip';
+    }
+  }
+  return { ...status, warning };
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/hook.cjs

@@ -168,3 +168,17 @@ if (hitRate < threshold && requests.size >= 5) {
     '\u26a0 Cache hit rate: ' + pct + '% (threshold: ' + (threshold * 100).toFixed(0) + '%) | 5m TTL: ' + pct5m + '% | ' + requests.size + ' API calls\n',
   );
 }
+
+// Harness analysis \u2014 best-effort, never throws into the hook stream. The
+// statusline picks up the resulting state file (`harness-state.json`) on
+// the next render, so warnings appear within ~1s of the triggering turn.
+try {
+  var harnessAnalyzer = require('./harness-analyzer.cjs');
+  var state = harnessAnalyzer.analyzeTranscript(sessionFile, {
+    sessionId: sessionId,
+    cwd: cwd,
+  });
+  if (state) harnessAnalyzer.writeState(state);
+} catch (_) {
+  // analyzer is purely advisory \u2014 never break the hook on failure
+}