preflight

preflight

変更ゲート付き、ブランチスコープの lint preflight です。origin/<base>...HEAD に関連するカテゴリのみを、変更されたパスだけを対象に lint します。リポジトリ全体に対する pnpm lint は実行しません。その後、各違反を 導入された違反（このブランチが追加または変更した行にある）か、既存の違反（ブランチがたまたま変更したファイルに以前からある）に分類します。

このスキルは、preflight のループにおける唯一の情報源です。次の 2 通りで呼び出されます。

• 単独実行（/preflight）—「自分のブランチはスコープ対象の lint に通るか」をすばやく確認します。修正があれば作業ツリーに残します。
• ship フロー内（例：/send-it）—コミット後、changelog／push の手順前に実行する lint ゲートです。

同梱スクリプトは Node の組み込み機能のみを使用するため、npm install もビルド手順も不要です。利用側リポジトリのルートを対象に動作します（ブランチ差分を git で解決できるよう、リポジトリのルートから実行してください）。

実行方法

1. ベースブランチが最新であることを確認します。git fetch origin <base>（ベースブランチは自動検出されます。Configuration を参照してください）。
2. preflight を実行します。node skills/preflight/scripts/preflight.mjs（違反を分類せず、カテゴリとスコープ対象のファイル一覧を表示するには、末尾に --dry-run を付けます）。--dry-run は実際のプレビューとして動作します。すべての linter が would-run を報告し、.preflight-summary.json を含め、何も書き込まれません。ほかの処理を行う前に、スクリプトは実行中の Node のメジャーバージョンがリポジトリで指定されたバージョンと一致するか確認します。正確な engines.node の指定（24.x、24.18.0）があればそれを使用し、なければ .nvmrc のメジャーバージョンを使用します。一致しない場合は、切り替え方法のヒント（nvm use／fnm use／mise use）を示して終了コード 1 で終了するため、ESLint が誤った Node で実行されることはありません。>=／^／~ を含む engines の範囲指定は固定指定ではありません。どちらも指定されていないリポジトリは確認対象外です。
3. .preflight-summary.json で、実行されたカテゴリと違反数（passed、deferred、blocking）を確認します。実際に実行した場合のみ書き込まれ、--dry-run では書き込まれません。一時的な作業ファイルであり、コミットしてはいけません。利用側リポジトリでは gitignore に追加します（rheged-skills-setup スキルがリポジトリの調整時にこの項目を追加します）。

スクリプトの終了コードに従って処理を進めます。

• 終了コード 0 — 合格。 導入された違反はなく、すべての linter が問題なく実行されました。続行してください。
• 終了コード 1 — 導入された違反（ブロッキング）。 node skills/preflight/scripts/lint-fix.mjs をブランチスコープのパスに対して実行し、その後 preflight を再実行します。導入された違反がなくなるか、ユーザーが中止するまで繰り返します。（ship フロー内では修正をコミットします。単独実行では、ユーザーが確認してコミットできるよう、作業ツリーに残します。）デフォルトでブロックされるのは、導入された エラー のみです。導入された ESLint の 警告 はブロッキングではない通知として報告され、ゲートを失敗させません。これは警告時に終了コード 0 となる pnpm lint／CI と同じ動作です。警告もゲート対象にするには blockOnWarnings: true を設定します（Configuration を参照してください）。
• 終了コード 2 — 既存の違反のみ。 一覧を示し、ユーザーにどちらかを選んでもらいます。
  • 今すぐ修正 — 修正を適用し、（ship フローの場合はコミットして）preflight を再実行します。
  • 保留 — Linear で負債チケットを作成します（以下の Debt-issue create を参照）。作成後（または作成を断られた後）、続行するか中止するかを判断します。

終了コード 1 は、linter の実行失敗（違反を解析できないままゼロ以外の終了コードで終了）を示す場合もあります。その場合は標準エラー出力を確認してください。これもブロッキングです。また、Node のメジャーバージョンが一致しない場合（手順 2 を参照）も終了コード 1 になります。Node を切り替えて再実行し、lint の失敗として扱わないでください。

カテゴリー

各カテゴリーはブランチで変更された内容に応じて実行されます（CI のパス条件に対応し、対象範囲はより限定的です）。

