serhii-nochevnyi/shipyard

デリバリーコンベアルール

このプロジェクトは、GSD（docs/gsd_multilevel_delivery_pipeline.md を参照）上にチケットごとのデリバリーコンベアを実行します。計画はチケットを兼ねます。これらのルールは、コンベアの決定論的レイヤーによって機械が消費可能な状態を保ちます。

言語. すべての成果物（計画、フロントマター、コミット、コード、PR 本文）は英語で記述されます。ユーザーに直接話しかける場合はユーザーの言語で応答してください。英語は成果物用、ユーザーの言語は会話用です。

計画担当者向け（PLAN.md の作成）

1. 常に完全なフロントマター: phase、plan、title、type、wave、depends_on: []、files_modified: []、requirements: []。空の requirements はブロッカーです — GSD の計画チェッカーと Gate 2（validate-graph）の両方がそれを拒否します。ROADMAP の要件 ID、または計画がインポートされた際の外部トラッカー ID を参照してください。wave は人間の読者のためのドキュメントです。グラフが信頼できる情報源であり、バリデーターが実際の依存関係の深さを再計算し、あなたの値が一致しない場合に警告します。装飾的ではなく、真実を保つようにしてください。

2. デリバリーブロック（追加的であり、GSD フィールドを決して置き換えません）:

   delivery:
     ticket: T-<phase>-<plan>
     risk: low|medium|high        # high の場合は human_checkpoint: true が必須
     human_checkpoint: false
     repo: owner/name             # 作業が別のリポジトリにある場合のみ
   

   repo は、このリポジトリに触れないすべてのチケットで必須です。 これを省略すると、コンベアはチケットを間違ったリポジトリに対して追跡します。その PR が隣でグリーンになってマージされても、ボードは pending のままになり、すべての依存チケットは決して進まないチケットの後ろでブロックされたままになります。files_modified 内のパスは、そのリポジトリを基準とした相対パスになります — 決して ../other-repo/x.ts のようなパスを使用しないでください。どのワークツリーも到達できません（Gate 2 が警告し、state-sync がチケットを保留します）。クロスリポジトリの依存関係はカスケードされません。親が最初に MERGE する必要があるため、完全な機能を待たせるのではなく、契約側（型やツール名）を独自のチケットに分割してください。

3. ブランチ名を発明しないでください。 標準的なブランチは ticket/<ID>-<slug> です。ここで slug はサニタイズされたチケットタイトル（小文字、翻字、非英数字は単一のハイフンにまとめ、40 文字以内）です。delivery.branch は省略してください — グラフバリデーターが生成します。明示的な値は同じルールに対して検証されます。

4. files_modified は推測ではなく契約です — 計画が触れるすべてのパスをリストしてください。空の files_modified は Gate 2 に失敗します（これは「依存関係の順序付けされていないチケットが決して衝突しない」ことをチェック可能にし、実行者のスコープでもあります）。依存関係の順序付けられていない計画が重複するパスを持つ場合も Gate 2 に失敗します。依存関係または再分割で解決してください。グロブを広げることでは解決しないでください（すべてに一致する裸のグロブはフラグが立てられます）。

5. 新しいものを書く前に、すでにこれを行うものを特定してください。 すべての計画の Context Reads は、チケットが拡張する既存の実装を指すか（path:line — それが基づくトランスフォーマー、ソーター、ミドルウェア、ヘルパー、エンドポイント）、または存在しないというチェックを記録する必要があります。つまり、どの動作を検索したか、そして見つけた2〜3の可能性のある場所を記録します。新しいコードに付けようとしている名前ではなく、動作で検索してください。重複はほとんどの場合、別の名前で呼ばれており、それがまさにレビューを生き残る理由です。「見当たらなかった」は「調べた」と同じ意味ではありません。後者のみが読者が信頼できる計画です。これはコンベアの中で最も安価なゲートです。気付かれない重複は、後で他のチケットがその上に構築した後に、統合者によってフェーズ全体遅れて発見され、その時点でそれを削除するには独自のチケットが必要になります。§4 とは異なり、これはフロントマターから機械的にチェックできません — Gate 2 はそれを決して見ず、ドリフトチェックは再評価するチケットに対してのみバックストップするため、それを書き留めることが制御となります。

6. 検証コマンドはチケットにスコープされ、プロジェクトにはスコープされません。 実際に files_modified をカバーする最も狭いコマンド（特定のテストファイルやフィルター、影響を受けるパスに対する型チェックとリント）を書いてください。裸の npm test / make test / e2e スイート全体は、ここでは検証コマンドではありません。これらは CI に属し、CI はプッシュごとにそれに特化したハードウェアで一度実行します。実行者はすべての試行でこれらを実行し、修正ロールはすべてのラウンドでそれらを再実行するため、スコープされていないコマンドは一度遅いだけではありません。それはコンベア全体のティックレートであり、各チケットが独自のワークツリーで並行して実行される分だけ乗算されます。コマンドを使い可能にする2つの特性があります。外部サービスなしでベアワークツリーで実行できること、そしてこのチケットのミスに対して失敗することです。スコープできないコマンド（ライブデータベース、ブラウザ、デプロイ済み環境が必要なスイート）は CI 専用のチェックです。テスト戦略の下でそう述べ、実行委員会に実行できないものを渡すのではなく、検証コマンドから除外してください。

