@bglocation/tune-context 1.0.1 → 2.0.0

package/hooks/pre-compact-snapshot.mjs

@@ -9,10 +9,16 @@
 // 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 { homedir } from 'node:os';
+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';
 
 function readStdin() {
   try {
@@ -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(homedir(), '.claude', '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.0.1",
+  "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",
@@ -32,13 +32,15 @@
     "hooks",
     "eval",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
+    "test": "node --test",
     "verify:pack": "node scripts/verify-pack.mjs",
     "verify:plugin": "node scripts/verify-plugin.mjs",
     "smoke:init": "node scripts/smoke-init.mjs",
-    "prepublishOnly": "npm run verify:pack && npm run verify:plugin && npm run smoke:init"
+    "prepublishOnly": "npm test && npm run verify:pack && npm run verify:plugin && npm run smoke:init"
   },
   "publishConfig": {
     "access": "public"

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,33 +109,69 @@ 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
-   doctrine skills in step 3). Merge into `settings.json` from
+   doctrine skills in step 3), **plus `~/.claude/hooks/config-dir.mjs`** — the
+   snapshot and adoption-log scripts import it for their state paths, so
+   installing them without it means `Cannot find module` on every event.
+   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).
+     **Under `CLAUDE_CONFIG_DIR`: the literal `<override>/hooks`** — that is where
+     the scripts are actually installed (the config dir moves, so must the path).
+     A hardcoded `$HOME/.claude/hooks` under an override points at a dir the
+     scripts were never copied to, and the hooks silently never fire. Verify with
+     the path cross-check in §3, not just "the command mentions the script".
    - `PreCompact` writes a mechanical git/branch/status snapshot per-project to
-     `~/.claude/tune-context/state/`; `SessionStart(compact)` reads it back via
-     `additionalContext`. Filesystem/git facts only — not decisions/open threads
-     (a hook has no model access).
+     `~/.claude/tune-context/state/` by default; `SessionStart(compact)` reads it
+     back via `additionalContext`. Filesystem/git facts only — not decisions/open
+     threads (a hook has no model access).
    - `adoption-log.mjs` is registered under **both** `PostToolUse` (every tool
      call) and `SubagentStart` (subagent spawns — these are NOT PostToolUse tools,
      they fire their own event carrying `agent_type`). It appends one line per
-     event to `~/.claude/tune-context/adoption.jsonl` — which lever the model
-     reached for (RAG vs grep, Skill, subagent, re-reads). Read it with
+     event to `~/.claude/tune-context/adoption.jsonl` by default — which lever the
+     model reached for (RAG vs grep, Skill, subagent, re-reads). Read it with
      `eval/adoption-report.mjs` (the `rag-usage` analog). Behavioral proxy only:
      no token cost (needs OTEL `claude_code.cost.usage` + a collector) and no
-     caveman (an output style, not a tool call).
+     caveman (an output style, not a tool call). Doctrine-as-method (narrow reads,
+     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.
+   - `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.
@@ -132,14 +191,30 @@ 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
   entries-are-registered are two different, both-required checks.
+- **Cross-check the path, don't just match the name.** For each registered hook,
+  the path in its `command` must resolve to **the same file** you installed —
+  not merely contain the script's name. Expand `$HOME`/`${HOME}` (to
+  `CLAUDE_CONFIG_DIR`-aware `~/.claude`, the same base you install into),
+  `resolve` both sides, and compare. Under `CLAUDE_CONFIG_DIR` the script lands
+  in `$CLAUDE_CONFIG_DIR/hooks/` while a hardcoded `$HOME/.claude/hooks/` command
+  points elsewhere — both the "name is present" and "file exists" checks pass
+  independently while the wiring is broken. If a command can't be parsed for a
+  path, say so out loud; a silent OK is worse than a false alarm.
+  Check **every** command that names the script, not the first match: the merge
+  is a set keyed by command, so a path change leaves the old entry next to the
+  new one, and Claude Code runs both. At least one must resolve to the installed
+  file; any other that resolves to a **missing** file is a dead wire erroring on
+  every event — report it (with which file to remove), don't pass over it. A
+  duplicate resolving to a file that exists runs twice but works — note it.
 - **Idempotency:** a second run would produce no changes.
 
 Report what you created, what you merged, and anything you deliberately skipped.

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

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.claude/hooks/pre-compact-snapshot.mjs\""
+            "command": "node \"{{HOOKS_DIR}}/pre-compact-snapshot.mjs\""
           }
         ]
       }
@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.claude/hooks/session-start-reinject.mjs\""
+            "command": "node \"{{HOOKS_DIR}}/session-start-reinject.mjs\""
           }
         ]
       }
@@ -28,7 +28,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.claude/hooks/adoption-log.mjs\""
+            "command": "node \"{{HOOKS_DIR}}/adoption-log.mjs\""
           }
         ]
       }
@@ -39,20 +39,21 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.claude/hooks/adoption-log.mjs\""
+            "command": "node \"{{HOOKS_DIR}}/adoption-log.mjs\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"{{HOOKS_DIR}}/context-reminder.mjs\""
           }
         ]
       }
-    ]
-  },
-  "permissions": {
-    "allow": [
-      "Bash({{BUILD_CMD}}:*)",
-      "Bash({{TEST_CMD}}:*)",
-      "Bash({{LINT_CMD}}:*)",
-      "Bash(git status:*)",
-      "Bash(git diff:*)",
-      "Bash(git log:*)"
     ]
   }
 }