カテゴリー	実行条件	スキップ条件
ESLint	ブランチの差分に lint 対象のコード、または eslint/tsconfig の設定パスが含まれる	Markdown のみ、または lint 対象外の変更
markdownlint	ブランチの差分に .md / .mdx が含まれる（リポジトリの ignore 設定を適用）	Markdown の変更がない場合。markdownlint-cli2 バイナリがない場合は警告を出してスキップします
actionlint	ブランチの差分に .github/workflows/*.yml または .github/actionlint.yaml が含まれる	ワークフローの変更がない場合。設定のみの変更では追跡対象のすべてのワークフローを lint します。actionlint バイナリがない場合は警告を出してスキップします

ESLint は各ワークスペースごとに実行され（pnpm --filter を使用）、ルート／scripts 用のバケットも実行されます。 型チェック、テスト、フレームワークのチェック（例：astro check）は preflight の対象ではありません。これらは CI で実行します。

単独実行と ship フロー内での実行

• 単独実行（/preflight）では lint の事前チェックと終了コードのループを実行し、その後に結果を報告します。新たに発生した違反がある場合は node skills/preflight/scripts/lint-fix.mjs を実行して再チェックすることがありますが、修正は作業ツリー内に残ります。コミット、変更履歴の作成、プッシュ、PR の作成は行いません。
• /send-it 内では、同じループを lint ゲートとして実行します（コミット後、変更履歴の作業前）。修正はコミットされ、変更履歴を書く前にブランチがクリーンな状態になります。変更履歴とその検証はship フローが管理する別個のゲートであり、このスキルには含まれません。

設定

リポジトリ固有の入力値は 2 つとも自動検出されるため、通常、利用側のリポジトリで編集する必要はありません。

• lint 対象のワークスペースは pnpm-workspace.yaml と各パッケージの package.json から特定されます。lint スクリプトを宣言しているワークスペースのみが含まれます。手動でリストを管理しなくても、意図的に lint 対象外としたワークスペースや、パッケージではないディレクトリは自動的に除外されます。
• ベースブランチは origin/HEAD（例：main、master、develop）から検出されます。このシンボリック参照が存在しない場合は main にフォールバックします。

どちらかを上書きするには、利用側のリポジトリのルートに preflight.config.json を追加します（テンプレートとして、このファイルと同じ場所に config.example.json が用意されています）。

{
  "baseBranch": "main",
  "blockOnWarnings": false,
  "workspaces": {
    "web": { "filter": "@acme/web", "prefix": "apps/web/" }
  },
  "linearTeamName": "",
  "debtProject": ""
}

どのキーも単独で指定できます。それ以外のキーは引き続き自動検出またはデフォルト値が適用されます。 pnpm を使用しないリポジトリ、意図的な除外、または検出機能が展開しないネストされたワークスペースの glob には、上書き設定を使用してください。

• blockOnWarnings（デフォルトは false）— 新たに発生した ESLint の警告レベルの検出結果でゲートをブロックするかどうかを指定します。デフォルトでは無効です。preflight は、新たに発生したエラー（および実行に失敗したリンター）のみでブロックします。新たに発生した警告はブロックせずに報告され、pnpm lint／CI と同じ動作になります。ブランチで追加された警告レベルの検出結果もゲートの対象にしたいリポジトリでは、true に設定してください。markdownlint／actionlint の検出結果は常にブロックします。警告とエラーの区別があるのは ESLint のみです。
• linearTeamName／debtProject — Exit 2 の Defer パスで使用する、エージェント向けのキーです（lint スクリプトでは無視されます）。負債の課題を作成するには、両方に空でない値が必要です。Debt-issue create を参照してください。空の場合、負債の課題作成は無効になります（ユーザーに設定するか、今すぐ修正するよう伝えてください）。プロジェクトを指定せずに課題を作成してはいけません。

負債課題の作成

Exit 2 でユーザーが Defer を選択した場合、リポジトリのルートにある preflight.config.json で linearTeamName と debtProject の両方が設定されている場合にのみ、 Linear の負債課題を作成します（そのファイルを読み込みます。キーが空、または存在しない場合は、 負債課題の作成が無効になります）。安全側に倒します。

1. いずれかのキーが空の場合、または Linear MCP サーバーが利用できない場合は、save_issue を 呼び出さないでください。ユーザーに linearTeamName と debtProject を設定するよう伝えます（または Fix now を選択するよう伝えます）。MCP が利用できず、ユーザーが追跡せずに続行することを望む場合に限り、 何も通知せずにスキップします。
2. チームは名前（linearTeamName）で解決し、プロジェクトは list_projects を使って解決します （debtProject は名前、ID、またはスラッグとして扱います）。見つからない場合は、save_issue を 呼び出さず、解決できなかった値を明示してエラーにします。
3. 見つかった場合は、team、project（必ず指定）、既存の違反を網羅するタイトルと説明、 担当者としてメンテナー、およびブランチ／PR のコンテキストへのリンクを指定して save_issue を 呼び出します。project を省略しないでください。

実装

同梱スクリプトは、このファイルと同じ場所の scripts/ にあり、node で直接実行します。pnpm エイリアスも npm install も不要です。

• scripts/preflight.mjs — 変更をゲートするプリフライトと終了コードの契約。
• scripts/lint-fix.mjs — ブランチで変更されたパスを対象にした、スコープ付きの eslint --fix／markdownlint-cli2 --fix。
• scripts/classify-lint.mjs — 違反を解析し、今回導入されたものと既存のものに分類。
• scripts/lib/{scope,diff-lines,paths}.mjs — 共通ヘルパー（ワークスペース／ベースブランチの検出、差分行のマッピング、パスの正規化）。

外部の npm 依存関係はありません（Node の組み込み機能のみを使用します）。

引数

$ARGUMENTS