devlog-tracker 0.25.1 → 0.29.2

package/cli/platforms/claude.test.js

@@ -0,0 +1,178 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { install } = require('./claude');
+
+function tmpdir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'devlog-tracker-claude-'));
+}
+
+function makeFakeRepo(dir) {
+  fs.mkdirSync(path.join(dir, 'claude'), { recursive: true });
+  fs.writeFileSync(
+    path.join(dir, 'claude', 'hooks.json'),
+    JSON.stringify({ hooks: { Stop: [{ hooks: [{ type: 'command', command: 'bash "${DEVLOG_TRACKER_ROOT}/core/scripts/enforce-devlog.sh"' }] }] } }, null, 2)
+  );
+  fs.mkdirSync(path.join(dir, 'commands'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'commands', 'start.md'), '---\ndescription: 啟動追蹤\n---\n\n步驟一。\n');
+}
+
+function makeVendorRoot(dir) {
+  // Real vendorRoot is targetDir/.devlog-tracker, which contains the marker in its path
+  const vendorRoot = path.join(dir, '.devlog-tracker');
+  fs.mkdirSync(path.join(vendorRoot, 'commands'), { recursive: true });
+  fs.writeFileSync(path.join(vendorRoot, 'commands', 'start.md'), '---\ndescription: 啟動追蹤\n---\n\n步驟一。\n');
+  return vendorRoot;
+}
+
+test('install merges hooks into .claude/settings.local.json without touching other keys', () => {
+  const repoRoot = tmpdir();
+  const vendorParent = tmpdir();
+  const targetDir = tmpdir();
+  const vendorRoot = makeVendorRoot(vendorParent);
+  makeFakeRepo(repoRoot);
+  fs.mkdirSync(path.join(targetDir, '.claude'), { recursive: true });
+  fs.writeFileSync(
+    path.join(targetDir, '.claude', 'settings.local.json'),
+    JSON.stringify({ permissions: { allow: ['Bash(ls:*)'] } }, null, 2)
+  );
+
+  install({ repoRoot, targetDir, vendorRoot });
+
+  const settings = JSON.parse(fs.readFileSync(path.join(targetDir, '.claude', 'settings.local.json'), 'utf8'));
+  assert.deepEqual(settings.permissions, { allow: ['Bash(ls:*)'] });
+  assert.equal(settings.hooks.Stop[0].hooks[0].command, `bash "${vendorRoot}/core/scripts/enforce-devlog.sh"`);
+});
+
+test('install writes .claude/skills/devlog-<name>/SKILL.md from vendored commands', () => {
+  const repoRoot = tmpdir();
+  const vendorParent = tmpdir();
+  const targetDir = tmpdir();
+  const vendorRoot = makeVendorRoot(vendorParent);
+  makeFakeRepo(repoRoot);
+
+  install({ repoRoot, targetDir, vendorRoot });
+
+  const skillPath = path.join(targetDir, '.claude', 'skills', 'devlog-start', 'SKILL.md');
+  assert.ok(fs.existsSync(skillPath));
+  assert.match(fs.readFileSync(skillPath, 'utf8'), /步驟一。/);
+});
+
+test('install upserts the devlog-tracker block into CLAUDE.md, leaving other content alone', () => {
+  const repoRoot = tmpdir();
+  const vendorParent = tmpdir();
+  const targetDir = tmpdir();
+  const vendorRoot = makeVendorRoot(vendorParent);
+  makeFakeRepo(repoRoot);
+  fs.writeFileSync(path.join(targetDir, 'CLAUDE.md'), '# My project\n\nSome existing notes.\n');
+
+  install({ repoRoot, targetDir, vendorRoot });
+
+  const content = fs.readFileSync(path.join(targetDir, 'CLAUDE.md'), 'utf8');
+  assert.match(content, /# My project/);
+  assert.match(content, /Some existing notes\./);
+  assert.match(content, /<!-- devlog-tracker:begin -->/);
+  assert.match(content, /<!-- devlog-tracker:end -->/);
+  assert.match(content, /devlog-tracker/);
+});
+
+test('re-running install is idempotent: no duplicate hook entries or skill directories', () => {
+  const repoRoot = tmpdir();
+  const vendorParent = tmpdir();
+  const targetDir = tmpdir();
+  const vendorRoot = makeVendorRoot(vendorParent);
+  makeFakeRepo(repoRoot);
+
+  install({ repoRoot, targetDir, vendorRoot });
+  const skillsAfterFirst = fs.readdirSync(path.join(targetDir, '.claude', 'skills'));
+  install({ repoRoot, targetDir, vendorRoot });
+  const skillsAfterSecond = fs.readdirSync(path.join(targetDir, '.claude', 'skills'));
+
+  const settings = JSON.parse(fs.readFileSync(path.join(targetDir, '.claude', 'settings.local.json'), 'utf8'));
+  assert.equal(settings.hooks.Stop.length, 1);
+  assert.deepEqual(skillsAfterFirst, skillsAfterSecond, 'skill directories should not duplicate');
+});
+
+test('re-running install twice on existing CLAUDE.md keeps exactly one marker pair', () => {
+  const repoRoot = tmpdir();
+  const vendorParent = tmpdir();
+  const targetDir = tmpdir();
+  const vendorRoot = makeVendorRoot(vendorParent);
+  makeFakeRepo(repoRoot);
+  fs.writeFileSync(path.join(targetDir, 'CLAUDE.md'), '# My project\n\nSome existing notes.\n');
+
+  install({ repoRoot, targetDir, vendorRoot });
+  install({ repoRoot, targetDir, vendorRoot });
+
+  const content = fs.readFileSync(path.join(targetDir, 'CLAUDE.md'), 'utf8');
+  const beginCount = (content.match(/<!-- devlog-tracker:begin -->/g) || []).length;
+  const endCount = (content.match(/<!-- devlog-tracker:end -->/g) || []).length;
+  assert.equal(beginCount, 1, 'Should have exactly one begin marker');
+  assert.equal(endCount, 1, 'Should have exactly one end marker');
+  assert.match(content, /# My project/);
+  assert.match(content, /Some existing notes\./);
+});
+
+test('install with real claude/hooks.json substitutes all placeholders and is idempotent', () => {
+  const repoRoot = path.join(__dirname, '..', '..');
+  const vendorParent = tmpdir();
+  const targetDir = tmpdir();
+  const vendorRoot = makeVendorRoot(vendorParent);
+
+  // First run
+  install({ repoRoot, targetDir, vendorRoot });
+
+  const settingsPath = path.join(targetDir, '.claude', 'settings.local.json');
+  const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+
+  // Collect all commands from the merged hooks
+  const commands = [];
+  for (const event of Object.keys(settings.hooks)) {
+    const entries = settings.hooks[event];
+    for (const entry of entries) {
+      if (entry.hooks) {
+        for (const hook of entry.hooks) {
+          if (hook.command) {
+            commands.push(hook.command);
+          }
+        }
+      }
+    }
+  }
+
+  // Verify no unsubstituted placeholders remain
+  for (const command of commands) {
+    assert.ok(!command.includes('${'), `Command should not contain unsubstituted placeholder: ${command}`);
+  }
+
+  // Verify every command contains the vendorRoot and /core/scripts/
+  for (const command of commands) {
+    assert.ok(command.includes(vendorRoot), `Command should contain vendorRoot path: ${command}`);
+    assert.ok(command.includes('/core/scripts/'), `Command should reference core/scripts: ${command}`);
+  }
+
+  // Now read the template to count expected entries per event
+  const templatePath = path.join(repoRoot, 'claude', 'hooks.json');
+  const template = JSON.parse(fs.readFileSync(templatePath, 'utf8'));
+
+  // Before second run, get the current entry counts
+  const entriesBeforeSecond = {};
+  for (const event of Object.keys(template.hooks)) {
+    entriesBeforeSecond[event] = settings.hooks[event] ? settings.hooks[event].length : 0;
+  }
+
+  // Second run
+  install({ repoRoot, targetDir, vendorRoot });
+
+  const settingsAfterSecond = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+
+  // Verify no duplication: each event should have same count as template (1 entry each)
+  for (const event of Object.keys(template.hooks)) {
+    const expectedCount = template.hooks[event].length;
+    const actualCount = settingsAfterSecond.hooks[event] ? settingsAfterSecond.hooks[event].length : 0;
+    assert.equal(actualCount, expectedCount, `Event ${event} should have ${expectedCount} entry (template count), got ${actualCount}`);
+  }
+});

package/cli/platforms/codex.js

@@ -3,15 +3,10 @@ const fs = require('fs');
 const path = require('path');
 const { mergeHooksTemplate } = require('../merge-hooks');
 const { upsertAgentsMd } = require('../agents-md');
+const { generateSkillsFromCommands } = require('../skills-from-commands');
 
 // Codex 只從 ~/.codex/prompts/ 讀 custom prompts（且已棄用），不會讀專案內的
 // .codex/prompts/；專案層級的指令要做成 .agents/skills/<name>/SKILL.md，以 $<name> 叫用。
-function parseCommand(text) {
-  const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(text);
-  if (!match) return { description: '', body: text };
-  const description = /^description:\s*(.*)$/m.exec(match[1]);
-  return { description: description ? description[1].trim() : '', body: match[2] };
-}
 
 // 0.25.0 曾把 prompts 寫到 .codex/prompts/devlog-*.md，Codex 讀不到；升級時清掉。
 function removeLegacyPrompts(targetDir) {
@@ -24,18 +19,11 @@ function removeLegacyPrompts(targetDir) {
 }
 
 function installSkills({ targetDir, vendorRoot }) {
-  const commandsDir = path.join(vendorRoot, 'commands');
-  for (const file of fs.readdirSync(commandsDir)) {
-    if (!file.endsWith('.md')) continue;
-    const name = `devlog-${path.basename(file, '.md')}`;
-    const { description, body } = parseCommand(fs.readFileSync(path.join(commandsDir, file), 'utf8'));
-    const skillDir = path.join(targetDir, '.agents', 'skills', name);
-    fs.mkdirSync(skillDir, { recursive: true });
-    fs.writeFileSync(
-      path.join(skillDir, 'SKILL.md'),
-      `---\nname: ${name}\ndescription: ${JSON.stringify(description)}\n---\n\n${body.trim()}\n\n使用者提供的額外參數：請看觸發這個 skill 的使用者訊息。\n`
-    );
-  }
+  generateSkillsFromCommands({
+    commandsDir: path.join(vendorRoot, 'commands'),
+    targetSkillsDir: path.join(targetDir, '.agents', 'skills'),
+    namePrefix: 'devlog',
+  });
   removeLegacyPrompts(targetDir);
 }
 

package/cli/skills-from-commands.js

@@ -0,0 +1,32 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+function parseCommand(text) {
+  const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(text);
+  if (!match) return { description: '', body: text };
+  const description = /^description:\s*(.*)$/m.exec(match[1]);
+  return { description: description ? description[1].trim() : '', body: match[2] };
+}
+
+// 把 commandsDir 底下每個 *.md 轉成 targetSkillsDir/<namePrefix>-<檔名>/SKILL.md。
+// 回傳寫入的 SKILL.md 絕對路徑陣列。
+function generateSkillsFromCommands({ commandsDir, targetSkillsDir, namePrefix }) {
+  const written = [];
+  for (const file of fs.readdirSync(commandsDir)) {
+    if (!file.endsWith('.md')) continue;
+    const name = `${namePrefix}-${path.basename(file, '.md')}`;
+    const { description, body } = parseCommand(fs.readFileSync(path.join(commandsDir, file), 'utf8'));
+    const skillDir = path.join(targetSkillsDir, name);
+    fs.mkdirSync(skillDir, { recursive: true });
+    const skillPath = path.join(skillDir, 'SKILL.md');
+    fs.writeFileSync(
+      skillPath,
+      `---\nname: ${name}\ndescription: ${JSON.stringify(description)}\n---\n\n${body.trim()}\n\n使用者提供的額外參數：請看觸發這個 skill 的使用者訊息。\n`
+    );
+    written.push(skillPath);
+  }
+  return written;
+}
+
+module.exports = { generateSkillsFromCommands, parseCommand };

package/cli/skills-from-commands.test.js

@@ -0,0 +1,51 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { generateSkillsFromCommands } = require('./skills-from-commands');
+
+function tmpdir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'devlog-tracker-skills-'));
+}
+
+test('generateSkillsFromCommands writes one SKILL.md per command file, using namePrefix', () => {
+  const commandsDir = tmpdir();
+  const targetSkillsDir = tmpdir();
+  fs.writeFileSync(
+    path.join(commandsDir, 'start.md'),
+    '---\ndescription: 啟動追蹤\n---\n\n請執行以下步驟：\n1. 做事\n'
+  );
+
+  const written = generateSkillsFromCommands({ commandsDir, targetSkillsDir, namePrefix: 'devlog' });
+
+  assert.equal(written.length, 1);
+  const skillPath = path.join(targetSkillsDir, 'devlog-start', 'SKILL.md');
+  assert.equal(written[0], skillPath);
+  const content = fs.readFileSync(skillPath, 'utf8');
+  assert.match(content, /^---\nname: devlog-start\ndescription: "啟動追蹤"\n---\n\n/);
+  assert.match(content, /請執行以下步驟：/);
+  assert.match(content, /使用者提供的額外參數：請看觸發這個 skill 的使用者訊息。\n$/);
+});
+
+test('generateSkillsFromCommands ignores non-.md files', () => {
+  const commandsDir = tmpdir();
+  const targetSkillsDir = tmpdir();
+  fs.writeFileSync(path.join(commandsDir, 'start.md'), '---\ndescription: x\n---\nbody');
+  fs.writeFileSync(path.join(commandsDir, 'README.txt'), 'not a command');
+
+  const written = generateSkillsFromCommands({ commandsDir, targetSkillsDir, namePrefix: 'devlog' });
+
+  assert.equal(written.length, 1);
+});
+
+test('generateSkillsFromCommands uses a different prefix and target dir independently', () => {
+  const commandsDir = tmpdir();
+  const targetSkillsDir = tmpdir();
+  fs.writeFileSync(path.join(commandsDir, 'status.md'), '---\ndescription: 查狀態\n---\nbody');
+
+  generateSkillsFromCommands({ commandsDir, targetSkillsDir, namePrefix: 'claude-devlog' });
+
+  assert.ok(fs.existsSync(path.join(targetSkillsDir, 'claude-devlog-status', 'SKILL.md')));
+});

