升级 Trellis 并完成项目审查（07-26-trellis-upgrade-project-audit）

2026-07-26 18:10:49 +08:00
@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,36 @@
+# 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 异常时停止升级并从基线恢复升级提交。
@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}
@@ -0,0 +1,41 @@
+# Trellis 升级实施清单
+
+## 执行步骤
+
+- [x] 将全局 Trellis CLI 升级到 0.6.9。
+- [x] 临时隔离并恢复 `.claude/settings.local.json`，避免 Claude 平台误检测。
+- [x] 以 `--create-new --migrate` 升级项目 Trellis 模板和 runtime。
+- [x] 保留 `session_auto_commit: false` 与 `codex.dispatch_mode: inline`。
+- [x] 合并上游 workflow，并恢复 hyb-oa Trellis-first overlay。
+- [x] 保留项目 `.trellis/.gitignore` 的本地 workspace 排除规则。
+- [x] 保留项目 `AGENTS.md`，不追加重复的通用英文托管块。
+- [x] 删除冲突 `.new` 副本和迁移遗留的旧拼写 skill。
+- [x] 运行升级后 task/context/hooks/governance 验证。
+- [x] 运行完整本地质量门禁并记录结果。
+- [x] 评估并更新稳定 spec。
+- [x] 形成中文提交。
+- [ ] 完成 Trellis task 归档。
+
+## 验证结果
+
+- Trellis CLI、项目版本与 npm latest 均为 0.6.9；升级后 dry-run 稳定。
+- Python 3.9.2 compileall、task validate/current/list 与 Trellis runtime 基本命令通过。
+- `bash scripts/check-minimal.sh` 退出码为 0：Prisma validate、服务端 985/985、前端 typecheck/build、功能矩阵均通过。
+- 非阻断提示仅有既有 `punycode` deprecated 与 Browserslist 数据陈旧提示。
+
+## 验证命令
+
+- `trellis --version`
+- `python3 ./.trellis/scripts/get_context.py`
+- `python3 ./.trellis/scripts/task.py validate .trellis/tasks/07-26-trellis-upgrade-project-audit`
+- `node scripts/qa/check-trellis-governance.mjs`
+- `node scripts/qa/audit-docs.mjs --check-registry`
+- `node scripts/qa/check-process-contract.mjs --baseline --json`
+- `bash scripts/check-minimal.sh`
+- `git diff --check`
+
+## 回滚点
+
+- CLI：重新安装升级前的 0.6.8。
+- 项目：回退本任务升级提交；`.trellis/.backup-*` 只用于本地临时核对，不纳入提交。
+- 若 hooks 或 task runtime 验证失败，停止后续业务工作，不以旧 workflow 混用新 runtime。
@@ -0,0 +1,88 @@
+# Trellis 升级与项目状态多维审查
+
+## Goal
+
+确认本项目 Trellis 与上游版本差异，制定可回滚的升级方案；同时从任务治理、代码与测试、文档事实源、仓库卫生、交付与运维等角度梳理当前项目状态，输出分级改进、优化和精简建议。
+
+## What I already know
+
+- 当前分支为 `main`，审查开始时工作区干净。
+- 当前没有正式 active task；旧的 `05-31-hyinda-light-ops-greenfield` 仅来自 stale session fallback。
+- 项目只启用 Codex 适配，Trellis 不自动提交。
+- 非微小改动必须先给出方案并等待批准。
+- 近期已经完成过多维系统审查和五人团队正式内用最小收口，需要优先复用结论，避免重复造文档。
+
+## Assumptions (temporary)
+
+- “升级 Trellis”指升级当前项目内由 Trellis 管理的模板、脚本和 Codex 适配文件，不修改全局 npm 包源码。
+- 本阶段只做只读审查、版本比对和方案设计；升级与冲突处理在用户批准后实施。
+- 审查建议应区分立即处理、近期优化和可暂缓项，并明确收益、风险与验证方式。
+
+## Open Questions
+
+- 待版本与模板漂移盘点后，只保留会实质影响升级范围的偏好问题。
+
+## Requirements (evolving)
+
+- 识别已安装 Trellis 版本、项目记录版本和可用最新版。
+- 识别 Trellis 管理文件的本地修改、模板漂移、潜在覆盖冲突和升级回滚点。
+- 复核现有 task、spec、docs、代码结构、测试与质量门禁、仓库产物和交付流程。
+- 复用既有事实源与历史审查，不轻易新建常驻文档。
+- 输出按优先级排序、可执行且避免过度治理的改进建议。
+
+## Scope
+
+- Trellis：全局 CLI 版本、项目模板版本、迁移、Codex hooks/agents/skills、task/spec/workflow/config 兼容性。
+- 工程：服务端、前端、测试与发布门禁的当前可执行状态；本阶段不主动重构业务代码。
+- 治理：task 生命周期、事实源状态、文档注册、历史 Issue 与 Trellis archive 的保留边界。
+- 仓库：已跟踪与本地忽略产物、体积热点、可安全清理项和防复发规则。
+- 交付：本地候选、部署、公网/真机/真实数据等状态边界是否仍准确。
+
+## Acceptance Criteria (evolving)
+
+- [x] 给出 Trellis 当前版本、目标版本、升级命令、冲突预案与验证清单。
+- [x] 给出项目现状摘要，并以证据路径支撑关键结论。
+- [x] 建议覆盖改进、优化、精简三个方向，并区分优先级。
+- [x] 在任何非微小修改前获得用户批准。
+- [x] 获批实施后通过 Trellis 治理、文档注册、核心前后端及 `git diff --check` 等适用验证。
+
+## Acceptance Evidence
+
+- Trellis CLI 与项目模板均已升级到 0.6.9；升级后 dry-run 不再产生 manifest 变化，仅识别五个预期本地定制文件。
+- 项目实际 Python 3.9.2 已通过 `.trellis/scripts` 与 `.codex/hooks` 全量编译检查；并修复 0.6.9 `task_context.py` 的嵌套多行 f-string 兼容问题。
+- Trellis task 的 validate/current/list、governance、process contract、敏感扫描与功能矩阵通过。
+- Prisma validate 通过；服务端 161 个测试文件、985/985 测试通过；前端 typecheck 与 production build 通过。
+- 文档 registry 仅保留既有 22 项假阳性 warning，原因和后续独立治理建议已记录在 research，不作为本次升级失败项。
+- 交付状态继续限定为 `LOCAL_CANDIDATE_PASS`；本任务未部署、未执行公网检查或真实数据操作。
+
+## Definition of Done (team quality bar)
+
+- 适用的 lint、typecheck、测试与流程检查通过。
+- 升级差异经过人工审阅，本地定制不被静默覆盖。
+- 事实源或任务记录按需更新，不制造重复文档。
+- 升级与审查改动形成中文提交并引用任务名。
+
+## Test Plan
+
+- 升级前后分别运行 `trellis update --dry-run`，确认版本、迁移、新增文件、本地修改和用户数据保护行为。
+- 运行 task validate、Trellis governance、文档 registry/process contract、敏感内容扫描和 `git diff --check`。
+- 运行 `bash scripts/check-minimal.sh`，覆盖 Prisma validate、服务端全量 Vitest、前端 typecheck/build 和功能矩阵。
+- 仅在修改业务代码或页面行为时追加聚焦服务端/Playwright；本轮默认不部署、不做公网或真实数据检查。
+- 升级后复核 Codex hooks、active task 解析、`get_context.py` 和 task 生命周期基本命令。
+
+## Out of Scope (explicit)
+
+- 公网部署、生产配置、真实数据写入、数据库重置、企业微信写入和真实付款。
+- 未经批准的大规模业务功能重构。
+- 启用 Codex 之外的 AI 平台适配。
+
+## Technical Notes
+
+- Trellis task：`.trellis/tasks/07-26-trellis-upgrade-project-audit/`
+- 工作流：`.trellis/workflow.md`
+- Trellis 项目规约：`.trellis/spec/hyb-oa/`
+- 关键业务事实源：`docs/文档索引.md`、`docs/文档事实源状态矩阵.md`、`docs/Agent开发交付实践.md`
+
+## Research References
+
+- `research/current-state-audit.md`：Trellis 0.6.9 升级预演、当前质量门禁、业务开放项、依赖、文档与仓库卫生审查结论。
@@ -0,0 +1,95 @@
+# 当前项目状态多维审查
+
+## 结论摘要
+
+- 当前业务代码仍处于 `LOCAL_CANDIDATE_PASS`，不是已部署或可公网测试；07-18 收口后的业务代码没有新增提交。
+- 本次重新执行完整本地门禁通过：Prisma schema 有效，服务端 161 个测试文件 / 985 项测试全部通过，前端 typecheck 与 production build 通过，流程合同、Trellis governance、敏感扫描和功能矩阵通过。
+- Trellis 项目版本为 0.5.19，本机 CLI 为 0.6.8，npm 最新为 0.6.9。升级应直接以 0.6.9 为目标。
+- 当前最需要优先处理的新增工程风险是前端 React Router 两项 moderate advisory；最重要的既有业务开放项仍是统一导出安全与客户端离线数据生命周期。
+
+## Trellis 升级审查
+
+### 实施结果（2026-07-26）
+
+- 全局 CLI 与项目模板已从 0.6.8 / 0.5.19 对齐到 0.6.9，并完成官方 migration。
+- 升级时临时隔离仅含本地设置的 `.claude/`，恢复后未生成 Claude 托管资产；项目继续保持 Codex-only。
+- 四个冲突文件按设计完成合并，保留 Trellis-first overlay、Codex inline、禁止自动提交和 `workspace/` 忽略规则；未保留 `.new` 冲突副本。
+- 0.6.9 runtime 的 `task_context.py` 包含 Python 3.9.2 不接受的嵌套多行 f-string；已改为先构造 warning 再着色，并通过全量 compileall 与 task runtime 验证。
+- 升级后 dry-run 不再改变 manifest，仅报告 `task_context.py`、`config.yaml`、`.gitignore`、`workflow.md`、`AGENTS.md` 五个有意保留的项目定制。
+
+### 升级前版本与差异
+
+- 项目：0.5.19。
+- 本机 CLI：0.6.8。
+- npm latest：0.6.9。
+- 0.6.9 将更新 Trellis runtime、共享 skills、Codex agents/hooks/config，并新增 `.trellis/agents/`、`trellis-channel`、`trellis-session-insight` 和拼写修正后的 `trellis-spec-bootstrap`。
+- `AGENTS.md`、`.trellis/workflow.md`、`.trellis/config.yaml`、`.trellis/.gitignore` 被识别为本地修改，必须三方合并。
+
+### 已确认风险
+
+1. 仅因为项目存在 `.claude/settings.local.json`，CLI 就把 Claude 判定为已配置平台，计划新增整套 `.claude/` commands、skills、agents、hooks 与 settings；这与 Codex-only 边界冲突。
+2. 0.6.9 的 `update --dry-run` 会实际清理 `.template-hashes.json` 中旧拼写 `trellis-spec-bootstarp` 的 5 个条目，尽管结尾显示 `No changes made`。预演后的非预期修改已恢复。
+3. 上游建议 `--migrate`，涉及旧拼写目录迁移；不能手工提前删除旧 skill 或强制覆盖本地 workflow。
+
+### 推荐升级路径
+
+1. 升级全局 CLI 到 0.6.9。
+2. 临时安全保存 `.claude/` 本地目录，使 Trellis 只检测到 Codex。
+3. 在干净提交点上执行保守更新和 migration；冲突文件生成 `.new`，不使用 force。
+4. 逐文件合并四个本地定制文件，保留中文沟通、方案批准、Codex inline、no auto commit、生产授权边界。
+5. 恢复 `.claude/settings.local.json`，确认没有新增 Claude 托管资产。
+6. 验证 context、task lifecycle、hooks、governance、完整本地门禁并单独提交升级。
+
+## 代码、测试与依赖
+
+- 规模：服务端约 200 个跟踪源文件，前端约 297 个跟踪源文件；服务端 161 个单元测试文件，前端测试目录 81 个文件；Prisma migration 61 项。
+- 全量门禁：985/985 服务端测试通过；前端 typecheck/build 通过。
+- 覆盖率配置能生成报告，但没有风险阈值；既有 `QA-COVERAGE-001` 仍开放。建议针对认证、付款、worker、迁移/恢复入口建立风险型阈值，不追求全仓统一百分比。
+- 前端生产依赖审计报告 2 项 moderate，均来自 React Router 6.30.4；公开修复指向 7.18.1，属于需要专项回归的 major migration。
+- 服务端 `npm audit` 因 npm quick-audit endpoint 返回 invalid package tree 而不可用；`npm ls` 无 problem、`npm ci --dry-run` 可完成，说明更像审计接口/锁树兼容问题，但仍应在依赖维护任务中闭合。
+- 可安全优先升级一批服务端 patch/minor；Vitest、React、Vite、Tailwind、pg-boss 等 major 不应混成一次升级。
+- 构建观察：PWA precache 约 2.1 MiB，扫码 vendor chunk 约 411 KiB，Material Symbols 字体约 479 KiB；目前无行为故障证据，先测真实首屏/弱网再优化。
+- 非阻断工具提示：Node `punycode` 弃用；Browserslist 数据约 6 个月未更新。
+
+## 业务与交付状态
+
+- 07-18 已本地验证：认证代理信任、附件主动内容、员工敏感字段、员工合同附件、付款状态机/审计、核心长表单、移动考勤、响应式表格、权限显隐与本地发布门禁等。
+- 上述本地修复仍未部署和公网复核；两个原 P0 的 Gate 0 外部验证仍需单独授权。
+- 当前 P1 开放项：统一 CSV/表格导出中和；退出/换账号后的离线数据隔离与清除。
+- P2 持续治理：下载凭证日志面、未执行 ACL 元数据、CSP、防误触、通知/搜索定位、路由元数据、错误恢复、冻结差旅入口、错误文案、移动权限与可访问性。
+- 这些 P2 不应打包成巨型重构，按触达页面或独立小任务收敛。
+
+## 文档与治理
+
+- 事实源矩阵最近审计为 07-16，已正确声明当前可信基线与 Trellis-first 优先级。
+- `audit-docs --check-registry` 报 22 个未注册文件，但这 22 个文件都在同一文档后续“当前事实源/手册/证据/技术参考”章节列出；脚本只解析首个主表，因此 warning 噪声高。
+- 建议让 registry checker 识别后续分类表，或把 22 项合并进主台账；优先改检查器，避免复制 22 行冗长元数据。
+- 历史 Issue CSV 共 349 个、约 3 MiB；Trellis archive 78 个 task、850 个文件、约 5.7 MiB。体积不大且有审计价值，不建议本轮物理删除。
+- 后续应停止向历史 Issue CSV 增长；Trellis archive 只保留 PRD/设计/关键结论和最小证据，不再重复提交大批 raw log。
+
+## 仓库卫生
+
+- 整体工作目录约 1.2 GiB，但 Git 仓库仅约 27 MiB；主要是本地依赖与忽略产物，不是 Git 历史膨胀。
+- `server/node_modules` 约 644 MiB，`client/node_modules` 约 253 MiB，属于可重建依赖缓存。
+- ignored 证据/输出中，`output` 约 154 MiB、`artifacts` 约 17 MiB，加上 build/report/coverage 可安全回收约 174 MiB；当前 `.gitignore` 已覆盖这些路径。
+- 建议新增一个显式的本地清理命令，只删除已忽略且可重建的固定路径；默认不删 node_modules，不清理已跟踪 Trellis archive。
+
+## 建议优先级
+
+### P0 / 本轮升级
+
+- 安全升级 Trellis 至 0.6.9，隔离 Claude 误检测、dry-run 写 manifest 和本地四文件合并风险。
+- 保持 `LOCAL_CANDIDATE_PASS` 状态上限；未经授权不部署、不做公网/真实数据验证。
+
+### P1 / 下一批独立任务
+
+- React Router 安全升级与导航/重定向回归。
+- 统一导出安全 + 客户端离线数据生命周期，沿用既有 WP-5。
+- 消除 document registry 的 22 项假阳性 warning，使门禁重新具备信噪比。
+
+### P2 / 维护与精简
+
+- 风险型覆盖阈值、服务端 audit 可用性、patch/minor 依赖维护。
+- 本地 ignored artifacts 清理命令和证据保留期限。
+- 按触达修复可访问性、导航元数据、错误恢复等开放项。
+- 真实性能数据证明需要后，再优化扫码 chunk、字体和 PWA precache。
@@ -0,0 +1,35 @@
+{
+  "id": "trellis-upgrade-project-audit",
+  "name": "trellis-upgrade-project-audit",
+  "title": "Trellis 升级与项目状态多维审查",
+  "description": "安全升级项目 Trellis，并基于现有事实源多维复核项目状态，形成分级优化与精简建议。",
+  "status": "in_progress",
+  "dev_type": null,
+  "scope": "trellis-governance-and-project-audit",
+  "package": null,
+  "priority": "P2",
+  "creator": "shunli",
+  "assignee": "shunli",
+  "createdAt": "2026-07-26",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [
+    ".trellis/",
+    ".agents/skills/",
+    ".codex/",
+    "AGENTS.md",
+    "docs/",
+    "scripts/qa/",
+    "server/",
+    "client/"
+  ],
+  "notes": "",
+  "meta": {}
+}
				`@@ -0,0 +1 @@`
				{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}