@aion0/forge 0.9.0 → 0.9.2

package/docs/UI-Design-Brief-SidePanel.md

@@ -0,0 +1,278 @@
+
+# Forge 浏览器扩展 UI 设计 Brief —— 给 AI / 设计师用
+
+> **如何使用**:把这份文档完整粘到一次新 Claude / 设计 AI 对话里,或直接交给设计师。它包含了产品上下文、当前 UI 现状、要新增的屏幕、视觉约束。**不要让 AI 自己脑补 Forge 是什么** —— 这份就是 ground truth。
+>
+> 配套文档(可选,深入需求时再给):
+> - `forge-team-workflow.md` —— 完整工作流(详细)
+
+
+## 1. 一句话产品定位
+
+**Forge 浏览器扩展是 Chrome MV3 侧边栏,一个 AI chat 入口,让公司 Design / Dev / QA 三个团队的日常协作在一个对话框里完成。它复用用户已登录的公司系统(Mantis / GitLab / PMDB / Teams)session,通过浏览器 DOM 提取拿数据,不需要 API token。**
+
+
+## 2. 用户角色与高频任务
+
+| 角色 | 高频任务(按频次) |
+|---|---|
+| **Design** | 1. 看 PMDB inbox 新需求 2. 起 PD 设计文档草稿 3. 整理评审反馈 4. 同类历史 epic 检索 |
+| **Dev (技术负责人)** | 1. Review PD 提反馈 2. 起技术设计文档 3. 拆 GitLab 子 issue 4. 看周进度简报 |
+| **Dev (模块负责人)** | 1. 看分给我的 issue 2. MR 摘要 3. 实现期写决策记录 |
+| **QA** | 1. 起测试用例草稿 2. 起自动化脚本 3. 创建 / 跟踪 Mantis bug |
+| **Manager** | (Phase 1 不专门设计,看 Dev 视图即可)Release dashboard 后期再做 |
+
+**所有人共同的高频任务**:在 chat 里输入问题 / 指令,看 chat 输出,接受/编辑后落地到 pd-docs git 仓库。
+
+
+## 3. 当前 UI 现状(必读)
+
+### 已实现 —— Direction A 侧边栏 4 个 Tab
+
+```
+┌─────────────────────────────────────┐
+│ ⚙ Forge          [⚙]                │  ← Header(logo + 设置图标)
+├─────────────────────────────────────┤
+│ Chat | Jobs | Connectors | Settings │  ← Tab Bar(badge 可挂未读)
+├─────────────────────────────────────┤
+│                                     │
+│                                     │
+│         (Tab 内容区)                │
+│                                     │
+│                                     │
+└─────────────────────────────────────┘
+```
+
+宽度:约 400-500 px(Chrome 侧边栏典型尺寸),高度全屏。
+
+### 当前 4 个 Tab 的现状
+
+| Tab | 现状 |
+|---|---|
+| **Chat** | 类 ChatGPT 风格,消息列表 + 输入框;支持多会话切换 / fork / 删除;消息支持 markdown 渲染 |
+| **Jobs** | 列定时 / 一次性 / cron 任务,基本 CRUD;skill picker 可挑技能;**已实现但可深化** |
+| **Connectors** | 列已安装的连接器,每个有"批准脚本"按钮(SHA-256 校验);**已实现** |
+| **Settings** | Forge URL / 登录 / 多 LLM provider 配置 / 保存测试按钮;**已实现** |
+
+### 视觉系统约束(必须遵守)
+
+- 设计语言定义在 `docs/design/`(repo 内的"Smith Extension"设计包,Direction A side-panel)
+- **颜色 / 字体 / 间距 token 已定**,新屏幕沿用,**不引入新色板**
+- 主背景 `var(--paper)`(米白色基底)
+- 风格关键词:**轻量、低对比、文字优先、克制动效**
+- **不要拟物 / 渐变 / 大圆角**;参考 Notion / Linear 的克制感
+
+
+## 4. Phase 1 要新增 / 改造的 UI
+
+下面是**本期要做的 UI 工作**。每条都注明优先级和范围。
+
+### 4.1 ⭐ P0 —— Chat Tab 增强:"绑定 Epic 上下文"
+
+**问题**:目前 chat 不知道你在哪个 epic 上下文里。Design 起 PD 时 chat 要能拉对应 epic 的 inbox 文件。
+
+**新增 UI 元素**:
+- **顶部"Epic 选择器"** —— Chat tab 上方一条窄条,左边显示当前绑定的 epic(如 `📌 EPIC-9981 SAML-SSO · 2026-Q3`),点击弹下拉切换 / 解绑 / 新建 epic
+- **未绑定状态**:显示 `📂 No epic context · select one` 提示色弱化
+- 切换 epic 时,chat 自动注入系统消息说明"上下文已切到 X"
+
+**视觉**:窄条高度 ~32px,跟 TabBar 同一级别但**视觉重量更轻**(灰色文字)。
+
+### 4.2 ⭐ P0 —— Chat 输入框:Quick Actions
+
+**问题**:Design / Dev / QA 各有几个常用动作,每次手打太重。
+
+**新增 UI 元素**:
+- **输入框上方一行 chip 按钮**,根据当前角色 / 当前 epic stage 上下文显示 3-5 个 Quick Action:
+  - Design + 已绑 epic + 无 02-design.md → `[起 PD 草稿]` `[起会议纪要]` `[找历史 epic]`
+  - Dev + 已绑 epic + 有 02-design.md → `[Review PD]` `[起技术设计]` `[拆子 issue]`
+  - QA + 已绑 epic + 02 / 04 都齐 → `[起测试用例]` `[起自动化脚本]` `[报 bug]`
+- 点 chip = 把对应 prompt 模板填进输入框,**用户可继续编辑后发出**(不直接发,避免误操作)
+- chip 视觉:细边框 / 灰色背景 / 小字号 / hover 微高亮
+
+### 4.3 ⭐ P0 —— 新 Tab: **Epic Workspace**(替换 / 升级现有 Connectors tab 上面?或独立 tab)
+
+**问题**:Forge chat 是入口,但用户也需要看到"当前 epic 有哪些文档、什么阶段、关联了什么"。今天的 4 个 tab 不承载这个视图。
+
+**建议**:**在 Chat 和 Jobs 中间插一个新 Tab,叫 `Epic`(或 `Work`)**。Tab Bar 变成 5 个:
+```
+Chat | Epic | Jobs | Connectors | Settings
+```
+
+**Epic Tab 的内容**:
+
+```
+┌────────────────────────────────────────┐
+│ [搜索框]   [+ New Epic]                │
+├────────────────────────────────────────┤
+│ ▾ 2026-Q3                              │
+│   📌 EPIC-9981 SAML-SSO    [Stage: Dev]│
+│      pd-docs / Mantis / GitLab Epic    │
+│      🟢 12 issues / 3 open / 0 blocker │
+│                                        │
+│   ⚪ EPIC-9985 Audit Log    [Stage: Design]│
+│                                        │
+│ ▾ 未规划                                │
+│   ⚪ EPIC-TBD 双因素登录   [Stage: Design]│
+│                                        │
+│ ▾ Inbox (4 条新需求)                    │
+│   📥 PMDB-7821 ACME SAML  · 3 天前      │
+│   📥 PMDB-7822 ...        · 1 天前      │
+│   ...                                  │
+└────────────────────────────────────────┘
+```
+
+要点:
+- **按 release 分组**,折叠
+- 每个 epic 卡片显示:**ID 名字、当前 stage、外链(pd-docs / Mantis / GitLab)、状态摘要**
+- **Inbox 区**单独一组,新需求倒序
+- 点 epic 卡片 → 跳到 chat tab 并自动绑定该 epic 上下文
+- 点 inbox 项 → 弹出"基于这条建 epic"对话框,确认后 chat 触发 Forge job
+
+### 4.4 ⭐ P1 —— Epic 详情面板(从 Epic Tab 点入)
+
+点击 Epic 卡片如果不希望直接跳 chat,而是**先看详情**,提供一个详情面板(也可以是 modal / 下推):
+
+```
+┌────────────────────────────────────────┐
+│ ← 返回                                  │
+│                                        │
+│ EPIC-9981 SAML-SSO                     │
+│ 2026-Q3 · Stage: Implementation        │
+│                                        │
+│ Links:                                 │
+│   📄 pd-docs/.../EPIC-9981/            │
+│   🐞 Mantis MA-9981                    │
+│   🦊 GitLab Epic !9981                 │
+│                                        │
+│ Documents in this Epic:                │
+│   ✅ 00-intake.md                       │
+│   ✅ 01-discovery/ (3)                  │
+│   ✅ 02-design.md (v1.0)                │
+│   ✅ 03-review/ (2 rounds)              │
+│   🔄 04-tech-design/ (3 modules)        │
+│   ⏳ 06-test/ (not yet)                  │
+│                                        │
+│ [💬 Open Chat in This Epic]            │
+│ [🔧 Run Job: Refresh Status]           │
+└────────────────────────────────────────┘
+```
+
+要点:
+- 列出 pd-docs 里这个 epic 目录下所有文件,**用 ✅ / 🔄 / ⏳ 表示当前状态**
+- 点文件名能预览 markdown(可后期做)
+- 底部主 CTA:"在这个 epic 上下文里开 chat"
+- 次要 CTA:运行相关 job(刷新 GitLab 状态、生成周报等)
+
+### 4.5 P1 —— Connectors Tab 增加视觉状态
+
+**问题**:已有审批流(approved / pending / updated),但缺一些 affordance。
+
+**改造**:
+- 每个连接器卡片增加最后一次成功调用的时间戳(`✓ 5 min ago · list_my_bugs`)
+- 出错时显示红色 pill(`⚠ last call failed: timeout`)
+- 增加"测试连接"按钮,跑一个 read-only tool 看是否 healthy
+
+### 4.6 P1 —— Jobs Tab 增加"上次运行结果摘要"
+
+**问题**:已有 jobs 列表,但用户不知道每个 job 上次跑得怎么样。
+
+**改造**:
+- 每个 job 卡片增加上次运行的时间戳 + 简短结果摘要(`✓ 10 min ago · synced 3 new items`)
+- 失败时红色,点开看 stderr / 错误
+
+### 4.7 P2 —— 起 PD / 起测试用例的"分步引导"对话
+
+**问题**:Quick Action chip 点一下 prompt 模板就填到输入框是够用的,但**起 PD 这种长流程**可以做得更引导。
+
+**可选改造**(只在用户反馈不够好时做):
+- 点 `[起 PD 草稿]` chip 弹一个轻量 wizard:
+  1. "基于哪些 discovery 文件?"(多选已有的)
+  2. "参考哪份历史 PD 的结构?"(下拉)
+  3. "重点强调哪些维度?"(可选 chip:架构 / API / 性能 / 安全 / 兼容性)
+- 走完 wizard 生成 prompt 给 chat 处理
+
+**Phase 1 默认不做,只在 4.2 的 chip 不够好时再做。**
+
+
+## 5. 你不需要设计的部分(Out of scope)
+
+- 完整的 Forge 后台管理界面(管理员看 jobs / connectors / 用户管理)—— 不在浏览器扩展里
+- Release dashboard(Manager 视角)—— Phase 1 不做
+- 移动端 / 不同浏览器 —— 只支持 Chrome 桌面版
+- 文件预览的高级渲染(Mermaid / 代码高亮)—— Phase 1 列表展示就够
+- 协作多人光标 / 实时同步 —— 离线文档协作走 git MR,不在 chat 里
+
+
+## 6. 给 AI 设计师的具体输出要求
+
+请按以下顺序产出(每个屏幕都要):
+
+1. **低保真线框图**(ASCII / markdown 表格 / 文字描述都行,Claude 输出的话用 ASCII)
+2. **交互说明**:每个可点元素点了之后发生什么
+3. **状态枚举**:loading / empty / error / success 各状态的视觉
+4. **响应式考虑**:侧边栏宽度可变(400-600px),怎么 graceful
+5. **可访问性**:键盘导航顺序,ARIA label 建议
+
+**优先做 §4.1 / 4.2 / 4.3 / 4.4 这四个 P0 / P1**。
+
+如果时间允许,可以再给 §4.5 / 4.6 一些建议。
+
+
+## 7. 我可能会被问到的几个问题(提前回答)
+
+**Q: 你为什么要把 Epic 视图做成独立 Tab 而不是放在 Chat 里?**
+A: Chat 是"做事的地方",Epic 视图是"导航 / 状态总览的地方"。两种心智模型不一样。但**点 Epic 后跳回 Chat 自动绑定**这个动作是把两边粘合的关键,请重点设计这个转场。
+
+**Q: Phase 1 是否要做 Manager 视角?**
+A: 不要。Manager 看 Dev 视角的 Epic Tab 已经够。Release dashboard 留给后期。
+
+**Q: 设计稿要不要细化到颜色 hex 值?**
+A: 不需要。沿用现有 `docs/design/` 的 token。给布局 / 信息密度 / 交互流就够了。
+
+**Q: 用户最常用的是不是 chat?其他 tab 会不会很少进?**
+A: 是的。Chat 占 70%+ 时间。但 Epic Tab(§4.3)是**进入 chat 的入口** —— 用户每天开始工作时先看 Epic Tab,决定今天进哪个上下文。所以这两个 tab 的连接要顺。
+
+
+## 8. 输出哪里好
+
+你可以直接在对话里贴 ASCII 线框 + 说明。
+
+如果你要给我多版方案(强烈推荐),用 markdown 标题分隔:`## 方案 A` / `## 方案 B`,我会逐个 review。
+
+
+# 附录:产品截图描述(没有图但可以脑补)
+
+当前 Chat tab 大致长这样(类 ChatGPT):
+
+```
+┌───────────────────────────────────┐
+│ ⚙ Forge                       [⚙] │
+├───────────────────────────────────┤
+│ Chat | Jobs | Connectors | Set    │
+├───────────────────────────────────┤
+│ [< Session: New Conversation v ]  │
+├───────────────────────────────────┤
+│ 👤 帮我看下 EPIC-9981 的 PD 进展   │
+│                                   │
+│ 🤖 EPIC-9981 (SAML-SSO) 的 PD     │
+│    目前在 v0.3 版本,3 轮评审已经… │
+│    [详情列表]                      │
+│                                   │
+│ 👤 帮我起一份技术设计…             │
+│                                   │
+│ 🤖 [Tool: claude_code]             │
+│    正在 fortinac/ cwd 跑分析...   │
+│    ✓ 生成 04-tech-design/         │
+│      overview.md (3.2 KB)         │
+│                                   │
+├───────────────────────────────────┤
+│ [_____________________________]   │  ← 输入框
+│ [发送]                            │
+└───────────────────────────────────┘
+```
+
+**新版本主要改动是**:
+1. 输入框上加一行 Quick Action chips
+2. 顶部 session selector 之上 / 之下加 Epic 选择器
+3. 增加 Epic tab(在 Chat 右边)

