コントリビューション

Slipway は、生成された AI ツールサーフェスと統制されたアーティファクトワークフローを備えた Go の CLI です。変更は、対象とするモジュールやコントラクトの範囲に限定してください。

リポジトリ構成

パス	用途
`cmd/`	Cobra のコマンドサーフェスと、CLI の JSON/テキスト表示。
`internal/model/`	永続的なドメイン型、ワークフローの状態、設定スキーマ。
`internal/state/`	ファイルシステムのレイアウト、ワークスペース設定、変更の永続化、アーカイブヘルパー。
`internal/engine/`	進行、ゲート、ガバナンス、アーティファクト、コンテキスト、ウェーブのロジック。
`internal/toolgen/`	AI ツールアダプタの生成と、凍結されたサーフェスコントラクト。
`internal/tmpl/templates/`	埋め込みのコマンド、スキル、フック、アーティファクトのテンプレート。
`docs/`	ドキュメントのソースページ（信頼できる情報源）。
`website/`	`docs/` をレンダリングして GitHub Pages 向けに配信する Astro Starlight サイト。
`artifacts/changes/`	Slipway が作成する統制された変更バンドル。

開発コマンド

go run . --help
go test ./... -count=1
go build ./...
go vet ./...
go run ./internal/testlint/cmd/testlint ./...

最終的な確認には、CI と同じタイムアウトを使います。

go test -timeout=20m ./... -count=1

テスト品質ポリシー

テストは、実装の些末な点やマシン依存のタイミングではなく、振る舞いを証明するものであるべきです。CI を黙らせるために質の悪いテストをスキップしてはいけません。そうしたテストは削除し、同じ PR の中で決定的な振る舞いをカバーするテストに置き換えてください。

空虚なテスト: コードを実行するだけのテスト、ハードコードされた定数を確認するだけのテスト、ユーザーから見える振る舞いを制約せずにモックが呼び出されたことだけをアサートするテストは削除します。
ソース grep テスト: .go ファイルを読み込んでソーステキストに対する strings.Contains をアサートするテストは削除します。エクスポートされた振る舞い、パーサーの結果、状態遷移、あるいはそのソースが守るはずだったレンダリング出力を実際に動かすテストに置き換えてください。
経過時間テスト: time.Since、所要時間のしきい値、スリープ、スケジューラのタイミングを使って実時間の経過をアサートするテストは削除します。決定的な同期、フェイククロック、制御されたコンテキスト、明示的なイベントに置き換えてください。
実レーステスト: ゴルーチンが特定の順序でインターリーブされることを期待してレースを証明しようとするテストは削除します。同期バリア、レース検出器によるカバレッジ、あるいは状態マシンへの直接的なアサーションに置き換えてください。

テキストが製品の振る舞いそのものである場合、テキストへのアサーションは依然として有効です。生成されたサーフェス、ゴールデン出力のフィクスチャ、CLI/API のコントラクトテストは、厳密なテキストや必須の部分文字列をアサートして構いません。そうしたフィクスチャはテスト対象の振る舞いの近くに置き、テキストが実装の grep ではなくコントラクトであることをレビュアーが分かるようにテスト名を付けてください。

internal/testlint アナライザーは、ローカルで最もシグナルの高いポリシーチェックをカバーします。すなわち、.go ファイルを読み込んで strings.Contains をアサートするソース grep テストと、time.Since または計測した所要時間の比較に基づく経過時間アサーションです。次のように直接実行できます。

go run ./internal/testlint/cmd/testlint ./...

ドキュメント

