@bglocation/tune-context 1.1.0 → 2.0.0

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\""
+          }
+        ]
+      }
     ]
   }
 }