Spec Kit constitution-sync Preset：恢复"物化式"宪法传播的可选方案与实现原理

在 Spec Kit 从"安装时固化产物"演进到"运行时解析（runtime resolution）"模型后，/constitution 命令不再自动把宪法条款传播到模板与命令文件中。constitution-sync 是一个**可选加入（opt-in）**的内置 preset，它为那些把模板视为"已评审、已提交工件"的团队恢复了两项旧行为：安装时带守卫的宪法物化，以及 /constitution 更新后的依赖工件同步。读完本文，你将理解该 preset 的完整工作机制、preset.yml 元数据、wrapped 命令的 5 步传播流程、源码中的 SHA-256 守卫实现，以及安装、验证、回退到默认模型的具体命令。

它解决什么问题

在 preset 模型出现之前，宪法（.specify/memory/constitution.md）的修改会由 /constitution 命令自动传播到 plan-template.md、spec-template.md、tasks-template.md、项目本地命令文件及指引文档中。当命令迁移到 preset 模型后，这一传播行为被有意移除：

• 传播会把宪法复制成多份"真相来源"，并与组合式解析栈（composition stack）相互冲突——物化后的编辑会在下一次重新组合时被遮蔽或覆盖；
• 默认的运行时模型以活动宪法为唯一真相来源：plan、tasks、analyze 每次运行时都会实时读取宪法，因此不存在"不同步"的问题。

constitution-sync 就是官方支持的"逃生舱口（supported escape hatch）"：它明知故犯地重新引入物化行为及其权衡，服务于直接评审物化工件的团队。对大多数项目，官方仍推荐默认的运行时解析模型，尤其是组织级治理场景——由核心团队维护版本化的组织 preset，一次性在多个仓库中推行，而不是在仓库间散落冻结副本。

工作机制：两件事

1. 安装时带守卫的宪法调和（guarded reconciliation）

该 preset 的存在本身会激活 core 中安装时的宪法调和逻辑。行为链条如下：

1. 安装 constitution-sync 时，物化当前解析出的 constitution-template 到 .specify/memory/constitution.md；
2. 之后 preset 栈的任何变化（安装、移除、启用、禁用、调整优先级）都会重新物化该模板，前提是活动文件仍与其记录的生成内容哈希匹配；
3. 一旦人工编辑过宪法，哈希不再匹配，自动替换即被禁用。

源码侧的实现在 presets 注册器：reconcile_constitution() 首先通过 self.registry.get("constitution-sync") 确认该 preset 已安装且 enabled，然后调用 _constitution_is_generated() 判断活动宪法是否为"未被修改的生成文件"，只有为真时才调用 _materialize_constitution_template() 覆写。

"是否为生成文件"的判定在 守卫函数 中：

• 优先读取 .specify/memory/.constitution-template.json 溯源边车文件（sidecar），校验其中 sha256 与当前文件内容的 SHA-256 一致；
• 对没有溯源边车的旧项目，只有当文件内容与内置 core constitution-template 完全一致时才视为生成文件。

物化逻辑本身（_materialize_constitution_template）：从解析栈收集 constitution-template 的全部层，若最高优先级层策略是 replace 则逐字节复制（返回 "copied"），否则通过 resolve_content 组合后写入（返回 "composed"），并同步写入含 sha256 与 source 字段的溯源文件。触发时机在 init 命令 中也有体现——在 preset 安装之后播种宪法，使 preset 提供的宪法模板能够通过解析栈生效。

2. /constitution 的 wrap 策略覆盖

该 preset 只提供一个 wrap 策略的 speckit.constitution 覆盖（见 preset.yml）：

provides:
  templates:
    - type: "command"
      name: "speckit.constitution"
      file: "commands/speckit.constitution.md"
      description: "Wrap /constitution to also propagate guidance into dependent templates and command files"
      strategy: "wrap"

wrap 策略意味着它叠加在 core 命令之上：wrapped 命令正文 首行就是 {CORE_TEMPLATE} 占位符，由注册流程替换为当前 core 命令体（替换逻辑见 _substitute_core_template）。这种设计保证 core 命令日后演进时本 preset 依然前向兼容，只在尾部追加一段传播（propagation）流程。

传播流程：/constitution 写完宪法之后的 5 步

wrapped 命令明确声明"本节对模板与命令传播取代上文 core 的 Scope Guard"——core 中"依赖模板与命令不在此处修改"的限制在此被有意解除，但"不实现功能、不生成应用代码"等其余约束仍然生效。随后执行：

1. plan-template.md：读取 .specify/templates/plan-template.md，检查 Constitution Check 与规则是否与新原则对齐。只有当团队打算将其作为已提交内容评审时，才把具体门禁文本物化进去；否则保留运行时指针 [Gates determined based on constitution file]，让 /plan 每次从活动宪法填充；
2. spec-template.md：核对范围与需求对齐——若宪法新增/移除了强制章节或约束则更新；
3. tasks-template.md：确保任务分类反映新增或移除的"原则驱动型"任务（如可观测性、版本管理、测试纪律）；
4. 已安装的 Spec Kit 命令文件：逐个检查 agent 命令文件（speckit.* 或 speckit-* 命名，skills 型集成为 speckit-<name>/SKILL.md，如 .github/agents/、.github/skills/、.claude/skills/），清除过时的 agent 专属命名引用。关键约束：只允许手工编辑项目本地、不受 preset/extension 管理的命令文件；凡是来自解析栈组合的文件都必须经栈重新生成，在原地编辑会在下次调和（specify integration use/switch、specify integration upgrade、preset/extension 安装或移除）时被覆盖；
5. 运行时指引文档：如 README.md、docs/quickstart.md 等，更新对已变更原则的引用。

