projscan

---

使用目的

エージェントが次のような質問をしたときに projscan を使用します。

• この機能を変更する前に、どのファイルを読めばよいですか？
• 引き継ぎ前に、どの証明コマンドを実行すればよいですか？
• 修正、レビュー担当者の確認、またはリリース承認が必要なリスクはどれですか？
• 最初に修正すべきリスクはどれですか？
• エージェントは承認済みの変更範囲内にとどまりましたか？

projscan はコアスキャンをローカルマシンで実行します。.gitignore を尊重し、オプトインしない限り .env の値をスキャン対象から除外し、同じ証拠を CLI と 51 ツールの MCP サーバーを通じて提供します。言語レイヤーでは、12 の名前付き言語を対象とする 11 個の AST アダプターを使用します。

Your agent / engineer
  (Codex, Claude Code, Cursor, CI, your scripts)
       |   intent, diff, repo files, feedback, proof requests
       v
  +----------------------------------------------------------------+
  |  projscan   (runs locally, source stays on this machine)       |
  |  ------------------------------------------------------------  |
  |  Mission Control -> assess Cards -> simulate risk -> prove      |
  |                         |              |              |         |
  |                         |              |              +- allowed files
  |                         |              |              +- forbidden files
  |                         |              |              +- proof receipt
  |                         |              |              +- change passport
  |                         |              |              +- review gate
  |                         |              |              +- live guard
  |                         |              +- bounded extraction       |
  |                         |              +- regression test first    |
  |                         |              +- leave unchanged          |
  |                         +- evidence strength                   |
  |                         +- trust memory                        |
  |                         +- AgentLoopKit handoff                |
  |                                                                |
  |  CLI + MCP tools, no account, telemetry off by default         |
  +----------------------------------------------------------------+
       |   next safe action, exact proof commands, handoff packet
       v
Reviewer / CI / LLM provider
  (only the evidence you choose to pass along)

インストール

npm install -g projscan
projscan start

グローバルにインストールせずに実行するには：

npx projscan start

まず信頼境界を確認してください：

projscan privacy-check
projscan start --intent "what can projscan read?"
projscan start --intent "does projscan read .env values?"

日常のワークフロー

コマンドの全カタログを確認する前に、次の 4 つのワークフローを使用してください。

機能を編集する前

projscan start --intent "what files do I need to change for auth?"
projscan start --intent "what should we build next?" # Routes to a before-edit implementation workplan
projscan start --intent "is my agent allowed to change billing retry logic?"
projscan understand --view change --intent "add auth token refresh" --format json
projscan prove --intent "is my agent allowed to change billing retry logic?"
projscan preflight --mode before_edit --format json

引用付きの変更マップ、先に読むべきファイル、変更される可能性の高いファイル、ブロックされた入力、実行可能な証明契約、編集前の証明ゲートが得られます。エージェントの権限に関する意図は projscan prove に振り分けられるため、start によって次のエージェントに広範なチェックリストではなく契約のパスを引き継げます。

成功基準：エージェントが、最初に読むファイル、変更する可能性の高いファイル、避けるべき禁止ファイル、編集前に実行すべき証明コマンドを示せること。

検証済み変更ワークフロー

projscan start --intent "is my agent allowed to change billing retry logic?"
projscan prove --intent "is my agent allowed to change billing retry logic?" --save-contract .projscan/proof-contract.json
# Make the bounded edit, then run the proof command.
projscan prove --run -- npm test -- tests/billing/retry.test.ts
projscan prove --changed --contract .projscan/proof-contract.json --format markdown
projscan passport --contract .projscan/proof-contract.json --format markdown
projscan proof-broker --contract .projscan/proof-contract.json --pr-comment
projscan review-gate --contract .projscan/proof-contract.json --pr-comment

コマンドの流れは start -> prove -> run -> changed です。契約が作成された後、prove --run の前に、範囲を限定した編集を行います。start が契約ワークフローを選択します。prove --intent は --save-contract が指定されている場合にのみ .projscan/proof-contract.json を書き込みます。prove --run -- <command...> はローカルの証明コマンドを実行し、終了コードを記録し、秘匿化されたログを取得して、現在の変更ファイルのフィンガープリントを作成します。projscan がコマンドを実行しなかった場合に、CI や外部の証拠を取り込むための prove --record-command も引き続き利用できます。prove --changed は、現在の作業ツリーと契約およびローカル台帳を照合します。

