scrum-skills 0.3.2 → 0.3.3

package/.agents/skills/diagram-design/references/type-waterfall.md

@@ -0,0 +1,75 @@
+# Waterfall Chart
+
+**Best for:** showing how a start total becomes an end total through signed contributions — a budget bridge (FY25 baseline → FY26 plan), headcount deltas (starting roster ± hires ± attrition), conversion leak/gain, P&L walk. Use when the running total is the story: every bar either anchors the total or bridges one running level to the next, and the reader traces the path from start to end.
+
+**Not this type:**
+
+- Two endpoints where only the *gap* matters → **dumbbell** (a Bar variant, `type-bar.md`). A dumbbell states two values and their distance; a waterfall states a path of signed steps that must reconcile. The types look adjacent but make opposite claims: the dumbbell hides what happened in between, the waterfall *is* what happened in between.
+- Independent category comparisons → **bar** (`type-bar.md`).
+- One quantity splitting and merging across stages → **Sankey** (`type-sankey.md`). A waterfall is strictly sequential and one-dimensional; the bars never branch.
+- Ordered drop-off through stages of one funnel → **pyramid / funnel** (`type-pyramid.md`).
+
+## Layout conventions
+
+- **Orientation:** vertical columns only, left → right in narrative order: start total, then each signed bridge, optional subtotal, end total. A horizontal waterfall reads as a Gantt.
+- **Plot area:** left 80px (y-axis labels), bottom 60px (category labels), top 40px, right 40px — inside a `0 0 1000 500` viewBox, same frame as the bar chart. Plot band x 80→960, y 40→420.
+- **Bar count:** 3–8 bars total, including both totals and at most one subtotal. More contributions than that → merge the tail into one named "Other" bridge (disclose what it contains) or split the walk into two charts.
+- **Bar width / pitch:** equal-width bars on an even pitch, bar ≥ 50% of the pitch. Six bars fit as width=96 on a 144px pitch starting at x=112.
+- **Totals anchor, bridges float.** The start total, any subtotal, and the end total are drawn from the domain floor (the x-axis baseline) up to their value. Bridge bars span exactly the running total before and after their contribution — an increase rises from the previous level, a decrease falls from it.
+- **Carry rules (the bridge grammar).** A horizontal connector line carries the running total across each gap between adjacent bars, drawn at the shared level: from the right edge of one bar to the left edge of the next, `ink @ 0.55` at 1px on light paper (`ink @ 0.40` on dark) — the dumbbell's connector weight, because the carry is load-bearing and must clear 3:1, not the 0.25 axis hairline. Each carry declares the running total it transports in `data-carry`.
+- **Machine-readable data contract.** Every bar rect declares `data-role` (`total`, `delta`, or `subtotal`), `data-value` (totals unsigned, deltas explicitly signed `+`/`-`), and `data-name`. `scripts/verify-waterfall.py` reads these and fails the build when the drawing and the declaration disagree — see the honesty rules below.
+- **Sign is encoded by fill weight, not hue.** Increases take the bar family's default tint (`muted @ 0.15` fill, `muted` stroke). Decreases are hollow — paper fill, same `muted` stroke — so the two directions survive greyscale and colour-vision deficiency without leaning on the accent. The geometry (which end of the bar meets the carry) and the signed printed value are the second and third encodings of the same fact.
+- **Totals are the heaviest marks:** `ink @ 0.08` fill with a 1px `ink` stroke. The reader's eye should land on the two anchors first, then walk the bridges.
+- **Focal bridge (≤1, optional):** the one contribution the chart exists to show gets the bar family's focal treatment — `accent @ 0.12` fill, `accent` stroke, accent value label. It replaces that bar's sign fill; the signed label and geometry still carry the direction.
+- **Value labels:** `arrow-label` role 8px. Totals and increases print above the bar top (baseline `top − 8`); decreases print below the bar bottom (baseline `bottom + 12`), because the space above a decrease is where its carry arrives. Deltas print with an explicit sign (`+64`, `−38`); totals print unsigned.
+- **Gridlines / axes:** identical to the bar chart — 4–6 faint horizontal gridlines `ink @ 0.08` 0.8px, y-axis line and x-axis baseline `ink @ 0.25` 1px, tick labels `arrow-label` role 8px `muted` right-aligned at x=72, rotated y-axis title `eyebrow` role 7px tracked.
+- **Category labels:** centered under each bar at y=440, `node-name` role 11px 600 `ink`; the focal bar's label may take accent.
+- **Legend:** horizontal bottom strip after a hairline rule, one key per treatment used: total, increase, decrease, focal.
+
+### Waterfall element pattern
+
+```svg
+<!-- Start total: anchored at the baseline (y=420), value 240 on a 0–400 domain, k=0.95 px/unit -->
+<rect x="112" y="192" width="96" height="228" fill="{paper}"/>
+<rect x="112" y="192" width="96" height="228" fill="{ink @ 0.08}" stroke="{ink}" stroke-width="1"
+      data-role="total" data-value="240" data-name="FY25 base"/>
+<text x="160" y="184" fill="{muted}" font-size="8" font-family="{arrow-label}" text-anchor="middle">240</text>
+
+<!-- Carry: the running total (240) crosses the gap at its own level -->
+<line x1="208" y1="192" x2="256" y2="192" stroke="{ink @ 0.55}" stroke-width="1" data-carry="240"/>
+
+<!-- Increase bridge: +64 rises from 240 to 304 -->
+<rect x="256" y="131" width="96" height="61" fill="{paper}"/>
+<rect x="256" y="131" width="96" height="61" fill="{muted @ 0.15}" stroke="{muted}" stroke-width="1"
+      data-role="delta" data-value="+64" data-name="Headcount"/>
+<text x="304" y="123" fill="{muted}" font-size="8" font-family="{arrow-label}" text-anchor="middle">+64</text>
+```
+
+Endpoint positions round to the nearest integer pixel and never snap to the 4px grid — data coordinates are exempt, exactly as in the dumbbell. Bar x-positions and widths are layout, so they stay on the grid.
+
+## Anti-patterns
+
+- **A floating bar with no carry.** The connector is the claim that the total is conserved across the gap; without it the chart is bars at odd heights.
+- **Sign by hue alone** (green up / red down, or accent on every decrease). Hue is the one channel that does not survive greyscale or CVD; fill weight and geometry carry the sign here, and the accent stays editorial.
+- **A truncated value axis.** The domain follows the data's range, never its observed extremes — the same rule, cases, and all-zero fallback as the dumbbell (`type-bar.md` § Dumbbell honesty rules). A waterfall on a clipped domain inflates every bridge.
+- **More than one subtotal.** A walk that needs several resting points is two walks; split it.
+- **Mixing units mid-walk.** Every bar is in the start total's unit or the reconciliation is fiction.
+- **3-D, shadows, rounded bridge bars** — same editorial rules as every chart here.
+
+## Waterfall honesty rules
+
+- **Decimal declarations conserve exactly.** Fractional budgets use exact decimal arithmetic for totals, carries, and printed-value identity; geometry retains its pixel-rounding allowance. A binary floating point accumulation error must not reject a reconciled dollar-and-cent walk, and an actual decimal discrepancy is still a failure.
+- **The running total must conserve.** Start + every signed bridge = each subtotal and the end total, exactly — the declared `data-value`s must reconcile before geometry is even considered. A waterfall that doesn't add up is not approximately right, it is wrong.
+- **Bridges span exactly their two running levels.** Each bar's drawn top and bottom must sit where the shared scale puts the running totals before and after it (±0.75px for integer rounding). Stretching one bridge "for legibility" moves money that doesn't exist.
+- **Every carry sits at the level it transports,** spanning its full gap, and declares that value. A carry drawn at the wrong height reconnects the walk to a different total.
+- **Every bar prints its value, deltas with an explicit sign.** An unsigned bridge asks the reader to infer direction from geometry alone; print `+`/`−`.
+- **Zero bridges are dropped, never drawn.** A zero-height bar is invisible ink that still occupies a column; state it in prose or the source line instead.
+- **A degenerate start (zero or negative total) is a named failure,** not a silently rescaled chart — the scale is derived from the start anchor.
+
+These rules are executable: `scripts/verify-waterfall.py` reads each bar's declaration, recomputes the running totals, refits the shared scale from the start anchor, and fails on any conservation, geometry, carry, label, or sign-treatment drift. `scripts/test-verify-waterfall.py` proves both polarities — the shipped examples pass, and each mutation class above fails with a named finding.
+
+## Examples
+
+- `assets/example-waterfall.html` — minimal light
+- `assets/example-waterfall-dark.html` — minimal dark
+- `assets/example-waterfall-full.html` — full editorial

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

