uni-harness 0.1.0

package/.claude/agents/TEMPLATE.md

@@ -0,0 +1,64 @@
+---
+# ── Custom agent template (this file itself is inactive) ────────
+# Claude Code treats a file without a `name` in its frontmatter as
+# documentation and ignores it. To create an agent: copy this file →
+# uncomment and fill the fields below → replace the body with that
+# agent's system prompt.
+#
+#   name:            lowercase-hyphen identifier (becomes the call name) [required]
+#   description:     WHEN to delegate to this agent — the main agent
+#                    reads this sentence to decide auto-delegation [required]
+#   tools:           allowed tools (omit to inherit all)
+#   disallowedTools: explicit denials (take precedence over tools)
+#   model:           sonnet | opus | haiku (omit to inherit)
+#
+# name: code-reviewer
+# description: Reviews code changes in a fresh context, without seeing the implementation process. Use after finishing a feature or fix, before commit/PR. Judges plan compliance and defects, and reports.
+# tools: Read, Grep, Glob, Bash
+#
+# Note: creating the first active agent in agents/ requires one session
+# restart. The harness hooks and permissions apply to agent tool calls too.
+# ────────────────────────────────────────────────────────────────
+---
+
+The body below is the system prompt of the example (fresh-context code
+reviewer). Replace it entirely when creating a new agent.
+
+---
+
+You are a code reviewer. You see only the result, not the implementer's
+reasoning — that is your value. Find what the implementer missed, without
+inheriting their assumptions.
+
+## Procedure
+
+1. Read the full change via `git diff` (or the scope you were given).
+2. If `plan.md` exists, read it and check the change against the plan and
+   requirements.
+3. Read enough surrounding code to judge each change in context.
+4. If `.harness/commands.env` has a TEST_CMD, run it and check the result.
+
+## Judging Criteria (in priority order)
+
+1. **Compliance**: implemented differently from the plan/requirements, or
+   requirements missing
+2. **Defects**: code that produces wrong results or crashes on real input —
+   report only what you can pair with a concrete failure scenario
+3. **Verification gaps**: changed behavior that no test covers
+4. **Simplification**: duplication replaceable by existing code (only when
+   confident)
+
+## Rules
+
+- Report only. Never modify code.
+- Anchor every finding to `file:line` with evidence. If it's speculation,
+  say so.
+- If there is nothing to report, say so. Never invent findings to fill space.
+- No style preferences — that's the linter's job.
+
+## Output Format
+
+- **Verdict**: approvable / needs changes (one-line rationale)
+- **Findings**: ordered by severity, each with location, problem, evidence,
+  failure scenario
+- **Scope checked**: files read, verification commands run and their results

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

