GitNexus evidence-provenance Schema 2 深度解析：为 AI 生成计划建立可验证的证据指纹与安全写入契约-港品优选

GitNexus evidence-provenance Schema 2 深度解析：为 AI 生成计划建立可验证的证据指纹与安全写入契约

【免费下载链接】GitNexusGitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a git repository (Github, Gitlab, Azure, Local) or ZIP file, and get an interactive knowledge graph with a built in Graph RAG Agent. Perfect for code exploration项目地址: https://gitcode.com/GitHub_Trending/gi/GitNexus

导读：本文讲解 GitNexus 中gitnexus-plan/gitnexus-work双技能共用的证据溯源（evidence provenance）Schema 2规范及其配套可执行脚本。它解决一个真实工程问题——AI 规划器产出的"变更计划"文档如何携带可审计的仓库证据（谁被引用、HEAD/index/工作区分别是什么内容、整棵树脏状态的总摘要），以及这些计划文件如何被原子、防竞态、防符号链接攻击地写入与读取。读完本文，你将掌握read-plan/snapshot/write-plan三个子命令的完整用法、路径与字节级契约、Linux 与 macOS 两套差异化的目录描述符锚定机制，以及 canonical bytes 的精确帧格式。

一、什么是 evidence provenance Schema 2

在 GitNexus 的规划技能体系中，gitnexus-plan负责把一项工程任务加工成"可直接实施"的计划文档，而gitnexus-work负责按 §7 实施序列逐条落地。两者之间传递的不仅是自然语言章节，还有一份机器可读的§11 Implementation Context 包，其中evidence_provenance字段是强制项——它是证明"这份计划针对的是哪一棵确切的仓库状态"的唯一依据。

.claude/skills/gitnexus-plan/references/evidence-provenance.md 是这份规范文档（normative byte contract），它声明：

相邻的 scripts/evidence-provenance.mjs 是规范的可执行定义（共 2366 行）；
gitnexus-plan与gitnexus-work各自携带字节完全一致的副本（.mjs 与 .md 均经 md5sum 校验一致），任一技能都能独立产出相同快照，无需依赖另一技能是否安装；
该 helper 是生成计划唯一受支持的写入边界——严禁用临时 shell 管道自行重算摘要，或直接写计划目标路径。

四个字节级副本位于仓库中，互为镜像：

副本位置	内容
`.claude/skills/gitnexus-plan/references/evidence-provenance.md`	规范文档
`.claude/skills/gitnexus-plan/scripts/evidence-provenance.mjs`	可执行定义
`.claude/skills/gitnexus-work/references/evidence-provenance.md`	规范文档（与上同 md5）
`.claude/skills/gitnexus-work/scripts/evidence-provenance.mjs`	可执行定义（与上同 md5）
`gitnexus/skills/gitnexus-plan/{references,scripts}/…`	打包进发行技能的副本
`gitnexus/skills/gitnexus-work/{references,scripts}/…`	打包进发行技能的副本

核心原则在 SKILL.md 中重复强调：

Pin working-tree evidence, not only HEAD：每个计划形态都携带带版本号的 global dirty digest 与按路径排序的 cited-path manifest；
Write the plan only through the helper：先在仓库外 scratchpad 组合完整 UTF-8 文档，再通过 stdin 交给write-plan；
Read an existing plan only through the helper：Deepen 必须调用read-plan，且只用回执中解码出的精确字节。

Schema 1 被有意废弃。执行器一旦遇到 schema 1 计划，必须保守地将其重新锚定到 schema 2 之下（evidence-provenance.mjs 中snapshot命令对非 2 的--schema-version直接抛错：Unsupported evidence provenance schema 1; schema 1 is legacy and must be conservatively re-anchored）。

二、三个子命令的 CLI 契约

在目标仓库根目录，运行当前技能目录下的 helper：

node <skill-dir>/scripts/evidence-provenance.mjs read-plan \ --repo "$PWD" \ --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md

<skill-dir>在本仓库中对应.claude/skills/gitnexus-plan（或gitnexus-work、gitnexus/skills/...下的镜像副本），取决于当前激活的技能。

parseCli（源码 evidence-provenance.mjs）对每个子命令严格白名单校验允许的选项：