package/cli/vendor.js

@@ -2,7 +2,11 @@
 const fs = require('fs');
 const path = require('path');
 
-const VENDOR_ENTRIES = ['hooks/scripts', 'codex/hooks', 'cursor/hooks', 'skills', 'commands'];
+const VENDOR_ENTRIES = ['core/scripts', 'claude/hooks.json', 'codex/hooks', 'cursor/hooks', 'skills', 'commands'];
+
+// 0.25.x及更早版本 vendor 到 .devlog-tracker/hooks/scripts/；升級後改放
+// core/scripts/，這裡清掉舊目錄避免孤兒檔案殘留。
+const STALE_ENTRIES = ['hooks'];
 
 function copyRecursive(src, dest) {
   const stat = fs.statSync(src);
@@ -29,6 +33,9 @@ function vendor({ repoRoot, targetDir, version }) {
     if (!fs.existsSync(src)) continue;
     copyRecursive(src, path.join(vendorRoot, entry));
   }
+  for (const entry of STALE_ENTRIES) {
+    fs.rmSync(path.join(vendorRoot, entry), { recursive: true, force: true });
+  }
   fs.writeFileSync(path.join(vendorRoot, 'VERSION'), `${version}\n`);
   fs.writeFileSync(path.join(vendorRoot, 'env.sh'), envShContent(vendorRoot));
   return vendorRoot;

package/cli/vendor.test.js

@@ -11,8 +11,10 @@ function tmpdir() {
 }
 
 function makeFakeRepo(dir) {
-  fs.mkdirSync(path.join(dir, 'hooks', 'scripts'), { recursive: true });
-  fs.writeFileSync(path.join(dir, 'hooks', 'scripts', 'enforce-devlog.sh'), '#!/usr/bin/env bash\necho hi\n');
+  fs.mkdirSync(path.join(dir, 'core', 'scripts'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'core', 'scripts', 'enforce-devlog.sh'), '#!/usr/bin/env bash\necho hi\n');
+  fs.mkdirSync(path.join(dir, 'claude'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'claude', 'hooks.json'), '{"hooks":{}}\n');
   fs.mkdirSync(path.join(dir, 'codex', 'hooks'), { recursive: true });
   fs.writeFileSync(path.join(dir, 'codex', 'hooks', 'on-stop.sh'), '#!/usr/bin/env bash\necho codex\n');
   fs.mkdirSync(path.join(dir, 'cursor', 'hooks'), { recursive: true });
@@ -31,7 +33,8 @@ test('vendor copies the expected directories and stamps VERSION + env.sh', () =>
   const vendorRoot = vendor({ repoRoot, targetDir, version: '0.21.0' });
 
   assert.equal(vendorRoot, path.join(targetDir, '.devlog-tracker'));
-  assert.ok(fs.existsSync(path.join(vendorRoot, 'hooks', 'scripts', 'enforce-devlog.sh')));
+  assert.ok(fs.existsSync(path.join(vendorRoot, 'core', 'scripts', 'enforce-devlog.sh')));
+  assert.ok(fs.existsSync(path.join(vendorRoot, 'claude', 'hooks.json')));
   assert.ok(fs.existsSync(path.join(vendorRoot, 'codex', 'hooks', 'on-stop.sh')));
   assert.ok(fs.existsSync(path.join(vendorRoot, 'cursor', 'hooks', 'on-stop.sh')));
   assert.ok(fs.existsSync(path.join(vendorRoot, 'skills', 'devlog-tracker', 'SKILL.md')));
@@ -43,14 +46,14 @@ test('vendor copies the expected directories and stamps VERSION + env.sh', () =>
   );
 });
 
-test('vendor preserves the ../../hooks/scripts relative layout codex/cursor wrappers rely on', () => {
+test('vendor preserves the ../../core/scripts relative layout codex/cursor wrappers rely on', () => {
   const repoRoot = tmpdir();
   const targetDir = tmpdir();
   makeFakeRepo(repoRoot);
 
   const vendorRoot = vendor({ repoRoot, targetDir, version: '0.21.0' });
 
-  const resolvedFromCodex = path.join(vendorRoot, 'codex', 'hooks', '..', '..', 'hooks', 'scripts', 'enforce-devlog.sh');
+  const resolvedFromCodex = path.join(vendorRoot, 'codex', 'hooks', '..', '..', 'core', 'scripts', 'enforce-devlog.sh');
   assert.ok(fs.existsSync(resolvedFromCodex));
 });
 
@@ -82,3 +85,19 @@ test('env.sh escapes shell metacharacters in the vendor path', () => {
   );
   assert.ok(fs.readFileSync(path.join(vendorRoot, 'env.sh'), 'utf8').includes('a\\$(x)\\"b\\`c\\\\d'));
 });
+
+test('re-running vendor after upgrade removes the stale hooks/scripts directory', () => {
+  const repoRoot = tmpdir();
+  const targetDir = tmpdir();
+  makeFakeRepo(repoRoot);
+
+  // Simulate a pre-upgrade install that used the old hooks/scripts layout.
+  const vendorRoot = path.join(targetDir, '.devlog-tracker');
+  fs.mkdirSync(path.join(vendorRoot, 'hooks', 'scripts'), { recursive: true });
+  fs.writeFileSync(path.join(vendorRoot, 'hooks', 'scripts', 'enforce-devlog.sh'), '#!/usr/bin/env bash\necho old\n');
+
+  vendor({ repoRoot, targetDir, version: '0.26.0' });
+
+  assert.ok(!fs.existsSync(path.join(vendorRoot, 'hooks')), 'stale hooks/ directory should be removed');
+  assert.ok(fs.existsSync(path.join(vendorRoot, 'core', 'scripts', 'enforce-devlog.sh')));
+});

package/codex/hooks/on-pre-tool.sh

@@ -3,16 +3,16 @@
 # contract as Claude Code (0 = allow, 2 = block), so this only needs the
 # cwd->CLAUDE_PROJECT_DIR translation; segment-watch.sh's stderr message
 # propagates unchanged. Fail-open like the Cursor adapter: only an exit code of
-# exactly 2 blocks; anything else (including a missing hooks/scripts dir or a
+# exactly 2 blocks; anything else (including a missing core/scripts dir or a
 # crash) allows.
 set -uo pipefail
 _src="${BASH_SOURCE[0]}"
 SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
-PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../hooks/scripts" 2>/dev/null && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../core/scripts" 2>/dev/null && pwd)"
 [ -d "$PLUGIN_SCRIPTS" ] || exit 0
 INPUT="$(cat 2>/dev/null || true)"
 ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
-export CLAUDE_PROJECT_DIR="$ROOT"
+export DEVLOG_PROJECT_DIR="$ROOT"
 printf '%s' "$INPUT" | bash "$PLUGIN_SCRIPTS/segment-watch.sh"
 RC=$?
 [ "$RC" -eq 2 ] && exit 2

package/codex/hooks/on-session-end.sh

@@ -7,10 +7,10 @@
 set -uo pipefail
 _src="${BASH_SOURCE[0]}"
 SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
-PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../hooks/scripts" && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../core/scripts" && pwd)"
 INPUT="$(cat 2>/dev/null || true)"
 ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