@@ -0,0 +1,46 @@
+#!/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
+# ════════════════════════════════════════════════════════════════
+set -euo pipefail
+
+INPUT=$(cat)
+
+python3 - "$INPUT" <<'PYEOF'
+import json, re, sys
+
+data = json.loads(sys.argv[1])
+cmd = (data.get("tool_input") or {}).get("command", "") or ""
+
+# DENY: irreversible/destructive patterns (extend per project as needed)
+DENY_PATTERNS = [
+    (r"\brm\s+(-[a-zA-Z]*[rf][a-zA-Z]*\s+)+(/|\$HOME|~)(\s|$)", "recursive delete of root/home directory"),
+    (r"\bgit\s+push\s+.*--force(?!-with-lease)", "--force push (use --force-with-lease if needed)"),
+    (r"\bgit\s+reset\s+--hard\s+origin/", "hard reset to remote (loses all local changes)"),
+    (r"\bgit\s+(commit|push)\b[^|;&]*--no-verify\b", "bypassing verification hooks with --no-verify"),
+    (r"\bDROP\s+(TABLE|DATABASE)\b", "destructive database command"),
+    (r"\bchmod\s+(-[a-zA-Z]+\s+)*777\b", "opening full permissions (chmod 777)"),
+    (r"curl[^|;&]*\|\s*(sudo\s+)?(ba)?sh", "piping a remote script into a shell"),
+    (r"wget[^|;&]*\|\s*(sudo\s+)?(ba)?sh", "piping a remote script into a shell"),
+    (r">\s*/dev/sd[a-z]", "writing directly to a block device"),
+    (r"\bmkfs\b", "formatting a filesystem"),
+]
+
+for pattern, reason in DENY_PATTERNS:
+    if re.search(pattern, cmd, re.IGNORECASE):
+        print(json.dumps({
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason":
+                    f"[harness guard] Blocked: {reason}. "
+                    "If this action is truly needed, ask the user to run it directly."
+            }
+        }))
+        sys.exit(0)
+
+# No match -> exit silently (normal permission flow)
+sys.exit(0)
+PYEOF

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

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# ════════════════════════════════════════════════════════════════
+# 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
+# ════════════════════════════════════════════════════════════════
+set -uo pipefail
+
+INPUT=$(cat)
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+LOG_DIR="$PROJECT_DIR/.harness/logs"
+mkdir -p "$LOG_DIR"
+
+python3 - "$INPUT" "$LOG_DIR" <<'PYEOF'
+import json, sys, datetime, collections
+
+data = json.loads(sys.argv[1])
+log_dir = sys.argv[2]
+log_path = f"{log_dir}/tool_calls.jsonl"
+
+event = data.get("hook_event_name", "")
+entry = {
+    "ts": datetime.datetime.now().isoformat(timespec="seconds"),
+    "session_id": data.get("session_id", ""),
+    "event": event,
+    "tool": data.get("tool_name", ""),
+}
+# If the call came from a subagent, record which one (for /ratchet diagnosis)
+for k in ("agent_id", "agent_type"):
+    if data.get(k):
+        entry[k] = data[k]
+ti = data.get("tool_input") or {}
+# Privacy/size: log only a summary of the input
+if "command" in ti:
+    entry["summary"] = str(ti["command"])[:200]
+elif "file_path" in ti:
+    entry["summary"] = str(ti["file_path"])[:200]
+
+if event == "PostToolUseFailure":
+    resp = data.get("tool_response") or data.get("error") or {}
+    entry["error"] = str(resp)[:300]
+
+with open(log_path, "a") as f:
+    f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+# ── tripwire checks ──────────────────────────────────────────
+session = data.get("session_id", "")
+lines = []
+try:
+    with open(log_path) as f:
+        for line in f:
+            try:
+                e = json.loads(line)
+                if e.get("session_id") == session:
+                    lines.append(e)
+            except Exception:
+                pass
+except Exception:
+    lines = []
+
+warnings = []
+
+# (1) per-session tool-call ceiling (default 300, warn every 100)
+n = len(lines)
+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.")
+
+if warnings:
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": event,
+            "additionalContext": "[harness tripwire] " + " ".join(warnings)
+        }
+    }, ensure_ascii=False))
+PYEOF
+exit 0

