feat(plugin): auto-refresh adopted decision table on version drift (v0.11.0)

v0.10.0 shipped the 7-core/5-hidden tool surface in the Rust binary but
left the adopted plugin_code_graph_mcp.md + MEMORY.md sentinel block
stuck at the v0.8.x/v0.9.x 12-tool content for already-adopted projects.
maybeAutoAdopt short-circuited on isAdopted() and never refreshed the
template. Also shipped the stale source template itself, and the
INDEX_LINE constant in adopt.js that drives the MEMORY.md sentinel.

Fixes:
- Source template `claude-plugin/templates/plugin_code_graph_mcp.md`
  synced to 7-core/5-hidden surface so fresh /plugin install + first
  adopt produces correct content.
- INDEX_LINE constant in adopt.js synced to v0.10.0 wording so the
  sentinel block in MEMORY.md matches the target file.
- New `needsRefresh()` helper: compares shipped template SHA vs target
  and checks MEMORY.md sentinel block content vs current INDEX_LINE.
- `maybeAutoAdopt()` now refreshes target + sentinel on drift unless
  CODE_GRAPH_NO_TEMPLATE_REFRESH=1 is set. Reason is 'refreshed'.
- `session-init.js` emits a one-line stderr notice on refresh.

Tests: 8 new cases in adopt.test.js cover drift detection, refresh path,
opt-out env var, and no-gratuitous-refresh when in sync. 37/37 adopt +
13/13 session-init + 335/335 cargo test green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sdsrss

