loop

seeks — per-pass protocol

CARDINAL RULE: do exactly ONE pass, then STOP and end your turn. Never loop internally across passes. Ending your turn is what lets the Stop hook drive the next pass, advance stop_fires (so the max_iters backstop + stuck guard can fire), and survive context compaction. A loop where you never yield is unkillable by the hook.

Wind-down: if the Stop-hook continue-message says the time budget is nearly up, treat it as a wind-down — do NOT start new work: write/refresh summary.md (what you found, what's still open), commit it, then end your turn. The clock will halt the loop shortly after.

State for loop <name> lives in the PRIMARY checkout's .seeks/run/<name>/. You are usually inside the loop's worktree; always mutate state through the CLI, which resolves the control plane via git — never write .seeks/... by relative path yourself: node "${CLAUDE_PLUGIN_ROOT}/bin/seeks.mjs" <subcommand> <name> ... (run via the Bash tool).

Every pass

1. Orient — read .seeks/run/<name>/{state.md,backlog.md,context.md} and .seeks/loops/<name>/spec.md (resolve .seeks with git rev-parse --path-format=absolute --git-common-dir if needed).
2. Backlog has - [ ] items → do the SINGLE next one (respect level: L1 = no edits, findings to state.md; L2 = edit + commit on seeks/<name>). Mark it - [x]; record: … status-set <name> '{"last_change":"<what you did>"}'; … log-add <name> "pass N — <summary>" (appends to log.md; never hand-append by relative path); commit seeks(<name>): pass N — <summary> (L2+).
3. Backlog EMPTY → ask the engine whether the sweep bar is met — never re-derive it yourself: STATUS=$(node "${CLAUDE_PLUGIN_ROOT}/bin/seeks.mjs" sweep-status <name>). This returns the exact predicate the gate releases on ({mode, satisfied, label, …}). Reading dry_sweeps/min_dry_sweeps by hand is the trap that deadlocks an exhaustive loop: in mode:"exhaustive" the gate keys off dry_depth_rounds, not dry_sweeps, so a "3 dry sweeps → certify" shortcut sets done while the gate holds out forever.
   • satisfied:true (this includes mode:"none" — no sweep configured, the legacy default) → go to the verifier (below).
   • satisfied:false → run exactly one creative discovery sweep through a fresh lens, then end the pass. Get the angle: LENS=$(… sweep-next-lens <name>) (breadth-first through the catalog; a repeated lens won't advance the streak, so always take the one you're handed). Depth (exhaustive): the sweep-status label shows depth — depth 1 = each module's logic; depth 2 = cross-module dataflow; depth 3 = adversarial inputs / probing tests. Review through $LENS at the current depth; when a full catalog pass comes up dry the engine deepens automatically (via sweep-tick). You MUST dispatch a bug-hunter subagent for the sweep (triage role's model — node "${CLAUDE_PLUGIN_ROOT}/bin/seeks.mjs" role triage), handing it $LENS + the goal's blast radius. Bound its reply so a high-effort model doesn't stall generating a huge final answer (the failure mode where an opus hunter has to be killed and re-dispatched): tell it to reason internally but return ONLY a terse findings list — per real, demonstrable defect one line of file:line · one-line defect · severity · one-line repro/why; cap ~5; if it finds nothing, reply exactly FINDINGS: 0. No prose essay, no re-listing the source. This is not optional: a sweep you run inline is anchored on your own edits, so an inline "found nothing" is the self-grading seeks exists to prevent — and in until-dry/exhaustive mode those dry sweeps are exactly what advances the gate toward release. The subagent READS source and reasons about correctness through $LENS; re-running tests/linters is only a regression floor, NOT the bug finder. Then … sweep-tick <name> <count-of-NEW-real-bugs> "$LENS":
     • Found > 0 → … backlog-add <name> "<each new item>" (re-seed); end the pass. (sweep-tick reset the dry streak to 0.)
     • Found == 0 → end the pass. The loop keeps sweeping — and in exhaustive mode deepening — until sweep-status reports satisfied:true or the time budget winds it down. For a rich/overnight target the time-budget halt is the expected end; do NOT short-circuit to the verifier on a few dry sweeps, and do NOT disarm — if the gate keeps blocking a loop you think is finished, read its block reason, which names the unmet bar (e.g. dry depth-round k/N).