Rasen エージェント契約

rasen CLI のマシン読み込み可能なサーフェスは、src/ に対して検証されます（キャップストーン監査、2026-06-11）。以下のすべての形状は、発信コードから文書化されています。

1. 一般的な慣例

• 1回の呼び出しごとに 1 つの JSON ドキュメント。 --json モードでは、stdout は正確に 1 つの JSON ドキュメント（2 スペース プリティプリント）を保持します。人間のプロース、スピナー、ストア バナーは stderr に移動します。
• ストア バナー。 人間モードでは、ストア選択ルートが Using Rasen root: <id> (<path>) を stderr に出力します。JSON モードでは出力されません。
• キー大文字小文字は表面に依存します（既知の矛盾を参照）: store/doctor/context ペイロードは snake_case を使用します。ワークフロー ペイロード（status、instructions、new change、validate、list）は camelCase を使用しますが、常に store_id を使用する埋め込み root オブジェクトは除きます。
• オプション キーは省略され、null ではありません。ほとんどのペイロード（root.store_id、member.path など）。明示的な null を使用する例外は、形状ごとに呼び出されます（store doctor git.*、失敗ペイロード）。

2. 診断エンベロープ

1 つのエンベロープ形状は、すべてのマシン読み込み可能診断（StoreDiagnostic）で共有されます:

{
  "severity": "error" | "warning" | "info",
  "code": "snake_case_string",
  "message": "human sentence",
  "target": "dotted.surface (optional)",
  "fix": "one actionable sentence/command (optional)"
}

診断は 2 つの位置に表示されます: status配列（トップレベルまたは各エントリごと）健全性所見用、スローされたエラー コマンド失敗時に単一要素 status 配列に変換。

3. ルート選択および RootOutput

すべてのルート解決コマンド（list、show、validate、status、instructions、instructions apply、new change、archive、doctor、context）は 1 つの優先度を持つ 1 つのRaseんルートを解決します:

1. --store <id> → 登録されたストアのルート（source: "store"）。
2. それ以外の場合、rasen/ の最も近い祖先: プランニング形状 → source: "nearest"（store: ポインターは stderr 警告で無視される）。有効な store: ポインター持つ config-only dir → そのストア、source: "declared"。
3. 最も近いルート + 登録されたストアが存在しない → エラー no_root_with_registered_stores。
4. ルートなし、ストアなし: スキャフォールディング コマンドは cwd を source: "implicit" として扱います。診断コマンド（doctor、context）は代わりに no_openspec_root で失敗します—それらはスキャフォールドではなく、検査します。

成功した JSON ペイロードはルートを埋め込みます:

"root": { "path": "/abs/path", "source": "store" | "declared" | "nearest" | "implicit", "store_id": "id (only when store-selected)" }

ルート失敗契約: JSON モードでは、解決失敗は { ...commandNullShape, "status": [diagnostic] } を stdout に出力して 1 で終了します。

4. コマンド JSON 形状

4.1 list --json

{ "changes": [ { "name", "completedTasks", "totalTasks", "lastModified", "status": "no-tasks"|"complete"|"in-progress" } ], "root": RootOutput } — 変更ごとの status は文字列列挙ここ。--specs: { "specs": [ { "id", "requirementCount" } ], "root" }。

4.2 show <item> --json

変更: { "id", "title", "deltaCount", "deltas": [...], "root" }。仕様: { "id", "title", "overview", "requirementCount", "requirements": [...], "metadata": { "version", "format", "sourcePath"? }, "root" }。

4.3 validate --json

{ "items": [ { "id", "type": "change"|"spec", "valid", "issues": [ { "level", "path", "message", "line"?, "column"? } ], "durationMs" } ], "summary": { "totals": {items,passed,failed}, "byType": {...} }, "version": "1.0", "root" }。アイテムが失敗する場合は終了 1。

4.4 status --json

