takt 0.33.2 → 0.35.0

package/builtins/ja/facets/instructions/plan.md

@@ -20,6 +20,9 @@
    - 参照資料の内容と現在の実装を突き合わせて差分を特定する
    - **参照資料が外部実装を指す場合、「バグ修正の手がかり」か「採用すべき設計アプローチ」かを判断する。スコープを参照資料の意図より狭める場合は判断根拠を計画レポートに含めること**
    - **要件ごとに「変更要/不要」を判定する。「不要」の場合は現行コードの該当箇所（ファイル:行）を根拠として示すこと。根拠なしの「既に正しい」は禁止**
+   - **要件は、明示要求とそこから直接導ける暗黙要求に限定する。一般的ベストプラクティスや将来拡張を要件化しない**
+   - **要件を細分化するときは、検証可能にするための分解に留める。細分化から新しい要求へ飛躍しない**
+   - **暗黙要求を置く場合は、その根拠となる明示要求を計画レポートで示す**
 3. コードを調査して不明点を解決する
 4. 影響範囲を特定する
 5. ファイル構成・設計パターンを決定する（必要な場合）

package/builtins/ja/facets/instructions/review-requirements.md

@@ -14,14 +14,19 @@
 
 **前回指摘の追跡（必須）:**
 - まず「Previous Response」から前回の open findings を抽出する
-- 各 finding に `finding_id` を付け、今回の状態を `new / persists / resolved` で判定する
+- 各 finding に `finding_id` を付け、今回の状態を `new / persists / resolved / reopened` で判定する
 - `persists` と判定する場合は、未解決である根拠（ファイル/行）を必ず示す
 
 ## 判定手順
 
-1. レビュー対象レポート・タスクから要件を1つずつ抽出する
-2. 各要件について、実装されたコード（ファイル:行）を特定する
-3. コードが要件を満たしていることを確認する
-4. 要求にない変更がないかチェックする
-5. 検出した問題ごとに、Policy のスコープ判定表と判定ルールに基づいてブロッキング/非ブロッキングを分類する
-6. ブロッキング問題（`new` または `persists`）が1件でもあれば REJECT と判定する
+1. `order.md`、関連タスク本文、`plan.md`、`coder-decisions.md` を読み、要件を1つずつ抽出する
+2. 1つの文に複数条件や経路がある場合、検証可能な最小単位まで分解する
+   - `A/B`、`global/project`、`JSON/leaf`、`allow/deny`、`read/write` を1行にまとめない
+3. 各要件について、実装されたコード（ファイル:行）を特定する
+4. 各要件を `充足 / 未充足 / 未確認` のいずれかで判定する
+   - 根拠コードがない場合は `充足` にしない
+   - 一部ケースしか確認できていない場合は `充足` にしない
+5. 要求にない変更を列挙し、妥当か不要かを判定する
+6. 前回 finding を `new / persists / resolved / reopened` で整理する
+7. 検出した問題ごとに、Policy のスコープ判定表と判定ルールに基づいてブロッキング/非ブロッキングを分類する
+8. ブロッキング問題（`new`、`persists`、または `reopened`）が1件でもあれば REJECT と判定する

package/builtins/ja/facets/instructions/supervise.md

@@ -21,7 +21,7 @@
    - コードが要件を満たしていることを実際に確認する（ファイルを読む、実行済みテストやビルドの証跡を確認する）
    - 片側のケースだけを確認して複合要件全体を ✅ にしてはいけない
    - 根拠は、その要件行の内容全体をカバーしている必要がある
-   - 計画レポートの判断を鵜呑みにせず、要件ごとに独立照合する
+   - 計画レポートや requirements-review の判断を鵜呑みにせず、要件ごとに独立照合する
    - 充足していない要件が1つでもあれば REJECT する
 4. 前段レビューの finding を再評価する
    - 各 `new / persists / resolved` を、指示書・`plan.md`・`coder-decisions.md`・実コードで照合する
@@ -31,7 +31,7 @@
 5. テスト・ビルド・動作確認の扱い
    - このムーブメントでコマンドを再実行する前提で書かない
    - 実行ログ、レポート、CI結果など、この run で確認できる証跡だけを使う
