Add --min-round flag to wait-for-state for Evaluator catchup

Bug: Evaluator used --round N+1 (exact equality) to watch for the next
Generator round. Under the never-stop Generator mode (set by Feedback-06
workflows), the Generator can race past N+1 into N+2 or higher between
the Evaluator's wake events — the round-field check sees the current
state after wake, which is already past N+1, so the watcher keeps waiting
forever even though plenty of rounds are ready to evaluate.

Fix: add --min-round N flag with >=  semantic. Evaluator now uses
--min-round N+1, which fires as soon as round >= N+1 AND the other
conditions match. Generator still uses --round N (exact) because a
Generator's post-round watcher genuinely wants "the Evaluator verdict
for MY round", not any later one. The two flags are mutually exclusive.

Also adds catchup guidance in the Evaluator skill for when many rounds
are missed at once (cumulative evaluation vs. per-round sweep), bumps
plugin version to 1.0.8.

Author: Jeehut

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tandemkit",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Describe your goal, approve the spec, then step away — Claude and Codex loop together until it's right.",
   "author": {
     "name": "Cihat Gündüz",

scripts/wait-for-state.sh

@@ -10,12 +10,16 @@ unset _TC _NV
 # TandemKit — wait-for-state
 # Blocks until a State.json field matches an expected value (or any change occurs).
 #
-# Usage: wait-for-state.sh <mission-folder> [<field> <value1> [value2 ...]] [--quiet] [--round N]
+# Usage: wait-for-state.sh <mission-folder> [<field> <value1> [value2 ...]] [--quiet] [--round N] [--min-round N]
 #   mission-folder:  absolute path to the TandemKit/NNN-MissionName/ folder
 #   field:           JSON field to check (e.g., evaluatorStatus, generatorStatus)
 #   value1..N:       acceptable values — script exits when field matches any of them
 #   --quiet:         suppress all output except final READY line (for Codex)
 #   --round N:       also require State.json "round" field to equal N exactly
+#   --min-round N:   also require State.json "round" field to be >= N (catches up if the
+#                    other agent raced ahead past N between wake events). Use this from the
+#                    Evaluator side when the Generator runs autonomously (Feedback-06 mode).
+#                    Mutually exclusive with --round.
 #
 # If no field/values given: blocks until State.json content changes (any field).
 #
@@ -25,19 +29,26 @@ unset _TC _NV
 MISSION_DIR="$1"
 shift
 
-# Check for --quiet and --round flags (can appear anywhere in remaining args)
+# Check for --quiet, --round, --min-round flags (can appear anywhere in remaining args)
 QUIET=false
 REQUIRED_ROUND=""
+MIN_ROUND=""
 _ARGS=()
 while [[ $# -gt 0 ]]; do
    case "$1" in
       --quiet) QUIET=true; shift ;;
       --round) REQUIRED_ROUND="$2"; shift 2 ;;
+      --min-round) MIN_ROUND="$2"; shift 2 ;;
       *) _ARGS+=("$1"); shift ;;
    esac
 done
 set -- "${_ARGS[@]+"${_ARGS[@]}"}"
 
+if [[ -n "$REQUIRED_ROUND" && -n "$MIN_ROUND" ]]; then
+   echo "ERROR: --round and --min-round are mutually exclusive" >&2
+   exit 1
+fi
+
 STATE_FILE="$MISSION_DIR/State.json"
 
 if [[ ! -d "$MISSION_DIR" ]]; then
