bf-lead-orchestrate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Lead Orchestrate (Sequence Pattern)

Lead Orchestrate（序列模式）

Overview

概述

BF 워크플로우의 자율 실행기이다. 모드 기반으로 동작하며, 사람과 직접 소통하지 않는다. 각 모드에서 완전 자율 실행 후 결과 파일과 함께 종료한다.

모드	입력	실행	출력
`plan`	tech-spec, conventions	bf-lead-plan 스폰 → Story 구조 생성	"done" + sprint-status.yaml + stories/
`epic`	epic-id, [modification.md]	implement → E2E → review	"done" + 결과 파일들

핵심 원칙: 사람과 절대 소통하지 않는다. 모든 판단은 자동 정책에 따르고, 결과는 파일에 기록된다. 사람과의 소통은 bf-execute(메인 세션)가 담당한다.

这是BF工作流的自主执行器。基于模式运行，不与人类直接交互。在每个模式下完全自主执行后，伴随结果文件一同终止。

模式	输入	执行	输出
`plan`	tech-spec, conventions	启动bf-lead-plan → 生成Story结构	"done" + sprint-status.yaml + stories/
`epic`	epic-id, [modification.md]	实现 → E2E测试 → 评审	"done" + 结果文件集

**核心原则：绝不与人类交互。**所有判断均遵循自动策略，结果记录在文件中。与人类的交互由bf-execute（主会话）负责。

When to Use

使用场景

```
bf-execute
```
가 스폰
직접 호출하지 않는다.

由
```
bf-execute
```
启动
不直接调用

Prerequisites

前置条件

승인된 Tech Spec:
```
docs/tech-specs/{TICKET}-tech-spec.md
```
```
docs/conventions.md
```
(있으면)

已批准的技术规格文档：
```
docs/tech-specs/{TICKET}-tech-spec.md
```
```
docs/conventions.md
```
（如有）

Error Handling

错误处理

bf-lead-plan 스폰 실패 (plan 모드):
```
"error: lead-plan spawn failed"
```
신호를 bf-execute에 전달 후 종료
bf-lead-implement 스폰 실패 (epic 모드):
```
"error: lead-implement spawn failed"
```
신호를 bf-execute에 전달 후 종료
E2E agent 스폰 실패:
```
e2e: escalated
```
기록, E3 리뷰로 진행
bf-lead-review 스폰 실패: 에픽 결과에 "review 미수행" 명시, bf-execute에
```
"done"
```
+ sprint-status.yaml 경로 전달
sprint-status.yaml 읽기/쓰기 실패: CLAUDE.md의 Read-yq-Verify Recover 절차를 따른다 (git checkout → 1회 재시도 → 실패 시
```
"error: sprint-status update failed"
```
보고)

plan模式下bf-lead-plan启动失败：向bf-execute发送
```
"error: lead-plan spawn failed"
```
信号后终止
epic模式下bf-lead-implement启动失败：向bf-execute发送
```
"error: lead-implement spawn failed"
```
信号后终止
E2E Agent启动失败：记录
```
e2e: escalated
```
，进入E3评审阶段
bf-lead-review启动失败：在史诗任务结果中注明“未执行评审”，向bf-execute发送
```
"done"
```
+ sprint-status.yaml路径
sprint-status.yaml读写失败：遵循CLAUDE.md中的Read-yq-Verify恢复流程（git checkout → 重试1次 → 失败则上报
```
"error: sprint-status update failed"
```
）

Instructions

操作说明

1. 초기 로딩

1. 初始加载

yq 전제조건 체크 (최초 1회):

bash

command -v yq >/dev/null 2>&1 || { echo "❌ yq not installed. Install: brew install yq"; exit 1; }

```
docs/tech-specs/{TICKET}-tech-spec.md
```
읽기
```
docs/sprint-status.yaml
```
읽기 (있으면)

yq前置条件检查（仅首次执行）：