package/.claude/hooks/sensor-post-edit.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# ════════════════════════════════════════════════════════════════
+# PostToolUse(Edit|Write) verification sensor
+# When a code file is modified: (1) run lint immediately and feed
+# failures back to Claude, (2) record the file in the per-session
+# pending_test marker. Tests run in batch at turn end (stop-gate.sh).
+# Commands come from .harness/commands.env (LINT_CMD/TEST_CMD).
+# ════════════════════════════════════════════════════════════════
+set -uo pipefail
+
+INPUT=$(cat)
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+ENV_FILE="$PROJECT_DIR/.harness/commands.env"
+LOG_DIR="$PROJECT_DIR/.harness/logs"
+
+# Commands not configured -> pass silently (harness not set up yet)
+[ -f "$ENV_FILE" ] || exit 0
+# shellcheck disable=SC1090
+source "$ENV_FILE"
+
+FILE_PATH=$(python3 -c '
+import json,sys
+d=json.loads(sys.argv[1])
+print((d.get("tool_input") or {}).get("file_path",""))' "$INPUT" 2>/dev/null || echo "")
+SESSION_ID=$(python3 -c '
+import json,sys
+print(json.loads(sys.argv[1]).get("session_id",""))' "$INPUT" 2>/dev/null || echo "")
+
+# Not a code file -> pass (don't run verification on docs/config edits)
+case "$FILE_PATH" in
+  *.py|*.ts|*.tsx|*.js|*.jsx|*.go|*.rs|*.java|*.rb|*.c|*.cpp|*.h|*.cs) ;;
+  *) exit 0 ;;
+esac
+
+# Record for the turn-end test gate (stop-gate.sh)
+if [ -n "$SESSION_ID" ]; then
+  mkdir -p "$LOG_DIR"
+  printf '%s\n' "$FILE_PATH" >> "$LOG_DIR/pending_test.$SESSION_ID"
+fi
+
+# Lint is fast, so run it immediately (timeout may be absent on macOS)
+TIMEOUT_BIN=$(command -v timeout || command -v gtimeout || true)
+if [ -n "${LINT_CMD:-}" ]; then
+  LINT_OUT=$(cd "$PROJECT_DIR" && ${TIMEOUT_BIN:+"$TIMEOUT_BIN" 120} bash -c "$LINT_CMD" 2>&1 | tail -40)
+  LINT_RC=$?
+  if [ "$LINT_RC" -ne 0 ]; then
+    python3 - "[LINT FAILED rc=$LINT_RC]
+$LINT_OUT" <<'PYEOF'
+import json, sys
+ctx = ("[harness sensor] The code you just modified failed lint. "
+       "Read the output below and fix it. This work is not done until it passes.\n"
+       + sys.argv[1])
+print(json.dumps({
+    "hookSpecificOutput": {
+        "hookEventName": "PostToolUse",
+        "additionalContext": ctx[:8000]
+    }
+}))
+PYEOF
+  fi
+fi
+exit 0

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

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# ════════════════════════════════════════════════════════════════
+# SessionStart context injection (startup|resume|clear|compact)
+# (1) If an in-progress checkpoint (progress.json) exists, surface
+#     it so completed steps aren't repeated. Re-injected after
+#     compaction too.
+# (2) If tool failures have piled up in the last 7 days of logs,
+#     suggest running /ratchet.
+# (3) If the harness is installed but unconfigured (commands.env has
+#     no commands), have Claude offer to run /harness-init.
+# ════════════════════════════════════════════════════════════════
+set -uo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+python3 - "$PROJECT_DIR" <<'PYEOF'
+import json, sys, os, datetime
+
+proj = sys.argv[1]
+parts = []
+
+# (3) harness installed but not configured -> offer /harness-init
+# (checked first so a fresh install greets the user with setup)
+try:
+    import re
+    with open(os.path.join(proj, ".harness/commands.env")) as f:
+        env = f.read()
+    if not re.search(r'^(LINT_CMD|TEST_CMD)=".+"', env, re.M):
+        parts.append(
+            "[harness] The harness is installed but not configured: "
+            ".harness/commands.env has no LINT_CMD/TEST_CMD, so the "
+            "verification sensors are inactive. Offer the user to run "
+            "/harness-init — it scans the repo, verifies the build/test/lint "
+            "commands by running them, and proposes the config as a diff for "
+            "approval. If the sensors are off intentionally, they can ignore this.")
+except Exception:
+    pass
+
+# (1) in-progress checkpoint
+try:
+    with open(os.path.join(proj, "progress.json")) as f:
+        ckpt = json.load(f)
+    if ckpt.get("status") not in ("completed", "abandoned"):
+        parts.append(
+            "[harness memory] An in-progress checkpoint exists. Before starting "
+            "work, read progress.json / plan.md / decisions.jsonl, do not repeat "
+            "completed steps, and resume from the next step.\n"
+            f"Checkpoint summary: {json.dumps(ckpt, ensure_ascii=False)[:1500]}")
+except Exception:
+    pass
+
+# (2) accumulated failures in the last 7 days -> nudge toward /ratchet
+try:
+    cutoff = datetime.datetime.now() - datetime.timedelta(days=7)
+    n = 0
+    with open(os.path.join(proj, ".harness/logs/tool_calls.jsonl")) as f:
+        for line in f:
+            try:
+                e = json.loads(line)
+            except Exception:
+                continue
+            if e.get("event") != "PostToolUseFailure":
+                continue
+            try:
+                ts = datetime.datetime.fromisoformat(e.get("ts", ""))
+            except Exception:
+                continue
+            if ts >= cutoff:
+                n += 1
+    if n >= 3:
+        parts.append(
+            f"[harness] The logs record {n} tool failures in the last 7 days. "
+            "If you see a repeating pattern, consider running /ratchet to turn "
+            "it into a rule/sensor. (Ignore if already handled.)")
+except Exception:
+    pass
+
+if parts:
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": "\n".join(parts)
+        }
+    }, ensure_ascii=False))
+PYEOF
+exit 0

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

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# ════════════════════════════════════════════════════════════════
+# Stop test gate
+# If code was modified this session (pending_test marker), run
+# TEST_CMD in batch before the turn ends. On failure, block the
+# 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).
+# ════════════════════════════════════════════════════════════════
+set -uo pipefail
+
+INPUT=$(cat)
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+ENV_FILE="$PROJECT_DIR/.harness/commands.env"
+LOG_DIR="$PROJECT_DIR/.harness/logs"
+
+SESSION_ID=$(python3 -c '
+import json,sys
+print(json.loads(sys.argv[1]).get("session_id",""))' "$INPUT" 2>/dev/null || echo "")
+[ -n "$SESSION_ID" ] || exit 0
+
+MARKER="$LOG_DIR/pending_test.$SESSION_ID"
+COUNTER="$LOG_DIR/stop_blocks.$SESSION_ID"
+
+# No code modified this session -> pass
+[ -s "$MARKER" ] || exit 0
+
+# Not configured -> pass silently (the harness must not break the work itself)
+[ -f "$ENV_FILE" ] || exit 0
+# shellcheck disable=SC1090
+source "$ENV_FILE"
+if [ -z "${TEST_CMD:-}" ]; then
+  rm -f "$MARKER"
+  exit 0
+fi
+
+# timeout may be absent on macOS — use it only if available
+TIMEOUT_BIN=$(command -v timeout || command -v gtimeout || true)
+TEST_OUT=$(cd "$PROJECT_DIR" && ${TIMEOUT_BIN:+"$TIMEOUT_BIN" 600} bash -c "$TEST_CMD" 2>&1 | tail -60)
+TEST_RC=$?
+
+if [ "$TEST_RC" -eq 0 ]; then
+  rm -f "$MARKER" "$COUNTER"
+  exit 0
+fi
+
+COUNT=0
+[ -f "$COUNTER" ] && COUNT=$(cat "$COUNTER" 2>/dev/null || echo 0)
+COUNT=$((COUNT + 1))
+
+if [ "$COUNT" -ge 3 ]; then
+  # Retry ceiling reached: let the next stop through, but demand escalation
+  rm -f "$MARKER" "$COUNTER"
+  REASON="[harness stop-gate] This is the 3rd attempt to end the turn with \
+failing tests. Stop repeating fix attempts. Write the escalation packet from \
+the Work Loop section of CLAUDE.md, report it to the user, then stop.
+$TEST_OUT"
+else
+  echo "$COUNT" > "$COUNTER"
+  REASON="[harness stop-gate] Code modified in this session does not pass \
+tests (rc=$TEST_RC, block $COUNT/3). Read the output below, fix it, then stop.
+$TEST_OUT"
+fi
+
+python3 - "$REASON" <<'PYEOF'
+import json, sys
+print(json.dumps({"decision": "block", "reason": sys.argv[1][:8000]},
+                 ensure_ascii=False))
+PYEOF
+exit 0

package/.claude/settings.json

@@ -0,0 +1,76 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-pre-bash.sh",
+            "timeout": 15,
+            "statusMessage": "harness: command safety check"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/sensor-post-edit.sh",
+            "timeout": 180,
+            "statusMessage": "harness: lint sensor"
+          }
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/observe-log.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/observe-log.sh",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/stop-gate.sh",
+            "timeout": 720,
+            "statusMessage": "harness: pre-stop test gate"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/session-start.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude/skills/checkpoint/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: checkpoint
+description: Save current work state to plan.md / decisions.jsonl / progress.json checkpoints. Use after completing a meaningful step, before pausing a long task, or when the user invokes /checkpoint.
+---
+
+# Checkpoint — Saving Work State
+
+The filesystem is the memory. Maintain these three files at the project root.
+The single test: **if this session died right now, could the next session
+pick up where it left off?**
+
+## Procedure
+
+1. **plan.md** — update if the plan changed. Format:
+   ```markdown
+   # Plan: [task title]
+   - [x] completed step
+   - [ ] next step  ← NEXT
+   - [ ] later step
+   ```
+
+2. **decisions.jsonl** — append only *settled decisions* from this step,
+   one per line (no exploratory reasoning or transient facts):
+   ```json
+   {"ts": "ISO8601", "decision": "what was decided", "why": "one-line rationale", "alternatives_rejected": ["rejected option"]}
+   ```
+
+3. **progress.json** — rewrite in full:
+   ```json
+   {
+     "task_id": "task identifier",
+     "status": "in_progress | completed | abandoned",
+     "completed_steps": ["list of completed steps"],
+     "next_step": "what to do next (be specific)",
+     "artifacts": ["files created/modified"],
+     "open_issues": ["unresolved items"],
+     "last_updated": "ISO8601"
+   }
+   ```
+
+## Rules
+
+- When the task is fully done, set `status: "completed"`. The SessionStart
+  hook does not inject completed checkpoints — forget this closing step and
+  the next session will read stale state.
+- Write checkpoints against the recovery test: the next session must be
+  able to resume from `next_step` alone.
+- Suggest deleting completed checkpoints older than 3 weeks (stale state
+  causes bad decisions).

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