-export CLAUDE_PROJECT_DIR="$ROOT"
+export DEVLOG_PROJECT_DIR="$ROOT"
 
 REASON=""
 if command -v jq >/dev/null 2>&1; then

package/codex/hooks/on-session-start.sh

@@ -13,10 +13,10 @@
 set -uo pipefail
 _src="${BASH_SOURCE[0]}"
 SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
-PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../hooks/scripts" && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../core/scripts" && pwd)"
 INPUT="$(cat 2>/dev/null || true)"
 ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
-export CLAUDE_PROJECT_DIR="$ROOT"
+export DEVLOG_PROJECT_DIR="$ROOT"
 
 SRC=""
 if command -v jq >/dev/null 2>&1; then

package/codex/hooks/on-stop.sh

@@ -3,15 +3,15 @@
 # reads "stop_hook_active", which is Claude Code's own standard field name
 # and not one of the documented Codex naming gaps, so it is forwarded as-is.
 # Fail-open like the Cursor adapter: only an exit code of exactly 2 blocks;
-# anything else (including a missing hooks/scripts dir or a crash) allows.
+# anything else (including a missing core/scripts dir or a crash) allows.
 set -uo pipefail
 _src="${BASH_SOURCE[0]}"
 SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
-PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../hooks/scripts" 2>/dev/null && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../core/scripts" 2>/dev/null && pwd)"
 [ -d "$PLUGIN_SCRIPTS" ] || exit 0
 INPUT="$(cat 2>/dev/null || true)"
 ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
