docs(architecture): add system remediation and refactoring plan

.doc/ops/short-term/2026-09-22-modular-contract-standard.md

@@ -3,7 +3,7 @@ title: "当前解耦审查与跨项目模块契约规范"
 task_id: modular-contract-standard-2026-09-22
 status: done
 created: 2026-09-22
-updated: 2026-09-22
+updated: 2026-09-23
 owner: Codex
 task_type: research
 task_tier: multi_stage
@@ -11,11 +11,11 @@ policy_revision: "agent-governance-2026-09-21-r1 @ d034aa00e5785f51234b484f9dca6
 branch: feature/modular-contract-standard-2026-09-22
 worktree: .worktrees/modular-contract-standard-2026-09-22
 base_dev_sha: d034aa00e5785f51234b484f9dca6bf4fb037660
-write_scope: [".doc/ops/short-term/2026-09-22-modular-contract-standard.md", ".doc/audit/2026-09-22-module-decoupling-current-state.md", ".doc/system-design/2026-09-22-generic-module-contract-standard.md", ".doc/remediation/2026-09-22-modular-platform-adoption-plan.md", ".doc/ops/CURRENT.md"]
+write_scope: [".doc/ops/short-term/2026-09-22-modular-contract-standard.md", ".doc/remediation/2026-09-22-agent-system-modular-refactor-plan.md", ".doc/remediation/2026-09-22-modular-platform-adoption-plan.md", ".doc/ops/CURRENT.md"]
 allowed_environments: []
 mutex: "path:本任务四份文档；CURRENT 使用行级 CAS"
 review_state: approved
-integration_state: merged
+integration_state: pending
 deployment: not_required
 cleanup: retained-with-reason
 cleanup_owner: 独立维护者
@@ -77,7 +77,7 @@ remote_sync: not_requested
 
 审阅结果：applied=3，proposed_fixes=0，decisions=0，fyi=0。主审另补规范 §2.2 功能设计卡与前端状态边界，与用户“功能、模块区分”一致，经局部复核未发现矛盾。实施前的仓库/owner/试点/SLO 仍须补齐，属于方案明确的后续立项条件，不伪装为已完成。
 
-### 产物身份
+### 产物身份（前轮合入时）
 
 | 文档 | SHA-256 |
 |---|---|
@@ -117,3 +117,52 @@ remote_sync: not_requested
 - 原证据恢复：确有原路径消费者需要且目标路径不存在时，由后续获授权维护者依据 manifest 复制/移回并校验；不得覆盖后续新生成证据。归档不改变这些旧证据的测试结论。
 - 未 push，未 fetch，未部署/重启。当前读取到的 origin/dev 跟踪引用已与上轮不同，未将其并入本次本地 dev；不声称已与远端同步。
 - 任务/候选 worktree 保留；本次不执行清理。独立维护者待 owner 退出后核对祖先、忽略文件、进程和唯一产物，再决定清理。
+
+## 系统专用整改规划续办
+
+授权：用户“按照规范，制定系统整改和重构方案”。沿用 logical task_id；本轮仅编制本项目实施方案，未授权业务实施、环境写入、push 或新成果 dev 集成。前轮规范文档已合入 dev 的事实保持不变；本记录顶部状态现用于新增方案阶段。
+
+本轮基线：dev@5c35f32e225a482d5838e6d771778fb754f75506。原任务 worktree 无未提交内容，且其树与 dev 一致，已在登记与 index 租约内快进到该确切 dev。未从其他 feature 开始。origin/dev...dev 本地跟踪比较待下方实际检查记录；未 fetch，不代表远端实时值。
+
+执行登记：modular-contract-standard-2026-09-22-system-plan。owner=Codex；branch/worktree 沿用原任务。新增允许写范围 .doc/remediation/2026-09-22-agent-system-modular-refactor-plan.md；本轮同时允许修改本任务文、通用采用计划中的当前项目指针及 CURRENT 自己的行。mutex 为上述精确 path；docs:admin 仅用于同一 logical task_id 续办的 CURRENT 行，不改他人记录。
+
+交付：[系统整改与重构方案](../../remediation/2026-09-22-agent-system-modular-refactor-plan.md)，包含规范逐条映射、目标职责/数据边界、分期执行单元、依赖/写者认领、存量迁移与回退、真实验证矩阵。通用平台 U1–U8 继续服务未来独立平台，本项目不把它们照搬成重复框架。
+
+研究验证：复核源码与已存在测试定义，不运行产品测试或运行探针；产物做结构/链接/事实锚点核对和文档审阅。三个只读子审查深化事件/迁移、后端边界、Agent/前端契约，结果归入父任务，不另写文件。
+
+### 系统整改方案阶段验收与交接
+
+本阶段研究/方案完成，业务整改仍未启动。交付主文档为系统整改与重构方案，SHA-256：eb06775651546f8af4c1218400ce3198949bbf2d3d566b4cdf6b698407298ea9。712行，17个工作包、22条MCS映射、12项需求，另含16条路径与5条SQL例外逐项处理及projects漏登记写者。基于dev@5c35f32e源码；不依赖本轮运行数据。
+
+源码深化新增事实已落在方案E3–E12和相应U单元：shadow的聊天自提交路径、producer字段漂移、taskrun租约及持久受理窗口、Runner未知执行、SSE先推后存、缓存事务逃逸、workspace内存lease与路径误报。均为源码可达条件；未查询现网影响数量，未将风险推断冒充事故复现。
+
+文档审阅采用ce-doc-review非交互流程，当前会话三位子审阅者覆盖coherence、feasibility、security、adversarial、product、scope、design七视角；同一人多视角不算独立多票。未运行外部CLI跨模型复核。结果如下：
+
+| 原始发现 | 主审取舍与修正 | 局部复核 |
+|---|---|---|
+| coherence / P1：U11c先提交run终态，与U9单一“待远端停止”状态不一致 | 接受。明确业务终态与远端执行状态两维；本地取消与撤销发布权同事务，远端停止继续持久对账；U11c依赖U9 | 已确认一致 |
+| feasibility / P2：U8要求产物全部拒绝，但相关资源端实现到U9/U12才落地 | 接受。U8独立验收DB fencing，端到端旧产物拒绝由U9/U12联合验收 | 已确认依赖闭合 |
+| design / P2：unknown/取消中缺状态—操作表且UI适配过晚 | 接受。U9补七行状态/操作契约、有界查询与实际响应解析；最小UI随W2上线，广泛状态重构仍归U15 | 已确认解决 |
+| security / adversarial / product / scope | 未发现达到行动门槛的剩余问题 | 未扩展实现范围 |
+
+已应用3项审阅修正；proposed_fixes=0、decisions=0、fyi=0。主审补充U1所有操作的owner/整改或维持原因清单，以及业务cancelled后仍扫描远端取消未完成记录，保证对应承诺有执行落点。
+
+实际验证：Python检查三份本轮相关文档22条本地链接，全部存在；MCS映射01–22、U1–U17、R1–R12完整唯一；代码围栏、末尾换行、行尾空白、文内路径可移植性检查通过；git diff --check通过。显式代码路径清单核对61项，24项为文中明确规划新增，37项现存；未将新增路径不存在记成实现完成。Mermaid仅人工结构核对，未调用渲染器。
+
+本轮只改四个路径：新增本系统方案、原任务记录、通用采用计划的系统方案指针、CURRENT自己的行。主目录保持干净、dev仍为5c35f32e；未改业务代码、.env、运行配置、生效规范或FEATURE-MATRIX/gap-matrix。Go/PG/PI/浏览器测试均未执行，本轮不适用业务验收。
+
+本轮新成果未提交、未合入dev、未push/部署。此前规范已合入dev的记录仍有效。本地origin/dev...dev读取为18/10，未fetch，不代表实时远端。cleanup继续retained-with-reason：新方案是未提交唯一产物，保留原任务worktree；用户审核及必要集成后，owner退出由独立维护者复查。
+
+建议下一步先审核W0/W1及双维取消契约；获得实施授权后按方案单元登记，先隔离特征测试与正确性修复，再推进结构重构。不得把用户“继续编制方案”解释为已批准所有代码、数据修复或环境操作。
+
+## 2026-09-23 系统整改方案文档入库
+
+授权来源：用户“合并入 dev，不用你实施”。仅提交系统方案、通用采用计划的关联指针及本任务记录；明确不执行U1–U17、不部署、不推送远端。review_state=approved表示批准文档入库，不表示已授权实施或改变规范生效状态。
+
+基线dev=5c35f32e225a482d5838e6d771778fb754f75506；任务分支/worktree沿用原现场，源HEAD等于dev，原三文档改动完整保留。已重读AGENTS/PROJECT/CURRENT、worktree流程及文档验证契约，生效规则未变化。CURRENT本任务行已有done，本轮不改它。
+
+本次机器登记：modular-contract-standard-2026-09-22-system-merge-20260923（原任务工作区，scope限定上述三文档）；集成登记integrate-system-refactor-plan-20260923（既有集成worktree，HEAD为确切dev基线，scope相同，仅git:dev能力）。逻辑task_id沿用不变。候选采用--no-ff，验证精确HEAD后由agentctl integrate推进本地dev。
+
+验证范围为三文档白名单、相对链接、U1–U17/MCS01–22/R1–R12、方案原SHA-256、内容不含机器绝对路径及git diff --check。方案正文冻结为eb06775651546f8af4c1218400ce3198949bbf2d3d566b4cdf6b698407298ea9；不重新跑业务测试或修改方案。
+
+主目录初始只有.codegraph/.gitignore未跟踪，其生成索引codegraph.db已被目录内规则忽略。本轮不擅自移动、删除或将该无关文件混入文档提交；受控集成的清洁条件单独核对。cleanup保留工作区供独立维护者在owner退出后核验。

.doc/remediation/2026-09-22-agent-system-modular-refactor-plan.md