編集前には証明契約、編集後には証明レシートが得られます。契約には、許可されたファイル、禁止ファイル、リスクのある契約、該当しそうなテスト、不足している回帰テストの証拠、証明コマンド、安全な変更の形、ロールバック、信頼度、レビュー担当者向けガイダンス、各リスク領域の proofRequirements が記載されます。レシートは実際の作業ツリーを契約と照合し、変更ファイルを、許可された本番ファイル、想定されたテスト、ドキュメント、生成された証明アーティファクト、設定／セキュリティの逸脱、禁止対象への変更、想定外の本番ファイルに分類します。レシートには証明の再実行ステータス、証明の充足度、リスクの差分、コミット準備状況、レビューチェックリストが報告されます。 兄弟関係にある Baseframe ハーネスディレクトリ（.agentloop/、.agentflight/）は、スコープ逸脱ではなくハーネスの証拠として分類されます。AgentLoopKit と AgentFlight は、承認されたワークフローの一環として、これらのディレクトリにセッション状態、タスクのステータス遷移、検証レポートを書き込むため、これらの書き込みはレシート上で情報として扱われ、forbiddenTouched の発生、コミット準備の妨げ、レビューゲートの停止にはつながりません。自動生成されるコントラクトでは、これらのディレクトリは forbiddenFiles に含まれなくなりました。レシートは、旧バージョンで保存されたコントラクト内の該当エントリーも無視し、Team Proof Recipe の forbiddenFiles エントリーも同様に扱います。ハーネス以外の場所にある本番パスを禁止するには、引き続き forbiddenFiles または Team Proof Recipes を使用してください。

依存関係の変更を意図する場合、そのスコープは引き続き実行可能な状態に保たれます。prove --intent で依存関係またはツールのバージョン変更（たとえば「projscan を 5.0.1 にアップグレード」）を指定すると、生成されるコントラクトでは package.json と package-lock.json が forbiddenFiles ではなく allowedFiles に配置されます。無関係な意図の場合、マニフェストはデフォルトで引き続き禁止されます。コントラクトの成果物は、プロジェクトルート内の .projscan/proof-contract.json または .projscan/proof-contracts/<name>.json に限定されます。--save-contract と --contract では、ほかのパスは拒否されます。

Proof Replay は、コマンド、終了コード、実行時間、変更ファイルのフィンガープリント、秘匿化された要約、ログパス、ソースを .projscan/proof-ledger.jsonl に記録します。実行されたプルーフのログは .projscan/proof-logs/ 内に保持されます。台帳の照合ではパッケージランナーのプレフィックスを正規化するため、npx projscan assess --mode fix-first --format json、pnpm exec projscan ...、node_modules/.bin/projscan ... は、いずれも必須の projscan assess --mode fix-first --format json を満たします。prove --changed は、プルーフを合格、不足、失敗、一部完了、または古い状態として示します。レシートの JSON には、リプレイのタイムライン、changedAfterProof、リプレイコマンド、ローカルレシートのフィンガープリントを含む proofReplay が記載されます。プルーフの実行後にエージェントが新しいファイルを編集すると、レビュー担当者が差分を確認する前に、プルーフが古い状態であることがレシートに示されます。

Proof Sufficiency は、ローカル台帳が変更された各範囲をどの程度カバーしているかを推定します。proofSufficiency は行を strong、adequate、weak、missing、stale、failed として示し、その後、レビュー担当者が解決する必要のある正確な不足項目を一覧表示します。

Team Proof Recipes を使うと、リポジトリ内の proofRecipes に、機微なパスに必要なプルーフを定義できます。一致するレシピが設定されている場合、prove --intent はそのレシピのコマンド、レビュー担当者、禁止ファイルを Proof Contract に追加します。prove --changed と projscan evidence-pack --pr-comment は、Proof Receipt に不足しているレシピのプルーフ、必須のレビュー担当者、レシピの逸脱を表示します。レシピ自体がプルーフコマンドを実行することはありません。ローカル台帳に証拠を追加するには、prove --run -- <command...> または prove --record-command を使用してください。 保存されたコントラクトは prove --changed の信頼できる情報源です。チームのレシピを変更した場合は、コントラクトを更新してください。

すべての prove レポートには、エージェントと MCP クライアント向けの簡潔な JSON サマリーである verifiedWorkflow が含まれます。フェーズ、次のアクション、次のコマンド、スコープの状態、プルーフの状態、プルーフ充足度の状態、リスク変化の方向、レビュー担当者の判断、プルーフが古い・不足・失敗のいずれかを示すフラグが記載されます。

projscan passport は、コントラクトとレシートを1つの引き継ぎ用成果物にまとめます。許可ファイル、禁止ファイル、変更ファイル、プルーフのリプレイ状態、Proof Sufficiency、レビュー担当者のアクション、次のコマンドが記載されます。レビュー担当者や別のエージェントが変更の全容を1つの JSON ファイルで確認する必要がある場合は、次のように保存してください。

projscan passport \
  --intent "is my agent allowed to change billing retry logic?" \
  --save-contract .projscan/proof-contract.json \
  --output .projscan/passport.json

同じパスポートの証拠から PR Passport を作成するには、projscan proof-broker を使用してください。必須のプルーフ項目、不足または古いプルーフのコマンド、Team Proof Recipes による必須レビュー担当者、リスクのある変更ファイル、レビュー担当者が求めるべき次のコマンドが記載されます。

projscan proof-broker --intent "<change>" --bootstrap-contract
projscan proof-broker --contract .projscan/proof-contract.json --pr-comment

--bootstrap-contractは、明示的に要求された場合にのみ新しいProof Contractを書き込みます。証明コマンドは実行せず、スコープを暗黙に拡大することもありません。

