depa-codument 0.4.1

package/src/templates/codument/std/root-agents.md

@@ -0,0 +1,39 @@
+# 根 AGENTS 受管块模板（std/root-agents.md）
+
+> `codument init` 把下面的**受管块**写进项目根 `AGENTS.md`（已有则更新该块），让任意 AI 助手从项目根就能找到 codument 入口。`upgrade-workspace` 刷新它。它**只是指针**——真正的指南在 `@/codument/std/AGENTS.md`，不要把规则正文搬到根。
+
+## 受管块内容（落进项目根 AGENTS.md）
+
+```markdown
+<!-- codument:begin -->
+# Codument Instructions
+
+These instructions are for AI assistants working in this project.
+
+打开 `@/codument/std/AGENTS.md`，当请求：
+- 提到 planning / proposal / track（proposal、behavior、change、plan、track、implement）
+- 引入新能力、破坏性变更、架构/模式调整、或较大性能/安全工作
+- 表述模糊、需要权威规范再动手
+- 用户补充需求属于某进行中 track 范围
+
+从 `@/codument/std/AGENTS.md` 了解：
+- 如何创建并应用变更提案（track 三阶段）
+- behavior 增量 / track.xml 格式与约定
+- 项目结构与工作流
+
+快速路由：
+- 项目工程约束 / 代码边界 / 技术取舍：`@/codument/attractors/project.md`
+- 产品目标 / 用户价值 / 范围取舍：`@/codument/attractors/product.md`
+- 信息该落哪层 / 何时晋升 / 冲突谁赢：`@/codument/std/attractors/knowledge-tiers.md`
+- docs/modeling 与 docs/impl 写法 / 路由 / frontmatter：`@/codument/std/attractors/model-driven-docs.md`
+- 长期记忆 lessons / incidents / patterns / summaries：`@/codument/std/attractors/project-memory.md`
+
+保留本受管块，'codument upgrade-workspace' 会刷新它。
+<!-- codument:end -->
+```
+
+## 规则
+
+- 受管块用 `<!-- codument:begin -->` / `<!-- codument:end -->` 包裹，便于幂等刷新；块外的项目自有内容不动。
+- 块内**只放指针**（何时打开 std/AGENTS.md + 它能解答什么），不放具体操作规则——避免与 `std/AGENTS.md` 双源漂移。
+- 与 AGE 的根 `AGENTS.md` 同位：项目根的助手契约入口；codument 把"详情"收进 `codument/std/`，根只留一个受管指针块。

package/src/templates/codument/std/sop/questioning.md

