dsh-pre-push-checks

DSH プッシュ前チェック

deepseek-harness のプッシュ前に、関連するローカルのエビデンスを一度実行するには、このスキルを使用します。唯一の順序に関する例外は gh stack sync です。これは、書き換えられたレイヤーを検証する前に連鎖的なリベースを公開する場合があります。その場合は直後に検証し、エビデンスに合格するまでマージしないでください。Git フックは意図的に対象を絞っています。pre-commit はステージ済みの lint を修正し、ステージ済みの空白をチェックして、ベンダーソースのメタデータを保護します。pre-push は差分に対するリポジトリの型チェックのみを実行します。網羅的なカバレッジとプラットフォームマトリックスは CI が担当します。

変更内容を確認する

1. チェックアウトとブランチを確認します。

git status --short --branch
git rev-parse --show-toplevel

2. 現在の PR のベースまたはスタックの親を確認し、その参照をフェッチして、そこからの変更範囲全体を調べます。

pnpm --silent run change-scope --base <verified-base-ref>

このコマンドは、ベースを推測したりフェッチしたりしません。現在のリモートまたはスタックの状態から確認した参照を指定してください。HEAD 以外のコミットを調べる場合は、--head <ref> を使用します。バージョン管理された JSON には、解決されたマージベースを基準とするコミット済みのパスが記録されます。一方、ステージ済み、未ステージ、未追跡のパスには現在のワークツリーの状態が反映されます。変更されたベースをマージした後は、レポートを再実行し、結合後の変更範囲が影響し得る挙動を再評価して、マージによって無効になったチェックのみを再実行します。

関連する証拠を選択する

フック以外に、普遍的なローカル基準はありません。動作を変更する場合は、その回帰時に失敗する、利用可能な範囲で最も限定的なテストまたは専用のチェックが必要です。より広範なチェックは、差分が実際に影響する範囲に限って追加してください。

リソースを所有するテスト、フィクスチャ、ヘルパー、または CI 実行パスを新たに追加または変更する場合は、まず dsh-ci-test-reliability を使って、復元、ネガティブコントロール、静止状態でのティアダウン、または並行プロセスの証拠が該当するか判断してください。このスキルでは引き続きコマンドを選択し、すでに合格した証拠を重複して取得しないようにします。

• パッケージまたはスクリプトの動作： 所有する Vitest ファイル、または対象を絞ったテスト名を実行します。共有コントラクトを変更する場合は隣接するパッケージのテストも追加します。変更が実際に複数の領域にまたがる場合、またはユーザーから依頼があった場合を除き、リポジトリ全体のカバレッジは CI に任せてください。
• Remote のモック型： ビルドされていない any は明示的なローカルフォールバックであり、厳密な証拠ではありません。Remote／モックの変更を引き渡す前に pnpm run typecheck を実行します。残りのエラーを調査する前に、不足している、古くなっている、または不完全な生成済み宣言を再ビルドします。この例外は test proxy 内にとどめ、本番の Remote 型、アンビエントフラグ、またはコピーしたシグネチャには持ち込まないでください。
• ドキュメント、Agent Notes、カタログ、またはドキュメントにリンクされたコメント： pnpm run doc-sync を実行します。ドキュメントのワークフローで必要な場合は、完全な lint も実行します。
• モデル、エディター、CLI、またはターミナルに表示される出力： その出力を所有する、対象を絞ったキーなしスナップショット、または実行可能なサンプルの実シナリオを実行します。
• 期待出力の配置： 選択された記録済み Session の生成データを再生入力として使い、永続化された出力を期待値とするテストは、トップレベルの snapshots/ に配置します。snapshot.yml には、同梱される dsh プロファイルと構成／ヘッダーのピン留めを記載します。正規の親ファイルは session[.vN].jsonl、子ファイルは session.<ordinal>[.vN].jsonl であり、ハーネスはロールごとに最も新しい世代を選択します。この Session の往復処理を伴わない ARIA、ジオメトリ、ジェネレーター、CLI、単体テストの期待値は、それを所有するテストの隣にある tests/expected/ に配置します。snapshots/ に置いたり、*.snapshot.ts の所有ファイルを割り当てたりしないでください。所有する test:expected、test:web、または test レーンを使用します。
• プロファイルと設定の配置： 同梱される dsh プロファイルのパッケージ横断の動作は apps/cli/tests/profiles/ に配置します。パッケージ固有の Loader 構成は、そのパッケージの tests/fixtures/ に配置します。ユーザー向けの任意のオーバーレイは apps/cli/config/examples/ に置き、docs/user/ のガイドと対にします。
• パッケージマニフェスト、公開エクスポート、ビルド設定、worker／bin エントリー、またはビルド後のランタイムパス： pnpm run build、関連するハイジーンチェック、および所有するビルド成果物のスモークテストを実行します。
• リポジトリのテストおよびスクリプトの型： pnpm run build:artifacts がチェックするのはパッケージプロジェクトのみです。TypeScript の変更が完了したと判断する前に、最新の build:artifacts の後で pnpm run build:check を実行するか、pnpm run build を実行します。build:check は既存の build:artifacts 出力を読み込み、再ビルドは行いません。
• 実際のプロバイダーまたはエージェントの動作： 認証情報を利用できる場合は、該当する pnpm run test:e2e ターゲットを実行します。シークレットを出力してはいけません。