PR Passportからレビュー判断を生成するには、projscan review-gateを使用します。ready、needs-proof、drifted、blockedのいずれかを報告し、レビューを進められるかどうかを示します。また、未解消の証明課題を項目ごとに提示し、スコープが移動した場合は再契約コマンドを示します。証明課題が解消されるまで、CIを失敗させることもできます。

projscan review-gate --intent "<change>" --bootstrap-contract
projscan review-gate --contract .projscan/proof-contract.json --pr-comment
projscan review-gate --contract .projscan/proof-contract.json --ci --fail-on-needs-proof

保存済みのProof Contractに照らして現在の作業ツリーを確認するには、projscan guardを使用します。エージェントがファイルを編集した後に使うか、セッション中に--watchを実行してください。

projscan guard --contract .projscan/proof-contract.json
projscan guard --contract .projscan/proof-contract.json --watch

成功基準：レビュー担当者が、変更されたリスク領域について、スコープ、証明の実行状況、証明の鮮度、十分性、レビューを妨げている未解消の証明課題を正確に確認できます。

引き継ぎまたはコミットの前

projscan start --intent "is this safe to commit?"
projscan assess --mode fix-first --format markdown
projscan preflight --mode before_commit --format json
projscan evidence-pack --pr-comment

変更ファイルのリスク、優先順位付きの次のアクション（1〜2件）、手動レビューのゲート、担当者への振り分け、ベースラインの傾向に関する記録、レビュー担当者向けの正確な証明コマンドを確認できます。評価の根拠となる未処理の修正項目を確認するには、projscan bug-hunt --format jsonを使用してください。

成功基準：レビュー担当者が、スキャン出力全体を読まずに、最優先の修正、残っている証明、手動承認ゲートの有無を確認できます。

リリース候補のレビュー前

projscan release-train --format json
projscan preflight --mode before_merge --format json
projscan evidence-pack --pr-comment

読み取り専用の準備状況に関する証拠を確認できます。projscanは修正項目と承認ゲートを報告しますが、これらのコマンドからタグ付け、公開、デプロイ、バージョンの更新は行いません。

成功基準：誰かがタグ付けや公開を行う前に、リリースレビューで具体的な不具合と人による承認ゲートを切り分けられます。

週次の証明優先評価

projscan assess --goal "make this repo safer to ship this week"
projscan assess --mode fix-first --format markdown
projscan simulate --plan "split bugHunt.ts into ranking, evidence, and output modules"

Proof Cardsを確認できます。各推奨事項には、ローカルの証拠、影響、安全な変更方針、検証コマンド、フィードバックまたは抑制に関するガイダンス、リスク差分が含まれます。現在のリスク差分を前回の実行結果と比較するには、--baseline previous-assess.jsonを追加してください。assessは既存の品質、bug-hunt、preflightの証拠をまとめるものであり、リリース、タグ付け、公開、デプロイは行いません。

Proof Cardsには、証拠の強さ、信頼度の理由、順位付けの理由、信頼の記録、証拠の不足、AgentLoopKitへの引き継ぎパケットも表示されます。承認された推奨事項、ノイズの多い検出結果、誤検出、抑制を今後の順位付けに反映するには、--feedback .projscan-feedback.jsonを追加してください。

リファクタリングや抽出の前に、リスク差分シミュレーターを使用してください。ローカルの証拠から、変更される可能性の高いファイル、影響を受けるテスト、契約面、ロールアウトの手順、証明コマンド、変更前後のリスクを予測します。制約付きの抽出、テスト先行、変更しない選択肢を比較し、推奨案を提示します。読み取り専用であり、ファイルの編集、計画の実行、リリース、タグ付け、公開、デプロイは行いません。

成功基準：チームが、価値の高い修正項目（1〜2件）、それらが重要な理由、証明方法、出荷準備に引き続き注意やレビューが必要かどうかを確認できます。

Baseframe Suiteの評価アーティファクト

ProjScanがリスクを見つけます。 AgentLoopKitが作業を制御します。 AgentFlightが結果を証明します。

Baseframe Suiteのタスクで安定したローカルアーティファクトが必要な場合は、次を実行します。

projscan assess \
  --intent "Implement password reset" \
  --task-id auth-password-reset-20260626-01 \
  --emit-baseframe

ProjScanは.baseframe/evidence/<task-id>/projscan-assessment.jsonを書き込み、 AgentLoopKitやAgentFlightのアーティファクトを書き込まずに .baseframe/agent-workflow.jsonを更新します。Baseframe Suite Integration v1を参照してください。

ミッションコントロール

projscan start --intent "<goal>" は、自然言語で記述された目標を実行計画に変換します。

• 現在のコマンド
• ブロックされている入力
• 次に実行するコマンド
• 証拠キュー
• 完了条件
• レビューゲート

作業をエージェント間で引き継ぐ可能性がある場合は、ミッションを保存します。

projscan start --save-mission .projscan/mission --intent "is it safe to commit this change?"
projscan mission-proof --mission .projscan/mission --format markdown
projscan start --mission .projscan/mission

