release-candidate: 汇集 local_dev 至 test，准备长期实测 [Tag: rc-v1.1.0-beta.3]

Fixed Chinese names collided on reused gate-pg across nightly runs.

.cursor/hooks.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [
+      {
+        "command": ".cursor/hooks/guard-git.sh",
+        "matcher": "^git ",
+        "failClosed": true
+      }
+    ]
+  }
+}

.cursor/hooks/guard-git.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Fail-closed red-line gate for destructive / unauthorized git. Does not replace agentctl leases.
+set -euo pipefail
+input=$(cat)
+command=$(printf '%s' "$input" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("command") or "")')
+
+ask() {
+  local user_msg="$1"
+  local agent_msg="$2"
+  python3 -c 'import json,sys; print(json.dumps({"permission":"ask","user_message":sys.argv[1],"agent_message":sys.argv[2]}))' "$user_msg" "$agent_msg"
+  exit 0
+}
+
+allow() {
+  echo '{"permission":"allow"}'
+  exit 0
+}
+
+# Normalize whitespace for matching
+cmd=$(printf '%s' "$command" | tr '\n' ' ')
+
+# Unauthorized push (user must confirm)
+if printf '%s' "$cmd" | grep -Eq '(^|[[:space:]])git([[:space:]]+-[^[:space:]]+)*[[:space:]]+push([[:space:]]|$)'; then
+  ask "git push 需要显式用户授权（AGENTS remote_sync）。请确认后再继续。" \
+      "Hook blocked git push pending user authorization."
+fi
+
+# Destructive / force operations
+if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+.*(--force|-f)([[:space:]]|$)' \
+  || printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+push[[:space:]].*\+'; then
+  ask "检测到 git --force / 强推。破坏性操作须用户明确授权。" \
+      "Hook requires confirmation for force git operation."
+fi
+
+if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+reset[[:space:]]+.*--hard'; then
+  ask "git reset --hard 会丢弃工作区。须用户明确授权。" \
+      "Hook requires confirmation for git reset --hard."
+fi
+
+if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+clean[[:space:]]+.*-[a-zA-Z]*f'; then
+  ask "git clean -f 会删除未跟踪文件。须用户明确授权。" \
+      "Hook requires confirmation for git clean -f."
+fi
+
+if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+branch[[:space:]]+(-D|--delete[[:space:]]+--force)'; then
+  ask "强制删分支 (-D) 须用户明确授权；优先 git branch -d。" \
+      "Hook requires confirmation for git branch -D."
+fi
+
+if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+worktree[[:space:]]+remove[[:space:]]+.*--force'; then
+  ask "git worktree remove --force 被 AGENTS 禁止升级。须用户明确授权。" \
+      "Hook requires confirmation for forced worktree remove."
+fi
+
+if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+checkout[[:space:]]+--\.($|[[:space:]])'; then
+  ask "git checkout -- . 会丢弃全部本地修改。须用户明确授权。" \
+      "Hook requires confirmation for discarding all local changes."
+fi
+
+allow

.cursor/mcp.json

@@ -0,0 +1,17 @@
+{
+  "mcpServers": {
+    "agentctl": {
+      "command": "node",
+      "args": ["${workspaceFolder}/scripts/mcp/agentctl-mcp.mjs"]
+    },
+    "jev": {
+      "command": "node",
+      "args": ["${workspaceFolder}/scripts/mcp/jev-mcp.mjs"]
+    },
+    "codegraph": {
+      "type": "stdio",
+      "command": "codegraph",
+      "args": ["serve", "--mcp", "--path", "${workspaceFolder}"]
+    }
+  }
+}

.cursor/rules/agentctl-mandatory.mdc

@@ -0,0 +1,23 @@
+---
+description: Agent-System 写操作必须经 agentctl（租约、docs apply、候选合入）；禁止绕过治理直接改共享文档或 push。
+alwaysApply: true
+---
+
+# agentctl 强制治理
+
+本仓库由 agentctl 管理面协调（SQLite + launchd daemon）。细则见 [AGENTS.md](../../AGENTS.md) 与 [操作规范](../../.doc/ops/2026-09-21-agent-worktree-workflow.md)；流程技能见 `.cursor/skills/agentctl-*`。
+
+## 硬边界
+
+1. **写仓库**：必须 `agentctl with` / MCP `lease_run`。裸 `git commit` 会被 agentctl pre-commit hook 拒绝。
+2. **共享文档**：`.doc/ops/CURRENT.md`、`.doc/status/FEATURE-MATRIX.md` 只能 `docs apply`（行级 CAS；MATRIX 键为 `record_id`）。
+3. **合入 local dev**：`validate` 后 `queue enqueue`（daemon `--ff-only`）或受控 `integrate`；禁止直接改主目录 `dev`  tip。
+4. **禁止默认**：未授权 `git push`、晋升 test/main、`--force` 清理、卸载 launchd coordinator、改 gap-matrix / 升 MATRIX 状态值冒充发布。
+
+## 会话路径
+
+- 启动 → skill `agentctl-session-start`
+- 建场 → `agentctl-worktree-setup`
+- 写回 → `agentctl-lease-write`
+- 合入/收口 → `agentctl-integrate-closeout`
+- MCP 工具定义见 `.cursor/mcp.json` → `scripts/mcp/agentctl-mcp.mjs`

.cursor/rules/test-reports-standard.mdc

@@ -1,6 +1,67 @@
 ---
-description: 按变更范围选择测试及真实证据要求
+description: 规定项目中所有自动化测试、功能测试、集成测试报告的存放路径与结构标准规范
+globs: ["**/*test*.go", ".doc/test-reports/**/*.md"]
 alwaysApply: true
 ---
 
-测试范围、精确产品 PI 入口、环境模型证据和报告格式统一见 [验证契约](../../.doc/ops/2026-09-21-validation-contract.md)。按实际变更选择适用行；报告大小不扩大测试范围。
+# 测试报告规范准则 (Test Reports Standard)
+
+本仓库严格遵循标准化、可追溯的质量测试管理体系。所有测试报告必须归档于指定的文档目录下，并遵循固定结构。
+
+**范围判定**：纯工程规范/文档变更按 [PROJECT.md](../../PROJECT.md) §8 和 [worktree 工作规范](../../.doc/ops/2026-09-21-agent-worktree-workflow.md) 检查链接、规则一致性及 Git 差异；不适用下述产品 PI 全链路与全量 Go 回归要求。报告注明 NOT REQUIRED 及依据，不能记成产品测试 PASS。运行模板、提示词和业务变更不属于此例外。
+
+## 一、 测试报告归档路径规范
+
+- **统一目录**：所有测试报告必须统一存放于 `.doc/test-reports/` 目录下。
+- **命名规范**：遵循 `YYYY-MM-DD-<模块/功能/版本>-test-report.md` 命名格式。
+  - 例如：`.doc/test-reports/2026-09-07-three-branch-intent-framework-test-report.md`
+- **证据附件**：运行产物（json/jsonl、workspace 快照、截图）放 `.doc/test-reports/assets/<report-slug>/`，**不得**与 `*-test-report.md` 混放在同一层级目录。
+
+---
+
+## 二、 测试报告固定结构模板
+
+每份测试报告必须包含以下核心板块：
+
+```markdown
+# [功能/模块名称] 测试报告
+
+## 一、 测试背景 (Background)
+- 简述被测功能/特性的产生背景、业务痛点或上一轮测试中发现的缺陷与瓶颈。
+
+## 二、 测试目标 (Test Objectives)
+- 列举本次测试需要验证的核心功能点、质量指标（如通过率 100%、无流程卡点、非阻塞人机协同等）。
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+- 测试环境（OS、Go 版本、后端 Stub/Real 模型）；
+- 测试层级分层（单元测试、协同集成测试、CLI 真实交互测试）；
+- 核心测试用例矩阵设计。
+
+## 四、 预期结果 (Expected Results)
+- 明确给出各用例输入下的理论判定分支、目标意图、提取槽位、参谋回复风格与状态机流转。
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+- 必须包含针对每一个典型测试用例的真实记录：
+  - **测试输入 (Input)**
+  - **实际输出 (Actual Output)**：贴出真实的终端/日志输出文本
+  - **评价判定 (Evaluation / Verdict)**：PASS / FAIL 标志及判定依据
+  - **性能与耗时 (Duration & Latency)**
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+- 附带 `go test -v ./...` 全量回归测试输出与通过率统计。
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+- 总结测试是否达到上线/合并标准，提出后续演进或强化点。
+```
+
+---
+
+## 三、 执行要求与真实 Agent 交付铁律
+
+1. **真实 Agent 交付铁律（红线）**：
+   - **开发实现阶段**：可以快速使用 `stub` 验证状态机、协议分流、数据落盘与逻辑契约，加速反馈；
+   - **交付前验收与测试报告生成**：**必须切回真实环境与真实 Agent（`pi-agent` + 实际运行的 `MiniMax-M2.7-highspeed` 容器）进行全链路端到端实测**；
+   - **严禁**使用 stub 的测试输出作为最终交付报告的验收数据。
+2. **严禁散落存放**：测试报告统一归档至 `.doc/test-reports/` 目录下，禁止散落在根目录或临时沙箱中。
+3. **真实控制台取样**：测试报告中的输入、输出、耗时与判定必须取自实际环境运行的真实控制台输出与日志。
+4. **Git 规范管理**：测试报告伴随对应阶段的 `docs(test)` 或 `test(...)` 规范提交入库。

.cursor/skills/agentctl-integrate-closeout/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: agentctl-integrate-closeout
+description: Validate a merge candidate, enqueue for daemon ff-only integrate, and close out five-state. Use when ready to land a task on local dev.
+---
+
+# agentctl 集成与收口
+
+权威：[操作规范](../../../.doc/ops/2026-09-21-agent-worktree-workflow.md)、[验证契约](../../../.doc/ops/2026-09-21-validation-contract.md)。常驻 daemon 已装载时走 **enqueue**，勿手动 `integrate`（除非 daemon 停）。
+
+## 候选
+
+```bash
+D=$(git -C /path/to/Agent-System rev-parse HEAD)   # 冻结 expected-dev
+ID=integrate-<task>-YYYY-MM-DD
+git worktree add -b feature/$ID .worktrees/$ID "$D"
+cd .worktrees/$ID
+python3 ../../scripts/agentctl.py task register --id "$ID" --owner Cursor --scope . --capability git:dev
+python3 ../../scripts/agentctl.py with --task "$ID" \
+  --resource path:. --resource git:index --resource git:dev -- bash -lc '
+  git merge --no-ff -m "merge: candidate <feature> into dev" feature/<task>
+'
+```
+
+第一父必须等于 `$D`。
+
+## validate → enqueue（daemon ff）
+
+```bash
+python3 ../../scripts/agentctl.py validate --task "$ID" -- <验收命令>
+python3 ../../scripts/agentctl.py queue enqueue \
+  --task "$ID" --expected-dev "$D" --head "$(git rev-parse HEAD)"
+# 在任务 worktree 内 enqueue；数秒内 daemon 合入
+python3 ../../scripts/agentctl.py queue list
+python3 ../../scripts/agentctl.py daemon status
+```
+
+验收按验证契约选行；治理脚本用 `unittest discover`。
+
+## 五态收口
+
+| 字段 | 典型值 |
+|---|---|
+| review_state | accepted |
+| integration_state | merged_local_dev |
+| deployment | not_required 或 loaded_local_launchd |
+| cleanup | pending（独立维护者；禁止 `--force`） |
+| remote_sync | not_requested |
+
+CURRENT 行 → `done`（`docs apply`）；`task close --status done`。
+
+## 清理前
+
+确认 tip 为 local_dev 祖先、证据已持久化、无 tracked/untracked 遗留、无进程占用。唯一日志/对话归档进 `.doc/ops/evidence/` 后再 `worktree remove`。
+
+只读盘点（不自动删除、不自动写 MATRIX）：
+
+```bash
+python3 ../../scripts/agentctl.py cleanup report   # 主目录或任意同仓 cwd
+python3 ../../scripts/agentctl.py docs drift
+```
+
+对 `verdict=ready` 的 worktree 由独立维护者执行 `agent-worktree.sh remove … --delete-branch`；拒绝则保留 cleanup_pending。daemon 未装载时用 `queue schedule --drain`（主目录 + 分支 dev）。

.cursor/skills/agentctl-lease-write/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: agentctl-lease-write
+description: Write under agentctl leases and docs apply CAS. Use before any git write, shared-doc edit, or when hitting UNMANAGED_DOCUMENT_CHANGE / EVIDENCE_REQUIRED.
+---
+
+# agentctl 租约写回
+
+权威：[AGENTS §3–5](../../../AGENTS.md)、[操作规范](../../../.doc/ops/2026-09-21-agent-worktree-workflow.md)。
+
+## 原则
+
+- **任何仓库写**（含 `git add/commit`）必须在 `agentctl with` / MCP `lease_run` 租约内
+- CURRENT / FEATURE-MATRIX **只能** `docs apply`（行级 CAS；MATRIX 键为 `record_id`）
+- 直接 `git commit` 会被 agentctl-managed pre-commit hook 拒绝
+
+## lease_run（CLI）
+
+```bash
+python3 scripts/agentctl.py with \
+  --task "$ID" \
+  --resource path:scripts --resource path:.doc --resource git:index \
+  -- bash -lc 'git add … && git commit -m "…"'
+```
+
+MCP：`lease_run` 的 `command` 为 **argv 数组**（无额外 shell）。
+
+## docs apply（行级）
+
+```bash
+python3 scripts/agentctl.py docs snapshot --file .doc/ops/CURRENT.md --record "$RID"
+# expected_sha256 = snapshot.sha256；改 replacement 后：
+python3 scripts/agentctl.py docs apply --task "$ID" --request /tmp/req.json
+```
+
+FEATURE-MATRIX 升 `done` 需要 `docs:approve` + 可核验 evidence（`git cat-file -e`），否则 `EVIDENCE_REQUIRED`。
+收口或合入含 MATRIX 的变更后跑 `python3 scripts/agentctl.py docs drift`：硬告警仅 `done→非 done`；不因任务结束自动升 done。
+
+## 常见拒绝
+
+| 码 | 处置 |
+|---|---|
+| `UNMANAGED_DOCUMENT_CHANGE` | 保留现场，先 snapshot/reconcile，勿覆盖 |
+| `BASE_CHANGED` | 重新 snapshot，基于新 sha 再 apply |
+| `AMBIGUOUS_RECORD` | 修重复 record_id / 模块名 |
+| `CAPABILITY_REQUIRED` | 任务缺 docs:admin / docs:approve |
+| `DOCUMENT_RECEIPT_REQUIRED` | 共享文档须经 apply 收据后再 commit |

.cursor/skills/agentctl-session-start/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: agentctl-session-start
+description: Start an Agent-System session under agentctl governance. Use at session start, when opening a worktree, or before any write to this repo.
+---
+
+# agentctl 会话启动
+
+权威规范：[AGENTS.md](../../../AGENTS.md)、[操作规范](../../../.doc/ops/2026-09-21-agent-worktree-workflow.md)、[CURRENT](../../../.doc/ops/CURRENT.md)。
+
+## 步骤
+
+1. 读 `AGENTS.md`、`PROJECT.md`、`.doc/ops/CURRENT.md` 活跃摘要（勿跳过）。
+2. 核对管理面：
+
+```bash
+python3 scripts/agentctl.py daemon status
+# 期望：status=ok；launchd 已装载时 manager.lock.held=true
+```
+
+或 MCP 工具 `status`。
+
+3. 刷新 CodeGraph 索引（fail-open；CLI 缺失可跳过）：
+
+```bash
+codegraph sync -q
+# 或：python3 scripts/agentctl.py hooks codegraph-sync
+```
+
+跨文件定位优先用 CodeGraph MCP/`explore`；**grep 仍是完整性唯一权威**（假阴性时以 grep 为准）。
+
+4. 若任务已存在：在注册 worktree 内工作，确认 `tasks.state=active`。
+5. 若新任务：跟 [agentctl-worktree-setup](../agentctl-worktree-setup/SKILL.md)。
+6. 任何仓库写 → [agentctl-lease-write](../agentctl-lease-write/SKILL.md)；合入 → [agentctl-integrate-closeout](../agentctl-integrate-closeout/SKILL.md)。
+
+## 禁止
+
+- 主目录直接开发提交；未授权 `git push` / 晋升 test/main
+- 绕过 `docs apply` 改 CURRENT / FEATURE-MATRIX
+- 卸载或重启 launchd coordinator（除非用户明示）

.cursor/skills/agentctl-worktree-setup/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: agentctl-worktree-setup
+description: Create an agentctl task worktree, register scopes/capabilities, and claim CURRENT. Use when starting a new feature/fix task in Agent-System.
+---
+
+# agentctl 建场
+
+权威：[操作规范](../../../.doc/ops/2026-09-21-agent-worktree-workflow.md)。
+
+## 命令序列
+
+```bash
+cd /path/to/Agent-System   # 主目录（dev）
+D=$(git rev-parse HEAD)
+ID=<task-id-YYYY-MM-DD>
+WT=.worktrees/$ID
+# 推荐入口：自动 best-effort codegraph init（后台；CLI 缺失不阻断）
+./scripts/agent-worktree.sh create feature/$ID
+# 等价：git worktree add -b feature/$ID "$WT" "$D"
+cd "$WT"
+python3 ../../scripts/agentctl.py task register \
+  --id "$ID" --owner <Owner> \
+  --scope scripts --scope .doc \
+  --capability docs:publish
+# 需要整文/行级 admin 时再加 --capability docs:admin；证据升 done 加 docs:approve
+codegraph sync -q   # 若建场已 init，此处只需 sync；缺失 CLI 可跳过
+```
+
+## CURRENT 认领（docs apply）
+
+```bash
+python3 ../../scripts/agentctl.py docs snapshot \
+  --file .doc/ops/CURRENT.md --record "$ID" > /tmp/claim-snap.json
+# 新建行：expected_sha256=null
+cat > /tmp/claim.json <<EOF
+{"request_id":"$ID-claim-1","changes":[{
+  "file":".doc/ops/CURRENT.md","record_id":"$ID","expected_sha256":null,
+  "replacement":"| <Owner> | $ID | feature/$ID | $WT | <mutex> | in_progress |"
+}]}
+EOF
+python3 ../../scripts/agentctl.py docs apply --task "$ID" --request /tmp/claim.json
+```
+
+## short-term 模板字段
+
+`status`、`write_scope`、`mutex`、`base_dev_sha`、`review_state`/`integration_state`/`deployment`/`cleanup`/`remote_sync`。命名 `.doc/ops/short-term/YYYY-MM-DD-<slug>.md`。
+
+## 注意
+
+- 从确切 `dev` SHA 创建，不从他人 feature 分支启动
+- 重叠 path/mutex 只允许一个写者
+- CodeGraph 索引是加速器：有假阴性；穷举调用方仍用 grep

.cursor/skills/jev-decide/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: jev-decide
+description: Use jev-service typed decisions (choice/noul/numeric with probabilities) for Agent-System governance classification. Use when choosing task tier, validation level, reject-code routing, or other closed-enum judgments.
+---
+
+# jev-decide（治理决策）
+
+依赖 MCP 服务器 `jev`（[`scripts/mcp/jev-mcp.mjs`](../../../scripts/mcp/jev-mcp.mjs)）。凭证在本机 `~/.secrets/jev/`（`api.key`、`base-url`），**禁止**写入仓库、commit 或聊天。
+
+## 何时用
+
+输入是情境文本、输出是**封闭枚举 / yes-no / 分桶数值**时调用 `jev_decide`，例如：
+
+| 决策点 | 建议 questions |
+|---|---|
+| 任务分级（是否开 worktree） | `choice`：`info_reply` / `single_task` / `cross_module` |
+| 验证层级（验证契约） | `choice`（可多题）：`doc` / `script` / `go` / `frontend` / `migration` / `product_pi` |
+| 拒绝码处置 | `choice`：`reconcile` / `re_snapshot` / `fix_record_id` / `request_capability` / `abort` |
+| 是否 blocker / 是否触碰重验面 | `noul` |
+
+不适合：需要解释链、多步规划、自由文本生成——那些走大模型或 agentctl 确定性门禁。
+
+## 调用约定
+
+1. 可选先 `jev_health`；失败则本机判断，勿阻塞写路径。
+2. `jev_decide`：同一情境的多问合成一次请求。
+3. 问句**正向措辞**，避免双重否定。
+4. 置信度路由：
+   - `confidence >= 0.9` 且 top1−top2 ≥ 0.15 → 可采用
+   - 否则 → agent 自行按规范裁定，把 jev 结果当参考
+5. 401/超时/`answers.*.error` → 降级到本机判断；勿把决策失败变成业务失败。
+
+## 示例（任务分级）
+
+```json
+{
+  "context": "用户请求：给 CURRENT 加一行认领说明，不改代码",
+  "questions": {
+    "tier": {
+      "type": "choice",
+      "question": "This request matches which AGENTS task tier?",
+      "options": ["info_reply", "single_task", "cross_module"]
+    },
+    "needs_worktree": {
+      "type": "noul",
+      "question": "Does this require a new feature/fix worktree?"
+    }
+  }
+}
+```
+
+权威矩阵仍以 [AGENTS.md](../../../AGENTS.md)、[验证契约](../../../.doc/ops/2026-09-21-validation-contract.md) 为准；jev 只加速封闭枚举分类，不替代机器门禁（admit/hooks/docs apply）。

.doc/README.md

@@ -11,10 +11,10 @@
 .doc/
   README.md              ← 本文件（总地图）
   status/                ← 模块/功能完成度 SSOT
-  audit/                 ← 问题发现与分析
+  audit/                 ← 问题发现与分析、ISSUES.md 问题/修复台账
   remediation/           ← 整改方案与发布缺口
   archive/               ← 历史（只增不删）
-  ops/                   ← 活协作（任务、交接、调研）
+  ops/                   ← 活协作（任务、交接、调研；lessons/ 开发经验）
   system-design/         ← 模块架构深读
   adr/                   ← 架构决策
   backlog/               ← 产品 backlog（非阻塞）
@@ -40,6 +40,8 @@
 | 当前在做什么 | [ops/CURRENT.md](ops/CURRENT.md) |
 | 模块完成度 | [status/FEATURE-MATRIX.md](status/FEATURE-MATRIX.md) |
 | 发布 blocker | [remediation/gap-matrix.md](remediation/gap-matrix.md) |
+| 问题历史、修复经过 | [问题台账](audit/ISSUES.md) · [闭环规范](ops/2026-09-23-issue-learning-workflow.md) |
+| 开发注意事项与经验检索 | [经验索引](ops/lessons/INDEX.md) |
 | 审计/问题分析 | [audit/INDEX.md](audit/INDEX.md) |
 | 整改方案 | [remediation/INDEX.md](remediation/INDEX.md) |
 | 历史归档 | [archive/README.md](archive/README.md) |
@@ -68,6 +70,6 @@ audit（问题）→ remediation（方案）→ ops/short-term（任务）
   → test-reports（验收）→ archive（关闭证据）
 ```
 
-状态字段：`planned | in_progress | blocked | done | cancelled`
+任务状态字段：`planned | in_progress | blocked | done | cancelled`。问题以 issue_state、经验以 lesson_state 独立记录，取值与转换见 [闭环规范](ops/2026-09-23-issue-learning-workflow.md)；研究任务完成不关闭待修问题。
 
 会话结束不等于任务完成；只有 done/cancelled 任务归档。CURRENT 保留最多 3 项焦点及活跃/阻塞/待集成/待清理事项，完成认领和长证据迁入 [历史快照](archive/ops/2026-09-21-current-history.md)。移动文档同步修复相对链接，保留证据与来源。规范生命周期另用 proposed/approved/active/deprecated；工具能力另用 manual/enforced。

.doc/adr/2026-09-14-final-artifact-vault.md

@@ -0,0 +1,25 @@
+# ADR：最终成果保险库（FAV）
+
+## 状态
+
+已接受（2026-09-14，落地计划 V0–V6）
+
+## 背景
+
+运行库 PostgreSQL 与 workspace 投影会一起丢失或错挂。需要独立保存**已确认终态**的精确字节，但不能成为第三套完整业务真相源，也不能用目录扫描猜测“最终文件”。
+
+## 决策
+
+1. **三层权威**：PostgreSQL 管项目/权限/工作流/版本关系；workspace 是可清理投影；FAV 只对已归档 payload、manifest、来源证据和删除状态权威。
+2. **无 tenant_id**：安全边界沿用 `environment + project_members + role-admin`。未来组织层另立 ADR。
+3. **事件准入**：只接受方案准入表中的数据库事实。显式 publish/pin 不能绕过终态 allowlist。禁止扫描 workspace。
+4. **同事务冻结**：终态事务把精确 payload/SHA 写入 staging 并写 unpublished outbox；publisher 不得重读可变消息行。
+5. **union-deny 删除**：运行库删除账本或 vault tombstone 任一侧删除即拒绝读取/恢复。
+6. **恢复**：只进 scratch 库，默认 `recover-as-collection`。禁止 GET 自动写回或覆盖现有 head。
+7. **互补**：FAV、migration corpus、完整 DB backup/PITR 互相不能替代。不作为 409/split-brain 绕行。
+
+## 后果
+
+- 实现从 `feature/final-artifact-vault` 推进；mutex=`artifact-vault`。
+- Goose 从 **00034** 增加 FAV 表（00033 已被 task-run 治理占用）。
+- 降级读取默认关闭（`FAV_DEGRADED_READ`），Unit A 纠挂完成前不得对现网开启。

.doc/archive/ops/2026-09-21-agent-policy-review.md

@@ -0,0 +1,47 @@
+---
+title: "Agent 规范整体审查"
+status: done
+created: 2026-09-21
+updated: 2026-09-21
+owner: Codex
+branch: feature/agent-policy-review
+worktree: .worktrees/agent-policy-review
+base_dev_sha: a241e838150f218f3a09d3523f93291b847d45fd
+write_scope: [.doc/ops/short-term/2026-09-21-agent-policy-review.md, .doc/archive/ops/2026-09-21-agent-policy-review.md, .doc/audit/2026-09-21-agent-policy-review.md, .doc/ops/CURRENT.md]
+mutex: agent-policy-review
+deployment: not_required
+cleanup: retained-with-reason
+---
+
+# Agent 规范整体审查
+
+## 目标与范围
+
+评估生效规范的可完善之处，形成有依据的新增、删除、修改清单。本轮使用 ce-doc-review 的只读审查流程；不修改 AGENTS/PROJECT/客户端规则，不实现锁管理或改业务代码。
+
+## 已确定约束
+
+- 全部新增修改使用 .worktrees；主目录留给 dev 集成与运行。
+- 锁先统一入口/提交门禁防误改，OS 权限隔离后续实施。
+- 审查不等于实现或部署授权；已有未合入规范收口和 .locks 方案保留原分支。
+
+## 步骤
+
+1. [x] 启动链、当前 Git、规范与模板盘点。
+2. [x] 一致性、可执行性、范围、安全及故障场景复核。
+3. [x] 核实保留发现，形成增删改建议与实施优先级。
+4. [x] 文档校验、归档、本地提交。
+
+## 验收
+
+- 每条保留发现有当前源文件或明确缺失证据、实际后果和建议修改。
+- 区分已生效规则、尚待实现工具和未合入草案；不把建议当现状。
+- 未修改主目录跟踪文件、运行锁、服务或用户数据。
+
+## 结果与交接
+
+- [整体审查](../../audit/2026-09-21-agent-policy-review.md)：10 组增删改建议、2 项安全观察；保留已确定的 worktree 与 L1-first 选择。
+- 五个独立会话内视角已返回；主审核对引用与实际命令/脚本。文档原规则未改，自动化未实施。
+- 检查项：新增文档相对链接、git diff --check；未运行产品测试，不作运行验收声明。
+- 本任务 CURRENT 快照标 done，未占共享集成槽位；本地分支保留供审核，未合入 dev、未 push。
+- 需要执行修改时先按第一批消除冲突，再处理减负及既有工具实现；不要将本报告直接视为已生效规则。

.doc/archive/ops/2026-09-21-agent-workflow-governance-adoption.md

@@ -0,0 +1,43 @@
+---
+title: "采纳 Agent worktree 工作规范"
+status: done
+created: 2026-09-21
+updated: 2026-09-21
+owner: Codex
+branch: feature/agent-workflow-governance-plan
+worktree: .worktrees/feature-agent-workflow-governance-plan
+mutex: agent-workflow-governance
+---
+
+# 采纳 Agent worktree 工作规范
+
+## 授权与范围
+
+用户于 2026-09-21 确认“提交吧，之后按这套执行”。延续原治理任务，在原 dev 派生的独立 worktree 内将方案采纳为生效规则，提交并合入本地 dev。仅修改规范、模板和治理记录。
+
+本次不将 W1–W4 的自动化开发宣称已完成；它们保留在实施任务中。主目录仍有其他任务未提交改动，使用临时集成 worktree 合入纯文档，不迁移原任务、不改变业务运行态、不 push。
+
+## 步骤
+
+1. [x] 核对主目录现场、原方案提交与集成槽位。
+2. [x] 同步 AGENTS、PROJECT、Cursor 规则、操作规范与模板。
+3. [x] 文档检查、提交、独立 worktree 合入 dev。
+4. [x] 更新验收/交接及清理状态。
+
+## 验收
+
+- [x] 单 Agent 主目录开发例外已移除，生效规则可从启动链发现。
+- [x] 创建明确来自 dev；测试提交、共享服务串行、部署及安全清理条件可执行。
+- [x] 自动化能力保持 planned；主目录其他任务未提交改动不被纳入提交。
+- [x] 本地 dev 含本次规范提交；未 push，未重建服务。
+
+## 相关链接
+
+- [方案](../../remediation/2026-09-21-agent-workflow-governance-plan.md)
+
+## 结果
+
+- 规则提交 `048bbe4a`，验证的合并候选及首次 dev 合入 `83e22a70`。
+- [文档验收](../../test-reports/2026-09-21-agent-workflow-governance-adoption-test-report.md)。
+- 主目录旧任务保留；临时 dev 集成工作区保留到原 owner 可安全切回 dev，见 [交接](../../ops/handoffs/2026-09-21-agent-workflow-governance-plan.md)。
+- 收口提交合入后普通清理本任务和候选工作区，实际结果记录共同 Git 目录的治理操作收据。未 push；deployment=not_required。

.doc/audit/2026-09-14-dev-runtime-data-root-split-brain.md

@@ -0,0 +1,167 @@
+---
+title: "dev rebuild 从临时 worktree 挂载空数据根导致正文投影 409"
+status: done
+created: 2026-09-14
+updated: 2026-09-14
+severity: critical
+---
+
+# dev rebuild 从临时 worktree 挂载空数据根导致正文投影 409
+
+## 现象
+
+用户刷新项目 143 后，前端请求：
+
+```text
+GET /api/v1/docgov/documents/doc_proj143_intake/content 409
+DOCUMENT_CONTENT_PROJECTION_MISSING
+docgov: document content projection missing
+```
+
+错误发生在 `projectDocuments.ts` → `controlledDocHydrate.ts` 的受控正文水合链。它不是并发编辑的 `HEAD_CONFLICT`，也不是此前已修过的 canonical hash drift。
+
+本轮只做只读现场核对与整改设计：没有操作用户会话、没有修改数据库/正文、没有重建共享容器。
+
+## 结论
+
+直接根因是 **dev 应用、PI Runner、Cursor Runner 被重建成挂载临时集成 worktree 的空 `data/dev`，而 PostgreSQL 仍沿用原 dev 持久卷**，形成数据库与文件事实源的 split-brain：
+
+```text
+PostgreSQL persistent volume
+  document_records.work_dir=/app/data/workspaces/bizdev/intake_1789270446856290128
+                     │
+                     ├─ 主仓 data/dev：output.md 存在，SHA 与 DB/head 一致
+                     │
+                     └─ 当前容器 /app/data：绑定 /tmp/as-dev-wf409-merge/data/dev，文件不存在
+```
+
+`loadControlledDocumentContent` 先取得账本 head，再调用 `InspectProjection`；容器内看不到 `output.md`，因此正确分类为 `MISSING` 并返回 409。前端只是如实暴露后端错误，不是本次根因。
+
+## 现场证据
+
+### E1 — 容器挂载源是临时 worktree
+
+2026-09-14 08:54 UTC 的 `docker inspect shuimu-agent-app-dev`：
+
+| 项 | 现场值 |
+|---|---|
+| Compose working dir | `/tmp/as-dev-wf409-merge` |
+| Compose config | `/tmp/as-dev-wf409-merge/docker-compose.dev.yml` |
+| app `/app/data` source | `/tmp/as-dev-wf409-merge/data/dev` |
+| pi-agent `/app/data/workspaces` source | `/tmp/as-dev-wf409-merge/data/dev/workspaces` |
+| cursor-agent `/app/data/workspaces` source | `/tmp/as-dev-wf409-merge/data/dev/workspaces` |
+| app created | `2026-09-14T08:40:44Z` |
+
+数据库容器的数据仍来自命名卷 `agent-dev-context-pgdata`，不会随 Compose 工作目录切换。由此产生“旧数据库 + 新空文件根”的不一致组合。
+
+### E2 — 项目 143 数据本身当前完整
+
+`document_records`：
+
+| 字段 | 值 |
+|---|---|
+| doc_id | `doc_proj143_intake` |
+| work_dir | `/app/data/workspaces/bizdev/intake_1789270446856290128` |
+| content_sha256 | `f283ba94c9c037897f021960f51abacee7242c3db8d10f9f2a5e32cde6acf039` |
+| updated_at | `2026-09-14 05:14:10.302146+00` |
+
+账本 open version 1 的 head snapshot 302 是人工修订，SHA 同为 `f283...f039`；主仓文件：
+
+```text
+/home/weichen/projects/Agent-System/data/dev/workspaces/bizdev/intake_1789270446856290128/output.md
+size=40075
+sha256=f283ba94c9c037897f021960f51abacee7242c3db8d10f9f2a5e32cde6acf039
+```
+
+同一路径在当前 app 容器内 `stat` 返回 `No such file or directory`。所以无需再次对项目 143 做内容修复；需要恢复正确数据根挂载。
+
+### E3 — 影响不是单文档
+
+对 dev 数据库 100 条“非模板且 work_dir 非空”的记录做只读比较：
+
+| 根目录 | aligned | missing |
+|---|---:|---:|
+| 主仓 `/home/weichen/projects/Agent-System/data/dev` | 32 | 68 |
+| 当前容器挂载 `/tmp/as-dev-wf409-merge/data/dev` | 0 | 100 |
+
+主仓下的 68 条 missing 包含历史测试/临时路径，不能直接等同于 68 个真实用户缺陷；但当前容器对本次抽样 **100/100 都不可见**，足以确认环境级事故。恢复前任何真实文档读取或 PI 写入都不可信。
+
+错误根在容器启动后已出现 27 个文件，其中 9 个 CAS blob 的 mtime 为 `08:40:45 UTC`；虽然 08:54 UTC 尚未找到新的 `output.md`，错误根已经不是可直接丢弃的“绝对空目录”，恢复前仍须做完整差异保全。
+
+只读核对显示 test/main 当前 app 与 PI Runner 仍挂主仓 `data/test`、`data/main`，本轮没有观察到同样的运行事故；但其 Compose 仍使用相对 bind，仍受同一设计缺陷影响。
+
+### E4 — 健康检查假阳性
+
+同一时刻 `/health` 与 `/ready` 都返回 200，只检查数据库、schema 和 task store；未验证：
+
+- 容器绑定的数据根身份；
+- app 与 runner 是否挂载同一根；
+- 活跃项目的正文投影是否可达；
+- 数据库记录与文件根是否属于同一环境实例。
+
+因此“healthy + schema 33”不能证明文档运行态可用。
+
+## 根因分析
+
+### R1 — Compose 相对 bind mount 与调用 worktree 耦合（直接根因）
+
+`docker-compose.dev.yml` 使用：
+
+```yaml
+- ./data/dev:/app/data
+- ./data/dev/workspaces:/app/data/workspaces
+```
+
+Compose 按 project working directory 解析相对路径。`scripts/env-service.sh` 又把 `ROOT_DIR` 定义为脚本所在 worktree 并 `cd` 进去，所以从任何复制/linked worktree 执行 `dev rebuild`，都会把该 worktree 自己的 `data/dev` 当成运行数据根。
+
+### R2 — 纪律是文档约束，不是可执行门禁
+
+`scripts/agent-worktree.sh` 只打印“禁止在此目录运行 env-service”，`AGENTS.md` 也规定 worktree 不得操作共享 Docker；但 `env-service.sh` 没有检测 linked worktree、主 worktree、分支、数据根或集成槽位。一次误调用即可静默替换全套容器挂载。
+
+### R3 — 数据库与文件没有共享存储身份
+
+数据库使用稳定 named volume；正文使用随调用目录变化的 bind mount。两者没有共同的 environment/storage UUID，也没有启动握手，因此任意一个被指向另一份状态时，进程仍可启动并连接成功。
+
+### R4 — 账本权威仍被兼容投影阻断
+
+当前设计声明 ledger head 是权威正文，但 GET 在账本存在时仍要求 `output.md` 投影必须存在且 aligned。于是兼容投影丢失会阻断 UI 读取权威账本。该 fail-closed 对真实 fork 有价值，却把“可安全重建的 missing”与“内容分叉”按同样的可用性后果处理。
+
+### R5 — 正文更新仍是非原子双写
+
+人工 PATCH 先提交 PostgreSQL 账本，再单独写 `output.md`；候选 commit/reject 也采用 DB 状态与文件投影分步更新。失败后只依赖同幂等键重试，没有持久 projection job/status 和后台补偿。即使修复本次挂载问题，进程崩溃、权限错误或磁盘故障仍可能再次留下 head 已更新、投影缺失的状态。
+
+### R6 — 发布验收没有“从不同源码目录 rebuild 后仍接回同一状态”的负例
+
+既有真实 UI 验收验证过 restart 后恢复，但 restart 不会重新解析 Compose bind mount；本次事故由 rebuild/recreate 触发。现有门禁没有覆盖 linked worktree、临时集成目录或错误数据根的启动拒绝。
+
+## 为什么会“每次修改后又出现”
+
+修改本身并不会删除项目 143 正文。本次时间线表明：最新人工修订和主仓 `output.md` 在 05:14 UTC 已一致落盘；08:40 UTC 后续 dev rebuild 把运行容器切到另一份空数据根，刷新才出现 409。
+
+因此用户感知的“改完再刷新就坏”来自两个事件经常相邻：开发修改 → Agent 在临时 worktree 合并/rebuild → Compose 改绑数据目录。只修某个文档、某个 hydrate effect 或某次 hash 漂移，都无法阻止它复发。
+
+## 严重度与影响
+
+`critical`：
+
+- dev 环境所有受控正文、工作流产物和 runner 工作区均可能不可见或写入错误根；
+- 错误根上的新输出可能与主仓状态分叉；
+- health/ready 仍为绿色，集成报告可能产生假 PASS；
+- test/main 使用同类相对 bind 写法，设计缺陷可横向复制，虽本轮未观察其被错挂载。
+
+## 关联整改
+
+- Remediation: [dev 运行数据根隔离与文档投影自愈整改](../remediation/2026-09-14-dev-runtime-data-root-and-projection-remediation.md)
+- Short-term: [dev runtime data root guard 诊断与设计](../ops/short-term/2026-09-14-dev-runtime-data-root-guard.md)
+- 前序问题: [项目 143 canonical hash 漂移](./2026-09-14-project143-controlled-content-404.md)
+
+## 开放问题
+
+- 恢复前需再次冻结并备份错误根，确认 08:40 UTC 后是否已有新会话、附件、runner 输出或 agent session 写入；08:54 UTC 抽样未发现 `output.md`，不能替代完整差异清单。
+- test/main 当前挂载源需在实施 Unit A 只读核对；本轮未扩大操作范围。
+
+## 审查附记（2026-09-14 ~09:23 UTC）
+
+- 现场复核：`shuimu-agent-app-dev` 仍 created `08:40:44Z`，bind source 仍为 `/tmp/as-dev-wf409-merge/data/dev`；`/health` `/ready` 仍 200，`schema_version=33`。
+- 主仓 CURRENT 集成槽仍为 `implementer_cursor` / `e2e`。worktree 副本不得写成 idle。
+- 方案已审查修订：见 [整改方案](../remediation/2026-09-14-dev-runtime-data-root-and-projection-remediation.md)。用户选择事故抢占 + 先改方案再批实施。08:54 的 `f283...f039` 不得再当 Wave 0 硬门槛。

.doc/audit/2026-09-21-go-agentx-runtime-latency-gap.md

@@ -0,0 +1,39 @@
+---
+title: "pi-native 对比未过 P95 门槛"
+status: planned
+created: 2026-09-21
+updated: 2026-09-21
+severity: medium
+---
+
+# pi-native 对比未过 P95 门槛
+
+## 现象
+
+真实 MiniMax-M2.7-highspeed 双后端对比中，`pi-native` 六例全部写出目标文件，容器 `pi-agent` 只有两例文档任务成功。按成功样本计算的 P95 仍是 `pi-native` 16.616s、容器 6.926s，比值为 2.40，超过 1.3 倍替换门槛。因此 dev 默认后端保持 `pi-agent`。
+
+## 根因分析
+
+- 时延样本只统计成功且无 P0 的用例。容器 `reasoning` 画像使用 `--no-tools`，不会把助手正文落成目标文件，四例返回 `MISSING_TARGET`，不进入 P95。容器 P95 只由两例较快的文档任务构成。
+- `pi-native` 的 P95 落在 `doc-outline`（16.616s）。同一提示在容器上是 6.926s。文档任务本身慢于 1.3 倍，不是分位数算法造成的。
+- 第一轮对比把分位索引截断成 0，两例成功时取了更快的那例，已作废。本结论使用 nearest-rank（`ceil`）后的第二轮日志。
+
+## 严重度
+
+`medium`。运行时可以继续在分支上迭代，当前默认链路未切换，容器后端仍可回退。
+
+## 关联整改
+
+- 任务：`.doc/ops/short-term/2026-09-21-go-agentx-runtime.md`
+- 报告：`.doc/test-reports/2026-09-21-go-agentx-runtime-test-report.md`
+- 后续：缩短 `pi-native` 文档轮次时延，或把门槛改成按同一成功用例配对比较后重新实测。未重新通过前不改 `AGENT_BACKEND`。
+
+## 证据
+
+- `.doc/test-reports/assets/go-agentx-runtime/ab-live.txt`
+- `.doc/test-reports/assets/go-agentx-runtime/ab-live-round1.txt`（作废的截断分位）
+
+## 开放问题
+
+- 容器结果不回传 token，本轮容器用量为 0，无法比较 token。
+- `reasoning` 画像的成功定义是否应要求容器也把正文写入目标文件。当前判定仍按两边各自的 `Result.Success` 与目标文件是否出现。

.doc/audit/2026-09-22-module-decoupling-current-state.md

@@ -0,0 +1,156 @@
+---
+title: "当前系统模块解耦现状审查"
+type: docs
+date: 2026-09-22
+source_sha: d034aa00e5785f51234b484f9dca6bf4fb037660
+task_id: modular-contract-standard-2026-09-22
+---
+
+# 当前系统模块解耦现状审查
+
+## 结论与范围
+
+当前系统属于**已有实质模块化基础，但契约一致性、数据所有权与运行隔离尚未闭合的模块化单体**。不是只有文件夹拆分：已有应用用例、共享事务、PostgreSQL outbox/delivery/inbox、独立 events 进程、PI Runner HTTP typed-result 边界。
+
+下一步收益最大的工作是统一业务入口、修正事件顺序契约、补运行时校验和资源预算。把现有相互依赖的实现全部包装为 HTTP 服务，会保留语义耦合并引入跨进程失败窗口。
+
+本报告针对固定源码 SHA，只读检查 Go/React、架构配置、迁移和部署定义。**未检查当前实际镜像/进程/数据库积压，未运行 Go/PG/PI/浏览器或故障注入测试。** 下文“实现存在”是源码证据；“可能造成”是风险推导；不宣称现网事故已复现，也不改变 FEATURE-MATRIX 或发布门禁。
+
+关联：[通用规范](../system-design/2026-09-22-generic-module-contract-standard.md)、[采用规划](../remediation/2026-09-22-modular-platform-adoption-plan.md)、[任务与验证](../ops/short-term/2026-09-22-modular-contract-standard.md)。
+
+## 分维度判断
+
+| 维度 | 已有基础 | 当前局限 | 判断 |
+|---|---|---|---|
+| 模块职责 | domain/app/server 分层，组合根 | server 认识大量实现，跨包类型泄漏 | 部分解耦 |
+| 业务入口 | docflow/stageflow/chatflow 用例 | 对话和 HTTP 同一动作存在旁路 | 需优先收敛 |
+| 数据边界 | 表 owner 清单与 UoW | 5 项 SQL 写例外、16 项路径例外 | 明确但未闭合 |
+| 事件通信 | 可靠 PG 投递与独立进程 | 顺序规则与 ADR 冲突，校验不完整 | 机制具备，语义有缺口 |
+| 并发与幂等 | claim、lease、token、DB 收据 | 慢消费者共享循环，同 ID 异载荷不校验 | 部分保证 |
+| 跨进程边界 | Web/server、PI Runner、events | 业务模块大多仍共享 server 进程/资源 | 不能宣称全模块故障隔离 |
+| 前端功能 | API/hooks 拆分 | 根状态和 setter 跨功能共享 | 文件组织优于状态边界 |
+| 工程约束 | arch-check 与契约 registry | 静态覆盖有限，不证明运行隔离 | 有工具，须明确盲区 |
+
+不提供无权重依据的“解耦百分比”。以下发现按对数据与行为的实际影响排序，而非按文件大小排序。
+
+---
+
+## A1. 事件领取规则与已接受的顺序契约相冲突
+
+**高优先级源码问题。** ADR 规定允许首个高领域版本 bootstrap，禁止把 MemoryBus 的连续版本等待搬到 PG dispatcher：`.doc/adr/2026-09-15-event-consumer-checkpoint.md:12-23`。
+
+当前 `internal/events/dispatcher.go:39-46,75-84` 采用 `version <= checkpoint + 1`；无 checkpoint 时只接纳版本 0/1。生产者 `internal/app/docflow/commands.go:182-185` 使用 document record ID，`:211-214` 使用 candidate ID，`:162-165` 使用文档账本版本。这些不是从 1 开始连续的事件序号。
+
+因此在“无 checkpoint、第一条版本为 42”这一明确条件下，该事件按 SQL 不能被领取。是否已有这种实际积压未查数据库，不能报成现网观测。
+
+现有 `internal/events/pg_test.go:18-28` 固化同样 gap 规则；`dispatcher_pg_test.go:105-109` 使用 v1/v2，不能覆盖稀疏首事件。
+
+**建议验收**：真实 PG 下测试首次 v42、v42→v47、部分事件订阅、毒消息隔离；按既有 ADR 恢复 bootstrap，或经明确新 ADR 引入独立事件序列及迁移。通用规范对应 MCS-15。
+
+## A2. 同一批准动作存在 HTTP 与对话入口分叉
+
+**高优先级待验证风险。** HTTP `internal/server/handlers.go:793-808` 调用 `docflow.Commands.Approve`，后者在 `internal/app/docflow/commands.go:173-188` 执行 UoW 与 EventApproved。
+
+对话 `internal/chat/action_executor.go:68-76` 直接调用 GovernanceEngine.ApproverApprove；`internal/app/app.go:294-307` 已不再注册旧通知/批准 hook，`internal/docgov/engine.go:957-960` 的直接路径仅尝试旧 hook。
+
+源码证明入口路径不同，存在绕过 durable workflow_advance/notify 的风险；本次未执行真实对话批准，不能把完整用户后果记为已复现。
+
+**建议验收**：同一授权场景分别从 HTTP、对话、后台任务触发，比较授权拒绝、状态提交、事件、工作流推进与通知，所有入口汇入同一用例。通用规范对应 MCS-04。
+
+## A3. 契约登记尚未成为完整运行时校验
+
+`internal/events/registry.go:28-52` 登记 producer、consumer、schema、PayloadFields；`:75-91` 主要检查启用与消费者。
+
+`internal/events/envelope.go:65-85` 检查基础字段、schema、digest/scope，但不按事件逐项校验 producer allowlist、JSON 必填/类型/额外字段。`internal/events/pg.go:32-47` 依赖此验证。`inventory.go:29-63` 也未完成 payload 结构检查。
+
+实际 `internal/app/docflow/commands.go:279` 的 Producer 为 `docflow`，registry 示例为 `app/docflow`（`registry.go:42-46`），当前路径不会因此拒绝。消费 hydration `dispatcher.go:204-224` 与 handler 调用 `worker.go:252` 也不能证明所有入口统一重新校验。
+
+**建议验收**：未知事件/schema、伪造 producer、缺必填、异类型、超大 payload、digest/tenant/environment 不符均有发布和消费负例。通用规范对应 MCS-08/09/18/21。
+
+## A4. 消费者逻辑独立，但资源执行仍串行共享
+
+`internal/events/worker.go:99-113` 逐一 RunOnce 各消费者；`:137-147` 一批先 claim 再逐个 handle。心跳直到该条 handle 才启动（`:208-234`）。
+
+慢消费者会延迟同 worker 的其他消费者；预取队尾还可能在开始处理前耗掉 lease。增加副本能缓解吞吐，不证明消费者有独立预算和公平性。当前可隔离永久错误，不等于慢任务也隔离。
+
+**建议验收**：阻塞一个消费者、保持另一个持续输入，后者满足自己的延迟预算；批量排队超过租期时不允许并发重复副作用。先按空闲槽 claim，并配置每消费者超时、并发、池配额；高风险任务再进程隔离。对应 MCS-14/17。
+
+## A5. 去重与健康检查不能被扩大解释
+
+`internal/events/pg.go:43` 对相同 event_id 使用 DO NOTHING，未比较已有 payload digest。因此“重复 ID 被忽略”并不保证“同键异载荷会冲突”。
+
+`cmd/events/main.go:91-115` 的 health、ready、live 分别关注进程、DB/schema/注册条件、调度心跳；`worker.go:109-112` 在处理前 Touch 且忽略 RunOnce 返回错误。Compose healthcheck 使用 /health（`docker-compose.dev.yml:170-175`）。
+
+**建议验收**：同 ID 同内容返回既有结果、不同内容冲突；依赖持续失败时最老消息年龄和分消费者失败数告警，不能依靠健康探针证明业务前进。对应 MCS-13/19/20。
+
+---
+
+## B1. 组合根、契约类型与实现仍相互渗透
+
+优点：`internal/app/app.go:96` 集中装配，`internal/server/server.go:87` 接收 runtime。限制：`server.go:40-84` 持有领域具体服务、pool、上下文等，`:123-132` 还回填 Runtime 并初始化执行器。HTTP 适配器获得整个 Runtime，难以维持最小依赖。
+
+`internal/app/stageflow/usecase.go:10-37` 是窄端口且未配置时 fail closed，但 `types.go:3-15` alias 到 bizdev 模型。`internal/app/chatflow/ports.go:75-106` 返回 ctxmgr/coordinator/projectinstance 具体类型。接口改变了调用位置，仍未彻底隐藏内部模型。
+
+本次 server 生产 SQL 搜索未发现真实业务 SQL，**不能把持有 pool 等同于已经直接越权写表**。改造重点是缩小可用能力与未来变更影响，不虚构违规。
+
+## B2. 单写者有登记，仍有明确例外
+
+`.doc/system-design/module-boundaries.yaml:276-374` 登记表 owner，`:471-511` 登记 5 项 SQL 例外。
+
+源码确认：`internal/docrevision/pg_store.go:456-477` 更新 freeform_documents/document_records；`internal/docduty/store.go:144`、`revoke.go:154` 修改 document_records；`internal/projectinstance/store.go:920` 更新 task_runs。
+
+建议通过 owner repository/用例端口逐项归还写权，保留必需事务边界。不得为了删除一个 import，把同一 SQL 移到万能公共 repository。
+
+## B3. 共享事务值得保留，不能随意替换为网络调用
+
+`internal/app/docflow/commands.go:88-112` 使用 UoW 与 owner GetForUpdate；`internal/docrevision/pg_store.go:482-491` 加入同一事务；`internal/app/uow/pg_uow.go:52-80,95-124` 提供有界事务重试、锁等待和提交。
+
+`internal/app/app.go:269-275` 接入 events.PGSink，`internal/events/pg.go:17-58` 拒绝无 UoW 发布并同事务创建 envelope/delivery。这是实质强一致性能力。若以后拆进程，必须重新定义跨域中间态、补偿和对账，不能用分布式锁替代事务。
+
+## B4. 文件与前端状态也构成模块间隐式协议
+
+文件证据：`internal/coordinator/context.go:456-459` 读取 output.md；`engine.go:691-701,895,1051` 读写/拼接共享产物路径；`internal/docgov/lease.go:415-416` 写 projection 文件。文件 owner、不可变引用、版本与发布原子性应与数据库同样治理。
+
+前端证据：`web/src/App.tsx:130-170,1163-1204,1367-1406` 将消息、交付物、缓存及 setter 传给多个功能 hooks；`useSendMessage.ts:85-121` 可修改多个域状态。建议 owner 管理状态、对外命令/查询/事件；浏览器内无需强制 HTTP。
+
+`web/src/api/authHeaders.ts:27-44` 已有认证辅助，但 chatStream、taskRuns、docgov 等仍各自 fetch。统一 client 应处理通用超时、错误、取消与身份，功能 DTO 继续分域。
+
+## B5. 静态架构检查有价值，但证明范围有限
+
+`internal/archtest/scan.go:38-70` 默认只扫 internal 生产 Go；`:169-205` 检查 import allowlist 和登记表的 SQL 字符串。它不涵盖前端、默认 cmd 范围、动态 SQL 完整语义、实际权限、兼容性和资源隔离。
+
+`scan.go:18,392-410` 的事件匹配范围主要为 document.* / intent.plan.* 和特定调用模式，不能根据 YAML 中存在 taskrun/fav 就假定每条协议都被检查。
+
+`module-boundaries.yaml:182-225` 仍允许 server 依赖大量领域；`:641-651` 登记 sql_write=5、path=16 基线。**这是读取到的配置，不是本次 arch-check 执行结果。**
+
+---
+
+## 可保留的隔离与演进能力
+
+- 独立 worker：`cmd/events/main.go:68-89,127-130` 注册 notify/advance/projection，FAV 明确不注册；Compose 已有 events 服务。历史“没有独立 worker”的判断已过时。
+- 领取与确认：`dispatcher.go:49-97,163-200,227-259` 有原子 claim、owner/token、attempt、inbox/checkpoint；旧 ClaimIDs 已禁用。
+- DB 效果原子性：`worker.go:247-275` 的 handler、fenced ack、commit 同事务；仅适用于参与同一 DB 事务的效果，不能扩展为任意外部 IO。
+- 消费者实现：`internal/app/docproject/consumer.go:73-94` 使用事件回执与 no-replace；`docadvance/consumer.go:80-104` 使用同事务推进与通知。
+- 冻结执行输入：`internal/workflow/runtime/orchestrator.go:27-41,69-85` 从冻结实例取职责，缺失时拒绝，可泛化为任务绑定配置/契约版本。
+- PI Runner：`internal/agent/piagent.go:145-194` 有 HTTP/Bearer、超时、run_id、typed result 和大小限制；`remote_result.go:63-79` 对存在但非法 typed 字段 fail closed。
+
+## 测试证据边界
+
+以下是已有测试定义，不是本次 PASS：
+
+| 路径 | 已有测试意图 | 本次状态 |
+|---|---|---|
+| internal/app/docflow/same_tx_pg_test.go | 状态与 outbox 同事务回滚 | 未运行 |
+| internal/events/dispatcher_pg_test.go | 多 worker、off/shadow、ack、隔离 | 未运行 |
+| internal/app/docnotify/e1a_pg_test.go | 通知权限、shadow/live、回滚 | 未运行 |
+| internal/app/docadvance/e1b_pg_test.go | 工作流事件消费 | 未运行 |
+| internal/app/docproject/e1c_pg_test.go | 投影与 no-replace | 未运行 |
+| internal/agent/piagent_typed_e2e_test.go | 条件启用的真实 PI | 未运行 |
+
+PG 测试在 short 或缺少独立 DSN 时可跳过；PI 测试有显式开启条件。建议新增 A1–A5 的针对性场景，再做受影响用户入口验收。未经授权，本次不启动这些实现或共享环境测试。
+
+## 与原方案的关系
+
+继续引用 2026-09-20 A–G 分批整改作为现有依赖收敛清单，不能据此宣称原批次已经完成。A1–A5 是本次新增或细化的源码证据，实施时应并入同一治理链，避免开第二套互相冲突的解耦项目。
+
+原规范保留模块化单体，本次通用规范允许按条件选择进程/服务隔离。两者分别用于“当前项目生效规则”和“未来项目待采纳标准”，没有自动覆盖关系。

.doc/audit/2026-09-23-historical-issue-records.md

@@ -0,0 +1,27 @@
+# 历史问题补录：可选职责与正文哈希
+
+补录日期：2026-09-23；owner：Codex；登记任务：[issue-learning-2026-09-23](../ops/short-term/2026-09-23-issue-learning.md)。这是两个问题的登记主记录，原审计、修复任务及验收报告继续作为事实证据；没有重新运行产品测试或读取业务数据。`evidence_basis=historical`，当前运行状态未复测，源码复核基线为 `2fdb6e548e3784771f27e6a9e79b9c364f76c566`。
+
+## nullable-duty
+
+- issue_id：`ISSUE-20260923-nullable-duty`；issue_state：`resolved`；severity：high；recurrence_count：0（指登记后重开次数，非历史发生总数）。
+- 发现/修复日期：2026-09-17；原处理 owner：Cursor；补录 owner：Codex；原任务：`fix/docgov-optional-duty-null-fk`。
+- 现象与已证实根因：[原审计](2026-09-17-docgov-optional-duty-null-fk.md)。可选 reviewer 缺席合法返回 0，但创建路径直接写入可空 FK；heal 路径已有空值映射，创建路径漏改。底层 FK 又被错误分型掩盖。
+- 同类范围：可选职责的创建/heal 写入边界。历史报告验证 reviewer/approver 为 NULL；不能由此推断所有 FK、全职责模式和全部授权边界均已验证。
+- 修复思路：保留可选职责语义，在 SQL 边界将缺席值映射 NULL，并改善错误分型；通过强制配置 reviewer 绕过错误会改变业务契约。未发现其他尝试的实测记录，不虚构失败实验。
+- 修复经过/提交：[原任务](../archive/ops/2026-09-17-docgov-optional-duty-null-fk.md)，历史合并 `e488d10`；本次只核对原文记录，不把短 SHA 当当前制品身份。
+- 验证与关闭范围：[原报告](../test-reports/2026-09-17-docgov-optional-duty-null-fk-test-report.md) 记录单测、PG 集成、真实任务 API 启动与 DB NULL；证明账本创建通过，不证明真实 UI 或 PI 全流程完成。历史 deployment=passed（dev，来源为原报告），当前运行未复测。
+- 本次复核：当前源码 `internal/docgov/engine.go` 创建路径仍调用 `nullIfZero`；这是源码检查，未重跑 PG。
+- 经验：[LESSON-20260923-nullable-duty](../ops/lessons/2026-09-23-nullable-duty.md)。后续触发：职责模型或任一持久化入口变化时复核，异常复发重开。独立的 flushSync 警告不在本条关闭范围。
+
+## content-hash
+
+- issue_id：`ISSUE-20260923-content-hash`；issue_state：`resolved`；severity：critical；recurrence_count：0（登记后）。
+- 发现/修复日期：2026-09-14；原处理：Cursor 修复、Antigravity UI 验收；补录 owner：Codex。
+- 现象与因果链：[原审计](2026-09-14-project143-controlled-content-404.md)。文件存在却被报 404；规范化去掉有硬换行语义的双空格，bootstrap 只改账本哈希未同步文件；并发 hydration 与无效轮询更新放大故障。
+- 同类范围：旧文档 bootstrap、规范化、账本/文件投影、错误映射与刷新竞态。历史扫描范围见原审计，不扩大为所有数据无问题。
+- 修复思路/选择：[整改方案](../remediation/2026-09-14-controlled-content-canonical-hash-remediation.md)。保持文本语义、原子投影和结构化错误；历史原文件与旧 head 先保全再显式 migration_repair。静默覆盖原文件会丢失语义，不能用于“对齐哈希”。这不是本轮数据操作授权。
+- 修复经过：[原审计关闭结果](2026-09-14-project143-controlled-content-404.md#关闭结果) 与 [最终报告](../test-reports/2026-09-14-controlled-content-ui-acceptance.md)；后续水合/缓存修复合入 `d0e8f60`、`36e4bc3`。报告保留早期失败及无效运行，只有 clean-run3 / full-chain-final 属最终有效证据。
+- 验证与关闭范围：原报告记录旧项目真实页面、全链路主阶段和重启恢复 PASS；历史 deployment=passed（dev）。不据此宣告当前 production_ready 或当前制品无回归。
+- 本次复核：`internal/docrevision/canonicalize.go` 已委托 doccontent；`canonicalize_golden_test.go` 包含硬换行和封装一致性测试。本次未执行这些测试。
+- 经验：[LESSON-20260923-content-hash](../ops/lessons/2026-09-23-content-hash.md)。后续触发：canonicalizer、bootstrap、投影或水合修改时复核；复发追加时间线并重开。

.doc/audit/2026-09-23-matrix-status-regression.md

@@ -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。

.doc/audit/ISSUES.md

@@ -0,0 +1,12 @@
+# 问题与修复台账
+
+维护规则：[问题记录与开发经验闭环](../ops/2026-09-23-issue-learning-workflow.md)。每个问题一个稳定 ID；主记录是事实与状态来源，本表为可检索投影。新发现及时登记，修复后保留记录；发布 blocker 仍见 [gap-matrix](../remediation/gap-matrix.md)。
+
+更新：2026-09-23。本轮为初始建库，仅补录两个历史案例；下列历史 resolved 不表示本日运行回归通过。
+
+| issue_id | 模块 / 检索词 | 问题 | 严重度 | issue_state | owner | 证据日期 / 范围 | 唯一主记录 | 经验 |
+|---|---|---|---|---|---|---|---|---|
+| 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) |

.doc/ops/2026-09-21-agent-worktree-workflow.md

@@ -121,13 +121,34 @@ validate 要求干净树、记录精确 HEAD 与命令摘要；必要的实际
 
 任务状态、集成、部署、远端同步和 cleanup 分别记录，见[收口清单](./templates/session-close-checklist.md)。命令结束不等于任务完成；task close 会拒绝仍有运行或待恢复 operation 的任务。
 
+### 8.1 只读盘点（先盘点，再人工处置）
+
+```bash
+# 批量 worktree 清理就绪度；verdict=ready 才可考虑 remove。从不自动删除。
+./scripts/agentctl cleanup report
+
+# FEATURE-MATRIX 状态漂移：硬告警仅 done→非 done（ISSUE-20260923 工具化）；
+# open_capabilities 为人工判断候选。从不自动升 done / 写 MATRIX。
+./scripts/agentctl docs drift
+```
+
+daemon 前台循环可按 `--audit-every N`（默认 30）周期跑上述盘点；**不在 daemon 内调用 `docs apply`**（主目录 cwd 必 `WORKTREE_MISMATCH`）。常驻 systemd/launchd 装载需独立授权，本规范默认不装载。
+
+### 8.2 关闭与删除
+
 ```bash
 ./scripts/agentctl task close --id task-id --status done
 ./scripts/agent-worktree.sh remove feature/task-id --delete-branch
 ```
 
-清理由目录外的维护者执行，核对实际 Git 映射、dev 祖先、所有证据、tracked/untracked/ignored 文件、未完成 Git 操作、registry、生命周期锁和使用目录的进程。只用普通 remove/-d，拒绝时保留 cleanup_pending 和复查责任，不换成强制删除。
+清理由目录外的维护者执行，核对实际 Git 映射、dev 祖先、所有证据、tracked/untracked/ignored 文件、未完成 Git 操作、registry、生命周期锁和使用目录的进程。只用普通 remove/-d，拒绝时保留 cleanup_pending 和复查责任，不换成强制删除。盘点只读；删除仍人工；拒绝即保留 cleanup_pending。
 
 **本机限制**：无法读取某些同 UID 进程 cwd 时，工具不能证明其未使用目录，故保留 cleanup_pending；明确识别的 OS 用户 launchd（macOS）/systemd（Linux）管理进程有诊断性例外。进程 cwd 可见性走双路径：Darwin 用 `lsof`，Linux 用 `/proc`；测试中的删除正例可替换对应枚举以模拟可见主机，其余 Git/锁/文件条件为真实执行；可见占用、未知不可读、未合入、脏文件与活跃登记的拒绝另有真实/针对性测试。不要把这项限制转成跳过检查的通用开关。
 
 保护任务、旧 detached 工作区和非本次产物不自动清理。用户未要求 push 时仅本地提交/合入；用户已要求时再按授权同步并核对远端引用。
+
+### 8.3 CodeGraph（治理加速器）
+
+- `agentctl init` 与 `agent-worktree.sh create` 会 best-effort 初始化/同步 `.codegraph/`（CLI 缺失则跳过，不阻断）。
+- `hooks install` 安装 `post-merge` / `post-checkout` → `hooks codegraph-sync`（fail-open，永不阻断 integrate）。
+- 会话启动执行 `codegraph sync -q`。索引是 tree-sitter **近似**：有假阴性；**grep 是完整性唯一权威**；重命名与穷举调用方必须 grep 确认。

.doc/ops/2026-09-21-policy-registry.md

@@ -27,3 +27,21 @@ CURRENT 是带时间的活跃协调快照；Git/机器状态用于核验实际
 ## Herdr v1.2 局部修订
 
 用户已授权采纳经研究修正的资源分工与自动审批。Herdr roster 的角色/额度/客户端参数由 `herdr-v1.2` 取代旧路由，仅在明确使用 Herdr 时激活，不扩展通用会话工作流。具体来源、验证与生效集成见[本轮任务](../archive/ops/2026-09-21-herdr-orchestration-v12.md)。已通过 dev 合并提交 `8c5e3477585fe27a485343dac97a670d95cf8905` 生效；profile/dry-run、入口保护和 Kimi 原子计数有隔离验收，真实 Herdr pane 启动未在本轮执行，不将其记为已实测。
+
+## 系统问题分析局部修订
+
+修订 ID：`systemic-issue-analysis-2026-09-23-r1`；owner：`Codex`；state：`active`（已通过 `958dd44fee8bbea8d19129457fc0ad749fdebdbe` 合入 dev）；工具能力：`manual`。用户明确要求将“由个案追查同类根因、潜在问题，研究并提出方案”加入规范，授权与验证见 [任务记录](./short-term/2026-09-23-systemic-issue-analysis.md)。
+
+核心行为唯一来源为 [AGENTS 分析要求](../../AGENTS.md#bug-与系统问题的分析要求)，验证范围由 [验证契约](./2026-09-21-validation-contract.md#问题修复的回归范围) 定义，[分析模板](./templates/audit-note.md) 承载证据。客户端继续引用统一入口。生效提交为 `958dd44fee8bbea8d19129457fc0ad749fdebdbe`，候选验证与受控集成收据见任务记录；不新增业务实施或环境操作授权。
+
+## 问题记录与经验复用局部修订
+
+修订 ID：`issue-learning-2026-09-23-r1`；owner：Codex；state：`active`（已通过 `7bbd7a407f857515005c0324d90339017ea5f3e8` 合入 dev）；执行能力：`manual`。用户要求同时管理出现的问题、修复记录和思路，并及时总结为开发注意事项，授权与验证见 [任务](short-term/2026-09-23-issue-learning.md)。
+
+[闭环规范](2026-09-23-issue-learning-workflow.md) 为本流程唯一来源；AGENTS 增加按任务触发的读取/更新入口，模板承载证据，问题台账和经验索引提供检索。生效提交为包含本修订的首个受控 dev 集成提交，以任务收据与 Git 父链核实；未合入不能声称全仓生效。此修订不新增产品功能、自动门禁或运行权限。
+
+## CodeGraph 与只读盘点局部修订
+
+修订 ID：`codegraph-governance-2026-09-24-r1`；owner：`Cursor`；state：`active`（生效 tip `19eb56e3744d3c7d4b69b065c87e27689e8caa53` / fixup `0c676afe1faf831020c7c3201509d7cec0328d53`）；工具能力：盘点命令与 hooks sync 为 `enforced`（脚本已落地）；常驻 daemon 装载仍为 `manual`（本机默认不装载）。用户授权：将 CodeGraph 纳入治理启动/建场/sync，并对 worktree 清理与 FEATURE-MATRIX 做只读盘点提醒（不自动删除、不自动升 done）。
+
+唯一来源增补：[AGENTS §1/§4](../../AGENTS.md)、[worktree 操作规范 §8](./2026-09-21-agent-worktree-workflow.md)、[收口清单](./templates/session-close-checklist.md)。命令入口：`agentctl cleanup report`、`agentctl docs drift`、`agentctl hooks codegraph-sync`、建场 `agent-worktree.sh create` 的 best-effort `codegraph init`。不改产品 SWBOOT-10 stub，不装载 systemd coordinator（需另授）。

.doc/ops/2026-09-21-validation-contract.md

@@ -15,6 +15,12 @@
 
 多类变更取并集。按 [模块开发标准](../system-design/2026-09-20-module-development-standards.md) 追加边界与 registry parity 等范围门禁。开发阶段可用 stub；交付验收不能冒充真实执行。纯文档无需产品 PI 或全量 Go，也不为形式重建服务。
 
+## 问题修复的回归范围
+
+Bug/系统问题修复先按 [AGENTS 分析要求](../../AGENTS.md#bug-与系统问题的分析要求) 确定问题类别和影响范围，再从上表选择验证层级。验收须包含：原始复现案例；通过同一机制的其他输入、措辞或入口；相关边界/异常路径；应保持不变的正常行为。场景按实际因果链选择，不机械穷举；不适用或未覆盖的项记录理由与风险。
+
+验证机制和预期行为，不以硬编码原句、固定回复文本或单个样例通过代替回归。能在修复前复现失败的场景记录修复前后对照；不能复现时说明证据限制。报告逐项区分通过、失败、未运行与待验证；只提供分析/方案时列出验收设计，不声称已经运行或修复。
+
 ## 产品 PI 基线与精确追加
 
 优先入口：`./scripts/run-nightly-real-pi.sh`。调用前核验并从获授权配置提供（不在命令/报告贴凭证值）：

.doc/ops/2026-09-23-agentctl-cursor-integration.md

@@ -0,0 +1,38 @@
+---
+title: "agentctl Cursor 能力层（skills / MCP / rules / hooks）"
+status: active
+created: 2026-09-23
+updated: 2026-09-23
+owner: Cursor
+task_id: agentctl-cursor-integration-2026-09-23
+---
+
+# agentctl Cursor 能力层
+
+把已上线的 agentctl 管理面包装为 Cursor 原生能力，使 agent 默认走租约 / docs 收据 / 候选合入。
+
+## 能力清单
+
+| 层 | 路径 | 作用 |
+|---|---|---|
+| MCP | [`.cursor/mcp.json`](../../.cursor/mcp.json) → [`scripts/mcp/agentctl-mcp.mjs`](../../scripts/mcp/agentctl-mcp.mjs) | `status` / `task_*` / `lease_run` / `docs_*` / `validate` / `queue_enqueue` / `quarantine_status` |
+| Skills | [`.cursor/skills/agentctl-*`](../../.cursor/skills/) | 会话启动、建场、租约写、集成收口 |
+| Rule | [`.cursor/rules/agentctl-mandatory.mdc`](../../.cursor/rules/agentctl-mandatory.mdc) | alwaysApply：强制走 agentctl |
+| Hooks | [`.cursor/hooks.json`](../../.cursor/hooks.json) + `guard-git.sh` | `git push` / 破坏性 git → `permission: ask` |
+
+权威规则仍是 [AGENTS.md](../../AGENTS.md) 与 [操作规范](./2026-09-21-agent-worktree-workflow.md)；本目录不复制全文。
+
+## 启用
+
+1. 合入 local `dev` 后，在 Cursor 中 **Reload Window** 或重载 MCP。
+2. 确认 MCP 服务器 `agentctl` 出现在工具列表；hooks 出现在 Cursor Hooks 设置页。
+3. 会话开始跟 skill `agentctl-session-start`（核对 `daemon status`）。
+
+## 与管理面关系
+
+- launchd `com.agentctl.coordinator` 持续 `queue schedule`；本能力层只封装 CLI，不替代 daemon。
+- git hooks（pre-commit / pre-merge / reference-transaction）仍由 `agentctl hooks` 管理，与 Cursor `beforeShellExecution` 互补：前者执行租约/候选门禁，后者拦未授权 push/强推。
+
+## 非目标
+
+不 push；不晋升 test/main；不改 gap-matrix；不卸载 daemon。

.doc/ops/2026-09-23-issue-learning-workflow.md

@@ -0,0 +1,61 @@
+# 问题记录与开发经验闭环
+
+修订：`issue-learning-2026-09-23-r1`；owner：Codex；生效条件见 [规范登记](2026-09-21-policy-registry.md)。执行能力为 `manual`：依靠 Agent 读取、任务记录与审查；本轮没有增加自动检索、CI 阻断或模型训练。
+
+## 入口与职责
+
+| 入口 | 回答的问题 | 权威边界 |
+|---|---|---|
+| [问题台账](../audit/ISSUES.md) | 出现过什么问题，目前处理到哪一步？ | 索引和状态投影；事实、修复经过以链接的唯一问题主记录为准 |
+| 问题主记录 | 为什么发生、考虑过哪些方案、改了什么、如何验证？ | 放 audit，或沿用已有任务/审计中的明确章节；使用 [问题模板](templates/issue-record.md) |
+| [开发经验](lessons/INDEX.md) | 遇到类似工作应先检查什么？ | 按机制提炼的注意事项；使用 [经验模板](templates/development-lesson.md)，不替代现行规范 |
+| CURRENT / FEATURE-MATRIX / gap-matrix | 当前协调 / 能力 / 发布门禁 | 维持原职责；只有对应状态改变才更新 |
+
+修复方案、任务、提交、验收报告通过链接串联，已有材料直接复用。一个 task 可处理多个 issue，一个 issue 可跨分析/实施任务；研究任务 done 不等于问题 resolved。一个 lesson 可覆盖多个同根因 issue。短问题可在任务主文档内记录，无需机械创建一套文件。
+
+## 何时记录、检索和总结
+
+1. **设计、编码、排障或运维前**：按模块、路径、错误码、症状和共用机制检索问题台账及经验索引。先查索引、再读命中条目的来源；核对当前源码/规范是否仍适用。在任务记录填写检索词、命中 ID、采纳的检查；无命中明确记录。简单信息答复不要求建任务或检索整库。
+2. **首次发现问题时**：在当前任务 worktree 建立或补充问题主记录和台账行，记录预期/实际、影响、环境/版本、owner、下一步及证据缺口；尚未定位也可以登记。ID 使用 `ISSUE-YYYYMMDD-<slug>`，日期为登记日；发生日期另列，跨 worktree 以语义 slug 避免抢序号。
+3. **定位、改方案、完成修复或发现验收失败时**：在同一主记录追加时间线和尝试结果；保留被否定假设、失败方案及不适用条件，区分观察、推测和已证实根因。按 [问题分析要求](../../AGENTS.md#bug-与系统问题的分析要求) 检查共用机制和同类入口。
+4. **根因与修复得到验证后、任务收口前**：提炼经验或更新已有同机制经验，并链接回问题。若尚无验证证据，只能建 `candidate`；若没有新增可复用结论，记“不新增经验”及理由，仍保留问题记录。分析-only、未修复或验收失败的问题继续留在台账。
+5. **经验落到开发动作**：写清触发条件、机制、应做检查、错误做法及原因、验证方法、适用边界。优先链接现有测试/约束；需要新增回归、lint、架构门禁或规范时，在当前授权内实施，超出授权则记录 owner/后续任务。仅提出自动化建议不能标为已落实。
+6. **复发或规则变化时**：同一故障未解决的复现追加原 issue；已关闭问题再次出现，重开原 issue 为 `investigating`，递增 `recurrence_count` 并保留原关闭证据。不同根因建立新 issue 并互相链接。复盘为何已有经验/测试未生效：未检索、范围不适用、遗漏入口、检查未执行或实现回退，并更新防护。模块/接口/规范变化时复核命中经验；确认过时标 `superseded` 并链接替代条目，无替代则 `retired`，保留历史。
+
+检索示例（在任务工作区执行，替换为本任务关键词）：
+
+```bash
+rg -n -i 'docgov|nullable|23503|职责' .doc/audit/ISSUES.md .doc/ops/lessons
+```
+
+owner 在上述里程碑及时更新，最迟在会话交接前保存事实和未完成项；不依赖定时服务。经验不会自动改变模型参数，作用是让后续 Agent 能检索、有证据地复用，并逐步把重复风险转换为可执行检查。
+
+## 问题状态与关闭条件
+
+问题的 `issue_state` 与任务 `status` 分开；台账保留当前投影，主记录保留变迁历史。
+
+| issue_state | 含义 / 转移要求 |
+|---|---|
+| open | 已登记，等待定位 |
+| investigating | 正在复现、验证假设和范围 |
+| fixing | 修复方案明确且已获实施授权 |
+| verifying | 修复待验收，或必要证据尚缺 |
+| resolved | 约定范围的修复、必要环境验收均有证据，经验已总结或有不新增理由 |
+| deferred | 暂缓处理；保留风险、责任人、复查触发和授权/决策依据，不冒充修复 |
+| duplicate | 指向唯一主 issue，保留原报告和去重理由 |
+
+定位失败可保留 investigating；临时止血不代表 resolved，必须标清剩余根治项。验证失败回到 investigating/fixing，不能覆盖失败记录。关闭至少能追溯：根因、同类范围、修复提交或获授权的处理动作、原例/变体/正常行为验收及缺项、实际部署状态、lesson 或不新增理由。业务改动待部署时不能把目标环境问题关闭；无需部署写 not_required。
+
+**历史补录**：发生日、修复日和补录日分开。只按旧报告已证明的范围记录 `resolved`，同时标 `evidence_basis=historical` 和当前运行未复测；缺乏关闭证据用 `verifying` 并说明原因，不从旧任务 done 推导修复完成。历史条目不能用于宣布当前系统就绪。本轮仅补录两个有来源案例，不代表穷尽全部历史问题。
+
+## 经验质量与维护
+
+`lesson_state`：`candidate | validated | superseded | retired`。validated 表示注意事项有可核对的因果证据且已复核适用边界，不表示所有模块或当前线上均测试通过。需记录 reviewer、last_reviewed、reviewed_revision、来源 issue、证据日期、关键词、关联测试、适用/不适用范围及仍缺的防护。
+
+同机制优先更新已有 lesson，保留修订记录；新机制才新增 `LESSON-YYYYMMDD-<slug>`。将通用经验升级成强制规范时，只在对应规范的唯一来源修改并登记生效条件，经验条目保留理由与链接。经验与现行规范冲突时先按有效规范执行，登记冲突与复核项；历史经验不能授予数据修复、部署或扩大范围的权限。
+
+## 并发、验收与敏感信息
+
+所有写入沿用 [worktree 操作规范](2026-09-21-agent-worktree-workflow.md)。问题/经验索引使用各自 `path:` 短租约；当前 `agentctl docs apply` 仅覆盖 CURRENT/FEATURE-MATRIX，不宣称新索引有行级 CAS。写入前读最新内容、只改自己的条目；从旧 dev 分出的工作区在集成前合并最新 dev 并处理索引冲突，保留他人条目。索引和主记录在同一逻辑提交同步，避免状态分叉。
+
+文档验收包括链接/锚点、ID 唯一、主记录与索引状态一致、来源及日期、入口/模板可达和情景检查。运行回归按 [验证契约](2026-09-21-validation-contract.md)；未运行、缺项与历史证据单独标明。只保留足够判断的脱敏证据，业务正文、凭证和个人数据不复制进经验库。

.doc/ops/CURRENT.md

@@ -1,43 +1,19 @@
 # 当前焦点
 
-**更新**：2026-09-23（DOCREV UI PASS + FEATURE-MATRIX A–G done / 红线证据入账）。此文件是协调快照；实际分支、进程、执行租约以机器核验为准。能力和发布结论分别见 [FEATURE-MATRIX](../status/FEATURE-MATRIX.md) / [gap-matrix](../remediation/gap-matrix.md)。
+**更新**：2026-09-22（dev 门禁复验与 test 晋升收口）。此文件是协调快照；实际分支、进程、执行租约以机器核验为准。能力和发布结论分别见 [FEATURE-MATRIX](../status/FEATURE-MATRIX.md) / [gap-matrix](../remediation/gap-matrix.md)。
 
-本机 macOS 已可用 `agentctl with`/`docs apply`/`validate`/`integrate`（W1-B 进程层）；共享文档写走 docs apply 收据。
+手工 CAS 前：本 macOS 宿主 `docs apply`/`with`/`validate`/`integrate` 因 `/proc` 不可用；本轮文档与环境写采用手工等效（见任务例外登记）。
 
 ## 焦点
 
-0. **全量未完成计划收口**：FEATURE-MATRIX「模块解耦批次 A–G」→ `done`；多意图 I1 / 语义摘要 S1 / 治理 W4 / rdev / 红线证据已登记残差；红线（FAV live / SWBOOT-10 / D7 物理删 / PI 叙事 flag）不放量。详见 [收口短文](./short-term/2026-09-22-unfinished-batch-closeout.md)。
-
-1. **DOCREV UI 重跑已 PASS**：main 18 + post-restart UI-15；20 audit + 9 remediation `done`（`management-implementation-plan` 仍方案态）。schema 63；密封 [sealed-ledger-ui00-16-post-20260923T0400Z](../test-reports/assets/2026-09-22-docrev-ui-rerun/sealed-ledger-ui00-16-post-20260923T0400Z/)；证据 [测试报告](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md)；worktree cleanup=pending。
-
-2. **dev→test 已晋升**：`origin/dev@591ea601`（schema 61 门禁绿）；`origin/test@83c6a12a` + tag `rc-v1.1.0-beta.1`；test 环境 health schema=61、Runner `MiniMax-M3`。[报告](../test-reports/2026-09-22-dev-gate-and-test-promotion-test-report.md)。
-3. **本任务 cleanup=pending**：feature / integrate / promote-test worktrees 待独立维护者按门禁复查后清理；不强删。
-4. **Agent 规范与 L1 门禁**：R01–R10、共享 .locks 已启用；本机 macOS 租约路径可用（Darwin 进程层已落地），与 Linux 双平台 enforced。
+1. **dev→test 已晋升**：`origin/dev@591ea601`（schema 61 门禁绿）；`origin/test@83c6a12a` + tag `rc-v1.1.0-beta.1`；test 环境 health schema=61、Runner `MiniMax-M3`。[报告](../test-reports/2026-09-22-dev-gate-and-test-promotion-test-report.md)。
+2. **本任务 cleanup=pending**：feature / integrate / promote-test worktrees 待独立维护者按门禁复查后清理；不强删。
+3. **Agent 规范与 L1 门禁**：R01–R10、共享 .locks 已启用；本机 macOS 上租约路径不可用，受测 Linux 主机仍 enforced。
 
 ## 并行认领
 
 | owner | task | branch | worktree | mutex | status |
 |---|---|---|---|---|---|
-| Cursor | agentctl-mgmt-go-live-close-2026-09-23 | feature/agentctl-mgmt-go-live-close-2026-09-23 | .worktrees/agentctl-mgmt-go-live-close-2026-09-23 | agentctl-mgmt-go-live-close | done |
-| Cursor | integrate-agentctl-mgmt-go-live-2026-09-23 | feature/integrate-agentctl-mgmt-go-live-2026-09-23 | .worktrees/integrate-agentctl-mgmt-go-live-2026-09-23 | git:dev | done |
-| Cursor | agentctl-mgmt-go-live-2026-09-23 | feature/agentctl-mgmt-go-live-2026-09-23 | .worktrees/agentctl-mgmt-go-live-2026-09-23 | agentctl-mgmt-go-live | done |
-| Cursor | w3-u6-current-fix-2026-09-23 | feature/w3-u6-current-fix-2026-09-23 | .worktrees/w3-u6-current-fix-2026-09-23 | w3-u6-current-fix | done |
-| Cursor | integrate-w3-u6-closeout-2026-09-23 | feature/integrate-w3-u6-closeout-2026-09-23 | .worktrees/integrate-w3-u6-closeout-2026-09-23 | git:dev | done |
-| Cursor | integrate-matrix-record-id-2026-09-23 | feature/integrate-matrix-record-id-2026-09-23 | .worktrees/integrate-matrix-record-id-2026-09-23 | git:dev | done |
-| Cursor | w3-u6-closeout-2026-09-23 | feature/w3-u6-closeout-2026-09-23 | .worktrees/w3-u6-closeout-2026-09-23 | w3-u6-closeout | done |
-| Cursor | matrix-record-id-2026-09-23 | feature/matrix-record-id-2026-09-23 | .worktrees/matrix-record-id-2026-09-23 | matrix-record-id | done |
-| Cursor | w2-closeout-2026-09-23 | feature/w2-closeout-2026-09-23 | .worktrees/w2-closeout-2026-09-23 | w2-closeout | done |
-| Cursor | current-projection-2026-09-23 | feature/current-projection-2026-09-23 | .worktrees/current-projection-2026-09-23 | current-projection | done |
-| Cursor | agentctl-daemon-2026-09-23 | feature/agentctl-daemon-2026-09-23 | .worktrees/agentctl-daemon-2026-09-23 | agentctl-daemon | done |
-| Cursor | agentctl-handoff-2026-09-23 | feature/agentctl-handoff-2026-09-23 | .worktrees/agentctl-handoff-2026-09-23 | agentctl-handoff | done |
-| Cursor | agentctl-claim-2026-09-23 | feature/agentctl-claim-2026-09-23 | .worktrees/agentctl-claim-2026-09-23 | agentctl-claim | done |
-| Cursor | agent-governance-config-2026-09-23 | feature/agent-governance-config-2026-09-23 | .worktrees/agent-governance-config-2026-09-23 | agent-governance-config | done |
-| Cursor | coordination-db-daemon-impl-plan-2026-09-23 | feature/coordination-db-daemon-impl-plan-2026-09-23 | .worktrees/coordination-db-daemon-impl-plan-2026-09-23 | coordination-db-daemon-impl-plan | done |
-| Cursor | coordination-db-daemon-2026-09-23 | feature/coordination-db-daemon-2026-09-23 | .worktrees/coordination-db-daemon-2026-09-23 | coordination-db-daemon | done |
-| Cursor | integrate-pi-runner-response-size-r2-2026-09-23 | feature/integrate-pi-runner-response-size-2026-09-23 | .worktrees/integrate-pi-runner-response-size-2026-09-23 | git:dev | done |
-| Cursor | modular-decouple-residual-b-2026-09-23 | feature/modular-decouple-residual-2026-09-23 | .worktrees/modular-decouple-residual-2026-09-23 | modular-decouple-residual | done |
-| 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 | done |
-| 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 |
 | Cursor | integrate-dev-prod-ready-test-promotion-2026-09-22 | feature/integrate-dev-prod-ready-test-promotion-2026-09-22 | .worktrees/integrate-dev-prod-ready-test-promotion-2026-09-22 | git:dev | done |
@@ -49,7 +25,6 @@
 
 | 路径/事项 | 分类与保留原因 | cleanup_owner | 复查触发 |
 |---|---|---|---|
-| `.worktrees/docrev-ui-rerun-2026-09-22` / `freeform-project-id-bigint` | 任务 done；UI PASS 密封；cleanup=pending | 独立维护者 | tip 为 local_dev 祖先且无 Playwright 后 remove |
 | `.worktrees/dev-prod-ready-test-promotion-2026-09-22` 等本轮三个 worktree | 任务 done；cleanup=pending；证据已入 test-reports / gap-matrix | 独立维护者 | 核对 tip 为 origin/dev 或 origin/test 祖先、无进程后 remove |
 | Cline `2026-09-16-partial-deferred-completion` | 仍 in_progress；W5–W7 未关闭 | Cline owner / 维护者 | 单独授权实施或交接 |
 | 保护分支 / FAV 相关 | 保护项；故意不合入、不删 | 原 owner / 维护者 | 用户调整保护边界后 |

.doc/ops/evidence/2026-09-23-agentctl-cursor-integration/hooks-check.txt

@@ -0,0 +1,6 @@
+OK status -> allow
+OK push -> ask
+OK reset -> ask
+OK clean -> ask
+OK force-wt -> ask
+hooks OK

.doc/ops/evidence/2026-09-23-agentctl-cursor-integration/mcp-summary.json

@@ -0,0 +1,20 @@
+{
+  "initialize": {
+    "name": "agentctl",
+    "version": "1.0.0"
+  },
+  "tools": [
+    "status",
+    "task_register",
+    "task_close",
+    "lease_run",
+    "docs_snapshot",
+    "docs_apply",
+    "validate",
+    "queue_enqueue",
+    "quarantine_status"
+  ],
+  "status_ok": true,
+  "daemon_ok": true,
+  "daemon_held": true
+}

.doc/ops/evidence/2026-09-23-agentctl-cursor-integration/queue-retry-note.txt

@@ -0,0 +1 @@
+queue retry after parking untracked promotion receipts (DIRTY_TREE) at /tmp/ci-hold-receipts

.doc/ops/evidence/2026-09-23-agentctl-cursor-integration/skills-check.txt

@@ -0,0 +1,5 @@
+OK agentctl-session-start lines 30
+OK agentctl-worktree-setup lines 48
+OK agentctl-lease-write lines 45
+OK agentctl-integrate-closeout lines 53
+skills OK

.doc/ops/evidence/2026-09-23-agentctl-cursor-integration/unittest-summary.txt

@@ -0,0 +1,2 @@
+146:Ran 134 tests in 122.988s
+148:OK (skipped=3)

.doc/ops/handoffs/2026-09-21-agent-workflow-governance-plan.md

@@ -25,9 +25,9 @@ status: open
 | 研究 mutex | 已在本 worktree CURRENT 标记 done |
 | 共享集成槽位 | 本任务分支 CURRENT 登记文档集成；实际操作持 common-dir 下 dev-integration.lock，主目录 CURRENT 保留 |
 | branch | feature/agent-workflow-governance-plan |
-| worktree | .worktrees/feature-agent-workflow-governance-plan |
+| worktree | 原任务及候选在收口后按门禁清理；dev 文档入口暂为 `.worktrees/agent-governance-dev-integration` |
 | 起点 | 本地 dev@15b8a4a8 |
-| 合入 / push | 本次按已验证候选合入本地 dev；未 push，最终结果见规范采纳验收报告 |
+| 合入 / push | 规则提交 `048bbe4a` 已经由候选 `83e22a70` 合入本地 dev；未 push；后续收口仅文档 |
 
 ## 验证及边界
 
@@ -35,9 +35,10 @@ status: open
 - 主目录另有 Cursor 工作流作用域任务的未提交改动；保留现场，不 checkout/pull/stash/reset。
 - 当前没有自动任务协调器，分支 CURRENT 不等于全局实时认领。此次只有人工明确范围和本机 flock，不宣称自动队列或全局硬隔离已实现。
 - 收口文档允许单独审核/合入，但不能按计划已写完将治理功能改成 done。
-- 主目录仍是旧任务分支；dev 暂由 `.worktrees/agent-governance-dev-integration` 检出以安全集成文档。旧任务 owner 保存成果、确认主目录干净后，先安全移除临时 dev worktree，再在主目录切回 dev；不得强抢 dev 检出。
+- 规范首次合入后，Cursor 已把作用域修复合入 `dev@e0665ca4`，并将主目录切为该提交的 detached HEAD 进行部署。dev 仍暂由 `.worktrees/agent-governance-dev-integration` 检出；该目录当前也被 Cursor 的集成流程使用，须等其释放槽位后再清理或接管。主目录最终切回 dev 前先安全移除临时 dev worktree；不得强抢检出或修改活跃部署源。
 
 ## 相关链接
 
 - [研究任务](../../archive/ops/2026-09-21-agent-workflow-governance-plan.md)
 - [CURRENT](../CURRENT.md)
+- [采纳验收](../../test-reports/2026-09-21-agent-workflow-governance-adoption-test-report.md)

.doc/ops/lessons/2026-09-23-content-hash.md

@@ -0,0 +1,31 @@
+---
+lesson_id: LESSON-20260923-content-hash
+lesson_state: validated
+owner: Codex
+reviewer: Codex (source review)
+last_reviewed: 2026-09-23
+reviewed_revision: 2fdb6e548e3784771f27e6a9e79b9c364f76c566
+source_issues: [ISSUE-20260923-content-hash]
+keywords: [docrevision, doccontent, canonicalize, hash, bootstrap, hard-break, hydration, '404']
+---
+
+# 文本规范化必须保持语义并维护账本与文件一致性
+
+**触发**：修改 Markdown 规范化、哈希、版本 bootstrap、文件投影、正文加载或刷新缓存时。
+
+**机制与来源**：[问题主记录](../../audit/2026-09-23-historical-issue-records.md#content-hash)。去掉行尾双空格破坏硬换行语义；只更新账本哈希使原文件读取失配。统一报 404 和无效轮询更新让数据冲突难以诊断并反复呈现。
+
+**开发检查**：
+
+1. 对规范化定义允许变化和必须保留的语义，保留硬换行等差异样例；哈希一致性依赖相同语义和规范化契约。
+2. 追踪快照、记录哈希与文件投影的写入顺序和失败恢复。旧文档首次 bootstrap 与新文档创建分别覆盖，并发 content/revision 请求和刷新后读取需按实际因果链验证。
+3. 数据修复先按授权保全原文件及旧版本，显式记录修复来源；不能通过静默覆盖或跳过校验来隐藏不一致。
+4. 将不存在、完整性冲突和临时失败按协议区分。检查无变化轮询是否重复触发内容加载；失败反馈应可定位。
+
+**已有防护**：[黄金样例](../../../internal/docrevision/canonicalize_golden_test.go) 含硬换行保持及 doccontent 封装一致性；[历史真实 UI 报告](../../test-reports/2026-09-14-controlled-content-ui-acceptance.md) 覆盖旧文档、刷新和重启。2026-09-23 只核对源码与报告，未重跑；测试存在不等于在未来变更中已执行。
+
+**边界**：哈希不同不自动说明数据丢失，也不自动授权重写。不同文件格式的空白语义不同；不得把 Markdown 规则机械用于其他格式。当前制品和旧数据迁移需要各自证据，新项目 PASS 不代替旧数据验收。
+
+**未完成防护**：没有全仓扫描或新 CI 门禁；未来相关修改按验证契约运行适用用例并记录结果。
+
+**修订**：2026-09-23 从历史问题提炼，核对当前 canonicalize 委托与黄金样例；规范化/投影/缓存契约改变时再审。

.doc/ops/lessons/2026-09-23-matrix-status-cas.md

@@ -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。

.doc/ops/lessons/2026-09-23-nullable-duty.md

@@ -0,0 +1,30 @@
+---
+lesson_id: LESSON-20260923-nullable-duty
+lesson_state: validated
+owner: Codex
+reviewer: Codex (source review)
+last_reviewed: 2026-09-23
+reviewed_revision: 2fdb6e548e3784771f27e6a9e79b9c364f76c566
+source_issues: [ISSUE-20260923-nullable-duty]
+keywords: [docgov, nullable, SQL, FK, reviewer_id, '23503', heal]
+---
+
+# 可选职责在所有持久化入口保持同一空值语义
+
+**触发**：修改可选成员/职责、SQL 写入、创建/heal/import/upsert 等路径时；检查范围以实际共享字段和表写者为准。
+
+**机制与来源**：[问题主记录](../../audit/2026-09-23-historical-issue-records.md#nullable-duty)。内存 0 表示缺席，但数据库可空 FK 需要 NULL；一个入口已有转换不能证明另一个入口也有。原审计中错误被通用 INTERNAL_ERROR 掩盖，说明还需检查错误分型。
+
+**开发检查**：
+
+1. 从字段契约确定缺席、有值但非法、合法值三种语义；沿现有表写者列出所有写入口，检查转换一致性。
+2. 保持可选职责业务规则；让 SQL 边界处理缺席值，不能靠强制填 reviewer 掩盖实现错误。合法角色与非法 ID 仍按原有鉴权/FK 处理。
+3. 对缺席、合法、非法值及相关创建/修复入口安排真实 PG 验证；mock 不会证明 FK/NULL 行为。保持正常职责模式的回归。
+
+**已有防护**：[engine](../../../internal/docgov/engine.go) 创建路径使用 `nullIfZero`；[历史报告](../../test-reports/2026-09-17-docgov-optional-duty-null-fk-test-report.md) 记录 `TestDocGov_CreateOrGetDocument_OptionalDutiesNullFK`、分型单测与 API/DB 冒烟。2026-09-23 仅复核源码及旧报告，未重跑测试；未据此证明真实 UI、所有写路径或当前部署。
+
+**边界**：只适用于明确以 0 表示未设置且列允许 NULL 的字段；不能对所有数值或必填关系统一转 NULL。授权资格判定仍遵循现行规范。
+
+**未完成防护**：跨所有相关入口的自动覆盖不由本条保证；后续变更任务按实际影响补证。没有新增 CI 门禁。
+
+**修订**：2026-09-23 从历史 FK 案例提炼，并核对当前创建路径；接口/表写者变化或同因复发时再审。

.doc/ops/lessons/INDEX.md

@@ -0,0 +1,11 @@
+# 开发经验与注意事项
+
+先按本任务模块、路径、症状和机制检索，再读命中条目的适用条件与来源。执行步骤与维护要求见 [闭环规范](../2026-09-23-issue-learning-workflow.md)；事实入口见 [问题台账](../../audit/ISSUES.md)。这些是仓库可共享的外部经验，不依赖单个聊天会话或某个客户端私有记忆。
+
+| lesson_id | 触发条件 / 关键词 | 注意事项 | lesson_state | 主记录 / 最近复核 |
+|---|---|---|---|---|
+| 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 并保留替代链接。

.doc/ops/long-term/2026-09-16-pu7-pi-narrative-contract.md

@@ -2,7 +2,7 @@
 title: "PU7 PI change-report 叙事 — 获批后任务契约"
 status: done
 created: 2026-09-16
-updated: 2026-09-17
+updated: 2026-09-23
 owner: Cursor-Auto
 branch: feature/pu7-pi-narrative
 mutex: docgov
@@ -13,6 +13,10 @@ go_no_go: go
 
 **go/no-go**：GO（用户覆盖授权，见 Wave3 research）。脚手架已合 `dev`；W3 live（产品 PI + digest 绑定）已接线，默认 flag 仍 off。
 
+## 2026-09-23 收口
+
+修复后真实 MiniMax 复测 PASS（截断 hunk/impact 输入 + reasoning 目标落盘）；报告见 [../../test-reports/2026-09-23-pi-narrative-closeout-test-report.md](../../test-reports/2026-09-23-pi-narrative-closeout-test-report.md)。FEATURE-MATRIX `docgov-pi-narrative` → `done`。默认 flag 仍 off；放量另授权。
+
 ## 目标
 
 只读消费 immutable diff+lineage+risk floor 的 PI 叙事；任意 schema/超时/注入 → 全量 fallback。
@@ -27,11 +31,12 @@ go_no_go: go
 ## 路径
 
 - `internal/docrevision/flags.go` / `narrative.go` / `service.go`
-- `deploy/pi-agent/change-report-narrative-v1.mjs`
+- `deploy/pi-agent/change-report-narrative-v1.mjs`；`runner.mjs` reasoning 目标落盘
 - `web/.../ChangeReportPanel.tsx` / `changeReportView.ts`
 - 报告：[../../test-reports/2026-09-16-pu7-pi-narrative-test-report.md](../../test-reports/2026-09-16-pu7-pi-narrative-test-report.md)
 - W3 live：[../../test-reports/2026-09-17-w3-pi-change-report-narrative-test-report.md](../../test-reports/2026-09-17-w3-pi-change-report-narrative-test-report.md)
-- short-term：[../short-term/2026-09-17-w3-pi-change-report-narrative.md](../short-term/2026-09-17-w3-pi-change-report-narrative.md)
+- 收口：[../../test-reports/2026-09-23-pi-narrative-closeout-test-report.md](../../test-reports/2026-09-23-pi-narrative-closeout-test-report.md)
+- short-term：[../short-term/2026-09-17-w3-pi-change-report-narrative.md](../short-term/2026-09-17-w3-pi-change-report-narrative.md)；[../short-term/2026-09-23-pi-narrative-final-closeout.md](../short-term/2026-09-23-pi-narrative-final-closeout.md)
 
 ## 回滚
 

.doc/ops/research/2026-09-14-final-artifact-vault.md

@@ -0,0 +1,149 @@
+---
+title: "最终成果保险库与部分恢复边界"
+created: 2026-09-14
+status: done
+confidence: high
+---
+
+# 调研：最终成果保险库与部分恢复边界
+
+## 结论
+
+提案可行，建议采用，但不应实现成“把最终文件复制到一个固定目录”。应建设独立的**最终成果保险库（Final Artifact Vault，FAV）**：只接收服务端已经确认终态、具有稳定标识和内容哈希的成果，以不可变 blob、语义 manifest 和提交回执保存，并与工作区清理完全解耦。
+
+FAV 是 PostgreSQL 完整备份/PITR 的互补层，不是第三套完整业务事实源。它只对“已归档成果的精确内容与出处”负责，可以在数据库损坏或选择性重建时恢复文档、最终回复和有限的来源关系；成员权限、工作流活动态、租约、待办任务、幂等记录等仍须由数据库备份或其他权威记录恢复。
+
+## 当前能力与缺口
+
+| 能力 | 当前事实 | 与提案的差距 |
+|---|---|---|
+| 受控文档版本 | `document_content_blobs` 与 `document_snapshots` 在 PostgreSQL 内保存不可变 Markdown；工作区 `output.md` 是投影 | 数据库与账本一起丢失时，没有独立副本；当前 GET 仍会被缺失工作区投影阻断 |
+| 助手最终回复 | `chat_messages.content` 保存正文，`chat_turns.assistant_message_id` 可在 completed 回合绑定最终消息 | 占位正文会原地更新，没有独立不可变回复快照；删除 session 会级联删除消息 |
+| 回复导出 | `replyexport` 已区分 completed、status/error/card，提供 `content_sha256` 与 `export_policy` | `export-source` 仍从当前消息行临时构造 snapshot，不是持久归档；部分调用在缺少真实回合状态时默认按 completed 评估 |
+| 附件 CAS | `storage_blobs`/`file_references` + `data/<env>/storage/blobs` 按 SHA 去重 | blob 物理文件仍在运行状态根，引用元数据仍在数据库；不独立于工作区/数据库事故 |
+| 数据备份 | 现有脚本主要导出 PostgreSQL；数据生命周期方案已要求 DB + state 成对打包 | 尚无跨文档/回复的终态准入、持续发布、独立索引或成果级恢复 API |
+
+当前事故已经证明“数据库记录还在”不代表“运行容器能找到正文”。FAV 可以解决成果副本对工作区根的依赖，但不能替代固定 `RUNTIME_STATE_ROOT`、storage identity、projection outbox 和数据库备份。
+
+## 提案中应保留的部分
+
+1. **独立持久位置**：成果存储不位于 Git worktree、临时集成目录、任务 workspace 或普通 GC 扫描范围。
+2. **只收终态成果**：拒绝流式片段、候选稿、工具轨迹、修复过程、临时报告、租约和未完成任务。
+3. **支持系统定位**：使用稳定 artifact UUID、逻辑资源 ID、来源事件和内容 SHA，而不是依赖数据库自增 ID 或 workspace 路径。
+4. **辅助部分恢复**：允许在数据库关系不匹配时校验并导入已归档内容，同时保留来源和冲突证据。
+5. **与清理联动**：工作区或旧数据集只有在必需成果全部发布并验证后才可进入销毁阶段。
+
+## 必须修正的部分
+
+### 1. “最终”必须由状态机判定
+
+不能按文件名、目录、时间或“任务进程退出 0”判断最终。建议的准入规则：
+
+| 成果类型 | 可归档条件 | 明确排除 |
+|---|---|---|
+| 智能体生成文档 | agent candidate 已 `committed`，且 output snapshot 成为账本 head；归档该次生成的不可变 snapshot | ready、needs_confirmation、rejected、stale、quality_failed、workspace 草稿 |
+| 受控文档正式稿 | `approved` 时归档被冻结的 review snapshot；版本被 sealed 时可归档该版 final head | drafting/reviewing 中尚未冻结的当前文件、lease 中内容 |
+| 自由文档 | 已形成不可变 version，且用户显式“发布/归档”或被正式成果引用；显式操作不能绕过终态检查 | 自动保存中的连续修订、临时私密摘录 |
+| 助手回复 | `chat_turn.status=completed`、绑定唯一 `assistant_message_id`、正文 SHA 匹配，且 `export_policy=full`；`copy_only` 只在 completed 后显式 pin 时进入 | status/error/cancelled/system、纯操作卡、流式 chunk、placeholder、中间 agent 消息；未完成回复即使 pin 也拒绝 |
+| 最终报告/附件 | 被上述成果 manifest 引用并通过合规/病毒/类型校验 | 未引用附件、日志、Prompt、工具输入输出、agent session |
+
+“每次成功保存的人工 revision”仍进入 PostgreSQL 不可变账本，但不自动进入 FAV。这样既保留文档历史，又不会把编辑过程伪装成最终成果。
+
+### 2. 保险库不是第三套完整真相源
+
+建议采用三层责任边界：
+
+| 层 | 权威范围 | 可否清理 |
+|---|---|---|
+| PostgreSQL 运行库 | 项目/用户/权限、工作流、任务、当前指针、完整版本账本和归档发布状态 | 按环境生命周期与完整备份策略处理 |
+| Runtime workspace/state | Agent 计算现场、`output.md` 投影、临时转换文件和附件运行副本 | 可重建/可清理，但须受发布门禁保护 |
+| Final Artifact Vault | 已准入成果的精确字节、manifest、来源证据、保留/删除状态和发布回执 | 独立保留；只能按成果保留策略和删除账本处理 |
+
+正常读写仍以数据库授权和业务指针为准。数据库仍能完成授权判定但正文缺失时，可从 FAV 只读降级返回并标记 `source=vault/degraded`；若权限关系也缺失，FAV 不得绕过授权直接对用户开放，只能进入管理员隔离恢复流程。
+
+### 3. 发布必须避免双写裂缝
+
+数据库事务内同时提交业务终态、精确 payload/SHA 的不可变 staging 和 `artifact.publish.requested` outbox；事务外 publisher 只从 staging 幂等写 blob、manifest，校验后最后写 commit marker，再回填 receipt。对象存储 I/O 不进入数据库事务。不能让异步 publisher 重读仍可更新或随 session 级联删除的消息行。
+
+清理流程只认 `verified` receipt，不认“消息发过”“目录存在”或“有一个 SHA”。重复投递必须由 `artifact_uuid + source_event_id + payload_sha256` 去重；相同逻辑资源的新终态生成新 manifest，不覆盖旧 manifest。
+
+### 4. Manifest 必须表达恢复语义
+
+每个归档单元至少包含：
+
+```text
+artifact_schema_version
+artifact_uuid / artifact_type / logical_resource_id
+project_external_key / environment
+source_event_id / source_run_id / source_message_id / source_snapshot_id
+payload members: name / media_type / byte_size / sha256 / required
+terminal_evidence: state / decided_at / actor_ref / policy_version
+lineage: parent artifact / document version / chat turn
+retention_class / sensitivity / encryption_key_ref
+source_database_identity / source_schema_version / source_commit
+published_at / publisher_version / manifest_sha256
+```
+
+manifest 使用稳定外部标识，同时保留旧数据库 ID 作为来源提示。它必须能在没有原数据库的情况下建立离线目录，但不得声称自己包含未列出的业务依赖。
+
+### 5. 恢复必须经过隔离与对账
+
+FAV 支持两种恢复结果：
+
+- `recover-as-collection`：把验证通过的成果导入新的恢复集合/文档，保留原来源与 hash，不伪造原工作流状态。这是默认模式。
+- `relink`：只有项目、用户、权限、会话和版本依赖均存在且无冲突时，才把成果重新连接到原逻辑资源。
+
+恢复顺序为：离线 inventory → manifest/schema/SHA 校验 → 删除账本/保留策略检查 → scratch DB 导入 → 依赖与 ID 映射 → 冲突预览 → 人工确认 → 单事务 promotion → 审计报告。禁止 GET 接口因发现不一致而自动写回数据库，也禁止直接覆盖既有 head 或消息。
+
+## 可恢复与不可恢复边界
+
+| 可从 FAV 恢复 | 不能只靠 FAV 恢复 |
+|---|---|
+| 最终 Markdown/附件字节与 MIME/SHA | 用户认证凭证、session、token |
+| 已归档助手最终回复及其稳定 turn/message 来源 | 项目成员关系、文档 duty、当时的完整授权图 |
+| 文档版本/快照的有限来源、父子和生成 run 线索 | 活跃 lease、pending candidate、未完成 task/run |
+| 最终报告、批准/提交终态证据 | 通知投递状态、outbox 消费位置、worker 状态 |
+| 恢复所需 schema/producer/storage identity 元数据 | 未进入准入清单的草稿、中间过程和完整数据库约束 |
+
+因此灾难恢复仍须保留 PostgreSQL base backup/WAL 或经验证的完整逻辑备份；FAV 解决的是“最终成果可独立找回”和“有限业务内容可重建”。
+
+## 存储、保留与安全
+
+- 第一阶段可用独立 filesystem backend，但必须有独立 `vault_storage_identity`、最小权限凭证和 mount，不允许退回 `./data/dev`；凭证只从受管 secret/env 注入。生产目标应支持 TLS、静态加密及异机/对象存储复制。
+- 当前仓库没有 tenant 实体，安全边界应使用现有 `environment + project_members/role-admin` 授权模型，不得伪造 `tenant_id`。blob 采用**项目作用域加密 CAS**：同项目按 SHA-256 去重，跨项目相同 SHA 不共享密钥和删除边界；未来引入组织/租户层须另立 ADR 和迁移。
+- manifest-member 到 blob 的引用账本决定删除：tombstone 先撤销单个成果读取与 key wrapping；仅当项目作用域内最后有效引用消失且 retention/legal hold 允许时物理清除。manifest 和 commit marker 只追加，定期执行 checksum scrub 和离线目录重建。
+- filesystem backend 必须以同文件系统临时文件、校验、文件 `fsync`、原子 no-replace rename、父目录 `fsync` 实现持久化，确认 blob/manifest 落盘后才提交 marker；不能把“最后写 marker”误当成掉电安全。
+- WORM/对象锁按数据类别启用，不对所有内容一律永久锁定。普通保留使用可治理模式；法律保全单独使用 legal hold。
+- project/user 授权仍由服务端复用正常读取的既有判定；授权关系缺失或不确定时 fail closed。归档正文不得进入日志、metrics 或通知 payload。
+- 自动归档前执行服务端敏感内容准入：结构化排除 Prompt/工具轨迹，secret、认证材料、restricted 或分类失败均 fail closed，且正文不进入 outbox/staging。
+- 建立删除/法务保留账本。满足删除条件时先禁止读取和恢复，再删除密钥/对象；任何历史 restore 都必须重放 tombstone，避免已删除内容复活。
+- manifest 不保存 secret、Prompt、内部推理、工具轨迹或认证材料；敏感元数据最小化，必要时使用不可逆外部键映射。
+
+## 与数据精简方案的关系
+
+FAV 与 migration corpus、完整备份是三个不同产品：
+
+| 机制 | 目的 | 内容 |
+|---|---|---|
+| Final Artifact Vault | 持续保存终态成果，供定位、只读降级和有限恢复 | 小而长期、按终态事件持续追加 |
+| Migration corpus | 验证旧 schema 到新 schema 的迁移、异常和 reload | 小而可重复、脱敏、带 assertions |
+| DB + state backup/PITR | 完整灾难恢复与回滚 | 大而完整、按 RPO/RTO 生成 |
+
+清理不能因为“FAV 有最终正文”就跳过完整备份，也不能用完整备份替代成果级准入。正确门禁是三者分别验证：最终成果覆盖率、迁移 corpus 可升级、完整备份可恢复。
+
+首次启用 FAV 时还必须做一次**存量终态回填**：只从权威数据库的不可变 snapshot、批准/提交事件和 completed chat turn 枚举，以来源事件 + payload SHA 幂等产生请求。缺正文或终态证据的记录进入 quarantine；批准排除必须记录原因、批准人和有效期。禁止为了达到 coverage 扫描 workspace 或批量把“旧数据”标为已覆盖。
+
+## 外部依据
+
+- [RFC 8493 BagIt](https://www.rfc-editor.org/rfc/rfc8493.html) 要求 manifest 覆盖 payload 并验证完整性，支持本方案的 manifest/checksum 设计。
+- [OCI Descriptor](https://github.com/opencontainers/image-spec/blob/main/descriptor.md) 以 digest 标识并校验内容，支持内容寻址 blob。
+- [AWS Transactional Outbox guidance](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html) 说明业务写入与 outbox 同事务、消费者幂等的必要性。
+- [PostgreSQL PITR](https://www.postgresql.org/docs/17/continuous-archiving.html)、[pg_restore](https://www.postgresql.org/docs/17/app-pgrestore.html) 与 [pg_verifybackup](https://www.postgresql.org/docs/16/app-pgverifybackup.html) 说明完整恢复、选择性恢复依赖和真实 restore 演练的边界。
+- [AWS S3 Object Lock](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock.html) 说明 governance/compliance/legal hold 的差异，支持按数据类别选择保留模式。
+
+## 建议动作
+
+1. 采用[最终成果保险库整改方案](../../remediation/2026-09-14-final-artifact-vault-remediation.md)，先定义终态协议和 manifest，再选择 filesystem 或对象存储实现。
+2. 将 FAV 发布完成率加入 dataset inventory/GC 的硬门禁，但不把 FAV 设为当前 409 的绕行修复。
+3. 首次实现优先覆盖受控文档 approved/agent committed snapshot 与 `export_policy=full` 的 completed assistant reply。
+4. 先在 dev 用项目 6173 的等价脱敏 corpus 做“生成 → 发布 → 清 workspace → 读取/恢复 → rebuild”演练，再考虑 main 保留策略。

.doc/ops/research/2026-09-14-runtime-data-retention-and-migration-corpus.md

@@ -0,0 +1,150 @@
+---
+title: "运行数据精简、迁移语料与演示数据保留策略"
+created: 2026-09-14
+status: done
+confidence: high
+---
+
+# 调研：运行数据精简、迁移语料与演示数据保留策略
+
+## 结论
+
+用户提出的“及时清理过往数据，只保留最新、有用且必要的一部分，并用保留数据验证迁移和重载”方向合理，尤其适合当前快速迭代期的 dev/test 环境。
+
+但必须补充两个边界：
+
+1. 清理历史运行数据只能降低数据转换量和现场噪声，不能替代对受支持旧 schema 的迁移兼容；应把有价值的旧状态压缩成小型、可重复、脱敏的 migration corpus。
+2. 不应在当前库上逐表删除后继续使用；当前跨项目数据存在非完整级联和 DB/文件双事实源，优先采用“新库 + 新状态根 + 选择性导入 + 旧卷隔离”的蓝绿轮换。
+3. 对最终成果再增加独立 [Final Artifact Vault](./2026-09-14-final-artifact-vault.md)，但它只辅助成果定位与部分恢复，不能替代完整 DB+state 备份或旧 schema migration corpus。
+
+## 当前数据画像
+
+2026-09-14 只读现场：
+
+| 环境 | schema | 项目数/特征 | 文件状态 | 判断 |
+|---|---:|---|---|---|
+| dev | 33 | 366 个项目；149 active、217 planning；全部产生于 9 月 11–14 日 | 主仓 `data/dev` 约 100MB | 大量 PG/E2E 夹具，适合立即精简，但须先解决当前错误挂载事故 |
+| test | 29 | 约 37 个项目 | 主仓 `data/test` 约 20KB | schema 落后且数据价值低，应改为可重建/短 TTL |
+| main | 25 | 10 个历史 seed 项目，当前无受控文档 | 主仓 `data/main` 约 20KB | 不应用作日常迁移试验；清理需另行确认业务/展示用途 |
+| shared KB | 独立 | 跨环境共享知识库 | `data/shared` | 不属于本方案的项目数据清理范围 |
+
+dev 主要表约有：`projects=366`、`chat_sessions=421`、`chat_messages=1923`、`task_runs=307`、`document_records=153`、`document_snapshots=283`、`document_change_events=257`。数据库总体不大，主要问题不是容量，而是数据来源混杂、迁移噪声和无法判定哪些记录应保留。
+
+## 现有清理为何不能直接做
+
+### 1. `DELETE projects` 不是完整项目删除
+
+当前外键有 101 条，部分项目子表 CASCADE，但存在关键例外：
+
+- `task_runs.project_id` 是 `ON DELETE SET NULL`，项目删除后 run/event 仍可残留；
+- `document_versions`、`document_snapshots`、`document_change_events`、`document_change_reports`、`document_agent_candidates` 依赖 `doc_id`/snapshot/version，但不完整依附 `projects`；
+- `document_content_blobs` 与 `storage_blobs` 需要引用计数/mark-and-sweep，不能看到文件就删；
+- 工作区、agent sessions、CAS 文件位于状态根，数据库 cascade 不会删除文件；
+- notification/outbox/audit/lineage 的保留语义不同，不能一律级联。
+
+所以简单删除项目会制造孤儿数据，反而加重后续迁移与排障成本。
+
+### 2. 现有备份/恢复不足以支撑安全轮换
+
+- `backup-system-db.sh` 只导出 PostgreSQL，不包含与之匹配的 `data/<env>` 文件状态；
+- `restore-system-db-drill.sh` 校验 dump 列表并运行迁移测试，但当前没有真正把 dump restore 到新隔离数据库；
+- restore 未强制隔离目标，默认路径存在误触共享 dev 库的风险；
+- 没有 dataset manifest、项目选择、文件 SHA inventory、脱敏、预期断言与导入校验；
+- 备份脚本的凭证来源需要改成统一安全配置，不应保留脚本内默认值。
+
+在这些缺口补齐前，不能用“有 dump”作为可删除证明。
+
+## 建议的数据分类
+
+| 类别 | 用途 | 典型内容 | 是否进入日常运行库 | 保留策略 |
+|---|---|---|---|---|
+| `operational-pinned` | 当前人工使用/正在排障 | 项目 143 等明确认领项目 | dev 可保留；main 按业务规则 | 显式 pin，禁止自动清理 |
+| `demo-current` | 产品展示 | 每个正式工作流 1 个完整、可解释项目 | dev/demo 环境 | 只保留当前版本；新版验证后替换旧版 |
+| `regression-golden` | 功能回归 | 文档版本、人工修订、并发冲突、reload 等完整链 | 隔离验收库，可选只读展示副本 | 小型、确定性、脱敏；按能力而非数量保留 |
+| `migration-baseline` | 旧 schema → 当前 schema | 旧 release 的最小 DB + 匹配文件包 | 仅隔离迁移测试 | 最多保留 3 个 release 基线，滚动替换 |
+| `ephemeral-test` | PG/E2E 单次运行 | 自动测试项目、会话、run、workspace | 每次独立数据库/状态根 | PASS 后立即删；FAIL 保留 3–7 天 |
+| `quarantine` | 清理回滚与取证 | 被替换的完整卷/状态根 | 不挂载到运行容器 | 只读 7–14 天，恢复演练通过后销毁 |
+
+## 建议的最小保留集合
+
+当前 dev 可先采用 6–10 个项目的上限，而不是按日期盲留：
+
+1. 项目 143：暂作旧数据/canonical repair/active workflow 回归样本；若含真实内容，不进入 Git，后续用脱敏等价 fixture 替换。
+2. 项目 6173：目前最新且证据完整的受控正文 UI 全链，含两份受控文档、V3/r2、并发、权限与 restart 验证，可作为当前回归/展示候选。
+3. 项目 6159：保留一个发布周期作为上一轮文档账本对照；6173 corpus 稳定后删除，避免永久重复。
+4. 三个正式工作流各生成 1 个 `demo-current`：`main`、`product_manager`、`test_manager`；必须由固定 seed/真实页面脚本可重建，不能依赖手工挑出的偶然状态。
+5. 1 个失败/异常样本不进入展示库，只进入隔离 `regression-golden`：覆盖 projection missing、hard-break、旧消息 scope、高 ID sequence 等历史风险。
+
+最新项目不等于最有价值。选择评分应优先：证据完整度、覆盖的能力、是否可脱敏重建、DB/文件一致性、是否有预期断言；时间只作为同类样本的淘汰条件。
+
+本轮已只读确认 143、6159、6173 共 5 份受控文档在主仓状态根的 `output.md` 均存在且 SHA 与 `document_records` 一致；这说明它们具备候选资格，但仍需通过敏感性、owner 和可恢复性审查后才能进入最终 retain allowlist。
+
+## 迁移语料库策略
+
+不保存每个 Goose 版本的整库。按产品 release 边界保留：
+
+- `oldest-supported`：当前承诺支持的最老 release；
+- `previous-release`：上一发布版；
+- `current-pre-upgrade`：本次上线前快照，下一次轮换为 previous。
+
+当前建议先建立三个最小基线：
+
+- schema 25：文档账本前/早期治理状态，覆盖 main 当前落后路径；
+- schema 28/29：文档 revision 首次引入后的状态，覆盖 test 当前路径；
+- schema 32/33：canonical repair、task 状态和当前数据根契约。
+
+这些基线应由迁移 fixture builder 在隔离库中构造或从已批准快照脱敏得到，不能直接把 main/test 的运行数据当测试资产。
+
+每个 corpus package 必须包含：
+
+```text
+manifest.json
+database.dump
+state.tar.zst
+checksums.txt
+assertions.yaml
+```
+
+manifest 至少记录 dataset 版本、source schema、目标 schema、生成 commit、storage identity、项目/会话/文档/run 数量、文件总数和 SHA、脱敏状态、过期时间；`assertions.yaml` 记录迁移后必须成立的版本、状态、正文 hash、序列与权限断言。
+
+二进制 dump/状态包不进 Git；仓库只保留 manifest schema、fixture builder、脱敏规则、选择规则和非敏感断言。实际包放受控备份目录或对象存储。
+
+## 每次发布的数据轮换模型
+
+```text
+旧运行库/状态根（只读）
+        │ export + manifest + checksums
+        ▼
+迁移语料构建区（脱敏/裁剪/恢复验证）
+        │
+        ├── oldest-supported corpus
+        ├── previous-release corpus
+        └── current demo/regression corpus
+        │
+        ▼
+新数据库 + 新状态根（latest schema）
+        │ import selected datasets
+        ▼
+工程门禁 + 页面验收 + rebuild/reload
+        │ PASS
+        ▼
+切换运行 identity；旧卷 quarantine 7–14 天后销毁
+```
+
+这比在原 dev 库上大规模 DELETE 更适合当前阶段：新库天然消除未知孤儿，导入过程本身又验证了备份、迁移、文件配对、序列和重载。
+
+## 风险边界
+
+- main 真实业务数据不能套用 dev 的 7–14 天策略；须先定义业务、合规、审计和用户删除规则。
+- 项目 143 等真实内容不能直接固化为仓库 fixture；应保留 hash/结构特征并脱敏重建。
+- migration corpus 不能只有 happy path，否则清场后会失去发现 legacy bug 的能力。
+- 任何清理必须先完成隔离 restore，并验证数据库与文件包属于同一 storage identity。
+- 任何清理还必须验证应归档终态成果均已取得 FAV verified receipt；“有归档正文”不能替代完整关系闭包恢复。
+- 错误 `/tmp` 数据根属于当前事故证据；在 split-brain 恢复报告签字前不纳入普通清理。
+
+## 建议动作
+
+- 采用 [运行数据生命周期与迁移语料整改方案](../../remediation/2026-09-14-runtime-data-lifecycle-and-migration-corpus-remediation.md)。
+- 首轮只处理 dev；test 改为短 TTL 隔离环境；main 仅盘点，不删除；shared KB 排除。
+- 先实现 dataset inventory/export/restore/verify，再执行蓝绿精简，不先写清理 SQL。
+- 并行实施[最终成果保险库整改](../../remediation/2026-09-14-final-artifact-vault-remediation.md)，把成果覆盖率加入 GC/销毁门禁。

.doc/ops/short-term/2026-09-14-dev-runtime-data-root-guard.md

@@ -0,0 +1,61 @@
+---
+title: "dev runtime data root split-brain 诊断、方案审查与修订"
+status: in_progress
+created: 2026-09-14
+updated: 2026-09-14
+owner: Cursor
+branch: fix/dev-runtime-data-root-guard
+worktree: .worktrees/fix-dev-runtime-data-root-guard
+mutex: infra-runtime-state
+---
+
+# dev runtime data root split-brain 诊断、方案审查与修订
+
+## 目标
+
+定位项目 143 刷新 409 的当前根因，经审查后把整改方案改成可执行、可分批批准的文本；**不实施**纠挂或业务代码，直到用户再批 Unit A / Unit B。
+
+## 范围
+
+- 诊断：用户报错链、dev PostgreSQL、主仓文件、容器 mount、health/ready、Compose / `env-service.sh`
+- 审查：原文六波次方案的内部矛盾、可行性、抢占与身份首启风险
+- 修订：Unit A / Unit B / Deferred 拆分与可执行 Wave 0 Runbook
+
+## 非目标
+
+- 不操作真实用户会话
+- 不写数据库、不覆盖正文、不删除错误根
+- 本轮不 rebuild、不占集成槽执行纠挂（抢占授权已写入方案，实施另批）
+- 不变更运行中的 test/main
+
+## 步骤
+
+1. [x] 完成仓库启动链、既有 canonical hash/refresh 事故文档复核。
+2. [x] 比对项目 143 DB record、ledger head、主仓 `output.md` 与容器内路径。
+3. [x] 审计 app/pi/cursor mounts、Compose working dir、健康检查与影响面。
+4. [x] 完成初版 audit、remediation、gap/feature/current SSOT。
+5. [x] 多视角审查原文方案；现场复核挂载与集成槽仍为事故态。
+6. [x] 按审查结论重写整改方案（Unit A/B/Deferred + 可执行 Runbook）。
+7. [ ] 用户再批后实施 Unit A（事故抢占纠挂）。
+8. [ ] 用户再批后实施 Unit B（绝对状态根 + 门禁 + `/ready`）。
+
+## 验收标准
+
+- [x] 直接根因有数据库、文件和容器三方证据。
+- [x] 明确区分旧 hash drift、真正 ETag 409 与本次 projection missing。
+- [x] 修订方案不再把 Wave 0 依赖尚未存在的 identity / outbox；不再把 Deferred 当事故关门条件。
+- [x] 未污染真实会话或修改共享运行态。
+- [ ] Unit A/B 实施与验收（另批）。
+
+## 相关链接
+
+- Audit: [../../audit/2026-09-14-dev-runtime-data-root-split-brain.md](../../audit/2026-09-14-dev-runtime-data-root-split-brain.md)
+- Remediation: [../../remediation/2026-09-14-dev-runtime-data-root-and-projection-remediation.md](../../remediation/2026-09-14-dev-runtime-data-root-and-projection-remediation.md)
+- Test report: 待 Unit A 实施后创建
+
+## 证据 / 备注
+
+- 诊断分支：`fix/dev-runtime-data-root-guard`，基线 `dev@a8f9451`，诊断 commit `f1edb70`。
+- 2026-09-14 08:54 UTC 诊断：app/pi/cursor 均挂 `/tmp/as-dev-wf409-merge/data/dev*`；DB 仍为 `agent-dev-context-pgdata`。
+- 2026-09-14 ~09:23 UTC 审查复核：同一挂载仍在；`/health` `/ready` 200，`schema_version=33`；主仓 CURRENT 槽位仍为 `implementer_cursor` e2e。
+- 用户选择：Wave 0 = 事故抢占；先改方案再批实施。

.doc/ops/short-term/2026-09-14-final-artifact-vault-implementation.md

@@ -0,0 +1,49 @@
+---
+title: "最终成果保险库 V0–V6 落地"
+status: done
+created: 2026-09-14
+updated: 2026-09-14
+owner: Cursor
+branch: feature/final-artifact-vault
+worktree: .worktrees/fix-dev-runtime-data-root-guard
+mutex: artifact-vault
+---
+
+# 最终成果保险库 V0–V6 落地
+
+## 目标
+
+按已审查方案实现 FAV：协议、独立存储、文档/助手接入、存量回填、只读降级、scratch 恢复与清理门禁。
+
+## 非目标
+
+- 不替代 Unit A/B 纠挂
+- 不占 agent-dev 集成槽 rebuild
+- 不扫描 workspace 猜测终态
+- 不新增 tenant_id
+
+## 步骤
+
+1. [x] V0 ADR/schema/eligibility/goose/表征（goose **00034**）
+2. [x] V0 领域缺口（review_snapshot_id、ledger hook、task CompleteChatTurn + export 列）
+3. [x] V1 存储与 publisher（独立根、项目作用域 CAS、PG/Memory registry）
+4. [x] V2 文档接入（persistAgentCommit / ApproverApprove / freeform publish）
+5. [x] V3 助手接入（同步 chat + task finalize）
+6. [x] V3.5 回填（只枚举账本/完成 turn）
+7. [x] V4 降级读取（`FAV_DEGRADED_READ` 默认关）
+8. [x] V5 恢复（scratch-only recover-apply 写入 collection；union-deny 跳过 tombstone）
+9. [x] V6 门禁与三份演练报告（live e2e 待 Unit A）
+10. [x] 缺口补齐：approve/commit 同事务 staging；半发布 exclusive 重试；GET 零写入；`copy_only` pin-export；destroy 预检 CLI
+
+## 相关链接
+
+- ADR: [../../adr/2026-09-14-final-artifact-vault.md](../../adr/2026-09-14-final-artifact-vault.md)
+- Remediation: [../../remediation/2026-09-14-final-artifact-vault-remediation.md](../../remediation/2026-09-14-final-artifact-vault-remediation.md)
+- Test report: [../../test-reports/2026-09-14-final-artifact-vault-test-report.md](../../test-reports/2026-09-14-final-artifact-vault-test-report.md)
+
+## 证据 / 备注
+
+- 分支：`feature/final-artifact-vault`
+- 未执行 `env-service` rebuild；`FAV_DEGRADED_READ` 默认 false
+- Goose：`00034_2026-09-14-final-artifact-vault.sql`
+- 未合 `dev`；live 6173 / PITR / corpus 仍待 Unit A 另占槽

.doc/ops/short-term/2026-09-14-final-artifact-vault-plan.md

@@ -0,0 +1,61 @@
+---
+title: "最终成果保险库调研与整改方案"
+status: done
+created: 2026-09-14
+updated: 2026-09-14
+owner: Codex
+branch: fix/dev-runtime-data-root-guard
+worktree: .worktrees/fix-dev-runtime-data-root-guard
+mutex: artifact-vault
+---
+
+# 最终成果保险库调研与整改方案
+
+## 目标
+
+评估并完善“只归档最终生成物和最终智能体回复”的提案，形成不会与数据库、文档账本和工作区争夺事实源，且能支持受控部分恢复的系统方案。
+
+## 范围
+
+- 最终文档版本、最终助手回复和必要恢复元数据的归档边界；
+- 终态判定、原子发布、不可变清单、校验、授权、保留与删除；
+- 工作区清理门禁、降级读取、隔离恢复和数据库重建边界；
+- 与现有数据生命周期、迁移语料、文档账本和对话持久化方案衔接。
+
+## 非目标
+
+- 本轮不实现业务代码、数据库迁移或对象存储；
+- 不归档候选稿、流式片段、工具轨迹、租约、临时工作区或其他中间结果；
+- 不把保险库定义为运行数据库的完整镜像或自动覆盖线上数据的入口；
+- 不执行数据删除、卷切换或恢复写入。
+
+## 步骤
+
+1. [x] 登记任务和独立 mutex。
+2. [x] 核对现有文档快照、CAS、最终助手消息、任务终态和备份恢复边界。
+3. [x] 评审提案，明确可采用部分、必须修正部分和反模式。
+4. [x] 编写专项调研与整改方案，并并入运行数据生命周期方案。
+5. [x] 更新 CURRENT、FEATURE-MATRIX、gap-matrix 与整改索引。
+6. [x] 完成文档一致性、安全、可行性和对抗性复核。
+
+## 验收标准
+
+- [x] 明确“最终”的服务端判定规则和禁止进入保险库的内容。
+- [x] 明确数据库、工作区、保险库三者权威边界，不产生静默双写。
+- [x] 方案含 manifest/checksum、幂等发布、清理前门禁、降级读取和隔离恢复流程。
+- [x] 明确可恢复与不可恢复的数据范围、安全/删除要求及恢复演练。
+- [x] 本轮未实施业务代码或破坏性操作。
+
+## 相关链接
+
+- Research: [最终成果保险库与部分恢复边界](../research/2026-09-14-final-artifact-vault.md)
+- Remediation: [最终成果保险库与受控恢复](../../remediation/2026-09-14-final-artifact-vault-remediation.md)
+- Test report: 待用户批准实施后创建
+
+## 证据 / 备注
+
+- 当前受控文档不可变正文位于 PostgreSQL `document_content_blobs`，工作区 `output.md` 是投影。
+- 当前附件 CAS 物理 blob 位于运行状态根，引用元数据位于 PostgreSQL。
+- 当前任务完成摘要通过 `FinalizeAssistantTaskMessage` 写回 `chat_messages`，尚无独立终态成果发布协议。
+- 文档复核补齐：显式发布不可绕过终态、不可变 payload staging、项目作用域加密 CAS/引用删除、存量回填、掉电持久化、敏感内容准入、既有项目授权降级和 scratch 恢复权限。
+- 独立 Claude 安全/对抗复核结果已收敛；whole-document peer 因结构化输出重试耗尽被丢弃，未作为结论依据。

.doc/ops/short-term/2026-09-14-runtime-data-lifecycle-plan.md

@@ -0,0 +1,60 @@
+---
+title: "运行数据精简与迁移语料库方案"
+status: done
+created: 2026-09-14
+updated: 2026-09-14
+owner: Codex
+branch: fix/dev-runtime-data-root-guard
+worktree: .worktrees/fix-dev-runtime-data-root-guard
+mutex: infra-runtime-state
+---
+
+# 运行数据精简与迁移语料库方案
+
+## 目标
+
+评估及时清理旧数据建议的合理性，并设计可恢复、可迁移验证、可展示且不污染长期环境的数据生命周期方案。
+
+## 范围
+
+- dev/test/main 数据量、schema、项目/文档/run 关系与文件状态；
+- 备份/恢复、选择性导出、迁移 corpus、蓝绿轮换；
+- retention 分类、TTL、quarantine、GC 和验收门禁。
+- 最终成果保险库 coverage 与清理门禁，但不以其替代完整备份。
+
+## 非目标
+
+- 不执行 DELETE/TRUNCATE/drop volume；
+- 不修改数据库、文件正文或容器；
+- 不清理 main/shared KB；
+- 不把现有项目 ID 清单视作删除授权。
+
+## 步骤
+
+1. [x] 只读统计三环境 schema、项目/关键表规模和 dev 文件规模。
+2. [x] 审计项目外键闭包、revision/CAS/workspace 孤儿风险。
+3. [x] 审计现有 backup/restore drill 能力与隔离缺口。
+4. [x] 制定数据分类、最小保留集、migration corpus 和蓝绿轮换方案。
+5. [x] 更新父整改、CURRENT、gap 与 remediation 索引。
+6. [x] 并入最终成果保险库、终态 coverage 和受控部分恢复边界。
+
+## 验收标准
+
+- [x] 明确说明建议合理的条件和不能替代 migration 的边界。
+- [x] 首轮 retain 建议基于能力覆盖，不按时间盲留。
+- [x] 方案包含备份配对、真实 restore、选择性导入、reload/rebuild、rollback 和延迟销毁。
+- [x] 本轮未实施破坏性操作。
+- [x] 明确最终成果保险库、migration corpus 和完整 DB+state backup 三者互补且分别验收。
+
+## 相关链接
+
+- Research: [../research/2026-09-14-runtime-data-retention-and-migration-corpus.md](../research/2026-09-14-runtime-data-retention-and-migration-corpus.md)
+- Remediation: [../../remediation/2026-09-14-runtime-data-lifecycle-and-migration-corpus-remediation.md](../../remediation/2026-09-14-runtime-data-lifecycle-and-migration-corpus-remediation.md)
+- Final Artifact Vault: [../../remediation/2026-09-14-final-artifact-vault-remediation.md](../../remediation/2026-09-14-final-artifact-vault-remediation.md)
+- Test report: 待用户批准实施后创建
+
+## 证据 / 备注
+
+- dev schema 33 / 366 projects / 主仓状态约 100MB；test schema 29；main schema 25。
+- `DELETE projects` 无法完整清理 task run、revision ledger、blob 与文件状态。
+- 首选新 green DB/state root 导入 retain allowlist，旧 blue 只读隔离后延迟销毁。

.doc/ops/short-term/2026-09-21-go-agentx-runtime.md

@@ -0,0 +1,66 @@
+---
+title: "Go 原生 PI Agent 运行时（pi-native 并存验证）"
+status: in_progress
+created: 2026-09-21
+updated: 2026-09-21
+owner: Cursor
+branch: feature/go-agentx-runtime-2026-09-21
+worktree: .worktrees/go-agentx-runtime-2026-09-21
+base_dev_sha: a5ea469ca44171a5c3e6419b1757852270fb991d
+write_scope: [internal/agentx, internal/agent, internal/config, internal/taskrun, internal/workspace, internal/server, cmd, deploy/postgres/goose, tools/cursor-bridge, .doc/ops, .doc/status, .doc/audit, .doc/test-reports]
+head_sha: 5d77e9cf
+deployment: pending
+cleanup: pending
+mutex: agent-backend-swap
+---
+
+# Go 原生 PI Agent 运行时（pi-native 并存验证）
+
+## 目标
+
+在主服务进程内实现 Go 智能体运行时，以新后端名 `pi-native` 与容器 `pi-agent` 并存；移除未使用的 cursor 后端；经双后端对比达到同等或更好后再切默认，否则保持 `AGENT_BACKEND=pi-agent`。
+
+## 范围
+
+- `internal/agentx`：OpenAI 兼容流式客户端、工作区工具、agent loop、JSONL transcript
+- `internal/agent/pinative.go`：`agent.Backend` 适配，名称 `pi-native`
+- 移除 `cursor-cli` 与 `tools/cursor-bridge`
+- 工作区注册、TTL/配额 GC（清理仍受冻结清单与 receipts 门禁约束）、管理端点
+- 双后端对比判定套件
+
+## 非目标
+
+- 删除 `deploy/pi-agent/`、`PiAgentBackend`、runner 契约与 compose 中的 pi-agent 服务
+- 在对比未通过时修改 `AGENT_BACKEND` 默认值
+- 模板文档生成与智能体小队动态编排
+- 在本 worktree 内执行 `env-service`
+
+## 步骤
+
+1. [x] 从 dev `a5ea469ca44171a5c3e6419b1757852270fb991d` 创建 worktree
+2. [x] LLM 流式客户端与契约测试
+3. [x] 工具 jail 与 hook
+4. [x] agent loop 与 JSONL 会话
+5. [x] `pi-native` 接线并移除 cursor
+6. [x] 工作区注册表、GC、管理端点
+7. [x] 双后端对比；未达标则不切默认
+8. [x] 报告、FEATURE-MATRIX、CURRENT 收口
+
+## 验收标准
+
+- [ ] `go vet ./...` 通过；`go test -short ./...` 未全绿（见报告第六节，失败在既有 import 与共享 dev 库）
+- [x] `AGENT_BACKEND` 默认仍为 `pi-agent`（对比未判定为同等或更好）
+- [x] 判定标准已执行：成功率 1.00≥0.33、P0=0、P95 16.616s > 1.3×6.926s，不切换
+- [x] cursor 后端代码与配置已移除；pi-agent 容器链路仍保留
+
+## 相关链接
+
+- Checklist: 
+- Handoff: 
+- Test report: `.doc/test-reports/2026-09-21-go-agentx-runtime-test-report.md`
+
+## 证据 / 备注
+
+远端同步状态：创建时主目录为本地 `dev`，ahead of `origin/dev`，未为创建任务执行 fetch/pull。
+
+对比未过 P95 门槛后，用户决定先不把时延作为切换条件：dev 启用 `pi-native`，失败时在进程内回退到容器 `pi-agent`。test/main 的 compose 默认仍是 `pi-agent`。`deployment` 在主目录 rebuild 之后再记。

.doc/ops/short-term/2026-09-21-intent-confirm-stage-aware.md

@@ -0,0 +1,41 @@
+---
+title: "意图确认优先与阶段感知消解"
+status: done
+created: 2026-09-21
+updated: 2026-09-21
+owner: Cursor
+branch: fix/intent-confirm-stage-aware-2026-09-21
+worktree: .worktrees/intent-confirm-stage-aware-2026-09-21
+base_dev_sha: 49fb68fec1ea56f00616c23d08efb15950c2300d
+mutex: intent+web+docgov
+---
+
+# 意图确认优先与阶段感知消解
+
+## 目标
+
+商务流初期「整理一下需求」等弱写表述 → 阶段感知消解为 intake，经确认卡片拍板后再执行；不强指令误伤。扩展已合入的工作流作用域修复。
+
+## 范围
+
+- 批次5 `feat(intent)`：弱写动词 + `stageAwareRequirementsTask` + `needs_confirmation`
+- 批次6 `feat(coordinator)`：智能确认门禁（PendingExpectation）
+- 批次7 `feat(web)`：阶段错误降级聊天一次
+- 批次8：验收报告 + 合回 `dev` + 真实 PI 抽样
+
+## 步骤
+
+1. [x] 批次5–7 实现与单元门禁
+2. [x] 批次8：合入 `dev@0c401904` + rebuild + 真实链路抽样（陈威项目 6579）
+
+## 验收标准
+
+- [x] V0.1「整理一下需求」→ 确认 →「好」→ intake（单元 + 真实 PI）
+- [x] 强指令不强制确认；「编写用户需求表」无 rdev 误拦
+- [x] 合入后真实 PI 抽样（见测试报告）
+
+## 相关链接
+
+- Plan: `~/.cursor/plans/意图确认优先与阶段感知_7ab2c4d5.plan.md`
+- Prior (done): `.doc/archive/ops/2026-09-21-intent-workflow-scoping.md`
+- Test report: `.doc/test-reports/2026-09-21-intent-confirm-stage-aware-test-report.md`

.doc/ops/short-term/2026-09-21-workflow-scope-weighting.md

@@ -0,0 +1,59 @@
+---
+title: "工作流作用域权重化"
+status: done
+created: 2026-09-21
+updated: 2026-09-21
+owner: Cursor
+branch: feature/workflow-scope-weighting-2026-09-21
+worktree: .worktrees/workflow-scope-weighting-2026-09-21
+base_dev_sha: 10aee3feb478c550adc9959f2d3a8d17cd5b48a0
+write_scope: [internal/workflowscope, internal/intent, internal/server, internal/coordinator, internal/config, internal/sysadmin, web/src, docker-compose.dev.yml, docker-compose.test.yml, docker-compose.main.yml, .env.example, .doc]
+head_sha: 7723a5515948788602b342cdda1137c90fee311b
+deployment: deployed
+cleanup: pending
+mutex: intent+web+docgov
+---
+
+# 工作流作用域权重化
+
+## 目标
+
+把「句子里出现他流文档短语就硬拦截」改为「匹配质量 × 工作流关系权重」裁决。激活流优先；只有他流精确命中明显压过激活流时才跨流。只读跨流在查看权限通过后放行并注明归属；写动作仍引导到项目设置切换（跨流写在现架构下不可执行）。`WORKFLOW_SCOPE_MODE` 默认 `strict`，保持现状。
+
+## 范围
+
+- 新建 `internal/workflowscope`（开关、关系权重、打分裁决）
+- 服务端文档读取、意图填槽、前端模板匹配改用同一裁决
+- compose / `.env.example` / sysadmin 登记开关
+- dev 真实环境验收与测试报告
+
+## 非目标
+
+- 不迁移 `document_records`，不加 `workflow_instance_id`
+- 不改工作流切换 / 激活接口
+- 不改 `production_ready`，不晋升 test/main，不动项目 143
+
+## 步骤
+
+1. [x] 打分内核与开关
+2. [x] 服务端只读跨流放行与查看权限
+3. [x] 意图填槽改打分
+4. [x] 前端模板匹配改打分
+5. [x] 开关声明、真实验收、报告、合回 dev
+
+## 验收标准
+
+- [x] strict 模式与现有跨流拦截断言一致
+- [x] weighted 下激活流精确名压过他流短语，不再误拦
+- [x] weighted 下只读精确点名他流文档可放行并注明归属；写动作仍拦截
+- [x] 无查看权限 / 实例已关闭时跨流只读拒绝
+- [x] 空激活键不过滤
+
+## 相关链接
+
+- Plan: `~/.cursor/plans/工作流作用域权重化_411b5e35.plan.md`
+- Test report: `.doc/test-reports/2026-09-21-workflow-scope-weighting-test-report.md`
+
+## 证据 / 备注
+
+查看权限：治理实例 `ViewableTaskKeys` 只含当前实例已启用文档。他流任务键不在快照内，不能把它当成「显式隐藏」。判定为：解析失败按 `failClosedAuthz` 拒绝；`ViewableTaskKeys` 为空（实例已关闭）拒绝；键落在当前实例但不可见则拒绝；键不属于当前实例、且调用方已能查看该实例文档时允许只读。

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

@@ -0,0 +1,168 @@
+---
+title: "当前解耦审查与跨项目模块契约规范"
+task_id: modular-contract-standard-2026-09-22
+status: done
+created: 2026-09-22
+updated: 2026-09-23
+owner: Codex
+task_type: research
+task_tier: multi_stage
+policy_revision: "agent-governance-2026-09-21-r1 @ d034aa00e5785f51234b484f9dca6bf4fb037660"
+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/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: pending
+deployment: not_required
+cleanup: retained-with-reason
+cleanup_owner: 独立维护者
+cleanup_trigger: 本地 dev 集成完成且 owner 退出后由独立维护者复查
+remote_sync: not_requested
+---
+
+# 当前解耦审查与跨项目模块契约规范
+
+## 用户目标与授权
+
+2026-09-22 用户要求：“梳理当前系统，看系统的多模块、功能之间的解耦做的如何，并制定规范（和本项目无关的通用规范）”，重点为统一封装、HTTP/Socket/IPC/RPC 通信、接口契约、总线调度、并发数据完整性和幂等，并形成设计规划。交付终点是可审研究与规范草案。允许隔离任务区写文档、只读源码与官方资料检索；不实施业务代码、不部署、不操作数据库、不 push。
+
+本次是跨项目标准的新研究任务，引用 2026-09-20 项目专用审查作为输入，不代替原 A–G 整改任务、不改变现行 ADR。用户 AGENTS 指定的 .doc taxonomy 优先于技能默认 docs/plans 目录。研究阶段保留共享主目录原有三项未跟踪 promotion receipts；后续经用户确认归档，见集成结果。
+
+## 产物与步骤
+
+1. 当前源码证据：[解耦现状](../../audit/2026-09-22-module-decoupling-current-state.md)。
+2. 可独立复用的规范：[通用模块契约规范](../../system-design/2026-09-22-generic-module-contract-standard.md)。
+3. 平台封装与渐进采用：[落地方案](../../remediation/2026-09-22-modular-platform-adoption-plan.md)。
+4. 文档交叉审阅、路径与差异检查；本记录承载验证和交接。
+
+## 基线与验证计划
+
+- 本地 dev 完整 SHA 见 frontmatter；创建时 origin/dev...dev 为 0 / 6，仅本地 remote-tracking 比较，未 fetch，不能作为远端实时状态。
+- 两个只读子审查共用父任务：coupling_evidence（模块边界），bus_evidence（事件与事务），不独立写入。
+- 实际环境未验收；本次只做源码证据与文档验证，不运行 Go/PG/PI/浏览器测试。
+- 不更新 FEATURE-MATRIX/gap-matrix：本次不改变模块能力与发布 blocker 声明。
+- 检索记忆仅用于导航与流程提醒；现状结论须回到当前源码核实。
+
+## 验证与收口
+
+本次研究交付完成；用户后续明确要求“合入 dev”，review_state=approved 仅表示同意文档入库，规范仍为 proposed，不自动启用为项目强制规则。用户后续可直接围绕同一 task_id 审阅/修订；业务实施另立授权任务。
+
+### 实际检查
+
+| 范围 | 实际检查 | 结果及限制 |
+|---|---|---|
+| 固定源码 | 两个只读子审查 + 主审核对 dispatcher、producer、worker 与 ADR | 现状报告保留路径及行号；不等于运行验收 |
+| 文档链接 | Python 逐项解析四文档本地 Markdown 链接 | 8 条本地链接存在，0 错误 |
+| 文档结构 | Python 检查 fenced block、行尾空白、末尾换行、路径可移植性 | 0 错误；Mermaid 结构人工检查，未调用渲染器 |
+| 稳定 ID | Python 检查规范 MCS-01–22 与计划 U1–U8 | 唯一且完整 |
+| 差异 | git diff --check；git diff -- .doc/ops/CURRENT.md | 无空白错误；CURRENT 仅本任务行，使用 CAS 收据 |
+| 运行与业务 | Go/arch-check/PG/PI/浏览器/部署 | 本次不适用，未执行；不报告产品 PASS |
+| 研究阶段主目录 | git rev-parse dev 与 git status --short | 当时 dev 为基线 SHA，原三项未跟踪 promotion receipts 保留；后续结果见集成节 |
+
+所有新增文件也由 Python 检查，避免 git diff --check 不覆盖 untracked 的盲区。只保存源码定位、文档检查结果与公开官方资料链接，不保存业务正文、秘密或环境值。
+
+### 文档审阅记录
+
+使用 ce-plan 与 ce-doc-review 的非交互文档审阅流程，三位当前会话子审阅者各承担两种视角；同一审阅者内部的两个视角不计为独立印证。六种视角为 coherence、feasibility、security、adversarial、product、scope。未运行外部 CLI 跨模型复核，不以此作为验证证据。
+
+| 原始 finding 与证据 | 主审判定及实际修正 | 复核 |
+|---|---|---|
+| feasibility，P2/75：U2 仅依赖 U1，却要求持久结果查询；持久收据归 U3 | 接受。U2 区分开发与最终验收依赖；U3 明确单次命令收据及授权查询，U5 管多步流程 | 原审阅者局部只读确认已解决 |
+| security，P2/75：不可信插件只有进程/资源隔离，不能阻止同 UID 访问宿主秘密 | 接受。MCS-01 后补最小权限、文件/网络限制和不继承秘密；U5 增访问拒绝负例 | 原审阅者局部只读确认已解决 |
+| scope，P2/75：所有系统统一要求数据库/队列等验收会强加无用设施 | 接受。规范 §8.1 按能力适用，区分 N/A 与 SKIP；U1/U6 同步 manifest 与门禁 | 原审阅者局部只读确认已解决 |
+| coherence / adversarial / product | 未返回达到行动门槛的 finding | 无需修改 |
+
+审阅结果：applied=3，proposed_fixes=0，decisions=0，fyi=0。主审另补规范 §2.2 功能设计卡与前端状态边界，与用户“功能、模块区分”一致，经局部复核未发现矛盾。实施前的仓库/owner/试点/SLO 仍须补齐，属于方案明确的后续立项条件，不伪装为已完成。
+
+### 产物身份（前轮合入时）
+
+| 文档 | SHA-256 |
+|---|---|
+| audit/2026-09-22-module-decoupling-current-state.md | d73bb9fddc0d88d4848dc711b67fdaac52b9d9383bf7c1938e9ed26f46ca8187 |
+| system-design/2026-09-22-generic-module-contract-standard.md | a47e4e1a59a31c350ffae936602116f3e944e011d005e7e6237ac11d06b74c19 |
+| remediation/2026-09-22-modular-platform-adoption-plan.md | 5d4f7c7bcd03e8510f07661f4f05a5adaf974145b1667ae1d70a31d02c770609 |
+
+### 交接
+
+- 影响：新增三份研究/规范/规划文档与本任务记录；CURRENT 仅本任务认领行，经受控集成进入 dev；不改业务、原生效规范、FEATURE-MATRIX 或 gap-matrix。
+- 本地保存：研究完成时文档未提交；后续用户授权本地 dev 集成，执行状态与证据见下节。
+- 部署：not_required；运行制品未检查、未修改。
+- 远端：not_requested，未 fetch/push；创建时 local tracking 比较 0/6，不能代表实时远端。
+- 清理：retained-with-reason。保留任务与集成 worktree，待集成完成且 owner 退出后由独立维护者核对，不满足门禁不得删除。
+- 后续实施必须重新核验 dev 与生效规则；通用平台线和当前项目 CP1–CP6 分开立项，不能把本次“研究完成”理解为实施授权。
+
+## 2026-09-22 本地 dev 集成续办
+
+授权来源：用户后续指令“合入 dev”。交付扩展为本地提交、独立候选验证、受控推进 dev；不 push、不部署、不实施方案。基线仍为 d034aa00e5785f51234b484f9dca6bf4fb037660，已重读相同生效规则，无规则差异。
+
+逻辑 task_id 沿用原值；原机器登记已关闭且工具不支持 reopen，使用执行登记 modular-contract-standard-2026-09-22-integration-prep，范围仍为原五份文档。为接续原任务 CURRENT 行，登记 docs:admin 但仅对该行使用 CAS，不改布局/其他任务/集成槽位。原 CURRENT 内容已保存在本机临时备份，核实相对 HEAD 只有本任务一行后重新发布取得续办收据。
+
+候选执行登记 integrate-modular-contract-standard-2026-09-22，分支 feature/integrate-modular-contract-standard-2026-09-22，同名 .worktrees 路径，scope 为本任务五文档，能力仅 git:dev。从上述确切 dev 创建 --no-ff 候选；冻结 SHA 由 Git merge 父节点及 agentctl validate/integrate 收据记录。验证为文件白名单、相对链接、ID、内容哈希、CURRENT 单行差异与 git diff --check；普通文档无须 Go/PI 或容器重建。
+
+集成前障碍：主目录保留三项非本任务未跟踪 promotion-receipts，clean_source 对集成不适用构建证据例外。按 AGENTS 不擅自移动他人未提交文件；先完成可审候选，再处理该障碍，不绕过 hooks 或清洁检查。
+
+### 集成结果与证据归档
+
+用户在针对三项未跟踪证据的明确归档请求后回复“继续”，授权按原样归档、校验后继续集成。归档前再次核实 dev 基线、三个对象清单及此前计算的清单摘要，无变化；以同文件系统 rename 保留原文件，归档后逐个核对 11 个文件的大小和 SHA-256，合计 16960 字节。未读取或修改 .env。
+
+- 本地文档提交：9814a67ee61dd97a31b104135c354f3ac0850bfc。
+- 首次集成候选/实际 dev 合入：3f89eff70af427cbf3649b6d079a03ebfc2c65e2；父节点为原 dev 基线及上述文档提交。
+- 候选验证收据：9e10402e-ce43-4a5e-a421-d01fc471b568，8 条本地链接、3 份核心文档哈希、22 条规则、8 个单元、五文件白名单与 CURRENT 单行差异通过。
+- 原样归档收据：a1aec604-dd4c-4d5a-b84d-abe6fb0e044a。完整清单及原路径映射位于主仓 .locks/evidence-archive/modular-contract-standard-2026-09-22/manifest.json；三个对象和 11 个原始文件均实际保存在同目录，不只记录旧路径。
+- 受控集成收据：c84f146c-8c05-4f9c-bc5f-b4aafef6b808，status=merged。主目录以 --ff-only 接收已验证的 --no-ff 候选，未绕过门禁。
+- 本节是首次成功集成后的收口记录，另作纯文档提交，通过同一候选工作区从 3f89eff7 基线构造新 --no-ff 节点并重新验证后集成；最终提交由 Git 历史及机器收据定位，避免自引用 SHA。
+- 原证据恢复：确有原路径消费者需要且目标路径不存在时，由后续获授权维护者依据 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/ops/short-term/2026-09-23-agentctl-cursor-integration.md

@@ -0,0 +1,47 @@
+---
+title: "agentctl Cursor 能力层集成"
+task_id: agentctl-cursor-integration-2026-09-23
+status: done
+created: 2026-09-23
+updated: 2026-09-23
+owner: Cursor
+task_type: implementation
+task_tier: single
+policy_revision: "agent-governance-2026-09-21-r1 @ 357e4ddb0fe62e12cf6d1321382376257b0fe674"
+branch: feature/agentctl-cursor-integration-2026-09-23
+worktree: .worktrees/agentctl-cursor-integration-2026-09-23
+base_dev_sha: "357e4ddb0fe62e12cf6d1321382376257b0fe674"
+write_scope: [".cursor", "scripts", ".doc", ".gitignore"]
+allowed_environments: []
+mutex: agentctl-cursor-integration
+review_state: accepted
+integration_state: merged_local_dev
+deployment: not_required
+cleanup: pending
+cleanup_owner: "独立维护者"
+cleanup_trigger: "合入 local_dev 且无进程占用后复查"
+remote_sync: not_requested
+---
+
+# agentctl Cursor 能力层集成
+
+## 落地
+
+| 项 | 值 |
+|---|---|
+| feature | `07094d0d` |
+| merge（daemon） | `9e4ddfcd`（第一父 `357e4ddb`） |
+| 测试 | MCP 9 tools + hooks ask/allow + skills frontmatter；unittest 134/3 skipped |
+| 证据 | [evidence/](../evidence/2026-09-23-agentctl-cursor-integration/) |
+
+启用：Reload Window / 重载 MCP；跟 skill `agentctl-session-start`。规范文：[2026-09-23-agentctl-cursor-integration.md](../2026-09-23-agentctl-cursor-integration.md)。
+
+## 收口
+
+| 字段 | 值 |
+|---|---|
+| review_state | accepted |
+| integration_state | merged_local_dev |
+| deployment | not_required（Cursor 能力层无运行制品；daemon 此前已 loaded） |
+| cleanup | pending |
+| remote_sync | not_requested |

.doc/ops/short-term/2026-09-23-chat-semantic-d3-closeout.md

@@ -0,0 +1,54 @@
+---
+title: "chat-semantic-d3 收口（拆行 + tip 重验）"
+task_id: chat-semantic-d3-closeout-2026-09-23
+status: done
+created: 2026-09-23
+updated: 2026-09-23
+owner: Cursor
+task_type: implementation
+task_tier: small
+branch: feature/chat-semantic-d3-closeout-2026-09-23
+worktree: .worktrees/chat-semantic-d3-closeout-2026-09-23
+write_scope: [".doc/**", "internal/app/**", "internal/app/chatflow/**"]
+mutex: chat
+base_dev_sha: "9d8332ad0892adf147cb31da358ed01ad3e503fa"
+policy_revision: "AGENTS+worktree-ops @ 9d8332ad"
+remote_sync: not_requested
+review_state: accepted
+integration_state: merged_local_dev
+deployment: not_required
+cleanup: pending
+---
+
+# chat-semantic-d3 收口
+
+## 目标
+
+审查原 PU6 方案：REPLACE 被 Wave5 X-2 密封导致行无法 done。收窄 `chat-semantic-d3` 为 shadow 能力并升 done；REPLACE 迁出为 `chat-semantic-replace` deferred；当前 tip 重验 + 修复 reasoning 真 PI 回归。
+
+## 范围
+
+- 文档：FEATURE-MATRIX 拆行 + short-term + 测试报告
+- 代码：`PiSemanticSummarizer` reasoning 叙事回落；chatflow 测试异步 drain
+- 非目标：不接线 REPLACE；不 push；不改 gap-matrix；不晋升 test/main
+
+## 边界 lineage（before → after）
+
+| 行 | before | after | 义务去向 |
+|---|---|---|---|
+| chat-semantic-d3 | partial；声明含 shadow→可选 REPLACE | done；仅 durable shadow + 确定性 served | REPLACE → `chat-semantic-replace` |
+| chat-semantic-replace | （无） | deferred；关闭=独立授权+fail-closed | Wave5 X-2 |
+
+## 验证
+
+见 [测试报告](../../test-reports/2026-09-23-chat-semantic-d3-closeout-test-report.md)。
+
+## 五态（收口时更新）
+
+| 字段 | 目标值 |
+|---|---|
+| review_state | accepted |
+| integration_state | merged_local_dev |
+| deployment | not_required |
+| cleanup | pending |
+| remote_sync | not_requested |

.doc/ops/short-term/2026-09-23-coordination-db-daemon-research.md

@@ -0,0 +1,130 @@
+---
+title: "多主机 Agent 数据库协调机制调研"
+task_id: coordination-db-daemon-plan-2026-09-23
+status: done
+created: 2026-09-23
+updated: 2026-09-23
+owner: Codex
+task_type: research
+task_tier: multi_stage
+policy_revision: "agent-governance-2026-09-21-r1 + systemic-issue-analysis-2026-09-23-r1 + issue-learning-2026-09-23-r1 @ a0fd52a6276b1b531df9ba53e329a645cf8527c9"
+branch: feature/coordination-db-daemon-plan-2026-09-23
+worktree: .worktrees/coordination-db-daemon-plan-2026-09-23
+base_dev_sha: a0fd52a6276b1b531df9ba53e329a645cf8527c9
+write_scope:
+  - .doc/ops/short-term/2026-09-23-coordination-db-daemon-research.md
+  - .doc/remediation/2026-09-23-coordination-db-daemon-plan.md
+  - .doc/audit/ISSUES.md
+allowed_environments: []
+mutex: coordination-db-daemon-plan-docs
+review_state: approved
+integration_state: merged
+deployment: not_required
+cleanup: retained-with-reason
+cleanup_owner: 独立维护者
+cleanup_trigger: 用户审核及后续集成结束、owner 退出后复查
+remote_sync: not_requested
+---
+
+# 多主机 Agent 数据库协调机制调研
+
+## 用户目标与授权
+
+用户要求深入核查所附 SQLite/分布式数据库报告，评估将任务认领、执行、文档状态放入数据库，制定非容器 daemon 方案；后续明确“多台主机需要共同协调”。授权终点为可审研究与实施方案，不含安装服务、业务编码、迁移现有状态、恢复旧操作、部署、push 或 dev 集成。
+
+基线主目录干净；本地 dev 如 frontmatter。首次本地引用比较为 ahead 18 / behind 245（相对 origin/dev 的本地缓存；未 fetch，不表示当前远端实况）。检查已有 worktree 与机器登记后，通过现行 agent-worktree/agentctl 创建并登记本任务；不修改别人现场。
+
+## 范围与相关经验
+
+研究 scripts/agentctl.py、agent_worktree.py、相关 hooks/tests 和 CURRENT/FEATURE-MATRIX 的权威边界；检索词：认领、锁、并发、CAS、agentctl、governance、CURRENT、FEATURE-MATRIX。ISSUES/lessons 索引无直接同机制历史项；正文 hash 经验与投影保持语义有关，后续复核。研究型子审查共用本记录，均只读。
+
+本方案优先遵守仓库 .doc taxonomy，成果放 remediation；不采用 ce-plan 默认 docs/plans 路径。CURRENT 是现行协调快照，机器 task register 是本次启动登记；本轮不为调研改写共享快照或模块能力声明。
+
+## 研究步骤与验收
+
+1. 核对现行 SQLite/文件锁、认领/执行、文档 CAS 实现及真实只读状态。
+2. 官方来源核实报告技术结论，按多主机需求比较方案。
+3. 明确权威数据、事务与执行边界、失联恢复、daemon 运维和迁移。
+4. 文档审查、链接/一致性检查，交付方案；不执行实现测试。
+
+## 验证与交接
+
+研究已完成，用户已授权文档合入 dev；实施尚未授权。方案入口： [实施方案](../../remediation/2026-09-23-coordination-db-daemon-plan.md)。
+
+## ISSUE-20260923-coordination-authority
+
+- issue_state: investigating；severity: high；owner: Codex（研究）；recurrence_count: 0；登记日 2026-09-23。
+- 预期：所有 Agent 对认领归属和共享文档状态读取相同权威；冲突尽早可见，不在合并时才暴露。
+- 实际/触发：用户报告读写 FEATURE-MATRIX/CURRENT 与认领容易出问题。源码确认 docs snapshot/apply 读各自 worktree 的副本，scope 注册不含跨任务长期排他；跨主机还超出现有 L1 声明范围。
+- 机制证据：scripts/agentctl.py:173–185 主仓唯一 SQLite；219–236 写事务；310–329 数据模型；639–688 当前副本文档 CAS；999–1028 task 注册/关闭；scripts/tests/test_agentctl.py:322–341 测试预期主仓文档保持旧值。
+- 已证实：上述实现边界；数据库已存在；CURRENT 与机器状态独立。未证实：用户具体哪次冲突的丢写、实际发生频率、SQLite 写吞吐瓶颈；未做复现或故障注入，不称为已修复。
+- 因果链：分散 worktree 基线 + 本地行 CAS → 各副本可以分别合法更新 → Git 集成再解决分歧；scope 许可 + 短操作锁 ≠ 长期任务归属；单主机身份与 flock ≠ 跨主机协调。
+- 同类检查：CURRENT 与 MATRIX 都走本地副本 CAS；task register/close 与 Markdown 状态双轨；docs:publish 粒度为全局文件写回；worktree create 与 register 分开；Git/环境外部副作用无法加入数据库事务。
+- 影响边界：工程协调工具、任务归属、状态投影、未来跨主机接入；未对产品数据库/运行链路作故障结论。
+- 已有防护为何未覆盖：现行 L1 明确只覆盖本机入口、操作锁和副本 CAS；现有测试并未声明验证跨 worktree 全局记录或跨主机长期 claim。
+- 推荐处理：[方案](../../remediation/2026-09-23-coordination-db-daemon-plan.md)；不以数据库换型单独宣称解决。待实施后用两旧 worktree 同版本更新、两主机认领与旧 writer 存活恢复等验收。
+- 本次时间线：只读定位现机制 → 用户明确多主机 → PostgreSQL/daemon 主方案与 SQLite API 备选 → 设计与数据一致性复核；未开始修复。
+- 下一步/owner：用户审核方案后由实施 owner 逐 U1–U7 实施；issue 继续 investigating，研究任务完成不关闭问题。
+- 经验处理：采纳 LESSON-20260923-content-hash 的原文语义/投影恢复检查；没有修复验收，不新增 validated 经验。未来经故障注入与真实双机验收再提炼跨机协调 lesson。
+
+## 只读验证记录
+
+| 检查 | 当前证据 / 限制 |
+|---|---|
+| Git | 主目录 dev = a0fd52a6276b1b531df9ba53e329a645cf8527c9；启动时 tracked clean；origin/dev 本地缓存 ahead 18 / behind 245，未联网核验远端 |
+| agentctl status | version=1；唯一主仓 .locks；1 条 env:dev recovery_required、supervisor_alive=false；仅表示 supervisor 不存活，未核查 child/Docker/环境；未执行 recover |
+| 源码与测试 | 静态核对 Repo.db/Lease/docs/register/recover/hooks/worktree；未运行脚本测试，不将既有测试名记为 PASS |
+| 主机基础 | Linux；Python 3.14.7 内嵌 SQLite 3.53.4；systemd 259；pg_config 不在 PATH；未检查其他主机、服务账户权限或数据库服务可用性 |
+| 官方来源 | SQLite、PG、rqlite 等官方文档/项目 README；链接见方案；性能结论均待实测 |
+| 保全与敏感数据 | 只记录判断所需代码位置及最小状态；未读取 .env，未保存凭证/业务正文，未修改真实环境 |
+
+## 专项复核及处置
+
+对 Deep/跨机状态迁移方案进行了架构与数据一致性两个独立只读专项复核；不是运行验收。原始可判定结论及处置如下，5 项均已纳入现有授权的方案修订：
+
+| 来源 / 级别 | 原文与具体风险 | 处置及复核依据 |
+|---|---|---|
+| 架构 P1 | “已确认提交丢失 0”与异步备份“RPO ≤5 分钟”范围不清 | 限定零丢失为持久盘完整的进程/网络故障；灾难恢复按真实 RPO；两类验收分开，不暗含同步异地复制 |
+| 架构 P1 | 跨机 Git 对象/远端 PASS 不能满足本机 task/worktree HEAD + candidate receipt | 依据 agentctl.py admit_candidate/integrate，U4 增加本机 integration task/worktree 构造两父候选、精确验证及 expected-dev 再核对 |
+| 数据 P1 | 旧备份没有备份点之后已成功 operation 的 request_id/tombstone | 恢复屏障遍历 executor journal/目标收据，回填结果或 tombstone；未知不重放、失联主机隔离；加入备份后成功再恢复原 ID 重试测试 |
+| 数据 P2 | 恢复低位事件序号时旧高位 cursor 会漏更新，旧同号 generation 可能误去重 | 事件 cursor、projection identity、manifest/Git receipt 加 authority_epoch；错误 epoch 强制重建 snapshot |
+| 数据 P2 | U7 导入矩阵后旧已审/已提交 candidate 迟到集成，会破坏 DB 权威 | 增加 matrix authority_version 与独立 drain barrier；最终集成校验版本，覆盖 approved/committed/待 integrate 三种在途情形 |
+
+主审另补：迟到 heartbeat 不复活过期/quarantined lease；父子路径共享实际执行域的代次；heartbeat/投影回执不递归产生文档发布；proposals 从 U5 起、feature_records 从 U7 起，避免阶段矛盾。
+
+完成后确认每项已写入方案对应章节与 U-ID 验收。方案 SHA256：fc0f0959298f5589bf7300026322c24528bc69081c2de8e54cf84737a71b8812。
+
+ce-plan 要求的正式 ce-doc-review 调用结果：`fixes_applied=0, proposed_fixes_count=0, decisions_count=0, fyi_count=0, skipped_reason=skill_unreachable`。本会话没有可调用的通用技能执行入口，未用 generic subagent 冒充该技能调用；ce-doc-review 未运行。上述为 ce-plan 自身授权的专项研究/复核，不将它描述为正式文档技能 PASS，也没有启动外部模型 CLI。下一次有该入口时可追加正式审查；本次研究证据足以支撑可审方案，首轮交付时用户 review_state 为 pending；后续文档集成授权见下节。
+
+## 首轮研究交付快照
+
+- 授权内研究完成：源码/只读状态、官方资料纠错、7 个实施单元、迁移/回退/验收与非容器运维设计均已落盘。
+- 文档检查：两主文档全部本地相对链接目标存在；R=10、KTD=7、U=7 无重复；六个契约章节存在；git diff --check 通过。未运行实现测试、压力测试、双主机或灾难恢复，不宣称系统已具备新能力。
+- 本地文件：2 个新增研究/方案文件、ISSUES 新增 1 条；尚未 commit，未合入 dev，未部署，未 push。主目录 tracked clean 且 dev 仍为基线 a0fd52a6276b1b531df9ba53e329a645cf8527c9。
+- 现行 CURRENT/FEATURE-MATRIX 未改动：没有模块声明变化；本任务通过 machine task register 登记并收口。问题 remains investigating，不伪关。
+- review_state=pending（用户方案审核）；integration_state=not_required（本轮交付终点为可审工作区文档）；deployment=not_required；remote_sync=not_requested。
+- cleanup=retained-with-reason：工作区含待审未提交研究成果，必须保留；独立维护者在用户审核、后续提交/集成与 owner 退出后复查，不自动删除。
+- 后续建议：审核主方案与首期可停机边界；获实施授权后从 U1–U2 隔离验证起步，跨机真实接入/安装前补齐主机清单、目标权限和备份故障域。采用本方案时同步修改 AGENTS/PROJECT/runbook/验证契约与矩阵权威说明，不能只新增 daemon。
+
+## 文档集成授权与执行
+
+用户随后明确要求：“合入dev，然后通过对话再把这个说明返回给我”。据此允许将本任务方案、研究记录与问题台账提交并受控合入本地 dev；不包含业务实施、服务安装、旧操作恢复、环境变更或远端 push。
+
+沿用 task_id=coordination-db-daemon-plan-2026-09-23；原机器登记已经关闭，现行工具不支持重新打开，故仅为执行登记新增 coordination-db-daemon-plan-2026-09-23-integration-prep，原主任务身份不变。owner=Codex；写范围仍为 frontmatter 的三份文件；mutex=coordination-db-daemon-plan-docs；环境权限为空。
+
+集成前重读 AGENTS/PROJECT/CURRENT、worktree 规范与验证契约；当前 dev 完整 SHA 与原基线相同，相关 policy 无差异。复核 ISSUES/lessons 无新增同机制条目；继续采用既有文本语义/投影一致性检查。主目录干净；远端仅本地缓存 ahead 18 / behind 245，未 fetch。
+
+review_state=approved 指用户批准文档进入 dev，不代表授权执行 U1–U7。当前 integration_state=pending；拟提交三份文档，在独立 integration worktree 以原 dev 为第一父节点构建 --no-ff 候选，按验证契约做纯文档检查后，经 agentctl integrate 锁内 --ff-only 推进 dev。实际 SHA、验证与集成收据于完成后补记。
+
+验证范围：变更清单仅上述三份文档；相对链接及锚点、问题 ID/状态一致、R/KTD/U 唯一、计划六契约、方案 hash 和任务记录一致、Markdown 表格连续性、git diff --check。此为文档集成，不运行产品/脚本实现测试、不重建容器。
+
+## 文档集成结果与最终交接
+
+- 用户授权范围内文档已于本轮合入本地 dev。源提交 `a542c21a420fbc8bb9f413abd3d4bc95ac655ccc`；首个受控合并提交 `6a0d721f362ed327f6cbd61a670c65c429961411`；第一父提交为 `a0fd52a6276b1b531df9ba53e329a645cf8527c9`，第二父提交为上述源提交。
+- 集成执行登记：`integrate-coordination-db-daemon-plan-2026-09-23`；branch=`feature/integrate-coordination-db-daemon-plan-2026-09-23`；worktree=`.worktrees/integrate-coordination-db-daemon-plan-2026-09-23`；owner=Codex；scope=本任务三份文档；capability=`git:dev`；mutex=dev 集成槽位；基线仍为原 dev。已重读相关生效规范，无差异。
+- 实際验证：通过 `agentctl validate` 在干净候选上运行文档校验；输入 base 为上述基线，HEAD 为上述候选。检查三份变更白名单、15 个相对链接、研究问题锚点/台账表格连续性、状态一致、10 个 R / 7 个 KTD / 7 个 U 唯一、六个计划契约、方案 SHA256、`git diff --check`；输出 `result=PASS`，退出码 0。方案正文 hash 未改变。
+- 验证收据 run_id=`d3c27ee9-d389-46f9-af67-ba7d3b4d7aba`；集成收据 run_id=`404fd3a6-7480-4540-a6bb-e7f0c6ce1ab7`，`status=merged`。收据可通过主仓 `agentctl operation` 查询。
+- 集成后主目录干净；本地 origin/dev 缓存当时 ahead 20 / behind 245，未 fetch、未 push；不得据缓存断言当前远端包含本次文档。
+- 本节作为集成证据后补提交，经同一候选流程独立验证后合入；最终 dev SHA 以实际 Git 与本次对话回执为准，避免自引用提交散列。
+- 最终状态：status=done、review_state=approved（仅文档集成）、integration_state=merged、deployment=not_required、remote_sync=not_requested、cleanup=retained-with-reason。工作区保留供后续实施；owner 退出后由独立维护者按门禁复查，不擅自清理。
+- 问题仍 investigating；方案 U1–U7 未实施。没有数据库安装/迁移、daemon 启动、运行环境变更或产品验证；文档合入不改变 CURRENT/FEATURE-MATRIX 的现行权威，也不表示跨机能力生效。

.doc/ops/short-term/2026-09-23-integrate-fav-final.md

@@ -0,0 +1,35 @@
+# integrate-fav-final-2026-09-23
+
+| field | value |
+|---|---|
+| status | in_progress |
+| owner | Cursor |
+| type | integrate |
+| base_dev_sha | 6032dbaa16ea8389ebe871c7e1e532c016d673e7 |
+| write_scope | . |
+| mutex | git:dev |
+| review_state | pending |
+| integration_state | pending |
+| deployment | not_required |
+| cleanup | pending |
+| remote_sync | not_requested |
+
+## Exception registry (FAV protection lift)
+
+| field | value |
+|---|---|
+| owner | Cursor |
+| reason | 用户 2026-09-23 明确授权「都推进至完成」并选择解除保护 |
+| overridden_clause | CURRENT「禁止整支 merge FAV」 |
+| scope | feature/final-artifact-vault 整支合入 local_dev |
+| exit_condition | 合入后 flag 默认关；MATRIX events-fav 保持 partial；live 不放量 |
+| restore_action | 合入后 CURRENT 修订为「FAV live 仍不放量；FAV_DEGRADED_READ 默认 false」 |
+
+## Migration note
+
+FAV branch ships ; local_dev already has
+. Renumber FAV migration to .
+
+## Goose renumber
+
+resolved: FAV branch 00034 dropped; local_dev already has equivalent 00036_final-artifact-vault.sql

.doc/ops/short-term/2026-09-23-issue-learning.md

@@ -0,0 +1,86 @@
+---
+title: 问题修复记录与开发经验闭环
+task_id: issue-learning-2026-09-23
+status: done
+created: 2026-09-23
+updated: 2026-09-23
+owner: Codex
+task_type: implementation
+task_tier: small
+policy_revision: agent-governance-2026-09-21-r1 + systemic-issue-analysis-2026-09-23-r1 @ 2fdb6e548e3784771f27e6a9e79b9c364f76c566
+branch: feature/issue-learning-2026-09-23
+worktree: .worktrees/issue-learning-2026-09-23
+base_dev_sha: 2fdb6e548e3784771f27e6a9e79b9c364f76c566
+write_scope: [AGENTS.md, PROJECT.md, .doc/README.md, .doc/audit/ISSUES.md, .doc/audit/2026-09-23-historical-issue-records.md, .doc/ops/lessons, .doc/ops/2026-09-23-issue-learning-workflow.md, .doc/ops/2026-09-21-policy-registry.md, .doc/ops/templates, .doc/ops/short-term/2026-09-23-issue-learning.md, .doc/ops/CURRENT.md]
+allowed_environments: []
+mutex: agentctl path leases; git:index for commits
+review_state: approved
+integration_state: merged
+deployment: not_required
+cleanup: pending
+cleanup_owner: owner 退出后的独立维护者
+cleanup_trigger: 本地交付及证据保存完成且 owner 退出后
+remote_sync: not_requested
+---
+
+# 问题修复记录与开发经验闭环
+
+## 用户目标与授权
+
+2026-09-23 本会话用户要求：“除了任务、新功能的设计和实施有 FEATURE-MATRIX 和 CURRENT 来进行管理”，还希望记录“出现的问题、修复记录、修复思路”，及时总结开发注意事项，使 AI 积累经验、减少重复错误。
+
+本轮落实仓库文档机制：问题台账、经验库、模板、Agent 开工/收口入口，完成文档检查及本地受控集成。只改登记范围内的工程规范和文档；不改业务代码、产品提示词、.env、运行环境或用户私有记忆，不 push。旧问题仅补录有来源证据，不扩大为历史全量审计。
+
+## 现状与选择
+
+当前 AGENTS 已有根因/同类分析要求，audit/INDEX 为历史审计目录，CURRENT 为活跃协调，FEATURE-MATRIX 为能力声明；缺少跨任务问题台账和按机制检索的开发经验入口。为保持文档分工，新建 audit/ISSUES 与 ops/lessons；复用现有任务/审计/报告，不再要求每次故障创建全部文档。
+
+问题事实、处理进度、经验成熟度分别用 issue_state、任务 status、lesson_state；记录推测与事实、失败尝试、关闭证据、复发和过时处理。该流程为 manual，不声称 AI 已自动学习或工具已强制执行。
+
+## 检索与来源
+
+检索词：经验、修复、问题、lesson、experience、postmortem、learning。起始工作区无相关经验索引；读取现行规范和相关历史审计/验收。首次补录 nullable-duty 与 content-hash 两类；本次历史问题事实以仓库报告为准，未用私有记忆替代证据。
+
+两条经验分别核对当前 engine 的 nullIfZero、canonicalize 委托和黄金样例存在；历史报告分清 API/PG 冒烟与真实 UI/重启证据。已采用检查：证据日期/范围、旧数据与新数据、未运行不报 PASS、规范入口单一来源。
+
+## 验证计划与结果
+
+纯文档：差异范围和空白；修改/新增文件相对链接与锚点；问题/经验 ID 唯一和互链；索引状态一致；Agent 入口及模板可达。情景自审包括新问题未定位、只分析、修复未部署、暂缓/重复、历史补录、复发、经验过时和无新增经验。不运行产品测试或共享环境操作。
+
+- `python3 /tmp/verify-issue-learning.py 2fdb6e548e3784771f27e6a9e79b9c364f76c566` 执行 git diff 空白/范围、pathlib 相对路径、Markdown 锚点、ID/状态及入口断言，输出：`PASS: 17 documents; 137 relative links/anchors; scope/whitespace; 2 unique issue/lesson pairs and matching states; client/template entrypoints`。临时检查器非产品代码；可按本节检查范围复核。
+- 人工审阅全部新增文档和差异，下面情景均有明确动作；review_state=approved 指本轮 Codex 自审，不是独立审查或未来 Agent 行为实测。
+- 首次临时检查错误地要求每条 Cursor 规则直接含 AGENTS；实际 test-reports-standard 转发统一验证契约。核对原规则后修正检查器，未修改客户端以迎合错误断言。
+
+| 情景 | 文档规定的动作 / 自审结果 |
+|---|---|
+| 新问题未定位 | open/investigating，记录假设/缺口和下一步，通过 |
+| 仅分析完成 | 任务 done 可成立，问题仍保留未解决状态，通过 |
+| 修复未部署 / 验收失败 | verifying 或回 fixing；不能误关闭目标环境问题，通过 |
+| 暂缓 / 重复 | deferred 有 owner/复查与依据；duplicate 链接唯一主 ID，通过 |
+| 历史补录 | 保留旧证据日期和范围，当前未复测；未补录全部历史，通过 |
+| 已关闭问题复发 | 重开原记录，保存旧关闭结果和防护失效原因，通过 |
+| 经验过时 / 冲突 | superseded/retired，保留替代与理由；现行规范优先，通过 |
+| 无新增经验 / 未验证 | 分别写理由或 candidate，不凑条目，通过 |
+
+未运行产品回归、浏览器、PG 或 PI；本轮验证仅为文档与引用源码阅读。证据摘要未复制业务正文、凭证或个人信息。
+
+## 状态与交接
+
+创建基线见 frontmatter。创建前主目录 dev 干净，已核对 worktree 列表和机器登记；唯一未恢复 operation 为其他任务 env:dev，与本轮文档写路径无交集，未操作它。本地缓存 origin/dev 比较为 ahead 14 / behind 245；未 fetch，不能表述为实时远端差异。
+
+本轮使用 writing-for-agents 指导条件读取与单一来源；未启动子 Agent。新增文档采用现有 taxonomy。FEATURE-MATRIX 和 gap-matrix 无相关声明变化，不修改。
+
+cleanup 保留任务及候选 worktree，供 owner 退出后独立维护者复查；所有本轮唯一证据保存本任务。文档验证与本地受控集成已完成；远端未请求同步，运行制品不受影响。
+
+
+## 本地集成证据
+
+- 实现提交：`ccf515c3b1c0d7fe1a46c5de5f58253fd4e946f7`。
+- 生效提交：`7bbd7a407f857515005c0324d90339017ea5f3e8`，第一父提交为基线 `2fdb6e548e3784771f27e6a9e79b9c364f76c566`。集成前核对 dev 与相关规则均未变化。
+- 候选 task/worktree：`integrate-issue-learning-2026-09-23` / `.worktrees/integrate-issue-learning-2026-09-23`，范围同本任务，能力 git:dev。
+- 精确候选验证：`agentctl validate --task integrate-issue-learning-2026-09-23 -- python3 /tmp/verify-issue-learning.py 2fdb6e548e3784771f27e6a9e79b9c364f76c566`；输出与上文一致；收据 `5cf25c46-a78f-473a-87a4-8095522e5f32` 绑定生效提交。
+- 集成命令：`agentctl integrate --task integrate-issue-learning-2026-09-23 --expected-dev 2fdb6e548e3784771f27e6a9e79b9c364f76c566` 返回 merged；收据 `8999b15f-14be-4081-ab4a-1db267f6ad11`。
+- 首次候选构造未申请 git:dev 执行租约，CURRENT 的 pre-merge hook 拒绝 `DOCUMENT_RECEIPT_REQUIRED`，随后 validate 因尚未提交而拒绝 DIRTY_TREE；主目录未改变。核对 hook 的 merge_has_dev_lease 和 MERGE_HEAD 后，仅撤销本任务未提交候选，在 git:dev + git:index 租约下重新构造并通过，未绕过 hooks。该操作失误及恢复在此保留；不另提炼经验，因为已有操作规范与机器门禁覆盖，后续构造须落实登记能力对应的执行租约。
+- 当前规范已 active/manual；本轮状态与收据更新另作收口提交，经相同候选流程验证后合入，Git 父链与候选 task 收据保留最终版本。
+
+交付满足文档范围验收，done；cleanup=pending，两处工作区保留，待 owner 退出由独立维护者复查。未执行 fetch/push、环境写操作或产品测试。后续按闭环逐次积累；全量历史迁移、自动检索和 CI 校验不在本轮交付范围。

.doc/ops/short-term/2026-09-23-module-batches-ag-status-fix.md

@@ -0,0 +1,91 @@
+---
+title: "module-batches-ag 状态回退修正与收口"
+task_id: module-batches-ag-status-fix-2026-09-23
+status: done
+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: "8768ee2ba26b60dbeb939c60f2b8e3d7dbf95001"
+mutex: module-decoupling-spec
+review_state: accepted
+integration_state: merged_local_dev
+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. [x] validate → integrate → 五状态收口（local_dev `8768ee2b`）
+
+## 验证与证据
+
+| 范围 / 被测 SHA | 命令与环境 | 预期 | 实际 / 判定 | 证据 / 脱敏说明 |
+|---|---|---|---|---|
+| 架构门禁 | `./scripts/arch-check.sh --mode block` @ candidate `8768ee2b` | PASS | PASS | 纯文档变更；Go 全量 / PI **NOT REQUIRED**（验证契约） |
+| MATRIX 行 | docs apply + snapshot | status=done | PASS（done） | record_id=`module-batches-ag`；main tip 已核验 |
+| 链接一致性 | 目标路径存在性 | 可达 | PASS | issue/lesson/A–G short-term / boundaries |
+
+## 收口与交接
+
+| 字段 | 值 |
+|---|---|
+| review_state | accepted |
+| integration_state | merged_local_dev @ `8768ee2b` |
+| deployment | not_required |
+| cleanup | pending（独立维护者） |
+| remote_sync | not_requested |
+
+- 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)

.doc/ops/short-term/2026-09-23-pi-narrative-final-closeout.md

@@ -0,0 +1,74 @@
+---
+title: "docgov-pi-narrative 收口：修复后复测升 done"
+task_id: pi-narrative-final-closeout-b-2026-09-23
+status: done
+created: 2026-09-23
+updated: 2026-09-23
+owner: Cursor
+task_type: implementation
+task_tier: small
+policy_revision: "AGENTS+worktree-ops @ 9d8332ad0892adf147cb31da358ed01ad3e503fa"
+branch: feature/pi-narrative-final-closeout-b-2026-09-23
+worktree: .worktrees/pi-narrative-final-closeout-b-2026-09-23
+base_dev_sha: "9d8332ad0892adf147cb31da358ed01ad3e503fa"
+write_scope: ["internal/app", "internal/sysadmin", ".doc"]
+allowed_environments: []
+head_sha: "c1b60b7af2ae8631ebfe9d6a052d4e82e076abae"
+mutex: docgov
+review_state: accepted
+integration_state: merged_local_dev
+deployment: not_required
+cleanup: pending
+cleanup_owner: "独立维护者"
+cleanup_trigger: "合入 dev 祖先且无进程占用后 remove"
+remote_sync: not_requested
+---
+
+# docgov-pi-narrative 收口：修复后复测升 done
+
+## 用户目标与授权
+
+- 用户目标：审查并调整既有方案，推进 FEATURE-MATRIX `docgov-pi-narrative` 从 `partial` 结束为 `done`。
+- 授权来源：用户确认「docgov-pi-narrative 收口计划（复测后升 done）」并指示实施。
+- 交付终点：修复后真实 PI 复测 + 测试报告 + MATRIX 升 done + 合入 local `dev`；不 push；不放量 flag。
+- 禁止项：不默认开启仓库/compose `PI_CHANGE_REPORT_NARRATIVE`；不改 gap-matrix / `production_ready`；不晋升 test/main。
+
+## 范围与非目标
+
+- 允许：补强 `TestPiChangeReportNarrator_LiveMiniMax`（含 hunks + flag-on Resolve）；sysadmin reason；MATRIX/CURRENT/pu7/short-term/test-report。
+- 非目标：dev 常驻开启叙事 flag；Playwright flag-on 全链路；触碰 Cline partial-deferred 总控实现。
+
+## 相关问题与经验
+
+- 开工检索：docgov / PI narrative / change_report_narrative / `--no-tools`。
+- ISSUES / lessons：无直接命中 PI 叙事；沿用 content-hash 投影经验（证据与状态分轨）。
+- 历史缺口（2026-09-20）：计数-only 输入、prompt-only no-tool → 已修；本轮补修复后真实链路复测。
+
+## 步骤与验收
+
+1. [x] 建场并认领 mutex `docgov`
+2. [x] 补强 live 测试输入与 flag-on Resolve 断言
+3. [x] 真实 PI 复测 + 前端分区 + vet/short/arch（live PASS @ MiniMax-M2.7-highspeed 7.65s）
+4. [x] MATRIX → done；CURRENT/pu7/sysadmin 同步
+5. [x] 测试报告归档；validate + integrate；五态收口
+
+## 验证与证据
+
+| 范围 / 被测 SHA | 命令与环境 | 预期 | 实际 / 判定 | 证据 / 脱敏说明 |
+|---|---|---|---|---|
+| live PI（进程 env flag） | `RUN_PI_E2E=1 … TestPiChangeReportNarrator_LiveMiniMax` | PASS；digest 原样；含截断差异 | PASS（7.65s） | [assets](../../test-reports/assets/2026-09-23-pi-narrative-closeout/live-minimax.txt) |
+| 前端分区 | `overlayMode.test.ts` | PASS | PASS（14） | [overlay](../../test-reports/assets/2026-09-23-pi-narrative-closeout/overlay-mode.txt) |
+| 门禁 | `go vet` / short narrative / `arch-check --mode block` | 全绿 | PASS | 收口报告 |
+
+## 收口与交接
+
+- review_state=accepted；integration_state=merged_local_dev（`c1b60b7a` 含证据 + MATRIX done）；deployment=not_required；remote_sync=not_requested；cleanup=pending（独立维护者）。
+- CURRENT 任务行已登记 done；`## 焦点` 为 protected section，仍写「PI 叙事 flag 不放量」——与「默认 off；放量另授权」同义，未强改 protected 文案。
+- cleanup 交独立维护者：确认 tip 祖先、无进程占用后 `worktree remove`（禁 `--force`）。
+
+## 相关链接
+
+- Plan: 用户确认的收口计划（复测后升 done）
+- Contract: [../long-term/2026-09-16-pu7-pi-narrative-contract.md](../long-term/2026-09-16-pu7-pi-narrative-contract.md)
+- W3: [../../test-reports/2026-09-17-w3-pi-change-report-narrative-test-report.md](../../test-reports/2026-09-17-w3-pi-change-report-narrative-test-report.md)
+- 红线负例: [../../test-reports/2026-09-22-redline-evidence-pi-narrative-test-report.md](../../test-reports/2026-09-22-redline-evidence-pi-narrative-test-report.md)

.doc/ops/short-term/2026-09-23-remaining-worktrees-closeout.md

@@ -0,0 +1,35 @@
+# remaining-worktrees-closeout-2026-09-23
+
+| field | value |
+|---|---|
+| status | done |
+| owner | Cursor |
+| type | integrate/cleanup |
+| base_dev_sha | 3e01f1875661c8303d255661d5d6239de54d07fb (pre-closeout tip after FAV) |
+| tip_sha | (see closeout fav-constraint merge) |
+| go_agentx_merge | 6032dbaa |
+| fav_merge | 3e01f187 |
+| write_scope | .doc |
+| mutex | git:dev+worktree-cleanup |
+| review_state | accepted |
+| integration_state | merged_local_dev |
+| deployment | not_required |
+| cleanup | done |
+| remote_sync | not_requested |
+
+## Exception (FAV)
+
+见 `.doc/ops/short-term/2026-09-23-integrate-fav-final.md`（已合入 local_dev）。
+
+## CURRENT 受控约束
+
+用户 2026-09-23 授权临时放开 `protected_sections` 后，已将第一条改为：
+
+FAV live 仍不放量；`FAV_DEGRADED_READ` 默认 false；不删 origin/*（本轮仅前进 local dev，不 push）。
+
+保护已恢复。`## 焦点` 仍受保护未改。
+
+## Goose
+
+- go-agentx registry: `00066_2026-09-21-agentx-workspace-registry.sql`
+- FAV: 保留既有 `00036_2026-09-14-final-artifact-vault.sql`；丢弃分支重复 `00034`

.doc/ops/short-term/2026-09-23-squad-missing-target-retry.md

@@ -1,66 +0,0 @@
----
-title: "智能体小队故障根治（治理死锁 + MISSING_TARGET 纠偏重试）"
-task_id: squad-missing-target-retry-2026-09-23
-status: done
-created: 2026-09-23
-updated: 2026-09-23
-owner: Cursor
-task_type: implementation
-task_tier: multi_stage
-policy_revision: "agent-governance-2026-09-21-r1 @ 78c2bcf6"
-branch: feature/squad-missing-target-retry-2026-09-23
-worktree: .worktrees/squad-missing-target-retry-2026-09-23
-base_dev_sha: "78c2bcf6b6881dc9b50f5d0b0e9be31fadb1c681"
-head_sha: "4830b8ba6d4847cded6463f9c5595b8a6e76967c"
-write_scope: ["deploy/pi-agent", "internal/agent", "internal/squad", ".doc"]
-allowed_environments: ["test"]
-mutex: squad-missing-target-retry
-review_state: not_required
-integration_state: merged_local_dev_and_test
-deployment: test_ok
-cleanup: pending
-cleanup_owner: 独立维护者
-cleanup_trigger: tip 为 local_dev/origin 祖先且无进程占用后 remove
-remote_sync: not_requested
----
-
-# 智能体小队故障根治
-
-## 用户目标与授权
-
-- 用户目标：定位并彻底修复「智能体小队总是出错」。
-- 授权：env:test 运营解锁 + 代码修复 + 合入 local_dev 并晋升 test；不 push 远端、不动 main。
-
-## 根因
-
-1. **R1 治理死锁（运营）**：单人项目无法配齐三职，且 `workflow.allow_author_only_approval=false` → 规划存不下 → 永远无法激活 → 任务 100% `blocked_pending_governance`。
-2. **R2 MISSING_TARGET（代码）**：PI 正常 settle 但未 write `output.md` 时被判 permanent，零重试直接失败。
-
-## 结果
-
-| 项 | 值 |
-|---|---|
-| author_only（test） | `true` revision=1（审计 API） |
-| 代码合入 | `dev` merge `357e4ddb`（candidate） |
-| test tip | `9984c68d` + tag `rc-v1.1.0-beta.5` |
-| pinned | `357e4ddb` digest；`:8081` schema 65 |
-| E2E | project 6012 `bd_intake` `run_1790162579970596047` **completed** |
-
-## 步骤
-
-1. [x] test 开启 author_only → 单人项目 save-plan / preview / activate
-2. [x] `settled-no-deliverable` → transient + 纠偏 Prompt；settle-policy `retryable=true`
-3. [x] Go/Node 回归 + arch-check
-4. [x] integrate → promote + pinned rebuild
-5. [x] test 真实验收（小队任务 completed）
-6. [x] 任务记录与测试报告落盘
-
-## 边界
-
-- author_only **仅 test** 开启；dev/main 默认关闭。
-- 纠偏重试受 `MaxTransientStepInvocations=2` 硬上限；不把 trace/聊天正文当交付物落盘。
-
-## 相关
-
-- 报告：[../../test-reports/2026-09-23-squad-missing-target-retry-test-report.md](../../test-reports/2026-09-23-squad-missing-target-retry-test-report.md)
-- 晋升：`promote-squad-missing-target-retry-test-2026-09-23` → `rc-v1.1.0-beta.5`

.doc/ops/short-term/2026-09-23-systemic-issue-analysis.md

@@ -0,0 +1,69 @@
+---
+title: "Bug 与系统问题的同类根因分析规范"
+task_id: systemic-issue-analysis-2026-09-23
+status: done
+created: 2026-09-23
+updated: 2026-09-23
+owner: Codex
+task_type: implementation
+task_tier: small
+policy_revision: "agent-governance-2026-09-21-r1 @ 5c35f32e225a482d5838e6d771778fb754f75506"
+branch: feature/systemic-issue-analysis-2026-09-23
+worktree: .worktrees/systemic-issue-analysis-2026-09-23
+base_dev_sha: "5c35f32e225a482d5838e6d771778fb754f75506"
+write_scope: ["AGENTS.md", ".doc/ops/templates/audit-note.md", ".doc/ops/2026-09-21-validation-contract.md", ".doc/ops/2026-09-21-policy-registry.md", ".doc/ops/short-term/2026-09-23-systemic-issue-analysis.md", ".doc/ops/CURRENT.md"]
+allowed_environments: []
+mutex: "认领路径的 agentctl path 租约；提交另持 git:index"
+review_state: approved
+integration_state: merged
+deployment: not_required
+cleanup: pending
+cleanup_owner: "owner 退出后的独立集成/维护执行者"
+cleanup_trigger: "dev 集成与证据保存完成且 owner 退出后复查"
+remote_sync: not_requested
+---
+
+# Bug 与系统问题的同类根因分析规范
+
+## 用户目标与授权
+
+2026-09-23 本会话用户要求“规范中加入一些要求”，报告 bug 或系统问题后应尝试找到这类问题的原因、潜在问题，思考研究并提出方案；以“今天天气怎么样”的异常回复作为示例，强调不能只改一个提问或细节。这是规范修改授权，天气问题只是说明，不构成产品缺陷诊断或业务修复任务。
+
+交付终点：完成统一规范、配套模板与验证要求并检查一致性；在仓库门禁允许时本地集成。禁止修改业务代码、产品提示词、运行环境、.env，禁止推送或处理他人未提交现场。
+
+## 当前证据与变更
+
+- 已阅读 AGENTS、PROJECT、CURRENT、文档地图、worktree 操作规范、验证契约、规范登记和收口清单。
+- 当前已有授权/验证规则，但没有从个案归纳共用机制、横向排查和形成方案的明确要求；分析模板只有现象和根因占位。
+- AGENTS 新增四步要求和天气示例，限制有证据关联的扩展，区分研究/实施授权。
+- 分析模板补充事实、同类范围、证据分级与方案验收；验证契约补充问题类别回归；规范登记现为 active/manual，实际生效提交见下文。
+- CODEX、CLAUDE、GEMINI、ANTIGRAVITY、KIMI 与四个 Cursor 规则均转发统一入口，无需另复制规则。
+
+## 验证计划与结果
+
+纯文档：检查 diff、修改文档的相对链接及新增锚点、状态和客户端入口一致性；人工按天气示例、无法复现、仅个案证据、已授权修复四种情形检查规则是否可执行。不运行产品测试，不声称验证过未来 Agent 行为。
+
+- 基于 base_dev_sha 的工作区差异：`git diff --check` 退出 0；人工审阅全部规范差异通过。
+- Python pathlib/re 扫描上述 5 个修改文档的 Markdown 相对链接：`PASS: 5 changed documents; 34 relative links; new anchors resolve`；目标存在，新增两个锚点可解析。
+- 人工情景审阅通过：天气示例从机制出发而非预设根因；无法复现须保留假设/缺口及验证方法；仅个案须给范围依据；已授权修复可继续，不新增重复审批。
+- 客户端入口一致性通过：所有已读入口仍引用 AGENTS/统一验证契约，无重复新规则。
+- 本次只验证文档结构与要求一致性，未执行产品测试；输出无业务内容或凭证，无需脱敏。review_state=approved 指本轮自审，不代表独立评审。
+- 文档修改与验证已完成；前轮曾因主目录未跟踪项阻塞，本轮完成本地工具文件分类与受控集成后解除。
+
+## 集成与交接
+
+启动时本地 dev 为上述 base_dev_sha；相对本地缓存 origin/dev 为 ahead 10 / behind 245，未 fetch、未核验远端实时状态，不同步远端。
+
+2026-09-23 用户在同一会话明确要求“合入 dev”，沿用本 task_id。再次读取当前 dev 的相关规范，与初始基线无差异。
+
+复核 `git status --short --untracked-files=all`：唯一未跟踪文件为 `.codegraph/.gitignore`；其内容明确说明目录用于本机代码索引，数据库已经由其中规则忽略。本轮仅在 `.git/info/exclude` 添加 `/.codegraph/` 本地排除，保留现有排除规则；未更改、移动或删除 CodeGraph 文件，操作前后两个文件的 SHA-256 一致。此配置只影响本机 Git 展示，不提交缓存；要撤销可删除本轮添加的注释与排除行。主目录随后干净，原有 hooks、validate 与 integrate 门禁均保持启用。
+
+- 任务实现提交：`380584b86bd2ae53b2896a784ee892dad998e1bf`。
+- 生效集成提交：`958dd44fee8bbea8d19129457fc0ad749fdebdbe`；第一父提交为 `5c35f32e225a482d5838e6d771778fb754f75506`，第二父提交为任务实现提交。
+- 候选 worktree：`.worktrees/integrate-systemic-issue-analysis-2026-09-23`；机器登记 ID 同名（去掉路径前缀），owner Codex，允许写路径与本任务相同，能力仅 `git:dev`。
+- 精确候选验证：`agentctl validate --task integrate-systemic-issue-analysis-2026-09-23 -- python3 -` 执行差异范围/空白、6 个修改文档的 47 个相对链接、新增锚点和客户端入口检查，输出 `PASS: diff scope; 6 documents; 47 relative links; new anchors; client entrypoints`。收据 `107bab9a-6f66-4d7f-91eb-4881d030c834` 绑定上述生效提交。
+- 受控集成：`agentctl integrate --task integrate-systemic-issue-analysis-2026-09-23 --expected-dev 5c35f32e225a482d5838e6d771778fb754f75506` 返回 `status=merged`；收据 `557480b8-4705-4eb7-b39f-12d3578c78b5`。
+- 本轮状态/登记收口作为后续文档提交，同样从精确 dev 基线构造候选并验证后受控合入；其合并节点不改变上述规范生效提交。机器操作收据按候选 task 查询，Git 保留完整父链。
+- 本地 dev 已包含规范；`deployment=not_required`，运行制品未变；`remote_sync=not_requested`，未 fetch 或 push。
+
+任务验收已满足，状态 done；两个 worktree 保留供独立维护者在 owner 退出后复查清理，cleanup=pending。无业务遗留工作，不操作其他任务或共享服务。影响限于工程 Agent 的问题处理要求；FEATURE-MATRIX、发布门禁和产品运行版本无变化。

.doc/ops/short-term/2026-09-23-worktree-closeout-batch.md

@@ -0,0 +1,67 @@
+---
+title: "Worktree 批量收口：合入 dev + 清理"
+task_id: "worktree-closeout-batch-2026-09-23"
+status: done
+created: 2026-09-23
+updated: 2026-09-23
+owner: Cursor
+task_type: operations
+task_tier: multi_stage
+policy_revision: "agent-governance-2026-09-21-r1 @ 3f14d7fa"
+branch: feature/worktree-closeout-batch-2026-09-23
+worktree: .worktrees/worktree-closeout-batch-2026-09-23
+base_dev_sha: "3f14d7fa755269d69b3c1729a6c3180f27ed8630"
+write_scope: ["."]
+allowed_environments: []
+head_sha: "a690aab42d820058974ca38a363cb71ebe9e0bc9"
+mutex: "git:dev+worktree-cleanup"
+review_state: accepted
+integration_state: merged_local_dev
+deployment: not_required
+cleanup: retained-with-reason
+cleanup_owner: "独立维护者"
+cleanup_trigger: "全部合入验证通过且 worktree 清理完成"
+remote_sync: not_requested
+---
+
+# Worktree 批量收口：合入 dev + 清理
+
+## 用户目标与授权
+
+- 用户目标：检查当前所有 worktree，完成后测试合入 local `dev`，并清理 worktree。
+- 授权决策（计划确认）：
+  1. `merge_remote`：创建 integrate 候选，将 `origin/dev` 合入本地 `dev`，解决冲突后推进本地 dev；不默认 push。
+  2. `keep_protected`：FAV / go-agentx 保留不合入不清理。
+- 交付终点：本地 `dev` 含远端 + 本地独有 + 未合 docs 分支；无争议 worktree 清理完毕。
+- 禁止项：不 push；不晋升 test/main；不强删；不整支合入 FAV；不清理 go-agentx cancelled 现场。
+
+## 范围与非目标
+
+- 允许：同步 `origin/dev`、合入未完成 docs 分支、抢救未跟踪任务文档与 mineru gofmt、关闭 active 任务、普通 remove worktree/stale 目录、CURRENT docs apply。
+- 非目标：远端 push；FAV / go-agentx；test/main 晋升。
+
+## 步骤与验收
+
+1. [x] 建场 + recover `dac0865f` + 关闭 promote 任务 + 主目录切回 `dev`
+2. [ ] 同步 `origin/dev` 进本地 `dev`（冲突解决 + validate + integrate）
+3. [ ] 合入 modular / lock / policy / workflow-governance + 抢救文档/gofmt
+4. [ ] 关闭其余 active 任务；清理已合入 worktree / stale 目录（保留保护项）
+5. [ ] 验证报告 + CURRENT 收口
+
+## 验证与证据
+
+| 范围 / 被测 SHA | 命令与环境 | 预期 | 实际 / 判定 | 证据 / 脱敏说明 |
+|---|---|---|---|---|
+| 前置 | recover + task close + checkout dev | recovery 清空、主目录在 dev | recovered；promote 任务 cancelled；主目录 `dev` | agentctl status |
+
+独立报告：`.doc/test-reports/2026-09-23-worktree-closeout-batch-test-report.md`（阶段完成后补）。
+
+## 收口与交接
+
+- 本地提交 / dev 集成 / 远端：本轮仅本地；`remote_sync=not_requested`。
+- 保护项：`.worktrees/fix-dev-runtime-data-root-guard`（FAV）、`.worktrees/go-agentx-runtime-2026-09-21`。
+
+## 相关链接
+
+- 计划：`~/.cursor/plans/worktree_批量收口_c72b246f.plan.md`
+- 操作规范：`../2026-09-21-agent-worktree-workflow.md`

.doc/ops/short-term/2026-09-24-codegraph-governance.md

@@ -0,0 +1,29 @@
+---
+status: in_progress
+task_id: codegraph-governance-2026-09-24
+owner: Cursor
+mutex: agent-workflow-governance+codegraph
+base_dev_sha: 0ff698db6f3e49df7808a30ae328f3b81f9dd4ba
+write_scope: scripts, .doc, .cursor, .gitignore, AGENTS.md
+review_state: in_progress
+integration_state: not_merged
+deployment: not_required
+cleanup: pending
+remote_sync: not_requested
+policy_revision: codegraph-governance-2026-09-24-r1
+---
+
+# CodeGraph 纳入治理 + worktree/MATRIX 只读盘点
+
+## 目标
+
+1. 治理层接入 CodeGraph：MCP、gitignore、建场 init、hooks sync、会话 sync；soundness 边界（grep 权威）。
+2. 只读盘点：`cleanup report` / `docs drift`；daemon `--audit-every`；不自动删除、不自动升 done。
+3. 不碰产品 SWBOOT-10；不装载本机 systemd coordinator。
+
+## 验收
+
+- unittest（scripts/tests）+ 针对性正负例
+- 真实命令：cleanup report / docs drift / hooks codegraph-sync
+- 测试报告：`.doc/test-reports/2026-09-24-codegraph-governance-test-report.md`（工程规范变更，PI/全量 Go 标 NOT REQUIRED）
+- fixup landed note: trailing-slash check-ignore

.doc/ops/short-term/2026-09-24-intent-plan-i2-shadow-allowlist.md

@@ -0,0 +1,59 @@
+---
+title: "Track I2：shadow 层 + 项目 allowlist + 冻结阈值"
+task_id: intent-plan-i2-shadow-allowlist-2026-09-24
+status: in_progress
+created: 2026-09-24
+updated: 2026-09-24
+owner: Cursor
+task_type: implementation
+task_tier: small
+policy_revision: "AGENTS+CURRENT @ 9d8332ad"
+branch: feature/intent-plan-i2-shadow-allowlist-2026-09-24
+worktree: .worktrees/intent-plan-i2-shadow-allowlist-2026-09-24
+base_dev_sha: "9d8332ad0892adf147cb31da358ed01ad3e503fa"
+write_scope: ["internal/app", "internal/app/intentflow", "internal/chat", "internal/sysadmin", "docker-compose.*.yml", ".doc/ops/short-term", ".doc/test-reports"]
+allowed_environments: ["dev"]
+mutex: intent-plan
+review_state: pending
+integration_state: pending
+deployment: pending
+cleanup: pending
+cleanup_owner: 独立维护者
+remote_sync: not_requested
+---
+
+# Track I2：shadow 层 + 项目 allowlist + 冻结阈值
+
+## 用户目标与授权
+
+- 关闭 FEATURE-MATRIX `intent-plan-u1u8`：实现 I2 代码门禁后在 dev 逐级放量验收。
+- 本任务（T1）只交付代码：shadow 持久不可执行计划、`INTENT_PLAN_PROJECT_ALLOWLIST`、进程内对账指标、冻结阈值登记。
+- 禁止：升 compose 默认值、升 full、push、操作 test/main。
+
+## 冻结阈值（Foundation 0 / I2 进入 auto_read 前）
+
+对 U2 `plan-proposal-eval-v1.json` counterfactual 基线：
+
+| 指标 | 阈值 |
+|---|---|
+| hard-negative 错误自动执行（would_execute） | **0** |
+| 安全红线 / 越权副作用 | **0** |
+| 写意图漏判为 auto_read | **0** |
+| read_only would_execute 覆盖（非 hard-negative） | ≥ 基线分母内全部命中 |
+| 确认放弃率 / 主动拆单（放量观察） | 记录；不达不升 confirm 写扩面 |
+
+放量观察窗以标注数据集 + 手工样本为主证据；不以事后结果下调阈值。
+
+## 步骤
+
+1. [x] `TierShadow`：持久 `proposed` + `validated_only`，零执行；不占 active-write
+2. [x] `INTENT_PLAN_PROJECT_ALLOWLIST`（空拒绝 / `*` / id 列表）
+3. [x] 进程指标 + chat 对 shadow 不抢 legacy 路由
+4. [x] 单测 + arch-check
+5. [ ] 合入 local_dev；T2 做真实放量验收
+
+## 相关链接
+
+- 方案：多意图两行收口推进方案
+- 上位：[capability-enablement Track I](../../remediation/2026-09-20-capability-enablement-impact-plan.md)
+- 设计：[multi-intent-hitl-plan](../../system-design/2026-09-15-multi-intent-hitl-plan.md)

.doc/ops/short-term/2026-09-24-intent-plan-u9u12-live.md

@@ -0,0 +1,43 @@
+---
+status: done
+write_scope: internal/app,intentflow,internal/sysadmin,.doc/ops/short-term
+mutex: intent-plan
+base_dev_sha: 4e601e95
+review_state: self-reviewed
+integration_state: merged_local_dev
+deployment: loaded_shared_dev
+cleanup: pending
+remote_sync: not_pushed
+owner: Cursor
+task_id: intent-plan-u9u12-live-2026-09-24
+---
+
+# intent-plan U9–U12 live 接线（Track I3）
+
+## 目标
+
+- **U9**：`HandleTurn` 在 `RulesCanDecide==false` 且 elevated tier 时调用 `ActiveSegmentProposer`；失败 fail-closed；成功用 LLM spans + 确定性识别构建计划（`segmenter.v2.llm`）。
+- **U10**：`project.fact.supplement` → `MutateOwner`（`ctxmgr.UpdateProjectBlackboard`，与 SupplementInfo 同源黑板）。
+- **U11**：`document.claim`、`document.review.submit` → `DocGovOwner`（docgov 引擎）；其余 docgov key 仍 dry-run。
+- **U12**：`workflow.run`、`run.resume` → `RunControlOwner`（projectworkflow + taskrun）；其余仍 dry-run。
+
+## 验证
+
+```bash
+./scripts/arch-check.sh --mode block
+go test -short ./internal/app/intentflow/ ./internal/app/ ./internal/sysadmin/ -count=1 \
+  -run '^(TestHandleTurn|TestMutate|TestDocGov|TestRunControl|TestExpansion|TestBatch|TestActive|TestStub|TestRule|TestU10|TestU11|TestU12|TestBuild|TestDryRun|TestDefault|TestFeatures|TestQuery|TestTask|TestLive|TestProductionComposition)' 
+```
+
+## 未 live 的 action key（MATRIX 开放清单）
+
+| 域 | 仍为 validated-only / dry-run |
+|---|---|
+| U10 | （仅 `project.fact.supplement` live；无其它 mutate key） |
+| U11 | `document.review.approve/reject`, `document.final.approve/reject`, `document.proposal.decide` |
+| U12 | `workflow.switch`, `run.restart` |
+
+## 收口
+
+- 合入：`agentctl validate` → `queue enqueue` 或 integrate
+- FEATURE-MATRIX：由父任务更新

.doc/ops/short-term/2026-09-24-jev-dev-assist-enable.md

@@ -0,0 +1,29 @@
+---
+status: done
+write_scope: configs/.env.dev(local),env:dev,.doc
+mutex: env:dev+jevdecide
+base_dev_sha: 156c1130
+review_state: self-reviewed
+integration_state: docs_pending
+deployment: local_dev_assist_on
+cleanup: pending
+remote_sync: not_pushed
+owner: Cursor
+task_id: jev-dev-assist-on-2026-09-24
+---
+
+# local_dev 启用 jev-service（assist）并多样本对话验收
+
+## 目标
+
+将 `JEV_DECIDE_MODE` 从 shadow 升为 **assist**，用 ≥20 条真实 `/api/v1/chat` 验证：规则漏检时能否加成打开实时检索，且业务问句不被误伤。
+
+## 做法
+
+1. `configs/.env.dev`：`JEV_DECIDE_MODE=assist`（URL/KEY 不变）
+2. `env:dev` 租约下 force-recreate app → 日志 `jevdecide wired mode=assist`
+3. 20 轮真实对话；证据 [assets](../../test-reports/assets/2026-09-24-jev-dev-assist-enable/)；报告 [test-report](../../test-reports/2026-09-24-jev-dev-assist-enable-test-report.md)
+
+## 回退
+
+`JEV_DECIDE_MODE=shadow` 或 `off` 后 recreate app。

.doc/ops/short-term/2026-09-24-jev-dev-shadow-enable.md

@@ -0,0 +1,36 @@
+---
+status: done
+write_scope: configs/.env.dev(local),env:dev,.doc
+mutex: env:dev+jevdecide
+base_dev_sha: d8214a09
+review_state: self-reviewed
+integration_state: docs_only
+deployment: local_dev_shadow_on
+cleanup: pending
+remote_sync: not_pushed
+owner: Cursor
+task_id: jev-dev-shadow-on-2026-09-24
+---
+
+# local_dev 启用 jev-service（shadow）
+
+## 目标
+
+在运行中的 `local_dev` 打开产品侧 `JEV_DECIDE_MODE=shadow`，对接本机 jev-service，不改 compose 默认（仍 `off`），不放量 `assist`。
+
+## 做法
+
+1. `configs/.env.dev`（gitignore）写入：
+   - `JEV_DECIDE_MODE=shadow`
+   - `JEV_BASE_URL=http://172.17.0.1:8767`（容器经 docker0 网桥访问宿主机；`host.docker.internal` 本机不可达）
+   - `JEV_API_KEY` 自 `~/.secrets/jev/api.key` 注入（不入库）
+2. `agentctl with --resource env:dev` → `./scripts/env-service.sh dev rebuild`（旧镜像无 jevdecide 接线，仅 recreate 不够）
+3. 验证见 [启用报告](../../test-reports/2026-09-24-jev-dev-shadow-enable-test-report.md)
+
+## 回退
+
+将 `configs/.env.dev` 中 `JEV_DECIDE_MODE=off`（或删 JEV_*）后 `env-service.sh dev` recreate/restart app。
+
+## 非目标
+
+- 不改 compose 默认、不推远端、不晋升 test/main、不启用 assist

.doc/ops/short-term/2026-09-24-jev-mcp-integration.md

@@ -0,0 +1,40 @@
+---
+status: done
+write_scope: scripts/mcp,.cursor,.doc/ops/short-term,.doc/test-reports
+mutex: jev-mcp+docs
+base_dev_sha: b6f21e8a947c4bb8ab1171e05f7404b35f7bd2f1
+review_state: self-reviewed
+integration_state: merged_local_dev
+deployment: not_required
+cleanup: pending
+remote_sync: not_pushed
+owner: Cursor
+task_id: jev-mcp-integration-2026-09-24
+---
+
+# jev-service 治理侧 MCP 接入
+
+## 目标
+
+将本机 jev-service（类型化 decision API）以独立 MCP 服务器 `jev` 接入本仓库治理链路，供 agent 在封闭枚举决策点调用；凭证仅存 `~/.secrets/jev/`，不进 git。
+
+## 交付物
+
+- `scripts/mcp/jev-mcp.mjs` — `jev_decide` / `jev_health`
+- `.cursor/mcp.json` — 注册 `jev` server
+- `.cursor/skills/jev-decide/SKILL.md` — 治理用例指引
+- `.doc/test-reports/2026-09-24-jev-mcp-integration-test-report.md` — 真实链路证据
+
+## 非目标
+
+- 不改 Go 产品路径（intent / coordinator / pi-agent）
+- 不 push、不晋升 test/main
+- 不把 API key / 完整 secret 写入仓库或报告正文
+
+## 验证计划
+
+1. MCP initialize + tools/list（stdio NDJSON 或 Content-Length）
+2. `jev_health` 对本机与 frp 备用 URL
+3. `jev_decide` 治理样例（任务分级 + 验证层级）
+4. 401 负例（错误 key）
+5. 产品 PI 全链路：NOT REQUIRED（工程 MCP/文档变更，依据 PROJECT.md §验证入口与 test-reports-standard 例外）

.doc/ops/short-term/2026-09-24-jev-product-shadow.md

@@ -0,0 +1,36 @@
+---
+status: done
+write_scope: internal/jevdecide,internal/coordinator,internal/app,internal/config,internal/sysadmin,configs,deploy,.doc
+mutex: jevdecide+coordinator
+base_dev_sha: 0ff698db6f3e49df7808a30ae328f3b81f9dd4ba
+review_state: self-reviewed
+integration_state: merged_local_dev
+deployment: not_required
+cleanup: pending
+remote_sync: not_pushed
+owner: Cursor
+task_id: jev-product-shadow-2026-09-24
+---
+
+# jev-service 产品侧 shadow 接入
+
+## 目标
+
+产品 Go 路径接入 jev-service：离线评测过双门禁后，以 `JEV_DECIDE_MODE=off|shadow|assist` 灰度接入 realtime_query 与 ProfileTask；默认 off，失败 fail-open 回规则。
+
+## 交付
+
+- `internal/jevdecide` 客户端 + 熔断 + 指标 + 离线评测集（≥100）
+- coordinator `DecideAssist` 端口 + shadow/assist 接线
+- compose 三环境声明 `JEV_DECIDE_MODE=off`
+- 测试报告与 soak 证据
+
+## 非目标 / 暂缓
+
+- intent-l1 / docrevision 风险分级不接线
+- `assist` 生产开启需用户在双门禁报告后单独确认（代码已实现，默认 off）
+- 不 push / 不晋升 test/main
+
+## 五态（收口时更新）
+
+见测试报告结论。

.doc/ops/templates/audit-note.md

@@ -20,13 +20,31 @@ severity: medium
 
 用户目标及可核实来源、允许写路径、环境、交付终点、非目标。实质审查须落盘；可作为唯一主文档，无需复制任务链。关联父任务时引用其授权/认领，不另建重复认领。
 
+## 问题登记与经验检索
+
+涉及具体缺陷时填写 issue_id、issue_state 及 [问题台账](../../audit/ISSUES.md) 链接；已有主记录直接引用。记录检索词、命中经验和适用边界。研究 status=done 不代表 issue_state=resolved；详见 [闭环规范](../2026-09-23-issue-learning-workflow.md)。
+
 ## 现象
 
-（可观测症状）
+（预期/实际行为、原始案例、触发条件、环境与复现结果）
 
 ## 根因分析
 
-（证据路径、代码引用）
+Bug/系统问题按 [AGENTS 分析要求](../../../AGENTS.md#bug-与系统问题的分析要求) 填写；其他审查按实际范围裁剪。
+
+（问题类别、因果链、共用机制、现有防护为何未发现；证据路径/代码引用；区分已证实、假设和证据缺口）
+
+## 同类问题与影响范围
+
+| 关联场景/入口 | 与原例共用的机制 | 检查方法与证据 | 判定及影响 |
+|---|---|---|---|
+| | | | 已确认缺陷 / 潜在风险 / 本次未发现异常 / 未验证 |
+
+（说明排查边界、未覆盖项及理由；仅个案问题也需依据）
+
+## 方案与验收
+
+（处理选项、推荐理由、修复位置、实施步骤、风险；临时止血的局限和根治安排；原例/同类变体/边界与异常路径/正常行为的预期结果和验证方法。详见 [验证契约](../2026-09-21-validation-contract.md#问题修复的回归范围)。已有独立方案时链接，不复制全文；明确本轮是研究还是已授权实施。）
 
 ## 严重度
 
@@ -44,6 +62,10 @@ severity: medium
 
 - 
 
+## 修复经过与经验
+
+修复尝试、被否定方案、提交、部署和验收链接；未实施明确标注。得到验证后关联 lesson，或说明不新增理由；复发时解释已有防护为何失效并更新原记录。
+
 ## 状态与交接
 
 记录实际命令、被审 SHA、结果与脱敏范围；研究完成指产物有据可审，不代表建议已实施。记录剩余工作、cleanup_owner/保留原因/复查触发，以及本地提交、集成、远端状态。会话结束不强制 done。

.doc/ops/templates/development-lesson.md

@@ -0,0 +1,22 @@
+---
+lesson_id: LESSON-YYYYMMDD-<slug>
+lesson_state: candidate  # candidate | validated | superseded | retired
+owner: <维护者>
+reviewer: <复核者；自审要明确>
+last_reviewed: YYYY-MM-DD
+reviewed_revision: <核对的源码/规范 SHA>
+source_issues: [<issue_id>]
+keywords: [<模块>, <路径或符号>, <症状>, <机制>]
+---
+
+# <能直接指导开发的注意事项>
+
+- 触发条件：何时读本条？
+- 机制与来源：issue/根因/修复和证据日期；假设保留 candidate。
+- 开发检查：具体应该怎样做、应避免的错误及因果理由。
+- 验证方式：原例、同类和正常行为；链接现有测试/规范，区分已执行、仅存在和待补。
+- 适用边界：哪些前提下成立，哪些场景不适用。
+- 防护落实：已落地的测试/门禁/规范，仍需改进的 owner/任务/触发；没有自动化明确写 manual。
+- 修订与失效：复发补充原因；被替代/退役保留理由和替代链接。
+
+细则见 [闭环规范](../2026-09-23-issue-learning-workflow.md)。经验不另建授权或覆盖现行规范。

.doc/ops/templates/issue-record.md

@@ -0,0 +1,43 @@
+---
+issue_id: ISSUE-YYYYMMDD-<slug>
+issue_state: open  # open | investigating | fixing | verifying | resolved | deferred | duplicate
+severity: medium  # critical | high | medium | low
+owner: <负责定位/跟进者>
+task_ids: [<关联任务 ID>]
+created: YYYY-MM-DD
+occurred_at: <首次发现日期>
+updated: YYYY-MM-DD
+recurrence_count: 0
+evidence_basis: current  # current | historical；均注明版本/日期/环境
+lesson_ids: []
+---
+
+# <问题标题>
+
+按 [闭环规范](../2026-09-23-issue-learning-workflow.md) 维护。已有审计/任务承载这些内容时，在原主记录补字段/章节并索引，不复制正文。授权、worktree 与任务状态链接父任务。
+
+## 事实与证据
+
+预期/实际、触发条件、影响、版本/环境、首次发生与复现方法；证据日期、路径和脱敏范围。无法复现写缺口和下一步。
+
+## 根因与同类范围
+
+区分已证实、假设、已排除；共用机制、因果链、现有防护失效原因；同类入口、检查结果、未覆盖项及理由。
+
+## 修复思路与过程
+
+方案选项、选择理由、修复位置、临时止血局限及根治安排；链接既有方案。
+
+| 日期 | 假设 / 尝试 / 动作 | 实际结果与证据 | 决策 / 下一步 / owner |
+|---|---|---|---|
+| | | | |
+
+失败/未知结果保留，不用后续成功覆盖。追加修复提交、合入和部署证据；多轮尝试分别记录。
+
+## 验收与关闭
+
+原例、同类变体、边界/异常、正常行为，逐项记录真实结果/未运行和证据。记录 resolved 日期和范围；临时止血或研究完成不当作修复完成。deferred 填风险/决策依据/owner/复查触发；duplicate 指向主 ID。
+
+## 经验与复发
+
+lesson 链接，或不新增经验的理由；测试/规范/门禁落实情况和待办 owner。复发保留前次关闭记录、递增次数，解释旧经验/防护为何未生效。

.doc/ops/templates/session-close-checklist.md

@@ -9,6 +9,12 @@
 - [ ] 验证范围按 [验证契约](../2026-09-21-validation-contract.md)；保存实际命令、SHA、环境、结果和缺项，敏感材料最小化/脱敏。
 - [ ] 本次影响、关联文档、剩余工作/接管条件在主文档或 handoff 中可恢复。
 
+## 问题与经验
+
+- [ ] 新发现/修复/复发的问题已更新唯一主记录和 [问题台账](../../audit/ISSUES.md)，修复过程、未解决项及 owner 可追溯；研究 done 未误关问题。
+- [ ] 已验证的可复用结论已更新 [开发经验](../lessons/INDEX.md)，或记录不新增理由；未验证结论标 candidate，关联测试/门禁区分已落地与待办。
+- [ ] 本任务采用的经验、适用性和验证结果有记录；复发、过时、冲突经验按 [闭环规范](../2026-09-23-issue-learning-workflow.md) 处理。
+
 ## 认领、集成与环境
 
 - [ ] CURRENT 增量更新为实际状态；保留活跃/阻塞/待集成/待清理事项，只有已终态且无后续阻塞的认领转历史。
@@ -19,8 +25,11 @@
 ## 清理与归档
 
 - [ ] 按 [操作规范](../2026-09-21-agent-worktree-workflow.md) 核对 dev 祖先、验收、文件/唯一 ignored 证据、进程、保护项；普通 remove/-d 拒绝则保留，不强删。
+- [ ] 已跑 `agentctl cleanup report`；对 `verdict=ready` 项由维护者执行 remove；blocked 保留 cleanup_pending。
+- [ ] 已跑 `agentctl docs drift`；处理硬告警（`done→非 done`）；`open_capabilities` 按声明范围人工决定是否 `docs apply`（升 done 仍需 `docs:approve` + 已提交证据）。
 - [ ] cleanup 未完成时有 cleanup_owner、保留原因、证据位置、可观测复查触发；owner 退出后由独立集成/维护执行者复查。
 - [ ] 可再生缓存与唯一证据分开处理；唯一日志/截图已持久保存，不能仅留下即将删除的路径。
 - [ ] 只有 done/cancelled 任务归档；移动时修复相对链接并保留历史。未完成任务保留原状态，不为归档改 done。
 - [ ] 仅模块声明变化时更新 [FEATURE-MATRIX](../../status/FEATURE-MATRIX.md)，仅 blocker 变化时更新 [gap-matrix](../../remediation/gap-matrix.md)；CURRENT 焦点最多 3 条。
 - [ ] 实现与相应证据形成可解释、可验证、可回退的逻辑提交；无三大主干直接开发提交。
+- [ ] 本会话触及的仓库若已装 CodeGraph：收口前 `codegraph sync -q`（缺失 CLI 可跳过）。

.doc/ops/templates/short-term-task.md

@@ -40,6 +40,14 @@ remote_sync: not_requested  # not_requested | pending | pushed | failed
 - 允许写入、影响模块及依赖：
 - 非目标：
 
+## 相关问题与经验
+
+- issue_ids / 问题主记录（非问题任务可无）：
+- 开工检索词、命中 lesson_ids、适用性核对及采纳的检查（无命中明确写出）：
+- 收口新增/更新的经验与防护，或不新增理由；未落实项的 owner/触发：
+
+遵循 [闭环规范](../2026-09-23-issue-learning-workflow.md)，问题与经验状态独立于任务完成状态。
+
 ## 步骤与验收
 
 1. [ ] <步骤> — 验收条件/证据：

.doc/remediation/2026-09-14-dev-runtime-data-root-and-projection-remediation.md

@@ -0,0 +1,216 @@
+---
+title: "dev 运行数据根隔离与文档投影整改方案（审查修订）"
+status: planned
+created: 2026-09-14
+updated: 2026-09-14
+---
+
+# dev 运行数据根隔离与文档投影整改方案（审查修订）
+
+## 审查结论
+
+2026-09-14 多视角审查确认：**诊断成立，原文不可整包实施。**
+
+现场在审查当时（约 09:23 UTC）仍为 split-brain：
+
+| 项 | 值 |
+|---|---|
+| `shuimu-agent-app-dev` created | `2026-09-14T08:40:44Z` |
+| Compose working dir | `/tmp/as-dev-wf409-merge` |
+| app `/app/data` | `/tmp/as-dev-wf409-merge/data/dev` |
+| pi/cursor workspaces | `/tmp/as-dev-wf409-merge/data/dev/workspaces` |
+| `/health` `/ready` | 200，`schema_version=33` |
+| 主仓 CURRENT 集成槽 | `implementer_cursor` / `e2e` / workflow-plan |
+
+用户已拍板：
+
+1. **Wave 0 授权方式 = 事故抢占**：不排队等 e2e 结束；获批实施后立即停 runner/app，只读保全两端数据根，再从主仓目录纠挂。
+2. **本轮只改方案**：消解波次矛盾后再单独批准实施。本文未授权 rebuild、未授权写库、未授权删除 `/tmp`。
+
+原文把「恢复可读」和「投影 outbox / 数据治理 / 完整 SLO」绑成同一批准与同一关门条件。修订后拆成三个互不阻塞的批准单元。
+
+## 批准单元
+
+| 单元 | 目的 | 关闭事故？ | 状态 |
+|---|---|---|---|
+| **Unit A** | 事故遏制与纠挂：停写、保全、从主仓 remount | 恢复当前可读/可写 | 方案已修订，**实施待再批** |
+| **Unit B** | 防复发：绝对状态根 + 脚本硬门禁 + readiness 身份门禁 | 阻止同类错挂再次显示 healthy | 方案已修订，**实施待再批** |
+| **Deferred** | ledger 只读降级、projection outbox、历史 work_dir 治理、监控产品、迁仓外路径 | 否 | 记 long-term，不挡 Unit A/B 关门 |
+
+`RUNTIME-DATA-ROOT-SPLIT-BRAIN` 与 FEATURE-MATRIX `infra` 在 **Unit A 验收 + Unit B 负例** 后关闭。不得等 Deferred。同 worktree 上的数据生命周期方案是 sibling：可以并行设计，**不得**成为 Unit A 纠挂的前置或本 gap 的关门条件。
+
+## 目标
+
+1. 任意 build source / linked worktree / `/tmp` checkout 都不能改变已部署环境的持久数据根。
+2. 错挂或身份不一致时 `/ready` 必须 503；`/health` 只表示进程存活，不得作为部署就绪依据。
+3. Unit A 完成后，项目 143 等活跃受控正文在正确数据根上可打开；不以 08:54 历史 SHA 作为事后硬门槛。
+4. 真实内容分叉仍 409 并保全双方；安全 missing 的自动重建与 outbox **不在本方案实施范围**。
+
+## 术语（强制）
+
+| 术语 | 定义 |
+|---|---|
+| `SOURCE_ROOT` | 本次构建源码目录，可来自受控集成 worktree |
+| `RUNTIME_STATE_ROOT` | 各环境状态目录的**绝对父路径**。短期默认 = 主仓 `…/Agent-System/data` |
+| `ENV_STATE_DIR` | `${RUNTIME_STATE_ROOT}/<env>`，例如 `…/data/dev` |
+| `SHARED_STATE_ROOT` | 共享知识库状态根，**不**拼接 `/<env>`，不随 `SOURCE_ROOT` 变化 |
+| bind mount source | `docker inspect` 的宿主机 `Mounts.Source` |
+| build context | 镜像构建用的源码目录，允许与状态根不同 |
+
+禁止把 `RUNTIME_STATE_ROOT` 理解成已经带 env 的 `data/dev`。Compose 公式一律是 `${RUNTIME_STATE_ROOT}/${ENV}/...`。`.storage-identity.json`（Unit B）落在 `ENV_STATE_DIR/`。
+
+禁止把 Wave 0「容器 source」读成 `SOURCE_ROOT`。Wave 0 验收的是 **bind mount source**。
+
+## 核心决策
+
+### D1 — 代码根与状态根分离（Unit B；Wave 0 不依赖新变量）
+
+- Compose 可变 bind 改为 `${RUNTIME_STATE_ROOT}/${ENV}/...`，禁止 `./data/<env>`。
+- 短期兼容：用主仓 `data/` 作为 `RUNTIME_STATE_ROOT`。**本方案禁止把状态根迁到 `/var/lib/agent-system`。**
+- 禁止硬编码个人 HOME。解析顺序：显式环境文件 → Git common-dir 推出的 **primary** 根下的 `data/`。
+- 显式 `RUNTIME_STATE_ROOT` **不能**把任意绝对路径变成合法根。解析结果必须：绝对、`realpath`、等于宿主机 allowlist、环境后缀与命令一致、不落在任何 linked worktree toplevel、不是 `/tmp` 集成目录。
+- shared compose 使用 `SHARED_STATE_ROOT`，不套用 `/${ENV}`。
+- `.regulations` 若仍从 `SOURCE_ROOT` 相对挂载，必须在 Unit B 清单里单独点名；不得假装已被 data identity 覆盖。
+- **否决记录**：Postgres 逃过本次事故是因为 named volume。本轮仍保持宿主机 bind，以便 Unit A 做两端差异保全。不用 named volume 收口 `/app/data`，也不把「固定 `--project-directory`」当成 Unit B 的全部答案——脚本必须同时导出绝对 bind，否则合法集成 rebuild 仍会解析到调用目录。
+
+### D2 — 存储身份是配对仪式，不是可复制哨兵（Unit B）
+
+- 每个 `ENV_STATE_DIR` 放受保护的 `.storage-identity.json`：`environment`、UUID、schema version、**canonical host path**；不含 secret。
+- PostgreSQL 用**新的单行表**，不复用 `iam_system_config`。
+- **禁止自动初始化。** app 启动只校验，不 mint、不把文件 UUID 写进 DB，也不把 DB UUID 写到空根。
+- 真首启（允许 pair 命令写入同一 UUID）当且仅当：DB 无业务行（至少 `document_records` / `document_snapshots` 为空）**且**文件根无业务布局。
+- 已有业务库 + 文件根无合法 sentinel → fail closed / `/ready` 503。现场错误根已有 27 个文件，**「空目录」不是可用谓词**。
+- DB 有 UUID、文件缺失 → 503，不回写。
+- 文件有 UUID、DB 无 → 503，防止新卷认领旧根。
+- UUID 一致但 `realpath` ≠ DB 固化 canonical path → 503（克隆/备份根）。
+- runner 一致性**不**靠进程内 HTTP：`cursor-agent` 现为 `alpine sleep`，pi/cursor 只挂 `workspaces`，读不到状态根哨兵。Unit B 由部署脚本 `docker inspect` 三个容器的 `Mounts.Source` + 文件 sentinel + DB 行。进程内 `/ready` 只比 app 可见 sentinel 与 DB。
+- 未认证 `/ready` 只返回聚合布尔和稳定错误码，禁止 UUID、路径、mount source、doc_id、计数明细。
+
+### D3 — 读取真源与自动重建拆开（Deferred / 后续）
+
+- Unit A **不**改 GET 语义；纠挂后投影文件回到视野，现有 fail-closed 即可恢复 200。
+- 以后若做「ledger head 可读」，必须：identity 已通过、GET **只读**、真实 fork 仍 409 `DOCUMENT_CONTENT_PROJECTION_DRIFT`、不得在 GET 路径写盘。
+- 不得把「此刻 stat 不到 `output.md`」单独当成可自动重建。曾出现 fork/mismatch 的文档禁止降级为 MISSING 自愈。
+- 本方案**删除**原文 D3「MISSING 后台从 head 原子重建」。任何写回只允许在独立 Deferred 产品里设计，且必须有路径沙箱（`Lstat` + `EvalSymlinks`，realpath 严格位于 `ENV_STATE_DIR`）。
+
+### D4 — transactional outbox 降为 Deferred
+
+- 当前 409 的根因是错挂空根，不是缺 outbox。
+- 仓库已有 `InspectProjection`、`ProjectOutputMarkdown`、`fsutil.WriteFileAtomic`、`document-content-reconcile`。新 job 表 / projector 进程是第二产品。
+- PATCH 若以后暴露 `projection_status`：ledger commit 成功则 **HTTP 一律 200**，状态放 body/头；禁止用非 2xx 表示「账本未保存」。
+- fork：服务继续，该文档 409，保全双方，立即人工处置。**不是**停 app/runner。
+
+## 分波次计划
+
+| 波次 | 单元 | 内容 | 验收 |
+|---|---|---|---|
+| Wave 0 | A | 事故抢占：停 pi/cursor/app（保留 Postgres 卷）；只读保全主仓根与 `/tmp` 错误根；三方 disposition；**仅从主仓 checkout** 用现有相对 bind 纠挂三容器 | 见下方 Runbook；**不**验 storage identity，**不**改 143 正文 |
+| Wave 1 | B | `env-service.sh` + compose 同时改：导出绝对 `RUNTIME_STATE_ROOT`，可变 bind 全部改公式；worktree / `/tmp` 默认 mutating 失败且不 recreate 现网 | 两个不同 `SOURCE_ROOT` 渲染后，app/pi/cursor 的 host mount source 字节级相同，且等于 allowlist 中的 `ENV_STATE_DIR` |
+| Wave 2 | B | 与 Wave 1 同一批落地。CI 禁相对 `./data/<env>`；**允许**绝对路径落在 primary checkout 的 `data/<env>`。shared 只用 `SHARED_STATE_ROOT` | 合法配置不会被「工作树内 data/」误杀；dev 命令不能挂 test/main 根 |
+| Wave 3 | B | 文件/DB identity + pair 命令；`/ready` 增加 `storage_ready` 布尔；dev compose healthcheck 改为 `/api/v1/ready` | 复现本次 split-brain 时 `/ready` 503、容器 unhealthy；`/health` 仍可 200 |
+| — | Deferred | ledger GET 与 MISSING 解耦；outbox/projector；历史 work_dir 治理；五条时序指标与 60s SLO；迁仓外路径 | 另开 long-term，不进本 gap 关门 |
+
+Wave 1 若只改脚本、不改 compose，从 `/tmp` 做「合法 rebuild」仍会把 `./data/dev` 解析到空根。因此 **Wave 1 与 Wave 2 必须同批**。
+
+## Unit A — 即时恢复 Runbook（实施待再批）
+
+授权：事故抢占。主仓 CURRENT 即使仍显示 `implementer_cursor` / `e2e`，实施时也要写入抢占记录，停止该 e2e 对 `agent-dev` 的使用，并通知 queue 中的 `governance-action-level-authz`。以**主仓** CURRENT 与 `docker inspect` 为准，禁止信任任何 worktree 副本里的 `idle`。
+
+**冻结 = 停进程，不是文档 mutex，也不是「请大家别保存」。** 仓库没有 maintenance 开关。
+
+1. 在主仓 CURRENT 登记抢占：`holder=incident-preempt`，`scope=RUNTIME-DATA-ROOT Unit A`，`mutex=infra-runtime-state`。记录三容器 ID / created / `Mounts.Source` / compose working dir。
+2. **先停写再盘点**（保留 `shuimu-context-pg-dev`）：
+
+   ```bash
+   docker stop shuimu-pi-agent-dev shuimu-cursor-agent-dev shuimu-agent-app-dev
+   ```
+
+   未停止不得开始差异扫描。test/main 容器禁止触碰。
+3. 对主仓 `…/Agent-System/data/dev` 与 `/tmp/as-dev-wf409-merge/data/dev` 做只读 inventory：相对路径、size、mtime、SHA。使用 `find -P` / 不跟随 symlink；先 `Lstat` 跳过非常规文件。特别列出 08:40 UTC 之后的新增/修改，以及 `agent_sessions`、attachments、CAS、非 `output.md`。
+4. 备份目的地必须在仓库外、权限 `0700`、与运行数据根分离。`agent_sessions` / token / `.env` 只记存在性与大小，不拷贝明文。禁止把 `/tmp` 备份写进 `data/dev` 或 git 工作区。禁止 `cp -r` 覆盖主根。
+5. 按 **DB/ledger vs 主根 vs 错误根** 出 disposition 清单（保留主根 / 回收错误根独有项 / 标 orphan）。项目 143 只是抽样锚点，不能代表 100 条记录或 68 条主仓历史 missing。冻结时刻重新计算三方 hash；**删除「必须仍为 `f283...f039`」硬门槛**。仅当冻结快照上 143 仍三方一致时，才允许「只纠挂、不改该文件」。
+6. 纠挂**必须**在主仓执行，禁止 `env-service.sh` 从 worktree 或 `/tmp/as-dev-wf409-merge` 调用：
+
+   ```bash
+   PRIMARY=/home/weichen/projects/Agent-System
+   docker compose --project-directory "$PRIMARY" \
+     -f "$PRIMARY/docker-compose.dev.yml" \
+     up -d --build \
+     app pi-agent cursor-agent
+   ```
+
+   数据库 named volume 不变。纠挂后立刻 `docker inspect`：三个 bind source 必须是 `$PRIMARY/data/dev` 及其 `workspaces`，不得再指向 `/tmp`。
+7. 验证：`GET /api/v1/docgov/documents/doc_proj143_intake/content` 在冻结快照仍一致时应 200；抽查若干活跃非模板文档的投影可见性。`/ready` 仍按现状理解（此时还没有 storage identity）。
+8. 错误根只读保留到报告签字；本方案**不授权删除** `/tmp/as-dev-wf409-merge`。
+9. **禁止**在 Wave 0 对项目 143 保存 marker、禁止真实 PI 改文。那些属于 Unit B 之后的页面验收，另批。
+
+### Wave 0 验收（仅这些）
+
+- [ ] 停写发生在 inventory 之前；Postgres 未删卷、未重建。
+- [ ] 两端 inventory + 仓库外备份 + disposition 清单落盘到 test-reports assets。
+- [ ] app/pi/cursor 的 bind mount source 回到主仓 `data/dev`（或 `…/workspaces`），compose working dir 不再是 `/tmp/as-dev-wf409-merge`。
+- [ ] 项目 143 在「冻结快照仍一致」时 content 200，文件内容与冻结 hash 一致。
+- [ ] 错误根仍在且未被覆盖/删除。
+- [ ] 主仓 CURRENT 记录抢占与恢复结果；不以 `/health` 200 作为通过。
+
+## Unit B — 防复发验收矩阵
+
+### 脚本与 Compose
+
+- [ ] primary repo、linked worktree、`/tmp` integration checkout 三种 `SOURCE_ROOT` 下，合法 config 的 state bind source 相同，且等于 allowlist 中的绝对 `ENV_STATE_DIR`。
+- [ ] 未配置 / 相对 / 不存在 / 环境名不符 / 指向 worktree 或 `/tmp` 的 state root 均 fail fast，已有容器不被 recreate。
+- [ ] 显式 `RUNTIME_STATE_ROOT` 不在 allowlist 时失败（不能靠「绝对路径」绕过）。
+- [ ] dev 命令不能挂 test/main 根。
+- [ ] `docker inspect`：app、pi-agent、cursor-agent 三者 mount source 同一 realpath 前缀。
+- [ ] CI 断言的是「禁止相对 `./data/<env>` + 两次渲染 source 相同」，**不是**「不得出现 primary 工作树内的绝对 `data/dev`」。
+
+### Readiness
+
+- [ ] 错误空根、业务库无 sentinel、canonical path 不符：`/ready` 503，dev compose healthcheck 显示 unhealthy。
+- [ ] `/health` 保持 liveness，部署脚本不得用它当就绪。
+- [ ] `/ready` 不泄露 UUID/路径/doc 内容。
+
+## 回滚策略
+
+- Unit B 代码可回滚，但 **不得回滚/重建已配对的 storage UUID**；旧相对 bind **禁止**作为回滚方案。
+- Unit A 失败：保持停写，不要把容器重新绑回 `/tmp`。
+- 任何自动修复（若未来另批）只覆盖 `MISSING + identity matched + 无历史 fork`；fork 保留证据，服务继续。
+
+## 方案边界
+
+| 阶段 | 允许 | 禁止 |
+|---|---|---|
+| 审查修订（本轮） | 改 `.doc` 方案与 SSOT | 改业务代码、rebuild、写库、覆盖/删除正文或 `/tmp` |
+| Unit A（再批后） | 停 dev app/pi/cursor；只读保全；从主仓纠挂三容器 | 改 test/main 运行态；删错误根；Wave 0 写 143；从 worktree 调 `env-service` |
+| Unit B（再批后） | 改仓库内 compose/脚本/`/ready`；test/main **文件**可改绝对变量 | 对运行中的 test/main 做 mutating env-service；自动 mint identity；迁仓外 |
+| Deferred | 另开 long-term | 当作本事故关门条件 |
+
+## 监控（Unit B 最小集 / 其余 Deferred）
+
+Unit B 只要求：部署日志记录 source commit、compose working dir、state root、实际 mount source hash；禁止记录正文与凭证。`storage_identity_mismatch` 作为 `/ready` 布尔即可。
+
+五条 Prometheus 指标、60 秒 pending SLO、`/ready` 投影计数阈值整节移出本方案。
+
+## 相关链接
+
+- Audit: [dev rebuild 从临时 worktree 挂载空数据根](../audit/2026-09-14-dev-runtime-data-root-split-brain.md)
+- Short-term: [dev runtime data root guard](../ops/short-term/2026-09-14-dev-runtime-data-root-guard.md)
+- gap-matrix 行: `RUNTIME-DATA-ROOT-SPLIT-BRAIN`
+
+## 审查修订记录
+
+原文矛盾已在本文消除，不再保留互斥表述：
+
+- `RUNTIME_STATE_ROOT` 同时被写成「每环境根」和「父目录+/<env>」
+- 「本轮不重建」与 Wave 0 重建互相否决（现按阶段表）
+- Wave 0 冻结 143 SHA 与 Runbook 要求保存 marker
+- Wave 0 验收 storage identity（Wave 3 才有）
+- Wave 1 宣称 bind 固定但 compose 仍相对
+- Wave 2 CI 禁止工作树内 `data/<env>` 与短期默认根互斥
+- fork「停机式处理」与 409 继续服务互斥
+- PATCH 投影失败的 HTTP 状态分叉
+- GET `projection_status` 与 job state 混用
+- `CONTENT_FORK` 与 `DOCUMENT_CONTENT_PROJECTION_DRIFT` 对外码漂移
+- shared compose 套用每环境公式
+- 「暂停售写」未定义
+- 恢复与 outbox/治理/完整 SLO 同一关门条件

.doc/remediation/2026-09-14-final-artifact-vault-remediation.md

@@ -0,0 +1,247 @@
+---
+title: "最终成果保险库与受控恢复整改方案"
+status: planned
+created: 2026-09-14
+updated: 2026-09-14
+deepened: 2026-09-14
+---
+
+# 最终成果保险库与受控恢复整改方案
+
+## 背景
+
+提案评审见[最终成果保险库调研](../ops/research/2026-09-14-final-artifact-vault.md)。当前受控文档账本、助手消息和附件 CAS 分别覆盖局部持久化，但都仍与运行 PostgreSQL 或 `RUNTIME_STATE_ROOT` 绑定；工作区 split-brain 已证明成果定位不能依赖 `output.md` 路径。
+
+本方案把 FAV 作为[运行数据生命周期方案](./2026-09-14-runtime-data-lifecycle-and-migration-corpus-remediation.md)的长期成果层。它不替代当前事故的固定数据根整改，也不替代完整数据库备份。
+
+## 目标
+
+1. 只有服务端确认的终态文档、终态助手回复及其必要附件进入 FAV，中间结果准入率为 0。
+2. 每个成果都有稳定 UUID、语义 manifest、payload SHA、来源终态证据、保留策略和可验证发布回执。
+3. FAV 使用独立存储身份，工作区清理、worktree 删除和 app rebuild 不影响已验证成果。
+4. 数据库正文缺失但授权图完整时可只读降级；数据库关系损坏时只能经 scratch 恢复、冲突预览和人工 promotion。
+5. 完整数据库恢复、migration corpus 与成果级恢复分别演练、分别签字。
+
+## 核心决策
+
+1. **互补而非替代**：PostgreSQL 是运行关系与授权权威；FAV 只对已归档 payload 与 manifest 权威；workspace 是可清理投影。
+2. **事件准入而非目录扫描**：由 `agent_commit`、`approved`、`sealed`、显式 publish 和 completed chat turn 发起准入判断，禁止扫描 workspace 猜测“final”；显式 publish/pin 只是请求，不能绕过终态 allowlist。
+3. **事务 outbox**：业务终态与 publish request 同事务；异步 publisher 幂等写对象并最后写 commit marker。
+4. **默认只归档高价值回复**：completed + `export_policy=full` 自动进入；`copy_only` 仅显式 pin；`none` 永不进入。
+5. **恢复默认生成新受控对象**：`recover-as-collection` 保留来源；只有依赖、授权和 ID 无冲突时才允许 `relink`。
+6. **清理受覆盖率门禁**：应归档而未 `verified` 的成果会阻止受管 dataset/持久状态源销毁；普通计算 workspace 在终态 payload 已冻结后可按 TTL 清理，不能再成为成果事实源。
+
+### 终态准入协议（U1 必须固化）
+
+| 类型 | 允许的权威数据库事实 | payload 来源 | 拒绝条件 |
+|---|---|---|---|
+| Agent 文档提交 | `document_agent_candidates.status='committed'`，存在 `output_snapshot_id`，且对应 `document_change_events.change_kind='agent_commit'` 的 `to_snapshot_id` 与该 snapshot 一致 | `document_content_blobs` 对应不可变 snapshot | ready/needs_confirmation/rejected/stale/quality_failed、snapshot/event 不一致 |
+| sealed 文档版本 | `document_versions.status='sealed'` 且 `sealed_at` 非空 | 该版本 `head_snapshot_id` | open、head 缺失 |
+| approved 受控文档 | `document_records.current_state='approved'`、`approved_at` 非空且 `review_snapshot_id` 非空 | 冻结的 `review_snapshot_id`，不得取 workspace 当前文件 | reviewing/approving/rejected、review snapshot 缺失 |
+| 自由文档发布 | 显式 publish 事件引用已存在的不可变 ledger snapshot | 事件指向的 snapshot | 只有 UI 动作但无不可变 version，或事件后才读取“最新”正文 |
+| 助手最终回复 | `chat_turns.status='completed'`、`completed_at` 和唯一 `assistant_message_id` 均存在；同事务对精确正文计算的 policy snapshot 为 `full`，或为 `copy_only` 且存在 completed 后的显式 pin 事件 | 同事务冻结到 staging 的精确消息 revision/SHA | pending/streaming/failed/cancelled、placeholder/card/status、policy none/restricted/分类失败、pin 时未 completed |
+
+HTTP/SSE handler 只能调用这一套领域 eligibility 服务，不能自己根据字符串或响应结束推断终态。U1 先以当前数据库列和约束写 characterization test；若发现任一完成链缺少上述事实，先补领域状态机/事务边界，再允许接入 FAV。
+
+## 高层架构
+
+```mermaid
+flowchart TB
+  A[Document or chat terminal transaction] --> B[Operational PostgreSQL]
+  A --> C[artifact.publish.requested outbox]
+  C --> D[Idempotent publisher]
+  D --> E[Content-addressed blobs]
+  D --> F[Semantic manifest]
+  F --> G[Commit marker and receipt]
+  G --> H[Cleanup coverage gate]
+  G --> I[Authorized degraded read]
+  G --> J[Scratch recovery and reconciliation]
+```
+
+### 发布状态机
+
+```mermaid
+stateDiagram-v2
+  [*] --> requested
+  requested --> publishing
+  publishing --> verified
+  publishing --> retryable_failed
+  retryable_failed --> publishing
+  verified --> tombstoned
+  tombstoned --> purged
+```
+
+只有 `verified` 成果可用于清理门禁和恢复。manifest 写完但没有 commit marker 的对象视为未发布；`tombstoned` 内容不能被读取或恢复。
+
+## 数据与存储契约
+
+### 运行库注册表
+
+新增等价模型：
+
+```text
+final_artifacts
+  artifact_uuid, artifact_type, logical_resource_id
+  environment, project_id, project_external_key, source_event_id
+  source_snapshot_id / source_message_id / source_run_id
+  payload_sha256, manifest_sha256, vault_storage_identity
+  terminal_state, policy_version, retention_class
+  publication_status, requested_at, verified_at, tombstoned_at
+
+artifact_payload_staging
+  staging_uuid, project_id, source_event_id, payload_sha256
+  encrypted_payload / content_blob_ref, classification, created_at, releasable_at
+
+artifact_blob_references
+  artifact_uuid, project_scope, payload_sha256, envelope_key_ref
+  reference_status, retention_class, legal_hold, timestamps
+
+artifact_publication_attempts
+  artifact_uuid, idempotency_key, attempt_no, error_code, receipt, timestamps
+
+artifact_deletion_ledger
+  artifact_uuid, reason, authority, effective_at, applied_at, audit_ref
+```
+
+实现时优先复用现有 `outbox_events` 投递框架；归档注册与文档/消息终态的原子边界需由所属服务事务负责，不能由 HTTP handler 事后拼接。
+
+幂等 key 由业务终态事务确定性生成：`artifact_type + environment + project_external_key + logical_resource_id + source_event_kind + source_event_id + payload_sha256 + policy_version`。数据库对该 key 建唯一约束；同一终态重试/重新发布复用 key，新终态事件或新 payload 生成新 artifact，不用 outbox event ID 或 publisher 本地状态充当业务幂等键。
+
+当前仓库没有 tenant 实体；本期安全边界沿用现有 `environment + project_members/role-admin` 模型，不新增无法校验的 `tenant_id`。若未来引入组织/租户层，须另立 ADR 和数据迁移，不能仅改路径字段。
+
+终态事务必须把**精确 payload 字节或不可变 content blob 引用、SHA、来源版本**一并冻结到 staging，outbox 只引用 staging；publisher 不得在事务后重读可修改或会级联删除的消息行。staging 在成果 `verified` 或依法 `tombstoned` 前不得回收，且正文不能进入普通 outbox payload、日志或指标。
+
+### Vault 对象布局
+
+```text
+scopes/<environment>/<project_external_key>/blobs/sha256/<2>/<2>/<sha256>
+manifests/<artifact_uuid>/<manifest_sha256>.json
+commits/<artifact_uuid>/<manifest_sha256>.json
+tombstones/<artifact_uuid>/<event_uuid>.json
+catalog/checkpoints/<catalog_version>.json
+```
+
+路径不包含用户文件名、Prompt 或数据库自增 ID。manifest 记录逻辑标识、来源、成员、hash、终态证据、schema/producer/storage identity、敏感级别和保留策略；commit marker 最后生成。
+
+U1 必须交付版本化 `manifest.schema.json`、`commit-marker.schema.json` 和 `tombstone.schema.json`，并由同一 Go 类型/validator 验证。schema 采用 major/minor：读端必须兼容同 major 的旧 minor；未知 major fail closed 并进入迁移队列，不能静默猜字段。commit marker 至少绑定 artifact UUID、manifest SHA、全部 required member SHA、storage identity、committed_at 和 publisher version。
+
+CAS 只在项目安全作用域内去重，并采用项目作用域 envelope key；`artifact_blob_references` 是 tombstone、legal hold 和物理回收的权威引用账本。tombstone 立即撤销该 artifact 的读取和密钥包装；仅当该作用域内最后一个有效引用消失且 retention/legal hold 允许时，才清除 key wrapping 与 blob。跨项目相同 SHA 必须保持密码学与删除边界隔离。
+
+删除事务在运行库写 `artifact_deletion_ledger` 与删除 outbox，vault tombstone 是独立持久的拒绝恢复证据。读取/恢复采用 **union-deny**：任一侧声明删除都拒绝；两侧不一致进入 quarantine 和告警，不得恢复。purge 后仍永久保留最小 tombstone（或经校验的压缩删除目录），完整备份恢复后重放删除账本，防止旧备份复活数据。
+
+## 分波次计划
+
+| 波次 | 内容 | 验收 |
+|---|---|---|
+| V0 协议与 ADR | 固化三层权威边界、终态准入矩阵、manifest schema、恢复语义和删除模型 | ADR 与 JSON schema 评审通过；所有成果类型都有允许/拒绝状态 |
+| V1 存储与发布内核 | 建 `internal/artifactvault`、注册表/staging/outbox/attempt/reference/deletion migration、filesystem backend、项目作用域加密 CAS、manifest/commit marker 和幂等 publisher | 重复投递只生成一个逻辑成果；崩溃点重试不产生半发布可见对象；坏 SHA 拒绝 verified；跨项目同 SHA 不共享删除或密钥边界 |
+| V2 文档接入 | 从账本 snapshot 接入 agent committed、sealed、approved 和显式 publish；approved hook 改读账本而非 workspace | ready/rejected/stale/quality_failed 不入库；清空 workspace 后仍能校验/读取归档正文 |
+| V3 助手回复接入 | 把消息正文定稿、chat turn completed 和 publish request 收敛到原子服务边界；复用 `replyexport` 分类并增加真实回合状态校验 | placeholder/stream/error/card 不入库；completed+full 精确归档一次；SSE done 前已有 durable request |
+| V3.5 存量终态回填 | 只从权威数据库账本、批准事件和 completed chat turn 枚举既有终态，以来源事件 + payload SHA 生成确定性请求；缺正文/证据项进入 quarantine 或批准排除 | 重跑不增加逻辑成果；不扫描 workspace；每个排除项有原因、批准人和审计记录；清理 coverage 有可达分母 |
+| V4 查找与降级读取 | 建授权后的 artifact lookup；正文缺失且授权完整时返回带 degraded 标记的 FAV 内容；权限图缺失时 fail closed | 跨用户/跨项目负例通过；GET 不写数据库；vault 不可用时返回 typed degraded/error 而非伪 404 |
+| V5 恢复工具 | 建 inventory/verify/recover-plan/recover-apply；强制验证 scratch identity，使用无运行库权限的恢复凭证；默认 recover-as-collection，relink 需完整依赖、授权和人工确认 | DB 全删的隔离环境可重建成果目录；运行库目标、未授权操作者、计划篡改、冲突、删除账本和缺权限依赖均阻止 promotion |
+| V6 清理与运维门禁 | dataset inventory/GC 加 coverage；readiness 暴露 identity/connectivity/lag，metrics/alerts/checksum scrub/复制与 runbook 落地 | 未 verified 成果阻止销毁；workspace 清空、app rebuild、离线副本恢复演练均 PASS |
+
+## 实施单元与文件落点
+
+### U1. 终态协议、manifest 与数据库模型
+
+- **目标**：先建立可审计的准入和恢复契约，避免把所有“完成”字符串当终态。
+- **文件**：`.doc/adr/` 新 ADR；`deploy/postgres/goose/000xx_*final_artifact*.sql`；`internal/artifactvault/types.go`、`manifest.go`、`eligibility.go`、`manifest.schema.json`、`commit-marker.schema.json`、`tombstone.schema.json` 及对应测试。
+- **测试场景**：每类允许事件生成确定 artifact key；所有候选/失败/中间状态拒绝；未终态的显式 publish/pin 仍拒绝；secret、认证材料、restricted 或分类失败均在正文进入 outbox/staging 前 fail closed；manifest 必填字段、版本和 SHA 错误 fail closed；迁移 Up/Down 与约束验证。
+- **完成证据**：准入矩阵与 schema 一致，未分类类型默认拒绝。
+
+### U2. 独立存储与幂等 publisher
+
+- **依赖**：U1。
+- **文件**：`internal/artifactvault/store.go`、`filesystem_store.go`、`publisher.go`、`publisher_test.go`；`internal/config/config.go`；环境配置与 Compose 校验。
+- **执行说明**：vault 使用独立最小权限身份；凭证只从受管 secret/env 注入，不进入仓库、manifest、日志或业务数据库。后端必须启用传输加密和静态加密，manifest 只保存 key reference。filesystem 后端采用同文件系统临时文件、校验、文件 `fsync`、原子 no-replace rename、父目录 `fsync`，blob 与 manifest 持久化后才提交 marker。
+- **测试场景**：同一 outbox 重复消费；blob 已存在；每个写入/fsync/rename 边界强制终止后重启；损坏 blob；错误 storage identity；凭证轮换；vault 暂时不可用后重试；跨项目同 SHA、单方 tombstone、legal hold 和最后引用 purge。
+- **完成证据**：只有完整且已持久化的 manifest + commit marker 可见，publisher 不读 workspace 推断成果；任一项目删除不破坏其他项目成果。
+
+### U3. 文档账本与治理终态接入
+
+- **依赖**：U1、U2。
+- **文件**：`internal/docrevision/pg_mutate.go`、`internal/docgov/engine.go`、`internal/bizdev/service.go`、`internal/server/document_revision_handlers.go` 及 PG/服务测试。
+- **执行说明**：先补 characterization/PG 测试，再调整事务边界和 approved hook。
+- **测试场景**：agent commit、sealed final、approved review snapshot、已满足终态 allowlist 的显式 publish；未终态显式 publish、pending/reject/stale/quality failed 负例；投影缺失但账本和归档一致；同 run 重试。
+- **完成证据**：归档 payload 来自不可变账本 snapshot，不读取 `output.md` 作为事实源。
+
+### U4. 最终助手回复原子接入
+
+- **依赖**：U1、U2。
+- **文件**：`internal/ctxmgr/chat_turns.go`、`message_update.go`、`internal/server/task_finalize.go`、`internal/chat/session.go`、`internal/replyexport/policy.go` 及对应测试。
+- **执行说明**：先刻画同步回复、异步任务、SSE 断线重试三条完成链，再收敛到一个 terminal-finalize 领域事务。该事务以锁定的 message revision/content 重新计算并冻结 policy snapshot，不能信任 handler 传入或较早缓存的 `export_policy`；pin 是对已 completed 的精确 revision/SHA 追加独立终态事件。
+- **测试场景**：completed+full、completed+copy_only+显式 pin；未 completed 的 pin/publish、凭证回显、restricted/分类失败、placeholder 更新、failed/cancelled、card/status、重复 finalize、SSE done 前后崩溃；请求后修改/删除原消息再消费仍归档原 SHA；日志和指标不含正文。
+- **完成证据**：消息精确正文、completed turn、不可变 staging 和 publish request 同事务，不存在“完成但永远未请求归档”或“发布时读到后来正文”的窗口。
+
+### U7. 存量终态回填与覆盖率基线
+
+- **依赖**：U3、U4。
+- **文件**：`cmd/artifact-vault/backfill.go`、`internal/artifactvault/backfill.go` 及 PG 测试；dataset inventory 工具。
+- **执行说明**：只枚举不可变 document snapshot/终态事件和 completed chat turn，不读 workspace；用稳定来源事件 + payload SHA 幂等生成 staging/request。证据不足或正文缺失项进入 quarantine；排除需理由、批准人、有效期和审计记录，不能用“旧数据”批量豁免。
+- **测试场景**：回填重复执行、并发新终态、旧消息已删、缺 snapshot、批准排除过期、quarantine 修复后重跑。
+- **完成证据**：存量 coverage 的分子、分母、quarantine 和批准排除均可复算，V6 清理门禁不靠人工改数字通过。
+
+### U5. 授权查找与只读降级
+
+- **依赖**：U2–U4。
+- **文件**：`internal/artifactvault/catalog.go`；`internal/server/project_doc_handlers.go`、`reply_export_api.go`、`handlers.go` 及鉴权测试。
+- **执行说明**：降级读取不是独立权限或直连 vault 能力；必须先由运行库中的 resource→project 关系定位资源，再用现有 `requireProjectAccess`/系统管理员判定完成与正常读取相同的服务端授权。manifest 只用于交叉校验 project external key/sensitivity，绝不自行授予权限；任一授权依赖缺失或结果不确定即 fail closed。
+- **测试场景**：DB 正常时不走 FAV；投影/正文缺失且现有项目授权完整时降级；项目关系缺失、越权、跨项目同 SHA、tombstone、manifest/SHA 异常全部 fail closed；GET 零写入。
+- **完成证据**：响应显式标识来源与降级原因，不再把存储不一致伪装为 404。
+
+### U6. 隔离恢复、清理门禁与演练
+
+- **依赖**：U2–U5、U7。
+- **文件**：`cmd/artifact-vault/`、`internal/artifactvault/recovery.go` 与测试；`scripts/backup-system-db.sh`、`restore-system-db-drill.sh`；dataset 生命周期工具；`.doc/test-reports/`。
+- **执行说明**：`recover-apply` 先核验数据库 identity 并拒绝 dev/test/main 与任何非 scratch 目标，只接受无运行库权限的恢复专用凭证。操作者须通过 `role-admin` 与明确恢复能力校验；relink/promotion 还需目标项目授权和指定数据责任人确认。actor、plan hash、目标 identity 和 promotion 结果写不可变审计。恢复计划显式分类 UUID collision、SHA mismatch、partial dependency、authorization gap、metadata conflict；默认全部 fail，只有 recover-as-collection 可对允许的孤立成果生成新 UUID，relink 不允许 skip/prompt 后带冲突提升。
+- **清理门禁**：只允许 `dataset inventory/gc/destroy` 和环境 teardown 脚本执行受管销毁，preflight 服务不可用或 coverage 非 PASS 时 fail closed；vault/app 身份没有删除 dataset 的权限，运维删除身份单独审计。普通计算 workspace 可按 TTL 清理，因为终态确认前已把 payload 冻结进 staging；原始 shell/root 删除无法由应用层绝对阻止，必须靠主机权限与操作制度限制，不能在验收中声称“拦截任意 rm”。
+- **测试场景**：空 scratch 库 recover-as-collection；依赖齐全 relink；五类冲突；运行库 DSN、未授权操作者、计划 hash 被篡改、缺 blob、删除账本/tombstone 不一致与重放；未 verified 或 preflight 不可用阻止受管 GC；workspace 清空与 app rebuild；异机副本恢复。
+- **完成证据**：项目 6173 等价脱敏 corpus 完成“终态生成 → 发布 → 清 workspace → 读取 → scratch 恢复 → rebuild”真实链路。
+
+## 验收标准
+
+- [ ] 中间状态、流式片段、工具轨迹和 workspace 草稿进入 FAV 的测试结果为 0。
+- [ ] 应归档终态成果的 publish request 覆盖率为 100%，verified 延迟与失败积压可观测。
+- [ ] 任一 publisher 崩溃点都可幂等恢复，半成品不对读/恢复可见。
+- [ ] 工作区全部删除或换根后，已 verified 成果仍可由稳定逻辑 ID 定位并通过 SHA 校验。
+- [ ] 授权图缺失时 fail closed；跨环境/project/user 的读取和恢复负例通过；当前实现不伪造 tenant 边界。
+- [ ] 显式 publish/pin 不能绕过终态 allowlist；敏感分类失败或命中禁止内容时正文不进入 staging/outbox/vault/日志/指标。
+- [ ] 存量终态回填可幂等重跑；quarantine 与批准排除均有可复算审计，coverage 分母不可手工绕过。
+- [ ] 项目作用域引用账本保证 tombstone 立即不可读，最后有效引用且无 hold 时才清除密钥和对象。
+- [ ] FAV 可以在空 scratch 库恢复成果集合，但不能伪造权限、活动工作流、lease、pending task 或完整历史。
+- [ ] tombstone/删除账本在 restore 后重放，已删除内容不会复活。
+- [ ] PostgreSQL 完整 restore、migration corpus 升级和 FAV 部分恢复三条演练均有独立报告。
+- [ ] dev 清理只有在完整备份可恢复、migration corpus PASS、FAV coverage PASS 后才能进入销毁审批。
+
+## 风险与缓解
+
+| 风险 | 缓解 |
+|---|---|
+| FAV 变成第三真相源 | 限定只对 payload/manifest 权威；运行指针和授权始终由数据库决定 |
+| “最终”判定过宽导致存满中间结果 | 状态机 allowlist + 未分类拒绝 + 准入指标/抽样审计 |
+| 数据库提交与归档双写丢事件 | 同事务 outbox + 幂等 publisher + cleanup coverage gate |
+| outbox 指向可变或已删除正文 | 终态事务冻结精确 payload/SHA 到不可变 staging，publisher 只读 staging |
+| 存量终态不触发新 hook | 权威数据库幂等回填 + quarantine/批准排除审计，禁止 workspace 猜测 |
+| 归档可读但无法重建业务关系 | manifest 声明依赖与恢复能力；默认 recover-as-collection；完整灾备继续依赖 DB backup/PITR |
+| WORM、共享 blob 与删除义务冲突 | 项目作用域加密 CAS + manifest-member 引用账本；按 retention class 选 governance/compliance；单独 legal hold；最后引用后密钥/对象清除 |
+| 同机独立目录仍无法抗磁盘故障 | 第一阶段独立 mount/identity，生产要求异机或对象存储复制并做恢复演练 |
+| 归档泄露敏感上下文 | 结构化排除 Prompt/轨迹；服务端敏感分类 fail closed；最小化 metadata；传输/静态加密、项目授权、凭证隔离和访问审计 |
+
+## 明确不采用
+
+- 定时扫描 `**/output.md` 并复制“最新文件”。
+- 把所有 assistant 消息、SSE event 或 agent session 全量归档。
+- 在业务事务内同步调用对象存储，或反过来先写对象再提交业务状态。
+- DB 不一致时由 GET 请求静默重建/覆盖数据。
+- 因为 FAV 有最终正文就删除完整备份、WAL 或 migration corpus。
+- 把所有对象永久 compliance lock，忽略合法删除和数据最小化。
+
+## 相关链接
+
+- Research: [最终成果保险库与部分恢复边界](../ops/research/2026-09-14-final-artifact-vault.md)
+- Parent remediation: [运行数据生命周期与迁移语料库](./2026-09-14-runtime-data-lifecycle-and-migration-corpus-remediation.md)
+- Incident remediation: [dev 数据根隔离与投影自愈](./2026-09-14-dev-runtime-data-root-and-projection-remediation.md)
+- Short-term: [最终成果保险库方案](../ops/short-term/2026-09-14-final-artifact-vault-plan.md)
+- gap-matrix: `RUNTIME-DATA-ROOT-SPLIT-BRAIN`

.doc/remediation/2026-09-14-runtime-data-lifecycle-and-migration-corpus-remediation.md

@@ -0,0 +1,182 @@
+---
+title: "运行数据生命周期与迁移语料库整改方案"
+status: planned
+created: 2026-09-14
+updated: 2026-09-14
+---
+
+# 运行数据生命周期与迁移语料库整改方案
+
+## 背景
+
+合理性和当前数据画像见[调研](../ops/research/2026-09-14-runtime-data-retention-and-migration-corpus.md)。本方案是 [dev 数据根与投影整改](./2026-09-14-dev-runtime-data-root-and-projection-remediation.md) Wave 5 的详细子方案。
+
+目标不是“为了省事删数据”，而是把不可控的历史运行库转化为：
+
+- 少量可展示、可解释的当前数据；
+- 少量可重复、可断言的迁移/回归语料；
+- 大量自动过期的隔离测试数据；
+- 可恢复后再销毁的旧卷。
+
+## 目标
+
+1. dev 常驻项目控制在 6–10 个，均有 owner、用途、数据类别和过期/固定理由。
+2. test 不再积累跨轮测试数据；每轮使用独立 DB + state root，PASS 即删，FAIL 短期保留。
+3. 每次发布同时验证 clean install、受支持旧版本升级、选择性数据导入、reload/rebuild 和 rollback。
+4. 数据库 dump 与文件状态根成对归档，具备 storage identity、SHA manifest 和自动断言。
+5. 清理不产生孤儿 snapshot/run/blob/workspace，不误删共享 blob，不接触未授权 main/KB 数据。
+6. 最终成果在清理前进入独立 [Final Artifact Vault](./2026-09-14-final-artifact-vault-remediation.md) 并取得 verified 回执；该回执不能替代完整备份和 migration corpus。
+
+## 数据保留策略
+
+| 环境 | 常驻内容 | 自动过期 | 明确保留 | 禁止事项 |
+|---|---|---|---|---|
+| dev | 3 个 workflow demo + 2–4 个当前 regression + 明确人工项目 | 普通 E2E 24h；失败运行 7 天；上一版 demo 14 天 | pinned 项目、当前/上一 release 对照 | 不按 ID/目录 mtime 直接删除；不把真实内容提交为 fixture |
+| test | 无长期业务项目 | PASS 立即销毁；FAIL 3–7 天 | 最近 1 次失败环境用于排障 | 不连接 dev/test 共享库跑 destructive test |
+| main | 真实业务/正式展示 | 暂不自动过期 | 由产品、审计、合规规则决定 | 本方案不授权清理或测试写入 |
+| shared KB | 法规知识库 | 独立策略 | 现有 KB 备份体系 | 不随项目数据轮换 |
+
+## 数据标识模型
+
+新增数据集注册表或等价 SSOT：
+
+```text
+dataset_id
+class: operational_pinned | demo_current | regression_golden |
+       migration_baseline | ephemeral_test | quarantine
+environment
+source_schema / target_schema
+source_commit
+storage_identity
+owner
+retention_until
+pinned_reason
+contains_sensitive_data
+manifest_uri / manifest_sha256
+required_artifact_count / verified_artifact_count
+status: building | verified | active | quarantined | expired | destroyed
+```
+
+项目至少增加 `dataset_id`、`data_origin`、`retention_until`、`pinned_at/pinned_reason`；自动测试创建项目时必须带 `ephemeral_test` origin 和 run namespace。未分类数据默认不可自动删除，而不是默认过期。
+
+## 工具设计
+
+### 1. `dataset inventory`
+
+只读生成候选清单：项目关系行数、doc/run/session IDs、workspace、CAS 引用、最后活动时间、生命周期、是否有 ledger/fork/missing、敏感级别、推荐动作。输出 JSON + Markdown；不接受模糊环境名。
+
+### 2. `dataset export`
+
+按 dataset/project allowlist 导出关系闭包，不能只导 `projects` 表。必须同时打包：
+
+- project/chat/task/workflow/governance/document/revision/notification/outbox/audit 关系；
+- 账本 blob 与受控/自由文档文件；
+- file reference 指向的 CAS blob；
+- workspace/agent session 中经 allowlist 认领的文件；
+- schema/version/storage identity/count/SHA manifest。
+
+导出后在隔离区执行脱敏；真实账号 token、auth sessions、credential、原始敏感附件默认剔除或替换。
+
+### 3. `dataset restore --isolated-only`
+
+强制目标数据库名/端口/state root 满足隔离规则；拒绝 5433/5434/5435 及 `agent_system_dev|test|main`。实际执行 `pg_restore`，再导入文件包，不能只做 `pg_restore --list`。
+
+恢复顺序：创建空库 → 恢复 source schema/data → 校验 source assertions → 执行 Goose up → 校验 target assertions → 重建 projection/index → restart/reload → 再次校验。
+
+### 4. `dataset rotate`
+
+生成计划而不直接删除：`retain | replace | quarantine | destroy`。执行必须使用 manifest ID、期望 storage UUID 和确认短语；禁止 `--all`、模糊 glob、未解析环境变量。
+
+### 5. `dataset gc`
+
+仅在数据库引用闭包和文件 manifest 都验证后执行：
+
+- 删除明确 dataset/project 的关系闭包；
+- 清理无引用 document content blob/CAS blob；
+- 清理已归属 workspace/session；
+- `setval`/identity sequence 修复；
+- 输出 before/after counts、孤儿检查与可恢复位置。
+
+首轮 dev 推荐不在旧库运行 GC，而是蓝绿新建后切换；GC 用于后续小规模过期数据。
+
+### 6. `artifact coverage`
+
+按服务端终态事件盘点应归档成果，并与 FAV verified receipt 对账。任何必需成果处于 requested/publishing/failed/missing，或 vault storage identity 不匹配时，受管 dataset/持久状态源不得销毁。普通计算 workspace 只有在终态事务已冻结精确 payload 后才可按 TTL 清理；准入、manifest、恢复和删除边界见[最终成果保险库整改](./2026-09-14-final-artifact-vault-remediation.md)。
+
+## 迁移测试矩阵
+
+每个 release candidate 必须执行：
+
+| 测试轨 | 输入 | 验证重点 |
+|---|---|---|
+| Clean | 空 PostgreSQL + 空 state root | migrations 1→latest、官方 workflow seed、storage identity、ready |
+| Oldest | `oldest-supported` corpus | 跨版本 backfill、约束、ID sequence、文档 legacy repair |
+| Previous | `previous-release` corpus | 常规升级、API/UI 兼容、性能 |
+| Hazard | 最小异常 corpus | hard-break、projection missing/fork、旧消息 scope、高 ID、pending run |
+| Import | latest schema + selected demo/regression package | 关系闭包、文件 SHA、权限、通知、版本账本 |
+| Reload | import 后 app/pi rebuild + restart + 宿主级重载 | storage identity、mount、task 恢复、正文/overlay |
+| Rollback | 切换失败后接回 quarantine 旧卷 | RTO、旧 storage identity、无新写丢失 |
+| Artifact recovery | 已归档终态成果 + 空 scratch DB | manifest/SHA、删除账本、recover-as-collection、冲突预览、权限 fail closed |
+
+迁移通过必须包含真实 restore，不接受仅跑 Goose 幂等测试；产品签字至少包含真实页面登录、项目列表、对话、文档打开/修改、刷新、退出重登和 rebuild 后恢复。
+
+## 初次精简执行波次
+
+| 波次 | 动作 | 完成判据 |
+|---|---|---|
+| D0 冻结与标注 | 先完成当前 split-brain 遏制；冻结 dev 写入；对 366 个项目 inventory；人工确认 pinned/敏感/owner | 100% 项目有建议动作；未分类项不删除 |
+| D1 工具安全修补 | 移除备份脚本内默认凭证；backup 同时归档 DB+state；restore 强制 scratch 且真实恢复；加入 manifest/checksum/assertions | 恢复演练能从零创建隔离环境并通过 SHA/关系断言 |
+| D2 构建 corpus 与成果覆盖 | 建 schema 25、28/29、32/33 三个最小迁移包；构建 143 等价脱敏 hazard；选择 6173 current regression；盘点保留项目的终态成果并生成 FAV coverage | 每包可重复生成/恢复；必需成果均 verified 或有批准的排除理由，不依赖真实 main/test 数据 |
+| D3 新建 green dev | latest schema 空库 + 固定新 state root；导入选中的 6–10 项；执行 projection/CAS/sequence/integrity 校验 | 无 orphan；active 文档 aligned；ready/storage identity PASS |
+| D4 全链验收 | clean/oldest/previous/hazard/import/reload/rollback；真实页面和真实 PI 跑主链 | 报告区分工程、PG、PI、浏览器、restart/rebuild 证据 |
+| D5 原子切换 | 切换 dev 到 green identity；原 blue DB/文件根转只读 quarantine | 新环境持续观察 24–72h，无新增 blocker，可一键回接 blue |
+| D6 延迟销毁 | quarantine 满 7–14 天，再次 restore drill、差异确认、用户批准后销毁 | 记录销毁 manifest、范围、时间和不可恢复性；不得顺带清 main/KB |
+
+## 首轮建议保留/淘汰
+
+### 保留
+
+- 项目 143：临时 pinned，直到脱敏 legacy/hazard corpus 可替代。
+- 项目 6173：作为最新完整受控正文/版本/UI/restart 回归样本。
+- 项目 6159：作为 previous 对照保留一个发布周期，然后由 6173 替换。
+- 三正式工作流各一个新生成的确定性 demo；生成成功后不保留同类失败尝试。
+- 最近一次失败 E2E 的完整环境，最多 7 天，且与常驻 dev 隔离。
+
+### 不直接保留
+
+- 数百个无文档、无 run 或仅测试前置步骤的 planning/active 项目；
+- 重复的 UI Round 中间项目和已由更新 PASS 覆盖的失败项目；
+- 能由 unit/PG fixture 稳定重建的测试污染 workflow key、临时用户、session 和 run；
+- 无引用 CAS/workspace，需在 mark-and-sweep 验证后删除。
+
+该清单是初始建议，不是删除授权；最终 retain allowlist 应由 inventory 报告和用户确认生成。
+
+## 验收标准
+
+- [ ] dev 常驻项目 6–10 个，所有项目都有 dataset class/owner/retention。
+- [ ] 旧 366 项目对应的 blue DB+state 已成对备份并实际恢复成功。
+- [ ] green dev 从空库建成，选择性导入后 DB/file/storage UUID 一致。
+- [ ] 三个 migration baselines 与 hazard corpus 均能升到 latest 并通过断言。
+- [ ] 无 orphan task run、revision snapshot/version/event/report、CAS blob 或 workspace。
+- [ ] 项目 143/6173 页面打开、修改、刷新、重登、rebuild 后恢复 PASS。
+- [ ] 保留项目的应归档成果覆盖率为 100%，清空 workspace 后仍能定位并校验最终正文/最终回复。
+- [ ] FAV 在空 scratch 库完成受控部分恢复；未声称或伪造权限、lease、pending task 等未归档状态。
+- [ ] 新测试数据带 TTL，PASS 后自动销毁，失败数据按策略到期。
+- [ ] test/main/shared KB 未被误操作；所有破坏性动作有精确 manifest 和延迟销毁记录。
+
+## 不建议的方案
+
+- 每次直接 `docker compose down -v` 再凭记忆重建：无法证明保留数据和文件配对完整。
+- 在 dev 库中写一份巨型级联 DELETE：当前关系与文件引用复杂，容易留下孤儿或误删共享 blob。
+- 只保留最新时间的项目：会丢失最有价值的旧 schema/hazard 覆盖。
+- 把整份真实旧库永久当 migration fixture：迁移慢、不可重复、可能含敏感数据。
+- 把 FAV 当完整数据库替代品，或按 `output.md`/mtime 扫描猜测终态：会引入第三事实源并归档中间结果。
+- 修改历史 Goose migration 迎合新空库：已发布迁移不可重写；修正必须新增 migration。
+
+## 相关链接
+
+- Research: [运行数据精简、迁移语料与演示数据保留策略](../ops/research/2026-09-14-runtime-data-retention-and-migration-corpus.md)
+- Final Artifact Vault: [最终成果保险库与受控恢复](./2026-09-14-final-artifact-vault-remediation.md)
+- Parent remediation: [dev 数据根隔离与投影自愈](./2026-09-14-dev-runtime-data-root-and-projection-remediation.md)
+- Short-term: [运行数据生命周期方案](../ops/short-term/2026-09-14-runtime-data-lifecycle-plan.md)
+- gap-matrix: `RUNTIME-DATA-ROOT-SPLIT-BRAIN`

.doc/remediation/2026-09-20-module-decoupling-batch-plan.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`。
 
 ## 相关链接
 

.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

@@ -0,0 +1,402 @@
+---
+title: "通用模块平台封装与渐进采用 - Plan"
+type: docs
+date: 2026-09-22
+product_contract_source: ce-plan-bootstrap
+execution: knowledge-work
+---
+
+# 通用模块平台封装与渐进采用 - Plan
+
+## Goal Capsule
+
+让未来项目在新增功能和处理故障时，能够围绕明确的模块职责、通信契约与数据 owner 独立工作，并通过可重复验证判断问题是否被限制在约定范围内。
+
+采用[通用模块契约规范 MCS v0.1](../system-design/2026-09-22-generic-module-contract-standard.md)，以最小参考实现和故障验收推动平台封装。当前授权仅为现状研究、规范和方案编制；本文后续开发单元是建议工作，不是已启动的实施。
+
+当前项目证据来自[解耦现状审查](../audit/2026-09-22-module-decoupling-current-state.md)。通用规范独立复用，不依赖本项目的业务对象、路径或运行工具。本项目的既有 ADR/开发标准继续生效。
+
+---
+
+## Product Contract
+
+### Problem Frame
+
+模块分目录、共用接口和使用消息总线后，仍可能因共享数据、入口旁路、类型泄漏、慢消费者和不一致的失败语义发生连带问题。全面网络化又会增加超时、重复执行、部署和一致性成本。因此需要“职责与契约强约束 + 分档运行隔离 + 可证明的一致性”，并把横切能力封装复用。
+
+### Requirements
+
+**边界与复用**
+
+- R1. 通用标准必须可用于不同语言和业务，项目现状证据独立存放。
+- R2. 每个模块有职责、公开契约、数据 owner、不变量和目标隔离档位。
+- R3. 同一业务动作的不同入口保持授权、持久结果与事件语义一致。
+- R4. 统一封装覆盖共性通信治理，业务规则留在模块和显式编排中。
+
+**一致性与隔离**
+
+- R5. 命令、查询、事件、流有不同成功/失败语义；网络未知结果可恢复。
+- R6. 数据 owner、事务、幂等、顺序与租约共同保证已声明的不变量。
+- R7. 慢任务、错误、过载和进程崩溃在所选隔离档位下有明确影响范围。
+- R8. 并发/故障/兼容测试是验收的一部分，不能只靠静态依赖检查。
+
+**落地范围**
+
+- R9. 先建立小型可验证参考实现，再推广到第二个场景；不先造完整微服务平台。
+- R10. 本次只交付待审文档，业务实施、平台仓库创建、外部发布和环境操作留待单独授权。
+
+### Acceptance Examples
+
+| ID | 例子 | 验收结果 |
+|---|---|---|
+| AE1 | 两个入口提交相同授权动作 | 持久状态与事件一致，拒绝边界相同；覆盖 R3 |
+| AE2 | 并发重复/响应丢失后重试 | 单一业务效果、结果可查询；覆盖 R5/R6 |
+| AE3 | 慢消费者 + 其他消费者持续工作 | 后者仍达到约定延迟预算；覆盖 R7 |
+| AE4 | 首条高版本、乱序和过滤订阅 | 按明确契约推进，不误把空洞当丢失；覆盖 R6 |
+| AE5 | 新旧契约混跑与失败回退 | 无数据丢失或旧客户端误解释；覆盖 R8 |
+| AE6 | 参考实现替换传输适配器 | 业务不变量相同，额外网络失败行为显式呈现；覆盖 R4/R5 |
+
+### Scope Boundaries
+
+本次文档范围包括：当前实现审查、通用标准、统一封装设计、验证与推广计划。规范本文不指定云厂商、消息产品或全项目微服务化。
+
+后续工作建议分两条线：
+
+- **通用平台线**：模板、契约与参考 SDK/适配器/可靠投递套件，放在未来独立模板或平台仓库。
+- **当前项目线**：优先修复已核实的契约偏差与旁路，再按原 A–G 计划收敛依赖。以单独任务认领，继续遵守项目 ADR。
+
+跨区高可用、全部语言 SDK、通用可视化流程平台、service mesh、复杂 broker 拓扑均延后到实际需求证明价值。它们不是第一版完成条件。
+
+---
+
+## Planning Contract
+
+### Key Technical Decisions
+
+- KTD1. **以契约和数据 owner 划分模块，以资源/信任要求划分进程。** 实现 R2/R7；简单业务默认 L1，必须隔离 OOM、非可信插件或重计算选 L2 以上。既不强制每功能一个服务，也不禁止合理拆分。
+- KTD2. **统一治理入口采用薄 SDK 与适配器，事件采用持久总线。** 实现 R4/R5；Query/同步 Command 可直接访问提供方，经过同样的策略中间件。总线不做所有调用的中心转发服务器，避免放大共享故障点。
+- KTD3. **长任务调度归持久业务编排器。** 实现 R4/R6；平台提供任务/lease/receipt 原语，流程步骤、补偿和领域规则由用例定义。
+- KTD4. **一致性分成本地原子事务与跨域恢复协议。** 实现 R6；共库 UoW 和 outbox 是一种部署模式，跨进程使用 outbox/inbox 与 Saga。不能用一个“透明 RPC”承诺两者等价。
+- KTD5. **可靠投递默认至少一次，幂等由效果 owner 完成。** 实现 R5/R6；借鉴官方 outbox 与幂等 API 原理，具体规则以 MCS-11/13 为准。外部效果的未知结果走查询对账。
+- KTD6. **业务版本与消息序列分开。** 实现 R6；现状 A1 已显示混用风险，按 MCS-15 显式选择快照、可交换、严格增量三种语义。
+- KTD7. **第一版只做一套最小组合。** 实现 R9；建议 Go 参考 SDK + 进程内 + HTTP/JSON + PostgreSQL durable delivery。理由是足以验证类型、跨进程失败、事务和恢复，也可复用现有源码经验。该选择只作用于参考实现，规范不要求所有项目使用 Go/PG。
+- KTD8. **门禁分层并报告未覆盖项。** 实现 R8；静态边界、schema 兼容、真实数据库并发、真实传输故障和运行隔离各自提供证据，不用单个 arch-check 宣称全覆盖。
+
+选择 HTTP/JSON 是第一版的可检查性与通用接入选择，不是性能判断。gRPC/UDS 在强类型多语言或本机进程需求出现后增加；WebSocket 留给双向流；SSE 面向单向 UI 通知。每次增加适配器都跑相同业务契约和该传输特有故障测试。
+
+### Alternatives
+
+| 方案 | 收益 | 代价 | 决策 |
+|---|---|---|---|
+| 所有功能独立 HTTP 服务 | 独立进程/发布机会 | 同步链、运维和事务复杂性高 | 只用于已证明需要独立隔离的模块 |
+| 所有调用经过中央 bus 服务 | 集中路由与监控 | 单点、语义弱化、延迟和共享瓶颈 | 不采用为通用默认 |
+| 只用进程内接口 | 简洁、高效、本地事务 | 无崩溃/资源隔离 | 作为 L1 档 |
+| 显式契约 + 可替换适配器 + 持久事件 | 按风险演进、可验证 | 需要契约治理和一致性测试 | 推荐 |
+| 立即部署复杂消息集群 | 扩展能力丰富 | 缺容量证据、增加运营成本 | 达到触发条件后评估 |
+
+消息基础设施第一版可用事务型数据库队列。若多服务解耦、积压量、重放规模或独立吞吐突破数据库预算，再比较 NATS JetStream、RabbitMQ、Kafka 或云队列；选择需按顺序语义、retention、运维能力与真实 benchmark，而非流行度。即使 broker 提供去重，也仍须 MCS-13 的业务收据。
+
+### High-Level Technical Design
+
+系统组件和持久交付时序以规范 §3、§6 两张图为准。平台发布时按能力拆包，业务模块只依赖最小集合。
+
+```mermaid
+flowchart TB
+  Contract["U1 契约与设计卡"] --> SDK["U2 调用治理与适配器"]
+  Contract --> Data["U3 本地事务与幂等"]
+  SDK --> Event["U4 可靠事件消费"]
+  Data --> Event
+  Event --> Schedule["U5 持久调度与隔离"]
+  Contract --> Gates["U6 自动门禁"]
+  SDK --> Gates
+  Event --> Gates
+  Schedule --> Gates
+  Gates --> Pilot["U7 第二场景试点"]
+  Pilot --> Release["U8 发布与推广"]
+```
+
+### Output Structure
+
+下面是**未来独立参考仓库**的建议相对路径，不是本仓库将要新增的业务文件，也不是对已存在文件的声明：
+
+```text
+spec/
+  module.schema.json
+  operation.schema.json
+  errors.yaml
+  compatibility.md
+templates/
+  module-card.md
+  contract.md
+  failure-model.md
+sdk/go/
+  contract/
+  invoke/
+  transport/inprocess/
+  transport/http/
+  persistence/postgres/
+  delivery/
+  scheduler/
+conformance/
+  fixtures/
+  contract_test.go
+  concurrency_test.go
+  delivery_test.go
+  isolation_test.go
+examples/
+  reservation/
+  projection/
+  webhook/
+ci/
+  boundary-rules.yaml
+runbooks/
+  recovery.md
+  release.md
+```
+
+样例使用“资源预留 → 查询投影”展示可恢复工作流，无真实付费或外部通知副作用。外部效果另用可查询、支持幂等的本地 webhook 接收进程验证故障窗口。示例不使用本项目的文档审批等术语。
+
+### Assumptions and Deferred Decisions
+
+- 文中的“数据库和所”按“数据库和锁”理解；规范已区分唯一约束、事务、CAS、锁和 lease 的作用。
+- 新项目的业务规模、语言和运维环境尚未指定，当前不承诺吞吐、时限和工程工期。
+- 参考语言 Go 是建议起点，可在实施立项时替换；稳定 IDL、测试向量和语义仍然保留。
+- 未来平台仓库路径/owner、首个试点系统、业务 SLO 和外部副作用种类是**实施启动前必填项**。不阻塞本次方案交付，但没有这些信息不得称平台已经实施就绪或直接开工。
+
+---
+
+## Implementation Units
+
+所有 U 单元均为后续建议。每单元以独立可验收结果收口，代码与其必要回归测试同批提交，避免先搭完框架再验证。
+
+### U1. 契约与模块设计模板
+
+**目标/需求**：实现 R1/R2/R5。把规范落实为模板与可校验 manifest，先明确人读语义与机器字段的对应关系。
+
+**依赖**：实施前选择试点与 owner。
+
+**文件**：spec/module.schema.json、spec/operation.schema.json、spec/errors.yaml、spec/compatibility.md、templates/ 三份模板、conformance/contract_test.go。
+
+**做法**：模板覆盖 MCS-02/08，manifest 声明能力及 N/A 理由，不生成业务方法大全。契约给出资源预留命令、预留状态查询、预留完成事件三个相互关联样例；事件信封版本与 payload 版本分开。OpenAPI 与事件 schema 来源单一。
+
+**测试场景**：
+
+1. 缺 owner/数据边界/错误语义的 manifest 拒绝。
+2. 未知 major、字段改类型、枚举扩展按兼容策略发现差异。
+3. 新增可选字段时旧消费者仍能处理。
+4. Contract DTO 不引入业务实现/数据库类型。
+
+**验收**：新开发者仅依据设计卡能判断谁可调用、写什么、失败怎么恢复；schema 工具只能证明的部分在报告中标出。
+
+### U2. 统一调用治理与两种适配器
+
+**目标/需求**：实现 R3/R4/R5，覆盖 AE1/AE6。
+
+**依赖**：开发依赖 U1，可与 U3 并行；涉及 committed/unknown 持久结果查询的最终验收依赖 U3。
+
+**文件**：sdk/go/contract/、invoke/、transport/inprocess/、transport/http/；conformance/contract_test.go，新增 conformance/transport_test.go。
+
+**做法**：显式注入类型化客户端；统一身份、deadline、错误、trace、大小限制和取消。进程内与 HTTP 共享业务契约，HTTP 单独暴露断连/未知结果，不模拟成无失败本地函数。
+
+**测试场景**：
+
+1. 两入口相同输入产生相同业务结果及拒绝边界。
+2. 下游超时，剩余预算向下传播，不叠加完整超时。
+3. 超大请求、未知字段策略、伪造租户和错误 envelope 均按契约处理。
+4. HTTP 提交后响应中断，返回/记录 unknown 并能按 operation 查询。
+5. 客户端取消后已提交结果不被假称回滚。
+
+**验收**：替换适配器不修改业务不变量测试；业务入口不依赖整个 Runtime 或公共万能 Store。
+
+### U3. 单写者、事务和幂等收据
+
+**目标/需求**：实现 R6，覆盖 AE2。
+
+**依赖**：U1；可与 U2 并行开发，集成时统一契约。
+
+**文件**：sdk/go/persistence/postgres/；examples/reservation/；conformance/concurrency_test.go，新增 conformance/idempotency_test.go。
+
+**做法**：以唯一约束、expected_version 和同事务结果收据维护预留不变量；UoW 不穿越网络。无副作用的领域计算与提交校验分开。提供单次命令结果收据及按幂等键/operation_id 的授权查询；U5 在其上管理多步骤流程状态。
+
+**测试场景**：
+
+1. 同键并发 100 次，仅一个效果且所有成功重放得到等价结果。
+2. 同键异摘要冲突；不同键抢同版本只有一个成功。
+3. 数据变更与结果收据中途失败一起回滚。
+4. 序列化失败重跑完整事务，但不重放事务外副作用。
+5. 收据到期、迟到重试与业务唯一号保护符合契约。
+
+**验收**：真实独立数据库下验证并发与回滚；每种表/资源只有一个 owner，不以进程 mutex 验收。
+
+### U4. Outbox、消费者收据与顺序策略
+
+**目标/需求**：实现 R5/R6/R8，覆盖 AE2/AE4。
+
+**依赖**：U2/U3。
+
+**文件**：sdk/go/delivery/、examples/projection/、examples/webhook/；conformance/delivery_test.go，新增 conformance/recovery_test.go。
+
+**做法**：按 MCS-11/13/14/15 实现持久投递、按订阅者状态、短事务认领、token 校验、失败分类和受控重放。发布与消费入口均验证 schema/来源/租户；去重比较摘要。
+
+**测试场景**：
+
+1. DB commit 后 relay 崩溃，重启仍交付；事务回滚不交付。
+2. 效果提交后丢 ack，重复投递不重复效果。
+3. 首条版本 42、42→47、重复/乱序、部分订阅按所选策略工作。
+4. 同事件 ID 异 payload 被拒绝；错误生产身份/未知 schema 隔离。
+5. worker 旧 token ack 和旧版本写入均拒绝。
+6. webhook 已完成但回执丢失，经同键/查询恢复，不能再次执行。
+7. 重放超出效果收据保留窗口，系统拒绝或走明确恢复流程。
+
+**验收**：真实独立进程、数据库与传输故障证据齐全；不能以 MemoryBus 通过代替本单元。
+
+### U5. 持久调度与资源隔离
+
+**目标/需求**：实现 R4/R7，覆盖 AE3。
+
+**依赖**：U4。
+
+**文件**：sdk/go/scheduler/、sdk/go/delivery/；conformance/isolation_test.go，新增 conformance/scheduler_test.go；runbooks/recovery.md。
+
+**做法**：为两步预留/投影流程保存 operation/step 状态；有界并发、独立消费者执行槽、公平调度、停止领取与排空。高风险执行器进独立进程。业务补偿由示例模块显式提供。
+
+**测试场景**：
+
+1. 一个消费者阻塞，其他消费者达到试点声明的延迟预算。
+2. 预取任务尚未执行就租约过期，不导致未受控并发效果。
+3. 任务运行中进程终止，另一个 worker 接管；旧 worker 恢复后不能写入。
+4. 重复定时触发、重复取消、补偿失败均有稳定持久状态。
+5. 过载有背压且 accepted 只用于已可靠保存的工作。
+6. 停机排空超时后任务可恢复，进程 liveness 与业务进度分别反映。
+7. 不可信执行器无法读取宿主凭证、访问未授权业务路径或直连未授权数据服务；测试使用合成秘密与隔离数据。
+
+**验收**：记录故障域、负载和指标；L1 仅证明逻辑隔离，L2 场景必须杀实际子进程验证。
+
+### U6. 架构与契约门禁
+
+**目标/需求**：实现 R2/R8，覆盖 AE5。
+
+**依赖**：U1；最终验收依赖 U2–U5。
+
+**文件**：ci/boundary-rules.yaml、spec/compatibility.md、conformance/fixtures/；新增 conformance/boundary_test.go 和 conformance/compatibility_test.go。
+
+**做法**：依赖方向、内部类型引用、数据 owner、schema diff、消费者兼容与真实故障套件分开报告。语言 AST 负责静态边界，数据库 role 负例验证运行权限；不能仅正则扫描就宣称阻止所有动态 SQL。
+
+**测试场景**：
+
+1. 故意引入内部实现依赖和模块环，门禁失败。
+2. 越 owner 写表的普通运行身份被数据库拒绝。
+3. 扩字段、改类型、旧消费者枚举不兼容给出明确结果。
+4. 例外过期、基线增加、未执行关键测试不能生成全绿报告；经能力核对的 N/A 与适用但未执行的 SKIP 分开。
+
+**验收**：每项 enforced 有正负例与工具版本；提供静态/运行未覆盖说明。
+
+### U7. 第二业务场景与采用验证
+
+**目标/需求**：实现 R1/R9。
+
+**依赖**：U6。
+
+**文件**：在未来试点仓库新增模块设计卡、契约和 conformance 映射；参考仓库新增 examples/second-domain/ 与 conformance/adoption_test.go。确切业务路径待试点确定后补充，当前不假定存在。
+
+**做法**：选择与资源预留不同的真实场景，记录 SDK 引入的代码量、学习成本、业务接口数量、部署需求与故障定位耗时。优先复用原语，不复制第一个业务模型。
+
+**测试场景**：
+
+1. 第二场景无需 import 第一个示例的实现。
+2. 同样的重复、取消、失败恢复测试向量能够复用。
+3. 必须增加的扩展点有两个实际调用场景，避免预先制造万能框架。
+
+**验收**：证明封装具有跨场景复用价值；否则收缩平台表面并改模板，不能直接全项目推广。
+
+### U8. 版本发布与渐进推广
+
+**目标/需求**：实现 R8/R9。
+
+**依赖**：U7。
+
+**文件**：runbooks/release.md、runbooks/recovery.md、spec/compatibility.md；新增 conformance/upgrade_test.go。
+
+**做法**：按版本发布契约、SDK、适配器和测试向量，声明支持矩阵。迁移一条纵向能力后再推进下一条；采用 expand/contract，不双写两套权威状态。
+
+**测试场景**：
+
+1. 新旧 SDK/服务混跑可处理兼容请求与积压旧事件。
+2. 业务提交后回退程序版本，状态与事件仍可读取，不删收据制造重放。
+3. 从备份恢复后，外部不可逆副作用通过对账处理。
+4. 操作人员可按手册处理 DLQ、unknown operation 和失效租约。
+
+**验收**：版本支持期、升级/回退与恢复责任明确，完成的试点才进入推广。
+
+---
+
+## Verification Contract
+
+实施验证分五层：纯领域/公开用例、进程内与 HTTP 契约、独立数据库并发、真实进程交付故障、试点用户端到端。每层独立报告，SKIP/未运行不得计 PASS。
+
+| 单元 | 核心证据 | 失败时处理 |
+|---|---|---|
+| U1/U2 | schema/兼容与同一动作不同入口结果 | 修契约或适配器，不改业务含义掩盖差异 |
+| U3 | 并发竞争、事务与收据回滚 | 停止引入更多消费者 |
+| U4 | 崩溃/重投/稀疏版本/错误来源 | 保留 delivery 与诊断，不清库重来 |
+| U5 | 慢任务、过载、旧 worker 复活、排空 | 降低领取/并发，调整隔离，重测受影响预算 |
+| U6 | 人为违规负例与测试缺项拒绝 | 不标 enforced |
+| U7/U8 | 第二场景、混跑、恢复与操作手册 | 不扩大推广范围 |
+
+测试记录必须包含源版本、制品、运行拓扑、配置摘要、预期场景、实际执行、失败/重试和证据位置。容量目标由试点 SLO 确定后固化，不能凭方案给出未经测量的“毫秒级”“零影响”。
+
+---
+
+## Current Project Adoption
+
+当前项目的逐单元设计、迁移和验收已细化为[系统整改与重构方案](./2026-09-22-agent-system-modular-refactor-plan.md)（待审核）。下方 CP1–CP6 保留为原始映射索引；通用平台 U1–U8 仍是独立平台线，不作为本项目重复建设前置。
+
+这部分是当前项目的映射附录，不属于跨项目通用标准。保持既有模块化单体 ADR，后续如拆进程另提 ADR 和授权。
+
+| 顺序 | 目标与现有路径 | 建议新增/扩展验证 | 关联 |
+|---|---|---|---|
+| CP1 | events/dispatcher.go 对齐首事件 bootstrap；校验所有 producer 的版本语义 | dispatcher_pg_test.go：首条高版本、跳版本、部分订阅；pg_test.go 不再固化矛盾规则 | 审查 A1、MCS-15 |
+| CP2 | chat/action_executor.go 汇入 app/docflow.Commands；检查所有批准/提交入口 | chat/action_executor_test.go（新增或扩展）、server HTTP/真实对话批准：状态+事件+下游一致 | A2、MCS-04 |
+| CP3 | events 的发布/消费 schema、producer 与 digest 冲突校验 | events/envelope_test.go、pg_test.go、dispatcher_pg_test.go：非法来源/字段/同ID异摘要 | A3/A5 |
+| CP4 | events worker 分消费者预算，按容量 claim，补监控 | events/worker_isolation_test.go（计划新增）、真实 PG/多进程慢消费者与 lease 测试 | A4/A5 |
+| CP5 | 原 A/B/C/D/G 收敛 server 装配、契约类型、workflow 方向与数据/文件 owner | 对应公开用例特征测试与逐项删除例外的静态证据 | 原 A–G 计划 |
+| CP6 | 原 F 收敛前端 client/状态 owner，再按需做 E 文件拆分 | web API 错误/取消测试、受影响真实页面验收 | B4/B5 |
+
+CP1–CP4 先验证事实和修复原契约，不以本方案自动修改生效 ADR；各项都需实施任务。CP5 保留原批次 owner 与 mutex，避免同名领域同时两套重构。文件长度用于定位，不以拆文件作为解耦验收。
+
+项目现有业务与 PG 事务边界尚可受益于 L1 收敛，不建议先做全模块 HTTP 化。优先独立执行器/解析器等高资源或高风险边界时，另补权限、artifact owner、取消和恢复契约。
+
+---
+
+## Risks and Operating Model
+
+| 风险 | 约束/缓解 |
+|---|---|
+| 总线成为万能业务引擎 | 按 MCS-07 分开路由、投递、编排和领域逻辑 |
+| SDK 大版本导致全部模块同时升级 | 最小依赖包、兼容矩阵、协议和实现分版 |
+| 共享 DB 成为隐式通信 | owner、运行权限与投影，跨域查询例外有期限 |
+| 锁 TTL 被误认为排他完整证明 | MCS-14 要求资源端拒绝旧写，外部 API 另用幂等/对账 |
+| 为统一协议消除所有业务差异 | 统一技术语义，业务输入输出分模块定义 |
+| 推广早于真实恢复证明 | U7 第二场景后才进入 U8 |
+| 通用规范覆盖本项目现行规则 | 规范保持 proposed，采纳必须有适用范围和生效版本 |
+| 过度工程影响交付速度 | 第一版限制适配器数量，每个扩展点有实际场景 |
+
+职责建议：模块 owner 负责不变量与契约；平台 owner 负责 SDK、投递和兼容工具；运维负责容量、故障演练与恢复；集成/评审者核对端到端跨模块行为。小团队可兼任，责任不能空缺。
+
+不提供缺乏人员与容量输入的固定工期。排期按 U1 → U2/U3 → U4 → U5/U6 → U7 → U8 的依赖推进，各阶段先验收再扩大范围。
+
+---
+
+## Definition of Done
+
+**本次研究交付**：现状报告明确源码证据与未验证范围；通用规范脱离本项目仍完整可读；本方案列明统一封装边界、技术选择、工作单元、故障测试与采用顺序；文档链接、状态与审阅记录可核对。
+
+**后续平台交付**：U1–U8 对应证据齐全、第二场景验证通过、运维恢复和兼容矩阵可执行。模块故障隔离只按已实测档位声明。
+
+**当前项目改造交付**：按获授权 CP 任务范围分别验收，不能用本次文档交付代替代码、PG、真实产品 Runner 或浏览器证明。
+
+## Sources
+
+机制依据和官方链接已放在通用规范相应条款：gRPC deadline/retry、OpenAPI/AsyncAPI、CloudEvents、PostgreSQL 行锁、AWS outbox/幂等 API。它们支持机制选择，不直接证明本项目运行表现。项目落点与证据来自同批现状报告。
+
+可能相关的现有文档包括模块开发标准、module-boundaries.yaml、模块化单体 ADR、checkpoint ADR、09-20 A–G 计划及验证契约。只有后续实施真正改变它们的声明时才更新，不在此次方案中预先把能力记完成。

.doc/remediation/2026-09-23-coordination-db-daemon-phased-plan.md

@@ -0,0 +1,172 @@
+---
+title: "协调库与 daemon：分阶段设计与实施方案"
+status: planned
+created: 2026-09-23
+updated: 2026-09-23
+owner: Cursor
+task_id: coordination-db-daemon-2026-09-23
+task_type: research
+task_tier: multi_stage
+policy_revision: "agent-governance-2026-09-21-r1 @ 63e66c6fb35d6b4dd9f3ed92e15acc9933aeb344"
+branch: feature/coordination-db-daemon-2026-09-23
+worktree: .worktrees/coordination-db-daemon-2026-09-23
+base_dev_sha: "63e66c6fb35d6b4dd9f3ed92e15acc9933aeb344"
+write_scope: [".doc"]
+allowed_environments: []
+mutex: coordination-db-daemon
+review_state: pending
+integration_state: pending
+deployment: not_required
+cleanup: pending
+cleanup_owner: "独立维护者"
+remote_sync: not_requested
+---
+
+# 协调库与 daemon：分阶段设计与实施方案
+
+> 本文件是**方案文档（planned）**，不含 daemon/PostgreSQL 实施。配套 [研究依据](../ops/research/2026-09-23-coordination-db-daemon-research.md)。上位约束：[锁协调方案](./2026-09-21-agent-lock-coordination-plan.md)、[操作规范](../ops/2026-09-21-agent-worktree-workflow.md)、[平台深化方案](./2026-09-23-platform-deepening-reliability-ha-concurrency-plan.md) §0。
+
+## 0. 用户目标与授权
+
+- 用户目标：统一认领、状态与执行入口；文档逐步变为状态输出；为多主机协作预留结构。
+- 交付形态（已确认）：**研究 + 方案**；不实施数据库或 daemon。
+- 边界（已确认）：**分阶段**——L1 单宿主机内（daemon + 现有 SQLite）；跨机 PostgreSQL 仅登记为 planned 的 L2，需二次授权与 ADR。
+- 并行授权：修掉 `agentctl queue` 子解析器重复注册（已合入本地 `63e66c6f`）。
+
+## 1. 现状基线（纠正摘要偏差）
+
+| 摘要原说法 | 实测 |
+|---|---|
+| SQLite 管理「部分」协调状态 | `.locks/state.sqlite` 已是权威库（11 表；采样 tasks≈105 / runs≈653 / events≈1406） |
+| 非容器用 systemd | 本机 Darwin；仓库内 systemd/launchd/协调 compose **0 个** |
+| 任务注册无长期排他认领 | 属实：缺显式 claim；scope/lease 已有 |
+| 文档 `3f14d7fa` 已合入 | **不存在**；本轮重新落地 |
+
+已成立能力（不推倒）：`scripts/agentctl.py` 的 scope、flock 租约、三值进程存活、docs CAS+收据、候选准入、`--ff-only`、hooks；`.git/agent-control/dev-integration.lock` 与 `.locks/os/dev-integration.lock` 同 inode。
+
+关键缺口：长期 claim、常驻协调入口、`configs/agent-governance.yaml`、CURRENT/MATRIX 稳定 record id、queue/jobs 运维闭环（parser 已修，行仍为 0）、`agentctl_automation.py` 分叉。
+
+## 2. 目标架构
+
+```mermaid
+flowchart TB
+  subgraph L1 [L1 单宿主机 本方案设计线]
+    AG1[Agent 与工具调用] --> AC[agentctl CLI 统一入口]
+    AC --> DB[(.locks/state.sqlite 权威库)]
+    AC --> OS[.locks/os flock 稳定锁]
+    CO[常驻协调入口 launchd 本机] --> DB
+    CO --> PUB[docs apply 收据化发布]
+    AC --> GI[git:dev 候选验证与 ff-only]
+  end
+  subgraph L2 [L2 跨机 仅 planned 需 ADR]
+    HA[主机 A 执行代理] --> CD[中央协调 daemon]
+    HB[主机 B 执行代理] --> CD
+    CD --> PG[(独立 PostgreSQL)]
+    CD --> EXH[指定主机执行 Git 集成与部署]
+  end
+  L1 -.->|L1 验收后另立 ADR| L2
+```
+
+### 三种关系（协议核心）
+
+| 机制 | 作用 | 今日状态 |
+|---|---|---|
+| scope | 智能体允许修改哪些路径/能力 | `tasks.scopes` + `check_resources`，已 enforced |
+| claim | 某项工作当前由谁长期负责 | **缺失**；CURRENT 手工行不是原子认领 |
+| lease | 谁正在操作某资源 | `Lease` + flock + 存活核验，已 enforced |
+
+认领在短事务中完成：检查权限、冲突、冻结、公平排队、登记归属、写审计——全成或全拒。冲突返回持有者、队列票据与 `retry_after`。
+
+**执行安全不能只靠数据库锁。** TTL/心跳过期只进入 suspect/quarantine，不立即把资源交给下一个智能体；须核验旧进程与外部操作结果后再交接（见 U7）。
+
+## 3. L1 七个实施单元
+
+每单元另建 short-term + mutex + 验收 + 回退；合入 local_dev 串行占 `git:dev`。
+
+### U1 缺陷收敛与实现归一
+
+| 项 | 状态 |
+|---|---|
+| queue 子解析器重复注册 | **已修复并合入** `63e66c6fb35d6b4dd9f3ed92e15acc9933aeb344`（删后注册块；保留 `--head` / cancel `--task` / schedule `--drain`；回归 3 例；unittest 103/2 skipped PASS） |
+| `scripts/agentctl_automation.py` 零导入、schema 分叉 | planned：收敛到 W4 或按记录删除 |
+| `.locks/state.db` 0 字节孤儿 | planned：确认无引用后清理（运行态，不入 Git） |
+
+### U2 治理策略外部化
+
+新建 tracked `configs/agent-governance.yaml`（今日不存在），收敛 `SHARED_DOCS`、`PROJECTABLE_DOCS`、`JOB_KINDS`、protocol/policy 版本；fail-closed 加载；旧客户端低于最小协议版本拒写。
+
+### U3 显式长期认领 claim
+
+在 SQLite 增加 claim 表/字段（或等价资源键），与 scope/lease 分离。`BEGIN IMMEDIATE` 短事务内：权限、父子路径重叠、冻结、公平排队、审计。不同资源可并行。不把 Markdown `idle` 当作原子锁。
+
+### U4 常驻协调入口（本机）
+
+- **macOS**：launchd plist（本机默认）。
+- **Linux**：systemd unit。
+- 单实例：`.locks/os/manager.lock`（2026-09-21 方案已规划、今日不存在）。
+- 职责：驱动 `queue schedule`、文档投影发布、心跳过期扫描；**不新增权限**。
+- 不可用时：阻止受保护写入，不静默放行。
+
+### U5 CURRENT 状态输出化
+
+- `## 并行认领` / 集成槽位：稳定 record id + `docs project` 生成；人工「焦点 / 受控约束」保留。
+- 同批修正：`CURRENT.md:5` 与 `:15` 自相矛盾；操作规范 `:3`「Linux 本机」过时描述。
+- 发布仍走 `docs apply` CAS + 收据 + hook。
+
+### U6 FEATURE-MATRIX 分阶段迁移
+
+27 模块行加稳定 record id 与结构化状态字段；保留声明范围、审核与证据。`done` 仍需 `docs:approve` + 已提交证据路径；不因任务结束或锁释放自动升 done。`production_ready` 仍只由发布门禁判定。任务完成 ≠ 能力完成 ≠ 发布就绪。
+
+### U7 执行代理与安全交接
+
+固化：suspect → quarantine → 核验（supervisor/子进程组消失、物理锁可得、外部结果核对）→ 交接。复用并加强 `recover`；补 fencing generation 与 env/git 收据。Git 集成与共享环境部署集中主目录执行入口（`queue_schedule` 已限主 dev）；保留 flock、候选准入、`--ff-only`。数据库管记录与授权，执行入口防实际双写。
+
+## 4. L2 登记（planned，不开工）
+
+前置条件：用户二次授权 + ADR 覆盖锁方案 §3.2 与平台深化 §0。
+
+登记内容：中央独立 PostgreSQL（独立配置/数据目录/备份，不依赖产品容器）；中央协调 daemon；各主机执行代理；指定执行主机做 Git 集成与部署；systemd 开机启动与异常重启；单中央节点故障时暂停受保护写入。
+
+**待执行验收（不得冒充已测）**：真实双主机并发、断网、旧进程存活、重复 `request_id`、备份恢复。systemd 能恢复进程，不能替代主机容灾与数据库备份。
+
+## 5. 文档与状态模型
+
+| 内容 | 归属 |
+|---|---|
+| 任务归属、进度、队列、执行状态 | 数据库（权威） |
+| CURRENT 运行表格 | 逐步自动生成；人工焦点/约束保留 |
+| FEATURE-MATRIX | 分阶段结构化；证据与审核保留 |
+| 规范、方案、验收报告正文 | 继续 Git 管理 |
+
+## 6. 全局验收门
+
+1. 每单元：受影响 `unittest` + 负例（冲突认领、旧 generation、daemon 停写）。
+2. U3/U5/U6：双任务并行写不丢行、同行 CAS 冲突可见。
+3. U4/U7：杀 supervisor 留子进程不得误抢；断心跳后须核验再交接。
+4. L2：未授权不得实施；不得把 planned 写成 enforced。
+5. 红线：不把 L1 宣称为 OS 沙箱；不依赖产品容器启动协调；不接触业务数据库。
+
+## 7. 风险与回退
+
+| 风险 | 控制 |
+|---|---|
+| 两套锁各自放行 | 延续 2026-09-21 §10 硬链接/双锁兼容；禁止静默第二锁根 |
+| daemon 扩大权限 | 只调度已授权操作；能力仍来自 task register |
+| CURRENT 自动覆盖人工焦点 | 仅受控区块机器写；整文需 docs:admin |
+| L2 提前开工 | 无 ADR 拒合入跨机代码 |
+| 文档与运行态漂移 | CURRENT 标明快照时间；以 doctor/status 核验 |
+
+每单元独立 revert；迁移 additive；部署清单与代码分提交。
+
+## 8. 与既有文档关系
+
+- 本方案 = [2026-09-21 锁方案](./2026-09-21-agent-lock-coordination-plan.md) 的**演进版**：L1 补 claim/常驻入口/文档状态化；不推翻 SQLite 权威与 advisory 边界。
+- 不替代 [平台深化方案](./2026-09-23-platform-deepening-reliability-ha-concurrency-plan.md)（产品可靠性/HA）；协调跨机另立 ADR。
+- gap-matrix / FEATURE-MATRIX 状态不因本方案自动变更。
+
+## 9. 开工准入（第一批实施前）
+
+1. 每批 short-term + CURRENT 认领 + mutex。
+2. 从当时 dev tip 建 worktree；重读 policy_revision。
+3. L2 / 共享环境须单独授权。
+4. 本文件保持 planned；首批实施时回填映射，不代填验收。

.doc/remediation/2026-09-23-coordination-db-daemon-plan.md

@@ -1,172 +1,396 @@
 ---
-title: "协调库与 daemon：分阶段设计与实施方案"
-status: planned
+title: "多主机 Agent 认领、执行与文档状态数据库化方案"
 created: 2026-09-23
-updated: 2026-09-23
-owner: Cursor
-task_id: coordination-db-daemon-2026-09-23
-task_type: research
-task_tier: multi_stage
-policy_revision: "agent-governance-2026-09-21-r1 @ 63e66c6fb35d6b4dd9f3ed92e15acc9933aeb344"
-branch: feature/coordination-db-daemon-2026-09-23
-worktree: .worktrees/coordination-db-daemon-2026-09-23
-base_dev_sha: "63e66c6fb35d6b4dd9f3ed92e15acc9933aeb344"
-write_scope: [".doc"]
-allowed_environments: []
-mutex: coordination-db-daemon
-review_state: pending
-integration_state: pending
-deployment: not_required
-cleanup: pending
-cleanup_owner: "独立维护者"
-remote_sync: not_requested
+type: feat
+artifact_contract: ce-unified-plan/v1
+product_contract_source: ce-plan-bootstrap
+execution: code
+task_id: coordination-db-daemon-plan-2026-09-23
+source_revision: a0fd52a6276b1b531df9ba53e329a645cf8527c9
+deepened: 2026-09-23
 ---
 
-# 协调库与 daemon：分阶段设计与实施方案
+# Multi-host Agent Coordination Plan
 
-> 本文件是**方案文档（planned）**，不含 daemon/PostgreSQL 实施。配套 [研究依据](../ops/research/2026-09-23-coordination-db-daemon-research.md)。上位约束：[锁协调方案](./2026-09-21-agent-lock-coordination-plan.md)、[操作规范](../ops/2026-09-21-agent-worktree-workflow.md)、[平台深化方案](./2026-09-23-platform-deepening-reliability-ha-concurrency-plan.md) §0。
+## Goal Capsule
 
-## 0. 用户目标与授权
+**目标**：不同主机上的智能体看到一致的任务归属，冲突能在执行前被发现，失联或重启后不会让两个写者同时操作共享资源；用户能追溯每次认领、执行与状态变更。
 
-- 用户目标：统一认领、状态与执行入口；文档逐步变为状态输出；为多主机协作预留结构。
-- 交付形态（已确认）：**研究 + 方案**；不实施数据库或 daemon。
-- 边界（已确认）：**分阶段**——L1 单宿主机内（daemon + 现有 SQLite）；跨机 PostgreSQL 仅登记为 planned 的 L2，需二次授权与 ADR。
-- 并行授权：修掉 `agentctl queue` 子解析器重复注册（已合入本地 `63e66c6f`）。
+**推荐手段**：独立原生 PostgreSQL + 中央协调 daemon + 每台主机执行代理；保留现有本机 flock、worktree、精确候选集成和证据门禁。详见 KTD1–KTD7。
 
-## 1. 现状基线（纠正摘要偏差）
+**授权**：本次只交付研究与方案。后续编码、安装服务、接入其他主机、切换状态权威、部署与远端写入需相应实施授权；本方案不自动产生这些权限。执行时以 AGENTS / PROJECT 和当前生效 runbook 为准。
 
-| 摘要原说法 | 实测 |
+**交付组织**：U1–U6 构成首期可用交付，U7 完成 FEATURE-MATRIX 结构化治理。只部署协调服务，无需重建产品容器。不恢复已移出的个人中控台，不接入产品管理后台或产品数据库。
+
+**停止条件**：无法确认旧写者已退出、身份/epoch 不一致、旧新权威同时可写、外部副作用结果未知时，冻结相应资源并保留现场，不自动抢占或回滚。
+
+---
+
+## Product Contract
+
+### Summary
+
+思路合理，但收益主要来自统一权威数据与操作协议，不能归结为换一个“并发更强的数据库”。用户已明确需要多主机共同协调，因此推荐 PostgreSQL 原生服务；中央 SQLite + API 仍是可行的低运维备选，并非一跨主机就必须放弃 SQLite。禁止的是多台主机通过网络文件系统直接共享 WAL 数据文件。
+
+日常 Agent 使用结构化命令申请任务、认领范围、执行、更新状态；不再手工改表格认领。任务状态入库，CURRENT 的运行表格变成生成快照。FEATURE-MATRIX 分阶段迁移，能力声明和证据审核保留独立门禁。
+
+### Problem Frame
+
+现有系统已是“SQLite + flock + Git/Markdown”，不是只有 Markdown：
+
+| 已核对事实 | 证据与影响 |
 |---|---|
-| SQLite 管理「部分」协调状态 | `.locks/state.sqlite` 已是权威库（11 表；采样 tasks≈105 / runs≈653 / events≈1406） |
-| 非容器用 systemd | 本机 Darwin；仓库内 systemd/launchd/协调 compose **0 个** |
-| 任务注册无长期排他认领 | 属实：缺显式 claim；scope/lease 已有 |
-| 文档 `3f14d7fa` 已合入 | **不存在**；本轮重新落地 |
+| 主仓唯一 SQLite，WAL / FULL / BEGIN IMMEDIATE / 5 秒 busy timeout | `scripts/agentctl.py` 的 Repo.db / initialize；已有数据库写事务保护 |
+| 注册保存 scope；没有独立长期 claim 表 | task register 只防同 worktree 重复 active；许可范围不能表达全任务排他归属 |
+| 文档 snapshot/apply 读写当前 worktree | 两个旧副本可分别通过本地行 CAS；全局 docs 锁不能使副本变成同一全局记录 |
+| CURRENT 与 DB 任务状态独立更新 | tasks.state 为 active/done/cancelled；文档任务状态有五种，存在状态映射与可见性延迟 |
+| 所有 docs apply 共用 docs:publish 锁 | 不同行修改也串行执行文件解析/写回；可以缩短元数据临界区 |
+| 机器状态仍有恢复待核验操作 | 本次只读 status 发现 1 条 env:dev 的 recovery_required，supervisor_alive=false；不能据此断定子进程消失或环境安全 |
+| 现行能力声明仅覆盖本机 L1 | FEATURE-MATRIX 的“Agent worktree 治理自动化”为 partial，明确跨机隔离尚未完成 |
 
-已成立能力（不推倒）：`scripts/agentctl.py` 的 scope、flock 租约、三值进程存活、docs CAS+收据、候选准入、`--ff-only`、hooks；`.git/agent-control/dev-integration.lock` 与 `.locks/os/dev-integration.lock` 同 inode。
+本次确认了实现边界和状态分散的机制，未复现用户某一次具体丢写事故，也没有数据库吞吐、QPS 或延迟证据。问题记录与只读证据见[研究任务](../ops/short-term/2026-09-23-coordination-db-daemon-research.md)。不能把 SQLite 单写者当作已证实根因。
 
-关键缺口：长期 claim、常驻协调入口、`configs/agent-governance.yaml`、CURRENT/MATRIX 稳定 record id、queue/jobs 运维闭环（parser 已修，行仍为 0）、`agentctl_automation.py` 分叉。
+### Requirements
 
-## 2. 目标架构
+| ID | 必须实现的结果 |
+|---|---|
+| R1 | 多台主机、多个 checkout/worktree 对同一逻辑仓库使用同一任务和资源权威；本地路径不能充当全局仓库 ID |
+| R2 | 区分授权 scope、长期 claim、短期 execution lease；重叠排他认领原子拒绝，非冲突工作可并行 |
+| R3 | 任务、能力记录采用版本 CAS；所有变更具有 request_id、操作者、授权来源与审计，不接受最后写入覆盖 |
+| R4 | 多资源全有或全无授予；等待有上限、可取消、可查询 holder/原因，读快照不能作为执行授权 |
+| R5 | 断网、代理/daemon 崩溃、主机重启和响应丢失后仍保持执行排他；未知外部结果不自动重放 |
+| R6 | CURRENT 状态来自数据库投影；Git 版本可追溯，投影失败不撤销已提交的状态；保留人工正文 |
+| R7 | FEATURE-MATRIX 完成声明保持范围、审核者、提交、制品/环境与证据绑定；task done 不推导 feature done 或 production_ready |
+| R8 | 各主机经认证 API 使用已授予能力；CLI 与 hooks/执行代理使用同一协议，不允许客户端自授 capability |
+| R9 | 协调数据库、进程、配置、备份独立于产品容器和业务数据库；可以原生 daemon 开机启动、升级与恢复 |
+| R10 | 从当前 SQLite/Markdown 可审计迁移，旧客户端被写入门禁隔离；回退不丢新事件、不恢复旧写权限 |
+
+### Scope and Assumptions
+
+多主机是用户明确要求，替代此前单主机假设。初始容量设计按 2–10 台 Linux 主机、20–100 个并行 Agent、同一管理域估算；这不是实测规模。首期接受中央节点故障时暂停受保护写，不承诺高可用；单机故障自动接管、跨地域低延迟和恶意 root 对抗留作独立项目。
+
+源码编辑继续在独立本地 worktree；普通文件不能靠远程 token 获得内核强制保护。首期提供对合作 Agent 的一致协调，共享 Git 引用/部署动作通过指定执行入口与凭证隔离加强防护；不能宣称任意同 UID shell 都不可绕过。
+
+不把 Markdown 全文、业务内容或原始日志搬进数据库。方案、规范理由、验收报告和证据主体继续受 Git 管理；数据库保存结构化事实及不可变引用。Web 看板和 MCP 是后续 API 客户端，不是首期依赖。
+
+---
+
+## Planning Contract
+
+### Database Report Review
+
+以下为官方资料核查后的选型判断，均不等于本仓库性能测试：
+
+| 报告观点 | 校正与对本任务的意义 |
+|---|---|
+| rqlite 最推荐、适合高并发 | Raft 主要解决复制与可用性；写仍经 leader，增加网络/共识成本。HTTP 批量事务并不等同 PG 可交互的读取-判断-写入事务；不能仅为解决 Markdown 冲突就引入三节点 |
+| dqlite 是嵌入式多节点 SQLite | 基本方向正确，需承担复制、协议及原生依赖；不能从 LXD 使用推导本任务写吞吐或集成成本 |
+| libSQL 是 SQLite 官方分支 | 是独立项目的 fork，不是 SQLite 官方分支；embedded replica 不等于多写主协调，客户端授权读取不能用可能滞后的副本 |
+| LiteFS 透明复制可解决锁 | 复制数据库文件不等于跨主机执行锁；单主写、FUSE 与部署约束不能替代任务协议 |
+| PocketBase 相当于轻量高并发数据库 | 是 SQLite 驱动的后端应用框架；自带用户/订阅不等于已具备本项目 claim、fencing、Git 发布模型 |
+| bbolt / Badger / Pebble 都有更好的多写者并发 | bbolt 同时只允许一个读写事务；Badger 有并发 ACID 事务，Pebble 提供 batch/snapshot 而非完整事务层，不能笼统排名或当成跨主机协议 |
+| DuckDB 事务写入也是单写者 | 过度简化：单进程可支持多线程写与乐观冲突控制；其分析型定位及跨进程限制使它不适合此协调服务 |
+| WAL 读几乎无限并发，NORMAL 就够 | 读仍受 I/O、长事务和 checkpoint 影响；NORMAL 与 FULL 的断电持久性不同。权威认领记录不以降低持久性换吞吐 |
+
+若启用 SQLite 备选，验收实际程序链接的 SQLite 版本与官方 WAL 已知问题/修复，而非只查 sqlite CLI；本机 Python 当前内嵌 3.53.4，未发现依据可将本问题归因于旧版本 WAL 缺陷。
+
+来源：[rqlite FAQ](https://rqlite.io/docs/faq/)、[rqlite API](https://rqlite.io/docs/api/api/)、[SQLite WAL](https://sqlite.org/wal.html)、[SQLite PRAGMA synchronous](https://sqlite.org/pragma.html#pragma_synchronous)、[dqlite](https://github.com/canonical/dqlite)、[libSQL](https://github.com/tursodatabase/libsql)、[LiteFS](https://fly.io/docs/litefs/)、[PocketBase](https://pocketbase.io/docs/)、[bbolt](https://github.com/etcd-io/bbolt)、[Badger](https://github.com/dgraph-io/badger)、[Pebble](https://github.com/cockroachdb/pebble)、[DuckDB concurrency](https://duckdb.org/docs/stable/connect/concurrency)。
+
+### Key Technical Decisions
+
+- KTD1. **主方案使用专用 PostgreSQL，而不是产品 PG。** 多主机经 API 访问，关系约束、短事务、行锁与审计查询适合此模型；这是维护与正确性选择，不是已测出 SQLite 不够快。原生 PG 有安装、升级、备份成本；采用当前受支持稳定大版本及补丁，实施时锁定版本。
+- KTD2. **中央 SQLite + API 是低运维备选，首期不同时实现两种后端。** 可保留现行 WAL/FULL 并让单 daemon 串行短写，远端不直接开库。若部署资源极受限可重新采用；并发、安全与投影协议仍然必须实现。rqlite 只在明确要求独立节点多数派容灾且接受其事务模型时再评估；三进程同宿主不构成宿主级容灾。
+- KTD3. **单权威写服务、稳定 API、独立工具模块。** 建议新增 `tools/agentcoord/` 独立 Go module，产出一个二进制的 server / executor / CLI 子命令；不引用产品 internal 包。现有 Python CLI/hooks 做薄适配，逐步迁移；保留可验证行为，避免同时重写所有 Git 门禁。
+- KTD4. **长期锁是数据库记录，数据库锁只维持毫秒级事务。** 不把 PG connection / session advisory lock 持续占用到 Agent 工作结束；连接中断不能证明旧工作结束。可用事务级锁或固定命名空间行锁保护认领事务。见[PG 锁说明](https://www.postgresql.org/docs/current/explicit-locking.html)。首期不增加 PgBouncer；其 transaction pooling 不支持 session-level advisory lock，未来引入须按[官方兼容矩阵](https://www.pgbouncer.org/features.html)复核。
+- KTD5. **安全接管依赖目标侧执行控制。** 单调 token 只是协议字段，目标必须验证并串行执行；对不支持 fencing 的 Git/Docker/普通文件操作，失联后一律隔离等待核验，禁止 TTL 自动接管。
+- KTD6. **先迁移高频状态，再迁移能力行。** U1–U6 令任务/CURRENT 的机器状态入库；U7 经明确切换将矩阵结构化行权威迁入 DB。每个阶段只有一处权威，禁止 Markdown↔DB 双向自动同步。
+- KTD7. **数据库变更与外部执行之间使用持久操作状态和 outbox。** 不声称 DB commit 与 Git、文件 rename、Docker 构成一个事务；受控副作用最多一次接受启动、重复查询，无法判定完成则进入恢复。
+
+### High-Level Technical Design
+
+以下图与协议描述是设计约束，命名可在实现中细化。
 
 ```mermaid
 flowchart TB
-  subgraph L1 [L1 单宿主机 本方案设计线]
-    AG1[Agent 与工具调用] --> AC[agentctl CLI 统一入口]
-    AC --> DB[(.locks/state.sqlite 权威库)]
-    AC --> OS[.locks/os flock 稳定锁]
-    CO[常驻协调入口 launchd 本机] --> DB
-    CO --> PUB[docs apply 收据化发布]
-    AC --> GI[git:dev 候选验证与 ff-only]
-  end
-  subgraph L2 [L2 跨机 仅 planned 需 ADR]
-    HA[主机 A 执行代理] --> CD[中央协调 daemon]
-    HB[主机 B 执行代理] --> CD
-    CD --> PG[(独立 PostgreSQL)]
-    CD --> EXH[指定主机执行 Git 集成与部署]
-  end
-  L1 -.->|L1 验收后另立 ADR| L2
+  A[主机 A: Agent / CLI] --> EA[本机 executor + supervisor + flock]
+  B[主机 B: Agent / CLI] --> EB[本机 executor + supervisor + flock]
+  EA <-->|mTLS: claim / lease / events| C[中央 agentcoord daemon]
+  EB <-->|mTLS: claim / lease / events| C
+  C --> P[(专用 PostgreSQL)]
+  C --> O[持久 outbox / 排队 / 恢复]
+  O --> E[指定集成与环境执行主机]
+  E --> G[Git candidate / env-service 受控入口]
+  O --> W[专用 publisher worktree]
+  W --> D[CURRENT / FEATURE-MATRIX Git 快照]
 ```
 
-### 三种关系（协议核心）
+中央 daemon 不向任意主机暴露无范围的 shell；executor 主动连中央服务领取绑定 host 的操作，本机 CLI 可经 Unix socket 请求 executor。普通源码工作在登记任务 cwd；共享操作绑定批准的目标主机和主运行路径。
 
-| 机制 | 作用 | 今日状态 |
+**身份模型**：人工登记 `repo_id`（逻辑项目）及 `checkout_id / host_id / worktree_id`；不要把带凭证的 Git URL 当身份，也不按目录字符串合并两个仓库。中央登记唯一 integration target（当前逻辑 dev 权威）及 source ref；其他主机本地 dev SHA 是观测值，不能假装等于权威。新任务从权威基线的精确 SHA 建立，跨机对象通过已授权 Git 读取或校验后的 bundle 传输；制品具有 hash、大小限制和来源。提交 bundle 不等于允许 push origin。数据库 token 不能代替 Git 对象存在性、父链与 expected ref CAS。
+
+**数据模型**：
+
+| 记录 | 主要字段与不变量 |
+|---|---|
+| repositories / hosts / checkouts | 稳定 UUID、canonical target、协议版本、host boot identity、状态；同 repo 的不同主机路径单独保存 |
+| principals / grants | 身份、允许 repo/task/resource/action、授权证据/有效期；由已授权管理者登记，不信任客户端 cap 自报 |
+| tasks | 五态 task_status、owner、base SHA、policy revision、record_version；review/integration/deployment/cleanup/remote_sync 独立字段 |
+| registrations / authorized_scopes | registration_status、host/worktree/branch、可写范围；登记有效不推导 task in_progress |
+| claims | task、逻辑资源、claim revision、holder、active/releasing/quarantined/released；只在显式交接/关闭后释放 |
+| operations / execution_leases | request_id 唯一、payload hash、task、host、状态、token、expires_at、进程身份、结果引用；执行代次与任务状态分离 |
+| resources / namespace_guards | 逻辑父子路径、环境/分支/index/worktree 类型；创建和重叠检查有统一事务互斥 |
+| proposals / feature_records | U5 引入待审 proposals 及 canonical Git 基线；U7 引入权威 feature_records，含稳定 feature_id、scope/evidence ref、maturity、row_version；proposal 不等于生效记录 |
+| events / outbox / projections | 持久事件、请求/记录版本、投影 generation、source refs、输出 hash、Git commit 和发布状态 |
+
+需有 PK/FK/check 约束、request_id/主体域唯一约束、active exact-resource 辅助唯一约束。父子目录重叠不能靠 exact-key UNIQUE 保证；不得将不存在的记录 `SELECT FOR UPDATE` 当成已锁定未来插入。
+
+**资源与认领协议**：
+
+- 授权 scope 是许可上界；claim 是跨主机开发归属；lease 是一次真实操作占用。长期 claim 默认按模块 mutex 或逻辑源码前缀，普通文档用精确文件，不认领整份 CURRENT/MATRIX。
+- 第一版统一资源申请事务：按固定顺序锁定涉及的 repo/environment namespace guard 行 → 读取并规范化所有 requested resources → 检查 grant、freeze、长期 claim、活跃/隔离 lease → 全部创建或全部拒绝 → 同事务写事件/幂等收据。使用 READ COMMITTED 下锁后新语句重新读冲突集合；所有申请、释放、续期、冻结、恢复路径遵守同一锁顺序。
+- 命名空间锁只保护短元数据修改，不覆盖命令运行。不同 repo 可并行，同 repo 非冲突执行也可并行；未来仅在压测证实此事务瓶颈后拆 namespace。这样避免“两个事务都查到无冲突后插入”的 phantom 竞态。
+- 长期 claim 中父/子前缀冲突必须拒绝；`internal/a` 不与 `internal/ab` 冲突。路径去别名、拒绝逃逸/符号链接；大小写与系统文件语义作为接入契约。全局 module/env/ref 资源与 host-local index/worktree 资源分域。
+- 所有权变更必须带 expected_version；资源忙返回 holder/task/host、等待原因与可安全开展的不冲突范围。排队保留到达序号和有限 deadline，同一冲突域 FIFO；无冲突请求可越过被阻塞队首。取消与授予用同一事务判定，只有一个结果。
+- 不用大量写数据库的轮询自旋。事件游标 + 有界长轮询；通知只是唤醒，事实读 events。事件游标是 `(authority_epoch, sequence)`；恢复换 epoch 返回 CURSOR_RESET，客户端获取新一致 snapshot 及新起点，不能等旧高序号追平。全局事件顺序采用显式提交序列：同事务锁 event_clock 分配序号并提交，禁止仅以会先分配后提交的 PG sequence ID 推进不可回退游标。
+
+**执行生命周期**：
+
+```mermaid
+stateDiagram-v2
+  [*] --> queued
+  queued --> granted: 全资源授予
+  granted --> starting: executor持本机锁并复核代次
+  starting --> running: 记录进程身份
+  running --> succeeded: 退出与结果已核验
+  running --> failed: 明确失败
+  queued --> cancelled
+  granted --> recovery_required: 启动结果未知
+  starting --> recovery_required: 崩溃或响应丢失
+  running --> recovery_required: 失联/过期/子进程未知
+  recovery_required --> failed: 核实停止及外部结果
+  recovery_required --> succeeded: 核实已完成结果
+```
+
+续租在同一资源事务内校验 owner/session、authority_epoch、generation、lease 当前状态及 DB 时间未过期；过期或已隔离的租约不因迟到 heartbeat 自动复活。重新授权需先完成恢复，不借用旧 token。
+
+可取消排队；取消运行要 executor 确认进程退出并核验副作用后才终态。取消不是撤销已经发生的外部变更。
+
+```mermaid
+sequenceDiagram
+  participant A as CLI
+  participant C as Coordinator
+  participant P as PostgreSQL
+  participant E as Host executor
+  A->>C: request_id + scopes + expected_version
+  C->>P: 短事务校验并持久授予
+  P-->>C: operation + token
+  C-->>E: 绑定host的执行请求
+  E->>E: 本机flock + supervisor/cgroup
+  E->>C: 复核lease/epoch/授权
+  C-->>E: 允许该代次启动
+  E->>E: 启动一次，保存本机执行收据
+  E->>C: heartbeat / 完成结果
+  C->>P: 结果、释放及outbox同事务
+  A->>C: 按原request_id查询最终结果
+```
+
+**失联处理**：建议初始 heartbeat 10 秒、lease 60 秒，仅用于检测，实施压测后可调。中央以 DB 时间决定有效期，本机用 monotonic deadline 控制启动/续作；时钟跳变、重启、boot 不符进入隔离。所有新副作用启动必须在线确认；续租失败时 executor 停止接收新动作并暂停/终止受监督进程。中央租约过期将资源标 quarantined，不会立即变可用。
+
+executor 持久保存 operation/request/token 与启动/进程收据；spawn 与记账之间有崩溃窗口时按已命名 cgroup、PID/start/boot 核验，不按“日志没记录”判为未执行。完整子进程必须处于受监督 cgroup，子进程不能靠 setsid 脱管；无法验证范围则保留恢复状态。文件路径仍是 L1 合作边界，若允许旧 Agent 直接写，必须明确其不在强制防护覆盖内。
+
+**目标侧 fencing**：每个实际写入目标使用 `authority_epoch + generation`，成功持久授予才返回 token。父子路径映射至同一执行冲突域的目标代次；多目标请求返回与各目标绑定的 token 集，不能只按用户任意 path 字符串建互不相识的计数器。目标执行器将“核验代次→串行执行→核验结果→写收据”放在同一操作闸口，持有本机锁直到已知结束；仅在命令前查一次 DB 然后放开锁不够。旧代次完成结果可作为调查证据，不能回写新代次状态。
+
+首期将 dev 集成与每个共享环境绑定单一指定 executor，部署凭证只在该执行账户，避免其他主机绕过闸口；不设计自动主机接管。若原主机不可达，必须确认电源/访问已被隔离或目标原生拒绝旧 token，才可更换执行主机。Docker 已接受的长操作、远端 Git 已成功的更新不因 kill 本地 client 而取消，必须核对目标事实。对未知外部动作不承诺 exactly-once。
+
+### API and Agent Experience
+
+协议是结构化版本化 JSON API，CLI 给人可读摘要并可输出 JSON；不提供通用 SQL，也不让 Agent 直接连 PG。身份主体绑定 repo/grants，所有详情、列表、事件、证据索引均按同一权限过滤。
+
+| 操作族 | 语义 |
+|---|---|
+| task create/get/list/update/close | 创建、CAS 更新五态/交付维度，close 前核对活跃/恢复 operation；不隐式关闭能力 |
+| claim acquire/get/release/transfer | 全资源认领、明确归属；交接校验 owner/revision/未结束执行 |
+| execute / operation get/wait/cancel | 幂等请求、有限等待、完整受监督生命周期 |
+| resource list / freeze / recover | 查询实际占用与隔离，恢复必须 reason + 现场证据 + 管理能力 |
+| feature propose/review/apply | U7 的版本化能力声明，不以普通 task scope 获得审批权 |
+| snapshot/export/publish/reconcile | 读一致快照、生成文件、提交发布收据和修复投影 |
+| candidate validate/integrate / env guard | 沿用冻结 SHA、候选父链、环境批准范围与本机执行身份 |
+
+每次可重试写请求带 request_id；同主体域同 ID 同 payload 返回原结果，不同 payload 拒绝。保存幂等终态或不可复用 tombstone，不能清日志后让旧 request_id 再次执行。客户端遇超时先查询原 operation；只有明确未接受的新请求可安全重发。返回 CONFLICT_VERSION / RESOURCE_BUSY / RECOVERY_REQUIRED / AUTHORITY_UNAVAILABLE / STALE_EPOCH / PERMISSION_DENIED，区别数据库内部重试和用户资源冲突。
+
+所有工作区启动读取稳定安装客户端或主仓 bootstrap，协议协商拒绝旧版本写。不要依赖各 worktree 内可能陈旧的 Python 源码执行新权威规则。
+
+### Document Authority and Publication
+
+| 信息 | 首期权威 | 后续 |
 |---|---|---|
-| scope | 智能体允许修改哪些路径/能力 | `tasks.scopes` + `check_resources`，已 enforced |
-| claim | 某项工作当前由谁长期负责 | **缺失**；CURRENT 手工行不是原子认领 |
-| lease | 谁正在操作某资源 | `Lease` + flock + 存活核验，已 enforced |
+| 任务状态、owner、claim、队列、操作、恢复、cleanup 接管 | DB | CURRENT 只读投影，CLI 查询实时值 |
+| CURRENT 焦点、受控约束、说明 | Git 手工区块 | 与生成区块明确边界，不自动丢弃 |
+| FEATURE-MATRIX 能力行 | 首期 Git；DB 仅保存待审变更建议及基线 hash | U7 切换后结构化行以 DB 为准，Git 保存发布历史 |
+| 规范、方案、验收报告、证据正文 | Git 不可变提交引用 | 不变；URI/commit/path/hash 组合，不能只存主机绝对路径 |
+| 发布门禁与 production_ready | gap-matrix | 本方案不迁移、不自动推导 |
 
-认领在短事务中完成：检查权限、冲突、冻结、公平排队、登记归属、写审计——全成或全拒。冲突返回持有者、队列票据与 `retry_after`。
+首期通过中央 proposal 队列串行处理 MATRIX 修改，校验指定 dev 的行 hash 与审查证据，停止旧副本直接改行入口，合入成功才确认发布。U7 导入经审核的 canonical dev 表为 feature_records，校验稳定 ID、行数、正文、scope 与证据引用；替换生成区块的权威声明同一个切换窗口生效。U7 有独立 matrix authority_version 切换屏障：冻结 proposal apply/publish，排空或隔离 approved、committed、待 integrate 的所有旧发布，再固定 canonical dev SHA 完成导入核验；原子推进 authority_version 后启用新门禁。最终集成入口也验证此版本，旧候选必须拒绝或显式重基线，不能在导入后迟到集成。先前待审 proposal 重新基线，不能直接当生效数据导入。
 
-**执行安全不能只靠数据库锁。** TTL/心跳过期只进入 suspect/quarantine，不立即把资源交给下一个智能体；须核验旧进程与外部操作结果后再交接（见 U7）。
+生成器在一致性读事务中获取数据版本；数据库状态变更同时写 outbox。投影 identity 与去重键采用 `(authority_epoch, document_id, generation)`，Git receipt/manifest 必须同样绑定 epoch；旧 epoch 的同号 generation 仅供恢复调查，不抵销新发布。采用 schema/renderer version、源证据 SHA、生成时间、文件 hash manifest；多文件生成先写独立 staging，再由单 publisher 工作区提交同一 Git commit。普通 Agent 不能编辑生成区块；手工区块变动用 hash CAS，保留 Markdown 硬换行与其他正文。只有投影内容字段的变更才推进 document generation；heartbeat、投影自身回执与投影操作审计不递归触发新文档，避免自激发布循环。投影滞后可见，不因滞后阻止普通 DB task 查询；关键授权绝不读 Markdown 快照。
 
-## 3. L1 七个实施单元
+publisher 不直接写主目录 dev，每次构造最新 dev 的可验证候选并走现行集成入口。快照只在用户请求、任务里程碑或受控批次发布，不每个 heartbeat 产生 Git commit。投影状态 queued/rendered/committed/integrated 分离；Git commit 已完成但 DB receipt 丢失时按 generation/manifest 和提交父链找回，不能重复发布或用旧数据覆盖新快照。
 
-每单元另建 short-term + mutex + 验收 + 回退；合入 local_dev 串行占 `git:dev`。
+U7 的 feature done 需要 server 校验审核 grant、已提交证据、适用 source/artifact/environment、验证结论及 record_version；审核者对范围负责。服务器能校验证据结构和身份，不能自动证明报告业务事实。feature maturity、task_status、production_ready 保持不同状态空间。
 
-### U1 缺陷收敛与实现归一
+### Native Daemon Operations
 
-| 项 | 状态 |
+推荐一台长期在线 Linux 协调主机原生安装 PostgreSQL 与 agentcoord-server；每台执行主机安装 agentcoord-executor。中央服务可与其中一台开发主机同机，但产品容器重启不得停协调服务。所有路径由安装清单声明，DB data、运行 socket、配置、日志、备份不放 worktree 或产品 data 目录。
+
+| 服务 | 管理方式与建议 |
 |---|---|
-| queue 子解析器重复注册 | **已修复并合入** `63e66c6fb35d6b4dd9f3ed92e15acc9933aeb344`（删后注册块；保留 `--head` / cancel `--task` / schedule `--drain`；回归 3 例；unittest 103/2 skipped PASS） |
-| `scripts/agentctl_automation.py` 零导入、schema 分叉 | planned：收敛到 W4 或按记录删除 |
-| `.locks/state.db` 0 字节孤儿 | planned：确认无引用后清理（运行态，不入 Git） |
+| PostgreSQL 专用实例 | 发行版包与 systemd 管理；专用 cluster/DB/roles/端口，默认仅本机 socket，API 主机是唯一 DB 客户端 |
+| agentcoord-server | systemd system service，专用非 root 用户，固定已校验制品路径；Restart=on-failure、有限重启退避；启动后 schema/identity/reconcile 完成才 ready |
+| agentcoord-executor | 每主机专用受授权账户、systemd 管理；本机 socket 控制权限；任务 cgroup 生命周期与守护进程恢复一起核验 |
+| publisher | 指定 host/worktree 的受控 worker，复用执行代理，不增加第二权威 |
+| 定期维护 | systemd timer 触发备份/保留/巡检；不自动清除 quarantined 操作或旧 worktree |
 
-### U2 治理策略外部化
+user service 可用于开发试验；要注销后/开机运行必须核验 user manager、linger 和权限，不能拿 nohup 或一次启动成功代替可靠常驻。正式配置优先系统级 unit；Watchdog 仅在实现 sd_notify 心跳后启用，不放一个没有消费的配置。
 
-新建 tracked `configs/agent-governance.yaml`（今日不存在），收敛 `SHARED_DOCS`、`PROJECTABLE_DOCS`、`JOB_KINDS`、protocol/policy 版本；fail-closed 加载；旧客户端低于最小协议版本拒写。
+中央对执行主机只开放受限私网 mTLS API；host 证书、操作者身份与 task grant 分开，host 有证书不等于能修改任何 task。grant 由明确管理员授权登记；旧 CLI 自报能力的方式不能照搬。DB schema migration 使用独立高权限 role，正常服务不使用超级用户。秘密由 service credential/权限受限配置提供，不读产品 .env，不进入命令参数、日志或 Git。
 
-### U3 显式长期认领 claim
+/health 只表示进程活，/ready 表示 DB 可达、schema/协议兼容、权威身份已校验并完成启动恢复；某资源 quarantine 单独报告，不要求所有旧问题都解决才能接受无冲突操作。指标至少包含：认领冲突/版本冲突/DB 等待分别计数、事务时长、队列等待、最后 heartbeat、quarantine、投影滞后、备份年龄、磁盘与 PG WAL 增长。
 
-在 SQLite 增加 claim 表/字段（或等价资源键），与 scope/lease 分离。`BEGIN IMMEDIATE` 短事务内：权限、父子路径重叠、冻结、公平排队、审计。不同资源可并行。不把 Markdown `idle` 当作原子锁。
+备份以每日一致性基础备份 + 连续 WAL 归档为目标，保存到另一故障域，做定期隔离恢复演练；保留周期按实际容量配置。启动目标 RPO ≤5 分钟、RTO ≤30 分钟须经测量才承诺；只做每日逻辑备份时不能声称 5 分钟 RPO。[PG PITR](https://www.postgresql.org/docs/current/continuous-archiving.html)
 
-### U4 常驻协调入口（本机）
+恢复旧备份后控制平面仍可能落后已发生的 Git/部署事实：生成新 authority_epoch，全部执行租约隔离，撤销旧执行凭据，核对所有 target 后再开放。恢复屏障覆盖每个登记 executor 的持久 journal、最高接受代次与请求收据，不能只遍历备份中存在的 operation。按旧 epoch/主体/request_id 回填结果或不可复用 tombstone；恢复点之后不可重建的请求保持未知并拒绝重放。所有相关 executor 持久确认新 epoch 后才开放其资源；不可达主机继续隔离。新 epoch 的请求必须重新取得授权且不能自动包装未知旧请求为新请求。旧 epoch 与新 epoch 不按 UUID 大小排序，而是严格匹配当前已登记 authority。恢复期间禁止通过“创建空库”开机成功。
 
-- **macOS**：launchd plist（本机默认）。
-- **Linux**：systemd unit。
-- 单实例：`.locks/os/manager.lock`（2026-09-21 方案已规划、今日不存在）。
-- 职责：驱动 `queue schedule`、文档投影发布、心跳过期扫描；**不新增权限**。
-- 不可用时：阻止受保护写入，不静默放行。
+systemd 自动重启服务不代表自动重试任务；二者必须分开。维护升级先 drain、暂停新授予、处理在途 operation、备份、迁移 schema、滚动升级兼容客户端，然后核验后开放。单节点中央故障时允许读最后快照（标 stale），受保护写拒绝；禁止自动回退本地 SQLite 或 Markdown。
 
-### U5 CURRENT 状态输出化
+参考：[PostgreSQL 原生启动](https://www.postgresql.org/docs/current/server-start.html)、[systemd service 原始文档](https://github.com/systemd/systemd/blob/main/man/systemd.service.xml)、[PG SSL](https://www.postgresql.org/docs/current/ssl-tcp.html)。本机只读探测已见 Linux/systemd，未验证目标主机/管理员权限；pg_config 不在 PATH 不等于没有运行 PG 服务。
 
-- `## 并行认领` / 集成槽位：稳定 record id + `docs project` 生成；人工「焦点 / 受控约束」保留。
-- 同批修正：`CURRENT.md:5` 与 `:15` 自相矛盾；操作规范 `:3`「Linux 本机」过时描述。
-- 发布仍走 `docs apply` CAS + 收据 + hook。
+### Migration and Rollback
 
-### U6 FEATURE-MATRIX 分阶段迁移
+1. 盘点每台主机的 repo/checkout、旧 .locks identity、task/run、文档基线、客户端与 hooks 版本；验证 canonical integration target。把旧 active/done/cancelled 与新五态分开映射，冲突列入人工对照，不猜测 task done。
+2. 用新服务做只读 shadow 导入与比对，旧入口仍是唯一写权威；影子系统不得授予执行租约。不要在线双写两套权威。
+3. 切换窗口暂停新旧认领和执行，排空或隔离旧进程；保留原 lock inode。现有 env:dev recovery_required 必须由原 owner/获授权维护者检查，研究任务不替其 recover。
+4. 各主机安装统一客户端/hook/执行入口，验证旧程序无法再取得共享目标写权限；收紧共享目标凭证。无法升级或核验的主机注销写能力并保持隔离，不能一边放行旧客户端一边宣布多主机已统一。
+5. 冻结后做最终快照导入，持久保存来源 hash、转换报告与导入 ID；切换 authority/protocol epoch，所有主机核对新的 repo/host 映射后开启首期服务。
+6. 两台真实主机试点：同资源争抢、不同任务并行、断网与重启、生成投影与 Git 收据；通过后扩大接入，最后单独实施 U7 的矩阵权威切换。
 
-27 模块行加稳定 record id 与结构化状态字段；保留声明范围、审核与证据。`done` 仍需 `docs:approve` + 已提交证据路径；不因任务结束或锁释放自动升 done。`production_ready` 仍只由发布门禁判定。任务完成 ≠ 能力完成 ≠ 发布就绪。
+回退规则：未启用新写时可恢复旧唯一入口；一旦接受新写，不能还原旧 SQLite 快照直接继续。应冻结新入口、排空/隔离执行、导出全量新事件与状态、核验 Git/环境外部事实，再以有版本转换/人工对照的方式恢复兼容权威；无法无损转换时保持新库只读并修复服务。不回滚产品数据库，不强制 reset dev，不自动恢复旧 lease。
 
-### U7 执行代理与安全交接
+### Capacity and Delivery
 
-固化：suspect → quarantine → 核验（supervisor/子进程组消失、物理锁可得、外部结果核对）→ 交接。复用并加强 `recover`；补 fencing generation 与 env/git 收据。Git 集成与共享环境部署集中主目录执行入口（`queue_schedule` 已限主 dev）；保留 flock、候选准入、`--ff-only`。数据库管记录与授权，执行入口防实际双写。
+首期压测建议：100 个客户端并发，分布在至少两台主机，持续 30 分钟；混合任务查询、独立认领、同资源冲突、10 秒 heartbeat。100 个执行器约 10 次 heartbeat/秒只是容量估算，不是数据库基准。
 
-## 4. L2 登记（planned，不开工）
+提议验收目标：健康局域网中不含有意资源排队的元数据写 p95 ≤200ms；事务 p95 ≤50ms；在持久盘未丢失的正常运行/进程/网络故障中已确认提交丢失 0、重复共享副作用 0、非法双授予 0。磁盘/整机灾难恢复的数据损失按实测 RPO 报告，不能把异步备份承诺成所有故障零丢失。数据规模、RTT、硬件、样本数、错误类型与长尾均记录。跨地域按实际网络重订时延目标；不以降低同步提交或跳过权限达标。
 
-前置条件：用户二次授权 + ADR 覆盖锁方案 §3.2 与平台深化 §0。
+工程量估算（未做 prototype）：U1–U6 约 15–22 人日，U7 再 3–5 人日；多主机故障注入与迁移演练是主要不确定项。可先用 3–5 人日完成 U1–U2 的独立验证，依据证据继续，不把演示当正式接管。DB 高可用、Web/MCP、跨地域、多租户和恶意用户隔离不计入首期。
 
-登记内容：中央独立 PostgreSQL（独立配置/数据目录/备份，不依赖产品容器）；中央协调 daemon；各主机执行代理；指定执行主机做 Git 集成与部署；systemd 开机启动与异常重启；单中央节点故障时暂停受保护写入。
+---
 
-**待执行验收（不得冒充已测）**：真实双主机并发、断网、旧进程存活、重复 `request_id`、备份恢复。systemd 能恢复进程，不能替代主机容灾与数据库备份。
+## Implementation Units
 
-## 5. 文档与状态模型
+### U1. Identity and Storage Foundation
 
-| 内容 | 归属 |
+**目标 / Requirements**：R1、R3、R8、R9。建立独立工具模块、版本协议、身份与 grant 数据模型、短事务和迁移版本。
+
+**文件**：拟新增 `tools/agentcoord/go.mod`、`cmd/agentcoord/`、`internal/control/`、`internal/store/`、`migrations/`、`internal/store/store_integration_test.go`（均在该工具模块下）。
+
+**方法**：先对现有 register/with/docs 行为做特征测试；只复用契约不引入产品依赖。固定命名空间 guard、请求指纹、事件提交序列、授权校验同事务落地。
+
+**测试与验收**：真实 PG 下相同 task/request 双创建只保留一个；错误主体拒绝；未提交/回滚事务不留下有效 grant/event；两 repo 可隔离；先分配事件后提交的乱序不会丢游标。此阶段不接管真实仓库。
+
+### U2. Claims and Queue
+
+**依赖**：U1。**Requirements**：R2–R4。
+
+**文件**：`tools/agentcoord/internal/control/claims.go`、`queue.go`、`claims_integration_test.go`、`api_contract_test.go`；后续命名可调整，职责不合并到 handler。
+
+**方法**：授权/长期归属/执行占用分表；所有资源在短事务原子申请，CAS 修改，公平有限等待与取消；CLI 显示可行动的冲突信息。
+
+**测试与验收**：两主机争父/子路径只一个获准；a 与 ab 不误冲突；批量请求一项冲突则全部不授予；不同记录均能更新、相同行旧 version 失败；grant/release/cancel/续租竞争无双赢；长期 claim 不随一次命令结束释放。
+
+### U3. Host Executor and Fencing
+
+**依赖**：U2。**Requirements**：R1、R5、R8。
+
+**文件**：`tools/agentcoord/internal/executor/`、`executor_integration_test.go`、`recovery_integration_test.go`；适配 `scripts/agentctl.py`、`scripts/agent_worktree.py`、`scripts/tests/test_agentctl.py`、`scripts/tests/test_agent_worktree.py`。
+
+**方法**：保留本地 flock/生命周期/进程身份，加入 cgroup、host token、本地启动 journal 与续租；创建 worktree 与注册之间采用可恢复步骤，失败保留可归因工作区，不宣称 SQL 可回滚 Git。
+
+**测试与验收**：kill 中央服务/代理/客户端分别观察真实 child；SIGSTOP、setsid 子进程、主机重启、PID 重用、响应丢失和两次投递均不重复启动；lease 过期后旧 child 活着仍禁止接管；恢复旧 epoch 拒绝旧 token；同 UID 绕过边界明确记录，不冒称已沙箱化。
+
+### U4. Shared Targets and Git Integration
+
+**依赖**：U3。**Requirements**：R1、R5、R8。
+
+**文件**：`tools/agentcoord/internal/executor/targets.go`、`targets_integration_test.go`；适配 `scripts/agentctl.py` 的 validate/integrate/hooks、`scripts/env-service.sh`、`scripts/candidate-images-build.sh`；关联现有脚本测试。
+
+**方法**：每共享目标一个批准 executor；中央目标身份与本机主目录/环境绑定，不能从任意工作区调用。跨主机移交冻结的 source head 和必要 Git 对象，验证 hash/来源/父链后，由指定 integration executor 在本机注册独立 integration task/worktree，从当前 canonical dev 构造两父候选。按现行准入约束，在该 worktree HEAD 上执行验证并生成绑定本地 task + candidate SHA 的收据，再锁内复核 expected-dev 后推进。远端源分支 PASS 仅为辅助证据，不能代替本机候选验证；dev 前进必须重建重验。publisher 复用此流程。保留冻结制品与真实业务验收门禁。
+
+**测试与验收**：两个主机同时集成只有一条合法 ref 前进；旧 dev 基线拒绝；候选对象缺失/错 hash 拒绝；远端 source head 的 PASS 不能授权不同 merge candidate，缺本地 owning task/worktree 或精确候选收据拒绝；非目标 executor/无 env grant 拒绝；Docker 已接受操作但 client 死亡时进入恢复并核对实际结果，不能再次自动部署。
+
+### U5. Current Projection and Matrix Proposal
+
+**依赖**：U2、U4。**Requirements**：R3、R6、R7。
+
+**文件**：`tools/agentcoord/internal/projection/`、`projection_integration_test.go`；受控更新 `.doc/ops/CURRENT.md` 的生成区块契约及 Python docs 适配；新增稳定 feature ID 导入映射。
+
+**方法**：DB 任务/claim 状态自动投影，CURRENT 人工区块保留；MATRIX 先经中央待审 proposal 与 canonical Git CAS，现行矩阵仍为权威。publisher 单独工作区，outbox/manifest/提交/集成收据可恢复。
+
+**测试与验收**：两个旧 worktree 不再分别宣称同一权威修改成功；同一 generation 多次消费只一个发布结果；两文件中途失败、Git 成功回执丢失、dev 前进均能重建或找回；人工正文/硬换行/其他任务不丢失；未批准 MATRIX done 被拒绝。
+
+### U6. Native Deployment and Authority Cutover
+
+**依赖**：U1–U5。**Requirements**：R9、R10。
+
+**文件**：`tools/agentcoord/deploy/systemd/`、`tools/agentcoord/tests/multihost/`；拟新增原生安装/备份/恢复 runbook；更新 AGENTS、PROJECT、worktree 操作规范、policy-registry、验证契约，按规范单独认领共享文件。
+
+**方法**：固定制品安装、mTLS、专用 PG、独立配置、schema migration/drain/ready；先 shadow 再一次权威切换。规范修订与工具验收同步，未接入主机不得继续写共享目标。
+
+**测试与验收**：两真实主机跑完整流程；重启/注销/开机后 unit 状态与 ready；撤销证书/伪造 task/capability 拒绝；冷恢复演练、RPO/RTO 记录，区分完整存储下确认事务零丢失与灾难恢复实际损失窗口；恢复低序号备份时旧高位事件 cursor 收到 reset，旧投影同号收据不可抵销新 epoch 产物；旧 SQLite 客户端/hook 写入拒绝；备份后一次操作成功再恢复旧库，原 request_id 重试不得再次执行；PG 不可用没有本地降级写；完整记录迁移差异与回退条件。
+
+### U7. Feature Record Authority
+
+**依赖**：U5、U6 且首期稳定。**Requirements**：R3、R7、R10。
+
+**文件**：`tools/agentcoord/internal/control/features.go`、`features_integration_test.go`；`.doc/status/FEATURE-MATRIX.md` 的结构化行投影、稳定 ID 映射与版本契约；更新发布规范但不更改 gap-matrix 的门禁结果。
+
+**方法**：仅迁移完成度表及明确结构化字段；后续 prose/特殊章节逐项保留，不假设当前文件只有一张表。导入后切换生成区块权威；scope/evidence 留 Git 引用，批准记录入 DB。
+
+**测试与验收**：行数/稳定 ID/原义务/证据/状态完全对照；原模块改名不丢历史；未完成不得因任务关闭变 done；scope 缩小必须显式保留义务迁移；旧报告/错误制品/未提交证据无法升级；将旧 proposal 分别暂停在 approved、committed、待 integrate 后切换 U7，旧 authority 候选均不能迟到进入 dev；production_ready 保持独立。
+
+---
+
+## Verification Contract
+
+所有下列测试为未来实施验收要求，本研究未执行。按现行[验证契约](../ops/2026-09-21-validation-contract.md)分层记录，源码阅读不等于通过。
+
+| 层次 | 证据与判定 |
 |---|---|
-| 任务归属、进度、队列、执行状态 | 数据库（权威） |
-| CURRENT 运行表格 | 逐步自动生成；人工焦点/约束保留 |
-| FEATURE-MATRIX | 分阶段结构化；证据与审核保留 |
-| 规范、方案、验收报告正文 | 继续 Git 管理 |
+| 原有门禁回归 | `python3 -B -m unittest discover -s scripts/tests -p 'test_*.py' -v`；保留真实退出码，原有 scope/hooks/候选/恢复负例必须通过 |
+| 新模块静态/单元 | 独立 Go module 内 fmt/vet、`go test -race ./...`；不得用 mock PG 代替事务语义验证 |
+| 真实数据库 | 并发连接与真实提交、锁竞争、进程终止、SQLSTATE 重试；记录 PostgreSQL/driver/平台版本 |
+| 多主机协议 | 至少两台实际 Linux host、独立文件系统/boot identity，真实网络故障；单机多进程不冒充跨机 |
+| 用户使用路径 | 两个真实 Agent 会话通过 CLI 注册/认领/执行/关任务，第三会话观察一致状态；冲突解释可操作，重启后仍保留 |
+| 共享副作用 | 隔离测试仓库/测试环境实际 Git 和外部执行结果；不污染真实产品对话；受授权上线时再验目标环境 |
+| 迁移与灾难恢复 | 导入差异、旧入口隔离、数据库恢复、外部结果重核、epoch 失效、备份恢复耗时 |
+| 文档投影 | 一致 snapshot、CAS、重放、Git 发布恢复、原文语义与各权威状态分离 |
+| 性能 | 按 Capacity workload 报 p50/p95/p99、错误分类、资源等待与事务等待；未测不宣称达标 |
 
-## 6. 全局验收门
+额外不变量：任何时刻同一共享目标不存在两个可实际执行的 writer；数据库成功状态不早于已持久结果；暂停/超时/未知不得写成 succeeded；不能以健康检查代替原例、变体与正常路径验收。现有产品 API/浏览器不在此工具变更主验收范围；若实施改变业务行为，再追加相应真实产品验收。
 
-1. 每单元：受影响 `unittest` + 负例（冲突认领、旧 generation、daemon 停写）。
-2. U3/U5/U6：双任务并行写不丢行、同行 CAS 冲突可见。
-3. U4/U7：杀 supervisor 留子进程不得误抢；断心跳后须核验再交接。
-4. L2：未授权不得实施；不得把 planned 写成 enforced。
-5. 红线：不把 L1 宣称为 OS 沙箱；不依赖产品容器启动协调；不接触业务数据库。
+---
 
-## 7. 风险与回退
+## Definition of Done
 
-| 风险 | 控制 |
-|---|---|
-| 两套锁各自放行 | 延续 2026-09-21 §10 硬链接/双锁兼容；禁止静默第二锁根 |
-| daemon 扩大权限 | 只调度已授权操作；能力仍来自 task register |
-| CURRENT 自动覆盖人工焦点 | 仅受控区块机器写；整文需 docs:admin |
-| L2 提前开工 | 无 ADR 拒合入跨机代码 |
-| 文档与运行态漂移 | CURRENT 标明快照时间；以 doctor/status 核验 |
+首期完成：U1–U6 验收通过、两主机真实试点、旧新权威切换可审计、CURRENT 投影与发布可恢复、备份恢复实测；FEATURE-MATRIX 仍明确使用 Git 权威与中央 proposal。完整方案完成还需 U7 完成结构化行迁移与审批验收。
 
-每单元独立 revert；迁移 additive；部署清单与代码分提交。
+研究任务 done 仅表示可审方案交付。实施时分别报告本地 commit、dev 集成、协调制品版本与运行主机、数据库 schema、远端是否同步、cleanup；不因文档存在升级 FEATURE-MATRIX。移除试验遗留，保留真实故障证据，按原有保守门禁清理 worktree。
 
-## 8. 与既有文档关系
+---
 
-- 本方案 = [2026-09-21 锁方案](./2026-09-21-agent-lock-coordination-plan.md) 的**演进版**：L1 补 claim/常驻入口/文档状态化；不推翻 SQLite 权威与 advisory 边界。
-- 不替代 [平台深化方案](./2026-09-23-platform-deepening-reliability-ha-concurrency-plan.md)（产品可靠性/HA）；协调跨机另立 ADR。
-- gap-matrix / FEATURE-MATRIX 状态不因本方案自动变更。
+## Appendix
 
-## 9. 开工准入（第一批实施前）
+**直接源码**：`scripts/agentctl.py` 的 Repo.db、Lease、supervise、docs_snapshot/docs_apply、task register/close、recover、hooks、integrate；`scripts/agent_worktree.py` 的 create/write_lock/removal_lock；`scripts/tests/test_agentctl.py` 和 `test_agent_worktree.py`。
 
-1. 每批 short-term + CURRENT 认领 + mutex。
-2. 从当时 dev tip 建 worktree；重读 policy_revision。
-3. L2 / 共享环境须单独授权。
-4. 本文件保持 planned；首批实施时回填映射，不代填验收。
+**关联规范**：[工作规范](../ops/2026-09-21-agent-worktree-workflow.md)、[规范登记](../ops/2026-09-21-policy-registry.md)、[文本/投影经验](../ops/lessons/2026-09-23-content-hash.md)、[能力矩阵](../status/FEATURE-MATRIX.md)。
+
+**尚需部署时确定的信息**：中央主机及执行主机清单、私网/mTLS 签发方式、管理员账户、可用磁盘与备份目标、明确环境授权。这些不阻止方案和隔离实现，但阻止真实安装与权威切换。实际性能、恢复时长、旧任务处置由验收决定，不在研究中预报 PASS。

.doc/status/FEATURE-MATRIX.md

@@ -47,35 +47,35 @@
 
 ## 完成度矩阵
 
-| record_id | 模块 | 声明范围 | 状态 | 发布关系 | 证据 | 剩余工作 / 关闭条件 | mutex |
-|------|----------|------|----------|------|---------------------|-------|-------|
-| gov-agent-worktree | Agent worktree 治理自动化 | 主目录保护、任务 worktree、机器认领、候选集成、dev 部署与安全清理 | partial | non_blocker | [方案](../remediation/2026-09-21-agent-workflow-governance-plan.md)；[L1 验收](../test-reports/2026-09-21-agent-governance-test-report.md)；[W1-B macOS](../ops/short-term/2026-09-22-agentctl-macos.md)；[W4](../ops/short-term/2026-09-22-governance-automation.md)；residual `modular-decouple-residual-2026-09-23` | L1 与 macOS `with/docs apply/validate/integrate` 已合入。W4 landed：durable queue + 完整 docs projection apply（行/整文 CAS）+ deploy/recover 真实收据闭环 + Darwin cwd 可见性测试。仍 deferred：PI 源码镜像 compose、跨机隔离、automation/w4 实现收敛。本行不升 done | `agent-workflow-governance` |
-| intent-l1 | 意图识别 L1 | 18 类 Intent、三分支消解、写/只读分流、双标签 `DOC_BUSY`、intent 纯依赖边界 | done | non_blocker | [intent-recognition](../system-design/intent-recognition/)；[工作流作用域](../test-reports/2026-09-21-intent-workflow-scoping-test-report.md)；[审计](../audit/2026-09-13-conversation-intent-runtime-state.md)；[报告](../test-reports/2026-09-13-conversation-intent-runtime-state-test-report.md)；[双标签](../test-reports/assets/2026-09-15-conversation-intent-dual-tab/live.json)；[U1](../test-reports/2026-09-15-multi-intent-u1-contracts-test-report.md)–[U3](../test-reports/2026-09-15-multi-intent-u3-intentflow-pg-test-report.md) | **边界 before**：含 U9–U12 叙事混入 → **after**：U9–U12 迁至「多意图扩面」行。关闭：纯依赖边界回归即重开 | `intent` |
-| intent-plan-u1u8 | 多意图持久计划（U1–U8 基线） | app/intentflow 生命周期、HITL、默认 `legacy`、U1–U8 代码与安全基线 | partial | non_blocker（默认 legacy） | [设计](../system-design/2026-09-15-multi-intent-hitl-plan.md)；[U1](../test-reports/2026-09-15-multi-intent-u1-contracts-test-report.md)–[U8](../test-reports/2026-09-16-multi-intent-u8-task-generate-test-report.md)；[Wave2 真 PI](../test-reports/2026-09-16-wave2-real-pi-evidence-test-report.md)；[Track I1](../test-reports/2026-09-22-track-i1-query-owner-test-report.md) | **after Track I1**：生产组合根已去 Fake query owner，改真实 QueryOwner；receipt 含 auth scope digest；confirm 后走既有步骤内核 dispatcher。默认仍 `MULTI_INTENT_PLAN_TIER=legacy`。升 `auto_read/confirm` 需 Track I2（项目 allowlist + 频率门）。U9–U12 仍独立 dry-run | `intent-plan` |
-| intent-plan-u9u12 | 多意图扩面（U9–U12） | U9 LLM 分段实验；U10 mutate；U11 docgov；U12 workflow/run-control | partial | deferred_enhancement | [设计](../system-design/2026-09-15-multi-intent-hitl-plan.md)；[go/no-go GO](../ops/research/2026-09-16-wave3-pu6-pu8-go-no-go.md)；[脚手架](../test-reports/2026-09-16-pu8-u9-u12-flags-test-report.md)；[U9](../test-reports/2026-09-17-w4-u9-segment-test-report.md)；[U10](../test-reports/2026-09-17-w4-u10-mutate-test-report.md)；[U11](../test-reports/2026-09-17-w4-u11-docgov-test-report.md)；[U12](../test-reports/2026-09-17-w4-u12-run-control-test-report.md)；[2026-09-20 复核](../ops/research/2026-09-20-capability-enablement-impact-research.md) | U9 proposer 已实现和注入但未进入生产聊天分段调用；提议请求已带 reasoning profile。U10–U12 当前为 dry-run/validated-only adapter。历史直接调用/PI 测试继续有效，不代表 live 接线。逐域实现和验收，禁止以 `full` 一次放量 | `intent-plan` |
-| chat-ctxmgr | 对话 / ctxmgr baseline | 多轮上下文、刷新/重登/重启恢复、授权同集正文与计数、U10 端口化停止扩面 | done | non_blocker | [multi-turn](../system-design/multi-turn-dialogue/)；[刷新审计](../audit/2026-09-13-chat-history-refresh-disappears.md)；[U10](../test-reports/2026-09-15-chatlog-contextasm-u10-test-report.md)；[门禁 B3](../test-reports/2026-09-16-chat-refresh-gate-test-report.md)（项目 6359） | **before**：语义摘要误标 D5 混入 → **after**：摘要迁「语义摘要 D3」；D7 数据治理独立。U10 停止扩面 | `chat` |
-| chat-semantic-d3 | 语义摘要（D3） | 授权后可见集合上的语义摘要；shadow → 可选替换 deterministic | partial | deferred_enhancement | [chat-agent-p6-backlog](../backlog/chat-agent-p6-backlog.md)；[go/no-go GO](../ops/research/2026-09-16-wave3-pu6-pu8-go-no-go.md)；[pu6](../ops/long-term/2026-09-16-pu6-semantic-summary-contract.md)；[脚手架](../test-reports/2026-09-16-pu6-semantic-summary-test-report.md)；[W2 真 PI](../test-reports/2026-09-17-w2-semantic-summary-shadow-test-report.md)；[Track S1](../ops/short-term/2026-09-22-track-s1-summary-consolidation.md) | **after Track S1**：durable `chat_summary_shadow_jobs` + 后台租约/watermark/provenance 已合入；served Narrative 保持确定性。shadow 默认 off；`SEMANTIC_SUMMARY_REPLACE` **未接线**。**2026-09-23 实测** DOCREV 路径 schema **63**。授权可见集 digest 已进 shadow 路径。本行不升 done | `chat` |
-| chat-data-d7 | 对话数据治理（D7） | 留存/删除口径、库·备份·日志控制、敏感字段加密边界 | deferred | deferred_enhancement（违规则升 blocker） | [计划](../remediation/2026-09-16-feature-matrix-production-readiness-plan.md) Scope Boundaries；[D7 ADR 草案](../adr/2026-09-17-d7-chat-data-retention.md)；[W7 盘点](../audit/2026-09-17-d7-data-inventory.md)；[红线证据](../test-reports/2026-09-22-redline-evidence-d7-test-report.md) | 只读盘点 + Track E ID-only 符合性已补。口径仍 `pending-compliance-signoff`；**禁止物理删除**。本行不升 done | `chat` |
-| squad | 智能体小队 | 角色-任务-工作区-黑板 | done | non_blocker | [agent-squad](../system-design/agent-squad/)；[test 2026-09-07](../test-reports/2026-09-07-dynamic-squad-planning-test-report.md) | 非关键步骤降级(A5/A6)属 backlog | `squad` |
-| workflow-gov | 工作流治理 | 三正式工作流、设置页/DutyMode、动作级鉴权、真实 PI 三工作流 E2E、full/none 混合长链 | done | non_blocker | [三工作流整改](../remediation/2026-09-12-three-workflows-strict-governance-remediation.md)；[409/职责](../test-reports/2026-09-14-workflow-plan-409-frozen-and-optional-duties-test-report.md)；[鉴权](../test-reports/2026-09-14-governance-action-level-authz-test-report.md)；[PI E2E](../test-reports/2026-09-16-pi-three-workflow-e2e-test-report.md)；[Wave2 full/none](../test-reports/2026-09-16-wave2-real-pi-evidence-test-report.md) | full 跨用户审批 + none 免审批不阻塞已签。纯软件自举仍独立 planned | `workflow` |
-| workflow-rdev | 研发设计控制（rdev） | 医疗第 4 工作流：13×60 manifest/模板、`squad.rdev_doc.v1` kind 编排、main-completed 硬 precheck、StageKey 动态化；不含前端/真 PI/键名空间化 | partial | deferred_enhancement | [设计](../system-design/project-workflow/07-研发工作流rdev接入-设计与实施计划.md)；[收口](../ops/short-term/2026-09-22-rdev-closeout.md)；[报告](../test-reports/2026-09-22-rdev-closeout-test-report.md)；[P3 历史](../test-reports/2026-09-19-rdev-p3-real-pi-test-report.md) | **after 2026-09-22 收口**：`rd_proposal` 标题门禁 + 法规表首表截止 dry PASS；nightly 脚本已扩四工作流（FullChain×3+FullNone）。P3 真 PI 三样本重跑因缺 `env:dev` **blocked**（不以 stub 冒充）。剩余：获环境后重跑 P3。本行保持 partial | `workflow-def` / `rdev-templates` |
-| workflow-swboot | 纯软件项目自举 | 软件项目创建、Bootstrap、Delivery、受控工程交接 | partial | deferred_enhancement（明确不挡首发） | [设计](../system-design/2026-09-14-software-project-bootstrap-workflow.md)；[ADR](../adr/2026-09-16-software-project-bootstrap-keys.md)；[L1 报告](../test-reports/2026-09-16-software-project-bootstrap-test-report.md)；[W5a](../test-reports/2026-09-17-w5a-software-bootstrap-ui-pi-test-report.md)；[红线证据](../test-reports/2026-09-22-redline-evidence-swboot-test-report.md) | **after W5a + 红线证据**：catalog 驱动创建、软件不挂医疗 key。**SWBOOT-10 仍 stub**（L1–L4 证据已补；L5/L6 待授权）。本行不升 done | `workflow-design` |
-| iam-authz | IAM / 鉴权 | 项目级 API 鉴权 + RBAC；会话/阶段授权 | done | 加固 | [v3 full inventory](../audit/authorization-matrix-v3-full.md)；[session 中断](../test-reports/2026-09-16-iam-route-inventory-test-report.md)；[fail-closed](../test-reports/2026-09-16-wave1-iam-fail-closed-test-report.md)；[410 策略](../audit/2026-09-16-bug11-410-retire-decision.md)；[R13](../audit/2026-09-16-r13-data-safety-checklist.md) | 全路由 inventory + session 中断负例 + 410 冻结 + R13 基线已签 | `authz` |
-| docgov | 文档治理 | 法定文档生命周期 + 租约 + 受控正文读取 | done | non_blocker | [docgov](../test-reports/2026-09-08-docgov-lifecycle-and-claiming-framework-test-report.md)；[正文 UI](../test-reports/2026-09-14-controlled-content-ui-acceptance.md)；[canonical hash](../remediation/2026-09-14-controlled-content-canonical-hash-remediation.md)；[键统一](../test-reports/2026-09-21-workflow-doc-key-unification-test-report.md) | 项目 143 只读；不终止。`doc_proj*` 同一发布键不能再并存 | `docgov` |
-| docgov-revision | 文档版本 baseline | 账本、人工修订、确定性 diff+lineage、运行时 UI、负责人通知 | done | non_blocker | [管理](../test-reports/2026-09-13-document-revision-management-test-report.md)；[Round20 UI](../test-reports/2026-09-14-document-revision-runtime-ui-test-report.md)；[ADR](../adr/2026-09-13-document-version-boundary.md)；[proposed/authoritative](../ops/short-term/2026-09-20-proposed-authoritative-reports.md) | **before**：完整 PI narrative 混入 → **after**：迁「PI change-report 叙事」。fallback 报告是本行内显式行为，不是缺口。lineage GET 已按 URL 项目和文档可见性裁剪。test_manager 血缘的下游/上游版本改读文档版本，不再写死 1。Agent 候选报告为 `proposed`，正式提交才写 authoritative 后继并挂到版本；拒绝、替代后旧报告不能再出建议。人工修订、导入和聊天卡仍未分开预估与正式报告，见 [T1](../ops/short-term/2026-09-20-impact-loop-t1.md)。项目追踪索引见下一行 | `docgov` |
-| trace-impact | 阶段回溯与影响闭环 | 五表追踪索引、影响报告、L1 文档修订、L2 阶段再打开、待复核软标记、对话修订提案 | done | deferred_enhancement（不挡首发） | [设计](../system-design/2026-09-20-stage-backtrack-and-impact-loop-design.md)；[Track T](../remediation/2026-09-20-capability-enablement-impact-plan.md)；[对话化报告](../test-reports/2026-09-21-trace-panel-to-chat-test-report.md)；[T 补强](../ops/short-term/2026-09-22-track-t-strengthen.md) | 已合入 dev。常驻「需求与影响」面板已退役。**2026-09-23 实测** DOCREV 路径 schema **63**；test=`rc-v1.1.0-beta.1` schema 61；main 本轮未晋升。阶段推进确认门禁仍在。不签 D7 对话 ADR | `trace-index` |
-| docgov-pi-narrative | PI change-report 叙事 | 只读消费 diff+lineage 的 PI 叙事；失败全量降级 fallback | partial | deferred_enhancement | [Round20](../test-reports/2026-09-14-document-revision-runtime-ui-test-report.md)；[go/no-go GO](../ops/research/2026-09-16-wave3-pu6-pu8-go-no-go.md)；[pu7](../ops/long-term/2026-09-16-pu7-pi-narrative-contract.md)；[W3 真 PI](../test-reports/2026-09-17-w3-pi-change-report-narrative-test-report.md)；[红线负例](../test-reports/2026-09-22-redline-evidence-pi-narrative-test-report.md) | flag 默认 **off**（红线不放量）。fallback 全量负例单测已补。pi-agent reasoning 路径已带 `--no-tools`。不打开开关 | `docgov` |
-| web-workbench | 前端工作台 | 三栏 + 块文档 + SSE；错误卡/`TaskRunCard` 竖向进度/busy；版本冲突信封；demo seed 默认关；终止 preview | done | non_blocker | [workbench](../test-reports/2026-09-08-three-column-workbench-and-block-document-test-report.md)；[双标签](../test-reports/assets/2026-09-15-conversation-intent-dual-tab/screenshots/tab-b-busy.png)；[demo](../test-reports/2026-09-16-demo-seed-pollution-test-report.md)；[B4](../test-reports/2026-09-16-frontend-gate-b4-test-report.md)（项目 6363）；[TaskRunCard](../test-reports/2026-09-21-taskrun-status-card-persistence-test-report.md) | **before**：空「缺口」却 partial → **after**：本行 done。其他 409 消费方信封复用另列 hardening backlog | `web` |
-| pi-runner | PI Runner / 配置链 | pi-agent + MiniMax + typed-result-v1 | done | non_blocker | [piagent](../test-reports/2026-09-13-codex-audit-p0-remediation-test-report.md)；[container-env](../test-reports/2026-09-13-container-env-configuration-test-report.md)；[typed-result](../test-reports/2026-09-15-pi-typed-result-v1-test-report.md) | 文档生成仍使用读写和搜索工具。`tool_profile=reasoning` argv 为 `--no-tools`。**2026-09-22 实测** pi-agent 已 bind-mount `pi-args.mjs` | `pi-agent` |
-| infra-envs | 三环境运维 | dev/test/main + 共享 KB；对话/业务库隔离 | done | non_blocker | [PROJECT.md](../../PROJECT.md) §4；[晋升报告](../test-reports/2026-09-22-dev-gate-and-test-promotion-test-report.md)；[DOCREV](../test-reports/2026-09-22-docrev-ui-rerun-test-report.md) | **2026-09-23 实测**：本地/共享 dev DOCREV 路径 schema **63**；test health schema **61**（`rc-v1.1.0-beta.1`）；main 本轮未晋升 | `infra` |
-| ci-e2e | CI / E2E | PR CI、PG 集成、治理 PG、已签真实 PI 门禁；**nightly** schedule/`workflow_dispatch` + infra/product 分类 receipt | done | 加固（阻止**下一次**晋升，不自动否定已发布） | [BUG-08](../test-reports/2026-09-16-ci-governance-pg-bug08-test-report.md)；[PI 三工作流](../test-reports/2026-09-16-pi-three-workflow-e2e-test-report.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)；[W1 green](../test-reports/2026-09-17-w1-ci-e2e-green-nightly-test-report.md) + [receipt `6e2476f0…`](../assets/promotion-receipts/6e2476f0f2e408e111fe06ca7c31a38294a340b3.json) | **before**：partial（FullNone product_fail / secrets 文案过时）→ **after**：secrets 已配；duplicate goose 00048 已清；FullNone+U8 nightly `verdict=pass` | `ci` |
-| 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 条例外清零 | 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) | **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` |
-| 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) | subscriber shadow 只计算 intended outcome。**live 未放量**；观察窗起点已登记。`FAV_DEGRADED_READ` 默认 false；禁止整支 merge | `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` | — |
+| 模块 | 声明范围 | 状态 | 发布关系 | 证据 | 剩余工作 / 关闭条件 | mutex |
+|------|----------|------|----------|------|---------------------|-------|
+| Agent worktree 治理自动化 | 主目录保护、任务 worktree、机器认领、候选集成、dev 部署与安全清理 | partial | non_blocker | [方案](../remediation/2026-09-21-agent-workflow-governance-plan.md)；[L1 验收](../test-reports/2026-09-21-agent-governance-test-report.md) | 本机 .locks/短租约、共享文档 CAS、提交/候选/环境门禁及安全 helper 已验；主仓 7e9317b8 已启用 init/hooks，拒绝无租约 env 操作。后台调度、完整业务部署恢复闭环、产品 PI 镜像交付、OS/跨机隔离与清理可见性仍待[后续](../ops/long-term/2026-09-21-agent-workflow-governance-automation.md) | `agent-workflow-governance` |
+| 意图识别 L1 | 18 类 Intent、三分支消解、写/只读分流、双标签 `DOC_BUSY`、intent 纯依赖边界 | done | non_blocker | [intent-recognition](../system-design/intent-recognition/)；[工作流作用域](../test-reports/2026-09-21-intent-workflow-scoping-test-report.md)；[审计](../audit/2026-09-13-conversation-intent-runtime-state.md)；[报告](../test-reports/2026-09-13-conversation-intent-runtime-state-test-report.md)；[双标签](../test-reports/assets/2026-09-15-conversation-intent-dual-tab/live.json)；[U1](../test-reports/2026-09-15-multi-intent-u1-contracts-test-report.md)–[U3](../test-reports/2026-09-15-multi-intent-u3-intentflow-pg-test-report.md) | **边界 before**：含 U9–U12 叙事混入 → **after**：U9–U12 迁至「多意图扩面」行。关闭：纯依赖边界回归即重开 | `intent` |
+| 多意图持久计划（U1–U8 基线） | app/intentflow 生命周期、HITL、默认 `legacy`、U1–U8 代码与安全基线 | partial | non_blocker（默认 legacy） | [设计](../system-design/2026-09-15-multi-intent-hitl-plan.md)；[U1](../test-reports/2026-09-15-multi-intent-u1-contracts-test-report.md)–[U8](../test-reports/2026-09-16-multi-intent-u8-task-generate-test-report.md)；[Wave2 真 PI](../test-reports/2026-09-16-wave2-real-pi-evidence-test-report.md)；[2026-09-20 复核](../ops/research/2026-09-20-capability-enablement-impact-research.md) | legacy 有限只读多意图仍默认启用；新持久计划生产组合根仍使用 Fake query owner，confirm 后缺可靠调度，typed 参数/目标版本不足。原 U1–U8 测试证据保留，但不足以证明升 `auto_read/confirm` 可用。关闭条件见[整改方案](../remediation/2026-09-20-capability-enablement-impact-plan.md) Foundation 1 与 Track I | `intent-plan` |
+| 多意图扩面（U9–U12） | U9 LLM 分段实验；U10 mutate；U11 docgov；U12 workflow/run-control | partial | deferred_enhancement | [设计](../system-design/2026-09-15-multi-intent-hitl-plan.md)；[go/no-go GO](../ops/research/2026-09-16-wave3-pu6-pu8-go-no-go.md)；[脚手架](../test-reports/2026-09-16-pu8-u9-u12-flags-test-report.md)；[U9](../test-reports/2026-09-17-w4-u9-segment-test-report.md)；[U10](../test-reports/2026-09-17-w4-u10-mutate-test-report.md)；[U11](../test-reports/2026-09-17-w4-u11-docgov-test-report.md)；[U12](../test-reports/2026-09-17-w4-u12-run-control-test-report.md)；[2026-09-20 复核](../ops/research/2026-09-20-capability-enablement-impact-research.md) | U9 proposer 已实现和注入但未进入生产聊天分段调用；提议请求已带 reasoning profile。U10–U12 当前为 dry-run/validated-only adapter。历史直接调用/PI 测试继续有效，不代表 live 接线。逐域实现和验收，禁止以 `full` 一次放量 | `intent-plan` |
+| 对话 / ctxmgr baseline | 多轮上下文、刷新/重登/重启恢复、授权同集正文与计数、U10 端口化停止扩面 | done | non_blocker | [multi-turn](../system-design/multi-turn-dialogue/)；[刷新审计](../audit/2026-09-13-chat-history-refresh-disappears.md)；[U10](../test-reports/2026-09-15-chatlog-contextasm-u10-test-report.md)；[门禁 B3](../test-reports/2026-09-16-chat-refresh-gate-test-report.md)（项目 6359） | **before**：语义摘要误标 D5 混入 → **after**：摘要迁「语义摘要 D3」；D7 数据治理独立。U10 停止扩面 | `chat` |
+| 语义摘要（D3） | 授权后可见集合上的语义摘要；shadow → 可选替换 deterministic | partial | deferred_enhancement | [chat-agent-p6-backlog](../backlog/chat-agent-p6-backlog.md)；[go/no-go GO](../ops/research/2026-09-16-wave3-pu6-pu8-go-no-go.md)；[pu6](../ops/long-term/2026-09-16-pu6-semantic-summary-contract.md)；[脚手架](../test-reports/2026-09-16-pu6-semantic-summary-test-report.md)；[W2 真 PI](../test-reports/2026-09-17-w2-semantic-summary-shadow-test-report.md)；[2026-09-20 复核](../ops/research/2026-09-20-capability-enablement-impact-research.md) | shadow 默认 off。`00058` 增加 `chat_summaries`，写入失败不再伪装成功；运行中的库仍是 schema 53。摘要请求已带 `tool_profile=reasoning`（argv 为 `--no-tools`），当前容器要等镜像或 dev 挂载更新后才生效。授权可见集 digest 仍空。`SEMANTIC_SUMMARY_REPLACE` 未接线。 | `chat` |
+| 对话数据治理（D7） | 留存/删除口径、库·备份·日志控制、敏感字段加密边界 | deferred | deferred_enhancement（违规则升 blocker） | [计划](../remediation/2026-09-16-feature-matrix-production-readiness-plan.md) Scope Boundaries；[收口 §7.1](../remediation/2026-09-16-partial-deferred-completion-plan.md)；[D7 ADR 草案](../adr/2026-09-17-d7-chat-data-retention.md)；[W7 盘点](../audit/2026-09-17-d7-data-inventory.md)；[报告](../test-reports/2026-09-17-w7-d7-inventory-test-report.md)；[D7-TRACE](../remediation/gap-matrix.md) | **after W7**：只读盘点完成（sessions/messages/KB/日志/备份/event）。**未发现**已确认基线违规，未写发布 blocker。口径仍 `pending-compliance-signoff`；禁止按 365/180/30 物理删除。追踪索引另定为 `record`（[设计 §9](../system-design/2026-09-20-stage-backtrack-and-impact-loop-design.md)），不把本行升 done | `chat` |
+| 智能体小队 | 角色-任务-工作区-黑板 | done | non_blocker | [agent-squad](../system-design/agent-squad/)；[test 2026-09-07](../test-reports/2026-09-07-dynamic-squad-planning-test-report.md) | 非关键步骤降级(A5/A6)属 backlog | `squad` |
+| 工作流治理 | 三正式工作流、设置页/DutyMode、动作级鉴权、真实 PI 三工作流 E2E、full/none 混合长链 | done | non_blocker | [三工作流整改](../remediation/2026-09-12-three-workflows-strict-governance-remediation.md)；[409/职责](../test-reports/2026-09-14-workflow-plan-409-frozen-and-optional-duties-test-report.md)；[鉴权](../test-reports/2026-09-14-governance-action-level-authz-test-report.md)；[PI E2E](../test-reports/2026-09-16-pi-three-workflow-e2e-test-report.md)；[Wave2 full/none](../test-reports/2026-09-16-wave2-real-pi-evidence-test-report.md) | full 跨用户审批 + none 免审批不阻塞已签。纯软件自举仍独立 planned | `workflow` |
+| 研发设计控制（rdev） | 医疗第 4 工作流：13×60 manifest/模板、`squad.rdev_doc.v1` kind 编排、main-completed 硬 precheck、StageKey 动态化；不含前端/真 PI/键名空间化 | partial | deferred_enhancement | [设计](../system-design/project-workflow/07-研发工作流rdev接入-设计与实施计划.md)；[short-term](../archive/ops/2026-09-17-rdev-workflow-integration.md)；[模板深度](../archive/ops/2026-09-17-rdev-template-depth.md)；[S0+S1 首批报告](../test-reports/2026-09-17-rdev-template-depth-test-report.md)；[S1 续批报告](../test-reports/2026-09-17-rdev-template-depth-s1-continued-test-report.md)；[写作规范](../system-design/project-workflow/08-rdev模板写作规范.md)；[backlog](../backlog/2026-09-17-rdev-phase2-backlog.md) | **P0+P1 done**。**模板深度 S0+S1 首批 + S1 续批 done**：60/60 模板已补强；真 PI 抽样 PASS（含 `rd_planning_review` + `rd_design_vv`，项目 6446）。剩余：S3 overlay 与 R2/R3 已接。P2 名称匹配、阶段折叠、批量审批已接。选中 rdev 时显示与服务端相同的 CDO 前置说明（`workflowPrerequisite.test.ts`）。P4 键名空间化已接：发布清单用 `bd_`/`pm_`/`tm_`/`sw_`，旧键仍走同一套步骤和模板，旧 doc_id 仍可查（`keyspace_test.go`）。P3 三样本已在 dev 真 PI 上跑过（项目 6533）：`rd_sw_plan` 规划期关闭；`rd_proposal` completed 但未对齐模板标题；`rd_planning_review` 当时质量门禁 score 20，是把同节后一张法规表算进问题行。门禁已只读第一张表；保存的终稿不再报「问题行缺少」。建议书标题仍未对齐模板。没有新的真 PI。见 [P3 报告](../test-reports/2026-09-19-rdev-p3-real-pi-test-report.md)。nightly 未扩成四工作流。 | `workflow-def` / `rdev-templates` |
+| 纯软件项目自举 | 软件项目创建、Bootstrap、Delivery、受控工程交接 | partial | deferred_enhancement（明确不挡首发） | [设计](../system-design/2026-09-14-software-project-bootstrap-workflow.md)；[ADR](../adr/2026-09-16-software-project-bootstrap-keys.md)；[L1 报告](../test-reports/2026-09-16-software-project-bootstrap-test-report.md)；[W5a](../test-reports/2026-09-17-w5a-software-bootstrap-ui-pi-test-report.md) | **before**：L1 + UI 仍克隆医疗模板。**after W5a**：catalog 驱动创建、软件不挂医疗 key、docs_only 真 PI 建议 delivery 且不自动激活。**SWBOOT-10 仍 stub**（W5b）；本行不升 done | `workflow-design` |
+| IAM / 鉴权 | 项目级 API 鉴权 + RBAC；会话/阶段授权 | done | 加固 | [v3 full inventory](../audit/authorization-matrix-v3-full.md)；[session 中断](../test-reports/2026-09-16-iam-route-inventory-test-report.md)；[fail-closed](../test-reports/2026-09-16-wave1-iam-fail-closed-test-report.md)；[410 策略](../audit/2026-09-16-bug11-410-retire-decision.md)；[R13](../audit/2026-09-16-r13-data-safety-checklist.md) | 全路由 inventory + session 中断负例 + 410 冻结 + R13 基线已签 | `authz` |
+| 文档治理 | 法定文档生命周期 + 租约 + 受控正文读取 | done | non_blocker | [docgov](../test-reports/2026-09-08-docgov-lifecycle-and-claiming-framework-test-report.md)；[正文 UI](../test-reports/2026-09-14-controlled-content-ui-acceptance.md)；[canonical hash](../remediation/2026-09-14-controlled-content-canonical-hash-remediation.md)；[键统一](../test-reports/2026-09-21-workflow-doc-key-unification-test-report.md) | 项目 143 只读；不终止。`doc_proj*` 同一发布键不能再并存 | `docgov` |
+| 文档版本 baseline | 账本、人工修订、确定性 diff+lineage、运行时 UI、负责人通知 | done | non_blocker | [管理](../test-reports/2026-09-13-document-revision-management-test-report.md)；[Round20 UI](../test-reports/2026-09-14-document-revision-runtime-ui-test-report.md)；[ADR](../adr/2026-09-13-document-version-boundary.md)；[proposed/authoritative](../ops/short-term/2026-09-20-proposed-authoritative-reports.md) | **before**：完整 PI narrative 混入 → **after**：迁「PI change-report 叙事」。fallback 报告是本行内显式行为，不是缺口。lineage GET 已按 URL 项目和文档可见性裁剪。test_manager 血缘的下游/上游版本改读文档版本，不再写死 1。Agent 候选报告为 `proposed`，正式提交才写 authoritative 后继并挂到版本；拒绝、替代后旧报告不能再出建议。人工修订、导入和聊天卡仍未分开预估与正式报告，见 [T1](../ops/short-term/2026-09-20-impact-loop-t1.md)。项目追踪索引见下一行 | `docgov` |
+| 阶段回溯与影响闭环 | 五表追踪索引、影响报告、L1 文档修订、L2 阶段再打开、待复核软标记、对话修订提案 | done | deferred_enhancement（不挡首发） | [设计](../system-design/2026-09-20-stage-backtrack-and-impact-loop-design.md)；[Track T](../remediation/2026-09-20-capability-enablement-impact-plan.md)；[对话化报告](../test-reports/2026-09-21-trace-panel-to-chat-test-report.md) | 已合入 dev。常驻「需求与影响」面板已退役，新待复核与下游影响改走已有项目会话。dev schema 59。test/main 未升。阶段推进确认门禁仍在。不签 D7 对话 ADR，不改 `production_ready` | `trace-index` |
+| PI change-report 叙事 | 只读消费 diff+lineage 的 PI 叙事；失败全量降级 fallback | partial | deferred_enhancement | [Round20](../test-reports/2026-09-14-document-revision-runtime-ui-test-report.md)；[go/no-go GO](../ops/research/2026-09-16-wave3-pu6-pu8-go-no-go.md)；[pu7](../ops/long-term/2026-09-16-pu7-pi-narrative-contract.md)；[脚手架](../test-reports/2026-09-16-pu7-pi-narrative-test-report.md)；[W3 真 PI](../test-reports/2026-09-17-w3-pi-change-report-narrative-test-report.md)；[2026-09-20 复核](../ops/research/2026-09-20-capability-enablement-impact-research.md)；[最小化输入](../ops/short-term/2026-09-20-pi-narrative-clipped-diff.md) | flag 默认 off。`facts.json` 含截断后的 hunk 前后文和影响说明，以及完整 hunk/impact 计数与省略数；摘要 digest 仍不含正文。叙事请求已带 `tool_profile=reasoning`。运行中的 runner 尚未切到 `--no-tools`。不打开开关 | `docgov` |
+| 前端工作台 | 三栏 + 块文档 + SSE；错误卡/`TaskRunCard` 竖向进度/busy；版本冲突信封；demo seed 默认关；终止 preview | done | non_blocker | [workbench](../test-reports/2026-09-08-three-column-workbench-and-block-document-test-report.md)；[双标签](../test-reports/assets/2026-09-15-conversation-intent-dual-tab/screenshots/tab-b-busy.png)；[demo](../test-reports/2026-09-16-demo-seed-pollution-test-report.md)；[B4](../test-reports/2026-09-16-frontend-gate-b4-test-report.md)（项目 6363）；[TaskRunCard](../test-reports/2026-09-21-taskrun-status-card-persistence-test-report.md) | **before**：空「缺口」却 partial → **after**：本行 done。其他 409 消费方信封复用另列 hardening backlog | `web` |
+| PI Runner / 配置链 | pi-agent + MiniMax + typed-result-v1 | done | non_blocker | [piagent](../test-reports/2026-09-13-codex-audit-p0-remediation-test-report.md)；[container-env](../test-reports/2026-09-13-container-env-configuration-test-report.md)；[typed-result](../test-reports/2026-09-15-pi-typed-result-v1-test-report.md) | 文档生成仍使用读写和搜索工具。`tool_profile=reasoning` 的 argv 是 `--no-tools` 且不加载搜索扩展；未知 profile 拒绝启动。dev 挂载了 `pi-args.mjs`，但本轮未重启容器 | `pi-agent` |
+| 三环境运维 | dev/test/main + 共享 KB；对话/业务库隔离 | done | non_blocker | [PROJECT.md](../../PROJECT.md) §4；CURRENT 环境快照 dev/test schema **48**、main **47** | — | `infra` |
+| CI / E2E | PR CI、PG 集成、治理 PG、已签真实 PI 门禁；**nightly** schedule/`workflow_dispatch` + infra/product 分类 receipt | done | 加固（阻止**下一次**晋升，不自动否定已发布） | [BUG-08](../test-reports/2026-09-16-ci-governance-pg-bug08-test-report.md)；[PI 三工作流](../test-reports/2026-09-16-pi-three-workflow-e2e-test-report.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)；[W1 green](../test-reports/2026-09-17-w1-ci-e2e-green-nightly-test-report.md) + [receipt `6e2476f0…`](../assets/promotion-receipts/6e2476f0f2e408e111fe06ca7c31a38294a340b3.json) | **before**：partial（FullNone product_fail / secrets 文案过时）→ **after**：secrets 已配；duplicate goose 00048 已清；FullNone+U8 nightly `verdict=pass` | `ci` |
+| 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` |
+| 可靠事件核心 | 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` |
+| 模块开发规范 | 窄端口、领域事件、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` |
+| 模块解耦批次 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) | 各批独立 short-term 与验收后另拆行升 `done`。G1 例外 2026-09-28 到期，到期前须迁走或书面延期。禁止把本行标成进行中来代表七批都已开工 | `module-decoupling-spec` |
+| 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)；[short-term](../ops/short-term/2026-09-17-w6-fav-subscriber-shadow.md) | **after W6**：subscriber `ObserveShadow` 只计算 intended outcome，不写副作用。仍**禁止**整支 merge；`FAV_DEGRADED_READ` 默认 false；**live 未放量**（staging→artifact→publication 各 ≥7 天观察窗） | `events` |
+| 系统管理台 | 全屏系统级管理视图（总览/KB/特性开关/系统设置/工作流/角色/用户/文档 8 分组）；`/api/v1/admin/system/*`；`system_settings` 白名单可写；吸收下线 AdminSettingsModal | 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)；commit `f1404d5`/`0eaca61`、merge `dc7c31e`（dev）；dev 冒烟 schema 49 + 四端点 + 写读回环 PASS | 二期：Playwright 实跑、细粒度 `system:*` 权限、设置审计日志、KB 运维动作、白名单项接消费方 | `web` + `sysadmin` |
+| 个人工程中控台（已移出） | 原本地只读看板与后来的 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` | — |
 
 ---
 
@@ -100,7 +100,7 @@
 
 ## 2026-09-17 首次加载性能专项
 
-首次加载与重启首访性能优化：**done（U1–U5/U7 关账口径；U6 明确不加索引）**。[审计](../audit/2026-09-17-initial-load-performance-audit.md) · [方案](../remediation/2026-09-17-initial-load-performance-plan.md) · [U2 报告](../test-reports/2026-09-17-initial-load-perf-u2-test-report.md) · [2026-09-22 收口](../test-reports/2026-09-22-initial-load-closeout-test-report.md)。U2：自托管字体 + br/gzip。U3：导出/预览/管理台/块编辑器/Mermaid/公式延迟加载；2026-09-22 对 schema 61 部署包 `index-CgkGfOP7.js` 浏览器瀑布 n=20（含慢网）确认首屏与首可操作路径无 katex/mermaid/docx。U4：登录只同步当前项目成员；会话列表代次合并。U5：`/auth/me` 复用已核用户。U6：不加索引（瓶颈曾是成员扇出，无慢 SQL 证据）。U1：慢网 + CPU 4x 各 n=20 — 10 Mbps 表单 p75 599 ms（预算 1500）、2 Mbps p75 1346 ms（预算 3000），未放宽阈值。U7：[重启报告](../test-reports/2026-09-19-initial-load-u7-restart-test-report.md) postgres+app→`/ready` 1.0–1.2 s；2026-09-22 补测 `/ready` 后冷导航表单可见 n=20，p75 75 ms，相对约 10 s 历史诊断达到 ≤5 s（50%）目标——**仅限该口径**，不宣称宿主机整机开机首访。macOS 用 `PLAYWRIGHT_CHANNEL=msedge`（沙箱无法拉 Playwright Chromium）。mutex `web + static-delivery` / `loading-performance-audit`。
+首次加载与重启首访性能优化：**partial**（U2 静态交付已验收；U3 只做了登录壳拆包，未关闭）。[审计](../audit/2026-09-17-initial-load-performance-audit.md) · [方案](../remediation/2026-09-17-initial-load-performance-plan.md) · [U2 报告](../test-reports/2026-09-17-initial-load-perf-u2-test-report.md)。U2：自托管字体 + br/gzip。U3 进展（`fix/audit-remainder-closeout`）：导出、预览、管理台、块编辑器、Mermaid/公式改为点击或出现时再加载。入口包 `index-*.js` 由 2.83 MB / br 626 KB 降到 737 kB / br 170 KB（`index-j0BIrjIR.js`，包内无 katex）。公式在气泡或正文里出现时才加载，富文本复制同样延后。U3 的浏览器资源瀑布还没测，本行不关。U5：`/auth/me` 复用本请求已核过的用户，不再第二次解析会话；会话与用户状态合成一次 JOIN。没有锁等待证据，所以不节流 `last_seen`。`TestAuthMe_LogoutNextRequestIs401`。U1、U6、U7 未做。U4 进展：登录不再按项目数拉成员名册，只同步当前项目；其他项目先种入当前用户以保持会话可见，完整名册在打开成员面板时取。会话列表不再因项目数组变化而重拉，迟到响应用代次丢弃，同一项目的在途成员请求合并。`src/data/initFanout.test.ts`。2026-09-19 浏览器证据（`e2e/initial-load-performance.spec.ts`，n=20，本仓 Vite `:3100` 代理 `:8080`）：每次登录成员项目数 1、会话列表 GET 1，匿名与登录后资源路径均无 katex/mermaid/docx。同一探针在重建后的 `:8080`（`index-DOO0-Yh7.js`，schema 53，n=5）成员项目 1、会话列表 GET 1，匿名 JS 传输 172,417 B，首屏路径无 katex/mermaid/docx。重建前旧包 n=1 曾是 704/30。慢网 n=3、CPU 4 倍：10 Mbps 表单可见 558–604 ms，2 Mbps 1279–1296 ms，样本不足 20，U1 不关。U6 不加索引：测到的瓶颈是已消失的成员扇出，没有慢 SQL 证据。U7 已测未关：[报告](../test-reports/2026-09-19-initial-load-u7-restart-test-report.md)。Vite 监听约 0.3 s；314 个模块冷/热 1.45/1.11 s，不是历史十几秒。postgres+app 到 `/ready` 1.0–1.2 s。无头浏览器缺系统库，登录表单可见未测；不宣称较基线下降 50%。mutex `web + static-delivery`（U2 done）/ `loading-performance-audit`。
 
 ## 2026-09-17 文档编制人兼任方案
 

.doc/system-design/2026-09-22-generic-module-contract-standard.md

@@ -0,0 +1,386 @@
+---
+title: "通用模块化架构与通信契约规范"
+type: docs
+date: 2026-09-22
+standard_id: MCS
+version: "0.1"
+policy_state: proposed
+---
+
+# 通用模块化架构与通信契约规范
+
+本规范适用于新建或渐进改造的软件系统，独立于具体项目、语言、框架、云厂商和消息产品。目标是让功能变更、故障和数据责任尽可能局限在明确范围内，同时让模块能够独立测试、替换和按需部署。
+
+这是待审核的通用规范草案。文中的 MUST 表示采纳本规范后必须满足，SHOULD 表示偏离时须有记录，MAY 表示按需选用。规范存在不代表检查工具或运行保证已经实现。
+
+## 1. 基本决策
+
+**严格划分职责与契约，按故障风险选择部署边界。** 默认从契约明确的模块化单体起步；重计算、不可信插件、独立扩缩容或必须隔离崩溃的模块使用独立进程或服务。若产品要求任何一个模块崩溃都不能终止其他模块，必须选进程隔离档，不能以进程内接口验收。
+
+HTTP、RPC 是调用协议；Socket 是通信基础；IPC 是进程间通信方式，三者不是同一层次的互斥选项。gRPC 可以运行在 TCP 或 Unix Domain Socket 上。单独“换成 HTTP”不会消除数据、时序和业务语义耦合。
+
+### 1.1 名词与粒度
+
+| 概念 | 定义 | 划分依据 |
+|---|---|---|
+| 模块 | 拥有一组业务不变量、公开契约和内部实现的职责单元 | 数据所有权、变化原因、规则归属 |
+| 功能 | 用户能够完成的一件事 | 使用目标与验收结果 |
+| 用例 | 完成一个业务动作的应用入口 | 权限、输入、原子性、输出 |
+| 聚合 | 同一次提交必须维护不变量的数据集合 | 事务一致性要求 |
+| 服务/进程 | 可独立运行和部署的单位 | 故障、资源、信任和运维边界 |
+| 适配器 | 将公开语义映射到具体存储或传输的实现 | HTTP、RPC、进程内端口、数据库等 |
+| 总线 | 提供命令投递或事件分发的基础设施 | 投递语义、背压、资源隔离 |
+| 编排器 | 根据持久业务状态协调多个用例 | 流程、超时、重试、补偿 |
+
+一个功能可以组合多个模块；一个模块可以支撑多个功能。SHOULD 按业务能力划分，不能“一张表一个模块”“一个按钮一个服务”。修改一项领域规则必须同时修改多个模块，通常说明边界或公开契约不合理。
+
+### 1.2 隔离档位
+
+| 档位 | 实现 | 可提供 | 仍共享的风险 |
+|---|---|---|---|
+| L1 逻辑隔离 | 同进程独立包、显式端口、所有权检查 | 编译依赖、责任与测试隔离 | panic/OOM、线程池、地址空间、部署 |
+| L2 进程隔离 | 本机子进程/容器、IPC/HTTP/RPC、独立资源配额 | 进程崩溃与部分资源隔离 | 主机、磁盘、网络、数据库 |
+| L3 服务隔离 | 独立部署、身份、容量、存储权限 | 独立发布与扩缩容 | 共享基础设施、链路依赖 |
+| L4 故障域隔离 | 独立基础设施/区域及复制恢复设计 | 主机/区域级隔离 | 跨域一致性、成本与恢复复杂性 |
+
+MCS-01：每个模块 MUST 声明目标隔离档位、可承受故障、依赖失效行为及验收方法。不能把 L1 宣称为 L2，也不能承诺绝对“问题不扩散”。
+
+不可信代码除独立进程与资源配额外，MUST 使用最小权限执行身份、明确的文件与网络访问限制，不继承宿主秘密。普通同用户子进程只能作为崩溃隔离手段，不能作为信任隔离验收；具体沙箱/容器权限以负例验证。
+
+---
+
+## 2. 模块边界与开发规则
+
+MCS-02：模块 MUST 有唯一责任 owner、内部模型、公开契约、数据清单和不变量。共享代码只能承载稳定且无业务行为的基础类型，不能形成公共万能 Store/Manager。
+
+MCS-03：跨模块调用 MUST 经过公开契约，禁止引用对方内部实现、ORM 实体、数据库事务对象、可变内存指针或内部文件路径。内部包依赖图 MUST 无环；业务流程允许回调和迭代，但须在编排状态机中显式建模。
+
+MCS-04：同一业务动作的 Web、CLI、消息消费、定时任务和 Agent 工具入口 MUST 汇入相同应用用例，或通过契约测试证明语义一致。各入口不能各自复制授权、状态变更、事件发送。
+
+MCS-05：模块外部可见契约的语义由提供方负责；进程内调用方 MAY 定义更窄的需求接口，由适配器映射。独立共享契约包与服务 IDL 是发布边界，不能绑定实现包。共享词汇变化也需要兼容审查。
+
+建议模块内部结构：公开契约、应用用例、领域规则、存储/传输适配器、测试。小模块 MAY 合并文件，层数和目录数量不是验收指标。组合根只负责装配，不藏业务规则；领域层不创建全局客户端或定位服务。
+
+### 2.1 模块设计卡
+
+设计前 MUST 填写以下内容；不适用项写原因：
+
+| 项目 | 必需内容 |
+|---|---|
+| 身份 | module_id、owner、目的、非职责、隔离档位 |
+| 数据 | 唯一写入表/对象/文件命名空间、投影、保留期 |
+| 不变量 | 哪些状态必须一起提交、竞争对象、合法状态转换 |
+| 入口 | 命令、查询、事件订阅、流；调用者与权限 |
+| 输出 | 结果、事件、错误、外部副作用 |
+| 依赖 | 必需/可选依赖、故障降级、允许依赖方向 |
+| 并发 | 聚合键、版本比较、唯一约束、锁顺序、并发配额 |
+| 生命周期 | 启动、readiness、排空、取消、恢复、版本升级 |
+| 验收 | 契约测试、故障注入、资源隔离与恢复证据 |
+
+### 2.2 功能设计卡与前端边界
+
+跨模块功能 SHOULD 另有一张功能设计卡：用户目标、入口、参与模块及 owner、命令/查询/事件时序、授权决策点、原子提交范围、处理中/部分失败/完成的可见结果、补偿与恢复、端到端验收。卡片引用各模块契约，不复制第二套业务规则。
+
+前端也按功能 owner 管理状态，对外提供查询、命令与事件，避免把可变对象和任意 setter 传遍功能模块。浏览器内模块可以使用本地类型化接口，不必人为绕经网络；缓存刷新、取消、流重连及过期结果处理属于功能契约。
+
+---
+
+## 3. 通信架构与统一封装
+
+统一的是业务契约和治理策略，传输适配器按使用场景提供。不能把所有调用改成字符串 topic 加任意 JSON，从而失去类型、授权和依赖检查。
+
+```mermaid
+flowchart TB
+  Entry["Web / CLI / Agent / 定时器"] --> Adapter["入口适配与认证"]
+  Adapter --> Usecase["应用用例或持久流程编排"]
+  Usecase --> PortA["模块 A 公开契约"]
+  Usecase --> PortB["模块 B 公开契约"]
+  PortA --> A["模块 A 内部实现"]
+  PortB --> B["模块 B 内部实现"]
+  A --> StoreA["A 所有的数据与 Outbox"]
+  B --> StoreB["B 所有的数据与 Inbox"]
+  StoreA --> Relay["可靠投递器"]
+  Relay --> Bus["事件总线"]
+  Bus --> Sub["独立消费者队列与执行预算"]
+  Sub --> PortB
+  Policy["契约目录 / 身份 / 追踪 / 配额"] -.-> Adapter
+  Policy -.-> Relay
+  Policy -.-> Sub
+```
+
+### 3.1 总线与调度的分工
+
+MCS-06：平台 MUST 区分四类语义，允许共用基础代码，不得混用成功含义：
+
+| 机制 | 含义与接收方 | 成功定义 | 必需约束 |
+|---|---|---|---|
+| Query 调用 | 一个提供方返回信息 | 得到满足一致性要求的结果 | 超时、读权限、数据新鲜度 |
+| Command 调用/投递 | 一个逻辑 owner 接受业务动作，可多副本执行 | 同步 committed，或异步 accepted + operation_id | 持久性、幂等、结果查询 |
+| Event 分发 | 已发生事实，零到多个订阅者 | 发布持久化不等于消费者完成 | outbox、每订阅者独立进度 |
+| Stream | 有序交互或增量结果 | 通道建立不等于业务提交 | 游标、断线恢复、背压 |
+
+MCS-07：总线 MUST 只负责技术治理：校验、路由、投递、租约、确认、重试预算、可观测性。它不拥有业务表、不决定业务状态、不持业务全局锁。业务编排器通过契约发命令、消费事实，持久保存流程进度。
+
+“所有模块必须经过统一通信治理”可以实现为每个进程内的 SDK/代理与分布式 broker；不要求所有 HTTP 查询绕经单个中央服务。控制面故障时，已验证的契约与路由快照可按明确有效期继续使用；权限不可凭过期缓存无限放行。
+
+### 3.2 传输选择
+
+| 场景 | 首选 | 使用前必须解决 |
+|---|---|---|
+| 同进程、同发布、低风险 | 窄端口与依赖注入 | 不共享可变内部对象；不冒充崩溃隔离 |
+| 浏览器/第三方调用 | HTTP + OpenAPI | 身份、错误、分页、幂等、版本 |
+| 服务间强类型调用 | gRPC + Protobuf | deadline、兼容、健康、重试预算 |
+| 同主机进程隔离 | HTTP/gRPC over UDS 或成熟 IPC | OS 权限、消息边界、断连与重启 |
+| 浏览器增量单向通知 | SSE | cursor、重连、事件保留与重同步 |
+| 双向低延迟交互 | WebSocket | 身份续期、帧限制、心跳、序列/确认 |
+| 可延迟、可重放副作用 | 持久消息队列/事件总线 | ack、重复、顺序、死信、重放权限 |
+
+不建议第一版自造裸 TCP 帧协议，也不同时实现全部传输。HTTP/gRPC 与事件协议各维护一个权威描述，生成代码只是投影，不能让多套定义互相漂移。
+
+gRPC 未设置 deadline 可能无限等待；因此所有跨进程调用必须设置并传递剩余预算，不能每一跳重置完整超时。[gRPC deadline 官方说明](https://grpc.io/docs/guides/deadlines/)
+
+### 3.3 可复用平台包
+
+| 包/能力 | 负责 | 明确不负责 |
+|---|---|---|
+| contract-core | 元数据、错误类别、契约版本、兼容检查 | 业务 DTO 全部塞入公共包 |
+| transport-* | 编解码、连接、身份、deadline、trace | 状态机、表写入 |
+| invocation-policy | 配额、并发上限、熔断、有限重试 | 掩盖永久错误、无限重试 |
+| delivery | outbox、消费状态、租约、DLQ、重放管理 | 通用业务补偿 |
+| consistency | 幂等收据、CAS 辅助、事务集成扩展点 | 跨库“万能事务” |
+| lifecycle | readiness、drain、取消、恢复钩子 | 强行吞掉 OOM 或任意运行时错误 |
+| conformance | 契约兼容、架构依赖、故障测试套件 | 用接口 mock 代替真实投递验收 |
+
+平台核心不得 import 业务模块。通过显式注册及生成的类型化客户端暴露能力，避免全局 service locator。每种适配器发布能力清单，缺少持久投递能力的内存实现只能用于明确的临时通知或测试。
+
+---
+
+## 4. 接口契约
+
+MCS-08：契约 MUST 同时包含结构、语义、权限、一致性和失败行为，不能只有接口名和字段。
+
+### 4.1 每个操作的必填项
+
+| 维度 | 内容 |
+|---|---|
+| 标识与版本 | module、operation、schema version、owner、兼容窗口 |
+| 请求 | 字段类型、长度/大小上限、必填、缺省/null/未知枚举策略 |
+| 身份 | caller_service、actor/delegation、tenant、resource/action、信任来源 |
+| 前置条件 | 资源状态、expected_version、前置业务约束 |
+| 执行语义 | command/query/event/stream、同步/异步、幂等范围 |
+| 一致性 | 原子提交范围、读取陈旧度、读己之写条件 |
+| 输出 | committed/accepted、operation_id、结果引用、版本 |
+| 错误 | 稳定 code、可重试分类、冲突、结果未知、权限隐藏规则 |
+| 预算 | deadline、排队时间、最大重试、载荷、并发/速率 |
+| 事件 | 成功后产生哪些事实、订阅语义、顺序与重放 |
+| 演进与验收 | 支持版本、破坏性检测、测试、弃用日期、监控 |
+
+HTTP 可用 OpenAPI 描述请求响应，异步通道可用 AsyncAPI 描述消息与操作；它们不足以独自表达全部事务、幂等和授权规则，须附语义契约。[OpenAPI 3.1.1](https://spec.openapis.org/oas/v3.1.1.html)、[AsyncAPI 3.0.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0)
+
+### 4.2 通用元数据
+
+请求元数据包含 request_id、traceparent、operation、contract_version、remaining_budget、idempotency_key（适用时）、expected_version（适用时）。认证身份与租户由可信入口验证建立，不因请求体有 user_id 就信任它。重试沿用业务幂等键，每次传输 attempt_id 不同。
+
+响应明确区分：
+
+- committed：契约规定的持久状态已提交。
+- accepted：工作已可靠入队，返回可授权查询的 operation_id。
+- rejected：已确定未执行的业务或权限拒绝。
+- unknown：超时/断连后无法判断提交是否发生，必须查询或同键重试。
+- partial：只允许在契约明确哪些子结果成功、如何恢复时使用。
+
+错误至少包含稳定 code、安全 message、request_id，可选 operation_id、retry_after 和公开 details。禁止返回 SQL、堆栈、内部路径或秘密。HTTP/RPC 状态映射集中维护，业务不得靠文本匹配。
+
+### 4.3 事件信封
+
+MCS-09：事件 MUST 有唯一事件身份、来源、事实名称、payload schema、发生时间、租户/环境、聚合标识、correlation/causation、内容摘要。认证上下文只携带最小审计引用，不在消息里长期存放用户 bearer token。
+
+采用 CloudEvents 时，specversion 指信封标准版本；业务 schema 使用 dataschema 或明确的扩展字段，两者不能混为一谈。使用 (source, id) 标识不同事实；同一事实的投递重试不生成新事件身份。[CloudEvents 1.0.2](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md)
+
+payload 大小上限、字段可见性、保留期写入契约。大内容用不可变对象引用与摘要，引用必须在消费和重放窗口内可取；写入对象再提交 DB 指针时要管理孤儿对象，不能声称跨对象存储与数据库原子提交。
+
+---
+
+## 5. 数据完整性与并发
+
+MCS-10：每张业务表、对象命名空间和状态源 MUST 只有一个逻辑写入 owner。owner 的多个副本可以并行写，唯一约束/版本校验保证一致性。其他模块通过命令修改，不能“方便起见”直连写表。跨模块读取优先查询契约或订阅生成的只读投影，临时跨表读取须登记耦合与退出条件。
+
+共用数据库实例 MAY，共用超级用户写权限 SHOULD NOT。L1 至少用静态所有权检查；L2/L3 SHOULD 加数据库 role/schema ACL。迁移由 owner 维护，跨模块外键、视图和级联删除必须显式登记。
+
+### 5.1 事务边界
+
+MCS-11：业务状态与对应 outbox MUST 在同一原子事务中提交，或使用能证明同等保证的事务日志/CDC 方案。先写 DB 再直接发消息会留下双写失败窗口。[事务 outbox 模式](https://docs.aws.amazon.com/en_en/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html)
+
+同数据库、同应用边界可由用例管理明确的 Unit of Work，各数据 owner 执行自己的写操作。业务调用方不接触底层事务对象。跨模块共享事务是有意的一致性耦合，必须记录；不能承诺以后可零成本换成 RPC。
+
+跨进程、跨库不能传播本地 Tx 伪造原子性。跨域流程采用持久编排/Saga、预留资源、超时释放与补偿；补偿是新的业务动作，不等于撤销现实世界已发生的一切。必须定义中间态、对用户的可见性和需要人工处理的终态。
+
+### 5.2 约束与锁选型
+
+| 问题 | 首选机制 | 注意事项 |
+|---|---|---|
+| 重复创建/同业务号 | 唯一约束 + 幂等收据 | 单纯先查后写存在竞争 |
+| 同一聚合并发变更 | version/CAS + 条件更新 | 0 行更新是冲突，不能静默覆盖 |
+| 必须串行维护多行不变量 | 短事务 + 行锁/适当隔离级别 | 固定锁顺序、死锁/序列化失败有界重试 |
+| 队列任务竞争领取 | 原子 claim + lease | 领取成功不等于副作用完成 |
+| 长任务排他 | 租约 + token/epoch + 资源端拒旧写 | TTL 锁本身无法阻止暂停后复活的旧 worker |
+| 进程内缓存 | 互斥/并发容器 | 不能保证多进程一致性 |
+
+MCS-12：任何 DB 锁/事务不得跨越 LLM、HTTP、长文件 IO 或等待用户。计算在事务外进行，提交时重新验证权限、状态和 expected_version。
+
+SKIP LOCKED 适合竞争领取队列，返回的是不完整视图，不能把它当普通一致性查询或完整串行化证明。[PostgreSQL SELECT](https://www.postgresql.org/docs/current/sql-select.html)
+
+### 5.3 端到端幂等
+
+MCS-13：幂等必须由实际副作用 owner 保证；总线去重不能代替业务幂等。
+
+- 幂等作用域为 tenant + operation + caller namespace + key；记录规范化请求摘要、执行状态、结果/结果引用和期限。
+- 同键同摘要：返回已有结果，或返回正在执行的 operation；不得并行再执行。
+- 同键不同摘要：返回明确冲突，不能覆写收据或当新请求。
+- 本地 DB 效果与成功收据同事务；ack 在事务提交之后。
+- 外部 API/发信/扣费：使用对方幂等能力或业务唯一号，并有查询对账；无法可靠去重的副作用须声明风险与人工恢复路径。
+- 保留期必须覆盖客户端重试、队列积压、故障恢复与可重放窗口；过期后拒绝旧键、保留业务永久唯一约束或采用明确的新请求规则。
+
+进程执行后崩溃、响应丢失、消息重复到达均须测试。“至少一次投递 + 幂等可见效果”是默认承诺；不能概括为跨所有外部系统 exactly once。幂等键复用与迟到重试的语义必须明确。[AWS 幂等 API 设计](https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/)
+
+---
+
+## 6. 可靠总线与持久调度
+
+### 6.1 交付状态与恢复
+
+MCS-14：每个订阅者维护独立 delivery，使用有界重试、死信/隔离和可审计重放。状态至少表达 pending、leased、retry_wait、succeeded、dead/quarantined。
+
+```mermaid
+stateDiagram-v2
+  [*] --> pending
+  pending --> leased: 原子领取
+  retry_wait --> leased: 到期领取
+  leased --> succeeded: 效果及收据提交后确认
+  leased --> retry_wait: 瞬时错误或租约过期
+  leased --> quarantined: 非法来源或不兼容契约
+  leased --> dead: 永久业务失败或重试耗尽
+  dead --> pending: 审批后重放并保留事件身份
+  quarantined --> pending: 修正条件后受控重放
+```
+
+只领取执行容量内的消息；若预取多条，等待中的租约也必须续期或计入排队预算。租约续期失败后停止新副作用；ack/续租/结果写入须检查当前 owner + token。随机 token 可以做“当前持有者相等检查”，只有资源端能比较并拒绝旧代次的单调 epoch 才可宣称有序 fencing。
+
+处理失败分类：网络波动等可重试；权限/租户/来源/schema 不符隔离；确定的业务拒绝终结；依赖关闭暂停或延后；未知外部结果先查询对账。重放必须重新鉴权，保留原事件身份与新的 replay_id，不能清掉收据来强迫重复副作用。
+
+### 6.2 顺序与并行
+
+MCS-15：顺序范围 MUST 写明 tenant/environment + consumer + aggregate，默认只要求聚合内所需顺序，聚合间并行，不强制全局串行。
+
+领域版本、事件序号和全局表 ID 各有用途，不能互换。订阅者收到的事件可能只是领域事件子集，序号有空洞不必然代表丢消息。
+
+| 业务需要 | 契约与策略 |
+|---|---|
+| 可交换/幂等副作用 | 不强制排序，靠收据去重 |
+| 用最新完整快照更新投影 | 比较源版本，允许首次高版本 bootstrap，拒绝回退 |
+| 必须按顺序应用增量 | 独立、无缺口且订阅语义一致的 sequence；定义首序号与恢复 |
+| 缺号、毒消息 | 只阻塞相应聚合/订阅者，告警并从权威源补齐或重建 |
+
+不得直接用 aggregate_version == checkpoint + 1 判断所有事件可执行。选择连续 sequence 时须处理过滤事件、事务回滚、补偿、新订阅、迁移与归档，不能以数据库 sequence 自增就假定无缺口。
+
+### 6.3 调度器
+
+MCS-16：长流程的任务接受、状态和恢复 MUST 持久化；定时器到期等价于有幂等身份的命令投递，不能只靠进程内 timer。
+
+业务流程状态至少包含 operation_id、输入快照、当前步骤、各步骤幂等键、attempt、lease/epoch、deadline、结果引用、补偿进度、最后错误。依赖 DAG 与业务循环分开表达。优先级、租户公平性、配额、排队上限和取消行为必须声明。
+
+取消是请求，不保证已提交副作用消失。结果未知先对账；补偿和人工介入有独立权限及审计。流程定义升级后，运行中实例继续绑定原版本，除非存在明确迁移规则。
+
+### 6.4 端到端交付顺序
+
+```mermaid
+sequenceDiagram
+  participant C as 调用方
+  participant A as 模块A
+  participant D as A数据库
+  participant B as 事件总线
+  participant W as 模块B消费者
+  participant E as B数据库
+  C->>A: 命令 + 幂等键 + expected_version
+  A->>D: 同事务写业务、收据、outbox
+  D-->>A: commit
+  A-->>C: committed 或 operation_id
+  D->>B: relay 发送，允许重复
+  B->>W: 独立订阅投递
+  W->>E: 同事务校验收据并写效果
+  E-->>W: commit
+  W-->>B: ack
+```
+
+上图只保证各自数据库内原子性；relay 到 broker、消费者到外部服务的窗口分别依靠去重、查询和恢复契约处理。
+
+---
+
+## 7. 故障隔离、安全与可观测性
+
+MCS-17：每个消费者/依赖/租户 MUST 有有界执行预算，至少包括并发、队列长度、载荷、处理时限与重试总预算。独立队列、worker pool、连接池配额用于防止一个慢模块耗尽全部资源。仅捕获异常不构成隔离。
+
+重试由一层统一协调，避免客户端、服务、broker 各重试三次形成放大。只对契约允许的错误重试，采用退避和抖动；非幂等写禁止盲目重试或并发 hedging。gRPC 的传输重试策略也需纳入总预算。[gRPC retry](https://grpc.io/docs/guides/retry/)
+
+MCS-18：跨信任边界 MUST 验证服务身份、调用权限、租户和资源权限；同机 IPC 也不能默认可信。用户委托与服务自身权限分开；消费者按契约确定“重验当前权限”或“执行已批准且未撤销的操作凭证”，不得直接相信事件里的 actor_id。总线 publish/subscribe、死信读取、重放和流程补偿分别授权。
+
+MCS-19：日志与 trace MUST 能关联 request、operation、event、delivery、aggregate 和 attempt；指标至少含错误/延迟、outbox 最老年龄、消费者 lag、重试/死信、幂等冲突、lease 丢失、隔离队列深度。高基数租户/事件 ID 放日志或 trace，避免无界指标标签。
+
+MCS-20：readiness 只报告该进程能否履行职责，liveness 检查是否存活。非核心下游故障不应触发全系统重启风暴。停机先停止接受/领取，排空到预算，之后安全交还租约；崩溃恢复通过持久状态和收据继续。
+
+### 7.1 容量与故障目标
+
+每个系统必须填写负载基线、p95/p99、错误预算、排队/恢复时限、RPO/RTO 和故障注入标准，不能照抄统一常数。采用真实容量测试验证：入站速率、平均处理时间和目标利用率决定并发预算；最老消息年龄和排队尾延迟比单纯队列长度更有意义。
+
+必须识别总线、数据库和公共认证作为共享故障点。是否集群、高可用和跨区由 SLO 决定；总线高可用不能替代数据库备份恢复。数据库提交的耐久保证以实际复制与故障转移配置为准。
+
+---
+
+## 8. 演进、测试和可执行门禁
+
+MCS-21：契约 MUST 有兼容矩阵和弃用窗口；新增可选字段须验证旧消费者未知字段策略，枚举新增也可能破坏客户端。删除字段、改变含义/单位/权限/错误语义属于破坏性变更。采用 expand → 双版本兼容 → 消费者迁移 → contract，回滚窗口内保留兼容能力。
+
+每个模块的公开契约、数据库迁移、事件 schema、SDK 版本分别跟踪。新旧版本混跑必须验证，不通过一次“全系统同时升级”掩盖运行耦合。
+
+### 8.1 合并与发布证据
+
+边界、契约和权限是共同基线；数据库、可靠事件、外部副作用、租约、多租户及跨进程测试按系统实际声明的能力触发。设计卡/manifest MUST 记录适用能力和不适用理由；不能因为某项测试需要设施而给本不需要该设施的模块强加架构。
+
+门禁区分 PASS、FAIL、SKIP（适用但未执行）与 N/A（经核对不适用）。N/A 不等于 SKIP，不需要作为到期违规例外；若业务需要该能力但尚未实现，则不能标 N/A。下表和 §8.2 均遵循此规则，参考平台仍须覆盖其声明完整组合中的全部适用场景。
+
+| 门禁 | 必需证据 | 不能替代它的证据 |
+|---|---|---|
+| 边界 | 依赖图、无环、无内部包越界、数据所有权 | 目录拆分、文件行数 |
+| 契约 | schema lint、破坏性 diff、提供者/消费者兼容测试 | 仅生成代码成功 |
+| 正确性 | 公开用例不变量、权限负例、CAS/唯一约束 | handler mock |
+| 一致性 | 真数据库并发、回滚、收据和 outbox 同事务 | 单进程 mutex 单测 |
+| 交付 | 真传输的丢 ack、重复、乱序、断网、重启恢复 | 内存 bus |
+| 隔离 | 慢/崩溃消费者下其他模块仍达到预算 | 一个 handler 返回 error |
+| 运维 | 新旧版本混跑、drain、DLQ 重放、备份恢复 | health 为 200 |
+
+MCS-22：例外 MUST 有 owner、原因、范围、到期与移除计划。门禁状态明确为 proposed/manual/enforced，只有工具接入及正负例验证后才能写 enforced。初始遗留问题可按精确基线逐项收敛，不得无限扩大 allowlist 或移动基线掩盖新增耦合。
+
+### 8.2 最小验收场景集
+
+1. 同一幂等键 100 个并发请求，只有一个业务效果；同键异载荷明确冲突。
+2. 两个不同键竞争同一 expected_version，只有一个成功，其余返回冲突。
+3. 业务写失败时 outbox 不产生；提交后 relay 退出，恢复后消息仍能交付。
+4. 消费者效果提交后 ack 丢失，重投不重复效果。
+5. 外部调用成功但本地未知，查询/同键恢复后结果一致。
+6. worker 租约过期后旧执行者恢复，资源端拒绝旧写。
+7. 首条事件为高领域版本、过滤造成版本空洞、乱序与重复，按所选顺序契约处理。
+8. 一个消费者持续超时/毒消息，其余消费者和聚合仍满足各自预算。
+9. 跨租户命令、伪造事件来源、越权订阅/重放均拒绝。
+10. 队列饱和返回过载或明确 accepted；不得已经丢弃却返回成功。
+11. 新旧契约版本混跑、未知枚举、退出排空与断线重连符合声明。
+12. 备份恢复后收据、outbox、投影/业务状态保持可对账，不自动重新执行不可逆副作用。
+
+---
+
+## 9. 采用方法
+
+新项目先完成模块设计卡、契约样例、数据所有权图和关键故障目标，再写业务实现。优先交付一个真实端到端能力：同步命令 → 原子提交 → 可靠事件 → 幂等消费者 → 重启恢复。
+
+第一版平台只实现一个主语言 SDK、进程内适配器、一种跨进程传输和一种持久事件实现。需要多语言时，复用 IDL 与一致性测试向量，各语言实现相同语义，而非共享同一份业务代码。
+
+每次新增模块都回答三个问题：调用者是否需要理解内部实现；出故障能否只定位/替换该模块；验证契约时是否必须启动全部系统。答案若长期不理想，应调整职责和接口，而不是继续增加通信中间层。

.doc/system-design/module-boundaries.yaml

@@ -6,8 +6,21 @@
 
 imports:
   agent:
+    - agentx
+    - agentx/llm
+    - agentx/session
+    - agentx/tools
     - config
     - workspace
+  agentx:
+    - agentx/llm
+    - agentx/session
+    - agentx/tools
+  agentx/abtest: []
+  agentx/llm: []
+  agentx/session:
+    - agentx/llm
+  agentx/tools: []
   auth:
     - config
   authz:
@@ -55,6 +68,7 @@ imports:
     - ctxmgr
     - docgov
     - intent
+    - jevdecide
     - kb
     - maturity
     - projectinstance
@@ -93,6 +107,7 @@ imports:
     - events
     - freedoc
     - intent
+    - jevdecide
     - kb
     - notification
     - observability
@@ -172,6 +187,7 @@ imports:
     - squad
     - workflowdef
     - workflowscope
+  jevdecide: []
   kb:
     - config
   materialindex:
@@ -455,6 +471,7 @@ event_consumers:
   outbox.notify:
     - app/docnotify
     - notification
+    - server
   document.agent_candidate_ready:
     - notify
   document.agent_version_committed:

.doc/test-reports/2026-09-14-fav-migration-corpus-drill-test-report.md

@@ -0,0 +1,33 @@
+# FAV 演练：migration corpus（独立报告）
+
+## 一、 测试背景 (Background)
+
+Migration corpus / 蓝绿换库是 FAV 的 sibling，不在本计划实现。V6 只能引用其 PASS，不能用 FAV 覆盖率手改数字绕过。
+
+## 二、 测试目标 (Test Objectives)
+
+- `PreflightDestroy(..., corpusOK=false)` fail-closed。
+- 回填只枚举账本/完成 turn，禁止 workspace。
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+
+`TestCoverageGateFailClosed` + `TestBackfillIdempotentNoWorkspace`。无 corpus 目录实跑。
+
+## 四、 预期结果 (Expected Results)
+
+corpus 未 PASS → destroy 拒绝；缺证据行 → quarantine；重跑 Created 不增加。
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+
+- **测试输入**: `PreflightDestroy(..., backupOK=true, corpusOK=false)` 逻辑分支；`Backfill` 重复行与 missing evidence
+- **实际输出**: destroy 拒绝；首次 Created=1 Reused=1；rerun Reused；missing → Quarantine=1
+- **评价判定**: PASS（门禁与回填契约）；**未做** live corpus 晋升
+- **性能与耗时**: <5ms
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+
+`TestBackfillIdempotentNoWorkspace` PASS；`TestCoverageGateFailClosed` PASS。
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+
+`scripts/artifact-vault-preflight.sh` 默认 `CORPUS_OK=false`，避免手改 coverage 后 teardown。corpus 作业 PASS 后才能把该旗标打开。

.doc/test-reports/2026-09-14-fav-postgres-restore-drill-test-report.md

@@ -0,0 +1,33 @@
+# FAV 演练：PostgreSQL restore（独立报告）
+
+## 一、 测试背景 (Background)
+
+FAV 不替代完整 DB backup/PITR。本报告只验证「恢复演练门禁」：coverage 未 PASS 或 complementary backup 未声明时 destroy/teardown fail-closed。
+
+## 二、 测试目标 (Test Objectives)
+
+- `PreflightDestroy` 在 backup 未 PASS 时拒绝。
+- 不把 FAV 单测冒充为已完成的 PostgreSQL PITR 演练。
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+
+本机 `go test`；**未**对 `agent-dev` 做 pg_dump/restore（集成槽占用 + 数据根 split-brain）。命令：`TestCoverageGateFailClosed`。
+
+## 四、 预期结果 (Expected Results)
+
+`Coverage{Required:2, Verified:1}` + backupOK=true 仍因 coverage 失败而拒绝；backupOK=false 亦拒绝。
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+
+- **测试输入**: `PreflightDestroy(Coverage{Required: 2, Verified: 1}, true, true, true)`
+- **实际输出**: `artifactvault: coverage gate failed required=2 verified=1 quarantine=0`
+- **评价判定**: PASS（门禁）；**FAIL / 未做** live PostgreSQL restore
+- **性能与耗时**: <1ms
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+
+见 [assets/2026-09-14-final-artifact-vault/unit-tests.txt](assets/2026-09-14-final-artifact-vault/unit-tests.txt) 中 `TestCoverageGateFailClosed`。
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+
+门禁函数可用。完整 PostgreSQL restore 演练依赖独立 backup 作业与 Unit A 后的干净数据根，不得在本报告勾 PASS。

.doc/test-reports/2026-09-14-fav-scratch-recover-drill-test-report.md

@@ -0,0 +1,37 @@
+# FAV 演练：scratch 恢复（独立报告）
+
+## 一、 测试背景 (Background)
+
+方案要求恢复目标必须是 scratch identity，默认 `recover-as-collection`，union-deny 删除，禁止写回 dev/test/main。
+
+## 二、 测试目标 (Test Objectives)
+
+- `ValidateRecoverTarget` 拒绝 `agent_system_dev/test/main`。
+- relink 在冲突/缺授权时失败。
+- union-deny tombstone 后 `DegradedPayload` 拒绝。
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+
+内存 registry + tempfile vault。`cmd/artifact-vault recover-plan/apply` 仅编译，未对现网 DSN 执行 apply。
+
+## 四、 预期结果 (Expected Results)
+
+operational DSN 拒绝；scratch 计划通过；denied/relink+conflict 失败；tombstone 后不可读。
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+
+- **测试输入**: `TestRecoverRejectsOperationalDSN`、`TestRecoverPlanGates`、`TestTombstoneUnionDeny`
+- **实际输出**:
+  - `postgres://x/agent_system_dev` → refuse
+  - `postgres://x/fav_scratch` → accept
+  - union-deny → degraded read error
+- **评价判定**: PASS（计划校验）；live scratch 库 apply **未执行**（避免误连 operational）
+- **性能与耗时**: <10ms
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+
+见 unit-tests.txt。`go test -c ./cmd/artifact-vault` 编译通过。
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+
+恢复工具默认 scratch-only。项目 6173 等价「终态→发布→清 workspace→降级读→scratch 恢复→app rebuild」需 Unit A 后另占槽，不得声称已拦截任意 `rm`。

.doc/test-reports/2026-09-14-final-artifact-vault-test-report.md

@@ -0,0 +1,98 @@
+# 最终成果保险库 V0–V6 测试报告
+
+## 一、 测试背景 (Background)
+
+运行库与 workspace 投影会一起丢失或错挂。已审查的 FAV 方案要求只归档数据库终态事实，独立 `VAULT_STATE_ROOT`，禁止扫描 `output.md`，GET 零写入，恢复只进 scratch。本轮按落地计划实现 V0–V6 内核与领域接入；现网 Unit A 纠挂未完成，故不对 `agent-dev` 开降级读或容器 rebuild。
+
+## 二、 测试目标 (Test Objectives)
+
+- 准入表拒绝非终态、未知类型、敏感正文。
+- approved 无 `review_snapshot_id` 不得入库/批准。
+- task finalize 重算 `export_policy`/`content_sha256` 并 `CompleteChatTurn`。
+- publisher 幂等、拒绝 `data/dev` 根、跨项目同 SHA 分 key、tombstone union-deny。
+- 回填缺证据 quarantine；重跑不新增逻辑成果。
+- recover 拒绝 operational DSN；coverage/destroy 门禁 fail-closed。
+- 半发布缺 commit marker 不可见，exclusive 重试后可恢复。
+- GET/degraded 路径不调用 `Request`。
+- `copy_only` 仅 completed 后显式 pin 可进库。
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+
+| 项 | 值 |
+|----|-----|
+| OS | Linux 7.0.0-31-generic |
+| Go | `go test` 本机 |
+| 后端 | 单元/内存 registry + tempfile vault；**未**使用 stub 作为终态验收替代，也**未**对现网 `pi-agent` 做 6173 演练 |
+| 分支 | `feature/final-artifact-vault` |
+| worktree | `.worktrees/fix-dev-runtime-data-root-guard` |
+| 集成槽 | 未占用；禁止 `env-service` rebuild |
+| 证据 | [assets/2026-09-14-final-artifact-vault/unit-tests.txt](assets/2026-09-14-final-artifact-vault/unit-tests.txt) |
+
+## 四、 预期结果 (Expected Results)
+
+| 用例 | 判定 |
+|------|------|
+| approved 无 snapshot | 拒绝 |
+| task 无 completed turn | 拒绝 |
+| 显式 pin 非终态 | `ErrExplicitBypass` |
+| secret payload | 不得进 staging |
+| 重复 Request/Drain | 同一 UUID，verified=1 |
+| recover operational DSN | 拒绝 |
+| coverage 不完整 | destroy 拒绝 |
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+
+### 1. 准入与表征
+
+- **测试输入**: `go test -v ./internal/artifactvault/ ./internal/docgov/ -run 'TestEvaluateEligibility|TestApproverApprove|TestApprovedHook'`
+- **实际输出**: 全部 `--- PASS`（见 assets）
+- **评价判定**: PASS
+- **性能与耗时**: <10ms / 包
+
+### 2. Publisher / 文件系统
+
+- **测试输入**: `TestPublisherIdempotentAndCrashSafe`、`TestFilesystemRefusesRuntimeDataDev`、`TestTombstoneUnionDeny`、`TestLastReferencePurgeAndLegalHold`
+- **实际输出**: PASS；`data/dev` 根被拒绝
+- **评价判定**: PASS
+- **性能与耗时**: <10ms
+
+### 3. 领域 finalize
+
+- **测试输入**: `TestFinalizeAssistantTaskMessageRecalculatesExportColumns`、`TestCompleteChatTurnAfterFinalize`、`TestFinalizeTaskRunCompletesTurnAndIngests`
+- **实际输出**: PASS
+- **评价判定**: PASS
+- **性能与耗时**: server 用例 5ms
+
+### 4. 回填与恢复计划
+
+- **测试输入**: `TestBackfillIdempotentNoWorkspace`、`TestRecoverRejectsOperationalDSN`、`TestRecoverPlanGates`、`TestCoverageGateFailClosed`
+- **实际输出**: PASS
+- **评价判定**: PASS
+- **性能与耗时**: <10ms
+
+### 5. 缺口补齐（同事务 / recover-apply / GET 零写入 / pin）
+
+- **测试输入**: `TestPublisherRetriesAfterMissingCommit`、`TestUnpublishedWithoutCommitMarkerInvisible`、`TestFilesystemIdentityMismatch`、`TestDegradedPayloadDoesNotWrite`、`TestTryVaultDegradedDoesNotRequest`、`TestApplyRecoverAsCollectionWritesScratchAndSkipsDenied`、`TestServer_PinExportCopyOnlyAfterCompleted`、`TestValidateIndependentVault`
+- **实际输出**: 全部 `--- PASS`（见 [assets/2026-09-14-final-artifact-vault/unit-tests-gapfill.txt](assets/2026-09-14-final-artifact-vault/unit-tests-gapfill.txt)）
+- **评价判定**: PASS
+- **性能与耗时**: artifactvault 4ms；pin-export 120ms
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+
+```
+ok  chat-agent-system/internal/artifactvault  0.005s
+ok  chat-agent-system/internal/config         0.002s
+ok  chat-agent-system/internal/docgov         0.011s
+ok  chat-agent-system/internal/ctxmgr         0.073s
+ok  chat-agent-system/internal/server         0.364s  (FAV 挂钩 / pin-export / GET 零写入)
+```
+
+未跑 `go test ./...` 全量（含真实 PI E2E / 需容器的套件）；本波次范围是 FAV 包与挂钩单测。
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+
+V0–V6 **代码与单测已落地**，可作为合 `dev` 前的内核证据。下列不得写成已关闭：
+
+- 现网 `FAV_DEGRADED_READ` 必须保持 false，直到 Unit A 纠挂。
+- 项目 6173 等价脱敏 corpus 与三条 live 演练见独立报告，当前为 **preflight / 单测等价**，不是容器 e2e PASS。
+- Goose FAV 表为 **00034**（00033 已被 task-run 治理占用）。

.doc/test-reports/2026-09-21-agent-workflow-governance-adoption-test-report.md

@@ -0,0 +1,76 @@
+# Agent worktree 工作规范采纳验收
+
+**日期**：2026-09-21。**范围**：工程规范与文档，非自动化系统或产品运行验收。
+
+## 一、测试背景
+
+用户批准 worktree 工作方式，需将研究方案转为可发现的生效规则，同时保护主目录其他 Agent 的未提交工作。
+
+## 二、测试目标
+
+规则入口一致、没有新增断链、只合入工程文档、候选与 dev 一致、主目录业务现场不被切换。
+
+## 三、测试方案与环境
+
+本机 Linux / Git 2.53.0，真实 Git linked worktree；检查文档与本地 Git 集成。没有 stub/真实产品 PI 调用，没有业务运行测试。父进程用 flock 串行操作，原始记录保存在 common-dir/agent-control/governance-adoption.json。
+
+## 四、预期结果
+
+文档检查无新错误；dev 接收已验证的同一合并提交；主目录分支和 HEAD 不变；部署 not_required，自动化仍 planned。
+
+## 五、实际测试结果与判定
+
+- PASS：用户批准的工作方式已写入 AGENTS、PROJECT、Cursor 规则、Herdr 规范指针和任务/收口模板。
+- PASS：全部新增改动使用 worktree，显式 dev 基线，串行候选集成，部署与安全清理条件已生效；旧脚本 create/remove 缺口有明确绕行方法。
+- PASS：链接检查覆盖 308 次本地引用，无新增断链；FEATURE-MATRIX 原有 promotion receipt 旧链接未因本任务修改。
+- PASS：规则差异及候选 `git diff --check`，只包含工程规范/Markdown 路径。
+- PASS：父进程持本机 `flock`，从明确 dev 与任务 SHA 创建 no-ff 候选，验证后在临时 dev 工作区 `--ff-only` 接收同一候选。
+- PASS：主目录分支与 HEAD 未切换，其他 Agent 的未提交业务文件未被纳入提交。
+- NOT REQUIRED：业务测试、PI、容器重建。本次不涉及运行制品，`deployment=not_required`。
+- NOT IMPLEMENTED：自动注册表、队列、脚本 guard、OS 权限隔离、PI 镜像交付等，FEATURE-MATRIX 仍为 planned。
+
+### 控制台证据
+
+- 链接检查：`Local links checked: 308`，`New broken links: []`；旧 FEATURE-MATRIX receipt 链接单独保留为既有问题。
+- `git diff --check`：退出码 0，无输出。
+- `git diff --exit-code 048bbe4a 83e22a70`：退出码 0，无输出，候选树与已检查的规则树一致。
+- 集成输出：`candidate=83e22a701f33825fe5b8fc34c21bf1ad8db07628`，`dev=83e22a701f33825fe5b8fc34c21bf1ad8db07628`，`main_branch_preserved=fix/intent-workflow-scoping-2026-09-21`。
+- 耗时：首次文档集成调用约 1.27 秒（工具墙钟），不作为产品性能指标。
+
+### Git 身份
+
+| 项 | 值 |
+|---|---|
+| 初始 dev | `15b8a4a87d9bd260ce9f613f5297fdd1fe6a2285` |
+| 规则提交 | `048bbe4a5e2fd6ae0093664a2041a7533ea39fdf` |
+| 已验证候选 = 首次合入 dev | `83e22a701f33825fe5b8fc34c21bf1ad8db07628` |
+| 主目录保持 | `fix/intent-workflow-scoping-2026-09-21` @ `0912efdbd9346e61300b35961acccd1ec16bef0a` |
+| 远端 | 未 push，未 fetch；不以本地跟踪引用宣称实时远端状态 |
+
+本报告及任务归档为随后独立的文档收口提交，不改变前述被验证内容。最终 dev 提交可从 `git log dev` 查看，不把收口 commit 当运行部署 SHA。
+
+## 六、自动化测试套件汇总
+
+只执行上述文档和 Git 现场检查。Go/前端/PG/真实 PI 套件 NOT REQUIRED（纯工程规范，依据 PROJECT §8 与 test-reports-standard 范围判定），不报告业务测试通过率。
+
+## 七、测试结论与后续优化建议
+
+生效工作规则已合入本地 dev，文档准入通过；完整自动化实现仍按独立计划推进。
+
+### 并行基线变化
+
+首次规范合入后，Cursor 接续合入 `e0665ca4` 并占槽 rebuild。收口请求仍携带 `83e22a70` 基线，被集成前置检查拒绝（dev SHA 不匹配），没有推进引用或改写主目录。收口需采用最新 dev 重建候选并保留 Cursor 槽位状态。
+
+### 迁移与清理
+
+- 主目录仍有旧任务工作，按过渡规则保留；不 stash/reset、不覆盖、不重建服务。
+- 临时 dev 检出目录为 `.worktrees/agent-governance-dev-integration`。其保留不是开发例外：只作此次文档集成与可读入口。原任务 owner 保存成果并确认根目录干净后，安全移除临时目录，再将主目录切回 dev。
+- 本任务 worktree 和集成候选在收口合入后检查无 tracked/untracked/ignored 遗留及 cwd 使用，再普通 remove/-d；若任何检查失败则保留并报告。最终实际清理状态写入 common-dir 的 `agent-control/governance-cleanup.json`。
+- 本机 `flock` 和临时操作记录仅为本次受控集成，不等于完整机器协调系统已交付。
+
+## 链接
+
+- [工作规范](../ops/2026-09-21-agent-worktree-workflow.md)
+- [已采纳方案](../remediation/2026-09-21-agent-workflow-governance-plan.md)
+- [收口任务](../archive/ops/2026-09-21-agent-workflow-governance-adoption.md)
+- [迁移交接](../ops/handoffs/2026-09-21-agent-workflow-governance-plan.md)

.doc/test-reports/2026-09-21-go-agentx-runtime-test-report.md

@@ -0,0 +1,99 @@
+# Go 原生 PI Agent 运行时 测试报告
+
+## 一、 测试背景 (Background)
+
+主服务需要在进程内提供 `pi-native` 后端，与容器 `pi-agent` 并存。cursor 后端已从本分支移除。默认后端只有在真实双跑达到同等或更好之后才允许切到 `pi-native`。容器链路保留为回退。
+
+## 二、 测试目标 (Test Objectives)
+
+- `pi-native` 能对真实 MiniMax-M2.7-highspeed 完成文档、对话、推理三类任务，并写出目标文件。
+- 与容器 `pi-agent` 使用同一套提示、同一模型、同一工具画像。
+- 替换门槛：`pi-native` 成功率不低于容器、无 P0 产物缺陷、成功样本 P95 ≤ 容器 P95 的 1.3 倍。
+- `go vet ./...` 通过；短测试中本任务新增包通过。
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+
+- OS：Linux。Go 模块 `chat-agent-system`。模型：MiniMax-M2.7-highspeed。两端都走真实接口，不使用 stub。
+- 容器 runner：`http://127.0.0.1:18865`（`shuimu-pi-agent-dev`）。`pi-native` 由主进程内 `internal/agentx` 直连 MiniMax OpenAI 兼容流式接口。
+- 套件：`internal/agentx/abtest`，6 例（文档 2、对话 2、推理 2）。每例超时 3 分钟，工作区互相隔离。
+- 入口：`RUN_AGENTX_AB=1 go test ./internal/agentx/abtest/ -run TestLiveDualBackend`。
+- 第一轮分位数用截断索引，两例成功时取了更快的样本，该轮不作判定。判定使用第二轮 nearest-rank。
+
+## 四、 预期结果 (Expected Results)
+
+- `workspace` 画像写出目标文件；`reasoning` 画像不调用工具。`pi-native` 在推理画像把助手正文写入空目标。容器 `--no-tools` 只收集磁盘上已有文件，缺文件则 `MISSING_TARGET`。
+- 判定通过才允许把 dev 的 `AGENT_BACKEND` 改为 `pi-native`。未通过则默认保持 `pi-agent`。
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+
+### 用例矩阵（第二轮，2026-09-21）
+
+| 后端 | 用例 | 成功 | 目标 | 耗时 | token | 错误 |
+| --- | --- | --- | --- | --- | --- | --- |
+| pi-native | doc-brief | true | 1/1 | 8.216s | 1765 | |
+| pi-native | doc-outline | true | 1/1 | 16.616s | 2946 | |
+| pi-native | dialogue-hello | true | 1/1 | 3.001s | 159 | |
+| pi-native | dialogue-status | true | 1/1 | 2.657s | 180 | |
+| pi-native | reason-risk | true | 1/1 | 2.403s | 145 | |
+| pi-native | reason-scope | true | 1/1 | 3.180s | 142 | |
+| pi-agent | doc-brief | true | 1/1 | 5.974s | 0 | |
+| pi-agent | doc-outline | true | 1/1 | 6.926s | 0 | |
+| pi-agent | dialogue-hello | false | 0/1 | 4.727s | 0 | MISSING_TARGET |
+| pi-agent | dialogue-status | false | 0/1 | 3.024s | 0 | MISSING_TARGET |
+| pi-agent | reason-risk | false | 0/1 | 2.697s | 0 | MISSING_TARGET |
+| pi-agent | reason-scope | false | 0/1 | 2.828s | 0 | MISSING_TARGET |
+
+汇总：`native_success=1.00`，`remote_success=0.33`，`native_p95=16.616s`，`remote_p95=6.926s`，`p0=0`。整轮墙钟 62.25s。
+
+### 测试输入 (Input)
+
+固定套件见 `internal/agentx/abtest.Suite`。本轮文档目标文件名为 `output.md`，对话与推理目标为 `reply.md`。判定日志落盘后，套件里的文档目标改成了 `brief.md` / `outline.md`，以免生产代码再出现受架构扫描约束的 `output.md` 字面量。本表对应改名前的实跑。
+
+### 实际输出 (Actual Output)
+
+```
+native_success=1.00 remote_success=0.33 native_p95=16.615955879s remote_p95=6.926484503s p0=0
+pi-native doc-brief success=true p0=false targets=1/1 dur=8.216466681s err= tokens=1765
+pi-native doc-outline success=true p0=false targets=1/1 dur=16.615955879s err= tokens=2946
+pi-native dialogue-hello success=true p0=false targets=1/1 dur=3.001327463s err= tokens=159
+pi-native dialogue-status success=true p0=false targets=1/1 dur=2.657008525s err= tokens=180
+pi-native reason-risk success=true p0=false targets=1/1 dur=2.403261749s err= tokens=145
+pi-native reason-scope success=true p0=false targets=1/1 dur=3.180087344s err= tokens=142
+pi-agent doc-brief success=true p0=false targets=1/1 dur=5.974404302s err= tokens=0
+pi-agent doc-outline success=true p0=false targets=1/1 dur=6.926484503s err= tokens=0
+pi-agent dialogue-hello success=false p0=false targets=0/1 dur=4.726537486s err=MISSING_TARGET tokens=0
+pi-agent dialogue-status success=false p0=false targets=0/1 dur=3.02361258s err=MISSING_TARGET tokens=0
+pi-agent reason-risk success=false p0=false targets=0/1 dur=2.696804095s err=MISSING_TARGET tokens=0
+pi-agent reason-scope success=false p0=false targets=0/1 dur=2.828393237s err=MISSING_TARGET tokens=0
+replacement gate failed: [pi-native P95 latency exceeds 1.3x pi-agent]
+--- FAIL: TestLiveDualBackend (62.25s)
+```
+
+原文：`.doc/test-reports/assets/go-agentx-runtime/ab-live.txt`。
+
+### 评价判定 (Evaluation / Verdict)
+
+**FAIL（不切换默认后端）。** 成功率 1.00 ≥ 0.33，P0 为 0。P95 16.616 / 6.926 = 2.40，大于 1.3。`AGENT_BACKEND` 保持 `pi-agent`。未从主目录 rebuild，未改 compose。
+
+### 性能与耗时 (Duration & Latency)
+
+成功样本 P95：`pi-native` 16.616s，容器 6.926s。`pi-native` 合计 token 5337（prompt+completion 之和，日志字段为两端相加）。容器结果未回传用量。
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+
+`go vet ./...` 退出码 0。日志：`.doc/test-reports/assets/go-agentx-runtime/vet.txt`。
+
+`go test -short ./...` 退出码 1。本任务包通过：`internal/agent`、`internal/agentx`、`internal/agentx/abtest`、`internal/agentx/llm`、`internal/agentx/session`、`internal/agentx/tools`、`internal/workspace`、`internal/server`、`internal/config`、`internal/taskrun`。
+
+仍失败的包：
+
+- `internal/archtest`：`pi-native` 的 import 与路径字面量已纳入边界清单，path 计数回到 16。剩余 23 条 import 来自基线 `a5ea469` 上已有的 `workflowscope`、`materialindex`、`mineru`，本任务未改这些包。
+- `internal/docgov`、`internal/notification`、`internal/storage`：测试默认连 `127.0.0.1:5433` 的 dev 库。失败是外键与 `uq_projects_name_global` 重名，不是本运行时逻辑。这次短测试把 goose 推到了 **62**，新增空表 `agentx_workspace_registry`。迁移文件仍只在本分支。
+
+完整输出：`.doc/test-reports/assets/go-agentx-runtime/short-test.txt`。
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+
+未达到切换标准。dev 默认继续 `AGENT_BACKEND=pi-agent`。`deploy/pi-agent/`、`PiAgentBackend` 与 compose 中的 pi-agent 服务保留。回退不需要数据迁移。
+
+差距记录在 `.doc/audit/2026-09-21-go-agentx-runtime-latency-gap.md`。下一步是把 `pi-native` 文档任务的成功时延降到容器 P95 的 1.3 倍以内，再跑同一套 `TestLiveDualBackend`。worktree 保留，未合入 `dev`。

.doc/test-reports/2026-09-23-chat-semantic-d3-closeout-test-report.md

@@ -0,0 +1,88 @@
+# chat-semantic-d3 收口重验 测试报告
+
+## 一、 测试背景 (Background)
+
+FEATURE-MATRIX `chat-semantic-d3` 长期 `partial`：PU6/W2/S1 已交付 shadow 能力，但声明范围含被 Wave5 X-2 密封的 `SEMANTIC_SUMMARY_REPLACE`，导致无法收敛。本轮收口：把 REPLACE 义务迁出，对当前 local `dev` tip 重验 shadow 路径，并修复 reasoning/`--no-tools` 下真 PI 无法产出叙事的回归。
+
+## 二、 测试目标 (Test Objectives)
+
+- `go vet` / 相关 short 单测 / arch-check block 全绿
+- chatflow 授权可见 + injection 负例对齐 S1 异步 drain 后 PASS
+- 真实 PI Runner + MiniMax 产出 shadow narrative；不含「200万」注入秘密；REPLACE 仍不接线
+- 仓库零放量：`SEMANTIC_SUMMARY_SHADOW` 默认 off；`SEMANTIC_SUMMARY_REPLACE` 未接线
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+
+- OS：Linux；Go：go1.27.1
+- 分支/worktree：`feature/chat-semantic-d3-closeout-2026-09-23` @ base `9d8332ad`
+- Runner：`http://127.0.0.1:18865`，model `MiniMax-M2.7-highspeed`，`DATA_DIR`=主目录 `data/dev`（容器 bind-mount）
+- 层级：单元/表征 + 真实 PI；Playwright digest UI **NOT REQUIRED**（本行关闭条件不含 UI 替换；依据验证契约「纯工程/既有证据」）
+- 全量 `go test ./...`：**NOT REQUIRED**（本轮为 D3 收口与定向修复，非产品 PI 全链路交付；依据 [PROJECT.md](../../PROJECT.md) §8 / 验证契约纯工程范围）
+
+## 四、 预期结果 (Expected Results)
+
+- short：flag off/on、fallback、watermark、chatflow injection 负例 PASS
+- live：非空中文 narrative；无「200万」；elapsed 数秒级
+- arch-check `--mode block` PASS
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+
+### 5.1 go vet + short 语义套件
+
+- **测试输入 (Input)**：`go vet ./internal/ctxmgr/... ./internal/app/...`；`go test -short -count=1 ./internal/ctxmgr/ ./internal/app/chatflow/ ./internal/app/ -run 'Semantic|Shadow|Summar|ChatLog_Semantic|PiSemantic|ExtractAssistant'`
+- **实际输出 (Actual Output)**：
+
+```text
+ok  	chat-agent-system/internal/ctxmgr	0.015s
+ok  	chat-agent-system/internal/app/chatflow	0.009s
+ok  	chat-agent-system/internal/app	0.005s
+```
+
+- **评价判定 (Evaluation / Verdict)**：PASS
+- **性能与耗时 (Duration & Latency)**：<1s
+
+### 5.2 chatflow 异步 drain 对齐（S1 residual）
+
+- **测试输入 (Input)**：`TestChatLog_SemanticShadowAuthorizedOnlyAndInjectionCannotEscalate`（pending → Drain/Wait → ok）
+- **实际输出 (Actual Output)**：`--- PASS: TestChatLog_SemanticShadowAuthorizedOnlyAndInjectionCannotEscalate (0.01s)`
+- **评价判定 (Evaluation / Verdict)**：PASS（修复前失败于 `want shadow ok` 而实际为 `pending`）
+- **性能与耗时 (Duration & Latency)**：~10ms
+
+### 5.3 真实 PI MiniMax
+
+- **测试输入 (Input)**：`RUN_PI_E2E=1 go test ./internal/app -run TestPiSemanticSummarizer_LiveMiniMax -v`（token 自主目录 `.env` 注入，不入库）
+- **实际输出 (Actual Output)**：
+
+```text
+=== RUN   TestPiSemanticSummarizer_LiveMiniMax
+    semantic_summarizer_test.go:203: model=MiniMax-M2.7-highspeed protocol=semantic-summary-v1 elapsed=4.242s narrative="用户就高频超声手术刀系统的研发立项寻求建议，询问立项相关要点。助手回复指出需要重点关注电气安全要求和产品型检周期两个方面。"
+--- PASS: TestPiSemanticSummarizer_LiveMiniMax (4.24s)
+```
+
+- **评价判定 (Evaluation / Verdict)**：PASS（未出现「200万」；reasoning 路径经 prompt 内嵌消息 + execution.log 回落叙事）
+- **性能与耗时 (Duration & Latency)**：4.242s
+
+### 5.4 arch-check
+
+- **测试输入 (Input)**：`./scripts/arch-check.sh --mode block`
+- **实际输出 (Actual Output)**：`arch-check block: production gate passed`
+- **评价判定 (Evaluation / Verdict)**：PASS
+- **性能与耗时 (Duration & Latency)**：<1s
+
+### 5.5 已知非本行失败（记录，不挡收口）
+
+- `TestProductionCompositionHasNoHookRegistration`：`internal/server/server.go` 仍赋值 `OnOutbox`（与 D3 无关的既有失败；本轮未改 server）
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+
+| 套件 | 结果 |
+|---|---|
+| `go vet` ctxmgr/app | PASS |
+| short 语义相关 | PASS |
+| Live MiniMax | PASS |
+| arch-check block | PASS |
+| 全量 `go test ./...` | NOT REQUIRED（见第三节依据） |
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+
+达到 `chat-semantic-d3` 收窄后的 done 关闭条件。实现修正：`PiSemanticSummarizer` 在 reasoning/`--no-tools` 下内嵌授权消息，并从 `execution.log` 恢复助手叙事（对齐 pi-native）。`SEMANTIC_SUMMARY_REPLACE` 义务迁至独立 deferred 行 `chat-semantic-replace`；启用需独立授权 + fail-closed 灰度（Wave5 X-2）。不 push、不晋升、不改 gap-matrix。

.doc/test-reports/2026-09-23-pi-narrative-closeout-test-report.md

@@ -0,0 +1,71 @@
+# PI change-report 叙事收口测试报告
+
+## 一、 测试背景 (Background)
+
+`docgov-pi-narrative` 在 W3（2026-09-17）曾宣称 done，后因 2026-09-20 调研发现两处实质缺口回退 `partial`：`facts.json` 仅计数、`--no-tools` 仅为 prompt。缺口已先后补齐；2026-09-23 pi-runner response-size 与 reasoning 落盘路径变化触发本行重验。本轮补强 live 输入、修复 reasoning 目标落盘，并以真实 MiniMax 复测后升 `done`（默认 flag 仍 off）。
+
+## 二、 测试目标 (Test Objectives)
+
+- live 路径携带截断 hunk/impact 文本；digest 原样回写
+- flag-on `ResolveChangeReport` → `analysis_status=complete` 且服务端 `rule_risk` 不被覆盖
+- runner reasoning 画像在 `--no-tools` 下将助手正文物化为 `narrative.md`
+- 默认 `PI_CHANGE_REPORT_NARRATIVE=false` 保持
+- UI 分区回归仍 PASS
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+
+| 项 | 值 |
+|----|----|
+| OS | Linux |
+| Go | go1.x（本机） |
+| 被测 SHA | `fdbefbac`（合入 local_dev 后） |
+| Runner | `http://127.0.0.1:18865` / `MiniMax-M2.7-highspeed` / typed-result-v1 |
+| Flag | 进程级 `PI_CHANGE_REPORT_NARRATIVE=true`（测后无残留；compose 默认 false） |
+| 证据 | `assets/2026-09-23-pi-narrative-closeout/` |
+
+## 四、 预期结果 (Expected Results)
+
+- Live PASS；summary 引用具体阈值变更而非空泛计数
+- Resolve complete + medium risk 保留
+- overlay 14 pass；负例套件仍绿
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+
+### 5.1 真实 PI MiniMax（修复后输入）
+
+- **测试输入 (Input)**：`RUN_PI_E2E=1 PI_CHANGE_REPORT_NARRATIVE=true go test -count=1 ./internal/app -run TestPiChangeReportNarrator_LiveMiniMax -v`
+- **实际输出 (Actual Output)**：见 `live-minimax.txt`
+
+```text
+=== RUN   TestPiChangeReportNarrator_LiveMiniMax
+    pi_narrative_test.go:158: elapsed=7.654s model=MiniMax-M2.7-highspeed raw={"schema_version":1,"schema_kind":"change_report_narrative_v1","input_digest":"5fbc5c7c082a6434802f442d03c1d92433e6f540715291f980b7bc6f28d6f88e","from_sha":"fromsha-closeout-20260923","to_sha":"tosha-closeout-20260923","summary":["性能指标中响应时间阈值从2秒收紧至1秒","验收口径调整，性能设计响应预算需复核"]}
+--- PASS: TestPiChangeReportNarrator_LiveMiniMax (7.65s)
+```
+
+- **评价判定 (Evaluation / Verdict)**：PASS（digest 原样；summary 锚定 hunk 文本；Resolve complete）
+- **性能与耗时 (Duration & Latency)**：7.65s
+
+### 5.2 前端分区
+
+- **测试输入 (Input)**：`npx tsx --test src/features/documentRevision/overlayMode.test.ts`
+- **实际输出 (Actual Output)**：14 pass（见 `overlay-mode.txt`）
+- **评价判定 (Evaluation / Verdict)**：PASS
+- **性能与耗时 (Duration & Latency)**：~97ms
+
+### 5.3 单测 / arch
+
+- `go test -short` narrative / Resolve / CreateAgentCandidate_Flag：PASS
+- `node deploy/pi-agent/reasoning-materialize.test.mjs`：PASS
+- `./scripts/arch-check.sh --mode block`：PASS
+
+### 5.4 默认 flag
+
+- compose / `.env.example` 仍为 false（未改动放量配置）
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+
+本轮为能力成熟度收口（non_blocker），适用范围：narrative 包 + app live + overlay + arch。非产品全链路 PI nightly；全量 `go test ./...` **NOT REQUIRED**（依据验证契约：范围门禁已覆盖受影响包）。
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+
+达到 FEATURE-MATRIX `docgov-pi-narrative` → `done`。默认 flag off；dev/test 常驻开启另授权。观察窗后评估放量。

.doc/test-reports/2026-09-23-remaining-worktrees-closeout-test-report.md

@@ -0,0 +1,68 @@
+# 剩余 Worktree 推进完成 测试报告
+
+## 一、 测试背景 (Background)
+
+将 `.worktrees` 下剩余注册 worktree（已合入占用项、go-agentx、FAV）与 stale 目录推进至终态；用户授权解除 FAV 整支 merge 保护。不 push 远端。
+
+## 二、 测试目标 (Test Objectives)
+
+- 终止孤儿进程并移除已合入 worktree
+- 合入 go-agentx 与 FAV（flag 默认关；MATRIX events-fav 保持 partial）
+- 删除 stale 目录并归档 DIFF
+- CURRENT/MATRIX 收口；主目录仅保留 registered worktree
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+
+- OS: Linux；Go short/vet/arch-check；agentctl validate/integrate
+- 工程/治理变更：产品 PI 全链路 NOT REQUIRED（依据 PROJECT §8 / worktree 规范：合入与清理收口）
+
+## 四、 预期结果 (Expected Results)
+
+- local_dev 含 go-agentx + FAV；goose 无重号
+- `git worktree list` 仅主目录（或仅本收口 wt 待删）
+- FAV_DEGRADED_READ 默认 false；events-fav=partial
+- remote_sync=not_requested
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+
+### 5.1 阶段 A：孤儿进程与已合入 wt
+
+- Input: kill 2384895 / 2361626 / 493547；remove dual-push / integrate-go-agentx / intent-confirm
+- Actual: 三 PID 已终止；三 worktree+分支已 remove
+- Verdict: PASS
+
+### 5.2 阶段 B：go-agentx
+
+- Input: merge feature/go-agentx-runtime-2026-09-21；goose 00062 重编号为 00066；vet + short agentx/agent/workspace；arch-check
+- Actual: merged as 6032dbaa；validate PASS；integrate merged；源 wt/分支已删
+- Verdict: PASS
+
+### 5.3 阶段 C：FAV（例外授权）
+
+- Input: merge feature/final-artifact-vault；丢弃重复 00034；vet + short artifactvault/app/fav/storage/config + server 子集；arch-check
+- Actual: merged as 3e01f187；FAV flags 默认关；integrate merged；fix-dev-runtime-data-root-guard 与 feature/final-artifact-vault 已删
+- Verdict: PASS
+
+### 5.4 阶段 D：stale
+
+- Input: 4 计划项 + closeout leftover；见 assets/stale-DIFF.md
+- Actual: 全部 rm -rf；multiuser 短文以 local_dev W1-D 为准，无字段需回抬
+- Verdict: PASS
+
+### 5.5 阶段 E：文档收口
+
+- Input: docs apply 认领/清理 FAV 行/页眉/events-fav；测试报告
+- Actual: apply 成功；受控约束第一条因 protected_sections 未直接改写（记入 short-term）
+- Verdict: PASS（约束条文延期记入 short-term，不挡合入）
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+
+- go-agentx: go vet / go test -short ./internal/agentx/... / arch-check --mode block → PASS（validate run 3f593af3 / 51c72dfc）
+- FAV: go vet / go test -short ./internal/artifactvault/ ./internal/app/fav/ ./internal/storage/ ./internal/config/ + server 子集 + arch-check → PASS（validate run ef2d1f2a）
+- 全量 go test ./...：NOT REQUIRED（工程收口；排除预存 docquery/chatflow）
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+
+- 结论: 授权范围内剩余 worktree 推进完成；合入 tip `4381b710`；规范收尾后清理表已标「目录不存在」；不 push
+- 五态终态: review_state=accepted · integration_state=merged_local_dev · deployment=not_required · cleanup=done · remote_sync=not_requested
+- 后续: 有权维护者将受控约束第一条改为 short-term 建议文案；FAV live 仍不放量

.doc/test-reports/2026-09-23-squad-missing-target-retry-test-report.md

@@ -1,61 +0,0 @@
----
-title: "智能体小队故障根治 — 测试报告"
-date: 2026-09-23
-task_id: squad-missing-target-retry-2026-09-23
-verdict: PASS
----
-
-# 智能体小队故障根治 — 测试报告
-
-## 结论
-
-R1（test author_only 解锁）+ R2（settled-no-deliverable 纠偏重试）已落地；local `test@9984c68d` + `rc-v1.1.0-beta.5` pinned 重建后，项目 6012 触发「编写用户初始需求收集表」小队任务 **completed**（不再 `blocked_pending_governance`）。未 push 远端。
-
-## 版本矩阵
-
-| 项 | 值 |
-|---|---|
-| feature head | `4830b8ba` |
-| integrate candidate / local_dev tip（合入时） | `357e4ddb` |
-| local test | `9984c68d` |
-| rc tag | `rc-v1.1.0-beta.5` → `9984c68d` |
-| pinned commit | `357e4ddb` |
-| app digest | `shuimu-agent-app@sha256:038c301cb68f68d2346fe1e8ad9ed67e844f0338556b8fbffbd35dcf1f02d3ef` |
-| pi-agent digest | `shuimu-pi-agent@sha256:03e6249ab0f5a44128975f63de48557214498a01a8009ab289bc041082826114` |
-| test health schema | 65 |
-| author_only | `true` rev=1 |
-
-## 命令与判定
-
-| 步骤 | 判定 | 说明 |
-|---|---|---|
-| PUT `workflow.allow_author_only_approval` | PASS | CAS revision 0→1 |
-| save-plan author_only + activate 6012 | PASS | 7 文档兼任；instance active |
-| `go test -short ./internal/agent ./internal/squad ./internal/stream` | PASS | 含 settled-no-deliverable 单测 |
-| `node --test deploy/pi-agent/*.test.mjs` | PASS | clean settle+missing → retryable |
-| `arch-check --mode block` | PASS | |
-| agentctl validate + integrate | PASS | ff `78c2bcf6`→`357e4ddb` |
-| promote merge + update-ref + tag | PASS | P1=`c6f0561b` P2=`357e4ddb` |
-| candidate-images-build/apply + rebuild | PASS | pinned recreate |
-| E2E `bd_intake` | PASS | `run_1790162579970596047` completed；三步均有 `output.md` |
-
-## E2E 要点
-
-- 创建 HTTP 202，`status=running`（非 blocked）
-- ~6 分钟后 `completed`；workspace `bd_intake_1790162580039623588`
-- 交付物：`01_organize` / `02_draft` / `03_review` / 根 `output.md` 均非空
-
-## 资产
-
-- [assets/2026-09-23-squad-missing-target-retry/](./assets/2026-09-23-squad-missing-target-retry/)
-- [promotion-receipts/357e4ddb…](./assets/promotion-receipts/357e4ddb0fe62e12cf6d1321382376257b0fe674.json)
-
-## 状态
-
-| 字段 | 值 |
-|---|---|
-| review_state | not_required |
-| integration_state | merged_local_dev_and_test |
-| deployment | test_ok |
-| remote_sync | not_requested |
-| cleanup | pending |

.doc/test-reports/2026-09-23-worktree-closeout-batch-test-report.md

@@ -0,0 +1,60 @@
+---
+title: "Worktree 批量收口测试报告"
+created: 2026-09-23
+updated: 2026-09-23
+owner: Cursor
+task_id: worktree-closeout-cleanup-2026-09-23
+local_dev_sha: a690aab42d820058974ca38a363cb71ebe9e0bc9
+remote_sync: not_requested
+---
+
+# Worktree 批量收口测试报告
+
+## 范围
+
+本地 `dev` 与 `origin/dev` 分叉同步、未合入 docs 产物合入、未跟踪任务文档与 mineru gofmt 抢救、agentctl 任务收口、worktree 清理（保留 FAV / go-agentx）。
+
+## 被测 SHA
+
+| 阶段 | SHA | 说明 |
+|---|---|---|
+| 同步前本地_dev | `3f14d7fa` | 分叉 tip |
+| origin/dev | `5cdcee26` | 远端 tip |
+| 同步后 merge | `e6ddfab9` | `merge: sync origin/dev into local_dev` |
+| remaining docs | `c0a0db3a` | modular + lock/policy/governance 产物 + salvage |
+| cleanup fix | `a690aab4` | cwd-hidden 进程例外；当前 local_dev |
+
+## 命令与环境
+
+- 主机：Linux；主目录 `/home/weichen/projects/Agent-System`；local_dev only（未 push）。
+- `agentctl validate` + `integrate`（daemon manager_lock 未持有，直接 integrate）。
+- 同步候选验证：`arch-check --mode block`、`go vet ./...`、`go test -short`（排除预存在于 origin/dev 的 `docquery` / `app/chatflow` 失败）。
+- remaining 验证：arch-check、`gofmt -l internal/mineru/client.go`、`go test -short ./internal/mineru/`。
+- cleanup fix 验证：`python3 -B -m unittest scripts.tests.test_agent_worktree -v`（21 OK）。
+
+## 预期与实际
+
+| 项 | 预期 | 实际 | 判定 |
+|---|---|---|---|
+| recover `dac0865f` | recovered | recovered；promote 任务 cancelled | PASS |
+| merge origin/dev | 冲突解决后合入 local_dev | 14 文件冲突已解；CURRENT 双方认领行保留（集成槽位保留本地）；MATRIX 取 origin record_id 布局，A–G done 升格延后；协调方案保留本地全文并归档远端 phased 副本 | PASS |
+| docs 分支产物 | 合入 | modular refactor plan、lock/policy/governance 产物、salvage short-term 文档、mineru gofmt | PASS |
+| 预存 Go 失败 | 记录不为本轮引入 | `origin/dev@5cdcee26` 上 `docquery` 三例与 `chatflow` semantic shadow 同失败 | 已知残差 |
+| worktree 清理 | 无争议项移除；保护项保留 | 从 41 → 7 注册 worktree；21+ 次 agent_worktree/git remove 成功 | PASS（部分 cleanup_pending） |
+| 保护项 | FAV / go-agentx 保留 | 仍在 | PASS |
+
+## 清理残留（cleanup_pending）
+
+| 路径 | 原因 | cleanup_owner | 复查触发 |
+|---|---|---|---|
+| `.worktrees/fix-dev-runtime-data-root-guard` (FAV) | 受控保护，故意保留 | 原 owner / 维护者 | 用户调整保护边界 |
+| `.worktrees/go-agentx-runtime-2026-09-21` | cancelled 任务现场，故意保留 | 原 owner | 用户授权丢弃 |
+| `.worktrees/dual-push-lan-2026-09-21` | cursor-agent pid 占用 cwd | 独立维护者 | 进程退出后 remove |
+| `.worktrees/integrate-go-agentx-2026-09-21` | cursor-agent 占用 | 独立维护者 | 进程退出后 remove |
+| `.worktrees/intent-confirm-stage-aware-2026-09-21` | cursor-agent 占用 | 独立维护者 | 进程退出后 remove |
+| `.worktrees/fix-dev-multiuser-four-issues` 等 stale 目录 | 无 `.git`；含与_dev 不同的源码/文档片段 | 独立维护者 | 核对唯一内容归档后 rm |
+| FEATURE-MATRIX `模块解耦批次 A–G` | 仍为 `planned`（origin 升 done 需证据行更新） | 维护者 | 持 evidence + docs:approve 行更新 |
+
+## 结论
+
+local_dev `@a690aab4` 已包含 origin/dev 历史与本地独有提交、未合 docs 产物与抢救内容；无争议 worktree 已尽量清理。不 push；A–G MATRIX 升 done 与占用/保护 worktree 留待后续。

.doc/test-reports/2026-09-24-codegraph-governance-test-report.md

@@ -0,0 +1,76 @@
+# CodeGraph 治理与只读盘点 测试报告
+
+## 一、 测试背景 (Background)
+
+Agent 任务 worktree 完成后不自动清理、FEATURE-MATRIX 状态不及时更新，根因是治理面只有人工 `remove` / `docs apply`，无只读盘点触发器。本轮将 CodeGraph 纳入治理启动/建场/sync，并落地 `cleanup report` / `docs drift`（只提醒、不自动删除、不自动升 done）。
+
+## 二、 测试目标 (Test Objectives)
+
+- CodeGraph：MCP 注册、gitignore、建场 best-effort init、hooks fail-open sync、会话 sync；soundness 边界声明。
+- 只读盘点：`agentctl cleanup report`、`agentctl docs drift`（`done→非 done` 硬告警）；daemon `--audit-every`。
+- 回归：scripts/tests 全量通过；新增针对性用例。
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+
+- OS：Linux；Python 3.14；本机已装 `codegraph` CLI。
+- 层级：治理脚本单元测试 + 真实 CLI 取样。
+- **产品 PI 全链路 / 全量 Go 回归：NOT REQUIRED**（依据 PROJECT.md §8 与 worktree 操作规范：纯工程规范/治理工具变更）。
+
+## 四、 预期结果 (Expected Results)
+
+- `hooks codegraph-sync` 在无 CLI 时 exit 0 且 `not_installed`。
+- `hooks install` 含 `post-merge` / `post-checkout`。
+- `docs drift` 能检出 `done→planned` 回退。
+- `cleanup report` 不删除任何 worktree。
+- 建场在无 codegraph / 未 ignore 时不阻断。
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+
+### 5.1 针对性单元测试
+
+**Input**: `python3 -B -m unittest scripts.tests.test_codegraph_governance -v`
+
+**Actual**: 5/5 ok（cleanup_report_never_deletes、codegraph_sync_fail_open_without_binary、create_skips_codegraph_when_missing、docs_drift_detects_done_regression、hooks_install_includes_codegraph_sync_hooks）
+
+**Verdict**: PASS
+
+### 5.2 全量 scripts/tests
+
+**Input**: `python3 -B -m unittest discover -s scripts/tests -p 'test_*.py'`
+
+**Actual**: `Ran 139 tests in 68.951s` → `OK`
+
+**Verdict**: PASS
+
+### 5.3 真实 CLI：cleanup report
+
+**Input**: `python3 scripts/agentctl.py cleanup report`（任务 worktree）
+
+**Actual**（摘要）: `summary: {total: 36, ready: 26, blocked: 10}`；不删除目录。
+
+**Verdict**: PASS
+
+### 5.4 真实 CLI：docs drift
+
+**Input**: `python3 scripts/agentctl.py docs drift`
+
+**Actual**: `status=ok`, `baseline=first_snapshot`, `record_count=29`, `regressions=[]`, `open_capabilities=7`
+
+**Verdict**: PASS（首次快照无回退告警属预期）
+
+### 5.5 真实 CLI：hooks codegraph-sync
+
+**Input**: `python3 scripts/agentctl.py hooks codegraph-sync`
+
+**Actual**: `{"status":"ok","hook":"codegraph-sync","codegraph":{"status":"ok","exit_code":0}}`
+
+**Verdict**: PASS
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+
+- 治理脚本：`139` tests OK（见上）。
+- `go test ./...`：**NOT REQUIRED**（本任务无产品 Go 变更）。
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+
+达到合入 local_dev 标准。后续：独立授权后再装载本机 systemd coordinator；合入后在主目录执行 `hooks install` 以启用 post-merge/checkout sync；T7 按 `cleanup report` 的 ready 清单人工 remove。

.doc/test-reports/2026-09-24-intent-plan-i2-rollout-test-report.md

@@ -0,0 +1,84 @@
+# Track I2 多意图放量验收测试报告
+
+## 一、 测试背景 (Background)
+
+FEATURE-MATRIX `intent-plan-u1u8` 在 Track I1 后仍为 partial：默认 `legacy`，无项目 allowlist、无 shadow 对账。本轮合入 I2 代码后在共享 dev 按 shadow → auto_read → confirm 逐级放量验收。
+
+## 二、 测试目标 (Test Objectives)
+
+- shadow：真实聊天持久不可执行计划，legacy 路由仍执行，步骤 status=pending
+- auto_read：有权限项目上两项只读自动执行一次，receipt 含 auth scope
+- confirm：查询+生成确认前 `task_runs` 零增量；确认后经 `DispatchEligible` 单次执行
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+
+| 项 | 值 |
+|---|---|
+| OS | Linux |
+| 源码 | local_dev `526617ff`（含 I2 + compose dup fix） |
+| 环境 | 共享 dev `shuimu-agent-app-dev` schema **66** |
+| Runner | `:18865` MiniMax-M2.7-highspeed（健康） |
+| 放量配置 | `INTENT_PLAN_PROJECT_ALLOWLIST=*`；compose 仓库默认仍 `legacy` |
+| 验收项目 | **6579**（admin 成员）；993975 用于证明无成员时 confirm 鉴权失败（负例） |
+| 层级 | 真实 HTTP 聊天 + PG 账本；Playwright 双标签沿用既有 U6 lineage，本轮以 API+PG 为准 |
+
+证据：`.doc/test-reports/assets/2026-09-24-intent-plan-i2-rollout/`
+
+## 四、 预期结果 (Expected Results)
+
+| 档位 | 预期 |
+|---|---|
+| shadow | `status=proposed` `execution_mode=validated_only`；步骤 pending；回复仍有 legacy 查询内容 |
+| auto_read | `status=executing/completed`；两步 `succeeded`；live |
+| confirm | 出卡 awaiting；确认前 task_runs Δ=0；确认后 query+task.run succeeded，task_runs Δ=1 |
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+
+### 5.1 shadow
+
+- **测试输入 (Input)**：`POST /api/v1/chat` project=993975 message=`查一下项目风险，然后查相关法规`；`MULTI_INTENT_PLAN_TIER=shadow`
+- **实际输出 (Actual Output)**：`intent_plan.plan_id=pln_2eabf5b5…` status=`proposed` mode=`validated_only`；steps pending；reply 含法规查询结果（legacy）；elapsed≈6.2s；PG 同行一致
+- **评价判定 (Evaluation / Verdict)**：PASS
+- **性能与耗时 (Duration & Latency)**：6.18s
+
+### 5.2 auto_read（有权限项目）
+
+- **测试输入 (Input)**：同句，project=**6579**，tier=`auto_read`
+- **实际输出 (Actual Output)**：`pln_1dc96bd9…` status=`executing`；`project.advisory`/`regulation.query` 均为 `succeeded`；receipt summary 含 `scope=`；elapsed≈7.5s
+- **评价判定 (Evaluation / Verdict)**：PASS
+- **性能与耗时 (Duration & Latency)**：7.45s
+
+### 5.3 auto_read 负例（无项目成员）
+
+- **测试输入 (Input)**：project=993975（admin 非成员）
+- **实际输出 (Actual Output)**：计划停在 `awaiting_confirmation`、步骤 pending（DecidePlan 鉴权失败）；API GET/decision 返回 403
+- **评价判定 (Evaluation / Verdict)**：PASS（fail-closed，确认前无成功副作用）
+- **性能与耗时 (Duration & Latency)**：—
+
+### 5.4 confirm
+
+- **测试输入 (Input)**：project=6579 message=`查一下相关法规，然后帮我生成报价单`；随后 `POST …/decisions` kind=confirm
+- **实际输出 (Actual Output)**：确认前 plan awaiting、steps pending、`task_runs` 562→562（Δ=0）；确认后 status=executing，`regulation.query`+`task.run` succeeded，`task_runs` 563（Δ=1）；confirm_elapsed≈3.0s
+- **评价判定 (Evaluation / Verdict)**：PASS
+- **性能与耗时 (Duration & Latency)**：聊天 1.61s + confirm 2.98s
+
+### 5.5 Playwright 双标签
+
+- **测试输入 (Input)**：本轮未重跑 UI（时间盒）；既有 [U6 dual-tab](./2026-09-16-intent-plan-playwright-dual-tab-test-report.md) lineage 仍有效；本轮以真实 HTTP+PG 关闭 I2
+- **实际输出 (Actual Output)**：NOT RUN
+- **评价判定 (Evaluation / Verdict)**：不挡 I2 关闭（双标签属既有 U6 证据；本轮新增为放量接线）
+- **性能与耗时 (Duration & Latency)**：—
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+
+| 命令 | 结果 |
+|---|---|
+| `./scripts/arch-check.sh --mode block`（I2 合入候选） | PASS |
+| `go test -short ./internal/app/intentflow/ …`（I2 单测） | PASS |
+| 真实 dev HTTP+PG 放量三档 | PASS（见上） |
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+
+**I2 放量验收 PASS**。可将 `intent-plan-u1u8` 升 `done`，口径：仓库 compose 默认仍 `legacy`；dev 运维可按 allowlist 升 shadow/auto_read/confirm。后续 U9–U12 见独立行 `intent-plan-u9u12`。
+
+回退：将 `MULTI_INTENT_PLAN_TIER` 改回 `legacy` 并 recreate app；已有计划可读/可取消。

.doc/test-reports/2026-09-24-intent-plan-u9u12-live-test-report.md

@@ -0,0 +1,95 @@
+# 多意图 U9–U12 live 接线验收测试报告
+
+## 一、 测试背景 (Background)
+
+FEATURE-MATRIX `intent-plan-u9u12` 长期 partial：U9 `ActiveSegmentProposer` 已注入但未进 `HandleTurn`；U10–U12 仅为 `DryRunAdapter`（validated_only）。Track I2（`intent-plan-u1u8`）已升 done 后，本轮按 Track I3 逐域接线并在共享 dev 真实验收。
+
+## 二、 测试目标 (Test Objectives)
+
+- **U9**：规则可切句不走 LLM；歧义句走 proposer（失败 fail-closed）；生产聊天产生多段计划
+- **U10**：`project.fact.supplement` 确认后真实写黑板；确认前零副作用
+- **U11**：首批 `document.claim` + `document.review.submit` 确认后走 docgov 引擎
+- **U12**：首批 `workflow.run`（+ 只读 `run.status.query`）确认后真实执行
+- tier 停在 `confirm`；compose 默认仍 legacy；未开放键保持 validated_only
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+
+| 项 | 值 |
+|---|---|
+| OS | Linux |
+| 源码 | local_dev `b7d775a7`（含 live adapters + version binder + confirm Authorize slots） |
+| 环境 | 共享 dev `shuimu-agent-app-dev` schema **66** |
+| Runner | `:18865` MiniMax-M2.7-highspeed（健康） |
+| 运维 flag | `MULTI_INTENT_PLAN_TIER=confirm`；`INTENT_PLAN_PROJECT_ALLOWLIST=*`；U9–U12=`true` |
+| 验收项目 | **6579** |
+| 层级 | 真实 HTTP 聊天 + intent-plan decisions + PG；单测/arch-check |
+
+证据目录：`.doc/test-reports/assets/2026-09-24-intent-plan-u9u12/`
+
+## 四、 预期结果 (Expected Results)
+
+| 域 | 预期 |
+|---|---|
+| U9 | 规则句 `segmenter.v2` 多段 auto/confirm 可执行；无规则切分时 LLM 失败则 fail-closed 不落执行计划 |
+| U10 | awaiting → confirm 后 `project.fact.supplement=succeeded`（summary `project facts supplemented`） |
+| U11 | claim / review.submit 各自 confirm 后 `succeeded`（`document.*.accepted`） |
+| U12 | confirm 后 `workflow.run=succeeded` |
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+
+### 5.1 U9 生产分段接线
+
+- **测试输入 (Input)**：`查一下项目风险，然后查相关法规`（规则可切）；`法规案例权限相关情况一并说明下`（无连接词）
+- **实际输出 (Actual Output)**：规则句 plan `executing`，steps `project.advisory`/`regulation.query` succeeded，proposal `segmenter.v2`；歧义句 combo=`single`、无持久多段计划（proposer fail-closed）
+- **评价判定 (Evaluation / Verdict)**：PASS（接线进 HandleTurn；规则跳过 LLM；失败 fail-closed）
+- **性能与耗时 (Duration & Latency)**：规则句 ≈9.9s；歧义句 ≈11.1s
+- **证据**：`final-u9-rules.json`、`final-u9-amb.json`
+
+### 5.2 U10 mutate live
+
+- **测试输入 (Input)**：`补充项目信息：验收备注-…，然后查一下相关法规` → confirm
+- **实际输出 (Actual Output)**：`project.fact.supplement=succeeded`（`project facts supplemented`）+ `regulation.query=succeeded`
+- **评价判定 (Evaluation / Verdict)**：PASS
+- **性能与耗时 (Duration & Latency)**：创建 ≈0.7–1.5s；confirm ≈2.1–3.0s
+- **证据**：`final-u10.json`、`final2-u10.json`
+
+### 5.3 U11 docgov live（首批键）
+
+- **测试输入 (Input)**：
+  - claim：`认领文档 doc_proj6579_bd_cdo_quote，然后查一下文档状态`
+  - submit：`请将文档 doc_proj6579_bd_cdo_quote 提交审核，然后查法规`
+- **实际输出 (Actual Output)**：claim / `document.review.submit` 均 `succeeded`（`document.*.accepted`）
+- **评价判定 (Evaluation / Verdict)**：PASS
+- **性能与耗时 (Duration & Latency)**：claim confirm ≈2.9s；submit confirm 即时分派成功
+- **证据**：`final2-u11.json`、`final-u11-submit.json`
+
+### 5.4 U12 run-control live（首批键）
+
+- **测试输入 (Input)**：`运行产品经理工作流，然后查一下运行状态` → confirm
+- **实际输出 (Actual Output)**：`workflow.run=succeeded`（`workflow.run accepted`）+ `run.status.query=succeeded`
+- **评价判定 (Evaluation / Verdict)**：PASS（`run.resume` 仍由单测 + dry-run 覆盖；本轮自然语言未稳定触发 resume 组合）
+- **性能与耗时 (Duration & Latency)**：confirm ≈2.1s
+- **证据**：`final-u12.json`、`u12-confirm.json`
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+
+| 命令 | 结果 |
+|---|---|
+| `./scripts/arch-check.sh --mode block` | PASS |
+| `go test -short`（intentflow/app 定向 U9–U12/Owner） | PASS |
+| 真实 dev HTTP+PG 四域 | PASS（见上） |
+
+全量 `go test ./...` 中预存 `TestProductionCompositionHasNoHookRegistration`（OnOutbox）与本轮无关，未纳入本报告 PASS。
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+
+**U9–U12 逐域 live 验收 PASS**，可将 `intent-plan-u9u12` 升 `done`。口径：
+
+- 已 live：`U9` 生产分段；`project.fact.supplement`；`document.claim` / `document.review.submit`；`workflow.run`（+ 只读 run.status.query 同批）
+- 仍 validated_only：`document.review.approve/reject`、`document.final.approve/reject`、`document.proposal.decide`、`workflow.switch`、`run.restart`（`run.resume` 代码已 live，待自然语言稳定触发补证据）
+- tier 停 `confirm`；compose 默认 `legacy`；放量仅 dev 运维 flag
+
+### 实施中修复（合入 tip）
+
+1. 计划创建绑定 `ExpectedResourceVersion`（U10/U11）
+2. `authorizeDecision` 传入 `Slots`/`SafeSummary`（否则 U11 confirm 误 Forbidden）

.doc/test-reports/2026-09-24-jev-dev-assist-enable-test-report.md

@@ -0,0 +1,109 @@
+# local_dev jev-service assist 启用与对话加成 测试报告
+
+## 一、 测试背景 (Background)
+
+shadow 已在 local_dev 观察一致率。用户授权启用 **assist**，并用多样本真实对话检验：规则词典漏检的时效问句能否被 jev 高置信加成打开实时检索，同时业务问句不被误开。
+
+## 二、 测试目标 (Test Objectives)
+
+- 启动接线 `mode=assist`
+- 20 条真实 chat：A 规则命中基线 / B 漏检候选 / C 应保持非实时
+- 决策层：`rule=false ∧ jev=true ∧ mode=assist` 计为加成信号
+- 体验层：回复是否出现可核验的实时信息（气温/汇率/AQI/金价等）
+- C 组零错误加成
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+
+- OS：Linux；`shuimu-agent-app-dev`；jev `172.17.0.1:8767`；`JEV_DECIDE_MODE=assist`
+- 层级：真实 Agent（pi-agent + 实时检索）端到端对话
+- 样本矩阵：A×4 + B×10 + C×6（见 assets `batch-results.json`）
+- **全量 `go test ./...`：NOT REQUIRED**（运维开关 + 对话验收；产品单元/soak 已有既有报告）
+
+## 四、 预期结果 (Expected Results)
+
+| 组 | 预期 |
+|----|------|
+| A | rule=true，jev≈true，agree；行为与 shadow 时一致（assist 不压低规则） |
+| B | 多数 rule=false、jev=true → 决策加成；部分回复含实时事实 |
+| C | rule=false、jev=false，无 assist 加成 |
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+
+### 5.1 启动接线
+
+- **输入**：`.env.dev` → assist；force-recreate app
+- **实际输出**：`msg="jevdecide wired" mode=assist endpoint=http://172.17.0.1:8767`
+- **判定**：PASS
+
+### 5.2 批量对话汇总（20/20 HTTP 200）
+
+证据：[`assets/2026-09-24-jev-dev-assist-enable/batch-summary.json`](./assets/2026-09-24-jev-dev-assist-enable/batch-summary.json)
+
+| 指标 | 结果 | 判定 |
+|------|------|------|
+| 决策层加成（B） | **10/10**（B1–B10 全部 `rule=false jev=true`） | PASS |
+| A 组 agree | **4/4** | PASS |
+| C 组错误加成 | **0/6** | PASS |
+| UX 可见实时事实 | B3/B4/B6/B7/B8 明确；B9 部分；B1/B2/B5/B10 仍偏项目话术 | 决策 PASS；体验 **部分 PASS** |
+
+### 5.3 典型用例
+
+#### A1 规则基线
+
+- **输入**：`今天上海天气怎么样`
+- **日志**：`mode=assist rule=true jev=true confidence=0.997951 agree=true`
+- **判定**：PASS（assist 未破坏规则命中）
+
+#### B1 决策加成（体验弱）
+
+- **输入**：`外面冷不冷啊今天`
+- **日志**：`mode=assist rule=false jev=true confidence=0.990937 agree=false`
+- **回复**：偏项目 V0.5 话术（检索可能空/模型未用 snippet）
+- **判定**：决策 PASS；体验弱
+
+#### B3 决策+体验加成
+
+- **输入**：`上海现在热不热`
+- **日志**：`rule=false jev=true confidence=0.997512`
+- **回复**：给出约 29°C、湿度等实时表述
+- **判定**：PASS（整链加成可见）
+
+#### B4 汇率漏检加成
+
+- **输入**：`美元兑人民币现在多少了`（无「汇率」词典字）
+- **日志**：`rule=false jev=true`
+- **回复**：给出约 6.697 汇率
+- **判定**：PASS
+
+#### B6 英文天气
+
+- **输入**：`What's the weather like in Beijing today`
+- **日志**：`rule=false jev=true`（中文 marker 全漏）
+- **回复**：北京气温 24.6°C 等
+- **判定**：PASS（对英文问句加成明显）
+
+#### C2 业务防误伤
+
+- **输入**：`型检温度指标怎么定`（含「温度」但强业务词）
+- **日志**：`rule=false jev=false confidence=0.994535 agree=true`
+- **判定**：PASS（未错误加成）
+
+### 5.4 耗时
+
+单轮 chat 约 6–29s（含 pi-agent / 检索）；jev decide 本身亚秒级，不主导端到端。
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+
+NOT REQUIRED（运维启用 + 真实对话批次）。不将本报告记为产品全量回归 PASS。
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+
+**结论**：assist 在决策层对规则漏检的时效问句有明确加成（B 组 10/10），且未误伤 C 组业务问句；A 组规则路径保持。端到端体验上约半数 B 样本能把实时事实写进回复，其余仍受检索空结果/对话模板牵引限制——**加成在「是否打开检索」上已成立，在「答复一定用上检索」上仍有缺口**。
+
+**建议**：
+
+1. 保持 local_dev assist；继续统计 AssistHit / 检索空结果率
+2. 检索失败时对话提示可更明确，避免回落纯项目话术
+3. compose 默认仍 `off`；test/main 不放量直至浸泡与体验稳定
+
+回退：`JEV_DECIDE_MODE=shadow|off` + recreate app。

.doc/test-reports/2026-09-24-jev-dev-shadow-enable-test-report.md

@@ -0,0 +1,62 @@
+# local_dev jev-service shadow 启用 测试报告
+
+## 一、 测试背景 (Background)
+
+产品侧 jevdecide 已合入 `local_dev@d8214a09`，compose 默认 `JEV_DECIDE_MODE=off`。本任务在运行中的 dev 环境打开 shadow，验证容器可达本机 jev-service 且 realtime/ProfileTask shadow 日志落盘。
+
+## 二、 测试目标 (Test Objectives)
+
+- app 进程 `JEV_DECIDE_MODE=shadow` 且启动日志 `jevdecide wired`
+- 容器内 `POST /v1/decide` HTTP 200 且返回非空 answers
+- 真实 chat「今天上海天气怎么样」产生 `jevdecide realtime shadow` / `profile shadow`，agree=true
+- 回退路径明确（改 env 即可）；不启用 assist
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+
+- OS：Linux；环境：`shuimu-agent-app-dev`；jev-service：`127.0.0.1:8767`（容器侧 `172.17.0.1:8767`）
+- 层级：运维启用验收（非产品 PI 全链路门禁复测）
+- **全量 `go test ./...`：NOT REQUIRED**（依据 PROJECT §8 / worktree 规范：纯环境开关与文档；产品门禁已在 [jev-product-shadow 报告](./2026-09-24-jev-product-shadow-test-report.md)）
+
+## 四、 预期结果 (Expected Results)
+
+| 用例 | 预期 |
+|------|------|
+| 启动接线 | `msg="jevdecide wired" mode=shadow endpoint=http://172.17.0.1:8767` |
+| 容器 decide | HTTP 200，`answers.realtime` 含 choice/confidence |
+| chat 天气 | realtime shadow agree；profile shadow 有日志 |
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+
+### 5.1 启动接线
+
+- **输入**：`env-service.sh dev rebuild` 后 `docker logs … \| grep jevdecide`
+- **实际输出**：`time=2026-09-23T17:46:24.393Z level=INFO msg="jevdecide wired" mode=shadow endpoint=http://172.17.0.1:8767`
+- **判定**：PASS
+- **耗时**：rebuild ~20s；healthy 后即见日志
+
+### 5.2 容器内 decide
+
+- **输入**：app 容器内 `curl` → `$JEV_BASE_URL/v1/decide`（Bearer=$JEV_API_KEY；context=今天上海天气怎么样；noul realtime）
+- **实际输出**：HTTP 200；`choice=yes confidence≈0.998`
+- **判定**：PASS
+- **耗时**：~0.4s
+
+### 5.3 真实 chat shadow
+
+- **输入**：`POST /api/v1/chat` message=`今天上海天气怎么样` session=`jev-shadow-enable-probe`
+- **实际输出（日志）**：
+  - `jevdecide realtime shadow mode=shadow rule=true jev=true confidence=0.997951 margin=0.99590182 agree=true`
+  - `jevdecide profile shadow mode=shadow rule_bucket=low jev_bucket=low … agree=true`
+- **业务回复**：天气问答正常（fail-open / shadow 不改规则路径语义）
+- **判定**：PASS
+- **耗时**：chat 端到端 ~15s
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+
+NOT REQUIRED（运维启用；产品评测/soak 见既有 shadow 报告）。本报告不记产品测试 PASS。
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+
+- **local_dev shadow 已启用且端到端可观测**。
+- 回退：`configs/.env.dev` → `JEV_DECIDE_MODE=off` 后 recreate app。
+- 后续：真实轮浸泡计数；用户单独授权后再开 `assist`。compose 默认保持 `off`。

.doc/test-reports/2026-09-24-jev-mcp-integration-test-report.md

@@ -0,0 +1,74 @@
+# jev-service 治理侧 MCP 集成 测试报告
+
+## 一、 测试背景 (Background)
+
+将本机 jev-service（类型化 `/v1/decide`）以独立 MCP 服务器接入 Agent-System 治理链路，供 agent 在任务分级、验证层级等封闭枚举决策点调用。凭证仅存本机 `~/.secrets/jev/`，不进入仓库。
+
+## 二、 测试目标 (Test Objectives)
+
+- MCP stdio 握手（initialize / tools/list）成功
+- `jev_health` / `jev_decide` 对本机 `http://127.0.0.1:8767` 真实可用
+- 错误 API key 返回 401 且 MCP `isError=true`
+- frp 备用 URL 可真实 decide
+- 资产目录无 API key 明文泄漏
+- 产品 PI 全链路：NOT REQUIRED（工程 MCP/文档变更；依据 PROJECT.md 验证入口与 test-reports-standard 纯工程例外）
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+
+- OS：Linux；Node：v26.9.0
+- jev-service：本机 :8767 + frp `https://fun.u1680832.nyat.app:34608`（healthz 均 ok）
+- 被测：`.worktrees/jev-mcp-integration-2026-09-24/scripts/mcp/jev-mcp.mjs`
+- 层级：MCP 协议冒烟 + HTTP 端到端；无 Go/前端回归要求
+- 证据：`.doc/test-reports/assets/2026-09-24-jev-mcp-integration/`
+
+## 四、 预期结果 (Expected Results)
+
+| 用例 | 预期 |
+|---|---|
+| initialize | serverInfo.name=`jev` |
+| tools/list | 含 `jev_health`、`jev_decide` |
+| decide（文档小改） | tier≈single_task；validation≈doc；低风险 |
+| 401 | isError + unauthorized 文案，不崩溃 |
+| frp decide | HTTP 成功返回 answers |
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+
+### 用例 1：MCP 握手 + 本地 decide
+
+- **测试输入 (Input)**：NDJSON initialize → tools/list → jev_health → jev_decide（任务分级+验证层级+是否开 worktree）
+- **实际输出 (Actual Output)**：见 `assets/2026-09-24-jev-mcp-integration/01-local-handshake-decide.decoded.json`
+  - health：`ok=true`，base_url=`http://127.0.0.1:8767`
+  - answers：`tier=single_task` confidence≈0.909；`validation=doc` confidence≈0.996；`needs_worktree=no` confidence≈0.917
+- **评价判定 (Evaluation / Verdict)**：PASS
+- **性能与耗时 (Duration & Latency)**：整批 MCP 往返约 2.2s（含 3 问 decide）
+
+### 用例 2：401 负例
+
+- **测试输入 (Input)**：`JEV_API_KEY=definitely-wrong-key` + jev_decide
+- **实际输出 (Actual Output)**：`isError=true`，文案 `jev_decide unauthorized (401): check ~/.secrets/jev/api.key or JEV_API_KEY`（`02-auth-401.decoded.json`）
+- **评价判定**：PASS
+- **性能与耗时**：约 3s 内返回
+
+### 用例 3：frp 远程 decide
+
+- **测试输入 (Input)**：`base_url=https://fun.u1680832.nyat.app:34608`，validation 六类选择
+- **实际输出 (Actual Output)**：`validation=script` confidence≈0.668（`03-frp-decide.decoded.json`）——本批改动含 MCP 脚本，script 合理；置信中等，技能约定应回退 agent 自判
+- **评价判定**：PASS（连通与契约正确；中置信按设计不强制采纳）
+- **性能与耗时**：约 3s 内完成
+
+### 用例 4：探活延迟与密钥泄漏扫描
+
+- **实际输出**：`04-latency.txt` — local healthz ≈2ms；frp ≈49ms；`grep` 资产目录无 key 明文
+- **评价判定**：PASS
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+
+- `go test ./...`：NOT REQUIRED（未改 Go；工程 MCP/文档）
+- 产品 PI Runner：NOT REQUIRED（同上）
+- 本轮执行：MCP NDJSON 真实调用 4 组 + curl healthz 双端点
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+
+- 治理侧 MCP 接入达到合入标准：握手、鉴权、本地/frp decide、错误路径均有真实证据。
+- 合入后需在 Cursor 重载 MCP 以加载 `jev` server。
+- 后续（另授权）：产品侧 shadow 评测与低风险决策点灰度，不在本任务范围。

.doc/test-reports/2026-09-24-jev-product-shadow-test-report.md

@@ -0,0 +1,69 @@
+# jev-service 产品侧 shadow 接入 测试报告
+
+## 一、 测试背景 (Background)
+
+将本机 jev-service（类型化 `/v1/decide`）接入产品 Go 路径。设计为三层回退：默认 `JEV_DECIDE_MODE=off`、规则路径始终可走、shadow/assist 失败 fail-open。
+
+## 二、 测试目标 (Test Objectives)
+
+- P0 gate 1：realtime 准确率 ≥85% 且高置信 precision ≥95%；profile 分桶一致率 ≥75%
+- P1/P2：客户端 httptest 覆盖；mode=off 与纯规则逐例等价；shadow 不改路由；assist 仅增 realtime 召回
+- P3 gate 2（合成 soak）：≥200 轮、失败率 <2%、平均附加延迟 <300ms
+- P4：assist 代码就绪但默认 off；回退演练 PASS；**assist 放量需用户另确认**
+
+## 三、 测试方案与环境 (Test Plan & Environment)
+
+- OS：Linux；Go 1.27.1；jev-service `:8767`（healthz ok）
+- 评测集：`internal/jevdecide/testdata/eval-v1.json`（113 条）
+- 证据：`.doc/test-reports/assets/2026-09-24-jev-product-shadow/`
+- 产品 PI 全链路：NOT REQUIRED 作为本任务放量条件（默认 flag off；U8 nightly 过滤器未改）。依据：验证契约工程/Go 包变更 + flag 默认关闭
+
+## 四、 预期结果 (Expected Results)
+
+见目标阈值；mode=off 零行为差异。
+
+## 五、 实际测试结果与判定 (Actual Results & Evaluation)
+
+### 用例 1：P0 离线评测（真实 jev）
+
+- **输入**：`RUN_JEV_EVAL=1 go test ./internal/jevdecide -run TestOfflineEvalAgainstLiveJev`
+- **实际输出**（`p0-offline-eval.json`）：realtime accuracy **100%**（45/45），high-conf precision **100%**（44/44）；profile agreement **96.2%**（51/53）
+- **判定**：PASS（gate 1）
+- **耗时**：~31s
+
+### 用例 2：客户端单测
+
+- httptest：成功/401/5xx/坏 JSON/超时/熔断/profile bucket — `go test ./internal/jevdecide` PASS
+
+### 用例 3：shadow / assist / fail-open / mode=off
+
+- `decide_assist_test.go` + `TestModeOffByteEquivalentRealtime` PASS
+
+### 用例 4：合成 soak（≥200 轮真实 jev）
+
+- **输入**：`RUN_JEV_SOAK=1 go test ./internal/coordinator -run TestShadowSoakReplay`
+- **实际输出**（`p3-shadow-soak.json`）：turns=200，agree=196，disagree=4，jev_fail=0，latency_ms_avg=268
+- **判定**：PASS（失败率 0%<2%；均延迟 268ms<300ms）。4 条 disagree 为 shadow 观测，不改路由；人工复核见资产 JSON
+- **注**：此为评测语料重放，非线上真实对话窗；线上 3 天浸泡仍建议在 assist 放量前补做
+
+### 用例 5：架构与回归
+
+- `./scripts/arch-check.sh --mode block` PASS
+- `go vet` 相关包 PASS
+- `go test -short` 本任务包（jevdecide/coordinator/config/sysadmin/archtest）PASS
+- 主 tip 上既有 `docquery` Consistency:missing 失败与本改动无关（主目录复现）
+
+## 六、 自动化测试套件汇总 (Test Suite Execution)
+
+| 命令 | 结果 |
+|---|---|
+| `go test ./internal/jevdecide`（含 SKIP 的 live eval） | PASS |
+| `RUN_JEV_EVAL=1 … TestOfflineEvalAgainstLiveJev` | PASS |
+| `RUN_JEV_SOAK=1 … TestShadowSoakReplay` | PASS |
+| `arch-check --mode block` | PASS |
+
+## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
+
+- **可合入 local_dev**：shadow 接线完成，默认 `off`，回退 = 保持/改回 `JEV_DECIDE_MODE=off` 重启。
+- **assist 不自动开启**：需用户阅读本报告后显式授权把 dev 设为 `assist`（仅 realtime 增召回）。
+- 建议：线上 shadow 浸泡 ≥200 真实对话轮后再签 assist。

.doc/test-reports/assets/2026-09-14-final-artifact-vault/unit-tests-gapfill.txt

@@ -0,0 +1,48 @@
+=== RUN   TestEvaluateEligibility_Allowlist
+--- PASS: TestEvaluateEligibility_Allowlist (0.00s)
+=== RUN   TestEvaluateEligibility_ApprovedRequiresReviewSnapshot
+--- PASS: TestEvaluateEligibility_ApprovedRequiresReviewSnapshot (0.00s)
+=== RUN   TestEvaluateEligibility_TaskWithoutCompletedTurn
+--- PASS: TestEvaluateEligibility_TaskWithoutCompletedTurn (0.00s)
+=== RUN   TestEvaluateEligibility_SensitiveRejectedBeforeStaging
+--- PASS: TestEvaluateEligibility_SensitiveRejectedBeforeStaging (0.00s)
+=== RUN   TestEvaluateEligibility_CopyOnlyRequiresExplicitPinAfterCompleted
+--- PASS: TestEvaluateEligibility_CopyOnlyRequiresExplicitPinAfterCompleted (0.00s)
+=== RUN   TestEvaluateEligibility_UnknownTypeRejected
+--- PASS: TestEvaluateEligibility_UnknownTypeRejected (0.00s)
+=== RUN   TestPublisherIdempotentAndCrashSafe
+--- PASS: TestPublisherIdempotentAndCrashSafe (0.00s)
+=== RUN   TestPublisherRejectsBadSHAAndCrossProjectKeys
+--- PASS: TestPublisherRejectsBadSHAAndCrossProjectKeys (0.00s)
+=== RUN   TestFilesystemRefusesRuntimeDataDev
+--- PASS: TestFilesystemRefusesRuntimeDataDev (0.00s)
+=== RUN   TestTombstoneUnionDeny
+--- PASS: TestTombstoneUnionDeny (0.00s)
+=== RUN   TestLastReferencePurgeAndLegalHold
+--- PASS: TestLastReferencePurgeAndLegalHold (0.00s)
+=== RUN   TestFilesystemIdentityMismatch
+--- PASS: TestFilesystemIdentityMismatch (0.00s)
+=== RUN   TestUnpublishedWithoutCommitMarkerInvisible
+--- PASS: TestUnpublishedWithoutCommitMarkerInvisible (0.00s)
+=== RUN   TestPublisherRetriesAfterMissingCommit
+--- PASS: TestPublisherRetriesAfterMissingCommit (0.00s)
+=== RUN   TestDegradedPayloadDoesNotWrite
+--- PASS: TestDegradedPayloadDoesNotWrite (0.00s)
+=== RUN   TestApplyRecoverAsCollectionWritesScratchAndSkipsDenied
+--- PASS: TestApplyRecoverAsCollectionWritesScratchAndSkipsDenied (0.00s)
+PASS
+ok  	chat-agent-system/internal/artifactvault	0.004s
+=== RUN   TestValidateIndependentVault
+--- PASS: TestValidateIndependentVault (0.00s)
+PASS
+ok  	chat-agent-system/internal/config	0.002s
+=== RUN   TestFinalizeTaskRunCompletesTurnAndIngests
+2026/09/14 12:51:53 [kb] 无法连接到 PostgreSQL 知识库 (postgres://:@:0/?sslmode=disable): cannot parse `postgres://:xxxxx@:0/?sslmode=disable`: invalid port (outside range), 将降级运行在离线模式
+--- PASS: TestFinalizeTaskRunCompletesTurnAndIngests (0.00s)
+=== RUN   TestTryVaultDegradedDoesNotRequest
+--- PASS: TestTryVaultDegradedDoesNotRequest (0.00s)
+=== RUN   TestServer_PinExportCopyOnlyAfterCompleted
+2026/09/14 12:51:53 [kb] 无法连接到 PostgreSQL 知识库 (postgres://:@:0/?sslmode=disable): cannot parse `postgres://:xxxxx@:0/?sslmode=disable`: invalid port (outside range), 将降级运行在离线模式
+--- PASS: TestServer_PinExportCopyOnlyAfterCompleted (0.12s)
+PASS
+ok  	chat-agent-system/internal/server	0.131s