Potpie 规范过程（Specification Process）：基于 Git 的行为契约治理与一致性验证机制

Potpie 规范过程Specification Process基于 Git 的行为契约治理与一致性验证机制【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie导读本文讲解 Potpie 仓库中spec/process.md定义的一套规范过程契约Specification Process契约 IDSPEC-PROCESS当前 revision 2它规定了项目如何提出、接受、修订并验证自身的行为契约behavioral contract。这套过程把期望行为spec、架构决策ADR、实现code与一致性证据conformance record四者彻底分离并借助 Git 不可变历史实现可追溯、可重建的契约生命周期管理。读完本文你将掌握 Potpie 规范体系的五个独立状态轴、26 条规范性要求PROC-001 ~ PROC-026、变更记录SPEC-CHANGE-与一致性记录CONF-的协作方式以及仓库中对应的自动化验证脚本如何强制这些规则。为什么需要一套规范过程Potpie 的 Context Engine、Resource Manager、daemon 与 CLI 边界正处于迁移期。迁移面临的真实问题是目标架构必须在实现尚未完全就绪之前就可以被绑定binding。非正式的架构文档无法区分期望行为与当前实现快照通过测试也只能说明代码在某个 ref 上做了什么无法回答谁授权了这条行为承诺。为此ADR-0001Git-Based Living Specifications With Explicit Acceptance 作出决策spec/目录下的 Markdown 是规范的行为契约canonical contract契约使用整数修订号revision、稳定行为标识符、带类型的溯源信息typed provenance、显式变更记录与具名验收权威named acceptance authority契约成熟度、行为生命周期、实现声明、验证结果、派生新鲜度保持为相互独立的状态轴ADR 解释为什么存在该契约实现代码说明软件在选定 ref 上的行为一致性记录则保存带固定引用的声明与证据。仓库中spec/目录本身即为这套契约的实例process.md本契约、glossary.md术语契约、product.md产品契约、system.md系统契约、modules/下五个模块契约、decisions/ 下 12 个 ADR、changes/ 下 12 条变更记录以及 conformance/ 下的一致性记录。验收权威谁有权让契约生效规范过程的首要问题是权威来源。对最初的 revision-1 契约集合验收权威是user:dsantrateam:potpie作为文档所有者维护文档但仅凭所有权不获得验收权威agent:codex可以撰写提案并执行验证但同样不因此获得验收权威对验收权威本身的更改必须通过该契约的新验收修订来表示见 process.md 的 Acceptance Authority 一节。这直接对应规范性要求PROC-003只有被已接受的规范过程指名为验收权威的参与者才被允许绑定一个契约修订PROC-004作者身份、实现工作、测试结果、工具输出与 agent 断言均不得视为契约验收。也就是说代码合入了测试全绿Agent 写了这份文档都不能替代user:dsantra的显式验收。这一点在 SPEC-CHANGE-0001 的 Validation 一节有直接体现即使实现特征化测试11 个通过验收时仍明确标注Implementation conformance: unclaimed、Verification conformance: unverified。五个独立状态轴规范过程把一份契约处于什么状态拆成五个互不混淆的维度每个维度回答不同的问题状态轴回答的问题契约成熟度Contract maturity这一精确的契约修订是否具有约束力行为生命周期Behavior lifecycle该行为当前是否施加义务实现声明Implementation claim一个实现声称覆盖了什么验证结果Verification result已记录的证据确立了什么派生新鲜度Derived freshness已记录证据能否确立当前状态对应PROC-001这五个状态轴必须始终保持独立。设计意图见 process.md 的 Rationale 一节是在迁移完成之前就能接受目标架构而无需把未完成的代码伪装成合规。契约成熟度描述契约文本是 draft、proposed、accepted 还是 retired行为生命周期描述单个行为是 active、deprecated 还是 retired实现声明与验证结果按行为逐条记录在一致性记录中新鲜度由固定引用的身份 证据与当前选定的 ref 对比派生而来而不是被手工写进索引或契约元数据。规范性要求总览PROC-001 ~ PROC-026本契约 revision 2 包含 26 条规范性要求每条都带有活跃的权威溯源 authority [active]: user:dsantra与决策溯源 decision [active]: decision:ADR-0001。按职责可以归为六组1. 状态模型与修订纪律PROC-001、PROC-002PROC-001五个状态轴必须独立PROC-002对已接受契约的每一次编辑都必须分配下一个正整数修订号——包括编辑性修改ADR-0001 的 Consequences 明确列出Later edits create a new revision and change record, including editorial edits。2. 权威与验收PROC-003、PROC-004、PROC-009、PROC-021PROC-003只有具名验收权威能绑定契约修订PROC-004作者/实现/测试/工具输出/agent 断言不得视为验收PROC-009代码、测试、事故记录、文档与运行时观测不得在缺少已接受契约修订的情况下覆盖已接受行为PROC-021验收记录必须标识被接受的修订、匹配的变更记录、被授权的验收者与验收时间。3. 一致性记录与不可变性PROC-005、PROC-011、PROC-012、PROC-022 ~ PROC-026PROC-005实现声明与验证结果只能记录在一致性记录中PROC-011由稳定记录 ID 仓库路径 Git ref 共同标识的最终一致性记录版本在该 ref 上不可变在同一稳定路径发布后继版本必须创建新的 Git 对象不得改动先前版本PROC-012一致性记录必须固定pin其所评估的精确规范修订与 ref、以及精确实现 refPROC-022每个已定义的一致性范围scope在稳定的、以范围命名的路径上至多有一份当前记录日期、序号、实现版本、PR 号不得编码进当前一致性文件名PROC-023后继一致性记录必须通过扁平的previous_record_id、previous_record_ref、previous_record_path三个字段标识紧邻的前一记录版本且该历史目标必须可解析——不要求前一文件仍存在于当前树中PROC-024跨多个模块范围的验证证据必须记录在适用的系统范围一致性记录中而不是额外的 PR 专属或发布专属一致性文件中PROC-025合并前集成验证必须固定仓库、PR 号、PR head 提交、目标 base ref 与提交、已接受的规范身份与实现 ref不允许要求预测的最终合并提交作为验证身份PROC-026只发布一致性、规范治理、派生索引或一致性验证产物的后继提交可以指向其已验证的前驱因为记录无法包含自身提交哈希但只要范围内契约、运行时实现、测试或被引用的验证证据有任何变更就必须重新验证而不能归类为仅发布。4. 变更记录与可追溯性PROC-007、PROC-010、PROC-013、PROC-014、PROC-019、PROC-020PROC-007每个已接受的契约修订必须能通过 Git 历史寻址PROC-010对已接受契约的每次编辑都必须有匹配的已接受变更记录PROC-013 / PROC-014已接受的变更记录与已接受修订的溯源谱系必须能通过 Git 历史寻址PROC-019每个语义契约变更必须为每个受影响的行为标识符声明一个操作add / clarify / replace / split / merge / deprecate / retirePROC-020契约修订不得静默重新利用既有行为标识符silently repurpose。5. 行为标识符与废弃PROC-015、PROC-016PROC-015每个已退休的行为标识符必须能通过 Git 历史寻址作为 lineage tombstonePROC-016已退休的行为标识符不得用于不同的语义而被复用。6. 初始修订与审查PROC-006、PROC-008、PROC-017、PROC-018PROC-006契约修订在验收前必须通过适用的结构、语义、溯源、依赖一致性、历史变更与新鲜 Agent 重建fresh-agent reconstruction审查PROC-008已接受的 active 或 deprecated 行为不得包含未解决的 question 边unresolved question edgePROC-017已接受的 active 或 deprecated 行为不得包含显式 assumption 边PROC-018初始契约必须从 revision 1 开始并伴随一条从 revision 0 提出的变更记录。仓库 spec/index.md 的契约注册表确认SPEC-PROCESSrevision 2 为 accepted共 26 个行为整个目录共 240 个已接受的 active 行为节点。提案与变更修订如何前进规范过程定义了明确的修订前进路径初始契约从 revision 1 开始伴随一条从 revision 0 提出的变更记录PROC-018行为变更mutation从固定前一已接受修订与 Git ref 开始分配下一个整数修订并为每个语义变更声明行为操作PROC-002、PROC-019行为标识符保持稳定语义变化使用 replace、split 或 merge 操作并保留 tombstone而不是静默复用既有标识符PROC-020反向影响reverse impact从规范化的前向依赖、溯源、questions 与仓库引用派生而不是手工维护的反向列表避免行为分裂后留下过期的反向清单——这正是 ADR-0001 中Affected Behavior IDs 由 decision:ADR-0001边派生、不在 ADR 中复制的原因。以仓库中的真实案例说明SPEC-CHANGE-0001初始化本契约0 → 1一次性 add 了 PROC-001 ~ PROC-021 共 21 条行为SPEC-CHANGE-0011稳定一致性记录路径1 → 2是 PROC-011 的 clarify PROC-022 ~ PROC-026 的 add。其 Behavior Operations 表格展示了每条操作的类型clarify/add、From/To 行为与理由。审查与验收流程审查环节刻意区分三类角色作者author、验收权威acceptance authority、一致性执行者conformance performer。验收记录PROC-021标识精确修订、匹配变更记录、被授权验收者与验收时间随后产生的 Git commit 或不可变 blob 完成已接受修订身份PROC-007。值得注意的设计细节process.md 中编写 commit 1 时使用的章节级协作流程只是该提交的操作性控制不是后续仓库工作的永久验收要求——避免把一次性的协作约定误固化为常设契约义务。验收前置检查Acceptance Criteria包括PROC-001 ~ PROC-026 结构有效且携带活跃权威契约与SPEC-CHANGE-0011标识同一次转变ADR-0001 解释的决策不引入这些行为节点之外的额外行为结构、语义、溯源、一致性与重建审查无阻塞性发现实现与验证在一致性记录存在之前保持未声明、未验证的独立状态当前一致性树每个已定义范围恰好一个稳定文件每个后继都能解析其历史指针跨系统集成证据不需要单独的 PR 专属记录。一致性记录与新鲜度证据如何固定与前进稳定的范围路径 Git 历史作版本库一致性记录conformance record固定以下内容已接受的规范修订与 ref、实现 ref、行为范围、声明、验证结果、证据、执行者与时间。每个范围只有一个当前稳定路径。新的验证结果在该路径发布后继版本并通过previous_record_id、previous_record_ref、previous_record_path三个扁平字段指向前一记录的完整 Git ref 与历史路径。前一 Git 对象保持不可变的最终记录稳定文件名只是导航到当前记录而不是记录的版本身份PROC-011、PROC-022、PROC-023。以 conformance/index.md 展示的六个范围为例范围当前稳定记录规范修订行为数结果Context Enginespec/conformance/context-engine.md134passedPotpie Resource Managerspec/conformance/potpie-resource-manager.md237passedDaemonspec/conformance/daemon.md256passedCLIspec/conformance/cli.md133passedPotpie Capabilitiesspec/conformance/potpie-capabilities.md112passed跨系统spec/conformance/cross-system.md123passed历史版本不在当前树中保留带日期的重复文件而是通过 Git 取回例如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 集成身份系统范围记录cross-system.md拥有跨模块边界的证据PROC-024。以 cross-system.md 为例它对 PR#1057固定了仓库、PR 号与 head、目标 base ref 与提交、已接受规范 refs 与实现 ref。合成合并候选synthetic merge candidatee815363e...及其合并树可记录为支撑证据但不预测、也不要求最终合并提交PROC-025。发布边界记录无法自引用发布一致性记录的提交无法固定自身一个记录不能包含自己的提交哈希。因此PROC-026允许仅包含一致性、规范治理、派生索引或一致性验证产物的后继提交指向其已验证前驱而范围内契约、运行时、测试或被引证据的变更都必须产生稳定路径上的新验证结果。cross-system.md明确指出当前一致性发布提交是PROC-026下的 documentation-only 后继且不声明人工评审已批准或 PR 已合并。新鲜度派生而非存储新鲜度freshness由固定引用的身份、依赖与可用证据计算而来绝不作为索引或契约状态人工维护process.md 与 conformance/index.md 均强调。失败与过期回答不同的问题失败记录选定 refs 上的矛盾过期意味着先前的证据不再确立当前状态。当以下任一持久身份变化时才更新稳定记录见 conformance/index.md 的 Update Convention已接受的spec_id/spec_revision/spec_ref选定的implementation_ref范围内行为或依赖可复现证据或汇总结论用作集成目标的 PR-head 与 base-commit 对。若这些持久身份都没变常规结果留在 CI 即可不必发布新的仓库记录。只有已接受契约定义了真正新的独立范围时才允许新建一致性文件PR、发布、日期或重复检查都不会创建新范围。保留与历史tombstone 与不可变 ref保留策略Retention由 Git 历史承载已接受的修订与变更记录通过 Git 历史保留PROC-007、PROC-013已退休行为标识符作为谱系墓碑lineage tombstones保留且不复用PROC-015、PROC-016源码与一致性记录的各版本在其不可变 ref 上保持可寻址——即使稳定当前路径前进了、或者旧的带日期路径已不在当前树中PROC-011、PROC-023。仓库中的自动化验证支撑规范过程不只是纸面约定仓库提供确定性验证脚本强制这些规则。核心是 scripts/validate_conformance_history.py它逐一执行文件集合检查spec/conformance/目录必须恰好包含 6 个范围记录 index.mdEXPECTED_FILES杜绝多余的 PR/发布/日期专属文件混入当前树frontmatter 检查每个记录必须携带id、record_status: final、spec_id、spec_revision、spec_ref、implementation_ref、previous_record_id、previous_record_ref、previous_record_path等必需字段且旧式previous_record字段必须为null因为前驱产物有意不在当前树中解析SHA 完整性spec_ref、implementation_ref、previous_record_ref必须是完整 40 位 Git SHA并通过git cat-file -e验证对象存在契约解析从spec_ref解析出对应范围的契约文件校验其id、revision与maturity: accepted与记录声明一致行为迹核对记录正文## Behavior Trace中的行为 ID 集合必须与契约中的 active 行为集合完全一致缺失/多余都会报错历史指针解析previous_record_ref:previous_record_path必须能解析出前一记录且其id与previous_record_id匹配跨系统目标校验target_base_commit、target_pr_head_commit、target_merge_candidate、target_merge_tree必须存在若合并候选对象存在其父提交必须恰好为[base_commit, pr_head]其树必须等于target_merge_tree聚合校验六条记录覆盖的行为总数必须等于195spec/conformance/index.md中所有195个当前行为与此一致而spec/index.md的 240 为全目录契约行为总数二者口径不同195 是已由一致性记录覆盖的行为数链接校验所有本地 Markdown 链接必须解析到仓库内的真实文件。脚本成功输出为conformance validation passed: 6 stable records, 195 behaviors, history resolved。这正是 SPEC-CHANGE-0011 与 cross-system.md 中structural spec validation with zero warnings对应的自动化实现你也可以把它视为PROC-006结构性审查与 PROC-022 ~ PROC-026稳定路径与历史指针的可执行落地。阅读路径与进一步探索如果你要在仓库中继续深入这套机制推荐顺序即 spec/index.md 的 Read Orderspec/process.md本契约SPEC-PROCESS revision 2spec/glossary.md术语契约SPEC-GLOSSARY revision 1spec/product.md 与 spec/system.mdspec/modules/potpie-capabilities.md、spec/modules/context-engine.md、spec/modules/potpie-resource-manager.md、spec/modules/daemon.md、spec/modules/cli.mdspec/decisions/ADR-0001-spec-governance.md 等决策记录以及 spec/questions/open.md当前 4 个有意推迟的问题均无已接受 active 行为依赖spec/conformance/index.md 与 spec/conformance/cross-system.md验证脚本 scripts/validate_conformance_history.py小结Potpie 的规范过程是一套面向 AI 原生 SDLC的治理试验当代码尚未合入、Agent 可以起草提案、测试可以运行但尚未被验收时spec/中的契约文本借助整数修订、稳定行为标识符、显式变更记录、具名验收权威与不可变 Git 引用回答了哪一版行为承诺当前有约束力、由谁授权、证据在哪、证据是否仍然新鲜这四个问题。五个状态轴分离PROC-001、每次编辑都必须升修订并匹配变更记录PROC-002/010、一致性记录按范围在稳定路径上发布不可变后继PROC-011/022/023、跨模块证据归属系统记录PROC-024、合并前验证固定 PR-head 而非预测合并提交PROC-025/026——这些规则共同构成了一个先接受目标、后逐步迁移实现且全程可审计的契约生命周期。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考