-export CLAUDE_PROJECT_DIR="$ROOT"
+export DEVLOG_PROJECT_DIR="$ROOT"
 printf '%s' "$INPUT" | bash "$PLUGIN_SCRIPTS/enforce-devlog.sh"
 RC=$?
 [ "$RC" -eq 2 ] && exit 2

package/codex/hooks/on-user-prompt-submit.sh

@@ -7,9 +7,9 @@
 set -uo pipefail
 _src="${BASH_SOURCE[0]}"
 SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
-PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../hooks/scripts" && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../core/scripts" && pwd)"
 INPUT="$(cat 2>/dev/null || true)"
 ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
-export CLAUDE_PROJECT_DIR="$ROOT"
+export DEVLOG_PROJECT_DIR="$ROOT"
 printf '%s' "$INPUT" | bash "$PLUGIN_SCRIPTS/round-start.sh"
 exit 0

package/codex/hooks/test-adapters.sh

@@ -77,7 +77,7 @@ else
   echo "FAIL: sessionEnd 'why' fallback"; FAIL=1
 fi
 
-# fail-open: when ../../hooks/scripts is missing, preTool/stop wrappers must allow (exit 0)
+# fail-open: when ../../core/scripts is missing, preTool/stop wrappers must allow (exit 0)
 ORPHAN="$TMP/orphan"
 mkdir -p "$ORPHAN/codex/hooks"
 cp "$SCRIPT_DIR/on-pre-tool.sh" "$SCRIPT_DIR/on-stop.sh" "$SCRIPT_DIR/project-dir.sh" "$ORPHAN/codex/hooks/"
