Potpie 规格治理实践：SPEC-CHANGE-0011 如何稳定 Conformance 记录路径并构建 Git 历史血缘

Potpie 规格治理实践：SPEC-CHANGE-0011 如何稳定 Conformance 记录路径并构建 Git 历史血缘

【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie

导读

本文以 Potpie 仓库中已接受的规格变更记录 SPEC-CHANGE-0011 为线索，深入讲解 Potpie 如何把"一份 conformance 记录对应一个作用域、Git 历史充当版本仓库、跨模块集成证据收归于系统记录"这一套规范性规则固化进 规格流程契约。读完本文，你将掌握 SPEC-PROCESS 修订 2 中PROC-011与新增PROC-022～PROC-026六条行为规则的确切语义、稳定路径与历史指针的落地方式，以及仓库中校验脚本 validate_conformance_history.py 如何机械地保证这六条规则不被破坏。

背景：为什么需要稳定 Conformance 记录路径

Potpie 采用基于 Git 的"活规格"治理模式（见 ADR-0001）：spec/下的 Markdown 是行为契约的规范文本，契约用整数修订号、稳定行为标识符、类型化溯源与显式变更记录来管理，且明确区分契约成熟度、行为生命周期、实现声明、验证结果与派生新鲜度五条独立状态轴。

在此框架下，spec/conformance/目录保存实现与证据的验证结论。在 SPEC-CHANGE-0011 之前，conformance 记录的存放存在三类痛点：

1. 文件名携带日期：旧记录形如context-engine-2026-08-24.md、cli-2026-08-21.md，日期成为文件名的一部分，历史版本会作为"带日期的后继文件"持续堆积在当前树中；
2. PR 专属记录分散：跨模块的集成验证证据散落在 PR 专属或发布专属的额外文件中，而不是收归于系统作用域记录；
3. 身份定义模糊：最终记录版本的不可变性缺乏精确界定——"在哪一个 Git ref 上不可变"不明确，也没有规定后继版本如何指向紧邻的前一版本。

该变更（change_type: normative，由user:dsantra发起、agent:codex编写、user:dsantra于2026-08-25T14:33:00+05:30接受）将 Specification Process 从修订 1 推进到修订 2，从规范层面一次性解决了上述问题。

变更意图（Intent）：一条路径、一份当前记录、Git 历史即版本仓库

变更记录把意图表述得非常克制而明确：

• 每个模块或系统作用域只保留一份当前 conformance 文档；
• 用 Git 历史充当版本仓库（version store），历史版本通过 Git 对象寻址，而不是以带日期的文件继续留存在当前树中；
• PR/base 集成证据放入既有的跨系统记录（cross-system.md）；
• 避免在当前树中产生带日期的后继文件与独立的 PR 专属记录。

这一意图在 spec/conformance/index.md 的开头被复述为可执行的约定："The current tree contains one stable record path for each defined conformance scope. Git history stores prior record versions; dates, sequence numbers, implementation versions, and pull-request numbers are not encoded in current filenames."

行为操作（Behavior Operations）：一条澄清加五条新增

变更记录用一张操作表声明了对行为标识符的语义影响，这是 SPEC-PROCESS 修订 2 的核心改动清单：

这六条操作的完整规范文本已落入 spec/process.md 的 Normative Requirements 区（PROC-011、PROC-022～PROC-026），每条都带> authority [active]: user:dsantra溯源，其中PROC-022～PROC-026通过@ PROC-011、@ PROC-012等依赖边与既有规则建立显式引用关系。

语义差异（Semantic Diff）：追加式（append-only）模型与自指边界

修订 2 的核心思想是逻辑上的追加式模型：

• 一个最终记录版本在其 Git ref 上不可变（final record version is immutable at its Git ref）；
• 当验证发生变化时，稳定作用域路径前进到新的 Git 对象（the stable scope path advances to a new Git object）；
• 历史版本不再以带日期文件的形式留在当前树中；
• 系统记录成为跨模块 PR/base 集成证据的所有者，不再需要预测 GitHub 最终合并提交（eventual merge commit）。

PROC-011保留既有的不可变义务，但澄清了记录版本的精确身份 = 稳定 ID + 仓库路径 + Git ref，且不允许改写既有的 commit 或 blob。

修订 2 还解决了自指边界（self-reference boundary）：发布某条记录的 commit 无法包含自己的 commit hash（"a record cannot contain its own commit hash"），因此当中间 diff 仅限于 conformance、规格治理、派生索引或 conformance 校验器这几类工件时，后继 commit 可以指向已验证的前驱。但运行时实现、作用域内契约、测试或被引用的证据变更永远是重新验证的触发条件，不能伪装成"仅发布"（publication-only）而跳过验证——这正是PROC-026的完整语义。

兼容性、安全与失败影响：只影响规格存储，不动运行时

变更记录明确划定了影响边界：

This change affects specification storage and verification reconstruction only. It changes no product, Context Engine, Resource Manager, daemon, CLI, protocol, authorization, persistence, or failure behavior.

