Merge pull request #12 from reoring/feat/subworkflow-completion-check

feat(workflow): subworkflow completion_check loop

Author: reoring

CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file.
 
 The format is based on Keep a Changelog, and this project follows SemVer where practical.
 
+## [0.1.5] - 2026-02-25
+
+### Added
+
+- Allow subworkflow steps (`workflow:`) to use `completion_check` loops (`max_iterations`) to rerun child workflows until complete.
+- Add subworkflow event bubbling (`bubble_subworkflow_events`, `subworkflow_event_prefix`) and deterministic export copying (`exports_mode: merge|replace`).
+- Improve workflow TUI: ANSI-aware wrapping in tabs, and `y` to copy the visible detail tab to the clipboard (system clipboard commands or OSC52 fallback).
+- Add a runnable subworkflow loop example (`examples/subworkflow-loop.yaml`, `examples/subworkflow-loop-child.yaml`).
+
+### Changed
+
+- Completion checks accept decisions from `decision_file` JSON or text markers (`PASS`/`FAIL`/`COMPLETE`/`INCOMPLETE`), and can fall back to parsing worker stdout (JSON or marker).
+- Completion check instructions interpolate `$ROBOPPI_COMPLETION_CHECK_ID` / `${ROBOPPI_COMPLETION_CHECK_ID}` to the active check id for robustness.
+- `scripts/agent-pr-loop/todo-check.sh` now respects `ROBOPPI_TODO_PATH` / `ROBOPPI_LOOP_DIR` and prefers legacy `.agentcore-loop` when present.
+
 ## [0.1.4] - 2026-02-22
 
 ### Fixed

docs/workflow-design.md

@@ -44,6 +44,13 @@ steps:
 
 ### 2.2 StepDefinition
 
+Each step is one of:
+
+- **Worker step**: runs a worker (`worker` + `instructions` + `capabilities`)
+- **Subworkflow step**: runs a child workflow (`workflow`) and optionally exports child artifacts (`exports`)
+
+`worker` and `workflow` are mutually exclusive.
+
 ```yaml
 steps:
   <step_id>:
@@ -59,6 +66,16 @@ steps:
     capabilities:                           # allowed operations
       - enum                                # READ | EDIT | RUN_TESTS | RUN_COMMANDS
 
+    # ---- Subworkflow config (alternative to Worker config) ----
+    workflow?: string                        # child workflow YAML path (mutually exclusive with worker)
+    exports?:                                # optional: copy child artifacts into this step's context
+      - from: string                         # child step id
+        artifact: string                     # child artifact name
+        as?: string                          # name in parent context (default: artifact)
+    exports_mode?: enum                      # merge | replace
+    bubble_subworkflow_events?: boolean      # default: false (blackbox) / true (show child steps)
+    subworkflow_event_prefix?: string        # default: auto (= parent step id)
+
     # ---- DAG dependencies ----
     depends_on?: string[]                   # list of prerequisite step ids
 
@@ -111,9 +128,12 @@ completion_check:
 ```
 
 The checker worker evaluates artifact state and returns **complete / incomplete**.
-If incomplete, the main worker is rerun (up to `max_iterations`).
+If incomplete, the step is rerun (up to `max_iterations`).
 
-Because the checker and main worker run in the same `workspace`, file state naturally carries over across iterations.
+- For worker steps: rerun the worker
+- For subworkflow steps: rerun the child workflow
+
+Because the checker and the step execution run in the same `workspace`, file state naturally carries over across iterations.
 
 ### 2.6 Full type definition (TypeScript representation)
 
@@ -128,25 +148,71 @@ interface WorkflowDefinition {
   steps: Record<string, StepDefinition>;
 }
 