-   - 証跡がない項目は「未確認」と明記する
+   - 証跡がない項目は「未確認」と明記し、成功扱いにしない
    - レポート本文と実行証跡が矛盾する場合は、その矛盾自体を指摘する
 
 **レポートの確認:** Report Directory内の全レポートを読み、
@@ -54,6 +54,7 @@
 
 - ❌ が1件でもある場合は REJECT 必須
 - 根拠なしの ✅ は無効（実コードで確認すること）
+- 一部ケースしか確認できていない場合は ✅ にしない
 - 計画レポートの判断を鵜呑みにせず、要件ごとに独立照合する
 
 ## 前段 finding の再評価
@@ -64,6 +65,7 @@
 
 - 前段レビューの結論と最終判定が異なる場合は、必ず根拠を書く
 - false_positive / overreach を判定した場合は、task と plan のどちらに照らして不適切か明記する
+- requirements-review の結論を覆す場合は、その理由を必ず根拠付きで明記する
 
 ## 検証サマリー
 | 項目 | 状態 | 確認方法 |

package/builtins/ja/facets/instructions/team-leader-implement.md

@@ -22,8 +22,9 @@
      - **実装内容**（何をどのように実装するか）
      - **完了基準**（担当ファイルの実装が完了したこと）
    - テスト済みの場合は「既存テストがパスするよう実装する」と明記する
-   - ビルドチェックは指示しない（他パートのファイルが揃ってから全体でまとめて確認するため）
+   - 品質ゲート（Quality Gates）を参照し、必要な検証は専用の単独パートとして計画する
+   - 並列の実装パートには、全体ビルド・全体テストを重複して実行させない
 
 **制約:**
-- 各パートはテスト実行を行わない（後続ムーブメントで実施する）
+- テストやビルドが必要な場合は、他パートの変更が揃った後に、単独の検証パートで実行する
 - 担当外のファイルを変更しない（コンフリクトの原因になる）

package/builtins/ja/facets/knowledge/architecture.md

@@ -104,6 +104,99 @@ Vertical Slice の判定基準:
 - エラーハンドリングが一元化されているか（各所でtry-catch禁止）
 - ビジネスロジックがController/Viewに漏れていないか
 
