@bglocation/tune-context 1.0.1 → 2.0.0

package/bin/tune-context.mjs

@@ -1,16 +1,31 @@
 #!/usr/bin/env node
 // 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.
+//
+// This is the deterministic SUBSET of skills/tune-context/SKILL.md, not a full
+// twin of it. What it shares: the same managed-block rules and the same "never
+// clobber" guarantee. What it deliberately omits, because each needs judgment
+// a no-model-in-the-loop CLI cannot have (TASK-075):
+//
+//   • SKILL.md §2 step 4 — merging `.mcp.json` to add a semantic-search server
+//     when none was detected. Choosing *which* server to add for this repo is a
+//     judgment call; the CLI reads `.mcp.json` but never writes it.
+//   • SKILL.md §2 step 7 — wiring the wiki lever (RAG segment vs its own MCP vs
+//     a plain pointer). That choice depends on where the docs actually live and
+//     how they are hosted, which the CLI does not attempt to detect.
+//
+// "No model in the loop" is the feature here, not a gap — but the gap has to be
+// stated, or a CLI user cannot know what they did not get. Run the skill
+// (/tune-context) for the full pass.
 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';
+import { claudeDirs, detectExistingConfig, detectMcpServers, detectRejectedMcpServers, detectStack } from '../cli/detect.mjs';
 import {
   buildPermissionsAllow,
   generateProjectClaudeMd,
   generateUserClaudeMd,
   installDoctrine,
+  loadSettingsTemplate,
   mergeHooks,
   mergePermissions,
 } from '../cli/generate.mjs';
