construct

construct — プロダクトアイデアを構築可能なSRDへ変換する

construct は、プロダクトアイデアをソフトウェア要求仕様書（SRD）スイートに変換します。その要件と判断は、モデルの記憶ではなく実際の調査に基づいて行われます。決定論的エンジン（scripts/construct.mjs、依存関係ゼロのNode）が検索、資料の収集、SRDのレンダリング、検証をコードで実行します。あなたの役割は、インタビューを実施し、調査を推進し、レンダリングされたスキャフォールドを正確で根拠のあるSRDに拡充することです。

基本ルール: 推測された要件よりも根拠のある要件を優先します。エンジンが取得した調査結果（競合他社、OSSの先行事例、技術ドキュメント、StackOverflow）を使用して、スコープ、非機能要件（NFR）、およびアーキテクチャ上の決定を正当化し、[E#] で証拠を引用します。根拠付けはここでは助言的なものです。construct check はカバレッジを報告しますが、それに基づいて失敗することはありません。厳格さを適用するかどうかはあなた次第です。

スクリプト

依存関係のない単一のバンドル: node scripts/construct.mjs <command>。npm install もAPIキーも不要です。すべてのコマンドは --help で確認できます。主なコマンド:

• init --idea "<一言>"> --out <run> — 実行フォルダと brief.json をスキャフォールディングします。
• research --out <run> [--angles market,oss,tech,semantic] [--q "<焦点>"] [--semantic] — 複数の角度から証拠を収集し、<run>/evidence/ に保存します（[E#] ID 付きの EVIDENCE.md + evidence.json 資料）。デフォルトの角度: market,oss,tech。
• analyze --out <run> [--json] — 「何が薄いか」を報告します。現状のままで UNGROUNDED になるすべての機能/競合/テクノロジー/シードを挙げ、各ギャップを修正するドリルコマンドを表示します。情報提供のみで、決して実行を妨げません。
• web|oss|tech|so --out <run> [--q "<焦点>"] [--url ...] [--seeds ...] [--docs-url <u,...>] — 1つの角度に絞って標準出力に出力します（資料は作成しません）。薄い部分をさらに深掘りするために使用します。--docs-url は既知のドキュメントページを直接根拠付けます。
• render --out <run> [--level light|complex] [--merge] — brief.json + 資料からSRDツリー + SRD.json をレンダリングします。
• check --out <run> [--min-grounding <0-100>] [--semantic] [--json] — 構造的なハードゲート（不完全なSRDでは終了コード≠0）と、助言的な根拠カバレッジレポートです。--min-grounding N は、N%未満の根拠があるクレームで失敗する第2のゲートを有効にします。--semantic は VERIFY.json（review 参照）を取り込み、反駁またはサポートされていないクレームで失敗します。（research --semantic とは異なります。これは埋め込みの関連性によって証拠を再ランク付けするだけです。）
• review --out <run> [--apply <verdicts.json>] [--max-review N] [--json] — クレームサポートハーネス。--apply なしで実行すると、クレーム↔証拠のワークリスト（VERIFY.todo.json + VERIFY.md）を書き込みます。これは、根拠のある各クレームと、引用された各 [E#] スニペットをペアにして、評価できるようにするものです。--apply <verdicts.json> は、あなたの評決（supported|partial|refuted|unsupported）を VERIFY.json にまとめ、check --semantic がそれをゲートとして使用します。references/orchestration.md に従ってファンアウトしてください。
• verify --out <run> [--app <dir>] [--run-tests] [--strict] [--json] — ビルドレフェリー: BUILD-PLAN.json が整形式で非循環であること、すべてのタスク参照が SRD.json に解決されること、完了タスクのファイルが存在すること、すべての要件がテストによって参照されていることを確認します。--run-tests は宣言されたテストコマンドも実行します。--strict は、参照テストがない必須機能を失敗とします。
• status --out <run> [--json] — これまでの実行内容を表示します。--json はビルドフロンティア（どの BUILD-PLAN タスクが現在ビルド可能か、ブロックされているか）を追加します。
• semantic up|down|status — オプションのローカルDockerスタック（Qdrant + Ollama + SearXNG）。

ワークフロー

あなたは一度呼び出され、完全で根拠のあるSRDを返すことが期待されています。完了するまでループを駆動し、本当の判断が必要な場合にのみユーザーに質問を中断します。

1. ユーザーにインタビューする — 一度に1つの質問。 リサーチの前に製品を確立します。references/interview-playbook.md に従ってください: 問題、ターゲットユーザー、中核的価値、必須/すべき/できる機能、制約（予算、スケジュール、チーム、コンプライアンス）、候補技術、および競合他社/OSSのシード。各質問には回答を推奨し、アンケートをまとめて提示しないでください。回答を brief.json に書き込みます（construct init で開始します）。

2. リサーチ — アイデアを根拠付けます。 以下を実行:

   node scripts/construct.mjs research --out <run> --angles market,oss,tech
   

   これにより、Web上の競合他社を発見し、類似のOSSプロジェクト（および実際の落とし穴を見つけるためのそのIssue/PR）をマイニングし、候補技術のドキュメントとStackOverflowを取得します。<run>/evidence/EVIDENCE.md を読んでください。

3. さらに深掘りする — analyze がクリーンになるか、ユーザーが止めるまで。 以下を実行:

   node scripts/construct.mjs analyze --out <run>
   

   何が薄いかを正確に挙げます — 一致する証拠がない機能、競合、候補技術、OSSシード — そして各ギャップを修正するドリルコマンドを表示します。ファンアウト: 並列サブエージェントを生成できる場合は、ギャップごとに1つディスパッチします。各サブエージェントは、ブリーフの一文、ギャップ、そのドリルコマンド、および独自のWebSearchを受け取り、5行以内のサマリーと根拠付けに値するURLを返します。サブエージェントは実行フォルダに書き込んではいけません。ドリルは標準出力に出力します。construct research だけが資料を書き込み、それを実行できるのはあなただけです。調査結果を逐次的に取り込みます: construct web --url <u,...> --out <run> → research を再実行 → analyze を再実行。（サブエージェントがない場合は、自分でギャップに取り組み、一度に1つのドリルを実行します。）見つけた内容をユーザーに伝え、ユーザーに指示を仰ぎます — 必須機能と重要な決定を優先し、ユーザーが十分と言ったら停止します。references/orchestration.md と references/research-playbook.md を参照してください。

4. SRDをレンダリングします。 ブリーフが確固たるものになり、資料が豊富になったら:

   node scripts/construct.mjs render --out <run> --level complex
   

   ビルドが可能な場合は常に complex を選択してください。後でレベルを切り替えるとFR IDが変更されます（references/srd-authoring.md 参照）。これによりSRDツリー（下記参照）が書き込まれます。データモデルとインターフェースはブリーフからの推論によって事前にシードされます — それらを信頼せず、検証してください。次に拡充します: すべての 🧠 Decide: の呼び出しを解決し、テンプレート化された受け入れ基準とNFRメトリクスをテスト可能で境界のあるステートメントに洗練し（references/acceptance-criteria.md に従ってください。テンプレートのまま残っていると check が警告を出します）、データモデルとインターフェースを修正/拡張し、資料から要件と判断に [E#] の引用を追加します。references/srd-authoring.md と references/citation-format.md を参照してください。complex では、デザインシステム（design/）も拡充します: シードされたデザイントークンを製品の実際のブランド価値に置き換え、コンポーネントと画面/フローのインベントリを検証し、アクセシビリティ基準をターゲット標準（ブリーフから導出、デフォルトはWCAG 2.2 AA）に引き上げます。references/design-system-authoring.md を参照してください。

5. 敵対的レビュー — 新鮮な目で壊してみる。 実行フォルダのパスと references/adversarial-review.md 以外のコンテキストを与えずに、1人のレビューアーサブエージェントを生成します（サブエージェントがない場合は、敵対的な読み手としてそのチェックリストに厳密に従い、自分でパスを実行します）。SRDを壊そうと試みます — 曖昧さ、テスト不可能な基準、欠落した障害パス、引用のごまかし、矛盾 — そしてタグ付けされた調査結果を返します。すべての [blocker] を修正し、[advisory] は判断で対応し、その後 check を再実行します。新しいブロッカーが現れなくなるまでループします（上限: 3ラウンド。その後、残ったものをユーザーに提示します）。complex レベルで、真に議論のある、覆すのが難しいADRについては、references/orchestration.md の3人の審査員パネルも実行します。

6. 検証（3つのレイヤー）。

   • 構造的（ハード）: node scripts/construct.mjs check --out <run>。未解決の 🧠、機能要件の完全な欠如、受け入れ基準のないFR、ぶら下がったエンティティ/インターフェース/NFR参照、必須NFRカテゴリの欠落、または不正な形式のADRがあると失敗します。修正してパスするまで続けます。
   • 根拠付け（助言的）: 同じコマンドがカバレッジを表示します — 要件/判断のうち証拠を引用している割合。重要な部分（重要な決定）ではそれを引き上げます。references/grounding-coverage.md を参照してください。デフォルトではビルドを失敗させることはないので、判断で使用します。ユーザーが根拠付けを強制したい場合は、オプトインゲートを追加します: check --out <run> --min-grounding 70。
   • クレームサポート（助言的 → オプトインゲート）: カバレッジは引用を数えます。引用が正しいかどうかはチェックしません。construct review --out <run> はクレーム↔証拠のワークリストを構築します。各ペアを評価し（references/orchestration.md パターン4に従ってファンアウト）、verdicts.json を組み立て、review --apply verdicts.json を実行し、その後 check --out <run> --semantic で反駁/サポートされていないクレームをゲートします。提示する前に、重要なFR/ADRに対して1回パスする価値があります。 check が構造的にパスし、レビューアーが新しいブロッカーを見つけられず、根拠付けが誠実になるまで、ステップ3〜6をループします。

7. 提示する。 ユーザーにSRDスイートを提供します: ビジョン、競合状況、根拠のある要件、主要な決定（[E#] の証拠とリンク付き）。不明な点は推測せずに明示的にピン留めします。

8. ビルド（ユーザーがSRDだけでなくアプリケーションを望む場合）。 レンダリングは BUILD-PLAN.json も出力します。これは機械可読なタスクDAG（T-000スケルトン + FRごとに1タスク、必須 → すべき → できる、エンティティ認識型の依存関係）であり、その acceptance エントリは SRD.json をポイントします。あなたはすべてのアプリケーションコードを書き、エンジンが審判を務めます。 references/build-playbook.md に従ってください:

   • T-000（スキャフォールド、テストハーネス、CI）を実行します。BUILD-PLAN.json の conventions.appDir と conventions.testCommand を設定します。
   • タスクごとに、トポロジカル順序で: SRD.json から受け入れ基準を読み取ります。TDDで実装します — すべてのテストはそのFR IDを名前に含めます（例: describe("FR-001 …")、これが verify が grep するものです）。artifacts + tests を記録し、status: "done" を設定し、node scripts/construct.mjs verify --out <run> を実行して、次のタスクの前にエラーを修正します。
   • 同じマイルストーンのタスクは互いにエッジを持たないため、それらの準備完了フロンティア（status --out <run> --json）は並行してビルドできます — タスクごとに1つの独立したgitワークツリー。結果を BUILD-PLAN.json に統合するのはあなただけです（references/orchestration.md パターン5）。
   • マイルストーンごとに: verify --out <run> --run-tests --strict を実行し、その後マイルストーンの敵対的レビューを実行します — 実際にテストで実行されていない受け入れ基準がないかを、新鮮な目で確認します（プレイブックを参照。references/verify.md はverifyが何を証明でき、何を証明できないかを説明しています）。
   • ビルド中にFRが間違っていることが判明した場合は、ブリーフを修正し、再レンダリングし（進行状況は機能タイトルでマージされます）、シフトされたFR IDに再タグ付けし、再 check を実行します。

生成物（SRDツリー、--out 配下）

00-overview/   VISION.md · SCOPE.md (+ 🧠 未解決の決定)
requirements/  FUNCTIONAL.md (FR-NNN · 優先順位 · Given/When/Then · [E#])
               NON-FUNCTIONAL.md (NFR-NNN カテゴリ別 · メトリクス · [E#])
architecture/  SYSTEM-CONTEXT.md · DATA-MODEL.md · INTERFACES.md
               decisions/NNNN-*.md  (ADR)
design/        PRINCIPLES.md · DESIGN-TOKENS.md (+ design-tokens.json) · COMPONENTS.md
               SCREENS.md · ACCESSIBILITY.md      (complex のみ。スキップする場合は --no-design)
competitive/   LANDSCAPE.md (競合 + OSS 先行事例)
BUILD-PLAN.md · BUILD-PLAN.json (ビルドフェーズ用タスクDAG)
TRACEABILITY.md (FR ↔ NFR ↔ ADR ↔ エンティティ ↔ インターフェース ↔ コンポーネント ↔ 画面)
evidence/      EVIDENCE.md · evidence.json · meta.json   ·   brief.json · SRD.json

light は簡潔に保ち、complex は完全なNFRセット、2つ目のADR、障害パス受け入れ基準、完全なトレーサビリティマトリクス、およびデザインシステムサブツリー（design/: 原則、トークン、コンポーネント、画面/フロー、アクセシビリティ契約 — --no-design で除外）を追加します。--merge を追加すると、単一ファイルの SRD.md が生成されます。

オプションのセマンティックモード（完全にローカル、APIキー不要）

market/oss/tech の角度はネットワークアクセスのみが必要です。収集した証拠に対して関連性パスを実行するには、ローカルの埋め込みモデルを有効にできます:

node scripts/construct.mjs semantic up        # docker: Qdrant + Ollama + SearXNG
node scripts/construct.mjs research --out <run> --angles market,oss,tech,semantic --semantic

すべてローカルのDockerコンテナで実行されます。キーは不要で、データがマシンの外に出ることはありません。スタックが起動していない場合、--semantic は通知をログに記録し、字句ランキングを維持します。references/semantic-setup.md を参照してください。

参考文献

• references/interview-playbook.md — 一度に1つの質問でブリーフを引き出す方法。
• references/research-playbook.md — 角度を選択し、「十分」になるまで深掘りする方法。
• references/orchestration.md — 3層の動的ワークフローモデルとサブエージェントパターン: リサーチファンアウト、レッドチーム、審査員パネル、クレームサポートレビューファンアウト、ビルドファンアウト（単一ライタールールを含む）。
• references/adversarial-review.md — レッドチームのチェックリストとその調査結果の契約。
• references/srd-authoring.md — 🧠 の呼び出しを解決し、テスト可能な要件とADRを作成する方法。
• references/design-system-authoring.md — complex デザインシステムの拡充: トークン、コンポーネント、画面/フロー、アクセシビリティ契約。
• references/acceptance-criteria.md — 悪い Given/When/Then を良いものに書き換え、測定可能なNFRメトリクスパターン。
• references/citation-format.md — [E#] 根拠付け規則。
• references/grounding-coverage.md — 助言的カバレッジレポートの意味とその向上方法。
• references/build-playbook.md — ビルドループ: タスクTDD、FRタグ規則、マイルストーンゲート、マイルストーンレビュー。
• references/verify.md — 各 verify チェックが証明するものと、まだ目視確認が必要なもの。
• references/provider-apis.md — OSSのIssue/PRをホストごとにキーレスで取得する方法。
• references/web-discovery.md — 階層化されたキーレスWeb検索。
• references/semantic-setup.md — オプションのローカルDockerスタック。