Maintained repository references
维护中的仓库引用
Historical evidence needs recognizable release, PR, and measured-run identities. Maintained files also serve the public source home, while native publishing uses the repository identity supplied by its workflow. Concrete commit references and deployment-specific organization URLs do not express that distinction.
English
Problem
Historical evidence needs recognizable release, PR, and measured-run identities. Maintained files also serve the public source home, while native publishing uses the repository identity supplied by its workflow. Concrete commit references and deployment-specific organization URLs do not express that distinction.
Decision
Use release tags and PR, run, or job identifiers for historical evidence, and relative links for current repository files. The reference gate scans tracked files and nonignored new files. Vendor sources and frozen Agent Notes retain their existing exclusions; active notes and historical release records remain checked.
The gate resolves hexadecimal candidates against the local Git object database and rejects only unambiguous commit identities. Pairing hashes that identify blobs, schema digests, unrelated hexadecimal values, and hexadecimal branch names that resolve to different object identities remain valid. Organization URL detection shares decoding and normalization with the existing repository-link policy.
Native source manifests identify the public source home. During workflow packing, the native packer projects the workflow repository into disposable inputs so npm trusted publishing can verify the artifact identity. It preserves source manifests and publishes the resulting tarballs unchanged. Local packing without workflow context retains the public source metadata.
Alternatives considered
Reject every hexadecimal string. Persistence schemas and bilingual pairing legitimately use hashes. Git object-type verification separates commit references from these values.
Check only new diff lines. The policy applies to every maintained file, including existing references. A complete scan also catches staged and untracked additions before publication.
Delete required publishing metadata. Native publishing still needs the workflow repository identity. Projecting that identity during packing removes the source literal without changing the identity npm verifies.
Consequences
The gate disables network fetching, including Git partial-clone lazy fetching. It checks all locally available commit objects, including unreachable historical PR heads; absent objects cannot match. A checkout with extra PR objects can therefore detect references absent from CI’s full-history clone. Reference validation establishes the maintained-file policy, not remote tag immutability or historical compatibility. Published native tarballs expose the workflow repository in npm’s Repository metadata; source manifests retain the public source home.
Vendored notices link checked-in source locations while retaining upstream names, licenses, and the unchanged vendor manifest.
中文
问题
历史证据需要可辨认的发行版本、PR 和测量运行标识。维护中的文件也面向公开源码主页，而原生发布使用工作流提供的仓库身份。具体提交引用和与部署绑定的组织 URL 无法表达这一区分。
决策
历史证据使用发行 tag 以及 PR、运行或 job 标识，当前仓库文件使用相对链接。引用检查扫描已跟踪文件和未被忽略的新文件。Vendor 源码与冻结的 Agent Note 保留既有排除规则；活跃笔记和历史发行记录仍参与检查。
检查器针对本地 Git 对象库解析十六进制候选值，仅拒绝能明确标识提交的值。标识 blob 的配对哈希、schema 摘要、无关十六进制值，以及解析到不同对象标识的十六进制分支名仍然有效。组织 URL 检测与既有仓库链接策略共享解码和规范化逻辑。
原生源码清单标识公开源码主页。工作流打包期间，原生打包器将工作流仓库投影到临时输入，让 npm 可信发布可以核验产物身份。它保留源码清单，生成的 tarball 也不在发布时改写。没有工作流上下文的本地打包保留公开源码元数据。
考虑过的替代方案
拒绝每个十六进制字符串。 持久化 schema 和双语配对合理使用哈希。Git 对象类型校验将提交引用与这些值区分开。
仅检查新 diff 行。 策略适用于每个维护中的文件，包括既有引用。完整扫描也会在发布前发现暂存或尚未跟踪的新增文件。
删除发布所需的元数据。 原生发布仍需要工作流仓库身份。在打包阶段投影该身份，可以移除源码中的字面量，同时保持 npm 核验的身份不变。
影响
检查器禁止网络获取，包括 Git 部分克隆的延迟获取。它检查本地所有可用的提交对象，包括不可达的历史 PR 头；缺失的对象无法匹配。因此，包含额外 PR 对象的工作区可能检测到 CI 完整历史克隆中不存在的引用。引用校验建立维护中文件的策略，不证明远端 tag 不可变或历史兼容性。已发布的原生 tarball 在 npm 的 Repository 元数据中显示工作流仓库；源码清单保留公开源码主页。
Vendored 声明链接仓库内的源码位置，同时保留上游名称、许可证和未变的 vendor 清单。