最后，在 .specify/memory/constitution.md 顶部的 Sync Impact Report 中追加本次触碰的文件清单，格式为"模板更新状态（✅ updated / ⚠ pending）+ 文件路径"。

命令文件末尾还有一条硬边界：绝不直接编辑由 preset 或 extension 提供的模板与命令文件——它们归所属包所有，会在包更新或栈调和时被重新组合，手工编辑注定被覆盖。传播范围严格限定在项目自己的 .specify/templates/ 脚手架与未被 preset/extension 管理的命令文件。

明确的"不做什么"

边界同样重要，该 preset：

• 不改变未安装者的任何行为——默认运行时解析模型原样保留；
• 不禁用运行时解析——plan、tasks、analyze 每次运行仍读取活动宪法，本 preset 只是在其之上叠加物化副本，不取代真相来源；
• 不覆盖人工编写或编辑过的宪法——安装时调和只替换"溯源可证明是未修改生成文件"的内容；
• 不编辑受版本管理的包内文件——其他 preset/extension 提供或包装的模板、命令文件会从解析栈重新组合，本 preset 只写项目自身的 .specify/templates/ 与未受管命令文件。

适用场景与三条权衡

安装条件：只有当团队把物化模板与命令视为"已评审、已提交工件"时才装——例如 plan-template.md 的 Constitution Check 在 PR 评审中被当作"我们当前的门禁清单"阅读，并期望它跟随宪法更新。若依赖默认运行时模型，则不需要本 preset。

安装前必须理解的张力：preset 解析栈的理念是"模板与命令是分层、包所有、按需重新组合的工件，不是就地编辑的冻结文件"；而传播是相反思路——把指引物化进文件并冻结。具体权衡有三条：

1. 物化副本会漂移。任何被传播的内容都是快照；若修改宪法后未重跑 /constitution，副本即失去同步。默认运行时模型每次读活动宪法，天然无漂移。
2. 对组合文件的编辑活不过调和。如果你的 SDD 流程中 speckit.plan、speckit.specify、speckit.tasks、speckit.analyze、speckit.implement 等命令由 preset/extension 管理，它们会从栈重新计算——传播进其中的指引会在 specify integration use <key>/switch、specify integration upgrade 或任意 preset/extension 安装/移除时被覆盖。这解释了为什么本 preset 自我限制于项目本地文件：传播只在完全自有的工件上可靠。
3. 预填的 Constitution Check 可能给 /plan 引入锚定偏差。把具体门禁物化进 plan-template.md 会替换运行时指针，首次 /plan 可能锚定在冻结文本上。除非确实想要"已提交门禁"，否则保留指针。

结论：该 preset 适配"受治理模板与命令都是项目本地工件、且其余 SDD 流程使用纯 bundled core"的项目；若命令或模板来自其他 preset/extension，请优先选择默认运行时解析模型。

安装、验证与回退

版本前提

preset.yml 声明了硬性依赖：

requires:
  # Requires the runtime-resolution baseline (#3790, shipped in 0.14.4) where the
  # core /constitution command no longer propagates. Installing this preset on an
  # older core would double-apply propagation.
  speckit_version: ">=0.14.4"

即要求 Spec Kit >= 0.14.4——在该基线中 core /constitution 已不再传播，若在更旧的 core 上安装会导致传播被双重应用。

安装（内置 preset，无需下载）

# constitution-sync is a bundled preset — no download needed
specify preset add constitution-sync

本地开发与验证

# Test from local directory
specify preset add --dev ./presets/constitution-sync

# Verify the wrapped command resolves
specify preset resolve speckit.constitution

# Remove when done
specify preset remove constitution-sync

specify preset resolve speckit.constitution 用于确认 wrap 覆盖已生效，即解析出的命令体 = {CORE_TEMPLATE} 展开的 core 命令 + 追加的 "Constitution Template Sync" 传播段。

回退到默认模型

若要回到纯运行时解析：先把 .specify/templates/plan-template.md 中每个物化的 ## Constitution Check 小节重置为运行时指针——

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

[Gates determined based on constitution file]

（该指针与 core 模板 第 39 行起的默认结构一致），其余内容保持不动。然后执行 specify preset remove constitution-sync。更完整的说明见 升级文档。

小结

constitution-sync 是 Spec Kit 中一个典型的"知情权衡型" preset：它以 wrap 策略低成本扩展 core /constitution，用 SHA-256 溯源边车保证绝不覆盖人工宪法，把传播范围严格收缩到项目自有工件。理解它的关键，是理解它站在解析栈"组合-重算"模型的对立面，只在"物化工件即评审对象"的工作流中值得启用；否则，让活动宪法继续充当唯一真相来源，是更简洁也更抗漂移的默认选择。

参考路径：preset 元数据、wrapped 命令、安装时调和实现、哈希守卫、升级指南、core 宪法模板。