SOP 構文リファレンス

SOP 定義は sops_dir 配下のサブディレクトリから読み込まれますが、sops_dir はデフォルトでは未設定です。そのため、オペレーターがオプトインするまでランタイムでの SOP 実行は無効です。これを有効にするには、sops_dir にディレクトリを設定します。相対値はインストールルート（config.toml を格納しているディレクトリ）を基準に解決されるため、ドキュメントに記載された shared/sops は、SOP 作成者の書き込み先と同じディレクトリである <install>/shared/sops に解決されます。絶対パス、または ~-が先頭に付く値はそのまま使用されます。"" に戻す（または未設定のままにする）と、ランタイムでの SOP 実行は無効になります。CLI コマンドは、オフライン検査では引き続き <install>/shared/sops にフォールバックします。

1. ディレクトリレイアウト

<shared>/sops/
  deploy-prod/
    SOP.toml
    SOP.md

各 SOP にはSOP.tomlが必要です。SOP.mdはオプションですが、パースされたステップがない場合は検証に失敗します。

2. 境界の作成

ファイルベースの表現には、引き続きマニフェストファイルと SOP.md が含まれています。このページでは、意図的にマニフェストのフィールドを列挙したり、手作業で作成したマニフェストの例を示したりしていません。

このページは、SOPのレビュー、検証、デバッグ時に表示される構文を参照するために使用してください：SOP.md のステップ箇条書き、ランタイムスキーマから生成されたトリガーフィールドのサマリー、および condition 式。生成またはチェックインされたSOPを実行する前に、zeroclaw sop validate <name> で検証してください。

SOP.toml には、SOP の識別情報（name、description、version）、triggers、および実行設定が含まれます。同時実行の受付に関するフィールドは、この SOP の実行スロットがすべて埋まっているときにトリガーが到着した場合の動作を決定します。

admission_policy の値（SopAdmissionPolicy、snake_case）：

• parallel（デフォルト）- 最大 max_concurrent 件まで受け入れます。すぐに受け入れられないトリガーは延期され（トリガーのトランスポート上でバックプレッシャー／再配信の対象として提示され）、サイレントに破棄されることはありません。独立した作業（例：PR 承認 SOP）に最適です。
• hold - 直列化: この SOP の実行がアクティブでも待機中でもない場合にのみ受け入れ、その他のトリガーは延期します。事前承認ステップを重複させてはならないパイプライン向けです。
• coalesce - 実行中の処理に並行トリガーをまとめる（実行中の処理の最新状態が既にそれをカバーしている）。
• drop - レガシーな fire-and-forget: 受け入れられないトリガーは破棄されます。明示的なオプトインの場合にのみ使用し、決してデフォルトにはしません。

遅延トリガーのリカバリはトランスポートに依存します。このバージョンにはエンジン内に永続的な保留トリガーキューは存在しません（これは別途のフォローアップです）。

• AMQP（durable_ack = true、SOP専用ディスパッチ）: 配信はnack（requeue = true）されるため、空きができ次第ブローカーが再試行します。
• AMQP 統合 sop_and_agent_loop: エージェント側はすでに配信を消費しているため、バックプレッシャーによる SOP のオーバーフローは大々的にログ記録され、ACK されます（再配信はされません）。これはエージェント側の二重実行を回避するためです。
• MQTT / cron / filesystem / channel-router（およびディスパッチ結果をログ出力するだけのその他のヘッドレスソース）: メッセージごとの再配信がないため、遅延したトリガーは目立つログを残して破棄されます（次のスケジュール済み/発行済み/観測済みトリガーだけが復旧手段となります）。

[sop]
name = "deploy-prod"
description = "Production deploy with approval"
version = "1.0.0"
max_concurrent = 1
admission_policy = "hold"
max_pending_approvals = 8

[[triggers]]
type = "manual"

承認ブローカーのグループとポリシーは、SOPごとの SOP.toml ファイルではなく、メインの ZeroClaw 設定に配置されます。ステップは SOP.md 内で - policy: prod と記述することで、設定済みのポリシーを名前で参照できます。

[sop.approval.groups.release]
members = ["http:<paired-token-subject>", "agent:release-bot"]

[sop.approval.policies.prod]
required_group = "release"
quorum = 2
escalation_route = "oncall"

