fix: distinguish reused contracts in task preflight #19

WuYongJie · 2026-08-06T19:13:23+08:00

WuYongJie commented

2026-08-06 19:13:23 +08:00

任务占用与边界

任务名称：修复协作预检的共享契约误阻断
实际开发者：WuYongJie
任务来源/团队分工：解除 PR #17 对仅复用通用路由的导航任务造成的误阻断
目标结果：只有实际修改同一文件或同一公共契约的任务被阻断；只调用既有共享能力的任务可继续
预计修改路径：scripts/codex-task-preflight.ps1、AGENTS.md、docs/team-collaboration.md、.gitea/PULL_REQUEST_TEMPLATE.md
将写入的公共契约：任务预检参数与阻断判定规则、WIP PR 的公共契约边界模板
仅复用、明确不修改的公共契约：business.pages.show、Pages::show()；本 PR 不修改业务页面、路由或数据库查询
数据源、表/视图和字段：不涉及
上游 source_key / scope：不涉及
权限名、菜单键或共享组件：不涉及
明确不修改的范围：app/Http/Controllers/Business/Pages.php、所有业务 Repository、生产配置、数据库和部署脚本

碰撞检查

Codex 已执行 scripts/codex-task-preflight.ps1
已检查最新 main 和所有远程任务分支
已搜索主线既有页面、接口、Repository 和数据查询
已把“将写入”和“仅复用、不修改”的公共契约分开；仅复用项不作为单独阻断条件
未发现实际写入重叠

相关分支、重叠项与协调结论：PR #17 只写入 Pages.php 的 jd-wallet 专用处理，不修改 business.pages.show、Pages::show() 或导航配置。PR #17 的描述已补充此边界；只改订单数据导航配置和独立测试的任务可把 business.pages.show 标为仅复用后并行继续。

实际改动

完成内容：新增 -ReuseContract 可选参数；-Contract（别名 -WriteContract）仅代表将写入的公共契约；远程分支命中仅复用契约时只提示，不单独阻断；禁止用 app、tests 等宽泛根目录作为预计路径。
Codex 实际修改的文件：.gitea/PULL_REQUEST_TEMPLATE.md、AGENTS.md、docs/team-collaboration.md、scripts/codex-task-preflight.ps1
新增或变更的公共契约：-ReuseContract、-WriteContract 参数别名、WIP PR 的“将写入/仅复用”字段
与原计划的差异：无

验证证据

正常流程：在隔离的 feature/renshen-order-data-submenus 工作树，以其真实修改路径和 business.pages.show 仅复用声明运行新版预检，结果通过；同时识别出 PR #17 为仅复用提示。
错误输入/保护场景：计划修改 app/Http/Controllers/Business/Pages.php 时，预检被 feature/chenxi-jd-wallet-upstream 正确阻断。
宽泛范围保护：使用 -PlannedPath @('tests') 时，脚本明确拒绝并要求精确文件或最小子目录。
自动测试及结果：PowerShell AST 语法检查通过；git diff --check 通过。此任务仅改协作脚本和文档，不涉及 Laravel 运行逻辑。
实际页面、接口或只读业务查询结果：不适用。

风险检查

不涉及金额、权限、审批、数据库迁移、生产配置或数据修复
未提交 .env、密码、Token、私钥、真实财务数据、生产日志或构建产物
前端改动符合 DESIGN.md；无前端改动，不适用

高风险影响、回滚和授权状态：无生产动作；如需回滚，只需回退本 PR 的单个 Squash 提交。

合并前复查

已重新拉取远程引用并用实际修改范围再次运行碰撞检查
PR 不再是 WIP:，所有测试结果已经补齐
Codex 已重新读取原始需求和验收标准，并逐文件审核 origin/main...任务分支 的完整 diff
Codex 自审确认无越界修改、重复实现、敏感内容、未处理冲突和未验证结果
合并顺序不会覆盖其他未合并任务
已授权当前任务的 Codex 执行 Squash merge、验证 main 并清理任务分支
不涉及生产迁移、数据修复、删除、覆盖配置或部署