@@ -86,7 +86,7 @@ for W in on-pre-tool on-stop; do
   printf '{"cwd":"%s"}' "$ORPHAN" | bash "$ORPHAN/codex/hooks/$W.sh" >/dev/null 2>/dev/null
   RC=$?
   set -e
-  if [ "$RC" -eq 0 ]; then echo "PASS: $W fails open without hooks/scripts (exit 0)"; else echo "FAIL: $W orphan exit [$RC]"; FAIL=1; fi
+  if [ "$RC" -eq 0 ]; then echo "PASS: $W fails open without core/scripts (exit 0)"; else echo "FAIL: $W orphan exit [$RC]"; FAIL=1; fi
 done
 
 # sessionStart: payload with neither "how" nor "source" falls back to startup and still injects

package/commands/checkpoint.md

@@ -6,8 +6,8 @@ description: 調整 Checkpoint Mode 的沉默門檻——累積多少輪沒寫 #
 跑：
 
 ```bash
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/checkpoint-set.sh" <rounds>
+PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/checkpoint-set.sh" <rounds>
 ```
 
 不要自己手改 `.devlog/.checkpoint-state`。

package/commands/clean.md

@@ -30,11 +30,11 @@ description: 無條件清空 .devlog/devlog.md（含專案摘要與所有 Round
 ## 3. 跑清空腳本
 
 ```bash
-先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
+先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
 
 ```bash
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/clean-devlog.sh" --confirmed
+PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/clean-devlog.sh" --confirmed
 ```
 ```
 

