@bglocation/tune-context 1.1.0 → 2.0.0

package/cli/generate.mjs

@@ -76,6 +76,12 @@ function templateInnerBlock(templatePath) {
   const raw = readFileSync(templatePath, 'utf8');
   const start = raw.indexOf('<!-- >>> tune-context (managed) >>>');
   const end = raw.indexOf('<!-- <<< tune-context (managed) <<< -->');
+  // A missing marker makes `start`/`end` -1; indexOf('\n', -1) silently treats
+  // -1 as 0, which used to return garbage sliced from the top of the file
+  // instead of failing. A broken template must not become a broken CLAUDE.md.
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error(`template ${templatePath} is missing the tune-context managed-block markers`);
+  }
   const startLineEnd = raw.indexOf('\n', start) + 1;
   return raw.slice(startLineEnd, end).trimEnd();
 }

package/cli/sync-doctrine.mjs

@@ -1,6 +1,15 @@
 // Mirrors this package's skills/agents/hooks into a Claude Code config dir
-// (~/.claude by default). Idempotent — removes each destination entry before
-// copying, so deletions at the source propagate too, not just an overlay.
+// (~/.claude by default). Idempotent for content that still exists at the
+// source: each entry is removed then recopied, so a changed file/directory
+// shape can't leave old siblings behind inside THAT entry. This is an
+// OVERLAY, not a mirror, across runs: the outer loop is `readdirSync(from)`,
+// so an entry no longer present at the source is simply never visited again —
+// it is NOT deleted from the destination (review finding, TASK-077; verified
+// empirically, not assumed. See the "KNOWN GAP" test in
+// test/cli-sync-doctrine.test.mjs). A prune pass would need to diff against
+// what THIS tool previously wrote, since claudeDir may also hold a user's own
+// unrelated skills/agents/hooks that must never be touched — deliberately not
+// attempted here without that design decision.
 import { chmodSync, cpSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 

package/cli/verify.mjs

@@ -24,15 +24,31 @@ function extractHookPath(command) {
   return m ? (m[1] ?? m[2]) : null;
 }
 
-// Expand $HOME / ${HOME} the way the hook will at run time. Must use the exact
-// base claudeDirs() uses (process.env.HOME || homedir()) — a different notion of
-// "home" on the two sides of the comparison would itself manufacture a mismatch
-// and fire a false alarm on a correct install.
+// Expand $HOME / ${HOME} inside a hook COMMAND STRING the way it resolves at
+// run time (process.env.HOME, falling back to homedir() if HOME is somehow
+// unset) — the literal shell variable baked into the *default*, non-override
+// hook command form (hooksDirForTemplate() in cli/generate.mjs). UNRELATED to
+// CLAUDE_CONFIG_DIR: that rule lives solely in claudeBaseDir()
+// (hooks/config-dir.mjs, TASK-074) and governs which directory claudeDir
+// itself resolves to, a different axis from $HOME shell-expansion. A
+// different notion of "home" on the two sides of the comparison below would
+// itself manufacture a mismatch and fire a false alarm on a correct install.
 function expandHome(p) {
   const home = process.env.HOME || homedir();
   return p.replace(/\$\{HOME\}/g, home).replace(/\$HOME/g, home);
 }
 
+// TASK-072: signature of the PLUGIN channel's own hook registration turning up
+// where a settings.json entry is being checked. `${CLAUDE_PLUGIN_ROOT}` is
+// Claude Code's substitution for a plugin's OWN hooks.json — it is never
+// expanded for a command sitting in settings.json, so resolving/existsSync-ing
+// it here would always read as "missing", which would be a lie: the plugin
+// channel may be working perfectly well from Claude Code's side. Commands
+// matching this are pulled out of the resolvability check below and reported
+// separately, always informational — we can tell the command SHAPE is
+// present, never whether the plugin is actually enabled (Option B, TASK-072).
+const PLUGIN_PATH_HINT = /\$\{CLAUDE_PLUGIN_ROOT\}|[\\/]plugins[\\/]/;
+
 /**
  * @returns {{ok: boolean, checks: {name: string, ok: boolean, detail?: string}[]}}
  */
@@ -48,9 +64,38 @@ export function verify({ claudeDir, userSettingsPath, expectedHookCommands, proj
   const settings = readJson(userSettingsPath);
   for (const { event, scriptName } of expectedHookCommands) {
     const entries = settings?.hooks?.[event] || [];
-    const commands = entries.flatMap((g) => (g.hooks || []).map((h) => h.command)).filter(Boolean);
+    const allCommands = entries.flatMap((g) => (g.hooks || []).map((h) => h.command)).filter(Boolean);
     const installedPath = resolve(join(claudeDir, 'hooks', scriptName));
 
+    // Classify by DESTINATION, not by spelling: a command that resolves to
+    // the very file we installed is the CLI registration, whatever its path
+    // happens to look like. Without this, PLUGIN_PATH_HINT's loose
+    // `/plugins/` arm swallowed a correct install whose config dir merely
+    // sits under such a path (e.g. CLAUDE_CONFIG_DIR=/opt/plugins/claude) —
+    // it was dropped from `commands`, then reported "not found in
+    // settings.json", i.e. a false RED on a perfect install, plus a plugin
+    // note for a plugin that isn't there (review finding, EPIC-008).
+    // `${CLAUDE_PLUGIN_ROOT}` stays correctly classified: it is literal text
+    // in settings.json (Claude Code only expands it for a plugin's own
+    // hooks.json), so it can never resolve to the installed file.
+    const isInstalledTarget = (c) => {
+      const p = extractHookPath(c);
+      return p !== null && resolve(expandHome(p)) === installedPath;
+    };
+    const isPluginShaped = (c) => PLUGIN_PATH_HINT.test(c) && !isInstalledTarget(c);
+
+    // Report the plugin-channel shape separately and up front — see
+    // PLUGIN_PATH_HINT above — then exclude it from the resolvability check
+    // below so it can never be misread as a dead/stale leftover.
+    for (const pluginCmd of allCommands.filter((c) => c.includes(scriptName) && isPluginShaped(c))) {
+      checks.push({
+        name: `hooks.${event}: ${scriptName} also has a plugin-channel registration`,
+        ok: true,
+        detail: `${pluginCmd} — if the tune-context plugin is also enabled, every ${event} event logs twice; see README ("Measuring adoption") for the re-read-churn effect this has on adoption-report`,
+      });
+    }
+    const commands = allCommands.filter((c) => !isPluginShaped(c));
+
     // Match by the basename of each command's target path — ALL of them, not
     // just the first. mergeHooks is a set keyed by command, so a path change
     // (e.g. adopting CLAUDE_CONFIG_DIR) appends a new entry next to the old

package/eval/adoption-report.mjs

@@ -30,6 +30,29 @@ const DOCTRINE_SKILLS = new Set([
 // Churn is exempt — a within-session symptom, readable at any n.
 const MIN_SESSIONS_FOR_VERDICT = 3;
 
+// Two hook processes spawned for the SAME Claude Code event (a script
+// registered on both the plugin channel and settings.json — TASK-072) write
+// near-identical records milliseconds apart. FROZEN WITH PO (2026-07-25,
+// TASK-072; same anti-bias rule as MIN_SESSIONS_FOR_VERDICT above, TASK-062).
+//
+// Measured, not guessed: the gap distribution of same-key adjacent pairs in
+// the real 2026-07-24 log is cleanly bimodal —
+//   ≤14ms   : 159 pairs  (duplicate dispatch: 0,1,2,3,4,5,6,7,8,14ms)
+//   15-359ms:   0 pairs  (empty)
+//   ≥360ms  : 288 pairs  (continuous out to 10s — genuine repeated activity)
+// 100ms sits in the empty band, with maximum margin on both sides. A wider
+// window (the 1000ms first proposed here) reaches past the gap and swallows 8
+// real pairs — suppressing true churn, the exact failure this must avoid.
+const DUPLICATE_LOG_WINDOW_MS = 100;
+
+// Share of all records that must look like duplicate dispatches before the
+// churn verdict is withheld. FROZEN WITH PO (2026-07-25, TASK-072).
+// A doubled registration doubles EVERY event, so the signature is always a
+// large share (28% in the real log — 159 pairs of 559 records), never a
+// stray one. Requiring a share rather than a single pair keeps a couple of
+// coincidentally-fast events from silencing a whole log's verdict.
+const MIN_DUPLICATE_SHARE = 0.1;
+
 function defaultLogPath() {
   return join(claudeBaseDir(), 'tune-context', 'adoption.jsonl');
 }
@@ -64,6 +87,46 @@ export function parseLog(text) {
   return out;
 }
 
+// Two (or more) records sharing (session, tool, lever, detail) within
+// DUPLICATE_LOG_WINDOW_MS of each other look like the SAME real event logged
+// twice — the signature of a hook registered on two channels at once
+// (TASK-072), not genuine repeated activity. Runs over every lever, not just
+// reads: a doubled hook doubles all of them equally.
+//
+// Records with an empty `detail` are SKIPPED, and skipped on both sides of
+// the ratio (see `assessable`). classify() gives every non-search Bash call
+// `detail: null`, so they all collapse onto a single key — and Claude Code
+// fires parallel tool calls within one turn, whose hooks land milliseconds
+// apart. Two genuinely different Bash commands would then read as a duplicate
+// pair. Measured on a clean simulated log, parallel Bash alone reached 13.9%
+// and tripped MIN_DUPLICATE_SHARE — a false "undecidable" over a perfectly
+// readable log. Restricting to detail-bearing records removes that vector
+// (0% on the same simulation) and still detects the real thing with a wide
+// margin: 28.9% on the frozen snapshot, 42.8% on a 1605-record live log.
+// Deduplicating the counts themselves stays out of scope (TASK-072): we
+// withhold the verdict, we don't guess which record was "real".
+function countDuplicateRegistrationPairs(records) {
+  const groups = new Map();
+  let assessable = 0;
+  for (const r of records) {
+    const t = Date.parse(r.ts);
+    if (Number.isNaN(t)) continue;
+    if (!r.detail) continue; // ambiguous key — see above
+    assessable++;
+    const key = `${r.session ?? ''}\u0000${r.tool ?? ''}\u0000${r.lever ?? ''}\u0000${r.detail}`;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(t);
+  }
+  let pairs = 0;
+  for (const times of groups.values()) {
+    times.sort((a, b) => a - b);
+    for (let i = 1; i < times.length; i++) {
+      if (times[i] - times[i - 1] <= DUPLICATE_LOG_WINDOW_MS) pairs++;
+    }
+  }
+  return { pairs, assessable };
+}
+
 export function aggregate(records) {
   const search = { rag: 0, grepTool: 0, shell: 0, glob: 0 };
   const skills = new Map();
@@ -140,6 +203,13 @@ export function aggregate(records) {
     }
   }
 
+  // Both sides of this ratio come from the same population — only records
+  // whose duplicate status is actually assessable (see the function's note).
+  // Using records.length as the denominator instead would let a Bash-heavy
+  // log dilute a genuine doubling below the floor.
+  const { pairs: dedupPairs, assessable: dedupAssessable } = countDuplicateRegistrationPairs(records);
+  const dedupShare = dedupAssessable > 0 ? dedupPairs / dedupAssessable : 0;
+
   return {
     total: records.length,
     sessions: sessionSet.size,
@@ -155,6 +225,16 @@ export function aggregate(records) {
     reReadFiles,
     redundantReads,
     reReadRate: reads > 0 ? redundantReads / reads : null,
+    // TASK-072: near-duplicate records within DUPLICATE_LOG_WINDOW_MS,
+    // consistent with a doubled hook registration. dedupSuspected gates the
+    // churn VERDICT line in formatReport — the raw counts above stay as-is
+    // (deduplicating them would be a guess, out of scope). Gated on a SHARE,
+    // not a single pair: doubling affects every event, so a genuine doubled
+    // log is always well past the floor, while a couple of coincidentally
+    // fast events must not silence an otherwise readable verdict.
+    dedupPairs,
+    dedupShare,
+    dedupSuspected: dedupShare >= MIN_DUPLICATE_SHARE,
     // Doctrine applied as *method* — narrow reads, contracts-first edits,
     // delegation — leaves no `Skill` tool call, so the skills verdict below
     // can't see it (same blind spot the report already admits for caveman).
@@ -273,7 +353,17 @@ export function formatReport(a) {
     // on MIN_SESSIONS_FOR_VERDICT. But zero reads is zero churn signal: report
     // n/a, never "elevated" — that would be a false ✗ over no data (same
     // "say only what the sample supports" rule as the verdict above).
-    if (a.reReadRate === null) {
+    if (a.dedupSuspected) {
+      // TASK-072: withhold the verdict rather than print a fabricated ✓/~ —
+      // a doubled hook registration inflates re-read churn without any real
+      // re-reading happening. "Only say what the data supports" (TASK-070).
+      L.push(
+        `  ~ re-read churn: undecidable — ${a.dedupPairs} near-duplicate event pair(s),` +
+          ` ${pct(a.dedupShare)} of comparable records, consistent with the hook being` +
+          ' registered twice (plugin + settings.json). Every event logs twice, so churn' +
+          ' can\'t be read off this log; see README ("Measuring adoption").',
+      );
+    } else if (a.reReadRate === null) {
       L.push('  · re-read churn: n/a — no reads logged yet.');
     } else {
       L.push(

package/hooks/context-reminder.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// UserPromptSubmit hook: measures how much context this session is actually
+// carrying and, once it crosses a threshold, injects a short reminder that it
+// may be time to shed some. See tasks/TASK-079.
+//
+// Why a hook has to do this at all: the model cannot see its own context
+// usage — nothing in a turn tells it how many tokens it is re-sending. The
+// user can see a number but has no reason to watch it. Claude Code exposes no
+// timer and no context-threshold event (verified against the hooks docs), so
+// the only place the measurement can come from is the transcript.
+//
+// Honest scope, and the reason this reminds on SIZE rather than on "phase
+// boundary": a hook is a plain script with no model access, so it cannot know
+// that a work thread just ended. Size is measurable; a phase boundary is a
+// judgment. This hook therefore supplies the measurement the model can't see,
+// and leaves the timing judgment to the model — the reminder explicitly tells
+// it to stay quiet mid-task. The phase-boundary half is the `phase-workflow`
+// skill's job, model-side, where judgment actually lives.
+//
+// The number is real, not a proxy: Claude Code records per-request `usage` in
+// the transcript, and input_tokens + cache_read_input_tokens +
+// cache_creation_input_tokens is exactly the context that was re-sent.
+import { closeSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { claudeBaseDir } from './config-dir.mjs';
+
+// PO decision 2026-07-25 (TASK-079), frozen per the TASK-062 anti-bias rule:
+// a threshold that judges the session's own weight is the PO's call, not the
+// model's. Chosen from a measured 12.6h session (peak 547k tokens, 3
+// compactions): with fire-once-per-crossing, 80k/100k/120k/150k all produce
+// the SAME 4 reminders, so the choice is about how early the warning lands,
+// not about noise. 120k is ~60% of a standard 200k window and sits clearly
+// below the ~165k where that session's user compacted by hand.
+//
+// Override for a larger window (e.g. Opus 1M) — the transcript does NOT carry
+// the context-window size (checked: no such field), so this cannot be
+// auto-scaled and an absolute number is the honest interface.
+const DEFAULT_THRESHOLD_TOKENS = 120_000;
+
+// A drop to below this fraction of the previous reading means the context was
+// compacted or cleared, so the reminder re-arms. Deliberately loose: normal
+// turn-to-turn variation is a few percent, while a compaction cuts context by
+// 60-95% (measured: 166k->58k, 541k->23k, 165k->48k).
+const REARM_DROP_RATIO = 0.6;
+
+// Read only the tail: transcripts reach tens of MB (the session this was
+// built from was 9.4MB after 12.6h) and this runs on EVERY prompt, so parsing
+// the whole file would make the tool's own overhead grow with session length —
+// precisely the cost curve it exists to fight. The last entries are all we
+// need, and 256KB comfortably spans several of them.
+const TAIL_BYTES = 256 * 1024;
+
+export function thresholdTokens(env = process.env) {
+  const raw = env.TUNE_CONTEXT_REMIND_TOKENS;
+  if (raw === undefined) return DEFAULT_THRESHOLD_TOKENS;
+  const parsed = Number(raw);
+  // A malformed override must not silently disable the reminder, nor crash a
+  // prompt — fall back to the frozen default.
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_THRESHOLD_TOKENS;
+}
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/** Last TAIL_BYTES of a file as text, without reading what comes before it. */
+function readTail(path, bytes = TAIL_BYTES) {
+  const size = statSync(path).size;
+  const start = Math.max(0, size - bytes);
+  const length = size - start;
+  if (length === 0) return '';
+  const buf = Buffer.allocUnsafe(length);
+  const fd = openSync(path, 'r');
+  try {
+    readSync(fd, buf, 0, length, start);
+  } finally {
+    closeSync(fd);
+  }
+  return buf.toString('utf8');
+}
+
+/**
+ * Context size (tokens) of the most recent request recorded in the transcript,
+ * or null when the transcript has no usable entry yet.
+ *
+ * Scans backwards so the newest reading wins, and tolerates a partial first
+ * line: a tail read almost always starts mid-line, and that fragment simply
+ * fails JSON.parse and is skipped.
+ */
+export function latestContextTokens(transcriptText) {
+  const lines = transcriptText.split('\n');
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const usage = entry?.message?.usage;
+    if (!usage) continue;
+    const total =
+      (usage.input_tokens || 0) + (usage.cache_read_input_tokens || 0) + (usage.cache_creation_input_tokens || 0);
+    // Guard against the tiny synthetic entries Claude Code also writes.
+    if (total > 0) return total;
+  }
+  return null;
+}
+
+function stateFile() {
+  return join(claudeBaseDir(), 'tune-context', 'context-reminder.json');
+}
+
+function readState(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+// One entry per session id; sessions go stale the moment they end, so old
+// entries are dropped on write rather than accumulating forever (the same
+// hygiene TASK-076 gave state/).
+const STATE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+function pruneState(state, now) {
+  for (const [key, value] of Object.entries(state)) {
+    if (!value || typeof value.ts !== 'number' || now - value.ts > STATE_MAX_AGE_MS) delete state[key];
+  }
+  return state;
+}
+
+/**
+ * Pure decision: given the previous reading for this session and the current
+ * one, should a reminder fire, and what is the session's next state?
+ *
+ * Fires ONCE per crossing, not on every prompt above the threshold. A reminder
+ * costs tokens on the very prompt it appears in, so a context-efficiency tool
+ * that nagged every turn would be spending the thing it claims to save.
+ */
+export function decide(prev, total, threshold) {
+  let fired = prev?.fired === true;
+  // A large drop means the context was compacted/cleared: arm again so the
+  // NEXT time it grows past the threshold the user hears about it.
+  if (prev && typeof prev.last === 'number' && total < prev.last * REARM_DROP_RATIO) fired = false;
+
+  const remind = !fired && total >= threshold;
+  return { remind, next: { last: total, fired: fired || remind, ts: Date.now() } };
+}
+
+export function reminderText(total) {
+  const k = Math.round(total / 1000);
+  return [
+    `[tune-context] This session is now carrying ~${k}k tokens of context, and every further turn re-sends all of it.`,
+    'If the current work thread is finished: suggest /compact (or /clear when switching to unrelated work).',
+    'If you are mid-task: say nothing now and raise it when the thread closes.',
+    'The PreCompact hook preserves branch, dirty files and recent commits across a compaction — judgment calls and open threads are NOT preserved, so write those down first.',
+  ].join(' ');
+}
+
+// Never fails a prompt: this runs on EVERY UserPromptSubmit, so a broken or
+// unreadable transcript, an unwritable state dir or a malformed payload must
+// cost the user nothing. Same contract as adoption-log.mjs and (since
+// TASK-076) pre-compact-snapshot.mjs. Silence is the correct failure mode —
+// emitting nothing simply means no reminder this turn.
+function main() {
+  try {
+    const input = readStdin();
+    const transcriptPath = input.transcript_path;
+    if (!transcriptPath) return;
+
+    const total = latestContextTokens(readTail(transcriptPath));
+    if (total === null) return;
+
+    const session = input.session_id || 'unknown';
+    const path = stateFile();
+    const state = readState(path);
+    const { remind, next } = decide(state[session], total, thresholdTokens());
+
+    state[session] = next;
+    try {
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, JSON.stringify(pruneState(state, Date.now())));
+    } catch {
+      // Unwritable state only costs us the once-per-crossing memory; the
+      // reminder itself is still correct for this turn.
+    }
+
+    if (!remind) return;
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'UserPromptSubmit',
+          additionalContext: reminderText(total),
+        },
+      }),
+    );
+  } catch {
+    // non-fatal by design — never block a prompt over a reminder
+  }
+}
+
+if (process.argv[1] && process.argv[1].endsWith('context-reminder.mjs')) {
+  main();
+}

package/hooks/hooks.json

@@ -43,6 +43,17 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/context-reminder.mjs\""
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/pre-compact-snapshot.mjs

@@ -9,8 +9,14 @@
 // capture what the filesystem/git already know (branch, dirty files, recent
 // commits) — not decisions or open threads from the conversation. It is a
 // safety net against losing that mechanical state, not a summary.
+//
+// Claude Code also has a PostCompact event. Staying on PreCompact +
+// SessionStart(compact) is deliberate, not an oversight (TASK-078): this pair
+// is what TASK-056/061 proved out with a smoke-tested round trip, and nothing
+// since has needed PostCompact's different timing.
 import { execFileSync } from 'node:child_process';
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { claudeBaseDir } from './config-dir.mjs';
 
@@ -34,9 +40,50 @@ function git(cwd, args) {
   }
 }
 
+// Hash suffix makes this injective. The slug alone collapses distinct paths
+// that normalize the same way (/home/a/b and /home/a-b both slug to
+// "home-a-b"), which let two projects share one file — and SessionStart
+// (compact) would reinject one project's git state into an unrelated
+// session's compaction (TASK-076). Slug stays first for human readability;
+// the hash is what actually prevents the collision. Renaming the file shape
+// orphans pre-existing snapshots — acceptable, they're one-compaction-lived —
+// noted in CHANGELOG per the task.
 export function stateFilePath(cwd) {
   const safe = cwd.replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-+|-+$/g, '');
-  return join(claudeBaseDir(), 'tune-context', 'state', `${safe}.md`);
+  const hash = createHash('sha256').update(cwd).digest('hex').slice(0, 8);
+  return join(claudeBaseDir(), 'tune-context', 'state', `${safe}-${hash}.md`);
+}
+
+// PO decision 2026-07-25 (TASK-076): age-based, 30 days. One file per distinct
+// cwd (stateFilePath above) means every worktree or temp checkout a user ever
+// compacted in gets a permanent file, not just abandoned projects — and this
+// file is rewritten on every compaction of a still-active project, so mtime
+// age is an exact recency signal, not a proxy.
+const MAX_SNAPSHOT_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+// Self-contained like git() above: never throws, so a missing/unreadable
+// state/ directory or an unremovable file can't take the write down with it.
+// `keep` is excluded from consideration outright, not just by age, so the
+// snapshot this run just wrote can never be pruned regardless of mtime/clock
+// edge cases (no reliance on "the fresh write's mtime beats the cutoff").
+export function pruneStateDir(dir, keep) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const cutoff = Date.now() - MAX_SNAPSHOT_AGE_MS;
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const path = join(dir, entry.name);
+    if (path === keep) continue;
+    try {
+      if (statSync(path).mtimeMs < cutoff) unlinkSync(path);
+    } catch {
+      // gone already, or unremovable — not this hook's problem
+    }
+  }
 }
 
 export function buildSnapshot(input) {
@@ -61,11 +108,26 @@ export function buildSnapshot(input) {
   return lines.join('\n') + '\n';
 }
 
+// Never fails the host tool call: this snapshot is a safety net for a
+// compaction, not a critical feature, so its own failure can't be louder than
+// the context loss it guards against. An unwritable state dir (container,
+// read-only volume, misdirected CLAUDE_CONFIG_DIR) must not surface as a
+// nonzero exit at the exact moment the session is under context pressure.
+// Deliberately no console.error — hooks don't write to stdout/stderr
+// (transcript noise) — a silent safety-net failure is cheaper than a loud
+// one. Mirrors hooks/adoption-log.mjs's main(), which this file previously
+// lacked parity with (TASK-076).
 function main() {
-  const input = readStdin();
-  const path = stateFilePath(input.cwd || process.cwd());
-  mkdirSync(join(path, '..'), { recursive: true });
-  writeFileSync(path, buildSnapshot(input));
+  try {
+    const input = readStdin();
+    const cwd = input.cwd || process.cwd();
+    const path = stateFilePath(cwd);
+    mkdirSync(join(path, '..'), { recursive: true });
+    writeFileSync(path, buildSnapshot(input));
+    pruneStateDir(join(path, '..'), path);
+  } catch {
+    // non-fatal by design — never block a compaction over a snapshot write
+  }
 }
 
 if (process.argv[1] && process.argv[1].endsWith('pre-compact-snapshot.mjs')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bglocation/tune-context",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Context-efficiency configurator for Claude Code — token-saving doctrine packaged as skills, plus a tune-context configurator that scaffolds a lean CLAUDE.md, doctrine skills, subagents, settings, hooks and MCP wiring.",
   "type": "module",
   "license": "MIT",

package/skills/token-efficiency/SKILL.md

@@ -45,7 +45,9 @@ comments in the domain vocabulary someone would *search* with — better contrac
 ## 6. Measure, don't believe
 If the tool logs usage (`.rag/usage.jsonl` → `rag-usage`), review it
 periodically: is semantic search actually replacing grep? Promote or drop levers
-on data, not faith.
+on data, not faith. If `tune-context` is set up, `node eval/adoption-report.mjs`
+covers the rest of this doctrine the same way — search lever, skills, subagents,
+re-read churn — as a behavioral proxy (tool calls), not token cost.
 
 ## In a new project
 Set up semantic search proactively — `npx -p @bglocation/code-search-mcp