zdoc-i2i

name: zdoc-i2i description: "设计文档到实施任务转化引擎。输入 15+ 种设计文档（PRD/Arch/API/UX/Tech/Test/Data/DDD/...），源文档交叉一致性校验 → 内容整合 → 按最小可验收颗粒度拆分 Task → 交付前自动审核 → 产出独立 impl 文档 + 依赖 DAG + 交付报告。纯 LLM + 结构化输出架构。" argument-hint: "[--dir DIR] [--feature ID] [--prd PATH] [--arch PATH] [--api PATH] [--ux PATH] [--tech PATH] [--test PATH] [--data PATH] [--ddd PATH] [--output-dir DIR] [--validate-only]" allowed-tools: - Read - Write - Edit - Bash - Grep - Glob

zdoc-i2i

Design-to-Impl Skill — 将设计文档转化为可执行的实施任务。纯 LLM + 结构化输出架构，复用 Design Check Gate Rubric 做输入校验。

1. 目标与非目标

1.1 目标

• 将 15+ 种设计文档（PRD/Arch/API/UX/Tech/Test/Data/DDD/...）转化为可执行的实施任务
• 执行源文档交叉一致性校验，确保输入文档之间无冲突
• 按最小可验收颗粒度拆分 Task，产出带依赖 DAG 的独立 impl 文档
• 交付前自动审核，产出 delivery-report.json 质量报告
• 成功执行后自动冻结输入文档状态（approved → frozen）

1.2 非目标

• 不修改源文档：只读取设计文档，不修改任何输入文件（状态冻结除外）
• 不生成代码：产出实施计划文档（task-*.md + INDEX.md + SUMMARY.md），不产出业务代码
• 不做 gate 决策：evidence-only，汇总报告供人工确认，不自动判定通过/不通过
• 不替代 Design Check：zdoc-design-check 校验设计质量，zdoc-i2i 做实施转化，两者互补
• 不补充缺失信息：不发明设计文档中没有的功能、技术方案或业务规则

2. 输入/输出

2.1 输入

输入模式：目录扫描（--dir）/ 显式指定（--prd/--arch 等）/ 混合（--dir + 覆盖）三种模式。

必输文档：T01 PRD、T02 Architecture 缺失 → BLOCK。仅接受 approved 或 frozen 状态文档；draft / reviewing → BLOCK。

2.2 输出

2.3 退出状态

3. 执行步骤

I2I Pipeline 按以下 6 个 Phase 顺序执行：

详细执行步骤见下方各 Phase 章节。

Primary Abstraction

Skill (governed capability template)

Secondary Abstraction

Pipeline — LLM 4-phase validation + integration + decomposition + generation

Authority

Canonical bundle: zdoc-i2i/

Canonical Authority

• ADR: ADR-004 v1.7（设计文档到实施任务拆分技能 — I2I Design-to-Impl Skill）
• Reference: DOC-WRITING-GUIDE v1.0 (输出文档结构规范 — frontmatter / 标准章节 / 命名 / 交叉引用)

Runtime Boundary Baseline

This capability is a governed Skill for Design Documents → Implementation Tasks transformation.

• Read-only — does NOT modify source design documents.
• 只整合不补充 — does NOT invent features, tech solutions, or business rules not in input docs.
• 最小可验收颗粒度 — each Task must satisfy 5 conditions (§3.4 of ADR-004).
• 上下文自包含 — each Task impl doc is independently executable.
• DAG 确定性校验 — cycle detection via validate-dag.py, not LLM.
• 文档状态准入 — only accepts approved or frozen status documents; draft / reviewing → BLOCK.
• 执行后冻结 — successful execution sets all input documents to frozen status.

架构

┌─────────────────────────────────────────────────────────────────────┐
│              I2I — 设计文档 → 实施任务 转化引擎                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Phase 0: 源文档交叉一致性校验                                       │
│  ──────────────────────────────────────────                         │
│  1. ARCH ↔ TESTSET 交叉扫描（数量/语义/路径/版本）                    │
│  2. 约束溯源图构建                                                   │
│  3. 术语/命名预扫描                                                  │
│  4. BLOCK → 要求源文档澄清后重跑                                     │
│                                                                     │
│  Phase 1: 输入校验（内嵌 Gate Rubric）                               │
│  ──────────────────────────────────────────                         │
│  1. 识别输入文档类型（15+ 种）                                       │
│  2. 校验必输要素 → BLOCK / CONDITIONAL / PASS                       │
│  3. BLOCK → 返回缺失清单，停止                                       │
│                                                                     │
│  Phase 2: 内容整合                                                  │
│  ──────────────────────────────────────────                         │
│  按 Feature 聚合跨文档信息 → feature-context.md                      │
│                                                                     │
│  Phase 3: 任务拆分                                                  │
│  ──────────────────────────────────────────                         │
│  最小可验收颗粒度拆分 → task-list.json → validate-dag.py             │
│  → 依赖完整性校验 → dependency-suggestions.json                      │
│                                                                     │
│  Phase 4: 文档生成                                                  │
│  ──────────────────────────────────────────                         │
│  task-*.md + INDEX.md + SUMMARY.md + IMPL-INDEX.md                  │
│                                                                     │
│  Phase 5: 交付前审核 + 交付报告                                      │
│  ──────────────────────────────────────────                         │
│  自动审核清单 → delivery-report.json                                 │
│                                                                     │
│  输入: 设计文档路径                                                   │
│  输出: impl-{feature}-{PRD-ID}/ 目录 + delivery-report.json         │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Phase 0: 源文档交叉一致性校验