package/lib/__tests__/foreach-batch-yaml.test.ts

@@ -0,0 +1,33 @@
+/**
+ * Smoke test: fortinet-mr-review-batch v0.3.0 parses end-to-end through
+ * parseWorkflow with the new for_each.before extension.
+ */
+import { parseWorkflow } from '../pipeline';
+import { readFileSync } from 'fs';
+
+const txt = readFileSync('/Users/zliu/.forge/data/flows/fortinet-mr-review-batch.yaml', 'utf8');
+const wf = parseWorkflow(txt);
+
+let ok = true;
+function eq(actual: any, expected: any, label: string) {
+  if (JSON.stringify(actual) === JSON.stringify(expected)) {
+    console.log(`  ✓ ${label}`);
+  } else {
+    console.log(`  ✗ ${label}: got ${JSON.stringify(actual)}, want ${JSON.stringify(expected)}`);
+    ok = false;
+  }
+}
+
+console.log('fortinet-mr-review-batch v0.3.0 — parseWorkflow integration');
+eq(wf.name, 'fortinet-mr-review-batch', 'workflow name');
+eq(wf.for_each?.source, '{{nodes.list-iids.outputs.iids}}', 'for_each.source');
+eq(wf.for_each?.as, 'mr_iid', 'for_each.as');
+eq(wf.for_each?.on_failure, 'continue', 'for_each.on_failure');
+eq(wf.for_each?.before, ['list-iids'], 'for_each.before');
+eq(Object.keys(wf.nodes), ['list-iids', 'ingest', 'triage', 'fix', 'reply', 'cleanup'], 'all 6 nodes parsed');
+eq(wf.nodes['list-iids']?.mode, 'shell', 'list-iids mode = shell');
+eq(wf.nodes['list-iids']?.worktree, false, 'list-iids worktree = false');
+eq(wf.nodes['list-iids']?.outputs?.[0]?.name, 'iids', 'list-iids outputs.iids name');
+eq(wf.nodes['list-iids']?.outputs?.[0]?.extract, 'stdout', 'list-iids outputs.iids extract');
+
+process.exit(ok ? 0 : 1);

