uni-harness 0.2.2 → 0.4.0

package/.claude/hooks/guard-pre-bash.sh

@@ -1,17 +1,22 @@
 #!/usr/bin/env bash
 # ════════════════════════════════════════════════════════════════
 # PreToolUse(Bash) guard — blocks destructive/irreversible commands
-# before they run.
-# exit 0 + JSON(deny) = blocked / exit 0 (no output) = normal flow
+# before they run, and asks before a git commit that would land edits
+# no test run has seen (state-aware gate: the pending_test marker is
+# set by sensor-post-edit.sh and cleared only when stop-gate.sh sees
+# the tests pass).
+# exit 0 + JSON(deny/ask) = intercepted / exit 0 (no output) = normal flow
 # ════════════════════════════════════════════════════════════════
 set -euo pipefail
 
 INPUT=$(cat)
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
 
-python3 - "$INPUT" <<'PYEOF'
-import json, re, sys
+python3 - "$INPUT" "$PROJECT_DIR" <<'PYEOF'
+import json, os, re, sys
 
 data = json.loads(sys.argv[1])
+proj = sys.argv[2]
 cmd = (data.get("tool_input") or {}).get("command", "") or ""
 
 # DENY: irreversible/destructive patterns (extend per project as needed)
@@ -41,6 +46,36 @@ for pattern, reason in DENY_PATTERNS:
         }))
         sys.exit(0)
 
+# State-aware commit gate: committing while the pending_test marker
+# exists means tests have not passed since the last code edit. "ask",
+# not "deny" — WIP commits and doc-only commits are legitimate, so the
+# user decides. Fires only when TEST_CMD is configured (otherwise the
+# marker never clears and this would nag on every commit).
+try:
+    sid = data.get("session_id", "")
+    marker = os.path.join(proj, ".harness/logs", f"pending_test.{sid}")
+    env_path = os.path.join(proj, ".harness/commands.env")
+    configured = False
+    if os.path.exists(env_path):
+        with open(env_path) as f:
+            configured = bool(re.search(r'^TEST_CMD=".+"', f.read(), re.M))
+    if (configured and sid and os.path.exists(marker)
+            and re.search(r"\bgit\s+([a-z-]+\s+)*commit\b", cmd)):
+        print(json.dumps({
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "ask",
+                "permissionDecisionReason":
+                    "[harness guard] Code was edited this session but the "
+                    "test suite has not passed since (pending_test marker "
+                    "present). Run the TEST command first, or confirm this "
+                    "commit is intentionally untested (WIP/docs)."
+            }
+        }))
+        sys.exit(0)
+except Exception:
+    pass
+
 # No match -> exit silently (normal permission flow)
 sys.exit(0)
 PYEOF

package/.claude/hooks/guard-pre-edit.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# ════════════════════════════════════════════════════════════════
+# PreToolUse(Edit|Write) guard — two checks, both "ask" not "deny":
+# (1) protected paths: .claude/**, .harness/** (except state/),
+#     .github/**, .env*, *.config.* — the CLAUDE.md rule "never modify
+#     config/harness files without asking", promoted to a gate.
+# (2) test-weakening: edits to test files that add skip markers,
+#     remove test functions, or gut assertions. The #1 reward hack is
+#     making tests pass by making tests weaker — surface it to the
+#     user instead of letting it slide through.
+# Precision-first: fire only on unambiguous signals; fail silent on
+# any parse error.
+# ════════════════════════════════════════════════════════════════
+set -uo pipefail
+
+INPUT=$(cat)
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+python3 - "$INPUT" "$PROJECT_DIR" <<'PYEOF'
+import json, sys, os, re
+
+try:
+    data = json.loads(sys.argv[1])
+except Exception:
+    sys.exit(0)
+proj = os.path.realpath(sys.argv[2])
+
+ti = data.get("tool_input") or {}
+path = str(ti.get("file_path") or "")
+if not path:
+    sys.exit(0)
+
+# Only police files inside the project
+rp = os.path.realpath(path if os.path.isabs(path) else os.path.join(proj, path))
+if not (rp + os.sep).startswith(proj + os.sep):
+    sys.exit(0)
+rel = os.path.relpath(rp, proj).replace(os.sep, "/")
+base = os.path.basename(rel)
+
+
+def ask(reason):
+    print(json.dumps({"hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "ask",
+        "permissionDecisionReason": "[harness guard] " + reason,
+    }}, ensure_ascii=False))
+    sys.exit(0)
+
+
+# ── (1) protected paths ──────────────────────────────────────────
+# .harness/state/ is the checkpoint area Claude legitimately writes.
+if not rel.startswith(".harness/state/"):
+    protected = None
+    if rel.startswith(".claude/"):
+        protected = "the harness machinery (.claude/)"
+    elif rel.startswith(".harness/"):
+        protected = "the harness configuration (.harness/)"
+    elif rel.startswith(".github/"):
+        protected = "CI configuration (.github/)"
+    elif base == ".env" or base.startswith(".env."):
+        protected = "an environment file"
+    elif ".config." in base:
+        protected = "a tool configuration file"
+    if protected:
+        ask(f"'{rel}' is {protected}. Per the project rules, changes here "
+            "need explicit user approval — especially anything that would "
+            "weaken tests, lint, or guards. State what you want to change "
+            "and why.")
+
+# ── (2) test-weakening detection ─────────────────────────────────
+segs = rel.lower().split("/")
+is_test = (
+    any(s in ("test", "tests", "__tests__", "spec", "specs") for s in segs[:-1])
+    or re.search(r"(^|[._-])(test|spec)s?[._-]", base.lower())
+)
+if not is_test:
+    sys.exit(0)
+
+tool = data.get("tool_name", "")
+if tool == "Write":
+    try:
+        with open(rp) as f:
+            old = f.read()
+    except Exception:
+        sys.exit(0)  # brand-new test file: nothing to weaken yet
+    new = str(ti.get("content") or "")
+elif tool in ("Edit", "MultiEdit"):
+    edits = ti.get("edits") or [ti]
+    old = "\n".join(str(e.get("old_string") or "") for e in edits)
+    new = "\n".join(str(e.get("new_string") or "") for e in edits)
+else:
+    sys.exit(0)
+
+SKIP_MARKERS = [
+    r"@pytest\.mark\.skip", r"@pytest\.mark\.xfail", r"pytest\.skip\(",
+    r"@unittest\.skip", r"\.only\(", r"\.skip\(", r"\bxit\(", r"\bxdescribe\(",
+    r"\bxtest\(", r"it\.skip", r"describe\.skip", r"test\.skip",
+    r"@Disabled", r"t\.Skip\(", r"#\[ignore\]",
+]
+GUT_MARKERS = [r"assert\s+True\b", r"expect\(true\)\.toBe\(true\)", r"assert\s+1\s*==\s*1\b"]
+TEST_FN = re.compile(r"^\s*(def test_|func Test|it\(|test\(|Deno\.test\()", re.M)
+
+findings = []
+for pat in SKIP_MARKERS:
+    if len(re.findall(pat, new)) > len(re.findall(pat, old)):
+        findings.append(f"adds a skip/only marker ({pat.replace(chr(92), '')})")
+        break
+for pat in GUT_MARKERS:
+    if len(re.findall(pat, new)) > len(re.findall(pat, old)):
+        findings.append("adds a trivially-true assertion")
+        break
+n_old, n_new = len(TEST_FN.findall(old)), len(TEST_FN.findall(new))
+if n_new < n_old:
+    findings.append(f"removes {n_old - n_new} test function(s)")
+
+if findings:
+    ask(f"this change to test file '{rel}' " + " and ".join(findings) +
+        ". Weakening tests to make them pass is never an acceptable fix. "
+        "If the test itself is genuinely wrong or obsolete, explain that to "
+        "the user and get approval first.")
+PYEOF
+exit 0

