decisionscope

decisionscope

decisionscope は、ツールにホスト型の意思決定記録への読み取り専用アクセスを提供します。これは、実際に何が決定されたかを記録するシステムです。行動を起こす前に、ツールは自然言語で記録に質問できます。 「新しいオンボーディングフローは、まだリリースする予定ですか？」と尋ねると、現在の正式な回答、または記録に確かな回答がない場合は明示的な保留が返されます。ポーリングする呼び出し元は、カーソル以降に状態が変わった意思決定を取得することもできます。この記録は回答するだけで、システム内でアクションを実行することはありません。

decisionscope は転送クライアントです。CLI および stdio MCP サーバーとしてローカルで動作し、各呼び出しを JSON-RPC の tools/call リクエストとしてホスト型エンドポイントに転送します。エンドポイントは RITHMO_MCP_URL で指定され、デフォルトではホスト型サービスの https://app.rithmo.ai/api/mcp が使われます。セルフホスト型のデプロイでは、独自のアドレスで同じツールと契約が提供されます。

セットアップ

すべてのリクエストには、組織ごとのサービストークンが Bearer トークンとして付与されます。トークンは必ず1つの組織に対応し、mcp:read スコープを持つ必要があります。また、すべての結果はその組織に限定されます。匿名でのアクセスはできません。

export RITHMO_MCP_TOKEN="<your service token>"
# Optional; only needed for a self-hosted endpoint:
export RITHMO_MCP_URL="https://app.rithmo.ai/api/mcp"

トークンはシークレットストアに保管し、コードには決して記載しないでください。トークンが設定されていない場合、リクエストは送信される前にすべて失敗し、RITHMO_MCP_TOKEN を示すエラーが返されます。

インストール

npx @reneturcios/decisionscope whoami

または、コンテナイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/decisionscope

コンテナはデフォルトで MCP サーバーとして動作します（以下を参照）。CLI として使用するには CLI 引数を渡し、記録にアクセスできるよう、上記の2つの環境変数を -e で渡してください。

CLI

decisionscope query_decision "Are we still shipping the new onboarding flow?"
decisionscope query_decision "What did we decide about GitHub integration?" --type decision
decisionscope query_decision "Who owns the pricing change?" --owner "Priya" --surface jira
decisionscope list_decision_changes
decisionscope list_decision_changes --since "0_" --limit 200
decisionscope whoami

decisionscope --version

結果は JSON として出力されます。終了コード：成功時は 0、操作エラー時（トークンがない場合を含む）は 1、使用方法のエラー時は 2 です。引数はトークンの確認前に検証されるため、不正な形式の呼び出しは必ず使用方法のエラーになります。

MCP サーバー

1つの実行ファイルで両方の形式に対応します。mcp サブコマンドを実行すると、stdio MCP サーバーが起動します。

npx -y @reneturcios/decisionscope mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "decisionscope": {
      "command": "npx",
      "args": ["-y", "@reneturcios/decisionscope", "mcp"],
      "env": {
        "RITHMO_MCP_TOKEN": "<your service token>"
      }
    }
  }
}

オブジェクトの結果は、JSON テキストブロックおよび structuredContent として返されるため、クライアントは res.structuredContent を直接読み取れます。

ツール

ツール	入力	返される内容
query_decision	question（必須）；任意の type（action_item | follow_up | decision）、owner、area、surface	result によって判別される found、found_record、no_record のいずれかの結果です。詳しくは以下を参照してください。
list_decision_changes	任意の since（不透明なカーソル）、任意の limit（整数 1–200、デフォルトは 50）	{ changes, cursor, has_more }。カーソル以降の変更を (changed_at, decision_id) 順に返します。
whoami	（なし）	設定されたトークンの { org_id, scopes }。

query_decision の結果を読み取る

result フィールドには3つのバリアントがあり、その違いは重要です。

• found — コミットメント台帳からの最新の回答です。回答テキストは answer にあり、status、lifecycle_state、owner と source（どちらも判別可能な状態で、単なる null ではありません）、decided_at、due_at、rationale、conditions、director、context、supersedes チェーン（新しい順、循環を防止し、最大12ホップ）、任意の spine、および confidence スコアとともに返されます。confidence を除き、同じ決定に対する found の結果は、呼び出しのたびにバイト単位で同一です。
• found_record — 対象レコードからの最新の回答です。これは回答であり、拒否ではありません。回答テキストは answer ではなく subject.currentAnswer にあります。これは null の場合があり、その場合、対象は記録されていますが、対応に使える回答テキストはありません。
• no_record — 確信を持てる回答がありません。単純な形式は { "result": "no_record" } のみです。型付きの形式では、回答が保留されている理由（closed、no_record、または質問対象の表面がレコードの監視対象でない場合は not_observed）を説明する record が追加されます。premise_check がある場合、safe_to_proceed: false が必ず設定されています。no_record の場合は、決して先に進まないでください。

バリアント名ではなく、使用可能な回答があるかどうかで判定します。

const r = res.structuredContent;
const answer =
  r.result === 'found'        ? r.answer :
  r.result === 'found_record' ? r.subject.currentAnswer :
  null;
if (answer != null && String(answer).trim() !== '') { /* act */ }
else { /* hold — no answer to act on */ }

例外が1つあります。record.reason が record_unavailable: で始まる no_record は、レコード自体を読み取れなかったこと（一時的な障害）を意味します。「決定なし」とは異なるため、保留して再試行してください。

変更をすべて取得する

list_decision_changes はポーリングトリガー向けに作られています。

• 初回呼び出し（since を指定しない場合）は、変更を返さず、現在の先頭カーソルを返します。現在時点から開始し、過去の履歴は再生されません。最初から遡って取得するには、代わりに since: "0_" を渡します。
• has_more は、ページが満杯だったこと（changes.length === limit）を示します。最終ページがちょうど満杯の場合も true になるため、次の呼び出しで変更が0件返ることがあります。これは取得を終了する方法であり、エラーではありません。
• ページに行がない場合、カーソルは変更されずに返されるため、そのカーソルで再ポーリングしても安全で、冪等性が保たれます。
• 各変更には、found の結果と同じレコードのコア情報に加えて changed_at が含まれます。ただし、supersedes、spine、confidence は含まれません。status の範囲はより広く、取り消しは dropped または superseded として現れます。これらの値が found の結果で返されることはありません。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch only)
npm run dev     # run the CLI from source via tsx

ライセンス

MIT — LICENSE を参照してください。