@bglocation/tune-context 2.2.0 → 2.3.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "tune-context",
       "source": "./",
       "description": "Context-efficiency configurator for Claude Code: doctrine skills (token-efficiency, caveman, cdd, phase-workflow) plus a tune-context configurator that scaffolds a lean CLAUDE.md, subagents, settings and hooks.",
-      "version": "2.2.0",
+      "version": "2.3.1",
       "author": {
         "name": "Szymon Walczak",
         "url": "https://bglocation.dev"

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "tune-context",
   "displayName": "tune-context",
   "description": "Context-efficiency configurator for Claude Code: doctrine skills (token-efficiency, caveman, cdd, phase-workflow) plus a tune-context configurator that scaffolds a lean CLAUDE.md, subagents, settings and hooks.",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "author": {
     "name": "Szymon Walczak",
     "url": "https://bglocation.dev"

package/CHANGELOG.md

@@ -5,6 +5,90 @@ All notable changes to `@bglocation/tune-context` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.1] — 2026-07-28
+
+### Fixed
+
+- **The context reminder no longer goes quiet for 120k tokens at a stretch.** A
+  middle rung at **1.5× the threshold** (180k by default) joins the existing
+  120k and 240k, cutting the worst-case silence between notices from 120k to
+  60k. Reported from use: 120k is often too early to close a work thread, while
+  240k is far enough away that a session has to be dragged out to reach it, and
+  180k is where a phase boundary tends to land. The ladder is expressed as
+  multipliers (1×/1.5×/2×), so `TUNE_CONTEXT_REMIND_TOKENS` still scales all
+  three — a 400k threshold gives 400k/600k/800k.
+- **Each rung is now louder than the last, instead of repeating itself.** The
+  reminder's mid-task sentence is what escalates: wait for a natural break at
+  120k, raise it at the next pause anyway at 180k, say it this turn at 240k. A
+  third identical notice would just be the same coin flipped again. This also
+  fixes a real defect the third rung would otherwise have introduced — the
+  second notice used to call itself "second and final", which on a three-rung
+  ladder is false, and Claude weighs exactly that ("nothing more is coming")
+  when deciding whether to stay quiet.
+- **Docs describing the reminder as firing once.** `README.md` and the
+  `tune-context` skill both still said "a single short note" / "fires once per
+  crossing" — wrong since 2.1.0 added the second notice, not just since this
+  release.
+
+### Notes
+
+- The level-1 text is byte-identical to previous releases. A session live across
+  the upgrade whose state already recorded the old final notice earns one extra
+  notice, once, and then goes quiet — the two-rung and three-rung ladders write
+  the same number for different meanings, and a permanent ladder-version field
+  was not worth one notice.
+- This release touches `hooks/`, so **re-run `tune-context init`** (or the
+  dev-loop sync) after upgrading — `npm i -g` does not refresh hooks already
+  copied into `~/.claude/hooks/`. `tune-context verify` reports the drift.
+
+## [2.3.0] — 2026-07-28
+
+### Added
+
+- **The adoption report can now tell "RAG installed and ignored" from "no RAG
+  here"** — the blind spot 2.0.0 accepted on purpose, and the finding the report
+  most wants to surface. A new `~ RAG likely available, not reached for` line
+  appears when a project's `.mcp.json` declares a semantic-search MCP server, no
+  settings file rejects it, and that file is **older than every session logged in
+  that project**. It is never a ✗: config lists servers, not their tools, so the
+  claim is "probably within reach", not "it existed". Four guards keep it from
+  fabricating one — rejected servers (`disabledMcpjsonServers`) don't count, a
+  config file touched during or after the sessions drops back to unknown,
+  observation always wins (a project that actually called `search_codebase` is
+  never judged from config), and the frozen session floor now applies **per
+  project** as well as globally, because the claim is per project: a busy log can
+  still contain a project with a single session, and absence over one session is
+  not absence. User-scope servers stay unknown by design: `~/.claude.json` is
+  rewritten by Claude Code continuously, so its timestamp can't date anything
+  (TASK-083).
+
+### Fixed
+
+- **One RAG-using project no longer counts as coverage for all the others.**
+  Search was tallied globally while the verdict spoke about "these sessions", so
+  a single project with RAG lifted the counter above zero and every other project
+  read as covered. Search is now counted per project as well, which is what
+  TASK-070 specified and never landed — visible in the report as an availability
+  verdict decided project by project.
+
+- **A malformed log line can no longer take the whole report down.** `parseLog`
+  validates only `lever`, so `cwd` could be any JSON value — and the new probe
+  joins it into a filesystem path. Non-string `cwd`s are now ignored as projects
+  while still counting toward the global figures.
+
+### Documentation
+
+- **The README said the `/tune-context` skill needs the plugin. It doesn't.**
+  `tune-context init` installs the skill into `~/.claude/skills/` along with the
+  doctrine skills, so a plain `npm i -g` gives you both entry points (and the
+  plugin gives you both too, by putting `bin/tune-context` on `PATH`). Adds a
+  skill-vs-CLI comparison covering what a reader asks first — session, tokens,
+  repeatability — not just the two steps the CLI omits.
+
+- **`--force-claude-md` is documented outside `--help` for the first time.** It is
+  the one flag that discards content the tool otherwise refuses to touch, so it
+  should be the best-documented flag rather than the least.
+
 ## [2.2.0] — 2026-07-27
 
 ### Changed
@@ -380,6 +464,8 @@ action needed on upgrade.
   (`explore-cheap`, `reviewer`), the PreCompact / SessionStart / PostToolUse hook
   suite, and the adoption report (`eval/adoption-report.mjs`).
 
+[2.3.1]: https://gitlab.com/bglocation/tune-context/-/tags/v2.3.1
+[2.3.0]: https://gitlab.com/bglocation/tune-context/-/tags/v2.3.0
 [2.2.0]: https://gitlab.com/bglocation/tune-context/-/tags/v2.2.0
 [2.1.0]: https://gitlab.com/bglocation/tune-context/-/tags/v2.1.0
 [2.0.1]: https://gitlab.com/bglocation/tune-context/-/tags/v2.0.1

package/README.md

@@ -61,8 +61,11 @@ npm install -g @bglocation/tune-context
 tune-context init            # in any repo
 ```
 
-Prefer the model-driven path? Install the plugin and use the skill — it does the
-same thing plus wiki wiring and richer MCP detection:
+The command above also installs the **`/tune-context` skill** into
+`~/.claude/skills/`, so you can type it in a Claude session straight away — it does
+the same thing plus wiki wiring and richer MCP detection. Installing the plugin
+instead gets you the skill without the npm install, and updates through
+`/plugin marketplace update`:
 
 ```text
 /plugin marketplace add https://gitlab.com/bglocation/tune-context.git
@@ -79,11 +82,19 @@ The section below breaks down all three entry points and when to use each.
 
 Three entry points, same doctrine. Pick whichever fits how you work:
 
-**1. `/tune-context` skill (recommended).** With the plugin installed (below), run
-`/tune-context` in any repo. It detects the stack, MCP servers and existing config,
-then generates a lean project `CLAUDE.md`, wires the doctrine skills, and merges
-hooks + permissions — idempotently, never clobbering hand-written content. This is
-the full-fidelity path (it also handles wiki wiring and semantic-search detection).
+**1. `/tune-context` skill (recommended).** Type `/tune-context` in a Claude Code
+session, in the repo you want to configure. It detects the stack, MCP servers and
+existing config, then generates a lean project `CLAUDE.md`, wires the doctrine
+skills, and merges hooks + permissions — idempotently, never clobbering
+hand-written content. This is the full-fidelity path (it also handles wiki wiring
+and semantic-search detection).
+
+**Either channel gives you the skill.** The plugin installs it, and so does
+`tune-context init` — the CLI copies `skills/tune-context/` into
+`~/.claude/skills/` along with the doctrine skills. So a plain `npm i -g` gives you
+*both* entry points, and so does the plugin (it puts `bin/tune-context` on `PATH`
+while enabled). Claude never reaches for it on its own: the skill is marked
+`disable-model-invocation`, so it runs only when you type it.
 
 **2. CLI `tune-context init`.** The deterministic **subset** of the skill — same
 managed-block rules, same never-clobber guarantee, no model in the loop. Good for
@@ -99,15 +110,38 @@ node bin/tune-context.mjs init --cwd /path/to/your/repo
 It prints what it detected, what it synced/merged, and a verification report; a
 second run is a no-op.
 
-Two steps of the skill have **no CLI equivalent**, because each needs judgment a
-deterministic tool cannot supply — run `/tune-context` if you want them:
+Two flags are worth knowing:
+
+- **`--cwd <dir>`** — configure another repo instead of the current directory.
+- **`--force-claude-md`** — *destructive, opt-in, and normally unnecessary.* If a
+  `CLAUDE.md` still has hand-written content **inside** the managed block (the
+  layout used before 2.2.0), `init` refuses to regenerate it and says so —
+  "hand-written content sits inside the managed block — regenerating would erase
+  it". The fix is to move that prose below the closing marker, where the tool
+  never reaches. This flag regenerates anyway and **discards** it; use it only
+  when there is nothing in there worth keeping.
+
+### `/tune-context` vs `tune-context init`
 
-| Step | Skill | CLI |
+They are two different kinds of thing. The skill is a **procedure Claude follows**,
+so it can look at your repo and decide; the CLI is **code that runs**, so it does
+exactly what it was written to do, every time. Same doctrine, same managed-block
+rules, same never-clobber guarantee.
+
+| | `/tune-context` (skill) | `tune-context init` (CLI) |
 |---|---|---|
+| Where you run it | Claude Code chat | terminal, incl. CI |
+| Needs a Claude session | yes | no — plain Node ≥ 18 |
+| Costs tokens | yes | no |
+| Two runs, same repo | judgment may vary | byte-identical |
 | Project `CLAUDE.md`, doctrine skills, hooks, permissions | ✅ | ✅ |
 | Merge `.mcp.json` — add a semantic-search server if none was detected | ✅ | ❌ reads it, never writes it |
 | Wiki lever — RAG segment vs its own MCP vs a plain pointer | ✅ | ❌ not detected, not wired |
 
+Both write the same block into the same files, so mixing them is safe: script the
+CLI where you want repeatability, and run the skill when you want the two judgment
+steps it alone can do.
+
 **3. Plugin install.** Load the plugin so the skills, agents and hooks are available
 in every session. The best UX is the **marketplace** — install once, get updates
 with `/plugin marketplace update`:
@@ -183,23 +217,27 @@ many tokens it is re-sending, and Claude Code has no timer or context-threshold
 hook event. So `context-reminder.mjs` (registered under `UserPromptSubmit`)
 supplies the missing measurement: it reads the tail of the session transcript,
 sums the tokens actually re-sent, and once that passes **120,000** it injects a
-single short note suggesting `/compact`.
+short note suggesting `/compact`.
 
 - **The note goes to Claude, not to your screen.** Hooks can only reach you
   through the model — a `systemMessage` on this event was measured and does not
   render — so what you actually see is Claude bringing it up in its reply.
-- **The model picks the moment.** The note tells Claude to stay quiet mid-task
-  and raise it at the first natural break: the hook can measure size, but only
-  the model can see whether you're mid-refactor.
-- **Twice per crossing at most.** Once at the threshold, once more at **240,000**
-  if the context keeps growing — because a note that lands mid-task can be
-  correctly absorbed and then forgotten. Measured on one session: it fired at
-  166k, Claude stayed silent, and nothing spoke again until 346k. The second
-  notice halves that blind spot; there is deliberately no third.
+- **The model picks the moment — at first.** The hook can measure size, but only
+  Claude can see whether you're mid-refactor, so the first note tells it to stay
+  quiet mid-task and raise it at the next natural break. That deference runs out:
+  see the ladder below. A session that never reaches a "natural break" is exactly
+  the one paying the most for the wait.
+- **Three notes per crossing at most — 120,000 / 180,000 / 240,000.** A note that
+  lands mid-task can be correctly absorbed and then forgotten. Measured on one
+  session: it fired at 166k, Claude stayed silent, and nothing spoke again until
+  346k. Each rung halves that blind spot, and each one is *louder* than the last:
+  at 120k Claude is told to wait for a natural break, at 180k to raise it at the
+  next pause anyway, at 240k to say it this turn whatever it is doing. There is
+  deliberately no fourth — the reminder costs tokens on the prompt it appears in.
 - **Raise it for a large context window:** `export TUNE_CONTEXT_REMIND_TOKENS=400000`.
   120k is ~60% of a standard 200k window; the transcript doesn't record the window
-  size, so this can't be auto-scaled. Both levels scale with the override — the
-  second notice is always at twice the threshold.
+  size, so this can't be auto-scaled. The whole ladder scales with the override —
+  the rungs are always 1×, 1.5× and 2× the threshold (400k/600k/800k here).
 - **Turn it off:** delete the `UserPromptSubmit` entry from `settings.json`.
 
 Depth lives in the `phase-workflow` and `token-efficiency` skills (both installed
@@ -212,12 +250,25 @@ override's `tune-context/adoption.jsonl` — see above), and `eval/adoption-repo
 turns that into a report — code search (semantic RAG vs the Grep tool, with
 shell-plumbing greps kept out of the RAG share), doctrine skills, subagents, and
 re-read churn — closing with an *earned* verdict: withheld below a PO-frozen floor of
-distinct sessions, and never a false ✗ for a lever the log can't see (RAG
-installed-but-unused vs not installed; method-level doctrine that leaves no tool call).
-It's registered under two Claude Code hook events —
+distinct sessions, and never a false ✗ for a lever the log can't see (method-level
+doctrine leaves no tool call at all). It's registered under two Claude Code hook events —
 `PostToolUse` (every tool call) and `SubagentStart` (subagent spawns, which aren't
 regular tools).
 
