oh-my-harness 0.18.0 → 0.20.0

package/README.md

@@ -2,46 +2,40 @@
 
 # 🐴 oh-my-harness
 
-**Tame your AI coding agents with natural language.**
+**CLAUDE.md is a request. oh-my-harness is enforcement.**
+
+One command turns "TDD enforced, block dangerous commands" into hooks that actually **block** your AI coding agent — for Claude Code, Codex and Pi at once.
 
 [![npm version](https://img.shields.io/npm/v/oh-my-harness.svg)](https://www.npmjs.com/package/oh-my-harness)
 [![npm downloads](https://img.shields.io/npm/dm/oh-my-harness.svg)](https://www.npmjs.com/package/oh-my-harness)
 [![CI](https://github.com/kyu1204/oh-my-harness/actions/workflows/ci.yml/badge.svg)](https://github.com/kyu1204/oh-my-harness/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/github/license/kyu1204/oh-my-harness.svg)](LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue.svg)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
 
-> Stop hand-writing CLAUDE.md files. Describe your project, get enforced guardrails.
+<img src="docs/demo.gif" alt="omh init generates hooks; an AI agent's commit, rm -rf and untested edit are blocked" width="900">
 
 </div>
 
----
-
-## 😤 The Problem
-
-Every AI code agent needs configuration files. Claude Code needs `CLAUDE.md` + hooks. Cursor needs `.cursorrules`. Codex needs `AGENTS.md`. You end up:
+```bash
+npx oh-my-harness init "React + FastAPI, TDD enforced, lint on save"
+```
 
-- 📋 Copy-pasting config files between projects
-- 🔓 Forgetting to set up TDD enforcement hooks
-- 💥 Agents committing code without running tests
-- 🎲 Inconsistent behavior across projects
+That is the whole setup. Your agent now hits a wall when it tries to:
 
-## ✨ The Solution
+| Agent tries to... | Result |
+|---|---|
+| `git commit` while tests fail | ⛔ **Blocked** |
+| edit `src/foo.ts` before touching `foo.test.ts` | ⛔ **Blocked** (TDD guard) |
+| run `rm -rf /`, `chmod -R 777`, or any pattern you list | ⛔ **Blocked** |
+| write into `node_modules/`, `.next/`, `dist/` | ⛔ **Blocked** |
+| commit on a branch already merged to main | ⛔ **Blocked** |
+| save a file | ✅ auto-lint |
+| push a branch | ✅ auto-PR |
 
-```bash
-oh-my-harness init "React + FastAPI fullstack, TDD enforced, lint on save"
-```
+Every decision is logged to `.omh/state/events.jsonl` — `omh stats` shows what your agent tried and what got stopped.
 
-That's it. oh-my-harness generates **enforced guardrails** — not just instructions, but hooks that actually **block** bad behavior:
+## Why not just write CLAUDE.md?
 
-- ❌ Commit without tests passing? **Blocked.**
-- ❌ Edit source without updating tests first? **Blocked.** _(TDD Guard)_
-- ❌ Write to `node_modules/` or `.next/`? **Blocked.**
-- ❌ Run `rm -rf /`? **Blocked.**
-- ❌ Commit on a merged branch? **Blocked.**
-- ✅ Auto-lint on every file save? **Done.**
-- ✅ Auto-create PR after push? **Done.**
-- 📊 Track all hook events for analytics? **Done.**
+Because agents read instructions and then forget them halfway through a long session. A rule in a markdown file is a suggestion; a `PreToolUse` hook that returns `{"decision":"block"}` is a fact. oh-my-harness writes the markdown **and** the hooks, from one `harness.yaml`, and keeps them in sync (`omh sync --check` fails CI when they drift). Side-by-side with rule-sync tools and git hooks: [docs/comparison.md](docs/comparison.md).
 
 ---
 
@@ -64,131 +58,7 @@ omh diff          # Preview what `omh sync` would change
 omh sync --check  # Fail (exit 1) if generated files are out of date — CI gate
 ```
 
-### 🔄 Keeping generated files in sync
-
-`harness.yaml` is the source of truth, so the committed `CLAUDE.md`, hooks, and
-runtime configs can drift if someone edits `harness.yaml` without re-running
-`omh sync`. Three commands keep them honest:
-
-| Command | Use |
-|---------|-----|
-| `omh sync --check` | CI gate — exits non-zero (and lists the files) when generated output is stale, writes nothing |
-| `omh diff` | Human preview of exactly what `omh sync` would change |
-| `omh doctor --strict` | Health check that also fails on drift (plain `omh doctor` warns) |
-
-```yaml
-# .github/workflows/ci.yml
-- run: npx oh-my-harness sync --check   # fails the build if the harness is out of date
-```
-
-The hook manifest records the oh-my-harness version that generated it, so an
-upgrade that changes output is surfaced as a "re-run `omh sync`" hint.
-
-### 📁 What Gets Generated
-
-```text
-~/.omh/
-└── config.json                        # AI provider config (global, not per-project)
-
-your-project/
-├── CLAUDE.md                          # Claude Code instructions (TDD rules, standards)
-├── AGENTS.md                          # Codex CLI instructions (same managed sections)
-├── harness.yaml                       # Your harness config (source of truth)
-├── .omh/                              # Single source of truth — hooks + state
-│   ├── hooks/
-│   │   ├── catalog-branch-guard.sh    # Blocks commits on merged branches
-│   │   ├── catalog-tdd-guard.sh       # Enforces test-first workflow
-│   │   ├── catalog-commit-test-gate.sh # Tests must pass before commit
-│   │   ├── catalog-path-guard.sh      # Protects build outputs
-│   │   ├── catalog-command-guard.sh   # Blocks dangerous commands
-│   │   ├── catalog-lint-on-save.sh    # Auto-lint on save
-│   │   └── catalog-auto-pr.sh         # Auto-create PR after push
-│   ├── state/                         # gitignored — log/runtime data
-│   │   ├── events.jsonl               # Unified hook event log (powers omh stats)
-│   │   └── tdd-edits.json             # TDD guard working state
-│   └── manifest.json                  # Generated-files manifest
-├── .claude/
-│   ├── settings.json                  # Claude permissions + hooks → .omh/hooks/*.sh
-│   └── oh-my-harness.json             # Harness init/sync state
-└── .codex/
-    ├── config.toml                    # [features] hooks = true, goals = true
-    └── hooks.json                     # Codex hooks → .omh/hooks/*.sh (same scripts)
-```
-
----
-
-## ⚙️ How It Works
-
-```text
-  ~/.omh/config.json   ┌─────────────────────┐
-  ┌────────────────┐   │                     │
-  │ • Claude CLI   │──▶│   NL Processing     │◀── "React + FastAPI
-  │ • Claude API   │   │   (describe your    │     TDD enforced"
-  │ • OpenAI API   │   │                     │
-  │ • Gemini API   │   │                     │
-  │ • Codex OAuth  │   │                     │
-  │ • Codex OAuth  │   │                     │
-  │   API          │   └────────┬────────────┘
-  └────────────────┘            │
-   (global AI config)   ┌────────▼────────────┐
-                        │  Project Detector   │  ← Auto-detects language,
-                        │  (14 languages)     │    framework, package manager
-                        └────────┬────────────┘
-                                 │
-                        ┌────────▼────────────┐
-                        │   harness.yaml      │  ← Source of truth
-                        │   (editable, git    │    (hooks + rules)
-                        │    trackable)       │
-                        └────────┬────────────┘
-                                 │
-                  ┌──────────────┼──────────────┐
-                  ▼              ▼              ▼
-            ┌──────────┐  ┌──────────┐  ┌──────────┐
-            │CLAUDE.md │  │  Hooks   │  │settings. │
-            │ (rules)  │  │(enforce) │  │  json    │
-            │          │  │          │  │(perms)   │
-            └──────────┘  └──────────┘  └──────────┘
-```
-
-### 🔍 Project Detector
-
-oh-my-harness automatically detects your project type and injects accurate facts into the LLM prompt:
-
-| Language | Detection | Commands |
-|----------|-----------|----------|
-| 🟦 TypeScript/JS | package.json, tsconfig | pnpm/npm/yarn test, eslint, tsc |
-| 🐍 Python | pyproject.toml, requirements.txt, Pipfile, manage.py, .python-version | pytest, ruff, black, isort, mypy |
-| 🍎 Swift | Package.swift, .xcodeproj | swift test, xcodebuild |
-| 🦀 Rust | Cargo.toml | cargo test, cargo clippy |
-| 🐹 Go | go.mod | go test, golangci-lint |
-| ☕ Java/Kotlin | pom.xml, build.gradle | mvn test, ./gradlew test |
-| 💎 Ruby | Gemfile | bundle exec rspec |
-| 🐘 PHP | composer.json | phpunit |
-| 🎯 Dart/Flutter | pubspec.yaml | dart test, flutter test |
-| ⚡ C/C++ | CMakeLists.txt | cmake, make |
-| 🟣 C#/.NET | *.csproj | dotnet test |
-| 💧 Elixir | mix.exs | mix test |
-| 🔷 Scala | build.sbt | sbt test |
-| ⚡ Zig | build.zig | zig build test |
-
-### 🤖 AI Provider Setup
-
-oh-my-harness supports multiple AI providers for natural language mode:
-
-| Provider | Setup | Available Models | Default |
-|----------|-------|------------------|---------|
-| **Claude CLI** | `claude` command installed | Opus 4.6, Sonnet 4.6, Haiku 4.5 | ✓ |
-| **Claude API** | Set `ANTHROPIC_API_KEY` | Opus 4.6, Sonnet 4.6, Haiku 4.5 | Sonnet 4.6 |
-| **OpenAI API** | Set `OPENAI_API_KEY` | GPT-5.5, GPT-5.4, GPT-5.4-mini, GPT-5.4-nano, GPT-4.1, GPT-4.1-mini, o3, o4-mini | GPT-5.5 |
-| **Gemini API** | Set `GOOGLE_API_KEY` | Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 2.5 Flash Lite, Gemini 3.1 Pro Preview | Gemini 2.5 Pro |
-| **Codex OAuth** | `codex` command installed + `codex login`; runs `codex exec` | GPT-5.5, GPT-5.4, GPT-5.4-mini | GPT-5.5 |
-| **Codex OAuth API** | `omh config` device-code login; imports `~/.codex/auth.json` once if present, then uses `~/.omh` | GPT-5.5, GPT-5.4, GPT-5.4-mini | GPT-5.5 |
-
-Configuration is saved to `~/.omh/config.json` and selected via interactive UI on first use:
-
-```bash
-omh init  # will prompt for AI provider selection and model choice
-```
+📖 Deeper: [what gets generated & CI drift check](docs/generated-files.md) · [how it works, project detector, AI providers](docs/how-it-works.md)
 
 ---
 
@@ -215,6 +85,7 @@ All enforcement is powered by **catalog blocks** — reusable, parameterized hoo
 | 🗜️ `compact-context` | maintenance | Re-injects context on session start |
 | 📋 `config-audit` | audit | Audit trail for config changes |
 | 🔔 `desktop-notify` | ux | Cross-platform desktop notifications |
+| 🔁 `loop-guard` | quality | Blocks a loop session from writing its own work orders or touching architect-only paths |
 
 ### Usage in `harness.yaml`
 
@@ -261,6 +132,12 @@ on a non-blocking block (e.g. `lint-on-save`) is reported and ignored.
 
 ---
 
+## 🔁 Autonomous Loop Engine
+
+Hand omh a `WORKPLAN.md` and it runs one work order per fresh agent session, in an isolated git worktree, with hard-blocked protocol rules. `omh loop start` / `omh loop status` / `omh loop stop`. Full guide: [docs/loop-engine.md](docs/loop-engine.md).
+
+---
+
 ## 🖥️ Commands
 
 ```bash
@@ -288,201 +165,14 @@ omh test                                  # Dry-run verify all hooks
 omh stats                                 # TUI analytics dashboard
 ```
 
-### 🧹 `omh uninstall` — Safe generated-file cleanup
-
-`omh uninstall` removes oh-my-harness generated artifacts while preserving user
-content in merged files.
-
-```bash
-omh uninstall --dry-run
-omh uninstall -y
-omh uninstall -y --purge
-```
-
-Safety behavior:
-
-- Prints the same uninstall plan for dry-run and real execution.
-- Recommends backing up before execution; use `--skip-backup-warning` only for
-  automation that already handles backups.
-- Keeps `harness.yaml` by default; `--purge` removes it.
-- Preserves user content in `CLAUDE.md`, `AGENTS.md`, `.claude/settings.json`,
-  `.codex/hooks.json`, `.codex/config.toml`, and user Pi extensions.
-- Removes only OMH-owned hook commands that point at this project's
-  `.omh/hooks` directory.
-- Warns when `.codex/config.toml` feature flags (`hooks`/`goals`) are removed,
-  because manually-owned feature settings cannot be distinguished from OMH
-  generated settings.
-- Warns that `.codex/config.toml` comments may be lost when TOML is rewritten.
-- Uses backups for modified files and restores them on stop-on-error failures;
-  `--continue-on-error` records failures and keeps applying independent
-  operations.
-
-### 🩺 `omh doctor`
-
-```text
-oh-my-harness: running health checks...
-  ✓ .claude/oh-my-harness.json found
-  ✓ CLAUDE.md exists with intact markers
-  ✓ .claude/settings.json is valid
-  ✓ All hook scripts are executable
-oh-my-harness: all checks passed
-```
-
-### 🧪 `omh test` — Dry-Run Verification
-
-Simulates hook inputs to verify block/allow behavior without entering Claude Code:
-
-```text
-┌  omh test  Harness dry-run verification
-│
-◇  Branch guard
-│    ✓ git commit on feat/my-feature → ALLOWED
-│
-◇  TDD Guard
-│    ✓ src/foo.ts without test → BLOCKED
-│    ✓ tests/unit/foo.test.ts → ALLOWED
-│    ✓ README.md → ALLOWED
-│
-◇  File guards
-│    ✓ node_modules/test-file.js → BLOCKED
-│    ✓ dist/test-file.js → BLOCKED
-│    ✓ src/index.ts → ALLOWED
-│
-◇  Command guards
-│    ✓ "rm -rf /" → BLOCKED
-│    ✓ "npm test" → ALLOWED
-│
-└  14/14 checks passed ✓
-```
-
-### 📊 `omh stats` — TUI Analytics Dashboard
-
-Interactive dashboard powered by [ink](https://github.com/vadimdemedes/ink) with 3 views:
-
-```text
- [1] Overview   [2] Timeline   [3] Blocks          d:filter r:reload q:quit
-
- Active: 8  Events: 1213  Block rate: 2%
-
- branch-guard          ████████████████████ 0b/202a
- tdd-guard             █████████████████████ 14b/68a
- commit-test-gate      ████████████████████ 0b/199a
- path-guard            ████████████████████ 4b/76a
- command-guard         ████████████████████ 4b/202a
-
- Dormant (0 hits):
-   ░ lockfile-guard
-   ░ secret-file-guard
-```
-
-- **Overview** — Active blocks with hit bar charts + dormant block detection
-- **Timeline** — 24-hour heatmap + block rate + peak hour
-- **Blocks** — Scrollable detail view with params, hits, last block reason
-
-Keyboard: `1/2/3` views, `↑/↓` scroll, `d` date filter, `r` reload, `q` quit
-
----
-
-## 📊 Stateful Hook Logging
-
-Every hook invocation is recorded in `.omh/state/events.jsonl`:
-
-```jsonl
-{"ts":"2026-03-18T08:00:00Z","event":"PreToolUse","hook":"catalog-tdd-guard.sh","decision":"block","reason":"TDD — foo.test.* 테스트 파일을 먼저 수정하세요"}
-{"ts":"2026-03-18T08:00:05Z","event":"PreToolUse","hook":"catalog-command-guard.sh","decision":"allow","reason":""}
-```
-
-This powers `omh test` live verification and `omh stats` analytics.
-
----
-
-## 🏗️ Architecture
-
-```text
-oh-my-harness/
-├── bin/                    # CLI entry point
-├── src/
-│   ├── catalog/
-│   │   ├── blocks/         # 17 building block definitions
-│   │   ├── types.ts        # BuildingBlock, HookEntry schemas
-│   │   ├── registry.ts     # Block discovery & search
-│   │   ├── template-engine.ts # Handlebars rendering + applyDefaults
-│   │   └── converter.ts    # HookEntry[] → rendered scripts
-│   ├── cli/
-│   │   ├── commands/       # init, doctor, catalog, hook, sync, test
-│   │   ├── stats/          # TUI dashboard (ink/React)
-│   │   │   ├── App.tsx     # App shell (tab bar, keyboard nav)
-│   │   │   ├── data.ts     # Data aggregation layer
-│   │   │   └── components/ # Overview, Timeline, Blocks views
-│   │   ├── harness-tester.ts  # Hook simulation engine
-│   │   ├── event-logger.ts    # events.jsonl read/write/stats
-│   │   ├── event-verifier.ts  # Event-based verification
-│   │   ├── tui/               # Interactive provider & model selection
-│   │   ├── provider-setup.ts  # Provider configuration UI
-│   │   └── tool-checker.ts    # Command executable checks
-│   ├── core/
-│   │   ├── harness-schema.ts      # harness.yaml Zod schema
-│   │   ├── merged-config.ts       # MergedConfig + HooksConfig interfaces
-│   │   ├── harness-converter-v2.ts # harness.yaml → MergedConfig (catalog pipeline)
-│   │   └── generator.ts           # Orchestrates all generators
-│   ├── generators/
-│   │   ├── claude-md.ts    # CLAUDE.md with idempotent markers
-│   │   ├── hooks.ts        # Hook scripts + event logger injection
-│   │   ├── settings.ts     # .claude/settings.json
-│   │   └── gitignore.ts    # .gitignore updater
-│   ├── detector/
-│   │   ├── project-detector.ts  # Deterministic project detection
-│   │   ├── types.ts             # ProjectFacts, Detector interface
-│   │   └── detectors/           # 14 language detectors
-│   ├── cli/
-│   │   ├── tui/            # Interactive provider & model selection
-│   │   └── provider-setup.ts # Provider configuration UI
-│   └── nl/
-│       ├── provider-registry.ts # Multi-provider definitions
-│       ├── config-store.ts      # ~/.omh/config.json persistence
-│       ├── providers/           # Provider implementations
-│       │   ├── claude-cli.ts
-│       │   ├── claude-api.ts
-│       │   ├── openai-api.ts
-│       │   └── gemini-api.ts
-│       ├── parse-intent.ts      # LLM prompt integration
-│       └── prompt-templates.ts  # NL prompt construction
-└── tests/                  # 900+ tests (unit + integration)
-```
+Details for `uninstall`, `doctor`, `test`, `stats` and hook event logging: [docs/commands.md](docs/commands.md). Internals: [docs/architecture.md](docs/architecture.md) · [roadmap](docs/roadmap.md).
 
 ---
 
 ## 📦 Requirements
 
 - **Node.js** >= 20
-- **Claude CLI** (optional, for default NL mode) — [Install guide](https://docs.anthropic.com/en/docs/claude-code)
-- **API Keys** (optional, for Claude/OpenAI/Gemini API modes) — set `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GOOGLE_API_KEY`
-- **Codex CLI OAuth** (optional, for `codex` CLI-wrapper mode) — install `codex` and run `codex login`
-- **Codex OAuth API** (optional, experimental direct mode) — run `omh config` and choose Codex OAuth API to complete device-code sign-in; credentials are stored under `~/.omh`
-
----
-
-## 🗺️ Roadmap
-
-- [x] `npx oh-my-harness` — zero-install usage
-- [x] `omh sync` — regenerate from harness.yaml
-- [x] Building block catalog — 17 verified hook templates
-- [x] Project detector — 14 language auto-detection
-- [x] `omh test` — dry-run hook verification
-- [x] `omh stats` — TUI analytics dashboard (ink)
-- [x] Stateful hook logging — events.jsonl
-- [x] TDD Guard — enforce test-first workflow
-- [x] Multi-provider AI support — Claude API, OpenAI, Gemini, Codex OAuth
-- [x] Interactive model selection per provider
-- [x] GitHub star prompt — first-time only
-- [x] Codex emitter — `AGENTS.md` + `.codex/hooks.json` + `.codex/config.toml`
-- [x] Unified `.omh/` layout — single source of truth for hooks & state across runtimes
-- [x] Pi ([pi.dev](https://pi.dev)) emitter — bridge extension (`.pi/extensions/omh-harness.ts`) reusing the same `.omh/hooks/*.sh`
-- [x] `ask` mode — request approval before executing risky tools (Claude native prompt / Pi `ctx.ui.select`; Codex falls back to block)
-- [x] `omh uninstall` — remove generated artifacts while preserving user content
-- [x] `omh config` — view, reconfigure, or reset the saved AI provider (rotate expired keys, switch provider/model)
-- [ ] Community harness.yaml registry — share and reuse configs
-- [ ] `omh modify "change X"` — NL config editing
+- **An AI provider** (optional, only for natural-language `omh init`) — any one of: the `claude` CLI, an API key for Claude/OpenAI/Gemini/OpenRouter, a ChatGPT subscription via Codex, or a local OpenAI-compatible server (Ollama etc.). See [AI Provider Setup](docs/how-it-works.md#-ai-provider-setup).
 
 ---
 

package/dist/catalog/blocks/index.js

@@ -15,6 +15,7 @@ import { desktopNotify } from "./desktop-notify.js";
 import { configAudit } from "./config-audit.js";
 import { compactContext } from "./compact-context.js";
 import { worktreeSetup } from "./worktree-setup.js";
+import { loopGuard } from "./loop-guard.js";
 export const builtinBlocks = [
     branchGuard,
     commitTestGate,
@@ -33,4 +34,5 @@ export const builtinBlocks = [
     configAudit,
     compactContext,
     worktreeSetup,
+    loopGuard,
 ];

package/dist/catalog/blocks/loop-guard.d.ts

@@ -0,0 +1,10 @@
+import type { BuildingBlock } from "../types.js";
+/**
+ * Enforces the loop protocol's two deterministic bans as hard blocks instead
+ * of prose. Both have been violated in practice when they lived only in a
+ * ledger: a loop that writes its own work order and then implements it is
+ * approving itself, and architect-only files are exactly the ones a loop
+ * mis-diagnoses. Fires only in loop sessions — the runner exports OMH_LOOP=1,
+ * so the architect's own session is never blocked.
+ */
+export declare const loopGuard: BuildingBlock;

package/dist/catalog/blocks/loop-guard.js

@@ -0,0 +1,120 @@
+/**
+ * Enforces the loop protocol's two deterministic bans as hard blocks instead
+ * of prose. Both have been violated in practice when they lived only in a
+ * ledger: a loop that writes its own work order and then implements it is
+ * approving itself, and architect-only files are exactly the ones a loop
+ * mis-diagnoses. Fires only in loop sessions — the runner exports OMH_LOOP=1,
+ * so the architect's own session is never blocked.
+ */
+export const loopGuard = {
+    id: "loop-guard",
+    name: "Loop Guard",
+    description: "Blocks a loop session from writing its own work orders or touching architect-only paths",
+    category: "quality",
+    event: "PreToolUse",
+    matcher: "Edit|Write|Bash",
+    canBlock: true,
+    params: [
+        {
+            name: "workOrders",
+            type: "string",
+            description: "Work-order directory the loop must never write into",
+            required: false,
+            default: "docs/work-orders",
+        },
+        {
+            name: "architectOnly",
+            type: "string[]",
+            description: "Path prefixes only the architect may edit",
+            required: false,
+            default: [],
+        },
+    ],
+    template: `#!/bin/bash
+set -euo pipefail
+INPUT=$(cat)
+
+# Architect sessions pass through untouched; only the runner exports this.
+[[ "\${OMH_LOOP:-}" != "1" ]] && exit 0
+
+TOOL_NAME=$(echo "\$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+FILE_PATH=$(echo "\$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
+COMMAND=$(echo "\$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+# Codex apply_patch ships the whole patch in tool_input.command and names the
+# files in "*** {Add|Update|Delete} File: <path>" headers. Collect those
+# paths and treat them like file_path; the Bash write heuristic must NOT run
+# over patch text (it would fire on words inside the diff).
+PATCH_PATHS=()
+if [[ "\$TOOL_NAME" == "apply_patch" && -n "\$COMMAND" ]]; then
+  while IFS= read -r _p; do
+    _p="\${_p%$'\\r'}"
+    [[ -n "\$_p" ]] && PATCH_PATHS+=("\$_p")
+  done < <(printf '%s\\n' "\$COMMAND" | sed -nE 's/^\\*\\*\\* ((Add|Update|Delete) File|Move to): (.+)$/\\3/p')
+  COMMAND=""
+fi
+[[ -z "\$FILE_PATH" && -z "\$COMMAND" && \${#PATCH_PATHS[@]} -eq 0 ]] && exit 0
+
+# Component-boundary matching: wrap both sides in slashes so 'ios' matches
+# ios/App.swift and /repo/ios/... but never src/kiosk.ts.
+_omh_path_under() {
+  local file="/\$1/" prefix="\${2%/}"
+  [[ "\$file" == *"/\$prefix/"* ]]
+}
+
+# Bash coverage: a shell command that mentions a protected path AND carries a
+# write indicator is blocked. Reads (cat/grep of a work order) pass.
+# ponytail: substring heuristic — a command writing elsewhere while merely
+# mentioning a protected path is over-blocked; tighten to arg-level parsing if
+# that ever bites. This guards a drifting loop, not a malicious one — evasion
+# via split cd chains, variable indirection, pushd, or symlinks is explicitly
+# out of scope: winning that arms race needs a filesystem sandbox, not a hook.
+_omh_bash_writes_to() {
+  local cmd="\$1" target="\${2%/}"
+  [[ -z "\$cmd" || -z "\$target" ]] && return 1
+  [[ "\$cmd" == *"\$target"* ]] || return 1
+  # The path is interpolated into an ERE below: escape its metacharacters so
+  # "docs/[orders" cannot break the pattern (grep error = silent bypass) and
+  # "docs/o+rders" is compared literally.
+  target=$(printf '%s' "\$target" | sed -e 's/[][\\.*^$(){}?+|]/\\\\&/g')
+  local WRITE_OPS='(tee|mv|cp|rm|touch|truncate|sed[[:space:]]+-i[^[:space:]]*)'
+  # write op targeting the protected path directly ...
+  echo "\$cmd" | grep -qE '(>|>>)[[:space:]]*[^|&;]*'"\$target"'|(^|[^[:alnum:]_])'"\$WRITE_OPS"'[[:space:]][^|&;]*'"\$target" && return 0
+  # ... or a cd into it followed by any write op (relative paths escape the
+  # direct pattern once the cwd is inside the protected directory)
+  echo "\$cmd" | grep -qE '(^|[^[:alnum:]_])cd[[:space:]][^|&;]*'"\$target" \\
+    && echo "\$cmd" | grep -qE '>|(^|[^[:alnum:]_])'"\$WRITE_OPS"'[[:space:]]' 
+}
+
+# Any path a tool call names: the direct file_path plus apply_patch headers.
+_omh_any_path_under() {
+  local prefix="\$1" f
+  [[ -n "\$FILE_PATH" ]] && _omh_path_under "\$FILE_PATH" "\$prefix" && return 0
+  for f in "\${PATCH_PATHS[@]+"\${PATCH_PATHS[@]}"}"; do
+    _omh_path_under "\$f" "\$prefix" && return 0
+  done
+  return 1
+}
+
+WORK_ORDERS='{{{workOrders}}}'
+if _omh_any_path_under "\$WORK_ORDERS" || _omh_bash_writes_to "\$COMMAND" "\$WORK_ORDERS"; then
+  REASON="oh-my-harness: loop-guard — the loop must not write its own work orders. Mark the task 'BLOCKED: no work order' and move on; the architect writes work orders."
+  _log_event "block" "\$REASON"
+  _emit_decision "block" "\$REASON"
+  exit 0
+fi
+
+ARCHITECT_ONLY=({{#each architectOnly}}"{{{this}}}" {{/each}})
+for prefix in "\${ARCHITECT_ONLY[@]+"\${ARCHITECT_ONLY[@]}"}"; do
+  [[ -z "\$prefix" ]] && continue
+  if _omh_any_path_under "\$prefix" || _omh_bash_writes_to "\$COMMAND" "\$prefix"; then
+    REASON="oh-my-harness: loop-guard — \$prefix is architect-only. Mark the task 'BLOCKED: architect-only path' and move on."
+    _log_event "block" "\$REASON"
+    _emit_decision "block" "\$REASON"
+    exit 0
+  fi
+done
+
+exit 0`,
+    tags: ["loop", "autonomous", "quality", "guardrail"],
+};

package/dist/catalog/blocks/tdd-guard.js

@@ -63,7 +63,7 @@ fi
 # 대응 테스트 파일 확인 — 확장자 제거
 BASENAME=$(basename "\$FILE_PATH" | sed -E 's/\\.[^.]+$//')
 
-REASON="oh-my-harness: TDD — \${BASENAME} 에 대응하는 테스트 파일을 먼저 수정하세요"
+REASON="oh-my-harness: TDD guard — edit the test for \${BASENAME} first, then the source"
 if [[ ! -f "\$HISTORY_FILE" ]]; then
   _log_event "block" "\$REASON"
   _emit_decision "block" "\$REASON"

package/dist/cli/commands/config.js

@@ -7,7 +7,9 @@ function printSummary(config) {
     console.log(`  method:   ${chalk.cyan(config.method)}`);
     if (config.method === "api") {
         console.log(`  model:    ${chalk.cyan(config.model ?? "(default)")}`);
-        console.log(`  api key:  ${chalk.dim(maskApiKey(config.apiKey))}`);
+        if (config.baseUrl)
+            console.log(`  base url: ${chalk.cyan(config.baseUrl)}`);
+        console.log(`  api key:  ${chalk.dim(config.apiKey ? maskApiKey(config.apiKey) : "(none)")}`);
     }
     else if (config.method === "oauth") {
         console.log(`  model:    ${chalk.cyan(config.model ?? "(default)")}`);
@@ -72,10 +74,17 @@ export async function configCommand(options = {}) {
         console.log(chalk.green("Removed ~/.omh/config.json"));
         return { exitCode: 0 };
     }
-    // Default: show current config (if any), then reconfigure.
+    // Default: show current config, then ask before launching setup so a plain
+    // `omh config` is a safe read; `--yes` skips the prompt.
     if (existing) {
         printSummary(existing);
         console.log("");
+        if (!options.yes) {
+            const confirm = options.confirm ?? defaultConfirm;
+            const ok = await confirm("Reconfigure the AI provider?");
+            if (!ok)
+                return { exitCode: 0 };
+        }
     }
     else {
         console.log("No AI provider configured yet. Let's set one up.\n");

package/dist/cli/commands/loop.d.ts

@@ -0,0 +1,54 @@
+import type { LoopConfig } from "../../core/merged-config.js";
+import type { LivenessDeps } from "../../loop/state.js";
+import { stopLoop } from "../../loop/stop.js";
+import type { SupervisorExit } from "../../loop/supervisor.js";
+/**
+ * `omh loop` — the user-facing (and skill-facing) entry points to the
+ * supervisor in src/loop. `start` launches `run` detached; everything else
+ * reads or signals the state that `run` maintains.
+ */
+export interface LoopResult {
+    exitCode: number;
+}
+/** The subset of ChildProcess that start relies on; injectable for tests. */
+export interface ChildLike {
+    pid?: number;
+    exitCode: number | null;
+    unref(): void;
+    once(event: "exit", cb: (code: number | null) => void): unknown;
+}
+export type SpawnLike = (cmd: string, args: string[], opts: Record<string, unknown>) => ChildLike;
+export interface LoopStartOptions extends LivenessDeps {
+    projectDir?: string;
+    spawnImpl?: SpawnLike;
+    platform?: NodeJS.Platform;
+    /** How long to wait for the supervisor to acquire the run. */
+    acquireTimeoutMs?: number;
+}
+export declare function loopStartCommand(options?: LoopStartOptions): Promise<LoopResult>;
+export interface LoopRunOptions {
+    projectDir?: string;
+    runId: string;
+    supervisorImpl?: (o: {
+        projectDir: string;
+        cfg: LoopConfig;
+        runId: string;
+    }) => Promise<SupervisorExit>;
+    sweepImpl?: () => void;
+}
+export declare function loopRunCommand(options: LoopRunOptions): Promise<LoopResult>;
+export interface LoopStopOptions {
+    projectDir?: string;
+    now?: boolean;
+    stopImpl?: typeof stopLoop;
+}
+export declare function loopStopCommand(options?: LoopStopOptions): Promise<LoopResult>;
+export interface LoopStatusOptions extends LivenessDeps {
+    projectDir?: string;
+}
+export declare function loopStatusCommand(options?: LoopStatusOptions): Promise<LoopResult>;
+export interface LoopCleanOptions {
+    projectDir?: string;
+    branch?: boolean;
+}
+export declare function loopCleanCommand(options?: LoopCleanOptions): Promise<LoopResult>;