ドキュメントは docs/（信頼できる情報源）にあり、website/ の Astro Starlight サイトでレンダリングされます。website/scripts/sync-docs.mjs がビルド時に docs/** を Starlight のコンテンツコレクションへ変換するため、website/src/content/docs/ を手で編集してはいけません。ページを追加または移動したら、website/astro.config.mjs のサイドバーを更新してください。

ローカルでのビルドやプレビュー:

cd website
npm install
npm run build   # runs sync-docs, then `astro build`
npm run dev     # local preview with content synced from docs/

ドキュメントのワークフローは同じ npm run build を実行し、GitHub Pages へデプロイします。

アダプタコントラクト

コマンドのメタデータ、生成されるパス、フック、プロンプトサーフェスが変わるときは、コードとテストをまとめて更新してください。

go test ./internal/toolgen -count=1

生成されたサーフェスはコントラクトテストの対象です。対象には、サポートされるツール ID、コマンドパス、Codex のコマンドスキルとレガシープロンプトのクリーンアップ、OpenCode のフラットコマンド、バイト単位の安定性が含まれます。

ガバナンスコントラクト

ライフサイクル、アーティファクト、ゲートのセマンティクスが変わるときは:

所有するパッケージに、対象を絞った回帰テストを追加します。
Markdown や状態のパースを重複させず、共有セマンティクスはヘルパーにまとめます。
ホストコントラクトが変わったら、生成されるスキルやドキュメントを更新します。
アクティブな統制対象ワークトリー内で go run . validate を実行して検証します。

ガバナンス対象のカバレッジゲート

ガバナンスカーネル、すなわち internal/engine/gate、internal/engine/governance、internal/engine/progression（レディネスリゾルバは progression/readiness.go にあります）は、回帰を許さないカバレッジゲートで保護されています。高リスクな公開ライフサイクル面は、cmd と internal/state を対象にした 2 つ目の階層ゲートで保護します。これには status、next、validate、done、evidence、verification、worktree、runtime state の経路が含まれます。いずれかの対象パッケージのステートメントカバレッジがコミット済みのフロアを下回ると、CI は失敗します。これらのゲートはフェイルクローズで、フロアを自動的に下げることはなく、スキップ・強制・ソフトパスの経路もありません。

ベースライン: coverage-baseline.json はカーネルのフロアを記録し、coverage-public-surface-baseline.json は公開面のフロアと診断に使う package/file/surface メタデータを記録します。どちらも covergate ツールで生成し、手で編集することはありません。
CI ジョブ: Kernel Coverage Gate ジョブは、カーネルと公開面のパッケージを合わせた -coverpkg でスイート全体を 1 回実行し、続いて covergate -target kernel -check と covergate -target public-surface -check を実行します。ベースラインを決定的にするため、カバレッジは単一の OS（ubuntu）で計測します。
ユニオンセマンティクス: 複数パッケージにまたがる実行で -coverpkg を使うと、同じブロックがテストバイナリごとに 1 回ずつ出力されます。covergate はそれらをユニオンします（ブロックは 1 回だけカウントし、いずれかの出現で実行されていればカバー済みとみなす）。これは go tool cover と同じ挙動です。
モードの選択: covergate は明示的な -check または -write を必要とし、モードなしの呼び出しは拒否されます。-target で kernel または public-surface を選びます。-check は常にコミット済みのベースラインをそのまま使い、-exclude のような書き込み時専用のフラグはチェックモードでは拒否されます。
公開面の診断: 公開面の失敗は package と関連する surface/file メタデータを表示します。全体パーセンテージではなく、追加すべき対象テストが分かるようにするためです。

ゲートをローカルで実行する:

just coverage-gate

CI が回帰を報告した場合、通常の対処はカバレッジを回復させるテストを追加することです。低下が意図的でレビュー済みの場合（たとえばデッドコードを削除したとき)は、ベースラインをラチェットして差分をコミットし、変更がレビューで見えるようにしてください。

just coverage-baseline   # regenerates governed coverage baselines from current coverage

ベースラインを下げる編集が自動で行われることはありません。プルリクエストの差分に現れ、レビューを受ける必要があります。カバレッジを改善した後にフロアを引き上げるときも、同じコマンドを実行してください。

除外リスト: covergate に -exclude <prefix[,prefix...]> を渡せるのは、ゲート対象セットを選ぶ -write 時のみです。これは、生成物・テスト専用のプレフィックスのために用意されていますが、必須のカーネルまたは公開面パッケージのフロアを取り除くことはできません。

CI ジョブがデフォルトブランチでグリーンになったら、メンテナーは Kernel Coverage Gate をブランチ保護の必須ステータスチェックに残し、カーネルまたは公開面の回帰がレッドになってマージをブロックするようにしてください。