scrum-skills 0.1.2 → 0.2.0

package/tools/validate.mjs

@@ -1,153 +1,363 @@
 #!/usr/bin/env node
 /**
- * 敏捷数据校验脚本（零依赖）
+ * 敏捷数据校验脚本（零依赖，schema v3：三文件结构）
  * 用法: node tools/validate.mjs [目标目录]   默认当前工作目录
- * 校验 <目标>/agile/ 下所有 JSON 的引用完整性、状态机、TDD 纪律。
+ * 校验 <目标>/agile/ 下 backlog.json / sprints.json / journal.json：
+ * 引用完整性（双向）、状态机、TDD 纪律、里程碑达成口径、
+ * 需求属性（type/priority/value/缺陷详情/验收覆盖）、依赖无环、阻塞与范围变更。
  * 退出码: 0 通过, 1 有错误。
  */
-import { readdirSync, readFileSync, existsSync } from 'node:fs';
-import { join, basename, resolve } from 'node:path';
+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);
 
-function readJson(dir) {
-  const out = [];
-  if (!existsSync(dir)) return out;
-  for (const f of readdirSync(dir)) {
-    if (!f.endsWith('.json')) continue;
-    const p = join(dir, f);
-    try {
-      out.push({ file: p, data: JSON.parse(readFileSync(p, 'utf8')) });
-    } catch (e) {
-      errors.push(`${p}: JSON 解析失败 - ${e.message}`);
-    }
+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;
   }
-  return out;
-}
-
-const epics = readJson(join(AGILE, 'backlog/epics'));
-const stories = readJson(join(AGILE, 'backlog/stories'));
-const sprints = readJson(join(AGILE, 'sprints'));
-const journals = readJson(join(AGILE, 'journal'));
-
-const epicIds = new Set(epics.map(e => e.data.id));
-const storyIds = new Set(stories.map(s => s.data.id));
-const sprintIds = new Set(sprints.map(s => s.data.id));
-const allIds = new Set();
-const journalTaskIds = new Set();
-
-// 文件名与内部 id 一致（journal 按 taskId 对应 task，单独去重）
-for (const [items, key] of [[epics, 'id'], [stories, 'id'], [sprints, 'id'], [journals, 'taskId']]) {
-  for (const it of items) {
-    const id = it.data[key];
-    if (!id) { errors.push(`${it.file}: 缺少 ${key}`); continue; }
-    const stem = basename(it.file, '.json');
-    if (stem !== id) errors.push(`${it.file}: 文件名 ${stem} 与内部 ${key} ${id} 不一致`);
-    const bucket = key === 'taskId' ? journalTaskIds : allIds;
-    if (bucket.has(id)) errors.push(`${it.file}: ${key} ${id} 重复`);
-    bucket.add(id);
+  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}`);
 }
-for (const j of journals) {
-  const sid = j.data.storyId;
-  if (sid && !storyIds.has(sid)) errors.push(`${j.file}: storyId ${sid} 不存在`);
+
+// 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'];
 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}$/;
+// 用本地日期判定「今天」，避免 UTC 偏移导致活跃迭代判定差一天
+const now = new Date();
+const today = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
 
-// Story 校验
+// ---- 全局唯一 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) {
-  const d = s.file && s.data;
-  const { id, epicId, sprintId, status, acceptance, tasks } = d;
-  if (epicId && !epicIds.has(epicId)) errors.push(`${s.file}: epicId ${epicId} 不存在`);
-  if (sprintId && !sprintIds.has(sprintId)) errors.push(`${s.file}: sprintId ${sprintId} 不存在`);
-  if (!STORY_FLOW.includes(status) && status !== 'cancelled') errors.push(`${s.file}: 非法 story 状态 ${status}`);
+  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) && status !== 'cancelled') err(`story ${id}: 非法状态 ${status}`);
+  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 ((status === 'ready' || STORY_FLOW.indexOf(status) > 1) && (!acceptance || acceptance.length === 0))
-    errors.push(`${s.file}: 状态 ${status} 但验收标准为空`);
-  if (sprintId && (!acceptance || acceptance.length === 0))
-    errors.push(`${s.file}: 已进 sprint 但无验收标准（不满足 ready）`);
+    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 && status !== 'draft') 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 (sprintId) 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 (!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' && t.status !== 'cancelled')
-        errors.push(`${s.file}: story 已 done 但 task ${t.id} 状态为 ${t.status}`);
+      if (t.status !== 'done') err(`story ${id} 已 done 但 task ${t.id} 状态为 ${t.status}`);
     }
   }
-  for (const t of tasks ?? []) {
-    if (allIds.has(t.id)) errors.push(`${s.file}: task id ${t.id} 重复`);
-    allIds.add(t.id);
-    if (!TASK_FLOW.includes(t.status)) errors.push(`${s.file}: 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}，双向引用不一致`);
   }
+  const committed = (sp.stories ?? []).reduce((a, sid) => a + (storyById.get(sid)?.points ?? 0), 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 个）`);
+  }
 