@@ -21,33 +36,90 @@ const HOOK_EVENTS = [
   { event: 'SessionStart', scriptName: 'session-start-reinject.mjs' },
   { event: 'PostToolUse', scriptName: 'adoption-log.mjs' },
   { event: 'SubagentStart', scriptName: 'adoption-log.mjs' },
+  { event: 'UserPromptSubmit', scriptName: 'context-reminder.mjs' },
 ];
 
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * Version straight from the shipped package.json — one source of truth, the
+ * same file verify:plugin cross-checks against plugin.json/marketplace.json,
+ * so `--version` can never drift from what the manifests claim. Both channels
+ * ship it: npm always includes package.json in the tarball, and the plugin
+ * channel is a git clone of this repo (guarded in verify-plugin's REQUIRE).
+ */
+export function readVersion() {
+  return JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8')).version;
+}
+
 function usage() {
-  console.log(`tune-context init — configure this repo for token-efficient Claude Code use.
+  return `tune-context init — configure this repo for token-efficient Claude Code use.
 
 Usage:
   tune-context init [--cwd <dir>]
   tune-context --help
-`);
+  tune-context --version
+`;
+}
+
+// Pure so it is unit-testable without spawning a process. `init` is the ONLY
+// accepted command — no bare-args shortcut (PO decision 2026-07-25, TASK-078):
+// README never once documents calling this without it, and accepting anything
+// un-checked is exactly how a subcommand typo used to silently run init
+// against the wrong repo instead of failing loud.
+export function parseArgs(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) return { mode: 'help' };
+  // Before the command check, like --help: `--version` is a query about the
+  // tool, not an operation on a repo, so it must not require a subcommand.
+  if (argv.includes('--version') || argv.includes('-v')) return { mode: 'version' };
+  const [command, ...rest] = argv;
+  if (command !== 'init') {
+    return {
+      mode: 'error',
+      message: command === undefined ? 'Missing command: init' : `Unknown command: ${command}`,
+    };
+  }
+  const cwdFlagIdx = rest.indexOf('--cwd');
+  if (cwdFlagIdx === -1) return { mode: 'init', cwd: process.cwd() };
+  const value = rest[cwdFlagIdx + 1];
+  // Undefined (last arg) or another flag (e.g. `--cwd --foo`) both mean "no
+  // value was actually given" — resolve(undefined) used to throw a raw
+  // ERR_INVALID_ARG_TYPE with a Node stacktrace instead of a usage message.
+  if (value === undefined || value.startsWith('-')) {
+    return { mode: 'error', message: 'Missing value for --cwd' };
+  }
+  return { mode: 'init', cwd: resolve(value) };
 }
 
 function runInit(cwd) {
-  const here = dirname(fileURLToPath(import.meta.url));
-  const pkgRoot = resolve(here, '..');
   const templatesDir = join(pkgRoot, 'skills', 'tune-context', 'templates');
   const { claudeDir } = claudeDirs();
 
   const stack = detectStack(cwd);
   const existing = detectExistingConfig(cwd);
-  const mcpServers = detectMcpServers(cwd);
+
+  // A server the user rejected out of .mcp.json must not get an
+  // `mcp__<server>__*` permission rule, nor a CLAUDE.md line advertising a
+  // lever this session does not have (TASK-075). Rejection applies ONLY to
+  // project-scope servers — see detectRejectedMcpServers for why user- and
+  // local-scope servers are out of its reach.
+  const allMcpServers = detectMcpServers(cwd);
+  const rejectedNames = detectRejectedMcpServers([
+    existing.userSettingsJson,
+    existing.projectSettingsJson,
+    existing.projectSettingsLocalJson,
+  ]);
+  const isRejected = (s) => s.scope === 'project' && rejectedNames.has(s.name);
+  const mcpServers = allMcpServers.filter((s) => !isRejected(s));
+  const rejectedServers = allMcpServers.filter(isRejected);
+
   const detection = { stack, mcpServers };
 
   const synced = installDoctrine(pkgRoot, claudeDir);
   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);
@@ -71,6 +143,10 @@ function runInit(cwd) {
   console.log(`Hooks merged into ${existing.userSettingsJson}: ${hooksAdded.length ? hooksAdded.join(', ') : 'already present'}`);
   console.log(`Permissions merged into ${existing.projectSettingsJson}: ${permissionsAdded.length ? permissionsAdded.join(', ') : 'already present'}`);
   console.log(`MCP servers detected: ${mcpServers.length ? mcpServers.map((s) => `${s.name} (${s.scope}, ${s.classification})`).join(', ') : 'none'}`);
+  // Surfaced, never silent: skipping a server is a decision the user should see.
+  if (rejectedServers.length) {
+    console.log(`  skipped (rejected via disabledMcpjsonServers): ${rejectedServers.map((s) => s.name).join(', ')} — no permission rule, no CLAUDE.md line`);
+  }
 
   console.log(`\nVerify: ${result.ok ? 'OK' : 'FAILED'}`);
   for (const check of result.checks) {
@@ -79,11 +155,29 @@ function runInit(cwd) {
   if (!result.ok) process.exitCode = 1;
 }
 
-const args = process.argv.slice(2);
-if (args.includes('--help') || args.includes('-h')) {
-  usage();
-} else {
-  const cwdFlagIdx = args.indexOf('--cwd');
-  const cwd = cwdFlagIdx !== -1 ? resolve(args[cwdFlagIdx + 1]) : process.cwd();
-  runInit(cwd);
+export function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (parsed.mode === 'help') {
+    console.log(usage());
+  } else if (parsed.mode === 'version') {
+    // Bare number, no prefix or banner — this is what a script greps.
+    console.log(readVersion());
+  } else if (parsed.mode === 'error') {
+    // Usage on stderr + exit 1, never a stacktrace, and — because this whole
+    // branch returns before runInit() is ever called — no config file is
+    // touched on an invalid invocation (TASK-078).
+    process.stderr.write(`${parsed.message}\n\n${usage()}`);
+    process.exitCode = 1;
+  } else {
+    runInit(parsed.cwd);
+  }
+}
+
+// Guarded so importing this file for parseArgs/main (tests, or the
+// extensionless bin/tune-context wrapper) never runs the CLI as a side
+// effect of the import — only direct invocation of THIS file does. The
+// wrapper has a different argv[1] (its own path), so it calls main()
+// explicitly instead of relying on this check.
+if (process.argv[1] && process.argv[1].endsWith('tune-context.mjs')) {
+  main();
 }

package/cli/detect.mjs

@@ -4,6 +4,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { claudeBaseDir } from '../hooks/config-dir.mjs';
 
 function readJson(path) {
   try {
@@ -13,11 +14,46 @@ function readJson(path) {
   }
 }
 
-/** Resolve the base Claude config directory, honoring CLAUDE_CONFIG_DIR. */
+// The actual command a user (and permissions.allow) would type for a
+// package-manager script — single source of truth, consumed by detectStack
+// below so a detected package manager can never be silently ignored when
+// building buildCmd/testCmd/lintCmd (TASK-073).
+//
+// npm/pnpm: `test` has a built-in shorthand (no `run`); build/lint don't.
+// yarn: short form for all three — PO decision 2026-07-25, TASK-073. Yarn
+// doesn't require `run` for scripts that don't collide with a built-in
+// command, and this is the form a user actually types, which is what has to
+// match the permissions.allow rule.
+const RUN_COMMANDS = {
+  npm: { build: 'npm run build', test: 'npm test', lint: 'npm run lint' },
+  pnpm: { build: 'pnpm run build', test: 'pnpm test', lint: 'pnpm run lint' },
+  yarn: { build: 'yarn build', test: 'yarn test', lint: 'yarn lint' },
+};
+
+/** @returns {string|null} the command for `script` under `packageManager`, or null if either is unrecognized. */
+export function runCmd(packageManager, script) {
+  return RUN_COMMANDS[packageManager]?.[script] ?? null;
+}
+
+/**
+ * Resolve the base Claude config directory, honoring CLAUDE_CONFIG_DIR, plus
+ * the one piece of CLI-specific knowledge on top: `.claude.json`'s path.
+ * Thin wrapper — the actual `CLAUDE_CONFIG_DIR || ~/.claude` rule lives
+ * solely in claudeBaseDir() (hooks/config-dir.mjs), which also has to be
+ * reachable from installed hook scripts (syncDoctrine never copies cli/, so
+ * the rule can't live here and be imported the other way — TASK-074).
+ *
+ * claudeJsonPath is NOT simply `join(claudeDir, '.claude.json')`: under the
+ * default (no override), `.claude.json` sits next to `.claude/` as a
+ * *sibling* under $HOME, not inside it. An override redirects the whole
+ * config surface, `.claude.json` included, so there it lives *inside* the
+ * override dir instead. This asymmetry is existing, load-bearing behavior
+ * (predates this refactor) — preserved exactly, not something to "fix" here.
+ */
 export function claudeDirs() {
   const override = process.env.CLAUDE_CONFIG_DIR;
   return {
-    claudeDir: override || join(homedir(), '.claude'),
+    claudeDir: claudeBaseDir(),
     claudeJsonPath: override ? join(override, '.claude.json') : join(homedir(), '.claude.json'),
   };
 }
@@ -31,17 +67,14 @@ export function detectStack(cwd) {
     const monorepo = Boolean(
       pkg.workspaces || existsSync(join(cwd, 'pnpm-workspace.yaml')) || existsSync(join(cwd, 'turbo.json')) || existsSync(join(cwd, 'nx.json')),
     );
+    const packageManager = existsSync(join(cwd, 'pnpm-lock.yaml')) ? 'pnpm' : existsSync(join(cwd, 'yarn.lock')) ? 'yarn' : 'npm';
     return {
       ecosystem: 'node',
       name: pkg.name || null,
-      packageManager: existsSync(join(cwd, 'pnpm-lock.yaml'))
-        ? 'pnpm'
-        : existsSync(join(cwd, 'yarn.lock'))
-          ? 'yarn'
-          : 'npm',
-      buildCmd: scripts.build ? 'npm run build' : null,
-      testCmd: scripts.test ? 'npm test' : null,
-      lintCmd: scripts.lint ? 'npm run lint' : null,
+      packageManager,
+      buildCmd: scripts.build ? runCmd(packageManager, 'build') : null,
+      testCmd: scripts.test ? runCmd(packageManager, 'test') : null,
+      lintCmd: scripts.lint ? runCmd(packageManager, 'lint') : null,
       monorepo,
     };
   }
@@ -65,6 +98,11 @@ export function detectExistingConfig(cwd) {
     userClaudeMd: existsSync(join(claudeDir, 'CLAUDE.md')) ? join(claudeDir, 'CLAUDE.md') : null,
     projectMcpJson: existsSync(join(cwd, '.mcp.json')) ? join(cwd, '.mcp.json') : null,
     projectSettingsJson: join(cwd, '.claude', 'settings.json'),
+    // Untracked per-developer overrides. Never written to — read only, because
+    // `disabledMcpjsonServers` counts from ANY settings file (see
+    // detectRejectedMcpServers) and this is where the docs say per-developer
+    // .mcp.json approvals and rejections usually land.
+    projectSettingsLocalJson: join(cwd, '.claude', 'settings.local.json'),
     userSettingsJson: join(claudeDir, 'settings.json'),
   };
 }
@@ -105,10 +143,48 @@ export function detectMcpServers(cwd) {
   return servers;
 }
 
-/** MCP gating keys from a settings.json — narrows which detected servers are actually reachable. */
-export function detectMcpGating(settingsJsonPath) {
-  const settings = readJson(settingsJsonPath);
-  if (!settings) return null;
-  const { enabledMcpjsonServers, disabledMcpjsonServers, allowedMcpServers, deniedMcpServers } = settings;
-  return { enabledMcpjsonServers, disabledMcpjsonServers, allowedMcpServers, deniedMcpServers };
+/**
+ * Server names that settings files explicitly REJECT out of a project's
+ * `.mcp.json`. Deliberately narrow — one key, one meaning (TASK-075).
+ *
+ * Semantics verified against live Claude Code docs (code.claude.com/docs/en/settings
+ * and /docs/en/mcp, checked 2026-07-25), NOT inferred from the key names:
+ *
+ *   `disabledMcpjsonServers` is a plain `string[]` of server names, applies
+ *   ONLY to servers defined in a project `.mcp.json`, and genuinely means
+ *   rejected — `claude mcp get <name>` renders such a server as
+ *   "✘ Rejected (see disabledMcpjsonServers in settings)". Every settings file
+ *   is read, not just one, because the docs are explicit: "A
+ *   `disabledMcpjsonServers` entry in any settings file still rejects the server."
+ *
+ * Three neighbouring keys are deliberately NOT honoured here. Each would be a
+ * guess, which is the failure mode TASK-073 was about:
+ *
+ *   • `enabledMcpjsonServers` — absence does NOT mean disabled. An unlisted
+ *     `.mcp.json` server is "⏸ Pending approval": the user is asked and may
+ *     well approve it. Treating unlisted as disabled would silently drop rules
+ *     for servers that are about to start working.
+ *   • `allowedMcpServers` / `deniedMcpServers` — arrays of OBJECTS
+ *     (`{serverName}` | `{serverUrl}` | `{serverCommand}`), not names. They may
+ *     appear in any settings file and merge from every source, but they are an
+ *     organization-policy mechanism: enforcement rests on a managed tier
+ *     (`managed-settings.json`, server-managed settings, MDM profile or
+ *     registry) that this CLI does not read, and matching involves URL
+ *     wildcards, `${VAR}` expansion and denylist-over-allowlist precedence.
+ *     Honouring them by name alone would misjudge exactly the enterprise setups
+ *     they exist for — the docs themselves warn that "a `serverName` entry, in
+ *     either list, is not a security control."
+ *
+ * @param {string[]} settingsPaths - settings.json files to read, missing ones ignored
+ * @returns {Set<string>} rejected server names (empty set when nothing is rejected)
+ */
+export function detectRejectedMcpServers(settingsPaths) {
+  const rejected = new Set();
+  for (const path of settingsPaths) {
+    if (!path) continue;
+    const list = readJson(path)?.disabledMcpjsonServers;
+    if (!Array.isArray(list)) continue;
+    for (const name of list) if (typeof name === 'string' && name) rejected.add(name);
+  }
+  return rejected;
 }

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 {
@@ -34,6 +76,12 @@ function templateInnerBlock(templatePath) {
   const raw = readFileSync(templatePath, 'utf8');
   const start = raw.indexOf('<!-- >>> tune-context (managed) >>>');
   const end = raw.indexOf('<!-- <<< tune-context (managed) <<< -->');
+  // A missing marker makes `start`/`end` -1; indexOf('\n', -1) silently treats
+  // -1 as 0, which used to return garbage sliced from the top of the file
+  // instead of failing. A broken template must not become a broken CLAUDE.md.
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error(`template ${templatePath} is missing the tune-context managed-block markers`);
+  }
   const startLineEnd = raw.indexOf('\n', start) + 1;
   return raw.slice(startLineEnd, end).trimEnd();
 }

package/cli/sync-doctrine.mjs

@@ -1,6 +1,15 @@
 // Mirrors this package's skills/agents/hooks into a Claude Code config dir
-// (~/.claude by default). Idempotent — removes each destination entry before
-// copying, so deletions at the source propagate too, not just an overlay.
+// (~/.claude by default). Idempotent for content that still exists at the
+// source: each entry is removed then recopied, so a changed file/directory
+// shape can't leave old siblings behind inside THAT entry. This is an
+// OVERLAY, not a mirror, across runs: the outer loop is `readdirSync(from)`,
+// so an entry no longer present at the source is simply never visited again —
+// it is NOT deleted from the destination (review finding, TASK-077; verified
+// empirically, not assumed. See the "KNOWN GAP" test in
+// test/cli-sync-doctrine.test.mjs). A prune pass would need to diff against
+// what THIS tool previously wrote, since claudeDir may also hold a user's own
+// unrelated skills/agents/hooks that must never be touched — deliberately not
+// attempted here without that design decision.
 import { chmodSync, cpSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 

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,132 @@ 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} inside a hook COMMAND STRING the way it resolves at
+// run time (process.env.HOME, falling back to homedir() if HOME is somehow
+// unset) — the literal shell variable baked into the *default*, non-override
+// hook command form (hooksDirForTemplate() in cli/generate.mjs). UNRELATED to
+// CLAUDE_CONFIG_DIR: that rule lives solely in claudeBaseDir()
+// (hooks/config-dir.mjs, TASK-074) and governs which directory claudeDir
+// itself resolves to, a different axis from $HOME shell-expansion. A
+// different notion of "home" on the two sides of the comparison below 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);
+}
+
+// TASK-072: signature of the PLUGIN channel's own hook registration turning up
+// where a settings.json entry is being checked. `${CLAUDE_PLUGIN_ROOT}` is
+// Claude Code's substitution for a plugin's OWN hooks.json — it is never
+// expanded for a command sitting in settings.json, so resolving/existsSync-ing
+// it here would always read as "missing", which would be a lie: the plugin
+// channel may be working perfectly well from Claude Code's side. Commands
+// matching this are pulled out of the resolvability check below and reported
+// separately, always informational — we can tell the command SHAPE is
+// present, never whether the plugin is actually enabled (Option B, TASK-072).
+const PLUGIN_PATH_HINT = /\$\{CLAUDE_PLUGIN_ROOT\}|[\\/]plugins[\\/]/;
+
 /**
  * @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 allCommands = entries.flatMap((g) => (g.hooks || []).map((h) => h.command)).filter(Boolean);
+    const installedPath = resolve(join(claudeDir, 'hooks', scriptName));
+
+    // Classify by DESTINATION, not by spelling: a command that resolves to
+    // the very file we installed is the CLI registration, whatever its path
+    // happens to look like. Without this, PLUGIN_PATH_HINT's loose
+    // `/plugins/` arm swallowed a correct install whose config dir merely
+    // sits under such a path (e.g. CLAUDE_CONFIG_DIR=/opt/plugins/claude) —
+    // it was dropped from `commands`, then reported "not found in
+    // settings.json", i.e. a false RED on a perfect install, plus a plugin
+    // note for a plugin that isn't there (review finding, EPIC-008).
+    // `${CLAUDE_PLUGIN_ROOT}` stays correctly classified: it is literal text
+    // in settings.json (Claude Code only expands it for a plugin's own
+    // hooks.json), so it can never resolve to the installed file.
+    const isInstalledTarget = (c) => {
+      const p = extractHookPath(c);
+      return p !== null && resolve(expandHome(p)) === installedPath;
+    };
+    const isPluginShaped = (c) => PLUGIN_PATH_HINT.test(c) && !isInstalledTarget(c);
+
+    // Report the plugin-channel shape separately and up front — see
+    // PLUGIN_PATH_HINT above — then exclude it from the resolvability check
+    // below so it can never be misread as a dead/stale leftover.
+    for (const pluginCmd of allCommands.filter((c) => c.includes(scriptName) && isPluginShaped(c))) {
+      checks.push({
+        name: `hooks.${event}: ${scriptName} also has a plugin-channel registration`,
+        ok: true,
+        detail: `${pluginCmd} — if the tune-context plugin is also enabled, every ${event} event logs twice; see README ("Measuring adoption") for the re-read-churn effect this has on adoption-report`,
+      });
+    }
+    const commands = allCommands.filter((c) => !isPluginShaped(c));
+
+    // 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))];