kenaz 0.3.12 → 0.3.14

package/core/.specialist/tools/__tests__/handoff-doc.test.js

@@ -0,0 +1,46 @@
+// Project handoff documents: handoff-doc.js writes ISBAR files under .kenaz/handoffs/, and
+// ansuz-boot-fast.js lists them (plus legacy handoff*.md) newest first. Temp project dirs only.
+// Usage: node --test .specialist/tools/__tests__/handoff-doc.test.js
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const doc = require('../handoff-doc.js');
+const boot = require('../ansuz-boot-fast.js');
+
+const tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'kenaz-handoff-'));
+
+test('new writes an ISBAR file under .kenaz/handoffs with Identification filled in', () => {
+  const p = tmp();
+  const f = doc.create(p, '中繼 部署/收尾', 'sess-1', new Date(2026, 9, 11, 22, 5));
+  assert.strictEqual(path.dirname(f), path.join(p, '.kenaz', 'handoffs'));
+  assert.strictEqual(path.basename(f), '2026-10-11-2205-中繼-部署-收尾.md');
+  const s = fs.readFileSync(f, 'utf8');
+  for (const h of ['# Handoff: 中繼 部署/收尾', '## I · Identification', '## S · Situation', '## B · Background', '## A · Assessment', '## R · Recommendation']) assert.ok(s.includes(h), h);
+  assert.ok(s.includes('session sess-1'));
+  const again = doc.create(p, '中繼 部署/收尾', 'sess-1', new Date(2026, 9, 11, 22, 5));
+  assert.notStrictEqual(again, f, 'never overwrites an earlier handoff');
+});
+
+test('boot lists handoffs newest first, standard dir and legacy names, and ignores other markdown', () => {
+  const p = tmp();
+  const old = doc.create(p, 'older', null);
+  const newer = doc.create(p, 'newer', null);
+  fs.writeFileSync(path.join(p, '.kenaz', 'HANDOFF.md'), '# Legacy lane handoff\n');
+  fs.mkdirSync(path.join(p, 'docs'));
+  fs.writeFileSync(path.join(p, 'docs', 'README.md'), '# not a handoff\n');
+  const t = Date.now() / 1000;
+  fs.utimesSync(old, t - 3 * 86400, t - 3 * 86400);
+  fs.utimesSync(path.join(p, '.kenaz', 'HANDOFF.md'), t - 86400, t - 86400);
+  const docs = boot.findHandoffDocs(p);
+  assert.deepStrictEqual(docs.map((d) => path.basename(d.rel)), [path.basename(newer), 'HANDOFF.md', path.basename(old)]);
+  const lines = boot.handoffDocLines(p);
+  assert.match(lines[0], /Project handoff/);
+  assert.match(lines[1], /→ \.kenaz\/handoffs\/.*newer\.md  \(today\)  Handoff: newer/);
+  assert.match(lines[2], /\.kenaz\/HANDOFF\.md  \(1d ago\)  Legacy lane handoff/);
+});
+
+test('control: a project without handoffs prints nothing', () => {
+  assert.deepStrictEqual(boot.handoffDocLines(tmp()), []);
+});

package/core/.specialist/tools/__tests__/task-2425-lessons-lifecycle.test.js