package/.claude/hooks/observe-log.sh

@@ -3,7 +3,8 @@
 # Observability log — records every tool call as JSONL + tripwires
 # Log: .harness/logs/tool_calls.jsonl
 # Tripwires: (1) warn when per-session tool calls exceed a ceiling
-#            (2) same failure 3x in a row -> tell Claude to stop and pivot
+#            (2) same normalized error 3x in a session -> demand an
+#                escalation packet instead of another retry
 # ════════════════════════════════════════════════════════════════
 set -uo pipefail
 
@@ -67,15 +68,25 @@ if n > 0 and n % 100 == 0 and n >= 300:
     warnings.append(f"This session has exceeded {n} tool calls. "
                     "Re-examine the plan — this may be a runaway loop.")
 
-# (2) same failure 3x in a row
-fails = [e for e in lines if e.get("event") == "PostToolUseFailure"][-3:]
-if len(fails) == 3:
-    sigs = {(e.get("tool", ""), (e.get("error") or "")[:80]) for e in fails}
-    if len(sigs) == 1:
-        warnings.append("[tripwire] The same tool failed with the same error "
-                        "3 times in a row. Stop repeating this approach; write "
-                        "an escalation packet per the Work Loop section of "
-                        "CLAUDE.md and report to the user.")
+# (2) same error 3x this session (normalized, not necessarily consecutive)
+if event == "PostToolUseFailure":
+    import re
+    def norm(e):
+        s = (e.get("error") or "")[:300]
+        s = re.sub(r"0x[0-9a-fA-F]+", "N", s)   # addresses/ids
+        s = re.sub(r"\d+", "N", s)              # line numbers, counts
+        s = re.sub(r"(/[^\s:'\"]+)+", "PATH", s)  # file paths
+        return (e.get("tool", ""), s[:120])
+    sig = norm(entry)
+    count = sum(1 for e in lines
+                if e.get("event") == "PostToolUseFailure" and norm(e) == sig)
+    if count >= 3 and count % 3 == 0:
+        warnings.append(f"[tripwire] The same error has now occurred {count} "
+                        f"times this session (tool: {entry.get('tool', '')}). "
+                        "Stop repeating this approach. Write an escalation "
+                        "packet per the Work Loop section of CLAUDE.md "
+                        "(decision needed / alternatives tried / cost of "
+                        "waiting / safest default) and report to the user.")
 
 if warnings:
     print(json.dumps({

package/.claude/hooks/pre-compact.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# ════════════════════════════════════════════════════════════════
+# PreCompact — runs just before context compaction (auto or /compact).
+# Two jobs:
+# (1) snapshot .harness/state/ so whatever checkpoint exists at this
+#     moment survives even if the post-compaction session corrupts it
+# (2) record the PreCompact event in the log.
+# Context re-injection after compaction is session-start.sh's job
+# (matcher "compact") — PreCompact hook output supports no
+# hookSpecificOutput/additionalContext channel, only snapshot work.
+# Fail silent: an unconfigured or half-installed harness must never
+# break compaction.
+# ════════════════════════════════════════════════════════════════
+set -uo pipefail
+
+INPUT=$(cat)
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+STATE_DIR="$PROJECT_DIR/.harness/state"
+
+# (1) snapshot current checkpoints (best effort, keep only the latest)
+if [ -d "$STATE_DIR" ]; then
+  mkdir -p "$STATE_DIR/.pre-compact-backup" 2>/dev/null || true
+  for f in plan.md progress.json decisions.jsonl; do
+    [ -f "$STATE_DIR/$f" ] && cp "$STATE_DIR/$f" "$STATE_DIR/.pre-compact-backup/$f" 2>/dev/null
+  done
+fi
+
+# (2) note the event in the log (no JSON output — the PreCompact hook
+# schema accepts no context injection; emitting one fails validation)
+python3 - "$INPUT" "$PROJECT_DIR" <<'PYEOF'
+import json, sys, os, datetime
+
+try:
+    data = json.loads(sys.argv[1])
+except Exception:
+    data = {}
+proj = sys.argv[2]
+
+try:
+    log_dir = os.path.join(proj, ".harness/logs")
+    os.makedirs(log_dir, exist_ok=True)
+    with open(os.path.join(log_dir, "tool_calls.jsonl"), "a") as f:
+        f.write(json.dumps({
+            "ts": datetime.datetime.now().isoformat(timespec="seconds"),
+            "session_id": data.get("session_id", ""),
+            "event": "PreCompact",
+            "tool": "",
+            "summary": data.get("trigger", ""),
+        }, ensure_ascii=False) + "\n")
+except Exception:
+    pass
+PYEOF
+exit 0

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

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# ════════════════════════════════════════════════════════════════
+# SessionEnd ledger — one JSONL row per session.
+# Aggregates this session's entries from tool_calls.jsonl into
+# .harness/logs/sessions.jsonl: duration, call/failure/edit counts,
+# stop blocks, and whether edits ended with tests in a clean state.
+# This is the data /guide-audit and harness_report.py read instead of
+# guessing — per-session rollups beat re-scanning the raw log.
+# Also clears this session's marker files (pending_test/stop_blocks)
+# so stale markers never leak into the next session.
+# Fail silent: no logs, no harness, half-installed — always exit 0.
+# ════════════════════════════════════════════════════════════════
+set -uo pipefail
+
+INPUT=$(cat)
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+python3 - "$INPUT" "$PROJECT_DIR" <<'PYEOF'
+import json, sys, os, datetime
+
+try:
+    data = json.loads(sys.argv[1])
+except Exception:
+    data = {}
+proj = sys.argv[2]
+sid = data.get("session_id", "")
+if not sid:
+    raise SystemExit(0)
+
+log_dir = os.path.join(proj, ".harness/logs")
+log_path = os.path.join(log_dir, "tool_calls.jsonl")
+
+calls = failures = edits = 0
+first_ts = last_ts = None
+try:
+    with open(log_path) as f:
+        for line in f:
+            try:
+                e = json.loads(line)
+            except Exception:
+                continue
+            if e.get("session_id") != sid:
+                continue
+            ts = e.get("ts", "")
+            first_ts = first_ts or ts
+            last_ts = ts or last_ts
+            ev = e.get("event", "")
+            if ev == "PostToolUse":
+                calls += 1
+                if e.get("tool") in ("Edit", "Write", "MultiEdit", "NotebookEdit"):
+                    edits += 1
+            elif ev == "PostToolUseFailure":
+                calls += 1
+                failures += 1
+except Exception:
+    raise SystemExit(0)
+
+if calls == 0:
+    raise SystemExit(0)  # nothing happened; no row
+
+duration_s = None
+try:
+    duration_s = int((datetime.datetime.fromisoformat(last_ts)
+                      - datetime.datetime.fromisoformat(first_ts)).total_seconds())
+except Exception:
+    pass
+
+pending = os.path.join(log_dir, f"pending_test.{sid}")
+blocks_f = os.path.join(log_dir, f"stop_blocks.{sid}")
+stop_blocks = 0
+try:
+    with open(blocks_f) as f:
+        stop_blocks = int(f.read().strip() or 0)
+except Exception:
+    pass
+
+row = {
+    "ts": datetime.datetime.now().isoformat(timespec="seconds"),
+    "session_id": sid,
+    "event": "SessionEnd",
+    "reason": data.get("reason", ""),
+    "duration_s": duration_s,
+    "calls": calls,
+    "failures": failures,
+    "edits": edits,
+    "stop_blocks": stop_blocks,
+    # edits happened but the stop-gate never saw them pass -> not clean
+    "tests_clean": not os.path.exists(pending),
+}
+try:
+    os.makedirs(log_dir, exist_ok=True)
+    with open(os.path.join(log_dir, "sessions.jsonl"), "a") as f:
+        f.write(json.dumps(row, ensure_ascii=False) + "\n")
+except Exception:
+    pass
+
+for p in (pending, blocks_f):
+    try:
+        os.remove(p)
+    except Exception:
+        pass
+PYEOF
+exit 0

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

@@ -9,17 +9,42 @@
 #     suggest running /ratchet.
 # (3) If the harness is installed but unconfigured (commands.env has
 #     no commands), have Claude offer to run /harness-init.
+# (5) Right after a compaction (source=compact), instruct a checkpoint
+#     refresh before resuming — pre-compact.sh snapshotted the state
+#     but cannot inject context itself (schema limitation).
 # ════════════════════════════════════════════════════════════════
 set -uo pipefail
 
+INPUT=$(cat)
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
 
-python3 - "$PROJECT_DIR" <<'PYEOF'
+python3 - "$INPUT" "$PROJECT_DIR" <<'PYEOF'
 import json, sys, os, datetime
 
-proj = sys.argv[1]
+try:
+    hook_in = json.loads(sys.argv[1])
+except Exception:
+    hook_in = {}
+proj = sys.argv[2]
 parts = []
 
+# (5) resuming right after compaction -> refresh checkpoint first
+try:
+    if hook_in.get("source") == "compact":
+        backup = os.path.join(proj, ".harness/state/.pre-compact-backup")
+        note = ("[harness] Context was just compacted. Before resuming work, "
+                "verify the summary against .harness/state/ (plan.md / "
+                "progress.json / decisions.jsonl) and update progress.json "
+                "(/checkpoint) so the next step is recorded outside the "
+                "conversation.")
+        if os.path.isdir(backup):
+            note += (" A snapshot of the pre-compaction checkpoint was saved "
+                     "to .harness/state/.pre-compact-backup/ — consult it if "
+                     "anything seems lost.")
+        parts.append(note)
+except Exception:
+    pass
+
 # (3) harness installed but not configured -> offer /harness-init
 # (checked first so a fresh install greets the user with setup)
 try:

package/.claude/hooks/stop-gate.sh

@@ -6,6 +6,16 @@
 # stop and feed the output back. Blocking is capped at 3 per
 # session — after that, instruct an escalation packet and let the
 # stop through (prevents infinite loops).
+#
+# Trace rules v1 (.harness/trace.rules, optional): lines of
+#   require-before-stop <regex> <message>
+# <regex> must contain no whitespace (use . or \s inside it) — the
+# line is whitespace-split into keyword / regex / message.
+# In a session that edited code, each rule requires at least one
+# logged tool call matching <regex> before the turn may end.
+# An unsatisfied rule blocks the stop ONCE per session (a reminder,
+# not a cage — the marker in trace_notified.<sid> prevents loops).
+# File absent -> feature entirely off (fail silent).
 # ════════════════════════════════════════════════════════════════
 set -uo pipefail
 
@@ -22,6 +32,80 @@ print(json.loads(sys.argv[1]).get("session_id",""))' "$INPUT" 2>/dev/null || ech
 MARKER="$LOG_DIR/pending_test.$SESSION_ID"
 COUNTER="$LOG_DIR/stop_blocks.$SESSION_ID"
 
+# ── trace rules: require-before-stop ─────────────────────────────
+TRACE_FILE="$PROJECT_DIR/.harness/trace.rules"
+if [ -f "$TRACE_FILE" ] && [ -s "$MARKER" ]; then
+  TRACE_OUT=$(python3 - "$SESSION_ID" "$PROJECT_DIR" <<'PYEOF'
+import json, os, re, sys
+
+sid, proj = sys.argv[1], sys.argv[2]
+log_dir = os.path.join(proj, ".harness/logs")
+notified_path = os.path.join(log_dir, f"trace_notified.{sid}")
+
+try:
+    with open(os.path.join(proj, ".harness/trace.rules")) as f:
+        raw_rules = f.read().splitlines()
+except Exception:
+    raise SystemExit(0)
+
+rules = []
+for line in raw_rules:
+    line = line.strip()
+    if not line or line.startswith("#"):
+        continue
+    parts = line.split(None, 2)
+    if len(parts) == 3 and parts[0] == "require-before-stop":
+        rules.append((parts[1], parts[2]))
+if not rules:
+    raise SystemExit(0)
+
+session_lines = []
+try:
+    with open(os.path.join(log_dir, "tool_calls.jsonl")) as f:
+        for line in f:
+            try:
+                if json.loads(line).get("session_id") == sid:
+                    session_lines.append(line)
+            except Exception:
+                continue
+except Exception:
+    raise SystemExit(0)
+
+notified = set()
+try:
+    with open(notified_path) as f:
+        notified = set(f.read().splitlines())
+except Exception:
+    pass
+
+for regex, message in rules:
+    if regex in notified:
+        continue
+    try:
+        pat = re.compile(regex)
+    except Exception:
+        continue  # a broken regex must never block work
+    if any(pat.search(line) for line in session_lines):
+        continue
+    try:
+        with open(notified_path, "a") as f:
+            f.write(regex + "\n")
+    except Exception:
+        pass
+    print(json.dumps({"decision": "block", "reason":
+        f"[harness trace rule] Required step not seen this session "
+        f"(no logged tool call matched /{regex}/): {message} "
+        f"Do it now, or state explicitly why it does not apply, then stop. "
+        f"(This rule blocks only once per session.)"}, ensure_ascii=False))
+    break
+PYEOF
+)
+  if [ -n "$TRACE_OUT" ]; then
+    printf '%s\n' "$TRACE_OUT"
+    exit 0
+  fi
+fi
+
 # No code modified this session -> pass
 [ -s "$MARKER" ] || exit 0
 

package/.claude/settings.json

@@ -11,6 +11,28 @@
             "statusMessage": "harness: command safety check"
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-pre-edit.sh",
+            "timeout": 15,
+            "statusMessage": "harness: edit safety check"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/pre-compact.sh",
+            "timeout": 15
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -71,6 +93,17 @@
           }
         ]
       }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/session-end.sh",