bash

command -v yq >/dev/null 2>&1 || { echo "❌ yq not installed. Install: brew install yq"; exit 1; }

读取
```
docs/tech-specs/{TICKET}-tech-spec.md
```
读取
```
docs/sprint-status.yaml
```
（如有）

2. 모드 감지

2. 模式检测

스폰 시 전달받은 파라미터로 모드를 결정한다:

```
mode: "plan"
```
→ Plan 단계 실행
```
mode: "epic"
```
+
```
epic_id
```
+ (선택)
```
modification_path
```
→ Epic 단계 실행

根据启动时接收的参数确定模式：

```
mode: "plan"
```
→ 执行Plan阶段
```
mode: "epic"
```
+
```
epic_id
```
+（可选）
```
modification_path
```
→ 执行Epic阶段

Plan 모드

Plan模式

P1. bf-lead-plan 스폰

P1. 启动bf-lead-plan

```
bf-lead-plan
```
을 스폰한다 (
```
model: opus
```
).
전달: tech-spec 경로, conventions.md 경로 (bf-execute로부터 전달받은 경로를 그대로 전달, orchestrate 자체는 읽지 않음)
수신 대기:
```
"done"
```
+ stories/ 경로 + sprint-status.yaml 경로

启动
```
bf-lead-plan
```
（
```
model: opus
```
）。
传递参数：技术规格文档路径、conventions.md路径（直接传递从bf-execute接收的路径，orchestrate自身不读取）
等待接收：
```
"done"
```
+ stories/路径 + sprint-status.yaml路径

P2. 완료

P2. 完成

sprint-status.yaml을 읽어 에픽/스토리 구조를 확인한다.
bf-execute에 전달:
```
"done"
```
+ sprint-status.yaml 경로 + stories/ 경로
종료 (컨텍스트 소멸).

读取sprint-status.yaml，确认史诗/Story结构。
向bf-execute传递：
```
"done"
```
+ sprint-status.yaml路径 + stories/路径
终止（上下文销毁）。

Epic 모드

Epic模式

전달받은

epic_id

의 에픽을 자율 실행한다. E1 → E2 → E3 순차 진행.

自主执行接收到的

epic_id

对应的史诗任务。按E1 → E2 → E3顺序执行。

E0. 초기 정리 및 Modification 처리

E0. 初始整理及Modification处理

a) Orphan regression story 정리 (항상 실행, 첫 실행 시에는 대상이 없으므로 no-op): 에픽 내

is_regression: true

이고

status: todo

인 Story를

status: skipped

로 변경한다. 이전 E2E 실행 중 중단으로 생성된 orphan regression story를 정리하여 불필요한 재실행을 방지한다.

bash

yq -i '.<TICKET>.<EPIC>.<REGRESSION-STORY>.status = "skipped"' docs/sprint-status.yaml

b) Modification 처리 (modification.md가 전달된 경우에만):

modification.md를 읽어 수정 대상 Story를 파악한다.

해당 Story의 status를

in_progress

로 변경:

bash

yq -i '.<TICKET>.<EPIC>.<STORY>.status = "in_progress"' docs/sprint-status.yaml

tdd, review 필드를 초기화하고, e2e도

pending

으로 리셋한다. 보존하는 메트릭 필드:
ralph_retries
,
ralph_approaches
,
ralph_stuck
,
model_used
(이전 시도의 기록 유지).

review_blockers

review_recommended

는 bf-lead-review가 재리뷰 시 새 값으로 덮어쓰므로 별도 리셋 불필요. 수정 대상이 아닌 Story의 리뷰 메트릭은 보존된다:

bash

yq -i '
  .<TICKET>.<EPIC>.<STORY>.tdd = "pending" |
  .<TICKET>.<EPIC>.<STORY>.review = "pending"
' docs/sprint-status.yaml
yq -i '.<TICKET>.<EPIC>.e2e = "pending"' docs/sprint-status.yaml

