ai-architect-mcp-spec

幻覚による仕様がコードになる前に見つけます。
すべてのシンボルが存在すること、すべての受け入れ基準が要件にたどれること、測定なしでパフォーマンスの主張が通らないことを、チェックのループにモデルを介さず、決定論的に検証します。
Codex、Gemini CLI、Claude Code、CI で動作します。お使いのマシン上で実行できます。

エージェントが尋ねられること · はじめに · パイプライン · ツール · 検証 · 較正 · アーキテクチャ · ゼテティック標準

_{それぞれ単独で動作する 3 つの MCP サーバーの 1 つです。メモリー、コードグラフ、仕様検証を提供します。エコシステムの他の要素との連携方法 ↓}

---

PRD を作成する AI エージェントは、いずれ存在しない関数をでっち上げたり、測定できないレイテンシを主張したり、テスト対象であるはずの要件に結び付かない受け入れ基準を書いたりします。出力は自信に満ちているように見えますが、実行に移せるものではありません。パイプラインの次の工程であるコード生成、チケットのインポート、スプリント計画は、幻覚をひそかに引き継いでリリースし、後になってその代償を払うことになります。

AI Architect MCP Spec は、こうした問題を構造レベルで解決する TypeScript 製の MCP サーバーです。移植可能な検証器により、Codex、Gemini CLI、Claude Code、CI、その他の stdio MCP ホストで、同じ決定論的な厳格な出力ルールとセクション横断のトレーサビリティチェックを利用できます。パイプライン全体は、ホストがオーケストレーションアクションを実行することで動作するステートレスなリデューサー（step(state, result?) → next_state, action）です。現在、完全なパイプラインを実行できるホストとしてパッケージ化されているのは Claude Code のみです。セクションは一度に 1 つずつ生成され、ホストに渡される前に検証されます。また、根幹をなす主張はすべて、zetetic-team-subagents から選ばれた卓越した推論エージェントのパネルによって、ai-architect-mcp-codebase のコードベースグラフを基に判定されます。ループは閉じています。各判定者の信頼性は履歴から較正され、再試行の予算は生存統計から算出され、KPI ゲートは固定されたベースラインに照らして調整されます。また、ホールドアウトパーティションは機械的に封印され、評価前に較正結果をのぞき見できないようになっています。

得られるもの

• コードに照らしても耐えられる仕様です。 シンボルは実際のコードベースのグラフと照合されるため、PRD が先週改名された関数を参照することはありません。
• 実際に検証されるトレーサビリティです。 すべての受け入れ基準は要件に結び付ける必要があり、番号の抜けも見過ごされずに検出されます。
• 測定なしの PASS はありません。 判定分類では、レイテンシ、スループット、fps、ストレージに関する主張を PASS にすることはできません。確信ありげな推測ではなく、SPEC-COMPLETE または NEEDS-RUNTIME が返されます。
• 同調する判定者へのガードです。 5 件以上の主張に対してパネルの全員が 100％同意した場合、合意と見なされるのではなく、distribution_suspicious が発生します。
• 普段の作業環境で動作します。 決定論的な検証ツールは Codex、Gemini CLI、Claude Code、CI で利用でき、完全な生成パイプラインは、そのオーケストレーションアクションを実行できるホストで動作します。

主権を保った検証と、環境に配慮する設計意図

主権性は、現時点での実装です。 サーバーはステートレスなリデューサーです。step(state, result?) → next_state, action の形で動作します。アクションを出力し、ホストがそれを実行します。お使いのマシン上で動作し、判定を求めて外部に通信することはありません。

環境への配慮は、目指しているものです。 この仕組みの要は、兄弟プロジェクトとは異なります。それは 手戻りの回避 です。幻覚を含む PRD は、誰かが気付く前にコード生成、チケットのインポート、スプリント計画へと引き継がれ、その内容を使ったすべての工程をやり直すことになります。パイプラインの中でそれを検出する最もコストの低い場所は仕様作成の段階です。また、検出そのもののコストを抑えるため、次の 3 つの設計上の工夫をしています。

• チェックではモデルを使いません。 Hard Output Rules とセクション間のトレーサビリティは決定論的です。壊れた FR-AC リンクの検出に推論コストはかかりません。
• セクションは完成前に失敗を検出します。 それぞれのセクションは、ホストに渡される前に検証されます。すべて生成してから破棄することはありません。
• 再試行の予算は推測ではなく、導出されます。 MAX_ATTEMPTS は Kaplan-Meier の生存分析に基づいて算出され、map_failure_to_retrieval は再試行の前に 修正のための クエリを送ります。直前に失敗したコンテキストをそのまま使う再試行は、無駄の証拠を残すだけです。

兄弟リポジトリと同様、このリポジトリでは エネルギー消費量や CO₂ の数値を公開していません。ジュールを測定しておらず、手戻りの回避は測定値ではなく設計上の主張だからです。