package/lib/__tests__/foreach-before.test.ts

@@ -0,0 +1,201 @@
+/**
+ * for_each.before: tests — covers:
+ *   - parseWorkflow validates `before:` field shape + node existence
+ *   - parseForEach passes through `before:` correctly
+ *   - resolveForEachSource accepts node outputs (`{{nodes.X.outputs.Y}}`)
+ *
+ * Setup-phase orchestration (startPipeline scheduling, checkPipelineCompletion
+ * transition) needs running tasks + file system + scheduler — not unit-testable
+ * here. Verified end-to-end in fortinet-mr-review-batch v0.3.0.
+ *
+ * Run:  npx tsx lib/__tests__/foreach-before.test.ts
+ */
+
+import { parseWorkflow, resolveForEachSource } from '../pipeline';
+
+let passed = 0, failed = 0;
+function check(name: string, fn: () => void) {
+  try { fn(); console.log(`  ✓ ${name}`); passed++; }
+  catch (e) { console.log(`  ✗ ${name}\n    ${(e as Error).message}`); failed++; }
+}
+function expectThrow(fn: () => void, msgIncludes: string) {
+  try { fn(); throw new Error(`expected throw containing "${msgIncludes}"`); }
+  catch (e) {
+    const m = (e as Error).message;
+    if (!m.includes(msgIncludes)) throw new Error(`got "${m}", expected to include "${msgIncludes}"`);
+  }
+}
+function eqArr(a: unknown[], b: unknown[], label = '') {
+  if (a.length !== b.length || a.some((v, i) => v !== b[i])) {
+    throw new Error(`${label}: expected ${JSON.stringify(b)}, got ${JSON.stringify(a)}`);
+  }
+}
+
+console.log('for_each.before parsing + node-output source resolution tests');
+
+// ── parseForEach / parseWorkflow: shape + validation ──
+
+check('parseWorkflow accepts valid before: [<node>]', () => {
+  const wf = parseWorkflow(`
+name: test
+for_each:
+  source: "{{nodes.list-ids.outputs.ids}}"
+  as: id
+  before: [list-ids]
+nodes:
+  list-ids:
+    project: x
+    prompt: "echo 1,2,3"
+  body:
+    project: x
+    prompt: "consume {{id}}"
+    depends_on: [list-ids]
+`);
+  if (!wf.for_each) throw new Error('for_each missing');
+  if (!wf.for_each.before) throw new Error('before missing');
+  eqArr(wf.for_each.before, ['list-ids']);
+});
+
+check('parseWorkflow accepts multi-node before: [a, b]', () => {
+  const wf = parseWorkflow(`
+name: test
+for_each:
+  source: "{{nodes.b.outputs.list}}"
+  as: x
+  before: [a, b]
+nodes:
+  a: { project: x, prompt: "1" }
+  b: { project: x, prompt: "2", depends_on: [a] }
+  body: { project: x, prompt: "{{x}}" }
+`);
+  eqArr(wf.for_each!.before!, ['a', 'b']);
+});
+
+check('parseWorkflow with NO before: → before undefined (back-compat)', () => {
+  const wf = parseWorkflow(`
+name: test
+for_each:
+  source: "{{input.ids}}"
+  as: id
+nodes:
+  body: { project: x, prompt: "{{id}}" }
+`);
+  if (wf.for_each!.before !== undefined) throw new Error(`expected undefined, got ${JSON.stringify(wf.for_each!.before)}`);
+});
+
+check('parseWorkflow throws on before referencing unknown node', () => {
+  expectThrow(() => parseWorkflow(`
+name: test
+for_each:
+  source: "{{nodes.missing.outputs.x}}"
+  as: id
+  before: [missing]
+nodes:
+  body: { project: x, prompt: "1" }
+`), "references unknown node id 'missing'");
+});
+
+check('parseWorkflow throws on before: not-an-array', () => {
+  expectThrow(() => parseWorkflow(`
+name: test
+for_each:
+  source: "{{nodes.list-ids.outputs.x}}"
+  as: id
+  before: "list-ids"
+nodes:
+  list-ids: { project: x, prompt: "1" }
+  body: { project: x, prompt: "{{id}}" }
+`), 'must be an array of node id strings');
+});
+
+check('parseWorkflow throws on before: [empty-string]', () => {
+  expectThrow(() => parseWorkflow(`
+name: test
+for_each:
+  source: "{{nodes.x.outputs.x}}"
+  as: id
+  before: [""]
+nodes:
+  x: { project: x, prompt: "1" }
+  body: { project: x, prompt: "{{id}}" }
+`), 'must be an array of node id strings');
+});
+
+check('parseWorkflow throws on before: [non-string]', () => {
+  expectThrow(() => parseWorkflow(`
+name: test
+for_each:
+  source: "{{nodes.x.outputs.x}}"
+  as: id
+  before: [123]
+nodes:
+  x: { project: x, prompt: "1" }
+  body: { project: x, prompt: "{{id}}" }
+`), 'must be an array of node id strings');
+});
+
+// ── resolveForEachSource: ctx now includes nodes ──
+
+check('resolveForEachSource reads {{nodes.X.outputs.Y}} from pipeline.nodes', () => {
+  const nodes = {
+    'list-ids': { status: 'done' as const, outputs: { ids: '7,8,9' }, iterations: 0 },
+  };
+  const items = resolveForEachSource(
+    { source: '{{nodes.list-ids.outputs.ids}}' },
+    {},
+    {},
+    nodes,
+  );
+  eqArr(items, ['7', '8', '9']);
+});
+
+check('resolveForEachSource trims whitespace from node-output split items', () => {
+  const nodes = {
+    'list-ids': { status: 'done' as const, outputs: { ids: ' 1, 2 ,3 ' }, iterations: 0 },
+  };
+  const items = resolveForEachSource(
+    { source: '{{nodes.list-ids.outputs.ids}}' },
+    {},
+    {},
+    nodes,
+  );
+  eqArr(items, ['1', '2', '3']);
+});
+
+check('resolveForEachSource empty node output → empty array', () => {
+  const nodes = {
+    'list-ids': { status: 'done' as const, outputs: { ids: '' }, iterations: 0 },
+  };
+  const items = resolveForEachSource(
+    { source: '{{nodes.list-ids.outputs.ids}}' },
+    {},
+    {},
+    nodes,
+  );
+  eqArr(items, []);
+});
+
+check('resolveForEachSource with custom split + node output', () => {
+  const nodes = {
+    'list-ids': { status: 'done' as const, outputs: { ids: 'a|b|c' }, iterations: 0 },
+  };
+  const items = resolveForEachSource(
+    { source: '{{nodes.list-ids.outputs.ids}}', split: '|' },
+    {},
+    {},
+    nodes,
+  );
+  eqArr(items, ['a', 'b', 'c']);
+});
+
+check('resolveForEachSource without nodes param (back-compat) still works', () => {
+  const items = resolveForEachSource(
+    { source: '{{input.ids}}' },
+    { ids: '1,2' },
+    {},
+  );
+  eqArr(items, ['1', '2']);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/lib/__tests__/foreach-parse.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Step-2 verification: parseWorkflow handles `for_each:` correctly.
+ *
+ * No test framework — just a tsx script that throws on first failure.
+ * Run:  npx tsx lib/__tests__/foreach-parse.test.ts
+ */
+
+import { parseWorkflow } from '../pipeline';
+
+let passed = 0;
+let failed = 0;
+
+function check(name: string, fn: () => void) {
+  try { fn(); console.log(`  ✓ ${name}`); passed++; }
+  catch (e) { console.log(`  ✗ ${name}\n    ${(e as Error).message}`); failed++; }
+}
+
+function expectThrow(yaml: string, expectedSubstring: string) {
+  try {
+    parseWorkflow(yaml);
+    throw new Error(`expected throw containing "${expectedSubstring}", got none`);
+  } catch (e) {
+    const msg = (e as Error).message;
+    if (!msg.includes(expectedSubstring)) {
+      throw new Error(`expected throw containing "${expectedSubstring}", got: ${msg}`);
+    }
+  }
+}
+
+console.log('parseWorkflow + for_each: parser tests');
+
+check('no for_each → workflow.for_each is undefined', () => {
+  const w = parseWorkflow('name: foo\nnodes:\n  a: { project: x, prompt: "echo hi" }\n');
+  if (w.for_each !== undefined) throw new Error(`expected undefined, got ${JSON.stringify(w.for_each)}`);
+});
+
+check('valid for_each with string source', () => {
+  const w = parseWorkflow(`
+name: foo
+for_each:
+  source: "{{input.ids}}"
+  as: bug_id
+nodes:
+  a: { project: x, prompt: "echo {{bug_id}}" }
+`);
+  if (!w.for_each) throw new Error('for_each missing');
+  if (w.for_each.source !== '{{input.ids}}') throw new Error('source wrong');
+  if (w.for_each.as !== 'bug_id') throw new Error('as wrong');
+  if (w.for_each.on_failure !== 'continue') throw new Error(`on_failure default should be continue, got ${w.for_each.on_failure}`);
+});
+
+check('default as = "item"', () => {
+  const w = parseWorkflow('name: foo\nfor_each:\n  source: "{{input.x}}"\nnodes:\n  a: { project: x, prompt: "" }\n');
+  if (w.for_each!.as !== 'item') throw new Error('default as should be item');
+});
+
+check('on_failure: stop accepted', () => {
+  const w = parseWorkflow('name: foo\nfor_each:\n  source: x\n  on_failure: stop\nnodes:\n  a: { project: x, prompt: "" }\n');
+  if (w.for_each!.on_failure !== 'stop') throw new Error('on_failure not preserved');
+});
+
+check('array source literal', () => {
+  const w = parseWorkflow('name: foo\nfor_each:\n  source: [1, 2, 3]\nnodes:\n  a: { project: x, prompt: "" }\n');
+  if (!Array.isArray(w.for_each!.source)) throw new Error('array literal not preserved');
+  if ((w.for_each!.source as any[]).length !== 3) throw new Error('array length wrong');
+});
+
+check('split: ";" accepted', () => {
+  const w = parseWorkflow('name: foo\nfor_each:\n  source: x\n  split: ";"\nnodes:\n  a: { project: x, prompt: "" }\n');
+  if (w.for_each!.split !== ';') throw new Error('split not preserved');
+});
+
+console.log('\nError-path tests:');
+
+check('throws on missing source', () => {
+  expectThrow('name: foo\nfor_each:\n  as: bug\nnodes:\n  a: { project: x, prompt: "" }\n', 'source is required');
+});
+
+check('throws on invalid as identifier', () => {
+  expectThrow('name: foo\nfor_each:\n  source: x\n  as: "bad-name"\nnodes:\n  a: { project: x, prompt: "" }\n', 'must be a valid identifier');
+});
+
+check('throws on reserved as: input', () => {
+  expectThrow('name: foo\nfor_each:\n  source: x\n  as: input\nnodes:\n  a: { project: x, prompt: "" }\n', 'reserved template namespace');
+});
+
+check('throws on reserved as: run', () => {
+  expectThrow('name: foo\nfor_each:\n  source: x\n  as: run\nnodes:\n  a: { project: x, prompt: "" }\n', 'reserved template namespace');
+});
+
+check('throws on bad on_failure value', () => {
+  expectThrow('name: foo\nfor_each:\n  source: x\n  on_failure: maybe\nnodes:\n  a: { project: x, prompt: "" }\n', "must be 'continue' or 'stop'");
+});
+
+check('throws on for_each on conversation type', () => {
+  expectThrow(`
+name: foo
+type: conversation
+for_each:
+  source: x
+agents:
+  - id: a
+    agent: claude
+initial_prompt: hi
+nodes: {}
+`, "only supported on type='dag'");
+});
+
+check('throws on for_each scalar (not object)', () => {
+  expectThrow('name: foo\nfor_each: "{{input.ids}}"\nnodes:\n  a: { project: x, prompt: "" }\n', 'must be an object');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);