therookie 0.4.3

package/src/lib/context-diet.js

@@ -0,0 +1,628 @@
+import {
+  readFileSync,
+  readdirSync,
+  statSync,
+  existsSync,
+  writeFileSync,
+  openSync,
+  readSync,
+  closeSync,
+} from 'node:fs'
+import { homedir } from 'node:os'
+import { join, dirname, resolve, basename } from 'node:path'
+
+// spec 2026-07-10-context-diet-design.md — 모든 지표는 "실제 토큰 주입량"이 아니라
+// 설치 자산 기준 proxy 다(§1). 판정 목적은 정확한 토큰 수가 아니라 "정리할 가치가 있는
+// 비대 자산" 탐지.
+export const THRESHOLDS = {
+  claude_md_project: 20000,
+  claude_md_total: 40000,
+  skills_agents_desc: 30000,
+  rookie_self_skill: 15000,
+  rookie_self_injected: 10000,
+  unused_skills_min: 5,
+}
+export const USAGE_WINDOW_DAYS = 60
+export const USAGE_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
+export const NEW_SKILL_GRACE_MS = 30 * 24 * 60 * 60 * 1000
+export const INJECTION_STALE_MS = 30 * 24 * 60 * 60 * 1000
+
+// Claude Code 메모리 로딩 파일명 (§2.1 fixture 고정, codex 2차 P2).
+// CLAUDE.local.md: 공식 문서상 deprecated 이지만 여전히 자동 로드된다(2026-07 기준
+// memory 문서 — imports 로의 이전 권고일 뿐 로딩은 유지). proxy 측정이므로 포함.
+export const MEMORY_FILE_PATTERNS = ['CLAUDE.md', 'CLAUDE.local.md', join('.claude', 'CLAUDE.md')]
+export const IMPORT_MAX_DEPTH = 3
+
+export function usageCachePath(home) {
+  return join(home, '.rookie', 'context-diet-usage.json')
+}
+export function snoozePath(home) {
+  return join(home, '.rookie', 'context-diet-snooze.json')
+}
+export function keepPath(home) {
+  return join(home, '.rookie', 'context-diet-keep.json')
+}
+export function throttleMarkerPath(home) {
+  return join(home, '.rookie', 'context-diet.last')
+}
+export function lastInjectionPath(home) {
+  return join(home, '.rookie', 'last-injection.json')
+}
+
+function readTextSafe(p) {
+  try {
+    return readFileSync(p, 'utf8')
+  } catch {
+    return null
+  }
+}
+function readJsonSafe(p) {
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+// ---------------------------------------------------------------------------
+// frontmatter 서브셋 파서 (§2.1) — YAML 전체가 아닌 서브셋만:
+//   description: 단일라인 / 인용부호 / block scalar(|, >) 연속 들여쓰기 / plain 멀티라인.
+// 그 외 형태는 parse_error 로 별도 카운트(0 침묵 금지).
+// ---------------------------------------------------------------------------
+export function parseFrontmatter(md) {
+  const out = { description: null, disabled: false, error: null }
+  if (typeof md !== 'string' || !/^---\s*\r?\n/.test(md)) {
+    out.error = 'no_frontmatter'
+    return out
+  }
+  const endMatch = md.slice(3).match(/\r?\n---\s*(\r?\n|$)/)
+  if (!endMatch) {
+    out.error = 'unterminated_frontmatter'
+    return out
+  }
+  const fm = md.slice(3, 3 + endMatch.index)
+  const lines = fm.split(/\r?\n/)
+  let descFound = false
+  for (let i = 0; i < lines.length; i++) {
+    const dm = lines[i].match(/^(disable-model-invocation)\s*:\s*(.+?)\s*$/)
+    if (dm && dm[2].replace(/['"]/g, '') === 'true') out.disabled = true
+
+    const m = descFound ? null : lines[i].match(/^(description)\s*:\s*(.*)$/)
+    if (!m) continue
+    descFound = true
+    let value = m[2].trim()
+    if (/^[|>][+-]?\s*$/.test(value)) {
+      // block scalar — 이후 더 깊게 들여쓴 연속 라인
+      const block = []
+      for (let j = i + 1; j < lines.length; j++) {
+        if (/^\s+\S/.test(lines[j]) || lines[j].trim() === '') {
+          if (lines[j].trim() === '' && !/^\s+\S/.test(lines[j + 1] ?? '')) break
+          block.push(lines[j].trim())
+        } else break
+      }
+      out.description = block.join(' ').trim()
+    } else {
+      // plain 멀티라인 — 다음 라인이 key 형태가 아니고 들여쓰기면 연속으로 본다
+      const cont = []
+      for (let j = i + 1; j < lines.length; j++) {
+        if (/^\s+\S/.test(lines[j]) && !/^\s*[\w-]+\s*:/.test(lines[j])) cont.push(lines[j].trim())
+        else break
+      }
+      if (cont.length) value = [value, ...cont].join(' ')
+      const q = value.match(/^"(.*)"$/s) || value.match(/^'(.*)'$/s)
+      out.description = (q ? q[1] : value).trim()
+    }
+    if (!out.description) {
+      out.error = 'parse_error'
+      out.description = null
+    }
+  }
+  if (!descFound) out.error = 'no_description'
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// CLAUDE.md 로딩 규칙 합산 (§2.1 claude_md_total)
+// @import 확장 depth ≤3, visited set 으로 순환·중복 방지.
+// ---------------------------------------------------------------------------
+function parseImports(content) {
+  const refs = []
+  let inFence = false
+  for (const line of content.split('\n')) {
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence
+      continue
+    }
+    if (inFence) continue
+    for (const m of line.matchAll(/(^|\s)@([~A-Za-z0-9_][^\s`)\]]*)/g)) {
+      refs.push(m[2])
+    }
+  }
+  return refs
+}
+
+function expandFileChars(filePath, home, visited, depth) {
+  let real = filePath
+  try {
+    real = statSync(filePath).isFile() ? resolve(filePath) : null
+  } catch {
+    return 0
+  }
+  if (!real || visited.has(real)) return 0
+  visited.add(real)
+  const content = readTextSafe(real)
+  if (content == null) return 0
+  let chars = content.length
+  if (depth < IMPORT_MAX_DEPTH) {
+    for (const ref of parseImports(content)) {
+      const target = ref.startsWith('~/')
+        ? join(home, ref.slice(2))
+        : resolve(dirname(real), ref)
+      chars += expandFileChars(target, home, visited, depth + 1)
+    }
+  }
+  return chars
+}
+
+function listRuleFiles(dir) {
+  try {
+    return readdirSync(dir)
+      .filter((f) => f.endsWith('.md'))
+      .map((f) => join(dir, f))
+  } catch {
+    return []
+  }
+}
+
+export function measureMemory({ cwd, home }) {
+  // project — cwd 직속 메모리 파일 raw 합산 (import 확장은 total 에서)
+  const projectFiles = MEMORY_FILE_PATTERNS.map((p) => join(cwd, p)).filter((p) => existsSync(p))
+  let projectChars = 0
+  let projectLines = 0
+  for (const f of projectFiles) {
+    const t = readTextSafe(f)
+    if (t == null) continue
+    projectChars += t.length
+    projectLines += t.split('\n').length
+  }
+
+  // total — 글로벌 + cwd→루트 상위 디렉토리 + rules + @import 확장.
+  // 상한을 $HOME 이 아니라 루트로 잡는 이유: Claude Code 실제 로딩 규칙이 cwd 에서
+  // 루트 직전까지 재귀 탐색이고, 이 repo 처럼 cwd 가 $HOME 밖($/Volumes/..)인 경우
+  // $HOME 상한으로는 워크스페이스 CLAUDE.md 를 놓친다 (spec §2.1 의 "cwd→$HOME" 문구를
+  // 실측 기준으로 보정 — spec changelog 2026-07-10 3차 참조).
+  const candidates = new Set([join(home, '.claude', 'CLAUDE.md')])
+  let dir = cwd
+  for (;;) {
+    for (const pat of MEMORY_FILE_PATTERNS) candidates.add(join(dir, pat))
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  for (const f of listRuleFiles(join(home, '.claude', 'rules'))) candidates.add(f)
+  for (const f of listRuleFiles(join(cwd, '.claude', 'rules'))) candidates.add(f)
+
+  const visited = new Set()
+  let totalChars = 0
+  let totalFiles = 0
+  for (const f of candidates) {
+    if (!existsSync(f)) continue
+    totalFiles++
+    totalChars += expandFileChars(f, home, visited, 0)
+  }
+  return {
+    project: { chars: projectChars, lines: projectLines, files: projectFiles.length },
+    total: { chars: totalChars, files: totalFiles },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 스킬·에이전트 description 자산 수집 (§2.1 skills_agents_desc)
+// 활성 자산만: 로컬 skills/agents + enabled 플러그인(installed_plugins.json v2 +
+// settings.enabledPlugins). identity 는 네임스페이스 포함(plugin:skill).
+// ---------------------------------------------------------------------------
+function birthtimeMs(p) {
+  try {
+    const st = statSync(p)
+    return st.birthtimeMs || st.mtimeMs
+  } catch {
+    return 0
+  }
+}
+
+function collectSkillDirs(base, prefix, source, items) {
+  let entries
+  try {
+    entries = readdirSync(base, { withFileTypes: true })
+  } catch {
+    return
+  }
+  for (const e of entries) {
+    if (!e.isDirectory() && !e.isSymbolicLink()) continue
+    const skillMd = join(base, e.name, 'SKILL.md')
+    const md = readTextSafe(skillMd)
+    if (md == null) continue
+    const fm = parseFrontmatter(md)
+    items.push({
+      identity: prefix ? `${prefix}:${e.name}` : e.name,
+      kind: 'skill',
+      source,
+      path: skillMd,
+      descChars: fm.description ? fm.description.length : 0,
+      disabled: fm.disabled,
+      parseError: fm.error === 'parse_error' || fm.error === 'unterminated_frontmatter' || fm.error === 'no_frontmatter' ? fm.error : null,
+      birthtimeMs: birthtimeMs(join(base, e.name)),
+    })
+  }
+}
+
+function collectAgentFiles(base, prefix, source, items) {
+  let entries
+  try {
+    entries = readdirSync(base)
+  } catch {
+    return
+  }
+  for (const f of entries) {
+    if (!f.endsWith('.md') || f.startsWith('_') || f.startsWith('.')) continue
+    const p = join(base, f)
+    const md = readTextSafe(p)
+    if (md == null) continue
+    const fm = parseFrontmatter(md)
+    const name = basename(f, '.md')
+    items.push({
+      identity: prefix ? `${prefix}:${name}` : name,
+      kind: 'agent',
+      source,
+      path: p,
+      descChars: fm.description ? fm.description.length : 0,
+      disabled: fm.disabled,
+      parseError: fm.error === 'parse_error' || fm.error === 'unterminated_frontmatter' || fm.error === 'no_frontmatter' ? fm.error : null,
+      birthtimeMs: birthtimeMs(p),
+    })
+  }
+}
+
+// settings 로 꺼진 스킬 (§2.1 "disable-model-invocation·settings 로 꺼진 스킬은 제외").
+// Claude Code 의 per-skill disable 설정 키는 버전에 따라 다를 수 있어 알려진 형태를
+// 관용적으로 읽는다: skillOverrides { "<name>": false | {enabled:false} } / disabledSkills[] /
+// skills.disabled[]. 미지원 키는 조용히 무시(빈 set).
+export function loadSettingsDisabledSkills(home) {
+  const s = readJsonSafe(join(home, '.claude', 'settings.json')) || {}
+  const out = new Set()
+  if (s.skillOverrides && typeof s.skillOverrides === 'object') {
+    for (const [k, v] of Object.entries(s.skillOverrides)) {
+      if (v === false || (v && typeof v === 'object' && v.enabled === false)) out.add(k)
+    }
+  }
+  for (const arr of [s.disabledSkills, s.skills && s.skills.disabled]) {
+    if (Array.isArray(arr)) for (const k of arr) if (typeof k === 'string') out.add(k)
+  }
+  return out
+}
+
+// enabled 판정의 실제 소스 (실측, spec §2.1 문구 보정): installed_plugins.json v2 에는
+// enabled 필드가 없다 — 설치 경로(installPath)만 담는다. enabled 상태는
+// settings.json 의 enabledPlugins { "<name>@<marketplace>": true } 가 SSOT.
+export function resolveEnabledPluginInstalls({ home, cwd }) {
+  const settings = readJsonSafe(join(home, '.claude', 'settings.json')) || {}
+  const enabled = settings.enabledPlugins || {}
+  const registry = readJsonSafe(join(home, '.claude', 'plugins', 'installed_plugins.json'))
+  const plugins = (registry && registry.plugins) || {}
+  const out = []
+  for (const [key, installs] of Object.entries(plugins)) {
+    if (enabled[key] !== true) continue
+    const list = Array.isArray(installs) ? installs : []
+    // user 스코프 우선, project 스코프는 현재 cwd 가 그 projectPath 아래일 때만
+    const pick =
+      list.find((i) => i.scope === 'user') ||
+      list.find(
+        (i) =>
+          i.scope === 'project' &&
+          typeof i.projectPath === 'string' &&
+          (cwd === i.projectPath || cwd.startsWith(i.projectPath + '/'))
+      )
+    if (pick && pick.installPath) out.push({ key, name: key.split('@')[0], installPath: pick.installPath })
+  }
+  return out
+}
+
+export function collectAssets({ home, cwd }) {
+  const items = []
+  collectSkillDirs(join(home, '.claude', 'skills'), '', 'local', items)
+  collectAgentFiles(join(home, '.claude', 'agents'), '', 'local', items)
+  for (const pl of resolveEnabledPluginInstalls({ home, cwd })) {
+    collectSkillDirs(join(pl.installPath, 'skills'), pl.name, `plugin:${pl.key}`, items)
+    collectAgentFiles(join(pl.installPath, 'agents'), pl.name, `plugin:${pl.key}`, items)
+  }
+  const settingsDisabled = loadSettingsDisabledSkills(home)
+  if (settingsDisabled.size) {
+    for (const it of items) {
+      const short = it.identity.includes(':') ? it.identity.split(':').pop() : null
+      if (settingsDisabled.has(it.identity) || (short && settingsDisabled.has(short))) it.disabled = true
+    }
+  }
+  return items
+}
+
+// ---------------------------------------------------------------------------
+// 사용 이력 스캔 (§2.1 unused_skills) — 데이터 최소화: 이름·카운트만 추출.
+// transcript 본문 저장·출력·전송 금지. 매칭 3종: ① Skill tool_use input.skill
+// ② "Launching skill: <name>" ③ <command-name>/<name></command-name>
+// ---------------------------------------------------------------------------
+// 64KB chunk 동기 라인 스트리밍. deadline 초과 시 false(미완주) 반환.
+// 스킬 이름 매칭 패턴은 전부 ASCII 라 chunk 경계의 멀티바이트 분절은 매칭에 영향 없음.
+function scanFileLines(filePath, onLine, deadline) {
+  let fd
+  try {
+    fd = openSync(filePath, 'r')
+  } catch {
+    return true // 못 여는 파일은 skip — 완주로 취급
+  }
+  try {
+    const buf = Buffer.alloc(64 * 1024)
+    let carry = ''
+    for (;;) {
+      let n
+      try {
+        n = readSync(fd, buf, 0, buf.length, null)
+      } catch {
+        return true
+      }
+      if (n <= 0) break
+      const text = carry + buf.toString('utf8', 0, n)
+      const lines = text.split('\n')
+      carry = lines.pop()
+      for (const l of lines) onLine(l)
+      if (Date.now() > deadline) return false
+    }
+    if (carry) onLine(carry)
+    return true
+  } finally {
+    try {
+      closeSync(fd)
+    } catch {
+      /* noop */
+    }
+  }
+}
+
+function walkJsonl(dir, out) {
+  let entries
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return
+  }
+  for (const e of entries) {
+    const p = join(dir, e.name)
+    if (e.isDirectory()) walkJsonl(p, out)
+    else if (e.name.endsWith('.jsonl')) out.push(p)
+  }
+}
+
+export function scanSkillUsage({ home, windowDays = USAGE_WINDOW_DAYS, now = Date.now(), timeBudgetMs = 10000 }) {
+  // deadline 은 walk/stat/sort 이전에 시작 — 파일 목록 단계가 길어도 총 소요가 budget 을 크게 넘지 않게
+  const deadline = Date.now() + timeBudgetMs
+  const root = join(home, '.claude', 'projects')
+  const all = []
+  walkJsonl(root, all)
+  const cutoff = now - windowDays * 24 * 60 * 60 * 1000
+  const recent = []
+  for (const p of all) {
+    try {
+      const st = statSync(p)
+      if (st.mtimeMs >= cutoff) recent.push({ p, mtimeMs: st.mtimeMs })
+    } catch {
+      /* skip */
+    }
+  }
+  recent.sort((a, b) => b.mtimeMs - a.mtimeMs)
+
+  const counts = {}
+  const bump = (name) => {
+    if (!name) return
+    counts[name] = (counts[name] || 0) + 1
+  }
+  const onLine = (line) => {
+    if (line.includes('"name":"Skill"') || line.includes('"name": "Skill"')) {
+      const m = line.match(/"skill"\s*:\s*"([^"]+)"/)
+      if (m) bump(m[1])
+    }
+    if (line.includes('Launching skill:')) {
+      for (const m of line.matchAll(/Launching skill:\s*([A-Za-z0-9:_-]+)/g)) bump(m[1])
+    }
+    if (line.includes('<command-name>')) {
+      for (const m of line.matchAll(/<command-name>\/?([A-Za-z0-9:_-]+)<\/command-name>/g)) bump(m[1])
+    }
+  }
+  let scanned = 0
+  let partial = false
+  for (const { p } of recent) {
+    if (Date.now() > deadline) {
+      partial = true
+      break
+    }
+    // 라인 스트리밍(§2.1) — 파일 전체를 메모리에 올리지 않고 chunk 단위로 읽으며
+    // budget 을 chunk 마다 검사한다. 큰 jsonl 1개가 예산·메모리를 독점하지 않게.
+    const completed = scanFileLines(p, onLine, deadline)
+    if (!completed) {
+      partial = true
+      break
+    }
+    scanned++
+  }
+  return {
+    counts,
+    window_days: windowDays,
+    files_total: recent.length,
+    files_scanned: scanned,
+    partial,
+  }
+}
+
+export function loadUsageCache(home, now = Date.now()) {
+  const cache = readJsonSafe(usageCachePath(home))
+  if (!cache || typeof cache.scanned_at !== 'number') return null
+  if (now - cache.scanned_at > USAGE_CACHE_MAX_AGE_MS) return null
+  return cache
+}
+
+export function saveUsageCache(home, usage, now = Date.now()) {
+  try {
+    writeFileSync(usageCachePath(home), JSON.stringify({ scanned_at: now, ...usage }))
+  } catch {
+    /* best-effort — 미기록이면 다음에 재스캔 (§4) */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 미사용 스킬 후보 (§2.1 오탐 안전장치 포함)
+// ---------------------------------------------------------------------------
+export function findUnusedSkills({ items, counts, keep = [], now = Date.now() }) {
+  const used = (identity) => {
+    if ((counts[identity] || 0) > 0) return true
+    const short = identity.includes(':') ? identity.split(':').pop() : null
+    return short ? (counts[short] || 0) > 0 : false
+  }
+  const keepSet = new Set(keep)
+  return items
+    .filter((it) => it.kind === 'skill' && !it.disabled && !it.parseError)
+    .filter((it) => it.identity !== 'rookie' && !it.identity.endsWith(':rookie'))
+    .filter((it) => !keepSet.has(it.identity))
+    .filter((it) => !(it.birthtimeMs && now - it.birthtimeMs < NEW_SKILL_GRACE_MS))
+    .filter((it) => !used(it.identity))
+    .map((it) => it.identity)
+    .sort()
+}
+
+export function loadSnooze(home, now = Date.now()) {
+  const raw = readJsonSafe(snoozePath(home)) || {}
+  const active = {}
+  for (const [k, until] of Object.entries(raw)) {
+    const t = Date.parse(until)
+    if (Number.isFinite(t) && t > now) active[k] = until
+  }
+  return active
+}
+
+// ---------------------------------------------------------------------------
+// 리포트 조립 (§2.1 5항목 + 임계 판정 + snooze)
+// usageMode: 'cache-or-scan'(CLI 기본) | 'force-scan'(--force) | 'cache-only'(doctor)
+// ---------------------------------------------------------------------------
+export function computeReport({
+  cwd = process.cwd(),
+  home = homedir(),
+  now = Date.now(),
+  usageMode = 'cache-or-scan',
+} = {}) {
+  const snooze = loadSnooze(home, now)
+  const items = {}
+
+  // 1+2) claude_md_project / claude_md_total
+  let memory = null
+  try {
+    memory = measureMemory({ cwd, home })
+  } catch {
+    /* 부분 실패 허용 (§4) — 해당 항목 null */
+  }
+  items.claude_md_project = memory
+    ? {
+        chars: memory.project.chars,
+        lines: memory.project.lines,
+        files: memory.project.files,
+        threshold: THRESHOLDS.claude_md_project,
+        exceeded: memory.project.chars > THRESHOLDS.claude_md_project,
+      }
+    : null
+  items.claude_md_total = memory
+    ? {
+        chars: memory.total.chars,
+        files: memory.total.files,
+        threshold: THRESHOLDS.claude_md_total,
+        exceeded: memory.total.chars > THRESHOLDS.claude_md_total,
+      }
+    : null
+
+  // 3) skills_agents_desc
+  let assets = null
+  let parseErrors = 0
+  try {
+    assets = collectAssets({ home, cwd })
+    parseErrors = assets.filter((a) => a.parseError).length
+    const chars = assets.filter((a) => !a.disabled).reduce((s, a) => s + a.descChars, 0)
+    items.skills_agents_desc = {
+      chars,
+      count: assets.length,
+      parse_errors: parseErrors,
+      threshold: THRESHOLDS.skills_agents_desc,
+      exceeded: chars > THRESHOLDS.skills_agents_desc,
+    }
+  } catch {
+    items.skills_agents_desc = null
+  }
+
+  // 4) rookie_self
+  try {
+    const skillMd = readTextSafe(join(home, '.claude', 'skills', 'rookie', 'SKILL.md'))
+    const inj = readJsonSafe(lastInjectionPath(home))
+    const injAt = inj && inj.at ? Date.parse(inj.at) : NaN
+    const injStale = !Number.isFinite(injAt) || now - injAt > INJECTION_STALE_MS
+    const skillChars = skillMd ? skillMd.length : 0
+    const injChars = inj && typeof inj.chars === 'number' ? inj.chars : null
+    items.rookie_self = {
+      skill_chars: skillChars,
+      injected_chars: injChars,
+      injection_stale: injStale,
+      threshold_skill: THRESHOLDS.rookie_self_skill,
+      threshold_injected: THRESHOLDS.rookie_self_injected,
+      // stale 주입 메타는 판정에서 제외 (§2.1)
+      exceeded:
+        skillChars > THRESHOLDS.rookie_self_skill ||
+        (!injStale && injChars != null && injChars > THRESHOLDS.rookie_self_injected),
+    }
+  } catch {
+    items.rookie_self = null
+  }
+
+  // 5) unused_skills — usage 는 캐시 7일 재사용 (§2.1 데이터 최소화)
+  let usage = usageMode === 'force-scan' ? null : loadUsageCache(home, now)
+  let usageFromCache = !!usage
+  if (!usage && usageMode !== 'cache-only') {
+    try {
+      usage = scanSkillUsage({ home, now })
+      saveUsageCache(home, usage, now)
+    } catch {
+      usage = null
+    }
+  }
+  if (usage && assets) {
+    const keep = readJsonSafe(keepPath(home)) || []
+    const unused = findUnusedSkills({ items: assets, counts: usage.counts || {}, keep, now })
+    items.unused_skills = {
+      names: unused,
+      count: unused.length,
+      window_days: usage.window_days ?? USAGE_WINDOW_DAYS,
+      usage_partial: !!usage.partial,
+      usage_cached: usageFromCache,
+      usage_scanned_at: usage.scanned_at ?? now,
+      threshold: THRESHOLDS.unused_skills_min,
+      // partial 스캔이면 "안 쓴 걸로 오인" 위험 → 판정 제외 (§4 부분 실패 허용)
+      exceeded: !usage.partial && unused.length >= THRESHOLDS.unused_skills_min,
+    }
+  } else {
+    items.unused_skills = null
+  }
+
+  for (const [key, item] of Object.entries(items)) {
+    if (item) item.snoozed = key in snooze
+  }
+  const ok = Object.values(items).some((v) => v != null)
+  return {
+    ok,
+    measured_at: now,
+    proxy_note: '설치 자산 기준 proxy — 실제 토큰 주입량과 다를 수 있음',
+    items,
+    snooze,
+  }
+}

package/src/lib/dead-letter.js

@@ -0,0 +1,73 @@
+// B3 (spec 2026-07-11-memory-reliability-fix-design §B3) — dead letter 성격 분류.
+// 데이터 소스 = ~/.rookie/dead-letter/*.jsonl (hook queue 의 retry 소진·정책 거부 산물).
+// 파일명 규약(queue.sh): <sid>-mutate-invalid-<ts>.jsonl(4xx 정책 거부) /
+// <sid>-mutate.jsonl(batch-mutate retry 소진) / <sid>.jsonl(flush-session retry 소진).
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export function deadLetterKind(fileName) {
+  if (fileName.includes('-mutate-invalid-')) return 'mutate_invalid'
+  if (fileName.endsWith('-mutate.jsonl') || fileName.endsWith('-mutate-retry.jsonl')) return 'batch_mutate'
+  return 'flush_session'
+}
+
+// last_error_status → 사람이 읽는 사유 버킷.
+export function statusBucket(status) {
+  const s = String(status ?? '').trim()
+  if (s === '' || s === 'unknown') return 'unknown'
+  if (s === '000' || s === '0') return 'network'
+  const n = Number(s)
+  if (Number.isFinite(n) && n >= 400 && n < 500) return `http_4xx`
+  if (Number.isFinite(n) && n >= 500) return `http_5xx`
+  return 'unknown'
+}
+
+// entries = [{name, lastErrorStatus, deadLetterAt}] → 사유별 집계 (순수 — 테스트 대상).
+export function classifyDeadLetters(entries) {
+  const byKind = {}
+  const byStatus = {}
+  let recent = null
+  for (const e of entries) {
+    const kind = deadLetterKind(e.name)
+    byKind[kind] = (byKind[kind] ?? 0) + 1
+    // mutate-invalid 파일은 dispatcher 가 raw payload 만 남긴다(상태 필드 없음) —
+    // 4xx 정책 거부 산물이므로 파일명 kind 로 http_4xx 에 귀속(코드검토 P2).
+    const raw = statusBucket(e.lastErrorStatus)
+    const bucket = raw === 'unknown' && kind === 'mutate_invalid' ? 'http_4xx' : raw
+    byStatus[bucket] = (byStatus[bucket] ?? 0) + 1
+    const at = e.deadLetterAt ? Date.parse(e.deadLetterAt) : NaN
+    if (!Number.isNaN(at) && (recent === null || at > recent.ts)) {
+      recent = { ts: at, kind, bucket, at: e.deadLetterAt }
+    }
+  }
+  return { total: entries.length, byKind, byStatus, recent }
+}
+
+// dead-letter 디렉토리 스캔 (fail-soft). 각 파일의 마지막 유효 라인에서 상태를 뽑는다.
+export function readDeadLetterEntries(dir = join(process.env.HOME ?? '', '.rookie', 'dead-letter')) {
+  if (!existsSync(dir)) return []
+  let names
+  try {
+    names = readdirSync(dir).filter((f) => f.endsWith('.jsonl'))
+  } catch {
+    return []
+  }
+  const entries = []
+  for (const name of names) {
+    let lastErrorStatus = null
+    let deadLetterAt = null
+    try {
+      const lines = readFileSync(join(dir, name), 'utf8').split('\n').filter(Boolean)
+      for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+          const obj = JSON.parse(lines[i])
+          lastErrorStatus = obj.last_error_status ?? obj.status ?? null
+          deadLetterAt = obj.dead_letter_at ?? obj.queued_at ?? null
+          break
+        } catch { /* 깨진 라인 — 더 위 라인 시도 */ }
+      }
+    } catch { /* 읽기 실패 — 파일명만으로 집계 */ }
+    entries.push({ name, lastErrorStatus, deadLetterAt })
+  }
+  return entries
+}