子命令	允许选项	输出
`read-plan`	`--repo`,`--generated-plan`	JSON 回执：`generated_plan_path`、`bytes_read`、`plan_digest`、`plan_bytes_base64`
`snapshot`	`--repo`,`--generated-plan`,`--cited`（可多次）,`--schema-version`	完整`evidence_provenance`JSON 值
`write-plan`	`--repo`,`--generated-plan`,`--replace`,`--expected-plan-path`,`--expected-plan-digest`	JSON 回执：`generated_plan_path`、`bytes_written`；Deepen 时附加`prior_plan_backup_git_path`

解析器会拒绝：未知选项、重复选项（--cited除外）、缺失值、多余的位置参数；--repo与--generated-plan为必填。

2.1 read-plan：唯一受支持的计划读取方式

node <skill-dir>/scripts/evidence-provenance.mjs read-plan \ --repo "$PWD" \ --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md

它是 Deepen（强化已有计划）或执行计划时加载既有计划的唯一途径。回执携带规范的generated_plan_path、bytes_read、精确的plan_bytes_base64与plan_digest（格式sha256:<hex>）：

{ "generated_plan_path": "docs/plans/2026-07-11-gitnexus-plan-ingestion-retry.md", "bytes_read": 18273, "plan_digest": "sha256:2c…（64 位小写十六进制）", "plan_bytes_base64": "…" }

调用方必须解码并消费这些精确字节，绝不重新打开词法路径；并需在整个 Deepen 会话期间把规范路径与摘要绑定保留——一份路径的回执永远不能授权另一份路径，即使两者字节完全相同。

2.2 snapshot：生成 evidence_provenance 值

node <skill-dir>/scripts/evidence-provenance.mjs snapshot \ --repo "$PWD" \ --schema-version 2 \ --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md \ --cited src/one.ts \ --cited test/one.test.ts

每一个被引用的路径都要传一个--cited参数；
脚本输出完整的evidence_provenanceJSON 值，调用方需原样拷贝、绝不改写字段；
gitnexus-work在重锚定时会传入计划的schema_version、generated_plan_path，以及cited_path_manifest中的每个路径。

产出值结构（源码 evidence-provenance.mjs）：

{ "schema_version": 2, "head_commit": "<HEAD 完整 SHA>", "generated_plan_path": "docs/plans/…", "global_dirty_digest": { "algorithm": "sha256", "canonicalization": "gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records", "value": "<64 位小写 hex，无 sha256: 前缀>" }, "cited_path_manifest": [] }

gitnexus-work的 SKILL（SKILL.md）要求执行前做双层漂移检查（two-layer drift check）：即使当前 HEAD 与计划 pin 相同，也要同时重算全局 dirty digest 与 cited-path manifest，Schema 1 无法无歧义重算，必须保守重锚。

2.3 write-plan：唯一受支持的计划写入方式

计划文档完全组合好之后，通过 helper 发布其精确 UTF-8 字节：

node <skill-dir>/scripts/evidence-provenance.mjs write-plan \ --repo "$PWD" \ --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md \ < /path/to/outside-repo-scratch-plan.md

标准输入必须是合法 UTF-8，且至多 16 MiB（常量MAX_PLAN_BYTES = 16 * 1024 * 1024，见 evidence-provenance.mjs，readStdinBounded在超过时直接抛错）；
成功的写入会打印含规范化generated_plan_path与bytes_written的 JSON 回执；
helper 会安全地创建缺失的父目录；
初始规划绝不传--replace——目标已存在即为错误（写入采用 no-replace 原语）；
write-plan命令拒绝了所有与其所选命令不匹配的选项；直接 API 同样要求字面量布尔值与精确摘要字符串，而非真值强制转换（requireBoolean/normalizeSha256Digest于 evidence-provenance.mjs）。

2.4 write-plan --replace：仅 Deepen 模式可用

node <skill-dir>/scripts/evidence-provenance.mjs write-plan \ --repo "$PWD" \ --generated-plan docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md \ --replace \ --expected-plan-path docs/plans/YYYY-MM-DD-gitnexus-plan-example-change-plan.md \ --expected-plan-digest 'sha256:<digest-from-read-plan>' \ < /path/to/outside-repo-scratch-plan.md

Deepen 流程的语义链是：

先用read-plan取得规范路径与摘要；
原地重写同一路径时附加--replace、--expected-plan-path <generated_plan_path-from-read-plan>、--expected-plan-digest <plan_digest-from-that-same-receipt>；
成功写入会额外返回prior_plan_backup_git_path——一个指向被顶替旧计划的、位于 Git 管理目录下的持久备份路径。

校验约束（源码 evidence-provenance.mjs）：