[sop.approval.groups.*]のメンバーは承認IDであり、アカウント名ではありません。メンバーはソース修飾子付き（http:<subject>、ws:<subject>、agent:<alias>）で指定して特定のトランスポートのみに承認権限を付与するか、修飾子なし（ZeroClawOperator）で指定してそのIDを持つ任意のソースに承認権限を付与できます。HTTPおよびWebSocketの承認サーフェスはペアトークンのサブジェクトを使用します。現在のCLI承認パス（zeroclaw sop approve）は匿名であり、まだcli:<user>メンバーシップを満たすことができません。

ペアードトークンのサブジェクトは、ベアラートークンの小文字SHA-256 16進ダイジェストです。ペアリング後、標準的なgateway.paired_tokensエントリからダイジェストをコピーするか、そのシークレットをシェル履歴に残さずにベアラートークンから計算してください。ペアードトークンをローテーションすると新しいサブジェクトが生成されるため、同じローテーションの一環として古いダイジェストを参照しているすべての承認グループメンバーシップを更新してください。

3. SOP.md ステップ形式

ステップは## Stepsセクションからパースされます。

## Steps

1. **Preflight** — Check service health and release window.
   - tools: http_request

2. **Deploy** — Run deployment command.
   - tools: shell
   - requires_confirmation: true
   - policy: prod
   - input: {"type":"object","required":["version"],"properties":{"version":{"type":"string"}}}
   - output: {"type":"object","required":["digest"],"properties":{"digest":{"type":"string"}}}
   - next: 3

ルーティングと承認の箇条書きは、同じ SOP.md の手順にまとめることができます:

## Steps

1. **Classify event** — Inspect the incoming payload.
   - output: {"type":"object","required":["severity"],"properties":{"severity":{"type":"string"}}}
   - when: $.steps.1.severity == "critical"
   - next: 2

2. **Prepare summary** — Build the operator-facing remediation plan.
   - depends_on: 1
   - on_failure: retry:2
   - next: 3

3. **Approval gate** — Require explicit approval before changing state.
   - kind: checkpoint
   - requires_confirmation: true
   - next: 4

4. **Apply remediation** — Execute the approved action.
   - tools: shell
   - allow-tools: shell
   - on_failure: goto:5

5. **Notify operator** — Send a failure notice for follow-up.
   - tools: http_request

パーサーの動作:

• ## Steps セクションは、次のレベル 2 見出しまで解析されます。
• 番号付きアイテム(1.、2.、…)はステップの順序を定義します。
• 先頭の太字テキスト（**Title**）がステップのタイトルになり、残りのテキストが本文になります。
• - tools: は suggested_tools にマッピングされ、ステップに対する推奨ツール名を提供します。
• - allow-tools:（または - allow_tools:）は、ステップごとのツール許可リストを明示的に定義します。
• - deny-tools: (or - deny_tools:) は、ステップごとの明示的なツール拒否リストを定義します。
• - requires_confirmation: trueは、そのステップに対して承認を強制します。
• - kind: は execute（デフォルト）、checkpoint/approval、または capability を受け付けます。チェックポイントは決定論的実行を一時停止し、requires_confirmation: true はどの実行モードでも承認を必要とします。
• - capability: は、kind: capability ステップで使用される決定論的な機能の名前を指定します。
• - with: は、機能ステップの構造化された入力を提供します。
• - input: は、JSON Schema に似た入力コントラクトをステップの境界に付加します。
• - output: は、ステップ境界に JSON Schema のような出力コントラクトを関連付けます。
• - when: は、現在のステップが完了した後に蓄積された完了済みステップの出力に対して評価されます。ガードが false の場合は switch と明示的な next をバイパスし、線形の後続ステップへ進むか、ステップが終端であるか後続ステップがない場合は完了します。ガードが true であるか存在しない場合は、空でない switch が next より優先されます。switch がない場合は、終端または線形ルーティングに先立って、明示的な next が使用されます。
• - next: は、トップレベルの when がルーティングを許可し、switch ポートが宣言されていない場合にのみ、明示的な後続先へルーティングします。ルーティング対象外のステップは skipped とマークされ、ディスパッチされずに実行を pending のままにします。
• - terminal: true は別のステップに進まずに実行を完了します。最後のステップも、直線的な後続ステップがない場合は完了します。
• - depends_on:（または - depends-on:）には、非線形実行の前提条件となるステップを一覧表示します。
• - switch: は、多分岐ルーティング用に順序付けられた name>condition>step ポートを定義します。トップレベルの when が true または存在しない場合は、最初に一致したポートが選択されます。一致するポートがない switch は実行を完了し、next と線形後続要素は無視されます。トップレベルの when が false の場合、switch の評価はスキップされます。
• - on_failure:（または - on-failure:）は fail、retry:<count>、または goto:<step> を受け付け、報告されたステップの失敗と出力スキーマの失敗に適用されます。
• - mode: はそのステップの SOP 実行モードを上書きします。
• - agent: は、そのステップの親エージェントのエイリアスを上書きします。
• - call: は、値が計画済み呼び出しとして解析される場合に、ステップに JSON の計画済みツール呼び出しを追加します。
• - prompt: は承認ゲートの通知テンプレートを設定します。
• - policy: は [sop.approval].policies 内の approval-broker ポリシーを指定します。このポリシーは、必須グループへの所属と定足数によって承認を制御します。ポリシーが存在しない場合は、1 件の承認だけで解除されるのではなく、フェイルクローズになります。一方、ポリシーを省略すると、ゲートは制御されないままになります。
• - edit: 再開前に指定したフィールドを編集できるようにします。
• 認識されないサブ箇条書きやその他の空でない継続行は、ステップ本文に追加されます。

