Tapd Iteration Runner

TAPD 迭代调度器

1. 定位

本 skill 负责迭代级编排：建分支、拉需求、依赖排序、依次调度每个需求的 pipeline、迭代收尾。

runner 不知道的事：

• 需求内部的子 skill 步骤是什么
• speckit 命令长什么样
• context.md / req.md / spec.md 的格式
• subagent prompt 怎么渲染
• 单需求层面的重入怎么做

这些全部由 tapd-story-pipeline 承担。runner 在自己的主上下文中内联加载并执行 tapd-story-pipeline/SKILL.md，仅根据 meta.yaml 与 questions.md 做决策。

2. 基础配置

项目根目录下的 project.json 提供默认配置：

{
  "workspace_id": "对应的 TAPD 工作空间 ID",
  "owner": "开发者 ID"
}

取值优先级（适用于 workspace_id 和 owner）：

1. 用户在消息中显式指定 → 最高优先
2. project.json 中的配置 → 次优先
3. 通过 TAPD MCP 自动获取（仅 owner）→ 再次
4. 交互式询问用户 → 最低优先（兜底）

iteration_id 无默认值，必须由用户提供或通过交互获取。

3. runner → pipeline 参数传递

用户在发起迭代时可指定 agent 工具名称（如 agent / claude / cursor），存入 iteration-state.json.agent_tool。未指定时默认为 agent。

runner 内联执行 pipeline 时把 agent_tool 作为入参传入；pipeline 在自己的 meta.yaml 中 也写一份，作为后续单次调起的入参回退。（agent_tool 决定 pipeline 子 skill 用哪种 subagent 工具。）

workspace_id 同理：runner 在 loop 内联执行时把 iteration-state.json.workspace_id 作为入参传给 pipeline；pipeline 首次执行时把它落到 meta.yaml.workspace_id， 后续 pipeline 子 skill（如 commit 调 stories_update、req.md 兜底注入调 stories_get） 统一从 meta.yaml 取，避免依赖运行时入参或 project.json 兜底。

4. 子 Skill 编排

5. iteration-state.json

迭代级状态文件，保存在 specs/${VERSION}/iteration-state.json。

完整字段定义见 references/iteration-state-schema.md。

决策常用字段速查：

写入权限：

• runner 完全拥有 iteration-state.json，因为迭代级状态只有一个写者，避免 runner 与 pipeline 并发修改导致数据冲突
• stories.*.phase 和 stats 是 meta.yaml 的派生缓存——runner 在 loop 中从各需求的 meta.yaml 同步过来，用于在 iteration-state.json 单点呈现迭代级全局视图
• runner 不直接修改 pipeline 的 meta.yaml——pipeline 对自己的 meta.yaml 有完整的校验逻辑（state-mutation-guide.md §4），外部修改必须遵循 §7 速查表规则，确保 phase 与产物的对应关系始终合法

6. 状态流转

initialized → analyzed → implementing → completed → reported
                        └→ bugfix ──────┘

7. loop 调度逻辑

runner 主 SKILL 的核心。对 sequence 中每个 ID，用语义指令调度 pipeline。 runner 不修改 meta.yaml——所有状态变更由 pipeline 执行。

以下为逻辑伪代码（非可执行脚本），描述 runner 的语义调度循环：

for ID in sequence:
    iteration_state.selected_story = ID
    workdir = f"specs/{VERSION}/{ID}"

    # 记录壁钟开始时间（仅首次；持久化以便恢复后仍可计算耗时）
    if not iteration_state.stories[ID].started_at:
        iteration_state.stories[ID].started_at = now_iso8601()
        save_iteration_state()

    # 注入 req.md（首次）
    if not exists(f"{workdir}/req.md"):
        ensure_dir(workdir)
        if exists(f"specs/{VERSION}/.tmp/{ID}.md"):
            copy(f"specs/{VERSION}/.tmp/{ID}.md", f"{workdir}/req.md")
        else:
            desc = tapd_mcp.stories_get(workspace_id, id=ID).description
            write_file(f"{workdir}/req.md", desc)

    action = "execute"  # 首次用 execute

    while True:
        # 内联执行 pipeline（runner 不修改 meta.yaml）：
        # 按 action 与入参加载并执行 skills/tapd-story-pipeline/SKILL.md，
        # pipeline 在当前上下文中推进到下一个卡点后退出
        # （其子 skill specify/plan/... 各自拉 speckit subagent）。
        run_inline(skill="skills/tapd-story-pipeline/SKILL.md",
                   action=action, story_id=ID, workdir=workdir,
                   workspace_id=iteration_state.workspace_id,
                   agent_tool=iteration_state.agent_tool,
                   iter_branch=iteration_state.iter_branch)

        # pipeline 退出后读 meta.yaml（只读）判断结果
        meta = read_yaml(f"{workdir}/meta.yaml")

        if meta.phase == "committed":
            # 记录壁钟耗时 = committed 时刻 − started_at
            iteration_state.stories[ID].stats.duration_sec = \
                now_epoch() - parse_iso8601(iteration_state.stories[ID].started_at)
            sync_to_iteration_state(ID, phase="committed", stats=meta.stats)
            save_iteration_state()
            break

        # 根据卡点确定下一个 action（参见 state-mutation-guide.md §8）
        if meta.last_failure:
            if meta.last_failure.type == "system" and meta.attempts < 2:
                action = "retry"  # 自动重试，无需与用户对话
            else:
                user_input = chat_with_user(meta.last_failure)
                if user_input == "重试":
                    # 用户可能已修改 req.md / spec.md 等内容文件，并写好 attempt-md
                    action = "retry"
                else:
                    action = "abort"

        elif meta.pending_review:
            user_input = chat_with_user(meta.pending_review)
            if user_input == "通过":
                action = "approve"
            elif user_input == "回退":
                # 用户已写好 iteration-patches/attempt-${N}.md
                action = "reject"
            else:
                action = "abort"

        elif has_open_questions(f"{workdir}/questions.md"):
            user_answers = chat_with_user(read_open_questions(workdir))
            write_answers_to_questions_md(workdir, user_answers)
            action = "answer"

        else:
            # pipeline 退出异常
            notify_user(f"pipeline 退出异常，请检查 {workdir}/process.log")
            if chat_with_user("重试？") == "重试":
                action = "execute"
            else:
                break

