uni-harness 0.1.1 → 0.2.0

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/skills/harness-init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Scan the repository 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. If the repo has no project code yet (greenfield), offers to scaffold a minimal project so the sensors start active from the first line of code.
 ---
 
 # Harness Init — Initialize the Harness by Scanning the Repo
@@ -16,9 +16,11 @@ running them.
   the project. Never let it drive language detection, and never propose the
   kit's self-test (`harness/tests/test_hooks.sh`) as the project's TEST_CMD:
   it verifies the harness, not the user's code, and pointing the stop gate
-  at it would "pass" every turn regardless of what broke. If no project
-  code exists outside those directories yet, say so and leave the commands
-  blank until there is something real to verify.
+  at it would "pass" every turn regardless of what broke.
+- The scan decides which mode you are in: project code exists → continue
+  with Step 2 (and the brownfield section if the project predates the
+  harness). Nothing but harness files → switch to the **New Projects
+  (greenfield)** section below. Do not stop at "nothing to configure".
 - 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,
@@ -46,6 +48,32 @@ running them.
   truisms ("write good code") are forbidden — only things observable in
   this repository.
 
+## New Projects (greenfield — the harness was installed before any code)
+
+If the scan finds no project code at all (no manifest, no sources, no CI),
+the user is starting a project *with* the harness — the whole point is
+that sensors guard the very first code written. Ending with "come back
+later" leaves them off during the riskiest phase. Instead, offer to
+bootstrap:
+
+1. **Ask, don't guess:** what is being built, which language/runtime,
+   which framework and test runner (offer the ecosystem defaults, e.g.
+   pytest / vitest / go test).
+2. **Propose a minimal scaffold** and apply it only after approval: the
+   manifest (package.json / pyproject.toml / go.mod ...), a source entry
+   point, a test setup with **one real passing test**, and a
+   linter/formatter config if the ecosystem has a standard one. Announce
+   any dependency installs with the reason before running them.
+3. If it is not a git repository, offer `git init` (the guard hooks and
+   future ANTI-PATTERNS mining assume git history).
+4. Then continue with Step 2 exactly as usual: run the scaffold's
+   BUILD/TEST/LINT commands, confirm they pass, and fill CLAUDE.md and
+   commands.env with the **verified** commands.
+
+The exit criterion for greenfield: sensors ACTIVE against a real (if tiny)
+test suite. If the user declines the scaffold, leave everything blank as
+before and tell them to re-run /harness-init once code exists.
+
 ## Existing Projects (brownfield)
 
 - If CLAUDE.md existed before the harness was installed, never replace it.

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.
@@ -193,13 +211,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 +265,30 @@ 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);
   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. Your');
+      log('CLAUDE.md still references the old locations — update its Work Loop');
+      log('and Checkpoints sections, and move any existing checkpoint files');
+      log('into .harness/state/. Until then the SessionStart hook still reads');
+      log('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,21 @@ 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"
+OUT=$(node "$CLI" update "$TGT" 2>&1)
+check "prints checkpoint migration note" "now live in .harness/state/" "$OUT"
+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.1",
+  "version": "0.2.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"

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