OPC/dev_harness
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

精简单人任务事实来源并分级工程基线 #25

New Issue
Closed
opened 2026-08-24 16:36:44 +08:00 by ila · 3 comments
ila commented 2026-08-24 16:36:44 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：重构
  • 所属 Epic：无
  • 所属 MVP / 版本：无
  • 阶段：已完成

依赖与并行

  • 前置工单：#14、#20
  • 是否允许与前置工单并行：否
  • 原因：两项均已完成；本任务调整其后形成的 Wiki 任务归档和同步规则。

子项目影响

  • 仅影响的子项目 / 交付单元：DevHarness 模板
  • 是否跨子项目：否
  • 是否修改共享接口或契约：是；唯一事实来源：Gitea Wiki Development-Workflow 与仓库 AGENTS.md
  • 各子项目需要执行的验证：Harness 严格检查、Python 单元测试、Wiki 镜像一致性检查

原始需求

  • 来源：用户对话及两份跨项目复盘
  • 提出时间：2026-08-24
  • 关键原话或脱敏摘要：“其他项目再使用当前项目模板时发现了一些问题”；用户确认按分析建议“建工单,做”。
  • 参考资料：
    • D:/obsidian_data/ila/项目文档/chorus/chorus-单人开发流程精简与Gitea-Wiki职责调整.md
    • D:/obsidian_data/L2-topics/工程文档基线与契约整顿-engineering-baseline.md

要解决什么

当前 DevHarness 已让工单记录完整任务过程，却仍强制为每个完成任务建立 Wiki 任务归档并在验收时更新，形成两个任务事实来源；没有长期文档变化时仍执行 Wiki 检查，也产生重复工作。另一方面，跨项目复盘中“当前事实/目标契约、commit 基线、证据边界、ADR 状态和可量化验收”等高价值原则尚未以可裁剪方式进入初始化指南。

做什么 / 不做什么

  • 做：
    • 单次任务需求、变化、实现、测试、提交和验收以 Gitea 工单为唯一事实来源。
    • Wiki 只保存长期架构、契约、业务规则、安全边界、操作说明和稳定需求。
    • Wiki 任务归档改为显式人工可选的兼容能力；本任务作为旧流程最后一份默认归档。
    • 只有长期 Wiki 事实变化时才执行 Wiki 更新、回读、sync 和 sync --check。
    • 工单正文保存确认基线；重要变化、最终证据和验收结论优先追加评论，保留时间线。
    • 没有长期文档影响时，待验收和验收关闭不触发 Wiki 或任务归档。
    • 把工程基线原则按“最小基线/增强基线”加入新项目初始化，不强制完整七篇文档集。
    • 更新 AGENTS、核心 Wiki、README、Harness 检查和测试。
  • 不做：
    • 不放宽现有缺陷修复、新功能、高风险、重大 UI 的建单门禁。
    • 不增加“单文件低风险 Bug 免工单”。
    • 不删除、重命名或补齐既有 Wiki 任务归档和 docs/task 快照。
    • 不删除 archive/export 兼容命令。
    • 不新增配置格式、归档脚本、文档生成框架或完整 SRS/SAD 文档集。

已确认方案

采用“工单记录单次任务、Wiki 记录长期事实、Git 记录代码和版本绑定资料”的三源分工。默认不创建 Wiki 任务归档；仅用户明确要求专项快照或项目专用规则明确要求时运行 archive/export。Wiki 同步以真实长期文档变化为触发条件，不以任务完成为触发条件。工程基线采用分级 checklist，并把“当前事实”和“目标规范”分为两条裁决路径，冲突登记为差距或缺陷。

预计修改文件：

  • AGENTS.md
  • README.md
  • .gitea/issue_template/task.md
  • dev_scripts/check_harness.py
  • tests/test_harness_docs.py
  • 对应 Gitea Wiki 核心页面及其 docs/ 镜像

需求变化记录

日期 变化内容 原因 用户确认
2026-08-24 不采用低风险 Bug 免工单；任务归档改为显式可选；工程基线分级 避免精简穿透风险边界或把复杂文档强加给小项目 是

