gitnexus-plan

gitnexus-plan — 実装可能なエンジニアリング計画

エンジニアリングタスクの実装可能な計画を作成します。GitNexus はナビゲーション層（どこを見るか）、ステートメントレベルの PDG は制約層（何が動作をゲートし、何を供給するか）、そしてネイティブの対象を絞ったソース読み取りは検証層（今実際に何が真実か）です。出力は計画ドキュメントと、後続の実装エージェント（gitnexus-work、または任意の実行者）が調査を繰り返すことなく消費できる、コンパクトで機械可読な実装コンテキストパックです。

/gitnexus-plan <task description>
/gitnexus-plan impact_depth:3 depth:deep <task description>   # knob overrides, see Configuration

このスキルは計画を立てます。実装は決して行いません。 実行中は、本番コード、テスト、設定を変更しないでください。書き込む唯一のリポジトリファイルは計画ドキュメントです（リポジトリ外に保持する作業台帳は問題ありません）。その他に許可される唯一の状態変更は、analyze --index-only によるインデックス更新で、これは .gitnexus インデックスストアのみを書き込みます。アナライザーの dist/ 出力をビルドしてはならず、ソース、テスト、設定、評価データを変更してもいけません。古いアナライザーの来歴は、ソースに重み付けされた制限として開示され、計画実行によって修復されることは決してありません。

厳格なルール

• 台帳が最優先。 すべての GitNexus 呼び出しとすべてのリポジトリファイル読み取りの前に、コンテキスト台帳を確認してください。同じ質問にすでに回答したクエリを繰り返したり、変更されていない範囲を再読したりしないでください（許可される繰り返しは references/context-ledger.md で定義されています。このスキル自身の参照ファイルは台帳管理の対象外です）。
• すべてのグラフクエリは、名前を付けた計画上の質問に答えます。 質問と結論を台帳に記録してください。探索的な掘り起こしは行いません。
• ソースはグラフに勝ります。 グラフはナビゲートするものであり、現在のソースが権威です。主張する前に検証してください（フェーズ 4 を参照）。コメントは最も弱い証拠です — 実行可能なコードより強いものには決してなりません。
• 捏造は禁止。 シンボル、ファイル名、テスト名、ツール結果、PDG エッジを決してでっち上げないでください。不明な点は 前提と未解決の質問 に記載します。
• スコープクリープは禁止。 タスクが求めていない隣接するリファクタリングは、提案された変更ではなく、明示的に先送りされたフォローアップとして計画 §12 に記載します。
• HEAD だけでなく、作業ツリーの証拠を固定してください。 すべての計画フォームは、references/context-ledger.md で定義されたバージョン管理されたグローバルダーティダイジェストと、ソートされた引用パスマニフェストを保持します。これは scripts/evidence-provenance.mjs と references/evidence-provenance.md にあるポータブルヘルパーとバイトコントラクトでのみ生成してください。ダイジェストを再実装してはいけません。
• 計画はヘルパーを通じてのみ書き込んでください。 生成される計画のパスは、正規化されたリポジトリ相対の docs/plans/YYYY-MM-DD-gitnexus-plan-<3-5-word-slug>.md パスです。完全な UTF-8 ドキュメントをメモリ内または対象リポジトリ外のスクラッチパッドで構成し、それをヘルパーの write-plan コマンドに標準入力で渡してください。宛先を直接書き込んだり、安全なライターが失敗したときに外部出力パスにフォールバックしたりしないでください。
• 既存の計画はヘルパーを通じてのみ読み込んでください。 Deepen は scripts/evidence-provenance.mjs read-plan を呼び出し、ディスクリプタに固定されたレシートから正確にデコードされた plan_bytes_base64 を解析し、そのレシートの正規の generated_plan_path と plan_digest を 1 つのバインディングとして保持する必要があります。直接の字句パス読み取りを解析したり、ある計画のダイジェストを別のパスに適用したりしないでください。
• 十分になったら停止してください。 十分な証拠があれば探索は終了します。計画は、費やすトークンに比例して単調に改善するものではありません。

