taiyi-task

name	taiyi-task
description	TaiyiForge 第5阶段 — 任务拆解，TASK.md。四端通用。
paradigm	Partner

taiyi-task — 任务拆解

进入本阶段前请优先读 .taiyi/changes/<slug>/PHASE-CONTEXT.md（~500 tokens），不要全量加载上游工件。

框架集成

本阶段使用以下框架：

框架	用途	何时加载
Harness	阶段门禁与推进（status → continue；legacy：npx taiyi complete）	全程
OMO	任务切片遵循 OMO 垂直切片规范	T1 任务拆解步骤

Superpowers / GStack / OpenSpec / Spec-Kit 在本阶段不涉及。

前置门禁（Pre-flight）

0.1 上游确认

• ui-design 已过关（如有 UI 层；skippedPhases 含 ui-design 时可跳过）；design 已过关

0.2 Profile 判定

Profile	TASK.md 要求
full	完整：T0X 逐层检查 + 入口预设 + 任务拆解 + 估算 + Scope Break + 全局 Resources
api/ui	同 full
lite	简化版：可跳过 T0X 和 Scope Break
micro/spike	可跳过本阶段
nano	跳过

0.3 前置检查清单

• 上游阶段已过关（DESIGN；需 UI 时含 ui-design，以 engineTruth.skippedPhases 为准）
• 理解 DESIGN.md 中两个方案的取舍理由

---

步骤

工件契约

层	路径	职责
语义真源	task.json	Zod（src/schemas/task.ts）
生成视图	TASK.md	hbs（src/templates/task.hbs）
流程	本 Skill	T0.x 检查、切片、write_files 边界

工作流：编辑 json → scripts/taiyi-forge.sh render <slug> task → status → continue。

详见 docs/taiyi/artifact-contract.md。

json 字段（Zod 摘要）

字段	要求
title	任务拆解标题
slices	≥1 切片；id / description / write_files / dependencies / test_command
waves	可选；执行波次与 slice 分组
slice_risks / slice_rollbacks	可选；风险与回滚
scores / completeness_score	可选；自评 0–10
evolutionSuggestions	可选；架构沉淀

切片字段对齐下文 T1 主任务拆解 六要素（Level → time_estimate、Verify → test_command / verification）。

写作指引（填入 json，render 生成 TASK.md）

入口预设（写在 TASK.md 顶部）

# TASK: <slug 描述性标题>

## Engineer Context
- 本 change 在 TaiyiForge 第 5 阶段（task）
- UI-DESIGN.md 与 DESIGN.md 确认了方案
- 你只能从 TASK 任务池中挑选，**不实现未列出的功能**
- **不修改**非 write_files 清单中列出的文件

T0X 逐层检查（T0.1 - T0.7）

每层检查结果为 ⛔（阻止）/ ⚠️（需更新）/ ✅（通过）：

### T0.1 技术栈决策确认
- [ ] 语言版本（TS 5.x / Python 3.12+）
- [ ] 框架（Express / Next.js / Gin）
- [ ] 组件库（Shadcn / MUI / BYO）
- [ ] 测试框架（Vitest / Pytest / Jest）
- [ ] 样式方案（Tailwind / CSS Modules / CSS-in-JS）
- [ ] 所有项通过 ✅ → 继续

### T0.2 文件分析
前置：grep/glob 扫描项目文件结构。
- [ ] 新文件路径不与现有文件冲突
- [ ] 修改已知文件时已在项目中找到
- [ ] 无依赖遗漏（如缺少的 npm 包）

### T0.3 影响与兼容
- [ ] 没有改到公共 API 签名（如有需在 TASK 中声明）
- [ ] 没有引入破坏性 DB 迁移
- [ ] 改 schema 时同时有 up + down 迁移

### T0.4 测试兼容
- [ ] 知道已有测试的 runner 命令和配置文件路径
- [ ] 新增测试定位遵循项目模式（unit / integration / e2e）
- [ ] 已有测试不因本 change 而需要重构

### T0.5 设计兼容
- [ ] 新代码沿用 DESIGN.md 约束（如 Modest vs Bold 方案）
- [ ] 没引入 DESIGN 未讨论的新抽象/模式

### T0.6 UI 兼容（仅 UI 层 change）
- [ ] 色值/字体/间距引用 UI-DESIGN.md 或 project tokens
- [ ] 组件路径不与已有组织冲突