-// Task → journal TDD 纪律
-const journalByTask = new Map(journals.map(j => [j.data.taskId, j]));
-const realTaskIds = new Set();
-for (const s of stories) for (const t of s.data.tasks ?? []) realTaskIds.add(t.id);
-for (const [tid] of journalByTask) {
-  if (!realTaskIds.has(tid)) errors.push(`journal: taskId ${tid} 不指向任何真实 task`);
+  // 期号越大，起始日期应越晚
+  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}），期号与时间顺序不一致`);
+  }
 }
-for (const s of stories) {
-  for (const t of s.data.tasks ?? []) {
-    const hasRed = ['red', 'green', 'refactored', 'done'].includes(t.status);
-    const hasGreen = ['green', 'refactored', 'done'].includes(t.status);
-    const jShell = journalByTask.get(t.id);
-    if (!hasRed && t.journal && jShell && (jShell.data.entries ?? []).length > 0)
-      warns.push(`${t.id}: 尚在 todo 但 journal 已有实施记录（检查是否提前动了手）`);
-    if (!hasRed) continue;
-    const j = journalByTask.get(t.id);
-    if (!j) { errors.push(`task ${t.id}: 状态 ${t.status} 但 journal 缺失`); continue; }
-    const entries = j.data.entries ?? [];
-    const firstRedIdx = entries.findIndex(e => e.phase === 'red');
-    const firstGreenIdx = entries.findIndex(e => e.phase === 'green');
-    if (firstRedIdx < 0) errors.push(`task ${t.id}: journal 没有 red 记录（先写失败测试的铁律被违反）`);
-    else if (entries[firstRedIdx].result && !/^fail/i.test(entries[firstRedIdx].result))
-      errors.push(`task ${t.id}: 第一条 red 记录的 result 应为 fail，实际 "${entries[firstRedIdx].result}"`);
-    if (hasGreen) {
-      if (firstGreenIdx < 0) errors.push(`task ${t.id}: 状态已过 red 但 journal 没有 green 记录`);
-      else if (entries[firstGreenIdx].result && !/^pass/i.test(entries[firstGreenIdx].result))
-        errors.push(`task ${t.id}: 第一条 green 记录的 result 应为 pass`);
-    }
-    if (t.status === 'done') {
-      const last = entries[entries.length - 1];
-      if (!last || !last.result || !/^pass/i.test(last.result))
-        errors.push(`task ${t.id}: 已 done 但 journal 末条记录不是 pass`);
+
+// ---- 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`);
 }
 
-// Epic 校验
-for (const e of epics) {
-  for (const sid of e.data.stories ?? []) {
-    if (!storyIds.has(sid)) errors.push(`${e.file}: 引用 story ${sid} 不存在`);
-  }
-  if (e.data.status === 'done') {
-    for (const sid of e.data.stories ?? []) {
-      const st = stories.find(s => s.data.id === sid);
-      if (st && !['done', 'cancelled'].includes(st.data.status))
-        errors.push(`${e.file}: epic 已 done 但 story ${sid} 状态为 ${st.data.status}`);
-    }
+// ---- 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`);
   }
 }
 
-// Sprint 校验：引用 + 唯一活跃
-const today = new Date().toISOString().slice(0, 10);
-let active = 0;
-for (const sp of sprints) {
-  for (const sid of sp.data.stories ?? []) {
-    if (!storyIds.has(sid)) errors.push(`${sp.file}: 引用 story ${sid} 不存在`);
+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`);
   }
-  if (sp.data.start <= today && sp.data.end >= today) active++;
 }
-if (active > 1) errors.push(`同时存在 ${active} 个活跃 sprint，只允许一个`);
 
-// 输出
+// ---- 输出 ----
 for (const w of warns) console.warn(`  WARN  ${w}`);
 if (errors.length === 0) {
-  console.log(`✔ 校验通过：${epics.length} epics, ${stories.length} stories, ${sprints.length} sprints, ${journals.length} journals`);
+  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}`);