# 治理反馈闭环

老板-员工手册隐喻：用户发现子项目不足 → 告诉炼境（结构化落账）→ 炼境更新"企业文化与员工手册"（CONVENTIONS 规则 + 接入包模板）→ 批量分发给子项目 → 飞轮观测新规则是否生效。

## 为什么

- 现在用户发现子项目问题只能在会话里口头说（如 2026-07-06 的 group_id 探路问题），不落任何结构化通道，问题→体系改进全靠当次会话的执行力，跨会话就丢
- 治理管线已存在大半（blueprint-governance 的规则编辑与批量同步、blueprint-feedback 的梦核蒸馏、onboarding-pack 的模板版本化分发），但三处断环让"反馈驱动体系进化"没有闭合

## 三个缺口（待 /architect 细化）

### ① 治理反馈入口
- 现状：`append_project_note` 挂单项目、无类型标记，是"员工工作日志"而非"给老板的管理反馈"
- 方向：`report_governance_feedback` 类入口（MCP 工具优先，UI 上报按钮可后置），记录：哪个项目、什么问题、疑似哪条规则/模板缺陷；落 project_notes 加类型字段或独立治理账本表
- 形态待定：MCP 工具 vs UI 按钮 vs 笔记类型约定（三选或组合，architect 阶段定）

### ② 反馈进入梦核蒸馏
- 现状：梦核吃被动数据（commit 指标、复盘笔记、停滞模块、高风险 scope）
- 方向：用户主动治理反馈作为梦核 prompt 的高权重数据段（老板亲口说的问题 > 统计推断的问题），蒸馏产出规则修订/模板修订建议

### ③ 接入包批量重分发
- 现状：`sync_blueprint_rules` 有批量，但接入包 `apply_onboarding_pack` 单项目一次一发；模板更新后无"全员换发新手册"动作
- 方向：批量 re-apply（复用 ONBOARDING_MANAGED 块安全覆写机制），输出报告：哪些项目更新了哪些块、哪些跳过/失败

## 闭环全景

```
发现问题 → ① 结构化落账 → ② 梦核蒸馏 → 更新 CONVENTIONS/模板
    ↑                                        ↓
飞轮观测生效（Rules-Applied trailer / 复盘） ← ③ 批量分发
```

每一环都有数据留痕，管理动作可回溯。

## 设计档案：agent 自验协议的辩证与务实版选择（2026-07-06）

用户确立的协作协议：**需求对话 → 构建默认 agent 按钮化 → agent 自验 → 快速自修 → 结构化反馈 → 人终验**。经多角度辩证后识别出五个内生张力与对应调节器，最终按"大量开发者经验（流程死于执行成本而非设计错误；检查单短才有效；机制记的留下、靠记忆的蒸发）"选择**最小执行版**落地，完整辩证存档于此备查：

| 内生张力 | 调节器 | 关键点 |
|---------|--------|--------|
| 运动员兼裁判（验证与功能共享理解偏差） | 负面披露（「没验什么」一节） | 只覆盖已知盲区；未知盲区由人终验兜底——两柱互补，缺一超载。实证：mcp-single-server 自验全绿但 git-bash 层全挂，靠端到端终验抓住 |
| Goodhart（宽松断言让自己过） | 改断言需报备 | 非自觉依赖：断言修改在 diff 天然可审计 |
| 橡皮图章化（终验退化为签字） | 意外感触发深查 | 深查频率是自由参数，框架内无机制阻止衰减——最终锚是人的纪律，框架诚实承认此点方自洽 |
| 默认按钮化 vs 少而稳 | 默认分层 | 默认的是"存在可验证路径"，不是"永久驻军测试"；豁免需声明 |
| 不可按钮化工作（审美/体感/探索） | 显式豁免 | 强推得到仪式性假按钮 |

**关键澄清（两把尺子）**：acceptance 由 agent 参与撰写，可能继承需求理解偏差——agent 自验对 acceptance，人终验必须对**意图**，否则是拿被污染的尺子量两次。