ミッションバンドルには、ランブック、タスクカード、引き継ぎプロンプト、証拠スクリプト、レビューゲート JSON、レビュアーの返信、証拠ログが含まれます。mission-proof は、合格した証拠、不合格のゲート、再実行、レビュアーの判断、任意の手動ベースラインデータを要約します。

ターミナルのデモ

README のメディアを再生成します。

npm run docs:screenshots
npm run docs:demos

5.0.0 の変更点

5.0.0 では、Proof Broker と Review Gate を、明示的かつ再開可能な証拠優先の レビューループとして実装しました。

• projscan proof-broker --intent "<change>" --bootstrap-contract は、明示的に要求された場合に限り、次のスコープ付き Proof Contract を書き込みます。その後、ブートストラップのメタデータと、ブートストラップ後に実行する次のコマンドを含む PR Passport の出力を返します。
• projscan review-gate --intent "<change>" --bootstrap-contract は、レビュアーゲート上でも同じ処理を行い、対象のワークツリーに差分がある場合は、停止して契約を再作成する手順を明示します。
• projscan review-gate --contract .projscan/proof-contract.json --pr-comment は、ステータス、レビュー許可の判断、証拠の不足、契約再作成のガイダンス、存在する場合はブートストラップのステータス、必須レビュアー、次のコマンド、アーティファクトのパスを含む PR コメント用の Markdown を出力します。
• projscan review-gate --contract .projscan/proof-contract.json --ci --fail-on-needs-proof は、簡潔な CI サマリーを出力し、ゲートが ready になるまで 0 以外の終了コードを返します。
• Proof Broker と Review Gate の JSON では、コンソール出力と埋め込み Markdown の内容が一致するようになりました。レビュー画面から契約が作成された場合は、Bootstrap セクションも含まれます。
• ProjScan は Review Gate のアーティファクトを .projscan/review-gate.json または .projscan/review-gates/<name>.json に書き込みます。パストラバーサル、シンボリックリンクの参照先、無関係な上書き先は拒否します。
• MCP には引き続き projscan_review_gate と projscan_proof_broker が含まれ、MCP のツール数は 51 のままです。証拠を返しますが、証拠コマンドは実行しません。
• パッケージは、更新されたレポート型と追加のブートストラップメタデータを含む computeReviewGate() と computeProofBroker() をエクスポートします。
• リポジトリ内のエージェント向けワークフローガイダンスは [email protected] で動作するようになりました。新しいタスク、検証、引き継ぎ、リリース、メンテナー確認の作法を運用上のリリースループとして採用しています。

4.17.0 リリースノート

4.17.0 では、Agent Change Passport と Live Guard が追加されました。

• projscan passport --intent "<task>" --save-contract .projscan/proof-contract.json は Proof Contract を作成し、現在の作業ツリーをチェックして、 境界、レシート、証明の再生、Proof Sufficiency、 レビュアーのアクション、次のコマンドを含むローカルパスポートを 1 つ返します。
• projscan passport --contract .projscan/proof-contract.json --output .projscan/passport.json は JSON ハンドオフアーティファクトを書き込みます。ProjScan は .projscan/passport.json または .projscan/passports/<name>.json に書き込み、 パストラバーサルを拒否し、シンボリックリンクのパスをチェックして、 関係のないファイルの上書きを拒否します。
• projscan guard --contract .projscan/proof-contract.json は、現在の差分が 承認された境界内に収まっているかを報告します。--watch はエージェントのセッション中に ポーリングし、--fail-on-drift はガードが逸脱を検出するとゼロ以外の値で終了します。
• MCP に projscan_passport が追加され、MCP の提供ツール数は 49 になりました。 このツールは、MCP に証明コマンドの実行機能を追加することなく、 エージェントにパスポートの証拠を返します。
• Passport は --task-id <id> --emit-baseframe を使って Baseframe の評価証拠を添付できます。その間、ProjScan が 所有する範囲は、評価アーティファクトと共有マニフェストの更新に限定されます。

4.16.0 リリースノート

4.16.0 では、Baseframe Suite の評価エクスポートが追加されました。

• projscan assess --intent "<task>" --task-id <id> --emit-baseframe は .baseframe/evidence/<task-id>/projscan-assessment.json に書き込みます。
• ProjScan は、AgentLoopKit、AgentFlight、および不明なマニフェストフィールドを 保持しながら、.baseframe/agent-workflow.json を自身のステータスで更新します。
• パッケージは createBaseframeAssessment() に加え、Baseframe v1 の 評価およびワークフローマニフェストの型をエクスポートします。
• アーティファクトの書き込みはローカルでアトミックに行われ、タスク ID が検証され、 パストラバーサルとシンボリックリンクの出力パスから保護されます。

4.15.0 の更新内容

4.15.0 では、証明を優先する変更サイクルを強化しました。

