hyb-oa/.trellis/tasks/07-26-trellis-upgrade-project-audit/design.md

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 异常时停止升级并从基线恢复升级提交。