**落地物**（最小版，执行成本趋零）：AGENTS.md / 接入包模板 / agents-meta-rules 增设「自验报告纪律」三条；用户侧两个习惯（先看「没验什么」；意外感或外部契约变更时深查）。刻意不做：新工具、强制 hook、报告模板系统——坑驱动增量，人肉版跑出疼点后再在本模块机制化。

## 使者回传处置台账（2026-07-18 消化，共 23 条）

### 已落地（本轮 3 项）
- **/ship 三处模板修正**（`~/.claude/commands/ship.md`，全局命令即分发源）：① blueprint 尾 commit 铁律改为「每轮 /ship 的最后一个 PR 末位 commit」（多 PR 场景 manifest 单文件不可能每 PR 都带）；② 规模闸补两个不可拆例外（单一功能域强耦合 / 全新业务线初版）→ 警告放行不阻塞；③ MCP 连接错误注明可原地重试 2~3 次（偶发抖动非业务失败）
- **envoy.md 分类硬门槛**（接入包全托管文件）：Step 3 前置追问「任何有经验的工程师是否会提前想到？」——常识性知识与过窄 corner case 一律留本项目，堵住 2 例误回传的根因
- **CONVENTIONS v1.12.0**：飞轮工作流阶段 2 末新增「动工前辩证收缩」（M/L 卡必做），实证返工率对照写入

### 此前会话已落地（11 条，本轮核实关闭）
MANAGED 块警示（5b0b068）、Bug Fix/Feature 分类 + S 级轻量卡 + 汇总补录限定语（67bdacb AGENTS v1.5.0）、蓝图机器门控（f04eb6e blueprint-gate 双层，回应 07-09「文档约束无机器门控」假设）、lefthook API typecheck 必填项 + CONVENTIONS scope 前置提示（be2f695 v1.11.0）、Playwright 版本锁死（AGENTS tmpl）、agent_verify/human_verify 分层（AGENTS + CONVENTIONS）、/ship 阶段八 rebase 前 stash 保护（已在 ship.md）、空路径分发防护（473cf7e）

### 待观察（log_for_review，暂不动模板）
- **verify_onboarding lefthook 键名匹配是名义非语义**：等价功能不同键名会误报缺失；enterprise-system 6/7 fail 待核实是缺失还是改名
- **/ship 运行期间并行开发混入变更**（under_validation）：建议最终报告对比第零步 status 快照、新增变更单独列出不纳入本轮——再积累 1~2 次实例后进模板
- **/antirot 命令模板化**：enterprise-system 实现的文档防腐命令（机器验+文档一致性+蓝图健康三步），候选纳入接入包标配
- **Loop 模型路由**（Haiku=Observer / Sonnet=Actor）与**种子层/土壤层分工**：enterprise-system 特有 Loop 体系，尚不构成跨项目通用约定，观察其长期效果
- **OpenAI SDK tool_calls 联合类型守卫**：可作 AI 代码审查检查项候选（project_type:web）

### 遗留尾巴
- ~~src-tauri/ 下空路径污染残留~~ → 2026-07-18 辩证收缩后三步收官：①9 个污染文件已移出（暂存 `%TEMP%\liangjing-pollution-20260718`）；②两条空路径僵尸登记（agent编排界面(opencode)/银龙集团应用）已 unregister（磁盘无对应目录，实为死登记）；③辩证挖出 **inject 链路漏拦同一空路径洞**（`project_root()` 对空串 win_path 穿透写 cwd，正是 settings.json/liangjing.json 污染的来源）——已单点补 `validate_registered_path`（拒空+拒相对路径）+ 2 条回归测试。空路径事故至此两链路（apply/inject）全堵
- envoy.md 硬门槛已进模板，**需重建安装炼境后 apply 才会分发到子项目**（模板打包在二进制资源）

## 使者回传处置台账 · 第二轮（2026-09-11 分诊，覆盖 07-22→08-23 共 36 条）