10 個のパッケージ。17 個の MCP ツール。20 個のパイプラインステップ（PRD 生成が 11 個、オプトイン式の実装が 9 個）。合意による複数判定者の検証。外部根拠の反証要素を用いたクローズドループのキャリブレーション。1506 件のテスト。すべての数値定数には、引用元、ベンチマーク、または // source: provisional heuristic という明示があります。

クローズドループの信頼性キャリブレーション

検証は一度きりの合否レポートではありません。主張の解決ごとに観測結果をキャリブレーションリポジトリに書き戻し、コンセンサスの実行ごとに履歴からキャリブレーション済みの事後分布を取得できます。また、すべてのクローズドループで外部の対照群を実行し、キャリブレーションの効果を想定ではなく 測定 します。

• 判定者ごとのベイズ信頼性キャリブレーション — claim_type ごとに感度と特異度を分けた Beta(7,3) 事前分布を使用します。事後分布は SQLite ベースの ReliabilityRepository に保存され、主張の解決ごとに観測結果が書き出されます。
• MAX_ATTEMPTS の再試行キャリブレーション — Kaplan-Meier 生存分析の計算（Greenwood および Brookmeyer-Crowley の信頼区間を含む kmEstimate / kmMedianAttempts / logRankTest）を使用します。Schoenfeld のサンプルサイズ算出は、測定済みの event_rate=0.4762、CP CI [0.4456, 0.5069] に照らしてイベント率補正され、約 519（従来は 823）となります。
• KPI ゲートの調整 — Clopper-Pearson の正確な信頼区間、5 つのバケットを用いる detectMachineClass によるマシンクラスごとの wall_time 正規化、凍結ベースラインのコンテンツハッシュ検証、loadCalibratedGates と hold_provisional によるラチェット保護を使用します。
• プラン不一致の発生率 — Wheeler 1995、Western Electric 1956 に基づく XmR 管理図で測定します。診断プレフィックスと正規表現マッチャーの間のドリフトを検出する、合成インジェクションの往復プリフライトも実行します。
• 外部根拠に基づくホールドアウト部分集合 — Ajv スキーマオラクル、mathjs オラクル、tsc サブプロセスのコードオラクル、validateSection 仕様オラクルを使用します。スタブモードでの捏造は、型付き例外 OracleUnavailableError のスローに置き換えられています。これがアノテーターとの循環性を断ち切る層です。判定者とオラクルは推論経路を共有しません。
• CC-3 の強制的な探索対照群 — 各クローズドループでは、事前分布に戻す 20% の区画を切り出します。これがなければ、キャリブレーションが実際に進歩をもたらすかどうかにかかわらず、キャリブレーションの上でキャリブレーションを行うことが進歩のように見えてしまいます。
• アーム間の比較指標 — computeAblationComparison / computeReliabilityComparison / computeKpiGateComparison により、対応のあるブートストラップ信頼区間が生成されます（Efron & Tibshirani 1993 §16.4、決定論的な mulberry32 RNG、小数点以下 12 桁の再現性固定）。結果は反証可能な推奨であり、calibrated_helps、prior_helps、inconclusive_underpowered のいずれかです。
• 機械的に強制されるホールドアウト区画の封印 — 3 つの封印済みロックファイル（maxattempts-heldout.lock.json、kpigates-heldout.lock.json、heldout-partition.lock.json）によって、評価前に区画の sha256 が確定されます。封印済み区画でアーム間の指標を計算する方法は、SEAL_VERIFIED typeof センチネルのみです。それ以外を渡すと境界で型エラーになります。
• 本番モードのディスパッチャー — makeProductionDispatcher と AgentInvoker インターフェースを使用します。CLI の --mode production|canned フラグにより、キャリブレーションが実際の判定結果と定型の判定結果のどちらを参照するかを選択できます。オフラインでの再現性を保つため、定型アームも引き続き利用できます。

---

エージェントが質問できること

start_pipeline(feature_description, codebase_path?)
  → returns the first NextAction; the host executes it and feeds the result
    back via submit_action_result. Eleven steps later: 9 PRD files written.

submit_action_result(run_id, result)
  → drives the reducer one more step. The host sees only SUBSTANTIVE actions
    (ask_user, call_pipeline_tool, call_cortex_tool, spawn_subagents,
     write_file, done, failed). emit_message is coalesced into the
     messages array; the host never has to "advance past" a banner.

validate_prd_section(content, section_type)
  → deterministic Hard Output Rules — zero LLM calls, pure regex/parsing.
  → returns: violations[], hasCriticalViolations, totalScore.

validate_prd_document(sections[])
  → cross-section checks: SP arithmetic, AC numbering, FR-AC coverage,
    test traceability. Catches what per-section validation misses.

coordinate_context_budget(prd_context, completed_sections[])
  → per-section retrieval/generation token budgets so Cortex recall and
    section drafting don't fight over the same context window.

map_failure_to_retrieval(violations[])
  → closes the validation→retrieval feedback loop. When a section fails
    validation, this returns the corrective Cortex query that would
    have prevented the failure.

---

はじめに

