scrum-skills 0.0.0-stage → 0.1.0

package/.agents/skills/scrum-planning/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: scrum-planning
+description: 将用户与 AI 的需求对话约束为结构化敏捷数据（Epic/Story/Task），落库到 agile/ 目录。适用于需求澄清、故事编写、验收标准定义、任务拆解等规划场景。
+---
+
+# scrum-planning：需求对话 → 结构化敏捷数据
+
+## 何时使用
+
+用户提出新需求、新功能、新改进，或要求澄清/拆解/评审已有需求时使用本 skill。
+
+## 核心纪律
+
+1. **禁止只聊天**。凡是确认要做的事，必须落成 `agile/backlog/` 下的 JSON 文件（schema 见 `references/schema.md`）。对话中的口头结论不算数，文件才算数。
+2. **禁止凭空拆解**。写 story 前先用 1~3 轮对话澄清：角色、价值、边界、验收标准。澄清结果写进 `narrative` 和 `acceptance`，不许留在对话记录里。
+3. **数据是唯一事实来源**。后续实施只读文件不读对话记忆。AI 每次接手必须先读 `agile/` 下相关 JSON，再决定下一步。
+
+## 工作流
+
+1. **定位层级**：判断这是 Epic（多迭代的大目标）还是 Story（一个迭代内可交付的用户价值）。拿不准就先建 Epic，Story 留空壳。
+2. **写 Story**：
+   - `narrative` 必须是「作为 X，我想要 Y，以便 Z」三段式
+   - `acceptance` 至少 1 条，用 given/when/then 格式，必须可验证（能写测试或能演示）
+   - `points` 按斐波那契估（1/2/3/5/8），不确定就标 8 并在下次规划重估
+3. **拆 Task**：每个 story 拆成 test/impl/refactor/chore 型任务：
+   - **test 型任务先行**：每条可自动验证的 acceptance 至少对应一个 test 型 task
+   - test 与 impl 分开拆，不许一个 task 既写测试又写实现
+   - 每个 task 必须有 `journal` 字段指向日志文件（先建空壳不写内容）
+4. **编号**：取当前最大编号 +1，E-001/S-001 格式，不复用已删除编号。
+5. **落库后**：向用户复述 story id 与验收标准清单，运行 `node tools/validate.mjs` 确认通过。
+
+## 输出模板（对话中的回复结构）
+
+1. 一句话结论（做了什么、为什么）
+2. 新建/修改的文件清单
+3. 验收标准逐条列出请用户确认
+4. 校验结果
+
+## 反模式（禁止）
+
+- 只在对话里描述需求，不落文件
+- acceptance 写「功能正常」「体验良好」这类不可验证的空话
+- 把 test 和 impl 塞进同一个 task
+- 修改 story 时不更新 acceptance 却改了行为（验收标准必须与实现同步演进）

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