@@ -0,0 +1,98 @@
+# 问答协议（std/sop/questioning.md）
+
+> 从原 `std/protocols.md` 拆出的「提问」域。skill 经 `<ask protocol="...">` 引用。
+
+## 通则
+
+- **只在必须澄清/选择/确认时提问**；禁止为"测试运行环境能否提问"而发占位问题。
+- 当前步骤无需立即提问就直接继续。
+- 优先一次问清互不依赖的问题，减少往返；但有依赖的问题必须按决策树从最阻塞的前沿节点开始问。
+- **能查证就不问用户**：凡能从代码、测试、schema、config、现有 behaviors/modeling/engineering/decisions 中确认的问题，先查本地文件并写入 Evidence；只有用户意图、取舍偏好、不可逆策略才提问。
+- **澄清即沉淀（file-in/file-out）**：澄清过程中一旦某概念/行为/policy/架构**被澄清并稳定**，**当轮就**把它写回对应 owner registry（领域结构进 `codument/modeling`，长期工程知识进 `codument/engineering`，通过对应 delta 管理；legacy docs 只按项目配置同步），按 `knowledge-tiers.md` 路由，不要让结论只留在对话或拖到归档。未稳定的猜测留 track，不污染 owner registry。
+
+## Questioning Severity
+
+plan-track / plan-mission / discuss 可显式指定 questioning severity；**未指定时默认 `light`**。
+
+| severity | 适用场景 | 问答预算 | 行为 |
+|---|---|---:|---|
+| `auto` | 高自主、无问答、批量自动化、用户明确要求不要停下来确认 | 0 轮 | 不向用户提问；track/mission 名称、默认 hook、提交模式、校验模式等都自行推断；把假设写入 `analysis/decision-tree.md`、`decisions.md`、`proposal.md` 或 `design.md`。 |
+| `light` | 默认规划 | 最多 3 轮，每轮最多 2 题 | 只问 P0 用户意图 / 不可逆取舍；能查代码/文档就不问。 |
+| `normal` | 复杂功能或架构变更 | 最多 8 轮，每轮最多 3 题 | 问 P0/P1；每题必须给推荐答案和取舍。 |
+| `deep` | mission、跨仓库、长期架构收敛 | 最多 16 轮，每轮最多 3 题 | 允许深挖，但每轮必须更新文件并收敛 decision frontier。 |
+
+触发词映射：
+
+- 用户说“无问答 / 高自主 / 自动推进 / 不要问我 / no-question / auto” → `severity=auto`。
+- 用户说“轻量 / 默认 / 快速规划”或未指定 → `severity=light`。
+- 用户说“仔细问 / 正常澄清” → `severity=normal`。
+- 用户说“深挖 / grill / 详细盘问 / mission 级不确定性” → `severity=deep`。
+
+`auto` 是显式无问答模式：**不得**因 track-id / mission-id 命名、proposal/design/track.xml/mission.xml 确认、提交模式、校验模式、方向审查范围而停下来问用户。若存在高风险假设，写入文件并选择保守默认；实现/归档阶段再用 validate、verify、gap-loop 暴露问题。
+
+注意：`severity=auto` 是“提问自主度”轴；`CommitMode=auto` 是“是否自动提交”轴，二者独立，不能互相推断。
+
+## Decision Tree Protocol
+
+用于复杂规划、mission、architecture/design 或用户要求 grill/决策树时。推荐落盘：
+
+```text
+analysis/decision-tree.md
+```
+
+最小结构：
+
+```markdown
+# Decision Tree
+
+## Root Question
+- 本次规划最核心的不确定性是什么？
+
+## Severity
+- mode: light
+- max_rounds:
+- max_questions_per_round:
+
+## Decision Frontier
+| ID | Question | Priority | Blocks | Answerable By | Evidence | Recommendation | Status |
+|----|----------|----------|--------|---------------|----------|----------------|--------|
+| D1 |          | P0       |        | code/docs/user/tradeoff | | | pending |
+
+## Assumptions
+- 
+```
+
+提问规则：
+
+- 先列出决策树，再选择当前 **decision frontier**：最阻塞下游产物、且无法从代码/文档查证的 P0/P1 节点。
+- 每个问题必须包含：为什么现在问、阻塞哪些产物、推荐答案、2-3 个选项、无回复时默认值。
+- 一轮内只问互不依赖的问题；依赖型问题必须等父问题 resolved 后再问。
+- 收到答复后，回写 `decisions.md` 的“用户答复 / 最终决策 / 决策理由 / 状态”，并更新 `analysis/decision-tree.md`。
+
+`decisions.md` 推荐字段扩展：
+
+```markdown
+- Parent:
+- Blocks:
+- Evidence:
+- Confidence: 0.0-1.0
+- Reversibility: easy | moderate | hard
+- Durable candidate: yes | no
+```
+
+## 协议
+
+### ask-single-question-free
+单个开放式问题，自由文本作答。用于：澄清范围、收集一个决策（如 track 创建时的"修改意见"）。
+
+### ask-multi-question-free
+一轮内多个开放式问题，自由文本作答。用于：同轮收集多个相关决策（如 track 创建的"修改意见 + 提交模式 + 校验模式 + 方向审查"）。
+
+### ask-single-question-closed
+单个封闭式问题，给定选项择一/择多。用于：明确的二选一/多选一（如"是否配置并行参数 A/B"）。
+
+## 与 skill 的衔接
+
+- skill 的 `<ask protocol="ask-single-question-free">…</ask>` 表示该步可能需要交互；执行时按本协议判断"是否真的需要问"。
+- 失败处理类提问（重试/跳过/中止）也走对应封闭/开放协议。
+- 若当前 severity 为 `auto`，所有 `<ask ...>` 都必须被“写入假设 + 选择保守默认”替代；只有外部系统凭证、无法继续的权限缺失、 destructive 操作授权这类硬阻塞可以停止说明，仍不发规划确认问题。

package/src/templates/codument/std/sop/tdd.md