_{名称について。 このプロジェクトは、Claude Code、Codex、Gemini、MCPB、PyPI/npm、MCP Registry の各提供先で ai-architect-mcp-spec として公開されています。0.7.0 で Registry エントリーとプライマリバンドルがこの名称に移行し、0.8.0 で移行が完了したため、prd-spec-generator プラグインもリリースエイリアスもどこにも残されていません。以前の io.github.cdeust/prd-spec-generator の Registry バージョンは、有効なまま凍結されるのではなく、正規エントリーへのリンクを付けて非推奨になっています。}

インストール（マーケットプレイス — 推奨）

claude plugin marketplace add cdeust/ai-architect-mcp-spec
claude plugin install ai-architect-mcp-spec@ai-architect-mcp-spec-marketplace

Claude Code セッションを再起動してください。17 個の MCP ツールは、最初の stdio ハンドシェイク時に登録されます。その後、次を実行します。

/generate-prd build OAuth login for the admin console

プラグインに同梱されている mcp-server/index.js の MCP サーバーは自己完結型です （エビデンスリポジトリ用の任意のネイティブ依存関係である better-sqlite3 のみを使用します。不在の場合は、正常にインメモリモードへフォールバックします）。

prd-spec-generator からの移行

旧プラグインとマーケットプレイスは非推奨の公開物であり、別名ではありません。正式なパッケージをインストールする前に、これらを削除してください。

claude plugin uninstall prd-spec-generator@prd-spec-generator-marketplace
claude plugin marketplace remove prd-spec-generator-marketplace
claude plugin marketplace add cdeust/ai-architect-mcp-spec
claude plugin install ai-architect-mcp-spec@ai-architect-mcp-spec-marketplace

