depa-codument 0.4.1

package/src/templates/codument/std/spec/flow-notation.md

@@ -0,0 +1,93 @@
+# Flow Notation 规范
+
+复杂 operation / skill / actor drive 的流程不要只靠散文描述。凡是涉及事件路由、阶段切换、循环、分支、等待回执、失败退出的内容，用 Markdown 说明背景，用 `text` 围栏内的流程标记块表达可执行控制流。
+
+## 开头约定
+
+每个流程标记块开头建议先写三行自解释声明，让新读者不需要猜符号含义：
+
+```text
+@delimiter: --      # 块深度分隔符；根层 --，每深入一层多一个 --
+@node: #            # 流程节点前缀；对应 XML/AST 中的节点名，如 #switch / #case / #step / #loop / #return
+@marker: ?          # 块标识 / 跳转锚点前缀；如 ?event / ?confirm / ?done
+```
+
+含义：
+
+- `@delimiter: --` 定义层级单位。`--` 是根块，`----` 是子块，`------` 是孙块。
+- `#` 后面是流程节点名，说明这一块怎样执行：分支、步骤、循环、返回、退出等。
+- `?` 后面是块标识，用于开闭块配对，也可作为 `#goto target="?xxx"` 的跳转锚点。
+
+## 何时使用
+
+使用流程标记块表达：
+
+- operation 的程序化执行流程。
+- SKILL.md 的全局事件路由。
+- actor 的 `drive.md`：该 actor 收到某类消息后如何分支、何时返回给主流程。
+- 有明确控制语义的规则：硬闸、一次一动作、等待回执、重试、漂移再收敛、收口。
+
+不要用流程标记块表达：
+
+- 概念解释、术语定义、字段说明。
+- JSON schema、卡片 markup、命令示例。
+- 单纯的注意事项列表。
+
+## 基本语法
+
+写在 ```` ```text ```` 围栏里：
+
+```text
+@delimiter: --
+@node: #
+@marker: ?
+-- #switch ?event on="当前输入 / 回执"
+---- #case ?collect when="首次收到用户请求"
+------ #step ?resolve
+发起期望态补全动作；发出后停手等待回执。
+------ /?resolve
+---- /?collect
+---- #case ?done when="实际态已收敛"
+------ #return ?finish value="收口"
+------ /?finish
+---- /?done
+-- /?event
+```
+
+规则：
+
+- 开块格式：`<delimiter-depth> #node ?marker [key="value"]`。
+- 闭块格式：`<same-depth> /?marker`。
+- 每个块必须闭合，开闭的 `?marker` 必须一致。
+- payload 顶格写自然语言，不需要缩进，不需要转义 `<...>`、`|`、`&`。
+- 条件谓词是给 AI 读的自然语言，不是编译器表达式。
+
+## 节点词汇
+
+| 构造 | 用途 |
+|---|---|
+| `#switch` / `#case` / `#default` | 事件路由、状态分派、回执判因 |
+| `#sequence` | 固定顺序执行的一组动作 |
+| `#parallel` | 并行执行一组动作；可带 `limit` |
+| `#step` | 单个动作或判断点 |
+| `#if` / `#else-if` / `#else` | 局部分支 |
+| `#loop` | 反馈循环、重试循环、reconcile loop |
+| `#return` | 返回当前流程结果 |
+| `#exit` | 发出动作后终止本回合，等待用户或工具回执 |
+| `#goto` | 在同一流程块内跳到已命名锚点，慎用 |
+| `#fail` / `#on-fail` | 明确失败和失败处理 |
+| `#spawn` | 需要 fresh 子代理 / 独立执行者时使用 |
+| `#call` | 调用另一个流程 / skill / SOP |
+
+## SKILL.md 与 actor drive.md 的分工
+
+- `SKILL.md` 写全局事件路由：先判硬闸，再按事件读取精确 paths，再发唯一真动作或等待。
+- `actors/*/drive.md` 写 actor 内部局部流程：它收到什么、如何判断、返回什么给主流程。
+- `contract.md` / `messages.md` 不承载复杂控制流；它们只定义契约和消息形状。
+
+## 写法纪律
+
+- 流程块里的每个 `#case` 只允许读取该 case 明确列出的 paths。
+- 发出真动作后用 `#exit`，不要继续解释或追加第二个动作。
+- 主流程等待外部回执时，明确写“等待什么回执”，避免 AI 自行用页面状态猜测。
+- 复杂流程优先拆成“SKILL 全局路由 + actor 局部 drive”，不要把所有细节塞进一个巨大的流程块。