执行步骤：

1. 识别所有已识别的输入文档对（ARCH ↔ TESTSET、ARCH ↔ PRD、API ↔ TECH 等）
2. 执行交叉一致性扫描（§0.1），记录冲突项
3. 构建约束溯源图（§0.2），记录 §11 门槛与 §4/§5/§8 具体约束的对应关系
4. 执行术语/命名预扫描（§0.3），检查 API 名称版本标注
5. 执行原型文件检测与索引（§0.6），建立 UX Spec ↔ Prototype 映射
6. 输出 source-consistency-report.json
7. 任一 BLOCK 级冲突 → 要求源文档澄清后重跑，不进入 Phase 1
8. 仅 WARN → 记录到报告，带标注进入 Phase 1

0.1 交叉一致性扫描

扫描以下维度：

0.2 约束溯源图构建

记录 §11 门槛与具体约束的映射关系：

§11 门槛 N → 对应 §X.Y 具体约束 → TESTSET 测试点编号

作用：

• 当 TESTSET 细化约束时（如 4 条 → 7 条），溯源图能自动检测 ARCH §11 是否需要同步更新
• 拆解出的 task acceptance criteria 可以自动携带溯源链，避免约束丢失

0.3 术语/命名预扫描

0.4 源代码路径规范化

问题：设计文档中可能使用简写路径（如 src/handlers/），但实际项目源代码位于更深层级（如 apps/ai-coach-skill/src/handlers/）。如果 Task 文档中沿用简写路径，Agent 执行时可能在项目根目录错误创建 src/ 目录。

执行步骤：

1. 如果指定了 --src 参数，将其作为源代码根路径基准
2. 从设计文档（Architecture / Tech Design）中提取所有引用的源代码文件路径
3. 对每个路径执行规范化：
   • 如果路径以 src/ 开头且 --src 指定了更深层级（如 apps/ai-coach-skill/src），将路径前缀替换为完整路径
   • 例如：src/handlers/register.ts → apps/ai-coach-skill/src/handlers/register.ts
4. 将规范化后的路径记录到 source-consistency-report.json 的 path_normalization 字段
5. 后续 Phase 4 生成 Task 文档时，所有文件路径必须使用项目根目录相对路径（非简写）

路径规范化规则：

用途：此规范化结果写入 source-consistency-report.json，Phase 4 读取并应用到所有 Task 文档的"关键文件"和"产出物"路径中。

0.6 原型文件检测与索引

问题：设计文档（如 UX Spec）可能引用 HTML/原型文件作为视觉和交互的参考源，但任务拆分时往往只间接引用 UX Spec，丢失了原型的直接引用链，导致实施者不知道有原型可参考。

执行步骤：

1. 扫描 ux-prototypes/ 目录下的所有非 Markdown 文件（HTML、Vue、React 等可运行原型）
2. 对每个原型文件，提取其覆盖的交互阶段/Phase/模块信息（通过文件名、目录结构或文件内注释）
3. 将原型文件路径与 UX Spec 文档的 references 字段交叉比对，建立 UX Spec ↔ Prototype 映射关系
4. 记录到 source-consistency-report.json 的 prototype_index 字段
5. 后续 Phase 3 拆分 UI 相关 Task 时，自动注入对应原型的直接引用

原型识别规则：

原型阶段映射：

对 HTML 等可运行原型，提取其内部注释或 DOM 结构中标注的 Phase/阶段划分（如 <!-- PHASE B: 表单填写 -->），建立「原型阶段 → 对应 UX Spec 章节 → 对应 Task」的三层映射。

0.5 输出 source-consistency-report.json

