depa-codument 0.4.1

package/src/templates/codument/std/operations/artifact-sync.md

@@ -0,0 +1,172 @@
+# skill: codument-artifact-sync（制品同步）
+
+**描述：** 把 track 的 `output` 物料（docs / 制品目录）按规则同步到一个或多个目标位置。**显式触发，不隐式。**
+
+> 本文是完整提示词（口径已对齐当前标准）。**程序化的执行流程**（resolve → generate → 按 policy 写目标，带 dry-run / conflict / provenance 分支）用流程标记块（` ```text ` + `@delimiter: --`，构造词汇见 [`_operation-spec.md`](./_operation-spec.md)）表达；**说明、规则、背景、示例**用 Markdown，内嵌 XML 用 ```` ```xml ```` 围栏。
+>
+> 口径映射（旧→新）：`codument:artifact-sync`→`codument-artifact-sync`；`<artifact-sync artifact="...">` hook → `<cdt:ArtifactSync use="...">`；`attractor-profiles.json`→`config/attractor-profiles.xml`；`docs-knowledge.md`→`std/attractors/model-driven-docs.md`；旧 `feature.json` 的 `knowledgeSync.enabled` / `projectMemory.enabled`→`docs` / `memory` profile 的 `enabled`。**`artifacts.xml` 被取代**：来源不再读零散 source/target，而是直接读 track 的 `output` MaterialBundle（track.xml `<Ports>` 里 `role="output"` 的物料目录，如 `docs/`）；目标 = artifact 规则的 base-dir + relative-dir/file。
+
+---
+
+## 1.0 目标
+
+你是 Codument artifact 同步代理。当前任务是**只同步用户指定或 hook 引用的 artifact**。
+
+不要把 artifact-sync 退化为旧 docs-sync 全量同步。docs 类同步只是 artifact 的一种；其内容选择与写作规则由 [std/attractors/model-driven-docs.md](@codument/std/attractors/model-driven-docs.md) 以及 artifact 使用的 attractor profile（`docs`）提供，路由/质量/晋升判定见下方 §4.5。
+
+本 skill 是**普通同步流程**，不需要 gap-loop 式 fresh child orchestration；只有用户显式要求独立复检时才考虑委派子代理。
+
+---
+
+## 2.0 Artifact 选择
+
+```text
+@delimiter: --
+-- #sequence ?select
+---- #if ?user-id cond="用户提供了 artifact id"
+精确匹配该 artifact 规则（对应某条 output 物料/目标规则）；不模糊匹配
+---- /?user-id
+---- #else-if ?hook cond="当前来自 operation-hooks.xml 的 archive-track:after <cdt:ArtifactSync use=\"...\">"
+只执行该 hook 引用的 artifact（如 use="docs"）
+---- /?hook
+---- #else ?ambiguous
+------ #fail ?stop reason="无法唯一确定 artifact"
+停止并请求用户补充 artifact id
+------ /?stop
+---- /?ambiguous
+-- /?select
+```
+
+**关键约束**：不要因为存在 artifact 配置 / 物料目录就同步全部 artifact——只执行被指定或被 hook 引用的那一个。
+
+---
+
+## 3.0 必读输入
+
+必须读取：
+
+- track 的 `output` MaterialBundle（来源——track.xml `<Ports>` 里 `role="output"` 的物料目录，如 `docs/`）。
+- artifact 规则的目标（一个/多个目标根：`base-dir` + `relative-dir`/`relative-file`）及其 `policy`。
+- [config/attractor-profiles.xml](@codument/config/attractor-profiles.xml)（确认 `docs` profile 是否 `enabled`）。
+- 本文 §4.5 docs 路由（内容选择 / 路由 / 质量规程）。
+- artifact 引用的 workflow / skill / attractor-profile / agent resource（`skill` resource 只是规则或提示词来源，不是要写出的 artifact）。
+
+如果 artifact 的 source 指向某个 track（含已归档 track），还应读取该 track 中存在的：
+
+- `proposal.md` 与 `proposal/`
+- `design.md` 与 `design/`
+- `behavior_deltas/**/*.xml`（旧 track 兼容 `spec.md`）
+- `track.xml`
+- `decisions/*.md`（旧 track 兼容 `decisions.md`）
+- `reports/*.md`
+- archive 中的 `summary.md`
+
+**docs 类 artifact** 还必须读取：
+
+- [std/attractors/model-driven-docs.md](@codument/std/attractors/model-driven-docs.md)（路由表 / frontmatter / 根结构）
+- [std/attractors/knowledge-tiers.md](@codument/std/attractors/knowledge-tiers.md) §4–§5（晋升判定）
+- [std/docs-modeling-fractal/index.md](@codument/std/docs-modeling-fractal/index.md)
+- [std/docs-impl-fractal/index.md](@codument/std/docs-impl-fractal/index.md)
+- 现有 `docs/modeling` 与 `docs/impl`（如果目标是本项目 docs）
+
+---
+
+## 4.0 Artifact Sync 规则
+
+- 来源是 track 的 `output` MaterialBundle（取代旧 `artifacts.xml` 的零散 source/target）；**不要**再把 `artifacts.xml` 当成单独的来源/目标配置去读。
+- artifact resource 只允许 `workflow`、`skill`、`attractor-profile`、`agent`。`skill` resource 是规则或提示词来源，不是要写出的 artifact；`attractor-profile` resource 只引用 profile 名称（指向 `config/attractor-profiles.xml`），不要把直接 attractor 文件路径写在 resource 属性上。
+- artifact 规则只关心 `uses`、`targets`、`policy`。
+- **多个 target 表示同一 artifact 内容生成一次后分发到多个目标**，不表示多个独立 artifact。
+- 每个 target 必须有 `id`、`kind`（`local-dir|web|command`）、`base-dir`，并且在 `relative-dir` 和 `relative-file` 中**二选一**：目录型 artifact 用 `relative-dir`（同步到目标根目录下的一个目录）；文件型 artifact 用 `relative-file`（同步到目标根目录下的单个文件）。
+- **多 target 分发必须保持相同的相对路径结构**：如果 artifact 生成多个有层级关系的文件，先得到**一套相对文件树**，再把同一套相对文件树写入每个 target 的 `base-dir/relative-dir` 下。文件型 artifact 的多个 target 也必须用相同生成内容，只是写到各自 `base-dir/relative-file`。
+- **不要**因为存在多个 target 就为不同 target 生成不同文件集合、不同文件名或不同层级——除非 artifact 的 workflow / skill resource 明确要求 target-specific 差异。
+- 按 `<policy>` 处理 dry-run、conflict 和 provenance。
+
+---
+
+## 4.5 docs 路由（启用 docs 同步时）
+
+docs 类 artifact 的内容选择 / 路由 / 质量 / 晋升判定 + 目录职责补齐套路：
+
+- 先按 [knowledge-tiers.md](@codument/std/attractors/knowledge-tiers.md) §4–§5 判定：该信息是否该晋升、晋升到哪层（`docs/modeling`/`docs/impl`/`behaviors`/`decisions`/`memory`）。
+- 建模/本体 → `docs/modeling/...`；设计实现 → `docs/impl/...`（领域中立，按 `std/docs-{modeling,impl}-fractal/index.md` 规范，不写死 web 结构）。
+- 文件级路由用 [model-driven-docs.md](@codument/std/attractors/model-driven-docs.md) 的 Routing Table；单文件过大按"同名文件夹"拆分；frontmatter/命名/时效性按规范。
+- **新建目录**：按 [folder-manifest.md](@codument/std/spec/folder-manifest.md) 为新目录写「目录职责」块；可顺手对缺块目录跑一次补齐（backfill）。
+- **优先实时、归档兜底**：discuss 期已实时收敛的稳定结论，本步只做全量复查/补漏，不重复劳动；只把尚未沉淀的稳定知识补上。
+
+本 skill 负责选 artifact、解析来源目标、执行写入 + 上述 docs 内容选择/路由/质量 + 晋升判定 + 目录职责补齐。
+
+---
+
+## 5.0 执行流程
+
+整个同步是 resolve → source → generate → 按 policy 写目标的流程，写入阶段按 policy 分出 dry-run（首次预览）、conflict（diff-confirm）、provenance（manifest）三类分支。
+
+```text
+@delimiter: --
+-- #sequence ?sync
+---- #step ?scope
+确认 artifact id、触发来源（用户 / archive-track:after hook）和目标范围
+---- /?scope
+---- #if ?disabled cond="docs profile 未 enabled（docs 类 artifact）"
+------ #return ?skip value="不同步：对应 profile 未启用"
+------ /?skip
+---- /?disabled
+---- #step ?resolve
+解析 resources、attractor profile、targets 和 policy
+---- /?resolve
+---- #step ?source
+读取来源 = track 的 output MaterialBundle + §3 相关上下文
+---- /?source
+---- #step ?generate
+按 workflow / skill / docs profile 规则生成 artifact 内容——先得到一套相对文件树（docs/modeling、docs/impl 等）；docs 路由 / 晋升判定按 §4.5
+---- /?generate
+---- #if ?dry-run cond="policy 含 dry-run（或首次同步）"
+------ #step ?preview
+先输出 diff / report 预览，不落盘；等确认后再继续
+------ /?preview
+---- /?dry-run
+---- #loop ?targets for="每个 target"
+------ #step ?map
+把同一套相对文件树映射到该 target 的 base-dir/relative-dir（目录型）或 base-dir/relative-file（文件型）
+------ /?map
+------ #if ?conflict cond="policy conflict=diff-confirm 且目标已存在冲突内容"
+输出 diff 等用户确认；未确认则不覆盖该 target
+------ /?conflict
+------ #step ?write
+写入该 target（多目标保持同一相对结构）
+------ /?write
+---- /?targets
+---- #if ?prov cond="policy provenance=manifest"
+------ #step ?manifest
+写 provenance manifest（来源清单 / inline 来源信息）
+------ /?manifest
+---- /?prov
+---- #step ?report
+列出 artifact id、各 target 输出、变更文件、跳过原因、待确认项
+---- /?report
+-- /?sync
+```
+
+如果项目尚无 `docs/modeling` 或 `docs/impl`，docs 类 artifact 只能创建与当前 artifact source **直接相关**的小文档；**不要**退化为全量 docs bootstrap。
+
+---
+
+## 6.0 约束
+
+- 不要执行未被指定或未被 hook 引用的 artifact。
+- 不要因为 `docs` / `memory` profile `enabled` 或 artifact 配置存在就**隐式**同步。
+- 不要把普通实现细节写入 docs modeling（建模真源只装本体 / 心智模型 / 派生设计，不复述实现细节）。
+- 如果同步存在争议，优先输出**待确认事项**而不是断言。
+- `codument validate ...` 可能会格式化或补写 track metadata；运行验证后必须检查 `git diff`，并在报告中**区分**验证副作用和本次 artifact sync 修改。
+
+---
+
+## 7.0 参考
+
+- 内容选择 / 路由 / 质量 / 晋升判定 + 目录职责补齐：本文 §4.5 docs 路由。
+- docs 路由表 / frontmatter / 根结构：[std/attractors/model-driven-docs.md](@codument/std/attractors/model-driven-docs.md)。
+- 晋升阶梯与触发条件：[knowledge-tiers.md](@codument/std/attractors/knowledge-tiers.md) §4–§5。
+- profile 开关（`docs` / `memory` 的 `enabled`）：[config/attractor-profiles.xml](@codument/config/attractor-profiles.xml)。
+- 新建目录写"目录职责"块：[std/spec/folder-manifest.md](@codument/std/spec/folder-manifest.md)。
+- 归档时如何触发本同步：[codument-archive-track skill](./archive-track.md) §6。