@@ -0,0 +1,93 @@
+# 敏捷数据 Schema 规范（唯一事实来源）
+
+所有文件为 UTF-8 JSON，2 空格缩进，末尾换行。禁止出现 schema 未定义的字段。
+路径与命名固定：`agile/backlog/epics/E-<3位>.json`、`agile/backlog/stories/S-<3位>.json`、`agile/sprints/<id>.json`、`agile/journal/<storyId>-<taskId>.json`。
+
+## Epic（敏捷史诗）
+
+```json
+{
+  "id": "E-001",
+  "title": "用户认证",
+  "goal": "一句话说明这个史诗完成后用户获得了什么",
+  "status": "draft | active | done | cancelled",
+  "stories": ["S-001"],
+  "created": "2026-10-25"
+}
+```
+
+## Story（用户故事）
+
+```json
+{
+  "id": "S-001",
+  "epicId": "E-001",
+  "title": "邮箱密码登录",
+  "narrative": "作为<角色>，我想要<能力>，以便<价值>",
+  "acceptance": [
+    { "given": "已注册用户", "when": "输入正确邮箱密码提交", "then": "建立会话并跳转首页" }
+  ],
+  "tasks": [
+    {
+      "id": "S-001-T1",
+      "title": "为登录接口写失败测试",
+      "type": "test | impl | refactor | chore",
+      "status": "todo | red | green | refactored | done",
+      "files": [],
+      "journal": "agile/journal/S-001-T1.json"
+    }
+  ],
+  "points": 3,
+  "status": "draft | ready | in-progress | review | done",
+  "sprintId": null,
+  "created": "2026-10-25"
+}
+```
+
+## Sprint（迭代）
+
+```json
+{
+  "id": "P01-S1",
+  "name": "第 1 个迭代",
+  "goal": "本迭代要交付什么",
+  "start": "2026-10-26",
+  "end": "2026-11-08",
+  "stories": ["S-001"],
+  "capacity": 20
+}
+```
+
+## Journal（TDD 实施日志，每 task 一篇）
+
+```json
+{
+  "taskId": "S-001-T1",
+  "storyId": "S-001",
+  "entries": [
+    {
+      "phase": "red | green | refactor",
+      "date": "2026-10-26",
+      "note": "这一步做了什么、为什么",
+      "files": ["src/auth/login.ts"],
+      "testCommand": "pnpm test auth",
+      "result": "fail: 1 failed, 0 passed | pass: 3 passed"
+    }
+  ]
+}
+```
+
+## 状态机（校验脚本强制）
+
+- story: `draft → ready → in-progress → review → done`（可回退，不可跳级；`cancelled` 例外）
+- task: `todo → red → green → refactored → done`（只许前进；test 型 task 从 `todo` 直达 `green` 后视情况跳 refactor）
+- epic: 无强制流转，但 `done` 要求其下所有 story 均 `done/cancelled`
+
+## 硬约束（校验脚本强制）
+
+1. 所有 ID 引用必须存在且指向正确类型（epicId / sprintId / stories / journal）
+2. task 状态为 `green/refactored/done` 时，journal 必须存在且含至少一条 `phase: "red"` 的失败记录和一条 `phase: "green"` 的通过记录
+3. task 状态为 `done` 时，journal 最后一条 entry 的 `result` 必须是 `pass`
+4. story 状态为 `done` 时，其所有 task 必须 `done`
+5. story 进入 sprint（sprintId 非空）前必须为 `ready`（acceptance 非空且 ≥1 条）
+6. ID 全局唯一且不可复用；文件名与内部 id 一致

package/.agents/skills/scrum-report/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: scrum-report
+description: 从 agile/ 结构化数据生成可视化展示（看板、燃尽图、追溯链）。适用于查看进度、回顾、汇报、核对数据完整性等场景。
+---
+
+# scrum-report：数据可视化
+
+## 何时使用
+
+用户想看进度、看板、燃尽图、某个 story 的实施追溯链，或要求核对数据时使用。
+
+## 工具
+
+启动本地 server（由 scrum-skills CLI 提供，零依赖，node ≥ 18）：
+
+```bash
+npx scrum-skills serve          # 默认当前目录 http://localhost:4173
+npx scrum-skills serve . 8080   # 指定目录与端口
+```
+
+server 读取 `agile/` 全量 JSON，纯内存聚合，不写文件。改了数据刷新页面即生效。
+
+## 页面
+
+- `/` 看板：按 story 状态分列（draft/ready/in-progress/review/done），卡片显示 id、标题、点数、task 进度条
+- `/burndown` 燃尽图：当前活跃 sprint 的剩余点数曲线（无活跃 sprint 时提示）
+- `/story/S-001` 追溯链：acceptance → task → journal 每阶段（red/green/refactor）的完整记录
+
+## 纪律
+
+1. 展示前先跑 `node tools/validate.mjs`，**校验不过的数据不许出报表**——先修数据
+2. 报表只读 JSON，不许为展示改数据；发现数据缺漏时向用户报告并用 planning/sprint/tdd skill 补
+3. 向用户汇报进度时引用具体 id（S-001、S-001-T2），不许说「差不多了」「快完成了」这类没有数据支撑的口径
+4. 燃尽图数据来自 journal 的 date 字段；某 task 没写 journal 导致曲线缺点的，如实显示缺口并指出责任 story

