# Trellis 升级与项目状态多维审查设计

## 决策门

本任务先完成只读盘点和升级方案。用户批准前，不执行 CLI 安装、`trellis update`、模板覆盖、文件删除或业务代码修改。

## 升级顺序

1. 将全局 Trellis CLI 从当前版本对齐到 npm `latest`，再次 dry-run，避免用旧 CLI 写入旧模板。
2. 为当前干净基线保留可回滚提交点；注意 0.6.9 的 `trellis update --dry-run` 会实际清理 `.template-hashes.json` 中旧拼写 skill 的 5 个 manifest 条目，不能把 dry-run 当作零写入操作。
3. 临时安全保存项目内仅含本地设置的 `.claude/` 目录后再升级，避免 Trellis 仅凭目录存在误判 Claude 已启用并生成整套 Claude 资产；升级完成后原样恢复本地设置。
4. 项目升级优先使用“为冲突文件生成 `.new`、自动更新未改模板”的保守策略并应用 migration；不使用 `--force`。
5. 对 `AGENTS.md`、`.trellis/workflow.md`、`.trellis/config.yaml`、`.trellis/.gitignore` 逐文件三方合并，保留项目的中文、Trellis-first、Codex inline、禁止自动提交和授权边界。
6. 应用明确需要的 migration，验证 task、hook、context、governance 和完整本地质量门禁。

## 审查维度

- 产品/交付状态：继承并复核 07-16 审查与 07-18 本地候选证据，严格区分本地、部署、外部验证。
- 工程质量：代码规模、测试入口、全量门禁、风险覆盖和依赖/构建观察项。
- Trellis 治理：版本漂移、模板定制、task/spec/archive、Codex 集成和 session 状态。
- 文档治理：事实源、未注册文档、历史 Issue 与重复状态描述。
- 仓库卫生：ignored 生成物、tracked 历史证据、体积热点和清理验证。
- 运维边界：部署、生产配置、真实数据、企微和付款仍需单独授权。

## 建议分级

- P0：会导致升级覆盖、本地候选状态误判或高风险开放项失管的问题。
- P1：近期应完成、收益明确且可独立验收的改进。
- P2：持续治理或触达即修，不打包成巨型重构。
- 精简项：删除或合并前必须证明非事实源、非审计合同且可从 git 恢复。

## 回滚

- 全局 CLI 可按升级前版本号重新安装。
- 项目文件只在干净基线后修改；升级提交与后续优化提交分开，可独立回退。
- 不手改 `.trellis/.template-hashes.json`；发现 manifest 异常时停止升级并从基线恢复升级提交。