# プランレビューと監査証跡

プロジェクトの制約を取得し、提案されたプランを証拠と比較し、ライフサイクルの成果 (planned、submitted、merged、released、verified) を追跡して、承認された結果を来歴付きで保存します。

- Canonical: https://docs.xmemo.dev/ja/docs/guides/plan-review-and-audit
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: 175b0b54be778ea414d888fa51982bb437637db88fc7fe769ca86ce36f314e63
- Edition-Digest: 76964cb6df0d2bb8811906c5764afd29153f2cd136fc028d234785487ad0d647
- Source-Revision: sha256:fe7c573aca1054f57d1a9a3473cb5469fb99b6d0edc9e97966d5f99565482dbd

## ユーザーの目標とワークフローの境界

この実践的なワークフローは、開発者およびレビューエージェントがソフトウェアの提案、技術仕様、およびアーキテクチャプランをリポジトリの実証的証拠に照らして監査する手順を案内します。レビュー担当者はプランの主張を保存されているプロジェクトの制約と比較し、個別のライフサイクル段階 (planned、submitted、merged、released、verified) にわたる変更を追跡し、承認された合意決定を不可変の来歴帰属とともに永続化します。

## 利用資格と前提条件

監査およびプランレビュー機能は、MCP クライアントプロファイルおよびスタンドアロンの Skill CLI 全体で提供されます:

- MCP cursor-plugin および ordinary-full プロファイル: 包括的なレビュー機能を提供します: get_project_context (読み取り専用プロジェクトパック)、recall_context、search_knowledge、update_project_decision (決定の遷移: resolve、supersede、reopen)、update_project_todo (作業項目の遷移: accept、assign、block、unblock、complete、cancel)、および query_audit (イベントおよび統合レコードの監査)。
- MCP claude-plugin プロファイル: get_project_context、recall_context、create_pending_decision、resolve_decision、record_event、remember、recall、および todo を含みます。
- MCP generic-public、chatgpt-public、および public-only プロファイル: クイックサマリー用の focus="blockers" または focus="status" を指定した get_project_summary(project_id, focus)、および統計用の memory_overview をサポートします。
- スタンドアロン Skill (Claude Code、Codex、OpenClaw): 提供される 1.1.35 help.mjs からの逐語的コマンド: recall-context (84-87行)、search (80-83行)、remember (72-75行)、update (44-47行)、todo-add/list/done (112-123行)、および activity/stats (64-71行)。
- 前提条件: プロジェクトコンテキストおよび監査履歴を照会するための読み取りスコープ (memory:read)、決定を記録し作業項目を更新するための書き込みスコープ (memory:write)。

## 1 つの完全なタスク: サービス移行プランの監査

この合成監査チュートリアルでは、エージェントがプロジェクト proj_security_core の認証アップグレード提案をレビューし、リポジトリの制約に対して主張を検証し、作業項目を遷移させ、承認された結果を保存します。

## プロジェクトの制約と監査履歴を取得する

recall-context または get_project_context を使用して、確立されたプロジェクトガイドラインを取得し、以前の決定の来歴を検査します:

```bash
node scripts/xmemo-skill.mjs recall-context --query "token revocation policy session lifetime proj_security_core" --max_items 6 --max_tokens 2500
```

## 作業項目のステータスを遷移させ、決定を記録する

レビュー TODO を完了としてマークし、来歴を付与して正式な解決策を保存します:

```bash
node scripts/xmemo-skill.mjs todo-done --id todo_rev_401
node scripts/xmemo-skill.mjs remember --content "Approved plan auth_migration_v3: enforced 24h token revocation, strict mutual TLS, and zero unauthenticated fallback. Verified by reviewer audit." --path "plans/auth_migration_v3"
```

## 観察可能な結果

構造化されたプラン監査により、個別のライフサイクルマイルストーンを反映した不可変で検証可能な証跡が作成されます:

- 5 つの異なるマイルストーン状態: プランと作業項目は明示的な段階を経て進行します: planned (ドラフト仕様) -> submitted (正式レビュー要求) -> merged (実装統合完了) -> released (パッケージ化およびデプロイ完了) -> verified (デプロイ後検証合格)。planned を released や verified と混同しないでください。
- 決定論的な監査証跡: query_audit は、イベントのタイムスタンプ、実行エージェントの agent_id、対象のメモリ/決定 ID、および変更前後の状態差分を含む構造化レコードを返します。
- 来歴の保持: recall または recall_context でメモリを照会すると、正確な認可セッションとタイムスタンプを識別する不可変の来歴メタデータが開示されます。

## エージェントがアクセスできるもの

プランレビューと監査を実行するエージェントは、構造化され境界付けられた表現と対話します:

- 追記専用の監査ログ: 監査イベントログは追記専用 (append-only) です。エージェントは過去の決定監査レコードを上書き、不正変更、または削除することはできません。
- バージョン DAG と後継関係: 既存の決定またはメモリを更新すると、その先行バージョンにリンクされた新しいバージョンが作成されます。以前の状態は後継されたバージョンとして引き続き取得可能です (cursor-plugin / ordinary-full の list_memory_versions)。
- 証拠に基づくコンテキスト: recall ツールはプロジェクトメモリから抽出された事実証拠を返すため、エージェントが未検証のモデル推論を記録されたプロジェクト決定と誤認するのを防ぎます。

