depa-codument 0.4.1

package/src/templates/codument/std/operations/revise-track.md

@@ -0,0 +1,136 @@
+# skill: codument-revise-track（修订现有 Track 产物）
+
+在 implement、gap-loop、归档准备或其他**非线性工作**中，**修订已有 track 的自包含产物**——增删改 phase/task、调依赖、改 hook，或更新 proposal/design/behavior_deltas/analysis/decisions。它是显式的"改 track 自身"操作，**不替代** implement/gap-loop/archive。
+
+> 本文以 **Markdown 为主**。只有修订的固定执行顺序（前 hook → 定位 → 应用 → 后 hook）与"按变更类型改哪个文件"的分发用流程标记块表达；XML 片段用 ` ```xml ` 围栏内嵌。
+>
+> 口径映射（旧→新，全文一致）：`codument:revise-track`→`codument-revise-track`；`plan.xml`→`track.xml`；`spec_deltas/`→`behavior_deltas/`、`<spec-patch>`→`<behavior-patch>`、"spec"→"behavior"；`attractor-profiles.json`→`config/attractor-profiles.xml`（缺失默认 profile = `coding` → `attractors/project.md`）；`<attractor-check>`/`<confirm>` hook →`<cdt:AttractorCheck use="coding">`/`<cdt:HumanConfirm>`。track.xml 口径见 `codument/std/spec/track-xml-spec.md`，目录布局见其 §0.5。
+
+---
+
+## 0. 意图与触发
+
+**意图。** 修订现有 track 的产物：`proposal` / `design` / `behavior_deltas` / `track.xml`（增删改 phase/task、调度依赖、hook），以及 `analysis` / `decisions`。不替代 implement/gap-loop/archive。
+
+**触发。** 需求细化、范围调整、发现遗漏的阶段 / 任务、调度需改、出现新决策或新上下文时。**动态加入 / 删除 phase**（随任务细化）也走本 skill。
+
+**为什么 revise 在新 track.xml 下很轻。** `<TaskSpace>` 是 **id 寻址、状态标在节点上**的工作树：增删一个 Task = 改一处（加 / 删一个 `<Task>`/`<TaskGroup>` + 必要的一条 `<After>`），不触动他人结构、无全局重编号——这正是新 `track.xml` 相对旧固定三层 `plan.xml` 的优势。
+
+---
+
+## 1. 设置检查（前置）
+
+1. 验证存在 `codument/attractors/`、`codument/std/sop/workflow.md`。
+2. 读 `codument/config/attractor-profiles.xml`；缺失时用默认 profile `coding`（对照 `attractors/project.md`；旧项目兼容 `project.md` + `product.md`）。
+3. 如存在 `codument/config/operation-hooks.xml`，读其中 `operation name="revise-track"` 的 hook 配置。
+
+---
+
+## 2. 选择 Track
+
+```text
+@delimiter: --
+-- #switch ?pick on="用户如何指定 track"
+---- #case ?exact when="给了 track id"
+精确匹配 codument/tracks/<track_id>/
+---- /?exact
+---- #case ?fuzzy when="给了模糊描述"
+列出候选并请求确认
+---- /?fuzzy
+---- #default ?none
+无法唯一确定目标 track → 停止并请求用户补充
+---- /?none
+-- /?pick
+```
+
+---
+
+## 3. 修订前 Hook（revise-track:before）
+
+若 `operation-hooks.xml` 中存在 `Operation name="revise-track"` 的 `<Hook on="revise-track:before">`，则在修改**任何** track 文件**之前**执行它。常见配置是**方向审查**（默认 `cdt:AttractorCheck use="coding"`）：
+
+```xml
+<Operation name="revise-track">
+  <Hooks>
+    <Hook on="revise-track:before">
+      <cdt:AttractorCheck use="coding"/>
+    </Hook>
+  </Hooks>
+</Operation>
+```
+
+**若 hook 返回 `BLOCKED`，不要修改 track 文件**——按 result-policy 处理（如等待用户确认）后再决定是否继续。
+
+---
+
+## 4. 修订 Track
+
+**读取目标 track 的现有产物**（修订依据必须来自 track 目录内）：
+
+- `proposal.md`（与 `proposal/`）
+- `design.md`（与 `design/`，如存在）
+- `behavior_deltas/**/*.xml`
+- `track.xml`
+- `analysis/**`（findings / knowledge）
+- `decisions.md`（与 `decisions/`）
+
+**据 intent 更新最小必要文件**——保 id 稳定，尽量增量编辑（加 / 删一个 `Task`/`TaskGroup`、调一条 `<After>`、改一个 `<Hook>`），不做全局重排：
+
+```text
+@delimiter: --
+-- #switch ?route on="本次修订的性质"
+---- #case ?behavior when="需求 / 行为变化"
+更新 behavior_deltas/<cap>/delta.xml（<behavior-patch>，<upsert|delete|move> wrapper + behavior:// selector）
+---- /?behavior
+---- #case ?design when="方案变化"
+更新 design.md 或 design/
+---- /?design
+---- #case ?tasks when="任务 / 阶段 / 调度变化"
+编辑 track.xml：增删 phase（第一层 TaskGroup）/ task；新增节点 status="NOT_STARTED"；
+调度变化则改 cdt:child-mode 与 <Schedule><Dag for><Node><After ref>；hook 变化则改对应 <Hooks>
+---- /?tasks
+---- #case ?context when="新发现 / 新上下文"
+更新 analysis/findings.md 或 analysis/knowledge.md（外部记忆）
+---- /?context
+---- #case ?decision when="待确认决策"
+追加到 decisions.md（不新建分散决策记录；durable 决策同时落 decisions/<slug>.md）
+---- /?decision
+---- #default ?multi
+以上多类同时变化时，逐一应用最小编辑
+---- /?multi
+-- /?route
+```
+
+**自包含硬规则**：所有必要上下文必须保留在目标 track 目录内。**不引用 `.` 开头隐藏目录，也不引用 track 目录外的说明文档**作为理解本次修订的必需来源。
+
+---
+
+## 5. 校验
+
+- 跑 `codument validate <id> --strict`（结构 / 调度 / 引用；找不到 `codument` 命令则跳过并明确说明）。校验点见 `track-xml-spec.md` §9（id 唯一、`<Dag for>` 指向 dag 层且 `<After ref>` 只引用直接下层且无环、`<Hook on>` 合法、`<cdt:AttractorCheck use>` 能解析到 profile 等）。
+- 更新 `track.xml` 的 `Metadata.UpdatedAt`。
+
+---
+
+## 6. 修订后 Hook（revise-track:after）
+
+若 `operation-hooks.xml` 中存在 `<Hook on="revise-track:after">`，修订完成后执行——可用于人工确认、吸引子复检或生成下一步建议。
+
+---
+
+## 7. 输出
+
+报告：
+
+- **修改过的 track 文件**（哪些 behavior_deltas / design / track.xml / analysis / decisions）；
+- **修订原因**；
+- **是否执行了 operation hook**（before / after，及结果）；
+- **推荐下一步**：继续 `codument-impl-track`、运行 `codument-gap-loop`、再次 `codument-revise-track`，或 `codument-archive-track`。
+
+---
+
+## 8. 引用
+
+- `codument/std/spec/track-xml-spec.md` —— track.xml 三轴规范与目录布局（§0.5）
+- `codument/config/operation-hooks.xml` —— `operation name="revise-track"` 的 before/after hook
+- `codument/config/attractor-profiles.xml` —— `coding`/`docs`/`memory` profile 定义

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

@@ -0,0 +1,339 @@
+# skill: codument-validate（校验 track.xml / behavior）
+
+你是 Codument 行为驱动开发框架的 AI 代理助手。本 skill 校验 track 或 behavior 登记表的格式是否正确：track.xml 结构 / 调度 / hook / 引用，以及 behavior 增量（`<behavior-patch>`）与 behaviors 登记表。
+
+> 本文以 Markdown 为主（校验清单、输出示例、错误表）；**校验流程**（确定目标 → 逐项检查 → pass/fail/strict 分支 → 外部 CLI fallback）用流程标记块。
+>
+> 口径映射（旧命令 / 旧格式 → 当前标准）：`codument:validate`→`codument-validate`；`plan.xml`→`track.xml`（根 `<plan>`→`<Track>`）；`codument/specs/`→`codument/behaviors/`；`spec_deltas/`→`behavior_deltas/`；`<spec-patch>`→`<behavior-patch>`；`spec://`→`behavior://`；「spec」→「behavior」；`list --specs`→`list --behaviors`；旧 `metadata` JSON → `<Metadata>` XML 子元素；旧 `<attractor-check>`/`<confirm>` → `<cdt:AttractorCheck>`/`<cdt:GapLoop>`/`<cdt:HumanConfirm>`；旧 `artifacts.xml` → track.xml 的 `<Ports><MaterialBundle>`。校验规则对齐 `track-xml-spec.md §9`。
+
+---
+
+## 1. 校验流程
+
+接收可选参数 `item`（track 或 behavior 名）与可选 `--strict`。
+
+```text
+@delimiter: --
+-- #sequence ?validate
+---- #step ?args
+解析参数：有 [item] → 校验特定 track/behavior；无 → 批量模式（§6）
+---- /?args
+---- #switch ?type on="item 类型"
+------ #case ?as-track when="item 在 codument/tracks/"
+按 §2 校验 track
+------ /?as-track
+------ #case ?as-behavior when="item 在 codument/behaviors/"
+按 §3 校验 behavior 登记表
+------ /?as-behavior
+------ #case ?ambiguous when="两者都存在或都不存在"
+用 --type 参数消歧
+------ /?ambiguous
+------ #default ?batch
+进入批量模式（§6）
+------ /?batch
+---- /?type
+---- #if ?strict cond="带 --strict"
+执行 §5 额外检查
+---- /?strict
+---- #step ?ext
+尝试外部 CLI fallback（§7）：有 codument 命令则跑 codument validate <item> --strict；找不到则跳过并明确说明已跳过，不阻塞
+---- /?ext
+---- #switch ?verdict on="逐项结果"
+------ #case ?ok when="全部通过"
+按 §4 输出「验证通过」
+------ /?ok
+------ #case ?bad when="存在错误"
+按 §4 输出「验证失败」+ 每项错误定位与修复建议
+------ /?bad
+---- /?verdict
+-- /?validate
+```
+
+---
+
+## 2. 校验 Track
+
+对于 track 目录 `codument/tracks/<track_id>/`：
+
+### 2.1 结构验证
+
+- [ ] `track.xml` 存在且 XML 格式有效（可解析）。
+- [ ] `behavior_deltas/**/*.xml` 存在；旧 track 可兼容 `spec.md`（仅作兼容格式验证）。
+- [ ] 根节点是 `<Track id="...">`，声明 `xmlns:cdt="urn:codument:v1"`（不需要 `config:`）。
+
+### 2.2 `<Metadata>` 验证
+
+`track.xml` 的 `<Metadata>` 应含以下 XML 子元素（取代旧 metadata JSON）：
+
+| 元素 | 约束 |
+|---|---|
+| `<Track id="...">`（根属性） | 必需，字符串，kebab、动词开头，全局唯一（旧 `track_id` 上提为根属性） |
+| `<Status>` | 必需，`new\|in_progress\|completed\|cancelled` 之一 |
+| `<Goal>` | 必需，字符串（旧 `goal`/`description`） |
+| `<CreatedAt>` / `<UpdatedAt>` | 必需，ISO 8601 |
+| `<QuestionMode>` | 可选，`decision-tree`（未指定按 `decision-tree` 处理） |
+| `<QuestionSeverity>` | 可选，`auto\|light\|normal\|deep`（未指定按 `light` 处理） |
+| `<CommitMode>` | 可选，`auto\|manual` |
+
+> 旧 metadata 的 `type`（feature/bug/chore/refactor）若保留则校验枚举；`execution_mode`/`validation_mode`/`summary` 已迁出 `<Metadata>`（分别到 `<Schedule>`/`<Hooks>`/工具派生），不应出现在 `<Metadata>`。
+
+### 2.3 `<TaskSpace>` 结构验证（track-xml-spec §9.1-§9.3）
+
+- [ ] `<TaskSpace>` 必需。
+- [ ] 第一层 `<SubNodes>` 至少一个 `<TaskGroup>`（phase）。
+- [ ] 所有 phase 是第一层 `TaskGroup`（不引入独立 `<Phase>` 标签）。
+- [ ] phase 之下 `Task`（叶）/`TaskGroup`（非叶）任意层级嵌套；id 全局唯一。
+- [ ] 每个 `<TaskGroup>`/`<Task>` 有 `id`；`status` 为枚举 `NOT_STARTED|ACTIVE|DELEGATED|FORWARDED|DONE|REFUSED|ABANDONED`。
+- [ ] codument 扩展节点合法：`<cdt:Gate>`（阶段门控）、`<cdt:Acceptance>`（验收）、`<cdt:Priority>`/`priority` 属性。
+
+### 2.4 `<Schedule>` 调度验证（track-xml-spec §9.4）
+
+- [ ] `<Schedule>` 与 `<TaskSpace>` 并列（兄弟节点）。
+- [ ] 每个 `<Dag for="P">` 的 `for` 引用一个 `cdt:child-mode="dag"` 的节点。
+- [ ] 其 `<Node id>` 与子 `<After ref>` 只引用该节点的**直接下层** id（不跨层、不跨父）。
+- [ ] 该层内 DAG 无环。
+- [ ] 未标 `dag` 的层默认 `sequential`、按 `order` 执行，无需任何依赖配置。
+- [ ] 可选 `<Parallel max-concurrent spot-check>`（旧 wave_config）取值合法。
+
+### 2.5 `<Hooks>` 与引用验证（track-xml-spec §9.5）
+
+- [ ] `<Hook on="...">` 取值合法：`track:before|after`、`phase:before|after`、`task:before|after`。
+- [ ] `<cdt:AttractorCheck use="...">` 的 `use` 能在 `config/attractor-profiles.xml` 解析到 profile（如 `coding`/`docs`/`memory`）。
+- [ ] `<cdt:GapLoop>` 的 `max-rounds`/`on-exhausted`（如 `block`）合法。
+- [ ] `<cdt:HumanConfirm/>` 保持现有 confirm 协议约束。
+- [ ] `cdt:` 命名空间已声明。
+
+### 2.6 `<Ports>` / MaterialBundle 验证
+
+- [ ] `<Ports scope="track">` 的 `<MaterialBundle>` `role`（input/output）、`domain`、`path`（`vfs://...`）合法。
+- [ ] track 作用域**不设** JSON input/output 端口（出现则报错）。
+- [ ] input 物料含 `behavior_deltas`；output 物料含 `docs` 与 `behavior`（`codument/behaviors/`）。
+
+### 2.7 behavior 增量验证（旧 XML spec delta）
+
+对 `behavior_deltas/<capability>/delta.xml`：
+
+- [ ] 至少存在一个 `behavior_deltas/**/*.xml` 文件。
+- [ ] 每个 XML delta 根节点是 `<behavior-patch capability="<capability>" version="1">`。
+- [ ] 每个 mutation 使用 `<upsert|delete|move selector="behavior://...">` wrapper；`move` 还必须有 `to="behavior://..."`。
+- [ ] 新增/修改内容用 `<requirement>`、`<statement>`、`<suite>`、`<case>` 等业务节点表达。
+- [ ] BDD 场景用可嵌套 `<suite>` / `<case>`，case 内用 `<given>`、`<when>`、`<then>`。
+- [ ] 旧 track 的 `spec.md` 仅作兼容格式验证。
+
+---
+
+## 3. 校验 Behavior 登记表
+
+对于 behavior 目录 `codument/behaviors/<capability>/`：
+
+### 3.1 结构验证
+
+- [ ] `behaviors/<capability>.xml` 或 `behaviors/<capability>/index.xml` 存在；旧 registry 可兼容 `behaviors/<capability>/spec.md`。
+
+### 3.2 XML behavior 验证
+
+- [ ] XML 根节点是 `<capability id="...">`。
+- [ ] 至少包含一个 `<requirement>`。
+- [ ] 至少包含一个 `<case>`。
+
+---
+
+## 4. 输出格式
+
+### 验证通过
+
+```text
+✓ codument/tracks/add-user-auth/
+  ✓ track.xml <Metadata> - 有效
+  ✓ <TaskSpace> - 有效 (2 个 phase, 8 个任务)
+  ✓ <Schedule> - 有效 (1 个 dag 层, 无环)
+  ✓ <Hooks> - 有效 (use=coding 解析成功)
+  ✓ behavior_deltas - 有效 (2 个 patch, 3 个 capability)
+
+验证通过！
+```
+
+### 验证失败
+
+```text
+✗ codument/tracks/add-user-auth/
+  ✓ track.xml <Metadata> - 有效
+  ✗ behavior_deltas/csv-export/delta.xml - 错误
+    - XML behavior delta root must be <behavior-patch>
+    - XML behavior delta must contain at least one mutation with a behavior:// selector
+  ✓ <TaskSpace> - 有效
+
+验证失败！请修复以上错误后重试。
+```
+
+---
+
+## 5. 严格模式（--strict）
+
+使用 `--strict` 时执行额外检查。
+
+### Track 额外检查
+
+- [ ] `proposal.md` 存在（如果是新 track）。
+- [ ] `proposal.md` 含必需部分：背景、变更内容、影响范围。
+- [ ] `design.md` 格式正确（如果存在）。
+- [ ] 所有 `<case>` 的 `<when>` / `<then>` 语义完整。
+- [ ] 无重复的需求名称。
+- [ ] 任务 ID 唯一且符合命名规范（phase=`P{n}`、task=`T{phase}.{n}`、验收=`{taskId}-AC{n}`）。
+
+### Behavior 额外检查
+
+- [ ] 无重复的需求名称。
+- [ ] 所有需求有唯一标识符。
+- [ ] `design.md` 存在且格式正确（如果能力复杂）。
+
+### Operation Hooks 额外检查
+
+如果存在 `codument/config/operation-hooks.xml`：
+
+- [ ] 根节点是 `<OperationHooks version="1">`（或等价 `<Hook on>` 同构语法）。
+- [ ] `<Hook on="...">` 使用已知 operation 生命周期点，例如 `plan-track:before`、`plan-mission:before`、`archive-track:after`、`revise-track:before`。
+- [ ] hook 内嵌套的 `<cdt:AttractorCheck>`/`<cdt:ArtifactSync>`/`<cdt:GapLoop>`/`<cdt:HumanConfirm>` 遵循同一套 DSL。
+- [ ] `<cdt:AttractorCheck use="...">` 解析到 `attractor-profiles.xml` 的 profile，不使用 direct 文件属性。
+- [ ] 缺失 `operation-hooks.xml` 是合法状态，不产生错误。
+
+---
+
+## 6. 批量验证
+
+当未指定 `[item]` 时：
+
+1. 列出所有 `codument/tracks/` 下的 tracks。
+2. 列出所有 `codument/behaviors/` 下的 behaviors。
+3. 依次验证每个项目。
+4. 汇总结果：
+
+```text
+批量验证结果:
+
+Tracks:
+  ✓ add-user-auth
+  ✓ update-payment-flow
+  ✗ fix-login-bug (2 个错误)
+
+Behaviors:
+  ✓ auth
+  ✓ payment
+
+总计: 4 通过, 1 失败
+```
+
+---
+
+## 7. 外部 CLI fallback
+
+若系统装有 `codument` 命令，可跑 `codument validate <item> --strict` 作为补充。**找不到 `codument` 命令时，跳过该步并明确说明「已跳过外部 CLI 校验（未找到 codument 命令）」，不阻塞**——本 skill 的 Markdown 清单校验已是权威结果。
+
+---
+
+## 8. 参考
+
+### 常见错误及修复
+
+| 错误 | 原因 | 修复 |
+|------|------|------|
+| "XML behavior delta root must be <behavior-patch>" | 新 track 误写成 Markdown 或 XML 根节点错误 | 改为 `<behavior-patch capability="<capability>" version="1">` |
+| "XML behavior delta must contain at least one mutation" | patch 中没有 selector mutation | 添加带 `selector="behavior://..."` 的 `<upsert>` / `<delete>` / `<move>` 节点 |
+| "Invalid XML format" | track.xml 语法错误 | 检查 XML 标签闭合 |
+| "Missing required field in <Metadata>" | `<Metadata>` 缺字段 | 补 `<Status>`/`<Goal>`/`<CreatedAt>` 等 |
+| "Track must have at least one delta" | 没有 XML behavior delta | 添加 `behavior_deltas/<capability>/delta.xml` |
+| "Dag for refers to non-dag node" | `<Dag for>` 指向未标 `cdt:child-mode="dag"` 的节点 | 给该节点加 `cdt:child-mode="dag"`，或移除该 Dag |
+| "After ref crosses layer" | `<After ref>` 引用了非直接下层 id | 只在同一父的直接下层之间连边 |
+
+---
+
+## 9. 独立验证子代理模式
+
+当本 skill 被旧 `codument-execute-wave` 入口作为验证子代理调用时，执行以下独立验证流程；当前标准下波次执行已并入 `codument-impl-track`。
+
+### 9.1 触发条件
+
+当提示词中包含以下参数时，进入独立验证模式：
+
+- `workspace_dir`：工作区根目录。
+- `track_dir`：track 目录路径。
+- `wave_id`（可选）：指定验证的 wave。
+- `phase_id`（可选）：指定验证的 phase。
+
+### 9.2 Goal-Backward 验证方法
+
+从目标倒推验证，而非从代码正推：
+
+1. **读取验收标准：** 从 `track.xml` 提取目标 task 的 `<cdt:Acceptance>` 标准。
+2. **逐条验证：** 对每个 criterion，检查实现是否满足。
+3. **报告差距：** 列出未满足的标准和原因。
+
+### 9.3 三级验证
+
+对每个已完成的 task，执行三级递进验证：
+
+**Level 1: Exists（存在性）**
+- 验证 task 声明要修改/创建的文件是否存在。
+- 验证 git commits 是否存在（auto 模式 / `CommitMode=auto`）。
+- 验证 task `status` 是否为 `DONE`。
+
+**Level 2: Substantive（实质性）**
+- 验证文件内容是否包含 task 描述（`<Description>`）中提到的关键变更。
+- 验证代码变更是否与 `<cdt:Acceptance>` criteria 对应。
+- 验证测试是否存在且通过（如 workflow 要求 TDD）。
+
+**Level 3: Wired（连通性）**
+- 验证新增代码是否被正确引用/导入。
+- 验证新增功能是否在系统中可达。
+- 验证配置变更是否生效。
+
+### 9.4 验证报告格式
+
+```text
+📋 **验证报告：<wave_id 或 phase_id>**
+
+## 总览
+- 验证任务数：<n>
+- 通过：<n>
+- 失败：<n>
+
+## 详细结果
+
+### T{x}.{y}: <task name>
+
+**Level 1 - Exists:** ✅ 通过
+- [x] 文件存在：src/foo.ts
+- [x] Task 状态：DONE
+
+**Level 2 - Substantive:** ✅ 通过
+- [x] AC1: <标准描述> — 已验证
+- [x] AC2: <标准描述> — 已验证
+
+**Level 3 - Wired:** ⚠️ 部分通过
+- [x] 导入正确：src/index.ts 引用了 src/foo.ts
+- [ ] 配置未更新：config.json 缺少新字段
+
+## 阻塞问题
+- <问题描述>（影响：<影响范围>）
+
+## 非阻塞问题
+- <问题描述>（建议：<改进建议>）
+```
+
+### 9.5 输出协议
+
+验证结果必须按以下顺序输出（issues-first）：
+
+1. **阻塞问题**（blocking issues）— 必须修复才能继续。
+2. **非阻塞问题**（non-blocking issues）— 建议修复但不阻塞。
+3. **简要总结**（brief summary）— 通过/失败统计。
+
+---
+
+## 10. 参考
+
+- track 文件格式与校验规则：`codument/std/spec/track-xml-spec.md`（§9）
+- behavior delta 写法：`codument/std/spec/behavior-delta.md`
+- behavior 登记表格式：`codument/std/spec/behavior-registry.md`
+- profile 配置：`codument/config/attractor-profiles.xml`
+- 命令级 hook：`codument/config/operation-hooks.xml`

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

