@bglocation/tune-context 2.1.0 → 2.3.0

package/cli/sync-doctrine.mjs

@@ -14,25 +14,42 @@ import { chmodSync, cpSync, existsSync, mkdirSync, readdirSync, rmSync } from 'n
 import { dirname, join } from 'node:path';
 
 /**
+ * Everything this package deploys into a Claude config dir, as
+ * `{kind, name, source}` — one enumeration, used both by the copier below and
+ * by verify's staleness check (TASK-081). Two lists would drift apart, and a
+ * freshness check that walks a *different* set than the sync did would go
+ * green on exactly the file nobody thought to add to it.
+ *
  * @param {string} pkgRoot - root of the tune-context package (contains skills/, agents/, hooks/)
- * @param {string} claudeDir - destination Claude config dir (e.g. ~/.claude)
- * @returns {{kind: string, name: string, dest: string}[]} synced items
+ * @returns {{kind: string, name: string, source: string}[]}
  */
-export function syncDoctrine(pkgRoot, claudeDir) {
-  const synced = [];
+export function doctrineEntries(pkgRoot) {
+  const entries = [];
   for (const kind of ['skills', 'agents', 'hooks']) {
     const from = join(pkgRoot, kind);
     if (!existsSync(from)) continue;
     for (const entry of readdirSync(from)) {
       if (kind === 'hooks' && entry === 'hooks.json') continue; // plugin-only manifest, not a script to install
-      const s = join(from, entry);
-      const d = join(claudeDir, kind, entry);
-      rmSync(d, { recursive: true, force: true });
-      mkdirSync(dirname(d), { recursive: true });
-      cpSync(s, d, { recursive: true });
-      if (kind === 'hooks') chmodSync(d, 0o755);
-      synced.push({ kind, name: entry, dest: d });
+      entries.push({ kind, name: entry, source: join(from, entry) });
     }
   }
+  return entries;
+}
+
+/**
+ * @param {string} pkgRoot - root of the tune-context package (contains skills/, agents/, hooks/)
+ * @param {string} claudeDir - destination Claude config dir (e.g. ~/.claude)
+ * @returns {{kind: string, name: string, dest: string}[]} synced items
+ */
+export function syncDoctrine(pkgRoot, claudeDir) {
+  const synced = [];
+  for (const { kind, name, source } of doctrineEntries(pkgRoot)) {
+    const d = join(claudeDir, kind, name);
+    rmSync(d, { recursive: true, force: true });
+    mkdirSync(dirname(d), { recursive: true });
+    cpSync(source, d, { recursive: true });
+    if (kind === 'hooks') chmodSync(d, 0o755);
+    synced.push({ kind, name, dest: d });
+  }
   return synced;
 }

package/cli/verify.mjs

@@ -1,9 +1,43 @@
 // Re-checks what generate.mjs claims to have done — "the merge actually
 // 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 { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, join, resolve } from 'node:path';
+import { doctrineEntries } from './sync-doctrine.mjs';
+
+/**
+ * Content fingerprint of a deployed artifact — a file, or a whole directory
+ * (skills are directories; `skills/tune-context` carries its own templates/).
+ *
+ * A directory hashes as the sorted list of `relative path + content hash`, so a
+ * file MISSING from inside a synced skill, or an extra one left behind by an
+ * older shape, is drift too — not just an edited byte. Sorting is what makes it
+ * reproducible across filesystems that hand back readdir in different orders.
+ *
+ * Mode is deliberately not hashed: syncDoctrine chmods hooks to 755 after
+ * copying, so folding the exec bit in here would report a rewrite as drift on
+ * every platform where the package's own bits differ. The exec bit already has
+ * its own check.
+ *
+ * @returns {string|null} null when the path does not exist
+ */
+export function fingerprint(path) {
+  if (!existsSync(path)) return null;
+  const hash = createHash('sha256');
+  const walk = (current, rel) => {
+    const stat = statSync(current);
+    if (stat.isDirectory()) {
+      for (const entry of readdirSync(current).sort()) walk(join(current, entry), rel ? `${rel}/${entry}` : entry);
+      return;
+    }
+    hash.update(`${rel}\0`);
+    hash.update(createHash('sha256').update(readFileSync(current)).digest());
+  };
+  walk(path, '');
+  return hash.digest('hex');
+}
 
 function readJson(path) {
   try {
@@ -50,9 +84,83 @@ function expandHome(p) {
 const PLUGIN_PATH_HINT = /\$\{CLAUDE_PLUGIN_ROOT\}|[\\/]plugins[\\/]/;
 
 /**
- * @returns {{ok: boolean, checks: {name: string, ok: boolean, detail?: string}[]}}
+ * Are the deployed copies still the ones this package ships? (TASK-081)
+ *
+ * `npm i -g` updates the package; it does NOT touch what an earlier `init`
+ * copied into ~/.claude. settings.json points at those copies, so a release
+ * that changes hooks/ goes live only after another `init`. Observed right after
+ * publishing 2.1.0: the CLI reported 2.1.0, verify was all green, and the
+ * deployed context-reminder.mjs was still the 2.0.x file — the *only* file the
+ * release had changed.
+ *
+ * Two rules keep this from crying wolf:
+ *
+ *  - **Only what is actually deployed is compared.** An artifact absent from
+ *    claudeDir is not reported here at all, which is what makes a plugin-channel
+ *    install (registrations pointing at `${CLAUDE_PLUGIN_ROOT}`, no copies
+ *    anywhere) impossible to false-red: there is nothing to compare, so nothing
+ *    is claimed. Presence of the things that MUST exist is a separate check.
+ *  - **No package to compare against means "not checked", never a tick.** A
+ *    caller that cannot say where the installed package lives gets `unknown`,
+ *    which prints as `?` and neither passes nor fails — the TASK-070 rule that
+ *    an unobservable thing must not be reported as verified.
+ *
+ * @param {string|null} pkgRoot - root of the installed package, or null/undefined
+ * @returns {{name: string, ok: boolean, detail?: string, unknown?: boolean}[]}
  */
-export function verify({ claudeDir, userSettingsPath, expectedHookCommands, projectSettingsPath, expectedPermissions }) {
+export function staleDoctrineEntries(claudeDir, pkgRoot) {
+  if (!pkgRoot || !existsSync(pkgRoot)) return null;
+  const stale = [];
+  let compared = 0;
+  for (const { kind, name, source } of doctrineEntries(pkgRoot)) {
+    const deployed = join(claudeDir, kind, name);
+    const deployedPrint = fingerprint(deployed);
+    if (deployedPrint === null) continue; // not deployed through this channel — not ours to judge
+    compared += 1;
+    if (deployedPrint !== fingerprint(source)) stale.push(`${kind}/${name}`);
+  }
+  return { compared, stale };
+}
+
+function freshnessChecks(claudeDir, pkgRoot) {
+  const result = staleDoctrineEntries(claudeDir, pkgRoot);
+  if (result === null) {
+    return [
+      {
+        name: 'deployed skills/agents/hooks match the installed package',
+        ok: false,
+        unknown: true,
+        detail: 'not checked — no installed package to compare against; re-run `tune-context init` if a release changed hooks/',
+      },
+    ];
+  }
+
+  const { compared, stale } = result;
+  if (compared === 0) {
+    return [
+      {
+        name: 'deployed skills/agents/hooks match the installed package',
+        ok: false,
+        unknown: true,
+        detail: `not checked — nothing from this package is deployed under ${claudeDir}`,
+      },
+    ];
+  }
+
+  return [
+    {
+      name: `deployed skills/agents/hooks match the installed package (${compared} compared)`,
+      ok: stale.length === 0,
+      detail: stale.length ? `stale: ${stale.join(', ')} — content differs from the installed package; re-run \`tune-context init\`` : undefined,
+    },
+  ];
+}
+
+/**
+ * @param {string} [pkgRoot] - installed package root, for the staleness check
+ * @returns {{ok: boolean, checks: {name: string, ok: boolean, detail?: string, unknown?: boolean}[]}}
+ */
+export function verify({ claudeDir, userSettingsPath, expectedHookCommands, projectSettingsPath, expectedPermissions, pkgRoot }) {
   const checks = [];
 
   // Cross-check, not two independent presence checks. The old code asked
@@ -164,5 +272,9 @@ export function verify({ claudeDir, userSettingsPath, expectedHookCommands, proj
     checks.push({ name: `skill ${skill} installed`, ok, detail: ok ? undefined : `missing ${join(skillsDir, skill, 'SKILL.md')}` });
   }
 
-  return { ok: checks.every((c) => c.ok), checks };
+  checks.push(...freshnessChecks(claudeDir, pkgRoot));
+
+  // `unknown` is neither a pass nor a failure: it must not turn a healthy
+  // install red, and it must not be counted as verified either.
+  return { ok: checks.every((c) => c.ok || c.unknown === true), checks };
 }

package/eval/adoption-report.mjs

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

package/eval/mcp-probe.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bglocation/tune-context",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Context-efficiency configurator for Claude Code \u2014 token-saving doctrine packaged as skills, plus a tune-context configurator that scaffolds a lean CLAUDE.md, doctrine skills, subagents, settings, hooks and MCP wiring.",
   "type": "module",
   "license": "MIT",

package/skills/tune-context/SKILL.md

@@ -22,6 +22,17 @@ than rewriting the file. For JSON (`.mcp.json`, `settings.json`) there are no
 markers — merge key-by-key and preserve every existing key. This is what makes a
 second run a no-op.
 
+**Only derived content goes inside the block.** The block carries what detection
+produced — project name, build/test/lint, MCP rules, the doctrine pointer. The
+sections a human writes (what this is, architecture, conventions) are seeded
+**below** the closing marker from `CLAUDE.md.project.authored.tmpl`, once, and
+are never regenerated. Before TASK-082 they sat inside the block behind "fill in"
+prompts, i.e. the tool asked the user to write in the one place it overwrites;
+re-running it replaced a repo's architecture notes with placeholders. If you meet
+a CLAUDE.md still in that shape — authored text inside the markers — **do not
+regenerate it**: move those sections below the closing marker first (the CLI
+refuses outright and prints the same instruction).
+
 **Delta only, never duplicate.** If the existing hand-written CLAUDE.md already
 covers the template's content (build/test/lint, architecture, conventions), the
 managed block carries **only what is missing** — usually just pointers to the
@@ -98,10 +109,13 @@ covering the detected build/test/lint commands.
 
 ## 2. Generate (idempotent, never clobber)
 
-1. **Project `./CLAUDE.md`** from `${CLAUDE_SKILL_DIR}/templates/CLAUDE.md.project.tmpl`.
-   Fill the slots from detection; delete the slot guide comment; keep the managed
-   markers. If the file exists, replace only the managed block — hand-written
-   content outside it survives untouched.
+1. **Project `./CLAUDE.md`** from `${CLAUDE_SKILL_DIR}/templates/CLAUDE.md.project.tmpl`
+   (managed block) plus `CLAUDE.md.project.authored.tmpl` (the half below it).
+   Fill the block's slots from detection; delete the slot guide comment; keep the
+   managed markers. Seed the authored half **only when creating the file** — if
+   the file exists, replace the managed block and nothing else. Never write
+   detected facts below the marker, and never write authored prose above it: the
+   split is what makes re-running safe.
 2. **User `~/.claude/CLAUDE.md`** from `${CLAUDE_SKILL_DIR}/templates/CLAUDE.md.user.tmpl`
    — only if it is missing or clearly untuned. Never overwrite a user-tuned file
    without asking.

package/skills/tune-context/templates/CLAUDE.md.project.authored.tmpl

@@ -0,0 +1,16 @@
+<!-- Everything below is yours. tune-context seeds these headings once, when it
+     first creates this file, and never rewrites them: re-running the tool
+     replaces only the managed block above. Delete whatever you don't need.
+     Keep it thin — headings and pointers here, depth in skills. -->
+
+## What this is
+
+<!-- fill in: one sentence, what this project is -->
+
+## Architecture
+
+<!-- fill in: 3-6 lines, module -> responsibility -->
+
+## Conventions that bite
+
+<!-- fill in: only rules that bite (things that break if ignored) -->

package/skills/tune-context/templates/CLAUDE.md.project.tmpl

@@ -1,10 +1,10 @@
 <!-- >>> tune-context (managed) >>>
-     Regenerated by /tune-context. Edit freely OUTSIDE this block — content
-     outside the markers is never touched. -->
+     Regenerated by /tune-context and `tune-context init`. Everything between
+     these markers is DERIVED from detection and is rewritten on every run —
+     never hand-edit it. Your own content goes BELOW the block, where the tool
+     never reaches. -->
 # CLAUDE.md — {{PROJECT_NAME}}
 
-{{ONE_LINE_WHAT_THIS_IS}}
-
 ## Build / test / lint
 ```bash
 {{BUILD_CMD}}
@@ -17,23 +17,14 @@
 {{MCP_RULES}}
 Depth lives in skills: `token-efficiency`, `cdd`, `phase-workflow` (and
 `/caveman` for terse output) — not in this file.
-
-## Architecture
-{{ARCHITECTURE_BULLETS}}
-
-## Conventions that bite
-{{CONVENTIONS}}
-
 <!-- <<< tune-context (managed) <<< -->
 
 <!--
-Slot guide (delete after filling):
+Slot guide (managed block only — all of these are filled from detection):
   PROJECT_NAME          package/repo name
-  ONE_LINE_WHAT_THIS_IS one sentence, what the project is
   BUILD_CMD/TEST_CMD/LINT_CMD  verified commands (must actually exist)
   RUN_NOTES             how to run locally, if non-obvious
   MCP_RULES             one line per detected MCP server (see tune-context skill)
-  ARCHITECTURE_BULLETS  3-6 lines, module -> responsibility
-  CONVENTIONS           only rules that bite (things that break if ignored)
-Keep this file thin: headings + pointers. Depth goes into skills.
+Sections you write by hand are seeded once from CLAUDE.md.project.authored.tmpl
+and live BELOW the block. Nothing outside the markers is ever regenerated.
 -->