@@ -0,0 +1,26 @@
+# TDD 套路（std/sop/tdd.md）
+
+> `codument-impl-track` 引用的标准执行方法论。
+
+每个功能性 Task 按"测试先行 → 实现 → 重构"循环，直到验收满足：
+
+```text
+@delimiter: --
+-- #loop ?tdd until="cdt:Acceptance 全部满足 且 测试通过"
+---- #step ?red
+写测试：据 behavior delta 的 <suite>/<case>（given/when/then）与 cdt:Acceptance 写失败测试
+---- /?red
+---- #step ?green
+实现：写最小实现让测试通过
+---- /?green
+---- #step ?refactor
+重构：在测试保护下清理
+---- /?refactor
+-- /?tdd
+```
+
+- 子代理执行单个 Task 时按此套路；产物落到该 Task/phase 的 output MaterialBundle 目录。
+- 验收：`cdt:Acceptance` 勾选 + 测试通过；`codument-verify` 会独立复跑。
+- 重构、迁移、类型收紧、性能优化等**声称行为不变**的任务，先补 characterization / freeze 测试或等价的机械基线，锁住现有外部行为，再改实现；diff 审查应确认运行时语义没有无关变化。
+- 机制性防回退优先于口头约定：能用棘轮配置、公开表面冻结测试、架构断言、反例注入验红等方式守住的规则，不只写在文档里。
+- 非 TDD 适用场景（探索、配置）可降级，但行为用例仍是验收依据；降级原因与实证结论写入 `analysis/findings.md`。

package/src/templates/codument/std/sop/validation.md

@@ -0,0 +1,25 @@
+# 校验 / 纠偏 / 确认协议（std/sop/validation.md）
+
+> 从原 `std/protocols.md` 拆出的「门控与纠偏」域。这是 `track.xml` / `operation-hooks.xml` 里 `cdt:` hook 的**执行协议**（节点格式见 `std/spec/track-xml-spec.md §6`）。
+
+## 裁决词汇（统一）
+
+审查/纠偏类 check 返回结构化裁决 + summary。一般审查（如 AttractorCheck）用 `status ∈ PASS | GAP | BLOCKED`，`GAP` 修复后**必须重跑该 check** 直到 `PASS` 或 `BLOCKED`。**gap-loop 有专属三态** `NO_GAP | FIX_APPLIED | BLOCKED`（`NO_GAP`≈PASS；`FIX_APPLIED`=本轮发现并已修复、**须复检**；见下）。
+
+## 协议
+
+### cdt:HumanConfirm
+人工确认门控：到确认点 **yield 给用户**审阅后再继续。未通过则修复后重新确认，直到通过。暂无属性。
+
+### cdt:GapLoop（有界目标对比修复 · 双角色）
+**双角色协议**：父层编排代理只做轮次控制，每轮 **fresh-spawn** 一个独立子代理对比 scope 实现 vs 目标（proposal/design/behavior_deltas + `cdt:Acceptance`）→ 写 gap 报告（`track://reports/`）→ 必要修正 → 返回结构化 XML（`status ∈ NO_GAP|FIX_APPLIED|BLOCKED`）。父层据 XML 续轮：`FIX_APPLIED`**不算完成**必续轮复检；**首轮+无历史+NO_GAP 不得收口**（首轮怀疑），再验证一轮；非首轮 `NO_GAP` 才收口。属性 `max-rounds`（上限）/`on-exhausted`（`block` 等）。**完整协议（角色判定、模式补齐、禁止事项、输出 XML 契约）见 `gap-loop.md`。**
+
+### cdt:AttractorCheck（方向审查）
+派发 **fresh-subagent**，按 `use="<profile>"` 指定的 attractor profile（`config/attractor-profiles.xml`）对照吸引子审查当前 scope 是否偏离方向 → 返回裁决；`GAP` 按所在节点/默认策略修复复检。**执行器固定 fresh-subagent**（本协议约定，不在节点上配）。
+
+## 通用规则
+
+- **校验模式塌缩**：track 的"校验模式/粒度" = 在终态 phase（final）或每个 phase（every）挂 `cdt:GapLoop` 或 `cdt:HumanConfirm`。
+- **顺序**：phase 与 task 同时配置时，phase-before → task-before → task-after → phase-after。
+- **归属**：若上层（operation-hooks 或上层节点 hook）已拥有某 scope 的纠偏，下层不要再起竞争性 check，读已有结果即可。
+- **无隐式等待**：未配置 hook 时，不因 attractors/ 存在就额外暂停。

package/src/templates/codument/std/sop/wave-exec.md

