ce-proof

Proof - 共同編集型 Markdown エディター

Proof は、人間とエージェント向けの共同編集型ドキュメントエディターです。Bash から HTTP を介して、ホストされた Web API https://www.proofeditor.ai にアクセスします。

成果： ユーザーが使用可能なトークン付き Proof リンクを取得するか、依頼された閲覧、コメント、提案、または編集がドキュメントに反映されます。

完了条件： 操作がその操作自体のレベルで確認され、ユーザーが結果と簡潔な概要を受け取っていること。作成は、返された tokenUrl によって確認します。変更は ok: true によって確認します。202 または partial: true の応答の場合は、v3/document を再読み込みして確認します。プルは、書き込まれたローカルファイルによって確認し、読み取りは返された内容によって確認します。

最初の Proof の読み取りまたは変更を行う前に、HTTP または MCP のどちらを使う場合も、references/api.md を読んでください。 このファイルでは、エンドポイントの share/markdown、v3 のドキュメントおよび編集エンドポイント、プレゼンス、タイトル、DELETE /api/documents/<slug> を定義しています。また、操作の一覧表、エラーと再試行の分類、Claude Code 向けの curl 権限に関するヒントも記載しています。

共有ドキュメントをレビューする前、ドキュメントを作成して共有する前、ドキュメントをローカルファイルにプルする前に、references/workflows.md を読んでください。これらのフローには、そこで正確な手順が記載されています。

型付きの proof_* MCP ツール（proof_share_markdown、proof_v3_document、proof_v3_edit、proof_presence、proof_document_title、proof_document_delete、proof_report_bug）がハーネスですでに利用可能な場合は、そちらを優先してください。利用できない場合は、HTTP の手順を使用します。MCP モードでは、サーバーが by、X-Agent-Id、プレゼンスの ID を設定します。サインイン中のユーザーが所有していないドキュメントを編集したり、そのプレゼンスを扱ったりする場合は、Proof URL の ?token= の値を shareToken として渡してください。

削除の権限は MCP モードでも変わりません。所有者が設定されていないドキュメントには ownerSecret が必要で、所有者が設定されたドキュメントには所有者のセッションが必要です。shareToken として渡された編集者の accessToken では削除できません。

ID

すべての書き込みには、次の両方のフィールドを使って属性が記録され、値は変わりません。マシン ID は ai:compound-engineering で、すべての操作の by と X-Agent-Id ヘッダーに設定します。表示名は Compound Engineering で、POST /presence の name として渡します。これはドキュメントのセッションごとに一度設定し、Proof がその ID をエージェント ID に紐付けられるようにします。別のサブエージェントにドキュメントを所有させる場合、呼び出し元は異なる identity のペアを渡せます。ai:compound のような別の値を独自に作らないでください。

認証情報と境界

• accessToken は、読み取り、編集、プレゼンス、イベントで日常的に使用するベアラートークンです。ownerSecret が持つのは削除などのオーナー権限操作に限られ、日常的に使用するベアラートークンではありません。作成時に両方を取得し、シェル変数などを使って、セッション用の ownerSecret を accessToken とは別に保存してください。ドキュメントのオーナーが未設定の間、削除には ownerSecret が必要です。どちらもリポジトリで追跡されるファイル、コミット、永続的なログに含めてはいけません。また、ownerSecret をユーザー向けの文面に記載してはいけません。
• トークン付きリンク（tokenUrl）を人に渡し、/d/<slug> のみのリンクは渡さないでください。そのリンクのトークンがあれば、サインイン済みのユーザーはオーナー未設定のドキュメントをオーナーとして登録できます。
• 公開作成されたドキュメントは、サインイン済みの Every ユーザーがブラウザーでオーナーとして登録するまで、オーナー未設定です。オーナーとして登録すると ownerSecret は永久に無効になりますが、accessToken は引き続き機能します。その後の削除にはオーナーの Every セッションが必要になるため、オーナーに依頼するか、そのセッショントークンを使用してください。次のいずれかの応答が返った場合、シークレットは無効になっています。code: "DOCUMENT_DELETE_FORBIDDEN" と reason: "CREDENTIAL_NOT_OWNER" を伴う 403、または作成時の ownerSecret を提示したときの 401 です。再試行せず、そのシークレットの使用を中止してください。reason: "DOCUMENT_HAS_NO_OWNER" は逆の状態を示します。ドキュメントはまだオーナー未設定であるため、削除できるのは最初に取得した ownerSecret のみで、Every セッションでは削除できません。
• ユーザーが明示的に許可しない限り、シークレット、認証情報、API キー、非公開トークン、機密性の高い個人データを Proof ドキュメントに記載してはいけません。また、ユーザーに知らせず、リポジトリで追跡されるプロジェクトドキュメントを Proof リンクに置き換えてはいけません。
• Markdown を空にしても、コメントマークは消去されません。引用やコメントは、共有認証情報を持つ人なら誰でも引き続き読めるため、コンテンツを消去してもプライバシーのクリーンアップにはなりません。ドキュメントを削除すればクリーンアップできます。オーナー未設定の場合は ownerSecret を使い、オーナー登録後はオーナーとして削除してください。
• 公開後の引き渡し時に、自動で削除してはいけません。レビュー用ドキュメントは残してください。ユーザーから依頼されたとき、または一時的なスクラッチドキュメントを明示的に作成し終えたときに削除してください。

