uni-harness 0.2.1 → 0.2.2

package/.claude/hooks/session-start.sh

@@ -56,6 +56,22 @@ try:
 except Exception:
     pass
 
+# (4) CLAUDE.md still references the pre-v0.2 checkpoint locations
+# (the installer never edits the user-owned CLAUDE.md — Claude proposes
+# the fix as a diff instead)
+try:
+    with open(os.path.join(proj, "CLAUDE.md")) as f:
+        cm = f.read()
+    if ".harness/state" not in cm and ("progress.json" in cm or "plan.md" in cm):
+        parts.append(
+            "[harness] This project's CLAUDE.md references checkpoint files "
+            "(plan.md / progress.json / decisions.jsonl) at the project root, "
+            "but the harness now keeps them in .harness/state/. Propose a "
+            "small diff updating those path references in the Work Loop and "
+            "Checkpoints sections, and apply it only with the user's approval.")
+except Exception:
+    pass
+
 # (2) accumulated failures in the last 7 days -> nudge toward /ratchet
 try:
     cutoff = datetime.datetime.now() - datetime.timedelta(days=7)

package/README.ja.md

@@ -0,0 +1,213 @@
+# uni-harness
+
+🇺🇸 [English](README.md) | 🇰🇷 [한국어](README.ko.md) | 🇨🇳 [简体中文](README.zh-CN.md) | 🇯🇵 **日本語**
+
+![license](https://img.shields.io/badge/license-MIT-blue)
+![node](https://img.shields.io/badge/node-%E2%89%A516-brightgreen)
+![runtime](https://img.shields.io/badge/runtime-bash%20%2B%20python3%20stdlib-lightgrey)
+![for](https://img.shields.io/badge/for-Claude%20Code-d97757)
+
+Claude Code 向けのエージェント・ハーネスキットです。コーディング
+エージェントを、自動検証（センサー）、破壊的コマンドのブロック
+（ガード）、チェックポイントによるセッション復旧、トリップワイヤー
+付きの全ツール呼び出しログ、そしてあらゆる失敗を恒久的な構造へと
+変えるラチェット・ワークフローで包み込みます。
+
+> 公式: **Agent = Model + Harness.** 推論はモデルが担い、
+> それ以外のすべて — ルール、センサー、ループ上限、メモリ、
+> 可観測性 — をこのキットが担います。
+
+## インストール
+
+```bash
+npx uni-harness init            # プロジェクトルートで（または: init <パス>）
+```
+
+その後プロジェクトで Claude Code を開くと — Claude がハーネスの
+未設定を検知し、**`/harness-init` の実行を自ら提案**します（自分で
+実行しても構いません）。リポジトリをスキャンしてビルド/テスト/リント
+コマンドを検出し、**実際に実行して検証**した上で、承認を得て
+`CLAUDE.md` と `.harness/commands.env` に書き込みます。このステップ
+が終わるまで検証センサーは待機状態です。
+
+その他のインストーラーコマンド:
+
+```bash
+npx uni-harness update          # キットの機構を更新（あなたのファイルには一切触れません）
+npx uni-harness doctor          # インストール状態を診断
+npx uni-harness uninstall --yes # キットの機構を削除、あなたのファイルは保持
+```
+
+必要環境: bash、python3（標準ライブラリのみ — パッケージ不要）、
+インストーラー自体に node ≥16。
+
+**進行中のプロジェクトでも安全です。** `init` はあなたが所有する
+ものを決して上書きしません: 既存の `CLAUDE.md` は保持され
+（`/harness-init` がハーネス用セクションの追記を提案します）、既存の
+`settings.json` のフックと権限は保持されたままキットのフックが
+マージされ、`.gitignore` は置き換えではなく追記されます。`update` は
+未変更のキットファイルのみを更新します — カスタマイズしたものは
+スキップされ（一覧表示、`--force` で上書き可）ます。
+
+## 内容物
+
+| ファイル | 役割 |
+|---|---|
+| `CLAUDE.md` | プロジェクトのコマンド、ルール、アンチパターン、ワークループとチェックポイントのプロトコル |
+| `.claude/settings.json` | フック登録 |
+| `.claude/hooks/sensor-post-edit.sh` | コード編集のたびに即座にリントを実行し、失敗をフィードバック |
+| `.claude/hooks/stop-gate.sh` | ターン終了時にテストを一括実行。失敗状態での終了をブロック（セッションあたり3回上限、超過でエスカレーション要求） |
+| `.claude/hooks/guard-pre-bash.sh` | 破壊的コマンドと検証バイパス（`--no-verify`）を実行前にブロック |
+| `.claude/hooks/session-start.sh` | セッション開始/再開/圧縮時に進行中チェックポイントを再注入。失敗が蓄積すると `/ratchet` を提案 |
+| `.claude/hooks/observe-log.sh` | 全ツール呼び出しを JSONL で記録 + トリップワイヤー（同一失敗3回、呼び出し急増） |
+| `harness/harness_report.py` | ログからのヘルススコアカード |
+| `harness/tests/` | フックとインストーラーのセルフテスト |
+| `bin/cli.js` | インストーラー（init / update / doctor / uninstall） |
+
+スキル:
+
+| スキル | 役割 |
+|---|---|
+| `/harness-init` | リポジトリをスキャン → PROJECT セクションと commands.env を記入（インストール時に1回） |
+| `/checkpoint` | `.harness/state/` に状態を保存（plan.md / decisions.jsonl / progress.json） |
+| `/ratchet [ミス]` | 再現 → 分類 → ルール/センサー/権限を提案 → 検証（引数なし: ログ診断） |
+| `/guide-audit` | CLAUDE.md ルールの監査 — 維持 / 削除 / センサー化（月次） |
+
+## 推奨パーミッション（任意）
+
+キットはパーミッションポリシーを強制しません。無人運用や高自律
+モードで使うなら、プロジェクトの `.claude/settings.json` に以下の
+ような設定を検討してください — 特にエージェントが自身のハーネスを
+編集できないようにする項目を:
+
+```json
+{
+  "permissions": {
+    "ask": [
+      "Edit(.claude/**)", "Write(.claude/**)",
+      "Edit(.harness/**)", "Write(.harness/**)",
+      "Edit(.env*)", "Edit(*.config.*)", "Edit(.github/**)"
+    ],
+    "deny": [
+      "Read(.env)", "Read(.env.*)", "Read(**/secrets/**)",
+      "Read(**/*.pem)", "Bash(sudo*)"
+    ]
+  }
+}
+```
+
+## 運用ルーティン
+
+- **毎日 / タスクごと:** 普通に作業するだけです。センサーとガードは
+  自動です。長いタスクは `/checkpoint` で状態を保存。
+- **ミスを見つけたら:** 会話の中で直すだけにせず — `/ratchet
+  [何が起きたか]` で構造化してください。同じレビューコメント3回 →
+  ルールへ。同じルール違反3回 → ガード/権限へ昇格。
+- **毎週:** `python3 harness/harness_report.py` でスコアカードを
+  確認。繰り返しの失敗が見えたら `/ratchet` を実行。
+- **毎月:** `/guide-audit` で CLAUDE.md を監査 — センサーが既に
+  強制しているルールは削除し、矛盾はマージ。
+
+## カスタマイズ
+
+- 危険コマンドのパターン: `guard-pre-bash.sh` の `DENY_PATTERNS`
+- トリップワイヤーの閾値: `observe-log.sh`（デフォルト: 同一失敗3回、300呼び出し）
+- センサー対象の拡張子: `sensor-post-edit.sh` の case 文
+- 終了ブロック上限: `stop-gate.sh`（デフォルト: セッションあたり3回）
+- フックを変更したら `harness/tests/test_hooks.sh` にケースを追加して実行
+
+## 使うべきでない場面
+
+単発の質問、探索的なブレインストーミング、検証不能なクリエイティブ
+作業にはオーバーキルです。繰り返し実行される作業、失敗に実コストが
+伴う作業、無人で走る作業、セッションを跨いで状態を保持すべき作業で
+真価を発揮します。
+
+## 設計背景
+
+このキットは2つの資料の実装です。完全な分析は [`docs/`](docs/) に
+あります — npm パッケージには含まれません（動作中のエージェントに
+理論は不要）が、ここでのすべての設計判断を説明しています。
+
+### 📄 EnvHarness: Awakening Static Worlds for Agent Learning
+
+> **[arXiv:2608.19880](https://arxiv.org/abs/2608.19880)** · Chengsong Huang, Zifeng Wang, Rujun Han, Chen-Yu Lee ほか (2026)
+> 詳細分析: [docs/analysis-01-envharness.md](docs/analysis-01-envharness.md)
+
+**論文の主張。** *エージェント*にハーネス（ツール、メモリ、スキル）
+を装着すれば重みに触れずに拡張できるのと同様に、*環境*にハーネスを
+装着すれば、そのコードに触れずに学習信号をカスタマイズできる:
+`Static Env + EnvHarness = Customized Env`。環境はインターフェース層
+でのみ、3つの合成可能なコンポーネントによって変換される —
+**Stage**（初期状態の再構成）、**Contract**（アクションのフィルタ、
+観測の変換、遷移のラップ）、**Chain**（環境の合成）— そのため元の
+正解検証器は常に保存され、これが LLM 生成環境に対する本手法の中核的
+優位性となる。**EnvRigger** という自動化ループが設計を駆動する:
+失敗軌跡を*観察* → 根本原因を*診断* → 変換を*作成* → 元の失敗に
+対して*検証*。5つのベンチマークでラップされた環境がエージェント性能
+を引き上げ（例: ALFWorld 分布外 +9.0 ポイント、SWE-bench Verified
++2.7 かつステップ数 9.8% 減）— 分布外で最大の効果を示したことは、
+暗記ではなく転移の証拠である。
+
+**このキットが取り入れたもの:**
+
+| 論文の概念 | ここでの実装 |
+|---|---|
+| EnvRigger ループ（観察 → 診断 → 作成 → 検証） | `/ratchet` スキル — 自動受理を**ユーザー承認**に置き換え |
+| Contract: アクションのフィルタリング | `guard-pre-bash.sh`（破壊的コマンドを実行前にブロック） |
+| Contract: 構造化されたフィードバック | `sensor-post-edit.sh` / `stop-gate.sh`（検証結果をフィードバック） |
+| Stage: 準備された初期状態 | セッション開始時のチェックポイント復旧 |
+| **元の検証器の保存** | 不変条件: ハーネスはテストスイートを包むが、決して変更もバイパスもしない |
+
+### 📘 ハーネス・エンジニアリング: 6層プロダクション・プレイブック
+
+> 公開されている実務者資料の統合 — [Mitchell Hashimoto](https://mitchellh.com/)
+> のラチェット方法論、[OpenAI Codex フィールドレポート](https://openai.com/index/harness-engineering)、
+> [Martin Fowler](https://martinfowler.com/) のガイドとセンサーの分類、
+> そして Anthropic / LangChain / Cursor の資料。
+> 詳細分析: [docs/analysis-02-harness-engineering.md](docs/analysis-02-harness-engineering.md)
+
+**プレイブックの主張。** プロンプトエンジニアリング（モデルが*言う*
+こと）とコンテキストエンジニアリング（モデルが*見る*こと）は、
+ハーネスエンジニアリングに包含される: モデルが*できる*こと、失敗を
+生き延びるもの、許可されるもの、そして完了と見なされるもの。
+**Agent = Model + Harness** という主張は、自己報告ながら一貫した証拠
+に裏付けられている — 同じモデルがハーネスの交換だけで GAIA 30.91% →
+74.55% に跳躍、固定されたモデルがハーネス最適化だけで Terminal Bench
+30位 → 5位に上昇。アーキテクチャは6層で、このキットと1対1で対応する:
+
+| # | 層 | 原則 | このキットでは |
+|---|---|---|---|
+| 1 | **ガイド** | 各行 = 過去の失敗1件の恒久的予防 | `CLAUDE.md` |
+| 2 | **センサー** | 外部の決定論的チェック。自己判断は禁止 | `sensor-post-edit.sh`、`stop-gate.sh` |
+| 3 | **エージェンティックループ** | すべての予算に上限、枯渇時はエスカレーション | ワークループ・プロトコル + トリップワイヤー + 終了ブロック3回上限 |
+| 4 | **メモリ** | ファイルシステムこそがメモリ。復旧テスト合格が必須 | `/checkpoint` + `session-start.sh` |
+| 5 | **パーミッション** | モデルは自分自身を制限できない | `guard-pre-bash.sh` + 推奨パーミッション |
+| 6 | **可観測性** | すべてを記録し、ドリフトに警報 | `observe-log.sh` + `harness_report.py` |
+
+運用ルールもここから来ています — Hashimoto の**ラチェット原則**
+（「エージェントがミスをするたびに、そのミスの再発を不可能にする
+解決策をエンジニアリングせよ」）と Cursor の昇格ラダー:
+
+```mermaid
+flowchart LR
+    F[失敗を観察] --> R["/ratchet: 再現 + 診断"]
+    R --> P{最も強い層}
+    P -->|コンテキスト不足だった| G["ガイドルール (CLAUDE.md)"]
+    P -->|チェックで検出できる| S[センサー / lint ルール]
+    P -->|そもそも不可能にすべき| H[ガード / パーミッション]
+    G & S & H --> V[元の失敗に対して検証]
+    V --> N[同じ失敗は再発不能]
+```
+
+同じレビューコメント **3回** → ルールになる。同じルール違反 **3回**
+→ ゲートになる。そして成熟のシグナルはルール増加率の*低下*だ —
+蓄積するだけのハーネスは負債であり、それこそが `/guide-audit` の
+存在理由である。
+
+---
+
+キット自体を拡張するには？
+[docs/AGENT_BRIEFING.md](docs/AGENT_BRIEFING.md) から始めてください —
+不変条件（検証を弱めない、承認なしの自動適用禁止、最小限の
+インフラ）と、精査済みのバックログが載っています。

package/README.ko.md

@@ -0,0 +1,207 @@
+# uni-harness
+
+🇺🇸 [English](README.md) | 🇰🇷 **한국어** | 🇨🇳 [简体中文](README.zh-CN.md) | 🇯🇵 [日本語](README.ja.md)
+
+![license](https://img.shields.io/badge/license-MIT-blue)
+![node](https://img.shields.io/badge/node-%E2%89%A516-brightgreen)
+![runtime](https://img.shields.io/badge/runtime-bash%20%2B%20python3%20stdlib-lightgrey)
+![for](https://img.shields.io/badge/for-Claude%20Code-d97757)
+
+Claude Code용 에이전트 하네스 킷입니다. 코딩 에이전트를 자동 검증(센서),
+파괴적 명령 차단(가드), 체크포인트 기반 세션 복구, 트립와이어가 달린
+전체 도구 호출 로깅, 그리고 모든 실패를 영구 구조로 바꾸는 래칫
+워크플로로 감쌉니다.
+
+> 공식: **Agent = Model + Harness.** 추론은 모델이 가져오고,
+> 나머지 전부 — 규칙, 센서, 루프 상한, 메모리, 관측 — 는 이 킷이
+> 가져옵니다.
+
+## 설치
+
+```bash
+npx uni-harness init            # 프로젝트 루트에서 (또는: init <경로>)
+```
+
+그다음 프로젝트에서 Claude Code를 열면 — Claude가 하네스가 미설정
+상태임을 감지하고 **`/harness-init` 실행을 먼저 제안**합니다(직접
+실행해도 됩니다). 저장소를 스캔해 빌드/테스트/린트 명령을 감지하고,
+**실제로 실행해서 검증**한 뒤, 승인을 받아 `CLAUDE.md`와
+`.harness/commands.env`를 채웁니다. 이 단계 전까지 검증 센서는
+비활성 상태로 대기합니다.
+
+기타 인스톨러 명령:
+
+```bash
+npx uni-harness update          # 킷 기계 부품 갱신 (사용자 파일은 절대 안 건드림)
+npx uni-harness doctor          # 설치 상태 진단
+npx uni-harness uninstall --yes # 킷 기계 부품 제거, 사용자 파일은 유지
+```
+
+요구사항: bash, python3 (표준 라이브러리만 — 패키지 불필요), 인스톨러
+자체는 node ≥16.
+
+**진행 중인 프로젝트에도 안전합니다.** `init`은 사용자 소유 파일을
+절대 덮어쓰지 않습니다: 기존 `CLAUDE.md`는 유지되고(`/harness-init`이
+하네스 섹션 추가를 제안), 기존 `settings.json`의 훅·권한은 보존된 채
+킷 훅만 병합되며, `.gitignore`는 교체가 아니라 추가만 됩니다.
+`update`는 수정하지 않은 킷 파일만 갱신합니다 — 커스터마이즈한 파일은
+건너뛰고 목록으로 알려줍니다(`--force`로 덮어쓰기 가능).
+
+## 구성 요소
+
+| 파일 | 역할 |
+|---|---|
+| `CLAUDE.md` | 프로젝트 명령, 규칙, 안티패턴, 작업 루프·체크포인트 프로토콜 |
+| `.claude/settings.json` | 훅 등록 |
+| `.claude/hooks/sensor-post-edit.sh` | 코드 수정 즉시 lint 실행, 실패를 피드백 |
+| `.claude/hooks/stop-gate.sh` | 턴 종료 시 테스트 일괄 실행; 실패 상태의 종료를 차단 (세션당 3회 상한, 초과 시 에스컬레이션 강제) |
+| `.claude/hooks/guard-pre-bash.sh` | 파괴적 명령과 검증 우회(`--no-verify`)를 실행 전 차단 |
+| `.claude/hooks/session-start.sh` | 세션 시작/재개/압축 시 진행 중 체크포인트 재주입; 실패 누적 시 `/ratchet` 제안 |
+| `.claude/hooks/observe-log.sh` | 모든 도구 호출을 JSONL로 기록 + 트립와이어 (동일 실패 3회, 호출 급증) |
+| `harness/harness_report.py` | 로그 기반 상태 스코어카드 |
+| `harness/tests/` | 훅·인스톨러 자체 테스트 |
+| `bin/cli.js` | 인스톨러 (init / update / doctor / uninstall) |
+
+스킬:
+
+| 스킬 | 역할 |
+|---|---|
+| `/harness-init` | 저장소 스캔 → PROJECT 섹션 & commands.env 채우기 (설치 시 1회) |
+| `/checkpoint` | `.harness/state/`에 상태 저장 (plan.md / decisions.jsonl / progress.json) |
+| `/ratchet [실수]` | 재현 → 분류 → 규칙/센서/권한 제안 → 검증 (인자 없이: 로그 진단) |
+| `/guide-audit` | CLAUDE.md 규칙 감사 — 유지 / 삭제 / 센서 전환 (월 1회) |
+
+## 권장 권한 설정 (선택)
+
+킷은 권한 정책을 강제하지 않습니다. 무인 실행이나 고자율 모드로 쓴다면
+프로젝트의 `.claude/settings.json`에 아래와 같은 설정을 고려하세요 —
+특히 에이전트가 자기 하네스를 수정하지 못하게 막는 항목들:
+
+```json
+{
+  "permissions": {
+    "ask": [
+      "Edit(.claude/**)", "Write(.claude/**)",
+      "Edit(.harness/**)", "Write(.harness/**)",
+      "Edit(.env*)", "Edit(*.config.*)", "Edit(.github/**)"
+    ],
+    "deny": [
+      "Read(.env)", "Read(.env.*)", "Read(**/secrets/**)",
+      "Read(**/*.pem)", "Bash(sudo*)"
+    ]
+  }
+}
+```
+
+## 운영 루틴
+
+- **매일 / 작업마다:** 그냥 일하면 됩니다. 센서와 가드는 자동입니다.
+  긴 작업은 `/checkpoint`로 상태를 저장하세요.
+- **실수를 발견하면:** 대화에서만 고치지 말고 — `/ratchet [무슨 일이
+  있었는지]`로 구조화하세요. 같은 리뷰 코멘트 3회 → 규칙으로; 같은
+  규칙 위반 3회 → 가드/권한으로 승격.
+- **매주:** `python3 harness/harness_report.py`로 스코어카드 확인;
+  반복 실패가 보이면 `/ratchet` 실행.
+- **매월:** `/guide-audit`으로 CLAUDE.md 감사 — 센서가 이미 강제하는
+  규칙은 삭제, 모순은 병합.
+
+## 커스터마이징
+
+- 위험 명령 패턴: `guard-pre-bash.sh`의 `DENY_PATTERNS`
+- 트립와이어 임계값: `observe-log.sh` (기본: 동일 실패 3회, 300 호출)
+- 센서 대상 확장자: `sensor-post-edit.sh`의 case 문
+- 종료 차단 상한: `stop-gate.sh` (기본: 세션당 3회)
+- 훅을 수정하면 `harness/tests/test_hooks.sh`에 케이스를 추가하고 실행
+
+## 이런 경우에는 쓰지 마세요
+
+일회성 질문, 탐색적 브레인스토밍, 검증 불가능한 창작 작업에는
+과합니다. 반복 실행되는 작업, 실패 시 실제 비용이 발생하는 작업,
+무인으로 돌아가는 작업, 세션을 넘어 상태를 보존해야 하는 작업에서
+값을 합니다.
+
+## 설계 배경
+
+이 킷은 두 자료의 실무 구현입니다. 전체 분석은 [`docs/`](docs/)에
+있습니다 — npm 패키지에는 포함되지 않지만(동작하는 에이전트에게 이론은
+불필요), 여기의 모든 설계 결정을 설명합니다.
+
+### 📄 EnvHarness: Awakening Static Worlds for Agent Learning
+
+> **[arXiv:2608.19880](https://arxiv.org/abs/2608.19880)** · Chengsong Huang, Zifeng Wang, Rujun Han, Chen-Yu Lee 외 (2026)
+> 상세 분석: [docs/analysis-01-envharness.md](docs/analysis-01-envharness.md)
+
+**논문의 주장.** *에이전트*에 하네스(도구, 메모리, 스킬)를 달아
+가중치를 건드리지 않고 확장하듯, *환경*에도 하네스를 달아 코드를
+건드리지 않고 학습 신호를 커스터마이즈할 수 있다: `Static Env +
+EnvHarness = Customized Env`. 환경은 인터페이스 계층에서만 세 가지
+조합 가능한 컴포넌트로 변환된다 — **Stage**(초기 상태 재구성),
+**Contract**(행동 필터링, 관측 변환, 전이 래핑), **Chain**(환경
+합성) — 그래서 원본 정답 검증기가 항상 보존되며, 이것이 LLM 생성
+환경 대비 핵심 우위다. **EnvRigger**라는 자동화 루프가 설계를
+주도한다: 실패 궤적 *관찰* → 근본 원인 *진단* → 변환 *작성* → 원래
+실패에 대해 *검증*. 다섯 벤치마크에서 래핑된 환경이 에이전트 성능을
+끌어올렸고(예: ALFWorld 분포 외 +9.0점, SWE-bench Verified +2.7에
+스텝 9.8% 감소) — 분포 외에서 가장 큰 이득을 보인 것은 암기가 아닌
+전이의 증거다.
+
+**이 킷이 가져온 것:**
+
+| 논문 개념 | 여기서의 구현 |
+|---|---|
+| EnvRigger 루프 (관찰 → 진단 → 작성 → 검증) | `/ratchet` 스킬 — 자동 수용을 **사용자 승인**으로 대체 |
+| Contract: 행동 필터링 | `guard-pre-bash.sh` (파괴적 명령 실행 전 차단) |
+| Contract: 구조화된 피드백 | `sensor-post-edit.sh` / `stop-gate.sh` (검증 결과 피드백) |
+| Stage: 준비된 초기 상태 | 세션 시작 시 체크포인트 복구 |
+| **원본 검증기 보존** | 불변조건: 하네스는 테스트 스위트를 감싸되 절대 수정·우회하지 않음 |
+
+### 📘 하네스 엔지니어링: 6계층 프로덕션 플레이북
+
+> 공개된 실무자 자료의 종합 — [Mitchell Hashimoto](https://mitchellh.com/)의
+> 래칫 방법론, [OpenAI Codex 필드 리포트](https://openai.com/index/harness-engineering),
+> [Martin Fowler](https://martinfowler.com/)의 가이드·센서 분류, 그리고
+> Anthropic / LangChain / Cursor 자료.
+> 상세 분석: [docs/analysis-02-harness-engineering.md](docs/analysis-02-harness-engineering.md)
+
+**플레이북의 주장.** 프롬프트 엔지니어링(모델이 *말하는* 것)과 컨텍스트
+엔지니어링(모델이 *보는* 것)은 하네스 엔지니어링에 포섭된다: 모델이
+*할 수 있는* 것, 실패에서 살아남는 것, 허용되는 것, 그리고 완료로
+인정되는 것. **Agent = Model + Harness**라는 주장은 자기 보고이지만
+일관된 증거로 뒷받침된다 — 같은 모델이 하네스 교체만으로 GAIA에서
+30.91% → 74.55%로 도약, 고정된 모델이 하네스 최적화만으로 Terminal
+Bench 30위 → 5위. 아키텍처는 6계층이며, 이 킷과 일대일로 대응한다:
+
+| # | 계층 | 원칙 | 이 킷에서 |
+|---|---|---|---|
+| 1 | **가이드** | 각 줄 = 과거 실패 하나의 영구 방지 | `CLAUDE.md` |
+| 2 | **센서** | 외부의 결정론적 검사, 자기 판단 금지 | `sensor-post-edit.sh`, `stop-gate.sh` |
+| 3 | **에이전틱 루프** | 모든 예산에 상한, 소진 시 에스컬레이션 | 작업 루프 프로토콜 + 트립와이어 + 3회 종료 차단 상한 |
+| 4 | **메모리** | 파일시스템이 곧 메모리; 복구 테스트 통과 필수 | `/checkpoint` + `session-start.sh` |
+| 5 | **권한** | 모델은 스스로를 제한할 수 없다 | `guard-pre-bash.sh` + 권장 권한 |
+| 6 | **관측** | 전부 기록하고 드리프트에 경보 | `observe-log.sh` + `harness_report.py` |
+
+운영 규칙도 여기서 왔습니다 — Hashimoto의 **래칫 원칙**("에이전트가
+실수할 때마다, 그 실수의 재발이 불가능해지는 해법을 엔지니어링하라")과
+Cursor의 승격 사다리:
+
+```mermaid
+flowchart LR
+    F[실패 관찰] --> R["/ratchet: 재현 + 진단"]
+    R --> P{가장 강한 계층}
+    P -->|컨텍스트 부족이었다| G["가이드 규칙 (CLAUDE.md)"]
+    P -->|검사로 잡을 수 있다| S[센서 / lint 규칙]
+    P -->|아예 불가능해야 한다| H[가드 / 권한]
+    G & S & H --> V[원래 실패에 대해 검증]
+    V --> N[같은 실패는 재발 불가]
+```
+
+같은 리뷰 코멘트 **3회** → 규칙이 된다. 같은 규칙 위반 **3회** →
+게이트가 된다. 그리고 성숙의 신호는 규칙 증가율의 *감소*다 —
+쌓이기만 하는 하네스는 부채이며, `/guide-audit`이 존재하는 이유다.
+
+---
+
+킷 자체를 확장하시나요?
+[docs/AGENT_BRIEFING.md](docs/AGENT_BRIEFING.md)에서 시작하세요 —
+불변조건(검증 약화 금지, 승인 없는 자동 적용 금지, 최소 인프라)과
+검증된 백로그가 담겨 있습니다.

package/README.md

@@ -1,5 +1,7 @@
 # uni-harness
 
+🇺🇸 **English** | 🇰🇷 [한국어](README.ko.md) | 🇨🇳 [简体中文](README.zh-CN.md) | 🇯🇵 [日本語](README.ja.md)
+
 ![license](https://img.shields.io/badge/license-MIT-blue)
 ![node](https://img.shields.io/badge/node-%E2%89%A516-brightgreen)
 ![runtime](https://img.shields.io/badge/runtime-bash%20%2B%20python3%20stdlib-lightgrey)

package/README.zh-CN.md

@@ -0,0 +1,201 @@
+# uni-harness
+
+🇺🇸 [English](README.md) | 🇰🇷 [한국어](README.ko.md) | 🇨🇳 **简体中文** | 🇯🇵 [日本語](README.ja.md)
+
+![license](https://img.shields.io/badge/license-MIT-blue)
+![node](https://img.shields.io/badge/node-%E2%89%A516-brightgreen)
+![runtime](https://img.shields.io/badge/runtime-bash%20%2B%20python3%20stdlib-lightgrey)
+![for](https://img.shields.io/badge/for-Claude%20Code-d97757)
+
+一个面向 Claude Code 的智能体挽具（harness）套件。它为编码智能体包上
+自动验证（传感器）、破坏性命令拦截（守卫）、基于检查点的会话恢复、
+带绊线告警的全量工具调用日志，以及把每次失败都转化为永久结构的
+棘轮（ratchet）工作流。
+
+> 公式：**Agent = Model + Harness。** 模型带来推理能力；
+> 其余的一切 — 规则、传感器、循环上限、记忆、可观测性 —
+> 由这个套件提供。
+
+## 安装
+
+```bash
+npx uni-harness init            # 在项目根目录执行（或：init <路径>）
+```
+
+然后在项目中打开 Claude Code — Claude 会发现挽具尚未配置，并
+**主动提议运行 `/harness-init`**（也可以自己运行）。它会扫描仓库、
+检测构建/测试/lint 命令、**通过实际运行来验证它们**，并在你批准后
+填入 `CLAUDE.md` 和 `.harness/commands.env`。在此步骤完成前，
+验证传感器保持待机。
+
+其他安装器命令：
+
+```bash
+npx uni-harness update          # 刷新套件机件（绝不触碰你的文件）
+npx uni-harness doctor          # 诊断安装状态
+npx uni-harness uninstall --yes # 移除套件机件，保留你的文件
+```
+
+依赖要求：bash、python3（仅标准库 — 无需任何包）、安装器本身需要
+node ≥16。
+
+**对进行中的项目同样安全。** `init` 绝不覆盖你拥有的任何东西：
+已有的 `CLAUDE.md` 会被保留（运行 `/harness-init` 后它会以追加方式
+提议补充挽具章节），已有 `settings.json` 中的钩子和权限会被保留
+（套件钩子以合并方式加入），你的 `.gitignore` 只会被追加而不是替换。
+`update` 只刷新未被修改的套件文件 — 你自定义过的一律跳过
+（会列出，可用 `--force` 覆盖）。
+
+## 内含组件
+
+| 文件 | 作用 |
+|---|---|
+| `CLAUDE.md` | 项目命令、规则、反模式、工作循环与检查点协议 |
+| `.claude/settings.json` | 钩子注册 |
+| `.claude/hooks/sensor-post-edit.sh` | 每次代码编辑立即运行 lint，将失败反馈回去 |
+| `.claude/hooks/stop-gate.sh` | 回合结束时批量运行测试；失败状态下阻止收工（每会话 3 次上限，超过则强制升级上报） |
+| `.claude/hooks/guard-pre-bash.sh` | 在执行前拦截破坏性命令与验证绕过（`--no-verify`） |
+| `.claude/hooks/session-start.sh` | 会话启动/恢复/压缩时重新注入进行中的检查点；失败堆积时提示 `/ratchet` |
+| `.claude/hooks/observe-log.sh` | 以 JSONL 记录每次工具调用 + 绊线（同一失败 3 次、调用激增） |
+| `harness/harness_report.py` | 基于日志的健康记分卡 |
+| `harness/tests/` | 钩子与安装器的自测 |
+| `bin/cli.js` | 安装器（init / update / doctor / uninstall） |
+
+技能：
+
+| 技能 | 作用 |
+|---|---|
+| `/harness-init` | 扫描仓库 → 填写 PROJECT 章节 & commands.env（安装时一次） |
+| `/checkpoint` | 将状态保存到 `.harness/state/`（plan.md / decisions.jsonl / progress.json） |
+| `/ratchet [失误]` | 复现 → 归类 → 提议规则/传感器/权限 → 验证（无参数：诊断日志） |
+| `/guide-audit` | 审计 CLAUDE.md 规则 — 保留 / 删除 / 转为传感器（每月） |
+
+## 推荐权限配置（可选）
+
+套件不强加权限策略。若用于无人值守或高自治场景，可考虑在项目的
+`.claude/settings.json` 中加入类似配置 — 尤其是阻止智能体修改
+自身挽具的那些条目：
+
+```json
+{
+  "permissions": {
+    "ask": [
+      "Edit(.claude/**)", "Write(.claude/**)",
+      "Edit(.harness/**)", "Write(.harness/**)",
+      "Edit(.env*)", "Edit(*.config.*)", "Edit(.github/**)"
+    ],
+    "deny": [
+      "Read(.env)", "Read(.env.*)", "Read(**/secrets/**)",
+      "Read(**/*.pem)", "Bash(sudo*)"
+    ]
+  }
+}
+```
+
+## 运营例程
+
+- **每天 / 每个任务：** 正常干活即可。传感器和守卫是自动的。
+  长任务用 `/checkpoint` 保存状态。
+- **发现失误时：** 不要只在对话里修掉 — 运行 `/ratchet [发生了什么]`
+  把它结构化。同一审查意见出现 3 次 → 变成规则；同一规则被违反
+  3 次 → 升级为守卫/权限。
+- **每周：** 用 `python3 harness/harness_report.py` 查看记分卡；
+  出现重复失败就运行 `/ratchet`。
+- **每月：** 用 `/guide-audit` 审计 CLAUDE.md — 删除传感器已自动
+  强制执行的规则，合并互相矛盾的规则。
+
+## 自定义
+
+- 危险命令模式：`guard-pre-bash.sh` 中的 `DENY_PATTERNS`
+- 绊线阈值：`observe-log.sh`（默认：同一失败 3 次、300 次调用）
+- 传感器文件扩展名：`sensor-post-edit.sh` 中的 case 语句
+- 收工拦截上限：`stop-gate.sh`（默认：每会话 3 次）
+- 修改了钩子就在 `harness/tests/test_hooks.sh` 加一个用例并运行
+
+## 什么时候不该用
+
+对一次性提问、探索性头脑风暴、无法验证的创意工作来说它是杀鸡用牛刀。
+它的价值体现在：反复运行的工作、失败有真实代价的工作、无人值守运行
+的工作、以及必须跨会话保持状态的工作。
+
+## 设计背景
+
+本套件是两份材料的可运行实现。完整分析在 [`docs/`](docs/) 中 —
+它们不随 npm 包分发（运行中的智能体不需要理论），但解释了这里的
+每一个设计决策。
+
+### 📄 EnvHarness: Awakening Static Worlds for Agent Learning
+
+> **[arXiv:2608.19880](https://arxiv.org/abs/2608.19880)** · Chengsong Huang, Zifeng Wang, Rujun Han, Chen-Yu Lee 等 (2026)
+> 深度解读：[docs/analysis-01-envharness.md](docs/analysis-01-envharness.md)
+
+**论文主张。** 正如给*智能体*装上挽具（工具、记忆、技能）可以在不动
+权重的情况下扩展它，你也可以给*环境*装上挽具，在不动其代码的情况下
+定制学习信号：`Static Env + EnvHarness = Customized Env`。环境只在
+接口层通过三个可组合的组件被变换 — **Stage**（重塑初始状态）、
+**Contract**（过滤动作、变换观测、包装转移）、**Chain**（组合环境）—
+因此原始的真值验证器始终得到保留，这正是它相对 LLM 生成环境的核心
+优势。一个名为 **EnvRigger** 的自动化循环驱动设计：*观察*失败轨迹 →
+*诊断*根因 → *编写*变换 → 对原始失败进行*验证*。在五个基准上，
+包装后的环境提升了智能体表现（如 ALFWorld 分布外 +9.0 分、SWE-bench
+Verified +2.7 且步数减少 9.8%）— 分布外增益最大，是迁移而非记忆的
+证据。
+
+**本套件从中借鉴的：**
+
+| 论文概念 | 此处的实现 |
+|---|---|
+| EnvRigger 循环（观察 → 诊断 → 编写 → 验证） | `/ratchet` 技能 — 自动接受被替换为**用户批准** |
+| Contract：动作过滤 | `guard-pre-bash.sh`（破坏性命令执行前拦截） |
+| Contract：结构化反馈 | `sensor-post-edit.sh` / `stop-gate.sh`（验证结果反馈） |
+| Stage：备妥的初始状态 | 会话启动时的检查点恢复 |
+| **保留原始验证器** | 不变量：挽具包装你的测试套件，但绝不修改或绕过它 |
+
+### 📘 挽具工程：6 层生产实战手册
+
+> 公开实践者材料的综合 — [Mitchell Hashimoto](https://mitchellh.com/)
+> 的棘轮方法论、[OpenAI Codex 实战报告](https://openai.com/index/harness-engineering)、
+> [Martin Fowler](https://martinfowler.com/) 的向导与传感器分类法，以及
+> Anthropic / LangChain / Cursor 的资料。
+> 深度解读：[docs/analysis-02-harness-engineering.md](docs/analysis-02-harness-engineering.md)
+
+**手册主张。** 提示词工程（模型*说*什么）和上下文工程（模型*看到*
+什么）都被挽具工程所涵盖：模型*能做*什么、什么能在失败中幸存、什么被
+允许、什么算完成。**Agent = Model + Harness** 这一主张有自报但一致的
+证据支撑 — 同一个模型仅靠更换挽具在 GAIA 上从 30.91% 跃升至 74.55%，
+固定模型仅靠挽具优化在 Terminal Bench 上从第 30 名爬到第 5 名。
+架构分为六层，与本套件一一对应：
+
+| # | 层 | 原则 | 在本套件中 |
+|---|---|---|---|
+| 1 | **向导** | 每一行 = 对一次过往失败的永久预防 | `CLAUDE.md` |
+| 2 | **传感器** | 外部确定性检查，绝不自我评判 | `sensor-post-edit.sh`、`stop-gate.sh` |
+| 3 | **智能体循环** | 每项预算都有上限，耗尽即升级上报 | 工作循环协议 + 绊线 + 3 次收工拦截上限 |
+| 4 | **记忆** | 文件系统即记忆；必须通过恢复测试 | `/checkpoint` + `session-start.sh` |
+| 5 | **权限** | 模型无法限制它自己 | `guard-pre-bash.sh` + 推荐权限 |
+| 6 | **可观测性** | 记录一切，对漂移告警 | `observe-log.sh` + `harness_report.py` |
+
+运营规则也来自于此 — Hashimoto 的**棘轮原则**（"智能体每犯一次错，
+就工程化一个让该错误不可能重演的方案"）以及 Cursor 的晋升阶梯：
+
+```mermaid
+flowchart LR
+    F[观察到失败] --> R["/ratchet: 复现 + 诊断"]
+    R --> P{最强的层}
+    P -->|缺的是上下文| G["向导规则 (CLAUDE.md)"]
+    P -->|检查可以捕获| S[传感器 / lint 规则]
+    P -->|应当彻底不可能| H[守卫 / 权限]
+    G & S & H --> V[针对原始失败验证]
+    V --> N[同一失败无法重演]
+```
+
+同一审查意见出现 **3 次** → 变成规则。同一规则被违反 **3 次** →
+变成关卡。而成熟的信号是规则增速的*下降* — 只会堆积的挽具就是债务，
+这正是 `/guide-audit` 存在的意义。
+
+---
+
+想扩展套件本身？从
+[docs/AGENT_BRIEFING.md](docs/AGENT_BRIEFING.md) 开始 — 那里有
+不变量（不得削弱验证、未经批准不得自动应用、最小基础设施）和经过
+审核的待办清单。

package/harness/tests/test_hooks.sh

@@ -115,6 +115,14 @@ echo '{"task_id":"t1","status":"in_progress","next_step":"do X"}' > "$TMP/progre
 OUT=$(bash "$HOOKS/session-start.sh")
 check "reads legacy root checkpoint" "progress.json" "$OUT"
 rm "$TMP/progress.json"
+# CLAUDE.md still pointing checkpoints at the root -> propose-a-diff nudge
+printf '# P\n- write the plan to plan.md\n' > "$TMP/CLAUDE.md"
+OUT=$(bash "$HOOKS/session-start.sh")
+check "nudges CLAUDE.md path migration" "user's approval" "$OUT"
+printf '# P\n- write the plan to .harness/state/plan.md\n' > "$TMP/CLAUDE.md"
+OUT=$(bash "$HOOKS/session-start.sh")
+check "silent when CLAUDE.md paths are current" "EMPTY" "$OUT"
+rm "$TMP/CLAUDE.md"
 NOW=$(python3 -c 'import datetime; print(datetime.datetime.now().isoformat(timespec="seconds"))')
 for _ in 1 2 3; do
   echo "{\"ts\":\"$NOW\",\"session_id\":\"old\",\"event\":\"PostToolUseFailure\",\"tool\":\"Bash\",\"error\":\"x\"}" >> "$TMP/.harness/logs/tool_calls.jsonl"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uni-harness",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Agent harness kit for Claude Code — installs verification sensors, destructive-command guards, checkpoint recovery, observability logs, and ratchet skills into your project",
   "bin": {
     "uni-harness": "bin/cli.js"