feat: wrap-around navigation that seeks unreviewed files

Approving a file now advances to the next unreviewed file, wrapping
past the end of the review order — a reviewer who jumped ahead is
carried back to the files they skipped instead of dead-ending on the
last file with the review-complete prompt never firing. Plain ⇧→/⇧←
wrap at the ends too: next from the last file goes to the first
unreviewed file (else cycles), prev mirrors it, and stepping back from
the guide Overview wraps to the end.

The seek order is guide order when a guide is attached, extended with
any changed files the guide doesn't list so a partial guide can't
strand its "Other" files; without a guide it's the file array. A file
whose sign-off hash no longer matches (the agent rewrote it) counts as
unreviewed and is a legitimate wrap target. The guide-bar Next/Prev
buttons now dim only when nothing unreviewed remains, so the visible
affordance agrees with the keyboard.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015jcfPg9g4TTWQksf8vhHps

Author: ymansurozer

src/ui/decisions.ts

@@ -1,7 +1,7 @@
 import { S, D, toast, api, persist } from "./store";
 import { currentFile, applyDecisionToDiff, fileObjections, fileReviewState } from "./changes";
 import { render, deferRender } from "./render";
-import { nextFileIndex, guideProgress } from "./guide";
+import { nextUnreviewedFileIndex, guideProgress } from "./guide";
 import type { ChangeState, Decision } from "./types";
 
 // The explicit decision record is the source of truth for accept/reject (decoupled
@@ -67,7 +67,9 @@ export async function approveCurrentFile() {
   // moment it moves, not just visible in the bar. % matches the strip (LOC-weighted by default).
   const done = S.state.files.filter((f) => fileReviewState(f.path) !== "pending").length;
   toast(`${label} — ${done} of ${S.state.files.length} files · ${guideProgress().pct}%`);
-  const next = nextFileIndex(S.fileIndex);
+  // Seek the next unreviewed file, wrapping past the end so a reviewer who jumped ahead is
+  // carried back to the files they skipped instead of dead-ending here.
+  const next = nextUnreviewedFileIndex(S.fileIndex);
   if (next !== null && S.selectFile) S.selectFile(next);
   else render();
 }

src/ui/guide.ts

@@ -1,5 +1,6 @@
 import { S, $, esc } from "./store";
-import { fileReviewState } from "./changes";
+import { fileReviewState, fileFinished } from "./changes";
+import { nextUnreviewed, wrapNextTarget, wrapPrevTarget } from "./seek";
 import { renderMarkdown, renderMarkdownInline } from "./markdown";
 import { lineStats, walkthroughGroups, walkRows } from "./walkthrough";
 import type { WalkGroup, WalkRow, WalkFile } from "./walkthrough";
@@ -46,6 +47,49 @@ export function prevFileIndex(cur: number): number | null {
   return cur - 1 >= 0 ? cur - 1 : null;
 }
 
+// The order file navigation walks and wraps around. Without a guide it's the file array; with
+// one it's the guide order followed by every changed file the guide DIDN'T list (the
+// walkthrough's "Other" group), in file-array order — so the seek reaches unlisted files and
+// never dead-ends on a partial guide. Plain mid-list stepping (nextFileIndex) is unaffected;
+// only the seek/wrap helpers read this extended order.
+export function navOrder(): number[] {
+  const n = S.state?.files?.length ?? 0;
+  const all = Array.from({ length: n }, (_, i) => i);
+  if (!hasGuide()) return all;
+  const order = guideOrder();
+  const listed = new Set(order);
+  return order.concat(all.filter((i) => !listed.has(i)));
+}
+
+// "Unreviewed" for the seek — a file not signed off in the current state, matching the tree
+// badges and floating approve button (an agent edit after sign-off invalidates the hash, so
+// the file counts as unreviewed again). Store-reading wrapper over fileFinished.
+function seekFinished(i: number): boolean {
+  const path = S.state?.files?.[i]?.path;
+  return !!path && fileFinished(path);
+}
+
+// Is there any unreviewed file left anywhere in the nav order?
+export function anyUnreviewed(): boolean {
+  return navOrder().some((i) => !seekFinished(i));
+}
+
+// The next unreviewed file after `cur`, wrapping past the end — approve-advance's seek.
+// null when no unreviewed file remains (the caller falls back to the review-complete prompt).
+export function nextUnreviewedFileIndex(cur: number): number | null {
+  return nextUnreviewed(navOrder(), cur, seekFinished);
+}
+
+// Where plain "next" lands when it steps off the last file: first unreviewed, else first file.
+export function nextWrapIndex(): number | null {
+  return wrapNextTarget(navOrder(), seekFinished);
+}
+
+// Where plain "prev" lands when it steps off the first position: last unreviewed, else last file.
+export function prevWrapIndex(): number | null {
+  return wrapPrevTarget(navOrder(), seekFinished);
+}
+
 // Changed lines (additions + deletions) per file path — the weight used for progress, so
 // finishing a big file advances the bar more than a tiny one. Min 1 so every file counts.
 function locByPath(): Map<string, number> {

src/ui/main.ts

@@ -26,6 +26,9 @@ import {
   guideStale,
   nextFileIndex,
   prevFileIndex,
+  nextWrapIndex,
+  prevWrapIndex,
+  anyUnreviewed,
   walkthroughRows,
 } from "./guide";
 import { setBaseTitle, reviewStats } from "./progress";
@@ -215,33 +218,50 @@ S.guideNext = () => {
     S.startGuided?.();
     return;
   }
+  // Off the last file, wrap to the first unreviewed file (else cycle to the first) instead
+  // of dead-ending, so skipped files are surfaced.
   const n = nextFileIndex(S.fileIndex);
-  if (n !== null) S.selectFile?.(n);
+  const target = n !== null ? n : nextWrapIndex();
+  if (target !== null) S.selectFile?.(target);
 };
 S.guidePrev = () => {
-  if (S.overviewOpen) return;
+  // Stepping back from the Overview (the position before the first file) wraps to the end —
+  // the last unreviewed file, else the last file.
+  if (S.overviewOpen) {
+    const w = prevWrapIndex();
+    if (w !== null) S.selectFile?.(w);
+    return;
+  }
+  // Off the first file, drop to the Overview (unchanged); the wrap happens from there.
   const p = prevFileIndex(S.fileIndex);
   if (p === null) S.openOverview?.();
   else S.selectFile?.(p);
 };