prd-spec-generator:generate-prd を使用していた呼び出し元は、ai-architect-mcp-spec:generate-prd を使用する必要があります。prd-gen MCP サーバー名、@prd-gen/* プライベートワークスペースパッケージ、PRD_GEN_* 環境変数、.prd-gen ローカルデータディレクトリは、安定した内部インターフェースとして引き続き使用されます。これらによって非推奨の公開物がインストールされたままになることはありません。

プラグインスコープの MCP ツール名には、公開物名と安定したサーバーキーの両方が含まれるため、プロンプト、自動化、許可リストではプレフィックス全体を移行する必要があります。

• 旧：mcp__plugin_prd-spec-generator_prd-gen__<tool>
• 新：mcp__plugin_ai-architect-mcp-spec_prd-gen__<tool>

Gemini CLI でも、インストール済みの拡張機能はマニフェスト名で識別されます。旧 ID の拡張機能をそのまま更新するのではなく、置き換えてください。

gemini extensions uninstall prd-spec-generator
gemini extensions install https://github.com/cdeust/ai-architect-mcp-spec

関連エコシステム

パイプラインでコードベースのインテリジェンス、永続メモリ、genius-agent パネルを利用できるようにするには、効果を最大限に発揮するため、関連する 3 つのプラグインをインストールしてください。

claude plugin marketplace add cdeust/ai-architect-mcp-codebase  # codebase graph intel
claude plugin marketplace add cdeust/Cortex                  # persistent memory
claude plugin marketplace add cdeust/zetetic-team-subagents  # the genius + team agents

claude plugin install ai-architect-mcp-codebase
claude plugin install hypermnesia-mcp
claude plugin install zetetic-team-subagents

各プラグインは単独でも役立ちますが、組み合わせると ai-architect エコシステムになります。上記の関連エコシステムを参照してください。

ソースからのビルド

開発時、または監査サイクルをローカルで実行する場合は、次の手順に従ってください。

git clone https://github.com/cdeust/ai-architect-mcp-spec.git
cd ai-architect-mcp-spec
pnpm install --frozen-lockfile
pnpm build      # builds all 9 buildable packages via tsc
pnpm bundle     # produces the standalone mcp-server/index.js
pnpm test       # 1506 tests (vitest workspace, all packages; the
                # ai-architect-mcp-codebase wire contract is pinned
                # unconditionally — see docs/INTEGRATION-TESTING.md)

pnpm verify は、上記のすべて（インストール＋ビルド＋バンドル＋テスト）を実行します。CI と同じです。

ソースからビルドするための前提条件： Node.js 20.x または 22.x、pnpm v10 以降（corepack enable && corepack prepare pnpm@10）。

オフラインでのスモークテスト

# Reducer end-to-end without a real host (uses the canned dispatcher):
pnpm test --filter @prd-gen/orchestration smoke

# Benchmark KPI run:
pnpm test --filter @prd-gen/benchmark pipeline-kpis

どちらも M シリーズの Mac で 2 秒未満で実行されます。LLM の呼び出しも MCP トラフィックもなく、リデューサーは用意された ActionResults のみを使って完全に動作するため、オフラインで挙動を監査できます。

他の MCP ホストでの使用

まず、適用範囲を正確に説明します。フルパイプラインはホストに依存します。リデューサーはアクション（ask_user、spawn_subagents、write_file）を返しますが、これらはアクションを実行して結果を返すホストを前提としています。このワークフロー用にパッケージ化されたホストは、Claude Code（プラグインと /generate-prd スキル経由）のみです。

Codex と Gemini には、代わりにポータブルな Spec Verifier を提供します。これは LLM を使わないインターフェースで、決定論的なツールが 2 つだけあり、audit-prd と validate-spec の各スキルを利用できます。

• validate_prd_section — 単一のセクションに対する出力ルールの厳格なチェック
• validate_prd_document — セクション間のチェック（SP/AC/FR/テストのトレーサビリティ）

リポジトリのマーケットプレイスから Codex にインストールします。

codex plugin marketplace add cdeust/ai-architect-mcp-spec
codex plugin add ai-architect-mcp-spec@ai-architect-mcp-spec-marketplace

同じパッケージを Gemini CLI 拡張機能としてインストールします。

gemini extensions install https://github.com/cdeust/ai-architect-mcp-spec

どちらのマニフェストも、mcp-server/index.js を --profile verifier 付きで起動します。既存の Claude マニフェストではプロファイルを渡さないため、デフォルトの 17 ツールを備えた full インターフェースが維持されます。

違反がゼロという結果は、ドキュメントが実装済みの構造ルールを満たしていることを意味します。事実の正確性、製品価値、実装可能性、セキュリティ、意味上の正しさを証明するものではありません。

パッケージ化されていない MCP ホストの場合は、リポジトリをクローンし、同じ限定プロファイルを明示的に選択してください。/abs/path はクローン先のパスに置き換えてください。

git clone https://github.com/cdeust/ai-architect-mcp-spec.git /abs/path/ai-architect-mcp-spec
cd /abs/path/ai-architect-mcp-spec/mcp-server
npm ci --omit=dev

OpenAI Codex CLI（~/.codex/config.toml。ChatGPT デスクトップアプリおよび Codex IDE 拡張機能と共有）：

codex mcp add prd-spec -- node /abs/path/ai-architect-mcp-spec/mcp-server/index.js --profile verifier

Cursor（.cursor/mcp.json）および Windsurf （~/.codeium/windsurf/mcp_config.json）：

{
  "mcpServers": {
    "prd-spec": {
      "command": "node",
      "args": [
        "/abs/path/ai-architect-mcp-spec/mcp-server/index.js",
        "--profile",
        "verifier"
      ]
    }
  }
}

VS Code（.vscode/mcp.json）：

{
  "servers": {
    "prd-spec": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/abs/path/ai-architect-mcp-spec/mcp-server/index.js",
        "--profile",
        "verifier"
      ]
    }
  }
}

---

パイプライン

リデューサーは、連続する20のステップを生成します。最初の11ステップはPRD生成、続く9ステップはオプトインの仕様作成後の実装ステップで、人間のゲートを通過した場合のみ実行されます。各ステップが出力する実質的なアクションは最大1つです。ホストがそれを実行し、結果をフィードバックします。試用プランで機能を実行する場合（11セクション）、ホストから見えるイテレーションは通常約62回です。

#	ステップ	生成するもの
1	banner	実行 ID、機能の説明、機能概要を含むウェルカムバナー
2	preflight	パイプラインが依存する前に、必要なエコシステムの MCP（Cortex、ai-architect）をプローブします。skip_preflight でスキップできます
3	context_detection	トリガーワードから PRD の種類を検出します。不明確な場合はユーザーに質問します
4	input_analysis	パスが指定されている場合は index_codebase（ai-architect-mcp-codebase）を呼び出し、codebase_graph_path を設定します
5	feasibility_gate	エピックスコープの入力（≥2 EPIC_SIGNALS）を検出し、ユーザーに焦点を絞るよう求めます
6	clarification	作成してから回答するラウンド（プランに応じて4～10回）を行います。「proceed」で短縮できます
7	budget	Cortex の論文にある 60/30/10 の配分に基づき、セクションごとに検索・生成トークンを割り当てます
8	section_generation	一度に1セクションずつ、Cortex による想起 → エンジニアによる草案作成 → 検証 →（最大3回再試行）を行います
9	jira_generation	要件、user_stories、acceptance_criteria から JIRA チケットを合成します
10	file_export	SKILL.md に従って9つのファイル（コア6つ＋補助3つ）を書き出します
11	self_check	2フェーズの複数ジャッジ検証を行います（下記参照）。done に型付きの verification フィールドを設定します

ステップ12～20は、オプトインの仕様作成後の実装ループです。implementation_gate（人間のゲート。「Implement」か「PRD only」を選択します。10-verification-report.md も書き込みます）→ pre_impl_grounding → implementation（分離された worktree 内のエンジニアサブエージェント）→ post_impl_verification（インデックス作成 → 変更検出 → セマンティック差分 → セキュリティゲート）→ testing → review（FAIL 判定の場合、同じ worktree で REVIEW_RETRY_CAP の上限まで implementation を再試行します）→ pr_gate（プッシュ前に必須の人間によるゲート）→ pr_creation → finalize の順に進みます。implementation_gate で「PRD only」と回答すると、finalize に直接進みます。complete は終端マーカーであり、ステップではありません。

各ステップは個別にテストできます（stepOnce(state, result?) はランナーと同じ形式を返します）。ランナーは emit_message アクションを内部でまとめるため、ホストが何もしないアクションを受け取ることはありません。

---

MCP ツール

3つのインターフェースがあります。リデューサーはパイプライン全体を駆動します。検証、判定、予算管理のツールは、パイプラインに入らずに他のシステムから直接利用できます。診断インターフェースは設定、ヘルス、履歴を公開します。

Reducer (3):
  start_pipeline             Initialize a run; returns first NextAction
  submit_action_result       Drive the reducer one step; returns next NextAction
  get_pipeline_state         Read-only state snapshot for diagnostics

Validation (2):
  validate_prd_section       Hard Output Rules — single section
  validate_prd_document      Cross-section checks (SP/AC/FR/test traceability)

Verification (3):
  plan_section_verification  Extract claims + select judge panels
  plan_document_verification Same, document-wide
  conclude_verification      Aggregate JudgeVerdict[] → VerificationReport;
                             accepts optional `claims` array carrying
                             `external_grounding` so oracle-resolved ground
                             truth can replace LLM-only consensus where
                             schema/math/code/spec oracles are available

Budget + feedback (2):
  coordinate_context_budget  Per-section token allocation
  map_failure_to_retrieval   Validation failure → corrective Cortex query

Diagnostics (7):
  get_config, read_skill_config, check_health, get_prd_context_info,
  list_available_strategies, get_quality_history, get_strategy_effectiveness

各ツールは、Zod で検証された構造化引数を受け取り、型付きレスポンスを返します。どのツールも LLM を呼び出しません。セクションの草案とジャッジの判定は、ホストの spawn_subagents アクションを通じて返されるため、同じパイプラインをあらゆるエージェントランタイムで実行できます。

---

複数ジャッジによる検証

self_check ステップは2フェーズの契約です。フェーズ A では検証バッチを計画し、(claim_ids, judges) のスナップショットを状態に保存します。フェーズ B では判定結果を受け取り、スナップショットに照らして解析し、コンセンサスエンジンを通じて集約します。

plan_document_verification(sections[])
  → extracts atomic Claims (FR-001, AC-005, NFR-LATENCY-1, ...)
  → selects a panel per claim type:
      architecture        → liskov + alexander + dijkstra + architect
      performance         → fermi + carnot + curie + erlang
      security            → wu + ibnalhaytham + security-auditor
      data_model          → mendeleev + dba + lavoisier
      acceptance_criteria → toulmin + popper + test-engineer
      ...

[host spawns the panel; each agent returns a JSON verdict]

conclude_verification(verdicts[])
  → Per claim, runs consensus():
      strategy: weighted_average (default) | bayesian
      fail_threshold: 0.5  (≥50% confidence-weighted FAIL → forces FAIL)
      precautionary tie-breaker: more-severe verdict wins
  → distribution_suspicious flag fires when 100% PASS over ≥5 claims
  → returns ConsensusVerdict[] with full distribution + dissenting list

判定の分類は、意図的に二択ではなく5段階にしています。NFR の主張（レイテンシ、fps、スループット、ストレージ）に PASS を与えてはなりません。測定方法が指定されていれば SPEC-COMPLETE、そうでなければ NEEDS-RUNTIME です。すべてに PASS を付けるジャッジは、distribution_suspicious 検出器によって捕捉され、型付きの done.verification フィールドでフラグが立てられます。

キャリブレーションと反証

検証サブシステム自体も仮説です。つまり、過去の実績に基づいてキャリブレーションされた信頼性で重み付けしたコンセンサスは、一様な事前分布で重み付けしたコンセンサスを上回るという仮説です。以下のクローズドループでこれを検証します。

1. 観測。 各検証実行では、審査員ごとの観測結果（claim_id、claim_type、judge_id、verdict、oracle_truth?）を SQLite 信頼性リポジトリに書き出せます。観測結果には external_grounding フィールドが含まれ、Claim からオーケストレーターを経由してオラクルの解決パスまで伝播します。外部オラクル（Ajv スキーマ、mathjs、tsc、validateSection）でクレームを解決できる場合、その真偽が LLM のみのコンセンサスに置き換わります。
2. キャリブレーション。 以降の実行では、キャリブレーション済みの事後分布によって、審査員ごと、claim_type ごとにコンセンサスの重みが決まります。20% の対照群パーティションでは事前分布を使った探索を強制します（getReliabilityForRun / getRetryArmForRun は、run_id に基づいて各実行がどちらの群に入るかを決定論的に判定します）。対照群がなければ、キャリブレーションの効果を評価する際に、実際の効果がなくても進歩しているように見えてしまいます。
3. 比較。 群間メトリクス（computeAblationComparison、computeReliabilityComparison、computeKpiGateComparison）では、ペア・ブートストラップによる信頼区間（Efron & Tibshirani 1993 §16.4、決定論的な mulberry32 RNG、再現性を小数点以下12桁に固定）を計算し、反証可能な推奨結果を3つのいずれか1つ出力します。calibrated_helps、prior_helps、または inconclusive_underpowered です。
4. 封印。 ホールドアウトパーティションはロックファイル（§4.2 用の maxattempts-heldout.lock.json、§4.5 用の kpigates-heldout.lock.json、§4.1 の外部グラウンディング済み50クレームコーパス用の heldout-partition.lock.json）にコミットされ、パーティションの sha256 ハッシュが記録されます。群間メトリクス関数は、パラメーターとして SEAL_VERIFIED の typeof センチネルを受け取ります。このセンチネルを取得する唯一の方法は、先に封印を検証することです。評価前にホールドアウトパーティションをのぞくと、型エラーになります。
5. 根拠付け。 外部オラクルでクレームを決定論的に解決できる場合は、そのオラクルで解決します。できない場合は、スタブモードの真偽を捏造するのではなく、OracleUnavailableError がスローされます。これによってアノテーターとの循環性が断たれます。LLM 風の推論で学習した（またはそれに偏った）審査員が、LLM 以外の真偽を使ったキャリブレーションを汚染できなくなります。

ロックファイル、封印の検証手順、対照群パーティションを組み合わせることで、群間比較が「95% 信頼区間がゼロを含まず、calibrated_helps」と示した場合、その主張は測定されたものであり、雰囲気で確認したものではありません。「inconclusive_underpowered」と示された場合も、反証可能な主張です。必要なのは、確信を強めることではなく、データを増やすことです。

---

アーキテクチャ

ワークスペースパッケージは10個あり、それぞれ単独でビルドでき、パッケージ境界によって厳格なクリーンアーキテクチャのレイヤリングが強制されます。

core              ← domain types, schemas, agent identities
                    │  no I/O, no infrastructure dependency
                    │  Zod-validated; the only place where verdict /
                    │  section_type / capability shapes are defined
                    ▼
validation        ← Hard Output Rules (per-section + cross-section)
                    │  pure functions; no I/O
                    ▼
strategy          ← thinking-strategy selector (genius pattern routing)
                    │
meta-prompting    ← prompt builders for clarification / draft / jira
                    │  pure string composition
                    ▼
verification      ← claim extraction + judge selection +
                    │  consensus engine (weighted_average + Bayesian)
                    │  + buildJudgePrompt
                    ▼
orchestration     ← stateless reducer, 20 step handlers, runner
                    │  step(state, result?) → next_state, action
                    │  emit_message coalescing; canned-dispatcher utility
                    ▼
ecosystem-adapters← StdioMcpClient, AiArchitectCodebaseClient, CortexClient
                    │  the only package allowed to do I/O
                    ▼
mcp-server        ← composition root; 17 tools registered;
                    │  evidence repository (better-sqlite3, optional)
                    ▼
benchmark         ← pipeline KPI measurements + golden-fixture HOR scoring
                    │  + calibration/ subtree:
                    │    · ReliabilityRepository (SQLite, observation flush)
                    │    · Kaplan-Meier + log-rank + Schoenfeld N
                    │    · Clopper-Pearson exact CI + XmR control charts
                    │    · paired-bootstrap (Efron-Tibshirani 1993 §16.4)
                    │    · external oracles (Ajv / mathjs / tsc / validate)
                    │    · machine-class detector + frozen-baseline gates
                    │    · sealed held-out lock files (sha256 + SEAL_VERIFIED)
                    │    · production-mode dispatcher + AgentInvoker seam
                    │  Audit lineage: JSONL + .xmr sidecars per run.
skill             ← SKILL.md + slash-command definitions for Claude Code

依存関係のルール（例外なし）

各パッケージの package.json をチェックします。core が依存するのは zod のみ、verification が依存するのは core のみです。orchestration は core／validation／verification／meta-prompting に依存します（ecosystem-adapters には依存しません）。ecosystem-adapters は core と verification に依存し、すべてを組み合わせることができるのは mcp-server のみです。

クロス監査でレイヤー違反が2件見つかり、修正しました。

• orchestration が ecosystem-adapters から extractJsonObject と buildJudgePrompt をインポートしていました。純粋なユーティリティが誤ったパッケージに置かれていたため、それぞれ core と verification に移しました。
• 純粋なドメイン型（Claim、JudgeVerdict、JudgeRequest、AgentIdentity）が ecosystem-adapters/contracts/subagent.ts に置かれていたため、core/domain/agent.ts に移しました。インフラストラクチャパッケージでは、後方互換性のためのシムとして引き続き再エクスポートしています。

---

以前の PRD 生成ツールでは解決できない問題を解決します

失敗モード	対応内容
ターン間でセクションの内容がぶれる	ステップごとに不変の PipelineState スナップショットを1つ使用します。リデューサーは純粋関数であり、ホストは任意のステップを再実行できます
シンボルの幻覚	validate_prd_section が Hard Output Rules を実行します。codebase_path が設定されている場合、シンボルは ai-architect-mcp-codebase のグラフと照合されます
測定せずに NFR が PASS を主張する	判定の分類体系により、レイテンシー／スループット／fps／ストレージについて PASS を認めません。コンセンサスエンジンは SPEC-COMPLETE / NEEDS-RUNTIME を引き継ぎます
確証バイアス（すべての判定者が PASS とする）	5件以上の主張すべてが PASS の場合、distribution_suspicious フラグが作動し、型付きの done.verification.distribution_suspicious に表示されます
受け入れ基準を要件まで追跡できない	ドキュメント横断バリデーターが FR-AC の網羅性と AC の番号の欠落を確認します
何を網羅するか列挙せずに、テストが「包括的」と主張する	テスト追跡ルールにより、各セクションで主張されるテストはすべて FR または AC の ID を参照する必要があります
失敗時と同じコンテキストを使う再試行	map_failure_to_retrieval がバリデーターから Cortex へのフィードバックループを閉じ、再試行前に修正用クエリを実行します
根拠のない数値による予算設定（「検索には4Kトークンを使う」など）	coordinate_context_budget が、正規の SECTIONS_BY_CONTEXT プランに基づいてセクションごとの割り当てを生成します

---

エコシステムの他の要素との連携

                            ┌────────────────────────────────────┐
                            │         Claude Code (host)         │
                            └────────────────────┬───────────────┘
                                                 │ stdio MCP
              ┌──────────────────────────────────┼──────────────────────────────────┐
              ▼                                  ▼                                  ▼
   ┌───────────────────┐              ┌────────────────────┐              ┌───────────────────┐
   │   ai-architect-   │   graph_path │   ai-architect-    │  recall      │      Cortex       │
   │   mcp-codebase    │ ───────────► │   mcp-spec         │ ◄─────────── │   (memory engine) │
   │   (Rust MCP)      │              │   (TS MCP)         │              │   (Python MCP)    │
   │                   │   symbols    │                    │  excerpts    │                   │
   │   read-only       │ ◄──────────► │   stateless        │ ───────────► │   thermodynamic   │
   │   intelligence    │              │   reducer          │              │   memory          │
   └───────────────────┘              └─────────┬──────────┘              └───────────────────┘
                                                │
                                                │ spawn_subagents
                                                ▼
                                  ┌─────────────────────────────┐
                                  │   zetetic-team-subagents    │
                                  │   97 genius + 19 team       │
                                  │   Each judge cites its      │
                                  │   primary paper.            │
                                  └─────────────────────────────┘

各プロジェクトは、それぞれ1つの課題を担当します。ai-architect-mcp-codebase はコードについての事実を把握します。Cortex はすでに決定した内容を把握します。zetetic-team-subagents は、特定の形の主張について推論する方法を把握します。AI Architect MCP Spec は、これら3つのシグナルを、エージェントが実行に移せる PRD に変換する決定論的な連携役です。

---

ゼテティック標準

このコードベースで重要な役割を担う定数にはすべて、// source: アノテーションが付いています。次の3つの形式が認められています。

// source: <citation>          // a paper, a spec, a referenced design doc
// source: benchmark <path>    // a committed benchmark whose output produced this value
// source: provisional heuristic — <calibration plan>
                               // honest admission; tells the next reader
                               // (a) why the value is what it is today and
                               // (b) what evidence would change it

クロス監査で、以前は出典の記載がなかった定数をすべて見つけ、タグ付けしました。例：

// pipeline-kpis.ts
const KPI_GATES = {
  /** source: provisional heuristic. Smoke baseline = 62 iterations on
   *  trial+codebase; cap is 100 (~60% headroom). dijkstra cross-audit
   *  derived a structural max of 9 emit_message hops; the substantive-
   *  action count builds on that. Replace with measured P95 + 1σ once
   *  the calibrated baseline has enough runs. */
  iteration_count_max: 100,
  ...
};