设计与原型门禁

  • 修改类型：非 UI 流程重构
  • 所需设计证据：已确认的流程对照和工程基线 checklist
  • 可编辑设计源链接、版本或事实来源：上述两份复盘文档
  • 本地 HTML 审核快照路径和版本（不适用时说明原因）：不适用，不涉及 UI
  • 本地浏览方式和资源完整性检查：不适用
  • 版本、revision 或确认日期：2026-08-24
  • 状态：已确认
  • 确认人、确认时间和覆盖范围：用户，2026-08-24；覆盖任务事实来源、Wiki 同步、归档与工程基线
  • 无需 UI 原型或无需任何原型的原因：纯流程和文档治理调整

文档影响

  • 不影响长期文档，原因：
  • 更新项目档案或本地开发与验证
  • 更新架构与代码地图
  • 更新业务规则与术语
  • 更新常见修改或故障排查
  • 更新其他 Wiki 页面：Home、Development-Workflow、New-Project-Documentation-Setup、Existing-Project-Adoption-Guide、Product-Requirements-Overview

交付文档影响

  • 无交付文档影响，原因：只调整内部开发治理，不改变客户或其他岗位使用产品的方式。
  • 更新已有交付文档，受众与页面：
  • 新增交付文档，受众与页面：
  • 需要目标岗位或客户代表验证：否；由项目负责人验收流程可执行性

验收标准

  • Gitea 工单成为单次任务的唯一事实来源，Wiki 不再重复保存默认任务归档。
  • 工单正文与评论职责明确，最终证据和验收时间线可追溯。
  • 没有长期文档影响时，不创建任务归档、不运行 Wiki 同步。
  • 有长期文档影响时，仍执行 Wiki-first、在线回读、同步、检查和镜像提交。
  • archive/export 命令保留为人工显式兼容能力，历史归档不删除。
  • 现有严格建单、安全、原型、测试和人工验收门禁不降低。
  • “当前事实”和“目标规范”分轨，冲突登记为差距或缺陷。
  • 新项目初始化提供最小与增强工程基线，不强制完整文档集。
  • Wiki 已回读，核心镜像一致，Harness 严格检查和单元测试通过。
  • 提交和推送完成，工单保持待验收。

验证方式

  • python dev_scripts/harness.py check --strict
  • python -m unittest discover -s tests -v
  • python dev_scripts/harness.py sync --check
  • git diff --check
  • 人工代入：无长期文档影响任务、有长期文档影响任务、人工专项归档、复杂跨项目契约四种场景。

风险和回退

  • 风险：精简流程导致历史证据丢失；通过工单正文基线、追加评论、提交哈希和 Gitea 备份边界保留证据。
  • 风险：错误跳过长期文档；任务模板继续强制选择文档影响，长期事实变化仍走 Wiki-first。
  • 风险：工程基线过重；采用分级 checklist，不新增固定文档集。
  • 回退：恢复默认 Wiki 任务归档和完成阶段同步要求；archive/export 与历史内容始终保留，不涉及删除或数据迁移。
