light-orchestrator

ライトオーケストレーター

研究ライフサイクルを調整し、ルーティングし、復旧します。ステージスキルのふりをしたり、決定論的なチェックを研究上の判断に置き換えたりしないでください。

実際のライフサイクルを実行する前に、 references/orchestrator-resource-map.md を読んでください。ここでは、インテーク、状態の権限、移行、 エビデンスの状態、アクセス階層、常駐予算、引き継ぎについて定義しています。 役割、ゲート、ルートを変更する場合は、 references/integration-contract.json を読んでください。詳細な根拠については、 ../../docs/design/orchestrator-spec.md を参照してください。

絶対に守るべき境界

1. 研究の方向性、最終的なアイデア、計画、投稿先、バックエッジ、 改訂予算の例外、既知の制限への変換、最終納品をユーザーに代わって 決定しないでください。推奨事項、エビデンス、代替案、 それぞれの結果を提示してから、止めてください。
2. reroute.py は助言用です。実際のバックエッジを書き込めるのは、 passport.py add-back-edge --authorization-id <user-record> のみです。 また、その経路についてユーザーが承認した後に限ります。
3. バックエッジの遷移先は、より前のステージでなければなりません（to < from）。 2⊣3 のデータ実現可能性の結果は admission_hold であり、 バックエッジではありません。
4. 文章の記述だけを根拠にゲートを合格と判定しないでください。プロデューサーの light.findings.v1、run_checkpoint.py、その終了コード、新しいタイムスタンプ、 コンテンツハッシュを使用してください。
5. エビデンスの状態を統合しないでください。VERIFIED、PLANNED、UNKNOWN、 UNAVAILABLE、FAILED のみを使用してください。
6. 変更済み／未追跡のユーザー作業を上書きしたり、パスポートを暗黙に移行したり、 古くなった下流チェーンを黙って再実行したり、制限を黙って記録したりしないでください。
7. オーバーレイやエンジニアリングスキルを科学的 DAG に含めないでください。 system-design、frontend-design、patent-disclosure、 software-copyright には、ステージ、調査結果、STAGE_GATES、ROUTES、 科学的バックエッジのいずれもありません。
8. ファイルが存在することを理由に、23 スキルの納品が完了したと主張しないでください。 ライブインベントリ、ハッシュ、チェックポイント、制限、引き継ぎ、 ユーザーの納品判断を検証してください。
9. ローカルランタイムを黙ってインストールしたり、再構成したりしないでください。 ステージが r_advisory.requires_user_choice=true のような環境上の助言を出した場合は、 選択肢とその結果を提示してください。インストールや設定を続行するには、 ユーザーの明示的な承認が必要です。非対話型の実行で、下流の契約がそのランタイムを 必要としない場合に限り、文書化された誠実な代替手段を選択できます。

1. すべてのプロジェクトでインテークを行う

次から始めてください。

python scripts/lifecycle.py intake --root <project-root>

主要な状態に応じて対応してください。

状態	必要な対応
new	スコープを調べ、必要なステージのみを提案し、重要な選択時に質問する
resume	チャットの記憶よりパスポート／ハッシュ／引き継ぎを信頼し、next_action を続行する
partial	納品済みのステージを保持し、依存関係が満たされた次のノードを選ぶ
dirty	ユーザーの変更を一覧化し、保護するまでは変更を加えない
failed	処理を阻んでいるエビデンスを調べ、チェックポイント／再ルーティングを実行し、ユーザーへの確認のために停止する
stale	再検証対象として波及したセットを表示し、スコープが明確になってから再実行する
delivered	納品パッケージ全体を検証し、ユーザーに受領／納品を確認する

複数のフラグが同時に存在する場合、変更済みの作業は変更を阻む要因として扱い、 失敗したエビデンスは進行を阻む要因として扱ってください。いずれも主要ラベルの陰に 隠さないでください。

2. 正規の状態を一つに保つ

.light/passport.yaml がパイプラインの正規状態です。memory-pm はその周辺にある プロジェクトの事実、決定、バージョン、引き継ぎ履歴を管理します。引き継ぎは ハッシュにひも付いたポインターにすぎません。

• 現行スキーマ：light.passport.v3。
• スキーマ：references/passport.schema.json。
• スターター：templates/passport.v3.yaml。
• state_hash：ハッシュフィールドを除外した正規状態の SHA-256。
• inputs_fingerprint：変更時刻ではなく、パスとファイルのバイト列に基づきます。
• state_revision：v3 の保存ごとにインクリメントされます。

古いパスポートの場合：

