@bglocation/tune-context 2.1.0 → 2.2.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": "2.1.0",
+      "version": "2.2.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": "2.1.0",
+  "version": "2.2.0",
   "author": {
     "name": "Szymon Walczak",
     "url": "https://bglocation.dev"

package/CHANGELOG.md

@@ -5,6 +5,57 @@ 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.2.0] — 2026-07-27
+
+### Changed
+
+- **The managed block no longer holds sections you are meant to write yourself.**
+  `## Architecture`, `## Conventions that bite` and the one-line summary used to
+  sit *inside* the markers behind `<!-- fill in: … -->` prompts — so the tool
+  invited you to write in the one place it overwrites, and re-running it replaced
+  a repo's own documentation with placeholders. Measured on this repo before the
+  fix: 36 lines replaced, every one inside the block. Those sections are now
+  seeded **below** the closing marker, once, from a new
+  `CLAUDE.md.project.authored.tmpl`, and are never regenerated. The block keeps
+  only detected facts: project name, build/test/lint, MCP rules, doctrine pointer.
+  Affects both channels — the CLI and the `/tune-context` skill share the template.
+
+- **`verify` no longer passes an install it did not actually check.** Deployed
+  hooks, agents and skills are now compared by content against the installed
+  package, so a copy left behind by an earlier install is reported by name.
+  Skills compare recursively, so an edit inside `skills/tune-context/templates/`
+  counts too. Agents and the `tune-context` skill had **no check at all** before.
+  Previously `verify` asserted only that a hook file existed and was executable
+  — which is how 2.1.0 shipped with the CLI reporting 2.1.0, every check green,
+  and the two-releases-old `context-reminder.mjs` still deployed.
+
+### Added
+
+- **`tune-context verify`** — a read-only command that reports on an existing
+  install without touching anything. It exists because `init` *cannot* do this
+  job: init re-syncs before it verifies, so the drift an upgrade leaves behind
+  is already healed by the time init's own verify step looks. Run it after
+  upgrading. `init` now also names what it refreshed, instead of healing silently.
+- A `?` verdict, distinct from ✓ and ✗, for checks that could not be observed —
+  currently "no installed package to compare against" and "nothing from this
+  package is deployed here" (the plugin channel). It neither passes nor fails.
+- **A guard for files still in the old layout.** `init` now classifies an existing
+  `CLAUDE.md` before writing. If authored text sits inside the managed block, it
+  writes **nothing** to that file, finishes every other step (hooks, settings,
+  doctrine), and prints what to move and where. A block whose slots still hold the
+  untouched placeholders migrates silently — nothing to lose there.
+- `tune-context init --force-claude-md` — regenerate a guarded file anyway,
+  discarding the in-block content. Opt-in only; without it, such a file could
+  never be migrated by the tool at all.
+
+### Fixed
+
+- Migrating an old `CLAUDE.md` no longer seeds a **second, empty** copy of a
+  section the file already carries below the marker. The likeliest legacy shape
+  is a block whose slots were never filled precisely because their owner took the
+  advice and wrote below it; seeding on top of that lost nothing, but left a
+  curated file messier than it was found.
+
 ## [2.1.0] — 2026-07-26
 
 ### Changed
@@ -329,6 +380,10 @@ action needed on upgrade.
   (`explore-cheap`, `reviewer`), the PreCompact / SessionStart / PostToolUse hook
   suite, and the adoption report (`eval/adoption-report.mjs`).
 
+[2.2.0]: https://gitlab.com/bglocation/tune-context/-/tags/v2.2.0
+[2.1.0]: https://gitlab.com/bglocation/tune-context/-/tags/v2.1.0
+[2.0.1]: https://gitlab.com/bglocation/tune-context/-/tags/v2.0.1
+[2.0.0]: https://gitlab.com/bglocation/tune-context/-/tags/v2.0.0
 [1.1.0]: https://gitlab.com/bglocation/tune-context/-/tags/v1.1.0
 [1.0.1]: https://gitlab.com/bglocation/tune-context/-/tags/v1.0.1
 [1.0.0]: https://gitlab.com/bglocation/tune-context/-/tags/v1.0.0

package/README.md

