claude-token-saver 2.10.1 → 2.11.0

package/README.md

@@ -134,6 +134,31 @@ claude-token-saver mode       # 현재 설정 확인
 
 전체 옵션은 `--help` 또는 [영문 README](./README.en.md#options).
 
+## 🅷 Harness 모드
+
+다섯 가지 원칙(Ratchet, Evidence, PEV, Structured Task, Default Safe Path)을 한 줄 명령으로 `CLAUDE.md`에 셋업하고, statusline에 `🅷 5/5`로 점수화합니다. 같은 에러가 반복되면 `🅷⚠ ratchet?`로 알림이 뜹니다.
+
+```bash
+claude-token-saver harness init                # CLAUDE.md(5섹션) + .claude/ratchet.md
+claude-token-saver harness check               # 현재 점수
+claude-token-saver harness promote <N>         # statusline 경고 #N → ratchet에 한 줄 등록
+claude-token-saver harness list                # 등록된 ratchet 룰 번호 매겨 보기
+claude-token-saver harness rm <N>              # 룰 삭제 (자동 .bak 백업)
+claude-token-saver harness uninit              # harness 블록 제거 (CLAUDE.md 다른 내용은 보존)
+claude-token-saver harness off | on            # statusline 🅷 표시 토글
+```
+
+### ⚠️ 주의 — `harness rm`은 신중하게
+
+ratchet의 가치는 **"한 방향 누적"**에 있습니다. 룰을 가볍게 지우기 시작하면 같은 실수가 다시 새기 시작합니다. **지우기 전에 다음을 확인하세요**:
+
+- **룰이 너무 광범위해서 정상 케이스도 막나?** → ❌ 삭제 ✅ **조건을 좁혀서 다듬기**
+  - 예: `"하드코딩 금지"` → `"테스트 외 코드에서 하드코딩 금지"`
+- **룰이 너무 좁아 거의 발동 안 되나?** → ❌ 삭제 ✅ **그냥 두기** (비용 0)
+- **정말 잘못된 룰이라 확신?** → ✅ **그때만 삭제**
+
+대부분의 "과도한 ratchet" 문제는 **룰의 표현이 좁지 못해서** 생깁니다. 삭제는 마지막 수단으로 두고, 먼저 `.claude/ratchet.md`를 직접 열어 조건을 다듬는 쪽을 우선하세요. 삭제 시 자동 `.bak`이 남지만, **세션 컨텍스트(왜 그 룰이 박혔는지)는 백업으로 복원되지 않습니다**.
+
 ## 토큰 급증 원인 코드
 
 | 코드 | 의미 |
@@ -169,6 +194,9 @@ Node.js ≥ 18 · macOS / Linux / Windows / WSL · 의존성 0.
 
 ## 릴리스 노트
 
+### v2.11.0 (2026-05-02)
+- `harness list` / `harness rm <N>` 추가. 등록된 ratchet 룰을 번호로 보고 개별 삭제 가능 (자동 `.bak` 백업). 삭제 전 "조건을 좁혀서 다듬기" 우선 검토 안내가 CLI에 표시됩니다. README의 [⚠️ 주의 — `harness rm`은 신중하게](#️-주의--harness-rm은-신중하게) 항목 참고.
+
 ### v2.9.4 (2026-04-27)
 - README에 Node.js 사전 설치 안내 추가 (macOS/Windows/Linux별). GitHub에서 처음 본 사용자가 npm 명령부터 막히는 일을 방지. sudo 글로벌 설치 시 postinstall이 root 홈에 SKILL을 만드는 함정도 함께 안내.
 

package/bin/cli.js

@@ -446,12 +446,13 @@ async function main() {
 
   // 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 off | on   # toggle the statusline 🅷 segment
   if (args[0] === 'harness') {
     const sub = args[1];
-    const { harnessInit, harnessStatus, harnessPromote, findProjectRoot } =
+    const { harnessInit, harnessUninit, harnessStatus, harnessPromote, harnessListRules, harnessRmRule, findProjectRoot } =
       await import('../src/harness.js');
     const { HARNESS_SECTIONS } = await import('../src/harness-templates.js');
     const { loadConfig, saveConfig } = await import('../src/config.js');
@@ -557,6 +558,61 @@ async function main() {
       return;
     }
 
+    if (sub === 'uninit' || sub === 'remove') {
+      const purgeRatchet = args.includes('--purge-ratchet');
+      const r = harnessUninit({ purgeRatchet });
+      console.log(`Project root: ${r.root}`);
+      r.removed.forEach((f) => console.log(`  removed: ${f}`));
+      r.backedUp.forEach((f) => console.log(`  backup:  ${f}`));
+      r.skipped.forEach((f) => console.log(`  skip:    ${f}`));
+      if (r.removed.length === 0) console.log('Nothing to remove.');
+      return;
+    }
+
+    if (sub === 'list' || sub === 'ls') {
+      const { path, rules } = harnessListRules();
+      if (!rules.length) {
+        console.log(`No ratchet rules in ${path}`);
+        return;
+      }
+      console.log(`📋 Ratchet rules — ${path}\n`);
+      for (const r of rules) console.log(`  #${r.index}  ${r.text}`);
+      console.log('\nRemove with: claude-token-saver harness rm <N>');
+      return;
+    }
+
+    if (sub === 'rm') {
+      const raw = (args[2] || '').trim();
+      if (!/^\d+$/.test(raw)) {
+        console.error('Usage: claude-token-saver harness rm <N>   # N from `harness list`');
+        process.exit(1);
+      }
+      const n = parseInt(raw, 10);
+      // ⚠️ Heads-up before deletion. Ratchet's value is one-way accumulation —
+      // dropping a rule is sometimes right, but more often the rule is just
+      // too narrow. Surface the alternative loudly here.
+      console.log('⚠️  주의: ratchet 룰 삭제는 신중하게.');
+      console.log('   같은 실수가 또 발생할 가능성이 큽니다. 보통은 "조건이 너무 좁아서"');
+      console.log('   문제가 되는 경우가 많아요. 지우기 전에 한 번 더 검토하세요:');
+      console.log('   - 룰이 너무 광범위해서 정상 케이스도 막나? → 조건을 좁혀서 다듬기');
+      console.log('   - 룰이 너무 좁아서 거의 발동 안 되나? → 그냥 두기 (비용 0)');
+      console.log('   - 정말 잘못된 룰이라 확신? → 그때만 삭제');
+      console.log('');
+      const r = harnessRmRule(n);
+      if (!r.ok) {
+        console.error(`❌ ${r.error}`);
+        if (r.rules) {
+          console.error('Available:');
+          for (const x of r.rules) console.error(`  #${x.index}  ${x.text}`);
+        }
+        process.exit(1);
+      }
+      console.log(`✅ Removed #${n}: ${r.removed.text}`);
+      console.log(`   Backup: ${r.backup}`);
+      console.log(`   복구: cp "${r.backup}" "${r.path}"`);
+      return;
+    }
+
     if (sub === 'off' || sub === 'on') {
       const cfg = loadConfig();
       cfg.harness = cfg.harness || {};
@@ -567,7 +623,7 @@ async function main() {
     }
 
     console.error(`Unknown harness subcommand: ${sub}`);
-    console.error('Usage: claude-token-saver harness [check|init|promote "<rule>"|off|on]');
+    console.error('Usage: claude-token-saver harness [check|init|uninit [--purge-ratchet]|promote "<rule>"|list|rm <N>|off|on]');
     process.exit(1);
   }
 

package/package.json

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

package/src/harness.js

@@ -154,6 +154,54 @@ export function harnessInit({ root = findProjectRoot(), force = false } = {}) {
   return result;
 }
 
+/**
+ * harness uninit — remove the harness block from CLAUDE.md (preserves the
+ * user's other content). A safety backup is written first. ratchet.md is
+ * left intact (user-grown rules) unless `purgeRatchet` is true.
+ *
+ * Returns { removed: [], backedUp: [], skipped: [] }.
+ */
+export function harnessUninit({ root = findProjectRoot(), purgeRatchet = false } = {}) {
+  const cmPath = claudeMdPath(root);
+  const rmPath = ratchetMdPath(root);
+  const result = { removed: [], backedUp: [], skipped: [], root };
+
+  if (existsSync(cmPath)) {
+    const existing = readFileSync(cmPath, 'utf8');
+    if (existing.includes(HARNESS_BLOCK_BEGIN)) {
+      const stamp = new Date().toISOString().replace(/[:.]/g, '').slice(0, 15);
+      const bak = `${cmPath}.bak-${stamp}`;
+      writeFileSync(bak, existing);
+      const re = new RegExp(
+        `\\n*${escapeRe(HARNESS_BLOCK_BEGIN)}[\\s\\S]*?${escapeRe(HARNESS_BLOCK_END)}\\n?`,
+        'm',
+      );
+      const next = existing.replace(re, '').replace(/\n{3,}$/, '\n\n');
+      writeFileSync(cmPath, next);
+      result.backedUp.push(bak);
+      result.removed.push(cmPath + ' (harness block removed)');
+    } else {
+      result.skipped.push(cmPath + ' (no harness block found)');
+    }
+  } else {
+    result.skipped.push(cmPath + ' (does not exist)');
+  }
+
+  if (purgeRatchet && existsSync(rmPath)) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '').slice(0, 15);
+    const bak = `${rmPath}.bak-${stamp}`;
+    writeFileSync(bak, readFileSync(rmPath, 'utf8'));
+    result.backedUp.push(bak);
+    // Replace with empty initial template rather than delete (preserves dir).
+    writeFileSync(rmPath, harnessRatchetMdInitial());
+    result.removed.push(rmPath + ' (reset to initial)');
+  } else if (existsSync(rmPath)) {
+    result.skipped.push(rmPath + ' (kept; pass --purge-ratchet to reset)');
+  }
+
+  return result;
+}
+
 /**
  * harness promote — append a one-line rule to .claude/ratchet.md.
  * Creates the file from the initial template if missing.
@@ -172,6 +220,52 @@ export function harnessPromote(ruleText, { root = findProjectRoot() } = {}) {
   return { path: rmPath, root };
 }
 
+/**
+ * harness list — return numbered ratchet rules from .claude/ratchet.md.
+ * Numbering is 1-based and matches `harness rm <N>`.
+ */
+export function harnessListRules({ root = findProjectRoot() } = {}) {
+  const rmPath = ratchetMdPath(root);
+  if (!existsSync(rmPath)) return { path: rmPath, rules: [] };
+  const lines = readFileSync(rmPath, 'utf8').split('\n');
+  const rules = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    // A "rule line" starts with "- " (markdown bullet). Header lines, blanks,
+    // and the "## Rules" anchor are ignored.
+    if (/^\s*-\s+/.test(line)) {
+      rules.push({ index: rules.length + 1, lineNo: i, text: line.replace(/^\s*-\s+/, '') });
+    }
+  }
+  return { path: rmPath, rules };
+}
+
+/**
+ * harness rm — remove a ratchet rule by its 1-based index. Writes a `.bak`
+ * before mutating so the user can recover. Returns the removed rule for the
+ * CLI to echo back.
+ *
+ * NOTE: Removal is intentionally a separate verb from `promote`. Ratchet's
+ * value is one-way accumulation; deleting should feel deliberate. The CLI
+ * surfaces a "narrow the condition instead" reminder around this call.
+ */
+export function harnessRmRule(n, { root = findProjectRoot() } = {}) {
+  const { path: rmPath, rules } = harnessListRules({ root });
+  if (!existsSync(rmPath)) {
+    return { ok: false, error: `ratchet.md not found at ${rmPath}` };
+  }
+  const target = rules.find((r) => r.index === n);
+  if (!target) {
+    return { ok: false, error: `No rule #${n} (have ${rules.length})`, rules };
+  }
+  const content = readFileSync(rmPath, 'utf8');
+  writeFileSync(rmPath + '.bak', content);
+  const lines = content.split('\n');
+  lines.splice(target.lineNo, 1);
+  writeFileSync(rmPath, lines.join('\n'));
+  return { ok: true, path: rmPath, backup: rmPath + '.bak', removed: target };
+}
+
 /**
  * Statusline segment shape for the 🅷 indicator. Returns null when the user
  * has explicitly disabled harness display, or when there's no CLAUDE.md and