+**"RAG installed but ignored" vs "no RAG here"** is the one gap the log alone cannot
+close, and it happens to be the finding the report most wants — so it asks the config,
+per project, and only as far as the config can honestly answer. A
+`~ RAG likely available, not reached for` line appears when that project's `.mcp.json`
+declares a semantic-search server, no settings file rejects it, and the file is *older*
+than every session logged there. Everything else stays `·` unknown: config written
+during or after those sessions says nothing about them, and user-scope servers
+(`~/.claude.json`) can't be dated at all, since Claude Code rewrites that file
+continuously. It is never a ✗ — config names servers, not their tools, so the line
+claims the lever was probably within reach, not that it existed. It also answers to
+the same frozen session floor as the rest of the verdict, applied **per project**:
+"available and never reached for" is a claim about absence, and one logged session
+cannot establish absence.
+
 **Using both the plugin and `tune-context init` (CLI) on the same repo** registers
 the hook twice — once per channel — so every event logs twice. This is harmless
 (same script, same log, just doubled counts) and the report detects it: past a

package/eval/adoption-report.mjs

@@ -10,10 +10,16 @@
 //     (`claude_code.cost.usage`, needs a collector) — never a hook. This report
 //     measures *behavior* (a proxy), not dollars. OTEL is the opt-in complement.
 //   • caveman can't be measured: it's an output style, not a tool call.