package/commands/compact.md

@@ -13,10 +13,10 @@ description: 把 .devlog/devlog.md 裡已完成且較舊的紀錄搬到 devlog.a
    - 所有 `## Checkpoint` 區塊，永遠留在 devlog.md、不搬到 archive——它們是
      checkpoint 機制存在的目的：翻閱時的摘要路標，搬走就失去了作用
 4. 跑（不要自己搬檔）：
-   先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
+   先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
    ```bash
-   PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-   CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/compact-devlog.sh"
+   PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+   DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/compact-devlog.sh"
    ```
    檔案不存在時腳本 exit 1：告知沒有東西可壓縮。
 5. 用 stdout 的 `MOVED` / `REMAINING` / `ARCHIVE` 回報一句話。

package/commands/continue.md

@@ -9,12 +9,12 @@ description: 讀取 .devlog/devlog.md，核對最後一輪 Handoff 的工作區
 3. 讀最近的 Round（不夠再往前讀；有 `## Checkpoint` 就一併看最後一個）。不要讀 `devlog.archive.md` 或 `devlog.<name>.md`，除非 Handoff 下一步明確指向它們。
 4. 依**最後一個歷史 Round**（不是這一輪 continue 自己的 skeleton）的 Status 行動。`DONE`：告訴使用者上一題已經結束，等新需求。不要核對、不要自己找下一件工作。
 5. `IN_PROGRESS`、`INTERRUPTED`、`BLOCKED`：先核對，再行動。不要先問「上次做到哪」。不要改歷史 Round。