• projscan prove --intent "<change>" は、編集前にローカルの Proof Contract を作成します。変更が許可されたファイル、変更が禁止されたファイル、リスクのあるコントラクト、想定されるテスト、不足している回帰テストの証拠、証明コマンド、ロールバック、信頼度、Trust Memory のシグナル、証拠の不足、レビュアー向けガイダンス、および各リスク領域の proofRequirements を明示します。
• projscan start --intent "is my agent allowed to change billing retry logic?" は、projscan prove に直接ルーティングされるため、エージェントの変更権限を尋ねるプロンプトは、広範なチェックリストではなく、範囲を限定したコントラクトから始まります。
• projscan prove --run -- <command...> は、シェル実行を無効にした状態で、指定されたローカルの証明コマンドを実行します。.projscan/proof-logs/ の下に機密情報を伏せたログを保存し、prove-run の台帳行を追加します。また、prove --changed で自己申告の証拠ではなく、実行済みの証明を再実行できるようにします。
• projscan prove --changed は、保存済みのコントラクトに照らして現在の作業ツリーを検証し、PR、エージェント、CI 向けに Proof Receipt を生成します。変更ファイルの分類では、レビュアーがコピーできる判断を提示する前に、許可された本番環境向けの編集、想定されるテスト、ドキュメント、生成された証明アーティファクト、設定／セキュリティのドリフト、禁止された変更、想定外の本番環境向け変更を分類します。Receipt には、再実行のステータス、タイムラインイベント、changedAfterProof、再実行コマンド、Receipt のフィンガープリントを含む proofReplay も記載されます。Proof Sufficiency では、各 proofRequirements 行の証明が、strong、adequate、weak、missing、stale、failed のいずれであるかを示します。
• チーム用 Proof Recipes では、リポジトリに .projscanrc.json へのパス一致型 proofRecipes の追加を許可します。一致するレシピは、Proof Contract と Proof Receipt に必須コマンド、レビュアー、禁止されるドリフトを追加します。
• projscan prove --record-command "<command>" --exit-code <code> は、CI または別のランナーから証明を取り込む際に、コマンド、所要時間、変更ファイルのフィンガープリント、機密情報を伏せた出力の概要、および任意のログパスを含むローカル Proof Ledger の行を追加します。
• すべての prove JSON レポートには verifiedWorkflow が含まれます。これにより、エージェントは Markdown を解析せずに、次のアクション、次のコマンド、スコープのステータス、証明のステータス、proofSufficiency のステータス、レビュアーの判断、および証明が古い／不足／失敗していることを示すフラグを読み取れます。
• 保存済みの Mission Control バンドルは、mission.sh が既存の証明キューを実行する際に Proof Ledger の行を追加します。スクリプトは引き続き、人間向けに証明ログとステータス JSONL を書き込みます。
• projscan evidence-pack --pr-comment は、コントラクトと台帳が利用可能な場合、最新の Proof Receipt の概要を含めます。これにより、PR コメントに証明のステータス、証明の再実行、レビュアーの判断、スコープ、古い証明、失敗した証明、証明の充足度、レシピの不足、必須レビュアー、証明後に変更されたファイル、Receipt のフィンガープリント、再実行コマンドが表示されます。
• 証明アーティファクトの偽造がより困難になりました。Proof Contract と Proof Ledger の読み取りではシンボリックリンクによる範囲外へのアクセスを拒否し、証明ログではより多様な単独のトークン／キー形式の機密情報を伏せ、生成されたミッションスクリプトでは実行前にシェル制御構文を拒否します。
• 証明ワークフローを支えるコードベースを小さくし、レビューしやすくしました。Mission Control、bug-hunt、quality-scorecard、workplan、adoption、start-mode のルーティング、intent のルーティングにあるソースコードのホットスポットを、アーキテクチャテストを備えた専用ヘルパーに分割しました。
• MCP に projscan_prove が追加され、MCP のツール数は 48 になりました。

4.14.0 の更新内容

4.14.0 では、Verified Change Workflow と Executed Proof Runner が導入されました。

• projscan prove --intent "<change>" は、編集前にローカルの Proof Contract を作成します。
• projscan prove --run -- <command...> は、シェル実行を無効にした状態で、指定されたローカルの証明コマンドを実行し、機密情報を伏せた Proof Ledger の行を書き込みます。
• projscan prove --changed は、PR、エージェント、CI 向けに Proof Receipt を生成します。
• projscan evidence-pack --pr-comment は、コントラクトと台帳が利用可能な場合、最新の Proof Receipt の概要を含めます。
• MCP に projscan_prove が含まれ、MCP のツール数は 48 になりました。

4.12.1 リリースノート

4.12.1 は、Proof Cards V2 リリースに向けたシミュレーター精度のパッチです。

• projscan simulate --plan で、s.ts のような1文字のファイル名が、広範な計画テキストに一致するものとして扱われなくなりました。
• シミュレーターの用語重複に関するエビデンスで、生成されたエージェント／キャッシュのパスと、関連性の低い計画用語をフィルタリングするようになりました。そのため、計画に具体的なリポジトリの対象が記載されていない場合に、ログや証拠アーティファクトが該当ファイルとして有力視されることがなくなりました。

4.12.0 リリースノート

4.12.0 は、Proof Cards V2 の日々のトラストループを実現するリリースです。