フェーズ 0 — 解析と分類

references/context-ledger.md を読み、タスクとともに台帳を開きます: 元のリクエスト、解釈された目標、受け入れ基準。タスクを分類します:

カテゴリ	姿勢 (深さ · 計画形式 · ツール呼び出し予算 · 鮮度)
バグ修正 (ローカル)	狭い、主要シンボル 1〜2 個、impact_depth 1 · コンパクト · 約15 · 許容
機能追加	デフォルト設定 · コンパクト · 約30 · 許容
リファクタリング / 共有 API 変更	影響分析必須、impact_depth 3 · フル · 約45 · 厳格
パフォーマンス	デフォルト + パフォーマンス PDG モード (references/pdg-slice.md) · フル · 約45 · 厳格
セキュリティ	デフォルト + セキュリティ PDG モード + explain テイント検出 · フル · 約45 · 厳格
依存関係のアップグレード / 移行	影響分析 + 互換性重視; PDG はほとんど不要 · コンパクト · 約20 · 許容
並行性 / トランザクション	制御フロー + 状態変更 PDG 重視 · フル · 約45 · 厳格
テスト改善 / ドキュメント	最も狭い: 通常は影響分析も PDG パスも不要 · コンパクト · 約10 · 許容
アーキテクチャ変更 / スパイク	最も広い: まずクラスター + プロセス · フル · 上限なし · 厳格

カテゴリの姿勢は Configuration のベースラインを上書きします; 明示的な key:value 呼び出しノブは両方とも上書きします。複数の行に一致するタスクはそれらを組み合わせます: 最も広い深さを採用し、フォーカス領域を統合します。

シードされたエビデンス。 完了した調査がすでに検証済みの 所見を提供している場合 — 完了したレビュー、path:line アンカー付きのトリアージ文書、名前付きの失敗シナリオ — そこから台帳を開きます: ソース文書を 開始時の台帳エントリとして引用し、すでにカバーしている 領域に対してグラフのはしごを再実行するのではなく、それを直接基に計画を立てます。 エビデンスが証明していることを再導出するのは、ターン経済のルールに 反して消費される予算です。フェーズ 4 は、Proposed Changes が引用するものを ピン留めされたコミットで引き続きソース検証します — シードは探索を置き換えるものであり、 検証を置き換えるものでは決してありません。

深さはユーザーの決定であり、最初に一度だけ尋ねます。 インタラクティブな セッションで、呼び出しに明示的な深さのシグナルが含まれていない場合 (depth:、form:、freshness: ノブがなく、Deepen モードでもない)、 フェーズ 1 の前にブロッキング質問を 1 つ尋ねます — この計画はどの程度の深さにすべきですか?

1. クイック — depth:narrow form:compact freshness:accept。最速の有用な 計画: 主要シンボル 1〜2 個、最小限のグラフ作業、コアセクションのみ。
2. スタンダード — 上記のカテゴリの姿勢をそのまま適用します。分類が 別の判断を示さない限り、これを推奨します。
3. ディープ — depth:deep form:full freshness:strict。全 13 セクション、 impact_depth 3、クラスター/プロセスを読み取り、中心的な 関数に対する PDG スライス。

回答は、呼び出しで入力された場合とまったく同じようにノブを設定します; 明示的なノブが優先され、質問はスキップされます。ヘッドレス実行では決して 尋ねません — カテゴリの姿勢がそのまま適用されます。最初に尋ねることは、 完成した計画を後から深めることを提案する代わりになります: Deepen モード(以下)は、 既存の計画文書を強化するためのメカニズムとして残ります — 後のセッション、 レビューの所見、実行者からの差し戻し — デフォルトのフォローアップ質問ではありません。

ターン経済は成果物です。 計画はトークンあたりの意思決定の質で 評価され、徹底性のパフォーマンスではありません (測定例: 2 行の変更に対する 63 ターンの計画 — GitNexus リポジトリの eval/workflow_bench/)。カテゴリのツール呼び出し 予算内に収めてください; 予算が尽きたときにまだ未解決の質問がある場合は、 さらに掘り下げるのではなく §12 に記録してください — 実行者はいずれにせよ安価に再検証します。