コピーして使える条件付きルーティングの例

この完全な SOP.md は、重大なアラートを承認済みの修復手順に振り分ける一方、その他のアラートは修復せずに記録します:

# Alert triage

Classify an incoming alert, remediate critical alerts, and notify the operator.

## Steps

1. **Classify alert** - Normalize the incoming alert severity.
   - output: {"type":"object","required":["severity"],"properties":{"severity":{"type":"string"}}}
   - when: $.steps.1.severity == "critical"
   - next: 3

2. **Record routine alert** - Add the non-critical alert to the incident log.
   - tools: shell
   - next: 4

3. **Remediate critical alert** - Run the approved remediation command.
   - tools: shell
   - requires_confirmation: true
   - on_failure: retry:2
   - next: 4

4. **Notify operator** - Send the outcome to the operations channel.
   - tools: http_request

ステップ 1 が {"severity":"critical"} を出力すると、そのガード条件が一致し、next によってステップ 3 にジャンプします。その他の重大度の場合はステップ 2 にフォールスルーし、明示的な next によって修復処理をスキップして、ステップ 4 でクリティカルパスに合流します。

ローダーは SOP.toml も含むディレクトリのみを検出するため、上記の手順を <sops_dir>/alert-triage/ にあるこのマニフェストと組み合わせてください:

[sop]
name = "alert-triage"
description = "受信したアラートを分類し、重大なアラートを修復して、オペレーターに通知します。"

[[triggers]]
type = "manual"

次に zeroclaw sop validate alert-triage を実行すると、SOP が有効であることが報告されます。

[sop.approval] ポリシーとルート配信

ポリシーは承認をアウトオブバンドでチャネルにルーティングすることもできるため、承認者は実行を開始したサーフェスを監視していなくても対応できます:

[sop.approval.policies.prod]
required_group = "release"
quorum = 2
# このポリシーが制御するゲートで実行が PARKS になったときに配信されます。
request_route = "discord.ops:123456789012345678"
# そのゲートが後で TIMES OUT になった場合にのみ配信されます（別個の 2 番目のルート）。
escalation_route = "discord.oncall:987654321098765432"

両方のルートは channel:recipient です。channel は設定済みチャネルのマップキー（<channel>.<alias>、またはシングルトンの場合は単独の <channel>）で、recipient はそのチャネルの宛先（Discord チャネル ID、チャット ID、…）です。配信はベストエフォートで行われ、ゲートをブロックしたりクリアしたりすることはありません - 承認自体は、認証済みの approve/deny サーフェスを通じて引き続き返され、そのプリンシパルはポリシーのグループおよびクォーラム要件を満たすことができます。ルートが動作するのはデーモン内（チャネルが設定されている場所）だけです。未設定（または空）にすると、デフォルトどおり、発信元のサーフェスにのみ通知します。

ルート配信には永続的なリトライキューがありません。非同期送信が完了する前にデーモンが終了した場合や、チャネル送信に失敗した場合、パークされたゲートを変更することなく通知が失われる可能性があります。オペレーターは zeroclaw sop pending で保留中の実行を確認し、認証済みの承認サーフェスを通じて対象の承認者に連絡できます。

チャネルネイティブの承認者を付与する承認グループは、チャネル修飾メンバー形式 channel:<channel-key>:<sender> を使用する必要があります（例：channel:discord.ops:123456789012345678）。channel:123 や単なる 123 のようなスコープなしのメンバーは、送信者IDがプラットフォーム間で重複する可能性があるため、またチャネルエイリアスがあるため、チャネル承認と一致しません。

決定論的チェックポイント: 承認と再開

