マシンプロトコル

このページはアダプターや integration author 向けです。通常ユーザーは生成されたホスト capability を呼び出し、コマンドリファレンスを使います。

現在の JSON contract version は 2 です。

machine-protocol.schema.json は public command、Action、Outcome、status、error、recovery の shape を定義します。
source-envelope.schema.json は GitHub source transport shape を定義します。

実行可能な開始から終了までのホスト exchange はマシンプロトコル v2 チュートリアルを参照してください。

Schema は serialization shape を定義します。Runtime は JSON Schema で表現しきれないルールも検証します。Embedded manifest syntax、ordering、hash、cross-field identity、idempotency、workspace state、filesystem safety などです。Schema を検証し、prose から Go validator を再実装せず、CLI error を保持してください。

Process boundary

ホストはモデルを呼び出し、リポジトリを読み、tool を実行し、要求されたときに GitHub 認証情報を使います。この protocol exchange の Run/source path は local かつ deterministic です。Message を検証し、Run を記録し、Git を観測し、モデルや GitHub を呼び出さずに次の operation を返します。独立した public doctor コマンドは read-only diagnosis のためにユーザー環境の gh を呼び出す場合があります。

ホストは通常、各 step で JSON を使います。

slipway run --budget N --json --root ROOT [--no-review] --goal-file GOAL_FILE [--source-file SOURCE_FILE]
slipway protocol submit --run RUN --action ACTION --root ROOT (--outcome-file FILE | --outcome-stdin)
slipway protocol answer --run RUN --action ACTION --root ROOT --text-file TEXT_FILE
slipway protocol answer --run RUN --action ACTION --root ROOT --confirm-destructive --scope-sha256 DIGEST [--text-file TEXT_FILE]
slipway protocol skip --run RUN --action ACTION --root ROOT
slipway protocol resume RUN --root ROOT [--budget N]
slipway protocol resume RUN --root ROOT (--source-file FILE | --use-pinned-source | --source-choice pinned|adopt --candidate CANDIDATE) [--budget N]
slipway protocol material --run RUN --action ACTION --root ROOT --section KEY

Protocol 操作は versioned ホスト interface です。Documented であり help にも表示されますが、代替の end-user コマンド sequence ではありません。CLI が返す structured next variant から実行してください。

Run の開始

Canonical host invocation は exact goal を argv に入れません。Private temporary regular non-symlink file に書き、返された start variant の required goal_file path を解決します。

slipway run --budget 8 --json --root /absolute/worktree \
  --goal-file /private/temp/goal.txt

Ad-hoc Run はソースフィールドを省略します。Issue-backed Run は別の private temporary --source-file を指定します。CLI が消費した後、ホストは両方の temporary file を削除します。Run はその後 file や GitHub に依存しません。Human caller は1つの positional goal または --goal-stdin も使えますが、generated アダプターは process list/command trace の disclosure と platform command-line length 制限を避けるため goal_file を使います。

Start response には Run state、初期 orient Action、structured next operation が含まれます。

Action

Active Run には null でない Action が1つ含まれます。

{
  "contract_version": 2,
  "run_id": "...",
  "action_id": "...",
  "kind": "orient",
  "goal": "...",
  "brief": "...",
  "context": "...",
  "remaining_budget": 7
}

kind は orient、clarify、implement、review、summarize のいずれかです。

Issue-backed Action はさらに次を含みます。

source、manifest、requirements revision。
順序付き bounded section catalog。
Structured protocol material reader。
現在 Action に必要な section key。

Requirements Markdown は context に複製されません。Material reader は current non-void Action にだけ有効で、content を返す前に digest、byte count、section revision を検証します。

これらの key の versioned field は requirements.required_for_action です。Protocol v2 では requirements.sections にある全 key の ordered list と厳密に等しく、ホストがより小さい subset を推論してはいけません。

Reader の base_argv が権威ある invocation であり、slipway protocol material --root ROOT --run RUN --action ACTION で始まる厳密な9要素の並びに固定されています。Section flag は独立した argv 要素として追加し、上記 synopsis の順序に合わせて並べ替えないでください。synopsis は人間が読むための flag 順です。

Destructive confirmation の付与後に再発行される Implement Action は、3つめの variant field である destructive_authorization を持ちます。他のどの Action にも存在しないため、上記2つの形だけを網羅的とみなしたり、kind だけでモデル化したりしないでください:

Field	意味
`request_id`	この grant が応答する `destructive_request` の UUID。
`originating_action_id`	Request を発生させた Implement Action。
`scope_version`	Contract v2 では常に `1`。
`scope_sha256`	正規 scope に対する `sha256:<64 hex>`。
`targets`	厳密で空でない target の一覧。各要素は `path`、`git_ref`、`external_resource`、`data_domain` のいずれか。
`impact`	宣言された影響のテキスト。
`confirmed_at`	確認時刻の RFC 3339 UTC。

Slipway は load のたびに request_id、targets、impact から scope_sha256 を再計算し、一致しなければその Action を拒否します。Grant はその scope だけを認可し、それより広くはなりません。