+            "timeout": 15
+          }
+        ]
+      }
     ]
   }
 }

package/.claude/skills/distill/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: distill
+description: Mine a successfully completed task from the harness logs and distill the reusable procedure into a project skill (success-side ratchet). Use after a nontrivial task succeeded and is likely to recur (/distill [what succeeded]). Proposes only — creating the skill requires user approval.
+---
+
+# Distill — Turning Successes into Structure
+
+`/ratchet` makes failures permanent structure; `/distill` does the same
+for **successes** (the workflow-memory idea, arXiv:2409.07429). A
+multi-step procedure that worked once and will be needed again should
+become a project skill — not something to rediscover from scratch.
+
+## When to Use
+
+- The task took multiple nonobvious steps that a future session would
+  have to rediscover (env quirks, ordering constraints, project-specific
+  commands).
+- The task will plausibly recur (release flow, data migration, fixture
+  regeneration, deploy checklist).
+
+Do NOT distill one-off work, trivial sequences the code already
+documents, or a procedure that only worked once and remains unverified.
+
+## Procedure
+
+1. **Locate the trajectory** — from `.harness/logs/tool_calls.jsonl`,
+   collect this session's (or the named task's) entries: the commands
+   run, files touched, and order. Cross-check `.harness/state/plan.md`
+   and `decisions.jsonl` for the decisions that shaped it.
+2. **Separate the reusable from the incidental** — keep steps that will
+   repeat (commands, ordering, verification points); drop exploration,
+   dead ends, and one-time values. Parameterize what varies (version
+   numbers, file names) as `[placeholders]`.
+3. **Attach verification** — every distilled skill must state how to
+   check the procedure worked (which command proves success). A recipe
+   without a check is how quality drift starts.
+4. **Draft the skill** — propose
+   `.claude/skills/<name>/SKILL.md` (YAML frontmatter: name,
+   description with clear trigger conditions; body: numbered steps,
+   verification, known failure modes from this run).
+5. **Get approval** — show the full draft. Create the file only after
+   the user approves. Record the decision in `decisions.jsonl`.
+
+## Forbidden
+
+- No auto-creating skills without approval.
+- No distilling procedures whose success was never verified.
+- No secrets, tokens, or user-specific paths inside the skill body.
+- One skill per distinct procedure — do not merge unrelated recipes.