• Proof Cards に、エビデンスの強さ、信頼度の理由、エビデンスの不足、ランキングの理由、Trust Memory のコンテキスト、AgentLoopKit のハンドオフパケットが表示されるようになりました。
• projscan assess --feedback <path> で、ローカルのレビュアーからのフィードバックをランキングと信頼度に適用できます。
• projscan start --intent "is this safe to commit?" は、projscan assess --mode fix-first で開始し、プリフライトを証拠として維持するようになりました。
• projscan simulate --plan "<change plan>" では、範囲を限定した抽出、回帰テストを最初に行う方法、変更しない方法を比較してから、最も安全な選択肢を推奨します。

4.11.1 リリースノート

4.11.1 は、エビデンス優先リリースに向けた公開 README メディアの更新です。

• projscan assess と projscan simulate 用の Proof Cards 専用スクリーンショットを追加しました。
• 公開メディアに47個のツールを備えた MCP の機能範囲が表示されるよう、README のスクリーンショットを再生成しました。
• ウェブサイトへの引き継ぎガイダンスを更新し、不変の v4.11.1 メディア URL を使用するようにしました。

4.11.0 リリースノート

4.11.0 は、エビデンス優先のエンジニアリングコマンドセンターを提供するリリースです。

• projscan assess は、品質、バグ調査、プリフライトのエビデンスを、修正優先のガイダンスとリスクの変化を含む Proof Cards に変換します。
• projscan simulate --plan "<change plan>" は、編集前に、該当する可能性の高いファイル、テスト、コントラクト、ロールアウト、証拠確認用コマンド、変更前後のリスクを予測します。
• MCP で projscan_assess と projscan_simulate を含む47個のツールを利用できるようになりました。

MCP のセットアップ

コーディングセッション中にエージェントから projscan を呼び出す場合は、MCP を使用してください。

Claude Code：

claude mcp add projscan -- npx -y projscan mcp

Codex CLI：

[mcp_servers.projscan]
command = "npx"
args = ["-y", "projscan", "mcp"]

Cursor、Windsurf、Cline、Continue、Zed などの MCP クライアントでも、同じコマンドを起動できます。

npx -y projscan mcp

クライアントが notifications/file_changed に対応している場合は、--watch を追加してください。

npx -y projscan mcp --watch

エージェントへの質問

エージェントへの質問	CLI または MCP の方法
認証を実装しているファイルはどれですか？	projscan search "auth" --format json
このファイルをインポートしているのは誰ですか？	projscan semantic-graph --query importers --file src/auth/jwt.ts --format json
このシンボルの名前を変更すると、何が壊れますか？	projscan impact --symbol buildCodeGraph --format json
何を最初に修正すべきですか？	projscan bug-hunt --format json
今週、リスクが高く修正する価値があるものは何ですか？	projscan assess --goal "make this repo safer to ship this week"
このリファクタリングは実施する価値がありますか？	projscan simulate --plan "split bugHunt.ts into ranking, evidence, and output modules"
エージェントはこの変更を行うことを許可されていますか？	projscan start --intent "is my agent allowed to change billing retry logic?"
変更はスコープ内にとどまりましたか？	projscan prove --changed --contract .projscan/proof-contract.json --format markdown
レビュアーはこのエージェントからの引き継ぎを信頼できますか？	projscan passport --contract .projscan/proof-contract.json --format markdown
PR にはどの証拠を含めるべきですか？	projscan proof-broker --contract .projscan/proof-contract.json --pr-comment
この PR はレビューに出せる状態ですか？	projscan review-gate --contract .projscan/proof-contract.json --ci --fail-on-needs-proof
エージェントは契約から逸脱していますか？	projscan guard --contract .projscan/proof-contract.json
リスクが高く、カバレッジが低いファイルはどれですか？	projscan coverage --format json
エージェントは次に何をすべきですか？	projscan workplan --format json
この PR にはどの証拠を含めるべきですか？	projscan evidence-pack --pr-comment
このブランチはマージできる状態ですか？	projscan preflight --mode before_merge --format json

コマンド一覧

