uni-harness 0.1.2 → 0.2.1

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

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 # ════════════════════════════════════════════════════════════════
 # SessionStart context injection (startup|resume|clear|compact)
-# (1) If an in-progress checkpoint (progress.json) exists, surface
+# (1) If an in-progress checkpoint (.harness/state/progress.json,
+#     legacy: ./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,
@@ -36,15 +37,21 @@ try:
 except Exception:
     pass
 
-# (1) in-progress checkpoint
+# (1) in-progress checkpoint (.harness/state/; legacy installs kept it at the root)
 try:
-    with open(os.path.join(proj, "progress.json")) as f:
-        ckpt = json.load(f)
-    if ckpt.get("status") not in ("completed", "abandoned"):
+    ckpt, where = None, None
+    for rel in (".harness/state/progress.json", "progress.json"):
+        p = os.path.join(proj, rel)
+        if os.path.exists(p):
+            with open(p) as f:
+                ckpt = json.load(f)
+            where = os.path.dirname(rel) or "."
+            break
+    if ckpt and 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"work, read progress.json / plan.md / decisions.jsonl in {where}/, "
+            "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

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

@@ -1,17 +1,19 @@
 ---
 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.
+description: Save current work state to .harness/state/ checkpoints (plan.md / decisions.jsonl / progress.json). 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?**
+The filesystem is the memory. Maintain these three files in
+**`.harness/state/`** (created by the installer; gitignored by default —
+remove the `.gitignore` entry if you want decisions.jsonl in version
+control). 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:
+1. **`.harness/state/plan.md`** — update if the plan changed. Format:
    ```markdown
    # Plan: [task title]
    - [x] completed step
@@ -19,13 +21,13 @@ pick up where it left off?**
    - [ ] later step
    ```
 