{ "changeName", "schemaName", "planningHome"?: { "kind", "root", "changesDir", "defaultSchema" }, "changeRoot", "artifactPaths": { "<id>": {outputPath, resolvedOutputPath, existingOutputPaths} }, "nextSteps": ["..."], "actionContext": { "mode": "repo-local", "sourceOfTruth": "repo", "planningArtifacts", "linkedContext", "allowedEditRoots", "requiresAffectedAreaSelection", "constraints" }, "isComplete", "applyRequires", "artifacts": [ {id, outputPath, status: "done"|"ready"|"blocked", missingDeps?} ], "root" }。アクティブな変更なし: { "changes": [], "message", "root" }、終了 0。

4.5 instructions <artifact> --json

{ "changeName", "artifactId", "schemaName", "changeDir", "planningHome"?, "outputPath", "resolvedOutputPath", "existingOutputPaths", "description", "instruction"?, "context"?, "rules"?, "references"?: ReferenceIndexEntry[], "template", "dependencies": [{id,done,path,description}], "unlocks", "root" }。

ReferenceIndexEntry: { "store_id", "root"?, "specs"?: [{id,summary}], "fetch"?, "status": [] } — 解決されたエントリはroot/specs/fetchを保持。解決されないエントリはstore_id + warning状態を保持。インデックス50KB でキャップ（reference_index_truncated）。

4.6 instructions apply --json

{ "changeName", "changeDir", "schemaName", "contextFiles": { "<artifactId>": ["/abs", ...] }, "progress": {total,complete,remaining}, "tasks": [{id,description,done}], "state": "blocked"|"all_done"|"ready", "missingArtifacts"?, "instruction", "references"?, "root" }。

4.7 new change <name> --json

成功: { "change": { "id", "path", "metadataPath", "schema" }, "root" }。失敗: { "change": null, "status": [d] }、終了 1。

4.8 archive <name> --json

成功: { "archive": { "change", "archivedAs": "YYYY-MM-DD-name", "path", "specsUpdated", "totals"? }, "root" }。失敗: { "archive": null, "root"?, "status": [d] }、終了 1。JSON モードは厳密に非インタラクティブ: すべてのプロンプト ポイントは archive_* コードになります。

4.9 doctor --json

{ "root": { "path", "source", "store_id"?, "healthy", "status": [] }, "store": { "id", "metadata": {present,valid,remote?}, "origin_url"?, "status": [] } | null, "references": [...], "status": [] }。任意の重大度の健全性所見は 0 で終了。失敗ペイロード: { "root": null, "store": null, "references": [], "status": [d] }、終了 1。

4.10 context --json

{ "root": { "path", "source", "store_id"?, "role": "openspec_root" }, "members": [ { "role": "referenced_store", "id", "path"?, "remote"?, "fetch"?, "status": [] } ], "status": [] }。AVAILABLE = path present AND status empty。--code-workspace <path> は {folders:[{name,path}]} を書き込みます（利用可能な参照ストアのみ、ref: プレフィックス）。JSON モードでは、書き込みが出力前に実行されるため、stdout は書き込み失敗でも正確に 1 つのドキュメントを保有します。失敗: { "root": null, "members": [], "status": [d] }、終了 1。

4.11 store ... --json

setup/register: { "store": {id, root, metadata_path?}, "registry": {path, registered, already_registered}, "git": {is_repository, initialized, committed}, "created_files": [], "status": [] }。unregister/remove: { "store", "registry": {path, removed}, "files": {deleted, deleted_path, left_on_disk}, "status": [] }。list: { "stores": [{id, root}], "status": [] }。doctor: { "stores": [ { id, root, metadata_path?, openspec_root: {...healthy, status}, metadata: {present, valid, id?, remote}, git: {is_repository, has_commits, has_uncommitted_changes, has_remote, origin_url}, status } ], "status": [] } （null = unknown/not probed）。健全性所見は 0 で終了。失敗は一致する null-shape で 1 で終了。プロンプト キャンセルは 130 で終了します。

4.12 schemas --json / templates --json

schemas: bare array [ {name, description, artifacts, source} ]。templates: keyed object { "<artifactId>": {path, source} }。両方 cwd-based、no root/status keys。

5. 終了コード契約

6. 診断コード カタログ