-   1. 跑與寫「工作區」相同的生產者，不要自己跑 git、不要手編成 SKILL 的七種格式。先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
+   1. 跑與寫「工作區」相同的生產者，不要自己跑 git、不要手編成 SKILL 的七種格式。先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
       ```bash
-      PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-      CLAUDE_PROJECT_DIR="<步驟 1 記下的專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/hooks/scripts/workspace-snapshot.sh"
+      PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+      DEVLOG_PROJECT_DIR="<步驟 1 記下的專案根目錄絕對路徑，不要用 $(pwd) 重新推>" bash "${PLUGIN_ROOT}/core/scripts/workspace-snapshot.sh"
       ```
-      把 `CLAUDE_PROJECT_DIR` 換成實際的絕對路徑字串再執行，不要真的呼叫 `pwd`。stdout 就是實際快照（1 行或 2 行）。腳本檔找不到時才退回 `skills/devlog-tracker/SKILL.md` `#### 工作區` 的七種格式手編。不要重跑測試套件，除非「下一步」本身就是跑測試。
+      把 `DEVLOG_PROJECT_DIR` 換成實際的絕對路徑字串再執行，不要真的呼叫 `pwd`。stdout 就是實際快照（1 行或 2 行）。腳本檔找不到時才退回 `skills/devlog-tracker/SKILL.md` `#### 工作區` 的七種格式手編。不要重跑測試套件，除非「下一步」本身就是跑測試。
    2. 把編成的實際快照對照該歷史 Round 的 `#### 工作區` 正文。
       - 沒有這一節（舊 Round、`INTERRUPTED` stub）：沒有宣稱可對，不算「不符」——不用寫 `### 段落`，直接以剛才編成的實際快照為準。
       - 有這一節但跟編成的實際快照不符：在**這一輪**先追加一段 `### 段落`，寫宣稱 vs 實際（用剛才腳本的 stdout 當實際快照）。

package/commands/keep.md

@@ -34,16 +34,19 @@ description: 掃描整份 devlog.md，把值得留名的主題段落一次分別
 回覆：
   採用 → 全部照上面寫入
   改第 N 段範圍 <from>-<to> / 改第 N 段檔名 <name> / 移除第 N 段
+  摘要第 N 段 → 這一段搬完後，把敘事部分改寫得更精簡（見下方說明）
   全部歷史合併成一個檔 <name> → 放棄分段，整份歷史存成一檔
   取消
 ```
 
-同一則回覆可以合併多條修改，例如「改第 2 段檔名 foo，移除第 3 段」。`N` 一律對應上面列出的原始編號，修改不會讓其他段落重新編號。
+同一則回覆可以合併多條修改，例如「改第 2 段檔名 foo，移除第 3 段，摘要第 1 段」。`N` 一律對應上面列出的原始編號，修改不會讓其他段落重新編號。
+
+「摘要第 N 段」是選配、預設關閉：不特別指定就跟現在一樣，逐字搬移。指定的段落記下來，留到步驟 5.5 使用；跟「改範圍」「改檔名」同一則回覆可以合併，不影響步驟 4 的驗證。
 
 然後停止。使用者還沒回覆前不要寫任何檔。
 
 - 取消，或套用修改後一段都不剩 → 不改檔，結束。
-- 「全部歷史合併成一個檔 `<name>`」→ 放棄前面列出的分段，改成單一段：`from` = 最早的歷史 Round、`to` = 最晚的歷史 Round（仍不含開著的 Round），`<name>` 用使用者這裡給的名稱。之後只處理這一段，跳過步驟 4 的「重疊」與「批次撞名」檢查（只有一段）。
+- 「全部歷史合併成一個檔 `<name>`」→ 放棄前面列出的分段，改成單一段：`from` = 最早的歷史 Round、`to` = 最晚的歷史 Round（仍不含開著的 Round），`<name>` 用使用者這裡給的名稱。之後只處理這一段，跳過步驟 4 的「重疊」與「批次撞名」檢查（只有一段）；「摘要」仍可套用在這唯一一段上。
 - 其他回覆（採用 / 各種修改組合）→ 帶著套用修改後的段落清單，進入步驟 4。
 
 ## 4. 驗證每一段的範圍與檔名（不通過就再問一次，仍不寫檔）
@@ -75,11 +78,11 @@ description: 掃描整份 devlog.md，把值得留名的主題段落一次分別
 
 把步驟 4 驗證通過的段落，依 `from` 由小到大排序。對每一段依序跑（一段一次，不要自己搬檔，也不要一次塞多段給腳本）：
 
-先決定 plugin 根目錄（有 `CLAUDE_PLUGIN_ROOT` 用它；否則用 `DEVLOG_TRACKER_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
+先決定 plugin 根目錄（有 `DEVLOG_TRACKER_ROOT` 用它；否則用 `CLAUDE_PLUGIN_ROOT`；兩者都空就用含 `.claude-plugin/plugin.json` 的本 plugin 根目錄）：
 
 ```bash
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/keep-move.sh" \
+PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/keep-move.sh" \
   --from <from> --to <to> --name "<name>" --desc "<這段在做什麼的一句話>"
 ```
 
