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

package/.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