sprag-cli 3.40.0

package/src/harness-analyzer.cjs

@@ -0,0 +1,264 @@
+/**
+ * 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 *mutating* tool_use calls (Edit/Write/Bash…, 5+) in the
+ *    last 15 assistant turns with no plan signal (no TodoWrite, no
+ *    "plan"/"Phase"/"단계" mention). Suggests the model is racing through
+ *    edits without a verify pass. Read-only exploration (Read/Grep/Glob)
+ *    deliberately doesn't count — reading five files is research, not racing.
+ *
+ * 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 (assistant turns)
+const RATCHET_TURNS = 30;       // ratchet-candidate window
+const EVIDENCE_THRESHOLD = 0.3; // <30% → ⚠ no-evidence
+const PEV_TOOLUSE_THRESHOLD = 5;
+// Tools that change state. Only these count toward PEV-skip — an agentic
+// session trivially racks up 5+ *read* tool calls (Read/Grep/Glob) while
+// researching, which is exactly the behavior we don't want to punish.
+const MUTATING_TOOL_RE = /^(edit|write|multiedit|notebookedit|bash)$/i;
+
+// Mirrors src/paths.js userDataDir() exactly (same order as doc2md.cjs).
+// Duplicated because this file is CommonJS and paths.js is ESM; the
+// precedence must match or state lands where the rest of the tool won't look.
+function stateDir() {
+  if (process.env.XDG_CONFIG_HOME) {
+    return path.join(process.env.XDG_CONFIG_HOME, 'claude-token-saver');
+  }
+  if (process.platform === 'win32' && process.env.APPDATA) {
+    return path.join(process.env.APPDATA, 'claude-token-saver');
+  }
+  if (process.platform === 'darwin') {
+    return path.join(os.homedir(), 'Library', 'Application Support', 'claude-token-saver');
+  }
+  return path.join(os.homedir(), '.config', '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) {
+  // Window by *assistant turns*, not raw JSONL entries — one agentic turn can
+  // span dozens of entries, so an entry-sliced window covered only 1-2 real
+  // turns and made the rate jumpy.
+  const idxs = [];
+  for (let i = 0; i < entries.length; i++) {
+    if (entries[i] && entries[i].type === 'assistant') idxs.push(i);
+  }
+  const recentIdxs = idxs.slice(-RECENT_TURNS);
+  if (recentIdxs.length === 0) return null;
+  let proofCount = 0;
+  for (const i of recentIdxs) {
+    const text = assistantText(entries[i].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 = entries[i + 1];
+    if (!proof && next && next.type === 'user' && toolResultsIn(next.message).length > 0) {
+      proof = true;
+    }
+    if (proof) proofCount++;
+  }
+  return proofCount / recentIdxs.length;
+}
+
+function computePevSkip(entries) {
+  const assistants = entries.filter((e) => e && e.type === 'assistant');
+  const recent = assistants.slice(-RECENT_TURNS);
+  let mutatingCount = 0;
+  let planSignal = false;
+  for (const e of recent) {
+    const text = assistantText(e.message);
+    const tus = toolUsesIn(e.message);
+    mutatingCount += tus.filter((t) => MUTATING_TOOL_RE.test(t.name || '')).length;
+    if (looksLikePlanSignal(text, tus)) planSignal = true;
+  }
+  return mutatingCount >= 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,153 @@
+/**
+ * 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 — 파괴적 명령 항상 확인' },
+];
+
+/**
+ * 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)
+
+이 섹션은 \`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>" --project|--global\`로 승인.
+- **scope는 항상 사용자에게 먼저 물어볼 것** — 프로젝트 한정이면 \`--project\`,
+  도구·환경 일반 룰이면 \`--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가 로그 기반으로 자동
+  생성·갱신하므로 직접 수정하지 말 것 (관리: \`route-scan rules\`).
+
+${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 "<룰>" --project|--global\` — ratchet에 룰 추가 (scope는 사용자에게 먼저 물어볼 것)
+- \`claude-token-saver harness off\` — statusline 표시 끄기
+
+---
+
+📥 ratchet 룰 로드 (이 줄들을 지우면 룰이 적용되지 않습니다):
+
+${ratchetImportLine(scope)}
+${modelRatchetImportLine(scope)}
+${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 됩니다.
+
+이 파일은 CLAUDE.md의 \`@\` import로 매 세션 로드됩니다 — 즉 여기 있는 모든 줄이
+매 요청마다 토큰을 씁니다. 날짜 뒤에 \`[태그]\`를 붙여두면 나중에 묶어서 정리할 수
+있습니다: \`- 2026-05-08: [video,tts] ...\` →
+\`claude-token-saver harness prune --tag video\` (삭제 아니라 ratchet-archive.md로 이동).
+
+## 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;
+}