-2. **decisions.jsonl** — append only *settled decisions* from this step,
+2. **`.harness/state/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:
+3. **`.harness/state/progress.json`** — rewrite in full:
    ```json
    {
      "task_id": "task identifier",
@@ -40,6 +42,11 @@ pick up where it left off?**
 
 ## Rules
 
+- Legacy layout: if plan.md / progress.json / decisions.jsonl sit at the
+  project root (installs before v0.2), propose moving them into
+  `.harness/state/` — ask first, since a root plan.md might be the
+  project's own document rather than the harness's.
+
 - 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.

package/CLAUDE.md

@@ -31,7 +31,8 @@
 
 ## Work Loop
 
-- For any task with 3+ steps, write the plan to `plan.md` before starting.
+- For any task with 3+ steps, write the plan to `.harness/state/plan.md`
+  before starting.
 - Retry ceiling: at most 3 fix attempts per goal. Beyond that, stop and
   write an escalation packet.
 - Escalation packet format (report to the user):
@@ -45,10 +46,11 @@
 
 ## Checkpoints
 
-- At session start, if `progress.json` (checkpoint) exists, read it first
-  and do not repeat completed steps. (The SessionStart hook will remind you.)
+- At session start, if `.harness/state/progress.json` (checkpoint) exists,
+  read it first and do not repeat completed steps. (The SessionStart hook
+  will remind you.)
 - After completing each meaningful step, run `/checkpoint` to update
-  plan.md / decisions.jsonl / progress.json.
+  plan.md / decisions.jsonl / progress.json in `.harness/state/`.
 - Keep transient facts and exploratory reasoning out of checkpoints. Record
   only settled decisions in decisions.jsonl.
 

package/README.md

@@ -56,7 +56,6 @@ anything you've customized is skipped (listed, with `--force` to override).
 | `.claude/hooks/guard-pre-bash.sh` | Blocks destructive commands and verification bypasses (`--no-verify`) before execution |
 | `.claude/hooks/session-start.sh` | Re-injects in-progress checkpoints at session start/resume/compaction; nudges `/ratchet` when failures pile up |
 | `.claude/hooks/observe-log.sh` | Logs every tool call as JSONL + tripwires (same failure 3x, call surge) |
-| `.claude/agents/TEMPLATE.md` | Custom agent template (inactive until you uncomment `name`; example: fresh-context code reviewer) |
 | `harness/harness_report.py` | Health scorecard from the logs |
 | `harness/tests/` | Self-tests for the hooks and the installer |
 | `bin/cli.js` | The installer (init / update / doctor / uninstall) |
@@ -66,7 +65,7 @@ Skills:
 | Skill | Role |
 |---|---|
 | `/harness-init` | Scan the repo → fill PROJECT section & commands.env (once, at install) |
-| `/checkpoint` | Save state to plan.md / decisions.jsonl / progress.json |
+| `/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) |
 

package/bin/cli.js

@@ -9,8 +9,8 @@
  *   npx uni-harness uninstall [dir] --yes       remove machinery files
  *
  * File boundary (the core contract of this installer):
- *   machinery (managed)  — .claude/hooks/, .claude/skills/, .claude/agents/,
- *                          harness/  → init installs them, update refreshes
+ *   machinery (managed)  — .claude/hooks/, .claude/skills/, harness/
+ *                          → init installs them, update refreshes
  *                          them. Hashes are recorded in
  *                          .harness/kit-manifest.json so files the user has
  *                          modified are NEVER overwritten (unless --force).
@@ -26,7 +26,7 @@ const crypto = require('crypto');
 const { spawnSync } = require('child_process');
 
 const PKG_ROOT = path.resolve(__dirname, '..');
-const MACHINERY_DIRS = ['.claude/hooks', '.claude/skills', '.claude/agents', 'harness'];
+const MACHINERY_DIRS = ['.claude/hooks', '.claude/skills', 'harness'];
 // Files that live in these dirs but belong to the kit repository only.
 // test_installer.sh tests bin/cli.js, which is never installed into target
 // projects — shipping it there guarantees a failing test suite.
@@ -103,6 +103,24 @@ function runHookTests(target) {
 
 const log = (s) => process.stdout.write(s + '\n');
 
+// runtime dirs: logs (observability) and state (checkpoints — plan.md,
+// progress.json, decisions.jsonl). Both gitignored by default; users who
+// want decisions.jsonl in version control can drop the state entry.
+// Called by init AND update so upgrades pick up newly added dirs/entries.
+function ensureRuntimeDirs(target) {
+  fs.mkdirSync(path.join(target, '.harness/logs'), { recursive: true });
+  fs.mkdirSync(path.join(target, '.harness/state'), { recursive: true });
+  const gi = path.join(target, '.gitignore');
+  const giBody = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
+  const giLines = giBody.split('\n').map((l) => l.trim().replace(/\/$/, ''));
+  const giAdd = ['.harness/logs', '.harness/state'].filter((d) => !giLines.includes(d));
+  if (giAdd.length) {
+    fs.writeFileSync(gi, giBody + (giBody && !giBody.endsWith('\n') ? '\n' : '') +
+      giAdd.map((d) => d + '/\n').join(''));
+    log('  ~ .gitignore (+' + giAdd.map((d) => d + '/').join(', +') + ')');
+  }
+}
+
 // ── settings.json merge (init only) ──────────────────────────────
 // Hooks: append only the entries whose hook script is not yet registered
 // for that event. Everything the user already has is left untouched.
@@ -162,6 +180,36 @@ function mergeSettings(target) {
   }
 }
 
+// pre-v0.2 checkpoints lived at the project root. Migrate them into
+// .harness/state/, but ONLY files whose content is recognizably the
+// harness's own checkpoint format — a root plan.md may well be the
+// project's own document, and those are never touched.
+function migrateLegacyState(target) {
+  const isOurs = {
+    'progress.json': (s) => {
+      try { const j = JSON.parse(s); return !!j && typeof j === 'object' && 'status' in j && ('task_id' in j || 'next_step' in j); }
+      catch { return false; }
+    },
+    'decisions.jsonl': (s) => {
+      const lines = s.trim().split('\n');
+      return lines.length > 0 && lines.every((l) => {
+        try { return 'decision' in JSON.parse(l); } catch { return false; }
+      });
+    },
+    'plan.md': (s) => /^# Plan:/m.test(s),
+  };
+  for (const [name, test] of Object.entries(isOurs)) {
+    const src = path.join(target, name);
+    const dst = path.join(target, '.harness/state', name);
+    if (!fs.existsSync(src) || fs.existsSync(dst)) continue;
+    let body;
+    try { body = fs.readFileSync(src, 'utf8'); } catch { continue; }
+    if (!test(body)) { log('  ! ' + name + ' left at the root (not in harness checkpoint format)'); continue; }
+    fs.renameSync(src, dst);
+    log('  > ' + name + ' -> .harness/state/' + name + ' (migrated)');
+  }
+}
+
 // ── init ─────────────────────────────────────────────────────────
 function init(target, force) {
   const files = machineryFiles();
@@ -193,13 +241,7 @@ function init(target, force) {
   }
   mergeSettings(target);
 
-  fs.mkdirSync(path.join(target, '.harness/logs'), { recursive: true });
-  const gi = path.join(target, '.gitignore');
-  const giBody = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
-  if (!giBody.split('\n').some((l) => l.trim().replace(/\/$/, '') === '.harness/logs')) {
-    fs.writeFileSync(gi, giBody + (giBody && !giBody.endsWith('\n') ? '\n' : '') + '.harness/logs/\n');
-    log('  ~ .gitignore (+.harness/logs/)');
-  }
+  ensureRuntimeDirs(target);
 
   writeManifest(target, files);
 
@@ -253,14 +295,31 @@ function update(target, force) {
     const dst = path.join(target, rel);
     if (fs.existsSync(dst) && sha256(dst) === manifest.files[rel]) {
       fs.unlinkSync(dst);
+      try { fs.rmdirSync(path.dirname(dst)); } catch { /* keep if not empty */ }
       log('  - ' + rel + ' (removed from kit)');
       changed++;
     }
   }
 
   writeManifest(target, files);
+  ensureRuntimeDirs(target);
+  migrateLegacyState(target);
   log(`\n${changed} file(s) updated (v${manifest.kitVersion} -> v${KIT_VERSION}). ` +
       'CLAUDE.md / commands.env / settings.json were not touched.');
+
+  // pre-v0.2 installs kept checkpoints at the project root and their
+  // (owned, never-touched) CLAUDE.md still says so — tell, don't touch
+  try {
+    const cm = fs.readFileSync(path.join(target, 'CLAUDE.md'), 'utf8');
+    if (cm.includes('progress.json') && !cm.includes('.harness/state')) {
+      log('\nNote: checkpoint files (plan.md / progress.json / decisions.jsonl)');
+      log('now live in .harness/state/ instead of the project root. Recognized');
+      log('checkpoint files were migrated automatically (see above). Your');
+      log('CLAUDE.md still references the old locations — update its Work Loop');
+      log('and Checkpoints sections. Until then the SessionStart hook still');
+      log('reads a root progress.json as a fallback.');
+    }
+  } catch { /* no CLAUDE.md — nothing to migrate */ }
   if (skipped.length) {
     log('Skipped files with local modifications (use --force to overwrite):');
     for (const s of skipped) log('  ! ' + s);

package/harness/tests/test_hooks.sh

@@ -102,12 +102,18 @@ echo "session-start.sh"
 fresh_project
 OUT=$(bash "$HOOKS/session-start.sh")
 check "silent without checkpoint" "EMPTY" "$OUT"
-echo '{"task_id":"t1","status":"in_progress","next_step":"do X"}' > "$TMP/progress.json"
+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")
-check "injects in-progress checkpoint" "progress.json" "$OUT"
-echo '{"task_id":"t1","status":"completed"}' > "$TMP/progress.json"
+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")
 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")
+check "reads legacy root checkpoint" "progress.json" "$OUT"
 rm "$TMP/progress.json"
 NOW=$(python3 -c 'import datetime; print(datetime.datetime.now().isoformat(timespec="seconds"))')
 for _ in 1 2 3; do

package/harness/tests/test_installer.sh

@@ -38,6 +38,8 @@ check "installs CLAUDE.md" "yes" "$([ -f "$TGT/CLAUDE.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")"
+check "creates state dir" "yes" "$([ -d "$TGT/.harness/state" ] && echo yes)"
+check "gitignores state" ".harness/state/" "$(cat "$TGT/.gitignore")"
 check "init runs hook tests" "Hook tests passed" "$OUT"
 check "prints next step" "/harness-init" "$OUT"
 # regression: test_installer.sh tests bin/cli.js, which only exists in the
@@ -101,6 +103,29 @@ OUT=$(node "$CLI" update "$TGT" 2>&1)
 check "update removes stale kit-only file" "removed from kit" "$OUT"
 check "stale file is gone" "EMPTY" "$([ -f "$TGT/harness/tests/test_installer.sh" ] && echo left)"
 
+# update on a pre-v0.2 install must also add the new gitignore entry
+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")"
+
+# 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"
+# legacy root checkpoints: harness-format files are migrated, foreign ones kept
+echo '{"task_id":"t1","status":"in_progress","next_step":"do X"}' > "$TGT/progress.json"
+printf '{"ts":"2026-01-01","decision":"use X","why":"y"}\n' > "$TGT/decisions.jsonl"
+printf '# Roadmap\nnot a harness plan\n' > "$TGT/plan.md"
+OUT=$(node "$CLI" update "$TGT" 2>&1)
+check "prints checkpoint migration note" "now live in .harness/state/" "$OUT"
+check "migrates harness-format progress.json" "yes" "$([ -f "$TGT/.harness/state/progress.json" ] && [ ! -f "$TGT/progress.json" ] && echo yes)"
+check "migrates harness-format decisions.jsonl" "yes" "$([ -f "$TGT/.harness/state/decisions.jsonl" ] && echo yes)"
+check "keeps foreign plan.md at the root" "yes" "$([ -f "$TGT/plan.md" ] && [ ! -f "$TGT/.harness/state/plan.md" ] && echo yes)"
+rm -f "$TGT/plan.md" "$TGT/.harness/state/progress.json" "$TGT/.harness/state/decisions.jsonl"
+check "migration note does not edit CLAUDE.md" "# old project" "$(cat "$TGT/CLAUDE.md")"
+cp "$ROOT/CLAUDE.md" "$TGT/CLAUDE.md"   # restore for the doctor section
+OUT=$(node "$CLI" update "$TGT" 2>&1)
+check "no migration note for current template" "EMPTY" "$(printf '%s' "$OUT" | grep -F 'now live in' || true)"
+
 # ── doctor ───────────────────────────────────────────────────────
 echo "doctor"
 OUT=$(node "$CLI" doctor "$TGT" 2>&1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uni-harness",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "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"

package/.claude/agents/TEMPLATE.md

@@ -1,64 +0,0 @@
----
-# ── 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