depa-codument 0.4.1

package/src/templates/codument/std/spec/modeling-node-schema.md

@@ -0,0 +1,183 @@
+# modeling 节点 schema 规范（std/spec/modeling-node-schema.md）
+
+> 定义 `codument/modeling/` 里**一个节点长什么样**：kind 谱系、表征形式、每个 kind 的最小必备表征、命名空间 id。融合 DEPA 四维 + 事实源、modeling 实证、多表征 DSL。
+>
+> 载体见 `modeling-registry.md`；delta 见 `modeling-delta.md`。
+>
+> XNL 语法权威见 [std/spec/xnl-format.md](./xnl-format.md)。
+
+## 1. 一句话心法
+
+> 节点 = **有 id、多表征、可 XNL 寻址的领域结构节点**。越靠建模内核越用 DEPA 跨领域概念（裸名 kind）；越靠 shell/展示/交互越落到命名空间领域 kind。
+
+## 2. kind 谱系（内核裸名 → shell 命名空间）
+
+| 层 | kind 标签 | 最小必备表征 | DEPA / 来源 |
+|---|---|---|---|
+| 内核（裸名，跨领域） | `entity` / `object` | `types` + `fact_grade` + `single_writer` + invariants | Data / 事实源； `objects/data.md` |
+| | `enum` | `types` | Data |
+| | `state-machine` | `mermaid` + 状态枚举 | Data/Processor； `workflows` |
+| | `module` / `capsule` | `depends_on` + capsule-tree（**到文件/符号级**，见 §2.1） | Effect / 边界；`Module` |
+| | `component` | `runtime`/`input`/`config`/`output` 四个 `types` 块 + ctrl/rule/dataflow `pseudo` | DEPA 标准组件；`Procedure` |
+| | `port` | 入口签名 + `command\|message` 标注 | Actor/Processor；泛化 HttpEndpoint/Kafka |
+| | `actor` | 单写边界 + 偏重(data-owner/执行/组合) + 解环决策 | DEPA actor-paradigm |
+| | `policy` | rule `pseudo`(datalog/switch) 或引用 `behavior://` | 跨对象； `policies` |
+| shell（命名空间，领域定） | `surface:route` `backend:endpoint` `cli:command` `agent:tool` … | 各 plane 自定义 | route/command/action 本就跨领域 |
+
+> kind 词汇的“内核裸名 vs 命名空间领域”区分 Layer-1 的 Extension kind 谱系：通用概念裸名共用，领域概念加命名空间前缀。
+
+> **shell kind 节点的写法（重要）**：表里的 `surface:route` / `backend:endpoint` / `cli:command` 等**带冒号的命名空间 kind 是 `kind` 属性的值，不是 XNL 元素标签名**。XNL 元素标签名**禁含冒号**（写进标签名会触发 XNL 语法错 `Expected metadata key`）。落到 XNL 时：元素标签用普通词（`<endpoint>` / `<route>` / `<command>`），命名空间 kind 放进 `kind` 属性。
+> - ✅ `<endpoint #orders.place_order kind="backend:endpoint">` / `<route #shop.checkout kind="surface:route">`
+> - ❌ `<backend:endpoint #orders.place_order kind="backend:endpoint">`（标签名含冒号 → XNL 语法错）
+> 详见 §7 Good/Bad。
+
+### 2.1 capsule-tree 必须到文件/符号级（不止 contract/logic/support）
+
+`module`/`capsule` 的 capsule-tree **只列 contract/logic/support/ports 四目录是无效建模**——那是套路，不含信息。必须再下探一层，列出**每个 capsule 下的具体文件（或符号）+ 一句职责 + 它实现/投影的建模节点（`#id` 或 `modeling://…`）**。判据：读 capsule-tree 就能知道每个文件干嘛、依赖谁、是纯逻辑还是 IO 边界。
+
+```
+orders/
+  contract/
+    order-create.ts      # OrderCreate / CartLine 入参 DTO（无副作用）
+    order-response.ts     # OrderResponse ← modeling://domain/orders/order 只读投影
+  logic/
+    project-total.ts      # fn(lines)->total（derived_projection_cache，纯）
+    transit-status.ts     # 状态迁移守卫，依据 #orders.order_lifecycle
+  support/
+    order-store.ts        # append/load order 事件（authoritative_fact 写口，IO）
+    inventory-mailbox.ts  # 向 #inventory.inventory 投递 message
+  ports/
+    create-order.ts       # POST /orders -> #orders.place_order（message）
+```
+
+> 完整示例见测试资源 `test/resources/modeling-showcase/base/domain/orders/module.xnl`。
+
+## 3. 表征形式（多表征，TextElement 零转义）
+
+> 下表只给按例小抄；XNL `TextElement`（`?marker` 文本块）等完整语法以 [std/spec/xnl-format.md](./xnl-format.md) 为准。
+
+| 表征 | XNL 写法 | 装什么 |
+|---|---|---|
+| desc | `<desc ?>…</?>` | 语义 / businessDesc / 边界 |
+| types | `<types ?m>…</?m>` | TypeScript 类型 / 枚举 / 签名（Data + component IO） |
+| mermaid | `<mermaid ?m>…</?m>` | ER / state / module-relation / sequence |
+| pseudo | `<pseudo kind="ctrl\|rule\|dataflow" ?m>…</?m>` | 控制流 / 规则(datalog·switch) / 数据流 |
+| 结构 metadata | 节点属性 | `kind` `fact_grade` `single_writer` `depends_on` `visibility` `derived_from` |
+| 边界 | `<not-owned-here ?>` | 与相邻 context 易混时必写 |
+
+> **component 四块的写法（canonical）**：`component` 的 runtime / input / config / output **用裸标签** `<runtime>` / `<input>` / `<config>` / `<output>`（每块内部仍用 `types` 表征装类型/签名）——这是**推荐的 canonical 形式**。
+> - ✅ canonical：`<runtime ?r>…</?r>` / `<input ?i>…</?i>` / `<config ?c>…</?c>` / `<output ?o>…</?o>`
+> - ⚠️ 兼容：`validate` 也接受 `<types role="runtime">`（及 `role="input"`/`"config"`/`"output"`）这类 role 写法作兼容（accepted-but-discouraged），但**裸标签为推荐形式**，新建模请用裸标签。
+> 完整 Good 示例见 §7。
+
+## 4. 事实源（DEPA，entity 必备）
+
+- `fact_grade` 取 7 级之一：`authoritative_fact` / `domain_canonical_event` / `runtime_control_fact` / `append_only_journal` / `checkpoint_snapshot` / `derived_projection_cache` / `surface_view`。
+- `single_writer` = 该事实的唯一写入者；衍生节点用 `<fact-source>` 说明“谁是源、谁是只读投影、不反写”。
+
+## 5. id 命名空间（允许多级）
+
+- 用 XNL `XnlWord` 的多级命名空间：`#<context>.<name>`（如 `#resource.skill_tool`），或跨 plane 时 `#<plane>.<context>.<name>`（如 `#domain.resource.skill_tool`）= `namespace[...] + name`，全局唯一。
+- 命名空间层级 = 寻址路径层级，类似 `命名空间::类名`；同一 context 内可省略 plane 前缀，跨 plane 引用用全限定。
+- mutation 按 id 命中（`metadataIdMode:"identity"`）。
+
+## 6. 跨文档引用（VFS URI + scheme 自识别）
+
+节点之间、以及节点指向 behaviors 的引用，统一用 **VFS URI** 作 canonical 语法：
+
+- modeling 节点 → `modeling://<plane>/<context>/<name>`（绝对、自描述；文件移动/分形拆分后引用不失效，因为指逻辑节点非文件路径）。
+- 行为契约 → `behavior://<capability>/requirements/<id>`。
+- 与 codument 既有 `behavior://`/`decision://`/`spec://` 同族，一套心智。
+
+**解析规则：scheme 自识别**——解析器扫节点所有 metadata/attribute 值，**凡值匹配已知 VFS scheme（`modeling://` / `behavior://` / …）即视为引用并解析**，其余是字面量。不需要固定 key 白名单（scheme 本身标明“这是引用”）。
+
+约定可读 key（**仅约定，不强制**，靠 scheme 解析）：
+
+| key | 在哪种节点 | 值 |
+|---|---|---|
+| `depends_on` | module/capsule | `[ modeling://… ]` 列表 |
+| `derived_from` | derived plane 节点 | `modeling://…`（单一父来源） |
+| `single_writer` | entity | `modeling://…`（owning module/actor） |
+| `uses` | component / 字段 | `[ modeling://… ]`（引用的 entity/enum） |
+| `behaviors` | policy / behavior 节点 | `[ behavior://… ]` |
+
+> 注意区分：`fact_grade` 是**枚举值**（authoritative_fact…），不是引用，保持字面量；`single_writer` 是**引用**，用 `modeling://`。
+>
+> `<Import as="X" src="vfs://...">`（xnl-import）是**可选语法糖**（想要短别名 / 整包导入时用）；绝对 URI 始终可用，不依赖 import 声明即可解析。
+
+## 7. Good / Bad
+
+Good（entity，最小必备齐）：
+```xnl
+<object #resource.skill_tool kind="entity" fact_grade="authoritative_fact" single_writer="resource.store" [
+  <desc ?>聚合型资源…</?>
+  <types ?t>interface SkillTool { key: string; status: SkillToolStatus }
+  enum SkillToolStatus { Draft="draft", Online="online" }</?t>
+  <state-machine #resource.skill_tool_status [ <mermaid ?m>
+  stateDiagram-v2
+    draft --> online: publish
+  </?m> ]>
+  <fact-source ?>唯一写入者 resource.store；file_contents 只读投影不反写。</?>
+]>
+```
+
+Good（component，四块裸标签 — canonical）：
+```xnl
+<component #orders.place_order_proc kind="component" [
+  <desc ?>下单组件：校验库存、落账、投递通知。</?>
+  <runtime ?r>type Runtime = { clock: Clock; orderStore: OrderStore }</?r>
+  <input ?i>interface PlaceOrderInput { cartId: string; userId: string }</?i>
+  <config ?c>interface PlaceOrderConfig { maxLines: number }</?c>
+  <output ?o>interface PlaceOrderOutput { orderId: string; total: number }</?o>
+  <pseudo kind="ctrl" ?p>validate(input) -> reserve(stock) -> append(order) -> notify</?p>
+]>
+```
+
+Good（shell kind 节点 — 普通标签 + `kind` 属性）：
+```xnl
+<endpoint #orders.place_order kind="backend:endpoint">
+<route #shop.checkout kind="surface:route">
+```
+
+Bad：
+- ❌ entity 缺 `fact_grade`/`single_writer`/`types`（缺最小必备 → lint 不过）。
+- ❌ 把可测 BDD case 复述进 modeling（应放 behaviors，modeling 引用 `behavior://`）。
+- ❌ desc/types 用 XML 转义（应用 `TextElement ?marker` 零转义）。
+- ❌ module 缺 `depends_on`/capsule-tree（无法判依赖成环 → actor 决策）。
+- ❌ 用 `surface:route` 表达本应是内核 `entity` 的领域对象（kind 选错层）。
+- ❌ shell kind 把命名空间 kind 写进**元素标签名**：`<backend:endpoint #orders.place_order kind="backend:endpoint">`（标签名含冒号 → XNL 语法错 `Expected metadata key`）。正确：标签用普通词 `<endpoint … kind="backend:endpoint">`，冒号只出现在 `kind` 属性值里。
+- ❌ component 四块写成 `<types role="runtime">…</types>`（等）当作唯一表征——虽 `validate` 兼容接受，但**非 canonical**；应写裸标签 `<runtime>`/`<input>`/`<config>`/`<output>`。
+- ❌ component 四块用 **marker 名**编码角色 `<types ?runtime>…</?runtime>`——marker 是节点的免转义 id、**不承载语义角色**，`validate` **不**接受这种写法；必须用裸标签 `<runtime>` 或（兼容）`<types role="runtime">`。
+
+## 8. modeling vs behaviors
+
+- 可测 BDD 契约（requirement/suite/case，given/when/then）→ `codument/behaviors/`。
+- 结构/类型/状态机/依赖/事实源/分发策略 → `codument/modeling/`。
+- modeling 的 behavior/policy 节点引用 `behavior://…`，不重复。
+
+## 9. 语言约定（描述用中文，代码标识符用英文）
+
+modeling 节点的**描述性内容一律用中文**，**代码标识符保持英文**：
+
+- **中文**：`<desc>` / `<fact-source>` / `<not-owned-here>` / `<dependency-rule>` / `<invariants>` 等散文块；`<types>` 与 IO 块（`<runtime>`/`<input>`/`<config>`/`<output>`）里的**代码注释**（`// …`）；`<pseudo>` 的自然语言步骤；`<mermaid>` 的节点/迁移**标签文字**；capsule-tree 里每个文件的职责注释。
+- **英文**：TypeScript `interface`/`type`/字段名、`enum` 成员名与值、`kind` 值、`fact_grade` 枚举、metadata key、`#id` 命名空间（`<plane>.<context>.<name>`）、VFS scheme（`modeling://`/`behavior://`）；mermaid 状态名若对应 enum 值（如 `draft`/`done`）保持英文。
+
+> 原因：描述用中文便于团队阅读理解；代码标识符 / 枚举 / id 是**机器契约**，须英文以保证生成的 TS 可编译、与 schema 校验及跨文档引用一致。
+
+Good（注释/描述中文，标识符英文）：
+```xnl
+<component #orders.place_order kind="component" [
+  <desc ?>下单组件：校验购物车、预留库存、落账。</?>
+  <runtime ?r>
+  interface PlaceOrderRuntime {
+    orderStore: OrderStore       // 订单写入口（副作用契约）
+    inventory: InventoryMailbox  // 跨 actor 的 message 投递口
+  }
+  </?r>
+  <pseudo kind="ctrl" ?p>校验 input → 经 message 预留库存 → 落账 → 发布事件</?p>
+]>
+```
+
+Bad：
+- ❌ `<desc>`/`<fact-source>` 等描述写英文（应中文）。
+- ❌ 把 `interface`/字段名/`enum` 值/`#id`/`kind` 改成中文（破坏代码可用性与机器契约）。

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

