scrum-skills 0.3.2 → 0.3.4

package/.agents/skills/scrum-planning/references/schema.md

@@ -1,336 +1,384 @@
-# 敏捷数据 Schema（v3 · 三常驻 + 两可选）
-
-`agile/` 下**三个常驻数据文件 + 两个可选文件**（测试资产、交付说明），全部 UTF-8 JSON、2 空格缩进、末尾换行。
-
-| 文件 | 装什么 |
-|---|---|
-| `agile/backlog.json` | 史诗 epics（含量化目标 keyResults）+ 用户故事 stories（内联 tasks） |
-| `agile/sprints.json` | 迭代 sprints + 里程碑 milestones（MVP 节点是里程碑的一种） |
-| `agile/journal.json` | TDD 实施日志 journals（一个 task 一条，内联 entries） |
-| `agile/tests.json` | 测试资产：suites（层 × 级别 → cases）+ runs（执行记录与代码覆盖率），见第 5 节 |
-| `agile/last-change.json` | 最近一次交付的汇报（可选；已提交才覆盖，未提交则合并，见第 4 节） |
-
-> 所有数据文件都必须带 `"schemaVersion": 3`（含可选的 `tests.json` / `last-change.json`）。v2 及更早的散文件结构不再兼容，校验器发现 `agile/backlog/epics/`、`agile/backlog/stories/`、`agile/sprints/`、`agile/journal/` 里还有 JSON 会直接报错。
-
-## 1. backlog.json
-
-```json
-{
-  "schemaVersion": 3,
-  "epics": [
-    {
-      "id": "E-001",
-      "title": "用户认证与工作空间",
-      "goal": "一句话说明这个史诗完成后用户获得了什么",
-      "status": "draft | active | done | cancelled",
-      "keyResults": [
-        { "id": "E-001-KR1", "text": "新成员从收到邀请到能登录用时", "unit": "分钟", "target": 2, "current": 1.5 }
-      ],
-      "stories": ["S-001", "S-002"],
-      "created": "2026-08-24"
-    }
-  ],
-  "stories": [
-    {
-      "id": "S-001",
-      "epicId": "E-001",
-      "title": "邮箱密码登录",
-      "narrative": "作为<角色>，我想要<能力>，以便<价值>",
-      "type": "feature | bug | debt | spike",
-      "priority": "P0 | P1 | P2 | P3",
-      "value": 13,
-      "bug": {
-        "severity": "blocker | major | minor | trivial",
-        "environment": "Chrome 120 / Windows 11，看板页四列布局",
-        "steps": "1. …；2. …；3. …"
-      },
-      "acceptance": [
-        { "given": "已注册用户", "when": "输入正确邮箱密码提交", "then": "下发会话 cookie 并跳转首页", "verifyBy": ["S-001-T1"] }
-      ],
-      "points": 5,
-      "status": "draft | ready | in-progress | review | done | cancelled",
-      "sprintId": "R1-S1",
-      "created": "2026-08-24",
-      "schedule": { "start": "2026-08-31", "end": "2026-09-08" },
-      "dependsOn": ["S-004"],
-      "blocked": { "reason": "等产品确认是否要留审计日志", "since": "2026-10-21" },
-      "scopeChange": { "kind": "added-mid-sprint | split | expanded", "at": "2026-10-15", "reason": "客户临时插需求" },
-      "tasks": [
-        {
-          "id": "S-001-T1",
-          "title": "为登录接口写失败测试",
-          "type": "test | impl | refactor | chore",
-          "status": "todo | red | green | refactored | done",
-          "files": ["tests/auth/login.spec.ts"]
-        }
-      ]
-    }
-  ]
-}
-```
-
-字段说明：
-
-- **`type`**：`feature` 功能 / `bug` 缺陷 / `debt` 技术债 / `spike` 调研。`bug` 必须同时给 `bug` 详情三件套（severity / environment / steps），否则校验报错。
-- **`priority`**：P0 最高。数组顺序即 backlog 排序（rank），看板可再按优先级或 WSJF 重排。
-- **`value` + `points`** → WSJF = value / points，用来决定「先做谁」；点数仍是成本口径，两者别混。
-- **`acceptance[].verifyBy`**：这条验收由哪个 task 的测试覆盖（task id）。非 `draft` 状态没写只给 WARN，但它是「验收不是口号」的唯一凭据，建议必填。
-- **`dependsOn`**：故事级依赖，必须存在、不能自依赖、**不能成环**（校验器做 DFS 检测）。
-- **`blocked`**：当前阻塞的事实（原因 + 起始日期）。已 `done` 的故事不许带 `blocked`；处于迭代里还被阻塞会 WARN（站会必须处理）。
-- **`scopeChange`**：范围变更标记。`added-mid-sprint` 迭代中途插入、`split` 拆分产生、`expanded` 范围扩大。有了它，燃尽图上那段平台期才不会被误读成「拖延」。
-- **`schedule`** 可选，只给甘特图用（计划区间）；实际区间由 `journal.json` 的记录日期推出来，不用手填。
-- task 的 `id` 必须是 `<storyId>-T<n>`；日志集中在 `journal.json`，用 `taskId` 关联。
-
-## 2. sprints.json
-
-```json
-{
-  "schemaVersion": 3,
-  "sprints": [
-    {
-      "id": "R1-S1",
-      "name": "第 1 个迭代（登录与邀请）",
-      "goal": "本迭代要交付什么",
-      "start": "2026-08-31",
-      "end": "2026-09-13",
-      "stories": ["S-001", "S-002"],
-      "capacity": 12
-    }
-  ],
-  "milestones": [
-    {
-      "id": "M-001",
-      "title": "MVP · 内测可登录",
-      "kind": "mvp | release | checkpoint",
-      "due": "2026-09-13",
-      "status": "planned | at-risk | reached | missed",
-      "sprintId": "R1-S1",
-      "criteria": "达成口径：怎样算这个节点到了",
-      "stories": ["S-001", "S-002"]
-    }
-  ]
-}
-```
-
-- **MVP 节点就是 `kind: "mvp"` 的里程碑**，不另设实体。
-- `status: "reached"` 时挂的故事必须全部 `done/cancelled`，否则校验报错。
-- `due` 早于今天但状态仍是 `planned` → WARN。
-
-### 迭代编号规则（`sprints[].id`）
-
-格式：`R<发布周期>-S<期内冲刺号>`，例如 `R1-S1`、`R1-S2`、`R2-S1`。
-
-- **`S<期内冲刺号>`** 是 Sprint 本体 —— Scrum 里的 Sprint（冲刺/迭代）就是它，在一个发布周期内从 1 开始连号、不跳号。
-- **`R<发布周期>`** 是引用Release（发布周期/版本）这一层的分组：若干个冲刺归到一个发布窗口，和 `milestones`（尤其 `kind: "release"`）对齐。当前约定**一个发布周期 = 4 周 = 2 个两周冲刺**。
-  它不是 Scrum 术语（Scrum 只有 Sprint），业界最接近的是 Release 或 SAFe 的 PI（Program Increment，通常 8~12 周、含 4 个开发冲刺 + 1 个 IP 冲刺）。**既然叫 Release 就按 4 周一个周期排，别套 PI 的节奏。**
-- 周期号按时间递增（`R1`、`R2`…，不带前导零）；同一周期内冲刺号不得重复；**一个周期建议不超过 2 个冲刺**。
-- 小团队不需要发布周期这一层时，可以只用 `S-01`、`S-02` 纯序号（整段省略 `R` 前缀），但**同一个项目里不许两种风格混用**。
-- **id 被 `story.sprintId`、`milestones[].sprintId` 引用，定了就别改**；确需重命名时两处引用同步改，改完跑 `validate`（引用完整性会兜住漏改）。
-
-以上规则由 `tools/validate.mjs` 强制：id 必须匹配 `R<n>-S<n>` 或 `S-<n>`、不许混用风格、同一周期内冲刺号必须从 1 连续、周期号与起始日期顺序要一致（后两条分别报错与警告）。
-
-## 3. journal.json
-
-```json
-{
-  "schemaVersion": 3,
-  "journals": [
-    {
-      "taskId": "S-001-T1",
-      "storyId": "S-001",
-      "entries": [
-        {
-          "phase": "red | green | refactor",
-          "date": "2026-08-31",
-          "note": "这一步做了什么、为什么",
-          "files": ["tests/auth/login.spec.ts"],
-          "testCommand": "pnpm test auth/login",
-          "result": "fail: 3 failed, 0 passed — 404 Not Found"
-        }
-      ]
-    }
-  ]
-}
-```
-
-## 4. last-change.json（最后更新 / 交付说明）
-
-`agile/last-change.json` 是**可选**文件：还没交付过东西时不存在，校验器不报错。看板 `/last-change` 页读的就是它。
-
-### 写之前先查 git：已提交才覆盖，未提交就合并
-
-只留最近一次交付的前提是**上一次已经进了版本库**。文件如果还有没提交的改动，直接覆盖就把那次记录冲掉了，所以写入策略分两种：
-
-| 文件在 git 里的状态 | 写法 | 结果 |
-|---|---|---|
-| 已提交、工作区干净 | 整份覆盖 | 文件里只有本次交付 |
-| 有未提交改动 / 已暂存未提交 / 未跟踪 / 不是 git 仓库 | 合并 | 本次结果并进旧记录，旧的一条不丢 |
-
-用工具判断并写入，不要手写覆盖：
-
-```bash
-node tools/last-change.mjs check           # 退出码 0 = 可覆盖，2 = 必须先合并
-node tools/last-change.mjs write <记录.json>  # 按状态自动覆盖或合并，写后校验，失败回滚
-node tools/last-change.mjs write <记录.json> --replace   # 确认旧记录不要了才强制覆盖
-```
-
-合并的取舍（`write` 自动完成，手动合并也要照这个来）：
-
-- `changes` 按 `kind:id`、`scenarios` 按 `id`（没有就按 `title`）去重：**新的覆盖旧的**，没被提到的旧条目原样保留，顺序按「旧的在前、新增的追加」；
-- `extras` 按 `title`、`verification` 按 `what`、`preparation` 按 `step` 去重，规则同上；
-- `notes` / `open` 字符串去重后拼接；`access.urls` 按 `url`、`access.accounts` 按 `username` 合并；
-- `title` / `at` / `summary` 取本次的（缺了才沿用旧的）；
-- 合并后自动带上 `"merged": true` 与 `"mergedFrom"`（被并进来的那几次交付），看板据此标「合并记录」。
-
-```json
-{
-  "schemaVersion": 3,
-  "lastChange": {
-    "title": "登录接口收尾",
-    "at": "2026-10-27 14:35:12",
-    "summary": "一句话说清这次交付做成了什么",
-    "changes": [
-      {
-        "kind": "story",
-        "id": "S-001",
-        "title": "邮箱密码登录",
-        "action": "added | updated | removed",
-        "from": "in-progress",
-        "to": "review",
-        "note": "变更内容：补了两条验收、状态推进到评审",
-        "files": ["agile/backlog.json", "src/auth/login.ts"]
-      }
-    ],
-    "extras": [{ "title": "顺手把校验错误信息改成中文", "detail": "为什么做、做到什么程度", "files": ["tools/validate.mjs"] }],
-    "verification": [{ "what": "pnpm test", "result": "pass | fail | partial | skipped", "detail": "32 passed" }],
-    "access": {
-      "urls": [{ "label": "看板", "url": "http://localhost:4173", "note": "先起 serve" }],
-      "accounts": [{ "role": "管理员", "username": "admin@example.com", "password": "Passw0rd!", "note": "仅本地环境" }]
-    },
-    "preparation": [{ "step": "装依赖", "command": "pnpm install", "note": "Node ≥ 18" }],
-    "scenarios": [
-      {
-        "id": "TC-01",
-        "title": "正确密码能登录",
-        "storyIds": ["S-001"],
-        "steps": ["打开 /login", "填表提交"],
-        "expect": "跳转首页并下发会话 cookie",
-        "acceptance": "对应验收第 1 条"
-      }
-    ],
-    "merged": true,
-    "mergedFrom": [{ "title": "上一次还没提交的交付", "at": "2026-10-26 18:02:41" }],
-    "notes": ["使用说明、口径解释"],
-    "open": ["还没做的、已知限制"]
-  }
-}
-```
-
-字段说明：
-
-- **`title` / `at` 必填**：`at` 是本次交付时间，**写到秒**：`YYYY-MM-DD HH:mm:ss`（ISO 的 `T` 分隔也认）。只写 `YYYY-MM-DD` 仍然合法，但校验器会给 WARN、看板上也只能看到「哪天」，看不出「几点几分交付的」。`node tools/last-change.mjs write` 发现缺 `at` 会自动补当前时间。
-- **`merged` / `mergedFrom` 由工具写，不要手填**：只有「并进未提交旧记录」时才出现，`mergedFrom` 每条要有 `title`（`at` 可选）。`merged: true` 却没有 `mergedFrom` 会被校验器提醒。
-- **`changes[]`**：故事与任务的变更清单，看板表格一行一条。`kind` 只认 `story` / `task`，`id` 必须是 backlg 里真实存在的 id；`action` 是 `added`（新增）/ `updated`（状态或内容变更）/ `removed`（删除）；状态变更填 `from` → `to`，`files` 是这次动过的文件。
-- **其余分区都可选**，没有就省略，**不许为了填满而编**：项目没有账号体系就不写 `accounts`，没有前端入口就不写 `urls`。
-- `verification[].result` 与 `scenarios[].expect` 是「验收不是口号」的凭据：场景必须写清步骤与验收标准，验证结果只认 `pass/fail/partial/skipped`。
-- 校验器会查：`schemaVersion`、`at` 格式、`kind`/`action`/`result` 枚举、`changes[].id` 是否真实存在、`scenarios[].steps` 与 `expect` 是否齐备、`access.urls[].url` 是否为 `http(s)` 完整地址。缺 `title`、`what`、`expect`、`step` 报错；缺 `changes[].title`、场景 id、url label 只给 WARN。
-
-## 5. tests.json（测试资产与覆盖率）
-
-`agile/tests.json` 是**可选**文件：不存在时校验器不报错、看板 `/tests` 页显示空状态。它由 Coding Agent 在**每个 task 推到 `done`、story 送进 `review` 之前**维护（见 `scrum-tdd` 的交工汇报第 1 步），不是事后补的报表。
-
-```json
-{
-  "schemaVersion": 3,
-  "suites": [
-    {
-      "id": "TS-BE-01",
-      "name": "登录接口",
-      "layer": "frontend | backend | e2e",
-      "level": "unit | integration | e2e",
-      "runner": "vitest",
-      "files": ["tests/auth/login.spec.ts"],
-      "cases": [
-        {
-          "id": "TC-BE-001",
-          "title": "正确密码登录返回 200 并下发 httpOnly cookie",
-          "automated": true,
-          "taskId": "S-001-T1",
-          "covers": ["S-001-A1"],
-          "expect": "200；set-cookie 含 sid；HttpOnly",
-          "code": "tests/auth/login.spec.ts::正确密码登录",
-          "status": "pass | fail | skipped | blocked | not-run",
-          "lastRun": "2026-10-29",
-          "durationMs": 42,
-          "note": "失败原因写在这里"
-        }
-      ]
-    }
-  ],
-  "runs": [
-    {
-      "id": "RUN-20261029-2110",
-      "at": "2026-10-29 21:10:00",
-      "env": "local",
-      "command": "pnpm test",
-      "totals": { "total": 159, "pass": 158, "fail": 1, "skipped": 0, "durationMs": 24300 },
-      "failedCases": ["TC-BE-001"],
-      "coverage": {
-        "frontend": { "tool": "vitest", "lines": 72.4, "branches": 61.5, "functions": 66.0, "report": "coverage/frontend/lcov.info" },
-        "backend": { "tool": "vitest", "lines": 84.1, "branches": 70.2, "functions": 80.5, "report": "coverage/backend/lcov.info" }
-      }
-    }
-  ]
-}
-```
-
-字段说明：
-
-- **`suites[]`** 按模块 / 测试文件分组，承载**两个正交维度**：`layer`（`frontend` / `backend` / `e2e`，QA 主视图的三条泳道）与 `level`（`unit` / `integration` / `e2e`）。`files` 只用于定位，可省。
-- **`cases[]`** 一条用例 = 一次能判定成败的验证：
-  - `automated` 区分自动化 / 手工；**手工用例也要登记**，`steps` 一步一条，这是交接给 QA 的正文；
-  - `covers` 是覆盖的验收，写法 `S-001-A1`（故事 id + 第几条验收，**1 基**）；改验收顺序要同步改它，一条 E2E 用例可以覆盖多个故事；
-  - `expect` 必填（只有标题的用例不算交付物）；`taskId` 指向产出它的 TDD 任务（可省）；`code` 是自动化用例的定位串 `文件::用例名`，导入器靠它回写状态；
-  - `status` 只认 `pass / fail / skipped / blocked / not-run`；`not-run` 不要求 `lastRun`，其余必须写。
-- **`runs[]`** 每次执行一条，**按时间正序**（最后一条 = 最近一次）：`at` 到秒、`command`、`env`、`totals`、`failedCases`，有覆盖率报告就填 `coverage`。
-  - `coverage` 按层给 `lines / branches / functions / statements` 与 `tool`：**前端、后端各报各的，绝不做加权平均**，E2E 一般不报行覆盖。
-
-覆盖率的三个口径（页面按这个算，禁止合成一个「覆盖率」）：
-
-| 口径 | 分母 | 分子 |
-|---|---|---|
-| 需求覆盖 | 非 `draft` / `cancelled` 故事的验收条数 | 被至少一条用例 `covers` 命中的条数；其中最近一次 `pass` 的另算「验证通过」 |
-| 用例通过率 | 最近一次执行的 `total - skipped` | `pass` |
-| 代码覆盖 | 测试工具报告 | `lines` / `branches`，前端、后端分开 |
-
-校验器强制：枚举合法；用例 / 套件 id 与其它记录共用一个命名空间；`covers` 指向的验收必须存在且序号不越界；`taskId` 必须存在且属于 `covers` 里的故事；`runs` 时间正序；`通过+失败+跳过 ≤ 总数`；最新一次 `failedCases` 必须对应 `status: fail`；覆盖率在 0~100 之间。
-
-收口纪律（**只查登记过用例的故事**，避免老项目一升级就满屏报错）：
-
-- 该 story 下每个 `done` 的 `type: test` task 至少一条用例 → 否则**报错**；
-- story 到 `review` / `done` 时每条验收都被覆盖 → 否则**报错**（未到 review 只给 WARN）；
-- 用例 `lastRun` 早于 task 最后一次 `pass` → WARN（结果过期了）；
-- 最近一次执行条数多于已登记用例 → WARN（还有测试没登记）。
-
-## 状态机（校验器强制）
-
-- story: `draft → ready → in-progress → review → done`；不做了直接进 `cancelled`（已取消）终态（可回退，不可跳级；`done` 与 `cancelled` 都是终态）
-- task: `todo → red → green → refactored → done`（只能前进；test 型可 `todo → green`）
-- epic: 无强制流转，但 `done` 要求其下所有 story 均 `done/cancelled`
-- milestone: `planned → at-risk → reached / missed`
-
-## 硬约束（校验器强制 / 警告）
-
-1. ID 全局唯一（epic / story / task / sprint / milestone / suite / case 共用命名空间），task 命名 `<storyId>-T<n>`
-2. **双向引用一致**：`epic.stories` ↔ `story.epicId`、`sprint.stories` ↔ `story.sprintId`、`journal.taskId` ↔ task
-3. `ready` / `in-progress` / `review` / `done` 必须有验收标准；进 sprint 的故事必须有验收标准（`cancelled` 两样都不要求）
-4. 验收标准的 `verifyBy` 必须指向**同一 story 的** task
-5. task 到 `green/refactored/done` 时，journal 必须存在且首条 `red` 的 result 以 `fail` 开头、`green` 以 `pass` 开头
-6. task 为 `done` 时，journal 末条 entry 的 `result` 必须 `pass`
-7. story 为 `done` 时，其所有 task 必须 `done`，且不许仍标着 `blocked`
-8. 同时只能有一个活跃 sprint（`start ≤ 今天 ≤ end`）
-9. `dependsOn` 必须存在、不能自依赖、不能成环
-10. `schedule.start ≤ schedule.end`；计划区间超出所属迭代只给 WARN
-11. sprint 承诺点数超过 `capacity` → WARN
-12. epic 没有 `keyResults` → WARN（史诗要有量化目标）
-13. `cancelled` 是终态：不要求验收、不要求 task 全部 `done`；但仍标着 `blocked` 报错；还留在某个 sprint 里只给 WARN —— 它的点数不计入承诺容量，看板的燃尽图与里程碑完成度同样把它扣掉
+# 敏捷数据 Schema（v3 · 三常驻 + 三可选）
+
+`agile/` 下**三个常驻数据文件 + 三个可选文件**（测试资产、交付说明、架构图例），全部 UTF-8 JSON、2 空格缩进、末尾换行。
+
+| 文件 | 装什么 |
+|---|---|
+| `agile/backlog.json` | 史诗 epics（含量化目标 keyResults）+ 用户故事 stories（内联 tasks） |
+| `agile/sprints.json` | 迭代 sprints + 里程碑 milestones（MVP 节点是里程碑的一种） |
+| `agile/journal.json` | TDD 实施日志 journals（一个 task 一条，内联 entries） |
+| `agile/tests.json` | 测试资产：suites（层 × 级别 → cases）+ runs（执行记录与代码覆盖率），见第 5 节 |
+| `agile/last-change.json` | 最近一次交付的汇报（可选；已提交才覆盖，未提交则合并，见第 4 节） |
+| `agile/diagrams.json` | 架构图例索引（可选；产物 HTML 在 `agile/diagrams/` 下），见第 6 节 |
+
+> 所有数据文件都必须带 `"schemaVersion": 3`（含可选的 `tests.json` / `last-change.json` / `diagrams.json`）。v2 及更早的散文件结构不再兼容，校验器发现 `agile/backlog/epics/`、`agile/backlog/stories/`、`agile/sprints/`、`agile/journal/` 里还有 JSON 会直接报错。
+
+## 1. backlog.json
+
+```json
+{
+  "schemaVersion": 3,
+  "epics": [
+    {
+      "id": "E-001",
+      "title": "用户认证与工作空间",
+      "goal": "一句话说明这个史诗完成后用户获得了什么",
+      "status": "draft | active | done | cancelled",
+      "keyResults": [
+        { "id": "E-001-KR1", "text": "新成员从收到邀请到能登录用时", "unit": "分钟", "target": 2, "current": 1.5 }
+      ],
+      "stories": ["S-001", "S-002"],
+      "created": "2026-08-24"
+    }
+  ],
+  "stories": [
+    {
+      "id": "S-001",
+      "epicId": "E-001",
+      "title": "邮箱密码登录",
+      "narrative": "作为<角色>，我想要<能力>，以便<价值>",
+      "type": "feature | bug | debt | spike",
+      "priority": "P0 | P1 | P2 | P3",
+      "value": 13,
+      "bug": {
+        "severity": "blocker | major | minor | trivial",
+        "environment": "Chrome 120 / Windows 11，看板页四列布局",
+        "steps": "1. …；2. …；3. …"
+      },
+      "acceptance": [
+        { "given": "已注册用户", "when": "输入正确邮箱密码提交", "then": "下发会话 cookie 并跳转首页", "verifyBy": ["S-001-T1"] }
+      ],
+      "points": 5,
+      "status": "draft | ready | in-progress | review | done | cancelled",
+      "sprintId": "R1-S1",
+      "created": "2026-08-24",
+      "schedule": { "start": "2026-08-31", "end": "2026-09-08" },
+      "dependsOn": ["S-004"],
+      "blocked": { "reason": "等产品确认是否要留审计日志", "since": "2026-10-21" },
+      "scopeChange": { "kind": "added-mid-sprint | split | expanded", "at": "2026-10-15", "reason": "客户临时插需求" },
+      "tasks": [
+        {
+          "id": "S-001-T1",
+          "title": "为登录接口写失败测试",
+          "type": "test | impl | refactor | chore",
+          "status": "todo | red | green | refactored | done",
+          "files": ["tests/auth/login.spec.ts"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+字段说明：
+
+- **`type`**：`feature` 功能 / `bug` 缺陷 / `debt` 技术债 / `spike` 调研。`bug` 必须同时给 `bug` 详情三件套（severity / environment / steps），否则校验报错。
+- **`priority`**：P0 最高。数组顺序即 backlog 排序（rank），看板可再按优先级或 WSJF 重排。
+- **`value` + `points`** → WSJF = value / points，用来决定「先做谁」；点数仍是成本口径，两者别混。
+- **`acceptance[].verifyBy`**：这条验收由哪个 task 的测试覆盖（task id）。非 `draft` 状态没写只给 WARN，但它是「验收不是口号」的唯一凭据，建议必填。
+- **`dependsOn`**：故事级依赖，必须存在、不能自依赖、**不能成环**（校验器做 DFS 检测）。
+- **`blocked`**：当前阻塞的事实（原因 + 起始日期）。已 `done` 的故事不许带 `blocked`；处于迭代里还被阻塞会 WARN（站会必须处理）。
+- **`scopeChange`**：范围变更标记。`added-mid-sprint` 迭代中途插入、`split` 拆分产生、`expanded` 范围扩大。有了它，燃尽图上那段平台期才不会被误读成「拖延」。
+- **`schedule`** 可选，只给甘特图用（计划区间）；实际区间由 `journal.json` 的记录日期推出来，不用手填。
+- task 的 `id` 必须是 `<storyId>-T<n>`；日志集中在 `journal.json`，用 `taskId` 关联。
+
+## 2. sprints.json
+
+```json
+{
+  "schemaVersion": 3,
+  "sprints": [
+    {
+      "id": "R1-S1",
+      "name": "第 1 个迭代（登录与邀请）",
+      "goal": "本迭代要交付什么",
+      "start": "2026-08-31",
+      "end": "2026-09-13",
+      "stories": ["S-001", "S-002"],
+      "capacity": 12
+    }
+  ],
+  "milestones": [
+    {
+      "id": "M-001",
+      "title": "MVP · 内测可登录",
+      "kind": "mvp | release | checkpoint",
+      "due": "2026-09-13",
+      "status": "planned | at-risk | reached | missed",
+      "sprintId": "R1-S1",
+      "criteria": "达成口径：怎样算这个节点到了",
+      "stories": ["S-001", "S-002"]
+    }
+  ]
+}
+```
+
+- **MVP 节点就是 `kind: "mvp"` 的里程碑**，不另设实体。
+- `status: "reached"` 时挂的故事必须全部 `done/cancelled`，否则校验报错。
+- `due` 早于今天但状态仍是 `planned` → WARN。
+
+### 迭代编号规则（`sprints[].id`）
+
+格式：`R<发布周期>-S<期内冲刺号>`，例如 `R1-S1`、`R1-S2`、`R2-S1`。
+
+- **`S<期内冲刺号>`** 是 Sprint 本体 —— Scrum 里的 Sprint（冲刺/迭代）就是它，在一个发布周期内从 1 开始连号、不跳号。
+- **`R<发布周期>`** 是引用Release（发布周期/版本）这一层的分组：若干个冲刺归到一个发布窗口，和 `milestones`（尤其 `kind: "release"`）对齐。当前约定**一个发布周期 = 4 周 = 2 个两周冲刺**。
+  它不是 Scrum 术语（Scrum 只有 Sprint），业界最接近的是 Release 或 SAFe 的 PI（Program Increment，通常 8~12 周、含 4 个开发冲刺 + 1 个 IP 冲刺）。**既然叫 Release 就按 4 周一个周期排，别套 PI 的节奏。**
+- 周期号按时间递增（`R1`、`R2`…，不带前导零）；同一周期内冲刺号不得重复；**一个周期建议不超过 2 个冲刺**。
+- 小团队不需要发布周期这一层时，可以只用 `S-01`、`S-02` 纯序号（整段省略 `R` 前缀），但**同一个项目里不许两种风格混用**。
+- **id 被 `story.sprintId`、`milestones[].sprintId` 引用，定了就别改**；确需重命名时两处引用同步改，改完跑 `validate`（引用完整性会兜住漏改）。
+
+以上规则由 `tools/validate.mjs` 强制：id 必须匹配 `R<n>-S<n>` 或 `S-<n>`、不许混用风格、同一周期内冲刺号必须从 1 连续、周期号与起始日期顺序要一致（后两条分别报错与警告）。
+
+## 3. journal.json
+
+```json
+{
+  "schemaVersion": 3,
+  "journals": [
+    {
+      "taskId": "S-001-T1",
+      "storyId": "S-001",
+      "entries": [
+        {
+          "phase": "red | green | refactor",
+          "date": "2026-08-31",
+          "note": "这一步做了什么、为什么",
+          "files": ["tests/auth/login.spec.ts"],
+          "testCommand": "pnpm test auth/login",
+          "result": "fail: 3 failed, 0 passed — 404 Not Found"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## 4. last-change.json（最后更新 / 交付说明）
+
+`agile/last-change.json` 是**可选**文件：还没交付过东西时不存在，校验器不报错。看板 `/last-change` 页读的就是它。
+
+### 写之前先查 git：已提交才覆盖，未提交就合并
+
+只留最近一次交付的前提是**上一次已经进了版本库**。文件如果还有没提交的改动，直接覆盖就把那次记录冲掉了，所以写入策略分两种：
+
+| 文件在 git 里的状态 | 写法 | 结果 |
+|---|---|---|
+| 已提交、工作区干净 | 整份覆盖 | 文件里只有本次交付 |
+| 有未提交改动 / 已暂存未提交 / 未跟踪 / 不是 git 仓库 | 合并 | 本次结果并进旧记录，旧的一条不丢 |
+
+用工具判断并写入，不要手写覆盖：
+
+```bash
+node tools/last-change.mjs check           # 退出码 0 = 可覆盖，2 = 必须先合并
+node tools/last-change.mjs write <记录.json>  # 按状态自动覆盖或合并，写后校验，失败回滚
+node tools/last-change.mjs write <记录.json> --replace   # 确认旧记录不要了才强制覆盖
+```
+
+合并的取舍（`write` 自动完成，手动合并也要照这个来）：
+
+- `changes` 按 `kind:id`、`scenarios` 按 `id`（没有就按 `title`）去重：**新的覆盖旧的**，没被提到的旧条目原样保留，顺序按「旧的在前、新增的追加」；
+- `extras` 按 `title`、`verification` 按 `what`、`preparation` 按 `step` 去重，规则同上；
+- `notes` / `open` 字符串去重后拼接；`access.urls` 按 `url`、`access.accounts` 按 `username` 合并；
+- `title` / `at` / `summary` 取本次的（缺了才沿用旧的）；
+- 合并后自动带上 `"merged": true` 与 `"mergedFrom"`（被并进来的那几次交付），看板据此标「合并记录」。
+
+```json
+{
+  "schemaVersion": 3,
+  "lastChange": {
+    "title": "登录接口收尾",
+    "at": "2026-10-27 14:35:12",
+    "summary": "一句话说清这次交付做成了什么",
+    "changes": [
+      {
+        "kind": "story",
+        "id": "S-001",
+        "title": "邮箱密码登录",
+        "action": "added | updated | removed",
+        "from": "in-progress",
+        "to": "review",
+        "note": "变更内容：补了两条验收、状态推进到评审",
+        "files": ["agile/backlog.json", "src/auth/login.ts"]
+      }
+    ],
+    "extras": [{ "title": "顺手把校验错误信息改成中文", "detail": "为什么做、做到什么程度", "files": ["tools/validate.mjs"] }],
+    "verification": [{ "what": "pnpm test", "result": "pass | fail | partial | skipped", "detail": "32 passed" }],
+    "access": {
+      "urls": [{ "label": "看板", "url": "http://localhost:4173", "note": "先起 serve" }],
+      "accounts": [{ "role": "管理员", "username": "admin@example.com", "password": "Passw0rd!", "note": "仅本地环境" }]
+    },
+    "preparation": [{ "step": "装依赖", "command": "pnpm install", "note": "Node ≥ 18" }],
+    "scenarios": [
+      {
+        "id": "TC-01",
+        "title": "正确密码能登录",
+        "storyIds": ["S-001"],
+        "steps": ["打开 /login", "填表提交"],
+        "expect": "跳转首页并下发会话 cookie",
+        "acceptance": "对应验收第 1 条"
+      }
+    ],
+    "merged": true,
+    "mergedFrom": [{ "title": "上一次还没提交的交付", "at": "2026-10-26 18:02:41" }],
+    "notes": ["使用说明、口径解释"],
+    "open": ["还没做的、已知限制"]
+  }
+}
+```
+
+字段说明：
+
+- **`title` / `at` 必填**：`at` 是本次交付时间，**写到秒**：`YYYY-MM-DD HH:mm:ss`（ISO 的 `T` 分隔也认）。只写 `YYYY-MM-DD` 仍然合法，但校验器会给 WARN、看板上也只能看到「哪天」，看不出「几点几分交付的」。`node tools/last-change.mjs write` 发现缺 `at` 会自动补当前时间。
+- **`merged` / `mergedFrom` 由工具写，不要手填**：只有「并进未提交旧记录」时才出现，`mergedFrom` 每条要有 `title`（`at` 可选）。`merged: true` 却没有 `mergedFrom` 会被校验器提醒。
+- **`changes[]`**：故事与任务的变更清单，看板表格一行一条。`kind` 只认 `story` / `task`，`id` 必须是 backlg 里真实存在的 id；`action` 是 `added`（新增）/ `updated`（状态或内容变更）/ `removed`（删除）；状态变更填 `from` → `to`，`files` 是这次动过的文件。
+- **其余分区都可选**，没有就省略，**不许为了填满而编**：项目没有账号体系就不写 `accounts`，没有前端入口就不写 `urls`。
+- `verification[].result` 与 `scenarios[].expect` 是「验收不是口号」的凭据：场景必须写清步骤与验收标准，验证结果只认 `pass/fail/partial/skipped`。
+- 校验器会查：`schemaVersion`、`at` 格式、`kind`/`action`/`result` 枚举、`changes[].id` 是否真实存在、`scenarios[].steps` 与 `expect` 是否齐备、`access.urls[].url` 是否为 `http(s)` 完整地址。缺 `title`、`what`、`expect`、`step` 报错；缺 `changes[].title`、场景 id、url label 只给 WARN。
+
+## 5. tests.json（测试资产与覆盖率）
+
+`agile/tests.json` 是**可选**文件：不存在时校验器不报错、看板 `/tests` 页显示空状态。它由 Coding Agent 在**每个 task 推到 `done`、story 送进 `review` 之前**维护（见 `scrum-tdd` 的交工汇报第 1 步），不是事后补的报表。
+
+```json
+{
+  "schemaVersion": 3,
+  "suites": [
+    {
+      "id": "TS-BE-01",
+      "name": "登录接口",
+      "layer": "frontend | backend | e2e",
+      "level": "unit | integration | e2e",
+      "runner": "vitest",
+      "files": ["tests/auth/login.spec.ts"],
+      "cases": [
+        {
+          "id": "TC-BE-001",
+          "title": "正确密码登录返回 200 并下发 httpOnly cookie",
+          "automated": true,
+          "taskId": "S-001-T1",
+          "covers": ["S-001-A1"],
+          "expect": "200；set-cookie 含 sid；HttpOnly",
+          "code": "tests/auth/login.spec.ts::正确密码登录",
+          "status": "pass | fail | skipped | blocked | not-run",
+          "lastRun": "2026-10-29",
+          "durationMs": 42,
+          "note": "失败原因写在这里"
+        }
+      ]
+    }
+  ],
+  "runs": [
+    {
+      "id": "RUN-20261029-2110",
+      "at": "2026-10-29 21:10:00",
+      "env": "local",
+      "command": "pnpm test",
+      "totals": { "total": 159, "pass": 158, "fail": 1, "skipped": 0, "durationMs": 24300 },
+      "failedCases": ["TC-BE-001"],
+      "coverage": {
+        "frontend": { "tool": "vitest", "lines": 72.4, "branches": 61.5, "functions": 66.0, "report": "coverage/frontend/lcov.info" },
+        "backend": { "tool": "vitest", "lines": 84.1, "branches": 70.2, "functions": 80.5, "report": "coverage/backend/lcov.info" }
+      }
+    }
+  ]
+}
+```
+
+字段说明：
+
+- **`suites[]`** 按模块 / 测试文件分组，承载**两个正交维度**：`layer`（`frontend` / `backend` / `e2e`，QA 主视图的三条泳道）与 `level`（`unit` / `integration` / `e2e`）。`files` 只用于定位，可省。
+- **`cases[]`** 一条用例 = 一次能判定成败的验证：
+  - `automated` 区分自动化 / 手工；**手工用例也要登记**，`steps` 一步一条，这是交接给 QA 的正文；
+  - `covers` 是覆盖的验收，写法 `S-001-A1`（故事 id + 第几条验收，**1 基**）；改验收顺序要同步改它，一条 E2E 用例可以覆盖多个故事；
+  - `expect` 必填（只有标题的用例不算交付物）；`taskId` 指向产出它的 TDD 任务（可省）；`code` 是自动化用例的定位串 `文件::用例名`，导入器靠它回写状态；
+  - `status` 只认 `pass / fail / skipped / blocked / not-run`；`not-run` 不要求 `lastRun`，其余必须写。
+- **`runs[]`** 每次执行一条，**按时间正序**（最后一条 = 最近一次）：`at` 到秒、`command`、`env`、`totals`、`failedCases`，有覆盖率报告就填 `coverage`。
+  - `coverage` 按层给 `lines / branches / functions / statements` 与 `tool`：**前端、后端各报各的，绝不做加权平均**，E2E 一般不报行覆盖。
+
+覆盖率的三个口径（页面按这个算，禁止合成一个「覆盖率」）：
+
+| 口径 | 分母 | 分子 |
+|---|---|---|
+| 需求覆盖 | 非 `draft` / `cancelled` 故事的验收条数 | 被至少一条用例 `covers` 命中的条数；其中最近一次 `pass` 的另算「验证通过」 |
+| 用例通过率 | 最近一次执行的 `total - skipped` | `pass` |
+| 代码覆盖 | 测试工具报告 | `lines` / `branches`，前端、后端分开 |
+
+校验器强制：枚举合法；用例 / 套件 id 与其它记录共用一个命名空间；`covers` 指向的验收必须存在且序号不越界；`taskId` 必须存在且属于 `covers` 里的故事；`runs` 时间正序；`通过+失败+跳过 ≤ 总数`；最新一次 `failedCases` 必须对应 `status: fail`；覆盖率在 0~100 之间。
+
+收口纪律（**只查登记过用例的故事**，避免老项目一升级就满屏报错）：
+
+- 该 story 下每个 `done` 的 `type: test` task 至少一条用例 → 否则**报错**；
+- story 到 `review` / `done` 时每条验收都被覆盖 → 否则**报错**（未到 review 只给 WARN）；
+- 用例 `lastRun` 早于 task 最后一次 `pass` → WARN（结果过期了）；
+- 最近一次执行条数多于已登记用例 → WARN（还有测试没登记）。
+
+## 6. diagrams.json（架构图例）
+
+`agile/diagrams.json` 是**可选**文件：不存在时校验器不报错、看板 `/diagrams` 页显示空状态。
+
+它是**索引**，不是图本身：产物是一份自包含 HTML（内联 SVG），放在 `agile/diagrams/` 下。分开存是硬要求——一张图动辄几十 KB，塞进 JSON 会让 `/api/agile` 的快照变大好几倍，而且没法单独打开、单独 diff。
+
+```json
+{
+  "schemaVersion": 3,
+  "diagrams": [
+    {
+      "id": "DG-001",
+      "title": "登录时序",
+      "kind": "sequence",
+      "catalog": "sequence",
+      "storyIds": ["S-001"],
+      "taskId": "S-001-T2",
+      "summary": "浏览器 → 网关 → 认证服务 → Redis：会话建立、刷新与登出",
+      "file": "agile/diagrams/DG-001.html",
+      "svg": "agile/diagrams/DG-001.svg",
+      "aspect": "16:9",
+      "source": "diagram-design",
+      "lint": "pass",
+      "createdAt": "2026-10-31",
+      "updatedAt": "2026-10-31",
+      "supersedes": null
+    }
+  ]
+}
+```
+
+字段说明：
+
+- **`kind`** 是我们自己的筛选维度，只认 7 类：`architecture`（架构）/ `sequence`（时序）/ `flow`（流程）/ `erd`（ER 关系）/ `state`（状态）/ `deploy`（部署）/ `other`。
+- **`catalog`** 存 diagram-design 的原始图型名（如 `sequence`、`high-level`、`sankey`）。上游图型会从 42 种涨到 45 种、还会继续涨，所以这里**不做枚举校验**，写字符串即可。
+- **`storyIds`** 指向这张图服务的需求，可多挂（跨故事的端到端图很常见）。**单向引用**：故事那边不写 `diagrams` 字段，反向列表由页面派生。
+- **`taskId`** 可选，指向产出它的 TDD 任务；填了就必须属于 `storyIds` 里的故事。
+- **`file` / `svg`** 必须是 `agile/diagrams/` 下的**相对路径**，不许绝对路径、不许 `..`；`file` 必须真实存在。
+- **`lint`**：`pass`（过质检）/ `skipped`（明确 `--no-lint` 跳过）。图例入库走 `node tools/diagram.mjs add`，它会先跑 `node tools/diagram-lint.mjs` 再登记，不要手改 JSON。
+- **`supersedes`**：指向被本图取代的旧版，用来保留演进痕迹；不许自引用、不许成环。
+
+校验器强制：`schemaVersion`、id 形如 `DG-001` 且全局唯一、`title` / `kind` / `file` / 日期齐备、`file` 路径合法且存在、`storyIds` 与 `taskId` 引用真实存在且互相一致、`supersedes` 可解析且无环。
+
+校验器提醒（WARN）：`agile/diagrams/*.html` 存在但索引里没有（孤儿文件）；`updatedAt` 早于所挂故事最后一次 `pass` 的日志日期（图可能画的是改之前的版本）。
+
+收口纪律：改动涉及**模块边界 / 鉴权 / 支付 / 数据模型 / 外部集成**时，交工前用内置的 `diagram-design` skill 出图或重画，再 `node tools/diagram.mjs add` 登记；纯样式、文案、测试改动不需要画。
+
+## 状态机（校验器强制）
+
+- story: `draft → ready → in-progress → review → done`；不做了直接进 `cancelled`（已取消）终态（可回退，不可跳级；`done` 与 `cancelled` 都是终态）
+- task: `todo → red → green → refactored → done`（只能前进；test 型可 `todo → green`）
+- epic: 无强制流转，但 `done` 要求其下所有 story 均 `done/cancelled`
+- milestone: `planned → at-risk → reached / missed`
+
+## 硬约束（校验器强制 / 警告）
+
+1. ID 全局唯一（epic / story / task / sprint / milestone / suite / case 共用命名空间），task 命名 `<storyId>-T<n>`
+2. **双向引用一致**：`epic.stories` ↔ `story.epicId`、`sprint.stories` ↔ `story.sprintId`、`journal.taskId` ↔ task
+3. `ready` / `in-progress` / `review` / `done` 必须有验收标准；进 sprint 的故事必须有验收标准（`cancelled` 两样都不要求）
+4. 验收标准的 `verifyBy` 必须指向**同一 story 的** task
+5. task 到 `green/refactored/done` 时，journal 必须存在且首条 `red` 的 result 以 `fail` 开头、`green` 以 `pass` 开头
+6. task 为 `done` 时，journal 末条 entry 的 `result` 必须 `pass`
+7. story 为 `done` 时，其所有 task 必须 `done`，且不许仍标着 `blocked`
+8. 同时只能有一个活跃 sprint（`start ≤ 今天 ≤ end`）
+9. `dependsOn` 必须存在、不能自依赖、不能成环
+10. `schedule.start ≤ schedule.end`；计划区间超出所属迭代只给 WARN
+11. sprint 承诺点数超过 `capacity` → WARN
+12. epic 没有 `keyResults` → WARN（史诗要有量化目标）
+13. `cancelled` 是终态：不要求验收、不要求 task 全部 `done`；但仍标着 `blocked` 报错；还留在某个 sprint 里只给 WARN —— 它的点数不计入承诺容量，看板的燃尽图与里程碑完成度同样把它扣掉