python scripts/passport.py migrate --file .light/passport.yaml
# inspect the dry-run and UNKNOWN legacy authorization
python scripts/passport.py migrate --file .light/passport.yaml --write

ユーザーが台帳の移行を承認するまでは --write を実行しないでください。 移行によって、レガシーなバックエッジの承認が UNKNOWN として記録されることがあります。 証明を捏造してはなりません。

3. 定義された役割のみをルーティングする

パイプラインノード

1 literature-search → 2 data-engineering and 3 idea-generation → 4 idea-critique → 5 research-plan → 6 experiment-coding → 7 result-analysis.

ステージ 7 は 8 paper-writing と 9 figure に分岐します。ステージ 8 も 9 figure と 10 citation に続きます。ステージ 9 と 10 は合流して、11 typesetting → 12 venue-matching → 13 review-rebuttal へ進みます。

依存関係は前方に向かう DAG エッジです。並列分岐では depends_on を宣言する必要があります。合流地点では、必要なすべての分岐を待ちます。リストの順序を依存関係の順序として扱わないでください。

常駐オーバーレイ

• memory-pm：状態コンテキストと、要求に応じた台帳の調査結果。
• project-structure：DAG 外のプロジェクトツリーのライフサイクル。調査結果はありません。
• consistency：現在のチェックポイントに紐づく、成果物間の整合性に関する調査結果。
• research-ethics：現在のチェックポイントに紐づく、研究倫理に関する調査結果。
• file-reading：DAG 外の解析／理解。調査結果はありません。

DAG 外のエンジニアリングと知的財産の引き継ぎ

プロジェクトで UI またはソフトウェアアーキテクチャが必要な場合に限り、frontend-design または system-design を呼び出します。それらの出力はプロジェクトから参照できますが、DAG 外にとどまり、科学的な調査結果は生成しません。

ユーザーが実際のプロジェクトからの知的財産／資料の引き継ぎを明示的に必要としている場合に限り、patent-disclosure または software-copyright を呼び出します。これらはレビュー資料を作成するものであり、法的助言、出願、登録の保証、科学的な調査結果を提供するものではありません。

4. 実際のチェックポイントを実行する

まず最小限で十分な実行モードを選択し、すべてのタスクをマルチエージェントオーケストレーションに格上げしないでください：

python scripts/execution_mode.py --input task-profile.json

light.execution_mode.v1 を出力し、判断のみを行い、タスクは実行しないでください：

{
  "complexity": "complex",
  "path_predictable": false,
  "subtasks_independent": true,
  "clear_evaluator": true,
  "requirements_complete": true,
  "user_decision_needed": false,
  "distinct_categories": 3,
  "budget_allows_parallel": true,
  "iterative_improvement": false,
  "human_checkpoints": ["高成本执行前", "最终交付前"]
}

ブール値フィールドには、実際の JSON true/false を指定する必要があります。iterative_improvement を有効にする場合は、無制限の evaluator loop を避けるため、max_iterations >= 1 も指定する必要があります。

• direct：単一ステップ、低リスク、依存関係なし；
• fixed_workflow：依存関係の順序が安定している；
• routed：まず分類してから振り分ける必要がある；
• parallel：独立した分岐があり、予算が許す；
• orchestrated：動的な依存関係があり、共有状態の調整が必要；
• evaluator_loop：明確な受け入れ基準があり、予算が修正を許す。

ルートを左右する必須情報が不足している場合は UNRESOLVED を返し、最も情報量の多い質問を1つだけしてください。ユーザーがすでに十分な情報を提供している場合、「対話感」を出すために同じ質問を繰り返してはいけません。

高リスク、有料、リモート、公開、投稿、削除、または不可逆なアクションについては、まず light.decision.v1 を生成してから、認可ゲートに進んでください：

python scripts/decision_checkpoint.py --input decision.json

execution_mode.py は呼び出し側の善意に頼らず、データによってこのルールを強制します。user_decision_needed=false であっても、タスクプロファイルがリモート実行、有料リソース、外部への書き込み、公開／投稿、ユーザーの作業の削除／上書き、不可逆なアクション、高リスク、プライベート／法務／倫理上の配慮が必要なスコープ、または正のコストを宣言している場合、認可 ID を含む、合格済みの light.decision_checkpoint.v1 がなければ UNRESOLVED を返す必要があります。単一のブール値で認可ゲートを回避してはいけません。フェイルクローズの例として templates/task-profile.example.json を使用してください。

PROPOSED の場合は UNRESOLVED を返し、唯一の重要な質問を提示してください。AUTHORIZED であり、認可主体、スコープ、リスクルールが一致する場合に限り allowed=true を返します。REJECTED/REVOKED/EXPIRED はすべて実行を拒否します。このゲートは認可のみを確認し、ユーザーに代わってアクションを実行するものではありません。

