Rune-Spec/openspec/changes/configurable-pipeline/design.md

Context

Rune 当前把 5 个固定阶段（discuss→plan→task→build→archive）硬编码在 6 处源码里：

• types.ts：STAGES 字面量联合 + 5 个 Stage 接口
• cli.ts：5 个 cli.command() 硬编码
• assembler.ts：5 个 assembleXxxPrompt 专用函数
• scanner.ts：planCompleted/buildUnlocked 等固定语义
• defaults/config.ts：5 个固定 prompt
• adapters/：for (stage of STAGES) 注入

当前状态全从文件系统派生（plan done = 声明文档全存在；build done = task.md checkbox 全勾），无持久化状态文件。唯一不可逆操作 finish（移动目录到 archive/）不校验前置阶段——这是最大漏洞。

Goals / Non-Goals

Goals:

• 用通用 StageConfig 结构替换所有固定阶段渗透，实现"改配置即改流程"
• 建立"文档落地 + 可选 validate"两档完成判定，作为阶段推进的唯一依据
• 修复 finish 门禁：所有阶段实质完成才允许归档
• 保持 discuss 和 archive 作为固定端点，中间 pipeline 完全可配置
• 零特例：一个 stage = 一个文档，一条规则通吃所有阶段

Non-Goals:

• 多流水线 / 分支 / 条件跳过（0.2.0 不做，但数据结构不阻碍未来扩展）
• 回退命令（rune back / rune reset）——用户手动删文档解决
• 向前兼容旧配置格式（BREAKING，init 重新生成）
• validate 沙箱——config 是可信内容，类比 package.json scripts

Decisions

D1: 三明治结构（discuss + pipeline + archive）

选择：discuss 固定在 pipeline 之前（无门禁、不产文档）；archive 固定在 pipeline 之后（终端收尾、移动目录）；中间 pipeline 完全可配置。

理由：discuss 本质是自由探索（无可强制产出），archive 本质是目录移动（语义通用）。把两端固定、中间放开，在"需要灵活性的地方给灵活性，需要锚点的地方给锚点"。

备选（否决）：让 discuss/archive 也可配置。discuss 没有有意义的门禁（自由探索），archive 的移动语义是通用的，配置化无收益反而增复杂度。

D2: 每个 stage 产出且仅产出一个 <id>.md

选择：统一规则——每个 pipeline 阶段产出一个文档，文件名由 stage id 派生（plan → plan.md）。多文档需求拆成多个 stage。

理由：消除旧 plan 阶段的"一个 stage 多个文档 + 文档间 depend"特例。一条规则、一条代码路径、一个 done 检查。

备选（否决）：outputs: [...] 数组允许一阶段多文档。重新引入部分完成、文档间依赖等复杂度，违背"统一"初衷。

D3: 两档完成判定（baseline done + substantive done）

选择：

• baseline done = <id>.md 存在（即使空文档）。CLI 永远检查，不可关闭。
• substantive done = validate 函数返回 truthy（若配置了 validate）。未配置 validate 则 baseline 即 substantive。
• stage fully done = baseline && substantive。

理由：文档存在是廉价、不可否认的"执行过"证据，挡"完全跳过"。validate 挡"做得很差"（例如 checkbox 瞎勾、测试没过）。分档让简单阶段零配置工作，复杂阶段获得实质验证（bun test && bun run lint）。

备选（否决）：单档（只有 validate）。文档存在本身就有意义（执行证明），即使没配 validate 也该强制。

D4: validate 签名 (changeDir: string) => boolean | Promise<boolean>

选择：validate 是可选的 JS 函数字符串，签名 (changeDir: string) => boolean | Promise<boolean>。返回 truthy = 通过；falsy = 失败；throw = 失败并显示 message 给用户。

理由：changeDir 是读取阶段产出和项目文件的最小上下文。0.2.0 从最小签名开始，后续版本再扩展。Async 支持因为文件读取和命令执行都需要。

备选（否决）：

• 对象参数 { changeDir, projectRoot, stage, ... }：预留扩展，但 0.2.0 不需要。用 positional string 最简，后续要扩展时换对象参数（大版本变更可接受）。
• 独立 .js 文件引用（validate: ./validate-build.js）：config 不自包含，增加文件管理负担。后续可加此形式作为增强。

D5: validate 执行模型——AsyncFunction 动态构造