a) 清理孤立回归Story（始终执行，首次执行时无目标则无操作）： 将史诗任务中

is_regression: true

且

status: todo

的Story的状态改为

status: skipped

。清理之前E2E执行中断时生成的孤立回归Story，避免不必要的重复执行。

bash

yq -i '.<TICKET>.<EPIC>.<REGRESSION-STORY>.status = "skipped"' docs/sprint-status.yaml

b) 处理Modification（仅在传递了modification.md时执行）：

读取modification.md，确定需要修改的Story。

将对应Story的状态改为

in_progress

：

bash

yq -i '.<TICKET>.<EPIC>.<STORY>.status = "in_progress"' docs/sprint-status.yaml

初始化tdd、review字段，将e2e重置为

pending

。保留的指标字段：
ralph_retries
,
ralph_approaches
,
ralph_stuck
,
model_used
（保留之前尝试的记录）。

review_blockers

review_recommended

会由bf-lead-review在重新评审时覆盖，无需单独重置。非修改目标的Story的评审指标将被保留：

bash

yq -i '
  .<TICKET>.<EPIC>.<STORY>.tdd = "pending" |
  .<TICKET>.<EPIC>.<STORY>.review = "pending"
' docs/sprint-status.yaml
yq -i '.<TICKET>.<EPIC>.e2e = "pending"' docs/sprint-status.yaml

E1. 스토리 구현 — bf-lead-implement 스폰

E1. Story实现 — 启动bf-lead-implement

Story 0개 에픽 또는
todo
/
in_progress
Story가 없는 에픽은 E1을 건너뛰고 E2로 진행한다. (e2e가 이미

passed

인 Story 0개 에픽은 E2도 건너뛰고 E3로 직행)

모델 선택: 에픽 내 L/XL Story 포함 시
```
model: opus
```
, S/M만이면
```
model: sonnet
```
전달 정보:
- 에픽 ID, Story 문서 경로 목록 (status가
```
todo
```
  또는
```
in_progress
```
  인 Story만)
- conventions.md 경로
- modification.md 경로 (수정 재실행인 경우)
수신 대기:
```
"done"
```
또는
```
"done (stuck: {STORY-ID}, ...)"
```
+ sprint-status.yaml 경로

수신 후 자동 판단 (stuck):

조건	자동 결정
stuck 없음	E2로 진행
stuck Story 있음 + 비stuck Story 존재	stuck Story를 `status: skipped` 로 변경, 나머지로 E2 진행
전 Story stuck	모두 `status: skipped` 로 변경, `e2e: skipped` 기록, E3 review로 직행 (done Story 0개이므로 E2E 무의미)

stuck Story를 skip 처리:

bash

yq -i '.<TICKET>.<EPIC>.<STORY>.status = "skipped"' docs/sprint-status.yaml

stuck 정보는 sprint-status.yaml(

ralph_stuck: true

) + stuck.md에 이미 기록되어 있다. bf-execute가 에픽 결과로 사람에게 제시한다.

无Story的史诗任务或无
todo
/
in_progress
状态Story的史诗任务，将跳过E1直接进入E2。（所有Story的e2e均为

passed

的无Story史诗任务，将跳过E2直接进入E3）

模型选择：史诗任务包含L/XL级Story时使用
```
model: opus
```
，仅包含S/M级时使用
```
model: sonnet
```
传递信息：
- 史诗任务ID、Story文档路径列表（仅包含状态为
```
todo
```
  或
```
in_progress
```
  的Story）
- conventions.md路径
- modification.md路径（修改重执行场景）
等待接收：
```
"done"
```
或
```
"done (stuck: {STORY-ID}, ...)"
```
+ sprint-status.yaml路径

接收后的自动判断（stuck情况）：

