> 目标:不回滚 PR #18 的 evidence-first、跨项目模板和直接风险覆盖方向,只关闭已确认存在真实消费者或真实失败路径的合同缺口。 > 建议交付:一个 `coding-workflow` 核心 PR;与核心缺口无直接依赖的测试债务、supplemental suite 登记、Mermaid/SOP 可读性优化另行处理。 --- ### 明确不纳入核心 PR 1. 不要求 SEC checker 在本 PR 前新增 `anchor:` / `ref:` / `contract:` 黑名单;当前没有真实 alias 命中证据,且 checker 目前只保证 canonical directive 的提取和 malformed-canonical 检测。 2. 不给政策权威建立简单总优先级;配置证明 enforcement,DEC/治理文档证明 intent,两者冲突不能静默选边。 3. 不要求所有旧治理散文都重新获得 owner 确认;当前 tracked、scoped governance entry 可作为推定有效的政策权威,歧义或冲突时才进入 open decision。 4. 不向 SEC Case A 注入人工政策 fixture;Case A 继续使用真实仓库事实。验收改为对当前 SEC 已存在的政策做强制分类和逐项处置记录。 5. 不把 XDG attributes 回归、supplemental suite 登记、PR #19 历史说明、外部 eval runner 或 SEC 既知文档修复捆绑进核心 PR。它们各自需要独立 finding、范围和验收。 6. 不提升 `capability_contract.json.schema_version`;本方案冻结该字段只表示 JSON 数据形状/必需字段,不表示所有 authoring prose 规则的修订版本。 7. 不恢复完整三文档关系章节,不在核心 PR 增加 Mermaid 或 SOP 诊断语。 --- ## 1. 背景与当前事实 PR #18 正确把 `zh/` / `en/` 从带有个人偏好、Python/PowerShell 假设和示例能力的“万能项目规范”,重构为需要根据目标仓库事实项目化的下游模板。 当前主干已经具备以下正确边界: - `prepare` / `check` 只承担固定 object、目标 HEAD、dirty allowlist、文件形状、UTF-8、active marker 和 whitespace 等机械事实; - 语义真实性由目标代码/配置/测试、Case G、Case A 和 review 承担; - `capability_contract.json → interact.md → docs/business_user_guide.md` 保持单向权威; - 测试层级按真实覆盖范围表述; - 不写 run state、receipt、ledger 或仓库内 PR body; - PR #19 已增加写入前 finding、临时 upstream cleanup、多解释器分别记录和 independent review 身份证据。 当前仍存在五个可复现或有真实消费者的缺口。 ### G-01|事实与政策没有完整的双向分类规则 Skill 仍有“删除没有当前事实证据的强声明”。这会误伤无法从代码反推、但由目标仓库明确制定的规范性政策;反方向上,Agent 也可能把过时事实改写成“必须……”来规避事实核验。 真实消费者:SEC_metrics 的 tracked `AGENTS.md` 已含 fail-fast、具体异常、显式数据契约等 owner-declared 项目政策。 ### G-02|Anchor 消费者存在,发布者未正式定义协议 `coding-workflow` 当前双语模板中没有 `capability-anchor` 定义;SEC_metrics checker 已硬编码: ```text marker: capability-anchor ID: [A-Za-z0-9_.-]+ comment 内空白可容忍 ``` 同时,当前 checker 只检测 canonical `capability-anchor:` 的 malformed form;`<!-- anchor: ... -->` 等非 canonical 文本通常只是不可见,并不会被穷举拒绝。因此上游不能声称真实消费者已经实现“所有 alias 必败”。 ### G-03|跨项目最低测试决策只剩空 marker `TESTING.md §4` 没有固定最低规则;PR Checklist 只要求记录命令和结果,没有要求解释“为什么这次需要或不需要 test diff”。 ### G-04|Finding 闭环缺少生命周期与证据状态边界 当前模板有 finding ID、severity、证据、修复、复核,但没有精确定义 first-seen、reopen、candidate/evidence superseded 以及无法解释漏检原因时如何诚实记录。 ### G-05|两轮 Case A 允许第一轮漏检后仍整体 PASS DEC-006/当前 eval 允许第二轮因“新增项目事实”做最小改写。若 target 代码、配置、测试和 committed artifacts 身份没有变化,第二轮发现有效修正说明第一轮调查不完整;继续 PASS 会把“第二轮兜底”误写为“两轮收敛”。PR #18 round 2 已出现同一 identity 下再次发现文档错误并仍 PASS 的现实样本。 --- ## 2. 核心原则 ### P-01|不回滚 PR #18 不恢复旧十条代码规范、固定 runner、固定测试目录、通用假 Mermaid、样例能力、逐文件测试索引、仓库内 PR body 或单 commit/amend 发布政策。 ### P-02|按语义分类,不按句式分类 祈使句不自动是政策,陈述句也不自动是事实。含“当前实现必须……”等混合语义时,拆分规范意图与现状断言分别核验。 ### P-03|Enforcement 与 intent 不建立简单总排序 机器配置证明当前实际 enforcement;accepted decision、scoped governance instruction 证明规范意图。两者冲突是治理漂移,应形成 finding/open decision,而不是静默让一方“胜出”。 ### P-04|一个协议一个定义点 Canonical anchor token 只在 `capability_contract.json.rules` 定义。`TESTING.md`、Checklist 和 Skill 只指向该协议,不复写 token。 ### P-05|不扩张 `sync_docs.py` 本 PR 不增加 anchor parser、policy parser、PR history receipt、Markdown parser 或新 CLI。 ### P-06|现实 eval 不注入已知缺陷 SEC Case A 使用真实仓库事实。需要机械正负例时放在现有 repository distribution contract 或目标项目自己的 checker 测试中,不把真实 Case A 变成人工 fixture 测试。 ### P-07|第二轮证明收敛,不承担第一轮补漏 同一 identity 的第二轮只接受 `PASS_NOOP`。任何有效新增语义修正都使两轮 gate 失败并要求重跑。 ### P-08|中文为语义源,英文等价派生 先改 `zh/` 和 canonical Skill,再同步 `en/`;英文不得独立加强或弱化合同。 --- ## 3. 决策冻结 ## D-01|描述性事实、规范性政策与个人偏好 ### 3.1 分类规则 1. **描述性事实**:关于当前系统状态、能力、命令、文件职责、运行行为、副作用、交付状态或证据强度的主张。必须由当前代码、配置、测试、committed artifacts 或可重复运行结果支持。 2. **规范性政策**:规定开发者或 Agent 应如何工作。可由当前 scoped repository instruction、accepted decision、团队/项目配置,或明确被采纳并持久化的 owner decision 支持。 3. **个人/会话偏好**:默认只属于执行者或当前任务,不得自动写入下游项目。 4. **混合语句**:同时蕴含规范意图和当前实现事实时必须拆分;其中的事实部分仍按描述性事实核验。 ### 3.2 防证据洗白 - 不得把描述性声明改写成“必须/应该”以规避当前事实证据。 - 不得把规范性政策写成“实现已经保证……”来冒充运行时证明。 - 分类依据是语义和承担的风险,不是语法形式。 ### 3.3 政策权威与冲突 - 当前 tracked、scoped 的治理入口可推定为 active policy authority;但明显的模板残留、个人偏好、历史说明、失效状态或直接冲突必须形成 finding。 - 机器配置是 enforcement 证据,不自动 supersede 规范意图。配置与政策冲突时登记 finding/open decision;当前变更不得破坏硬 gate,也不得静默把政策改写成配置现状。 - 同类规范性政策冲突时,先看显式 supersession 和目标仓库已定义的 authority/scope 规则;没有明确裁决时不擅自修改结论。 - 本轮 owner 指令默认只授权当前任务。“作为长期项目政策采纳”必须有明确意图,并在同一变更中写入 repository authority 或 accepted decision;否则不得持久化。 - 权威、范围或状态无法确认时保持非破坏性:保留原文、登记 open decision,并说明已检查的来源;不得静默删除或永久神圣化。 ### 3.4 可审查记录 保留、修改或不更新一条 material policy 时,finding/no-update reason 应指出其权威来源、作用域和冲突检查结果。 --- ## D-02|Canonical capability anchor 协议 ### 3.5 唯一 authoring form ```html <!-- capability-anchor: <ANCHOR_ID> --> ``` - marker 名称和 `ANCHOR_ID` 大小写敏感; - `ANCHOR_ID` grammar:`[A-Za-z0-9_.-]+`; - canonical authoring form 如上;目标 checker 可容忍 comment 内空白差异; - 不允许用 JSON path、数组位置或 schema 内部路径代替 anchor ID。 ### 3.6 非 canonical 形式的边界 - 只有 canonical `capability-anchor` directive 建立受支持的 contract reference。 - `anchor:`、`ref:`、`contract:`、wiki link 等其他形式不受支持,不能被当作已完成的 alignment 引用。 - 本 PR **不声称**当前 SEC checker 能穷举发现并拒绝所有未知 alias;它只保证 canonical 提取、malformed-canonical、duplicate、dangling、deprecated 等现有机械边界。 - 未来只有真实 alias 命中或真实错误成功证据,才新增最小 alias 兼容/拒绝逻辑。 ### 3.7 结构引用边界 Anchor 证明“本文档引用了某个 contract entry”,不证明某一句自然语言与该 entry 精确绑定,也不证明 statement 的业务语义已经实现。Claim-level binding 若未来需要,必须单独设计,不在本 PR 顺手扩张。 ### 3.8 `test_anchor: null` 当一个 contract entry 显式使用 `test_anchor: null` 时,必须同时包含: - 非空、具体的 `untested_reason`; - 非空的 `pending_since`。 这表示覆盖缺口已登记,不表示 claim 已自动验证。模板不在本 PR 强制 `pending_since` 的跨项目日期解析格式;目标 checker可以加严。 ### 3.9 单一定义点和版本 - Canonical token 每种语言在九份模板中恰出现一次,位置只在 `capability_contract.json.rules`。 - `TESTING.md` 和 Checklist 只指向 contract-defined protocol,不复写 token。 - `schema_version` 保持 `0.1.0`。DEC-007 明确:该字段描述 JSON 数据形状/必需字段,不为纯 authoring prose 修订升级;未来 shape 或机器必需字段变化再按版本策略调整。 --- ## D-03|跨项目最低测试决策 ### 3.10 Canonical entrypoint(只放 §0) - 已有经过验证的 repository-owned 统一入口时优先使用,并记录它实际覆盖什么。 - 不存在统一入口时,不得仅为满足模板而创建 wrapper。 - 只有多命令编排、服务生命周期或清理步骤长期重复且形成独立维护收益时,才将 wrapper 作为单独项目改动审查。 该规则不在 §4 重复。 ### 3.11 Change Type → Required Evidence 1. 可安全、确定性复现的 escaped bug:先建立修复前失败的最小回归或 fixture,再改实现。 2. 无法先红测:保留修复前失败证据,并写明不可稳定自动化的原因和剩余风险。 3. 用户可观察行为、公开契约或 schema 变化:默认新增或修改最近边界的 contract/scenario 测试。 4. 无 test diff:必须指出具体已有测试如何覆盖本次新风险,并提供重跑证据;“已有高层测试”不是充分说明。 5. 纯内部重构且行为不变:可无新测试,但必须重跑受影响路径并给 no-test-change reason。 6. 文档-only gate:只证明实际检查的结构/解析/alignment 范围,不得冒充运行时行为验证。 ### 3.12 PR 执行点 `PR_Checklist.md` 必须检查“新增或不新增测试”的决策是否符合 `TESTING.md §4`,而不仅是命令是否被记录。 --- ## D-04|Finding 生命周期、证据状态与教训提升 ### 3.13 Finding - 使用稳定 ID 和 severity; - 记录 first-seen round/source; - finding 状态可使用 `OPEN`、`CLOSED`、`DEFERRED`; - `REOPENED` 是生命周期事件,不是新 finding;重开保留原 ID并追加新证据。 ### 3.14 Candidate / evidence - `CURRENT` / `SUPERSEDED` 描述候选或证据,不描述 finding 本身; - 最终 PASS 不得覆盖早期失败; - WDS 的正式 Case G/A raw record 至少绑定 candidate SHA、record URL 和内容 digest。普通下游 PR 不强制为每条评论计算 digest。 ### 3.15 返工原因 实质返工时说明上一轮 review/gate 未发现的原因。解释必须: - 有证据支持;或 - 明确标为 `hypothesis`;或 - 写 `unknown`。 不得为了填字段编造因果。 ### 3.16 长期教训 PR closure 时评估 material finding 是否揭示缺失的可复用决策规则: - 是:提升到最合适的权威(`TESTING.md`、`SOP.md`、DEC、项目治理入口或自动化 gate),并在 PR body 索引; - 否:记录 `None — no reusable rule identified`,不写事故编年史。 `TESTING.md §8` 增加:同一失效模式合并为更一般的规则;只有知识被更强测试、自动化 gate 或权威规则完整接管时才退役,不能只因案例变旧删除。 --- ## D-05|Case A 两轮严格收敛 ### 3.17 固定身份 两轮必须使用相同: - SEC target code/config/test/committed-artifact base identity; - upstream candidate SHA; - language; - round 1 最终九文档候选 bytes(作为 round 2 输入)。 Live 外部状态变化或 target identity 变化使本次两轮证据失效,必须重新冻结并重跑。 ### 3.18 判定 - `PASS_NOOP`:round 2 重新调查、重新选择测试和重新 review 后,九文档相对 round 1 最终候选零 diff,且无 staged/untracked/ignored residue。 - `ROUND1_INCOMPLETE`:round 2 发现由冻结 target 中原已存在的代码/配置/测试/artifact 反证支持的有效新增修正。说明 round 1 漏检;整个两轮 gate FAIL。 - `ROUND2_DRIFT`:只有措辞、排序、格式或偏好变化,无新增反证。说明最小改写不稳定;整个 gate FAIL。 `ROUND1_INCOMPLETE` 或 `ROUND2_DRIFT` 后,修复候选/调查协议,从 clean target 重新运行完整 round 1 + round 2;不得只补第三轮把前两轮改判为 PASS。 --- ## 4. 文件级实施 ## 4.1 `zh/skills/workflow-docs-sync/SKILL.md` 在 `## 重建事实并最小改写` 中、PR #19 的写入前 finding 规则之前加入 D-01 分类与冲突处理。 替换: ```markdown - 删除没有当前事实证据的强声明。需要产品判断时记录 open decision,不编造结论。 ``` 为: ```markdown - 删除、收窄或降级没有当前证据的描述性强声明;规范性政策按政策权威、作用域和冲突 处理。不得把事实改写为政策以规避证据,也不得把政策伪装成实现事实。需要产品判断时 记录 open decision,不编造结论。 ``` Finding/no-update reason 对 material policy 记录 authority source 与 scope。 ## 4.2 `zh/AGENTS.md` 只修改 `Project-specific Conventions` marker: ```markdown <!-- project-fill: 从 lint、formatter、compiler、build 等机器 enforcement,以及当前有效且 适用于本范围的 repository/team instruction 或 accepted decision 提取项目专属约定;区分 machine-enforced 与 owner-declared,并标明权威来源、作用域和已检查冲突。个人/会话偏好仅在 被明确采纳为项目政策并写入仓库权威后保留;没有可验证约定时写 None — 已检查的配置和治理 范围;完成后删除此 marker --> ``` 不恢复旧代码规范,不增加完整三文档关系块。 ## 4.3 `zh/capability_contract.json` - 在 `rules` 中以一条规则发布 canonical token、case sensitivity、ID grammar、空白 tolerance 和禁止 JSON path。 - 将 null-test 规则改为同时要求 `untested_reason` **与** `pending_since`。 - 加入一句结构边界:anchor reference 不单独证明 claim 语义。 - 保持 `schema_version: 0.1.0`。 ## 4.4 `zh/TESTING.md` - §0:加入 canonical wrapper 规则,仅此一处定义。 - §3:只写“消费 contract-defined protocol”,不复写 literal token;明确结构引用边界和 null-test 两字段。 - §4:加入 D-03 最低规则,并保留 project-fill 供项目加严。 - §8:加入同类合并与完整接管后退役的一句。 ## 4.5 `zh/.github/pull_request_template.md` §7 注释加入: - stable ID / severity / first-seen; - reopen 保留 ID; - finding state 与 candidate/evidence superseded 区分; - 漏检原因必须 evidence-backed / hypothesis / unknown; - raw record 可在 comments,body 保留索引; - `Promoted reusable rule: <authority / None>`。 不预置空 ledger 表,不建立仓库内记录文件。 ## 4.6 `zh/PR_Checklist.md` 增加: 1. 测试增改决策符合 `TESTING.md §4`;无 test diff 时有具体覆盖测试和重跑证据。 2. Anchor 按 contract-defined protocol 引用,不复写 token。 3. Material rounds、reopened findings、superseded candidate/evidence 保留。 4. 漏检原因未被编造。 5. Material finding 已评估是否提升为长期规则/自动 gate。 ## 4.7 `zh/docs/development_workflow/decisions.md` 新增 `DEC-007`,记录: - D-01 的知识分类、无简单总优先级、owner 持久化和防事实→政策洗白; - D-02 单一定义点、结构引用边界和 `schema_version` 语义; - D-05 两轮严格 `PASS_NOOP`; - 与 DEC-006 的 refine 关系; - 不修改 `sync_docs.py`、不新增 parser/ledger/receipt。 日期使用 owner 接受本决策进入候选的 UTC 日期,不使用未来 merge date。未接受前状态为 `proposed`。 不把 PR #19 的四条执行 gate 或 supplemental suite 历史顺手塞入 DEC-007;它们若需要长期决策记录,另立 finding/DEC。 ## 4.8 `zh/skills/workflow-docs-sync/evals/README.md` 扩展现有 Case A: ### Round 1 mandatory checks - 在编辑前从真实 SEC target 中至少选择并记录: - 三条当前 scoped normative policy(例如 fail-fast、具体异常、显式数据契约); - 两条描述性强声明; - 每条的分类、authority/evidence、scope、冲突和预期处置。 - 静默删除已分类政策:FAIL。 - 把描述性事实改写为祈使句以保留:FAIL。 - 对 policy 的修改/保留都记录 authority source;不注入人工 fixture。 - 核对 publisher/consumer:contract canonical grammar 对照 SEC checker 的真实 regex;记录 checker 只支持 canonical form且不穷举 alias。 - 记录 SEC 的 `ENTRY_STATUSES={active, deprecated}` 是项目侧加严,不要求模板改写为同一词表。 - 核对目标 TESTING 的 bug-first/no-test-diff 规则,正确且更具体的内容保持零 diff。 ### Alignment consumer validation SEC checker要求 evidence path 与工作树匹配 HEAD。为避免改变主 Case A target identity: 1. 在 primary Case A worktree 完成 round 2 `PASS_NOOP` 后冻结九文档 bytes/digest; 2. 从同一 SEC base 新建第二个 disposable validation checkout; 3. 应用完全相同的九文档候选并创建 test-only commit; 4. 运行: ```bash python3 tools/check_capability_contract_alignment.py --base-ref <SEC_BASE_SHA> ``` 5. 记录 derived validation commit、命令、结果和 cleanup;不得把 derived commit 冒充 primary target identity 或发布 commit。 ### Round 2 按 D-05 只接受 `PASS_NOOP`。有效新增修正和纯表达漂移都使 gate FAIL,并从 clean target 重跑两轮。 ### Formal raw records Case G/A raw record绑定 candidate SHA、URL、record SHA-256、exact prompt、命令、files/digest 和 verdict。 ## 4.9 `tests/test_workflow_docs_sync.py` 扩展现有 `test_scenario_5_repository_distribution_contract`: - 每语言九模板中 literal `<!-- capability-anchor: <ANCHOR_ID> -->` 恰出现一次; - 唯一位置是 `capability_contract.json.rules`; - `TESTING.md`、Checklist、Skill 不复写 token,只保留语义指针(不对整段散文做 exact assertion); - contract rule包含 case-sensitive ID grammar 和 `untested_reason` + `pending_since` 的共同要求;只 pin公开协议关键词,不 pin整段文案; - PR template包含稳定合同标识 `first-seen`、`reopened`、`superseded`、`unknown`; - 不增加第三种 active project-fill marker; - 九模板 LF/UTF-8/active-marker、Skill structure、CLI `{prepare,check}` 等现有合同不回归。 不修改 `sync_docs.py`、installer 或 CLI schema。 ## 4.10 英文同步 同步: - `en/AGENTS.md` - `en/capability_contract.json` - `en/TESTING.md` - `en/.github/pull_request_template.md` - `en/PR_Checklist.md` - 英文 development workflow 摘要 Canonical token、ID grammar 和 lifecycle identifiers 不翻译;语义必须等价。 --- ## 5. 实施顺序 1. 重新读取 `coding-workflow/main` 和 `SEC_metrics/main`;记录实际 SHA。确认 PR #19 已在 base 中。 2. 不修改文件,先登记五个 findings:policy classification、anchor publisher/consumer、test-decision、finding lifecycle、round-2 convergence。 3. 冻结 DEC-007 为 `proposed`;用户/owner接受后改为 `accepted` 并使用接受日期。 4. 修改 canonical Skill 和 `zh/` 模板。 5. 同步 `en/`。 6. 修改 distribution contract 测试和 eval contract。 7. 运行定向测试、全量 pytest、py_compile、Skill quick validation、diff checks、CLI help。 8. Fresh-context review;修复 BLOCKER/actionable WARN并重跑受影响机械测试。 9. 在最终 coding-workflow candidate SHA 上运行 Case G。 10. 冻结当时的 SEC main。已独立批准的 SEC 修复若要合并,应在此步之前完成;不得仅为让 Case A no-op 而预先美化目标。 11. Case A round 1:真实调查、分类、最小改写、真实测试、review、final check。 12. 冻结 round 1 九文档 bytes/digest;fresh context 执行 round 2。只有 `PASS_NOOP` 可继续。 13. 若 round 2 为 `ROUND1_INCOMPLETE` 或 `ROUND2_DRIFT`,修复候选/协议,从 clean SEC base 重新执行步骤 11–12。 14. 在 derived disposable SEC validation checkout 提交相同文档候选,运行 alignment checker并清理。 15. 最终 independent review,记录 reviewer identity、隔离边界和 raw record digest。 16. 完成 PR body:所有 failure/reopen/superseded evidence、promoted rule、known limits、no-update reasons。 17. 只有用户明确要求时 commit、push、创建 draft PR。 本核心 PR不以新 eval runner、XDG test、supplemental suite DEC、SEC 已知文档 PR为前置依赖。 --- ## 6. 最低验证 ### coding-workflow ```bash PYTHONDONTWRITEBYTECODE=1 \ python3 -m pytest -q -p no:cacheprovider tests/test_workflow_docs_sync.py ``` ```bash PYTHONDONTWRITEBYTECODE=1 \ python3 -m pytest -q -p no:cacheprovider ``` ```bash PYTHONDONTWRITEBYTECODE=1 \ python3 -m py_compile \ zh/skills/workflow-docs-sync/scripts/sync_docs.py \ zh/scripts/install_skills.py \ tests/test_workflow_docs_sync.py ``` ```bash PYTHONDONTWRITEBYTECODE=1 \ python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" \ zh/skills/workflow-docs-sync ``` ```bash git diff --check git diff --cached --check python3 zh/skills/workflow-docs-sync/scripts/sync_docs.py --help ``` ### SEC Case A 按冻结时目标 `TESTING.md` 选择真实命令。至少包括: - 目标仓库要求的快速/相关完整回归; - primary worktree 的 WDS final `check`; - derived committed validation checkout 的: ```bash python3 tools/check_capability_contract_alignment.py --base-ref <SEC_BASE_SHA> ``` 每条记录 exact command、interpreter、scope、result、not-run reason、side effects、isolation 和 cleanup。 --- ## 7. 验收标准 ### AC-01|语义分类 Skill按语义区分描述性事实、规范性政策、个人偏好和混合句,不按祈使/陈述语法机械分类。 ### AC-02|政策双向安全 Case A 对当前 SEC 至少三条真实政策逐项记录 disposition;无静默删除。至少一条描述性强声明不能通过改写为“必须”逃避证据核验。 ### AC-03|政策持久化边界 本轮 task instruction 不会自动成为长期政策;只有明确采纳并写入 repository authority 的 owner decision 可跨轮保留。 ### AC-04|Anchor 单一定义 每语言 canonical token 在九模板中恰出现一次且只位于 contract rules;大小写、ID grammar 与 SEC consumer一致。 ### AC-05|Alias 诚实边界 文档明确非 canonical form不受支持,但不声称当前 consumer穷举拒绝所有 alias;没有为了假想 alias 新增黑名单/parser。 ### AC-06|结构引用边界 Alignment PASS明确只证明结构引用、合法 ID、非悬空等机械事实,不冒充句子级绑定或能力语义证明。 ### AC-07|Null test metadata `test_anchor: null` 的 contract entry同时要求非空 `untested_reason` 与 `pending_since`。 ### AC-08|测试决策执行 TESTING含最低规则,Checklist明确核对新增/不新增测试的决策;无 test diff 有具体覆盖证据。 ### AC-09|Finding 生命周期 Finding ID/reopen 与 candidate/evidence superseded 分离;漏检原因可为 evidence-backed、hypothesis 或 unknown,不得编造。 ### AC-10|长期教训桥接 Material finding被评估是否提升到合适权威/自动化;没有跨 PR事故 ledger。 ### AC-11|严格收敛 最终 Case A round 2为 `PASS_NOOP`。任何有效新增修正或纯表达漂移都使两轮 gate失败并从 clean target重跑。 ### AC-12|真实消费者闭环 Derived SEC validation checkout运行真实 alignment checker;记录 publisher、consumer、actual command、project-specific tightening和结构边界。 ### AC-13|无生产扩张 `sync_docs.py`、installer、CLI schema零功能变化;CLI仍只有 `{prepare,check}`。 ### AC-14|双语和现有场景 中英文语义等价;现有五个公开 scenario、安装器、marker、whitespace/Git gate全部通过。 ### AC-15|证据不可擦除 PR body保留 material failure、reopen、superseded candidate/evidence;正式 raw record绑定 SHA、URL和digest。 --- ## 8. 明确不做与独立 backlog ### 核心 PR 不做 - 恢复完整三文档关系章节或旧十条规范; - 强制 PEP 8、禁止 `get`、每函数注释; - 通用 Mermaid 假图; - 固定 PowerShell runner、`/healthz`、Stage和测试目录; - 仓库内 PR_BODY、单 commit/amend/force-with-lease; - anchor alias黑名单或 claim-level binding parser; - 新 marker、run state、ledger、receipt、migration registry; - `sync_docs.py`功能修改; - 给每条旧政策强制 owner重新确认; - 为 Case A注入人工政策 fixture。 ### 独立 backlog(不因“顺手改同一文件”自动搭车) 1. XDG default attributes whitespace负例; 2. supplemental suite是否登记为长期 merge contract; 3. PR #19执行 gate是否需要单独 DEC; 4. 可复用 eval recorder/runner; 5. 已认可但尚未发布的 SEC文档修复; 6. Architecture真实 Mermaid指引; 7. SOP膨胀诊断语; 8. 用户个人代码哲学的 user-level agent instruction。 每项都需独立 finding、真实消费者/失败路径和范围验收。 --- ## 9. 仍需评审重点挑战的问题 1. D-01 对 tracked governance entry 的“推定有效”是否足够防误删,同时不会让明显个人残留永久化?是否需要更精确的 ambiguity 判据? 2. D-02 的“非 canonical 不受支持但不保证穷举拒绝”是否是当前 publisher/consumer 的诚实边界? 3. `test_anchor: null` 同时要求两个字段是否应只约束显式使用该 key 的 entry,而不要求所有 document entry增加 test metadata?本方案答案是“是”。 4. `schema_version` 仅表示 JSON shape的定义是否可接受?若反对,请指出真实消费者如何按 authoring-rule version分支。 5. Case A derived committed validation checkout是否是运行 SEC checker且不破坏 primary target identity的最小方案? 6. D-05 严格 no-op是否需要任何例外?本方案认为 target/live identity变化只会使证据失效并重跑,不构成 PASS例外。 7. D-04 的 lifecycle词表是否过度约束下游 PR风格?若需收窄,应至少保留 stable ID、reopen event和evidence superseded的语义边界。 --- ## 10. PR body 最终必须包含 - actual base/head/tree SHA; - 五个 finding ID及 first-seen/reopen/closure; - DEC-007状态和接受日期; - 逐文件真实范围与 no-update reasons; - D-01 policy classification table和 SEC真实样本 disposition; - Anchor publisher/consumer/grammar/limitations; - test-anchor null两字段语义; - D-03新增/不新增测试决策; - Case G、Case A round 1/2和 derived alignment raw records; - `PASS_NOOP` 证据; - independent reviewer identity/隔离证据; - promoted reusable rule或 None; - known limits和独立 backlog; - 明确说明 `sync_docs.py` / installer是否零 diff。 --- ## 11. 最终裁定 核心 PR现在做五件事: 1. 给事实、政策和个人偏好建立双向、不可洗白的证据边界; 2. 发布唯一且不夸大真实消费者能力的 capability anchor协议; 3. 恢复跨项目最低测试决策并接到 PR执行门; 4. 让 finding重开、证据 superseded和长期教训提升可见且诚实; 5. 把 Case A第二轮从“补漏也可 PASS”改成严格收敛门。 它不恢复 PR #18 删除的项目特定假设,也不借“顺手改同一文件”扩张新机制。
明确不纳入核心 PR
anchor:/ref:/contract:黑名单;当前没有真实 alias 命中证据,且 checker 目前只保证 canonical directive 的提取和 malformed-canonical 检测。capability_contract.json.schema_version;本方案冻结该字段只表示 JSON 数据形状/必需字段,不表示所有 authoring prose 规则的修订版本。1. 背景与当前事实
PR #18 正确把
zh//en/从带有个人偏好、Python/PowerShell 假设和示例能力的“万能项目规范”,重构为需要根据目标仓库事实项目化的下游模板。当前主干已经具备以下正确边界:
prepare/check只承担固定 object、目标 HEAD、dirty allowlist、文件形状、UTF-8、active marker 和 whitespace 等机械事实;capability_contract.json → interact.md → docs/business_user_guide.md保持单向权威;当前仍存在五个可复现或有真实消费者的缺口。
G-01|事实与政策没有完整的双向分类规则
Skill 仍有“删除没有当前事实证据的强声明”。这会误伤无法从代码反推、但由目标仓库明确制定的规范性政策;反方向上,Agent 也可能把过时事实改写成“必须……”来规避事实核验。
真实消费者:SEC_metrics 的 tracked
AGENTS.md已含 fail-fast、具体异常、显式数据契约等 owner-declared 项目政策。G-02|Anchor 消费者存在,发布者未正式定义协议
coding-workflow当前双语模板中没有capability-anchor定义;SEC_metrics checker 已硬编码:同时,当前 checker 只检测 canonical
capability-anchor:的 malformed form;<!-- anchor: ... -->等非 canonical 文本通常只是不可见,并不会被穷举拒绝。因此上游不能声称真实消费者已经实现“所有 alias 必败”。G-03|跨项目最低测试决策只剩空 marker
TESTING.md §4没有固定最低规则;PR Checklist 只要求记录命令和结果,没有要求解释“为什么这次需要或不需要 test diff”。G-04|Finding 闭环缺少生命周期与证据状态边界
当前模板有 finding ID、severity、证据、修复、复核,但没有精确定义 first-seen、reopen、candidate/evidence superseded 以及无法解释漏检原因时如何诚实记录。
G-05|两轮 Case A 允许第一轮漏检后仍整体 PASS
DEC-006/当前 eval 允许第二轮因“新增项目事实”做最小改写。若 target 代码、配置、测试和 committed artifacts 身份没有变化,第二轮发现有效修正说明第一轮调查不完整;继续 PASS 会把“第二轮兜底”误写为“两轮收敛”。PR #18 round 2 已出现同一 identity 下再次发现文档错误并仍 PASS 的现实样本。
2. 核心原则
P-01|不回滚 PR #18
不恢复旧十条代码规范、固定 runner、固定测试目录、通用假 Mermaid、样例能力、逐文件测试索引、仓库内 PR body 或单 commit/amend 发布政策。
P-02|按语义分类,不按句式分类
祈使句不自动是政策,陈述句也不自动是事实。含“当前实现必须……”等混合语义时,拆分规范意图与现状断言分别核验。
P-03|Enforcement 与 intent 不建立简单总排序
机器配置证明当前实际 enforcement;accepted decision、scoped governance instruction 证明规范意图。两者冲突是治理漂移,应形成 finding/open decision,而不是静默让一方“胜出”。
P-04|一个协议一个定义点
Canonical anchor token 只在
capability_contract.json.rules定义。TESTING.md、Checklist 和 Skill 只指向该协议,不复写 token。P-05|不扩张
sync_docs.py本 PR 不增加 anchor parser、policy parser、PR history receipt、Markdown parser 或新 CLI。
P-06|现实 eval 不注入已知缺陷
SEC Case A 使用真实仓库事实。需要机械正负例时放在现有 repository distribution contract 或目标项目自己的 checker 测试中,不把真实 Case A 变成人工 fixture 测试。
P-07|第二轮证明收敛,不承担第一轮补漏
同一 identity 的第二轮只接受
PASS_NOOP。任何有效新增语义修正都使两轮 gate 失败并要求重跑。P-08|中文为语义源,英文等价派生
先改
zh/和 canonical Skill,再同步en/;英文不得独立加强或弱化合同。3. 决策冻结
D-01|描述性事实、规范性政策与个人偏好
3.1 分类规则
3.2 防证据洗白
3.3 政策权威与冲突
3.4 可审查记录
保留、修改或不更新一条 material policy 时,finding/no-update reason 应指出其权威来源、作用域和冲突检查结果。
D-02|Canonical capability anchor 协议
3.5 唯一 authoring form
<!-- capability-anchor: <ANCHOR_ID> -->ANCHOR_ID大小写敏感;ANCHOR_IDgrammar:[A-Za-z0-9_.-]+;3.6 非 canonical 形式的边界
capability-anchordirective 建立受支持的 contract reference。anchor:、ref:、contract:、wiki link 等其他形式不受支持,不能被当作已完成的 alignment 引用。3.7 结构引用边界
Anchor 证明“本文档引用了某个 contract entry”,不证明某一句自然语言与该 entry 精确绑定,也不证明 statement 的业务语义已经实现。Claim-level binding 若未来需要,必须单独设计,不在本 PR 顺手扩张。
3.8
test_anchor: null当一个 contract entry 显式使用
test_anchor: null时,必须同时包含:untested_reason;pending_since。这表示覆盖缺口已登记,不表示 claim 已自动验证。模板不在本 PR 强制
pending_since的跨项目日期解析格式;目标 checker可以加严。3.9 单一定义点和版本
capability_contract.json.rules。TESTING.md和 Checklist 只指向 contract-defined protocol,不复写 token。schema_version保持0.1.0。DEC-007 明确:该字段描述 JSON 数据形状/必需字段,不为纯 authoring prose 修订升级;未来 shape 或机器必需字段变化再按版本策略调整。D-03|跨项目最低测试决策
3.10 Canonical entrypoint(只放 §0)
该规则不在 §4 重复。
3.11 Change Type → Required Evidence
3.12 PR 执行点
PR_Checklist.md必须检查“新增或不新增测试”的决策是否符合TESTING.md §4,而不仅是命令是否被记录。D-04|Finding 生命周期、证据状态与教训提升
3.13 Finding
OPEN、CLOSED、DEFERRED;REOPENED是生命周期事件,不是新 finding;重开保留原 ID并追加新证据。3.14 Candidate / evidence
CURRENT/SUPERSEDED描述候选或证据,不描述 finding 本身;3.15 返工原因
实质返工时说明上一轮 review/gate 未发现的原因。解释必须:
hypothesis;或unknown。不得为了填字段编造因果。
3.16 长期教训
PR closure 时评估 material finding 是否揭示缺失的可复用决策规则:
TESTING.md、SOP.md、DEC、项目治理入口或自动化 gate),并在 PR body 索引;None — no reusable rule identified,不写事故编年史。TESTING.md §8增加:同一失效模式合并为更一般的规则;只有知识被更强测试、自动化 gate 或权威规则完整接管时才退役,不能只因案例变旧删除。D-05|Case A 两轮严格收敛
3.17 固定身份
两轮必须使用相同:
Live 外部状态变化或 target identity 变化使本次两轮证据失效,必须重新冻结并重跑。
3.18 判定
PASS_NOOP:round 2 重新调查、重新选择测试和重新 review 后,九文档相对 round 1 最终候选零 diff,且无 staged/untracked/ignored residue。ROUND1_INCOMPLETE:round 2 发现由冻结 target 中原已存在的代码/配置/测试/artifact 反证支持的有效新增修正。说明 round 1 漏检;整个两轮 gate FAIL。ROUND2_DRIFT:只有措辞、排序、格式或偏好变化,无新增反证。说明最小改写不稳定;整个 gate FAIL。ROUND1_INCOMPLETE或ROUND2_DRIFT后,修复候选/调查协议,从 clean target 重新运行完整 round 1 + round 2;不得只补第三轮把前两轮改判为 PASS。4. 文件级实施
4.1
zh/skills/workflow-docs-sync/SKILL.md在
## 重建事实并最小改写中、PR #19 的写入前 finding 规则之前加入 D-01 分类与冲突处理。替换:
- 删除没有当前事实证据的强声明。需要产品判断时记录 open decision,不编造结论。为:
- 删除、收窄或降级没有当前证据的描述性强声明;规范性政策按政策权威、作用域和冲突 处理。不得把事实改写为政策以规避证据,也不得把政策伪装成实现事实。需要产品判断时 记录 open decision,不编造结论。Finding/no-update reason 对 material policy 记录 authority source 与 scope。
4.2
zh/AGENTS.md只修改
Project-specific Conventionsmarker:不恢复旧代码规范,不增加完整三文档关系块。
4.3
zh/capability_contract.jsonrules中以一条规则发布 canonical token、case sensitivity、ID grammar、空白 tolerance 和禁止 JSON path。untested_reason与pending_since。schema_version: 0.1.0。4.4
zh/TESTING.md4.5
zh/.github/pull_request_template.md§7 注释加入:
Promoted reusable rule: <authority / None>。不预置空 ledger 表,不建立仓库内记录文件。
4.6
zh/PR_Checklist.md增加:
TESTING.md §4;无 test diff 时有具体覆盖测试和重跑证据。4.7
zh/docs/development_workflow/decisions.md新增
DEC-007,记录:schema_version语义;PASS_NOOP;sync_docs.py、不新增 parser/ledger/receipt。日期使用 owner 接受本决策进入候选的 UTC 日期,不使用未来 merge date。未接受前状态为
proposed。不把 PR #19 的四条执行 gate 或 supplemental suite 历史顺手塞入 DEC-007;它们若需要长期决策记录,另立 finding/DEC。
4.8
zh/skills/workflow-docs-sync/evals/README.md扩展现有 Case A:
Round 1 mandatory checks
ENTRY_STATUSES={active, deprecated}是项目侧加严,不要求模板改写为同一词表。Alignment consumer validation
SEC checker要求 evidence path 与工作树匹配 HEAD。为避免改变主 Case A target identity:
PASS_NOOP后冻结九文档 bytes/digest;Round 2
按 D-05 只接受
PASS_NOOP。有效新增修正和纯表达漂移都使 gate FAIL,并从 clean target 重跑两轮。Formal raw records
Case G/A raw record绑定 candidate SHA、URL、record SHA-256、exact prompt、命令、files/digest 和 verdict。
4.9
tests/test_workflow_docs_sync.py扩展现有
test_scenario_5_repository_distribution_contract:<!-- capability-anchor: <ANCHOR_ID> -->恰出现一次;capability_contract.json.rules;TESTING.md、Checklist、Skill 不复写 token,只保留语义指针(不对整段散文做 exact assertion);untested_reason+pending_since的共同要求;只 pin公开协议关键词,不 pin整段文案;first-seen、reopened、superseded、unknown;{prepare,check}等现有合同不回归。不修改
sync_docs.py、installer 或 CLI schema。4.10 英文同步
同步:
en/AGENTS.mden/capability_contract.jsonen/TESTING.mden/.github/pull_request_template.mden/PR_Checklist.mdCanonical token、ID grammar 和 lifecycle identifiers 不翻译;语义必须等价。
5. 实施顺序
coding-workflow/main和SEC_metrics/main;记录实际 SHA。确认 PR docs(workflow): close supplemental qualification gaps #19 已在 base 中。proposed;用户/owner接受后改为accepted并使用接受日期。zh/模板。en/。PASS_NOOP可继续。ROUND1_INCOMPLETE或ROUND2_DRIFT,修复候选/协议,从 clean SEC base 重新执行步骤 11–12。本核心 PR不以新 eval runner、XDG test、supplemental suite DEC、SEC 已知文档 PR为前置依赖。
6. 最低验证
coding-workflow
PYTHONDONTWRITEBYTECODE=1 \ python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" \ zh/skills/workflow-docs-syncSEC Case A
按冻结时目标
TESTING.md选择真实命令。至少包括:check;每条记录 exact command、interpreter、scope、result、not-run reason、side effects、isolation 和 cleanup。
7. 验收标准
AC-01|语义分类
Skill按语义区分描述性事实、规范性政策、个人偏好和混合句,不按祈使/陈述语法机械分类。
AC-02|政策双向安全
Case A 对当前 SEC 至少三条真实政策逐项记录 disposition;无静默删除。至少一条描述性强声明不能通过改写为“必须”逃避证据核验。
AC-03|政策持久化边界
本轮 task instruction 不会自动成为长期政策;只有明确采纳并写入 repository authority 的 owner decision 可跨轮保留。
AC-04|Anchor 单一定义
每语言 canonical token 在九模板中恰出现一次且只位于 contract rules;大小写、ID grammar 与 SEC consumer一致。
AC-05|Alias 诚实边界
文档明确非 canonical form不受支持,但不声称当前 consumer穷举拒绝所有 alias;没有为了假想 alias 新增黑名单/parser。
AC-06|结构引用边界
Alignment PASS明确只证明结构引用、合法 ID、非悬空等机械事实,不冒充句子级绑定或能力语义证明。
AC-07|Null test metadata
test_anchor: null的 contract entry同时要求非空untested_reason与pending_since。AC-08|测试决策执行
TESTING含最低规则,Checklist明确核对新增/不新增测试的决策;无 test diff 有具体覆盖证据。
AC-09|Finding 生命周期
Finding ID/reopen 与 candidate/evidence superseded 分离;漏检原因可为 evidence-backed、hypothesis 或 unknown,不得编造。
AC-10|长期教训桥接
Material finding被评估是否提升到合适权威/自动化;没有跨 PR事故 ledger。
AC-11|严格收敛
最终 Case A round 2为
PASS_NOOP。任何有效新增修正或纯表达漂移都使两轮 gate失败并从 clean target重跑。AC-12|真实消费者闭环
Derived SEC validation checkout运行真实 alignment checker;记录 publisher、consumer、actual command、project-specific tightening和结构边界。
AC-13|无生产扩张
sync_docs.py、installer、CLI schema零功能变化;CLI仍只有{prepare,check}。AC-14|双语和现有场景
中英文语义等价;现有五个公开 scenario、安装器、marker、whitespace/Git gate全部通过。
AC-15|证据不可擦除
PR body保留 material failure、reopen、superseded candidate/evidence;正式 raw record绑定 SHA、URL和digest。
8. 明确不做与独立 backlog
核心 PR 不做
get、每函数注释;/healthz、Stage和测试目录;sync_docs.py功能修改;独立 backlog(不因“顺手改同一文件”自动搭车)
每项都需独立 finding、真实消费者/失败路径和范围验收。
9. 仍需评审重点挑战的问题
test_anchor: null同时要求两个字段是否应只约束显式使用该 key 的 entry,而不要求所有 document entry增加 test metadata?本方案答案是“是”。schema_version仅表示 JSON shape的定义是否可接受?若反对,请指出真实消费者如何按 authoring-rule version分支。10. PR body 最终必须包含
PASS_NOOP证据;sync_docs.py/ installer是否零 diff。11. 最终裁定
核心 PR现在做五件事:
它不恢复 PR #18 删除的项目特定假设,也不借“顺手改同一文件”扩张新机制。