换句话说，这是一次纯粹的过程与存储层面的规范化：不改变任何产品行为、Context Engine、Resource Manager、daemon、CLI、协议、鉴权、持久化或失败行为；既有验证结论及其钉住的实现/规格身份保持原有强度不变。这一点也保证了下面的"Conformance Invalidation: None"——修订过程既不改变已接受的运行时行为，也不削弱任何既有实现或验证结论。

计算影响评审（Computed Impact Review）：六个作用域的实际落盘

变更记录中的评审表逐项说明了仓库内各工件的处理方式，这也是理解本次变更落地范围的关键：

这一评审的实际结果在仓库中可直接验证：spec/conformance/当前恰好包含七个 Markdown 文件——六个稳定记录（context-engine.md、potpie-resource-manager.md、daemon.md、cli.md、potpie-capabilities.md、cross-system.md）加一个index.md，没有任何带日期或 PR 编号的文件名。

稳定记录的字段契约与历史血缘（PROC-022 / PROC-023 落地）

以 spec/conformance/cli.md 为例，稳定记录的前置元数据（frontmatter）必须保持扁平（flat），且包含完整身份字段：

id: CONF-CLI title: Potpie CLI Conformance kind: conformance-record record_status: final spec_id: SPEC-CLI spec_revision: 1 spec_ref: 047cbe067c9c726e7e14f066675453372d8a8406 implementation_ref: ecf37757561166f94a66a7375483cb48b6b5ef58 performed_by: agent:codex performed_at: "2026-08-27T12:47:45+05:30" result: passed previous_record: null previous_record_id: CONF-CLI previous_record_ref: e05a4f1adb9d440552e576616c39d1df14990c2d previous_record_path: spec/conformance/cli.md

这里的字段设计精确对应PROC-023的要求：

• previous_record_id：紧邻前一版本的稳定/历史记录 ID；
• previous_record_ref：前一版本所在的完整 Git ref（40 位 SHA）；
• previous_record_path：前一版本当时的仓库路径；
• previous_record：保留为null——因为旧的便携式校验器字段指向的工件有意不在当前树中解析（详见 conformance 索引的 Update Convention）。

PROC-022同时禁止在当前conformance 文件名中编码日期、序号、实现版本或 PR 编号；编号与日期只出现在历史 Git 对象里。索引中给出的迁移基线3e5edfd584aea53682720c3684e6fd78646fa1b3展示了血缘映射，例如：

历史检索遵循索引中给出的 Git 命令模式（git show <ref>:<path>直接取回历史对象，git log --follow追踪稳定路径的演进）：

git show 3e5edfd584aea53682720c3684e6fd78646fa1b3:spec/conformance/cli-2026-08-24.md git show 012d3638f2eae62685ea2f711c9c7a7b0dfeae84:spec/conformance/cli-2026-08-21.md git log --follow -- spec/conformance/cli.md

跨系统集成证据：PR/base 身份的耐久性（PROC-024 / PROC-025 落地）

PROC-024要求跨模块验证证据记录在适用的系统作用域记录中，而不是创建 PR 专属或发布专属的 conformance 文件；PROC-025则定义了预合并验证的耐久身份。二者在 spec/conformance/cross-system.md 中落地为完整的集成目标字段：

关键点在于：该记录只钉住PR head 与 base commit 这对耐久预合并身份，合成合并候选（merge candidate）与合并树可作为支撑证据记录，但不预测、也不要求最终合并提交。记录同时明确自己不声称人类评审已批准或 PR 已合并——评审门禁是合并治理问题，而非 conformance 失败。

该记录的行为追踪覆盖SYS-001至SYS-023，可复现证据包括：钉住实现 ref 的完整行为 conformance（根测试1447 passed, 4 skipped, 1 deselected、独立 Context Engine1153 passed, 32 skipped、Rust 依赖的 premerge journey1 passed, 1451 deselected）、PR head 的实时检查（PR#1057open 且 mergeable、19 项检查全部成功），以及"advanced-base impact"验证——main从b45323127f81be40f07c44cab7f7581fda4a0ae7前进到钉住 base 仅涉及四个文档分发文件，potpie/、spec/、pyproject.toml、uv.lock均无 delta，合成合并树通过git diff --check与全部 91 个 Node docs-check 测试。

校验机制：validate_conformance_history.py 如何锁定新规则

规范文本之外，仓库提供了机械化校验脚本 scripts/validate_conformance_history.py，把PROC-022～PROC-026转化为可执行的确定性断言：