フェーズ 1 — アンカーと鮮度

1. 対象リポジトリを解決します。不明な場合は list_repos を使用し、そうでなければ 作業ディレクトリをカバーするインデックス済みリポジトリを使用します。複数の リポジトリがインデックスされている場合は、すべての呼び出しで repo を明示的に 渡してください。
2. リポジトリの現在の HEAD コミットを台帳に記録します。プラン内のすべての行番号 引用はこれに固定されます。
3. アナライザーランナーを解決して記録します（このスキル内のすべての analyze コマンドで使用されます）。プロジェクトにランナーがある場合（以前の analyze が インデックスの隣に配置したもの）は node .gitnexus/run.cjs analyze …、そうで なければ gitnexus analyze …（インストール済み CLI — npm install -g gitnexus）、 それもなければ npx gitnexus analyze … を使用します。そのパス/バージョンと、 利用可能なソース/ビルドの識別情報を記録します。タイムスタンプから来歴を でっち上げてはいけません。
4. gitnexus://repo/{name}/context を読みます — コードベースの概要 + 陳腐化チェック です。鮮度ゲート。 陳腐化したグラフ上で構築されたプランは、陳腐化した ブラスト半径の主張を行います — しかし再インデックスはプランニングセッションが 負担する最大の固定コストであるため、ゲートはカテゴリごとに価格設定されます：
   • コンパクトプランのカテゴリはデフォルトで freshness: accept です。現在の グラフ上でプランし、ソース検証をより高く重み付けします — これらのプランは グラフのエビデンスをほとんど引用しません。グラフの主張が重要になる場合 （例：Proposed Changes が d=1 の依存リストに依拠している場合）にのみ、 プラン途中でのリフレッシュにエスカレートし、その場合に限ります。
   • フルプランのカテゴリはデフォルトで freshness: strict であり、その下で：
   • アナライザー来歴チェック — リフレッシュの前に。 解決されたランナー識別情報 をインデックスメタデータと比較し、アナライザーソースのチェックアウトでは 現在のアナライザーソースとも比較します。識別情報が陳腐化しているか不明な 場合は、出力を構築せず、そのグラフを重要にしないでください。 stale analyzer provenance — source-weighted limitation を index_refresh、プランヘッダー、および §12 に記録し、対象を絞ったソース読み込み に依拠するか、build-current ゲートを所有する gitnexus-work に実行を委ねて ください。
   • 陳腐化したインデックス → 解決されたランナーを介して analyze --index-only を 実行し（タスクカテゴリがフェーズ 3 に到達する場合は --pdg を追加）、 ランナーの来歴が既知の最新である場合にのみコンテキストリソースを再読み 込みします。リフレッシュ予算はここで一度だけ述べます：プランニングセッション ごとに、フェーズ 1 で最大 1 回の --index-only リフレッシュに加えて、 フェーズ 3 で最大 1 回の後続の --pdg アップグレード（フェーズ 1 の リフレッシュに --pdg が欠けていた場合のみ）です — Deepen 実行はそれ自体が 独自のセッションです。各コマンド、ランナー識別情報、および結果を台帳の index_refresh に記録します。
   • リフレッシュが失敗したか非現実的である場合（インデックスへの書き込みアクセスが ない、リポジトリサイズが法外）、または freshness: accept が渡された場合 → 陳腐化したグラフ上で続行し、ソース検証をより高く重み付けし、陳腐化とスキップ されたリフレッシュをプランヘッダーと Assumptions に明記します。
   • リソースが読み取れないがツールは動作する場合 → ツールのみで続行し、鮮度を 不明として扱い（ソースをより高く重み付け）、プランに注記します。
   • GitNexus が完全に利用できない場合 → フォールバックモード（以下）に 切り替えます。
5. アーキテクチャ規模のタスクに限り、gitnexus://repo/{name}/clusters と .../processes も読みます。