kind: checkpoint ステップで一時停止した確定的実行は、承認ゲート（zeroclaw sop pending は kind で区別しつつ両方を列挙）と同じ approve/deny インターフェースで解決されます。承認時、エンジンは実行を再開し、それ以降の kind: capability ステップを次の一時停止または完了まで非インタラクティブに駆動します。つまり checkpoint -> capability の末尾（例：承認済み下書きの投稿）は、ライブエージェントターンなしで実行されます。拒否時は実行がキャンセルされます。いずれの解決も承認台帳に記録されます。checkpoint ステップには - policy: を付与できます。そのポリシーで定められた必須グループのメンバーシップおよびクォーラムは、checkpoint の決定が解決される前に適用されます。そのポリシーが request_route を指定している場合、デーモンはアウトオブバンドの checkpoint 通知をそこへ送信します。escalation_route は時間制限付き承認ゲートのタイムアウトルートとして引き続き機能します。checkpoint の一時停止には、現時点では checkpoint 固有のエスカレーションタイムアウトはスケジュールされません。

2つの追加のチェックポイント解決により、レビュー担当者は単にゲートするだけでなく、ドラフトを形作ることができます（どちらもapprove/denyと同様に台帳監査されます）。

• 編集（変更） - チェックポイントの - edit: <field> 箇条書きによってオプトインで有効化されます。承認者は、実行が再開される前に、パイプされた値のそのフィールドを自分のテキストで置き換えることができます（Discord では、Edit ボタンをクリックすると現在の値が事前入力されたモーダルが開きます）。チェックポイントに記録される出力には、人間が承認したテキストが含まれます。先行ステップは監査証跡のためにモデルの元の値を保持します。台帳の行には decision: amend が記録されます。
• 修正 - チェックポイントの直前のステップが llm.generate ステップである場合に自動的に提示されます。承認者がガイダンスを送信すると、エンジンはそのガイダンスをレビュアーのフィードバックとしてフレーミングして（revision_feedback、ステップの静的設定プレーンで運ばれます - 信頼されないペイロードのフレーミングは変更されません）そのステップを再実行し、ドラフトを置き換えて、ゲートを再提示します。実行による各ゲート提示には一意のリビジョンが付与されます（各修正でインクリメントされ、後続の各チェックポイントの初回パーク時にもインクリメントされます）。プロンプト参照は <run_id>#<rev> になり、置き換え済みのプロンプト（古いドラフト、または以前のゲートに残ったボタン）への回答は拒否されます。ゲートあたり最大3回のリビジョンに制限されます。ドラフトの再作成に失敗した場合は、以前のドラフトがパークされたまま回答可能な状態に保たれます。台帳には、ガイダンスを理由として decision: revise が記録されます。

インジェクトアダプター機能

2 つの kind: capability ステップは、デーモンがエンジンの構築時に注入するアダプターを通じて実際の副作用を実行します。デーモンがない場合（CLI の検証やテスト時）は、shell.exec と同様に、明確なメッセージを表示して安全側に失敗します：

• llm.generate - デフォルトエージェントの解決済みモデルプロバイダーを使用し、パイプラインステップとして1回の境界付きモデル呼び出しを行います（ツールなし、エージェントループなし）。with: で指定できるフィールド: instruction（必須）、system、output_key（デフォルト text）、echo（ダウンストリームのパイピング用に出力へコピーされるペイロードフィールド）。パイプされたイベントペイロードは明示的な非信頼コンテンツフレーム内で配信され、設定として読み取られることはありません。
• forge.comment - git チャネルのアウトバウンドパスを通じて、git-forge の issue/PR にコメントを投稿します（プロバイダー非依存: GitHub / Gitea / Forgejo）。入力フィールド: repo（owner/repo）、number、body、およびオプションの channel（git.<alias>; デフォルトは唯一の設定済み git チャネル）。

チェックポイントと組み合わせることで、ヘッドレスレビューパイプラインを形成します。

1. **Draft** - kind: capability / capability: llm.generate
   - with: { instruction = "...", output_key = "body", echo = ["repo", "number"] }
2. **Approve** - kind: checkpoint / policy: triage
3. **Post** - kind: capability / capability: forge.comment

アダプターが接続される場所。 実際のアダプター（llm.generate のモデルプロバイダー、forge.comment の git チャネル、およびチェックポイントポリシーの帯域外承認ルート）は、daemon / channel-start パス上でのみ注入されます。これは、設定済みのチャネルマップと正式なモデルを持つ唯一のパスです。スタンドアロンのエージェント実行と CLI SOP 実行では、これらなしでエンジンが構築されるため、これらの機能とルートはそこではフェイルクローズドになります。llm.generate / forge.comment は動作するのではなく、明確な “requires an injected adapter” という失敗を報告し、チェックポイントのルート通知はログのみの no-op になります。これは shell.exec と同じフェイルクローズドモデルです。これらの機能を必要とするパイプラインは daemon 下で実行してください。