### T0.7 遗留决策记录

Notion	Decision	Alternate	Consequences	T0.X 检查

---

### T1. 主任务拆解

每个任务格式相同的 6 字段节：

T0X — 任务标题

Level: 0 / 1 / 2（0=底层抽象/配置，1=核心逻辑，2=集成封装） Estimate (confidence): 30min H / 2h M / 4h L

Description:

• 一句话描述

Why separate:

• 为什么要单独分拆

Write files:

• [new] src/foo/bar.ts
• [edit] src/foo/index.ts

Dependencies:

• T01 — 本任务在 T01 之后
• T02 — 本任务与 T02 可并行

Verify:

$ npx vitest run tests/unit/foo --reporter=verbose
...

**拆分原则**：
- 0 级任务（底层抽象/配置）放在前面，避免后续任务 blocked
- 可并行的任务标注 Dependencies 关系
- Verify 使用真实命令 + 预期关键输出

### T2. 全局资源

全局资源与偏差捕获

npm scripts

命令	用途
npm run dev	启动 dev server

模块路径别名

• @/ → src/
• @components/ → src/components/

### T3. Scope Break 检查

Scope Break (Pre-Flight)

• 所有 Write files 不超出 DESIGN 文件范围
• 没有引入 DESIGN 未讨论的新依赖
• 每个任务验证命令真实可用

---

## 过关（Harness）

1. 逐项检查 `## 质量自检`；有未通过项则不要过关。
2. 预检：`scripts/taiyi-forge.sh status <slug> --json --compact` — 解析 `engineTruth`（`qualityReady` / `blockers`）。
3. 用户确认后过关：`scripts/taiyi-forge.sh continue <slug>`。
4. 过关后再 `status --json --compact`，读 `engineTruth`；若 `currentPhase` 已变为 `dev`，切换到 taiyi-dev Skill 并通知用户。

Legacy：`npx taiyi complete <slug> task` 仍可用；聊天优先 `/taiyi:continue`。

## 产出

- `.taiyi/changes/<slug>/TASK.md`
- `.taiyi/changes/<slug>/task.json`

## 与下游衔接

| 下游 | 需要 |
|------|------|
| `taiyi-dev` | Write files → 实现边界；Verify 命令 → 通过标准；Dependencies → 执行顺序；T0.7 遗留决策 → 约束条件 |
| `taiyi-test` | Verify 命令 → 功能测试范围；Write files 清单 → 测试必须覆盖的文件 |

## 异常处理

| 场景 | 处理 |
|------|------|
| UI-DESIGN 未过关（需 UI 层时） | phase guard 拦截，退回完成 ui-design |
| T0.x 检查有 ⛔ 阻止项 | 不能过关 task 阶段，修复后重试 |
| 任务拆分粒度过粗 | 拆分原则：1 任务 = 1 个独立可验证的功能点，如果跨 3+ 文件或涉及 2+ 层（前端+后端），拆为多个任务 |
| DESIGN.md 两个方案的选择理由不明确 | 在 TASK 入口声明所选方案，备注另一个方案的 scope 延迟 |
| `continue` 被拒 | 检查 T0.x 是否全部 ✅、Scope Break 是否通过。修复后 status 再 continue |
| 误过关本阶段或后续 | `scripts/taiyi-forge.sh undo <slug> task` |

<fatal_constraints>
- NEVER add features not traceable to DESIGN.md or REQUIREMENT.md.
- NEVER skip T0.x checks (they catch most downstream rework).
- NEVER write tasks that cross 2+ layers — each task must be a vertical slice.
- NEVER write Verify commands that are placeholders — every command must run in the actual project.
- NEVER skip Dependencies field — all tasks require explicit dependency declaration.
</fatal_constraints>

## 质量自检

- [ ] 前置门禁已通过（0.1–0.3）
- [ ] 入口预设已写（Engineer Context）
- [ ] T0.1–T0.7 逐层检查全部 ✅
- [ ] 每个任务有 Level / Estimate / Why separate / Write files / Dependencies / Verify
- [ ] 每个 FR（caller_module 在本 scope 内的）至少 1 个切片覆盖（covers_frs 字段）
- [ ] Verify 命令可实际运行（非占位符）
- [ ] Scope Break 已通过
- [ ] Write files 不超出 DESIGN 范围
- [ ] 所有依赖在 package.json 中或标注为外部