package/src/templates/codument/std/operations/discuss-phase.md

@@ -0,0 +1,214 @@
+# skill: codument-discuss-phase（执行前讨论 · 细化 phase TaskSpace）
+
+引导用户对指定 phase（或整 track）进行执行前讨论：把较粗的 phase 谈成可执行的任务拆分、调度与风险对齐，把结论落进 `track.xml`（细化 TaskSpace、补 `cdt:Gate`/`cdt:Acceptance`、定 `cdt:child-mode`），并把讨论中**已澄清且稳定**的领域知识**当轮**收敛进 owner 文档。
+
+> 本文是完整提示词（口径已对齐当前标准）。**程序化的执行流程**（澄清 → 细化 TaskSpace → 实时沉淀的串行/条件）用流程标记块（` ```text ` + `@delimiter: --`，构造词汇见 `_operation-spec.md`）表达；**说明、规则、背景、示例**用 Markdown，内嵌 XML 用 ```` ```xml ```` 围栏。
+>
+> 口径映射：旧 `codument-discuss` 的 phase 细化能力→`codument-discuss-phase`；`plan.xml`→`track.xml`；phase=第一层 `<TaskGroup>`；`spec_deltas/`→`behavior_deltas/`、`spec://`→`behavior://`、“spec”→“behavior”；旧 `context.md` 的"讨论记录"不再是独立产物，而是**落进 `track.xml` 的 TaskSpace 细化 + 实时沉淀进 owner 文档**（迭代期工作记忆按需放 `tracks/<id>/analysis/` 或 `decisions.md`）；`<gate_criteria>`→`<cdt:Gate>`、`<acceptance_criteria>`→`<cdt:Acceptance>`；并行调度标 `cdt:child-mode="dag"` 交给 `plan-track-wave`。
+
+---
+
+## 0. 角色与定位
+
+你是 Codument 规范驱动开发框架的 AI 代理助手。discuss 是 **track 创建与实现之间的细化环节**：在实现前与用户讨论某 phase（或整 track）的任务拆分、调度与风险，把结论沉到 `track.xml`，同时把澄清出来的稳定知识实时收敛进文档。
+
+discuss 同时承担两件事，缺一不可：
+
+1. **细化 TaskSpace**：读该 phase 的 `<TaskGroup>`，给拆分草案（哪些是叶 `<Task>`、哪些需进一步 `<TaskGroup>` 嵌套、有无并行机会），与用户对齐粒度/并行/验收/风险后落进 `track.xml`。
+2. **澄清即沉淀**：discuss 是需求沟通的一部分——讨论中一旦把某领域概念/行为/policy/架构澄清到稳定，**当轮**就按 `model-driven-docs.md` 路由收敛进 `docs/modeling`/`docs/impl`，而不是只留对话或拖到归档。这是补强 owner 文档新鲜度的关键动作。
+
+---
+
+## 1. 设置检查
+
+**协议：验证 Codument 环境是否正确设置。**
+
+1. **检查必需入口是否存在：**
+   - 项目上下文：优先使用 `codument/attractors/`；若该目录不存在，旧项目必须同时存在 `codument/project.md` 和 `codument/product.md`。
+   - `codument/std/sop/workflow.md`（内置工作流规程；旧单体 `codument/std/workflow.md` 兼容读）
+
+2. **处理缺失：** 若标准工作流文件缺失，或既没有 `codument/attractors/` 也没有旧项目 `project.md`/`product.md` 组合，立即停止并宣布：
+   > "Codument 未设置。请先运行 `codument init` 初始化工作区。"
+   不要继续讨论流程。
+
+## 1.1 交互式问答
+
+所有澄清/选择/确认都遵循 `codument/std/sop/questioning.md` 中的 ask-* 协议。**重要：** 问答 ToolCall 只能用于真实澄清/选择/确认；禁止为测试运行环境能力发起占位问题。当前步骤无需立即提问时直接继续。
+
+---
+
+## 2. Track 与 Phase 选择
+
+### 2.1 选择 Track
+
+1. **发现 active tracks：** 扫描 `codument/tracks/` 并读取各 track 的 `track.xml`（`<Metadata><Status>`），列出所有活跃 track。
+2. **`{{args}}` 含 track ID：** 精确匹配；若精确且唯一匹配，直接选择并继续，**不需要用户确认**；仅在无匹配或多个候选时请求澄清。
+3. **只有一个活跃 track：** 自动选择。
+4. **多个活跃 track 且未指定：** 列出供用户选择（**Protocol: ask-single-question-closed**）：
+   > "请选择要讨论的 Track：
+   > A) <track_id_1> - <描述>
+   > B) <track_id_2> - <描述>
+   > ..."
+
+### 2.2 选择 Phase
+
+1. **解析 track.xml：** 读取 `<TaskSpace>`，列出第一层 `<TaskGroup>`（=phase）。
+2. **`{{args}}` 含 phase ID（如 P1）：** 直接选择该 phase。
+3. **未指定：** 缺省取下一个未完成 phase；或列出所有 phase 供用户选择（**Protocol: ask-single-question-closed**）：
+   > "请选择要讨论的阶段：
+   > A) P1 - <phase 名称>
+   > B) P2 - <phase 名称>
+   > ..."
+
+---
+
+## 3. 讨论流程
+
+### 3.1 加载上下文
+
+1. **读取 track 文件：**
+   - `behavior_deltas/**/*.xml` — 行为规范增量（`<behavior-patch>`）；旧 track 可兼容 `spec.md`。
+   - `proposal.md` — 变更提案。
+   - `design.md` — 方案设计（如存在）。
+   - `track.xml` — 任务规划/调度/状态真源。
+   - 相关 `attractors/`（project/product 吸引子）。
+
+2. **提取 phase 信息：**
+   - phase 目标（`<Description>`）。
+   - phase 内所有 `<Task>`/`<TaskGroup>` 列表与现有状态。
+   - 输入物料（该 phase `<Ports><MaterialBundle role="input">`，如有声明）。
+   - 现有调度（`cdt:child-mode`、`<Schedule><Dag>`，如有声明）。
+
+3. **读取迭代期工作记忆：** 若 `tracks/<id>/analysis/`、`decisions.md` 已存在，加载之前的分析/决策记录作为背景。
+
+### 3.2 引导讨论（澄清 → 细化 → 实时沉淀）
+
+整个讨论是一段**串行流程**：呈现现状 → 提问澄清 → 迭代追问 → 总结决策 → 细化 TaskSpace → 实时沉淀稳定结论。
+
+```text
+@delimiter: --
+-- #sequence ?discuss
+---- #step ?d1
+呈现 phase 概览：目标、任务数、任务列表，并给出拆分草案（叶/非叶、依赖、并行机会）
+---- /?d1
+---- #step ?d2
+就拆分粒度、并行(dag)与否、验收/门控、风险与用户对齐——提 3-5 个关键问题（仅必要处提问）
+（Protocol: ask-multi-question-free，聚焦：技术方案选择 / 边界与异常处理 / 与现有代码集成 / 测试策略 / 性能与安全考量）
+---- /?d2
+---- #loop ?refine until="关键决策均已澄清" max="1-2 轮"
+------ #step ?d3
+据用户回答追问 1-2 轮深入问题（Protocol: ask-single-question-free）
+------ /?d3
+---- /?refine
+---- #step ?d4
+总结所有关键决策（主题 + 决策内容 + 理由 + 实现要点 + 约束）
+---- /?d4
+---- #step ?d5
+据结论细化该 phase 的 TaskSpace（见 §3.3），写回 track.xml
+---- /?d5
+---- #step ?d6
+扫描本轮讨论：凡已澄清且稳定的领域知识，按 §3.4 当轮收敛进 owner 文档
+---- /?d6
+---- #step ?d7
+向用户确认细化结果与沉淀位置（Protocol: ask-single-question-free）
+---- /?d7
+-- /?discuss
+```
+
+**phase 概览**展示模板：
+
+> 📋 **Phase <id>: <name>**
+> 目标：<goal>
+> 任务数：<count>
+>
+> 任务列表：
+> - T{x}.{y}: <task name> [<priority>]
+> - ...
+
+**提问要点（§d2）。** 根据 phase 内容提 3-5 个关键问题帮助澄清实现方案，问题聚焦于：
+
+- **技术方案选择**（如有多种实现路径）。
+- **边界条件与异常处理策略**。
+- **与现有代码的集成方式**。
+- **测试策略**。
+- **性能 / 安全考量**（如适用）。
+
+### 3.3 落进 track.xml（细化 TaskSpace）
+
+据讨论结论细化该 phase 的 TaskSpace（结构轴 + 可选调度标记）：
+
+- **增删 `<Task>`/`<TaskGroup>`**：把粗任务拆为叶 `<Task>`，复杂任务升级为嵌套 `<TaskGroup>`（任意层级，取代旧固定 3 层）。
+- **补 `cdt:Acceptance`/`cdt:Gate`**：为目标 task 补验收标准（`{taskId}-AC{n}`）、为 phase 补阶段门控。
+- **定 `cdt:child-mode`**：若该层需要并行，在 `<TaskGroup>`（或 `<TaskSpace>`）上标 `cdt:child-mode="dag"`，并把**该层直接下层之间**的依赖声明交给 `plan-track-wave` skill（它在 `<Schedule><Dag for=该层><Node><After ref>` 里落依赖边）。默认 `sequential` 可省，多数层无需任何依赖配置。
+
+```xml
+<TaskGroup id="P1" name="后端导出端点" status="ACTIVE" order="0" cdt:child-mode="dag">
+  <Description>新增 /reports/export.csv，复用现有查询</Description>
+  <cdt:Gate>
+    <cdt:Criterion>所有 P0 任务 DONE</cdt:Criterion>
+    <cdt:Criterion>转义场景有测试覆盖</cdt:Criterion>
+  </cdt:Gate>
+  <SubNodes>
+    <Task id="T1.1" name="CSV 序列化器" status="NOT_STARTED" order="0" priority="P0">
+      <Description>RFC 4180 序列化，处理表头/转义</Description>
+      <cdt:Acceptance>
+        <cdt:Criterion id="T1.1-AC1" checked="false">逗号/引号/换行被正确转义</cdt:Criterion>
+      </cdt:Acceptance>
+    </Task>
+    <Task id="T1.2" name="导出端点" status="NOT_STARTED" order="1" priority="P0"/>
+  </SubNodes>
+</TaskGroup>
+```
+
+> 旧产物对照：旧的 `context.md`「讨论记录」在当前标准下不再单列文件——**关键决策落进 TaskSpace 的 task 拆分 + `cdt:Acceptance`/`cdt:Gate`**，稳定知识沉淀进 owner 文档；仅迭代期需要的工作记忆（决策选项/答复/理由）按需放 `tracks/<id>/decisions.md` 或 `analysis/`。
+
+### 3.4 实时沉淀稳定结论（澄清即沉淀）
+
+discuss 中一旦把某领域概念/行为/policy/架构澄清到**稳定**（将成为后续迭代依赖的基线），**当轮**就按 `knowledge-tiers.md` 晋升阶梯 + `model-driven-docs.md` 路由收敛进 owner 文档——不要只留对话、也不要拖到归档：
+
+- **稳定领域知识**（概念/对象/字段语义/生命周期/policy/workflow/derived 建模） → `docs/modeling/`。
+- **稳定实现/运维知识**（架构、framework/runtime 约定、operations、howto/rules/reference/troubleshooting） → `docs/impl/`。
+- **对外行为新增/变更** → 记进 `behavior_deltas/`（归档时应用进 `behaviors/` 登记表）。
+- **承重的一次性决策** → `decisions/`（`decision://`）。
+
+```text
+@delimiter: --
+-- #switch ?promote on="本轮澄清出的知识类型与稳定度"
+---- #case ?modeling when="领域概念/对象/字段语义/生命周期/policy/workflow 已稳定"
+据 model-driven-docs 路由表写最小正确文档进 docs/modeling/**，维护 frontmatter（last_verified）
+---- /?modeling
+---- #case ?impl when="架构/约定/operations/排障知识已稳定"
+写进 docs/impl/<plane>/{overview|howto|rules|reference|troubleshooting}/**，维护 frontmatter
+---- /?impl
+---- #case ?behavior when="对外行为新增/变更"
+记进 behavior_deltas/<cap>/delta.xml（<behavior-patch>），归档时提升进 behaviors/
+---- /?behavior
+---- #case ?decision when="一次性取舍变为以后都按此来的承重决策"
+落 tracks/<id>/decisions.md（archive-ready 的进 decisions/，可提升 decision://）
+---- /?decision
+---- #default ?unstable
+未稳定的猜测/被否决方案 → 留 track（analysis/decisions.md），不污染 owner 文档
+---- /?unstable
+-- /?promote
+```
+
+> 晋升判定细则（落 `docs/` 还是 behaviors/decisions/memory、何时晋升、触发条件）见 `codument/std/attractors/knowledge-tiers.md` §4–§5；docs profile 未启用时，仅记 track 待归档兜底，不强行写 `docs/`。
+
+---
+
+## 4. 完成
+
+宣布讨论完成：
+
+> "Phase <id> 讨论完成，track.xml 已细化（任务拆分 + 验收/门控 + 可选调度标记）；稳定结论已实时收敛进 owner 文档。
+> 推荐的下一步是 `请使用 codument-impl-track skill，实现 track: <track_id>` 开始实现；如该 phase 标了 `cdt:child-mode=dag` 需先排依赖，可先 `请使用 codument-plan-track-wave skill，规划 track: <track_id>`。"
+
+---
+
+## 引用
+
+- `codument/std/spec/track-xml-spec.md`（TaskSpace/Schedule/Hooks、phase=第一层 TaskGroup、`cdt:` 概念）
+- `codument/std/operations/plan-track-wave.md`（`cdt:child-mode=dag` 层的依赖边声明）
+- `codument/std/sop/questioning.md`（ask-single-question-free / -closed / ask-multi-question-free）
+- `codument/std/attractors/knowledge-tiers.md`（晋升阶梯、真源优先级）
+- `codument/std/attractors/model-driven-docs.md`（docs/modeling 与 docs/impl 路由、frontmatter）