+//   • RAG availability (the `~` line in the verdict) rests on a project's
+//     `.mcp.json` declaring a semantic-search server that predates the sessions
+//     — config, not introspection. It does NOT prove the server exposed
+//     `search_codebase`, and it says nothing about user-scope servers, whose
+//     config file carries no usable timestamp. See eval/mcp-probe.mjs (TASK-083).
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 import { claudeBaseDir } from '../hooks/config-dir.mjs';
+import { classifyAvailability, probeProjectMcp } from './mcp-probe.mjs';
 
 const DOCTRINE_SKILLS = new Set([
   'token-efficiency',
@@ -127,13 +133,29 @@ function countDuplicateRegistrationPairs(records) {
   return { pairs, assessable };
 }
 
-export function aggregate(records) {
+/**
+ * @param {object[]} records
+ * @param {{probe?: (cwd: string) => {names: string[], mtimeMs: number|null}}} [options]
+ *        probe - MCP config probe, injectable for tests (see eval/mcp-probe.mjs).
+ */
+export function aggregate(records, { probe = probeProjectMcp } = {}) {
   const search = { rag: 0, grepTool: 0, shell: 0, glob: 0 };
   const skills = new Map();
   const subagents = new Map();
   const readCounts = new Map(); // `${session}\u0000${file}` -> times read in that session
   const sessionSet = new Set();
   const cwdSet = new Set();
+  // TASK-083: search counted per project as well as globally. The global
+  // counter alone reads one RAG-using project as coverage for all the others —
+  // TASK-070 already specified this denominator as per-cwd, and it never landed.
+  const searchByCwd = new Map(); // cwd -> {rag, grepTool, shell, glob}
+  // Inputs to the availability probe's temporal guard. Session start is the
+  // earliest ts of ANY record in that session, not the earliest one in this
+  // cwd: a session that began elsewhere and moved here started before its first
+  // record here, and dating the config against the later value would loosen the
+  // guard in exactly the direction that fabricates verdicts.
+  const sessionStart = new Map(); // session key -> earliest ts (ms), or null if any record lacks one
+  const cwdSessions = new Map(); // cwd -> Set(session key)
   let reads = 0;
   let edits = 0;
   let bash = 0;
@@ -143,7 +165,30 @@ export function aggregate(records) {
 
   for (const r of records) {
     if (r.session != null) sessionSet.add(r.session);
-    if (r.cwd != null) cwdSet.add(r.cwd);
+    // A record with no cwd gets NO bucket of its own and can never promote a
+    // project to 'configured': there is no project whose config we could check.
+    // It still counts toward every global figure. Non-string cwds are treated
+    // the same way rather than trusted: the probe joins this value into a path,
+    // and parseLog vets only `lever`, so a malformed line could otherwise take
+    // the whole report down.
+    if (typeof r.cwd === 'string' && r.cwd !== '') {
+      cwdSet.add(r.cwd);
+      if (!searchByCwd.has(r.cwd)) searchByCwd.set(r.cwd, { rag: 0, grepTool: 0, shell: 0, glob: 0 });
+      if (!cwdSessions.has(r.cwd)) cwdSessions.set(r.cwd, new Set());
+      cwdSessions.get(r.cwd).add(r.session ?? '');
+    }
+    // One undateable record poisons its session's start: the missing ts could
+    // have been the earliest, so the guard would have nothing sound to compare
+    // against and every project that session touched falls back to 'unknown'.
+    const startKey = r.session ?? '';
+    const startedAt = Date.parse(r.ts);
+    if (!sessionStart.has(startKey)) {
+      sessionStart.set(startKey, Number.isNaN(startedAt) ? null : startedAt);
+    } else {
+      const known = sessionStart.get(startKey);
+      if (known !== null) sessionStart.set(startKey, Number.isNaN(startedAt) ? null : Math.min(known, startedAt));
+    }
+    const perCwd = searchByCwd.get(r.cwd) ?? null;
     switch (r.lever) {
       case 'search': {
         // Split content search by TOOL — the only reliable "is this a codebase
@@ -154,10 +199,19 @@ export function aggregate(records) {
         // so the split reinterprets existing logs — no format change, hook
         // untouched. See TASK-069.
         const tool = typeof r.tool === 'string' ? r.tool : '';
-        if (r.detail === 'rag' || tool.includes('search_codebase')) search.rag++;
-        else if (r.detail === 'glob' || tool === 'Glob') search.glob++;
-        else if (tool === 'Grep') search.grepTool++;
-        else search.shell++; // Bash-grep / ambiguous — reported, excluded from RAG-share
+        // One classification, counted twice: globally and into this project's
+        // bucket. Splitting the rule in two would let the per-project view and
+        // the global view disagree about what a RAG call is.
+        const kind =
+          r.detail === 'rag' || tool.includes('search_codebase')
+            ? 'rag'
+            : r.detail === 'glob' || tool === 'Glob'
+              ? 'glob'
+              : tool === 'Grep'
+                ? 'grepTool'
+                : 'shell'; // Bash-grep / ambiguous — reported, excluded from RAG-share
+        search[kind]++;
+        if (perCwd) perCwd[kind]++;
         break;
       }
       case 'skill':
@@ -210,12 +264,54 @@ export function aggregate(records) {
   const { pairs: dedupPairs, assessable: dedupAssessable } = countDuplicateRegistrationPairs(records);
   const dedupShare = dedupAssessable > 0 ? dedupPairs / dedupAssessable : 0;
 
+  // Was RAG even available in each project? Decided per cwd, so one RAG-using
+  // project can no longer cover for the rest (TASK-083). A project is dated by
+  // the EARLIEST session that touched it: the claim "configured before these
+  // sessions" has to hold for all of them, and one unknown start makes the
+  // whole project unknown.
+  const availability = { observed: 0, configured: 0, unknown: 0, byCwd: [], names: [] };
+  const configuredNames = new Set();
+  for (const cwd of [...cwdSet].sort()) {
+    const sessionsHere = cwdSessions.get(cwd);
+    let sessionStartMs = null;
+    for (const key of sessionsHere) {
+      const start = sessionStart.get(key) ?? null;
+      if (start === null) {
+        sessionStartMs = null;
+        break;
+      }
+      sessionStartMs = sessionStartMs === null ? start : Math.min(sessionStartMs, start);
+    }
+    const { tier, names } = classifyAvailability(cwd, {
+      ragObserved: searchByCwd.get(cwd).rag > 0,
+      sessionStartMs,
+      // The SAME PO-frozen floor as the global verdict, applied where the claim
+      // is actually made. Judgments moved per-project in TASK-083, and the
+      // global count stopped guaranteeing a per-project sample: a log with 10
+      // sessions can hold a project with one, and "available, never reached
+      // for" over one session is exactly the trend-from-a-sample the floor
+      // exists to refuse. No new threshold is chosen here — the number stays
+      // frozen above, this only stops the probe routing around it.
+      sampleSuffices: sessionsHere.size >= MIN_SESSIONS_FOR_VERDICT,
+      probe,
+    });
+    availability[tier]++;
+    availability.byCwd.push([cwd, tier]);
+    for (const name of names) configuredNames.add(name);
+  }
+  availability.names = [...configuredNames].sort();
+
   return {
     total: records.length,
     sessions: sessionSet.size,
     cwds: cwdSet.size,
     search,
     ragShare,
+    // Per-project search counts and the availability tier each one earned.
+    // Presentation stays a single aggregate verdict line (PO decision 3,
+    // 2026-07-27); these are what a per-project section would be built from.
+    searchByCwd: [...searchByCwd.entries()].sort((a, b) => a[0].localeCompare(b[0])),
+    availability,
     skills: [...skills.entries()].sort((a, b) => b[1] - a[1]),
     subagents: [...subagents.entries()].sort((a, b) => b[1] - a[1]),
     reads,
@@ -319,16 +415,26 @@ export function formatReport(a) {
           ' One session is a sample, not a trend; collect more, then re-run.',
       );
     } else {
-      if (a.search.rag === 0) {
+      const { configured, unknown } = a.availability;
+      // The `~` line speaks only for the projects the probe could judge, so it
+      // may replace this one only when that is ALL of them. Otherwise the
+      // projects it cannot judge would go unmentioned entirely — a worse
+      // silence than the blind spot TASK-070 admitted to out loud.
+      const probeSpeaksForEveryProject = configured > 0 && unknown === 0;
+      if (a.search.rag === 0 && !probeSpeaksForEveryProject) {
         // Availability (Option 1, PO 2026-07-24): search_codebase never observed
         // → report as unavailable, never ✗ and never ✓. The behavioral log can't
         // tell "RAG not installed here" from "installed but never reached for",
         // so it must not accuse — a known, accepted blind spot (TASK-070 notes).
+        // TASK-083 leaves this wording untouched for the case it was written
+        // for: no observation AND no config the probe could date. When the probe
+        // does have something, the `~` line below replaces this one — it answers
+        // the very question this sentence admits it cannot.
         L.push(
           '  · RAG not observed — no search_codebase in these sessions. Not counted' +
             ' as ✗: can\'t tell "not installed" from "installed but unused".',
         );
-      } else {
+      } else if (a.search.rag > 0) {
         // rag > 0 ⇒ denominator (rag + grepTool) > 0 ⇒ ragShare is a number.
         L.push(
           a.ragShare >= 0.5
@@ -336,6 +442,20 @@ export function formatReport(a) {
             : '  ✗ RAG lever weak — grep still dominates code search. Revisit index/skill wiring.',
         );
       }
+      // Earned middle state (TASK-083, PO decision 1): the project declares a
+      // non-rejected semantic-search server in a `.mcp.json` older than every
+      // session logged there, and search_codebase still never appears. Soft `~`,
+      // never a hard ✗ — config names servers, not tools, so this is evidence
+      // the lever was probably within reach, not proof it was.
+      if (configured > 0) {
+        const names = a.availability.names;
+        L.push(
+          `  ~ RAG likely available, not reached for — ${configured} of ${a.cwds} project(s) declare` +
+            ` a semantic-search MCP server in .mcp.json (${names.join(', ')}) predating every session` +
+            ' logged there, yet no search_codebase call. Config, not introspection:' +
+            ` confirm with \`claude mcp get ${names[0]}\`.`,
+        );
+      }
       // Zero `Skill` calls is NOT proof doctrine is unused — narrow reads,
       // contracts-first edits, and delegation are the method working *without*
       // a tool call. A hard ✗ here would penalize exactly the discipline this

package/eval/mcp-probe.mjs

@@ -0,0 +1,136 @@
+// MCP config probe — the "was RAG even available?" half of the adoption report
+// (TASK-083, closing Option 3 deferred in TASK-070).
+//
+// The report can see that `search_codebase` was never called. It cannot see
+// WHY, and the difference matters: "no RAG installed here" is not a finding,
+// "RAG installed and ignored" is exactly the finding the report exists for.
+// TASK-070 refused to guess and printed neither ✓ nor ✗. This module earns a
+// middle state instead of inventing a hard one.
+//
+// Three gaps sit between "configured" and "was available in that session", and
+// each one alone is enough to manufacture a false accusation:
+//
+//   1. server ≠ tool     — config lists servers, not their tools. A server
+//                          named `rag` may expose `query`, not `search_codebase`
+//                          (see classifyMcpServer's own warning in cli/detect.mjs).
+//   2. now ≠ then        — the probe reads today's config against a historical
+//                          log. Installing RAG today must not retroactively
+//                          convict every session that predates the install.
+//   3. configured ≠ approved — a project `.mcp.json` server the user never
+//                          approved is "⏸ Pending approval": present, not running.
+//
+// Gap 2 is closed by the mtime guard below. Gap 3 is only NARROWED: explicit
+// rejections (`disabledMcpjsonServers`) are honoured, but a server still
+// awaiting approval stays "configured" on purpose — absence from
+// `enabledMcpjsonServers` does not mean disabled (the user is asked, and may
+// well say yes), so reading it as unavailable would drop the very case this
+// module exists to surface. Gap 1 is not closed at all. Which is precisely why
+// the strongest verdict here is a soft `~`, never a hard ✗ (PO decision 1,
+// 2026-07-27).
+//
+// SCOPE — project `.mcp.json` only, measured rather than assumed (TASK-083
+// review, 2026-07-27): `~/.claude.json`, which declares the user and local
+// scopes, is rewritten by Claude Code continuously — it holds project history
+// and session state, not just `mcpServers`, so its mtime is always ~now. The
+// temporal guard would therefore degrade EVERY user-scope server to unknown,
+// silently disabling the probe exactly where people install RAG most often
+// (`claude mcp add --scope user`). A project `.mcp.json` is a static,
+// git-tracked file whose mtime means something. The honest answer for the user
+// scope is "unknown", and it stays "unknown" — recovering it needs the session
+// to record its own server list going forward, not a cleverer inference.
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { detectExistingConfig, detectMcpServers, detectRejectedMcpServers } from '../cli/detect.mjs';
+
+// The one classifyMcpServer bucket that could plausibly serve search_codebase.
+// Single source of truth, already maintained for the CLAUDE.md MCP rules — a
+// second allowlist here would drift from it (PO decision 2, 2026-07-27).
+const SEMANTIC_SEARCH = 'semantic code search';
+
+/** mtime of a path in epoch ms, or null when it is missing/unreadable. */
+function mtimeMs(path) {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Semantic-search servers a project's OWN `.mcp.json` declares and no settings
+ * file rejects, plus that file's mtime — the raw facts, no judgment.
+ *
+ * Rejections are read without any temporal guard of their own, deliberately: a
+ * server rejected today that was live back then reads as "unknown" instead of
+ * "configured", which is an error toward silence. That direction is always
+ * allowed here; the opposite one is what this whole module exists to prevent.
+ *
+ * @param {string} cwd - project directory as recorded in the adoption log
+ * @returns {{names: string[], mtimeMs: number|null}}
+ */
+export function probeProjectMcp(cwd) {
+  const config = detectExistingConfig(cwd);
+  const rejected = detectRejectedMcpServers([
+    config.projectSettingsJson,
+    config.projectSettingsLocalJson,
+    config.userSettingsJson,
+  ]);
+  const names = detectMcpServers(cwd)
+    .filter((s) => s.scope === 'project' && s.classification === SEMANTIC_SEARCH && !rejected.has(s.name))
+    .map((s) => s.name);
+  return { names, mtimeMs: mtimeMs(join(cwd, '.mcp.json')) };
+}
+
+/**
+ * How much this project's log entitles us to claim about RAG availability.
+ *
+ *   'observed'   — a search_codebase-class call is in the log for this cwd.
+ *                  Proven. The config is not even consulted.
+ *   'configured' — not observed, but the project declares a non-rejected
+ *                  semantic-search server in a `.mcp.json` that predates every
+ *                  session logged here. Likely available, unused. Soft `~`.
+ *   'unknown'    — everything else. TASK-070's wording, unchanged.
+ *
+ * The temporal guard is a valid inference, not a heuristic:
+ * `mtime < session start` ⇒ the file was not touched from before that session
+ * until now ⇒ the content read today IS the content that session saw. The
+ * converse buys nothing — a file changed during or after the session says
+ * nothing about its state back then — so it drops to 'unknown'. A fresh
+ * `git clone` stamps mtime at checkout time and so reads "too new": fail-safe,
+ * which is the house direction. The one case that fails the other way is a copy
+ * that preserves mtime (`cp -p`, `rsync -a`, a restored backup) — the file can
+ * then look older than a session it was never present for. Left undefended
+ * deliberately: it is exotic, and what it could inflate is a soft `~`, not an
+ * accusation.
+ *
+ * 'configured' additionally answers to a sample floor, passed in as
+ * `sampleSuffices` because the number is the report's to freeze with the PO, not
+ * this module's to pick. It applies to this tier and not to 'observed' for a
+ * reason: a call either happened or it didn't, but "available and never reached
+ * for" is a claim about ABSENCE across sessions, and absence is exactly what one
+ * session cannot establish.
+ *
+ * `probe` is injected so callers can prove the ordering above: on an
+ * 'observed' project it is never called, so a probe that throws is harmless.
+ *
+ * `names` is populated only for 'configured' — the one tier whose claim rests
+ * on those servers, and so the one whose report line has to name them for the
+ * reader to check. The other tiers carry nothing to confirm.
+ *
+ * @param {string} cwd
+ * @param {{ragObserved: boolean, sessionStartMs: number|null, sampleSuffices: boolean, probe?: (cwd: string) => {names: string[], mtimeMs: number|null}}} facts
+ *        sessionStartMs - earliest logged timestamp of any session that touched
+ *        this cwd; null when unknown, which alone forces 'unknown'.
+ *        sampleSuffices - has THIS project logged enough sessions to be spoken
+ *        about? False forces 'unknown' without consulting the config.
+ * @returns {{tier: 'observed'|'configured'|'unknown', names: string[]}}
+ */
+export function classifyAvailability(cwd, { ragObserved, sessionStartMs, sampleSuffices, probe = probeProjectMcp }) {
+  if (ragObserved) return { tier: 'observed', names: [] }; // observation beats inference — no probe
+  if (!sampleSuffices) return { tier: 'unknown', names: [] }; // too few sessions here to speak of absence
+  if (sessionStartMs === null) return { tier: 'unknown', names: [] }; // nothing to date the config against
+  const { names, mtimeMs: configMtime } = probe(cwd);
+  if (names.length === 0) return { tier: 'unknown', names: [] };
+  if (configMtime === null || configMtime >= sessionStartMs) return { tier: 'unknown', names: [] };
+  return { tier: 'configured', names };
+}

package/hooks/context-reminder.mjs

@@ -13,9 +13,11 @@
 // 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.
+// and leaves the timing judgment to the model — the first reminder explicitly
+// tells it to stay quiet mid-task. That deference is finite, though: it is
+// exactly what the LADDER below withdraws rung by rung, because a session that
+// never finds a "natural break" is the one paying the most. The phase-boundary
+// half is the `phase-workflow` skill's job, model-side, where judgment lives.
 //
 // The number is real, not a proxy: Claude Code records per-request `usage` in
 // the transcript, and input_tokens + cache_read_input_tokens +
@@ -137,43 +139,93 @@ function pruneState(state, now) {
   return state;
 }
 
-// TASK-080 fallback, chosen by the PO after measurement killed the preferred
-// design (see userNotice()): a SECOND and final notice at twice the threshold.
+// The notice ladder, as multipliers of the threshold: 120k / 180k / 240k by
+// default (TASK-080 added the second rung, TASK-084 the middle one).
 //
 // The problem it solves is measured, not hypothetical. Fire-once is consumed
 // when the model reads the reminder, and the reminder itself tells the model to
 // stay quiet mid-task — correctly, since only it can see whether a refactor is
 // half-finished. In session c9329adb that combination cost the user everything
 // between ~166k and ~346k: one firing, silently absorbed, and no re-arm until a
-// compaction that nobody had suggested.
+// compaction that nobody had suggested. Each rung halves the worst-case blind
+// spot: one rung left 120k of silence, two left 120k above the threshold, three
+// leave 60k.
 //
-// Why 2x and not "every +N tokens": periodic nagging would break the rule this
-// hook lives under — it is the only hook that ADDS tokens to the context it
-// exists to shrink. One extra notice per cycle is a bounded, one-off cost that
-// halves the worst-case blind spot; an unbounded series is the feature eating
-// itself. Deliberately NOT a third level.
-const ESCALATION_MULTIPLIER = 2;
+// Why a fixed ladder and not "every +N tokens": periodic nagging would break the
+// rule this hook lives under — it is the only hook that ADDS tokens to the
+// context it exists to shrink. Three notices per cycle is O(1) and measurable:
+// the text is ~600 chars ≈ 150 tokens, so the third rung costs ~0.1% of the
+// context it appears in. An unbounded series is the feature eating itself; a
+// bounded rung is not. (PO decision 2026-07-28, TASK-084 — the 1.5x point comes
+// from use: 120k is often too early to close a thread, 240k so far that a
+// session has to be dragged out to reach it.)
+//
+// Multipliers rather than absolute numbers so TUNE_CONTEXT_REMIND_TOKENS scales
+// the whole ladder, as the README promises. A hardcoded 180_000 would fall
+// BELOW the first rung the moment someone raises the threshold for a 1M window.
+//
+// Each rung carries its own wording, in ONE structure, deliberately. The
+// escalation IS that sentence tightening — repeating the level-1 text three
+// times would just be the same coin flipped again, which is what would make a
+// third rung not worth its tokens. Splitting trigger from wording into two
+// parallel structures would let them drift: a fourth multiplier with no fourth
+// sentence falls back to the level-1 text, so the LOUDEST rung would print the
+// SOFTEST wording and nothing would fail. One array makes that unrepresentable.
+//
+// The graded sentence REPLACES the mid-task line rather than riding on top of
+// it, and that is a budget fact rather than taste: the rest of the reminder is
+// 490 chars against a <700 ceiling, and the old append-a-sentence shape had
+// already spent that down to 21 chars of headroom (measured 592 / 679 before
+// TASK-084). Swapping keeps every rung inside budget — 592 / 615 / 606.
+const LADDER = [
+  {
+    at: 1,
+    timing: 'If you are mid-task: stay quiet now, but raise it at the first natural break rather than dropping it.',
+  },
+  {
+    at: 1.5,
+    timing:
+      'If you are mid-task: raise it at the next pause anyway — this is no longer early, and silence now costs the user every turn.',
+  },
+  {
+    at: 2,
+    timing:
+      'Final automatic notice — say it this turn whatever you are in the middle of; nothing more fires until a compaction.',
+  },
+];
 
-/** How many notices this session has earned at `total`: 0, 1 or 2. */
+/** How many notices this session has earned at `total`: 0..LADDER.length. */
 function levelFor(total, threshold) {
-  if (total >= threshold * ESCALATION_MULTIPLIER) return 2;
-  if (total >= threshold) return 1;
-  return 0;
+  let level = 0;
+  for (const rung of LADDER) {
+    if (total >= threshold * rung.at) level++;
+  }
+  return level;
 }
 
 /**
  * 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 at most TWICE per crossing (threshold, then 2x threshold), never on
- * every prompt above the line. 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.
+ * Fires at most once per rung of LEVEL_MULTIPLIERS, never on every prompt above
+ * the line. 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.
+ *
+ * `level` rides out with the decision because the TEXT is graded by it — see
+ * reminderText(). Crossing several rungs in one turn (a 100k tool result) fires
+ * once, at the rung actually reached: no level is owed retroactively.
  */
 export function decide(prev, total, threshold) {
   // `fired: true` is how state written before TASK-080 recorded a single
   // firing; read it as level 1 so an in-flight session whose hook is upgraded
   // mid-run is not re-notified from scratch.
+  //
+  // A pre-TASK-084 `levels: 2` means "crossed 2x", which on the new ladder is
+  // level 3 — so a session live across that upgrade earns exactly ONE extra
+  // notice, then goes quiet for good. Accepted rather than fixed: telling old-2
+  // from new-2 needs a ladder version in the state, a permanent cost for one
+  // notice in sessions that happen to span an upgrade.
   let reached = typeof prev?.levels === 'number' ? prev.levels : prev?.fired === true ? 1 : 0;
   // 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.
@@ -181,7 +233,7 @@ export function decide(prev, total, threshold) {
 
   const level = levelFor(total, threshold);
   const remind = level > reached;
-  return { remind, escalated: remind && level === 2, next: { last: total, levels: Math.max(reached, level), ts: Date.now() } };
+  return { remind, level, next: { last: total, levels: Math.max(reached, level), ts: Date.now() } };
 }
 
 /**
@@ -207,11 +259,15 @@ export function userNotice(total) {
 
 /**
  * The channel that actually works (`additionalContext`): the model reads it and
- * relays it. The timing judgement stays here, because only the model can tell
- * whether the current thread is finished — but see the second sentence: it must
- * relay eventually, because staying silent forever means the user never learns.
+ * relays it. The timing judgement is the model's on the FIRST rung, because only
+ * it can tell whether the current thread is finished — but that exemption is
+ * what LADDER spends: by the last rung the text asks it to speak regardless,
+ * since staying silent forever means the user never learns at all.
+ *
+ * `level` defaults to 1, so the level-1 text is byte-identical to every release
+ * since TASK-079 and a caller that does not care about rungs keeps working.
  */
-export function reminderText(total, { escalated = false } = {}) {
+export function reminderText(total, { level = 1 } = {}) {
   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.`,
@@ -220,11 +276,10 @@ export function reminderText(total, { escalated = false } = {}) {
     // heard about the cost at ~346k.
     'The user CANNOT see this reminder — it reaches you alone, so if you never mention it they will never know.',
     'If the current work thread is finished: suggest /compact (or /clear when switching to unrelated work).',
-    'If you are mid-task: stay quiet now, but raise it at the first natural break rather than dropping it.',
+    // Position matters: the graded sentence stays 4th of 5, so level 1 is
+    // unchanged from what shipped.
+    (LADDER[level - 1] ?? LADDER[0]).timing,
     '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.',
-    // Kept short on purpose: it rides ON TOP of the full reminder, inside the
-    // same <700 char budget.
-    ...(escalated ? ['This is the second and final automatic notice — nothing more fires until a compaction.'] : []),
   ].join(' ');
 }
 
@@ -245,7 +300,7 @@ function main() {
     const session = input.session_id || 'unknown';
     const path = stateFile();
     const state = readState(path);
-    const { remind, escalated, next } = decide(state[session], total, thresholdTokens());
+    const { remind, level, next } = decide(state[session], total, thresholdTokens());
 
     state[session] = next;
     try {
@@ -264,7 +319,7 @@ function main() {
         systemMessage: userNotice(total),
         hookSpecificOutput: {
           hookEventName: 'UserPromptSubmit',
-          additionalContext: reminderText(total, { escalated }),
+          additionalContext: reminderText(total, { level }),
         },
       }),
     );

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bglocation/tune-context",
-  "version": "2.2.0",
-  "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.",
+  "version": "2.3.1",
+  "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",
   "author": "Szymon Walczak",

package/skills/tune-context/SKILL.md

@@ -166,10 +166,14 @@ covering the detected build/test/lint commands.
      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
+     (120k, override `TUNE_CONTEXT_REMIND_TOKENS`) injects a short reminder to
+     consider `/compact`. Fires at most **three times per crossing**, on a ladder
+     of 1×/1.5×/2× the threshold (120k/180k/240k), re-arming only after a
+     compaction-sized drop. Each rung tightens the wording — wait for a natural
+     break, then raise it at the next pause, then say it this turn — because a
+     note absorbed mid-task is otherwise never repeated. Bounded at three on
+     purpose: 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`.