hyb-oa/.trellis/tasks/archive/2026-08/08-09-deployment-contract-single-source-harness/implement.md

部署合同单一事实源与失败路径覆盖：实施计划

Phase A：共享合同

• 在 check-source-provenance.mjs 添加一次返回完整 { BUILD_SHA, VITE_BUILD_SHA } 对象的派生函数，导入无副作用；不提供两个独立 getter。
• 让 collectSourceProvenance 从共享结果生成 commit、shortCommit 与兼容的 buildEnv。
• 在 provenance focused tests 中覆盖合法结果、固定键、12 位前缀、非法提交。

Phase B：调用点去重

• deploy.sh 从 provenance buildEnv 读取并完整注入对象中的两值；禁止自行截取候选提交或只消费一个键。
• production-preflight.mjs 导入共享函数，映射非法候选为既有 CANDIDATE_COMMIT_INVALID，并从共享完整对象生成两项远端构建 env assignments。
• 保留 production-preflight-remote.sh 的缺失、格式、前缀和 Compose config fail-closed 校验。
• 更新 validate-env-contract.js 的静态合同：要求两个调用点消费共享来源，而不是只搜索任意 BUILD_SHA= 文本。

Phase C：Harness

• 提取/复用 fake SSH 运行 helper，避免每个失败用例重复搭建临时二进制。
• 通过真实 production-preflight 子进程覆盖完整四象限：非零+code+无 marker、非零+code+有 marker、非零+无 code+无 marker、零退出+无 marker；验证失败前已有稳定 summary/reportRef。
• 扩展 fake Docker mode 覆盖 Compose config 失败，并证明未继续到 Prisma/status 查询。
• 补齐构建值缺失、完整/短格式非法、前缀不一致；成功 SSH fixture 对账共享 buildEnv。

实施证据：focused tests 共 31 项通过。另在两个独立临时 detached worktree 中分别回退错误码判断次序、删除共享对象的 VITE_BUILD_SHA；对应回归测试均变红，证明 AC4 用例对两个历史缺陷敏感。临时 worktree 已删除，本轮未连接生产。

Phase D：验证与 Review

• node --check deploy/trialrun/check-source-provenance.mjs deploy/trialrun/production-preflight.mjs
• bash -n deploy/trialrun/deploy.sh deploy/trialrun/production-preflight-remote.sh
• cd server && npm test -- tests/unit/scripts/check-source-provenance.test.js tests/unit/scripts/deployment-safety-contract.test.js
• node deploy/trialrun/validate-env-contract.js
• task/process/governance/sensitive/diff 门禁。
• 启动只读 reviewer，重点核对共享来源是否真实被两个调用点消费、远端校验是否保留、harness 是否执行真实失败分支且无生产连接。

Phase E：规约与提交

• 使用 trellis-update-spec 更新现有 deployment-trialrun.md，记录候选构建身份的单一来源与远端消费验证职责。
• 中文 commit 引用 08-09-deployment-contract-single-source-harness（621934a）。
• 不部署、不运行生产 preflight；任务证据明确为 local tooling hardening。

质量检查记录

• 语法与 focused tests：31/31 PASS。
• 环境合同：R26 PASS。
• task validation、process baseline、Trellis governance、sensitive scan、docs registry、git diff --check：全部退出 0；docs registry 仅保留既有 unregistered docs files: 22 warning。
• 边界：所有验证均使用本地 synthetic fixture；未执行 SSH、真实 Docker、生产 preflight、部署或迁移。
• reviewer 首轮发现“非零远端 + stable code + 不可读 marker”仍可能在证据前被 marker 校验覆盖；修复后增加真实子进程回归，复核 PASS、无新 finding。
• residual：deploy.sh 的整对象解析主要由静态合同覆盖，尚无完整 fake deployment 子进程；键白名单、去重与恰好两项均 fail-closed，保留为低风险后续改进，不扩大本任务。

Risky Files / Rollback Points

• deploy/trialrun/check-source-provenance.mjs：发布来源核心；任何 CLI JSON 兼容破坏都必须在 focused tests 阻断。
• deploy/trialrun/deploy.sh：正式部署入口；只改变输入来源，不改变步骤顺序或远端动作。
• deploy/trialrun/production-preflight.mjs：错误码/证据顺序不可回退。
• server/tests/unit/scripts/deployment-safety-contract.test.js：fake 命令必须默认拒绝未知调用，避免宽松 mock 制造假 PASS。