@@ -0,0 +1,42 @@
+# Wave / DAG 调度执行（std/sop/wave-exec.md）
+
+> `codument-impl-track` / `codument-plan-track-wave` 引用。描述 `cdt:child-mode="dag"` 的层如何调度执行。
+
+## 派生 wave
+
+对某 `cdt:child-mode="dag"` 的层：读 `<Schedule><Dag for="该层">` 的 `<Node id><After ref></Node>` 边 → 在该层**直接下层**上构 DAG → 计算入度 → 拓扑分层，每层即一个 **wave**（派生，不入库）。
+
+## 调度循环
+
+```text
+@delimiter: --
+-- #loop ?waves while="该层仍有未完成节点"
+---- #step ?ready
+ready = 该层入度为 0 且未完成的直接下层节点（= 本 wave）
+---- /?ready
+---- #parallel ?dispatch limit="<Parallel> max-concurrent（parallel=false 则退化为串行）"
+对 ready 批次每个 Task 派子代理执行（只传路径/引用，子代理自读）
+---- /?dispatch
+---- #step ?collect
+等批次完成 → 回写各 Task status
+---- /?collect
+---- #if ?spot cond="spot-check=true"
+父层独立 spot-check 本 wave 产物：目标指标、行为基线、diff 面、前一 wave 成果是否被污染
+---- /?spot
+---- #step ?lock
+spot-check 通过后，若 CommitMode=auto 则创建 wave/任务检查点；manual 模式也应在输出中建议用户尽快提交锁定，避免后续 wave 污染已验证成果
+---- /?lock
+---- #step ?advance
+减各后继节点入度 → 生成 wave 完成小结，并把关键事实写入 tracks/<id>/analysis/findings.md
+---- /?advance
+-- /?waves
+```
+
+## 规则
+
+- 默认（无 `cdt:child-mode="dag"`）按 `order` 顺序执行，不进本流程。
+- 子代理只接收路径/引用（task id、Description、cdt:Acceptance、input/output MaterialBundle 路径、前置产物位置）。
+- 子代理 prompt 必须写明：完成即停、不要开启超长会话；禁止 `git restore` / `git checkout` / `git stash`；遇到越界需求或前置成果异常时返回阻塞而不是自行大范围修复。
+- 父层不能盲信子代理自述。每个 wave 至少检查目标指标、行为基线测试、diff 是否符合预期；对"非我责任"类说法用错误性质、HEAD 对照或复现实验验证。
+- 非叶节点（TaskGroup）递归：先按其自身 child-mode 调度其直接下层。
+- 失败/抽检失败/DAG 阻塞按 `validation.md` 与失败处理协议处理（重试/跳过/中止）。

package/src/templates/codument/std/sop/workflow.md