コマンド	次の用途に使用します
projscan start	最初の60秒で概要を把握し、ルーティングと Mission Control を確認する場合
projscan understand	引用付きのリポジトリマップ、ランタイムフロー、公開コントラクト、変更準備状況を確認する場合
projscan preflight	編集、コミット、マージの続行・注意・ブロックを判定する場合
projscan assess	Proof Cards、リスク差分、修正優先のガイダンスを含む、証拠優先の評価を行う場合
projscan simulate	編集前に、変更計画のリスク差分をシミュレーションする場合
projscan prove	実行可能な Proof Contracts、Verified Workflow JSON、Proof Receipts を作成する場合
projscan passport	境界、レシート、証明、レビュアーのアクションを含むローカル変更パスポートを作成する場合
projscan proof-broker	必須の証明、証明の不足、レビュアー、次のコマンドを含む PR Passport を作成する場合
projscan review-gate	証明の負債、再コントラクトのガイダンス、CI の終了結果を含むレビュアー準備状況のゲートを確認する場合
projscan guard	保存済み Proof Contract と現在の作業ツリーを照合する場合
projscan evidence-pack	リスク、担当者、証明レシート、次のコマンドを含むレビュー用証拠を作成する場合
projscan bug-hunt	ヘルス、ホットスポット、セッション、プリフライトの証拠から修正キューを優先順位付けする場合
projscan workplan	証明と引き継ぎ文を含む、順序付けられたエージェントタスクを作成する場合
projscan doctor	プロジェクトのヘルス、ツールの不足、デッドコード、サプライチェーンのシグナルを確認する場合
projscan review	構造的な差分、リスク、循環、関数、依存関係から、1回の呼び出しで PR をレビューする場合
projscan impact	名前の変更、削除、アップグレード前に、ファイルまたはシンボルの影響範囲を確認する場合
projscan semantic-graph	インポート、エクスポート、インポーター、シンボル定義、パッケージのインポーターを確認する場合
projscan dataflow	フレームワークを考慮したソースからシンクへのリスクを確認する場合
projscan hotspots	変更頻度、複雑さ、所有権、カバレッジのリスクを順位付けする場合
projscan coverage	テストカバレッジが弱い高リスクファイルを確認する場合
projscan dependencies	依存関係の一覧、ライセンスの概要、リスクに関する注記を確認する場合
projscan upgrade <pkg>	変更履歴とインポーターの証拠から、オフラインでアップグレードの影響を確認する場合
projscan audit	標準化された npm audit の検出結果と SARIF を確認する場合
projscan coordinate	複数のワークツリーにわたる競合、要求、マージリスクを確認する場合
projscan plugin	ローカルのアナライザーおよびレポータープラグインのワークフローを実行する場合
projscan privacy-check	ローカルスキャンの境界、テレメトリー、無視ルール、ネットワーク対応パスを確認する場合
projscan mcp	stdio 経由で MCP サーバーを実行する場合

フラグが必要な場合は、生成されたコマンドヘルプを実行してください：

projscan help
projscan <command> --help

出力形式

コマンドでは、そのコマンドに適した場合に console、json、markdown、sarif、html を使用できます。

projscan analyze --format json
projscan doctor --format markdown
projscan ci --format sarif > projscan.sarif
projscan evidence-pack --pr-comment
projscan mission-proof --write reports/mission-proof.md

証拠をリポジトリの外に持ち出す場合は、範囲を限定し、機密情報を削除したレポートを使用してください：

projscan analyze --report-scope src/api --redact-paths --format json
projscan analyze --report-scope "src/api,packages/backend" --redact-paths --format json
projscan doctor --report-policy apiEvidence --format markdown

設定

リポジトリのデフォルト設定をソース管理下に置く場合は、.projscanrc.json を作成します。

{
  "minScore": 80,
  "failOn": "warning",
  "baseRef": "origin/main",
  "ignore": ["**/fixtures/**", "**/generated/**"],
  "scan": {
    "includeIgnored": false,
    "scanEnvValues": false,
    "offline": false
  },
  "disableRules": ["large-*"],
  "suppress": {
    "hardcoded-secret": ["src/firebase.ts"]
  },
  "severityOverrides": {
    "missing-prettier": "info"
  },
  "proofRecipes": [
    {
      "id": "billing-critical",
      "matches": ["src/billing/**"],
      "requiredCommands": ["npm test -- tests/billing/retry.test.ts"],
      "requiredReviewers": ["@platform"],
      "forbiddenFiles": ["src/auth/**"]
    }
  ],
  "reportPolicies": {
    "apiEvidence": {
      "reportScope": ["src/api", "packages/backend"],
      "redactPaths": true
    }
  }
}

特定のパスで既知の誤検知を抑制するには、ルールを全体で無効にせずに suppress を使用します。1 行だけに適用する場合は、値の横にインラインディレクティブを追加します。

const firebaseKey = 'AIza...'; // projscan-ignore-line hardcoded-secret -- Firebase web keys are public identifiers

パスにチーム固有の証明が必要な場合は、proofRecipes を使用します。一致するレシピが設定されていると、projscan prove はその証明コマンド、レビュアー、禁止ファイルを契約とレシートに追加します。証明コマンド自体は実行しません。 requiredCommands のないレシピはスキップされ、重複するレシピ ID には最初の有効なレシピが適用されます。

設定のドキュメントは docs/GUIDE.md にあります。

CI

プルリクエストをチェックするには、projscan ci を使用します。

projscan ci --min-score 80
projscan ci --changed-only
projscan ci --format json
projscan ci --format sarif > projscan.sarif

ci --format json の ci.issues[] はアノテーションに対応しており、projscan がデータを持つ場合、各課題に ruleId、severity、message、location、locations、remediation が含まれます。 doctor --format json と ci --format json にも scoreBreakdown が含まれます。これは基本スコア、重大度の重み、カテゴリごとのペナルティ、ペナルティの合計、最終スコア、評価を示します。 デフォルトでは、警告またはエラーがある場合にのみ、ci はしきい値を下回るスコアを理由に失敗します。従来の厳格な動作には "failOn": "info" を、エラーのみをブロックするには "failOn": "error" を設定します。

