uni-harness 0.2.1 → 0.4.0

package/.claude/skills/harness-init/SKILL.md

@@ -95,7 +95,11 @@ before and tell them to re-run /harness-init once code exists.
 - Show everything as a diff and get user approval:
   1. The PROJECT section of CLAUDE.md (PROJECT/LANGUAGE/BUILD/TEST/LINT)
   2. LINT_CMD / TEST_CMD in `.harness/commands.env` (identical to PROJECT)
-  3. Initial RULES / ANTI-PATTERNS entries (if any)
+  3. The Commands section of AGENTS.md (mirror of PROJECT — this is what
+     non-Claude tools like Codex/Cursor/Aider read; if the project already
+     had its own AGENTS.md, propose appending the harness quick-contract
+     instead of replacing anything)
+  4. Initial RULES / ANTI-PATTERNS entries (if any)
 - Write only what was approved. Afterwards, run TEST_CMD once more to
   confirm the sensor configuration points at a command that really runs.
 

package/.claude/skills/ratchet/SKILL.md

@@ -44,6 +44,13 @@ Handle one mistake end-to-end:
 | Quality drift | declared done without verification | strengthen sensor (TEST_CMD scope) |
 | Lost state | repeated already-completed steps | strengthen checkpoint protocol |
 | Runaway/cost blowup | tool-call surge, same-error loop | adjust tripwire thresholds |
+| Step repetition | same command/edit repeated with no progress between | tripwire threshold or trace rule |
+| Spec deviation | did work the task never asked for (scope creep, unrequested refactor) | CLAUDE.md guide entry |
+| Premature completion | declared done while a required step never ran | trace rule (`require-before-stop`) |
+
+(The last three classes come from the MAST failure taxonomy,
+arXiv:2503.13657 — they recur across agent systems, so classify against
+them before inventing a new class.)
 
 ## Proposal Format
 
@@ -51,11 +58,35 @@ Handle one mistake end-to-end:
 - Guard pattern → the regex to add to DENY_PATTERNS in guard-pre-bash.sh
 - Permission → the allow/ask/deny change for settings.json permissions
 - Sensor → commands.env change or file-extension additions in sensor-post-edit.sh
+- Trace rule → a `require-before-stop` line for `.harness/trace.rules`
+  (format: `require-before-stop <marker-regex> <message>` — stop-gate.sh
+  blocks the stop if no logged tool call this session matched the regex)
 
 With each proposal, include: (1) the failure class it prevents,
 (2) possible side effects (over-blocking etc.), (3) overlap/conflict with
 existing rules.
 
+## Falsifiable Contract (predictions.jsonl)
+
+Every proposal ships with a **machine-checkable prediction** — the claim
+that makes the rule falsifiable instead of decorative. When the user
+approves and the fix is applied, append one line to
+`.harness/state/predictions.jsonl`:
+
+```json
+{"ts": "<today ISO date>", "rule": "<short rule summary>",
+ "class": "<failure class>", "predict_absent": "<substring/regex that
+ matched the original failure in tool_calls.jsonl>",
+ "baseline_count": <how many times it fired in the last 30 days>,
+ "window_days": 30}
+```
+
+`/guide-audit` later counts `predict_absent` matches in the logs after
+`ts`. Zero matches inside the window = the rule demonstrably worked;
+matches at or near baseline = the rule failed its contract and becomes a
+delete/rewrite candidate. A proposal you cannot attach a prediction to is
+a smell — say so explicitly rather than inventing an untestable one.
+
 ## Approval and Cleanup
 
 - Apply only what the user approves.

package/AGENTS.md

@@ -0,0 +1,26 @@
+# Agent Instructions
+
+This project's canonical agent guide is **CLAUDE.md**, maintained by the
+uni-harness kit — commands, rules, anti-patterns, work-loop and checkpoint
+protocols all live there. Read CLAUDE.md and follow it.
+
+## Commands
+
+(filled by /harness-init — mirrors the PROJECT section of CLAUDE.md)
+
+## Quick contract for any coding agent working here
+
+- Run the TEST command after modifying code. Never report work as done
+  with failing tests, and never weaken a test (skip/only/deleted cases,
+  trivially-true assertions) to make it pass.
+- Do not modify `.claude/**`, `.harness/**`, `.github/**`, `.env*`, or
+  `*.config.*` files without explicit user approval — especially changes
+  that would weaken tests, lint, or guards.
+- After 3 failed attempts at the same goal, stop and escalate: what
+  decision is needed, what was tried, the cost of waiting, and the safest
+  default action.
+- Keep durable working state in `.harness/state/` (plan.md,
+  progress.json, decisions.jsonl), not in scattered notes.
+
+Keep this file in sync with CLAUDE.md (in Claude Code, /harness-init
+maintains both).

package/README.ja.md