@@ -0,0 +1,35 @@
+# 工作流程总纲（std/sop/workflow.md）
+
+> 原 `std/workflow.md` 移入 std/sop/。这是 codument 行为驱动开发的方法论总纲；各步细节见同目录其它 sop 与 `std/operations/`。
+
+## 核心原则
+
+- **行为驱动**：变更先落 behavior delta（`behavior_deltas/`，见 `std/spec/behavior-delta.md`），归档时提升进行为登记表（`codument/behaviors/`）。
+- **编排者轻量**：执行用子代理（独立上下文），编排者只读 `track.xml` 并派发、回写状态；只传路径/引用，子代理自读。
+- **独立 spot-check**：子代理的"完成 / 全绿 / 非我责任"自述只是待验证假设；编排者必须用客观命令、行为基线与 diff 审查独立确认后，才能把任务视为完成。
+- **三轴分离**：结构（TaskSpace）/ 调度（Schedule）/ 行为（Hooks）正交，见 `std/spec/track-xml-spec.md`。
+- **显式 hook 纠偏**：方向/确认/有界修复都由节点或命令生命周期上的 `cdt:` hook 触发；**无显式 hook 不隐式暂停**。
+- **知识沉淀与晋升**：track 是迭代轨迹；其中**稳定**的真理要按 [knowledge-tiers.md](@codument/std/attractors/knowledge-tiers.md) 晋升进 owner 层（`docs/modeling`/`docs/impl`/`behaviors`/`decisions`/`memory`）。owner 文档维护**实时优先**（discuss 期就收敛），归档兜底。这是 codument 相对 track 记忆的弱环，需刻意补强。
+- **事实写入磁盘**：长程实现中的实证数据、失败归因、环境约束、机制漏洞和 phase/wave 结论写入 `tracks/<id>/analysis/findings.md`；新会话恢复时先读它。
+- **破坏性 git 禁令**：子代理不得使用 `git restore` / `git checkout` / `git stash` 这类会抹掉他人未提交成果的命令；只读 git 查询允许，重命名可用 `git mv`。
+- **自包含**：所有提示词/规范在 `codument/`（init 落盘），规则随项目工作区一起维护。
+
+## 三阶段
+
+### 一、创建 track（`codument-plan-track`）
+查现状（`codument list [--behaviors]`）→ 选动词开头 kebab `track-id` → 写 `behavior_deltas/<cap>/delta.xml` + `proposal.md`(+`design.md`) + `track.xml`（TaskSpace；phase=第一层 TaskGroup）→ 同轮收集 提交模式 / 校验模式 / 方向审查并写成 Hooks → 等批准。
+
+### 二、实现（`codument-impl-track` 等）
+读 proposal/design/behavior_deltas/analysis/findings → 按 TaskSpace 顺序遍历 phase、层内按 Schedule（默认顺序 / `cdt:child-mode="dag"` 则 DAG，见 `wave-exec.md`）派发子代理 → 独立 spot-check → 回写 status 与 findings → 在 phase/task/track 生命周期跑 `cdt:` hook（`validation.md`）。可按需 `discuss` / `plan-track-wave` / `gap-loop` / `verify` / `revise-track`。
+
+### 三、归档（`codument-archive-track`）
+提升 behavior delta 进 `codument/behaviors/` → 移 track 到 `archive/YYYY-MM/...` → 条件提升 decision/memory → 显式 hook 触发 artifact/docs 同步（`archive-track.md` / `artifact-sync.md`）。
+
+## 何时建 track / 跳过
+
+**建**：新增能力、破坏性变更、架构/模式调整、改变行为的性能/安全工作。
+**跳过**：纯 bug 修复、拼写/格式、非破坏依赖更新、纯配置、给既有行为补测试。补充需求落在进行中 track 范围内则并入。
+
+## 外部 CLI 回退
+
+提示词要求运行 `codument validate ...` 但系统找不到 `codument` 命令时，**跳过该外部步骤并明确说明已跳过**，不阻塞工作流。

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

@@ -0,0 +1,36 @@
+# behavior delta 编写规范（std/spec/behavior-delta.md）
+
+> 口径：旧称 spec / spec_deltas，现统一为 **behavior**。每个 track 在 `tracks/<id>/behavior_deltas/<capability>/delta.xml` 声明对行为登记表（`codument/behaviors/`，见 `behavior-registry.md`）的增删改。
+
+## 形态
+
+```xml
+<behavior-patch capability="csv-export" version="1">
+  <upsert selector="behavior://csv-export/requirements/export-endpoint">
+    <requirement id="export-endpoint">
+      <statement>系统 SHALL 提供 GET /reports/export.csv，复用报表查询过滤条件，以 RFC 4180 CSV 流式返回。</statement>
+      <suite name="csv-export">
+        <case name="过滤条件一致">
+          <given>报表页应用了过滤条件 F</given>
+          <when>请求 /reports/export.csv 携带 F</when>
+          <then>导出行集与在线视图在 F 下一致</then>
+        </case>
+      </suite>
+    </requirement>
+  </upsert>
+</behavior-patch>
+```
+
+## 规则
+
+- 根节点 `<behavior-patch capability="<capability>" version="1">`；一个 capability 一个 delta 目录。
+- **mutation = wrapper 标签 + `selector`**：`<upsert|delete|move selector="behavior://...">`；`selector` 用 **`behavior://`** 虚拟路径定位行为登记表中的节点（取代旧 `spec://`）；`move` 还必须带 `to="behavior://..."`。
+- **行为用例用可嵌套 `<suite>` / `<case>`**（given/when/then），与各语言单测库的多层级、场景嵌套对齐；单个 delta 变长可拆为同名文件夹多文件。
+- `<requirement>` / `<statement>` 承载行为陈述；`<suite>/<case>` 承载可执行验收。
+- 节点要对拆分友好：`capability` → `requirement` → `statement` / `suite`，便于 single-file ↔ same-name-folder 演化。
+
+## 与 track / 归档的关系
+
+- track 的 `<Ports>` 把 `behavior_deltas/`（input 物料，`domain="behavior"`）与 `codument/behaviors/`（output `name="behavior"`）显式接起来。
+- 归档时（`codument-archive-track`）按 `<upsert|delete|move>` wrapper + `behavior://` selector 把 delta 应用进 `codument/behaviors/`（见 `behavior-registry.md`）。
+- 行为用例 `<suite>/<case>` 指导测试编写，是 `codument-verify` 的验收依据之一。

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