package/.claude/skills/guide-audit/SKILL.md

@@ -26,6 +26,20 @@ For each entry in RULES and ANTI-PATTERNS, run five checks:
 5. **Freshness** — when was it last seen actually working (blocking or
    catching a violation)? Cite `.harness/logs/tool_calls.jsonl` if evidence
    exists.
+6. **Contract verification** — if `.harness/state/predictions.jsonl`
+   exists, check every prediction whose window has elapsed
+   (`ts + window_days` in the past) deterministically:
+   count `predict_absent` matches among `PostToolUseFailure` entries in
+   `.harness/logs/tool_calls.jsonl` with a timestamp after `ts`.
+   - **0 matches** → the rule demonstrably worked: verdict *keep*, cite
+     the count.
+   - **matches at or near `baseline_count`** → the rule failed its
+     contract: verdict *delete candidate* or *convert-to-sensor candidate*
+     (a rule that didn't stop the failure needs a stronger layer, not
+     rewording).
+   - Report verified predictions in the output table and propose removing
+     their lines from predictions.jsonl (the contract is settled either
+     way). This check is grep-and-count, not judgment — show the numbers.
 
 ## Output Format
 

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

@@ -54,11 +54,15 @@ npx uni-harness uninstall --yes # キットの機構を削除、あなたのフ
 | ファイル | 役割 |
 |---|---|
 | `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回上限、超過でエスカレーション要求） |
-| `.claude/hooks/guard-pre-bash.sh` | 破壊的コマンドと検証バイパス（`--no-verify`）を実行前にブロック |
+| `.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/` | フックとインストーラーのセルフテスト |
@@ -70,8 +74,9 @@ npx uni-harness uninstall --yes # キットの機構を削除、あなたのフ
 |---|---|
 | `/harness-init` | リポジトリをスキャン → PROJECT セクションと commands.env を記入（インストール時に1回） |
 | `/checkpoint` | `.harness/state/` に状態を保存（plan.md / decisions.jsonl / progress.json） |
-| `/ratchet [ミス]` | 再現 → 分類 → ルール/センサー/権限を提案 → 検証（引数なし: ログ診断） |
-| `/guide-audit` | CLAUDE.md ルールの監査 — 維持 / 削除 / センサー化（月次） |
+| `/ratchet [ミス]` | 再現 → 分類 → ルール/センサー/権限を提案 → 検証（引数なし: ログ診断）。全提案に反証可能な予測（`predictions.jsonl`）を添付 |
+| `/guide-audit` | CLAUDE.md ルールの監査 — 維持 / 削除 / センサー化（月次）。過去の予測をログと照合検証し、効かなかったルールは証拠に基づいて削除 |
+| `/distill [成功]` | 成功側のラチェット: 完了したタスクをログから発掘し、再利用可能なプロジェクトスキルとして提案 |
 
 ## 推奨パーミッション（任意）
 
@@ -105,8 +110,11 @@ npx uni-harness uninstall --yes # キットの機構を削除、あなたのフ
   ルールへ。同じルール違反3回 → ガード/権限へ昇格。
 - **毎週:** `python3 harness/harness_report.py` でスコアカードを
   確認。繰り返しの失敗が見えたら `/ratchet` を実行。
+- **意味のある成功のあと:** 繰り返す手順なら `/distill` で
+  プロジェクトスキルにしてください。
 - **毎月:** `/guide-audit` で CLAUDE.md を監査 — センサーが既に
-  強制しているルールは削除し、矛盾はマージ。
+  強制しているルールは削除し、矛盾はマージ。各ルールの予測をログと
+  照合（同じ失敗が続いたルールは、感覚でなく数字で削除/昇格）。
 
 ## カスタマイズ
 

package/README.ko.md

@@ -52,11 +52,15 @@ npx uni-harness uninstall --yes # 킷 기계 부품 제거, 사용자 파일은
 | 파일 | 역할 |
 |---|---|
 | `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회 상한, 초과 시 에스컬레이션 강제) |
-| `.claude/hooks/guard-pre-bash.sh` | 파괴적 명령과 검증 우회(`--no-verify`)를 실행 전 차단 |
+| `.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/` | 훅·인스톨러 자체 테스트 |
@@ -68,8 +72,9 @@ npx uni-harness uninstall --yes # 킷 기계 부품 제거, 사용자 파일은
 |---|---|
 | `/harness-init` | 저장소 스캔 → PROJECT 섹션 & commands.env 채우기 (설치 시 1회) |
 | `/checkpoint` | `.harness/state/`에 상태 저장 (plan.md / decisions.jsonl / progress.json) |
