尧图网站建设 
oh-my-claudecode 的 Ralph PRD 验收标准修正机制基于证据保留的证据型 Criterion Amendment【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode导读oh-my-claudecode 的 Ralph 循环一种 PRD 驱动的持续执行循环将验收标准视为完成判定的权威只有所有活动验收标准都通过、并经过 reviewer 验证的故事才允许推进。但当实现过程中测量结果与派发时的简报不一致时例如简报声称存在 16 个 setter实测只有 12 个既不能靠模型静默改写验收标准也不能放任一条已被证伪的标准继续卡死整个循环。本篇文章围绕 ADR 03664 展开深入讲解 Ralph 引入的**证据保留型验收标准修正criterion amendment**机制——从criterionAmendments账本的数据结构、amendCriterion/supersedeCriterion两个编程接口、fail-closed 的读取校验到它在循环、reviewer 提示词与持续对话提示中的完整传导。读完你将掌握在测量胜过计划的前提下如何既不静默删除标准、也不削弱完成判定的权威性。一、ADR 背景验收标准何时可以被证伪又为何不能静默删除Ralph 的 PRDprd.json在派发时冻结验收标准。每个用户故事UserStory携带一组acceptanceCriteria而 Ralph 循环的 Step 4/7 只会对这些标准逐条验证见 Ralph 技能文档。问题在于实现工作往往会产生计划外的实证结果。ADR 03664 引用的正是 issue #3664 的具体失败案例派发简报中写的是所有 16 个设置FDFT_WHALE_STREAM1的文件都需要分类而实现者枚举后实际只有 12 个 setter——另外 7 个是读取方/断言方/文档配方。更重要的是这 7 个被误分类的读取方恰好是唯一受影响的文件错误的计数把正确答案掩盖了。面对这种情况存在三种常见的错误处理方式静默删除被证伪的标准—— 破坏审计追踪reviewer 无从得知原标准为何失效声称标准已满足—— 当测量已证伪标准时硬性宣称通过是文档中明确定义的PRD theaterPRD 走过场模型无 schema 的自由改写—— 不可验证、可静默删除同样违反 Ralph 的哲学。因此 ADR 03664 做出的决策是一条验收标准只能通过criterionAmendments账本条目停止支配完成判定——该条目必须原样保留被证伪的标准原文并附带有界的证据、理由、执行者和时间戳。不存在静默删除路径也不存在任意削弱目标的空间。二、核心决策与数据 Schema账本即审计轨迹ADR 给出了两段核心 TypeScript 类型它们在源码 src/hooks/ralph/prd.ts 中得到完整落地。2.1CriterionAmendment一次修正的完整记录type CriterionAmendmentKind replaced | superseded; interface CriterionAmendment { kind: CriterionAmendmentKind; // replaced (corrected criterion governs) | superseded (no replacement governs) original: string; // verbatim refuted criterion, retained forever replacement?: string; // required for replaced; must be absent for superseded reason: string; // why the original no longer governs (mandatory) evidence: string; // the bounded measurement that refuted it (mandatory, 10 chars) authority: string; // who performed the amendment (mandatory) timestamp: string; // ISO 8601 }对应源码中 prd.ts 第 36-51 行 的CriterionAmendment接口注释明确了两个关键语义original是逐字保留、永不改写或删除的原标准文本修改一条标准是该标准停止支配完成判定的唯一合法途径。而CriterionAmendmentKind区分两种形态replaced有一个修正后的标准接替支配replacement必填superseded没有替代标准支配replacement必须缺席。这种二值形态让账本既能表达计数修正用正确计数替代错误计数也能表达标准本身不成立整条作废且无替代。2.2UserStory的扩展活动标准与证据账本分离interface UserStory { // ... acceptanceCriteria: string[]; // currently governing criteria only criterionAmendments?: CriterionAmendment[]; // evidence ledger; original retained }这个设计的关键洞察是状态与历史分离acceptanceCriteria只保留当前正在支配的标准——Ralph 的 Step 4/7 只验证这些criterionAmendments是可选证据账本——每条被证伪的原标准连同证据被永久保留。在源码 prd.ts 第 53-78 行 的UserStory中还看到若干与该机制协同的 revision 字段governingCriteriaRevision本故事活动标准与账本的规范摘要、completionCriteriaRevision标记完成时所依据的标准修订、architectVerificationCriteriaRevision架构师批准所依据的标准修订。这些字段是本 ADR 机制能安全落地的前提——见下文修订绑定与并发安全。三、Authority 与完成语义原子修正、闭集错误码、fail-closed 读取ADR 对权威authority与完成completion语义做了严格的机制定义这些语义全部被源码实现逐条落实。3.1 两个编程入口ADR 定义的入口在 prd.ts 中实现// replaced: 修正标准在原位置插入账本追加记录 export function amendCriterion( directory: string, storyId: string, input: CriterionAmendmentInput, sessionId?: string ): CriterionAmendmentResult; // superseded: 无替代移除账本追加记录 export function supersedeCriterion( directory: string, storyId: string, input: CriterionAmendmentInput, sessionId?: string ): CriterionAmendmentResult;其中CriterionAmendmentInputprd.ts 第 133-146 行除timestamp外所有字段必填——任何不带证据、理由与执行者的修正都无法被记录。省略timestamp时自动取当前时间new Date().toISOString()。3.2 Mutation gate闭集错误码与失败即不变更ADR 列出了完整闭集错误码在 applyCriterionAmendment 的实现 中逐条对应错误码触发条件prd-not-found目录下找不到可用的 PRDstory-not-found指定的storyId不存在original-not-active待修正的标准不在活动列表中含空字符串reason-requiredreason为空evidence-requiredevidence为空evidence-too-short证据长度小于MIN_CRITERION_EVIDENCE_LENGTH 10authority-requiredauthority为空replacement-requiredkindreplaced但未提供replacementreplacement-not-allowedkindsuperseded却提供了replacementwrite-failed写入阶段异常失败ADR 强调一次失败的变更绝不改动 PRD。源码对此的实现方式非常直接所有校验都在进入mutatePrd锁内变更之前完成一旦命中错误码直接返回{ ok: false, error }磁盘上的 PRD 保持原样。测试 ralph-prd-amendment.test.ts 中的never mutates the PRD on validation failure用例专门验证了这一点传入evidence: short后断言acceptanceCriteria仍为原始标准、criterionAmendments保持undefined。3.3 成功变更的原子动作一个成功的变更见 applyCriterionAmendment 第 910-925 行在mutatePrd的独占文件锁内完成四个原子动作从acceptanceCriteria中移除原标准若为replaced把修正标准插入原标准的位置而非追加到末尾——测试用例inserts the replacement at the original criterion position验证了[first, original, last]会变为[first, replacement, last]把完整修正记录追加到criterionAmendments将故事的passes、architectVerified、completionCriteriaRevision、architectVerificationCriteriaRevision全部重置——变更会使已有的完成与批准声明失效。第 4 点是机制上极重要的一环修正后的活动标准集合与之前不同因此旧的passes: true基于旧标准集合不再可信故事必须回到未完成状态重新验证。3.4 读取期 fail-closed 校验静默偏差可被发现而非被默许ADR 的另一条关键约束是读取期规范化的 fail-closed 语义手工编辑的 PRD 若账本畸形、被修正的原标准仍处于活动状态、或原标准被重复修正则整个 PRD 无效readPrd返回null。源码中 normalizeCriterionAmendments第 206-235 行 实现该不变量字段缺失 →undefined合法兼容旧版非数组或条目非法 →null使故事非法进而使整个 PRD 非法空数组[]→ 视为缺失向后兼容每个original不得重复、不得仍出现在活动标准中否则返回null。测试套件 ralph-prd-amendment.test.ts 中fail-closed normalization invariants组完整覆盖缺 proof 字段、活动标准与被修正原标准同时存在矛盾账本、重复修正原标准、replaced无 replacement、superseded带 replacement——五种情形下readPrd均返回null。这与既有无效 PRD 启动失败的行为保持一致ensurePrdForStartupprd.ts 第 1036-1133 行会让 Ralph 明确报错而非带病运行。四、修订绑定与并发安全为什么 amendment 不会被陈旧的整文件写入抹掉本 ADR 变更发生在 Ralph 的会话/循环状态机里而 Ralph 有多个完整重写 PRD的代码路径标记完成、消费架构师批准等。若修正刚落地就被一个持有旧快照的路径整体覆写账本就会静默消失。源码用两层机制杜绝这一风险。4.1 完成声明与标准修订强绑定bindCompletionClaims第 314-333 行 在每次写入时重算governingCriteriaRevision对acceptanceCriteriacriterionAmendments取 sha256 摘要见 getGoverningCriteriaRevision并只保留修订匹配的完成声明passes true且completionCriteriaRevision governingCriteriaRevision才被视为已标记完成在此基础上还要architectVerified true且architectVerificationCriteriaRevision governingCriteriaRevision才视为完整故事。这就意味着修正改变活动标准后任何旧的完成声明都会在读取/绑定过程中被自动回退为未完成。测试fails closed when a valid hand-edited amendment retains stale completion evidence验证了手工在账本中追加合法修正但保留旧passes时读取结果会把故事打回passes: false。4.2 批准消费路径的 CAS 保护consumeStoryArchitectApproval第 632-686 行 与consumeCompletionArchitectApproval在消费架构师批准时做多重 revision 校验只有磁盘 PRD 仍与提交审核时的修订一致时才落地批准否则拒绝。测试套件中一组forced interleaving用例如rejects a stale full-PRD replacement after an amendment commits、does not overwrite a direct amendment injected after story request consumption证明修正提交后任何持旧快照的整文件写入都会因 revision 不匹配而失败。文档 REFERENCE.md 也总结了这一契约缺少当前标准修订的完成/批准声明会被重开并重新验证。五、实操如何在 Ralph 循环内修正被证伪的验收标准criterionAmendments的完整操作指引内嵌在 Ralph 技能文档PRD_Criterion_Amendments段 中并被持续注入到循环上下文的提示中。Ralph 的 Step 4验证明确规定实现证明标准在实证上为假时不得标记故事完成、不得静默删除或削弱标准而应走证据保留路径。5.1 操作三步骤判断形态用修正后的实测结果replace被证伪的标准若无替代标准支配则supersede在故事的criterionAmendments账本中记录original必须逐字保留且必须仍在活动列表中完成检查只验证活动标准账本保留审计轨迹供 reviewer 查看。5.2 完整 JSON 修正示例技能文档内嵌以 #3664 的 16→12 案例为例技能文档给出了可直接套用的 JSON 形态{ kind: replaced, original: All 16 files that set FDFT_WHALE_STREAM1 are classified affected/not-affected WITH EVIDENCE, replacement: All 12 files that set FDFT_WHALE_STREAM1 are classified affected/not-affected WITH EVIDENCE, reason: The brief count was wrong: 7 listed names are readers/asserters/doc-recipes, not setters, evidence: Enumerated setters via grep FDFT_WHALE_STREAM1: 12 setters, 16 total matches, authority: ses_ralph-session-id, timestamp: 2026-08-10T03:15:00.000Z }技能文档特别强调了两条铁律无有界证据、理由、执行者或时间戳的修正是无效的——PRD 会在读取时 fail-closed而非被静默削弱仍处于活动状态的原标准不能被修正一条原标准只能被修正一次一旦离开活动列表再次修正会返回original-not-active。5.3 程序化调用的参数语义若以编程方式调用供 Agent 工具或集成代码使用需显式传入directory与storyIdimport { amendCriterion, supersedeCriterion } from src/hooks/ralph/prd.js; // 替换修正标准插入原位置 const r1 amendCriterion(dir, US-001, { original: FDFT_ORIGINAL, // 必须逐字等于当前活动标准 replacement: FDFT_REPLACEMENT, // replaced 必填 reason: ..., // 非空 evidence: ..., // 非空且 10 字符 authority: ses_session-id, // 非空 timestamp: new Date().toISOString(), // 可省略缺省自动取当前时间 }); // { ok: true, amendment: {...} } 或 { ok: false, error: 闭集错误码 } // 作废无替代移除 const r2 supersedeCriterion(dir, US-001, { original: FDFT_ORIGINAL, reason: ..., evidence: ..., authority: ses_session-id, });补充说明几个可从源码确认的实现细节amendCriterion/supersedeCriterion内部共用同一个 applyCriterionAmendment仅kind不同保证校验与写路径完全一致会话隔离session scoping已内建带sessionId时读写定位到.omc/state/sessions/{sessionId}/prd.json见 findPrdPath。测试is session-scoped验证session-a内修正后session-b读到的是原始标准所有写操作走withStateFileMutationLock独占文件锁与原子写writePrdAtRevision支持 CAS传expectedRevision可拒绝陈旧的整文件覆写见 prd.ts 第 601-609 行。六、账本如何传导到循环与 Reviewer透明的审计呈现ADR 决策中有一条明确的传导要求Ralph 的循环上下文、continuation 提示、next-story 提示与架构师验证提示都要呈现修正账本让执行 Agent 和 reviewer看到带删除线的原标准与证据。源码通过统一的格式化函数实现。6.1 格式化带删除线的证据账本formatCriterionAmendments第 1163-1178 行 把账本渲染为 Markdown**Amended/Superseded Criteria (evidence ledger):** - ~~All 16 files that set FDFT_WHALE_STREAM1 ...~~ — replaced by: All 12 files that set ... (reason: ...; evidence: ...; authority: ...; at: ...)无修正时返回空字符串因此旧版故事的输出完全不受影响测试断言无修正时formatStory不含 evidence ledger、formatPrd不含~~formatStory第 1183-1214 行在活动标准列表下方渲染账本formatNextStoryPrompt第 1249-1277 行把账本连同若实现证明某标准为假用证据修正/作废它而非静默删除或宣称通过的指令注入到下一个故事的循环上下文持续模式persistent-mode的 continuation prompt 同样携带该指令见 src/hooks/persistent-mode/index.ts。6.2 Reviewer 提示验证修正是否被证据支撑架构师验证提示getArchitectVerificationPrompt在目标故事存在修正时注入完整账本并要求 reviewer验证每条修正都为其引用的证据所支撑且下面的活动标准才是真正支配的标准。换句话说reviewer 不仅要检查实现是否满足当前活动标准还要检查账本记录本身是否诚实、有据可依。相关测试ralph-prd-amendment.test.ts的formatting and prompts组逐一断言了formatCriterionAmendments、formatStory、formatNextStoryPrompt与架构师验证提示都能呈现带删除线的原标准、replacement、reason、evidence、authority、timestamp从而保证这一传导被确定性测试锁住。七、向后兼容、迁移与已知限制ADR 对兼容性做了明确承诺源码与测试均给出佐证criterionAmendments可选旧版 PRD无账本的读取、格式化与写入完全不变。测试reads and writes a legacy PRD without amendments unchanged断言无修正时 round-trip 无损格式化字节级一致无修正故事的formatStory/formatPrd输出与改动前逐字节相同测试keeps formatting identical for stories without amendments空账本视为缺失criterionAmendments: []读取后等价于undefined测试treats an empty amendment array as absentUserStoryInput/createPrd透传字段通过程序化方式构造故事时账本被完整保留测试preserves amendments when a story is created through createPrd已文档化的固有局限更老版本的 OMC 构建在重写 PRD 时只会序列化它自身 normalizer 认识的字段因此不会保留账本——修正记录只被携带本 schema 的构建所理解跨版本并发写入不在支持契约内。这一限制由 REFERENCE.md 明确记录。八、为何拒绝其他备选方案一次决策权衡的复盘ADR 完整记录了三组被否决的备选方案理解它们有助于把握本机制的设计哲学每条标准挂一个superseded: boolean标志issue 最小化建议—— 被拒。布尔标志既不记录证据也不记录替代标准削弱了 PRD 赖以存在的审计轨迹无 schema 的模型自由改写标准—— 被拒。这正是技能文档反复警告的PRD theater不可验证、可静默删除读取时自动消解矛盾丢弃坏账本条目—— 被拒。静默修复是另一种形式的静默删除fail-closed 才是既有 PRD 哲学。九、源码级测试覆盖把机制锁进契约本机制的确定性测试集中在 src/tests/ralph-prd-amendment.test.ts按describe组划分覆盖如下契约面amendCriterion原子替换与账本保留、原位插入、时间戳缺省、读写 round-trip、会话隔离、并发批准下的更新保全supersedeCriterion无替代移除、拒绝携带 replacementstrict validationstory-not-found/prd-not-found/original-not-active/reason-required/evidence-required/evidence-too-short/authority-required/replacement-required/replacement-not-allowed全闭集错误码以及同一原标准只能修正一次与失败绝不改盘fail-closed normalization畸形账本、矛盾账本、重复原标准在读取时令readPrd返回nullbackward compatibility旧版 PRD 无损读写、无修正格式化逐字节一致、createPrd透传账本completion semantics修正使已完成且已批准的故事失效、supersede 后完成判定不再被阻、架构师批准被陈旧标准自动重开formatting and prompts账本在各类提示中的可读呈现。这组测试与 ADR 03664、REFERENCE.md 对应章节 及 Ralph 技能文档 共同构成文档—实现—测试三重闭环任何破坏该语义的改动都会在任一层被拦截。十、结语测量取胜但循环不失其锚ADR 03664 在 oh-my-claudecode 中的落地回答了 Ralph 循环一个根本性的矛盾当实证测量与派发计划冲突时谁说了算答案是测量说了算——通过criterionAmendments账本被证伪的标准以逐字保留的原文、有界的证据、明确的理由与执行者身份退出支配位同时循环的完成判定没有丢失任何权威——修正会立即使旧完成声明失效、使故事回到待验证状态并让 reviewer 在透明的删除线证据之上重新把关。它把不削弱目标与尊重现实测量这两条看似对立的原则统一进了一套不可静默绕过的、可审计的标准治理机制。对于任何依赖 Agent 自主循环执行长任务、又想对标准变更保持可追溯性的系统这套证据账本 fail-closed 校验 revision 绑定的设计都值得直接借鉴。【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 oh-my-claudecode 的 Ralph PRD 验收标准修正机制：基于证据保留的证据型 Criterion Amendment
oh-my-claudecode 的 Ralph PRD 验收标准修正机制基于证据保留的证据型 Criterion Amendment【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode导读oh-my-claudecode 的 Ralph 循环一种 PRD 驱动的持续执行循环将验收标准视为完成判定的权威只有所有活动验收标准都通过、并经过 reviewer 验证的故事才允许推进。但当实现过程中测量结果与派发时的简报不一致时例如简报声称存在 16 个 setter实测只有 12 个既不能靠模型静默改写验收标准也不能放任一条已被证伪的标准继续卡死整个循环。本篇文章围绕 ADR 03664 展开深入讲解 Ralph 引入的**证据保留型验收标准修正criterion amendment**机制——从criterionAmendments账本的数据结构、amendCriterion/supersedeCriterion两个编程接口、fail-closed 的读取校验到它在循环、reviewer 提示词与持续对话提示中的完整传导。读完你将掌握在测量胜过计划的前提下如何既不静默删除标准、也不削弱完成判定的权威性。一、ADR 背景验收标准何时可以被证伪又为何不能静默删除Ralph 的 PRDprd.json在派发时冻结验收标准。每个用户故事UserStory携带一组acceptanceCriteria而 Ralph 循环的 Step 4/7 只会对这些标准逐条验证见 Ralph 技能文档。问题在于实现工作往往会产生计划外的实证结果。ADR 03664 引用的正是 issue #3664 的具体失败案例派发简报中写的是所有 16 个设置FDFT_WHALE_STREAM1的文件都需要分类而实现者枚举后实际只有 12 个 setter——另外 7 个是读取方/断言方/文档配方。更重要的是这 7 个被误分类的读取方恰好是唯一受影响的文件错误的计数把正确答案掩盖了。面对这种情况存在三种常见的错误处理方式静默删除被证伪的标准—— 破坏审计追踪reviewer 无从得知原标准为何失效声称标准已满足—— 当测量已证伪标准时硬性宣称通过是文档中明确定义的PRD theaterPRD 走过场模型无 schema 的自由改写—— 不可验证、可静默删除同样违反 Ralph 的哲学。因此 ADR 03664 做出的决策是一条验收标准只能通过criterionAmendments账本条目停止支配完成判定——该条目必须原样保留被证伪的标准原文并附带有界的证据、理由、执行者和时间戳。不存在静默删除路径也不存在任意削弱目标的空间。二、核心决策与数据 Schema账本即审计轨迹ADR 给出了两段核心 TypeScript 类型它们在源码 src/hooks/ralph/prd.ts 中得到完整落地。2.1CriterionAmendment一次修正的完整记录type CriterionAmendmentKind replaced | superseded; interface CriterionAmendment { kind: CriterionAmendmentKind; // replaced (corrected criterion governs) | superseded (no replacement governs) original: string; // verbatim refuted criterion, retained forever replacement?: string; // required for replaced; must be absent for superseded reason: string; // why the original no longer governs (mandatory) evidence: string; // the bounded measurement that refuted it (mandatory, 10 chars) authority: string; // who performed the amendment (mandatory) timestamp: string; // ISO 8601 }对应源码中 prd.ts 第 36-51 行 的CriterionAmendment接口注释明确了两个关键语义original是逐字保留、永不改写或删除的原标准文本修改一条标准是该标准停止支配完成判定的唯一合法途径。而CriterionAmendmentKind区分两种形态replaced有一个修正后的标准接替支配replacement必填superseded没有替代标准支配replacement必须缺席。这种二值形态让账本既能表达计数修正用正确计数替代错误计数也能表达标准本身不成立整条作废且无替代。2.2UserStory的扩展活动标准与证据账本分离interface UserStory { // ... acceptanceCriteria: string[]; // currently governing criteria only criterionAmendments?: CriterionAmendment[]; // evidence ledger; original retained }这个设计的关键洞察是状态与历史分离acceptanceCriteria只保留当前正在支配的标准——Ralph 的 Step 4/7 只验证这些criterionAmendments是可选证据账本——每条被证伪的原标准连同证据被永久保留。在源码 prd.ts 第 53-78 行 的UserStory中还看到若干与该机制协同的 revision 字段governingCriteriaRevision本故事活动标准与账本的规范摘要、completionCriteriaRevision标记完成时所依据的标准修订、architectVerificationCriteriaRevision架构师批准所依据的标准修订。这些字段是本 ADR 机制能安全落地的前提——见下文修订绑定与并发安全。三、Authority 与完成语义原子修正、闭集错误码、fail-closed 读取ADR 对权威authority与完成completion语义做了严格的机制定义这些语义全部被源码实现逐条落实。3.1 两个编程入口ADR 定义的入口在 prd.ts 中实现// replaced: 修正标准在原位置插入账本追加记录 export function amendCriterion( directory: string, storyId: string, input: CriterionAmendmentInput, sessionId?: string ): CriterionAmendmentResult; // superseded: 无替代移除账本追加记录 export function supersedeCriterion( directory: string, storyId: string, input: CriterionAmendmentInput, sessionId?: string ): CriterionAmendmentResult;其中CriterionAmendmentInputprd.ts 第 133-146 行除timestamp外所有字段必填——任何不带证据、理由与执行者的修正都无法被记录。省略timestamp时自动取当前时间new Date().toISOString()。3.2 Mutation gate闭集错误码与失败即不变更ADR 列出了完整闭集错误码在 applyCriterionAmendment 的实现 中逐条对应错误码触发条件prd-not-found目录下找不到可用的 PRDstory-not-found指定的storyId不存在original-not-active待修正的标准不在活动列表中含空字符串reason-requiredreason为空evidence-requiredevidence为空evidence-too-short证据长度小于MIN_CRITERION_EVIDENCE_LENGTH 10authority-requiredauthority为空replacement-requiredkindreplaced但未提供replacementreplacement-not-allowedkindsuperseded却提供了replacementwrite-failed写入阶段异常失败ADR 强调一次失败的变更绝不改动 PRD。源码对此的实现方式非常直接所有校验都在进入mutatePrd锁内变更之前完成一旦命中错误码直接返回{ ok: false, error }磁盘上的 PRD 保持原样。测试 ralph-prd-amendment.test.ts 中的never mutates the PRD on validation failure用例专门验证了这一点传入evidence: short后断言acceptanceCriteria仍为原始标准、criterionAmendments保持undefined。3.3 成功变更的原子动作一个成功的变更见 applyCriterionAmendment 第 910-925 行在mutatePrd的独占文件锁内完成四个原子动作从acceptanceCriteria中移除原标准若为replaced把修正标准插入原标准的位置而非追加到末尾——测试用例inserts the replacement at the original criterion position验证了[first, original, last]会变为[first, replacement, last]把完整修正记录追加到criterionAmendments将故事的passes、architectVerified、completionCriteriaRevision、architectVerificationCriteriaRevision全部重置——变更会使已有的完成与批准声明失效。第 4 点是机制上极重要的一环修正后的活动标准集合与之前不同因此旧的passes: true基于旧标准集合不再可信故事必须回到未完成状态重新验证。3.4 读取期 fail-closed 校验静默偏差可被发现而非被默许ADR 的另一条关键约束是读取期规范化的 fail-closed 语义手工编辑的 PRD 若账本畸形、被修正的原标准仍处于活动状态、或原标准被重复修正则整个 PRD 无效readPrd返回null。源码中 normalizeCriterionAmendments第 206-235 行 实现该不变量字段缺失 →undefined合法兼容旧版非数组或条目非法 →null使故事非法进而使整个 PRD 非法空数组[]→ 视为缺失向后兼容每个original不得重复、不得仍出现在活动标准中否则返回null。测试套件 ralph-prd-amendment.test.ts 中fail-closed normalization invariants组完整覆盖缺 proof 字段、活动标准与被修正原标准同时存在矛盾账本、重复修正原标准、replaced无 replacement、superseded带 replacement——五种情形下readPrd均返回null。这与既有无效 PRD 启动失败的行为保持一致ensurePrdForStartupprd.ts 第 1036-1133 行会让 Ralph 明确报错而非带病运行。四、修订绑定与并发安全为什么 amendment 不会被陈旧的整文件写入抹掉本 ADR 变更发生在 Ralph 的会话/循环状态机里而 Ralph 有多个完整重写 PRD的代码路径标记完成、消费架构师批准等。若修正刚落地就被一个持有旧快照的路径整体覆写账本就会静默消失。源码用两层机制杜绝这一风险。4.1 完成声明与标准修订强绑定bindCompletionClaims第 314-333 行 在每次写入时重算governingCriteriaRevision对acceptanceCriteriacriterionAmendments取 sha256 摘要见 getGoverningCriteriaRevision并只保留修订匹配的完成声明passes true且completionCriteriaRevision governingCriteriaRevision才被视为已标记完成在此基础上还要architectVerified true且architectVerificationCriteriaRevision governingCriteriaRevision才视为完整故事。这就意味着修正改变活动标准后任何旧的完成声明都会在读取/绑定过程中被自动回退为未完成。测试fails closed when a valid hand-edited amendment retains stale completion evidence验证了手工在账本中追加合法修正但保留旧passes时读取结果会把故事打回passes: false。4.2 批准消费路径的 CAS 保护consumeStoryArchitectApproval第 632-686 行 与consumeCompletionArchitectApproval在消费架构师批准时做多重 revision 校验只有磁盘 PRD 仍与提交审核时的修订一致时才落地批准否则拒绝。测试套件中一组forced interleaving用例如rejects a stale full-PRD replacement after an amendment commits、does not overwrite a direct amendment injected after story request consumption证明修正提交后任何持旧快照的整文件写入都会因 revision 不匹配而失败。文档 REFERENCE.md 也总结了这一契约缺少当前标准修订的完成/批准声明会被重开并重新验证。五、实操如何在 Ralph 循环内修正被证伪的验收标准criterionAmendments的完整操作指引内嵌在 Ralph 技能文档PRD_Criterion_Amendments段 中并被持续注入到循环上下文的提示中。Ralph 的 Step 4验证明确规定实现证明标准在实证上为假时不得标记故事完成、不得静默删除或削弱标准而应走证据保留路径。5.1 操作三步骤判断形态用修正后的实测结果replace被证伪的标准若无替代标准支配则supersede在故事的criterionAmendments账本中记录original必须逐字保留且必须仍在活动列表中完成检查只验证活动标准账本保留审计轨迹供 reviewer 查看。5.2 完整 JSON 修正示例技能文档内嵌以 #3664 的 16→12 案例为例技能文档给出了可直接套用的 JSON 形态{ kind: replaced, original: All 16 files that set FDFT_WHALE_STREAM1 are classified affected/not-affected WITH EVIDENCE, replacement: All 12 files that set FDFT_WHALE_STREAM1 are classified affected/not-affected WITH EVIDENCE, reason: The brief count was wrong: 7 listed names are readers/asserters/doc-recipes, not setters, evidence: Enumerated setters via grep FDFT_WHALE_STREAM1: 12 setters, 16 total matches, authority: ses_ralph-session-id, timestamp: 2026-08-10T03:15:00.000Z }技能文档特别强调了两条铁律无有界证据、理由、执行者或时间戳的修正是无效的——PRD 会在读取时 fail-closed而非被静默削弱仍处于活动状态的原标准不能被修正一条原标准只能被修正一次一旦离开活动列表再次修正会返回original-not-active。5.3 程序化调用的参数语义若以编程方式调用供 Agent 工具或集成代码使用需显式传入directory与storyIdimport { amendCriterion, supersedeCriterion } from src/hooks/ralph/prd.js; // 替换修正标准插入原位置 const r1 amendCriterion(dir, US-001, { original: FDFT_ORIGINAL, // 必须逐字等于当前活动标准 replacement: FDFT_REPLACEMENT, // replaced 必填 reason: ..., // 非空 evidence: ..., // 非空且 10 字符 authority: ses_session-id, // 非空 timestamp: new Date().toISOString(), // 可省略缺省自动取当前时间 }); // { ok: true, amendment: {...} } 或 { ok: false, error: 闭集错误码 } // 作废无替代移除 const r2 supersedeCriterion(dir, US-001, { original: FDFT_ORIGINAL, reason: ..., evidence: ..., authority: ses_session-id, });补充说明几个可从源码确认的实现细节amendCriterion/supersedeCriterion内部共用同一个 applyCriterionAmendment仅kind不同保证校验与写路径完全一致会话隔离session scoping已内建带sessionId时读写定位到.omc/state/sessions/{sessionId}/prd.json见 findPrdPath。测试is session-scoped验证session-a内修正后session-b读到的是原始标准所有写操作走withStateFileMutationLock独占文件锁与原子写writePrdAtRevision支持 CAS传expectedRevision可拒绝陈旧的整文件覆写见 prd.ts 第 601-609 行。六、账本如何传导到循环与 Reviewer透明的审计呈现ADR 决策中有一条明确的传导要求Ralph 的循环上下文、continuation 提示、next-story 提示与架构师验证提示都要呈现修正账本让执行 Agent 和 reviewer看到带删除线的原标准与证据。源码通过统一的格式化函数实现。6.1 格式化带删除线的证据账本formatCriterionAmendments第 1163-1178 行 把账本渲染为 Markdown**Amended/Superseded Criteria (evidence ledger):** - ~~All 16 files that set FDFT_WHALE_STREAM1 ...~~ — replaced by: All 12 files that set ... (reason: ...; evidence: ...; authority: ...; at: ...)无修正时返回空字符串因此旧版故事的输出完全不受影响测试断言无修正时formatStory不含 evidence ledger、formatPrd不含~~formatStory第 1183-1214 行在活动标准列表下方渲染账本formatNextStoryPrompt第 1249-1277 行把账本连同若实现证明某标准为假用证据修正/作废它而非静默删除或宣称通过的指令注入到下一个故事的循环上下文持续模式persistent-mode的 continuation prompt 同样携带该指令见 src/hooks/persistent-mode/index.ts。6.2 Reviewer 提示验证修正是否被证据支撑架构师验证提示getArchitectVerificationPrompt在目标故事存在修正时注入完整账本并要求 reviewer验证每条修正都为其引用的证据所支撑且下面的活动标准才是真正支配的标准。换句话说reviewer 不仅要检查实现是否满足当前活动标准还要检查账本记录本身是否诚实、有据可依。相关测试ralph-prd-amendment.test.ts的formatting and prompts组逐一断言了formatCriterionAmendments、formatStory、formatNextStoryPrompt与架构师验证提示都能呈现带删除线的原标准、replacement、reason、evidence、authority、timestamp从而保证这一传导被确定性测试锁住。七、向后兼容、迁移与已知限制ADR 对兼容性做了明确承诺源码与测试均给出佐证criterionAmendments可选旧版 PRD无账本的读取、格式化与写入完全不变。测试reads and writes a legacy PRD without amendments unchanged断言无修正时 round-trip 无损格式化字节级一致无修正故事的formatStory/formatPrd输出与改动前逐字节相同测试keeps formatting identical for stories without amendments空账本视为缺失criterionAmendments: []读取后等价于undefined测试treats an empty amendment array as absentUserStoryInput/createPrd透传字段通过程序化方式构造故事时账本被完整保留测试preserves amendments when a story is created through createPrd已文档化的固有局限更老版本的 OMC 构建在重写 PRD 时只会序列化它自身 normalizer 认识的字段因此不会保留账本——修正记录只被携带本 schema 的构建所理解跨版本并发写入不在支持契约内。这一限制由 REFERENCE.md 明确记录。八、为何拒绝其他备选方案一次决策权衡的复盘ADR 完整记录了三组被否决的备选方案理解它们有助于把握本机制的设计哲学每条标准挂一个superseded: boolean标志issue 最小化建议—— 被拒。布尔标志既不记录证据也不记录替代标准削弱了 PRD 赖以存在的审计轨迹无 schema 的模型自由改写标准—— 被拒。这正是技能文档反复警告的PRD theater不可验证、可静默删除读取时自动消解矛盾丢弃坏账本条目—— 被拒。静默修复是另一种形式的静默删除fail-closed 才是既有 PRD 哲学。九、源码级测试覆盖把机制锁进契约本机制的确定性测试集中在 src/tests/ralph-prd-amendment.test.ts按describe组划分覆盖如下契约面amendCriterion原子替换与账本保留、原位插入、时间戳缺省、读写 round-trip、会话隔离、并发批准下的更新保全supersedeCriterion无替代移除、拒绝携带 replacementstrict validationstory-not-found/prd-not-found/original-not-active/reason-required/evidence-required/evidence-too-short/authority-required/replacement-required/replacement-not-allowed全闭集错误码以及同一原标准只能修正一次与失败绝不改盘fail-closed normalization畸形账本、矛盾账本、重复原标准在读取时令readPrd返回nullbackward compatibility旧版 PRD 无损读写、无修正格式化逐字节一致、createPrd透传账本completion semantics修正使已完成且已批准的故事失效、supersede 后完成判定不再被阻、架构师批准被陈旧标准自动重开formatting and prompts账本在各类提示中的可读呈现。这组测试与 ADR 03664、REFERENCE.md 对应章节 及 Ralph 技能文档 共同构成文档—实现—测试三重闭环任何破坏该语义的改动都会在任一层被拦截。十、结语测量取胜但循环不失其锚ADR 03664 在 oh-my-claudecode 中的落地回答了 Ralph 循环一个根本性的矛盾当实证测量与派发计划冲突时谁说了算答案是测量说了算——通过criterionAmendments账本被证伪的标准以逐字保留的原文、有界的证据、明确的理由与执行者身份退出支配位同时循环的完成判定没有丢失任何权威——修正会立即使旧完成声明失效、使故事回到待验证状态并让 reviewer 在透明的删除线证据之上重新把关。它把不削弱目标与尊重现实测量这两条看似对立的原则统一进了一套不可静默绕过的、可审计的标准治理机制。对于任何依赖 Agent 自主循环执行长任务、又想对标准变更保持可追溯性的系统这套证据账本 fail-closed 校验 revision 绑定的设计都值得直接借鉴。【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考