关联规范
背景
docs index 每次运行都会更新多个 catalog 的 generated_at,即使内容本身没有实质变化,也会造成工作树 churn。PR Flow / governance 改动中这会放大 diff、增加 pathref/governance 验证噪音,并让 review 更难聚焦真正变化。
产品解决方案
让 docs index 生成保持稳定:无内容变化时不改文件;只有 catalog 内容 hash 变化时才更新对应文件。时间戳不应成为每次运行都改动的主内容。
用户视角:运行 docs index 后,如果没有实际文档索引变化,工作树保持干净。
技术实现方案
- 为 docs catalog 生成增加内容规范化步骤,生成前剔除或稳定化
generated_at。
- 写文件前比较规范化内容 hash;无变化则不写文件。
- 如果必须保留生成时间,移到单独 metadata 文件,或只在内容 hash 变化时更新。
- 增加测试:连续运行 docs index 两次,第二次
git diff 为空。
- 确保 pathref/full governance 仍读取同一 catalog schema。
Acceptance criteria
Blocked by
None - can start immediately
关联规范
背景
docs index每次运行都会更新多个 catalog 的generated_at,即使内容本身没有实质变化,也会造成工作树 churn。PR Flow / governance 改动中这会放大 diff、增加 pathref/governance 验证噪音,并让 review 更难聚焦真正变化。产品解决方案
让 docs index 生成保持稳定:无内容变化时不改文件;只有 catalog 内容 hash 变化时才更新对应文件。时间戳不应成为每次运行都改动的主内容。
用户视角:运行 docs index 后,如果没有实际文档索引变化,工作树保持干净。
技术实现方案
generated_at。git diff为空。Acceptance criteria
Blocked by
None - can start immediately