归档 Spec 治理任务（05-29-spec-governance-cleanup）
这个提交包含在：
@@ -0,0 +1,4 @@
|
||||
{"file": ".trellis/spec/hyb-oa/project-governance.md", "reason": "Verify Trellis-only and commit governance remain consistent"}
|
||||
{"file": ".trellis/spec/hyb-oa/docs-and-evidence.md", "reason": "Verify docs/spec/evidence boundary after cleanup"}
|
||||
{"file": ".trellis/spec/hyb-oa/frontend-react-vite-design.md", "reason": "Verify frontend-design authority and local UI contracts remain clear"}
|
||||
{"file": ".trellis/tasks/05-29-spec-governance-cleanup/research/spec-audit.md", "reason": "Check implementation matches approved audit findings"}
|
||||
@@ -0,0 +1,4 @@
|
||||
{"file": ".trellis/spec/hyb-oa/project-governance.md", "reason": "Trellis-only task and commit governance for spec cleanup"}
|
||||
{"file": ".trellis/spec/hyb-oa/docs-and-evidence.md", "reason": "Document/spec/evidence boundary rules for spec governance"}
|
||||
{"file": ".trellis/spec/hyb-oa/frontend-react-vite-design.md", "reason": "Frontend-design authority and local frontend spec boundary"}
|
||||
{"file": ".trellis/tasks/05-29-spec-governance-cleanup/research/spec-audit.md", "reason": "Audit findings and recommended spec cleanup scope"}
|
||||
@@ -0,0 +1,50 @@
|
||||
# Implementation Notes
|
||||
|
||||
## Decision
|
||||
|
||||
Use `trellis-spec-bootstarp` for the full spec audit and `trellis-update-spec`
|
||||
for targeted, incremental edits. Do not rebuild the whole spec tree because
|
||||
the `hyb-oa/` project specs are already high-signal and source-backed.
|
||||
|
||||
## Changes
|
||||
|
||||
- Removed Trellis default placeholder specs under `.trellis/spec/backend/` and
|
||||
`.trellis/spec/frontend/`.
|
||||
- Kept `.trellis/spec/backend/index.md` and `.trellis/spec/frontend/index.md`
|
||||
as short redirect indexes pointing to the real project specs.
|
||||
- Updated `frontend-react-vite-design.md` to clarify that it keeps
|
||||
hyb-oa-specific React/Vite/component/business-boundary contracts and should
|
||||
not copy broad `frontend-design` aesthetic guidance.
|
||||
- Replaced old new-work “Issue” authorization wording with “Trellis task” in:
|
||||
- `frontend-react-vite-design.md`
|
||||
- `deployment-trialrun.md`
|
||||
- `reimbursement-invoice-ocr.md`
|
||||
- Preserved historical Issue CSV references in governance/docs rules because
|
||||
they describe audit history, not new development authorization.
|
||||
|
||||
## Non-Changes
|
||||
|
||||
- No business code changed.
|
||||
- No frontend pages changed.
|
||||
- No backend API, Prisma schema, deployment script, production config,
|
||||
workflow/permission behavior or real data changed.
|
||||
- `docs/产品设计规则.md` was not changed because it already states that
|
||||
visual and interaction judgment belongs to `frontend-design`.
|
||||
|
||||
## Verification Plan
|
||||
|
||||
```bash
|
||||
rg -n "To be filled|Document your project's|active Issue|later Issue|Issue scope|Issue explicitly|separate approved Issue|Scaffold" .trellis/spec || true
|
||||
python3 ./.trellis/scripts/task.py validate 05-29-spec-governance-cleanup
|
||||
node scripts/qa/check-trellis-governance.mjs
|
||||
git diff --check
|
||||
```
|
||||
|
||||
## Verification Result
|
||||
|
||||
2026-05-29:
|
||||
|
||||
- Placeholder/old-Issue scan returned no findings.
|
||||
- `python3 ./.trellis/scripts/task.py validate 05-29-spec-governance-cleanup` passed.
|
||||
- `node scripts/qa/check-trellis-governance.mjs` passed.
|
||||
- `git diff --check` passed.
|
||||
@@ -0,0 +1,103 @@
|
||||
# Spec 治理与去噪审查
|
||||
|
||||
## Goal
|
||||
|
||||
对当前 `.trellis/spec/` 做一次轻量但系统的治理审查：确认哪些规则仍是稳定工程约束，哪些内容与 `frontend-design`、`docs/` 或任务证据重复，必要时去噪、合并和补强，让后续 AI 开发更容易遵守正确规则。
|
||||
|
||||
## What I Already Know
|
||||
|
||||
- 用户确认希望按建议执行：先用 `trellis-spec-bootstarp` 做全量体检，再用 `trellis-update-spec` 做具体落地。
|
||||
- 最近项目已经明确 Trellis-only，不再使用旧 `hyb-oa-delivery` skill。
|
||||
- 前端设计裁决来源已经转向 `frontend-design`，项目内旧前端设计规则如果重复或冲突，应以 `frontend-design` 和当前代码基线为准。
|
||||
- `.trellis/spec/hyb-oa/` 已存在项目级 spec：治理、前端、后端、审批、报销/OCR、企微、部署、文档证据、隐私等。
|
||||
- `docs/` 仍是业务事实源，spec 不应复制业务文档全文。
|
||||
- 当前还有 `05-26-oa-seven-day-trial-live-ops` 任务在进行，本任务不影响真实试运行。
|
||||
|
||||
## Requirements
|
||||
|
||||
### R1. 先审查，后修改
|
||||
|
||||
- 先形成 spec 体检报告，列出保留、合并、删除、补强建议。
|
||||
- 不在没有依据的情况下大规模重写 `.trellis/spec/`。
|
||||
- 每条修改必须能对应到当前项目事实、代码模式、流程约束或近期任务经验。
|
||||
|
||||
### R2. 明确文档边界
|
||||
|
||||
- `.trellis/spec/` 只放可复用工程约束、命令/API/状态/权限/部署/隐私等执行规则。
|
||||
- `docs/` 继续承载业务规则、公司运营事实、产品规则和手册。
|
||||
- `.trellis/tasks/` 继续承载单次任务需求、方案、证据和验收记录。
|
||||
|
||||
### R3. 前端设计规则去噪
|
||||
|
||||
- 检查 `.trellis/spec/hyb-oa/frontend-react-vite-design.md` 与 `docs/产品设计规则.md`、`frontend-design` skill 的关系。
|
||||
- 保留项目特有的 React/Vite、组件、布局和验证约束。
|
||||
- 避免在 spec 中重复大量通用审美规则；冲突时明确以 `frontend-design` 为前端设计裁决来源。
|
||||
|
||||
### R4. 保留硬边界
|
||||
|
||||
- 部署、公网检查、隐私、附件、企业微信、权限、审批、报销/OCR 等硬约束不得弱化。
|
||||
- 若发现 spec 缺少近期已稳定的执行规则，应补到对应 spec，而不是只留在任务记录。
|
||||
|
||||
### R5. 验证与收口
|
||||
|
||||
- 变更后必须通过 Trellis 任务校验、治理校验和 whitespace 检查。
|
||||
- 如果只做体检不改 spec，也必须把结论写入本任务 research。
|
||||
|
||||
## Scope
|
||||
|
||||
- `.trellis/spec/backend/index.md`
|
||||
- `.trellis/spec/frontend/index.md`
|
||||
- `.trellis/spec/hyb-oa/frontend-react-vite-design.md`
|
||||
- `.trellis/spec/hyb-oa/deployment-trialrun.md`
|
||||
- `.trellis/spec/hyb-oa/reimbursement-invoice-ocr.md`
|
||||
- 删除 `.trellis/spec/backend/` 和 `.trellis/spec/frontend/` 下默认占位模板文件。
|
||||
- 本任务 PRD、implementation notes 和 research 证据。
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] 已生成 spec 治理体检报告，覆盖 `.trellis/spec/hyb-oa/` 和 `.trellis/spec/guides/`。
|
||||
- [x] 已明确 `trellis-spec-bootstarp` 与 `trellis-update-spec` 的使用边界。
|
||||
- [x] 已治理重复、过期或冲突的 spec 内容，或明确记录“无需改动”的证据。
|
||||
- [x] 已明确 `frontend-design` 与项目本地前端规则的优先级。
|
||||
- [x] 未修改业务代码、数据库 schema、生产配置、部署脚本或真实数据。
|
||||
- [x] `python3 ./.trellis/scripts/task.py validate 05-29-spec-governance-cleanup` 通过。
|
||||
- [x] `node scripts/qa/check-trellis-governance.mjs` 通过。
|
||||
- [x] `git diff --check` 通过。
|
||||
|
||||
## Out Of Scope
|
||||
|
||||
- 不重写 `docs/` 业务事实源。
|
||||
- 不修改前端页面、后端 API、数据库、权限模型、审批状态机、企业微信配置或部署配置。
|
||||
- 不引入新 skill，不删除现有 Trellis skill。
|
||||
- 不把 spec 治理变成产品需求重写或公司制度整理。
|
||||
|
||||
## Test Plan
|
||||
|
||||
```bash
|
||||
rg -n "To be filled|Document your project's|active Issue|later Issue|Issue scope|Issue explicitly|separate approved Issue|Scaffold" .trellis/spec || true
|
||||
python3 ./.trellis/scripts/task.py validate 05-29-spec-governance-cleanup
|
||||
node scripts/qa/check-trellis-governance.mjs
|
||||
git diff --check
|
||||
```
|
||||
|
||||
## Technical Notes
|
||||
|
||||
- 主要审查对象：
|
||||
- `.trellis/spec/hyb-oa/*.md`
|
||||
- `.trellis/spec/guides/*.md`
|
||||
- `docs/产品设计规则.md`
|
||||
- 当前可用 `frontend-design` skill 的职责边界
|
||||
- 预期方法：
|
||||
- `trellis-spec-bootstarp`：用于全量审查和体系边界判断。
|
||||
- `trellis-update-spec`：用于把确认后的具体规则写入已有 spec。
|
||||
|
||||
## Implementation Result
|
||||
|
||||
2026-05-29 已完成：
|
||||
|
||||
- 体检报告：`research/spec-audit.md`。
|
||||
- 删除 `.trellis/spec/backend/` 和 `.trellis/spec/frontend/` 下的默认模板占位文件。
|
||||
- 保留 backend/frontend 两个 `index.md`，改成指向 `hyb-oa` 真实项目 spec 的短 redirect。
|
||||
- 更新 `frontend-react-vite-design.md`，明确本地 spec 不复制 `frontend-design` 的通用审美规则，只保留 hyb-oa 工程约束。
|
||||
- 将新开发授权口径从旧 “Issue” 改成 Trellis task。
|
||||
- 未修改业务代码、生产配置、部署脚本、数据库或真实数据。
|
||||
@@ -0,0 +1,87 @@
|
||||
# Spec 治理体检报告
|
||||
|
||||
## Method
|
||||
|
||||
按 `trellis-spec-bootstarp` 的口径审查现有 `.trellis/spec/`：
|
||||
|
||||
- 是否描述当前项目真实结构，而不是保留模板占位。
|
||||
- 是否把业务事实、任务证据和可复用工程约束分清。
|
||||
- 是否与 `frontend-design`、`docs/产品设计规则.md` 和 Trellis-only 口径一致。
|
||||
- 是否包含可执行的命令、签名、边界、错误矩阵或测试要求。
|
||||
|
||||
## Inventory
|
||||
|
||||
当前 spec 分三组：
|
||||
|
||||
- `.trellis/spec/hyb-oa/`：项目真实高信号规则，覆盖治理、前端、后端、审批、报销/OCR、企微、部署、文档证据、隐私。
|
||||
- `.trellis/spec/guides/`：跨层思考和复用思考清单。
|
||||
- `.trellis/spec/backend/`、`.trellis/spec/frontend/`：除 `index.md` 外，大量仍是 Trellis 默认脚手架，占位文案为 `To be filled by the team`。
|
||||
|
||||
## Findings
|
||||
|
||||
### F1. hyb-oa 主 spec 应保留
|
||||
|
||||
`hyb-oa/` 下规则大多是近期任务沉淀出的真实工程约束，包含命令、文件路径、边界、错误行为和测试要求。应作为当前唯一高信号项目 spec 主体保留。
|
||||
|
||||
代表文件：
|
||||
|
||||
- `project-governance.md`
|
||||
- `frontend-react-vite-design.md`
|
||||
- `backend-fastify-prisma.md`
|
||||
- `deployment-trialrun.md`
|
||||
- `docs-and-evidence.md`
|
||||
- `security-privacy.md`
|
||||
|
||||
### F2. backend/frontend 默认脚手架是噪音
|
||||
|
||||
`backend/` 和 `frontend/` 下多个文件仍含模板问题和 `To be filled by the team`，没有项目约束。它们会让后续 AI 误以为有一套待补充的并行规范。
|
||||
|
||||
建议：
|
||||
|
||||
- 删除这些占位文件。
|
||||
- 保留 `backend/index.md` 和 `frontend/index.md`，把它们改成 redirect/index，只指向 `hyb-oa` 项目真实 spec。
|
||||
|
||||
### F3. 少量旧 Issue 口径需要改为 Trellis task
|
||||
|
||||
Trellis-only 已是当前治理口径，但部分 spec 仍用 “Issue” 表达新任务授权：
|
||||
|
||||
- `frontend-react-vite-design.md`：`active Issue`
|
||||
- `deployment-trialrun.md`：`Issue explicitly authorizes`、`separate approved Issue`
|
||||
- `reimbursement-invoice-ocr.md`：`later Issue`、`Issue scope`
|
||||
|
||||
建议统一改为 “current Trellis task” 或 “separate approved Trellis task”。历史 Issue CSV 只保留为审计材料。
|
||||
|
||||
### F4. frontend-design 边界已基本正确
|
||||
|
||||
`docs/产品设计规则.md` 已声明前端视觉裁决交给 `frontend-design`，自身只保留产品体验事实。`frontend-react-vite-design.md` 也已声明 `frontend-design` 是设计 authority。
|
||||
|
||||
建议只补强一句：本地 spec 保留项目工程约束和组件/测试契约，不复制 `frontend-design` 的通用审美规则。
|
||||
|
||||
### F5. guides 可暂时保留
|
||||
|
||||
`guides/` 是思考清单，虽然偏通用，但没有模板占位，也不会与 hyb-oa 主 spec 冲突。暂不治理；后续只有在发现误导时再精简。
|
||||
|
||||
## Recommended Changes
|
||||
|
||||
1. 删除默认占位 spec 文件：
|
||||
- `.trellis/spec/backend/database-guidelines.md`
|
||||
- `.trellis/spec/backend/directory-structure.md`
|
||||
- `.trellis/spec/backend/error-handling.md`
|
||||
- `.trellis/spec/backend/logging-guidelines.md`
|
||||
- `.trellis/spec/backend/quality-guidelines.md`
|
||||
- `.trellis/spec/frontend/component-guidelines.md`
|
||||
- `.trellis/spec/frontend/directory-structure.md`
|
||||
- `.trellis/spec/frontend/hook-guidelines.md`
|
||||
- `.trellis/spec/frontend/quality-guidelines.md`
|
||||
- `.trellis/spec/frontend/state-management.md`
|
||||
- `.trellis/spec/frontend/type-safety.md`
|
||||
2. 将 `backend/index.md` 和 `frontend/index.md` 改成短 redirect index。
|
||||
3. 把新开发授权口径从 Issue 统一改为 Trellis task。
|
||||
4. 在 `frontend-react-vite-design.md` 明确不复制 `frontend-design` 通用审美规则。
|
||||
5. 跑 `rg "To be filled|Document your project's|active Issue|later Issue|Issue scope"` 验证噪音清除。
|
||||
|
||||
## Non-Changes
|
||||
|
||||
- 不重写 `hyb-oa/` 主 spec。
|
||||
- 不动 `docs/` 业务事实源。
|
||||
- 不修改业务代码、部署脚本、生产配置、数据库或测试逻辑。
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "spec-governance-cleanup",
|
||||
"name": "spec-governance-cleanup",
|
||||
"title": "Spec 治理与去噪审查",
|
||||
"description": "审查并治理 Trellis spec，删除占位噪音，统一 frontend-design 与 Trellis-only 规则边界。",
|
||||
"status": "completed",
|
||||
"dev_type": null,
|
||||
"scope": "trellis-spec-governance",
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "shunli",
|
||||
"assignee": "shunli",
|
||||
"createdAt": "2026-05-29",
|
||||
"completedAt": "2026-05-29",
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": null,
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
在新工单中引用
屏蔽一个用户