package/src/templates/codument/std/spec/folder-manifest.md

@@ -0,0 +1,99 @@
+# 目录职责自描述与补齐（std/spec/folder-manifest.md）
+
+> 解决一个问题：分形 docs **不应强依赖一份中心规范**去说明"每个标准文件夹装什么"。每个文件夹应能在**自己**的 `index.md` 里**独立声明**职责；不同业务领域长出的自定义文件夹也能自带说明。本规范定义这套**自描述格式**，以及一个**补齐（backfill）机制**给缺失的文件夹补上声明。
+>
+> 它与 [docs-*-fractal](@codument/std/docs-modeling-fractal/index.md) 互补：分形 index 给"递归规则 + 默认类目词汇"；本规范给"每个具体文件夹**就地**钉死它装什么"。层级与晋升语义见 [std/attractors/knowledge-tiers.md](@codument/std/attractors/knowledge-tiers.md)。
+
+## 1. 目录职责块（写在该目录的 `index.md` 里）
+
+每个**标准化文件夹**的 `index.md`，在 H1 标题下方紧跟一个**目录职责块**。两种规模：
+
+**精简型（一行 blockquote，多数叶子类目用）**：
+
+```markdown
+# <Folder> ...
+
+> 目录职责 · holds: <一句话：装什么> · excludes: <一句话：不装什么> · tier: stable|dated · ⬆from: <晋升来源> · ⬇to: <晋升去向>
+```
+
+**完整型（plane / context / 根这种结构节点用）**：
+
+```markdown
+## 目录职责
+
+- **holds**：本目录拥有……
+- **excludes**：不属于这里的（去向）……
+- **tier**：`stable`（就地改）| `dated`（带日期记录）
+- **promotes_from**：上游来源层（哪些信息晋升到这里）
+- **promotes_to**：下游去向层（这里稳定后再晋升到哪）
+```
+
+字段语义（全部对齐 [knowledge-tiers.md](@codument/std/attractors/knowledge-tiers.md)）：
+
+| 字段 | 含义 | 缺省 |
+|---|---|---|
+| `holds` | 该文件夹**装什么**（一句话边界）；标准文件夹可引用分形默认类目语义 | 必填 |
+| `excludes` | **不**装什么 + 应去哪（防止相邻目录混淆） | 相邻易混时必填 |
+| `tier` | `stable`=owner 文档就地改；`dated`=带日期、归档不可变 | 必填 |
+| `promotes_from` / `promotes_to` | 晋升阶梯上的上下游边 | 知识层目录必填；纯导航目录可省 |
+
+> 这是**受控小块**，不是又一份 frontmatter。不要把真源正文塞进职责块——职责块只声明"边界与晋升边"，导航仍走 index 表格。
+
+## 2. 标准文件夹 vs 自定义文件夹
+
+- **标准文件夹**（分形默认类目：modeling 的 `objects/policies/workflows`、impl 的 `overview/howto/rules/...` 等）：职责可**继承分形默认**，职责块写一行即可（甚至只写与默认的差异）。
+- **自定义文件夹**（某业务领域自己长出来的类目，如 `sources/ transforms/ sinks/`、`runbooks/ slas/`）：分形规范**无法预知**，所以**必须**自带完整型职责块——这正是"允许在某个文件独立进行说明配置"的落点。
+
+> 规则：**任何不在分形默认词汇表内的目录，其 `index.md` 必须有职责块**；否则视为未声明，补齐机制会标记。
+
+## 3. 补齐机制（backfill / 补齐）
+
+目标：不必预先在中心文件枚举所有目录；缺声明的由机制扫描补上。**幂等**——只补缺失，不覆盖人工已写的块（除非显式确认）。
+
+步骤：
+
+1. **扫描**：遍历 `docs/`（及按需的知识层目录），对每个含 `index.md` 的目录检查是否有合法职责块。
+2. **判缺**：列出 (a) 缺职责块的目录；(b) 非默认词汇却无完整型块的自定义目录；(c) 职责块与实际内容/位置不符的目录。
+3. **生成**：对每个缺口，从下列来源合成职责块——
+   - 目录**名 + 在树中的位置** → 套分形默认类目语义；
+   - 目录**实际内容**（已有哪些文件/子目录）→ 收敛 holds/excludes；
+   - [knowledge-tiers.md](@codument/std/attractors/knowledge-tiers.md) → 定 `tier` 与 `promotes_from/to`；
+   - 推断不确定时**标 TODO/uncertainty，不臆造**；自定义目录语义模糊时提请人工确认。
+4. **写回**：把生成的精简/完整型块插到该目录 `index.md` H1 下；新增/改动登记到 `docs/migration-map.md` 若涉及路径。
+
+触发点：
+- **docs-bootstrap**：首次建分形 docs 时，为每个目录补齐职责块。
+- **artifact-sync**：归档同步**新建**目录时，顺手为新目录写职责块。
+- **validate**：作为一致性检查项（缺块 / 块与内容不符 → 报告）。
+
+## 4. 与中心声明的关系
+
+职责声明现在有两处，**就近优先**：
+
+- **就地（权威）**：各目录 `index.md` 的职责块——单一事实、独立可配。
+- **中心（导航）**：[knowledge-tiers.md](@codument/std/attractors/knowledge-tiers.md) 的分层表给"有哪些层、晋升怎么走"的总览；它**不**逐个枚举叶子目录。
+
+冲突时以**就地职责块**为准（它离真源最近）；中心表只在分层/晋升语义上兜底。
+
+## 5. 示例
+
+标准叶子（继承默认，一行）：
+
+```markdown
+# Resource Objects
+
+> 目录职责 · holds: resource context 的对象数据/行为真源 · excludes: 跨对象规则(→policies/) · tier: stable · ⬆from: track design 稳定后 · ⬇to: 代码/测试投影
+```
+
+自定义类目（必须完整型）：
+
+```markdown
+# Transforms
+
+## 目录职责
+- **holds**：数据管道领域里"转换"算子的建模真源（输入/输出 schema、语义、副作用）。
+- **excludes**：数据源(→`sources/`)、落地(→`sinks/`)、调度(→`schedules/`)。
+- **tier**：`stable`
+- **promotes_from**：track 中该管道的 proposal/design 稳定部分
+- **promotes_to**：源码/测试（瞬时投影）
+```

