walden-history

Walden 历史

使用此技能讲述 Walden 仓库的过往：某项功能如何演进、产品组合讲述了怎样的故事、每次批准后发生了多少返工，以及如何妥善退役已被取代的规范。walden 技能负责起草并执行当前工作；此技能负责回顾过往。尽可能使用用户偏好的语言回复。

何时使用

• 用户询问某项功能如何演进——其时间线、编年史或契约历史
• 用户询问产品的故事：各个阶段、取代关系、仍在推进与已退役的工作
• 用户询问批准后发生了多少返工，或想分析变更情况
• 用户决定退役已被取代的规范

前置条件

一个包含已提交 .walden/ 文档的 Git 仓库。walden CLI 可选，仅用于交叉核对当前状态：以下所有还原工作都只需 Git 即可完成。若仓库将 .walden/ 列入 Git 忽略规则，则没有规范历史可供梳理——请直言说明，不要凭空捏造。

溯源规则

每条历史陈述必须且只能带有以下两个标签之一；标签不是装饰，而是陈述的证据类别：

• [sealed]——对指定提交中记录的值进行字符串比较。在该提交中，若 design.source_requirements_fingerprint 等于 requirements.approved_fingerprint，tasks.source_design_fingerprint 等于 design.approved_fingerprint，且证据记录中的链字段等于其所指的文档封存值，则链条一致。若某次提交中的封存值不一致，则属于发现的问题——必须明确报告，绝不可掩饰。
• [inferred]——提交消息、署名、时间因果关系，以及所有“因为”。推断是合理叙述；未标注的推断则是臆造。

四条硬性规则：

1. 使用 git show <sha>:<path> 获取历史内容——绝不可依靠回忆。如果你在本次对话中没有运行该命令，就不知道文档写了什么。
2. 每条历史主张都必须以其所依据的提交标识符为锚点。没有 sha 的主张不算主张，只是印象。
3. 内容核验属于内核范畴：你可以相互比较记录的指纹；从正文重新计算指纹则需要遵循 walden CLI 的规范化规则。若用户要求核验内容与封存值是否一致，请如实说明这一点，并建议检出该提交后运行 walden validate。
4. Git 署名只是来源的代理信息：请写“由……提交”，绝不可写“由……批准”。Walden 目前尚未记录批准者身份，编年史不得捏造。

配方：功能编年史

重建单个功能的时间线。按文档（requirements.md、design.md、tasks.md）分别处理，按时间从早到晚：

# Revision list for one document (oldest first)
git log --follow --reverse --format='%h|%aI|%an|%s' -- .walden/specs/<feature>/requirements.md

# Frontmatter as of one revision (flat key: value — trivially parseable)
git show <sha>:.walden/specs/<feature>/requirements.md | sed -n '2,/^---$/p'

根据连续修订之间的 frontmatter 变更，使用事件推导表得出事件——绝不可仅凭提交消息推断：

连续修订之间观察到的变更	事件
status: draft → in-review	开始评审
status: in-review → approved，且设置了 approved_at	批准
status: approved → draft，且指纹已清除	调整
出现 approved_fingerprint，状态仍为 approved	封存（补录采用记录）
已批准文档中的 source_*_fingerprint 出现或发生变更	链修复
正文发生变更，且出现新的 approved_fingerprint 和 approved_at	重新批准周期
出现 walden_schema_version	格式迁移标记

然后以相同方式读取证据台账自身的历史：

git log --reverse --format='%h|%aI' -- .walden/evidence/<feature>.json
git show <sha>:.walden/evidence/<feature>.json

记录首次出现即为初次证明；result 变更是验证历史；不同修订之间的 profile 差异则是值得叙述的环境变化。最后查询退役记录：如果该功能在 .walden/RETIRED.md 中有条目，报告退役提交、记录的原因以及取代它的功能。

输出：一张按时间顺序排列的表格——每个事件一行，列为提交、日期、事件和标签（[sealed]/[inferred]）——后接叙述；叙述可以进行解读，但必须引用表格中的行。

配方：产品故事

项目组合的发展历程。本配方有严格的范围规则：审视整个项目组合时，只读取退役索引和 git log 元数据——绝不可深入重建每个功能。深入分析应针对指定功能，通过功能编年史完成。

# First appearance of each feature (creation event)
git log --reverse --format='%h %aI' -- .walden/specs/<feature> | head -1

# All feature directories ever deleted (retirement candidates for the integrity check)
git log --diff-filter=D --format= --name-only -- '.walden/specs/*/requirements.md' | sort -u

汇总：按创建日期将功能归入不同代；.walden/RETIRED.md 条目通过明确的取代关系为各代画上句号；普查结果（现存／已退役／进行中）构成故事的现在时态。按取代链分组，而非仅按日期分组——日期只能提示 [inferred]，索引条目则按惯例明确记录为 [sealed by convention]。

配方：返工报告

返工分析的原始素材：每份文档在获批后发生了什么。

1. 执行功能编年史的批准事件提取，获取每份文档的批准事件。
2. 将历史拆分为各次批准之间的片段；针对每个片段总结变更：

git diff <approvalShaA>..<approvalShaB> -- .walden/specs/<feature>/<doc>

3. 将调整事件（approved → draft）单独报告，与草稿阶段的内容演变分开——调整是重新打开契约；草稿反复修改则属于创作过程。
4. 最后给出指标区块，先列数字，再写叙述：

rework metrics — <feature>
  re-approval cycles: requirements=N design=N tasks=N
  reconciliations: N
  first approval → last recorded change: N days

退役仪式

此技能唯一的写入路径。已被取代的规范会被删除——历史留存在 git 中——并记录在退役索引里，因此门禁只评判现存的项目组合，而叙述仍保留其篇章。

前置条件：用户已在当前对话中指定要退役的功能及其取代关系。向用户确认准确的清单和后继功能，并等待明确批准——绝不可将沉默或更早的随口一提视为同意。

步骤，合并为一次提交：

git rm -r .walden/specs/<feature>            # per retired feature
# append one index entry per feature to .walden/RETIRED.md (create it on first use)
git add .walden/RETIRED.md
git commit -m "chore: retire <scope> (superseded by <successor>)"

绝不推送。提交后，建议运行 walden validate——现存项目组合此时就是整个项目组合。

退役索引约定

.walden/RETIRED.md 与 constitution.md 和 lessons.md 放在一起，位于 specs/ 之外，因此任何 walden 命令都不会评判它。每个已退役功能占一行——既能用单一模式解析，也能直接阅读：

# Retired Specifications

History lives in git: `git show <retirement-commit>^:.walden/specs/<name>/requirements.md`
restores any document exactly as sealed.

- <feature-name> — retired <short-sha> — superseded by <feature-or-era> — <reason>

完整性检查

索引必须与 git 历史一致。报告所有不匹配项：

• 索引中存在条目，但对应的规范目录仍然存在——已记录退役，但尚未执行。
• 已删除的功能（来自 --diff-filter=D 列表）没有索引条目——未记录的退役；提议使用删除提交补录索引行。
• 索引行格式错误——指出行号。

输出规范

• 时间线采用表格形式，每行一个提交锚点，标签内联；表格后附叙述，并引用对应行。
• 正文中使用短 SHA，命令中使用完整路径。
• 历史记录缺失时（压缩合并、浅克隆、被 git 忽略的 .walden/），说明丢失了什么，并且只叙述 git 保留的内容——绝不推测。
• 每份返工报告都要先列出数字，再进行叙述。