条件	自动决策
无stuck情况	进入E2阶段
存在stuck Story且存在非stuck Story	将stuck Story的状态改为 `status: skipped` ，使用剩余Story进入E2阶段
所有Story均stuck	将所有Story的状态改为 `status: skipped` ，记录 `e2e: skipped` ，直接进入E3评审阶段（无已完成Story，E2E无意义）

标记stuck Story为跳过：

bash

yq -i '.<TICKET>.<EPIC>.<STORY>.status = "skipped"' docs/sprint-status.yaml

stuck信息已记录在sprint-status.yaml（

ralph_stuck: true

）和stuck.md中。bf-execute会将史诗任务结果呈现给人类。

E2. E2E 작성 + 실행 — E2E agent 스폰

E2. 编写+执行E2E测试 — 启动E2E Agent

done Story가 없는 에픽은 E2E agent를 스폰하지 않고 E3로 직행한다:

Story 0개 에픽 (인프라 에픽 등):
```
e2e: passed
```
로 기록
전 Story skipped (전체 stuck 포함):
```
e2e: skipped
```
로 기록. 구현이 없는 상태에서 E2E를 실행하면 무의미한 실패가 발생하므로 skip 처리

<HARD-GATE> done Story가 1개 이상인 에픽에서 E2E 단계는 절대 건너뛰지 않는다. Story 수가 적어도, 변경이 사소해 보여도 E2E를 실행한다. "E2E 없이도 충분하다"는 이 게이트를 우회하는 전형적인 합리화이다. </HARD-GATE>

E2E agent를 1개 스폰한다.

E2E agent 모델 선택:

기본:
```
model: sonnet
```
브라우저 UI 프로젝트 (React/Vue/Angular/Next.js 등):
```
model: opus
```
— agent-browser 기반 E2E는 복잡한 DOM 상호작용과 시나리오 판단이 필요
API-only / CLI 프로젝트:
```
model: sonnet
```
— curl/shell 기반 E2E는 상대적으로 단순 전달 정보: 에픽 ID, Story 목록, tech-spec 경로, conventions.md 경로, sprint-status.yaml 경로.

E2E agent는 아래 **"E2E Agent 지침"**을 따른다.

수신 후 자동 판단 (E2E):

조건	자동 결정
`"passed"`	E3로 진행
`"failed"` + regression story (E2E 사이클 2회 미만)	regression story로 E1 재실행
`"failed"` + regression story (E2E 사이클 2회 도달)	`e2e: max-regression-cycles` 기록, E3 진행
`"escalation"` (가드레일 초과 또는 인프라 오류)	`e2e: escalated` 기록, E3 진행

E2E 사이클 카운트: epic 모드 진입 시 0으로 시작,

"failed"

수신마다 +1.

max-regression-cycles 판정 시 orphan regression story 정리: E2E 사이클 2회 도달로

max-regression-cycles

를 기록할 때, 해당 사이클에서 E2E agent가 추가한 regression story가

status: todo

인 채 남아있다. 이 Story들을

status: skipped

로 변경하여 orphan을 방지한다:

bash

undefined

无已完成Story的史诗任务，将不启动E2E Agent直接进入E3：

无Story的史诗任务（如基础设施类史诗任务）：记录为
```
e2e: passed
```
所有Story均被跳过（包括全部stuck）：记录为
```
e2e: skipped
```
。在无实现的情况下执行E2E会产生无意义的失败，因此跳过处理

<HARD-GATE> 存在至少1个已完成Story的史诗任务，绝不能跳过E2E阶段。即使Story数量少或变更看似微小，也必须执行E2E测试。“无需E2E也足够”是绕过此关卡的典型合理化借口。 </HARD-GATE>

启动1个E2E Agent。

E2E Agent模型选择：

默认：
```
model: sonnet
```
浏览器UI项目（React/Vue/Angular/Next.js等）：
```
model: opus
```
— 基于agent-browser的E2E需要复杂的DOM交互和场景判断
纯API/CLI项目：
```
model: sonnet
```
— 基于curl/shell的E2E相对简单传递信息：史诗任务ID、Story列表、技术规格文档路径、conventions.md路径、sprint-status.yaml路径。