@@ -0,0 +1,184 @@
+# skill: codument-verify（独立验证 · fresh-subagent 实跑）
+
+以**独立验证模式**确认 track 的实现真正达成目标：fresh-spawn 一个独立子代理，**实际运行**应用/测试、复现验收用例，对照 `cdt:Acceptance`/`cdt:Gate` 与 behavior 验收用例从目标倒推，逐条给 PASS/FAIL + 证据，落 `track://reports/verify-report.md`。**只判定不修复**；有 FAIL 则列差距并建议回 `implement`/`gap-loop`。
+
+> 本文是完整提示词（口径已对齐当前标准）。**程序化的执行流程**（逐验收项的实跑 → PASS/FAIL 判定 → 收口/回退）用流程标记块（` ```text ` + `@delimiter: --`，构造词汇见 `_operation-spec.md`）表达；**说明、规则、背景、模板**用 Markdown，内嵌 XML 用 ```` ```xml ```` 围栏。
+>
+> 口径映射：`codument:verify`→`codument-verify`；`plan.xml`→`track.xml`；phase=第一层 `<TaskGroup>`；`acceptance_criteria`→`cdt:Acceptance`、`gate_criteria`→`cdt:Gate`；`spec_deltas/`→`behavior_deltas/`、`spec://`→`behavior://`、“spec”→“behavior”；`execution_mode=wave`→某层 `cdt:child-mode="dag"`（wave=该 dag 层的拓扑分层派生视图）；报告落 `track://reports/verify-report.md`（=`codument/tracks/<id>/reports/`）。
+
+---
+
+## 0. 角色与定位
+
+你是 Codument 规范驱动开发框架的**独立验证代理**。职责是：
+
+- **不参与实现，只做验证**。
+- 从目标与验收标准**倒推**，验证实现是否真实成立。
+- 按 **issues-first** 输出（先阻塞问题，再非阻塞问题，再结论）。
+
+**verify 与 gap-loop 的区别**：gap-loop 对照"目标 vs 实现产物"做方向/完成度纠偏**并修复**；verify 是**独立运行真实行为**确认可用（跑测试、启动应用、复现用例），**只判定不修复**。verify 必须用 fresh-subagent 执行以保证独立性，且**实际运行而非只读代码**。报告状态对照失败时不轻易判 PASS。
+
+---
+
+## 1. 设置检查
+
+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. 验证目标选择
+
+1. **识别 track：**
+   - `{{args}}` 含 `<track-id>` → 优先精确匹配；若精确且唯一匹配，直接使用；仅在无匹配或多个候选时请求澄清。
+   - 否则从 `codument/tracks/` 与各 track 的 `track.xml`（`<Metadata><Status>`）选第一个活跃 track。
+
+2. **识别验证范围（可选）：**
+   - `{{args}}` 可附带 `P{n}`（phase）或某 dag 层的某波次标识；未指定时验证整个 track。
+
+3. **读取上下文文件：**
+   - `codument/tracks/<track_id>/track.xml`
+   - `codument/tracks/<track_id>/behavior_deltas/**/*.xml`；旧 track 可兼容 `codument/tracks/<track_id>/spec.md`
+   - `codument/tracks/<track_id>/proposal.md`
+   - `codument/tracks/<track_id>/design.md`（如存在）
+   - `codument/tracks/<track_id>/decisions.md` / `analysis/`（如存在，迭代期背景）
+   - `codument/tracks/<track_id>/reports/`（已有历史报告，如存在）
+
+---
+
+## 3. 验证方法
+
+### 3.1 Goal-Backward（目标倒推）
+
+1. 从 `track.xml` 提取目标 task 的 `cdt:Acceptance`（验收标准），以及所属 phase 的 `cdt:Gate`（阶段门控）。
+2. 按 criterion 逐条反推：
+   - 需要哪些代码/配置/文件存在。
+   - 需要哪些行为可达。
+   - 需要哪些测试或证据支持。
+3. 可选补充：从 `behavior_deltas/**/*.xml` 的行为 case（suite/case）取验收用例作复现依据。
+
+### 3.2 三级验证
+
+对每个目标 task 执行以下三层验证：
+
+1. **Exists（存在性）**
+   - 文件是否存在。
+   - task 的 `status` 是否与实现一致。
+   - auto 提交模式下是否存在对应 commit（如适用）。
+
+2. **Substantive（实质性）**
+   - 代码/配置改动是否真正满足 task 的 `<Description>`。
+   - 是否覆盖 `cdt:Acceptance` 各 criterion。
+   - 相关测试是否存在并能支持结论。
+
+3. **Wired（连通性）**
+   - 新增能力是否被正确引用/接入。
+   - 入口是否可达。
+   - 系统路径是否连通（不是"孤立代码"）。
+
+### 3.3 Wave 模式附加检查（如适用）
+
+若目标范围所在层标了 `cdt:child-mode="dag"`（wave = 该层依赖的拓扑分层派生视图）：
+
+- 检查目标波次内各 Task 是否按依赖完成。
+- 检查跨波次依赖产物（前驱 Task 的 output）是否被后续波次正确使用。
+
+---
+
+## 4. 独立执行与逐项判定
+
+verify 的核心是**派发 fresh-subagent 实际运行**——不是父代理顺手读一遍代码。父代理只负责收集验证目标、spawn 子代理、汇总其 PASS/FAIL，并据结论决定收口/回退。
+
+```text
+@delimiter: --
+-- #sequence ?verify
+---- #step ?v1
+父代理：从 track.xml 收集所有 cdt:Acceptance、cdt:Gate，以及 behavior_deltas 的验收用例（suite/case），按范围（整 track / phase / wave）圈定目标集
+---- /?v1
+---- #spawn ?run as=fresh-subagent inject="按 agent 类型注入模型/档位，如 codex→gpt-5.5、effort=high"
+独立上下文：实跑测试 / 启动应用 / 复现用例，观察真实行为（不只读代码）；对每条验收逐项判定并收集证据
+---- /?run
+---- #loop ?items for="每条 cdt:Acceptance / cdt:Gate / behavior case"
+------ #step ?ex
+三级验证：Exists（文件/状态/commit）→ Substantive（满足描述、覆盖 criterion、测试支持）→ Wired（被接入、入口可达、路径连通）
+------ /?ex
+------ #switch ?verdict on="实跑结果"
+-------- #case ?pass when="行为真实达成、证据充分"
+记 PASS + 证据（命令输出 / 测试结果 / 复现步骤 / 文件定位）
+-------- /?pass
+-------- #case ?fail when="未达成 / 行为错误 / 证据缺失"
+记 FAIL + 差距（定位、影响、修复建议）；不在 verify 内修复
+-------- /?fail
+------ /?verdict
+---- /?items
+---- #step ?report
+汇总写报告 → track://reports/verify-report.md（issues-first：阻塞 → 非阻塞 → 结论）
+---- /?report
+---- #switch ?conclude on="是否存在 FAIL"
+------ #case ?allpass when="全部 PASS"
+-------- #return ?ok value="PASS：报告可进归档（codument-archive-track）"
+-------- /?ok
+------ /?allpass
+------ #case ?hasfail when="存在 FAIL"
+-------- #return ?back value="FAIL：列差距，建议回 codument-impl-track 修实现 / codument-gap-loop 做目标对比修复"
+-------- /?back
+------ /?hasfail
+---- /?conclude
+-- /?verify
+```
+
+**fresh-spawn 注入（按 agent 类型）：** 父代理 spawn 验证子代理时按当前运行的 agent 类型注入模型/档位——例如 **codex → 模型 `gpt-5.5`、`effort=high`**；其他 agent 按其高能力档。落盘 skill 时由对应 agent 生成器补充该注入；本协议在此声明意图，确保自包含 skill 不丢"用高能力档 fresh-subagent 实跑验证"这一要求。
+
+**只判定不修复：** verify 子代理发现 FAIL 时记录差距即可，**不得**在本流程内修改实现（修复属于 `implement`/`gap-loop` 的职责）。
+
+---
+
+## 5. 输出协议（issues-first）
+
+输出顺序必须为：
+
+1. **阻塞问题（Blocking Issues）** — 会导致验收失败或行为错误的问题。每条含：定位、影响、修复建议。
+2. **非阻塞问题（Non-Blocking Issues）** — 质量或一致性问题。
+3. **简要结论（Summary）** — 验证范围、通过/失败任务数、是否可进入下一步（如归档）。
+
+报告落 `track://reports/verify-report.md`（=`codument/tracks/<id>/reports/verify-report.md`，按需带轮次/范围后缀以与历史报告区分）。模板：
+
+```text
+📋 验证报告：<track_id> [范围]
+
+Blocking Issues:
+- <问题1>（定位 / 影响 / 修复建议）
+
+Non-Blocking Issues:
+- <问题1>
+
+逐项判定:
+- <AC/Gate/case id>: PASS | FAIL — <证据 / 差距>
+
+Summary:
+- 验证任务数：<n>
+- 通过：<n>
+- 失败：<n>
+- 结论：PASS | FAIL
+- 下一步：全 PASS → codument-archive-track；有 FAIL → codument-impl-track / codument-gap-loop
+```
+
+> 全 PASS 才可进归档；有 FAIL 则列差距并建议回 `implement`（补实现）或 `gap-loop`（目标对比纠偏修复）。报告/状态对照失败时不轻易判 PASS。
+
+---
+
+## 引用
+
+- `codument/std/spec/track-xml-spec.md`（`cdt:Acceptance`/`cdt:Gate`、phase=第一层 TaskGroup、wave=dag 层派生视图）
+- `codument/std/sop/validation.md`（裁决词汇、fresh-subagent 执行约定）
+- `codument/std/operations/gap-loop.md`（FAIL 后的目标对比修复双角色协议）
+- `codument/std/operations/impl-track.md`（FAIL 后补实现）
+- `codument/std/sop/questioning.md`（ask-* 协议）