@bglocation/tune-context 1.1.0 → 2.0.0

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": "1.1.0",
+      "version": "2.0.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.1.0",
+  "version": "2.0.0",
   "author": {
     "name": "Szymon Walczak",
     "url": "https://bglocation.dev"

package/CHANGELOG.md

@@ -5,6 +5,166 @@ 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.0.0] — 2026-07-25
+
+Three hardening epics' worth of work plus the first new feature since 1.0: a
+reminder that measures what a session actually costs. **The major bump is for
+one breaking change** — `tune-context` with no subcommand no longer runs `init`
+(see below). Everything else is additive; see "Upgrading from 1.1.0" at the end.
+
+### Added
+
+- **Context-size reminder** (`hooks/context-reminder.mjs`, `UserPromptSubmit`).
+  Claude can't see its own context usage — nothing in a turn reports how many
+  tokens are being re-sent, and Claude Code has no timer or threshold event — so
+  this hook reads the tail of the session transcript, sums the tokens actually
+  re-sent, and once that passes a PO-frozen **120k** injects one short note
+  suggesting `/compact`. Fires **once per crossing**, re-arming only after a
+  compaction-sized drop: the note costs tokens on the turn it appears in, so
+  nagging every prompt would spend exactly what the tool saves (measured on a
+  12.6h session: 4 reminders total). Reminds on *size*, not "phase boundary" —
+  size is measurable, a phase boundary is a judgment, so the reminder hands the
+  timing call to the model and tells it to stay quiet mid-task. Override with
+  `TUNE_CONTEXT_REMIND_TOKENS`; remove the `UserPromptSubmit` entry to disable.
+  (TASK-079)
+
+### Fixed
+
+- **Plugin-shaped hook commands no longer misread as broken.** `cli/verify.mjs`
+  treated any registered command it couldn't resolve to an installed file as
+  stray or dead — including a plugin's own `${CLAUDE_PLUGIN_ROOT}`-based
+  registration, which it was never meant to check. Now reported as its own
+  always-ok informational line instead. (EPIC-008 / TASK-072)
+- **Adoption report no longer prints a false churn verdict over doubled
+  events.** Running the plugin and `tune-context init` together on one repo
+  registers each hook twice, so every event logs twice — this previously
+  surfaced as spurious "elevated re-read churn." The report now detects a
+  near-duplicate signature (records identical on session/tool/lever/detail
+  within a measured 100ms window, at ≥10% of assessable records) and withholds
+  the re-read-churn verdict instead of printing a number the doubling would
+  have faked. Thresholds are frozen from two independent real logs, not
+  guessed — a naively "safe" 1000ms window was shown to swallow real churn
+  instead. (EPIC-008 / TASK-072)
+- **Generated commands now match the detected package manager exactly.**
+  `CLAUDE.md` and `permissions.allow` used to assume npm-style `run` commands
+  regardless of lockfile. Now derived from one `runCmd(packageManager, script)`
+  table: npm/pnpm use `npm run build` / `pnpm run build` (`test` keeps its
+  shorthand), yarn uses the bare short form for all three — `yarn build`,
+  `yarn test`, `yarn lint` (PO decision). (EPIC-008 / TASK-073)
+- **`disabledMcpjsonServers` is now honoured.** A project `.mcp.json` server a
+  user rejected via `disabledMcpjsonServers` (in any settings file) no longer
+  gets a `permissions.allow` rule or a `CLAUDE.md` mention — previously
+  `tune-context init` wired it in regardless. Three neighbouring keys
+  (`enabledMcpjsonServers`, `allowedMcpServers`, `deniedMcpServers`) are
+  deliberately not treated as equivalent, verified against docs rather than
+  guessed — each would need introspection this CLI doesn't have.
+  (EPIC-008 / TASK-075)
+- **PreCompact snapshot files could collide across projects.** `state/` keyed
+  snapshots by a human-readable slug of `cwd` alone, which is not injective —
+  `/home/a/b` and `/home/a-b` (also `.`/`_` variants) slugged to the same
+  filename, so `SessionStart(compact)` could reinject one project's git state
+  into an unrelated session. A short hash of the real `cwd` is now appended to
+  the filename. **Breaking for `state/` only**: snapshots written under the old
+  filename shape are orphaned (harmless — a snapshot is only ever valid for the
+  one compaction right after it) rather than reused; the new retention policy
+  below cleans them up over time. (EPIC-008 / TASK-076)
+- **`pre-compact-snapshot.mjs` could exit non-zero.** Brought to parity with
+  `adoption-log.mjs`: an unwritable state directory (read-only volume,
+  misdirected `CLAUDE_CONFIG_DIR`) now fails the snapshot silently instead of
+  surfacing a nonzero exit from a hook at the exact moment a session is
+  compacting under context pressure. (EPIC-008 / TASK-076)
+- **Manual hook-install instructions now produce a working hook.** README
+  pointed at the raw `settings.json.tmpl`, which still has an unsubstituted
+  `{{HOOKS_DIR}}` placeholder and no instruction to replace it — followed
+  literally, the hook command was `node "{{HOOKS_DIR}}/adoption-log.mjs"` and
+  silently never ran. Replaced with a ready-to-paste `settings.json` snippet.
+  (EPIC-008 / TASK-078)
+- **Plugin-only installs now get a working `tune-context` command.** Claude
+  Code exposes `bin/` files under their literal filename — confirmed against
+  current docs, no extension-stripping — so `bin/tune-context.mjs` only ever
+  produced a bare `tune-context.mjs`. A plugin-only install (no
+  `npm install -g`) got "command not found" for the command README documents.
+  Added an extensionless `bin/tune-context` alias so both channels give the
+  identical command. (EPIC-008 / TASK-078)
+- **`tune-context --cwd` (no value) no longer crashes with a Node stacktrace.**
+  `resolve(undefined)` used to throw `ERR_INVALID_ARG_TYPE` straight to the
+  terminal; now reports "Missing value for `--cwd`" plus usage, on stderr,
+  exit 1. **Breaking:** an unrecognized *or missing* subcommand is now also
+  rejected the same way instead of silently running `init` — `init` is the
+  only accepted subcommand. README never documented calling this tool with no
+  arguments; every example already used explicit `init`. (EPIC-008 / TASK-078)
+
+### Changed
+
+- **One source of truth for `CLAUDE_CONFIG_DIR` resolution.** `cli/detect.mjs`'s
+  `claudeDirs()` now delegates the `CLAUDE_CONFIG_DIR || ~/.claude` rule to
+  `hooks/config-dir.mjs`'s `claudeBaseDir()` instead of re-implementing it —
+  the two could previously drift apart. No behavior change.
+  (EPIC-008 / TASK-074)
+- **Removed a dead `permissions` block from the settings template.**
+  `settings.json.tmpl` carried a `permissions.allow` block nothing ever read —
+  the CLI merges its own, computed from the detected stack, straight into the
+  *project's* settings instead. PO-approved removal. (EPIC-008 / TASK-074)
+- **`bin/tune-context.mjs`'s header states its real scope.** No longer reads
+  as a full twin of the `/tune-context` skill — names the two steps it
+  deliberately can't do (merging in a semantic-search MCP server, wiki-lever
+  wiring) instead of leaving the gap unstated. (EPIC-008 / TASK-075)
+
+### Added
+
+- **`state/` retention.** Snapshots untouched for 30 days are pruned on the
+  next PreCompact write anywhere on the machine — `state/` is one shared
+  directory across all projects, so any project's compaction sweeps it, not
+  only the project being written; the snapshot just written is never a prune
+  candidate. Previously `state/` was the only tune-context artifact with no
+  cleanup policy. (EPIC-008 / TASK-076)
+- **`tune-context --version`** (also `-v`), printing the bare number so
+  `$(tune-context --version)` is directly comparable. Read from the shipped
+  `package.json` — the same file `verify:plugin` cross-checks against
+  `plugin.json` and `marketplace.json`, so the CLI can't report a version the
+  manifests disagree with.
+- **README: "Keeping context lean while you work".** The tool configures a
+  lean setup, but shedding accumulated context stays a deliberate, recurring
+  act — `/compact` when a thread closes, `/clear` when switching tasks — and
+  the README never said so. Includes what the PreCompact/SessionStart pair
+  does and does not preserve across a compaction.
+- **`token-efficiency` §6 recommends `eval/adoption-report.mjs`.** Previously
+  the section on measuring whether doctrine is actually used pointed only at
+  `rag-usage`, a different package's tool — silent about the one instrument
+  this repo ships for the same purpose. (EPIC-008 / TASK-078)
+
+### Testing / packaging
+
+- **Unit test harness for the CLI.** `npm test` now also exercises
+  `cli/managed-block.mjs`, `cli/generate.mjs`, `cli/verify.mjs` and
+  `cli/detect.mjs` directly — previously only reachable end-to-end through
+  `smoke:init` — plus a structural guard that fails when a `cli/` export has
+  nothing importing it. (EPIC-008 / TASK-077)
+- **`verify:plugin` and `verify:pack` now guard `bin/` and
+  `eval/adoption-report.mjs`.** Both were tracked by git accidentally, not by
+  contract, despite README telling a plugin-only or npm install to run them —
+  a clone or tarball missing either would previously pass both checks anyway.
+  (EPIC-008 / TASK-078)
+
+### Upgrading from 1.1.0
+
+Re-running `tune-context init` over a 1.1.0 install is safe and was verified
+end-to-end: hook entries are not duplicated, unrelated `settings.json` keys and
+hand-written `CLAUDE.md` content are untouched, and your own
+`permissions.allow` rules are kept.
+
+Two leftovers are deliberate, because removing them would break "never
+clobber" — tune-context cannot tell its own past output from a rule you added
+on purpose:
+
+- **pnpm/yarn projects**: the npm-style rules 1.1.0 wrote (`Bash(npm test:*)`
+  and friends) stay in `.claude/settings.json` alongside the correct new ones
+  (`Bash(pnpm test:*)`). Harmless — an unused allow rule grants nothing extra
+  for a command you never run — but safe to delete by hand.
+- **PreCompact snapshots** under `<config dir>/tune-context/state/` written
+  before this release keep their old filenames and are ignored. The new
+  30-day retention deletes them on its own; no action needed.
+
 ## [1.1.0] — 2026-07-24
 
 Two hardening epics land together: consistent `CLAUDE_CONFIG_DIR` support with the