-S.guideAtStart = () => !!S.overviewOpen;
-S.guideAtLast = () => !S.overviewOpen && nextFileIndex(S.fileIndex) === null;
+// The nav buttons dim only when the review is fully signed off (nothing left to wrap to) —
+// while unreviewed work remains, next/prev stay live because they now seek it.
+S.guideAtStart = () => !!S.overviewOpen && !anyUnreviewed();
+S.guideAtLast = () => !S.overviewOpen && nextFileIndex(S.fileIndex) === null && !anyUnreviewed();
 // Review-order file stepping (⇧←/⇧→) — guide order when guided (or on the Overview), else sequential.
 S.nextFile = () => {
   if (hasGuide() || S.overviewOpen) {
     S.guideNext?.();
     return;
   }
   const n = S.fileIndex + 1;
-  if (n < S.state.files.length) S.selectFile?.(n);
+  // Off the last file, wrap to the first unreviewed file (else the first file).
+  const target = n < S.state.files.length ? n : nextWrapIndex();
+  if (target !== null) S.selectFile?.(target);
 };
 S.prevFile = () => {
   if (hasGuide() || S.overviewOpen) {
     S.guidePrev?.();
     return;
   }
   const p = S.fileIndex - 1;
-  if (p >= 0) S.selectFile?.(p);
+  // Off the first file, wrap to the last unreviewed file (else the last file). Without a guide
+  // there's no Overview to step back into, so the wrap applies straight from the first file.
+  const target = p >= 0 ? p : prevWrapIndex();
+  if (target !== null) S.selectFile?.(target);
 };
 // Tree-order file stepping (⇧↑/⇧↓) — walk the file rows as shown in the tree (skip folders),
 // selecting the prev/next one (preview for unchanged files).

src/ui/seek.test.ts