公開モード

主な用途は一方向の公開です。既存のローカル Markdown ファイルをすべて読み込み、その内容を新しいドキュメントの本文として投稿し、共有可能な URL をユーザーに渡します。ローカルファイルが正本です。公開によってディスク上の内容が同期されることはありません。

この仕組みを使う入口は 2 つあります。1 つは、ローカルの Markdown ファイルを指定するだけのユーザーリクエスト（「これを Proof で共有して」「このドキュメントの Proof リンクを作って」など）です。ファイルが特定できない場合に限り、どのファイルかを確認してください。上流の呼び出し元はないものとして扱います。もう 1 つは、ファイルパスとタイトルを渡す ce-brainstorm、ce-ideate、または ce-plan からの引き渡しです。

公開するのは Markdown のみです。ソースが HTML 形式の統合プランの場合は、アップロードせず、ローカルのブラウザーで開くパスを返してください。統合プランを公開する場合、準備状況が分かっていれば、タイトルにその状態を示してください。例：Plan: <title> (requirements-only) または Plan: <title> (implementation-ready)。

手書きやプレースホルダーの内容ではなく、ソースファイルのバイト列をそのまま公開してください。references/workflows.md に、改行、引用符、バッククォートを正しくエスケープする jq --rawfile の手順があります。公開後の引き渡しが済んだら、URL をユーザーに示して制御を戻してください。

編集

GET /api/agent/<slug>/v3/document と POST /api/agent/<slug>/v3/edit は、エージェントが読み取りと書き込みを行う唯一のエンドポイントです。コメント、返信、解決、提案、コンテンツの変更はすべて、v3 の編集本文における operations です。そのため、references/api.md で読んでいないパスは、あなたが作り出したものです。

編集する前に、v3/document を信頼できる情報源として読み取ります。次に、変更内容を表す最も限定的な操作を選びます。文章には、範囲を限定した replace、insert、または delete を使用します。変更を変更履歴として表示する場合は suggest を使用します。set_document を使用するのは、ユーザーが文書全体の置き換えを求めた場合、または変更を限定的に表現できない場合だけです。対象は markdown 内の表示テキストであり、生の Markdown 構文やブロック参照ではありません。

読み取り結果の comments[] と suggestions[] がレビュー状態です。返信、解決、解決解除、承認、または却下は ID で行います。v3 にコメント削除操作はありません。orphaned: true とマークされたコメントも読み取りと返信はできますが、以前の引用は現在有効なアンカーではありません。

次のエラーが発生した場合は、再試行する前に停止して確認してください。

• TARGET_AMBIGUOUS — アンカーが複数箇所に一致し、何も変更されていません。error.candidates の occurrence／before／after を使って曖昧さを解消します。暗黙に最初の一致が選ばれると決めつけず、コメントを確認なしに再試行しないでください。
• retryable: false — リクエストを修正します。error.current を伴う retryable: true — current に基づいて対象を再特定してから、一度だけ再試行します。
• 202／PENDING、または partial: true を伴う ok: false — 書き込みがコミットされた可能性があります。後続処理を行ったり成功を報告したりする前に、v3/document を再度読み取り、失敗した操作だけを再試行します（同じ Idempotency-Key を使うと安全に再実行されます）。
• 最新の読み取り後に安全な再試行を一度行っても失敗する場合は、繰り返し再試行せず、references/api.md に従ってバグを報告します。

文書をローカルファイルにダウンロードすると、そのファイルは上書きされます。ダウンロードがユーザーの依頼ではなく別の操作に伴う副作用である場合は、まずパスを確認してください。