E2E Agent需遵循以下**“E2E Agent指南”**。

接收后的自动判断（E2E结果）：

条件	自动决策
`"passed"`	进入E3阶段
`"failed"` + 回归Story（E2E周期少于2次）	以回归Story重新执行E1
`"failed"` + 回归Story（E2E周期达到2次）	记录 `e2e: max-regression-cycles` ，进入E3阶段
`"escalation"` （超出防护阈值或基础设施错误）	记录 `e2e: escalated` ，进入E3阶段

E2E周期计数：进入epic模式时从0开始，每次接收到

"failed"

则+1。

判定为max-regression-cycles时清理孤立回归Story： 当E2E周期达到2次并记录

max-regression-cycles

时，该周期中E2E Agent添加的回归Story可能仍处于

status: todo

状态。将这些Story的状态改为

status: skipped

，避免产生孤立Story：

bash

undefined

대상: E2E agent가 "failed" 보고와 함께 전달한 regression story 목록

目标：E2E Agent在报告"failed"时传递的回归Story列表

yq -i '.<TICKET>.<EPIC>.<ORPHAN-STORY>.status = "skipped"' docs/sprint-status.yaml

undefined

yq -i '.<TICKET>.<EPIC>.<ORPHAN-STORY>.status = "skipped"' docs/sprint-status.yaml

undefined

E3. 에픽 통합 리뷰 — bf-lead-review 스폰

E3. 史诗任务集成评审 — 启动bf-lead-review

<HARD-GATE> 리뷰 단계는 절대 건너뛰지 않는다. E2E가 escalated/max-regression-cycles여도, Story가 모두 skipped여도 리뷰를 실행한다. 리뷰 결과가 사람 판단 ②의 핵심 입력이다. </HARD-GATE>

모델 선택: 에픽 내 L/XL Story 포함 시
```
model: opus
```
, S/M만이면
```
model: sonnet
```
```
mode: "epic-review"
```
+ epic ID + tech-spec 경로
수신 대기:
```
"done: approved"
```
또는
```
"done: blockers"
```
+ review.md 경로

수신 후 자동 판단 (리뷰):

조건	자동 결정
`"done: approved"` (Blocker 0건)	에픽 완료
`"done: blockers"` (Blocker 1건+)	sprint-status.yaml + review.md에 기록된 상태 유지, 자동 수정 안 함

<HARD-GATE> Blocker가 있어도 자동 수정하지 않는다. 코드를 고치거나, Story를 재실행하거나, 수정 지시를 생성하는 행위 모두 금지된다. Blocker 처리는 사람이 bf-execute의 에픽 결과에서 판단한다. </HARD-GATE>

<HARD-GATE> 绝不能跳过评审阶段。即使E2E结果为escalated/max-regression-cycles，或所有Story均被跳过，也必须执行评审。评审结果是人类决策的核心输入。 </HARD-GATE>

模型选择：史诗任务包含L/XL级Story时使用
```
model: opus
```
，仅包含S/M级时使用
```
model: sonnet
```
参数：
```
mode: "epic-review"
```
+ 史诗任务ID + 技术规格文档路径
等待接收：
```
"done: approved"
```
或
```
"done: blockers"
```
+ review.md路径

接收后的自动判断（评审结果）：

条件	自动决策
`"done: approved"` （无阻塞问题）	史诗任务完成
`"done: blockers"` （存在1个以上阻塞问题）	保留sprint-status.yaml + review.md中记录的状态，不自动修改

<HARD-GATE> 即使存在阻塞问题，也不自动修改。禁止修改代码、重新执行Story或生成修改指令。阻塞问题的处理由人类通过bf-execute查看史诗任务结果后决定。 </HARD-GATE>

E4. 완료 — Done 신호

