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

## Phase A：共享合同

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

## Phase B：调用点去重

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

## Phase C：Harness

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

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

## Phase D：验证与 Review

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

## Phase E：规约与提交

- [x] 使用 `trellis-update-spec` 更新现有 `deployment-trialrun.md`，记录候选构建身份的单一来源与远端消费验证职责。
- [x] 中文 commit 引用 `08-09-deployment-contract-single-source-harness`（`621934a`）。
- [x] 不部署、不运行生产 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。