@@ -0,0 +1,712 @@
+---
+title: "Agent-System 模块契约整改与渐进重构 - Plan"
+type: refactor
+date: 2026-09-22
+artifact_contract: ce-unified-plan/v1
+product_contract_source: user-request-and-MCS-v0.1
+origin: .doc/system-design/2026-09-22-generic-module-contract-standard.md
+execution: code
+source_sha: 5c35f32e225a482d5838e6d771778fb754f75506
+task_id: modular-contract-standard-2026-09-22
+---
+
+# Agent-System 模块契约整改与渐进重构 - Plan
+
+## Goal Capsule
+
+**目标**：用户从页面、对话和后台触发同一业务动作时，获得一致的授权与持久结果；单个任务或消费者失败后能够独立恢复，其他工作继续；维护者修改一个领域时无需同时修改多个领域实现。
+
+**方法**：在当前模块化单体上纵向迁移，以统一用例、领域 owner、持久事件和既有 Runner 边界落实 MCS v0.1。先补正确性与恢复缺口，再收敛依赖，最后缩减例外和推广门禁。
+
+**授权与终点**：本次只形成可审核方案。后续实施按 U 单元另行授权、认领和验收；本文件不是开工、数据库修复、事件重放或部署许可。
+
+**权威**：AGENTS/PROJECT/生效 ADR 和验证契约继续约束实施；MCS 为本方案设计依据，保持 proposed，不因本方案出现而自动取代本项目现行规则。与规范冲突时不得静默扩大例外。
+
+**停止条件**：实施中遇到授权/冻结职责变化、既有业务含义必须改变、运行制品不符或存量结果未知时，先停止该切片放量并保存现场；不能通过删队列、换模型、硬重置或回滚数据库让测试通过。
+
+关联：[通用规范](../system-design/2026-09-22-generic-module-contract-standard.md) · [现状审查](../audit/2026-09-22-module-decoupling-current-state.md) · [通用平台规划](./2026-09-22-modular-platform-adoption-plan.md) · [任务记录](../ops/short-term/2026-09-22-modular-contract-standard.md)。
+
+---
+
+## Product Contract
+
+### Problem Frame
+
+现有系统已实现 UoW、文档账本、PG 事件交付、任务持久化、SSE 回放、WorkspaceRef 和 typed PI Runner。主要矛盾是这些机制尚未在所有入口和副作用上形成同一套契约，而非缺少一个全新总线。
+
+本轮源码基线为 dev@5c35f32e。与前次审查 d034aa00 相比，internal/cmd/web/deploy/configs/scripts 无变更；旧审查可复用，以下新增结论来自定向深化。没有查询当前业务数据库、运行镜像或实际积压，没有执行产品测试，因此不将源码可达风险称为已复现事故。FEATURE-MATRIX 与 gap-matrix 的历史 PASS 保留其原范围，不作为本次全系统现状背书。
+
+### Requirements
+
+| ID | 要求 | 用户可见/维护结果 |
+|---|---|---|
+| R1 | HTTP、对话、Agent owner 和恢复入口共享业务用例 | 相同动作的权限、状态、事件一致 |
+| R2 | 所有写动作绑定可信身份、资源范围、当前授权与冻结职责 | 确认、项目创建、普通聊天不隐式授予任务权限 |
+| R3 | DB 业务状态、相应收据/outbox 与本地可见状态保持提交一致 | 回滚后无假批准、假消息或假终态 |
+| R4 | 事件发布/消费都有明确 schema、来源和去重规则 | 同 ID 异载荷拒绝，未知输入隔离 |
+| R5 | 按真实事件语义消费稀疏版本，且同聚合竞争领取安全 | 首次高版本不卡死，旧投影不覆盖新状态 |
+| R6 | 任务受理、执行所有权、恢复和终态可持久核对 | 进程重启后可确定谁在执行、结果在哪里 |
+| R7 | 超时、取消与远端执行未知结果可区分和对账 | 不因响应丢失盲目启动第二次执行 |
+| R8 | SSE 游标代表可恢复进度，前端状态绑定用户/项目/会话/任务 | 刷新、切项目与重连不会串状态或吞终态 |
+| R9 | 表、文件和公共模型具有明确 owner | 跨模块通过端口操作，不能绕道直写 |
+| R10 | 消费者与外部执行器具有明确资源预算和失效处理 | 慢任务不会耗尽所有消费者资源 |
+| R11 | 结构重构保持现有功能、授权和协议兼容 | 重构不夹带功能放量和流程规则变更 |
+| R12 | 每个切片有分层验证、兼容迁移和回退范围 | 只有实际证据支持的能力才记完成 |
+
+### Protected Behaviour
+
+- 保持三正式工作流及已接入 rdev 的现有行为，不修改工作流发布键、文档 ID、角色含义和冻结计划规则。
+- 零治理项目创建、普通对话与发起文档任务分开授权；不增加创建者/任意职责绕过。
+- project 143 只读、不终止，不作为写入测试夹具。
+- FAV 分支不整支合并，FAV consumer 继续 off，FAV_DEGRADED_READ 保持 false；不借路径整改上线 FAV。
+- MULTI_INTENT_PLAN_TIER 不自动升 full，SEMANTIC_SUMMARY_REPLACE 不顺带启用，SWBOOT-10 保持原 fail-closed 边界；D7 不新增物理删除。
+- 保持 typed-result 存在但非法时 fail closed，安全错误信封不退化为 SQL/路径/正文泄漏。
+- 不新建跨项目 SDK 仓库、不全系统 HTTP 化、不引入新 broker、不改 test/main。需要新增协议或隔离等级时先限定在既有 Runner/MinerU 边界。
+
+### Acceptance Examples
+
+| ID | 场景 | 必须观察到的结果 |
+|---|---|---|
+| AE1 | 同一批准动作分别由页面和真实对话触发 | 同样拒绝越权；各自合法操作只有一次状态/事件/通知与推进效果 |
+| AE2 | outbox/通知写入故障与 shadow 执行 | 业务事务回滚；shadow 不产生真实消息、通知或业务指针变化 |
+| AE3 | 第一条事件 v42，下一条 v47；两 worker 同时领取 | 可推进且无同聚合并发效果；重复/晚到事件按消费者策略处理 |
+| AE4 | 同键同输入并发、同键异输入、受理后崩溃 | 一个任务；异输入冲突；重启后可查询并恢复受理状态 |
+| AE5 | 旧 worker 失租后恢复，远端调用响应丢失 | 旧写被拒绝；查询原执行，不盲目再启动 |
+| AE6 | 完成与取消竞争、页面断线/切项目/重登 | API 返回实际持久终态，UI 可重同步且不污染其他作用域 |
+| AE7 | 工作区投影丢失，但账本存在 | 读正文仍成功且 GET 不修复；授权负例仍拒绝 |
+| AE8 | 新旧契约混跑、积压事件和进程重启 | 兼容阶段可回退，隔离项保留，恢复不重复不可逆副作用 |
+
+---
+
+## Evidence and Standard Mapping
+
+### Findings Driving Sequencing
+
+| 编号 | 当前源码事实及锚点 | 整改影响 |
+|---|---|---|
+| E1 | events/dispatcher.go:39–84 要求 head+1；app/docflow/commands.go:182–214 使用记录 ID/候选 ID | 不能只调重试；必须恢复已接受的首事件 bootstrap 语义 |
+| E2 | chat/action_executor.go:68–76 直调 Gov；server/handlers.go:793–808 走 docflow；app/app.go:294–307 停止旧 hook 注册 | 统一批准入口，但先加固用例授权和事务可见性 |
+| E3 | app/docflow/commands.go:65–84 的 DutyAuthorizer 对零身份/空职责仅做条件比较 | 不能简单移除 HTTP 前置 CheckDocTaskAccess 后声称行为等价 |
+| E4 | app/docnotify/consumer.go:65–67 忽略 PostProjectNotice 错误；chat_notice.go:29 经 ctxmgr/manager.go:197–230 的 pool 自提交 | 存在会话时，事件事务回滚/shadow 不能回滚该聊天副作用 |
+| E5 | events/registry.go:47–48 的 taskrun payload 仅列 run_id，taskrun/finalize.go:431–439 实际写更多字段；docflow Producer 与清单名称不一致 | 先盘点真实 producer，不能直接上线严格校验阻断正常终态 |
+| E6 | taskrun/store.go:305 获取租约可覆盖 worker；manager.go:257/768 失败只告警；UpdateRun 仅按 run_id | 有 lease 字段仍不足以防旧执行者提交 |
+| E7 | task_run_handlers.go 与 app/plan_owner.go 各自受理；既有键不比较完整业务摘要，owner 收据只在内存 | 复用 ClaimRun/Manager，增加公共受理与持久请求/收据 |
+| E8 | agent/piagent.go 将传输错误视为可重试；runner.mjs 直接 spawn 且按 workspace 管进程 | 必须区分业务 run、step、attempt 和 invocation 身份 |
+| E9 | taskrun/manager.go:523 附近先推订阅再落库，满通道可丢弃；非本地 run 仅一次回放 | 游标与实时通知须以持久事件/快照为依据 |
+| E10 | docgov 批准先改 memDocs/memAudits 后写 SQL；taskrun/finalize.go:130–141 总是新 Within；projectinstance/store.go:911–922 直接写 projects/task_runs | DB owner 迁移同时处理缓存回滚与嵌套事务，不能只搬 SQL |
+| E11 | workspace/lease.go 是进程内 map，Capability 读 guard 不完成项目授权；路径扫描还把 admin 路由当 workspaces/ 依赖 | 不把字符串归零或内存 token 当跨进程能力隔离证明 |
+| E12 | 前端已有 RequestEpoch、身份缓存和重连工具，但 App/setter 耦合与部分异步回调仍跨 scope | 复用已有设施，补实际 hook 与浏览器验证 |
+
+以上源码路径除 web/deploy 显式注明外均位于 internal/。风险后果依赖所列路径与输入成立；实际影响范围由实施前隔离复现和获授权运行只读盘点确认。特别是 E4 不等于已观察到现网 shadow 污染。
+
+### MCS Coverage
+
+| 条款 | 本系统采用方式 | 执行单元 |
+|---|---|---|
+| 01 隔离档位 | server 内 L1；events/Runner/MinerU 既有进程边界按 L2 能力实测 | U1/U6/U9/U17 |
+| 02 职责与 owner | 模块/表/文件设计卡，既有 owner 清单补漏 | U1/U11/U12 |
+| 03 公开契约与依赖 | 入口→应用→领域端口；具体装配留 app/cmd | U13/U14/U16 |
+| 04 同动作同入口 | 文档动作与任务动作各一组用例 | U5/U7 |
+| 05 契约类型独立 | 消费者窄接口、稳定 DTO，不导出实现别名 | U13/U14 |
+| 06 四种通信语义 | Query、Command、Event、SSE 分开定义成功 | U5/U7/U9/U10 |
+| 07 总线/编排分离 | events 管交付，taskrun 管执行，业务流程归 app/coordinator | U6/U7/U13 |
+| 08 完整契约 | 身份、版本、幂等、错误与预算纳入操作卡 | U1/U3/U5/U7 |
+| 09 事件信封 | 实际字段/producer 校验、消费者入口复核 | U3 |
+| 10 唯一写者 | 5 条 SQL 例外回归属主，并扫描漏登记表 | U11/U16 |
+| 11 原子事务 | 文档/任务/通知/收据加入同一 UoW | U2/U5/U7/U11 |
+| 12 锁与外部 IO | DB 短事务；Runner/文件操作分准备与提交 | U8/U9/U12 |
+| 13 幂等 | 事件摘要冲突、任务请求摘要、效果端收据 | U2/U3/U5/U7/U9 |
+| 14 delivery 恢复 | 当前 token 校验、失租停止、受控重放 | U4/U6/U8/U17 |
+| 15 顺序与并行 | 首高版本 bootstrap，聚合内独占、聚合间并行 | U4 |
+| 16 持久调度 | 复用 task_runs/intentflow，补 pending 恢复和 owner receipt | U7/U8 |
+| 17 资源预算 | 独立消费者池、有限预取、超时/重试/连接配额 | U6/U9 |
+| 18 授权 | Principal 来自认证事实；执行与重放重验权限 | U3/U5/U7/U9/U17 |
+| 19 可观测 | operation/run/event/attempt 关联，lag/lease/unknown 指标 | U6/U8/U9/U10 |
+| 20 生命周期 | 停止领取、排空、孤儿扫描、真实 readiness | U6/U8/U17 |
+| 21 演进 | producer/consumer 兼容矩阵、additive 迁移、逐入口切换 | U3/U9/U10/U17 |
+| 22 例外与门禁 | 期限治理、语义扫描、运行负例和 N/A/SKIP 分离 | U1/U16 |
+
+---
+
+## Planning Contract
+
+### Key Technical Decisions
+
+- KTD1. 保留模块化单体与纵向迁移；不先建通用平台。对应 R9/R11，遵守现行模块化单体 ADR。
+- KTD2. 两个主应用入口族：文档动作继续扩展 app/docflow；任务受理新增窄 app/taskflow，复用 taskrun.Manager。server/chat/plan owner 只做协议适配和调用。对应 R1/R2。
+- KTD3. 认证身份传递与资源授权分开。用例从 DB 权威关系解析 project/doc/task/duty，所有入口使用同一 action 策略；服务身份不能伪装 UserID=0 的万能人类。对应 R2。
+- KTD4. DB 内效果、幂等收据、事件确认必须同事务，缓存变更在提交后生效；非事务副作用移到提交后可恢复执行。对应 R3。
+- KTD5. 保持 checkpoint+bootstrap ADR，不引入无缺口全局 event_seq；已有事件 ID 不改写，晚到事件不能单凭小于 checkpoint 就丢弃。对应 R4/R5。
+- KTD6. events 交付 lease 与 taskrun 执行 lease 分别实现和验证，不做万能 LockService。单表唯一写者可参与调用方同一 UoW；从跨模块 SQL 迁移到 owner 不能新开嵌套事务。对应 R6/R9。
+- KTD7. 外部执行复用现有 HTTP typed-result-v1，增加可选能力协商与执行收据。超时进入结果未知；重试同 invocation，不重启未知旧执行。对应 R7。
+- KTD8. SSE 为持久事实的观察通道。可靠事件先提交再推送；临时高频进度可合并，但必须标注并以持久 snapshot 重同步。对应 R8。
+- KTD9. 校验加严先于兼容消费者/producer 升级是不安全的。先修 producer 与副作用，再库存分类，后启用严格校验和新领取器；暂停消费时仍可靠记录新事件。对应 R4/R12。
+- KTD10. 不通过放宽 allowlist、重置基线或修改公开路由追求“零耦合”。保留必要组合根依赖，区分真实越界与扫描误报。对应 R9/R12。
+
+不引入新 RPC/消息产品，因此不做选型型外部研究。并发方案只核对 PostgreSQL 官方行锁/事务 advisory lock 及 SKIP LOCKED 的边界；它们支持领取算法设计，不能代替本系统多进程测试。[锁语义](https://www.postgresql.org/docs/current/explicit-locking.html)、[SELECT/SKIP LOCKED](https://www.postgresql.org/docs/current/sql-select.html)。
+
+### Target Module Responsibilities
+
+下表是逻辑边界，不要求按表创建同名新包，也不要求全部模块独立进程。
+
+| 职责族 / 现有包 | 持有数据与不变量 | 对外能力 / 整改边界 |
+|---|---|---|
+| auth/authz | 会话、用户、授权策略 | 认证事实与动作授权；不持业务执行状态 |
+| projectworkflow/projectinstance | 项目、工作流实例、冻结职责和阶段 | ProjectAccess/InstanceQuery/WorkflowCommand；跨域终止归 app 编排 |
+| workflowdef/workflow/runtime/workflowscope | 定义、校验、运行解释 | 冻结定义 DTO 和实例端口，运行时不穿透实例 Service |
+| docgov/docduty | 文档治理状态与职责维护 | DocCommands、DutyCommands；document_records SQL 归 docgov |
+| docrevision/docquery/doccontent | 版本/快照、权威正文、内容语义 | RevisionCommands/DocumentQuery；GET 不隐式修复 |
+| freedoc | 自由文档根与 owner 范围 | 自由文档指针由 freedoc owner 在同 UoW 更新 |
+| ctxmgr/chat | 会话/消息/turn、授权读取 | ChatLog/ContextAssembler/事务消息写入；chat 不装配领域实现 |
+| intent/app/intentflow | 分类与既有持久计划 | 不改变开放级别；计划确认不替代业务执行授权 |
+| app/taskflow + taskrun | 受理契约、run/manifest/events、执行所有权 | Admission/RunQuery/Resume/Cancel；复用已有 Manager |
+| coordinator/bizdev/squad | 业务编排与小队步骤 | 接受冻结输入、调用端口，不自行占有全部存储 |
+| agent/mineru | 远端执行与解析适配 | Execute/Query/Cancel；不成为文档事实源 |
+| workspace/storage/upload | 有界工作区、CAS、上传暂存 | WorkspaceRef/ArtifactRef；路径解析和原子发布集中 |
+| materialindex/kb/projectcontext | 索引、知识检索与上下文组合 | 先授权再检索，索引不是业务写权；跨模块读取通过查询端口 |
+| events + app/docnotify/docadvance/docproject | 信封、delivery/inbox、订阅效果 | events 只交付；效果通过所属模块的事务端口 |
+| notification | 站内通知与阶段就绪请求 | 幂等通知写入，不借总线直接写聊天表 |
+| traceimpact | 关系、追踪修订、复核建议 | 只读/命令契约保持；本轮不自动确认关系或传播删除 |
+| sysadmin/config | 系统设置与环境配置 | 白名单配置、明确消费者，不与个人工程工具合并 |
+| artifactvault/dataset | 已有禁用/部分能力及相应数据 | 按原状态保留；不以本计划启用 FAV 或物理删除 |
+| web 功能域 | 会话视图、运行观察、文档投影 | 分域状态 owner；统一 transport、领域 DTO 和流适配仍分开 |
+
+### High-Level Technical Design
+
+```mermaid
+flowchart TB
+  UI["页面 / 对话 / Agent owner / 恢复命令"] --> Entry["HTTP / chat 协议适配"]
+  Entry --> Doc["app/docflow 文档用例"]
+  Entry --> Task["app/taskflow 任务用例"]
+  Doc --> Policy["当前资源与冻结职责授权"]
+  Task --> Policy
+  Doc --> Owners["docgov / docrevision / freedoc / ctxmgr owner"]
+  Task --> Run["taskrun Manager 与 fenced 存储"]
+  Owners --> DB["PostgreSQL / UoW / outbox"]
+  Run --> DB
+  DB --> Events["events 领取与独立消费者执行槽"]
+  Events --> Effects["notify / advance / projection"]
+  Effects --> Owners
+  Run --> Runner["PI Runner / MinerU"]
+  Runner --> Workspace["按执行代次隔离的工作区"]
+  Workspace --> Publish["账本提交与产物发布校验"]
+  Publish --> Owners
+  DB --> SSE["持久事件 / snapshot / SSE"]
+  SSE --> UI
+```
+
+```mermaid
+sequenceDiagram
+  participant C as 页面或对话
+  participant A as 应用用例
+  participant D as 业务数据库
+  participant W as 事件消费者
+  C->>A: 认证身份 + 动作 + 幂等键/expected_version
+  A->>D: 授权复核、锁定资源、状态/收据/outbox同事务
+  D-->>A: commit
+  A-->>C: committed 或可靠accepted
+  W->>D: 独占领取一个聚合的delivery
+  W->>D: 效果owner写入 + inbox + fenced ack同事务
+  D-->>W: commit
+  C->>A: 刷新/断线恢复查询
+  A->>D: 授权读取权威状态
+  A-->>C: 一致的结果与持久游标
+```
+
+```mermaid
+stateDiagram-v2
+  [*] --> accepted: 请求及身份已持久保存
+  accepted --> running: 原子claim获得执行代次
+  running --> reconciling: 远端响应丢失或worker失联
+  running --> cancel_requested: 用户显式请求
+  cancel_requested --> reconciling: 未确认执行停止
+  reconciling --> running: 同执行身份查询确认继续
+  reconciling --> interrupted: 确认无执行但需人工resume
+  running --> terminal: finalizer及结果同事务提交
+  cancel_requested --> terminal: 业务CAS确定结果并撤销旧发布权
+  reconciling --> terminal: 查询确认已有业务结果
+  interrupted --> running: 用户确认后以新代次恢复
+```
+
+这张图表达业务操作过程；terminal 仅指权威业务终态，远端进程是否停止另用 execution_state/cancel_delivery_state 跟踪，不能由业务cancelled推断。cancel_requested/reconciling 优先使用兼容的操作状态/metadata表达，不立即扩展 task_runs.status 枚举。保留 completed/failed/cancelled/interrupted 的业务值，UI按两个维度一起解释；若必须改枚举，须U9独立协议迁移。
+
+### Phases and Dependencies
+
+| 阶段 | 单元 | 交付门槛 |
+|---|---|---|
+| W0 特征与契约基线 | U1 | 明确适用能力、冻结基线、建立能发现问题的测试入口 |
+| W1 正确性修复 | U2→U3→U4；U5 与其协调 | shadow 无真实写、严格校验不误伤 producer、稀疏事件可安全推进、批准入口一致 |
+| W2 执行与观察可靠性 | U6；U7→U8→U9及最小UI适配；U10 | 有界消费者、持久受理、旧 worker 拒写、未知结果可对账、可靠回放 |
+| W3 领域边界收敛 | U11/U12→U13→U14 | owner 回归、路径集中、接口隐藏实现、工作流依赖单向 |
+| W4 前端与门禁 | U15/U16 | 作用域隔离、精确架构规则和负例 |
+| W5 验收与逐批放量 | U17贯穿各阶段，最终收口 | 每批独立制品、真实业务、恢复与回退证据 |
+
+依赖还包括：U5 依赖 U2/U3 的事务/契约成果；其上线与 U4 兼容。U6 在 U4 后改变调度。U7 可在 U1 后开发，接线到生产要等待 U3；U8 在 U7 后，U9 在 U8 后；U10 依赖 U8，取消恢复场景等 U9。U11a/b 需要 U5，U11c 需要 U8/U9；U12 需要 U5/U9 的发布身份；U13 依赖对应域的 U5/U7/U11/U12；U14 在 U11/U13 后；U15 的 transport 可先开发，最终整体验收等 U9/U10；U16 的检测器可早做，收紧规则随每批成果落地。
+
+原 A–G 所称 A/B/C/D 可并行不能直接套用：它们共享 app/app.go、docgov 契约、server 和 module-boundaries.yaml。上述文件及迁移号各时段仅一个写者，公共变更由该切片整合。任务分支统一 feature/<task-id> 或 fix/<task-id>，不用旧方案中的 refactor/* 前缀。
+
+---
+
+## Implementation Units
+
+每个 U 是一个验收工作包，内部较大的包按明确子切片提交；不得把 U11/U13/U15 整包做成单次巨型重构。代码、必要回归和对应边界规则同批交付。下列“新增”路径为规划，不冒充现存文件；迁移号在实施认领时分配，不预占。
+
+### U1. 建立当前契约、生产者与验证基线
+
+**需求/依赖**：R11/R12；无代码前置。owner：架构协调者；mutex：architecture-docs、module-boundaries。
+
+**文件**：现有 module-boundaries.yaml、FEATURE-MATRIX、验证契约、各域现有测试；拟新增 `.doc/system-design/2026-09-22-agent-system-module-contracts.md` 与 `.doc/test-reports/2026-09-22-modular-refactor-baseline.md`。
+
+**交付**：登记本文模块职责、真实入口→用例→owner→事件→消费者矩阵；每个现有操作都标明本轮整改单元，或维持现状的原因及回归用例，不遗留无owner的系统边界。逐个事件记录实际 payload、producer、订阅者/no-op 与顺序语义。记录有效配置来源、待整改例外和最老消息指标的获取方法。运行采样只在获授权实施阶段开展，禁止读取正文/秘密作为盘点材料。
+
+**验证**：复用 existing tests 建立 expected_tests，不把旧报告当新 PASS；缺独立 DSN/Runner 时明确 blocked 或 SKIP。每个负例先能暴露本轮对应问题。纯基线文档不新增镜像/业务测试代码。
+
+**完成/回退**：形成固定 SHA 与隔离环境证据；不改 production_ready、不启用 feature flag。基线不齐则该切片不能放量，允许继续不依赖运行的端口设计。
+
+### U2. 修复通知效果事务与 shadow 零业务写
+
+**需求/依赖**：R3/R4，AE2；依赖 U1。owner：ctxmgr/notification；mutex：ctxmgr、docnotify、events、迁移号。
+
+**文件**：`internal/app/docnotify/consumer.go`、`chat_notice.go`、`internal/ctxmgr/message_update.go`；新增 `internal/ctxmgr/event_notice.go`、`event_notice_pg_test.go`，扩展 `internal/app/docnotify/e1a_pg_test.go`；additive migration 新增 ctxmgr-owned 通知效果收据。
+
+**设计**：ctxmgr 接受调用方 TxScope，写消息/会话更新/收据；docnotify 不吞写失败。效果键固定为 source_event_id + effect_kind + recipient，首次选择的 session/message 写入收据；session 变化不改变去重身份。找不到会话采用明确的持久 no-op 收据，不在重投时随机改投新会话。通知、消息、收据与 ack 同事务。正式 shadow 改为只读效果规划与独立对账，不调用能自提交/改缓存的生产副作用；过渡回滚模拟仅用于已证明全部效果同事务的隔离测试。
+
+**测试**：
+
+1. 存在真实 PG 会话时重复 shadow，chat_messages、notifications、chat_sessions 内容/更新时间均无业务变化。
+2. 消息写失败或 ack 前故障，消息、通知、收据整体回滚；重投恰好一次可见效果。
+3. 重试前最新会话改变、用户权限撤销、目标文档不属于项目，分别去重或拒绝。
+4. 无会话 no-op 后重放保持既定结果，运营重新通知必须是新授权动作。
+
+**完成/回退**：复用 TestE1A_NotifyShadowLiveRollback_PG 并加入真实 Chat 依赖；不能只测 notification 表。回退到旧 notify 实现前必须暂停相关消费，不能以旧 shadow 保安全；新增收据保留。
+
+### U3. 事件契约兼容、严格校验与身份冲突
+
+**需求/依赖**：R4/R12；依赖 U1，生产放量需 U2。owner：events；mutex：events、docflow、taskrun/finalize、registry/YAML。
+
+**文件**：`internal/events/registry.go`、`envelope.go`、`pg.go`、`inventory.go`、`inventory_store.go`、`worker.go`、`internal/app/docflow/commands.go`、`internal/taskrun/finalize.go`；扩展对应测试，新增 `internal/events/contract_validation_pg_test.go`。
+
+**设计**：
+
+1. 新 docflow producer 统一为 app/docflow；旧 docflow 只在限定 legacy 读兼容中归一识别，保留原 envelope/digest。
+2. taskrun v1 兼容旧 run_id-only 与已有完整 payload，明确字段类型与可选性；intent 的 payload environment/project/引用必须与 envelope 一致。
+3. PGSink/InsertEnvelope 共用验证器；hydrate 后、handler 前复验；inventory 同规则。producer 字符串只是代码标识，可信源仍由受控写入口/部署身份提供。
+4. 同 event_id 冲突时比较稳定事实字段与 payload digest；相同事实幂等返回，不重置 delivery；不同事实 typed conflict，不补投递行。occurred_at 重试生成差异不单独构成冲突。
+5. 保持 payload bytes 的现有摘要算法，不夹带 canonical JSON 迁移。taskrun/intent notify 当前成功 no-op 必须显式登记，不顺带新增用户通知。
+
+**测试**：全量实际 producer 样例、legacy alias、两种 taskrun payload、非法 scope/schema/字段/来源、同 ID 异 digest/项目、重复 delivery 状态不变、intent envelope/payload 范围不符。保留 TestRegistryParityWithYAML。
+
+**完成/回退**：先兼容 reader/writer，后严格模式；不得让正常 finalizer 因漏登记字段失败。此单元无需新事件表/版本序列；严格校验回退保留已隔离数据，不能自动释放。
+
+### U4. 稀疏版本、聚合独占与毒消息处理
+
+**需求/依赖**：R5/R6，AE3；依赖 U2/U3。owner：events；mutex：events/dispatcher。
+
+**文件**：`internal/events/dispatcher.go`、`pg_test.go`、`dispatcher_pg_test.go`；新增 `aggregate_claim_pg_test.go`。保持 00035/00040 已发布迁移不变。
+
+**设计**：删除 PG 的 checkpoint+1 领取限制，保留 checkpoint+首 safe 事件 bootstrap ADR。短 claim 事务先对 consumer/environment/aggregate 的稳定命名空间取得 try-advisory-xact-lock，随后用 READ COMMITTED 下新的 SQL statement 重新检查有效 lease、inventory 与最早未完成事件，再按容量每聚合领取一条并提交。不要先锁 delivery 再等聚合锁，也不要依赖锁前 CTE 快照。环境过滤显式传入。
+
+顺序按数值 aggregate_version、occurred_at、event_id 稳定排序；最早事件在 retry backoff/expired lease/dead/quarantine 时不得越过它。dead/quarantine 需要明确授权的恢复决定，其他聚合继续。未知 scope 隔离自身，不能污染另一 scope 的锁或检查点。
+
+领取顺序只保证当前可见队列：notify 的晚到低版本仍按事件处理；projection 由 owner 判旧版本 no-op 并记收据；workflow_advance 重读当前 approved/范围；intent 按 payload revision 更新。checkpoint 高水位不证明全部低版本效果已完成。
+
+**测试**：首次 v42、42→47；2/4 真实 worker 同时首领；同批多事件；旧 lease 接管；backoff/毒消息仅阻塞相应聚合；notify 晚到不丢、projection 不回退；错环境不领取。替换 TestVersionClaimableMatchesMemoryBusGap 的错误 PG 约束，MemoryBus 单独标为 characterization。
+
+**完成/回退**：不新增无缺口 event_seq、不重写历史 envelope/检查点。新旧 claim 协议禁止混跑；停领、排空、替换所有 worker 再恢复。回旧二进制可能恢复旧停滞，只能暂停并前滚修复，不能抬 checkpoint 或清队列。
+
+### U5. 文档动作唯一用例、完整授权与缓存原子性
+
+**需求/依赖**：R1/R2/R3，AE1；依赖 U2/U3，与 U4 联合验收。owner：docflow/docgov；mutex：docgov、chat/action、server 文档入口、app 装配。
+
+**文件**：`internal/app/docflow/commands.go`、`internal/docgov/engine.go`、`repository.go`、`internal/chat/action_executor.go`、`internal/server/handlers.go`、`stage_access_helpers.go`；新增 `internal/chat/action_ports.go`、`internal/app/chat_action_adapter.go`、`internal/app/docflow/action_parity_pg_test.go`、`cache_rollback_pg_test.go`。
+
+**设计**：
+
+1. 扩展现有 Commands 的送审/审核/批准/驳回明确动作；chat 调消费者自有端口，由 app adapter 接同一用例，不引入全局 ActionBus。
+2. 用例在可信 Principal 和完整依赖存在后，解析 doc→project/task/governing instance、阶段、enabled、精确职责与冻结策略。不能直接信任当前 DutyAuthorizer 的零 ID 条件放行，也不能让缺依赖的 CheckDocTaskAccess 构成允许。
+3. PG 路径基于同事务完整记录执行状态机；补齐 GetForUpdate 所需字段。缓存/审计只在提交成功后发布；rollback 后当前实例与重建实例一致。生产缺 UoW/EventSink fail closed。
+4. 人工修订复用既有 change-event 幂等；治理状态动作增加 docgov-owned command receipt（必要的 additive 表），键包含 actor/scope/action/key、请求摘要和结果 revision。legacy 无键请求维持状态/CAS校验且禁止自动写重试；新客户端传稳定键。
+5. 新批准事实身份绑定持久 decision/row revision，区分“同次重试”与“重新提交后的新批准”；不能永久用文档记录 ID 去重所有批准。旧事件保留。旧 hook 不与 durable 消费者双发。
+
+**测试**：HTTP/真实对话各完成合法动作；actor=0/伪造角色/跨项目/创建者无职责/职责撤销/关闭实例均无副作用；outbox 与 commit 故障时原实例缓存、审计、重建实例、DB 同时不变；批准/驳回竞争；同键异参数；返工后再次批准有新事实，重试不重发。复用 commands_scope_test、e0a_pg_test、state_machine_duty_policy_test、access_governing_pg_test。
+
+**完成/回退**：保持 wire 错误与职责含义，前置授权在新用例负例通过前不移除。回退不得重新开放已确认的旁路；若旧实现不安全，暂停该写入口并前滚，查询保持可用。
+
+### U6. 消费者执行预算、失租停止与可观测性
+
+**需求/依赖**：R10/R12；依赖 U4。owner：events/runtime；mutex：events worker、cmd/events、相关配置。
+
+**文件**：`internal/events/worker.go`、`dispatcher.go`、`cmd/events/main.go`、既有配置/Compose 的 events 段；新增 `internal/events/worker_isolation_pg_test.go`、`worker_drain_test.go`。
+
+**设计**：每 consumer 独立有界执行槽/循环/deadline；按空闲槽 claim，未获得执行容量不预占 lease。handler pool、心跳/控制连接有分别预算，总连接不超过环境 DB 预算。失租取消活动 handler，ack/fail/续租按当前 token 和真实数据库当前时间判断；不以事务起点 now() 充当长处理后提交时有效性。活动 cancel 按 lease key 管理并结束清理。
+
+注册/RunOnce 错误不吞掉；监控 oldest pending、blocked aggregate、retry/dead/quarantine、处理耗时、失租和实际 modes。readiness/liveness/业务进度分开。容量阈值在 U1 隔离基线后冻结，初始小并发，不凭 goroutine 数宣称隔离。
+
+**测试**：慢 notify 时 projection/advance 在各自预算内完成；handler pool 满时续租仍可用；批量等待不耗尽租期；到期旧 token 不可复活；停机先停领再排空，超时留下可接管状态。
+
+**完成/回退**：先保持已有进程拓扑，以资源隔离达标为准。无法隔离的高风险效果另立进程拆分决定；不是本轮默认增加服务。回退并发前先排空，不清 attempts/inbox。
+
+### U7. 统一任务受理与持久请求/收据
+
+**需求/依赖**：R1/R2/R6，AE4；开发依赖 U1，接线放量依赖 U3。owner：taskflow；mutex：server task_run、app/plan_owner、taskrun store、ctxmgr。
+
+**文件**：新增 `internal/app/taskflow/commands.go`、`ports.go`、`types.go`、`admission_pg_test.go`；调整 `internal/server/task_run_handlers.go`、`internal/app/plan_owner.go`、`internal/taskrun/manager.go`、`store.go`、`types.go`；新增 `internal/app/plan_owner_pg_test.go`。
+
+**设计**：将 HTTP 已有项目/duty/scope/busy 检查收进公共受理用例；计划 owner 复用，确认后执行仍重验权限。复用 ClaimRun/client_turn_id 和 task_runs 唯一键，不造第二执行器。以 additive 字段保存版本化命令输入、规范化摘要、受理结果及消息引用；输入不含秘密，原始正文使用现有不可变内容引用。
+
+受理、必要聊天绑定和请求收据尽量同 UoW；不能事务化的旧兼容步骤以可恢复状态补齐后才能 accepted。worker 只执行已经完整受理且授权有效的输入。pending 崩溃恢复是明确扫描路径；历史无请求快照的 run 不自动猜参数执行。LookupReceipt 从持久 run 查询，不依赖内存 map。现有 Fake query owner 在生产未开放路径维持 unavailable/validated_only，不随本轮升多意图级别。
+
+**测试**：保留 ClaimRun/ClaimThenStart 并发、busy 不留消息测试；加 HTTP/Agent 同请求同结果、同键异 task/payload冲突、确认后撤权、claim后崩溃、消息绑定失败、重启 receipt lookup。创建/聊天成功不代表有启动任务权。
+
+**完成/回退**：新增元数据旧 reader 可忽略；旧 worker 不得读取无法理解的新受理命令。先兼容读、再切 writer；未完成受理保持可查询状态，不通过删除 run 解决。
+
+### U8. taskrun 执行代次、fencing 与恢复
+
+**需求/依赖**：R6/R10，AE5；依赖 U7。owner：taskrun；mutex：taskrun manager/store/finalize、迁移号。
+
+**文件**：`internal/taskrun/manager.go`、`store.go`、`types.go`、`finalize.go`；扩展 store_lease_pg_test、finalize_pg_test；新增 `lease_fencing_pg_test.go`。
+
+**设计**：在 task_runs 增加执行 epoch（或等价可比较代次），pending→running/confirmed resume 与 lease 获取以 DB 条件更新一次完成。获取失败不得启动，heartbeat 拒绝后停止新工作。进度写、事件序号、manifest/finalizer、产物发布均携带 run+attempt+epoch 并受资源端校验。不得先 UpdateRun 覆盖 owner 再尝试 acquire。
+
+周期扫描仅标识孤儿/可恢复状态；用户确认 resume 的原规则保留。新 Manager 与旧 Manager 的竞争协议不兼容，升级采用停止新受理、排空/明确标识中断、替换后再接管；不能假定滚动混跑安全。
+
+**测试**：两 Manager 同时 claim/resume 仅一个执行；失败 claim 不调用 executor；续租失败停写；旧进程暂停→新 owner接管→旧进程恢复，其DB进度/消息/终态/发布许可写入均拒绝；完成/取消竞争仍只有一个终态；pending 与 running 恢复分别验证。
+
+**完成/回退**：本单元独立完成DB执行代次与owner写入校验；Runner工作目录和文件发布的端到端旧产物拒绝，在U9/U12联合验收后才可声明。真实独立 PG/多进程证据，保留 TestManager_DoneEmittedAfterFinalize 等。发布新 fencing 后不能直接回旧 writer 绕过 epoch；先停写、排空到兼容边界，优先前滚。不回滚业务数据库。
+
+### U9. PI Runner 执行身份、未知结果与取消协议
+
+**需求/依赖**：R7/R10，AE5/AE6；依赖 U8。owner：agent/Runner；mutex：agent、deploy/pi-agent、taskflow cancel。
+
+**文件**：`internal/agent/piagent.go`、`remote_result.go`、`step_retry.go`、`deploy/pi-agent/runner.mjs`、任务取消用例/handler，以及 `web/src/api/taskRuns.ts`、`web/src/App.tsx`、`web/src/hooks/useTaskRunAttempts.ts` 的最小协议适配；新增 `internal/agent/remote_execution_recovery_test.go`、`deploy/pi-agent/tests/execution-lifecycle.test.mjs`、`internal/server/task_run_cancel_pg_test.go`。
+
+**设计**：区分业务 run_id、step_id、execution_attempt、invocation_id。对同 invocation 可靠去重启动，并提供受身份保护的状态/结果查询与精确取消；执行结果用不可变回执，服务重启后可恢复/明确 unknown，不能只依赖 activeChildren map。旧版本 Runner 通过能力协商走受限兼容模式；新能力未确认时禁用危险的传输错误自动重启。
+
+按 attempt 隔离工作目录，旧执行器不能直接改当前权威产物；提升结果到文档/任务终态仍校验 U8 的 epoch。Runner 收据只证明执行状态，不成为第二业务事实源。传输超时先查询同 invocation；确认未开始/无副作用后才可新 attempt。
+
+取消采用两个状态维度：请求尚未在DB提交时为cancel_requested；本地业务CAS取消成功后，task_runs可为cancelled，并在同UoW撤销旧执行发布权、写消息/收据/取消意图/outbox。远端仍可能stopping/unknown，须继续对账，不能宣称物理停止。完成已胜出则返回completed；响应始终读取实际持久结果。再次启动/恢复还须确认原执行已停止，或经明确策略证明旧执行完全隔离且无法产生外部效果。工具权限/profile保持原批准范围，不放开新工具。
+
+最小前端协议适配是U9放量前置，广泛状态owner重构仍归U15：
+
+| 业务与执行状态 | 页面表达 | 允许操作 |
+|---|---|---|
+| running + reconciling/unknown | 正在核对执行结果 | 保留run/invocation，查询原执行；禁止新attempt重试 |
+| 取消请求尚未确认提交 | 已请求取消，尚未确认 | 查询/重查同一取消请求，不宣称取消成功 |
+| cancelled + stopping/unknown | 任务已取消，执行器停止待确认 | 继续查询停止结果；不创建新执行 |
+| 取消请求失败且仍running | 取消未成功，任务仍在运行 | 保持观察和run身份，可再次明确请求取消 |
+| completed胜出 | 任务已完成 | 显示持久结果，不覆盖为cancelled |
+| interrupted且服务端允许恢复 | 任务已中断，可确认继续 | 仅用户确认后创建获准的新代次 |
+| 仅观察连接断开 | 连接中断，正在恢复进度 | 重连/手动查询，不修改业务状态 |
+
+前端查询使用有界退避和单次超时；达到观察预算后显示“暂无法确认，可重新查询”，保留身份，不继续无界自动轮询，也不推断任务失败或已停止。新的取消API响应必须被客户端解析，不能继续Promise<void>并清掉run_id。任务owner另有持久取消/对账扫描：即使业务已cancelled，也持续处理cancel_delivery_state未完成的记录，在有界预算内重试同一精确取消请求或查询原invocation；不依赖当前只负责通知的事件消费者，超预算进入可审计待处理状态。
+
+**测试**：提交后断响应、重复启动、Runner 重启、旧 attempt 取消不杀新 attempt、kill失败、完成取消竞争、旧结果发布拒绝；真实hook/浏览器逐行验证上述状态和操作限制，观察abort不能写业务cancelled。保留 Runner result-v1/settle-policy、runner_auth 与真实 typed PI 用例。
+
+**完成/回退**：只扩展既有 HTTP 边界，不上新 RPC。先部署兼容 Runner，再客户端，再开放新能力；保留回执与 attempt 目录直到对账完成，未知状态不得清理。MinerU 复用相同生命周期原则，但不假设其接口已支持查询/取消。
+
+### U10. 持久事件先于推送与跨实例 SSE 恢复
+
+**需求/依赖**：R8，AE6；依赖 U8，取消场景等 U9。owner：taskrun/stream；mutex：taskrun event写入、server task SSE、web taskRuns。
+
+**文件**：`internal/taskrun/manager.go`、`store.go`、`internal/server/task_run_handlers.go`、`web/src/api/taskRuns.ts`；新增 `internal/taskrun/event_replay_pg_test.go`、`internal/server/task_run_slow_observer_test.go`，扩展 taskRuns.test。
+
+**设计**：可靠事件先落库再推，seq 在同一执行所有权下分配；落库失败不发送可恢复游标。慢订阅者满队列必须断开恢复或显式 gap/resync，不能默默漏掉且继续推进 cursor。跨 server 实例观察通过同一 PG 事件源有限补读，可用通知优化但不能只依赖内存 fanout。终态后以持久 snapshot 收敛。
+
+SSE 每次连接和持续观察按项目/session/run授权；401/403/404、撤权等永久拒绝停止自动重连。断线只停止观察，不取消后台任务。
+
+**测试**：保留 PersistenceAndReplayAfterRestart、DisconnectDoesNotCancelWorker、SubscribeUnsubscribeRace；加落库失败无推送、队列32容量以上慢观察、跨实例继续观察、cursor中断无缺口、权限撤销和终态补读。真实浏览器重连不能用 handler mock 代替。
+
+**完成/回退**：不引入新 broker，保持 after_seq/replay_only wire 兼容。旧客户端可读取持久 snapshot；必要新字段只 additive。回退不得恢复已知“推了但没持久化”的成功承诺。
+
+### U11. 表写者回归与跨 owner 事务
+
+**需求/依赖**：R3/R9；U11a/b依赖U5，U11c依赖U8/U9。owner：各表 owner，app 负责事务；mutex：docgov/docrevision/docduty/authz/projectinstance/taskrun，按以下三片串行。
+
+**文件/子切片**：
+
+1. U11a 职责：`internal/docduty/store.go`、`revoke.go`、`internal/docgov/repository.go`、`internal/authz/authorizer.go`、server/project_members_handlers、bizdev/service 的 heal 调用。docduty 保留纯选择/撤销规则，document_records SQL 归 docgov。
+2. U11b 根指针：`internal/docrevision/pg_store.go`、docgov/repository、freedoc owner；app adapter 按文档种类选择同 scope 的 ProjectHead，补 revision_schema_version/row_revision 等原语义。
+3. U11c 终止：`internal/projectinstance/store.go` 的跨表终止上移 app 用例；projectworkflow 持 projects 写权，taskrun 提供 scope-aware 终态操作。不能调用当前总是新 Within 的 Cancel，也不能把 repository M3 stub 当现成能力。
+
+**数据语义**：成员变更与职责撤销同事务，冻结职责不重算；heal 迁出 GET 前提供成员写入/显式修复入口，防止旧项目永远缺职责。终止将实例、project生命周期、本地run业务终态、旧发布权撤销以及消息/收据/取消意图/outbox同事务收口；commit后通知进程取消。依U9双维契约，业务cancelled不等于远端已停止，取消意图须持久重试/对账，远端停止结果独立更新。所有错误传播，不忽略task_runs UPDATE失败，也不在事务内等待远端kill。
+
+**测试**：扩展 docduty/store_pg_test、duty_locked_pg_test、authz/authorizer_pg_test、docflow/e0a_pg_test、projectinstance/terminate_test、taskrun/finalize_pg_test；新增 `internal/app/projectflow/terminate_pg_test.go`。验证 owner 失败全部回滚、heal/撤权竞争、controlled/freeform 指针与账本一致、终止/finalize竞争只有合法终态。
+
+**完成/回退**：5 条 SQL 例外逐条随代码删除；同时登记 projects 等扫描遗漏的关联写者。已提交终止不能通过程序 revert 复活；保留兼容读与恢复手册。
+
+### U12. 权威正文、工作区能力与文件 IO 边界
+
+**需求/依赖**：R9/R11，AE7；依赖 U5/U9。owner：docquery/workspace/storage；mutex：文件路径表所列包，分读取→诊断修复→写入三个切片。
+
+**文件**：`internal/docquery/service.go`、`internal/workspace/capability.go`、`lease.go`、`resolver.go`、`internal/docrevision/projection.go`、`reconcile.go`，以及下方16条 path登记。复用 WorkspaceRef，不新增另一套文件门面。
+
+**设计**：server 通过已授权 docflow.Query/docquery 读账本，删除直接文件兜底；缺账本按现有安全错误返回，不在 GET bootstrap。workspace 只接由 doc/task owner 解析出的可信逻辑引用，读前验证项目/任务权限。现有进程内 LeaseTable 只作本机校验，跨进程发布接 U8 的持久 epoch 与 U9 的 attempt目录。
+
+文件准备在 UoW 外、immutable bytes/digest 已稳定后再提交 DB 引用；投影在 commit 后执行，可重建且不当权威源。共享存储布局/旧 work_dir 不批量搬迁，compatibility resolver 限定既有合法路径。显式注入 DataDir，生产缺失拒绝写入，不默认为 data/dev。
+
+**测试**：复用 docquery 的 GetIsReadOnly/GetDriftStillServesLedger、workspace 的 symlink/坏key/UoW内IO、docrevision reconcile备份/hard-break测试；新增 `internal/workspace/publication_fencing_pg_test.go` 与 `internal/server/document_query_parity_pg_test.go`。覆盖错scope读、旧attempt发布、投影删除、存储失败、先备份后修复且原文件保留。
+
+**完成/回退**：路径例外逐条语义消除，不改 Runner 约定文件名、不改 admin URL。对象已生成但DB未提交时登记孤儿回收条件，本轮不自动删除；不启用 FAV 替代现有账本。
+
+### U13. server/chat/coordinator 的窄端口与装配收口
+
+**需求/依赖**：R1/R9/R11；依赖对应领域 U5/U7/U11/U12。owner：app；mutex：app/app.go、server、chat、coordinator、stageflow，按切片单写者。
+
+**文件/顺序**：先 U5 的 chat action adapter；再 `internal/app/stageflow/types.go` 去 bizdev 类型 alias；再 `internal/app/chatflow/ports.go`、`assembler.go`、chat/session、coordinator/context 定义独立读取 DTO；再 server/server.go 将 Runtime 回填、executor 初始化移回 app；最后分功能注入 Dependencies，迁移 coordinator 的 ctxmgr/kb 具体依赖。
+
+使用已有 KB Hub/ctxmgr 授权读取，不构造第二客户端；区分必需知识失败与允许的降级，不把私有聊天写进共享 KB。bizdev Snapshot 仅作为过渡 construction adapter，不能让 handler 借它访问所有实现。热点文件按已稳定用例拆分，不与语义变化混成同批。
+
+**测试**：stageflow/usecase_test、chat/action_executor_test、chatflow/chatlog_test、ctxmgr/chat_memory_test::TestSearchChatMemory_PrivacyGate、KB client、现有 server 路由特征；新增 `internal/app/composition_contract_test.go`。替换假端口可独立测试，公开 DTO 不带具体领域/PG 类型；用户/session/project 隔离不变。
+
+**完成/回退**：chat 不再 import app 实现，server 不持 pool/整个 Runtime；组合根仍允许具体依赖。逐功能域删除边而非一次改全包；保留适配器作兼容回退，不恢复绕过用例的调用。
+
+### U14. 工作流定义、实例与执行的单向边界
+
+**需求/依赖**：R9/R11；依赖 U11/U13。owner：workflow-def；mutex：workflowdef/projectinstance/workflow/runtime/app catalog。
+
+**文件**：`internal/workflowdef/catalog.go`、`validator_v2.go`、`internal/projectinstance/service.go`、`internal/workflow/runtime/orchestrator.go`；新增 `internal/app/workflow_catalog_adapter.go` 和 `workflow_contract_test.go`。
+
+**设计**：VersionResolver 返回稳定发布视图；FrozenTaskReader 读取已激活实例的冻结 executor/template/duty。旧目录/UI flatten 兼容放 app adapter，不进入真实执行。validator 通过注入的 executor/gate key 校验能力，避免反向 import 整个 workflow 实现。
+
+**测试**：catalog_policy、validator、keyspace、rdev_completeness、runtime/orchestrator、projectinstance/hash/live_plan/duty_reassign；新增“定义升级后旧实例执行完全不变”“旧目录flatten不影响执行”“缺冻结职责fail closed”。
+
+**完成/回退**：不重写历史 JSON/plan_hash，不重算 config_snapshot；只收窄类型和依赖方向。缺兼容适配器时不切换 catalog/runtime，不拿当前定义补历史缺项。
+
+### U15. 前端统一 transport 与功能状态 owner
+
+**需求/依赖**：R8/R11；transport设计可早于后端，完整验收依赖 U9/U10。owner：web；mutex：web API公共层与 App，三片交付。
+
+**文件/子切片**：U15a 新增 `web/src/api/transport.ts`、`transport.test.ts`，迁移 authHeaders/errorEnvelope 公共语义；U15b 调整 App、useSendMessage、useTaskRunAttempts/useTaskRunStream；U15c 统一 useChatWindow/loadOlder/loadDay/anchor、useAuthenticatedWorkspaceSync、useRecoveredTaskPhases 的作用域 generation。
+
+**设计**：U9的状态—操作表和最小取消/unknown UI随W2先交付，本单元保留该协议再拆广泛状态owner。transport 只负责身份快照、AbortSignal/deadline、安全错误与只读有限重试；SSE/upload保持专用适配。写动作没有稳定幂等键不自动重试。conversation、task execution、document projection 各有状态 owner，通过命令/查询/事件连接，避免跨域任意 setter。useSyncExternalStore snapshot 必须有可观察的新身份/版本，不能原地变更同一对象。
+
+切项目/注销只停止观察并拒绝旧响应；显式停止才发取消，失败保留 run_id 可查询。401/403/404 分类与后端一致；保持 DOC_BUSY、PLAN_FROZEN、内容投影错误的既有用户表达。
+
+**测试**：新增 `web/src/hooks/useTaskRunStream.test.ts`、`useTaskRunScope.test.tsx`，并明确纳入 package.json 的测试选择（现有脚本不自动覆盖所有新 tsx）；保留实际任务回放与阶段快照测试。真实 hook 验证身份切换、旧SSE晚到、snapshot重渲染、取消失败/完成竞争；源码字符串检查不能替代。最终浏览器走发起→切项目→返回→刷新→取消/恢复。
+
+**完成/回退**：各域API路径/DTO不改，适配分组迁移；必要时按组回退，不能恢复跨用户缓存或吞取消失败行为。
+
+### U16. 架构门禁、例外收口与模块契约发布
+
+**需求/依赖**：R9/R12；检测器可从 U1 开始，收紧依赖对应 U11–U15 结果。owner：architecture/各领域 owner；mutex：archtest、module-boundaries、契约文档。
+
+**文件**：`internal/archtest/scan.go` 及测试、`scripts/arch-check.sh`、`.doc/system-design/module-boundaries.yaml`，U1 模块契约登记；按声明变化增量更新 FEATURE-MATRIX，发布 blocker 仅按新证据处理。
+
+**设计**：扩大到 cmd/前端适用边界，检查实现类型别名和禁止依赖；SQL扫描覆盖所有实际业务写表，明确动态SQL盲区。按能力声明选择测试，N/A和SKIP分开。表owner机器检查是L1，不能宣称数据库ACL已隔离；DB role强化若涉及共享UoW，单独评估，不为凑门禁破坏原子性。
+
+修正 URL 字符串误报，保留真实越界文件路径/动态SQL负例。sql_write/path 例外逐项注销并收紧，import/event 零新增底线保留。必要公共词汇包只能容纳无行为值，不搬解析/hash/path函数。
+
+**测试**：刻意跨领域import、类型alias泄漏、越权表写、URL合法/路径非法、新事件类别、未知schema、过期例外均有正负例；检测器不支持的部分标明。registry/YAML parity还需真实producer/consumer契约测试补足。
+
+**完成/回退**：标准状态与 enforced 分开；旧A–G例外计数按实数更新，不直接将文件归零冒充规范达标。回退代码与必要例外成对，过期例外必须新审批理由，不静默延期。
+
+### U17. 兼容迁移、积压恢复与真实端到端验收
+
+**需求/依赖**：R12，AE8；贯穿每批，最终依赖全部适用 U。owner：集成/验证；mutex：目标环境与 dev集成串行。
+
+**文件**：扩展 `internal/events/cutover.go` 的只读分页inventory与测试；新增 `.doc/ops/2026-09-22-modular-refactor-rollout.md`；每批在 test-reports 生成真实报告；新增 `web/e2e/modular-command-parity.spec.ts`、`task-run-recovery.spec.ts` 及其测试入口。
+
+**设计**：inventory 覆盖 pending/leased/dead/quarantined，读取新校验必要的 producer/payload/scope但只输出脱敏ID/摘要/错误码/预期状态/token/attempt。manifest绑定环境、源码版本和事件集合；任何恢复应用前重新检查原值。现有 ApplyReplay 是纯校验且 dryRun参与digest，不是可用批量执行器，本轮不据此直接重放存量。
+
+正常 pending 在新规则下继续交付不称 replay；已dead/quarantine保留，单项恢复须独立审计与授权。若确需批量修复，先另立恢复工具切片（持久具体ID、apply状态、不可变审计），不以手工SQL捷径完成。
+
+**测试/完成**：按下方 Verification Contract 跑真实PG、多进程、PI、浏览器、restart和跨用户负例。每批保持版本/制品/环境固定，记录原mode/lease/积压→兼容升级→排空→切换→观察→恢复边界。仅通过的切片可记done，未覆盖的语义/运维能力继续保留任务。
+
+---
+
+## Data and Exception Migration
+
+### Migration Decisions
+
+| 单元 | 计划数据变更 | 保留/兼容条件 |
+|---|---|---|
+| U2 | 新增 chat_event_notice_receipts（ctxmgr owner，拟定名） | source_event/effect/recipient 唯一；同事务保存 session/message 或明确no-op；旧消息不靠正文猜收据 |
+| U3/U4 | 校验与claim逻辑优先复用现有表 | 不新增event_seq，不取消现有aggregate唯一约束，不改历史payload/digest；必要索引须经隔离数据EXPLAIN后决定 |
+| U5 | 新增 document_command_receipts（docgov owner，拟定名） | 治理命令请求摘要、decision/revision/result；内容修订继续复用document_change_events |
+| U7 | task_runs additive 请求schema/摘要/输入引用/受理状态字段 | 旧run字段为空表示legacy，不猜造请求；先兼容reader再切writer |
+| U8 | task_runs additive执行epoch及必要条件索引 | 旧记录从明确初值迁移；新旧writer切换需排空，不能无条件混跑 |
+| U9 | Runner执行收据/不可变结果的持久命名空间 | 与run/step/attempt绑定；回执只含必要字段；正文留受控产物，秘密不入回执 |
+| U10 | 优先复用task_run_events和phase snapshot | 必要事件类型/序列约束调整单独认领migration，旧cursor与结果协议兼容 |
+| U11/U12 | 原则上改写者/适配器，不重写业务正文/账本 | 保留row_revision、revision_schema_version、冻结hash和Markdown硬换行 |
+| U17 | 当前只读manifest与受控单项处置 | 现有replay表不足以证明批量恢复；不自动修改历史receipt/checkpoint |
+
+所有迁移使用新增 Goose 文件，禁止编辑已发布 migration。数据库表/列/索引变更与应用兼容窗口同一工作包审查；迁移号在开工时登记，由单写者串行分配。旧输入分类不通过批量改hash/字段伪造成新格式；schema版本是数据库实际应用结果，不从历史文档抄写。
+
+### SQL Ownership Backlog
+
+| 当前例外 | 目标owner/事务入口 | 单元 |
+|---|---|---|
+| docduty/revoke.go → document_records | docgov.Repository 精确槽位撤销，成员变化同UoW | U11a |
+| docduty/store.go → document_records | docgov职责读写，docduty只产出heal计划 | U11a |
+| docrevision/pg_store.go → document_records | docgov受控根指针投影 | U11b |
+| docrevision/pg_store.go → freeform_documents | freedoc自由文档根指针投影 | U11b |
+| projectinstance/store.go → task_runs | taskrun scope-aware finalizer，app终止用例编排 | U11c |
+| 当前未登记的 projectinstance→projects | projectworkflow生命周期owner，同一终止事务 | U11c/U16 |
+
+前四条例外到期 2026-09-28，task_runs 例外到期 2026-10-26。projects 是本轮发现的登记缺口，不能通过“5条归零”漏掉。现有宽sql scanner未发现不等于无其他跨表写，U1/U16补完整清单。
+
+### Path Backlog
+
+| ID | 现有文件（internal/前缀省略） | 处理与验收 | 到期 |
+|---|---|---|---|
+| P1 | agent/cursor.go：output.md | artifact契约/兼容wire，不随意改Runner文件名 | 10-12 |
+| P2 | agent/piagent.go：output.md | 同上，typed结果与真实Runner保持一致 | 10-12 |
+| P3 | bizdev/service.go：data/dev | 明确注入DataDir，缺值拒绝生产写 | 10-12 |
+| P4 | bizdev/service.go：output.md | 账本/能力读取，删除多目录猜测 | 10-12 |
+| P5 | coordinator/context.go：output.md | ArtifactSummary/ContextReader端口 | 10-12 |
+| P6 | coordinator/dialogue_llm.go：data/dev | 实际默认值，非仅示例；注入受控执行目录 | 10-12 |
+| P7 | coordinator/document_summary.go：data/dev | 同上 | 10-12 |
+| P8 | coordinator/engine.go：output.md | 任务结果返回逻辑产物引用 | 10-12 |
+| P9 | docgov/lease.go：output.md | DB提交后由workspace写投影，失败可恢复 | 10-12 |
+| P10 | docgov/project_docs.go：output.md | 列表/正文走账本；修复为显式命令 | 10-12 |
+| P11 | docrevision/projection.go：output.md | 注入ProjectionReader，保留分类 | 09-28 |
+| P12 | docrevision/reconcile.go：output.md | 备份与读取能力；保留dry-run/原文件 | 10-12 |
+| P13 | server/document_revision_access.go：output.md | 通过授权Query，不自行读物理文件 | 09-28 |
+| P14 | server/document_revision_handlers.go：output.md | 错误提示改安全文案，非物理写入迁移 | 09-28 |
+| P15 | server/server.go：workspaces/ | 实为admin/workspaces/reconcile URL；修扫描误报，路由不改 | 10-12 |
+| P16 | storage/cas.go：data/dev | 真实默认根，组合根显式注入 | 10-12 |
+
+年份均为2026。按当前YAML实数：09-28到期为4 SQL + 3 path，10-12为13 path，10-26为1 SQL。原A–G“2条U4/14条U5”的分组已过时。P15经正负例证明误报后可以注销，但不得宣称由此完成一个真实运行隔离缺口。
+
+到期日前不能完成：责任owner给出范围、原因、截止和退出条件，单独审核延期；本方案不修改expires，不自动为所有17单元延期。优先级按安全/正确性决定，不能为了赶过期例外跳过W1。
+
+---
+
+## Verification Contract
+
+### Evidence Layers
+
+| 层级 | 适用单元 | 必须证明 |
+|---|---|---|
+| L-A 静态/单测 | 所有代码单元 | 窄接口、依赖、纯规则与错误映射；不能代表PG/运行态 |
+| L-B 真PG | U2–U8/U10–U12 | 原子提交/回滚、跨owner写入、幂等、真实并发与租约 |
+| L-C 独立多进程/故障注入 | U4/U6/U8–U10/U12 | 抢占、失租复活、kill/restart、丢响应/ack、资源耗尽与恢复 |
+| L-D 真实PI/解析适配 | U5/U7–U9/U12–U15 | 批准动作/任务/产物使用实际Runner和批准模型，stub不计 |
+| L-E 真实浏览器 | U5/U7/U9/U10/U12/U14/U15 | 可见操作、刷新/重登/切scope/重启后的持久结果及跨用户拒绝 |
+| L-F 运维兼容 | 每个涉及schema/协议/worker的切片 | 新旧版本支持矩阵、排空、存量分类、恢复与回退证据 |
+
+工程命令遵循[验证契约](../ops/2026-09-21-validation-contract.md)：
+
+- Go改动：`./scripts/arch-check.sh --mode block`、`go vet ./...`、`go test -short ./...`，另跑单元列出的独立PG/鉴权负例。short中SKIP不能算PG通过。
+- Web改动：`npm test`、`npm run build`；真实hook和新增tsx测试显式进入选择列表，另跑受影响Playwright。
+- 产品PI：nightly现有两项仅为 TestMultiIntentU8_RealPI_ConfirmGenerate_PG、TestWorkflowGovernance_PiAgent_PG_FullNoneMixedChain；按改动追加三工作流/批准入口/Runner恢复精确用例。不能用“nightly绿”代替全部本方案场景。
+- 环境预检：独立TEST_DATABASE_URL不得指向共享dev；PI预检端口/模型固定条件按当前测试源码核验。真实目标模型由已批准配置决定，本计划不指定替换模型。测试基础设施不满足时记录infra_fail，不放宽断言/权限。
+- shared dev真实验收必须占完整环境执行租约并固定制品；从主运行入口构建部署。部署后核对源码SHA/镜像摘要、挂载、schema、health/ready和业务结果，不用restart当新代码证明。
+
+### Required End-to-End Matrix
+
+| 链路 | 正例 | 负例/恢复 | 独立证据 |
+|---|---|---|---|
+| 文档批准 | 页面与真实对话同动作→治理/审计/outbox→通知/推进 | actor缺失、无精确职责、跨项目、撤权；commit失败原实例缓存不变 | PG + PI/对话 +浏览器 |
+| 文档生成 | 合法任务→Runner→候选/账本/根指针→刷新 | 重复请求、旧版本冲突、workspace丢投影、文件准备后DB失败 | 真Runner + PG +浏览器 |
+| 通知/shadow | 同event仅一次站内及聊天效果 | rollback、无会话、会话变更、重投、shadow零业务写 | PG副作用所有表与缓存 |
+| 事件交付 | v42/v47、多worker、独立consumer | poison/backoff/过期lease/晚到版本、错scope | 独立PG/多进程 |
+| 任务受理 | HTTP/Agent同键同动作只有一个run | 同键异参数、claim后退出、消息绑定失败、legacy输入缺失 | PG/restart |
+| 执行/取消 | 幂等invocation、精确cancel、实际终态 | 响应丢失、旧worker复活、旧attempt kill、完成竞争 | Runner进程 + PG +UI |
+| SSE/前端 | 持久cursor、重连、跨实例观察 | DB落库失败、慢连接、401/403、切用户/项目、旧回调晚到 | 后端真实事件源 +hook +浏览器 |
+| 工作流/成员 | 冻结职责/计划、成员变更、终止 | 发布定义更新不改旧实例；撤权与heal/终态竞争 | PG +现有正式工作流 |
+| 运维 | 兼容升级、停领排空、小批恢复 | 新旧writer不兼容拒绝、inventory后状态改变、未知结果不清理 | 精确制品及操作收据 |
+
+浏览器新增链路优先扩展 `web/e2e/document-revision-runtime.spec.ts`、`controlled-document-reload.spec.ts`、`governance-action-level-authz.spec.ts`、`conversation-intent-dual-tab.spec.ts`；仅在已有场景无法表达时新增U17文件。产品数据使用专用测试项目，不能向真实用户会话发送探针。
+
+### Quantitative Acceptance
+
+正确性阈值先固定：双执行/跨租户泄漏/丢已确认提交/同效果重复均为0；同键100并发与2/4 worker竞争场景必须覆盖。资源与延迟预算由U1在固定环境采样后写入切片验收：非故障consumer的领取/完成延迟、正常负载p95/p99、连接占用、最老pending年龄。新配置不允许比已冻结预算差；调整预算要解释负载/资源变化，不能在失败后移动指标。
+
+不能为未知业务规模统一承诺“零延迟扩散”。U6必须给每consumer独立预算并验证故障注入下仍达标；未填写具体预算不能结束该单元。规范N/A仅表示没有该能力，不能把缺测试/缺基础设施记N/A。
+
+---
+
+## Rollout and Recovery
+
+### Compatibility Sequence
+
+1. **只读盘点与隔离复现**：确认实际制品、数据库迁移、consumer modes、活跃lease/运行任务和积压；保存脱敏manifest。此阶段不启用现有shared shadow。
+2. **兼容准备**：additive schema、producer完整字段、legacy reader、U2原子副作用先到位；新校验先用只读验证/离线fixtures验证兼容集合。
+3. **写入口切换**：文档/任务用例按功能切换，旧入口通过适配器进入同用例；观察授权/幂等/事务失败，禁止旧hook+新event双写。
+4. **执行协议切换**：涉及U4/U8时停止新领取/受理并排空，确认旧worker退出；off只停止领取，不等于取消正在执行的handler。随后替换全部参与竞争的writer，恢复受控小批量工作。
+5. **观察与积压处理**：先确认新请求正确，再有限消化普通pending；dead/quarantine不自动释放。切off意味着积压暂停，生产旧hook不会自动兜底。
+6. **前端与门禁收紧**：兼容后端能力后迁移功能状态，逐条删例外；最后contract旧路径/协议。每阶段只交付已验证切片。
+
+### Rollback Matrix
+
+| 变更 | 可回退范围 | 禁止 |
+|---|---|---|
+| 纯接口/装配适配器 | 保留旧wire的新实现内部回退 | 回到已确认的授权旁路 |
+| strict事件校验 | 回到经过验证的兼容reader/writer | 修改历史payload/digest，自动释放隔离项 |
+| aggregate领取/执行epoch | 停领/排空后退到最近兼容部署；优先前滚 | 不同锁/epoch协议worker混跑 |
+| additive表/字段 | 保留schema和收据，旧兼容读 | down migration删除恢复所需状态 |
+| Runner新执行协议 | 先结束/对账在途invocation，再关新能力 | 未知执行重新启动、只按workspace误杀 |
+| 前端状态拆分 | 按功能组回到兼容transport | 丢失run身份或忽略取消失败 |
+| workspace投影 | 重建可清理投影，保持账本权威 | 从旧output覆盖账本、删唯一原始文件 |
+| 已提交批准/终止/通知 | 走业务补偿或人工恢复命令 | 用Git revert假装撤销已发生业务 |
+
+本方案不批准任何存量数据修复/恢复apply。实施者先提交具体事件/资源集合、原值/预期值、影响、审批依据、恢复步骤与验证收据；现有工具能力不足时先补受限工具及负例，不能直接SQL改状态。
+
+---
+
+## Coordination and Prior Plans
+
+### Write Claims and Parallelism
+
+| 共享面 | 排程规则 |
+|---|---|
+| app/app.go | U5/U7/U13/U14的装配变更由当期集成者单写者提交，其他切片先提供适配器/测试 |
+| events/worker/dispatcher/registry | U2–U4语义冻结后才做U6并发，不同时横向重排 |
+| taskrun manager/store/finalize | U7→U8→U9/U10；与U11c终止owner收口协调 |
+| docgov/docrevision | U5状态/授权稳定后迁U11写权，再U12文件边界 |
+| module-boundaries.yaml | 统一认领；只收紧实际完成的边，例外注销附证据 |
+| migrations | 单写者分配号；兼容准备、回填、约束收紧按独立回退价值拆批 |
+| web App/public transport | API契约冻结后先transport，再状态域；不与业务UX扩面混写 |
+| dev与shared环境 | 精确候选验证后受控集成；部署与长E2E串行持锁 |
+
+代码和隔离测试可在不同模块工作区并行；是否并行取决于实际写路径及语义依赖，不凭计划里的owner名称不同放行。
+
+### Existing Work Mapping
+
+| 原计划 | 本方案对应 | 关系 |
+|---|---|---|
+| 通用平台U1–U8 | 作为MCS参考实现未来线 | 不在本项目重复建设SDK/框架 |
+| 当前项目CP1 | U3/U4 | 补契约兼容、同聚合竞争与存量准入 |
+| CP2 | U5 | 补完整授权、缓存/DB回滚和新批准事实身份 |
+| CP3 | U3 | 覆盖taskrun/intent实际producer，避免strict误伤 |
+| CP4 | U2/U6 | 先修事务逃逸，再做shadow/资源隔离 |
+| A/B/C | U5/U13 | 先行为后依赖，词汇拆分与用例边界同步 |
+| D | U14 | 保持冻结定义与旧catalog兼容 |
+| E | U13末尾 | 稳定行为后的文件拆分，不独立算解耦完成 |
+| F | U10/U15 | 扩充持久SSE、scope和实际hook验收 |
+| G | U11/U12/U16 | 5 SQL+16 path语义核销，并补漏登记 |
+| 既有多意图/摘要/FAV/自举方案 | 原授权范围继续 | 不借本方案放量，不关闭原未完成任务 |
+
+本文细化并整合当前项目的实施顺序；旧A–G/CP编号和历史证据保留，不删原文、不追认未实施批次。实施任务引用“本文件U-ID + 原批次ID”避免两套同模块重构并行启动。
+
+### Document Impact
+
+本次只新增本方案、更新原主任务和通用采用计划的当前项目指针、CURRENT自己的续办行。实施时按实际行为变化更新：模块开发标准/模块契约卡、事件checkpoint ADR补充算法、Runner协议说明、错误/SSE契约、module-boundaries、相关测试报告。FEATURE-MATRIX仅改受影响声明；gap-matrix须确认新证据对发布门禁的实际影响后处理，不因本次规划统一降级/升级。
+
+---
+
+## Definition of Done
+
+**本次方案交付完成**：22条MCS有本系统落点，新增源码发现有证据，17单元有依赖/owner/文件/测试/回退，旧计划有对应，存量和真实验收边界明确；完成文档审阅与链接/路径/ID检查。不要求本轮运行产品测试或实施代码。
+
+**一个实施单元完成**：其公开契约、正负例、适用PG/多进程/PI/UI证据通过；代码/候选SHA与运行制品一致；声明按实际更新。缺失、SKIP或只跑mock不能标其完整完成。
+
+**本系统整改完成**：所有适用单元通过；真实SQL写权与文件责任明确；同动作入口一致；旧worker写拒绝与unknown恢复可证；前端跨scope不污染；必要依赖清晰且无新增未经批准越界；全部例外有核销或明确未完成状态。单纯“21条例外清零”不满足总完成条件。
+
+### Implementation Prerequisites and Deferred Choices
+
+- 第一批可按 U1/U2 开始准备；具体实施仍需用户授权。owner、独立测试环境、已批准模型和部署窗口在对应任务启动时记录。
+- 容量/SLO数值、实际积压数量、当前consumer模式和制品身份属于实施前运行事实，本轮不猜测；缺失时阻止放量，不阻止无运行副作用的设计工作。
+- 迁移号、精确索引与批量大小由实际 schema/EXPLAIN 和数据规模决定；不能为完整方案虚构线上性能数字。
+- 批量replay工具、全模块进程拆分、数据库按模块独立部署、通用多语言SDK、FAV/D7/全多意图放量均另立项目，不作为本轮已承诺交付。
+
+建议审核与实施顺序：先 W0/W1 的正确性与风险边界，再 W2 的任务恢复协议；通过真实链路后推进 W3/W4 结构重构。每批可独立停下，不做一次性“大重写”。
+
+## Sources
+
+- [MCS通用规范](../system-design/2026-09-22-generic-module-contract-standard.md)、[现状审查](../audit/2026-09-22-module-decoupling-current-state.md)。
+- [模块化单体ADR](../adr/2026-09-14-modular-monolith-decoupling.md)、[首事件bootstrap ADR](../adr/2026-09-15-event-consumer-checkpoint.md)。
+- [现行模块开发标准](../system-design/2026-09-20-module-development-standards.md)、[原A–G计划](./2026-09-20-module-decoupling-batch-plan.md)。
+- [验证契约](../ops/2026-09-21-validation-contract.md)、[worktree操作规范](../ops/2026-09-21-agent-worktree-workflow.md)、[功能矩阵](../status/FEATURE-MATRIX.md)、[发布门禁](./gap-matrix.md)。
+- 当前源码锚点与具体测试入口见 Evidence、各U单元和 Verification Contract。历史报告只用于定位已有设计与覆盖，不作为本轮重新执行结果。

.doc/remediation/2026-09-22-modular-platform-adoption-plan.md

@@ -349,6 +349,8 @@ runbooks/
 
 ## Current Project Adoption
 
+当前项目的逐单元设计、迁移和验收已细化为[系统整改与重构方案](./2026-09-22-agent-system-modular-refactor-plan.md)（待审核）。下方 CP1–CP6 保留为原始映射索引；通用平台 U1–U8 仍是独立平台线，不作为本项目重复建设前置。
+
 这部分是当前项目的映射附录，不属于跨项目通用标准。保持既有模块化单体 ADR，后续如拆进程另提 ADR 和授权。
 
 | 顺序 | 目标与现有路径 | 建议新增/扩展验证 | 关联 |