E4. 完成 — 发送Done信号

bf-execute에 전달:

```
"done"
```
+ sprint-status.yaml 경로 + review.md 경로
종료 (컨텍스트 소멸).

向bf-execute传递：

```
"done"
```
+ sprint-status.yaml路径 + review.md路径
终止（上下文销毁）。

E2E Agent 지침

E2E Agent指南

E2E agent에게 전달할 인라인 지침이다. Agent는 이 지침을 그대로 따른다.

yq 전제조건 체크 (최초 1회):

bash

command -v yq >/dev/null 2>&1 || { echo "❌ yq not installed. Install: brew install yq"; exit 1; }

这是传递给E2E Agent的内联指南。Agent需严格遵循此指南。

yq前置条件检查（仅首次执行）：

bash

command -v yq >/dev/null 2>&1 || { echo "❌ yq not installed. Install: brew install yq"; exit 1; }

1. 프로젝트 E2E 타입 판별

1. 判别项目E2E类型

프로젝트 루트를 분석하여 타입을 결정한다:

브라우저 UI 프로젝트:
```
package.json
```
에 React/Vue/Angular/Svelte/Next.js dependency,
```
public/index.html
```
또는
```
src/App.*
```
,
```
next.config.*
```
/
```
vite.config.*
```
/
```
angular.json
```
→ agent-browser CLI 기반 E2E 작성
API-only 프로젝트: 백엔드 프레임워크만 존재 (Express/Fastify/NestJS/Django/Flask 등) → curl/httpie 기반 API E2E 작성
CLI 도구 프로젝트:
```
package.json
```
의
```
bin
```
필드 존재, CLI 엔트리포인트 → shell script 기반 CLI E2E 작성
E2E 불가 프로젝트: 라이브러리, 유틸리티 패키지, 순수 SDK → E2E skip,
```
"passed"
```
즉시 보고 (E2E 스크립트 작성/실행 없이
```
e2e: passed
```
기록)

分析项目根目录，确定类型：

浏览器UI项目：
```
package.json
```
中包含React/Vue/Angular/Svelte/Next.js依赖，存在
```
public/index.html
```
或
```
src/App.*
```
、
```
next.config.*
```
/
```
vite.config.*
```
/
```
angular.json
```
→ 基于agent-browser CLI编写E2E测试
纯API项目：仅包含后端框架（Express/Fastify/NestJS/Django/Flask等） → 基于curl/httpie编写API E2E测试
CLI工具项目：
```
package.json
```
中存在
```
bin
```
字段，有CLI入口点 → 基于shell script编写CLI E2E测试
无法执行E2E的项目：库、工具包、纯SDK → 跳过E2E，立即上报
```
"passed"
```
（不编写/执行E2E脚本，直接记录
```
e2e: passed
```
）

2. E2E 시나리오 도출

2. 推导E2E场景

에픽 내 모든 Story의 AC를 E2E 관점으로 시나리오화
Happy path + 주요 실패 경로 포함
사용자 플로우 기준으로 순서 결정

将史诗任务中所有Story的验收标准（AC）从E2E视角转化为测试场景
包含正常流程+主要异常流程
按用户流程顺序排列

3. E2E 스크립트 작성

3. 编写E2E脚本

```
tests/e2e/{epic-name}/
```
디렉토리에 저장
파일명:
```
{scenario-name}.sh
```
(shell 스크립트)
모든 E2E 타입은 shell script로 통일하여
```
zsh
```
로 직접 실행

브라우저 UI — agent-browser 요소 선택 원칙:

사용: semantic locator (
```
find role button --name "Submit"
```
,
```
find label "Email"
```
), @ref (snapshot 기반)
금지: CSS 셀렉터, XPath, DOM 구현 세부사항

保存到
```
tests/e2e/{epic-name}/
```
目录
文件名：
```
{scenario-name}.sh
```
（shell脚本）
所有E2E类型统一使用shell script，可直接用
```
zsh
```
执行