@@ -108,6 +119,20 @@ check_condition() {
       fi
    fi
 
+   # Check min-round constraint (>=). Useful when the other agent may race past N
+   # between our wake events — fires as soon as round has reached N or later.
+   if [[ -n "$MIN_ROUND" ]]; then
+      local actual_round
+      actual_round=$(read_round)
+      # Numeric comparison; guard against non-integer output by defaulting to 0.
+      if ! [[ "$actual_round" =~ ^[0-9]+$ ]]; then
+         actual_round=0
+      fi
+      if (( actual_round < MIN_ROUND )); then
+         return 1
+      fi
+   fi
+
    local current
    current=$(read_field)
 
@@ -143,7 +168,10 @@ INITIAL_HASH=$(file_hash)
 # Not ready — enter watch loop
 if [[ "$QUIET" != true ]]; then
    if [[ -n "$FIELD" ]]; then
-      echo "WAITING: $FIELD not yet ${VALUES[*]:-non-null}. Watching $STATE_FILE..."
+      _round_note=""
+      [[ -n "$REQUIRED_ROUND" ]] && _round_note=" (round == $REQUIRED_ROUND)"
+      [[ -n "$MIN_ROUND" ]] && _round_note=" (round >= $MIN_ROUND)"
+      echo "WAITING: $FIELD not yet ${VALUES[*]:-non-null}$_round_note. Watching $STATE_FILE..."
    else
       echo "WAITING: Watching $STATE_FILE for any change..."
    fi

skills/evaluator/SKILL.md

@@ -253,11 +253,13 @@ The user invokes this skill with `/tandemkit:evaluator NNN-MissionName`. First r
 
 After writing your verdict, IMMEDIATELY start TWO background watchers:
 
-1. **Next round watcher:**
+1. **Next round watcher (use `--min-round`, NOT `--round`):**
 ```bash
-bash "$HOME/.claude/plugins/cache/FlineDev/tandemkit/latest/scripts/wait-for-state.sh" "$(pwd)/TandemKit/NNN-MissionName" generatorStatus ready-for-eval --round N+1
+bash "$HOME/.claude/plugins/cache/FlineDev/tandemkit/latest/scripts/wait-for-state.sh" "$(pwd)/TandemKit/NNN-MissionName" generatorStatus ready-for-eval --min-round N+1
 ```
 
+Why `--min-round` and not `--round`: if the Generator is running autonomously (never-stop mode), it may advance past round N+1 while you are still writing your verdict. `--round N+1` is exact-match and would miss a Generator that already raced to round N+2 or N+3 — the condition window on round=N+1 may only have existed for milliseconds between the Generator's writes. `--min-round N+1` fires as soon as the Generator has reached at least N+1 AND is in `ready-for-eval`, which is the semantic you actually want: "wake me up when there is at least one new round to evaluate".
+
 2. **Completion watcher:**
 ```bash
 bash "$HOME/.claude/plugins/cache/FlineDev/tandemkit/latest/scripts/wait-for-state.sh" "$(pwd)/TandemKit/NNN-MissionName" phase complete
@@ -269,6 +271,15 @@ Run both with `run_in_background: true`. When either returns:
 
 If a watch times out (10 minutes), re-read State.json and restart the watchers. NEVER go idle.
 
+### Catchup case — Evaluator has fallen behind
+
+If the watcher fires and State.json reports `round` is **more than one ahead** of your last-evaluated round (e.g. you last evaluated round 4 and the Generator is now at round 11), you are in a catchup situation. The Generator's per-round artifacts (`Generator/Round-NN.md`, `Generator/ChangedFiles-NN.txt`) are persistent, so no evaluation work has been lost — but you need to decide between two strategies:
+
+- **Per-round sweep (preferred when the number of missed rounds is small, say ≤ 3):** evaluate each missed round individually in order (Round-NN-Discussion/Claude-01.md → Round-NN.md), bump State.json `round` appropriately after each. Accurate but slow.
+- **Cumulative catchup evaluation (preferred when many rounds have been missed):** write ONE evaluation at the current round targeting the cumulative delta since your last PASS, covering all intermediate milestones and feedbacks in one report. Note the catchup mode explicitly (e.g. set a `catchupEvaluation` field in State.json) so Planner/user can see why rounds 5..N-1 don't have individual Evaluator files. Faster; loses per-round granularity.
+
+Never silently skip rounds — either evaluate them or record that you did a cumulative pass. The verdict in State.json reflects the catchup round's verdict.
+
 ════════════════════════════════════════
   → Verdict delivered — Watching for next round
 ════════════════════════════════════════