scrum-skills 0.3.2 → 0.3.3

package/tools/last-change.mjs

@@ -1,326 +1,326 @@
-#!/usr/bin/env node
-/**
- * 交付说明 agile/last-change.json 的写入策略（零依赖，node >= 18）
- *
- * 规矩只有一条：写之前先看 git。
- *   · 文件已提交、工作区干净 → 上一次交付已经进了版本库，整份覆盖没风险；
- *   · 还有没提交的改动（未跟踪 / 已暂存 / 改过没提交 / 根本不是 git 仓库）
- *     → 直接覆盖会把上一次还没入库的记录冲掉，必须把本次结果并进去。
- *
- * 用法:
- *   node tools/last-change.mjs check [dir]
- *       打印状态与建议。退出码：0 可直接写，2 必须先合并，3 读不了文件
- *   node tools/last-change.mjs write <记录.json|-> [dir] [--replace]
- *       按状态自动覆盖或合并，写后跑一次 validate，不过就回滚。
- *       --replace 无视 git 状态强制整份覆盖（只有确认旧记录不要了才用）
- *
- * 结构规范见 .agents/skills/scrum-planning/references/schema.md 第 4 节。
- */
-import { existsSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { execFileSync, spawnSync } from 'node:child_process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const VALIDATOR = fileURLToPath(new URL('./validate.mjs', import.meta.url));
-const REL = 'agile/last-change.json';
-
-/** 五种状态 → 一句人话 + 建议动作（write / merge / replace） */
-export const STATE_TEXT = {
-  missing: { label: '还没有这个文件', advice: 'write', hint: '第一次写，直接生成即可' },
-  committed: { label: '已提交', advice: 'replace', hint: '上一次交付已经在版本库里，可以整份覆盖' },
-  dirty: { label: '未提交（有改动）', advice: 'merge', hint: '上一次交付还没入库，覆盖会丢，先合并' },
-  untracked: { label: '未提交（未纳入版本库）', advice: 'merge', hint: '文件还没 add 过，覆盖会丢，先合并' },
-  'no-git': { label: '不是 git 仓库', advice: 'merge', hint: '无法判断是否已入库，按未提交处理' },
-};
-
-const git = (root, args) =>
-  execFileSync('git', ['-C', root, ...args], {
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-    timeout: 5000,
-    windowsHide: true,
-  }).trim();
-
-/**
- * 判定 last-change.json 的版本库状态。
- * 返回 { state, advice, file, tracked, dirty, hash?, date?, subject? }
- */
-export function checkLastChange(root = process.cwd()) {
-  const dir = resolve(root);
-  const file = join(dir, REL);
-  const base = { file, state: 'missing', advice: 'write', tracked: false, dirty: false };
-  if (!existsSync(file)) return base;
-
-  let tracked = false;
-  try {
-    git(dir, ['ls-files', '--error-unmatch', REL]);
-    tracked = true;
-  } catch (e) {
-    const text = `${e.stderr ?? ''}${e.message ?? ''}`;
-    // git 没装或不是仓库：都无法判断有没有入库，按「未提交」处理
-    if (/not a git repository|ENOENT|is not recognized/i.test(text)) {
-      return { ...base, state: 'no-git', advice: 'merge' };
-    }
-  }
-  if (!tracked) return { ...base, state: 'untracked', advice: 'merge' };
-
-  if (git(dir, ['status', '--porcelain', '--', REL])) {
-    return { ...base, state: 'dirty', advice: 'merge', tracked: true, dirty: true };
-  }
-
-  let hash, date, subject;
-  try {
-    const log = git(dir, ['log', '-1', '--format=%h%x1f%ad%x1f%s', '--date=short', '--', REL]);
-    [hash, date, subject] = log.split('\x1f');
-  } catch {
-    // 已跟踪但查不到 log（浅克隆之类）不影响判断
-  }
-  return { ...base, state: 'committed', advice: 'replace', tracked: true, hash, date, subject };
-}
-
-/** 本地时间戳，精确到秒：2026-10-27 09:05:03。交付记录缺 at 时用它补 */
-export function nowStamp(d = new Date()) {
-  const p = n => String(n).padStart(2, '0');
-  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
-}
-
-const stampOf = iso => {
-  const d = new Date(iso ?? '');
-  return Number.isNaN(d.getTime()) ? String(iso ?? '') : nowStamp(d);
-};
-
-/**
- * 这个文件在 git 里的提交历史（页面「查看历史」用）。
- * 没有 git / 从没提交过都给空列表，不抛错——空历史是正常状态。
- */
-export function listLastChangeHistory(root = process.cwd(), { limit = 40 } = {}) {
-  const dir = resolve(root);
-  const state = checkLastChange(dir).state;
-  try {
-    const out = git(dir, ['log', `-n${limit}`, '--format=%H%x1f%h%x1f%aI%x1f%s', '--', REL]);
-    const entries = (out ? out.split('\n').filter(Boolean) : []).map(line => {
-      const [hash, short, iso, subject] = line.split('\x1f');
-      return { hash, short, date: stampOf(iso), iso, subject };
-    });
-    return { entries, state };
-  } catch (e) {
-    return { entries: [], state: 'no-git', message: String(e?.message ?? '') };
-  }
-}
-
-/** 取某一版交付记录（git show <hash>:agile/last-change.json） */
-export function readLastChangeAt(root = process.cwd(), hash) {
-  const dir = resolve(root);
-  const id = String(hash ?? '').trim();
-  if (!/^[0-9a-f]{7,40}$/i.test(id)) throw new Error('非法的提交号（只接受十六进制 hash）');
-
-  let raw;
-  try {
-    raw = git(dir, ['show', `${id}:${REL}`]);
-  } catch {
-    throw new Error('该提交里取不到 agile/last-change.json（提交不存在，或那时还没这个文件）');
-  }
-  let doc;
-  try {
-    doc = JSON.parse(raw);
-  } catch {
-    throw new Error('该版本的文件不是合法 JSON，没法渲染');
-  }
-
-  let short = id.slice(0, 7);
-  let date = '';
-  let subject = '';
-  try {
-    const [h, iso, s] = git(dir, ['log', '-1', '--format=%h%x1f%aI%x1f%s', id, '--', REL]).split('\x1f');
-    if (h) short = h;
-    date = stampOf(iso);
-    subject = s ?? '';
-  } catch {
-    // 查不到提交说明不影响看内容
-  }
-  return { hash: id, short, date, subject, doc };
-}
-
-const mergeList = (prev, next, keyOf) => {
-  const out = [];
-  const at = new Map();
-  for (const item of prev ?? []) {
-    const key = item ? keyOf(item) : null;
-    if (!key) { out.push(item); continue; }
-    if (at.has(key)) continue;
-    at.set(key, out.length);
-    out.push(item);
-  }
-  for (const item of next ?? []) {
-    const key = item ? keyOf(item) : null;
-    if (!key) { out.push(item); continue; }
-    // 同 key：新内容就地替换，位置留在原来的顺序上，读起来才是时间线
-    if (at.has(key)) out[at.get(key)] = item;
-    else { at.set(key, out.length); out.push(item); }
-  }
-  return out;
-};
-
-const mergeStrings = (prev, next) => {
-  const out = [];
-  for (const s of [...(prev ?? []), ...(next ?? [])]) {
-    if (typeof s !== 'string' || !s.trim()) continue;
-    if (!out.includes(s)) out.push(s);
-  }
-  return out;
-};
-
-/**
- * 把下一次交付并进还没提交的旧记录：按 key 去重、新的覆盖旧的、旧的顺序保留。
- * 只处理 lastChange 内层对象（外层 schemaVersion 由调用方补）。
- */
-export function mergeLastChange(prev = {}, next = {}) {
-  const out = { ...next };
-  if (!out.title) out.title = prev.title;
-  if (!out.at) out.at = prev.at;
-  if (!out.summary) out.summary = prev.summary;
-
-  const keep = (key, list) => {
-    if (list.length) out[key] = list;
-    else delete out[key];
-  };
-  keep('changes', mergeList(prev.changes, next.changes, c => (c?.kind && c?.id ? `${c.kind}:${c.id}` : null)));
-  keep('extras', mergeList(prev.extras, next.extras, x => x?.title ?? null));
-  keep('verification', mergeList(prev.verification, next.verification, v => v?.what ?? null));
-  keep('preparation', mergeList(prev.preparation, next.preparation, p => p?.step ?? null));
-  keep('scenarios', mergeList(prev.scenarios, next.scenarios, s => s?.id ?? s?.title ?? null));
-  keep('notes', mergeStrings(prev.notes, next.notes));
-  keep('open', mergeStrings(prev.open, next.open));
-
-  const urls = mergeList(prev.access?.urls, next.access?.urls, u => u?.url ?? null);
-  const accounts = mergeList(prev.access?.accounts, next.access?.accounts, a => a?.username ?? null);
-  if (urls.length || accounts.length) {
-    out.access = {};
-    if (urls.length) out.access.urls = urls;
-    if (accounts.length) out.access.accounts = accounts;
-  } else if (next.access === undefined) {
-    delete out.access;
-  }
-
-  // 同一次交付被重复并进来时不要把它的标题再记一遍
-  const sameDelivery = prev.title && next.title && prev.title === next.title && prev.at === next.at;
-  const older = sameDelivery || !prev.title ? [] : [{ title: prev.title, at: prev.at }];
-  const mergedFrom = mergeList(prev.mergedFrom, older, x => `${x?.at ?? ''}|${x?.title ?? ''}`);
-  if (mergedFrom.length) {
-    out.merged = true;
-    out.mergedFrom = mergedFrom;
-  } else {
-    delete out.merged;
-    delete out.mergedFrom;
-  }
-  return out;
-}
-
-/**
- * 按 git 状态写入：已提交 → 覆盖，否则 → 合并。写后校验，失败回滚。
- * next 传 lastChange 内层对象（也接受整份 { schemaVersion, lastChange }）。
- */
-export function writeLastChange(root = process.cwd(), next, { validate = true, force = false } = {}) {
-  const dir = resolve(root);
-  const file = join(dir, REL);
-  const input = next?.lastChange ?? next;
-  if (!input || typeof input !== 'object') throw new Error('缺少 lastChange 记录（内层对象或整份文件都行）');
-  // 交付时间精确到秒：没写就补当下，免得页面上只看到一个日期
-  const payload = { ...input };
-  if (!payload.at) payload.at = nowStamp();
-
-  const before = existsSync(file) ? readFileSync(file, 'utf8') : null;
-  let prev = null;
-  if (before !== null) {
-    try {
-      prev = JSON.parse(before)?.lastChange ?? null;
-    } catch {
-      return { action: 'failed', state: checkLastChange(dir).state, file, message: '现有 last-change.json 解析失败，先修好再来写，别直接覆盖' };
-    }
-  }
-
-  const state = checkLastChange(dir);
-  let action, merged;
-  if (!prev) {
-    action = 'create';
-    merged = payload;
-  } else if (force || state.advice === 'replace') {
-    action = 'replace';
-    merged = payload;
-  } else {
-    action = 'merge';
-    merged = mergeLastChange(prev, payload);
-  }
-
-  writeFileSync(file, JSON.stringify({ schemaVersion: 3, lastChange: merged }, null, 2) + '\n');
-  if (!validate) return { action, state: state.state, file, validation: 'skipped', changes: merged.changes?.length ?? 0 };
-
-  const r = spawnSync(process.execPath, [VALIDATOR, dir], { encoding: 'utf8', timeout: 30000 });
-  if (r.status !== 0) {
-    if (before === null) rmSync(file, { force: true });
-    else writeFileSync(file, before);
-    return {
-      action: 'rolled-back', state: state.state, file, validation: 'fail',
-      message: `写后校验未通过，已回滚：${(r.stdout || r.stderr || '').trim()}`,
-    };
-  }
-  return { action, state: state.state, file, validation: 'pass', changes: merged.changes?.length ?? 0 };
-}
-
-function printCheck(state) {
-  const info = STATE_TEXT[state.state] ?? STATE_TEXT.missing;
-  console.log(`· 文件: ${state.file}`);
-  console.log(`· 状态: ${info.label}${state.state === 'committed' && state.hash ? `（${state.hash}${state.date ? ` · ${state.date}` : ''}${state.subject ? ` · ${state.subject}` : ''}）` : ''}`);
-  console.log(`· 建议: ${info.hint}`);
-}
-
-function main() {
-  const [cmd, ...rest] = process.argv.slice(2);
-  const positional = rest.filter(a => !a.startsWith('--'));
-  if (cmd === 'check' || cmd === 'status') {
-    const state = checkLastChange(positional[0] ?? process.cwd());
-    printCheck(state);
-    process.exit(state.advice === 'merge' ? 2 : 0);
-  }
-  if (cmd === 'write') {
-    const src = positional[0];
-    if (!src) {
-      console.error('用法: node tools/last-change.mjs write <记录.json|-> [目录] [--replace]');
-      process.exit(1);
-    }
-    const dir = resolve(positional[1] ?? process.cwd());
-    let raw;
-    try {
-      raw = src === '-' ? readFileSync(0, 'utf8') : readFileSync(resolve(src), 'utf8');
-    } catch (e) {
-      console.error(`✘ 读不到记录文件: ${e.message}`);
-      process.exit(3);
-    }
-    let doc;
-    try {
-      doc = JSON.parse(raw);
-    } catch (e) {
-      console.error(`✘ 记录文件不是合法 JSON: ${e.message}`);
-      process.exit(3);
-    }
-
-    const state = checkLastChange(dir);
-    printCheck(state);
-    const r = writeLastChange(dir, doc, { force: rest.includes('--replace') });
-    if (r.action === 'failed' || r.action === 'rolled-back') {
-      console.error(`✘ ${r.message}`);
-      process.exit(4);
-    }
-    const verb = { create: '新建', replace: '整份覆盖', merge: '并入旧记录' }[r.action] ?? r.action;
-    console.log(`✔ 已${verb}: ${REL}（changes ${r.changes} 条）`);
-    console.log('· 校验: 通过');
-    if (r.action === 'merge') console.log('· 旧记录还留着，提交后下次才会整份覆盖');
-    return;
-  }
-
-  console.error('用法:\n  node tools/last-change.mjs check [目录]\n  node tools/last-change.mjs write <记录.json|-> [目录] [--replace]');
-  process.exit(1);
-}
-
-const entry = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : '';
-if (entry && entry === import.meta.url) main();
+#!/usr/bin/env node
+/**
+ * 交付说明 agile/last-change.json 的写入策略（零依赖，node >= 18）
+ *
+ * 规矩只有一条：写之前先看 git。
+ *   · 文件已提交、工作区干净 → 上一次交付已经进了版本库，整份覆盖没风险；
+ *   · 还有没提交的改动（未跟踪 / 已暂存 / 改过没提交 / 根本不是 git 仓库）
+ *     → 直接覆盖会把上一次还没入库的记录冲掉，必须把本次结果并进去。
+ *
+ * 用法:
+ *   node tools/last-change.mjs check [dir]
+ *       打印状态与建议。退出码：0 可直接写，2 必须先合并，3 读不了文件
+ *   node tools/last-change.mjs write <记录.json|-> [dir] [--replace]
+ *       按状态自动覆盖或合并，写后跑一次 validate，不过就回滚。
+ *       --replace 无视 git 状态强制整份覆盖（只有确认旧记录不要了才用）
+ *
+ * 结构规范见 .agents/skills/scrum-planning/references/schema.md 第 4 节。
+ */
+import { existsSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const VALIDATOR = fileURLToPath(new URL('./validate.mjs', import.meta.url));
+const REL = 'agile/last-change.json';
+
+/** 五种状态 → 一句人话 + 建议动作（write / merge / replace） */
+export const STATE_TEXT = {
+  missing: { label: '还没有这个文件', advice: 'write', hint: '第一次写，直接生成即可' },
+  committed: { label: '已提交', advice: 'replace', hint: '上一次交付已经在版本库里，可以整份覆盖' },
+  dirty: { label: '未提交（有改动）', advice: 'merge', hint: '上一次交付还没入库，覆盖会丢，先合并' },
+  untracked: { label: '未提交（未纳入版本库）', advice: 'merge', hint: '文件还没 add 过，覆盖会丢，先合并' },
+  'no-git': { label: '不是 git 仓库', advice: 'merge', hint: '无法判断是否已入库，按未提交处理' },
+};
+
+const git = (root, args) =>
+  execFileSync('git', ['-C', root, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 5000,
+    windowsHide: true,
+  }).trim();
+
+/**
+ * 判定 last-change.json 的版本库状态。
+ * 返回 { state, advice, file, tracked, dirty, hash?, date?, subject? }
+ */
+export function checkLastChange(root = process.cwd()) {
+  const dir = resolve(root);
+  const file = join(dir, REL);
+  const base = { file, state: 'missing', advice: 'write', tracked: false, dirty: false };
+  if (!existsSync(file)) return base;
+
+  let tracked = false;
+  try {
+    git(dir, ['ls-files', '--error-unmatch', REL]);
+    tracked = true;
+  } catch (e) {
+    const text = `${e.stderr ?? ''}${e.message ?? ''}`;
+    // git 没装或不是仓库：都无法判断有没有入库，按「未提交」处理
+    if (/not a git repository|ENOENT|is not recognized/i.test(text)) {
+      return { ...base, state: 'no-git', advice: 'merge' };
+    }
+  }
+  if (!tracked) return { ...base, state: 'untracked', advice: 'merge' };
+
+  if (git(dir, ['status', '--porcelain', '--', REL])) {
+    return { ...base, state: 'dirty', advice: 'merge', tracked: true, dirty: true };
+  }
+
+  let hash, date, subject;
+  try {
+    const log = git(dir, ['log', '-1', '--format=%h%x1f%ad%x1f%s', '--date=short', '--', REL]);
+    [hash, date, subject] = log.split('\x1f');
+  } catch {
+    // 已跟踪但查不到 log（浅克隆之类）不影响判断
+  }
+  return { ...base, state: 'committed', advice: 'replace', tracked: true, hash, date, subject };
+}
+
+/** 本地时间戳，精确到秒：2026-10-27 09:05:03。交付记录缺 at 时用它补 */
+export function nowStamp(d = new Date()) {
+  const p = n => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+
+const stampOf = iso => {
+  const d = new Date(iso ?? '');
+  return Number.isNaN(d.getTime()) ? String(iso ?? '') : nowStamp(d);
+};
+
+/**
+ * 这个文件在 git 里的提交历史（页面「查看历史」用）。
+ * 没有 git / 从没提交过都给空列表，不抛错——空历史是正常状态。
+ */
+export function listLastChangeHistory(root = process.cwd(), { limit = 40 } = {}) {
+  const dir = resolve(root);
+  const state = checkLastChange(dir).state;
+  try {
+    const out = git(dir, ['log', `-n${limit}`, '--format=%H%x1f%h%x1f%aI%x1f%s', '--', REL]);
+    const entries = (out ? out.split('\n').filter(Boolean) : []).map(line => {
+      const [hash, short, iso, subject] = line.split('\x1f');
+      return { hash, short, date: stampOf(iso), iso, subject };
+    });
+    return { entries, state };
+  } catch (e) {
+    return { entries: [], state: 'no-git', message: String(e?.message ?? '') };
+  }
+}
+
+/** 取某一版交付记录（git show <hash>:agile/last-change.json） */
+export function readLastChangeAt(root = process.cwd(), hash) {
+  const dir = resolve(root);
+  const id = String(hash ?? '').trim();
+  if (!/^[0-9a-f]{7,40}$/i.test(id)) throw new Error('非法的提交号（只接受十六进制 hash）');
+
+  let raw;
+  try {
+    raw = git(dir, ['show', `${id}:${REL}`]);
+  } catch {
+    throw new Error('该提交里取不到 agile/last-change.json（提交不存在，或那时还没这个文件）');
+  }
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch {
+    throw new Error('该版本的文件不是合法 JSON，没法渲染');
+  }
+
+  let short = id.slice(0, 7);
+  let date = '';
+  let subject = '';
+  try {
+    const [h, iso, s] = git(dir, ['log', '-1', '--format=%h%x1f%aI%x1f%s', id, '--', REL]).split('\x1f');
+    if (h) short = h;
+    date = stampOf(iso);
+    subject = s ?? '';
+  } catch {
+    // 查不到提交说明不影响看内容
+  }
+  return { hash: id, short, date, subject, doc };
+}
+
+const mergeList = (prev, next, keyOf) => {
+  const out = [];
+  const at = new Map();
+  for (const item of prev ?? []) {
+    const key = item ? keyOf(item) : null;
+    if (!key) { out.push(item); continue; }
+    if (at.has(key)) continue;
+    at.set(key, out.length);
+    out.push(item);
+  }
+  for (const item of next ?? []) {
+    const key = item ? keyOf(item) : null;
+    if (!key) { out.push(item); continue; }
+    // 同 key：新内容就地替换，位置留在原来的顺序上，读起来才是时间线
+    if (at.has(key)) out[at.get(key)] = item;
+    else { at.set(key, out.length); out.push(item); }
+  }
+  return out;
+};
+
+const mergeStrings = (prev, next) => {
+  const out = [];
+  for (const s of [...(prev ?? []), ...(next ?? [])]) {
+    if (typeof s !== 'string' || !s.trim()) continue;
+    if (!out.includes(s)) out.push(s);
+  }
+  return out;
+};
+
+/**
+ * 把下一次交付并进还没提交的旧记录：按 key 去重、新的覆盖旧的、旧的顺序保留。
+ * 只处理 lastChange 内层对象（外层 schemaVersion 由调用方补）。
+ */
+export function mergeLastChange(prev = {}, next = {}) {
+  const out = { ...next };
+  if (!out.title) out.title = prev.title;
+  if (!out.at) out.at = prev.at;
+  if (!out.summary) out.summary = prev.summary;
+
+  const keep = (key, list) => {
+    if (list.length) out[key] = list;
+    else delete out[key];
+  };
+  keep('changes', mergeList(prev.changes, next.changes, c => (c?.kind && c?.id ? `${c.kind}:${c.id}` : null)));
+  keep('extras', mergeList(prev.extras, next.extras, x => x?.title ?? null));
+  keep('verification', mergeList(prev.verification, next.verification, v => v?.what ?? null));
+  keep('preparation', mergeList(prev.preparation, next.preparation, p => p?.step ?? null));
+  keep('scenarios', mergeList(prev.scenarios, next.scenarios, s => s?.id ?? s?.title ?? null));
+  keep('notes', mergeStrings(prev.notes, next.notes));
+  keep('open', mergeStrings(prev.open, next.open));
+
+  const urls = mergeList(prev.access?.urls, next.access?.urls, u => u?.url ?? null);
+  const accounts = mergeList(prev.access?.accounts, next.access?.accounts, a => a?.username ?? null);
+  if (urls.length || accounts.length) {
+    out.access = {};
+    if (urls.length) out.access.urls = urls;
+    if (accounts.length) out.access.accounts = accounts;
+  } else if (next.access === undefined) {
+    delete out.access;
+  }
+
+  // 同一次交付被重复并进来时不要把它的标题再记一遍
+  const sameDelivery = prev.title && next.title && prev.title === next.title && prev.at === next.at;
+  const older = sameDelivery || !prev.title ? [] : [{ title: prev.title, at: prev.at }];
+  const mergedFrom = mergeList(prev.mergedFrom, older, x => `${x?.at ?? ''}|${x?.title ?? ''}`);
+  if (mergedFrom.length) {
+    out.merged = true;
+    out.mergedFrom = mergedFrom;
+  } else {
+    delete out.merged;
+    delete out.mergedFrom;
+  }
+  return out;
+}
+
+/**
+ * 按 git 状态写入：已提交 → 覆盖，否则 → 合并。写后校验，失败回滚。
+ * next 传 lastChange 内层对象（也接受整份 { schemaVersion, lastChange }）。
+ */
+export function writeLastChange(root = process.cwd(), next, { validate = true, force = false } = {}) {
+  const dir = resolve(root);
+  const file = join(dir, REL);
+  const input = next?.lastChange ?? next;
+  if (!input || typeof input !== 'object') throw new Error('缺少 lastChange 记录（内层对象或整份文件都行）');
+  // 交付时间精确到秒：没写就补当下，免得页面上只看到一个日期
+  const payload = { ...input };
+  if (!payload.at) payload.at = nowStamp();
+
+  const before = existsSync(file) ? readFileSync(file, 'utf8') : null;
+  let prev = null;
+  if (before !== null) {
+    try {
+      prev = JSON.parse(before)?.lastChange ?? null;
+    } catch {
+      return { action: 'failed', state: checkLastChange(dir).state, file, message: '现有 last-change.json 解析失败，先修好再来写，别直接覆盖' };
+    }
+  }
+
+  const state = checkLastChange(dir);
+  let action, merged;
+  if (!prev) {
+    action = 'create';
+    merged = payload;
+  } else if (force || state.advice === 'replace') {
+    action = 'replace';
+    merged = payload;
+  } else {
+    action = 'merge';
+    merged = mergeLastChange(prev, payload);
+  }
+
+  writeFileSync(file, JSON.stringify({ schemaVersion: 3, lastChange: merged }, null, 2) + '\n');
+  if (!validate) return { action, state: state.state, file, validation: 'skipped', changes: merged.changes?.length ?? 0 };
+
+  const r = spawnSync(process.execPath, [VALIDATOR, dir], { encoding: 'utf8', timeout: 30000 });
+  if (r.status !== 0) {
+    if (before === null) rmSync(file, { force: true });
+    else writeFileSync(file, before);
+    return {
+      action: 'rolled-back', state: state.state, file, validation: 'fail',
+      message: `写后校验未通过，已回滚：${(r.stdout || r.stderr || '').trim()}`,
+    };
+  }
+  return { action, state: state.state, file, validation: 'pass', changes: merged.changes?.length ?? 0 };
+}
+
+function printCheck(state) {
+  const info = STATE_TEXT[state.state] ?? STATE_TEXT.missing;
+  console.log(`· 文件: ${state.file}`);
+  console.log(`· 状态: ${info.label}${state.state === 'committed' && state.hash ? `（${state.hash}${state.date ? ` · ${state.date}` : ''}${state.subject ? ` · ${state.subject}` : ''}）` : ''}`);
+  console.log(`· 建议: ${info.hint}`);
+}
+
+function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const positional = rest.filter(a => !a.startsWith('--'));
+  if (cmd === 'check' || cmd === 'status') {
+    const state = checkLastChange(positional[0] ?? process.cwd());
+    printCheck(state);
+    process.exit(state.advice === 'merge' ? 2 : 0);
+  }
+  if (cmd === 'write') {
+    const src = positional[0];
+    if (!src) {
+      console.error('用法: node tools/last-change.mjs write <记录.json|-> [目录] [--replace]');
+      process.exit(1);
+    }
+    const dir = resolve(positional[1] ?? process.cwd());
+    let raw;
+    try {
+      raw = src === '-' ? readFileSync(0, 'utf8') : readFileSync(resolve(src), 'utf8');
+    } catch (e) {
+      console.error(`✘ 读不到记录文件: ${e.message}`);
+      process.exit(3);
+    }
+    let doc;
+    try {
+      doc = JSON.parse(raw);
+    } catch (e) {
+      console.error(`✘ 记录文件不是合法 JSON: ${e.message}`);
+      process.exit(3);
+    }
+
+    const state = checkLastChange(dir);
+    printCheck(state);
+    const r = writeLastChange(dir, doc, { force: rest.includes('--replace') });
+    if (r.action === 'failed' || r.action === 'rolled-back') {
+      console.error(`✘ ${r.message}`);
+      process.exit(4);
+    }
+    const verb = { create: '新建', replace: '整份覆盖', merge: '并入旧记录' }[r.action] ?? r.action;
+    console.log(`✔ 已${verb}: ${REL}（changes ${r.changes} 条）`);
+    console.log('· 校验: 通过');
+    if (r.action === 'merge') console.log('· 旧记录还留着，提交后下次才会整份覆盖');
+    return;
+  }
+
+  console.error('用法:\n  node tools/last-change.mjs check [目录]\n  node tools/last-change.mjs write <记录.json|-> [目录] [--replace]');
+  process.exit(1);
+}
+
+const entry = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : '';
+if (entry && entry === import.meta.url) main();