brief bar_

Brief Bar — スコアリングサービス（briefs.welance.com）

→ briefs.welance.com — 公開ページ、公開中

Welance Directory	このスコアリングサービスを活用した、ガイド付きブリーフ作成ツールとマーケットプレイス
Brief Bar	サービスの機能 · コンソール · ルール
API ドキュメント	OpenAPI、すべてのフィールドを説明
連携	ワークフローに組み込む4つの方法：コンソール · プロンプト · MCP · API
あなたのブリーフ、あなたのキー	データの送信先、保持するデータ、独自のキーを持ち込む方法
プライバシー · 利用規約	ホスト型サービスとMCPコネクターについて：運営者、保持するデータと保持期間、公正な利用
llms.txt	マシン向けに記述されたバー — アシスタントに参照させてください

8言語に対応し、ビルド工程もトラッキングもありません。同一オリジンからページとAPIを提供します。

---

オープンでバージョン管理されたルールセットに基づいて、デジタルプロダクトのブリーフをスコアリングします。スコアはブリーフの品質を示し、別のゲートは公開が可能かどうかを示します。LLMが行うのはあくまで判定だけです（サーバー側で実行され、キーがサーバーの外に出ることはありません）。すべての数値、ゲート、決定は決定論的なコードが担います。

プロダクトの目標は、期待を明確にし、話し合えるようにするブリーフです。これにより、クライアントとサプライヤーは、契約する前に協業するかどうか、またどのように協業するかを理解できます。プロダクト上の決定と現在のルール適用範囲の監査をご覧ください。監査では改善案を示しますが、現在のスコアリングは変更しません。

このリポジトリはサービスです。ルールセットとエンジンは、インストール可能なパッケージ（brief_bar/）としてこの中にあります。将来、独立したOSSリポジトリに分割し、バージョンを固定した依存関係としてここから利用できるよう、すでに境界を設けています。