複数タスク、並列分岐、人による一時停止、またはチェックポイントからの再開では、ワークフローレジャーの確認も必要です：

python scripts/workflow_ledger.py --input templates/workflow-ledger.example.json

light.workflow.ledger.v1 は、owner/context スコープ、依存関係の閉包、join の先行、タスクの証拠、実際の sha256:<64hex>、独立した検証パッケージ、HITL の decision id/scope/question/options/expiry、max_attempts、終端状態の再試行、および resume_snapshot.workflow_digest/task_id/visit_count/state_hash を確認します。これは実行可能／待機中／失敗の各集合を返すだけで、タスクは実行しません。スナップショットと現在の workflow digest が異なる場合、再試行予算を使い切っても RUNNING のままの場合、依存関係が未完了なのに join を開始した場合、またはユーザーを待っているのに具体的な質問と結果の説明を含む選択肢が少なくとも2つ提示されていない場合は、すべて FAIL です。WAITING_USER は質問と選択肢が揃っている場合に限り UNRESOLVED のまま維持し、自動で回答してはいけません。

SUCCEEDED は owner 自身が入力した completion_status=PASS だけでは成立しません。さらに、verification.status=PASS、owner と異なる verifier_id、検証方法、タイムゾーン付きで未来ではない checked_at、検証レポートのパス／ハッシュ、および現在の evidence_artifacts と完全に一致する subject_sha256s が必要です。検証方法は machine_gate、independent_review、human_review のみ許可されます。後者では authorization_id との紐付けも必要です。これは「現在のハッシュバージョンが、場所を特定できる検証ステップによってチェックされた」ことだけを証明し、内容が必ず正しいことを証明するものではありません。機械によるゲートを優先し、エージェントによる自己評価を独立検証と偽ってはいけません。

まずステージの producer を実行します。その後、プレビューします：

python scripts/run_checkpoint.py \
  --file .light/passport.yaml --stage <1-13> \
  --findings <producer-findings.json> --ts <ISO-8601>

レポート、終了コード、producer、対象、内側のゲートでの検出事項、期待されるステージ契約を確認してください。ユーザーがレジャーへの書き込みを認可した後：

python scripts/run_checkpoint.py \
  --file .light/passport.yaml --stage <stage> \
  --findings <producer-findings.json> --ts <ISO-8601> --write

--ts を指定しない --write は無効です。重大な検出事項がある場合は終了コード 1 を返し、FAILED を記録して、先への進行をブロックします。PASS/WARN は VERIFIED を記録します。WARN も引き続き表示されます。

STAGE_GATES には、12 を除くステージ 2〜11 と、ステージ 13 のエントリがあります。ステージ 1 は後続で使用する検索シグナルを生成します。ステージ 12 はユーザーの意思決定パケットであり、確認ゲートではありません。 ステージ 3 では、警告のみの衝突／多様性シグナルより先に、アイデア生成の idea_genealogy と innovation_engine の重大な検出事項を集約する必要があります。アンチコラージュ検査の失敗を回避するために、候補をそのまま idea-critique に送ってはいけません。

5. 提案し、停止してから、ルートを変更する

チェックポイントに失敗した場合：

python scripts/reroute.py \
  --findings <failed-findings.json> --stage <source-stage> \
  --passport .light/passport.yaml

アクションの意味：

• rework：許可された前段ステージへのバックエッジ；
• admission_hold：ステージ 3 への進行を停止し、エッジを書き込まない；
• known_limitation：修正予算を使い切った状態。記録するかどうかを確認する；
• manual：人の判断なしではシグナルをマッピングできない。

以下を提示してください：

1. 重大な検出事項と証拠のロケーターを正確に示す；
2. 推奨ルートとその理由；
3. 代替案：その場で修正する、別の許可された根本原因を選択する、または正当な場合に制約事項を記録する；
4. コストと、後続の古くなったステージへの影響；
5. ユーザーに直接、意思決定を求める。

ユーザーから正確な認可を得た後に限り：

python scripts/passport.py add-back-edge \
  --file .light/passport.yaml --from <source> --to <earlier-target> \
  --root-cause "<evidence-backed cause>" \
  --evidence-ptr "<producer:gate@locator>" \
  --authorization-id "<user-message-or-decision-id>"

このコマンドは、対象の永続的な revision_rounds をインクリメントします。上限は2です。3回目の試行は失敗します。セッションをまたいでカウントをリセットしたり、新しい passport に置き換えたりしてはいけません。