## 任务占用与边界 - 任务名称：修复协作预检的共享契约误阻断 - 实际开发者：WuYongJie - 任务来源/团队分工：解除 PR #17 对仅复用通用路由的导航任务造成的误阻断 - 目标结果：只有实际修改同一文件或同一公共契约的任务被阻断；只调用既有共享能力的任务可继续 - 预计修改路径：`scripts/codex-task-preflight.ps1`、`AGENTS.md`、`docs/team-collaboration.md`、`.gitea/PULL_REQUEST_TEMPLATE.md` - 将写入的公共契约：任务预检参数与阻断判定规则、WIP PR 的公共契约边界模板 - 仅复用、明确不修改的公共契约：`business.pages.show`、`Pages::show()`；本 PR 不修改业务页面、路由或数据库查询 - 数据源、表/视图和字段：不涉及 - 上游 `source_key` / `scope`：不涉及 - 权限名、菜单键或共享组件：不涉及 - 明确不修改的范围：`app/Http/Controllers/Business/Pages.php`、所有业务 Repository、生产配置、数据库和部署脚本 ## 碰撞检查 - [x] Codex 已执行 `scripts/codex-task-preflight.ps1` - [x] 已检查最新 `main` 和所有远程任务分支 - [x] 已搜索主线既有页面、接口、Repository 和数据查询 - [x] 已把“将写入”和“仅复用、不修改”的公共契约分开；仅复用项不作为单独阻断条件 - [x] 未发现实际写入重叠相关分支、重叠项与协调结论：PR #17 只写入 `Pages.php` 的 `jd-wallet` 专用处理，不修改 `business.pages.show`、`Pages::show()` 或导航配置。PR #17 的描述已补充此边界；只改订单数据导航配置和独立测试的任务可把 `business.pages.show` 标为仅复用后并行继续。 ## 实际改动 - 完成内容：新增 `-ReuseContract` 可选参数；`-Contract`（别名 `-WriteContract`）仅代表将写入的公共契约；远程分支命中仅复用契约时只提示，不单独阻断；禁止用 `app`、`tests` 等宽泛根目录作为预计路径。 - Codex 实际修改的文件：`.gitea/PULL_REQUEST_TEMPLATE.md`、`AGENTS.md`、`docs/team-collaboration.md`、`scripts/codex-task-preflight.ps1` - 新增或变更的公共契约：`-ReuseContract`、`-WriteContract` 参数别名、WIP PR 的“将写入/仅复用”字段 - 与原计划的差异：无 ## 验证证据 - 正常流程：在隔离的 `feature/renshen-order-data-submenus` 工作树，以其真实修改路径和 `business.pages.show` 仅复用声明运行新版预检，结果通过；同时识别出 PR #17 为仅复用提示。 - 错误输入/保护场景：计划修改 `app/Http/Controllers/Business/Pages.php` 时，预检被 `feature/chenxi-jd-wallet-upstream` 正确阻断。 - 宽泛范围保护：使用 `-PlannedPath @('tests')` 时，脚本明确拒绝并要求精确文件或最小子目录。 - 自动测试及结果：PowerShell AST 语法检查通过；`git diff --check` 通过。此任务仅改协作脚本和文档，不涉及 Laravel 运行逻辑。 - 实际页面、接口或只读业务查询结果：不适用。 ## 风险检查 - [x] 不涉及金额、权限、审批、数据库迁移、生产配置或数据修复 - [x] 未提交 `.env`、密码、Token、私钥、真实财务数据、生产日志或构建产物 - [x] 前端改动符合 `DESIGN.md`；无前端改动，不适用高风险影响、回滚和授权状态：无生产动作；如需回滚，只需回退本 PR 的单个 Squash 提交。 ## 合并前复查 - [x] 已重新拉取远程引用并用实际修改范围再次运行碰撞检查 - [x] PR 不再是 `WIP:`，所有测试结果已经补齐 - [x] Codex 已重新读取原始需求和验收标准，并逐文件审核 `origin/main...任务分支` 的完整 diff - [x] Codex 自审确认无越界修改、重复实现、敏感内容、未处理冲突和未验证结果 - [x] 合并顺序不会覆盖其他未合并任务 - [x] 已授权当前任务的 Codex 执行 Squash merge、验证 `main` 并清理任务分支 - [x] 不涉及生产迁移、数据修复、删除、覆盖配置或部署

WuYongJie added 1 commit 2026-08-06 19:16:07 +08:00

fix: distinguish reused contracts in task preflight 7452914886

WuYongJie changed title from ~~WIP: 修复协作预检的共享契约误阻断~~ to fix: distinguish reused contracts in task preflight

2026-08-06 19:20:30 +08:00

WuYongJie merged commit 481b5d2e49 into main

2026-08-06 19:21:01 +08:00

WuYongJie referenced this issue from a commit

2026-08-06 19:21:02 +08:00

fix: distinguish reused contracts in task preflight (#19)

Sign in to join this conversation.