@@ -0,0 +1,50 @@
+---
+name: guide-audit
+description: Audit the RULES/ANTI-PATTERNS in CLAUDE.md and classify each rule as keep / delete candidate / convert-to-sensor candidate. Use for the monthly review or when the user invokes /guide-audit. Proposes only — applying always requires user approval.
+---
+
+# Guide Audit — Guide Hygiene
+
+Goal: keep CLAUDE.md down to rules that are *still* needed. Rules that only
+accumulate are debt — find the ones a sensor now enforces, the ones that
+lost their grounding, and the ones that contradict each other.
+**Never apply any deletion or edit without user approval.**
+
+## Procedure
+
+For each entry in RULES and ANTI-PATTERNS, run five checks:
+
+1. **Verifiability** — can compliance be judged objectively?
+   (Vague rules like "write good code" fail this.)
+2. **Grounding** — did it come from an actually observed failure? Does it
+   carry a date and cause?
+3. **Contradiction** — does it conflict with another rule?
+4. **Sensor overlap** — is it already enforced automatically? Cross-check:
+   - what LINT_CMD/TEST_CMD in `.harness/commands.env` catches
+   - the DENY_PATTERNS in `guard-pre-bash.sh`
+   - the permissions (allow/ask/deny) in `settings.json`, if present
+5. **Freshness** — when was it last seen actually working (blocking or
+   catching a violation)? Cite `.harness/logs/tool_calls.jsonl` if evidence
+   exists.
+
+## Output Format
+
+| Rule | Verdict | Rationale |
+|---|---|---|
+| (rule summary) | keep / delete candidate / convert-to-sensor candidate / rewrite candidate | one sentence |
+
+- **Delete candidate**: already enforced by a sensor, or its originating
+  failure can no longer be traced.
+- **Convert-to-sensor candidate**: repeatedly violated — include the
+  concrete promotion (linter rule, guard pattern, or permissions entry).
+- **Rewrite candidate**: intent is valid but unverifiable as written —
+  include replacement wording that is observable.
+
+## Approval and Application
+
+- Apply only what the user approves. Deletions remove the whole line;
+  sensor conversions are applied as a pair — "add sensor + delete rule"
+  (never the half-application where the rule is gone but the sensor
+  didn't land).
+- If the audit leaves zero rules, an empty RULES section can be the right
+  answer. Never invent rules to fill space.

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

@@ -0,0 +1,70 @@
+---
+name: harness-init
+description: Scan the repository of a new project to fill in the PROJECT section of CLAUDE.md and .harness/commands.env, and propose initial RULES/ANTI-PATTERNS. Run once right after installing the harness, or whenever CLAUDE.md is still in placeholder state. Verifies detected commands by actually running them before applying.
+---
+
+# Harness Init — Initialize the Harness by Scanning the Repo
+
+Goal: fill CLAUDE.md and `.harness/commands.env` with commands that
+**actually work**. Never write a guessed command — only ones verified by
+running them.
+
+## Step 1: Scan
+
+- Language/version: from manifests (package.json, pyproject.toml, go.mod,
+  Cargo.toml, *.csproj, ...). Prefer versions pinned in lockfiles/config.
+- BUILD / TEST / LINT candidates: collect from manifest scripts, Makefile,
+  CI config (.github/workflows etc. — read only), and any existing README.
+- One-line project purpose: from the README or top-level code structure.
+
+## Step 2: Verify (the core step)
+
+- **Actually run** each collected TEST / LINT / BUILD command (with a
+  timeout). Record the results as they are:
+  - Passes → adopt the command.
+  - Fails but the command itself is valid (tests were already broken, etc.)
+    → adopt it, and report the current failing state to the user.
+  - Command missing or not runnable → leave that field blank and report.
+    Do not invent one.
+- If dependencies need installing, do not run the install — tell the user
+  first.
+
+## Step 3: Initial Rule Candidates
+
+- Skim past mistakes with `git log --oneline --grep="fix\|revert\|hotfix" -i`;
+  if a type repeats, draft ANTI-PATTERNS candidates (date = today, cite the
+  commit hashes in parentheses).
+- Propose at most 3 RULES candidates grounded in this codebase. Generic
+  truisms ("write good code") are forbidden — only things observable in
+  this repository.
+
+## Existing Projects (brownfield)
+
+- If CLAUDE.md existed before the harness was installed, never replace it.
+  Propose **appending** the harness protocol sections it lacks — PROJECT,
+  RULES, ANTI-PATTERNS, Work Loop, Checkpoints, "When a Mistake Is Found" —
+  while keeping every existing instruction intact. If an existing
+  instruction conflicts with a harness rule, surface the conflict and let
+  the user decide; never silently override either side.
+- If the project already has its own hooks, skills, or agents under
+  `.claude/`, list them and check for overlap before proposing anything
+  (e.g. an existing post-edit test hook would double-run tests alongside
+  the harness sensor).
+- If tests are currently failing in the existing project, say so and
+  recommend starting with LINT_CMD only (TEST_CMD empty) until the suite
+  is green — a stop gate that always fails would block every turn.
+
+## Step 4: Propose → Approve → Apply
+
+- 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)
+- Write only what was approved. Afterwards, run TEST_CMD once more to
+  confirm the sensor configuration points at a command that really runs.
+
+## Forbidden
+
+- Writing any command into CLAUDE.md or commands.env that was not executed.
+- Installing dependencies or changing the environment without approval.
+- Inventing generic rules to fill space (an empty RULES beats a fabricated one).