フェーズ 2 — グラフナビゲーションのはしご

現在の台帳の問いに答えるために、最も狭い操作をこの順序で使用します。予算は、台帳で有効なプライマリシンボルが最大 max_primary_symbols (5) 個、関連シンボルが max_related_symbols (20) 個です。

1. query {search_query, task_context} — タスクの概念、実行フロー、モジュール、および関連するテストを特定します。
2. context {name} — 各候補プライマリシンボルの 360° ビュー: 呼び出し元、呼び出し先、分類された参照、プロセス。プライマリに昇格させるか破棄します。ambiguous な結果 (ランク付けされた候補) は、kind / file_path / uid で絞り込んだ 1 回の再試行で解決します — その再試行は許可された繰り返しです。
3. impact {target, direction} — 共有される、または接続性の高いシンボルの上流/下流の影響範囲 (maxDepth = impact_depth、ハブシンボルでは最初に summaryOnly: true、その後で掘り下げる — 許可された繰り返し)。d=1 の項目 — 直接 (深さ 1) の依存関係 — を記録し、計画はそのすべてを考慮しなければなりません。
4. trace {from, to} — タスクが A がどのように B に到達するか にかかっている場合、連鎖的な context ホップの代わりに 1 回の呼び出しで済ませます。
5. ステートメントレベルの PDG — フェーズ 3、変更の中心となる関数に対して。
6. cypher — 最後の手段。上記のツールでは表現できない正確なグラフの問いにのみ使用します。まず gitnexus://repo/{name}/schema を読み、すべてのクエリをアンカーし LIMIT します。
7. detect_changes {scope} — 既存の未コミットまたはブランチの作業に対して計画する場合にのみ。

デフォルトですべてのツールを実行しないでください。ローカルなテスト修正では、ステップ 2 ではしごを終えてもかまいません。

フェーズ 3 — ステートメントレベルの PDG スライス

変更に最も中心的に関わる 1〜3 個の関数について、境界付きの PDG コンテキストスライスを構築します。references/pdg-slice.md を読み、それに従ってください — ツール呼び出し、包含基準、深さの境界、スライスのスキーマ、セキュリティモードとパフォーマンスモード、および PDG レイヤーがない場合のフォールバックは、それが規定しています。

フェーズ 4 — 対象を絞ったソース検証

GitNexus はどこを見るべきかを示しました。次に、そこに何があるかを確認します。通常のファイル読み取り (正確な行範囲、本当に必要でない限りファイル全体は読まない) を使用して:

• 計画が引用するすべてのソース範囲を読みます: シグネチャ、分岐条件、状態の変更、エラーパス、動作を変える付近のコメント。コンパクトな計画は引用が少なくなります — 引用したものを検証し、検証するものを増やすために引用の集合を広げないでください。
• GitNexus がプライマリシンボルに関連付けたテストを読みます。特定していないテストが存在すると決して主張しないでください。
• 計画が指定するビルド/テストコマンドが実際に存在するか (package.json のスクリプト / CI ワークフロー) を検証し、基盤となるバイナリを直接呼び出すよりも、前提条件 (pre-hooks) を伴うスクリプト形式を優先してください。
• 変更を制約するリポジトリの規約 (AGENTS.md、GUARDRAILS.md、lint/build 設定) を確認します — 変更が触れる部分のみ。
• 進めながら、各台帳シンボルを source_verified: true とマークします。Proposed Changes で名前が挙げられているシンボルは、ソース検証済みでなければなりません。
• グラフとソースが矛盾する場合: ソースを信頼し、その不一致を台帳と計画に記録し、再インデックスを推奨します。古いグラフデータを事実として提示しないでください。
• 構成の直前に、references/evidence-provenance.md で指定されたとおりに scripts/evidence-provenance.mjs を呼び出して、バージョン付きの evidence_provenance スナップショットを再計算します: すべてのダーティパスにわたる正規のグローバルダーティダイジェストと、引用されたすべてのパスのソート済みマニフェスト (オブジェクト種別および HEAD/index/ワークツリー/未追跡レイヤーのダイジェストを含む)。計画中に変更された引用は再読み取りします。生成された計画のパスのみを除外します。

