@bglocation/tune-context 2.1.0 → 2.3.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.3.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.3.0",
   "author": {
     "name": "Szymon Walczak",
     "url": "https://bglocation.dev"

package/CHANGELOG.md

@@ -5,6 +5,105 @@ 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.3.0] — 2026-07-28
+
+### Added
+
+- **The adoption report can now tell "RAG installed and ignored" from "no RAG
+  here"** — the blind spot 2.0.0 accepted on purpose, and the finding the report
+  most wants to surface. A new `~ RAG likely available, not reached for` line
+  appears when a project's `.mcp.json` declares a semantic-search MCP server, no
+  settings file rejects it, and that file is **older than every session logged in
+  that project**. It is never a ✗: config lists servers, not their tools, so the
+  claim is "probably within reach", not "it existed". Four guards keep it from
+  fabricating one — rejected servers (`disabledMcpjsonServers`) don't count, a
+  config file touched during or after the sessions drops back to unknown,
+  observation always wins (a project that actually called `search_codebase` is
+  never judged from config), and the frozen session floor now applies **per
+  project** as well as globally, because the claim is per project: a busy log can
+  still contain a project with a single session, and absence over one session is
+  not absence. User-scope servers stay unknown by design: `~/.claude.json` is
+  rewritten by Claude Code continuously, so its timestamp can't date anything
+  (TASK-083).
+
+### Fixed
+
+- **One RAG-using project no longer counts as coverage for all the others.**
+  Search was tallied globally while the verdict spoke about "these sessions", so
+  a single project with RAG lifted the counter above zero and every other project
+  read as covered. Search is now counted per project as well, which is what
+  TASK-070 specified and never landed — visible in the report as an availability
+  verdict decided project by project.
+
+- **A malformed log line can no longer take the whole report down.** `parseLog`
+  validates only `lever`, so `cwd` could be any JSON value — and the new probe
+  joins it into a filesystem path. Non-string `cwd`s are now ignored as projects
+  while still counting toward the global figures.
+
+### Documentation
+
+- **The README said the `/tune-context` skill needs the plugin. It doesn't.**
+  `tune-context init` installs the skill into `~/.claude/skills/` along with the
+  doctrine skills, so a plain `npm i -g` gives you both entry points (and the
+  plugin gives you both too, by putting `bin/tune-context` on `PATH`). Adds a
+  skill-vs-CLI comparison covering what a reader asks first — session, tokens,
+  repeatability — not just the two steps the CLI omits.
+
+- **`--force-claude-md` is documented outside `--help` for the first time.** It is
+  the one flag that discards content the tool otherwise refuses to touch, so it
+  should be the best-documented flag rather than the least.
+
+## [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 +428,11 @@ action needed on upgrade.
   (`explore-cheap`, `reviewer`), the PreCompact / SessionStart / PostToolUse hook
   suite, and the adoption report (`eval/adoption-report.mjs`).
 
+[2.3.0]: https://gitlab.com/bglocation/tune-context/-/tags/v2.3.0
+[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
@@ -46,8 +61,11 @@ npm install -g @bglocation/tune-context
 tune-context init            # in any repo
 ```
 
-Prefer the model-driven path? Install the plugin and use the skill — it does the
-same thing plus wiki wiring and richer MCP detection:
+The command above also installs the **`/tune-context` skill** into
+`~/.claude/skills/`, so you can type it in a Claude session straight away — it does
+the same thing plus wiki wiring and richer MCP detection. Installing the plugin
+instead gets you the skill without the npm install, and updates through
+`/plugin marketplace update`:
 
 ```text
 /plugin marketplace add https://gitlab.com/bglocation/tune-context.git
@@ -64,11 +82,19 @@ The section below breaks down all three entry points and when to use each.
 
 Three entry points, same doctrine. Pick whichever fits how you work:
 
-**1. `/tune-context` skill (recommended).** With the plugin installed (below), run
-`/tune-context` in any repo. It detects the stack, MCP servers and existing config,
-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).
+**1. `/tune-context` skill (recommended).** Type `/tune-context` in a Claude Code
+session, in the repo you want to configure. It detects the stack, MCP servers and
+existing config, 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).
+
+**Either channel gives you the skill.** The plugin installs it, and so does
+`tune-context init` — the CLI copies `skills/tune-context/` into
+`~/.claude/skills/` along with the doctrine skills. So a plain `npm i -g` gives you
+*both* entry points, and so does the plugin (it puts `bin/tune-context` on `PATH`
+while enabled). Claude never reaches for it on its own: the skill is marked
+`disable-model-invocation`, so it runs only when you type it.
 
 **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