{
  "feature_id": "ARCH-LITE-XXX",
  "generated_at": "...",
  "status": "PASS | FAIL | WARN",
  "consistency_checks": [
    {
      "dimension": "quantity_consistency",
      "status": "PASS | FAIL",
      "details": "..."
    }
  ],
  "prd_tech_alignment": {
    "enum_checks": [
      {
        "field": "gender",
        "prd_source": "PRD-M12 FR-M12-001 L378",
        "prd_values": ["male", "female"],
        "tech_source": "TECH-M12 §2.3.1",
        "tech_values": ["male", "female", "other"],
        "arch_source": "ARCH-M12 L136",
        "arch_values": ["male", "female", "other", "prefer_not_to_say"],
        "status": "FAIL",
        "resolution": "以 PRD 为准，TECH/ARCH 移除 extra values"
      }
    ],
    "numeric_checks": [
      {
        "concept": "邀请码长度",
        "prd_value": "8位",
        "prd_source": "PRD-M12 FR-M12-001 L378",
        "discrepancies": [
          { "doc": "BUSINESS-M12 L114", "value": "6位", "location": "ASCII 流程图" }
        ],
        "status": "FAIL"
      }
    ],
    "field_existence_checks": [
      {
        "field": "pain_impact_level",
        "prd_referenced": true,
        "prd_location": "PRD-M12 Open Questions #5 L786",
        "tech_defined": false,
        "status": "WARN",
        "resolution": "stale discussion in PRD, field removed in v3.0"
      }
    ],
    "encoding_format_checks": [
      {
        "field": "injury_selections",
        "tech_header": "{body_part}_{injury_type}_{severity}",
        "tech_mapping_table": ["none", "knee", "ankle_foot", "hip_back", "illness_recovery", "doctor_advice", "other"],
        "api_values": ["none", "knee", "ankle_foot", "hip_back", "illness_recovery", "doctor_advice", "other"],
        "status": "WARN",
        "resolution": "TECH header is design-level description, API enum values are canonical"
      }
    ]
  },
  "constraint_traceability": [
    {
      "gate_id": "§11 N",
      "source_section": "§X.Y",
      "test_points": ["HP-01", "BC-01"]
    }
  ],
  "naming_issues": [],
  "path_normalization": {
    "src_base": "apps/ai-coach-skill/src",
    "normalized_paths": [
      {
        "original": "src/handlers/register.ts",
        "normalized": "apps/ai-coach-skill/src/handlers/register.ts"
      }
    ]
  },
  "prototype_index": [
    {
      "file": "ux-prototypes/proto-m12-onboarding.html",
      "type": "html",
      "phases": [
        {
          "phase_id": "PHASE-A",
          "description": "邀请码验证",
          "ux_spec_section": "UX-M12 §3.1"
        },
        {
          "phase_id": "PHASE-B",
          "description": "5题身份建档表单",
          "ux_spec_section": "UX-M12 s9.3"
        }
      ],
      "referenced_by": ["UX-M12-Onboarding-Identity.md"]
    }
  ]
}

Phase 1: 输入校验

执行步骤：

1. 解析 {{args}}，确定输入模式（目录扫描 / 显式指定 / 混合）
2. 使用 Glob 扫描输入目录，按§1.4 优先级识别文档类型
3. 检查文档状态（§1.7），仅接受 approved / frozen，draft / reviewing → BLOCK
4. 对每个已识别文档执行 Gate 校验（§1.5），记录 PASS / WARN / FAIL
5. 必输文档（T01 PRD、T02 Arch）缺失 → BLOCK，输出缺失清单并停止
6. 汇总判定三态（§1.6），CONDITIONAL 时记录 WARN 项
7. 如有 --validate-only，输出校验结果后停止

1.1 输入模式

根据参数组合确定输入模式：

1.2 文档类型优先级

文档分为必输和可选两类：

必输文档缺失 → BLOCK；可选文档缺失 → 跳过，不影响判定。

1.3 文档发现与类型识别

使用 Glob 工具扫描输入目录，按以下优先级识别文档类型：

识别优先级: 文件名前缀 > 目录路径 > 内容特征

1. 文件名前缀匹配（最高优先级）
   PRD-*     → T01  ARCH-*    → T02  API-*     → T03
   BUSINESS-*→ T04  TECH-*     → T05  UX-*      → T06
   TESTSET-* → T08  DataFlow-* → T09  DDD-*     → T10
   SKILL-*   → T11  ADAPTER-*  → T12  JOB-*     → T13

2. 目录路径匹配（次优先级）
   prds/      → T01  arch/      → T02  api/       → T03
   business/  → T04  tech/      → T05  ux/        → T06
   ux-prototypes/ → T07  testset/ → T08  data/    → T09
   ddd/       → T10  skills/    → T11  adapters/  → T12
   jobs/      → T13  stg/       → T14  reviews/   → T15

