ハウス同期
リポジトリのベンダーハウスファイルをインストール済みプラグインの最新バージョンと同期し、ローカルの編集を決して静かに破棄しない。このスキルは /house-rules:sync 経由でのみ呼び出すこと。これはファイルを書き込むスキルであり、規約に関する単なる質問から発動することはありません(その場合は /house-rules:conventions を使用してください)。
このスキルが駆動するCLI:
node ${CLAUDE_PLUGIN_ROOT}/scripts/house <init|render|check> [--repo <path>] [--apply] [--force-managed <path>]
--repo のデフォルトはカレントディレクトリです。以下では init、render、check 以外のサブコマンドを発明することはありません。
デフォルトのパス: 計画、そして適用
同期にはただ一つのデフォルトパスがあります。毎回この順序で実行してください。
1. リポジトリがハウスを採用していることを確認する
リポジトリルートの house.json を読み取ります。house.json がない場合は、このリポジトリがまだブートストラップされていないことを意味します: 停止し、ユーザーに /house-rules:bootstrap を実行するように伝えてください。マニフェストがないことを「同期するものがない」と扱わないでください。
2. 計画 (ドライラン)
node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <path>
--apply がない場合、これは計画のみを行います。.house/lock.json (各エントリ: path, module, source, bodySha256) を読み取り、ディスク上の各管理ファイルの現在のボディハッシュをロックと比較し、次に新しくレンダリングされるボディと比較します。各管理ファイルを正確に1つのバケットに分類します:
- クリーン. ディスク上のハッシュがロックと一致します。計画: 新しくレンダリングされたボディで上書きします。
- 欠落. ファイルがディスク上に存在しません。計画: 復元します。
- ローカル変更. ディスク上のハッシュがロックともレンダリングされたno-opとも一致しません。計画: 拒否します。以下の3つの出口を参照してください。
他のことをする前に計画を出力してください。このステップでは、クリーンまたは欠落ファイルに対しても何も適用しないでください。
3. ローカル変更: 3つの出口、決して暗黙の選択はない
ローカルに変更された管理ファイルは、マージされず、上書きされず、静かに放置されることもありません。ディスク上のファイルとハウスがレンダリングするものとの差分を出力し、次に以下の3つの出口を正確にこの順序で出力し、そのファイルに対して停止します (--apply 下でもファイルは未変更のまま保持され、単に書き込みから除外されます):
- 上流優先. 変更を加えたハウスパッケージリポジトリ自体 (
dubbl-a/house-rules) に対してPRを開き、その編集がプライベートフォークではなく、全員の新しいハウスルールになるようにします。これが推奨される出口です。 - 逸脱を記録し管理対象から外す.
house.jsonのdeviations配列にwhyを持つエントリを追加し、ファイルを管理セットから削除し、リポジトリの CLAUDE.md の## Deviations from houseセクションにミラーリングします。これは編集が本当にリポジトリ固有であり、決して上流に送られない場合に使用します。 - 強制上書き. 以下を実行します:
これはローカル編集が破棄可能であることが確認された場合にのみ使用し、最も高速であるためデフォルトとして決して使用しないでください。実行する前にユーザーに確認を求めてください。ユーザーに代わってプロンプトなしで選択しないでください。node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <path> --force-managed <path>
4つ目のオプションを提供したり、これを選択を待つインタラクティブメニューにしないでください。3つの出口を実行の結果として述べ、ユーザー(またはこのスキルの後続の呼び出し)がいずれか1つに対して行動できるようにします。
4. 適用
クリーンなファイルと欠落ファイルが accounted for され、ローカルに変更されたすべてのファイルが3つの出口のいずれかにルーティングされるか(または意図的に拒否されたまま)、適用します:
node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <path> --apply
これにより、クリーンなファイルと欠落ファイルが書き込まれます。拒否されたままのローカル変更ファイルには決して書き込みません。--force-managed がそれを行う唯一のパスであり、指定された1つのパスに対してのみです。
レンダリングが warning: ... is git-ignored という行を出力した場合、続行する前に停止して無視ルールを修正してください: git が認識できない宛先はチェッカーやCIに届きません。.claude/settings.local.json のみを無視し、.claude/ や .house/ を決して無視しないでください。
レンダリングまたはチェッカーが warning: module is not in house.json, but <dir>/ exists here を出力した場合、このリポジトリの house.json が作成された後にモジュールが出荷され、そのルールはリポジトリが modules の下に "<name>": {"enabled": true} を追加するまでベンダー化されていません。自分でキーを追加しないでください: 警告行をそのまま同期PRの本文に、新しいモジュールがこのリポジトリに適用され、採用者の選択が必要であると述べる行の下にコピーしてください。
4b. レンダリングが書き込んだものをパスごとにステージングする
git add house.json .house/ .claude/rules/house/
レンダリング計画がそこにファイルをリストした場合にのみ、そのコマンドに scripts/house/ を追加してください。git はパススペックが何も一致しない場合、コマンド全体を拒否します。明示的なパスで、決して git add -A はしないでください: チェッカーとCIは git ls-files を読み取るため、ステージングされていないレンダリングファイルは誰もチェックしないものであり、ブランケット追加はツリーにある他のものをすべて掃き込んでしまいます。
レンダリングの Scaffolded リスト (.github/PULL_REQUEST_TEMPLATE.md、.github/workflows/pr-checks.yml、CLAUDE.md スケルトン) は管理ファイルではないため、[untracked] 警告はそれを認識できません: それらのファイルをレビューし、パスごとにステージングしてください。
スキャフォールドはレンダリングごとではなくリポジトリごとに1回提供されます。ロックの scaffolds リストは、このリポジトリがすでに受け取ったテンプレートを記録します。記録されたテンプレートは、そのファイルがまだディスク上にあるかどうかに関係なく、二度と書き込まれることはありません。そのため、CLAUDE.md.house-skeleton が CLAUDE.md にマージされて削除された場合、削除されたままであり、再同期で rm する必要はありません。リポジトリがそれを戻したい場合、render --apply --scaffold は欠落しているスキャフォールドを書き込み、既存のファイルを決して上書きしません。scaffolds キーが0.2.3以降の最初の同期でロック差分に現れることを期待してください。これは記録でありハッシュではなく、何もそれを拒否しません。
4c. Gitignore ツールスクラッチ
リポジトリの .gitignore に .claude/worktrees/ と .superpowers/ が含まれていることを確認し、欠けている行を追加してください。git status に表示されるツールスクラッチは、git add -A がされるとコミットされてしまいます。
5. ピンを確認する
house.json にロードされたプラグインバージョンが含まれていることを確認します。レンダリングによって書き込まれ、手動で編集しないでください。render --apply は version フィールドを以下のプラグインバージョンに設定します:
${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json
これを確認するために installed_plugins.json を決して読み取らないでください。これはリポジトリ間のインストール状態を記録し、現在ロードされているものと遅れたり異なったりする可能性があります。CLAUDE_PLUGIN_ROOT の下の plugin.json が実際にこの同期を実行しているバージョンです。
6. ベンダー化されたチェッカーで検証する
CI と prebuild が実際に実行する方法でチェッカーを実行してください。プラグイン自身のコピーではありません:
node .house/check.mjs
node ${CLAUDE_PLUGIN_ROOT}/scripts/house check --repo <path> はプラグイン自身のペイロードに対して同一のロジックを実行し、.house/check.mjs がリポジトリにベンダー化される前(初回同期時)に便利です。ベンダー化されたコピーが存在する場合は、それを直接実行することで、出荷されるファイルが実際にパスするファイルであり、同じように見えるだけのコピーではないことを証明します。
ここでの [untracked] 警告は、ステップ4bでそのファイルがスキップされたことを意味します。ステージングして再実行してください。[gitignored] の発見は、ステップ4の無視ルールがまだ管理ファイルを飲み込んでいることを意味します。
7. ドクターの出力を表示する
チェックの実行後、ドクターを実行しその行を報告してください:
node ${CLAUDE_PLUGIN_ROOT}/scripts/house doctor --repo <path>
各出力行の意味 (ラベルは doctor が出力する通り):
effective branch guard: plugin | repo | NONE.NONE:house.jsonがなく、リポジトリローカルのフックもありません。現在、保護ブランチへの直接コミットをガードしているものは何もありません。repo: リポジトリローカルの.claude/hooks/no-direct-master.shファイルが存在するか、.claude/settings.jsonがhooksブロックを持っています。移行中はリポジトリフックが優先されます。プラグインフックは deferred になり、exit 0 になります。plugin:house.jsonが存在し、リポジトリローカルのフックシグナルがどちらも存在しません。プラグインフックが実際にbranchPolicyとprotectedBranchesを強制しているものです。house.jsonがguardレコードを持つ場合はplugin (recorded <date>)、持たない場合はplugin (unrecorded)と出力されます。これはチェッカーのguard警告がクリアされているかどうかについてのみです。フックはどちらにせよ同じように強制します。
git-hook floor: .... ベンダー化された.githooks/ツリーがこのクローンで実際にgitに配線されているかどうか。core.hooksPathは.git/configに存在するため、これはマシン状態であり、クローン、レンダリング、PRはそれを保持しません。チェッカーはそれを決して読み取りません(ADR 0008 はチェッカーをリポジトリのみに保ちます)。そしてドクターがそれを報告する場所です。armed (core.hooksPath=<path>, <scope>): git がここでフロアを実行しています。何もする必要はありません。NOT armed -- core.hooksPath is unset in this clone: フロアはレンダリングされていますが、非アクティブです。house render --applyで有効化されるか、プラグインがインストールされた状態でリポジトリでセッションを開始すると有効化されます。NOT armed -- core.hooksPath is <other>: 別のツール(husky、lefthook、モノレポの慣習)が、このリポジトリが持つ唯一の hooksPath を所有しています。House はそれを決して上書きしません。そこからフロアをチェーンするか、それを unset して render を再実行してください。not rendered here (missing: <paths>): 7つのフロアファイルのうち少なくとも1つが欠落しており、行はそれらを指定します。7つすべてが欠落しているのは、単にまだフロアをレンダリングしていないリポジトリです。1つ欠落しているのは見た目以上に悪いです。すべてのガードは.githooks/house-lib.shを source し、その source が失敗した場合に非ゼロで終了します。そのため、ライブラリのみが欠落しているフロアは、フェイルオープンする代わりにすべてのコミットを失敗させます。いずれにせよレンダリングしてください。not applicable: このルートにhouse.jsonがないか、branchPolicyがprではありません。- インデントされた後続の行は、保護的ではなくフロアを静かにするものを報告します。
foreign hooks in this clone's .git/hooks: アーミングは拒否されます。なぜならcore.hooksPathは.git/hooksを完全に置き換え、それらを静かに無効にするからです。not executable: git はビットがないフックを静かに無視するため、失われたモードはフェイルオープンです。レンダリングはそれを復元します(ファイルを読み取れるクラスに対してのみビットを追加するため、意図的に 0600 のフックは 0700 に戻り、決して拡張されません)。reference-transaction: supported by git <version> (>= 2.28)またはinert on git <version> (needs 2.28): 2.28 以降ではフロアにどのフラグもオフにできないメンバーがあり、inert な行は表面的なものではなく実際のギャップです。2.28 未満では--no-verifyはpre-commitとpre-pushを一緒にスキップし、他にそれをキャッチするものはありません。そのため、そのgitではフラグはセッション時間の PreToolUse フックによってのみ拒否され、ループ内にセッションがない場合、それは存在しません。この行をgitをアップグレードするプロンプトとして扱い、メモとして扱わないでください。
jq on PATH: yes | no. フックはそれなしでも拒否します(手書きのdeny JSON)が、ギャップを報告して修正されるようにします。pin vX matches plugin vY|pin vX differs from installed plugin vY.house.jsonのversionとプラグイン自身のplugin.jsonの比較。ステップ5と同じ比較です。differsはピンの更新がまだ行われていないか、スキップされたことを意味します。npm wiring (.house/check.mjs referenced by): <scripts> | none found..house/check.mjs --only=drift,todoを呼び出すcheck:docs(または同等の軽量なスクリプト)と、完全な.house/check.mjsを呼び出すcheck:houseスクリプトを期待します。いずれかが欠落している場合、package.jsonを直接編集するのではなく、コピー&ペースト可能なスニペットを出力してください:"check:docs": "node .house/check.mjs --only=drift,todo" "check:house": "node .house/check.mjs"rule-load positive control: ....InstructionsLoadedフックが配線されているかどうか、そしてその独自のログが実際に何を目撃したか。これがないと、グロブが決して一致しないルールは、何もしないルールとまったく同じに見えます。repo (.claude/settings.json): リポジトリが独自のフックを宣言しています。plugin hook; log <path>: last load <ts>, <n> of <m> vendored rules seen: プラグイン自身のフックが配線され、少なくとも1回のロードをログに記録しており、実際にロードされたベンダールールファイルの実数を持っています。<n>が<m>より少ない場合、行は; not seen in this log: <names>と続き、ログがロードを保持していない各ベンダールールを名前で示します。なぜなら、数だけでは何かが間違っているとわかっても、どのファイルを開けばいいかわからないからです。そのリストをリードとして読み、評決として読まないでください。ログは自己トリミングされるため、ルールはずっと前にロードされた後にのみそこに現れる可能性があり、誠実な次のステップは、ルールのpaths:が主張するファイルを開き、ドクターを再実行することです。それを生き残った名前は、その範囲が書かれたファイルに到達していないルールです。plugin hook declared; no log yet for this checkout: プラグインのフックは配線されていますが、ここではまだ何もログに記録していません -- このリポジトリでセッションを開始し、ドクターを再実行してください。none wired: 何もフックを宣言していません。git-ignored house destinations: none | <paths>.none以外は、チェッカーが認識できない宛先です。ステップ4と同様に無視ルールを修正してください。
8. リポジトリが上流で修正できないものを、アイテムごとに1つのIssueにルーティングする
同期またはコンプライアンスパスは、多くの場合、パッケージのみが対処できる所見や警告を表面化します: チェッカーのギャップ、ここに存在しないファイルに名前を付けるルールアンカー、リポジトリが必要としスキーマに欠けている設定スロット。そのような各アイテムに対して、同じセッションで上流で修正するか(パッケージリポジトリへのブランチとPR。ステップ3と同じ上流優先の出口)、またはパッケージリポジトリにアクション可能なアイテムごとに1つのIssueをファイルし、単一の変更でクローズできるほど小さくします。
決して複数アイテムのダイジェストIssueにバッチ化しないでください: ダイジェストは最も遅いアイテムが着地するまでクローズできず、そのアイテムは独立して優先順位付けできず、半分解決されたダイジェストが蓄積されます。このリポジトリに残るのは、このリポジトリが修正できるものだけです。
エスケープハッチ
これらは上記のデフォルトパスでインラインで表面化される例外であり、事前に選択するための別個のメニューではありません:
house.jsonがない: ステップ1で停止し、/house-rules:bootstrapを指定します。- ローカルに変更されたファイル: ステップ3の3つの出口。
- 破棄可能であることが確認されたローカル編集:
--force-managed <path>。尋ねた後にのみ。 - リポジトリでの初回同期、
.house/check.mjsがまだベンダー化されていない: ステップ6でベンダー化されたパスの代わりにhouse check --repo <path>を使用し、これが1回限りの置換であり、定常状態ではないことに注意してください。
してはいけないこと
- ローカルに変更された管理ファイルをマージしないでください。
…
[truncated for translation]