浏览器UI — agent-browser元素选择原则：

推荐使用：语义定位器（
```
find role button --name "Submit"
```
、
```
find label "Email"
```
）、@ref（基于快照）
禁止使用：CSS选择器、XPath、DOM实现细节

4. E2E 실행

4. 执行E2E测试

작성 즉시 전체 E2E 실행:

인프라 오류 vs 테스트 실패 구분:

인프라 오류 (regression Story 생성 안함,
```
"escalation"
```
+ 인프라 오류 사유를 Lead에 보고):
- exit code 127 (
```
command not found
```
  )
- ```
ECONNREFUSED
```
  (서버 미시작)
- ```
browser not started
```
  ,
```
browser crashed
```
- 스크립트 syntax error
테스트 실패 (regression Story 생성 대상):
- assertion 실패, wait 타임아웃, 예상과 다른 HTTP status code

编写完成后立即执行全部E2E测试：

区分基础设施错误与测试失败：

基础设施错误（不生成回归Story，向Lead上报
```
"escalation"
```
+基础设施错误原因）：
- 退出码127（
```
command not found
```
  ）
- ```
ECONNREFUSED
```
  （服务器未启动）
- ```
browser not started
```
  、
```
browser crashed
```
- 脚本语法错误
测试失败（需生成回归Story）：
- 断言失败、等待超时、HTTP状态码与预期不符

5. 결과 판정

5. 结果判定

전체 통과:

sprint-status.yaml 업데이트:

bash

yq -i '.<TICKET>.<EPIC>.e2e = "passed"' docs/sprint-status.yaml

```
"passed"
```
+ tests/e2e/ 경로를 Lead에 보고

git commit:

[{TICKET}] E2E 테스트 작성 및 통과

— tests/e2e/
파일만 커밋,
docs/
하위 파일은 제외

실패:

Regression 가드레일 확인:
- 에픽 내
```
is_regression: true AND (status: todo OR status: done)
```
  인 Story 3개 이상 →
```
"escalation"
```
  보고 (
```
status: skipped
```
  인 이전 orphan은 제외)
- ```
parent_story
```
  체인 depth 2 이상 →
```
"escalation"
```
  보고
가드레일 통과 시:
- 실패 원인 분석 + failure tag 분류:
  - ```
  spec-gap
```
  : AC/Tech Spec이 시나리오를 예상하지 못함
- ```
impl-bug
```
    : AC는 맞으나 구현에 결함
  - ```
  test-design
```
  : E2E 테스트 자체가 잘못됨
- ```
convention-violation
```
    : conventions.md 규칙 위반
  - ```
  integration
```
  : 개별 모듈 정상이나 결합 시 실패
- 새 regression Story 문서 생성:
```
docs/stories/{TICKET}-story-{N+1}.md
```
  - 번호: stories/ 전체에서 가장 큰 번호 + 1
- sprint-status.yaml에 새 Story 추가:
  bash
```
yq -i '.<TICKET>.<EPIC>.<NEW-STORY> = {
  "status":"todo","difficulty":"S","tdd":"pending","review":"pending",
  "model_used":null,"ralph_retries":0,"ralph_approaches":0,
  "review_blockers":0,"review_recommended":0,
  "failure_tag":"impl-bug","is_regression":true,
  "parent_story":"story-1","ralph_stuck":false
}' docs/sprint-status.yaml
```
  - ```
  failure_tag
```
  : 판정한 태그
- ```
is_regression: true
```
  - ```
  parent_story
```
  : 원인 Story ID
- 나머지 필드: 기본값
- 난이도 태깅:
```
impl-bug
```
  /
```
test-design
```
  /
```
convention-violation
```
  → SM,
  spec-gap
  /
  integration
  → sprint-status.yaml에서 원본 Story 난이도를 확인하여 ML