GitHub Actions の例：

name: ProjScan
on:
  pull_request:
    branches: [main]

permissions:
  contents: read
  security-events: write

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 24 }
      - uses: abhiyoheswaran1/projscan@v1
        with:
          min-score: '80'
          changed-only: 'true'

プラグイン

ローカルプラグインを使うと、projscan のコアを変更せずに、チーム固有のアナライザールールやカスタムの人間向けレポートを追加できます。

ローカルプラグインの読み込み

projscan plugin list
projscan plugin validate .projscan-plugins/team-radar.projscan-plugin.json
projscan plugin test .projscan-plugins/team-radar.projscan-plugin.json
PROJSCAN_PLUGINS_PREVIEW=1 projscan doctor --reporter team-radar

コマンドごとのサポート一覧を生成するには、projscan help を実行します。

プラグインのドキュメント：

• プラグインの作成
• プラグインギャラリー
• 2.0 移行ガイド
• マニフェストスキーマ

サポート対象のリポジトリ

projscan は TypeScript、JavaScript、Python、Go、Java、Ruby、Rust、PHP、C#、Kotlin、Swift、C++ を読み込み、利用可能な場合は AST 対応アダプターを使用します。また、C、Shell、CSS、HTML、SQL、Dart、Lua、Scala、R、および関連するプロジェクトファイルのファイルレベルのシグナルも検出します。

フレームワークのシグナルは、React、Next.js、Vue、Nuxt、Svelte、Angular、Express、Fastify、NestJS、Vite、Tailwind CSS、Prisma、Remix、SvelteKit、Astro、Hono、Koa、および一般的なモノレポ構成に対応しています。

JavaScript と TypeScript では @babel/parser を使用します。JavaScript 以外の言語では、パッケージに同梱された tree-sitter WASM 文法を使用します。公開パッケージには直接のランタイム依存関係が 7 つあります。オプションのセマンティック検索では、ピア依存関係 @xenova/transformers を使用します。

信頼モデル

領域	projscan の動作
ソースコード	コアスキャンはローカルファイルを読み取り、結果をお使いのマシンに保存します。
.gitignore	--include-ignored を指定しない限り、無視対象のファイルはスキャンされません。
.env	projscan はデフォルトでパスを報告します。--scan-env-values を指定すると値を読み取ります。
ネットワーク	audit、レジストリチェック、オプトインのテレメトリ、任意のセマンティックモデルのダウンロードでは、ネットワークに接続することがあります。
テレメトリ	projscan telemetry enable を実行するか、init team のプロンプトに同意するまでオフです。
プラグイン	PROJSCAN_PLUGINS_PREVIEW=1 を設定し、doctor、ci、analyze、plugin test --execute などの実行パスを通ると、ローカルのプラグインコードが実行されます。
リポジトリへの書き込み	ソースへの書き込みには、明示的な修正コマンドが必要です。キャッシュ、保存済みミッション、Proof Contracts、Proof Ledger の行、証明ログは .projscan* ローカルディレクトリ内に保存されます。

監査用ヘルパー：

projscan privacy-check
projscan telemetry status
projscan telemetry explain
projscan doctor --offline

サプライチェーンスキャナーは、git、npm audit、web-tree-sitter、任意のプラグイン、任意のセマンティック検索で使用されるパッケージ文字列や API にフラグを立てることがあります。上記のランタイムパスは、それらの機能が実行されるタイミングを示しています。

インストールに関する注意事項

[email protected] には、直接のランタイム依存関係が 7 つあります。

• @babel/parser
• @babel/types
• chalk
• commander
• fast-glob
• ora
• web-tree-sitter

グローバルインストール中に npm が allow-scripts の警告を表示した場合は、表示されたパッケージ名を確認してください。projscan のコアは、5.0.0 のランタイムで node-gyp による文法のビルドを必要としません。npm が projscan@latest のインストールスクリプトを報告した場合は、警告のテキストを添えて Issue を作成するか、projscan feedback intake --text "<warning text>" --format json を実行して、セットアップの信頼性に関する具体的なタスクに変換してください。

文法パッケージはビルド時のソースであり、グローバルインストールの依存関係ではありません。公開されている文法アセットには tree-sitter-python.wasm と tree-sitter-c_sharp.wasm が含まれます。

詳細ドキュメント

• 完全ガイド
• 最初の 10 分
• ロードマップ
• 導入ワークフロー
• スウォームの調整
• 安定性ポリシー
• テレメトリポリシー
• セキュリティポリシー

貢献

PR を作成する前に CONTRIBUTING.md をお読みください。貢献には、そこに記載されている MIT License と DCO 1.1 の証明が適用されます。

法的事項

• ライセンス：MIT
• 免責事項：DISCLAIMER.md
• セキュリティポリシー：SECURITY.md
• プライバシーに関する通知：PRIVACY.md
• テレメトリポリシー：TELEMETRY.md
• 商標およびブランドポリシー：TRADEMARKS.md
• サードパーティに関する通知：THIRD-PARTY-NOTICES.md

の一部