// verification/consensus.ts
/** source: provisional heuristic — Beta(7,3) (mean 0.7, ESS=10,
 *  moderately informative toward reliability). Replaced per agent by
 *  Beta(α+correct, β+incorrect) once calibrated from history. */
const DEFAULT_RELIABILITY_PRIOR_MEAN = 0.7;

4つの柱（一貫性／真実性／有用性／必要性）とゼテティックな探究の7つのルールは、zetetic-team-subagents 標準を継承しています。暫定値が、真実として暗黙のうちに引き継がれることはありません。

---

このシステムが行わないこと

このシステム自体にも同じ基準を適用しています。

1. PRD パイプラインはコードを書きません。サーバー自体もコードを書くことはありません。 ステップ 1～11 では PRD を作成します。PRD 内のシンボルはグラフに照らして検証されますが、こちらで編集することはありません。オプトイン方式の実装ループ（ステップ 12～20）は、人間が implementation_gate で「Implement」と回答した場合にのみ実行されます。その後、ホスト側のエンジニア／テストエンジニア／コードレビュアーのサブエージェントが、隔離されたワークツリーで実装の作成、テスト、レビューを行います。必須の pr_gate 承認なしにプッシュしたり、PR にしたりすることはありません。このサーバーが出力するのは spawn_subagents アクションのみであり、自らソースファイルを編集したり、ブランチをプッシュしたりすることはありません。
2. 文章の品質は検証しません。 Hard Output Rules は構造上の不変条件（FR の番号付け、AC のトレーサビリティ、NFR の形式、相互参照）をチェックします。文が適切に書かれているか、説得力があるかはチェックしません。それを担うのが複数の審査員によるフェーズです。そこでも審査員が判定するのは、スタイルではなく、個々の主張です。
3. 審査フェーズはエンドツーエンドでテストできますが、審査員の判定は決定論的ではありません。 テストでは、設計上 100％ PASS を返す固定のディスパッチャーを使用します。distribution_suspicious 検出器があるのは、実際の審査パネルも追認による合意に陥る可能性があるためです。その点を取り繕うことはしません。
4. KPI ゲートは調整によって決められており、恣意的に選ばれたものではありません。 iteration_count_max、wall_time_ms_max、mean_section_attempts_max は、Clopper-Pearson の正確な信頼区間、マシンクラスごとの wall_time 正規化、loadCalibratedGates と hold_provisional によるラチェット保護を用いて、K=100 の固定ベースラインに対して調整されています。ロックファイルにはベースラインのコンテンツハッシュが記録されており、後から変更するとシール検証に失敗します。データがまだ十分でない場合、ゲートはロックされず hold_provisional のままです。事前登録の全容については、docs/PHASE_4_PLAN.md を参照してください。
5. 引用があることと、引用が有効であることは別です。 // source: Knuth 1998 というコメントは、Knuth 1998 が実在するか、値を裏付けているかにかかわらず、規約を満たします。引用が記載されていることは必ず確認しますが、引用の妥当性を保つのは、各フェーズで天才とチームが行う相互監査サイクルです。