@@ -39,6 +39,21 @@ That single command detects the stack + MCP servers, writes a lean `CLAUDE.md`,
 syncs the doctrine skills/agents/hooks into `~/.claude/`, merges hooks and
 permissions, and prints a verification report. It's idempotent — safe to re-run.
 
+Safe to re-run means exactly this: the managed block in `CLAUDE.md` holds only
+what detection produced and is rewritten every time; everything below the closing
+marker is yours and is never touched, including the `## Architecture` and
+`## Conventions that bite` sections the tool seeds there once. Write your own
+notes below the marker, not inside the block.
+
+**After upgrading the package, re-run `init`.** `npm i -g` updates the package,
+not the hooks an earlier run copied into `~/.claude/hooks/` — `settings.json`
+points at those copies, so a release that changes hooks goes live only after
+another `init`. To check without changing anything:
+
+```bash
+tune-context verify        # read-only: is what's deployed still what ships?
+```
+
 Install it globally if you'll use it across repos:
 
 ```bash

package/bin/tune-context.mjs

@@ -29,7 +29,7 @@ import {
   mergeHooks,
   mergePermissions,
 } from '../cli/generate.mjs';
-import { verify } from '../cli/verify.mjs';
+import { staleDoctrineEntries, verify } from '../cli/verify.mjs';
 
 const HOOK_EVENTS = [
   { event: 'PreCompact', scriptName: 'pre-compact-snapshot.mjs' },
@@ -56,9 +56,19 @@ function usage() {
   return `tune-context init — configure this repo for token-efficient Claude Code use.
 
 Usage:
-  tune-context init [--cwd <dir>]
+  tune-context init [--cwd <dir>] [--force-claude-md]
+  tune-context verify [--cwd <dir>]
   tune-context --help
   tune-context --version