选择：CLI 读取 validate 字符串，用 new AsyncFunction('changeDir', body) 构造异步函数，传入 changeDir 执行。Bun 原生支持，Bun.file / Bun.write / fetch 等全局 API 在函数内可用。

async function runValidate(body: string, changeDir: string): Promise<ValidateResult> {
  const fn = new AsyncFunction("changeDir", body);
  try {
    const result = await fn(changeDir);
    return { passed: !!result, reason: null };
  } catch (e) {
    return { passed: false, reason: e instanceof Error ? e.message : String(e) };
  }
}

理由：config 是项目可信内容（和 package.json scripts 同信任级），不需要 VM 沙箱。AsyncFunction 让 await 直接在函数体里用，validate 脚本可写 const c = await Bun.file(...).text(); return /pattern/.test(c);。

备选（否决）：vm.runInNewContext 沙箱。增加复杂度无安全收益——开发工具的 config 本身就有完整执行权（package.json scripts 证明了这个模型可行）。

D6: 动态 CLI 命令注册

选择：CLI 启动时读取配置，为每个 pipeline stage 注册 rune <stage-id> <change> 命令。discuss、finish、status 为固定命令。

理由：直接替换硬编码命令。显式 stage 名比 rune next 更可审计，也允许用户直接获取特定阶段的提示词。

备选（否决）：单一 rune next 命令自动推进。不可审计、不灵活（用户无法直接获取特定阶段提示词）。

D7: 门禁分级——软门禁 + 硬门禁

选择：

• 软门禁（stage 命令）：rune <stage> <change> 检查前置阶段全 fully-done 才输出提示词。未通过则报错并指引。软——因为提示词只是文本，无法物理阻止 agent 工作。
• 硬门禁（finish）：rune finish 检查所有阶段 fully-done 才执行目录移动。未通过则拒绝。

理由：rune 无运行时守护进程，agent 有文件写权限。唯一真正不可逆的杠杆是 finish（目录移动）。软门禁提供清晰反馈和引导，硬门禁是最终执行点。

D8: 默认 pipeline = [requirements, design, plan, task, build]

选择：5 个线性阶段，把旧 plan 阶段的 3 个文档拆成 3 个独立 stage。每个产出一个 .md。

理由：语义清晰，每个阶段一个审计点。和旧实现一一对应，老用户变更内容可直接迁移。遵循"一个 stage 一个文档"统一规则。

备选（否决）：[plan, task, build]（3 个，plan 单文档）。丢失 requirements/design 独立审计点。

D9: 数据模型

interface StageConfig {
  id: string; // [a-z][a-z-]*，CLI 命令名 + 文件名 stem
  prompt: string; // 阶段提示词
  validate?: string; // 可选 JS 函数体
}

interface PipelineConfig {
  stages: StageConfig[]; // 有序线性数组
}

interface StageStatus {
  config: StageConfig;
  docExists: boolean;
  validated: boolean; // 无 validate 配置时恒为 true
  done: boolean; // docExists && validated
}

interface ChangeStatus {
  changeDir: string;
  stages: StageStatus[];
  currentIndex: number; // 第一个未 done 的阶段索引
  allDone: boolean;
}

所有 Status 从文件系统 + 配置派生，不持久化。

D10: 配置 schema 校验

加载配置时校验：

• stage id 唯一（不可重复）
• stage id 字符集：/^[a-z][a-z-]*$/
• stage id 不可为保留字（discuss、finish、status、archive）
• pipeline 至少 1 个 stage
• validate（若有）是合法可执行的 JS 字符串（new AsyncFunction 构造不抛异常）

Risks / Trade-offs

• [validate 脚本有完整执行权] → 文档明确警告 config 是可信内容（类比 package.json scripts），不盲目复制陌生项目 config。
• [空文档可骗过 baseline done] → 有意设计。"optional stage" = 手动建空 <id>.md，gate 自然通过。validate 挡实质内容。
• [配置 BREAKING，老用户 config 不兼容] → rune init 重新生成默认配置 + README 迁移指引。
• [validate 签名只有 changeDir，后续扩展是 breaking] → 0.2.0 大版本，可接受。或从 day-1 用对象包装（{ changeDir }）预留——倾向后者，零成本。
• [scanner 逻辑变复杂（从固定语义到配置驱动）] → 充分测试覆盖：空目录、部分完成、全完成、validate 失败等场景。