証拠の階層、強い順: 現在のソースと設定 → 現在のテストと実行可能な動作 → コンパイラ/ビルド/lint の出力 → GitNexus グラフと PDG → ドキュメントとコメント。

フェーズ 5 — 計画を構成する

1. references/plan-template.md を読み、台帳からカテゴリのフォーム — コンパクト （コアセクション、パックを除いて 80 行以内）またはフル（全 13 セクション）— に入力し、主張にテンプレートの 4 つのクラス — [verified]、[graph]、[inferred]、[assumed] — のタグを付け、未解決の 疑問点を §12 に振り分けます。
2. references/context-pack.md に従って実装コンテキストパックを構築します （これは計画のセクション 11 です）。コンパクト形式とフル形式の両方で必須の evidence_provenance を含めます。
3. generated_plan_path を、計画対象のリポジトリのルート配下の docs/plans/YYYY-MM-DD-gitnexus-plan-<slug>.md に設定します（フェーズ 1 の 対象リポジトリであり、必ずしも cwd ではありません）。3〜5 語のケバブケースの slug と、ドキュメント内ではリポジトリ相対パスを使用します。 その宛先を作成せずに完全なドキュメントを構成し、references/evidence-provenance.md で指定されているとおりに、その正確な UTF-8 バイト列を scripts/evidence-provenance.mjs write-plan にパイプします。このヘルパーは 不足している親ディレクトリを安全に作成します。初回の計画では --replace を 渡してはなりません。安全書き込みの失敗は計画の公開をブロックします。それを 報告し、直接書き込んだり、外部の宛先を選んだり、リポジトリ相対のprovenance 契約を弱めたりしないでください。スナップショットコマンドとライターコマンドは 同じ厳格な generated-plan のファイル名／日付バリデータを適用します。どちらの 呼び出しでも、ソース、.git、任意の docs/plans/ パスで代用しないでください。
4. チャットで提示するもの: 目的、提案された変更の概要、実装順序、上位のリスク、 未解決の疑問点、計画ファイルのパス。ドキュメント全体をチャットに貼り付けないで ください。

ディープンモード

/gitnexus-plan deepen <plan-path> は、新しいプランを作成する代わりに、既存のプランをその場で強化します。

1. 対象リポジトリと正規化されたリポジトリ相対のプラン候補を解決し、references/evidence-provenance.md で指定されているとおりに scripts/evidence-provenance.mjs read-plan --repo <root> --generated-plan <candidate> でそれを読み込みます。存在しない、外部にある、脱出する、シンボリックリンクである、またはスコープが異なるパスは拒否します。レシートの正確な plan_bytes_base64 のみをデコードして解析します。その正規の generated_plan_path と plan_digest は、ディープンセッション全体を通じて変更せずに保持します。
2. フェーズ 1 を完全に再実行します — アナライザーのプロベナンスチェックとフレッシュネスゲート(ディープン実行はそれ自体が独自のセッションであり、独自のリフレッシュ予算を持ちます)。
3. 再ピン留めの前に再アンカーします。 プランのグローバルダーティダイジェストと引用パスマニフェストを再計算し、さらにその古い HEAD ピンと現在の HEAD を比較します。変更、リネーム、削除、混在、または新たに存在しなくなった引用パスは、ピンとプロベナンススナップショットが移動する_前に_、その範囲が再読み込みされるか、クレームがダウングレードされます。コミットピンだけを移動すると、ダーティまたは古いクレームが検証済みとして黙って洗浄されます。
4. 呼び出しがノブを明示的にオーバーライドしない限り、depth: deep(impact_depth 3、クラスター/プロセスの読み取り)にエスカレートします。
5. プランの §11 パックから台帳をシードし、再検証します。すべての [graph]/[inferred] クレームは [verified] に向けた的を絞ったパスを受け取ります。すべての [assumed] クレームは解決されるか、その理由とともに保持されます。直接 (d=1) の依存アカウンティングは、リフレッシュされたグラフに対して再チェックされます。PDG スライスは、そのレイヤーが存在する場合、中心的な関数に対して構築または拡張されます。
6. 実行状態を調整します。 gitnexus-work がこのプランのコミットをすでにランディングしている場合(実行途中のルートバック)、HEAD に存在する §7 のステップを完了済みとしてマークし、残りを再シーケンスします — 書き換えられたプランは、ランディング済みのステップをやり直すことなく先頭から実行可能でなければなりません。
7. より深いパスが薄いと示したもの — テストシナリオ、リスク、Definition of Done — を強化し、クレームタグのアップグレードを散文全体に引き継ぎます。
8. scripts/evidence-provenance.mjs write-plan --replace --expected-plan-path <retained-read-plan-path> --expected-plan-digest <retained-read-plan-digest> を通じて同じ正規ファイルを書き換えます。同じ 13 セクション、コンテキストパックは同期を保ち、エビデンスヘッダーは更新されます。--replace はディープンモード専用であり、両方の期待値は同じ read-plan レシートから取得する必要があります。ダイジェスト/パスの不一致があれば公開はブロックされます。成功したレシートの prior_plan_backup_git_path を保持します。これは、置き換えられたプランの検証済み Git 管理バックアップを指します。チャットで差分を要約します。アップグレードされたクレーム、再検証に失敗したクレーム、変更されたセクション、およびそのバックアップパスです。

