workflow-state
workflow-state.json は、実行の単一情報源です。スキーマは templates/workflow-state.template.json にあります。すべてのアーティファクト書き込み時に post-write-state フックが、また scripts/approve_event.py / scripts/reject_event.py によって更新されます。エージェントは手動で編集してはいけません。
キー
| キー | 意味 |
|---|---|
run_id | 実行フォルダ名（runs/<run-id>）と一致しなければならない |
requirements_hash | artifacts/01-requirements.md の SHA-256（書き込み時に設定） |
execution_plan | 順序付けられたステップ: step, name, agents, depends_on, status (pending/running/done/failed), attempts |
artifacts | 実行相対パス → {owner, status, sha256, updated_at} のマップ |
gate_results | G1..G8 → {status: PASS/FAIL/PASS-N/A, attempts, findings, responsible_agent} のマップ |
retry_counters | G1..G8 → 既に消費されたリトライ回数のマップ |
approval | {status: pending/approved/rejected, approved_at, plan_sha256, rejected_count, feedback[]} |
notes | 追加専用の自由形式ログ（決定、スキップされたエージェントとその理由） |
更新ルール
- ハッシュはファイルバイトのSHA-256（16進小文字）。ステップがスキップされた場合、そのアーティファクトが
doneで、ディスク上のハッシュが一致すれば、新しい情報は記録しない。 - ステータス遷移:
pending → running → done|failed。対象を絞ったリトライは、責任エージェントのステップとその下流依存のみを再実行し、そのステップのattemptsとretry_counters[gate]を増やす。 - スキップされたエージェント は
notesに記録され（例："entertainment-planner skipped: no entertainment required"）、そのアーティファクトはNot applicable — <reason>として書き込まれる。 - ゲート結果 はゲートごとに findings と
responsible_agentとともに記録される。status: FAILかつattempts: 3のゲートは依存する実行を停止し、下流ステップをfailedとし、明確なレポートで実行を終了する。 - 承認:
approval.status = "approved"とapproval.plan_sha256を設定できるのはscripts/approve_event.pyのみ。scripts/reject_event.pyはapproval.feedbackに追加し、rejected_countを増やす。06-event-plan.mdの改訂は、フィールドが古くてもガードのためにplan_sha256を無効にする。 - 書き込みはアトミック（一時ファイル＋リネーム）。
updated_atは UTC ISO-8601（...Z）で保持する。
再開契約（/plan-event --resume <run-id>）
- 状態をロードする。
workflow-state.jsonがないか無効な場合は → エラーで停止する。 - ディスク上の
artifactsのすべてのパスを再ハッシュする。不一致はそのアーティファクトをstaleとしてマークする。 statusがpending/running/failedのステップと、アーティファクトがstaleのステップ（およびその下流依存）のみを実行する。- アーティファクトが
doneでハッシュが一致するステップを決して繰り返さない。 - 各アーティファクトの完了時に、フックが自動的に状態を更新する。コーディネーターは
execution_plan、gate_results、retry_counters、notesのみを更新する。