@@ -1,36 +1,36 @@
----
-name: scrum-meta
-description: 维护与演进 .agents/skills/ 下的敏捷 skill 体系本身。当用户要求修改 skill 规则、引入外部 skill（如 superpowers）、调整工作流纪律时使用。
----
-
-# scrum-meta：skill 体系自身的演进
-
-## 何时使用
-
-用户要求：改某个 skill 的规则/工作流、从外部 skill 合集（superpowers、openspec 等）吸收能力、新增或删除 skill 时。
-
-## 核心纪律（对 skill 文件本身也用敏捷的规矩）
-
-1. **先说清动机再动手**：改 skill 前用 1~2 轮对话确认要解决的问题是什么（brainstorming 同款：一次问一个问题）。没有真实痛点不动 skill，禁止为改而改。
-2. **修改必须最小且可追溯**：每个改动能回答「这解决什么问题」；改动后向用户复述改了哪些文件哪些节。
-3. **引入外部 skill 前先做映射判断**：
-   - 现有 skill（planning/sprint/tdd/report/meta）已覆盖的能力 → 不引入，说明理由即可
-   - 有增量价值且与「数据落库、状态机、TDD」纪律兼容 → 融入对应 skill 的相应小节（不新建文件），标注出处
-   - 需要独立工作流的才新建 skill 文件
-4. **skill 不膨胀**：每个 SKILL.md 控制在可一屏读完；超了就往 references/ 拆细节。
-5. **同步索引**：改动影响能力边界时，同步更新 `AGENTS.md` 的 skill 索引行和该 skill 的 frontmatter description。
-
-## 工作流
-
-1. 读当前各 skill + `AGENTS.md`，确认现状
-2. 与用户确认动机与落点（哪个 skill 哪一节 / 新建）
-3. 实施修改（局部编辑，禁止整文件重写）
-4. 若修改了敏捷数据规范（schema/状态机），运行 `node tools/validate.mjs` 确认未破坏
-5. 复述：改动清单 + 每项对应的动机 + 落索引情况
-
-## 反模式（禁止）
-
-- 不经确认大改 skill 工作流
-- 照抄外部 skill 全文（只吸收方法，用本项目语言重写，标注出处）
-- 新增 skill 却不更新 AGENTS.md 索引
-- 把 skill 改成与本体系冲突的纪律（如允许对话结论不落库）
+---
+name: scrum-meta
+description: 维护与演进 .agents/skills/ 下的敏捷 skill 体系本身。当用户要求修改 skill 规则、引入外部 skill（如 superpowers）、调整工作流纪律时使用。
+---
+
+# scrum-meta：skill 体系自身的演进
+
+## 何时使用
+
+用户要求：改某个 skill 的规则/工作流、从外部 skill 合集（superpowers、openspec 等）吸收能力、新增或删除 skill 时。
+
+## 核心纪律（对 skill 文件本身也用敏捷的规矩）
+
+1. **先说清动机再动手**：改 skill 前用 1~2 轮对话确认要解决的问题是什么（brainstorming 同款：一次问一个问题）。没有真实痛点不动 skill，禁止为改而改。
+2. **修改必须最小且可追溯**：每个改动能回答「这解决什么问题」；改动后向用户复述改了哪些文件哪些节。
+3. **引入外部 skill 前先做映射判断**：
+   - 现有 skill（planning/sprint/tdd/report/meta）已覆盖的能力 → 不引入，说明理由即可
+   - 有增量价值且与「数据落库、状态机、TDD」纪律兼容 → 融入对应 skill 的相应小节（不新建文件），标注出处
+   - 需要独立工作流的才新建 skill 文件
+4. **skill 不膨胀**：每个 SKILL.md 控制在可一屏读完；超了就往 references/ 拆细节。
+5. **同步索引**：改动影响能力边界时，同步更新 `AGENTS.md` 的 skill 索引行和该 skill 的 frontmatter description。
+
+## 工作流
+
+1. 读当前各 skill + `AGENTS.md`，确认现状
+2. 与用户确认动机与落点（哪个 skill 哪一节 / 新建）
+3. 实施修改（局部编辑，禁止整文件重写）
+4. 若修改了敏捷数据规范（schema/状态机），运行 `node tools/validate.mjs` 确认未破坏
+5. 复述：改动清单 + 每项对应的动机 + 落索引情况
+
+## 反模式（禁止）
+
+- 不经确认大改 skill 工作流
+- 照抄外部 skill 全文（只吸收方法，用本项目语言重写，标注出处）
+- 新增 skill 却不更新 AGENTS.md 索引
+- 把 skill 改成与本体系冲突的纪律（如允许对话结论不落库）

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