> **通道缺陷实锤升级**：第一轮已消化的 23 条至今仍挂在 `list_envoy_returns`「待处理」列表——
> 回传只进不出，无回执标记。在缺口①机制化之前，本台账是唯一消化凭证；
> notes 档案落地卡（下方）因此优先级上调（它是回执机制的地基）。

### 已消化 6（有落点证据，直接关闭）
- 世界模型同构（08-23）→ 本文件「开发侧世界模型透镜」节
- 新 agent CLI 接入模式（08-23）→ dsh-takeover-readiness T3 卡吸收
- 换主力前基线快照（08-23）→ dsh-takeover-readiness T4 卡吸收
- 统计先于自动化闸门（08-23）→ dsh-takeover 辩证收敛③已实际应用（上游化否决即用此模式）
- Gitea 1.22 无 actions API 的替代路径（07-24）→ cicd-workflow.md「本机 CI runner 速查」（09-11 回流）
- get_ci_status 三态语义（07-23 报）→ 代码已修（gitea.rs 结论三分支 ✅/❌/⏳），09-11 实调 success 路径验证

### 已过时 1
- DSH 0.1.1-rc.2 坑清单（08-23）→ 0.1.5 时代大半失效，`.dsh/README.md` 活文档为单一来源，炼境侧无动作

### 待行动 10 → 收敛为 3 张候选卡（见下方任务卡；模板变更属 Feature，执行前须用户确认）

### 仅归档 19
- **模式库候选 +11**（透镜节闸门证据显著加厚）：三资产闭环 / NL→过滤服务端验证 / DualScopeBridge /
  crypto.randomUUID 非安全上下文 / DB 触发器审计注册表 / ALS+postgres-js 注入 / capacitor 三条 /
  ssh-action secrets envs / 部署脚本 git pull 自更新延迟
- **/ship 规模闸实证 ×3**（超大 PR 例外有效 / L1 无人值守例外放行 / MCP 断连续接有效）→ 喂「/ship 体检」卡的阈值复核
- **挂触发 ×2**：SQL migration 文件漏提交检测（再发一例立卡）；blueprint-gate files 重叠误标 🔵
  （与 gate 信噪比增强同域，同一触发条件合并观察）
- **review 体系设计输入 ×2**：对抗验证系统性过滤结构性建议 / 严苛 review 标准条件性收益——review 体系动工时消费
- **坑库候选 ×1**：Windows 复制 SSH 私钥须 `cat | clip` 保 LF（CRLF 致 ssh-action 静默失败）

## 开发侧世界模型透镜（2026-08-23 辩证收敛）

> 源头：enterprise-system 使者回传「炼境=开发侧世界模型容器」（2026-08-23）+ 业务侧四载体
> （vision-world-model.md / estate1-world-model.md / hub-relation-catalog.md / hub-matrix-biz-ecology.md）回顾。
> **合题：世界模型是透镜，不是工程**——用透镜照出真实病灶就修，其余全部挂闸门。

### 同构映射（业务侧 ↔ 开发侧）

R 规则层=CONVENTIONS 规则库（炼境强项，业务侧反而隐式）｜E 实体层=项目/模块/任务卡/服务器（实体丰富、跨项目关系贫乏）｜A 资产层=接入包（唯一模式雏形）｜地图=单项目蓝图画布（无全局）｜可拆除性=资产纯文件 git（notes 是唯一违规点）。

### 两处判断修正（辩证结论，防后续会话重新推演）

1. **「独立世界仓库」被否**：现在只有一个住户（notes 档案），为一个住户建仓库违反晋升阶梯（第二个场景才晋升）。炼境自身仓库本来就是事实上的元仓库，跨项目资产先住这里。
2. **可拆除性缺口比直觉窄**：飞轮数据可从 git 历史重生（ingest_git_history=重生配方），不违规；**唯一硬违规是 project_notes**（复盘笔记+使者回传，原创不可再生，只活在 SQLite）——即下方 A 卡。

### 三个闸门（等真实场景敲门，禁止提前建设）