@@ -0,0 +1,42 @@
+# behavior 登记表规范（std/spec/behavior-registry.md）
+
+> 旧称 spec registry / `codument/specs/`，现为 **behavior 登记表** `codument/behaviors/`。它是项目行为的合并真源（Contract Registry）：track 完成归档时把 `behavior_deltas/` 应用进来。
+
+## 布局
+
+```
+codument/behaviors/
+├── <capability>.xml              单文件能力（行为较少）
+└── <capability>/                 同名文件夹（行为较多时拆分）
+    ├── index.xml                 入口，include 子文件
+    └── <area>.xml
+```
+
+- 单文件 ↔ 同名文件夹**自动演化**：内容过多时把 `<capability>.xml` 拆成 `<capability>/index.xml` + 子文件，沿用分形习惯。
+- `behavior://<capability>/requirements/<id>/suites/<id>/cases/<id>` 是定位行为节点的 VFS 路径，被 `behavior-patch` 的 `selector` 与跨文档引用使用；可按节点层级截短，例如只定位到 `requirements/<id>`。
+
+## 节点
+
+```xml
+<behaviors capability="csv-export" version="1">
+  <requirement id="export-endpoint">
+    <statement>系统 SHALL 提供 GET /reports/export.csv …</statement>
+    <suite name="csv-export">
+      <case name="字段转义"><given>…</given><when>…</when><then>…</then></case>
+    </suite>
+  </requirement>
+</behaviors>
+```
+
+- `<behaviors capability version>` 根；`<requirement id>` + `<statement>` + 可嵌套 `<suite>/<case>`。
+- 行为状态/适用性等元信息走属性；行为本体是事实真源，**不**复述实现细节（实现真源在代码 + docs/impl）。
+
+## 应用 delta（归档时）
+
+1. 解析 `behavior_deltas/<cap>/delta.xml` 的 `<behavior-patch>`。
+2. 对每个 `<upsert|delete|move selector="behavior://…">` 在登记表定位并施改。
+3. 登记表内容变化后，若启用 docs 同步，按显式 hook 联动 docs（见 `std/operations/artifact-sync.md`）。
+
+## 设计取舍
+
+- behavior 登记表是**契约**层（"系统应有什么行为"），不与代码/文档争夺实现真源；行为对照失效检测、链接维护等能力可以渐进增强，当前格式保持 XML 结构友好、对拆分友好。

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

@@ -0,0 +1,68 @@
+# engineering delta 编写规范（std/spec/engineering-delta.md）
+
+> 每个 track 对 engineering 登记表（`codument/engineering/`）的变更，用**目标态节点 + 节点级 3-way 合并**表达。真 VCS 是宿主 git；xnl-vfs 只当临时合并引擎。
+>
+> 仅当 `codument/config/engineering.xml` 的 engineering profile `enabled` 时启用。
+
+## 形态：目标态节点
+
+track 在下面路径写改动节点的目标态：
+
+```text
+tracks/<id>/engineering_deltas/<plane>/<category>/<topic>.xnl
+```
+
+示例：
+
+```xnl
+<howto #backend.howto.orders.add_endpoint kind="howto" [
+  <desc ?>新增订单接口的标准维护步骤。</?>
+  <when-to-use ?>需要新增 backend endpoint 并接入 behavior case 时使用。</?>
+  <steps ?>
+  1. 先新增 behavior case。
+  2. 在 orders module 增加 route handler。
+  3. 写集成测试。
+  </?>
+  <verification ?>运行 backend route test 与 codument validate。</?>
+]>
+```
+
+## 操作语义
+
+| 操作 | 怎么表达 |
+|---|---|
+| 新增 / 修改节点 | 在 `engineering_deltas` 写目标态节点，按 `#id` 命中 |
+| 删除节点 | delta 显式删除清单或目标态删除语义，archive merge 时移除 |
+| 重命名 / 移动文件 | 用宿主 git rename / vfs rename，保持节点 id 稳定 |
+| 同文件内重排 | XNL mutation 按 id 命中 |
+
+## base 锚定
+
+- track create 时记录当前 `codument/engineering` 的宿主 git commit id，作为 3-way base。
+- archive 时物化 base、当前 registry(ours)、track delta(theirs)，做三方合并。
+
+## 冲突策略
+
+默认保守：
+
+| 情形 | 默认 |
+|---|---|
+| 不相交节点 | 自动 |
+| 同节点不同子部 | 自动 |
+| 纯新增 / 纯删除未被动过节点 | 自动 |
+| 同节点同子部异内容 | 人工 |
+| delete-modify | 人工 |
+| add-add 同 id 异内容 | 人工 |
+
+策略可在 `codument/config/engineering.xml` 覆盖：
+
+```xml
+<MergePolicy>
+  <Conflict type="same-field" resolve="human"/>
+  <Conflict type="delete-modify" resolve="human"/>
+  <Conflict type="add-add" resolve="human"/>
+</MergePolicy>
+```
+
+`resolve` 取 `human | ours | theirs | base`。
+

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