@@ -1,61 +1,61 @@
----
-name: scrum-planning
-description: 将用户与 AI 的需求对话约束为结构化敏捷数据（Epic/Story/Task），落库到 agile/ 目录。适用于需求澄清、故事编写、验收标准定义、任务拆解等规划场景。
----
-
-# scrum-planning：需求对话 → 结构化敏捷数据
-
-## 何时使用
-
-用户提出新需求、新功能、新改进，或要求澄清/拆解/评审已有需求时使用本 skill。
-
-## 核心纪律
-
-1. **禁止只聊天**。凡是确认要做的事，必须落成 `agile/backlog.json`（迭代/里程碑落 `agile/sprints.json`，日志落 `agile/journal.json`；schema 见 `references/schema.md`）。对话中的口头结论不算数，文件才算数。
-2. **禁止凭空拆解**。写 story 前先走「澄清」流程（见下节），澄清结果写进
-   `narrative` 和 `acceptance`，不许留在对话记录里。
-3. **数据是唯一事实来源**。后续实施只读文件不读对话记忆。AI 每次接手必须先读 `agile/` 下相关 JSON，再决定下一步。
-
-## 需求澄清（brainstorming，源自 superpowers）
-
-在写任何 story 之前执行，把模糊想法聊成清晰需求：
-
-1. **一次只问一个问题**，一次抛一堆问题等于没问。优先问影响验收的：这东西做完了怎么算成功？谁在用？边界在哪？
-2. **不替用户做主**：澄清中给出选项和各自的代价，让用户拍板；用户的原话是最高优先级输入。
-3. **至少考虑两条路**：写 story 前在内心比对过至少两种实现/拆解方案，被放弃的那条如果用户可能关心，用一句话带过取舍理由（可写进 narrative 或讨论中）。
-4. **适时收敛**：问题问清了就停，不许无限澄清；宁可拆成两个 story 也不做一个大而全的。
-5. **结论即时落库**：每澄清出一个结论，当场更新到对应 story JSON（`narrative`/`acceptance`/`points`），禁止聊完再统一补。
-
-## 工作流
-
-1. **定位层级**：判断这是 Epic（多迭代的大目标）还是 Story（一个迭代内可交付的用户价值）。拿不准就先建 Epic，Story 留空壳。
-2. **写 Story**：
-   - `narrative` 必须是「作为 X，我想要 Y，以便 Z」三段式
-   - `type`：`feature` / `bug` / `debt` / `spike`；`bug` 必须同时写 `bug` 三件套（severity / environment / steps），说不出复现步骤的就还不是 bug
-   - `priority`（P0~P3）+ `value`：`value / points` 就是 WSJF，用来回答「下一个迭代先做谁」
-   - `acceptance` 至少 1 条，用 given/when/then 格式，必须可验证；每条都要写 `verifyBy` 指向覆盖它的 task（否则验收只是口号）
-   - `points` 按斐波那契估（1/2/3/5/8），不确定就标 8 并在下次规划重估
-   - 有前置故事就写 `dependsOn`（不许成环）；当下被卡住就写 `blocked: { reason, since }`，不要只在对话里提
-3. **拆 Task**：每个 story 拆成 test/impl/refactor/chore 型任务：
-   - **test 型任务先行**：每条可自动验证的 acceptance 至少对应一个 test 型 task
-   - test 与 impl 分开拆，不许一个 task 既写测试又写实现
-   - 每个 task 在 `agile/journal.json` 的 `journals` 里占一条 `entries: []` 的空壳记录
-   - 故事若要在甘特图上显示计划排期，补 `schedule: { start, end }`（可选，不填就落「未排期」）
-4. **编号**：取当前最大编号 +1，`E-001` / `S-001` / `M-001` 格式，不复用已删除编号；迭代 id 另见 `references/schema.md` 的「迭代编号规则」。
-5. **落库后**：向用户复述 story id 与验收标准清单，运行 `node tools/validate.mjs` 确认通过。
-
-## 输出模板（对话中的回复结构）
-
-1. 一句话结论（做了什么、为什么）
-2. 新建/修改的文件清单
-3. 验收标准逐条列出请用户确认
-4. 校验结果
-
-## 反模式（禁止）
-
-- 只在对话里描述需求，不落文件
-- acceptance 写「功能正常」「体验良好」这类不可验证的空话
-- 把 test 和 impl 塞进同一个 task
-- 修改 story 时不更新 acceptance 却改了行为（验收标准必须与实现同步演进）
-- 只写 `priority` 不写 `value`（或反过来）—— 没有 WSJF 就没法回答「先做谁」
-- 用 narrative 描述依赖/阻塞，而不写 `dependsOn` / `blocked`（看板和甘特图读不到，等于没记）
+---
+name: scrum-planning
+description: 将用户与 AI 的需求对话约束为结构化敏捷数据（Epic/Story/Task），落库到 agile/ 目录。适用于需求澄清、故事编写、验收标准定义、任务拆解等规划场景。
+---
+
+# scrum-planning：需求对话 → 结构化敏捷数据
+
+## 何时使用
+
+用户提出新需求、新功能、新改进，或要求澄清/拆解/评审已有需求时使用本 skill。
+
+## 核心纪律
+
+1. **禁止只聊天**。凡是确认要做的事，必须落成 `agile/backlog.json`（迭代/里程碑落 `agile/sprints.json`，日志落 `agile/journal.json`；schema 见 `references/schema.md`）。对话中的口头结论不算数，文件才算数。
+2. **禁止凭空拆解**。写 story 前先走「澄清」流程（见下节），澄清结果写进
+   `narrative` 和 `acceptance`，不许留在对话记录里。
+3. **数据是唯一事实来源**。后续实施只读文件不读对话记忆。AI 每次接手必须先读 `agile/` 下相关 JSON，再决定下一步。
+
+## 需求澄清（brainstorming，源自 superpowers）
+
+在写任何 story 之前执行，把模糊想法聊成清晰需求：
+
+1. **一次只问一个问题**，一次抛一堆问题等于没问。优先问影响验收的：这东西做完了怎么算成功？谁在用？边界在哪？
+2. **不替用户做主**：澄清中给出选项和各自的代价，让用户拍板；用户的原话是最高优先级输入。
+3. **至少考虑两条路**：写 story 前在内心比对过至少两种实现/拆解方案，被放弃的那条如果用户可能关心，用一句话带过取舍理由（可写进 narrative 或讨论中）。
+4. **适时收敛**：问题问清了就停，不许无限澄清；宁可拆成两个 story 也不做一个大而全的。
+5. **结论即时落库**：每澄清出一个结论，当场更新到对应 story JSON（`narrative`/`acceptance`/`points`），禁止聊完再统一补。
+
+## 工作流
+
+1. **定位层级**：判断这是 Epic（多迭代的大目标）还是 Story（一个迭代内可交付的用户价值）。拿不准就先建 Epic，Story 留空壳。
+2. **写 Story**：
+   - `narrative` 必须是「作为 X，我想要 Y，以便 Z」三段式
+   - `type`：`feature` / `bug` / `debt` / `spike`；`bug` 必须同时写 `bug` 三件套（severity / environment / steps），说不出复现步骤的就还不是 bug
+   - `priority`（P0~P3）+ `value`：`value / points` 就是 WSJF，用来回答「下一个迭代先做谁」
+   - `acceptance` 至少 1 条，用 given/when/then 格式，必须可验证；每条都要写 `verifyBy` 指向覆盖它的 task（否则验收只是口号）
+   - `points` 按斐波那契估（1/2/3/5/8），不确定就标 8 并在下次规划重估
+   - 有前置故事就写 `dependsOn`（不许成环）；当下被卡住就写 `blocked: { reason, since }`，不要只在对话里提
+3. **拆 Task**：每个 story 拆成 test/impl/refactor/chore 型任务：
+   - **test 型任务先行**：每条可自动验证的 acceptance 至少对应一个 test 型 task
+   - test 与 impl 分开拆，不许一个 task 既写测试又写实现
+   - 每个 task 在 `agile/journal.json` 的 `journals` 里占一条 `entries: []` 的空壳记录
+   - 故事若要在甘特图上显示计划排期，补 `schedule: { start, end }`（可选，不填就落「未排期」）
+4. **编号**：取当前最大编号 +1，`E-001` / `S-001` / `M-001` 格式，不复用已删除编号；迭代 id 另见 `references/schema.md` 的「迭代编号规则」。
+5. **落库后**：向用户复述 story id 与验收标准清单，运行 `node tools/validate.mjs` 确认通过。
+
+## 输出模板（对话中的回复结构）
+
+1. 一句话结论（做了什么、为什么）
+2. 新建/修改的文件清单
+3. 验收标准逐条列出请用户确认
+4. 校验结果
+
+## 反模式（禁止）
+
+- 只在对话里描述需求，不落文件
+- acceptance 写「功能正常」「体验良好」这类不可验证的空话
+- 把 test 和 impl 塞进同一个 task
+- 修改 story 时不更新 acceptance 却改了行为（验收标准必须与实现同步演进）
+- 只写 `priority` 不写 `value`（或反过来）—— 没有 WSJF 就没法回答「先做谁」
+- 用 narrative 描述依赖/阻塞，而不写 `dependsOn` / `blocked`（看板和甘特图读不到，等于没记）