package/.agents/skills/scrum-sprint/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: scrum-sprint
+description: 管理 Sprint 迭代周期与 Story 状态流转，落库到 agile/sprints/。适用于排期、组建迭代、状态更新、每日进度同步等场景。
+---
+
+# scrum-sprint：迭代排期与状态流转
+
+## 何时使用
+
+用户要求排期、组建/启动/收尾一个迭代、更新任务进度、回顾时使用本 skill。
+
+## 前置
+
+先读 `agile/backlog/stories/` 全量与当前活跃 sprint，掌握真实状态。**状态以文件为准，对话记忆一律作废。**
+
+## 工作流
+
+### 组建 Sprint
+
+1. 从 backlog 中挑 `ready` 状态的 story（不满足 ready 的先回 scrum-planning 补验收标准）
+2. 总点数不超过 `capacity`（默认 20，可和用户商量）
+3. 写 `agile/sprints/<id>.json`（id 格式 `P<迭代序号>-S<期号>` 如 `P01-S1`），story 的 `sprintId` 同步更新
+4. 被选中的 story 状态改为 `in-progress`（或 sprint 启动时改）
+
+### 状态流转（严格按状态机，见 planning skill 的 schema.md）
+
+- story: `draft → ready → in-progress → review → done`
+- task: `todo → red → green → refactored → done`
+- 每次流转必须同步落库并运行 `node tools/validate.mjs`
+- story 到 `review` 的条件：所有 task 为 `done` 且验收标准逐条核对过
+- story 到 `done` 由用户确认，AI 不许自行关闭
+
+### 收尾 / 回顾
+
+1. sprint 到期：未完成 story 回 backlog（`sprintId` 置 null，状态回 `ready`），完成项保持 `done`
+2. 生成回顾小结写入对话（做了什么/没做什么/为什么），不落文件除非用户要求
+3. 建议用户运行 `node tools/serve.mjs` 查看燃尽图核对进度
+
+## 硬约束
+
+- 一次只能有一个活跃 sprint（`start` 已过且 `end` 未到的最多一个）
+- 不许把 `draft` 状态的 story 排进 sprint（校验脚本会报错）
+- task 状态只能前进不能回退；发现做错了就新建 chore task 处理
+- 每次修改后必须校验，校验失败时先修复数据再继续对话

package/.agents/skills/scrum-tdd/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: scrum-tdd
+description: 以 red-green-refactor TDD 循环驱动任务实施，并把每一步过程落库到 agile/journal/。适用于领取任务、写代码、跑测试、重构等实施场景。
+---
+
+# scrum-tdd：TDD 驱动实施 + 过程落库
+
+## 何时使用
+
+领取 task 开始写代码时使用本 skill。**没有 task id 不开工**——先回 scrum-planning 建故事拆任务。
+
+## 前置
+
+1. 读目标 story 的 JSON（验收标准 + task 列表）
+2. 找到第一个非 `done` 的 task，确认其 `type`
+3. 读该 task 的 journal（若有历史条目，从上次断点继续）
+
+## Red-Green-Refactor 循环（每轮三阶段，顺序铁律）
+
+### 🔴 Red（先写失败测试）
+
+1. 按 acceptance 写一条会失败的测试（test 型 task 的本职；impl 型 task 先确认对应 test task 已 red）
+2. 跑测试，**确认它因正确的原因失败**（不是语法错、不是环境错）
+3. journal 追加 entry：`phase:"red"`、note 写测试意图、`result` 记 `fail: <原因>`
+4. task 状态 → `red`
+
+### 🟢 Green（最小实现让测试通过）
+
+1. 写**刚好**让测试通过的实现，不许顺手加没测试覆盖的功能
+2. 跑测试直到通过
+3. journal 追加 `phase:"green"` entry，`result` 记 `pass: <统计>`
+4. task 状态 → `green`
+
+### 🔵 Refactor（在绿灯保护下清理）
+
+1. 测试全绿的前提下消除重复、命名、结构问题；每步小改、改完立即跑测试
+2. 有实质重构才写 journal entry（`phase:"refactor"`），零碎小改可并入 green entry
+3. task 状态 → `refactored`（无实质重构可直接 `green → done`）
+
+### ✅ Done
+
+1. 最后一次全量测试通过，journal 末条 `result` 为 `pass`
+2. task 状态 → `done`，`files` 补齐本次触碰的文件
+3. story 的所有 task 都 done → 提醒用户进入 review（scrum-sprint skill）
+
+## Journal 纪律
+
+- 每个 task 一篇 `agile/journal/<storyId>-<taskId>.json`，**每次状态推进必须当场追加 entry**，不许攒到最后补
+- note 写「为什么」不写「什么」（文件名 git log 里都有）
+- 中断（用户喊停/上下文不够）：journal 追加一条 note 说明断点在哪，task 状态留在当前阶段
+
+## 硬约束
+
+- **没 red 过不许写实现**——task 直接从 todo 跳 green 属违规（校验脚本会查 journal 必须先有 red 后有 green）
+- 测试骗不过状态机：`done` 的 task journal 末条必须 pass
+- 不许为让测试通过而删除/跳过/弱化测试；确需改测试时在 journal 的 note 里说明理由
+- 一次只做一个 task 的一个阶段，禁止批量推进多个 task 状态