• 文件集合精确匹配：spec/conformance/下必须恰好是六个作用域文件加index.md（EXPECTED_FILES = {*SCOPES, "index.md"}），任何多余文件（如带日期的历史副本）都会导致校验失败；
• 作用域映射固定：SCOPES把六个文件名映射到稳定的记录 ID 与契约路径，如cli.md → CONF-CLI / SPEC-CLI / spec/modules/cli.md；
• 必需字段齐全：REQUIRED_FIELDS要求 15 个字段全部存在，且previous_record必须为null，历史指针只能走三个扁平的previous_record_*字段；
• 历史指针可解析：通过git show <previous_record_ref>:<previous_record_path>取回历史对象并核对previous_record_id，且spec_ref必须解析到maturity: accepted的契约、implementation_ref必须能git cat-file -e命中——这正是"历史版本不留在当前树中也能寻址"的机械证明；
• 行为追踪完整：记录正文的 Behavior Trace 表必须与契约中的[active]行为集合完全一致（validate_behavior_scope比对 traced 与 active，多一个少一个都报错）；
• 集成目标字段校验：cross-system.md必须携带 8 个target_*字段，且合成合并候选存在时其父提交必须恰为 base 与 PR head 两个、其树必须与target_merge_tree一致；
• 本地链接可解析：所有相对 Markdown 链接必须解析到仓库内存在的文件（validate_local_links）；
• 全局行为计数：六个作用域覆盖的活动行为总数必须恰为 195，索引必须链接每个当前记录。

该脚本的检查粒度与变更记录的 Validation 一节逐条对应，是"稳定路径 + 历史血缘 + PR/base 身份"三项义务的可执行投影。

更新约定：什么时候该发布后继记录

spec/conformance/index.md 的 Update Convention 给出了运维者最关心的判断标准：只有耐久验证身份发生变化时才更新稳定记录，包括：

• 接受的spec_id、spec_revision或spec_ref；
• 选定的implementation_ref；
• 作用域内行为或依赖；
• 可复现证据或聚合结论；
• 用作集成目标的 PR-head 与 base-commit 组合。

后继版本在同一稳定路径上替换当前内容，并通过previous_record_id/previous_record_ref/previous_record_path指向紧邻前一版本；前一个 Git 对象不被改动。如果没有任何耐久身份变化，就把例行结果留在 CI 中，而不是发布新的仓库记录。只有当一个已接受的契约定义了真正新的独立作用域时才新建 conformance 文件——PR、发布、日期或重复检查都不构成新作用域，跨模块集成始终留在cross-system.md。

这一约定与变更记录"Conformance Invalidation: None"相互印证：六条稳定记录保留了最新六项结论并链接到先前提交版本，新鲜度（freshness）始终从钉住的身份派生，而不是被写成索引或契约元数据里的状态值。

验证与接受：变更如何过关

变更记录的 Validation 一节列出了通过的全部校验门：

Structural: passed; validate_spec.py reported 0 warnings Semantic: passed; stable-path, lineage, integration-scope, and PR/base obligations are atomic and do not change runtime behavior Provenance: passed; all changed or added process behaviors carry active user authority Historical mutation: passed; revision advances 1 to 2, PROC-011 retains immutability, and PROC-022 through PROC-026 are unused new IDs Dependency/consistency: passed; six current scopes, indexes, historical refs, and accepted runtime contracts agree Fresh-agent reconstruction: passed; spec/index.md leads to the process, six stable records, module contracts, PR/base identity, and Git-history retrieval Independent conformance state: unchanged; six scopes cover 190 applicable active behaviors

注意 Validation 表格中的两个数字语境：变更接受时六个作用域覆盖 190 条适用活动行为（"Independent conformance state: unchanged"）；而后续 conformance 记录发布时（如 cross-system.md 的 SYS-E1 所记）行为总数演进为 195，校验脚本 validate_conformance_history.py 中的total_behaviors != 195断言与之对应——这体现了"记录随验证演进、规则保持稳定"的追加式模型。

最终，user:dsantra在2026-08-25T14:33:00+05:30接受本变更：接受动作绑定 Specification Process 修订 2，且不产生任何新的运行时实现声明（"makes no new runtime implementation claim"）。这一变更连同其余变更记录被登记在 spec/index.md 的 Change Record Registry 中（SPEC-CHANGE-0011 | SPEC-PROCESS | 1 → 2 | accepted）。

总结：稳定路径是可导航性，Git ref 才是身份

SPEC-CHANGE-0011 确立的治理模型可以浓缩为一句话：稳定文件名是导航（navigation），Git 对象才是身份（identity）。最终记录版本由其稳定记录 ID、仓库路径与 Git ref 三者共同界定，在任何 ref 上不可变；作用域路径随验证结果前进，历史版本通过 Git 历史寻址而不在当前树中堆积；跨模块集成证据收归于系统记录并以 PR-head/base-commit 为耐久身份，不预测合并提交；发布记录时无法自指，因而"仅发布"边界被严格限定在 conformance、规格治理、派生索引与校验器工件之内，任何契约、运行时、测试或证据变更都必须重新验证。

这套模型让"目标架构可以先于实现被接受"成为可能——ADR-0001 的初衷正是区分意图、实现与证据。对任何希望在 AI 原生 SDLC 中建立可审计、可重建验证血缘的工程团队而言，Potpie 这套"稳定路径 + Git 历史 + 扁平历史指针 + 机械校验"的组合，提供了一个可以整体借鉴、也可以拆解复用的治理样板。

【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie