oh-my-harness 0.22.0 → 0.24.0

package/README.md

@@ -33,7 +33,7 @@ That is the whole setup. Your agent now hits a wall when it tries to:
 | save a file | ✅ auto-lint |
 | push a branch | ✅ auto-PR |
 
-Every decision is logged to `.omh/state/events.jsonl` — `omh stats` shows what your agent tried and what got stopped.
+Every decision is logged to `.omh/state/events.jsonl` — `omh stats` shows what your agent tried and what got stopped, and `omh explain` tells you in plain language why the last few calls were blocked and how to allow once or change the rule.
 
 ## Why not just write CLAUDE.md?
 
@@ -66,7 +66,44 @@ omh diff          # Preview what `omh sync` would change
 omh sync --check  # Fail (exit 1) if generated files are out of date — CI gate
 ```
 
-📖 Deeper: [what gets generated & CI drift check](docs/generated-files.md) · [how it works, project detector, AI providers](docs/how-it-works.md)
+📖 Deeper: [what gets generated & CI drift check](docs/generated-files.md) · [how it works, project detector, presets & Jev, AI providers](docs/how-it-works.md)
+
+---
+
+## 🎛️ Presets and the Jev chooser
+
+You do not need a chat model to set up a harness.
+
+**Presets** are deterministic and offline. The project detector fills in test, lint and typecheck commands and build directories; rule text is templated; a block whose required parameter cannot be detected is left out rather than half-configured.
+
+| Preset | What it enables |
+|--------|-----------------|
+| `minimal` | dangerous-command guard, main-branch guard, build-output guard |
+| `safe` | minimal + tests and typecheck must pass before a commit, lockfile and secret-file guards, lint on save |
+| `strict` | safe + test-first (TDD) on every source edit |
+
+```bash
+omh init --preset safe        # confirm prompt; add -y to skip it
+```
+
+**Jev** picks the blocks for you from a description. [Jev](https://docs.typesafe.ai/introduction) is TypeSafe's System One model: it does not generate text, it answers typed questions with calibrated probabilities. `omh init "description"` sends the description plus the detector facts and asks, in one call, "should block X be enabled?" for every selectable block and "how strict?" once. Probabilities at or above 0.65 enable a block, at or below 0.35 disable it, anything in between keeps the preset default. Rule text and free-form params never come from the model.
+
+```bash
+export TYPESAFE_API_KEY=...   # or put it in the project's .env
+omh init "Next.js + FastAPI, TDD enforced, no auto PRs"
+# Jev (jev-latest) chose: strictness=strict, 1716 input tokens
+#   enabled:   ... tdd-guard, sql-guard ...
+#   disabled:  auto-pr
+```
+
+- Get a key from the [TypeSafe console](https://typesafe.ai) (early access at the time of writing). One init costs a fraction of a cent (input $0.042 per million tokens, output free) and takes about half a second.
+- `--preset` always wins and never calls Jev. No key and no LLM provider? `omh init "description"` falls back to `safe` and says so.
+- `omh doctor` and `omh config --show` tell you whether the chooser is active. Remove the key to go back to the LLM providers or presets.
+- `omh modify "..."` later edits the same way: Jev answers enable / disable / ask / keep per block, you confirm the change set, `omh sync` runs. Mark an entry `locked: true` in harness.yaml and modify will refuse to remove or weaken it.
+- Interactive `omh init` offers both: "Describe your project (Jev picks the blocks)" and "Use a preset (no AI)".
+- Descriptions in English work best; other languages are handled but with lower confidence, so include the specifics.
+
+The always-on guards (harness self-protection, `--no-verify`, force-push) are added to every preset and every Jev result.
 
 ---
 
@@ -83,6 +120,8 @@ All enforcement is powered by **catalog blocks** — reusable, parameterized hoo
 | 🪝 `harness-guard` | security | Blocks shell writes to the harness's own hooks and config (always on) |
 | 🚫 `no-verify-guard` | git | Blocks `--no-verify` / `-n` / hooksPath overrides on commit and push (always on) |
 | 💥 `force-push-guard` | git | Blocks force pushes to protected branches (always on) |
+| 🛑 `stop-test-gate` | quality | When the agent tries to end its turn with failing tests, sends it back (retry-capped) |
+| 📝 `stop-uncommitted-warn` | git | Lists uncommitted changes as a system message when the turn ends |
 | 📁 `path-guard` | file-protection | Blocks writes to protected paths |
 | 🔐 `lockfile-guard` | file-protection | Prevents manual lockfile edits |
 | 🤫 `secret-file-guard` | security | Blocks edits to .env, credentials |
@@ -155,6 +194,8 @@ Hand omh a `WORKPLAN.md` and it runs one work order per fresh agent session, in
 # 🚀 Initialize
 omh init "your project description"      # Jev with TYPESAFE_API_KEY, else an LLM provider, else the "safe" preset
 omh init --preset strict                  # No provider: minimal | safe | strict
+omh explain                               # Why were the last tool calls blocked, and what to do about it
+omh modify "no auto PRs, TDD guard asks"  # Edit harness.yaml from a sentence (Jev decides per block; locked: true entries stay)
 omh init                                  # Interactive TUI (import existing harness.yaml)
 
 # 📋 Catalog

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

@@ -10,12 +10,46 @@ export const branchGuard = {
         { name: "mainBranch", type: "string", description: "Main branch name", default: "main", required: false },
     ],
     tags: ["git", "branch", "merge", "guard"],
+    explain: {
+        allowOnce: "create a feature branch (git switch -c feat/x) and commit there",
+        change: "harness.yaml > hooks > branch-guard > params.mainBranch, or remove the hook, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 if _omh_cmd_matches "$COMMAND" git commit || _omh_cmd_matches "$COMMAND" git push; then
-  BRANCH=$(git branch --show-current 2>/dev/null)
+  # Where does the commit/push run? Follow cd / pushd and git -C (#133). A repo
+  # outside this project is not ours to guard; an unresolvable cwd is treated
+  # as the project itself (fail closed).
+  GIT_CWD=$(_omh_simple_commands "$COMMAND" | awk -F '\\t' -v root="$_OMH_PROJECT_ROOT" -v home="\${HOME:-}" "\${_OMH_AWK_PATHLIB}"'
+    BEGIN { cwd = root }
+    found != "" { next }
+    { i = 1
+      while (i <= NF && $i ~ /^[A-Za-z_][A-Za-z0-9_]*=/) i++
+      if (i <= NF && ($i == "sudo" || $i == "doas")) { i++; while (i <= NF && $i ~ /^-/) i++ }
+      if (i > NF) next
+      if ($i == "cd" || $i == "pushd" || $i == "popd") { cwd = omh_cd_cmd(cwd, i, home); next }
+      if ($i != "git") next
+      c = cwd; ex = 0; j = i + 1
+      while (j <= NF && $j ~ /^-/) {
+        if ($j == "-C") { if ($(j + 1) ~ /^\\//) ex = 1; c = omh_cd(c, $(j + 1), home); j++ }
+        else if ($j == "-c") j++
+        j++
+      }
+      if (j <= NF && ($j == "commit" || $j == "push")) { found = c; explicit = ex } }
+    END { print found "\\t" explicit }')
+  GIT_EXPLICIT="\${GIT_CWD#*	}"; GIT_CWD="\${GIT_CWD%%	*}"
+  [[ "$GIT_CWD" == "?" || -z "$GIT_CWD" ]] && GIT_CWD="$_OMH_PROJECT_ROOT"
+  # ';' / newline chaining: a failed cd would leave the commit in this project, so judge it
+  # here, unless the target came from an explicit absolute git -C.
+  [[ "$(_omh_seq_unsafe "$COMMAND")" == "1" && "$GIT_EXPLICIT" != "1" ]] && GIT_CWD="$_OMH_PROJECT_ROOT"
+  case "$GIT_CWD" in
+    "$_OMH_PROJECT_ROOT"|"$_OMH_PROJECT_ROOT"/*) ;;
+    *) exit 0 ;;
+  esac
+  # A subdirectory of the project is the same repository; if it does not exist yet, ask the root.
+  BRANCH=$(git -C "$GIT_CWD" branch --show-current 2>/dev/null || git -C "$_OMH_PROJECT_ROOT" branch --show-current 2>/dev/null)
   [[ -z "$BRANCH" ]] && exit 0
   MAIN='{{mainBranch}}'
   if [[ "$BRANCH" == "$MAIN" ]] || [[ "$BRANCH" == "master" && "$MAIN" == "main" ]]; then
@@ -32,8 +66,8 @@ if _omh_cmd_matches "$COMMAND" git commit || _omh_cmd_matches "$COMMAND" git pus
     fi
   fi
   if [[ "$MERGED" -eq 0 ]]; then
-    git fetch origin "$MAIN" --quiet >/dev/null 2>&1 || true
-    if git branch -r --merged "origin/$MAIN" 2>/dev/null | grep -qE "origin/\${BRANCH}$"; then
+    git -C "$GIT_CWD" fetch origin "$MAIN" --quiet >/dev/null 2>&1 || true
+    if git -C "$GIT_CWD" branch -r --merged "origin/$MAIN" 2>/dev/null | grep -qE "origin/\${BRANCH}$"; then
       MERGED=1
     fi
   fi

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

@@ -16,6 +16,10 @@ export const commandGuard = {
         },
     ],
     tags: ["security", "bash", "guard", "dangerous"],
+    explain: {
+        allowOnce: "rewrite the command without the blocked pattern (a narrower path, no sudo, no -R 777)",
+        change: "harness.yaml > hooks > command-guard > params.patterns: remove or edit the pattern, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

package/dist/catalog/blocks/commit-test-gate.js

@@ -17,13 +17,21 @@ export const commitTestGate = {
         },
     ],
     tags: ["git", "test", "quality", "guard"],
+    explain: {
+        allowOnce: "make the test command pass, or commit only after fixing the failing test",
+        change: "harness.yaml > hooks > commit-test-gate: change testCommand or cacheTtlSeconds, set mode: ask, or remove it, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 if _omh_cmd_matches "$COMMAND" git commit; then
   FP=$(_omh_tree_fingerprint)
-  if _omh_gate_cached commit-test-gate {{cacheTtlSeconds}} "$FP"; then
+  GATE_CMD=$(cat <<'OMH_GATE_CMD'
+{{{testCommand}}}
+OMH_GATE_CMD
+)
+  if _omh_gate_cached commit-test-gate {{cacheTtlSeconds}} "$FP" "$GATE_CMD"; then
     echo "oh-my-harness: tests already passed on this exact tree; skipping" >&2
     _log_event "allow" "cached: tree unchanged since last passing run"
     exit 0
@@ -35,7 +43,7 @@ if _omh_cmd_matches "$COMMAND" git commit; then
     _emit_decision "block" "$REASON"
     exit 0
   fi
-  _omh_gate_record commit-test-gate "$FP"
+  _omh_gate_record commit-test-gate "$FP" "$GATE_CMD"
 fi
 exit 0`,
 };