package/bin/scrum-skills.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * scrum-skills CLI（零依赖，node >= 18）
+ * 命令:
+ *   scrum-skills init [dir] [--force]  初始化敏捷开发文件到目标文件夹（默认当前目录）
+ *                                      拷贝 .agents/skills/、AGENTS.md、tools/validate.mjs，建 agile/ 目录骨架
+ *                                      已存在 AGENTS.md 时拒绝，--force 覆盖（备份为 AGENTS.md.bak）
+ *   scrum-skills serve [dir] [port]    启动可视化 server（默认当前目录，端口 4173）
+ *   scrum-skills validate [dir]        校验敏捷数据（默认当前目录）
+ */
+import { cpSync, mkdirSync, existsSync, writeFileSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const PKG_ROOT = fileURLToPath(new URL('..', import.meta.url));
+const HELP = `用法:
+  scrum-skills init [dir] [--force]      初始化敏捷开发文件到目标文件夹（默认当前目录）
+  scrum-skills serve [dir] [port]        启动可视化 server（默认当前目录，端口 4173）
+  scrum-skills validate [dir]            校验敏捷数据（默认当前目录）
+  scrum-skills help                      显示本帮助`;
+
+const [cmd, ...args] = process.argv.slice(2);
+const fail = msg => { console.error(`✘ ${msg}`); process.exit(1); };
+
+function init() {
+  const force = args.includes('--force');
+  const dir = resolve(args.find(a => !a.startsWith('--')) || process.cwd());
+  if (!existsSync(dir)) fail(`目录不存在: ${dir}`);
+
+  const agentsMd = join(dir, 'AGENTS.md');
+  if (existsSync(agentsMd) && !force)
+    fail(`目标目录已有 AGENTS.md。确认覆盖请加 --force（旧文件会备份为 AGENTS.md.bak）`);
+  const backed = existsSync(agentsMd);
+  if (backed) cpSync(agentsMd, `${agentsMd}.bak`);
+
+  cpSync(join(PKG_ROOT, '.agents'), join(dir, '.agents'), { recursive: true, force: true });
+  writeFileSync(agentsMd, readFileSync(join(PKG_ROOT, 'templates/AGENTS.md'), 'utf8'));
+
+  mkdirSync(join(dir, 'tools'), { recursive: true });
+  cpSync(join(PKG_ROOT, 'tools/validate.mjs'), join(dir, 'tools/validate.mjs'));
+
+  for (const sub of ['backlog/epics', 'backlog/stories', 'sprints', 'journal'])
+    mkdirSync(join(dir, 'agile', sub), { recursive: true });
+
+  console.log(`✔ 已初始化到 ${dir}
+  - .agents/skills/      四个敏捷 skill（planning / sprint / tdd / report）
+  - AGENTS.md            agent 入口纪律文件${backed ? '（旧文件已备份为 AGENTS.md.bak）' : ''}
+  - tools/validate.mjs   数据校验脚本
+  - agile/               数据目录骨架（backlog / sprints / journal）
+
+下一步:
+  1. 在目标项目里让 AI 读 AGENTS.md，用 scrum-planning 建第一个 story
+  2. 每次改动后运行: node tools/validate.mjs
+  3. 看板/燃尽图: 在目标项目目录下运行 scrum-skills serve`);
+}
+
+function runTool(script, needPort) {
+  const positional = args.filter(a => !a.startsWith('--'));
+  const dir = resolve(positional[0] || process.cwd());
+  if (!existsSync(dir)) fail(`目录不存在: ${dir}`);
+  const port = needPort ? (positional[1] || '4173') : null;
+  const r = spawnSync(process.execPath,
+    [join(PKG_ROOT, 'tools', script), dir, ...(port ? [port] : [])],
+    { stdio: 'inherit' });
+  process.exit(r.status ?? 1);
+}
+
+switch (cmd) {
+  case 'init': init(); break;
+  case 'serve': runTool('serve.mjs', true); break;
+  case 'validate': runTool('validate.mjs', false); break;
+  case 'help': case '-h': case '--help': case undefined:
+    console.log(HELP); break;
+  default:
+    console.error(`未知命令: ${cmd}\n`);
+    console.log(HELP);
+    process.exit(1);
+}

package/package.json

@@ -1,6 +1,19 @@
-{
-  "name": "scrum-skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "scrum-skills",
+  "version": "0.1.0",
+  "description": "结构化敏捷开发管理 skills + CLI：AI 对话产出结构化敏捷数据，TDD 驱动实施，数据可视化看板",
+  "type": "module",
+  "bin": {
+    "scrum-skills": "./bin/scrum-skills.mjs"
+  },
+  "files": [
+    "bin/",
+    "tools/",
+    "templates/",
+    ".agents/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/templates/AGENTS.md

@@ -0,0 +1,42 @@
+# AGENTS.md
+
+本项目采用结构化敏捷开发管理。**任何 agent（CodeBuddy / Claude Code / Cursor 等）在本项目内工作前，必须先读本文件并遵守以下纪律。**
+
+## 强制规则
+
+1. **数据是唯一事实来源**。所有需求、任务、进度状态以 `agile/` 目录下的 JSON 文件为准，对话记忆一律不作数。每次接手工作先读 `agile/` 掌握现状，再决定下一步。
+2. **必须使用敏捷 skills**（位于 `.agents/skills/`），按场景加载，不要全量加载（省上下文）：
+   - 需求澄清、写故事、拆任务 → **scrum-planning**
+   - 排期、组建迭代、状态流转、收尾回顾 → **scrum-sprint**
+   - 领取任务写代码（TDD 循环 + 实施日志落库）→ **scrum-tdd**
+   - 看板/燃尽图/追溯链可视化 → **scrum-report**
+3. **对话产出必须落库**。凡是确认要做的事，必须写进 `agile/backlog/`（结构见 `.agents/skills/scrum-planning/references/schema.md`），禁止只停留在对话里。
+4. **TDD 铁律**：任务实施走 red → green → refactor 循环，没写过失败测试不许写实现；每步过程必须当场写入 `agile/journal/`（不许事后补记）。
+5. **每次修改敏捷数据后必须运行校验**，校验不过不许继续：
+
+   ```bash
+   node tools/validate.mjs
+   ```
+
+6. **可视化**（server 不在本项目内，由 scrum-skills CLI 提供）：
+
+   ```bash
+   npx scrum-skills serve        # http://localhost:4173 看板 / 燃尽图 / story 追溯链
+   ```
+
+## 状态机（摘要）
+
+- story: `draft → ready → in-progress → review → done`
+- task: `todo → red → green → refactored → done`（只能前进；task 状态编码了 TDD 阶段）
+- 详细规则与硬约束见 `.agents/skills/scrum-planning/references/schema.md`。
+
+## 目录索引
+
+| 路径 | 内容 |
+|---|---|
+| `.agents/skills/` | 四个敏捷 skill（planning / sprint / tdd / report） |
+| `agile/backlog/epics/` | 史诗 E-*.json |
+| `agile/backlog/stories/` | 用户故事 S-*.json（含验收标准与任务） |
+| `agile/sprints/` | 迭代 P*-S*.json |
+| `agile/journal/` | 每任务一篇 TDD 实施日志 |
+| `tools/validate.mjs` | 数据校验（引用完整性 / 状态机 / TDD 纪律） |

package/tools/serve.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * 敏捷数据可视化 server（零依赖，node >= 18）
+ * 用法: node tools/serve.mjs [目标目录] [port]   目录默认 cwd，端口默认 4173
+ * 页面: / 看板 | /burndown 燃尽图 | /story/:id 追溯链
+ * 校验不通过时拒绝出报表，提示先跑 validate
+ */
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join, basename, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const PKG_ROOT = new URL('..', import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1');
+const TARGET = resolve(process.argv[2] || process.cwd());
+const PORT = Number(process.argv[3] || 4173);
+const AGILE = join(TARGET, 'agile');
+
+// ---- 数据加载 ----
+function readJson(dir) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const f of readdirSync(dir)) if (f.endsWith('.json'))
+    out.push(JSON.parse(readFileSync(join(dir, f), 'utf8')));
+  return out;
+}
+function load() {
+  return {
+    epics: readJson(join(AGILE, 'backlog/epics')),
+    stories: readJson(join(AGILE, 'backlog/stories')),
+    sprints: readJson(join(AGILE, 'sprints')),
+    journals: readJson(join(AGILE, 'journal')),
+  };
+}
+
+// ---- 聚合 ----
+function storyCard(s) {
+  const tasks = s.tasks ?? [];
+  const done = tasks.filter(t => t.status === 'done').length;
+  return { id: s.id, title: s.title, points: s.points, sprintId: s.sprintId,
+           epicId: s.epicId, done, total: tasks.length };
+}
+function burndown(sprints, stories, journals) {
+  const today = new Date().toISOString().slice(0, 10);
+  const sp = sprints.filter(s => s.start <= today && s.end >= today)[0] || sprints[0];
+  if (!sp) return null;
+  const total = (sp.stories ?? []).reduce((a, sid) => {
+    const st = stories.find(s => s.id === sid); return a + (st?.points ?? 0);
+  }, 0);
+  // 每个 task 的 done 日期取其 journal 最后一条 pass 的 date
+  const doneDate = new Map();
+  for (const j of journals) {
+    const entries = (j.entries ?? []).filter(e => /^pass/i.test(e.result || ''));
+    if (entries.length) doneDate.set(j.taskId, entries[entries.length - 1].date);
+  }
+  const days = [];
+  for (let d = new Date(sp.start); d <= new Date(sp.end); d.setDate(d.getDate() + 1)) {
+    const ds = d.toISOString().slice(0, 10);
+    let burned = 0;
+    for (const sid of sp.stories ?? []) {
+      const st = stories.find(s => s.id === sid);
+      if (!st || st.status !== 'done') continue;
+      const nDone = (st.tasks ?? []).filter(t => doneDate.get(t.id) <= ds).length;
+      burned += (st.points || 0) * ((st.tasks?.length || 1) > 0 ? nDone / st.tasks.length : 0);
+    }
+    days.push({ date: ds, remaining: Math.round((total - burned) * 10) / 10 });
+  }
+  return { sprint: sp, total, days };
+}
+
+// ---- 页面（内联极简 HTML+SVG，无外部依赖） ----
+const CSS = `<style>
+ *{box-sizing:border-box} body{font:14px/1.6 system-ui,sans-serif;margin:0;background:#f5f6fb;color:#1b1c20}
+ header{background:linear-gradient(135deg,#4a7cf6,#7a5af5);color:#fff;padding:18px 28px}
+ header a{color:#fff;margin-right:18px;text-decoration:none;opacity:.9}
+ main{padding:24px;max-width:1200px;margin:0 auto}
+ .cols{display:grid;grid-template-columns:repeat(auto-fit,minmax(200px,1fr));gap:14px}
+ .col h3{margin:0 0 8px;font-size:13px;color:#666}
+ .card{background:#fff;border-radius:12px;box-shadow:0 2px 8px rgba(0,0,0,.06);padding:12px;margin-bottom:10px}
+ .card b{font-size:14px} .meta{font-size:12px;color:#888;margin-top:4px}
+ .bar{height:5px;background:#e9edfe;border-radius:99px;margin-top:8px;overflow:hidden}
+ .bar i{display:block;height:100%;background:linear-gradient(90deg,#4a7cf6,#7a5af5)}
+ .chip{display:inline-block;background:#e9edfe;border:1px solid #d7ddfc;border-radius:99px;padding:0 9px;font-size:11px;margin-right:6px}
+ .ac{background:#fff;border-radius:12px;box-shadow:0 2px 8px rgba(0,0,0,.06);padding:14px;margin-bottom:12px}
+ .phase{border-left:4px solid #ccc;padding:8px 14px;margin:8px 0;background:#fff;border-radius:0 10px 10px 0}
+ .red{border-color:#e05260}.green{border-color:#3aa76d}.refactor{border-color:#4a7cf6}
+ pre{background:#f0f1f5;padding:8px 12px;border-radius:8px;overflow:auto;font-size:12px}
+</style>`;
+const page = (title, body) => `<!doctype html><html lang="zh"><head><meta charset="utf-8"><title>${title}</title>${CSS}</head>
+<body><header><strong>敏捷看板</strong>
+<a href="/">看板</a><a href="/burndown">燃尽图</a></header><main>${body}</main></body></html>`;
+
+function kanbanHtml(d) {
+  const cols = ['draft', 'ready', 'in-progress', 'review', 'done'];
+  const label = { draft: '草稿', ready: '就绪', 'in-progress': '进行中', review: '评审', done: '完成' };
+  return page('看板', `<h2>看板</h2><div class="cols">` + cols.map(c => {
+    const cards = d.stories.filter(s => (s.status ?? 'draft') === c).map(s => {
+      const sc = storyCard(s);
+      const pct = sc.total ? Math.round(sc.done / sc.total * 100) : 0;
+      return `<div class="card"><span class="chip">${sc.id}</span>${sc.sprintId ? `<span class="chip">${sc.sprintId}</span>` : ''}
+        <b><a href="/story/${sc.id}">${sc.title}</a></b>
+        <div class="meta">${sc.epicId ?? ''} · ${sc.points ?? '?'} 点 · 任务 ${sc.done}/${sc.total}</div>
+        <div class="bar"><i style="width:${pct}%"></i></div></div>`;
+    }).join('');
+    return `<div class="col"><h3>${label[c]}（${cards ? d.stories.filter(s => s.status === c).length : 0}）</h3>${cards}</div>`;
+  }).join('') + '</div>');
+}
+
+function burndownHtml(d) {
+  const b = burndown(d.sprints, d.stories, d.journals);
+  if (!b) return page('燃尽图', '<h2>燃尽图</h2><p>暂无 sprint 数据。</p>');
+  const W = 900, H = 320, P = 40;
+  const n = b.days.length || 1;
+  const maxV = b.total || 1;
+  const x = i => P + i * (W - 2 * P) / (n - 1 || 1);
+  const y = v => H - P - v * (H - 2 * P) / maxV;
+  const pts = b.days.map((d, i) => `${x(i)},${y(d.remaining)}`).join(' ');
+  const ideal = `M${x(0)},${y(b.total)} L${x(n - 1)},${y(0)}`;
+  const labels = b.days.map((d, i) => i % Math.ceil(n / 10) === 0
+    ? `<text x="${x(i)}" y="${H - 15}" font-size="10" text-anchor="middle" fill="#888">${d.date.slice(5)}</text>` : '').join('');
+  return page('燃尽图', `<h2>燃尽图 — ${b.sprint.name}（${b.sprint.start} ~ ${b.sprint.end}，总 ${b.total} 点）</h2>
+  <svg viewBox="0 0 ${W} ${H}" style="max-width:960px;width:100%">
+    <line x1="${P}" y1="${y(0)}" x2="${W - P}" y2="${y(0)}" stroke="#ccc"/>
+    <line x1="${P}" y1="${P}" x2="${P}" y2="${y(0)}" stroke="#ccc"/>
+    <path d="${ideal}" stroke="#c9c9d4" stroke-dasharray="6 5" fill="none"/>
+    <polyline points="${pts}" stroke="#4a7cf6" stroke-width="2.5" fill="none"/>
+    ${b.days.map((d, i) => `<circle cx="${x(i)}" cy="${y(d.remaining)}" r="3.5" fill="#7a5af5"/>`).join('')}
+    ${labels}
+  </svg><p class="meta">虚线为理想燃尽线；点数据来自 journal 的 pass 日期，缺口说明有 task 未按纪律落库。</p>`);
+}
+
+function storyHtml(d, id) {
+  const s = d.stories.find(x => x.id === id);
+  if (!s) return page('404', `<h2>未找到 ${id}</h2>`);
+  const ac = (s.acceptance ?? []).map(a =>
+    `<li><b>Given</b> ${a.given}；<b>When</b> ${a.when}；<b>Then</b> ${a.then}</li>`).join('');
+  const tasks = (s.tasks ?? []).map(t => {
+    const j = d.journals.find(x => x.taskId === t.id);
+    const entries = (j?.entries ?? []).map(e =>
+      `<div class="phase ${e.phase}"><b>${e.phase.toUpperCase()}</b> <span class="meta">${e.date} · ${e.result ?? ''}</span>
+       <div>${e.note}</div>${e.files?.length ? `<div class="meta">文件：${e.files.join(', ')}</div>` : ''}
+       ${e.testCommand ? `<pre>${e.testCommand}</pre>` : ''}</div>`).join('');
+    return `<div class="ac"><span class="chip">${t.id}</span><span class="chip">${t.type}</span><span class="chip">${t.status}</span>
+      <b>${t.title}</b>${entries || '<p class="meta">暂无实施记录</p>'}</div>`;
+  }).join('');
+  return page(id, `<h2><span class="chip">${s.id}</span>${s.title}</h2>
+    <p>${s.narrative ?? ''}</p><p class="meta">${s.epicId ?? ''} · ${s.sprintId ?? '未排期'} · ${s.points ?? '?'} 点 · 状态 ${s.status}</p>
+    <h3>验收标准</h3><ol>${ac}</ol><h3>任务与实施记录</h3>${tasks}`);
+}
+
+// ---- server ----
+try { execFileSync(process.execPath, [join(PKG_ROOT, 'tools/validate.mjs'), TARGET], { stdio: 'pipe' }); }
+catch (e) {
+  console.error(`✘ ${TARGET} 下的数据校验未通过，拒绝出报表。请先修复：\n` + e.stdout);
+  process.exit(1);
+}
+import('node:http').then(({ createServer }) => {
+  createServer((req, res) => {
+    const d = load();
+    const url = new URL(req.url, 'http://x');
+    let html = null;
+    if (url.pathname === '/') html = kanbanHtml(d);
+    else if (url.pathname === '/burndown') html = burndownHtml(d);
+    else if (url.pathname.startsWith('/story/')) html = storyHtml(d, url.pathname.slice(7));
+    if (html) { res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }); res.end(html); }
+    else { res.writeHead(404); res.end('not found'); }
+  }).listen(PORT, () => console.log(`敏捷看板: http://localhost:${PORT}`));
+});

