@kienntpixon/dieu-phoi 0.5.3 → 0.6.1

package/lib/knowledge.cjs

@@ -0,0 +1,1002 @@
+'use strict';
+// `dieu-phoi knowledge ...` — per-project knowledge store (core 0.6.0).
+// s1: project identity (path, rekey). s2: the store itself — index.json + sections/<id>.md + history/, read with
+// get/list, written only by `merge --run <id>` (lock, tmp+rename, history, 40-line cap, sha/rev conflicts), and
+// cross-repo links (related: child|parent) for a parent repo whose sessions work in its child repos.
+// s3: freshness per section (core.computeFreshness in hook.cjs) on get/list/status, and the project_knowledge line of the start block.
+//
+// Store layout (<projects>/<name>-<sha8(key)>/):
+//   index.json            { schema, key, name, related: [{key,name,path,rel}], sections: [{id,title,tags,paths,sha,rev,updated,lines}] }
+//   sections/<id>.md      body only (<= 40 lines)
+//   history/<id>/r<rev>-<sha8>-<stamp>.md   the replaced body, first line a JSON comment with its index entry
+//   meta.json             { keys: [...] } (aliases written by rekey), knowledge.lock while a writer holds the store
+//   cache/freshness.json  freshness per HEAD (key: HEAD + index.json mtime/size, <= 12 HEADs), rebuildable; git errors not cached
+//
+// Delta (written by agents into a run dir as knowledge-delta*.md, merged at gate 3):
+//   repo: <path of the repo/worktree the delta was checked against>   (header, before the first `## `)
+//   head: <sha>                                                         (optional; else HEAD read from repo:)
+//   ## +<id>        new section          ## <id>     replace an existing one
+//   title: / tags: a, b / paths: glob, glob / base: <sha>#<rev>   (meta lines right under the heading)
+//   body...
+// merge is idempotent: it records the sha256 of every delta file it applied (meta.json `applied`) and skips that file
+// next time; a file whose text changed hashes differently and counts as new. A "+id" / stale-base section whose content
+// equals the current body or an older body kept in history/ counts as already merged ("same"), never a conflict.
+// A replacement must carry `base:` = the `base:` line `knowledge get` printed; if the section moved on since (another
+// session merged), the section is reported as a conflict and left untouched.
+
+const fs = require('fs');
+const path = require('path');
+const cp = require('child_process');
+const crypto = require('crypto');
+const core = require('../hook.cjs');
+const { repoOf } = require('./args.cjs');
+
+const KNOWLEDGE_HELP = `Cách dùng: dieu-phoi knowledge <lệnh> [--repo <đường dẫn>] [--json]
+
+  path [--json]          in thư mục kho knowledge của repo (cwd hoặc --repo; worktree/clone cùng repo ra cùng thư mục)
+                         --json: khoá, loại khoá (remote|git), tên, HEAD đọc từ file, alias, gợi ý rekey
+  rekey [--from <tên thư mục kho>]
+                         repo vừa có remote nên khoá đổi: ghi khoá mới thành alias của kho cũ (không đổi tên/di chuyển
+                         thư mục). Không --from thì tự lấy kho của khoá git-common-dir nếu có
+  list [--follow] [--dirty] [--json]
+                         các mục của kho (id, tiêu đề, số dòng, sha#rev, tags, paths) + repo liên quan (related),
+                         mỗi mục gắn ok / STALE / ? (độ tươi so với HEAD của worktree đang đứng)
+  status [--follow] [--dirty] [--no-cache] [--json]
+                         chỉ độ tươi: mục nào stale (file nào đổi sau sha của mục), mục nào không xác định (sha không
+                         có trong repo này…). Một tiến trình git (diff-tree --no-renames, pathspec = paths của các mục),
+                         cache theo HEAD đọc từ file. --dirty: thêm file chưa commit (git status -uno, tối đa 2 s,
+                         quá thì "chưa kiểm"). --no-cache: bỏ qua cache
+  get <id|từ khoá>... [--path <file>[,<file>]] [--follow] [--json]
+                         in đúng các mục cần: id khớp đúng, hoặc mọi từ khoá đều có trong id/tag/tiêu đề; --path: các
+                         mục có glob paths khớp file (đường dẫn trong repo); cả hai = giao. Mỗi mục in dòng
+                         "base: <sha>#<rev>" và độ tươi (STALE + file đã đổi / không xác định) — chép base vào delta
+                         khi sửa mục đó; --dirty như status. --follow: tra thêm kho cha (upstream).
+                         "children"/"upstream" chưa có trong kho thì được dựng từ related. Không mục nào khớp → exit 1
+  merge --run <id|thư mục run> [--task <id>[,<id>] [--untagged]] [--dry-run] [--json]
+                         gộp mọi knowledge-delta*.md của run (--task: chỉ knowledge-delta-<task_id>[-r<n>].md của các
+                         task đó, --untagged: thêm file không mang task_id; verdict accept tự gọi bước này) vào kho của repo ghi ở header "repo:" (không có thì
+                         --repo/cwd): khoá knowledge.lock, ghi tmp+rename, bản cũ vào history/, sha = HEAD của repo đó.
+                         "## +id" thêm mục (bắt buộc paths:), "## id" thay mục (bắt buộc base: <sha>#<rev>); base cũ
+                         → xung đột, không ghi đè; mục > 40 dòng bị từ chối. Có xung đột/từ chối → exit 2.
+                         Idempotent: file delta đã gộp (hash trong meta.json) và mục trùng một rev cũ trong history/ → "không đổi"
+  bootstrap [--children <mẫu tên>[,…]] [--json]
+                         chỉ đọc: liệt kê nguồn để seed kho (CLAUDE.md/README/AGENTS.md của repo, context-r/contract/
+                         handoff cũ trong runs có nhắc repo), mục đã có, mục nên có và mẫu delta. --children: repo anh em
+                         khớp mẫu tên (vd. pff-*,fff-*) để ghi mục children — không tạo kho cho chúng
+  link <đường dẫn repo khác> --rel child|parent [--remove]
+                         ghi liên kết cha–con vào related của cả hai kho (repo kia là con/cha của repo này)
+`;
+
+const MAX_LINES = 40;
+const INDEX_SCHEMA = 1;
+const ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const SYNTH_IDS = new Set(['children', 'upstream']);
+const LOCK_TRIES = 200; // x 50 ms = 10 s
+
+function sleepSync(ms) {
+  try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch (_) { /* busy-wait fallback not needed */ }
+}
+
+/** Run fn under a file lock (wx, stale after 5 min via core.acquireLock); { locked: true } when it stays busy. */
+function withLock(file, fn, tries) {
+  let got = false;
+  const n = tries || 60;
+  for (let i = 0; i < n && !got; i++) {
+    got = core.acquireLock(file);
+    if (!got) sleepSync(50);
+  }
+  if (!got) return { locked: true };
+  try { return { value: fn() }; } finally { try { fs.unlinkSync(file); } catch (_) { /* gone */ } }
+}
+
+function isDir(p) {
+  try { return fs.statSync(p).isDirectory(); } catch (_) { return false; }
+}
+
+const slash = (p) => String(p).replace(/\\/g, '/');
+
+function infoOf(opts, fallback) {
+  const start = repoOf(opts);
+  const info = core.resolveProject(start, { fallback });
+  if (!info) return { start, info: null };
+  return { start, info };
+}
+
+function notRepo(start) {
+  return { code: 1, out: `Không phải repo git: ${start} (dùng --repo <đường dẫn trong repo>).` };
+}
+
+function cmdPath(opts) {
+  const { start, info } = infoOf(opts, true);
+  if (!info) return notRepo(start);
+  const head = core.readHead(start);
+  const hint = info.rekey_from
+    ? `Repo đã có remote nhưng kho cũ "${info.rekey_from}" (khoá git-common-dir) chưa được nối: chạy \`dieu-phoi knowledge rekey\`.`
+    : null;
+  if (opts.json) {
+    return { code: 0, out: JSON.stringify(Object.assign({ path: start }, info, { head, rekey_hint: hint }), null, 2) };
+  }
+  if (hint) process.stderr.write(`${hint}\n`);
+  return { code: 0, out: info.dir };
+}
+
+function cmdRekey(opts) {
+  const { start, info } = infoOf(opts, true);
+  if (!info) return notRepo(start);
+  const store = core.projectsDir();
+  const from = typeof opts.from === 'string' ? opts.from : info.rekey_from;
+  if (opts.from !== undefined && typeof opts.from !== 'string') return { code: 1, out: '--from cần tên thư mục kho.' };
+  if (!from) {
+    return { code: 0, out: info.exists ? `Kho đã có (${info.dir}) — không cần rekey.` : 'Không có kho cũ nào để nối (thử --from <tên thư mục kho>).' };
+  }
+  if (!core.isStoreDirName(from) || !fs.statSync(path.join(store, from), { throwIfNoEntry: false })) {
+    return { code: 1, out: `Không thấy kho "${from}" trong ${store}.` };
+  }
+  if (info.exists && info.dir_name !== from) {
+    return { code: 1, out: `Khoá mới đã có kho riêng (${info.dir_name}) — hai kho tồn tại, rekey không tự gộp. Gộp tay hoặc xoá một bên.` };
+  }
+  if (info.exists && info.dir_name === from && info.alias) {
+    return { code: 0, out: `Đã nối từ trước: ${info.key} -> ${from}.` };
+  }
+  const r = withLock(path.join(store, 'aliases.lock'), () => {
+    const aliases = core.loadAliases();
+    aliases[info.key] = from;
+    core.writeFileAtomic(core.aliasesFile(), `${JSON.stringify(aliases, null, 2)}\n`);
+    const metaFile = path.join(store, from, 'meta.json');
+    const meta = core.readJsonFile(metaFile, {});
+    const keys = Array.isArray(meta.keys) ? meta.keys.slice() : [];
+    if (!keys.includes(info.key)) keys.push(info.key);
+    core.writeFileAtomic(metaFile, `${JSON.stringify(Object.assign({}, meta, { keys }), null, 2)}\n`);
+  });
+  if (r.locked) return { code: 1, out: 'aliases.json đang bị tiến trình khác khoá — thử lại.' };
+  return { code: 0, out: `Đã nối ${info.key} -> ${path.join(store, from).replace(/\\/g, '/')}` };
+}
+
+// ------------------------------------------------------------------ store: read
+
+/**
+ * index.json of a store dir: { exists, idx, error }. A file that exists but does not parse is an error (a writer must
+ * never replace it with an empty index and lose every section).
+ */
+function readIndex(dir) {
+  const file = path.join(dir, 'index.json');
+  let txt;
+  try { txt = fs.readFileSync(file, 'utf8'); } catch (e) {
+    if (e.code === 'ENOENT') return { exists: false, idx: null };
+    return { exists: true, idx: null, error: `không đọc được ${slash(file)}: ${e.message}` };
+  }
+  let idx;
+  try { idx = JSON.parse(txt.replace(/^/, '')); } catch (e) {
+    return { exists: true, idx: null, error: `index.json hỏng (${slash(file)}): ${e.message}` };
+  }
+  if (!idx || typeof idx !== 'object' || Array.isArray(idx)) return { exists: true, idx: null, error: `index.json không phải object: ${slash(file)}` };
+  if (!Array.isArray(idx.sections)) idx.sections = [];
+  if (!Array.isArray(idx.related)) idx.related = [];
+  return { exists: true, idx };
+}
+
+function newIndex(info) {
+  return { schema: INDEX_SCHEMA, key: info.key, name: info.name, related: [], sections: [] };
+}
+
+function sectionFile(dir, id) {
+  return path.join(dir, 'sections', `${id}.md`);
+}
+
+function readBody(dir, id) {
+  try { return fs.readFileSync(sectionFile(dir, id), 'utf8').replace(/\r\n/g, '\n').replace(/\n+$/, ''); } catch (_) { return null; }
+}
+
+/** Body line count by the same rule everywhere (merge's <= 40 limit, list, get): CRLF, CR or LF break a line; trailing blank lines do not count. */
+const LINE_BREAK = /\r\n|\r|\n/;
+function countLines(text) {
+  const s = String(text == null ? '' : text).replace(/(\r\n|\r|\n)+$/, '');
+  return s ? s.split(LINE_BREAK).length : 0;
+}
+
+/** True body lines of a stored section: counted from sections/<id>.md (what get prints), the index value only as a fallback. */
+function sectionLines(dir, s) {
+  const body = dir ? readBody(dir, s.id) : null;
+  return body == null ? (s.lines || 0) : countLines(body);
+}
+
+/** Store dir of a related entry: its own key dir, an alias of its key, or whatever its path resolves to now. */
+function storeDirOf(entry) {
+  if (!entry || typeof entry.key !== 'string') return null;
+  const store = core.projectsDir();
+  if (typeof entry.name === 'string') {
+    const own = core.keyDirName(entry.key, entry.name);
+    if (core.isStoreDirName(own) && isDir(path.join(store, own))) return path.join(store, own);
+  }
+  const a = core.loadAliases()[entry.key];
+  if (core.isStoreDirName(a) && isDir(path.join(store, a))) return path.join(store, a);
+  if (typeof entry.path === 'string' && isDir(entry.path)) {
+    const r = core.resolveProject(entry.path);
+    if (r && r.key === entry.key) return r.dir;
+  }
+  return null;
+}
+
+// globMatch and the freshness check live in hook.cjs (s3): the installed hook is one self-contained file.
+const { globMatch } = core;
+
+/** `--path` value -> repo-relative path (absolute and ./ ../ paths resolve against `start`); null when outside the repo. */
+function relInRepo(info, start, f) {
+  const p = slash(core.nativePath(String(f).trim()));
+  if (!(path.isAbsolute(p) || p.startsWith('./') || p.startsWith('../'))) return p.replace(/^\/+/, '');
+  if (!info.root) return null;
+  const rel = path.relative(path.resolve(info.root), path.resolve(start, p));
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return rel === '' ? '' : null;
+  return slash(rel);
+}
+
+// ------------------------------------------------------------------ get / list
+
+function tokensOf(s) {
+  return String(s).normalize('NFC').toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+}
+
+function termMatches(sec, term) {
+  const t = String(term).toLowerCase().trim();
+  if (!t) return false;
+  if (sec.id === t) return true;
+  // Word-prefix match: "ui" finds "Bẫy UI" / "ui-pitfalls" but not "build".
+  const words = tokensOf([sec.id, String(sec.title || ''), ...(sec.tags || []).map(String)].join(' '));
+  const toks = tokensOf(t);
+  return toks.length > 0 && toks.every((tok) => words.some((w) => w.startsWith(tok)));
+}
+
+/** Matching index entries (index order): ids/terms OR'ed, then AND'ed with --path files when both are given. */
+function selectSections(idx, terms, rels) {
+  return idx.sections.filter((s) => {
+    const byTerm = terms.length ? terms.some((t) => termMatches(s, t)) : true;
+    const byPath = rels.length ? rels.some((r) => (s.paths || []).some((g) => globMatch(g, r))) : true;
+    return byTerm && byPath;
+  });
+}
+
+function baseOf(sec) {
+  return `${sec.sha || 'none'}#${sec.rev || 0}`;
+}
+
+function shortSha(s) {
+  return s ? String(s).slice(0, 7) : '-';
+}
+
+function sectionOut(repo, sec, body, fr) {
+  const out = {
+    repo: repo.name, repo_rel: repo.rel || 'self', id: sec.id, title: sec.title, tags: sec.tags || [], paths: sec.paths || [],
+    sha: sec.sha || null, rev: sec.rev || 0, updated: sec.updated || null, lines: body ? countLines(body) : (sec.lines || 0), base: baseOf(sec), body,
+  };
+  const f = fr && fr.sections && fr.sections[sec.id];
+  if (f) {
+    out.fresh = f.state;
+    if (f.files) { out.stale = f.files; out.stale_count = f.n_files || f.files.length; }
+    if (f.why) out.fresh_why = f.why;
+    if (f.dirty) out.dirty = f.dirty;
+  }
+  return out;
+}
+
+/**
+ * Freshness of a store for the worktree around `start` (s3): at most one git process (diff-tree --no-renames over the
+ * sections' globs), cached by HEAD read from files; --dirty adds uncommitted files (git status -uno, 2 s timeout).
+ */
+function freshnessOf(storeDir, idx, start, opts) {
+  const g = start ? core.findGit(start) : null;
+  if (!g) {
+    const sections = {};
+    for (const s of idx.sections) sections[s.id] = { state: 'unknown', why: 'không thấy repo (đường dẫn đã mất?)' };
+    return { head: null, cached: false, sections, counts: core.freshCounts(sections) };
+  }
+  let head = core.readHead(g);
+  if (head && head.unsupported) { const sha = headShaOf(start); if (sha) head = { sha, branch: null }; }
+  const fr = core.computeFreshness({ dir: storeDir, idx, root: g.root, head, cache: !opts['no-cache'] });
+  if (opts.dirty) fr.dirty_check = core.addDirty(fr, idx, g.root);
+  return fr;
+}
+
+function freshLine(s) {
+  if (s.fresh === 'stale') return `STALE — ${s.stale_count} file đổi sau sha của mục: ${core.shortFileList(s.stale, 5)} (kiểm lại trước khi dùng)`;
+  if (s.fresh === 'unknown') return `độ tươi: không xác định — ${s.fresh_why}`;
+  if (s.fresh === 'fresh') return 'độ tươi: tươi';
+  return null;
+}
+
+function synthSection(id, idx) {
+  const want = id === 'children' ? 'child' : 'parent';
+  const rel = idx.related.filter((r) => r.rel === want);
+  if (!rel.length) return null;
+  const body = rel.map((r) => `- ${r.name} — ${r.path || '?'} (khoá ${r.key})`).join('\n')
+    + (want === 'parent' ? '\n\nThứ chép từ repo cha (toolset, kit) tra ở kho cha: `dieu-phoi knowledge get <id> --follow`, hoặc `--repo <đường dẫn cha>`.' : '');
+  return { id, title: want === 'child' ? 'Repo con' : 'Repo cha (upstream)', tags: ['related'], paths: [], sha: null, rev: 0, updated: null, lines: body.split('\n').length, synthesized: true, body };
+}
+
+function renderSection(s) {
+  const meta = [`sha ${shortSha(s.sha)}`, `rev ${s.rev}`, s.updated ? String(s.updated).slice(0, 10) : null,
+    s.tags.length ? `tags: ${s.tags.join(', ')}` : null, s.paths.length ? `paths: ${s.paths.join(', ')}` : null].filter(Boolean);
+  const head = [`## ${s.id} — ${s.title || s.id}`, meta.join(' · ')];
+  if (s.synthesized) head.push('(dựng từ related — chưa có mục lưu trong kho)');
+  else {
+    head.push(`base: ${s.base}`);
+    const fl = freshLine(s);
+    if (fl) head.push(fl);
+    if (s.dirty && s.dirty.length) head.push(`chưa commit: ${core.shortFileList(s.dirty, 5)}`);
+  }
+  return `${head.join('\n')}\n\n${s.body}`;
+}
+
+function repoLine(r) {
+  const tag = r.rel && r.rel !== 'self' ? ` (${r.rel === 'parent' ? 'cha' : r.rel})` : '';
+  return `repo: ${r.name}${tag} — ${slash(r.dir)}`;
+}
+
+function parentsOf(idx) {
+  const out = [];
+  for (const r of idx.related.filter((x) => x.rel === 'parent')) {
+    const dir = storeDirOf(r);
+    if (!dir) { out.push({ name: r.name, key: r.key, dir: null, path: r.path, rel: 'parent', idx: null }); continue; }
+    const ri = readIndex(dir);
+    out.push({ name: r.name, key: r.key, dir, path: r.path, rel: 'parent', idx: ri.idx, error: ri.error });
+  }
+  return out;
+}
+
+function cmdGet(opts) {
+  const { start, info } = infoOf(opts, false);
+  if (!info) return notRepo(start);
+  const terms = opts._.map(String).filter((t) => t.trim());
+  let rels = [];
+  if (opts.path !== undefined) {
+    if (typeof opts.path !== 'string' || !opts.path.trim()) return { code: 1, out: '--path cần đường dẫn file.' };
+    for (const f of opts.path.split(',').map((x) => x.trim()).filter(Boolean)) {
+      const r = relInRepo(info, start, f);
+      if (r == null) return { code: 1, out: `--path nằm ngoài repo: ${f}` };
+      rels.push(r);
+    }
+  }
+  if (!terms.length && !rels.length) return { code: 1, out: `Cần <id|từ khoá> hoặc --path.\n\n${KNOWLEDGE_HELP.trimEnd()}` };
+  const ri = readIndex(info.dir);
+  if (ri.error) return { code: 1, out: ri.error };
+  if (!ri.exists) return { code: 1, out: `Kho chưa có mục nào: ${info.dir} (chưa merge delta nào cho repo này).` };
+  const self = { name: info.name, key: info.key, dir: info.dir, rel: 'self' };
+  const results = [];
+  const hit = new Set();
+  const picked = selectSections(ri.idx, terms, rels);
+  const fr = picked.length ? freshnessOf(info.dir, ri.idx, start, opts) : null;
+  for (const sec of picked) {
+    results.push(sectionOut(self, sec, readBody(info.dir, sec.id) || '', fr));
+    terms.forEach((t) => { if (termMatches(sec, t)) hit.add(t); });
+  }
+  if (!rels.length) {
+    for (const t of terms) {
+      const id = t.toLowerCase().trim();
+      if (SYNTH_IDS.has(id) && !ri.idx.sections.some((s) => s.id === id)) {
+        const s = synthSection(id, ri.idx);
+        if (s) { results.push(Object.assign(sectionOut(self, s, s.body), { synthesized: true })); hit.add(t); }
+      }
+    }
+  }
+  const followed = [];
+  if (opts.follow && terms.length) {
+    for (const p of parentsOf(ri.idx)) {
+      followed.push({ name: p.name, dir: p.dir, error: p.error || (p.dir ? null : 'không thấy kho') });
+      if (!p.idx) continue;
+      const pPicked = selectSections(p.idx, terms, []);
+      // The parent's freshness is checked against the parent's own checkout (related.path), refreshed on first get.
+      const pfr = pPicked.length ? freshnessOf(p.dir, p.idx, p.path && isDir(core.nativePath(p.path)) ? core.nativePath(p.path) : null, opts) : null;
+      for (const sec of pPicked) {
+        results.push(sectionOut(p, sec, readBody(p.dir, sec.id) || '', pfr));
+        terms.forEach((t) => { if (termMatches(sec, t)) hit.add(t); });
+      }
+    }
+  }
+  const missing = terms.filter((t) => !hit.has(t));
+  const code = results.length ? 0 : 1;
+  if (opts.json) {
+    const freshness = fr ? { head: fr.head, cached: fr.cached, counts: fr.counts, error: fr.error || null, dirty_check: fr.dirty_check || null } : null;
+    return { code, out: JSON.stringify({ repo: { key: info.key, name: info.name, dir: info.dir }, freshness, followed, sections: results, missing }, null, 2) };
+  }
+  if (!results.length) {
+    const ids = ri.idx.sections.map((s) => s.id);
+    return { code, out: `Không có mục khớp (${[...terms, ...rels.map((r) => `--path ${r}`)].join(', ')}) trong ${info.dir}.${ids.length ? ` Có: ${ids.join(', ')}.` : ''}` };
+  }
+  const parts = [];
+  let lastRepo = null;
+  for (const s of results) {
+    const r = s.repo_rel === 'self' ? self : followed.find((f) => f.name === s.repo) || { name: s.repo, dir: '?' };
+    const tag = `${s.repo_rel}:${s.repo}`;
+    if (tag !== lastRepo) { parts.push(repoLine(Object.assign({}, r, { rel: s.repo_rel }))); lastRepo = tag; }
+    parts.push(renderSection(s));
+  }
+  if (missing.length) parts.push(`(không khớp: ${missing.join(', ')})`);
+  for (const f of followed.filter((x) => x.error)) parts.push(`(kho cha ${f.name}: ${f.error})`);
+  return { code, out: parts.join('\n\n') };
+}
+
+const FRESH_MARK = { fresh: 'ok   ', stale: 'STALE', unknown: '?    ' };
+
+function listLines(idx, fr, dir) {
+  return idx.sections.map((s) => {
+    const f = fr && fr.sections && fr.sections[s.id];
+    const mark = f ? `${FRESH_MARK[f.state] || '?    '} ` : '';
+    return `  ${mark}${s.id.padEnd(18)} ${String(sectionLines(dir, s)).padStart(3)}d  ${shortSha(s.sha)}#${s.rev || 0}  ${String(s.updated || '').slice(0, 10)}  ${s.title || ''}`
+      + `${(s.tags || []).length ? `  [${s.tags.join(', ')}]` : ''}${(s.paths || []).length ? `  ${s.paths.join(', ')}` : ''}`;
+  });
+}
+
+function freshHeader(fr, n) {
+  if (!fr) return '';
+  const head = fr.head ? `HEAD ${fr.head.slice(0, 7)}${fr.branch ? ` (${fr.branch})` : ''}` : 'HEAD ?';
+  return `${head} · ${core.knowledgeSummary(fr, n)} · ${fr.cached ? 'cache' : `tính mới${fr.ms_git ? ` (git ${fr.ms_git} ms)` : ''}`}${fr.error ? ` · git lỗi: ${fr.error}` : ''}`;
+}
+
+/** Details under list/status: stale files, unknown reasons, uncommitted files (--dirty). */
+function freshDetails(idx, fr) {
+  const out = [];
+  if (!fr) return out;
+  for (const s of idx.sections) {
+    const f = fr.sections[s.id];
+    if (!f) continue;
+    if (f.state === 'stale') out.push(`    ${s.id}: ${f.n_files || f.files.length} file đổi — ${core.shortFileList(f.files, 5)}`);
+    else if (f.state === 'unknown') out.push(`    ${s.id}: không xác định — ${f.why}`);
+    if (f.dirty) out.push(`    ${s.id}: chưa commit — ${core.shortFileList(f.dirty, 5)}`);
+  }
+  if (fr.dirty_check && !fr.dirty_check.checked) out.push(`    (--dirty: ${fr.dirty_check.why})`);
+  return out;
+}
+
+function parentFresh(p, opts) {
+  if (!p.idx) return null;
+  const pp = p.path && isDir(core.nativePath(p.path)) ? core.nativePath(p.path) : null;
+  return freshnessOf(p.dir, p.idx, pp, opts);
+}
+
+/** list (all sections + freshness marks) and status (freshness only, with the stale files) share this. */
+function listOrStatus(opts, status) {
+  const { start, info } = infoOf(opts, false);
+  if (!info) return notRepo(start);
+  const ri = readIndex(info.dir);
+  if (ri.error) return { code: 1, out: ri.error };
+  const idx = ri.idx || newIndex(info);
+  const fr = ri.exists ? freshnessOf(info.dir, idx, start, opts) : null;
+  const parents = opts.follow ? parentsOf(idx) : [];
+  const pfr = parents.map((p) => parentFresh(p, opts));
+  if (opts.json) {
+    const fj = (f) => (f ? { head: f.head, branch: f.branch || null, cached: f.cached, counts: f.counts, error: f.error || null, dirty_check: f.dirty_check || null, sections: f.sections } : null);
+    return {
+      code: 0,
+      out: JSON.stringify({
+        repo: { key: info.key, name: info.name, dir: info.dir, exists: ri.exists }, related: idx.related, sections: idx.sections.map((s) => Object.assign({}, s, { lines: sectionLines(info.dir, s) })), freshness: fj(fr),
+        parents: parents.map((p, i) => ({ name: p.name, key: p.key, dir: p.dir, sections: p.idx ? p.idx.sections.map((s) => Object.assign({}, s, { lines: sectionLines(p.dir, s) })) : [], freshness: fj(pfr[i]), error: p.error || null })),
+      }, null, 2),
+    };
+  }
+  const out = [`${repoLine({ name: info.name, dir: info.dir })} — ${ri.exists ? `${idx.sections.length} mục` : 'chưa có kho'}`];
+  if (fr) out.push(`  ${freshHeader(fr, idx.sections.length)}`);
+  if (!status) out.push(...listLines(idx, fr, info.dir));
+  out.push(...freshDetails(idx, fr));
+  for (const r of idx.related) out.push(`  related: ${r.rel === 'parent' ? 'cha' : 'con'} ${r.name} — ${r.path || '?'}`);
+  parents.forEach((p, i) => {
+    out.push(repoLine({ name: p.name, dir: p.dir || '?', rel: 'parent' }) + (p.idx ? ` — ${p.idx.sections.length} mục` : ` — ${p.error || 'không thấy kho'}`));
+    if (!p.idx) return;
+    out.push(`  ${freshHeader(pfr[i], p.idx.sections.length)}`);
+    if (!status) out.push(...listLines(p.idx, pfr[i], p.dir));
+    out.push(...freshDetails(p.idx, pfr[i]));
+  });
+  return { code: 0, out: out.join('\n') };
+}
+
+function cmdList(opts) {
+  return listOrStatus(opts, false);
+}
+
+function cmdStatus(opts) {
+  return listOrStatus(opts, true);
+}
+
+// ------------------------------------------------------------------ delta parsing
+
+const META_RE = /^(title|tags|paths|base)\s*:\s*(.*?)\s*$/i;
+
+function unquote(v) {
+  return String(v).trim().replace(/^[`"'](.*)[`"']$/, '$1').trim();
+}
+
+function splitList(v, lower) {
+  return String(v).split(/[,\s]+/).map((x) => unquote(x)).filter(Boolean).map((x) => (lower ? x.toLowerCase() : slash(x)));
+}
+
+/** Parse a delta file: { repo, head, sections: [{ add, rawId, id, title?, tags?, paths?, base?, body, lines }] }. */
+function parseDelta(text) {
+  const lines = String(text).replace(/^/, '').split(LINE_BREAK);
+  const out = { repo: null, head: null, sections: [] };
+  let cur = null;
+  let fence = false;
+  for (const line of lines) {
+    if (/^\s*(```|~~~)/.test(line)) fence = !fence;
+    const h = !fence && /^##\s+(\+)?\s*(.+?)\s*$/.exec(line); // a heading that is not a valid id is rejected later
+    if (h) {
+      cur = { add: !!h[1], rawId: h[2], raw: [] };
+      out.sections.push(cur);
+      continue;
+    }
+    if (cur) { cur.raw.push(line); continue; }
+    const m = /^\s*(repo|head)\s*:\s*(.+?)\s*$/i.exec(line);
+    if (m && !out[m[1].toLowerCase()]) out[m[1].toLowerCase()] = unquote(m[2].replace(/[.;,]+$/, '')).replace(/[.;,]+$/, '');
+  }
+  for (const s of out.sections) {
+    s.id = s.rawId.toLowerCase();
+    let i = 0;
+    while (i < s.raw.length && !s.raw[i].trim()) i++;
+    for (; i < s.raw.length; i++) {
+      const m = META_RE.exec(s.raw[i]);
+      if (!m) break;
+      const k = m[1].toLowerCase();
+      if (k === 'title') s.title = unquote(m[2]);
+      else if (k === 'tags') s.tags = splitList(m[2], true);
+      else if (k === 'paths') s.paths = splitList(m[2], false);
+      else s.base = unquote(m[2]);
+    }
+    const body = s.raw.slice(i).map((l) => l.replace(/\s+$/, ''));
+    while (body.length && !body[0]) body.shift();
+    while (body.length && !body[body.length - 1]) body.pop();
+    s.body = body.join('\n');
+    s.lines = countLines(s.body);
+    delete s.raw;
+  }
+  return out;
+}
+
+// ------------------------------------------------------------------ merge
+
+function headShaOf(dir) {
+  const h = core.readHead(dir);
+  if (h && h.sha) return h.sha;
+  if (h && h.unsupported) {
+    const r = cp.spawnSync('git', ['rev-parse', 'HEAD'], { cwd: dir, encoding: 'utf8', windowsHide: true, timeout: 10000 });
+    const v = r.status === 0 ? r.stdout.trim() : '';
+    if (/^[0-9a-f]{40,64}$/i.test(v)) return v.toLowerCase();
+  }
+  return null;
+}
+
+function runDirOf(v) {
+  if (typeof v !== 'string' || !v.trim()) return { error: '--run cần id run hoặc thư mục run.' };
+  const s = core.nativePath(v.trim());
+  if (/[\\/]/.test(s) || path.isAbsolute(s)) {
+    const p = path.resolve(s);
+    return isDir(p) ? { dir: p } : { error: `Không thấy thư mục run: ${p}` };
+  }
+  if (!/^[A-Za-z0-9_-]+$/.test(s)) return { error: `id run không hợp lệ: ${v}` };
+  const p = path.join(core.runsDir(), s);
+  return isDir(p) ? { dir: p } : { error: `Không thấy run ${s} (${slash(p)}).` };
+}
+
+/** Task id a delta file belongs to: knowledge-delta-<task_id>[-r<n>].md (8 chars a-z0-9); null = untagged. */
+function deltaTaskOf(file) {
+  const m = /^knowledge-delta-([a-z0-9]{8})(?:-r\d+)?\.md$/i.exec(path.basename(file));
+  return m ? m[1].toLowerCase() : null;
+}
+
+/**
+ * Delta files of a run, oldest round first. filter: { tasks: Set|null, untagged: bool } — with tasks, only files
+ * tagged with one of them (plus untagged ones when untagged is true).
+ */
+function deltaFiles(runDir, filter) {
+  const num = (f) => { const m = /-r(\d+)\.md$/i.exec(f); return m ? Number(m[1]) : 0; };
+  return fs.readdirSync(runDir)
+    .filter((f) => /^knowledge-delta.*\.md$/i.test(f))
+    .filter((f) => {
+      if (!filter || !filter.tasks) return true;
+      const t = deltaTaskOf(f);
+      return t ? filter.tasks.has(t) : !!filter.untagged;
+    })
+    .sort((a, b) => num(a) - num(b) || a.localeCompare(b))
+    .map((f) => path.join(runDir, f));
+}
+
+function taskFilterOf(opts) {
+  if (typeof opts.task !== 'string' || !opts.task.trim()) return null;
+  return { tasks: new Set(opts.task.split(',').map((x) => x.trim().toLowerCase()).filter(Boolean)), untagged: !!opts.untagged };
+}
+
+function sameContent(cur, body, next) {
+  const eqList = (a, b) => JSON.stringify(a || []) === JSON.stringify(b || []);
+  return cur.body === body && (cur.title || '') === (next.title || '') && eqList(cur.tags, next.tags) && eqList(cur.paths, next.paths);
+}
+
+const APPLIED_MAX = 300;
+
+/** sha256 of the delta text, BOM and CRLF normalised so a CRLF checkout hashes like the LF original. */
+function deltaHash(text) {
+  return crypto.createHash('sha256').update(String(text).replace(/^/, '').replace(/\r\n?/g, '\n')).digest('hex');
+}
+
+function appliedOf(dir) {
+  const meta = core.readJsonFile(path.join(dir, 'meta.json'), {}) || {};
+  return Array.isArray(meta.applied) ? meta.applied : [];
+}
+
+/** Add one applied-delta entry to meta.json (caller holds the store lock). */
+function recordApplied(dir, info, entry) {
+  ensureMeta(dir, info);
+  const file = path.join(dir, 'meta.json');
+  const meta = core.readJsonFile(file, {}) || {};
+  const applied = (Array.isArray(meta.applied) ? meta.applied : []).filter((a) => a && a.sha256 !== entry.sha256);
+  applied.push(entry);
+  core.writeFileAtomic(file, `${JSON.stringify(Object.assign({}, meta, { applied: applied.slice(-APPLIED_MAX) }), null, 2)}\n`);
+}
+
+/** Older revisions of a section kept in history/<id>/: [{ rev, title, tags, paths, body }]. */
+function historyRevs(dir, id) {
+  const hd = path.join(dir, 'history', id);
+  let names;
+  try { names = fs.readdirSync(hd); } catch (_) { return []; }
+  const out = [];
+  for (const n of names) {
+    if (!/\.md$/i.test(n)) continue;
+    let txt;
+    try { txt = fs.readFileSync(path.join(hd, n), 'utf8').replace(/\r\n/g, '\n'); } catch (_) { continue; }
+    const m = /^<!-- knowledge-history (\{.*\}) -->\n/.exec(txt);
+    let head = null;
+    try { head = m ? JSON.parse(m[1]) : null; } catch (_) { head = null; }
+    if (!head) continue;
+    out.push({ rev: head.rev || 0, title: head.title, tags: head.tags, paths: head.paths, body: txt.slice(m[0].length).replace(/\n+$/, '') });
+  }
+  return out;
+}
+
+/** The older revision whose content equals the delta section's, or null: a delta merged before is recognised, not a conflict. */
+function mergedBefore(dir, id, body, next) {
+  return historyRevs(dir, id).find((h) => sameContent(h, body, next)) || null;
+}
+
+function stamp(d) {
+  return d.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+}
+
+/** Validate a delta section against the current index (no writes). Returns the planned outcome. */
+function planSection(s, idx, dir, seen) {
+  if (!ID_RE.test(s.id)) return { op: 'reject', why: `id không hợp lệ "${s.rawId}" (a-z 0-9 . _ -, ≤ 64 ký tự)` };
+  if (seen.has(s.id)) return { op: 'reject', why: 'trùng id trong cùng delta' };
+  seen.add(s.id);
+  if (!s.body) return { op: 'reject', why: 'thân mục rỗng' };
+  if (s.lines > MAX_LINES) return { op: 'reject', why: `${s.lines} dòng > ${MAX_LINES}` };
+  const cur = idx.sections.find((x) => x.id === s.id);
+  const curBody = cur ? readBody(dir, s.id) : null;
+  if (s.add) {
+    const next = { title: s.title || s.id, tags: s.tags || [], paths: s.paths || [] };
+    if (!next.paths.length) return { op: 'reject', why: 'mục mới phải có paths: (glob file mà mục nói tới)' };
+    if (cur) {
+      if (sameContent({ body: curBody, title: cur.title, tags: cur.tags, paths: cur.paths }, s.body, next)) return { op: 'same', cur };
+      const old = mergedBefore(dir, s.id, s.body, next);
+      if (old) return { op: 'same', cur, why: `khớp rev ${old.rev} cũ, đã gộp trước đó` };
+      return { op: 'conflict', cur, why: `mục đã có (rev ${cur.rev || 0}, ${String(cur.updated || '').slice(0, 19)}) — phiên khác vừa thêm; get rồi sửa thành "## ${s.id}" kèm base` };
+    }
+    return { op: 'add', next };
+  }
+  if (!cur) return { op: 'reject', why: `chưa có mục ${s.id} để thay (thêm mới dùng "## +${s.id}")` };
+  const next = { title: s.title || cur.title || s.id, tags: s.tags || cur.tags || [], paths: s.paths || cur.paths || [] };
+  if (!next.paths.length) return { op: 'reject', why: 'mục phải có paths:' };
+  if (sameContent({ body: curBody, title: cur.title, tags: cur.tags, paths: cur.paths }, s.body, next)) return { op: 'same', cur };
+  const m = /^([0-9a-f]{7,64}|none)(?:#(\d+))?$/i.exec(String(s.base || '').trim());
+  const merged = () => {
+    const old = mergedBefore(dir, s.id, s.body, next);
+    return old ? { op: 'same', cur, why: `khớp rev ${old.rev} cũ, đã gộp trước đó` } : null;
+  };
+  if (!m) return merged() || { op: 'conflict', cur, why: `thiếu base: (chép dòng "base: ${baseOf(cur)}" từ knowledge get rồi kiểm lại nội dung)` };
+  const bsha = m[1].toLowerCase();
+  const csha = String(cur.sha || 'none').toLowerCase();
+  const shaOk = bsha === 'none' ? csha === 'none' : csha.startsWith(bsha);
+  const revOk = m[2] === undefined || Number(m[2]) === (cur.rev || 0);
+  if (!shaOk || !revOk) {
+    return merged() || { op: 'conflict', cur, why: `base ${shortSha(bsha)}#${m[2] === undefined ? '?' : m[2]} ≠ hiện tại ${baseOf(Object.assign({}, cur, { sha: shortSha(cur.sha) }))} (cập nhật ${String(cur.updated || '').slice(0, 19)}) — đọc lại bằng get, sửa delta rồi merge lại` };
+  }
+  return { op: 'replace', cur, curBody, next };
+}
+
+/** Apply one parsed delta to a store (caller holds the lock unless dry). Returns per-section results. */
+function applyDelta(delta, info, sha, dry, src) {
+  const dir = info.dir;
+  const ri = readIndex(dir);
+  if (ri.error) return { error: ri.error };
+  const idx = ri.idx || newIndex(info);
+  if (src && appliedOf(dir).some((a) => a && a.sha256 === src.hash)) {
+    return { results: delta.sections.map((s) => ({ id: s.id || s.rawId, op: 'same', lines: s.lines, why: 'file delta đã gộp trước đó (cùng nội dung), bỏ qua' })), skipped: true };
+  }
+  const delay = Number(process.env.DIEU_PHOI_TEST_KNOWLEDGE_LOCK_DELAY_MS || 0);
+  if (delay > 0 && !dry) sleepSync(delay); // test hook: widen the read-modify-write window to prove the lock
+  const now = new Date();
+  const results = [];
+  const seen = new Set();
+  let changed = false;
+  for (const s of delta.sections) {
+    const p = planSection(s, idx, dir, seen);
+    const r = { id: s.id || s.rawId, op: p.op, lines: s.lines };
+    if (p.why) r.why = p.why;
+    if (p.op === 'add' || p.op === 'replace') {
+      const rev = p.op === 'add' ? 1 : (p.cur.rev || 0) + 1;
+      const entry = { id: s.id, title: p.next.title, tags: p.next.tags, paths: p.next.paths, sha, rev, updated: now.toISOString(), lines: s.lines };
+      r.rev = rev;
+      if (p.op === 'replace') r.from_rev = p.cur.rev || 0;
+      if (!dry) {
+        if (p.op === 'replace' && p.curBody != null) {
+          const hist = path.join(dir, 'history', s.id, `r${p.cur.rev || 0}-${shortSha(p.cur.sha)}-${stamp(now)}.md`);
+          const head = JSON.stringify(Object.assign({}, p.cur, { replaced: now.toISOString(), replaced_by_sha: sha }));
+          core.writeFileAtomic(hist, `<!-- knowledge-history ${head} -->\n${p.curBody}\n`);
+        }
+        core.writeFileAtomic(sectionFile(dir, s.id), `${s.body}\n`);
+      }
+      const at = idx.sections.findIndex((x) => x.id === s.id);
+      if (at >= 0) idx.sections[at] = entry; else idx.sections.push(entry);
+      changed = true;
+    }
+    results.push(r);
+  }
+  if (changed && !dry) {
+    idx.schema = INDEX_SCHEMA;
+    idx.key = info.key;
+    idx.name = idx.name || info.name;
+    core.writeFileAtomic(path.join(dir, 'index.json'), `${JSON.stringify(idx, null, 2)}\n`);
+    ensureMeta(dir, info);
+  }
+  if (changed && !dry && src && !results.some((r) => r.op === 'conflict' || r.op === 'reject')) {
+    recordApplied(dir, info, { sha256: src.hash, file: src.file, run: src.run, at: now.toISOString() });
+  }
+  return { results };
+}
+
+function ensureMeta(dir, info) {
+  const file = path.join(dir, 'meta.json');
+  const meta = core.readJsonFile(file, {}) || {};
+  const keys = Array.isArray(meta.keys) ? meta.keys.slice() : [];
+  if (keys.includes(info.key) && meta.created) return;
+  if (!keys.includes(info.key)) keys.push(info.key);
+  core.writeFileAtomic(file, `${JSON.stringify(Object.assign({ created: new Date().toISOString(), name: info.name }, meta, { keys }), null, 2)}\n`);
+}
+
+const OP_MARK = { add: '+', replace: '~', same: '=', conflict: '!', reject: 'x' };
+
+function describe(r) {
+  if (r.op === 'add') return `+ ${r.id} (${r.lines} dòng, rev 1)`;
+  if (r.op === 'replace') return `~ ${r.id} (rev ${r.from_rev} → ${r.rev}, ${r.lines} dòng)`;
+  if (r.op === 'same') return `= ${r.id} (không đổi${r.why ? `: ${r.why}` : ''})`;
+  if (r.op === 'conflict') return `! ${r.id} XUNG ĐỘT: ${r.why}`;
+  return `${OP_MARK[r.op] || '?'} ${r.id} BỊ TỪ CHỐI: ${r.why}`;
+}
+
+function cmdMerge(opts) {
+  const rd = runDirOf(opts.run);
+  if (rd.error) return { code: 1, out: rd.error };
+  const filter = taskFilterOf(opts);
+  const files = deltaFiles(rd.dir, filter);
+  if (!files.length) return { code: 1, out: `Run ${slash(rd.dir)} không có knowledge-delta*.md${filter ? ` của task ${Array.from(filter.tasks).join(',')}` : ''}.` };
+  const dry = !!opts['dry-run'];
+  const report = [];
+  const totals = { add: 0, replace: 0, same: 0, conflict: 0, reject: 0, error: 0 };
+  for (const file of files) {
+    const rep = { file: slash(file) };
+    report.push(rep);
+    let delta;
+    let src = null;
+    try {
+      const text = fs.readFileSync(file, 'utf8');
+      delta = parseDelta(text);
+      src = { hash: deltaHash(text), file: path.basename(file), run: path.basename(rd.dir) };
+    } catch (e) { rep.error = `không đọc được: ${e.message}`; totals.error++; continue; }
+    if (!delta.sections.length) { rep.error = 'không có mục "## <id>" nào'; totals.error++; continue; }
+    let target = null;
+    if (delta.repo) {
+      const p = path.resolve(core.nativePath(delta.repo));
+      if (isDir(p)) target = p;
+      else if (opts.repo !== undefined) { target = repoOf(opts); rep.note = `repo: ${delta.repo} không còn — dùng --repo`; } else {
+        rep.error = `repo: ${delta.repo} không tồn tại (worktree đã xoá?) — chạy lại với --repo <đường dẫn repo>`; totals.error++; continue;
+      }
+    } else target = repoOf(opts);
+    const info = core.resolveProject(target);
+    if (!info) { rep.error = `không phải repo git: ${slash(target)}`; totals.error++; continue; }
+    let sha = null;
+    if (delta.head) {
+      if (!/^[0-9a-f]{7,64}$/i.test(delta.head)) { rep.error = `head: không phải sha: ${delta.head}`; totals.error++; continue; }
+      sha = delta.head.toLowerCase();
+    } else sha = headShaOf(target);
+    if (!sha) { rep.error = `không xác định được HEAD của ${slash(target)} (repo chưa có commit?) — thêm dòng "head: <sha>" vào delta`; totals.error++; continue; }
+    Object.assign(rep, { repo: slash(target), store: info.dir, key: info.key, sha });
+    let out;
+    if (dry) out = applyDelta(delta, info, sha, true, src);
+    else {
+      const lk = withLock(path.join(info.dir, 'knowledge.lock'), () => applyDelta(delta, info, sha, false, src), LOCK_TRIES);
+      out = lk.locked ? { error: `kho đang bị khoá quá ${LOCK_TRIES * 50 / 1000} s (${slash(path.join(info.dir, 'knowledge.lock'))}) — thử lại` } : lk.value;
+    }
+    if (out.error) { rep.error = out.error; totals.error++; continue; }
+    rep.sections = out.results;
+    for (const r of out.results) totals[r.op]++;
+  }
+  const code = totals.conflict || totals.reject || totals.error ? 2 : 0;
+  if (opts.json) return { code, out: JSON.stringify({ run: slash(rd.dir), dry_run: dry, totals, deltas: report }, null, 2) };
+  const lines = [];
+  if (dry) lines.push('(dry-run — không ghi gì)');
+  for (const rep of report) {
+    const name = path.basename(rep.file);
+    if (rep.error) { lines.push(`${name}: LỖI — ${rep.error}`); continue; }
+    lines.push(`${name} → ${rep.store} (sha ${shortSha(rep.sha)})${rep.note ? ` [${rep.note}]` : ''}`);
+    for (const r of rep.sections) lines.push(`  ${describe(r)}`);
+  }
+  lines.push(`Tổng: ${totals.add} thêm, ${totals.replace} thay, ${totals.same} không đổi, ${totals.conflict} xung đột, ${totals.reject} từ chối${totals.error ? `, ${totals.error} file lỗi` : ''}.`);
+  return { code, out: lines.join('\n') };
+}
+
+// ------------------------------------------------------------------ bootstrap
+
+const BOOT_SECTIONS = [
+  ['build-test', 'lệnh build/test/lint, thời gian chạy, test nào chậm/flaky'],
+  ['ports-resources', 'cổng, DB, thư mục output dùng chung, tiến trình nền — thứ hai phiên có thể tranh nhau'],
+  ['conventions', 'quy ước code/commit/nhánh/worktree, file không được sửa'],
+  ['pitfalls', 'bẫy đã gặp (kèm cách tránh)'],
+  ['env-secrets', 'TÊN biến môi trường/file cấu hình cần có (không ghi giá trị)'],
+  ['arch-<module>', 'vài dòng định hướng + tên project trong codebase-memory-mcp (không chép cấu trúc code)'],
+];
+const BOOT_DOCS = /^(claude|agents|readme|contributing|contract)(\.[a-z]+)?\.md$/i;
+const BOOT_RUN_FILE = /^(context-r\d*.*|contract.*|dp-out-.*-plan.*|handoff-.*)\.md$/i;
+const BOOT_MAX_RUNS = 15;
+const BOOT_SKIP_DIR = /^(node_modules|\.git|library|temp|obj|build|dist|assets|packages|vendor|_archive)$/i;
+
+function lineCount(file) {
+  try { return countLines(fs.readFileSync(file, 'utf8')); } catch (_) { return 0; }
+}
+
+/** Repo docs worth reading: root + one level down (CLAUDE.md, AGENTS.md, README*, CONTRACT*), skipping vendored dirs. */
+function bootDocs(root) {
+  const out = [];
+  const scan = (dir, depth) => {
+    let ents = [];
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+    for (const e of ents) {
+      const p = path.join(dir, e.name);
+      if (e.isFile() && BOOT_DOCS.test(e.name)) out.push({ path: slash(path.relative(root, p)), lines: lineCount(p) });
+      else if (e.isDirectory() && depth < 1 && !BOOT_SKIP_DIR.test(e.name) && (!e.name.startsWith('.') || e.name === '.claude')) scan(p, depth + 1);
+    }
+  };
+  scan(root, 0);
+  return out;
+}
+
+const reEsc = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Old run files (context-r, contract, plan outputs, handoffs) that name this repo, newest first. */
+function bootRuns(info, extraPaths) {
+  const needles = [info.root].concat(extraPaths || []).map((p) => slash(p).toLowerCase().replace(/\/+$/, '')).filter(Boolean);
+  const nameRe = new RegExp(`[/\\\\]${reEsc(info.name)}(?![a-z0-9_-])`, 'i');
+  const hits = [];
+  let dirs = [];
+  try { dirs = fs.readdirSync(core.runsDir(), { withFileTypes: true }).filter((d) => d.isDirectory()); } catch (_) { return hits; }
+  for (const d of dirs) {
+    const rd = path.join(core.runsDir(), d.name);
+    let files = [];
+    try { files = fs.readdirSync(rd).filter((f) => BOOT_RUN_FILE.test(f)); } catch (_) { continue; }
+    for (const f of files) {
+      const p = path.join(rd, f);
+      let st;
+      let txt;
+      try { st = fs.statSync(p); if (st.size > 400 * 1024) continue; txt = fs.readFileSync(p, 'utf8'); } catch (_) { continue; }
+      const low = slash(txt).toLowerCase();
+      const n = needles.reduce((a, s) => a + low.split(s).length - 1, 0) + (nameRe.test(txt) ? 1 : 0);
+      if (n) hits.push({ path: slash(p), mentions: n, mtime: st.mtime.toISOString() });
+    }
+  }
+  return hits.sort((a, b) => b.mtime.localeCompare(a.mtime)).slice(0, BOOT_MAX_RUNS);
+}
+
+/** Sibling repos whose folder name matches one of the patterns (for a parent repo's `children` section). No linking. */
+function bootChildren(info, patterns) {
+  if (typeof patterns !== 'string' || !patterns.trim()) return [];
+  const parent = path.dirname(path.resolve(info.root));
+  const res = patterns.split(',').map((x) => x.trim()).filter(Boolean)
+    .map((g) => new RegExp(`^${reEsc(g).replace(/\\\*/g, '.*').replace(/\\\?/g, '.')}$`, 'i'));
+  let ents = [];
+  try { ents = fs.readdirSync(parent, { withFileTypes: true }); } catch (_) { return []; }
+  return ents.filter((e) => e.isDirectory() && res.some((r) => r.test(e.name)) && fs.existsSync(path.join(parent, e.name, '.git'))
+    && path.resolve(parent, e.name) !== path.resolve(info.root))
+    .map((e) => slash(path.join(parent, e.name)));
+}
+
+/**
+ * `knowledge bootstrap [--repo R] [--children pat,pat] [--json]`: read-only. Lists what a bootstrap agent should read
+ * (repo docs, old run files naming this repo), what the store already has, and the delta it should write. The agent
+ * writes knowledge-delta-<task>.md into its run dir; merge --run writes the store — the CLI never summarises.
+ */
+function cmdBootstrap(opts) {
+  const { start, info } = infoOf(opts, true);
+  if (!info) return notRepo(start);
+  const ri = readIndex(info.dir);
+  const have = ri.idx ? ri.idx.sections.map((s) => s.id) : [];
+  const startSlash = slash(path.resolve(start));
+  const res = {
+    repo: slash(info.root), store: slash(info.dir), key: info.key, head: headShaOf(start), sections: have,
+    docs: bootDocs(info.root), runs: bootRuns(info, startSlash !== slash(info.root) ? [startSlash] : []),
+    children: bootChildren(info, opts.children),
+    suggested: BOOT_SECTIONS.map(([id, what]) => ({ id, what, exists: have.includes(id) })),
+  };
+  if (opts.json) return { code: 0, out: JSON.stringify(res, null, 2) };
+  const L = [`Bootstrap knowledge: ${res.repo}`,
+    `kho: ${res.store}${have.length ? ` (đã có ${have.length} mục: ${have.join(', ')})` : ' (chưa có mục nào)'}`,
+    '', 'Đọc (chỉ đọc, không sửa repo):'];
+  for (const d of res.docs) L.push(`  ${d.path} (${d.lines} dòng)`);
+  if (!res.docs.length) L.push('  (không thấy CLAUDE.md/README/AGENTS.md)');
+  L.push(`Run cũ có nhắc repo này (${res.runs.length}, mới nhất trước; điều gì đã cũ so với code hiện tại thì bỏ):`);
+  for (const r of res.runs) L.push(`  ${r.path} (${r.mentions} lần, ${r.mtime.slice(0, 10)})`);
+  if (res.children.length) {
+    L.push('Repo con theo mẫu tên (ghi vào mục "children": đường dẫn + vai trò; KHÔNG gộp knowledge của con vào kho này):');
+    for (const c of res.children) L.push(`  ${c}`);
+  }
+  L.push('', 'Mục nên có (≤ 40 dòng/mục; chỉ điều không suy ra được từ code; cấu trúc code để cho codebase-memory-mcp):');
+  for (const s of res.suggested) L.push(`  ${s.exists ? '=' : '+'} ${s.id}: ${s.what}`);
+  L.push('', 'Ghi <run>/knowledge-delta-<task_id>.md:', `  repo: ${res.repo}`, `  head: ${res.head || '<sha>'}`,
+    '  ## +build-test', '  title: …', '  tags: …', '  paths: package.json, test/**   (bắt buộc: glob các file mục nói tới)', '  <thân mục>',
+    'Agent KHÔNG tự chạy knowledge merge: kho chỉ đổi khi người dùng accept (verdict … accept ở cổng 3 tự gộp delta).',
+    'Kiểm trước, không ghi gì: dieu-phoi knowledge merge --run <run> --task <task_id> --dry-run (sửa mục đã có: "## <id>" + dòng base: chép từ knowledge get).');
+  return { code: 0, out: L.join('\n') };
+}
+
+// ------------------------------------------------------------------ link
+
+function upsertRelated(info, other, rel, remove) {
+  const lk = withLock(path.join(info.dir, 'knowledge.lock'), () => {
+    const ri = readIndex(info.dir);
+    if (ri.error) return { error: ri.error };
+    const idx = ri.idx || newIndex(info);
+    const before = JSON.stringify(idx.related);
+    idx.related = idx.related.filter((r) => r.key !== other.key);
+    if (!remove) idx.related.push({ key: other.key, name: other.name, path: other.root, rel });
+    if (JSON.stringify(idx.related) === before) return { changed: false };
+    idx.schema = INDEX_SCHEMA;
+    idx.key = info.key;
+    idx.name = idx.name || info.name;
+    core.writeFileAtomic(path.join(info.dir, 'index.json'), `${JSON.stringify(idx, null, 2)}\n`);
+    ensureMeta(info.dir, info);
+    return { changed: true };
+  }, LOCK_TRIES);
+  return lk.locked ? { error: `kho ${info.dir} đang bị khoá — thử lại` } : lk.value;
+}
+
+function cmdLink(opts) {
+  const { start, info } = infoOf(opts, false);
+  if (!info) return notRepo(start);
+  const target = opts._[0];
+  if (!target) return { code: 1, out: 'Cần đường dẫn repo kia: knowledge link <đường dẫn> --rel child|parent' };
+  if (opts.rel !== 'child' && opts.rel !== 'parent') return { code: 1, out: '--rel phải là child (repo kia là con) hoặc parent (repo kia là cha).' };
+  const otherPath = path.resolve(core.nativePath(String(target)));
+  const other = isDir(otherPath) ? core.resolveProject(otherPath) : null;
+  if (!other) return { code: 1, out: `Không phải repo git: ${otherPath}` };
+  if (other.key === info.key) return { code: 1, out: 'Hai đường dẫn là cùng một repo (cùng khoá).' };
+  const remove = !!opts.remove;
+  const inverse = opts.rel === 'child' ? 'parent' : 'child';
+  const a = upsertRelated(info, other, opts.rel, remove);
+  if (a.error) return { code: 1, out: a.error };
+  const b = upsertRelated(other, info, inverse, remove);
+  if (b.error) return { code: 1, out: b.error };
+  const verb = remove ? 'Đã gỡ liên kết' : 'Đã liên kết';
+  return { code: 0, out: `${verb}: ${other.name} là ${opts.rel === 'child' ? 'con' : 'cha'} của ${info.name}${a.changed || b.changed ? '' : ' (không đổi)'}.` };
+}
+
+function cmdKnowledge(opts) {
+  const sub = opts._.shift();
+  if (!sub || opts.help || opts.h || sub === 'help') {
+    return { code: sub || opts.help || opts.h ? 0 : 1, out: KNOWLEDGE_HELP.trimEnd() };
+  }
+  if (sub === 'path') return cmdPath(opts);
+  if (sub === 'rekey') return cmdRekey(opts);
+  if (sub === 'get') return cmdGet(opts);
+  if (sub === 'list') return cmdList(opts);
+  if (sub === 'status') return cmdStatus(opts);
+  if (sub === 'merge') return cmdMerge(opts);
+  if (sub === 'link') return cmdLink(opts);
+  if (sub === 'bootstrap') return cmdBootstrap(opts);
+  return { code: 1, out: `Lệnh knowledge lạ: ${sub}\n\n${KNOWLEDGE_HELP.trimEnd()}` };
+}
+
+module.exports = {
+  cmdKnowledge, KNOWLEDGE_HELP, MAX_LINES, parseDelta, globMatch, readIndex, storeDirOf, selectSections, headShaOf, freshnessOf,
+  deltaFiles, deltaTaskOf, cmdMerge, cmdBootstrap,
+};