context は active answer と以前の Outcome summary の bounded projection であり、完全なジャーナル、source、conversation、hidden モデル reasoning ではありません。

Outcome

Outcome はちょうど1つの入力から提出します。

slipway protocol submit --run RUN --action ACTION --root ROOT --outcome-file FILE
slipway protocol submit --run RUN --action ACTION --root ROOT --outcome-stdin

公開 Outcome field はすべて必須です。空の集合も array のままで、該当しない object branch は JSON null にします。

{
  "contract_version": 2,
  "action_id": "...",
  "action_kind": "orient",
  "status": "completed",
  "summary": "observed facts",
  "observations": [],
  "known_issues": [],
  "suggested_actions": [],
  "pause": null,
  "implementation": null,
  "review": null
}

action_kind は outstanding Action と一致する必要があります。Host status は completed、needs_input、partial、error で、skip は Outcome status ではなく CLI operation です。

Orient または Clarify は最大1つの clarify、implement、summarize Action を提案できます。Suggestion は予約ではなく参考です。Review が有効で、かつ Slipway が既に code change を観測している場合は、suggestion を採用する前に Review を差し込みます。
Non-paused Implement は implementation branch を使い、実際の file、attempt、uncertainty、test/type-check/build/lint activity と exit code を報告します。
Non-paused Review は review branch を使い finding を報告し、repair work を提案しません。
Summary とすべての needs_input Outcome は suggested Action を持ちません。

正当な Outcome 組み合わせ

Action	Host status	必須 result branch	許可される pause	許可される suggestion
Orient	`completed` / `partial` / `error`	`implementation=null`、`review=null`	なし	Clarify、Implement、Summarize のいずれかを 0 または 1 件
Orient	`needs_input`	`implementation=null`、`review=null`	decision または environment	なし
Clarify	`completed` / `error`	`implementation=null`、`review=null`	なし	Clarify、Implement、Summarize のいずれかを 0 または 1 件
Clarify	`needs_input`	`implementation=null`、`review=null`	decision または environment	なし
Implement	`completed`	`implementation.result=applied\|not_needed`、`review=null`	なし	なし
Implement	`partial`	`implementation.result=partial`、`review=null`	なし	なし
Implement	`error`	`implementation.result=unable`、`review=null`	なし	なし
Implement	`needs_input`	`implementation=null`、`review=null`	decision、destructive、environment	なし
Review	`completed`	`review.result=no_findings_reported\|findings_reported`、`implementation=null`	なし	なし
Review	`partial`	`review.result=inconclusive`、`implementation=null`	なし	なし
Review	`error`	`review.result=error`、`implementation=null`	なし	なし
Summarize	`completed` / `error`	`implementation=null`、`review=null`	なし	なし

Clarify には意図的に partial の正当な組み合わせがありません。1つの Action は1つの decision だけを扱います。Review は needs_input を使えず、いかなる Action も提案できません。not_run は CLI が生成する Review-skip projection だけに属します。

needs_input Outcome の pause reason は decision_required、destructive_confirmation_required、environment_unavailable のいずれかです。budget_exhausted は CLI だけが生成します。

Pause は任意の supersedes_answer_action_id を持つことがあり、その answer が今回の pause に置き換えられる以前の Clarify Action を指します。これは reason: "decision_required" と同時にのみ正当です。

Destructive confirmation は exact current Implement request と scope digest にだけ有効です。「yes」などの自然言語は authorization ではなく feedback です。Action 変更、resume、scope 拡大、mismatch は grant を無効化します。

Outcome input は上限 1 MiB、有効 UTF-8 で、BOM、duplicate/unknown field、trailing data を含んではなりません。

Structured `next`

継続可能な success/error には typed next object が含まれます。

operation：action、answer、resume、start、command、none。
元の workspace_identity。
id、base_argv、typed input を持つ variant が0個以上。

Input type は string、path、enum、digest です。Consumer は1つの variant を選び、入力値を schema 順に独立 argv element として挿入します。Display コマンドを parse/連結してはなりません。

Start variant は exact goal を required goal_file path input として持ち、goal text を base_argv に埋め込みません。Decision/feedback variant も required text_file path を使い、destructive confirmation note は optional text_file を使います。ホストは private temporary regular file を作成し、typed variant を解決し、消費後に file を削除します。Direct --text と stdin mode は human-facing convenience として残りますが、generated machine canonical path ではありません。

すべての required input が解決された variant だけが human shell コマンドに render できます。POSIX、cmd.exe、PowerShell rendering は presentation であり、machine value は structured argv です。

Windows display コマンドに cmd.exe では安全に保持できない expansion-sensitive な % または ! が含まれる場合、renderer は PowerShell UTF-16LE EncodedCommand trampoline を使用します。これは copyable display form だけを変え、decode 後の process argv は structured variant と byte-for-byte で等価でなければなりません。

Ended Run は operation: "none" と空の variant list を使います。

Source envelope

Source envelope は上限 16 MiB で、repository/Issue node ID で1つの github.com Issue を識別します。Valid Change では次を満たします。