@@ -0,0 +1,49 @@
+# modeling 登记表规范（std/spec/modeling-registry.md）
+
+> `codument/modeling/` 是项目的**领域建模真源**（领域本体 / attractor 载体）。与 `codument/behaviors/`（行为契约）正交：behaviors 答“系统应有什么可测行为”，modeling 答“系统的结构真相是什么”（对象、类型、状态机、模块依赖、事实源、actor）。`docs/impl/` 保留为派生实现知识，不进 `codument/`。
+>
+> 仅当 `codument/config/modeling.xml` 的 modeling profile `enabled` 时启用；默认关，存量项目无感。
+>
+> XNL 语法权威见 [std/spec/xnl-format.md](./xnl-format.md)。
+
+## 物理形态：xnl-vfs 工作树，宿主 git 版本化
+
+```
+codument/modeling/
+├── <plane>/                      domain(canonical) + 派生 plane(backend/surface/runtime/...)
+│   └── <context>/                bounded context
+│       ├── index.xnl             本 context 的节点（过大才拆同名子文件）
+│       └── <kind>/<id>.xnl       拆分后的节点文件
+└── .node-meta/                   节点稳定 id 的 sidecar（可选；命名空间内联 id 优先）
+```
+
+- 工作树是磁盘上**可读、可手改、宿主 git 可 diff** 的 XNL 文件（`xnl-vfs` `LocalFsVfsPersistence`）。
+- **真 VCS = 宿主 git**：`codument/modeling/**.xnl` 由项目自己的 git 版本化、协作、提供历史。
+- **不持久化平行 vcs 仓库**：xnl-vfs/xnl-vcs 仅作**临时合并引擎**（归档时的节点级 3-way），其产物（如 `.xnl-vcs/`）放 `.tmp/` 并 **gitignore**，不入库——避免可变控制文件（refs/HEAD/logs/workspace）在多人协作时冲突，也避免与宿主 git 重复记账。
+- 节点稳定 id 优先用 XNL 多级命名空间内联（`#<context>.<name>` 或跨 plane `#<plane>.<context>.<name>`）；需要时用 `.node-meta/<name>.node.xnl` sidecar 兜底。
+
+## 载体与定位
+
+- 文件 = XNL（`xnl-core`）。`DataElement`（结构）+ `TextElement ?marker`（desc / TypeScript / mermaid / 伪代码，**零转义**）。
+- 节点 id = `XnlWord` 命名空间：`#<context>.<name>`（类似 `命名空间::类名`，全局唯一）。
+- `modeling://<plane>/<context>/<id>` 是跨文档引用的 VFS 路径，映射到 XNL `#<context>.<id>`；mutation 在 `metadataIdMode:"identity"` 下按 id 命中。
+- 单文件 ↔ 同名文件夹**自动演化**：内容过大时把 `index.xnl` 节点拆为 `<kind>/<id>.xnl`（宿主 git 跟踪 rename）。`codument modeling lint` 给出拆分建议——默认阈值 **> ~400 行 或 > ~8 个顶层建模节点**（可在 `config/modeling.xml` 配）；lint 只建议，实际拆分由模型按 `folder-manifest.md` 应用。
+
+## 节点（kind 谱系 + 最小表征）
+
+节点 schema 详规见 `std/spec/modeling-node-schema.md`。要点：
+
+- **kind 谱系**：越靠内核越用 DEPA 跨领域概念（裸名 kind：`entity`/`enum`/`state-machine`/`module`/`component`/`port`/`actor`/`policy`）；越靠 shell 越用命名空间领域 kind（`surface:route`/`backend:endpoint`/`cli:command`…）。
+- **最小必备表征**（CLI 校验）：`entity` 必带 `types`+`fact_grade`+`single_writer`；`state-machine` 必带 `mermaid`；`module` 必带 `depends_on`+capsule-tree（**到文件/符号级**，非仅 contract/logic/support）；`component` 必带 `runtime`/`input`/`config`/`output` 四个 `types` 块。
+- **不重复 behaviors**：可测行为契约归 `behaviors`；modeling 的 behavior/policy 节点**引用 `behavior://…`**，不复述 case。
+
+## 应用 delta（归档时）
+
+见 `std/spec/modeling-delta.md`。简述：base = track create 时记录的**宿主 git commit id**；archive 取 base(从宿主 git 物化) + ours(当前工作树) + theirs(track 的 `modeling_deltas`)，用 **xnl-vfs `xnlFileHandler.merge` 临时**做节点级 3-way 合并，写回工作树并由宿主 git 提交；冲突 issues-first 报告，不静默覆盖。
+
+## 设计取舍
+
+- modeling 是**结构真源**层，不与代码/docs 争夺实现真源（实现真源在代码 + `docs/impl`）。
+- 复用 xnl 的**节点级 merge 算法**（优于 git 行级合并），但**不持久化平行 vcs 仓库**——历史/协作交宿主 git，xnl-vfs/vcs 只当临时合并引擎。
+- 不自建 delta 节点类型与 apply 算法。
+- 默认关：无 `config/modeling.xml` 或 profile 未 enabled → 全流程跳过，行为不变。

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