- git commit하지 않는다 — regression story 문서(
```
docs/stories/
```
  )와 sprint-status.yaml은 Phase 4 Archive에서 일괄 커밋한다.
- ```
"failed"
```
  + regression story 목록을 Lead에 보고

全部通过：

更新sprint-status.yaml：

bash

yq -i '.<TICKET>.<EPIC>.e2e = "passed"' docs/sprint-status.yaml

向Lead上报
```
"passed"
```
+ tests/e2e/路径
git提交：
```
[{TICKET}] E2E测试编写及通过
```
— 仅提交
tests/e2e/
下的文件，排除
docs/
下的文件

测试失败：

检查回归防护阈值：
- 史诗任务中
```
is_regression: true AND (status: todo OR status: done)
```
  的Story达到3个以上 → 上报
```
"escalation"
```
  （排除状态为
```
skipped
```
  的历史孤立Story）
- ```
parent_story
```
  链深度达到2级以上 → 上报
```
"escalation"
```
通过阈值检查时：
- 分析失败原因并分类failure tag：
  - ```
  spec-gap
```
  ：验收标准/技术规格未考虑该场景
- ```
impl-bug
```
    ：验收标准正确但实现存在缺陷
  - ```
  test-design
```
  ：E2E测试本身设计错误
- ```
convention-violation
```
    ：违反conventions.md规则
  - ```
  integration
```
  ：单个模块正常但集成时失败
- 生成新的回归Story文档：
```
docs/stories/{TICKET}-story-{N+1}.md
```
  - 编号：stories/目录中最大编号+1
- 在sprint-status.yaml中添加新Story：
  bash
```
yq -i '.<TICKET>.<EPIC>.<NEW-STORY> = {
  "status":"todo","difficulty":"S","tdd":"pending","review":"pending",
  "model_used":null,"ralph_retries":0,"ralph_approaches":0,
  "review_blockers":0,"review_recommended":0,
  "failure_tag":"impl-bug","is_regression":true,
  "parent_story":"story-1","ralph_stuck":false
}' docs/sprint-status.yaml
```
  - ```
  failure_tag
```
  ：判定的标签
- ```
is_regression: true
```
  - ```
  parent_story
```
  ：根源Story ID
- 其余字段：默认值
- 标记难度：
```
impl-bug
```
  /
```
test-design
```
  /
```
convention-violation
```
  → SM级，
  spec-gap
  /
  integration
  → 查看sprint-status.yaml中原始Story的难度，标记为ML级
- 不执行git提交 — 回归Story文档（
```
docs/stories/
```
  ）和sprint-status.yaml将在Phase 4 Archive中统一提交
- 向Lead上报
```
"failed"
```
  + 回归Story列表

6. sprint-status.yaml 업데이트 프로토콜

6. sprint-status.yaml更新协议

E2E agent는 CLAUDE.md의 Read-yq-Verify 프로토콜을 따른다:

수정 전에 sprint-status.yaml을 읽어 현재 상태 확인
```
yq -i
```
명령어로 대상 필드만 수정
수정 후 파일을 읽어 변경 확인

E2E Agent需遵循CLAUDE.md中的Read-yq-Verify协议：

修改前读取sprint-status.yaml，确认当前状态
使用
```
yq -i
```
命令仅修改目标字段
修改后读取文件，确认变更生效

Output Format

输出格式

```
"done"
```
+ sprint-status.yaml 경로 + review.md 경로 (에픽 실행 완료)
```
"done"
```
+ sprint-status.yaml 경로 + stories/ 경로 (plan 모드 완료)
중간 과정은 파일에만 기록, bf-execute 컨텍스트에 남기지 않음

```
"done"
```
+ sprint-status.yaml路径 + review.md路径（史诗任务执行完成）
```
"done"
```
+ sprint-status.yaml路径 + stories/路径（plan模式完成）
中间过程仅记录在文件中，不保留在bf-execute上下文中