@@ -0,0 +1,142 @@
+'use strict';
+// TASK_2425: lesson lifecycle. Temp homes and temp projects only, never the real ~/.kenaz.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const lessons = require('../lessons');
+
+const ROOT = path.resolve(__dirname, '..', '..', '..');
+const mk = () => fs.mkdtempSync(path.join(os.tmpdir(), 'k2425-'));
+const project = () => { const p = mk(); fs.mkdirSync(path.join(p, '.kenaz'), { recursive: true }); return p; };
+const files = (dir) => { try { return fs.readdirSync(dir).filter((n) => n.endsWith('.md')); } catch (_) { return []; } };
+const projKnowledge = (p) => path.join(p, '.kenaz', 'knowledge');
+function fire(p, id, n, daysAgo = 1) {
+  const log = path.join(p, '.kenaz', 'specialist', 'memory_usage.jsonl');
+  fs.mkdirSync(path.dirname(log), { recursive: true });
+  for (let i = 0; i < n; i++) {
+    fs.appendFileSync(log, JSON.stringify({ ts: new Date(Date.now() - daysAgo * 86400000).toISOString(), kind: 'guard', file: `${id}.md` }) + '\n');
+  }
+}
+const addP = (p, home, text, extra = {}) => lessons.add({ scope: 'project', text, projectPath: p, home, ...extra });
+
+test('dedup: a similar text bumps recurrences and writes no file; a dissimilar text writes one', () => {
+  const home = mk(); const p = project();
+  const a = addP(p, home, 'never run the deploy script on the main branch');
+  const r = addP(p, home, 'never run deploy script on main branch');
+  assert.equal(r.recurred, true); assert.equal(r.id, a.id); assert.equal(r.recurrences, 1);
+  assert.equal(files(projKnowledge(p)).length, 1);
+  assert.equal(addP(p, home, 'never run deploy script on main branch').recurrences, 2);
+  assert.match(fs.readFileSync(path.join(projKnowledge(p), `${a.id}.md`), 'utf8'), /recurrences: 2\r?\nlast_recurrence: /);
+  const ctl = addP(p, home, 'use pnpm for installing packages here');
+  assert.ok(!ctl.recurred); assert.equal(files(projKnowledge(p)).length, 2);
+  assert.ok(!addP(p, home, 'never run deploy script on main branch', { force: true }).recurred);
+  assert.equal(files(projKnowledge(p)).length, 3);
+});
+
+test('dedup: Chinese text dedups by character', () => {
+  const home = mk(); const p = project();
+  const a = addP(p, home, '部署前必須先跑測試');
+  assert.equal(addP(p, home, '部署前必須先執行測試').id, a.id);
+  assert.equal(files(projKnowledge(p)).length, 1);
+  assert.ok(!addP(p, home, '回覆一律使用繁體中文').recurred);
+});
+
+test('cap: the 21st active lesson is refused with merge suggestions and nothing is written', () => {
+  const home = mk(); const p = project();
+  for (let i = 0; i < lessons.MAX_ACTIVE_PER_LAYER; i++) addP(p, home, `lesson${i}x unique${i}y words${i}z`);
+  assert.equal(files(projKnowledge(p)).length, 20);
+  assert.throws(() => addP(p, home, 'completely other thing about databases'), (e) => /cap of 20/.test(e.message) && (e.message.match(/kenaz learn merge/g) || []).length === 3);
+  assert.equal(files(projKnowledge(p)).length, 20);
+});
+
+test('merge: one new lesson, sources archived with merged_into, fires and recurrences summed', () => {
+  const home = mk(); const p = project();
+  const a = addP(p, home, 'alpha rule one', { paths: ['src/a'] }); const b = addP(p, home, 'beta other rule two', { paths: ['src/b'] });
+  fire(p, a.id, 2); fire(p, b.id, 1);
+  const r = lessons.merge([a.id, b.id], { text: 'general rule for both', projectPath: p, home });
+  const rows = lessons.listAll({ projectPath: p, home });
+  assert.equal(rows.length, 1); assert.equal(rows[0].id, r.id);
+  assert.equal(rows[0].fires, 3); assert.deepEqual(rows[0].paths.sort(), ['src/a', 'src/b']);
+  const arch = path.join(projKnowledge(p), 'archive', 'merged');
+  assert.deepEqual(files(arch).sort(), [`${a.id}.md`, `${b.id}.md`].sort());
+  assert.match(fs.readFileSync(path.join(arch, `${a.id}.md`), 'utf8'), new RegExp(`merged_into: "${r.id}"`));
+  assert.throws(() => lessons.merge([a.id, b.id], { text: 'x', projectPath: p, home }), /no active lesson/);
+});
+
+test('graduate: archived under graduated/ with graduated_to', () => {
+  const home = mk(); const p = project();
+  const a = addP(p, home, 'something that became a test');
+  lessons.graduate(a.id, 'abc1234', { projectPath: p, home });
+  assert.equal(lessons.listAll({ projectPath: p, home }).length, 0);
+  assert.match(fs.readFileSync(path.join(projKnowledge(p), 'archive', 'graduated', `${a.id}.md`), 'utf8'), /graduated_to: "abc1234"/);
+});
+
+test('review: 3 fires and 2 recurrences are candidates, 1 fire is not; similar pairs and old prefs listed', () => {
+  const home = mk(); const p = project();
+  const three = addP(p, home, 'first topic zebra alpha'); const rec = addP(p, home, 'second matter quartz beta');
+  const one = addP(p, home, 'third item walnut gamma');
+  fire(p, three.id, 3); fire(p, one.id, 1);
+  addP(p, home, 'second matter quartz beta'); addP(p, home, 'second matter quartz beta');
+  addP(p, home, 'third item walnut gamma delta', { force: true });
+  const old = lessons.add({ scope: 'user', text: 'old preference about tabs', projectPath: p, home });
+  const f = path.join(home, '.kenaz', 'knowledge', `${old.id}.md`);
+  fs.writeFileSync(f, fs.readFileSync(f, 'utf8').replace(/created: .*/, `created: ${new Date(Date.now() - 100 * 86400000).toISOString()}`));
+  const r = lessons.reviewAll({ projectPath: p, home });
+  assert.deepEqual(r.candidates.map((l) => l.id).sort(), [three.id, rec.id].sort());
+  assert.ok(!r.candidates.some((l) => l.id === one.id));
+  assert.deepEqual(r.oldPrefs.map((l) => l.id), [old.id]);
+  assert.ok(r.pairs.some((x) => [x.a.id, x.b.id].includes(one.id)));
+});
+
+test('banner: nudge only when there is something to act on; prefs capped at 10 plus +K more', () => {
+  const home = mk(); const p = project();
+  addP(p, home, 'plain fact about widgets');
+  assert.ok(!lessons.bannerLines(p, { home }).some((l) => l.startsWith('[lessons]')));
+  const a = addP(p, home, 'fact two about gadgets'); fire(p, a.id, 3);
+  assert.ok(lessons.bannerLines(p, { home }).includes('[lessons] 1 to graduate, 0 near cap: kenaz learn review'));
+  const home2 = mk(); const p2 = project();
+  for (let i = 0; i < 18; i++) addP(p2, home2, `lesson${i}x unique${i}y words${i}z`);
+  assert.ok(lessons.bannerLines(p2, { home: home2 }).includes('[lessons] 0 to graduate, 1 near cap: kenaz learn review'));
+  const home3 = mk(); const p3 = project();
+  for (let i = 0; i < 12; i++) lessons.add({ scope: 'user', text: `pref${i}x unique${i}y words${i}z`, projectPath: p3, home: home3 });
+  const lines = lessons.bannerLines(p3, { home: home3 });
+  assert.equal(lines.filter((l) => l.startsWith('[learn] pref:')).length, 10);
+  assert.ok(lines.includes('[learn] +2 more'));
+});
+
+test('stats: per-layer lifecycle counts, read-only', () => {
+  const home = mk(); const p = project();
+  const a = addP(p, home, 'stat lesson one'); const b = addP(p, home, 'other thing two here');
+  fire(p, a.id, 2); addP(p, home, 'stat lesson one');
+  lessons.graduate(b.id, 'x', { projectPath: p, home });
+  const s = lessons.stats({ projectPath: p, home });
+  assert.deepEqual([s.project.active, s.project.fires, s.project.recurrences, s.project.graduated, s.project.merged], [1, 2, 1, 1, 0]);
+});
+
+test('npm path: kenaz learn review|merge|graduate through cli.js against a staged ~/.kenaz/core', () => {
+  const home = mk(); const p = project();
+  const core = path.join(home, '.kenaz', 'core');
+  fs.mkdirSync(path.join(core, '.specialist', 'tools'), { recursive: true });
+  fs.mkdirSync(path.join(core, '.vendor'), { recursive: true });
+  for (const n of ['lessons.js', 'lessons-lifecycle.js', 'lessons-harvest.js']) fs.copyFileSync(path.join(ROOT, '.specialist', 'tools', n), path.join(core, '.specialist', 'tools', n));
+  for (const n of ['js-yaml.cjs', 'require-yaml.cjs']) fs.copyFileSync(path.join(ROOT, '.vendor', n), path.join(core, '.vendor', n));
+  const { run } = require(path.join(ROOT, 'packages', 'kenaz', 'lib', 'cli.js'));
+  const go = (...argv) => { const out = []; const code = run(['learn', ...argv, '--home', home, '--project-path', p], (l) => out.push(l)); return { code, text: out.join('\n') }; };
+  const first = go('add', '--scope', 'project', '--about', 'kenaz', '--text', 'kenaz banner hides the wish line');
+  assert.equal(first.code, 0);
+  const id = /learned (lesson-\w+)/.exec(first.text)[1];
+  assert.match(go('add', '--scope', 'project', '--text', 'kenaz banner hides the wish line').text, /recurred lesson-\w+ \(1 times\)/);
+  go('add', '--scope', 'project', '--text', 'kenaz banner hides the wish line');
+  const rev = go('review').text;
+  assert.match(rev, /make it code in this project/); assert.match(rev, new RegExp(id));
+  assert.match(rev, /kenaz_wish_create scope=kenaz/);
+  const other = /learned (lesson-\w+)/.exec(go('add', '--scope', 'project', '--text', 'use pnpm for installs here').text)[1];
+  const m = go('merge', id, other, '--text', 'general rule');
+  assert.equal(m.code, 0); assert.match(m.text, /merged/);
+  const newId = /into (lesson-\w+)/.exec(m.text)[1];
+  assert.match(go('graduate', newId, '--to', 'deadbeef').text, /graduated/);
+  assert.equal(lessons.listAll({ projectPath: p, home: mk() }).length, 0);
+  assert.equal(files(path.join(projKnowledge(p), 'archive', 'graduated')).length, 1);
+});

