@bglocation/tune-context 1.1.0 → 2.0.1

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,7 +1,7 @@
 {
   "name": "@bglocation/tune-context",
-  "version": "1.1.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.",
+  "version": "2.0.1",
+  "description": "Context-efficiency configurator for Claude Code \u2014 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",
   "author": "Szymon Walczak",

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

package/skills/tune-context/SKILL.md

@@ -43,10 +43,32 @@ not guesses); monorepo vs single project (workspaces, `packages/`, `apps/`).
 | project | `./.mcp.json` |
 | user | `~/.claude.json` → top-level `mcpServers` |
 | local | `~/.claude.json` → `["<abs project path>"].mcpServers` |
-| gating | `settings.json`: `enabledMcpjsonServers`, `disabledMcpjsonServers`, `allowedMcpServers`, `deniedMcpServers` |
+| rejected | any `settings.json`: `disabledMcpjsonServers` (project `.mcp.json` servers only) |
 
 If `CLAUDE_CONFIG_DIR` is set, `.claude.json` lives there instead of `~`.
 
+**A rejected server is not a lever.** A project `.mcp.json` server named in
+`disabledMcpjsonServers` (in *any* settings file) is rejected — `claude mcp get`
+shows it as `✘ Rejected`. Skip it: no `mcp__<server>__*` permission rule, no
+CLAUDE.md line promising a capability this session does not have. Say which
+servers you skipped and why.
+
+Read the neighbouring keys carefully rather than by name — the three below look
+like the same mechanism and are not:
+- `enabledMcpjsonServers` — an *approval* list. A `.mcp.json` server that is
+  absent from it is **⏸ pending approval**, not disabled; the user is prompted
+  and may approve it. Do not treat absence as rejection.
+- `allowedMcpServers` / `deniedMcpServers` — arrays of **objects**
+  (`{serverName}` | `{serverUrl}` | `{serverCommand}`). They may sit in any
+  settings file and merge from every source, but they are organization policy,
+  not a per-project toggle: enforcement rests on a managed tier
+  (`managed-settings.json`, server-managed settings, MDM/registry), and matching
+  uses URL wildcards, `${VAR}` expansion and denylist-over-allowlist precedence.
+  The docs warn a `serverName` entry "is not a security control".
+- `disabledMcpServers` / `enabledMcpServers` (note: no `json`) — a *different*
+  pair, living per-project in `~/.claude.json`, covering user-configured,
+  plugin and claude.ai servers. Disjoint from the `…Mcpjson…` keys above.
+
 **Classify each server** — this is what turns "a server exists" into a rule:
 
 | Type | Rule to write into the project CLAUDE.md |
@@ -65,8 +87,9 @@ If `CLAUDE_CONFIG_DIR` is set, `.claude.json` lives there instead of `~`.
 **Existing config.** Note whether `./CLAUDE.md`, `.claude/settings.json`,
 `.mcp.json`, `rag.config.json` already exist — you will merge, never clobber.
 For `settings.json` also check `hooks.PreCompact` / `hooks.SessionStart` /
-`hooks.PostToolUse` / `hooks.SubagentStart` for an entry already calling
-`pre-compact-snapshot.mjs` / `session-start-reinject.mjs` / `adoption-log.mjs`
+`hooks.PostToolUse` / `hooks.SubagentStart` / `hooks.UserPromptSubmit` for an
+entry already calling `pre-compact-snapshot.mjs` / `session-start-reinject.mjs` /
+`adoption-log.mjs` / `context-reminder.mjs`
 (idempotency: skip if present — `adoption-log.mjs` is registered under both
 `PostToolUse` and `SubagentStart`) and `permissions.allow` for entries already
 covering the detected build/test/lint commands.
@@ -86,6 +109,9 @@ covering the detected build/test/lint commands.
    `phase-workflow` are present in `~/.claude/skills/` (they ship with this tool).
 4. **`.mcp.json`** — **merge**. Add a semantic-search server only if none was
    detected in any scope. Preserve every existing server and key.
+   *(Skill path only — the `tune-context` CLI reads `.mcp.json` but never writes
+   it: picking which server to add is a judgment call, and the CLI runs with no
+   model in the loop.)*
 5. **Hooks** — ensure `~/.claude/hooks/pre-compact-snapshot.mjs`,
    `~/.claude/hooks/session-start-reinject.mjs` and `~/.claude/hooks/adoption-log.mjs`
    exist (they ship with this tool, installed once user-level — same as the
@@ -95,10 +121,10 @@ covering the detected build/test/lint commands.
    Install the hooks directory as a set, never single files. Merge into `settings.json` from
    `${CLAUDE_SKILL_DIR}/templates/settings.json.tmpl`: append the `PreCompact`
    (matcher `"*"`, docs: omit or `*` = every trigger), `SessionStart`
-   (matcher `"compact"`), `PostToolUse` (matcher `"*"`) and `SubagentStart`
-   (matcher `"*"`) entries **only if an entry calling that script isn't already
-   there** — treat each hook array as a set keyed by `command`, not a value to
-   overwrite.
+   (matcher `"compact"`), `PostToolUse` (matcher `"*"`), `SubagentStart`
+   (matcher `"*"`) and `UserPromptSubmit` (matcher `"*"`) entries **only if an
+   entry calling that script isn't already there** — treat each hook array as a
+   set keyed by `command`, not a value to overwrite.
    - The template's `{{HOOKS_DIR}}` slot decides where those commands point.
      **Default: `$HOME/.claude/hooks`** — keep the literal `$HOME` (expanded when
      the hook fires, so `settings.json` stays portable between machines).
@@ -122,14 +148,30 @@ covering the detected build/test/lint commands.
      contracts-first edits) is likewise not `Skill`-call-visible — the verdict
      reports zero `Skill` calls as a neutral note, not "unused", and points at the
      edit:read ratio as a partial proxy.