@@ -0,0 +1,86 @@
+# engineering 节点 schema 规范（std/spec/engineering-node-schema.md）
+
+> 定义 `codument/engineering/` 里一个长期工程知识节点长什么样：kind、最小表征、id、引用边界。
+
+## 1. 心法
+
+engineering 节点是**可寻址、可验证、可合并的工程知识单元**。它不复制建模真源，不复述 behavior case，只描述实现/维护/排障视角，并用 URI 连接其他真源。
+
+## 2. kind 谱系
+
+| kind | 装什么 | 最小必备表征 |
+|---|---|---|
+| `overview` | 心智模型、组成、边界 | `desc` + `mental-model` |
+| `howto` | 可重复维护操作 | `when-to-use` + `steps` + `verification` |
+| `rule` | 实现约束/护栏 | `rule` + `rationale` + `enforcement` |
+| `example` | worked example | `scenario` + `walkthrough` |
+| `reference` | 查表/配置/API/schema 映射 | `scope` + `source-of-truth` + `update-procedure` |
+| `troubleshooting` | 故障诊断与修复 | `symptoms` + `diagnosis` + `fix` |
+| `runbook` | 运维/发布/恢复手册 | `preconditions` + `steps` + `verification` + `rollback` |
+| `code-map` | 代码路径映射 | `scope` + `paths` + `update-procedure` |
+
+可扩展 shell kind 用命名空间形式放在 `kind` 属性值里，例如 `security:checklist`。XNL 元素标签不要写冒号。
+
+## 3. 表征形式
+
+| 表征 | 装什么 |
+|---|---|
+| `<desc>` | 一句话说明 |
+| `<mental-model>` | overview 的核心心智模型 |
+| `<when-to-use>` | howto 适用场景 |
+| `<steps>` | 步骤 |
+| `<verification>` | 验证方式 |
+| `<rollback>` | 回滚 / 恢复 |
+| `<rule>` | 规则正文 |
+| `<rationale>` | 为什么 |
+| `<enforcement>` | 如何执行 / 测试 / lint |
+| `<scenario>` | example 场景 |
+| `<walkthrough>` | example 过程 |
+| `<scope>` | reference/code-map 范围 |
+| `<source-of-truth>` | 查表来源 |
+| `<update-procedure>` | 如何更新 |
+| `<symptoms>` | 故障症状 |
+| `<diagnosis>` | 诊断步骤 |
+| `<fix>` | 修复方式 |
+| `<paths>` | 代码路径列表 |
+
+## 4. id 与 URI
+
+- id：`#<plane>.<category>.<topic>.<name>`，例如 `#backend.howto.orders.add_endpoint`。
+- URI：`engineering://backend/howto/orders/add_endpoint`。
+- 路径：`codument/engineering/backend/howto/orders.xnl` 或 `orders/index.xnl`。
+
+## 5. 引用
+
+允许引用：
+
+- `engineering://...`：其他工程知识。
+- `modeling://...`：结构/领域真源。
+- `behavior://...`：可测行为契约。
+- `decision://...`：承重决策。
+
+引用值可出现在任意 metadata/attribute 中，解析器按 scheme 自识别。
+
+## 6. 语言约定
+
+- 描述、步骤、规则、排障内容用中文。
+- 代码路径、文件名、函数名、接口名、URI、kind、id 保持英文。
+
+## 7. Good / Bad
+
+Good：
+
+```xnl
+<rule #runtime.rules.state.no_derived_writeback kind="rule" applies_to=["modeling://domain/orders/order"] [
+  <rule ?>派生 projection 不得反写 authoritative fact。</?>
+  <rationale ?>避免多个事实源同时写同一业务状态。</?>
+  <enforcement ?>review 时检查写路径；测试覆盖 projection 只读。</?>
+]>
+```
+
+Bad：
+
+- ❌ 把状态机、实体字段、事实源本体写进 engineering（应放 `modeling`）。
+- ❌ 把 BDD case 复制进 engineering（应放 `behaviors`）。
+- ❌ 节点没有稳定 id。
+- ❌ howto 没有 steps / verification。

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