@@ -84,15 +110,38 @@ 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:
+Two flags are worth knowing:
 
-| Step | Skill | CLI |
+- **`--cwd <dir>`** — configure another repo instead of the current directory.
+- **`--force-claude-md`** — *destructive, opt-in, and normally unnecessary.* If a
+  `CLAUDE.md` still has hand-written content **inside** the managed block (the
+  layout used before 2.2.0), `init` refuses to regenerate it and says so —
+  "hand-written content sits inside the managed block — regenerating would erase
+  it". The fix is to move that prose below the closing marker, where the tool
+  never reaches. This flag regenerates anyway and **discards** it; use it only
+  when there is nothing in there worth keeping.
+
+### `/tune-context` vs `tune-context init`
+
+They are two different kinds of thing. The skill is a **procedure Claude follows**,
+so it can look at your repo and decide; the CLI is **code that runs**, so it does
+exactly what it was written to do, every time. Same doctrine, same managed-block
+rules, same never-clobber guarantee.
+
+| | `/tune-context` (skill) | `tune-context init` (CLI) |
 |---|---|---|
+| Where you run it | Claude Code chat | terminal, incl. CI |
+| Needs a Claude session | yes | no — plain Node ≥ 18 |
+| Costs tokens | yes | no |
+| Two runs, same repo | judgment may vary | byte-identical |
 | 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 |
 
+Both write the same block into the same files, so mixing them is safe: script the
+CLI where you want repeatability, and run the skill when you want the two judgment
+steps it alone can do.
+
 **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`:
@@ -197,12 +246,25 @@ override's `tune-context/adoption.jsonl` — see above), and `eval/adoption-repo
 turns that into a report — code search (semantic RAG vs the Grep tool, with
 shell-plumbing greps kept out of the RAG share), doctrine skills, subagents, and
 re-read churn — closing with an *earned* verdict: withheld below a PO-frozen floor of
-distinct sessions, and never a false ✗ for a lever the log can't see (RAG
-installed-but-unused vs not installed; method-level doctrine that leaves no tool call).
-It's registered under two Claude Code hook events —
+distinct sessions, and never a false ✗ for a lever the log can't see (method-level
+doctrine leaves no tool call at all). It's registered under two Claude Code hook events —
 `PostToolUse` (every tool call) and `SubagentStart` (subagent spawns, which aren't
 regular tools).
 
+**"RAG installed but ignored" vs "no RAG here"** is the one gap the log alone cannot
+close, and it happens to be the finding the report most wants — so it asks the config,
+per project, and only as far as the config can honestly answer. A
+`~ RAG likely available, not reached for` line appears when that project's `.mcp.json`
+declares a semantic-search server, no settings file rejects it, and the file is *older*
+than every session logged there. Everything else stays `·` unknown: config written
+during or after those sessions says nothing about them, and user-scope servers
+(`~/.claude.json`) can't be dated at all, since Claude Code rewrites that file
+continuously. It is never a ✗ — config names servers, not their tools, so the line
+claims the lever was probably within reach, not that it existed. It also answers to
+the same frozen session floor as the rest of the verdict, applied **per project**:
+"available and never reached for" is a claim about absence, and one logged session
+cannot establish absence.
+
 **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

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) {