-   - Both state paths resolve through `hooks/config-dir.mjs`'s `claudeBaseDir()` —
-     same `CLAUDE_CONFIG_DIR || ~/.claude` rule as the registration paths above, so
-     an override isolates state too, not just script locations.
+   - `context-reminder.mjs` is registered under `UserPromptSubmit` (matcher `"*"`).
+     It reads the **tail** of the session transcript (`transcript_path`, present on
+     every hook payload), sums `input_tokens + cache_read + cache_creation` — the
+     context actually re-sent — and once that crosses a PO-frozen threshold
+     (120k, override `TUNE_CONTEXT_REMIND_TOKENS`) injects one short reminder to
+     consider `/compact`. Fires **once per crossing**, re-arming only after a
+     compaction-sized drop: the reminder costs tokens on the prompt it appears in,
+     so nagging every turn would spend exactly what the tool saves. It reminds on
+     SIZE, not on "phase boundary" — size is measurable from the transcript, a
+     phase boundary is a judgment a hook (no model access) cannot make, so the
+     reminder hands that timing call to the model and `phase-workflow`.
+   - All three state paths resolve through `hooks/config-dir.mjs`'s
+     `claudeBaseDir()` — same `CLAUDE_CONFIG_DIR || ~/.claude` rule as the
+     registration paths above, so an override isolates state too, not just script
+     locations.
 6. **`settings.json` permissions** — merge `permissions.allow`: the project's
    safe, frequent commands (build/test/lint, `git status`/`diff`/`log`) and
-   `mcp__<server>__<tool>` for detected servers. Union with the existing array
+   `mcp__<server>__<tool>` for detected servers — **excluding servers rejected
+   via `disabledMcpjsonServers`** (see §1). Union with the existing array
    (dedupe, never remove entries). Never add blanket `Bash(*)` or bypass modes.
 7. **Wiki** — wire the lever chosen in detection (segment / MCP note / pointer).
+   *(Skill path only — the CLI neither detects the wiki location nor wires this
+   lever; choosing between a RAG segment, a dedicated MCP and a plain pointer
+   needs judgment.)*
 
 Keep the generated CLAUDE.md **thin**: headings and pointers only. Depth belongs
 in skills — that is the whole point of this setup.
@@ -149,10 +191,11 @@ in skills — that is the whole point of this setup.
   should exit 0 without throwing; same for `adoption-log.mjs`).
 - **The merge actually landed — don't just trust step 5 ran.** Re-read the
   target `settings.json` (the same file you merged into) and parse it: confirm
-  `hooks.PreCompact`, `hooks.SessionStart`, `hooks.PostToolUse` and
-  `hooks.SubagentStart` each contain an entry whose `command` references the
-  expected script (`pre-compact-snapshot.mjs` / `session-start-reinject.mjs` /
-  `adoption-log.mjs` twice, for `PostToolUse` and `SubagentStart`). Copying the
+  `hooks.PreCompact`, `hooks.SessionStart`, `hooks.PostToolUse`,
+  `hooks.SubagentStart` and `hooks.UserPromptSubmit` each contain an entry whose
+  `command` references the expected script (`pre-compact-snapshot.mjs` /
+  `session-start-reinject.mjs` / `adoption-log.mjs` twice, for `PostToolUse` and
+  `SubagentStart` / `context-reminder.mjs`). Copying the
   hook scripts to `~/.claude/hooks/` is not sufficient — a real prior incident
   had the scripts present and executable while `settings.json` had **no**
   `hooks` key at all, so the hooks silently never fired. Scripts-exist and

package/skills/tune-context/templates/settings.json.tmpl

@@ -43,16 +43,17 @@
           }
         ]
       }
-    ]
-  },
-  "permissions": {
-    "allow": [
-      "Bash({{BUILD_CMD}}:*)",
-      "Bash({{TEST_CMD}}:*)",
-      "Bash({{LINT_CMD}}:*)",
-      "Bash(git status:*)",
-      "Bash(git diff:*)",
-      "Bash(git log:*)"
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"{{HOOKS_DIR}}/context-reminder.mjs\""
+          }
+        ]
+      }
     ]
   }
 }