@bglocation/tune-context 1.0.1 → 1.1.0

package/.claude-plugin/marketplace.json

@@ -1,5 +1,6 @@
 {
   "name": "bglocation",
+  "description": "Context-engineering tooling for Claude Code from bglocation — token-saving doctrine, configurators and semantic-search wiring.",
   "owner": {
     "name": "Szymon Walczak",
     "url": "https://bglocation.dev"
@@ -9,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": "1.0.1",
+      "version": "1.1.0",
       "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": "1.0.1",
+  "version": "1.1.0",
   "author": {
     "name": "Szymon Walczak",
     "url": "https://bglocation.dev"

package/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+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).
+
+## [1.1.0] — 2026-07-24
+
+Two hardening epics land together: consistent `CLAUDE_CONFIG_DIR` support with the
+guards to keep it honest (EPIC-006), and an adoption report that only claims what
+the log can actually support (EPIC-007). Default-path behavior is unchanged — no
+action needed on upgrade.
+
+### Added
+
+- **`CLAUDE_CONFIG_DIR` honored across the whole hook lifecycle.** Setting Claude
+  Code's `CLAUDE_CONFIG_DIR` now moves *everything* user-level under the override —
+  not just the config dir, but registered hook command paths and hook **state**
+  (PreCompact snapshots, adoption log) too. Previously the override leaked: scripts
+  landed under `/x/`, but hook commands and state still pointed at `~/.claude`.
+  Documented in the README with a per-path table. (EPIC-006 / TASK-064, TASK-067)
+- **Golden-fixture test harness** for the adoption report's pure functions
+  (`parseLog` / `aggregate` / `formatReport`), run by `npm test` and wired into the
+  `prepublishOnly` gate. Deliberately wrong aggregation now fails a fixture instead
+  of shipping. (EPIC-007 / TASK-068)
+- **edit:read ratio** in the adoption report — a partial, *ungraded* proxy for
+  doctrine applied as method (narrow reads, contracts-first edits), the discipline
+  that leaves no `Skill` tool call to count. (EPIC-007 / TASK-071)
+
+### Changed
+
+- **`verify` cross-checks hook wiring.** `cli/verify.mjs` now confirms each
+  registered hook command points at the file actually installed — checking *all*
+  matching entries, not just the first — so a dead or mis-pointed duplicate fails
+  red instead of passing on a partial match. (EPIC-006 / TASK-065)
+- **Adoption report splits code search from shell plumbing.** Semantic search (RAG)
+  and the Grep tool count as code search; `grep`/`find` inside Bash is reported
+  separately and kept out of the RAG share. Removes the "RAG 0%" false negative on
+  logs that were only ever doing operational greps. (EPIC-007 / TASK-069)
+- **The adoption verdict is now earned.** RAG and doctrine-skill judgments are
+  withheld below a PO-frozen floor of 3 distinct sessions ("insufficient signal"
+  instead of a confident ✗ over one atypical session). A lever the log genuinely
+  can't distinguish — RAG installed-but-unused vs not installed, or method-level
+  doctrine that leaves no tool call — is reported neutrally, never as a false ✗.
+  (EPIC-007 / TASK-070, TASK-071)
+
+### Fixed
+
+- **Manual hook-install docs were incomplete.** README / SKILL.md now instruct
+  copying `hooks/config-dir.mjs` alongside `hooks/adoption-log.mjs` — the latter
+  imports the former, so a by-hand install following the old docs threw
+  `Cannot find module`. (EPIC-006)
+- **No more false churn/verdict lines over empty data.** The adoption report no
+  longer prints "elevated re-read churn" for a zero-read log, and no longer dangles
+  a "see verdict below" pointer when the verdict section has nothing to say.
+  (EPIC-007 / TASK-070, TASK-071)
+
+### Testing / packaging
+
+- `smoke:init` now exercises **both** the default `$HOME` and the
+  `CLAUDE_CONFIG_DIR` override paths, asserting hook state round-trips in each.
+  (EPIC-006 / TASK-066)
+- `npm test` (the golden-fixture suite) runs first in `prepublishOnly`, ahead of
+  `verify:pack` / `verify:plugin` / `smoke:init` — cheapest gate, fails fastest.
+  (EPIC-007 / TASK-068)
+
+## [1.0.1] — 2026-07-23
+
+### Fixed
+
+- Stop shipping the dev-only MCP config (`.mcp.json`, `rag.config.json`) to plugin
+  installers. Because the repo root doubles as the plugin root, a tracked
+  `.mcp.json` would force every marketplace install to load a `rag` server pointing
+  at a binary and index the installer doesn't have — breaking the "RAG is optional,
+  detected never assumed" contract. Now enforced by `verify:plugin`.
+
+## [1.0.0] — 2026-07-23
+
+### Added
+
+- Initial dual-channel release under `@bglocation`: a Claude Code **plugin**
+  (marketplace) and an **npm CLI** (`tune-context init`), from one self-contained
+  repo. Ships the doctrine skills (`token-efficiency`, `caveman`, `cdd`,
+  `phase-workflow`), the `tune-context` configurator (skill + deterministic CLI
+  twin with a never-clobber managed-block contract), right-sized subagents
+  (`explore-cheap`, `reviewer`), the PreCompact / SessionStart / PostToolUse hook
+  suite, and the adoption report (`eval/adoption-report.mjs`).
+
+[1.1.0]: https://gitlab.com/bglocation/tune-context/-/tags/v1.1.0
+[1.0.1]: https://gitlab.com/bglocation/tune-context/-/tags/v1.0.1
+[1.0.0]: https://gitlab.com/bglocation/tune-context/-/tags/v1.0.0

package/README.md

@@ -110,11 +110,35 @@ The plugin manifest (`.claude-plugin/plugin.json`) and hook wiring
 automatically; `bin/tune-context` is added to `PATH` while the plugin is enabled.
 The marketplace catalog is [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json).
 
+### `CLAUDE_CONFIG_DIR`
+
+By default the CLI reads and writes Claude config under `~/.claude` (and
+`~/.claude.json`). If you set Claude Code's `CLAUDE_CONFIG_DIR`, `tune-context
+init` honors it consistently — everything user-level moves under the override:
+
+| What | Default | With `CLAUDE_CONFIG_DIR=/x` |
+|---|---|---|
+| doctrine skills / agents / hook scripts | `~/.claude/…` | `/x/…` |
+| `settings.json` (hooks + gating) | `~/.claude/settings.json` | `/x/settings.json` |
+| MCP-server detection (`.claude.json`) | `~/.claude.json` | `/x/.claude.json` |
+| registered hook command paths | `$HOME/.claude/hooks/…` | `/x/hooks/…` |
+| hook state (PreCompact snapshot, adoption log) | `~/.claude/tune-context/…` | `/x/tune-context/…` |
+
+Without the override the generated `settings.json` keeps the portable
+`$HOME/.claude/hooks/…` form (expanded when the hook fires, so it travels between
+machines). Under the override it's baked to the literal `/x/hooks/…` — where the
+scripts actually land. Useful for shared accounts, containers, and test isolation.
+
 ## Measuring adoption (does the doctrine actually get used?)
 `hooks/adoption-log.mjs` logs one JSONL line per event to
-`~/.claude/tune-context/adoption.jsonl`, and `eval/adoption-report.mjs` turns that
-into a report: RAG vs grep, doctrine skills, subagents, re-read churn — with a
-verdict per lever. It's registered under two Claude Code hook events —
+`~/.claude/tune-context/adoption.jsonl` by default (under `CLAUDE_CONFIG_DIR`, the
+override's `tune-context/adoption.jsonl` — see above), and `eval/adoption-report.mjs`
+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 —
 `PostToolUse` (every tool call) and `SubagentStart` (subagent spawns, which aren't
 regular tools).
 
@@ -123,8 +147,8 @@ regular tools).
 1. **Install the hook.** Either run **`/tune-context`** in your repo (it copies the
    script to `~/.claude/hooks/` and merges the hook entries into `settings.json`
    for you), or do it by hand:
-   - copy `hooks/adoption-log.mjs` → `~/.claude/hooks/adoption-log.mjs` (needs
-     Node ≥ 18 on `PATH`);
+   - copy `hooks/adoption-log.mjs` **and** `hooks/config-dir.mjs` (it imports the
+     latter for the log path) → `~/.claude/hooks/` (needs Node ≥ 18 on `PATH`);
    - add the `PostToolUse` **and** `SubagentStart` blocks from
      [`skills/tune-context/templates/settings.json.tmpl`](skills/tune-context/templates/settings.json.tmpl)
      to your `settings.json` — `~/.claude/settings.json` for every project, or a
@@ -137,7 +161,8 @@ regular tools).
    the `/hooks` command.
 
 3. **Just work.** Every tool call and subagent run now appends a line to
-   `~/.claude/tune-context/adoption.jsonl` (created on first write).
+   `~/.claude/tune-context/adoption.jsonl` by default (created on first write; under
+   `CLAUDE_CONFIG_DIR` it's the override's `tune-context/adoption.jsonl` instead).
 
 4. **Read the report** any time, from this checkout (or the installed package):
    ```bash
@@ -147,13 +172,16 @@ regular tools).
 
 **Stop / opt out:** delete the `PostToolUse` + `SubagentStart` entries from
 `settings.json` (watcher picks that up too). The log stays local under
-`~/.claude/tune-context/` and records only tool names, file paths, and
-skill/agent names — never full Bash command strings.
+`~/.claude/tune-context/` (or the `CLAUDE_CONFIG_DIR` override) and records only
+tool names, file paths, and skill/agent names — never full Bash command strings.
 
 **Honest scope:** this is a *behavioral proxy*, not a bill. Token cost lands only
 in OTEL (`CLAUDE_CODE_ENABLE_TELEMETRY=1` → `claude_code.cost.usage`, needs a
 collector), never a hook; and caveman is an output style with no tool call, so it
-can't be counted this way.
+can't be counted this way. Doctrine applied as *method* — narrow reads,
+contracts-first edits, delegation — is only partly visible too: no `Skill` call,
+but its trace shows up in the report's edit:read ratio, so the verdict never
+reads zero `Skill` calls as "unused."
 
 ### Getting real cost (OTEL) — outside tune-context
 

package/bin/tune-context.mjs

@@ -2,7 +2,6 @@
 // tune-context init — deterministic detect -> generate -> verify.
 // This is the CLI/plugin-bin twin of skills/tune-context/SKILL.md: same
 // managed-block rules, same "never clobber" guarantee, no model in the loop.
-import { readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { claudeDirs, detectExistingConfig, detectMcpServers, detectStack } from '../cli/detect.mjs';
@@ -11,6 +10,7 @@ import {
   generateProjectClaudeMd,
   generateUserClaudeMd,
   installDoctrine,
+  loadSettingsTemplate,
   mergeHooks,
   mergePermissions,
 } from '../cli/generate.mjs';
@@ -47,7 +47,7 @@ function runInit(cwd) {
   const userClaudeMd = generateUserClaudeMd(claudeDir, templatesDir);
   const projectClaudeMd = generateProjectClaudeMd(cwd, detection, templatesDir);
 
-  const settingsTemplate = JSON.parse(readFileSync(join(templatesDir, 'settings.json.tmpl'), 'utf8'));
+  const settingsTemplate = loadSettingsTemplate(templatesDir);
   const hooksAdded = mergeHooks(existing.userSettingsJson, { hooks: settingsTemplate.hooks });
   const permissionsAllow = buildPermissionsAllow(detection);
   const permissionsAdded = mergePermissions(existing.projectSettingsJson, permissionsAllow);

package/cli/generate.mjs

@@ -7,6 +7,48 @@ import { dirname, join } from 'node:path';
 import { syncDoctrine } from './sync-doctrine.mjs';
 import { upsertManagedBlock } from './managed-block.mjs';
 
+/**
+ * The hooks directory baked into settings.json commands.
+ *
+ * Default stays the *portable* `$HOME/.claude/hooks` form — `$HOME` is expanded
+ * by the shell when the hook fires, so settings.json can be carried between
+ * machines. This must be byte-identical to what shipped before {{HOOKS_DIR}}
+ * existed, or every current user sees a spurious diff.
+ *
+ * Under CLAUDE_CONFIG_DIR it must instead be the *literal* `<override>/hooks`
+ * path, because that is where syncDoctrine actually installs the scripts
+ * (claudeDir == the override). A hardcoded `$HOME/.claude/hooks` there points at
+ * a dir the scripts were never copied to, and the hooks silently never fire —
+ * the bug this task fixes.
+ */
+export function hooksDirForTemplate(env = process.env) {
+  const override = env.CLAUDE_CONFIG_DIR;
+  return override ? join(override, 'hooks') : '$HOME/.claude/hooks';
+}
+
+/**
+ * Read settings.json.tmpl and fill the {{HOOKS_DIR}} slot in each hook command.
+ *
+ * Parse first, then substitute into the parsed command strings — never inject a
+ * filesystem path into JSON *source*. A CLAUDE_CONFIG_DIR containing a backslash
+ * or a quote (both legal in a posix dir name) would otherwise land inside the
+ * JSON text and throw an opaque `Bad escaped character in JSON` on parse. The
+ * `{{HOOKS_DIR}}` placeholder itself has no JSON-special chars, so the template
+ * parses cleanly and only the parsed strings ever see the real path.
+ */
+export function loadSettingsTemplate(templatesDir, env = process.env) {
+  const template = JSON.parse(readFileSync(join(templatesDir, 'settings.json.tmpl'), 'utf8'));
+  const hooksDir = hooksDirForTemplate(env);
+  for (const groups of Object.values(template.hooks || {})) {
+    for (const group of groups) {
+      for (const hook of group.hooks || []) {
+        if (typeof hook.command === 'string') hook.command = hook.command.replaceAll('{{HOOKS_DIR}}', hooksDir);
+      }
+    }
+  }
+  return template;
+}
+
 function readJson(path, fallback) {
   if (!existsSync(path)) return fallback;
   try {

package/cli/verify.mjs

@@ -2,7 +2,8 @@
 // landed" per SKILL.md §3. Never trust that a write succeeded just because
 // the function returned; re-read the target file and parse it.
 import { existsSync, readFileSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
 
 function readJson(path) {
   try {
@@ -12,17 +13,87 @@ function readJson(path) {
   }
 }
 
+// Pull the script path out of a hook command string. Commands look like
+//   node "$HOME/.claude/hooks/pre-compact-snapshot.mjs"
+// so the target is the first single- or double-quoted argument. Returns null
+// when nothing is quoted — the caller must treat that as "cannot verify", never
+// as a silent pass. A false alarm here is cheaper than a missed broken wire.
+function extractHookPath(command) {
+  if (typeof command !== 'string') return null;
+  const m = command.match(/"([^"]+)"|'([^']+)'/);
+  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.
+function expandHome(p) {
+  const home = process.env.HOME || homedir();
+  return p.replace(/\$\{HOME\}/g, home).replace(/\$HOME/g, home);
+}
+
 /**
  * @returns {{ok: boolean, checks: {name: string, ok: boolean, detail?: string}[]}}
  */
 export function verify({ claudeDir, userSettingsPath, expectedHookCommands, projectSettingsPath, expectedPermissions }) {
   const checks = [];
 
+  // Cross-check, not two independent presence checks. The old code asked
+  // "does some command contain the script name?" and, separately, "does the
+  // script exist in claudeDir?" — both could pass while pointing at different
+  // dirs (the CLAUDE_CONFIG_DIR bug: script installed under the override, but
+  // the command still hardcoded to $HOME/.claude/hooks). Here the registered
+  // command must resolve to *the same file* we installed.
   const settings = readJson(userSettingsPath);
   for (const { event, scriptName } of expectedHookCommands) {
     const entries = settings?.hooks?.[event] || [];
-    const ok = entries.some((g) => g.hooks?.some((h) => h.command?.includes(scriptName)));
-    checks.push({ name: `hooks.${event} registers ${scriptName}`, ok, detail: ok ? undefined : `not found in ${userSettingsPath}` });
+    const commands = entries.flatMap((g) => (g.hooks || []).map((h) => h.command)).filter(Boolean);
+    const installedPath = resolve(join(claudeDir, 'hooks', scriptName));
+
+    // 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
+    // one, and Claude Code runs every registered command: a leftover pointing
+    // at a missing file errors on every event. First-match-only had two holes:
+    // stale-first hid a correct entry behind the pre-fix error message, and
+    // correct-first passed silently over a dead leftover.
+    const matching = commands.filter((c) => basename(extractHookPath(c) || '') === scriptName);
+
+    if (matching.length === 0) {
+      // Fall back to a substring test so a present-but-unparseable command is
+      // reported loudly rather than mistaken for "not registered at all".
+      const fallback = commands.find((c) => c.includes(scriptName));
+      if (!fallback) {
+        checks.push({ name: `hooks.${event} registers ${scriptName}`, ok: false, detail: `not found in ${userSettingsPath}` });
+      } else {
+        checks.push({ name: `hooks.${event} → ${scriptName} points at installed file`, ok: false, detail: `could not parse a path from command: ${fallback}` });
+      }
+      continue;
+    }
+
+    const resolved = matching.map((c) => resolve(expandHome(extractHookPath(c))));
+    const strays = resolved.filter((p) => p !== installedPath);
+    const deadStrays = strays.filter((p) => !existsSync(p));
+
+    let ok;
+    let detail;
+    if (!resolved.includes(installedPath)) {
+      ok = false;
+      detail = `registered ${resolved[0]} != installed ${installedPath}`;
+    } else if (deadStrays.length) {
+      // The wiring we installed is correct, but a stale duplicate points at
+      // nothing — a dead wire that errors at run time. Red, with a message
+      // distinguishable from "the fix didn't land".
+      ok = false;
+      detail = `correct registration present, but stale entry points at missing file: ${deadStrays.join(', ')} — remove it from ${userSettingsPath}`;
+    } else {
+      // Duplicates that resolve to an existing file run twice but don't break;
+      // surface them so the choice is visible, not silent.
+      ok = true;
+      detail = strays.length ? `note: also registered at ${strays.join(', ')}` : undefined;
+    }
+    checks.push({ name: `hooks.${event} → ${scriptName} points at installed file`, ok, detail });
   }
 
   const scriptNames = [...new Set(expectedHookCommands.map((h) => h.scriptName))];

package/eval/adoption-report.mjs

@@ -11,9 +11,9 @@
 //     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.
 import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { parseArgs } from 'node:util';
+import { claudeBaseDir } from '../hooks/config-dir.mjs';
 
 const DOCTRINE_SKILLS = new Set([
   'token-efficiency',
@@ -22,8 +22,16 @@ const DOCTRINE_SKILLS = new Set([
   'phase-workflow',
 ]);
 
+// Minimum distinct sessions before the verdict prints a hard ✓/✗ for the
+// cross-session levers (RAG, doctrine skills). Below it those judgments are
+// withheld ("insufficient signal") — one atypical session can't masquerade as a
+// trend. FROZEN WITH PO (2026-07-24, TASK-070): the model must not choose the
+// sample size at which its own sessions escape a verdict (anti-bias, TASK-062).
+// Churn is exempt — a within-session symptom, readable at any n.
+const MIN_SESSIONS_FOR_VERDICT = 3;
+
 function defaultLogPath() {
-  return join(homedir(), '.claude', 'tune-context', 'adoption.jsonl');
+  return join(claudeBaseDir(), 'tune-context', 'adoption.jsonl');
 }
 
 const USAGE = `
@@ -33,7 +41,8 @@ Usage:
   adoption-report [--log <path>]
 
 Options:
-  --log <path>   Path to adoption.jsonl (default: ~/.claude/tune-context/adoption.jsonl)
+  --log <path>   Path to adoption.jsonl (default: <config dir>/tune-context/adoption.jsonl,
+                 where <config dir> is $CLAUDE_CONFIG_DIR if set, else ~/.claude)
   -h, --help     Show this help
 
 The log is written by the adoption-log.mjs PostToolUse hook (installed by
@@ -56,10 +65,12 @@ export function parseLog(text) {
 }
 
 export function aggregate(records) {
-  const search = { rag: 0, text: 0, glob: 0 };
+  const search = { rag: 0, grepTool: 0, shell: 0, glob: 0 };
   const skills = new Map();
   const subagents = new Map();
-  const readCounts = new Map(); // detail(file) -> times read
+  const readCounts = new Map(); // `${session}\u0000${file}` -> times read in that session
+  const sessionSet = new Set();
+  const cwdSet = new Set();
   let reads = 0;
   let edits = 0;
   let bash = 0;
@@ -68,12 +79,24 @@ export function aggregate(records) {
   const bump = (m, k) => m.set(k, (m.get(k) ?? 0) + 1);
 
   for (const r of records) {
+    if (r.session != null) sessionSet.add(r.session);
+    if (r.cwd != null) cwdSet.add(r.cwd);
     switch (r.lever) {
-      case 'search':
-        if (r.detail === 'rag') search.rag++;
-        else if (r.detail === 'glob') search.glob++;
-        else search.text++;
+      case 'search': {
+        // Split content search by TOOL — the only reliable "is this a codebase
+        // search?" signal. RAG (search_codebase) and the Grep tool are
+        // unambiguous code search; a grep/find inside Bash is usually plumbing
+        // (git … | grep, npm pack | grep) and must NOT compete with RAG. The
+        // record's `tool` field (set by the logger's buildRecord) carries this,
+        // 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
         break;
+      }
       case 'skill':
         bump(skills, r.detail ?? '(unknown)');
         break;
@@ -82,7 +105,11 @@ export function aggregate(records) {
         break;
       case 'read':
         reads++;
-        if (r.detail) bump(readCounts, r.detail);
+        // Key re-read churn by (session, file): the same file opened in two
+        // independent sessions is NOT lost context — only re-opening within one
+        // session is. Per-file-global inflates churn on multi-session logs
+        // (TASK-070). Single-session logs are unchanged (session is constant).
+        if (r.detail) bump(readCounts, `${r.session ?? ''}\u0000${r.detail}`);
         break;
       case 'edit':
         edits++;
@@ -95,8 +122,11 @@ export function aggregate(records) {
     }
   }
 
-  const contentSearches = search.rag + search.text;
-  const ragShare = contentSearches > 0 ? search.rag / contentSearches : null;
+  // RAG-share denominator is ONLY unambiguous code search (RAG + Grep tool);
+  // shell plumbing is excluded. null (not 0) when there was no code search at
+  // all — "n/a", not "✗ weak", so an all-plumbing log stops reading as failure.
+  const codeSearches = search.rag + search.grepTool;
+  const ragShare = codeSearches > 0 ? search.rag / codeSearches : null;
 
   // Re-read churn proxy: files opened more than once, and the extra opens beyond
   // the first. High churn hints the model is re-fetching context it lost — the
@@ -112,6 +142,8 @@ export function aggregate(records) {
 
   return {
     total: records.length,
+    sessions: sessionSet.size,
+    cwds: cwdSet.size,
     search,
     ragShare,
     skills: [...skills.entries()].sort((a, b) => b[1] - a[1]),
@@ -123,6 +155,14 @@ export function aggregate(records) {
     reReadFiles,
     redundantReads,
     reReadRate: reads > 0 ? redundantReads / reads : null,
+    // 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).
+    // Edits per read is a partial, honest echo of that method: editing without
+    // re-reading first is what narrow-read discipline looks like from the
+    // outside. Not a verdict — a read-heavy exploration session scores low here
+    // for reasons unrelated to doctrine — so it is shown, never graded (TASK-071).
+    editReadRatio: reads > 0 ? edits / reads : null,
   };
 }
 
@@ -130,21 +170,27 @@ function pct(x) {
   return x === null ? 'n/a' : `${Math.round(x * 100)}%`;
 }
 
+function ratio(x) {
+  return x === null ? 'n/a' : `${x.toFixed(1)}:1`;
+}
+
 export function formatReport(a) {
   const L = [];
   L.push('tune-context Adoption Report');
   L.push('============================');
   L.push('');
   L.push(`Tool calls logged: ${a.total}`);
+  L.push(`Sessions: ${a.sessions}   Projects (distinct cwd): ${a.cwds}`);
   L.push('');
 
-  L.push('Search — RAG vs grep:');
-  L.push(`  semantic (RAG):  ${a.search.rag}`);
-  L.push(`  text (grep/find):${String(a.search.text).padStart(2)}`);
-  L.push(`  glob (file find):${String(a.search.glob).padStart(2)}`);
+  L.push('Search — code search vs shell plumbing:');
+  L.push(`  semantic (RAG):     ${a.search.rag}`);
+  L.push(`  code search (Grep): ${a.search.grepTool}`);
+  L.push(`  shell text-search:  ${a.search.shell}  (grep/find in Bash — operational, not in RAG-share)`);
+  L.push(`  glob (file find):   ${a.search.glob}`);
   L.push(
-    `  RAG share of content search: ${pct(a.ragShare)}` +
-      (a.ragShare === null ? '  (no content searches yet)' : ''),
+    `  RAG share of code search: ${pct(a.ragShare)}` +
+      (a.ragShare === null ? '  (no code search — RAG or Grep — observed)' : ''),
   );
   L.push('');
 
@@ -153,7 +199,10 @@ export function formatReport(a) {
     const mark = DOCTRINE_SKILLS.has(name) ? '★' : ' ';
     L.push(`  ${mark} ${String(n).padStart(3)}×  ${name}`);
   }
-  if (a.skills.length === 0) L.push('  (none — doctrine skills unused)');
+  // No forward reference to "the verdict below" here: on a totally empty log
+  // (total === 0) the verdict section only prints "No data yet" and never
+  // mentions skills at all — a "see verdict below" promise would dangle.
+  if (a.skills.length === 0) L.push('  (none via the Skill tool)');
   L.push('');
 
   L.push(`Subagents spawned: ${a.subagents.length} distinct`);
@@ -169,6 +218,10 @@ export function formatReport(a) {
     `  re-read files: ${a.reReadFiles}  redundant opens: ${a.redundantReads}` +
       `  (${pct(a.reReadRate)} of reads)`,
   );
+  L.push(
+    `  edit:read ratio: ${ratio(a.editReadRatio)}  — edits per read; narrow,` +
+      ' contracts-first edits (doctrine-as-method, not tool-call-visible) push this up.',
+  );
   L.push('');
 
   // Verdict — behavioral, not a cost claim. Frozen thresholds so the model
@@ -177,23 +230,58 @@ export function formatReport(a) {
   if (a.total === 0) {
     L.push('  No data yet. Run some sessions with the hook installed, then re-run.');
   } else {
-    if (a.ragShare !== null) {
+    // RAG + doctrine skills are cross-session tendencies: gate them on sample
+    // size so a single atypical session can't read as a trend. Below the
+    // PO-frozen floor, withhold both judgments (TASK-070).
+    if (a.sessions < MIN_SESSIONS_FOR_VERDICT) {
+      L.push(
+        `  ~ RAG/skills verdict withheld — needs ≥${MIN_SESSIONS_FOR_VERDICT} distinct sessions, have ${a.sessions}.` +
+          ' One session is a sample, not a trend; collect more, then re-run.',
+      );
+    } else {
+      if (a.search.rag === 0) {
+        // 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).
+        L.push(
+          '  · RAG not observed — no search_codebase in these sessions. Not counted' +
+            ' as ✗: can\'t tell "not installed" from "installed but unused".',
+        );
+      } else {
+        // rag > 0 ⇒ denominator (rag + grepTool) > 0 ⇒ ragShare is a number.
+        L.push(
+          a.ragShare >= 0.5
+            ? '  ✓ RAG lever working — semantic search is the default over grep.'
+            : '  ✗ RAG lever weak — grep still dominates code search. Revisit index/skill wiring.',
+        );
+      }
+      // 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
+      // project trains toward, so it is replaced with a neutral note pointing
+      // at edit:read (see the churn section above) — a partial, honest proxy,
+      // not a substitute verdict (TASK-071).
       L.push(
-        a.ragShare >= 0.5
-          ? '  ✓ RAG lever working — semantic search is the default over grep.'
-          : '  ✗ RAG lever weak — grep still dominates content search. Revisit index/skill wiring.',
+        a.skills.length > 0
+          ? '  ✓ Doctrine skills are being invoked.'
+          : '  · No explicit Skill invocations — doctrine-as-method (narrow reads,' +
+              ' contracts-first, delegation) isn\'t tool-call-visible. See edit:read above.',
+      );
+    }
+    // Churn is a within-session symptom — valid at any sample size, so NOT gated
+    // 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) {
+      L.push('  · re-read churn: n/a — no reads logged yet.');
+    } else {
+      L.push(
+        a.reReadRate <= 0.25
+          ? '  ✓ Low re-read churn.'
+          : '  ~ Elevated re-read churn — context may be getting lost (compaction/RAG lever).',
       );
     }
-    L.push(
-      a.skills.length > 0
-        ? '  ✓ Doctrine skills are being invoked.'
-        : '  ✗ Doctrine skills unused — check skill descriptions / discoverability.',
-    );
-    L.push(
-      a.reReadRate !== null && a.reReadRate <= 0.25
-        ? '  ✓ Low re-read churn.'
-        : '  ~ Elevated re-read churn — context may be getting lost (compaction/RAG lever).',
-    );
   }
   L.push('');
   L.push('Cost (dollars) is not measurable from hooks. For hard cost, enable OTEL:');

package/hooks/adoption-log.mjs

@@ -28,8 +28,8 @@ import {
   renameSync,
   statSync,
 } from 'node:fs';
-import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { claudeBaseDir } from './config-dir.mjs';
 
 const MAX_LOG_BYTES = 5 * 1024 * 1024; // rotate to <path>.1 past this (bounded ~2×)
 
@@ -42,7 +42,7 @@ function readStdin() {
 }
 
 export function logFilePath() {
-  return join(homedir(), '.claude', 'tune-context', 'adoption.jsonl');
+  return join(claudeBaseDir(), 'tune-context', 'adoption.jsonl');
 }
 
 // Detect a text-search shell command (grep/rg/find/ag/ack), the grep-side of the

package/hooks/config-dir.mjs

@@ -0,0 +1,12 @@
+// Shared base-dir resolution for hook STATE paths (snapshots, adoption log).
+// Mirrors claudeDirs() in cli/detect.mjs — same rule, but must live here rather
+// than be imported from cli/: syncDoctrine only copies hooks/ into
+// <claudeDir>/hooks/, so an installed hook has no access to cli/ at runtime.
+// eval/adoption-report.mjs imports this too, via a relative path (eval/ is
+// never installed, so that path is safe only in-repo).
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function claudeBaseDir() {
+  return process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+}

package/hooks/pre-compact-snapshot.mjs

@@ -11,8 +11,8 @@
 // safety net against losing that mechanical state, not a summary.
 import { execFileSync } from 'node:child_process';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { claudeBaseDir } from './config-dir.mjs';
 
 function readStdin() {
   try {
@@ -36,7 +36,7 @@ function git(cwd, args) {
 
 export function stateFilePath(cwd) {
   const safe = cwd.replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-+|-+$/g, '');
-  return join(homedir(), '.claude', 'tune-context', 'state', `${safe}.md`);
+  return join(claudeBaseDir(), 'tune-context', 'state', `${safe}.md`);
 }
 
 export function buildSnapshot(input) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bglocation/tune-context",
-  "version": "1.0.1",
+  "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.",
   "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/tune-context/SKILL.md

@@ -89,25 +89,42 @@ covering the detected build/test/lint commands.
 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.
+   - 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.
+   - 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.
 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
@@ -140,6 +157,21 @@ in skills — that is the whole point of this setup.
   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,7 +39,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$HOME/.claude/hooks/adoption-log.mjs\""
+            "command": "node \"{{HOOKS_DIR}}/adoption-log.mjs\""
           }
         ]
       }