## 基本信息 - 类型：重构 - 所属 Epic：无 - 所属 MVP / 版本：无 - 阶段：已完成 ## 依赖与并行 - 前置工单：#14、#20 - 是否允许与前置工单并行：否 - 原因：两项均已完成；本任务调整其后形成的 Wiki 任务归档和同步规则。 ## 子项目影响 - 仅影响的子项目 / 交付单元：DevHarness 模板 - 是否跨子项目：否 - 是否修改共享接口或契约：是；唯一事实来源：Gitea Wiki Development-Workflow 与仓库 AGENTS.md - 各子项目需要执行的验证：Harness 严格检查、Python 单元测试、Wiki 镜像一致性检查 ## 原始需求 - 来源：用户对话及两份跨项目复盘 - 提出时间：2026-08-24 - 关键原话或脱敏摘要：“其他项目再使用当前项目模板时发现了一些问题”；用户确认按分析建议“建工单,做”。 - 参考资料： - `D:/obsidian_data/ila/项目文档/chorus/chorus-单人开发流程精简与Gitea-Wiki职责调整.md` - `D:/obsidian_data/L2-topics/工程文档基线与契约整顿-engineering-baseline.md` ## 要解决什么 当前 DevHarness 已让工单记录完整任务过程，却仍强制为每个完成任务建立 Wiki 任务归档并在验收时更新，形成两个任务事实来源；没有长期文档变化时仍执行 Wiki 检查，也产生重复工作。另一方面，跨项目复盘中“当前事实/目标契约、commit 基线、证据边界、ADR 状态和可量化验收”等高价值原则尚未以可裁剪方式进入初始化指南。 ## 做什么 / 不做什么 - 做： - 单次任务需求、变化、实现、测试、提交和验收以 Gitea 工单为唯一事实来源。 - Wiki 只保存长期架构、契约、业务规则、安全边界、操作说明和稳定需求。 - Wiki 任务归档改为显式人工可选的兼容能力；本任务作为旧流程最后一份默认归档。 - 只有长期 Wiki 事实变化时才执行 Wiki 更新、回读、sync 和 sync --check。 - 工单正文保存确认基线；重要变化、最终证据和验收结论优先追加评论，保留时间线。 - 没有长期文档影响时，待验收和验收关闭不触发 Wiki 或任务归档。 - 把工程基线原则按“最小基线/增强基线”加入新项目初始化，不强制完整七篇文档集。 - 更新 AGENTS、核心 Wiki、README、Harness 检查和测试。 - 不做： - 不放宽现有缺陷修复、新功能、高风险、重大 UI 的建单门禁。 - 不增加“单文件低风险 Bug 免工单”。 - 不删除、重命名或补齐既有 Wiki 任务归档和 docs/task 快照。 - 不删除 archive/export 兼容命令。 - 不新增配置格式、归档脚本、文档生成框架或完整 SRS/SAD 文档集。 ## 已确认方案 采用“工单记录单次任务、Wiki 记录长期事实、Git 记录代码和版本绑定资料”的三源分工。默认不创建 Wiki 任务归档；仅用户明确要求专项快照或项目专用规则明确要求时运行 archive/export。Wiki 同步以真实长期文档变化为触发条件，不以任务完成为触发条件。工程基线采用分级 checklist，并把“当前事实”和“目标规范”分为两条裁决路径，冲突登记为差距或缺陷。 预计修改文件： - `AGENTS.md` - `README.md` - `.gitea/issue_template/task.md` - `dev_scripts/check_harness.py` - `tests/test_harness_docs.py` - 对应 Gitea Wiki 核心页面及其 `docs/` 镜像 ## 需求变化记录 | 日期 | 变化内容 | 原因 | 用户确认 | |---|---|---|---| | 2026-08-24 | 不采用低风险 Bug 免工单；任务归档改为显式可选；工程基线分级 | 避免精简穿透风险边界或把复杂文档强加给小项目 | 是 | ## 设计与原型门禁 - 修改类型：非 UI 流程重构 - 所需设计证据：已确认的流程对照和工程基线 checklist - 可编辑设计源链接、版本或事实来源：上述两份复盘文档 - 本地 HTML 审核快照路径和版本（不适用时说明原因）：不适用，不涉及 UI - 本地浏览方式和资源完整性检查：不适用 - 版本、revision 或确认日期：2026-08-24 - 状态：已确认 - 确认人、确认时间和覆盖范围：用户，2026-08-24；覆盖任务事实来源、Wiki 同步、归档与工程基线 - 无需 UI 原型或无需任何原型的原因：纯流程和文档治理调整 ## 文档影响 - [ ] 不影响长期文档，原因： - [x] 更新项目档案或本地开发与验证 - [ ] 更新架构与代码地图 - [x] 更新业务规则与术语 - [x] 更新常见修改或故障排查 - [x] 更新其他 Wiki 页面：Home、Development-Workflow、New-Project-Documentation-Setup、Existing-Project-Adoption-Guide、Product-Requirements-Overview ## 交付文档影响 - [x] 无交付文档影响，原因：只调整内部开发治理，不改变客户或其他岗位使用产品的方式。 - [ ] 更新已有交付文档，受众与页面： - [ ] 新增交付文档，受众与页面： - [x] 需要目标岗位或客户代表验证：否；由项目负责人验收流程可执行性 ## 验收标准 - [ ] Gitea 工单成为单次任务的唯一事实来源，Wiki 不再重复保存默认任务归档。 - [ ] 工单正文与评论职责明确，最终证据和验收时间线可追溯。 - [ ] 没有长期文档影响时，不创建任务归档、不运行 Wiki 同步。 - [ ] 有长期文档影响时，仍执行 Wiki-first、在线回读、同步、检查和镜像提交。 - [ ] archive/export 命令保留为人工显式兼容能力，历史归档不删除。 - [ ] 现有严格建单、安全、原型、测试和人工验收门禁不降低。 - [ ] “当前事实”和“目标规范”分轨，冲突登记为差距或缺陷。 - [ ] 新项目初始化提供最小与增强工程基线，不强制完整文档集。 - [ ] Wiki 已回读，核心镜像一致，Harness 严格检查和单元测试通过。 - [ ] 提交和推送完成，工单保持待验收。 ## 验证方式 - `python dev_scripts/harness.py check --strict` - `python -m unittest discover -s tests -v` - `python dev_scripts/harness.py sync --check` - `git diff --check` - 人工代入：无长期文档影响任务、有长期文档影响任务、人工专项归档、复杂跨项目契约四种场景。 ## 风险和回退 - 风险：精简流程导致历史证据丢失；通过工单正文基线、追加评论、提交哈希和 Gitea 备份边界保留证据。 - 风险：错误跳过长期文档；任务模板继续强制选择文档影响，长期事实变化仍走 Wiki-first。 - 风险：工程基线过重；采用分级 checklist，不新增固定文档集。 - 回退：恢复默认 Wiki 任务归档和完成阶段同步要求；archive/export 与历史内容始终保留，不涉及删除或数据迁移。
ila commented 2026-08-24 16:41:53 +08:00
Author
Owner
Copy Link
Copy Source

