taiyi-change — 变更提案

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

框架集成

本阶段使用以下框架：

框架	用途	何时加载
Harness	阶段门禁与推进（status → continue；legacy：npx taiyi complete）	全程
OMO	作为 workflow 入口，承接 /taiyi:new 命令	进入时
Superpowers	brainstorming — 可选，当需求不清晰时加载协助梳理	可选
OpenSpec	将 CHANGE.md 同步到 openspec/changes/<slug>/	可选（taiyi sync-openspec）

Spec-Kit 和 GStack 在本阶段不涉及。

前置门禁（Pre-flight）

0.1 架构级变更检测

命中任一 → 反问用户确认：

1. 改模块结构（新增/拆分/合并目录）
2. 动 ADR（架构决策记录）
3. 改公共契约（API 签名、CLI 参数、DB Schema）
4. 跨服务编排（涉及 2+ 独立服务）

0.2 Profile 判定

Profile	CHANGE.md 要求
full	完整：Motivation + In/Out Scope + Risks + Success Criteria
api/ui	同上，Out of scope ≥ 1 条
lite	可省略 Risks 段，其余照常
micro/spike	仅 Motivation + Success Criteria，Out of scope 可选
nano	可跳过本阶段（引擎自动通过）

0.3 前置检查清单

• slug 命名合理（小写+连字符，如 fix-login-timeout）
• 用户已确认变更目标（不是 AI 自己推断的需求）
• 不与其他活跃 change 的 Scope 重叠（taiyi list 确认）

---

步骤

工件契约

层	路径	职责
语义真源	change.json	Zod（src/schemas/change.ts）— Agent 优先编辑
生成视图	CHANGE.md	hbs（src/templates/change.hbs）— 人读 / PR
流程	本 Skill	门禁、写作纪律、下游衔接

工作流：编辑 json → scripts/taiyi-forge.sh render <slug> change → status --json --compact → 用户确认 → continue --approver "名"。

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

json 字段（Zod 摘要）

字段	要求
title	描述性标题
motivation	谁痛、现状代价、改善指标（具体，不笼统）
scope.includes	In scope 条目
scope.excludes	≥1 条 Out of scope；关联 change 写 slug
success_criteria	≥1 条；id + description；每条可映射到测试
risks	full/api 推荐：risk / probability / impact / mitigation
impact_map	可选；模块影响面声明
evidence	success_criteria[].is_checked=true 时必填真跑命令

1. 编辑 change.json

/taiyi:new 已 seed change.json + CHANGE.md。

Motivation 好/坏例子（写入 motivation）：

好：当前翻译需人工复制粘贴到 DeepL，每次约 10 分钟。集成 API 后翻译可在 5 秒内完成，消除手动步骤。

坏：需要改进翻译功能。

Success Criteria（写入 success_criteria[]）：

• 每条可验证：curl / npm test / UI 操作步骤
• 不是「代码写好了」这类不可测试描述

要求：

• Motivation 说清「谁痛、现状代价、改善指标」，不笼统
• Out of Scope ≥ 1 条，标注关联 change slug（如有）
• Success Criteria 每条可直接映射到测试
• 影响面声明：是否需改 REQUIREMENT / 触及架构（impact_map 或 motivation 中说明）
• 不要写实现细节；不要推断用户未确认的范围

2. 渲染 CHANGE.md

scripts/taiyi-forge.sh render <slug> change

Zod 校验通过后从 json 重生成 md（去掉 seed 标记）。continue 前若 json 已改且 md 仍是 seed/快照态，引擎也会自动 sync。人只改 md 时引擎可 reverse-sync 拉回 json；显式 render 会覆盖 md。

3. 过关（Harness）

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

Legacy：npx taiyi complete <slug> change --approver "名" 仍可用；聊天优先 /taiyi:continue。

产出

• .taiyi/changes/<slug>/CHANGE.md
• .taiyi/changes/<slug>/change.json

与下游衔接

下游	需要
taiyi-requirement	Motivation + Scope → User Stories 边界；Success Criteria → AC Traceability；Out of scope → 不写 US 的范围
taiyi-design	影响面声明 → 架构决策范围；Success Criteria → 验证标准

异常处理

场景	处理
continue 被拒（非零退出）	读错误输出 → 缺少人工审批还是工件不完整。缺少审批 → 提示提供 --approver。工件不完整 → 补全后重试 status 再 continue。最多 1 次自动重试
CHANGE 与已有 change 范围重叠	在 Scope 中标注关联 slug，与用户确认是否需要合并或拆分
用户对 CHANGE 内容有争议	停止写入，等用户修改指示。不要自行协商修改范围
Profile 判定 skip 但门禁拦截	确认 profile → 如是 nano 说明可跳过的理由，人工放行
误过关后续阶段	change 为基石不可 undo；用 scripts/taiyi-forge.sh undo <slug> requirement（或更后阶段 id）回滚；仅需改 CHANGE 时直接编辑工件后 status

<fatal_constraints>

• NEVER skip CHANGE and proceed to REQUIREMENT.
• NEVER write implementation details in CHANGE.md.
• NEVER write Success Criteria that cannot be mapped to tests.
• NEVER infer scope from conversation — scope must be written in change.json.
• NEVER fabricate Motivation or pain points not grounded in user's description.
• NEVER merge multiple unrelated changes into one slug. </fatal_constraints>

质量自检

• 前置门禁三项全部通过（0.1–0.3）
• Motivation 说清了"谁痛、现状代价、改善指标"
• Out of scope ≥ 1 条
• In/Out 格式清晰（### 子节或 - In: 风格）
• Success Criteria 每条可映射到测试
• Risks 已记录（full/api profile）或说明"无显著风险"
• 架构级变更已检测（0.1）且结果已记录
• 影响面声明已写入

引擎门控（自动，无需手动确认）

• WIP 限制: 活跃种子 ≥ TAIYI_MAX_SEEDS(默认10) → 阻止创建。--force 或 TAIYI_SEED_LIMIT=0 跳过
• 复杂度重评估: change 过关时按已填 CHANGE.md 重算复杂度（不再总是 "low"）
• SC 可量化: 所有 SC 均无数字/%/状态码 → agent 日志 warn（不阻止，人审兜底）