---

監査サイクルの再現

このリポジトリには、複数のエージェントによる相互監査ワークフローが含まれています。重要なフェーズが終わるたびに、次を行います。

# Engineering team review:
#   architect, code-reviewer, refactorer, test-engineer, security-auditor,
#   devops-engineer, dba (when relevant)

# Genius team review:
#   feynman (integrity), curie (measurement), popper (falsifiability),
#   dijkstra (correctness), shannon (signal), deming (variation),
#   poincare (qualitative), ...

各エージェントは、記憶に頼らずコードの現状を読み、重要度順に並べた指摘事項の一覧を作成します。指摘事項は、提起されたサイクル内で解決します。新たな測定なしには解決できない項目は、解決に必要な証拠を明記して持ち越します。これにより、延期は明示された義務となり、何も言わずに放置されることはありません。

---

プロジェクト構成

packages/
├── core/                  Domain types · schemas · agent identities · evidence repo
├── validation/            Hard Output Rules · per-section + cross-section validators
├── verification/          Claim extraction · judge selection · consensus engine
├── meta-prompting/        Prompt builders (clarification / draft / jira)
├── strategy/              Thinking-strategy selector
├── orchestration/         Stateless reducer · 20 step handlers · runner · canned-dispatcher
├── ecosystem-adapters/    StdioMcpClient · AiArchitectCodebaseClient · CortexClient
├── mcp-server/            Composition root · 17 MCP tools registered
├── benchmark/             Pipeline KPI measurement · golden-fixture HOR scoring
│   └── calibration/       ReliabilityRepository · KM survival ·
│                          Clopper-Pearson · XmR · paired-bootstrap ·
│                          external oracles · sealed held-out partitions ·
│                          production-mode dispatcher
└── skill/                 SKILL.md · slash-command definitions