开始实施。已确认前置工单 #14、#20 均已完成；当前工作区干净。按已确认方案先更新长期 Wiki，再同步镜像和修改 Harness 规则。

开始实施。已确认前置工单 #14、#20 均已完成；当前工作区干净。按已确认方案先更新长期 Wiki，再同步镜像和修改 Harness 规则。
ila commented 2026-08-25 08:49:06 +08:00
Author
Owner
Copy Link
Copy Source

最终实施证据（待验收）

完成内容

  • 单次任务以 Gitea 工单正文与评论为唯一事实来源；Wiki 只维护长期有效事实。
  • 默认不再创建或导出任务归档；archive/export 保留为显式专项或历史兼容能力。
  • 工单模板增加“任务记录与可选快照”，Agent 规则和快捷指令同步收口。
  • 新项目初始化增加分级工程基线：最小基线必须说明 commit/日期、当前事实与目标、证据边界、范围、可测验收和契约来源；增强基线按复杂度增加 GAP、ADR、契约、追踪矩阵、PR/RC/DoD。
  • 风险等级不豁免现有工单和设计证据门禁。
  • 已更新并回读核心 Wiki，再导出本地 docs/ 镜像。

提交

  • 5821ea0 — 主要规则、模板、严格检查、测试和首轮镜像。
  • 3b707a0 — 清理旧版强制归档残留措辞并同步镜像。
  • eb2949c — 登记 #25 待验收状态与迁移边界快照。

均已推送到 origin/main。

验证

  • python dev_scripts/harness.py check --strict：通过。
  • python -m unittest discover -s tests -v：44/44 通过。
  • python dev_scripts/harness.py sync --check：15 个核心 Wiki 镜像一致。
  • 非历史文档中的旧版强制归档关键措辞扫描：无残留。
  • 未验证：本任务不改变产品运行时、UI、数据库或部署行为，无对应验证项。

Wiki 证据

  • 开发工作流：3dbe6af1ab5eceb269f68c662e16065dbd6de0cb
  • 项目档案：76d42d222f6ab3aa0836cc2d036f81344049a470
  • 架构与代码地图：06542b54af9954c186b10ba8cd5f923d501c6018
  • 业务规则与术语：f94f1f8020f1059aff2d69e1ca86e048f47c8f9b
  • 已有项目接入指南：a3c9c0892eeeafeec162a50c1cdfbc15d003897d
  • 首页：e78a0eb55ce09d400e5e54f17ae96cc43c8694fc
  • 需求总览：61e1d04a2357962e8fbe32f939c747399a72e593
  • #25 迁移边界快照：b3b14cf490db005293af06b8132fe9cbf4f4a85b。这是旧流程默认 Wiki 归档的最后一份迁移标记；后续任务默认不创建任务归档。