ステップコントラクトの適用

ステップコントラクトは任意です。指定する場合、input と output は type、required、properties、items フィールドを持つコンパクトな JSON オブジェクトを受け付けます。サポートされているプリミティブ型は object、array、string、number、integer、boolean、null です。

[sop] の設定で強制の適用を制御します:

スキーマの強制はフェイルクローズで動作します。無効なステップ入力はステップの開始を妨げ、無効なステップ出力はステップの on_failure ポリシーを通じてルーティングされます。ルーティングの強制は、LLM および決定論的な実行における線形的な current_step + 1 の進行を置き換えます。ツールスコープの強制は、実行中のステップターンで利用可能なツールを絞り込み、スコープ外の呼び出しをディスパッチ時にブロックします。

信頼できないトリガーのトピックとペイロードのテキストは、ステップコンテキストに到達する前に、上限設定、正規化、スクリーニング、フレーミングが行われます。フレーミングは常に有効で、警告テキストは非表示にできますが、生の外部トリガーテキストがモデルコンテキストに補間されることはありません。

手続き的メモリはオプトイン方式です。有効にすると、sop_workshop は保存された SOP 提案の作成と検査、完了した実行コンテキストの候補プロシージャへのキャプチャ、承認済みの提案の SOP.toml/SOP.md への適用を行えます。書き戻しは明示的な apply アクションを通じてのみ行われます。

実行の耐久性

[sop] 設定は、デーモンの再起動後に実行状態が維持されるかどうかも制御します：

persist_runs = true がデフォルトであるため、保留中の HITL 承認が再起動時に失われることはありません（永続バックエンドを開けない場合、build_sop_engine は目立つログを出してインメモリーストアにフォールバックするため、デフォルトで安全です）。persist_runs = false は一時的なエンジン向けに文書化されたオプトアウトです。

4. トリガータイプ

各ソースのライブ対アンワイヤードのステータスとトランスポートの詳細については、SOP Fan-In を参照してください。

JSON パス比較: $.value > 85、$.status == "critical"

トリガーの condition フィールドとステップの when: ガードは、同じ式文法を使用します。トリガー条件はイベントペイロードに対して評価されます。ステップの when: ガードは、次の形式で蓄積された完了済みステップの出力に対して評価されます:

{
  ステップ: {
    "1": {
      "重大度": クリティカル
    }
  }
}

評価は、無効な条件、ペイロードの欠落、未解決のJSONパス、およびペイロードまたは比較対象が数値でない直接的な数値比較に対してフェイルクローズドです。空の条件は無条件にマッチします。

JSON Path フォーム

$ で始まる条件は、JSON ペイロード内の値を比較します: $.path.to.field <op> <value>。

パスルール:

• ドット区切りのセグメントを使用します。配列要素には $.readings.1 のような数値セグメントを使用します。ブラケット構文はサポートされていません。
• キーの欠落、範囲外の配列インデックス、無効な JSON、空のペイロードはフェイルクローズします。
• ワイルドカード、フィルター、再帰的下降、組み込み変数はありません。

直接数値形式

先頭に $ のない条件は、ペイロード全体を数値として比較します。これはスカラーイベントペイロードに便利です。

演算子

比較では 1 つの演算子を使用します。ソースが所有するオーサリング カタログは次のとおりです:

• ==: 等しい
• !=: ではない
• >: より大きい
• >=: 以上
• <: より小さい
• <=: 以下

パーサーは演算子トークンを最長一致で照合します。JSON-path の比較では、まず数値比較を試みます。両辺が数値として解析できる場合は数値として比較し、それ以外の場合は値を文字列として比較します。比較対象を囲む二重引用符は削除されるため、文字列リテラルは引用符で囲みます: $.status == "critical"。直接の数値条件は数値のみを対象とします。一方でも数値として解析できない場合、一致しません。

条件評価器は JSON のブール値を文字列 true と false に変換するため、$.active == "true" のように引用符付きの文字列として比較してください。

条件は単一の比較です。AND、OR、NOT などの論理結合子はサポートされていません。

6. 検証

SOP 接続とイベントファンイン

zeroclaw sop validate
zeroclaw sop validate <name>

このドキュメントでは、外部イベントが SOP 実行をトリガーする方法について説明します。