3. 内容特征匹配（兜底）
   含用户故事/AC          → T01  含架构分层/技术选型 → T02
   含 API 端点/Schema     → T03  含交互流程/设计原则 → T06
   含设计系统/组件规范     → T07  含测试范围/Happy Path  → T08
   含领域模型/聚合根      → T10  含数据流转/状态机  → T09

1.4 Gate 校验（内嵌 Gate Rubric）

读取 gate/rubric.md，对每个已识别的文档执行以下校验：

1.5 三态判定

对每个文档的 Gate 结果做汇总判定：

如果判定为 BLOCK，输出格式：

## 输入校验失败 — BLOCK

以下文档缺失必输要素，无法进入实施转化：

| 文档 | 类型 | 缺失项 |
|------|------|--------|
| {filename} | {type} | {missing_items} |

请补充上述文档后重新执行。

如果判定为 CONDITIONAL，记录 WARN 项并在后续 SUMMARY.md 中呈现。

如果 --validate-only，到此停止，输出校验结果。

1.6 文档状态检查

在 Gate 校验之前，先检查每个输入文档的状态：

状态识别规则（按优先级）：

1. 文档 frontmatter 中的 status 字段：status: approved
2. 文档头部的状态标记：**Status**: approved 或 **状态**: 已批准
3. 文件名中的状态后缀：PRD-M01.approved.md
4. 以上均无 → 默认视为 draft，BLOCK

如果文档状态检查失败，输出格式：

## 输入校验失败 — BLOCK（文档状态）

以下文档状态不符合要求，无法进入实施转化：

| 文档 | 当前状态 | 需要状态 |
|------|---------|---------|
| {filename} | {current_status} | approved 或 frozen |

请将文档通过评审后重新执行。

Phase 2: 内容整合

执行步骤：

1. 从 PRD 中识别 Feature（按用户故事前缀 / Milestone 编号 / 文件名）
2. 对每个 Feature，从各类型文档中提取相关信息（§2.1 映射表）
3. 从 PRD 中提取 Out of Scope 列表（§2.2）
4. 为每个 Feature 生成 feature-context.md（模板见 templates/feature-context.md）

2.1 按 Feature 聚合

从已识别的文档中，按 Feature（功能特性）聚合跨文档信息。Feature 的识别规则：

1. PRD 中的用户故事编号前缀（如 US-M01-* → Feature M01）
2. PRD 中的 Milestone 编号
3. 文件名中的 Feature ID（如 PRD-M01-*.md → M01）

对每个 Feature，从各类型文档中提取相关信息：

2.2 Out of Scope 标注

从 PRD 中提取 Out of Scope 列表（BD-4），明确标注哪些内容不纳入后续 Task 拆分。

2.3 输出 feature-context.md

为每个 Feature 生成 feature-context.md，格式见 templates/feature-context.md。

Phase 3: 任务拆分

执行步骤：

1. 对每个 Feature 的 feature-context.md，按§3.2 策略确定拆分方式
2. 按§3.1 五个条件逐个拆分 Task，确保每个 Task 满足最小可验收颗粒度
3. 为每个 Task 注入结构化上下文（§3.7），确保信息完整传递
4. 为每个 Task 定义依赖关系（§3.4），包括依赖类型（FS / FF / data-dependency）
5. 写入 task-list.json（§3.6 格式）
6. 运行 validate-dag.py 校验 DAG（§3.5）
7. 处理校验结果：CYCLE_DETECTED → SUMMARY.md 警告；WARNING → 记录但不阻塞
8. 执行依赖完整性校验（§3.8），输出 dependency-suggestions.json
9. 执行 AC-测试点映射校验（§3.9），确保 TESTSET 覆盖完整
10. 执行原型感知上下文注入（§3.10），为 UI 相关 Task 注入原型引用和对齐验收项

3.1 最小可验收颗粒度

每个 Task 必须满足以下全部条件：

3.2 拆分策略

3.3 不应拆分的情况

3.4 依赖关系定义

为每个 Task 定义依赖关系：

3.5 DAG 确定性校验

LLM 产出依赖关系后，写入 task-list.json，然后运行 validate-dag.py：

python zdoc-i2i/validate-dag.py {output_dir}/impl-{feature}-{id}/task-list.json

脚本输出 dag-validation.json：

• PASS — 无环，拓扑排序成功
• CYCLE_DETECTED — 含循环依赖，输出环路路径
• WARNING — 含孤立节点（无依赖也无被依赖的 Task）

如果 CYCLE_DETECTED：在 SUMMARY.md 中输出警告，不自动修改依赖关系。 如果 WARNING：记录但不阻塞。

3.6 输出 task-list.json

Phase 3 产出 task-list.json，作为 Phase 4 文档生成的数据源（Phase 3→4 桥接文件）。Phase 4 读取此文件生成所有 Task impl 文档、INDEX.md 和 SUMMARY.md。

