From 5c249b097512b2718b61fad9e6096a45ab0b9d59 Mon Sep 17 00:00:00 2001 From: WeiCHEN Date: Wed, 23 Sep 2026 09:37:48 +0800 Subject: [PATCH 1/2] docs(plan): add modular refactor implementation undertaking framework Define phase gates, work-package template, anti-duplication checks against A-G/exceptions baseline, and product-host backfill rules without coding. --- .../2026-09-23-modular-refactor-impl-plan.md | 65 +++++++ ...efactor-implementation-undertaking-plan.md | 179 ++++++++++++++++++ .doc/remediation/INDEX.md | 1 + 3 files changed, 245 insertions(+) create mode 100644 .doc/ops/short-term/2026-09-23-modular-refactor-impl-plan.md create mode 100644 .doc/remediation/2026-09-23-modular-refactor-implementation-undertaking-plan.md diff --git a/.doc/ops/short-term/2026-09-23-modular-refactor-impl-plan.md b/.doc/ops/short-term/2026-09-23-modular-refactor-impl-plan.md new file mode 100644 index 00000000..8040b1e4 --- /dev/null +++ b/.doc/ops/short-term/2026-09-23-modular-refactor-impl-plan.md @@ -0,0 +1,65 @@ +--- +title: "编制模块化重构实施承接计划（框架+映射回填）" +task_id: modular-refactor-impl-plan-2026-09-23 +status: in_progress +created: 2026-09-23 +updated: 2026-09-23 +owner: Cursor +task_type: research +task_tier: small +policy_revision: "AGENTS+worktree-ops+validation-contract @ 2ce8688db4f49fdd116799b9d36ef7ea802afc33" +branch: feature/modular-refactor-impl-plan-2026-09-23 +worktree: .worktrees/modular-refactor-impl-plan-2026-09-23 +base_dev_sha: "2ce8688db4f49fdd116799b9d36ef7ea802afc33" +write_scope: [".doc"] +allowed_environments: [] +head_sha: "" +mutex: "docs-remediation-modular-impl-plan" +review_state: pending +integration_state: pending +deployment: not_required +cleanup: pending +cleanup_owner: "独立维护者" +cleanup_trigger: "tip 为 local_dev 祖先且无进程占用后 remove" +remote_sync: not_requested +--- + +# 编制模块化重构实施承接计划 + +## 用户目标与授权 + +- 用户目标：按「框架+映射回填」编制符合设计与规范的实施承接计划；合入本机 `dev`；不实施业务代码。 +- 授权来源：用户确认计划「实施承接计划编制」。 +- 交付终点：`.doc/remediation/2026-09-23-modular-refactor-implementation-undertaking-plan.md` 合入本机 `dev`。 +- 禁止项：不 push；不操作 test/main；不代填 17 工作包；不触碰红线能力。 + +## 范围与非目标 + +- 允许写入：`.doc/remediation/**`、`.doc/ops/short-term/**`、`.doc/ops/CURRENT.md`（docs apply）、INDEX。 +- 非目标：方案正文审结、业务编码、跨机同步。 + +## 步骤与验收 + +1. [x] 从 `dev@2ce8688d` 创建 worktree 并登记 agentctl +2. [x] 编写承接计划主文档（阶段门禁、工作包模板、防重复施工、回填指引） +3. [x] 本任务文 + remediation INDEX 入口 +4. [ ] 文档自检与提交；docs apply 认领 CURRENT +5. [ ] validate → integrate 合入本机 `dev` +6. [ ] CURRENT done + 收口分项 + +## 验证与证据 + +| 范围 / 被测 SHA | 命令与环境 | 预期 | 实际 / 判定 | 证据 | +|---|---|---|---|---| +| 纯文档 | 相对链接 + taxonomy | 链接可达；落在 remediation/ops | 待提交后核 | 本文件 + 主计划 | +| 门禁 | 不跑 Go/PI | not_required | not_required | 验证契约纯文档行 | + +## 收口与交接 + +- 产物机器：按主计划 §6 回填 17 包与审核清单后开工。 +- remote_sync：默认未推送。 + +## 相关链接 + +- 主计划：[../../remediation/2026-09-23-modular-refactor-implementation-undertaking-plan.md](../../remediation/2026-09-23-modular-refactor-implementation-undertaking-plan.md) +- 审核清单：[../../audit/2026-09-23-modular-refactor-plan-review-checklist.md](../../audit/2026-09-23-modular-refactor-plan-review-checklist.md) diff --git a/.doc/remediation/2026-09-23-modular-refactor-implementation-undertaking-plan.md b/.doc/remediation/2026-09-23-modular-refactor-implementation-undertaking-plan.md new file mode 100644 index 00000000..3350b655 --- /dev/null +++ b/.doc/remediation/2026-09-23-modular-refactor-implementation-undertaking-plan.md @@ -0,0 +1,179 @@ +--- +title: "系统整改与重构方案 · 实施承接计划（框架+映射回填）" +status: planned +created: 2026-09-23 +updated: 2026-09-23 +owner: Cursor +task_id: modular-refactor-impl-plan-2026-09-23 +base_dev_sha: "2ce8688db4f49fdd116799b9d36ef7ea802afc33" +--- + +# 系统整改与重构方案 · 实施承接计划（框架+映射回填） + +## 1. 目的、输入依赖与非目标 + +### 1.1 目的 + +为产物机器上的《系统整改与重构方案》（22 条规范 → 17 工作包 → 6 阶段）提供**可在本机规范下执行的承接框架**：阶段门禁、工作包登记模板、防重复施工前置检查、回填与开工准入、集成与收口分项。产物机器把工作包明细填入本模板后即可按包开工。 + +### 1.2 输入依赖（本机不可见须回填） + +| 输入 | 路径 / 说明 | 本机状态 | +|---|---|---| +| 重构方案正文 | `.doc/remediation/2026-09-22-agent-system-modular-refactor-plan.md`（worktree `modular-contract-standard-2026-09-22`） | **不可见**；17 工作包明细由产物机器回填 | +| 审核检查清单 | [../audit/2026-09-23-modular-refactor-plan-review-checklist.md](../audit/2026-09-23-modular-refactor-plan-review-checklist.md) | 已合入本机 `dev`；N01–N22 / P1 / P2 / CX 自查由产物机器完成 | +| 模块开发规范 | [../system-design/2026-09-20-module-development-standards.md](../system-design/2026-09-20-module-development-standards.md) | 生效 | +| 验证契约 | [../ops/2026-09-21-validation-contract.md](../ops/2026-09-21-validation-contract.md) | 生效 | +| 操作规范 | [../ops/2026-09-21-agent-worktree-workflow.md](../ops/2026-09-21-agent-worktree-workflow.md) | 生效 | +| A–G 分批 | [./2026-09-20-module-decoupling-batch-plan.md](./2026-09-20-module-decoupling-batch-plan.md) | FEATURE-MATRIX 行 `done`；本文件保持 planned 为历史批次记录 | + +### 1.3 非目标 + +- 本文件**不实施**业务代码、不代填 17 工作包明细、不虚构方案正文内容。 +- 不改 `production_ready`；不整支 merge FAV；不升 `MULTI_INTENT_PLAN_TIER`；不接线 `SEMANTIC_SUMMARY_REPLACE`；不放开 PI 叙事 flag；D7 不授权物理删除；SWBOOT-10 保持 stub 直至独立授权。 +- 不 push、不操作 test/main（除非另获授权）。 + +## 2. 已落地基线盘点（本机实测） + +编制日：**2026-09-23**。基线 tip：`2ce8688db4f49fdd116799b9d36ef7ea802afc33`（本任务 `base_dev_sha`；合入后以当时 `dev` tip 为准重测）。 + +| 检查项 | 命令 / 依据 | 结果 | +|---|---|---| +| 架构门禁 | `./scripts/arch-check.sh --mode block` | **PASS**（production gate passed） | +| 边界例外 | `.doc/system-design/module-boundaries.yaml` `exceptions:` | **`[]`**（曾记 21 条已清零） | +| A–G 批次 | FEATURE-MATRIX「模块解耦批次 A–G」 | **`done`**（A–F + G1/G2/G3；baseline import/sql_write/path/event 全 0） | +| 发布缺口 | [gap-matrix.md](./gap-matrix.md) 现行区段 | 已列行均为 **PASS**（新缺陷须新开 audit/gap 行，不得静默覆盖） | +| 审核清单 | audit 2026-09-23 checklist | 已入库；自查列多为「待回填」 | + +**含义**：方案阶段中与 A–G / 通知事务 / SSE / 鉴权相关的大量「从零整改」在本机已有落地。后续工作包默认按 **增量修复** 或 **回归门禁** 登记，禁止重复施工覆盖既有证据。 + +## 3. 阶段 → 门禁表 + +方案六阶段与本机验证契约对齐。每阶段须满足「准入」方可开工下属工作包；「完成」须证据可核验。 + +| 阶段 | 主题（方案口径） | 准入 | 完成判据 | 验证契约适用行 | +|---|---|---|---|---| +| 1 | 契约、模块职责、验证基线 | 审核清单 §3 P1 无「阻断」；N 映射至少覆盖本阶段涉及规范 | 契约/registry/table_owners 变更有 before/after；`arch-check` + 范围测试绿 | 纯文档 **或** Go/接口（改契约时） | +| 2 | 通知事务、事件领取、授权、业务入口一致性 | 清单 §4 P2 无阻断；§5 前置检查声明与已 PASS gap 关系 | 同事务通知/lease/鉴权/入口一致性有精确用例 PASS | Go/接口；涉 SSE 追加既有 stream 测试 | +| 3 | 任务受理、执行租约、Runner 取消与未知结果、SSE 恢复 | 清单 §5 CX 无阻断；取消状态契约已冻结 | CX 状态机/未知结果/SSE 恢复场景 PASS | Go/接口；产品链路按范围追加 | +| 4 | DB 写权、文件访问、后端接口、工作流依赖收敛 | 阶段 1–3 相关包 done 或显式 deferred；mutex 无冲突 | YAML allowlist 只删边不放新边；无新无到期例外 | Go/接口 + arch-check | +| 5 | 前端状态职责拆分、架构门禁完善 | 后端契约稳定（wire DTO 不变或已同步） | `web/` `npm test` + `npm run build`；受影响浏览器场景 | 前端 | +| 6 | 分批迁移、真实验收、上线 | 阶段 1–5 完成判据满足；红线未触碰 | 获授权环境 `/health` `/ready` + 范围真实业务；制品身份可对账 | 迁移/运行配置 **并** 产品 Agent（按变更并集） | + +阶段之间：**编码与隔离测试可并行**（mutex 不重叠）；**dev 集成与共享环境验收串行**（`git:dev` / `env:dev`）。 + +## 4. 工作包登记模板 + +产物机器将方案每个工作包复制为下表一行（或独立 short-term，回链本计划）。缺任一项 → 不得标 `in_progress` 编码。 + +### 4.1 必填字段 + +| 字段 | 要求 | +|---|---| +| `wp_id` | 方案工作包 ID（例 WP-01）；唯一 | +| `phase` | 1–6 | +| `title` | ≤40 字 | +| `norm_refs` | Nxx + 审核清单行（P1-*/P2-*/CX-*） | +| `relation_to_baseline` | **必须**三选一：`incremental`（增量修复）/ `regression_gate`（仅加固测试与门禁）/ `net_new`（本机确认无对等落地；须写明检索范围） | +| `code_anchors` | 文件路径 + 符号（函数/类型）；禁止只写包名 | +| `deps` | 依赖的 `wp_id` / 已合入 tip / 外部 ADR | +| `mutex` | 模块/路径资源名；与 CURRENT 认领一致 | +| `write_scope` | 允许写路径列表 | +| `test_scenarios` | Given/When/Then + **精确** `-run` 用例名或 npm 测试文件；stub/SKIP 不得作交付 PASS | +| `rollback` | 可操作回退：单批 `revert` 边界；数据/迁移是否兼容；例外条目是否需成对恢复 | +| `evidence` | `.doc/test-reports/…` 或 short-term 验证节路径 | +| `owner` / `branch` / `worktree` / `base_dev_sha` | 开工时填写；必须从当时 `dev` tip 创建 | + +### 4.2 登记表示例（空行供回填） + +| wp_id | phase | title | relation_to_baseline | code_anchors | mutex | test_scenarios | rollback | 判定 | +|---|---|---|---|---|---|---|---|---| +| *WP-??* | *?* | *待回填* | *待声明* | *待回填* | *待回填* | *待回填* | *待回填* | 待回填 | + +### 4.3 推荐代码锚点（本机已知落点，供对照，非代填） + +| 主题 | 本机锚点（符号级） | +|---|---| +| 事件契约 | `internal/events/registry.go` `StaticContracts` | +| 事件领取 | `internal/events/dispatcher.go` `ClaimLeases`；`worker.go` | +| 可见通知同事务 | `internal/notification/document_events.go` `EmitVisibleDocumentEvent`；`service.go` `EmitVisibleStageReady` | +| 授权 | `internal/authz/authorizer.go` `RequireProjectAccess*` | +| 任务取消 | `internal/taskrun/finalize.go` `Commands.Cancel`；`manager.go` `Manager.Cancel` | +| SSE / 续订 | `internal/server/sse.go` `extendSSEWriteDeadline`；`task_run_handlers.go` `after_seq` | +| 边界门禁 | `.doc/system-design/module-boundaries.yaml`；`./scripts/arch-check.sh` | + +## 5. 防重复施工前置检查 + +每个工作包开工前，owner 在 short-term 勾选并留证据链接： + +1. [ ] 检索 [gap-matrix](./gap-matrix.md)：若已有 PASS 行覆盖同一缺陷，默认 `regression_gate`；声称重开须新 audit 证据。 +2. [ ] 检索 FEATURE-MATRIX：相关模块行状态与「剩余条件」；不得把已 `done` 伞行改回 `planned` 以「再做一遍」。 +3. [ ] 确认 `module-boundaries.yaml` `exceptions` 仍为 `[]`（或仅含本包显式新增且带到期日的例外）；禁止无到期例外。 +4. [ ] 对照审核清单：关联 P1/P2/CX 行不是「阻断」。 +5. [ ] 声明 `relation_to_baseline`；`net_new` 须列出已检索路径（至少含 §4.3 相关锚点与 A–G short-term）。 +6. [ ] mutex / write_scope 与 CURRENT / agentctl 登记一致；热点（lockfile、迁移号、顶层路由）单独认领。 +7. [ ] 红线未触碰（§1.3）；若工作包接近红线能力，单独授权记录。 + +任一项未勾 → 状态保持 `planned` 或 `blocked`，不得编码。 + +## 6. 产物机器回填与开工准入 + +### 6.1 回填顺序 + +1. 同步本机已合入的本计划 + [审核清单](../audit/2026-09-23-modular-refactor-plan-review-checklist.md)。 +2. 完成清单 §2 N01–N22 映射与 §3–§5 自查（优先 CX → P1 → P2）。 +3. 将方案 17 工作包填入 §4.2 表（或每包一个 short-term，回链 `wp_id`）。 +4. 每包做完 §5 前置检查。 + +### 6.2 开工准入（硬条件） + +同时满足才可 `agentctl task register` 并编码： + +- 审核清单相关行无「阻断」； +- 该包 §4 必填字段齐全； +- §5 前置检查全部勾选； +- 从**产物机器（或本机）当时 `dev` 完整 SHA** 创建 feature/fix worktree，不从他人 feature 派生。 + +### 6.3 本机 vs 产物机器协调 + +- CURRENT / `.locks` **不是跨机分布式锁**；两机并行须靠人工 mutex 约定或只在一机实施。 +- 文档合入本机 `dev` 后，产物机器需 push/同步才能看见；未授权 push 时用手动拷贝，并在任务文记录同步方式。 + +## 7. 集成、部署与收口 + +### 7.1 集成 + +遵循操作规范：冻结 head → 候选 worktree `merge --no-ff`（第一父 = expected_dev）→ `agentctl validate` → `agentctl integrate --expected-dev `（`git:dev` 租约内 `--ff-only`）。主目录禁止直接开发提交。 + +共享文档（CURRENT / FEATURE-MATRIX）变更走 `docs apply`；任务仅改自己的 CURRENT 行。 + +### 7.2 部署判定 + +| 变更 | deployment | +|---|---| +| 仅 `.doc` 普通文档 / 本承接计划 | `not_required` | +| Go/API/事件/迁移/模板提示词 | 获授权环境 rebuild + `/health` `/ready` + 范围业务；`restart` 不足证明 | +| 前端交互 | `npm test`/`build` + 受影响真实浏览器 | + +### 7.3 收口分项（每个工作包与本框架任务均须报告） + +| 字段 | 含义 | +|---|---| +| `review_state` | 审查结论 | +| `integration_state` | 是否已合入目标 `dev` | +| `deployment` | 见上 | +| `cleanup` | worktree/分支清理；拒绝时 `pending` + owner/触发条件，不 `--force` | +| `remote_sync` | 默认 `not_requested` | + +### 7.4 与本框架任务的关系 + +- 本文件 status=`planned`：追踪「17 包回填后的实施队列」，**不是**业务已开工。 +- 编制本框架的 short-term：[../ops/short-term/2026-09-23-modular-refactor-impl-plan.md](../ops/short-term/2026-09-23-modular-refactor-impl-plan.md)（文档任务，合入后 done）。 + +## 8. 相关链接 + +- 审核清单：[../audit/2026-09-23-modular-refactor-plan-review-checklist.md](../audit/2026-09-23-modular-refactor-plan-review-checklist.md) +- 模块开发规范 · 验证契约 · 操作规范（见 §1.2） +- A–G：[./2026-09-20-module-decoupling-batch-plan.md](./2026-09-20-module-decoupling-batch-plan.md) +- gap-matrix：[./gap-matrix.md](./gap-matrix.md) +- 目标方案（产物机器）：`.doc/remediation/2026-09-22-agent-system-modular-refactor-plan.md` diff --git a/.doc/remediation/INDEX.md b/.doc/remediation/INDEX.md index 54f485e3..b320f1bd 100644 --- a/.doc/remediation/INDEX.md +++ b/.doc/remediation/INDEX.md @@ -2,6 +2,7 @@ | 文档 | 说明 | |------|------| +| [2026-09-23-modular-refactor-implementation-undertaking-plan.md](./2026-09-23-modular-refactor-implementation-undertaking-plan.md) | 系统整改与重构方案的**实施承接计划**（框架+映射回填）：阶段门禁、工作包模板、防重复施工（对照 A–G/`exceptions=[]`）、产物机器回填与开工准入。配套 [审核清单](../audit/2026-09-23-modular-refactor-plan-review-checklist.md) · [任务](../ops/short-term/2026-09-23-modular-refactor-impl-plan.md)。不代填 17 工作包、不实施业务代码 | | [../system-design/2026-09-22-t20-hardening-design.md](../system-design/2026-09-22-t20-hardening-design.md) | T20 W4 加固设计决策（XFF、锁拆分、timeout、shutdown、SSE POST、前端 generation/cookie、compose non-root/init、backup 调度文档）；F5/I8 见 lowrisk 批。配套 [任务](../ops/short-term/2026-09-22-t20-design-items.md) | | [../system-design/2026-09-20-stage-backtrack-and-impact-loop-design.md](../system-design/2026-09-20-stage-backtrack-and-impact-loop-design.md) | 阶段回溯与影响闭环：L1 修订 / L2 再打开、待复核软标记、对话提案桥。追踪留存定为 `record`；候选边由下游编制人裁决。配套 short-term 切片均为 planned | | [2026-09-20-module-decoupling-batch-plan.md](./2026-09-20-module-decoupling-batch-plan.md) | 耦合残留分批 A–G（server 装配、逻辑环、docgov 词汇、工作流依赖、巨型文件、前端 client、例外清零）；保持 planned，不改代码。配套 [审计](../audit/2026-09-20-module-coupling-audit.md) · [规范](../system-design/2026-09-20-module-development-standards.md) | From 19a8f19a8a8f59a10309fbc3596d0711bae34524 Mon Sep 17 00:00:00 2001 From: WeiCHEN Date: Wed, 23 Sep 2026 09:37:49 +0800 Subject: [PATCH 2/2] docs(ops): claim CURRENT for modular-refactor-impl-plan Register the undertaking-plan documentation task in the parallel-claim table. --- .doc/ops/CURRENT.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.doc/ops/CURRENT.md b/.doc/ops/CURRENT.md index f284d9eb..54082efe 100644 --- a/.doc/ops/CURRENT.md +++ b/.doc/ops/CURRENT.md @@ -18,6 +18,7 @@ | owner | task | branch | worktree | mutex | status | |---|---|---|---|---|---| +| Cursor | modular-refactor-impl-plan-2026-09-23 | feature/modular-refactor-impl-plan-2026-09-23 | .worktrees/modular-refactor-impl-plan-2026-09-23 | docs-remediation-modular-impl-plan | in_progress | | Cursor | modular-refactor-review-2026-09-23 | feature/modular-refactor-review-2026-09-23 | .worktrees/modular-refactor-review-2026-09-23 | ops-audit-modular-refactor-review | done | | Cursor | 2026-09-22-status-reconcile | feature/status-reconcile-2026-09-22 | .worktrees/status-reconcile-2026-09-22 | ops-status-reconcile | done | | Cursor | 2026-09-22-dev-prod-ready-test-promotion | feature/dev-prod-ready-test-promotion-2026-09-22 | .worktrees/dev-prod-ready-test-promotion-2026-09-22 | dev-runtime-migration+release-gate+test-promotion | done |