@@ -89,6 +92,19 @@ CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/keep-move.sh" \
 
 如果這批段落最終涵蓋了 `devlog.md` 目前剩下的所有歷史 Round（沒有瑣碎段落留下），跑到最後一段（Round 號碼最新的那一段）時，腳本會自動判定為 full keep：專案摘要併入那一檔、開著的 Round 重編號成 1、`.span-open` 刪除、checkpoint counter 歸零。這是預期行為，不用特別處理，也不用另外判斷「這是不是 full keep」。
 
+## 5.5 選配：摘要標記為「摘要第 N 段」的段落
+
+只處理步驟 3 使用者明確標記要摘要、且步驟 5 已成功搬移的段落。沒有任何段落被標記時，整節跳過。
+
+這一步是 Claude 自己改寫，不是另外呼叫 LLM API、不是腳本邏輯——`keep-move.sh` 在步驟 5 已經把該段逐字搬進 `devlog.<name>.md`，機器可核對的欄位跟這一步無關。對每個被標記的段落：
+
+1. 用 Read 讀出該段剛寫入的 `devlog.<name>.md` 全文。
+2. 只能改寫每個 `## Round` 裡的敘事文字：`### Summary`、`### Reply`、`#### 決策`、`#### 現況`。把同一輪裡這幾節的內容改寫得更精簡，可以合併重複的敘述，但不要跨 Round 合併——Round 的數量與編號必須維持原樣。
+3. 絕對不要動：`## Round <n> — <時間戳>` 標題本身、`### User Input`、`#### 工作區`、`#### 檔案`、`#### 完成條件`、`#### 下一步`、`### Status`，以及 `## Kept 索引`。這些是機器核對過的事實或 `resume`／`continue` 接手時要逐字比對的欄位，摘要只能動無法被 git 或 Stop 驗證的敘事散文。
+4. 用 Edit 把改寫後的內容寫回同一個檔案（不要用 Write 整檔覆寫，避免不小心動到上面列的欄位）。
+
+改寫完成後才進入步驟 6／7 回報；回報時註明哪幾段套用了摘要。
+
 ## 6. 處理腳本結果
 
 每段成功時記下 stdout 給的具名檔路徑、`ROUNDS=<from>-<to>` 與 `REMAINING=<int>`，等這批全部段落都跑完（或某段失敗中止）後，一次在步驟 7 回報。

package/commands/lessons-drift.md

@@ -1,15 +1,15 @@
 ---
-description: 調整 Lessons Mode「工作區漂移重複發生」機制性提醒的門檻——累積幾次工作區不符才印一次建議。
+description: 調整 Lessons Mode 機制性提醒的共用門檻——工作區漂移或 BLOCKED 輪次累積達幾次才印一次建議。
 ---
 
 取得使用者要設定的次數（正整數）；沒帶就先問，不要用預設值硬猜。跑：
 
 ```bash
-PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${DEVLOG_TRACKER_ROOT:-}}"
-CLAUDE_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/hooks/scripts/lessons-drift-set.sh" <次數>
+PLUGIN_ROOT="${DEVLOG_TRACKER_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+DEVLOG_PROJECT_DIR="$(pwd)" bash "${PLUGIN_ROOT}/core/scripts/lessons-drift-set.sh" <次數>
 ```
 
-不要自己手改 `.devlog/.lessons-drift-state`。
+不要自己手改 `.devlog/.lessons-advisory-state`。
 
 - stdout 是 `NOT_STARTED`：告知這個專案還沒 `/devlog-tracker:start`，問要不要現在
   `/devlog-tracker:start`，不要自己跑 start。