diff --git a/CHANGELOG.md b/CHANGELOG.md index ad2304b..57cadcf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,15 @@ - 使用校验和固定的 `actionlint` 检查 GitHub Actions 语义，并将官方 Actions 固定到完整 commit SHA。 - 本地发布检查与 CI 使用相同的 Markdown 和 Harness contract 入口，避免只在 GitHub 上发现结构问题。 +## Review Finding Receiving / Fix Loop - 2026-07-23 + +- 在 Plan、Code Review 和 Fix 三个角色中正向建立 Review Finding Receiving / Fix Loop 心智：artifact owner（Plan Writer / Fix）收到 finding 后先 Receiving（理解→核对→判断→响应），成立且在 scope 内时最小修正并验证，不成立或依据不足时返回依据，含义不清时返回澄清问题，改变需求时标记决策点交回小P和秦鹏。 +- 修正 Plan Reviewer 和 Code Reviewer 的复审语义：复审修正或有依据的反馈，不只看是否按建议修改；接受反馈理由和证据时可以关闭 finding，信息不足时澄清或修订 finding，争议涉及需求或范围时经小P交秦鹏。所有开放 finding 闭合后才给出当前 gate GO。 +- 明确小P的 finding 路由边界：保留 finding 原意和证据路由给 artifact owner，不预判 finding 成立或有效，不替 artifact owner 完成 Receiving，不替 Reviewer 判断 finding 是否闭合。原 Reviewer 不可用时选择另一位独立于 artifact owner 的 Reviewer 接续，并完整移交上下文，不随意换人绕过分歧。 +- 删除 `roles/fix.md`、`docs/2026-07-20-harness-core-workflow-spec.md` 和 `HARNESS.md` 中将 finding 预判为"有效 finding""已确认 finding""确认应修复"等诱发盲目执行的旧表达；改为"已路由 finding""对已路由 finding 完成 Receiving""判断并响应 finding"。 +- `roles/plan-writer.md` 和 `roles/fix.md` 新增 Receiving 责任段；`roles/plan-reviewer.md` 和 `roles/code-reviewer.md` 新增复审反馈规则；`roles/coordinator.md` 新增 finding 路由边界与 Reviewer 改派规则。 +- 本次只调整 Harness 文档和角色心智，不新增状态机、finding 数据库、强制 disposition 表、新 Reviewer 身份或语义 marker validator；不改变 `scripts/validate_repository.py` 或 `tests/` 的现有结构 contract。 + ## Event-driven orchestration mindset - 2026-07-23 - 在设计北极星中正向定义秦鹏、小P、云上C总、小C或云上小C的稳定身份：小P是中心编排者和状态所有者，云上C总是承担 Plan Writer 与 Code Reviewer 的架构师，实现 Bot 负责编码与自检。 diff --git a/HARNESS.md b/HARNESS.md index 20bf49a..dc9127d 100644 --- a/HARNESS.md +++ b/HARNESS.md @@ -36,7 +36,7 @@ Harness 先确定具体协作主体，再理解它们在不同阶段承担的角 | 云上C总 | 架构师 | 作为 Plan Writer 把 confirmed Spec 转成可执行 Plan；实现完成后作为非实现方 Code Reviewer 独立审查结果 | | 小C或云上小C | 当前群 live discovery 唯一解析的实现者 | 作为 Implementer 在指定 workspace 实现、自检并交付可 Review 结果；收到 finding 后进入 Fix | -Plan Writer 不批准自己的 Plan，Implementer 不批准自己的实现。Code Reviewer 默认是云上C总在 Review 阶段承担的职责，不是一个身份不明的常驻 Bot；只有秦鹏明确改变分工，或云上C总是本轮实现方时，小P才路由给另一个经确认的非本轮实现方。Fix 也不是新的 Bot 身份，而是原实现方处理已路由 finding 时重新进入的工作角色。 +Plan Writer 不批准自己的 Plan，Implementer 不批准自己的实现。Code Reviewer 默认是云上C总在 Review 阶段承担的职责，不是一个身份不明的常驻 Bot；只有秦鹏明确改变分工，或云上C总是本轮实现方时，小P才路由给另一个经确认的非本轮实现方。Fix 也不是新的 Bot 身份，而是原实现方对已路由 finding 完成 Receiving 时重新进入的工作角色。 稳定角色心智位于 `roles/`。小P始终读取角色接口；目标 Bot 尚未稳定拥有对应心智时，派工随 Task Brief 附简短 Role Card 或目标可读的明确引用，已经具备时只发送 Task Brief。 diff --git a/HARNESS_DESIGN_PRINCIPLES.md b/HARNESS_DESIGN_PRINCIPLES.md index 973e341..d00fc15 100644 --- a/HARNESS_DESIGN_PRINCIPLES.md +++ b/HARNESS_DESIGN_PRINCIPLES.md @@ -31,7 +31,7 @@ Harness 先建立具体协作主体的稳定心智，再说明它们在不同阶 每个阶段角色应专注一个主要问题，并对一个清楚结果负责。 -Plan writer 把 Spec 变成可执行 Plan，不批准自己的 Plan；Plan reviewer 判断 Plan 是否忠实、清楚、可执行；implementer 完成当前工作并自检；reviewer 独立判断结果；fix 只处理已经路由的 finding。 +Plan writer 把 Spec 变成可执行 Plan，不批准自己的 Plan；Plan reviewer 判断 Plan 是否忠实、清楚、可执行；implementer 完成当前工作并自检；reviewer 独立判断结果；fix 接收已经路由的 finding，独立核对其是否成立，并根据判断完成修正、反馈或提出决策点。 这些角色是具体主体在某个阶段承担的职责，不是身份不明的新 Bot。默认由小P Review 云上C总写的 Plan，由云上C总 Review 小C或云上小C的实现；如果默认分工会造成自写自批，小P必须路由给另一个经确认的非产出方。小P负责选择角色和路由结果，不把多个角色重新合并到自己身上。 @@ -61,11 +61,11 @@ Plan writer 定义 Unit、完成条件和 gate；小P在收到并确认正式结 ## 7. 优先塑造心智，而不是堆规则 -Harness 应先说清角色、目标、边界、结果和协作语义，让智能体能够判断和发挥。 +Harness 应先说清角色、目标、边界、结果和协作语义，让智能体能够判断和发挥。能够通过正向心智、充分上下文和清楚协作语义解决的问题，不增加负向规则。 -复杂流程仍需要少量薄协议，保护经常丢失或容易被绕过的交接点。但协议不是证据表格：代码、测试、日志、截图和 review finding 是认真工作后自然留下的结果，不应为了填表而重复制造。 +复杂流程仍需要少量薄协议，保护需求权威、角色分离、审批关系、不可逆操作等后果严重的边界。但协议不是证据表格：代码、测试、日志、截图和 review finding 是认真工作后自然留下的结果，不应为了填表而重复制造。 -只有真实运行反复证明某个问题仅靠清楚心智仍不稳定时，才为它增加一条最小 guardrail。 +只有问题会破坏上述严重边界，或者真实运行反复证明它会造成高成本失败且仅靠清楚心智仍不稳定时，才为它增加一条最小 guardrail。除此之外，任务策略和具体交互方式有意留给智能体根据现场判断。 ## 8. 区分协议、心智和策略 @@ -96,3 +96,5 @@ Harness 重构的目标不是文档统一、字段增多或模板更整齐，而 5. Plan 和 Execution Unit 是否能够完成、验证和交接？ 6. 这次修改的是协议、角色心智还是任务策略，是否改对了层？ 7. 真实流程是否能通过角色间的正式交接最终到达交付，而不是依赖小P持续监控其他 Bot？ +8. 目标行为能否通过正向心智、充分上下文或清楚协作语义解决，而不增加负向规则？ +9. 新增 guardrail 是否确实保护严重边界或反复的高成本失败，并把其余策略空间留给智能体？ diff --git a/README.md b/README.md index 4478268..350f9cd 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ Harness 在当时的目标项目 workspace 中执行。本仓库是控制面， ```text workspace 已指定 + 实现方已从群内唯一解析 → 需求输入 → confirmed Spec → Plan 写审分离 -→ Implementation → 独立 Code Review → Fix 后复审 +→ Implementation → 独立 Code Review → Fix Receiving 后复审 → live verification → submit / CI → close ``` diff --git a/docs/2026-07-20-harness-core-workflow-spec.md b/docs/2026-07-20-harness-core-workflow-spec.md index e396833..9824a98 100644 --- a/docs/2026-07-20-harness-core-workflow-spec.md +++ b/docs/2026-07-20-harness-core-workflow-spec.md @@ -106,9 +106,9 @@ Harness 先正向定义具体协作主体，再说明它们在不同阶段承担 ### 4.6 Fix -Fix 不是新的长期 Bot 身份，而是实现方收到有效 finding 后重新进入的工作角色： +Fix 不是新的长期 Bot 身份，而是实现方收到已路由 finding 后重新进入的工作角色： -> 我的职责是理解已确认的 finding，在原 scope 内完成定向修复并重新验证。若 finding 实际改变需求，应交回小P和秦鹏，不应自行扩大范围。 +> 我的职责是对已路由的 finding 完成 Receiving（理解→核对→判断→响应）。成立且在 scope 内时最小修正并验证；不成立或依据不足时返回依据；含义不清时返回澄清问题；实际改变需求时标记决策点交回小P和秦鹏。 ### 4.7 心智如何落地 @@ -156,7 +156,7 @@ workspace 与实现方已由秦鹏指定（Harness 外部前置条件） - Plan writer 不能给自己的 Plan 判定 GO。 - Plan 没有说清任务边界时，小P退回 Plan，不替 Plan writer 编造实现步骤。 -- Code review finding 先由小P判断应进入 fix、需求决策还是 blocked。 +- Code review finding 先由小P路由到 Fix、需求决策或 blocked；小P不预判 finding 是否成立。 - Fix 完成只表示可以重新 review；必须由 code reviewer 给出 GO，才能进入小P收口。 - 一个 gate 的 GO 只表示允许进入下一步，不等于 submitted、deployed、verified 或 closed。 - 缺仓库、权限、登录、工具、可读上下文或 runtime 条件时，当前节点进入 blocked；条件恢复后回到中断处继续。 diff --git a/docs/2026-07-23-review-finding-reception-plan.md b/docs/2026-07-23-review-finding-reception-plan.md new file mode 100644 index 0000000..8fd2373 --- /dev/null +++ b/docs/2026-07-23-review-finding-reception-plan.md @@ -0,0 +1,134 @@ +# sayToLittleP Review Finding Reception / Fix Loop Plan + +日期：2026-07-23 +状态：submitted — PR #4 open, CI passed +Authority：`docs/2026-07-23-review-finding-reception-spec.md`（confirmed，commit `8c984f1`） +北极星：`HARNESS_DESIGN_PRINCIPLES.md`（commit `c99119c`） +分支：`fix/review-finding-reception` +Implementer：小C +Plan Writer：云上C总 +Plan Reviewer：小P +Code Reviewer：云上C总（默认） + +## Outcome + +建立一个同时适用 Plan 与 Code 的轻量 Receiving / Fix Loop：artifact owner（Plan Writer / Fix）收到 Reviewer finding 后先 Receiving（理解→核对→判断→响应）——成立且在 scope 内则最小修正+验证；不成立/依据不足/含义不清/改变需求则返回依据、澄清问题或决策点；原 Reviewer 复审修正或有依据的反馈并决定关闭/澄清/修订/升级；所有开放 finding 闭合后才给出当前 gate `GO`。小P只路由 finding 与守 gate，不替双方做专业判断。 + +不引入通用状态机、finding 数据库、强制 disposition 表、新模板或常驻 Reviewer；不新增前置 Code Review；不写死逐项/批量 at。边界 Review 建议已由秦鹏判为非阻塞，不升级为规则。 + +## Current Evidence（live doc @ `8c984f1`） + +- **待修 pre-classify 文案**（finding 被预判为有效/已确认/必改）： + - `roles/fix.md:5`「何时选择：小P确认 Code Review finding 应在原 scope 内修复时」；`:12`「处理有效 finding 时重新进入的工作角色」；`:16`「只在原 scope 内修复已确认 finding」。 + - `docs/2026-07-20-harness-core-workflow-spec.md:109`「收到有效 finding 后重新进入」；`:111`「理解已确认的 finding」；`:159`「Code review finding 先由小P判断应进入 fix…」。 + - `HARNESS.md:39`「处理已路由 finding 时重新进入的工作角色」（"处理"弱化判断）。 +- **缺失**：`roles/plan-writer.md`、`roles/fix.md` 无显式 Receiving 责任；`roles/plan-reviewer.md:20`、`roles/code-reviewer.md:19` 只说"问题闭合后 GO / Fix 后重新 Review"，未提"复审修正**或有依据的反馈**"；`roles/coordinator.md` 未显式"不预判 finding 成立 / 不替 artifact owner 判断 / 不替 Reviewer 判闭环 / 原 Reviewer 不可用改派独立 Reviewer + 完整上下文"。 +- **contract 基线**：`scripts/validate_repository.py` 检查 required files / UTF-8 / 结尾换行 / 冲突标记 / 静态 Bot open_id / 相对链接 / role card 三段标题（角色接口/工作心智/判断与边界）/ HARNESS 九节标题 / task-brief 字段 + at-bot 契约；`tests/test_validate_repository.py` 为其单元测试。无 finding 语义检查。 +- **北极星约束**：§7/§9 与 `core-workflow-spec.md:278` 明确反对"只检查文件/字符串存在的一致性脚本"；§9 要求"通过真实或代表性流程运行观察角色接力"。故验证以代表性 Pilot 为主、contract 仅保结构+最小不变量。 + +## Design Decisions + +### DD1 — Receiving 心智 + 文案原则（先正向补心智，再删诱发盲目执行的旧表达） + +- 在 `roles/plan-writer.md`、`roles/fix.md` 的工作心智/判断与边界补 **Receiving 责任**：理解→核对→判断→响应；成立且在 scope 内→最小修正+验证；不成立/依据不足→返回依据；含义不清→返回澄清；改变需求/取舍→标记决策点交小P。不因 Reviewer 语气/身份直接执行，也不草率拒绝。 +- 在 `roles/plan-reviewer.md`、`roles/code-reviewer.md` 补"**复审修正或有依据的反馈**"：不只检查是否按建议修改；接受反馈可关闭；信息不足→澄清/修订 finding（不机械重复）；争议涉需求/范围/取舍→经小P交秦鹏。 +- **文案修正**（`roles/fix.md`、`core-workflow-spec.md`、`HARNESS.md`）：删"有效 finding/已确认 finding/确认应修复"等预判表达，改为"待判断的 finding / 已路由的 finding / 判断并响应 finding"；`fix.md:5`「何时选择」改为"小P把 finding 路由给 Fix 时"（不预判应在 scope 内修复）；`HARNESS.md:39`「处理已路由 finding」→「对已路由 finding 完成 Receiving」。 +- 不新增 heading/字段/状态机；在现有「工作心智/判断与边界」段内补充。 + +### DD2 — Plan Review receiving loop（Spec §6.1） + +Plan Reviewer 输出有证据/后果/最小修正方向的 finding → 小P路由回 Plan Writer（**不预判成立**）→ Plan Writer Receiving（对照 confirmed Spec/仓库现状/角色边界/可执行性）→ 修订 Plan 或返回依据/澄清 → 原 Plan Reviewer 复审 → 全闭合 → Plan Review `GO`。Plan Writer 不得借 Receiving 改 confirmed Spec；Reviewer 不得要求实现阶段尚未产生的证据写进 Plan。不写死逐项/批量 at。 + +### DD3 — Code Review receiving loop（Spec §6.2） + +Code Reviewer 输出有代码/行为依据的 finding → 小P路由给 Fix / 需求决策 / blocked（**不替 Fix 判断技术结论**）→ Fix Receiving（对照 Spec/reviewed Plan/真实代码/验证证据）→ 最小修正+验证 或 返回依据/替代修复 → 原 Code Reviewer 复审 → 全闭合 → Code Review `GO`。Fix 可提更合适修复；闭合相同问题且不越需求边界即可，不强制采用 Reviewer 具体实现建议。不新增前置 Code Review；小P readiness 检查不扩展为实质 Code Review。 + +### DD4 — 小P编排边界（Spec §7） + +`roles/coordinator.md` 显式：保留 finding 原意+证据路由；明确返回目标是 gate Reviewer（默认原 Reviewer）；消费正式响应后更新 Plan 已有状态+路由给 gate Reviewer；需求/范围/取舍交秦鹏；GO 后放行。**不预判 finding 成立；不替 artifact owner Receiving；不替 Reviewer 判闭环；不持续监控/实质预审**。readiness 检查仅限 diff/验证/材料存在，不替 Code Reviewer 找实现缺陷。 + +### DD5 — 原 Reviewer 不可用改派（Spec §4.3） + +默认原 Reviewer 复审。原 Reviewer 确实不可用、无法继续承担该 gate 时，小P选另一位**独立于 artifact owner** 的 Reviewer，完整移交 finding + artifact owner 完整响应 + 当前产物 + 必要证据。不得为绕分歧或加速关单随意换人。 + +### DD6 — 能力适配与 Skill（Spec §8） + +Harness 只固化"先判断、后行动、原 Reviewer 复审"行为契约，不硬依赖具体 Skill/模型。Agent 稳定具备 Receiving 心智→Task Brief 只给 finding+上下文；不稳定→小P随 Role Mind 附简短 Receiving 方法。Code Review 修复可用 Superpowers `receiving-code-review` 或等价；Plan Review 用通用判断逻辑（基于 confirmed Spec/Plan 可执行性/当前证据），不机械套用面向代码的指令。Skill 不可用≠blocker；Role Mind 最小契约须足以闭环。不硬编码模型名。 + +### DD7 — contract 边界（尊重北极星§7/§9，不新增语义 marker 检查） + +不新增 disposition 表 / 字符串一致性脚本 / 语义 marker validator。`validate_repository.py` 继续保结构（required files/headings/links/task-brief/at-bot 契约）——**仅验证仓库结构，不证明 Receiving 行为**。行为由独立 Review + Pilot（DD8）证明。北极星§7/§9：正向心智能解决时不加负向规则，结构检查不能证明行为；本问题尚无证据需要机械 guardrail。若未来 Pilot 反复证明心智不稳定，再按§7 增加最小 guardrail。 + +### DD8 — Pilot：以本次真实 Harness 运行为主（Spec §10.2） + +不把六类语义写成 6 次固定 at-bot 流程，也不预设"至少 1-2 行为真实接力"。**以本次交付本身作为主要真实 Pilot**：当前 Plan finding 的 Receiving/复审（小P Review → Plan Writer 修订），以及后续若自然发生的 Code finding/Fix 复审。Spec §10.2 中未自然出现的分支，用最小代表性 walkthrough 补证。 + +验收仍覆盖六类语义，但交互次数与组合方式留给 Agent 判断，不要求固定格式或填表： + +1. Plan finding 成立→Plan Writer 修订+原 Plan Reviewer 复审关闭。 +2. Plan finding 不充分→Plan Writer 返回依据+原 Plan Reviewer 接受反馈或澄清后闭环。 +3. Code finding 成立→Fix 修复验证+原 Code Reviewer 复审关闭。 +4. Code finding 不成立或建议方式不合适→Fix 返回证据/替代修复+原 Code Reviewer 作实质判断。 +5. finding 实际改变 confirmed Spec→不进普通 Fix，小P路由秦鹏。 +6. Skill 不可用→仅 Role Mind + Task Brief 完成闭环。 + +## Execution Units（轻量） + +### Unit 1 — Role 心智 + 协议文案修正 Owner: 小C ☑ + +Files：`HARNESS_DESIGN_PRINCIPLES.md`、`HARNESS.md`、`roles/{coordinator,plan-writer,plan-reviewer,fix,code-reviewer}.md`、`docs/2026-07-20-harness-core-workflow-spec.md`。 + +Changes：按 DD1-DD6 补 Receiving 责任（plan-writer/fix）+ 复审反馈（plan-reviewer/code-reviewer）+ 小P边界（coordinator）+ 改派规则 + Skill 适配；删 pre-classify 文案（有效/已确认 finding、确认应修复、处理→Receiving）。不新增 heading/字段/状态机；同步 core-workflow-spec 避免两套表述（Spec §12）。 + +完成条件：Spec §10.1 全部文档一致性条款满足；无"未判断 finding 称为有效/已确认/必改"残留；北极星/Harness/Role Mind/core-workflow 对 finding 语义一致。 + +Gate：Unit 1-2 自检（`npm run ci` 绿）后统一交小P路由云上C总 Code Review；小P仅做材料/readiness 与状态路由，不前置实质 Review。 + +### Unit 2 — README/CHANGELOG 入口一致性 Owner: 小C ☑ + +Files：`README.md`、`CHANGELOG.md`。 + +Changes：README/CHANGELOG 同步 Receiving/Fix Loop 语义，CHANGELOG 直接对齐现有 event-driven orchestration 条目风格。不新增/修改 `scripts/validate_repository.py` 或 `tests/`（DD7：不新增语义 marker contract，现有 contract 仅保结构）。 + +完成条件：`npm run ci` 绿（Markdown lint + 现有 contract）；README/CHANGELOG 与 HARNESS/Role Mind 入口一致。 + +Gate：`npm run ci` pass。 + +### Code Review Gate Owner: 云上C总 ☑ + +小C 完成 Unit 1-2 + 自检（`validate_repository.py` + CI 绿）后交回小P；云上C总 对照 Spec（`8c984f1`）+ 本 Plan 独立 Code Review 文档/契约改动，GO 后进 Unit 3。不前置 Code Review、不自审 Plan。 + +### Unit 3 — 代表性 Pilot Owner: 小P+秦鹏（小C 提供可 Pilot 的角色/上下文） ☑ + +Changes：按 DD8 跑 6 行为 Pilot（真实或代表性 at-bot 接力）。 + +完成条件：6 行为均演示角色判断+闭环（Spec §10.2）；记录 Pilot 结果（非填表）；若出现形式化争辩/流程负担，收紧文案+Task Brief（Spec §11），不恢复旧语义。 + +Pilot 结果（2026-07-23）：本次真实 Plan Review 覆盖成立 finding 的修订与原 Reviewer 复审；最小 walkthrough 覆盖不充分 Plan finding 的有据反馈，以及 Code finding 成立、替代修复、不成立、需求变化和 Skill 不可用分支。原 Reviewer 对响应作了实质复审，并纠正了不必要的升级建议，没有机械维持 finding 或机械接受 Fix。小P确认 Spec §10.2 六类语义均已演示，秦鹏已验收。 + +Gate：小P 确认行为闭环 + 秦鹏验收口径。 + +## Verification + +```bash +npm ci +npm run ci # markdownlint-cli2 + python3 unittest contracts + validate_repository.py +git diff --check +``` + +Pilot：DD8（本次真实 Harness 运行 + 必要最小 walkthrough）。 + +## Rollback + +- 仅 Harness 文档/角色心智/contract tests，不改外部接口或运行数据；回滚相关提交恢复。 +- 若 Pilot 出现形式化争辩或流程负担（Spec §11），收紧文案与 Task Brief，不恢复"finding 等于修改命令"旧语义。 + +## Open Points 裁定（小P Review） + +1. 不新增语义 marker contract（DD7）——行为由独立 Review + Pilot 证明，现有 contract 仅保结构。 +2. Pilot 以本次真实 Harness 运行为主 + 必要最小 walkthrough，不规定 at 次数/组合（DD8）。 +3. CHANGELOG 直接对齐现有 event-driven orchestration 条目风格，不作为待决点。 + +## Review Gate + +小P已对照 Spec `8c984f1` + 北极星 `c99119c` 完成独立 Plan Review，并在首轮 `CHANGES REQUIRED` 的四项 finding 闭合后给出 `GO`。小C可进入 Unit 1。Unit 1-2 完成后由云上C总独立 Code Review，GO 后进 Unit 3 Pilot。 diff --git a/docs/2026-07-23-review-finding-reception-spec.md b/docs/2026-07-23-review-finding-reception-spec.md new file mode 100644 index 0000000..1301123 --- /dev/null +++ b/docs/2026-07-23-review-finding-reception-spec.md @@ -0,0 +1,232 @@ +# sayToLittleP Review Finding Receiving / Fix Loop Spec + +状态：Confirmed + +日期：2026-07-23 + +确认人：秦鹏 + +## 1. 背景与问题 + +上一轮 Harness Pilot 暴露了一个共同问题：Plan Writer 或实现方收到 Reviewer 的 finding 后，容易把它直接当作修改命令，不先判断 finding 是否成立、证据是否充分、建议是否符合 confirmed Spec 和当前实现。 + +这个问题同时存在于两条返工路径： + +- Plan Review 后，Plan Writer 可能不加判断地改写 Plan； +- Code Review 后，Implementer / Fix 可能不加判断地修改代码。 + +现有 Harness 已要求 Reviewer 提供依据，也要求修改后重新 Review，但协议中的若干表达提前把 finding 定性为“有效 finding”“已确认 finding”或“应进入 Fix”。这会削弱 artifact owner 的独立判断，使 Review 退化成“Reviewer 下指令、接收方照做”，并可能把不充分的建议、个人偏好或隐含需求变化直接写入 Plan 或代码。 + +Review finding 应被视为需要认真接收和验证的专业异议，而不是天然正确的修改指令。 + +## 2. 目标 + +本次修改建立一个同时适用于 Plan 和代码的轻量 Receiving / Fix Loop： + +1. artifact owner 收到 finding 后，先理解、核对并判断； +2. finding 成立且修正仍在 confirmed Spec 内时，完成最小修正和必要验证； +3. finding 不成立、依据不足、含义不清或实际改变需求时，不盲改，而是返回理由、证据或需要澄清的问题； +4. 原 Reviewer 复审修改结果或有依据的反馈，并决定关闭、澄清、修订 finding 或升级决策； +5. 所有开放 finding 闭合后，Reviewer 才能给出当前 gate 的 `GO`。 + +目标是增强角色的判断心智，不是增加审批层级或机械流程。 + +## 3. 非目标 + +- 不引入通用状态机、finding 数据库、强制 disposition 表或新的复杂模板； +- 不要求每个 finding 都生成长篇分析，判断和回复应与风险相称； +- 不降低 Reviewer 提出明确、高质量 finding 的责任； +- 不允许 artifact owner 单方面宣布 finding 已关闭； +- 不新增一个身份不明的 Reviewer Bot，也不改变既有 Bot 分工； +- 不让小P在正式 Code Review 前替 Reviewer 做一轮实质性预审； +- 不改变 confirmed Spec 的需求权威，也不允许在普通 Fix 中静默扩大需求。 + +## 4. 核心心智 + +### 4.1 Finding 是待判断的专业异议 + +Reviewer 对 finding 的质量负责，artifact owner 对接收后的专业判断负责。任何一方都不能用角色身份替代证据。 + +artifact owner 收到 finding 后，应完成与风险相称的 Receiving： + +1. **理解**：确认 finding 指向的行为、约束和后果； +2. **核对**：对照 confirmed Spec、当前 Plan、代码和可获得证据； +3. **判断**：判断 finding 是否成立、是否在 scope 内，以及建议是否是合适的最小修正； +4. **响应**：修正并验证，或返回简短、有依据的异议、疑问或决策点。 + +接收方不因 Reviewer 的语气、身份或结论直接执行修改，也不因不认同建议而草率拒绝。重点是技术与需求事实，而不是服从或争辩。 + +### 4.2 Artifact owner + +本 Spec 中的 artifact owner 是当前被 Review 产物的负责人： + +- Plan Review 的 artifact owner 是 Plan Writer； +- Code Review 的 artifact owner 是 Implementer 重新进入的 Fix 角色。 + +两者使用同一个 Receiving 原则，但判断依据不同： + +- Plan Writer 主要对照 confirmed Spec、仓库现状、角色边界和可执行性； +- Fix 主要对照 confirmed Spec、reviewed Plan、真实代码行为和验证证据。 + +### 4.3 Reviewer 对闭环负责 + +原 Reviewer 必须复审 artifact owner 的响应： + +- 有修改时，判断修改是否真正闭合 finding，是否产生新问题； +- 无修改但有理由和证据时，判断反馈是否足以撤销或修订 finding； +- 信息仍不足时，澄清或补强 finding，而不是机械重复原结论； +- 争议实际涉及需求、范围或取舍时，经小P交给秦鹏决定。 + +“接收方没有按建议修改”本身不是维持 finding 的理由；“接收方认为 finding 不成立”也不等于 finding 自动关闭。 + +默认由提出 finding 的原 Reviewer 完成复审。只有原 Reviewer 确实不可用、无法继续承担该 gate 时，小P才可以选择另一位独立于 artifact owner 的 Reviewer 接续，并提供原 finding、artifact owner 的完整响应、当前产物和必要证据。不得为了绕过分歧或加速关单随意更换 Reviewer。 + +## 5. 统一 Fix Loop + +```text +Reviewer finding +→ 小P路由 finding 与必要上下文 +→ artifact owner Receiving + ├─ 成立且在 scope 内：修正 + 验证 + 返回结果 + ├─ 不成立或依据不足：返回判断 + 证据 + ├─ 含义不清：返回具体澄清问题 + └─ 改变需求或取舍：标记决策点，返回小P +→ 原 Reviewer 复审 + ├─ 接受修正或反馈：关闭 finding + ├─ 证据不足：澄清或修订 finding，进入下一轮 + └─ 需求决策：小P路由秦鹏 +→ 所有 finding 闭合后，Reviewer 给出当前 gate GO +``` + +这是一个 fix loop，而不是“finding 自动变成 fix 命令”的单向链路。 + +## 6. 两条适用路径 + +### 6.1 Plan Review Loop + +1. Plan Reviewer 输出有证据、后果和最小修正方向的 finding； +2. 小P把 finding 路由回 Plan Writer，不预先宣告 finding 已成立； +3. Plan Writer 对照 confirmed Spec 和现实约束判断； +4. Plan Writer 修订 Plan，或返回有依据的反馈 / 澄清问题； +5. 原 Plan Reviewer 复审响应； +6. finding 全部闭合后才给出 Plan Review `GO`。 + +Plan Writer 不得借 Receiving 改写 confirmed Spec；Reviewer 也不得把实现阶段尚未产生的证据强行要求写进 Plan。 + +### 6.2 Code Review Loop + +1. Code Reviewer 输出有代码或行为依据、说明后果的 finding； +2. 小P判断它应路由给 Fix、需求决策或 blocked，但不替 Fix 判断技术结论； +3. Fix 对照 Spec、Plan、代码和验证证据完成 Receiving； +4. Fix 实施最小修正并验证，或返回有依据的反馈 / 澄清问题； +5. 原 Code Reviewer 复审响应； +6. finding 全部闭合后才给出 Code Review `GO`。 + +Fix 可以提出更合适的修复方式；只要它闭合相同问题且不越过需求边界，不要求机械采用 Reviewer 给出的具体实现建议。 + +## 7. 小P的编排边界 + +小P负责： + +- 保留 finding 的原意和必要证据，将其路由给正确 artifact owner； +- 明确当前返回目标仍是负责该 gate 的 Reviewer，默认是原 Reviewer； +- 原 Reviewer 确实不可用时，选择另一位独立 Reviewer，并完整移交 finding 与响应上下文； +- 收到正式响应后更新 Plan 中已有状态，并将响应路由给负责当前 gate 的 Reviewer； +- 将真实需求变化、范围变化或无法由技术证据解决的取舍交给秦鹏； +- 在 Reviewer 给出 `GO` 后放行下一阶段。 + +小P不负责： + +- 把 Reviewer finding 预先定性为必须执行的修改； +- 代替 artifact owner 完成 Receiving 判断； +- 代替原 Reviewer判断 finding 是否闭合； +- 在正式 Review 前持续监控或开展一轮实质性预审。 + +小P可以做交付完整性和 gate readiness 检查，例如确认 diff、验证结果和必要材料是否存在；这不应扩展为替 Code Reviewer 寻找并裁定实现缺陷。 + +## 8. 能力适配与 Skill 使用 + +Harness 只固化“先判断、后行动、原 Reviewer 复审”的行为契约，不把某个具体 Skill 设为流程运行的强依赖。 + +- 目标 Agent 已稳定具备 Receiving 心智时，Task Brief 只需给出 finding 和必要上下文； +- 目标 Agent 不稳定具备该心智时，小P应随 Role Mind 附上简短 Receiving 方法； +- Code Review 修复场景可以使用 Superpowers `receiving-code-review` 或其等价方法； +- Plan Review 返工使用同一通用判断逻辑，但必须以 confirmed Spec、Plan 可执行性和当前证据为准，不能机械套用只面向代码的指令； +- Skill 不可用时不构成 blocker，Role Mind 中的最小行为契约必须足以指导闭环。 + +能力适配按目标 Agent 是否稳定具备所需心智判断，不在 Harness 中硬编码具体模型名称。 + +## 9. 文案修正原则与修改范围 + +实现时先正向补齐角色心智，再删除会诱发盲目执行的旧表达。重点原则： + +- 小P“路由 finding”，而不是“确认 finding 有效后下达 Fix”； +- artifact owner“判断并响应 finding”，而不是“处理已确认 finding”； +- Reviewer“复审修改或反馈”，而不是只检查是否按建议修改； +- `GO` 的条件是开放 finding 已闭合，不是所有建议都被照做。 + +预计同步修改： + +- `HARNESS_DESIGN_PRINCIPLES.md`； +- `HARNESS.md`； +- `roles/coordinator.md`； +- `roles/plan-writer.md`； +- `roles/plan-reviewer.md`； +- `roles/fix.md`； +- `roles/code-reviewer.md`； +- `docs/2026-07-20-harness-core-workflow-spec.md` 的相关角色与返工语义； +- 按入口一致性需要同步 `README.md`、`CHANGELOG.md` 和最小 contract tests。 + +本 Spec 已经确认；后续按 reviewed Plan 修改运行协议，不在 Spec 阶段提前实现其余范围。 + +## 10. 验收条件 + +### 10.1 文档与协议 + +- 北极星、Harness、Role Mind 和 core workflow Spec 对 finding 的语义一致； +- 不再把尚未经过 artifact owner 判断的 finding 称为“有效 finding”“已确认 finding”或等价的必改命令； +- Plan Writer 和 Fix 都明确具备 Receiving 责任； +- Plan Reviewer 和 Code Reviewer 都明确复审“修正或有依据的反馈”； +- 小P被定义为 finding 路由与 gate owner，不是 finding 技术裁决者； +- 原 Reviewer 不可用时只能改派另一位独立 Reviewer，并完整继承 finding 与响应上下文； +- 协议没有新增强制 disposition 表、重型状态字段或新的常驻 Reviewer； +- 没有把小P的 readiness 检查扩展成正式 Review 前的实质性 Code Review。 + +### 10.2 代表性行为 + +至少用 contract test 或代表性 Pilot 覆盖以下行为： + +1. Plan finding 成立：Plan Writer 修订并由原 Plan Reviewer 复审关闭； +2. Plan finding 不充分：Plan Writer 返回依据，原 Plan Reviewer 接受反馈或澄清后闭环； +3. Code finding 成立：Fix 修复和验证，原 Code Reviewer 复审关闭； +4. Code finding 不成立或建议方式不合适：Fix 返回证据或替代修复，原 Code Reviewer作出实质判断； +5. finding 实际改变 confirmed Spec：不进入普通 Fix，由小P路由秦鹏； +6. Skill 不可用时，仅依靠 Role Mind 和 Task Brief 仍能完成上述闭环。 + +验收关注角色是否真的判断与闭环，不要求输出固定格式或逐项填表。 + +## 11. 风险与回滚 + +主要风险有两个： + +1. 把“独立判断”误解为默认反驳 Reviewer，增加无价值往返； +2. 把“轻量”误解为无需说明理由，使 Reviewer 无法判断 finding 是否闭合。 + +实现应强调与风险相称的判断和简短证据：明显成立的问题直接修；真正存疑的问题才反馈。若 Pilot 出现形式化争辩或流程负担，可收紧文案和 Task Brief，不恢复“finding 等于修改命令”的旧语义。 + +本次只涉及 Harness 文档、角色心智和对应 contract tests，不改变外部接口或运行数据，可通过回滚相关提交恢复。 + +## 12. 确认边界 + +本 Spec 已经秦鹏确认，成为 `docs/2026-07-20-harness-core-workflow-spec.md` 在 Review Receiving 和 Fix Loop 语义上的增量修订；冲突时以本 Spec 为准，实现阶段必须同步修正 core workflow Spec，避免两套有效表述并存。 + +实现 Plan 可以细化文件改动、测试和 Pilot 方法，但不能改变以下已确定结论： + +- finding 是需要判断的专业异议，不是天然正确的修改命令； +- Plan Writer 与 Fix 都必须在修改前完成与风险相称的 Receiving； +- 成立的 finding 修正并验证，不充分的 finding 返回依据或问题； +- 原 Reviewer 复审修改或反馈，并对 finding 的闭环负责； +- 原 Reviewer 确实不可用时可以由另一位独立 Reviewer 接续，但必须完整继承上下文，不能用换人绕过分歧； +- 小P负责路由和 gate，不替双方完成专业判断； +- 能力适配可以使用 Skill，但 Harness 不依赖具体 Skill 或模型名称； +- 本次保持轻量，不引入新的重型流程。 diff --git a/roles/code-reviewer.md b/roles/code-reviewer.md index 7c25fb1..96ccd3f 100644 --- a/roles/code-reviewer.md +++ b/roles/code-reviewer.md @@ -15,6 +15,7 @@ - 我不能是本轮实现方。 - 不重新定义需求，也不把偏好包装成需求缺陷。 -- Findings 应有代码或行为依据，并给出最小必要修正。 -- Fix 后必须重新 Review；只有问题闭合才给出 `GO`。 +- Findings 应有代码或行为依据，并给出最小必要修正方向。 +- Fix 响应后，我复审修正或有依据的反馈——不只看是否按建议修改；反馈理由和证据成立时可以关闭 finding；信息仍不足时澄清或修订 finding（不机械重复原结论）；争议涉及需求或范围时经小P交秦鹏。Fix 可以提出更合适的修复方式；只要闭合相同问题且不越需求边界，不要求机械采用我的具体实现建议。 +- 所有开放 finding 闭合后才给出 Code Review `GO`。 - Code Review `GO` 只放行下一 gate，不等于整体交付完成。 diff --git a/roles/coordinator.md b/roles/coordinator.md index 809add0..2af030b 100644 --- a/roles/coordinator.md +++ b/roles/coordinator.md @@ -27,3 +27,16 @@ Spec 确认后，我以 orchestrator 身份工作：依据 Spec、Plan 和当前 - Finding、blocked 和人工验证失败必须回到正确角色。 - 局部 `GO` 不等于 submitted、deployed、verified 或 closed。 - 我可以维护 Plan 中已有的 Checkbox 和运行状态，但不能借进度回写新增、拆分或重排 Execution Unit，也不能修改完成条件；这类内容变更必须退回 Plan Writer，并按需要重新 Review。 + +### Finding 路由与 Reviewer 交接 + +Reviewer 提出 finding 后，我负责路由它与必要上下文到正确的 artifact owner。在此过程中： + +- 我不预判 finding 成立或有效；不替 artifact owner 完成 Receiving 判断；不替 Reviewer 判断 finding 是否闭合。 +- readiness 检查仅限确认 diff、验证结果和必要材料存在，不扩展为 Code Reviewer 的实质审查。 +- 当前 gate 的返回目标默认是原 Reviewer；artifact owner 的正式响应由我路由回负责该 gate 的 Reviewer。 + +**原 Reviewer 不可用时**：原 Reviewer 确实无法继续承担该 gate 时，我选择另一位**独立于 artifact owner** 的 Reviewer 接续，并完整移交原 finding、artifact owner 的完整响应、当前产物和必要证据。不得为了绕过分歧或加速关单随意更换 Reviewer。 + +- 需求变化、范围变化或无法由技术证据解决的取舍，交秦鹏决定。 +- Reviewer 给出 `GO` 后，我放行下一阶段。 diff --git a/roles/fix.md b/roles/fix.md index 3ba29df..8cc9ddd 100644 --- a/roles/fix.md +++ b/roles/fix.md @@ -2,18 +2,29 @@ ## 角色接口 -- **何时选择**：小P确认 Code Review finding 应在原 scope 内修复时。 -- **接收**：已路由 finding、相关 Spec/Plan facts、当前代码结果和验证上下文。 -- **交付**：定向修复、必要自检以及对 finding 的响应。 +- **何时选择**：小P把 Code Review finding 路由给 Fix 时。 +- **接收**：已路由的 finding、相关 Spec/Plan facts、当前代码结果和验证上下文。 +- **交付**：最小修正和必要自检，或对 finding 有依据的反馈（不成立、依据不足、含义不清或涉及需求决策）。 - **交给谁**：小P，再由小P交回原 Code Reviewer。 ## 工作心智 -Fix 不是新的长期 Bot 身份，而是实现方处理有效 finding 时重新进入的工作角色。我的目标是闭合具体问题，不借机重做整个方案。 +Fix 不是新的长期 Bot 身份，而是实现方对已路由 finding 完成 Receiving 时重新进入的工作角色。我的目标是闭合具体问题，不借机重做整个方案。 + +收到 finding 后，我按与风险相称的深度完成 Receiving： + +1. **理解**：确认 finding 指向的行为、约束和后果； +2. **核对**：对照 confirmed Spec、reviewed Plan、真实代码行为和验证证据； +3. **判断**：finding 成立且在 scope 内 → 最小修正 + 验证；不成立或依据不足 → 返回依据；含义不清 → 返回澄清问题；实际改变需求或涉及取舍 → 标记决策点交回小P； +4. **响应**：修正并验证，或返回简短、有依据的异议、疑问或决策点。 + +我不因 Reviewer 的语气、身份或结论直接执行修改，也不因不认同建议而草率拒绝。重点是技术与需求事实，而不是服从或争辩。 ## 判断与边界 -- 只在原 scope 内修复已确认 finding。 -- Finding 若实际改变需求，交回小P和秦鹏，不自行扩大范围。 +- 对已路由 finding 完成 Receiving 后，成立且在 scope 内时完成最小修正并验证。 +- Finding 不成立或依据不足时，返回判断和证据，不为了省事而照改。 +- Finding 含义不清时，返回具体澄清问题，让 Reviewer 修订或补强。 +- Finding 实际改变需求或超出 scope 时，标记决策点交回小P和秦鹏，不自行扩大范围。 - 修复完成不等于 Review 通过；必须重新交给独立 Code Reviewer。 - 新发现但不属于当前 finding 的问题，单独说明并由小P路由。 diff --git a/roles/plan-reviewer.md b/roles/plan-reviewer.md index 74b4e3f..3fe7230 100644 --- a/roles/plan-reviewer.md +++ b/roles/plan-reviewer.md @@ -17,4 +17,6 @@ - 只提出会影响正确性、责任边界或可执行性的 finding。 - 不要求为了完整感增加字段、表格、证据清单或复杂状态机。 - 不把实现阶段尚未产生的 runtime evidence 误判为 Plan 文档缺陷。 -- Finding 要说明证据、后果和最小修正；问题闭合后给出明确 `GO`。 +- Finding 要说明证据、后果和最小修正方向。 +- Plan Writer 响应后，我复审修正或有依据的反馈——不只看是否按建议修改；反馈理由和证据成立时可以关闭 finding；信息仍不足时澄清或修订 finding（不机械重复原结论）；争议涉及需求或范围时经小P交秦鹏。 +- 所有开放 finding 闭合后才给出 Plan Review `GO`。 diff --git a/roles/plan-writer.md b/roles/plan-writer.md index c6dca80..98d7e76 100644 --- a/roles/plan-writer.md +++ b/roles/plan-writer.md @@ -15,6 +15,8 @@ Plan 要让实现者知道先做什么、依赖什么、修改落在哪里、怎 Plan 还要让小P能够依据已确认的状态变化回写真实进度。中、重任务的 Execution Unit 和必要 gate 应具有明确完成条件，并能用 Checkbox 或等价的简洁状态追踪；轻量任务不为此增加多余结构。 +Plan Review 收到 finding 后，我按与风险相称的深度完成 Receiving：理解 finding 指向的约束和后果 → 对照 confirmed Spec、仓库现状、角色边界和可执行性核对 → 判断成立且在 scope 内时修订 Plan，不成立或依据不足时返回依据，含义不清时返回澄清问题，涉及需求变化时标记决策点交回小P。我不因 Reviewer 身份直接照改，也不草率拒绝。 + ## 判断与边界 - 不改变或静默删减 Spec。 @@ -23,3 +25,4 @@ Plan 还要让小P能够依据已确认的状态变化回写真实进度。中 - Spec 或现状不足以形成清楚 Plan 时，明确指出缺口并返回小P。 - 不增加与当前问题无关的字段、状态机或校验机制。 - Plan Review `GO` 后，运行中的 Checkbox 和状态由小P依据角色返回结果维护；需要改变 Unit 或完成条件时，由我修订并重新交给 Plan Reviewer。 +- Plan Review finding 的 Receiving 不借机改写 confirmed Spec；Reviewer 也不应要求实现阶段尚未产生的证据写进 Plan。