package/dist/catalog/blocks/commit-typecheck-gate.js

@@ -17,13 +17,21 @@ export const commitTypecheckGate = {
         },
     ],
     tags: ["git", "typecheck", "quality", "guard"],
+    explain: {
+        allowOnce: "fix the type errors the typecheck command reports",
+        change: "harness.yaml > hooks > commit-typecheck-gate: change typecheckCommand, set mode: ask, or remove it, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 if _omh_cmd_matches "$COMMAND" git commit; then
   FP=$(_omh_tree_fingerprint)
-  if _omh_gate_cached commit-typecheck-gate {{cacheTtlSeconds}} "$FP"; then
+  GATE_CMD=$(cat <<'OMH_GATE_CMD'
+{{{typecheckCommand}}}
+OMH_GATE_CMD
+)
+  if _omh_gate_cached commit-typecheck-gate {{cacheTtlSeconds}} "$FP" "$GATE_CMD"; then
     echo "oh-my-harness: typecheck already passed on this exact tree; skipping" >&2
     _log_event "allow" "cached: tree unchanged since last passing run"
     exit 0
@@ -35,7 +43,7 @@ if _omh_cmd_matches "$COMMAND" git commit; then
     _emit_decision "block" "$REASON"
     exit 0
   fi
-  _omh_gate_record commit-typecheck-gate "$FP"
+  _omh_gate_record commit-typecheck-gate "$FP" "$GATE_CMD"
 fi
 exit 0`,
 };

package/dist/catalog/blocks/force-push-guard.js

@@ -32,6 +32,10 @@ export const forcePushGuard = {
         },
     ],
     tags: ["git", "push", "guard", "force"],
+    explain: {
+        allowOnce: "push to a feature branch and open a pull request; use --force-with-lease if you really need to rewrite your own branch",
+        change: "harness.yaml > hooks > force-push-guard > params.protected / allowLease, or remove it, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

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

@@ -6,6 +6,10 @@
 // ls, diff, sed without -i) stay allowed so the agent can inspect its own rules, and `omh` is
 // never a writer here, so `omh sync` / `omh hook add` remain the sanctioned
 // way to change the harness.
+// Scope (#133): by default only paths that resolve inside this project root
+// count, following cd / pushd, ~, .. and absolute paths, so another checkout's
+// .omh is not this harness's business. Tokens that cannot be resolved ($VAR,
+// backticks, unknown cwd) fall back to name matching and stay fail-closed.
 // ponytail: harness.yaml itself is deliberately not protected (it is the
 // user's knob); per-hook `locked: true` is tracked in #118. `rm -rf .` / `*`
 // from the project root are left to command-guard patterns.
@@ -25,8 +29,19 @@ export const harnessGuard = {
             default: [],
             required: false,
         },
+        {
+            name: "scope",
+            type: "string",
+            description: "project: only paths that resolve inside this project root are protected (cd and absolute paths are followed); any: match the protected names anywhere in the command",
+            default: "project",
+            required: false,
+        },
     ],
     tags: ["security", "bash", "guard", "harness", "self-protection"],
+    explain: {
+        allowOnce: "edit harness.yaml and run omh sync; hook scripts and runtime config are generated, not hand-edited",
+        change: "harness.yaml > hooks > harness-guard: scope: any / project, extraPaths, mode: ask, or remove it, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)
@@ -41,12 +56,15 @@ WRITERS="rm mv cp tee chmod chown chgrp truncate dd ln touch install rsync shred
 GIT_WRITERS="checkout restore clean rm mv"
 
 HIT=$(_omh_simple_commands "$COMMAND" | awk -F '\\t' \\
-  -v protected="$(IFS='|'; printf '%s' "\${PROTECTED[*]}")" -v writers="$WRITERS" -v gitw="$GIT_WRITERS" '
+  -v protected="$(IFS='|'; printf '%s' "\${PROTECTED[*]}")" -v writers="$WRITERS" -v gitw="$GIT_WRITERS" \\
+  -v root="$_OMH_PROJECT_ROOT" -v home="\${HOME:-}" -v scope='{{scope}}' -v seq_unsafe="$(_omh_seq_unsafe "$COMMAND")" "\${_OMH_AWK_PATHLIB}"'
   BEGIN {
+    cwd = root
     np = split(protected, P, "|")
     nw = split(writers, W, " "); for (k = 1; k <= nw; k++) isw[W[k]] = 1
     ng = split(gitw, G, " ");    for (k = 1; k <= ng; k++) isg[G[k]] = 1
   }
+  # name-based matching: scope=any, and the fallback for tokens that cannot be resolved
   function hits(t,   k, p, L) {
     sub(/^\\.\\//, "", t)
     for (k = 1; k <= np; k++) {
@@ -59,13 +77,34 @@ HIT=$(_omh_simple_commands "$COMMAND" | awk -F '\\t' \\
     }
     return ""
   }
+  # project scope: the token must resolve (through cd, ~, .., absolute paths) to a protected path under root
+  function check_at(base, t,   a, rel, k, p, L) {
+    a = omh_abs(base, t, home)
+    if (a == "") return hits(t)
+    if (!omh_under(a, root)) return ""
+    rel = (a == root) ? "" : substr(a, length(root) + 2)
+    for (k = 1; k <= np; k++) {
+      p = P[k]; if (p == "") continue
+      sub(/^\\.\\//, "", p); L = length(p)
+      if (rel == p || substr(rel, 1, L + 1) == p "/") return p
+    }
+    return ""
+  }
+  function check(t,   p) {
+    if (scope == "any") return hits(t)
+    p = check_at(cwd, t)
+    # with semicolon or newline chaining a failed cd leaves the shell where it was: judge from the root too
+    if (p == "" && seq_unsafe == "1" && cwd != root && t !~ /^\\//) p = check_at(root, t)
+    return p
+  }
   found != "" { next }
   {
-    if ($1 == "__omh_redirect__") { p = hits($2); if (p != "") found = "redirect into " p; next }
+    if ($1 == "__omh_redirect__") { p = check($2); if (p != "") found = "redirect into " p; next }
     i = 1
     while (i <= NF && $i ~ /^[A-Za-z_][A-Za-z0-9_]*=/) i++
     if (i <= NF && ($i == "sudo" || $i == "doas")) { i++; while (i <= NF && $i ~ /^-/) i++ }
     if (i > NF) next
+    if ($i == "cd" || $i == "pushd" || $i == "popd") { cwd = omh_cd_cmd(cwd, i, home); next }
     a0 = $i
     write = 0
     if (isw[a0]) write = 1
@@ -82,7 +121,7 @@ HIT=$(_omh_simple_commands "$COMMAND" | awk -F '\\t' \\
     }
     else if (a0 == "find") { for (k = i; k <= NF; k++) if ($k == "-delete" || $k == "-exec" || $k == "-execdir") write = 1 }
     if (!write) next
-    for (k = i + 1; k <= NF; k++) { p = hits($k); if (p != "") { found = a0 " on " p; next } }
+    for (k = i + 1; k <= NF; k++) { p = check($k); if (p != "") { found = a0 " on " p; next } }
   }
   END { if (found != "") print found }')
 if [[ -n "$HIT" ]]; then

package/dist/catalog/blocks/index.js

@@ -19,6 +19,8 @@ import { loopGuard } from "./loop-guard.js";
 import { harnessGuard } from "./harness-guard.js";
 import { noVerifyGuard } from "./no-verify-guard.js";
 import { forcePushGuard } from "./force-push-guard.js";
+import { stopTestGate } from "./stop-test-gate.js";
+import { stopUncommittedWarn } from "./stop-uncommitted-warn.js";
 export const builtinBlocks = [
     branchGuard,
     commitTestGate,
@@ -41,4 +43,6 @@ export const builtinBlocks = [
     harnessGuard,
     noVerifyGuard,
     forcePushGuard,
+    stopTestGate,
+    stopUncommittedWarn,
 ];

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

@@ -16,6 +16,10 @@ export const lockfileGuard = {
         },
     ],
     tags: ["security", "file", "lockfile", "guard"],
+    explain: {
+        allowOnce: "change the dependency with the package manager (npm/pnpm/yarn/pip add or remove) so it rewrites the lockfile",
+        change: "harness.yaml > hooks > lockfile-guard > params.lockfiles: remove the file, or remove the hook, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

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

@@ -30,6 +30,10 @@ export const loopGuard = {
             default: [],
         },
     ],
+    explain: {
+        allowOnce: "the loop must not write its own work orders or architect-only paths; do that from an architect session",
+        change: "harness.yaml > loop.architectOnly / loop.workOrders, or disable the loop, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

package/dist/catalog/blocks/no-verify-guard.js

@@ -18,6 +18,10 @@ export const noVerifyGuard = {
     canBlock: true,
     params: [],
     tags: ["git", "hooks", "guard", "bypass"],
+    explain: {
+        allowOnce: "fix what the git hook reports and commit or push again without --no-verify",
+        change: "harness.yaml > hooks > no-verify-guard: set mode: ask or remove it, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

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

@@ -22,6 +22,10 @@ export const pathGuard = {
         },
     ],
     tags: ["security", "file", "path", "guard"],
+    explain: {
+        allowOnce: "write to a source path instead; build output and dependency directories are regenerated by their tools",
+        change: "harness.yaml > hooks > path-guard > params.blockedPaths: remove the path (protectHarness: false lifts the self-protection), then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

package/dist/catalog/blocks/secret-file-guard.js

@@ -16,6 +16,10 @@ export const secretFileGuard = {
         },
     ],
     tags: ["security", "secrets", "credentials", "guard"],
+    explain: {
+        allowOnce: "edit the secret file yourself outside the agent",
+        change: "harness.yaml > hooks > secret-file-guard > params.patterns: remove the pattern, or remove the hook, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

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

@@ -16,6 +16,10 @@ export const sqlGuard = {
         },
     ],
     tags: ["security", "sql", "guard", "database"],
+    explain: {
+        allowOnce: "run the statement yourself outside the agent, or use a narrower statement",
+        change: "harness.yaml > hooks > sql-guard > params.patterns: remove or edit the pattern, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

package/dist/catalog/blocks/stop-test-gate.d.ts

@@ -0,0 +1,2 @@
+import type { BuildingBlock } from "../types.js";
+export declare const stopTestGate: BuildingBlock;

package/dist/catalog/blocks/stop-test-gate.js

@@ -0,0 +1,81 @@
+// Stop-event gate (#117): when the agent is about to end its turn with a red
+// test suite, hand the failure back so it keeps working instead of finishing
+// on a broken tree. Two safety valves: Claude's stop_hook_active flag (a Stop
+// hook that blocked once must not block the follow-up stop) and a per-session
+// retry cap kept in .omh/state, which also covers runtimes without that flag.
+// The tree-fingerprint cache shared with commit-test-gate means a suite that
+// just passed on this exact tree is not run again.
+export const stopTestGate = {
+    id: "stop-test-gate",
+    name: "Stop Test Gate",
+    description: "Runs tests when the agent tries to end its turn and sends it back to work while they fail",
+    category: "quality",
+    event: "Stop",
+    canBlock: true,
+    params: [
+        { name: "testCommand", type: "string", description: "Test command to run before the turn may end", required: true },
+        {
+            name: "maxRetries",
+            type: "number",
+            description: "How many times per session the turn may be sent back before the gate gives up and lets it end",
+            default: 2,
+            required: false,
+        },
+        {
+            name: "cacheTtlSeconds",
+            type: "number",
+            description: "Skip the run when the working tree is unchanged since the last pass and that pass is younger than this many seconds (0 disables)",
+            default: 600,
+            required: false,
+        },
+    ],
+    tags: ["stop", "test", "quality", "gate"],
+    explain: {
+        allowOnce: "make the test command pass; after maxRetries send-backs in one session the gate lets the turn end anyway",
+        change: "harness.yaml > hooks > stop-test-gate: change testCommand, maxRetries or cacheTtlSeconds, or remove it, then omh sync",
+    },
+    template: `#!/bin/bash
+set -euo pipefail
+INPUT=$(cat)
+# A Stop hook that already sent the agent back must not block the follow-up stop.
+[[ "$(echo "$INPUT" | jq -r '.stop_hook_active // false' 2>/dev/null)" == "true" ]] && exit 0
+
+SESSION=$(echo "$INPUT" | jq -r '.session_id // "default"' 2>/dev/null | tr -c 'A-Za-z0-9_-' '_')
+STATE_DIR="\${_OMH_STATE_DIR:-.omh/state}"
+COUNT_FILE="$STATE_DIR/stop-test-gate-\${SESSION}.count"
+COUNT=$(cat "$COUNT_FILE" 2>/dev/null || echo 0)
+[[ "$COUNT" =~ ^[0-9]+$ ]] || COUNT=0
+if [[ "$COUNT" -ge {{maxRetries}} ]]; then
+  _log_event "allow" "stop-test-gate: retry cap ({{maxRetries}}) reached for this session; letting the turn end"
+  exit 0
+fi
+
+FP=$(_omh_tree_fingerprint)
+GATE_CMD=$(cat <<'OMH_GATE_CMD'
+{{{testCommand}}}
+OMH_GATE_CMD
+)
+if _omh_gate_cached stop-test-gate {{cacheTtlSeconds}} "$FP" "$GATE_CMD"; then
+  rm -f "$COUNT_FILE"
+  _log_event "allow" "cached: tree unchanged since last passing run"
+  exit 0
+fi
+
+STATUS=0
+set -o pipefail
+ESC=$'\\x1b'
+OUTPUT=$(NO_COLOR=1 FORCE_COLOR=0 {{{testCommand}}} 2>&1 | sed "s/\${ESC}\\[[0-9;]*[A-Za-z]//g") || STATUS=$?
+if [[ "$STATUS" -ne 0 ]]; then
+  mkdir -p "$STATE_DIR" 2>/dev/null || true
+  echo $((COUNT + 1)) > "$COUNT_FILE"
+  TAIL=$(printf '%s\\n' "$OUTPUT" | tail -n 15)
+  REASON="oh-my-harness: the test suite is failing; fix it before ending the turn (attempt $((COUNT + 1))/{{maxRetries}}):
+$TAIL"
+  _log_event "block" "$REASON"
+  jq -cn --arg r "$REASON" '{decision:"block", reason:$r, hookSpecificOutput:{hookEventName:"Stop", decision:"block", reason:$r}}'
+  exit 0
+fi
+rm -f "$COUNT_FILE"
+_omh_gate_record stop-test-gate "$FP" "$GATE_CMD"
+exit 0`,
+};

package/dist/catalog/blocks/stop-uncommitted-warn.d.ts

@@ -0,0 +1,2 @@
+import type { BuildingBlock } from "../types.js";
+export declare const stopUncommittedWarn: BuildingBlock;

package/dist/catalog/blocks/stop-uncommitted-warn.js

@@ -0,0 +1,30 @@
+// Stop-event notice (#117): when the turn ends with uncommitted changes, say
+// so as a system message. Never blocks; the point is that the human sees what
+// was left behind instead of discovering it later.
+export const stopUncommittedWarn = {
+    id: "stop-uncommitted-warn",
+    name: "Stop Uncommitted Warning",
+    description: "When the agent ends its turn with uncommitted changes, lists them as a system message (never blocks)",
+    category: "git",
+    event: "Stop",
+    canBlock: false,
+    params: [],
+    tags: ["stop", "git", "notice"],
+    template: `#!/bin/bash
+set -euo pipefail
+INPUT=$(cat)
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+if ! CHANGES=$(git status --porcelain 2>&1); then
+  MSG="oh-my-harness: could not read git status, so uncommitted changes may be unreported: $(printf '%s' "$CHANGES" | head -n 3)"
+  _log_event "allow" "$MSG"
+  jq -cn --arg m "$MSG" '{systemMessage:$m}'
+  exit 0
+fi
+[[ -z "$CHANGES" ]] && exit 0
+N=$(printf '%s\\n' "$CHANGES" | wc -l | tr -d ' ')
+MSG="oh-my-harness: $N uncommitted change(s) left behind:
+$(printf '%s\\n' "$CHANGES" | head -n 20)"
+_log_event "allow" "$MSG"
+jq -cn --arg m "$MSG" '{systemMessage:$m}'
+exit 0`,
+};

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

@@ -22,6 +22,10 @@ export const tddGuard = {
             default: "\\.(test|spec)\\.(ts|tsx|js|jsx)$",
         },
     ],
+    explain: {
+        allowOnce: "edit or create the matching test file first (the guard records test edits per session), then edit the source",
+        change: "harness.yaml > hooks > tdd-guard: narrow srcPattern/testPattern, set mode: ask, or remove it, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

package/dist/catalog/types.d.ts

@@ -19,11 +19,20 @@ export interface BuildingBlock {
     params: ParamDefinition[];
     template: string;
     tags: string[];
+    /** Plain-language remedies shown by `omh explain` (#115). */
+    explain?: {
+        /** How to get past this block one time without changing the rule. */
+        allowOnce?: string;
+        /** Where the rule lives and how to change it. */
+        change?: string;
+    };
 }
 export interface HookEntry {
     block: string;
     params: Record<string, unknown>;
     mode?: "block" | "ask";
+    /** `omh modify` may never remove or weaken a locked entry (#118). */
+    locked?: boolean;
 }
 export declare const ParamDefinitionSchema: z.ZodObject<{
     name: z.ZodString;
@@ -75,7 +84,7 @@ export declare const BuildingBlockSchema: z.ZodObject<{
     tags: z.ZodArray<z.ZodString, "many">;
 }, "strip", z.ZodTypeAny, {
     id: string;
-    event: "PreToolUse" | "PostToolUse" | "SessionStart" | "Notification" | "ConfigChange" | "WorktreeCreate" | "UserPromptSubmit" | "Stop" | "PreCompact" | "PostCompact" | "SubagentStop" | "PreBash" | "PostBash" | "PreEdit" | "PostEdit" | "PreRead" | "PostRead" | "PreWrite" | "PostWrite" | "SessionEnd" | "PreToolResult" | "PostToolResult" | "WorktreeRemove";
+    event: "PreToolUse" | "PostToolUse" | "SessionStart" | "Notification" | "ConfigChange" | "WorktreeCreate" | "Stop" | "SubagentStop" | "UserPromptSubmit" | "PreCompact" | "PostCompact" | "PreBash" | "PostBash" | "PreEdit" | "PostEdit" | "PreRead" | "PostRead" | "PreWrite" | "PostWrite" | "SessionEnd" | "PreToolResult" | "PostToolResult" | "WorktreeRemove";
     name: string;
     params: {
         name: string;
@@ -92,7 +101,7 @@ export declare const BuildingBlockSchema: z.ZodObject<{
     matcher?: string | undefined;
 }, {
     id: string;
-    event: "PreToolUse" | "PostToolUse" | "SessionStart" | "Notification" | "ConfigChange" | "WorktreeCreate" | "UserPromptSubmit" | "Stop" | "PreCompact" | "PostCompact" | "SubagentStop" | "PreBash" | "PostBash" | "PreEdit" | "PostEdit" | "PreRead" | "PostRead" | "PreWrite" | "PostWrite" | "SessionEnd" | "PreToolResult" | "PostToolResult" | "WorktreeRemove";
+    event: "PreToolUse" | "PostToolUse" | "SessionStart" | "Notification" | "ConfigChange" | "WorktreeCreate" | "Stop" | "SubagentStop" | "UserPromptSubmit" | "PreCompact" | "PostCompact" | "PreBash" | "PostBash" | "PreEdit" | "PostEdit" | "PreRead" | "PostRead" | "PreWrite" | "PostWrite" | "SessionEnd" | "PreToolResult" | "PostToolResult" | "WorktreeRemove";
     name: string;
     params: {
         name: string;
@@ -112,12 +121,16 @@ export declare const HookEntrySchema: z.ZodObject<{
     block: z.ZodString;
     params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     mode: z.ZodDefault<z.ZodEnum<["block", "ask"]>>;
+    /** `omh modify` may never remove or weaken a locked entry (#118). */
+    locked: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     block: string;
     params: Record<string, unknown>;
     mode: "block" | "ask";
+    locked?: boolean | undefined;
 }, {
     block: string;
     params?: Record<string, unknown> | undefined;
     mode?: "block" | "ask" | undefined;
+    locked?: boolean | undefined;
 }>;

package/dist/catalog/types.js

@@ -22,4 +22,6 @@ export const HookEntrySchema = z.object({
     block: z.string(),
     params: z.record(z.unknown()).default({}),
     mode: z.enum(["block", "ask"]).default("block"),
+    /** `omh modify` may never remove or weaken a locked entry (#118). */
+    locked: z.boolean().optional(),
 });

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

@@ -0,0 +1,28 @@
+import { type HookEvent } from "../event-logger.js";
+import type { BuildingBlock } from "../../catalog/types.js";
+export interface ExplainOptions {
+    projectDir?: string;
+    /** How many block decisions to show, newest first. Default 5. */
+    last?: number;
+    json?: boolean;
+}
+export interface ExplainEntry {
+    ts: string;
+    block: string;
+    hook: string;
+    reason: string;
+    allowOnce?: string;
+    change: string;
+}
+/**
+ * catalog-<id>.sh -> id. Legacy scripts were named harness-<name>.sh, so a
+ * harness- prefix is stripped too, but only when what is left is not itself a
+ * block id: catalog-harness-guard.sh must stay harness-guard.
+ */
+export declare function blockIdFromHook(hook: string, knownIds?: Set<string>): string;
+export declare function toEntry(ev: HookEvent, blocks: BuildingBlock[]): ExplainEntry;
+export declare function formatExplanation(ev: HookEvent, blocks: BuildingBlock[], now?: number): string;
+export declare function explainCommand(options?: ExplainOptions): Promise<{
+    exitCode: number;
+    entries: ExplainEntry[];
+}>;