merge: candidate module-batches-ag-status-fix into local_dev

This commit is contained in:
weichen
2026-09-23 15:09:12 +00:00
8 changed files with 182 additions and 10 deletions
@@ -0,0 +1,55 @@
---
issue_id: ISSUE-20260923-matrix-status-regression
issue_state: resolved
severity: high
owner: Cursor
task_ids: [module-batches-ag-status-fix-2026-09-23]
created: 2026-09-23
occurred_at: 2026-09-23
updated: 2026-09-23
recurrence_count: 0
evidence_basis: current
lesson_ids: [LESSON-20260923-matrix-status-cas]
---
# FEATURE-MATRIX 状态字段被合并冲突回退
按 [闭环规范](../ops/2026-09-23-issue-learning-workflow.md) 维护。关联任务:[module-batches-ag-status-fix](../ops/short-term/2026-09-23-module-batches-ag-status-fix.md)。
## 事实与证据
- **预期**:`module-batches-ag` 在 A–G 合入且 arch-check 全 0 后保持 `done`(提交 `77bdbdbc` 已写入)。
- **实际**:本地 `dev` tip 上该行状态为 `planned`,剩余工作栏仍写「关闭本伞行」与 A–G 已合入事实矛盾;用户观感为「多次要求实现但未实现」。
- **触发**:含 FEATURE-MATRIX 的 closeout / sync 合并冲突手解,取了无 `record_id` 或旧侧行内容。
- **影响**:后续会话按 `planned` 错误前提规划,可能重复实施或延误收口;不构成发布 blocker(发布关系仍为 `non_blocker`)。
- **环境**:本机 `dev` @ `18b9556f`(任务基线);修复提交见本任务 feature 分支。
- **复现(修复前)**:`git show 77bdbdbc:.doc/status/FEATURE-MATRIX.md` 该行 status=`done`;修复前 tip 同行为 `planned`。
## 根因与同类范围
- **已证实**:共享文档在 `docs apply` 行级 CAS / `record_id` 稳定键启用前窗口内,merge 冲突对手解无机器核验状态字段;手解取旧侧覆盖 `done`。
- **已排除**:A–G 代码未合入(合入 merge commits 与 arch-check PASS 否定)。
- **共用机制**:CURRENT / FEATURE-MATRIX 等协调 SSOT;任何绕过 `docs apply` 的整表手改或冲突取旧侧。
- **同类入口**:其他矩阵行、CURRENT 认领行在无 CAS 收据时同样脆弱;本轮只修 `module-batches-ag`,不扩大扫全表 unless 另授权。
## 修复思路与过程
| 日期 | 假设 / 尝试 / 动作 | 实际结果与证据 | 决策 / 下一步 / owner |
|---|---|---|---|
| 2026-09-23 | 只读考古 git + arch-check | A–G 已落地;状态回退成立 | 按计划修正登记,不重做代码 / Cursor |
| 2026-09-23 | docs apply 行级 CAS 恢复 `done` + 登记 lesson | MATRIX 行 status=`done`;header 同步;arch-check PASS | resolved;合入 local_dev / Cursor |
方案:恢复矩阵事实状态;登记问题与经验;强制后续矩阵变更走 `docs apply`;合入含 MATRIX 的合并后机器核对目标 `record_id` 状态列。
## 验收与关闭
- 原例:PASS — MATRIX `module-batches-ag` status=`done`(docs apply 收据 + commit `b9d09c97`)。
- 同类:本任务不批量改其他行;风险已记入 lesson。
- 正常:PASS — `docs apply` 无拒绝;`./scripts/arch-check.sh --mode block` PASS(worktree tip)。
- deployment:`not_required`(纯文档)。
- resolved:2026-09-23;范围=状态登记与台账,不含 Server 镜像字段增量。
## 经验与复发
- lesson:[LESSON-20260923-matrix-status-cas](../ops/lessons/2026-09-23-matrix-status-cas.md)
- 防护:能力完成升 `done` 已有 `docs:approve` + evidence `cat-file` 门禁;复发时重开本 issue 并检查是否绕过 apply。
+1
View File
@@ -9,3 +9,4 @@
| ISSUE-20260923-nullable-duty | docgov / nullable / 23503 / reviewer_id | 可选职责空值写 0 导致 FK 失败 | high | resolved | Codex(历史补录) | 2026-09-17;历史 PG / API 冒烟;当前未复测 | [主记录](2026-09-23-historical-issue-records.md#nullable-duty) | [LESSON-20260923-nullable-duty](../ops/lessons/2026-09-23-nullable-duty.md) |
| ISSUE-20260923-content-hash | docrevision / canonicalize / hard-break / 404 | 规范化破坏 Markdown 语义并造成正文哈希漂移 | critical | resolved | Codex(历史补录) | 2026-09-14;历史真实 UI / 重启;当前未复测 | [主记录](2026-09-23-historical-issue-records.md#content-hash) | [LESSON-20260923-content-hash](../ops/lessons/2026-09-23-content-hash.md) |
| ISSUE-20260923-coordination-authority | agentctl / claim / SQLite / CAS / CURRENT / FEATURE-MATRIX | 本地副本 CAS 与任务许可不能表达跨主机全局权威认领 | high | investigating | Codex(研究) | 2026-09-23;源码/只读状态,未复现具体丢写 | [主记录](../ops/short-term/2026-09-23-coordination-db-daemon-research.md#issue-20260923-coordination-authority) | 沿用 content-hash 投影经验;跨机结论待实施验证 |
| ISSUE-20260923-matrix-status-regression | FEATURE-MATRIX / module-batches-ag / merge / docs-apply | 矩阵行 done 被 closeout 合并冲突手解回退为 planned | high | resolved | Cursor | 2026-09-23;本机 dev tip 与 git 考古;docs apply 已恢复 | [主记录](2026-09-23-matrix-status-regression.md) | [LESSON-20260923-matrix-status-cas](../ops/lessons/2026-09-23-matrix-status-cas.md) |
+2 -1
View File
@@ -19,8 +19,9 @@
| owner | task | branch | worktree | mutex | status |
|---|---|---|---|---|---|
| Cursor | closeout-claim-removed-2026-09-23 | feature/closeout-claim-removed-2026-09-23 | (removed) | git:dev+worktree-cleanup | done |
| Cursor | module-batches-ag-status-fix-2026-09-23 | feature/module-batches-ag-status-fix-2026-09-23 | .worktrees/module-batches-ag-status-fix-2026-09-23 | module-decoupling-spec | in_progress |
| Cursor | fav-constraint-current-2026-09-23 | feature/fav-constraint-current-2026-09-23 | (removed) | git:dev+docs | done |
| Cursor | closeout-worktree-cleanup-2026-09-23 | feature/closeout-worktree-cleanup-2026-09-23 | (removed) | git:dev+worktree-cleanup | done |
| Cursor | closeout-worktree-cleanup-2026-09-23 | feature/closeout-worktree-cleanup-2026-09-23 | .worktrees/closeout-worktree-cleanup-2026-09-23 | git:dev+worktree-cleanup | done |
| Cursor | remaining-worktrees-closeout-2026-09-23 | feature/remaining-worktrees-closeout-2026-09-23 | (removed) | git:dev+worktree-cleanup | done |
| Cursor | worktree-closeout-cleanup-2026-09-23 | feature/worktree-closeout-cleanup-2026-09-23 | .worktrees/worktree-closeout-cleanup-2026-09-23 | git:dev+worktree-cleanup | done |
| Cursor | worktree-closeout-batch-2026-09-23 | feature/worktree-closeout-batch-2026-09-23 | (removed) | git:dev+worktree-cleanup | done |
@@ -0,0 +1,30 @@
---
lesson_id: LESSON-20260923-matrix-status-cas
lesson_state: validated
owner: Cursor
reviewer: Cursor (source review + arch-check)
last_reviewed: 2026-09-23
reviewed_revision: b9d09c97120ee5bcdea487b0d0ca5910d6e98a1d
source_issues: [ISSUE-20260923-matrix-status-regression]
keywords: [FEATURE-MATRIX, docs-apply, record_id, merge-conflict, CAS, planned, done]
---
# 共享矩阵状态变更必须走 docs apply,合并后核验状态列
**触发**:改 FEATURE-MATRIX / CURRENT 行状态,或合并含这两份文件的候选时。
**机制与来源**:[ISSUE-20260923-matrix-status-regression](../../audit/2026-09-23-matrix-status-regression.md)。A–G 代码已合入且曾标 `done`,closeout 合并冲突手解取旧侧把状态盖回 `planned`,误导后续会话。
**开发检查**:
1. 不直接编辑 FEATURE-MATRIX / CURRENT 表行;用 `agentctl docs snapshot` + `docs apply`(MATRIX 键为 `record_id`)。
2. 升 `done` 须 `docs:approve` 与已提交 evidence 路径(门禁 `EVIDENCE_REQUIRED`)。
3. 合并含共享文档的候选后,对目标 `record_id` 再 `docs snapshot` 或 `grep` 核验状态列未被回退;冲突手解禁止静默取旧侧。
**验证方式**:本轮对 `module-batches-ag` 做 apply 收据 + `arch-check --mode block` PASS;未新增自动化 CI。manual。
**适用边界**:仅协调 SSOT(CURRENT / FEATURE-MATRIX);普通 `.doc` 短文仍可租约内直接改。不覆盖 gap-matrix 发布门禁语义。
**防护落实**:`scripts/agentctl.py` 已对 MATRIX `done` 要求 evidence;本条强调合并后人工/脚本核验。仍缺:merge 后自动断言关键 `record_id` 状态(待治理任务)。
**修订**:2026-09-23 新建;同日 apply 恢复 + arch-check 后升 validated。
+1
View File
@@ -6,5 +6,6 @@
|---|---|---|---|---|
| LESSON-20260923-nullable-duty | docgov、SQL、nullable、23503、可选职责、创建/heal | 检查所有写入口的缺席值语义;用真实 PG 验证 NULL/FK | validated | [可选职责持久化](2026-09-23-nullable-duty.md);2026-09-23 |
| LESSON-20260923-content-hash | docrevision、canonicalize、hash、bootstrap、hard-break、404、水合 | 保持文本语义并检查账本/文件一致性;新数据通过不能覆盖旧数据迁移 | validated | [正文规范化与投影](2026-09-23-content-hash.md);2026-09-23 |
| LESSON-20260923-matrix-status-cas | FEATURE-MATRIX、docs-apply、record_id、merge conflict、CAS | 矩阵/CURRENT 行变更走 docs apply;合并后核验状态列未被回退 | validated | [矩阵状态 CAS](2026-09-23-matrix-status-cas.md);2026-09-23 |
validated 的证据范围见各条目;本日复核为历史材料和源码阅读,未重跑产品回归。后续按机制补充,过时条目标 superseded/retired 并保留替代链接。
@@ -0,0 +1,84 @@
---
title: "module-batches-ag 状态回退修正与收口"
task_id: module-batches-ag-status-fix-2026-09-23
status: in_progress
created: 2026-09-23
updated: 2026-09-23
owner: Cursor
task_type: implementation
task_tier: small
policy_revision: "AGENTS+issue-learning+module-dev-standards @ 18b9556f3be4f2c5381673532ad71ec8a33e90f0"
branch: feature/module-batches-ag-status-fix-2026-09-23
worktree: .worktrees/module-batches-ag-status-fix-2026-09-23
base_dev_sha: "18b9556f3be4f2c5381673532ad71ec8a33e90f0"
write_scope:
- .doc/audit/
- .doc/ops/
- .doc/remediation/
- .doc/status/
allowed_environments: []
head_sha: "b9d09c97120ee5bcdea487b0d0ca5910d6e98a1d"
mutex: module-decoupling-spec
review_state: accepted
integration_state: pending
deployment: not_required
cleanup: pending
cleanup_owner: 独立维护者
cleanup_trigger: tip 为 local_dev 祖先且无进程后 remove
remote_sync: not_requested
---
# module-batches-ag 状态回退修正与收口
## 用户目标与授权
- 用户目标:检查解耦/总线/高可用/高并发是否按规范落地;按规范完善方案;对应 FEATURE-MATRIX `module-batches-ag`。
- 授权来源:用户确认计划「module-batches-ag 状态回退修正与收口」。
- 交付终点:MATRIX 行 `planned → done`;问题与经验登记;batch-plan 文档状态一致;合入 local_dev;不 push。
- 禁止:不重做 A–G 代码;不 push;不改 FAV live / production_ready / gap-matrix。
## 范围与非目标
- 允许:共享文档 CAS 修正、问题/经验台账、batch-plan frontmatter、验收复核证据。
- 非目标:Server 镜像字段增量收口(另立任务);重跑全量 Go/PI。
## 相关问题与经验
- issue:`ISSUE-20260923-matrix-status-regression`(resolved)
- 开工检索:`matrix|FEATURE-MATRIX|merge conflict|docs apply` → lessons INDEX 无命中;新建 lesson。
- 经验:`LESSON-20260923-matrix-status-cas`(validated)
## 调查结论(只读复核,本机 2026-09-23)
- A–G 合入证据:`server-assembly` / `chat-app-decouple` / `docgov-vocabulary` / `workflow-def-unidirect` / `engine-split` / `web-api-client` / `g1` / `g2-g3` merge commits 均在 `dev` 祖先链。
- `./scripts/arch-check.sh --mode block` PASS;`module-boundaries.yaml` `exceptions: []`,baseline 全 0。
- 巨型文件已拆(例:`coordinator/engine.go` 1844→344)。
- 提交 `77bdbdbc` 曾标 MATRIX 行 `done`;其后 closeout 合并冲突手解取旧侧盖回 `planned`。
## 步骤与验收
1. [x] agentctl 建场与 CURRENT 认领
2. [x] 登记 issue + lesson + ISSUES 投影
3. [x] batch-plan `status: done`
4. [x] docs apply MATRIX `planned → done`(evidence 指向已合入 short-term)
5. [x] arch-check block 复核 + 文档差异/链接
6. [ ] validate → integrate → 五状态收口
## 验证与证据
| 范围 / 被测 SHA | 命令与环境 | 预期 | 实际 / 判定 | 证据 / 脱敏说明 |
|---|---|---|---|---|
| 架构门禁 | `./scripts/arch-check.sh --mode block` @ `b9d09c97` | PASS | PASS | 纯文档变更;Go 全量 / PI **NOT REQUIRED**(验证契约) |
| MATRIX 行 | docs apply + snapshot | status=done | PASS(done) | record_id=`module-batches-ag`;收据 run `…-matrix-1` / header `@document` |
| 链接一致性 | 目标路径存在性 | 可达 | PASS | issue/lesson/A–G short-term / boundaries |
## 收口与交接
- 本地提交:`54641f46`(登记)+ `b9d09c97`(MATRIX);后续 resolve 提交另记。
- Server 镜像字段债务不在本任务。
## 相关链接
- Plan:用户确认的状态回退修正计划
- 分批计划:[../../remediation/2026-09-20-module-decoupling-batch-plan.md](../../remediation/2026-09-20-module-decoupling-batch-plan.md)
- 问题:[../../audit/2026-09-23-matrix-status-regression.md](../../audit/2026-09-23-matrix-status-regression.md)
@@ -1,8 +1,8 @@
---
title: "模块解耦分批整改(A–G)"
status: planned
status: done
created: 2026-09-20
updated: 2026-09-20
updated: 2026-09-23
---
# 模块解耦分批整改(A–G)
@@ -11,7 +11,7 @@ updated: 2026-09-20
[耦合审计](../audit/2026-09-20-module-coupling-audit.md) 确认:模块化单体、窄端口和 PG 事件总线已经在运行。本计划只清除仍会让故障跨模块扩散的残留,不推翻 [ADR](../adr/2026-09-14-modular-monolith-decoupling.md),不引入 RPC,不合入 FAV,不改 `production_ready`。
通信规则以 [模块开发规范](../system-design/2026-09-20-module-development-standards.md) 为准。每一批开工前另建 short-term,并在 CURRENT 认领;本文件把批次保持 `planned`。
通信规则以 [模块开发规范](../system-design/2026-09-20-module-development-standards.md) 为准。每一批开工前另建 short-term,并在 CURRENT 认领。**2026-09-23**:A–G 与 residual 二轮均已合入;本文件 `status: done`。FEATURE-MATRIX 伞行曾因合并冲突回退为 `planned`,由任务 `module-batches-ag-status-fix-2026-09-23` 按证据恢复。
## 目标
@@ -97,10 +97,10 @@ G1 若在到期日前无法合并,必须另写 audit:要么延长并给出
## 验收标准
- [ ] 每一批有独立 short-term、CURRENT 认领、测试记录;本文件不代替那些记录。
- [ ] 未开始的批次在 FEATURE-MATRIX 保持 `planned`。
- [ ] 任一批不得把 FAV live、`production_ready` 或 RPC 拆分写进自己的完成定义。
- [ ] 合入 `dev` 时集成槽位为该批 holder,冒烟包含 `arch-check`、`go vet`、`go test -short`。
- [x] 每一批有独立 short-term、CURRENT 认领、测试记录;本文件不代替那些记录。
- [x] 伞行 FEATURE-MATRIX `module-batches-ag` 在 2026-09-23 复核收口为 `done`(此前合并回退已修正)。
- [x] 任一批不得把 FAV live、`production_ready` 或 RPC 拆分写进自己的完成定义。
- [x] 合入 `dev` 时集成槽位为该批 holder,冒烟包含 `arch-check`、`go vet`、`go test -short`。
## 相关链接
+2 -2
View File
@@ -1,6 +1,6 @@
# 模块与功能完成度(SSOT)
**更新**: 2026-09-20(模块开发规范与耦合审计已合入文档;批次 A–G 仍为 planned,不改 `production_ready`)
**更新**: 2026-09-23(批次 A–G 伞行 `module-batches-ag` 已 `done`;不改 `production_ready`)
**production_ready**: yes(权威来源:[gap-matrix](../remediation/gap-matrix.md);本表不推导发布门禁)
**发布缺口**: [../remediation/gap-matrix.md](../remediation/gap-matrix.md)
**协作焦点**: [../ops/CURRENT.md](../ops/CURRENT.md)
@@ -72,7 +72,7 @@
| infra-artifact-digest | Artifact 同 digest 晋升 | 候选 commit 一次构建、按 digest 晋升、promotion receipt | done | 加固 | [计划 PU5B](../remediation/2026-09-16-feature-matrix-production-readiness-plan.md);[Wave2B](../test-reports/2026-09-16-wave2b-nightly-promotion-receipt-test-report.md);[Wave2C](../test-reports/2026-09-16-wave2c-same-image-digest-test-report.md) | **关闭**:same-image pin(`candidate-images-*` + `PINNED_IMAGE_MODE` + promote `--require-digests`)。**声明**:单机 retag/digest pin;远程 registry 推送另立任务 | `infra` |
| events-core | 可靠事件核心 | PG dispatcher、notify/advance/projection live、生产闭包 hook 退出、Phase2 选择性解耦已合入 | done | non_blocker | [E0A–E2](../test-reports/2026-09-15-event-e0a-production-scope-contract-test-report.md) 等;[复盘](../ops/research/2026-09-15-track-e-retrospective.md);[shared live](../test-reports/2026-09-15-event-notify-shared-live-test-report.md);[phase2 closeout](../test-reports/2026-09-15-phase2-closeout-test-report.md) | **before**:与 FAV off 混成 partial → **after**:FAV 独立行。选择性后续解耦按收益触发 | `architecture-docs` / `events` |
| module-spec | 模块开发规范 | 窄端口、领域事件、wire DTO 三种契约;故障隔离红线;新增模块/表/事件流程。不含批次 A–G 的代码整改 | done | non_blocker | [规范](../system-design/2026-09-20-module-development-standards.md);[审计](../audit/2026-09-20-module-coupling-audit.md);[ADR](../adr/2026-09-14-modular-monolith-decoupling.md) | 文档入口已立。代码整改不在本行 | `module-decoupling-spec` |
| module-batches-ag | 模块解耦批次 A–G | server 端口装配、chat 解环、docgov 词汇、工作流单向依赖、巨型文件、前端 api client、21 条例外清零 | planned | non_blocker | [分批计划](../remediation/2026-09-20-module-decoupling-batch-plan.md);[审计](../audit/2026-09-20-module-coupling-audit.md);[A](../ops/short-term/2026-09-22-server-assembly-cleanup.md);[B](../ops/short-term/2026-09-22-chat-app-decouple.md);[C](../ops/short-term/2026-09-22-docgov-vocabulary-convergence.md);[D](../ops/short-term/2026-09-22-workflow-def-unidirect.md);[E](../ops/short-term/2026-09-22-engine-split.md);[F](../ops/short-term/2026-09-22-web-api-client.md);[G1](../ops/short-term/2026-09-22-g1-exception-clearance.md);[G2/G3](../ops/short-term/2026-09-22-g2-g3-exception-clearance.md) | **after 2026-09-22**:A–F 与 E 已合入;G1/G2/G3 例外清零后 `arch-check --mode block` PASS 且 baseline import/sql_write/path/event **全 0**。关闭本伞行 | `module-decoupling-spec` |
| module-batches-ag | 模块解耦批次 A–G | server 端口装配、chat 解环、docgov 词汇、工作流单向依赖、巨型文件、前端 api client、21 条例外清零 | done | non_blocker | [分批计划](../remediation/2026-09-20-module-decoupling-batch-plan.md);[审计](../audit/2026-09-20-module-coupling-audit.md);[A](../ops/short-term/2026-09-22-server-assembly-cleanup.md);[B](../ops/short-term/2026-09-22-chat-app-decouple.md);[C](../ops/short-term/2026-09-22-docgov-vocabulary-convergence.md);[D](../ops/short-term/2026-09-22-workflow-def-unidirect.md);[E](../ops/short-term/2026-09-22-engine-split.md);[F](../ops/short-term/2026-09-22-web-api-client.md);[G1](../ops/short-term/2026-09-22-g1-exception-clearance.md);[G2/G3](../ops/short-term/2026-09-22-g2-g3-exception-clearance.md);[状态回退修正](../ops/short-term/2026-09-23-module-batches-ag-status-fix.md);[ISSUE](../audit/2026-09-23-matrix-status-regression.md) | **2026-09-23 复核收口**:A–F + G1/G2/G3 及 residual 二轮均已合入 dev;`arch-check --mode block` PASS、baseline 全 0、exceptions 清零。此前状态曾被 closeout 合并冲突错误回退(ISSUE-20260923-matrix-status-regression),本次按证据修正。Server 镜像字段增量收口另立任务 | `module-decoupling-spec` |
| events-fav | Final Artifact Vault(FAV) | 不可变终态制品库;`FAV_DEGRADED_READ=false` | partial | deferred_enhancement | [Track E 复盘](../ops/research/2026-09-15-track-e-retrospective.md);[U7 报告](../test-reports/2026-09-16-fav-u7-incremental-test-report.md);[W6 shadow](../test-reports/2026-09-17-w6-fav-subscriber-shadow-test-report.md);[红线证据](../test-reports/2026-09-22-redline-evidence-fav-test-report.md) | gap-fill 单测+drill 证据已合入 local_dev(例外授权 2026-09-23)。**live 未放量**;观察窗起点已登记。`FAV_DEGRADED_READ` 默认 false;保持 partial 不升 done | `events` |
| web-sysadmin | 系统管理台 | 全屏系统级管理视图(总览/KB/特性开关/系统设置/工作流/角色/用户/文档 8 分组);`/api/v1/admin/system/*`;`system_settings` 白名单可写;吸收下线 AdminSettingsModal;细粒度 `system:*` + 设置审计日志(goose 00065) | done | non_blocker | [short-term](../ops/short-term/2026-09-17-system-admin-console.md);[测试报告](../test-reports/2026-09-17-system-admin-console-test-report.md);residual `modular-decouple-residual-2026-09-23` | 剩余 deferred:Playwright 实跑、KB 运维动作、白名单项接消费方 | `web` + `sysadmin` |
| removed-control-center | 个人工程中控台(已移出) | 原本地只读看板与后来的 Control Center 都不再属于本仓库 | removed | 进度管理改由独立项目承担 | [历史设计](../archive/design/2026-09-17-personal-engineering-control-center-plan.md);[历史报告](../test-reports/2026-09-17-engineering-dashboard-test-report.md) | 2026-09-19 删除 `cmd/control-center`、`internal/controlcenter`、`control-center/web`、`deploy/control-center`。不恢复 `engineering-dashboard` | — |