コミットやプッシュが続くというだけで、合格済みのチェックを手動で再実行しないでください。特に、プッシュ直前にプリプッシュフックと重複するだけの理由で typecheck を実行してはいけません。

Vitest のファイルおよび名前のフィルターは、スクリプト名の直後に pnpm run で渡してください。独立した -- を挿入しないでください。Vitest に渡され、-t フィルターが無効になる場合があります。たとえば、次のコマンドはヘッドレスのスナップショットシナリオを1つ実行します。

pnpm run test:snapshot snapshots/session/headless.snapshot.ts -t 'cordis-inspect-jsdoc'

これは以下の pnpm スクリプトに適用されます。npm やその他の起動方法では、それぞれ独自の引数転送構文が使われます。フィルターを指定した実行を対象を絞った証拠として扱う前に、報告された選択テスト数を確認してください。

影響を受けたソースにユニットテストのカバレッジを絞る

テストの選択とカバレッジの選択は別々です。Vitest のファイルフィルターは実行するテストを選びますが、リポジトリの設定ではそれ以外の場合、すべての packages/*/*/src/**/*.ts ファイルが測定対象になります。ユニットテストのカバレッジが関係する場合は、対象となるテストと、そのテストでカバレッジを検証するソースファイルまたはパッケージの両方を指定してください。

pnpm exec vitest run packages/<group>/<package>/tests/<behavior>.spec.ts \
  --coverage \
  --coverage.include='packages/<group>/<package>/src/**/*.ts'

動作が本当に 1 つのモジュールに限定される場合は、ソースファイルを正確に指定してください。影響を受けるファイルまたはパッケージが複数ある場合は --coverage.include を繰り返し指定し、その範囲をテストするために必要な対象テストファイルをすべて渡してください。設定済みのファイル単位の 100% 閾値は、選択したソース範囲内でも適用されます。

対象となるテストが明確でない場合は、Vitest の依存関係グラフを使って候補を見つけ、その実行を証拠として扱う前に、選択されたテストを確認してください。

pnpm exec vitest related packages/<group>/<package>/src/<changed>.ts \
  --run \
  --coverage \
  --coverage.include='packages/<group>/<package>/src/<changed>.ts'

vitest related では、設定、動的読み込み、サブプロセス、ワーカー、ビルド済み成果物、外部プロバイダー経由でのみ実行される動作を検出できません。そのような対象テストは明示的に選択してください。カバレッジ未達の影響対象ファイルを隠すために、--passWithNoTests の使用、カバレッジ閾値の引き下げ、--coverage.include の対象範囲の縮小をしてはいけません。選択したパッケージ範囲で、焦点を絞った 1 つのテストではカバレッジが不足する場合は、関連する対象テストを追加するか、除外するモジュールが変更の影響を受けない場合に限り、ソース範囲を絞ってください。

ローカルでの完全なリハーサル

完全なローカル再現を行うのは、ユーザーから明示的に求められた場合、CI の失敗を調査している場合、または変更がリポジトリ全体に広く及び、より狭い範囲では妥当な検証にならない場合に限ります。現行のワークフローとパッケージスクリプトを一覧として使用し、削除済みの check:pre-push 集約処理を再現してはいけません。