+
+  verify              Check an existing install without changing anything —
+                      including whether the deployed hooks/skills/agents still
+                      match this package. Run it after upgrading: an upgrade
+                      does not refresh copies an earlier init made.
+
+  --force-claude-md   Regenerate a project CLAUDE.md whose hand-written content
+                      still sits inside the managed block. Discards that content.
+                      Without it, such a file is left untouched.
 `;
 }
 
@@ -73,14 +83,21 @@ export function parseArgs(argv) {
   // 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') {
+  // `verify` joins `init` as an accepted command (TASK-081). It writes nothing,
+  // which is the point: init syncs before it verifies, so init can never
+  // observe the drift an upgrade leaves behind — only a check that runs on its
+  // own can. The TASK-078 rule still holds: an unknown command fails loudly.
+  if (command !== 'init' && command !== 'verify') {
     return {
       mode: 'error',
-      message: command === undefined ? 'Missing command: init' : `Unknown command: ${command}`,
+      message: command === undefined ? 'Missing command: init or verify' : `Unknown command: ${command}`,
     };
   }
+  // Opt-in only, and never inferred: this is the one flag that can destroy
+  // content the tool otherwise refuses to touch (TASK-082).
+  const forceClaudeMd = rest.includes('--force-claude-md');
   const cwdFlagIdx = rest.indexOf('--cwd');
-  if (cwdFlagIdx === -1) return { mode: 'init', cwd: process.cwd() };
+  if (cwdFlagIdx === -1) return { mode: command, cwd: process.cwd(), forceClaudeMd };
   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
@@ -88,10 +105,10 @@ export function parseArgs(argv) {
   if (value === undefined || value.startsWith('-')) {
     return { mode: 'error', message: 'Missing value for --cwd' };
   }
-  return { mode: 'init', cwd: resolve(value) };
+  return { mode: command, cwd: resolve(value), forceClaudeMd };
 }
 
-function runInit(cwd) {
+function runInit(cwd, { forceClaudeMd = false } = {}) {
   const templatesDir = join(pkgRoot, 'skills', 'tune-context', 'templates');
   const { claudeDir } = claudeDirs();
 
@@ -115,9 +132,16 @@ function runInit(cwd) {
 
   const detection = { stack, mcpServers };
 
+  // Sample staleness BEFORE syncing. init's own sync heals drift, so by the
+  // time verify runs at the end there is nothing left to find — the whole
+  // reason `tune-context verify` exists as a command of its own (TASK-081).
+  // What init can still do, and what an upgrading user needs to hear, is name
+  // what WAS stale and has just been refreshed.
+  const wasStale = staleDoctrineEntries(claudeDir, pkgRoot)?.stale ?? [];
+
   const synced = installDoctrine(pkgRoot, claudeDir);
   const userClaudeMd = generateUserClaudeMd(claudeDir, templatesDir);
-  const projectClaudeMd = generateProjectClaudeMd(cwd, detection, templatesDir);
+  const projectClaudeMd = generateProjectClaudeMd(cwd, detection, templatesDir, { force: forceClaudeMd });
 
   const settingsTemplate = loadSettingsTemplate(templatesDir);
   const hooksAdded = mergeHooks(existing.userSettingsJson, { hooks: settingsTemplate.hooks });
@@ -130,6 +154,7 @@ function runInit(cwd) {
     projectSettingsPath: existing.projectSettingsJson,
     expectedHookCommands: HOOK_EVENTS,
     expectedPermissions: permissionsAllow,
+    pkgRoot,
   });
 
   console.log(`tune-context init — ${cwd}\n`);
@@ -138,8 +163,20 @@ function runInit(cwd) {
     console.log('  build/test/lint commands not detected for this ecosystem — filled with TODO placeholders in CLAUDE.md.');
   }
   console.log(`\nDoctrine synced to ${claudeDir}: ${synced.length} item(s)`);
+  if (wasStale.length) {
+    const noun = wasStale.length === 1 ? 'copy' : 'copies';
+    console.log(`  refreshed ${wasStale.length} stale ${noun} left behind by an earlier install: ${wasStale.join(', ')}`);
+  }
   console.log(`User CLAUDE.md: ${userClaudeMd.changed ? 'written' : `skipped (${userClaudeMd.skipped})`}`);
-  console.log(`Project CLAUDE.md: ${projectClaudeMd.changed ? `updated ${projectClaudeMd.path}` : 'already up to date'}`);
+  if (projectClaudeMd.guarded) {
+    console.log(`Project CLAUDE.md: SKIPPED — ${projectClaudeMd.skipped}`);
+  } else {
+    // migrated is checked first: a legacy file whose owner already wrote their
+    // own sections below the marker migrates without being seeded, so `seeded`
+    // alone would report that run as a plain "updated".
+    const how = projectClaudeMd.migrated ? 'migrated to the new layout' : projectClaudeMd.seeded ? 'created' : 'updated';
+    console.log(`Project CLAUDE.md: ${projectClaudeMd.changed ? `${how} ${projectClaudeMd.path}` : 'already up to date'}`);
+  }
   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'}`);
@@ -148,13 +185,71 @@ function runInit(cwd) {
     console.log(`  skipped (rejected via disabledMcpjsonServers): ${rejectedServers.map((s) => s.name).join(', ')} — no permission rule, no CLAUDE.md line`);
   }
 
+  // Loud, and separated from the one-line summary: this is the only step that
+  // finished with nothing written, and the user has to act for it to land.
+  if (projectClaudeMd.guarded) {
+    console.log(`
+! ${projectClaudeMd.path} was NOT written.
+  It predates the current layout: "## Architecture" / "## Conventions that bite"
+  sit INSIDE the managed markers, where every run regenerates. Your text is
+  still there and untouched.
+  To migrate: move those sections BELOW the "${'<!-- <<< tune-context (managed) <<< -->'}"
+  line, then re-run init — everything outside the markers is never touched again.
+  To regenerate anyway and lose them: tune-context init --force-claude-md`);
+  }
+
   console.log(`\nVerify: ${result.ok ? 'OK' : 'FAILED'}`);
   for (const check of result.checks) {
-    console.log(`  ${check.ok ? '✓' : '✗'} ${check.name}${check.detail ? ` — ${check.detail}` : ''}`);
+    // `?` is its own verdict: something we could not observe, reported as
+    // neither verified nor broken (TASK-081).
+    const mark = check.unknown ? '?' : check.ok ? '✓' : '✗';
+    console.log(`  ${mark} ${check.name}${check.detail ? ` — ${check.detail}` : ''}`);
   }
