scrum-skills 0.3.2 → 0.3.3

package/tools/validate.mjs

@@ -1,664 +1,781 @@
-#!/usr/bin/env node
-/**
- * 敏捷数据校验脚本（零依赖，schema v3：三文件结构）
- * 用法: node tools/validate.mjs [目标目录]   默认当前工作目录
- * 校验 <目标>/agile/ 下 backlog.json / sprints.json / journal.json：
- * 引用完整性（双向）、状态机、TDD 纪律、里程碑达成口径、
- * 需求属性（type/priority/value/缺陷详情/验收覆盖）、依赖无环、阻塞与范围变更。
- * 另外校验可选的 last-change.json（每次交付的汇报）：引用、动作枚举、验收口径、调试地址。
- * 退出码: 0 通过, 1 有错误。
- */
-import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-
-const TARGET = resolve(process.argv[2] || process.cwd());
-const AGILE = join(TARGET, 'agile');
-const errors = [];
-const warns = [];
-const err = m => errors.push(m);
-const warn = m => warns.push(m);
-
-const FILES = { backlog: 'backlog.json', sprints: 'sprints.json', journal: 'journal.json' };
-const data = {};
-for (const [key, name] of Object.entries(FILES)) {
-  const p = join(AGILE, name);
-  if (!existsSync(p)) {
-    err(`agile/${name} 缺失（schema v2 只认三文件结构）`);
-    continue;
-  }
-  try {
-    data[key] = JSON.parse(readFileSync(p, 'utf8'));
-  } catch (e) {
-    err(`agile/${name}: JSON 解析失败 - ${e.message}`);
-    continue;
-  }
-  if (data[key].schemaVersion !== 3) err(`agile/${name}: schemaVersion 应为 3，实际 ${data[key].schemaVersion}`);
-}
-
-// v2 不兼容散文件结构：残留就报错，提醒合并
-for (const rel of ['backlog/epics', 'backlog/stories', 'sprints', 'journal']) {
-  const p = join(AGILE, rel);
-  if (existsSync(p) && statSync(p).isDirectory() && readdirSync(p).some(f => f.endsWith('.json')))
-    err(`agile/${rel}/ 仍有散文件 JSON：v2 只认三文件结构，请合并进 backlog.json / sprints.json / journal.json`);
-}
-
-const backlog = data.backlog ?? {};
-const sprintsFile = data.sprints ?? {};
-const journalFile = data.journal ?? {};
-const epics = Array.isArray(backlog.epics) ? backlog.epics : [];
-const stories = Array.isArray(backlog.stories) ? backlog.stories : [];
-const sprints = Array.isArray(sprintsFile.sprints) ? sprintsFile.sprints : [];
-const milestones = Array.isArray(sprintsFile.milestones) ? sprintsFile.milestones : [];
-const journals = Array.isArray(journalFile.journals) ? journalFile.journals : [];
-
-const STORY_FLOW = ['draft', 'ready', 'in-progress', 'review', 'done', 'cancelled'];
-// 终态：done 与 cancelled 都不再往前走，也不再要求验收 / 任务全部做完
-const STORY_TERMINAL = ['done', 'cancelled'];
-const TASK_FLOW = ['todo', 'red', 'green', 'refactored', 'done'];
-const EPIC_FLOW = ['draft', 'active', 'done', 'cancelled'];
-const MILESTONE_FLOW = ['planned', 'at-risk', 'reached', 'missed'];
-const STORY_KIND = ['feature', 'bug', 'debt', 'spike'];
-const PRIORITY = ['P0', 'P1', 'P2', 'P3'];
-const SEVERITY = ['blocker', 'major', 'minor', 'trivial'];
-const SCOPE_KIND = ['added-mid-sprint', 'split', 'expanded'];
-const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
-/**
- * 交付时间：`YYYY-MM-DD` 或 `YYYY-MM-DD HH:mm:ss`（也接受 ISO 的 T 分隔）。
- * 日期必须真实存在（2026-13-01、2026-02-30 都不行），时分秒越界同样拦掉。
- */
-const STAMP_RE = /^(\d{4}-\d{2}-\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?)?$/;
-const stampOk = value => {
-  const m = STAMP_RE.exec(typeof value === 'string' ? value : '');
-  if (!m) return false;
-  const [, date, hh, mm, ss] = m;
-  // 用 UTC 构造再比对：本地时区（东八区）下 new Date('…T00:00:00') 转 ISO 会退到前一天
-  const [y, mo, da] = date.split('-').map(Number);
-  const d = new Date(Date.UTC(y, mo - 1, da));
-  if (d.getUTCFullYear() !== y || d.getUTCMonth() !== mo - 1 || d.getUTCDate() !== da) return false;
-  if (hh === undefined) return true;
-  return Number(hh) <= 23 && Number(mm) <= 59 && Number(ss ?? 0) <= 59;
-};
-const stampDate = value => (typeof value === 'string' ? value.slice(0, 10) : '');
-// 用本地日期判定「今天」，避免 UTC 偏移导致活跃迭代判定差一天
-const now = new Date();
-const today = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
-
-// ---- 全局唯一 id ----
-const ids = new Set();
-function claim(id, where) {
-  if (!id) { err(`${where}: 缺少 id`); return; }
-  if (ids.has(id)) err(`${where}: id ${id} 重复`);
-  else ids.add(id);
-}
-for (const e of epics) claim(e.id, 'epic');
-for (const s of stories) {
-  claim(s.id, 'story');
-  for (const t of s.tasks ?? []) {
-    claim(t.id, `story ${s.id} 的 task`);
-    if (t.id && !t.id.startsWith(`${s.id}-T`)) err(`task ${t.id}: 命名应为 ${s.id}-T<n>`);
-  }
-}
-for (const sp of sprints) claim(sp.id, 'sprint');
-for (const m of milestones) claim(m.id, 'milestone');
-
-const epicById = new Map(epics.map(e => [e.id, e]));
-const storyById = new Map(stories.map(s => [s.id, s]));
-const sprintById = new Map(sprints.map(s => [s.id, s]));
-const taskById = new Map();
-for (const s of stories) for (const t of s.tasks ?? []) taskById.set(t.id, { task: t, story: s });
-
-// ---- 依赖图必须是有向无环 ----
-{
-  const state = new Map(); // 1=访问中 2=已完成
-  const visit = (id, path) => {
-    const st = state.get(id) ?? 0;
-    if (st === 2) return;
-    if (st === 1) { err(`story 依赖成环: ${[...path, id].join(' → ')}`); return; }
-    state.set(id, 1);
-    for (const dep of storyById.get(id)?.dependsOn ?? []) if (storyById.has(dep)) visit(dep, [...path, id]);
-    state.set(id, 2);
-  };
-  for (const s of stories) visit(s.id, []);
-}
-
-// ---- Epic ----
-for (const e of epics) {
-  if (!EPIC_FLOW.includes(e.status)) err(`epic ${e.id}: 非法状态 ${e.status}`);
-  if (!e.title) err(`epic ${e.id}: 缺少 title`);
-  if (!e.goal) err(`epic ${e.id}: 缺少 goal`);
-  if (!Array.isArray(e.keyResults) || e.keyResults.length === 0) warn(`epic ${e.id}: 没有 keyResults（史诗要有量化目标，否则完成与否全靠感觉）`);
-  for (const kr of e.keyResults ?? []) {
-    if (!kr.id) err(`epic ${e.id}: keyResult 缺少 id`);
-    if (!kr.text) err(`epic ${e.id}: keyResult ${kr.id ?? '?'} 缺少 text`);
-    if (!Number.isFinite(kr.target)) err(`epic ${e.id}: keyResult ${kr.id ?? '?'} 的 target 必须是数字`);
-    if (!Number.isFinite(kr.current)) warn(`epic ${e.id}: keyResult ${kr.id ?? '?'} 没有 current，算不出进度`);
-  }
-  for (const sid of e.stories ?? []) {
-    const st = storyById.get(sid);
-    if (!st) { err(`epic ${e.id}: 引用 story ${sid} 不存在`); continue; }
-    if (st.epicId !== e.id) err(`epic ${e.id}: story ${sid} 的 epicId 是 ${st.epicId}，双向引用不一致`);
-  }
-  if (e.status === 'done') {
-    for (const sid of e.stories ?? []) {
-      const st = storyById.get(sid);
-      if (st && !['done', 'cancelled'].includes(st.status))
-        err(`epic ${e.id} 已 done 但 story ${sid} 状态为 ${st.status}`);
-    }
-  }
-}
-
-// ---- Story ----
-for (const s of stories) {
-  const { id, epicId, sprintId, status, acceptance, tasks, points } = s;
-  if (!s.title) err(`story ${id}: 缺少 title`);
-  if (!epicId) warn(`story ${id}: 未挂 epic`);
-  else if (!epicById.has(epicId)) err(`story ${id}: epicId ${epicId} 不存在`);
-  else if (!(epicById.get(epicId).stories ?? []).includes(id))
-    err(`story ${id}: 挂在 ${epicId} 上，但该 epic 的 stories 里没有它（双向引用不一致）`);
-
-  if (!STORY_FLOW.includes(status))
-    err(`story ${id}: 非法状态 ${status}（合法：${STORY_FLOW.join('/')}）`);
-  if (!Number.isFinite(points)) err(`story ${id}: points 必须是数字`);
-  else if (![1, 2, 3, 5, 8, 13].includes(points)) warn(`story ${id}: points ${points} 不在斐波那契序列`);
-
-  // 需求属性：类型 / 优先级 / 价值
-  if (!STORY_KIND.includes(s.type)) err(`story ${id}: type 必须是 ${STORY_KIND.join('/')}，实际 ${s.type}`);
-  if (!PRIORITY.includes(s.priority)) err(`story ${id}: priority 必须是 ${PRIORITY.join('/')}，实际 ${s.priority}`);
-  if (!Number.isFinite(s.value) || s.value <= 0) err(`story ${id}: value 必须是正数（用于算 WSJF）`);
-  if (s.type === 'bug') {
-    if (!s.bug) err(`story ${id}: type 为 bug 但缺少 bug 详情`);
-    else {
-      if (!SEVERITY.includes(s.bug.severity)) err(`story ${id}: bug.severity 必须是 ${SEVERITY.join('/')}`);
-      if (!s.bug.environment) err(`story ${id}: bug 缺少 environment（什么环境能复现）`);
-      if (!s.bug.steps) err(`story ${id}: bug 缺少 steps（怎么复现）`);
-    }
-  }
-
-  // 取消掉的故事不会再交付，别逼着为它补验收标准
-  if (['ready', 'in-progress', 'review', 'done'].includes(status) && (!acceptance || acceptance.length === 0))
-    err(`story ${id}: 状态 ${status} 但验收标准为空`);
-  for (const [i, a] of (acceptance ?? []).entries()) {
-    if (!a.given || !a.when || !a.then) err(`story ${id}: 第 ${i + 1} 条验收标准缺 given/when/then`);
-    // 每条验收都要能被某个 task 的测试验证，否则「验收」只是口号
-    for (const tid of a.verifyBy ?? []) {
-      const hit = taskById.get(tid);
-      if (!hit) err(`story ${id}: 第 ${i + 1} 条验收的 verifyBy ${tid} 不存在`);
-      else if (hit.story.id !== id) err(`story ${id}: 第 ${i + 1} 条验收的 verifyBy ${tid} 属于 ${hit.story.id}`);
-    }
-    if (!(a.verifyBy ?? []).length && !['draft', 'cancelled'].includes(status))
-      warn(`story ${id}: 第 ${i + 1} 条验收没有 verifyBy（没绑定验证任务）`);
-  }
-
-  // 阻塞 / 依赖
-  for (const dep of s.dependsOn ?? []) {
-    if (dep === id) err(`story ${id}: 不能依赖自己`);
-    else if (!storyById.has(dep)) err(`story ${id}: dependsOn 引用了不存在的 story ${dep}`);
-  }
-  if (s.blocked) {
-    if (!s.blocked.reason) err(`story ${id}: blocked 缺少 reason（堵在哪要说清）`);
-    if (!DATE_RE.test(s.blocked.since ?? '')) err(`story ${id}: blocked.since 格式应为 YYYY-MM-DD`);
-    if (status === 'done') err(`story ${id}: 已 done 却还标着 blocked`);
-    if (status === 'cancelled') err(`story ${id}: 已取消却还标着 blocked（不做了就别再挂着阻塞）`);
-    if (sprintId && !STORY_TERMINAL.includes(status))
-      warn(`story ${id}: 处于 ${sprintId} 但被阻塞（${s.blocked.reason}），站会必须处理`);
-  }
-
-  // 范围变更标记
-  if (s.scopeChange) {
-    if (!SCOPE_KIND.includes(s.scopeChange.kind)) err(`story ${id}: scopeChange.kind 必须是 ${SCOPE_KIND.join('/')}`);
-    if (!DATE_RE.test(s.scopeChange.at ?? '')) err(`story ${id}: scopeChange.at 格式应为 YYYY-MM-DD`);
-    else if (s.scopeChange.at > today) warn(`story ${id}: scopeChange.at ${s.scopeChange.at} 在未来`);
-    if (!s.scopeChange.reason) warn(`story ${id}: scopeChange 缺少 reason`);
-  }
-
-  if (sprintId) {
-    const sp = sprintById.get(sprintId);
-    if (!sp) err(`story ${id}: sprintId ${sprintId} 不存在`);
-    else if (!(sp.stories ?? []).includes(id))
-      err(`story ${id}: 指向 ${sprintId}，但该 sprint 的 stories 里没有它（双向引用不一致）`);
-    if (status !== 'cancelled' && (!acceptance || acceptance.length === 0))
-      err(`story ${id}: 已进 sprint 但无验收标准（不满足 ready）`);
-  }
-
-  if (s.schedule) {
-    const { start, end } = s.schedule;
-    if (!DATE_RE.test(start ?? '') || !DATE_RE.test(end ?? '')) err(`story ${id}: schedule 日期格式应为 YYYY-MM-DD`);
-    else if (start > end) err(`story ${id}: schedule 起点 ${start} 晚于终点 ${end}`);
-    else if (!sprintId) warn(`story ${id}: 未排期却有计划区间 ${start}~${end}`);
-    else {
-      const sp = sprintById.get(sprintId);
-      if (sp && (start < sp.start || end > sp.end))
-        warn(`story ${id}: 计划区间 ${start}~${end} 超出 ${sprintId}（${sp.start}~${sp.end}）`);
-    }
-  }
-
-  if (!Array.isArray(tasks) || tasks.length === 0) warn(`story ${id}: 没有拆 task，TDD 无从落地`);
-  for (const t of tasks ?? []) {
-    if (!TASK_FLOW.includes(t.status)) err(`task ${t.id}: 非法状态 ${t.status}`);
-    if (!['test', 'impl', 'refactor', 'chore'].includes(t.type)) err(`task ${t.id}: 非法类型 ${t.type}`);
-    if (!t.title) err(`task ${t.id}: 缺少 title`);
-  }
-  if (status === 'done') {
-    for (const t of tasks ?? []) {
-      if (t.status !== 'done') err(`story ${id} 已 done 但 task ${t.id} 状态为 ${t.status}`);
-    }
-  }
-}
-
-// ---- Sprint ----
-let active = 0;
-for (const sp of sprints) {
-  if (!sp.name) warn(`sprint ${sp.id}: 缺少 name`);
-  if (!DATE_RE.test(sp.start ?? '') || !DATE_RE.test(sp.end ?? '')) err(`sprint ${sp.id}: 起止日期格式应为 YYYY-MM-DD`);
-  else if (sp.start > sp.end) err(`sprint ${sp.id}: 起点 ${sp.start} 晚于终点 ${sp.end}`);
-  if (!Number.isFinite(sp.capacity)) err(`sprint ${sp.id}: capacity 必须是数字`);
-  for (const sid of sp.stories ?? []) {
-    const st = storyById.get(sid);
-    if (!st) { err(`sprint ${sp.id}: 引用 story ${sid} 不存在`); continue; }
-    if (st.sprintId !== sp.id) err(`sprint ${sp.id}: story ${sid} 的 sprintId 是 ${st.sprintId}，双向引用不一致`);
-    if (st.status === 'cancelled')
-      warn(`story ${sid}: 已取消但仍排在 ${sp.id} 里，建议从迭代移出（点数已不计入承诺）`);
-  }
-  // 已取消的故事不再占迭代容量：承诺点数只算还可能交付的
-  const committed = (sp.stories ?? []).reduce((a, sid) => {
-    const st = storyById.get(sid);
-    return st && st.status !== 'cancelled' ? a + (st.points ?? 0) : a;
-  }, 0);
-  if (Number.isFinite(sp.capacity) && committed > sp.capacity)
-    warn(`sprint ${sp.id}: 承诺 ${committed} 点超过容量 ${sp.capacity} 点`);
-  if (sp.start <= today && sp.end >= today) active++;
-}
-if (active > 1) err(`同时存在 ${active} 个活跃 sprint，只允许一个`);
-
-// ---- 迭代 id 规则：R<发布周期>-S<期内冲刺号>，或纯序号 S-01 ----
-{
-  const SPRINT_ID_RE = /^(?:R(\d+)-)?S-?(\d{1,2})$/;
-  const parsed = [];
-  for (const sp of sprints) {
-    const m = SPRINT_ID_RE.exec(sp.id ?? '');
-    if (!m) { err(`sprint ${sp.id}: id 必须形如 R1-S1（发布周期-冲刺）或 S-01（纯序号）`); continue; }
-    parsed.push({ sp, release: m[1] ?? null, seq: Number(m[2]) });
-  }
-  const styles = new Set(parsed.map(p => (p.release === null ? 'seq' : 'rel')));
-  if (styles.size > 1) err('sprint id 风格混用：R<n>-S<n> 与 S-<n> 不许同时出现');
-
-  const byRelease = new Map();
-  for (const p of parsed) {
-    const key = p.release ?? 'seq';
-    if (!byRelease.has(key)) byRelease.set(key, []);
-    byRelease.get(key).push(p);
-  }
-
-  for (const [key, list] of byRelease) {
-    const seqs = list.map(p => p.seq).sort((a, b) => a - b);
-    const dup = seqs.find((v, i) => i > 0 && v === seqs[i - 1]);
-    if (dup) err(`发布周期 ${key} 内冲刺序号重复：S${dup}`);
-    else if (seqs.some((v, i) => v !== i + 1))
-      err(`发布周期 ${key} 内冲刺序号应为 S1..S${seqs.length} 连续，实际 ${seqs.map(s => `S${s}`).join('/')}`);
-    if (list.length > 2) warn(`发布周期 ${key} 内有 ${list.length} 个冲刺（约定一期不超过 2 个）`);
-  }
-
-  // 期号越大，起始日期应越晚
-  const rels = [...byRelease.entries()]
-    .filter(([k]) => k !== 'seq')
-    .map(([k, list]) => ({ r: Number(k), start: list.map(p => p.sp.start).sort()[0] }))
-    .sort((a, b) => a.r - b.r);
-  for (let i = 1; i < rels.length; i++) {
-    if (rels[i].start < rels[i - 1].start)
-      warn(`发布周期 R${rels[i].r} 起始 ${rels[i].start} 早于 R${rels[i - 1].r}（${rels[i - 1].start}），期号与时间顺序不一致`);
-  }
-}
-
-// ---- Milestone ----
-for (const m of milestones) {
-  if (!m.title) err(`milestone ${m.id}: 缺少 title`);
-  if (!['mvp', 'release', 'checkpoint'].includes(m.kind)) err(`milestone ${m.id}: 非法 kind ${m.kind}`);
-  if (!MILESTONE_FLOW.includes(m.status)) err(`milestone ${m.id}: 非法状态 ${m.status}`);
-  if (!DATE_RE.test(m.due ?? '')) err(`milestone ${m.id}: due 格式应为 YYYY-MM-DD`);
-  if (!m.criteria) warn(`milestone ${m.id}: 缺少 criteria（达成口径），没法判断是否 reached`);
-  if (m.sprintId) {
-    const sp = sprintById.get(m.sprintId);
-    if (!sp) err(`milestone ${m.id}: sprintId ${m.sprintId} 不存在`);
-    else if (DATE_RE.test(m.due ?? '') && m.due > sp.end)
-      warn(`milestone ${m.id}: due ${m.due} 晚于所属 ${m.sprintId} 结束日 ${sp.end}`);
-  }
-  if (!(m.stories ?? []).length) warn(`milestone ${m.id}: 没有挂任何 story，无法验证达成`);
-  for (const sid of m.stories ?? []) {
-    if (!storyById.has(sid)) err(`milestone ${m.id}: 引用 story ${sid} 不存在`);
-  }
-  if (m.status === 'reached') {
-    for (const sid of m.stories ?? []) {
-      const st = storyById.get(sid);
-      if (st && !['done', 'cancelled'].includes(st.status))
-        err(`milestone ${m.id} 已 reached 但 story ${sid} 状态为 ${st.status}`);
-    }
-  }
-  if (m.status === 'planned' && DATE_RE.test(m.due ?? '') && m.due < today)
-    warn(`milestone ${m.id}: 状态 planned 但 due ${m.due} 已过期，应改成 at-risk / missed`);
-}
-
-// ---- Journal 与 TDD 纪律 ----
-const journalByTask = new Map();
-for (const j of journals) {
-  if (!j.taskId) { err('journal: 缺少 taskId'); continue; }
-  if (journalByTask.has(j.taskId)) err(`journal: taskId ${j.taskId} 重复`);
-  journalByTask.set(j.taskId, j);
-  const hit = taskById.get(j.taskId);
-  if (!hit) { err(`journal ${j.taskId}: 不指向任何真实 task`); continue; }
-  if (j.storyId !== hit.story.id) err(`journal ${j.taskId}: storyId ${j.storyId} 与 task 所属 ${hit.story.id} 不一致`);
-  let prev = '';
-  for (const e of j.entries ?? []) {
-    if (!['red', 'green', 'refactor'].includes(e.phase)) err(`journal ${j.taskId}: 非法 phase ${e.phase}`);
-    if (!DATE_RE.test(e.date ?? '')) err(`journal ${j.taskId}: date 格式应为 YYYY-MM-DD`);
-    else if (e.date > today) warn(`journal ${j.taskId}: 记录日期 ${e.date} 在未来`);
-    if (prev && e.date < prev) err(`journal ${j.taskId}: 记录日期倒序 ${prev} → ${e.date}`);
-    prev = e.date;
-    if (!e.note) warn(`journal ${j.taskId}: ${e.phase} 缺 note`);
-    if (!e.result) warn(`journal ${j.taskId}: ${e.phase} 缺 result`);
-  }
-}
-
-for (const [tid, { task }] of taskById) {
-  const hasRed = ['red', 'green', 'refactored', 'done'].includes(task.status);
-  const hasGreen = ['green', 'refactored', 'done'].includes(task.status);
-  const j = journalByTask.get(tid);
-  if (!hasRed) {
-    if (j && (j.entries ?? []).length > 0) warn(`${tid}: 尚在 todo 但 journal 已有实施记录（检查是否提前动了手）`);
-    continue;
-  }
-  if (!j) { err(`task ${tid}: 状态 ${task.status} 但 journal 缺失`); continue; }
-  const entries = j.entries ?? [];
-  const firstRed = entries.findIndex(e => e.phase === 'red');
-  const firstGreen = entries.findIndex(e => e.phase === 'green');
-  if (firstRed < 0) err(`task ${tid}: journal 没有 red 记录（先写失败测试的铁律被违反）`);
-  else if (entries[firstRed].result && !/^fail/i.test(entries[firstRed].result))
-    err(`task ${tid}: 第一条 red 记录的 result 应为 fail，实际 "${entries[firstRed].result}"`);
-  if (hasGreen) {
-    if (firstGreen < 0) err(`task ${tid}: 状态已过 red 但 journal 没有 green 记录`);
-    else if (entries[firstGreen].result && !/^pass/i.test(entries[firstGreen].result))
-      err(`task ${tid}: 第一条 green 记录的 result 应为 pass`);
-  }
-  if (task.status === 'done') {
-    const last = entries[entries.length - 1];
-    if (!last || !last.result || !/^pass/i.test(last.result))
-      err(`task ${tid}: 已 done 但 journal 末条记录不是 pass`);
-  }
-}
-
-// ---- last-change.json（每次交付的汇报，可选文件） ----
-// 文件不存在 = 还没交付过东西，合法；存在就必须能被看板「最后更新」页原样渲染。
-{
-  const p = join(AGILE, 'last-change.json');
-  if (existsSync(p)) {
-    const ACTION = ['added', 'updated', 'removed'];
-    const CHECK = ['pass', 'fail', 'partial', 'skipped'];
-    let doc = null;
-    try {
-      doc = JSON.parse(readFileSync(p, 'utf8'));
-    } catch (e) {
-      err(`agile/last-change.json: JSON 解析失败 - ${e.message}`);
-    }
-    if (doc) {
-      if (doc.schemaVersion !== 3) err(`agile/last-change.json: schemaVersion 应为 3，实际 ${doc.schemaVersion}`);
-      const c = doc.lastChange;
-      if (!c || typeof c !== 'object' || Array.isArray(c)) {
-        err('last-change: 缺少 lastChange 对象（整个交付说明都装在里面）');
-      } else {
-        if (!c.title) err('last-change: 缺少 title（这次交付做成了什么）');
-        if (!stampOk(c.at)) {
-          err('last-change: at 格式应为 YYYY-MM-DD HH:mm:ss（时分秒可省，但省了页面上只显示到天）');
-        } else if (typeof c.at === 'string' && c.at.length === 10) {
-          warn('last-change: at 只有日期，页面只会显示到天；建议写成 YYYY-MM-DD HH:mm:ss');
-        } else if (stampDate(c.at) > today) {
-          warn(`last-change: at ${c.at} 在未来`);
-        }
-
-        // 1. 故事 / 任务变更清单
-        const changes = Array.isArray(c.changes) ? c.changes : [];
-        if (!changes.length) warn('last-change: changes 为空（这次交付没碰任何故事或任务？）');
-        for (const [i, ch] of changes.entries()) {
-          const at = `last-change.changes[${i}]`;
-          if (!['story', 'task'].includes(ch.kind)) err(`${at}: kind 必须是 story / task，实际 ${ch.kind}`);
-          if (!ch.id) err(`${at}: 缺少 id`);
-          if (!ACTION.includes(ch.action)) err(`${at}: action 必须是 ${ACTION.join('/')}，实际 ${ch.action}`);
-          if (!ch.title) warn(`${at}: 缺 title，看板表格里只剩一个编号`);
-          if (ch.files !== undefined && !Array.isArray(ch.files)) err(`${at}: files 必须是数组`);
-          if (ch.kind === 'story' && ch.id && !storyById.has(ch.id)) err(`${at}: 故事 ${ch.id} 不存在`);
-          if (ch.kind === 'task' && ch.id && !taskById.has(ch.id)) err(`${at}: 任务 ${ch.id} 不存在`);
-        }
-
-        // 2. 额外做的事
-        for (const [i, x] of (Array.isArray(c.extras) ? c.extras : []).entries()) {
-          if (!x?.title) err(`last-change.extras[${i}]: 缺少 title（做了什么要写清）`);
-          if (x?.files !== undefined && !Array.isArray(x.files)) err(`last-change.extras[${i}]: files 必须是数组`);
-        }
-
-        // 3. 验证结果
-        for (const [i, v] of (Array.isArray(c.verification) ? c.verification : []).entries()) {
-          if (!v?.what) err(`last-change.verification[${i}]: 缺少 what（验的是哪一项）`);
-          if (!CHECK.includes(v?.result)) err(`last-change.verification[${i}]: result 必须是 ${CHECK.join('/')}，实际 ${v?.result}`);
-        }
-
-        // 4. 账号密码与调试地址
-        if (c.access !== undefined) {
-          for (const [i, u] of (Array.isArray(c.access?.urls) ? c.access.urls : []).entries()) {
-            if (!u?.label) warn(`last-change.access.urls[${i}]: 缺 label，看板只会显示一串地址`);
-            if (!/^https?:\/\/\S+$/.test(u?.url ?? '')) err(`last-change.access.urls[${i}]: url 必须是 http(s) 开头的完整地址，实际 ${u?.url}`);
-          }
-          for (const [i, a] of (Array.isArray(c.access?.accounts) ? c.access.accounts : []).entries()) {
-            if (!a?.username) err(`last-change.access.accounts[${i}]: 缺少 username`);
-            if (a?.password !== undefined && typeof a.password !== 'string') err(`last-change.access.accounts[${i}]: password 必须是字符串`);
-          }
-        }
-
-        // 5. 测试前准备
-        for (const [i, s] of (Array.isArray(c.preparation) ? c.preparation : []).entries()) {
-          if (!s?.step) err(`last-change.preparation[${i}]: 缺少 step（要做什么）`);
-        }
-
-        // 6. 逐条测试场景
-        for (const [i, s] of (Array.isArray(c.scenarios) ? c.scenarios : []).entries()) {
-          const at = `场景 ${s?.id ?? `#${i + 1}`}`;
-          if (!s?.id) warn(`last-change.scenarios[${i}]: 缺 id，逐条核对时没法引用`);
-          if (!s?.title) err(`last-change.${at}: 缺少 title`);
-          if (!s?.expect) err(`last-change.${at}: 缺少 expect（验收标准是什么）`);
-          if (s?.steps !== undefined && (!Array.isArray(s.steps) || s.steps.some(x => typeof x !== 'string' || !x.trim())))
-            err(`last-change.${at}: steps 必须是非空字符串数组（一步一条）`);
-          if (Array.isArray(s?.steps) && !s.steps.length) warn(`last-change.${at}: steps 为空，用户照着没法走`);
-        }
-
-        // 合并标记：未提交的旧记录被并进来时才出现
-        if (c.merged !== undefined && typeof c.merged !== 'boolean')
-          err('last-change.merged: 必须是布尔值');
-        if (c.mergedFrom !== undefined) {
-          if (!Array.isArray(c.mergedFrom)) err('last-change.mergedFrom: 必须是数组');
-          else for (const [i, m] of c.mergedFrom.entries()) {
-            if (!m?.title) err(`last-change.mergedFrom[${i}]: 缺少 title（并进来的是哪次交付）`);
-            if (m?.at !== undefined && !stampOk(m.at)) err(`last-change.mergedFrom[${i}]: at 格式应为 YYYY-MM-DD HH:mm:ss`);
-          }
-          if (Array.isArray(c.mergedFrom) && !c.mergedFrom.length) warn('last-change.mergedFrom: 空数组没有意义，删掉它');
-        }
-        if (c.merged === true && !(Array.isArray(c.mergedFrom) && c.mergedFrom.length))
-          warn('last-change.merged 为 true 但没写 mergedFrom，看板讲不清并了哪几次');
-
-        // 7. 说明 / 遗留
-        for (const key of ['notes', 'open']) {
-          if (c[key] !== undefined && (!Array.isArray(c[key]) || c[key].some(x => typeof x !== 'string')))
-            err(`last-change.${key}: 必须是字符串数组`);
-        }
-      }
-    }
-  }
-}
-
-// ---- tests.json（测试资产，可选文件） ----
-// 不存在 = 这个项目还没登记测试用例，合法（老项目升级不受影响）；
-// 存在就必须能被 /tests 页原样渲染，且能支撑「覆盖率缺口」的判断。
-{
-  const p = join(AGILE, 'tests.json');
-  if (existsSync(p)) {
-    const LAYER = ['frontend', 'backend', 'e2e'];
-    const LEVEL = ['unit', 'integration', 'e2e'];
-    const CASE_STATUS = ['pass', 'fail', 'skipped', 'blocked', 'not-run'];
-    const COVER_KEYS = ['lines', 'branches', 'functions', 'statements'];
-    const COVER_REF = /^(S-\d+)-A(\d+)$/;
-    let doc = null;
-    try {
-      doc = JSON.parse(readFileSync(p, 'utf8'));
-    } catch (e) {
-      err(`agile/tests.json: JSON 解析失败 - ${e.message}`);
-    }
-    if (doc) {
-      if (doc.schemaVersion !== 3) err(`agile/tests.json: schemaVersion 应为 3，实际 ${doc.schemaVersion}`);
-      const suites = Array.isArray(doc.suites) ? doc.suites : [];
-      const runs = Array.isArray(doc.runs) ? doc.runs : [];
-      if (!Array.isArray(doc.suites)) err('tests: suites 必须是数组（没有用例就写空数组）');
-      if (!Array.isArray(doc.runs)) err('tests: runs 必须是数组（没跑过就写空数组）');
-
-      const caseById = new Map();
-      const cases = [];
-      const coveredRefs = new Set();
-      const registeredStories = new Set();
-
-      for (const su of suites) {
-        claim(su.id, 'tests suite');
-        if (!su.name) err(`tests suite ${su.id ?? '?'}: 缺少 name`);
-        if (!LAYER.includes(su.layer)) err(`tests suite ${su.id}: layer 必须是 ${LAYER.join('/')}，实际 ${su.layer}`);
-        if (!LEVEL.includes(su.level)) err(`tests suite ${su.id}: level 必须是 ${LEVEL.join('/')}，实际 ${su.level}`);
-        if (su.files !== undefined && (!Array.isArray(su.files) || su.files.some(f => typeof f !== 'string')))
-          err(`tests suite ${su.id}: files 必须是字符串数组`);
-        if (!Array.isArray(su.cases) || su.cases.length === 0) {
-          warn(`tests suite ${su.id}: 没有用例（空套件不该留在清单里）`);
-        }
-        for (const c of su.cases ?? []) {
-          claim(c.id, `tests suite ${su.id} 的 case`);
-          if (!c.title) err(`tests case ${c.id ?? '?'}: 缺少 title`);
-          if (typeof c.automated !== 'boolean') err(`tests case ${c.id}: automated 必须是布尔值（手工用例也要登记）`);
-          if (!CASE_STATUS.includes(c.status))
-            err(`tests case ${c.id}: status 必须是 ${CASE_STATUS.join('/')}，实际 ${c.status}`);
-          if (!c.expect) err(`tests case ${c.id}: 缺少 expect（预期结果，QA 交付物不能只有标题）`);
-          if (c.status !== 'not-run') {
-            if (!DATE_RE.test(c.lastRun ?? '')) err(`tests case ${c.id}: lastRun 格式应为 YYYY-MM-DD（没跑过就写 not-run）`);
-            else if (c.lastRun > today) warn(`tests case ${c.id}: lastRun ${c.lastRun} 在未来`);
-          }
-          if (c.durationMs !== undefined && (!Number.isFinite(c.durationMs) || c.durationMs < 0))
-            err(`tests case ${c.id}: durationMs 必须是非负数字`);
-          if (c.covers !== undefined && !Array.isArray(c.covers)) err(`tests case ${c.id}: covers 必须是数组`);
-          const covers = Array.isArray(c.covers) ? c.covers : [];
-          for (const ref of covers) {
-            const m = COVER_REF.exec(typeof ref === 'string' ? ref : '');
-            if (!m) { err(`tests case ${c.id}: covers 的 ${ref} 格式应为 S-xxx-A<n>`); continue; }
-            const st = storyById.get(m[1]);
-            if (!st) { err(`tests case ${c.id}: covers 指向不存在的故事 ${m[1]}`); continue; }
-            const total = (st.acceptance ?? []).length;
-            if (Number(m[2]) < 1 || Number(m[2]) > total)
-              err(`tests case ${c.id}: covers ${ref} 越界（${st.id} 只有 ${total} 条验收）`);
-            else { coveredRefs.add(ref); registeredStories.add(st.id); }
-          }
-          if (c.taskId) {
-            const hit = taskById.get(c.taskId);
-            if (!hit) err(`tests case ${c.id}: task ${c.taskId} 不存在`);
-            else {
-              const storyIds = new Set(covers.map(r => String(r).replace(/-A\d+$/, '')).filter(id => storyById.has(id)));
-              if (storyIds.size && !storyIds.has(hit.story.id))
-                err(`tests case ${c.id}: task ${c.taskId} 属于 ${hit.story.id}，与 covers 指向的故事不一致`);
-            }
-          }
-          caseById.set(c.id, c);
-          cases.push(c);
-        }
-      }
-
-      // 执行记录：时间正序（最后一条 = 最近一次），汇总要自洽
-      let prev = '';
-      for (const [i, r] of runs.entries()) {
-        if (!stampOk(r.at)) err(`tests.runs[${i}]: at 格式应为 YYYY-MM-DD HH:mm:ss`);
-        else {
-          if (prev && r.at < prev) err(`tests.runs[${i}]: 必须按时间正序排（最新一条放最后），${prev} 之后出现了 ${r.at}`);
-          prev = r.at;
-        }
-        if (!r.command) warn(`tests.runs[${i}]: 缺少 command（这次是怎么跑起来的）`);
-        const t = r.totals;
-        if (!t || typeof t !== 'object') err(`tests.runs[${i}]: 缺少 totals`);
-        else {
-          for (const k of ['total', 'pass', 'fail', 'skipped']) {
-            if (!Number.isFinite(t[k])) err(`tests.runs[${i}].totals.${k}: 必须是数字`);
-          }
-          if (Number.isFinite(t.total) && (t.pass ?? 0) + (t.fail ?? 0) + (t.skipped ?? 0) > t.total)
-            err(`tests.runs[${i}].totals: 通过 + 失败 + 跳过 加总超过总数 ${t.total}，执行记录自相矛盾`);
-        }
-        if (r.failedCases !== undefined && !Array.isArray(r.failedCases))
-          err(`tests.runs[${i}]: failedCases 必须是数组`);
-        for (const id of r.failedCases ?? []) {
-          if (!caseById.has(id)) err(`tests.runs[${i}]: failedCases 里的 ${id} 不在用例清单里`);
-        }
-        if (r.coverage !== undefined) {
-          if (!r.coverage || typeof r.coverage !== 'object' || Array.isArray(r.coverage))
-            err(`tests.runs[${i}].coverage: 必须是按层的对象（frontend / backend）`);
-          for (const [layer, cov] of Object.entries(r.coverage ?? {})) {
-            if (!LAYER.includes(layer)) err(`tests.runs[${i}].coverage: 层的键只能是 ${LAYER.join('/')}，实际 ${layer}`);
-            if (!cov || typeof cov !== 'object') { err(`tests.runs[${i}].coverage.${layer}: 必须是对象`); continue; }
-            if (!cov.tool) warn(`tests.runs[${i}].coverage.${layer}: 缺少 tool（覆盖率是哪个工具出的）`);
-            for (const k of COVER_KEYS) {
-              if (cov[k] === undefined) continue;
-              if (!Number.isFinite(cov[k]) || cov[k] < 0 || cov[k] > 100)
-                err(`tests.runs[${i}].coverage.${layer}.${k}: 百分比必须在 0~100 之间，实际 ${cov[k]}`);
-            }
-          }
-        }
-      }
-
-      const latest = runs[runs.length - 1];
-      for (const id of latest?.failedCases ?? []) {
-        const c = caseById.get(id);
-        if (c && c.status !== 'fail')
-          err(`tests: 最新一次执行的 failedCases 里的 ${id} 状态是 ${c.status}，应为 fail（执行记录与用例清单不一致）`);
-      }
-      if (latest?.totals?.total > cases.length) {
-        warn(`tests.json 只登记了 ${cases.length} 条用例，最近一次执行共 ${latest.totals.total} 条：还有 ${latest.totals.total - cases.length} 条没登记`);
-      }
-
-      // 收口纪律：登记过用例的故事，不许漏 test 任务、不许漏验收
-      for (const s of stories) {
-        if (!registeredStories.has(s.id)) continue;
-        for (const t of s.tasks ?? []) {
-          if (t.type === 'test' && t.status === 'done' && !cases.some(c => c.taskId === t.id))
-            err(`task ${t.id}: 已 done 的 test 型任务没有登记用例（story ${s.id} 已经登记了用例，别漏这一条）`);
-        }
-        if (['review', 'done'].includes(s.status)) {
-          (s.acceptance ?? []).forEach((_, i) => {
-            const ref = `${s.id}-A${i + 1}`;
-            if (!coveredRefs.has(ref))
-              err(`story ${s.id}: 验收 ${ref} 没有任何用例覆盖（故事已到 ${s.status}）`);
-          });
-        }
-        for (const c of cases) {
-          if (!c.taskId || !c.lastRun) continue;
-          const hit = taskById.get(c.taskId);
-          if (!hit || hit.story.id !== s.id) continue;
-          const passes = (journalByTask.get(c.taskId)?.entries ?? []).filter(e => /^pass/i.test(e.result ?? ''));
-          const lastPass = passes[passes.length - 1]?.date;
-          if (lastPass && c.lastRun < lastPass)
-            warn(`tests case ${c.id}: lastRun ${c.lastRun} 早于 task ${c.taskId} 最后一次通过 ${lastPass}（结果该刷新了）`);
-        }
-      }
-
-      const doneStories = stories.filter(s => s.status === 'done');
-      const missing = doneStories.filter(s => !registeredStories.has(s.id));
-      if (missing.length) {
-        warn(`tests.json 只登记了 ${registeredStories.size} 个故事的用例，还有 ${missing.length} 个已完成故事完全没有用例`);
-      }
-    }
-  }
-}
-
-// ---- 输出 ----
-for (const w of warns) console.warn(`  WARN  ${w}`);
-if (errors.length === 0) {
-  const taskCount = taskById.size;
-  console.log(`✔ 校验通过：${epics.length} epics, ${stories.length} stories (${taskCount} tasks), ${sprints.length} sprints, ${milestones.length} milestones, ${journals.length} journals`);
-} else {
-  console.error(`✘ 校验失败，共 ${errors.length} 处错误：`);
-  for (const e of errors) console.error(`  - ${e}`);
-  process.exit(1);
-}
+#!/usr/bin/env node
+/**
+ * 敏捷数据校验脚本（零依赖，schema v3：三文件结构）
+ * 用法: node tools/validate.mjs [目标目录]   默认当前工作目录
+ * 校验 <目标>/agile/ 下 backlog.json / sprints.json / journal.json：
+ * 引用完整性（双向）、状态机、TDD 纪律、里程碑达成口径、
+ * 需求属性（type/priority/value/缺陷详情/验收覆盖）、依赖无环、阻塞与范围变更。
+ * 另外校验可选的 last-change.json（每次交付的汇报）：引用、动作枚举、验收口径、调试地址。
+ * 退出码: 0 通过, 1 有错误。
+ */
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve, normalize, isAbsolute } from 'node:path';
+
+const TARGET = resolve(process.argv[2] || process.cwd());
+const AGILE = join(TARGET, 'agile');
+const errors = [];
+const warns = [];
+const err = m => errors.push(m);
+const warn = m => warns.push(m);
+
+const FILES = { backlog: 'backlog.json', sprints: 'sprints.json', journal: 'journal.json' };
+const data = {};
+for (const [key, name] of Object.entries(FILES)) {
+  const p = join(AGILE, name);
+  if (!existsSync(p)) {
+    err(`agile/${name} 缺失（schema v2 只认三文件结构）`);
+    continue;
+  }
+  try {
+    data[key] = JSON.parse(readFileSync(p, 'utf8'));
+  } catch (e) {
+    err(`agile/${name}: JSON 解析失败 - ${e.message}`);
+    continue;
+  }
+  if (data[key].schemaVersion !== 3) err(`agile/${name}: schemaVersion 应为 3，实际 ${data[key].schemaVersion}`);
+}
+
+// v2 不兼容散文件结构：残留就报错，提醒合并
+for (const rel of ['backlog/epics', 'backlog/stories', 'sprints', 'journal']) {
+  const p = join(AGILE, rel);
+  if (existsSync(p) && statSync(p).isDirectory() && readdirSync(p).some(f => f.endsWith('.json')))
+    err(`agile/${rel}/ 仍有散文件 JSON：v2 只认三文件结构，请合并进 backlog.json / sprints.json / journal.json`);
+}
+
+const backlog = data.backlog ?? {};
+const sprintsFile = data.sprints ?? {};
+const journalFile = data.journal ?? {};
+const epics = Array.isArray(backlog.epics) ? backlog.epics : [];
+const stories = Array.isArray(backlog.stories) ? backlog.stories : [];
+const sprints = Array.isArray(sprintsFile.sprints) ? sprintsFile.sprints : [];
+const milestones = Array.isArray(sprintsFile.milestones) ? sprintsFile.milestones : [];
+const journals = Array.isArray(journalFile.journals) ? journalFile.journals : [];
+
+const STORY_FLOW = ['draft', 'ready', 'in-progress', 'review', 'done', 'cancelled'];
+// 终态：done 与 cancelled 都不再往前走，也不再要求验收 / 任务全部做完
+const STORY_TERMINAL = ['done', 'cancelled'];
+const TASK_FLOW = ['todo', 'red', 'green', 'refactored', 'done'];
+const EPIC_FLOW = ['draft', 'active', 'done', 'cancelled'];
+const MILESTONE_FLOW = ['planned', 'at-risk', 'reached', 'missed'];
+const STORY_KIND = ['feature', 'bug', 'debt', 'spike'];
+const PRIORITY = ['P0', 'P1', 'P2', 'P3'];
+const SEVERITY = ['blocker', 'major', 'minor', 'trivial'];
+const SCOPE_KIND = ['added-mid-sprint', 'split', 'expanded'];
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * 交付时间：`YYYY-MM-DD` 或 `YYYY-MM-DD HH:mm:ss`（也接受 ISO 的 T 分隔）。
+ * 日期必须真实存在（2026-13-01、2026-02-30 都不行），时分秒越界同样拦掉。
+ */
+const STAMP_RE = /^(\d{4}-\d{2}-\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?)?$/;
+const stampOk = value => {
+  const m = STAMP_RE.exec(typeof value === 'string' ? value : '');
+  if (!m) return false;
+  const [, date, hh, mm, ss] = m;
+  // 用 UTC 构造再比对：本地时区（东八区）下 new Date('…T00:00:00') 转 ISO 会退到前一天
+  const [y, mo, da] = date.split('-').map(Number);
+  const d = new Date(Date.UTC(y, mo - 1, da));
+  if (d.getUTCFullYear() !== y || d.getUTCMonth() !== mo - 1 || d.getUTCDate() !== da) return false;
+  if (hh === undefined) return true;
+  return Number(hh) <= 23 && Number(mm) <= 59 && Number(ss ?? 0) <= 59;
+};
+const stampDate = value => (typeof value === 'string' ? value.slice(0, 10) : '');
+// 用本地日期判定「今天」，避免 UTC 偏移导致活跃迭代判定差一天
+const now = new Date();
+const today = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
+
+// ---- 全局唯一 id ----
+const ids = new Set();
+function claim(id, where) {
+  if (!id) { err(`${where}: 缺少 id`); return; }
+  if (ids.has(id)) err(`${where}: id ${id} 重复`);
+  else ids.add(id);
+}
+for (const e of epics) claim(e.id, 'epic');
+for (const s of stories) {
+  claim(s.id, 'story');
+  for (const t of s.tasks ?? []) {
+    claim(t.id, `story ${s.id} 的 task`);
+    if (t.id && !t.id.startsWith(`${s.id}-T`)) err(`task ${t.id}: 命名应为 ${s.id}-T<n>`);
+  }
+}
+for (const sp of sprints) claim(sp.id, 'sprint');
+for (const m of milestones) claim(m.id, 'milestone');
+
+const epicById = new Map(epics.map(e => [e.id, e]));
+const storyById = new Map(stories.map(s => [s.id, s]));
+const sprintById = new Map(sprints.map(s => [s.id, s]));
+const taskById = new Map();
+for (const s of stories) for (const t of s.tasks ?? []) taskById.set(t.id, { task: t, story: s });
+
+// ---- 依赖图必须是有向无环 ----
+{
+  const state = new Map(); // 1=访问中 2=已完成
+  const visit = (id, path) => {
+    const st = state.get(id) ?? 0;
+    if (st === 2) return;
+    if (st === 1) { err(`story 依赖成环: ${[...path, id].join(' → ')}`); return; }
+    state.set(id, 1);
+    for (const dep of storyById.get(id)?.dependsOn ?? []) if (storyById.has(dep)) visit(dep, [...path, id]);
+    state.set(id, 2);
+  };
+  for (const s of stories) visit(s.id, []);
+}
+
+// ---- Epic ----
+for (const e of epics) {
+  if (!EPIC_FLOW.includes(e.status)) err(`epic ${e.id}: 非法状态 ${e.status}`);
+  if (!e.title) err(`epic ${e.id}: 缺少 title`);
+  if (!e.goal) err(`epic ${e.id}: 缺少 goal`);
+  if (!Array.isArray(e.keyResults) || e.keyResults.length === 0) warn(`epic ${e.id}: 没有 keyResults（史诗要有量化目标，否则完成与否全靠感觉）`);
+  for (const kr of e.keyResults ?? []) {
+    if (!kr.id) err(`epic ${e.id}: keyResult 缺少 id`);
+    if (!kr.text) err(`epic ${e.id}: keyResult ${kr.id ?? '?'} 缺少 text`);
+    if (!Number.isFinite(kr.target)) err(`epic ${e.id}: keyResult ${kr.id ?? '?'} 的 target 必须是数字`);
+    if (!Number.isFinite(kr.current)) warn(`epic ${e.id}: keyResult ${kr.id ?? '?'} 没有 current，算不出进度`);
+  }
+  for (const sid of e.stories ?? []) {
+    const st = storyById.get(sid);
+    if (!st) { err(`epic ${e.id}: 引用 story ${sid} 不存在`); continue; }
+    if (st.epicId !== e.id) err(`epic ${e.id}: story ${sid} 的 epicId 是 ${st.epicId}，双向引用不一致`);
+  }
+  if (e.status === 'done') {
+    for (const sid of e.stories ?? []) {
+      const st = storyById.get(sid);
+      if (st && !['done', 'cancelled'].includes(st.status))
+        err(`epic ${e.id} 已 done 但 story ${sid} 状态为 ${st.status}`);
+    }
+  }
+}
+
+// ---- Story ----
+for (const s of stories) {
+  const { id, epicId, sprintId, status, acceptance, tasks, points } = s;
+  if (!s.title) err(`story ${id}: 缺少 title`);
+  if (!epicId) warn(`story ${id}: 未挂 epic`);
+  else if (!epicById.has(epicId)) err(`story ${id}: epicId ${epicId} 不存在`);
+  else if (!(epicById.get(epicId).stories ?? []).includes(id))
+    err(`story ${id}: 挂在 ${epicId} 上，但该 epic 的 stories 里没有它（双向引用不一致）`);
+
+  if (!STORY_FLOW.includes(status))
+    err(`story ${id}: 非法状态 ${status}（合法：${STORY_FLOW.join('/')}）`);
+  if (!Number.isFinite(points)) err(`story ${id}: points 必须是数字`);
+  else if (![1, 2, 3, 5, 8, 13].includes(points)) warn(`story ${id}: points ${points} 不在斐波那契序列`);
+
+  // 需求属性：类型 / 优先级 / 价值
+  if (!STORY_KIND.includes(s.type)) err(`story ${id}: type 必须是 ${STORY_KIND.join('/')}，实际 ${s.type}`);
+  if (!PRIORITY.includes(s.priority)) err(`story ${id}: priority 必须是 ${PRIORITY.join('/')}，实际 ${s.priority}`);
+  if (!Number.isFinite(s.value) || s.value <= 0) err(`story ${id}: value 必须是正数（用于算 WSJF）`);
+  if (s.type === 'bug') {
+    if (!s.bug) err(`story ${id}: type 为 bug 但缺少 bug 详情`);
+    else {
+      if (!SEVERITY.includes(s.bug.severity)) err(`story ${id}: bug.severity 必须是 ${SEVERITY.join('/')}`);
+      if (!s.bug.environment) err(`story ${id}: bug 缺少 environment（什么环境能复现）`);
+      if (!s.bug.steps) err(`story ${id}: bug 缺少 steps（怎么复现）`);
+    }
+  }
+
+  // 取消掉的故事不会再交付，别逼着为它补验收标准
+  if (['ready', 'in-progress', 'review', 'done'].includes(status) && (!acceptance || acceptance.length === 0))
+    err(`story ${id}: 状态 ${status} 但验收标准为空`);
+  for (const [i, a] of (acceptance ?? []).entries()) {
+    if (!a.given || !a.when || !a.then) err(`story ${id}: 第 ${i + 1} 条验收标准缺 given/when/then`);
+    // 每条验收都要能被某个 task 的测试验证，否则「验收」只是口号
+    for (const tid of a.verifyBy ?? []) {
+      const hit = taskById.get(tid);
+      if (!hit) err(`story ${id}: 第 ${i + 1} 条验收的 verifyBy ${tid} 不存在`);
+      else if (hit.story.id !== id) err(`story ${id}: 第 ${i + 1} 条验收的 verifyBy ${tid} 属于 ${hit.story.id}`);
+    }
+    if (!(a.verifyBy ?? []).length && !['draft', 'cancelled'].includes(status))
+      warn(`story ${id}: 第 ${i + 1} 条验收没有 verifyBy（没绑定验证任务）`);
+  }
+
+  // 阻塞 / 依赖
+  for (const dep of s.dependsOn ?? []) {
+    if (dep === id) err(`story ${id}: 不能依赖自己`);
+    else if (!storyById.has(dep)) err(`story ${id}: dependsOn 引用了不存在的 story ${dep}`);
+  }
+  if (s.blocked) {
+    if (!s.blocked.reason) err(`story ${id}: blocked 缺少 reason（堵在哪要说清）`);
+    if (!DATE_RE.test(s.blocked.since ?? '')) err(`story ${id}: blocked.since 格式应为 YYYY-MM-DD`);
+    if (status === 'done') err(`story ${id}: 已 done 却还标着 blocked`);
+    if (status === 'cancelled') err(`story ${id}: 已取消却还标着 blocked（不做了就别再挂着阻塞）`);
+    if (sprintId && !STORY_TERMINAL.includes(status))
+      warn(`story ${id}: 处于 ${sprintId} 但被阻塞（${s.blocked.reason}），站会必须处理`);
+  }
+
+  // 范围变更标记
+  if (s.scopeChange) {
+    if (!SCOPE_KIND.includes(s.scopeChange.kind)) err(`story ${id}: scopeChange.kind 必须是 ${SCOPE_KIND.join('/')}`);
+    if (!DATE_RE.test(s.scopeChange.at ?? '')) err(`story ${id}: scopeChange.at 格式应为 YYYY-MM-DD`);
+    else if (s.scopeChange.at > today) warn(`story ${id}: scopeChange.at ${s.scopeChange.at} 在未来`);
+    if (!s.scopeChange.reason) warn(`story ${id}: scopeChange 缺少 reason`);
+  }
+
+  if (sprintId) {
+    const sp = sprintById.get(sprintId);
+    if (!sp) err(`story ${id}: sprintId ${sprintId} 不存在`);
+    else if (!(sp.stories ?? []).includes(id))
+      err(`story ${id}: 指向 ${sprintId}，但该 sprint 的 stories 里没有它（双向引用不一致）`);
+    if (status !== 'cancelled' && (!acceptance || acceptance.length === 0))
+      err(`story ${id}: 已进 sprint 但无验收标准（不满足 ready）`);
+  }
+
+  if (s.schedule) {
+    const { start, end } = s.schedule;
+    if (!DATE_RE.test(start ?? '') || !DATE_RE.test(end ?? '')) err(`story ${id}: schedule 日期格式应为 YYYY-MM-DD`);
+    else if (start > end) err(`story ${id}: schedule 起点 ${start} 晚于终点 ${end}`);
+    else if (!sprintId) warn(`story ${id}: 未排期却有计划区间 ${start}~${end}`);
+    else {
+      const sp = sprintById.get(sprintId);
+      if (sp && (start < sp.start || end > sp.end))
+        warn(`story ${id}: 计划区间 ${start}~${end} 超出 ${sprintId}（${sp.start}~${sp.end}）`);
+    }
+  }
+
+  if (!Array.isArray(tasks) || tasks.length === 0) warn(`story ${id}: 没有拆 task，TDD 无从落地`);
+  for (const t of tasks ?? []) {
+    if (!TASK_FLOW.includes(t.status)) err(`task ${t.id}: 非法状态 ${t.status}`);
+    if (!['test', 'impl', 'refactor', 'chore'].includes(t.type)) err(`task ${t.id}: 非法类型 ${t.type}`);
+    if (!t.title) err(`task ${t.id}: 缺少 title`);
+  }
+  if (status === 'done') {
+    for (const t of tasks ?? []) {
+      if (t.status !== 'done') err(`story ${id} 已 done 但 task ${t.id} 状态为 ${t.status}`);
+    }
+  }
+}
+
+// ---- Sprint ----
+let active = 0;
+for (const sp of sprints) {
+  if (!sp.name) warn(`sprint ${sp.id}: 缺少 name`);
+  if (!DATE_RE.test(sp.start ?? '') || !DATE_RE.test(sp.end ?? '')) err(`sprint ${sp.id}: 起止日期格式应为 YYYY-MM-DD`);
+  else if (sp.start > sp.end) err(`sprint ${sp.id}: 起点 ${sp.start} 晚于终点 ${sp.end}`);
+  if (!Number.isFinite(sp.capacity)) err(`sprint ${sp.id}: capacity 必须是数字`);
+  for (const sid of sp.stories ?? []) {
+    const st = storyById.get(sid);
+    if (!st) { err(`sprint ${sp.id}: 引用 story ${sid} 不存在`); continue; }
+    if (st.sprintId !== sp.id) err(`sprint ${sp.id}: story ${sid} 的 sprintId 是 ${st.sprintId}，双向引用不一致`);
+    if (st.status === 'cancelled')
+      warn(`story ${sid}: 已取消但仍排在 ${sp.id} 里，建议从迭代移出（点数已不计入承诺）`);
+  }
+  // 已取消的故事不再占迭代容量：承诺点数只算还可能交付的
+  const committed = (sp.stories ?? []).reduce((a, sid) => {
+    const st = storyById.get(sid);
+    return st && st.status !== 'cancelled' ? a + (st.points ?? 0) : a;
+  }, 0);
+  if (Number.isFinite(sp.capacity) && committed > sp.capacity)
+    warn(`sprint ${sp.id}: 承诺 ${committed} 点超过容量 ${sp.capacity} 点`);
+  if (sp.start <= today && sp.end >= today) active++;
+}
+if (active > 1) err(`同时存在 ${active} 个活跃 sprint，只允许一个`);
+
+// ---- 迭代 id 规则：R<发布周期>-S<期内冲刺号>，或纯序号 S-01 ----
+{
+  const SPRINT_ID_RE = /^(?:R(\d+)-)?S-?(\d{1,2})$/;
+  const parsed = [];
+  for (const sp of sprints) {
+    const m = SPRINT_ID_RE.exec(sp.id ?? '');
+    if (!m) { err(`sprint ${sp.id}: id 必须形如 R1-S1（发布周期-冲刺）或 S-01（纯序号）`); continue; }
+    parsed.push({ sp, release: m[1] ?? null, seq: Number(m[2]) });
+  }
+  const styles = new Set(parsed.map(p => (p.release === null ? 'seq' : 'rel')));
+  if (styles.size > 1) err('sprint id 风格混用：R<n>-S<n> 与 S-<n> 不许同时出现');
+
+  const byRelease = new Map();
+  for (const p of parsed) {
+    const key = p.release ?? 'seq';
+    if (!byRelease.has(key)) byRelease.set(key, []);
+    byRelease.get(key).push(p);
+  }
+
+  for (const [key, list] of byRelease) {
+    const seqs = list.map(p => p.seq).sort((a, b) => a - b);
+    const dup = seqs.find((v, i) => i > 0 && v === seqs[i - 1]);
+    if (dup) err(`发布周期 ${key} 内冲刺序号重复：S${dup}`);
+    else if (seqs.some((v, i) => v !== i + 1))
+      err(`发布周期 ${key} 内冲刺序号应为 S1..S${seqs.length} 连续，实际 ${seqs.map(s => `S${s}`).join('/')}`);
+    if (list.length > 2) warn(`发布周期 ${key} 内有 ${list.length} 个冲刺（约定一期不超过 2 个）`);
+  }
+
+  // 期号越大，起始日期应越晚
+  const rels = [...byRelease.entries()]
+    .filter(([k]) => k !== 'seq')
+    .map(([k, list]) => ({ r: Number(k), start: list.map(p => p.sp.start).sort()[0] }))
+    .sort((a, b) => a.r - b.r);
+  for (let i = 1; i < rels.length; i++) {
+    if (rels[i].start < rels[i - 1].start)
+      warn(`发布周期 R${rels[i].r} 起始 ${rels[i].start} 早于 R${rels[i - 1].r}（${rels[i - 1].start}），期号与时间顺序不一致`);
+  }
+}
+
+// ---- Milestone ----
+for (const m of milestones) {
+  if (!m.title) err(`milestone ${m.id}: 缺少 title`);
+  if (!['mvp', 'release', 'checkpoint'].includes(m.kind)) err(`milestone ${m.id}: 非法 kind ${m.kind}`);
+  if (!MILESTONE_FLOW.includes(m.status)) err(`milestone ${m.id}: 非法状态 ${m.status}`);
+  if (!DATE_RE.test(m.due ?? '')) err(`milestone ${m.id}: due 格式应为 YYYY-MM-DD`);
+  if (!m.criteria) warn(`milestone ${m.id}: 缺少 criteria（达成口径），没法判断是否 reached`);
+  if (m.sprintId) {
+    const sp = sprintById.get(m.sprintId);
+    if (!sp) err(`milestone ${m.id}: sprintId ${m.sprintId} 不存在`);
+    else if (DATE_RE.test(m.due ?? '') && m.due > sp.end)
+      warn(`milestone ${m.id}: due ${m.due} 晚于所属 ${m.sprintId} 结束日 ${sp.end}`);
+  }
+  if (!(m.stories ?? []).length) warn(`milestone ${m.id}: 没有挂任何 story，无法验证达成`);
+  for (const sid of m.stories ?? []) {
+    if (!storyById.has(sid)) err(`milestone ${m.id}: 引用 story ${sid} 不存在`);
+  }
+  if (m.status === 'reached') {
+    for (const sid of m.stories ?? []) {
+      const st = storyById.get(sid);
+      if (st && !['done', 'cancelled'].includes(st.status))
+        err(`milestone ${m.id} 已 reached 但 story ${sid} 状态为 ${st.status}`);
+    }
+  }
+  if (m.status === 'planned' && DATE_RE.test(m.due ?? '') && m.due < today)
+    warn(`milestone ${m.id}: 状态 planned 但 due ${m.due} 已过期，应改成 at-risk / missed`);
+}
+
+// ---- Journal 与 TDD 纪律 ----
+const journalByTask = new Map();
+for (const j of journals) {
+  if (!j.taskId) { err('journal: 缺少 taskId'); continue; }
+  if (journalByTask.has(j.taskId)) err(`journal: taskId ${j.taskId} 重复`);
+  journalByTask.set(j.taskId, j);
+  const hit = taskById.get(j.taskId);
+  if (!hit) { err(`journal ${j.taskId}: 不指向任何真实 task`); continue; }
+  if (j.storyId !== hit.story.id) err(`journal ${j.taskId}: storyId ${j.storyId} 与 task 所属 ${hit.story.id} 不一致`);
+  let prev = '';
+  for (const e of j.entries ?? []) {
+    if (!['red', 'green', 'refactor'].includes(e.phase)) err(`journal ${j.taskId}: 非法 phase ${e.phase}`);
+    if (!DATE_RE.test(e.date ?? '')) err(`journal ${j.taskId}: date 格式应为 YYYY-MM-DD`);
+    else if (e.date > today) warn(`journal ${j.taskId}: 记录日期 ${e.date} 在未来`);
+    if (prev && e.date < prev) err(`journal ${j.taskId}: 记录日期倒序 ${prev} → ${e.date}`);
+    prev = e.date;
+    if (!e.note) warn(`journal ${j.taskId}: ${e.phase} 缺 note`);
+    if (!e.result) warn(`journal ${j.taskId}: ${e.phase} 缺 result`);
+  }
+}
+
+for (const [tid, { task }] of taskById) {
+  const hasRed = ['red', 'green', 'refactored', 'done'].includes(task.status);
+  const hasGreen = ['green', 'refactored', 'done'].includes(task.status);
+  const j = journalByTask.get(tid);
+  if (!hasRed) {
+    if (j && (j.entries ?? []).length > 0) warn(`${tid}: 尚在 todo 但 journal 已有实施记录（检查是否提前动了手）`);
+    continue;
+  }
+  if (!j) { err(`task ${tid}: 状态 ${task.status} 但 journal 缺失`); continue; }
+  const entries = j.entries ?? [];
+  const firstRed = entries.findIndex(e => e.phase === 'red');
+  const firstGreen = entries.findIndex(e => e.phase === 'green');
+  if (firstRed < 0) err(`task ${tid}: journal 没有 red 记录（先写失败测试的铁律被违反）`);
+  else if (entries[firstRed].result && !/^fail/i.test(entries[firstRed].result))
+    err(`task ${tid}: 第一条 red 记录的 result 应为 fail，实际 "${entries[firstRed].result}"`);
+  if (hasGreen) {
+    if (firstGreen < 0) err(`task ${tid}: 状态已过 red 但 journal 没有 green 记录`);
+    else if (entries[firstGreen].result && !/^pass/i.test(entries[firstGreen].result))
+      err(`task ${tid}: 第一条 green 记录的 result 应为 pass`);
+  }
+  if (task.status === 'done') {
+    const last = entries[entries.length - 1];
+    if (!last || !last.result || !/^pass/i.test(last.result))
+      err(`task ${tid}: 已 done 但 journal 末条记录不是 pass`);
+  }
+}
+
+// ---- last-change.json（每次交付的汇报，可选文件） ----
+// 文件不存在 = 还没交付过东西，合法；存在就必须能被看板「最后更新」页原样渲染。
+{
+  const p = join(AGILE, 'last-change.json');
+  if (existsSync(p)) {
+    const ACTION = ['added', 'updated', 'removed'];
+    const CHECK = ['pass', 'fail', 'partial', 'skipped'];
+    let doc = null;
+    try {
+      doc = JSON.parse(readFileSync(p, 'utf8'));
+    } catch (e) {
+      err(`agile/last-change.json: JSON 解析失败 - ${e.message}`);
+    }
+    if (doc) {
+      if (doc.schemaVersion !== 3) err(`agile/last-change.json: schemaVersion 应为 3，实际 ${doc.schemaVersion}`);
+      const c = doc.lastChange;
+      if (!c || typeof c !== 'object' || Array.isArray(c)) {
+        err('last-change: 缺少 lastChange 对象（整个交付说明都装在里面）');
+      } else {
+        if (!c.title) err('last-change: 缺少 title（这次交付做成了什么）');
+        if (!stampOk(c.at)) {
+          err('last-change: at 格式应为 YYYY-MM-DD HH:mm:ss（时分秒可省，但省了页面上只显示到天）');
+        } else if (typeof c.at === 'string' && c.at.length === 10) {
+          warn('last-change: at 只有日期，页面只会显示到天；建议写成 YYYY-MM-DD HH:mm:ss');
+        } else if (stampDate(c.at) > today) {
+          warn(`last-change: at ${c.at} 在未来`);
+        }
+
+        // 1. 故事 / 任务变更清单
+        const changes = Array.isArray(c.changes) ? c.changes : [];
+        if (!changes.length) warn('last-change: changes 为空（这次交付没碰任何故事或任务？）');
+        for (const [i, ch] of changes.entries()) {
+          const at = `last-change.changes[${i}]`;
+          if (!['story', 'task'].includes(ch.kind)) err(`${at}: kind 必须是 story / task，实际 ${ch.kind}`);
+          if (!ch.id) err(`${at}: 缺少 id`);
+          if (!ACTION.includes(ch.action)) err(`${at}: action 必须是 ${ACTION.join('/')}，实际 ${ch.action}`);
+          if (!ch.title) warn(`${at}: 缺 title，看板表格里只剩一个编号`);
+          if (ch.files !== undefined && !Array.isArray(ch.files)) err(`${at}: files 必须是数组`);
+          if (ch.kind === 'story' && ch.id && !storyById.has(ch.id)) err(`${at}: 故事 ${ch.id} 不存在`);
+          if (ch.kind === 'task' && ch.id && !taskById.has(ch.id)) err(`${at}: 任务 ${ch.id} 不存在`);
+        }
+
+        // 2. 额外做的事
+        for (const [i, x] of (Array.isArray(c.extras) ? c.extras : []).entries()) {
+          if (!x?.title) err(`last-change.extras[${i}]: 缺少 title（做了什么要写清）`);
+          if (x?.files !== undefined && !Array.isArray(x.files)) err(`last-change.extras[${i}]: files 必须是数组`);
+        }
+
+        // 3. 验证结果
+        for (const [i, v] of (Array.isArray(c.verification) ? c.verification : []).entries()) {
+          if (!v?.what) err(`last-change.verification[${i}]: 缺少 what（验的是哪一项）`);
+          if (!CHECK.includes(v?.result)) err(`last-change.verification[${i}]: result 必须是 ${CHECK.join('/')}，实际 ${v?.result}`);
+        }
+
+        // 4. 账号密码与调试地址
+        if (c.access !== undefined) {
+          for (const [i, u] of (Array.isArray(c.access?.urls) ? c.access.urls : []).entries()) {
+            if (!u?.label) warn(`last-change.access.urls[${i}]: 缺 label，看板只会显示一串地址`);
+            if (!/^https?:\/\/\S+$/.test(u?.url ?? '')) err(`last-change.access.urls[${i}]: url 必须是 http(s) 开头的完整地址，实际 ${u?.url}`);
+          }
+          for (const [i, a] of (Array.isArray(c.access?.accounts) ? c.access.accounts : []).entries()) {
+            if (!a?.username) err(`last-change.access.accounts[${i}]: 缺少 username`);
+            if (a?.password !== undefined && typeof a.password !== 'string') err(`last-change.access.accounts[${i}]: password 必须是字符串`);
+          }
+        }
+
+        // 5. 测试前准备
+        for (const [i, s] of (Array.isArray(c.preparation) ? c.preparation : []).entries()) {
+          if (!s?.step) err(`last-change.preparation[${i}]: 缺少 step（要做什么）`);
+        }
+
+        // 6. 逐条测试场景
+        for (const [i, s] of (Array.isArray(c.scenarios) ? c.scenarios : []).entries()) {
+          const at = `场景 ${s?.id ?? `#${i + 1}`}`;
+          if (!s?.id) warn(`last-change.scenarios[${i}]: 缺 id，逐条核对时没法引用`);
+          if (!s?.title) err(`last-change.${at}: 缺少 title`);
+          if (!s?.expect) err(`last-change.${at}: 缺少 expect（验收标准是什么）`);
+          if (s?.steps !== undefined && (!Array.isArray(s.steps) || s.steps.some(x => typeof x !== 'string' || !x.trim())))
+            err(`last-change.${at}: steps 必须是非空字符串数组（一步一条）`);
+          if (Array.isArray(s?.steps) && !s.steps.length) warn(`last-change.${at}: steps 为空，用户照着没法走`);
+        }
+
+        // 合并标记：未提交的旧记录被并进来时才出现
+        if (c.merged !== undefined && typeof c.merged !== 'boolean')
+          err('last-change.merged: 必须是布尔值');
+        if (c.mergedFrom !== undefined) {
+          if (!Array.isArray(c.mergedFrom)) err('last-change.mergedFrom: 必须是数组');
+          else for (const [i, m] of c.mergedFrom.entries()) {
+            if (!m?.title) err(`last-change.mergedFrom[${i}]: 缺少 title（并进来的是哪次交付）`);
+            if (m?.at !== undefined && !stampOk(m.at)) err(`last-change.mergedFrom[${i}]: at 格式应为 YYYY-MM-DD HH:mm:ss`);
+          }
+          if (Array.isArray(c.mergedFrom) && !c.mergedFrom.length) warn('last-change.mergedFrom: 空数组没有意义，删掉它');
+        }
+        if (c.merged === true && !(Array.isArray(c.mergedFrom) && c.mergedFrom.length))
+          warn('last-change.merged 为 true 但没写 mergedFrom，看板讲不清并了哪几次');
+
+        // 7. 说明 / 遗留
+        for (const key of ['notes', 'open']) {
+          if (c[key] !== undefined && (!Array.isArray(c[key]) || c[key].some(x => typeof x !== 'string')))
+            err(`last-change.${key}: 必须是字符串数组`);
+        }
+      }
+    }
+  }
+}
+
+// ---- tests.json（测试资产，可选文件） ----
+// 不存在 = 这个项目还没登记测试用例，合法（老项目升级不受影响）；
+// 存在就必须能被 /tests 页原样渲染，且能支撑「覆盖率缺口」的判断。
+{
+  const p = join(AGILE, 'tests.json');
+  if (existsSync(p)) {
+    const LAYER = ['frontend', 'backend', 'e2e'];
+    const LEVEL = ['unit', 'integration', 'e2e'];
+    const CASE_STATUS = ['pass', 'fail', 'skipped', 'blocked', 'not-run'];
+    const COVER_KEYS = ['lines', 'branches', 'functions', 'statements'];
+    const COVER_REF = /^(S-\d+)-A(\d+)$/;
+    let doc = null;
+    try {
+      doc = JSON.parse(readFileSync(p, 'utf8'));
+    } catch (e) {
+      err(`agile/tests.json: JSON 解析失败 - ${e.message}`);
+    }
+    if (doc) {
+      if (doc.schemaVersion !== 3) err(`agile/tests.json: schemaVersion 应为 3，实际 ${doc.schemaVersion}`);
+      const suites = Array.isArray(doc.suites) ? doc.suites : [];
+      const runs = Array.isArray(doc.runs) ? doc.runs : [];
+      if (!Array.isArray(doc.suites)) err('tests: suites 必须是数组（没有用例就写空数组）');
+      if (!Array.isArray(doc.runs)) err('tests: runs 必须是数组（没跑过就写空数组）');
+
+      const caseById = new Map();
+      const cases = [];
+      const coveredRefs = new Set();
+      const registeredStories = new Set();
+
+      for (const su of suites) {
+        claim(su.id, 'tests suite');
+        if (!su.name) err(`tests suite ${su.id ?? '?'}: 缺少 name`);
+        if (!LAYER.includes(su.layer)) err(`tests suite ${su.id}: layer 必须是 ${LAYER.join('/')}，实际 ${su.layer}`);
+        if (!LEVEL.includes(su.level)) err(`tests suite ${su.id}: level 必须是 ${LEVEL.join('/')}，实际 ${su.level}`);
+        if (su.files !== undefined && (!Array.isArray(su.files) || su.files.some(f => typeof f !== 'string')))
+          err(`tests suite ${su.id}: files 必须是字符串数组`);
+        if (!Array.isArray(su.cases) || su.cases.length === 0) {
+          warn(`tests suite ${su.id}: 没有用例（空套件不该留在清单里）`);
+        }
+        for (const c of su.cases ?? []) {
+          claim(c.id, `tests suite ${su.id} 的 case`);
+          if (!c.title) err(`tests case ${c.id ?? '?'}: 缺少 title`);
+          if (typeof c.automated !== 'boolean') err(`tests case ${c.id}: automated 必须是布尔值（手工用例也要登记）`);
+          if (!CASE_STATUS.includes(c.status))
+            err(`tests case ${c.id}: status 必须是 ${CASE_STATUS.join('/')}，实际 ${c.status}`);
+          if (!c.expect) err(`tests case ${c.id}: 缺少 expect（预期结果，QA 交付物不能只有标题）`);
+          if (c.status !== 'not-run') {
+            if (!DATE_RE.test(c.lastRun ?? '')) err(`tests case ${c.id}: lastRun 格式应为 YYYY-MM-DD（没跑过就写 not-run）`);
+            else if (c.lastRun > today) warn(`tests case ${c.id}: lastRun ${c.lastRun} 在未来`);
+          }
+          if (c.durationMs !== undefined && (!Number.isFinite(c.durationMs) || c.durationMs < 0))
+            err(`tests case ${c.id}: durationMs 必须是非负数字`);
+          if (c.covers !== undefined && !Array.isArray(c.covers)) err(`tests case ${c.id}: covers 必须是数组`);
+          const covers = Array.isArray(c.covers) ? c.covers : [];
+          for (const ref of covers) {
+            const m = COVER_REF.exec(typeof ref === 'string' ? ref : '');
+            if (!m) { err(`tests case ${c.id}: covers 的 ${ref} 格式应为 S-xxx-A<n>`); continue; }
+            const st = storyById.get(m[1]);
+            if (!st) { err(`tests case ${c.id}: covers 指向不存在的故事 ${m[1]}`); continue; }
+            const total = (st.acceptance ?? []).length;
+            if (Number(m[2]) < 1 || Number(m[2]) > total)
+              err(`tests case ${c.id}: covers ${ref} 越界（${st.id} 只有 ${total} 条验收）`);
+            else { coveredRefs.add(ref); registeredStories.add(st.id); }
+          }
+          if (c.taskId) {
+            const hit = taskById.get(c.taskId);
+            if (!hit) err(`tests case ${c.id}: task ${c.taskId} 不存在`);
+            else {
+              const storyIds = new Set(covers.map(r => String(r).replace(/-A\d+$/, '')).filter(id => storyById.has(id)));
+              if (storyIds.size && !storyIds.has(hit.story.id))
+                err(`tests case ${c.id}: task ${c.taskId} 属于 ${hit.story.id}，与 covers 指向的故事不一致`);
+            }
+          }
+          caseById.set(c.id, c);
+          cases.push(c);
+        }
+      }
+
+      // 执行记录：时间正序（最后一条 = 最近一次），汇总要自洽
+      let prev = '';
+      for (const [i, r] of runs.entries()) {
+        if (!stampOk(r.at)) err(`tests.runs[${i}]: at 格式应为 YYYY-MM-DD HH:mm:ss`);
+        else {
+          if (prev && r.at < prev) err(`tests.runs[${i}]: 必须按时间正序排（最新一条放最后），${prev} 之后出现了 ${r.at}`);
+          prev = r.at;
+        }
+        if (!r.command) warn(`tests.runs[${i}]: 缺少 command（这次是怎么跑起来的）`);
+        const t = r.totals;
+        if (!t || typeof t !== 'object') err(`tests.runs[${i}]: 缺少 totals`);
+        else {
+          for (const k of ['total', 'pass', 'fail', 'skipped']) {
+            if (!Number.isFinite(t[k])) err(`tests.runs[${i}].totals.${k}: 必须是数字`);
+          }
+          if (Number.isFinite(t.total) && (t.pass ?? 0) + (t.fail ?? 0) + (t.skipped ?? 0) > t.total)
+            err(`tests.runs[${i}].totals: 通过 + 失败 + 跳过 加总超过总数 ${t.total}，执行记录自相矛盾`);
+        }
+        if (r.failedCases !== undefined && !Array.isArray(r.failedCases))
+          err(`tests.runs[${i}]: failedCases 必须是数组`);
+        for (const id of r.failedCases ?? []) {
+          if (!caseById.has(id)) err(`tests.runs[${i}]: failedCases 里的 ${id} 不在用例清单里`);
+        }
+        if (r.coverage !== undefined) {
+          if (!r.coverage || typeof r.coverage !== 'object' || Array.isArray(r.coverage))
+            err(`tests.runs[${i}].coverage: 必须是按层的对象（frontend / backend）`);
+          for (const [layer, cov] of Object.entries(r.coverage ?? {})) {
+            if (!LAYER.includes(layer)) err(`tests.runs[${i}].coverage: 层的键只能是 ${LAYER.join('/')}，实际 ${layer}`);
+            if (!cov || typeof cov !== 'object') { err(`tests.runs[${i}].coverage.${layer}: 必须是对象`); continue; }
+            if (!cov.tool) warn(`tests.runs[${i}].coverage.${layer}: 缺少 tool（覆盖率是哪个工具出的）`);
+            for (const k of COVER_KEYS) {
+              if (cov[k] === undefined) continue;
+              if (!Number.isFinite(cov[k]) || cov[k] < 0 || cov[k] > 100)
+                err(`tests.runs[${i}].coverage.${layer}.${k}: 百分比必须在 0~100 之间，实际 ${cov[k]}`);
+            }
+          }
+        }
+      }
+
+      const latest = runs[runs.length - 1];
+      for (const id of latest?.failedCases ?? []) {
+        const c = caseById.get(id);
+        if (c && c.status !== 'fail')
+          err(`tests: 最新一次执行的 failedCases 里的 ${id} 状态是 ${c.status}，应为 fail（执行记录与用例清单不一致）`);
+      }
+      if (latest?.totals?.total > cases.length) {
+        warn(`tests.json 只登记了 ${cases.length} 条用例，最近一次执行共 ${latest.totals.total} 条：还有 ${latest.totals.total - cases.length} 条没登记`);
+      }
+
+      // 收口纪律：登记过用例的故事，不许漏 test 任务、不许漏验收
+      for (const s of stories) {
+        if (!registeredStories.has(s.id)) continue;
+        for (const t of s.tasks ?? []) {
+          if (t.type === 'test' && t.status === 'done' && !cases.some(c => c.taskId === t.id))
+            err(`task ${t.id}: 已 done 的 test 型任务没有登记用例（story ${s.id} 已经登记了用例，别漏这一条）`);
+        }
+        if (['review', 'done'].includes(s.status)) {
+          (s.acceptance ?? []).forEach((_, i) => {
+            const ref = `${s.id}-A${i + 1}`;
+            if (!coveredRefs.has(ref))
+              err(`story ${s.id}: 验收 ${ref} 没有任何用例覆盖（故事已到 ${s.status}）`);
+          });
+        }
+        for (const c of cases) {
+          if (!c.taskId || !c.lastRun) continue;
+          const hit = taskById.get(c.taskId);
+          if (!hit || hit.story.id !== s.id) continue;
+          const passes = (journalByTask.get(c.taskId)?.entries ?? []).filter(e => /^pass/i.test(e.result ?? ''));
+          const lastPass = passes[passes.length - 1]?.date;
+          if (lastPass && c.lastRun < lastPass)
+            warn(`tests case ${c.id}: lastRun ${c.lastRun} 早于 task ${c.taskId} 最后一次通过 ${lastPass}（结果该刷新了）`);
+        }
+      }
+
+      const doneStories = stories.filter(s => s.status === 'done');
+      const missing = doneStories.filter(s => !registeredStories.has(s.id));
+      if (missing.length) {
+        warn(`tests.json 只登记了 ${registeredStories.size} 个故事的用例，还有 ${missing.length} 个已完成故事完全没有用例`);
+      }
+    }
+  }
+}
+
+// ---- diagrams.json（架构图例，可选文件） ----
+// 和 tests.json 同一套设计：不存在就跳过（老项目升级不受影响）；
+// 存在就必须能被 /diagrams 页原样渲染，且索引与产物文件一一对应。
+{
+  const p = join(AGILE, 'diagrams.json');
+  if (existsSync(p)) {
+    const KIND = ['architecture', 'sequence', 'flow', 'erd', 'state', 'deploy', 'other'];
+    const LINT_RESULT = ['pass', 'skipped'];
+    let doc = null;
+    try {
+      doc = JSON.parse(readFileSync(p, 'utf8'));
+    } catch (e) {
+      err(`agile/diagrams.json: JSON 解析失败 - ${e.message}`);
+    }
+    if (doc) {
+      if (doc.schemaVersion !== 3) err(`agile/diagrams.json: schemaVersion 应为 3，实际 ${doc.schemaVersion}`);
+      if (!Array.isArray(doc.diagrams)) err('diagrams: diagrams 必须是数组（没有图例就写空数组）');
+      const diagrams = Array.isArray(doc.diagrams) ? doc.diagrams : [];
+      const byId = new Map();
+      const indexed = new Set();
+
+      for (const d of diagrams) {
+        const where = `diagram ${d.id ?? '?'}`;
+        claim(d.id, 'diagram');
+        if (!/^DG-\d{3,}$/.test(d.id ?? '')) err(`${where}: id 必须形如 DG-001`);
+        if (!d.title) err(`${where}: 缺少 title`);
+        if (!KIND.includes(d.kind)) err(`${where}: kind 必须是 ${KIND.join('/')}，实际 ${d.kind}`);
+        if (d.catalog !== undefined && typeof d.catalog !== 'string') err(`${where}: catalog 必须是字符串（存 diagram-design 的原始图型名）`);
+        if (d.lint !== undefined && !LINT_RESULT.includes(d.lint)) err(`${where}: lint 只能是 ${LINT_RESULT.join('/')}`);
+
+        // 产物路径：只认 agile/ 下的相对路径，不许 .. 也不许绝对路径
+        if (!d.file) err(`${where}: 缺少 file（产物 HTML 的路径）`);
+        else {
+          const rel = normalize(d.file).replace(/\\/g, '/');
+          if (isAbsolute(d.file) || rel.startsWith('../') || !rel.startsWith('agile/diagrams/'))
+            err(`${where}: file 必须是 agile/diagrams/ 下的相对路径，实际 ${d.file}`);
+          else {
+            if (!existsSync(join(TARGET, rel))) err(`${where}: 产物文件不存在 ${d.file}`);
+            indexed.add(rel);
+          }
+        }
+        if (d.svg !== undefined) {
+          const rel = normalize(d.svg).replace(/\\/g, '/');
+          if (isAbsolute(d.svg) || !rel.startsWith('agile/diagrams/')) err(`${where}: svg 必须是 agile/diagrams/ 下的相对路径`);
+          else if (!existsSync(join(TARGET, rel))) warn(`${where}: svg 导出文件不存在 ${d.svg}`);
+          else indexed.add(rel);
+        }
+
+        // 关联：故事必须存在；任务必须存在且属于所挂的故事（与用例的 taskId 规则一致）
+        if (d.storyIds !== undefined && !Array.isArray(d.storyIds)) err(`${where}: storyIds 必须是数组`);
+        const storyIds = Array.isArray(d.storyIds) ? d.storyIds : [];
+        for (const sid of storyIds) if (!storyById.has(sid)) err(`${where}: storyIds 里的 ${sid} 不存在`);
+        if (d.taskId) {
+          const hit = taskById.get(d.taskId);
+          if (!hit) err(`${where}: task ${d.taskId} 不存在`);
+          else if (storyIds.length && !storyIds.includes(hit.story.id))
+            err(`${where}: task ${d.taskId} 属于 ${hit.story.id}，与 storyIds 不一致`);
+        }
+
+        for (const key of ['createdAt', 'updatedAt']) {
+          if (!DATE_RE.test(d[key] ?? '')) err(`${where}: ${key} 格式应为 YYYY-MM-DD`);
+          else if (d[key] > today) warn(`${where}: ${key} ${d[key]} 在未来`);
+        }
+        if (DATE_RE.test(d.createdAt ?? '') && DATE_RE.test(d.updatedAt ?? '') && d.updatedAt < d.createdAt)
+          err(`${where}: updatedAt ${d.updatedAt} 早于 createdAt ${d.createdAt}`);
+        if (d.supersedes !== undefined) {
+          if (!byId.has(d.supersedes) && !diagrams.some(x => x.id === d.supersedes))
+            err(`${where}: supersedes 指向不存在的图例 ${d.supersedes}`);
+          if (d.supersedes === d.id) err(`${where}: 不许 supersedes 自己`);
+        }
+        byId.set(d.id, d);
+      }
+
+      // supersedes 链不能成环
+      for (const d of diagrams) {
+        const seen = new Set();
+        let cur = d;
+        while (cur?.supersedes) {
+          if (seen.has(cur.id)) { err(`diagram ${d.id}: supersedes 成环（${[...seen].join(' → ')}）`); break; }
+          seen.add(cur.id);
+          cur = byId.get(cur.supersedes);
+        }
+      }
+
+      // 孤儿文件：索引没登记就不该躺在 agile/diagrams/ 里（绕过工具手放的最常见姿势）
+      const dir = join(AGILE, 'diagrams');
+      if (existsSync(dir) && statSync(dir).isDirectory()) {
+        for (const name of readdirSync(dir)) {
+          if (!/\.html?$/i.test(name)) continue;
+          const rel = `agile/diagrams/${name}`;
+          if (!indexed.has(rel)) warn(`${rel} 没有登记进 diagrams.json（用 node tools/diagram.mjs add 登记）`);
+        }
+      }
+
+      // 过期：图比故事最后一次通过的日志还旧，很可能画的是改之前的版本
+      const lastPassByStory = new Map();
+      for (const s of stories) {
+        let last = '';
+        for (const t of s.tasks ?? []) {
+          for (const e of journalByTask.get(t.id)?.entries ?? []) {
+            if (/^pass/i.test(e.result ?? '') && e.date > last) last = e.date;
+          }
+        }
+        if (last) lastPassByStory.set(s.id, last);
+      }
+      for (const d of diagrams) {
+        if (!DATE_RE.test(d.updatedAt ?? '')) continue;
+        for (const sid of d.storyIds ?? []) {
+          const pass = lastPassByStory.get(sid);
+          if (pass && d.updatedAt < pass)
+            warn(`diagram ${d.id}: updatedAt ${d.updatedAt} 早于 ${sid} 最后一次通过 ${pass}（图可能过期）`);
+        }
+      }
+    }
+  }
+}
+
+// ---- 输出 ----
+for (const w of warns) console.warn(`  WARN  ${w}`);
+if (errors.length === 0) {
+  const taskCount = taskById.size;
+  console.log(`✔ 校验通过：${epics.length} epics, ${stories.length} stories (${taskCount} tasks), ${sprints.length} sprints, ${milestones.length} milestones, ${journals.length} journals`);
+} else {
+  console.error(`✘ 校验失败，共 ${errors.length} 处错误：`);
+  for (const e of errors) console.error(`  - ${e}`);
+  process.exit(1);
+}