weichen
1ac79c2a90
Why: make requirements, experiments and implementation revisions reviewable while retaining bounded continuous authorization. Evidence: task-card SELF receipts include expected red regressions and 104 passing governance checks; full candidate verification follows. Impact: add project delivery policy and generated task fields; make post-merge reminders read-only. Refs: .task/feature-iterative-delivery.md; policy/delivery.md
90 lines
6.1 KiB
Markdown
90 lines
6.1 KiB
Markdown
# 开发门禁的执行与证据
|
||
|
||
本文件细化根 AGENTS.md 的启动、验证和回收规则。通用语义以固定的
|
||
`deps/development-guidelines` 为准；门禁实现及回归用例随本仓版本管理。
|
||
需求表、设计试验、迭代调整、阶段产物与人工评审按 [迭代交付](delivery.md) 执行。
|
||
任务卡记录批准来源与对象版本；本地 evidence 仅记录命令，不能证明人工批准。
|
||
|
||
## 启动与恢复
|
||
|
||
从当前检出运行一次启动检查，使用每次唯一、仓外的绝对收据路径：
|
||
|
||
```bash
|
||
RECEIPT=/tmp/my-task-precheck.json CMD="make precheck" make evidence
|
||
make task-start NAME=feature/my-task PRECHECK_RECEIPT=/tmp/my-task-precheck.json
|
||
```
|
||
|
||
第一步先捕获原始执行，再创建任务卡；收据保存完整脱敏输出、退出码、执行位置和对象。
|
||
第二步核验收据与当前仓库/基线，再创建工作区并导入；不靠事后重跑冒充首次检查。
|
||
同一收据不可覆盖。首次检查失败时处理原因，使用新路径重新启动。主干在两步间前进时，
|
||
重新确认新的启动基线，不能把旧收据移花接木到新对象。
|
||
|
||
恢复已有任务仍先捕获本次启动检查，再在原任务工作区用
|
||
`IMPORT_RECEIPT=/tmp/my-task-resume.json make evidence` 导入；不重新建分支。
|
||
工作区忙或落后时先由 owner 保存现场并同步；远端不可达时只继续不依赖新鲜基线的阅读和分析。
|
||
|
||
堆叠任务使用 `PARENT=feature/parent PARENT_PR=<父PR链接>`。父分支须包含本批主干 R0；
|
||
卡片同时记录父分支、父 SHA 和父 PR。父先合入，子同步最新 main 并改回 main 为 PR base。
|
||
|
||
## 被测对象
|
||
|
||
`make task-sync` 在父仓合并后按固定 gitlink 物化未修改组件，并核对实际组件工作树。
|
||
组件 feature 分支若与新指针不同，先保留其分支，交给 owner 显式同步并更新组合；
|
||
不能用自动 checkout 丢弃组件分支现场。任何失败都保留现场并阻止同步成功声明。
|
||
|
||
`make test-worktree` 核对递归子模块：未初始化、冲突、指针漂移及子仓未保存改动均拒绝。
|
||
它是组合测试和构建的前置检查。父仓未提交改动可以局部测试，但证据必须记录实际对象状态；
|
||
正式验收使用已提交的固定对象，不能仅写一个与工作树不同的 HEAD。
|
||
|
||
## 本地记录与独立证据
|
||
|
||
本地 `make evidence` 一律生成 SELF。`SRC=GATE/REPLAY` 不可把本地执行升级为权威来源。
|
||
GATE 引用受信平台的运行链接、执行身份、完整 SHA 和结果；REPLAY 引用独立审阅者的
|
||
环境、命令、对象和结果。审核者核验这些来源，不能只读作者填入的标签。
|
||
|
||
收据中的摘要检测损坏，不是签名或身份凭据。保存的是完整脱敏输出及其 SHA-256；
|
||
命令含敏感值时展示脱敏形式，并记录原命令摘要。执行前后对象分别记录；命令改变 HEAD
|
||
时不把执行前 SHA 冒充执行后对象。不能读取执行后状态时明确记录缺项。
|
||
|
||
凭据从环境或受保护文件引用，避免出现在命令字面量。脱敏是补充防护，不是允许输出秘密。
|
||
执行脚本不通过 shell tracing 暴露环境；管道任何一段失败应传回非零退出码。
|
||
工具写入失败本身也必须报错，不能只保留一个看似成功的退出状态。
|
||
|
||
## 回收
|
||
|
||
仅在登记的任务 worktree 根目录回收。owner 先确认全部写者已退出、任务成果与证据已保存，
|
||
以 `TASK_WRITERS_STOPPED=1 make task-finish` 明确确认；
|
||
脚本检查主检出/子目录误用、Git 操作和锁、父子仓修改及未跟踪/ignored 文件；
|
||
子模块另有登记 worktree 时拒绝回收，避免删除其他检出依赖的 Git 管理目录。
|
||
可再生缓存由 owner 按已识别路径单独处置；无法确认用途的文件保留。
|
||
|
||
任务合入需以本次成功获取的权威目标验证。合入提交不能证明未提交文件已经落盘。
|
||
Git 对含子模块的工作区需要显式删除选项时，只有全部现场检查通过才允许该路径；
|
||
它不豁免任何脏状态、忽略文件、独有提交/引用或锁检查。普通删除失败不转入强删兜底。
|
||
保留无法确认安全的目录和分支，输出下一步处理依据。
|
||
子仓 pin 之外的 refs/stash/reflog 历史采取保守拒绝，即使其中部分可能已在远端：
|
||
owner 须先独立确认其保存与归属，工具不把缓存的远端引用当作唯一数据已经备份的证据。
|
||
远端分支删除与本地回收分别报告，失败不能声明两者全部完成。
|
||
回收后由所有者执行 `make task-close` 闭合卡片；回收命令不顺带改写共享主检出。
|
||
post-merge 仅提示，不自动调用闭合。`make task-close` 会提交、推送并可能创建 PR，
|
||
执行者先按迭代交付规则核对该动作的授权及所选任务，保留未授权的其他任务现场。
|
||
回收命令使用待删目录之外的 `RECEIPT` 保存输出，清理结果由后续闭合记录引用。
|
||
|
||
## CI 凭据边界
|
||
|
||
候选代码执行前结束有凭据的源码获取阶段。获取只访问受信主机及登记的组件仓，
|
||
不根据候选提供的任意 URL 携带 token；认证配置限单次进程，不写全局 Git 配置或 remote URL。
|
||
测试/构建阶段检查配置中不存在凭据，并使用不含 checkout token 的环境。
|
||
|
||
仓内测试只能证明脚本边界。runner 隔离、token 权限、工作流来源和平台分支保护
|
||
由平台维护者验证；没有对应 GATE/REPLAY 时标未验证，不由本地测试推断。
|
||
|
||
## 持续回归
|
||
|
||
`make test-governance` 在临时真实 Git 仓库中覆盖回收、组件同步、离线启动、收据捕获/导入、
|
||
管道失败、假凭据脱敏、写路径及 CI 凭据隔离；临时 remote 均为本地路径，禁止使用真实秘密。
|
||
它纳入 `make test`，新机制必须有正常、拒绝和故障分支。历史临时测试记录仅作定位线索。
|
||
|
||
普通文档核对真实入口和相对链接；规范升级检查条文、命令、模板与能力矩阵是否一致。
|
||
机制未变可按固定版本复用证据，变更的机制重新运行对应负例。
|