-interface StepDefinition {
+type StepDefinition = WorkerStepDefinition | SubworkflowStepDefinition;
+
+interface WorkerStepDefinition {
   description?: string;
   agent?: string;                          // optional agent profile id
   worker: "CODEX_CLI" | "CLAUDE_CODE" | "OPENCODE" | "CUSTOM";
+  model?: string;
   workspace?: string;
   instructions: string;
   capabilities: ("READ" | "EDIT" | "RUN_TESTS" | "RUN_COMMANDS")[];
+
   depends_on?: string[];
   inputs?: InputRef[];
   outputs?: OutputDef[];
   timeout?: DurationString;
   max_retries?: number;
   max_steps?: number;
   max_command_time?: DurationString;
+
   completion_check?: CompletionCheckDef;
   convergence?: ConvergenceDef;         // optional; opt-in convergence control for loops
   max_iterations?: number;              // default: 1 (no loop)
   on_iterations_exhausted?: "abort" | "continue";
   on_failure?: "retry" | "continue" | "abort";
+
+  // Disallow subworkflow-only fields
+  workflow?: never;
+  exports?: never;
+}
+
+interface ExportRef {
+  from: string;
+  artifact: string;
+  as?: string;
+}
+
+interface SubworkflowStepDefinition {
+  description?: string;
+  workflow: string;
+  exports?: ExportRef[];
+  exports_mode?: "merge" | "replace";
+  bubble_subworkflow_events?: boolean;
+  subworkflow_event_prefix?: string;
+
+  depends_on?: string[];
+  inputs?: InputRef[];
+  timeout?: DurationString;
+  max_retries?: number;
+
+  completion_check?: CompletionCheckDef;
+  convergence?: ConvergenceDef;
+  max_iterations?: number;
+  on_iterations_exhausted?: "abort" | "continue";
+  on_failure?: "retry" | "continue" | "abort";
+
+  // Disallow worker-only fields
+  agent?: never;
+  worker?: never;
+  model?: never;
+  workspace?: never;
+  instructions?: never;
+  capabilities?: never;
+  outputs?: never;
+  max_steps?: never;
+  max_command_time?: never;
 }
 
 interface ConvergenceStageDef {

examples/README.md

@@ -40,6 +40,7 @@ timeout 10s ./roboppi daemon examples/daemon/simple-cron.yaml --verbose
 - `examples/build-test-report.yaml`: build -> test (parallel) -> report
 - `examples/failure-recovery.yaml`: failure handling / retry patterns
 - `examples/todo-loop.yaml`: simple iterative loop pattern
+- `examples/subworkflow-loop.yaml`: subworkflow step + completion_check loop (see `examples/subworkflow-loop-child.yaml`)
 - `examples/agent-pr-loop.yaml`: larger multi-step agent loop (see demo under `examples/agent-pr-loop-demo/`)
 - `examples/appthrust-dashboard/workflow.yaml`: production workflow for a team project (design -> todo -> implement -> validate)
 

examples/subworkflow-loop-child.yaml

@@ -0,0 +1,29 @@
+# Child workflow used by examples/subworkflow-loop.yaml
+
+name: subworkflow-loop-child
+version: "1"
+timeout: "1m"
+
+steps:
+  produce:
+    worker: CUSTOM
+    instructions: |
+      set -euo pipefail
+      mkdir -p .roboppi-loop
+
+      n=0
+      if [ -f .roboppi-loop/counter ]; then
+        n="$(cat .roboppi-loop/counter)"
+      fi
+      n=$((n+1))
+      echo "$n" > .roboppi-loop/counter
+
+      echo "run=$n" > report.txt
+      if [ "$n" -ge 3 ]; then
+        echo "OK" >> report.txt
+      fi
+      cat report.txt
+    capabilities: [READ, EDIT, RUN_COMMANDS]
+    outputs:
+      - name: report
+        path: report.txt

examples/subworkflow-loop.yaml

@@ -0,0 +1,41 @@
+# Subworkflow loop example
+#
+# Runs a child workflow via a `workflow:` step and uses a CUSTOM completion_check
+# to repeat the subworkflow until it becomes COMPLETE.
+#
+# Run:
+#   ./roboppi workflow examples/subworkflow-loop.yaml --verbose
+#   # (dev)
+#   bun run src/workflow/run.ts examples/subworkflow-loop.yaml --verbose
+
+name: subworkflow-loop
+version: "1"
+timeout: "5m"
+
+steps:
+  cycle:
+    workflow: "./subworkflow-loop-child.yaml"
+
+    # Show child steps in the UI as `cycle/<child-step-id>`.
+    bubble_subworkflow_events: true
+
+    # Copy exported artifacts deterministically across iterations.
+    exports_mode: replace
+    exports:
+      - from: produce
+        artifact: report
+        as: child-report
+
+    # exit 0 = COMPLETE, exit 1 = INCOMPLETE
+    completion_check:
+      worker: CUSTOM
+      instructions: |
+        set -euo pipefail
+        if [ -f report.txt ] && grep -q '^OK$' report.txt; then
+          exit 0
+        fi
+        exit 1
+      capabilities: [READ, RUN_COMMANDS]
+
+    max_iterations: 5
+    on_iterations_exhausted: abort

issues/completion-check-check-id-templating.ja.md

@@ -0,0 +1,105 @@
+# completion_check: decision_file の check_id 注入が brittle（$ENV がそのまま書かれる）
+
+ステータス: Open
+
+関連:
+
+- docs/issues/completion-check-decision-stability.ja.md
+
+## 問題
+
+completion_check の `decision_file` が JSON であっても、`check_id` が現在のチェック ID と一致しない場合、runner が以下のように扱って workflow が落ちる。
+
+- `stale decision_file check_id mismatch`
+- `Completion check infrastructure failure repeated`
+
+現場の典型パターン:
+
+- worker に「`check_id` は `$AGENTCORE_COMPLETION_CHECK_ID` を使え」と指示する
+- worker が **環境変数を展開できず**、文字列 `$AGENTCORE_COMPLETION_CHECK_ID` をそのままファイルに書く
+- runner は mismatch を stale とみなして FAIL
+
+これは「プロンプト調整の問題」ではなく、**runner と worker のインターフェイス設計**の問題になっている。
+
+## 再現（最小）
+
+1. workflow で completion_check に `decision_file: .agentcore-loop/review.verdict` を指定
+2. completion_check の instructions に次を要求
+
+```json
+{"decision":"incomplete","check_id":"$AGENTCORE_COMPLETION_CHECK_ID","reason":"not-ready"}
+```
+
+3. 実行すると runner が `check_id_match=false` で停止する
+
+## 期待（理想）
+
+- worker が shell を実行できない/しない場合でも `check_id` を正しく書ける
+- `check_id` mismatch が起きても、少なくとも「直し方」が明確で、即 hard-fail にならない
+
+## 根本解決案（候補）
+
+### 案A: runner が check_id を “文字列として” prompt に注入する
+
+worker は env var を読めないことがあるため、runner が instructions の先頭に **実値**を埋め込む。
+
+例:
+
+- `CompletionCheckID: <uuid>` を固定フォーマットで提示
+- workflow DSL に `{{completion_check_id}}` のようなテンプレートを導入し、runner が展開
+
+Pros:
+
+- LLM の出力だけで `check_id` が成立
+- 最も小さい変更で効果が大きい
+
+Cons:
+
+- workflow DSL のテンプレート導入（または自動注入）の設計が必要
+
+### 案B: decision_file の path を check_id で一意化（content で持たない）
+
+`decision_file` を固定パスではなく、check_id を含むファイル名にする。
+
+例:
+
+- `.agentcore-loop/review.verdict.<uuid>.json`
+
+runner は **その check_id のファイルだけ**を読む。
+
+Pros:
+
+- mismatch の概念が消える
+
+Cons:
+
+- artifact/cleanup/outputs の扱いが変わる
+
+### 案C: runner が JSON wrapper を生成し、worker には marker だけ要求
+
+worker 出力（または別ファイル）から `COMPLETE/INCOMPLETE` / `PASS/FAIL` を受け取り、runner が check_id を付与して JSON 化する。
+
+Pros:
+
+- LLM に strict な JSON ファイル書き込みを要求しない
+
+Cons:
+
+- runner 側の仕様追加が必要（decision_source の優先順位も含む）
+
+### 案D: mismatch を “infra failure” ではなく “INCOMPLETE + actionable” にする
+
+`check_id` mismatch は、実運用では「worker が書き方を間違えた」ケースが多い。
+
+- hard-fail ではなく INCOMPLETE として次 iteration で上書き可能にする
+- エラーメッセージに `expected=<uuid> got=<value>` を必ず含める
+- 可能なら `suggested_fix: rm -f <decision_file>` のようなガイドを出す
+
+## 受け入れ条件
+
+- `decision_file` が JSON で `decision` を含む場合、`check_id` を worker が確実に正しく書ける（少なくとも案A/B/C のいずれかで達成）
+- `check_id` mismatch が発生しても、workflow が “インフラ故障” として即死しない（INCOMPLETE で継続できる or 明確な修正指示が出る）
+- unit test で以下をカバー
+  - `check_id` 正常一致
+  - `check_id` 不一致（stale/誤記/プレースホルダ）
+  - JSON 形式エラー

issues/completion-check-decision-file-writer-helper.ja.md

@@ -0,0 +1,68 @@
+# completion_check: decision_file を LLM に書かせない（runner/スクリプトで生成する）
+
+ステータス: Open
+
+関連:
+
+- docs/issues/completion-check-decision-stability.ja.md
+- issues/completion-check-check-id-templating.ja.md
+
+## 問題
+
+completion_check の “正規経路” が `decision_file` の structured JSON になったことで、workflow 側は次を worker に要求しがちになる。
+
+- JSON 形式が正しい
+- 必須キー（decision/check_id/reason 等）が揃う
+- `check_id` が現行の completion check id と一致する
+
+しかし実際には、LLM worker に strict JSON のファイル書き込みを要求するのは brittle で、次のような事故が起きる。
+
+- JSON ではなく `PASS/FAIL` を書いてしまう
+- JSON だが `check_id` がプレースホルダ（`$AGENTCORE_COMPLETION_CHECK_ID`）のまま
+- 余計なコードフェンス/説明が混ざる
+
+結果として `Completion check infrastructure failure` のような “中身の改善とは無関係な失敗” が発生し、ループが止まる。
+
+## 根本方針
+
+decision_file は **LLM ではなく runner か deterministic なスクリプト**が生成する。
+
+LLM は以下のどれか “緩い出力” だけを提供する。
+
+- 最終行 marker: `COMPLETE` / `INCOMPLETE`
+- `PASS` / `FAIL`
+- `verdict.txt` に `complete|incomplete`
+- `verdict.json` に `{decision: ..., reasons: ...}`（ただし check_id は runner が付与）
+
+## 提案（実装案）
+
+### 案1: completion_check を CUSTOM に寄せる（JSON wrapper を生成）
+
+workflow DSL:
+
+- worker(LMM) は `.agentcore-loop/review.marker` に `COMPLETE/INCOMPLETE` を書く
+- completion_check(CUSTOM script) が:
+  - marker を読む
+  - `AGENTCORE_COMPLETION_CHECK_ID` を env から取得
+  - `decision_file` に JSON を確実に書く
+
+この場合、LLM に check_id を触らせない。
+
+### 案2: runner が “marker->JSON” を内蔵する
+
+runner は `decision_file` を読む前に:
+
+- worker 出力 marker（互換）を読み
+- JSON に正規化して `decision_file` を自動生成（またはメモリ上で解釈）
+
+### 案3: runner が decision_file の check_id を自動付与する
+
+`decision_file` が JSON で `decision` を含むが `check_id` が欠ける場合:
+
+- runner が現行 check_id を付与する（stale 防止は path/mtime 併用で担保）
+
+## 受け入れ条件
+
+- worker が shell を実行できない環境でも安定して completion_check が回る
+- structured decision が必須でも `check_id` mismatch で落ちない
+- 既存 workflow（PASS/FAIL, COMPLETE/INCOMPLETE）の後方互換を維持