feat(infra): 交付分析——release 指标持久化 + 跨版本趋势 HTML 仪表盘

[pcliangx]

汇总 2026-07-15 brainstorming 会话里已成型的设计,待后续详细安排(用户明示 defer)。

背景 / Why

交付完成后 AGF 没有任何机制系统性量化工程交付:growth-analyst 只管产品/业务指标(北极星/OMTM/漏斗),observability.md 只管运行时 OTEL,retro 模板也无量化行。且 /agf-board 对 solo·inline 会话结构性空着(只读 ~/.claude/tasks,而 inline 工作不产生 native task——实测 72 个 session 目录 71 个空)。本 issue 把"交付分析"这一整块能力归档。

目标能力:交付分析(delivery analytics)

持久记录每轮 release 的工程交付指标 → 跨版本看趋势 → 生成自包含 HTML 仪表盘(复刻 agf-board.sh 本地 open 即读的手法)。

架构(三部件)

计算层 agf-release-metrics.sh ──▶ 持久层 release-metrics.jsonl ──▶ 视图层 agf-release-dashboard.sh
  算单轮 vX.Y.Z 指标              一行一 release,入 git(SSOT)      读 jsonl → 自包含趋势 HTML
  (git/gh + AGF 流水线解析)       retro 时 append                  (inline SVG,file:// 开,gitignore 可重建)
  输出①markdown 表贴 retro
  输出②--emit-json 追加 jsonl

指标集

有价值(推荐算): 交付清单(features/changes) · Bug 修复数 · Bug 新开/逃逸数 · AC 通过率 · 评审结论分布(approve/block/redo) · 返工次数(Redo) · UAT 结论 · cycle time · 成本/token(留白手填)

只当上下文、别当 KPI: 净代码增减(+/-行,虚荣指标) · commit/文件数 · 测试文件增量 · 按轨拆分 —— 纳入时须明确标注"上下文,非目标",以免激励灌水。

数据源:git · gh(type:bug issue 按 close 日期窗口) · progress/* 的 [x]/[ ] · docs/reviews/* verdict · docs/qa/* UAT verdict · docs/changes/archive/ · CHANGELOG。

拆分与建议顺序

阶段	交付	依赖
S0 计算层	agf-release-metrics.sh(先 git/gh,再补 progress/reviews/qa 解析)+ 单测 + 接入 retro §1/§2/§3	无
S1 持久层	--emit-json + docs/reviews/release-metrics.jsonl schema + retro append	S0
S2 视图层	agf-release-dashboard.sh 趋势 HTML + /agf-release-dashboard	S1(≥2 行才有趋势)
(并行) 看板扩展	plans/progress → kanban,复用 S0 的 progress/reviews/qa 解析器	蹭 S0

已定的设计决策

• 触发粒度 per release,并进 /agf-release-retro(指标归 retro §1 进度 / §2 质量 / §3 成本 / §4 流程)。
• release-metrics.jsonl 入 git = 趋势数据 SSOT;HTML 是可重建产物、gitignore(数据在 jsonl,视图随时重生)。
• 纯脚本零 LLM(git + gh + markdown 解析);图表设计走 dataviz skill(配色/可读性/sparkline)。
• 倾向开一个短 ADR记 jsonl schema 数据契约 + 视图可重建原则(对标 ADR-021 / ADR-024)。

相关待办(共用地基)

看板扩展(读 docs/superpowers/plans/* + progress/* → kanban,解决 solo 会话看板空)与本能力共用 progress/reviews/qa 解析层,建议同一条实施线先建解析器、两边消费。

待后续详细安排的开放项

• jsonl schema 字段最终定义;区间锚点边界(retro 时新 tag 未打 → 上一 tag..HEAD fallback)
• 图表选型:纯 bash inline SVG vs 最小内联 JS(均须 file:// 自包含无 CDN)
• 指标集最终裁定 + "上下文层"是否纳入
• 看板扩展与本能力是否合并为一条实施线

AC(验收)

• AC-1: agf-release-metrics.sh vX.Y.Z 输出推荐指标集的 markdown 表 + --emit-json,零 LLM、只读退出 0,有单测(注入 git 输出/fixture 断言,不依赖真实历史)
• AC-2: retro(skill + retro-_TEMPLATE.md)接入,指标各归 §1/§2/§3/§4;release-metrics.jsonl 每轮 append 一行且入 git
• AC-3: agf-release-dashboard.sh 读 jsonl 生成自包含趋势 HTML(file:// 可开、无 CDN、gitignore),≥2 轮数据时显示环比趋势(▲▼)
• AC-4: 短 ADR 记 jsonl schema + 视图可重建原则;CHANGELOG(MINOR)+ repo-layout.md 同步

Refs

• ADR-026 D7(看板为唯一任务视图——本能力丰富其数据面,不逆转)
• skill agf-running-release-retro + docs/reviews/retro-_TEMPLATE.md(接入点)
• growth-analyst(边界:产品/业务指标,不含工程交付度量——本能力填此空白)
• 设计来源:2026-07-15 brainstorming 会话

[pcliangx]

结论：defer（暂不做）

2026-07-19 分析会话裁定本 issue 暂不实施。

为什么 defer

1. 测不到东西 —— 模板仓无 app 代码、docs/changes/archive/ 空、docs/qa/ 仅模板；issue 想量的工程交付过程（cycle time / UAT / AC / bug 逃逸）还没发生过。68 个 git tag 全是模板自版本号，不是产品 release。
2. 不可验证 = 自打脸 —— AC-3 写明「≥2 轮数据时显示趋势」，当前合不进、验不了；而 v6.24.0 刚花大力气清零 written≠working（ADR-023/024）。把不可验证的度量代码合进「消灭 written≠working」的 repo 是结构性反讽。
3. kanban 空是真相源问题，不是渲染问题 —— /agf-board 对 solo·inline 空，是因为 inline 会话按设计不写 ~/.claude/tasks，换更花哨的解析器照样空。

根因已修（2026-07-19，v6.30.0 retro）

跑首份版本级 retro 时发现：模板把 docs/reviews/* 整个 gitignore 了（v6.24.x churn 策略），导致 retro 本身无法持久化、跨 release 学习链断裂——这正是本 issue「跨 release 数据缺失」的根因。已在 retro PR 加 .gitignore 例外 !docs/reviews/retro-v*-*.md 修掉（合并于 v6.30.0 retro）。所以「持久化跨 release 数据」的地基从 2026-07-19 起才真正存在。

重启触发条件（满足后可重开）

• docs/reviews/retro-v*.md 累计 ≥2 份（跨 release 趋势有数据可画）；且
• 首个真实产品 release 落档（docs/changes/archive/ 非空、docs/qa/ 有真 UAT 报告）——那时 cycle time / AC / UAT / bug 逃逸才有实数可量。

届时再评估：S0 计算层是否值得做，还是 retro 模板的量化占位行已够用。

同期落地（本 issue 的最小可行内核）

retro-_TEMPLATE.md §1/§2 加了量化占位行（cycle time / AC 通过率 / 返工次数 / UAT 结论 / bug 逃逸 / 膨胀指标）——首次真实 release 时数据形状近零成本自然捕获，无需先建仪表盘。这是「先捕获、后自动化」的 lean 落地，等触发条件到了再决定要不要上 S0-S2 全套。

---

（本评论钉死决策 + 触发条件，避免 issue 无人认领地悬着。v6.30.0 retro §5 的 AI-1 tag-orphan 门、AI-3 release-cut precheck 是相邻基础设施，已推进。）