package/src/templates/codument/std/spec/mission-xml-spec.md

@@ -0,0 +1,249 @@
+# Mission XML 规范
+
+`codument/missions/{pending,active,archived}/.../mission.xml` 是 codument mission 的**结构 / 状态 / 调度真源**。mission 是比 track 更长周期的控制面对象，用于编排多个 plan 节点和落地 track，并允许在执行中根据 evidence 或 human decision 受控重规划。
+
+mission 不替代 track。真实代码、规范、测试和迁移仍由 `codument/tracks/<id>/track.xml` 管理。
+
+## 1. 目录位置
+
+```text
+codument/missions/
+  pending/<mission-id>/mission.xml
+  active/<mission-id>/mission.xml
+  archived/YYYY-MM-DD-<mission-id>/mission.xml
+```
+
+- `pending`：已规划但未启动。
+- `active`：正在执行；允许受控重规划。
+- `archived`：完成、取消、废弃或被替代。
+
+## 2. 与 track.xml 的关系
+
+`mission.xml` 与 `track.xml` 同构，复用三轴模型：
+
+- `TaskSpace`：结构轴，表达 mission plan 分组、叶子任务、TrackLink 绑定和状态。
+- `Schedule`：调度轴，表达 DAG 依赖。
+- `Hooks`：行为轴，表达 mission reconcile、人工确认、方向审查等生命周期行为。
+
+区别：
+
+- 根节点是 `<Mission>`。
+- 顶层 `TaskSpace` 默认 `cdt:child-mode="dag"`。
+- active mission 允许受控重规划，须递增 `Metadata.Revision` 并写 report。
+- mission 的顶层节点应是 `TaskGroup`；真正执行单元是叶子 `Task`。track creation / track execution 通过叶子 `Task` 上的 `cdt:TrackLink` 绑定真实 track。
+
+## 3. 最小示例
+
+```xml
+<Mission id="runtime-evolution" version="1" xmlns:cdt="urn:codument:v1">
+  <Metadata>
+    <Status>pending</Status>
+    <Goal>重构 runtime 长周期架构</Goal>
+    <Description>先证据盘点，再设计收敛，再切片为 tracks 落地。</Description>
+    <QuestionMode>decision-tree</QuestionMode>
+    <QuestionSeverity>light</QuestionSeverity>
+    <Revision>1</Revision>
+    <CreatedAt>2026-06-27T13:56:11Z</CreatedAt>
+    <UpdatedAt>2026-06-27T13:56:11Z</UpdatedAt>
+  </Metadata>
+
+  <Ports scope="mission">
+    <MaterialBundle role="state" name="analysis" domain="mission" path="vfs://./analysis/"/>
+    <MaterialBundle role="state" name="reports" domain="mission" path="vfs://./reports/"/>
+    <MaterialBundle role="output" name="tracks" domain="codument" path="vfs://@/codument/tracks/"/>
+  </Ports>
+
+  <TaskSpace id="space_runtime-evolution" name="runtime-evolution" version="1" cdt:child-mode="dag">
+    <Description>Runtime evolution mission.</Description>
+    <SubNodes>
+      <TaskGroup id="G1" name="证据盘点" status="NOT_STARTED" order="0">
+        <Description>盘点事实源、读写路径和包边界。</Description>
+        <SubNodes>
+          <Task id="G1-T1" name="盘点事实源" status="NOT_STARTED" order="0"/>
+          <Task id="G1-T2" name="盘点包边界" status="NOT_STARTED" order="1"/>
+        </SubNodes>
+      </TaskGroup>
+      <TaskGroup id="G2" name="设计收敛" status="NOT_STARTED" order="1">
+        <Description>形成架构归属和候选 track 边界。</Description>
+        <SubNodes>
+          <Task id="G2-T1" name="形成架构方案" status="NOT_STARTED" order="0"/>
+          <Task id="G2-T2" name="确认首批 track 切片" status="NOT_STARTED" order="1">
+            <cdt:TrackLink state="candidate" id="add-runtime-data-subgraph-contracts"/>
+          </Task>
+        </SubNodes>
+      </TaskGroup>
+      <TaskGroup id="G3" name="首批 track 落地" status="NOT_STARTED" order="2">
+        <Description>创建并执行首批 track。</Description>
+        <SubNodes>
+          <Task id="G3-T1" name="创建并执行 runtime data subgraph track" status="NOT_STARTED" order="0">
+            <cdt:TrackLink state="candidate" id="add-runtime-data-subgraph-contracts"/>
+          </Task>
+          <Task id="G3-T2" name="验证首批 track 结果" status="NOT_STARTED" order="1"/>
+        </SubNodes>
+      </TaskGroup>
+    </SubNodes>
+  </TaskSpace>
+
+  <Schedule>
+    <Dag for="space_runtime-evolution">
+      <Node id="G2"><After ref="G1"/></Node>
+      <Node id="G3"><After ref="G2"/></Node>
+    </Dag>
+  </Schedule>
+
+  <Hooks>
+    <Hook on="mission:after-node">
+      <cdt:MissionReconcile max-rounds="3" on-drift="replan-or-block"/>
+    </Hook>
+  </Hooks>
+</Mission>
+```
+
+## 4. Metadata
+
+```xml
+<Metadata>
+  <Status>active</Status>
+  <Goal>...</Goal>
+  <Description>...</Description>
+  <QuestionMode>decision-tree</QuestionMode>
+  <QuestionSeverity>light</QuestionSeverity>
+  <Revision>7</Revision>
+  <CreatedAt>...</CreatedAt>
+  <UpdatedAt>...</UpdatedAt>
+</Metadata>
+```
+
+mission status:
+
+- `pending`
+- `active`
+- `completed`
+- `cancelled`
+- `superseded`
+- `archived`
+
+`Revision` 从 `1` 起。每次受控重规划必须递增。
+
+`QuestionMode` / `QuestionSeverity` 记录 mission 规划期的问答策略，与 track.xml 保持一致：
+
+- `QuestionMode` 当前取 `decision-tree`。
+- `QuestionSeverity` 取 `auto|light|normal|deep`；未指定按 `light` 处理。
+- 这两个字段只控制规划/澄清阶段，不等同于 track 的 `CommitMode`。
+
+## 5. TaskSpace
+
+mission TaskSpace 必须保持接近 track.xml 的结构：
+
+- 顶层直接子节点使用 `TaskGroup`，表达可 DAG 调度的 mission 工作组（如证据盘点、设计收敛、首批落地、验证收口）。
+- `TaskGroup` 内部使用叶子 `Task` 表达顺序执行的实际动作。
+- mission 任务状态只写在 `TaskGroup.status` / `Task.status` 上。
+- `cdt:TrackLink` 只允许挂在叶子 `Task` 上，不挂在 `TaskGroup` 上。
+- 顶层 `TaskGroup` id 建议使用 `G1` / `G2` / `VERIFY` / `CLOSE` 等语义化或稳定短 id；叶子 task id 建议使用 `G1-T1` 形态。
+
+节点状态复用 track TaskSpace 状态：
+
+- `NOT_STARTED`
+- `ACTIVE`
+- `DONE`
+- `BLOCKED`
+- `ABANDONED`
+- `SUPERSEDED`
+
+如果现有 validator 只支持 track 状态枚举，第一版实现可以在 mission spec 中定义语义，后续再扩 validator。
+
+### 5.1 TrackLink
+
+`cdt:TrackLink` 是 mission 叶子任务与 codument track 的绑定指针，不是任务状态，也不是路径缓存。
+
+```xml
+<Task id="G2-T2" name="确认首批 track 切片" status="NOT_STARTED" order="1">
+  <cdt:TrackLink state="candidate" id="add-runtime-data-subgraph-contracts"/>
+</Task>
+```
+
+创建真实 track 后，`codument-impl-mission` 必须原地更新同一个节点：
+
+```xml
+<Task id="G2-T2" name="确认首批 track 切片" status="DONE" order="1">
+  <cdt:TrackLink state="bound" id="add-runtime-data-subgraph-contracts"/>
+</Task>
+```
+
+属性：
+
+| 属性 | 必填 | 含义 |
+|---|---:|---|
+| `state` | 是 | `candidate` 或 `bound` |
+| `id` | 是 | `candidate` 时是推荐 track id；`bound` 时是真实 track id |
+
+禁止在 `cdt:TrackLink` 上写 `path`、`archive-path` 或 track 状态。消费者通过 `id` 解析真实位置：
+
+- active track：`codument/tracks/<id>/track.xml`
+- archived track：`codument/archive/**/<timestamp>-<id>/track.xml`
+
+如果真实创建的 track id 与 candidate id 不同，直接把 `id` 更新为真实 id，并在 `reports/track-bind-XXX.md` 记录原 candidate id。
+
+## 6. Schedule
+
+mission 顶层默认 DAG：
+
+```xml
+<TaskSpace id="space_x" cdt:child-mode="dag">
+```
+
+`Schedule` 规则与 track 一致：
+
+- `<Dag for="...">` 只描述该父节点的直接下层依赖。mission 默认只把顶层 `TaskGroup` 放进 `TaskSpace` 的 DAG。
+- `<Node id="..."><After ref="..."/></Node>` 表示前驱。
+- 不跨层、不跨父。
+- 一个 `TaskGroup` 内的叶子 `Task` 默认按 `order` 顺序执行，不在 mission 顶层 `Schedule/Dag` 中描述。
+
+## 7. Cybernetic DEPA Actors
+
+mission execution is a cybernetic actor loop over a DAG-shaped desired state.
+
+| Actor | 控制论角色 | DEPA 归属 | 职责 |
+|---|---|---|---|
+| `MissionPlanner` | 期望态产出者 | Processor + Actor | 产出或修订 desired mission graph |
+| `MissionObserver` | 传感器 | Data + Actor | 读取 actual state projection |
+| `MissionReconciler` | 控制器 | Processor + Actor | 比较 desired vs actual，判定 drift / ready / blocked / done |
+| `MissionApplier` | 执行器 | Effect + Actor | 执行一个 bounded convergence action |
+
+执行协议：
+
+```text
+MissionObserver 观测实际态
+-> MissionReconciler 比较 mission.xml 期望态 vs 实际态
+-> MissionPlanner 在必要时提出重规划
+-> MissionApplier 执行一个 bounded action
+-> 写 report / 更新 mission.xml
+-> 下一轮
+```
+
+## 8. 受控重规划
+
+active mission 允许修改 `mission.xml`，但必须满足：
+
+- 有 evidence 或 human decision。
+- 写入 `reports/replan-XXX.md` 或 `reports/human-intervention-XXX.md`。
+- 更新 `Metadata.Revision` 和 `UpdatedAt`。
+- 说明 trigger、actual state、desired state、diff、decision、applied change。
+
+允许的重规划：
+
+- 新增节点。
+- 删除 / supersede 节点。
+- 修改节点目标、验收、状态。
+- 修改 DAG 依赖。
+- 暂停等待人工介入。
+
+## 9. 标准文件拆分
+
+新 mission 不使用 `roadmap.md`。内容拆分：
+
+- `proposal.md`：目标、非目标、成功判据、背景。
+- `design.md`：actor 模型、重规划协议、风险、plan vs track 区分。
+- `mission.xml`：TaskGroup/Task 节点、依赖、状态、`cdt:TrackLink` 绑定。
+- `analysis/`：执行期 evidence / findings，默认不进 git。
+- `reports/`：mission run / drift / replan / verify reports，默认不进 git。