-| `/ratchet [실수]` | 재현 → 분류 → 규칙/센서/권한 제안 → 검증 (인자 없이: 로그 진단) |
-| `/guide-audit` | CLAUDE.md 규칙 감사 — 유지 / 삭제 / 센서 전환 (월 1회) |
+| `/ratchet [실수]` | 재현 → 분류 → 규칙/센서/권한 제안 → 검증 (인자 없이: 로그 진단). 모든 제안에 반증 가능한 예측(`predictions.jsonl`)을 첨부 |
+| `/guide-audit` | CLAUDE.md 규칙 감사 — 유지 / 삭제 / 센서 전환 (월 1회); 과거 예측을 로그와 대조 검증해 안 통한 규칙은 증거로 삭제 |
+| `/distill [성공]` | 성공 쪽 래칫: 완료된 작업을 로그에서 발굴해 재사용 가능한 프로젝트 스킬로 제안 |
 
 ## 권장 권한 설정 (선택)
 
@@ -102,8 +107,11 @@ npx uni-harness uninstall --yes # 킷 기계 부품 제거, 사용자 파일은
   규칙 위반 3회 → 가드/권한으로 승격.
 - **매주:** `python3 harness/harness_report.py`로 스코어카드 확인;
   반복 실패가 보이면 `/ratchet` 실행.
+- **의미 있는 성공 후:** 반복될 절차라면 `/distill`로 프로젝트 스킬로
+  만드세요.
 - **매월:** `/guide-audit`으로 CLAUDE.md 감사 — 센서가 이미 강제하는
-  규칙은 삭제, 모순은 병합.
+  규칙은 삭제, 모순은 병합, 그리고 각 규칙의 예측을 로그와 대조
+  (같은 실패가 계속된 규칙은 감이 아니라 숫자로 삭제/승격).
 
 ## 커스터마이징
 

package/README.md

@@ -52,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 |
@@ -68,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)
 
@@ -103,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
 

package/README.zh-CN.md