@@ -0,0 +1,272 @@
+# Track XML 规范（重构后的 track 文件，取代 plan.xml）
+
+`tracks/<id>/track.xml`（根 `<Track>`）是 codument 的**任务规划 + 执行 + 任务状态**文件。它是 dynamic-workflow 三层标准的一个**领域落地**：复用 Layer 1（Imports/Ports/MaterialBundle/Extension）、Layer 2（Hook）、Layer 3（TaskSpace 任务树）；codument 领域特有的东西用 `cdt:`（`urn:codument:v1`）命名空间。
+
+> 内核规范见 `../dynamic-workflow/spec/`（`kernel-pointer.md` 说明复用关系）。本文档只定义 `<Track>` 这个领域根与 codument 的 `cdt:` 概念。
+
+## 0. 三轴解构（设计要旨）
+
+旧 `plan.xml` 把"结构 / 调度 / 行为"混在一棵固定三层树 + 一堆并列块里。新 `track.xml` 拆成三条**正交轴**：
+
+```
+<Track>
+  <Metadata/>            轨道元信息（id 在根属性；status/goal/commit-mode…）
+  <Imports/>             （可选）vfs:// 引入外部流程/定义（一般 track 不需要）
+  <Ports/>               ① 轨道作用域 input/output/state + MaterialBundle（物料目录）
+  <TaskSpace>            ② 结构轴：工作树（做什么 + 状态），phase=第一层 TaskGroup，可任意层级嵌套
+    <SubNodes> … </SubNodes>
+  </TaskSpace>
+  <Schedule>             ③ 调度轴：怎么跑（mode + 依赖边 Needs）；与 TaskSpace 并列
+  <Hooks/>               ④ 行为轴：轨道级生命周期 hook（校验/纠偏/确认）
+</Track>
+```
+
+- **结构**只描述任务层级与状态；**调度**只描述执行顺序/并行；**行为**只描述生命周期校验。三者互不嵌套污染。
+- 这比旧的固定 Phase→Task→Subtask（3 层封顶）**理论上限更高**：TaskSpace 的 `TaskGroup`/`Task` 可递归任意深；调度是 DAG；行为是统一 hook。
+
+---
+
+## 0.5 track 目录结构（`tracks/<id>/` 文件布局）
+
+`track.xml` 是状态真源，但一个 track 目录还承载迭代期的工作记忆与可提升候选。完整布局：
+
+```text
+tracks/<id>/
+  track.xml               ★ 状态真源（结构/调度/行为三轴）
+  proposal.md             为什么 / 是什么 / 目标-非目标 / 影响
+  design.md               （可选）方案 / 决策摘要 / 风险 / 兼容 / 迁移
+  behavior_deltas/<cap>/delta.xml   行为增量（<behavior-patch>，归档提升进 behaviors/）
+  analysis/               规划/分析期的 planning-with-files 外部记忆（避免长对话丢上下文）
+    findings.md             直接找到的事实、约束、问题与结论
+    knowledge.md            阅读后沉淀的知识上下文、术语与机制理解
+  decisions.md            决策问题/选项/用户答复/结论与理由（需要决策时建）
+  decisions/              archive-ready 的 durable 单文件决策（归档可提升 decision://）
+  memory/                 （可选）长期记忆候选，按类别分子目录（归档且 memory profile 启用时提升 memory://）
+  reports/                gap-loop / verify 的结构化报告（track://reports/...，按轮累积）
+```
+
+规则：
+- `track.xml`/`proposal`/`behavior_deltas` 必有；其余按需。
+- `analysis/` 是**迭代期外部记忆**，不是 owner 真源——稳定结论按 `knowledge-tiers.md` 晋升进 `docs/`/`behaviors/`，不滞留 analysis。
+- `analysis/findings.md` 应记录可复用的事实锚：spot-check 证据、测试/指标结果、失败归因、环境约束、机制漏洞、phase/wave 完成小结。新会话接手或续跑时优先读取它，避免只依赖对话记忆。
+- `decisions/`→`decision://`、`memory/`→`memory://`、`behavior_deltas/`→`behaviors/` 的提升时机见 `std/operations/archive-track.md` 与 `knowledge-tiers.md` §4–§5。
+- 子代理只接收**路径/引用**自读（见 `implement.md`），不把这些目录正文塞进编排者上下文。
+
+---
+
+## 1. `<Track>` 根
+
+```xml
+<Track id="add-csv-export" version="1" xmlns:cdt="urn:codument:v1">
+  …
+</Track>
+```
+
+- `id`：track 标识（kebab、动词开头），唯一真源（旧的 `metadata/track_id` 上提为根属性）。
+- `version`：schema 版本。
+- 只声明 `cdt`（`urn:codument:v1`）命名空间。**不引入 `xmlns:config`**——track.xml 当前不引用 bt-instant-ctrl-flow 的 `config:` 配置。
+
+---
+
+## 2. `<Metadata>` — 轨道元信息
+
+```xml
+<Metadata>
+  <Status>in_progress</Status>          <!-- new | in_progress | completed | cancelled -->
+  <Goal>为报表新增 CSV 导出</Goal>
+  <Description>后端端点 + 前端按钮 + docs 同步</Description>
+  <QuestionMode>decision-tree</QuestionMode>     <!-- decision-tree -->
+  <QuestionSeverity>light</QuestionSeverity>     <!-- auto | light | normal | deep -->
+  <CommitMode>manual</CommitMode>       <!-- auto | manual -->
+  <CreatedAt>2026-06-14T10:00:00Z</CreatedAt>
+  <UpdatedAt>2026-06-14T15:00:00Z</UpdatedAt>
+</Metadata>
+```
+
+- **不含** `execution_mode`（→ `<Schedule mode>`）、`validation_mode`/`validation_granularity`/`gap_loop_round`（→ `<Hooks>` 见 §6），也不含手维护的 `summary`（工具从 TaskSpace 派生）。
+- `QuestionMode` / `QuestionSeverity` 与 `CommitMode` 并列但分属不同轴：前者描述规划/澄清阶段如何问问题，后者描述实现阶段是否自动提交。`QuestionMode` 当前取 `decision-tree`；`QuestionSeverity` 当前取 `auto|light|normal|deep`，未指定按 `light` 处理。
+- 可选 `cdt:`：`<cdt:Milestones>`、`<cdt:Risks>`（旧 milestones/risks 降级；大多数 track 放 proposal.md 即可）。
+
+---
+
+## 3. `<Ports>`（Layer 1；`<Imports>` 可选）
+
+```xml
+<Ports scope="track">
+  <!-- 轨道作用域只用目录物料（多入多出）；不需要 JSON input/output 端口 -->
+  <MaterialBundle role="input"  name="behavior-deltas" domain="behavior"     path="vfs://./behavior_deltas/"/>
+  <MaterialBundle role="output" name="docs"        domain="doc"      path="vfs://@/docs/"/>
+  <!-- track 完成后行为增量提升进 behavior registry -->
+  <MaterialBundle role="output" name="behavior"        domain="codument" path="vfs://@/codument/behaviors/"/>
+</Ports>
+```
+
+- Ports/MaterialBundle 语义同内核 Layer 1 §2。这把"轨道吃哪些目录、产出落哪"显式化，**取代** artifacts.xml 里零散的 source/target——artifact sync 直接读 track 的 output MaterialBundle。
+- 轨道作用域**不设 JSON `input`/`output` 端口**；track 的输入输出就是这些目录物料：`spec-deltas`（输入）、`docs` + `spec`（输出，后者即 `codument/behaviors/` 行为登记表）。
+- **`<Imports>` 可选**：cdt: check 自包含（配置在节点上）、`AttractorCheck.use` 直接指 `attractor-profiles.xml` 的 profile（按约定解析，无需 import），故一般 track 无需 `<Imports>`。仅当 track 要 import 外部流程/定义（如 `workflows/` 的 BTWorkflow）时才写。
+- 旧 `context_files`（phase 级）→ 收进对应 TaskGroup 的 `<Ports><MaterialBundle role="input">` 或 task 的物料。
+
+---
+
+## 4. `<TaskSpace>` — 结构轴（工作树 + 状态）★
+
+复用 Layer 3 的 TaskSpace（Task DSL，`<Description>` 元素、status 标在 XML）。codument 约定：
+
+- **phase = `SubNodes` 第一层 `TaskGroup`**（不引入独立 `<Phase>` 标签）。
+- phase 之下 `Task`（叶）/`TaskGroup`（非叶）**任意层级嵌套**（取代旧固定 3 层）。
+- 任务状态枚举沿用：`NOT_STARTED | ACTIVE | DELEGATED | FORWARDED | DONE | REFUSED | ABANDONED`。
+- codument 领域扩展用 `cdt:` 子节点：`<cdt:Gate>`（阶段门控）、`<cdt:Acceptance>`（验收标准）、`<cdt:Priority>`/`priority` 属性。
+- **层级执行模式 `cdt:child-mode`**：在 `<TaskSpace>` 或任一 `<TaskGroup>` 上加 `cdt:child-mode="sequential|dag"`（**默认 `sequential`，可省**），标记其**直接下层节点**是依次执行还是 DAG。**默认无需任何依赖配置**；只有标 `dag` 的层，才在 `<Schedule>` 里声明该层直接下层之间的依赖（§5）。可对多个非叶节点分别标 `dag`。
+
+```xml
+<TaskSpace id="space_add-csv-export" name="add-csv-export" version="1">
+  <Description>为报表新增 CSV 导出</Description>
+  <SubNodes>
+
+    <!-- 第一层 TaskGroup = phase -->
+    <TaskGroup id="P1" name="后端导出端点" status="ACTIVE" order="0">
+      <Description>新增 /reports/export.csv，复用现有查询</Description>
+      <cdt:Gate>                              <!-- 阶段门控（旧 gate_criteria） -->
+        <cdt:Criterion>所有 P0 任务 DONE</cdt:Criterion>
+        <cdt:Criterion>转义场景有测试覆盖</cdt:Criterion>
+      </cdt:Gate>
+      <SubNodes>
+        <Task id="T1.1" name="CSV 序列化器" ownerAccount="agent:impl" status="DONE" order="0" priority="P0">
+          <Description>RFC 4180 序列化，处理表头/转义</Description>
+          <cdt:Acceptance>
+            <cdt:Criterion id="T1.1-AC1" checked="true">逗号/引号/换行被正确转义</cdt:Criterion>
+          </cdt:Acceptance>
+        </Task>
+        <!-- 非叶 task → 多层嵌套（旧 subtasks 的泛化） -->
+        <TaskGroup id="T1.2" name="导出端点" status="ACTIVE" order="1" priority="P0">
+          <Description>GET /reports/export.csv，流式返回</Description>
+          <SubNodes>
+            <Task id="T1.2.1" name="路由与参数复用" status="DONE" order="0"/>
+            <Task id="T1.2.2" name="流式写出" status="ACTIVE" order="1"/>
+          </SubNodes>
+        </TaskGroup>
+      </SubNodes>
+      <!-- phase 级行为 hook（见 §6） -->
+      <Hooks>
+        <Hook on="phase:after"><cdt:AttractorCheck use="coding"/></Hook>
+      </Hooks>
+    </TaskGroup>
+
+    <TaskGroup id="P2" name="前端导出按钮" status="TODO" order="1">
+      <Description>报表页"导出 CSV"按钮</Description>
+      <SubNodes>
+        <Task id="T2.1" name="按钮与下载" status="TODO" order="0" priority="P0"/>
+      </SubNodes>
+    </TaskGroup>
+
+    <TaskGroup id="P3" name="docs 同步与收尾" status="TODO" order="2">
+      <Description>同步 docs，终态人工确认</Description>
+      <SubNodes>
+        <Task id="T3.1" name="同步 docs/modeling 与 docs/impl" status="TODO" order="0" priority="P1">
+          <Hooks><Hook on="task:after"><cdt:AttractorCheck use="docs"/></Hook></Hooks>
+        </Task>
+      </SubNodes>
+      <Hooks><Hook on="phase:after"><cdt:HumanConfirm/></Hook></Hooks>   <!-- 终态校验=人工确认 -->
+    </TaskGroup>
+
+  </SubNodes>
+</TaskSpace>
+```
+
+ID 约定（沿用旧规范的可读性）：phase=`P{n}`、task=`T{phase}.{n}`、嵌套继续追加 `.{n}`、验收=`{taskId}-AC{n}`。这些是 `id`/`order` 属性值约定，不是结构约束。
+
+---
+
+## 5. `<Schedule>` — 调度轴（怎么跑）
+
+与 `<TaskSpace>` **并列的兄弟节点**。调度按**层级**表达：默认每层依次执行（无需配置）；只有被 `cdt:child-mode="dag"` 标记的层（§4），才在这里声明**那一层直接下层节点之间**的依赖。
+
+```xml
+<Schedule>
+  <!-- 每个 <Dag for="<父节点 id>"> 只管该父节点的【直接下层】依赖（单层、可有多个父） -->
+  <Dag for="P1">
+    <Node id="T1.3">                        <!-- 有前驱的直接下层各一个 <Node> -->
+      <After ref="T1.1"/>                    <!-- 前驱用 <After ref> 子元素，一个前驱一行 -->
+      <After ref="T1.2"/>
+    </Node>
+  </Dag>
+  <!-- 顶层（phase 间）若也并行，再加 <Dag for="<TaskSpace id>">；本例 phase 默认顺序，不需要 -->
+  <Parallel max-concurrent="3" spot-check="true"/>   <!-- 旧 wave_config -->
+</Schedule>
+```
+
+设计要点（回应"更直观、对 AI 更省力、足够结构化"）：
+- **默认零配置**：未标 `dag` 的层按 `order` 依次执行——大多数 track 不必写任何依赖。
+- **依赖完全结构化**：前驱用 `<After ref="...">` **子元素**表达，一个前驱一行——**不用空格分隔的属性字符串**（避免 id 含空格 / 解析歧义），新增一条依赖 = 加一行 `<After>`，对 AI 编辑最省力、最不易错。
+- **作用域单一**：一个 `<Dag>` 只描述**一个父节点的直接下层**之间的边；要给多个非叶节点配依赖，就写多个 `<Dag for=...>`。**不跨层、不跨父**，避免旧 `<Needs task on>` 那种全局扁平边带来的歧义。
+- 不再有全局 `mode`（执行模式是**逐层**的 `cdt:child-mode`）；不再手维护 `<waves>`/`wave=`，wave = 某 dag 层依赖的拓扑分层（派生视图，不入库）。
+- **波次调度执行细节**由 `std/sop/wave-exec.md` 和 `std/operations/impl-track.md` 定义；本规范只约束结构位置与格式。
+
+---
+
+## 6. `<Hooks>` — 行为轴（校验 / 纠偏 / 确认）
+
+复用 Layer 2 Hook（`<Hooks><Hook on><typed-child/></Hook></Hooks>`）。可挂在 `<Track>`（track 级）、phase（第一层 TaskGroup）、task 级。typed-child 是 codument **内置**的 `cdt:` check——**配置直接写在节点上，无独立定义文件**：
+
+| typed-child | 配置（在节点上） | 取代旧 |
+|---|---|---|
+| `<cdt:AttractorCheck use="<profile>"/>` | `use` = `attractor-profiles.xml` 的 profile 名（如 `coding`/`docs`）。执行器固定 **fresh-subagent**（由 std 提示词约定，不配置） | `<attractor-check>` |
+| `<cdt:GapLoop max-rounds="5" on-exhausted="block" verify-round="false"/>` | `max-rounds` 上限、`on-exhausted`（`block`/…）、`verify-round`（见下）直接写在属性上 | `validation_mode=yield-gap-loop` + `<confirm protocol="yield-gap-loop">` |
+| `<cdt:HumanConfirm/>` | 暂无属性 | `validation_mode=yield-human-confirm` + `<confirm protocol="yield-human-confirm">` |
+
+- `on` 取值：`track:before|after`、`phase:before|after`、`task:before|after`。
+- **自包含**：check 的配置全在节点属性上；**无 `agents/` 定义注册表**。`AttractorCheck` 唯一的外部 ref 是 `use=` → `attractor-profiles.xml` 的 profile 名（决定校验对照哪些吸引子文件）；其审查方式（用 fresh-subagent）由 `std` 提示词统一约定。
+- **新建 track 默认方向审查**：每个第一层 phase（`TaskSpace` 的直接下层 `TaskGroup`）默认都应包含 `<Hook on="phase:after"><cdt:AttractorCheck use="coding"/></Hook>`；只有用户在创建 track 时明确选择关闭、改为终态 phase，或改用其他 profile（如 `docs`）时才覆盖。
+- **校验模式塌缩**：旧 `validation_mode`/`validation_granularity` = "在终态 phase（或每个 phase）挂哪个 typed check"。`every_phase` = 每个第一层 TaskGroup 都挂；`final_phase` = 仅最后一个挂。
+- **`<cdt:GapLoop verify-round="true|false">`**（可选，默认 `false`）：控制 gap-loop 的**首轮怀疑验证轮**——首轮返回 `NO_GAP` 且无历史报告时，`true` 才再 fresh-spawn 一轮（轻量）验证轮，`false`（默认）直接收口。属性缺省时取**全局默认 `false`**（约定；`config/operation-hooks.xml` 的 `<Operation name="gap-loop">` 可声明全局开关覆盖该约定）。节点属性覆盖全局默认（per-scope）。它**不**影响 `FIX_APPLIED` 复检——后者始终强制。创建 track 时在 §3.7 同轮确认里询问并写入各 GapLoop 节点；后续追加 phase 沿用同一设置。运行期语义见 `std/operations/gap-loop.md` §0.2.4。
+- track 级生命周期 hook（如归档前 docs 审查）也可写在 `<Track><Hooks>`；命令级（无 track 文件的操作）走 `config/operation-hooks.xml`（同语法）。
+
+```xml
+<Track …>
+  …
+  <Hooks>
+  </Hooks>
+</Track>
+```
+
+> 注意：校验/纠偏的 `<cdt:GapLoop>` 应挂在 phase（终态或每个第一层 TaskGroup）的 `phase:after`，**不要**在 `<Track><Hooks>` 再挂 `track:after` 的 `<cdt:GapLoop>`——否则会和终态 phase 的 `phase:after` GapLoop 叠加，导致末尾 gap-loop 重复执行一次。`<Track><Hooks>` 只放真正的 track 级生命周期 hook（如归档前 docs 审查）。
+
+---
+
+## 7. 状态与派生
+
+- **任务/阶段状态**：`<TaskGroup>`/`<Task>` 的 `status` 属性（枚举）。父 TaskGroup 状态应反映子节点（`ACTIVE` 若有子在跑、`DONE` 若全 DONE）。
+- **track 状态**：`<Metadata><Status>`（`new|in_progress|completed|cancelled`）。
+- **summary 不入库**：阶段/任务计数、按优先级统计等由工具遍历 TaskSpace 派生（旧 `<summary>` 删除）。
+- **commit / blocker**：完成任务的 commit SHA、阻塞原因可作 `<Task>` 的 `cdt:commit` / `cdt:blocker` 属性或 `<Config>` 字段。
+
+---
+
+## 8. 与旧 plan.xml 的迁移映射（upgrade-track 自动转换）
+
+| 旧 | 新 |
+|---|---|
+| `<plan>` / `<metadata>` | `<Track id=>` / `<Metadata>` |
+| `<phases><phase>` | `<TaskSpace><SubNodes><TaskGroup>`（第一层） |
+| `<tasks><task>` / `<subtasks><subtask>` | 嵌套 `<Task>`/`<TaskGroup>`（任意层级） |
+| 文本/`<description>` | `<Description>` 元素 |
+| `status`（TODO/IN_PROGRESS/DONE/…） | 枚举（NOT_STARTED/ACTIVE/DONE/…）；`TODO→NOT_STARTED`、`IN_PROGRESS→ACTIVE` |
+| `<gate_criteria>` | `<cdt:Gate>` |
+| `<acceptance_criteria>` | `<cdt:Acceptance>` |
+| `execution_mode`/`<waves>`/`wave=`/`<wave_config>` | 逐层 `cdt:child-mode="sequential|dag"` + `<Schedule><Dag for><Node after>` + `<Parallel>` |
+| `validation_mode`/`<confirm>`/`<attractor-check>` | `<Hooks>` + `cdt:` typed check |
+| `context_files` | `<Ports><MaterialBundle role="input">` |
+| `milestones`/`risks`/`validations`/`summary` | `cdt:` 可选节点 / proposal.md / 工具派生（summary 删除） |
+
+迁移是 breaking，由 `codument upgrade-track` 执行；过渡期 validate 兼容读旧 `plan.xml` 并提示。
+
+---
+
+## 9. 校验规则（strict）
+
+1. 根 `<Track id>`；`<Metadata><Status>` 合法枚举。
+2. `<TaskSpace>` 必需；第一层 SubNodes 至少一个 TaskGroup（phase）；id 全局唯一。
+3. `status` 属性为枚举。
+4. 每个 `<Schedule><Dag for="P">` 的 `for` 必须引用一个 `cdt:child-mode="dag"` 的节点；其 `<Node id>` 与子 `<After ref>` 只能引用该节点的**直接下层** id；该层内 DAG 无环。
+5. `<Hook on>` 取值合法；`<cdt:AttractorCheck use>` 能在 `config/attractor-profiles.xml` 解析到 profile；`<cdt:GapLoop>` 的 `max-rounds`/`on-exhausted` 合法，`verify-round`（如有）为 `true|false`。
+6. 格式良好的 XML；`cdt:` 命名空间已声明（track.xml 不需要 `config:`）。