解決

no_openspec_root, no_root_with_registered_stores, no_registered_stores, unknown_store, store_identity_mismatch, unhealthy_store_root, store_path_not_supported, invalid_store_pointer, initiative_option_removed, areas_option_removed; pass-through: invalid_store_id, invalid_store_registry, invalid_store_metadata。

Raseんルートの健全性（エラー、修正なし）

openspec_store_root_missing, openspec_store_root_not_directory, openspec_root_missing, openspec_root_not_directory, openspec_config_missing, openspec_config_not_file, openspec_specs_not_directory, openspec_changes_not_directory, openspec_archive_not_directory。（specs/changes/archive はオプション ディレクトリです—存在しないときではなく、何か非ディレクトリがそのパスに存在するときにのみ失敗します。）

ストア レジストリ/ID/状態

invalid_store_id, invalid_store_registry, invalid_store_metadata, store_registry_busy, store_not_found, no_store_registry, store_registry_changed, store_metadata_missing, store_metadata_id_mismatch, store_metadata_invalid, store_id_conflict, store_path_conflict, store_already_registered（info）。

ストア セットアップ/レジスタ/削除

store_setup_id_required, store_setup_path_required, store_setup_path_not_directory, store_setup_inside_git_repo, store_setup_non_empty_directory, store_setup_cancelled, store_path_required, store_path_missing, store_path_not_directory, store_register_root_unhealthy, store_register_identity_confirmation_required, store_register_cancelled, store_remote_empty, store_remote_requires_hand_edit, store_remove_confirmation_required, store_remove_cancelled, store_remove_path_not_directory, store_remove_metadata_missing, store_root_missing（remove で警告、doctor でエラー）、store_root_not_directory。

ストア git

store_git_init_failed, store_git_identity_missing, store_git_commit_failed, store_git_no_commits（警告）、store_clone_fragile_directories（警告）、store_remote_divergence（info、doctor）。

参照（警告）

reference_invalid_id, reference_registry_unreadable, reference_unresolved, reference_root_unhealthy, reference_index_truncated。

関係（警告; doctor; context はレジストリのみを保持）

relationship_registry_unreadable, root_pointer_ignored, root_pointer_invalid, pointer_declarations_inert。

アーカイブ（JSON モード）

archive_change_name_required, archive_change_not_found, archive_validation_failed, archive_confirmation_required, archive_tasks_incomplete, archive_spec_update_failed, archive_spec_validation_failed, archive_target_exists, archive_error。

コンテキスト書き込み

context_file_exists, context_output_dir_missing。

フォールバック

doctor_failed, context_failed, store_error, change_error, archive_error。

既知の矛盾

キャップストーン監査によって記録されました。公開されたキー名前変更は、このリリースを過ぎて延期された製品の決定です:

1. JSON モードでは、複数の失敗パスが stderr のみを出力し、JSON ドキュメントがありませんでした。 キャップストーン戦闘一覧で修正: show/validate 不明および曖昧アイテムは {status:[{code: unknown_item | ambiguous_item, ...}]} を発行します。status/instructions/list/show/validate のスローされたエラーは JSON 認識失敗ヘルパーを通じてルーティングされます（コマンドの null-shape + status）。store <unknown subcommand> --json は {status:[{code: unknown_store_subcommand}]} を発行します。list は解決失敗時に {changes|specs: [], root: null} null-shape を保有します。
2. store_root_missing は 2 つの重大度で発行されます（remove での警告、store doctor でのエラー）—コンテキストに依存、上記で文書化。
3. snake_case（store family）対 camelCase（workflow family）キー大文字小文字。root.store_id はすべての場所で snake_case です。
4. 4 つの平行するエンベロープ型宣言が src に存在します。archive診断は target を保有しません。
5. list --json は status キーを変更ごとの文字列列挙として再利用します。
6. validate 出力のみが version フィールドを保有します。
7. schemas/templates はルート選択を無視します（cwd-based、no --store）。
8. 廃止された noun フォーム（change/spec subcommands）は無条件ペイロードを root/status なしで発行します。