ratchet

Ratchet — プロジェクトのブートストラップまたはガードレールの強化

開始時にアナウンスします：「Ratchet スキルを使って、このプロジェクトにガードレールを設定します。」

前提条件

• ユーザーが /ratchet を実行したか、プロジェクトにガードレールを設定、追加、または更新するよう依頼しています。現在のディレクトリがそのプロジェクトです。
• 既存のプロジェクトでは、強制レベルを一度に一段階ずつ強化します。ゲートを緩めたり、人が行った作業を上書きしたりしてはいけません。

手順

ステップ 0：ガードレールのソースを特定する

チェックアウトは、.guardrails-source に SKILL.md と並んで指定されたディレクトリ（install.sh --copy）、またはそのディレクトリの 2 階層上にあるリポジトリです。いずれも templates/ と scripts/ を含みます。ソースを読む前に、git clone -q <checkout> <guardrails> を実行し、<guardrails> のクローン先を <tmp>/guardrails にします。<tmp> はプロジェクト外の一時ディレクトリです。コピーとテストスイートの実行にはクローンを使用し、Ratchet の作業完了後に削除します（references/rationale.md）。

ステップ 1：モードを判定する

グリーンフィールドとは、スキャフォールディング以外のコミットがなく、ソースファイルも既存の AGENTS.md／ドキュメントもない状態です。それ以外はすべてレトロフィットです。.guardrails/scripts/ があり、新しいものを求めているプロジェクトはアップグレードです。ギャップ分析は行わず、以下の専用手順に従います（references/rationale.md）。

git rev-list --count HEAD 2>/dev/null   # none or few → likely greenfield
ls src lib app AGENTS.md docs 2>/dev/null

リポジトリが明らかに単一のプログラムではない限り、次の質問を 1 つだけ行い、推奨する回答も示します：1 つのシステムが複数のパッケージに分かれているのか、それとも 1 つのリポジトリに複数のシステムがあるのか？ バージョン管理、リリース、リスクを一緒に扱うパッケージは 1 つのシステムです。単一ユニットのプロジェクトではマニフェストは不要で、それ以外はこのスキルを変更せずに適用します。個別にコンプライアンスを満たすシステムがある場合は、ファイルをコピーする前にユニットのヒアリング（ステップ 1b）を行います。

ステップ 1b：ユニットのヒアリング（複数ユニットのリポジトリのみ）

/ratchet では事実を宣言します。ルールは設定できません。質問は一度に 1 つずつ行い、推奨する回答も示して、各事実を表の指示先に記録します：

質問	記録先
ユニットは何ですか？（それぞれ相対ディレクトリで指定）	.guardrails/units.yaml の units:
コンプライアンス対象外のものと、その理由は何ですか？	マニフェストの not_a_unit:。理由は項目の横に # コメントとして記載
各ユニットの安全性クラスは何ですか？	該当ユニットの設定ファイルの safety_class: — ステップ 4 のヒアリングをユニットごとに繰り返す
各ユニットは何に依存していますか？	依存するユニットの設定ファイルの depends_on: — 各依存関係について依存関係の評価が必要です（grill-requirements、「依存関係の宣言」）
分離された依存関係はありますか？ある場合、どの制御のもとで分離されていますか？	依存するユニットの設定ファイルの segregated_from: に (RC-…)、(adr: <path>)、または (ADR-<token>) として引用を記載（ファイルはルートまたは依存するユニットの docs/adr/ に配置）。check-units.sh では引用がない場合、INCOMPLETE-SEGREGATION になります

クラスの下限が適用されるか、ユニットが他のユニットの内部を参照できるか、またはどのユニットがマージ時に実行されるかは、質問しないでください。

順番に、一度に 1 つずつ導入します。必須の最初のステップは、マニフェスト、ユニットごとの設定ファイル、免責事項です。depends_on: が空のユニットは、リポジトリを共有する独立したガードレールプロジェクトです。他のすべてを免責事項として記載したうえで、1 つのユニットを記載したマニフェストを作成するのは、有効な最初のステップです。依存関係のエッジ（depends_on:、エクスポート、期待値）は、実際に結合している場合に宣言します。