@@ -0,0 +1,221 @@
+# 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` | プロジェクトのコマンド、ルール、アンチパターン、ワークループとチェックポイントのプロトコル |
+| `AGENTS.md` | ルールのクロスツール・ミラー — Codex、Cursor、Aider、Gemini CLI など20以上のツールが読み取る |
+| `.claude/settings.json` | フック登録 |
+| `.claude/hooks/sensor-post-edit.sh` | コード編集のたびに即座にリントを実行し、失敗をフィードバック |
+| `.claude/hooks/stop-gate.sh` | ターン終了時にテストを一括実行。失敗状態での終了をブロック（セッションあたり3回上限、超過でエスカレーション要求）。任意のトレースルール（`.harness/trace.rules`: 「ターン終了前に必ず X が起きていること」）も強制 |
+| `.claude/hooks/guard-pre-bash.sh` | 破壊的コマンドと検証バイパス（`--no-verify`）を実行前にブロック。テストが一度も通っていない編集をコミットしようとするとユーザーに確認 |
+| `.claude/hooks/guard-pre-edit.sh` | アンチゲーミング・ゲート: テストを弱める編集（skip/only マーカー、テスト削除、アサーションの骨抜き）と設定/ハーネスファイルの変更にユーザー承認を要求 |
+| `.claude/hooks/pre-compact.sh` | コンテキスト圧縮の直前にチェックポイントをスナップショット。再開時のチェックポイント更新指示は `session-start.sh` が担当 |
+| `.claude/hooks/session-start.sh` | セッション開始/再開/圧縮時に進行中チェックポイントを再注入。失敗が蓄積すると `/ratchet` を提案 |
+| `.claude/hooks/session-end.sh` | セッションごとに台帳1行を記録（所要時間、呼び出し/失敗/編集数、終了ブロック回数、テスト状態）→ `sessions.jsonl` |
+| `.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 [ミス]` | 再現 → 分類 → ルール/センサー/権限を提案 → 検証（引数なし: ログ診断）。全提案に反証可能な予測（`predictions.jsonl`）を添付 |
+| `/guide-audit` | CLAUDE.md ルールの監査 — 維持 / 削除 / センサー化（月次）。過去の予測をログと照合検証し、効かなかったルールは証拠に基づいて削除 |
+| `/distill [成功]` | 成功側のラチェット: 完了したタスクをログから発掘し、再利用可能なプロジェクトスキルとして提案 |
+
+## 推奨パーミッション（任意）
+
+キットはパーミッションポリシーを強制しません。無人運用や高自律
+モードで使うなら、プロジェクトの `.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` を実行。
+- **意味のある成功のあと:** 繰り返す手順なら `/distill` で
+  プロジェクトスキルにしてください。
+- **毎月:** `/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,215 @@
+# 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` | 프로젝트 명령, 규칙, 안티패턴, 작업 루프·체크포인트 프로토콜 |
+| `AGENTS.md` | 규칙의 크로스툴 미러 — Codex, Cursor, Aider, Gemini CLI 등 20+ 도구가 읽음 |
+| `.claude/settings.json` | 훅 등록 |
+| `.claude/hooks/sensor-post-edit.sh` | 코드 수정 즉시 lint 실행, 실패를 피드백 |
+| `.claude/hooks/stop-gate.sh` | 턴 종료 시 테스트 일괄 실행; 실패 상태의 종료를 차단 (세션당 3회 상한, 초과 시 에스컬레이션 강제); 선택적 트레이스 규칙(`.harness/trace.rules`: "턴이 끝나기 전 반드시 X가 있었어야 함") 집행 |
+| `.claude/hooks/guard-pre-bash.sh` | 파괴적 명령과 검증 우회(`--no-verify`)를 실행 전 차단; 테스트가 한 번도 통과하지 않은 편집을 커밋하려 하면 사용자에게 확인 |
+| `.claude/hooks/guard-pre-edit.sh` | 안티게이밍 게이트: 테스트 약화 편집(skip/only 마커, 테스트 삭제, 단언 무력화)과 설정/하네스 파일 변경에 사용자 승인 요구 |
+| `.claude/hooks/pre-compact.sh` | 컨텍스트 압축 직전 체크포인트 스냅샷; 재개 시 체크포인트 갱신 지시는 `session-start.sh`가 담당 |
+| `.claude/hooks/session-start.sh` | 세션 시작/재개/압축 시 진행 중 체크포인트 재주입; 실패 누적 시 `/ratchet` 제안 |
+| `.claude/hooks/session-end.sh` | 세션당 원장(ledger) 한 줄 기록 (소요 시간, 호출/실패/편집 수, 종료 차단 횟수, 테스트 상태) → `sessions.jsonl` |
+| `.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 [실수]` | 재현 → 분류 → 규칙/센서/권한 제안 → 검증 (인자 없이: 로그 진단). 모든 제안에 반증 가능한 예측(`predictions.jsonl`)을 첨부 |
+| `/guide-audit` | CLAUDE.md 규칙 감사 — 유지 / 삭제 / 센서 전환 (월 1회); 과거 예측을 로그와 대조 검증해 안 통한 규칙은 증거로 삭제 |
+| `/distill [성공]` | 성공 쪽 래칫: 완료된 작업을 로그에서 발굴해 재사용 가능한 프로젝트 스킬로 제안 |
+
+## 권장 권한 설정 (선택)
+
+킷은 권한 정책을 강제하지 않습니다. 무인 실행이나 고자율 모드로 쓴다면
+프로젝트의 `.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` 실행.
+- **의미 있는 성공 후:** 반복될 절차라면 `/distill`로 프로젝트 스킬로
+  만드세요.
+- **매월:** `/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)
@@ -50,11 +52,15 @@ anything you've customized is skipped (listed, with `--force` to override).
 | File | Role |
 |---|---|
 | `CLAUDE.md` | Project commands, rules, anti-patterns, work-loop and checkpoint protocols |
+| `AGENTS.md` | Cross-tool mirror of the rules — read by Codex, Cursor, Aider, Gemini CLI and 20+ other tools |
 | `.claude/settings.json` | Hook registration |
 | `.claude/hooks/sensor-post-edit.sh` | Runs lint immediately on code edits, feeds failures back |
-| `.claude/hooks/stop-gate.sh` | Runs tests in batch at turn end; blocks stopping on failure (3-per-session cap, then demands escalation) |
-| `.claude/hooks/guard-pre-bash.sh` | Blocks destructive commands and verification bypasses (`--no-verify`) before execution |
+| `.claude/hooks/stop-gate.sh` | Runs tests in batch at turn end; blocks stopping on failure (3-per-session cap, then demands escalation); enforces optional trace rules (`.harness/trace.rules`: "step X must have happened before the turn ends") |
+| `.claude/hooks/guard-pre-bash.sh` | Blocks destructive commands and verification bypasses (`--no-verify`) before execution; asks before a `git commit` that would land edits no test run has seen |
+| `.claude/hooks/guard-pre-edit.sh` | Anti-gaming gate: test-weakening edits (skip/only markers, deleted tests, gutted assertions) and config/harness file changes require user approval |
+| `.claude/hooks/pre-compact.sh` | Snapshots checkpoints just before context compaction; `session-start.sh` then instructs a checkpoint refresh when the session resumes |
 | `.claude/hooks/session-start.sh` | Re-injects in-progress checkpoints at session start/resume/compaction; nudges `/ratchet` when failures pile up |
+| `.claude/hooks/session-end.sh` | Writes one ledger row per session (duration, calls, failures, edits, stop blocks, test state) to `sessions.jsonl` |
 | `.claude/hooks/observe-log.sh` | Logs every tool call as JSONL + tripwires (same failure 3x, call surge) |
 | `harness/harness_report.py` | Health scorecard from the logs |
 | `harness/tests/` | Self-tests for the hooks and the installer |
@@ -66,8 +72,9 @@ Skills:
 |---|---|
 | `/harness-init` | Scan the repo → fill PROJECT section & commands.env (once, at install) |
 | `/checkpoint` | Save state to `.harness/state/` (plan.md / decisions.jsonl / progress.json) |
-| `/ratchet [mistake]` | Reproduce → classify → propose rule/sensor/permission → verify (no args: diagnose the logs) |
-| `/guide-audit` | Audit CLAUDE.md rules — keep / delete / convert-to-sensor (monthly) |
+| `/ratchet [mistake]` | Reproduce → classify → propose rule/sensor/permission → verify (no args: diagnose the logs). Every proposal ships a falsifiable prediction (`predictions.jsonl`) |
+| `/guide-audit` | Audit CLAUDE.md rules — keep / delete / convert-to-sensor (monthly); verifies past predictions against the logs, so rules that didn't work get deleted on evidence |
+| `/distill [success]` | The success-side ratchet: mine a completed task from the logs and propose a reusable project skill |
 
 ## Recommended Permissions (optional)
 
@@ -101,8 +108,12 @@ from editing its own harness:
   3x → rule; same rule violated 3x → promote to a guard/permission.
 - **Weekly:** check the scorecard with `python3 harness/harness_report.py`;
   if repeated failures show up, run `/ratchet`.
+- **After a nontrivial success:** if the procedure will recur, run
+  `/distill` to turn it into a project skill.
 - **Monthly:** audit CLAUDE.md with `/guide-audit` — delete rules the
-  sensors now enforce, merge contradictions.
+  sensors now enforce, merge contradictions, and check each rule's
+  prediction against the logs (a rule whose failure kept happening is
+  deleted or promoted on numbers, not vibes).
 
 ## Customizing