7. depends_on はカスケードを駆動し、単なる順序付けではありません。 Epic スタックデリバリー（デフォルト）では、ルートチケット（空の depends_on）はフェーズ Epic ブランチに PR を作成します。依存チケットはカスケードされます — マージを待たずにプライマリペアレントのブランチに PR を作成するため、フローがブロックされることはありません。依存関係を正確に宣言してください。偽の依存関係はフローをシリアル化し、欠落しているものは実行者に不完全なベースを渡します。バリデーターは Epic（epic/<phase-dir>）、プライマリペアレント、および pr_base を導出します。同じフェーズ内の複数のペアレント（ダイヤモンド）は警告を受け取ります。実用的な場合は線形化してください。依存関係は1つのフェーズ内に保ってください。 フェーズ間の依存関係はカスケードできません — スタックする共有ブランチがないため、依存チケットはペアレントのフェーズ全体がデフォルトブランチにランディングするまでブロックされたままになります。バリデーターはそれらのすべてについて警告します。代わりに再分割してください。

8. IDは標準的です: T-<2桁のフェーズ>-<2桁の計画>。T-01-02 と書き、決して T-1-2 と書かないでください。バリデーターは両方を正規化しますが、ブランチ、PR タイトル、Jira ラベルは他のすべての場所で文字列比較されます。

9. 値に末尾の # コメントを付けないでください。 コメントは独自の行に配置してください。files_modified: [a.ts] # note は以前はコメントを最後のパスに折りたたんでいました。パーサーは現在それを正しく削除しますが、Gate 2 は # を含む値をほぼ常にリークであるため拒否します。

10. Gate 2 は機械的です: グラフバリデーターが終了コード 0 で終了した場合のみ合格します。Jira/GitHub の問題、ROLLOUT.md、または散文の要約は、具体化された PLAN ファイルの代わりにはなりません。

11. Jira は投影であり、信頼できる情報源ではありません。 デフォルトでは（pipeline.jira.enabled: false または Jira MCP が接続されていない場合を除く）、decompose は検証済みグラフを Jira（フェーズごとに 1 つの Epic、チケットごとに 1 つの課題）に英語でエクスポートします。これは Gate 2 の後であり、決してそれより前、または代わりではありません。プロジェクトは自動解決されキャッシュされます。Jira の障害は分解をブロックしてはなりません。PLAN ファイルは標準のままです。

実行者向け（チケットの実装）

1. files_modified 内に留まってください。 範囲外の変更は別のチケットに属します — 静かに範囲を拡大するのではなく、エスカレーションしてください。
2. 新しいものを書く前に、既存の実装を読んでください。 計画が §5 で命名したもの、およびドリフトチェックからコンベアが提供した reuse_candidates があれば、それぞれを最初に読み、それらを拡張してください。それらに並行して新しいレイヤーを追加しないでください。候補が本当に適合しない場合は、その理由を証拠に示してください。それは正当な結果であり、静かに無視することはそうではありません。再利用は決して files_modified を残すことを許可しません。それに基づいて構築すると範囲外になる場合、それは範囲外のエスカレーション（§1）であり、より広い差分ではありません。
3. アトミックコミット にはチケット ID をプレフィックスとして付けます: feat(T-01-02): …
4. 計画の検証コマンドをローカルでグリーンになるまで実行 してから完了を宣言してください。コマンド出力なしで検証を主張しないでください。それらのコマンドを実行してください — スイート全体に拡大して「徹底」しないでください（§6）。CI が完全な実行を所有し、ここで開始したスイートは自分のワークツリーとマシンを共有する他のすべての実行者をブロックします。計画のコマンドが壊れているか、明らかに変更をカバーしていない場合は、計画内で修正または狭め、その理由を証拠に示してください。npm test を黙って代用することは修正ではありません。
5. ワークツリーとブランチはコンベア（tickets.json）から提供されます — アドホックにブランチやワークツリーを作成しないでください。PR ベースもコンベア（delivery-state.json → base：ルートチケットの場合は Epic ブランチ、依存チケットの場合はペアレントブランチ）によって解決されます — Epic スタック下で main/master に直接 PR を開かないでください。
6. コミットで停止してください。 push せず、プルリクエストを開かず、レビュアーに触れないでください。オーケストレーターは、何かを公開する前にワークツリーを機械的に検証します（git log <base>..HEAD）。このチェックは「エージェントが成功を報告したが何も変更しなかった」ことをキャッチするものであり、公開がチェック対象のエージェントの手にない場合にのみ機能します。代わりに、検証証拠と PR 本文を返却してください。