package/src/templates/codument/std/spec/modeling-delta.md

@@ -0,0 +1,85 @@
+# modeling delta 编写规范（std/spec/modeling-delta.md）
+
+> 每个 track 对 modeling 登记表（`codument/modeling/`，见 `modeling-registry.md`）的增删改，用**目标态节点 + 节点级 3-way 合并**表达，而非自建 delta 节点类型。真 VCS 是宿主 git；xnl-vfs 只当**临时合并引擎**（不持久化平行 vcs 仓库）。
+>
+> 仅当 `codument/config/modeling.xml` 的 modeling profile `enabled` 时启用。
+>
+> XNL 语法权威见 [std/spec/xnl-format.md](./xnl-format.md)。
+
+## 形态：目标态节点（modeling_deltas）
+
+- track 在 `tracks/<id>/modeling_deltas/<plane>/<context>.xnl` 写**改动节点的目标态**（可评审，像 `behavior_deltas/`，宿主 git 跟踪）。每个节点带稳定多级命名空间 id（`#<context>.<name>` 或 `#<plane>.<context>.<name>`）。
+- 它是归档 3-way 合并的 **theirs** 侧；registry 工作树是 **ours** 侧；base 见下。
+
+```xnl
+<!-- tracks/<id>/modeling_deltas/domain/resource.xnl -->
+<object #resource.skill_tool kind="entity" fact_grade="authoritative_fact" single_writer="resource.store" [
+  <desc ?>聚合型资源：可编辑/打包/恢复的文本文件集合。</?>
+  <types ?ts1>
+  interface SkillTool { key: string; appId: string; status: SkillToolStatus; isArchived: boolean }
+  enum SkillToolStatus { Draft="draft", Online="online" }
+  </?ts1>
+  <fact-source ?>唯一写入者 resource.store；file_contents 为只读投影，不反写。</?>
+]>
+```
+
+## 增删改移（git 语义，不自建 op）
+
+| 操作 | 怎么表达 |
+|---|---|
+| 新增 / 修改节点 | 在 `modeling_deltas` 写目标态节点（按 `#id` 命中：无则新增，有则更新） |
+| 删除节点 | `modeling_deltas` 显式标记删除（或目标态省略该节点 + 删除清单）；合并时该节点从 registry 移除 |
+| 重命名 / 移动文件 | `vfs.rename`（宿主 git 记录 rename） |
+| 单文件内节点移动 | `XnlMutation` `TREE_MOVE`（`xnl-core`，按 `#id`） |
+
+## base 锚定（决策 A，锚在宿主 git）
+
+- **track create 时记录当时 `codument/modeling` 所在的宿主 git commit id** 作为 3-way base，写入 track 元信息。
+- 归档时 base 从宿主 git 物化（`git show <commit>:codument/modeling/...`），与当前工作树(ours) + `modeling_deltas`(theirs) 做三方合并，支持并发 track / registry 已前进。
+
+## 应用（归档时，机械、临时引擎）
+
+1. 物化三方：base（宿主 git 记录的 commit）+ ours（当前 `codument/modeling` 工作树）+ theirs（track 的 `modeling_deltas`），各加载为 xnl-vfs 快照（内存 / `.tmp/`，不持久化）。
+2. 节点级 3-way 合并：`xnl-vfs` `xnlFileHandler.merge(base, ours, theirs)`（底层 `xnl-core` `diffNodes`+`applyMutations`，`metadataIdMode:"identity"`，按 `#id` 命中）。
+3. 按下方**冲突解决策略**处理冲突。
+4. 合并结果写回 `codument/modeling` 工作树，由宿主 git 提交。`.tmp/` 临时产物不入库。
+5. 跑 `codument modeling lint`（分形拆分）。
+6. 模型把设计方案按类目回写 `docs/impl/`。
+
+## 冲突解决策略（保守默认 + 可配）
+
+默认**保守**：能无歧义自动合并的自动；**真冲突一律 issues-first 报告并暂停**（像 confirm gate），不静默选边。
+
+| 情形 | 默认 |
+|---|---|
+| 不相交节点（theirs 改 A、ours 改 B） | ✅ 自动 |
+| 同节点不同子部（theirs 改 A 的 `types`、ours 改 A 的 `mermaid`） | ✅ 自动 |
+| 纯新增新 id / 纯删除未被动过的节点 | ✅ 自动 |
+| 同节点同子部异内容 | ❌ 默认人工 |
+| `DELETE_MODIFY`（theirs 删 A、ours 改 A） | ❌ 默认人工 |
+| `RENAME_RENAME`（两边改名到不同处） | ❌ 默认人工 |
+| ADD/ADD 同 id 异内容 | ❌ 默认人工 |
+
+- 报告每条真冲突给 `{ metadataId, base/ours/theirs 片段 }`；归档 agent 低歧义的可判定并记录 `choice`，真语义冲突升级给用户逐条选 `choice: "ours"|"theirs"|"base"` 或手改。
+- **按冲突类型可在 `config/modeling.xml` 配**覆盖默认，例如把 `delete_modify` 设为 `theirs` 自动尊重删除；缺省全部走人工。配置字段（建议）：
+  ```xml
+  <modeling-config>
+    <merge-policy>
+      <conflict type="same-field" resolve="human"/>
+      <conflict type="delete-modify" resolve="human"/>
+      <conflict type="rename-rename" resolve="human"/>
+      <conflict type="add-add" resolve="human"/>
+    </merge-policy>
+  </modeling-config>
+  ```
+  `resolve` 取 `human` | `ours` | `theirs` | `base`。
+
+## 与 track / 归档的关系
+
+- track 的 `<Ports>` 把 `modeling_deltas/`（input，`domain="modeling"`）与 `codument/modeling/`（output `name="modeling"`）显式接起来。
+- desc/types/mermaid/伪代码都是 `TextElement`，整块当 `valueAfter` 替换，不被 XML 实体污染。
+- modeling 节点引用 `behavior://…` 不复述可测 case。
+
+## 多文件 import（依赖）
+
+跨文件命名空间引用（`<Import as="X" src="vfs://...">`）依赖 xnl.ts 侧 `add-vfs-import-resolver`；就绪前以“单 context 单文件 + 目录 glob 回退”起步。