{
  "feature_id": "M01",
  "feature_name": "用户注册",
  "generated_at": "2026-05-28T10:00:00",
  "tasks": [
    {
      "id": "task-001",
      "slug": "data-model",
      "name": "数据模型定义",
      "priority": "P0",
      "estimated_hours": 4,
      "dependencies": [],
      "dependency_type": {},
      "acceptance_criteria": ["AC-001: Given ..., When ..., Then ..."],
      "source_docs": ["PRD-M01 §3.1", "ARCH-M01 §4.2"],
      "exception": null,
      "acceptance_gates": ["§11 门槛 1"],
      "source_constraints": ["§4.2", "§5.1"],
      "exclusions": [],
      "api_versions": [],
      "semantic_overlaps": []
    },
    {
      "id": "task-002",
      "slug": "api-endpoint-post-register",
      "name": "注册接口实现",
      "priority": "P0",
      "estimated_hours": 6,
      "dependencies": ["task-001"],
      "dependency_type": {
        "task-001": "FS"
      },
      "acceptance_criteria": ["AC-002: Given 已有数据模型, When 调用 POST /register, Then 返回 201"],
      "source_docs": ["API-M01 §2.1", "PRD-M01 §3.2"],
      "exception": null,
      "acceptance_gates": ["§11 门槛 2"],
      "source_constraints": ["§4.2"],
      "exclusions": [],
      "api_versions": [
        {
          "library": "ai",
          "version": "^4.1.54",
          "deprecated_apis": ["StreamingTextResponse"],
          "compatible_apis": ["toDataStreamResponse()"]
        }
      ],
      "semantic_overlaps": []
    }
  ]
}

字段说明：

3.7 Task 上下文注入模板

为每个 Task 定义强制注入的上下文字段，确保信息完整传递：

task_context:
  # 必填：该 task 涉及的所有 §11 门槛编号
  acceptance_gates: ["§11 门槛 N", ...]

  # 必填：该 task 涉及的所有 §4/§5/§6/§7/§8 具体约束编号
  source_constraints: ["§X.Y", ...]

  # 必填：该 task 的排除项与例外声明
  exclusions:
    - description: "..."
      exception_approved_by: "§11 门槛 N 或 §X.Y 显式批准"

  # 选填：与该 task 存在语义重叠的其他 task
  semantic_overlaps: ["task-NNN", ...]

  # 选填：UI 相关 task 关联的原型引用（§3.10 原型感知上下文注入）
  prototype_refs:
    - file: "ux-prototypes/proto-m12-onboarding.html"
      phase_id: "PHASE-B"
      phase_description: "5题身份建档表单"
      alignment_ac: "实现必须对齐 proto-m12-onboarding.html PHASE-B 的布局、文案、状态和交互，并提供截图或 Playwright 核对证据"

  # 选填：该 task 依赖的外部 API 版本信息
  api_versions:
    - library: "ai"
      version: "^4.1.54"
      deprecated_apis: ["StreamingTextResponse"]
      compatible_apis: ["toDataStreamResponse()", "pipeDataStreamToResponse()"]

3.8 依赖完整性校验

DAG 校验通过后，执行依赖完整性检查：

输出：dependency-suggestions.json，由人工确认后合并到 task-list.json。

{
  "suggestions": [
    {
      "task_id": "task-014",
      "suggested_dependency": "task-001",
      "reason": "task-014 创建文件，需依赖目录结构",
      "rule": "directory_structure_dependency"
    }
  ],
  "existing_table_checks": [
    {
      "task_id": "task-005",
      "table": "runner_risk_profiles",
      "referenced_as": "existing table",
      "found_in_migrations": false,
      "status": "FAIL",
      "suggestion": "该表在当前 codebase 的 migration 文件中不存在。建议：(a) 在 TASK-001 中增加 CREATE TABLE runner_risk_profiles，或 (b) 标注依赖的前置 migration 版本号"
    }
  ]
}

3.9 AC-测试点映射校验

拆解后检查 TESTSET 覆盖完整性：

TESTSET 中的每个测试点（HP-01~07, BC-01~12, ARC-01~04, ...）
  → 是否至少被一个 task 的 AC 覆盖？→ 未覆盖标记为 ORPHAN
  → 是否有 task 的 AC 覆盖了 TESTSET 之外的内容？→ 标记为 EXTRA

作用：

• 检测测试范围模糊：如果 PERF-04/05 未被任何 task 显式排除或覆盖，标记为 GAP
• 检测测试点遗漏：如果 TESTSET 中有测试点未被任何 task 的 AC 引用，标记为 ORPHAN

3.10 原型感知上下文注入