次に .guardrails/scripts/check-units.sh を実行します。その検出結果（特に UNCLAIMED-PATH）を、免責事項に関する質問の作業リストとして使用します。

ステップ 2（新規プロジェクト）：スキャフォールド

1. リポジトリではない場合は git init を実行します（デフォルトのブランチ名は何でもかまいません）。まだコミットがなければ、初回コミットを作成します（ワークツリーにはベースが必要です）。

2. スキャフォールド用のワークツリー（worktree-discipline）を作成します。

3. <guardrails> から以下をコピーします。

   • 単一ユニット：templates/config.yaml → .guardrails/config.yaml
   • 複数ユニット：templates/units.yaml → .guardrails/units.yaml。インタビューの内容を反映して記入します。また、templates/config.yaml → 各ユニットの <unit>/.guardrails/config.yaml にコピーし、各ユニットの doc_* パスと verify_commands を調整します。マニフェストリポジトリにルートの .guardrails/config.yaml を置いてはいけません。1 つのツリーに 2 つの権限元があると、すべてのゲートで終了コード 2 になります。ユニットごとに配置するファイルについては references/multi-unit.md に記載されています。
   • scripts/*.sh → .guardrails/scripts/（実行権限を保持します）
   • templates/srs.md → docs/requirements/README.md
   • templates/rmf.md → docs/risk/README.md
   • templates/sad.md → docs/architecture/README.md
   • templates/soup.md → docs/architecture/soup.md
   • templates/problems.md → docs/problems/README.md
   • templates/CONTEXT.md → docs/CONTEXT.md
   • templates/*_GUIDELINES.md → .guardrails/templates/
   • templates/CLAUDE.md → CLAUDE.md（既存の場合はスキップします）
   • templates/AGENTS-block.md → 新規 AGENTS.md の本文

   要件、リスク、アーキテクチャ、問題の各ディレクトリは、変更ごとの台帳です。変更のたびに、変更を作成した日付を付けた YYYY-MM-DD-<slug>.md ファイルを 1 つ追加します。各 README には項目の文法が記載されています。

4. docs/adr/、docs/plans/、docs/verification/ を作成し、templates/verification.md → .guardrails/templates/verification.md にコピーします。テンプレートを docs/verification/ に置いてはいけません。そこにあるすべての *.md は記録として読み込まれます。記録を別の場所に保存する場合は、doc_verification を設定します。.gitignore に以下の項目がなければ追加します。

   .worktrees/
   .claude/worktrees/
   *.bak
   

   プロジェクトでこれまで 1 つしか使っていない場合も、ワークツリー用の項目を両方追加します。.claude/worktrees/ はハーネスの変更用ワークツリーを対象とし、.worktrees/ は手動フォールバックと、変更用ワークツリーの中にネストされるすべてのタスクワークツリー（worktree-discipline のステップ 1）を対象とします。

5. 設定済みのすべてのパスをコミット内に存在させます。そうでない場合、check-trace.sh は終了コード 2 となり、git は空のディレクトリを追跡しません。

   • strict_paths / test_paths の項目は git のパススペックであり、コミット済みのファイルに少なくとも 1 つ一致する必要があります。空の src/ に .gitkeep を置くだけで十分です。
   • doc_* の値にはファイル、または *.md ファイルが直下にあるディレクトリを指定します。ディレクトリには .gitkeep ではなく、実際の *.md ファイルが必要です。サブステップ 3 の README を残してください。
   • ディレクトリに内容が入るまでキーを省略してはいけません。ゲートを無効にするには、id_prefixes からそのプレフィックスを削除し、その理由を記録します。

6. 安全クラスのインタビュー（ステップ 4）を実施し、回答を safety_class: に記入して TBD のセンチネルを置き換え、verify_commands をプロジェクトで実際に使うテストコマンドに設定します。 TEST、CODE、ARCHITECTURE に対して tailor-guidelines を実行します（独自のファイルを必要とするユニットごとに、さらに 1 回実行します）。

7. ワークツリー内でコミットし、merge-change で統合します。統合後の結果でチェック用スクリプトがすべてパスする必要があります。

既存プロジェクトのスクリプトをアップグレードする

ワークツリーで、独立した変更として作業します。

1. references/upgrade-notes.md に記載された作業順に従います。最初の 3 項目をステップ 2 の前に実施します。
2. コピーする前に、各ガイドラインファイルに対してアップグレードモードで tailor-guidelines を実行します。その後、<guardrails> から scripts/*.sh → .guardrails/scripts/ に実行ビットを維持してコピーし、 templates/*_GUIDELINES.md → .guardrails/templates/ にコピーします。 .guardrails/scripts/finalize-ids.sh、finalize-docs.sh、prune-plans.sh が 存在する場合は削除します。
3. 文法をスクリプトとともに説明するファイルを更新します。 同じガードレールのバージョンから 4 つの台帳 README と検証テンプレートを再コピーし、 AGENTS.md の管理ブロックも再置換します。プロジェクトが README を編集している場合は、 差分を確認して追加内容を再適用します。
4. check-trace.sh を実行し、各失敗を修正します。ステップ 5 で検証記録を作成する際に、 新しい警告をそれぞれ記載します。既存の台帳では status:／opened: の問題、 上位文書化の相互参照、および DANGLING-FILE が報告されます。 派生評価が明示的に宣言されるようになりました。RMF に assesses: 行がない派生 REQ／LLR は 赤になります。
5. ツールの適格性を再記録し（ステップ 5）、merge-change で統合します。

ステップ 3（レトロフィット）：まずギャップ分析を行い、その後に強化する

1. 棚卸し（読み取り専用）：AGENTS.md／CLAUDE.md の内容とガードレールに 反するルール（「ベースブランチに直接コミットする」など）、既存の要件、リスク、 アーキテクチャ文書、バグトラッカーまたは問題ログ、 docs/verification/ に保管する価値のある検証証跡、テストの構成とコマンド、 CI 設定、最近のコミットの署名 （git log -20 --format='%h %G? %s'）。
2. ギャップ分析を docs/plans/<YYYY-MM-DD>-ratchet-gap-analysis.md に 書きます。存在するもの、不足しているもの、矛盾しているもの、および導入順序の提案を 記載します。これは変更の計画であり、ゲートの前に破棄されます。ステップ 5 で 検証記録を作成する際に、導入順序をその記録にコピーします。
3. 最初の一手：.guardrails/（設定、スクリプト、テンプレート、またはステップ 1b のマニフェストとユニットごとの設定）を導入し、管理ブロックを AGENTS.md に マージし、不足している文書の骨格を追加し、ステップ 2.4 に記載されたとおりに .gitignore を拡張します。この変更では既存文書を移行しないでください。 複数ユニットのリポジトリでは、先に references/multi-unit.md を読みます。
   • `` が存在する場合は、マーカー間のブロックだけを置き換えます。 存在しない場合は、templates/AGENTS-block.md 全体を追記します。 競合するルールはユーザーに報告し、削除しないでください。
   • strict_paths は、すでに整備済み、または新規のパスからなる短いリストに設定します。 既存の未追跡コードは既存のものとして扱います。
4. その後の一手（別々の変更として実施し、レトロフィットの検証記録に記載）： grill-requirements／analyze-risks を使ってレガシー要件文書とリスク文書を移行し、 各ガイドラインファイルに対して tailor-guidelines を実行し、 strict_paths の対象範囲を領域ごとに拡張します。 各 doc_* キーにはファイルまたはディレクトリを指定できるため、srs.md は 引き続き使用できます。複数の開発者がいるリポジトリでは、変更の競合を避けるため、 モノリシックな doc_* ファイルをそれぞれ README とともに、最初の日付付きファイルとして ディレクトリに移すことを推奨します。
5. merge-change で統合します。

ステップ 4：安全クラスの聞き取り（IEC 62304 4.3）

推奨する回答を示しながら、質問を一度に 1 つずつ尋ねます。

1. このソフトウェアの故障が、危険な状況の一因となる可能性はありますか。 いいえの場合 → クラス A。
2. はいの場合：ソフトウェア外部のリスク管理策を考慮した後でも、その結果生じる危害は 重傷または死亡に至る可能性がありますか。はいの場合 → クラス C、 重傷に至らない場合 → クラス B。
3. 根拠を ADR として記録します（grill-requirements の「ADRs」）。

ユーザーが判断に迷っている場合は、まず意図された使用方法、予見可能な誤用、 ハードウェアの安全策を確認します。2 つのクラスで迷う場合は、別の判断を正当化できるまで、 高い方のクラスを適用します。

複数ユニットのリポジトリでは、ユニットごとにこの聞き取りを繰り返し、 各ユニットの設定にクラスを記録します。

ステップ 5：人によるセットアップチェックリスト

変更の検証記録を今すぐ作成します。.guardrails/templates/verification.md を docs/verification/<date>-<branch>.md にコピーし、記入して印刷した references/setup-checklist.md を ## ツールの適格性確認 の下に置きます。

署名項目はラチェットのゲートです。 .guardrails/scripts/check-signing.sh --setup が終了コード 0 を返すまでは完了ではありません。 ステップ 2.7／ステップ 3.5 より前に項目を満たしてください。既存プロジェクトへの導入では、 既存プロジェクトはガードレールの採用を完了する前にコミット署名を設定する必要があることを早い段階で明記します。コミッターの公開鍵が見つからない場合は、作業を止め、その鍵を明示します。

ツールの適格性確認。 guardrails_version と guardrails_commit （git -C <guardrails> rev-parse HEAD）を設定とその記録に記載し、 テストスイートの結果も記録します。対象プロジェクト内のスクリプトは決して変更しません。

テストスイートはクローン内で実行し、対象プロジェクトでは決して実行しません。また、bats は決してインストールしません。 対象プロジェクトに bats を追加してはいけません。更新ごとに適格性を満たす実行を 1 回記録するか、suite not run at install time: <reason> と記録します。

終了ステータスはパイプを介さず、実行そのものから取得します。そうしないと、記録される合否が別のコマンドのものになります。次を実行します。 <guardrails>/tests/run-tests.sh > <tmp>/ratchet.log 2>&1; rc=$?。まず $rc を確認します。ログはクローンの外に保管します。ログには run-tests: testing commit <guardrails_commit> が含まれていなければなりません。run-tests: で始まる別の行がある場合、どのコミットについての記録か特定できないため、再実行します （references/rationale.md）。

注意すべき兆候

考え	実際のところ
「AGENTS.md を上書きするだけでいい」	レトロフィットでは上書きしません。管理ブロックのみを使います。
「今すぐすべての箇所で厳格なチェックを有効にしよう」	レガシーコードの作業がすべて止まります。制約を一段階だけ強めます。
「署名は後から追加する制約にできる」	最初のマージで適用されます。証明された署名がなければ、クリーンアップもできません。
「スキャフォールドにはワークツリーは不要」	他の変更と同様、ワークツリーと署名付きスカッシュマージを使います。
「safety_class は TBD のままでもよい」	設定するまで、ほかの項目を正しく拡張できません。
「スクリプトをコピーしたので、アップグレードは完了」	README、テンプレート、管理ブロックも更新します。

完了条件

• safety_class が設定されており（ユニットがある場合はユニットごとに）、ADR もあります。
• レトロフィットの検証記録に、ギャップ分析で決めた採用順序が記載されています。
• アップグレードでは、1 つのガードレールバージョンからスクリプトと文法ファイルをコピーし、各失敗に対処し、新しい警告をそれぞれ検証記録に記載しています。
• セットアップチェックリストが、適格性の根拠とともに保存されています。
• check-signing.sh --setup が終了コード 0 を返します。
• 変更が merge-change を通じてマージされ、チェック用スクリプトが合格します。

参考資料

• references/upgrade-notes.md — 既に .guardrails/scripts/ があるプロジェクトで更新する際、新しいスクリプトをコピーする前に読みます。
• references/multi-unit.md — ステップ 1b で複数のユニットが見つかった場合、ステップ 2.3 またはステップ 3.3 でファイルをインストールする前に読みます。
• references/setup-checklist.md — ステップ 5 に進んだときに読みます。
• references/rationale.md — ここにあるルールが誤っているように見えるとき、または変更を提案する前に読みます。