package/src/templates/codument/std/operations/discuss.md

@@ -0,0 +1,87 @@
+# skill: codument-discuss（创建 track/mission 前的上下文讨论）
+
+在还没有决定要 quick、track 还是 mission 前，先基于 Codument owner 知识和项目工程文件做一次轻量上下文搜集、问题树澄清与任务尺度分流。
+
+> 本 operation 不创建 track、mission、discussion workspace，也不创建 `codument/discussions/`。讨论内容和临时决策主要留在 AI agent 上下文；只有必要的临时 analysis 写入 `codument/analysis/`，并在每次 discuss 开始和转入 plan 前清理。
+
+## 0. 定位
+
+`codument-discuss` 是 pre-plan 讨论入口：
+
+- 不修改源码。
+- 不创建 track/mission。
+- 不写 proposal/design/behavior delta。
+- 不持久化 discussion workspace。
+- 输出一个明确建议：`quick | track | mission | blocked`。
+
+如果目标 track 已存在、用户要细化某个 phase，使用 `codument-discuss-phase`。
+
+## 1. 临时 analysis 生命周期
+
+每次触发 `codument-discuss`：
+
+1. 删除旧的 `codument/analysis/`。
+2. 创建新的 `codument/analysis/`。
+3. 可写入：
+   - `context.md`：代码、测试、behavior/modeling/engineering、archive、mission/track 扫描摘要。
+   - `decision-tree.md`：Root Question、QuestionSeverity、Decision Frontier、Assumptions。
+   - `recommendation.md`：route、理由、下一步命令、未决问题。
+4. 如果用户同意进入 `codument-plan-track` 或 `codument-plan-mission`，在开始创建前再次删除 `codument/analysis/`。
+
+`codument/analysis/` 是 scratch，不是 owner 真源；稳定结论应在后续 quick/track/mission 中按知识层级进入 `codument/modeling`、`codument/engineering`、`behaviors`、`decisions` 或 memory。
+
+## 2. 上下文搜集
+
+先执行命令级前置 hook：若 `operation-hooks.xml` 为 `discuss:before` 配了 `<cdt:AttractorCheck use="coding"/>`，读取 `coding` profile 和其引用的 attractors。
+
+然后读取：
+
+- `codument/attractors/` 与 `codument/std/attractors/`。
+- `codument/behaviors/`。
+- `codument/modeling/` 与 `codument/engineering/`（如果存在）。
+- `codument/decisions/`、`codument/memory/`。
+- 当前 active tracks、missions、archive 中相关历史。
+- 相关源码、测试、配置和文档。
+
+## 3. Questioning
+
+使用 `codument/std/sop/questioning.md` 的 severity：
+
+| severity | 行为 |
+|---|---|
+| `auto` | 不提问，直接基于证据给 route 和保守假设。 |
+| `light` | 默认，只问 P0 用户意图或不可逆取舍。 |
+| `normal` | 可问 P0/P1，每题给推荐答案与取舍。 |
+| `deep` | 适合不确定性大的方向探索，但仍必须把 frontier 收敛到下一步 route。 |
+
+## 4. 分流规则
+
+| route | 条件 | 下一步 |
+|---|---|---|
+| `quick` | 小范围 bug、测试、局部重构、配置修正；不引入新行为契约和长期规划对象 | `codument-impl-quick` |
+| `track` | 新能力、行为变化、架构/模式调整、风险较高或需要 proposal/design/behavior delta | `codument-plan-track` |
+| `mission` | 跨多个 track/仓库，长期自动化，执行期需要重规划 | `codument-plan-mission` |
+| `blocked` | 关键信息缺失、权限/环境不可用、用户目标冲突 | 先补证据或请求用户决策 |
+
+## 5. 输出格式
+
+最终回复必须包含：
+
+```text
+route: quick|track|mission|blocked
+reason:
+suggested_next_command:
+evidence_read:
+open_questions:
+analysis_files:
+```
+
+如果 route 是 `track` 或 `mission`，开始 planning 前清理 `codument/analysis/`。
+
+## 引用
+
+- `codument/std/sop/questioning.md`
+- `codument/std/operations/plan-track.md`
+- `codument/std/operations/plan-mission.md`
+- `codument/std/operations/impl-quick.md`
+- `codument/std/attractors/knowledge-tiers.md`