brief_bar/     the open ruleset + deterministic engine (the OSS core)
  rules/*.yaml       14 rules, weights sum to 100, ★ = gate requirement
  scoring.yaml       the €10k floor, the 4-requirement gate (anonymised is directory-context, deactivatable), the bands
  score.py           weighted average + gate + decision (no model here)
  judge.py           MockJudge (keyword, offline) + LLMJudge protocol
  llm.py             batched-judge & suggestion prompts (versioned with rules)
  fixtures/*.yaml    labelled briefs = the regression corpus / CI immune system
app/                 the FastAPI service
  main.py            routes, rate limit, CORS; mounts site/ at /
  scorer.py          mock/LLM orchestration + Redis verdict cache
site/                THE public pages: landing, console, rules — served both
                     by GitHub Pages and by the service itself (one surface)
CLAUDE.md · PLAN.md  bootstrap + phased mission for an agentic coding session
GOVERNANCE.md · CONTRIBUTING.md · CODEOWNERS · LICENSE   the open-bar machinery (MIT)
docker-compose.yml   api + redis (the only stateful dependency: ephemeral cache)

クイックスタート

cp .env.example .env          # add a spend-capped PB_OPENROUTER_API_KEY
make up                       # docker compose up --build -d  (api + redis)
make health                   # GET /v1/healthz
open http://localhost:8000    # the console (mock judge works with no key)

APIキーがない場合、サービスはモック専用（即時に動作するキーワードエンジン、完全に決定論的）で実行されます。これだけで開発やテストスイート全体の実行ができます。キーを追加すると、llm 判定器と /v1/suggest が利用可能になります。

API

コンソールでは、最大 10 MB（10,000,000バイト）のPDF、UTF-8 TXT、Markdownドキュメントをインポートできます。テキストの抽出は、同梱のPDF.jsの表示APIとワーカーを使ってローカルで実行されます。元のファイルはアップロードされません。AIで明示的にスコアリングする前に、抽出されたテキストを確認してください。インポートしたドキュメントのスコアリングでは no_cache: true が設定されます。

APIのテキスト長上限は別途設定されており、デフォルトは 1,000,000文字（PB_REQUEST_MAX_CHARS）です。既存の環境変数による上書きも引き続き適用されます。プロバイダーのコンテキスト上限のほうが低い場合があります。インポートに成功しても、すべてのモデルがドキュメントを判定できるとは限りません。テキストが黙って切り詰められたり要約されたりすることはありません。PDFの抽出は1,000ページ、60秒が上限です。抽出可能なテキストがないページ、パスワード保護されたPDF、形式が不正なファイルは拒否されます。必要に応じて、インポート前にOCRを実行するか、空白ページを削除してください。マルチパート／ファイルストレージAPIはありません。

POST /v1/score

{ "brief": "…", "locale": "it", "judge": "mock" }   // judge: "mock" | "llm"

{ "score": 92.0, "band": "Directory-ready", "decision": "blocked",
  "decision_label": "Blocked — hard requirements unmet",
  "gate": { "passed": false, "missing": ["anonymised"] },
  "verdicts": [ { "rule_id": "anonymised", "status": "fail", "confidence": 0.8,
                  "quote": "Stripe … [email protected]", "note": "identifying info present",
                  "weight": 8, "severity": "high", "gate": "pass" }, … ],
  "review_required": false, "low_confidence": [],
  "ruleset_version": "1.0.0+83107baec655", "engine": "[email protected]+83107baec655",
  "judge": "mock", "cached": false }

ruleset_version は監査証跡です。どのバージョンのバーがブリーフを判定したかを正確に固定し、すべての判定結果にブリーフからの一字一句そのままの引用を証拠として添付します。特定のモデルが使われなくなった後も、人が確認できます。（モック判定器はいつまでも再現可能です。LLM判定器は温度0で実行され、(ruleset_version, model, brief) をキーにキャッシュされます。ただし、温度0でもプロバイダーの更新をまたいだ決定論性は保証されません。証跡として期限なく残るのは引用部分です。） Welance は OpenRouter（PB_OPENROUTER_API_KEY）を使用します。公開スコアの判定には deepseek/deepseek-v4-proを使用し、対話型の提案生成には google/gemini-3.1-flash-liteを使用します。セルフホストする場合は、 オプションの直接 Anthropic アダプターも引き続き設定できますが、Welance のデプロイには含まれません。OpenRouter を使用する場合、リクエストではサーバーの許可リスト（PB_OPENROUTER_MODELS、ベンダー名が前置された正確なスラッグをカンマ区切りで指定）から modelを選択できます。それ以外の値は 422 で拒否されます。 解決されたモデルは、再現可能な監査証跡としてすべてのスコアに返されます。 提案の生成では、PB_SUGGEST_MODELで選択した、レイテンシの低いモデルを使用できます。単一ルールの提案は編集可能な人間の選択肢であり、デフォルトでは生成呼び出しを 1 回行います。2 回目の LLM レビューを再び有効にするには、PB_SUGGEST_VERIFY=trueを設定します。 権威あるスコアと複数ギャップの修復ループでは、引き続き検証が行われます。検証を実施した場合、提案レスポンスには検証モデル名が含まれます。 このサービスは OpenRouter の接続プールを再利用し、出力上限を個別に設定しています（PB_SUGGEST_MAX_TOKENS、PB_SUGGEST_ALL_MAX_TOKENS、PB_VERIFIER_MAX_TOKENS）。短い提案 JSON に、判定用の大きな上限は必要ないためです。サービス負担で正常に生成された提案はキャッシュされますが、BYOK 呼び出しは常に共有キャッシュを経由しません。

判定エンジンは通常、プロバイダーへの 1 回の呼び出しですべての 14 項目を判定します。 PB_JUDGE_BATCH_SIZE=5を設定すると、ルールを決定論的に 5/5/4 件のバッチに分割し、最大 PB_JUDGE_CONCURRENCY=3件の呼び出しを同時に実行してから、同じ決定論的な集約処理で統合します。これは運用上のレイテンシ設定であり、スコアリングモードではありません。バッチに未完了のものや失敗したものが 1 つでもあると、スコア全体が拒否されます。デプロイ済みモデルで実環境のmake test-llm-batchingによる比較に合格するまでは、デフォルトの0のままにしてください。

独自のキーを使用する場合は、X-LLM-Key: <your OpenRouter key>を送信すると、そのキーで呼び出しが実行されます。このデプロイでPB_BYOK_MODELSが設定されていない限り、有効な OpenRouter モデルのスラッグを使用できます（費用は利用者負担です）。キーはリクエストごとに使用され、保存もログ記録もされません。BYOK によるスコアリングでは共有の判定キャッシュを意図的に経由しないため、提供されたキーで常に新しい呼び出しが行われます。利用額に上限を設定したキーを使用してください。コンソールでは、ライブモードのオプション項目として設定できます。

他者のサーバーにキーを送信することには、この説明だけでは不十分です。キーを取り扱うすべての処理、その処理が行われないことを証明できる箇所、そして正直に開示すべき限界については、briefs.welance.com/security.htmlをご覧ください。この主張はtests/test_byok_leak.pyによって担保されており、キーがログ、キャッシュへの書き込み、またはレスポンスに到達した場合はテストが失敗します。

その他のエンドポイント：

• POST /v1/suggest {brief, rule_id, locale, model?} → 1 つのギャップに対する個別の修正案（LLM）。
• POST /v1/suggest/all {brief, rule_ids?, locale, model?} → 不合格のギャップごとに 1 つの修正案を返します。rule_idsを省略すると、自動検出します（LLM）。
• GET /v1/rules → ディレクトリ UI 用の全カタログ（id、title、weight、gate、criteria、references）。
• GET /v1/models → 有効な判定モデル（default + available）を返し、モデル選択に使用します。
• GET /v1/healthz → サービスのリリース、ルールセットのバージョン、エンジンと LLM の利用可否。
• GET / → 対話型コンソール。

提案レスポンスにはX-PB-Generation-Ms、X-PB-Verification-Ms、 X-PB-Cached、X-PB-Cache-Ms、X-PB-Modelと標準のServer-Timingヘッダーが含まれます。これにより、プロンプトやドキュメントの内容を公開することなく、呼び出し元はモデルのレイテンシとネットワーク／UI のレイテンシを区別できます。/v1/healthzでは、オプションの Redis キャッシュ／レート制限ストアが現在接続されているかどうかも報告されます。

MCP：無料で利用でき、モデルはご自身で用意

https://briefs.welance.com/mcp は無料のリモート MCP サーバーです（Streamable HTTP、ステートレス JSON）。**こちらのモデルは一切動作しません。**お使いのアシスタントのモデルが、サービスの判定用プロンプトを使って概要を評価し、bar のコードがその判定結果を検証して、/v1/score と同じエンジンで計算します。

ツール	機能
get_rules	最新のカタログ：基準、重み、ゲート、ポリシーコンテキスト、ステータススコア、評価帯、バージョン
get_brief_template	最新のルールに基づく Markdown 形式の概要テンプレート。各セクションで必要な入力項目も含みます
get_judge_prompt	お使いのモデル用の判定プロンプト（サービスのものと一言一句同じ）と判定結果の JSON Schema
get_improvement_prompt	お使いのモデルが概要を改善するための、ゲートを優先した作業順序
check_brief	決定論的なチェックのみ（連絡先、明記された予算／スケジュール、データの手がかり、プレースホルダー）。意味的な網羅性の確認は不完全で、スコアにはなりません
aggregate_verdicts	お使いのモデルによる判定結果を検証し（各ルールが一度ずつ出現すること、引用が原文と一致すること、最新バージョンであること）、集計します
bar_status	最新のルールセットのバージョンと機能

プロンプト（score_with_your_model — ゲートを優先するワークフロー全体 —、judge_brief、improve_brief、brief_template）およびリソース（perfect-brief://rules、…/template、…/judge-prompt、…/verdict-schema）としても利用できます。同じ仕様は /v1/byo/* のプレーン HTTP でも利用できます（/docs を参照）。

**参考情報であり、権威ある判定ではありません。**集計結果には、ルールセットのバージョン、エビデンスのエラー、パターンの競合とともに、evaluation_source: "client"、authoritative: false が付与され、welance/directory でチームを探す → へのリンク（PB_DIRECTORY_URL）が含まれます。公開を許可することはできません。welance/directory は /v1/score ですべての概要を独自に採点します。

インストール

Claude（claude.ai、Desktop）：Settings → Connectors → Add custom connector → https://briefs.welance.com/mcp。Claude Code：

claude mcp add --transport http perfect-brief https://briefs.welance.com/mcp

ChatGPT：Settings → Apps & Connectors → Advanced → enable developer mode → Create → URL https://briefs.welance.com/mcp、認証なし （利用可否はプランによって異なります）。

Cursor（~/.cursor/mcp.json または .cursor/mcp.json）：

{ "mcpServers": { "perfect-brief": { "url": "https://briefs.welance.com/mcp" } } }

VS Code（.vscode/mcp.json または MCP: Add Server… → HTTP）：

{ "servers": { "perfect-brief": { "type": "http", "url": "https://briefs.welance.com/mcp" } } }

ローカル（stdio） — コマンドを実行できる任意のクライアントで、同じツールを利用できます：

{ "mcpServers": { "perfect-brief": { "command": "uvx",
  "args": ["--from", "git+https://github.com/welance/perfect-brief#subdirectory=mcp-server", "perfect-brief-mcp"] } } }

プロトコル：リビジョン 2024-11-05 → 2025-11-25 は initialize を通じてネゴシエーションされます（未知のリビジョンには 2025-11-25 で応答します）。ステートレスな 2026-07-28 エンベロープ（server/discover）も提供されます。JSON-RPC のバッチは 400 で拒否されます。セッションもイベントストリームもありません。

以前のコネクターは /mcp-hosted で利用できます。このコネクターの score_brief／suggest_fixes はサービスの判定モデルを使用します。PB_MCP_HOSTED_ENABLED=true でない限り無効で、有効にした場合も同じアドレスごとの制限が適用されます。Official MCP Registry の登録案は registry/ にあります。

welance.com/directory での利用方法

directory は純粋な利用側です。判定結果を表示し、採点ロジックは一切保持しません：

const res = await fetch("https://briefs.welance.com/v1/score", {
  method: "POST",
  headers: { "content-type": "application/json", "x-api-key": KEY },
  body: JSON.stringify({ brief, locale, judge: "llm" }),
}).then(r => r.json());
// res.decision drives publish/blocked/with-reservation; res.gate.missing lists why.
// persist res together with res.ruleset_version for a reproducible audit trail.

ユーザーの入力中（デバウンスあり）と送信時に採点します。判定結果の永続化が必要な場合は、otto.welance.com がサーバー間で同じエンドポイントを呼び出します。

設計メモ

• ステートレスなサービスです。 スコアは (brief, ruleset_version) の純粋関数です。 データベースはありません。Redis には一時的な判定キャッシュとレート制限用カウンターのみを保持し、Redis がダウンしてもサービスは適切に機能し続けます。
• ルールセットを依存関係として扱います。 brief_bar/ は独自のバージョンと CI コーパスを持つインストール可能なパッケージです。現在はここにベンダーとして同梱していますが、welance/brief-bar に切り出してタグを固定する作業は、コード変更を伴わないそのままの移行です。
• ゲートが重大度の上限に取って代わります。 重大な不足事項は、数値にひそかにペナルティを課すものではなく、明示的な公開要件（clear-title、problem-defined、budget-floor、anonymised）です。
• オペレーターの誓約。 ルールはブリーフを評価し、OPERATOR-COVENANT.md は私たち自身を評価します。リードの採掘やブリーフを使ったトレーニングは行わず、welance 自身のブリーフにも同じ基準を適用します（welance はチームとして Directory で提案を行います）。各誓約にはその適用方法を明記し、コードで検証できるものは CI でテストします。
• ガバナンス。 誰でも PR でルール変更を提案できます。CI のフィクスチャコーパスは免疫システムとして機能し、数値を変える変更には、公開の場でフィクスチャの変更も伴います。ルール変更の PR には、マージ前にコミュニティでの7日間の議論期間を設けます。PR テンプレートには、完全な提案に必要な内容が案内されており、GOVERNANCE.md には期間の詳細が記載されています。 基準に異議を唱えることも、このリポジトリの重要な利用方法です。

決定事項

重要な影響を伴うアーキテクチャ上の決定は、ADR として docs/decisions/ に記録されています。

• 0001 — モデルをまたいだ検証: すべての AI による提案を2つ目のモデルがレビューする理由（自己選好バイアス）と、レビュー担当のモデルが現在、生成モデルと同じラボに属している理由（コスト）を説明します。環境変数の行を1つ変更すれば、異なるラボによるレビューに戻せます。
• 0002 — デフォルトモデルの選定: 選定基準、DeepSeek V4 pro/flash の組み合わせの根拠となった日付入りの価格スナップショット、見直しのタイミングを説明します。

開発とテスト

pip install -e ".[dev]"
make test        # fixture corpus + API tests, all on the deterministic mock judge
make lint        # ruff
make typecheck   # mypy
make dev         # uvicorn --reload on :8000

デプロイ（OVH Kubernetes）

イメージは :8000 で動作するステートレスな HTTP サービスで、/v1/healthz のライブネスプローブを備えています。標準的な Deployment、Service、Ingress に、小規模な Redis を追加します（キャッシュなので、単一レプリカでもマネージドインスタンスでも問題ありません）。Secret/ConfigMap を使って PB_* を設定し、PB_CORS_ORIGINS を Directory のオリジンに限定してください。API は水平スケーリングし、キャッシュは Redis を介して共有します。

テキストとドキュメントの境界

API が受け付けるのはテキストであり、アップロードではありません。brief はサイズ上限のある1つの文字列です。Directory は、対応する PDF、DOCX、テキスト系ドキュメントをブラウザー内でローカルに読み取り、抽出したテキストを信頼できないコンテキストとして含める場合があります。元のバイトデータ、画像、任意のバイナリはこのサービスに送信されず、保存も添付ファイルとしての公開もされません。Directus へのマルチパート公開は、Directory の別個のワークフローです。

同梱のコンソールでは、デフォルトでモック判定を使用します（オフラインで即時に動作します）。ライブモードでは、このサービスの /v1/score と /v1/suggest を呼び出します。呼び出し元がリクエストごとの BYOK キーを明示的に指定しない限り、プロバイダーの認証情報はサーバー側に保持されます。