| 候选 | 闸门条件 | 备注 |
|------|---------|------|
| 跨项目 edges | 第一个真实跨项目查询需求（最可能从梦核来） | 方案已定：自省派生 ∪ 显式声明（继承 hub-relation-catalog） |
| 全局地图视图 | edges 落地之后 | 开闸时先辩证「矩阵 vs 画布」——manage-multi-view 已承载一半需求，勿撞车；节点须双承载（入口+健康度） |
| 模式库 | ⚡ 闸门已敲响（2026-08-23 第三候选到位，待用户决定开建） | 接入包=第一个模式，库=接入包机制泛化；三候选：DSH 接入模板（活文档在 enterprise-system/.dsh/README.md，**炼境不复抄**——第二消费者出现时直接从活文档拷）、子主题规范、**dev path 定位投影**；09-11 分诊归档再 +11 候选 |

### 三投影准入律（新资产类型的验收清单）

任何新世界模型资产类型，三投影不齐不算入模：**文件形态**（git 可拆除）+ **MCP 工具**（agent 可消费）+ **UI 投影**（人可终验）。

### 已否决方案存档：用 enterprise-system 框架整体重构炼境（2026-08-23 辩证，用户暂存待续）

**结论：整体重构否决，机制移植推荐（种子拿来，土壤留下）。**

三个硬阻断：① 炼境命根子是"本地之手"（启动编辑器/写本地文件/git/托盘），web 栈给不了，重构完仍需本地 daemon，架构更重；② 数据哲学正面冲突——enterprise「页面身份在数据库」vs 炼境「可拆除性：资产=文件在 git」，搬进配置引擎 DB 是哲学掉头；③ 单用户桌面背不动多用户 web 引擎的权限/隔离死重。收益错位：世界模型瓶颈（edges 无数据/无消费场景）没有一个是 UI 框架造成的。

**种子清单**（可移植机制，经模式库通道逐颗引入）：dev path 定位投影（下方 💭 卡）、view-lab 多维视图交互（做 manage-multi-view 时借）、关系目录方法论（已继承为 edges 方案）、Hub 矩阵交叉点双承载（地图开闸时用）、注册表反转三件套（设计纪律）。

**反转条件**（出现再重估引擎化）：① 需要多端/远程访问 → 届时是"炼境长出 web 投影"非重构本体；② 实体清单页持续增殖（现 15+ 张）→ 届时炼境内部长轻量配置化表格引擎，只管新页不回迁旧页。

### 💭 DevPath 卡 1：模板契约层「定位投影」
- status: concept
- 内容：AGENTS.md.tmpl agent 按钮节新增「定位投影（dev path）」条——UI 项目应提供 DEV 浮层，一键复制"当前页面 → 代码/配置锚点"（ROUTE/CODE/DATA/STATE 四段契约），参考实现 enterprise-system `components/DevPathHint.tsx`；自身 AGENTS.md + meta-rules 同步。S 级，1.7.0 若仍未分发可补遗不升号
- 概念定位：dev path = 人这边的发话按钮——agent 按钮让 agent 能做，dev path 让人能说（把"我在这里"的手势转成 agent 可解析地址）；搭配截图 = 人语视觉参照 + agent 语机器锚点双通道

### 💭 DevPath 卡 2：炼境自建 DevPathHint（吃自己狗粮）
- status: concept
- 内容：新增 `src/components/DevPathHint.tsx` + App 挂载，DEV 环境左下浮层：当前路由 → 页面组件文件路径 → 选中项目/模块 ID，一键复制。M 级
- 注意：炼境页面是代码路由非配置驱动，价值低于 enterprise 版（那边 grep 会扑空，这边 grep 通常能中）——实现时保持轻量，勿照抄其配置推导层

## 任务卡