+## 境界での解決
+
+設定、Option、provider、権限、パスのような値は、境界で解決してから内部へ渡す。メイン処理は「何が解決済みか」を前提に組み立て、各所で設定ソースを問い合わせない。
+
+| 基準 | 判定 |
+|------|------|
+| 入口で `ExecutionContext` や `ResolvedOptions` のような解決済みオブジェクトを作る | OK |
+| オーケストレーション層が解決済みの値だけを扱う | OK |
+| 下位層が global/project/env を再読込して同じ値を再解決する | REJECT |
+| 表示用と実行用で別々の解決関数を持つ | REJECT |
+| 未解決の options を深い層まで運び、先で `??` 解決する | REJECT |
+
+```typescript
+// REJECT - 実行層が設定ソースを直接知っている
+async function executePiece(options) {
+  const engine = new PieceEngine({
+    provider: options.provider ?? globalConfig.provider,
+  });
+}
+
+class AgentRunner {
+  run(step, options) {
+    const provider = options.provider ?? resolveProviderFromConfig();
+    return getProvider(provider).call();
+  }
+}
+
+// OK - 境界で解決し、内部は解決済み値を使う
+async function executePiece(options) {
+  const context = resolveExecutionContext(options);
+  const engine = new PieceEngine(context);
+}
+
+class AgentRunner {
+  run(step, options) {
+    return getProvider(options.resolvedProvider).call();
+  }
+}
+```
+
+### Tell, Don't Ask
+
+下位層に設定ソースを問い合わせさせるのではなく、上位層が「これを使え」と解決済みの値を渡す。値の選択責務と実行責務を分離する。
+
+| パターン | 判定 |
+|---------|------|
+| 上位層が `resolvedProvider` のような値を渡す | OK |
+| 下位層が `options` を覗いて自前で解決する | REJECT |
+| 実行オブジェクトが `setup(config)` 後は `run()` だけ公開する | OK |
+| 実行中に `getGlobalConfig()` を呼んで分岐する | REJECT |
+
+### 腐敗防止層
+
+優先順位解決や外部設定形式の吸収は、境界の専用層に閉じ込める。内部モデルへは正規化済みの値だけを渡す。
+
+| パターン | 判定 |
+|---------|------|
+| YAML/env/CLI 差分を resolver/adapter に閉じ込める | OK |
+| ドメイン層が env 名や設定キー文字列を直接扱う | REJECT |
+| 外部形式から内部形式への変換が1箇所に集約されている | OK |
+| 同じ正規化ロジックが複数箇所にコピーされている | REJECT |
+
+### フェーズ分離
+
+入力、解釈、実行、出力を段階で分ける。反復処理は、できる限り「解釈済みの入力をまとめて受け取り、実行だけを繰り返す」構造にする。
+
+| 基準 | 判定 |
+|------|------|
+| 入口で raw input を `Resolved*` 型へ変換してから本処理に渡す | OK |
+| ループ本体が解決済みデータに対する実行だけを担う | OK |
+| ループ内で毎回 config/env/option を解釈する | REJECT |
+| 反復ごとに「入力取得→解釈→実行→出力」を1関数に詰め込む | REJECT |
+| 最適化で逐次処理が必要でも、解釈フェーズを専用メソッドに隔離している | OK |
+
+```typescript
+// REJECT - 各反復が入力解釈まで担う
+for (const item of items) {
+  const resolved = resolveItem(item, rawOptions, config);
+  const result = execute(resolved);
+  output(result);
+}
+
+// OK - 先に解釈し、反復は実行だけ
+const resolvedItems = items.map((item) => resolveItem(item, rawOptions, config));
+
+for (const item of resolvedItems) {
+  const result = execute(item);
+  output(result);
+}
+```
+
+逐次解釈が必要なケースでも、`nextRawInput()` と `resolveInput()` と `executeResolved()` の責務は分ける。性能要件でフェーズを近づけても、責務まで混ぜない。
+
 ## コード品質の検出手法
 
 **説明コメント（What/How）の検出基準**

package/builtins/ja/facets/knowledge/cqrs-es.md

@@ -291,7 +291,7 @@ Controller → UseCase → CommandGateway → Aggregate
 UseCaseが必要なケース:
 - コマンド発行前にRead Modelから他集約の状態を確認する
 - 複数のバリデーションを直列に実行する
-- コマンド送信後の結果整合性を待機する（ポーリング等）
+- コマンド送信後の結果整合性を待機する（リアクティブポーリング）
 
 UseCaseが不要なケース:
 - Controllerからコマンドを1つ送るだけで完結する単純な操作
@@ -301,6 +301,7 @@ UseCaseが不要なケース:
 | ControllerがRepository直接参照してバリデーション | UseCase層に分離 |
 | UseCaseがHTTPリクエスト/レスポンスに依存 | REJECT。UseCaseはプロトコル非依存 |
 | UseCaseがAggregate内部状態を直接変更 | REJECT。CommandGateway経由 |
+| UseCaseがSubscription Queryで結果を待機 | REJECT。分散環境で動作しない。リアクティブポーリングを使う |
 
 ## プロジェクション設計
 
@@ -370,12 +371,25 @@ class InventoryReleaseHandler(private val commandGateway: CommandGateway) {
 
 ## Query側の設計
 
-ControllerはQueryGatewayを使う。Repositoryを直接使わない。
+Query側はイベント駆動のPubSubモデルで動作する。Projection が EventHandler でRead Modelを更新し、Query側はRead Modelを参照する。
+
+イベント配信はPubSub（メッセージブローカー経由）で全インスタンスに配信する。同一インスタンスへの配信を前提とする仕組みは使わない。
+
+- **Subscription Query**（たとえばAxonの `subscriptionQuery()`）: クエリ結果の変更通知を購読元インスタンスに返す仕組みだが、分散配置やサードパーティのイベントストアプラグイン使用時に、購読を発行したインスタンスと通知を受け取るインスタンスが異なり、同一筐体でレスポンスを返せない。同期的な応答が必要な場合はリアクティブポーリングで Read Model の更新を待機する。
+- **Subscribing イベントプロセッサ**（たとえばAxonの `SubscribingEventProcessor`）: ローカルのイベントバスからの直接購読に依存し、イベントを発行したインスタンスのみがイベントを受け取る。分散環境では他インスタンスの Projection が更新されない。PubSubで全インスタンスにイベントが配信される構成にする。
+
+| 基準 | 判定 |
+|------|------|
+| Subscription Query（たとえばAxonの `subscriptionQuery()`）の使用 | REJECT。分散環境で動作しない。リアクティブポーリングを使う |
+| Subscribing イベントプロセッサ（たとえばAxonの `SubscribingEventProcessor`）の使用 | REJECT。ローカル配信のみ。分散環境で他インスタンスが更新されない |
+| Controller から Repository を直接参照 | REJECT。UseCase層を経由 |
+| Query側が Command Model を参照 | REJECT |
+| QueryHandler がコマンドを発行 | REJECT |
 
 レイヤー間の型:
 - `application/query/` - Query結果の型（例: `OrderDetail`）
 - `adapter/protocol/` - RESTレスポンスの型（例: `OrderDetailResponse`）
-- QueryHandlerはapplication層の型を返し、Controllerがadapter層の型に変換
+- QueryHandler は application層の型を返し、Controller が adapter層の型に変換
 
 ```kotlin
 // application/query/OrderDetail.kt
@@ -399,7 +413,7 @@ fun handle(query: GetOrderDetailQuery): OrderDetail? {
     return OrderDetail(...)
 }
 
-// Controller - adapter層の型に変換
+// Controller - 単純な参照は同期返却で十分
 @GetMapping("/{id}")
 fun getById(@PathVariable id: String): ResponseEntity<OrderDetailResponse> {
     val detail = queryGateway.query(
@@ -416,16 +430,62 @@ fun getById(@PathVariable id: String): ResponseEntity<OrderDetailResponse> {
 Controller (adapter) → QueryGateway → QueryHandler (application) → Repository
      ↓                                      ↓
 Response.from(detail)                  OrderDetail
+
+イベント流（PubSub）:
+Aggregate → Event Bus → Projection(@EventHandler) → Repository(Read Model)
+                                                          ↑
+                                          QueryHandler がここを参照
 ```
 
 ## 結果整合性
 
-| 状況 | 対応 |
+コマンド発行後に同期的なレスポンスが必要な場合、リアクティブポーリングで Projection の更新を待機する。
+
+| 基準 | 判定 |
 |------|------|
-| UIが即座に更新を期待している | 設計見直し or ポーリング/WebSocket |
+| Subscription Query で Projection 更新を待機 | REJECT。分散環境で動作しない。リアクティブポーリングを使う |
+| UIが即座に更新を期待している | ポーリング or WebSocket |
 | 整合性遅延が許容範囲を超える | アーキテクチャ再検討 |
 | 補償トランザクションが未定義 | 障害シナリオの検討を要求 |
 
+### リアクティブポーリング
+
+コマンド発行 → Projection更新完了をポーリングで待機するパターン。
+
+```kotlin
+// UseCase: コマンド送信 → ポーリングで完了待機
+fun execute(input: PlaceOrderInput): Mono<PlaceOrderOutput> {
+    val orderId = UUID.randomUUID().toString()
+    return Mono.fromCallable { validatePreConditions(input) }
+        .subscribeOn(Schedulers.boundedElastic())
+        .flatMap {
+            Mono.fromFuture(commandGateway.send<Any>(
+                PlaceOrderCommand(orderId, input.customerId, input.items)
+            ))
+        }
+        .then(pollForCompletion(orderId))
+        .thenReturn(PlaceOrderOutput(orderId))
+}
+
+// ポーリング: Projection の更新を待機
+private fun pollForCompletion(orderId: String): Mono<Void> {
+    return ReactivePolling.waitFor(
+        supplier = { orderRepository.findById(orderId).orElse(null) },
+        condition = { it.sagaCompleted || it.status == OrderStatus.CONFIRMED },
+        timeout = Duration.ofSeconds(60),
+        maxAttempts = 300
+    )
+}
+```
+
+ポーリングが適切なケース:
+- Saga が完了するまでレスポンスを返したくない場合
+- コマンド発行後に作成されたリソースのIDを返す場合
+
+ポーリングが不要なケース:
+- コマンド発行だけで完了する単純な操作（結果を待たない）
+- UIがリアルタイム更新を必要としない場合
+
 ## Saga vs EventHandler
 
 Sagaは「競合が発生する複数アグリゲート間の操作」にのみ使用する。

package/builtins/ja/facets/output-contracts/plan.md

@@ -9,6 +9,14 @@
 ### 目的
 {達成すべきこと}
 
+### 分解した要件
+| # | 要件 | 種別 | 備考 |
+|---|------|------|------|
+| 1 | {要件1} | 明示 / 暗黙 | {複合要件を分解した場合の補足} |
+
+- 1つの文に複数条件がある場合、検証可能な最小単位まで分解する
+- `A/B`、`global/project`、`JSON/leaf`、`allow/deny`、`read/write` のような並列表現は別行にする
+
 ### 参照資料の調査結果（参照資料がある場合）
 {参照資料の実装アプローチの概要と、現在の実装との主要な差異}
 

package/builtins/ja/facets/output-contracts/requirements-review.md

@@ -7,17 +7,19 @@
 {1-2文で結果を要約}
 
 ## 要件照合
-| # | 要件（タスクから抽出） | 充足 | 根拠（ファイル:行） |
-|---|-------------------|------|-------------------|
-| 1 | {要件1} | ✅/❌ | `src/file.ts:42` |
+| # | 要件（タスクから抽出） | 状態 | 根拠（ファイル:行） | コメント |
+|---|-------------------|------|-------------------|----------|
+| 1 | {要件1} | 充足 / 未充足 / 未確認 | `src/file.ts:42` | {補足} |
 
-- ❌ が1件でもある場合は REJECT 必須
-- 根拠なしの ✅ は無効（実コードで確認すること）
+- 1つの文に複数条件がある場合、検証可能な最小単位まで分解して複数行にする
+- `未充足` が1件でもある場合は REJECT 必須
+- 根拠なしの `充足` は無効（実コードで確認すること）
+- 一部ケースしか確認できていない場合は `充足` にしない
 
 ## スコープチェック
-| # | 要求外の変更 | ファイル | 妥当性 |
-|---|-------------|---------|--------|
-| 1 | {要求にない変更} | `src/file.ts` | 妥当/不要 |
+| # | 要求外の変更 | ファイル | 妥当性 | コメント |
+|---|-------------|---------|--------|----------|
+| 1 | {要求にない変更} | `src/file.ts` | 妥当 / 要再確認 / 不要 | {理由} |
 
 ## 今回の指摘（new）
 | # | finding_id | family_tag | カテゴリ | 場所 | 問題 | 修正案 |

package/builtins/ja/facets/output-contracts/supervisor-validation.md

@@ -19,6 +19,14 @@
 - 一部ケースしか根拠がない場合は ✅ にしない
 - 計画レポートの判断を鵜呑みにせず、要件ごとに独立照合する
 
+## 前段 finding の再評価
+| finding_id | 前段判定 | 再評価 | 根拠 |
+|------------|----------|--------|------|
+| {id} | new / persists / resolved | 妥当 / false_positive / overreach | `src/file.ts:42`, `reports/plan.md` |
+
+- 前段レビューの結論と最終判定が異なる場合は、必ず根拠を書く
+- false_positive / overreach を判定した場合は、task と plan のどちらに照らして不適切か明記する
+
 ## 検証サマリー
 | 項目 | 状態 | 確認方法 |
 |------|------|---------|

package/builtins/ja/facets/personas/planner.md

@@ -20,6 +20,8 @@
 - 調査してから計画する。既存コードを読まずに計画を立てない
 - 推測で書かない。名前・値・振る舞いは必ずコードで確認する。「不明」で止まらない
 - シンプルに設計する。過度な抽象化や将来への備えは不要
+- 要件は、明示要求とそこから直接導ける暗黙要求に限定する。一般論や好みを要件化しない
+- 要件を細分化するときは検証可能な最小単位までに留め、そこから新しい要求へ飛躍しない
 - 確認が必要な場合は質問を一度にまとめる。追加の確認質問を繰り返さない
 - 後方互換コードは計画に含めない。明示的な指示がない限り不要
 - 実装方法を指定する前に、ナレッジ・ポリシーの制約を確認する。制約に反する実装方法を指示書に書かない
@@ -69,6 +71,12 @@
 
 タスク指示書に明記された作業のみを計画する。暗黙の「改善」を勝手に含めない。
 
+**要件分解の規律:**
+- 明示要求から直接導ける暗黙要求は計画に含めてよい
+- 暗黙要求を置く場合は、どの明示要求から導いたかを説明できること
+- 一般的ベストプラクティス、将来あるとよい拡張、好みの一貫性は要件として追加しない
+- 要件の細分化は、検証可能にするための分解であって、要求追加ではない
+
 **削除の判断基準:**
 - **今回の変更で新たに未使用になったコード** → 削除を計画してよい（例: リネームした旧変数）
 - **既存の機能・フロー・エンドポイント・Saga・イベント** → タスク指示書で明示的に指示されない限り削除しない

package/builtins/ja/facets/personas/requirements-reviewer.md

@@ -20,7 +20,14 @@
 ## 行動姿勢
 
 - 要求を1つずつ照合する。まとめて「概ね充足」とは言わない
+- 1つの文に複数条件がある場合、検証可能な最小単位まで分解してから照合する
+- `A/B`、`global/project`、`JSON/leaf`、`allow/deny`、`read/write` のような並列表現を1件として扱わない
 - 実コードで確認する。「実装しました」を鵜呑みにしない
+- 片側ケースだけ確認して充足扱いしない。複合要件は全ケースを確認する
+- 根拠のない「充足」を書かない。各判定に対応するファイル:行を示す
+- 証跡不足で確認できない場合は「未確認」と扱い、「未実装」と混同しない
 - スコープを守る。要求にない変更は理由を問う
+- 要求にない変更は、存在だけでなく妥当性まで判定する
 - 曖昧さを放置しない。仕様が不明確なら指摘する
 - 削除に注目する。ファイルやコードの削除が要求に基づくか確認する
+- `plan.md` や `coder-decisions.md` は参照してよいが、最終根拠は必ず実コードと差分に置く

package/builtins/ja/facets/personas/supervisor.md

@@ -21,10 +21,14 @@
 
 - 実行証跡を確認する。ファイルだけでなく、ログ・レポート・結果を突き合わせる
 - 要求と照合する。元のタスク要求を再度読み、漏れがないか確認する
+- 複合要件は自分で再分解する。前段レビューの分解をそのまま採用しない
+- `requirements-review` の結果は参考情報として扱い、最終判定は自分で再検算する
 - 鵜呑みにしない。「完了しました」を信用せず、自分で検証する
 - 具体的に指摘する。「何が」「どう」問題かを明確にする
 - あなたは最後の門番。「たぶん大丈夫」では通さない
 - 実行していないコマンド結果を推測で書かない。証跡がなければ未確認として扱う
+- レポート本文と実行証跡が矛盾する場合は、矛盾自体を最優先の問題として扱う
+- false positive と overreach を区別する。成立しない指摘と、範囲外の指摘を同じ扱いにしない
 
 ## ドメイン知識
 
@@ -48,6 +52,7 @@
 **要求の充足（最重要）:**
 
 - 全要件を個別に検証し、1件でも未充足なら APPROVE しない
+- 1つの文に複数条件がある場合、検証可能な最小単位まで分解して個別に確認する
 - 「~もできる」と言っていたことが本当にできるか
 - 暗黙の要求（当然期待される動作）が満たされているか
 - 「概ね完了」「主要部分は完了」は APPROVE の根拠にならない。全要件の充足が必要
@@ -68,6 +73,7 @@
 - 実行ログ・レポート・CI結果など、この run で確認できる証跡のみを根拠に使う
 - 実行証跡がない場合は「未確認」と明記し、勝手に成功/失敗にしない
 - レポート本文と実行証跡が矛盾する場合は、矛盾自体を指摘して REJECT する
+- `未確認` は `未実装` や `成功` に読み替えない
 
 **エッジケース・エラーケース:**
 

package/builtins/ja/facets/policies/coding.md

@@ -77,6 +77,93 @@ function createEngine(config, cwd: string) {
 3. **上位から値を渡す経路があるか？** → なければ引数・フィールドを追加
 4. **関連する値に不変条件があるか？** → ロード・セットアップ時にクロスバリデーションする
 
+## 解決責務の一元化
+
+設定、Option、provider、パス、権限のような「早い段階で決められる値」は、境界で一度だけ解決する。同じ値を複数の層で再解決しない。
+
+| パターン | 判定 | 理由 |
+|---------|------|------|
+| 入口で解決した値を下位層へ明示的に渡す | OK | 値の出所が追える |
+| 解決専用のメソッド/オブジェクトに委譲する | OK | SSOTが保たれる |
+| 上位と下位で同じ設定を別々に解決する | REJECT | 優先順位のズレを生む |
+| ログ表示用と実行用で別々に解決する | REJECT | 表示と挙動が乖離する |
+| メイン処理内で `if` を重ねて設定解決する | REJECT | オーケストレーションに詳細が漏れる |
+
+```typescript
+// REJECT - 各層がそれぞれ設定を解決
+function executeTask(options) {
+  const provider = options.provider ?? loadGlobalConfig().provider;
+  return runAgent({
+    provider,
+    stepProvider: resolveProviderForStep(options.step),
+  });
+}
+
+function runAgent(options) {
+  const provider = options.provider ?? resolveProviderFromConfig();
+  return getProvider(provider).call();
+}
+
+// OK - 境界で解決し、以降は解決済みの値だけを使う
+function executeTask(options) {
+  const resolved = resolveExecutionContext(options);
+  return runAgent({
+    resolvedProvider: resolved.provider,
+    resolvedModel: resolved.model,
+  });
+}
+
+function runAgent(options) {
+  return getProvider(options.resolvedProvider).call();
+}
+```
+
+判断基準:
+1. この値は実行前に確定できるか？ → できるなら境界で解決する
+2. 同じ優先順位ロジックが2箇所以上にあるか？ → 専用メソッド/オブジェクトに集約する
+3. 下位層が設定ソースそのものを知っているか？ → 解決済みの値だけを渡す
+4. 表示・実行・保存で別々に解決しているか？ → 同じ解決結果を共有する
+
+## フェーズ分離
+
+入力の収集、解釈・正規化、実行、出力・副作用は段階で分ける。ループやメイン処理の途中で未解決の入力を受け取り直して、その場で解釈しない。
+
+| パターン | 判定 | 理由 |
+|---------|------|------|
+| `RawOptions -> ResolvedOptions -> ExecutionContext` の順で段階を分ける | OK | 各段階の責務が明確 |
+| ループ前に入力をまとめて正規化する | OK | 各反復が同じ前提で動く |
+| ループ内で毎回 `options ?? config ?? env` を解決する | REJECT | 各反復の前提が揺れる |
+| 反復ごとに入力解釈と実行ロジックが混在する | REJECT | 処理の意図が読めない |
+| 1件ずつ「入力→解釈→実行→出力」を繰り返すしかない場合でも、解釈処理を専用メソッドに隔離する | OK | 最低限の責務分離を保てる |
+
+```typescript
+// REJECT - ループ内で毎回入力を解釈
+for (const step of steps) {
+  const provider = options.provider
+    ?? step.provider
+    ?? projectConfig.provider
+    ?? globalConfig.provider;
+  const result = await executeStep(step, { provider });
+  printResult(result);
+}
+
+// OK - 先に解決し、ループ内は実行だけ
+const context = resolveExecutionContext(rawOptions, steps);
+
+for (const step of context.steps) {
+  const result = await executeStep(step, {
+    resolvedProvider: step.resolvedProvider,
+  });
+  printResult(result);
+}
+```
+
+判断基準:
+1. ループ内の分岐は「業務判断」か「入力解釈」か？ → 入力解釈ならループ外へ出す
+2. 同じ入力解釈が各反復で繰り返されているか？ → 先にまとめて正規化する
+3. 実行関数が raw input を直接受け取っているか？ → `Resolved*` 型へ変換してから渡す
+4. 最適化で逐次処理が必要か？ → 解釈だけでも先に関数へ抽出する
+
 ## 抽象化
 
 ### 条件分岐を追加する前に考える

package/builtins/ja/{piece-categories.yaml → workflow-categories.yaml}

@@ -1,38 +1,38 @@
-piece_categories:
+workflow_categories:
   🚀 クイックスタート:
-    pieces:
+    workflows:
       - default
       - frontend-mini
       - backend-mini
       - compound-eye
   ⚡ Mini:
-    pieces:
+    workflows:
       - frontend-mini
       - backend-mini
       - backend-cqrs-mini
       - dual-mini
       - dual-cqrs-mini
   🎨 フロントエンド:
-    pieces:
+    workflows:
       - frontend
       - frontend-mini
   ⚙️ バックエンド:
-    pieces:
+    workflows:
       - backend
       - backend-mini
       - backend-cqrs
       - backend-cqrs-mini
   🔧 デュアル:
-    pieces:
+    workflows:
       - dual
       - dual-mini
       - dual-cqrs
       - dual-cqrs-mini
   🏗️ インフラストラクチャ:
-    pieces:
+    workflows:
       - terraform
   🔍 レビュー:
-    pieces:
+    workflows:
       - review-default
       - review-fix-default
       - review-frontend
@@ -55,12 +55,12 @@ piece_categories:
       - audit-architecture-backend
       - audit-architecture-dual
   🎵 TAKT開発:
-    pieces:
+    workflows:
       - takt-default
       - review-takt-default
       - review-fix-takt-default
   その他:
-    pieces:
+    workflows:
       - research
       - deep-research
       - magi

package/builtins/ja/{pieces → workflows}/audit-architecture-backend.yaml

@@ -1,7 +1,7 @@
 name: audit-architecture-backend
 description: バックエンド特化のアーキテクチャ監査。サービスモジュールと境界を列挙し、コードを変更せずに Issue 化しやすいレポートを作成する
-max_movements: 12
-initial_movement: plan
+max_steps: 12
+initial_step: plan
 
 loop_monitors:
   - cycle: [supervise, review]
@@ -17,7 +17,7 @@ loop_monitors:
         - condition: Quality is insufficient with no prospect of improvement
           next: ABORT
 
-movements:
+steps:
   - name: plan
     persona: planner
     knowledge:

package/builtins/ja/{pieces → workflows}/audit-architecture-dual.yaml

@@ -1,7 +1,7 @@
 name: audit-architecture-dual
 description: フルスタックのアーキテクチャ監査。frontend/backend の境界と横断配線を列挙し、コードを変更せずに Issue 化しやすいレポートを作成する
-max_movements: 12
-initial_movement: plan
+max_steps: 12
+initial_step: plan
 
 loop_monitors:
   - cycle: [supervise, review]
@@ -17,7 +17,7 @@ loop_monitors:
         - condition: Quality is insufficient with no prospect of improvement
           next: ABORT
 
-movements:
+steps:
   - name: plan
     persona: planner
     knowledge:

package/builtins/ja/{pieces → workflows}/audit-architecture-frontend.yaml

@@ -1,7 +1,7 @@
 name: audit-architecture-frontend
 description: フロントエンド特化のアーキテクチャ監査。UIモジュールと境界を列挙し、コードを変更せずに Issue 化しやすいレポートを作成する
-max_movements: 12
-initial_movement: plan
+max_steps: 12
+initial_step: plan
 
 loop_monitors:
   - cycle: [supervise, review]
@@ -17,7 +17,7 @@ loop_monitors:
         - condition: Quality is insufficient with no prospect of improvement
           next: ABORT
 
-movements:
+steps:
   - name: plan
     persona: planner
     knowledge: