English · 日本語

ここにあるのは、仮定ではなく実際に起きた失敗だけです。症状を探し、最初の一手を実行してから、 該当の節を読んでください。

まず種類を確認します。 Windows のハーネスは .ps1 フックを同梱します。settings.json が .sh を登録していると、すべての参照が外れ、すべてが許可されます。種類と登録はどちらも一つの OS フラグから導かれるので、食い違っていればハーネスが手で編集されています。

harness-view assess .        # 同梱されているのに登録されていないフックを報告する

次にフックを直接試します。 フックは標準入力で JSON を読み、終了コードで答えます:

echo '{"cwd":"'"$PWD"'","tool_name":"Bash","tool_input":{"command":"cat .env"}}' \
  | bash .claude/hooks/protect-secrets.sh; echo "exit=$?"

2 はブロック、0 は許可です。PowerShell では $? ではなく必ず $LASTEXITCODE を確認します。 $? はスクリプトが動いたかを示す真偽値で、何を決めたかではありません。Windows では PATH 上の bash が Git Bash ではなく WSL のランチャーのことがあります。両者はパスの解決が違うので、設定が 呼ぶ方で試してください。

v1.20.1 より古いハーネスなら 更新してください (/harness-update)。そこで実セッションの穴が 四つ塞がれました: git -c k=v commit などの git グローバルオプションがコミットと破壊的コマンドの ガードをすり抜けた、Windows PowerShell 5.1 のペイロードにバイトオーダーマークが付いて検証台帳が 止まった、タイムアウトしたガードがコマンドを通した、protect-secrets が PowerShell ツールを 見ていなかった、の四つです。

ブロッキングフックは onFailure: "block" と 30 秒のタイムアウトを持ちます。動けないガードは許可 ではなく拒否します。すべての Bash 呼び出しがブロックされるなら、フック自体が失敗しています。 上と同じ手順で手動実行してください。よくある原因は、登録が呼ぶインタプリタ (bash、pwsh、 powershell) が PATH にないこと、またはフックがタイムアウトより遅いことです。

このフックは検証台帳 (.claude/state/verify-ledger.jsonl) を読み、次を拒否します:

• すでに合格した内容に対するレビューやスイートの再実行
• 結果が記録されないまま、同じ内容に同じ席を二度ディスパッチすること
• 三回目のレビュー、または同一の指示
• タスクの予算 (dispatch_budget、既定 24) を超えるディスパッチ
• 登録済みの TASK-NNN も TIER: direct / TIER: standard も示さない、書き込み可能な席

メッセージは台帳の行を引用します。記録された結果を使うか、何かを変えてゲートを一度だけ実行して ください。.claude/hooks/README.md のとおり、上書きできるのはあなただけです。

guard-board は docs/tasks/master-plan.md のタスク行の編集をブロックします。タスクの状態は ファイルの status:、そのフォルダ、ボードの行の三か所にあり、 python .claude/scripts/task.py move TASK-NNN <state> が三つを変えて行を読み戻します。Phases 表と ボード周りの文章は今も編集できます。

python .claude/scripts/harness-check.py

登録されたフックのスクリプトが存在するか、コマンドや表が名指しする席が存在するか、階層表と席が 一致するか、引用されたルールが存在するか、席が挙げるスキルがインストールされているかを確かめます。 各所見は file:line と修正を示します。

実際のバグでした: 拒否ルールが .env.example、つまりすべてのブロックメッセージが読めと案内する 唯一のファイルに一致していました。修正済みで、eval は見本の読み取り、ローカルの .env の作成、 それを読み込んだ実行を確かめています。自分のハーネスでは、拒否リストには env を含むすべての ファイル名ではなく、値を持つファイルを挙げてください。.claude/settings.json と protect-secrets フックを確認します。

python harness-bootstrap/scripts/port.py --self-test

両方のフックの種類、アダプターがプラットフォームで使われうるすべてのインタプリタ名を候補にして いること、評価できない呼び出しを拒否することを確かめます。かつてアダプターは powershell と いう名前を埋め込んでいましたが、これは Windows にしかありません。macOS と Linux のバイナリは pwsh なので、すべての呼び出しがトレースバックで落ち、ガードは一度も動いていませんでした。

Codex では、プロジェクトが信頼済みか、フックが /hooks でレビュー済みかも確認してください。 それまでは移植したフックはディスク上にあるだけで動きません。 docs/tools/codex.ja.md を参照してください。

graph-stale フックは .claude/ 配下の編集の後に .claude/state/harness-graph.json を再生成し、 /harness-update と /harness-toggle は自分で再生成します。スクリプトによる書き込みはエディタの フックを発火させないためです。二つのマップは必要なときに作ります: /code-graph はモジュール境界の マップを更新し、/docs-graph は孤立した要件 ID を表示します。強制的に再構築するには:

python .claude/scripts/harness-graph.py     # または: harness-view scan .

python scripts/check_numbers.py

文書、デッキ、クリップ、図のすべての数字をスクリプトの出力と比べ、矛盾があれば非ゼロで終わります。 かつてクリップは eval が 107 に達した後も古い 26 件の結果を表示し続け、その表記がスラッシュの前後に 空白を挟んでいたせいでチェッカーから隠れていました。ページとスクリプトが食い違えば、スクリプトを信じて Issue を開いて ください。

• CONFLICT はエラーではありません。ファイルが存在し、インストールされる内容と違うという 意味です。一つずつ手で解決します: 自分のものを残す、手直しする、新しいものを採る、差分をタスクとして 登録する。スキャフォルダはあなたが書いたものを上書きも削除もしません。
• 変数で終了コード 1 は、未解決の {{VAR}} です。ルールファイルに残ったプレースホルダは何にも 一致せず黙って失敗するので、実行は何も書きません。vars.json で埋めて再実行してください。
• 編成やリンクで終了コード 1 は、無効なフラグの組、Agent を持つ二つ目の席、配線されていない 統制、harness-check.py が解決できないリンクのいずれかです。メッセージがファイルと行を示します。

harness-view assess . の出力と、失敗したコマンドを添えて Issue を開いてください。assess の 出力はノードを名指しするので、たいていそれで問題の場所が分かります。