設定

ベースラインのデフォルト — フェーズ 0 のカテゴリ別の姿勢がこれらを上書きし、タスクテキストの前にあるインラインの key:value トークンが両方を上書きします（このリポジトリにはスキル設定ファイルの仕組みはありません。呼び出し引数がその仕組みです）:

ノブ	デフォルト	意味
depth	カテゴリ別	narrow = impact_depth 1、1 つの関数が明らかに中心である場合のみ PDG。default = この表のとおり。deep = impact_depth 3 + クラスター/プロセスを読み取り
form	カテゴリ別	compact（コアセクション + ミニパック、パックを除いて 80 行以下 — references/plan-template.md を参照）または full（13 セクションすべて）
impact_depth	2	impact の maxDepth
pdg_data_depth	2	PDG スライスにおけるデータ依存ホップ
pdg_control_depth	2	PDG スライスにおける制御依存ホップ
max_primary_symbols	5	台帳の予算（アクティブなシンボル。破棄されたものはカウントしない）
max_related_symbols	20	台帳の予算（アクティブなシンボル。破棄されたものはカウントしない）
max_snippet_lines	30	プラン内で引用される最長のソース抜粋
freshness	カテゴリ別	strict（フルプランのカテゴリ）= グラフに依存する前に、古いインデックス（および欠落している PDG レイヤー）を analyze --index-only [--pdg] で更新する。accept（コンパクトなカテゴリ）= 現在のグラフ上でプランを立て、ソースを重視してラベル付けし、グラフの主張が重要になった場合にのみ更新する

フォールバックモード（GitNexus または PDG が利用できない場合）

1. まず最初に、その旨をチャットとプラン内で伝えてください。
2. 対象を絞ったリポジトリ探索（grep/glob/読み取り）を使用して、呼び出し元、 依存関係、実行フロー、状態変化、および関連するテストを近似してください。
3. そのような検出結果にはすべて、プラン内で ソース由来 とラベル付けしてください。決して グラフ由来として提示せず、ステートメントレベルのエッジを決して捏造しないでください。
4. 信頼性を実質的に高める場合には、解決済みのランナー — node .gitnexus/run.cjs、インストール済みの gitnexus、または npx gitnexus — を介して analyze --index-only（PDG レイヤーには --pdg を追加）を 推奨してください。

スキルに関するフィードバック

この実行で指示に摩擦が生じた場合は、最終レスポンスに簡潔なフィードバックを含めてください。フィードバックはチャットのみです。評価の学びを追記したり、 ベンチマークデータを編集したり、ライブのプランニングタスク中にこのスキルを変更したりしないでください。