@@ -51,11 +51,15 @@ node ≥16。
 | 文件 | 作用 |
 |---|---|
 | `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 次上限，超过则强制升级上报） |
-| `.claude/hooks/guard-pre-bash.sh` | 在执行前拦截破坏性命令与验证绕过（`--no-verify`） |
+| `.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` | 每个会话写入一行台账（时长、调用/失败/编辑数、收工拦截次数、测试状态）→ `sessions.jsonl` |
 | `.claude/hooks/observe-log.sh` | 以 JSONL 记录每次工具调用 + 绊线（同一失败 3 次、调用激增） |
 | `harness/harness_report.py` | 基于日志的健康记分卡 |
 | `harness/tests/` | 钩子与安装器的自测 |
@@ -67,8 +71,9 @@ node ≥16。
 |---|---|
 | `/harness-init` | 扫描仓库 → 填写 PROJECT 章节 & commands.env（安装时一次） |
 | `/checkpoint` | 将状态保存到 `.harness/state/`（plan.md / decisions.jsonl / progress.json） |
-| `/ratchet [失误]` | 复现 → 归类 → 提议规则/传感器/权限 → 验证（无参数：诊断日志） |
-| `/guide-audit` | 审计 CLAUDE.md 规则 — 保留 / 删除 / 转为传感器（每月） |
+| `/ratchet [失误]` | 复现 → 归类 → 提议规则/传感器/权限 → 验证（无参数：诊断日志）。每个提议附带可证伪的预测（`predictions.jsonl`） |
+| `/guide-audit` | 审计 CLAUDE.md 规则 — 保留 / 删除 / 转为传感器（每月）；将过往预测与日志比对验证，没起作用的规则凭证据删除 |
+| `/distill [成功]` | 成功侧的棘轮：从日志中挖掘已完成的任务，提议为可复用的项目技能 |
 
 ## 推荐权限配置（可选）
 
@@ -101,8 +106,11 @@ node ≥16。
   3 次 → 升级为守卫/权限。
 - **每周：** 用 `python3 harness/harness_report.py` 查看记分卡；
   出现重复失败就运行 `/ratchet`。
+- **一次有意义的成功之后：** 若流程还会重复，用 `/distill` 把它
+  变成项目技能。
 - **每月：** 用 `/guide-audit` 审计 CLAUDE.md — 删除传感器已自动
-  强制执行的规则，合并互相矛盾的规则。
+  强制执行的规则，合并互相矛盾的规则，并将每条规则的预测与日志
+  比对（同一失败仍在发生的规则，凭数字而非感觉删除或升级）。
 
 ## 自定义
 

package/bin/cli.js

@@ -229,7 +229,7 @@ function init(target, force) {
   }
 
   let claudeMdExisted = false;
-  for (const rel of ['CLAUDE.md', '.harness/commands.env']) {
+  for (const rel of ['CLAUDE.md', 'AGENTS.md', '.harness/commands.env']) {
     const dst = path.join(target, rel);
     if (fs.existsSync(dst)) {
       log('  = ' + rel + ' (existing file kept)');
@@ -304,6 +304,9 @@ function update(target, force) {
   writeManifest(target, files);
   ensureRuntimeDirs(target);
   migrateLegacyState(target);
+  // hooks added in newer kit versions need registering too — mergeSettings
+  // is append-only and idempotent, so this never disturbs user settings
+  mergeSettings(target);
   log(`\n${changed} file(s) updated (v${manifest.kitVersion} -> v${KIT_VERSION}). ` +
       'CLAUDE.md / commands.env / settings.json were not touched.');
 
@@ -360,7 +363,7 @@ function doctor(target) {
     const body = fs.readFileSync(sp, 'utf8');
     JSON.parse(body);
     check(true, '.claude/settings.json parses');
-    for (const h of ['guard-pre-bash.sh', 'sensor-post-edit.sh', 'stop-gate.sh', 'observe-log.sh', 'session-start.sh']) {
+    for (const h of ['guard-pre-bash.sh', 'guard-pre-edit.sh', 'sensor-post-edit.sh', 'stop-gate.sh', 'observe-log.sh', 'session-start.sh', 'pre-compact.sh', 'session-end.sh']) {
       if (!body.includes(h)) check(false, `hook registered: ${h}`, 'not in settings.json');
     }
   } catch { check(false, '.claude/settings.json', 'missing or failed to parse'); }

package/harness/harness_report.py

@@ -1,7 +1,9 @@
 #!/usr/bin/env python3
 """Harness health scorecard.
 
-Reads .harness/logs/tool_calls.jsonl and prints health metrics.
+Reads .harness/logs/tool_calls.jsonl (raw tool calls) and, if present,
+.harness/logs/sessions.jsonl (the per-session ledger written by
+session-end.sh) and prints health metrics.
 
 Usage:
     python3 harness/harness_report.py [--days 7]
@@ -79,6 +81,19 @@ def main() -> int:
                 print(f"  [{n}x] {tool}: {err}")
         print("\n  -> For failures repeated 2+ times, consider /ratchet to turn them into rules.")
 
+    ledger = load(root / ".harness" / "logs" / "sessions.jsonl", since)
+    if ledger:
+        clean = sum(1 for e in ledger if e.get("tests_clean"))
+        blocked = sum(e.get("stop_blocks") or 0 for e in ledger)
+        durations = sorted(e.get("duration_s") or 0 for e in ledger)
+        print("\n─ Session ledger ─")
+        print(f"  Ended sessions:        {len(ledger)}")
+        print(f"  Tests clean at end:    {clean}/{len(ledger)}")
+        print(f"  Stop-gate blocks:      {blocked}")
+        print(f"  Duration (median):     {durations[len(durations) // 2]}s")
+        if clean < len(ledger):
+            print("  -> Sessions ending with untested edits are quality-drift risk; check why.")
+
     print("\n─ How to read this ─")
     print("  · Is the failure rate trending down week over week?")
     print("  · The same failure signature next week means the ratchet isn't working")

package/harness/tests/test_hooks.sh

@@ -44,6 +44,55 @@ OUT=$(echo '{"tool_name":"Bash","tool_input":{"command":"git push --force-with-l
 check "allows force-with-lease" "EMPTY" "$OUT"
 OUT=$(echo '{"tool_name":"Bash","tool_input":{"command":"git status"}}' | bash "$HOOKS/guard-pre-bash.sh")
 check "passes safe commands" "EMPTY" "$OUT"
+# state-aware commit gate: pending_test marker + configured TEST_CMD -> ask
+printf 'LINT_CMD=""\nTEST_CMD="true"\n' > "$TMP/.harness/commands.env"
+echo "a.py" > "$TMP/.harness/logs/pending_test.s1"
+OUT=$(echo '{"tool_name":"Bash","session_id":"s1","tool_input":{"command":"git commit -m wip"}}' | bash "$HOOKS/guard-pre-bash.sh")
+check "asks on commit with untested edits" '"permissionDecision": "ask"' "$OUT"
+OUT=$(echo '{"tool_name":"Bash","session_id":"s2","tool_input":{"command":"git commit -m ok"}}' | bash "$HOOKS/guard-pre-bash.sh")
+check "allows commit in a session without pending edits" "EMPTY" "$OUT"
+printf 'LINT_CMD=""\nTEST_CMD=""\n' > "$TMP/.harness/commands.env"
+OUT=$(echo '{"tool_name":"Bash","session_id":"s1","tool_input":{"command":"git commit -m x"}}' | bash "$HOOKS/guard-pre-bash.sh")
+check "commit gate silent when TEST_CMD unconfigured" "EMPTY" "$OUT"
+rm -f "$TMP/.harness/logs/pending_test.s1"
+
+# ── guard-pre-edit.sh ────────────────────────────────────────────
+echo "guard-pre-edit.sh"
+fresh_project
+OUT=$(echo '{"tool_name":"Edit","tool_input":{"file_path":"'"$TMP"'/.claude/settings.json","old_string":"a","new_string":"b"}}' | bash "$HOOKS/guard-pre-edit.sh")
+check "asks on harness machinery edit" '"permissionDecision": "ask"' "$OUT"
+OUT=$(echo '{"tool_name":"Write","tool_input":{"file_path":"'"$TMP"'/.harness/state/progress.json","content":"{}"}}' | bash "$HOOKS/guard-pre-edit.sh")
+check "allows checkpoint writes" "EMPTY" "$OUT"
+OUT=$(echo '{"tool_name":"Edit","tool_input":{"file_path":"'"$TMP"'/src/app.py","old_string":"a","new_string":"b"}}' | bash "$HOOKS/guard-pre-edit.sh")
+check "allows normal source edits" "EMPTY" "$OUT"
+OUT=$(echo '{"tool_name":"Edit","tool_input":{"file_path":"'"$TMP"'/.env","old_string":"a","new_string":"b"}}' | bash "$HOOKS/guard-pre-edit.sh")
+check "asks on env file edit" '"permissionDecision": "ask"' "$OUT"
+OUT=$(echo '{"tool_name":"Edit","tool_input":{"file_path":"'"$TMP"'/vite.config.ts","old_string":"a","new_string":"b"}}' | bash "$HOOKS/guard-pre-edit.sh")
+check "asks on tool config edit" '"permissionDecision": "ask"' "$OUT"
+OUT=$(echo '{"tool_name":"Edit","tool_input":{"file_path":"'"$TMP"'/tests/test_app.py","old_string":"def test_a():","new_string":"@pytest.mark.skip\ndef test_a():"}}' | bash "$HOOKS/guard-pre-edit.sh")
+check "asks on added skip marker" "skip" "$OUT"
+OUT=$(echo '{"tool_name":"Edit","tool_input":{"file_path":"'"$TMP"'/src/api.test.ts","old_string":"it(\"works\", () => {","new_string":"it.skip(\"works\", () => {"}}' | bash "$HOOKS/guard-pre-edit.sh")
+check "asks on it.skip in js tests" '"permissionDecision": "ask"' "$OUT"
+mkdir -p "$TMP/tests"
+printf 'def test_a():\n    pass\ndef test_b():\n    pass\n' > "$TMP/tests/test_app.py"
+OUT=$(echo '{"tool_name":"Write","tool_input":{"file_path":"'"$TMP"'/tests/test_app.py","content":"def test_a():\n    pass\n"}}' | bash "$HOOKS/guard-pre-edit.sh")
+check "asks on removed test function" "removes 1 test function" "$OUT"
+OUT=$(echo '{"tool_name":"Edit","tool_input":{"file_path":"'"$TMP"'/tests/test_app.py","old_string":"def test_a():","new_string":"def test_a():\ndef test_c():"}}' | bash "$HOOKS/guard-pre-edit.sh")
+check "allows adding tests" "EMPTY" "$OUT"
+OUT=$(echo '{"tool_name":"Write","tool_input":{"file_path":"'"$TMP"'/tests/test_new.py","content":"def test_x():\n    pass\n"}}' | bash "$HOOKS/guard-pre-edit.sh")
+check "allows brand-new test file" "EMPTY" "$OUT"
+OUT=$(echo '{"tool_name":"Edit","tool_input":{"file_path":"/somewhere/else/test_x.py","old_string":"def test_a():","new_string":""}}' | bash "$HOOKS/guard-pre-edit.sh")
+check "ignores files outside the project" "EMPTY" "$OUT"
+
+# ── pre-compact.sh ───────────────────────────────────────────────
+echo "pre-compact.sh"
+fresh_project
+mkdir -p "$TMP/.harness/state"
+echo '{"task_id":"t1"}' > "$TMP/.harness/state/progress.json"
+OUT=$(echo '{"hook_event_name":"PreCompact","session_id":"s1","trigger":"auto"}' | bash "$HOOKS/pre-compact.sh")
+check "emits no JSON (PreCompact schema has no context channel)" "EMPTY" "$OUT"
+check "snapshots checkpoint" "yes" "$([ -f "$TMP/.harness/state/.pre-compact-backup/progress.json" ] && echo yes)"
+check "logs the compaction event" "PreCompact" "$(cat "$TMP/.harness/logs/tool_calls.jsonl")"
 
 # ── observe-log.sh ───────────────────────────────────────────────
 echo "observe-log.sh"
@@ -53,11 +102,16 @@ LINES=$(wc -l < "$TMP/.harness/logs/tool_calls.jsonl" | tr -d ' ')
 check "logs one call" "1" "$LINES"
 echo '{"hook_event_name":"PostToolUse","session_id":"s1","tool_name":"Edit","tool_input":{"file_path":"a.py"},"agent_id":"x1","agent_type":"code-reviewer"}' | bash "$HOOKS/observe-log.sh" > /dev/null
 check "records subagent fields" "code-reviewer" "$(tail -1 "$TMP/.harness/logs/tool_calls.jsonl")"
-OUT=""
-for _ in 1 2 3; do
-  OUT=$(echo '{"hook_event_name":"PostToolUseFailure","session_id":"s1","tool_name":"Bash","tool_input":{"command":"pytest"},"tool_response":"E: same error"}' | bash "$HOOKS/observe-log.sh")
-done
-check "tripwire on 3 identical failures" "The same tool failed" "$OUT"
+# same error 3x — line numbers differ (normalization) and a success is
+# interleaved (no longer requires "in a row")
+OUT=$(echo '{"hook_event_name":"PostToolUseFailure","session_id":"s1","tool_name":"Bash","tool_input":{"command":"pytest"},"tool_response":"E: boom at line 12"}' | bash "$HOOKS/observe-log.sh")
+check "no tripwire on first failure" "EMPTY" "$OUT"
+echo '{"hook_event_name":"PostToolUse","session_id":"s1","tool_name":"Read","tool_input":{"file_path":"a.py"}}' | bash "$HOOKS/observe-log.sh" > /dev/null
+OUT=$(echo '{"hook_event_name":"PostToolUseFailure","session_id":"s1","tool_name":"Bash","tool_input":{"command":"pytest"},"tool_response":"E: boom at line 34"}' | bash "$HOOKS/observe-log.sh")
+OUT=$(echo '{"hook_event_name":"PostToolUseFailure","session_id":"s1","tool_name":"Bash","tool_input":{"command":"pytest"},"tool_response":"E: boom at line 56"}' | bash "$HOOKS/observe-log.sh")
+check "tripwire on 3 normalized repeats" "escalation packet" "$OUT"
+OUT=$(echo '{"hook_event_name":"PostToolUseFailure","session_id":"s1","tool_name":"Bash","tool_input":{"command":"npm test"},"tool_response":"E: different failure"}' | bash "$HOOKS/observe-log.sh")
+check "no tripwire on a different error" "EMPTY" "$OUT"
 
 # ── sensor-post-edit.sh ──────────────────────────────────────────
 echo "sensor-post-edit.sh"
@@ -96,46 +150,90 @@ OUT=$(echo '{"session_id":"s1"}' | bash "$HOOKS/stop-gate.sh")
 check "silent when tests pass" "EMPTY" "$OUT"
 [ -f "$TMP/.harness/logs/pending_test.s1" ] && MARKER_LEFT="yes" || MARKER_LEFT=""
 check "clears marker on pass" "EMPTY" "$MARKER_LEFT"
+# trace rules: require-before-stop blocks once, then lets the stop pass
+fresh_project
+printf 'LINT_CMD=""\nTEST_CMD="true"\n' > "$TMP/.harness/commands.env"
+printf '# comment line\nrequire-before-stop npm.run.build Run the build before ending the turn.\n' > "$TMP/.harness/trace.rules"
+echo "a.py" > "$TMP/.harness/logs/pending_test.s1"
+echo '{"ts":"2026-01-01T00:00:00","session_id":"s1","event":"PostToolUse","tool":"Edit","summary":"a.py"}' > "$TMP/.harness/logs/tool_calls.jsonl"
+OUT=$(echo '{"session_id":"s1"}' | bash "$HOOKS/stop-gate.sh")
+check "trace rule blocks on missing required step" "trace rule" "$OUT"
+OUT=$(echo '{"session_id":"s1"}' | bash "$HOOKS/stop-gate.sh")
+check "trace rule blocks only once per session" "EMPTY" "$OUT"
+echo "a.py" > "$TMP/.harness/logs/pending_test.s2"
+echo '{"ts":"2026-01-01T00:01:00","session_id":"s2","event":"PostToolUse","tool":"Bash","summary":"npm run build"}' >> "$TMP/.harness/logs/tool_calls.jsonl"
+OUT=$(echo '{"session_id":"s2"}' | bash "$HOOKS/stop-gate.sh")
+check "trace rule satisfied by matching log entry" "EMPTY" "$OUT"
+rm -f "$TMP/.harness/trace.rules"
+
+# ── session-end.sh ───────────────────────────────────────────────
+echo "session-end.sh"
+fresh_project
+OUT=$(echo '{"hook_event_name":"SessionEnd","session_id":"s9","reason":"exit"}' | bash "$HOOKS/session-end.sh")
+check "silent with no session activity" "EMPTY" "$([ -f "$TMP/.harness/logs/sessions.jsonl" ] && echo present)"
+cat > "$TMP/.harness/logs/tool_calls.jsonl" <<'EOF'
+{"ts":"2026-01-01T10:00:00","session_id":"s9","event":"PostToolUse","tool":"Bash","summary":"ls"}
+{"ts":"2026-01-01T10:05:00","session_id":"s9","event":"PostToolUse","tool":"Edit","summary":"a.py"}
+{"ts":"2026-01-01T10:06:00","session_id":"s9","event":"PostToolUseFailure","tool":"Bash","error":"boom"}
+{"ts":"2026-01-01T10:07:00","session_id":"other","event":"PostToolUse","tool":"Bash","summary":"ls"}
+EOF
+echo "a.py" > "$TMP/.harness/logs/pending_test.s9"
+echo "2" > "$TMP/.harness/logs/stop_blocks.s9"
+OUT=$(echo '{"hook_event_name":"SessionEnd","session_id":"s9","reason":"exit"}' | bash "$HOOKS/session-end.sh")
+ROW=$(cat "$TMP/.harness/logs/sessions.jsonl" 2>/dev/null)
+check "writes one ledger row" '"session_id": "s9"' "$ROW"
+check "counts calls for this session only" '"calls": 3' "$ROW"
+check "counts failures and edits" '"failures": 1' "$ROW"
+check "records duration" '"duration_s": 360' "$ROW"
+check "records unclean test state" '"tests_clean": false' "$ROW"
+check "records stop blocks" '"stop_blocks": 2' "$ROW"
+[ -f "$TMP/.harness/logs/pending_test.s9" ] && LEFT="yes" || LEFT=""
+check "cleans session marker files" "EMPTY" "$LEFT"
 
 # ── session-start.sh ─────────────────────────────────────────────
 echo "session-start.sh"
 fresh_project
-OUT=$(bash "$HOOKS/session-start.sh")
+OUT=$(echo '{"hook_event_name":"SessionStart","source":"startup"}' | bash "$HOOKS/session-start.sh")
 check "silent without checkpoint" "EMPTY" "$OUT"
 mkdir -p "$TMP/.harness/state"
 echo '{"task_id":"t1","status":"in_progress","next_step":"do X"}' > "$TMP/.harness/state/progress.json"
-OUT=$(bash "$HOOKS/session-start.sh")
+OUT=$(echo '{"hook_event_name":"SessionStart","source":"startup"}' | bash "$HOOKS/session-start.sh")
 check "injects in-progress checkpoint" ".harness/state" "$OUT"
 echo '{"task_id":"t1","status":"completed"}' > "$TMP/.harness/state/progress.json"
-OUT=$(bash "$HOOKS/session-start.sh")
+OUT=$(echo '{"hook_event_name":"SessionStart","source":"startup"}' | bash "$HOOKS/session-start.sh")
 check "skips completed checkpoint" "EMPTY" "$OUT"
 rm "$TMP/.harness/state/progress.json"
 # legacy layout (pre-v0.2): checkpoint at the project root still read
 echo '{"task_id":"t1","status":"in_progress","next_step":"do X"}' > "$TMP/progress.json"
-OUT=$(bash "$HOOKS/session-start.sh")
+OUT=$(echo '{"hook_event_name":"SessionStart","source":"startup"}' | 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")
+OUT=$(echo '{"hook_event_name":"SessionStart","source":"startup"}' | 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")
+OUT=$(echo '{"hook_event_name":"SessionStart","source":"startup"}' | 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"
 done
-OUT=$(bash "$HOOKS/session-start.sh")
+OUT=$(echo '{"hook_event_name":"SessionStart","source":"startup"}' | bash "$HOOKS/session-start.sh")
 check "nudges /ratchet on accumulated failures" "/ratchet" "$OUT"
 fresh_project
 printf 'LINT_CMD=""\nTEST_CMD=""\n' > "$TMP/.harness/commands.env"
-OUT=$(bash "$HOOKS/session-start.sh")
+OUT=$(echo '{"hook_event_name":"SessionStart","source":"startup"}' | bash "$HOOKS/session-start.sh")
 check "offers /harness-init when unconfigured" "/harness-init" "$OUT"
 printf 'LINT_CMD="true"\nTEST_CMD=""\n' > "$TMP/.harness/commands.env"
-OUT=$(bash "$HOOKS/session-start.sh")
+OUT=$(echo '{"hook_event_name":"SessionStart","source":"startup"}' | bash "$HOOKS/session-start.sh")
 check "no setup nudge once configured" "EMPTY" "$OUT"
+# resuming right after a compaction -> checkpoint-refresh instruction
+# (pre-compact.sh cannot inject context; this is the supported channel)
+mkdir -p "$TMP/.harness/state/.pre-compact-backup"
+OUT=$(echo '{"hook_event_name":"SessionStart","source":"compact"}' | bash "$HOOKS/session-start.sh")
+check "instructs checkpoint refresh after compaction" "pre-compact-backup" "$OUT"
 
 # ── result ───────────────────────────────────────────────────────
 echo

package/harness/tests/test_installer.sh

@@ -35,6 +35,7 @@ check "installs hooks" "yes" "$([ -f "$TGT/.claude/hooks/stop-gate.sh" ] && echo
 check "hooks are executable" "yes" "$([ -x "$TGT/.claude/hooks/stop-gate.sh" ] && echo yes)"
 check "installs skills" "yes" "$([ -f "$TGT/.claude/skills/ratchet/SKILL.md" ] && echo yes)"
 check "installs CLAUDE.md" "yes" "$([ -f "$TGT/CLAUDE.md" ] && echo yes)"
+check "installs AGENTS.md" "yes" "$([ -f "$TGT/AGENTS.md" ] && echo yes)"
 check "installs settings.json" "yes" "$([ -f "$TGT/.claude/settings.json" ] && echo yes)"
 check "writes manifest" "yes" "$([ -f "$TGT/.harness/kit-manifest.json" ] && echo yes)"
 check "gitignores logs" ".harness/logs/" "$(cat "$TGT/.gitignore")"
@@ -50,6 +51,7 @@ check "does not ship test_installer.sh" "EMPTY" "$([ -f "$TGT/harness/tests/test
 echo "init (brownfield)"
 BF=$(mktemp -d)
 echo "MY PROJECT RULES" > "$BF/CLAUDE.md"
+echo "MY OWN AGENTS FILE" > "$BF/AGENTS.md"
 echo "node_modules/" > "$BF/.gitignore"
 mkdir -p "$BF/.claude"
 cat > "$BF/.claude/settings.json" <<'EOF'
@@ -64,6 +66,7 @@ cat > "$BF/.claude/settings.json" <<'EOF'
 EOF
 OUT=$(node "$CLI" init "$BF" 2>&1)
 check "keeps existing CLAUDE.md" "MY PROJECT RULES" "$(cat "$BF/CLAUDE.md")"
+check "keeps existing AGENTS.md" "MY OWN AGENTS FILE" "$(cat "$BF/AGENTS.md")"
 check "notes CLAUDE.md was kept" "existing CLAUDE.md was kept" "$OUT"
 check "keeps user permissions" '"Read"' "$(cat "$BF/.claude/settings.json")"
 check "keeps user's own hook" "my-own-hook.sh" "$(cat "$BF/.claude/settings.json")"
@@ -108,6 +111,20 @@ sed -i.bak '/.harness\/state/d' "$TGT/.gitignore" && rm -f "$TGT/.gitignore.bak"
 OUT=$(node "$CLI" update "$TGT" 2>&1)
 check "update re-adds state gitignore entry" ".harness/state/" "$(cat "$TGT/.gitignore")"
 
+# update on an install from before a hook existed must register the new
+# hook in settings.json (mergeSettings runs on update too, append-only)
+python3 - "$TGT" <<'EOF'
+import json, sys, os
+sp = os.path.join(sys.argv[1], '.claude/settings.json')
+s = json.load(open(sp))
+s['hooks'].pop('SessionEnd', None)
+s['user_marker'] = 'kept'
+json.dump(s, open(sp, 'w'), indent=2)
+EOF
+OUT=$(node "$CLI" update "$TGT" 2>&1)
+check "update registers newly shipped hooks" "session-end.sh" "$(cat "$TGT/.claude/settings.json")"
+check "update merge keeps user settings" '"user_marker"' "$(cat "$TGT/.claude/settings.json")"
+
 # pre-v0.2 CLAUDE.md pointing checkpoints at the project root -> migration
 # note (told, never touched); the current template must NOT trigger it
 printf '# old project\n- read progress.json first\n' > "$TGT/CLAUDE.md"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uni-harness",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "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"
@@ -8,6 +8,7 @@
   "files": [
     "bin",
     "CLAUDE.md",
+    "AGENTS.md",
     ".claude",
     ".harness/commands.env",
     "harness",