问题：当前 Task 拆分中，UI 相关 Task 仅通过 UX Spec 间接引用原型，实施者无法直接找到对应的原型文件和具体阶段。实际项目中（如 Task-011 onboarding-form-ui），原型包含表单布局、错误文案、loading 状态、sticky 按钮等可对照实现的细节，但这些信息在 Task 文档中丢失。

执行步骤：

1. 从 Phase 0 的 source-consistency-report.json 读取 prototype_index
2. 对每个 Task，判断是否涉及 UI 实现（拆分策略为"页面"或涉及 T06 UX Spec / T07 UX Prototype）
3. 若涉及 UI 且存在对应原型： a. 根据 Task 的验收标准和 UX Spec 章节引用，匹配原型中的对应 Phase b. 将原型文件路径 + 阶段信息注入 Task 上下文 c. 在 Task 的验收标准中自动追加一条原型对齐验收项：

   实现必须对齐 {prototype_file} 中 {phase_id} 的布局、文案、状态和交互，
   并提供截图或 Playwright 核对证据
   

   d. 在 Task 文档的"关联文档"表格中增加原型引用行
4. 若涉及 UI 但无原型 → 不追加原型对齐验收项，但记录 WARNING

原型匹配规则：

注入后的 task-list.json 扩展字段：

{
  "prototype_refs": [
    {
      "file": "ux-prototypes/proto-m12-onboarding.html",
      "phase_id": "PHASE-B",
      "phase_description": "5题身份建档表单",
      "alignment_ac": "实现必须对齐 proto-m12-onboarding.html PHASE-B 的布局、文案、状态和交互，并提供截图或 Playwright 核对证据"
    }
  ]
}

Phase 4: 文档生成

执行步骤：

1. 创建输出目录结构（§4.1）
2. 读取 templates/ 下对应模板，按模板格式逐个生成文件
3. 应用路径规范化：从 source-consistency-report.json 读取 path_normalization 结果，将所有 Task 文档中的文件路径替换为规范化后的完整路径
4. ENUM 生成校验（§4.8）：以 PRD 定义为准生成 ENUM，校验 TECH/ARCH 差异
5. 为每个 Task 生成 task-{nnn}-{slug}.md（模板见 templates/task.md）
6. 生成 INDEX.md（模板见 templates/index.md）
7. 多 Feature 时生成 IMPL-INDEX.md（模板见 templates/impl-index.md）
8. 生成 SUMMARY.md（模板见 templates/summary.md），统计数字必须从 task-list.json 动态计算
9. 执行产物完整性检查（§4.7）
10. 执行交付前自动审核（§5.1）
11. 生成交付报告 delivery-report.json（§5.3）

4.1 目录结构

{output_dir}/
├── IMPL-INDEX.md                         # 全局索引（多 Feature 时）
├── impl-{feature}-{PRD-ID}/
│   ├── SUMMARY.md                        # 汇总报告
│   ├── INDEX.md                          # Feature 索引
│   ├── IMPL-{PRD-ID}-{feature-slug}.md   # Feature 聚合上下文
│   ├── IMPL-TASK-001-{slug}.md           # Task 实施文档
│   ├── IMPL-TASK-002-{slug}.md
│   └── ...
└── ...

4.2 命名规则

遵循 DOC-WRITING-GUIDE §0.6 命名规范：

4.3 输出文档结构规范（DOC-WRITING-GUIDE 对齐）

所有生成的产物文档必须遵循 DOC-WRITING-GUIDE 的结构规范（详见 ADR-004 §4.0）。

Frontmatter 必填字段：

---
title: "{中文标题}"
status: draft
created: "{YYYY-MM-DD}"
updated: "{YYYY-MM-DD}"
layer: "L3 实现层"
priority: "{P0/P1/P2}"
related_docs: []
relationships:
  depends_on: []
  implements: []
  constrains: []
  references: []
  supersedes: []
  superseded_by: []
context_policy:
  load_priority: recommended
  task_scopes: []
  max_tokens_hint: 3000
---

标准章节：

交叉引用格式：

