feat(miner-governor): iterate-loop stop/abandon/handoff policy (#2335)

[JSONbored]

Summary

Closes #2335.

Adds decideNextAction/decideNextActionWithReason (packages/gittensory-engine/src/miner/iterate-policy.ts): the pure policy the iterate-loop orchestrator (#2333, sibling issue, not yet built) will consult each iteration to choose among exactly three outcomes -- continue, handoff, or abandon. Deliberately split from the loop mechanics so the actual thresholds are one small, independently-reviewable, IO-free artifact.

• Precedence (each check short-circuits the ones below): rejectionSignaled always wins, even over an otherwise-passing self-review -- disengage silently rather than retry-hammer a repo that has signaled it doesn't want automated contributions (the Matplotlib "MJ Rathbun" cautionary tale). An ambiguous self-review (the calculator itself errored) abandons rather than optimistically continuing or handing off. A clean predicted-gate pass (from maintainer: self-review adapter wiring iterate-loop diffs through predicted-gate + slop scoring #2334's SelfReviewVerdict) is the only path to handoff. A hard iteration ceiling abandons regardless of whether the blocker set was still changing. A no-progress detector (set-equality on the self-review's blocker codes vs. the prior iteration's) stops the loop from wasting turns on an attempt that isn't converging.
• HandoffPacket: the forward-looking interface Phase 4 (submission, built later) will target -- worktree path/branch ref, diff summary, the passing verdict, and an attempt-log reference. Interface only, not an implementation of Phase 4.
• deriveSelfReviewOutcome: narrows a real SelfReviewVerdict (maintainer: self-review adapter wiring iterate-loop diffs through predicted-gate + slop scoring #2334) down to the SelfReviewOutcome this policy needs.

Barrel-exported from the engine's public entrypoint.

Validation

Measured, not assumed -- per this session's coverage-discipline directive:

npm run build && npx tsc -p tsconfig.test.json && node --experimental-test-coverage --test "dist-test/**/*.test.js"

• 397/397 tests pass, 0 fail.
• iterate-policy.js coverage: 100.00% lines / 100.00% branch / 100.00% funcs.

Test plan

• Every branch of decideNextAction covered: continue (blocker set changed, first iteration, one-below-ceiling), handoff (clean pass), and every distinct abandon reason (rejection_signaled -- including winning over an otherwise-passing self-review, self_review_ambiguous -- with and without a reason string, max_iterations_reached -- at and beyond the ceiling, no_progress -- including reordered-but-identical sets, duplicate-code false-positive guard, and different-length fast path).
• deriveSelfReviewOutcome pass/fail mapping covered.
• Barrel-export smoke test.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	gittensory-ui	ad444d1	Commit Preview URL Branch Preview URL	Jul 11 2026, 09:53 AM

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-11 09:55:26 UTC}

3 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This is a clean, self-contained addition of a pure decision function (`decideNextAction`/`decideNextActionWithReason`) governing continue/handoff/abandon outcomes for a not-yet-built iterate loop, plus a `HandoffPacket` interface stub for a later phase. The precedence logic (rejection > ambiguous > pass > iteration ceiling > no-progress > continue) is implemented correctly and matches the description; `blockerSetsEqual` correctly guards against both length and duplicate-count false positives, which the tests explicitly exercise. The change is IO-free, additive-only (new file + barrel export), closes its stated issue (#2335), and CI is green with claimed 100% branch coverage on the new file that the visible tests substantiate.

Nits — 6 non-blocking

• packages/gittensory-engine/src/miner/iterate-policy.ts:1-24 — the file-header comment reproduces most of the PR description (roadmap rationale, Matplotlib anecdote); consider trimming to what a future reader actually needs at the call site.
• packages/gittensory-engine/src/miner/iterate-policy.ts:79-93 — `HandoffPacket` has no consumer in this diff (Phase 4 is explicitly deferred); fine as a documented forward-looking interface, but worth confirming the maintainer wants speculative interfaces landed ahead of their implementation rather than added when Phase 4 actually lands.
• The external magic-number/deep-nesting flags on lines 116-121/144 are false positives — those are precedence step numbers in a comment and a flat sequence of early-return `if`s, not real nesting or literals in logic.
• Consider whether `HandoffPacket` should move into the future Phase 4 PR instead of landing now with zero references, to keep this PR's surface strictly to the policy function it claims to add.
• The reason strings (e.g. 'Downgrading to abandon rather than optimistically handing off.') are good for an attempt-log but have no test asserting exact wording stability if that log is machine-parsed later — worth a comment noting reason text is not a stable contract if that matters downstream.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2335
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 47 registered-repo PR(s), 39 merged, 428 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 47 PR(s), 428 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence. LLM value judgment: moderate — The policy function itself is correct, small, and thoroughly tested, but it has no live caller yet (the orchestrator loop in sibling issue #2333 is not built), so this PR advances the roadmap without yet changing observable system behavior.

Linked issue satisfaction

Addressed
The PR adds packages/gittensory-engine/src/miner/iterate-policy.ts with a pure decideNextAction/decideNextActionWithReason covering exactly the continue/handoff/abandon branches specified (rejection-signaled precedence, ambiguous self-review, clean pass, iteration ceiling, no-progress set-equality detector), defines HandoffPacket with the requested fields, and ships owner-facing unit tests hitting

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 47 PR(s), 428 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.