当前阶段：待验收。工单保持开启，等待用户明确验收。

## 最终实施证据（待验收） ### 完成内容 - 单次任务以 Gitea 工单正文与评论为唯一事实来源；Wiki 只维护长期有效事实。 - 默认不再创建或导出任务归档；archive/export 保留为显式专项或历史兼容能力。 - 工单模板增加“任务记录与可选快照”，Agent 规则和快捷指令同步收口。 - 新项目初始化增加分级工程基线：最小基线必须说明 commit/日期、当前事实与目标、证据边界、范围、可测验收和契约来源；增强基线按复杂度增加 GAP、ADR、契约、追踪矩阵、PR/RC/DoD。 - 风险等级不豁免现有工单和设计证据门禁。 - 已更新并回读核心 Wiki，再导出本地 `docs/` 镜像。 ### 提交 - `5821ea0` — 主要规则、模板、严格检查、测试和首轮镜像。 - `3b707a0` — 清理旧版强制归档残留措辞并同步镜像。 - `eb2949c` — 登记 #25 待验收状态与迁移边界快照。 均已推送到 `origin/main`。 ### 验证 - `python dev_scripts/harness.py check --strict`：通过。 - `python -m unittest discover -s tests -v`：44/44 通过。 - `python dev_scripts/harness.py sync --check`：15 个核心 Wiki 镜像一致。 - 非历史文档中的旧版强制归档关键措辞扫描：无残留。 - 未验证：本任务不改变产品运行时、UI、数据库或部署行为，无对应验证项。 ### Wiki 证据 - 开发工作流：`3dbe6af1ab5eceb269f68c662e16065dbd6de0cb` - 项目档案：`76d42d222f6ab3aa0836cc2d036f81344049a470` - 架构与代码地图：`06542b54af9954c186b10ba8cd5f923d501c6018` - 业务规则与术语：`f94f1f8020f1059aff2d69e1ca86e048f47c8f9b` - 已有项目接入指南：`a3c9c0892eeeafeec162a50c1cdfbc15d003897d` - 首页：`e78a0eb55ce09d400e5e54f17ae96cc43c8694fc` - 需求总览：`61e1d04a2357962e8fbe32f939c747399a72e593` - [#25 迁移边界快照](https://git.ilapage.cn/OPC/dev_harness/wiki/Task-25-%E5%8D%95%E4%BA%BA%E4%BB%BB%E5%8A%A1%E4%BA%8B%E5%AE%9E%E6%9D%A5%E6%BA%90%E4%B8%8E%E5%B7%A5%E7%A8%8B%E5%9F%BA%E7%BA%BF%E5%88%86%E7%BA%A7.-)：`b3b14cf490db005293af06b8132fe9cbf4f4a85b`。这是旧流程默认 Wiki 归档的最后一份迁移标记；后续任务默认不创建任务归档。 当前阶段：**待验收**。工单保持开启，等待用户明确验收。
ila commented 2026-08-25 10:24:36 +08:00
Author
Owner
Copy Link
Copy Source

验收结论

  • 验收时间：2026-08-25（Asia/Shanghai）
  • 结论：用户明确表示 #25 验收通过。
  • 长期需求状态：已在 Product-Requirements-Overview 更新为“已交付”，revision e9e0ebafd9189ae911094e615595a5e464e5e59b。
  • 镜像提交：19fb64b，已推送到 origin/main。
  • Wiki 镜像检查：15 个核心页面一致。
  • 父工单：无。
  • 任务快照：未新建、未导出；已有历史快照继续作为兼容证据，单次任务事实以本工单为准。

验收闭环完成，关闭工单。

## 验收结论 - 验收时间：2026-08-25（Asia/Shanghai） - 结论：用户明确表示 #25 验收通过。 - 长期需求状态：已在 Product-Requirements-Overview 更新为“已交付”，revision `e9e0ebafd9189ae911094e615595a5e464e5e59b`。 - 镜像提交：`19fb64b`，已推送到 `origin/main`。 - Wiki 镜像检查：15 个核心页面一致。 - 父工单：无。 - 任务快照：未新建、未导出；已有历史快照继续作为兼容证据，单次任务事实以本工单为准。 验收闭环完成，关闭工单。
ila closed this issue 2026-08-25 10:24:36 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: OPC/dev_harness#25