---

ライセンス

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

プロジェクト文書： ROADMAP（今後1年間にプロジェクトが目指すこと、そして目指さないこと） · CONTRIBUTING（変更の提案方法とテスト方針） · GOVERNANCE（意思決定者と、メンテナーが活動を停止した場合にプロジェクトがどうなるか） · SECURITY（脆弱性の報告方法とサプライチェーンの保証） · 保証ケース（セキュリティ上の論拠と、その適用範囲） · CODE OF CONDUCT · CHANGELOG。

このソフトウェアは、Clément Deust が独立して開発したものです。雇用関係の外で開発されており、過去または現在の雇用主とは提携関係になく、支持や所有も受けていません。ai-architect エコシステムの一部です（Cortex、 ai-architect-mcp-codebase、 zetetic-team-subagents）。

アルゴリズムと定数の引用および一次資料は、プロジェクトのソース規律に関するルールに従って、コード内の // source: アノテーションで記載しています。これらのアノテーションを削除してもライセンス条件は変わりませんが、コードの基礎となった元の研究への帰属表示が失われます。

---

測定できない関数を幻覚で作り上げる PRD を出荷してはいけません。
すべての主張が Pearl、Curie、Liskov、そしてほかの7人の審査委員によって評価され、呼び出しグラフと照合され、Cortex が昨日のこととして覚えている内容に基づいた PRD を出荷しましょう。