.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "AST knowledge graph plugin for Claude Code — semantic search, call graph, HTTP tracing, impact analysis",
-    "version": "0.10.0"
+    "version": "0.11.0"
   },
   "plugins": [
     {
       "name": "code-graph-mcp",
       "source": "./claude-plugin",
       "description": "AST knowledge graph for intelligent code navigation — auto-indexes your codebase and provides semantic search, call graph traversal, HTTP route tracing, and impact analysis via MCP tools",
-      "version": "0.10.0",
+      "version": "0.11.0",
       "author": {
         "name": "sdsrs"
       },

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## v0.11.0 — auto-refresh stale decision table on plugin upgrade
+
+### Migration note
+
+v0.10.0 shipped the 7-core/5-hidden tool surface in the Rust binary **but left the adopted `plugin_code_graph_mcp.md` decision table file — and the `MEMORY.md` sentinel block — stuck at the v0.8.x/v0.9.x 12-tool content** for any project that had already auto-adopted. The plugin's `maybeAutoAdopt()` short-circuited on `isAdopted() == true` and never refreshed the template. Two related holes were also fixed:
+
+1. The shipped source template (`claude-plugin/templates/plugin_code_graph_mcp.md`) was not updated in v0.10.0 — **new** `/plugin install` + first-adopt users were also getting the stale 12-tool table.
+2. The `INDEX_LINE` constant in `adopt.js` (which drives the `MEMORY.md` sentinel block) was likewise still the v0.8.x 12-tool line.
+
+### What changes on upgrade
+
+- **Source template synced** to match the 7-core / 5-hidden surface. Fresh `/plugin install` gets the correct decision table on first adopt.
+- **`INDEX_LINE` synced** to the v0.10.0 wording.
+- **Auto-refresh on drift**: when a project is already adopted but the shipped template hash ≠ the project's copy (or the `MEMORY.md` sentinel block's content ≠ current `INDEX_LINE`), the next plugin SessionStart refreshes both silently. One-time stderr notice: `[code-graph] Refreshed decision table to latest shipped version.`
+- Hand-edited decision tables are overwritten by default. To lock: `CODE_GRAPH_NO_TEMPLATE_REFRESH=1` in `~/.claude/settings.json` env.
+
+### Opt-out
+
+- `CODE_GRAPH_NO_TEMPLATE_REFRESH=1` — preserves your local edits of `plugin_code_graph_mcp.md`; also pins `MEMORY.md` sentinel to whatever it was. Does not affect first-adopt (only the refresh path).
+- `CODE_GRAPH_NO_AUTO_ADOPT=1` — still gates the first-adopt path as in v0.9.0.
+- `code-graph-mcp unadopt` — unchanged; strips sentinel + deletes target file.
+
+### Why this matters
+
+Without this fix, an already-adopted v0.8.x/v0.9.x user who upgrades to v0.10.x gets mixed state: the Rust binary serves 7 tools in `tools/list` but the MEMORY.md index + decision-table file still instruct the LLM to route through the full 12-tool surface as if they were peers. Functionally nothing breaks (hidden tools remain callable by name), but the decision guidance is misaligned. v0.11.0 closes the loop so the three surfaces — binary, index pointer, decision table — all move together on upgrade.
+
 ## v0.10.0 — tools/list surface trimmed to 7 core tools
 
 ### Migration note

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "code-graph-mcp"
-version = "0.10.0"
+version = "0.11.0"
 edition = "2021"
 
 [features]

Cargo.toml

@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.10.0",
+  "version": "0.11.0",
   "keywords": [
     "code-graph",
     "ast",

claude-plugin/.claude-plugin/plugin.json

@@ -10,9 +10,9 @@ const os = require('os');
 const SENTINEL_BEGIN = '<!-- code-graph-mcp:begin v1 -->';
 const SENTINEL_END = '<!-- code-graph-mcp:end -->';
 const INDEX_LINE = [
-  '- [code-graph-mcp](plugin_code_graph_mcp.md) — 代码理解 12 工具（替代 Grep/Read 多步）：',
-  '  - 问"谁调/改动/模块/概念/HTTP/相似" → `get_call_graph`/`impact_analysis`/`module_overview`/`semantic_code_search`/`trace_http_chain`/`find_similar_code`',
-  '  - 问"返回型/引用/死码/依赖/架构/看签名" → `ast_search`/`find_references`/`find_dead_code`/`dependency_graph`/`project_map`/`get_ast_node`',
+  '- [code-graph-mcp](plugin_code_graph_mcp.md) — v0.10.0 起 tools/list 默认 7 核心 + 5 隐藏可调（省启动 token）',
+  '  - 核心 7（默认暴露）：`get_call_graph`/`module_overview`/`semantic_code_search`/`ast_search`/`find_references`/`get_ast_node`/`project_map`',
+  '  - 进阶 5（隐藏按名可调）：`impact_analysis`/`trace_http_chain`/`dependency_graph`/`find_similar_code`/`find_dead_code`',
 ].join('\n');
 const TEMPLATE_PATH = path.resolve(__dirname, '..', 'templates', 'plugin_code_graph_mcp.md');
 const TARGET_NAME = 'plugin_code_graph_mcp.md';
@@ -102,6 +102,26 @@ function isAdopted({ cwd, home } = {}) {
   return index.includes(SENTINEL_BEGIN) && index.includes(SENTINEL_END);
 }
 
+// v0.11.0 — shipped template / INDEX_LINE 与已落地版本出现漂移时返回 true。
+// 让已 adopt 的项目在下次 SessionStart 自动对齐到插件最新决策表，避免"老用户
+// 永远停留在首次 adopt 时的 snapshot"。手动编辑会被覆盖——锁定方式：
+// CODE_GRAPH_NO_TEMPLATE_REFRESH=1。
+function needsRefresh({ cwd, home, templatePath } = {}) {
+  const dir = memoryDir(cwd, home);
+  const target = path.join(dir, TARGET_NAME);
+  const indexPath = path.join(dir, 'MEMORY.md');
+  const tpl = templatePath || TEMPLATE_PATH;
+  if (!fs.existsSync(target) || !fs.existsSync(tpl) || !fs.existsSync(indexPath)) {
+    return false;
+  }
+  const shipped = fs.readFileSync(tpl);
+  const current = fs.readFileSync(target);
+  if (!shipped.equals(current)) return true;
+  const index = fs.readFileSync(indexPath, 'utf8');
+  const desiredBlock = `${SENTINEL_BEGIN}\n${INDEX_LINE}\n${SENTINEL_END}`;
+  return !index.includes(desiredBlock);
+}
+
 // 检测脚本是否从 Claude Code 插件 cache 运行。
 // 走 __dirname 而非 CLAUDE_PLUGIN_ROOT — 后者在多插件共存时会互相污染
 // （见 feedback_plugin_env_isolation.md）。
@@ -122,6 +142,12 @@ function maybeAutoAdopt({ cwd, home, env, scriptPath } = {}) {
     return { attempted: false, reason: 'not-plugin-mode' };
   }
   if (isAdopted({ cwd, home })) {
+    // v0.11.0: shipped template / INDEX_LINE 漂移时重跑 adopt 对齐。
+    // opt-out: CODE_GRAPH_NO_TEMPLATE_REFRESH=1（锁定手动编辑）。
+    if (env.CODE_GRAPH_NO_TEMPLATE_REFRESH !== '1' && needsRefresh({ cwd, home })) {
+      const result = adopt({ cwd, home });
+      return { attempted: true, reason: 'refreshed', result };
+    }
     return { attempted: false, reason: 'already-adopted' };
   }
   const result = adopt({ cwd, home });
@@ -197,6 +223,6 @@ if (require.main === module) {
 
 module.exports = {
   adopt, unadopt, memoryDir, formatResult, stripSentinelBlock,
-  isAdopted, isPluginModeInstall, maybeAutoAdopt,
+  isAdopted, isPluginModeInstall, maybeAutoAdopt, needsRefresh,
   SENTINEL_BEGIN, SENTINEL_END, INDEX_LINE, TEMPLATE_PATH, TARGET_NAME,
 };

claude-plugin/scripts/adopt.js

@@ -6,8 +6,8 @@ const path = require('path');
 const os = require('os');
 const {
   adopt, unadopt, memoryDir, stripSentinelBlock,
-  isAdopted, isPluginModeInstall, maybeAutoAdopt,
-  SENTINEL_BEGIN, SENTINEL_END, INDEX_LINE, TEMPLATE_PATH,
+  isAdopted, isPluginModeInstall, maybeAutoAdopt, needsRefresh,
+  SENTINEL_BEGIN, SENTINEL_END, INDEX_LINE, TEMPLATE_PATH, TARGET_NAME,
 } = require('./adopt');
 
 function makeSandbox() {
@@ -348,6 +348,123 @@ test('maybeAutoAdopt returns no-memory-dir when project memory missing', () => {
   }
 });
 
+// v0.11.0 — template-refresh on drift
+
+test('needsRefresh returns false when target matches shipped template + INDEX_LINE', () => {
+  const sb = makeSandbox();
+  try {
+    adopt({ cwd: sb.cwd, home: sb.home });
+    assert.strictEqual(needsRefresh({ cwd: sb.cwd, home: sb.home }), false);
+  } finally { sb.cleanup(); }
+});
+
+test('needsRefresh returns true when target content drifted from shipped template', () => {
+  const sb = makeSandbox();
+  try {
+    adopt({ cwd: sb.cwd, home: sb.home });
+    const target = path.join(sb.dir, TARGET_NAME);
+    fs.writeFileSync(target, '# stale content from earlier plugin version\n');
+    assert.strictEqual(needsRefresh({ cwd: sb.cwd, home: sb.home }), true);
+  } finally { sb.cleanup(); }
+});
+
+test('needsRefresh returns true when MEMORY.md INDEX_LINE drifted', () => {
+  const sb = makeSandbox();
+  try {
+    adopt({ cwd: sb.cwd, home: sb.home });
+    const indexPath = path.join(sb.dir, 'MEMORY.md');
+    const stale = `# Memory Index\n\n${SENTINEL_BEGIN}\n- old 12-tool index line\n${SENTINEL_END}\n`;
+    fs.writeFileSync(indexPath, stale);
+    assert.strictEqual(needsRefresh({ cwd: sb.cwd, home: sb.home }), true);
+  } finally { sb.cleanup(); }
+});
+
+test('needsRefresh returns false when not adopted (nothing to refresh)', () => {
+  const sb = makeSandbox();
+  try {
+    assert.strictEqual(needsRefresh({ cwd: sb.cwd, home: sb.home }), false);
+  } finally { sb.cleanup(); }
+});
+
+test('maybeAutoAdopt refreshes drifted target on re-run (reason=refreshed)', () => {
+  const sb = makeSandbox();
+  try {
+    adopt({ cwd: sb.cwd, home: sb.home });
+    const target = path.join(sb.dir, TARGET_NAME);
+    fs.writeFileSync(target, '# stale\n');
+    const res = maybeAutoAdopt({
+      cwd: sb.cwd, home: sb.home,
+      scriptPath: '/home/u/.claude/plugins/cache/code-graph-mcp/scripts',
+      env: {},
+    });
+    assert.strictEqual(res.attempted, true);
+    assert.strictEqual(res.reason, 'refreshed');
+    assert.strictEqual(res.result.ok, true);
+    // Target now matches shipped template
+    const shipped = fs.readFileSync(TEMPLATE_PATH);
+    const current = fs.readFileSync(target);
+    assert.ok(shipped.equals(current), 'target re-synced to shipped template');
+    // Sentinel preserved in MEMORY.md
+    assert.strictEqual(isAdopted({ cwd: sb.cwd, home: sb.home }), true);
+  } finally { sb.cleanup(); }
+});
+
+test('maybeAutoAdopt refreshes drifted INDEX_LINE in MEMORY.md', () => {
+  const sb = makeSandbox();
+  try {
+    adopt({ cwd: sb.cwd, home: sb.home });
+    const indexPath = path.join(sb.dir, 'MEMORY.md');
+    const stale = `# Memory Index\n\n${SENTINEL_BEGIN}\n- old 12-tool index line\n${SENTINEL_END}\n`;
+    fs.writeFileSync(indexPath, stale);
+    const res = maybeAutoAdopt({
+      cwd: sb.cwd, home: sb.home,
+      scriptPath: '/home/u/.claude/plugins/cache/code-graph-mcp/scripts',
+      env: {},
+    });
+    assert.strictEqual(res.attempted, true);
+    assert.strictEqual(res.reason, 'refreshed');
+    const index = fs.readFileSync(indexPath, 'utf8');
+    assert.ok(index.includes(INDEX_LINE), 'INDEX_LINE restored from current constant');
+    assert.ok(!index.includes('old 12-tool index line'), 'stale line removed');
+  } finally { sb.cleanup(); }
+});
+
+test('maybeAutoAdopt skips refresh when CODE_GRAPH_NO_TEMPLATE_REFRESH=1 (locks manual edits)', () => {
+  const sb = makeSandbox();
+  try {
+    adopt({ cwd: sb.cwd, home: sb.home });
+    const target = path.join(sb.dir, TARGET_NAME);
+    const userEdit = '# my hand-edited decision table\n';
+    fs.writeFileSync(target, userEdit);
+    const res = maybeAutoAdopt({
+      cwd: sb.cwd, home: sb.home,
+      scriptPath: '/home/u/.claude/plugins/cache/code-graph-mcp/scripts',
+      env: { CODE_GRAPH_NO_TEMPLATE_REFRESH: '1' },
+    });
+    assert.strictEqual(res.attempted, false);
+    assert.strictEqual(res.reason, 'already-adopted');
+    assert.strictEqual(fs.readFileSync(target, 'utf8'), userEdit, 'user edit preserved');
+  } finally { sb.cleanup(); }
+});
+
+test('maybeAutoAdopt stays already-adopted when in sync (no gratuitous refresh)', () => {
+  const sb = makeSandbox();
+  try {
+    adopt({ cwd: sb.cwd, home: sb.home });
+    const target = path.join(sb.dir, TARGET_NAME);
+    const mtimeBefore = fs.statSync(target).mtimeMs;
+    const res = maybeAutoAdopt({
+      cwd: sb.cwd, home: sb.home,
+      scriptPath: '/home/u/.claude/plugins/cache/code-graph-mcp/scripts',
+      env: {},
+    });
+    assert.strictEqual(res.attempted, false);
+    assert.strictEqual(res.reason, 'already-adopted');
+    const mtimeAfter = fs.statSync(target).mtimeMs;
+    assert.strictEqual(mtimeAfter, mtimeBefore, 'target file not touched when in sync');
+  } finally { sb.cleanup(); }
+});
+
 test('Windows platform is rejected with clear reason', { skip: process.platform === 'win32' }, () => {
   const orig = process.platform;
   Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });

claude-plugin/scripts/adopt.test.js

@@ -259,14 +259,22 @@ function runSessionInit() {
   const indexFreshness = binaryCheck.available ? ensureIndexFresh() : 'skipped';
 
   // v0.9.0 C' 上下文感知默认：插件模式下首次 SessionStart 自动 adopt。
-  // 仅一次 stderr 提示（采纳成功时），让用户知道发生了什么 + 如何回退。
+  // v0.11.0: 已 adopt 的项目如果 shipped template 漂移也会触发一次刷新。
+  // 两种情况都发一次 stderr 提示，让用户知道发生了什么 + 如何回退。
   const autoAdopt = maybeAutoAdopt({ scriptPath: __dirname });
   if (autoAdopt.attempted && autoAdopt.result && autoAdopt.result.ok) {
-    process.stderr.write(
-      '[code-graph] Auto-adopted into project MEMORY.md (plugin install → knowing consent).\n' +
-      '            Opt out:    CODE_GRAPH_NO_AUTO_ADOPT=1 in ~/.claude/settings.json env\n' +
-      '            Reverse:    code-graph-mcp unadopt\n'
-    );
+    if (autoAdopt.reason === 'refreshed') {
+      process.stderr.write(
+        '[code-graph] Refreshed decision table to latest shipped version.\n' +
+        '            Lock file:  CODE_GRAPH_NO_TEMPLATE_REFRESH=1 in ~/.claude/settings.json env\n'
+      );
+    } else {
+      process.stderr.write(
+        '[code-graph] Auto-adopted into project MEMORY.md (plugin install → knowing consent).\n' +
+        '            Opt out:    CODE_GRAPH_NO_AUTO_ADOPT=1 in ~/.claude/settings.json env\n' +
+        '            Reverse:    code-graph-mcp unadopt\n'
+      );
+    }
   }
 
   // quietHooks: adopted → quiet by default (rely on MEMORY.md pointer + on-demand

claude-plugin/scripts/session-init.js

@@ -11,23 +11,38 @@ type: reference
 > 本文件自动写入，自动切换 quietHooks（跳过每次 project_map 注入）。
 > 退出：`CODE_GRAPH_NO_AUTO_ADOPT=1` 阻止，`code-graph-mcp unadopt` 回退。
 > 手动强控：`CODE_GRAPH_QUIET_HOOKS=0` 强制注入 / `=1` 强制静默（覆盖 adoption 推导）。
+>
+> **v0.11.0 起**：已 adopt 的项目在下次 SessionStart 会自动对齐到插件 shipped
+> 的最新决策表（本文件 SHA 与 template 差异时覆盖）。手动编辑会被覆盖——
+> 要锁定自己的版本，设 `CODE_GRAPH_NO_TEMPLATE_REFRESH=1`（不影响首次 adopt）。
 
 ## 何时调用 MCP/CLI（替代多步 Grep/Read）
 
+> v0.10.0 起：tools/list 默认只暴露 7 个核心工具；下表中 `⚙` 标记的 5 个工具
+> 已从 tools/list 隐藏以节省 session 启动 tokens，但**仍可通过名称直接调用**
+> （向后兼容别名）或用 CLI 子命令。高频场景可优先用核心 7 个。
+
+### 核心 7（tools/list 默认暴露）
+
 | 意图 | 工具 | 关键参数 / 例子 |
 |------|------|----------------|
 | "谁调用 X？" / "X 调了啥？" | `get_call_graph` / `callgraph X` | 替代 `grep "X("` |
-| "改 X 会炸啥？" | `impact_analysis` / `impact X` | 修改函数签名前必跑 |
 | "Y 模块长啥样？" | `module_overview` / `overview Y/` | 替代逐文件 Read |
 | "找做 Z 的代码"（概念） | `semantic_code_search` / `search "Z"` | 不知道精确名 |
 | "返回 T 类型的函数" | `ast_search --returns T` | 结构化筛选 |
 | "X 在哪被引用？" | `find_references` / `refs X` | 含 callers/importers |
-| "未使用的代码" | `find_dead_code` / `dead-code [path]` | 清理 exports |
-| "相似/重复函数" | `find_similar_code` / `similar X` | 需 embedding |
-| "X 文件依赖谁？" | `dependency_graph` / `deps X` | file 级别 |
-| "看 X 的源码 / 签名" | `get_ast_node` / `show X` | `--include-impact` 含影响面 |
+| "看 X 的源码 / 签名" | `get_ast_node` / `show X` | `include_impact=true` 含影响面（替代 impact_analysis） |
 | "项目结构总览" | `project_map` / `map` | 起手势用 `--compact` |
-| HTTP 路由 → handler 链路 | `trace_http_chain` / `trace ROUTE` | API 调试 |
+
+### 进阶 5（隐藏但可调）
+
+| 意图 | 工具 | 关键参数 / 例子 |
+|------|------|----------------|
+| ⚙ "改 X 会炸啥？" | `impact_analysis` / `impact X` | 修改签名前用；或 `get_ast_node` + `include_impact=true` |
+| ⚙ HTTP 路由 → handler 链路 | `trace_http_chain` / `trace ROUTE` | API 调试 |
+| ⚙ "X 文件依赖谁？" | `dependency_graph` / `deps X` | file 级别 |
+| ⚙ "相似/重复函数" | `find_similar_code` / `similar X` | 需 embedding |
+| ⚙ "未使用的代码" | `find_dead_code` / `dead-code [path]` | 清理 exports |
 
 ## 不要替代
 
@@ -40,7 +55,8 @@ type: reference
 1. 起手 `project_map --compact` 看架构
 2. `semantic_code_search` 默认带 `compact=true`，省 token
 3. 展开节点：`get_ast_node node_id=N compact=true` 看签名 / 不带 compact 看全文
-4. 改前必跑 `impact_analysis`
+4. 改前评估影响：`get_ast_node symbol_name=X include_impact=true`（核心 7 内）
+   或直接 `impact_analysis symbol_name=X`（隐藏但可调，输出更细：风险等级 + 路由 + 文件计数）
 5. 搜不到结果 → `code-graph-mcp health-check` 检查索引与 embedding 覆盖率
 
 可用 prompts：`impact-analysis`、`understand-module`、`trace-request`
@@ -73,4 +89,5 @@ code-graph-mcp health-check              # 索引健康
 
 - `code-graph-mcp unadopt` — 精确移除 sentinel 段 + 本文件，quietHooks 自动回到 false（下次 SessionStart 恢复 project_map 注入）。
 - `CODE_GRAPH_NO_AUTO_ADOPT=1`（`~/.claude/settings.json` env） — 阻止未来自动 adopt，不影响已 adopted 状态。
+- `CODE_GRAPH_NO_TEMPLATE_REFRESH=1`（v0.11.0+） — 锁定本文件不随插件升级刷新；允许手动编辑长久保留。
 - `CODE_GRAPH_QUIET_HOOKS=0` — 强制恢复 project_map 注入（即使已 adopted）。

claude-plugin/templates/plugin_code_graph_mcp.md

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph-darwin-arm64",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "code-graph-mcp binary for macOS ARM64",
   "license": "MIT",
   "repository": {