## 共有とストレージの境界

監査レコードと決定は、厳格なマルチテナントおよびプロジェクトパーティションによって管理されます:

- プロジェクトスコープの境界設定: project:proj_security_core にバインドされた決定と作業項目は、無関係な個人プロジェクトや外部チームスペースから隔離されたままになります。
- スクラッチパッドの除外: 一時的な開発者の下書きメモ (スクラッチパッド)、ローカルデバッグログ、および一時的な思考を永続的な決定レコードに書き込んではいけません。
- 帰属の不可変性: サーバーは、認証された呼び出し元の owner_identity および source_identity をすべての決定に刻印します。クライアントが他のエージェントを偽造またはなりすますことはできません。

## 障害回復

標準的な解決手順に従って、監査の不一致やレビューの競合を管理します:

- 未検証のプランの主張または矛盾: 提案されたプランが既存のアーキテクチャ決定と矛盾する場合、決定を解決済みにしないでください。不一致を説明する詳細な resolution_note を添えて、action="supersede" または action="reopen" で決定を遷移させます。
- 作業項目または決定 ID の欠落: 参照されている todo_id または decision_id が見つからない場合は、todo-list (Skill) または get_project_context(project_id="proj_security_core") を使用してアクティブな項目を照会し、正規の ID を特定します。
- スコープ権限の拒否: エージェントに対象プロジェクトの書き込み権限がない場合、update_project_decision は HTTP 403 Forbidden を返します。ロールの割り当てについてプロジェクト管理者にエスカレーションしてください。

## 関連リファレンス

関連するセキュリティの概念、来歴の詳細、および作業項目の管理については、以下のガイドを参照してください:

- 来歴と帰属: 呼び出し元帰属の詳細については /docs/concepts/provenance-attribution を参照してください。
- TODO 作業項目リファレンス: プロジェクトタスク追跡については /docs/tools/todos を参照してください。
- 元帳取引リファレンス: 財務およびリソース監査については /docs/tools/ledger を参照してください。
- 再開とエージェントハンドオフ: セッションチェックポイント作成ワークフローについては /docs/guides/resume-and-handoff を参照してください。
- プロジェクトガイド: プロジェクトワークスペースの編成については /docs/concepts/projects を参照してください。

## ChatGPT ユーザー

bearer token をチャットに貼り付けずに、ChatGPT が XMemo の設定、プロジェクト事実、意思決定、TODO に永続的にアクセスできるようにします。

ChatGPT/OpenAI app の OAuth フローで hosted XMemo MCP server に接続し、XMemo アカウントに memory:read と memory:write の許可を承認します。

合成の設定またはプロジェクトメモを保存し、新しいチャットを開始してから、作業を続ける前に ChatGPT に XMemo 経由でそれを呼び出させます。

OAuth が失敗する、またはツールが表示されない場合は、direct token を作成する前に、ホストアプリで MCP server からサインアウトし、XMemo server URL を再接続して再試行します。

## Copilot / Codex 開発者

リポジトリの判断、コーディング規約、バグ修正メモ、タスク履歴を IDE と CLI エージェント間で持ち運べます。

利用可能な場合は、VS Code / GitHub Copilot および Gemini CLI に OAuth を使用してください。Copilot CLI、Codex、Cursor、またはその他の直接 MCP クライアントの場合は、XMEMO_KEY をローカル環境またはシークレットストアに保持し、安定した XMEMO_AGENT_INSTANCE_ID を設定してください。

コードベースの判断またはバグ修正を記録し、次の IDE または CLI エージェントに、編集前に関連する XMemo コンテキストを呼び出させます。

呼び出し結果が空の場合は、選択した MCP 設定パス、direct client 用の XMEMO_KEY 環境変数、ホストアプリ内の古い OAuth 認証情報を確認します。

## チーム / エンタープライズ pilot owner

アカウント制御、ソース attribution、エクスポート/削除ワークフロー、レビュー担当者向けに安全な設定証跡で共有メモリを評価します。

保護された XMemo workspace を作成または開き、承認済みユーザーを招待してから、readiness badges に従って OAuth またはスコープ付き direct credential で各クライアントを接続します。

pilot メンバーに合成のチームメモリを保存してもらい、XMemo でソース attribution を確認し、削除/エクスポートとサポート経路をレビューします。

メンバーが接続できない場合は、新しい token を発行する前に、ロール権限、OAuth 承認、クライアント readiness 状態、サポートガイダンスを確認します。

## 自律エージェント operator

headless またはスケジュール済みエージェントが進捗を記録し、過去の判断を取得し、安定した非秘密のインスタンス ID を保持できるようにします。

/api/v1/mcp/config/autonomous-agent を取得します。runner が OAuth + custom headers をサポートする場合は auth_modes.oauth を優先し、完全 headless runner の場合のみ secret store の XMEMO_KEY で auth_modes.xmemo_key を使います。

XMemo に進捗を書き込む合成タスクを 1 つ実行し、runner を再起動して、同じ XMEMO_AGENT_INSTANCE_ID でその進捗を呼び出せることを確認します。

attribution が変わる、または呼び出し結果がインスタンス間で分かれる場合は、XMEMO_AGENT_INSTANCE_ID を git の外に永続化し、runner が起動ごとに再生成していないことを確認します。