[PRD-M01-Onboarding](../prds/PRD-M01-Onboarding.md)
[Section 3.4 最小可验收颗粒度](#34-最小可验收颗粒度定义)

中英文规则：文件名英文 kebab-case，frontmatter title 中文，章节标题中文为主，技术术语保留英文。

4.4 版本戳

所有生成的文件必须包含以下元数据头部：

<!-- Generated by zdoc-i2i v1.6 | {YYYY-MM-DDTHH:MM:SS} | source-hash: {md5 of input doc paths} -->

4.5 文件模板

SUMMARY.md

读取 templates/summary.md 模板，按模板格式填充。包含：

• 输入文档校验结果（含 CONDITIONAL 的 WARN 项）
• Feature → Task 映射
• Out of Scope 汇总
• 关键决策记录
• 风险与注意事项
• DAG 校验结果
• 依赖完整性校验结果
• AC-测试点覆盖率
• 源文档交叉一致性结果
• 文档状态变更日志
• 验收/检查点

INDEX.md

读取 templates/index.md 模板，按模板格式填充。包含：

• Task 清单（ID + 名称 + 状态 + 优先级 + 工时 + 依赖）
• 依赖关系图（Mermaid + 表格，表格为权威源）
• 执行顺序（拓扑排序分层）
• 关键路径

IMPL-INDEX.md（多 Feature 时）

读取 templates/impl-index.md 模板。包含：

• Feature 清单 + 统计
• 跨 Feature 依赖关系
• 全局 DAG + 全局执行顺序

IMPL-{PRD-ID}-{feature-slug}.md（Feature 聚合上下文）

读取 templates/feature-context.md 模板。包含：

• YAML frontmatter（title/status/layer/priority/related_docs/relationships/context_policy）
• 文档定位、关联文档、范围边界
• 功能概述、用户故事、验收标准
• 业务规则、技术约束、API 契约
• 交互流程、领域模型、数据流
• 测试要点、Out of Scope
• 验收/检查点

IMPL-TASK-{nnn}-{slug}.md（Task 实施文档）

读取 templates/task.md 模板，按模板格式填充。每个 Task 的 impl 文档必须包含：

• YAML frontmatter（title/status/layer/priority/module_id/related_docs/relationships/context_policy）
• 文档定位、关联文档、范围边界
• Task 元数据（Feature、优先级、工时、依赖、产出物、例外理由）
• 验收标准
• 溯源链（§11 门槛 → §X.Y 约束 → TESTSET 测试点）
• 完整上下文（业务规则、技术约束、API 契约、交互要求、领域模型、数据流、测试要点）
• 排除项（含例外来源标注）
• API 版本信息
• 实施指引（仅基于设计文档已明确信息）
• 验收/检查点

4.6 文档状态冻结

Phase 4 文档生成全部成功后，执行文档状态冻结：

1. 冻结条件：Phase 4 所有产物完整性检查通过
2. 冻结操作：对每个输入文档，将状态置为 frozen
   • 更新 frontmatter：status: frozen
   • 更新头部状态标记：**Status**: frozen 或 **状态**: 已锁定
   • 注意：文件名中的状态后缀不做更新，frontmatter 为权威源
3. 记录日志：在 SUMMARY.md 中记录状态变更

## 文档状态变更

| 文档 | 原状态 | 新状态 | 变更时间 |
|------|--------|--------|---------|
| PRD-M01.md | approved | frozen | {timestamp} |
| ARCH-M01.md | approved | frozen | {timestamp} |

4. 失败处理：如果 Phase 4 生成失败，不冻结文档，保持原有状态，允许修复后重跑

4.7 产物完整性检查

生成完成后，自动执行以下检查：

4.8 ENUM 生成校验

Phase 4 生成 Task 文档时，对所有 ENUM 类型字段执行以 PRD 为准的校验：

执行步骤：

1. 读取 source-consistency-report.json 中的 prd_tech_alignment.enum_checks
2. 对每个 FAIL 级别的 ENUM 差异： a. 以 PRD 定义的值集合为准生成 DDL/校验逻辑 b. 在 Task 文档的"完整上下文 > 技术约束"中标注：

   ⚠️ 注意：TECH/ARCH 文档中包含额外值 [X]，但 PRD 未定义。本 Task 以 PRD 为准，仅使用 [PRD 定义的值]。如需扩展，请先更新 PRD。

3. 在 delivery-report.json 中记录 ENUM 校验结果

ENUM 追溯标注格式（在 Task 文档"技术约束"章节中）：

#### 枚举值定义（以 PRD 为准）

| 字段 | PRD 定义值 | TECH/ARCH 值 | 本 Task 使用 |
|------|-----------|-------------|-------------|
| gender | male, female | male, female, other | male, female（以 PRD 为准） |

Phase 5: 交付前审核 + 交付报告

执行步骤：

1. 执行交付前自动审核清单（§5.1）
2. 执行语义偏移检测（§5.2）
3. 生成 delivery-report.json（§5.3）

5.1 交付前自动审核清单

5.2 语义偏移检测

对每个 task 的关键 AC 执行语义对比：

源文档原文 ↔ task AC 表述
  → 检查是否存在语义偏移（如将"验证后删除"简化为"删除"）
  → 若检测到偏移，标记为 SEMANTIC_DRIFT
  → 输出差异说明

5.3 交付报告

I2I Pipeline 在交付时附带 delivery-report.json：

{
  "feature_id": "ARCH-LITE-XXX",
  "generated_at": "...",
  "i2i_version": "v1.6",
  "source_consistency": {
    "status": "PASS | FAIL",
    "issues": []
  },
  "dependency_validation": {
    "status": "PASS | WARN",
    "suggestions": []
  },
  "ac_coverage": {
    "total_test_points": 40,
    "covered_by_tasks": 38,
    "orphan_test_points": ["PERF-04", "PERF-05"],
    "coverage_rate": "95%"
  },
  "semantic_drift": {
    "total_acs": 64,
    "flagged": 2,
    "details": []
  },
  "pre_delivery_checks": {
    "passed": 8,
    "failed": 0,
    "warnings": 1
  }
}

重跑语义

Non-Negotiable Rules

1. 只整合不补充：不发明设计文档中没有的功能、技术方案或业务规则
2. 缺失即停止：BLOCK 时返回缺失清单并停止，不猜测或填补
3. 上下文自包含：每个 Task impl 文档必须包含该 Task 需要的全部上下文
4. 依赖关系显式化：不允许隐式依赖
5. DAG 确定性校验：环检测由 validate-dag.py 执行，不依赖 LLM
6. Out of Scope 不纳入：设计文档明确排除的内容不生成 Task
7. 不修改源文档：只读取设计文档（状态冻结除外，见 §4.6）
8. 可追溯：每个 Task 信息可追溯到源设计文档的具体章节
9. 命名规范：严格遵循 §4.2 命名规则
10. 全局索引必出：多 Feature 时必须生成 IMPL-INDEX.md
11. 版本戳必加：所有生成文件必须包含 §4.4 版本戳
12. 工时例外记录：超过 8h 的 Task 必须记录例外理由
13. 文档状态准入：仅接受 approved / frozen 状态的输入文档，draft / reviewing 状态 BLOCK 并提示需先通过评审
14. 执行后冻结：成功生成全部 Task 文档后，将所有输入文档状态置为 frozen
15. DOC-WRITING-GUIDE 对齐：所有生成的产物文档必须包含 YAML frontmatter（§4.3）和标准章节（文档定位、关联文档、范围边界、验收/检查点），遵循 DOC-WRITING-GUIDE 的结构规范
16. 源文档交叉一致性：Phase 0 执行源文档交叉一致性校验，BLOCK 级冲突要求源文档澄清后重跑，不进入拆解
17. 依赖完整性：Phase 3 执行依赖完整性校验，自动检测缺失依赖并输出建议
18. 交付前审核：Phase 5 执行交付前自动审核清单，BLOCK 级问题不交付
19. 交付报告必出：每次执行必须生成 delivery-report.json，记录校验覆盖率和质量指标
20. 文件路径完整性：Task 文档中所有文件路径必须使用项目根目录相对的完整路径，禁止使用简写路径（如 src/）。如指定了 --src 参数，Phase 0 规范化所有路径后传递到 Phase 4
21. 原型引用显式化：UI 相关 Task 的验收标准必须包含原型对齐验收项（当存在对应原型时），原型文件路径和阶段信息必须直接写入 Task 文档的"关联文档"表格和 task-list.json 的 prototype_refs 字段，禁止仅通过 UX Spec 间接引用

术语定义

Pitfalls / 常见坑与规避

Usage

# 全量目录扫描（推荐）
# 输出: docs/mvp-lite/impl/ 目录 + delivery-report.json
zdoc-i2i --dir docs/mvp-lite/

# 指定 Feature
# 输出: docs/mvp-lite/impl/impl-user-registration-M01/ 目录 + delivery-report.json
zdoc-i2i --dir docs/mvp-lite/ --feature M01

# 最小输入
# 输出: docs/mvp-lite/impl/impl-user-registration-M01/ 目录（含 IMPL-TASK-001-*.md, INDEX.md, SUMMARY.md）
zdoc-i2i --prd docs/prds/PRD-M01.md --arch docs/arch/ARCH-M01.md

# 指定源代码根路径（确保文件路径使用项目根相对的完整路径）
# 输出: 所有 Task 文档中的路径自动规范化为 apps/ai-coach-skill/src/... 前缀
zdoc-i2i --dir docs/mvp-lite/ --src apps/ai-coach-skill/src

# 指定输出目录
# 输出: custom-impl/ 目录替代默认 docs/mvp-lite/impl/
zdoc-i2i --dir docs/mvp-lite/ --output-dir custom-impl

# 仅校验（不生成 Task）
# 输出: stdout 打印 PASS / CONDITIONAL / BLOCK 判定 + 缺失清单
zdoc-i2i --dir docs/mvp-lite/ --validate-only