关键原则：runner 只做三件事——

1. 读 meta.yaml（只读）判断卡点
2. 与用户对话
3. 写用户输入文件（questions.md 答复、attempt-md）并确定下一个 action

8. 与 pipeline 的通信契约

8.1 内联调用约定

runner 在 loop 中内联执行 pipeline，传入以下入参：

runner 按上述入参与 ACTION 加载并执行 skills/tapd-story-pipeline/SKILL.md。 pipeline 推进到下一个卡点后退出（输出其 §8.1 退出报告），控制权回到 loop。

ACTION 取值：execute / approve / reject / answer / retry / abort 各指令语义见 ../tapd-story-pipeline/references/state-mutation-guide.md §2。

8.2 退出后读取的文件

runner 只读以下文件（不写 meta.yaml）：

• ${WORKDIR}/meta.yaml — 只读，判断卡点类型
• ${WORKDIR}/questions.md — 只读判断 + 写答复（外部可写的内容文件）
• ${WORKDIR}/commit.md — 仅在 tapd-iteration-report 阶段批量读取

8.3 退出报告用途

pipeline 退出时输出的文字报告面向用户，runner 的决策不依赖退出报告——所有决策数据从 meta.yaml（只读）和 questions.md 读取。

8.4 契约版本

本契约基于 tapd-story-pipeline v1.1.0 语义指令模式 + runner v2.0.0 内联执行模式。runner 的 loop 逻辑与 state-mutation-guide.md §8 runner 速查表保持同步。

9. 恢复机制

当 tapd-iteration-init 检测到已有未完成的 iteration-state.json 时，按 references/recovery.md 流程恢复。恢复时：

1. 读 iteration-state.json
2. 对 sequence 中所有非 committed 需求，加载其 meta.yaml
3. 同步 meta.yaml.phase / meta.yaml.stats 到 iteration-state.json.stories.*.phase / stats （派生缓存的一次性回填）
4. 遗留的卡点（last_failure / pending_review / questions.md [open]）由 loop 在下一轮调度时自然处理

10. 迭代汇总触发

每次 pipeline 退出且推进了 phase 后，runner 检查所有需求 phase 是否全部为 committed：

• 是 → iteration-state.json.status = completed，加载 tapd-iteration-report/SKILL.md 执行汇总；汇总完成后 status = reported（终态）
• 否 → 继续 loop

11. 平台约定

${AGENT_TOOL} 从 iteration-state.json.agent_tool 字段读取。

12. 参考文件

13. Example: 3 需求迭代 Happy Path

用户输入："帮我开发 TAPD 迭代 #1001234 的需求，workspace_id 是 20000001"

阶段 1 — init：

• 读取 project.json 获取 workspace_id=20000001
• 调 TAPD MCP iterations_get → 迭代名称 iteration-v0.9.x
• 创建分支 v0.9.x，创建 specs/v0.9.x/，写入 iteration-state.json（status=initialized）

阶段 2 — analysis：

• 调 TAPD MCP stories_get → 3 个子需求 A、B、C
• A 无依赖，B 依赖 A（共享模块），C 依赖 B（接口依赖）
• sequence = [A, B, C]，status → analyzed

阶段 3 — loop：

需求 A：内联执行 pipeline → phase 推进到 committed → sync → 下一个
需求 B：内联执行 pipeline → phase=tasks-generated（confirm 卡点）
  → runner 展示 artifacts → 用户"通过" → phase=confirmed → 再次内联执行 → committed
需求 C：内联执行 pipeline → committed
全部 committed → status=completed

阶段 4 — report：

• 生成 changelog.md（v0.9.0）
• 生成 summary.md（效能统计）
• patch 自增 → 1
• git commit + push → status=reported（终态）