+
+  // Said on every run, not only when drift is found: the moment a user learns
+  // this is the moment they upgrade, and by then a stale hook is already live.
+  console.log(`\nNote: upgrading the package does not refresh hooks already installed in ${join(claudeDir, 'hooks')}.
+  Re-run \`tune-context init\` after any release that changes hooks/ — the staleness check above is what catches it if you don't.`);
+
   if (!result.ok) process.exitCode = 1;
 }
 
+/**
+ * Read-only counterpart to init: report on an install without touching a single
+ * file. Detection still runs, because the expected permissions depend on the
+ * project's own stack — but nothing is written, so this is safe to run anywhere,
+ * any number of times, including from CI after an upgrade.
+ */
+function runVerify(cwd) {
+  const { claudeDir } = claudeDirs();
+  const existing = detectExistingConfig(cwd);
+  const detection = { stack: detectStack(cwd), mcpServers: detectMcpServers(cwd) };
+  const permissionsAllow = buildPermissionsAllow(detection);
+
+  const result = verify({
+    claudeDir,
+    userSettingsPath: existing.userSettingsJson,
+    projectSettingsPath: existing.projectSettingsJson,
+    expectedHookCommands: HOOK_EVENTS,
+    expectedPermissions: permissionsAllow,
+    pkgRoot,
+  });
+
+  console.log(`tune-context verify — ${cwd}\n`);
+  console.log(`Verify: ${result.ok ? 'OK' : 'FAILED'}`);
+  for (const check of result.checks) {
+    const mark = check.unknown ? '?' : check.ok ? '✓' : '✗';
+    console.log(`  ${mark} ${check.name}${check.detail ? ` — ${check.detail}` : ''}`);
+  }
+  // A read-only command owes the reader the next step. Run on a machine that
+  // never ran init, this prints a screen of ✗ and, without the line below,
+  // nothing that says the whole list is one command away from green.
+  if (!result.ok) {
+    console.log('\nNext: `tune-context init` writes what is missing and refreshes what drifted. It never edits content outside the managed block.');
+    process.exitCode = 1;
+  }
+}
+
 export function main() {
   const parsed = parseArgs(process.argv.slice(2));
   if (parsed.mode === 'help') {
@@ -168,8 +263,10 @@ export function main() {
     // touched on an invalid invocation (TASK-078).
     process.stderr.write(`${parsed.message}\n\n${usage()}`);
     process.exitCode = 1;
+  } else if (parsed.mode === 'verify') {
+    runVerify(parsed.cwd);
   } else {
-    runInit(parsed.cwd);
+    runInit(parsed.cwd, { forceClaudeMd: parsed.forceClaudeMd });
   }
 }
 

package/cli/generate.mjs

@@ -5,7 +5,37 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { syncDoctrine } from './sync-doctrine.mjs';
-import { upsertManagedBlock } from './managed-block.mjs';
+import { END_MARKER, START_MARKER, upsertManagedBlock } from './managed-block.mjs';
+
+/**
+ * Headings the PRE-TASK-082 template kept INSIDE the managed block, together
+ * with the exact placeholders the CLI wrote into them (old generate.mjs slots
+ * ONE_LINE_WHAT_THIS_IS / ARCHITECTURE_BULLETS / CONVENTIONS).
+ *
+ * They exist here for exactly one reason: recognising a file written by an
+ * older version. The current template emits neither, so "does the block still
+ * contain them" is a precise test for the old layout — no heuristics, no
+ * guessing whether prose "looks hand-written".
+ *
+ * This is the one place that deliberately encodes knowledge of a previous
+ * template. Deleting it would not break generation; it would break the guard
+ * that stops a regeneration from erasing someone's documentation.
+ */
+const LEGACY_AUTHORED_HEADINGS = ['## Architecture', '## Conventions that bite'];
+const LEGACY_PLACEHOLDERS = [
+  '<!-- fill in: one sentence, what this project is -->',
+  '<!-- fill in: 3-6 lines, module -> responsibility -->',
+  '<!-- fill in: only rules that bite -->',
+];
+
+/**
+ * The headings the seed would introduce. If the file already carries one of them
+ * OUTSIDE the block it already has an authored half, and seeding would staple a
+ * second, empty copy above the one its owner actually wrote. A legacy file whose
+ * in-block slots were never filled *because* the owner wrote below the marker is
+ * exactly that case, and it is the likeliest one: they followed the advice.
+ */
+const SEEDED_HEADINGS = ['## What this is', ...LEGACY_AUTHORED_HEADINGS];
 
 /**
  * The hooks directory baked into settings.json commands.
@@ -86,9 +116,105 @@ function templateInnerBlock(templatePath) {
   return raw.slice(startLineEnd, end).trimEnd();
 }
 
-export function generateProjectClaudeMd(cwd, detection, templatesDir) {
-  const templatePath = join(templatesDir, 'CLAUDE.md.project.tmpl');
-  const inner = templateInnerBlock(templatePath);
+/**
+ * Which layout an existing project CLAUDE.md is in — the whole guard rests on
+ * this one classification.
+ *
+ * @param {string|null} existing - file content, or null if there is no file
+ * @returns {'absent'|'no-block'|'current'|'legacy-empty'|'legacy-authored'}
+ *
+ *   absent          - nothing there yet; create block + seed the authored part
+ *   no-block        - a hand-written CLAUDE.md with no markers; appending our
+ *                     block cannot touch what is already there
+ *   current         - post-TASK-082 layout; regenerate the block, nothing else
+ *   legacy-empty    - old layout, the authored slots still hold their untouched
+ *                     placeholders; migrating loses nothing, so do it silently
+ *   legacy-authored - old layout with real content inside the block; the ONLY
+ *                     case that must not be overwritten
+ *
+ * "All three placeholders still present verbatim" is the test for legacy-empty,
+ * so any deviation — filled in, reworded, or a section deleted — classifies as
+ * authored. The asymmetry is deliberate: a needless guard costs one message, a
+ * missed one costs somebody's documentation.
+ */
+export function classifyProjectClaudeMd(existing) {
+  if (existing == null) return 'absent';
+  const start = existing.indexOf(START_MARKER);
+  const end = existing.indexOf(END_MARKER);
+  if (start === -1 || end === -1 || end < start) return 'no-block';
+  const block = existing.slice(start, end);
+  if (!LEGACY_AUTHORED_HEADINGS.some((heading) => block.includes(heading))) return 'current';
+  return LEGACY_PLACEHOLDERS.every((placeholder) => block.includes(placeholder)) ? 'legacy-empty' : 'legacy-authored';
+}
+
+/**
+ * The seeded half of the project CLAUDE.md. A bare ENOENT here would surface as
+ * a Node stacktrace mid-init; the same reasoning as templateInnerBlock's marker
+ * check — a broken install must say what is broken, not fail cryptically or,
+ * worse, quietly skip the half of the file the user is meant to write in.
+ */
+function readAuthoredTemplate(templatesDir) {
+  const path = join(templatesDir, 'CLAUDE.md.project.authored.tmpl');
+  if (!existsSync(path)) throw new Error(`missing template ${path} — the authored half of CLAUDE.md cannot be seeded`);
+  return readFileSync(path, 'utf8');
+}
+
+/**
+ * Put the seeded authored skeleton directly under the managed block, so the
+ * generated document reads top-to-bottom (derived facts, then your own notes)
+ * instead of appending it after whatever else the file already holds.
+ */
+function hasAuthoredSectionsOutsideBlock(content) {
+  const start = content.indexOf(START_MARKER);
+  const end = content.indexOf(END_MARKER);
+  const outside =
+    start === -1 || end === -1 || end < start ? content : content.slice(0, start) + content.slice(end + END_MARKER.length);
+  return SEEDED_HEADINGS.some((heading) => outside.includes(heading));
+}
+
+function insertAuthoredSeed(content, seed) {
+  const idx = content.indexOf(END_MARKER);
+  const body = seed.trim();
+  if (idx === -1) return `${content.trimEnd()}\n\n${body}\n`;
+  const cut = idx + END_MARKER.length;
+  const tail = content.slice(cut).replace(/^\n+/, '');
+  return tail ? `${content.slice(0, cut)}\n\n${body}\n\n${tail}` : `${content.slice(0, cut)}\n\n${body}\n`;
+}
+
+/**
+ * Write/refresh the project CLAUDE.md.
+ *
+ * The managed block carries ONLY what detection produced. Sections a human
+ * writes (what this is, architecture, conventions) are seeded once, BELOW the
+ * block, and never rewritten — the same never-clobber guarantee this module
+ * already gives ~/.claude/CLAUDE.md and settings.json. Before TASK-082 those
+ * sections lived inside the block with "fill in" prompts, i.e. the tool invited
+ * you to write exactly where it overwrites.
+ *
+ * @param {{force?: boolean}} [options] - force:true regenerates a legacy-authored
+ *   file anyway, discarding the in-block content. Only ever set from an explicit
+ *   `--force-claude-md`, never by default: without an escape hatch a file that
+ *   trips the guard could never be migrated by the tool at all.
+ * @returns {{path, changed, layout, guarded?, seeded?, migrated?, skipped?}}
+ */
+export function generateProjectClaudeMd(cwd, detection, templatesDir, { force = false } = {}) {
+  const path = join(cwd, 'CLAUDE.md');
+  const existing = existsSync(path) ? readFileSync(path, 'utf8') : null;
+  const layout = classifyProjectClaudeMd(existing);
+
+  // Guard BEFORE any write. A warning printed after the fact would be worthless:
+  // the content it warns about would already be gone.
+  if (layout === 'legacy-authored' && !force) {
+    return {
+      path,
+      changed: false,
+      layout,
+      guarded: true,
+      skipped: 'hand-written content sits inside the managed block — regenerating would erase it',
+    };
+  }
+
+  const inner = templateInnerBlock(join(templatesDir, 'CLAUDE.md.project.tmpl'));
 
   const mcpRules = detection.mcpServers.length
     ? detection.mcpServers.map((s) => `- \`${s.name}\` (${s.scope}, ${s.classification}) — see token-efficiency skill for the matching rule.`).join('\n')
@@ -96,21 +222,29 @@ export function generateProjectClaudeMd(cwd, detection, templatesDir) {
 
   const filled = fillTemplate(inner, {
     PROJECT_NAME: detection.stack.name || '<!-- fill in: project name -->',
-    ONE_LINE_WHAT_THIS_IS: '<!-- fill in: one sentence, what this project is -->',
     BUILD_CMD: detection.stack.buildCmd || '# no build script detected — fill in or delete this line',
     TEST_CMD: detection.stack.testCmd || '# no test script detected — fill in or delete this line',
     LINT_CMD: detection.stack.lintCmd || '# no lint script detected — fill in or delete this line',
     RUN_NOTES: detection.stack.monorepo ? '<!-- monorepo detected — note which package/workspace to run commands from -->' : '',
     MCP_RULES: mcpRules,
-    ARCHITECTURE_BULLETS: '<!-- fill in: 3-6 lines, module -> responsibility -->',
-    CONVENTIONS: '<!-- fill in: only rules that bite -->',
   });
 
-  const path = join(cwd, 'CLAUDE.md');
-  const existing = existsSync(path) ? readFileSync(path, 'utf8') : null;
-  const { content, changed } = upsertManagedBlock(existing, filled);
-  if (changed) writeFileSync(path, content);
-  return { path, changed };
+  const { content } = upsertManagedBlock(existing, filled);
+
+  // Seed exactly when the authored sections have nowhere else to live: a brand
+  // new file, or an old one whose never-filled sections vanish with the block
+  // they sat in — and, either way, only when the file does not already have an
+  // authored half of its own below the marker. Never on a `current` file: the
+  // user may have deleted those headings on purpose, and re-adding them would be
+  // its own kind of clobber.
+  const seeded =
+    (layout === 'absent' || layout === 'legacy-empty' || (force && layout === 'legacy-authored')) &&
+    !hasAuthoredSectionsOutsideBlock(content);
+  const next = seeded ? insertAuthoredSeed(content, readAuthoredTemplate(templatesDir)) : content;
+
+  const changed = existing === null || next !== existing;
+  if (changed) writeFileSync(path, next);
+  return { path, changed, layout, seeded, migrated: layout === 'legacy-empty' };
 }
 
 export function generateUserClaudeMd(claudeDir, templatesDir) {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bglocation/tune-context",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Context-efficiency configurator for Claude Code \u2014 token-saving doctrine packaged as skills, plus a tune-context configurator that scaffolds a lean CLAUDE.md, doctrine skills, subagents, settings, hooks and MCP wiring.",
   "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.
 -->