@@ -0,0 +1,87 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { nextUnreviewed, wrapNextTarget, wrapPrevTarget } from "./seek.js";
+
+// A finished predicate backed by a set of signed-off file indices. A file absent from the set
+// is unreviewed — this is how a hash-invalidated file (signed off, then edited by the agent)
+// re-enters the seek: the store's fileFinished returns false for it, so it's just "not in set".
+const finishedIn = (done: number[]) => {
+  const s = new Set(done);
+  return (i: number) => s.has(i);
+};
+
+test("nextUnreviewed wraps past the end to the first unreviewed file — guide order", () => {
+  // Guide order is not the file-array order; the seek must follow it.
+  const order = [3, 1, 4, 0, 2];
+  // Everything signed off except file index 1; cur is the last file in the order (2).
+  const next = nextUnreviewed(order, 2, finishedIn([3, 4, 0, 2]));
+  assert.equal(next, 1, "scans forward from the last slot, wraps, lands on 1");
+});
+
+test("nextUnreviewed wraps past the end to the first unreviewed file — file order", () => {
+  const order = [0, 1, 2, 3, 4];
+  // Only file 2 remains; cur is the last file (4).
+  assert.equal(nextUnreviewed(order, 4, finishedIn([0, 1, 3, 4])), 2);
+});
+
+test("nextUnreviewed returns null when the current file is the last remaining one", () => {
+  // Approve-advance on the final unreviewed file: after approving, cur is finished and every
+  // other file already was — no wrap target, so the caller shows the review-complete prompt.
+  const order = [0, 1, 2];
+  assert.equal(nextUnreviewed(order, 1, finishedIn([0, 1, 2])), null);
+});
+
+test("nextUnreviewed never returns the current file, even when it is unreviewed", () => {
+  // The just-approved file is finished in practice, but guard the wrap regardless.
+  const order = [0, 1, 2];
+  assert.equal(nextUnreviewed(order, 1, finishedIn([0, 2])), null);
+});
+
+test("nextUnreviewed treats a hash-invalidated (dropped-out) file as a wrap target", () => {
+  // File 0 was signed off then invalidated by an agent edit → back to unreviewed.
+  const order = [0, 1, 2];
+  assert.equal(nextUnreviewed(order, 2, finishedIn([1, 2])), 0);
+});
+
+test("nextUnreviewed starts from the top when cur is not in the order", () => {
+  // A diff file absent from the guide order isn't in `order`; scan from the first slot.
+  const order = [3, 1, 4];
+  assert.equal(nextUnreviewed(order, 99, finishedIn([3])), 1);
+});
+
+test("partial guide: approve-advance and wrap reach the unlisted 'Other' files", () => {
+  // navOrder() builds guide order followed by changed files the guide didn't list. Here the
+  // guide covers files 2 and 0; files 1 and 3 are unlisted, appended in file-array order.
+  const order = [2, 0, 1, 3];
+  // Approve the last guide-listed file (0) while an unlisted file (1) is still pending →
+  // advance must land on it, not dead-end at the end of the guided sequence.
+  assert.equal(nextUnreviewed(order, 0, finishedIn([2, 0])), 1);
+  // The plain-next wrap likewise targets an unlisted pending file.
+  assert.equal(wrapNextTarget(order, finishedIn([2, 0])), 1);
+  assert.equal(wrapPrevTarget(order, finishedIn([2, 0])), 3);
+});
+
+test("wrapNextTarget lands on the first unreviewed file when work remains", () => {
+  assert.equal(wrapNextTarget([3, 1, 4, 0, 2], finishedIn([3, 1])), 4, "guide order");
+  assert.equal(wrapNextTarget([0, 1, 2, 3], finishedIn([0])), 1, "file order");
+});
+
+test("wrapNextTarget cycles to the first file when everything is reviewed", () => {
+  assert.equal(wrapNextTarget([3, 1, 4], finishedIn([3, 1, 4])), 3);
+});
+
+test("wrapPrevTarget lands on the last unreviewed file when work remains", () => {
+  assert.equal(wrapPrevTarget([3, 1, 4, 0, 2], finishedIn([2, 0])), 4, "guide order");
+  assert.equal(wrapPrevTarget([0, 1, 2, 3], finishedIn([3])), 2, "file order");
+});
+
+test("wrapPrevTarget cycles to the last file when everything is reviewed", () => {
+  assert.equal(wrapPrevTarget([3, 1, 4], finishedIn([3, 1, 4])), 4);
+});
+
+test("empty order yields no target", () => {
+  const none = finishedIn([]);
+  assert.equal(nextUnreviewed([], 0, none), null);
+  assert.equal(wrapNextTarget([], none), null);
+  assert.equal(wrapPrevTarget([], none), null);
+});

src/ui/seek.ts

@@ -0,0 +1,41 @@
+// Pure file-seek logic for wrap-around navigation. These operate on an explicit `order`
+// (file indices in nav order — guide order when a guide is attached, else the file array)
+// and a `finished` predicate ("this file is signed off in the current state"), so they're
+// unit-testable without the Alpine store. guide.ts holds the thin store-reading wrappers.
+
+// The next unreviewed file after `cur`, scanning `order` forward and wrapping past the end
+// back to the beginning. Used by approve-advance to seek remaining work instead of dead-ending.
+// `cur`'s own slot is never returned (a just-approved file counts as finished anyway, but the
+// wrap must not land back on the starting file). null when no unreviewed file remains anywhere.
+export function nextUnreviewed(
+  order: number[],
+  cur: number,
+  finished: (i: number) => boolean,
+): number | null {
+  const n = order.length;
+  if (!n) return null;
+  // `cur` may be absent from the order (a diff file not listed in the guide) — start scanning
+  // from the top of the order in that case (pos === -1 makes the first probe order[0]).
+  const pos = order.indexOf(cur);
+  for (let step = 1; step <= n; step++) {
+    const i = order[(pos + step) % n]!;
+    if (i === cur) continue;
+    if (!finished(i)) return i;
+  }
+  return null;
+}
+
+// The target when plain "next" steps off the LAST file in the order: the first unreviewed
+// file if any remains, else the first file (a plain cycle). null only when there are no files.
+export function wrapNextTarget(order: number[], finished: (i: number) => boolean): number | null {
+  if (!order.length) return null;
+  return order.find((i) => !finished(i)) ?? order[0]!;
+}
+
+// Mirror of wrapNextTarget for plain "prev" stepping off the FIRST position: the last
+// unreviewed file if any remains, else the last file.
+export function wrapPrevTarget(order: number[], finished: (i: number) => boolean): number | null {
+  if (!order.length) return null;
+  for (let i = order.length - 1; i >= 0; i--) if (!finished(order[i]!)) return order[i]!;
+  return order[order.length - 1]!;
+}