package/core/.specialist/tools/__tests__/task-2427-harvest.test.js

@@ -0,0 +1,150 @@
+'use strict';
+// TASK_2427: harvest from the project's own history, review suggestions, nudge log, self-improvement stats.
+// Temp git repos and temp homes only, never the real ~/.kenaz or ~/.claude.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync, spawnSync } = require('child_process');
+const lessons = require('../lessons');
+const hv = require('../lessons-harvest');
+const stats = require('../../../.formation/tools/kenaz-stats');
+
+const mk = () => fs.mkdtempSync(path.join(os.tmpdir(), 'k2427-'));
+const put = (file, body) => { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, body); };
+
+/** Repo with: TASK_1 clean, TASK_2 reviewer fix on the branch after delivery, TASK_3 fix-up on main after the merge. */
+function repo({ rework = true } = {}) {
+  const dir = mk();
+  const g = (...a) => execFileSync('git', a, { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  g('init', '-q', '-b', 'main'); g('config', 'user.email', 't@t'); g('config', 'user.name', 't'); g('config', 'commit.gpgsign', 'false');
+  const commit = (msg, file) => { put(path.join(dir, file), msg + Math.random()); g('add', '-A'); g('commit', '-q', '-m', msg); };
+  const land = (card, br, steps) => {
+    g('checkout', '-q', '-b', br);
+    for (const [m, f] of steps) commit(m, f);
+    g('checkout', '-q', 'main'); g('merge', '--no-ff', '-q', '-m', `Merge ${card}: done`, br);
+  };
+  commit('base', 'README.md');
+  land('TASK_1', 'b1', [['[TASK_1] task completed', 'src/one.js']]);
+  if (rework) {
+    land('TASK_2', 'b2', [['[TASK_2] task completed', 'src/two.js'], ['[TASK_2] reviewer fix', 'src/fix.js']]);
+    land('TASK_3', 'b3', [['[TASK_3] task completed', 'src/three.js']]);
+    commit('[TASK_3] fix-up after merge', 'src/late.js');
+  }
+  return dir;
+}
+
+test('rework is harvested once with the files of the extra commits, and disappears after add --source harvest:<id>', () => {
+  const dir = repo(); const home = mk();
+  const items = hv.harvest({ projectPath: dir });
+  const ids = items.map((i) => i.id).sort();
+  assert.deepEqual(ids, ['rework:TASK_2', 'rework:TASK_3']);
+  const t2 = items.find((i) => i.id === 'rework:TASK_2');
+  assert.deepEqual(t2.paths, ['src/fix.js']);
+  assert.match(t2.cmd, /^kenaz learn add --scope project --type check --paths src\/fix\.js --text "<why: .*" --source harvest:rework:TASK_2$/);
+  assert.deepEqual(items.find((i) => i.id === 'rework:TASK_3').paths, ['src/late.js']);
+  const r = lessons.add({ scope: 'project', text: 'run the reviewer checklist before delivering', paths: ['src/fix.js'], source: 'harvest:rework:TASK_2', projectPath: dir, home });
+  assert.ok(r.id);
+  assert.match(fs.readFileSync(path.join(dir, '.kenaz', 'knowledge', `${r.id}.md`), 'utf8'), /source: "harvest:rework:TASK_2"/);
+  assert.deepEqual(hv.harvest({ projectPath: dir }).map((i) => i.id), ['rework:TASK_3']);
+  assert.throws(() => lessons.add({ scope: 'project', text: 'x y', source: 'bogus', projectPath: dir, home }), /--source/);
+});
+
+test('control: a clean history harvests nothing and the banner prints no line', () => {
+  const dir = repo({ rework: false }); const home = mk();
+  assert.deepEqual(hv.harvest({ projectPath: dir }), []);
+  assert.deepEqual(lessons.bannerLines(dir, { home, syncHarvest: true }), []);
+  const out = []; lessons.main(['harvest', '--project-path', dir, '--home', home], (l) => out.push(l));
+  assert.deepEqual(out, ['no history items to harvest']);
+});
+
+test('failed executor result, blocked card with a reason and a handoff A-section risk line are harvested', () => {
+  const dir = repo({ rework: false }); const execDir = mk(); const now = Date.now();
+  put(path.join(execDir, 'TASK_9-abc.result.json'), JSON.stringify({ adapter: 'deepseek', model: 'v3', ok: false, exitCode: 1, error: 'no commits', worktree: path.join(dir, '.wt', 'x') }));
+  put(path.join(execDir, 'TASK_8-def.result.json'), JSON.stringify({ adapter: 'codex', ok: true, worktree: path.join(dir, '.wt', 'y') }));
+  put(path.join(execDir, 'TASK_7-zzz.result.json'), JSON.stringify({ adapter: 'codex', ok: false, error: 'other project', worktree: path.join(mk(), 'wt') }));
+  put(path.join(dir, '.kenaz', 'tasks', 'blocked', 'TASK_5_thing.yaml'), 'id: TASK_5\nblocked_reason: needs the vendor key\nscope_paths:\n  - src/api\n');
+  put(path.join(dir, '.kenaz', 'tasks', 'blocked', 'TASK_6_thing.yaml'), 'id: TASK_6\n');
+  put(path.join(dir, '.kenaz', 'handoffs', '2026-10-11-1200-x.md'), [
+    '# Handoff: x', '', '## A · Assessment（評估）', '- 已驗證（怎麼驗證的）：unit tests', '- 未驗證 / 風險 / 阻塞：', '  - Windows path handling is untested', '- unverified: migration on a big db', '## R · Recommendation', '- risk: not an A-section line', ''].join('\n'));
+  const items = hv.harvest({ projectPath: dir, now, execDir });
+  assert.deepEqual(items.map((i) => i.id.split(':')[0]).sort(), ['blocked', 'exec', 'handoff', 'handoff']);
+  assert.match(items.find((i) => i.id.startsWith('exec:')).why, /no commits/);
+  assert.deepEqual(items.find((i) => i.id === 'blocked:TASK_5').paths, ['src/api']);
+  const hand = items.filter((i) => i.id.startsWith('handoff:')).map((i) => i.why).join('|');
+  assert.match(hand, /Windows path handling/); assert.match(hand, /migration on a big db/); assert.ok(!/not an A-section/.test(hand));
+  assert.deepEqual(hv.harvest({ projectPath: dir, now: now + 40 * 86400000, execDir }), [], 'items age out after the harvest window (7 days)');
+});
+
+test('banner: one line at most, merged with the lessons line when both apply', () => {
+  const dir = repo(); const home = mk();
+  assert.deepEqual(lessons.bannerLines(dir, { home, syncHarvest: true }), ['[learn] 2 history items to review: kenaz learn review']);
+  const a = lessons.add({ scope: 'project', text: 'alpha rule', projectPath: dir, home, force: true });
+  for (let i = 0; i < 3; i++) {
+    const log = path.join(dir, '.kenaz', 'specialist', 'memory_usage.jsonl');
+    fs.appendFileSync(log, JSON.stringify({ ts: new Date().toISOString(), kind: 'guard', file: `${a.id}.md` }) + '\n');
+  }
+  const lines = lessons.bannerLines(dir, { home, syncHarvest: true });
+  assert.equal(lines.filter((l) => /review/.test(l)).length, 1);
+  assert.match(lines.join('\n'), /\[lessons\] 1 to graduate, 0 near cap, 2 history items: kenaz learn review/);
+});
+
+test('review prints the per-rigor suggestion and the top rework files from a fake dashboard-models.json', () => {
+  const dir = repo(); const home = mk();
+  for (const [id, r] of [['TASK_1', 'high'], ['TASK_2', 'high'], ['TASK_3', 'high']]) put(path.join(dir, '.kenaz', 'tasks', 'done', `${id}_x.yaml`), `id: ${id}\nrigor: ${r}\n`);
+  put(path.join(dir, '.kenaz', 'dashboard-models.json'), JSON.stringify({ dispatchFamily: 'claude', dispatchModelByRigor: { high: 'claude-sonnet-4-5' } }));
+  const out = []; lessons.main(['review', '--project-path', dir, '--home', home], (l) => out.push(l));
+  const text = out.join('\n');
+  assert.match(text, /high: 1\/3 first-pass with .*sonnet.*consider kenaz subagent set .* --rigor high/);
+  assert.match(text, /most rework commits: .*src\/(fix|late)\.js \(1\)/);
+  assert.match(text, /rework:TASK_2/);
+});
+
+test('correction-detect appends a nudge line without the prompt text', () => {
+  const dir = mk(); const home = mk();
+  put(path.join(dir, '.kenaz', 'project.yaml'), 'name: t\n');
+  const hook = path.join(__dirname, '..', '..', '..', '.claude', 'hooks', 'correction-detect.js');
+  const secret = '不是這樣 SECRET-PROMPT-TEXT';
+  const r = spawnSync(process.execPath, [hook], { input: JSON.stringify({ session_id: 's1', prompt: secret }), encoding: 'utf8',
+    env: { ...process.env, CLAUDE_PROJECT_DIR: dir, USERPROFILE: home, HOME: home, KENAZ_MODE: '' } });
+  assert.match(r.stdout, /--source correction-nudge/);
+  const log = fs.readFileSync(path.join(dir, '.kenaz', 'specialist', 'correction-nudges.jsonl'), 'utf8');
+  const row = JSON.parse(log.trim());
+  assert.equal(row.session_id, 's1'); assert.ok(Date.parse(row.ts));
+  assert.ok(!/SECRET|不是/.test(log));
+});
+
+test('stats: nudge conversion, lessons by source, recurrence after a fire, harvest open vs recorded, graduated', () => {
+  const dir = repo(); const home = mk(); const now = Date.now();
+  const nudge = (msAgo) => fs.appendFileSync(path.join(dir, '.kenaz', 'specialist', 'correction-nudges.jsonl'), JSON.stringify({ ts: new Date(now - msAgo).toISOString(), session_id: 's' }) + '\n');
+  put(path.join(dir, '.kenaz', 'specialist', 'correction-nudges.jsonl'), '');
+  nudge(3 * 3600000); // lesson added 5 min later: converted
+  nudge(2 * 3600000); // nothing follows: not converted
+  const a = lessons.add({ scope: 'project', text: 'always run the linter first', source: 'correction-nudge', projectPath: dir, home });
+  // move the lesson into the window right after the first nudge
+  const f = path.join(dir, '.kenaz', 'knowledge', `${a.id}.md`);
+  fs.writeFileSync(f, fs.readFileSync(f, 'utf8').replace(/created: .*/, `created: ${new Date(now - 3 * 3600000 + 5 * 60000).toISOString()}`));
+  const logUse = path.join(dir, '.kenaz', 'specialist', 'memory_usage.jsonl');
+  const line = (kind, msAgo) => JSON.stringify({ ts: new Date(now - msAgo).toISOString(), kind, file: `${a.id}.md` }) + '\n';
+  fs.appendFileSync(logUse, line('recurrence', 5 * 3600000) + line('guard', 4 * 3600000) + line('recurrence', 3600000));
+  lessons.add({ scope: 'project', text: 'harvested lesson about fix', source: 'harvest:rework:TASK_2', projectPath: dir, home });
+  const g = lessons.add({ scope: 'project', text: 'graduate me please', projectPath: dir, home });
+  lessons.graduate(g.id, 'abc123', { projectPath: dir, home });
+  const s = hv.selfStats({ projectPath: dir, home, now, days: 14 });
+  assert.equal(s.nudges, 2); assert.equal(s.converted, 1);
+  assert.equal(s.bySource['correction-nudge'].lessons, 1);
+  assert.deepEqual([s.bySource['correction-nudge'].recurBefore, s.bySource['correction-nudge'].recurAfter, s.bySource['correction-nudge'].fired], [1, 1, 1]);
+  assert.equal(s.bySource.harvest.lessons, 1); assert.equal(s.bySource.manual.lessons, 1);
+  assert.equal(s.graduated, 1); assert.equal(s.harvestOpen, 1); assert.equal(s.harvestRecorded, 1);
+  const all = stats.collect({ home, cwd: dir, days: 14, now });
+  assert.equal(all.selfImprovement.nudges, 2);
+  assert.match(stats.render(all), /Self-improvement[\s\S]*correction nudges 2: lesson recorded within 15 min after 1 \(50%\)[\s\S]*first-pass merge rate/);
+});
+
+test('boot never waits for the harvest scan: no cache -> no line now, a detached refresh is started', () => {
+  const dir = repo(); const home = mk();
+  const started = [];
+  assert.deepEqual(lessons.bannerLines(dir, { home, refreshHarvest: (p) => started.push(p) }), []);
+  assert.deepEqual(started, [dir]);
+});

package/core/.specialist/tools/ansuz-boot-fast.js

@@ -1021,6 +1021,7 @@ async function main() {
   // line above) so the query is scoped to the bound project when pinned.
   const wishesLine = formatWishesLine(await fetchOpenWishes(mcpBase, WISH_TIMEOUT_MS, IS_PINNED ? BASE : null));
   if (wishesLine) lines.push(wishesLine);
+  for (const l of handoffDocLines(BASE)) lines.push(l);
   for (const l of openCardLines()) lines.push(l);
   const landedLine = landedActiveCardsLine();
   if (landedLine) lines.push(landedLine);
@@ -1028,7 +1029,7 @@ async function main() {
   try { for (const l of require('./lessons').bannerLines(BASE)) lines.push(l); } catch { /* optional */ }
   const peerLines = await fetchPendingPeerLines(mcpBase, WISH_TIMEOUT_MS, IS_PINNED ? BASE : process.env.CLAUDE_PROJECT_DIR || process.cwd());
   for (const l of peerLines) lines.push(l);
-  lines.push('（boot 完成：依 Open cards 提議程；小修正直接做，中型工作開卡派工）');
+  lines.push('（boot 完成：' + (findHandoffDocs(BASE).length ? '先讀 → 標記的 handoff 全文，再' : '') + '依 Open cards 提議程；小修正直接做，中型工作開卡派工）');
   process.stdout.write(lines.join(String.fromCharCode(10)) + String.fromCharCode(10));
 }
 
@@ -1043,6 +1044,39 @@ if (require.main === module) {
   });
 }
 
+// Project handoff documents: markdown a previous session wrote for the next one. Standard place:
+// .kenaz/handoffs/*.md (ISBAR, created by handoff-doc.js); older hand-written ones are still found
+// as handoff*.md in .kenaz/, the project root or docs/. Read-only: nothing is archived or moved.
+// Newest first; the banner tells Ansuz to read the newest in full.
+const HANDOFF_DOC_DIRS = [['.kenaz/handoffs', /\.md$/i], ['.kenaz', /^handoff.*\.md$/i], ['', /^handoff.*\.md$/i], ['docs', /^handoff.*\.md$/i]];
+const HANDOFF_DOC_MAX = 3;
+function findHandoffDocs(base, now = Date.now()) {
+  const docs = [];
+  for (const [d, re] of HANDOFF_DOC_DIRS) {
+    let names = [];
+    try { names = fs.readdirSync(path.join(base, d)); } catch { continue; }
+    for (const n of names) {
+      if (!re.test(n)) continue;
+      const fp = path.join(base, d, n);
+      let st; try { st = fs.statSync(fp); } catch { continue; }
+      if (!st.isFile()) continue;
+      let title = '';
+      try { const m = fs.readFileSync(fp, 'utf8').slice(0, 4096).match(/^#\s+(.+)$/m); if (m) title = m[1].trim().slice(0, 100); } catch { /* unreadable */ }
+      docs.push({ rel: (d ? d + '/' : '') + n, mtimeMs: st.mtimeMs, ageDays: Math.floor((now - st.mtimeMs) / 86400000), title });
+    }
+  }
+  return docs.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+function handoffDocLines(base, now) {
+  const docs = findHandoffDocs(base, now);
+  if (!docs.length) return [];
+  const age = (n) => (n <= 0 ? 'today' : n + 'd ago');
+  const lines = ['📎 Project handoff (read the newest in full with Read BEFORE proposing the agenda; it overrides the card list where they disagree):'];
+  docs.slice(0, HANDOFF_DOC_MAX).forEach((h, i) => lines.push('  ' + (i === 0 ? '→ ' : '  ') + h.rel + '  (' + age(h.ageDays) + ')' + (h.title ? '  ' + h.title : '')));
+  if (docs.length > HANDOFF_DOC_MAX) lines.push('  … ' + (docs.length - HANDOFF_DOC_MAX) + ' older');
+  return lines;
+}
+
 // TASK_2404: active cards whose task branch is already an ancestor of origin/main (local remote-tracking
 // refs only -- no fetch at boot). Silent when none or when anything fails.
 function landedActiveCardsLine() {
@@ -1062,6 +1096,8 @@ function landedActiveCardsLine() {
 }
 
 module.exports = {
+  findHandoffDocs,
+  handoffDocLines,
   isOutsideAnyProject,
   harnessSessionIdFromEnv,
   hintNamesThisSession,

package/core/.specialist/tools/handoff-doc.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+'use strict';
+// Project handoff document (ISBAR) for the next session.
+//   node handoff-doc.js new --topic "<topic>" [--session <id>] [--project-path <dir>]
+//     creates <project>/.kenaz/handoffs/<YYYY-MM-DD-HHmm>-<slug>.md from the ISBAR template with the
+//     Identification section filled in, and prints its path; the writer then fills S/B/A/R.
+//   node handoff-doc.js latest [--project-path <dir>]   prints the newest handoff's path
+// ansuz-boot-fast.js lists .kenaz/handoffs/ newest first and tells Ansuz to read the newest in full.
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync } = require('child_process');
+
+const REL_DIR = path.join('.kenaz', 'handoffs');
+
+function slugify(topic) {
+  const s = String(topic || '').trim().toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '-').replace(/^-+|-+$/g, '').slice(0, 48);
+  return s || 'handoff';
+}
+
+function stamp(d) {
+  const p = (n) => String(n).padStart(2, '0');
+  return d.getFullYear() + '-' + p(d.getMonth() + 1) + '-' + p(d.getDate()) + '-' + p(d.getHours()) + p(d.getMinutes());
+}
+
+function git(projectPath, args) {
+  try { return execFileSync('git', args, { cwd: projectPath, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return ''; }
+}
+
+function template({ topic, session, projectPath, now }) {
+  const branch = git(projectPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const head = git(projectPath, ['rev-parse', '--short', 'HEAD']);
+  return [
+    '# Handoff: ' + topic,
+    '',
+    '## I · Identification',
+    '- 時間：' + now.toISOString(),
+    '- 專案：' + projectPath,
+    '- 撰寫者：Ansuz' + (session ? '（session ' + session + '）' : '') + '，節點 ' + os.hostname(),
+    '- 分支 / HEAD：' + (branch || '—') + ' @ ' + (head || '—'),
+    '',
+    '## S · Situation（現況）',
+    '- 一句話：現在在做什麼、做到哪裡',
+    '- 進行中的卡 / 分支 / worktree：',
+    '',
+    '## B · Background（背景）',
+    '- 用戶的決定與理由（原話優先）：',
+    '- 相關卡、commit、文件：',
+    '',
+    '## A · Assessment（評估）',
+    '- 已驗證（怎麼驗證的）：',
+    '- 未驗證 / 風險 / 阻塞：',
+    '',
+    '## R · Recommendation（建議）',
+    '- 下一個 session 的第一步：',
+    '- 待用戶決定的事：',
+    '',
+  ].join('\n');
+}
+
+function create(projectPath, topic, session, now = new Date()) {
+  const dir = path.join(projectPath, REL_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  let file = path.join(dir, stamp(now) + '-' + slugify(topic) + '.md');
+  for (let i = 2; fs.existsSync(file); i++) file = path.join(dir, stamp(now) + '-' + slugify(topic) + '-' + i + '.md');
+  fs.writeFileSync(file, template({ topic, session, projectPath, now }));
+  return file;
+}
+
+function latest(projectPath) {
+  const dir = path.join(projectPath, REL_DIR);
+  let names = [];
+  try { names = fs.readdirSync(dir).filter((n) => n.endsWith('.md')); } catch { return null; }
+  const withTime = names.map((n) => ({ f: path.join(dir, n), t: fs.statSync(path.join(dir, n)).mtimeMs }));
+  withTime.sort((a, b) => b.t - a.t);
+  return withTime.length ? withTime[0].f : null;
+}
+
+function main(argv, out = console.log, cwd = process.cwd()) {
+  const val = (k) => { const i = argv.indexOf('--' + k); return i >= 0 ? argv[i + 1] : undefined; };
+  const projectPath = path.resolve(val('project-path') || process.env.CLAUDE_PROJECT_DIR || cwd);
+  if (argv[0] === 'new') {
+    const topic = val('topic');
+    if (!topic) { out('usage: handoff-doc.js new --topic "<topic>" [--session <id>] [--project-path <dir>]'); return 2; }
+    out(create(projectPath, topic, val('session')));
+    return 0;
+  }
+  if (argv[0] === 'latest') { const f = latest(projectPath); out(f || 'no handoff in ' + path.join(projectPath, REL_DIR)); return f ? 0 : 1; }
+  out('usage: handoff-doc.js <new --topic "<topic>" [--session <id>] | latest> [--project-path <dir>]');
+  return 2;
+}
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));
+
+module.exports = { create, latest, slugify, template, main, REL_DIR };