package/src/templates/codument/std/operations/docs-bootstrap.md

@@ -0,0 +1,148 @@
+# skill: codument-docs-bootstrap（把现存项目总结进分形 docs）
+
+**本提示词供执行文档建模引导的代理阅读。** 当前任务是读取现存项目事实，按 Codument docs 分形规范一次性建立或更新 `docs/modeling/` 与 `docs/impl/`，并记录不确定项，为后续 knowledge sync 打底。
+
+> 本文是完整协议（口径已对齐当前标准）。**程序化的执行流程**（inventory→write-modeling→write-impl→backfill-manifests→record-uncertainty 序列）用流程标记块（` ```text ` + `@delimiter: --`，构造词汇见 `codument/std/operations/_operation-spec.md`）表达；**说明、规则、背景、示例**用 Markdown，内嵌 XML/YAML 用围栏。
+>
+> 口径映射：`codument:docs-bootstrap`→`codument-docs-bootstrap`；`codument/specs/`→`codument/behaviors/`；分形规范路径**修正**为 `codument/std/docs-modeling-fractal/index.md` 与 `codument/std/docs-impl-fractal/index.md`（**不是** `attractors/docs-*-fractal`）。
+
+---
+
+## 0. 总纲
+
+你是 Codument 文档建模代理。当前任务是按 Codument docs 分形规范建立或更新：
+
+- **`docs/modeling/`**：领域本体——领域模型、能力边界、用户/系统行为、约束、状态机、术语、业务规则、与实现无关的外部契约。**领域中立**——类目词汇由本领域真源结构决定，**不写死 web / surface / backend 这类结构**。
+- **`docs/impl/`**：实现知识——目录与模块职责、入口/命令/API/任务流、数据流与持久化、配置/运行/测试/构建、关键实现决策与已知限制。
+
+铁律：**不要把猜测写成事实**。不确定信息必须写入待确认事项（uncertainty / TODO）。
+
+本 skill 是**普通文档整理流程**，不需要 gap-loop 式 fresh child orchestration；只有用户显式要求并行审查时才考虑委派子代理（见 `codument/std/operations/gap-loop.md`）。
+
+**入参**（可选）：`scope`——要总结的子系统 / 目录；缺省全项目。
+
+### 与 docs profile 的关系
+
+- **bootstrap 建立 docs 体系**：这是**一次性引导**，把现状落成分形 docs 的起点。
+- 之后 **track 归档时由 `artifact-sync` 做增量同步**（docs profile enabled + 显式 hook，见 `codument/std/operations/artifact-sync.md`）。
+- 即便 docs profile 未启用，本 skill 也可**纯手动跑**。
+
+---
+
+## 1. 输入读取顺序
+
+1. 读取 `codument/attractors/`；旧项目可兼容读取 `codument/project.md`、`codument/product.md`、`codument/tech-stack.md`。
+2. 读取 `codument/config/attractor-profiles.xml`，确认 `docs` profile 是否启用；**即使未启用，本 skill 仍可手动执行**。
+3. 读取现有 `docs/modeling`、`docs/impl` 与其他 docs 目录。
+4. 读取 README、package/config、入口文件、核心源码目录、测试目录、CLI/API 路由或集成点。
+5. 读取 `codument/behaviors/` 与近期重要 archive/track，**只把能从事实支持的内容写入 docs**。
+
+---
+
+## 2. 写入规则
+
+### 2.1 docs/modeling（稳定知识，领域中立）
+
+写入：领域模型与术语、capability 边界、用户目标与系统行为、约束/状态机/业务规则、与实现无关的外部契约。
+
+按 modeling 分形规范落盘（`codument/std/docs-modeling-fractal/index.md`）：
+
+- 递归规则不变：`plane → context → 类目 → 叶子`；每层 `index.md` 只导航；一处真源、其余引用；derived 用 `derived_from` 指回 canonical。
+- **类目词汇随领域变**：先问"本领域这个 context 的真源天然分成哪几类"，选 3–6 个正交、稳定、领域自然的类目作为 context 第一层子目录——**不要硬套别人的 `objects/policies/workflows` 或写死 web 结构**。
+- 必需 plane：`domain`（canonical 本体）；derived plane 按领域命名（`backend`/`surface`/`runtime`/`pipeline`/…）。
+
+### 2.2 docs/impl（实现知识）
+
+写入：目录与模块职责、入口/命令/API/任务流、数据流与持久化、配置/运行/测试/构建、关键实现决策与已知限制。
+
+按 impl 分形规范落盘（`codument/std/docs-impl-fractal/index.md`）：
+
+- 递归规则同构：`plane → 类目 → 主题 → 叶子`；类目在前、主题在后；本体不放这里，引用 `docs/modeling/`。
+- 推荐默认六类作为起点：`overview / howto / rules / examples / reference / troubleshooting`；领域不适配时在 plane 第一层换成领域自定义类目集。
+- 推荐 plane：`global`（跨 plane 实现知识）；其余按领域命名。
+
+### 2.3 文件组织
+
+- 优先创建**少量可导航文件**；单文件过长时升级为同名目录 + `index.md`。
+- `index.md` 只做导航与摘要，不塞大量正文。
+- **不覆盖用户已有手写内容**；需要重写时保留可追溯摘要。
+
+**最小可用 bootstrap**：若项目还没有 `docs/modeling` 和 `docs/impl`，可先创建两个轻量入口 `docs/modeling/index.md`、`docs/impl/index.md`，先承载事实来源、核心摘要、待确认项与后续拆分计划；一旦正文过长，再把具体主题拆到同名子文件，让 `index.md` 回到导航职责。
+
+---
+
+## 3. 目录职责块（folder-manifest）
+
+对建出的**每个目录**，按 `codument/std/spec/folder-manifest.md` 在其 `index.md` 的 H1 下方写一个**目录职责块**：
+
+- **标准文件夹**（分形默认类目）：可继承分形默认，写一行**精简型**：
+
+  ```markdown
+  > 目录职责 · holds: <装什么> · excludes: <不装什么/去向> · tier: stable|dated · ⬆from: <晋升来源> · ⬇to: <晋升去向>
+  ```
+
+- **自定义文件夹**（本领域自己长出的类目，分形规范无法预知）：**必须**写**完整型**职责块：
+
+  ```markdown
+  ## 目录职责
+  - **holds**：……
+  - **excludes**：……（去向）
+  - **tier**：`stable` | `dated`
+  - **promotes_from**：上游来源层
+  - **promotes_to**：下游去向层
+  ```
+
+字段语义（`holds`/`excludes`/`tier`/`promotes_from`/`promotes_to`）与 tier/晋升语义对齐 `codument/std/attractors/knowledge-tiers.md`。
+
+**补齐（backfill）**：扫描 `docs/` 下每个含 `index.md` 的目录，对**缺职责块**或**自定义目录无完整型块**的补上——从目录名+树中位置套分形默认语义、从实际内容收敛 holds/excludes、从 knowledge-tiers 定 tier 与晋升边；推断不确定时**标 TODO/uncertainty，不臆造**，自定义目录语义模糊时提请人工确认。补齐**幂等**：只补缺失，不覆盖人工已写的块（除非显式确认）。
+
+---
+
+## 4. 执行流程
+
+```text
+@delimiter: --
+-- #sequence ?bootstrap
+---- #step ?inventory
+盘点：按 §1 顺序读 attractors / config / 现有 docs / README+源码+测试+路由 / behaviors+近期 track；列出事实来源与已有 docs 状态；决定哪些知识进 modeling、哪些进 impl
+---- /?inventory
+---- #step ?write-modeling
+按 modeling 分形规范把领域/本体（概念、关系、能力本体、约束、术语）落盘到 docs/modeling/...（领域中立，类目由真源结构决定，不写死 web）；derived 填 derived_from 不复制 canonical
+---- /?write-modeling
+---- #step ?write-impl
+按 impl 分形规范把实现知识（模块、接口、关键流程、运维）落盘到 docs/impl/...（类目在前主题在后，默认六类或领域自定义）；本体引用 docs/modeling，不复制
+---- /?write-impl
+---- #step ?backfill-manifests
+对建出的每个目录按 folder-manifest 给其 index.md 写「目录职责」块（标准类目精简型 / 自定义类目完整型）；扫描缺块的幂等补齐，不覆盖人工块
+---- /?backfill-manifests
+---- #step ?record-uncertainty
+对推断不确定处显式标注 TODO/uncertainty，不臆造；docs profile 关闭时本步仍可纯手动执行
+---- /?record-uncertainty
+---- #step ?review-report
+Review：检查猜测/重复/过度拆分/实现与建模混写；Report：列出更新的文件、未写入原因、待确认问题
+---- /?review-report
+-- /?bootstrap
+```
+
+---
+
+## 5. 验证
+
+- 文档中的事实必须能**追溯**到源码、测试、behavior、track、archive、README 或 attractor。
+- `docs/modeling` **不应**写实现目录细节。
+- `docs/impl` **不应**替代领域/behavior 真源（本体引用 `docs/modeling`，不复制）。
+- 每个建出的目录其 `index.md` 都有合法的目录职责块（自定义类目为完整型）。
+- 如项目无测试或入口不明确，记录为待确认，**不阻塞**已有事实整理。
+
+## 输出
+
+`docs/modeling/**` 与 `docs/impl/**`（含各目录的目录职责块）+ 待确认/不确定项清单。
+
+## 引用
+
+- modeling 分形规范：`codument/std/docs-modeling-fractal/index.md`
+- impl 分形规范：`codument/std/docs-impl-fractal/index.md`
+- 目录职责块格式与补齐：`codument/std/spec/folder-manifest.md`
+- 知识分层 / 晋升 / 真源优先级：`codument/std/attractors/knowledge-tiers.md`
+- 归档期增量 docs 同步：`codument/std/operations/artifact-sync.md`
+- 流程标记块语法：`codument/std/operations/_operation-spec.md`