@@ -0,0 +1,82 @@
+# engineering 登记表规范（std/spec/engineering-registry.md）
+
+> `codument/engineering/` 是项目的**长期工程知识真源**：实现方式、维护操作、工程规则、示例、参考、排障、runbook、code map。它与 `codument/modeling/` 正交：modeling 答“系统结构真相是什么”，engineering 答“人和 AI 应该如何实现、维护、排障”。
+>
+> 仅当 `codument/config/engineering.xml` 的 engineering profile `enabled` 时启用；默认关，存量项目无感。
+>
+> XNL 语法权威见 [std/spec/xnl-format.md](./xnl-format.md)。
+
+## 物理形态：XNL 工作树，宿主 git 版本化
+
+```text
+codument/engineering/
+├── <plane>/                       global/backend/surface/runtime/storage/agents/operations/...
+│   └── <category>/                overview/howto/rules/examples/reference/troubleshooting/runbooks/code-map
+│       ├── <topic>.xnl            小主题单文件
+│       └── <topic>/               变大后同名文件夹演化
+│           ├── index.xnl
+│           └── <leaf>.xnl
+└── .node-meta/                    节点稳定 id 的 sidecar（可选；命名空间内联 id 优先）
+```
+
+- 工作树是磁盘上可读、可手改、宿主 git 可 diff 的 XNL 文件。
+- 真 VCS = 宿主 git：`codument/engineering/**.xnl` 由项目自己的 git 版本化、协作、提供历史。
+- 不持久化平行 vcs 仓库：xnl-vfs/xnl-vcs 仅作临时合并引擎；其产物放 `.tmp/` 并 gitignore。
+- 节点稳定 id 优先用 XNL 多级命名空间内联：`#<plane>.<category>.<topic>.<name>`。
+
+## 与 docs/impl 的关系
+
+`engineering` 吸收 `docs/impl-fractal` 的长期工程知识语义，并把它纳入 codument 的 delta/merge/validate 管理：
+
+- `docs/impl/` 可以作为迁移前 legacy 或派生展示层。
+- 新的长期工程知识应进入 `codument/engineering/`。
+- 不稳定的执行期发现仍先留在 track `analysis/` / `reports/`，稳定后再进入 engineering。
+
+## URI 与引用
+
+canonical URI：
+
+```text
+engineering://<plane>/<category>/<topic>/<name>
+```
+
+引用规则：
+
+- 指向工程知识：`engineering://...`
+- 指向结构真源：`modeling://...`
+- 指向行为契约：`behavior://...`
+- 指向承重决策：`decision://...`
+
+解析器应按 scheme 自识别引用，不依赖固定 key 白名单。
+
+## 默认 plane
+
+- `global`：跨 plane 的实现/维护知识。
+- `backend`、`surface`、`runtime`、`storage`、`pipelines`、`agents`、`operations`：按项目需要启用。
+
+## 默认 category
+
+| category | 装什么 |
+|---|---|
+| `overview` | 心智模型、组成、边界 |
+| `howto` | 可重复维护操作 |
+| `rules` | 实现约束、约定、护栏 |
+| `examples` | worked example / 样例 |
+| `reference` | code map、API/schema/配置表、映射 |
+| `troubleshooting` | 故障模式、诊断、修复 |
+| `runbooks` | 运维/发布/恢复执行手册 |
+| `code-map` | 代码路径与工程知识节点的映射 |
+
+## 节点
+
+节点 schema 详见 `std/spec/engineering-node-schema.md`。要点：
+
+- 文件 = XNL。
+- 描述性内容用中文；代码路径、接口名、文件名、URI、`#id` 保持英文。
+- 长文用 TextElement block style，避免 XML/Markdown 转义污染。
+- 与 modeling 不重复：结构/事实源/状态机归 modeling；engineering 只写实现和维护视角，必要时引用 `modeling://...`。
+
+## 应用 delta
+
+见 `std/spec/engineering-delta.md`。简述：base = track create 时记录的宿主 git commit id；archive 取 base + ours + theirs，做节点级 3-way merge，写回 `codument/engineering/`；冲突 issues-first，不静默覆盖。
+