### ✅ notes 档案落地（可拆除性修复：双写 + 存量回填）· done 2026-09-11
- status: done
- complexity: M
- files: src-tauri/src/mcp_tools.rs, src-tauri/src/mcp_inject.rs（原卡列 db.rs 实际未动——无新表，纯双写层）
- acceptance: agent_verify: [Tauri command] append_project_note(pid, content) → DB 有记录**且** `.blueprint/notes-archive.jsonl` 尾行 JSON 可解析出同一 content；存量回填命令执行后 JSONL 行数 = project_notes 表行数；cargo test 覆盖双写 + 并发追加不交错 ✅（110 测试全绿含新增 3：双写行匹配 / 回填幂等+死登记跳过 / 8 线程并发不交错）
- **归宿翻转声明（动工前辩证，偏离原卡设计）**：原卡「炼境仓库集中式档案」→ 改为**按项目分片**
  （各项目 `.blueprint/notes-archive.jsonl` 存自己的笔记）。理由：① 安装态进程无法可靠定位「炼境仓库」路径；
  ② 与「资产=纯文件在项目 git、可拆除性按项目」哲学一致（透镜节 .blueprint 分片描述）；③ 子项目会话
  （含 DSH，文件直读）就地消费自家档案；④ usage.json 先例本就是 per-project 写入
- 实现留痕：双写失败不回滚笔记（DB 事实源）仅 log_event warn；`backfill_notes_archive` MCP 工具
  全量重建幂等自愈；死登记（空/相对路径）跳过并报告（复用 validate_registered_path 防护，
  project_root 重构出依赖注入版 project_root_with_conn）
- **待重建终验**：MCP 实调（append 双写 + backfill 存量 78+ 条笔记落盘）需重建安装炼境后执行

### 📋 /ship 模板体检（第二轮分诊待行动 ×4）
- status: todo
- complexity: S
- files: ~/.claude/commands/ship.md（全局命令即分发源）
- 内容：① CI 轮询预算改指数退避、上限 20 分钟，push 侧 job 成功作提前信号提示；② 注明「PR 是否已存在以
  create_pull_request 的 already_exists 为准，get_pr_events 有延迟仅作辅助」；③ 600 行规模闸口径复核——
  例外命中率长期近 100%（实证 3 例见归档），评估改按「新文件占比」；④ review 环节机械阈值（行数/any/import 违规）
  下放 lint，prompt 只留机器验不了的判断
- acceptance: `[人工] ship.md diff 覆盖 4 项；[实战] 下次 /ship 无对应摩擦复发（轮询不被人工打断、无 PR 误判）`

### 📋 /envoy 模板体检（第二轮分诊待行动 ×2）
- status: todo
- complexity: S
- files: src-tauri/resources/onboarding/ 内 envoy 模板 + docs/templates/ 同步（onboarding-sync 规则：升版本号）
- 内容：① Step 2 增显式提示「凡涉及炼境自身定位/缺口/演进方向的讨论，默认进带回候选清单」（愿景类漏传实锤）；
  ② 增 MCP 不可用时的降级指引（SDK 直连脚本兜底路径）。
  ~~③ .dsh 形态~~ → 辩证后挂「Claude 退出终审席」触发（当下由终审会话代传，见 dsh-takeover 协作模式纪律 4）
- acceptance: `[cargo] cargo test onboarding 通过（版本号已升）；[分发] 重建安装后 apply，子项目 envoy 文件含两段新增`

### 📋 接入包杂项挂车批（第二轮分诊待行动 ×4，不单独发车）
- status: todo
- complexity: S
- 内容：挂「下次模板升版本批车」顺路带走——① migration 建号前必 `ls` 目录取真实最大号；② 写配置 migration 前先
  SELECT 消费方实际使用的 key；③「挂起模块 × 新模块」双向留痕进 CONVENTIONS「何时更新蓝图」候选场景；
  ④ 文档防腐铁律加注「prompt/skill 文件豁免删冗余——重复是遵循度手段，非腐化」
- acceptance: `[人工] 下次模板批 diff 含 4 项；版本号随批次升级`

（其余 concept 阶段，L 级——待 /architect 设计确认后由 /splitter 拆卡）