履歴を書き換えるプッシュを保護する

単独の PR ブランチとスタックされた PR ブランチのどちらでも、レビュー後を含め、リベースは許可されています。単独ブランチの履歴を書き換える前に、最新のリモートブランチをフェッチし、その正確な OID を記録してください。--force-with-lease=<branch>:<observed-oid> を指定して公開し、同時更新があればプッシュを中断させてください。gh stack push と gh stack sync は、それらが管理するブランチに対してリース保護を提供します。--force のみを使うことは決して許可されません。

履歴を書き換えてプッシュした後は、ライブのヘッドを再度フェッチし、未解決のレビューコメントスレッド、承認、マージ可能性、チェックを再監査してください。書き換え前のコミットハッシュとインラインコメントのアンカーは、現在の状態を示す証拠ではありません。

同期後の検証

gh stack sync はフェッチ、連鎖的なリベース、プッシュを 1 回の操作として行うため、書き換えと公開の間にローカル検証を挟めません。実行前に、ワークツリーがクリーンであることを確認し、公式のスタック順序と正確なリモートヘッドを記録してください。実行後は次のことを行ってください。

1. すべてのブランチヘッドと、公式な GitHub スタック順序を再確認します。
2. 書き換えられた各レイヤーの変更範囲を、ライブの PR ベースと照合して確認します。
3. 影響を受ける各レイヤーについて、このスキルで選択した関連エビデンスを実行します。
4. 選択したすべてのチェックに合格するまで、すべての PR を未マージのままにし、検証は保留中と報告します。

同期後のエビデンスが失敗した場合は、リース保護付きで公開済みのヘッドをそのままにして、問題を修正し、その修正を検証してから訂正内容を公開してください。コマンドが成功したというだけで、同期によってスタックの準備が整ったと主張してはいけません。

失敗への対処

通常のプッシュ前に関連チェックが失敗した場合は、停止して問題を修正するか、障害要因を説明してください。CI では違う結果になると期待してプッシュしてはいけません。同期後の例外については、マージをブロックし、上記の修復手順に従ってください。

失敗が環境固有のものと思われる場合は、そのことを検証してください。

• 正確なコマンド、失敗したテスト、プラットフォーム固有の不一致を記録します。
• 関連する非プラットフォームのエビデンスを確認します。
• 必須チェックの場合は、クロスプラットフォームの非決定性を解消する修正を優先します。
• ローカルフックを回避できるのは、ユーザーが明示的に依頼または同意した場合に限ります。その場合は、何が失敗したのか、CI で異なる結果が予想される理由を正確に報告してください。

プッシュ手順

通常のプッシュと、単独で行うリベース後のプッシュでは、次の手順を実行します。

1. 選択した関連チェックを一度実行します。
2. 通常どおりコミットし、先に進む前に、pre-commit の修正ツールによって変更されたファイルを確認します。
3. 通常どおりプッシュするか、書き換えが許可されたブランチの場合は正確なリースを使用してプッシュし、増分型の型チェックフックが実行されるようにします。
4. リモートの参照がローカルの HEAD と一致することを確認します。

git rev-parse HEAD origin/$(git branch --show-current)

GitHub の PR では、プッシュ後にリモートの CI を確認します。

gh pr checks

保留中のチェックは保留中として報告します。失敗をブランチまたは環境に起因すると判断する前に、失敗の内容を確認します。

gh pr checks が「no checks reported」と報告し、/actions/runs?head_sha=<sha> が total_count: 0 を返す場合、プッシュの問題や GitHub イベントの欠落を疑う前に、マージ可能性を確認します。

gh pr view <number> --json mergeable,mergeStateStatus

PR が CONFLICTING／DIRTY の間、GitHub は pull_request ワークフローの実行を作成しないため、シグナルがない原因は競合であり、インフラストラクチャではありません。唯一の解決策は競合の解消です。空のコミット、--allow-empty を使ったプッシュ、ドラフト／準備完了の切り替え、リバートと再適用の繰り返しでは、いずれも total_count はゼロのままで、不要な履歴が追加されます。ブランチをまだローカルでマージできない場合は、git merge-tree --write-tree HEAD origin/<base> で競合しているパスを確認します。

gh stack sync では、通常の順序が実行可能だったかのように扱わず、同期後の検証手順を使用します。