body の最初の非空行は 。
次の非空 block は厳密に1つの slipway-manifest JSON fence。
ordered manifest は5〜64の section entry を持ち、outcome、requirements、acceptance examples、constraints、non-goals role を含みます。
envelope は参照された comments をちょうど含みます。
各 comment は exact section marker で始まり、宣言 digest と一致します。

Normalized section は最大 256 KiB、完全 section payload は最大 4 MiB、manifest は最大 256 KiB です。Missing、extra、duplicate、minimized、edited、oversized、hash-mismatched reference は拒否されます。

Top-level source schema は invalid refreshed head で空または whitespace-only の Issue/comment body と空 comments array を許可します。これにより、marker 不足、空の referenced section、digest mismatch はホストが envelope を先に拒否したり無関係な議論を収集したりせず、CLI によって分類されます。Embedded manifest string と semantic digest check は runtime が検証し、top-level schema 単独ではありません。

CLI は stable identity、provenance、byte count、revision、content-addressed accepted material を保存し、raw envelope、title label、source-file path、unreferenced comment をジャーナルに書きません。

Refresh と candidate

Issue-backed resume は次のいずれかを明示的に行います。

fresh envelope を import して比較する。
pinned snapshot を継続する。
exact current candidate で keep pinned または adopt valid candidate を選ぶ。

Source option 省略は「unchanged」でも暗黙の network access でもありません。別 Issue identity や異なる parent requirements revision の amendment は Run を変更せずに拒否されます。Candidate ID と choice は stale-safe idempotency を持ちます。

Versioned schema は closed な source_candidate.classification_code、resume_operation enum と、valid/invalid candidate の field combination に対する serialization authority です。Invalid candidate の observation_sha256 は、deterministic comparison に使う exact rejected source observation の domain-separated digest です。これは provenance であり、accepted Requirements でも、ホストが GitHub から取得したことの証明でもありません。

成功した resume は必要に応じて stale outstanding work を無効化し、workspace を再検証し、通常は fresh Orient を返します。--budget 省略時は正の remaining budget を保持し、0なら max(initial_budget, 3) まで補充します。明示的な --budget N は N に置き換えます。Replacement は実際に Run を resume する mutation でのみ適用されます。

resume は current typed next.operation が resume のときだけ受け付けます。Active Action または answer 可能な decision/destructive pause で呼ぶと current typed recovery とともに拒否されるため、失われた success response の retry が新しい work を暗黙に void することはありません。User take-over/reorder は public slipway stop を先に使い、その後に別の explicit resume を行います。

Workspace と Git 観測

Workspace identity には canonical worktree root、per-worktree Git directory、Git common directory が含まれます。Load や mutation のたびにこれらの path を再発見・比較してからジャーナルを変更します。

Repository-wide status は filesystem read-only の例外です。Namespace/lock の作成、permission 変更、ジャーナル byte の修復を行いません。別 linked worktree の Run は workspace_foreign 付き FirstEvent header stub として表示され、owning worktree 外では完全に replay しません。読めない local Run directory は、Run ID を伴わない status の JSON にある unavailable_runs に identity を残し、targeted read は corruption と absence を区別します。この一覧は slipway list ではありません。slipway list はホストアダプターを報告し、Run のデータを一切含みません。

Git observation は index、porcelain status、dirty path の hash と bounded metadata を記録し、file content は記録しません。差異は Run start 以降の変更の証拠であり、現在のホストが原因であることの証明ではありません。

Idempotency と順序

Outcome idempotency は元の accepted input bytes で hash を計算し、意味的に同じでも serialization が異なる JSON は conflict します。
Answer、skip、resume、candidate operation はすべて current ID に紐付き、stale/conflicting retry を拒否します。
各 Run の writer は同時に1つで、platform lock implementation が強制します。
Journal order が recovery record で、run.json は再構築可能です。

Error と互換性

Machine error には contract_version、stable code、human message、exit_code が含まれ、回復可能なら structured recovery も付きます。Consumer は code/version で分岐し、message text で分岐してはなりません。

Mutation が commit 済みでも、その後の derive、render、write response が失敗した場合、mutation_committed_output_failed は committed: true、exact Run ID、targeted slipway status RUN --root ROOT recovery を報告します。Mutation を blind replay してはいけません。

exit_code は process の exit status と一致し、2つの値のいずれかです:

値	意味
`2`	Usage error: invocation 自体が誤っている。
`3`	Runtime error: invocation は妥当だが operation が失敗した。

Structured CLI error を生成せずに失敗した process は 1 で終了し、JSON body を出力しません。1 は protocol の結果ではなく、defect または environment failure として扱ってください。

journal_record_too_large は厳密な context、size、limit detail field を持ち、Run ID が既知ならその Run への read-only status recovery variant も持ちます。Oversized record の拒否は persistent Run を終了させず、無効にもしません。

未知の contract version と field は拒否されます。Version 2 は、それ以前の未公開開発 format との互換性を約束しません。将来の非互換変更は新しい明示的な version を使うべきで、暗黙の alias を加えてはなりません。