--replace必须同时携带--expected-plan-path与--expected-plan-digest，二者缺一即错；
未传--replace却携带这两个 expected 参数同样报错；
期望路径必须与写入目标逐字节相等——一个计划的相同字节不能授权另一个计划；
期望路径只能指向已存在的普通文件，不接受符号链接或其他类型。

三、路径契约：谁可以被读写

所有 Git 路径与 CLI 路径必须满足（normalizeRepoPath，evidence-provenance.mjs）：

合法 UTF-8，且已规范化为Unicode NFC；
非空的POSIX 仓库相对路径；
拒绝：NUL、反斜杠、绝对路径 / 盘符（/开头或/^[A-Za-z]:\//）、空组件、.或..组件；也拒绝无法往返编码的非法 Unicode 标量值。

helper不做静默修复或别名化。以下情况一律 fail closed：来自 Git 的非法 UTF-8、非 NFC 名称、索引未合并阶段（unmerged stages）、不支持的 Git 模式、socket/设备/FIFO、不可读对象、父路径组件中的符号链接穿越、快照期间观察到的仓库变更。

generated-plan 路径的命名约束是双重的：

Schema 2 下计划路径永远是仓库相对路径；
快照排除与写入要求精确匹配docs/plans/YYYY-MM-DD-gitnexus-plan-<3-5-word-kebab-slug>.md，且必须是合法日历日期（写入正则见源码GENERATED_PLAN_WRITE_PATTERN，并做new Date(...)回环校验：非法日期如2026-02-30会被拒绝）：
```
/^docs\/plans\/(\d{4}-\d{2}-\d{2})-gitnexus-plan-[a-z0-9]+(?:-[a-z0-9]+){2,4}\.md$/
```
它们不能指向.git、源码、配置文件或任意仓库文件；
读取侧（GENERATED_PLAN_READ_PATTERN）为兼容文档化历史计划，接受规范化的docs/plans/*gitnexus-plan*.md，但保持同样的描述符锚定包含性检查；该读取兼容性不会放宽写入器；
外部输出（仓库外路径）没有 Schema 2 表示——写入不允许 external 路径；
快照的排除是一次精确规范化路径比较（源码 evidence-provenance.mjs：.filter((record) => record.path !== generatedPlan)）——不允许 glob、目录、basename 或docs/plans/全目录排除；若精确路径是重命名端点，则仅排除该端点记录。

四、安全的既有计划读取契约（read-plan）

read-plan采用fail-closed策略：除非宿主机平台能基于持有的目录描述符解析名称，否则拒绝读取：

Linux：/proc/self/fd配合O_DIRECTORY与O_NOFOLLOW；
macOS：O_DIRECTORY/O_NOFOLLOW；
其它平台一律拒绝——未经验证的读取不是"降级读取"，而是另一种带竞态的、不同的操作。

读取流程（对应 read-plan 实现与规范 L99-L111）：

解析出精确的 Git top-level；
以持有的 no-follow 目录描述符打开仓库根目录及每一级计划父目录；
拒绝缺失、符号链接、非目录与逃逸的父目录；
以O_NOFOLLOW打开叶子文件；
从持有的文件描述符读取至多 16 MiB，要求合法 UTF-8，对精确字节做哈希；
返回回执前，证明父链与词法叶子仍指向同一批持有的对象。

无论是 Deepen 还是 work 执行，都不得解析此回执之前或之外获得的字节。规范原文对此的态度非常明确：一份字节不匹配就换路径读取、或把 A 计划的摘要套到 B 计划上，都是被禁止的。

五、安全的 generated-plan 写入契约（write-plan）

写入器的安全前提（requireDescriptorAnchoring，evidence-provenance.mjs）：

宿主机必须提供O_DIRECTORY与O_NOFOLLOW；
Linux 还必须存在/proc/self/fd；
不 spawn 任何解释器、不加载任何原生代码：发布原语是link(2)。

5.1 link(2)：原子、绝不替换

规范与源码（linkNoReplace/linkCreatedDespiteError，evidence-provenance.mjs）指出发布使用fs.linkSync，其特性是：

原子；目标名已被占用时返回EEXIST——无论占用者是普通文件、目录还是活/悬空符号链接，都不跟随符号链接去覆盖其目标；
与renameat2(RENAME_NOREPLACE)、renameatx_np(RENAME_EXCL)提供相同的 no-replace 保证，但在所有受支持平台均可通过fs.linkSync使用；甚至在 v9fs（WSL2 的 9p）等renameat2不可用的文件系统上也能工作；
链接成功后，临时名会被 unlink；已发布文件与写入器创建并验证的是同一 inode，因此下游所有身份检查"构造性地"成立；
链接成功但 unlink 失败时，计划已被发布，按成功报告——因为它确实成功了；
不支持硬链接的文件系统（FAT、Coda、部分 SMB/FUSE/virtiofs）会大声拒绝，绝不降级为替换式 rename；
若系统报告错误但链接实际已建（NFS 场景），用源文件 nlink 是否达到 2 判定。

计划父目录与仓库的 Git 管理目录必须位于同一文件系统。

5.2 写入时序与 fsync 保障

写入器流程（规范 L134-L147 + 源码）：

解析目标仓库精确 Git top-level，以持有的 no-follow 目录描述符打开根与每个目标父目录；
相对这些描述符创建缺失父目录；
在写入边界证明描述符链与词法链仍标识同一批目录；符号链接或非目录父目录、逃逸解析路径、符号链接/非常规最终目标、父目录被替换均为错误；
在持有的最终父描述符旁创建随机互斥临时文件，保持其 no-follow 描述符打开；
写入并 flush 字节，把临时名绑定到已打开的 inode，在发布前对打开中的文件做哈希；
发布前一刻重新验证父目录与临时路径的 inode、大小、摘要；
发布：相对持有的目录描述符把临时名 link 到目标——目标被占用时失败而非替换。因此初始模式即使出现"先检查后目标出现"也无法覆盖；
随后 flush 目录，以O_NOFOLLOW重新打开已提交路径，分别对原始临时 fd 与路径绑定 fd 做哈希，再做一次描述符锚定的路径身份检查；发现任何变更或替换即中止，绝不接受"混合时代"的输出。

每个新建的计划或 vault 目录先自身 fsync，再 fsync 进其所在目录；每次跨目录的保留性移动在报告成功或恢复路径前，都会 fsync 源与目标目录。

六、Linux 锚定 vs macOS 验证：两条不同的证明路径

这是本设计中一个刻意保留的真实差异，而非被抹平的实现细节：

Linux上每个名字都经由/proc/self/fd/<fd>/<child>解析——这是内核基于描述符已持有的 inode解析的 magic link。其上的名字永远不会被重新遍历，因此攻击者即使在"检查"与"使用"之间重命名了父目录，也无法重定向操作——竞态是不可能的，不只是被检测到。

macOS没有这样的路径。/dev/fd/<fd>是 devfs 节点而非 magic link：可以被 open，但无法经由它解析任何子项；open("/dev/fd/<fd>/child")返回ENOENT，对它的realpath返回/dev/fd/<fd>而非目录路径（规范注明这是在 macOS 26 上实测的，非推断）。Node 不暴露openat、dir_fd参数或 FFI，因此 macOS 写入器的做法是：

在每个组件上以O_NOFOLLOW做词法解析；
在整个操作期间对链上每个目录持有打开的描述符；
在每一步之前与之后证明链仍恰好指向其持有的 inode。

持有描述符正是让记录的 inode 号可信的原因：一个打开的描述符 pin 住它的 inode，被释放的编号无法在遍历下方被回收复用（源码verifyPinnedDescriptors，evidence-provenance.mjs）。

两种平台共享同一个结论，只是强度不同：

macOS 买到的是检测而非预防——检查与使用之间窗口内被调包的父目录会被紧随其后的检查捕获，操作在未写入任何内容时中止；但在 Linux 上它根本不可能发生。无论哪种平台，没有任何已发布字节能逃过验证。

实现注释还记录了一个值得注意的历史坑：macOS 上曾为目录 open 追加O_NOFOLLOW_ANY，但 XNU 在配合O_DIRECTORY时会直接以EINVAL拒绝，导致 Darwin 上所有目录打开失败；该标志已被移除且不会以探测或降级方式回归——逐组件O_NOFOLLOW遍历才是保证本身。

七、Canonical bytes：全局脏摘要的精确帧格式

global_dirty_digest.value是对下列字节流计算出的小写 SHA-256（不带sha256:前缀）；所有文本值均为其精确 UTF-8 字节；下文的NUL指一个0x00字节。规范化字面量被定义为：

gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records

帧结构（与源码serializeDirtyRecords/canonicalRecord/serializeFields一致，evidence-provenance.mjs）：

前缀字段，每个后跟 NUL，再跟一个额外 NUL：gitnexus-evidence-provenance、schema_version、2；
零或多条记录，按规范化路径 UTF-8 字节的**无符号字典序（unsigned lexicographic comparison）**排序——禁止 locale 序与文件系统序（源码用compareUtf8做二进制字节比较，并对重复规范化路径抛错）；
每条记录为record+ NUL，随后是按固定顺序的field-name+ NUL +field-value+ NUL 对序列，最后再加一个额外 NUL。固定字段（RECORD_FIELDS）为：path、state、head_kind、index_kind、worktree_kind、untracked_kind、rename_from、rename_to、head_digest、index_digest、worktree_digest、untracked_digest；
字面量absent表示所有不可用的重命名端点、对象 kind 与层摘要——它永远不会是空字符串。

固定字段数 + 前缀/记录后的额外 NUL 使帧边界无歧义；值内不允许出现 NUL；重复规范化路径被拒绝。

八、记录、重命名与状态语义

原始脏集合（dirty set）取自 Git porcelain v2（源码 readDirtySnapshot），读取时强制参数为：

git -c diff.renameLimit=0 -c status.renameLimit=0 status \ --porcelain=v2 -z --untracked-files=all --find-renames=50% --ignore-submodules=none

-zNUL 终止；
包含所有未跟踪文件；
子模块检查开启；
固定 50% 重命名阈值；
diff.renameLimit=0与status.renameLimit=0同时设置，仓库配置无法限制重命名候选数量。

共享同一路径的多个原始 porcelain 事实被合并为一条规范记录。一次重命名贡献两个端点事实：

旧端点：path=<old>、rename_from=absent、rename_to=<new>；
新端点：path=<new>、rename_from=<old>、rename_to=absent。

两者通常都是renamed状态；记录排序而非新旧角色决定先后顺序。工作区脏的重命名目标、或同时带另一事实的端点，状态为mixed并保留重命名元数据。任一端点被引用时，引用清单会自动扩为包含两端。

普通XY状态映射（源码classifyXY，evidence-provenance.mjs）：

条件	状态
索引列与工作区列都脏	`mixed`
删除（任一列为 D）	`deleted`
仅索引变更	`staged`
仅工作区变更	`unstaged`
`?`	`untracked`
同路径多个不同事实	`mixed`
阶段化删除后又重建文件	保留 HEAD/index 事实，文件系统对象记入 untracked 层
`? child/`（Git 内嵌目录标记）	去掉尾部斜杠后规范化，`child`物化为一个有界目录对象
引用路径不在脏集合内	`clean`（仅存在于 Git 层之外为`untracked`；任何层都不存在为`absent`）
未合并路径（`u`记录 /`U`列）	直接抛错，无法规范化——先解决索引

九、对象与摘要规则

每个存在的层摘要格式为sha256:<小写十六进制>（源码sha256()函数）：

HEAD 层

普通文件/符号链接：Git blob 精确字节的 SHA-256；
目录：精确原始 Git tree 字节的 SHA-256；
gitlink：tree 中存储的 ASCII 对象 ID 的 SHA-256。

索引层

普通文件/符号链接：stage-0 Git blob 字节的 SHA-256；
gitlink：其 ASCII 对象 ID 的 SHA-256；
索引没有目录层；任何非 stage-0 条目都会被拒绝。

已跟踪工作区层

普通文件：原始文件字节，以不跟随符号链接的方式打开读取（源码hashFile全程O_NOFOLLOW+ 前后fstat身份一致性断言）；
符号链接：原始链接目标字节；
gitlink：仅在rev-parse --show-toplevel证明该目录自身是嵌套仓库根、HEAD在其中可解析、且 porcelain v2 未报告该嵌套目录的任何 staged/unstaged/untracked/ignored 变更后，才取检出嵌套 HEAD 的 ASCII 对象 ID；同一 root/HEAD/clean 证明会被 mutation guard 重复一次；脏、空、未初始化或父目录穿透的 gitlink 一律 fail closed；
目录：下述 v1 目录流。

层归属

HEAD 与索引中都不存在的路径，文件系统对象记入untracked层、worktree标记为 absent；
Git 托管的路径记入worktree、untracked标记为 absent；
缺失层对 kind 与 digest 都用字面量absent；
空文件是零字节的 SHA-256——绝不能用"不存在"冒充空文件。

目录对象 v1 流

前缀字段gitnexus-evidence-directory、schema_version、1，同样的 NUL 帧；
递归条目按无符号 UTF-8 相对路径字节排序；
每条目固定字段：path、kind、digest；
一次自底向上的文件系统遍历访问每个节点一次，返回每个子摘要及展平子树以保留规范字节；绝不跟随链接；
当目录被证明是精确的嵌套 Git top-level 时，仅排除其管理性.git条目，其余（工作文件、嵌套目录）仍是证据。

目录边界（DIRECTORY_LIMITS，evidence-provenance.mjs）：每次遍历至多 10,000 个条目、深度 256、普通文件内容至多 256 MiB；超过任一上限即 fail closed，且各界限独立适用于每条记录物化的每个顶层目录对象。

竞态防护（源码末尾verifyGuards+ 快照前后双重比对）：

HEAD 对象只从快照开始时捕获的完整对象 ID 读取，符号名HEAD绝不针对各层重新解析；
索引层从一次捕获的 stage-0 列表解析；
helper 守护对应的 HEAD/ref/reflog 控制文件与原始索引文件，结束时比对捕获列表，拒绝普通的 A→B→A 变更而非接受混合时代层；
普通文件经O_NOFOLLOW描述符读取并做前后身份检查；符号链接用 lstat/readlink/lstat；目录在盘点前后记录身份；
开始与结束时比对 porcelain-v2 status 与 HEAD，并重查文件系统守卫；
被引用的缺失路径持有最近存在父目录的 no-follow 描述符，记录首个缺失组件/叶子；该锚定缺失在最终 Git status pass 前后各查一次，使新建的 ignored 路径无法逃避 porcelain；
观察到任何竞态都拒绝整个快照，绝不输出混合时代的证据。

十、在 gitnexus-plan / gitnexus-work 全流程中的落位

理解了契约后，再看它在两个技能中"何时、为何"被调用会更有价值：

gitnexus-plan（规划，永不改动生产代码）——SKILL.md

Phase 4（定向源码验证）结束前，立即按本文档要求重算evidence_provenance快照，重读规划期间发生变化的任何引用，且只排除 generated-plan 路径；
Phase 5 组合计划时，把该 schema-2 JSON 原样拷入 §11 包的强制evidence_provenance字段（见 plan-template.md 与 context-pack.md 中"此为该字段唯一规范 schema"的声明），再整体交给write-plan（初始模式，不带--replace）；
Deepen 模式则先read-plan→ 全量重跑 Phase 1 → 重锚再重 pin → 以write-plan --replace --expected-plan-path --expected-plan-digest原地重写同一规范文件，并保留回执中的prior_plan_backup_git_path。

gitnexus-work（执行，会改动代码）——SKILL.md

输入三态：计划路径、最新docs/plans/*gitnexus-plan*.md、或小任务直通模式；
解析 §11 包并要求回执规范路径与evidence_provenance.generated_plan_path逐字节相等；缺失 provenance 或 schema 1 一律视为 legacy 计划，绝非干净树；
执行前做两层漂移检查与保守重锚，重锚结果留在会话状态、永不改写计划正文；
用git rev-parse --git-path解析备份路径（gitnexus-plan-backups/<random-name>），而绝不可把它当作仓库相对工作树路径——该约定在计划父目录发布后被重命名时依然有效。

十一、总结：它为什么值得作为 byte contract 存在

从工程本质看，这份文档把"AI 写了什么、依据了哪棵确切的仓库状态"从不可审计的自然语言，压缩成了可复算、可字节级比对的证据流。它的设计取舍非常清晰：

只信描述符，不信词法路径——读取与写入都锚定在 held directory descriptor 上，Linux 让竞态不可能，macOS 让竞态必然被发现；
只信精确字节，不信语义巧合——同一路径、同一摘要、同一 inode 是强绑定的三位一体；同一字节的拷贝也不能授权另一路径；
只信 no-replace 原语，不信先查后写——link(2)让"覆盖别人的文件"在结构上不可行；
写入前自证、写入后再证——fsync、inode、digest 多重验证，绝不允许混合时代的输出逃逸。

后续代码阅读推荐按此顺序：先读规范文档 references/evidence-provenance.md，再对照 scripts/evidence-provenance.mjs 的normalizeRepoPath、readDirtySnapshot、canonicalRecord、serializeDirtyRecords、linkNoReplace、parseCli、main等关键函数；随后结合两个 SKILL 看调用时序，最后在.claude/skills/gitnexus-plan/references/context-pack.md中确认evidence_provenance在实施上下文包中的字段语义。这套契约同时服务 AI 规划器的"防伪"与执行器的"防错"，是让多代理、多会话、跨平台协作下仍能保持仓库证据可信的底层保障。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析