package/tools/validate.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+/**
+ * 敏捷数据校验脚本（零依赖）
+ * 用法: node tools/validate.mjs [目标目录]   默认当前工作目录
+ * 校验 <目标>/agile/ 下所有 JSON 的引用完整性、状态机、TDD 纪律。
+ * 退出码: 0 通过, 1 有错误。
+ */
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join, basename, resolve } from 'node:path';
+
+const TARGET = resolve(process.argv[2] || process.cwd());
+const AGILE = join(TARGET, 'agile');
+const errors = [];
+const warns = [];
+
+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}`);
+    }
+  }
+  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);
+  }
+}
+for (const j of journals) {
+  const sid = j.data.storyId;
+  if (sid && !storyIds.has(sid)) errors.push(`${j.file}: storyId ${sid} 不存在`);
+}
+
+const STORY_FLOW = ['draft', 'ready', 'in-progress', 'review', 'done'];
+const TASK_FLOW = ['todo', 'red', 'green', 'refactored', 'done'];
+
+// Story 校验
+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}`);
+  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）`);
+  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}`);
+    }
+  }
+  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}`);
+  }
+}
+
+// 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`);
+}
+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`);
+    }
+  }
+}
+
+// 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}`);
+    }
+  }
+}
+
+// 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} 不存在`);
+  }
+  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`);
+} else {
+  console.error(`✘ 校验失败，共 ${errors.length} 处错误：`);
+  for (const e of errors) console.error(`  - ${e}`);
+  process.exit(1);
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.