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-022PROC-026六条行为规则的确切语义、稳定路径与历史指针的落地方式以及仓库中校验脚本 validate_conformance_history.py 如何机械地保证这六条规则不被破坏。背景为什么需要稳定 Conformance 记录路径Potpie 采用基于 Git 的活规格治理模式见 ADR-0001spec/下的 Markdown 是行为契约的规范文本契约用整数修订号、稳定行为标识符、类型化溯源与显式变更记录来管理且明确区分契约成熟度、行为生命周期、实现声明、验证结果与派生新鲜度五条独立状态轴。在此框架下spec/conformance/目录保存实现与证据的验证结论。在 SPEC-CHANGE-0011 之前conformance 记录的存放存在三类痛点文件名携带日期旧记录形如context-engine-2026-08-24.md、cli-2026-08-21.md日期成为文件名的一部分历史版本会作为带日期的后继文件持续堆积在当前树中PR 专属记录分散跨模块的集成验证证据散落在 PR 专属或发布专属的额外文件中而不是收归于系统作用域记录身份定义模糊最终记录版本的不可变性缺乏精确界定——在哪一个 Git ref 上不可变不明确也没有规定后继版本如何指向紧邻的前一版本。该变更change_type: normative由user:dsantra发起、agent:codex编写、user:dsantra于2026-08-25T14:33:0005: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 的核心改动清单OperationFrom behaviorTo behaviorReasonclarifyPROC-011PROC-011把不可变性精确定义在记录的 Git ref上同时允许在同一稳定路径上发布后继版本add—PROC-022每个 conformance 作用域最多只能有一条当前稳定路径add—PROC-023要求后继记录通过扁平的previous_record_id、previous_record_ref、previous_record_path字段指向紧邻前一版本add—PROC-024跨模块集成证据必须记录在适用的系统记录中add—PROC-025定义预合并验证所钉住的 PR-head 与 base-commit 身份add—PROC-026定义非自指发布边界且不豁免实现或证据变更这六条操作的完整规范文本已落入 spec/process.md 的 Normative Requirements 区PROC-011、PROC-022PROC-026每条都带 authority [active]: user:dsantra溯源其中PROC-022PROC-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 hasha 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六个作用域的实际落盘变更记录中的评审表逐项说明了仓库内各工件的处理方式这也是理解本次变更落地范围的关键Artifact or behaviorRequired changeNo-change reason当前 conformance 记录六个作用域的最新记录迁到各自稳定路径并补充历史 Git 指针更早的记录 blob 在其既有 ref 上保持不变跨系统 conformance将已批准的 PR#1057head/base 与合成合并证据并入cross-system.md模块级行为证据仍保留在五个模块记录中Conformance 索引只列出六条稳定的当前记录并说明 Git 历史检索方式索引是派生导航而非验证权威SPEC-INDEX登记 SPEC-PROCESS 修订 2、本变更与稳定的 conformance 索引其他契约身份与依赖不变SPEC-GLOSSARY、产品/系统/模块契约、ADR-0001、既有最终版本无需变更存储与证据血缘不改变运行时义务旧版本在 commit012d3638f2eae62685ea2f711c9c7a7b0dfeae84与3e5edfd584aea53682720c3684e6fd78646fa1b3上仍可寻址这一评审的实际结果在仓库中可直接验证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:4505: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紧邻前一版本的稳定/历史记录 IDprevious_record_ref前一版本所在的完整 Git ref40 位 SHAprevious_record_path前一版本当时的仓库路径previous_record保留为null——因为旧的便携式校验器字段指向的工件有意不在当前树中解析详见 conformance 索引的 Update Convention。PROC-022同时禁止在当前conformance 文件名中编码日期、序号、实现版本或 PR 编号编号与日期只出现在历史 Git 对象里。索引中给出的迁移基线3e5edfd584aea53682720c3684e6fd78646fa1b3展示了血缘映射例如Current pathPrevious record IDPrevious path at baseline refcontext-engine.mdCONF-CONTEXT-ENGINE-2026-08-24-01spec/conformance/context-engine-2026-08-24.mddaemon.mdCONF-DAEMONspec/conformance/daemon.mdat604c3eb5c9a561eec959ab688c279d04e9e6ff5bcross-system.mdCONF-SYSTEM-2026-08-24-01spec/conformance/cross-system-2026-08-24.md历史检索遵循索引中给出的 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 中落地为完整的集成目标字段FieldPinned identityRepositorypotpie-ai/potpiePull requestPR#1057Base refmainBase commit20a8389cabec6e5924b1e3d4ef12d1dcfe900a3cPR head refrefactor/context-runtime-boundaryPR head commitecf37757561166f94a66a7375483cb48b6b5ef58Implementation commitecf37757561166f94a66a7375483cb48b6b5ef58Synthetic merge candidatee815363eae37fcf60ecf2ff0d8c7dddd8064d7e1Merge-candidate parents20a8389cabec6e5924b1e3d4ef12d1dcfe900a3c,ecf37757561166f94a66a7375483cb48b6b5ef58Merge-candidate tree203e2b7b17363ac562c74ae138b860517073ce5b关键点在于该记录只钉住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-022PROC-026转化为可执行的确定性断言文件集合精确匹配spec/conformance/下必须恰好是六个作用域文件加index.mdEXPECTED_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:0005: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 确立的治理模型可以浓缩为一句话稳定文件名是导航navigationGit 对象才是身份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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考