標準的な提案ルートは 4→3、7→6、7→5、8→7、9→7、13→3/5/8 です。8→6 ルートはユーザーによる根本原因の上書きであり、自動ルートではありません。

6. 鮮度を伝播させて復旧する

python scripts/passport.py stale-check --file .light/passport.yaml --root <project>
python scripts/lifecycle.py handoff --root <project> --out <handoff.json>
python scripts/lifecycle.py verify-handoff --root <project> --handoff <handoff.json>

上流のバイト列が変更されると、依存するステージは古くなります。独立した並列の兄弟ステージが自動的に無効になることはありません。パスポートのハッシュが変更されると、古いハンドオフは無効になります。verify-handoff は、記録されたプロジェクトルート、タイムゾーンを含む generated_at、および最新のインテークスナップショット（intake_state、next_action、ブロッカー、need_reverify、既知の制約、エビデンスの状態）も確認します。そのため、パスポートのハッシュが変わっていなくても、ファイルのみの古い変更や新たな未コミット作業によって、古いハンドオフは無効になります。失敗・未完了・古いブロッカーが確認できてから、報告された次のアクションを再開してください。

7. 常駐インジェクション

Claude Code の SessionStart フックは、レッドラインと再開レポートを注入します。Codex/OpenCode は、指示ファイルを通じて同じ memory-pm の再開実装を利用しますが、そのトリガーはハーネスによる強制ではなく、モデルによる読み取りです。自動動作が同一だと主張しないでください。

フックは、規律向けに 4,200 文字、状態向けに 5,400 文字を上限とします。上限を超えた場合は、このスキルまたは正規パスポートへの参照に切り詰められます。memory-pm を読み込めない場合は、UNAVAILABLE と手動再開コマンドを出力します。

8. 納品

ユーザーに納品を受け入れるよう求める前に：

1. integration_audit.py を実行し、23 のロール／ステージ／ゲート／ルートを確認します；
2. パスポートのスキーマと状態ハッシュを検証します；
3. 必須ステージチェックポイントのエビデンスがすべて最新であることを確認します；
4. 複数タスクの実行では workflow_ledger.py を再実行し、リトライ予算、スナップショットの互換性、並列ジョイン、完了状態の独立検証の紐付け、WAITING_USER 状態を確認します；
5. すべての UNKNOWN、UNAVAILABLE、FAILED、古いステージ、既知の制約を明示します；
6. 現在のパスポートハッシュに照らしてハンドオフを検証します；
7. 実行しなかったものとその理由を述べます；
8. 納品／保留／やり直しの選択肢を提示し、ユーザーに確認を求めます。

PLANNED を VERIFIED に変更したり、失敗したゲートを免除したり、改訂予算を超過したり、ユーザーの決定なしに納品を確定したりしないでください。

明示的な承認後、機械的に記録します：

python scripts/passport.py authorize-delivery \
  --file .light/passport.yaml --root <project> \
  --authorization-id <user-record> \
  --known-limitation "<accepted limitation>"

このコマンドは、納品済みでない、または VERIFIED でないステージと、古い／不完全な成果物を拒否します。delivery_status=DELIVERED への唯一のサポート対象の遷移です。

完了チェック

• インテークを新規／再開／部分的／未完了／失敗／古い／納品済みのいずれかに分類した。
• パスポートは v3 で、ハッシュが有効であり、必要に応じて明示的に移行されている。
• ステージ 1～13、5 つのオーバーレイ、4 つのエンジニアリング／IP スキルの役割が維持されている。
• 検出結果の生成元と利用先が明記されており、機能しないゲートがない。
• 並列のフォーク／ジョインと依存関係の閉包が有効である。
• ワークフローレジャーに、上限付きのリトライ、実際の成果物ハッシュ、タスクエビデンス、互換性のある再開スナップショットがある。
• WAITING_USER に意思決定 ID／範囲／質問／選択肢／有効期限が設定され、自動再開されていない。
• 明示的な承認があるまでは、再ルーティングは助言にとどまっている。
• バックエッジは前の段階に向けられ、承認に紐付けられ、予算内である。
• ハンドオフのハッシュと次のアクションが検証されている。
• ハンドオフのルート、タイムスタンプ、最新のインテークスナップショットが引き続き一致している。
• エビデンスでは 5 つの状態のみを使用している。
• 既知の制約と利用できないリソースが明示されている。
• 影響の大きいタスクプロファイルでは、承認 ID を伴う合格済みの意思決定チェックポイントが添付されるまで、実行モードを選択できない。
• 再ルーティングと納品はオーケストレーターではなくユーザーが決定した。