package/README.md

@@ -15,7 +15,7 @@ tune-context/
 ├── .claude-plugin/plugin.json   # Claude Code plugin manifest
 ├── skills/            # token-efficiency, caveman, cdd, phase-workflow, tune-context (+ templates/)
 ├── agents/            # explore-cheap, reviewer (model right-sizing)
-├── hooks/             # PreCompact state-doc, SessionStart re-inject, PostToolUse adoption log + hooks.json
+├── hooks/             # PreCompact state-doc, SessionStart re-inject, adoption log, context reminder + hooks.json
 ├── bin/ + cli/        # `tune-context init` — deterministic detect → generate → verify
 ├── eval/              # adoption-report.mjs (the rag-usage analog)
 └── scripts/           # verify-pack, smoke-init, sync-tune-context (dev/maintenance)
@@ -70,8 +70,9 @@ 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).
 
-**2. CLI `tune-context init`.** The deterministic, no-model twin of the skill — same
-managed-block rules, same never-clobber guarantee. Good for CI or scripted setup:
+**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
+CI or scripted setup:
 
 ```bash
 npx -p @bglocation/tune-context tune-context init           # runs in the current repo
@@ -83,6 +84,15 @@ 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:
+
+| Step | Skill | CLI |
+|---|---|---|
+| 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 |
+
 **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`:
@@ -129,6 +139,51 @@ Without the override the generated `settings.json` keeps the portable
 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.
 
+## Keeping context lean while you work
+
+Setup is the cheap half. The recurring half is **shedding context you no longer
+need** — and that stays a manual, deliberate act, because only you know when a
+piece of work is actually finished.
+
+Every turn re-sends the whole conversation as input. A session that has been
+running for hours pays for its early exploration on *every* later request, long
+after that detail stopped being useful. So:
+
+| When | Do | Why |
+|---|---|---|
+| A work thread closes (feature done, bug fixed) | `/compact` | Keeps the conclusions, drops the raw tool output that led to them |
+| Switching to unrelated work | `/clear` | Nothing from the old task is worth carrying — `/compact` would still keep a summary of it |
+| Long session, no natural break yet | `/compact` anyway | Waiting for auto-compact means paying full price right up to the limit |
+
+tune-context softens the cost of compacting rather than replacing it: its
+`PreCompact` hook snapshots your branch, dirty files and recent commits, and the
+`SessionStart(compact)` hook injects that back afterwards — so the mechanical
+state survives even though the transcript doesn't. Judgment calls and open
+threads do **not** survive; write those down before compacting if they matter.
+
+### The reminder is automatic
+
+Claude cannot see its own context usage — nothing in a turn tells the model how
+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`.
+
+- **Once per crossing, not per prompt.** The note itself costs tokens on the turn
+  it appears in, so it re-arms only after a compaction-sized drop. Measured on a
+  12.6-hour session: 4 reminders total.
+- **The model picks the moment.** The reminder tells Claude to stay quiet
+  mid-task and raise it when the thread closes — the hook can measure size, but
+  only the model can see whether you're mid-refactor.
+- **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.
+- **Turn it off:** delete the `UserPromptSubmit` entry from `settings.json`.
+
+Depth lives in the `phase-workflow` and `token-efficiency` skills (both installed
+by `tune-context init`), not here.
+
 ## Measuring adoption (does the doctrine actually get used?)
 `hooks/adoption-log.mjs` logs one JSONL line per event to
 `~/.claude/tune-context/adoption.jsonl` by default (under `CLAUDE_CONFIG_DIR`, the
@@ -142,6 +197,12 @@ It's registered under two Claude Code hook events —
 `PostToolUse` (every tool call) and `SubagentStart` (subagent spawns, which aren't
 regular tools).
 
+**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
+measured share of near-duplicate pairs it withholds the re-read-churn verdict
+instead of printing a number the doubling would have faked.
+
 ### Turn it on
 
 1. **Install the hook.** Either run **`/tune-context`** in your repo (it copies the
@@ -149,10 +210,34 @@ regular tools).
    for you), or do it by hand:
    - 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
-     repo's `.claude/settings.json` for just that one.
+   - merge this into your `settings.json` — `~/.claude/settings.json` for every
+     project, or a repo's `.claude/settings.json` for just that one (if the file
+     doesn't exist yet, this can be the whole thing):
+     ```json
+     {
+       "hooks": {
+         "PostToolUse": [
+           {
+             "matcher": "*",
+             "hooks": [
+               { "type": "command", "command": "node \"$HOME/.claude/hooks/adoption-log.mjs\"" }
+             ]
+           }
+         ],
+         "SubagentStart": [
+           {
+             "matcher": "*",
+             "hooks": [
+               { "type": "command", "command": "node \"$HOME/.claude/hooks/adoption-log.mjs\"" }
+             ]
+           }
+         ]
+       }
+     }
+     ```
+     Using `CLAUDE_CONFIG_DIR`? Replace `$HOME/.claude/hooks` with the literal
+     override path instead — `$HOME` is not expanded there (see
+     [`CLAUDE_CONFIG_DIR`](#claude_config_dir) above).
 
 2. **No reload needed.** Claude Code watches the settings files, so the new hooks
    go live within a few seconds of saving — **you do not need to reload VSCode,

package/bin/tune-context

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// Extensionless alias so the plugin channel's bin/ PATH entry gives the same
+// `tune-context` command the npm channel already provides via package.json's
+// `bin` field. Claude Code exposes bin/ files under their literal filename —
+// no extension-stripping — so without this file, a plugin-only install
+// (no `npm install -g`) only offers `tune-context.mjs` (TASK-078). Real logic
+// stays in tune-context.mjs; this just re-executes it against the same
+// process.argv.
+import { main } from './tune-context.mjs';
+
+main();

package/bin/tune-context.mjs

@@ -1,10 +1,25 @@
 #!/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,
@@ -21,26 +36,83 @@ 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);
@@ -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;
 }